Feishu

Feishu bot

Feishu (Lark) is a team chat platform used by companies for messaging and collaboration. This plugin connects OpenClaw to a Feishu/Lark bot using the platform’s WebSocket event subscription so messages can be received without exposing a public webhook URL.

Bundled plugin

Feishu ships bundled with current OpenClaw releases, so no separate plugin install is required.

If you are using an older build or a custom install that does not include bundled Feishu, install it manually:

openclaw plugins install @openclaw/feishu

Quickstart

There are two ways to add the Feishu channel:

Method 1: onboarding (recommended)

If you just installed OpenClaw, run onboarding:

openclaw onboard

The wizard guides you through:

Creating a Feishu app and collecting credentials
Configuring app credentials in OpenClaw
Starting the gateway

✅ After configuration, check gateway status:

openclaw gateway status
openclaw logs --follow

Method 2: CLI setup

If you already completed initial install, add the channel via CLI:

openclaw channels add

Choose Feishu, then enter the App ID and App Secret.

✅ After configuration, manage the gateway:

openclaw gateway status
openclaw gateway restart
openclaw logs --follow

Step 1: Create a Feishu app

1. Open Feishu Open Platform

Visit Feishu Open Platform and sign in.

Lark (global) tenants should use https://open.larksuite.com/app and set domain: "lark" in the Feishu config.

2. Create an app

Click Create enterprise app
Fill in the app name + description
Choose an app icon

Create enterprise app

3. Copy credentials

From Credentials & Basic Info, copy:

App ID (format: cli_xxx)
App Secret

❗ Important: keep the App Secret private.

Get credentials

4. Configure permissions

On Permissions, click Batch import and paste:

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

Configure permissions

5. Enable bot capability

In App Capability > Bot:

Enable bot capability
Set the bot name

Enable bot capability

6. Configure event subscription

⚠️ Important: before setting event subscription, make sure:

You already ran openclaw channels add for Feishu
The gateway is running (openclaw gateway status)

In Event Subscription:

Choose Use long connection to receive events (WebSocket)
Add the event: im.message.receive_v1
(Optional) For Drive comment workflows, also add: drive.notice.comment_add_v1

⚠️ If the gateway is not running, the long-connection setup may fail to save.

Configure event subscription

7. Publish the app

Create a version in Version Management & Release
Submit for review and publish
Wait for admin approval (enterprise apps usually auto-approve)

Step 2: Configure OpenClaw

Configure with the wizard (recommended)

openclaw channels add

Choose Feishu and paste your App ID + App Secret.

Configure via config file

Edit ~/.openclaw/openclaw.json:

{
  channels: {
    feishu: {
      enabled: true,
      dmPolicy: "pairing",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "My AI assistant",
        },
      },
    },
  },
}

If you use connectionMode: "webhook", set both verificationToken and encryptKey. The Feishu webhook server binds to 127.0.0.1 by default; set webhookHost only if you intentionally need a different bind address.

Verification Token and Encrypt Key (webhook mode)

When using webhook mode, set both channels.feishu.verificationToken and channels.feishu.encryptKey in your config. To get the values:

In Feishu Open Platform, open your app
Go to Development → Events & Callbacks (开发配置 → 事件与回调)
Open the Encryption tab (加密策略)
Copy Verification Token and Encrypt Key

The screenshot below shows where to find the Verification Token. The Encrypt Key is listed in the same Encryption section.

Verification Token location

Configure via environment variables

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"

Lark (global) domain

If your tenant is on Lark (international), set the domain to lark (or a full domain string). You can set it at channels.feishu.domain or per account (channels.feishu.accounts.<id>.domain).

{
  channels: {
    feishu: {
      domain: "lark",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
        },
      },
    },
  },
}

Quota optimization flags

You can reduce Feishu API usage with two optional flags:

typingIndicator (default true): when false, skip typing reaction calls.
resolveSenderNames (default true): when false, skip sender profile lookup calls.

Set them at top level or per account:

{
  channels: {
    feishu: {
      typingIndicator: false,
      resolveSenderNames: false,
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          typingIndicator: true,
          resolveSenderNames: false,
        },
      },
    },
  },
}

Step 3: Start + test

1. Start the gateway

openclaw gateway

2. Send a test message

In Feishu, find your bot and send a message.

3. Approve pairing

By default, the bot replies with a pairing code. Approve it:

openclaw pairing approve feishu <CODE>

After approval, you can chat normally.

Overview

Feishu bot channel: Feishu bot managed by the gateway
Deterministic routing: replies always return to Feishu
Session isolation: DMs share a main session; groups are isolated
WebSocket connection: long connection via Feishu SDK, no public URL needed

Access control

Direct messages

Default: dmPolicy: "pairing" (unknown users get a pairing code)

Approve pairing:

openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

