Feishu Multi Agent Chat

多个 AI Agent 在飞书群聊中通过 at 互相通信，实现多 Agent 协作。覆盖建群、创建Bot、拉Bot进群、获取open_id、text格式互 at 通信、防呆约束、故障排查全流程。Use when user says 飞书多Agent通信、Bot互at、飞书Bot创建、群聊AI协作、多Bot群聊。支持 CherryClaw、WorkBuddy、OpenClaw、AutoClaw 等框架。

zhouxin121@zhouxin121

Install

openclaw skills install @zhouxin121/feishu-agent-communication

飞书多 Agent 群聊通信

v13.6.0 基础版 | 2026-07-10 | 免费公开，能跑通 ~30 分钟

多个 AI Agent 在飞书群里自动协作——建群 → 拉 Bot → 互 @ 通信 + 分工合作。

Step 0：连接飞书

各框架统一操作：Agent 设置 → 频道 → 添加飞书 → 扫码。扫码后自动建立 WebSocket 长连接直连飞书群。

各框架原生扫码配置即可。

Step 1：准备条件

飞书账号（免费注册 feishu.cn）
创建飞书群（单人即可创建，可添加多个飞书机器人）
框架软件已安装并运行

Step 2：创建飞书 Bot 应用

飞书开放平台 → 创建企业自建应用 → 添加「机器人」能力
权限管理 → 逐一开通：

权限	状态	说明
`im:message:send_as_bot`	✅ 开	以 Bot 身份发送消息
`im:message.group_at_msg:readonly`	✅ 开	接收人类 @ 当前 Bot
`im:message.group_at_msg.include_bot:readonly`	✅ 开	接收其他 Bot @ 当前 Bot（最关键）
`im:message.group_msg`	❌ 关	与 `group_at_msg` 互斥——两个同时开，`group_msg` 的事件路由会把带 @ 的消息当普通消息处理、不触发 @ 判断

最小权限集：group_msg 关 + 两个 group_at_msg 开 = 群内仅在 @ 时响应。

⚠️ 事件订阅：「事件与回调」页面有 「事件配置」和「回调配置」两个独立 Tab，必须分别点进去 → 分别点「验证」→ 分别点「保存」。只做一边连不上 WebSocket。
- 两个 Tab 的订阅方式均选「使用长连接接收事件」
- 事件配置 Tab 需添加事件 im.message.receive_v1
记下 App ID（cli_ 开头）和 App Secret
创建版本 → 发布（一般免审核，几秒通过）

Step 3：获取群号

手机飞书 App → 进群 → 右上角「…」→ 群设置 → 拖到底部 → 群号。格式：oc_ 开头。

Step 3.5：把 Bot 拉进群（最容易漏掉！）

群设置 → 群机器人 → 添加机器人 → 选择 Step 2 创建的 Bot。

Step 4：Bot 间 @ 通信格式

必须用 text，不用 post/card

格式	@ 标签写法	Bot 间可靠性
text	`<at user_id="ou_xxx">名称</at>`	✅ 所有框架一致解析
post	`{"tag":"at","user_id":"ou_xxx"}`	❌ CherryClaw 不解析，静默丢失
interactive	卡片内 @ 标签	❌ 富文本/卡片中 @ 被忽略

原因：不同框架 SDK 序列化 post 方式不同，实测 CherryClaw 不解析 post 格式 @ 标签。

"text 格式"仅指 msg_type 和 @ 标签的承载方式，不约束消息正文。 消息正文可以包含 Markdown 排版、结构化数据、代码块、表格等——只需全部放在 content.text 字符串内、@ 标签用 <at> 语法即可。

@ 标签写法

text

<at user_id="ou_xxx">Bot名称</at>

属性名 user_id，值是 ou_xxx 格式的 open_id（不是 cli_xxx App ID）
<at> 嵌在 content.text 字符串内
禁止用 < > HTML 转义，直接用原始 <at> 标签

⚠️ Agent 会"意译"模板而非逐字执行——模板指令必须加"请逐字复制，不要修改任何字符"。

发送方式

通过飞书 REST API（POST /im/v1/messages）发送。需要 msg_type=text，content.text 内含 <at> 标签。

参数	值
API 端点	`POST /im/v1/messages?receive_id_type=chat_id`
`msg_type`	`text`
`content.text`	含 `<at user_id="ou_xxx">名称</at>` 的字符串
`receive_id`	群号（`oc_` 开头）

⚠️ 别把 @ 符号当成真 @ 群里显示"@云端主agent"不等于是真 @。只有通过飞书 REST API 发送 content.text 中含 <at user_id="ou_xxx"> 标签的消息，才会触发对方的 @ 通知。纯文本 @名称 只是普通文字。

open_id：App 隔离 + 获取方式

