From bec660f0975db3dd5593fa16f37c1c910a09ff8a Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 05:17:59 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/gateway/heartbeat.md | 270 ++++++++++++++++---------------- docs/zh-CN/providers/google.md | 137 ++++++++-------- docs/zh-CN/tools/tts.md | 211 ++++++++++++------------- 3 files changed, 307 insertions(+), 311 deletions(-) diff --git a/docs/zh-CN/gateway/heartbeat.md b/docs/zh-CN/gateway/heartbeat.md index 9337c07a1..fab058e39 100644 --- a/docs/zh-CN/gateway/heartbeat.md +++ b/docs/zh-CN/gateway/heartbeat.md @@ -1,38 +1,38 @@ --- read_when: - 调整心跳频率或消息内容 - - 在心跳和 cron 之间决定用于定时任务的方案 + - 为计划任务决定使用心跳还是 cron summary: 心跳轮询消息和通知规则 title: 心跳 x-i18n: - generated_at: "2026-04-24T18:08:23Z" + generated_at: "2026-04-25T05:16:43Z" model: gpt-5.4 provider: openai - source_hash: 673d9b0700679135d6ac1cc89256de4238f69c513c853f68e6888c6e19070ae4 + source_hash: 17353a03bbae7ad564548e767099f8596764e2cf9bc3d457ec9fc3482ba7d71c source_path: gateway/heartbeat.md workflow: 15 --- -> **心跳还是 Cron？** 关于何时使用两者中的哪一个，请参见 [自动化与任务](/zh-CN/automation)。 +> **心跳还是 Cron？** 关于何时使用两者的指导，请参见 [Automation & Tasks](/zh-CN/automation)。 -心跳会在主会话中运行**周期性的智能体轮次**，让模型能够发现任何需要注意的事项，而不会对刷屏造成干扰。 +心跳会在主会话中运行**周期性的智能体轮次**，这样模型就可以发现任何需要你关注的事项，而不会对你造成刷屏。 -心跳是一次计划执行的主会话轮次——它**不会**创建[后台任务](/zh-CN/automation/tasks)记录。 -任务记录用于脱离式工作（ACP 运行、子智能体、隔离的 cron 作业）。 +心跳是一个按计划执行的主会话轮次——它**不会**创建 [后台任务](/zh-CN/automation/tasks) 记录。 +任务记录用于脱离主会话的工作（ACP 运行、子智能体、隔离的 cron 作业）。 -故障排除： [计划任务](/zh-CN/automation/cron-jobs#troubleshooting) +故障排除：[计划任务](/zh-CN/automation/cron-jobs#troubleshooting) ## 快速开始（新手） -1. 保持启用心跳（默认是 `30m`，或对于 Anthropic OAuth/令牌认证为 `1h`，包括 Claude CLI 复用），或者设置你自己的频率。 -2. 在智能体工作区中创建一个简短的 `HEARTBEAT.md` 清单或 `tasks:` 块（可选但推荐）。 -3. 决定心跳消息应该发送到哪里（默认是 `target: "none"`；设置 `target: "last"` 可路由到最近一次联系）。 +1. 保持心跳启用状态（默认是 `30m`，对于 Anthropic OAuth/token 认证，包括 Claude CLI 复用，则为 `1h`），或者设置你自己的频率。 +2. 在智能体工作区中创建一个简短的 `HEARTBEAT.md` 检查清单或 `tasks:` 块（可选，但推荐）。 +3. 决定心跳消息应发送到哪里（`target: "none"` 是默认值；设置 `target: "last"` 可将其路由到最后一个联系人）。 4. 可选：启用心跳推理投递以提高透明度。 -5. 可选：如果心跳运行只需要 `HEARTBEAT.md`，可使用轻量级 bootstrap 上下文。 -6. 可选：启用隔离会话，以避免每次心跳都发送完整会话历史。 +5. 可选：如果心跳运行只需要 `HEARTBEAT.md`，可使用轻量级引导上下文。 +6. 可选：启用隔离会话，以避免每次心跳都发送完整的对话历史。 7. 可选：将心跳限制在活跃时段内（本地时间）。 -示例配置： +配置示例： ```json5 { @@ -40,12 +40,12 @@ x-i18n: defaults: { heartbeat: { every: "30m", - target: "last", // 显式投递到最近一次联系（默认是 "none"） - directPolicy: "allow", // 默认：允许 direct/私信目标；设为 "block" 则抑制 - lightContext: true, // 可选：仅从 bootstrap 文件注入 HEARTBEAT.md - isolatedSession: true, // 可选：每次运行使用全新会话（无会话历史） + target: "last", // 显式投递到最后一个联系人（默认是 "none"） + directPolicy: "allow", // 默认：允许直接/私信目标；设为 "block" 则抑制 + lightContext: true, // 可选：仅从引导文件中注入 HEARTBEAT.md + isolatedSession: true, // 可选：每次运行使用全新会话（无对话历史） // activeHours: { start: "08:00", end: "24:00" }, - // includeReasoning: true, // 可选：额外发送单独的 `Reasoning:` 消息 + // includeReasoning: true, // 可选：也单独发送 `Reasoning:` 消息 }, }, }, @@ -54,34 +54,33 @@ x-i18n: ## 默认值 -- 间隔：`30m`（或者当检测到 Anthropic OAuth/令牌认证模式时为 `1h`，包括 Claude CLI 复用）。设置 `agents.defaults.heartbeat.every` 或每个智能体的 `agents.list[].heartbeat.every`；使用 `0m` 可禁用。 +- 间隔：`30m`（或者在检测到 Anthropic OAuth/token 认证模式时为 `1h`，包括 Claude CLI 复用）。设置 `agents.defaults.heartbeat.every` 或按智能体设置 `agents.list[].heartbeat.every`；使用 `0m` 可禁用。 - 提示词正文（可通过 `agents.defaults.heartbeat.prompt` 配置）： `Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.` -- 心跳提示词会**原样**作为用户消息发送。仅当默认智能体启用了心跳且运行在内部被标记为心跳时，系统提示词才会包含 “Heartbeat” 部分。 -- 当使用 `0m` 禁用心跳时，普通运行也会从 bootstrap 上下文中省略 `HEARTBEAT.md`，这样模型就不会看到仅供心跳使用的指令。 -- 活跃时段（`heartbeat.activeHours`）会按配置的时区进行检查。 - 在该时间窗之外，心跳会被跳过，直到窗口内的下一次 tick。 +- 心跳提示词会**原样**作为用户消息发送。系统提示词仅在为默认智能体启用心跳且该运行被内部标记时，才会包含 “Heartbeat” 部分。 +- 当使用 `0m` 禁用心跳时，普通运行也会从引导上下文中省略 `HEARTBEAT.md`，这样模型就看不到仅供心跳使用的指令。 +- 活跃时段（`heartbeat.activeHours`）会在配置的时区中进行检查。 + 在该时间窗口之外，心跳会被跳过，直到窗口内的下一个 tick。 ## 心跳提示词的用途 -默认提示词故意设计得比较宽泛： +默认提示词有意保持较宽泛： -- **后台任务**：“考虑未完成任务” 会推动智能体检查后续事项（收件箱、日历、提醒、排队工作），并暴露任何紧急内容。 -- **人工检查**：“白天有时关心一下你的主人” 会推动偶尔发送轻量级的 “你需要什么吗？” 消息，但会通过你配置的本地时区避免夜间刷屏（见 [/concepts/timezone](/zh-CN/concepts/timezone)）。 +- **后台任务**：“Consider outstanding tasks” 会推动智能体检查待处理事项（收件箱、日历、提醒、排队工作），并将任何紧急事项呈现出来。 +- **人工签到**：“Checkup sometimes on your human during day time” 会推动偶尔发送轻量级的“你需要什么吗？”消息，但会通过使用你配置的本地时区（参见 [/concepts/timezone](/zh-CN/concepts/timezone)）来避免夜间刷屏。 -心跳可以对已完成的[后台任务](/zh-CN/automation/tasks)做出反应，但心跳运行本身不会创建任务记录。 +心跳可以对已完成的 [后台任务](/zh-CN/automation/tasks) 作出反应，但心跳运行本身不会创建任务记录。 -如果你希望心跳执行非常具体的事情（例如“检查 Gmail PubSub 统计”或“验证 Gateway 网关健康状态”），请将 `agents.defaults.heartbeat.prompt`（或 `agents.list[].heartbeat.prompt`）设置为自定义正文（按原样发送）。 +如果你希望心跳执行非常具体的操作（例如“检查 Gmail PubSub 统计信息”或“验证 Gateway 网关健康状态”），请将 `agents.defaults.heartbeat.prompt`（或 `agents.list[].heartbeat.prompt`）设置为自定义正文（将原样发送）。 ## 响应约定 -- 如果没有任何需要注意的事项，请回复 **`HEARTBEAT_OK`**。 -- 在心跳运行期间，当 `HEARTBEAT_OK` 出现在回复的**开头或结尾**时，OpenClaw 会将其视为 ack。 - 如果去掉该标记后剩余内容**≤ `ackMaxChars`**（默认：300），则会移除该标记并丢弃回复。 -- 如果 `HEARTBEAT_OK` 出现在回复**中间**，则不会被特殊处理。 -- 对于告警，**不要**包含 `HEARTBEAT_OK`；只返回告警文本。 +- 如果没有任何事项需要关注，请回复 **`HEARTBEAT_OK`**。 +- 在心跳运行期间，当 `HEARTBEAT_OK` 出现在回复的**开头或结尾**时，OpenClaw 会将其视为确认。该标记会被去除；如果剩余内容**≤ `ackMaxChars`**（默认：300），则回复会被丢弃。 +- 如果 `HEARTBEAT_OK` 出现在回复的**中间**，则不会被特殊处理。 +- 对于提醒消息，**不要**包含 `HEARTBEAT_OK`；只返回提醒文本。 -在心跳之外，如果消息开头/结尾意外出现 `HEARTBEAT_OK`，该标记会被移除并记入日志；如果消息仅包含 `HEARTBEAT_OK`，则会被丢弃。 +在非心跳场景下，若消息开头/结尾意外出现 `HEARTBEAT_OK`，它会被去除并记录日志；如果消息内容只有 `HEARTBEAT_OK`，则会被丢弃。 ## 配置 @@ -92,12 +91,12 @@ x-i18n: heartbeat: { every: "30m", // 默认：30m（0m 禁用） model: "anthropic/claude-opus-4-6", - includeReasoning: false, // 默认：false（可用时投递单独的 Reasoning: 消息） - lightContext: false, // 默认：false；true 时仅保留工作区 bootstrap 文件中的 HEARTBEAT.md - isolatedSession: false, // 默认：false；true 时每次心跳都在全新会话中运行（无会话历史） - target: "last", // 默认：none | 选项：last | none | （核心或插件，例如 "bluebubbles"） - to: "+15551234567", // 可选的渠道专用覆盖值 - accountId: "ops-bot", // 可选的多账户渠道 id + includeReasoning: false, // 默认：false（在可用时单独投递 Reasoning: 消息） + lightContext: false, // 默认：false；true 时仅从工作区引导文件中保留 HEARTBEAT.md + isolatedSession: false, // 默认：false；true 时每次心跳都在全新会话中运行（无对话历史） + target: "last", // 默认：none | 可选值：last | none | （核心或插件，例如 "bluebubbles"） + to: "+15551234567", // 可选的渠道特定覆盖 + accountId: "ops-bot", // 可选的多账号渠道 id prompt: "Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.", ackMaxChars: 300, // HEARTBEAT_OK 之后允许的最大字符数 }, @@ -106,18 +105,17 @@ x-i18n: } ``` -### 范围与优先级 +### 作用域和优先级 - `agents.defaults.heartbeat` 设置全局心跳行为。 -- `agents.list[].heartbeat` 会在其上合并；如果任何智能体带有 `heartbeat` 块，则**只有这些智能体**会运行心跳。 -- `channels.defaults.heartbeat` 设置所有渠道的可见性默认值。 +- `agents.list[].heartbeat` 会在其之上合并；如果任一智能体具有 `heartbeat` 块，则**只有这些智能体**会运行心跳。 +- `channels.defaults.heartbeat` 为所有渠道设置可见性默认值。 - `channels..heartbeat` 会覆盖渠道默认值。 -- `channels..accounts..heartbeat`（多账户渠道）会按每个渠道账户进行覆盖。 +- `channels..accounts..heartbeat`（多账号渠道）会按渠道进一步覆盖。 -### 每智能体心跳 +### 按智能体配置的心跳 -如果任何 `agents.list[]` 条目包含 `heartbeat` 块，则**只有这些智能体**会运行心跳。 -每智能体块会在 `agents.defaults.heartbeat` 之上合并（因此你可以先设置共享默认值，再按智能体覆盖）。 +如果任一 `agents.list[]` 条目包含 `heartbeat` 块，则**只有这些智能体**会运行心跳。按智能体配置的块会合并到 `agents.defaults.heartbeat` 之上（因此你可以先设置一次共享默认值，再按智能体覆盖）。 示例：两个智能体，只有第二个智能体运行心跳。 @@ -127,7 +125,7 @@ x-i18n: defaults: { heartbeat: { every: "30m", - target: "last", // 显式投递到最近一次联系（默认是 "none"） + target: "last", // 显式投递到最后一个联系人（默认是 "none"） }, }, list: [ @@ -157,11 +155,11 @@ x-i18n: defaults: { heartbeat: { every: "30m", - target: "last", // 显式投递到最近一次联系（默认是 "none"） + target: "last", // 显式投递到最后一个联系人（默认是 "none"） activeHours: { start: "09:00", end: "22:00", - timezone: "America/New_York", // 可选；如果设置了 userTimezone 则使用它，否则使用主机时区 + timezone: "America/New_York", // 可选；如果设置了 userTimezone，则使用它，否则使用主机时区 }, }, }, @@ -169,21 +167,21 @@ x-i18n: } ``` -在该时间窗之外（美国东部时间上午 9 点前或晚上 10 点后），心跳会被跳过。窗口内下一次计划 tick 会照常运行。 +在该时间窗口之外（美东时间上午 9 点之前或晚上 10 点之后），心跳会被跳过。窗口内下一次计划 tick 会正常运行。 ### 24/7 设置 -如果你希望心跳全天运行，可使用以下任一模式： +如果你希望心跳全天运行，请使用以下任一模式： -- 完全省略 `activeHours`（无时间窗限制；这是默认行为）。 +- 完全省略 `activeHours`（不限制时间窗口；这是默认行为）。 - 设置全天窗口：`activeHours: { start: "00:00", end: "24:00" }`。 不要将 `start` 和 `end` 设为相同时间（例如 `08:00` 到 `08:00`）。 -这会被视为零宽度窗口，因此心跳会始终被跳过。 +这会被视为零宽度窗口，因此心跳始终会被跳过。 -### 多账户示例 +### 多账号示例 -在 Telegram 等多账户渠道上，使用 `accountId` 来指定目标账户： +使用 `accountId` 来指定 Telegram 等多账号渠道中的特定账号： ```json5 { @@ -213,58 +211,58 @@ x-i18n: ### 字段说明 - `every`：心跳间隔（时长字符串；默认单位 = 分钟）。 -- `model`：心跳运行的可选模型覆盖值（`provider/model`）。 -- `includeReasoning`：启用后，当可用时还会投递单独的 `Reasoning:` 消息（与 `/reasoning on` 形式相同）。 -- `lightContext`：为 true 时，心跳运行使用轻量级 bootstrap 上下文，并且仅保留工作区 bootstrap 文件中的 `HEARTBEAT.md`。 -- `isolatedSession`：为 true 时，每次心跳都会在全新会话中运行，不带之前的会话历史。使用与 cron `sessionTarget: "isolated"` 相同的隔离模式。可显著降低每次心跳的 token 成本。与 `lightContext: true` 结合可获得最大节省。投递路由仍使用主会话上下文。 +- `model`：心跳运行的可选模型覆盖（`provider/model`）。 +- `includeReasoning`：启用后，在可用时也会投递单独的 `Reasoning:` 消息（与 `/reasoning on` 的形式相同）。 +- `lightContext`：为 true 时，心跳运行会使用轻量级引导上下文，并且只从工作区引导文件中保留 `HEARTBEAT.md`。 +- `isolatedSession`：为 true 时，每次心跳都会在一个全新会话中运行，不包含此前的对话历史。使用与 cron `sessionTarget: "isolated"` 相同的隔离模式。这会显著降低每次心跳的 token 成本。与 `lightContext: true` 结合可获得最大节省。投递路由仍使用主会话上下文。 - `session`：心跳运行的可选会话键。 - `main`（默认）：智能体主会话。 - - 显式会话键（可从 `openclaw sessions --json` 或 [sessions CLI](/zh-CN/cli/sessions) 复制）。 - - 会话键格式：见 [会话](/zh-CN/concepts/session) 和 [群组](/zh-CN/channels/groups)。 + - 显式会话键（从 `openclaw sessions --json` 或 [sessions CLI](/zh-CN/cli/sessions) 复制）。 + - 会话键格式：参见 [Sessions](/zh-CN/concepts/session) 和 [Groups](/zh-CN/channels/groups)。 - `target`： - - `last`：投递到最近使用的外部渠道。 + - `last`：投递到最后使用的外部渠道。 - 显式渠道：任何已配置的渠道或插件 id，例如 `discord`、`matrix`、`telegram` 或 `whatsapp`。 - - `none`（默认）：运行心跳，但**不**向外部投递。 -- `directPolicy`：控制 direct/私信投递行为： - - `allow`（默认）：允许 direct/私信心跳投递。 - - `block`：抑制 direct/私信投递（`reason=dm-blocked`）。 -- `to`：可选的收件人覆盖值（渠道专用 id，例如 WhatsApp 的 E.164 或 Telegram chat id）。对于 Telegram 的 topic/thread，请使用 `:topic:`。 -- `accountId`：多账户渠道的可选账户 id。当 `target: "last"` 时，如果解析出的最近渠道支持账户，则应用该账户 id；否则会被忽略。如果该账户 id 与解析出的渠道中已配置账户不匹配，则跳过投递。 + - `none`（默认）：运行心跳，但**不进行**外部投递。 +- `directPolicy`：控制直接/私信投递行为： + - `allow`（默认）：允许直接/私信心跳投递。 + - `block`：抑制直接/私信投递（`reason=dm-blocked`）。 +- `to`：可选的接收者覆盖（渠道特定 id，例如 WhatsApp 的 E.164 或 Telegram chat id）。对于 Telegram topics/threads，请使用 `:topic:`。 +- `accountId`：多账号渠道的可选账号 id。当 `target: "last"` 时，如果最后解析出的渠道支持账号，则该账号 id 会应用于该渠道；否则将被忽略。如果该账号 id 与解析出的渠道中已配置的账号不匹配，则会跳过投递。 - `prompt`：覆盖默认提示词正文（不合并）。 -- `ackMaxChars`：`HEARTBEAT_OK` 之后允许的最大字符数，超过则仍会投递。 -- `suppressToolErrorWarnings`：为 true 时，在心跳运行期间抑制工具错误警告载荷。 -- `activeHours`：将心跳运行限制在一个时间窗内。对象包含 `start`（HH:MM，含边界；一天开始请用 `00:00`）、`end`（HH:MM，不含边界；一天结束可用 `24:00`）以及可选的 `timezone`。 - - 省略或设为 `"user"`：如果设置了 `agents.defaults.userTimezone` 则使用它，否则回退到主机系统时区。 +- `ackMaxChars`：在 `HEARTBEAT_OK` 之后允许的最大字符数，超出则进行投递。 +- `suppressToolErrorWarnings`：为 true 时，会在心跳运行期间抑制工具错误警告负载。 +- `activeHours`：将心跳运行限制在某个时间窗口内。对象包含 `start`（HH:MM，含边界；一天开始请使用 `00:00`）、`end`（HH:MM，不含边界；一天结束允许使用 `24:00`）以及可选的 `timezone`。 + - 省略或设为 `"user"`：如果设置了 `agents.defaults.userTimezone`，则使用它，否则回退到主机系统时区。 - `"local"`：始终使用主机系统时区。 - - 任意 IANA 标识符（例如 `America/New_York`）：直接使用；如果无效，则回退到上面的 `"user"` 行为。 - - `start` 和 `end` 不能相同，否则活动窗口会被视为零宽度（始终在窗口之外）。 - - 在活动窗口之外，心跳会被跳过，直到窗口内的下一次 tick。 + - 任意 IANA 标识符（例如 `America/New_York`）：直接使用；如果无效，则回退到上述 `"user"` 行为。 + - `start` 和 `end` 不能相等来表示一个有效窗口；相等值会被视为零宽度（始终处于窗口外）。 + - 在活跃窗口之外，心跳会被跳过，直到窗口内的下一个 tick。 ## 投递行为 -- 心跳默认在智能体的主会话中运行（`agent::`），或者当 `session.scope = "global"` 时使用 `global`。设置 `session` 可覆盖为特定渠道会话（Discord/WhatsApp 等）。 +- 心跳默认在智能体的主会话中运行（`agent::`），如果 `session.scope = "global"`，则运行在 `global` 中。设置 `session` 可覆盖为特定的渠道会话（Discord/WhatsApp 等）。 - `session` 只影响运行上下文；投递由 `target` 和 `to` 控制。 -- 要投递到特定渠道/收件人，请设置 `target` + `to`。使用 `target: "last"` 时，投递会使用该会话最近一次的外部渠道。 -- 心跳默认允许投递到 direct/私信目标。设置 `directPolicy: "block"` 可抑制发送到直接目标，同时仍运行心跳轮次。 -- 如果主队列繁忙，心跳会被跳过，并在之后重试。 -- 如果 `target` 未解析到外部目标，运行仍会发生，但不会发送出站消息。 -- 如果 `showOk`、`showAlerts` 和 `useIndicator` 全部被禁用，则运行会在一开始被跳过，原因为 `reason=alerts-disabled`。 -- 如果仅禁用了告警投递，OpenClaw 仍可运行心跳、更新到期任务时间戳、恢复会话空闲时间戳，并抑制对外告警载荷。 -- 如果解析出的心跳目标支持输入状态，OpenClaw 会在心跳运行期间显示输入中。这使用与心跳发送聊天输出相同的目标，并可通过 `typingMode: "never"` 禁用。 -- 仅包含心跳内容的回复**不会**保持会话存活；最后的 `updatedAt` 会被恢复，因此空闲过期行为保持正常。 -- 脱离式[后台任务](/zh-CN/automation/tasks)可以入队一个系统事件并唤醒心跳，以便主会话能更快注意到某些事项。这种唤醒不会让心跳运行变成后台任务。 +- 如需投递到特定渠道/接收者，请设置 `target` + `to`。当使用 `target: "last"` 时，投递会使用该会话最后一个外部渠道。 +- 心跳投递默认允许直接/私信目标。设置 `directPolicy: "block"` 可抑制发送到直接目标，同时仍运行心跳轮次。 +- 如果主队列繁忙，心跳会被跳过，并在稍后重试。 +- 如果 `target` 未解析出任何外部目标，运行仍会发生，但不会发送任何出站消息。 +- 如果 `showOk`、`showAlerts` 和 `useIndicator` 全部被禁用，则该运行会在开始前被跳过，并标记为 `reason=alerts-disabled`。 +- 如果仅禁用了提醒投递，OpenClaw 仍可运行心跳、更新到期任务时间戳、恢复会话空闲时间戳，并抑制对外提醒负载。 +- 如果解析出的心跳目标支持输入状态，OpenClaw 会在心跳运行期间显示正在输入。这使用与心跳发送聊天输出相同的目标，并且可通过 `typingMode: "never"` 禁用。 +- 仅包含心跳内容的回复**不会**保持会话活跃；最后的 `updatedAt` 会被恢复，因此空闲过期行为仍然正常。 +- Control UI 和 WebChat 历史记录会隐藏心跳提示词以及仅含 OK 的确认消息。底层会话转录仍可能包含这些轮次，用于审计/重放。 +- 脱离主会话的 [后台任务](/zh-CN/automation/tasks) 可以入队一个系统事件并唤醒心跳，以便主会话尽快注意到某些事项。该唤醒并不会让心跳运行变成后台任务。 ## 可见性控制 -默认情况下，会抑制 `HEARTBEAT_OK` 确认消息，而告警内容会被投递。 -你可以按渠道或按账户进行调整： +默认情况下，`HEARTBEAT_OK` 确认消息会被抑制，而提醒内容会被投递。你可以按渠道或按账号调整此行为： ```yaml channels: defaults: heartbeat: showOk: false # 隐藏 HEARTBEAT_OK（默认） - showAlerts: true # 显示告警消息（默认） + showAlerts: true # 显示提醒消息（默认） useIndicator: true # 发出指示器事件（默认） telegram: heartbeat: @@ -273,20 +271,20 @@ channels: accounts: work: heartbeat: - showAlerts: false # 对此账户抑制告警投递 + showAlerts: false # 为此账号抑制提醒投递 ``` -优先级：每账户 → 每渠道 → 渠道默认值 → 内置默认值。 +优先级：按账号 → 按渠道 → 渠道默认值 → 内置默认值。 ### 每个标志的作用 -- `showOk`：当模型返回仅包含 OK 的回复时，发送 `HEARTBEAT_OK` 确认消息。 -- `showAlerts`：当模型返回非 OK 回复时，发送告警内容。 +- `showOk`：当模型返回仅含 OK 的回复时，发送 `HEARTBEAT_OK` 确认消息。 +- `showAlerts`：当模型返回非 OK 回复时，发送提醒内容。 - `useIndicator`：为 UI 状态界面发出指示器事件。 -如果**三者**都为 false，OpenClaw 会完全跳过心跳运行（不会调用模型）。 +如果**三者全部**为 false，OpenClaw 会完全跳过心跳运行（不调用模型）。 -### 每渠道与每账户示例 +### 按渠道与按账号示例 ```yaml channels: @@ -297,11 +295,11 @@ channels: useIndicator: true slack: heartbeat: - showOk: true # 所有 Slack 账户 + showOk: true # 所有 Slack 账号 accounts: ops: heartbeat: - showAlerts: false # 仅对 ops 账户抑制告警 + showAlerts: false # 仅为 ops 账号抑制提醒 telegram: heartbeat: showOk: true @@ -311,24 +309,22 @@ channels: | 目标 | 配置 | | ---------------------------------------- | ---------------------------------------------------------------------------------------- | -| 默认行为（静默 OK，开启告警） | _(无需配置)_ | -| 完全静默（无消息、无指示器） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | +| 默认行为（静默 OK，开启提醒） | _(无需配置)_ | +| 完全静默（无消息，无指示器） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: false }` | | 仅指示器（无消息） | `channels.defaults.heartbeat: { showOk: false, showAlerts: false, useIndicator: true }` | -| 仅在一个渠道中显示 OK | `channels.telegram.heartbeat: { showOk: true }` | +| 仅在一个渠道显示 OK | `channels.telegram.heartbeat: { showOk: true }` | -## HEARTBEAT.md（可选） +## `HEARTBEAT.md`（可选） -如果工作区中存在 `HEARTBEAT.md` 文件，默认提示词会要求智能体读取它。 -你可以把它理解为你的“心跳检查清单”：内容小、稳定，并且适合每 30 分钟都纳入一次。 +如果工作区中存在 `HEARTBEAT.md` 文件，默认提示词会告诉智能体读取它。你可以把它看作你的“心跳检查清单”：简短、稳定，并且适合每 30 分钟都包含一次。 -在普通运行中，仅当默认智能体启用了心跳指引时，才会注入 `HEARTBEAT.md`。 -使用 `0m` 禁用心跳频率，或设置 `includeSystemPromptSection: false`，都会将它从普通 bootstrap 上下文中省略。 +在普通运行中，只有当为默认智能体启用了心跳指导时，才会注入 `HEARTBEAT.md`。将心跳频率设置为 `0m` 来禁用，或设置 `includeSystemPromptSection: false`，都会使其不再出现在普通引导上下文中。 -如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和 Markdown 标题，例如 `# Heading`），OpenClaw 会跳过该次心跳运行，以节省 API 调用。 -该跳过会报告为 `reason=empty-heartbeat-file`。 -如果文件不存在，心跳仍会运行，并由模型自行决定该做什么。 +如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和 Markdown 标题，例如 `# Heading`），OpenClaw 会跳过心跳运行以节省 API 调用。 +该跳过会标记为 `reason=empty-heartbeat-file`。 +如果文件缺失，心跳仍会运行，并由模型决定该做什么。 -请保持内容简短（简短清单或提醒），以避免提示词膨胀。 +请保持它简短（简要清单或提醒），以避免提示词膨胀。 示例 `HEARTBEAT.md`： @@ -342,7 +338,7 @@ channels: ### `tasks:` 块 -`HEARTBEAT.md` 还支持一个小型结构化 `tasks:` 块，用于在心跳内部执行基于间隔的检查。 +`HEARTBEAT.md` 还支持一个小型结构化的 `tasks:` 块，用于在心跳内部执行基于间隔的检查。 示例： @@ -362,29 +358,29 @@ tasks: - If nothing needs attention after all due tasks, reply HEARTBEAT_OK. ``` -行为： +行为如下： -- OpenClaw 会解析 `tasks:` 块，并根据每个任务自己的 `interval` 进行检查。 -- 每次 tick 的心跳提示词中只包含**已到期**的任务。 -- 如果没有任务到期，则会完全跳过该次心跳（`reason=no-tasks-due`），以避免浪费一次模型调用。 -- `HEARTBEAT.md` 中非任务内容会被保留，并作为附加上下文追加在到期任务列表之后。 -- 任务上次运行时间戳会存储在会话状态（`heartbeatTaskState`）中，因此这些间隔在正常重启后仍能保留。 -- 只有在心跳运行完成其正常回复路径后，任务时间戳才会前移。被跳过的 `empty-heartbeat-file` / `no-tasks-due` 运行不会将任务标记为已完成。 +- OpenClaw 会解析 `tasks:` 块，并根据每个任务自己的 `interval` 检查它。 +- 每个 tick 的心跳提示词中只会包含**到期**任务。 +- 如果没有任务到期，心跳会被完全跳过（`reason=no-tasks-due`），以避免浪费一次模型调用。 +- `HEARTBEAT.md` 中的非任务内容会被保留，并作为额外上下文附加在到期任务列表之后。 +- 任务的上次运行时间戳会存储在会话状态（`heartbeatTaskState`）中，因此在正常重启后间隔信息仍会保留。 +- 只有当一次心跳运行完成其正常回复路径后，任务时间戳才会推进。被跳过的 `empty-heartbeat-file` / `no-tasks-due` 运行不会将任务标记为已完成。 -任务模式适用于这样的场景：你希望一个心跳文件容纳多个周期性检查，但又不想在每次 tick 时都为所有检查付费。 +当你希望一个心跳文件承载多个周期性检查、但又不想在每个 tick 都为所有检查付费时，任务模式会很有用。 -### 智能体可以更新 HEARTBEAT.md 吗？ +### 智能体可以更新 `HEARTBEAT.md` 吗？ 可以——如果你要求它这样做。 -`HEARTBEAT.md` 只是智能体工作区中的一个普通文件，因此你可以在普通聊天中告诉智能体，例如： +`HEARTBEAT.md` 只是智能体工作区中的普通文件，因此你可以在普通聊天中告诉智能体，例如： -- “更新 `HEARTBEAT.md`，加入每日历检查。” -- “重写 `HEARTBEAT.md`，让它更短，并专注于收件箱跟进。” +- “更新 `HEARTBEAT.md`，添加一个每日历检查。” +- “重写 `HEARTBEAT.md`，让它更简短，并聚焦于收件箱跟进事项。” -如果你希望这件事主动发生，也可以在心跳提示词中加入明确的一行，例如：“如果清单已经过时，请更新 HEARTBEAT.md，改成一个更好的版本。” +如果你希望它主动这样做，也可以在你的心跳提示词中加入一条明确说明，例如：“如果检查清单已过时，请更新 HEARTBEAT.md，换成更好的版本。” -安全说明：不要把机密信息（API 密钥、电话号码、私有令牌）写入 `HEARTBEAT.md`——它会成为提示词上下文的一部分。 +安全提示：不要将机密信息（API 密钥、电话号码、私密 token）放入 `HEARTBEAT.md`——它会成为提示词上下文的一部分。 ## 手动唤醒（按需） @@ -394,33 +390,33 @@ tasks: openclaw system event --text "Check for urgent follow-ups" --mode now ``` -如果多个智能体配置了 `heartbeat`，一次手动唤醒会立即运行这些智能体各自的心跳。 +如果有多个智能体配置了 `heartbeat`，手动唤醒会立即运行这些智能体中的每一个心跳。 使用 `--mode next-heartbeat` 可等待下一次计划 tick。 ## 推理投递（可选） -默认情况下，心跳只投递最终的“answer”载荷。 +默认情况下，心跳只会投递最终的“answer”负载。 如果你希望提高透明度，请启用： - `agents.defaults.heartbeat.includeReasoning: true` -启用后，心跳还会额外投递一条以 `Reasoning:` 为前缀的消息（形式与 `/reasoning on` 相同）。当智能体正在管理多个会话/Codexes，而你想了解它为何决定提醒你时，这会很有用——但它也可能泄露比你想要更多的内部细节。在群聊中建议保持关闭。 +启用后，心跳还会投递一条单独的消息，前缀为 `Reasoning:`（形式与 `/reasoning on` 相同）。当智能体正在管理多个会话/Codex harness 时，这在你想了解它为何决定提醒你时会很有用——但它也可能泄露比你希望看到的更多内部细节。在群聊中，建议保持关闭。 ## 成本意识 -心跳会运行完整的智能体轮次。更短的间隔会消耗更多 token。要降低成本： +心跳会运行完整的智能体轮次。间隔越短，消耗的 token 越多。为了降低成本： -- 使用 `isolatedSession: true`，避免发送完整会话历史（每次运行大约可从 ~100K token 降到 ~2-5K）。 -- 使用 `lightContext: true`，将 bootstrap 文件限制为仅 `HEARTBEAT.md`。 +- 使用 `isolatedSession: true`，避免发送完整对话历史（每次运行可从约 100K token 降到约 2-5K）。 +- 使用 `lightContext: true`，将引导文件限制为仅 `HEARTBEAT.md`。 - 设置更便宜的 `model`（例如 `ollama/llama3.2:1b`）。 - 保持 `HEARTBEAT.md` 简短。 -- 如果你只想要内部状态更新，请使用 `target: "none"`。 +- 如果你只想更新内部状态，请使用 `target: "none"`。 -## 相关 +## 相关内容 -- [自动化与任务](/zh-CN/automation) — 一览所有自动化机制 -- [后台任务](/zh-CN/automation/tasks) — 脱离式工作如何被跟踪 -- [时区](/zh-CN/concepts/timezone) — 时区如何影响心跳调度 -- [故障排除](/zh-CN/automation/cron-jobs#troubleshooting) — 调试自动化问题 +- [Automation & Tasks](/zh-CN/automation) — 所有自动化机制一览 +- [后台任务](/zh-CN/automation/tasks) — 脱离主会话的工作如何被跟踪 +- [Timezone](/zh-CN/concepts/timezone) — 时区如何影响心跳调度 +- [故障排除](/zh-CN/automation/cron-jobs#troubleshooting) — 自动化问题调试指南 diff --git a/docs/zh-CN/providers/google.md b/docs/zh-CN/providers/google.md index 8252862d5..e7e28668d 100644 --- a/docs/zh-CN/providers/google.md +++ b/docs/zh-CN/providers/google.md @@ -1,41 +1,33 @@ --- read_when: - 你想在 OpenClaw 中使用 Google Gemini 模型 - - 你需要 API 密钥或 OAuth 凭证流程 -summary: Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、TTS、Web 搜索） + - 你需要 API 密钥或 OAuth 认证流程 +summary: Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、TTS、网页搜索） title: Google（Gemini） x-i18n: - generated_at: "2026-04-25T01:28:12Z" + generated_at: "2026-04-25T05:16:41Z" model: gpt-5.4 provider: openai - source_hash: b8644a578180600ba65275c28e45cc31eb131173d0f0abdd29dcee908d625642 + source_hash: de0d6563d1c7a25fe26aa7ce255b1d3ed80e950b7761039e6d0a76f23a14e6f3 source_path: providers/google.md workflow: 15 --- -Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、TTS、Web 搜索） - -Google（Gemini） - -你想在 OpenClaw 中使用 Google Gemini 模型 - -你需要 API 密钥或 OAuth 凭证流程 - -Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并支持通过 Gemini Grounding 实现图像生成、媒体理解（图像 / 音频 / 视频）、文本转语音和 Web 搜索。 +Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，另外还支持通过 Gemini Grounding 实现图像生成、媒体理解（图像/音频/视频）、文本转语音和网页搜索。 - 提供商：`google` -- 凭证：`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` +- 认证：`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` - API：Google Gemini API - 运行时选项：`agents.defaults.embeddedHarness.runtime: "google-gemini-cli"` - 会复用 Gemini CLI OAuth，同时保持模型引用规范形式为 `google/*`。 + 会复用 Gemini CLI OAuth，同时保持模型引用规范为 `google/*`。 ## 入门指南 -选择你偏好的凭证方式，并按照设置步骤操作。 +选择你偏好的认证方式，并按照设置步骤进行操作。 - **最适合：** 通过 Google AI Studio 进行标准 Gemini API 访问。 + **最适合：** 通过 Google AI Studio 进行标准的 Gemini API 访问。 @@ -63,7 +55,7 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并支 } ``` - + ```bash openclaw models list --provider google ``` @@ -71,16 +63,16 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并支 - 环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都可接受。使用你已经配置好的那个即可。 + 环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都可以使用。使用你已经配置好的那个即可。 - **最适合：** 复用现有的 Gemini CLI 登录，通过 PKCE OAuth，而不是使用单独的 API 密钥。 + **最适合：** 复用现有的 Gemini CLI 登录，通过 PKCE OAuth 而不是单独的 API 密钥进行认证。 - `google-gemini-cli` 提供商属于非官方集成。一些用户报告称，以这种方式使用 OAuth 时会遇到账户限制。请自行承担风险。 + `google-gemini-cli` 提供商是一个非官方集成。有些用户报告称，以这种方式使用 OAuth 时会遇到账户限制。请自行承担风险。 @@ -95,14 +87,14 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并支 npm install -g @google/gemini-cli ``` - OpenClaw 同时支持 Homebrew 安装和全局 npm 安装，包括常见的 Windows / npm 布局。 + OpenClaw 同时支持通过 Homebrew 安装和全局 npm 安装，包括常见的 Windows/npm 布局。 ```bash openclaw models auth login --provider google-gemini-cli --set-default ``` - + ```bash openclaw models list --provider google ``` @@ -125,10 +117,10 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并支 - 如果在浏览器流程开始之前登录就失败，请确保本地 `gemini` 命令已安装并且位于 `PATH` 中。 + 如果在浏览器流程开始前登录就失败，请确认本地 `gemini` 命令已安装并且位于 `PATH` 中。 - `google-gemini-cli/*` 模型引用是旧版兼容别名。新配置应使用 `google/*` 模型引用，并在需要本地 Gemini CLI 执行时配合 `google-gemini-cli` 运行时。 + `google-gemini-cli/*` 模型引用是旧版兼容别名。新的配置应使用 `google/*` 模型引用，并在需要本地 Gemini CLI 执行时搭配 `google-gemini-cli` 运行时。 @@ -143,18 +135,18 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并支 | 文本转语音 | 是 | | 实时语音 | 是（Google Live API） | | 图像理解 | 是 | -| 音频转录 | 是 | +| 音频转写 | 是 | | 视频理解 | 是 | -| Web 搜索（Grounding） | 是 | -| 思考 / 推理 | 是（Gemini 2.5+ / Gemini 3+） | +| 网页搜索（Grounding） | 是 | +| 思考/推理 | 是（Gemini 2.5+ / Gemini 3+） | | Gemma 4 模型 | 是 | -Gemini 3 模型使用 `thinkingLevel`，而不是 `thinkingBudget`。OpenClaw 会将 Gemini 3、Gemini 3.1 以及 `gemini-*-latest` 别名的推理控制映射到 `thinkingLevel`，这样默认 / 低延迟运行就不会发送被禁用的 `thinkingBudget` 值。 +Gemini 3 模型使用 `thinkingLevel` 而不是 `thinkingBudget`。OpenClaw 会将 Gemini 3、Gemini 3.1 和 `gemini-*-latest` 别名的推理控制映射到 `thinkingLevel`，这样默认/低延迟运行就不会发送已禁用的 `thinkingBudget` 值。 -`/think adaptive` 会保留 Google 的动态思考语义，而不是选择一个固定的 OpenClaw 级别。Gemini 3 和 Gemini 3.1 会省略固定的 `thinkingLevel`，让 Google 自行选择级别；Gemini 2.5 则会发送 Google 的动态哨兵值 `thinkingBudget: -1`。 +`/think adaptive` 会保留 Google 的动态思考语义，而不是选择一个固定的 OpenClaw 级别。Gemini 3 和 Gemini 3.1 不会发送固定的 `thinkingLevel`，以便让 Google 自行选择级别；Gemini 2.5 会发送 Google 的动态哨兵值 `thinkingBudget: -1`。 -Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会将 `thinkingBudget` 重写为 Gemma 4 支持的 Google `thinkingLevel`。将 thinking 设置为 `off` 时，会保持禁用思考，而不会映射为 `MINIMAL`。 +Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会将 `thinkingBudget` 重写为 Gemma 4 支持的 Google `thinkingLevel`。将思考设置为 `off` 时，会保持思考禁用状态，而不会映射为 `MINIMAL`。 ## 图像生成 @@ -162,9 +154,9 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会 内置的 `google` 图像生成提供商默认使用 `google/gemini-3.1-flash-image-preview`。 -- 还支持 `google/gemini-3-pro-image-preview` -- 生成：每次请求最多 4 张图片 -- 编辑模式：已启用，最多支持 5 张输入图片 +- 也支持 `google/gemini-3-pro-image-preview` +- 生成：每次请求最多 4 张图像 +- 编辑模式：已启用，最多支持 5 张输入图像 - 几何控制：`size`、`aspectRatio` 和 `resolution` 要将 Google 用作默认图像提供商： @@ -182,16 +174,16 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会 ``` -有关共享工具参数、提供商选择和故障切换行为，请参见 [图像生成](/zh-CN/tools/image-generation)。 +有关共享工具参数、提供商选择和故障转移行为，请参阅 [Image Generation](/zh-CN/tools/image-generation)。 ## 视频生成 -内置的 `google` 插件还通过共享的 -`video_generate` 工具注册了视频生成。 +内置的 `google` 插件还会通过共享的 +`video_generate` 工具注册视频生成能力。 - 默认视频模型：`google/veo-3.1-fast-generate-preview` -- 模式：文生视频、图生视频和单视频参考流程 +- 模式：文生视频、图生视频，以及单视频参考流程 - 支持 `aspectRatio`、`resolution` 和 `audio` - 当前时长限制：**4 到 8 秒** @@ -210,20 +202,20 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会 ``` -有关共享工具参数、提供商选择和故障切换行为，请参见 [视频生成](/zh-CN/tools/video-generation)。 +有关共享工具参数、提供商选择和故障转移行为，请参阅 [Video Generation](/zh-CN/tools/video-generation)。 ## 音乐生成 -内置的 `google` 插件还通过共享的 -`music_generate` 工具注册了音乐生成。 +内置的 `google` 插件还会通过共享的 +`music_generate` 工具注册音乐生成能力。 - 默认音乐模型：`google/lyria-3-clip-preview` -- 还支持 `google/lyria-3-pro-preview` +- 也支持 `google/lyria-3-pro-preview` - 提示词控制：`lyrics` 和 `instrumental` -- 输出格式：默认 `mp3`，此外 `google/lyria-3-pro-preview` 还支持 `wav` -- 参考输入：最多 10 张图片 -- 基于会话的运行会通过共享任务 / 状态流程分离执行，包括 `action: "status"` +- 输出格式：默认 `mp3`，另外在 `google/lyria-3-pro-preview` 上支持 `wav` +- 参考输入：最多 10 张图像 +- 基于会话的运行会通过共享的任务/状态流程分离执行，包括 `action: "status"` 要将 Google 用作默认音乐提供商： @@ -240,18 +232,18 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会 ``` -有关共享工具参数、提供商选择和故障切换行为，请参见 [音乐生成](/zh-CN/tools/music-generation)。 +有关共享工具参数、提供商选择和故障转移行为，请参阅 [Music Generation](/zh-CN/tools/music-generation)。 ## 文本转语音 -内置的 `google` 语音提供商通过 -`gemini-3.1-flash-tts-preview` 使用 Gemini API TTS 路径。 +内置的 `google` 语音提供商使用 Gemini API TTS 路径，并采用 +`gemini-3.1-flash-tts-preview`。 - 默认语音：`Kore` -- 凭证：`messages.tts.providers.google.apiKey`、`models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` -- 输出：常规 TTS 附件为 WAV，Talk / 电话场景为 PCM -- 原生语音便笺输出：该 Gemini API 路径不支持，因为 API 返回的是 PCM 而不是 Opus +- 认证：`messages.tts.providers.google.apiKey`、`models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` +- 输出：常规 TTS 附件使用 WAV，Talk/电话场景使用 PCM +- 原生语音便笺输出：此 Gemini API 路径不支持，因为 API 返回的是 PCM 而不是 Opus 要将 Google 用作默认 TTS 提供商： @@ -265,6 +257,7 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会 google: { model: "gemini-3.1-flash-tts-preview", voiceName: "Kore", + audioProfile: "Speak professionally with a calm tone.", }, }, }, @@ -272,8 +265,13 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会 } ``` -Gemini API TTS 支持在文本中使用富表现力的方括号音频标签，例如 -`[whispers]` 或 `[laughs]`。如果你希望这些标签不显示在聊天回复中，但仍发送给 TTS，请将它们放在 `[[tts:text]]...[[/tts:text]]` 块内： +Gemini API TTS 使用自然语言提示来控制风格。设置 +`audioProfile` 可在朗读文本前添加一个可复用的风格提示。若你的提示文本提到了具名说话人，请设置 +`speakerName`。 + +Gemini API TTS 还接受文本中的方括号音频标签， +例如 `[whispers]` 或 `[laughs]`。如果你想在发送给 TTS 的同时不让这些标签出现在可见聊天回复中，可将它们放在 `[[tts:text]]...[[/tts:text]]` +块内： ```text Here is the clean reply text. @@ -282,25 +280,25 @@ Here is the clean reply text. ``` -一个限制为 Gemini API 的 Google Cloud Console API 密钥可用于此提供商。这不是单独的 Cloud Text-to-Speech API 路径。 +限制为 Gemini API 的 Google Cloud Console API 密钥可用于此提供商。这不是单独的 Cloud Text-to-Speech API 路径。 ## 实时语音 内置的 `google` 插件注册了一个由 -Gemini Live API 支持的实时语音提供商，适用于 Voice Call 和 Google Meet 等后端音频桥接场景。 +Gemini Live API 支持的实时语音提供商，用于 Voice Call 和 Google Meet 等后端音频桥接。 | 设置 | 配置路径 | 默认值 | | --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | | 模型 | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` | | 语音 | `...google.voice` | `Kore` | | Temperature | `...google.temperature` | （未设置） | -| VAD 开始灵敏度 | `...google.startSensitivity` | （未设置） | +| VAD 起始灵敏度 | `...google.startSensitivity` | （未设置） | | VAD 结束灵敏度 | `...google.endSensitivity` | （未设置） | | 静音时长 | `...google.silenceDurationMs` | （未设置） | | API 密钥 | `...google.apiKey` | 回退到 `models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | -示例 Voice Call 实时配置： +Voice Call 实时配置示例： ```json5 { @@ -327,23 +325,28 @@ Gemini Live API 支持的实时语音提供商，适用于 Voice Call 和 Google ``` -Google Live API 使用 WebSocket 上的双向音频和函数调用。OpenClaw 会将电话 / Meet 桥接音频适配到 Gemini 的 PCM Live API 流，并让工具调用保持在共享的实时语音契约上。除非你需要调整采样行为，否则请不要设置 `temperature`；OpenClaw 会省略非正值，因为当 `temperature: 0` 时，Google Live 可能返回只有转录文本而没有音频的结果。Gemini API 转录会在不使用 `languageCodes` 的情况下启用；当前的 Google SDK 会在此 API 路径上拒绝语言代码提示。 +Google Live API 通过 WebSocket 使用双向音频和函数调用。OpenClaw 会将电话/Meet 桥接音频适配到 Gemini 的 PCM Live API 流，并在共享的实时语音契约上保留工具调用。除非你需要调整采样，否则请将 `temperature` +保持未设置；OpenClaw 会省略非正值，因为当 `temperature: 0` 时，Google Live 可能返回只有转录而没有音频的结果。 +Gemini API 转写在不使用 `languageCodes` 的情况下启用；当前 Google +SDK 会在此 API 路径上拒绝语言代码提示。 -Control UI Talk 浏览器会话仍然需要一个具有浏览器 WebRTC 会话实现的实时语音提供商。目前该路径是 OpenAI Realtime；Google 提供商用于后端实时桥接。 +Control UI Talk 浏览器会话仍然需要一个带有浏览器 WebRTC 会话实现的实时语音提供商。目前该路径是 OpenAI Realtime；Google 提供商用于后端实时桥接。 ## 高级配置 - 对于直接 Gemini API 运行（`api: "google-generative-ai"`），OpenClaw 会将已配置的 `cachedContent` 句柄透传给 Gemini 请求。 + 对于直接 Gemini API 运行（`api: "google-generative-ai"`），OpenClaw + 会将已配置的 `cachedContent` 句柄透传给 Gemini 请求。 - - 可使用 `cachedContent` 或旧版 `cached_content` 配置按模型或全局参数 + - 使用以下任一方式按模型或全局配置参数： + `cachedContent` 或旧版 `cached_content` - 如果两者同时存在，则 `cachedContent` 优先 - 示例值：`cachedContents/prebuilt-context` - - Gemini 缓存命中用量会从上游的 `cachedContentTokenCount` 规范化为 OpenClaw 的 `cacheRead` + - Gemini 缓存命中用量会从上游 `cachedContentTokenCount` 规范化到 OpenClaw `cacheRead` ```json5 { @@ -369,14 +372,14 @@ Control UI Talk 浏览器会话仍然需要一个具有浏览器 WebRTC 会话 - 回复文本来自 CLI JSON 的 `response` 字段。 - 当 CLI 将 `usage` 留空时，用量会回退到 `stats`。 - - `stats.cached` 会被规范化为 OpenClaw 的 `cacheRead`。 + - `stats.cached` 会规范化为 OpenClaw `cacheRead`。 - 如果缺少 `stats.input`，OpenClaw 会根据 - `stats.input_tokens - stats.cached` 推导输入 token。 + `stats.input_tokens - stats.cached` 推导输入 token 数。 - - 如果 Gateway 网关作为守护进程运行（launchd / systemd），请确保 `GEMINI_API_KEY` + + 如果 Gateway 网关以守护进程方式运行（launchd/systemd），请确保 `GEMINI_API_KEY` 对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过 `env.shellEnv` 提供）。 @@ -386,7 +389,7 @@ Control UI Talk 浏览器会话仍然需要一个具有浏览器 WebRTC 会话 - 选择提供商、模型引用和故障切换行为。 + 选择提供商、模型引用和故障转移行为。 共享图像工具参数和提供商选择。 diff --git a/docs/zh-CN/tools/tts.md b/docs/zh-CN/tools/tts.md index 0734f9090..e588920b4 100644 --- a/docs/zh-CN/tools/tts.md +++ b/docs/zh-CN/tools/tts.md @@ -3,39 +3,39 @@ read_when: - 为回复启用文本转语音 - 配置 TTS 提供商或限制 - 使用 `/tts` 命令 -summary: 用于对外发出回复的文本转语音（TTS） +summary: 用于出站回复的文本转语音（TTS） title: 文本转语音 x-i18n: - generated_at: "2026-04-25T05:01:42Z" + generated_at: "2026-04-25T05:16:41Z" model: gpt-5.4 provider: openai - source_hash: 62a19b06c589aa87278464d93fa92f21c7121a5a66b336fb3eb27ae1d7f0786a + source_hash: 42faea3996a8a1e88ee09f597808b054fd86fc0935e7f5f781386d2e85da7508 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**（主要或回退提供商；也用于摘要） -- **Vydra**（主要或回退提供商；共享的图像、视频和语音提供商） +- **Vydra**（主要或回退提供商；共享图像、视频和语音提供商） - **xAI**（主要或回退提供商；使用 xAI TTS API） ### 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,32 +49,31 @@ OpenClaw 可以使用 ElevenLabs、Google Gemini、Gradium、Microsoft、MiniMax Microsoft 语音**不**需要 API 密钥。 -如果配置了多个提供商，将优先使用选定的提供商，其他提供商则作为回退选项。 -自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用了摘要，对应提供商也必须完成身份验证。 +如果配置了多个提供商，会先使用所选提供商，其他提供商作为回退选项。 +自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用了摘要，也必须为该提供商完成身份验证。 ## 服务链接 -- [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) +- [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) - [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 语音输出格式](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) +- [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) ## 默认启用吗？ -不会。自动 TTS 默认**关闭**。你可以在配置中通过 -`messages.tts.auto` 启用，或在本地通过 `/tts on` 启用。 +不是。自动 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)。 +TTS 配置位于 `openclaw.json` 中的 `messages.tts` 下。 +完整 schema 位于 [Gateway 网关配置](/zh-CN/gateway/configuration)。 ### 最小配置（启用 + 提供商） @@ -89,7 +88,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### OpenAI 作为主要提供商，ElevenLabs 作为回退 +### OpenAI 主提供商，ElevenLabs 回退 ```json5 { @@ -130,7 +129,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### Microsoft 作为主要提供商（无 API 密钥） +### Microsoft 主提供商（无 API 密钥） ```json5 { @@ -153,7 +152,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### MiniMax 作为主要提供商 +### MiniMax 主提供商 ```json5 { @@ -177,7 +176,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### Google Gemini 作为主要提供商 +### Google Gemini 主提供商 ```json5 { @@ -197,11 +196,9 @@ 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 { @@ -223,10 +220,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 { @@ -247,11 +244,10 @@ 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 { @@ -302,7 +298,7 @@ OpenRouter TTS 使用与内置 OpenRouter 模型提供商相同的 `OPENROUTER_A } ``` -### 仅在收到入站语音消息后以音频回复 +### 仅在收到入站语音消息后用音频回复 ```json5 { @@ -336,49 +332,51 @@ OpenRouter TTS 使用与内置 OpenRouter 模型提供商相同的 `OPENROUTER_A - `auto`：自动 TTS 模式（`off`、`always`、`inbound`、`tagged`）。 - `inbound` 仅在收到入站语音消息后发送音频。 - - `tagged` 仅在回复包含 `[[tts:key=value]]` 指令或 `[[tts:text]]...[[/tts:text]]` 块时发送音频。 + - `tagged` 仅在回复包含 `[[tts:key=value]]` 指令或 `[[tts:text]]...[[/tts:text]]` 区块时发送音频。 - `enabled`：旧版开关（`doctor` 会将其迁移为 `auto`）。 -- `mode`：`"final"`（默认）或 `"all"`（包含工具/分块回复）。 +- `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` - - 非默认值会被视为与 OpenAI 兼容的 TTS 端点，因此接受自定义模型名和语音名。 + - 非默认值会被视为兼容 OpenAI 的 TTS 端点，因此接受自定义模型名和语音名。 - `providers.elevenlabs.voiceSettings`： - `stability`、`similarityBoost`、`style`：`0..1` - `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.voiceName`：Gemini 预置语音名称（默认 `Kore`；也接受 `voice`）。 +- `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`。 - `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`：提供商原生速度覆盖值。 @@ -388,28 +386,27 @@ OpenRouter TTS 使用与内置 OpenRouter 模型提供商相同的 `OPENROUTER_A - `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.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 语音输出格式；并非所有格式都受内置 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.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` 时，必须使用这些指令才会触发音频。 -启用后，模型可以发出 `[[tts:...]]` 指令来覆盖单条回复所用的语音，还可以附带一个可选的 `[[tts:text]]...[[/tts:text]]` 块，用于提供表现性标签（笑声、歌唱提示等），这些内容应只出现在音频中。 +启用后，模型可以发出 `[[tts:...]]` 指令来为单条回复覆盖语音设置，还可以选择附带一个 `[[tts:text]]...[[/tts:text]]` 区块，用于提供表现性标签（笑声、歌唱提示等），这些内容只应出现在音频中。 除非设置了 `modelOverrides.allowProvider: true`，否则 `provider=...` 指令会被忽略。 -回复负载示例： +示例回复负载： ``` Here you go. @@ -421,16 +418,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 { @@ -444,7 +441,7 @@ Here you go. } ``` -可选允许列表（启用提供商切换，同时保持其他旋钮可配置）： +可选允许列表（启用提供商切换，同时保持其他参数仍可配置）： ```json5 { @@ -460,13 +457,13 @@ Here you go. } ``` -## 按用户的偏好设置 +## 每用户偏好设置 -斜杠命令会将本地覆盖项写入 `prefsPath`（默认： +斜杠命令会将本地覆盖写入 `prefsPath`（默认： `~/.openclaw/settings/tts.json`，可通过 `OPENCLAW_TTS_PREFS` 或 `messages.tts.prefsPath` 覆盖）。 -存储的字段： +已存储字段： - `enabled` - `provider` @@ -478,20 +475,20 @@ Here you go. ## 输出格式（固定） - **Feishu / Matrix / Telegram / WhatsApp**：Opus 语音消息（ElevenLabs 使用 `opus_48000_64`，OpenAI 使用 `opus`）。 - - 48 kHz / 64 kbps 是语音消息的良好折中。 + - 48 kHz / 64 kbps 是语音消息的良好折中方案。 - **其他渠道**：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`，但并非所有格式都可从该服务获得。 - - 输出格式值遵循 Microsoft 语音输出格式（包括 Ogg/WebM Opus）。 - - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保障的 Opus 语音消息，请使用 OpenAI/ElevenLabs。 - - 如果配置的 Microsoft 输出格式失败，OpenClaw 会回退并重试 MP3。 + - 内置传输支持 `outputFormat`，但并非所有格式都可由该服务提供。 + - 输出格式值遵循 Microsoft Speech 输出格式（包括 Ogg/WebM Opus）。 + - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保证的 Opus 语音消息，请使用 OpenAI/ElevenLabs。 + - 如果配置的 Microsoft 输出格式失败，OpenClaw 会重试并回退到 MP3。 -OpenAI/ElevenLabs 的输出格式按渠道固定（见上文）。 +OpenAI/ElevenLabs 的输出格式会按渠道固定（见上文）。 ## 自动 TTS 行为 @@ -499,32 +496,32 @@ OpenAI/ElevenLabs 的输出格式按渠道固定（见上文）。 - 如果回复已包含媒体或 `MEDIA:` 指令，则跳过 TTS。 - 跳过过短的回复（少于 10 个字符）。 -- 若启用，则使用 `agents.defaults.model.primary`（或 `summaryModel`）为长回复生成摘要。 +- 在启用时，使用 `agents.defaults.model.primary`（或 `summaryModel`）对长回复生成摘要。 - 将生成的音频附加到回复中。 -如果回复超过 `maxLength`，且摘要已关闭（或摘要模型没有 API 密钥），则会跳过音频，并发送普通文本回复。 +如果回复超过 `maxLength` 且摘要已关闭（或摘要模型没有 API 密钥），则会跳过音频，仅发送普通文本回复。 ## 流程图 ``` -Reply -> TTS enabled? - no -> send text - yes -> has media / MEDIA: / short? - yes -> send text - no -> length > limit? - no -> TTS -> attach audio - yes -> summary enabled? - no -> send text - yes -> summarize (summaryModel or agents.defaults.model.primary) - -> TTS -> attach audio +回复 -> 是否启用 TTS？ + 否 -> 发送文本 + 是 -> 是否有媒体 / MEDIA: / 太短？ + 是 -> 发送文本 + 否 -> 长度 > 限制？ + 否 -> TTS -> 附加音频 + 是 -> 是否启用摘要？ + 否 -> 发送文本 + 是 -> 生成摘要（summaryModel 或 agents.defaults.model.primary） + -> TTS -> 附加音频 ``` ## 斜杠命令用法 只有一个命令：`/tts`。 -有关启用详情，请参见 [Slash commands](/zh-CN/tools/slash-commands)。 +启用详情见[斜杠命令](/zh-CN/tools/slash-commands)。 -Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在那里将原生命令注册为 `/voice`。文本形式的 `/tts ...` 仍然可用。 +Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在该平台上注册 `/voice` 作为原生命令。文本形式的 `/tts ...` 仍然可用。 ``` /tts off @@ -538,23 +535,23 @@ Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在那 说明： -- 命令需要授权发送者（allowlist/所有者规则仍然适用）。 +- 命令需要经过授权的发送者（仍适用允许列表/所有者规则）。 - 必须启用 `commands.text` 或原生命令注册。 - 配置 `messages.tts.auto` 接受 `off|always|inbound|tagged`。 -- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会将其写为 `off`。 -- 如果你希望默认使用 `inbound` 或 `tagged`，请使用配置。 -- `limit` 和 `summary` 存储在本地偏好中，而不是主配置中。 -- `/tts audio` 会生成一次性音频回复（不会切换 TTS 为开启状态）。 +- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会写为 `off`。 +- 如果你想使用 `inbound` 或 `tagged` 作为默认值，请使用配置。 +- `limit` 和 `summary` 存储在本地偏好设置中，而不是主配置中。 +- `/tts audio` 会生成一次性的音频回复（不会将 TTS 切换为开启）。 - `/tts status` 包含最近一次尝试的回退可见性： - - 成功回退：`Fallback: -> ` 加上 `Attempts: ...` - - 失败：`Error: ...` 加上 `Attempts: ...` + - 成功回退：`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 时，音频会以语音消息而非文件附件的形式发送。 +它接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是按次调用的提供商请求超时时间，单位为毫秒。 ## Gateway 网关 RPC