diff --git a/docs/zh-CN/providers/google.md b/docs/zh-CN/providers/google.md index 3ca700df1..d4a3cf364 100644 --- a/docs/zh-CN/providers/google.md +++ b/docs/zh-CN/providers/google.md @@ -2,20 +2,20 @@ read_when: - 你想在 OpenClaw 中使用 Google Gemini 模型 - 你需要 API 密钥或 OAuth 认证流程 -summary: Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、网络搜索） +summary: Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、TTS、Web 搜索） title: Google（Gemini） x-i18n: - generated_at: "2026-04-12T10:03:27Z" + generated_at: "2026-04-16T06:26:12Z" model: gpt-5.4 provider: openai - source_hash: 64b848add89061b208a5d6b19d206c433cace5216a0ca4b63d56496aecbde452 + source_hash: ec2d62855f5e80efda758aad71bcaa95c38b1e41761fa1100d47a06c62881419 source_path: providers/google.md workflow: 15 --- # Google（Gemini） -Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，以及通过 Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）和网络搜索。 +Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，同时支持通过 Gemini Grounding 实现图像生成、媒体理解（图像/音频/视频）、文本转语音和 Web 搜索。 - 提供商：`google` - 认证：`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` @@ -24,10 +24,10 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，以及 ## 入门指南 -选择你偏好的认证方式，并按照设置步骤操作。 +选择你偏好的认证方式，并按照设置步骤进行操作。 - + **最适合：** 通过 Google AI Studio 进行标准的 Gemini API 访问。 @@ -36,7 +36,7 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，以及 openclaw onboard --auth-choice gemini-api-key ``` - 或直接传入密钥： + 或者直接传入密钥： ```bash openclaw onboard --non-interactive \ @@ -64,13 +64,13 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，以及 - 环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都可接受。使用你已经配置好的那个即可。 + 环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都受支持。使用你已经配置好的那个即可。 - - **最适合：** 通过 PKCE OAuth 复用已有的 Gemini CLI 登录，而不是单独使用 API 密钥。 + + **最适合：** 通过 PKCE OAuth 复用现有的 Gemini CLI 登录，而不是使用单独的 API 密钥。 `google-gemini-cli` 提供商是非官方集成。一些用户报告称，以这种方式使用 OAuth 时会遇到账户限制。请自行承担使用风险。 @@ -78,13 +78,13 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，以及 - 本地 `gemini` 命令必须可在 `PATH` 上使用。 + 本地 `gemini` 命令必须在 `PATH` 中可用。 ```bash # Homebrew brew install gemini-cli - # or npm + # 或 npm npm install -g @google/gemini-cli ``` @@ -113,14 +113,14 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，以及 （或使用 `GEMINI_CLI_*` 变体。） - 如果 Gemini CLI OAuth 请求在登录后失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`，然后重试。 + 如果在登录后 Gemini CLI OAuth 请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`，然后重试。 - 如果在浏览器流程开始前登录就失败，请确认本地 `gemini` 命令已安装并且位于 `PATH` 上。 + 如果在浏览器流程启动前登录就失败，请确认本地 `gemini` 命令已安装并且位于 `PATH` 中。 - 仅支持 OAuth 的 `google-gemini-cli` 提供商是一个独立的文本推理接口。图像生成、媒体理解和 Gemini Grounding 仍然使用 `google` 提供商 id。 + 仅限 OAuth 的 `google-gemini-cli` 提供商是一个独立的文本推理接口。图像生成、媒体理解和 Gemini Grounding 仍然使用 `google` 提供商 id。 @@ -132,15 +132,16 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，以及 | 聊天补全 | 是 | | 图像生成 | 是 | | 音乐生成 | 是 | +| 文本转语音 | 是 | | 图像理解 | 是 | -| 音频转录 | 是 | +| 音频转写 | 是 | | 视频理解 | 是 | -| 网络搜索（Grounding） | 是 | +| Web 搜索（Grounding） | 是 | | 思考/推理 | 是（Gemini 3.1+） | | Gemma 4 模型 | 是 | -Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会将 `thinkingBudget` 重写为 Google 支持的 `thinkingLevel`，以适配 Gemma 4。将 thinking 设置为 `off` 会保持禁用思考，而不是映射为 `MINIMAL`。 +Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会将 `thinkingBudget` 重写为 Google 支持的 `thinkingLevel`，用于 Gemma 4。将 thinking 设置为 `off` 会保持思考关闭，而不是映射到 `MINIMAL`。 ## 图像生成 @@ -167,12 +168,12 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会 ``` -有关共享工具参数、提供商选择和故障切换行为，请参阅 [Image Generation](/zh-CN/tools/image-generation)。 +参见 [图像生成](/zh-CN/tools/image-generation)，了解共享工具参数、提供商选择和故障转移行为。 ## 视频生成 -内置的 `google` 插件还会通过共享的 `video_generate` 工具注册视频生成功能。 +内置的 `google` 插件还通过共享的 `video_generate` 工具注册了视频生成功能。 - 默认视频模型：`google/veo-3.1-fast-generate-preview` - 模式：文生视频、图生视频，以及单视频参考流程 @@ -194,17 +195,17 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会 ``` -有关共享工具参数、提供商选择和故障切换行为，请参阅 [Video Generation](/zh-CN/tools/video-generation)。 +参见 [视频生成](/zh-CN/tools/video-generation)，了解共享工具参数、提供商选择和故障转移行为。 ## 音乐生成 -内置的 `google` 插件还会通过共享的 `music_generate` 工具注册音乐生成功能。 +内置的 `google` 插件还通过共享的 `music_generate` 工具注册了音乐生成功能。 - 默认音乐模型：`google/lyria-3-clip-preview` - 也支持 `google/lyria-3-pro-preview` - 提示词控制：`lyrics` 和 `instrumental` -- 输出格式：默认 `mp3`，在 `google/lyria-3-pro-preview` 上还支持 `wav` +- 输出格式：默认 `mp3`，另外在 `google/lyria-3-pro-preview` 上支持 `wav` - 参考输入：最多 10 张图像 - 基于会话的运行会通过共享的任务/状态流程分离执行，包括 `action: "status"` @@ -223,19 +224,59 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会 ``` -有关共享工具参数、提供商选择和故障切换行为，请参阅 [Music Generation](/zh-CN/tools/music-generation)。 +参见 [音乐生成](/zh-CN/tools/music-generation)，了解共享工具参数、提供商选择和故障转移行为。 + + +## 文本转语音 + +内置的 `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 + +要将 Google 用作默认 TTS 提供商： + +```json5 +{ + messages: { + tts: { + auto: "always", + provider: "google", + providers: { + google: { + model: "gemini-3.1-flash-tts-preview", + voiceName: "Kore", + }, + }, + }, + }, +} +``` + +Gemini API TTS 支持在文本中使用富表现力的方括号音频标签，例如 `[whispers]` 或 `[laughs]`。如果你想让这些标签不出现在可见的聊天回复中，但仍发送给 TTS，请将它们放在 `[[tts:text]]...[[/tts:text]]` 块内： + +```text +Here is the clean reply text. + +[[tts:text]][whispers] Here is the spoken version.[[/tts:text]] +``` + + +限制为 Gemini API 的 Google Cloud Console API 密钥可用于此提供商。这不是单独的 Cloud Text-to-Speech API 路径。 ## 高级配置 - 对于直接的 Gemini API 运行（`api: "google-generative-ai"`），OpenClaw 会将已配置的 `cachedContent` 句柄透传给 Gemini 请求。 + 对于直接的 Gemini API 运行（`api: "google-generative-ai"`），OpenClaw 会将配置好的 `cachedContent` 句柄传递给 Gemini 请求。 - - 可使用 `cachedContent` 或旧版 `cached_content` 配置按模型或全局参数 - - 如果两者同时存在，`cachedContent` 优先 + - 使用 `cachedContent` 或旧版 `cached_content`，按模型或全局配置参数 + - 如果两者都存在，则 `cachedContent` 优先 - 示例值：`cachedContents/prebuilt-context` - - Gemini 的缓存命中用量会从上游的 `cachedContentTokenCount` 规范化为 OpenClaw 的 `cacheRead` + - Gemini 缓存命中用量会从上游的 `cachedContentTokenCount` 规范化为 OpenClaw `cacheRead` ```json5 { @@ -260,13 +301,13 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会 - 回复文本来自 CLI JSON 的 `response` 字段。 - 当 CLI 将 `usage` 留空时，用量会回退到 `stats`。 - - `stats.cached` 会被规范化为 OpenClaw 的 `cacheRead`。 - - 如果 `stats.input` 缺失，OpenClaw 会根据 `stats.input_tokens - stats.cached` 推导输入 token 数。 + - `stats.cached` 会被规范化为 OpenClaw `cacheRead`。 + - 如果缺少 `stats.input`，OpenClaw 会根据 `stats.input_tokens - stats.cached` 推导输入 token 数。 - 如果 Gateway 网关以守护进程形式运行（launchd/systemd），请确保 `GEMINI_API_KEY` 对该进程可用（例如在 `~/.openclaw/.env` 中，或通过 `env.shellEnv`）。 + 如果 Gateway 网关以守护进程方式运行（launchd/systemd），请确保 `GEMINI_API_KEY` 对该进程可用（例如在 `~/.openclaw/.env` 中，或通过 `env.shellEnv` 提供）。 @@ -274,7 +315,7 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw 会 - 选择提供商、模型引用和故障切换行为。 + 选择提供商、模型引用和故障转移行为。 共享图像工具参数和提供商选择。 diff --git a/docs/zh-CN/tools/tts.md b/docs/zh-CN/tools/tts.md index ae269f0ac..76031a74c 100644 --- a/docs/zh-CN/tools/tts.md +++ b/docs/zh-CN/tools/tts.md @@ -3,48 +3,50 @@ read_when: - 为回复启用文本转语音 - 配置 TTS 提供商或限制 - 使用 `/tts` 命令 -summary: 用于出站回复的文本转语音（TTS） +summary: 用于外发回复的文本转语音（TTS） title: 文本转语音 x-i18n: - generated_at: "2026-04-12T22:42:45Z" + generated_at: "2026-04-16T06:26:25Z" model: gpt-5.4 provider: openai - source_hash: ad79a6be34879347dc73fdab1bd219823cd7c6aa8504e3e4c73e1a0554c837c5 + source_hash: de7c1dc8831c1ba307596afd48cb4d36f844724887a13b17e35f41ef5174a86f source_path: tools/tts.md workflow: 15 --- # 文本转语音（TTS） -OpenClaw 可以使用 ElevenLabs、Microsoft、MiniMax 或 OpenAI 将出站回复转换为音频。 +OpenClaw 可以使用 ElevenLabs、Google Gemini、Microsoft、MiniMax 或 OpenAI 将外发回复转换为音频。 它适用于 OpenClaw 能发送音频的任何地方。 ## 支持的服务 -- **ElevenLabs**（主要或回退提供商） -- **Microsoft**（主要或回退提供商；当前内置实现使用 `node-edge-tts`） -- **MiniMax**（主要或回退提供商；使用 T2A v2 API） -- **OpenAI**（主要或回退提供商；也用于摘要） +- **ElevenLabs**（主提供商或回退提供商） +- **Google Gemini**（主提供商或回退提供商；使用 Gemini API TTS） +- **Microsoft**（主提供商或回退提供商；当前内置实现使用 `node-edge-tts`） +- **MiniMax**（主提供商或回退提供商；使用 T2A v2 API） +- **OpenAI**（主提供商或回退提供商；也用于摘要） ### 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`。 -由于这一路径是一个未公布 SLA 或配额的公共 Web 服务，请将其视为尽力而为的服务。如果你需要有保障的限制和支持，请使用 OpenAI 或 ElevenLabs。 +由于这一路径是一个未公布 SLA 或配额的公共 Web 服务，请将其视为尽力而为的服务。如果你需要有保证的限制和支持，请使用 OpenAI 或 ElevenLabs。 ## 可选密钥 -如果你想使用 OpenAI、ElevenLabs 或 MiniMax： +如果你想使用 OpenAI、ElevenLabs、Google Gemini 或 MiniMax： - `ELEVENLABS_API_KEY`（或 `XI_API_KEY`） +- `GEMINI_API_KEY`（或 `GOOGLE_API_KEY`） - `MINIMAX_API_KEY` - `OPENAI_API_KEY` Microsoft 语音**不**需要 API 密钥。 -如果配置了多个提供商，将优先使用所选提供商，其他提供商作为回退选项。 -自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用摘要，该提供商也必须完成身份验证。 +如果配置了多个提供商，将优先使用所选提供商，其他提供商则作为回退选项。 +自动摘要使用已配置的 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你启用了摘要，该提供商也必须已完成认证。 ## 服务链接 @@ -58,9 +60,9 @@ Microsoft 语音**不**需要 API 密钥。 ## 默认启用吗？ -不是。自动 TTS 默认**关闭**。可通过配置中的 `messages.tts.auto` 启用，或使用 `/tts on` 在本地启用。 +否。自动 TTS 默认**关闭**。可在配置中通过 `messages.tts.auto` 启用，或在本地通过 `/tts on` 启用。 -当未设置 `messages.tts.provider` 时，OpenClaw 会按注册表自动选择顺序挑选第一个已配置的语音提供商。 +当未设置 `messages.tts.provider` 时，OpenClaw 会按注册表自动选择顺序选取第一个已配置的语音提供商。 ## 配置 @@ -80,7 +82,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### OpenAI 作为主要提供商，ElevenLabs 作为回退提供商 +### OpenAI 为主，ElevenLabs 为回退 ```json5 { @@ -121,7 +123,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### Microsoft 作为主要提供商（无需 API 密钥） +### Microsoft 为主（无 API 密钥） ```json5 { @@ -144,7 +146,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### MiniMax 作为主要提供商 +### MiniMax 为主 ```json5 { @@ -168,6 +170,28 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` +### Google Gemini 为主 + +```json5 +{ + messages: { + tts: { + auto: "always", + provider: "google", + providers: { + google: { + apiKey: "gemini_api_key", + model: "gemini-3.1-flash-tts-preview", + voiceName: "Kore", + }, + }, + }, + }, +} +``` + +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`。 + ### 禁用 Microsoft 语音 ```json5 @@ -184,7 +208,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### 自定义限制 + prefsPath 路径 +### 自定义限制 + prefs 路径 ```json5 { @@ -199,7 +223,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -### 仅在收到入站语音消息后才用音频回复 +### 仅在收到入站语音消息后以音频回复 ```json5 { @@ -233,26 +257,26 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 - `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"`（包含工具/分块回复）。 -- `provider`：语音提供商 id，例如 `"elevenlabs"`、`"microsoft"`、`"minimax"` 或 `"openai"`（会自动回退）。 +- `mode`：`"final"`（默认）或 `"all"`（包括工具/分块回复）。 +- `provider`：语音提供商 id，例如 `"elevenlabs"`、`"google"`、`"microsoft"`、`"minimax"` 或 `"openai"`（会自动回退）。 - 如果 `provider` **未设置**，OpenClaw 会按注册表自动选择顺序使用第一个已配置的语音提供商。 -- 旧版 `provider: "edge"` 仍然可用，并会被规范化为 `microsoft`。 +- 旧版 `provider: "edge"` 仍然可用，并会被标准化为 `microsoft`。 - `summaryModel`：用于自动摘要的可选低成本模型；默认为 `agents.defaults.model.primary`。 - 接受 `provider/model` 或已配置的模型别名。 -- `modelOverrides`：允许模型输出 TTS 指令（默认开启）。 - - `allowProvider` 默认为 `false`（提供商切换需要主动启用）。 -- `providers.`：由提供商拥有的设置，按语音提供商 id 分组。 +- `modelOverrides`：允许模型发出 TTS 指令（默认开启）。 + - `allowProvider` 默认为 `false`（切换提供商需显式启用）。 +- `providers.`：按语音提供商 id 键控的提供商自有设置。 - 旧版直接提供商块（`messages.tts.openai`、`messages.tts.elevenlabs`、`messages.tts.microsoft`、`messages.tts.edge`）会在加载时自动迁移到 `messages.tts.providers.`。 -- `maxTextLength`：TTS 输入的硬性上限（字符数）。如果超出，`/tts audio` 会失败。 -- `timeoutMs`：请求超时时间（毫秒）。 -- `prefsPath`：覆盖本地偏好设置 JSON 路径（提供商/限制/摘要）。 -- `apiKey` 值会回退到环境变量（`ELEVENLABS_API_KEY`/`XI_API_KEY`、`MINIMAX_API_KEY`、`OPENAI_API_KEY`）。 +- `maxTextLength`：TTS 输入的硬上限（字符数）。超过时，`/tts audio` 会失败。 +- `timeoutMs`：请求超时（毫秒）。 +- `prefsPath`：覆盖本地 prefs JSON 路径（提供商/限制/摘要）。 +- `apiKey` 值会回退到环境变量（`ELEVENLABS_API_KEY`/`XI_API_KEY`、`GEMINI_API_KEY`/`GOOGLE_API_KEY`、`MINIMAX_API_KEY`、`OPENAI_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` @@ -262,46 +286,48 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 - `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.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）。 -- `providers.microsoft.enabled`：允许使用 Microsoft 语音（默认 `true`；无需 API 密钥）。 +- `providers.google.model`：Gemini TTS 模型（默认 `gemini-3.1-flash-tts-preview`）。 +- `providers.google.voiceName`：Gemini 预置语音名称（默认 `Kore`；也接受 `voice`）。 +- `providers.google.baseUrl`：覆盖 Gemini API 基础 URL。仅接受 `https://generativelanguage.googleapis.com`。 + - 如果省略 `messages.tts.providers.google.apiKey`，TTS 可以在回退到环境变量之前复用 `models.providers.google.apiKey`。 +- `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 设置的旧版别名。 +- `edge.*`：同一组 Microsoft 设置的旧版别名。 -## 模型驱动的覆盖（默认开启） +## 模型驱动的覆盖项（默认开启） -默认情况下，模型**可以**为单条回复输出 TTS 指令。 -当 `messages.tts.auto` 为 `tagged` 时，必须有这些指令才会触发音频。 +默认情况下，模型**可以**为单条回复发出 TTS 指令。 +当 `messages.tts.auto` 为 `tagged` 时，必须使用这些指令才会触发音频。 -启用后，模型可以输出 `[[tts:...]]` 指令来覆盖单条回复的声音， -还可以选择附带一个 `[[tts:text]]...[[/tts:text]]` 块，用于提供仅应出现在 -音频中的表现性标签（笑声、歌唱提示等）。 +启用后，模型可以发出 `[[tts:...]]` 指令来覆盖单条回复的语音设置，还可以选择性提供一个 `[[tts:text]]...[[/tts:text]]` 块，用于写入只应出现在音频中的表现性标记（笑声、唱歌提示等）。 -除非设置了 `modelOverrides.allowProvider: true`，否则 `provider=...` 指令会被忽略。 +`provider=...` 指令会被忽略，除非设置 `modelOverrides.allowProvider: true`。 示例回复载荷： ``` -给你。 +Here you go. [[tts:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]] -[[tts:text]]（笑）再把这首歌读一遍。[[/tts:text]] +[[tts:text]](laughs) Read the song once more.[[/tts:text]] ``` 可用的指令键（启用时）： -- `provider`（已注册的语音提供商 id，例如 `openai`、`elevenlabs`、`minimax` 或 `microsoft`；需要 `allowProvider: true`） -- `voice`（OpenAI 声音）或 `voiceId`（ElevenLabs / MiniMax） -- `model`（OpenAI TTS 模型、ElevenLabs model id 或 MiniMax 模型） +- `provider`（已注册的语音提供商 id，例如 `openai`、`elevenlabs`、`google`、`minimax` 或 `microsoft`；需要 `allowProvider: true`） +- `voice`（OpenAI 语音）、`voiceName` / `voice_name` / `google_voice`（Google 语音）或 `voiceId`（ElevenLabs / MiniMax） +- `model`（OpenAI TTS 模型、ElevenLabs model id 或 MiniMax 模型）或 `google_model`（Google TTS 模型） - `stability`、`similarityBoost`、`style`、`speed`、`useSpeakerBoost` - `vol` / `volume`（MiniMax 音量，0-10） - `pitch`（MiniMax 音高，-12 到 12） @@ -309,7 +335,7 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 - `languageCode`（ISO 639-1） - `seed` -禁用所有模型覆盖： +禁用所有模型覆盖项： ```json5 { @@ -339,43 +365,44 @@ TTS 配置位于 `openclaw.json` 的 `messages.tts` 下。 } ``` -## 按用户偏好设置 +## 每用户偏好设置 -Slash 命令会将本地覆盖写入 `prefsPath`（默认： +Slash 命令会将本地覆盖项写入 `prefsPath`（默认： `~/.openclaw/settings/tts.json`，可通过 `OPENCLAW_TTS_PREFS` 或 `messages.tts.prefsPath` 覆盖）。 -存储的字段： +存储字段： - `enabled` - `provider` - `maxLength`（摘要阈值；默认 1500 个字符） - `summarize`（默认 `true`） -这些值会覆盖该主机上的 `messages.tts.*`。 +这些设置会覆盖该主机上的 `messages.tts.*`。 ## 输出格式（固定） - **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 采样率）。原生不支持语音便签格式；如果你需要有保障的 Opus 语音消息，请使用 OpenAI 或 ElevenLabs。 + - 44.1 kHz / 128 kbps 是语音清晰度的默认平衡方案。 +- **MiniMax**：MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。原生不支持语音便笺格式；如果你需要有保证的 Opus 语音消息，请使用 OpenAI 或 ElevenLabs。 +- **Google Gemini**：Gemini API TTS 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 作为音频附件返回，并为 Talk/电话场景直接返回 PCM。此路径不支持原生 Opus 语音便笺格式。 - **Microsoft**：使用 `microsoft.outputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。 - - 内置传输接受 `outputFormat`，但该服务并不提供所有格式。 + - 内置传输支持 `outputFormat`，但并非所有格式都可从该服务获取。 - 输出格式值遵循 Microsoft Speech 输出格式（包括 Ogg/WebM Opus）。 - - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保障的 Opus 语音消息，请使用 OpenAI/ElevenLabs。 - - 如果配置的 Microsoft 输出格式失败，OpenClaw 会使用 MP3 重试。 + - Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要有保证的 Opus 语音消息，请使用 OpenAI/ElevenLabs。 + - 如果配置的 Microsoft 输出格式失败，OpenClaw 会重试使用 MP3。 -OpenAI/ElevenLabs 输出格式会按渠道固定（见上文）。 +OpenAI/ElevenLabs 的输出格式按渠道固定（见上文）。 ## 自动 TTS 行为 启用后，OpenClaw 会： - 如果回复已包含媒体或 `MEDIA:` 指令，则跳过 TTS。 -- 跳过过短的回复（少于 10 个字符）。 -- 在启用时，使用 `agents.defaults.model.primary`（或 `summaryModel`）为长回复生成摘要。 +- 跳过非常短的回复（少于 10 个字符）。 +- 如果启用，会使用 `agents.defaults.model.primary`（或 `summaryModel`）对较长回复进行摘要。 - 将生成的音频附加到回复中。 如果回复超过 `maxLength` 且摘要已关闭（或摘要模型没有 API 密钥），则会跳过音频，并发送普通文本回复。 @@ -383,24 +410,24 @@ OpenAI/ElevenLabs 输出格式会按渠道固定（见上文）。 ## 流程图 ``` -回复 -> 是否启用 TTS？ - 否 -> 发送文本 - 是 -> 是否有媒体 / MEDIA: / 内容过短？ - 是 -> 发送文本 - 否 -> 长度 > 限制？ - 否 -> TTS -> 附加音频 - 是 -> 是否启用摘要？ - 否 -> 发送文本 - 是 -> 生成摘要（summaryModel 或 agents.defaults.model.primary） - -> TTS -> 附加音频 +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 ``` ## Slash 命令用法 只有一个命令：`/tts`。 -启用详情请参见 [Slash 命令](/zh-CN/tools/slash-commands)。 +启用详情见 [Slash 命令](/zh-CN/tools/slash-commands)。 -Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在那里注册 `/voice` 作为原生命令。文本形式的 `/tts ...` 仍然可用。 +Discord 说明：`/tts` 是 Discord 内置命令，因此 OpenClaw 会在那里将 `/voice` 注册为原生命令。文本形式的 `/tts ...` 仍然可用。 ``` /tts off @@ -414,22 +441,22 @@ Discord 说明：`/tts` 是 Discord 的内置命令，因此 OpenClaw 会在那 说明： -- 命令要求发送者已获授权（允许列表/owner 规则仍然适用）。 +- 命令需要授权发送者（allowlist/owner 规则仍然适用）。 - 必须启用 `commands.text` 或原生命令注册。 - 配置 `messages.tts.auto` 接受 `off|always|inbound|tagged`。 - `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会将其写为 `off`。 -- 如果你想使用 `inbound` 或 `tagged` 作为默认值，请使用配置。 +- 如果你想使用 `inbound` 或 `tagged` 默认值，请使用配置。 - `limit` 和 `summary` 存储在本地偏好中，而不是主配置中。 -- `/tts audio` 会生成一次性音频回复（不会将 TTS 切换为开启）。 +- `/tts audio` 会生成一次性音频回复（不会切换 TTS 为开启状态）。 - `/tts status` 包含最近一次尝试的回退可见性： - - 成功回退：`Fallback: -> ` 加上 `Attempts: ...` - - 失败：`Error: ...` 加上 `Attempts: ...` + - 成功回退：`Fallback: -> ` 加 `Attempts: ...` + - 失败：`Error: ...` 加 `Attempts: ...` - 详细诊断：`Attempt details: provider:outcome(reasonCode) latency` - OpenAI 和 ElevenLabs API 失败现在会包含已解析的提供商错误详情和请求 id（如果提供商返回），这些信息会显示在 TTS 错误/日志中。 ## 智能体工具 -`tts` 工具可将文本转换为语音，并返回一个用于回复投递的音频附件。当渠道是 Feishu、Matrix、Telegram 或 WhatsApp 时，音频会作为语音消息而不是文件附件发送。 +`tts` 工具可将文本转换为语音，并返回用于回复投递的音频附件。当渠道是 Feishu、Matrix、Telegram 或 WhatsApp 时，音频会作为语音消息而不是文件附件发送。 ## Gateway 网关 RPC