跳轉到內容
最近更新

飛書 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（示例）

Command
openclaw gateway --port 3000

0.2 驗證端口在監聽

任選一個驗證方式：

方式 A：看日誌

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

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

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

方式 C：檢查端口

Command
lsof -i :3000 || true

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

Step 1：確認 Webhook endpoint 路徑

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

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

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

1.1 推薦做法：從日誌裡找

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

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

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

方案 A：Ngrok

A1. 安裝並登錄

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

A2. 建立隧道

假設 gateway 監聽 3000：

Command
ngrok http 3000

你會看到：

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

✅ 複製這個 https 域名備用。

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

TEXT
http://127.0.0.1:4040

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

方案 B：Cloudflare Tunnel

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

B1. 安裝 cloudflared

（按系統安裝即可）

B2. 快速測試（最簡單）

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

它會輸出：

  • https://random.trycloudflare.com

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

B3. Named Tunnel（推薦長期）

  1. 登錄：
Command
cloudflared tunnel login
  1. 創建隧道：
Command
cloudflared tunnel create openclaw-feishu
  1. 寫設定文件 ~/.cloudflared/config.yml：
YAML
tunnel: openclaw-feishucredentials-file: /home/YOUR_USER/.cloudflared/<UUID>.jsoningress:  - hostname: openclaw-feishu.trycloudflare.com    service: http://localhost:3000  - service: http_status:404
  1. 運行：
Command
cloudflared tunnel --config ~/.cloudflared/config.yml run

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

方案 C：Localtunnel

C1. 安裝

Command
npm install -g localtunnel

C2. 啟動

Command
lt --port 3000 --subdomain openclawvans

輸出類似：

  • https://openclawvans.loca.lt

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

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

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

請求 URL：

TEXT
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（不推薦生產）

參考鏈接