From 447c42ddd74e55623d3b98593691c2fdbd01207a Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sun, 26 Apr 2026 02:34:28 +0000 Subject: [PATCH] chore(i18n): refresh zh-CN translations --- docs/zh-CN/channels/whatsapp.md | 249 +++++++++++++------------ docs/zh-CN/tools/tts.md | 309 +++++++++++++++++--------------- 2 files changed, 286 insertions(+), 272 deletions(-) diff --git a/docs/zh-CN/channels/whatsapp.md b/docs/zh-CN/channels/whatsapp.md index ceb5454a6..10246ae87 100644 --- a/docs/zh-CN/channels/whatsapp.md +++ b/docs/zh-CN/channels/whatsapp.md @@ -1,29 +1,28 @@ --- read_when: - - 处理 WhatsApp/web 渠道行为或收件箱路由 + - 处理 WhatsApp / web 渠道行为或收件箱路由 summary: WhatsApp 渠道支持、访问控制、投递行为和运维 title: WhatsApp x-i18n: - generated_at: "2026-04-25T18:12:19Z" + generated_at: "2026-04-26T02:32:11Z" model: gpt-5.4 provider: openai - source_hash: 0935e7ac3676c57d83173a6dd9eedc489f77b278dfbc47bd811045078ee7e4d0 + source_hash: 0e06f394be0e779a65fb1e17b3d4e5d8443c89c93596f4c012bab145dc4904dd source_path: channels/whatsapp.md workflow: 15 --- -Status：通过 WhatsApp Web（Baileys）达到生产就绪。Gateway 网关拥有已关联的会话。 +Status：通过 WhatsApp Web（Baileys）达到生产就绪。Gateway 网关负责已关联的会话。 ## 安装（按需） - 新手引导（`openclaw onboard`）和 `openclaw channels add --channel whatsapp` - 会在你首次选择该插件时提示安装 WhatsApp 插件。 -- `openclaw channels login --channel whatsapp` 也会在 - 插件尚未安装时提供安装流程。 -- 开发渠道 + git 检出：默认使用本地插件路径。 + 会在你第一次选择时提示安装 WhatsApp 插件。 +- 当插件尚未安装时，`openclaw channels login --channel whatsapp` 也会提供安装流程。 +- 开发渠道 + git checkout：默认使用本地插件路径。 - Stable/Beta：默认使用 npm 包 `@openclaw/whatsapp`。 -仍然支持手动安装： +仍然可以手动安装： ```bash openclaw plugins install @openclaw/whatsapp @@ -31,10 +30,10 @@ openclaw plugins install @openclaw/whatsapp - 对于未知发件人，默认私信策略是配对。 + 未知发送者的默认私信策略为配对。 - 跨渠道诊断和修复操作手册。 + 跨渠道诊断与修复操作手册。 完整的渠道配置模式和示例。 @@ -61,7 +60,7 @@ openclaw plugins install @openclaw/whatsapp - + ```bash openclaw channels login --channel whatsapp @@ -73,7 +72,7 @@ openclaw channels login --channel whatsapp openclaw channels login --channel whatsapp --account work ``` - 要在登录前附加现有/自定义的 WhatsApp Web 认证目录： + 如需在登录前附加现有/自定义的 WhatsApp Web 认证目录： ```bash openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth @@ -82,7 +81,7 @@ openclaw channels login --channel whatsapp --account work - + ```bash openclaw gateway @@ -103,7 +102,7 @@ openclaw pairing approve whatsapp -OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据和设置流程已针对该方案优化，但也支持个人号码方案。） +OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据和设置流程已针对这种配置进行了优化，但也支持个人号码配置。） ## 部署模式 @@ -113,7 +112,7 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 这是最清晰的运维模式： - 为 OpenClaw 使用单独的 WhatsApp 身份 - - 更清晰的私信允许列表和路由边界 + - 更清晰的私信 allowlist 和路由边界 - 更低的自聊混淆概率 最小策略模式： @@ -132,13 +131,13 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 - 新手引导支持个人号码模式，并会写入适合自聊的基础配置： + 新手引导支持个人号码模式，并会写入适合自聊的基线配置： - `dmPolicy: "allowlist"` - `allowFrom` 包含你的个人号码 - `selfChatMode: true` - 在运行时，自聊保护机制会根据已关联的自身号码和 `allowFrom` 生效。 + 在运行时，自聊保护会根据已关联的自身号码和 `allowFrom` 生效。 @@ -152,19 +151,19 @@ OpenClaw 建议尽可能为 WhatsApp 使用单独的号码。（渠道元数据 ## 运行时模型 -- Gateway 网关拥有 WhatsApp socket 和重连循环。 -- 出站发送要求目标账户存在活动的 WhatsApp 监听器。 -- Status 和广播聊天会被忽略（`@status`、`@broadcast`）。 -- 直接聊天使用私信会话规则（`session.dmScope`；默认 `main` 会将私信折叠到智能体主会话）。 -- 群组会话是隔离的（`agent::whatsapp:group:`）。 -- WhatsApp Web 传输遵循 Gateway 网关主机上的标准代理环境变量（`HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` 及其小写变体）。优先使用主机级代理配置，而不是渠道专用的 WhatsApp 代理设置。 +- Gateway 网关负责 WhatsApp socket 和重连循环。 +- 出站发送要求目标账户具有活动中的 WhatsApp 监听器。 +- Status 和 broadcast 聊天会被忽略（`@status`、`@broadcast`）。 +- 私聊使用私信会话规则（`session.dmScope`；默认 `main` 会将私信折叠到智能体主会话）。 +- 群组会话相互隔离（`agent::whatsapp:group:`）。 +- WhatsApp Web 传输遵循 Gateway 网关主机上的标准代理环境变量（`HTTPS_PROXY`、`HTTP_PROXY`、`NO_PROXY` 及其小写变体）。优先使用主机级代理配置，而不是 WhatsApp 渠道专用代理设置。 ## 插件钩子与隐私 WhatsApp 入站消息可能包含个人消息内容、电话号码、 -群组标识符、发送者名称和会话关联字段。因此， -除非你明确选择启用，否则 WhatsApp 不会将入站 `message_received` -hook 负载广播给插件： +群组标识符、发送者名称以及会话关联字段。因此， +除非你显式选择加入，否则 WhatsApp 不会向插件广播入站 +`message_received` hook 载荷： ```json5 { @@ -178,7 +177,7 @@ hook 负载广播给插件： } ``` -你可以将启用范围限定到单个账户： +你也可以将此选择加入限定到某一个账户： ```json5 { @@ -196,92 +195,91 @@ hook 负载广播给插件： } ``` -仅当你信任相关插件接收入站 WhatsApp 消息内容和标识符时， -才启用此选项。 +仅在你信任插件可以接收入站 WhatsApp 消息内容和标识符时，才启用此功能。 ## 访问控制与激活 - `channels.whatsapp.dmPolicy` 控制直接聊天访问： + `channels.whatsapp.dmPolicy` 控制私聊访问： - `pairing`（默认） - `allowlist` - `open`（要求 `allowFrom` 包含 `"*"`） - `disabled` - `allowFrom` 接受 E.164 风格号码（内部会标准化）。 + `allowFrom` 接受 E.164 风格的号码（内部会规范化）。 - 多账户覆盖：`channels.whatsapp.accounts..dmPolicy`（以及 `allowFrom`）对该账户优先于渠道级默认值。 + 多账户覆盖：对于该账户，`channels.whatsapp.accounts..dmPolicy`（以及 `allowFrom`）优先于渠道级默认值。 运行时行为细节： - - 配对关系会持久化到渠道允许存储中，并与已配置的 `allowFrom` 合并 - - 如果未配置允许列表，则默认允许已关联的自身号码 - - OpenClaw 永远不会自动配对出站 `fromMe` 私信（即你从已关联设备发送给自己的消息） + - 配对会持久化到渠道 allow-store 中，并与已配置的 `allowFrom` 合并 + - 如果未配置任何 allowlist，则默认允许已关联的自身号码 + - OpenClaw 绝不会自动配对出站 `fromMe` 私信（即你从已关联设备发送给自己的消息） - + 群组访问有两层： - 1. **群组成员允许列表**（`channels.whatsapp.groups`） + 1. **群组成员资格 allowlist**（`channels.whatsapp.groups`） - 如果省略 `groups`，则所有群组都有资格 - - 如果存在 `groups`，它会作为群组允许列表（允许使用 `"*"`） + - 如果存在 `groups`，它会作为群组 allowlist（允许 `"*"`） 2. **群组发送者策略**（`channels.whatsapp.groupPolicy` + `groupAllowFrom`） - - `open`：绕过发送者允许列表 + - `open`：绕过发送者 allowlist - `allowlist`：发送者必须匹配 `groupAllowFrom`（或 `*`） - `disabled`：阻止所有群组入站消息 - 发送者允许列表回退： + 发送者 allowlist 回退： - 如果未设置 `groupAllowFrom`，运行时会在可用时回退到 `allowFrom` - - 发送者允许列表会在提及/回复激活之前进行评估 + - 发送者 allowlist 会在提及/回复激活之前进行评估 - 注意：如果完全不存在 `channels.whatsapp` 配置块，运行时群组策略回退值为 `allowlist`（并记录警告日志），即使设置了 `channels.defaults.groupPolicy` 也是如此。 + 注意：如果根本不存在 `channels.whatsapp` 配置块，则运行时的群组策略回退为 `allowlist`（并带有警告日志），即使设置了 `channels.defaults.groupPolicy` 也是如此。 - 默认情况下，群组回复需要被提及。 + 群组回复默认需要被提及。 提及检测包括： - 对机器人身份的显式 WhatsApp 提及 - - 已配置的提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`） - - 隐式回复机器人检测（回复的发送者匹配机器人身份） + - 已配置的提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`） + - 隐式回复机器人检测（回复发送者与机器人身份匹配） 安全说明： - - 引用/回复只能满足提及门控；它**不会**授予发送者授权 - - 在 `groupPolicy: "allowlist"` 下，即使非允许列表发送者回复了允许列表用户的消息，仍会被阻止 + - 引用/回复只满足提及门控；它**不会**授予发送者授权 + - 使用 `groupPolicy: "allowlist"` 时，即使非 allowlist 发送者回复了 allowlist 用户的消息，也仍会被阻止 会话级激活命令： - `/activation mention` - `/activation always` - `activation` 会更新会话状态（而非全局配置）。它受 owner 权限控制。 + `activation` 会更新会话状态（不是全局配置）。它受 owner 权限控制。 ## 个人号码与自聊行为 -当已关联的自身号码也存在于 `allowFrom` 中时，WhatsApp 自聊保护会启用： +当已关联的自身号码也出现在 `allowFrom` 中时，会启用 WhatsApp 自聊保护： - 跳过自聊轮次的已读回执 -- 忽略原本会触发提醒自己的 mention-JID 自动触发行为 +- 忽略原本会提醒你自己的 mention-JID 自动触发行为 - 如果未设置 `messages.responsePrefix`，自聊回复默认使用 `[{identity.name}]` 或 `[openclaw]` -## 消息标准化与上下文 +## 消息规范化与上下文 传入的 WhatsApp 消息会被包装进共享的入站信封中。 - 如果存在引用回复，会按以下形式附加上下文： + 如果存在引用回复，上下文会按以下形式附加： ```text [Replying to id:] @@ -289,12 +287,12 @@ hook 负载广播给插件： [/Replying] ``` - 可用时也会填充回复元数据字段（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、发送者 JID/E.164）。 + 在可用时，也会填充回复元数据字段（`ReplyToId`、`ReplyToBody`、`ReplyToSender`、发送者 JID/E.164）。 - - 仅媒体的入站消息会使用如下占位符进行标准化： + + 仅含媒体的入站消息会使用如下占位符进行规范化： - `` - `` @@ -302,14 +300,14 @@ hook 负载广播给插件： - `` - `` - 位置消息正文使用简洁的坐标文本。位置标签/注释以及联系人/vCard 详情会呈现为带围栏的不可信元数据，而不是内联提示文本。 + 位置正文使用简洁的坐标文本。位置标签/备注以及联系人/vCard 详情会渲染为带围栏的不可信元数据，而不是内联提示文本。 - 对于群组，未处理消息可以被缓冲，并在机器人最终被触发时作为上下文注入。 + 对于群组，当机器人最终被触发时，未处理的消息可以被缓冲并作为上下文注入。 - - 默认上限：`50` + - 默认限制：`50` - 配置：`channels.whatsapp.historyLimit` - 回退：`messages.groupChat.historyLimit` - `0` 表示禁用 @@ -322,7 +320,7 @@ hook 负载广播给插件： - 默认情况下，已接受的入站 WhatsApp 消息会启用已读回执。 + 默认会为已接受的入站 WhatsApp 消息启用已读回执。 全局禁用： @@ -357,7 +355,7 @@ hook 负载广播给插件： -## 投递、分块和媒体 +## 投递、分块与媒体 @@ -367,27 +365,28 @@ hook 负载广播给插件： - - 支持图片、视频、音频（PTT 语音便笺）和文档负载 - - 回复负载会保留 `audioAsVoice`；WhatsApp 会将音频媒体作为 Baileys PTT 语音便笺发送 - - 非 Ogg 音频（包括 Microsoft Edge TTS MP3/WebM 输出）在作为 PTT 投递前会被转码为 Ogg/Opus + - 支持图片、视频、音频（PTT 语音便笺）和文档载荷 + - 音频媒体通过 Baileys 的 `audio` 载荷并设置 `ptt: true` 发送，因此 WhatsApp 客户端会将其渲染为按住说话语音便笺 + - 回复载荷会保留 `audioAsVoice`；即使提供商返回 MP3 或 WebM，WhatsApp 的 TTS 语音便笺输出也会继续走此 PTT 路径 - 原生 Ogg/Opus 音频会以 `audio/ogg; codecs=opus` 发送，以兼容语音便笺 - - 通过在视频发送时设置 `gifPlayback: true`，支持动画 GIF 播放 - - 发送多媒体回复负载时，说明文字会应用到第一项媒体；但 PTT 语音便笺会先发送音频，再单独发送可见文本，因为 WhatsApp 客户端对语音便笺说明文字的渲染并不一致 - - 媒体源可以是 HTTP(S)、`file://` 或本地路径 + - 非 Ogg 音频（包括 Microsoft Edge TTS 的 MP3/WebM 输出）会在 PTT 投递前通过 `ffmpeg` 转码为 48 kHz 单声道 Ogg/Opus + - 发送视频时通过 `gifPlayback: true` 支持动画 GIF 播放 + - 发送多媒体回复载荷时，说明文字会应用到第一项媒体；但 PTT 语音便笺会先发送音频，再单独发送可见文本，因为 WhatsApp 客户端对语音便笺说明文字的渲染并不一致 + - 媒体来源可以是 HTTP(S)、`file://` 或本地路径 - + - 入站媒体保存上限：`channels.whatsapp.mediaMaxMb`（默认 `50`） - 出站媒体发送上限：`channels.whatsapp.mediaMaxMb`（默认 `50`） - 按账户覆盖使用 `channels.whatsapp.accounts..mediaMaxMb` - - 图片会自动优化（尺寸/质量扫描）以适应限制 + - 图片会自动优化（调整尺寸/质量扫描）以适配限制 - 媒体发送失败时，首项回退会发送文本警告，而不是静默丢弃响应 ## 回复引用 -WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消息。使用 `channels.whatsapp.replyToMode` 进行控制。 +WhatsApp 支持原生回复引用，出站回复会可见地引用入站消息。使用 `channels.whatsapp.replyToMode` 进行控制。 | 值 | 行为 | | ----------- | --------------------------------------------------------------------- | @@ -396,7 +395,7 @@ WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消 | `"all"` | 引用每一段出站回复分块 | | `"batched"` | 引用排队的批量回复，同时让即时回复不带引用 | -默认值是 `"off"`。按账户覆盖使用 `channels.whatsapp.accounts..replyToMode`。 +默认值为 `"off"`。按账户覆盖使用 `channels.whatsapp.accounts..replyToMode`。 ```json5 { @@ -408,16 +407,16 @@ WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消 } ``` -## 反应级别 +## Reaction 级别 -`channels.whatsapp.reactionLevel` 控制智能体在 WhatsApp 上使用 emoji 反应的广泛程度： +`channels.whatsapp.reactionLevel` 控制智能体在 WhatsApp 上使用 emoji reaction 的广泛程度： -| 级别 | 确认反应 | 智能体主动反应 | 说明 | +| 级别 | 确认 reaction | 智能体主动 reaction | 说明 | | ------------- | ------------- | ------------------------- | ------------------------------------------------ | -| `"off"` | 否 | 否 | 完全不使用反应 | -| `"ack"` | 是 | 否 | 仅确认反应（回复前回执） | -| `"minimal"` | 是 | 是（保守） | 确认反应 + 带保守引导的智能体反应 | -| `"extensive"` | 是 | 是（鼓励） | 确认反应 + 带鼓励性引导的智能体反应 | +| `"off"` | 否 | 否 | 完全不使用 reaction | +| `"ack"` | 是 | 否 | 仅确认 reaction（回复前确认收到） | +| `"minimal"` | 是 | 是（保守） | 确认 + 智能体 reaction，并采用保守指导 | +| `"extensive"` | 是 | 是（鼓励） | 确认 + 智能体 reaction，并采用鼓励式指导 | 默认值：`"minimal"`。 @@ -433,10 +432,10 @@ WhatsApp 支持原生回复引用，即出站回复会可见地引用入站消 } ``` -## 确认反应 +## 确认 reaction -WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时立即发送确认反应。 -确认反应受 `reactionLevel` 控制——当 `reactionLevel` 为 `"off"` 时会被抑制。 +WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时立即发送确认 reaction。 +确认 reaction 受 `reactionLevel` 控制 —— 当 `reactionLevel` 为 `"off"` 时会被抑制。 ```json5 { @@ -454,21 +453,21 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时 行为说明： -- 在入站消息被接受后立即发送（回复前） -- 失败会被记录日志，但不会阻塞正常回复投递 -- 群组模式 `mentions` 会在由提及触发的轮次发送反应；群组激活 `always` 会绕过此检查 +- 在接受入站消息后立即发送（回复前） +- 失败会记录日志，但不会阻塞正常回复投递 +- 群组模式 `mentions` 会在由提及触发的轮次发送 reaction；群组激活 `always` 会绕过此检查 - WhatsApp 使用 `channels.whatsapp.ackReaction`（此处不使用旧版 `messages.ackReaction`） ## 多账户与凭证 - + - 账户 id 来自 `channels.whatsapp.accounts` - - 默认账户选择：如果存在 `default` 则使用它，否则使用第一个已配置的账户 id（已排序） - - 账户 id 会在内部标准化以便查找 + - 默认账户选择：如果存在则为 `default`，否则为第一个已配置的账户 id（已排序） + - 账户 id 会在内部规范化后用于查找 - + - 当前认证路径：`~/.openclaw/credentials/whatsapp//creds.json` - 备份文件：`creds.json.bak` - `~/.openclaw/credentials/` 中的旧版默认认证仍会被识别/迁移，用于默认账户流程 @@ -477,26 +476,26 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时 `openclaw channels logout --channel whatsapp [--account ]` 会清除该账户的 WhatsApp 认证状态。 - 在旧版认证目录中，会保留 `oauth.json`，同时移除 Baileys 认证文件。 + 在旧版认证目录中，会保留 `oauth.json`，同时删除 Baileys 认证文件。 -## 工具、操作和配置写入 +## 工具、动作与配置写入 -- 智能体工具支持包括 WhatsApp 反应操作（`react`）。 -- 操作开关： +- 智能体工具支持包括 WhatsApp reaction 动作（`react`）。 +- 动作门控： - `channels.whatsapp.actions.reactions` - `channels.whatsapp.actions.polls` -- 默认启用渠道发起的配置写入（可通过 `channels.whatsapp.configWrites=false` 禁用）。 +- 默认启用由渠道发起的配置写入（可通过 `channels.whatsapp.configWrites=false` 禁用）。 ## 故障排除 - + 症状：渠道状态显示未关联。 - 修复方法： + 修复： ```bash openclaw channels login --channel whatsapp @@ -506,70 +505,70 @@ WhatsApp 支持通过 `channels.whatsapp.ackReaction` 在收到入站消息时 - 症状：账户已关联，但反复断开或尝试重连。 + 症状：已关联账户反复断开或重复尝试重连。 - 修复方法： + 修复： ```bash openclaw doctor openclaw logs --follow ``` - 如有需要，使用 `channels login` 重新关联。 + 如有需要，可使用 `channels login` 重新关联。 - 当目标账户不存在活动的 Gateway 网关监听器时，出站发送会快速失败。 + 当目标账户不存在活动中的 Gateway 网关监听器时，出站发送会快速失败。 请确保 Gateway 网关正在运行，并且该账户已关联。 - - 按以下顺序检查： + + 请按以下顺序检查： - `groupPolicy` - `groupAllowFrom` / `allowFrom` - - `groups` 允许列表条目 + - `groups` allowlist 条目 - 提及门控（`requireMention` + 提及模式） - `openclaw.json`（JSON5）中的重复键：后面的条目会覆盖前面的条目，因此每个作用域只保留一个 `groupPolicy` - WhatsApp Gateway 网关运行时应使用 Node。Bun 被标记为不适合稳定的 WhatsApp/Telegram Gateway 网关运行。 + WhatsApp Gateway 网关运行时应使用 Node。Bun 被标记为不兼容稳定的 WhatsApp / Telegram Gateway 网关运行。 ## 系统提示词 -WhatsApp 通过 `groups` 和 `direct` 映射支持类似 Telegram 的群组和直接聊天系统提示词。 +WhatsApp 通过 `groups` 和 `direct` 映射支持类似 Telegram 的群组和私聊系统提示词。 群组消息的解析层级： -首先确定生效的 `groups` 映射：如果账户定义了自己的 `groups`，它会完全替换根级 `groups` 映射（不进行深度合并）。然后在生成的单一映射上执行提示词查找： +首先确定生效的 `groups` 映射：如果账户定义了自己的 `groups`，它会完全替换根级 `groups` 映射（不进行深度合并）。随后提示词查找会在得到的这个单一映射上进行： -1. **群组专用系统提示词**（`groups[""].systemPrompt`）：当映射中存在该特定群组条目，**并且**其定义了 `systemPrompt` 键时使用。如果 `systemPrompt` 是空字符串（`""`），则会抑制通配符，不应用任何系统提示词。 +1. **群组专用系统提示词**（`groups[""].systemPrompt`）：当映射中存在该特定群组条目，**且**其定义了 `systemPrompt` 键时使用。如果 `systemPrompt` 是空字符串（`""`），则会抑制通配符，并且不应用任何系统提示词。 2. **群组通配符系统提示词**（`groups["*"].systemPrompt`）：当映射中完全不存在该特定群组条目，或者该条目存在但未定义 `systemPrompt` 键时使用。 -直接消息的解析层级： +私聊消息的解析层级： -首先确定生效的 `direct` 映射：如果账户定义了自己的 `direct`，它会完全替换根级 `direct` 映射（不进行深度合并）。然后在生成的单一映射上执行提示词查找： +首先确定生效的 `direct` 映射：如果账户定义了自己的 `direct`，它会完全替换根级 `direct` 映射（不进行深度合并）。随后提示词查找会在得到的这个单一映射上进行： -1. **直接聊天专用系统提示词**（`direct[""].systemPrompt`）：当映射中存在该特定对端条目，**并且**其定义了 `systemPrompt` 键时使用。如果 `systemPrompt` 是空字符串（`""`），则会抑制通配符，不应用任何系统提示词。 -2. **直接聊天通配符系统提示词**（`direct["*"].systemPrompt`）：当映射中完全不存在该特定对端条目，或者该条目存在但未定义 `systemPrompt` 键时使用。 +1. **私聊专用系统提示词**（`direct[""].systemPrompt`）：当映射中存在该特定对端条目，**且**其定义了 `systemPrompt` 键时使用。如果 `systemPrompt` 是空字符串（`""`），则会抑制通配符，并且不应用任何系统提示词。 +2. **私聊通配符系统提示词**（`direct["*"].systemPrompt`）：当映射中完全不存在该特定对端条目，或者该条目存在但未定义 `systemPrompt` 键时使用。 注意：`dms` 仍然是轻量级的按私信历史覆盖桶（`dms..historyLimit`）；提示词覆盖位于 `direct` 下。 -**与 Telegram 多账户行为的区别：** 在 Telegram 中，在多账户设置下，根级 `groups` 会被有意抑制——即使某些账户没有定义自己的 `groups` 也是如此——以防止机器人接收其并不属于的群组消息。WhatsApp 不应用这一保护：无论配置了多少账户，凡是未定义账户级覆盖的账户，都会继承根级 `groups` 和根级 `direct`。在多账户 WhatsApp 设置中，如果你希望为每个账户设置群组或直接聊天提示词，应在每个账户下显式定义完整映射，而不是依赖根级默认值。 +**与 Telegram 多账户行为的区别：** 在 Telegram 中，在多账户设置下，根级 `groups` 会被有意地对所有账户抑制——即使某些账户根本没有定义自己的 `groups` 也是如此——以防止机器人接收其并未加入的群组消息。WhatsApp 不应用这一保护：对于未定义账户级覆盖的账户，无论配置了多少个账户，都会始终继承根级 `groups` 和根级 `direct`。在多账户 WhatsApp 设置中，如果你希望按账户设置群组或私聊提示词，请在每个账户下显式定义完整映射，而不要依赖根级默认值。 重要行为： -- `channels.whatsapp.groups` 既是按群组划分的配置映射，也是聊天级群组允许列表。在根级或账户级作用域下，`groups["*"]` 都表示“该作用域下允许所有群组”。 -- 只有当你本来就希望该作用域允许所有群组时，才添加通配符群组 `systemPrompt`。如果你仍然只希望固定的一组群组 id 有资格使用，请不要将 `groups["*"]` 用作提示词默认值。应改为在每个显式列入允许列表的群组条目上重复设置该提示词。 -- 群组准入和发送者授权是分开的检查。`groups["*"]` 会扩大可以进入群组处理的群组集合，但它本身不会授权这些群组中的所有发送者。发送者访问仍然由 `channels.whatsapp.groupPolicy` 和 `channels.whatsapp.groupAllowFrom` 单独控制。 -- `channels.whatsapp.direct` 对私信没有相同的副作用。`direct["*"]` 只会在私信已经通过 `dmPolicy` 加上 `allowFrom` 或配对存储规则获准后，提供默认的直接聊天配置。 +- `channels.whatsapp.groups` 既是按群组配置映射，也是聊天级群组 allowlist。在根级或账户作用域下，`groups["*"]` 都表示“该作用域下允许所有群组进入”。 +- 只有当你本来就希望该作用域允许所有群组进入时，才添加通配符群组 `systemPrompt`。如果你仍然只希望固定的一组群组 id 有资格进入，请不要将 `groups["*"]` 用作提示词默认值。相反，请在每个显式加入 allowlist 的群组条目中重复该提示词。 +- 群组准入和发送者授权是分开的检查。`groups["*"]` 会扩大可以进入群组处理的群组集合，但它本身不会授权这些群组中的每个发送者。发送者访问仍然由 `channels.whatsapp.groupPolicy` 和 `channels.whatsapp.groupAllowFrom` 单独控制。 +- `channels.whatsapp.direct` 对私信没有相同的副作用。`direct["*"]` 仅在私信已经通过 `dmPolicy` 加上 `allowFrom` 或配对存储规则获准后，提供默认私聊配置。 示例： @@ -578,31 +577,31 @@ WhatsApp 通过 `groups` 和 `direct` 映射支持类似 Telegram 的群组和 channels: { whatsapp: { groups: { - // 仅当根级作用域下应允许所有群组时使用。 + // 仅当根级作用域应允许所有群组进入时使用。 // 适用于所有未定义自己 groups 映射的账户。 "*": { systemPrompt: "所有群组的默认提示词。" }, }, direct: { // 适用于所有未定义自己 direct 映射的账户。 - "*": { systemPrompt: "所有直接聊天的默认提示词。" }, + "*": { systemPrompt: "所有私聊的默认提示词。" }, }, accounts: { work: { groups: { - // 此账户定义了自己的 groups，因此根级 groups 会被完全 - // 替换。若要保留通配符，也需要在此处显式定义 "*"。 + // 该账户定义了自己的 groups，因此根级 groups 会被完全 + // 替换。若要保留通配符，也需要在这里显式定义 "*"。 "120363406415684625@g.us": { requireMention: false, - systemPrompt: "专注于项目管理。", + systemPrompt: "聚焦项目管理。", }, - // 仅当此账户下应允许所有群组时使用。 + // 仅当该账户中应允许所有群组进入时使用。 "*": { systemPrompt: "工作群组的默认提示词。" }, }, direct: { - // 此账户定义了自己的 direct 映射，因此根级 direct 条目会被 - // 完全替换。若要保留通配符，也需要在此处显式定义 "*"。 - "+15551234567": { systemPrompt: "特定工作直接聊天的提示词。" }, - "*": { systemPrompt: "工作直接聊天的默认提示词。" }, + // 该账户定义了自己的 direct 映射，因此根级 direct 条目会被 + // 完全替换。若要保留通配符，也需要在这里显式定义 "*"。 + "+15551234567": { systemPrompt: "特定工作私聊的提示词。" }, + "*": { systemPrompt: "工作私聊的默认提示词。" }, }, }, }, diff --git a/docs/zh-CN/tools/tts.md b/docs/zh-CN/tools/tts.md index eac974c52..12e3fea2c 100644 --- a/docs/zh-CN/tools/tts.md +++ b/docs/zh-CN/tools/tts.md @@ -3,72 +3,72 @@ read_when: - 为回复启用文本转语音 - 配置 TTS 提供商或限制 - 使用 `/tts` 命令 -summary: 用于发送回复的文本转语音（TTS） +summary: 用于外发回复的文本转语音（TTS） title: 文本转语音 x-i18n: - generated_at: "2026-04-26T02:22:23Z" + generated_at: "2026-04-26T02:32:12Z" model: gpt-5.4 provider: openai - source_hash: 38925c9b27808e36dde4016a0fc983be9ce50657ad2b571e987d2e850613771f + source_hash: 710036289a2dc35d70c8c51aecd696e5c90a56903a588c3aaf8e88f40c2851d1 source_path: tools/tts.md workflow: 15 --- -OpenClaw 可以使用 Azure Speech、ElevenLabs、Google Gemini、Gradium、Inworld、Local CLI、Microsoft、MiniMax、OpenAI、Volcengine、Vydra、xAI 或 Xiaomi MiMo 将发出的回复转换为音频。 -它适用于 OpenClaw 可以发送音频的任何地方。 +OpenClaw 可以使用 Azure Speech、ElevenLabs、Google Gemini、Gradium、Inworld、Local CLI、Microsoft、MiniMax、OpenAI、Volcengine、Vydra、xAI 或 Xiaomi MiMo 将外发回复转换为音频。 +它适用于 OpenClaw 可以发送音频的任何场景。 ## 支持的服务 -- **Azure Speech**（主提供商或后备提供商；使用 Azure AI Speech REST API） -- **ElevenLabs**（主提供商或后备提供商） -- **Google Gemini**（主提供商或后备提供商；使用 Gemini API TTS） -- **Gradium**（主提供商或后备提供商；支持语音便笺和电话语音输出） -- **Inworld**（主提供商或后备提供商；使用 Inworld 流式 TTS API） -- **Local CLI**（主提供商或后备提供商；运行已配置的本地 TTS 命令） -- **Microsoft**（主提供商或后备提供商；当前内置实现使用 `node-edge-tts`） -- **MiniMax**（主提供商或后备提供商；使用 T2A v2 API） -- **OpenAI**（主提供商或后备提供商；也用于摘要） -- **Volcengine**（主提供商或后备提供商；使用 BytePlus Seed Speech HTTP API） -- **Vydra**（主提供商或后备提供商；共享图像、视频和语音提供商） -- **xAI**（主提供商或后备提供商；使用 xAI TTS API） -- **Xiaomi MiMo**（主提供商或后备提供商；通过 Xiaomi chat completions 使用 MiMo TTS） +- **Azure Speech**（主提供商或回退提供商；使用 Azure AI Speech REST API） +- **ElevenLabs**（主提供商或回退提供商） +- **Google Gemini**（主提供商或回退提供商；使用 Gemini API TTS） +- **Gradium**（主提供商或回退提供商；支持语音便笺和电话输出） +- **Inworld**（主提供商或回退提供商；使用 Inworld 流式 TTS API） +- **Local CLI**（主提供商或回退提供商；运行已配置的本地 TTS 命令） +- **Microsoft**（主提供商或回退提供商；当前内置实现使用 `node-edge-tts`） +- **MiniMax**（主提供商或回退提供商；使用 T2A v2 API） +- **OpenAI**（主提供商或回退提供商；也用于摘要） +- **Volcengine**（主提供商或回退提供商；使用 BytePlus Seed Speech HTTP API） +- **Vydra**（主提供商或回退提供商；共享图像、视频和语音提供商） +- **xAI**（主提供商或回退提供商；使用 xAI TTS API） +- **Xiaomi MiMo**（主提供商或回退提供商；通过 Xiaomi chat completions 使用 MiMo TTS） ### Microsoft 语音说明 -内置的 Microsoft 语音提供商当前通过 `node-edge-tts` 库，使用 Microsoft Edge 的在线神经网络 TTS 服务。它是托管服务（不是本地服务），使用 Microsoft 的端点，并且不需要 API 密钥。 +内置的 Microsoft 语音提供商当前通过 `node-edge-tts` 库使用 Microsoft Edge 的在线神经网络 TTS 服务。它是托管服务（不是本地服务），使用 Microsoft 的端点，并且不需要 API 密钥。 `node-edge-tts` 提供语音配置选项和输出格式，但并非所有选项都受该服务支持。使用 `edge` 的旧版配置和指令输入仍然有效，并会被规范化为 `microsoft`。 -由于这一路径是公共 Web 服务，没有公开发布的 SLA 或配额，请将其视为“尽力而为”的服务。如果你需要有保障的限制和支持，请使用 OpenAI 或 ElevenLabs。 +由于这一路径是没有公开 SLA 或配额说明的公共 Web 服务，应将其视为尽力而为。如果你需要有保障的限制和支持，请使用 OpenAI 或 ElevenLabs。 -## 可选密钥 +## 可选键 如果你想使用 Azure Speech、ElevenLabs、Google Gemini、Gradium、Inworld、MiniMax、OpenAI、Volcengine、Vydra、xAI 或 Xiaomi MiMo： -- `AZURE_SPEECH_KEY` 加 `AZURE_SPEECH_REGION`（也接受 `AZURE_SPEECH_API_KEY`、`SPEECH_KEY` 和 `SPEECH_REGION`） +- `AZURE_SPEECH_KEY` 加上 `AZURE_SPEECH_REGION`（也接受 `AZURE_SPEECH_API_KEY`、`SPEECH_KEY` 和 `SPEECH_REGION`） - `ELEVENLABS_API_KEY`（或 `XI_API_KEY`） - `GEMINI_API_KEY`（或 `GOOGLE_API_KEY`） - `GRADIUM_API_KEY` - `INWORLD_API_KEY` -- `MINIMAX_API_KEY`；MiniMax TTS 也接受通过 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_CODING_API_KEY` 提供的 Token Plan 身份验证 +- `MINIMAX_API_KEY`；MiniMax TTS 还接受通过 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_CODING_API_KEY` 进行的 Token Plan 认证 - `OPENAI_API_KEY` -- `VOLCENGINE_TTS_API_KEY`（或 `BYTEPLUS_SEED_SPEECH_API_KEY`）；旧版 AppID/token 身份验证也接受 `VOLCENGINE_TTS_APPID` 和 `VOLCENGINE_TTS_TOKEN` +- `VOLCENGINE_TTS_API_KEY`（或 `BYTEPLUS_SEED_SPEECH_API_KEY`）；旧版 AppID/token 认证也接受 `VOLCENGINE_TTS_APPID` 和 `VOLCENGINE_TTS_TOKEN` - `VYDRA_API_KEY` - `XAI_API_KEY` - `XIAOMI_API_KEY` -Local CLI 和 Microsoft 语音**不**需要 API 密钥。 +Local CLI 和 Microsoft 语音 **不** 需要 API 密钥。 -如果配置了多个提供商，将首先使用所选提供商，其他提供商则作为后备选项。 -自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用了摘要，该提供商也必须已完成身份验证。 +如果配置了多个提供商，则会先使用所选提供商，其他提供商作为回退选项。 +自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用了摘要，对应的提供商也必须完成认证。 ## 服务链接 - [OpenAI 文本转语音指南](https://platform.openai.com/docs/guides/text-to-speech) -- [OpenAI Audio API 参考](https://platform.openai.com/docs/api-reference/audio) +- [OpenAI 音频 API 参考](https://platform.openai.com/docs/api-reference/audio) - [Azure Speech REST 文本转语音](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech) - [Azure Speech provider](/zh-CN/providers/azure-speech) - [ElevenLabs 文本转语音](https://elevenlabs.io/docs/api-reference/text-to-speech) -- [ElevenLabs 身份验证](https://elevenlabs.io/docs/api-reference/authentication) +- [ElevenLabs 认证](https://elevenlabs.io/docs/api-reference/authentication) - [Gradium](/zh-CN/providers/gradium) - [Inworld TTS API](https://docs.inworld.ai/tts/tts) - [MiniMax T2A v2 API](https://platform.minimaxi.com/document/T2A%20V2) @@ -80,14 +80,14 @@ Local CLI 和 Microsoft 语音**不**需要 API 密钥。 ## 默认启用吗？ -不会。自动 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)。 ### 最小配置（启用 + 提供商） @@ -102,9 +102,10 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### 按智能体覆盖语音 +### 按智能体覆盖语音设置 -当某个智能体需要使用不同的提供商、声音、模型、风格或自动 TTS 模式时，请使用 `agents.list[].tts`。智能体块会在 `messages.tts` 之上进行深度合并，因此提供商凭证可以保留在全局提供商配置中。 +当某个智能体需要使用不同的提供商、语音、模型、风格或自动 TTS 模式时，请使用 `agents.list[].tts`。 +智能体块会在 `messages.tts` 之上进行深度合并，因此提供商凭证可以保留在全局提供商配置中。 ```json5 { @@ -137,14 +138,14 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -自动回复、`/tts audio`、`/tts status` 和 `tts` 智能体工具的优先级顺序如下： +自动回复、`/tts audio`、`/tts status` 和 `tts` 智能体工具的优先级如下： 1. `messages.tts` -2. 当前活动的 `agents.list[].tts` +2. 当前激活的 `agents.list[].tts` 3. 此主机的本地 `/tts` 偏好设置 4. 启用模型覆盖时的内联 `[[tts:...]]` 指令 -### OpenAI 为主，ElevenLabs 为后备 +### OpenAI 主提供商 + ElevenLabs 回退 ```json5 { @@ -185,7 +186,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### Azure Speech 为主 +### Azure Speech 主提供商 ```json5 { @@ -195,8 +196,8 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 provider: "azure-speech", providers: { "azure-speech": { - // apiKey 默认回退到 AZURE_SPEECH_KEY。 - // region 默认回退到 AZURE_SPEECH_REGION。 + // apiKey 会回退到 AZURE_SPEECH_KEY。 + // region 会回退到 AZURE_SPEECH_REGION。 voice: "en-US-JennyNeural", lang: "en-US", outputFormat: "audio-24khz-48kbitrate-mono-mp3", @@ -208,9 +209,12 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -Azure Speech 使用的是 Speech 资源密钥，而不是 Azure OpenAI 密钥。解析顺序为 `messages.tts.providers.azure-speech.apiKey` -> `AZURE_SPEECH_KEY` -> `AZURE_SPEECH_API_KEY` -> `SPEECH_KEY`，区域的解析顺序为 `messages.tts.providers.azure-speech.region` -> `AZURE_SPEECH_REGION` -> `SPEECH_REGION`。新配置应使用 `azure-speech`；`azure` 可作为提供商别名使用。 +Azure Speech 使用的是 Speech 资源密钥，而不是 Azure OpenAI 密钥。解析顺序为 `messages.tts.providers.azure-speech.apiKey` -> +`AZURE_SPEECH_KEY` -> `AZURE_SPEECH_API_KEY` -> `SPEECH_KEY`，区域则为 +`messages.tts.providers.azure-speech.region` -> `AZURE_SPEECH_REGION` -> +`SPEECH_REGION`。新配置应使用 `azure-speech`；`azure` 可作为提供商别名接受。 -### Microsoft 为主（无 API 密钥） +### Microsoft 主提供商（无 API 密钥） ```json5 { @@ -233,7 +237,7 @@ Azure Speech 使用的是 Speech 资源密钥，而不是 Azure OpenAI 密钥。 } ``` -### MiniMax 为主 +### MiniMax 主提供商 ```json5 { @@ -257,9 +261,9 @@ Azure Speech 使用的是 Speech 资源密钥，而不是 Azure OpenAI 密钥。 } ``` -MiniMax TTS 的身份验证解析顺序为 `messages.tts.providers.minimax.apiKey`，然后是已存储的 `minimax-portal` OAuth/token 配置文件，再然后是 Token Plan 环境变量密钥（`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`），最后是 `MINIMAX_API_KEY`。当未显式设置 TTS `baseUrl` 时，OpenClaw 可以复用已配置的 `minimax-portal` OAuth 主机用于 Token Plan 语音。 +MiniMax TTS 认证解析顺序是 `messages.tts.providers.minimax.apiKey`，然后是已存储的 `minimax-portal` OAuth/token 配置文件，再然后是 Token Plan 环境变量键（`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`），最后是 `MINIMAX_API_KEY`。当未显式设置 TTS `baseUrl` 时，OpenClaw 可以复用已配置的 `minimax-portal` OAuth 主机用于 Token Plan 语音。 -### Google Gemini 为主 +### Google Gemini 主提供商 ```json5 { @@ -279,9 +283,10 @@ MiniMax TTS 的身份验证解析顺序为 `messages.tts.providers.minimax.apiKe } ``` -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`。 -### Inworld 为主 +### Inworld 主提供商 ```json5 { @@ -303,9 +308,9 @@ Google Gemini TTS 使用 Gemini API 密钥路径。这里可以使用限制为 G } ``` -`apiKey` 的值必须是从 Inworld 控制台（Workspace > API Keys）逐字复制的 Base64 编码凭证字符串。提供商会将其作为 `Authorization: Basic ` 发送，不会进行任何额外编码，因此不要传入原始 bearer token，也不要自行再次进行 Base64 编码。该密钥会回退到 `INWORLD_API_KEY` 环境变量。完整设置请参阅 [Inworld provider](/zh-CN/providers/inworld)。 +`apiKey` 的值必须是从 Inworld 控制台（Workspace > API Keys）逐字复制的 Base64 编码凭证字符串。该提供商会将其作为 `Authorization: Basic ` 发送，而不会进行任何额外编码，因此不要传入原始 bearer token，也不要自行再次进行 Base64 编码。该密钥会回退到 `INWORLD_API_KEY` 环境变量。完整设置见 [Inworld provider](/zh-CN/providers/inworld)。 -### Volcengine 为主 +### Volcengine 主提供商 ```json5 { @@ -326,9 +331,10 @@ Google Gemini TTS 使用 Gemini API 密钥路径。这里可以使用限制为 G } ``` -Volcengine TTS 使用的是来自 Speech Console 的 BytePlus Seed Speech API 密钥，而不是 Doubao 模型提供商所使用的 OpenAI 兼容 `VOLCANO_ENGINE_API_KEY`。解析顺序为 `messages.tts.providers.volcengine.apiKey` -> `VOLCENGINE_TTS_API_KEY` -> `BYTEPLUS_SEED_SPEECH_API_KEY`。旧版 AppID/token 身份验证仍可通过 `messages.tts.providers.volcengine.appId` / `token` 或 `VOLCENGINE_TTS_APPID` / `VOLCENGINE_TTS_TOKEN` 使用。语音便笺目标会请求提供商原生的 `ogg_opus`；普通音频文件目标会请求 `mp3`。 +Volcengine TTS 使用的是来自 Speech Console 的 BytePlus Seed Speech API 密钥，而不是 Doubao 模型提供商使用的 OpenAI 兼容 `VOLCANO_ENGINE_API_KEY`。解析顺序为 `messages.tts.providers.volcengine.apiKey` -> +`VOLCENGINE_TTS_API_KEY` -> `BYTEPLUS_SEED_SPEECH_API_KEY`。旧版 AppID/token 认证仍可通过 `messages.tts.providers.volcengine.appId` / `token` 或 `VOLCENGINE_TTS_APPID` / `VOLCENGINE_TTS_TOKEN` 使用。语音便笺目标会请求提供商原生的 `ogg_opus`；普通音频文件目标会请求 `mp3`。 -### xAI 为主 +### xAI 主提供商 ```json5 { @@ -350,9 +356,9 @@ Volcengine TTS 使用的是来自 Speech Console 的 BytePlus Seed Speech API } ``` -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`。 -### Xiaomi MiMo 为主 +### Xiaomi MiMo 主提供商 ```json5 { @@ -375,9 +381,9 @@ xAI TTS 使用与内置 Grok 模型提供商相同的 `XAI_API_KEY` 路径。解 } ``` -Xiaomi MiMo TTS 使用与内置 Xiaomi 模型提供商相同的 `XIAOMI_API_KEY` 路径。语音提供商 id 是 `xiaomi`；`mimo` 也可作为别名使用。目标文本会作为 assistant 消息发送，以符合 Xiaomi 的 TTS 协议。可选的 `style` 会作为用户指令发送，但不会被朗读出来。 +Xiaomi MiMo TTS 与内置 Xiaomi 模型提供商使用相同的 `XIAOMI_API_KEY` 路径。语音提供商 ID 是 `xiaomi`；`mimo` 也可作为别名。目标文本会作为 assistant message 发送，以匹配 Xiaomi 的 TTS 协议。可选的 `style` 会作为 user instruction 发送，不会被朗读出来。 -### OpenRouter 为主 +### OpenRouter 主提供商 ```json5 { @@ -398,9 +404,11 @@ Xiaomi MiMo TTS 使用与内置 Xiaomi 模型提供商相同的 `XIAOMI_API_KEY` } ``` -OpenRouter TTS 使用与内置 OpenRouter 模型提供商相同的 `OPENROUTER_API_KEY` 路径。解析顺序为 `messages.tts.providers.openrouter.apiKey` -> `models.providers.openrouter.apiKey` -> `OPENROUTER_API_KEY`。 +OpenRouter TTS 与内置 OpenRouter 模型提供商使用相同的 `OPENROUTER_API_KEY` 路径。解析顺序为 +`messages.tts.providers.openrouter.apiKey` -> +`models.providers.openrouter.apiKey` -> `OPENROUTER_API_KEY`。 -### Local CLI 为主 +### Local CLI 主提供商 ```json5 { @@ -421,9 +429,9 @@ OpenRouter TTS 使用与内置 OpenRouter 模型提供商相同的 `OPENROUTER_A } ``` -Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}` 和 `{{OutputBase}}` 占位符会在 `args` 中展开；如果不存在 `{{Text}}` 占位符，OpenClaw 会将要朗读的文本写入 stdin。`outputFormat` 接受 `mp3`、`opus` 或 `wav`。语音便笺目标会被转码为 Ogg/Opus，电话语音输出会通过 `ffmpeg` 转码为原始 16 kHz 单声道 PCM。旧版提供商别名 `cli` 仍然有效，但新配置应使用 `tts-local-cli`。 +Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`args` 中的 `{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}` 和 `{{OutputBase}}` 占位符会被展开；如果不存在 `{{Text}}` 占位符，OpenClaw 会将要朗读的文本写入 stdin。`outputFormat` 接受 `mp3`、`opus` 或 `wav`。语音便笺目标会被转码为 Ogg/Opus，电话输出会通过 `ffmpeg` 转码为原始 16 kHz 单声道 PCM。旧版提供商别名 `cli` 仍然可用，但新配置应使用 `tts-local-cli`。 -### Gradium 为主 +### Gradium 主提供商 ```json5 { @@ -459,7 +467,7 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} } ``` -### 自定义限制 + 偏好设置路径 +### 自定义限制 + prefs 路径 ```json5 { @@ -474,7 +482,7 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} } ``` -### 仅在收到语音消息后用音频回复 +### 仅在收到入站语音消息后用音频回复 ```json5 { @@ -507,111 +515,111 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} ### 字段说明 - `auto`：自动 TTS 模式（`off`、`always`、`inbound`、`tagged`）。 - - `inbound` 仅在收到传入的语音消息后发送音频。 + - `inbound` 仅在收到入站语音消息后发送音频。 - `tagged` 仅在回复包含 `[[tts:key=value]]` 指令或 `[[tts:text]]...[[/tts:text]]` 块时发送音频。 -- `enabled`：旧版开关（Doctor 会将其迁移为 `auto`）。 -- `mode`：`"final"`（默认）或 `"all"`（包括工具/分块回复）。 -- `provider`：语音提供商 id，例如 `"elevenlabs"`、`"google"`、`"gradium"`、`"inworld"`、`"microsoft"`、`"minimax"`、`"openai"`、`"volcengine"`、`"vydra"`、`"xai"` 或 `"xiaomi"`（会自动回退）。 -- 如果未设置 `provider`，OpenClaw 会按注册表自动选择顺序使用第一个已配置的语音提供商。 -- 旧版 `provider: "edge"` 配置可通过 `openclaw doctor --fix` 修复，并重写为 `provider: "microsoft"`。 -- `summaryModel`：用于自动摘要的可选低成本模型；默认值为 `agents.defaults.model.primary`。 +- `enabled`：旧版开关（`doctor` 会将其迁移为 `auto`）。 +- `mode`：`"final"`（默认）或 `"all"`（包含工具/分块回复）。 +- `provider`：语音提供商 ID，例如 `"elevenlabs"`、`"google"`、`"gradium"`、`"inworld"`、`"microsoft"`、`"minimax"`、`"openai"`、`"volcengine"`、`"vydra"`、`"xai"` 或 `"xiaomi"`（回退会自动处理）。 +- 如果 `provider` **未设置**，OpenClaw 会按注册表自动选择顺序使用第一个已配置的语音提供商。 +- 旧版 `provider: "edge"` 配置可由 `openclaw doctor --fix` 修复，并重写为 `provider: "microsoft"`。 +- `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` 会失败。 +- `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` 值会回退到环境变量（`AZURE_SPEECH_KEY` / `AZURE_SPEECH_API_KEY` / `SPEECH_KEY`、`ELEVENLABS_API_KEY` / `XI_API_KEY`、`GEMINI_API_KEY` / `GOOGLE_API_KEY`、`GRADIUM_API_KEY`、`INWORLD_API_KEY`、`MINIMAX_API_KEY`、`OPENAI_API_KEY`、`VYDRA_API_KEY`、`XAI_API_KEY`、`XIAOMI_API_KEY`）。Volcengine 则使用 `appId` / `token`。 +- `prefsPath`：覆盖本地 prefs JSON 路径（提供商/限制/摘要）。 +- `apiKey` 值会回退到环境变量（`AZURE_SPEECH_KEY`/`AZURE_SPEECH_API_KEY`/`SPEECH_KEY`、`ELEVENLABS_API_KEY`/`XI_API_KEY`、`GEMINI_API_KEY`/`GOOGLE_API_KEY`、`GRADIUM_API_KEY`、`INWORLD_API_KEY`、`MINIMAX_API_KEY`、`OPENAI_API_KEY`、`VYDRA_API_KEY`、`XAI_API_KEY`、`XIAOMI_API_KEY`）。Volcengine 改用 `appId`/`token`。 - `providers.azure-speech.apiKey`：Azure Speech 资源密钥（环境变量：`AZURE_SPEECH_KEY`、`AZURE_SPEECH_API_KEY` 或 `SPEECH_KEY`）。 - `providers.azure-speech.region`：Azure Speech 区域，例如 `eastus`（环境变量：`AZURE_SPEECH_REGION` 或 `SPEECH_REGION`）。 -- `providers.azure-speech.endpoint` / `providers.azure-speech.baseUrl`：可选的 Azure Speech 端点 / base URL 覆盖值。 +- `providers.azure-speech.endpoint` / `providers.azure-speech.baseUrl`：可选的 Azure Speech endpoint/base URL 覆盖。 - `providers.azure-speech.voice`：Azure 语音 ShortName（默认 `en-US-JennyNeural`）。 - `providers.azure-speech.lang`：SSML 语言代码（默认 `en-US`）。 - `providers.azure-speech.outputFormat`：用于标准音频输出的 Azure `X-Microsoft-OutputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。 - `providers.azure-speech.voiceNoteOutputFormat`：用于语音便笺输出的 Azure `X-Microsoft-OutputFormat`（默认 `ogg-24khz-16bit-mono-opus`）。 - `providers.elevenlabs.baseUrl`：覆盖 ElevenLabs API base URL。 -- `providers.openai.baseUrl`：覆盖 OpenAI TTS 端点。 +- `providers.openai.baseUrl`：覆盖 OpenAI TTS endpoint。 - 解析顺序：`messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` - - 非默认值会被视为 OpenAI 兼容的 TTS 端点，因此接受自定义模型名和语音名。 + - 非默认值会被视为与 OpenAI 兼容的 TTS endpoint，因此接受自定义模型名和语音名。 - `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.seed`：整数 `0..4294967295`（尽力提供确定性） +- `providers.elevenlabs.languageCode`：2 字母 ISO 639-1 代码（例如 `en`、`de`） +- `providers.elevenlabs.seed`：整数 `0..4294967295`（尽力保证确定性） - `providers.minimax.baseUrl`：覆盖 MiniMax API base 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.tts-local-cli.command`：用于 CLI TTS 的本地可执行文件或命令字符串。 - `providers.tts-local-cli.args`：命令参数；支持 `{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}` 和 `{{OutputBase}}` 占位符。 -- `providers.tts-local-cli.outputFormat`：预期的 CLI 输出格式（`mp3`、`opus` 或 `wav`；音频附件默认值为 `mp3`）。 +- `providers.tts-local-cli.outputFormat`：预期的 CLI 输出格式（`mp3`、`opus` 或 `wav`；音频附件默认使用 `mp3`）。 - `providers.tts-local-cli.timeoutMs`：命令超时时间（毫秒，默认 `120000`）。 - `providers.tts-local-cli.cwd`：可选的命令工作目录。 -- `providers.tts-local-cli.env`：命令的可选字符串环境变量覆盖值。 +- `providers.tts-local-cli.env`：命令的可选字符串环境变量覆盖。 - `providers.inworld.baseUrl`：覆盖 Inworld API base URL（默认 `https://api.inworld.ai`）。 - `providers.inworld.voiceId`：Inworld 语音标识符（默认 `Sarah`）。 - `providers.inworld.modelId`：Inworld TTS 模型（默认 `inworld-tts-1.5-max`；也支持 `inworld-tts-1.5-mini`、`inworld-tts-1-max`、`inworld-tts-1`）。 - `providers.inworld.temperature`：采样温度 `0..2`（可选）。 - `providers.google.model`：Gemini TTS 模型（默认 `gemini-3.1-flash-tts-preview`）。 -- `providers.google.voiceName`：Gemini 预置语音名称（默认 `Kore`；也接受 `voice`）。 -- `providers.google.audioProfile`：加在朗读文本前面的自然语言风格提示。 -- `providers.google.speakerName`：当你的 TTS 提示使用命名说话人时，加在朗读文本前面的可选说话人标签。 -- `providers.google.baseUrl`：覆盖 Gemini API base URL。仅接受 `https://generativelanguage.googleapis.com`。 - - 如果省略 `messages.tts.providers.google.apiKey`，TTS 可以在回退到环境变量前复用 `models.providers.google.apiKey`。 +- `providers.google.voiceName`：Gemini 预设语音名称（默认 `Kore`；也接受 `voice`）。 +- `providers.google.audioProfile`：在要朗读的文本前附加的自然语言风格提示。 +- `providers.google.speakerName`：当你的 TTS 提示使用命名说话人时，在要朗读文本前附加的可选说话人标签。 +- `providers.google.baseUrl`：覆盖 Gemini API base URL。只接受 `https://generativelanguage.googleapis.com`。 + - 如果省略 `messages.tts.providers.google.apiKey`，TTS 可以在回退到环境变量之前复用 `models.providers.google.apiKey`。 - `providers.gradium.baseUrl`：覆盖 Gradium API base URL（默认 `https://api.gradium.ai`）。 - `providers.gradium.voiceId`：Gradium 语音标识符（默认 Emma，`YTpq7expH9539ERJ`）。 - `providers.volcengine.apiKey`：BytePlus Seed Speech API 密钥（环境变量：`VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`）。 -- `providers.volcengine.resourceId`：BytePlus Seed Speech 资源 id（默认 `seed-tts-1.0`，环境变量：`VOLCENGINE_TTS_RESOURCE_ID`；如果你的 BytePlus 项目具有 TTS 2.0 权限，请使用 `seed-tts-2.0`）。 +- `providers.volcengine.resourceId`：BytePlus Seed Speech 资源 ID（默认 `seed-tts-1.0`，环境变量：`VOLCENGINE_TTS_RESOURCE_ID`；当你的 BytePlus 项目具有 TTS 2.0 权限时，请使用 `seed-tts-2.0`）。 - `providers.volcengine.appKey`：BytePlus Seed Speech app key 请求头（默认 `aGjiRDfUWi`，环境变量：`VOLCENGINE_TTS_APP_KEY`）。 -- `providers.volcengine.baseUrl`：覆盖 Seed Speech TTS HTTP 端点（环境变量：`VOLCENGINE_TTS_BASE_URL`）。 -- `providers.volcengine.appId`：旧版 Volcengine Speech Console 应用 id（环境变量：`VOLCENGINE_TTS_APPID`）。 -- `providers.volcengine.token`：旧版 Volcengine Speech Console 访问令牌（环境变量：`VOLCENGINE_TTS_TOKEN`）。 +- `providers.volcengine.baseUrl`：覆盖 Seed Speech TTS HTTP endpoint（环境变量：`VOLCENGINE_TTS_BASE_URL`）。 +- `providers.volcengine.appId`：旧版 Volcengine Speech Console application id（环境变量：`VOLCENGINE_TTS_APPID`）。 +- `providers.volcengine.token`：旧版 Volcengine Speech Console access token（环境变量：`VOLCENGINE_TTS_TOKEN`）。 - `providers.volcengine.cluster`：旧版 Volcengine TTS 集群（默认 `volcano_tts`，环境变量：`VOLCENGINE_TTS_CLUSTER`）。 - `providers.volcengine.voice`：语音类型（默认 `en_female_anna_mars_bigtts`，环境变量：`VOLCENGINE_TTS_VOICE`）。 - `providers.volcengine.speedRatio`：提供商原生速度比率。 - `providers.volcengine.emotion`：提供商原生情感标签。 - `providers.xai.apiKey`：xAI TTS API 密钥（环境变量：`XAI_API_KEY`）。 - `providers.xai.baseUrl`：覆盖 xAI TTS base URL（默认 `https://api.x.ai/v1`，环境变量：`XAI_BASE_URL`）。 -- `providers.xai.voiceId`：xAI 语音 id（默认 `eve`；当前可用实时语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`）。 +- `providers.xai.voiceId`：xAI 语音 ID（默认 `eve`；当前可用实时语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`）。 - `providers.xai.language`：BCP-47 语言代码或 `auto`（默认 `en`）。 - `providers.xai.responseFormat`：`mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`（默认 `mp3`）。 -- `providers.xai.speed`：提供商原生速度覆盖值。 +- `providers.xai.speed`：提供商原生速度覆盖。 - `providers.xiaomi.apiKey`：Xiaomi MiMo API 密钥（环境变量：`XIAOMI_API_KEY`）。 - `providers.xiaomi.baseUrl`：覆盖 Xiaomi MiMo API base URL（默认 `https://api.xiaomimimo.com/v1`，环境变量：`XIAOMI_BASE_URL`）。 - `providers.xiaomi.model`：TTS 模型（默认 `mimo-v2.5-tts`，环境变量：`XIAOMI_TTS_MODEL`；也支持 `mimo-v2-tts`）。 -- `providers.xiaomi.voice`：MiMo 语音 id（默认 `mimo_default`，环境变量：`XIAOMI_TTS_VOICE`）。 +- `providers.xiaomi.voice`：MiMo 语音 ID（默认 `mimo_default`，环境变量：`XIAOMI_TTS_VOICE`）。 - `providers.xiaomi.format`：`mp3` 或 `wav`（默认 `mp3`，环境变量：`XIAOMI_TTS_FORMAT`）。 -- `providers.xiaomi.style`：作为 user 消息发送的可选自然语言风格指令；不会被朗读。 +- `providers.xiaomi.style`：可选的自然语言风格指令，会作为 user message 发送；不会被朗读。 - `providers.openrouter.apiKey`：OpenRouter API 密钥（环境变量：`OPENROUTER_API_KEY`；可复用 `models.providers.openrouter.apiKey`）。 - `providers.openrouter.baseUrl`：覆盖 OpenRouter TTS base URL（默认 `https://openrouter.ai/api/v1`；旧版 `https://openrouter.ai/v1` 会被规范化）。 -- `providers.openrouter.model`：OpenRouter TTS 模型 id（默认 `hexgrad/kokoro-82m`；也接受 `modelId`）。 -- `providers.openrouter.voice`：提供商特定的语音 id（默认 `af_alloy`；也接受 `voiceId`）。 +- `providers.openrouter.model`：OpenRouter TTS 模型 ID（默认 `hexgrad/kokoro-82m`；也接受 `modelId`）。 +- `providers.openrouter.voice`：提供商特定的语音 ID（默认 `af_alloy`；也接受 `voiceId`）。 - `providers.openrouter.responseFormat`：`mp3` 或 `pcm`（默认 `mp3`）。 -- `providers.openrouter.speed`：提供商原生速度覆盖值。 -- `providers.microsoft.enabled`：允许使用 Microsoft 语音（默认 `true`；无需 API 密钥）。 +- `providers.openrouter.speed`：提供商原生速度覆盖。 +- `providers.microsoft.enabled`：允许使用 Microsoft 语音（默认 `true`；无 API 密钥）。 - `providers.microsoft.voice`：Microsoft 神经网络语音名称（例如 `en-US-MichelleNeural`）。 - `providers.microsoft.lang`：语言代码（例如 `en-US`）。 - `providers.microsoft.outputFormat`：Microsoft 输出格式（例如 `audio-24khz-48kbitrate-mono-mp3`）。 - - 有效值请参阅 Microsoft Speech 输出格式；并非所有格式都受内置的 Edge 支持传输方式支持。 + - 有效值见 Microsoft Speech 输出格式；并非所有格式都受内置的 Edge 后端传输支持。 - `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`：百分比字符串（例如 `+10%`、`-5%`）。 - `providers.microsoft.saveSubtitles`：在音频文件旁写入 JSON 字幕。 -- `providers.microsoft.proxy`：Microsoft 语音请求的代理 URL。 -- `providers.microsoft.timeoutMs`：请求超时覆盖值（毫秒）。 -- `edge.*`：同一组 Microsoft 设置的旧版别名。运行 `openclaw doctor --fix` 可将已保存配置重写为 `providers.microsoft`。 +- `providers.microsoft.proxy`：Microsoft 语音请求使用的代理 URL。 +- `providers.microsoft.timeoutMs`：请求超时覆盖（毫秒）。 +- `edge.*`：同一组 Microsoft 设置的旧版别名。运行 `openclaw doctor --fix` 可将持久化配置重写为 `providers.microsoft`。 ## 模型驱动的覆盖（默认开启） -默认情况下，模型**可以**为单条回复输出 TTS 指令。 +默认情况下，模型**可以**为单条回复输出 TTS 指令。 当 `messages.tts.auto` 为 `tagged` 时，必须有这些指令才会触发音频。 -启用后，模型可以输出 `[[tts:...]]` 指令，以覆盖单条回复的语音设置；也可以附带一个可选的 `[[tts:text]]...[[/tts:text]]` 块，用于提供只应出现在音频中的表现性标签（笑声、唱歌提示等）。 +启用后，模型可以输出 `[[tts:...]]` 指令来为单条回复覆盖语音设置，还可以附带一个可选的 `[[tts:text]]...[[/tts:text]]` 块，用于提供表达性标签（笑声、歌唱提示等），这些内容只应出现在音频中。 除非设置 `modelOverrides.allowProvider: true`，否则 `provider=...` 指令会被忽略。 @@ -626,12 +634,12 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} 可用的指令键（启用时）： -- `provider`（已注册的语音提供商 id，例如 `openai`、`elevenlabs`、`google`、`gradium`、`minimax`、`microsoft`、`volcengine`、`vydra`、`xai` 或 `xiaomi`；需要 `allowProvider: true`） -- `voice`（OpenAI、Gradium、Volcengine 或 Xiaomi 的语音）、`voiceName` / `voice_name` / `google_voice`（Google 语音）或 `voiceId`（ElevenLabs / Gradium / MiniMax / xAI） +- `provider`（已注册的语音提供商 ID，例如 `openai`、`elevenlabs`、`google`、`gradium`、`minimax`、`microsoft`、`volcengine`、`vydra`、`xai` 或 `xiaomi`；需要 `allowProvider: true`） +- `voice`（OpenAI、Gradium、Volcengine 或 Xiaomi 语音）、`voiceName` / `voice_name` / `google_voice`（Google 语音），或 `voiceId`（ElevenLabs / Gradium / MiniMax / xAI） - `model`（OpenAI TTS 模型、ElevenLabs model id、MiniMax 模型或 Xiaomi MiMo TTS 模型）或 `google_model`（Google TTS 模型） - `stability`、`similarityBoost`、`style`、`speed`、`useSpeakerBoost` - `vol` / `volume`（MiniMax 音量，0-10） -- `pitch`（MiniMax 整数音高，-12 到 12；在发送 MiniMax 请求前会截断小数值） +- `pitch`（MiniMax 整数音高，-12 到 12；在发起 MiniMax 请求前会截断小数值） - `emotion`（Volcengine 情感标签） - `applyTextNormalization`（`auto|on|off`） - `languageCode`（ISO 639-1） @@ -667,40 +675,46 @@ Local CLI TTS 会在 Gateway 网关主机上运行已配置的命令。`{{Text}} } ``` -## 按用户偏好设置 +## 按用户的偏好设置 -斜杠命令会将本地覆盖项写入 `prefsPath`（默认值：`~/.openclaw/settings/tts.json`，可通过 `OPENCLAW_TTS_PREFS` 或 `messages.tts.prefsPath` 覆盖）。 +斜杠命令会将本地覆盖写入 `prefsPath`（默认： +`~/.openclaw/settings/tts.json`，可通过 `OPENCLAW_TTS_PREFS` 或 +`messages.tts.prefsPath` 覆盖）。 -已存储字段： +存储的字段： - `enabled` - `provider` - `maxLength`（摘要阈值；默认 1500 个字符） - `summarize`（默认 `true`） -对于该主机，这些值会覆盖来自 `messages.tts` 加上当前活动 `agents.list[].tts` 块的生效配置。 +这些字段会覆盖该主机上来自 `messages.tts` 加上当前激活 +`agents.list[].tts` 块的生效配置。 ## 输出格式（固定） -- **Feishu / Matrix / Telegram / WhatsApp**：语音便笺回复优先使用 Opus（ElevenLabs 使用 `opus_48000_64`，OpenAI 使用 `opus`）。 +- **Feishu / Matrix / Telegram / WhatsApp**：语音便笺回复优先使用 Opus（ElevenLabs 的 `opus_48000_64`，OpenAI 的 `opus`）。 - 48 kHz / 64 kbps 是语音消息较好的折中方案。 -- **Feishu**：当语音便笺回复生成为 MP3/WAV/M4A 或其他可能的音频文件时，Feishu 插件会在发送原生 `audio` 气泡前，使用 `ffmpeg` 将其转码为 48 kHz Ogg/Opus。如果转换失败，Feishu 会将原始文件作为附件接收。 -- **其他渠道**：MP3（ElevenLabs 使用 `mp3_44100_128`，OpenAI 使用 `mp3`）。 - - 44.1 kHz / 128 kbps 是语音清晰度的默认平衡设置。 -- **MiniMax**：普通音频附件使用 MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。对于 Feishu 和 Telegram 等语音便笺目标，OpenClaw 会在发送前使用 `ffmpeg` 将 MiniMax MP3 转码为 48 kHz Opus。 -- **Xiaomi MiMo**：默认使用 MP3，或在配置时使用 WAV。对于 Feishu 和 Telegram 等语音便笺目标，OpenClaw 会在发送前使用 `ffmpeg` 将 Xiaomi 输出转码为 48 kHz Opus。 -- **Local CLI**：使用已配置的 `outputFormat`。语音便笺目标会被转换为 Ogg/Opus，电话语音输出会通过 `ffmpeg` 转换为原始 16 kHz 单声道 PCM。 -- **Google Gemini**：Gemini API TTS 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 作为音频附件，对语音便笺目标转码为 48 kHz Opus，并为 Talk / 电话语音直接返回 PCM。 -- **Gradium**：音频附件使用 WAV，语音便笺目标使用 Opus，电话语音使用 8 kHz 的 `ulaw_8000`。 -- **Inworld**：普通音频附件使用 MP3，语音便笺目标使用原生 `OGG_OPUS`，Talk / 电话语音使用 22050 Hz 的原始 `PCM`。 -- **xAI**：默认使用 MP3；`responseFormat` 可为 `mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`。OpenClaw 使用 xAI 的批量 REST TTS 端点，并返回完整的音频附件；此提供商路径不使用 xAI 的流式 TTS WebSocket。此路径不支持原生 Opus 语音便笺格式。 +- **Feishu / WhatsApp**：当语音便笺回复生成为 MP3/WebM/WAV/M4A + 或其他可能的音频文件时，渠道插件会在发送原生语音消息前，使用 `ffmpeg` 将其转码为 48 kHz + Ogg/Opus。WhatsApp 会通过带有 `ptt: true` 和 + `audio/ogg; codecs=opus` 的 Baileys `audio` 负载发送结果。如果转换失败，Feishu 会收到原始文件作为附件；WhatsApp 发送会失败，而不是发送不兼容的 PTT 负载。 +- **其他渠道**：MP3（ElevenLabs 的 `mp3_44100_128`，OpenAI 的 `mp3`）。 + - 44.1 kHz / 128 kbps 是语音清晰度的默认平衡点。 +- **MiniMax**：普通音频附件使用 MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。对于 Feishu、Telegram 和 WhatsApp 等语音便笺目标，OpenClaw 会在投递前使用 `ffmpeg` 将 MiniMax MP3 转码为 48 kHz Opus。 +- **Xiaomi MiMo**：默认使用 MP3，配置后也可使用 WAV。对于 Feishu、Telegram 和 WhatsApp 等语音便笺目标，OpenClaw 会在投递前使用 `ffmpeg` 将 Xiaomi 输出转码为 48 kHz Opus。 +- **Local CLI**：使用已配置的 `outputFormat`。语音便笺目标会被转换为 Ogg/Opus，电话输出会通过 `ffmpeg` 转换为原始 16 kHz 单声道 PCM。 +- **Google Gemini**：Gemini API TTS 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 用于音频附件，将其转码为 48 kHz Opus 用于语音便笺目标，并直接返回 PCM 用于 Talk/电话。 +- **Gradium**：音频附件使用 WAV，语音便笺目标使用 Opus，电话使用 8 kHz 的 `ulaw_8000`。 +- **Inworld**：普通音频附件使用 MP3，语音便笺目标使用原生 `OGG_OPUS`，Talk/电话使用 22050 Hz 的原始 `PCM`。 +- **xAI**：默认使用 MP3；`responseFormat` 可以是 `mp3`、`wav`、`pcm`、`mulaw` 或 `alaw`。OpenClaw 使用 xAI 的批处理 REST TTS endpoint，并返回完整的音频附件；此提供商路径不使用 xAI 的流式 TTS WebSocket。此路径不支持原生 Opus 语音便笺格式。 - **Microsoft**：使用 `microsoft.outputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。 - - 内置传输层接受 `outputFormat`，但并非所有格式都可从该服务获得。 + - 内置传输接受 `outputFormat`，但并非所有格式都可从该服务获得。 - 输出格式值遵循 Microsoft Speech 输出格式（包括 Ogg/WebM Opus）。 - - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保障的 Opus 语音消息，请使用 OpenAI / ElevenLabs。 - - 如果配置的 Microsoft 输出格式失败，OpenClaw 会回退重试 MP3。 + - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保证的 Opus 语音消息，请使用 OpenAI/ElevenLabs。 + - 如果已配置的 Microsoft 输出格式失败，OpenClaw 会回退并重试 MP3。 -OpenAI / ElevenLabs 输出格式会按渠道固定（见上文）。 +OpenAI/ElevenLabs 的输出格式按渠道固定（见上文）。 ## 自动 TTS 行为 @@ -708,32 +722,33 @@ OpenAI / ElevenLabs 输出格式会按渠道固定（见上文）。 - 如果回复已包含媒体或 `MEDIA:` 指令，则跳过 TTS。 - 跳过非常短的回复（少于 10 个字符）。 -- 启用时，使用 `agents.defaults.model.primary`（或 `summaryModel`）为长回复生成摘要。 -- 将生成的音频附加到回复中。 +- 启用时，使用 `agents.defaults.model.primary`（或 `summaryModel`）对长回复进行摘要。 +- 将生成的音频作为附件附加到回复中。 -如果回复超出 `maxLength` 且摘要已关闭（或摘要模型没有 API 密钥），则会跳过音频并发送普通文本回复。 +如果回复超过 `maxLength`，且摘要已关闭（或摘要模型没有 API 密钥），则会跳过音频，并发送普通文本回复。 ## 流程图 ``` -回复 -> 是否启用 TTS？ +回复 -> 已启用 TTS？ 否 -> 发送文本 是 -> 是否有媒体 / MEDIA: / 过短？ 是 -> 发送文本 否 -> 长度 > 限制？ 否 -> TTS -> 附加音频 - 是 -> 是否启用摘要？ + 是 -> 已启用摘要？ 否 -> 发送文本 - 是 -> 生成摘要（summaryModel 或 agents.defaults.model.primary） + 是 -> 摘要（summaryModel 或 agents.defaults.model.primary） -> TTS -> 附加音频 ``` ## 斜杠命令用法 -只有一个命令：`/tts`。 -启用详情请参阅 [斜杠命令](/zh-CN/tools/slash-commands)。 +只有一个命令：`/tts`。 +启用详情见 [斜杠命令](/zh-CN/tools/slash-commands)。 -Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在那里将原生命令注册为 `/voice`。文本形式的 `/tts ...` 仍然可用。 +Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在该平台上注册 +`/voice` 作为原生命令。文本形式的 `/tts ...` 仍然可用。 ``` /tts off @@ -747,25 +762,25 @@ Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在那 说明： -- 命令需要已授权的发送者（仍然适用 allowlist / owner 规则）。 +- 命令需要授权发送者（allowlist/owner 规则仍然适用）。 - 必须启用 `commands.text` 或原生命令注册。 - 配置 `messages.tts.auto` 接受 `off|always|inbound|tagged`。 -- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会写为 `off`。 -- 如果你希望默认值为 `inbound` 或 `tagged`，请使用配置。 -- `limit` 和 `summary` 存储在本地偏好中，而不是主配置中。 +- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会将其写为 `off`。 +- 如果你想使用 `inbound` 或 `tagged` 作为默认值，请使用配置。 +- `limit` 和 `summary` 存储在本地 prefs 中，而不是主配置中。 - `/tts audio` 会生成一次性的音频回复（不会切换 TTS 为开启）。 -- `/tts status` 会包含最近一次尝试的回退可见性： +- `/tts status` 包含最近一次尝试的回退可见性： - 成功回退：`Fallback: -> ` 加 `Attempts: ...` - 失败：`Error: ...` 加 `Attempts: ...` - 详细诊断：`Attempt details: provider:outcome(reasonCode) latency` -- OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误详情和请求 id（当提供商返回时），这些信息会显示在 TTS 错误 / 日志中。 +- OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误详情和请求 ID（当提供商返回时），这些信息会显示在 TTS 错误/日志中。 ## 智能体工具 -`tts` 工具会将文本转换为语音，并返回一个用于回复投递的音频附件。当渠道是 Feishu、Matrix、Telegram 或 WhatsApp 时，音频会作为语音消息而不是文件附件发送。 -当 `ffmpeg` 可用时，Feishu 可以在这一路径上对非 Opus 的 TTS 输出进行转码。 -由于客户端对语音便笺字幕的渲染并不一致，WhatsApp 会将可见文本与 PTT 语音便笺音频分开发送。 -它接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是单次调用的提供商请求超时时间（毫秒）。 +`tts` 工具会将文本转换为语音，并返回用于回复投递的音频附件。当渠道是 Feishu、Matrix、Telegram 或 WhatsApp 时，音频会以语音消息而不是文件附件的形式投递。 +在此路径上，如果 `ffmpeg` 可用，Feishu 和 WhatsApp 可以对非 Opus 的 TTS 输出进行转码。 +WhatsApp 会通过 Baileys 以 PTT 语音便笺（带有 `ptt: true` 的 `audio`）发送音频，并将可见文本与 PTT 音频分开发送，因为客户端并不总是能稳定显示语音便笺上的字幕。 +它接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是按调用设置的提供商请求超时，单位为毫秒。 ## Gateway 网关 RPC