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)

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)

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

C) Port check

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

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

ngrok authtoken YOUR_AUTHTOKEN

A2. Create a tunnel

Assuming port 3000:

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:

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)

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:

cloudflared tunnel login

2. Create:

cloudflared tunnel create openclaw-feishu

3. Create ~/.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. Run:

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

Now your domain stays stable across restarts.

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

C1. Install

npm install -g localtunnel

C2. Run

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:

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

• Feishu Open Platform
• Ngrok Docs
• Cloudflare Tunnel Docs
• Localtunnel GitHub