@quantumclaw/quantumclaw 2026.3.22

package/docs/channels/feishu.md

@@ -0,0 +1,747 @@
+---
+summary: "Feishu bot overview, features, and configuration"
+read_when:
+  - You want to connect a Feishu/Lark bot
+  - You are configuring the Feishu channel
+title: Feishu
+---
+
+# Feishu bot
+
+Feishu (Lark) is a team chat platform used by companies for messaging and collaboration. This plugin connects QuantumClaw 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 QuantumClaw 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:
+
+```bash
+quantumclaw plugins install @quantumclaw/feishu
+```
+
+---
+
+## Quickstart
+
+There are two ways to add the Feishu channel:
+
+### Method 1: onboarding (recommended)
+
+If you just installed QuantumClaw, run onboarding:
+
+```bash
+quantumclaw onboard
+```
+
+The wizard guides you through:
+
+1. Creating a Feishu app and collecting credentials
+2. Configuring app credentials in QuantumClaw
+3. Starting the gateway
+
+✅ **After configuration**, check gateway status:
+
+- `quantumclaw gateway status`
+- `quantumclaw logs --follow`
+
+### Method 2: CLI setup
+
+If you already completed initial install, add the channel via CLI:
+
+```bash
+quantumclaw channels add
+```
+
+Choose **Feishu**, then enter the App ID and App Secret.
+
+✅ **After configuration**, manage the gateway:
+
+- `quantumclaw gateway status`
+- `quantumclaw gateway restart`
+- `quantumclaw logs --follow`
+
+---
+
+## Step 1: Create a Feishu app
+
+### 1. Open Feishu Open Platform
+
+Visit [Feishu Open Platform](https://open.feishu.cn/app) and sign in.
+
+Lark (global) tenants should use [https://open.larksuite.com/app](https://open.larksuite.com/app) and set `domain: "lark"` in the Feishu config.
+
+### 2. Create an app
+
+1. Click **Create enterprise app**
+2. Fill in the app name + description
+3. Choose an app icon
+
+![Create enterprise app](../images/feishu-step2-create-app.png)
+
+### 3. Copy credentials
+
+From **Credentials & Basic Info**, copy:
+
+- **App ID** (format: `cli_xxx`)
+- **App Secret**
+
+❗ **Important:** keep the App Secret private.
+
+![Get credentials](../images/feishu-step3-credentials.png)
+
+### 4. Configure permissions
+
+On **Permissions**, click **Batch import** and paste:
+
+```json
+{
+  "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](../images/feishu-step4-permissions.png)
+
+### 5. Enable bot capability
+
+In **App Capability** > **Bot**:
+
+1. Enable bot capability
+2. Set the bot name
+
+![Enable bot capability](../images/feishu-step5-bot-capability.png)
+
+### 6. Configure event subscription
+
+⚠️ **Important:** before setting event subscription, make sure:
+
+1. You already ran `quantumclaw channels add` for Feishu
+2. The gateway is running (`quantumclaw gateway status`)
+
+In **Event Subscription**:
+
+1. Choose **Use long connection to receive events** (WebSocket)
+2. Add the event: `im.message.receive_v1`
+
+⚠️ If the gateway is not running, the long-connection setup may fail to save.
+
+![Configure event subscription](../images/feishu-step6-event-subscription.png)
+
+### 7. Publish the app
+
+1. Create a version in **Version Management & Release**
+2. Submit for review and publish
+3. Wait for admin approval (enterprise apps usually auto-approve)
+
+---
+
+## Step 2: Configure QuantumClaw
+
+### Configure with the wizard (recommended)
+
+```bash
+quantumclaw channels add
+```
+
+Choose **Feishu** and paste your App ID + App Secret.
+
+### Configure via config file
+
+Edit `~/.quantumclaw/quantumclaw.json`:
+
+```json5
+{
+  channels: {
+    feishu: {
+      enabled: true,
+      dmPolicy: "pairing",
+      accounts: {
+        main: {
+          appId: "cli_xxx",
+          appSecret: "xxx",
+          botName: "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:
+
+1. In Feishu Open Platform, open your app
+2. Go to **Development** → **Events & Callbacks** (开发配置 → 事件与回调)
+3. Open the **Encryption** tab (加密策略)
+4. 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](../images/feishu-verification-token.png)
+
+### Configure via environment variables
+
+```bash
+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`).
+
+```json5
+{
+  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:
+
+```json5
+{
+  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
+
+```bash
+quantumclaw 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:
+
+```bash
+quantumclaw 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**:
+
+  ```bash
+  quantumclaw pairing list feishu
+  quantumclaw 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 (default)
+- `"allowlist"` = only allow `groupAllowFrom`
+- `"disabled"` = disable group messages
+
+**2. Mention requirement** (`channels.feishu.groups.<chat_id>.requireMention`):
+
+- `true` = require @mention (default)
+- `false` = respond without mentions
+
+---
+
+## Group configuration examples
+
+### Allow all groups, require @mention (default)
+
+```json5
+{
+  channels: {
+    feishu: {
+      groupPolicy: "open",
+      // Default requireMention: true
+    },
+  },
+}
+```
+
+### Allow all groups, no @mention required
+
+```json5
+{
+  channels: {
+    feishu: {
+      groups: {
+        oc_xxx: { requireMention: false },
+      },
+    },
+  },
+}
+```
+
+### Allow specific groups only
+
+```json5
+{
+  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).
+
+```json5
+{
+  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)**
+
+1. Start the gateway and @mention the bot in the group
+2. Run `quantumclaw 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)**
+
+1. Start the gateway and DM the bot
+2. Run `quantumclaw logs --follow` and look for `open_id`
+
+**Method 2**
+
+Check pairing requests for user Open IDs:
+
+```bash
+quantumclaw 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                   |
+| -------------------------- | ----------------------------- |
+| `quantumclaw gateway status`  | Show gateway status           |
+| `quantumclaw gateway install` | Install/start gateway service |
+| `quantumclaw gateway stop`    | Stop gateway service          |
+| `quantumclaw gateway restart` | Restart gateway service       |
+| `quantumclaw logs --follow`   | Tail gateway logs             |
+
+---
+
+## Troubleshooting
+
+### Bot does not respond in group chats
+
+1. Ensure the bot is added to the group
+2. Ensure you @mention the bot (default behavior)
+3. Check `groupPolicy` is not set to `"disabled"`
+4. Check logs: `quantumclaw logs --follow`
+
+### Bot does not receive messages
+
+1. Ensure the app is published and approved
+2. Ensure event subscription includes `im.message.receive_v1`
+3. Ensure **long connection** is enabled
+4. Ensure app permissions are complete
+5. Ensure the gateway is running: `quantumclaw gateway status`
+6. Check logs: `quantumclaw logs --follow`
+
+### App Secret leak
+
+1. Reset the App Secret in Feishu Open Platform
+2. Update the App Secret in your config
+3. Restart the gateway
+
+### Message send failures
+
+1. Ensure the app has `im:message:send_as_bot` permission
+2. Ensure the app is published
+3. Check logs for detailed errors
+
+---
+
+## Advanced configuration
+
+### Multiple accounts
+
+```json5
+{
+  channels: {
+    feishu: {
+      defaultAccount: "main",
+      accounts: {
+        main: {
+          appId: "cli_xxx",
+          appSecret: "xxx",
+          botName: "Primary bot",
+        },
+        backup: {
+          appId: "cli_yyy",
+          appSecret: "yyy",
+          botName: "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.
+
+```json5
+{
+  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.
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "codex",
+        runtime: {
+          type: "acp",
+          acp: {
+            agent: "codex",
+            backend: "acpx",
+            mode: "persistent",
+            cwd: "/workspace/quantumclaw",
+          },
+        },
+      },
+    ],
+  },
+  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:
+
+```text
+/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.
+
+```json5
+{
+  agents: {
+    list: [
+      { id: "main" },
+      {
+        id: "clawd-fan",
+        workspace: "/home/user/clawd-fan",
+        agentDir: "/home/user/.quantumclaw/agents/clawd-fan/agent",
+      },
+      {
+        id: "clawd-xi",
+        workspace: "/home/user/clawd-xi",
+        agentDir: "/home/user/.quantumclaw/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](#get-groupuser-ids) for lookup tips.
+
+---
+
+## Configuration reference
+
+Full configuration: [Gateway 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                            | `open`           |
+| `channels.feishu.groupAllowFrom`                  | Group allowlist                         | -                |
+| `channels.feishu.groups.<chat_id>.requireMention` | Require @mention                        | `true`           |
+| `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
+
+## 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