--- created: "2026-03-22" type: resource tags: [resource, openclaw, ai-gateway, architecture, reference, homelab] source: "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 ```json { "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 间通信 默认禁用，需显式启用: ```json { "tools": { "agentToAgent": { "enabled": true, "allow": ["agent-a", "agent-b"] } } } ``` ## 渠道配置 ### Discord ```json { "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: ```json { "bindings": [ { "agentId": "agent-id", "match": { "channel": "discord", "accountId": "account-id" } } ] } ``` 匹配优先级: peer > parent-peer > guild+roles > guild > team > account > channel > default ## Skills 技能系统 ### 加载优先级（高到低） 1. **Workspace skills**: `/skills/skill-name/SKILL.md` 2. **Managed skills**: `~/.openclaw/skills/skill-name/SKILL.md` 3. **Bundled skills**: 内置技能 ### SKILL.md 格式 ```markdown --- name: skill-name description: "一行描述" homepage: https://example.com metadata: { "openclaw": { "emoji": "📕", "requires": { "bins": ["curl"] } } } --- # 技能说明 工具定义和使用指南... ``` ### 技能配置 ```json { "skills": { "entries": { "skill-name": { "enabled": true }, "other-skill": { "enabled": true, "apiKey": "..." } }, "load": { "extraDirs": [], "watch": true } } } ``` ## Plugins 插件系统 ### 安装 ```bash 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 工具: ```json { "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 定时任务 ```json { "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 子代理 后台生成独立会话执行任务，完成后报告结果。 ```json { "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` | 完全隔离 | ### 重置 ```json { "session": { "reset": { "mode": "idle", "idleMinutes": 120 } } } ``` ## Gateway 配置 ```json { "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 (外部触发) ```json { "hooks": { "enabled": true, "token": "shared-secret", "path": "/hooks" } } ``` 端点: - `POST /hooks/wake` - 入队系统事件 - `POST /hooks/agent` - 运行隔离的 agent turn - `POST /hooks/` - 自定义映射钩子 ## 环境变量 ```json { "env": { "API_KEY": "value", "NODE_TLS_REJECT_UNAUTHORIZED": "0" } } ``` 支持 `${VAR_NAME}` 语法引用环境变量，支持 SecretRef 对象（env/file/exec 来源）。 ## 诊断命令 ```bash 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 创建指南]]