Allowlist mode: set channels.feishu.allowFrom with allowed Open IDs

Group chats

1. Group policy (channels.feishu.groupPolicy):

"open" = allow everyone in groups
"allowlist" = only allow groupAllowFrom
"disabled" = disable group messages

Default: allowlist

2. Mention requirement (channels.feishu.requireMention, overridable via channels.feishu.groups.<chat_id>.requireMention):

explicit true = require @mention
explicit false = respond without mentions
when unset and groupPolicy: "open" = default to false
when unset and groupPolicy is not "open" = default to true

Group configuration examples

Allow all groups, no @mention required (default for open groups)

{
  channels: {
    feishu: {
      groupPolicy: "open",
    },
  },
}

Allow all groups, but still require @mention

{
  channels: {
    feishu: {
      groupPolicy: "open",
      requireMention: true,
    },
  },
}

Allow specific groups only

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Feishu group IDs (chat_id) look like: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

Restrict which senders can message in a group (sender allowlist)

In addition to allowing the group itself, all messages in that group are gated by the sender open_id: only users listed in groups.<chat_id>.allowFrom have their messages processed; messages from other members are ignored (this is full sender-level gating, not only for control commands like /reset or /new).

{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // Feishu user IDs (open_id) look like: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

Get group/user IDs

Group IDs (chat_id)

Group IDs look like oc_xxx.

Method 1 (recommended)

Start the gateway and @mention the bot in the group
Run openclaw logs --follow and look for chat_id

Method 2

Use the Feishu API debugger to list group chats.

User IDs (open_id)

User IDs look like ou_xxx.

Method 1 (recommended)

Start the gateway and DM the bot
Run openclaw logs --follow and look for open_id

Method 2

Check pairing requests for user Open IDs:

openclaw pairing list feishu

Common commands

Command	Description
`/status`	Show bot status
`/reset`	Reset the session
`/model`	Show/switch model

Note: Feishu does not support native command menus yet, so commands must be sent as text.

Gateway management commands

Command	Description
`openclaw gateway status`	Show gateway status
`openclaw gateway install`	Install/start gateway service
`openclaw gateway stop`	Stop gateway service
`openclaw gateway restart`	Restart gateway service
`openclaw logs --follow`	Tail gateway logs

Troubleshooting

Bot does not respond in group chats

Ensure the bot is added to the group
Ensure you @mention the bot (default behavior)
Check groupPolicy is not set to "disabled"
Check logs: openclaw logs --follow

Bot does not receive messages

Ensure the app is published and approved
Ensure event subscription includes im.message.receive_v1
Ensure long connection is enabled
Ensure app permissions are complete
Ensure the gateway is running: openclaw gateway status
Check logs: openclaw logs --follow

App Secret leak

Reset the App Secret in Feishu Open Platform
Update the App Secret in your config
Restart the gateway

Message send failures

Ensure the app has im:message:send_as_bot permission
Ensure the app is published
Check logs for detailed errors

Advanced configuration

Multiple accounts

{
  channels: {
    feishu: {
      defaultAccount: "main",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "Primary bot",
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          name: "Backup bot",
          enabled: false,
        },
      },
    },
  },
}

defaultAccount controls which Feishu account is used when outbound APIs do not specify an accountId explicitly.

Message limits

textChunkLimit: outbound text chunk size (default: 2000 chars)
mediaMaxMb: media upload/download limit (default: 30MB)

Streaming

Feishu supports streaming replies via interactive cards. When enabled, the bot updates a card as it generates text.

{
  channels: {
    feishu: {
      streaming: true, // enable streaming card output (default true)
      blockStreaming: true, // enable block-level streaming (default true)
    },
  },
}

Set streaming: false to wait for the full reply before sending.

ACP sessions

Feishu supports ACP for:

DMs
group topic conversations

Feishu ACP is text-command driven. There are no native slash-command menus, so use /acp ... messages directly in the conversation.

Persistent ACP bindings

Use top-level typed ACP bindings to pin a Feishu DM or topic conversation to a persistent ACP session.

{
  agents: {
    list: [
      {
        id: "codex",
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
      },
    ],
  },
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "feishu",
        accountId: "default",
        peer: { kind: "direct", id: "ou_1234567890" },
      },
    },
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "feishu",
        accountId: "default",
        peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" },
      },
      acp: { label: "codex-feishu-topic" },
    },
  ],
}

Thread-bound ACP spawn from chat

In a Feishu DM or topic conversation, you can spawn and bind an ACP session in place:

/acp spawn codex --thread here

Notes:

--thread here works for DMs and Feishu topics.
Follow-up messages in the bound DM/topic route directly to that ACP session.
v1 does not target generic non-topic group chats.

Multi-agent routing

Use bindings to route Feishu DMs or groups to different agents.

