OpenClaw Feishu/Lark Integration: Complete Setup Guide

Feishu vs Lark: Two Platforms, One Integration

Feishu and Lark are ByteDance's enterprise messaging platforms — Feishu for mainland China, Lark for international markets. They share the same underlying architecture, which means the integration process is nearly identical regardless of which version your organization uses.

OpenClaw supports two ways to connect with Feishu/Lark:

This guide focuses on the built-in plugin, which handles roughly 90% of use cases. If you need full workspace integration (reading docs, managing calendars, creating tasks), see the Official Feishu Plugin section near the end.

Prerequisites for OpenClaw Feishu Setup

Before you start, make sure you have:

• OpenClaw installed and running (version ≥ 2026.2). If you haven't set it up yet, follow the installation guide.
• A Feishu developer account at open.feishu.cn (or open.larksuite.com for Lark).
• Gateway accessible — confirm with:

openclaw gateway status

No public IP or domain required. The built-in plugin uses WebSocket mode by default, which establishes an outbound connection to Feishu servers. This works behind NATs, firewalls, and most corporate networks without any port forwarding.

Step 1: Create a Feishu/Lark Bot App

Open the Developer Console

Navigate to the developer portal for your platform:

• Feishu (China): open.feishu.cn → Developer Console
• Lark (International): open.larksuite.com → Developer Console

Create the Application

1. Click Create Custom App (or "Enterprise Self-Built Application" depending on your UI language)
2. Fill in the app name — something descriptive like "OpenClaw Assistant"
3. Optionally add an icon and description (this is what users see in the bot directory)

Copy Your Credentials

1. Go to Credentials & Basic Info in the left sidebar
2. Copy the App ID (looks like cli_a5xxxxxxxxxxxxx)
3. Copy the App Secret

⚠️ Keep your App Secret secure. Never commit it to version control, paste it in chat, or include it in screenshots. If it leaks, rotate it immediately from the developer console.

Step 2: Configure Feishu Bot Permissions

Your app needs specific permissions (scopes) to send and receive messages. There are two ways to set this up.

Option A: Batch Import (Recommended)

This is the fastest approach — paste a JSON block and all permissions are enabled at once.

1. In your app's settings, go to Development Settings → Permission Management
2. Click Batch Enable (or "Batch Import Scopes")
3. Paste the following JSON:

{
  "scopes": {
    "tenant": [
      "im:chat", "im:message", "im:message:send_as_bot",
      "im:message.p2p_msg:readonly", "im:message.group_at_msg:readonly",
      "im:message.group_msg", "im:message:readonly", "im:resource",
      "im:chat.members:bot_access",
      "im:chat.access_event.bot_p2p_chat:read",
      "contact:user.employee_id:readonly",
      "application:application:self_manage", "application:bot.menu:write",
      "cardkit:card:write",
      "docs:document.content:read", "sheets:spreadsheet",
      "wiki:wiki:readonly", "event:ip_list"
    ],
    "user": [
      "im:chat.access_event.bot_p2p_chat:read"
    ]
  }
}

4. Click Confirm to apply

Option B: Manual Selection

If batch import isn't available in your console version, enable these permissions individually under Permission Management:

• im:message — Send and receive messages
• im:message:send_as_bot — Send messages as the bot
• im:message.p2p_msg:readonly — Read direct messages
• im:message.group_at_msg:readonly — Read @mention messages in groups
• im:message.group_msg — Read all group messages
• im:resource — Access message resources (images, files)
• im:chat — Access chat metadata
• im:chat.members:bot_access — Check bot membership in chats
• contact:user.employee_id:readonly — Read user IDs
• docs:document.content:read — Read document content (optional, for doc summaries)
• sheets:spreadsheet — Access spreadsheets (optional)
• wiki:wiki:readonly — Read wiki pages (optional)

The document, spreadsheet, and wiki permissions are optional. Only enable them if you want the bot to be able to read and summarize docs that users share in chat.

Step 3: Enable Feishu Bot & Event Subscriptions

Enable Bot Capability

1. In the left sidebar, go to App Capabilities → Bot
2. Toggle the bot capability on
3. Optionally set a bot description and help text

Configure Event Subscriptions

This is the critical step that tells Feishu to forward messages to your OpenClaw instance.

