上一章講的都是 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 長連線。流程雖長，但跑通一次後就是一勞永逸的團隊協作通道。下一節我們看釘釘，並給出一個手機端遠端實戰的完整例子。