diff --git a/docs/zh-CN/channels/feishu.md b/docs/zh-CN/channels/feishu.md index 9394ab703..19ec0db4c 100644 --- a/docs/zh-CN/channels/feishu.md +++ b/docs/zh-CN/channels/feishu.md @@ -5,19 +5,19 @@ read_when: summary: Feishu 机器人概览、功能和配置 title: Feishu x-i18n: - generated_at: "2026-04-25T07:01:13Z" + generated_at: "2026-04-25T08:32:00Z" model: gpt-5.4 provider: openai - source_hash: 01e6373cc5744973e9f18016c5d5bd6a036a03eb269cba3b5fd7f4108cad2ecb + source_hash: 5630a1f817a4831e1af75d63594edd4647861c09b5b2cfd32478b2c2aba1b049 source_path: channels/feishu.md workflow: 15 --- # Feishu / Lark -Feishu/Lark 是一个一体化协作平台，团队可以在其中聊天、共享文档、管理日历，并协同完成工作。 +Feishu/Lark 是一个一体化协作平台，团队可以在其中聊天、共享文档、管理日历并协同完成工作。 -**Status：** 适用于机器人私信 + 群聊的生产就绪。WebSocket 是默认模式；webhook 模式为可选。 +**Status：** 已可用于生产环境的机器人私信和群聊。WebSocket 是默认模式；webhook 模式为可选。 --- @@ -30,7 +30,7 @@ Feishu/Lark 是一个一体化协作平台，团队可以在其中聊天、共 ```bash openclaw channels login --channel feishu ``` - 使用你的 Feishu/Lark 移动应用扫描二维码，以自动创建一个 Feishu/Lark 机器人。 + 使用你的 Feishu/Lark 移动应用扫描二维码，自动创建一个 Feishu/Lark 机器人。 @@ -46,14 +46,14 @@ Feishu/Lark 是一个一体化协作平台，团队可以在其中聊天、共 ### 私信 -配置 `dmPolicy` 来控制谁可以向机器人发送私信： +配置 `dmPolicy` 以控制谁可以向机器人发送私信： - `"pairing"` — 未知用户会收到配对码；通过 CLI 批准 - `"allowlist"` — 只有 `allowFrom` 中列出的用户可以聊天（默认：仅机器人所有者） - `"open"` — 允许所有用户 - `"disabled"` — 禁用所有私信 -**批准一个配对请求：** +**批准配对请求：** ```bash openclaw pairing list feishu @@ -62,27 +62,27 @@ openclaw pairing approve feishu ### 群聊 -**群组策略** (`channels.feishu.groupPolicy`)： +**群组策略**（`channels.feishu.groupPolicy`）： -| Value | 行为 | -| ------------- | ---------------------------------- | -| `"open"` | 响应群组中的所有消息 | -| `"allowlist"` | 仅响应 `groupAllowFrom` 中的群组 | -| `"disabled"` | 禁用所有群组消息 | +| 值 | 行为 | +| ------------- | ---- | +| `"open"` | 响应群组中的所有消息 | +| `"allowlist"` | 仅响应 `groupAllowFrom` 中的群组 | +| `"disabled"` | 禁用所有群组消息 | 默认值：`allowlist` -**提及要求** (`channels.feishu.requireMention`)： +**提及要求**（`channels.feishu.requireMention`）： -- `true` — 需要 @提及（默认） -- `false` — 无需 @提及即可响应 +- `true` — 必须 @ 提及（默认） +- `false` — 无需 @ 提及也会响应 - 按群组覆盖：`channels.feishu.groups..requireMention` --- ## 群组配置示例 -### 允许所有群组，无需 @提及 +### 允许所有群组，无需 @ 提及 ```json5 { @@ -94,7 +94,7 @@ openclaw pairing approve feishu } ``` -### 允许所有群组，但仍要求 @提及 +### 允许所有群组，但仍要求 @ 提及 ```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"], }, }, @@ -144,17 +144,17 @@ openclaw pairing approve feishu -## 获取群组/用户 ID +## 获取群组 / 用户 ID -### 群组 ID (`chat_id`，格式：`oc_xxx`) +### 群组 ID（`chat_id`，格式：`oc_xxx`） -在 Feishu/Lark 中打开该群组，点击右上角的菜单图标，然后进入**设置**。群组 ID (`chat_id`) 会列在设置页面中。 +在 Feishu/Lark 中打开群组，点击右上角的菜单图标，然后进入**设置**。群组 ID（`chat_id`）会显示在设置页面中。 ![获取群组 ID](/images/feishu-get-group-id.png) -### 用户 ID (`open_id`，格式：`ou_xxx`) +### 用户 ID（`open_id`，格式：`ou_xxx`） -启动 Gateway 网关，向机器人发送一条私信，然后检查日志： +启动 Gateway 网关，向机器人发送一条私信，然后查看日志： ```bash openclaw logs --follow @@ -170,11 +170,11 @@ openclaw pairing list feishu ## 常用命令 -| Command | 说明 | -| --------- | ----------------------- | -| `/status` | 显示机器人状态 | -| `/reset` | 重置当前会话 | -| `/model` | 显示或切换 AI 模型 | +| 命令 | 说明 | +| --------- | ---- | +| `/status` | 显示机器人状态 | +| `/reset` | 重置当前会话 | +| `/model` | 显示或切换 AI 模型 | > Feishu/Lark 不支持原生斜杠命令菜单，因此请将这些命令作为纯文本消息发送。 @@ -184,31 +184,31 @@ openclaw pairing list feishu ### 机器人在群聊中没有响应 -1. 确保机器人已被添加到群组中 -2. 确保你 @提及了机器人（默认必须） +1. 确认机器人已添加到群组 +2. 确认你已 @ 提及机器人（默认要求） 3. 验证 `groupPolicy` 不是 `"disabled"` 4. 检查日志：`openclaw logs --follow` -### 机器人没有收到消息 +### 机器人未接收到消息 -1. 确保机器人已在 Feishu Open Platform / Lark Developer 中发布并获批 -2. 确保事件订阅包含 `im.message.receive_v1` -3. 确保已选择**持久连接**（WebSocket） -4. 确保已授予所有必需的权限范围 -5. 确保 Gateway 网关正在运行：`openclaw gateway status` +1. 确认机器人已在 Feishu Open Platform / Lark Developer 中发布并获批 +2. 确认事件订阅包含 `im.message.receive_v1` +3. 确认已选择**长连接**（WebSocket） +4. 确认已授予所有必需的权限范围 +5. 确认 Gateway 网关正在运行：`openclaw gateway status` 6. 检查日志：`openclaw logs --follow` ### App Secret 泄露 1. 在 Feishu Open Platform / Lark Developer 中重置 App Secret -2. 更新你配置中的对应值 +2. 更新你配置中的值 3. 重启 Gateway 网关：`openclaw gateway restart` --- ## 高级配置 -### 多账户 +### 多账号 ```json5 { @@ -219,12 +219,12 @@ openclaw pairing list feishu main: { appId: "cli_xxx", appSecret: "xxx", - name: "主机器人", + name: "Primary bot", }, backup: { appId: "cli_yyy", appSecret: "yyy", - name: "备用机器人", + name: "Backup bot", enabled: false, }, }, @@ -233,12 +233,12 @@ openclaw pairing list feishu } ``` -`defaultAccount` 用于控制当出站 API 未指定 `accountId` 时使用哪个账户。 +`defaultAccount` 用于控制当出站 API 未指定 `accountId` 时使用哪个账号。 ### 消息限制 - `textChunkLimit` — 出站文本分块大小（默认：`2000` 个字符） -- `mediaMaxMb` — 媒体上传/下载限制（默认：`30` MB） +- `mediaMaxMb` — 媒体上传 / 下载限制（默认：`30` MB） ### 流式传输 @@ -249,20 +249,20 @@ Feishu/Lark 通过交互式卡片支持流式回复。启用后，机器人会 channels: { feishu: { streaming: true, // 启用流式卡片输出（默认：true） - blockStreaming: true, // 启用块级流式传输（默认：true） + blockStreaming: true, // 启用分块流式传输（默认：true） }, }, } ``` -将 `streaming: false` 设为关闭后，会在一条消息中发送完整回复。 +将 `streaming: false` 设置为一次性发送完整回复。 ### 配额优化 使用两个可选标志来减少 Feishu/Lark API 调用次数： -- `typingIndicator`（默认 `true`）：设为 `false` 以跳过“正在输入”反应调用 -- `resolveSenderNames`（默认 `true`）：设为 `false` 以跳过发送者资料查询 +- `typingIndicator`（默认 `true`）：设置为 `false` 可跳过正在输入的反应调用 +- `resolveSenderNames`（默认 `true`）：设置为 `false` 可跳过发送者资料查询 ```json5 { @@ -277,7 +277,7 @@ Feishu/Lark 通过交互式卡片支持流式回复。启用后，机器人会 ### ACP 会话 -Feishu/Lark 支持用于私信和群组线程消息的 ACP。Feishu/Lark ACP 由文本命令驱动——没有原生斜杠命令菜单，因此请直接在对话中使用 `/acp ...` 消息。 +Feishu/Lark 支持在私信和群组话题消息中使用 ACP。Feishu/Lark ACP 由文本命令驱动——没有原生斜杠命令菜单，因此请直接在对话中使用 `/acp ...` 消息。 #### 持久 ACP 绑定 @@ -325,13 +325,13 @@ Feishu/Lark 支持用于私信和群组线程消息的 ACP。Feishu/Lark ACP 由 #### 从聊天中启动 ACP -在 Feishu/Lark 私信或线程中： +在 Feishu/Lark 私信或话题中： ```text /acp spawn codex --thread here ``` -`--thread here` 适用于私信和 Feishu/Lark 线程消息。后续在已绑定对话中的消息会直接路由到该 ACP 会话。 +`--thread here` 适用于私信和 Feishu/Lark 话题消息。随后在已绑定对话中的后续消息会直接路由到该 ACP 会话。 ### 多智能体路由 @@ -371,7 +371,7 @@ Feishu/Lark 支持用于私信和群组线程消息的 ACP。Feishu/Lark ACP 由 - `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 | 说明 | 默认值 | -| ------------------------------------------------- | ------------------------------------ | ---------------- | -| `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` | 在群组中需要 @提及 | `true` | -| `channels.feishu.groups..requireMention` | 按群组覆盖 @提及要求 | 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` | +| 设置 | 说明 | 默认值 | +| ------------------------------------------------- | ------------------------------------------ | ---------------- | +| `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` | 在群组中要求 @ 提及 | `true` | +| `channels.feishu.groups..requireMention` | 按群组覆盖 @ 提及要求 | 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` | --- @@ -418,7 +418,7 @@ Feishu/Lark 支持用于私信和群组线程消息的 ACP。Feishu/Lark ACP 由 - ✅ 图片 - ✅ 文件 - ✅ 音频 -- ✅ 视频/媒体 +- ✅ 视频 / 媒体 - ✅ 表情贴纸 ### 发送 @@ -427,24 +427,26 @@ Feishu/Lark 支持用于私信和群组线程消息的 ACP。Feishu/Lark ACP 由 - ✅ 图片 - ✅ 文件 - ✅ 音频 -- ✅ 视频/媒体 +- ✅ 视频 / 媒体 - ✅ 交互式卡片（包括流式更新） -- ⚠️ 富文本（post 风格格式；不支持完整的 Feishu/Lark 编辑能力） +- ⚠️ 富文本（post 样式格式；不支持完整的 Feishu/Lark 编辑能力） -### 线程和回复 +原生 Feishu/Lark 音频气泡使用 Feishu `audio` 消息类型，并要求上传 Ogg/Opus 媒体（`file_type: "opus"`）。现有的 `.opus` 和 `.ogg` 媒体会直接作为原生音频发送。MP3/WAV/M4A 和其他常见音频格式，仅在回复请求语音投递时才会通过 `ffmpeg` 转码为 48 kHz 的 Ogg/Opus（`audioAsVoice` / 消息工具 `asVoice`，包括 TTS 语音便笺回复）。普通 MP3 附件会保持为常规文件。如果缺少 `ffmpeg` 或转换失败，OpenClaw 会回退为文件附件，并记录原因。 + +### 话题和回复 - ✅ 行内回复 -- ✅ 线程回复 -- ✅ 回复线程消息时，媒体回复会保持线程感知 +- ✅ 话题回复 +- ✅ 回复话题消息时，媒体回复会保持话题感知 -对于 `groupSessionScope: "group_topic"` 和 `"group_topic_sender"`，原生 Feishu/Lark 话题群组使用事件 `thread_id`（`omt_*`）作为规范的话题会话键。OpenClaw 转换为线程的普通群组回复则继续使用回复根消息 ID（`om_*`），这样首轮消息和后续消息会保留在同一个会话中。 +对于 `groupSessionScope: "group_topic"` 和 `"group_topic_sender"`，原生 Feishu/Lark 话题群组使用事件 `thread_id`（`omt_*`）作为规范的话题会话键。对于 OpenClaw 转换为话题的普通群组回复，仍然使用回复根消息 ID（`om_*`），这样首轮消息和后续消息会保持在同一个会话中。 --- ## 相关内容 -- [渠道概览](/zh-CN/channels) — 所有支持的渠道 -- [配对](/zh-CN/channels/pairing) — 私信认证和配对流程 +- [渠道概览](/zh-CN/channels) — 所有受支持的渠道 +- [配对](/zh-CN/channels/pairing) — 私信身份验证和配对流程 - [群组](/zh-CN/channels/groups) — 群聊行为和提及门控 - [渠道路由](/zh-CN/channels/channel-routing) — 消息的会话路由 - [安全](/zh-CN/gateway/security) — 访问模型和加固措施 diff --git a/docs/zh-CN/logging.md b/docs/zh-CN/logging.md index 14a2bafb2..ca9982dba 100644 --- a/docs/zh-CN/logging.md +++ b/docs/zh-CN/logging.md @@ -1,27 +1,27 @@ --- read_when: - 你需要一份适合初学者的日志概览 - - 你想配置日志级别或格式 + - 你想要配置日志级别或格式 - 你正在进行故障排除，需要快速找到日志 summary: 日志概览：文件日志、控制台输出、CLI 尾随查看，以及 Control UI title: 日志概览 x-i18n: - generated_at: "2026-04-25T07:22:21Z" + generated_at: "2026-04-25T08:32:00Z" model: gpt-5.4 provider: openai - source_hash: c1a8ec7992c0c1b59036ccfd2b6d1d844c68f78cec14ff8eebddeac67f3fc607 + source_hash: e16a8aa487616c338c625c55fdfcc604759ee7b1e235b0b318b36d7a6fb07ab8 source_path: logging.md workflow: 15 --- # 日志 -OpenClaw 有两个主要的日志表面： +OpenClaw 有两个主要的日志入口： -- 由 Gateway 网关写入的**文件日志**（JSON 行）。 +- 由 Gateway 网关写入的**文件日志**（JSON Lines）。 - 在终端和 Gateway 网关调试 UI 中显示的**控制台输出**。 -Control UI 的**日志**标签页会尾随显示 gateway 文件日志。此页面会说明日志位于哪里、如何读取日志，以及如何配置日志级别和格式。 +Control UI 的**Logs**选项卡会尾随显示 Gateway 网关的文件日志。本页将说明日志存放在哪里、如何读取，以及如何配置日志级别和格式。 ## 日志存放位置 @@ -29,7 +29,7 @@ Control UI 的**日志**标签页会尾随显示 gateway 文件日志。此页 `/tmp/openclaw/openclaw-YYYY-MM-DD.log` -日期使用 gateway 主机的本地时区。 +日期使用 Gateway 网关主机的本地时区。 你可以在 `~/.openclaw/openclaw.json` 中覆盖此设置： @@ -45,7 +45,7 @@ Control UI 的**日志**标签页会尾随显示 gateway 文件日志。此页 ### CLI：实时尾随查看（推荐） -使用 CLI 通过 RPC 尾随查看 gateway 日志文件： +使用 CLI 通过 RPC 尾随查看 Gateway 网关日志文件： ```bash openclaw logs --follow @@ -54,8 +54,8 @@ openclaw logs --follow 当前有用的选项： - `--local-time`：使用你的本地时区显示时间戳 -- `--url ` / `--token ` / `--timeout `：标准 Gateway 网关 RPC 标志 -- `--expect-final`：由智能体支持的 RPC 最终响应等待标志（通过共享客户端层在此处接受） +- `--url ` / `--token ` / `--timeout `：标准的 Gateway 网关 RPC 标志 +- `--expect-final`：由智能体支持的 RPC 最终响应等待标志（这里通过共享客户端层接受） 输出模式： @@ -65,18 +65,18 @@ openclaw logs --follow - `--plain`：在 TTY 会话中强制使用纯文本。 - `--no-color`：禁用 ANSI 颜色。 -当你显式传入 `--url` 时，CLI 不会自动应用配置或环境变量中的凭证；如果目标 Gateway 网关需要认证，请自行附带 `--token`。 +当你传入显式的 `--url` 时，CLI 不会自动应用配置或环境变量凭证；如果目标 Gateway 网关需要认证，请自行包含 `--token`。 -在 JSON 模式下，CLI 会输出带 `type` 标记的对象： +在 JSON 模式下，CLI 会输出带有 `type` 标记的对象： - `meta`：流元数据（文件、游标、大小） -- `log`：已解析的日志条目 +- `log`：解析后的日志条目 - `notice`：截断 / 轮转提示 - `raw`：未解析的原始日志行 -如果本地 local loopback Gateway 网关请求配对，`openclaw logs` 会自动回退到已配置的本地日志文件。显式指定的 `--url` 目标不会使用此回退机制。 +如果本地 local loopback Gateway 网关请求配对，`openclaw logs` 会自动回退到已配置的本地日志文件。显式的 `--url` 目标不会使用此回退机制。 -如果 Gateway 网关无法连接，CLI 会打印一个简短提示，建议运行： +如果 Gateway 网关无法访问，CLI 会打印一条简短提示，建议运行： ```bash openclaw doctor @@ -84,8 +84,7 @@ openclaw doctor ### Control UI（网页） -Control UI 的**日志**标签页使用 `logs.tail` 尾随查看同一个文件。 -有关如何打开它，请参见 [/web/control-ui](/zh-CN/web/control-ui)。 +Control UI 的 **Logs** 选项卡会使用 `logs.tail` 尾随显示同一个文件。有关如何打开它，请参见 [/web/control-ui](/zh-CN/web/control-ui)。 ### 仅渠道日志 @@ -106,18 +105,18 @@ openclaw channels logs --channel whatsapp 控制台日志是**感知 TTY** 的，并针对可读性进行了格式化： - 子系统前缀（例如 `gateway/channels/whatsapp`） -- 级别颜色（info/warn/error） +- 级别着色（info/warn/error） - 可选的紧凑模式或 JSON 模式 控制台格式由 `logging.consoleStyle` 控制。 ### Gateway 网关 WebSocket 日志 -`openclaw gateway` 还提供用于 RPC 流量的 WebSocket 协议日志： +`openclaw gateway` 还提供 RPC 流量的 WebSocket 协议日志： -- 普通模式：仅显示值得关注的结果（错误、解析错误、慢调用） +- 普通模式：仅显示重要结果（错误、解析错误、慢调用） - `--verbose`：显示所有请求/响应流量 -- `--ws-log auto|compact|full`：选择详细输出的渲染样式 +- `--ws-log auto|compact|full`：选择详细渲染样式 - `--compact`：`--ws-log compact` 的别名 示例： @@ -130,7 +129,7 @@ openclaw gateway --verbose --ws-log full ## 配置日志 -所有日志配置都位于 `~/.openclaw/openclaw.json` 中的 `logging` 下。 +所有日志配置都位于 `~/.openclaw/openclaw.json` 的 `logging` 下。 ```json { @@ -150,75 +149,79 @@ openclaw gateway --verbose --ws-log full - `logging.level`：**文件日志**（JSONL）级别。 - `logging.consoleLevel`：**控制台**详细程度级别。 -你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两者（例如 `OPENCLAW_LOG_LEVEL=debug`）。环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅针对单次运行提高详细程度。你也可以传入全局 CLI 选项 **`--log-level `**（例如，`openclaw --log-level debug gateway run`），它会在该命令中覆盖环境变量。 +你可以通过 **`OPENCLAW_LOG_LEVEL`** 环境变量覆盖这两个设置（例如 `OPENCLAW_LOG_LEVEL=debug`）。环境变量优先于配置文件，因此你可以在不编辑 `openclaw.json` 的情况下，仅针对单次运行提高详细程度。你也可以传入全局 CLI 选项 **`--log-level `**（例如 `openclaw --log-level debug gateway run`），它会在该命令中覆盖环境变量。 -`--verbose` 只影响控制台输出和 WS 日志详细程度；它不会更改文件日志级别。 +`--verbose` 仅影响控制台输出和 WS 日志详细程度；它不会更改文件日志级别。 ### 控制台样式 `logging.consoleStyle`： -- `pretty`：适合人工阅读、带颜色、带时间戳。 -- `compact`：更紧凑的输出（适合长时间会话）。 +- `pretty`：适合人类阅读，带颜色和时间戳。 +- `compact`：输出更紧凑（最适合长时间会话）。 - `json`：每行一个 JSON（适用于日志处理器）。 ### 脱敏 -工具摘要在输出到控制台之前可以对敏感令牌进行脱敏： +工具摘要可以在输出到控制台之前对敏感令牌进行脱敏： - `logging.redactSensitive`：`off` | `tools`（默认：`tools`） -- `logging.redactPatterns`：用于覆盖默认集合的正则表达式字符串列表 +- `logging.redactPatterns`：regex 字符串列表，用于覆盖默认集合 -脱敏**仅影响控制台输出**，不会修改文件日志。 +脱敏仅影响**控制台输出**，不会修改文件日志。 -## 诊断 + OpenTelemetry +## Diagnostics + OpenTelemetry -诊断是用于模型运行**以及**消息流遥测（webhook、排队、会话状态）的结构化、机器可读事件。它们**不会**替代日志；它们的存在是为了向指标、追踪和其他导出器提供数据。 +诊断是用于模型运行**以及**消息流遥测（webhook、排队、会话状态）的结构化、机器可读事件。它们**不会**替代日志；它们的作用是为指标、追踪和其他导出器提供数据。 -诊断事件会在进程内发出，但只有在启用 diagnostics 和导出器插件后，导出器才会附加。 +诊断事件在进程内发出，但只有在启用 diagnostics 和导出器插件后，导出器才会附加。 -### OpenTelemetry 与 OTLP 的区别 +### OpenTelemetry 与 OTLP - **OpenTelemetry（OTel）**：用于追踪、指标和日志的数据模型 + SDK。 -- **OTLP**：用于将 OTel 数据导出到收集器 / 后端的线协议。 +- **OTLP**：用于将 OTel 数据导出到收集器 / 后端的传输协议。 - OpenClaw 当前通过 **OTLP/HTTP（protobuf）** 导出。 ### 导出的信号 -- **指标**：计数器 + 直方图（令牌使用量、消息流、排队）。 +- **指标**：计数器 + 直方图（令牌使用、消息流、排队）。 - **追踪**：用于模型使用 + webhook / 消息处理的 span。 -- **日志**：当启用 `diagnostics.otel.logs` 时通过 OTLP 导出。日志量可能很大；请留意 `logging.level` 和导出器过滤器。 +- **日志**：当启用 `diagnostics.otel.logs` 时，通过 OTLP 导出。日志量可能很高；请留意 `logging.level` 和导出器过滤器。 ### 诊断事件目录 模型使用： -- `model.usage`：令牌、成本、持续时间、上下文、提供商 / 模型 / 渠道、会话 ID。 +- `model.usage`：令牌、成本、耗时、上下文、provider / 模型 / 渠道、会话 ID。 消息流： -- `webhook.received`：按渠道统计的 webhook 入站。 -- `webhook.processed`：webhook 已处理 + 持续时间。 +- `webhook.received`：每个渠道的 webhook 入站。 +- `webhook.processed`：webhook 已处理 + 耗时。 - `webhook.error`：webhook 处理器错误。 -- `message.queued`：消息已加入处理队列。 -- `message.processed`：结果 + 持续时间 + 可选错误。 +- `message.queued`：消息已入队等待处理。 +- `message.processed`：结果 + 耗时 + 可选错误。 +- `message.delivery.started`：出站投递尝试开始。 +- `message.delivery.completed`：出站投递尝试结束 + 耗时 / 结果计数。 +- `message.delivery.error`：出站投递尝试失败 + 耗时 / 有界错误类别。 队列 + 会话： - `queue.lane.enqueue`：命令队列 lane 入队 + 深度。 - `queue.lane.dequeue`：命令队列 lane 出队 + 等待时间。 - `session.state`：会话状态转换 + 原因。 -- `session.stuck`：会话卡住警告 + 持续时长。 +- `session.stuck`：会话卡住警告 + 持续时间。 - `run.attempt`：运行重试 / 尝试元数据。 - `diagnostic.heartbeat`：聚合计数器（webhook / 队列 / 会话）。 -执行： +Exec： -- `exec.process.completed`：终端 exec 进程结果、持续时间、目标、模式、退出码和失败类型。不包含命令文本和工作目录。 +- `exec.process.completed`：终端 exec 进程结果、耗时、目标、模式、 + 退出码和失败类型。不包含命令文本和工作目录。 ### 启用 diagnostics（无导出器） -如果你希望 diagnostics 事件可供插件或自定义接收端使用，请使用此配置： +如果你希望 diagnostics 事件可供插件或自定义接收端使用，请使用： ```json { @@ -230,7 +233,7 @@ openclaw gateway --verbose --ws-log full ### diagnostics 标志（定向日志） -使用标志可以在不提高 `logging.level` 的情况下开启额外的定向调试日志。标志不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）。 +使用标志可在不提高 `logging.level` 的情况下启用额外的定向调试日志。标志不区分大小写，并支持通配符（例如 `telegram.*` 或 `*`）。 ```json { @@ -249,12 +252,12 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload 说明： - 标志日志会写入标准日志文件（与 `logging.file` 相同）。 -- 输出仍会根据 `logging.redactSensitive` 进行脱敏。 +- 输出仍会按照 `logging.redactSensitive` 进行脱敏。 - 完整指南：[/diagnostics/flags](/zh-CN/diagnostics/flags)。 ### 导出到 OpenTelemetry -可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出 diagnostics。这适用于任何接受 OTLP/HTTP 的 OpenTelemetry 收集器 / 后端。 +diagnostics 可以通过 `diagnostics-otel` 插件（OTLP/HTTP）导出。这适用于任何接受 OTLP/HTTP 的 OpenTelemetry 收集器 / 后端。 ```json { @@ -295,47 +298,65 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload - 你也可以使用 `openclaw plugins enable diagnostics-otel` 启用该插件。 - `protocol` 当前仅支持 `http/protobuf`。`grpc` 会被忽略。 -- 指标包括令牌使用量、成本、上下文大小、运行时长，以及消息流计数器 / 直方图（webhook、排队、会话状态、队列深度 / 等待时间）。 -- 可以使用 `traces` / `metrics` 开关来控制是否导出追踪 / 指标（默认：开启）。启用后，追踪包括模型使用 span，以及 webhook / 消息处理 span。 -- 默认不会导出原始模型 / 工具内容。仅当你的收集器和保留策略已批准保存提示词、响应、工具或系统提示文本时，才使用 `diagnostics.otel.captureContent`。 +- 指标包括令牌使用、成本、上下文大小、运行时长，以及消息流计数器 / 直方图（webhook、排队、会话状态、队列深度 / 等待时间）。 +- 可通过 `traces` / `metrics` 切换追踪 / 指标（默认：开启）。启用后，追踪包括模型使用 span，以及 webhook / 消息处理 span。 +- 默认不会导出原始模型 / 工具内容。仅当你的收集器和保留策略已获批准可存储提示词、响应、工具或系统提示文本时，才使用 `diagnostics.otel.captureContent`。 - 当你的收集器需要认证时，请设置 `headers`。 -- 支持的环境变量：`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_SERVICE_NAME`、`OTEL_EXPORTER_OTLP_PROTOCOL`。 -- 当另一个预加载项或宿主进程已经注册全局 OpenTelemetry SDK 时，设置 `OPENCLAW_OTEL_PRELOADED=1`。在该模式下，插件不会启动或关闭它自己的 SDK，但仍会连接 OpenClaw 诊断监听器，并遵循 `diagnostics.otel.traces`、`metrics` 和 `logs`。 +- 支持的环境变量：`OTEL_EXPORTER_OTLP_ENDPOINT`、 + `OTEL_SERVICE_NAME`、`OTEL_EXPORTER_OTLP_PROTOCOL`。 +- 当另一个 preload 或宿主进程已经注册全局 OpenTelemetry SDK 时，请设置 `OPENCLAW_OTEL_PRELOADED=1`。在该模式下，插件不会启动或关闭自己的 SDK，但仍会接入 OpenClaw 诊断监听器，并遵循 `diagnostics.otel.traces`、`metrics` 和 `logs`。 -### 已导出的指标（名称 + 类型） +### 导出的指标（名称 + 类型） 模型使用： -- `openclaw.tokens`（计数器，属性：`openclaw.token`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`） -- `openclaw.cost.usd`（计数器，属性：`openclaw.channel`、`openclaw.provider`、`openclaw.model`） -- `openclaw.run.duration_ms`（直方图，属性：`openclaw.channel`、`openclaw.provider`、`openclaw.model`） -- `openclaw.context.tokens`（直方图，属性：`openclaw.context`、`openclaw.channel`、`openclaw.provider`、`openclaw.model`） +- `openclaw.tokens`（计数器，属性：`openclaw.token`、`openclaw.channel`、 + `openclaw.provider`、`openclaw.model`） +- `openclaw.cost.usd`（计数器，属性：`openclaw.channel`、`openclaw.provider`、 + `openclaw.model`） +- `openclaw.run.duration_ms`（直方图，属性：`openclaw.channel`、 + `openclaw.provider`、`openclaw.model`） +- `openclaw.context.tokens`（直方图，属性：`openclaw.context`、 + `openclaw.channel`、`openclaw.provider`、`openclaw.model`） 消息流： -- `openclaw.webhook.received`（计数器，属性：`openclaw.channel`、`openclaw.webhook`） -- `openclaw.webhook.error`（计数器，属性：`openclaw.channel`、`openclaw.webhook`） -- `openclaw.webhook.duration_ms`（直方图，属性：`openclaw.channel`、`openclaw.webhook`） -- `openclaw.message.queued`（计数器，属性：`openclaw.channel`、`openclaw.source`） -- `openclaw.message.processed`（计数器，属性：`openclaw.channel`、`openclaw.outcome`） -- `openclaw.message.duration_ms`（直方图，属性：`openclaw.channel`、`openclaw.outcome`） +- `openclaw.webhook.received`（计数器，属性：`openclaw.channel`、 + `openclaw.webhook`） +- `openclaw.webhook.error`（计数器，属性：`openclaw.channel`、 + `openclaw.webhook`） +- `openclaw.webhook.duration_ms`（直方图，属性：`openclaw.channel`、 + `openclaw.webhook`） +- `openclaw.message.queued`（计数器，属性：`openclaw.channel`、 + `openclaw.source`） +- `openclaw.message.processed`（计数器，属性：`openclaw.channel`、 + `openclaw.outcome`） +- `openclaw.message.duration_ms`（直方图，属性：`openclaw.channel`、 + `openclaw.outcome`） +- `openclaw.message.delivery.started`（计数器，属性：`openclaw.channel`、 + `openclaw.delivery.kind`） +- `openclaw.message.delivery.duration_ms`（直方图，属性： + `openclaw.channel`、`openclaw.delivery.kind`、`openclaw.outcome`、 + `openclaw.errorCategory`） 队列 + 会话： - `openclaw.queue.lane.enqueue`（计数器，属性：`openclaw.lane`） - `openclaw.queue.lane.dequeue`（计数器，属性：`openclaw.lane`） -- `openclaw.queue.depth`（直方图，属性：`openclaw.lane` 或 `openclaw.channel=heartbeat`） +- `openclaw.queue.depth`（直方图，属性：`openclaw.lane` 或 + `openclaw.channel=heartbeat`） - `openclaw.queue.wait_ms`（直方图，属性：`openclaw.lane`） - `openclaw.session.state`（计数器，属性：`openclaw.state`、`openclaw.reason`） - `openclaw.session.stuck`（计数器，属性：`openclaw.state`） - `openclaw.session.stuck_age_ms`（直方图，属性：`openclaw.state`） - `openclaw.run.attempt`（计数器，属性：`openclaw.attempt`） -执行： +Exec： -- `openclaw.exec.duration_ms`（直方图，属性：`openclaw.exec.target`、`openclaw.exec.mode`、`openclaw.outcome`、`openclaw.failureKind`） +- `openclaw.exec.duration_ms`（直方图，属性：`openclaw.exec.target`、 + `openclaw.exec.mode`、`openclaw.outcome`、`openclaw.failureKind`） -### 已导出的 span（名称 + 关键属性） +### 导出的 span（名称 + 关键属性） - `openclaw.model.usage` - `openclaw.channel`、`openclaw.provider`、`openclaw.model` @@ -362,10 +383,13 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload - `openclaw.message.processed` - `openclaw.channel`、`openclaw.outcome`、`openclaw.chatId`、 `openclaw.messageId`、`openclaw.reason` +- `openclaw.message.delivery` + - `openclaw.channel`、`openclaw.delivery.kind`、`openclaw.outcome`、 + `openclaw.errorCategory`、`openclaw.delivery.result_count` - `openclaw.session.stuck` - `openclaw.state`、`openclaw.ageMs`、`openclaw.queueDepth` -当显式启用内容捕获时，模型 / 工具 span 还可以包含有界且已脱敏的 `openclaw.content.*` 属性，用于你选择启用的特定内容类别。 +当显式启用内容捕获时，模型 / 工具 span 还可以包含有界、已脱敏的 `openclaw.content.*` 属性，用于你选择启用的特定内容类别。 ### 采样 + 刷新 @@ -374,10 +398,10 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload ### 协议说明 -- 可以通过 `diagnostics.otel.endpoint` 或 - `OTEL_EXPORTER_OTLP_ENDPOINT` 设置 OTLP/HTTP 端点。 -- 如果端点已包含 `/v1/traces` 或 `/v1/metrics`，则会按原样使用。 -- 如果端点已包含 `/v1/logs`，则会按原样用于日志。 +- OTLP/HTTP 端点可通过 `diagnostics.otel.endpoint` 或 + `OTEL_EXPORTER_OTLP_ENDPOINT` 设置。 +- 如果端点已包含 `/v1/traces` 或 `/v1/metrics`，则按原样使用。 +- 如果端点已包含 `/v1/logs`，则日志也会按原样使用该端点。 - `OPENCLAW_OTEL_PRELOADED=1` 会复用外部已注册的 OpenTelemetry SDK 用于追踪 / 指标，而不是启动由插件拥有的 NodeSDK。 - `diagnostics.otel.logs` 会为主日志记录器输出启用 OTLP 日志导出。 @@ -385,15 +409,15 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload ### 日志导出行为 - OTLP 日志使用与写入 `logging.file` 相同的结构化记录。 -- 遵循 `logging.level`（文件日志级别）。控制台脱敏**不会**应用于 +- 遵循 `logging.level`（文件日志级别）。控制台脱敏**不**适用于 OTLP 日志。 -- 对于高流量安装，应该优先使用 OTLP 收集器采样 / 过滤。 +- 高流量安装应优先使用 OTLP 收集器采样 / 过滤。 ## 故障排除提示 -- **Gateway 网关无法连接？** 请先运行 `openclaw doctor`。 -- **日志为空？** 检查 Gateway 网关是否正在运行，以及是否正在向 - `logging.file` 中的文件路径写入。 +- **Gateway 网关无法访问？** 先运行 `openclaw doctor`。 +- **日志为空？** 检查 Gateway 网关是否正在运行，并正在向 + `logging.file` 中的文件路径写入日志。 - **需要更多细节？** 将 `logging.level` 设置为 `debug` 或 `trace` 后重试。 ## 相关内容 diff --git a/docs/zh-CN/tools/tts.md b/docs/zh-CN/tools/tts.md index e588920b4..465451fc4 100644 --- a/docs/zh-CN/tools/tts.md +++ b/docs/zh-CN/tools/tts.md @@ -3,25 +3,25 @@ read_when: - 为回复启用文本转语音 - 配置 TTS 提供商或限制 - 使用 `/tts` 命令 -summary: 用于出站回复的文本转语音（TTS） +summary: 用于外发回复的文本转语音（TTS） title: 文本转语音 x-i18n: - generated_at: "2026-04-25T05:16:41Z" + generated_at: "2026-04-25T08:32:05Z" model: gpt-5.4 provider: openai - source_hash: 42faea3996a8a1e88ee09f597808b054fd86fc0935e7f5f781386d2e85da7508 + source_hash: b63be2c606754b3ed334c394fb2ea8da3698ca8bfcbe8c136a5b710cb9c52768 source_path: tools/tts.md workflow: 15 --- -OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Microsoft、MiniMax、OpenAI、Vydra 或 xAI，将出站回复转换为音频。 -它适用于 OpenClaw 可以发送音频的任何地方。 +OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Microsoft、MiniMax、OpenAI、Vydra 或 xAI，将外发回复转换为音频。 +它适用于 OpenClaw 能够发送音频的任何地方。 ## 支持的服务 - **ElevenLabs**（主要或回退提供商） - **Google Gemini**（主要或回退提供商；使用 Gemini API TTS） -- **Gradium**（主要或回退提供商；支持语音便签和电话输出） +- **Gradium**（主要或回退提供商；支持语音便笺和电话输出） - **Microsoft**（主要或回退提供商；当前内置实现使用 `node-edge-tts`） - **MiniMax**（主要或回退提供商；使用 T2A v2 API） - **OpenAI**（主要或回退提供商；也用于摘要） @@ -30,12 +30,12 @@ OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Microsoft、MiniMax ### Microsoft 语音说明 -当前内置的 Microsoft 语音提供商通过 `node-edge-tts` 库使用 Microsoft Edge 的在线神经 TTS 服务。它是托管服务（不是本地服务），使用 Microsoft 的端点，并且不需要 API 密钥。 -`node-edge-tts` 提供语音配置选项和输出格式，但并非所有选项都受该服务支持。使用 `edge` 的旧版配置和指令输入仍然有效，并会被规范化为 `microsoft`。 +当前内置的 Microsoft 语音提供商通过 `node-edge-tts` 库，使用 Microsoft Edge 的在线神经网络 TTS 服务。它是托管服务（不是本地服务），使用 Microsoft 的端点，并且不需要 API 密钥。 +`node-edge-tts` 提供语音配置选项和输出格式，但并非所有选项都受该服务支持。使用 `edge` 的旧版配置和指令输入仍然可用，并会规范化为 `microsoft`。 -由于这一路径是公共 Web 服务，且没有公开发布的 SLA 或配额，请将其视为“尽力而为”服务。如果你需要有保证的限制和支持，请使用 OpenAI 或 ElevenLabs。 +由于这条路径是公共 Web 服务，没有公开的 SLA 或配额，因此应将其视为尽力而为的服务。如果你需要有保障的限制和支持，请使用 OpenAI 或 ElevenLabs。 -## 可选键 +## 可选密钥 如果你想使用 OpenAI、ElevenLabs、Google Gemini、Gradium、MiniMax、Vydra 或 xAI： @@ -49,31 +49,31 @@ OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Microsoft、MiniMax Microsoft 语音**不**需要 API 密钥。 -如果配置了多个提供商，会先使用所选提供商，其他提供商作为回退选项。 -自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用了摘要，也必须为该提供商完成身份验证。 +如果配置了多个提供商，则会优先使用所选提供商，其他提供商作为回退选项。 +自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用摘要，对应提供商也必须完成身份验证。 ## 服务链接 -- [OpenAI Text-to-Speech guide](https://platform.openai.com/docs/guides/text-to-speech) -- [OpenAI Audio API reference](https://platform.openai.com/docs/api-reference/audio) -- [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech) -- [ElevenLabs Authentication](https://elevenlabs.io/docs/api-reference/authentication) +- [OpenAI 文本转语音指南](https://platform.openai.com/docs/guides/text-to-speech) +- [OpenAI 音频 API 参考](https://platform.openai.com/docs/api-reference/audio) +- [ElevenLabs 文本转语音](https://elevenlabs.io/docs/api-reference/text-to-speech) +- [ElevenLabs 身份验证](https://elevenlabs.io/docs/api-reference/authentication) - [Gradium](/zh-CN/providers/gradium) - [MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2) - [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts) -- [Microsoft Speech output formats](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) -- [xAI Text to Speech](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest) +- [Microsoft Speech 输出格式](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) +- [xAI 文本转语音](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest) ## 默认启用吗？ 不是。自动 TTS 默认**关闭**。可在配置中通过 `messages.tts.auto` 启用，或在本地使用 `/tts on` 启用。 -当未设置 `messages.tts.provider` 时，OpenClaw 会按照注册表自动选择顺序，选取第一个已配置的语音提供商。 +当未设置 `messages.tts.provider` 时，OpenClaw 会按照注册表自动选择顺序，选择第一个已配置的语音提供商。 ## 配置 TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 -完整 schema 位于 [Gateway 网关配置](/zh-CN/gateway/configuration)。 +完整 schema 请参见 [Gateway 网关配置](/zh-CN/gateway/configuration)。 ### 最小配置（启用 + 提供商） @@ -88,7 +88,7 @@ TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 } ``` -### OpenAI 主提供商，ElevenLabs 回退 +### OpenAI 为主，ElevenLabs 为回退 ```json5 { @@ -129,7 +129,7 @@ TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 } ``` -### Microsoft 主提供商（无 API 密钥） +### Microsoft 为主（无 API 密钥） ```json5 { @@ -152,7 +152,7 @@ TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 } ``` -### MiniMax 主提供商 +### MiniMax 为主 ```json5 { @@ -176,7 +176,7 @@ TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 } ``` -### Google Gemini 主提供商 +### Google Gemini 为主 ```json5 { @@ -196,9 +196,11 @@ TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 } ``` -Google Gemini TTS 使用 Gemini API 密钥路径。这里可以使用限制为 Gemini API 的 Google Cloud Console API 密钥，它与内置 Google 图像生成提供商使用的是同一种密钥样式。解析顺序为 `messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` -> `GEMINI_API_KEY` -> `GOOGLE_API_KEY`。 +Google Gemini TTS 使用 Gemini API 密钥路径。这里可以使用限制为 Gemini API 的 Google Cloud Console API 密钥，其形式与内置 Google 图像生成提供商使用的密钥相同。解析顺序为 +`messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` -> +`GEMINI_API_KEY` -> `GOOGLE_API_KEY`。 -### xAI 主提供商 +### xAI 为主 ```json5 { @@ -220,10 +222,10 @@ Google Gemini TTS 使用 Gemini API 密钥路径。这里可以使用限制为 G } ``` -xAI TTS 与内置 Grok 模型提供商使用相同的 `XAI_API_KEY` 路径。解析顺序为 `messages.tts.providers.xai.apiKey` -> `XAI_API_KEY`。 -当前可用的实时语音为 `ara`、`eve`、`leo`、`rex`、`sal` 和 `una`；默认值为 `eve`。`language` 接受 BCP-47 标签或 `auto`。 +xAI TTS 使用与内置 Grok 模型提供商相同的 `XAI_API_KEY` 路径。解析顺序为 `messages.tts.providers.xai.apiKey` -> `XAI_API_KEY`。 +当前可用的语音有 `ara`、`eve`、`leo`、`rex`、`sal` 和 `una`；默认值为 `eve`。`language` 接受 BCP-47 标签或 `auto`。 -### OpenRouter 主提供商 +### OpenRouter 为主 ```json5 { @@ -244,10 +246,11 @@ xAI TTS 与内置 Grok 模型提供商使用相同的 `XAI_API_KEY` 路径。解 } ``` -OpenRouter TTS 与内置 OpenRouter 模型提供商使用相同的 `OPENROUTER_API_KEY` 路径。解析顺序为 `messages.tts.providers.openrouter.apiKey` -> +OpenRouter TTS 使用与内置 OpenRouter 模型提供商相同的 `OPENROUTER_API_KEY` 路径。解析顺序为 +`messages.tts.providers.openrouter.apiKey` -> `models.providers.openrouter.apiKey` -> `OPENROUTER_API_KEY`。 -### Gradium 主提供商 +### Gradium 为主 ```json5 { @@ -283,7 +286,7 @@ OpenRouter TTS 与内置 OpenRouter 模型提供商使用相同的 `OPENROUTER_A } ``` -### 自定义限制 + prefs 路径 +### 自定义限制 + 偏好设置路径 ```json5 { @@ -298,7 +301,7 @@ OpenRouter TTS 与内置 OpenRouter 模型提供商使用相同的 `OPENROUTER_A } ``` -### 仅在收到入站语音消息后用音频回复 +### 仅在收到入站语音消息后以音频形式回复 ```json5 { @@ -332,23 +335,23 @@ OpenRouter TTS 与内置 OpenRouter 模型提供商使用相同的 `OPENROUTER_A - `auto`：自动 TTS 模式（`off`、`always`、`inbound`、`tagged`）。 - `inbound` 仅在收到入站语音消息后发送音频。 - - `tagged` 仅在回复包含 `[[tts:key=value]]` 指令或 `[[tts:text]]...[[/tts:text]]` 区块时发送音频。 -- `enabled`：旧版开关（`doctor` 会将其迁移为 `auto`）。 -- `mode`：`"final"`（默认）或 `"all"`（包括工具/分块回复）。 + - `tagged` 仅当回复包含 `[[tts:key=value]]` 指令或 `[[tts:text]]...[[/tts:text]]` 块时发送音频。 +- `enabled`：旧版开关（Doctor 会将其迁移为 `auto`）。 +- `mode`：`"final"`（默认）或 `"all"`（包含工具/分块回复）。 - `provider`：语音提供商 id，例如 `"elevenlabs"`、`"google"`、`"gradium"`、`"microsoft"`、`"minimax"`、`"openai"`、`"vydra"` 或 `"xai"`（回退会自动处理）。 -- 如果 `provider` **未设置**，OpenClaw 会按照注册表自动选择顺序，使用第一个已配置的语音提供商。 +- 如果未设置 `provider`，OpenClaw 会按照注册表自动选择顺序使用第一个已配置的语音提供商。 - 旧版 `provider: "edge"` 配置可通过 `openclaw doctor --fix` 修复，并重写为 `provider: "microsoft"`。 -- `summaryModel`：用于自动摘要的可选低成本模型；默认为 `agents.defaults.model.primary`。 +- `summaryModel`：用于自动摘要的可选低成本模型；默认值为 `agents.defaults.model.primary`。 - 接受 `provider/model` 或已配置的模型别名。 - `modelOverrides`：允许模型发出 TTS 指令（默认开启）。 - - `allowProvider` 默认为 `false`（提供商切换需显式选择启用）。 -- `providers.`：由提供商拥有的设置，以语音提供商 id 为键。 -- 旧版直接提供商区块（`messages.tts.openai`、`messages.tts.elevenlabs`、`messages.tts.microsoft`、`messages.tts.edge`）可通过 `openclaw doctor --fix` 修复；已提交的配置应使用 `messages.tts.providers.`。 -- 旧版 `messages.tts.providers.edge` 也可通过 `openclaw doctor --fix` 修复；已提交的配置应使用 `messages.tts.providers.microsoft`。 -- `maxTextLength`：TTS 输入的硬上限（字符数）。若超出，`/tts audio` 会失败。 -- `timeoutMs`：请求超时（毫秒）。 + - `allowProvider` 默认为 `false`（切换提供商需要显式启用）。 +- `providers.`：由提供商管理、按语音提供商 id 键控的设置。 +- 旧版直接提供商块（`messages.tts.openai`、`messages.tts.elevenlabs`、`messages.tts.microsoft`、`messages.tts.edge`）可通过 `openclaw doctor --fix` 修复；提交的配置应使用 `messages.tts.providers.`。 +- 旧版 `messages.tts.providers.edge` 也可通过 `openclaw doctor --fix` 修复；提交的配置应使用 `messages.tts.providers.microsoft`。 +- `maxTextLength`：TTS 输入的硬上限（字符数）。超出时，`/tts audio` 会失败。 +- `timeoutMs`：请求超时时间（毫秒）。 - `prefsPath`：覆盖本地偏好设置 JSON 路径（提供商/限制/摘要）。 -- `apiKey` 值会回退到环境变量（`ELEVENLABS_API_KEY`/`XI_API_KEY`、`GEMINI_API_KEY`/`GOOGLE_API_KEY`、`GRADIUM_API_KEY`、`MINIMAX_API_KEY`、`OPENAI_API_KEY`、`VYDRA_API_KEY`、`XAI_API_KEY`）。 +- `apiKey` 值可回退到环境变量（`ELEVENLABS_API_KEY`/`XI_API_KEY`、`GEMINI_API_KEY`/`GOOGLE_API_KEY`、`GRADIUM_API_KEY`、`MINIMAX_API_KEY`、`OPENAI_API_KEY`、`VYDRA_API_KEY`、`XAI_API_KEY`）。 - `providers.elevenlabs.baseUrl`：覆盖 ElevenLabs API 基础 URL。 - `providers.openai.baseUrl`：覆盖 OpenAI TTS 端点。 - 解析顺序：`messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` @@ -358,53 +361,54 @@ OpenRouter TTS 与内置 OpenRouter 模型提供商使用相同的 `OPENROUTER_A - `useSpeakerBoost`：`true|false` - `speed`：`0.5..2.0`（1.0 = 正常） - `providers.elevenlabs.applyTextNormalization`：`auto|on|off` -- `providers.elevenlabs.languageCode`：2 位 ISO 639-1 代码（例如 `en`、`de`） +- `providers.elevenlabs.languageCode`：2 字母 ISO 639-1 代码（例如 `en`、`de`） - `providers.elevenlabs.seed`：整数 `0..4294967295`（尽力保证确定性） - `providers.minimax.baseUrl`：覆盖 MiniMax API 基础 URL（默认 `https://api.minimax.io`，环境变量：`MINIMAX_API_HOST`）。 - `providers.minimax.model`：TTS 模型（默认 `speech-2.8-hd`，环境变量：`MINIMAX_TTS_MODEL`）。 - `providers.minimax.voiceId`：语音标识符（默认 `English_expressive_narrator`，环境变量：`MINIMAX_TTS_VOICE_ID`）。 - `providers.minimax.speed`：播放速度 `0.5..2.0`（默认 1.0）。 - `providers.minimax.vol`：音量 `(0, 10]`（默认 1.0；必须大于 0）。 -- `providers.minimax.pitch`：整数音高偏移 `-12..12`（默认 0）。在调用 MiniMax T2A 之前，小数值会被截断，因为该 API 拒绝非整数的音高值。 +- `providers.minimax.pitch`：整数音高偏移 `-12..12`（默认 0）。小数值在调用 MiniMax T2A 前会被截断，因为该 API 不接受非整数音高值。 - `providers.google.model`：Gemini TTS 模型（默认 `gemini-3.1-flash-tts-preview`）。 - `providers.google.voiceName`：Gemini 预置语音名称（默认 `Kore`；也接受 `voice`）。 -- `providers.google.audioProfile`：自然语言风格提示，会添加到朗读文本前。 -- `providers.google.speakerName`：可选说话人标签；当你的 TTS 提示使用命名说话人时，会添加到朗读文本前。 +- `providers.google.audioProfile`：添加在朗读文本前的自然语言风格提示。 +- `providers.google.speakerName`：当你的 TTS 提示使用命名说话人时，添加在朗读文本前的可选说话人标签。 - `providers.google.baseUrl`：覆盖 Gemini API 基础 URL。仅接受 `https://generativelanguage.googleapis.com`。 - - 如果省略 `messages.tts.providers.google.apiKey`，TTS 可在回退到环境变量之前复用 `models.providers.google.apiKey`。 + - 如果省略 `messages.tts.providers.google.apiKey`，TTS 在回退到环境变量之前，可以复用 `models.providers.google.apiKey`。 - `providers.gradium.baseUrl`：覆盖 Gradium API 基础 URL（默认 `https://api.gradium.ai`）。 - `providers.gradium.voiceId`：Gradium 语音标识符（默认 Emma，`YTpq7expH9539ERJ`）。 - `providers.xai.apiKey`：xAI TTS API 密钥（环境变量：`XAI_API_KEY`）。 - `providers.xai.baseUrl`：覆盖 xAI TTS 基础 URL（默认 `https://api.x.ai/v1`，环境变量：`XAI_BASE_URL`）。 -- `providers.xai.voiceId`：xAI 语音 id（默认 `eve`；当前可用实时语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`）。 +- `providers.xai.voiceId`：xAI 语音 id（默认 `eve`；当前可用语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`）。 - `providers.xai.language`：BCP-47 语言代码或 `auto`（默认 `en`）。 - `providers.xai.responseFormat`：`mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`（默认 `mp3`）。 - `providers.xai.speed`：提供商原生速度覆盖值。 -- `providers.openrouter.apiKey`：OpenRouter API 密钥（环境变量：`OPENROUTER_API_KEY`；可复用 `models.providers.openrouter.apiKey`）。 +- `providers.openrouter.apiKey`：OpenRouter API 密钥（环境变量：`OPENROUTER_API_KEY`；也可复用 `models.providers.openrouter.apiKey`）。 - `providers.openrouter.baseUrl`：覆盖 OpenRouter TTS 基础 URL（默认 `https://openrouter.ai/api/v1`；旧版 `https://openrouter.ai/v1` 会被规范化）。 - `providers.openrouter.model`：OpenRouter TTS 模型 id（默认 `hexgrad/kokoro-82m`；也接受 `modelId`）。 -- `providers.openrouter.voice`：提供商特定语音 id（默认 `af_alloy`；也接受 `voiceId`）。 +- `providers.openrouter.voice`：提供商特定的语音 id（默认 `af_alloy`；也接受 `voiceId`）。 - `providers.openrouter.responseFormat`：`mp3` 或 `pcm`（默认 `mp3`）。 - `providers.openrouter.speed`：提供商原生速度覆盖值。 - `providers.microsoft.enabled`：允许使用 Microsoft 语音（默认 `true`；无需 API 密钥）。 - `providers.microsoft.voice`：Microsoft 神经语音名称（例如 `en-US-MichelleNeural`）。 - `providers.microsoft.lang`：语言代码（例如 `en-US`）。 - `providers.microsoft.outputFormat`：Microsoft 输出格式（例如 `audio-24khz-48kbitrate-mono-mp3`）。 - - 有效值请参见 Microsoft Speech 输出格式；并非所有格式都受内置的基于 Edge 的传输支持。 + - 有效值请参阅 Microsoft Speech 输出格式；并非所有格式都受内置的 Edge 后端传输支持。 - `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`：百分比字符串（例如 `+10%`、`-5%`）。 - `providers.microsoft.saveSubtitles`：在音频文件旁写入 JSON 字幕。 - `providers.microsoft.proxy`：Microsoft 语音请求的代理 URL。 - `providers.microsoft.timeoutMs`：请求超时覆盖值（毫秒）。 -- `edge.*`：同一组 Microsoft 设置的旧版别名。运行 `openclaw doctor --fix` 可将持久化配置重写为 `providers.microsoft`。 +- `edge.*`：同一组 Microsoft 设置的旧版别名。运行 + `openclaw doctor --fix`，将持久化配置重写为 `providers.microsoft`。 -## 模型驱动的覆盖（默认开启） +## 模型驱动的覆盖项（默认开启） 默认情况下，模型**可以**为单条回复发出 TTS 指令。 -当 `messages.tts.auto` 为 `tagged` 时，必须使用这些指令才会触发音频。 +当 `messages.tts.auto` 为 `tagged` 时，必须使用这些指令才能触发音频。 -启用后，模型可以发出 `[[tts:...]]` 指令来为单条回复覆盖语音设置，还可以选择附带一个 `[[tts:text]]...[[/tts:text]]` 区块，用于提供表现性标签（笑声、歌唱提示等），这些内容只应出现在音频中。 +启用后，模型可以发出 `[[tts:...]]` 指令来覆盖单条回复的语音，还可以附带一个可选的 `[[tts:text]]...[[/tts:text]]` 块，用于提供仅应出现在音频中的表现性标签（笑声、唱歌提示等）。 -除非设置了 `modelOverrides.allowProvider: true`，否则 `provider=...` 指令会被忽略。 +除非设置 `modelOverrides.allowProvider: true`，否则 `provider=...` 指令会被忽略。 示例回复负载： @@ -418,16 +422,16 @@ Here you go. 可用的指令键（启用时）： - `provider`（已注册的语音提供商 id，例如 `openai`、`elevenlabs`、`google`、`gradium`、`minimax`、`microsoft`、`vydra` 或 `xai`；需要 `allowProvider: true`） -- `voice`（OpenAI 或 Gradium 语音）、`voiceName` / `voice_name` / `google_voice`（Google 语音）或 `voiceId`（ElevenLabs / Gradium / MiniMax / xAI） +- `voice`（OpenAI 或 Gradium 语音）、`voiceName` / `voice_name` / `google_voice`（Google 语音），或 `voiceId`（ElevenLabs / Gradium / MiniMax / xAI） - `model`（OpenAI TTS 模型、ElevenLabs 模型 id 或 MiniMax 模型）或 `google_model`（Google TTS 模型） - `stability`、`similarityBoost`、`style`、`speed`、`useSpeakerBoost` - `vol` / `volume`（MiniMax 音量，0-10） -- `pitch`（MiniMax 整数音高，-12 到 12；在发起 MiniMax 请求前，小数值会被截断） +- `pitch`（MiniMax 整数音高，-12 到 12；小数值会在 MiniMax 请求前被截断） - `applyTextNormalization`（`auto|on|off`） - `languageCode`（ISO 639-1） - `seed` -禁用所有模型覆盖： +禁用所有模型覆盖项： ```json5 { @@ -441,7 +445,7 @@ Here you go. } ``` -可选允许列表（启用提供商切换，同时保持其他参数仍可配置）： +可选允许列表（启用提供商切换，同时保留其他参数可配置）： ```json5 { @@ -457,13 +461,13 @@ Here you go. } ``` -## 每用户偏好设置 +## 按用户存储的偏好设置 -斜杠命令会将本地覆盖写入 `prefsPath`（默认： +斜杠命令会将本地覆盖项写入 `prefsPath`（默认： `~/.openclaw/settings/tts.json`，可通过 `OPENCLAW_TTS_PREFS` 或 `messages.tts.prefsPath` 覆盖）。 -已存储字段： +存储的字段： - `enabled` - `provider` @@ -474,54 +478,55 @@ Here you go. ## 输出格式（固定） -- **Feishu / Matrix / Telegram / WhatsApp**：Opus 语音消息（ElevenLabs 使用 `opus_48000_64`，OpenAI 使用 `opus`）。 - - 48 kHz / 64 kbps 是语音消息的良好折中方案。 +- **Feishu / Matrix / Telegram / WhatsApp**：语音便笺回复优先使用 Opus（ElevenLabs 使用 `opus_48000_64`，OpenAI 使用 `opus`）。 + - 48 kHz / 64 kbps 是语音消息的良好折中。 +- **Feishu**：当语音便笺回复生成为 MP3/WAV/M4A 或其他可能的音频文件时，Feishu 插件会在发送原生 `audio` 气泡前，使用 `ffmpeg` 将其转码为 48 kHz Ogg/Opus。如果转换失败，Feishu 会收到原始文件作为附件。 - **其他渠道**：MP3（ElevenLabs 使用 `mp3_44100_128`，OpenAI 使用 `mp3`）。 - - 44.1 kHz / 128 kbps 是语音清晰度的默认平衡选择。 -- **MiniMax**：普通音频附件使用 MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。对于 Feishu 和 Telegram 等语音便签目标，OpenClaw 会在发送前使用 `ffmpeg` 将 MiniMax MP3 转码为 48 kHz Opus。 -- **Google Gemini**：Gemini API TTS 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 用于音频附件，并对 Talk/电话直接返回 PCM。此路径不支持原生 Opus 语音便签格式。 -- **Gradium**：音频附件使用 WAV，语音便签目标使用 Opus，电话使用 8 kHz 的 `ulaw_8000`。 -- **xAI**：默认使用 MP3；`responseFormat` 可为 `mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`。OpenClaw 使用 xAI 的批量 REST TTS 端点，并返回完整音频附件；该提供商路径不使用 xAI 的流式 TTS WebSocket。此路径不支持原生 Opus 语音便签格式。 + - 44.1 kHz / 128 kbps 是兼顾语音清晰度的默认平衡点。 +- **MiniMax**：普通音频附件使用 MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。对于 Feishu 和 Telegram 等语音便笺目标，OpenClaw 会在交付前使用 `ffmpeg` 将 MiniMax 的 MP3 转码为 48 kHz Opus。 +- **Google Gemini**：Gemini API TTS 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 作为音频附件，并直接为 Talk/电话返回 PCM。此路径不支持原生 Opus 语音便笺格式。 +- **Gradium**：音频附件使用 WAV，语音便笺目标使用 Opus，电话使用 8 kHz 的 `ulaw_8000`。 +- **xAI**：默认使用 MP3；`responseFormat` 可为 `mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`。OpenClaw 使用 xAI 的批处理 REST TTS 端点，并返回完整音频附件；此提供商路径不使用 xAI 的流式 TTS WebSocket。此路径不支持原生 Opus 语音便笺格式。 - **Microsoft**：使用 `microsoft.outputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。 - - 内置传输支持 `outputFormat`，但并非所有格式都可由该服务提供。 + - 内置传输支持 `outputFormat`，但服务并不提供所有格式。 - 输出格式值遵循 Microsoft Speech 输出格式（包括 Ogg/WebM Opus）。 - - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保证的 Opus 语音消息，请使用 OpenAI/ElevenLabs。 - - 如果配置的 Microsoft 输出格式失败，OpenClaw 会重试并回退到 MP3。 + - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保障的 Opus 语音消息，请使用 OpenAI/ElevenLabs。 + - 如果配置的 Microsoft 输出格式失败，OpenClaw 会使用 MP3 重试。 -OpenAI/ElevenLabs 的输出格式会按渠道固定（见上文）。 +OpenAI/ElevenLabs 的输出格式按渠道固定（见上文）。 ## 自动 TTS 行为 启用后，OpenClaw 会： - 如果回复已包含媒体或 `MEDIA:` 指令，则跳过 TTS。 -- 跳过过短的回复（少于 10 个字符）。 -- 在启用时，使用 `agents.defaults.model.primary`（或 `summaryModel`）对长回复生成摘要。 +- 跳过非常短的回复（少于 10 个字符）。 +- 启用时，使用 `agents.defaults.model.primary`（或 `summaryModel`）对长回复进行摘要。 - 将生成的音频附加到回复中。 -如果回复超过 `maxLength` 且摘要已关闭（或摘要模型没有 API 密钥），则会跳过音频，仅发送普通文本回复。 +如果回复超过 `maxLength` 且摘要已关闭（或摘要模型没有 API 密钥），则会跳过音频，并发送普通文本回复。 ## 流程图 ``` -回复 -> 是否启用 TTS？ +回复 -> 已启用 TTS？ 否 -> 发送文本 - 是 -> 是否有媒体 / MEDIA: / 太短？ - 是 -> 发送文本 - 否 -> 长度 > 限制？ - 否 -> TTS -> 附加音频 - 是 -> 是否启用摘要？ - 否 -> 发送文本 - 是 -> 生成摘要（summaryModel 或 agents.defaults.model.primary） + 是 -> 是否有媒体 / MEDIA: / 过短？ + 是 -> 发送文本 + 否 -> 长度 > 限制？ + 否 -> TTS -> 附加音频 + 是 -> 已启用摘要？ + 否 -> 发送文本 + 是 -> 摘要（summaryModel 或 agents.defaults.model.primary） -> TTS -> 附加音频 ``` ## 斜杠命令用法 只有一个命令：`/tts`。 -启用详情见[斜杠命令](/zh-CN/tools/slash-commands)。 +启用细节请参见 [斜杠命令](/zh-CN/tools/slash-commands)。 -Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在该平台上注册 `/voice` 作为原生命令。文本形式的 `/tts ...` 仍然可用。 +Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在该平台将原生命令注册为 `/voice`。文本形式的 `/tts ...` 仍然可用。 ``` /tts off @@ -535,23 +540,24 @@ Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在该 说明： -- 命令需要经过授权的发送者（仍适用允许列表/所有者规则）。 +- 命令需要已获授权的发送者（允许列表/所有者规则仍然适用）。 - 必须启用 `commands.text` 或原生命令注册。 - 配置 `messages.tts.auto` 接受 `off|always|inbound|tagged`。 -- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会写为 `off`。 -- 如果你想使用 `inbound` 或 `tagged` 作为默认值，请使用配置。 +- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会将其写为 `off`。 +- 如果你希望默认值为 `inbound` 或 `tagged`，请使用配置。 - `limit` 和 `summary` 存储在本地偏好设置中，而不是主配置中。 -- `/tts audio` 会生成一次性的音频回复（不会将 TTS 切换为开启）。 +- `/tts audio` 会生成一次性的音频回复（不会打开 TTS）。 - `/tts status` 包含最近一次尝试的回退可见性： - 成功回退：`Fallback: -> ` 加 `Attempts: ...` - 失败：`Error: ...` 加 `Attempts: ...` - 详细诊断：`Attempt details: provider:outcome(reasonCode) latency` -- OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误详情和请求 id（如果提供商返回了该值），这些信息会显示在 TTS 错误/日志中。 +- OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误详情和请求 id（如果提供商返回了该信息），并会在 TTS 错误/日志中显示。 ## 智能体工具 -`tts` 工具可将文本转换为语音，并返回一个音频附件以供回复发送。当渠道为 Feishu、Matrix、Telegram 或 WhatsApp 时，音频会以语音消息而非文件附件的形式发送。 -它接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是按次调用的提供商请求超时时间，单位为毫秒。 +`tts` 工具可将文本转换为语音，并返回用于回复投递的音频附件。当渠道为 Feishu、Matrix、Telegram 或 WhatsApp 时，音频会作为语音消息而不是文件附件进行投递。 +当 `ffmpeg` 可用时，Feishu 在此路径上可以对非 Opus 的 TTS 输出进行转码。 +它接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是单次调用的提供商请求超时时间，单位为毫秒。 ## Gateway 网关 RPC