Clawdbot 部署到飞书（飞连）使用教程（完整版）

0. 你将得到什么

完成本教程后，你会拥有一套可长期在线的 Clawdbot（Clawd）：

Clawd Gateway 在你的服务器/本机常驻运行（默认本地监听 127.0.0.1:18789）
飞书（飞连）机器人 能把群聊/私聊消息转发给 Clawd，再把 Clawd 回复发回飞书
你在飞书里就能像"@机器人下指令"一样使用 Agent（记忆、工具、定时任务都在你自己的环境里）

1. 准备清单（开始前先对照）

1.1 运行环境

一台长期在线设备（推荐 VPS / 家用小主机 / Mac mini）
Node.js 22+
可用的模型能力（OpenAI/Claude API 或本地模型皆可，按你的 Clawd 配置为准）

1.2 账号与权限

飞书开放平台账号
有权限创建 企业自建应用（机器人）

1.3 你需要理解的三个端口（别混）

18789：Clawd Gateway 的 WebSocket 控制面（内部总线）
18793（或你配置的）：Canvas HTTP 服务（可选，不是飞书接入核心）
飞书自己的事件通道：由飞书平台提供，插件去连它（不是你开端口给飞书）

2. 安装并初始化 Clawdbot（Gateway）

目标：让 Gateway 能正常启动，并且 status/health/doctor 通过。

2.1 安装（示例）

复制代码

node -v   # 确保 >= 22
npm -v
npm i -g clawdbot

2.2 初始化向导

复制代码

clawd onboard

按向导完成：

模型配置（API Key / Base URL 等）
工作目录（建议单独目录，比如 ~/clawd）
后台守护（如果向导支持，直接启用）

2.3 启动与自检

复制代码

clawd status
clawd health
clawd doctor

检查点：

Gateway 正常运行
端口监听符合预期（默认 127.0.0.1:18789）

小提示：如果你要远程访问 18789，优先用 SSH Tunnel / Tailscale，不要直接把 18789 暴露公网。

3. 安装飞书 Channel 插件（把飞书接到 Clawd）

思路：飞书接入不是 Gateway 自带的，需要装一个 Channel Adapter 插件。插件的作用就是"翻译 + 搬运"。

3.1 安装插件（示例）

以社区常用的 m1heng 飞书插件为例（包名以你实际为准）：

复制代码

npm i -g @m1heng-clawd/feishu
# 或在你的 clawd 项目/工作目录里安装：npm i @m1heng-clawd/feishu

3.2 插件需要的核心配置

一般你需要准备：

App ID
App Secret
（可能还要）事件加解密 Key / Verify Token（看插件要求）

这些都来自飞书开放平台创建的自建应用（下一节会做）。

4. 在飞书开放平台创建机器人（自建应用）

目标：创建应用 → 申请权限 → 开启事件接收（推荐长连接）→ 拿到 App ID/Secret。

4.1 创建企业自建应用

在飞书开放平台：

创建「企业自建应用」
开启「机器人」能力（Bot）

拿到：

App ID
App Secret

4.2 配置权限（必须做，否则发不出/收不到）

你至少要确保应用具备：

接收消息事件（群聊/私聊相关）
发送消息权限（文本/富文本/卡片等按你需求）
读取用户或群信息（可选，但常用）

权限名在飞书后台会按版本/语言略有差异：原则是"能收消息事件 + 能发消息"。

4.3 配置事件订阅：优先使用「长连接模式」

两种模式对比：

HTTP 回调模式：飞书 POST 到你的公网 HTTPS 回调地址
- 你需要公网域名 + HTTPS + 验签/证书/穿透
长连接模式（推荐）：你的插件主动连飞书的事件通道，飞书把事件从连接里推给你
- 不需要暴露公网回调地址
- 你文中提到的"勾选长连接接收回调"就是这个思路

按插件文档/飞书后台提示：

启用 长连接接收事件
保存配置

4.4 发布与可用性检查

确认应用状态可用（内部测试/发布到企业内）
把机器人加到群里或开启私聊

5. 把飞书插件接到 Gateway（最关键链路）

