knowledge-base/4 - Resources/OpenClaw/OpenClaw 架构与配置全览.md

created, type, tags, source

created	type	tags	source
2026-03-22	resource	resource openclaw ai-gateway architecture reference homelab	https://docs.openclaw.ai/ 系统性整理

OpenClaw 架构与配置全览

概述

OpenClaw 是一个自托管 AI 网关，将 30+ 聊天渠道（WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Matrix, Teams 等）连接到 AI 编码代理。支持 35+ 模型提供商、多 agent 隔离路由、技能/插件扩展、定时任务和 webhook 自动化。

• 配置文件: ~/.openclaw/openclaw.json（JSON5 格式，热重载）
• 默认端口: 18789
• 文档: https://docs.openclaw.ai/

目录结构

~/.openclaw/
├── openclaw.json                    # 主配置文件
├── .env                             # 环境变量
├── workspace/                       # 默认 agent workspace
├── workspace-{agent-id}/            # 各 agent 独立 workspace
│   ├── AGENTS.md                    # 操作指令 + 记忆
│   ├── SOUL.md                      # 人格/边界/语气
│   ├── TOOLS.md                     # 工具使用说明
│   ├── IDENTITY.md                  # 名称/风格
│   ├── USER.md                      # 用户画像
│   ├── BOOTSTRAP.md                 # 一次性引导（运行后删除）
│   ├── MEMORY.md                    # 记忆
│   ├── HEARTBEAT.md                 # 心跳
│   ├── skills/                      # workspace 级技能（最高优先级）
│   │   └── skill-name/SKILL.md
│   └── hooks/                       # workspace 级钩子
├── agents/{agent-id}/
│   ├── agent/                       # agentDir: auth/model 配置
│   │   ├── auth-profiles.json
│   │   └── models.json
│   └── sessions/                    # 会话存储
│       ├── sessions.json
│       └── {session-id}.jsonl
├── skills/                          # managed 技能（中优先级）
│   └── skill-name/SKILL.md
├── hooks/                           # managed 钩子
├── plugins/                         # 已安装插件
├── browser/                         # 浏览器数据
└── xiaohongshu-mcp/                 # Docker 部署的 MCP 服务

关键区分: workspace vs agentDir

目录	用途	放什么
workspace-{id}/	agent 的工作目录	所有 .md 文件、skills/、hooks/
agents/{id}/agent/	agent 的状态目录	auth-profiles.json、models.json
agents/{id}/sessions/	会话存储	自动生成的 .jsonl 文件

重要: Bootstrap 文件（AGENTS.md, SOUL.md 等）必须放在 workspace 目录，不是 agentDir。agentDir 只放 JSON 配置文件。

Agent 配置

添加 Agent

{
  "agents": {
    "defaults": {
      "model": { "primary": "anthropic/claude-sonnet-4-6" },
      "workspace": "~/.openclaw/workspace"
    },
    "list": [
      {
        "id": "agent-id",
        "name": "agent-id",
        "workspace": "/home/yiukai/.openclaw/workspace-agent-id",
        "agentDir": "/home/yiukai/.openclaw/agents/agent-id/agent",
        "model": "kimi-coding/k2p5",
        "identity": { "name": "显示名称" },
        "groupChat": {
          "mentionPatterns": ["<@!?BOT_USER_ID>", "中文名称", "BOT_USER_ID"]
        },
        "subagents": {
          "allowAgents": ["other-agent-id"]
        }
      }
    ]
  }
}

Agent 间通信

默认禁用，需显式启用:

{
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": ["agent-a", "agent-b"]
    }
  }
}

渠道配置

Discord

{
  "channels": {
    "discord": {
      "enabled": true,
      "groupPolicy": "allowlist",
      "accounts": {
        "account-id": {
          "name": "显示名称",
          "enabled": true,
          "token": "BOT_TOKEN",
          "groupPolicy": "open",
          "streaming": "off",
          "guilds": {
            "GUILD_ID": {
              "requireMention": false,
              "users": ["OWNER_ID", "BOT_ID"],
              "channels": { "CHANNEL_ID": { "allow": true } }
            }
          }
        }
      }
    }
  }
}

DM 策略

策略	说明
pairing	需要配对码（默认）
allowlist	仅允许指定用户
open	允许所有
disabled	禁用 DM

Bot 必需权限

View Channels, Send Messages, Read Message History, Embed Links, Attach Files

Bot 必需 Intent

Message Content Intent（必须），Server Members Intent（推荐）

路由绑定 (Bindings)

将消息路由到特定 agent:

{
  "bindings": [
    {
      "agentId": "agent-id",
      "match": {
        "channel": "discord",
        "accountId": "account-id"
      }
    }
  ]
}

匹配优先级: peer > parent-peer > guild+roles > guild > team > account > channel > default

