ngrok隧道监听

技能简介

该技能在本地启动一个HTTP服务器，通过ngrok建立公网隧道，将外部webhook请求转发到本地处理。支持自动匹配已安装技能的事件处理器，或在无匹配时向用户发送通知等待人工决策。

业务背景

开发调试阶段常需接收第三方平台的实时回调，但本地服务无外网地址。本技能一键建立公网隧道，自动将webhook请求转发至对应本地服务，省去服务器部署成本，支持无匹配时人工介入，兼顾自动化与可控性。

落地案例：电商平台运营人员需在本地调试订单状态同步功能，配置ngrok令牌后启动技能，获得固定公网URL填入平台后台。当订单支付完成，平台推送webhook至该地址，技能自动解析载荷并触发本地处理脚本；若事件类型未配置自动路由，则即时推送WhatsApp通知提醒人工确认，避免遗漏关键业务事件。

能做什么

• 为本地服务生成临时或固定的公网URL
• 接收并解析HTTP POST/GET等webhook载荷
• 根据skill.json配置自动转发到对应技能的本地端口或执行命令
• 无匹配处理器时通过WhatsApp推送待办通知
• 输出结构化JSON日志供其他进程轮询

使用说明

1. 安装依赖

cd skills/ngrok-unofficial-webhook-skill
npm install

2. 配置环境变量

复制.env.example为.env，填写以下字段：

• NGROK_AUTHTOKEN（必填）：从ngrok控制台获取
• NGROK_DOMAIN（可选）：固定域名避免URL变动
• WEBHOOK_PORT（可选）：本地端口，默认4040
• OPENCLAW_NOTIFY_TARGET（可选）：WhatsApp通知手机号

3. 启动服务

node scripts/webhook-server.js

后台长期运行：

nohup node scripts/webhook-server.js >> /tmp/ngrok-webhook.log 2>&1 &

终端会输出NGROK_URL，将此地址填入第三方平台的webhook配置即可。

4. 健康检查与停止

curl http://localhost:4040/health

使用kill命令终止后台进程。

输入与输出

见下方输入与输出表格。

风险提示

• ngrok免费域名每次重启可能变化，生产环境建议绑定固定域名
• webhook载荷直接解析后执行shell命令，需确保skill.json来源可信
• 公网URL暴露期间可能收到无关扫描流量，建议配合路径密钥或IP白名单
• 后台进程异常退出不会自动重启，需自行配置systemd或pm2托管

来源信息

原始链接：https://github.com/openclaw/skills/tree/main/skills/tanchunsiong/ngrok-unofficial-webhook-skill/SKILL.md
来源类型：GitHub仓库