docs(feishu): Feishu docs – add verificationToken and align zh-CN with EN (openclaw#31555) thanks @xbsheng

Verified: - pnpm build - pnpm test:macmini - pnpm check (blocked locally by pre-existing mainline lint issue in src/scripts/ci-changed-scope.test.ts unrelated to this PR) Co-authored-by: xbsheng <56357338+xbsheng@users.noreply.github.com> Co-authored-by: Tak Hoffman <781889+Takhoffman@users.noreply.github.com>
2026-03-07 22:44:16 +00:00 · 2026-03-03 11:33:41 +08:00
parent 99a48aad08
commit 02d26ced98
4 changed files with 106 additions and 23 deletions
--- 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.
--- 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.<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
 {
--- a/docs/images/feishu-verification-token.png
+++ b/docs/images/feishu-verification-token.png
--- 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.<chat_id>.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.<chat_id>.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.<id>.appId`             | 应用 App ID                    | -         |
-| `channels.feishu.accounts.<id>.appSecret`         | 应用 App Secret                | -         |
-| `channels.feishu.accounts.<id>.domain`            | 单账号 API 域名覆盖            | `feishu`  |
-| `channels.feishu.dmPolicy`                        | 私聊策略                       | `pairing` |
-| `channels.feishu.allowFrom`                       | 私聊白名单（open_id 列表）     | -         |
-| `channels.feishu.groupPolicy`                     | 群组策略                       | `open`    |
-| `channels.feishu.groupAllowFrom`                  | 群组白名单                     | -         |
-| `channels.feishu.groups.<chat_id>.requireMention` | 是否需要 @提及                 | `true`    |
-| `channels.feishu.groups.<chat_id>.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.<id>.appId`             | 应用 App ID                       | -                |
+| `channels.feishu.accounts.<id>.appSecret`         | 应用 App Secret                   | -                |
+| `channels.feishu.accounts.<id>.domain`            | 单账号 API 域名覆盖               | `feishu`         |
+| `channels.feishu.dmPolicy`                        | 私聊策略                          | `pairing`        |
+| `channels.feishu.allowFrom`                       | 私聊白名单（open_id 列表）        | -                |
+| `channels.feishu.groupPolicy`                     | 群组策略                          | `open`           |
+| `channels.feishu.groupAllowFrom`                  | 群组白名单                        | -                |
+| `channels.feishu.groups.<chat_id>.requireMention` | 是否需要 @提及                    | `true`           |
+| `channels.feishu.groups.<chat_id>.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
 ### 接收

 - ✅ 文本消息
+- ✅ 富文本（帖子）
 - ✅ 图片
 - ✅ 文件
 - ✅ 音频