Use this file to discover all available pages before exploring further.

Feishu

Feishu / Lark

Feishu/Lark is an all-in-one collaboration platform where teams chat, share documents, manage calendars, and get work done together.

Status: production-ready for bot DMs + group chats. WebSocket is the default mode; webhook mode is optional.

Quick start

note

Requires OpenClaw 2026.4.25 or above. Run `openclaw --version` to check. Upgrade with `openclaw update`.

Run the channel setup wizard

```bash} openclaw channels login --channel feishu ```


text
Scan the QR code with your Feishu/Lark mobile app to create a Feishu/Lark bot automatically.

After setup completes, restart the gateway to apply the changes

```bash} openclaw gateway restart ```

Access control

Direct messages

Configure

text

dmPolicy

to control who can DM the bot:

text
"pairing"
— unknown users receive a pairing code; approve via CLI
text
"allowlist"
— only users listed in
text
allowFrom
can chat (default: bot owner only)
text
"open"
— allow public DMs only when
text
allowFrom
includes
text
"*"
; with restrictive entries, only matching users can chat
text
"disabled"
— disable all DMs

Approve a pairing request:


bash
openclaw pairing list feishu
openclaw pairing approve feishu <CODE>

Group chats

Group policy (

text

channels.feishu.groupPolicy

Value	Behavior
text `"open"`	Respond to all messages in groups
text `"allowlist"`	Only respond to groups in text `groupAllowFrom` or explicitly configured under text `groups.<chat_id>`
text `"disabled"`	Disable all group messages; explicit text `groups.<chat_id>` entries do not override this

Default:

text

allowlist

Mention requirement (

text

channels.feishu.requireMention

text
true
— require @mention (default)
text
false
— respond without @mention
Per-group override:
text
channels.feishu.groups.<chat_id>.requireMention
Broadcast-only
text
@all
and
text
@_all
are not treated as bot mentions. A message that mentions both
text
@all
and the bot directly still counts as a bot mention.

Group configuration examples

Allow all groups, no @mention required


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

Allow all groups, still require @mention


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

Allow specific groups only


json5
{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      // Group IDs look like: oc_xxx
      groupAllowFrom: ["oc_xxx", "oc_yyy"],
    },
  },
}

text

allowlist

mode, you can also admit a group by adding an explicit

text

groups.<chat_id>

entry. Explicit entries do not override

text

groupPolicy: "disabled"

. Wildcard defaults under

text

groups.*

configure matching groups, but they do not admit groups by themselves.


json5
{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groups: {
        oc_xxx: {
          requireMention: false,
        },
      },
    },
  },
}

Restrict senders within a group


json5
{
  channels: {
    feishu: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["oc_xxx"],
      groups: {
        oc_xxx: {
          // User open_ids look like: ou_xxx
          allowFrom: ["ou_user1", "ou_user2"],
        },
      },
    },
  },
}

Get group/user IDs

Group IDs (
text
`chat_id`
, format:
text
`oc_xxx`
)

Open the group in Feishu/Lark, click the menu icon in the top-right corner, and go to Settings. The group ID (

text

chat_id

) is listed on the settings page.

Get Group ID

User IDs (
text
`open_id`
, format:
text
`ou_xxx`
)

Start the gateway, send a DM to the bot, then check the logs:


bash
openclaw logs --follow

Look for

text

open_id

in the log output. You can also check pending pairing requests:


bash
openclaw pairing list feishu

Common commands

Command	Description
text `/status`	Show bot status
text `/reset`	Reset the current session
text `/model`	Show or switch the AI model

note

Feishu/Lark does not support native slash-command menus, so send these as plain text messages.

Troubleshooting

Bot does not respond in group chats

Ensure the bot is added to the group
Ensure you @mention the bot (required by default)
Verify
text
groupPolicy
is not
text
"disabled"
Check logs:
text
openclaw logs --follow

Bot does not receive messages

Ensure the bot is published and approved in Feishu Open Platform / Lark Developer
Ensure event subscription includes
text
im.message.receive_v1
Ensure persistent connection (WebSocket) is selected
Ensure all required permission scopes are granted
Ensure the gateway is running:
text
openclaw gateway status
Check logs:
text
openclaw logs --follow

App Secret leaked

Reset the App Secret in Feishu Open Platform / Lark Developer
Update the value in your config
Restart the gateway:
text
openclaw gateway restart

