#Feishu / Lark

Beyond messaging, Feishu offers fourteen feishu_* tools for documents, wikis, Drive, permissions, and Bitable.

Use the supported long-connection transport; it needs no public address.

#What you need

1. Create a custom app in the Feishu or Lark developer console and add a bot to it.
2. Copy the App ID (cli_…) and App Secret.
3. Grant the app scopes. Messaging needs im:message, im:message.group_at_msg, im:message:send_as_bot, im:chat:readonly, and im:resource. Each tool family needs its own: docx:document, drive:drive, wiki:wiki, bitable:app.
4. Add the Connection to Hub (below), so the bot holds its long connection open.
5. Under Events & Callbacks, set the subscription mode to Receive events through persistent connection. The console only saves it while a client is connected, which is why the Connection comes first; Verify shows Connected. Then Add Events: Message received (im.message.receive_v1), Bot added to group (im.chat.member.bot.added_v1) and Bot removed from group (im.chat.member.bot.deleted_v1). The webhook alternative is not supported yet.
6. Under Version Management & Release, create and publish a version. Nothing above reaches the bot until a version with it is released.
7. Add the bot to the chats it should answer in.

Feishu and Lark are the same product on different hosts. domain: lark uses open.larksuite.com, for apps made in the international Lark console; domain: feishu uses open.feishu.cn, for apps made in the mainland China Feishu console. An app exists on one of them only. The app's Add Connection form picks Lark unless you choose Feishu; the CLI secret file defaults to feishu when domain is absent.

#Add it to Hub

The secret file is JSON:

{
  "appId": "cli_...",
  "appSecret": "...",
  "domain": "feishu"
}

The long connection needs the App ID and secret. Hub refuses webhook mode even if its verification token and encrypt key are supplied.

clisbot channels add feishu --account main --secret-file ./feishu-app.json

Hub exchanges the pair for a tenant access token before storing it, so a wrong secret fails at setup rather than at the first message.

#Conversations it handles

Group chats, DMs, and group DMs, with message threads. Inbound covers messages, card clicks as callbacks, and member events.

Use Channel slash commands for session controls, Project/Workspace selection and this channel's invocation forms.

#What the agent can do

Message tool actions: send, thread-reply, read, edit, pin, unpin, list-pins, member-info, channel-info, plus react and reactions when the account enables reactions.

Channel tools, registered on the agent's MCP server and authorized per call:

Tool	What it reaches
feishu_doc	Docx documents
feishu_chat	Chat metadata and membership
feishu_wiki	Wiki spaces and nodes
feishu_drive	Drive files and folders
feishu_perm	Permissions. Off by default.
feishu_app_scopes	What the app is actually allowed to do
feishu_bitable_create_app, _create_field, _create_record, _get_meta, _get_record, _list_fields, _list_records, _update_record	Bitable

feishu_app_scopes is the tool to reach for first when something returns a permission error: it reports the app's granted scopes rather than guessing.

#Limits

• No media in or out. Inbound attachments are not downloaded and there is no upload path.
• No delete, no sticker, no streaming card. Card clicks arrive inbound, but Hub renders no Lark card of its own, so approval prompts are not native.
• No channel webhook transport. Hub supports the long connection only.

#Verified live

Nothing. The tool factories and the send path are driven against a faked Lark SDK client, so the code paths are real but the platform is not. A live run needs Lark app credentials, a group chat the bot belongs to, and a DM target.

#Troubleshooting

Every call returns a permission error. Ask the agent to call feishu_app_scopes. A scope granted in the console still needs the app version published.

The bot connects but never sees a message. The Hub log shows ws client ready and nothing after it. The app has no Message received event, or the version that adds it is not published (steps 5 and 6).

The long connection will not open. Event subscription is not set to Use long connection in the app console.

The log says Incorrect domain name (code 1000040351). The Connection's domain is the other platform from the app's. Add the Connection again with the right Domain. A Connection saved before Hub kept the domain with it falls back to feishu, so a Lark app added that way needs saving again.

Webhook configuration is rejected. Choose the long connection; providing webhook secrets does not enable this transport.

A feishu_perm call says the tool does not exist. It is off by default. Enable it on the account.