{
  agents: {
    list: [
      { id: "main" },
      {
        id: "clawd-fan",
        workspace: "/home/user/clawd-fan",
        agentDir: "/home/user/.openclaw/agents/clawd-fan/agent",
      },
      {
        id: "clawd-xi",
        workspace: "/home/user/clawd-xi",
        agentDir: "/home/user/.openclaw/agents/clawd-xi/agent",
      },
    ],
  },
  bindings: [
    {
      agentId: "main",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_xxx" },
      },
    },
    {
      agentId: "clawd-fan",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_yyy" },
      },
    },
    {
      agentId: "clawd-xi",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_zzz" },
      },
    },
  ],
}

Routing fields:

match.channel: "feishu"
match.peer.kind: "direct" or "group"
match.peer.id: user Open ID (ou_xxx) or group ID (oc_xxx)

See Get group/user IDs for lookup tips.

Configuration reference

Full configuration: Gateway configuration

Key options:

Setting	Description	Default
`channels.feishu.enabled`	Enable/disable channel	`true`
`channels.feishu.domain`	API domain (`feishu` or `lark`)	`feishu`
`channels.feishu.connectionMode`	Event transport mode	`websocket`
`channels.feishu.defaultAccount`	Default account ID for outbound routing	`default`
`channels.feishu.verificationToken`	Required for webhook mode	-
`channels.feishu.encryptKey`	Required for webhook mode	-
`channels.feishu.webhookPath`	Webhook route path	`/feishu/events`
`channels.feishu.webhookHost`	Webhook bind host	`127.0.0.1`
`channels.feishu.webhookPort`	Webhook bind port	`3000`
`channels.feishu.accounts.<id>.appId`	App ID	-
`channels.feishu.accounts.<id>.appSecret`	App Secret	-
`channels.feishu.accounts.<id>.domain`	Per-account API domain override	`feishu`
`channels.feishu.dmPolicy`	DM policy	`pairing`
`channels.feishu.allowFrom`	DM allowlist (open_id list)	-
`channels.feishu.groupPolicy`	Group policy	`allowlist`
`channels.feishu.groupAllowFrom`	Group allowlist	-
`channels.feishu.requireMention`	Default require @mention	conditional
`channels.feishu.groups.<chat_id>.requireMention`	Per-group require @mention override	inherited
`channels.feishu.groups.<chat_id>.enabled`	Enable group	`true`
`channels.feishu.textChunkLimit`	Message chunk size	`2000`
`channels.feishu.mediaMaxMb`	Media size limit	`30`
`channels.feishu.streaming`	Enable streaming card output	`true`
`channels.feishu.blockStreaming`	Enable block streaming	`true`

dmPolicy reference

Value	Behavior
`"pairing"`	Default. Unknown users get a pairing code; must be approved
`"allowlist"`	Only users in `allowFrom` can chat
`"open"`	Allow all users (requires `"*"` in allowFrom)
`"disabled"`	Disable DMs

Supported message types

Receive

✅ Text
✅ Rich text (post)
✅ Images
✅ Files
✅ Audio
✅ Video/media
✅ Stickers

Send

✅ Text
✅ Images
✅ Files
✅ Audio
✅ Video/media
✅ Interactive cards
⚠️ Rich text (post-style formatting and cards, not arbitrary Feishu authoring features)

Threads and replies

✅ Inline replies
✅ Topic-thread replies where Feishu exposes reply_in_thread
✅ Media replies stay thread-aware when replying to a thread/topic message

Drive comments

Feishu can trigger the agent when someone adds a comment on a Feishu Drive document (Docs, Sheets, etc.). The agent receives the comment text, document context, and the comment thread so it can respond in-thread or make document edits.

Requirements:

Subscribe to drive.notice.comment_add_v1 in your Feishu app event subscription settings (alongside the existing im.message.receive_v1)
The Drive tool is enabled by default; disable with channels.feishu.tools.drive: false

The feishu_drive tool exposes these comment actions:

Action	Description
`list_comments`	List comments on a document
`list_comment_replies`	List replies in a comment thread
`add_comment`	Add a new top-level comment
`reply_comment`	Reply to an existing comment thread

When the agent handles a Drive comment event, it receives:

the comment text and sender
document metadata (title, type, URL)
the comment thread context for in-thread replies

After making document edits, the agent is guided to use feishu_drive.reply_comment to notify the commenter and then output NO_REPLY to avoid duplicate sends.

Runtime action surface

Feishu currently exposes these runtime actions:

send
read
edit
thread-reply
pin
list-pins
unpin
member-info
channel-info
channel-list
react and reactions when reactions are enabled in config
feishu_drive comment actions: list_comments, list_comment_replies, add_comment, reply_comment

Channels Overview — all supported channels
Pairing — DM authentication and pairing flow
Groups — group chat behavior and mention gating
Channel Routing — session routing for messages
Security — access model and hardening