1. Go to Events & Callbacks → Event Subscriptions
2. For Connection Mode, select Long Connection (WebSocket)
3. Add the following events:

The im.message.receive_v1 event is the only strictly required one — without it, your bot won't receive any messages. The reaction events are useful if you want to trigger actions based on emoji responses (e.g., thumbs-up to confirm an action).

⚠️ Without event subscriptions, the chat input box won't appear when users open a conversation with your bot in Feishu/Lark. If users see the bot profile but can't type anything, this is almost certainly the issue.

⚠️ This is the #1 cause of the "app has not established a long connection" error. If you see this error in your logs, double-check that you've added at least the im.message.receive_v1 event and selected Long Connection mode.

Step 4: Publish the Feishu App

Your app won't be visible to users until you publish it.

1. Go to Version Management in the left sidebar
2. Click Create Version
3. Fill in a version number (e.g., 1.0.0) and release notes
4. Click Submit for Review

For internal enterprise apps, approval is usually automatic if you are a tenant admin (or an admin with full scope). If you're a regular developer, the app may go through your organization's configured review process — check with your admin.

Once published:

1. Open Feishu (or Lark) on desktop or mobile
2. Go to the app directory or search bar
3. Search for your app name
4. You should see the bot listed — but don't message it yet. Configure OpenClaw first.

Step 5: Configure OpenClaw Feishu Channel

Quick Setup via CLI

The fastest way to connect:

openclaw channels add    # Select "Feishu", then paste your App ID and Secret
openclaw gateway restart

The CLI walks you through the essential settings interactively.

Manual Configuration

For more control, edit ~/.openclaw/openclaw.json directly:

{
  channels: {
    feishu: {
      enabled: true,
      domain: "feishu",            // Use "lark" for Lark international
      connectionMode: "websocket",
      dmPolicy: "pairing",
      groupPolicy: "open",
      requireMention: true,
      streaming: true,
      typingIndicator: true,
      accounts: {
        main: {
          appId: "cli_a5xxxxxxxxxxxxx",
          appSecret: "your-app-secret",
          botName: "AI Assistant"
        }
      }
    }
  }
}

Configuration Reference

Feishu vs Lark domain: The only difference is the domain field. Set it to "feishu" if your organization uses Feishu (China), or "lark" if you're on Lark (international). Everything else — credentials, permissions, events — works the same way.

Step 6: Start OpenClaw Gateway & Pair Feishu

Launch the Gateway

openclaw gateway           # Start the gateway (foreground)

In a separate terminal, watch the logs:

openclaw logs --follow     # Stream logs in real time

You should see output like:

[feishu] WebSocket connected to wss://open.feishu.cn/...
[feishu] Bot "AI Assistant" is online

Pair Your Account

The default DM policy is pairing, which means new users need to be approved before they can chat with the bot. This prevents unauthorized access.

1. Open Feishu (or Lark) and find your bot
2. Send any message — "hello" works fine
3. Check your terminal. You'll see a pairing request with a code:

[feishu] New pairing request from user_xxxxx (Code: ABC123)

4. Approve the pairing:

openclaw pairing approve feishu ABC123

5. Go back to Feishu/Lark and send another message
6. The AI should respond

Verify Connection

openclaw gateway status

Expected output:

Feishu: connected (websocket)
  Account: main
  Bot: AI Assistant
  Paired users: 1
  Active groups: 0

If the status shows disconnected, check the Troubleshooting section below.

Feishu Group Chat Configuration

By default, groupPolicy: "open" lets the bot join any group it's added to. For tighter control, use an allowlist:

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      requireMention: true,
      groups: {
        "oc_xxxxxxxxx": {           // Feishu chat ID
          agentId: "main",
          requireMention: false      // Override: respond to all messages in this group
        },
        "oc_yyyyyyyyy": {
          agentId: "support",        // Route to a different agent
          requireMention: true
        }
      }
    }
  }
}

To find a group's chat ID, add the bot to the group and check the logs — the ID is printed when the bot joins.

Tip: Set requireMention: true globally and override it per group. This prevents the bot from being noisy in large channels while allowing free-form conversation in dedicated AI groups.

Feishu Webhook Mode Setup

WebSocket is the recommended connection mode, but some corporate networks block persistent outbound WebSocket connections. In that case, switch to webhook mode:

