Complete OpenClaw Feishu Setup: Connect Your Agent to Feishu

Key takeaways

• OpenClaw connects to Feishu via WebSocket. Your gateway reaches out; Feishu doesn't call back in, so no public IP is needed
• The @openclaw/feishu plugin has shipped built into OpenClaw since v2026.2. Most users don't need to install anything extra
• Enable event subscriptions only after your gateway is running, or the subscription may appear to save but silently fail to deliver events
• v2026.2.14 changed the dmPolicy default from "open" to "pairing" with no config migration. If DMs stopped working after an upgrade, this is why
• Lark (international) users add one config key: domain: "lark". The rest of the setup is identical

This guide covers the full setup path, Lark domain config, and four failure modes that trip up first installs. Three plugins exist for Feishu, each with different tradeoffs. They can't run simultaneously, so pick the right one before you open the Feishu developer console.

OpenClaw Feishu plugin: which one to install

Pick your plugin before you touch the Feishu developer console. The built-in and the official plugin can't run simultaneously (per the AlexAnys/openclaw-feishu community fork, which is community-maintained and not an official OpenClaw project), so choose one and stick with it.

For most people, the built-in plugin is the right call. It handles DMs and group messages well. The Feishu official plugin is worth it if you want document creation or calendar management under your identity. The legacy AlexAnys plugin has no reason to exist unless you're on an older OpenClaw version.

This guide covers the built-in plugin setup.

Step 1: Create the Feishu app

You'll need a Feishu account with app-creation access. Most enterprise Feishu accounts have this by default. Lark international users start at open.larksuite.com instead of open.feishu.cn.

Step 2: Configure OpenClaw for Feishu

Two ways to do this. The wizard is faster.

openclaw channels add

{
  "feishu": {
    "appId": "cli_xxx",
    "appSecret": "your-app-secret",
    "dmPolicy": "open"
  }
}

{
  "feishu": {
    "appId": "cli_xxx",
    "appSecret": "your-app-secret",
    "domain": "lark",
    "dmPolicy": "open"
  }
}

export FEISHU_APP_ID=cli_xxx
export FEISHU_APP_SECRET=your-app-secret

Step 3: Start the gateway and approve pairing

Start the gateway if it isn't running:

openclaw gateway start

Send a direct message to your bot in Feishu. The gateway will log a pairing request. Approve it:

openclaw pairing approve

Check the gateway logs for this line, which confirms the WebSocket connection is live:

[feishu] feishu[default]: bot open_id resolved: ou_xxxxxxxx

If that line doesn't appear, the app isn't connected. Check that the app is published and that event subscription was enabled with the gateway running.

To verify messages are actually arriving, check channel status:

openclaw channels status feishu

Look at lastInboundAt. If it's null after you've sent messages, the channel is configured but nothing is arriving. Source: GitHub issue #11719.

Fix: Event subscription saves before the gateway starts

This is the most common setup failure. You enable event subscription in the Feishu console. It appears to save, but the bot never responds. The official docs mention it in a warning that's easy to miss.

Fix it in three steps:

1. Start the gateway: openclaw gateway start
2. Go back to the Feishu developer console and delete the existing event subscription
3. Re-add im.message.receive_v1 with the gateway running and verify it saves without error

The official OpenClaw docs are explicit: confirm the gateway is running before saving the subscription. Feishu doesn't show a connection indicator on the event subscription page, so there's no visual feedback if the save fails.

Fix: DMs stopped working after upgrading to v2026.2.14

If your bot was working and stopped responding to DMs after an update, this is almost certainly the cause. The v2026.2.14 release changed the dmPolicy default from "open" to "pairing" in bot.ts:557:

const dmPolicy = feishuCfg?.dmPolicy ?? "pairing";

No config migration ran. Any install that relied on the old default silently broke.

Fix: explicitly set dmPolicy in your config and restart:

{
  "feishu": {
    "appId": "cli_xxx",
    "appSecret": "your-app-secret",
    "dmPolicy": "open"
  }
}

Then restart the gateway. If you want pairing behavior instead, you'll need to approve each new user via openclaw pairing approve.

Fix: WebSocket connected but messages are not received

The gateway shows the bot is connected. The open_id resolved. The WS client is ready. But you send a message and nothing logs.

Run:

openclaw channels status feishu

Check lastInboundAt. If it's null or hasn't updated, messages aren't arriving. Two likely causes per GitHub issue #11719:

1. The app isn't published. Go to Version Management and Release in the Feishu developer console and verify a published version exists. Saving a draft isn't sufficient.
2. Event subscription was saved before the gateway started. Delete the subscription, start the gateway, and re-add it.

The Feishu developer console gives no feedback when the subscription fails to connect. You won't see an error. You'll just see silence.

Feishu vs Lark: which domain is yours?

