146 lines
4.5 KiB
Markdown
146 lines
4.5 KiB
Markdown
---
|
|
summary: "Feishu bot support status, capabilities, and configuration"
|
|
read_when:
|
|
- You want to connect Clawdbot to Feishu
|
|
- You are debugging Feishu webhook callbacks or long connection events
|
|
---
|
|
|
|
# Feishu (Bot API)
|
|
|
|
Status: experimental. Text messages only (V1). Supports HTTP callback and long connection.
|
|
|
|
## Plugin required
|
|
|
|
Feishu ships as a plugin and is not bundled with the core install.
|
|
|
|
- Install via CLI: `clawdbot plugins install @clawdbot/feishu`
|
|
- Or select **Feishu** during onboarding and confirm the install prompt
|
|
- Details: [Plugins](/plugin)
|
|
|
|
## Quick setup (beginner)
|
|
|
|
1. Install the Feishu plugin:
|
|
- From a source checkout: `clawdbot plugins install ./extensions/feishu`
|
|
- From npm (if published): `clawdbot plugins install @clawdbot/feishu`
|
|
2. Create a Feishu app, enable the bot feature, and get:
|
|
- `appId`
|
|
- `appSecret`
|
|
3. Configure event subscription:
|
|
- Events: subscribe to `im.message.receive_v1`
|
|
- Choose one delivery mode:
|
|
- **Long connection** (no public URL required)
|
|
- **HTTP callback** (public HTTPS webhook required)
|
|
4. Configure Clawdbot (choose one):
|
|
|
|
### Long connection (mode: ws)
|
|
|
|
```json5
|
|
{
|
|
channels: {
|
|
feishu: {
|
|
enabled: true,
|
|
mode: "ws",
|
|
appId: "cli_xxx",
|
|
appSecret: "xxx",
|
|
dm: { policy: "pairing" },
|
|
groupPolicy: "allowlist",
|
|
groups: {
|
|
oc_xxx: { allow: true, requireMention: true },
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
### HTTP callback (mode: http)
|
|
|
|
```json5
|
|
{
|
|
channels: {
|
|
feishu: {
|
|
enabled: true,
|
|
mode: "http",
|
|
appId: "cli_xxx",
|
|
appSecret: "xxx",
|
|
verificationToken: "xxx", // or encryptKey: "xxx"
|
|
webhookPath: "/feishu",
|
|
dm: { policy: "pairing" },
|
|
groupPolicy: "allowlist",
|
|
groups: {
|
|
oc_xxx: { allow: true, requireMention: true },
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
5. Start the gateway. In HTTP callback mode, Feishu will POST to the webhook path.
|
|
6. DM access is pairing by default; approve the pairing code on first contact.
|
|
|
|
## Webhook security (mode: http)
|
|
|
|
The plugin validates webhook requests using one of:
|
|
|
|
- `verificationToken`: checks the token provided in the callback payload.
|
|
- `encryptKey`: validates the Feishu signature header and decrypts encrypted payloads when present.
|
|
|
|
## Group behavior
|
|
|
|
- Default `groupPolicy` is `allowlist`.
|
|
- Groups require mention by default (`requireMention: true`).
|
|
- Configure allowlisted groups by **chat id** under `channels.feishu.groups`.
|
|
|
|
## Public URL (Webhook-only)
|
|
|
|
Feishu webhooks require a public HTTPS endpoint. For security, only expose the `/feishu` path to the internet. Keep the dashboard and other sensitive endpoints on a private network.
|
|
|
|
If you use a reverse proxy like Caddy, only proxy the specific path:
|
|
|
|
```caddy
|
|
your-domain.com {
|
|
reverse_proxy /feishu* localhost:18789
|
|
}
|
|
```
|
|
|
|
## Targets (delivery and allowlists)
|
|
|
|
- Direct message user: `user:<open_id>` (example open id format: `ou_xxx`)
|
|
- Group chat: `chat:<chat_id>` (example chat id format: `oc_xxx`)
|
|
|
|
Example outbound send:
|
|
|
|
```bash
|
|
clawdbot message send --channel feishu --target user:ou_xxx --message "hello"
|
|
```
|
|
|
|
## Configuration reference (Feishu)
|
|
|
|
Full configuration: [Configuration](/gateway/configuration)
|
|
|
|
Provider options:
|
|
|
|
- `channels.feishu.enabled`: enable/disable the channel.
|
|
- `channels.feishu.appId`: Feishu appId.
|
|
- `channels.feishu.appSecret`: Feishu appSecret.
|
|
- `channels.feishu.mode`: `http | ws` (default `http`).
|
|
- `channels.feishu.verificationToken`: webhook verification token.
|
|
- `channels.feishu.encryptKey`: webhook encrypt key (signature validation + optional decryption).
|
|
- `channels.feishu.webhookPath`: webhook path on the gateway HTTP server (default `/feishu`).
|
|
- `channels.feishu.webhookUrl`: optional; used to derive the webhook path.
|
|
- `channels.feishu.dm.policy`: `pairing | allowlist | open | disabled` (default `pairing`).
|
|
- `channels.feishu.dm.allowFrom`: allowlist entries (`ou_...`) or `"*"`.
|
|
- `channels.feishu.groupPolicy`: `allowlist | open | disabled` (default `allowlist`).
|
|
- `channels.feishu.groups.<chatId>`: group allowlist entry and options (`allow`, `requireMention`, `users`, `systemPrompt`).
|
|
|
|
Multi-account options:
|
|
|
|
- `channels.feishu.accounts.<id>.appId`
|
|
- `channels.feishu.accounts.<id>.appSecret`
|
|
- `channels.feishu.accounts.<id>.mode`
|
|
- `channels.feishu.accounts.<id>.verificationToken`
|
|
- `channels.feishu.accounts.<id>.encryptKey`
|
|
- `channels.feishu.accounts.<id>.webhookPath`
|
|
- `channels.feishu.accounts.<id>.webhookUrl`
|
|
- `channels.feishu.accounts.<id>.dm`
|
|
- `channels.feishu.accounts.<id>.groups`
|