From 229736e6eceab6ba615fe9e9f862d049241f2853 Mon Sep 17 00:00:00 2001 From: Johnny Date: Mon, 26 Jan 2026 16:06:21 +0800 Subject: [PATCH] docs(feishu): add channel docs --- docs/channels/feishu.md | 119 ++++++++++++++++++++++++++++++++++++++++ docs/channels/index.md | 2 + docs/docs.json | 15 +---- 3 files changed, 124 insertions(+), 12 deletions(-) create mode 100644 docs/channels/feishu.md diff --git a/docs/channels/feishu.md b/docs/channels/feishu.md new file mode 100644 index 000000000..6095e951c --- /dev/null +++ b/docs/channels/feishu.md @@ -0,0 +1,119 @@ +--- +summary: "Feishu bot support status, capabilities, and configuration" +read_when: + - You want to connect Clawdbot to Feishu + - You are debugging Feishu webhook callbacks +--- + +# Feishu (Bot API) + +Status: experimental. HTTP callback only. Text messages only (V1). + +## 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: + - Callback URL: `https://gateway.example.com/feishu` + - Events: subscribe to `im.message.receive_v1` + - Set either a **verification token** or an **encrypt key** +4. Configure Clawdbot: + +```json5 +{ + channels: { + feishu: { + enabled: true, + 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. Feishu will POST to the webhook path. +6. DM access is pairing by default; approve the pairing code on first contact. + +## Webhook security + +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:` (example open id format: `ou_xxx`) +- Group chat: `chat:` (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.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.`: group allowlist entry and options (`allow`, `requireMention`, `users`, `systemPrompt`). + +Multi-account options: + +- `channels.feishu.accounts..appId` +- `channels.feishu.accounts..appSecret` +- `channels.feishu.accounts..verificationToken` +- `channels.feishu.accounts..encryptKey` +- `channels.feishu.accounts..webhookPath` +- `channels.feishu.accounts..webhookUrl` +- `channels.feishu.accounts..dm` +- `channels.feishu.accounts..groups` diff --git a/docs/channels/index.md b/docs/channels/index.md index 52e963b87..9542bb52c 100644 --- a/docs/channels/index.md +++ b/docs/channels/index.md @@ -4,6 +4,7 @@ read_when: - You want to choose a chat channel for Clawdbot - You need a quick overview of supported messaging platforms --- + # Chat Channels Clawdbot can talk to you on any chat app you already use. Each channel connects via the Gateway. @@ -16,6 +17,7 @@ Text is supported everywhere; media and reactions vary by channel. - [Discord](/channels/discord) — Discord Bot API + Gateway; supports servers, channels, and DMs. - [Slack](/channels/slack) — Bolt SDK; workspace apps. - [Google Chat](/channels/googlechat) — Google Chat API app via HTTP webhook. +- [Feishu](/channels/feishu) — Feishu Bot API via HTTP callback (plugin, installed separately). - [Mattermost](/channels/mattermost) — Bot API + WebSocket; channels, groups, DMs (plugin, installed separately). - [Signal](/channels/signal) — signal-cli; privacy-focused. - [BlueBubbles](/channels/bluebubbles) — **Recommended for iMessage**; uses the BlueBubbles macOS server REST API with full feature support (edit, unsend, effects, reactions, group management — edit currently broken on macOS 26 Tahoe). diff --git a/docs/docs.json b/docs/docs.json index 983585bff..5f2f8b412 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -809,11 +809,7 @@ }, { "group": "Help", - "pages": [ - "help/index", - "help/troubleshooting", - "help/faq" - ] + "pages": ["help/index", "help/troubleshooting", "help/faq"] }, { "group": "Install & Updates", @@ -944,13 +940,7 @@ }, { "group": "Web & Interfaces", - "pages": [ - "web", - "web/control-ui", - "web/dashboard", - "web/webchat", - "tui" - ] + "pages": ["web", "web/control-ui", "web/dashboard", "web/webchat", "tui"] }, { "group": "Channels", @@ -962,6 +952,7 @@ "channels/discord", "channels/slack", "channels/googlechat", + "channels/feishu", "channels/mattermost", "channels/signal", "channels/imessage",