OpenClaw + Feishu: Deploy AI Agents Inside ByteDance's Platform

Most enterprise AI deployments fail at adoption. The tool works perfectly in staging but nobody uses it because it lives in a separate tab, a separate login, a separate context. Feishu solves this problem if you're already inside the ByteDance ecosystem — and OpenClaw gives you the agent brain to make the most of it.

Why Run AI Agents Inside Feishu

Feishu combines messaging, docs, calendar, video, and project management in one platform. For teams already working inside it, adding an AI agent means zero workflow interruption. Your team asks the agent a question, gets an answer, and keeps moving — all without leaving the app they already have open.

Here's what makes the Feishu + OpenClaw combination particularly effective. Feishu's event system is more structured than Slack's — it delivers strongly typed payloads with user IDs, chat IDs, and message metadata consistently. OpenClaw's adapter parses this cleanly, which means your agent has reliable context on who asked what, from where, at what time.

As of early 2025, the OpenClaw Feishu channel adapter is at v1.3 and supports direct messages, group chats, Feishu Docs comments, and event-triggered workflows. That last one — event triggers — is where teams get creative. You can fire an OpenClaw agent task when a Feishu calendar event is created, a document is shared, or a form is submitted.

Create Your Feishu App and Get Credentials

Everything starts in the Feishu Developer Console at open.feishu.cn (or open.larksuite.com for Lark). You need an enterprise account or a developer account to create apps.

1. Log in to the Developer Console and click Create App.
2. Choose Custom App — not a template app. Give it a name your team will recognize, like "AI Assistant" or your product name.
3. On the Credentials page, copy the App ID and App Secret. These are your primary credentials.
4. Navigate to Permissions & Scopes and add: im:message, im:message.group_at_msg, im:chat, contact:user.id:readonly.
5. Under Event Subscriptions, paste your OpenClaw gateway webhook URL and click Verify. The adapter responds to the challenge automatically.
6. Subscribe to these events: im.message.receive_v1 and im.chat.member.bot.added_v1.
7. Click Publish to make the app available inside your organization.

Sound familiar? This is identical to the pattern used by every enterprise bot platform. The key difference with Feishu is step 5 — the challenge verification happens synchronously. Your gateway must be live and reachable before you can complete this step.

Here's where most people stop. They try to verify with localhost and it fails. Use ngrok or Cloudflare Tunnel during development, then switch to your production URL when you deploy. We'll cover this in the Common Mistakes section.

Configure OpenClaw for Feishu

Add the Feishu channel block to your channels.yaml file. The structure mirrors other OpenClaw channel adapters:

channels:
  - type: feishu
    name: feishu-main
    app_id: "cli_your_app_id_here"
    app_secret: "your_app_secret_here"
    verification_token: "your_verification_token"
    encrypt_key: "your_encrypt_key"        # optional but recommended
    group_enabled: true
    mention_only: true                      # only respond when @mentioned in groups
    agent: your-agent-name
    memory_scope: user                      # isolate memory per Feishu user ID

The verification_token comes from the Event Subscriptions page in the Developer Console. The encrypt_key is optional but enables payload encryption — Feishu encrypts the event body before sending it to your webhook, and OpenClaw decrypts it using this key. Turn it on for any production deployment handling sensitive conversations.

Restart your OpenClaw gateway after saving the config. Check the gateway logs for a line confirming the Feishu adapter registered successfully:

[INFO] Channel registered: feishu-main (type=feishu, agent=your-agent-name)
[INFO] Feishu event subscription active, listening on /webhooks/feishu

If you see an error about the verification token, regenerate it in the Developer Console and update your config. Tokens expire if the app is unpublished and republished.

Advanced Features: Cards, Events, and Multi-Agent Routing

Basic message-response is just the start. The Feishu adapter supports three capabilities that take your deployment further.

Feishu Interactive Cards

Feishu's card format lets your agent return structured output — tables, action buttons, dropdown selectors, and form fields — that render natively inside the Feishu app. Configure a card template in your agent's response handler:

