OpenClaw

OpenClaw Feishu / Lark Channel

Enterprise
Medium

Connect OpenClaw to Feishu (飞书) or Lark using WebSocket-based event subscription. This enterprise integration lets your AI assistant handle direct messages and group chats on Feishu/Lark — China's leading workplace collaboration platform by ByteDance. OpenClaw connects via the Feishu Open Platform's long-connection (WebSocket) mode, so no public URL or webhook endpoint is required. Just create a Feishu app, enter your App ID and App Secret, and your assistant is live.

Quick Info
DifficultyMedium
CategoryEnterprise
Features Supported3 / 6

Feishu / Lark Supported Features

Text Messages

Supported

Media & Files

Supported

Reactions

Not Supported

Threads

Not Supported

Voice Messages

Not Supported

Group Chat

Supported

Feishu / Lark Prerequisites

  • A Feishu (feishu.cn) or Lark (larksuite.com) tenant account with app creation access
  • The Feishu plugin installed: openclaw plugins install @openclaw/feishu
  • OpenClaw Gateway running and configured
  • Node.js 18+ installed on your server

Feishu / Lark Quick Setup

1

Create a Feishu/Lark app

Visit the Feishu Open Platform (open.feishu.cn/app) or Lark Developer Console (open.larksuite.com/app) for international tenants. Create a new enterprise app, set the name, description, and icon. Copy the App ID (format: cli_xxx) and App Secret from the Credentials page.

2

Configure permissions and bot capability

In the app's Permissions section, batch-import the required permissions. Enable the Bot capability under App Capability > Bot. In Event Subscription, select 'Use long connection' (WebSocket mode) and add the 'im.message.receive_v1' event. Publish the app through Version Management & Release.

3

Add Feishu channel config to OpenClaw

Run 'openclaw channels add' and select Feishu, or manually add the channel configuration to ~/.openclaw/openclaw.json with your appId and appSecret. You can also use environment variables FEISHU_APP_ID and FEISHU_APP_SECRET.

4

Start Gateway and test

Run 'openclaw gateway' to start the service. Send a direct message to your bot in Feishu. If using the default pairing policy, approve the sender via 'openclaw pairing approve feishu <code>' in your terminal.

Feishu / Lark Configuration Example

config.json
{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "YOUR_APP_SECRET",
          "botName": "My AI Assistant"
        }
      }
    }
  }
}

Feishu / Lark Deep Dive

Architecture Overview

OpenClaw connects to Feishu through the Feishu Open Platform's WebSocket-based long-connection mode. Unlike traditional webhook setups, this approach doesn't require a public URL or firewall configuration — the Gateway initiates an outbound WebSocket connection to Feishu's servers and receives events in real-time. The flow is: User sends a message in Feishu → Feishu Open Platform → WebSocket push to your Gateway → OpenClaw processes with AI → reply via Feishu Bot API → message delivered in Feishu. This architecture is ideal for self-hosted deployments behind NATs or corporate firewalls, as no inbound connections are needed. The Gateway maintains the WebSocket connection and automatically handles reconnection.
WebSocket mode (long connection) is recommended over webhook mode — no public URL, no SSL certificate, and works behind firewalls.
The Feishu plugin is installed separately via 'openclaw plugins install @openclaw/feishu', keeping the core Gateway lightweight.

Feishu App Setup & Credentials

Setting up the Feishu integration requires creating an app on the Feishu Open Platform: 1. Visit open.feishu.cn/app (or open.larksuite.com/app for Lark) and create a new Enterprise App. 2. In Credentials & Basic Info, copy the App ID (format: cli_xxx) and App Secret — these are your authentication credentials. 3. Under Permissions & Scopes, batch-import the required permissions for messaging. Key permissions include im:message, im:message:send_as_bot, and im:chat. 4. Enable Bot capability under App Capability > Bot. Set a bot name and description. 5. In Event Subscription, select 'Use long connection' (WebSocket mode) and add the im.message.receive_v1 event to receive incoming messages. 6. Submit the app for release through Version Management & Release. The app must be published and approved before it can receive messages.
terminal
# Via environment variables
export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="your_app_secret"

