OpenClaw Codex

Recipe

Connect OpenClaw to Feishu (Lark)

Feishu (global version: Lark) is one of the most powerful messaging platforms for AI agents. This guide walk you through creating a Feishu App, enabling a Bot, and connecting it to your OpenClaw gateway.

Prerequisites

  • A running OpenClaw gateway (see VPS Deploy Recipe)
  • A public URL for your gateway (via Cloudflare Tunnel or Reverse Proxy)
  • A Feishu/Lark account with permissions to create apps

Step 1 — Create a Feishu App

  1. Go to the Feishu Open Platform.
  2. Click Create Custom App.
  3. Enter a name and description (e.g., "OpenClaw Agent").
  4. Navigate to App Settings → App Credentials and copy your App ID and App Secret.

Step 2 — Enable Bot Capability

  1. In your app sidebar, go to App Capabilities → Bot.
  2. Click Enable Bot.

Step 3 — Configure OpenClaw

Add the Feishu credentials to your secrets.env file.

bash ~/.config/openclaw/secrets.env 
FEISHU_APP_ID=cli_a1b2c3d4e5f6
FEISHU_APP_SECRET=your_app_secret
FEISHU_VERIFICATION_TOKEN=your_token_from_step_4
FEISHU_ENCRYPT_KEY=your_key_from_step_4

Restart your gateway: systemctl --user restart openclaw-gateway.

Step 4 — Event Subscriptions & Webhook

  1. Go to Development Config → Event Subscriptions.
  2. Copy the Verification Token and Encrypt Key and add them to your secrets.env from Step 3.
  3. Set the Request URL to: https://your-public-url.com/webhook/feishu.
  4. Feishu will send a test request. OpenClaw handles this automatically if your Verification Token matches.
  5. Under Add Events, subscribe to:
    • im.message.receive_v1 (Receive messages)
    • im.message.recalled_v1 (Recall messages)

Step 5 — Permissions

Go to Development Config → Permissions and add:

  • im:message (Receive and send messages)
  • im:message.group_at:readonly (Receive messages that @bot in groups)
  • im:message.p2p:msg:readonly (Receive messages in private chats)

Click Apply for release (or use the test version) to activate these permissions.

Step 6 — Test the Bot

  1. Find your bot in Feishu (search for the app name).
  2. Send a message like "Hello".
  3. Check your OpenClaw logs: journalctl --user -u openclaw-gateway -f.
  4. If the bot replies, you're connected!

💡 Troubleshooting

  • Handshake Failed: Ensure your public URL is accessible and the FEISHU_VERIFICATION_TOKEN in your env exactly matches what's in the Feishu console.
  • No Response: Verify the Bot has permission to send messages and the app is in the "Running" state (not just "Developing").
  • EncodingAESKey Errors: If you enabled encryption, ensure FEISHU_ENCRYPT_KEY is correctly set. OpenClaw supports both encrypted and plaintext webhooks.

Related