你已经装好了 OpenClaw，也配置了几个 Agent——intel 负责收集资讯，wechat 负责写文章，coder 负责写代码。每个 Agent 单独用都没问题。
但你很快发现一件事：它们互相不知道对方的存在。你得把 intel 的结果复制出来，再粘贴给 wechat，手动当它们之间的传话筒。
这篇教程就是写给这个阶段的人的——已经有多个 Agent 在跑，想让它们真正协同起来，不再靠人工中转。
0 核心概念：两种模式，不要混淆
OpenClaw 多 Agent 有两种根本不同的运行模式。混淆这两种模式是配置出错最常见的原因：
注意：群聊协作用的是持久 Agent；子 Agent 调用走的是 sessions_spawn。两者的配置字段完全不同，搞混了配置会直接失效或报错。
本教程介绍四种打破 Agent 隔离的通信工具：
方案一 群聊协作（最直观，今天就能用）
把多个持久 Agent 的 bot 拉进同一个群，通过 @ 提及来触发不同 Agent。每个 Agent 被触发时能读到群里的历史消息，包括其他 Agent 之前的回复——这就是上下文共享的原理。
配置：openclaw.json
{
"channels": {
"telegram": {
"groupPolicy": "allowlist",
"groups": { "allowlist": ["-100xxxxxxx"] }
},
"feishu": {
"requireMention": true
},
"slack": {
"channels": {
"C_YOUR_CHANNEL_ID": {
"allow": true,
"requireMention": true,
"allowBots": true
}
}
}
}
}注意：飞书和 Slack 必须设
requireMention: true，否则每条消息都触发，多个 Bot 会互相触发陷入死循环。
实际交互效果
你: @intel 最近 AI 行业有什么重要新闻？
intel: [回复 3 条重要新闻]
你: @wechat 把 intel 刚才说的第一条新闻写成公众号文章
wechat: [基于群里 intel 的回复，写出完整文章]
# 原理：wechat 被 @ 时，群历史消息全量进入其上下文窗口适合场景：日常协作、需要人工协调、透明度要求高的流程。
方案二 子 Agent 调用（最高效，最省钱）
主 Agent 通过 sessions_spawn 工具派生一个临时子 Agent，子 Agent 只把最终结论返回，中间过程不污染主 Agent 的会话历史。
sessions_spawn 完整参数
{
"task": "收集最近 7 天 AI 重要动态", // 必填
"label": "intel-daily", // 便于 /subagents list 识别
"agentId": "intel", // 指定哪个 Agent 执行
"model": "anthropic/claude-haiku-3.5",// 单次覆盖模型（省钱关键）
"thinking": "none", // 关闭扩展思考
"runTimeoutSeconds": 300, // 超时保护，5 分钟
"cleanup": "delete" // 完成后立即归档
}必须配置的权限白名单（最常见的坑）
注意：
allowAgents只能放在agents.list[]的具体 Agent 条目里，不能放 agents.defaults 里。放错位置会导致 Gateway 启动时配置校验报错崩溃
// ✅ 正确写法
{
"agents": {
"list": [
{
"id": "main",
"subagents": {
"allowAgents": ["intel", "wechat", "content-curator"]
// 或写 ["*"] 允许调用所有 Agent
}
}
]
}
}
// ❌ 错误写法——会导致 Gateway 启动崩溃
// "agents": { "defaults": { "subagents": { "allowAgents": [...] } } }两个重要冲突
agentToAgent.enabled: true与 sessions_spawn 冲突。同时开启时，子 Agent 会出现在 sessions 列表但 totalTokens 永远是 0，永不执行。二选一，不能同时用。
runTimeoutSeconds目前不能在 agents.defaults 里设全局默认值，必须在每次 sessions_spawn 调用里单独传入。忘记设的话子 Agent 跑飞了不会自动停。
子 Agent 的上下文注入（天然省钱）
子 Agent 系统提示比主 Agent 少注入多个文件，基础开销天然更低：
全局配置
{
"agents": {
"defaults": {
"subagents": {
"model": "anthropic/claude-haiku-3.5", // 子 Agent 默认便宜模型
"maxConcurrent": 8, // 全局并发上限
"archiveAfterMinutes": 60, // 完成后 60 分钟自动归档
"maxChildrenPerAgent": 5 // 每个 session 最多 5 个子 Agent
}
}
}
}嵌套子 Agent：三层流水线（进阶）
开启 maxSpawnDepth: 2 后，可实现「主 Agent → 编排子 Agent → 工作子 Agent」三层模式：
注意：社区反映嵌套子 Agent 行为有时不稳定。建议先用 maxSpawnDepth: 1 的单层模式验证后再尝试深度 2。
方案三 agentToAgent 持久 Agent 直接通信
sessions_send 工具允许持久 Agent 之间像打「内线电话」一样直接发消息，不需要用户在群里中转。适合「主管 + 专家」长期协作模式。
配置：必须显式开启
{
"tools": {
"agentToAgent": {
"enabled": true,
"allow": ["main", "intel", "wechat", "coder"]
}
}
}重要提醒：agentToAgent.enabled: true 与 sessions_spawn 冲突，两者不能同时使用。如果你还需要派生临时子 Agent，目前只能用方案二，暂时不要开 agentToAgent。
协作架构图
用户发指令 → 主管 Agent (main) 接收
↓
判断任务类型，sessions_send 分配给专家
↙ ↓ ↘
intel wechat coder
↘ ↓ ↙
主管 Agent 汇总结果 → 回复用户
方案四 共享文件协作（最低成本，全异步）
多个 Agent 通过读写共享目录里的文件传递信息，适合定时任务和异步场景。这是当前 Bug #5813 尚未修复期间最稳定的变通方案。
约定协议示例
# intel 的 AGENTS.md（写入端）
完成资讯收集后，写入：
- ~/clawd/shared/intel-latest.md → 最新资讯（每次覆盖）
- ~/clawd/shared/intel-to-wechat.md → 专门给 wechat 的素材
# wechat 的 AGENTS.md（读取端）
写作前：
1. 读取 ~/clawd/shared/intel-to-wechat.md
2. 检查文件时间戳：超过 6 小时标记为「陈旧」，提示用户确认配合 Cron 实现全自动流水线
# 每天 8:00 收集资讯
openclaw cron add --every 24h --at 08:00 --agent intel
"收集过去 24 小时 AI 动态，写入 ~/clawd/shared/intel-latest.md"
# 每天 9:00 写文章（intel 完成后）
openclaw cron add --every 24h --at 09:00 --agent wechat
"读取 ~/clawd/shared/intel-latest.md，写一篇公众号文章草稿"成功：早上 10 点你打开飞书，wechat 发来文章草稿。全程无需人工干预。
四种方案对比
注意：方案二（sessions_spawn）和方案三（agentToAgent）目前不能同时使用（Bug #5813）。选择前先想清楚你更需要哪个。
优先级速查表
从哪里开始
第一步 先试群聊协作——配置最简单，今天就能验证多 Agent 上下文共享是否生效
↓
第二步 确认群聊正常后，在 AGENTS.md 里加 sessions_spawn 规则（记得配 allowAgents）
↓
第三步 测试子 Agent 时，先不要开 agentToAgent，避免触发 Bug #5813
↓
第四步 基础流程跑通后，加 Cron + 共享文件实现全自动异步任务
提示：遇到奇怪的行为时，先升级 OpenClaw 版本，再用
/subagents list和/subagents log检查子 Agent 实际运行状态，而不是反复修改配置猜原因。
常见问题排查
问题一：@ 了没有任何反应
原因：飞书应用没有群聊消息权限
解决：进入飞书开放平台 → 找到你的应用 → 权限管理 → 开启 im:message.group_at_msg 权限，重新发布应用版本
问题二：群里只有一个 bot 响应，其他 bot 没动静
原因：这是正常行为
说明：飞书群里 @ 谁谁响应，没有被 @ 的 bot 不会动。这正是 requireMention: true 生效的表现，不是 bug。
问题三：多个 bot 同时响应，没有 @ 的也在说话
原因：requireMention 没有生效
解决：检查 openclaw.json，找到飞书频道配置，确认是否有这一行：
"feishu": {
"requireMention": true // 必须是 true，不能缺，不能是 false
}改完记得重启 Gateway 让配置生效。
