mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 13:20:43 +00:00
feat: Streamline Feishu channel onboarding with QR code scan-to-create flow (#65680)
Add QR-based app registration, improve Feishu onboarding flows, support direct login entry, add group chat policy setup, reduce log noise, and update docs.
This commit is contained in:
mazhe-nerd
@@ -6,296 +6,32 @@ read_when:
|
||||
title: Feishu
|
||||
---
|
||||
|
||||
# Feishu bot
|
||||
# Feishu / Lark
|
||||
|
||||
Feishu (Lark) is a team chat platform used by companies for messaging and collaboration. This plugin connects OpenClaw to a Feishu/Lark bot using the platform’s WebSocket event subscription so messages can be received without exposing a public webhook URL.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Bundled plugin
|
||||
|
||||
Feishu ships bundled with current OpenClaw 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
|
||||
openclaw plugins install @openclaw/feishu
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quickstart
|
||||
|
||||
There are two ways to add the Feishu channel:
|
||||
|
||||
### Method 1: onboarding (recommended)
|
||||
|
||||
If you just installed OpenClaw, run onboarding:
|
||||
|
||||
```bash
|
||||
openclaw onboard
|
||||
```
|
||||
|
||||
The wizard guides you through:
|
||||
|
||||
1. Creating a Feishu app and collecting credentials
|
||||
2. Configuring app credentials in OpenClaw
|
||||
3. Starting the gateway
|
||||
|
||||
✅ **After configuration**, check gateway status:
|
||||
|
||||
- `openclaw gateway status`
|
||||
- `openclaw logs --follow`
|
||||
|
||||
### Method 2: CLI setup
|
||||
|
||||
If you already completed initial install, add the channel via CLI:
|
||||
|
||||
```bash
|
||||
openclaw channels add
|
||||
```
|
||||
|
||||
Choose **Feishu**, then enter the App ID and App Secret.
|
||||
|
||||
✅ **After configuration**, manage the gateway:
|
||||
|
||||
- `openclaw gateway status`
|
||||
- `openclaw gateway restart`
|
||||
- `openclaw 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
|
||||
|
||||
|
||||
|
||||
### 3. Copy credentials
|
||||
|
||||
From **Credentials & Basic Info**, copy:
|
||||
|
||||
- **App ID** (format: `cli_xxx`)
|
||||
- **App Secret**
|
||||
|
||||
❗ **Important:** keep the App Secret private.
|
||||
|
||||
|
||||
|
||||
### 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"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
### 5. Enable bot capability
|
||||
|
||||
In **App Capability** > **Bot**:
|
||||
|
||||
1. Enable bot capability
|
||||
2. Set the bot name
|
||||
|
||||
|
||||
|
||||
### 6. Configure event subscription
|
||||
|
||||
⚠️ **Important:** before setting event subscription, make sure:
|
||||
|
||||
1. You already ran `openclaw channels add` for Feishu
|
||||
2. The gateway is running (`openclaw gateway status`)
|
||||
|
||||
In **Event Subscription**:
|
||||
|
||||
1. Choose **Use long connection to receive events** (WebSocket)
|
||||
2. Add the event: `im.message.receive_v1`
|
||||
3. (Optional) For Drive comment workflows, also add: `drive.notice.comment_add_v1`
|
||||
|
||||
⚠️ If the gateway is not running, the long-connection setup may fail to save.
|
||||
|
||||
|
||||
|
||||
### 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 OpenClaw
|
||||
|
||||
### Configure with the wizard (recommended)
|
||||
|
||||
```bash
|
||||
openclaw channels add
|
||||
```
|
||||
|
||||
Choose **Feishu** and paste your App ID + App Secret.
|
||||
|
||||
### Configure via config file
|
||||
|
||||
Edit `~/.openclaw/openclaw.json`:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
feishu: {
|
||||
enabled: true,
|
||||
dmPolicy: "pairing",
|
||||
accounts: {
|
||||
main: {
|
||||
appId: "cli_xxx",
|
||||
appSecret: "xxx",
|
||||
name: "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.
|
||||
|
||||
|
||||
|
||||
### 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
|
||||
openclaw 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
|
||||
openclaw 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
|
||||
## Quick start
|
||||
|
||||
> **Requires OpenClaw 2026.4.10 or above.** Run `openclaw --version` to check. Upgrade with `openclaw update`.
|
||||
|
||||
<Steps>
|
||||
<Step title="Run the channel setup wizard">
|
||||
```bash
|
||||
openclaw channels login --channel feishu
|
||||
```
|
||||
Scan the QR code with your Feishu/Lark mobile app to create a Feishu/Lark bot automatically.
|
||||
</Step>
|
||||
|
||||
<Step title="After setup completes, restart the gateway to apply the changes">
|
||||
```bash
|
||||
openclaw gateway restart
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
---
|
||||
|
||||
@@ -303,38 +39,43 @@ After approval, you can chat normally.
|
||||
|
||||
### Direct messages
|
||||
|
||||
- **Default**: `dmPolicy: "pairing"` (unknown users get a pairing code)
|
||||
- **Approve pairing**:
|
||||
Configure `dmPolicy` to control who can DM the bot:
|
||||
|
||||
```bash
|
||||
openclaw pairing list feishu
|
||||
openclaw pairing approve feishu <CODE>
|
||||
```
|
||||
- `"pairing"` — unknown users receive a pairing code; approve via CLI
|
||||
- `"allowlist"` — only users listed in `allowFrom` can chat (default: bot owner only)
|
||||
- `"open"` — allow all users
|
||||
- `"disabled"` — disable all DMs
|
||||
|
||||
- **Allowlist mode**: set `channels.feishu.allowFrom` with allowed Open IDs
|
||||
**Approve a pairing request:**
|
||||
|
||||
```bash
|
||||
openclaw pairing list feishu
|
||||
openclaw pairing approve feishu <CODE>
|
||||
```
|
||||
|
||||
### Group chats
|
||||
|
||||
**1. Group policy** (`channels.feishu.groupPolicy`):
|
||||
**Group policy** (`channels.feishu.groupPolicy`):
|
||||
|
||||
- `"open"` = allow everyone in groups
|
||||
- `"allowlist"` = only allow `groupAllowFrom`
|
||||
- `"disabled"` = disable group messages
|
||||
| Value | Behavior |
|
||||
| ------------- | ------------------------------------------ |
|
||||
| `"open"` | Respond to all messages in groups |
|
||||
| `"allowlist"` | Only respond to groups in `groupAllowFrom` |
|
||||
| `"disabled"` | Disable all group messages |
|
||||
|
||||
Default: `allowlist`
|
||||
|
||||
**2. Mention requirement** (`channels.feishu.requireMention`, overridable via `channels.feishu.groups.<chat_id>.requireMention`):
|
||||
**Mention requirement** (`channels.feishu.requireMention`):
|
||||
|
||||
- explicit `true` = require @mention
|
||||
- explicit `false` = respond without mentions
|
||||
- when unset and `groupPolicy: "open"` = default to `false`
|
||||
- when unset and `groupPolicy` is not `"open"` = default to `true`
|
||||
- `true` — require @mention (default)
|
||||
- `false` — respond without @mention
|
||||
- Per-group override: `channels.feishu.groups.<chat_id>.requireMention`
|
||||
|
||||
---
|
||||
|
||||
## Group configuration examples
|
||||
|
||||
### Allow all groups, no @mention required (default for open groups)
|
||||
### Allow all groups, no @mention required
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -346,7 +87,7 @@ Default: `allowlist`
|
||||
}
|
||||
```
|
||||
|
||||
### Allow all groups, but still require @mention
|
||||
### Allow all groups, still require @mention
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -366,16 +107,14 @@ Default: `allowlist`
|
||||
channels: {
|
||||
feishu: {
|
||||
groupPolicy: "allowlist",
|
||||
// Feishu group IDs (chat_id) look like: oc_xxx
|
||||
// Group IDs 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).
|
||||
### Restrict senders within a group
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -385,7 +124,7 @@ In addition to allowing the group itself, **all messages** in that group are gat
|
||||
groupAllowFrom: ["oc_xxx"],
|
||||
groups: {
|
||||
oc_xxx: {
|
||||
// Feishu user IDs (open_id) look like: ou_xxx
|
||||
// User open_ids look like: ou_xxx
|
||||
allowFrom: ["ou_user1", "ou_user2"],
|
||||
},
|
||||
},
|
||||
@@ -396,35 +135,23 @@ In addition to allowing the group itself, **all messages** in that group are gat
|
||||
|
||||
---
|
||||
|
||||
<a id="get-groupuser-ids"></a>
|
||||
|
||||
## Get group/user IDs
|
||||
|
||||
### Group IDs (chat_id)
|
||||
### Group IDs (`chat_id`, format: `oc_xxx`)
|
||||
|
||||
Group IDs look like `oc_xxx`.
|
||||
Open the group in Feishu/Lark, click the menu icon in the top-right corner, and go to **Settings**. The group ID (`chat_id`) is listed on the settings page.
|
||||
|
||||
**Method 1 (recommended)**
|
||||
|
||||
|
||||
1. Start the gateway and @mention the bot in the group
|
||||
2. Run `openclaw logs --follow` and look for `chat_id`
|
||||
### User IDs (`open_id`, format: `ou_xxx`)
|
||||
|
||||
**Method 2**
|
||||
Start the gateway, send a DM to the bot, then check the logs:
|
||||
|
||||
Use the Feishu API debugger to list group chats.
|
||||
```bash
|
||||
openclaw logs --follow
|
||||
```
|
||||
|
||||
### User IDs (open_id)
|
||||
|
||||
User IDs look like `ou_xxx`.
|
||||
|
||||
**Method 1 (recommended)**
|
||||
|
||||
1. Start the gateway and DM the bot
|
||||
2. Run `openclaw logs --follow` and look for `open_id`
|
||||
|
||||
**Method 2**
|
||||
|
||||
Check pairing requests for user Open IDs:
|
||||
Look for `open_id` in the log output. You can also check pending pairing requests:
|
||||
|
||||
```bash
|
||||
openclaw pairing list feishu
|
||||
@@ -434,23 +161,13 @@ openclaw pairing list feishu
|
||||
|
||||
## Common commands
|
||||
|
||||
| Command | Description |
|
||||
| --------- | ----------------- |
|
||||
| `/status` | Show bot status |
|
||||
| `/reset` | Reset the session |
|
||||
| `/model` | Show/switch model |
|
||||
| Command | Description |
|
||||
| --------- | --------------------------- |
|
||||
| `/status` | Show bot status |
|
||||
| `/reset` | Reset the current session |
|
||||
| `/model` | Show or switch the AI model |
|
||||
|
||||
> Note: Feishu does not support native command menus yet, so commands must be sent as text.
|
||||
|
||||
## Gateway management commands
|
||||
|
||||
| Command | Description |
|
||||
| -------------------------- | ----------------------------- |
|
||||
| `openclaw gateway status` | Show gateway status |
|
||||
| `openclaw gateway install` | Install/start gateway service |
|
||||
| `openclaw gateway stop` | Stop gateway service |
|
||||
| `openclaw gateway restart` | Restart gateway service |
|
||||
| `openclaw logs --follow` | Tail gateway logs |
|
||||
> Feishu/Lark does not support native slash-command menus, so send these as plain text messages.
|
||||
|
||||
---
|
||||
|
||||
@@ -459,30 +176,24 @@ openclaw pairing list feishu
|
||||
### 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"`
|
||||
2. Ensure you @mention the bot (required by default)
|
||||
3. Verify `groupPolicy` is not `"disabled"`
|
||||
4. Check logs: `openclaw logs --follow`
|
||||
|
||||
### Bot does not receive messages
|
||||
|
||||
1. Ensure the app is published and approved
|
||||
1. Ensure the bot is published and approved in Feishu Open Platform / Lark Developer
|
||||
2. Ensure event subscription includes `im.message.receive_v1`
|
||||
3. Ensure **long connection** is enabled
|
||||
4. Ensure app permissions are complete
|
||||
3. Ensure **persistent connection** (WebSocket) is selected
|
||||
4. Ensure all required permission scopes are granted
|
||||
5. Ensure the gateway is running: `openclaw gateway status`
|
||||
6. Check logs: `openclaw logs --follow`
|
||||
|
||||
### App Secret leak
|
||||
### App Secret leaked
|
||||
|
||||
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
|
||||
1. Reset the App Secret in Feishu Open Platform / Lark Developer
|
||||
2. Update the value in your config
|
||||
3. Restart the gateway: `openclaw gateway restart`
|
||||
|
||||
---
|
||||
|
||||
@@ -513,42 +224,53 @@ openclaw pairing list feishu
|
||||
}
|
||||
```
|
||||
|
||||
`defaultAccount` controls which Feishu account is used when outbound APIs do not specify an `accountId` explicitly.
|
||||
`defaultAccount` controls which account is used when outbound APIs do not specify an `accountId`.
|
||||
|
||||
### Message limits
|
||||
|
||||
- `textChunkLimit`: outbound text chunk size (default: 2000 chars)
|
||||
- `mediaMaxMb`: media upload/download limit (default: 30MB)
|
||||
- `textChunkLimit` — outbound text chunk size (default: `2000` chars)
|
||||
- `mediaMaxMb` — media upload/download limit (default: `30` MB)
|
||||
|
||||
### Streaming
|
||||
|
||||
Feishu supports streaming replies via interactive cards. When enabled, the bot updates a card as it generates text.
|
||||
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)
|
||||
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.
|
||||
Set `streaming: false` to send the complete reply in one message.
|
||||
|
||||
### Quota optimization
|
||||
|
||||
Reduce the number of Feishu/Lark API calls with two optional flags:
|
||||
|
||||
- `typingIndicator` (default `true`): set `false` to skip typing reaction calls
|
||||
- `resolveSenderNames` (default `true`): set `false` to skip sender profile lookups
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
feishu: {
|
||||
typingIndicator: false,
|
||||
resolveSenderNames: false,
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### ACP sessions
|
||||
|
||||
Feishu supports ACP for:
|
||||
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 `/acp ...` messages directly in the conversation.
|
||||
|
||||
- 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.
|
||||
#### Persistent ACP binding
|
||||
|
||||
```json5
|
||||
{
|
||||
@@ -592,58 +314,39 @@ Use top-level typed ACP bindings to pin a Feishu DM or topic conversation to a p
|
||||
}
|
||||
```
|
||||
|
||||
#### Thread-bound ACP spawn from chat
|
||||
#### Spawn ACP from chat
|
||||
|
||||
In a Feishu DM or topic conversation, you can spawn and bind an ACP session in place:
|
||||
In a Feishu/Lark DM or thread:
|
||||
|
||||
```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.
|
||||
`--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 `bindings` to route Feishu DMs or groups to different agents.
|
||||
Use `bindings` to route Feishu/Lark DMs or groups to different agents.
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
list: [
|
||||
{ id: "main" },
|
||||
{
|
||||
id: "clawd-fan",
|
||||
workspace: "/home/user/clawd-fan",
|
||||
agentDir: "/home/user/.openclaw/agents/clawd-fan/agent",
|
||||
},
|
||||
{
|
||||
id: "clawd-xi",
|
||||
workspace: "/home/user/clawd-xi",
|
||||
agentDir: "/home/user/.openclaw/agents/clawd-xi/agent",
|
||||
},
|
||||
{ id: "agent-a", workspace: "/home/user/agent-a" },
|
||||
{ id: "agent-b", workspace: "/home/user/agent-b" },
|
||||
],
|
||||
},
|
||||
bindings: [
|
||||
{
|
||||
agentId: "main",
|
||||
agentId: "agent-a",
|
||||
match: {
|
||||
channel: "feishu",
|
||||
peer: { kind: "direct", id: "ou_xxx" },
|
||||
},
|
||||
},
|
||||
{
|
||||
agentId: "clawd-fan",
|
||||
match: {
|
||||
channel: "feishu",
|
||||
peer: { kind: "direct", id: "ou_yyy" },
|
||||
},
|
||||
},
|
||||
{
|
||||
agentId: "clawd-xi",
|
||||
agentId: "agent-b",
|
||||
match: {
|
||||
channel: "feishu",
|
||||
peer: { kind: "group", id: "oc_zzz" },
|
||||
@@ -656,7 +359,7 @@ Use `bindings` to route Feishu DMs or groups to different agents.
|
||||
Routing fields:
|
||||
|
||||
- `match.channel`: `"feishu"`
|
||||
- `match.peer.kind`: `"direct"` or `"group"`
|
||||
- `match.peer.kind`: `"direct"` (DM) or `"group"` (group chat)
|
||||
- `match.peer.id`: user Open ID (`ou_xxx`) or group ID (`oc_xxx`)
|
||||
|
||||
See [Get group/user IDs](#get-groupuser-ids) for lookup tips.
|
||||
@@ -667,44 +370,33 @@ See [Get group/user IDs](#get-groupuser-ids) for lookup tips.
|
||||
|
||||
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 | `allowlist` |
|
||||
| `channels.feishu.groupAllowFrom` | Group allowlist | - |
|
||||
| `channels.feishu.requireMention` | Default require @mention | conditional |
|
||||
| `channels.feishu.groups.<chat_id>.requireMention` | Per-group require @mention override | inherited |
|
||||
| `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 |
|
||||
| Setting | Description | Default |
|
||||
| ------------------------------------------------- | ------------------------------------------ | ---------------- |
|
||||
| `channels.feishu.enabled` | Enable/disable the channel | `true` |
|
||||
| `channels.feishu.domain` | API domain (`feishu` or `lark`) | `feishu` |
|
||||
| `channels.feishu.connectionMode` | Event transport (`websocket` or `webhook`) | `websocket` |
|
||||
| `channels.feishu.defaultAccount` | Default account 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 domain override | `feishu` |
|
||||
| `channels.feishu.dmPolicy` | DM policy | `allowlist` |
|
||||
| `channels.feishu.allowFrom` | DM allowlist (open_id list) | [BotOwnerId] |
|
||||
| `channels.feishu.groupPolicy` | Group policy | `allowlist` |
|
||||
| `channels.feishu.groupAllowFrom` | Group allowlist | — |
|
||||
| `channels.feishu.requireMention` | Require @mention in groups | `true` |
|
||||
| `channels.feishu.groups.<chat_id>.requireMention` | Per-group @mention override | inherited |
|
||||
| `channels.feishu.groups.<chat_id>.enabled` | Enable/disable a specific group | `true` |
|
||||
| `channels.feishu.textChunkLimit` | Message chunk size | `2000` |
|
||||
| `channels.feishu.mediaMaxMb` | Media size limit | `30` |
|
||||
| `channels.feishu.streaming` | Streaming card output | `true` |
|
||||
| `channels.feishu.blockStreaming` | Block-level streaming | `true` |
|
||||
| `channels.feishu.typingIndicator` | Send typing reactions | `true` |
|
||||
| `channels.feishu.resolveSenderNames` | Resolve sender display names | `true` |
|
||||
|
||||
---
|
||||
|
||||
@@ -727,62 +419,16 @@ Key options:
|
||||
- ✅ Files
|
||||
- ✅ Audio
|
||||
- ✅ Video/media
|
||||
- ✅ Interactive cards
|
||||
- ⚠️ Rich text (post-style formatting and cards, not arbitrary Feishu authoring features)
|
||||
- ✅ Interactive cards (including streaming updates)
|
||||
- ⚠️ Rich text (post-style formatting; doesn't support full Feishu/Lark authoring capabilities)
|
||||
|
||||
### 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
|
||||
- ✅ Thread replies
|
||||
- ✅ Media replies stay thread-aware when replying to a thread message
|
||||
|
||||
## Drive comments
|
||||
|
||||
Feishu can trigger the agent when someone adds a comment on a Feishu Drive document (Docs, Sheets,
|
||||
etc.). The agent receives the comment text, document context, and the comment thread so it can
|
||||
respond in-thread or make document edits.
|
||||
|
||||
Requirements:
|
||||
|
||||
- Subscribe to `drive.notice.comment_add_v1` in your Feishu app event subscription settings
|
||||
(alongside the existing `im.message.receive_v1`)
|
||||
- The Drive tool is enabled by default; disable with `channels.feishu.tools.drive: false`
|
||||
|
||||
The `feishu_drive` tool exposes these comment actions:
|
||||
|
||||
| Action | Description |
|
||||
| ---------------------- | ----------------------------------- |
|
||||
| `list_comments` | List comments on a document |
|
||||
| `list_comment_replies` | List replies in a comment thread |
|
||||
| `add_comment` | Add a new top-level comment |
|
||||
| `reply_comment` | Reply to an existing comment thread |
|
||||
|
||||
When the agent handles a Drive comment event, it receives:
|
||||
|
||||
- the comment text and sender
|
||||
- document metadata (title, type, URL)
|
||||
- the comment thread context for in-thread replies
|
||||
|
||||
After making document edits, the agent is guided to use `feishu_drive.reply_comment` to notify the
|
||||
commenter and then output the exact silent token `NO_REPLY` / `no_reply` to
|
||||
avoid duplicate sends.
|
||||
|
||||
## 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
|
||||
- `feishu_drive` comment actions: `list_comments`, `list_comment_replies`, `add_comment`, `reply_comment`
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
|
||||
Reference in New Issue
Block a user