Skills 技能系统

加载优先级（高到低）

1. Workspace skills: <workspace>/skills/skill-name/SKILL.md
2. Managed skills: ~/.openclaw/skills/skill-name/SKILL.md
3. Bundled skills: 内置技能

SKILL.md 格式

---
name: skill-name
description: "一行描述"
homepage: https://example.com
metadata: { "openclaw": { "emoji": "📕", "requires": { "bins": ["curl"] } } }
---

# 技能说明

工具定义和使用指南...

技能配置

{
  "skills": {
    "entries": {
      "skill-name": { "enabled": true },
      "other-skill": { "enabled": true, "apiKey": "..." }
    },
    "load": { "extraDirs": [], "watch": true }
  }
}

Plugins 插件系统

安装

openclaw plugins install plugin-name          # 从 npm
openclaw plugins install -l ./local-plugin    # 从本地

插件能力注册

能力	注册方法
文本推理	api.registerProvider(...)
语音	api.registerSpeechProvider(...)
图片生成	api.registerImageGenerationProvider(...)
网络搜索	api.registerWebSearchProvider(...)
消息渠道	api.registerChannel(...)

MCP 适配器插件

openclaw-mcp-adapter 将 MCP 服务器工具注册为原生 agent 工具:

{
  "plugins": {
    "entries": {
      "openclaw-mcp-adapter": {
        "enabled": true,
        "config": {
          "servers": [
            {
              "name": "server-name",
              "transport": "http",
              "url": "http://localhost:18060/mcp"
            }
          ]
        }
      }
    }
  }
}

支持 stdio（启动子进程）和 http（连接运行中的服务）两种传输方式。

Hooks 钩子系统

事件类型

事件	触发时机
command:new	/new 命令
command:reset	/reset 命令
command:stop	/stop 命令
message:received	收到消息
message:sent	发送消息
agent:bootstrap	Agent 启动
gateway:startup	Gateway 启动

内置钩子

钩子	功能
session-memory	/new 时保存上下文快照
bootstrap-extra-files	启动时注入额外文件
command-logger	命令审计日志
boot-md	启动时执行 BOOT.md

Cron 定时任务

{
  "cron": {
    "enabled": true,
    "entries": [
      {
        "name": "job-name",
        "schedule": "0 8 * * 1-5",
        "timezone": "Europe/Stockholm",
        "agentId": "agent-id",
        "message": "执行任务",
        "deliver": {
          "channel": "discord",
          "target": "channel:CHANNEL_ID"
        }
      }
    ]
  }
}

Subagents 子代理

后台生成独立会话执行任务，完成后报告结果。

{
  "agents": {
    "defaults": {
      "subagents": {
        "maxSpawnDepth": 1,
        "maxConcurrent": 8,
        "runTimeoutSeconds": 300,
        "allowAgents": ["*"]
      }
    }
  }
}

命令: /subagents list|info|log|kill|spawn|send

Session 会话管理

作用域

模式	说明
main	每个 agent 单一 session
per-peer	每个发送者独立
per-channel-peer	每个渠道+发送者独立
per-account-channel-peer	完全隔离

重置

{
  "session": {
    "reset": {
      "mode": "idle",
      "idleMinutes": 120
    }
  }
}

Gateway 配置

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "auth": { "mode": "token", "token": "..." },
    "controlUi": { "enabled": true },
    "http": {
      "endpoints": {
        "chatCompletions": { "enabled": false },
        "responses": { "enabled": false }
      }
    }
  }
}

热重载

三种模式:

• hybrid（默认）: 安全变更即时生效，关键变更自动重启
• hot: 仅安全变更生效，关键变更需手动重启
• restart: 任何变更都重启

Webhook (外部触发)

{
  "hooks": {
    "enabled": true,
    "token": "shared-secret",
    "path": "/hooks"
  }
}

端点:

• POST /hooks/wake - 入队系统事件
• POST /hooks/agent - 运行隔离的 agent turn
• POST /hooks/<name> - 自定义映射钩子

环境变量

{
  "env": {
    "API_KEY": "value",
    "NODE_TLS_REJECT_UNAUTHORIZED": "0"
  }
}

支持 ${VAR_NAME} 语法引用环境变量，支持 SecretRef 对象（env/file/exec 来源）。

诊断命令

openclaw doctor [--fix]          # 诊断并修复
openclaw status --deep           # 完整状态审计
openclaw config validate         # 配置校验
openclaw channels status --probe # 渠道连通性检查
openclaw gateway probe           # Gateway 连通性检查
openclaw logs --follow           # 尾随日志

Related

• OpenClaw-Skill-Reference
• OpenClaw 部署配置分析
• OpenClaw Stock Agent 配置详情
• OpenClaw Agent 创建指南