diff --git a/CHANGELOG.md b/CHANGELOG.md index 274ca2e9975..e3b641955d5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,7 @@ Docs: https://docs.openclaw.ai ### Changes +- Docs/Feishu webhook setup: clarify `verificationToken` configuration with Open Platform navigation steps, and align Feishu sender-allowlist guidance plus zh-CN channel documentation with current runtime behavior. (#31555) - Secrets/SecretRef coverage: expand SecretRef support across the full supported user-supplied credential surface (64 targets total), including runtime collectors, `openclaw secrets` planning/apply/audit flows, onboarding SecretInput UX, and related docs; unresolved refs now fail fast on active surfaces while inactive surfaces report non-blocking diagnostics. (#29580) Thanks @joshavant. - Tools/PDF analysis: add a first-class `pdf` tool with native Anthropic and Google PDF provider support, extraction fallback for non-native models, configurable defaults (`agents.defaults.pdfModel`, `pdfMaxBytesMb`, `pdfMaxPages`), and docs/tests covering routing, validation, and registration. (#31319) Thanks @tyler6204. - Outbound adapters/plugins: add shared `sendPayload` support across direct-text-media, Discord, Slack, WhatsApp, Zalo, and Zalouser with multi-media iteration and chunk-aware text fallback. (#30144) Thanks @nohat. diff --git a/docs/channels/feishu.md b/docs/channels/feishu.md index e20f3f06f88..3158599aa86 100644 --- a/docs/channels/feishu.md +++ b/docs/channels/feishu.md @@ -197,6 +197,17 @@ Edit `~/.openclaw/openclaw.json`: If you use `connectionMode: "webhook"`, set `verificationToken`. 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 (webhook mode) + +When using webhook mode, set `channels.feishu.verificationToken` in your config. To get the value: + +1. In Feishu Open Platform, open your app +2. Go to **Development** → **Events & Callbacks** (开发配置 → 事件与回调) +3. Open the **Encryption** tab (加密策略) +4. Copy **Verification Token** + +![Verification Token location](../images/feishu-verification-token.png) + ### Configure via environment variables ```bash @@ -359,9 +370,9 @@ After approval, you can chat normally. } ``` -### Allow specific users to run control commands in a group (e.g. /reset, /new) +### Restrict which senders can message in a group (sender allowlist) -In addition to allowing the group itself, control commands are gated by the **sender** open_id. +In addition to allowing the group itself, **all messages** in that group are gated by the sender open_id: only users listed in `groups..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 { diff --git a/docs/images/feishu-verification-token.png b/docs/images/feishu-verification-token.png new file mode 100644 index 00000000000..0d6d72d1040 Binary files /dev/null and b/docs/images/feishu-verification-token.png differ diff --git a/docs/zh-CN/channels/feishu.md b/docs/zh-CN/channels/feishu.md index ff569c20e2f..4cc8b578a6a 100644 --- a/docs/zh-CN/channels/feishu.md +++ b/docs/zh-CN/channels/feishu.md @@ -201,6 +201,19 @@ openclaw channels add } ``` +若使用 `connectionMode: "webhook"`，需设置 `verificationToken`。飞书 Webhook 服务默认绑定 `127.0.0.1`；仅在需要不同监听地址时设置 `webhookHost`。 + +#### 获取 Verification Token（仅 Webhook 模式） + +使用 Webhook 模式时，需在配置中设置 `channels.feishu.verificationToken`。获取方式： + +1. 在飞书开放平台打开您的应用 +2. 进入 **开发配置** → **事件与回调** +3. 打开 **加密策略** 选项卡 +4. 复制 **Verification Token**（校验令牌） + +![Verification Token 位置](/images/feishu-verification-token.png) + ### 通过环境变量配置 ```bash @@ -228,6 +241,34 @@ export FEISHU_APP_SECRET="xxx" } ``` +### 配额优化 + +可通过以下可选配置减少飞书 API 调用： + +- `typingIndicator`（默认 `true`）：设为 `false` 时不发送“正在输入”状态。 +- `resolveSenderNames`（默认 `true`）：设为 `false` 时不拉取发送者资料。 + +可在渠道级或账号级配置： + +```json5 +{ + channels: { + feishu: { + typingIndicator: false, + resolveSenderNames: false, + accounts: { + main: { + appId: "cli_xxx", + appSecret: "xxx", + typingIndicator: true, + resolveSenderNames: false, + }, + }, + }, + }, +} +``` + --- ## 第三步：启动并测试 @@ -280,7 +321,7 @@ openclaw pairing approve feishu <配对码> **1. 群组策略**（`channels.feishu.groupPolicy`）： - `"open"` = 允许群组中所有人（默认） -- `"allowlist"` = 仅允许 `groupAllowFrom` 中的用户 +- `"allowlist"` = 仅允许 `groupAllowFrom` 中的群组 - `"disabled"` = 禁用群组消息 **2. @提及要求**（`channels.feishu.groups..requireMention`）： @@ -321,14 +362,36 @@ openclaw pairing approve feishu <配对码> } ``` -### 仅允许特定用户在群组中使用 +### 仅允许特定群组 ```json5 { channels: { feishu: { groupPolicy: "allowlist", - groupAllowFrom: ["ou_xxx", "ou_yyy"], + // 群组 ID 格式为 oc_xxx + groupAllowFrom: ["oc_xxx", "oc_yyy"], + }, + }, +} +``` + +### 仅允许特定成员在群组中发信（发送者白名单） + +除群组白名单外，该群组内**所有消息**均按发送者 open_id 校验：仅 `groups..allowFrom` 中列出的用户消息会被处理，其他成员的消息会被忽略（此为发送者级白名单，不仅针对 /reset、/new 等控制命令）。 + +```json5 +{ + channels: { + feishu: { + groupPolicy: "allowlist", + groupAllowFrom: ["oc_xxx"], + groups: { + oc_xxx: { + // 用户 open_id 格式为 ou_xxx + allowFrom: ["ou_user1", "ou_user2"], + }, + }, }, }, } @@ -428,12 +491,13 @@ openclaw pairing list feishu ### 多账号配置 -如果需要管理多个飞书机器人： +如果需要管理多个飞书机器人，可配置 `defaultAccount` 指定出站未显式指定 `accountId` 时使用的账号： ```json5 { channels: { feishu: { + defaultAccount: "main", accounts: { main: { appId: "cli_xxx", @@ -578,23 +642,29 @@ openclaw pairing list feishu 主要选项： -| 配置项 | 说明 | 默认值 | -| ------------------------------------------------- | ------------------------------ | --------- | -| `channels.feishu.enabled` | 启用/禁用渠道 | `true` | -| `channels.feishu.domain` | API 域名（`feishu` 或 `lark`） | `feishu` | -| `channels.feishu.accounts..appId` | 应用 App ID | - | -| `channels.feishu.accounts..appSecret` | 应用 App Secret | - | -| `channels.feishu.accounts..domain` | 单账号 API 域名覆盖 | `feishu` | -| `channels.feishu.dmPolicy` | 私聊策略 | `pairing` | -| `channels.feishu.allowFrom` | 私聊白名单（open_id 列表） | - | -| `channels.feishu.groupPolicy` | 群组策略 | `open` | -| `channels.feishu.groupAllowFrom` | 群组白名单 | - | -| `channels.feishu.groups..requireMention` | 是否需要 @提及 | `true` | -| `channels.feishu.groups..enabled` | 是否启用该群组 | `true` | -| `channels.feishu.textChunkLimit` | 消息分块大小 | `2000` | -| `channels.feishu.mediaMaxMb` | 媒体大小限制 | `30` | -| `channels.feishu.streaming` | 启用流式卡片输出 | `true` | -| `channels.feishu.blockStreaming` | 启用块级流式 | `true` | +| 配置项 | 说明 | 默认值 | +| ------------------------------------------------- | --------------------------------- | ---------------- | +| `channels.feishu.enabled` | 启用/禁用渠道 | `true` | +| `channels.feishu.domain` | API 域名（`feishu` 或 `lark`） | `feishu` | +| `channels.feishu.connectionMode` | 事件传输模式（websocket/webhook） | `websocket` | +| `channels.feishu.defaultAccount` | 出站路由默认账号 ID | `default` | +| `channels.feishu.verificationToken` | Webhook 模式必填 | - | +| `channels.feishu.webhookPath` | Webhook 路由路径 | `/feishu/events` | +| `channels.feishu.webhookHost` | Webhook 监听地址 | `127.0.0.1` | +| `channels.feishu.webhookPort` | Webhook 监听端口 | `3000` | +| `channels.feishu.accounts..appId` | 应用 App ID | - | +| `channels.feishu.accounts..appSecret` | 应用 App Secret | - | +| `channels.feishu.accounts..domain` | 单账号 API 域名覆盖 | `feishu` | +| `channels.feishu.dmPolicy` | 私聊策略 | `pairing` | +| `channels.feishu.allowFrom` | 私聊白名单（open_id 列表） | - | +| `channels.feishu.groupPolicy` | 群组策略 | `open` | +| `channels.feishu.groupAllowFrom` | 群组白名单 | - | +| `channels.feishu.groups..requireMention` | 是否需要 @提及 | `true` | +| `channels.feishu.groups..enabled` | 是否启用该群组 | `true` | +| `channels.feishu.textChunkLimit` | 消息分块大小 | `2000` | +| `channels.feishu.mediaMaxMb` | 媒体大小限制 | `30` | +| `channels.feishu.streaming` | 启用流式卡片输出 | `true` | +| `channels.feishu.blockStreaming` | 启用块级流式 | `true` | --- @@ -614,6 +684,7 @@ openclaw pairing list feishu ### 接收 - ✅ 文本消息 +- ✅ 富文本（帖子） - ✅ 图片 - ✅ 文件 - ✅ 音频