OpenClaw 飛書 Webhook 內網穿透

飛書 Webhook 內網穿透

適用場景：你要用飛書「事件訂閱 Webhook」模式接入 OpenClaw（接收消息、卡片交互等）。
關鍵限制：飛書要求 公網可訪問的 HTTPS URL + 域名（不能用裸 IP，不能用 http）。
因此：本地運行的 OpenClaw gateway（例如 3000/8080）必須通過 隧道工具暴露到公網。

你將完成什麼

• 確認 OpenClaw gateway 正在本地監聽端口
• 選擇一種隧道方式（Ngrok / Cloudflare Tunnel / Localtunnel）
• 得到公網 HTTPS 域名
• 在飛書開放平臺設定事件訂閱 URL 並通過驗證
• 最終在飛書群/私聊 @機器人 能收到回覆

開始前準備（小白必看）

• 你已經完成 OpenClaw 安裝與基礎設定（含飛書 appId/appSecret 或插件設定）
• 你知道 OpenClaw gateway 的監聽端口（常見 3000 或 8080）
• 你能打開飛書開放平臺並管理“企業自建應用”

Step 0：確認 gateway 在本地能訪問

0.1 啟動 gateway（示例）

openclaw gateway --port 3000

0.2 驗證端口在監聽

任選一個驗證方式：

方式 A：看日誌

• 看到類似 “listening on 3000” 的輸出（不同版本會略不同）

方式 B：curl health（如果你的 gateway 有健康檢查）

curl -i http://127.0.0.1:3000/health || true

方式 C：檢查端口

lsof -i :3000 || true

如果你不確定端口是多少：
先用你實際啟動參數為準；或在 openclaw gateway --help/日誌裡找預設端口。

Step 1：確認 Webhook endpoint 路徑

飛書事件訂閱要填：
https://你的域名/<feishu-endpoint>

但不同插件/版本 endpoint 可能不同，比如：

• /feishu/events
• /webhook/feishu
• /events

1.1 推薦做法：從日誌裡找

openclaw gateway --verbose# 或openclaw logs | grep -i -E "feishu|webhook|event|callback" || true

1.2 兜底做法：用你插件文件給的路徑

如果你暫時找不到日誌，就先用你最常見的：/feishu/events
驗證失敗再回到這裡調整（見“驗證失敗排查”）。

方案 A：Ngrok

A1. 安裝並登錄

1. 註冊並安裝 Ngrok
2. 設置 authtoken：

ngrok authtoken REDACTED_NGROK_AUTHTOKEN

A2. 建立隧道

假設 gateway 監聽 3000：

ngrok http 3000

你會看到：

• Forwarding https://xxxx.ngrok-free.app -> http://localhost:3000

✅ 複製這個 https 域名備用。

A3. 用 ngrok 面板排查（強烈推薦）

http://127.0.0.1:4040

這裡能看到飛書發來的請求是否到達你的本地。

方案 B：Cloudflare Tunnel

優勢：更穩定、可長期運行、可固定域名（trycloudflare 或自有域名）、安全性更強。
缺點：首次設定比 ngrok 多一點。

B1. 安裝 cloudflared

（按系統安裝即可）

B2. 快速測試（最簡單）

cloudflared tunnel --url http://localhost:3000

它會輸出：

• https://random.trycloudflare.com

✅ 這個域名可以直接拿去飛書驗證（適合快速跑通）。

B3. Named Tunnel（推薦長期）

1. 登錄：

cloudflared tunnel login

2. 創建隧道：

cloudflared tunnel create openclaw-feishu

3. 寫設定文件 ~/.cloudflared/config.yml：

tunnel: openclaw-feishucredentials-file: /home/YOUR_USER/.cloudflared/<UUID>.jsoningress:  - hostname: openclaw-feishu.trycloudflare.com    service: http://localhost:3000  - service: http_status:404

4. 運行：

cloudflared tunnel --config ~/.cloudflared/config.yml run

✅ 這樣域名固定，重啟後不變（長期更省心）。

方案 C：Localtunnel

C1. 安裝

npm install -g localtunnel

C2. 啟動

lt --port 3000 --subdomain openclawvans

輸出類似：

• https://openclawvans.loca.lt

缺點：不穩定、容易掉線、域名可能被佔用。

Step 2：在飛書開放平臺設定事件訂閱

以你的公網域名為例（假設 endpoint 是 /feishu/events）：

請求 URL：

https://YOUR_DOMAIN/feishu/events

2.1 飛書校驗要求（重點）

• 必須是 HTTPS
• 必須是 域名（隧道提供的域名也算）
• URL 路徑必須正確（錯一個字符都會驗證失敗）

點擊“驗證/訂閱”，飛書會發一個驗證請求到你的 URL。

Step 3：驗證與測試

3.1 飛書後臺驗證成功

• 如果失敗：看下面“驗證失敗排查”

3.2 在飛書群或私聊測試

• 把機器人加入群（或私聊）
• 發消息：@機器人 你好

✅ 成功標準

• 飛書裡機器人有回覆
• 或 OpenClaw 日誌看到事件已收到、已處理

驗證失敗排查

飛書後臺提示 URL 不合法

• 你填的是 http（必須 https）
• 你填的是 IP（必須域名）
• 域名沒帶路徑/路徑不對

飛書驗證超時

• 隧道沒跑（ngrok/cloudflared 已退出）
• gateway 沒跑或端口不對（3000/8080 搞錯）
• 本地防火牆/安全軟件攔截

回調校驗失敗

• 你的 endpoint 路徑不對（例如實際是 /webhook/feishu）
• gateway 沒掛載該路由（插件未啟用/設定未生效）
• 需要校驗 token/encrypt key：檢查插件要求並在 config 中補齊

國內網絡慢

• ngrok 美國節點可能慢：優先用 Cloudflare Tunnel 或換網絡環境

安全建議

隧道一開，你的 gateway 等於暴露到公網了：

• ✅ 建議開啟 pairing/白名單：只允許你的使用者觸發指令
• ✅ 優先限制“只響應 @提及”
• ✅ 只開放 webhook 必要路徑（不要暴露管理端口/調試端點）
• ✅ 不要把 appSecret/token 打進日誌或提交到 git
• ✅ 長期運行用 VPS/Docker + systemd（穩定也更安全）

推薦選擇

• 測試/快速跑通：Ngrok
• 長期/更穩定/國內更友好：Cloudflare Tunnel（推薦）
• 一次性臨時：Localtunnel（不推薦生產）

參考鏈接

• 飛書開放平臺
• Ngrok 文件
• Cloudflare Tunnel 文件
• Localtunnel GitHub