Advanced configuration

Multiple accounts


json5
{
  channels: {
    feishu: {
      defaultAccount: "main",
      accounts: {
        main: {
          appId: "cli_xxx",
          appSecret: "xxx",
          name: "Primary bot",
          tts: {
            providers: {
              openai: { voice: "shimmer" },
            },
          },
        },
        backup: {
          appId: "cli_yyy",
          appSecret: "yyy",
          name: "Backup bot",
          enabled: false,
        },
      },
    },
  },
}

text

defaultAccount

controls which account is used when outbound APIs do not specify an

text

accountId

text

accounts.<id>.tts

uses the same shape as

text

messages.tts

and deep-merges over global TTS config, so multi-bot Feishu setups can keep shared provider credentials globally while overriding only voice, model, persona, or auto mode per account.

Message limits

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

Streaming

Feishu/Lark supports streaming replies via interactive cards. When enabled, the bot updates the card in real time as it generates text.


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

Set

text

streaming: false

to send the complete reply in one message.

Quota optimization

Reduce the number of Feishu/Lark API calls with two optional flags:

text
typingIndicator
(default
text
true
): set
text
false
to skip typing reaction calls
text
resolveSenderNames
(default
text
true
): set
text
false
to skip sender profile lookups


json5
{
  channels: {
    feishu: {
      typingIndicator: false,
      resolveSenderNames: false,
    },
  },
}

ACP sessions

Feishu/Lark supports ACP for DMs and group thread messages. Feishu/Lark ACP is text-command driven — there are no native slash-command menus, so use

text

/acp ...

messages directly in the conversation.

Persistent ACP binding


json5
{
  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" },
    },
  ],
}

Spawn ACP from chat

In a Feishu/Lark DM or thread:


text
/acp spawn codex --thread here

text

--thread here

works for DMs and Feishu/Lark thread messages. Follow-up messages in the bound conversation route directly to that ACP session.

Multi-agent routing

Use

text

bindings

to route Feishu/Lark DMs or groups to different agents.


json5
{
  agents: {
    list: [
      { id: "main" },
      { id: "agent-a", workspace: "/home/user/agent-a" },
      { id: "agent-b", workspace: "/home/user/agent-b" },
    ],
  },
  bindings: [
    {
      agentId: "agent-a",
      match: {
        channel: "feishu",
        peer: { kind: "direct", id: "ou_xxx" },
      },
    },
    {
      agentId: "agent-b",
      match: {
        channel: "feishu",
        peer: { kind: "group", id: "oc_zzz" },
      },
    },
  ],
}

Routing fields:

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

See Get group/user IDs for lookup tips.

Configuration reference

Full configuration: Gateway configuration

Setting	Description	Default
text `channels.feishu.enabled`	Enable/disable the channel	text `true`
text `channels.feishu.domain`	API domain ( text `feishu` or text `lark` )	text `feishu`
text `channels.feishu.connectionMode`	Event transport ( text `websocket` or text `webhook` )	text `websocket`
text `channels.feishu.defaultAccount`	Default account for outbound routing	text `default`
text `channels.feishu.verificationToken`	Required for webhook mode	—
text `channels.feishu.encryptKey`	Required for webhook mode	—
text `channels.feishu.webhookPath`	Webhook route path	text `/feishu/events`
text `channels.feishu.webhookHost`	Webhook bind host	text `127.0.0.1`
text `channels.feishu.webhookPort`	Webhook bind port	text `3000`
text `channels.feishu.accounts.<id>.appId`	App ID	—
text `channels.feishu.accounts.<id>.appSecret`	App Secret	—
text `channels.feishu.accounts.<id>.domain`	Per-account domain override	text `feishu`
text `channels.feishu.accounts.<id>.tts`	Per-account TTS override	text `messages.tts`
text `channels.feishu.dmPolicy`	DM policy	text `allowlist`
text `channels.feishu.allowFrom`	DM allowlist (open_id list)	[BotOwnerId]
text `channels.feishu.groupPolicy`	Group policy	text `allowlist`
text `channels.feishu.groupAllowFrom`	Group allowlist	—
text `channels.feishu.requireMention`	Require @mention in groups	text `true`
text `channels.feishu.groups.<chat_id>.requireMention`	Per-group @mention override; explicit IDs also admit the group in allowlist mode	inherited
text `channels.feishu.groups.<chat_id>.enabled`	Enable/disable a specific group	text `true`
text `channels.feishu.textChunkLimit`	Message chunk size	text `2000`
text `channels.feishu.mediaMaxMb`	Media size limit	text `30`
text `channels.feishu.streaming`	Streaming card output	text `true`
text `channels.feishu.blockStreaming`	Block-level streaming	text `true`
text `channels.feishu.typingIndicator`	Send typing reactions	text `true`
text `channels.feishu.resolveSenderNames`	Resolve sender display names	text `true`