{
  channels: {
    feishu: {
      connectionMode: "webhook",
      verificationToken: "from-feishu-console",
      encryptKey: "from-feishu-console",
      webhookPath: "/feishu/events",
      webhookPort: 3000
    }
  }
}

To get the verification token and encrypt key:

1. In your Feishu app settings, go to Events & Callbacks → Encryption Strategy
2. Copy the Verification Token and Encrypt Key

Then configure the request URL in the Feishu console:

1. Under Events & Callbacks → Event Subscriptions, switch to Push to URL
2. Set the URL to https://your-domain.com/feishu/events
3. Click Verify — Feishu sends a challenge request, and OpenClaw responds automatically

⚠️ Webhook mode requires a publicly accessible URL. You'll need a domain, TLS certificate, and proper firewall rules. For most setups, WebSocket is far simpler.

Multi-Agent Routing for Feishu

If you run multiple AI agents, you can route different conversations to different agents using the top-level bindings array:

{
  bindings: [
    { agentId: "main", match: { channel: "feishu", peer: { kind: "direct" } } },
    { agentId: "support", match: { channel: "feishu", peer: { kind: "direct", id: "ou_xxxxx" } } },
    { agentId: "team-helper", match: { channel: "feishu", peer: { kind: "group", id: "oc_xxxxxxxxx" } } }
  ]
}

This is useful for organizations that want a general-purpose assistant, a customer support agent, and a developer tooling agent — all running through the same Feishu bot but backed by different models and prompts. Direct messages go to the main agent by default, but specific users or groups can be routed to different agents.

Official Feishu Plugin for OpenClaw

The official Feishu plugin is maintained by ByteDance's Feishu/Lark team. Unlike the built-in plugin (which operates as a bot), the official plugin uses OAuth to act on behalf of a user. This gives it access to the full workspace: documents, calendars, tasks, spreadsheets, and wikis.

Requirements

• OpenClaw ≥ 2026.2.26 (Linux/macOS) or ≥ 2026.3.2 (Windows)
• Node.js ≥ 22
• npm available in PATH

Installation

npm config set registry https://registry.npmjs.org
curl -o /tmp/feishu-plugin.tgz https://sf3-cn.feishucdn.com/obj/open-platform-opendoc/4d184b1ba733bae2423a89e196a2ef8f_QATOjKH1WN.tgz
npm install /tmp/feishu-plugin.tgz -g
rm /tmp/feishu-plugin.tgz
feishu-plugin-onboard install

The feishu-plugin-onboard install command launches an interactive setup wizard. It will:

1. Ask for your Feishu App ID and App Secret
2. Open a browser window for OAuth authorization
3. Generate a configuration file at ~/.openclaw/plugins/feishu/config.json
4. Register the plugin with your OpenClaw instance

Post-Installation

After installation, verify the plugin is loaded:

openclaw plugins list

You should see feishu-official in the output. Test it by asking the bot to perform a workspace action:

@Bot Summarize the latest document in the "Engineering" wiki space

Diagnostics

If the plugin isn't working:

feishu-plugin-onboard doctor           # Check for common issues
feishu-plugin-onboard doctor --fix     # Auto-fix detected issues
feishu-plugin-onboard info --all       # Show full plugin info

⚠️ Security consideration: The official plugin accesses your workspace data through your personal OAuth token. This means the bot can read any document, calendar event, or task that you have access to. Do not use the official plugin on shared bots or machines — use it only on personal, secured instances.

Using Both Plugins

You can run the built-in plugin and official plugin simultaneously. The built-in plugin handles messaging, while the official plugin handles workspace actions. OpenClaw routes requests to the appropriate plugin automatically.

To disable the official plugin without uninstalling:

feishu-plugin-onboard disable

Troubleshooting Feishu Integration Issues

"No input box" — users can't type messages to the bot

Cause: Event subscriptions are missing or the app isn't published.

Fix:

1. Confirm im.message.receive_v1 is added under Events & Callbacks
2. Confirm the connection mode is set to Long Connection
3. Confirm the app is published (Version Management → check for an active version)
4. Restart the gateway: openclaw gateway restart

"App has not established a long connection" error

Cause: The Feishu event subscription expects a WebSocket connection, but OpenClaw hasn't connected yet.

Fix:

