openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-01 22:06:55 +00:00
parent e1895a9870
commit 249bf36895
2 changed files with 383 additions and 461 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

341
docs/zh-CN/providers/openai.md
View File

@ -1,102 +1,84 @@
---
read_when:
- 你想在 OpenClaw 中使用 OpenAI 模型
- 你想使用 Codex 订阅身份验证，而不是 API 密钥
- 你想使用 Codex 订阅认证，而不是 API 密钥
- 你需要更严格的 GPT-5 智能体执行行为
summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI
title: OpenAI
x-i18n:
generated_at: "2026-04-30T13:51:17Z"
generated_at: "2026-05-01T22:04:13Z"
model: gpt-5.5
provider: openai
source_hash: 7e113f2418f82a8859f208f85efb55114bda7bc17beeb28f012b19e861609dad
source_hash: bd9a8f05d31800354307c6fd7beb8cd1eed3d234e5c1e939e895cd99658b540b
source_path: providers/openai.md
workflow: 16
---
OpenAI 为 GPT 模型提供开发者 API，而 Codex 也可通过 OpenAI 的 Codex 客户端作为
ChatGPT 套餐中的编码智能体使用。OpenClaw 将这些
表面保持分离，让配置保持可预测。
OpenAI 为 GPT 模型提供开发者 API，Codex 也可以通过 OpenAI 的 Codex 客户端作为 ChatGPT 计划中的编码智能体使用。OpenClaw 将这些表面分开，确保配置保持可预测。
OpenClaw 支持三条 OpenAI 系列路由。模型前缀会选择
提供商/认证路由；单独的运行时设置会选择由谁执行
嵌入式 Agent loop：
OpenClaw 支持三种 OpenAI 系列路由。模型前缀会选择提供商/认证路由；单独的运行时设置会选择由谁执行嵌入式 Agent loop：
- **API key** — 使用按量计费的直接 OpenAI Platform 访问（`openai/*` 模型）
- **通过 PI 使用 Codex 订阅** — 使用订阅访问权限登录 ChatGPT/Codex（`openai-codex/*` 模型）
- **API key** — 通过用量计费直接访问 OpenAI Platform（`openai/*` 模型）
- **通过 PI 使用 Codex 订阅** — 使用订阅访问权限进行 ChatGPT/Codex 登录（`openai-codex/*` 模型）
- **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型加 `agents.defaults.agentRuntime.id: "codex"`）
OpenAI 明确支持在 OpenClaw 等外部工具和工作流中使用订阅 OAuth。
提供商、模型、运行时和渠道是分离的层。如果这些标签
被混在一起，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，再
更改配置。
提供商、模型、运行时和渠道是彼此独立的层。如果这些标签被混在一起，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，再更改配置。
## 快速选择
| 目标 | 使用 | 说明 |
| --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
| 直接 API key 计费 | `openai/gpt-5.5` | 设置 `OPENAI_API_KEY` 或运行 OpenAI API key 新手引导。 |
| 通过 ChatGPT/Codex 订阅认证使用 GPT-5.5 | `openai-codex/gpt-5.5` | Codex OAuth 的默认 PI 路由。订阅设置的首选。 |
| 通过原生 Codex app-server 行为使用 GPT-5.5 | `openai/gpt-5.5` 加 `agentRuntime.id: "codex"` | 为该模型引用强制使用 Codex app-server harness。 |
| 图像生成或编辑 | `openai/gpt-image-2` | 可与 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 搭配使用。 |
| 透明背景图像 | `openai/gpt-image-1.5` | 使用 `outputFormat=png` 或 `webp` 以及 `openai.background=transparent`。 |
| 直接 API key 计费 | `openai/gpt-5.5` | 设置 `OPENAI_API_KEY` 或运行 OpenAI API key 新手引导。 |
| 使用 ChatGPT/Codex 订阅认证的 GPT-5.5 | `openai-codex/gpt-5.5` | Codex OAuth 的默认 PI 路由。订阅设置的首选项。 |
| 使用原生 Codex app-server 行为的 GPT-5.5 | `openai/gpt-5.5` 加 `agentRuntime.id: "codex"` | 为该模型引用强制使用 Codex app-server harness。 |
| 图像生成或编辑 | `openai/gpt-image-2` | 可使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth。 |
| 透明背景图像 | `openai/gpt-image-1.5` | 使用 `outputFormat=png` 或 `webp`，并设置 `openai.background=transparent`。 |
## 命名映射
这些名称相似，但不可互换：
| 你看到的名称 | 层 | 含义 |
| 你看到的名称 | 层级 | 含义 |
| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `openai` | 提供商前缀 | 直接 OpenAI Platform API 路由。 |
| `openai-codex` | 提供商前缀 | 通过普通 OpenClaw PI runner 使用的 OpenAI Codex OAuth/订阅路由。 |
| `codex` 插件 | 插件 | 内置 OpenClaw 插件，提供原生 Codex app-server 运行时和 `/codex` 聊天控制。 |
| `agentRuntime.id: codex` | 智能体运行时 | 为嵌入式轮次强制使用原生 Codex app-server harness。 |
| `/codex ...` | 聊天命令集 | 在对话中绑定/控制 Codex app-server 线程。 |
| `runtime: "acp", agentId: "codex"` | ACP 会话路由 | 通过 ACP/acpx 运行 Codex 的显式回退路径。 |
| `openai` | 提供商前缀 | 直接 OpenAI Platform API 路由。 |
| `openai-codex` | 提供商前缀 | 通过常规 OpenClaw PI 运行器使用的 OpenAI Codex OAuth/订阅路由。 |
| `codex` 插件 | 插件 | OpenClaw 内置插件，提供原生 Codex app-server 运行时和 `/codex` 聊天控制。 |
| `agentRuntime.id: codex` | 智能体运行时 | 为嵌入式轮次强制使用原生 Codex app-server harness。 |
| `/codex ...` | 聊天命令集 | 从对话中绑定/控制 Codex app-server 线程。 |
| `runtime: "acp", agentId: "codex"` | ACP 会话路由 | 通过 ACP/acpx 运行 Codex 的显式回退路径。 |
这意味着一个配置可以有意同时包含 `openai-codex/*` 和
`codex` 插件。当你希望通过 PI 使用 Codex OAuth，同时也希望
原生 `/codex` 聊天控制可用时，这是有效的。`openclaw doctor` 会对这个
组合发出警告，方便你确认这是有意设置；它不会重写它。
这意味着配置可以有意同时包含 `openai-codex/*` 和 `codex` 插件。当你既想通过 PI 使用 Codex OAuth，又想让原生 `/codex` 聊天控制可用时，这是有效的。`openclaw doctor` 会对该组合发出警告，以便你确认这是有意设置；它不会重写该配置。
<Note>
GPT-5.5 可通过直接 OpenAI Platform API key 访问和
订阅/OAuth 路由使用。将 `openai/gpt-5.5` 用于直接 `OPENAI_API_KEY`
流量，将 `openai-codex/gpt-5.5` 用于通过 PI 使用 Codex OAuth，或将
`openai/gpt-5.5` 与 `agentRuntime.id: "codex"` 搭配，用于原生 Codex
app-server harness。
GPT-5.5 可通过直接 OpenAI Platform API key 访问和订阅/OAuth 路由使用。直接 `OPENAI_API_KEY` 流量使用 `openai/gpt-5.5`，通过 PI 的 Codex OAuth 使用 `openai-codex/gpt-5.5`，原生 Codex app-server harness 使用带有 `agentRuntime.id: "codex"` 的 `openai/gpt-5.5`。
</Note>
<Note>
启用 OpenAI 插件，或选择 `openai-codex/*` 模型，并不会
启用内置 Codex app-server 插件。OpenClaw 只会在你通过
`agentRuntime.id: "codex"` 显式选择原生 Codex harness，或使用旧版 `codex/*` 模型引用时
启用该插件。
如果内置 `codex` 插件已启用，但 `openai-codex/*` 仍通过 PI 解析，
`openclaw doctor` 会发出警告并保持路由不变。
启用 OpenAI 插件，或选择 `openai-codex/*` 模型，并不会启用内置 Codex app-server 插件。只有在你通过 `agentRuntime.id: "codex"` 显式选择原生 Codex harness，或使用旧版 `codex/*` 模型引用时，OpenClaw 才会启用该插件。
如果内置 `codex` 插件已启用，但 `openai-codex/*` 仍通过 PI 解析，`openclaw doctor` 会发出警告并保持路由不变。
</Note>
## OpenClaw 功能覆盖范围
## OpenClaw 功能覆盖
| OpenAI 能力 | OpenClaw 表面 | Status |
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
| 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
| Codex 订阅模型 | 使用 `openai-codex` OAuth 的 `openai-codex/<model>` | 是 |
| Codex app-server harness | 使用 `agentRuntime.id: codex` 的 `openai/<model>` | 是 |
| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，当已启用 Web 搜索且未固定提供商时 |
| 图像 | `image_generate` | 是 |
| 视频 | `video_generate` | 是 |
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 |
| 实时语音 | Voice Call `realtime.provider: "openai"` / Control UI Talk | 是 |
| Embeddings | 记忆 embedding 提供商 | 是 |
| OpenAI 能力 | OpenClaw 表面 | Status |
| ------------------------ | -------------------------------------------------------- | ------------------------------------------------------ |
| 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
| Codex 订阅模型 | 使用 `openai-codex` OAuth 的 `openai-codex/<model>` | 是 |
| Codex app-server harness | 使用 `agentRuntime.id: codex` 的 `openai/<model>` | 是 |
| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定提供商时 |
| 图像 | `image_generate` | 是 |
| 视频 | `video_generate` | 是 |
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 |
| 实时语音 | Voice Call `realtime.provider: "openai"` / Control UI Talk | 是 |
| Embeddings | 记忆嵌入提供商 | 是 |
## 记忆 embeddings
## 记忆嵌入
OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的 embedding 端点，为
`memory_search` 索引和查询 embeddings 提供支持：
OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为 `memory_search` 索引和查询嵌入提供支持：
```json5
{
@ -111,19 +93,15 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的 embedding 端点，为
}
```
对于需要非对称 embedding 标签的 OpenAI 兼容端点，请在
`memorySearch` 下设置 `queryInputType` 和 `documentInputType`。OpenClaw 会将
它们作为提供商特定的 `input_type` 请求字段转发：查询 embeddings 使用
`queryInputType`；已索引的记忆块和批量索引使用
`documentInputType`。完整示例见 [记忆配置参考](/zh-CN/reference/memory-config#provider-specific-config)。
对于需要非对称嵌入标签的 OpenAI 兼容端点，请在 `memorySearch` 下设置 `queryInputType` 和 `documentInputType`。OpenClaw 会将它们作为提供商特定的 `input_type` 请求字段转发：查询嵌入使用 `queryInputType`；已索引的记忆分块和批量索引使用 `documentInputType`。完整示例请参阅 [记忆配置参考](/zh-CN/reference/memory-config#provider-specific-config)。
## 入门指南
选择你偏好的认证方法并按照设置步骤操作。
选择你偏好的认证方法，并按照设置步骤操作。
<Tabs>
<Tab title="API key（OpenAI Platform）">
**最适合：** 直接 API 访问和按量计费。
**最适合：** 直接 API 访问和按用量计费。
<Steps>
<Step title="获取你的 API key">
@ -134,7 +112,7 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的 embedding 端点，为
openclaw onboard --auth-choice openai-api-key
```
或直接传入该 key：
或者直接传入 key：
```bash
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
@ -149,16 +127,14 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的 embedding 端点，为
### 路由摘要
| 模型引用 | 运行时配置 | 路由 | 认证 |
| ---------------------- | -------------------------- | --------------------------- | ---------------- |
| `openai/gpt-5.5` | 省略 / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.4-mini` | 省略 / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server |
| 模型引用 | 运行时配置 | 路由 | 认证 |
| ---------------------- | ---------------------------------- | -------------------------- | ---------------- |
| `openai/gpt-5.5` | 省略 / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.4-mini` | 省略 / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server |
<Note>
除非你显式强制使用 Codex app-server harness，否则 `openai/*` 是直接 OpenAI API key 路由。将 `openai-codex/*` 用于通过
默认 PI runner 使用 Codex OAuth，或将 `openai/gpt-5.5` 与
`agentRuntime.id: "codex"` 搭配，用于原生 Codex app-server 执行。
`openai/*` 是直接 OpenAI API key 路由，除非你显式强制使用 Codex app-server harness。通过默认 PI 运行器的 Codex OAuth 使用 `openai-codex/*`，或使用带有 `agentRuntime.id: "codex"` 的 `openai/gpt-5.5` 进行原生 Codex app-server 执行。
</Note>
### 配置示例
@ -191,7 +167,7 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的 embedding 端点，为
openclaw models auth login --provider openai-codex
```
对于无头环境或不适合回调的设置，添加 `--device-code`，使用 ChatGPT 设备码流程登录，而不是 localhost 浏览器回调：
对于无头或不适合回调的设置，请添加 `--device-code`，使用 ChatGPT 设备代码流程登录，而不是 localhost 浏览器回调：
```bash
openclaw models auth login --provider openai-codex --device-code
@ -213,15 +189,13 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的 embedding 端点，为
| 模型引用 | 运行时配置 | 路由 | 认证 |
|-----------|----------------|-------|------|
| `openai-codex/gpt-5.5` | 省略 / `runtime: "pi"` | 通过 PI 使用 ChatGPT/Codex OAuth | Codex 登录 |
| `openai-codex/gpt-5.4-mini` | 省略 / `runtime: "pi"` | 通过 PI 使用 ChatGPT/Codex OAuth | Codex 登录 |
| `openai-codex/gpt-5.5` | `runtime: "auto"` | 仍为 PI，除非某个插件显式声明 `openai-codex` | Codex 登录 |
| `openai-codex/gpt-5.5` | 省略 / `runtime: "pi"` | 通过 PI 的 ChatGPT/Codex OAuth | Codex 登录 |
| `openai-codex/gpt-5.4-mini` | 省略 / `runtime: "pi"` | 通过 PI 的 ChatGPT/Codex OAuth | Codex 登录 |
| `openai-codex/gpt-5.5` | `runtime: "auto"` | 仍然是 PI，除非插件显式声明 `openai-codex` | Codex 登录 |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server 认证 |
<Note>
继续使用 `openai-codex` 提供商 ID 执行认证/配置文件命令。
`openai-codex/*` 模型前缀也是 Codex OAuth 的显式 PI 路由。
它不会选择或自动启用内置 Codex app-server harness。
继续使用 `openai-codex` 提供商 id 来执行认证/配置文件命令。`openai-codex/*` 模型前缀也是 Codex OAuth 的显式 PI 路由。它不会选择或自动启用内置 Codex app-server harness。
</Note>
### 配置示例
@ -233,33 +207,31 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的 embedding 端点，为
```
<Note>
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录，OpenClaw 会在自己的智能体认证存储中管理生成的凭证。
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备代码流程登录，OpenClaw 会在自己的智能体认证存储中管理生成的凭证。
</Note>
### Status 指示器
聊天中的 `/status` 会显示当前会话正在使用哪个模型运行时。
默认 PI 运行框架显示为 `Runtime: OpenClaw Pi Default`。选择内置的 Codex app-server harness 时，`/status` 会显示
`Runtime: OpenAI Codex`。现有会话会保留其记录的 harness id，因此如果你希望 `/status` 反映新的 PI/Codex 选择，请在更改 `agentRuntime` 后使用
聊天中的 `/status` 会显示当前会话激活的是哪个模型运行时。
默认 Pi harness 显示为 `Runtime: OpenClaw Pi Default`。当选择内置 Codex app-server harness 时，`/status` 会显示
`Runtime: OpenAI Codex`。现有会话会保留其记录的 harness id，因此如果你希望 `/status` 反映新的 Pi/Codex 选择，请在更改 `agentRuntime` 后使用
`/new` 或 `/reset`。
### Doctor 警告
如果启用了内置的 `codex` 插件，同时选择了此标签页的
`openai-codex/*` 路由，`openclaw doctor` 会警告该模型仍然通过 PI 解析。当这是预期的订阅凭证路由时，请保持配置不变。只有在你希望使用原生 Codex
app-server 执行时，才切换到 `openai/<model>` 加
如果在选择此标签页的 `openai-codex/*` 路由时启用了内置 `codex` 插件，`openclaw doctor` 会警告该模型仍会通过 PI 解析。当这就是预期的订阅凭证路由时，请保持配置不变。只有在你想要原生 Codex app-server 执行时，才切换到 `openai/<model>` 加
`agentRuntime.id: "codex"`。
### 上下文窗口上限
OpenClaw 将模型元数据和运行时上下文上限视为独立值。
OpenClaw 将模型元数据和运行时上下文上限视为两个独立值。
对于通过 Codex OAuth 使用的 `openai-codex/gpt-5.5`：
- 原生 `contextWindow`：`1000000`
- 默认运行时 `contextTokens` 上限：`272000`
实践中，较小的默认上限具有更好的延迟和质量特征。使用 `contextTokens` 覆盖它：
实践中，较小的默认上限在延迟和质量特性上表现更好。可使用 `contextTokens` 覆盖它：
```json5
{
@ -279,7 +251,7 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的 embedding 端点，为
### 目录恢复
当上游 Codex 目录元数据中存在 `gpt-5.5` 时，OpenClaw 会使用它。如果实时 Codex 发现遗漏了 `openai-codex/gpt-5.5` 行，但账户已通过凭证验证，OpenClaw 会合成该 OAuth 模型行，使 cron、子智能体和已配置的默认模型运行不会因
当上游 Codex 目录元数据中存在 `gpt-5.5` 时，OpenClaw 会使用它。如果账号已完成凭证验证，但实时 Codex 发现结果省略了 `openai-codex/gpt-5.5` 这一行，OpenClaw 会合成该 OAuth 模型行，以免 cron、子智能体和已配置默认模型的运行因
`Unknown model` 而失败。
</Tab>
@ -288,28 +260,29 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的 embedding 端点，为
## 原生 Codex app-server 凭证
原生 Codex app-server harness 使用 `openai/*` 模型引用加
`agentRuntime.id: "codex"`，但其凭证仍然基于账户。OpenClaw 按以下顺序选择凭证：
`agentRuntime.id: "codex"`，但其凭证仍基于账号。OpenClaw 会按以下顺序选择凭证：
1. 绑定到智能体的显式 OpenClaw `openai-codex` 凭证配置文件。
2. app-server 的现有账户，例如本地 Codex CLI ChatGPT 登录。
3. 仅对于本地 stdio app-server 启动，当 app-server 报告无账户但仍需要 OpenAI 凭证时，依次使用 `CODEX_API_KEY`、`OPENAI_API_KEY`。
1. 绑定到该智能体的显式 OpenClaw `openai-codex` 凭证配置。
2. app-server 的现有账号，例如本地 Codex CLI ChatGPT 登录。
3. 仅对于本地 stdio app-server 启动，当 app-server 报告没有账号但仍需要 OpenAI 凭证时，先使用 `CODEX_API_KEY`，再使用
`OPENAI_API_KEY`。
这意味着本地 ChatGPT/Codex 订阅登录不会仅仅因为 Gateway 网关进程也为直接 OpenAI 模型或嵌入设置了 `OPENAI_API_KEY` 而被替换。环境变量 API key 回退仅适用于本地 stdio 无账户路径；它不会发送到 WebSocket app-server 连接。选择订阅式 Codex 配置文件时，OpenClaw 还会避免将 `CODEX_API_KEY` 和 `OPENAI_API_KEY` 传入派生的 stdio app-server 子进程，并通过 app-server 登录 RPC 发送所选凭证。
这意味着本地 ChatGPT/Codex 订阅登录不会仅仅因为 gateway 进程也为直接 OpenAI 模型或嵌入设置了 `OPENAI_API_KEY` 就被替换。环境变量 API key 回退仅适用于本地 stdio 无账号路径；它不会发送到 WebSocket app-server 连接。当选择订阅式 Codex 配置时，OpenClaw 还会避免将 `CODEX_API_KEY` 和 `OPENAI_API_KEY` 传入派生出的 stdio app-server 子进程，并会通过 app-server login RPC 发送所选凭证。
## 图像生成
内置的 `openai` 插件通过 `image_generate` 工具注册图像生成。
它通过相同的 `openai/gpt-image-2` 模型引用，同时支持 OpenAI API key 图像生成和 Codex OAuth 图像生成。
内置 `openai` 插件通过 `image_generate` 工具注册图像生成。
它通过同一个 `openai/gpt-image-2` 模型引用，同时支持 OpenAI API key 图像生成和 Codex OAuth 图像生成。
| 能力 | OpenAI API key | Codex OAuth |
| ------------------------- | ---------------------------------- | ------------------------------------ |
| 模型引用 | `openai/gpt-image-2` | `openai/gpt-image-2` |
| 凭证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 |
| 传输协议 | OpenAI Images API | Codex Responses 后端 |
| 每次请求的最大图像数 | 4 | 4 |
| 每次请求最大图像数 | 4 | 4 |
| 编辑模式 | 已启用（最多 5 张参考图像） | 已启用（最多 5 张参考图像） |
| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 |
| 宽高比 / 分辨率 | 不转发到 OpenAI Images API | 安全时映射到受支持的尺寸 |
| 宽高比 / 分辨率 | 不会转发给 OpenAI Images API | 安全时映射为受支持的尺寸 |
```json5
{
@ -325,13 +298,13 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的 embedding 端点，为
参阅[图像生成](/zh-CN/tools/image-generation)，了解共享工具参数、提供商选择和故障转移行为。
</Note>
`gpt-image-2` 是 OpenAI 文本到图像生成和图像编辑的默认模型。`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可用作显式模型覆盖。透明背景 PNG/WebP 输出请使用 `openai/gpt-image-1.5`；当前 `gpt-image-2` API 会拒绝
`gpt-image-2` 是 OpenAI 文本生成图像和图像编辑的默认模型。`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可作为显式模型覆盖使用。请使用 `openai/gpt-image-1.5` 输出透明背景 PNG/WebP；当前 `gpt-image-2` API 会拒绝
`background: "transparent"`。
对于透明背景请求，智能体应调用 `image_generate`，并设置
`model: "openai/gpt-image-1.5"`、`outputFormat: "png"` 或 `"webp"`，以及
`background: "transparent"`；较旧的 `openai.background` 提供商选项仍被接受。OpenClaw 还会保护公开 OpenAI 和
OpenAI Codex OAuth 路由，将默认的 `openai/gpt-image-2` 透明请求重写为 `gpt-image-1.5`；Azure 和自定义 OpenAI 兼容端点会保留其已配置的部署/模型名称。
`background: "transparent"`；旧的 `openai.background` 提供商选项仍会被接受。OpenClaw 还会保护公开 OpenAI 和
OpenAI Codex OAuth 路由，将默认 `openai/gpt-image-2` 透明请求重写为 `gpt-image-1.5`；Azure 和自定义 OpenAI 兼容端点会保留其已配置的部署/模型名称。
同一设置也暴露给无头 CLI 运行：
@ -347,9 +320,10 @@ openclaw infer image generate \
从输入文件开始时，请对 `openclaw infer image edit` 使用相同的 `--output-format` 和 `--background` 标志。
`--openai-background` 仍可作为 OpenAI 专用别名使用。
对于 Codex OAuth 安装，请保持相同的 `openai/gpt-image-2` 引用。配置 `openai-codex` OAuth 配置文件后，OpenClaw 会解析该已存储的 OAuth 访问令牌，并通过 Codex Responses 后端发送图像请求。对于该请求，它不会先尝试 `OPENAI_API_KEY`，也不会静默回退到 API key。若你希望改用直接 OpenAI Images API 路由，请使用 API key、自定义基础 URL 或 Azure 端点显式配置 `models.providers.openai`。
如果该自定义图像端点位于受信任的 LAN/私有地址，还请设置
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；除非存在此选择加入设置，否则 OpenClaw 会继续阻止私有/内部 OpenAI 兼容图像端点。
对于 Codex OAuth 安装，请保持同一个 `openai/gpt-image-2` 引用。当配置了
`openai-codex` OAuth 配置时，OpenClaw 会解析已存储的 OAuth 访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试 `OPENAI_API_KEY`，也不会针对该请求静默回退到 API key。当你想改用直接 OpenAI Images API 路由时，请使用 API key、自定义基础 URL 或 Azure 端点显式配置 `models.providers.openai`。
如果该自定义图像端点位于受信任的 LAN/私有地址，还需要设置
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；除非存在此显式选择加入，否则 OpenClaw 会继续阻止私有/内部 OpenAI 兼容图像端点。
生成：
@ -371,15 +345,15 @@ openclaw infer image generate \
## 视频生成
内置的 `openai` 插件通过 `video_generate` 工具注册视频生成。
内置 `openai` 插件通过 `video_generate` 工具注册视频生成。
| 能力 | 值 |
| ---------------- | --------------------------------------------------------------------------------- |
| 默认模型 | `openai/sora-2` |
| 模式 | 文本到视频、图像到视频、单视频编辑 |
| 模式 | 文本生成视频、图像生成视频、单视频编辑 |
| 参考输入 | 1 张图像或 1 个视频 |
| 尺寸覆盖 | 支持 |
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略并显示工具警告 |
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并发出工具警告 |
```json5
{
@ -395,19 +369,19 @@ openclaw infer image generate \
参阅[视频生成](/zh-CN/tools/video-generation)，了解共享工具参数、提供商选择和故障转移行为。
</Note>
## GPT-5 提示贡献
## GPT-5 prompt 贡献
OpenClaw 会为跨提供商的 GPT-5 系列运行添加共享 GPT-5 提示贡献。它按模型 id 应用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 和其他兼容的 GPT-5 引用都会收到相同的覆盖。较旧的 GPT-4.x 模型不会收到。
OpenClaw 会为跨提供商的 GPT-5 系列运行添加共享 GPT-5 prompt 贡献。它按模型 id 应用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 和其他兼容 GPT-5 引用都会收到相同叠加。较旧的 GPT-4.x 模型不会收到。
内置的原生 Codex harness 会通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和 Heartbeat 覆盖，因此通过 `agentRuntime.id: "codex"` 强制运行的 `openai/gpt-5.x` 会话，即使 Codex 拥有其余 harness 提示，也会保留相同的跟进执行和主动 Heartbeat 指引。
内置原生 Codex harness 通过 Codex app-server developer instructions 使用相同的 GPT-5 行为和 Heartbeat 叠加，因此强制通过 `agentRuntime.id: "codex"` 运行的 `openai/gpt-5.x` 会话，即便 harness prompt 的其余部分由 Codex 拥有，也会保留相同的跟进和主动 Heartbeat 指引。
GPT-5 贡献会添加带标签的行为契约，涵盖人格持久性、执行安全、工具纪律、输出形态、完成检查和验证。渠道特定的回复和静默消息行为保留在共享 OpenClaw 系统提示和出站投递策略中。GPT-5 指引始终为匹配模型启用。友好的交互风格层是独立且可配置的。
GPT-5 贡献会添加带标签的行为契约，涵盖 persona 持久性、执行安全、工具纪律、输出形态、完成检查和验证。特定渠道的回复和静默消息行为仍保留在共享 OpenClaw 系统 prompt 和出站投递策略中。GPT-5 指引始终会为匹配模型启用。友好交互风格层是独立且可配置的。
| 值 | 效果 |
| ---------------------- | ---------------------------- |
| `"friendly"`（默认） | 启用友好交互风格层 |
| `"on"` | `"friendly"` 的别名 |
| `"off"` | 仅禁用友好风格层 |
| 值 | 效果 |
| ---------------------- | ----------------------------------------- |
| `"friendly"`（默认） | 启用友好交互风格层 |
| `"on"` | `"friendly"` 的别名 |
| `"off"` | 仅禁用友好风格层 |
<Tabs>
<Tab title="配置">
@ -431,31 +405,34 @@ GPT-5 贡献会添加带标签的行为契约，涵盖人格持久性、执行
</Tabs>
<Tip>
这些值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
运行时值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
</Tip>
<Note>
当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 设置时，仍会读取旧版 `plugins.entries.openai.config.personality` 作为兼容性回退。
当未设置共享 `agents.defaults.promptOverlays.gpt5.personality` 设置时，旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退读取。
</Note>
## 语音和语音识别
## 语音与语音识别
<AccordionGroup>
<Accordion title="语音合成（TTS）">
内置的 `openai` 插件为 `messages.tts` 表面注册语音合成。
内置 `openai` 插件为 `messages.tts` 表面注册语音合成。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
| 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
| 语音 | `messages.tts.providers.openai.voice` | `coral` |
| 速度 | `messages.tts.providers.openai.speed` | （未设置） |
| 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） |
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音备注为 `opus`，文件为 `mp3` |
| 速度 | `messages.tts.providers.openai.speed` |（未设置）|
| 指令 | `messages.tts.providers.openai.instructions` |（未设置，仅 `gpt-4o-mini-tts`）|
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音便条为 `opus`，文件为 `mp3` |
| API key | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` |
| 基础 URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
| 额外正文 | `messages.tts.providers.openai.extraBody` / `extra_body` |（未设置）|
可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用语音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。
`extraBody` 会在 OpenClaw 生成的字段之后合并到 `/audio/speech` 请求 JSON 中，因此可将它用于需要额外键（例如 `lang`）的 OpenAI 兼容端点。原型键会被忽略。
```json5
{
messages: {
@ -475,14 +452,14 @@ GPT-5 贡献会添加带标签的行为契约，涵盖人格持久性、执行
</Accordion>
<Accordion title="语音转文本">
内置的 `openai` 插件通过 OpenClaw 的媒体理解转录表面注册批量语音转文本。
内置 `openai` 插件通过 OpenClaw 的媒体理解转写表面注册批量语音转文本。
- 默认模型：`gpt-4o-transcribe`
- 端点：OpenAI REST `/v1/audio/transcriptions`
- 输入路径：multipart 音频文件上传
- 只要入站音频转录使用 `tools.media.audio`，OpenClaw 都支持该功能，包括 Discord 语音频道片段和渠道音频附件
- 只要入站音频转录使用 `tools.media.audio`，OpenClaw 都支持此功能，包括 Discord 语音渠道片段和渠道音频附件
要强制对入站音频转录使用 OpenAI：
如需强制对入站音频转录使用 OpenAI：
```json5
{
@ -502,12 +479,12 @@ GPT-5 贡献会添加带标签的行为契约，涵盖人格持久性、执行
}
```
当共享音频媒体配置或单次转录请求提供语言和提示词提示时，它们会转发给 OpenAI。
当共享音频媒体配置或每次调用的转录请求提供语言和提示词提示时，它们会被转发给 OpenAI。
</Accordion>
<Accordion title="实时转录">
内置的 `openai` 插件会为语音通话插件注册实时转录。
内置的 `openai` 插件会为 Voice Call 插件注册实时转录。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
@ -519,13 +496,13 @@ GPT-5 贡献会添加带标签的行为契约，涵盖人格持久性、执行
| API key | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
<Note>
使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，并使用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这个流式提供商用于语音通话的实时转录路径；Discord 语音目前会录制短片段，并改用批处理 `tools.media.audio` 转录路径。
使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，并使用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。此流式提供商用于 Voice Call 的实时转录路径；Discord 语音目前会录制短片段，并改用批处理 `tools.media.audio` 转录路径。
</Note>
</Accordion>
<Accordion title="实时语音">
内置的 `openai` 插件会为语音通话插件注册实时语音。
内置的 `openai` 插件会为 Voice Call 插件注册实时语音。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
@ -537,11 +514,11 @@ GPT-5 贡献会添加带标签的行为契约，涵盖人格持久性、执行
| API key | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
<Note>
通过 `azureEndpoint` 和 `azureDeployment` 配置键支持用于后端实时桥接的 Azure OpenAI。支持双向工具调用。使用 G.711 u-law 音频格式。
通过 `azureEndpoint` 和 `azureDeployment` 配置键支持 Azure OpenAI，用于后端实时桥接。支持双向工具调用。使用 G.711 u-law 音频格式。
</Note>
<Note>
Control UI Talk 使用 OpenAI 浏览器实时会话，其中包含由 Gateway 网关签发的临时客户端密钥，并让浏览器直接通过 WebRTC SDP 与 OpenAI Realtime API 交换。维护者可使用 `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 进行实时验证；OpenAI 这一段会在 Node 中签发客户端密钥，使用虚拟麦克风媒体生成浏览器 SDP offer，将其发送到 OpenAI，并在不记录密钥的情况下应用 SDP answer。
Control UI Talk 使用 OpenAI 浏览器实时会话，其中包含由 Gateway 网关签发的临时客户端密钥，并通过浏览器直接与 OpenAI Realtime API 进行 WebRTC SDP 交换。维护者可以使用 `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 进行实时验证；OpenAI 这一路会在 Node 中签发客户端密钥，使用虚拟麦克风媒体生成浏览器 SDP offer，将其发布到 OpenAI，并应用 SDP answer，且不会记录密钥。
</Note>
</Accordion>
@ -549,13 +526,13 @@ GPT-5 贡献会添加带标签的行为契约，涵盖人格持久性、执行
## Azure OpenAI 端点
内置的 `openai` provider 可以通过覆盖基础 URL，将图像生成目标指向 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换到 Azure 的请求格式。
内置的 `openai` provider 可以通过覆盖基准 URL，将图像生成指向 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换为 Azure 的请求形态。
<Note>
实时语音使用单独的配置路径（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），不受 `models.providers.openai.baseUrl` 影响。请参阅 [语音与语音合成](#voice-and-speech) 下的 **实时语音** 折叠项了解其 Azure 设置。
实时语音使用单独的配置路径（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），不受 `models.providers.openai.baseUrl` 影响。有关其 Azure 设置，请参阅 [语音和语音合成](#voice-and-speech) 下的**实时语音**折叠项。
</Note>
在以下情况使用 Azure OpenAI：
在以下情况下使用 Azure OpenAI：
- 你已经有 Azure OpenAI 订阅、配额或企业协议
- 你需要 Azure 提供的区域数据驻留或合规控制
@ -563,7 +540,7 @@ GPT-5 贡献会添加带标签的行为契约，涵盖人格持久性、执行
### 配置
要通过内置的 `openai` provider 使用 Azure 图像生成，请将 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 Azure OpenAI 密钥（不是 OpenAI Platform 密钥）：
如需通过内置 `openai` provider 使用 Azure 图像生成，请将 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 Azure OpenAI key（不是 OpenAI Platform key）：
```json5
{
@ -578,7 +555,7 @@ GPT-5 贡献会添加带标签的行为契约，涵盖人格持久性、执行
}
```
OpenClaw 会为 Azure 图像生成路由识别这些 Azure 主机后缀：
OpenClaw 会为 Azure 图像生成路由识别以下 Azure 主机后缀：
- `*.openai.azure.com`
- `*.services.ai.azure.com`
@ -587,31 +564,31 @@ OpenClaw 会为 Azure 图像生成路由识别这些 Azure 主机后缀：
对于识别出的 Azure 主机上的图像生成请求，OpenClaw 会：
- 发送 `api-key` 标头，而不是 `Authorization: Bearer`
- 使用按部署限定范围的路径（`/openai/deployments/{deployment}/...`）
- 向每个请求追加 `?api-version=...`
- 对 Azure 图像生成调用使用 600 秒的默认请求超时。单次调用的 `timeoutMs` 值仍会覆盖此默认值。
- 使用按部署限定的路径（`/openai/deployments/{deployment}/...`）
- 为每个请求追加 `?api-version=...`
- 对 Azure 图像生成调用使用 600 秒的默认请求超时。每次调用的 `timeoutMs` 值仍会覆盖此默认值。
其他基础 URL（公共 OpenAI、兼容 OpenAI 的代理）会保留标准 OpenAI 图像请求格式。
其他基准 URL（公共 OpenAI、OpenAI 兼容代理）会保留标准 OpenAI 图像请求形态。
<Note>
`openai` provider 图像生成路径的 Azure 路由需要 OpenClaw 2026.4.22 或更高版本。早期版本会把任何自定义 `openai.baseUrl` 当作公共 OpenAI 端点处理，并且在访问 Azure 图像部署时失败。
`openai` provider 的图像生成路径上的 Azure 路由需要 OpenClaw 2026.4.22 或更高版本。更早版本会像处理公共 OpenAI 端点一样处理任何自定义 `openai.baseUrl`，因此会在 Azure 图像部署上失败。
</Note>
### API 版本
设置 `AZURE_OPENAI_API_VERSION`，为 Azure 图像生成路径固定特定的 Azure 预览版或正式版：
设置 `AZURE_OPENAI_API_VERSION`，为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本：
```bash
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
```
未设置该变量时，默认值为 `2024-12-01-preview`。
当未设置该变量时，默认值为 `2024-12-01-preview`。
### 模型名称就是部署名称
Azure OpenAI 会将模型绑定到部署。对于通过内置 `openai` provider 路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure 部署名称**，而不是公共 OpenAI 模型 ID。
如果你创建了名为 `gpt-image-2-prod` 的部署，用来提供 `gpt-image-2`：
如果你创建了名为 `gpt-image-2-prod`、用于提供 `gpt-image-2` 服务的部署：
```
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
@ -621,33 +598,33 @@ Azure OpenAI 会将模型绑定到部署。对于通过内置 `openai` provider
### 区域可用性
Azure 图像生成目前仅在部分区域可用（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、`uaenorth`）。在创建部署之前，请查看 Microsoft 当前的区域列表，并确认你的区域提供该具体模型。
Azure 图像生成目前仅在部分区域可用（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、`uaenorth`）。创建部署前，请查看 Microsoft 当前的区域列表，并确认你的区域提供了特定模型。
### 参数差异
Azure OpenAI 和公共 OpenAI 并不总是接受相同的图像参数。Azure 可能会拒绝公共 OpenAI 允许的选项（例如 `gpt-image-2` 上的某些 `background` 值），或仅在特定模型版本上公开这些选项。这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 Azure 门户中检查你的具体部署和 API 版本支持的参数集。
<Note>
Azure OpenAI 使用原生传输和兼容行为，但不会收到 OpenClaw 的隐藏归因标头 — 请参阅 [高级配置](#advanced-configuration) 下的 **原生与兼容 OpenAI 的路由** 折叠项。
Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐藏归因标头 — 请参阅 [高级配置](#advanced-configuration) 下的**原生路由与 OpenAI 兼容路由**折叠项。
对于 Azure 上的聊天或 Responses 流量（图像生成以外），请使用新手引导流程或专用 Azure provider 配置 — 仅设置 `openai.baseUrl` 不会套用 Azure API/认证格式。存在一个单独的 `azure-openai-responses/*` provider；请参阅下方的服务端压缩折叠项。
对于 Azure 上的聊天或 Responses 流量（图像生成之外），请使用新手引导流程或专用 Azure provider 配置；仅设置 `openai.baseUrl` 不会启用 Azure API/认证形态。存在单独的 `azure-openai-responses/*` provider；请参阅下方的服务端压缩折叠项。
</Note>
## 高级配置
<AccordionGroup>
<Accordion title="传输（WebSocket 与 SSE）">
OpenClaw 对 `openai/*` 和 `openai-codex/*` 都优先使用 WebSocket，并带有 SSE 回退（`"auto"`）。
OpenClaw 对 `openai/*` 和 `openai-codex/*` 都优先使用 WebSocket，并以 SSE 作为回退（`"auto"`）。
在 `"auto"` 模式下，OpenClaw：
在 `"auto"` 模式下，OpenClaw 会：
- 在回退到 SSE 之前重试一次早期 WebSocket 失败
- 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
- 为重试和重新连接附加稳定的会话与轮次身份标头
- 在不同传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`）
- 为重试和重连附加稳定的会话与轮次身份标头
- 在传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`）
| 值 | 行为 |
|-------|----------|
| `"auto"`（默认） | 优先 WebSocket，回退到 SSE |
| `"auto"`（默认） | 优先 WebSocket，SSE 回退 |
| `"sse"` | 仅强制使用 SSE |
| `"websocket"` | 仅强制使用 WebSocket |
@ -675,10 +652,10 @@ Azure OpenAI 使用原生传输和兼容行为，但不会收到 OpenClaw 的隐
</Accordion>
<Accordion title="WebSocket 预热">
OpenClaw 默认为 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以降低首轮延迟。
OpenClaw 默认为 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以降低第一轮延迟。
```json5
// 禁用预热
// Disable warm-up
{
agents: {
defaults: {
@ -695,12 +672,12 @@ Azure OpenAI 使用原生传输和兼容行为，但不会收到 OpenClaw 的隐
</Accordion>
<Accordion title="快速模式">
OpenClaw 为 `openai/*` 和 `openai-codex/*` 暴露共享的快速模式开关：
OpenClaw 为 `openai/*` 和 `openai-codex/*` 公开共享的快速模式开关：
- **聊天/UI：** `/fast status|on|off`
- **配置：** `agents.defaults.models["<provider>/<model>"].params.fastMode`
启用后，OpenClaw 会将快速模式映射到 OpenAI 优先级处理（`service_tier = "priority"`）。现有 `service_tier` 值会保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。
启用后，OpenClaw 会将快速模式映射到 OpenAI 优先处理（`service_tier = "priority"`）。现有 `service_tier` 值会被保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。
```json5
{
@ -715,13 +692,13 @@ Azure OpenAI 使用原生传输和兼容行为，但不会收到 OpenClaw 的隐
```
<Note>
会话覆盖优先于配置。在会话 UI 中清除会话覆盖后，该会话会回到配置的默认值。
会话覆盖优先于配置。在会话 UI 中清除会话覆盖后，会话会回到已配置的默认值。
</Note>
</Accordion>
<Accordion title="优先级处理（service_tier）">
OpenAI 的 API 通过 `service_tier` 暴露优先级处理。在 OpenClaw 中按模型设置它：
<Accordion title="优先处理（service_tier）">
OpenAI 的 API 通过 `service_tier` 公开优先处理。在 OpenClaw 中按模型设置：
```json5
{
@ -738,23 +715,23 @@ Azure OpenAI 使用原生传输和兼容行为，但不会收到 OpenClaw 的隐
支持的值：`auto`、`default`、`flex`、`priority`。
<Warning>
`serviceTier` 只会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一 provider，OpenClaw 会保持 `service_tier` 不变。
`serviceTier` 只会转发给原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一 provider，OpenClaw 会保持 `service_tier` 不变。
</Warning>
</Accordion>
<Accordion title="服务端压缩（Responses API）">
对于直接的 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi harness 流包装器会自动启用服务端压缩：
对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi harness 流包装器会自动启用服务端压缩：
- 强制 `store: true`（除非模型兼容性设置 `supportsStore: false`）
- 强制 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
- 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`）
这适用于内置 Pi harness 路径，也适用于嵌入式运行使用的 OpenAI provider 钩子。原生 Codex 应用服务器 harness 通过 Codex 管理自己的上下文，并使用 `agents.defaults.agentRuntime.id` 单独配置。
这适用于内置 Pi harness 路径，以及嵌入式运行使用的 OpenAI provider 钩子。原生 Codex 应用服务器 harness 会通过 Codex 管理自己的上下文，并使用 `agents.defaults.agentRuntime.id` 单独配置。
<Tabs>
<Tab title="显式启用">
对兼容端点（如 Azure OpenAI Responses）有用：
适用于 Azure OpenAI Responses 等兼容端点：
```json5
{
@ -806,13 +783,13 @@ Azure OpenAI 使用原生传输和兼容行为，但不会收到 OpenClaw 的隐
</Tabs>
<Note>
`responsesServerCompaction` 仅控制 `context_management` 注入。直接的 OpenAI Responses 模型仍会强制使用 `store: true`，除非 compat 设置了 `supportsStore: false`。
`responsesServerCompaction` 仅控制 `context_management` 注入。直连 OpenAI Responses 模型仍会强制使用 `store: true`，除非兼容层设置 `supportsStore: false`。
</Note>
</Accordion>
<Accordion title="严格智能体式 GPT 模式">
对于在 `openai/*` 上运行的 GPT-5 系列，OpenClaw 可以使用更严格的嵌入式执行契约：
对于 `openai/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行契约：
```json5
{
@ -825,10 +802,10 @@ Azure OpenAI 使用原生传输和兼容行为，但不会收到 OpenClaw 的隐
```
使用 `strict-agentic` 时，OpenClaw：
- 当工具操作可用时，不再将仅有计划的轮次视为成功推进
- 使用立即行动 steer 重试该轮次
- 对实质性工作自动启用 `update_plan`
- 如果模型持续规划而不行动，则显示明确的阻塞状态
- 当工具操作可用时，不再将仅规划的回合视为成功进展
- 使用立即行动的 steer 重试该回合
- 为实质性工作自动启用 `update_plan`
- 如果模型持续规划而不行动，则显示明确的受阻状态
<Note>
仅限 OpenAI 和 Codex GPT-5 系列运行。其他提供商和较旧的模型系列保持默认行为。
@ -837,23 +814,23 @@ Azure OpenAI 使用原生传输和兼容行为，但不会收到 OpenClaw 的隐
</Accordion>
<Accordion title="原生路由与 OpenAI 兼容路由">
OpenClaw 对直接 OpenAI、Codex 和 Azure OpenAI 端点的处理不同于通用 OpenAI 兼容 `/v1` 代理：
OpenClaw 对直连 OpenAI、Codex 和 Azure OpenAI 端点的处理不同于通用 OpenAI 兼容 `/v1` 代理：
**原生路由**（`openai/*`、Azure OpenAI）：
- 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
- 对拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用的推理
- 对拒绝 `reasoning.effort: "none"` 的模型或代理省略已禁用的 reasoning
- 默认将工具 schema 设为严格模式
- 仅在已验证的原生主机上附加隐藏归因标头
- 保留仅限 OpenAI 的请求整形（`service_tier`、`store`、reasoning-compat、prompt-cache 提示）
- 保留仅适用于 OpenAI 的请求整形（`service_tier`、`store`、reasoning 兼容、prompt-cache 提示）
**代理/兼容路由：**
- 使用更宽松的 compat 行为
- 从非原生 `openai-completions` 载荷中移除 Completions `store`
- 接受用于 OpenAI 兼容 Completions 代理的高级 `params.extra_body`/`params.extraBody` 透传 JSON
- 接受用于 OpenAI 兼容 Completions 代理（例如 vLLM）的 `params.chat_template_kwargs`
- 不强制使用严格工具 schema 或仅限原生的标头
- 使用更宽松的兼容行为
- 从非原生 `openai-completions` payload 中剥离 Completions `store`
- 接受高级 `params.extra_body`/`params.extraBody` 透传 JSON，用于 OpenAI 兼容的 Completions 代理
- 接受 `params.chat_template_kwargs`，用于 vLLM 等 OpenAI 兼容的 Completions 代理
- 不强制使用严格工具 schema 或仅原生标头
Azure OpenAI 使用原生传输和 compat 行为，但不会收到隐藏归因标头。
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因标头。
</Accordion>
</AccordionGroup>

503
docs/zh-CN/tools/tts.md
View File

@ -1,34 +1,30 @@
---
read_when:
- 为回复启用文本转语音
- 配置 TTS 提供商、回退链或 persona
- 使用 `/tts` 命令或指令
- 为回复启用文本转语音功能
- 配置 TTS 提供商、回退链或角色设定
- 使用 /tts 命令或指令
sidebarTitle: Text to speech (TTS)
summary: 用于出站回复的文本转语音 —— 提供商、persona、斜杠命令和每渠道输出
summary: 出站回复的文本转语音 —— 提供商、角色设定、斜杠命令和按渠道输出
title: 文本转语音
x-i18n:
generated_at: "2026-04-28T00:34:21Z"
model: gpt-5.4
generated_at: "2026-05-01T22:04:15Z"
model: gpt-5.5
provider: openai
source_hash: ec58d19fbca0ff0cd9828f32c150123cad22f053a6b4281ed40ec3d1fa41d1b2
source_hash: 8ff736249314fcfbc4f61c24a9c005c02e3582e2aa5fe0baac7e99c5e00f15e1
source_path: tools/tts.md
workflow: 15
workflow: 16
---
OpenClaw 可以通过 **14 种语音提供商**将出站回复转换为音频，
并在 Feishu、Matrix、Telegram 和 WhatsApp 上发送原生语音消息，
在其他地方发送音频附件，以及为电话和 Talk 提供 PCM/Ulaw 流。
OpenClaw 可以通过 **14 个语音提供商**将出站回复转换为音频，并在 Feishu、Matrix、Telegram 和 WhatsApp 上发送原生语音消息，在其他位置发送音频附件，并为电话和 Talk 提供 PCM/Ulaw 流。
## 快速开始
<Steps>
<Step title="选择提供商">
OpenAI 和 ElevenLabs 是最可靠的托管选项。Microsoft 和
Local CLI 无需 API 密钥即可使用。完整列表请参阅[提供商矩阵](#supported-providers)。
OpenAI 和 ElevenLabs 是最可靠的托管选项。Microsoft 和本地 CLI 无需 API key 即可使用。完整列表请参阅[提供商矩阵](#supported-providers)。
</Step>
<Step title="设置 API 密钥">
为你的提供商导出环境变量（例如 `OPENAI_API_KEY`、
`ELEVENLABS_API_KEY`）。Microsoft 和 Local CLI 不需要密钥。
<Step title="设置 API key">
导出你的提供商所需的环境变量（例如 `OPENAI_API_KEY`、`ELEVENLABS_API_KEY`）。Microsoft 和本地 CLI 不需要密钥。
</Step>
<Step title="在配置中启用">
设置 `messages.tts.auto: "always"` 和 `messages.tts.provider`：
@ -46,53 +42,43 @@ OpenClaw 可以通过 **14 种语音提供商**将出站回复转换为音频，
</Step>
<Step title="在聊天中试用">
`/tts status` 会显示当前状态。`/tts audio Hello from OpenClaw`
会发送一次性的音频回复。
`/tts status` 会显示当前状态。`/tts audio Hello from OpenClaw` 会发送一次性音频回复。
</Step>
</Steps>
<Note>
默认情况下，自动 TTS **关闭**。当未设置 `messages.tts.provider` 时，
OpenClaw 会按照注册表自动选择顺序选取第一个已配置的提供商。
默认情况下，自动 TTS 为**关闭**。当未设置 `messages.tts.provider` 时，OpenClaw 会按注册表自动选择顺序选取第一个已配置的提供商。
</Note>
## 支持的提供商
| 提供商 | 认证 | 说明 |
| 提供商 | 认证 | 备注 |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| **Azure Speech** | `AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION`（也支持 `AZURE_SPEECH_API_KEY`、`SPEECH_KEY`、`SPEECH_REGION`） | 原生 Ogg/Opus 语音便笺输出和电话支持。 |
| **DeepInfra** | `DEEPINFRA_API_KEY` | 与 OpenAI 兼容的 TTS。默认使用 `hexgrad/Kokoro-82M`。 |
| **ElevenLabs** | `ELEVENLABS_API_KEY` 或 `XI_API_KEY` | 支持语音克隆、多语言，并可通过 `seed` 实现确定性。 |
| **Google Gemini** | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | Gemini API TTS；通过 `promptTemplate: "audio-profile-v1"` 支持 persona 感知。 |
| **Gradium** | `GRADIUM_API_KEY` | 支持语音便笺和电话输出。 |
| **Inworld** | `INWORLD_API_KEY` | 流式 TTS API。支持原生 Opus 语音便笺和 PCM 电话。 |
| **Local CLI** | none | 运行已配置的本地 TTS 命令。 |
| **Microsoft** | none | 通过 `node-edge-tts` 使用公开的 Edge 神经 TTS。尽力而为，不提供 SLA。 |
| **MiniMax** | `MINIMAX_API_KEY`（或 Token Plan：`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`） | T2A v2 API。默认使用 `speech-2.8-hd`。 |
| **OpenAI** | `OPENAI_API_KEY` | 也用于自动摘要；支持 persona `instructions`。 |
| **OpenRouter** | `OPENROUTER_API_KEY`（可复用 `models.providers.openrouter.apiKey`） | 默认模型为 `hexgrad/kokoro-82m`。 |
| **Volcengine** | `VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`（旧版 AppID/token：`VOLCENGINE_TTS_APPID`/`_TOKEN`） | BytePlus Seed Speech HTTP API。 |
| **Vydra** | `VYDRA_API_KEY` | 共享的图片、视频和语音提供商。 |
| **xAI** | `XAI_API_KEY` | xAI 批量 TTS。**不**支持原生 Opus 语音便笺。 |
| **Xiaomi MiMo** | `XIAOMI_API_KEY` | 通过 Xiaomi 聊天补全提供 MiMo TTS。 |
| **Azure Speech** | `AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION`（也支持 `AZURE_SPEECH_API_KEY`、`SPEECH_KEY`、`SPEECH_REGION`） | 原生 Ogg/Opus 语音消息输出和电话。 |
| **DeepInfra** | `DEEPINFRA_API_KEY` | 兼容 OpenAI 的 TTS。默认使用 `hexgrad/Kokoro-82M`。 |
| **ElevenLabs** | `ELEVENLABS_API_KEY` 或 `XI_API_KEY` | 语音克隆、多语言，并可通过 `seed` 实现确定性输出。 |
| **Google Gemini** | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` | Gemini API TTS；可通过 `promptTemplate: "audio-profile-v1"` 感知 persona。 |
| **Gradium** | `GRADIUM_API_KEY` | 语音消息和电话输出。 |
| **Inworld** | `INWORLD_API_KEY` | 流式 TTS API。原生 Opus 语音消息和 PCM 电话。 |
| **本地 CLI** | 无 | 运行已配置的本地 TTS 命令。 |
| **Microsoft** | 无 | 通过 `node-edge-tts` 使用公开的 Edge 神经网络 TTS。尽力而为，无 SLA。 |
| **MiniMax** | `MINIMAX_API_KEY`（或 Token Plan：`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`） | T2A v2 API。默认使用 `speech-2.8-hd`。 |
| **OpenAI** | `OPENAI_API_KEY` | 也用于自动摘要；支持 persona `instructions`。 |
| **OpenRouter** | `OPENROUTER_API_KEY`（可复用 `models.providers.openrouter.apiKey`） | 默认模型为 `hexgrad/kokoro-82m`。 |
| **Volcengine** | `VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`（旧版 AppID/token：`VOLCENGINE_TTS_APPID`/`_TOKEN`） | BytePlus Seed Speech HTTP API。 |
| **Vydra** | `VYDRA_API_KEY` | 共享的图像、视频和语音提供商。 |
| **xAI** | `XAI_API_KEY` | xAI 批量 TTS。**不**支持原生 Opus 语音消息。 |
| **Xiaomi MiMo** | `XIAOMI_API_KEY` | 通过 Xiaomi 聊天补全使用 MiMo TTS。 |
如果配置了多个提供商，则会优先使用当前选中的提供商，
其他提供商将作为回退选项。自动摘要使用 `summaryModel`（或
`agents.defaults.model.primary`），因此如果你保留摘要启用状态，
对应提供商也必须完成认证。
如果配置了多个提供商，会优先使用所选提供商，其他提供商作为回退选项。自动摘要使用 `summaryModel`（或 `agents.defaults.model.primary`），因此如果你保持摘要启用，该提供商也必须完成认证。
<Warning>
内置的 **Microsoft** 提供商通过 `node-edge-tts` 使用 Microsoft Edge 的在线神经 TTS
服务。它是一个公开的网络服务，没有公开的
SLA 或配额 —— 请将其视为尽力而为。旧版提供商 id `edge` 会被
规范化为 `microsoft`，并且 `openclaw doctor --fix` 会重写已持久化的
配置；新配置应始终使用 `microsoft`。
内置的 **Microsoft** 提供商通过 `node-edge-tts` 使用 Microsoft Edge 的在线神经 TTS 服务。它是一个公开 Web 服务，没有已发布的 SLA 或配额，请将其视为尽力而为。旧版提供商 ID `edge` 会被规范化为 `microsoft`，并且 `openclaw doctor --fix` 会重写已持久化的配置；新配置应始终使用 `microsoft`。
</Warning>
## 配置
TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择一个
预设并调整对应的提供商块：
TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择一个预设，并调整提供商块：
<Tabs>
<Tab title="Azure Speech">
@ -148,8 +134,8 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
apiKey: "${GEMINI_API_KEY}",
model: "gemini-3.1-flash-tts-preview",
voiceName: "Kore",
// 可选的自然语言风格提示：
// audioProfile: "请用平静、播客主持人的语气说话。",
// Optional natural-language style prompts:
// audioProfile: "Speak in a calm, podcast-host tone.",
// speakerName: "Alex",
},
},
@ -370,9 +356,9 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
</Tab>
</Tabs>
### 每个智能体的语音覆盖
### 按智能体设置的语音覆盖
当某个智能体需要使用不同的提供商、语音、模型、persona 或自动 TTS 模式时，请使用 `agents.list[].tts`。智能体块会在 `messages.tts` 之上执行深度合并，因此提供商凭证可以保留在全局提供商配置中：
当某个智能体应使用不同的提供商、语音、模型、角色或自动 TTS 模式发声时，请使用 `agents.list[].tts`。该智能体块会深度合并到 `messages.tts` 之上，因此提供商凭据可以保留在全局提供商配置中：
```json5
{
@ -400,23 +386,18 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
}
```
如果要为某个智能体固定 persona，请在提供商
配置旁设置 `agents.list[].tts.persona` —— 它只会覆盖该智能体的全局 `messages.tts.persona`。
要固定按智能体设置的角色，请在提供商配置旁边设置 `agents.list[].tts.persona`，它只会为该智能体覆盖全局 `messages.tts.persona`。
自动回复、`/tts audio`、`/tts status` 以及
`tts` 智能体工具的优先级顺序如下：
自动回复、`/tts audio`、`/tts status` 和 `tts` 智能体工具的优先级顺序：
1. `messages.tts`
2. 当前激活的 `agents.list[].tts`
3. 渠道覆盖（当该渠道支持 `channels.<channel>.tts` 时）
4. 账户覆盖（当渠道传入 `channels.<channel>.accounts.<id>.tts` 时）
5. 此主机上的本地 `/tts` 偏好设置
6. 启用[模型覆盖](#model-driven-directives)时的内联 `[[tts:...]]` 指令
2. 活跃的 `agents.list[].tts`
3. 渠道覆盖，当渠道支持 `channels.<channel>.tts` 时
4. 账号覆盖，当渠道传入 `channels.<channel>.accounts.<id>.tts` 时
5. 此主机的本地 `/tts` 偏好设置
6. 启用[模型驱动指令](#model-driven-directives)时的内联 `[[tts:...]]` 指令
渠道和账户覆盖使用与 `messages.tts` 相同的结构，并会在前面各层之上执行
深度合并，因此共享的提供商凭证可以保留在
`messages.tts` 中，而渠道或机器人账户只修改语音、模型、persona
或自动模式：
渠道和账号覆盖项使用与 `messages.tts` 相同的结构，并在更早的层之上进行深度合并，因此共享的提供商凭证可以保留在 `messages.tts` 中，而某个渠道或机器人账号只更改语音、模型、人格或自动模式：
```json5
{
@ -444,13 +425,11 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
}
```
## Persona
## 人格
**persona** 是一种稳定的语音身份，可以在不同提供商之间以确定性的方式
应用。它可以偏好某个提供商，定义与提供商无关的提示意图，并携带
与提供商相关的语音、模型、提示模板、seed 和语音设置绑定。
**人格**是一种稳定的语音身份，可以跨提供商确定性地应用。它可以偏好某个提供商，定义与提供商无关的提示意图，并携带特定于提供商的语音、模型、提示模板、种子和语音设置绑定。
### 最小 persona
### 最小人格
```json5
{
@ -472,7 +451,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
}
```
### 完整 persona（与提供商无关的提示）
### 完整人格（与提供商无关的提示）
```json5
{
@ -483,17 +462,17 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
personas: {
alfred: {
label: "Alfred",
description: "冷淡中带温度的英式管家旁白。",
description: "Dry, warm British butler narrator.",
provider: "google",
fallbackPolicy: "preserve-persona",
prompt: {
profile: "一位聪明绝顶的英式管家。冷峻、机智、温暖、迷人、情感丰富，绝不平淡。",
scene: "安静的深夜书房。为受信任的操作者进行近距离麦克风旁白。",
sampleContext: "说话者正在以简洁、自信且略带冷幽默的温暖语气回答一个私密的技术请求。",
style: "精致、克制、带一点若有若无的调侃。",
accent: "英式英语。",
pacing: "节奏从容，带短促的戏剧性停顿。",
constraints: ["不要把配置值直接读出来。", "不要解释这个 persona。"],
profile: "A brilliant British butler. Dry, witty, warm, charming, emotionally expressive, never generic.",
scene: "A quiet late-night study. Close-mic narration for a trusted operator.",
sampleContext: "The speaker is answering a private technical request with concise confidence and dry warmth.",
style: "Refined, understated, lightly amused.",
accent: "British English.",
pacing: "Measured, with short dramatic pauses.",
constraints: ["Do not read configuration values aloud.", "Do not explain the persona."],
},
providers: {
google: {
@ -522,101 +501,81 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
}
```
### Persona 解析
### 人格解析
当前激活的 persona 会以确定性方式进行选择：
活动人格会确定性地选择：
1. 如果已设置，则使用本地偏好 `/tts persona <id>`。
2. 如果已设置，则使用 `messages.tts.persona`。
3. 不使用 persona。
1. `/tts persona <id>` 本地偏好设置（如果已设置）。
2. `messages.tts.persona`（如果已设置）。
3. 无人格。
提供商选择遵循“显式优先”的顺序：
提供商选择按显式优先运行：
1. 直接覆盖（CLI、Gateway 网关、Talk、允许的 TTS 指令）。
2. 本地偏好 `/tts provider <id>`。
3. 当前 persona 的 `provider`。
2. `/tts provider <id>` 本地偏好设置。
3. 活动人格的 `provider`。
4. `messages.tts.provider`。
5. 注册表自动选择。
对于每次提供商尝试，OpenClaw 按以下顺序合并配置：
对于每次提供商尝试，OpenClaw 会按以下顺序合并配置：
1. `messages.tts.providers.<id>`
2. `messages.tts.personas.<persona>.providers.<id>`
3. 可信请求覆盖
4. 允许的模型发出的 TTS 指令覆盖
3. 受信任请求覆盖项
4. 允许的模型发出 TTS 指令覆盖项
### 提供商如何使用 persona 提示
### 提供商如何使用人格提示
Persona 提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent`、
`pacing`、`constraints`）是**与提供商无关**的。每个提供商自行决定如何
使用它们：
人格提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent`、`pacing`、`constraints`）是**与提供商无关**的。每个提供商会决定如何使用它们：
<AccordionGroup>
<Accordion title="Google Gemini">
仅当生效中的 Google 提供商配置设置了 `promptTemplate: "audio-profile-v1"`
或 `personaPrompt` 时，才会将 persona 提示字段包装为 Gemini TTS 提示结构。
较旧的 `audioProfile` 和 `speakerName` 字段
仍会作为 Google 专用提示文本预置添加。在 `[[tts:text]]` 块内部的
行内音频标签，如 `[whispers]` 或 `[laughs]`，
会保留在 Gemini 转录中；OpenClaw 不会生成这些标签。
仅当有效的 Google 提供商配置设置了 `promptTemplate: "audio-profile-v1"` 或 `personaPrompt` 时，才会将人格提示字段包装进 Gemini TTS 提示结构中。较早的 `audioProfile` 和 `speakerName` 字段仍会作为 Google 专用提示文本前置。`[[tts:text]]` 块内的 `[whispers]` 或 `[laughs]` 等内联音频标签会保留在 Gemini 转录文本中；OpenClaw 不会生成这些标签。
</Accordion>
<Accordion title="OpenAI">
仅当未显式配置 OpenAI `instructions` 时，
才会将 persona 提示字段映射到请求的 `instructions` 字段。
显式的 `instructions` 始终优先。
仅当未配置显式 OpenAI `instructions` 时，才会将人格提示字段映射到请求的 `instructions` 字段。显式 `instructions` 始终优先。
</Accordion>
<Accordion title="Other providers">
仅使用 `personas.<id>.providers.<provider>` 下
与提供商相关的 persona 绑定。除非该提供商实现了自己的
persona 提示映射，否则 persona 提示字段会被忽略。
<Accordion title="其他提供商">
只使用 `personas.<id>.providers.<provider>` 下特定于提供商的人格绑定。人格提示字段会被忽略，除非该提供商实现了自己的“人格提示”映射。
</Accordion>
</AccordionGroup>
### 回退策略
当某个 persona 对当前尝试的提供商**没有绑定**时，`fallbackPolicy` 用于控制行为：
当人格对尝试的提供商**没有绑定**时，`fallbackPolicy` 控制行为：
| 策略 | 行为 |
| 策略 | 行为 |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `preserve-persona` | **默认值。** 与提供商无关的提示字段仍然可用；提供商可以使用它们，也可以忽略它们。 |
| `provider-defaults` | 在本次尝试的提示准备中省略 persona；提供商使用自己的中性默认值，同时仍继续回退到其他提供商。 |
| `fail` | 跳过该提供商尝试，并使用 `reasonCode: "not_configured"` 和 `personaBinding: "missing"`。仍会继续尝试回退提供商。 |
| `preserve-persona` | **默认值。** 与提供商无关的提示字段保持可用；提供商可以使用它们，也可以忽略它们。 |
| `provider-defaults` | 该次尝试的提示准备会省略人格；提供商使用其中性默认值，同时继续回退到其他提供商。 |
| `fail` | 使用 `reasonCode: "not_configured"` 和 `personaBinding: "missing"` 跳过该提供商尝试。仍会尝试回退提供商。 |
只有当**所有**尝试的提供商都被跳过
或失败时，整个 TTS 请求才会失败。
只有在**每个**尝试的提供商都被跳过或失败时，整个 TTS 请求才会失败。
## 模型驱动的指令
## 模型驱动指令
默认情况下，助手**可以**发出 `[[tts:...]]` 指令，为单条回复覆盖
语音、模型或速度，还可以附带一个可选的
`[[tts:text]]...[[/tts:text]]` 块，用于表达只应出现在
音频中的提示：
默认情况下，助手**可以**发出 `[[tts:...]]` 指令，为单次回复覆盖语音、模型或语速，还可以附加一个可选的 `[[tts:text]]...[[/tts:text]]` 块，用于只应出现在音频中的表现力提示：
```text
给你。
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]]
```
当 `messages.tts.auto` 为 `"tagged"` 时，**必须使用指令**
才能触发音频。即使指令被拆分在相邻块中，流式分块传输在渠道看到文本之前
也会从可见文本中剥离这些指令。
当 `messages.tts.auto` 为 `"tagged"` 时，**必须有指令**才会触发音频。流式分块交付会在渠道看到文本之前从可见文本中剥离指令，即使这些指令被拆分到相邻块中也是如此。
除非设置了 `modelOverrides.allowProvider: true`，否则 `provider=...` 会被忽略。当某条
回复声明 `provider=...` 时，该指令中的其他键只会由该提供商解析；
不受支持的键会被剥离，并作为 TTS
指令警告上报。
除非 `modelOverrides.allowProvider: true`，否则会忽略 `provider=...`。当回复声明 `provider=...` 时，该指令中的其他键只由该提供商解析；不支持的键会被剥离，并作为 TTS 指令警告报告。
**可用的指令键：**
**可用指令键：**
- `provider`（已注册的提供商 id；需要 `allowProvider: true`）
- `provider`（已注册的提供商 ID；需要 `allowProvider: true`）
- `voice` / `voiceName` / `voice_name` / `google_voice` / `voiceId`
- `model` / `google_model`
- `stability`、`similarityBoost`、`style`、`speed`、`useSpeakerBoost`
- `vol` / `volume`（MiniMax 音量，0–10）
- `pitch`（MiniMax 整数音高，−12 到 12；小数值会被截断）
- `emotion`（Volcengine 情感标签）
- `emotion`（Volcengine 情绪标签）
- `applyTextNormalization`（`auto|on|off`）
- `languageCode`（ISO 639-1）
- `seed`
@ -627,7 +586,7 @@ Persona 提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent
{ messages: { tts: { modelOverrides: { enabled: false } } } }
```
**允许切换提供商，同时保留其他可配置项：**
**允许切换提供商，同时保持其他旋钮可配置：**
```json5
{ messages: { tts: { modelOverrides: { enabled: true, allowProvider: true, allowSeed: false } } } }
@ -635,8 +594,7 @@ Persona 提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent
## 斜杠命令
单一命令 `/tts`。在 Discord 上，OpenClaw 还会注册 `/voice`，因为
`/tts` 是 Discord 的内置命令 —— 文本形式的 `/tts ...` 仍然可用。
单个命令 `/tts`。在 Discord 上，OpenClaw 还会注册 `/voice`，因为 `/tts` 是一个内置 Discord 命令，文本 `/tts ...` 仍然可用。
```text
/tts off | on | status
@ -650,127 +608,119 @@ Persona 提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent
```
<Note>
这些命令要求发送者已获授权（适用允许列表/所有者规则），并且
必须启用 `commands.text` 或原生命令注册。
命令需要授权发送者（适用允许列表/所有者规则），并且必须启用 `commands.text` 或原生命令注册。
</Note>
行为说明：
- `/tts on` 会将本地 TTS 偏好写为 `always`；`/tts off` 会写为 `off`。
- `/tts chat on|off|default` 会为当前聊天写入会话范围的自动 TTS 覆盖。
- `/tts persona <id>` 会写入本地 persona 偏好；`/tts persona off` 会清除它。
- `/tts latest` 会从当前会话转录中读取最新的助手回复，并将其作为一次性音频发送。它只会在会话条目上存储该回复的哈希，以抑制重复发送语音。
- `/tts audio` 会生成一次性的音频回复（**不会**切换 TTS 开关）。
- `limit` 和 `summary` 存储在**本地偏好**中，而不是主配置中。
- `/tts status` 包含最近一次尝试的回退诊断 —— `Fallback: <primary> -> <used>`、`Attempts: ...`，以及每次尝试的详情（`provider:outcome(reasonCode) latency`）。
- 启用 TTS 时，`/status` 会显示当前激活的 TTS 模式，以及已配置的提供商、模型、语音和已脱敏的自定义端点元数据。
- `/tts on` 将本地 TTS 偏好设置写为 `always`；`/tts off` 将其写为 `off`。
- `/tts chat on|off|default` 为当前聊天写入一个会话作用域的自动 TTS 覆盖项。
- `/tts persona <id>` 写入本地人格偏好设置；`/tts persona off` 会清除它。
- `/tts latest` 从当前会话转录中读取最新的助手回复，并将其作为音频发送一次。它只会在会话条目上存储该回复的哈希，以抑制重复语音发送。
- `/tts audio` 生成一次性音频回复（**不会**开启 TTS）。
- `limit` 和 `summary` 存储在**本地偏好设置**中，而不是主配置中。
- `/tts status` 包含最新尝试的回退诊断：`Fallback: <primary> -> <used>`、`Attempts: ...`，以及每次尝试的详细信息（`provider:outcome(reasonCode) latency`）。
- 启用 TTS 时，`/status` 会显示活动 TTS 模式，以及已配置的提供商、模型、语音和经过清理的自定义端点元数据。
## 每用户偏好
## 按用户偏好设置
斜杠命令会将本地覆盖写入 `prefsPath`。默认值为
`~/.openclaw/settings/tts.json`；可通过环境变量 `OPENCLAW_TTS_PREFS`
或 `messages.tts.prefsPath` 进行覆盖。
斜杠命令会将本地覆盖项写入 `prefsPath`。默认值为 `~/.openclaw/settings/tts.json`；可使用 `OPENCLAW_TTS_PREFS` 环境变量或 `messages.tts.prefsPath` 覆盖。
| 存储字段 | 效果 |
| 存储字段 | 效果 |
| ------------ | -------------------------------------------- |
| `auto` | 本地自动 TTS 覆盖（`always`、`off`，……） |
| `provider` | 本地主提供商覆盖 |
| `persona` | 本地 persona 覆盖 |
| `maxLength` | 摘要阈值（默认 `1500` 个字符） |
| `summarize` | 摘要开关（默认 `true`） |
| `auto` | 本地自动 TTS 覆盖项（`always`、`off`、…） |
| `provider` | 本地主提供商覆盖项 |
| `persona` | 本地人格覆盖项 |
| `maxLength` | 摘要阈值（默认 `1500` 个字符） |
| `summarize` | 摘要开关（默认 `true`） |
这些设置会覆盖该主机上来自 `messages.tts` 加上当前
`agents.list[].tts` 块的生效配置。
这些会覆盖来自 `messages.tts` 的有效配置，以及该主机活动的 `agents.list[].tts` 块。
## 输出格式（固定）
TTS 语音投递由渠道能力驱动。渠道插件会声明
语音风格的 TTS 是应让提供商请求原生 `voice-note` 目标，
还是保留常规 `audio-file` 合成并仅将兼容输出标记为可进行语音
投递。
TTS 语音交付由渠道能力驱动。渠道插件会声明语音风格的 TTS 是否应要求提供商提供原生 `voice-note` 目标，或保持普通 `audio-file` 合成并仅将兼容输出标记为语音交付。
- **支持语音便笺的渠道**：语音便笺回复优先使用 Opus（ElevenLabs 的 `opus_48000_64`，OpenAI 的 `opus`）。
- 48 kHz / 64 kbps 是语音消息在体积与效果之间的良好折中。
- **Feishu / WhatsApp**：当语音便笺回复生成为 MP3/WebM/WAV/M4A
或其他可能的音频文件时，渠道插件会在发送原生语音消息前使用 `ffmpeg` 将其转码为 48 kHz
的 Ogg/Opus。WhatsApp 会通过 Baileys 的 `audio` 负载并设置 `ptt: true` 和
`audio/ogg; codecs=opus` 来发送结果。如果转换失败，Feishu 会收到原始
文件作为附件；而 WhatsApp 发送会失败，而不是发布不兼容的
PTT 负载。
- **BlueBubbles**：保持提供商合成走常规 audio-file 路径；MP3
和 CAF 输出会被标记为用于 iMessage 语音备忘录投递。
- **支持语音留言的渠道**：语音留言回复优先使用 Opus（ElevenLabs 的 `opus_48000_64`，OpenAI 的 `opus`）。
- 48kHz / 64kbps 是语音消息的良好折中。
- **Feishu / WhatsApp**：当语音留言回复生成为 MP3/WebM/WAV/M4A
或其他可能的音频文件时，渠道插件会先使用 `ffmpeg` 将其转码为 48kHz
Ogg/Opus，然后再发送原生语音消息。WhatsApp 会通过 Baileys `audio`
payload 发送结果，并带有 `ptt: true` 和 `audio/ogg; codecs=opus`。如果转换失败，Feishu 会收到原始
文件作为附件；WhatsApp 发送会失败，而不是发布不兼容的
PTT payload。
- **BlueBubbles**：保持提供商合成走普通音频文件路径；MP3
和 CAF 输出会标记为 iMessage 语音备忘录投递。
- **其他渠道**：MP3（ElevenLabs 的 `mp3_44100_128`，OpenAI 的 `mp3`）。
- 44.1 kHz / 128 kbps 是语音清晰度的默认平衡点。
- **MiniMax**：常规音频附件使用 MP3（`speech-2.8-hd` 模型，32 kHz 采样率）。对于渠道声明的语音便笺目标，当渠道声明支持转码时，OpenClaw 会在投递前使用 `ffmpeg` 将 MiniMax 的 MP3 转码为 48 kHz Opus。
- **Xiaomi MiMo**：默认使用 MP3，或在配置时使用 WAV。对于渠道声明的语音便笺目标，当渠道声明支持转码时，OpenClaw 会在投递前使用 `ffmpeg` 将 Xiaomi 输出转码为 48 kHz Opus。
- **Local CLI**：使用已配置的 `outputFormat`。语音便笺目标会被
转换为 Ogg/Opus，电话输出会被转换为原始 16 kHz 单声道 PCM，
均通过 `ffmpeg` 完成。
- **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 语音便笺格式。
- 44.1kHz / 128kbps 是语音清晰度的默认平衡。
- **MiniMax**：MP3（`speech-2.8-hd` 模型，32kHz 采样率）用于普通音频附件。对于渠道声明的语音留言目标，当渠道声明支持转码时，OpenClaw 会在投递前使用 `ffmpeg` 将 MiniMax MP3 转码为 48kHz Opus。
- **Xiaomi MiMo**：默认使用 MP3，配置后也可使用 WAV。对于渠道声明的语音留言目标，当渠道声明支持转码时，OpenClaw 会在投递前使用 `ffmpeg` 将 Xiaomi 输出转码为 48kHz Opus。
- **本地 CLI**：使用配置的 `outputFormat`。语音留言目标会被
转换为 Ogg/Opus，电话输出会使用 `ffmpeg` 转换为原始 16 kHz 单声道 PCM。
- **Google Gemini**：Gemini API TTS 返回原始 24kHz PCM。OpenClaw 会将其封装为 WAV 用于音频附件，将其转码为 48kHz 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 语音留言格式。
- **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。
保证使用 Opus 语音消息，请使用 OpenAI/ElevenLabs。
- 如果配置的 Microsoft 输出格式失败，OpenClaw 会使用 MP3 重试。
OpenAI/ElevenLabs 的输出格式按渠道固定（见上文）。
OpenAI/ElevenLabs 输出格式按渠道固定（见上文）。
## 自动 TTS 行为
当启用 `messages.tts.auto` 时，OpenClaw 会：
启用 `messages.tts.auto` 时，OpenClaw 会：
- 如果回复已包含媒体或 `MEDIA:` 指令，则跳过 TTS。
- 跳过过短的回复（少于 10 个字符）。
- 当启用摘要时，使用
`summaryModel`（或 `agents.defaults.model.primary`）对长回复做摘要。
- 如果回复已经包含媒体或 `MEDIA:` 指令，则跳过 TTS。
- 跳过非常短的回复（少于 10 个字符）。
- 启用摘要时，会使用
`summaryModel`（或 `agents.defaults.model.primary`）总结长回复。
- 将生成的音频附加到回复中。
- 在 `mode: "final"` 下，仍会在文本流完成后
为流式最终回复发送仅音频的 TTS；生成的媒体会经过与常规回复附件相同的
渠道媒体规范化流程。
- 在 `mode: "final"` 中，对于流式最终回复，仍会在
文本流完成后发送仅音频 TTS；生成的媒体会通过与普通回复附件相同的
渠道媒体标准化流程。
如果回复超过 `maxLength` 且摘要已关闭（或者摘要模型没有 API 密钥），
则会跳过音频，发送普通文本回复。
如果回复超过 `maxLength` 且摘要已关闭（或摘要模型没有 API key），
则跳过音频并发送普通文本回复。
```text
回复 -> 启用 TTS？
否 -> 发送文本
是 -> 是否包含媒体 / MEDIA: / 过短？
是 -> 发送文本
否 -> 长度 > 限制？
否 -> TTS -> 附加音频
是 -> 是否启用摘要？
否 -> 发送文本
是 -> 摘要 -> 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 -> TTS -> attach audio
```
## 按渠道划分的输出格式
| 目标 | 格式 |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Feishu / Matrix / Telegram / WhatsApp | 语音便笺回复优先使用 **Opus**（ElevenLabs 的 `opus_48000_64`，OpenAI 的 `opus`）。48 kHz / 64 kbps 在清晰度和体积之间取得平衡。 |
| 其他渠道 | **MP3**（ElevenLabs 的 `mp3_44100_128`，OpenAI 的 `mp3`）。44.1 kHz / 128 kbps 是语音的默认值。 |
| Talk / 电话 | 提供商原生 **PCM**（Inworld 为 22050 Hz，Google 为 24 kHz），或用于电话的 Gradium `ulaw_8000`。 |
| 目标 | 格式 |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Feishu / Matrix / Telegram / WhatsApp | 语音消息回复优先使用 **Opus**（ElevenLabs 的 `opus_48000_64`，OpenAI 的 `opus`）。48 kHz / 64 kbps 在清晰度和大小之间取得平衡。 |
| 其他渠道 | **MP3**（ElevenLabs 的 `mp3_44100_128`，OpenAI 的 `mp3`）。44.1 kHz / 128 kbps 是语音默认值。 |
| Talk / 电话通信 | 提供商原生 **PCM**（Inworld 22050 Hz，Google 24 kHz），或 Gradium 用于电话通信的 `ulaw_8000`。 |
各提供商说明：
各提供商说明：
- **Feishu / WhatsApp 转码：** 当语音便笺回复生成为 MP3/WebM/WAV/M4A 时，渠道插件会使用 `ffmpeg` 转码为 48 kHz Ogg/Opus。WhatsApp 会通过 Baileys 并使用 `ptt: true` 和 `audio/ogg; codecs=opus` 发送。如果转换失败：Feishu 会回退为附加原始文件；WhatsApp 会发送失败，而不是发布不兼容的 PTT 负载。
- **MiniMax / Xiaomi MiMo：** 默认使用 MP3（MiniMax `speech-2.8-hd` 为 32 kHz）；对语音便笺目标会通过 `ffmpeg` 转码为 48 kHz Opus。
- **Local CLI：** 使用已配置的 `outputFormat`。语音便笺目标会转换为 Ogg/Opus，电话输出会转换为原始 16 kHz 单声道 PCM。
- **Google Gemini：** 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 用于附件，对语音便笺目标转码为 48 kHz Opus，并对 Talk/电话直接返回 PCM。
- **Inworld：** 附件使用 MP3，语音便笺使用原生 `OGG_OPUS`，Talk/电话使用 22050 Hz 的原始 `PCM`。
- **xAI：** 默认使用 MP3；`responseFormat` 可以为 `mp3|wav|pcm|mulaw|alaw`。使用 xAI 的批处理 REST 端点 —— **不**使用流式 WebSocket TTS。**不**支持原生 Opus 语音便笺格式。
- **Microsoft：** 使用 `microsoft.outputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要保证为 Opus 语音消息，请使用 OpenAI/ElevenLabs。如果配置的 Microsoft 格式失败，OpenClaw 会回退重试 MP3。
- **Feishu / WhatsApp 转码：** 当语音消息回复以 MP3/WebM/WAV/M4A 形式到达时，渠道插件会用 `ffmpeg` 转码为 48 kHz Ogg/Opus。WhatsApp 通过 Baileys 发送，并带有 `ptt: true` 和 `audio/ogg; codecs=opus`。如果转换失败：Feishu 会回退为附加原始文件；WhatsApp 发送会失败，而不是发布不兼容的 PTT 载荷。
- **MiniMax / Xiaomi MiMo：** 默认 MP3（MiniMax `speech-2.8-hd` 为 32 kHz）；通过 `ffmpeg` 为语音消息目标转码为 48 kHz Opus。
- **本地 CLI：** 使用配置的 `outputFormat`。语音消息目标会转换为 Ogg/Opus，电话通信输出会转换为原始 16 kHz 单声道 PCM。
- **Google Gemini：** 返回原始 24 kHz PCM。OpenClaw 会将其封装为 WAV 用于附件，为语音消息目标转码为 48 kHz Opus，并为 Talk/电话通信直接返回 PCM。
- **Inworld：** MP3 附件，原生 `OGG_OPUS` 语音消息，Talk/电话通信使用原始 `PCM` 22050 Hz。
- **xAI：** 默认 MP3；`responseFormat` 可以是 `mp3|wav|pcm|mulaw|alaw`。使用 xAI 的批量 REST 端点 — **不**使用流式 WebSocket TTS。不支持原生 Opus 语音消息格式。
- **Microsoft：** 使用 `microsoft.outputFormat`（默认 `audio-24khz-48kbitrate-mono-mp3`）。Telegram `sendVoice` 接受 OGG/MP3/M4A；如果你需要保证 Opus 语音消息，请使用 OpenAI/ElevenLabs。如果配置的 Microsoft 格式失败，OpenClaw 会用 MP3 重试。
OpenAI 和 ElevenLabs 的输出格式按渠道固定，如上所列。
OpenAI 和 ElevenLabs 输出格式按上方所列为每个渠道固定。
## 字段参考
## 字段参考
<AccordionGroup>
<Accordion title="顶层 messages.tts.*">
<AccordionGroup>
<Accordion title="Top-level messages.tts.*">
<ParamField path="auto" type='"off" | "always" | "inbound" | "tagged"'>
自动 TTS 模式。`inbound` 仅在收到入站语音消息后发送音频；`tagged` 仅在回复包含 `[[tts:...]]` 指令或 `[[tts:text]]` 块时发送音频。
</ParamField>
@ -778,16 +728,16 @@ OpenAI 和 ElevenLabs 的输出格式按渠道固定，如上所列。
旧版开关。`openclaw doctor --fix` 会将其迁移到 `auto`。
</ParamField>
<ParamField path="mode" type='"final" | "all"' default="final">
`"all"` 除最终回复外，还包括工具/分块回复。
`"all"` 除最终回复外还包含工具/块回复。
</ParamField>
<ParamField path="provider" type="string">
语音提供商 id。未设置时，OpenClaw 会按注册表自动选择顺序使用第一个已配置的提供商。旧版 `provider: "edge"` 会被 `openclaw doctor --fix` 重写为 `"microsoft"`。
语音提供商 ID。未设置时，OpenClaw 会按注册表自动选择顺序使用第一个已配置的提供商。旧版 `provider: "edge"` 会由 `openclaw doctor --fix` 重写为 `"microsoft"`。
</ParamField>
<ParamField path="persona" type="string">
来自 `personas` 的当前 persona id。会被规范化为小写。
来自 `personas` 的活动 persona ID。会规范化为小写。
</ParamField>
<ParamField path="personas.<id>" type="object">
稳定的语音身份。字段包括：`label`、`description`、`provider`、`fallbackPolicy`、`prompt`、`providers.<provider>`。参见[Persona](#personas)。
稳定的口语身份。字段：`label`、`description`、`provider`、`fallbackPolicy`、`prompt`、`providers.<provider>`。参见 [Personas](#personas)。
</ParamField>
<ParamField path="summaryModel" type="string">
用于自动摘要的低成本模型；默认为 `agents.defaults.model.primary`。接受 `provider/model` 或已配置的模型别名。
@ -796,16 +746,16 @@ OpenAI 和 ElevenLabs 的输出格式按渠道固定，如上所列。
允许模型发出 TTS 指令。`enabled` 默认为 `true`；`allowProvider` 默认为 `false`。
</ParamField>
<ParamField path="providers.<id>" type="object">
由提供商拥有的设置，按语音提供商 id 键控。旧版直接块（`messages.tts.openai`、`.elevenlabs`、`.microsoft`、`.edge`）会被 `openclaw doctor --fix` 重写；只提交 `messages.tts.providers.<id>`。
由提供商拥有的设置，按语音提供商 ID 索引。旧版直接块（`messages.tts.openai`、`.elevenlabs`、`.microsoft`、`.edge`）会由 `openclaw doctor --fix` 重写；只提交 `messages.tts.providers.<id>`。
</ParamField>
<ParamField path="maxTextLength" type="number">
TTS 输入字符数的硬上限。超过时，`/tts audio` 会失败。
TTS 输入字符数的硬性上限。超过时 `/tts audio` 会失败。
</ParamField>
<ParamField path="timeoutMs" type="number">
请求超时，单位为毫秒。
请求超时时间，单位为毫秒。
</ParamField>
<ParamField path="prefsPath" type="string">
覆盖本地偏好 JSON 路径（提供商/限制/摘要）。默认值为 `~/.openclaw/settings/tts.json`。
覆盖本地偏好 JSON 路径（提供商/限制/摘要）。默认 `~/.openclaw/settings/tts.json`。
</ParamField>
</Accordion>
@ -813,69 +763,69 @@ OpenAI 和 ElevenLabs 的输出格式按渠道固定，如上所列。
<ParamField path="apiKey" type="string">环境变量：`AZURE_SPEECH_KEY`、`AZURE_SPEECH_API_KEY` 或 `SPEECH_KEY`。</ParamField>
<ParamField path="region" type="string">Azure Speech 区域（例如 `eastus`）。环境变量：`AZURE_SPEECH_REGION` 或 `SPEECH_REGION`。</ParamField>
<ParamField path="endpoint" type="string">可选的 Azure Speech 端点覆盖（别名 `baseUrl`）。</ParamField>
<ParamField path="voice" type="string">Azure 语音 ShortName。默认值为 `en-US-JennyNeural`。</ParamField>
<ParamField path="lang" type="string">SSML 语言代码。默认值为 `en-US`。</ParamField>
<ParamField path="outputFormat" type="string">用于标准音频的 Azure `X-Microsoft-OutputFormat`。默认值为 `audio-24khz-48kbitrate-mono-mp3`。</ParamField>
<ParamField path="voiceNoteOutputFormat" type="string">用于语音便笺输出的 Azure `X-Microsoft-OutputFormat`。默认值为 `ogg-24khz-16bit-mono-opus`。</ParamField>
<ParamField path="voice" type="string">Azure 语音 ShortName。默认 `en-US-JennyNeural`。</ParamField>
<ParamField path="lang" type="string">SSML 语言代码。默认 `en-US`。</ParamField>
<ParamField path="outputFormat" type="string">标准音频的 Azure `X-Microsoft-OutputFormat`。默认 `audio-24khz-48kbitrate-mono-mp3`。</ParamField>
<ParamField path="voiceNoteOutputFormat" type="string">语音消息输出的 Azure `X-Microsoft-OutputFormat`。默认 `ogg-24khz-16bit-mono-opus`。</ParamField>
</Accordion>
<Accordion title="ElevenLabs">
<ParamField path="apiKey" type="string">回退到 `ELEVENLABS_API_KEY` 或 `XI_API_KEY`。</ParamField>
<ParamField path="model" type="string">模型 id（例如 `eleven_multilingual_v2`、`eleven_v3`）。</ParamField>
<ParamField path="voiceId" type="string">ElevenLabs 语音 id。</ParamField>
<ParamField path="model" type="string">模型 ID（例如 `eleven_multilingual_v2`、`eleven_v3`）。</ParamField>
<ParamField path="voiceId" type="string">ElevenLabs 语音 ID。</ParamField>
<ParamField path="voiceSettings" type="object">
`stability`、`similarityBoost`、`style`（各自为 `0..1`）、`useSpeakerBoost`（`true|false`）、`speed`（`0.5..2.0`，`1.0` = 正常）。
`stability`、`similarityBoost`、`style`（各为 `0..1`）、`useSpeakerBoost`（`true|false`）、`speed`（`0.5..2.0`，`1.0` = 正常）。
</ParamField>
<ParamField path="applyTextNormalization" type='"auto" | "on" | "off"'>文本规范化模式。</ParamField>
<ParamField path="languageCode" type="string">2 位 ISO 639-1 代码（例如 `en`、`de`）。</ParamField>
<ParamField path="seed" type="number">整数 `0..4294967295`，用于尽力而为的确定性。</ParamField>
<ParamField path="languageCode" type="string">2 字母 ISO 639-1（例如 `en`、`de`）。</ParamField>
<ParamField path="seed" type="number">用于尽力保证确定性的整数 `0..4294967295`。</ParamField>
<ParamField path="baseUrl" type="string">覆盖 ElevenLabs API 基础 URL。</ParamField>
</Accordion>
<Accordion title="Google Gemini">
<ParamField path="apiKey" type="string">回退到 `GEMINI_API_KEY` / `GOOGLE_API_KEY`。如果省略，TTS 可以在环境变量回退之前复用 `models.providers.google.apiKey`。</ParamField>
<ParamField path="model" type="string">Gemini TTS 模型。默认值为 `gemini-3.1-flash-tts-preview`。</ParamField>
<ParamField path="voiceName" type="string">Gemini 预置语音名称。默认值为 `Kore`。别名：`voice`。</ParamField>
<ParamField path="audioProfile" type="string">会在朗读文本前添加的自然语言风格提示。</ParamField>
<ParamField path="speakerName" type="string">当你的提示使用命名说话者时，可选的说话者标签，会在朗读文本前添加。</ParamField>
<ParamField path="promptTemplate" type='"audio-profile-v1"'>设置为 `audio-profile-v1` 时，会将当前 persona 提示字段包装为确定性的 Gemini TTS 提示结构。</ParamField>
<ParamField path="personaPrompt" type="string">附加到该模板 Director's Notes 中的 Google 专用额外 persona 提示文本。</ParamField>
<ParamField path="apiKey" type="string">回退到 `GEMINI_API_KEY` / `GOOGLE_API_KEY`。如果省略，TTS 可在环境变量回退前复用 `models.providers.google.apiKey`。</ParamField>
<ParamField path="model" type="string">Gemini TTS 模型。默认 `gemini-3.1-flash-tts-preview`。</ParamField>
<ParamField path="voiceName" type="string">Gemini 预置语音名称。默认 `Kore`。别名：`voice`。</ParamField>
<ParamField path="audioProfile" type="string">在朗读文本前添加的自然语言风格提示词。</ParamField>
<ParamField path="speakerName" type="string">当你的提示词使用具名说话人时，在朗读文本前添加的可选说话人标签。</ParamField>
<ParamField path="promptTemplate" type='"audio-profile-v1"'>设置为 `audio-profile-v1`，以将活动 persona 提示词字段包装到确定性的 Gemini TTS 提示词结构中。</ParamField>
<ParamField path="personaPrompt" type="string">追加到模板 Director's Notes 的 Google 专用额外 persona 提示词文本。</ParamField>
<ParamField path="baseUrl" type="string">仅接受 `https://generativelanguage.googleapis.com`。</ParamField>
</Accordion>
<Accordion title="Gradium">
<ParamField path="apiKey" type="string">环境变量：`GRADIUM_API_KEY`。</ParamField>
<ParamField path="baseUrl" type="string">默认值为 `https://api.gradium.ai`。</ParamField>
<ParamField path="voiceId" type="string">默认使用 Emma（`YTpq7expH9539ERJ`）。</ParamField>
<ParamField path="voiceId" type="string">默认值为 Emma（`YTpq7expH9539ERJ`）。</ParamField>
</Accordion>
<Accordion title="Inworld">
<ParamField path="apiKey" type="string">环境变量：`INWORLD_API_KEY`。</ParamField>
<ParamField path="baseUrl" type="string">默认值为 `https://api.inworld.ai`。</ParamField>
<ParamField path="modelId" type="string">默认值为 `inworld-tts-1.5-max`。还支持：`inworld-tts-1.5-mini`、`inworld-tts-1-max`、`inworld-tts-1`。</ParamField>
<ParamField path="modelId" type="string">默认值为 `inworld-tts-1.5-max`。另有：`inworld-tts-1.5-mini`、`inworld-tts-1-max`、`inworld-tts-1`。</ParamField>
<ParamField path="voiceId" type="string">默认值为 `Sarah`。</ParamField>
<ParamField path="temperature" type="number">采样温度 `0..2`。</ParamField>
</Accordion>
<Accordion title="Local CLI (tts-local-cli)">
<Accordion title="本地 CLI (tts-local-cli)">
<ParamField path="command" type="string">用于 CLI TTS 的本地可执行文件或命令字符串。</ParamField>
<ParamField path="args" type="string[]">命令参数。支持 `{{Text}}`、`{{OutputPath}}`、`{{OutputDir}}`、`{{OutputBase}}` 占位符。</ParamField>
<ParamField path="outputFormat" type='"mp3" | "opus" | "wav"'>预期的 CLI 输出格式。音频附件默认使用 `mp3`。</ParamField>
<ParamField path="timeoutMs" type="number">命令超时时间，单位为毫秒。默认值为 `120000`。</ParamField>
<ParamField path="timeoutMs" type="number">命令超时时间（毫秒）。默认值为 `120000`。</ParamField>
<ParamField path="cwd" type="string">可选的命令工作目录。</ParamField>
<ParamField path="env" type="Record<string, string>">命令的可选环境变量覆盖。</ParamField>
</Accordion>
<Accordion title="Microsoft (no API key)">
<Accordion title="Microsoft（无 API key）">
<ParamField path="enabled" type="boolean" default="true">允许使用 Microsoft 语音。</ParamField>
<ParamField path="voice" type="string">Microsoft 神经语音名称（例如 `en-US-MichelleNeural`）。</ParamField>
<ParamField path="voice" type="string">Microsoft 神经网络语音名称（例如 `en-US-MichelleNeural`）。</ParamField>
<ParamField path="lang" type="string">语言代码（例如 `en-US`）。</ParamField>
<ParamField path="outputFormat" type="string">Microsoft 输出格式。默认值为 `audio-24khz-48kbitrate-mono-mp3`。内置的 Edge 支持传输并不支持所有格式。</ParamField>
<ParamField path="rate / pitch / volume" type="string">百分比字符串（例如 `+10%`、`-5%`）。</ParamField>
<ParamField path="saveSubtitles" type="boolean">在音频文件旁写入 JSON 字幕。</ParamField>
<ParamField path="proxy" type="string">Microsoft 语音请求的代理 URL。</ParamField>
<ParamField path="timeoutMs" type="number">请求超时覆盖（毫秒）。</ParamField>
<ParamField path="edge.*" type="object" deprecated>旧版别名。运行 `openclaw doctor --fix` 将持久化配置重写到 `providers.microsoft`。</ParamField>
<ParamField path="edge.*" type="object" deprecated>旧版别名。运行 `openclaw doctor --fix` 将持久化配置重写为 `providers.microsoft`。</ParamField>
</Accordion>
<Accordion title="MiniMax">
@ -890,11 +840,12 @@ OpenAI 和 ElevenLabs 的输出格式按渠道固定，如上所列。
<Accordion title="OpenAI">
<ParamField path="apiKey" type="string">回退到 `OPENAI_API_KEY`。</ParamField>
<ParamField path="model" type="string">OpenAI TTS 模型 id（例如 `gpt-4o-mini-tts`）。</ParamField>
<ParamField path="model" type="string">OpenAI TTS 模型 ID（例如 `gpt-4o-mini-tts`）。</ParamField>
<ParamField path="voice" type="string">语音名称（例如 `alloy`、`cedar`）。</ParamField>
<ParamField path="instructions" type="string">显式的 OpenAI `instructions` 字段。设置后，persona 提示字段**不会**自动映射。</ParamField>
<ParamField path="extraBody / extra_body" type="Record<string, unknown>">在生成的 OpenAI TTS 字段之后合并到 `/audio/speech` 请求正文中的额外 JSON 字段。可将其用于 OpenAI 兼容端点，例如 Kokoro，这些端点需要 `lang` 等特定于提供商的键；不安全的原型键会被忽略。</ParamField>
<ParamField path="baseUrl" type="string">
覆盖 OpenAI TTS 端点。解析顺序：配置 → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`。非默认值会被视为与 OpenAI 兼容的 TTS 端点，因此接受自定义模型和语音名称。
覆盖 OpenAI TTS 端点。解析顺序：配置 → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`。非默认值会被视为 OpenAI 兼容的 TTS 端点，因此接受自定义模型和语音名称。
</ParamField>
</Accordion>
@ -907,21 +858,21 @@ OpenAI 和 ElevenLabs 的输出格式按渠道固定，如上所列。
<ParamField path="speed" type="number">提供商原生速度覆盖。</ParamField>
</Accordion>
<Accordion title="Volcengine (BytePlus Seed Speech)">
<Accordion title="Volcengine（BytePlus Seed Speech）">
<ParamField path="apiKey" type="string">环境变量：`VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`。</ParamField>
<ParamField path="resourceId" type="string">默认值为 `seed-tts-1.0`。环境变量：`VOLCENGINE_TTS_RESOURCE_ID`。当你的项目具有 TTS 2.0 权限时，请使用 `seed-tts-2.0`。</ParamField>
<ParamField path="appKey" type="string">App key 请求头。默认值为 `aGjiRDfUWi`。环境变量：`VOLCENGINE_TTS_APP_KEY`。</ParamField>
<ParamField path="resourceId" type="string">默认值为 `seed-tts-1.0`。环境变量：`VOLCENGINE_TTS_RESOURCE_ID`。当你的项目拥有 TTS 2.0 权益时，使用 `seed-tts-2.0`。</ParamField>
<ParamField path="appKey" type="string">应用密钥头。默认值为 `aGjiRDfUWi`。环境变量：`VOLCENGINE_TTS_APP_KEY`。</ParamField>
<ParamField path="baseUrl" type="string">覆盖 Seed Speech TTS HTTP 端点。环境变量：`VOLCENGINE_TTS_BASE_URL`。</ParamField>
<ParamField path="voice" type="string">语音类型。默认值为 `en_female_anna_mars_bigtts`。环境变量：`VOLCENGINE_TTS_VOICE`。</ParamField>
<ParamField path="speedRatio" type="number">提供商原生速度比率。</ParamField>
<ParamField path="emotion" type="string">提供商原生情感标签。</ParamField>
<ParamField path="speedRatio" type="number">提供商原生速度比例。</ParamField>
<ParamField path="emotion" type="string">提供商原生情绪标签。</ParamField>
<ParamField path="appId / token / cluster" type="string" deprecated>旧版 Volcengine Speech Console 字段。环境变量：`VOLCENGINE_TTS_APPID`、`VOLCENGINE_TTS_TOKEN`、`VOLCENGINE_TTS_CLUSTER`（默认值为 `volcano_tts`）。</ParamField>
</Accordion>
<Accordion title="xAI">
<ParamField path="apiKey" type="string">环境变量：`XAI_API_KEY`。</ParamField>
<ParamField path="baseUrl" type="string">默认值为 `https://api.x.ai/v1`。环境变量：`XAI_BASE_URL`。</ParamField>
<ParamField path="voiceId" type="string">默认值为 `eve`。可用实时语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`。</ParamField>
<ParamField path="voiceId" type="string">默认值为 `eve`。在线语音：`ara`、`eve`、`leo`、`rex`、`sal`、`una`。</ParamField>
<ParamField path="language" type="string">BCP-47 语言代码或 `auto`。默认值为 `en`。</ParamField>
<ParamField path="responseFormat" type='"mp3" | "wav" | "pcm" | "mulaw" | "alaw"'>默认值为 `mp3`。</ParamField>
<ParamField path="speed" type="number">提供商原生速度覆盖。</ParamField>
@ -930,43 +881,37 @@ OpenAI 和 ElevenLabs 的输出格式按渠道固定，如上所列。
<Accordion title="Xiaomi MiMo">
<ParamField path="apiKey" type="string">环境变量：`XIAOMI_API_KEY`。</ParamField>
<ParamField path="baseUrl" type="string">默认值为 `https://api.xiaomimimo.com/v1`。环境变量：`XIAOMI_BASE_URL`。</ParamField>
<ParamField path="model" type="string">默认值为 `mimo-v2.5-tts`。环境变量：`XIAOMI_TTS_MODEL`。也支持 `mimo-v2-tts`。</ParamField>
<ParamField path="model" type="string">默认值为 `mimo-v2.5-tts`。环境变量：`XIAOMI_TTS_MODEL`。还支持 `mimo-v2-tts`。</ParamField>
<ParamField path="voice" type="string">默认值为 `mimo_default`。环境变量：`XIAOMI_TTS_VOICE`。</ParamField>
<ParamField path="format" type='"mp3" | "wav"'>默认值为 `mp3`。环境变量：`XIAOMI_TTS_FORMAT`。</ParamField>
<ParamField path="style" type="string">可选的自然语言风格指令，作为用户消息发送；不会被朗读出来。</ParamField>
<ParamField path="style" type="string">作为用户消息发送的可选自然语言风格指令；不会被朗读。</ParamField>
</Accordion>
</AccordionGroup>
## 智能体工具
`tts` 工具会将文本转换为语音，并返回一个音频附件用于
回复投递。在 Feishu、Matrix、Telegram 和 WhatsApp 上，音频会
作为语音消息投递，而不是文件附件。在此路径上，当 `ffmpeg`
可用时，Feishu 和 WhatsApp 可以对非 Opus 的 TTS 输出进行转码。
`tts` 工具将文本转换为语音，并返回用于回复发送的音频附件。在 Feishu、Matrix、Telegram 和 WhatsApp 上，音频会作为语音消息而不是文件附件发送。当 `ffmpeg` 可用时，Feishu 和 WhatsApp 可以在此路径上转码非 Opus TTS 输出。
WhatsApp 会通过 Baileys 以 PTT 语音便笺形式发送音频（`audio` 并带有
`ptt: true`），并将可见文本与 PTT 音频**分开发送**，因为
客户端并不总能正确渲染语音便笺上的说明文字。
WhatsApp 通过 Baileys 将音频作为 PTT 语音备注（带有 `ptt: true` 的 `audio`）发送，并且会将可见文本与 PTT 音频**分开发送**，因为客户端不能稳定地在语音备注上呈现标题。
该工具接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是
单次调用的提供商请求超时时间，单位为毫秒。
该工具接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是每次调用的提供商请求超时时间，单位为毫秒。
## Gateway 网关 RPC
## Gateway RPC
| 方法 | 用途 |
| 方法 | 用途 |
| ----------------- | ---------------------------------------- |
| `tts.status` | 读取当前 TTS 状态和最近一次尝试。 |
| `tts.enable` | 将本地自动偏好设为 `always`。 |
| `tts.disable` | 将本地自动偏好设为 `off`。 |
| `tts.convert` | 一次性文本 → 音频。 |
| `tts.setProvider` | 设置本地提供商偏好。 |
| `tts.setPersona` | 设置本地 persona 偏好。 |
| `tts.providers` | 列出已配置的提供商和状态。 |
| `tts.status` | 读取当前 TTS 状态和上次尝试。 |
| `tts.enable` | 将本地自动偏好设置为 `always`。 |
| `tts.disable` | 将本地自动偏好设置为 `off`。 |
| `tts.convert` | 一次性文本 → 音频。 |
| `tts.setProvider` | 设置本地提供商偏好。 |
| `tts.setPersona` | 设置本地 persona 偏好。 |
| `tts.providers` | 列出已配置的提供商和状态。 |
## 服务链接
- [OpenAI 文本转语音指南](https://platform.openai.com/docs/guides/text-to-speech)
- [OpenAI 音频 API 参考](https://platform.openai.com/docs/api-reference/audio)
- [OpenAI Audio 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)