Supported message types

Receive

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

Inbound Feishu/Lark audio messages are normalized as media placeholders instead of raw

text

file_key

JSON. When

text

tools.media.audio

is configured, OpenClaw downloads the voice-note resource and runs shared audio transcription before the agent turn, so the agent receives the spoken transcript. If Feishu includes transcript text directly in the audio payload, that text is used without another ASR call. Without an audio transcription provider, the agent still receives a

text

<media:audio>

placeholder plus the saved attachment, not the raw Feishu resource payload.

Send

✅ Text
✅ Images
✅ Files
✅ Audio
✅ Video/media
✅ Interactive cards (including streaming updates)
⚠️ Rich text (post-style formatting; doesn't support full Feishu/Lark authoring capabilities)

Native Feishu/Lark audio bubbles use the Feishu

text

audio

message type and require Ogg/Opus upload media (

text

file_type: "opus"

). Existing

text

.opus

and

text

.ogg

media is sent directly as native audio. MP3/WAV/M4A and other likely audio formats are transcoded to 48kHz Ogg/Opus with

text

ffmpeg

only when the reply requests voice delivery (

text

audioAsVoice

/ message tool

text

asVoice

, including TTS voice-note replies). Ordinary MP3 attachments stay regular files. If

text

ffmpeg

is missing or conversion fails, OpenClaw falls back to a file attachment and logs the reason.

Threads and replies

✅ Inline replies
✅ Thread replies
✅ Media replies stay thread-aware when replying to a thread message

For

text

groupSessionScope: "group_topic"

and

text

"group_topic_sender"

, native Feishu/Lark topic groups use the event

text

thread_id

(

text

omt_*

) as the canonical topic session key. Normal group replies that OpenClaw turns into threads keep using the reply root message ID (

text

om_*

) so the first turn and follow-up turn stay in the same session.

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

OpenClaw Docs

Feishu

Feishu / Lark

Quick start

note

Run the channel setup wizard

After setup completes, restart the gateway to apply the changes

Access control

Direct messages

Group chats

Group configuration examples

Allow all groups, no @mention required

Allow all groups, still require @mention

Allow specific groups only

Restrict senders within a group

Get group/user IDs

Group IDs (
text
`chat_id`
, format:
text
`oc_xxx`
)

User IDs (
text
`open_id`
, format:
text
`ou_xxx`
)

Common commands

note

Troubleshooting

Bot does not respond in group chats

Bot does not receive messages

App Secret leaked

Advanced configuration

Multiple accounts

Message limits

Streaming

Quota optimization

ACP sessions

Persistent ACP binding

Spawn ACP from chat

Multi-agent routing

Configuration reference

Supported message types

Receive

Send

Threads and replies

Related

OpenClaw Docs

Feishu

Feishu / Lark

Quick start

note

Run the channel setup wizard

After setup completes, restart the gateway to apply the changes

Access control

Direct messages

Group chats

Group configuration examples

Allow all groups, no @mention required

Allow all groups, still require @mention

Allow specific groups only

Restrict senders within a group

Get group/user IDs

Group IDs (textCopychat_id, format: textCopyoc_xxx)

User IDs (textCopyopen_id, format: textCopyou_xxx)

Common commands

note

Troubleshooting

Bot does not respond in group chats

Bot does not receive messages

App Secret leaked

Advanced configuration

Multiple accounts

Message limits

Streaming

Quota optimization

ACP sessions

Persistent ACP binding

Spawn ACP from chat

Multi-agent routing

Configuration reference

Supported message types

Receive

Send

Threads and replies

Related

Group IDs (
text
`chat_id`
, format:
text
`oc_xxx`
)

User IDs (
text
`open_id`
, format:
text
`ou_xxx`
)