Skip to content

Last updated · 2026-01-30

OpenClaw Feishu/Lark Webhook Tunneling (Ngrok / Cloudflare Tunnel / Localtunnel)

Use case: you want Feishu/Lark Webhook event subscription mode (receive messages, card interactions, etc.).
Key constraint: Feishu requires a public HTTPS URL with a domain (no plain IP, no http).
Therefore: your local OpenClaw gateway (e.g., port 3000/8080) must be exposed via a tunnel.

What you’ll achieve

  • Confirm OpenClaw gateway is listening locally
  • Choose a tunnel option (Ngrok / Cloudflare Tunnel / Localtunnel)
  • Obtain a public HTTPS domain
  • Configure Feishu event subscription URL and pass verification
  • Finally: mention the bot in Feishu and get a response

Prerequisites

  • OpenClaw installed, Feishu plugin/app config ready (appId/appSecret, etc.)
  • You know which local port gateway listens on (commonly 3000 or 8080)
  • Access to Feishu Open Platform for an internal app

Step 0: Make sure gateway works locally

0.1 Start gateway (example)

bash
openclaw gateway --port 3000

0.2 Verify the port is reachable

Pick one:

A) Check logs

  • Look for “listening on 3000” (wording varies by version)

B) Health endpoint (if available)

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

C) Port check

bash
lsof -i :3000 || true

Step 1: Confirm your Feishu webhook endpoint path (critical)

Feishu needs: https://YOUR_DOMAIN/<feishu-endpoint>

The endpoint path depends on plugin/version, common examples:

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

1.1 Recommended: find it in logs

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

1.2 Fallback: use the plugin docs’ default

If unsure, try /feishu/events first, then adjust if verification fails.

Option A: Ngrok (fastest, best for quick testing)

A1. Install and set authtoken

bash
ngrok authtoken YOUR_AUTHTOKEN

A2. Create a tunnel

Assuming port 3000:

bash
ngrok http 3000

You’ll get something like:

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

Copy the https domain.

A3. Use ngrok inspector for debugging (highly recommended)

Open:

text
http://127.0.0.1:4040

You can see incoming Feishu requests and your responses.

Option B: Cloudflare Tunnel (free + stable, recommended long-term)

B1. Install cloudflared

(install for your OS)

B2. Quick test (simplest)

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

It prints:

  • https://random.trycloudflare.com

This is enough to pass Feishu verification for a quick run.

B3. Named Tunnel (recommended long-term)

  1. Login:
bash
cloudflared tunnel login
  1. Create:
bash
cloudflared tunnel create openclaw-feishu
  1. Create ~/.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. Run:
bash
cloudflared tunnel --config ~/.cloudflared/config.yml run

Now your domain stays stable across restarts.

Option C: Localtunnel (one-off, least reliable)

C1. Install

bash
npm install -g localtunnel

C2. Run

bash
lt --port 3000 --subdomain openclawvans

You may get:

  • https://openclawvans.loca.lt

Downside: unstable, frequent disconnects, subdomain may be unavailable.

Step 2: Configure Feishu event subscription

In Feishu Open Platform, set the request URL like:

text
https://YOUR_DOMAIN/feishu/events

Feishu validation rules (important)

  • Must be HTTPS
  • Must be a domain
  • Path must match your plugin endpoint exactly

Click “Verify/Subscribe”, Feishu will send a verification request to your URL.

Step 3: Verify and test

3.1 Feishu verification succeeds

If it fails, see Troubleshooting.

3.2 Test in chat

  • Add the bot to a group or DM
  • Send: @bot hello

Success:

  • Bot replies in Feishu
  • Or logs show the event was received and processed

Troubleshooting (most issues land here)

1) “Invalid URL”

  • You used http (must be https)
  • You used an IP (must be domain)
  • Missing/wrong path

2) Timeout during verification

  • Tunnel not running (ngrok/cloudflared stopped)
  • Gateway not running or wrong port
  • Local firewall blocks it

3) Request arrives at tunnel but Feishu still fails

  • Wrong endpoint path (/feishu/events vs /webhook/feishu)
  • Plugin not enabled/config not loaded
  • Token/encryption fields required by plugin but missing

4) Slow network (China)

  • Ngrok may be slow; prefer Cloudflare Tunnel or better region/network

Security notes

Once the tunnel is live, your gateway is exposed publicly:

  • Use pairing/allowlists to restrict who can trigger high-risk actions
  • Prefer “respond only when mentioned” in group chats
  • Expose only required webhook paths (avoid admin/debug endpoints)
  • Never commit appSecret/token to git
  • For long-term use, run on VPS/Docker with a process supervisor (systemd)

Recommendations

  • Quick test: Ngrok
  • Long-term stable: Cloudflare Tunnel (recommended)
  • One-off: Localtunnel (not recommended for production)

References