
基于 9 Agent 实战部署经验提炼,适用于任何业务场景的 OpenClaw 多 Agent 部署。
目录
架构总览 前置条件 Phase 1:设计 Agent 角色 Phase 2:创建 Workspace 文件 Phase 3:从单 Agent 升级到多 Agent Phase 4:飞书多机器人配置 Phase 5:注册与绑定 Phase 6:验证与测试 常见问题排查 运维速查表
1. 架构总览
┌─────────────────────────────────────────────────┐│ 飞书群 ││ 机器人A(main) 机器人B(agent-2) 机器人C(...) │└──────┬──────────────┬──────────────┬─────────────┘│ │ │▼ ▼ ▼┌─────────────────────────────────────────────────┐│ OpenClaw Gateway ││ accounts.json ← 飞书账号注册 ││ openclaw.json ← Agent 列表 + 路由绑定 │└──────┬──────────────┬──────────────┬─────────────┘│ │ │▼ ▼ ▼workspace/ workspace-agent2/ workspace-agent3/(main Agent) (Agent 2) (Agent 3)
核心概念:
1 个飞书应用 = 1 个飞书机器人 = 1 个 OpenClaw Account 1 个 Account 通过 binding 绑定到 1 个 Agent main Agent 是默认路由,未匹配的消息都走 main main 可通过 spawn 实时调度其他 Agent
2. 前置条件
openclaw onboard | |
确认当前环境:
openclaw agents listopenclaw channels status --probecat ~/.openclaw/openclaw.json
3. Phase 1:设计 Agent 角色
3.1 角色设计原则
Agent 即部门:每个 Agent 代表一个独立职能部门 职责不重叠:明确边界,避免多个 Agent 做同一件事 调度中枢唯一:只有 1 个 main Agent 做调度,其他 Agent 专注执行 可独立运作:每个 Agent 有自己的记忆、节奏、产出标准
3.2 角色映射表(示例)
4. Phase 2:创建 Workspace 文件
4.1 每个 Agent 需要 5 个核心文件
SOUL.md | ||
IDENTITY.md | ||
TOOLS.md | ||
HEARTBEAT.md | ||
MEMORY.md |
4.2 main Agent 的 SOUL.md 必须包含调度方式
## 调度方式**实时调度(默认)**:当 CEO 要求"让 XX 做某事"或你判断任务需要立即执行时,**直接 spawn 对应 Agent**,等待其返回结果后汇总给 CEO。不要写文件等领取。**异步任务**:仅当 CEO 明确说"不急""下周做""排进计划"时,才写入 work/inbox/ 文件。spawn 调用要点:- 给被调度 Agent 的指令必须清晰:目标、约束条件、交付物格式- 多 Agent 协同时,可并行 spawn 多个 Agent,汇总后统一回复 CEO- spawn 返回后,对结果做质量把关,不达标时要求重做
[!WARNING] 如果 SOUL.md 不显式写明"直接 spawn",Agent 会默认使用异步 inbox 模式(写文件等领取),而非实时调用。
4.3 批量创建 Workspace 目录
OC=~/.openclawSRC=/path/to/source # 你的 workspace 文件所在目录ROLES="content-growth wechat-conversion delivery-upgrade"for role in $ROLES; doWS="$OC/workspace-$role"mkdir -p "$WS"/{memory,skills,work/{inbox,drafts,archives,output/{reports,content,data,plans},runtime/{state,scripts,cache}}}cp "$SRC/workspace-$role"/{SOUL.md,IDENTITY.md,TOOLS.md,HEARTBEAT.md,MEMORY.md} "$WS/"cp "$OC/workspace/AGENTS.md" "$WS/AGENTS.md" 2>/dev/nullcp "$OC/workspace/USER.md" "$WS/USER.md" 2>/dev/nullecho "✅ workspace-$role 创建完成"done
5. Phase 3:从单 Agent 升级到多 Agent
5.1 修改 openclaw.json
从单 Agent 模式(只有 agents.defaults.workspace):
"agents": {"defaults": {"workspace": "/home/user/.openclaw/workspace"}}
升级为多 Agent 模式(删掉 defaults.workspace,加 agents.list):
"agents": {"defaults": {"model": { "primary": "zai/glm-4.7" },"compaction": { "mode": "safeguard" },"maxConcurrent": 4,"subagents": { "maxConcurrent": 8 }},"list": [{"id": "main","name": "CEO经营参谋官","default": true,"workspace": "/home/user/.openclaw/workspace","subagents": { "allowAgents": ["*"] },"heartbeat": {"every": "6h","activeHours": { "start": "09:00", "end": "22:00", "timezone": "Asia/Shanghai" }}},{"id": "content-growth","name": "公域内容增长官","workspace": "/home/user/.openclaw/workspace-content-growth","subagents": { "allowAgents": ["*"] },"heartbeat": {"every": "24h","activeHours": { "start": "09:00", "end": "22:00", "timezone": "Asia/Shanghai" }}}]}
5.2 添加跨 Agent 调用权限
"tools": {"agentToAgent": {"enabled": true,"allow": ["main", "content-growth", "wechat-conversion"]}}
5.3 用 Node 脚本批量添加(推荐)
node -e "const fs = require('fs');const config = JSON.parse(fs.readFileSync(process.env.HOME+'/.openclaw/openclaw.json','utf8'));const newAgents = [{ id: 'content-growth', name: '公域内容增长官', every: '24h' },{ id: 'wechat-conversion', name: '企微前端转化官', every: '24h' }];for (const a of newAgents) {if (!config.agents.list.find(x => x.id === a.id)) {config.agents.list.push({id: a.id, name: a.name,workspace: process.env.HOME+'/.openclaw/workspace-'+a.id,subagents: { allowAgents: ['*'] },heartbeat: { every: a.every, activeHours: { start: '09:00', end: '22:00', timezone: 'Asia/Shanghai' } }});}}config.tools = config.tools || {};config.tools.agentToAgent = { enabled: true, allow: config.agents.list.map(a => a.id) };fs.writeFileSync(process.env.HOME+'/.openclaw/openclaw.json', JSON.stringify(config, null, 2));"
6. Phase 4:飞书多机器人配置
6.1 为每个 Agent 创建飞书应用
对每个新 Agent,在 飞书开放平台 执行:
im.message.receive_v1 | 最易遗漏 | |
| 不发布不生效 |
6.2 必需权限清单
im:messageim:message:send_as_botim:message.group_at_msg:readonlyim:message.p2p_msg:readonlycontact:contact.base:readonly
[!CAUTION] 三个最常见的遗漏:
忘了添加 im.message.receive_v1事件 → 机器人收不到消息添加权限/事件后忘了发布新版本 → 不会生效 缺少 contact:contact.base:readonly→ 日志报 99991672 错误
7. Phase 5:注册与绑定
7.1 完整注册脚本
每拿到一个新的 appId/appSecret,执行:
AGENT_ID="content-growth"APP_ID="cli_xxxxxx"APP_SECRET="xxxxxx"# 1. 更新 openclaw.jsonnode -e "const fs = require('fs');const config = JSON.parse(fs.readFileSync(process.env.HOME+'/.openclaw/openclaw.json','utf8'));config.channels.feishu.accounts['$AGENT_ID'] = { appId: '$APP_ID', appSecret: '$APP_SECRET' };fs.writeFileSync(process.env.HOME+'/.openclaw/openclaw.json', JSON.stringify(config,null,2));console.log('✅ openclaw.json updated');"# 2. 更新运行时 accounts.json(关键!)node -e "const fs = require('fs');const acc = JSON.parse(fs.readFileSync(process.env.HOME+'/.openclaw/channels/feishu/accounts.json','utf8'));acc.accounts['$AGENT_ID'] = { appId: '$APP_ID', appSecret: '$APP_SECRET' };fs.writeFileSync(process.env.HOME+'/.openclaw/channels/feishu/accounts.json', JSON.stringify(acc,null,2));console.log('✅ accounts.json updated');"# 3. 绑定路由openclaw agents bind --agent $AGENT_ID --bind feishu:$AGENT_ID# 4. 重启openclaw gateway restart
[!IMPORTANT] >
openclaw.json和~/.openclaw/channels/feishu/accounts.json两个文件都必须更新。只改一个会导致飞书连接不上。
7.2 验证
openclaw agents list --bindings # 确认路由规则openclaw channels status --probe # 确认连接状态
[!TIP] 不要手写 bindings JSON,容易格式错误。始终使用
openclaw agents bind命令。
8. Phase 6:验证与测试
测试 1:直接对话
@ 某个机器人或私聊:你是谁?
验证点:回复包含 SOUL.md 中定义的角色名称和职责。
测试 2:单 Agent 调度
私聊 main:
直接调用增长负责人,出3个围绕核心用户痛点的内容选题。验证点:main 通过 spawn 调用 content-growth,返回完整结果。
测试 3:多 Agent 协作
请立即调用以下Agent:1. 增长负责人:出3条引流选题2. 客户成功官:设计新客户欢迎话术汇总结果给我。
验证点:main 并行 spawn,汇总后一次性回复。注意可能触发 API 限流。
9. 常见问题排查
查看日志
openclaw logs --follow问题速查表
did not mention bot | |||
feishu[xxx] 记录 | im.message.receive_v1 | ||
replies=0 | |||
99991672 | |||
429 Rate limit | |||
Invalid input | openclaw agents bind 命令 | ||
feishu[main] |
清 session 重启
# 清单个 Agentfind ~/.openclaw/agents/<agent-id>/sessions/ -type f -delete# 清全部find ~/.openclaw/agents/*/sessions/ -type f -delete# 重启openclaw gateway restart
10. 运维速查表
日常命令
openclaw agents list | |
openclaw agents list --bindings | |
openclaw channels status --probe | |
openclaw logs --follow | |
openclaw gateway restart |
关键文件路径
~/.openclaw/openclaw.json | ||
~/.openclaw/channels/feishu/accounts.json | 必须同步更新 | |
~/.openclaw/workspace-<id>/ | ||
~/.openclaw/agents/<id>/sessions/ |
添加新 Agent 完整清单
[ ] 设计 5 个 workspace 文件 [ ] 创建 workspace 目录结构 [ ] 添加到 openclaw.json的agents.list[ ] 更新 tools.agentToAgent.allow[ ] 飞书开放平台创建应用(权限 + 事件 + 发布) [ ] 更新 openclaw.json的channels.feishu.accounts[ ] 更新 channels/feishu/accounts.json[ ] 执行 openclaw agents bind[ ] 执行 openclaw gateway restart[ ] 执行 openclaw channels status --probe验证[ ] 飞书群测试对话
手册版本: v1.0 | 基于 OpenClaw 2026.3.28
夜雨聆风