Feishu and Lark are the same product on different infrastructure. Feishu (open.feishu.cn) is for mainland China tenants. Lark (open.larksuite.com) is for international tenants. You can't mix the two.

If your company's Feishu login URL includes "larksuite.com" you're on Lark international. Create your app at open.larksuite.com and add domain: "lark" to your OpenClaw channel config. That's the only difference. Source: docs.openclaw.ai/channels/feishu.

Access control: dmPolicy and group settings

The dmPolicy key controls who can initiate DM conversations with your agent:

Source: docs.openclaw.ai/channels/feishu.

For group chat settings, you can configure whether the agent responds to all messages or only mentions. See the OpenClaw pairing and DM policy guide for the full reference.

Multi-agent routing with Feishu bindings

If you're running multiple OpenClaw agents on one gateway, you can route Feishu DMs or specific group chats to different agents using bindings. A binding targets messages by peer.kind (for DMs) or group ID.

{
  "bindings": [
    {
      "match": { "channel": "feishu", "peer.kind": "group", "groupId": "oc_xxx" },
      "target": "my-other-agent"
    }
  ]
}

Source: docs.openclaw.ai/channels/feishu. A dedicated bindings reference guide is on the backlog.

Key Terms

Feishu / 飞书 is Bytedance's enterprise messaging platform, primarily serving the China market. Lark is the same platform's international brand.

WebSocket long-connection is how OpenClaw receives Feishu events. Your gateway opens an outbound connection to Feishu's servers. No inbound ports needed.

App ID is the public Feishu app credential, in format cli_xxx. App Secret is the private half. Treat it like a password.

dmPolicy is the OpenClaw config key that controls who can DM your agent. The default changed to "pairing" in v2026.2.14.

Bot capability is the Feishu app feature that lets your app send and receive messages under a bot identity. Without it, event subscription won't work.

Event subscription is the Feishu mechanism that pushes message events to your gateway via WebSocket. It must be enabled with the gateway running, and the app must be published for it to activate.

Pairing is OpenClaw's device/user approval flow. When dmPolicy is "pairing", new DM senders appear in a pending list until you run openclaw pairing approve.

FAQ

Does OpenClaw Feishu setup require a public IP address or open server port?

No. OpenClaw uses WebSocket long-connection mode with Feishu. The gateway opens an outbound connection to Feishu's servers. Feishu pushes events over that connection. No inbound port forwarding needed.

How do I approve a Feishu pairing request in OpenClaw?

After sending your first DM to the bot, run openclaw pairing approve from the terminal where your gateway is running. The command lists pending users and prompts for confirmation. Source: docs.openclaw.ai/channels/feishu.

Why did my OpenClaw Feishu bot stop responding to DMs after an upgrade?

The v2026.2.14 update changed the dmPolicy default from "open" to "pairing". Any setup that relied on the old default broke without warning. Fix: add "dmPolicy": "open" to your channel config and restart the gateway.

Can I use OpenClaw with both Feishu domestic and Lark international at the same time?

No. They're separate tenants on different infrastructure. You set up one or the other. For Lark, add domain: "lark" to your config and create your app at open.larksuite.com. Source: docs.openclaw.ai/channels/feishu.

What's the difference between the built-in OpenClaw Feishu plugin and the Feishu official plugin?

The built-in @openclaw/feishu is a bot identity integration, simpler to set up with messaging focus. The Feishu official plugin (community-maintained fork, not an official OpenClaw project) uses OAuth to act as your user identity. That adds document creation and calendar management. They can't run simultaneously.

Evidence & Methodology

Research for this article pulled from the following sources, verified March 2026:

• OpenClaw official Feishu channel docs: primary source for setup steps, permissions JSON, and Lark domain config
• OpenClaw Feishu channel docs: setup steps, permissions JSON, event subscription ordering requirement, dmPolicy configuration reference, and Lark domain config
• GitHub issue #17741: primary source for dmPolicy default change in v2026.2.14, including source code reference
• GitHub issue #11719: WebSocket connected/no messages failure pattern and diagnostic approach
• AlexAnys/openclaw-feishu: community-maintained fork; referenced for plugin comparison and mutual exclusivity behavior

Every specific fact is tied to a named source above. The fix resolution for GitHub issue #11719 wasn't confirmed in the thread. However, the diagnostic steps and root causes appear in the official OpenClaw Feishu docs and the GitHub issue thread.

Related Resources

Internal:

• OpenClaw pairing and DM policy guide
• OpenClaw Telegram Setup Guide
• OpenClaw Discord Setup Guide
• OpenClaw Signal Setup Guide
• OpenClaw CLI Commands Reference
• OpenClaw Universal Troubleshooting

External:

• OpenClaw Feishu channel docs
• GitHub issue #17741: dmPolicy default change

Changelog

• 2026-03-09: Replaced third-party tutorial links with official OpenClaw and Lark documentation
• 2026-03-08: Initial publication