# Or via CLI wizard
openclaw channels add
Keep your App Secret secure. Never commit it to version control. Use environment variables (FEISHU_APP_SECRET) for production deployments. If compromised, reset the secret immediately in the Feishu Open Platform console.

Feishu vs Lark Configuration

Feishu (feishu.cn) is the domestic Chinese version, while Lark (larksuite.com) is the international version. Both use the same protocol but connect to different API endpoints. By default, OpenClaw connects to the Feishu (domestic) API. If you're using Lark for international tenants, set the domain to 'lark' in your configuration. This switches all API calls to Lark's endpoints automatically.
openclaw.json
{
  "channels": {
    "feishu": {
      "domain": "lark",
      "accounts": {
        "main": {
          "appId": "cli_xxx",
          "appSecret": "YOUR_APP_SECRET"
        }
      }
    }
  }
}
Use 'feishu' (default) for domestic Chinese tenants and 'lark' for international tenants. The domain setting affects API endpoints, not the app creation platform.

DM Policies

DM (Direct Message) policies control who can interact with your AI assistant in private chats. OpenClaw supports four policies: • pairing (default) — New users must go through a pairing flow. They send a message, receive a pairing code, and you approve or deny via the CLI. Once approved, they can chat freely. • allowlist — Only Feishu Open IDs explicitly listed in allowFrom can message the bot. Everyone else is silently ignored. • open — Anyone who messages the bot gets a response. Use with caution. • disabled — DM functionality is completely turned off.
openclaw.json
{
  "channels": {
    "feishu": {
      "dmPolicy": "allowlist",
      "allowFrom": ["ou_xxx", "ou_yyy"]
    }
  }
}
To find a user's Open ID (format: ou_xxx), have them DM the bot and check the Gateway logs, or use 'openclaw pairing list feishu'.

Group Chat Management

OpenClaw supports Feishu group chats with flexible access control: • open (default) — Any group member can trigger the bot when it's @mentioned. • allowlist — Only approved users in the group can interact with the bot. • disabled — Group messages are completely ignored. By default, the bot requires @mention in groups (requireMention: true). This prevents the bot from responding to every message in busy group chats. You can disable this to make the bot respond to all messages. Group Chat IDs (format: oc_xxx) can be found in the Gateway logs when the bot receives a message in a group. Add the bot to a group, @mention it, and check 'openclaw logs --follow'.
openclaw.json
{
  "channels": {
    "feishu": {
      "groupPolicy": "open",
      "requireMention": true
    }
  }
}
To find Group Chat IDs (oc_xxx), start the Gateway, @mention the bot in a group, and check the logs: openclaw logs --follow

Streaming Replies via Interactive Cards

OpenClaw supports streaming AI responses in Feishu using interactive cards. When enabled, the bot sends an initial card that updates progressively as the AI generates its response — similar to how ChatGPT streams text in real-time. This provides a much better user experience compared to waiting for the complete response before sending. The streaming card updates happen in-place, so the chat doesn't get flooded with multiple messages.
openclaw.json
{
  "channels": {
    "feishu": {
      "streaming": true
    }
  }
}
Streaming is enabled by default. Set streaming: false to disable it and send complete responses as regular text messages instead.

Message Types & Media Support

OpenClaw handles various Feishu message types: Inbound (receive): Text messages, rich text (posts), images, files, audio, video, and stickers. All supported message types are processed and forwarded to the AI. Outbound (send): Text messages, images, files, and audio. Rich text support is partial — the bot primarily responds with plain text or streaming cards. Media files are subject to size limits. The default maximum for media downloads is 30 MB (mediaMaxMb). Large files beyond this limit are skipped with a log warning.
openclaw.json
{
  "channels": {
    "feishu": {
      "mediaMaxMb": 30,
      "textChunkLimit": 2000
    }
  }
}

Multiple Accounts & Multi-Agent Routing

