Feishu Multi Agent Chat

飞书多 Agent 群聊通信

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

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

---

Step 0：连接飞书

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

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

---

Step 1：准备条件

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

---

Step 2：创建飞书 Bot 应用

1. 飞书开放平台 → 创建企业自建应用 → 添加「机器人」能力

2. 权限管理 → 逐一开通：

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

1. ⚠️ 事件订阅：「事件与回调」页面有 「事件配置」和「回调配置」两个独立 Tab，必须分别点进去 → 分别点「验证」→ 分别点「保存」。只做一边连不上 WebSocket。

   • 两个 Tab 的订阅方式均选「使用长连接接收事件」
   • 事件配置 Tab 需添加事件 im.message.receive_v1

2. 记下 App ID（cli_ 开头）和 App Secret

3. 创建版本 → 发布（一般免审核，几秒通过）

---

Step 3：获取群号

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

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

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

---

Step 4：Bot 间 @ 通信格式

必须用 text，不用 post/card

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

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

@ 标签写法

Bot名称

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

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

发送方式

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

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

---

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 不要混淆

---

Step 5：五步验证闭环

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

---

故障排查

---

LLM/AI 防呆说明

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

---

架构约束

CherryClaw 框架层过滤 Bot 消息

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

一个飞书 App 只能有一个 WebSocket

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

---

Bot 间 @ 通信只需记住：text 格式 + `` 嵌在 content.text 内。 post 不行、别人的 open_id 不可靠、必须附带显式 ID。

---

版本记录

---

参考链接

1. https://open.feishu.cn/document/home/index
2. https://open.feishu.cn/document/server-docs/im-v1/message-content-description/create-content
3. https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/send
4. https://open.feishu.cn/document/server-docs/event-subscription-guide/overview
5. https://docs.openclaw.ai/
6. https://github.com/openclaw/openclaw
7. https://clawhub.ai/
8. https://pay.ldxp.cn/item/t7ktxb （赞赏获得10分钟内完成部署的文档）
9. https://clawhub.ai/glassmarbles/feishu-agent-relay
10. https://docs.cherrystudio.ai/

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