{"skill":{"slug":"openclaw-feishu-multi-agent","displayName":"OpenClaw Feishu Multi-Agent","summary":"Build and troubleshoot OpenClaw multi-agent workflows on Feishu. This skill teaches coordinator and specialist agents to combine visible `<at>` mentions with...","description":"---\nname: openclaw-feishu-multi-agent\ndescription: Build and troubleshoot OpenClaw multi-agent workflows on Feishu. This skill teaches coordinator and specialist agents to combine visible `<at>` mentions with `sessions_send` so delegation, handoffs, and multi-hop discussions work reliably in group chats. Use it to scaffold new setups, audit existing configs, repair broken session metadata, and generate reusable role-based artifacts.\n---\n\n# OpenClaw Feishu Multi-Agent\n\n## Goal\n\n让 OpenClaw 的多个独立 agent 在同一个飞书群里协作：\n\n- 协调者 agent 负责读群消息、决定谁处理\n- 群里能看到显式 `<at>`\n- 被点名的 agent 会主动回群\n- agent 之间可以继续串联讨论\n\n## 先判断是哪种场景\n\n### 场景 A：用户已经有多 agent\n\n优先检查并修复：\n\n1. `~/.openclaw/openclaw.json`\n2. `~/.openclaw/PROTOCOL.md`\n3. 各 agent 的 `IDENTITY.md` / `SOUL.md`\n4. 会话存储是否把 Feishu 群上下文写坏\n5. gateway 重启后是否恢复\n\n### 场景 B：用户还没有多 agent\n\n先帮助用户定义角色表，再补齐：\n\n1. agent roster\n2. Feishu account bindings\n3. 协调协议\n4. 各 agent 身份文件\n5. 验证话术\n\n## 核心规则\n\n### 规则 1\n\n飞书里的 `<at>` 只是“给人看见谁被点名了”。\n\n### 规则 2\n\nOpenClaw 里的 `sessions_send` 才是“真正唤醒另一个 agent”。\n\n### 规则 3\n\n每一次委派都必须同时做两步：\n\n1. 在飞书群里发可视化 `<at>`\n2. 用 `sessions_send` 向目标 agent 投递任务\n\n少一步都不算成功。\n\n### 规则 4\n\n`sessions_send` 默认使用 `sessionKey`：\n\n```text\nagent:{targetAgentId}:feishu:group:oc_xxx\n```\n\n不要给 `sessions_send` 传 `agentId`。\n\n## 推荐实施顺序\n\n1. 盘点角色、agentId、Feishu accountId、Open ID、职责和触发词\n2. 标准化 `~/.openclaw/PROTOCOL.md`\n3. 把协调者 agent 写成“默认总调度”\n4. 把专业 agent 写成“收到 sessions_send 后直接回群”\n5. 检查 `openclaw.json` 的 `agents.list`、`bindings`、`tools.agentToAgent.allow`\n6. 检查群 session 是否保持 `channel=feishu`、`chatType=group`\n7. 重启 gateway\n8. 用真实飞书话术验证\n\n## 角色设计要求\n\n不要把方案写死成 Steve / Jonathan / Brendan / Seth。\n\n始终把角色抽象成：\n\n- `coordinator`: 默认调度者\n- `specialists`: 一个或多个专业 agent\n\n角色名、人设、职责、触发词都应该允许自定义。\n\n## 你需要产出的东西\n\n根据用户场景，通常会创建或更新：\n\n- `~/.openclaw/PROTOCOL.md`\n- `~/.openclaw/openclaw.json`\n- `{agentDir}/IDENTITY.md`\n- 可选：一个团队协作 skill，避免 agent 退回单 bot 多角色思路\n\n## 修复时重点检查\n\n### 1. 路由遗漏\n\n如果协调者只叫了部分 agent：\n\n- 检查它的默认召集规则\n- 检查“其他人 / 大家 / 团队一起讨论”是否被错误窄化\n\n### 2. sessions_send 超时\n\n超时不等于没收到。继续检查：\n\n- 目标 agent session 是否生成\n- 目标 agent 是否进入长时间工具执行\n- 日志里是否出现 nested run / timeout\n\n### 3. 会话写坏\n\n如果目标 agent “像是收到了，但没回群”，重点检查 session store：\n\n- `channel` 是否被错误写成 `webchat`\n- `deliveryContext.to` 是否缺失\n- `accountId` 是否缺失\n- `chatType` 是否还是 `group`\n\n## 参考文件\n\n- 详细方案和诊断步骤：见 [reference.md](reference.md)\n- 可复用模板：见 [templates.md](templates.md)\n- 角色样例：见 [roles.example.json](roles.example.json)\n\n## Utility Scripts\n\n### 1. 统一入口\n\n优先使用统一入口，避免记多个脚本名：\n\n```bash\npython \".cursor/skills/openclaw-feishu-multi-agent/scripts/manage_feishu_multi_agent.py\" --help\n```\n\n如果想一把跑完“生成 -> 落地 -> 审计”：\n\n```bash\npython \".cursor/skills/openclaw-feishu-multi-agent/scripts/manage_feishu_multi_agent.py\" bootstrap \\\n  --roles \".cursor/skills/openclaw-feishu-multi-agent/roles.example.json\" \\\n  --output-dir \"/tmp/openclaw-feishu-artifacts\" \\\n  --apply-identities\n```\n\n加上 `--write --backup` 才会真正写入 `~/.openclaw/`。\n\n### 2. 生成可落地模板\n\n当用户还没配好多 agent，或希望把角色表转换成可落地文档时，运行：\n\n```bash\npython \".cursor/skills/openclaw-feishu-multi-agent/scripts/render_feishu_multi_agent.py\" \\\n  --roles \".cursor/skills/openclaw-feishu-multi-agent/roles.example.json\" \\\n  --output-dir \"/tmp/openclaw-feishu-artifacts\"\n```\n\n产出：\n\n- `PROTOCOL.generated.md`\n- `openclaw.generated.json`\n- `roles.generated.json`\n- `identities/*.IDENTITY.generated.md`\n\n`openclaw.generated.json` 现在会同时带出：\n\n- `agents.list`\n- `bindings`\n- `channels.feishu.accounts`\n- `tools.sessions.visibility`\n- `tools.agentToAgent.allow`\n\n### 3. 审计现有配置\n\n当用户已经有多 agent，想快速检查 `openclaw.json` 是否与角色表一致时，运行：\n\n```bash\npython \".cursor/skills/openclaw-feishu-multi-agent/scripts/audit_feishu_multi_agent.py\" \\\n  --roles \"/path/to/roles.json\" \\\n  --config \"~/.openclaw/openclaw.json\"\n```\n\n重点检查：\n\n- `agents.list`\n- `bindings`\n- `channels.feishu.accounts`\n- `tools.sessions.visibility`\n- `tools.agentToAgent.allow`\n\n### 4. 半自动落地到 `~/.openclaw/`\n\n当用户希望把角色表直接应用到自己的 OpenClaw 环境时，先 dry-run：\n\n```bash\npython \".cursor/skills/openclaw-feishu-multi-agent/scripts/apply_feishu_multi_agent.py\" \\\n  --roles \"/path/to/roles.json\" \\\n  --apply-identities\n```\n\n确认无误后再写入：\n\n```bash\npython \".cursor/skills/openclaw-feishu-multi-agent/scripts/apply_feishu_multi_agent.py\" \\\n  --roles \"/path/to/roles.json\" \\\n  --apply-identities \\\n  --write --backup\n```\n\n这个脚本会：\n\n- 合并 `openclaw.json` 里的 `agents.list`\n- 合并 `channels.feishu.accounts`\n- 合并 `bindings`\n- 打开 `tools.sessions.visibility=all`\n- 打开 `tools.agentToAgent.enabled=true`\n- 补齐 `tools.agentToAgent.allow`\n- 写入 `~/.openclaw/PROTOCOL.md`\n- 可选写入各 agent 的 `IDENTITY.md`\n\n### 5. 修复 Feishu 群 session\n\n当某个 agent “像是收到了，但没回群”，优先检查并按需修复 session metadata：\n\n```bash\npython \".cursor/skills/openclaw-feishu-multi-agent/scripts/repair_feishu_group_sessions.py\" \\\n  --roles \"/path/to/roles.json\" \\\n  --group-id \"oc_xxx\"\n```\n\n如需直接写回：\n\n```bash\npython \".cursor/skills/openclaw-feishu-multi-agent/scripts/repair_feishu_group_sessions.py\" \\\n  --roles \"/path/to/roles.json\" \\\n  --group-id \"oc_xxx\" \\\n  --fix --backup\n```\n\n## 交付风格\n\n- 中文说明为主\n- 代码、路径、键名、命令用英文\n- 默认提供通用模板，不绑定用户现有角色名\n","tags":{"latest":"1.0.1"},"stats":{"comments":0,"downloads":654,"installsAllTime":0,"installsCurrent":0,"stars":0,"versions":2},"createdAt":1773577466171,"updatedAt":1778491925219},"latestVersion":{"version":"1.0.1","createdAt":1773580426993,"changelog":"Improve public-facing English description, tagline, and discovery tags.","license":"MIT-0"},"metadata":null,"owner":{"handle":"ccharlesmeng","userId":"s171t1hv7jcr6sfc75db6zy7k18844xa","displayName":"CCharlesMeng","image":"https://avatars.githubusercontent.com/u/11910337?v=4"},"moderation":null}