乐于分享
好东西不私藏

OpenClaw 多 Agent 部署操作指南

OpenClaw 多 Agent 部署操作指南
昨天写了一篇关于 一人公司的AI组织架构:OpenClaw 9角色部署复盘的文章。今天我把部署操作步骤分享出来。希望能够帮助更多感兴趣的伙伴「结尾提供原始文档」

基于 9 Agent 实战部署经验提炼,适用于任何业务场景的 OpenClaw 多 Agent 部署。


目录

  1. 架构总览
  2. 前置条件
  3. Phase 1:设计 Agent 角色
  4. Phase 2:创建 Workspace 文件
  5. Phase 3:从单 Agent 升级到多 Agent
  6. Phase 4:飞书多机器人配置
  7. Phase 5:注册与绑定
  8. Phase 6:验证与测试
  9. 常见问题排查
  10. 运维速查表

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. 前置条件

项目
要求
操作系统
Ubuntu 22.04+ / macOS / Windows
OpenClaw
已安装并完成 openclaw onboard
飞书
已有企业飞书账号,开放平台可创建应用
现有状态
至少 1 个 Agent(main)已在运行
LLM API
已配置模型(如 zai/glm-4.7),注意 API 频率限制

确认当前环境

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 角色映射表(示例)

Agent ID
角色名称
核心职责
main
总经理/调度中枢
调度 + 经营决策拆解
sales-growth
增长负责人
获客 + 引流
customer-success
客户成功官
客户交付 + 续费
finance
财务分析官
财务分析 + 预算
...
...
...

4. Phase 2:创建 Workspace 文件

4.1 每个 Agent 需要 5 个核心文件

文件
用途
要点
SOUL.md
灵魂/系统指令
定位、职责、原则、边界、输出格式
IDENTITY.md
身份卡片
名称、角色、风格
TOOLS.md
业务知识注入
价格体系、KPI、业务流程等
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 $ROLESdo  WS="$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/null  cp "$OC/workspace/USER.md" "$WS/USER.md" 2>/dev/null  echo "✅ 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,在 飞书开放平台 执行:

步骤
操作
注意事项
1
创建企业自建应用
取名与角色一致
2
凭证与基础信息 → 复制 App ID 和 App Secret
妥善保管
3
权限管理 → 添加权限(见 6.2)
不要遗漏
4
事件与回调 → 订阅方式选「长连接」
不需要公网服务器
5
事件与回调 → 添加 im.message.receive_v1
最易遗漏
6
应用功能 → 机器人 → 开启
7
版本管理与发布 → 创建版本 → 发布
不发布不生效

6.2 必需权限清单

im:messageim:message:send_as_botim:message.group_at_msg:readonlyim:message.p2p_msg:readonlycontact:contact.base:readonly

[!CAUTION] 三个最常见的遗漏:

  1. 忘了添加 im.message.receive_v1 事件 → 机器人收不到消息
  2. 添加权限/事件后忘了发布新版本 → 不会生效
  3. 缺少 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
session 损坏
清 session + 重启
权限错误
99991672
缺少飞书权限
添加权限 + 发布新版本
API 限流
429 Rate limit
并发调用过多
降低 maxConcurrent 或等待
bindings 报错
Invalid input
手写格式错误
用 openclaw agents bind 命令
新账号连不上
只有 feishu[main]
未更新 accounts.json
同步更新两个文件

清 session 重启

# 清单个 Agentfind ~/.openclaw/agents/<agent-id>/sessions/ -type f -delete# 清全部find ~/.openclaw/agents/*/sessions/ -type f -delete# 重启openclaw gateway restart

10. 运维速查表

日常命令

命令
用途
openclaw agents list
查看所有 Agent
openclaw agents list --bindings
查看路由绑定
openclaw channels status --probe
查看通道健康
openclaw logs --follow
实时日志
openclaw gateway restart
重启 Gateway

关键文件路径

文件
路径
说明
主配置
~/.openclaw/openclaw.json
Agent 列表、通道、绑定
飞书账号(运行时)
~/.openclaw/channels/feishu/accounts.json必须同步更新
Agent workspace
~/.openclaw/workspace-<id>/
5 个核心 .md 文件
Agent sessions
~/.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

觉得有启发?点个「在看」或转发给同样在做 AI 自动化的朋友。喜欢请关注
回复 「龙虾手册」获取部署原始文档链接。