跳转到内容

最近更新 · 2026-01-30

OpenClaw 飞书 Webhook 模式内网穿透（Ngrok / Cloudflare Tunnel / Localtunnel）

适用场景：你要用飞书「事件订阅 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（示例）

bash
openclaw gateway --port 3000

0.2 验证端口在监听

任选一个验证方式：

方式 A：看日志

  • 看到类似 “listening on 3000” 的输出（不同版本会略不同）

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

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

方式 C：检查端口

bash
lsof -i :3000 || true

如果你不确定端口是多少：
先用你实际启动参数为准；或在 openclaw gateway --help/日志里找默认端口。

Step 1：确认飞书 Webhook endpoint 路径（很关键）

飞书事件订阅要填：
https://你的域名/<feishu-endpoint>

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

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

1.1 推荐做法：从日志里找

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

1.2 兜底做法：用你插件文档给的路径

如果你暂时找不到日志，就先用你最常见的：/feishu/events
验证失败再回到这里调整（见“验证失败排查”）。

方案 A：Ngrok（最快上手，适合测试/短期）

A1. 安装并登录

  1. 注册并安装 Ngrok
  2. 设置 authtoken：
bash
ngrok authtoken YOUR_AUTHTOKEN

A2. 建立隧道

假设 gateway 监听 3000：

bash
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. 快速测试（最简单）

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

它会输出：

  • https://random.trycloudflare.com

✅ 这个域名可以直接拿去飞书验证（适合快速跑通）。

B3. Named Tunnel（推荐长期）

  1. 登录：
bash
cloudflared tunnel login
  1. 创建隧道：
bash
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. 运行：
bash
cloudflared tunnel --config ~/.cloudflared/config.yml run

✅ 这样域名固定，重启后不变（长期更省心）。

方案 C：Localtunnel（一次性临时，最不推荐）

C1. 安装

bash
npm install -g localtunnel

C2. 启动

bash
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 日志看到事件已收到、已处理

验证失败排查（90% 的问题在这里）

1) 飞书后台提示 URL 不合法

  • 你填的是 http（必须 https）
  • 你填的是 IP（必须域名）
  • 域名没带路径/路径不对

2) 飞书验证超时

  • 隧道没跑（ngrok/cloudflared 已退出）
  • gateway 没跑或端口不对（3000/8080 搞错）
  • 本地防火墙/安全软件拦截

3) 看到请求到了 ngrok(4040) 但飞书仍失败

  • 你的 endpoint 路径不对（例如实际是 /webhook/feishu）
  • gateway 没挂载该路由（插件未启用/配置未生效）
  • 需要校验 token/encrypt key：检查插件要求并在 config 中补齐

4) 国内网络慢

  • ngrok 美国节点可能慢：优先用 Cloudflare Tunnel 或换网络环境

安全建议（强烈建议照抄到站里）

隧道一开，你的 gateway 等于暴露到公网了：

  • ✅ 建议开启 pairing/白名单：只允许你的用户触发指令
  • ✅ 优先限制“只响应 @提及”
  • ✅ 只开放 webhook 必要路径（不要暴露管理端口/调试端点）
  • ✅ 不要把 appSecret/token 打进日志或提交到 git
  • ✅ 长期运行用 VPS/Docker + systemd（稳定也更安全）

推荐选择

  • 测试/快速跑通：Ngrok
  • 长期/更稳定/国内更友好：Cloudflare Tunnel（推荐）
  • 一次性临时：Localtunnel（不推荐生产）

参考链接