1. Make sure connectionMode is "websocket" in your config
2. Restart the gateway: openclaw gateway restart
3. Check logs: openclaw logs --follow — look for WebSocket connection messages
4. If behind a strict proxy, check if outbound WebSocket connections are blocked

Bot is online but doesn't respond to messages

Cause: Usually a pairing issue or misconfigured DM policy.

Fix:

1. Check if the user is paired: openclaw pairing list feishu
2. If using pairing mode, approve the user: openclaw pairing approve feishu <CODE>
3. If you want anyone to chat without pairing, set dmPolicy: "open"
4. Check logs for errors: openclaw logs --follow

Bot doesn't respond in group chats

Cause: The bot requires @mention but wasn't mentioned, or group policy blocks the group.

Fix:

1. Make sure groupPolicy is "open" or the group is in the allowlist
2. If requireMention is true, users must @mention the bot
3. Verify the bot is actually a member of the group
4. Check that im:message.group_msg permission is enabled

"Message send failed" or "send_as_bot" errors

Cause: Missing im:message:send_as_bot permission, or the app hasn't been re-published after adding permissions.

Fix:

1. Confirm the permission is enabled in the developer console
2. Create a new version and publish it — permission changes require a new release
3. Restart the gateway

Built-in and official plugins seem to conflict

Cause: Both plugins handling overlapping events, causing duplicate responses.

Fix:

1. This is rare — OpenClaw deduplicates events automatically in most cases. If you do see double responses, disable one:

feishu-plugin-onboard disable    # Disable official plugin
# OR
openclaw channels disable feishu  # Disable built-in plugin

2. In normal operation, both plugins coexist fine: the built-in plugin handles messaging, while the official plugin handles workspace actions (docs, calendar, tasks, etc.)

Windows: ENOENT error when installing official plugin

Cause: npm can't find the downloaded .tgz file, usually a path issue on Windows.

Fix:

1. Use a full absolute path:

npm install C:\Users\YourName\Downloads\feishu-plugin.tgz -g

2. Make sure you're running the terminal as Administrator
3. Verify Node.js ≥ 18: node --version

OpenClaw Feishu Command Reference

FAQ

Do I need a public IP or domain?

No. WebSocket mode (the default) connects outbound from your machine to Feishu's servers. No inbound traffic, no port forwarding, no DNS records. The only exception is webhook mode, which does require a publicly accessible URL.

What's the difference between Feishu and Lark?

Feishu is for mainland China. Lark is the international version. They run on separate infrastructure but have the same features and APIs. The only config difference is the domain field — set it to "feishu" or "lark". Your App ID and Secret work on whichever platform you created them on.

Should I use the built-in plugin or the official plugin?

For messaging — sending and receiving messages, reading shared content in chat — the built-in plugin is all you need. For workspace actions — reading docs, managing calendars, creating tasks, querying spreadsheets — use the official plugin. You can run both simultaneously.

Can I run Feishu alongside other channels?

Yes. OpenClaw supports multiple channels concurrently. You can have Feishu, Telegram, Discord, WhatsApp, and others all running at the same time, each connecting to the same or different agents. Add them with openclaw channels add.

Responses are slow — how do I speed things up?

1. Enable streaming (streaming: true) — this shows partial responses as they're generated, so users see text appearing immediately
2. Check your model — larger models are slower. Try a faster model for routine queries
3. Check network latency — if your OpenClaw instance is far from Feishu's servers, responses will feel slower
4. Review your prompt — long system prompts increase processing time

My App Secret was compromised — what do I do?

1. Go to the Feishu developer console immediately
2. Navigate to Credentials & Basic Info
3. Click Reset next to App Secret
4. Copy the new secret
5. Update ~/.openclaw/openclaw.json with the new value
6. Restart the gateway: openclaw gateway restart
7. The old secret is invalidated instantly — no need to revoke individual sessions

Next Steps After Feishu Setup

Now that your Feishu/Lark integration is up and running, explore what else OpenClaw can do:

• Browse all 50+ supported channels — connect additional platforms
• Skills directory — discover what your AI assistant can do
• Troubleshooting guide — fix common issues across all channels
• Complete beginner guide — learn OpenClaw from scratch
• Telegram integration — add Telegram as another channel
• Discord integration — set up Discord with Gateway Intents