1. 从单 Agent 到多 Agent卡住的地方到底在哪OpenClaw 多 Agent 部署这件事真正让人卡住的往往不是“怎么装”而是“装完之后怎么让多个 Agent 各干各的、还能互相喊得动”。单 Agent 的时候一个workspace目录、一个飞书机器人跑起来就完事一旦要拆成“调度中枢 增长 交付 财务”这种结构配置文件立刻从十几行膨胀到上百行飞书那边还要为每个 Agent 单独建应用、配权限、发版本任何一环漏了表现都是“机器人不回消息”。这篇就聚焦两件事openclaw.json的配置骨架怎么搭以及飞书多机器人怎么接进来并验证成功。适合已经跑通单 Agent、准备往多 Agent 协作升级的人。核心检索词先摆出来OpenClaw 多 Agent 部署、openclaw.json 配置、飞书接入。读完你应该能拿到一份可复制的配置片段并且知道每个字段为什么这么写。先说清楚一个心智模型后面所有配置都围绕它展开1 个飞书应用 1 个飞书机器人 1 个 OpenClaw Account1 个 Account 通过 binding 绑定到 1 个 Agentmain Agent 是默认路由没匹配上的消息都走它main 可以通过 spawn 实时调度其他 Agent。这个模型一旦立住openclaw.json里那些agents.list、channels.feishu.accounts、tools.agentToAgent就不再是零散字段而是这条链路上的三个环节。下面按“前置检查 → 配置骨架 → 飞书接入 → 验证 → 排障”的顺序走一遍。2. 动手前先把环境和现状摸清楚在改任何配置之前先确认当前处于什么状态。很多人一上来就手写 JSON结果改完发现根本没生效其实是没搞清楚运行时到底读的是哪个文件。先跑三条命令看现状openclaw agents list openclaw channels status --probe cat ~/.openclaw/openclaw.json第一条列出当前所有 Agent第二条探测通道健康度第三条把主配置打印出来。如果agents list里只有一个 main说明你还在单 Agent 模式正好从这篇开始升级。环境上需要满足Ubuntu 22.04 / macOS / Windows 任一OpenClaw 已安装并完成openclaw onboard飞书有企业账号开放平台能创建自建应用至少一个 LLM API 已配好模型比如zai/glm-4.7并且注意 API 频率限制多 Agent 并发时很容易撞到 429。这里有个容易被忽略的点OpenClaw 的配置其实分两层。~/.openclaw/openclaw.json是主配置管 Agent 列表、通道、绑定而~/.openclaw/channels/feishu/accounts.json是飞书账号的运行时文件。两个都要改只改一个会出现“配置看着对但飞书连不上”的诡异现象。后面第 4 节会专门讲这个坑。3. openclaw.json 配置骨架从 defaults 到 agents.list3.1 单 Agent 的原始形态单 Agent 模式下配置里通常只有一段agents: { defaults: { workspace: /home/user/.openclaw/workspace } }defaults.workspace是全局默认工作目录所有 Agent 没单独指定时都用它。问题在于多 Agent 场景下每个 Agent 需要独立的记忆、技能和产出目录共享一个 workspace 会互相污染。3.2 升级为多 Agent 骨架升级的关键动作是删掉defaults.workspace改成agents.list数组每个 Agent 显式声明自己的workspace。下面是一份可直接复制的骨架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 } } } ] }几个字段值得单独说。default: true标记默认路由 Agent有且只有一个subagents.allowAgents控制这个 Agent 能调度谁[*]表示不限制heartbeat.every是自主运行节拍main 设 6 小时、执行型 Agent 设 24 小时比较合理activeHours限定活跃时段避免半夜乱跑。3.3 打开跨 Agent 调用权限光有 list 还不够Agent 之间要能互相调用得显式开权限tools: { agentToAgent: { enabled: true, allow: [main, content-growth, wechat-conversion] } }allow数组里列出允许参与互调的 Agent id。建议用脚本生成避免手写漏项node -e const fs require(fs); const p process.env.HOME /.openclaw/openclaw.json; const config JSON.parse(fs.readFileSync(p, utf8)); config.tools config.tools || {}; config.tools.agentToAgent { enabled: true, allow: config.agents.list.map(a a.id) }; fs.writeFileSync(p, JSON.stringify(config, null, 2)); console.log(agentToAgent allow , config.tools.agentToAgent.allow.join(,)); 跑完打印出所有 Agent id说明权限已同步。3.4 每个 Agent 的 workspace 要放什么配置指向的 workspace 目录不是空的每个 Agent 至少需要 5 个核心文件文件用途要点SOUL.md灵魂/系统指令定位、职责、原则、边界、输出格式IDENTITY.md身份卡片名称、角色、风格TOOLS.md业务知识注入价格体系、KPI、业务流程HEARTBEAT.md自主运行节拍定时任务、巡检规则MEMORY.md长期记忆模板经验、决策记录批量创建目录可以这样写OC~/.openclaw SRC/path/to/source ROLEScontent-growth wechat-conversion delivery-upgrade for role in $ROLES; do 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/ echo workspace-$role 创建完成 donemain Agent 的 SOUL.md 里必须显式写清调度方式否则它会默认走异步 inbox 模式写文件等领取而不是实时 spawn。这一点我在实际部署里踩过表现是“让它调增长官结果半天没动静”后来才发现是 SOUL.md 没写调度规则。注意如果 SOUL.md 不显式写明“直接 spawn”Agent 会默认使用异步 inbox 模式而非实时调用。4. 飞书多机器人接入应用、权限、绑定三步走4.1 为每个 Agent 创建飞书应用在飞书开放平台对每个新 Agent 执行一遍创建企业自建应用取名与角色一致凭证与基础信息里复制 App ID 和 App Secret 并妥善保管权限管理里添加权限事件与回调订阅方式选「长连接」不需要公网服务器事件与回调里添加im.message.receive_v1这是最容易漏的一步应用功能里开启机器人版本管理与发布里创建版本并发布不发布不生效。必需权限清单im:message im:message:send_as_bot im:message.group_at_msg:readonly im:message.p2p_msg:readonly contact:contact.base:readonly三个最常见的漏配忘了加im.message.receive_v1事件机器人收不到消息加了权限和事件却忘了发布新版本不会生效缺少contact:contact.base:readonly日志会报 99991672 错误。4.2 注册与绑定脚本拿到 appId/appSecret 后两个配置文件都要更新然后绑定路由、重启AGENT_IDcontent-growth APP_IDcli_xxxxxx APP_SECRETxxxxxx # 1. 更新 openclaw.json node -e const fs require(fs); const p process.env.HOME /.openclaw/openclaw.json; const config JSON.parse(fs.readFileSync(p, utf8)); config.channels.feishu.accounts[$AGENT_ID] { appId: $APP_ID, appSecret: $APP_SECRET }; fs.writeFileSync(p, JSON.stringify(config, null, 2)); console.log(openclaw.json updated); # 2. 更新运行时 accounts.json关键 node -e const fs require(fs); const p process.env.HOME /.openclaw/channels/feishu/accounts.json; const acc JSON.parse(fs.readFileSync(p, utf8)); acc.accounts[$AGENT_ID] { appId: $APP_ID, appSecret: $APP_SECRET }; fs.writeFileSync(p, 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重要openclaw.json和~/.openclaw/channels/feishu/accounts.json两个文件都必须更新。只改一个会导致飞书连接不上。绑定这一步不要手写 bindings JSON格式很容易错始终用openclaw agents bind命令。5. 验证请求从直接对话到多 Agent 协作配置改完用三个测试逐层验证。测试一直接对话。在飞书里 某个机器人或私聊“你是谁”验证点是回复包含 SOUL.md 里定义的角色名称和职责。如果没回复先看第 6 节排障。测试二单 Agent 调度。私聊 main“直接调用增长负责人出 3 个围绕核心用户痛点的内容选题。”验证点是 main 通过 spawn 调用 content-growth返回完整结果。如果 main 只是自己答了说明tools.agentToAgent没生效或 SOUL.md 没写调度规则。测试三多 Agent 协作。私聊 main“请立即调用以下 Agent1. 增长负责人出 3 条引流选题2. 客户成功官设计新客户欢迎话术。汇总结果给我。”验证点是 main 并行 spawn汇总后一次性回复。这一步可能触发 API 限流注意观察日志。验证绑定和通道状态openclaw agents list --bindings openclaw channels status --probe第一条确认路由规则第二条确认连接状态。两条都正常说明飞书接入成功。6. 本篇常见错排查日志是排查的第一入口openclaw logs --follow对照下面这张速查表定位问题现象日志关键词原因解决方案群消息不回复did not mention bot未 机器人群里必须 新机器人完全无响应无 feishu[xxx] 记录未订阅 im.message.receive_v1开放平台添加事件 发布收到消息但不回复replies0session 卡死清 session 重启权限错误99991672缺少飞书权限添加权限 发布新版本API 限流429 Rate limit并发调用过多降低 maxConcurrent 或等待bindings 报错Invalid input手写格式错误用 openclaw agents bind新账号连不上只有 feishu[main]未更新 accounts.json同步更新两个文件清 session 重启用这几条# 清单个 Agent find ~/.openclaw/agents/agent-id/sessions/ -type f -delete # 清全部 find ~/.openclaw/agents/*/sessions/ -type f -delete # 重启 openclaw gateway restart日常运维记住这几个命令和路径命令用途openclaw agents list查看所有 Agentopenclaw agents list --bindings查看路由绑定openclaw channels status --probe查看通道健康openclaw logs --follow实时日志openclaw gateway restart重启 Gateway文件路径说明~/.openclaw/openclaw.json主配置Agent 列表、通道、绑定~/.openclaw/channels/feishu/accounts.json飞书账号运行时必须同步更新~/.openclaw/workspace- /Agent workspace5 个核心 .md~/.openclaw/agents/ /sessions/Agent 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验证 → 飞书群测试对话。7. 模型接入与长期编码的配套选择多 Agent 跑起来之后模型调用量会明显上升尤其是 main 频繁 spawn 其他 Agent 时。这时候如果模型接入不稳定整个协作链路都会抖。我自己的做法是把模型接入统一走一个兼容层避免每个 Agent 各自配一套 key 和 endpoint。TaoToken 在这里的角色就是提供统一的模型接入入口支持对话、编码等多种调用方式。你可以先到 TaoToken 模型对话 验证模型是否可用确认没问题后再把 key 配到 OpenClaw 的模型配置里。具体操作路径先到 API Keys 管理页 创建 key然后参考 接入文档 把 endpoint 和 key 填进agents.defaults.model。如果只是排障和接入验证走 API Keys 接入文档这条线就够了。如果你的多 Agent 场景偏长期编码、Agent 持续运行比如让某个 Agent 专门负责代码生成和重构那更适合用 Coding Plan它在长会话和编码任务上的配额更友好。控制台入口在 Console可以统一看调用情况。配置模型时有个细节agents.defaults.model.primary填的是模型标识比如zai/glm-4.7如果你的接入层用的是自定义 endpoint需要在 OpenClaw 的 provider 配置里对应改掉 base URL。改完记得openclaw gateway restart然后跑一次测试一确认模型响应正常。最后留一个实操建议多 Agent 部署最容易出问题的不是配置本身而是“改了一个文件忘了另一个”。每次动完openclaw.json顺手确认accounts.json是否同步再跑一遍openclaw channels status --probe。这个习惯能省掉大半的排障时间。