本书共 18 章，分为 4 大部分，全面讲解 OpenClaw 高级编程技术。第一部分深入 Agent 编排架构，包括多 Agent 通信协议、任务分解策略、状态同步机制；第二部分详解多模型适配，涵盖提供商抽象层、认证管理、动态切换策略；第三部分探讨高级策略，如故障转移、负载均衡、成本优化和缓存机制；第四部分聚焦生产实践，包括监控告警、性能调优、安全加固和灾难恢复。
智能体隔离 · 工作区设计 · 认证配置文件 · 会话存储 · 路由绑定
在 OpenClaw 中，一个智能体（Agent）是一个完全独立作用域的"大脑"，拥有自己的工作区、认证、会话历史和人格设定。多 Agent 系统允许在单个 Gateway 网关实例中并行运行多个隔离的智能体。
{
// 定义所有智能体
agents: {
list: [
{
id: "main",
name: "主智能体",
workspace: "~/.openclaw/workspace-main",
agentDir: "~/.openclaw/agents/main/agent",
model: "anthropic/claude-opus-4-5",
subagents: {
allowAgents: ["researcher", "writer"]
}
},
{
id: "researcher",
name: "调研员",
workspace: "~/.openclaw/workspace-researcher",
agentDir: "~/.openclaw/agents/researcher/agent",
model: "anthropic/claude-haiku-4-5"
},
{
id: "writer",
name: "写作助手",
workspace: "~/.openclaw/workspace-writer",
agentDir: "~/.openclaw/agents/writer/agent",
model: "openai/gpt-5.2"
}
]
},
// 入站消息路由规则
bindings: [
{
agentId: "main",
match: { channel: "feishu", accountId: "default" }
},
{
agentId: "researcher",
match: { channel: "telegram" }
}
]
}| 组件 | 默认路径 | 可配置项 | 用途 |
|---|---|---|---|
| 配置文件 | ~/.openclaw/openclaw.json |
OPENCLAW_CONFIG_PATH |
全局配置、agents.list、bindings |
| 状态目录 | ~/.openclaw |
OPENCLAW_STATE_DIR |
所有运行时数据根目录 |
| 工作区 | ~/.openclaw/workspace |
agents.list[].workspace |
AGENTS.md、SOUL.md、Skills、记忆文件 |
| 智能体目录 | ~/.openclaw/agents/<agentId>/agent |
agents.list[].agentDir |
auth-profiles.json、模型注册表 |
| 会话存储 | ~/.openclaw/agents/<agentId>/sessions |
自动派生 | 聊天历史、路由状态、压缩记录 |
认证配置文件（auth-profiles.json）存储 OAuth 令牌和 API 密钥，每个智能体从自己的位置读取：
{
profiles: {
anthropic:default: {
provider: "anthropic",
type: "setup-token",
token: "sk-ant-...",
createdAt: "2026-03-10T08:30:00Z"
},
openai:default: {
provider: "openai",
type: "oauth",
accessToken: "eyJhbGc...",
expiresAt: "2026-04-10T08:30:00Z"
}
}
}# 添加新智能体（自动创建 workspace 和 agentDir）
openclaw agents add researcher --workspace ~/.openclaw/workspace-researcher
# 验证添加成功
openclaw agents list
# 查看绑定状态
openclaw agents list --bindings
# 删除智能体（强制模式）
openclaw agents delete researcher --force# SOUL.md - 调研员
## 角色
我是调研助手，专注信息搜索、网页查询和内容整理。
## 职责
- 根据任务搜索和整理相关信息
- 输出结构清晰、有据可查的调研报告
- 不确定信息注明来源，不编造
## 风格
- 简洁客观，结论在前
- 数据来源标注清晰
- 避免主观臆断# AGENTS.md - 调研员
## 我是谁
我是主 Agent 的调研助手，不是主 Agent。
## 行为规范
### ✅ 收到任务直接执行
- 不反问，不问确认，直接干
- 模糊需求先做，做完再补充说明
### ✅ 输出格式
- 结论在前，细节在后
- 标注信息来源
### ❌ 禁止
- 不说"我是主 Agent"
- 不问"需要我创建子 Agent 吗"
- 不模仿主 Agent 的交互风格openclaw agents add 自动创建目录结构{
// ========== 智能体定义 ==========
agents: {
list: [
{
id: "main",
name: "主智能体",
default: true,
workspace: "~/.openclaw/workspace-main",
agentDir: "~/.openclaw/agents/main/agent",
model: "anthropic/claude-opus-4-5",
subagents: {
allowAgents: ["researcher", "writer", "coder"]
},
sandbox: {
mode: "off"
}
},
{
id: "researcher",
name: "调研员",
workspace: "~/.openclaw/workspace-researcher",
agentDir: "~/.openclaw/agents/researcher/agent",
model: "anthropic/claude-haiku-4-5",
sandbox: {
mode: "all",
scope: "agent"
},
tools: {
allow: ["web_search", "web_fetch", "read"],
deny: ["exec", "write", "browser"]
}
},
{
id: "writer",
name: "写作助手",
workspace: "~/.openclaw/workspace-writer",
agentDir: "~/.openclaw/agents/writer/agent",
model: "openai/gpt-5.2",
sandbox: {
mode: "non-main"
}
},
{
id: "coder",
name: "代码助手",
workspace: "~/.openclaw/workspace-coder",
agentDir: "~/.openclaw/agents/coder/agent",
model: "openai-codex/gpt-5.2-codex",
sandbox: {
mode: "off"
}
}
]
},
// ========== 路由绑定 ==========
bindings: [
{
agentId: "main",
match: { channel: "feishu", accountId: "default" }
},
{
agentId: "researcher",
match: { channel: "telegram" }
},
{
agentId: "writer",
match: {
channel: "whatsapp",
peer: { kind: "dm", id: "+8613800138000" }
}
},
{
agentId: "main",
match: { channel: "whatsapp" }
}
],
// ========== 渠道配置 ==========
channels: {
feishu: {
defaultAccount: "default",
accounts: {
default: {
appId: "cli_xxx",
appSecret: "xxx",
botName: "大橘"
}
}
},
whatsapp: {
dmPolicy: "allowlist",
allowFrom: ["+8613800138000", "+8613900139000"]
}
},
// ========== 工具权限 ==========
tools: {
agentToAgent: {
enabled: true,
allow: ["main", "researcher", "writer", "coder"]
}
}
}| 问题现象 | 可能原因 | 诊断命令 | 解决方案 |
|---|---|---|---|
| 子 Agent 自称"我是主 Agent" | 复制了主 Agent 的 AGENTS.md | cat workspace-researcher/AGENTS.md |
重写专属 AGENTS.md，明确"不是主 Agent" |
openclaw agents bind报错 |
此命令不存在 | - | 手动编辑bindings字段，不支持 CLI 绑定 |
config get agents.list报 path not found |
还未执行agents add |
openclaw agents list |
先执行agents add生成列表 |
| 飞书 Bot 响应"terminated" | 迁移时误删allowFrom等字段 |
python3 -c "import json; print(json.load(open('~/.openclaw/openclaw.json'))['channels']['feishu'])" |
从备份恢复，补回缺失字段 |
| 主 Agent 无法 spawn 子 Agent | 未配置subagents.allowAgents |
openclaw config get agents.list[0].subagents |
openclaw config set agents.list[0].subagents.allowAgents '["researcher"]' --json |
| Gateway 重启后无回复 | 不必要地执行了gateway restart |
openclaw gateway status |
配置支持热重载，无需重启 Gateway |