|
|
---
|
|
|
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 OpenClaw 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 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
|
|
|
|
|
|
---
|
|
|
|
|
|
## Access control
|
|
|
|
|
|
### Direct messages
|
|
|
|
|
|
- **Default**: `dmPolicy: "pairing"` (unknown users get a pairing code)
|
|
|
- **Approve pairing**:
|
|
|
|
|
|
```bash
|
|
|
openclaw pairing list feishu
|
|
|
openclaw 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
|
|
|
- `"allowlist"` = only allow `groupAllowFrom`
|
|
|
- `"disabled"` = disable group messages
|
|
|
|
|
|
Default: `allowlist`
|
|
|
|
|
|
**2. Mention requirement** (`channels.feishu.requireMention`, overridable via `channels.feishu.groups.<chat_id>.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`
|
|
|
|
|
|
---
|
|
|
|
|
|
## Group configuration examples
|
|
|
|
|
|
### Allow all groups, no @mention required (default for open groups)
|
|
|
|
|
|
```json5
|
|
|
{
|
|
|
channels: {
|
|
|
feishu: {
|
|
|
groupPolicy: "open",
|
|
|
},
|
|
|
},
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### Allow all groups, but still require @mention
|
|
|
|
|
|
```json5
|
|
|
{
|
|
|
channels: {
|
|
|
feishu: {
|
|
|
groupPolicy: "open",
|
|
|
requireMention: true,
|
|
|
},
|
|
|
},
|
|
|
}
|
|
|
```
|
|
|
|
|
|
### 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"],
|
|
|
},
|
|
|
},
|
|
|
},
|
|
|
},
|
|
|
}
|
|
|
```
|
|
|
|
|
|
---
|
|
|
|
|
|
<a id="get-groupuser-ids"></a>
|
|
|
|
|
|
## 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 `openclaw 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 `openclaw logs --follow` and look for `open_id`
|
|
|
|
|
|
**Method 2**
|
|
|
|
|
|
Check pairing requests for user Open IDs:
|
|
|
|
|
|
```bash
|
|
|
openclaw 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 |
|
|
|
| -------------------------- | ----------------------------- |
|
|
|
| `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 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 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: `openclaw 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: `openclaw gateway status`
|
|
|
6. Check logs: `openclaw 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",
|
|
|
name: "Primary bot",
|
|
|
},
|
|
|
backup: {
|
|
|
appId: "cli_yyy",
|
|
|
appSecret: "yyy",
|
|
|
name: "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/openclaw",
|
|
|
},
|
|
|
},
|
|
|
},
|
|
|
],
|
|
|
},
|
|
|
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/.openclaw/agents/clawd-fan/agent",
|
|
|
},
|
|
|
{
|
|
|
id: "clawd-xi",
|
|
|
workspace: "/home/user/clawd-xi",
|
|
|
agentDir: "/home/user/.openclaw/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 | `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 |
|
|
|
|
|
|
---
|
|
|
|
|
|
## 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
|
|
|
|
|
|
## 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
|
|
|
|
|
|
- [Channels Overview](/channels) — all supported channels
|
|
|
- [Pairing](/channels/pairing) — DM authentication and pairing flow
|
|
|
- [Groups](/channels/groups) — group chat behavior and mention gating
|
|
|
- [Channel Routing](/channels/channel-routing) — session routing for messages
|
|
|
- [Security](/gateway/security) — access model and hardening
|