Connect Feishu

What You Need First

• A Feishu account that can create apps in your organisation. If your admin restricts app creation, you will need their help for the release step at the end.
• A running bot. Deploy one from the homepage — either framework works, and the Feishu steps are identical up to the last one.
• A Feishu tenant. Create the app in the Feishu console at open.feishu.cn. Lark, the international edition, runs on its own domain (open.larksuite.com) — the dashboard connect flow validates against Feishu today, so a Lark app’s credentials are rejected there. Lark works on a self-hosted bot, where you set the domain yourself; see the self-hosted sections below.

Step 1 — Create the App and Enable the Bot

1. Open the developer console and choose Create Custom App. Give it the name and icon your colleagues will see.
2. In the left menu, open Add App Capability and enable Bot. Without this the app exists but nobody can message it.

Step 2 — Add the Scopes

Under Permissions & Scopes, add the message scopes. This is the minimum for a bot that reads a message and answers it:

• im:message — read the messages sent to it
• im:message:send_as_bot — reply as the bot
• im:message.p2p_msg:readonly — receive direct messages
• im:message.group_at_msg:readonly — receive group messages that @mention it. Skip this one if the bot will only ever be used in direct messages.
• im:resource — handle images and files in a conversation
• A contact read scope, so the agent can tell who is speaking. Search contact: in the console and take the base read scope your tenant offers — depending on the tenant version that is contact:user.base:readonly or contact:contact.base:readonly.

Scope names differ slightly between tenant versions, so trust the console’s own search over any list, including this one. Add more later if you want the agent to do more; start here so the first connection is not held up by an approval queue.

Step 3 — Copy the App ID and App Secret

Go to Credentials & Basic Info and copy the App ID and the App Secret. Unlike Telegram or Discord, Feishu identifies a bot with a pair of values rather than a single token — so you will paste two things, not one.

The secret is a password. Do not paste it into a chat, a ticket or a shared document, and rotate it in the console if it ever leaks.

Step 4 — Paste Them Into Your Bot

1. Open openclawlaunch.com/dashboard and click Connect Platforms, then the Feishu tile.
2. Choose the instance that should answer in Feishu.
3. Paste the App ID and App Secret, and start the connection.

The credentials are checked against Feishu straight away, so a typo fails here rather than turning into a bot that silently never answers. On OpenClaw the Feishu channel plugin is installed at this moment rather than kept in every container, so give the first connect up to a minute.

Step 5 — Deliver Events Over a Persistent Connection

This is the step people miss, and the reason a bot that looks connected never replies. Feishu has to be told how to deliver incoming messages.

1. Back in the Feishu console, open Events & Callbacks.
2. Click the edit icon beside Subscription mode and choose Receive events through persistent connection. Your bot dials out to Feishu, so there is no public callback URL to expose and nothing to whitelist.
3. Click Add Events and add im.message.receive_v1. When prompted to Add Scopes, accept.

Step 6 — Release the App, Then Say Hello

Feishu apps only reach colleagues once a version is published and, in most organisations, approved by an admin. Create a version and release it.

Then search for the bot by name in Feishu and message it. It replies with a pairing code. Paste that code back into the dashboard to prove the account is yours, and the conversation goes live.

Both frameworks pair on Feishu. OpenClaw pairs unknown direct messages by policy, and Hermes routes any unauthorised direct message through pairing when no allowlist is set — so on either one, expect a code rather than an immediate answer. It is the same handshake as Telegram pairing, and it exists for the same reason: a bot anyone can find is otherwise a bot anyone can use.

Self-Hosted: OpenClaw

Running OpenClaw yourself, the same setup lives in your openclaw.json under channels.feishu. Verified against the shipped 2026.8.1 build:

{
  "channels": {
    "feishu": {
      "enabled": true,
      "dmPolicy": "pairing",
      "connectionMode": "websocket",
      "accounts": {
        "main": {
          "appId": "cli_xxxxxxxxxxxx",
          "appSecret": "xxxxxxxxxxxxxxxxxxxxxxxx"
        }
      }
    }
  },
  "plugins": {
    "entries": {
      "feishu": { "enabled": true }
    }
  }
}

Two things are easy to miss. Feishu is a plugin channel, so the plugins.entries.feishu entry has to be enabled as well as the channel itself — a channel block alone leaves the plugin unloaded and the bot silent. And the credentials sit under an account entry, which is what lets one bot serve several Feishu apps; a single pair may also be written directly as channels.feishu.appId and channels.feishu.appSecret.

The guided route installs the plugin for you rather than making you add it by hand:

openclaw channels login feishu

The channel also accepts allowFrom, groupAllowFrom, groupPolicy, encryptKey and verificationToken. The last two belong to the callback style of event delivery — with a persistent connection you do not need them. Keep dmPolicy on pairing unless you have a specific reason not to.

Self-Hosted: Hermes

Hermes shapes this differently, and copying OpenClaw’s field names across will not work. Feishu is a platform entry with its credentials nested under extra, in snake case:

platforms:
  feishu:
    enabled: true
    extra:
      app_id: cli_xxxxxxxxxxxx
      app_secret: xxxxxxxxxxxxxxxxxxxxxxxx
      domain: feishu          # lark for an international tenant
      connection_mode: websocket

This block in config.yaml is the form our managed containers write, and it is where the domain field lives — the one place a Lark tenant is selected rather than assumed. Upstream also reads the same four values from FEISHU_APP_ID, FEISHU_APP_SECRET, FEISHU_DOMAIN and FEISHU_CONNECTION_MODE if you would rather keep them in the environment. Restart the gateway after changing either: hermes gateway restart.

Groups and Direct Messages

Direct messages are the simple case: one person, one conversation. Group chats are worth thinking about before you invite the bot in.

• Add the bot to a group and it can see what is said there. That is the point, and it is also the privacy question — decide which groups deserve it.
• In a busy group, require a mention so the agent answers when addressed rather than after every message.
• A group is not proof of identity. Keep anything sensitive — credentials, live browser links, account actions — in a direct message.

Troubleshooting

• Connected, but no replies. Almost always the event subscription. Confirm im.message.receive_v1 is added and the subscription mode is the persistent connection, then message the bot again.
• Nobody can find the bot. The app version has not been released, or is waiting on admin approval.
• Credentials rejected. Check you copied the App Secret rather than one of the other credentials on that page, and that the app was created in the Feishu console — a Lark app’s credentials do not authenticate against Feishu, which is what the dashboard connect flow checks against.
• It answers you but not colleagues. That is pairing doing its job on both frameworks. Each person pairs once, or you widen the policy deliberately.
• It stopped after a secret rotation. Reconnect from the dashboard with the new secret; the old one is dead the moment you rotate it.
• A “Cannot find module” error mentioning the Lark SDK. See that specific fix.

What to Do With It

A Feishu bot is most useful where the work already is: summarising a long thread, answering from your documents, filing the thing someone just asked for. Give it skills for the procedures your team repeats, and if you run more than one bot, Skill Sync keeps them consistent.

Related: WeChat, WeChat on Hermes, Slack, Telegram, Hermes hosting.