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

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

1.1 运行环境

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

1.2 账号与权限

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

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

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

目标：让 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 暴露公网。

思路：飞书接入不是 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（看插件要求）

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

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

4.1 创建企业自建应用

在飞书开放平台：

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

拿到：

• App ID
• App Secret

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

你至少要确保应用具备：

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

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

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

两种模式对比：

• HTTP 回调模式：飞书 POST 到你的公网 HTTPS 回调地址

• 你需要公网域名 + HTTPS + 验签/证书/穿透

• 长连接模式（推荐）：你的插件主动连飞书的事件通道，飞书把事件从连接里推给你

• 不需要暴露公网回调地址
• 你文中提到的“勾选长连接接收回调”就是这个思路

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

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

4.4 发布与可用性检查

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

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

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

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

1. 飞书产生消息事件（例如群里 @机器人）
2. 插件通过长连接收到事件
3. 插件把事件翻译成 Clawd 内部消息结构
4. 插件通过 WebSocket 把消息投递到 Gateway（18789）
5. Agent 处理（模型 + 记忆 + skills）
6. Gateway 输出回复事件给插件
7. 插件调用飞书发送消息 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.1 飞书侧
 
          
 
           
群里 @机器人发：ping
 
           
或私聊机器人发：ping
 
          
 
          
期望：
 
          
 
           
插件收到事件（能看到日志）
 
           
机器人能回复（哪怕只是 echo 或默认提示）
 
          
 
          
6.2 Gateway 侧
 
          
 
           
clawd status 显示运行
 
           
Gateway 日志能看到来自 channel=feishu 的消息事件（若有日志等级设置，调到 info/debug）
 
          
 
          
6.3 常见成功标志
 
          
 
           
飞书里收到了回复
 
           
插件日志里能看到：收到事件 → 投递 Gateway → 发送消息成功
 
          
 
          
 
           
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 或事件类型不匹配）
 
           
 
           
 
            
Clawd 能跑 shell、能读写文件，强模型 + 高权限 = 高风险。建议你做到：
 
            
 
             
最小权限：不要让默认 Agent 拿到不必要的系统权限
 
             
隔离账号与凭证：API Key、云服务凭证用独立账号/子账号
 
             
不要暴露 18789 到公网：使用 SSH Tunnel / Tailscale
 
             
警惕指令注入：把外部输入当作不可信数据（尤其是群聊）
 
            
 
            
 
             
可以，但要遵守 4 条规则：
 
             
 
              
每个实例的 Gateway 端口不同
 
             
 
             
 
              
A：18789
 
              
B：28789
 
             
 
             
 
              
每个实例的工作目录隔离
 
             
 
             
 
              
~/clawd-a、~/clawd-b 否则记忆/状态文件会互相覆盖。
 
             
 
             
 
              
同一个飞书机器人不要同时连多个 Clawd 实例
 否则会出现重复响应、竞态、去重混乱。



 
              
多实例的推荐绑定方式
 
             
 
             
 
              
最简单：多个飞书应用（机器人） 各绑一个 Clawd 实例
 
              
更高级：插件做路由（按 chat_id/租户分发），但实现复杂
 
             
 
             
 
              
 
               
18789 是 Clawd 的内部总线，不是飞书端口
 
               
飞书接入靠 Channel 插件：一头连飞书事件通道，一头连 Gateway（18789）
 
               
完整闭环就是：飞书事件 → 插件 → Gateway/Agent → 插件 → 飞书消息 API