目标：插件同时"连飞书事件通道"和"连 Clawd 内部总线 18789"，形成双向桥。

5.1 你要知道消息到底怎么走

完整链路（照这个排错最有效）：

飞书产生消息事件（例如群里 @机器人）
插件通过长连接收到事件
插件把事件翻译成 Clawd 内部消息结构
插件通过 WebSocket 把消息投递到 Gateway（18789）
Agent 处理（模型 + 记忆 + skills）
Gateway 输出回复事件给插件
插件调用飞书发送消息 API 回到原会话

一句话：插件把飞书事件流接入 18789，再把 18789 的回复流发回飞书。

5.2 配置插件（示例字段）

不同插件配置格式略有差异，但你最终要填的基本就这些：

FEISHU_APP_ID=...
FEISHU_APP_SECRET=...
GATEWAY_WS=ws://127.0.0.1:18789（或你的实际地址）
（可选）事件加密/验签相关配置

建议你把配置写进：

.env 文件

或
Clawd/插件的配置文件（JSON/YAML）

5.3 启动顺序建议

先启动 Gateway
再启动飞书插件
最后去飞书里发一条测试消息

6. 验证：用最小用例确认闭环

按下面顺序测（别一上来就测复杂指令）：

6.1 飞书侧

群里 @机器人发：ping
或私聊机器人发：ping

期望：

插件收到事件（能看到日志）
机器人能回复（哪怕只是 echo 或默认提示）

6.2 Gateway 侧

clawd status 显示运行
Gateway 日志能看到来自 channel=feishu 的消息事件（若有日志等级设置，调到 info/debug）

6.3 常见成功标志

飞书里收到了回复
插件日志里能看到：收到事件 → 投递 Gateway → 发送消息成功

7. 常见问题排错（按链路逐段定位）

7.1 飞书里发消息，插件完全没反应

优先检查：

飞书应用是否启用了事件接收（长连接）
权限是否开齐（收消息事件权限）
机器人是否已加入群、是否允许被 @
插件是否真的启动成功、是否连上飞书事件通道

7.2 插件能收到事件，但 Gateway 没收到

检查：

GATEWAY_WS 是否正确（ws://127.0.0.1:18789）
Gateway 是否只监听 loopback（如果插件在另一台机器上跑，你得用 SSH Tunnel/Tailscale）
18789 是否被本机防火墙拦截（本机也可能拦）

7.3 Gateway 收到消息，但飞书不回复

检查：

飞书发消息权限是否开通
token 是否能正常获取与刷新（App ID/Secret 对不对）
是否命中了飞书 API 速率限制（插件一般会提示）
会话标识（chat_id/open_id）是否解析正确（插件 bug 或事件类型不匹配）

8. 安全建议（务必看）

Clawd 能跑 shell、能读写文件，强模型 + 高权限 = 高风险。建议你做到：

最小权限：不要让默认 Agent 拿到不必要的系统权限
隔离账号与凭证：API Key、云服务凭证用独立账号/子账号
不要暴露 18789 到公网：使用 SSH Tunnel / Tailscale
警惕指令注入：把外部输入当作不可信数据（尤其是群聊）

9. 多实例部署（你提到的"改端口跑多个"）

可以，但要遵守 4 条规则：

每个实例的 Gateway 端口不同
- A：18789
- B：28789
每个实例的工作目录隔离
- ~/clawd-a、~/clawd-b
  
  否则记忆/状态文件会互相覆盖。
同一个飞书机器人不要同时连多个 Clawd 实例

否则会出现重复响应、竞态、去重混乱。
多实例的推荐绑定方式
- 最简单：多个飞书应用（机器人） 各绑一个 Clawd 实例
- 更高级：插件做路由（按 chat_id/租户分发），但实现复杂

10. 最后总结

18789 是 Clawd 的内部总线，不是飞书端口
飞书接入靠 Channel 插件：一头连飞书事件通道，一头连 Gateway（18789）
完整闭环就是：飞书事件 → 插件 → Gateway/Agent → 插件 → 飞书消息 API