OpenClaw supports running multiple Feishu bot accounts simultaneously. Each account has its own App ID, App Secret, and bot name. This is useful for organizations that need separate bots for different teams or purposes. You can also configure multi-agent routing, where different AI agents handle different conversations based on peer bindings. For example, one agent handles DMs while another handles group chats, or different agents serve different Feishu groups.
openclaw.json
{
  "channels": {
    "feishu": {
      "accounts": {
        "support": {
          "appId": "cli_aaa",
          "appSecret": "secret_a",
          "botName": "Support Bot"
        },
        "hr": {
          "appId": "cli_bbb",
          "appSecret": "secret_b",
          "botName": "HR Bot"
        }
      }
    }
  }
}

Useful Commands

OpenClaw provides several built-in commands for managing your Feishu bot: • /status — Show current bot status and connection info • /reset — Reset the current conversation session • /model — Show or switch the active AI model • openclaw gateway status — Check Gateway connection status • openclaw gateway restart — Restart the Gateway service • openclaw logs --follow — View real-time Gateway logs • openclaw pairing list feishu — List all approved and pending pairings • openclaw pairing approve feishu <code> — Approve a pending pairing request

Feishu / Lark Configuration Reference

enabled
Type: booleanDefault: true

Enable or disable the Feishu channel

domain
Type: stringDefault: "feishu"

API domain: 'feishu' for domestic (feishu.cn) or 'lark' for international (larksuite.com)

dmPolicy
Type: stringDefault: "pairing"

Controls who can DM the bot. Options: pairing, allowlist, open, disabled

allowFrom
Type: string[]Default: []

Open IDs (ou_xxx) allowed to message the bot when dmPolicy is 'allowlist'

groupPolicy
Type: stringDefault: "open"

Group chat policy. Options: open, allowlist, disabled

requireMention
Type: booleanDefault: true

Whether the bot requires @mention to respond in group chats

streaming
Type: booleanDefault: true

Enable streaming AI responses via interactive cards

textChunkLimit
Type: numberDefault: 2000

Maximum characters per text message chunk

mediaMaxMb
Type: numberDefault: 30

Maximum media file size in megabytes for uploads and downloads

accounts.<id>.appId
Type: stringDefault: ""

Feishu App ID (format: cli_xxx) from the Open Platform console

accounts.<id>.appSecret
Type: stringDefault: ""

Feishu App Secret from the Open Platform console

accounts.<id>.botName
Type: stringDefault: ""

Display name of the bot in Feishu chats

historyLimit
Type: numberDefault: 50

Number of recent messages to include as AI context

Feishu / Lark Frequently Asked Questions

Feishu / Lark Troubleshooting

Bot is unresponsive in group chats

The bot may not be added to the group, @mention is not working, or groupPolicy is set to 'disabled'.

Verify the bot is added to the group. Check that groupPolicy is not 'disabled'. Try @mentioning the bot by name. Check Gateway logs with 'openclaw logs --follow' for errors.
No messages received — bot is completely silent

The app may not be published, event subscription is not configured, or permissions are missing.

Confirm the app is published and approved in Version Management & Release. Verify that 'Use long connection' is selected in Event Subscription and the im.message.receive_v1 event is added. Check that all required permissions are imported. Ensure the Gateway is running with 'openclaw gateway status'.
Messages fail to send

The im:message:send_as_bot permission may not be granted, or the app hasn't been published.

Ensure the im:message:send_as_bot permission is granted in the app's Permissions section. Re-publish the app if you recently added permissions. Check Gateway logs for specific error messages.
App Secret leaked or compromised

The App Secret was accidentally committed to version control or shared insecurely.

Immediately reset the App Secret in the Feishu Open Platform console (Credentials page). Update your OpenClaw configuration or environment variables with the new secret. Restart the Gateway with 'openclaw gateway restart'.
WebSocket connection drops frequently

Network instability or firewall interfering with long-lived WebSocket connections.

Check your server's network stability. Ensure your firewall allows outbound WebSocket connections. The Gateway automatically reconnects, but frequent drops may indicate network issues. Check logs for reconnection patterns.
View Full DocumentationBack to All Channels

Related Channels

Slack

Medium

OpenClaw workspace app via Bolt SDK

Setup Guide

Google Chat

Medium

OpenClaw Google Chat API app via HTTP endpoint

Setup Guide

Microsoft Teams

Medium

OpenClaw enterprise integration via Bot Framework

Setup Guide