飞书 open_id 是 App 隔离的——同一 Bot 在不同 App 视角下 open_id 不同。

获取 open_id 的方法

对方 Bot 在群里发消息 → 从 WebSocket 事件回调中取 event.sender.sender_id.open_id。

冷启动闭环

对方 Bot 还没发过消息 → 你没有它的 open_id。此时你 @ 它时，必须在消息里附带自己的显式 open_id。对方用这个 open_id 就能直接 @ 回你。

app_id / open_id / user_id 不要混淆

ID	格式	用途	获取方式
`app_id`	`cli_` 开头	拉 Bot 进群时填写	飞书开放平台 → 应用凭证
`open_id`	`ou_` 开头	发消息、@ 人时填写	WebSocket 事件
`user_id`	企业自定义	跨应用打通用户数据，不能用于 @	`/contact/v3/users` API

Step 5：五步验证闭环

步骤	内容	验证目标
①	往群里发一条普通 text 消息	Bot 能否发消息到群
②	人类在群里 @ Bot	本对话收到回复
③	Bot 用 text+at @ 其他 Bot（附带自己 open_id）	对方回复
④	其他 Bot 用 text+at @ 本 Bot	本对话收到
⑤	多 Bot 链式 @ 协作	全链路畅通

五步验证中 ③④⑤ 任意一步卡住，通常需要手动翻 WebSocket 事件排查 open_id 不匹配和 @ 标签格式错误。赞赏版部署文档含每步期望日志 + 自动诊断 + 一键验证脚本，<10 分钟跑通。

故障排查

#	现象	原因	解决
1	Bot 不响应	没把 Bot 拉进群	Step 3.5，群设置 → 群机器人 → 添加
2	WebSocket 连不上	事件/回调只点订阅没验证保存	Step 2 第 3 步，两个 Tab 分别验证+保存
3	@ 了对方没收到	用了 post 格式	改为 text 格式（Step 4）
4	@ 了对方没收到	open_id 是其他 App 视角的	从 WebSocket 事件取自己视角 open_id
5	@ 了对方没收到	`<at>` 被转义成 `<at>`	不要 HTML 转义，直接用原始标签
6	收到群内所有消息	开了 `im:message.group_msg`	关闭该权限

LLM/AI 防呆说明

以下 6 条来自实测——LLM 和 Agent 会反复犯同样的错。

#	错	为什么错	正确做法
1	"回复并 @ 我"	Agent 无法从语境推断"我"= 谁	给出完整 `<at user_id="ou_xxx">@名称</at>` 模板
2	模板被"意译"	LLM 理解意图后改写格式	强调"逐字复制，不要修改任何字符"
3	教别人用 post 格式	Agent A 按飞书官方文档教 Agent B，但 CherryClaw 不解析 post	标注平台差异
4	纯文本 `@名称` 当 @ 触发	LLM 混淆"包含 @ 文字"和"真正的 @ 通知"	@ 触发只能通过飞书 API `<at>` 标签
5	403 看错误文字就下结论	"free quota exhausted" 不一定是配额问题	403 排查顺序：路由 → 权限 → 格式 → 配额
6	权限全开还是不行 → 归因框架 bug	没检查对端的发送格式	优先查对端是否用 post/转义 `<at>`，再怀疑框架

架构约束

CherryClaw 框架层过滤 Bot 消息

即使飞书权限全对、格式全对，CherryClaw 在框架层检查 sender_type == "app" 并主动丢弃。因此 Bot 间通信必须走飞书 HTTP API 直接发送，绕过框架的入站过滤。

一个飞书 App 只能有一个 WebSocket

同一 App ID 不能同时被多个框架进程连接。多框架共用同一群时，每个框架需注册独立的飞书 App。

Bot 间 @ 通信只需记住：text 格式 + <at user_id="自己App视角的open_id"> 嵌在 content.text 内。 post 不行、别人的 open_id 不可靠、必须附带显式 ID。

版本记录

版本	日期	变更内容
v13.6.0-base	2026-07-10	基础版：保留 Step 0-5 执行骨架，移除 OpenClaw 集成章节、curl 示例、精确指令模板、架构图（以上放赞赏版）
v13.0.0	2026-07-09	架构重构：Gateway→框架原生IM通道；通信格式 post→text；新增 open_id App隔离+安全约束
v13.1.0	2026-07-09	新增「LLM/AI 防呆说明」6 条；故障排查新增 2 条；Step 4 指令约束加强
v13.2.0	2026-07-09	新增「三个 ID 区分」「架构约束」章节；权限互斥警告强化
v13.5.0	2026-07-09	user_id 陷阱强化
v13.6.0	2026-07-10	完整版：新增 OpenClaw 集成章节、curl 示例、精确指令模板、deployment 文档引导

参考链接

（内容由AI生成，仅供参考）