上一章讲的都是 IM 平台。这一节专攻飞书——办公协作领域用得最广的平台之一。飞书的接入属于开放平台型，步骤比扫码直连多一些，但只要理清"在飞书开放平台建应用 → 在 WorkBuddy 回填凭证 → 回飞书配置事件"这条主线，一遍就能跑通。
一、整体流程概览#
飞书接入可以拆成三个阶段，先把骨架记住，细节就好填：
- 飞书侧建应用：在飞书开放平台创建企业自建应用，拿到凭证
- WorkBuddy 侧配置：填入凭证，选连接方式，完成注册
- 飞书侧配事件：把消息事件、回调配好，发布版本
下面逐步展开。
二、飞书侧：创建应用与拿凭证#
1. 创建企业自建应用#
登录 飞书开放平台，在"开发者后台"创建一个企业自建应用，填写名称、描述、图标。
2. 添加机器人能力#
进入应用详情页，找到**"添加应用能力"，勾选"机器人"**。这一步让应用具备收发消息的能力。
3. 批量开通权限#
左侧进入**"权限管理"，点"批量开通/导入权限"**，粘贴官方提供的权限 JSON。这套权限通常涵盖：
- 消息读写（接收、发送）
- 文档读写
- 日历
- 多维表格读写
权限 JSON 可从 WorkBuddy 的接入文档复制。批量导入比一条条勾选快得多，且不易漏权限导致后续报错。
4. 取凭证#
左侧进入**"凭证与基础信息"**，记录两个关键值：
- App ID
- App Secret
5. 生成加密策略#
进入**"事件与回调"**，在加密策略里生成：
- Encrypt Key（加密策略）
- Verification Token（验证令牌）
这两个值 WorkBuddy 侧也要用到。
三、WorkBuddy 侧：填凭证与选连接方式#
回到 WorkBuddy 的 Claw 设置，进入飞书配置，依次填写：
| 字段 | 来源 |
|---|---|
| App ID | 飞书"凭证与基础信息" |
| App Secret | 飞书"凭证与基础信息" |
| Encrypt Key | 飞书"事件与回调"加密策略 |
填完后要选择连接方式，这是飞书接入的关键决策点。
两种连接方式#
| 方式 | 适用场景 | 特点 |
|---|---|---|
| WebSocket 长连接（推荐） | 本地无公网 IP | 不需要公网服务器，WorkBuddy 主动连出去 |
| URL 回调模式 | 有公网服务器 | 飞书把消息推到你的 Webhook URL |
绝大多数个人和小团队没有公网 IP，因此首选 WebSocket 长连接，免去服务器运维。
填完所有信息后，点击**"注册"。如果选的是 WebSocket，状态会显示"已连接"**，即代表注册成功。
四、回飞书侧：配事件与回调#
注册成功后，还要回飞书开放平台把事件订阅补全。
1. 配置事件接收方式#
进入**"事件与回调"**：
- WebSocket 模式：勾选**"使用长连接接收事件"**，并验证
- 回调模式：把 WorkBuddy 输出的 Webhook URL 粘贴进去
2. 添加事件订阅#
在事件订阅里添加**"接收消息"**事件。这一步确保用户给机器人发消息时，飞书能推送给 WorkBuddy。
3. 配置回调#
在回调配置里加上**"卡片透传交互"**。这一步让机器人的交互卡片（按钮、表单）能把用户的点击回传给 WorkBuddy，是后面做交互式回复的基础。
4. 创建版本并发布#
回到应用详情，点**"创建版本"，填写版本号，然后"发布"**。发布后，应用才在企业内正式生效。
五、验证：发条指令试试#
发布完成后，回到飞书 App：
- 在搜索框搜刚创建的机器人名称
- 打开与机器人的对话
- 发一句"你好"或任意指令
- 电脑端 WorkBuddy 收到并响应，即说明全链路打通
六、常见问题排查#
| 现象 | 排查方向 |
|---|---|
| 注册后显示"未连接" | 检查 App ID/App Secret/Encrypt Key 是否填对 |
| 发指令无响应 | 确认"接收消息"事件已订阅、版本已发布 |
| 卡片按钮点了没反应 | 确认回调里加了"卡片透传交互" |
| 回调模式验证失败 | Webhook URL 是否公网可达、是否输出了正确响应 |
小结#
飞书接入的核心是"两边来回填凭证 + 选对连接方式"。没有公网 IP 的用户首选 WebSocket 长连接。流程虽长，但跑通一次后就是一劳永逸的团队协作通道。下一节我们看钉钉，并给出一个手机端远程实战的完整例子。