chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
9fc8a7b7f7
commit
bec660f097
@ -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 | <channel id>（核心或插件，例如 "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 | <channel id>（核心或插件，例如 "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.<channel>.heartbeat` 会覆盖渠道默认值。
|
||||
- `channels.<channel>.accounts.<id>.heartbeat`（多账户渠道）会按每个渠道账户进行覆盖。
|
||||
- `channels.<channel>.accounts.<id>.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，请使用 `<chatId>:topic:<messageThreadId>`。
|
||||
- `accountId`：多账户渠道的可选账户 id。当 `target: "last"` 时，如果解析出的最近渠道支持账户，则应用该账户 id；否则会被忽略。如果该账户 id 与解析出的渠道中已配置账户不匹配，则跳过投递。
|
||||
- `none`（默认）：运行心跳，但**不进行**外部投递。
|
||||
- `directPolicy`：控制直接/私信投递行为：
|
||||
- `allow`（默认）：允许直接/私信心跳投递。
|
||||
- `block`：抑制直接/私信投递（`reason=dm-blocked`）。
|
||||
- `to`：可选的接收者覆盖（渠道特定 id，例如 WhatsApp 的 E.164 或 Telegram chat id）。对于 Telegram topics/threads，请使用 `<chatId>:topic:<messageThreadId>`。
|
||||
- `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:<id>:<mainKey>`），或者当 `session.scope = "global"` 时使用 `global`。设置 `session` 可覆盖为特定渠道会话（Discord/WhatsApp 等）。
|
||||
- 心跳默认在智能体的主会话中运行（`agent:<id>:<mainKey>`），如果 `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) — 自动化问题调试指南
|
||||
|
||||
@ -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/*`。
|
||||
|
||||
## 入门指南
|
||||
|
||||
选择你偏好的凭证方式，并按照设置步骤操作。
|
||||
选择你偏好的认证方式，并按照设置步骤进行操作。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="API 密钥">
|
||||
**最适合：** 通过 Google AI Studio 进行标准 Gemini API 访问。
|
||||
**最适合：** 通过 Google AI Studio 进行标准的 Gemini API 访问。
|
||||
|
||||
<Steps>
|
||||
<Step title="运行新手引导">
|
||||
@ -63,7 +55,7 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并支
|
||||
}
|
||||
```
|
||||
</Step>
|
||||
<Step title="验证模型是否可用">
|
||||
<Step title="验证模型可用">
|
||||
```bash
|
||||
openclaw models list --provider google
|
||||
```
|
||||
@ -71,16 +63,16 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并支
|
||||
</Steps>
|
||||
|
||||
<Tip>
|
||||
环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都可接受。使用你已经配置好的那个即可。
|
||||
环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都可以使用。使用你已经配置好的那个即可。
|
||||
</Tip>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Gemini CLI（OAuth）">
|
||||
**最适合：** 复用现有的 Gemini CLI 登录，通过 PKCE OAuth，而不是使用单独的 API 密钥。
|
||||
**最适合：** 复用现有的 Gemini CLI 登录，通过 PKCE OAuth 而不是单独的 API 密钥进行认证。
|
||||
|
||||
<Warning>
|
||||
`google-gemini-cli` 提供商属于非官方集成。一些用户报告称，以这种方式使用 OAuth 时会遇到账户限制。请自行承担风险。
|
||||
`google-gemini-cli` 提供商是一个非官方集成。有些用户报告称，以这种方式使用 OAuth 时会遇到账户限制。请自行承担风险。
|
||||
</Warning>
|
||||
|
||||
<Steps>
|
||||
@ -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 布局。
|
||||
</Step>
|
||||
<Step title="通过 OAuth 登录">
|
||||
```bash
|
||||
openclaw models auth login --provider google-gemini-cli --set-default
|
||||
```
|
||||
</Step>
|
||||
<Step title="验证模型是否可用">
|
||||
<Step title="验证模型可用">
|
||||
```bash
|
||||
openclaw models list --provider google
|
||||
```
|
||||
@ -125,10 +117,10 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并支
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
如果在浏览器流程开始之前登录就失败，请确保本地 `gemini` 命令已安装并且位于 `PATH` 中。
|
||||
如果在浏览器流程开始前登录就失败，请确认本地 `gemini` 命令已安装并且位于 `PATH` 中。
|
||||
</Note>
|
||||
|
||||
`google-gemini-cli/*` 模型引用是旧版兼容别名。新配置应使用 `google/*` 模型引用，并在需要本地 Gemini CLI 执行时配合 `google-gemini-cli` 运行时。
|
||||
`google-gemini-cli/*` 模型引用是旧版兼容别名。新的配置应使用 `google/*` 模型引用，并在需要本地 Gemini CLI 执行时搭配 `google-gemini-cli` 运行时。
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -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 模型 | 是 |
|
||||
|
||||
<Tip>
|
||||
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`。
|
||||
</Tip>
|
||||
|
||||
## 图像生成
|
||||
@ -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 会
|
||||
```
|
||||
|
||||
<Note>
|
||||
有关共享工具参数、提供商选择和故障切换行为，请参见 [图像生成](/zh-CN/tools/image-generation)。
|
||||
有关共享工具参数、提供商选择和故障转移行为，请参阅 [Image Generation](/zh-CN/tools/image-generation)。
|
||||
</Note>
|
||||
|
||||
## 视频生成
|
||||
|
||||
内置的 `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 会
|
||||
```
|
||||
|
||||
<Note>
|
||||
有关共享工具参数、提供商选择和故障切换行为，请参见 [视频生成](/zh-CN/tools/video-generation)。
|
||||
有关共享工具参数、提供商选择和故障转移行为，请参阅 [Video Generation](/zh-CN/tools/video-generation)。
|
||||
</Note>
|
||||
|
||||
## 音乐生成
|
||||
|
||||
内置的 `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 会
|
||||
```
|
||||
|
||||
<Note>
|
||||
有关共享工具参数、提供商选择和故障切换行为，请参见 [音乐生成](/zh-CN/tools/music-generation)。
|
||||
有关共享工具参数、提供商选择和故障转移行为，请参阅 [Music Generation](/zh-CN/tools/music-generation)。
|
||||
</Note>
|
||||
|
||||
## 文本转语音
|
||||
|
||||
内置的 `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.
|
||||
```
|
||||
|
||||
<Note>
|
||||
一个限制为 Gemini API 的 Google Cloud Console API 密钥可用于此提供商。这不是单独的 Cloud Text-to-Speech API 路径。
|
||||
限制为 Gemini API 的 Google Cloud Console API 密钥可用于此提供商。这不是单独的 Cloud Text-to-Speech API 路径。
|
||||
</Note>
|
||||
|
||||
## 实时语音
|
||||
|
||||
内置的 `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
|
||||
```
|
||||
|
||||
<Note>
|
||||
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 路径上拒绝语言代码提示。
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Control UI Talk 浏览器会话仍然需要一个具有浏览器 WebRTC 会话实现的实时语音提供商。目前该路径是 OpenAI Realtime；Google 提供商用于后端实时桥接。
|
||||
Control UI Talk 浏览器会话仍然需要一个带有浏览器 WebRTC 会话实现的实时语音提供商。目前该路径是 OpenAI Realtime；Google 提供商用于后端实时桥接。
|
||||
</Note>
|
||||
|
||||
## 高级配置
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="直接复用 Gemini 缓存">
|
||||
对于直接 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 数。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="环境和守护进程设置">
|
||||
如果 Gateway 网关作为守护进程运行（launchd / systemd），请确保 `GEMINI_API_KEY`
|
||||
<Accordion title="环境与守护进程设置">
|
||||
如果 Gateway 网关以守护进程方式运行（launchd/systemd），请确保 `GEMINI_API_KEY`
|
||||
对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过
|
||||
`env.shellEnv` 提供）。
|
||||
</Accordion>
|
||||
@ -386,7 +389,7 @@ Control UI Talk 浏览器会话仍然需要一个具有浏览器 WebRTC 会话
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
|
||||
选择提供商、模型引用和故障切换行为。
|
||||
选择提供商、模型引用和故障转移行为。
|
||||
</Card>
|
||||
<Card title="图像生成" href="/zh-CN/tools/image-generation" icon="image">
|
||||
共享图像工具参数和提供商选择。
|
||||
|
||||
@ -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>`：由提供商拥有的设置，以语音提供商 id 作为键名。
|
||||
- 旧版直接提供商块（`messages.tts.openai`、`messages.tts.elevenlabs`、`messages.tts.microsoft`、`messages.tts.edge`）可通过 `openclaw doctor --fix` 修复；提交的配置应使用 `messages.tts.providers.<id>`。
|
||||
- 旧版 `messages.tts.providers.edge` 也可通过 `openclaw doctor --fix` 修复；提交的配置应使用 `messages.tts.providers.microsoft`。
|
||||
- `maxTextLength`：TTS 输入的硬性上限（字符数）。超出时，`/tts audio` 会失败。
|
||||
- `timeoutMs`：请求超时时间（毫秒）。
|
||||
- `allowProvider` 默认为 `false`（提供商切换需显式选择启用）。
|
||||
- `providers.<id>`：由提供商拥有的设置，以语音提供商 id 为键。
|
||||
- 旧版直接提供商区块（`messages.tts.openai`、`messages.tts.elevenlabs`、`messages.tts.microsoft`、`messages.tts.edge`）可通过 `openclaw doctor --fix` 修复；已提交的配置应使用 `messages.tts.providers.<id>`。
|
||||
- 旧版 `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: <primary> -> <used>` 加上 `Attempts: ...`
|
||||
- 失败：`Error: ...` 加上 `Attempts: ...`
|
||||
- 成功回退：`Fallback: <primary> -> <used>` 加 `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
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user