diff --git a/docs/zh-CN/channels/feishu.md b/docs/zh-CN/channels/feishu.md index 7d1d14fca..b439cd943 100644 --- a/docs/zh-CN/channels/feishu.md +++ b/docs/zh-CN/channels/feishu.md @@ -1,14 +1,14 @@ --- read_when: - - 你想要连接一个 Feishu/Lark 机器人 + - 你想连接一个 Feishu/Lark 机器人 - 你正在配置 Feishu 渠道 summary: Feishu 机器人概览、功能和配置 title: Feishu x-i18n: - generated_at: "2026-04-23T20:12:19Z" + generated_at: "2026-04-24T01:17:04Z" model: gpt-5.4 provider: openai - source_hash: 76565e89007211ba194ea9ab47ba926f5c9b5d12782d046bc94995a075671f02 + source_hash: f68a03c457fb2be7654f298fbad759705983d9e673b7b7b950609694894bdcbc source_path: channels/feishu.md workflow: 15 --- @@ -17,20 +17,20 @@ x-i18n: Feishu/Lark 是一个一体化协作平台，团队可以在其中聊天、共享文档、管理日历，并协同完成工作。 -**状态：** 机器人私信 + 群聊已可用于生产环境。WebSocket 是默认模式；webhook 模式为可选。 +**状态：** 已可用于生产环境，支持机器人私信 + 群聊。WebSocket 是默认模式；webhook 模式为可选。 --- ## 快速开始 -> **需要 OpenClaw 2026.4.23 或更高版本。** 运行 `openclaw --version` 进行检查。使用 `openclaw update` 升级。 +> **需要 OpenClaw 2026.4.24 或更高版本。** 运行 `openclaw --version` 进行检查。使用 `openclaw update` 升级。 ```bash openclaw channels login --channel feishu ``` - 使用你的 Feishu/Lark 移动应用扫描二维码，自动创建一个 Feishu/Lark 机器人。 + 使用你的 Feishu/Lark 移动应用扫描二维码，以自动创建一个 Feishu/Lark 机器人。 @@ -49,11 +49,11 @@ Feishu/Lark 是一个一体化协作平台，团队可以在其中聊天、共 配置 `dmPolicy` 以控制谁可以向机器人发送私信： - `"pairing"` — 未知用户会收到配对码；通过 CLI 批准 -- `"allowlist"` — 只有列在 `allowFrom` 中的用户可以聊天（默认：仅机器人所有者） +- `"allowlist"` — 只有 `allowFrom` 中列出的用户可以聊天（默认：仅机器人所有者） - `"open"` — 允许所有用户 - `"disabled"` — 禁用所有私信 -**批准一个配对请求：** +**批准配对请求：** ```bash openclaw pairing list feishu @@ -62,27 +62,27 @@ openclaw pairing approve feishu ### 群聊 -**群组策略**（`channels.feishu.groupPolicy`）： +**群组策略** (`channels.feishu.groupPolicy`)： -| Value | Behavior | -| ------------- | -------- | -| `"open"` | 在群组中响应所有消息 | +| Value | 行为 | +| ------------- | ---- | +| `"open"` | 响应群组中的所有消息 | | `"allowlist"` | 仅响应 `groupAllowFrom` 中的群组 | | `"disabled"` | 禁用所有群组消息 | 默认值：`allowlist` -**提及要求**（`channels.feishu.requireMention`）： +**提及要求** (`channels.feishu.requireMention`)： -- `true` — 需要 @mention（默认） -- `false` — 无需 @mention 也会响应 +- `true` — 需要 `@mention`（默认） +- `false` — 无需 `@mention` 也会响应 - 按群组覆盖：`channels.feishu.groups..requireMention` --- ## 群组配置示例 -### 允许所有群组，无需 @mention +### 允许所有群组，无需 `@mention` ```json5 { @@ -94,7 +94,7 @@ openclaw pairing approve feishu } ``` -### 允许所有群组，但仍要求 @mention +### 允许所有群组，但仍要求 `@mention` ```json5 { @@ -114,7 +114,7 @@ openclaw pairing approve feishu channels: { feishu: { groupPolicy: "allowlist", - // 群组 ID 类似：oc_xxx + // 群组 ID 形如：oc_xxx groupAllowFrom: ["oc_xxx", "oc_yyy"], }, }, @@ -131,7 +131,7 @@ openclaw pairing approve feishu groupAllowFrom: ["oc_xxx"], groups: { oc_xxx: { - // 用户 open_id 类似：ou_xxx + // 用户 open_id 形如：ou_xxx allowFrom: ["ou_user1", "ou_user2"], }, }, @@ -146,15 +146,15 @@ openclaw pairing approve feishu ## 获取群组/用户 ID -### 群组 ID（`chat_id`，格式：`oc_xxx`） +### 群组 ID (`chat_id`，格式：`oc_xxx`) -在 Feishu/Lark 中打开群组，点击右上角的菜单图标，然后进入**设置**。群组 ID（`chat_id`）会显示在设置页面中。 +在 Feishu/Lark 中打开群组，点击右上角的菜单图标，然后进入 **设置**。群组 ID (`chat_id`) 会显示在设置页面上。 ![Get Group ID](/images/feishu-get-group-id.png) -### 用户 ID（`open_id`，格式：`ou_xxx`） +### 用户 ID (`open_id`，格式：`ou_xxx`) -启动 Gateway 网关，向机器人发送一条私信，然后检查日志： +启动 Gateway 网关，向机器人发送一条私信，然后查看日志： ```bash openclaw logs --follow @@ -170,8 +170,8 @@ openclaw pairing list feishu ## 常用命令 -| Command | Description | -| --------- | ----------- | +| Command | 描述 | +| --------- | ---- | | `/status` | 显示机器人状态 | | `/reset` | 重置当前会话 | | `/model` | 显示或切换 AI 模型 | @@ -184,31 +184,31 @@ openclaw pairing list feishu ### 机器人在群聊中没有响应 -1. 确保机器人已加入群组 -2. 确保你已 @mention 机器人（默认要求） -3. 验证 `groupPolicy` 不是 `"disabled"` -4. 检查日志：`openclaw logs --follow` +1. 确保机器人已被添加到群组中 +2. 确保你已 `@mention` 机器人（默认要求） +3. 确认 `groupPolicy` 不是 `"disabled"` +4. 查看日志：`openclaw logs --follow` -### 机器人没有收到消息 +### 机器人没有接收到消息 -1. 确保机器人已在 Feishu Open Platform / Lark Developer 中发布并获得批准 +1. 确保机器人已在 Feishu Open Platform / Lark Developer 中发布并获批 2. 确保事件订阅包含 `im.message.receive_v1` -3. 确保已选择**持久连接**（WebSocket） +3. 确保已选择 **persistent connection**（WebSocket） 4. 确保已授予所有必需的权限范围 5. 确保 Gateway 网关正在运行：`openclaw gateway status` -6. 检查日志：`openclaw logs --follow` +6. 查看日志：`openclaw logs --follow` ### App Secret 泄露 1. 在 Feishu Open Platform / Lark Developer 中重置 App Secret -2. 更新你的配置中的值 +2. 更新你配置中的对应值 3. 重启 Gateway 网关：`openclaw gateway restart` --- ## 高级配置 -### 多账户 +### 多账号 ```json5 { @@ -233,7 +233,7 @@ openclaw pairing list feishu } ``` -`defaultAccount` 用于控制当出站 API 未指定 `accountId` 时使用哪个账户。 +`defaultAccount` 控制在出站 API 未指定 `accountId` 时使用哪个账号。 ### 消息限制 @@ -242,7 +242,7 @@ openclaw pairing list feishu ### 流式传输 -Feishu/Lark 支持通过交互式卡片进行流式回复。启用后，机器人会在生成文本时实时更新卡片。 +Feishu/Lark 支持通过交互卡片进行流式回复。启用后，机器人会在生成文本时实时更新卡片。 ```json5 { @@ -259,10 +259,10 @@ Feishu/Lark 支持通过交互式卡片进行流式回复。启用后，机器 ### 配额优化 -使用两个可选标志来减少 Feishu/Lark API 调用次数： +使用两个可选标志减少 Feishu/Lark API 调用次数： -- `typingIndicator`（默认 `true`）：设为 `false` 可跳过“正在输入”反应调用 -- `resolveSenderNames`（默认 `true`）：设为 `false` 可跳过发送者资料查询 +- `typingIndicator`（默认 `true`）：设为 `false` 以跳过“正在输入”反应调用 +- `resolveSenderNames`（默认 `true`）：设为 `false` 以跳过发送者资料查询 ```json5 { @@ -331,11 +331,11 @@ Feishu/Lark 支持用于私信和群组话题消息的 ACP。Feishu/Lark ACP 由 /acp spawn codex --thread here ``` -`--thread here` 适用于私信和 Feishu/Lark 话题消息。绑定会话中的后续消息会直接路由到该 ACP 会话。 +`--thread here` 适用于私信和 Feishu/Lark 话题消息。绑定对话中的后续消息会直接路由到该 ACP 会话。 ### 多智能体路由 -使用 `bindings` 将 Feishu/Lark 私信或群组路由到不同智能体。 +使用 `bindings` 将 Feishu/Lark 私信或群组路由到不同的智能体。 ```json5 { @@ -367,11 +367,11 @@ Feishu/Lark 支持用于私信和群组话题消息的 ACP。Feishu/Lark ACP 由 路由字段： -- `match.channel`：`"feishu"` -- `match.peer.kind`：`"direct"`（私信）或 `"group"`（群聊） -- `match.peer.id`：用户 Open ID（`ou_xxx`）或群组 ID（`oc_xxx`） +- `match.channel`: `"feishu"` +- `match.peer.kind`: `"direct"`（私信）或 `"group"`（群聊） +- `match.peer.id`: 用户 Open ID (`ou_xxx`) 或群组 ID (`oc_xxx`) -查找技巧请参见[获取群组/用户 ID](#get-groupuser-ids)。 +查找提示请参见 [获取群组/用户 ID](#get-groupuser-ids)。 --- @@ -379,33 +379,33 @@ Feishu/Lark 支持用于私信和群组话题消息的 ACP。Feishu/Lark ACP 由 完整配置：[Gateway 网关配置](/zh-CN/gateway/configuration) -| Setting | Description | Default | -| ------------------------------------------------- | ------------------------------------------ | ---------------- | -| `channels.feishu.enabled` | 启用/禁用该渠道 | `true` | -| `channels.feishu.domain` | API 域（`feishu` 或 `lark`） | `feishu` | -| `channels.feishu.connectionMode` | 事件传输方式（`websocket` 或 `webhook`） | `websocket` | -| `channels.feishu.defaultAccount` | 用于出站路由的默认账户 | `default` | -| `channels.feishu.verificationToken` | webhook 模式必需 | — | -| `channels.feishu.encryptKey` | 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` | 按账户覆盖域设置 | `feishu` | -| `channels.feishu.dmPolicy` | 私信策略 | `allowlist` | -| `channels.feishu.allowFrom` | 私信允许列表（`open_id` 列表） | [BotOwnerId] | -| `channels.feishu.groupPolicy` | 群组策略 | `allowlist` | -| `channels.feishu.groupAllowFrom` | 群组允许列表 | — | -| `channels.feishu.requireMention` | 在群组中要求 @mention | `true` | -| `channels.feishu.groups..requireMention` | 按群组覆盖 @mention 要求 | 继承 | -| `channels.feishu.groups..enabled` | 启用/禁用特定群组 | `true` | -| `channels.feishu.textChunkLimit` | 消息分块大小 | `2000` | -| `channels.feishu.mediaMaxMb` | 媒体大小限制 | `30` | -| `channels.feishu.streaming` | 流式卡片输出 | `true` | -| `channels.feishu.blockStreaming` | 分块流式传输 | `true` | -| `channels.feishu.typingIndicator` | 发送“正在输入”反应 | `true` | -| `channels.feishu.resolveSenderNames` | 解析发送者显示名称 | `true` | +| Setting | 描述 | Default | +| ------------------------------------------------- | ---- | ---------------- | +| `channels.feishu.enabled` | 启用/禁用该渠道 | `true` | +| `channels.feishu.domain` | API 域名（`feishu` 或 `lark`） | `feishu` | +| `channels.feishu.connectionMode` | 事件传输方式（`websocket` 或 `webhook`） | `websocket` | +| `channels.feishu.defaultAccount` | 出站路由的默认账号 | `default` | +| `channels.feishu.verificationToken` | webhook 模式必需 | — | +| `channels.feishu.encryptKey` | 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` | 按账号覆盖域名 | `feishu` | +| `channels.feishu.dmPolicy` | 私信策略 | `allowlist` | +| `channels.feishu.allowFrom` | 私信允许列表（`open_id` 列表） | [BotOwnerId] | +| `channels.feishu.groupPolicy` | 群组策略 | `allowlist` | +| `channels.feishu.groupAllowFrom` | 群组允许列表 | — | +| `channels.feishu.requireMention` | 在群组中要求 `@mention` | `true` | +| `channels.feishu.groups..requireMention` | 按群组覆盖 `@mention` | inherited | +| `channels.feishu.groups..enabled` | 启用/禁用特定群组 | `true` | +| `channels.feishu.textChunkLimit` | 消息分块大小 | `2000` | +| `channels.feishu.mediaMaxMb` | 媒体大小限制 | `30` | +| `channels.feishu.streaming` | 流式卡片输出 | `true` | +| `channels.feishu.blockStreaming` | 分块流式传输 | `true` | +| `channels.feishu.typingIndicator` | 发送“正在输入”反应 | `true` | +| `channels.feishu.resolveSenderNames` | 解析发送者显示名称 | `true` | --- @@ -419,7 +419,7 @@ Feishu/Lark 支持用于私信和群组话题消息的 ACP。Feishu/Lark ACP 由 - ✅ 文件 - ✅ 音频 - ✅ 视频/媒体 -- ✅ 表情贴纸 +- ✅ 贴纸 ### 发送 @@ -428,12 +428,12 @@ Feishu/Lark 支持用于私信和群组话题消息的 ACP。Feishu/Lark ACP 由 - ✅ 文件 - ✅ 音频 - ✅ 视频/媒体 -- ✅ 交互式卡片（包括流式更新） -- ⚠️ 富文本（post 风格格式；不支持完整的 Feishu/Lark 编辑能力） +- ✅ 交互卡片（包括流式更新） +- ⚠️ 富文本（post 风格格式；不支持 Feishu/Lark 的全部原生编辑能力） ### 话题和回复 -- ✅ 行内回复 +- ✅ 内联回复 - ✅ 话题回复 - ✅ 回复话题消息时，媒体回复会保持话题感知 @@ -445,4 +445,4 @@ Feishu/Lark 支持用于私信和群组话题消息的 ACP。Feishu/Lark ACP 由 - [配对](/zh-CN/channels/pairing) — 私信身份验证和配对流程 - [群组](/zh-CN/channels/groups) — 群聊行为和提及门控 - [渠道路由](/zh-CN/channels/channel-routing) — 消息的会话路由 -- [安全](/zh-CN/gateway/security) — 访问模型与加固 +- [安全](/zh-CN/gateway/security) — 访问模型与加固措施