response_format:
  type: feishu_card
  template_id: "AAq7..."          # from Feishu Card Builder
  fallback: text                   # send plain text if card rendering fails

Cards are especially useful for approval workflows. Your agent can present a decision card — "Approve / Reject / Request Changes" — and Feishu sends the user's choice back to OpenClaw as a card action event. The agent then processes the action and updates the relevant system.

Calendar and Document Event Triggers

Subscribe to calendar.event.created_v1 and drive.file.created_in_folder_v1 in the Developer Console. When these fire, OpenClaw receives the event and routes it to your configured agent. This is how teams build "AI that watches Feishu and takes action" — the agent notices a new document in the team folder and automatically summarizes it, or sees a new calendar event and prepares a briefing.

Multi-Agent Routing by Chat ID

If you have multiple OpenClaw agents for different functions, route Feishu messages based on the chat or group they originate from. Add routing rules to your channels.yaml:

routing:
  - chat_id: "oc_abc123"       # engineering group
    agent: code-reviewer
  - chat_id: "oc_def456"       # ops group
    agent: ops-assistant
  default_agent: general-assistant

This lets one Feishu app power multiple specialized agents across different teams, with each team getting the agent tuned for their workflow.

Common Mistakes When Connecting OpenClaw to Feishu

• Verifying the webhook with localhost — Feishu makes an outbound HTTP call to verify your endpoint. Localhost is not reachable from Feishu's servers. Use ngrok during development: ngrok http 8080 and paste the forwarding URL into the Developer Console.
• Missing group mention permission — The im:message.group_at_msg scope is separate from im:message. Without it, your bot receives direct messages but is invisible in group chats even when @mentioned.
• Not setting mention_only: true in group chats — Without this, your agent responds to every message in every group it's added to. That's a fast way to annoy your entire team. Default to mention_only and disable it only for dedicated bot channels.
• Hardcoding App Secret in channels.yaml — Use environment variable substitution: app_secret: "${FEISHU_APP_SECRET}". Never commit credentials to version control.
• Ignoring the encrypt_key option — For any deployment handling HR, finance, or customer data, enable payload encryption. Feishu supports it natively and OpenClaw handles decryption transparently — there's no reason to skip it.

Frequently Asked Questions

Does OpenClaw support Feishu out of the box?

OpenClaw includes a Feishu channel adapter from v0.9 onward. Configure it in channels.yaml with your App ID, App Secret, and verification token. No additional SDK installation is required — the adapter handles OAuth, message decryption, and event subscription automatically.

What permissions does the Feishu bot need for OpenClaw?

At minimum: im:message, im:message.group_at_msg, im:chat, and contact:user.id:readonly. For document workflows, add docs:doc:readonly. Request only what your agent actually uses — Feishu's app review rejects over-permissioned bots.

Can OpenClaw agents respond in Feishu group chats?

Yes. Add the bot to any Feishu group and @mention it to trigger the agent. Set group_enabled: true in the Feishu channel block. The agent receives full message thread context and replies in-thread, keeping conversations organized and easy to follow.

How do I handle Feishu's event subscription verification?

Feishu sends a challenge request to your webhook URL during setup. OpenClaw's Feishu adapter responds automatically — you just need your gateway URL to be publicly reachable when you save the event subscription. Localhost URLs will always fail this check. Use ngrok for local testing.

What message types can the OpenClaw Feishu agent send?

The adapter supports text, rich text, image, and file message types. For structured output — tables, action buttons, forms — use Feishu Interactive Cards configured via the card_template field in your agent's response handler. Cards render natively inside Feishu.

Is there a rate limit on Feishu bot messages?

Feishu enforces 5 messages per second per bot for standard apps. For enterprise ISV apps, limits are higher. OpenClaw queues outgoing messages and respects this limit automatically. If you hit it frequently, batch responses into single rich-text cards to reduce message volume.