chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
f3fe598a39
commit
d5b596ac72
@ -1,13 +1,13 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想以交互方式调整凭证、设备或智能体默认设置
|
||||
- 你想以交互方式调整凭证、设备或智能体默认值
|
||||
summary: '`openclaw configure` 的 CLI 参考（交互式配置提示）'
|
||||
title: 配置
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T20:36:31Z"
|
||||
generated_at: "2026-05-02T02:28:49Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 3d33a37f0b87128d082a11e4a3429c691e5402515c737aebc28282b25e0a3a2a
|
||||
source_hash: 16e45fdead5e8026e8d359a09c799fb1248226a9425fcd9ff956d165b880663d
|
||||
source_path: cli/configure.md
|
||||
workflow: 16
|
||||
---
|
||||
@ -17,23 +17,21 @@ x-i18n:
|
||||
用于设置凭据、设备和智能体默认值的交互式提示。
|
||||
|
||||
<Note>
|
||||
**模型**部分包含一个多选项，用于设置 `agents.defaults.models` 允许列表（会显示在 `/model` 和模型选择器中）。按提供商范围设置的选项会将其选中的模型合并到现有允许列表中，而不会替换配置中已有的无关提供商。通过 configure 重新运行提供商凭证配置会保留现有的 `agents.defaults.model.primary`。当你明确想要更改默认模型时，请使用 `openclaw models auth login --provider <id> --set-default` 或 `openclaw models set <model>`。
|
||||
**模型**部分包含一个多选项，用于设置 `agents.defaults.models` 允许列表（会显示在 `/model` 和模型选择器中的内容）。提供商范围的设置选择会把选中的模型合并到现有允许列表中，而不是替换配置里已有的无关提供商。
|
||||
|
||||
从配置流程重新运行提供商认证时，会保留现有的 `agents.defaults.model.primary`，即使该提供商的认证步骤返回的配置补丁带有它自己推荐的默认模型。也就是说，添加或重新认证 xAI、OpenRouter 或其他提供商时，新模型应该会变为可用，而不会接管你当前的主要模型。只有在你有意更改默认模型时，才使用 `openclaw models auth login --provider <id> --set-default` 或 `openclaw models set <model>`。
|
||||
</Note>
|
||||
|
||||
当 configure 从提供商凭证选项启动时，默认模型和允许列表选择器会自动优先选择该提供商。对于 Volcengine 和 BytePlus 等成对提供商，同一偏好也会匹配它们的 coding-plan 变体（`volcengine-plan/*`、`byteplus-plan/*`）。如果首选提供商筛选会产生空列表，configure 会回退到未筛选的目录，而不是显示空白选择器。
|
||||
当配置流程从某个提供商认证选择开始时，默认模型和允许列表选择器会自动优先使用该提供商。对于 Volcengine 和 BytePlus 这样的成对提供商，相同的偏好也会匹配它们的编码计划变体（`volcengine-plan/*`、`byteplus-plan/*`）。如果首选提供商筛选会产生空列表，配置流程会回退到未筛选的目录，而不是显示空白选择器。
|
||||
|
||||
<Tip>
|
||||
不带子命令的 `openclaw config` 会打开同一个向导。使用 `openclaw config get|set|unset` 进行非交互式编辑。
|
||||
</Tip>
|
||||
|
||||
对于 Web 搜索，`openclaw configure --section web` 可让你选择一个提供商
|
||||
并配置其凭据。一些提供商还会显示特定于提供商的
|
||||
后续提示：
|
||||
对于 Web 搜索，`openclaw configure --section web` 可让你选择提供商并配置其凭据。部分提供商还会显示提供商特定的后续提示：
|
||||
|
||||
- **Grok** 可以使用同一个 `XAI_API_KEY` 提供可选的 `x_search` 设置，并
|
||||
让你选择一个 `x_search` 模型。
|
||||
- **Kimi** 可以询问 Moonshot API 区域（`api.moonshot.ai` 与
|
||||
`api.moonshot.cn`）以及默认的 Kimi Web 搜索模型。
|
||||
- **Grok** 可以提供可选的 `x_search` 设置，使用相同的 `XAI_API_KEY`，并让你选择一个 `x_search` 模型。
|
||||
- **Kimi** 可以询问 Moonshot API 区域（`api.moonshot.ai` 与 `api.moonshot.cn`）以及默认的 Kimi Web 搜索模型。
|
||||
|
||||
相关：
|
||||
|
||||
@ -58,12 +56,12 @@ x-i18n:
|
||||
|
||||
注意：
|
||||
|
||||
- 选择 Gateway 网关运行位置时，始终会更新 `gateway.mode`。如果你只需要这个，可以选择“继续”而不选择其他部分。
|
||||
- 写入本地配置后，当所选设置路径需要时，configure 会安装选定的可下载插件。远程 Gateway 网关配置不会安装本地插件包。
|
||||
- 选择 Gateway 网关运行位置始终会更新 `gateway.mode`。如果这就是你需要的全部内容，可以选择“继续”而不选择其他部分。
|
||||
- 写入本地配置后，如果所选设置路径需要可下载插件，配置流程会安装所选插件。远程 Gateway 网关配置不会安装本地插件包。
|
||||
- 面向渠道的服务（Slack/Discord/Matrix/Microsoft Teams）会在设置期间提示输入渠道/房间允许列表。你可以输入名称或 ID；向导会在可能时将名称解析为 ID。
|
||||
- 如果你运行守护进程安装步骤，令牌凭证需要令牌，并且 `gateway.auth.token` 由 SecretRef 管理，configure 会验证 SecretRef，但不会将解析后的明文令牌值持久化到 supervisor 服务环境元数据中。
|
||||
- 如果令牌凭证需要令牌，并且配置的令牌 SecretRef 未解析，configure 会阻止守护进程安装，并给出可操作的修复指导。
|
||||
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，且 `gateway.auth.mode` 未设置，configure 会阻止守护进程安装，直到显式设置 mode。
|
||||
- 如果你运行 daemon 安装步骤，令牌认证需要令牌，并且 `gateway.auth.token` 由 SecretRef 管理，配置流程会验证 SecretRef，但不会把解析后的明文令牌值持久化到 supervisor 服务环境元数据中。
|
||||
- 如果令牌认证需要令牌且配置的令牌 SecretRef 未解析，配置流程会阻止 daemon 安装，并给出可执行的修复指引。
|
||||
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，并且 `gateway.auth.mode` 未设置，配置流程会阻止 daemon 安装，直到显式设置模式。
|
||||
|
||||
## 示例
|
||||
|
||||
|
||||
@ -2,20 +2,20 @@
|
||||
read_when:
|
||||
- 添加或修改消息 CLI 操作
|
||||
- 更改出站渠道行为
|
||||
summary: '`openclaw message` 的 CLI 参考（发送 + 渠道操作）'
|
||||
summary: CLI 参考：`openclaw message`（发送 + 渠道操作）
|
||||
title: 消息
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T20:10:10Z"
|
||||
model: gpt-5.4
|
||||
generated_at: "2026-05-02T02:28:50Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 43f14b3815d89c92a7503e620e2424f41a3f6b92e20e089504017305b19bace4
|
||||
source_hash: f429acc2c81f33d1ade543ab1170220e293077e1d1721ac0940937de3d19f0d2
|
||||
source_path: cli/message.md
|
||||
workflow: 15
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
# `openclaw message`
|
||||
|
||||
用于发送消息和执行渠道操作的单一出站命令
|
||||
用于发送消息和渠道操作的单个出站命令
|
||||
（Discord/Google Chat/iMessage/Matrix/Mattermost（插件）/Microsoft Teams/Signal/Slack/Telegram/WhatsApp）。
|
||||
|
||||
## 用法
|
||||
@ -26,48 +26,48 @@ openclaw message <subcommand> [flags]
|
||||
|
||||
渠道选择：
|
||||
|
||||
- 如果配置了多个渠道，则必须使用 `--channel`。
|
||||
- 如果只配置了一个渠道，它会成为默认渠道。
|
||||
- 取值：`discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp`（Mattermost 需要插件）
|
||||
- 当存在 `--channel` 或带渠道前缀的目标时，`openclaw message` 会将所选渠道解析到其所属插件；否则它会加载已配置的渠道插件以推断默认渠道。
|
||||
- 如果配置了多个渠道，则必须提供 `--channel`。
|
||||
- 如果只配置了一个渠道，它会成为默认值。
|
||||
- 值：`discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp`（Mattermost 需要插件）
|
||||
- 当存在 `--channel` 或带渠道前缀的目标时，`openclaw message` 会将所选渠道解析到其所属插件；否则，它会加载已配置的渠道插件来推断默认渠道。
|
||||
|
||||
目标格式（`--target`）：
|
||||
|
||||
- WhatsApp：E.164 或群组 JID
|
||||
- Telegram：聊天 id 或 `@username`
|
||||
- Discord：`channel:<id>` 或 `user:<id>`（或 `<@id>` 提及；原始数字 id 会被视为渠道）
|
||||
- Telegram：聊天 ID 或 `@username`
|
||||
- Discord：`channel:<id>` 或 `user:<id>`（或 `<@id>` 提及；原始数字 ID 会被视为渠道）
|
||||
- Google Chat：`spaces/<spaceId>` 或 `users/<userId>`
|
||||
- Slack：`channel:<id>` 或 `user:<id>`（接受原始渠道 id）
|
||||
- Mattermost（插件）：`channel:<id>`、`user:<id>` 或 `@username`（裸 id 会被视为渠道）
|
||||
- Signal：`+E.164`、`group:<id>`、`signal:+E.164`、`signal:group:<id>` 或 `username:<name>`/`u:<name>`
|
||||
- iMessage：handle、`chat_id:<id>`、`chat_guid:<guid>` 或 `chat_identifier:<id>`
|
||||
- Slack：`channel:<id>` 或 `user:<id>`（接受原始渠道 ID）
|
||||
- Mattermost（插件）：`channel:<id>`、`user:<id>` 或 `@username`（裸 ID 会被视为渠道）
|
||||
- Signal：`+E.164`、`group:<id>`、`signal:+E.164`、`signal:group:<id>`，或 `username:<name>`/`u:<name>`
|
||||
- iMessage：句柄、`chat_id:<id>`、`chat_guid:<guid>` 或 `chat_identifier:<id>`
|
||||
- Matrix：`@user:server`、`!room:server` 或 `#alias:server`
|
||||
- Microsoft Teams：conversation id（`19:...@thread.tacv2`）或 `conversation:<id>` 或 `user:<aad-object-id>`
|
||||
- Microsoft Teams：会话 ID（`19:...@thread.tacv2`）或 `conversation:<id>` 或 `user:<aad-object-id>`
|
||||
|
||||
名称查找：
|
||||
|
||||
- 对于受支持的 provider（Discord/Slack 等），会通过目录缓存解析像 `Help` 或 `#help` 这样的渠道名称。
|
||||
- 如果缓存未命中，而 provider 支持，OpenClaw 会尝试实时目录查找。
|
||||
- 对于受支持的提供商（Discord/Slack 等），像 `Help` 或 `#help` 这样的渠道名称会通过目录缓存解析。
|
||||
- 缓存未命中时，如果提供商支持，OpenClaw 会尝试实时目录查找。
|
||||
|
||||
## 常用标志
|
||||
|
||||
- `--channel <name>`
|
||||
- `--account <id>`
|
||||
- `--target <dest>`（用于 send/poll/read 等操作的目标渠道或用户）
|
||||
- `--targets <name>`（可重复；仅用于广播）
|
||||
- `--target <dest>`（发送/投票/读取等操作的目标渠道或用户）
|
||||
- `--targets <name>`（可重复；仅广播）
|
||||
- `--json`
|
||||
- `--dry-run`
|
||||
- `--verbose`
|
||||
|
||||
## SecretRef 行为
|
||||
|
||||
- `openclaw message` 会在运行所选操作之前解析受支持渠道的 SecretRef。
|
||||
- 解析会尽可能限定在当前操作目标范围内：
|
||||
- 设置了 `--channel` 时按渠道范围解析（或从 `discord:...` 这类带前缀目标推断）
|
||||
- 设置了 `--account` 时按账户范围解析（渠道全局 + 所选账户表面）
|
||||
- 当省略 `--account` 时，OpenClaw 不会强制使用 `default` 账户 SecretRef 范围
|
||||
- 与目标消息操作无关渠道上的未解析 SecretRef 不会阻塞操作。
|
||||
- 如果所选渠道/账户的 SecretRef 未解析，该命令会对此操作执行失败关闭。
|
||||
- `openclaw message` 会在运行所选操作前解析受支持渠道的 SecretRefs。
|
||||
- 在可能时，解析范围会限定到当前操作目标：
|
||||
- 设置了 `--channel` 时按渠道范围限定（或从 `discord:...` 这类带前缀目标推断）
|
||||
- 设置了 `--account` 时按账号范围限定（渠道全局项 + 所选账号表面）
|
||||
- 省略 `--account` 时，OpenClaw 不会强制使用 `default` 账号 SecretRef 范围
|
||||
- 无关渠道上未解析的 SecretRefs 不会阻止定向消息操作。
|
||||
- 如果所选渠道/账号的 SecretRef 未解析，该操作会以失败关闭方式终止。
|
||||
|
||||
## 操作
|
||||
|
||||
@ -77,10 +77,10 @@ openclaw message <subcommand> [flags]
|
||||
- 渠道：WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost（插件）/Signal/iMessage/Matrix/Microsoft Teams
|
||||
- 必需：`--target`，以及 `--message`、`--media` 或 `--presentation`
|
||||
- 可选：`--media`、`--presentation`、`--delivery`、`--pin`、`--reply-to`、`--thread-id`、`--gif-playback`、`--force-document`、`--silent`
|
||||
- 共享展示负载：`--presentation` 发送语义块（`text`、`context`、`divider`、`buttons`、`select`），核心会通过所选渠道声明的能力进行渲染。参见 [消息展示](/zh-CN/plugins/message-presentation)。
|
||||
- 通用投递偏好：`--delivery` 接受如 `{ "pin": true }` 这样的投递提示；当渠道支持时，`--pin` 是置顶投递的简写。
|
||||
- 共享呈现载荷：`--presentation` 会发送语义块（`text`、`context`、`divider`、`buttons`、`select`），核心会通过所选渠道声明的能力来渲染它们。请参阅 [Message Presentation](/zh-CN/plugins/message-presentation)。
|
||||
- 通用投递偏好：`--delivery` 接受诸如 `{ "pin": true }` 的投递提示；当渠道支持时，`--pin` 是置顶投递的简写。
|
||||
- 仅 Telegram：`--force-document`（将图片和 GIF 作为文档发送，以避免 Telegram 压缩）
|
||||
- 仅 Telegram：`--thread-id`（论坛主题 id）
|
||||
- 仅 Telegram：`--thread-id`（论坛主题 ID）
|
||||
- 仅 Slack：`--thread-id`（线程时间戳；`--reply-to` 使用同一字段）
|
||||
- Telegram + Discord：`--silent`
|
||||
- 仅 WhatsApp：`--gif-playback`
|
||||
@ -96,9 +96,9 @@ openclaw message <subcommand> [flags]
|
||||
- 渠道：Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/Matrix
|
||||
- 必需：`--message-id`、`--target`
|
||||
- 可选：`--emoji`、`--remove`、`--participant`、`--from-me`、`--target-author`、`--target-author-uuid`
|
||||
- 注意：`--remove` 需要 `--emoji`（省略 `--emoji` 可在支持时清除自己的反应；参见 /tools/reactions）
|
||||
- 注意：`--remove` 需要 `--emoji`（省略 `--emoji` 可在支持的地方清除自己的反应；请参阅 /tools/reactions）
|
||||
- 仅 WhatsApp：`--participant`、`--from-me`
|
||||
- Signal 群组反应：必需 `--target-author` 或 `--target-author-uuid`
|
||||
- Signal 群组反应：需要 `--target-author` 或 `--target-author-uuid`
|
||||
|
||||
- `reactions`
|
||||
- 渠道：Discord/Google Chat/Slack/Matrix
|
||||
@ -108,7 +108,8 @@ openclaw message <subcommand> [flags]
|
||||
- `read`
|
||||
- 渠道：Discord/Slack/Matrix
|
||||
- 必需：`--target`
|
||||
- 可选：`--limit`、`--before`、`--after`
|
||||
- 可选：`--limit`、`--message-id`、`--before`、`--after`
|
||||
- 仅 Slack：`--message-id` 读取特定 Slack 消息时间戳；与 `--thread-id` 组合可读取精确的线程回复。
|
||||
- 仅 Discord：`--around`
|
||||
|
||||
- `edit`
|
||||
@ -123,14 +124,14 @@ openclaw message <subcommand> [flags]
|
||||
- 渠道：Discord/Slack/Matrix
|
||||
- 必需：`--message-id`、`--target`
|
||||
|
||||
- `pins`（列出）
|
||||
- `pins`（列表）
|
||||
- 渠道：Discord/Slack/Matrix
|
||||
- 必需：`--target`
|
||||
|
||||
- `permissions`
|
||||
- 渠道：Discord/Matrix
|
||||
- 必需：`--target`
|
||||
- 仅 Matrix：当启用 Matrix 加密并且允许验证操作时可用
|
||||
- 仅 Matrix：当启用 Matrix 加密且允许验证操作时可用
|
||||
|
||||
- `search`
|
||||
- 渠道：Discord
|
||||
@ -141,7 +142,7 @@ openclaw message <subcommand> [flags]
|
||||
|
||||
- `thread create`
|
||||
- 渠道：Discord
|
||||
- 必需：`--thread-name`、`--target`（渠道 id）
|
||||
- 必需：`--thread-name`、`--target`（渠道 ID）
|
||||
- 可选：`--message-id`、`--message`、`--auto-archive-min`
|
||||
|
||||
- `thread list`
|
||||
@ -151,14 +152,14 @@ openclaw message <subcommand> [flags]
|
||||
|
||||
- `thread reply`
|
||||
- 渠道：Discord
|
||||
- 必需：`--target`（线程 id）、`--message`
|
||||
- 必需：`--target`（线程 ID）、`--message`
|
||||
- 可选：`--media`、`--reply-to`
|
||||
|
||||
### 表情符号
|
||||
|
||||
- `emoji list`
|
||||
- Discord：`--guild-id`
|
||||
- Slack：无额外标志
|
||||
- Slack：没有额外标志
|
||||
|
||||
- `emoji upload`
|
||||
- 渠道：Discord
|
||||
@ -191,9 +192,9 @@ openclaw message <subcommand> [flags]
|
||||
- `event create`（Discord）：`--guild-id`、`--event-name`、`--start-time`
|
||||
- 可选：`--end-time`、`--desc`、`--channel-id`、`--location`、`--event-type`
|
||||
|
||||
### 审核管理（Discord）
|
||||
### 审核（Discord）
|
||||
|
||||
- `timeout`：`--guild-id`、`--user-id`（可选 `--duration-min` 或 `--until`；两者都省略则清除 timeout）
|
||||
- `timeout`：`--guild-id`、`--user-id`（可选 `--duration-min` 或 `--until`；两者都省略则清除超时）
|
||||
- `kick`：`--guild-id`、`--user-id`（+ `--reason`）
|
||||
- `ban`：`--guild-id`、`--user-id`（+ `--delete-days`、`--reason`）
|
||||
- `timeout` 也支持 `--reason`
|
||||
@ -201,20 +202,20 @@ openclaw message <subcommand> [flags]
|
||||
### 广播
|
||||
|
||||
- `broadcast`
|
||||
- 渠道：任何已配置渠道；使用 `--channel all` 以目标所有 provider
|
||||
- 渠道：任何已配置渠道；使用 `--channel all` 定向所有提供商
|
||||
- 必需：`--targets <target...>`
|
||||
- 可选：`--message`、`--media`、`--dry-run`
|
||||
|
||||
## 示例
|
||||
|
||||
发送一条 Discord 回复：
|
||||
发送 Discord 回复：
|
||||
|
||||
```
|
||||
openclaw message send --channel discord \
|
||||
--target channel:123 --message "hi" --reply-to 456
|
||||
```
|
||||
|
||||
发送一条带有语义按钮的消息：
|
||||
发送带语义按钮的消息：
|
||||
|
||||
```
|
||||
openclaw message send --channel discord \
|
||||
@ -222,9 +223,9 @@ openclaw message send --channel discord \
|
||||
--presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Approve","value":"approve","style":"success"},{"label":"Decline","value":"decline","style":"danger"}]}]}'
|
||||
```
|
||||
|
||||
核心会根据渠道能力，将相同的 `presentation` 负载渲染为 Discord 组件、Slack blocks、Telegram 行内按钮、Mattermost props 或 Teams/Feishu 卡片。完整契约和回退规则参见 [消息展示](/zh-CN/plugins/message-presentation)。
|
||||
核心会根据渠道能力，将同一个 `presentation` 载荷渲染为 Discord 组件、Slack 块、Telegram 内联按钮、Mattermost props，或 Teams/Feishu 卡片。完整合约和回退规则请参阅 [Message Presentation](/zh-CN/plugins/message-presentation)。
|
||||
|
||||
发送更丰富的展示负载：
|
||||
发送更丰富的呈现载荷：
|
||||
|
||||
```bash
|
||||
openclaw message send --channel googlechat --target spaces/AAA... \
|
||||
@ -232,7 +233,7 @@ openclaw message send --channel googlechat --target spaces/AAA... \
|
||||
--presentation '{"title":"Deploy approval","tone":"warning","blocks":[{"type":"text","text":"Choose a path"},{"type":"buttons","buttons":[{"label":"Approve","value":"approve"},{"label":"Decline","value":"decline"}]}]}'
|
||||
```
|
||||
|
||||
创建一个 Discord 投票：
|
||||
创建 Discord 投票：
|
||||
|
||||
```
|
||||
openclaw message poll --channel discord \
|
||||
@ -242,7 +243,7 @@ openclaw message poll --channel discord \
|
||||
--poll-multi --poll-duration-hours 48
|
||||
```
|
||||
|
||||
创建一个 Telegram 投票（2 分钟后自动关闭）：
|
||||
创建 Telegram 投票（2 分钟后自动关闭）：
|
||||
|
||||
```
|
||||
openclaw message poll --channel telegram \
|
||||
@ -252,14 +253,14 @@ openclaw message poll --channel telegram \
|
||||
--poll-duration-seconds 120 --silent
|
||||
```
|
||||
|
||||
发送一条 Teams 主动消息：
|
||||
发送 Teams 主动消息：
|
||||
|
||||
```
|
||||
openclaw message send --channel msteams \
|
||||
--target conversation:19:abc@thread.tacv2 --message "hi"
|
||||
```
|
||||
|
||||
创建一个 Teams 投票：
|
||||
创建 Teams 投票：
|
||||
|
||||
```
|
||||
openclaw message poll --channel msteams \
|
||||
@ -268,14 +269,14 @@ openclaw message poll --channel msteams \
|
||||
--poll-option Pizza --poll-option Sushi
|
||||
```
|
||||
|
||||
在 Slack 中添加反应：
|
||||
在 Slack 中反应：
|
||||
|
||||
```
|
||||
openclaw message react --channel slack \
|
||||
--target C123 --message-id 456 --emoji "✅"
|
||||
```
|
||||
|
||||
在 Signal 群组中添加反应：
|
||||
在 Signal 群组中反应：
|
||||
|
||||
```
|
||||
openclaw message react --channel signal \
|
||||
@ -283,14 +284,14 @@ openclaw message react --channel signal \
|
||||
--emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
|
||||
```
|
||||
|
||||
通过通用展示发送 Telegram 行内按钮：
|
||||
通过通用呈现发送 Telegram 内联按钮：
|
||||
|
||||
```
|
||||
openclaw message send --channel telegram --target @mychat --message "Choose:" \
|
||||
--presentation '{"blocks":[{"type":"buttons","buttons":[{"label":"Yes","value":"cmd:yes"},{"label":"No","value":"cmd:no"}]}]}'
|
||||
```
|
||||
|
||||
通过通用展示发送一张 Teams 卡片：
|
||||
通过通用呈现发送 Teams 卡片：
|
||||
|
||||
```bash
|
||||
openclaw message send --channel msteams \
|
||||
@ -305,7 +306,7 @@ openclaw message send --channel telegram --target @mychat \
|
||||
--media ./diagram.png --force-document
|
||||
```
|
||||
|
||||
## 相关内容
|
||||
## 相关
|
||||
|
||||
- [CLI 参考](/zh-CN/cli)
|
||||
- [智能体发送](/zh-CN/tools/agent-send)
|
||||
|
||||
@ -3,46 +3,52 @@ read_when:
|
||||
- 你需要一份按提供商划分的模型设置参考
|
||||
- 你需要模型提供商的示例配置或 CLI 新手引导命令
|
||||
sidebarTitle: Model providers
|
||||
summary: 模型提供商概览，包含示例配置 + CLI 流程
|
||||
summary: 模型提供商概览：示例配置 + CLI 流程
|
||||
title: 模型提供商
|
||||
x-i18n:
|
||||
generated_at: "2026-05-02T01:45:08Z"
|
||||
generated_at: "2026-05-02T02:28:46Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 8bec3029270ea475bfeb45d87a84ec01b52d461bceecc3ab4ec9ca1f62ac6cc5
|
||||
source_hash: 6b1523616a846b2bf0cad46f9f4a713fbb5e8bd7327108ab593eea8c841d5eef
|
||||
source_path: concepts/model-providers.md
|
||||
workflow: 16
|
||||
---
|
||||
|
||||
LLM/模型提供商（不是 WhatsApp/Telegram 这样的聊天渠道）参考。有关模型选择规则，请参阅 [Models](/zh-CN/concepts/models)。
|
||||
模型提供商（**LLM/模型提供商**，不是 WhatsApp/Telegram 这类聊天渠道）参考。模型选择规则见 [Models](/zh-CN/concepts/models)。
|
||||
|
||||
## 快速规则
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="模型引用和 CLI 辅助命令">
|
||||
<Accordion title="模型引用和 CLI 助手">
|
||||
- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。
|
||||
- 设置后，`agents.defaults.models` 会作为允许列表。
|
||||
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
|
||||
- CLI 助手：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
|
||||
- `models.providers.*.contextWindow` / `contextTokens` / `maxTokens` 设置提供商级默认值；`models.providers.*.models[].contextWindow` / `contextTokens` / `maxTokens` 会按模型覆盖它们。
|
||||
- 回退规则、冷却探测和会话覆盖持久化：[模型故障转移](/zh-CN/concepts/model-failover)。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="OpenAI 提供商/运行时拆分">
|
||||
<Accordion title="添加提供商认证不会更改你的主模型">
|
||||
当你添加或重新认证提供商时，`openclaw configure` 会保留现有的 `agents.defaults.model.primary`。提供商插件仍可能在其认证配置补丁中返回推荐的默认模型，但在主模型已存在时，configure 会将其视为“让此模型可用”，而不是“替换当前主模型”。
|
||||
|
||||
若要有意切换默认模型，请使用 `openclaw models set <provider/model>` 或 `openclaw models auth login --provider <id> --set-default`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="OpenAI provider/运行时拆分">
|
||||
OpenAI 系列路由按前缀区分：
|
||||
|
||||
- `openai/<model>` 使用 Pi 中的直接 OpenAI API 密钥提供商。
|
||||
- `openai-codex/<model>` 使用 Pi 中的 Codex OAuth。
|
||||
- `openai/<model>` 使用 PI 中的直接 OpenAI API key 提供商。
|
||||
- `openai-codex/<model>` 使用 PI 中的 Codex OAuth。
|
||||
- `openai/<model>` 加上 `agents.defaults.agentRuntime.id: "codex"` 使用原生 Codex 应用服务器 harness。
|
||||
|
||||
请参阅 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果提供商/运行时拆分让你困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
|
||||
见 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。如果提供商/运行时拆分让人困惑，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
|
||||
|
||||
插件自动启用遵循相同边界：`openai-codex/<model>` 属于 OpenAI 插件，而 Codex 插件由 `agentRuntime.id: "codex"` 或旧版 `codex/<model>` 引用启用。
|
||||
|
||||
GPT-5.5 可通过 `openai/gpt-5.5` 用于直接 API 密钥流量，通过 Pi 中的 `openai-codex/gpt-5.5` 用于 Codex OAuth，并且在设置 `agentRuntime.id: "codex"` 时可通过原生 Codex 应用服务器 harness 使用。
|
||||
GPT-5.5 可通过 `openai/gpt-5.5` 用于直接 API key 流量，可在 PI 中通过 `openai-codex/gpt-5.5` 用于 Codex OAuth，也可在设置 `agentRuntime.id: "codex"` 时通过原生 Codex 应用服务器 harness 使用。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="CLI 运行时">
|
||||
CLI 运行时使用相同拆分：选择规范模型引用，例如 `anthropic/claude-*`、`google/gemini-*` 或 `openai/gpt-*`，然后在你想使用本地 CLI 后端时，将 `agents.defaults.agentRuntime.id` 设置为 `claude-cli`、`google-gemini-cli` 或 `codex-cli`。
|
||||
CLI 运行时使用相同的拆分：选择规范模型引用，例如 `anthropic/claude-*`、`google/gemini-*` 或 `openai/gpt-*`，然后在你想使用本地 CLI 后端时，将 `agents.defaults.agentRuntime.id` 设置为 `claude-cli`、`google-gemini-cli` 或 `codex-cli`。
|
||||
|
||||
旧版 `claude-cli/*`、`google-gemini-cli/*` 和 `codex-cli/*` 引用会迁移回规范提供商引用，并单独记录运行时。
|
||||
|
||||
@ -51,57 +57,57 @@ LLM/模型提供商（不是 WhatsApp/Telegram 这样的聊天渠道）参考。
|
||||
|
||||
## 插件拥有的提供商行为
|
||||
|
||||
大多数提供商特定逻辑位于提供商插件（`registerProvider(...)`）中，而 OpenClaw 保留通用推理循环。插件负责新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具架构清理、故障转移分类、OAuth 刷新、用量报告、思考/推理配置文件等。
|
||||
大多数提供商特定逻辑位于提供商插件中（`registerProvider(...)`），而 OpenClaw 保留通用推理循环。插件拥有新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、思考/推理配置文件等。
|
||||
|
||||
provider-SDK 钩子和内置插件示例的完整列表位于[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。需要完全自定义请求执行器的提供商属于一个独立且更深入的扩展面。
|
||||
提供商 SDK 钩子和内置插件示例的完整列表位于 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。需要完全自定义请求执行器的提供商属于另一个更深层的扩展表面。
|
||||
|
||||
<Note>
|
||||
提供商拥有的运行器行为位于显式提供商钩子上，例如重放策略、工具架构规范化、流包装以及传输/请求辅助工具。旧版 `ProviderPlugin.capabilities` 静态包仅用于兼容， shared runner 逻辑不再读取它。
|
||||
提供商拥有的 runner 行为位于显式提供商钩子上，例如重放策略、工具 schema 规范化、流包装以及传输/请求助手。旧版 `ProviderPlugin.capabilities` 静态包仅用于兼容性，共享 runner 逻辑不再读取它。
|
||||
</Note>
|
||||
|
||||
## API 密钥轮换
|
||||
## API key 轮换
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="密钥来源和优先级">
|
||||
通过以下方式配置多个密钥：
|
||||
<Accordion title="key 来源和优先级">
|
||||
通过以下方式配置多个 key：
|
||||
|
||||
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个实时覆盖，最高优先级）
|
||||
- `<PROVIDER>_API_KEYS`（逗号或分号列表）
|
||||
- `<PROVIDER>_API_KEY`（主密钥）
|
||||
- `<PROVIDER>_API_KEY`（主 key）
|
||||
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）
|
||||
|
||||
对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。密钥选择顺序会保留优先级并对值去重。
|
||||
对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退包含在内。key 选择顺序会保留优先级并对值去重。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="何时触发轮换">
|
||||
- 仅在速率限制响应时才会使用下一个密钥重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 或定期用量限制消息）。
|
||||
- 非速率限制失败会立即失败；不会尝试密钥轮换。
|
||||
- 当所有候选密钥都失败时，会返回最后一次尝试的最终错误。
|
||||
- 仅在速率限制响应时，才会使用下一个 key 重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded` 或周期性用量限制消息）。
|
||||
- 非速率限制失败会立即失败；不会尝试 key 轮换。
|
||||
- 当所有候选 key 都失败时，将返回最后一次尝试的最终错误。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 内置提供商（pi-ai 目录）
|
||||
|
||||
OpenClaw 随附 pi-ai 目录。这些提供商**不需要** `models.providers` 配置；只需设置认证并选择一个模型。
|
||||
OpenClaw 随附 pi‑ai 目录。这些提供商不需要任何 `models.providers` 配置；只需设置认证并选择模型。
|
||||
|
||||
### OpenAI
|
||||
|
||||
- 提供商：`openai`
|
||||
- 认证：`OPENAI_API_KEY`
|
||||
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单一覆盖）
|
||||
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖）
|
||||
- 示例模型：`openai/gpt-5.5`、`openai/gpt-5.4-mini`
|
||||
- 如果特定安装或 API key 表现不同，请用 `openclaw models list --provider openai` 验证账号/模型可用性。
|
||||
- 如果特定安装或 API key 的行为不同，请使用 `openclaw models list --provider openai` 验证账号/模型可用性。
|
||||
- CLI：`openclaw onboard --auth-choice openai-api-key`
|
||||
- 默认传输协议为 `auto`（优先 WebSocket，回退到 SSE）
|
||||
- 默认传输为 `auto`（WebSocket 优先，SSE 回退）
|
||||
- 通过 `agents.defaults.models["openai/<model>"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
|
||||
- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true`/`false`）
|
||||
- OpenAI 优先级处理可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用
|
||||
- `/fast` 和 `params.fastMode` 会将直接的 `openai/*` Responses 请求映射为 `api.openai.com` 上的 `service_tier=priority`
|
||||
- 当你想使用显式层级，而不是共享的 `/fast` 开关时，请使用 `params.serviceTier`
|
||||
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）仅适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理
|
||||
- 原生 OpenAI 路由也会保留 Responses `store`、提示缓存提示信息，以及 OpenAI 推理兼容的载荷整形；代理路由则不会
|
||||
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意隐藏，因为实时 OpenAI API 请求会拒绝它，且当前 Codex 目录未公开它
|
||||
- `/fast` 和 `params.fastMode` 会将直接 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority`
|
||||
- 当你想使用显式 tier 而不是共享 `/fast` 开关时，请使用 `params.serviceTier`
|
||||
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）仅应用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理
|
||||
- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示和 OpenAI 推理兼容载荷整形；代理路由不会
|
||||
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意抑制，因为实时 OpenAI API 请求会拒绝它，且当前 Codex 目录未公开它
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -113,17 +119,17 @@ OpenClaw 随附 pi-ai 目录。这些提供商**不需要** `models.providers`
|
||||
|
||||
- 提供商：`anthropic`
|
||||
- 认证：`ANTHROPIC_API_KEY`
|
||||
- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单一覆盖）
|
||||
- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖）
|
||||
- 示例模型：`anthropic/claude-opus-4-6`
|
||||
- CLI：`openclaw onboard --auth-choice apiKey`
|
||||
- 直接的公有 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API key 和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`）
|
||||
- 推荐的 Claude CLI 配置会保持模型引用为规范形式，并单独选择 CLI
|
||||
- 直接公共 Anthropic 请求支持共享 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API key 和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`）
|
||||
- 首选 Claude CLI 配置会保留规范模型引用，并单独选择 CLI
|
||||
后端：`anthropic/claude-opus-4-7` 搭配
|
||||
`agents.defaults.agentRuntime.id: "claude-cli"`。旧版
|
||||
`claude-cli/claude-opus-4-7` 引用仍可用于兼容性。
|
||||
|
||||
<Note>
|
||||
Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 用法已再次被允许，因此 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为此集成的获准路径，除非 Anthropic 发布新策略。Anthropic setup-token 仍可作为受支持的 OpenClaw token 路径使用，但 OpenClaw 现在会优先使用 Claude CLI 复用和可用的 `claude -p`。
|
||||
Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 使用方式已重新允许，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 使用视为此集成的获准方式，除非 Anthropic 发布新策略。Anthropic setup-token 仍作为受支持的 OpenClaw token 路径可用，但 OpenClaw 现在会在可用时优先使用 Claude CLI 复用和 `claude -p`。
|
||||
</Note>
|
||||
|
||||
```json5
|
||||
@ -137,19 +143,19 @@ Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 用法已再次被
|
||||
- 提供商：`openai-codex`
|
||||
- 认证：OAuth（ChatGPT）
|
||||
- PI 模型引用：`openai-codex/gpt-5.5`
|
||||
- 原生 Codex app-server harness 引用：`openai/gpt-5.5`，搭配 `agents.defaults.agentRuntime.id: "codex"`
|
||||
- 原生 Codex app-server harness 文档：[Codex harness](/zh-CN/plugins/codex-harness)
|
||||
- 原生 Codex 应用服务器 harness 引用：`openai/gpt-5.5` 搭配 `agents.defaults.agentRuntime.id: "codex"`
|
||||
- 原生 Codex 应用服务器 harness 文档：[Codex harness](/zh-CN/plugins/codex-harness)
|
||||
- 旧版模型引用：`codex/gpt-*`
|
||||
- 插件边界：`openai-codex/*` 会加载 OpenAI 插件；原生 Codex app-server 插件仅在选择 Codex harness 运行时或旧版 `codex/*` 引用时才会被选择。
|
||||
- 插件边界：`openai-codex/*` 加载 OpenAI 插件；原生 Codex 应用服务器插件仅由 Codex harness 运行时或旧版 `codex/*` 引用选择。
|
||||
- CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex`
|
||||
- 默认传输协议为 `auto`（优先 WebSocket，回退到 SSE）
|
||||
- 默认传输为 `auto`（WebSocket 优先，SSE 回退）
|
||||
- 通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 按 PI 模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
|
||||
- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）中转发
|
||||
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）只会附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不会附加到通用 OpenAI 兼容代理
|
||||
- 与直接 `openai/*` 使用相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority`
|
||||
- `openai-codex/gpt-5.5` 使用 Codex 目录原生的 `contextWindow = 400000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
|
||||
- 策略说明：OpenAI Codex OAuth 明确支持 OpenClaw 这类外部工具/工作流。
|
||||
- 当你想使用 Codex OAuth/订阅路径时，请使用 `openai-codex/gpt-5.5`；当你的 API-key 设置和本地目录公开公有 API 路径时，请使用 `openai/gpt-5.5`。
|
||||
- 隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理
|
||||
- 与直接 `openai/*` 共享相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射到 `service_tier=priority`
|
||||
- `openai-codex/gpt-5.5` 使用 Codex 目录原生 `contextWindow = 400000` 和默认运行时 `contextTokens = 272000`；可用 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
|
||||
- 策略说明：OpenAI Codex OAuth 明确支持 OpenClaw 等外部工具/工作流。
|
||||
- 当你想使用 Codex OAuth/订阅路由时，请使用 `openai-codex/gpt-5.5`；当你的 API key 设置和本地目录公开公共 API 路由时，请使用 `openai/gpt-5.5`。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -173,13 +179,13 @@ Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 用法已再次被
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="GLM 模型" href="/zh-CN/providers/glm">
|
||||
Z.AI Coding Plan 或通用 API 端点。
|
||||
Z.AI Coding Plan 或通用 API endpoint。
|
||||
</Card>
|
||||
<Card title="MiniMax" href="/zh-CN/providers/minimax">
|
||||
MiniMax Coding Plan OAuth 或 API key 访问。
|
||||
</Card>
|
||||
<Card title="Qwen Cloud" href="/zh-CN/providers/qwen">
|
||||
Qwen Cloud 提供商接口，以及 Alibaba DashScope 和 Coding Plan 端点映射。
|
||||
Qwen Cloud 提供商表面，以及 Alibaba DashScope 和 Coding Plan endpoint 映射。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -201,24 +207,24 @@ Anthropic 员工告知我们，OpenClaw 风格的 Claude CLI 用法已再次被
|
||||
|
||||
- 提供商：`google`
|
||||
- 认证：`GEMINI_API_KEY`
|
||||
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单一覆盖）
|
||||
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖）
|
||||
- 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview`
|
||||
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被规范化为 `google/gemini-3-flash-preview`
|
||||
- 别名：`google/gemini-3.1-pro` 会被接受，并规范化为 Google 实时 Gemini API ID：`google/gemini-3.1-pro-preview`
|
||||
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会规范化为 `google/gemini-3-flash-preview`
|
||||
- 别名：`google/gemini-3.1-pro` 会被接受并规范化为 Google 的实时 Gemini API id：`google/gemini-3.1-pro-preview`
|
||||
- CLI：`openclaw onboard --auth-choice gemini-api-key`
|
||||
- 思考：`/think adaptive` 使用 Google 动态思考。Gemini 3/3.1 会省略固定的 `thinkingLevel`；Gemini 2.5 会发送 `thinkingBudget: -1`。
|
||||
- 直接 Gemini 运行还接受 `agents.defaults.models["google/<model>"].params.cachedContent`（或旧版 `cached_content`），以转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead`
|
||||
- 直接 Gemini 运行还接受 `agents.defaults.models["google/<model>"].params.cachedContent`（或旧版 `cached_content`），以转发提供商原生 `cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead`
|
||||
|
||||
### Google Vertex 和 Gemini CLI
|
||||
|
||||
- 提供商：`google-vertex`、`google-gemini-cli`
|
||||
- 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用自己的 OAuth 流程
|
||||
- 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
|
||||
|
||||
<Warning>
|
||||
OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后遇到了 Google 账号限制。请查看 Google 条款；如果你选择继续，请使用非关键账号。
|
||||
OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，使用第三方客户端后 Google 账号受到限制。请查看 Google 条款；如果你选择继续，请使用非关键账号。
|
||||
</Warning>
|
||||
|
||||
Gemini CLI OAuth 作为内置 `google` 插件的一部分随附提供。
|
||||
Gemini CLI OAuth 作为内置 `google` 插件的一部分发布。
|
||||
|
||||
<Steps>
|
||||
<Step title="安装 Gemini CLI">
|
||||
@ -245,57 +251,57 @@ Gemini CLI OAuth 作为内置 `google` 插件的一部分随附提供。
|
||||
openclaw models auth login --provider google-gemini-cli --set-default
|
||||
```
|
||||
|
||||
默认模型：`google-gemini-cli/gemini-3-flash-preview`。你**不会**把客户端 ID 或密钥粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的认证配置中。
|
||||
默认模型：`google-gemini-cli/gemini-3-flash-preview`。你**不**要将客户端 ID 或密钥粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的身份验证配置文件中。
|
||||
|
||||
</Step>
|
||||
<Step title="设置项目（如有需要）">
|
||||
<Step title="设置项目（如需要）">
|
||||
如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，并将 `stats.cached` 规范化为 OpenClaw `cacheRead`。
|
||||
|
||||
### Z.AI（GLM）
|
||||
### Z.AI (GLM)
|
||||
|
||||
- 提供商：`zai`
|
||||
- 认证：`ZAI_API_KEY`
|
||||
- 身份验证：`ZAI_API_KEY`
|
||||
- 示例模型：`zai/glm-5.1`
|
||||
- CLI：`openclaw onboard --auth-choice zai-api-key`
|
||||
- 别名：`z.ai/*` 和 `z-ai/*` 会规范化为 `zai/*`
|
||||
- `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定接口面
|
||||
- `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定表面
|
||||
|
||||
### Vercel AI Gateway
|
||||
### Vercel AI Gateway 网关
|
||||
|
||||
- 提供商：`vercel-ai-gateway`
|
||||
- 认证：`AI_GATEWAY_API_KEY`
|
||||
- 身份验证：`AI_GATEWAY_API_KEY`
|
||||
- 示例模型：`vercel-ai-gateway/anthropic/claude-opus-4.6`、`vercel-ai-gateway/moonshotai/kimi-k2.6`
|
||||
- CLI：`openclaw onboard --auth-choice ai-gateway-api-key`
|
||||
|
||||
### Kilo Gateway
|
||||
### Kilo Gateway 网关
|
||||
|
||||
- 提供商：`kilocode`
|
||||
- 认证：`KILOCODE_API_KEY`
|
||||
- 身份验证：`KILOCODE_API_KEY`
|
||||
- 示例模型：`kilocode/kilo/auto`
|
||||
- CLI：`openclaw onboard --auth-choice kilocode-api-key`
|
||||
- 基础 URL：`https://api.kilo.ai/api/gateway/`
|
||||
- 静态回退目录内置 `kilocode/kilo/auto`；实时 `https://api.kilo.ai/api/gateway/models` 发现可以进一步扩展运行时目录。
|
||||
- `kilocode/kilo/auto` 背后的精确上游路由由 Kilo Gateway 拥有，而不是硬编码在 OpenClaw 中。
|
||||
- 静态回退目录随附 `kilocode/kilo/auto`；实时 `https://api.kilo.ai/api/gateway/models` 设备发现可以进一步扩展运行时目录。
|
||||
- `kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 网关拥有，而不是在 OpenClaw 中硬编码。
|
||||
|
||||
有关设置详情，请参阅 [/providers/kilocode](/zh-CN/providers/kilocode)。
|
||||
设置详情请参阅 [/providers/kilocode](/zh-CN/providers/kilocode)。
|
||||
|
||||
### 其他内置提供商插件
|
||||
|
||||
| 提供商 | ID | 认证环境变量 | 示例模型 |
|
||||
| 提供商 | ID | 身份验证环境变量 | 示例模型 |
|
||||
| ----------------------- | -------------------------------- | ------------------------------------------------------------ | --------------------------------------------- |
|
||||
| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |
|
||||
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` |
|
||||
| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — |
|
||||
| Cloudflare AI Gateway 网关 | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — |
|
||||
| DeepInfra | `deepinfra` | `DEEPINFRA_API_KEY` | `deepinfra/deepseek-ai/DeepSeek-V3.2` |
|
||||
| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` |
|
||||
| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — |
|
||||
| Groq | `groq` | `GROQ_API_KEY` | — |
|
||||
| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` |
|
||||
| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` |
|
||||
| Kilo Gateway 网关 | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` |
|
||||
| Kimi Coding | `kimi` | `KIMI_API_KEY` 或 `KIMICODE_API_KEY` | `kimi/kimi-code` |
|
||||
| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` |
|
||||
| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` |
|
||||
@ -307,48 +313,48 @@ Gemini CLI JSON 回复会从 `response` 解析；用量会回退到 `stats`，
|
||||
| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` |
|
||||
| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` |
|
||||
| Venice | `venice` | `VENICE_API_KEY` | — |
|
||||
| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` |
|
||||
| Volcano Engine（Doubao） | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` |
|
||||
| Vercel AI Gateway 网关 | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` |
|
||||
| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` |
|
||||
| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4.3` |
|
||||
| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` |
|
||||
|
||||
#### 值得了解的注意事项
|
||||
#### 值得了解的特殊行为
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="OpenRouter">
|
||||
仅在经过验证的 `openrouter.ai` 路由上应用其应用归因标头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用符合 OpenRouter 托管提示缓存的缓存 TTL 条件，但不会接收 Anthropic 缓存标记。作为代理式 OpenAI 兼容路径，它会跳过仅限原生 OpenAI 的成形处理（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容）。由 Gemini 支持的引用仅保留代理 Gemini 思考签名清理。
|
||||
仅在经过验证的 `openrouter.ai` 路由上应用其应用归因标头和 Anthropic `cache_control` 标记。DeepSeek、Moonshot 和 ZAI 引用符合 OpenRouter 托管提示缓存的缓存 TTL 条件，但不会接收 Anthropic 缓存标记。作为代理风格的 OpenAI 兼容路径，它会跳过仅限原生 OpenAI 的塑形（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容）。Gemini 后端引用仅保留代理 Gemini 思维签名清理。
|
||||
</Accordion>
|
||||
<Accordion title="Kilo Gateway">
|
||||
由 Gemini 支持的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的引用会跳过代理推理注入。
|
||||
<Accordion title="Kilo Gateway 网关">
|
||||
Gemini 后端引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的引用会跳过代理推理注入。
|
||||
</Accordion>
|
||||
<Accordion title="MiniMax">
|
||||
API 密钥新手引导会写入显式的纯文本 M2.7 聊天模型定义；图像理解仍保留在插件拥有的 `MiniMax-VL-01` 媒体提供商上。
|
||||
</Accordion>
|
||||
<Accordion title="NVIDIA">
|
||||
模型 ID 使用 `nvidia/<vendor>/<model>` 命名空间（例如 `nvidia/nvidia/nemotron-...` 以及 `nvidia/moonshotai/kimi-k2.5`）；选择器会保留字面的 `<provider>/<model-id>` 组合，而发送到 API 的规范键仍保持单前缀。
|
||||
模型 ID 使用 `nvidia/<vendor>/<model>` 命名空间（例如 `nvidia/nvidia/nemotron-...` 与 `nvidia/moonshotai/kimi-k2.5` 并列）；选择器会保留字面量 `<provider>/<model-id>` 组合，而发送到 API 的规范键保持单前缀。
|
||||
</Accordion>
|
||||
<Accordion title="xAI">
|
||||
使用 xAI Responses 路径。`grok-4.3` 是内置默认聊天模型。`/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为它们的 `*-fast` 变体。`tool_stream` 默认开启；可通过 `agents.defaults.models["xai/<model>"].params.tool_stream=false` 禁用。
|
||||
</Accordion>
|
||||
<Accordion title="Cerebras">
|
||||
以内置 `cerebras` 提供商插件形式提供。GLM 使用 `zai-glm-4.7`；OpenAI 兼容基础 URL 为 `https://api.cerebras.ai/v1`。
|
||||
作为内置 `cerebras` 提供商插件发布。GLM 使用 `zai-glm-4.7`；OpenAI 兼容基础 URL 是 `https://api.cerebras.ai/v1`。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 通过 `models.providers` 使用的提供商（自定义/基础 URL）
|
||||
## 通过 `models.providers` 使用提供商（自定义/基础 URL）
|
||||
|
||||
使用 `models.providers`（或 `models.json`）添加**自定义**提供商或 OpenAI/Anthropic 兼容代理。
|
||||
|
||||
下面许多内置提供商插件已经发布默认目录。只有当你想覆盖默认基础 URL、标头或模型列表时，才使用显式 `models.providers.<id>` 条目。
|
||||
下面的许多内置提供商插件已经发布默认目录。仅当你想覆盖默认基础 URL、标头或模型列表时，才使用显式 `models.providers.<id>` 条目。
|
||||
|
||||
Gateway 网关模型能力检查还会读取显式 `models.providers.<id>.models[]` 元数据。如果某个自定义或代理模型接受图像，请在该模型上设置 `input: ["text", "image"]`，以便 WebChat 和节点来源附件路径将图像作为原生模型输入传递，而不是作为纯文本媒体引用。
|
||||
Gateway 网关模型能力检查还会读取显式的 `models.providers.<id>.models[]` 元数据。如果自定义模型或代理模型接受图像，请在该模型上设置 `input: ["text", "image"]`，这样 WebChat 和节点来源附件路径会将图像作为原生模型输入传递，而不是作为仅文本媒体引用传递。
|
||||
|
||||
### Moonshot AI（Kimi）
|
||||
|
||||
Moonshot 以内置提供商插件形式提供。默认使用内置提供商，只有在需要覆盖基础 URL 或模型元数据时，才添加显式 `models.providers.moonshot` 条目：
|
||||
Moonshot 作为内置提供商插件提供。默认使用内置提供商，只有在需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目：
|
||||
|
||||
- 提供商：`moonshot`
|
||||
- 认证：`MOONSHOT_API_KEY`
|
||||
- 凭证：`MOONSHOT_API_KEY`
|
||||
- 示例模型：`moonshot/kimi-k2.6`
|
||||
- CLI：`openclaw onboard --auth-choice moonshot-api-key` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`
|
||||
|
||||
@ -400,11 +406,11 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
|
||||
}
|
||||
```
|
||||
|
||||
旧版 `kimi/k2p5` 仍可作为兼容模型 ID 被接受。
|
||||
旧版 `kimi/k2p5` 仍作为兼容模型 ID 被接受。
|
||||
|
||||
### Volcano Engine（Doubao）
|
||||
### Volcano Engine（豆包）
|
||||
|
||||
Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访问。
|
||||
Volcano Engine（火山引擎）提供对中国区豆包和其他模型的访问。
|
||||
|
||||
- 提供商：`volcengine`（编码：`volcengine-plan`）
|
||||
- 凭证：`VOLCANO_ENGINE_API_KEY`
|
||||
@ -419,20 +425,20 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访
|
||||
}
|
||||
```
|
||||
|
||||
新手引导默认使用编码界面，但通用 `volcengine/*` 目录会同时注册。
|
||||
新手引导默认使用编码表面，但通用的 `volcengine/*` 目录会同时注册。
|
||||
|
||||
在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的提供商范围选择器。
|
||||
在新手引导/配置模型选择器中，Volcengine 凭证选项会优先显示 `volcengine/*` 和 `volcengine-plan/*` 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的按提供商限定的选择器。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="标准模型">
|
||||
- `volcengine/doubao-seed-1-8-251228`（Doubao Seed 1.8）
|
||||
- `volcengine/doubao-seed-1-8-251228` (Doubao Seed 1.8)
|
||||
- `volcengine/doubao-seed-code-preview-251028`
|
||||
- `volcengine/kimi-k2-5-260127`（Kimi K2.5）
|
||||
- `volcengine/glm-4-7-251222`（GLM 4.7）
|
||||
- `volcengine/deepseek-v3-2-251201`（DeepSeek V3.2 128K）
|
||||
- `volcengine/kimi-k2-5-260127` (Kimi K2.5)
|
||||
- `volcengine/glm-4-7-251222` (GLM 4.7)
|
||||
- `volcengine/deepseek-v3-2-251201` (DeepSeek V3.2 128K)
|
||||
|
||||
</Tab>
|
||||
<Tab title="编码模型（volcengine-plan）">
|
||||
<Tab title="编码模型 (volcengine-plan)">
|
||||
- `volcengine-plan/ark-code-latest`
|
||||
- `volcengine-plan/doubao-seed-code`
|
||||
- `volcengine-plan/kimi-k2.5`
|
||||
@ -444,10 +450,10 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访
|
||||
|
||||
### BytePlus（国际版）
|
||||
|
||||
BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。
|
||||
BytePlus ARK 为国际用户提供与火山引擎相同模型的访问能力。
|
||||
|
||||
- 提供商：`byteplus`（编码：`byteplus-plan`）
|
||||
- 凭证：`BYTEPLUS_API_KEY`
|
||||
- 认证：`BYTEPLUS_API_KEY`
|
||||
- 示例模型：`byteplus-plan/ark-code-latest`
|
||||
- CLI：`openclaw onboard --auth-choice byteplus-api-key`
|
||||
|
||||
@ -461,16 +467,16 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。
|
||||
|
||||
新手引导默认使用编码界面，但通用 `byteplus/*` 目录会同时注册。
|
||||
|
||||
在新手引导/配置模型选择器中，BytePlus 凭证选项会优先选择 `byteplus/*` 和 `byteplus-plan/*` 行。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的按提供商限定的选择器。
|
||||
在新手引导/配置模型选择器中，BytePlus 认证选项会优先显示 `byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，OpenClaw 会回退到未过滤的目录，而不是显示空的、限定提供商范围的选择器。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Standard models">
|
||||
- `byteplus/seed-1-8-251228`（Seed 1.8）
|
||||
- `byteplus/kimi-k2-5-260127`（Kimi K2.5）
|
||||
- `byteplus/glm-4-7-251222`（GLM 4.7）
|
||||
<Tab title="标准模型">
|
||||
- `byteplus/seed-1-8-251228` (Seed 1.8)
|
||||
- `byteplus/kimi-k2-5-260127` (Kimi K2.5)
|
||||
- `byteplus/glm-4-7-251222` (GLM 4.7)
|
||||
|
||||
</Tab>
|
||||
<Tab title="Coding models (byteplus-plan)">
|
||||
<Tab title="编码模型 (byteplus-plan)">
|
||||
- `byteplus-plan/ark-code-latest`
|
||||
- `byteplus-plan/doubao-seed-code`
|
||||
- `byteplus-plan/kimi-k2.5`
|
||||
@ -482,10 +488,10 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问。
|
||||
|
||||
### Synthetic
|
||||
|
||||
Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型：
|
||||
Synthetic 在 `synthetic` 提供商后方提供 Anthropic 兼容模型：
|
||||
|
||||
- 提供商：`synthetic`
|
||||
- 凭证：`SYNTHETIC_API_KEY`
|
||||
- 认证：`SYNTHETIC_API_KEY`
|
||||
- 示例模型：`synthetic/hf:MiniMaxAI/MiniMax-M2.5`
|
||||
- CLI：`openclaw onboard --auth-choice synthetic-api-key`
|
||||
|
||||
@ -516,30 +522,30 @@ MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
|
||||
- MiniMax OAuth（中国）：`--auth-choice minimax-cn-oauth`
|
||||
- MiniMax API key（全球）：`--auth-choice minimax-global-api`
|
||||
- MiniMax API key（中国）：`--auth-choice minimax-cn-api`
|
||||
- 凭证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
|
||||
- 认证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
|
||||
|
||||
设置详情、模型选项和配置片段请参阅 [/providers/minimax](/zh-CN/providers/minimax)。
|
||||
设置详情、模型选项和配置片段见 [/providers/minimax](/zh-CN/providers/minimax)。
|
||||
|
||||
<Note>
|
||||
在 MiniMax 的 Anthropic 兼容流式传输路径上，除非你显式设置，否则 OpenClaw 默认禁用 thinking，并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
|
||||
在 MiniMax 的 Anthropic 兼容流式传输路径上，除非你显式设置，OpenClaw 默认会禁用思考，并且 `/fast on` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
|
||||
</Note>
|
||||
|
||||
插件拥有的能力拆分：
|
||||
|
||||
- 文本/聊天默认值保持为 `minimax/MiniMax-M2.7`
|
||||
- 文本/聊天默认保持在 `minimax/MiniMax-M2.7`
|
||||
- 图像生成是 `minimax/image-01` 或 `minimax-portal/image-01`
|
||||
- 图像理解是在两条 MiniMax 凭证路径上由插件拥有的 `MiniMax-VL-01`
|
||||
- Web 搜索保持使用提供商 ID `minimax`
|
||||
- 图像理解是两个 MiniMax 认证路径上的插件自有 `MiniMax-VL-01`
|
||||
- Web 搜索保持在提供商 ID `minimax`
|
||||
|
||||
### LM Studio
|
||||
|
||||
LM Studio 作为内置提供商插件发布，使用原生 API：
|
||||
LM Studio 作为内置提供商插件提供，并使用原生 API：
|
||||
|
||||
- 提供商：`lmstudio`
|
||||
- 凭证：`LM_API_TOKEN`
|
||||
- 认证：`LM_API_TOKEN`
|
||||
- 默认推理基础 URL：`http://localhost:1234/v1`
|
||||
|
||||
然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）：
|
||||
然后设置模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -549,14 +555,14 @@ LM Studio 作为内置提供商插件发布，使用原生 API：
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw 使用 LM Studio 的原生 `/api/v1/models` 和 `/api/v1/models/load` 进行设备发现 + 自动加载，默认使用 `/v1/chat/completions` 进行推理。设置和故障排除请参阅 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
|
||||
OpenClaw 使用 LM Studio 的原生 `/api/v1/models` 和 `/api/v1/models/load` 做设备发现 + 自动加载，并默认用 `/v1/chat/completions` 做推理。设置与故障排除见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
|
||||
|
||||
### Ollama
|
||||
|
||||
Ollama 作为内置提供商插件发布，并使用 Ollama 的原生 API：
|
||||
Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API：
|
||||
|
||||
- 提供商：`ollama`
|
||||
- 凭证：无需（本地服务器）
|
||||
- 认证：无需（本地服务器）
|
||||
- 示例模型：`ollama/llama3.3`
|
||||
- 安装：[https://ollama.com/download](https://ollama.com/download)
|
||||
|
||||
@ -573,23 +579,23 @@ ollama pull llama3.3
|
||||
}
|
||||
```
|
||||
|
||||
当你使用 `OLLAMA_API_KEY` 选择加入时，Ollama 会在本地 `http://127.0.0.1:11434` 被检测到，并且内置提供商插件会将 Ollama 直接添加到 `openclaw onboard` 和模型选择器中。新手引导、云端/本地模式和自定义配置请参阅 [/providers/ollama](/zh-CN/providers/ollama)。
|
||||
当你使用 `OLLAMA_API_KEY` 选择启用时，OpenClaw 会在本地 `http://127.0.0.1:11434` 检测 Ollama，并且内置提供商插件会把 Ollama 直接添加到 `openclaw onboard` 和模型选择器。新手引导、云/本地模式和自定义配置见 [/providers/ollama](/zh-CN/providers/ollama)。
|
||||
|
||||
### vLLM
|
||||
|
||||
vLLM 作为面向本地/自托管 OpenAI 兼容服务器的内置提供商插件发布：
|
||||
vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容服务器：
|
||||
|
||||
- 提供商：`vllm`
|
||||
- 凭证：可选（取决于你的服务器）
|
||||
- 认证：可选（取决于你的服务器）
|
||||
- 默认基础 URL：`http://127.0.0.1:8000/v1`
|
||||
|
||||
要在本地选择加入自动设备发现（如果你的服务器不强制要求凭证，任意值都可以）：
|
||||
要在本地选择启用自动发现（如果你的服务器不强制认证，任何值都可以）：
|
||||
|
||||
```bash
|
||||
export VLLM_API_KEY="vllm-local"
|
||||
```
|
||||
|
||||
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
|
||||
然后设置模型（替换为 `/v1/models` 返回的某个 ID）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -599,23 +605,23 @@ export VLLM_API_KEY="vllm-local"
|
||||
}
|
||||
```
|
||||
|
||||
详情请参阅 [/providers/vllm](/zh-CN/providers/vllm)。
|
||||
详情见 [/providers/vllm](/zh-CN/providers/vllm)。
|
||||
|
||||
### SGLang
|
||||
|
||||
SGLang 作为面向快速自托管 OpenAI 兼容服务器的内置提供商插件发布：
|
||||
SGLang 作为内置提供商插件提供，用于快速自托管的 OpenAI 兼容服务器：
|
||||
|
||||
- 提供商：`sglang`
|
||||
- 凭证：可选（取决于你的服务器）
|
||||
- 认证：可选（取决于你的服务器）
|
||||
- 默认基础 URL：`http://127.0.0.1:30000/v1`
|
||||
|
||||
要在本地选择加入自动设备发现（如果你的服务器不强制要求凭证，任意值都可以）：
|
||||
要在本地选择启用自动发现（如果你的服务器不强制认证，任何值都可以）：
|
||||
|
||||
```bash
|
||||
export SGLANG_API_KEY="sglang-local"
|
||||
```
|
||||
|
||||
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
|
||||
然后设置模型（替换为 `/v1/models` 返回的某个 ID）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -625,7 +631,7 @@ export SGLANG_API_KEY="sglang-local"
|
||||
}
|
||||
```
|
||||
|
||||
详情请参阅 [/providers/sglang](/zh-CN/providers/sglang)。
|
||||
详情见 [/providers/sglang](/zh-CN/providers/sglang)。
|
||||
|
||||
### 本地代理（LM Studio、vLLM、LiteLLM 等）
|
||||
|
||||
@ -664,7 +670,7 @@ export SGLANG_API_KEY="sglang-local"
|
||||
```
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Default optional fields">
|
||||
<Accordion title="默认可选字段">
|
||||
对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 是可选的。省略时，OpenClaw 默认使用：
|
||||
|
||||
- `reasoning: false`
|
||||
@ -676,15 +682,15 @@ export SGLANG_API_KEY="sglang-local"
|
||||
建议：设置与你的代理/模型限制匹配的显式值。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Proxy-route shaping rules">
|
||||
- 对于非原生端点（任何非空 `baseUrl`，且其主机不是 `api.openai.com`）上的 `api: "openai-completions"`，OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持的 `developer` 角色而返回 400 错误。
|
||||
- 代理式 OpenAI 兼容路由也会跳过仅限原生 OpenAI 的请求整形：没有 `service_tier`，没有 Responses `store`，没有 Completions `store`，没有提示缓存提示，没有 OpenAI reasoning 兼容载荷整形，也没有隐藏的 OpenClaw attribution 标头。
|
||||
- 对于需要供应商特定字段的 OpenAI 兼容 Completions 代理，请设置 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），以将额外 JSON 合并到出站请求正文中。
|
||||
- 对于 vLLM 聊天模板控制，请设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话 thinking 级别关闭时，内置 vLLM 插件会自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。
|
||||
- 对于较慢的本地模型或远程 LAN/tailnet 主机，请设置 `models.providers.<id>.timeoutSeconds`。这会延长提供商模型 HTTP 请求处理时间，包括连接、标头、正文流式传输以及总的 guarded-fetch 中止时间，而不会增加整个智能体运行时超时。
|
||||
<Accordion title="代理路由塑形规则">
|
||||
- 对非原生端点（任何非空 `baseUrl` 且其主机不是 `api.openai.com`）上的 `api: "openai-completions"`，OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持的 `developer` 角色返回 400 错误。
|
||||
- 代理式 OpenAI 兼容路由还会跳过仅适用于原生 OpenAI 的请求塑形：没有 `service_tier`、没有 Responses `store`、没有 Completions `store`、没有提示缓存提示、没有 OpenAI 推理兼容载荷塑形，也没有隐藏的 OpenClaw 归因标头。
|
||||
- 对于需要厂商特定字段的 OpenAI 兼容 Completions 代理，设置 `agents.defaults.models["provider/model"].params.extra_body`（或 `extraBody`），将额外 JSON 合并到出站请求体中。
|
||||
- 对于 vLLM 聊天模板控制，设置 `agents.defaults.models["provider/model"].params.chat_template_kwargs`。当会话思考级别关闭时，内置 vLLM 插件会自动为 `vllm/nemotron-3-*` 发送 `enable_thinking: false` 和 `force_nonempty_content: true`。
|
||||
- 对于较慢的本地模型或远程 LAN/tailnet 主机，设置 `models.providers.<id>.timeoutSeconds`。这会扩展提供商模型 HTTP 请求处理，包括连接、标头、正文流式传输以及总的受保护抓取中止时间，而不会增加整个 Agent 运行时超时。
|
||||
- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认 OpenAI 行为（解析到 `api.openai.com`）。
|
||||
- 出于安全考虑，在非原生 `openai-completions` 端点上，显式的 `compat.supportsDeveloperRole: true` 仍会被覆盖。
|
||||
- 对于非直连端点（除规范 `anthropic` 之外的任何提供商，或自定义 `models.providers.anthropic.baseUrl` 且其主机不是公共 `api.anthropic.com` 端点）上的 `api: "anthropic-messages"`，OpenClaw 会抑制隐式 Anthropic beta 标头，例如 `claude-code-20250219`、`interleaved-thinking-2025-05-14` 和 OAuth 标记，因此自定义 Anthropic 兼容代理不会因不支持的 beta 标志而拒绝请求。如果你的代理需要特定 beta 功能，请显式设置 `models.providers.<id>.headers["anthropic-beta"]`。
|
||||
- 为了安全，在非原生 `openai-completions` 端点上，显式的 `compat.supportsDeveloperRole: true` 仍会被覆盖。
|
||||
- 对非直连端点（canonical `anthropic` 以外的任何提供商，或自定义 `models.providers.anthropic.baseUrl` 且其主机不是公开 `api.anthropic.com` 端点）上的 `api: "anthropic-messages"`，OpenClaw 会抑制隐式 Anthropic beta 标头，例如 `claude-code-20250219`、`interleaved-thinking-2025-05-14` 和 OAuth 标记，这样自定义 Anthropic 兼容代理就不会拒绝不支持的 beta 标志。如果你的代理需要特定 beta 功能，请显式设置 `models.providers.<id>.headers["anthropic-beta"]`。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -4,27 +4,29 @@ read_when:
|
||||
- 配置 TTS 提供商、回退链或角色设定
|
||||
- 使用 /tts 命令或指令
|
||||
sidebarTitle: Text to speech (TTS)
|
||||
summary: 出站回复的文本转语音 —— 提供商、角色设定、斜杠命令和按渠道输出
|
||||
summary: 出站回复的文本转语音——提供商、角色设定、斜杠命令和按渠道输出
|
||||
title: 文本转语音
|
||||
x-i18n:
|
||||
generated_at: "2026-05-01T22:04:15Z"
|
||||
generated_at: "2026-05-02T02:28:56Z"
|
||||
model: gpt-5.5
|
||||
provider: openai
|
||||
source_hash: 8ff736249314fcfbc4f61c24a9c005c02e3582e2aa5fe0baac7e99c5e00f15e1
|
||||
source_hash: 1bd5aadf91f42af1c25a59f12a5851e76ebb1a339bc8b236394fc2e33754d7e6
|
||||
source_path: tools/tts.md
|
||||
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 和本地 CLI 无需 API key 即可使用。完整列表请参阅[提供商矩阵](#supported-providers)。
|
||||
OpenAI 和 ElevenLabs 是最可靠的托管选项。Microsoft 和
|
||||
Local CLI 无需 API key 即可工作。完整列表请参阅[提供商矩阵](#supported-providers)。
|
||||
</Step>
|
||||
<Step title="设置 API key">
|
||||
导出你的提供商所需的环境变量（例如 `OPENAI_API_KEY`、`ELEVENLABS_API_KEY`）。Microsoft 和本地 CLI 不需要密钥。
|
||||
导出你的提供商所需的环境变量（例如 `OPENAI_API_KEY`、
|
||||
`ELEVENLABS_API_KEY`）。Microsoft 和 Local CLI 不需要密钥。
|
||||
</Step>
|
||||
<Step title="在配置中启用">
|
||||
设置 `messages.tts.auto: "always"` 和 `messages.tts.provider`：
|
||||
@ -42,43 +44,47 @@ 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 会按注册表自动选择顺序选取第一个已配置的提供商。
|
||||
Auto-TTS 默认**关闭**。当 `messages.tts.provider` 未设置时，
|
||||
OpenClaw 会按注册表自动选择顺序选用第一个已配置的提供商。
|
||||
内置的 `tts` 智能体工具仅用于明确意图：普通聊天会保持文本形式，
|
||||
除非用户请求音频、使用 `/tts`，或启用 Auto-TTS/指令式语音。
|
||||
</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 电话。 |
|
||||
| **本地 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。 |
|
||||
| **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"` 感知人设。 |
|
||||
| **Gradium** | `GRADIUM_API_KEY` | 语音便笺和电话输出。 |
|
||||
| **Inworld** | `INWORLD_API_KEY` | 流式 TTS API。原生 Opus 语音便笺和 PCM 电话音频。 |
|
||||
| **Local CLI** | 无 | 运行已配置的本地 TTS 命令。 |
|
||||
| **Microsoft** | 无 | 通过 `node-edge-tts` 使用公共 Edge 神经网络 TTS。尽力而为，无 SLA。 |
|
||||
| **MiniMax** | `MINIMAX_API_KEY`（或令牌计划：`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`） | T2A v2 API。默认使用 `speech-2.8-hd`。 |
|
||||
| **OpenAI** | `OPENAI_API_KEY` | 也用于自动摘要；支持人设 `instructions`。 |
|
||||
| **OpenRouter** | `OPENROUTER_API_KEY`（可复用 `models.providers.openrouter.apiKey`） | 默认模型 `hexgrad/kokoro-82m`。 |
|
||||
| **Volcengine** | `VOLCENGINE_TTS_API_KEY` 或 `BYTEPLUS_SEED_SPEECH_API_KEY`（旧版 AppID/令牌：`VOLCENGINE_TTS_APPID`/`_TOKEN`） | BytePlus Seed Speech HTTP API。 |
|
||||
| **Vydra** | `VYDRA_API_KEY` | 共享的图像、视频和语音提供商。 |
|
||||
| **xAI** | `XAI_API_KEY` | xAI 批量 TTS。**不**支持原生 Opus 语音消息。 |
|
||||
| **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 服务。它是一个公开 Web 服务，没有已发布的 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">
|
||||
@ -202,7 +208,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
|
||||
}
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Microsoft (no key)">
|
||||
<Tab title="Microsoft（无密钥）">
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
@ -356,9 +362,9 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### 按智能体设置的语音覆盖
|
||||
### 按智能体覆盖语音
|
||||
|
||||
当某个智能体应使用不同的提供商、语音、模型、角色或自动 TTS 模式发声时，请使用 `agents.list[].tts`。该智能体块会深度合并到 `messages.tts` 之上，因此提供商凭据可以保留在全局提供商配置中：
|
||||
当某个智能体应使用不同的提供商、语音、模型、人设或 Auto-TTS 模式时，使用 `agents.list[].tts`。智能体块会深度合并到 `messages.tts` 之上，因此提供商凭据可以保留在全局提供商配置中：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -386,18 +392,18 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
|
||||
}
|
||||
```
|
||||
|
||||
要固定按智能体设置的角色，请在提供商配置旁边设置 `agents.list[].tts.persona`，它只会为该智能体覆盖全局 `messages.tts.persona`。
|
||||
要固定每个智能体的人设，请在提供商配置旁设置 `agents.list[].tts.persona`，它只会覆盖该智能体的全局 `messages.tts.persona`。
|
||||
|
||||
自动回复、`/tts audio`、`/tts status` 和 `tts` 智能体工具的优先级顺序：
|
||||
|
||||
1. `messages.tts`
|
||||
2. 活跃的 `agents.list[].tts`
|
||||
3. 渠道覆盖，当渠道支持 `channels.<channel>.tts` 时
|
||||
4. 账号覆盖，当渠道传入 `channels.<channel>.accounts.<id>.tts` 时
|
||||
2. 当前 `agents.list[].tts`
|
||||
3. 渠道覆盖项，当该渠道支持 `channels.<channel>.tts` 时
|
||||
4. 账号覆盖项，当该渠道传入 `channels.<channel>.accounts.<id>.tts` 时
|
||||
5. 此主机的本地 `/tts` 偏好设置
|
||||
6. 启用[模型驱动指令](#model-driven-directives)时的内联 `[[tts:...]]` 指令
|
||||
6. 启用[模型覆盖](#model-driven-directives)时的内联 `[[tts:...]]` 指令
|
||||
|
||||
渠道和账号覆盖项使用与 `messages.tts` 相同的结构，并在更早的层之上进行深度合并，因此共享的提供商凭证可以保留在 `messages.tts` 中，而某个渠道或机器人账号只更改语音、模型、人格或自动模式：
|
||||
渠道和账号覆盖项使用与 `messages.tts` 相同的结构，并在前面各层之上进行深度合并，因此共享的提供商凭证可以保留在 `messages.tts` 中，而某个渠道或机器人账号只更改语音、模型、persona 或自动模式：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -425,11 +431,11 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
|
||||
}
|
||||
```
|
||||
|
||||
## 人格
|
||||
## Personas
|
||||
|
||||
**人格**是一种稳定的语音身份，可以跨提供商确定性地应用。它可以偏好某个提供商，定义与提供商无关的提示意图，并携带特定于提供商的语音、模型、提示模板、种子和语音设置绑定。
|
||||
**persona** 是一个稳定的语音身份，可以跨提供商以确定性方式应用。它可以偏好某一个提供商、定义与提供商无关的提示意图，并携带针对特定提供商的语音、模型、提示模板、种子和语音设置绑定。
|
||||
|
||||
### 最小人格
|
||||
### 最小 persona
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -451,7 +457,7 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
|
||||
}
|
||||
```
|
||||
|
||||
### 完整人格（与提供商无关的提示）
|
||||
### 完整 persona（提供商无关提示）
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -501,60 +507,60 @@ TTS 配置位于 `~/.openclaw/openclaw.json` 中的 `messages.tts` 下。选择
|
||||
}
|
||||
```
|
||||
|
||||
### 人格解析
|
||||
### Persona 解析
|
||||
|
||||
活动人格会确定性地选择：
|
||||
当前 persona 会以确定性方式选择：
|
||||
|
||||
1. `/tts persona <id>` 本地偏好设置（如果已设置）。
|
||||
2. `messages.tts.persona`（如果已设置）。
|
||||
3. 无人格。
|
||||
1. 本地 `/tts persona <id>` 偏好设置，如果已设置。
|
||||
2. `messages.tts.persona`，如果已设置。
|
||||
3. 无 persona。
|
||||
|
||||
提供商选择按显式优先运行：
|
||||
|
||||
1. 直接覆盖（CLI、Gateway 网关、Talk、允许的 TTS 指令）。
|
||||
2. `/tts provider <id>` 本地偏好设置。
|
||||
3. 活动人格的 `provider`。
|
||||
1. 直接覆盖项（CLI、Gateway 网关、Talk、允许的 TTS 指令）。
|
||||
2. 本地 `/tts provider <id>` 偏好设置。
|
||||
3. 当前 persona 的 `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 提示
|
||||
|
||||
人格提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent`、`pacing`、`constraints`）是**与提供商无关**的。每个提供商会决定如何使用它们：
|
||||
Persona 提示字段（`profile`、`scene`、`sampleContext`、`style`、`accent`、`pacing`、`constraints`）是**提供商无关**的。每个提供商自行决定如何使用它们：
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Google Gemini">
|
||||
仅当有效的 Google 提供商配置设置了 `promptTemplate: "audio-profile-v1"` 或 `personaPrompt` 时，才会将人格提示字段包装进 Gemini TTS 提示结构中。较早的 `audioProfile` 和 `speakerName` 字段仍会作为 Google 专用提示文本前置。`[[tts:text]]` 块内的 `[whispers]` 或 `[laughs]` 等内联音频标签会保留在 Gemini 转录文本中；OpenClaw 不会生成这些标签。
|
||||
仅当有效的 Google 提供商配置设置了 `promptTemplate: "audio-profile-v1"` 或 `personaPrompt` 时，才会将 persona 提示字段包装进 Gemini TTS 提示结构。较旧的 `audioProfile` 和 `speakerName` 字段仍会作为 Google 专用提示文本前置。`[[tts:text]]` 块内的 `[whispers]` 或 `[laughs]` 等内联音频标签会保留在 Gemini 转写文本中；OpenClaw 不会生成这些标签。
|
||||
</Accordion>
|
||||
<Accordion title="OpenAI">
|
||||
仅当未配置显式 OpenAI `instructions` 时，才会将人格提示字段映射到请求的 `instructions` 字段。显式 `instructions` 始终优先。
|
||||
仅当没有配置显式 OpenAI `instructions` 时，才会将 persona 提示字段映射到请求的 `instructions` 字段。显式 `instructions` 始终优先。
|
||||
</Accordion>
|
||||
<Accordion title="其他提供商">
|
||||
只使用 `personas.<id>.providers.<provider>` 下特定于提供商的人格绑定。人格提示字段会被忽略，除非该提供商实现了自己的“人格提示”映射。
|
||||
<Accordion title="Other providers">
|
||||
只使用 `personas.<id>.providers.<provider>` 下的提供商专用 persona 绑定。除非提供商实现自己的 persona 提示映射，否则会忽略 persona 提示字段。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### 回退策略
|
||||
|
||||
当人格对尝试的提供商**没有绑定**时，`fallbackPolicy` 控制行为：
|
||||
当某个 persona 对尝试的提供商**没有绑定**时，`fallbackPolicy` 控制行为：
|
||||
|
||||
| 策略 | 行为 |
|
||||
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `preserve-persona` | **默认值。** 与提供商无关的提示字段保持可用；提供商可以使用它们，也可以忽略它们。 |
|
||||
| `provider-defaults` | 该次尝试的提示准备会省略人格；提供商使用其中性默认值，同时继续回退到其他提供商。 |
|
||||
| `fail` | 使用 `reasonCode: "not_configured"` 和 `personaBinding: "missing"` 跳过该提供商尝试。仍会尝试回退提供商。 |
|
||||
| `preserve-persona` | **默认。** 提供商无关提示字段保持可用；提供商可以使用它们，也可以忽略它们。 |
|
||||
| `provider-defaults` | 在这次尝试的提示准备中省略 persona；提供商使用其中性默认值，同时继续回退到其他提供商。 |
|
||||
| `fail` | 跳过该提供商尝试，并带有 `reasonCode: "not_configured"` 和 `personaBinding: "missing"`。仍会尝试回退提供商。 |
|
||||
|
||||
只有在**每个**尝试的提供商都被跳过或失败时，整个 TTS 请求才会失败。
|
||||
只有当**所有**尝试的提供商都被跳过或失败时，整个 TTS 请求才会失败。
|
||||
|
||||
## 模型驱动指令
|
||||
|
||||
默认情况下，助手**可以**发出 `[[tts:...]]` 指令，为单次回复覆盖语音、模型或语速，还可以附加一个可选的 `[[tts:text]]...[[/tts:text]]` 块，用于只应出现在音频中的表现力提示：
|
||||
默认情况下，助手**可以**输出 `[[tts:...]]` 指令，为单次回复覆盖语音、模型或语速，还可以包含可选的 `[[tts:text]]...[[/tts:text]]` 块，用于只应出现在音频中的表现性提示：
|
||||
|
||||
```text
|
||||
Here you go.
|
||||
@ -563,20 +569,20 @@ Here you go.
|
||||
[[tts:text]](laughs) Read the song once more.[[/tts:text]]
|
||||
```
|
||||
|
||||
当 `messages.tts.auto` 为 `"tagged"` 时，**必须有指令**才会触发音频。流式分块交付会在渠道看到文本之前从可见文本中剥离指令，即使这些指令被拆分到相邻块中也是如此。
|
||||
当 `messages.tts.auto` 为 `"tagged"` 时，**必须有指令**才会触发音频。流式块交付会在渠道看到文本前从可见文本中剥离指令，即使这些指令被拆分在相邻块中也是如此。
|
||||
|
||||
除非 `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`
|
||||
- `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost`
|
||||
- `vol` / `volume`（MiniMax 音量，0–10）
|
||||
- `pitch`（MiniMax 整数音高，−12 到 12；小数值会被截断）
|
||||
- `emotion`（Volcengine 情绪标签）
|
||||
- `applyTextNormalization`（`auto|on|off`）
|
||||
- `applyTextNormalization` (`auto|on|off`)
|
||||
- `languageCode`（ISO 639-1）
|
||||
- `seed`
|
||||
|
||||
@ -594,7 +600,7 @@ Here you go.
|
||||
|
||||
## 斜杠命令
|
||||
|
||||
单个命令 `/tts`。在 Discord 上，OpenClaw 还会注册 `/voice`，因为 `/tts` 是一个内置 Discord 命令，文本 `/tts ...` 仍然可用。
|
||||
单个命令 `/tts`。在 Discord 上，OpenClaw 还会注册 `/voice`，因为 `/tts` 是 Discord 内置命令，文本 `/tts ...` 仍然可用。
|
||||
|
||||
```text
|
||||
/tts off | on | status
|
||||
@ -608,82 +614,78 @@ Here you go.
|
||||
```
|
||||
|
||||
<Note>
|
||||
命令需要授权发送者（适用允许列表/所有者规则），并且必须启用 `commands.text` 或原生命令注册。
|
||||
命令需要来自已授权发送者（适用 allowlist/owner 规则），并且必须启用 `commands.text` 或原生命令注册。
|
||||
</Note>
|
||||
|
||||
行为说明：
|
||||
|
||||
- `/tts on` 将本地 TTS 偏好设置写为 `always`；`/tts off` 将其写为 `off`。
|
||||
- `/tts chat on|off|default` 为当前聊天写入一个会话作用域的自动 TTS 覆盖项。
|
||||
- `/tts persona <id>` 写入本地人格偏好设置；`/tts persona off` 会清除它。
|
||||
- `/tts latest` 从当前会话转录中读取最新的助手回复，并将其作为音频发送一次。它只会在会话条目上存储该回复的哈希，以抑制重复语音发送。
|
||||
- `/tts audio` 生成一次性音频回复（**不会**开启 TTS）。
|
||||
- `/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 status` 包含最新尝试的回退诊断信息：`Fallback: <primary> -> <used>`、`Attempts: ...`，以及每次尝试的详细信息（`provider:outcome(reasonCode) latency`）。
|
||||
- `/status` 会在启用 TTS 时显示当前 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` | 本地人格覆盖项 |
|
||||
| `maxLength` | 摘要阈值（默认 `1500` 个字符） |
|
||||
| `summarize` | 摘要开关（默认 `true`） |
|
||||
| 存储字段 | 效果 |
|
||||
| ------------ | ---------------------------------------------- |
|
||||
| `auto` | 本地自动 TTS 覆盖项（`always`、`off`、…） |
|
||||
| `provider` | 本地主提供商覆盖项 |
|
||||
| `persona` | 本地 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`）。
|
||||
- 48kHz / 64kbps 是语音消息的良好折中。
|
||||
- **Feishu / WhatsApp**：当语音留言回复生成为 MP3/WebM/WAV/M4A
|
||||
或其他可能的音频文件时，渠道插件会先使用 `ffmpeg` 将其转码为 48kHz
|
||||
Ogg/Opus，然后再发送原生语音消息。WhatsApp 会通过 Baileys `audio`
|
||||
payload 发送结果，并带有 `ptt: true` 和 `audio/ogg; codecs=opus`。如果转换失败，Feishu 会收到原始
|
||||
- **支持语音便签的渠道**：语音便签回复优先使用 Opus（ElevenLabs 的 `opus_48000_64`，OpenAI 的 `opus`）。
|
||||
- 48kHz / 64kbps 是语音消息的良好权衡。
|
||||
- **Feishu / WhatsApp**：当语音便签回复生成为 MP3/WebM/WAV/M4A
|
||||
或其他可能的音频文件时，渠道插件会先用 `ffmpeg` 将其转码为 48kHz
|
||||
Ogg/Opus，再发送原生语音消息。WhatsApp 会通过 Baileys `audio` 负载发送
|
||||
结果，并设置 `ptt: true` 和 `audio/ogg; codecs=opus`。如果转换失败，Feishu 会收到原始
|
||||
文件作为附件；WhatsApp 发送会失败，而不是发布不兼容的
|
||||
PTT payload。
|
||||
- **BlueBubbles**：保持提供商合成走普通音频文件路径；MP3
|
||||
和 CAF 输出会标记为 iMessage 语音备忘录投递。
|
||||
PTT 负载。
|
||||
- **BlueBubbles**：让提供商合成走常规音频文件路径；MP3
|
||||
和 CAF 输出会被标记为用于 iMessage 语音备忘录投递。
|
||||
- **其他渠道**：MP3（ElevenLabs 的 `mp3_44100_128`，OpenAI 的 `mp3`）。
|
||||
- 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 语音留言格式。
|
||||
- **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 重试。
|
||||
- 如果配置的 Microsoft 输出格式失败，OpenClaw 会用 MP3 重试。
|
||||
|
||||
OpenAI/ElevenLabs 输出格式按渠道固定（见上文）。
|
||||
|
||||
## 自动 TTS 行为
|
||||
## Auto-TTS 行为
|
||||
|
||||
启用 `messages.tts.auto` 时，OpenClaw 会：
|
||||
|
||||
- 如果回复已经包含媒体或 `MEDIA:` 指令，则跳过 TTS。
|
||||
- 跳过非常短的回复（少于 10 个字符）。
|
||||
- 启用摘要时，会使用
|
||||
- 如果回复已包含媒体或 `MEDIA:` 指令，则跳过 TTS。
|
||||
- 跳过很短的回复（少于 10 个字符）。
|
||||
- 在启用摘要时，使用
|
||||
`summaryModel`（或 `agents.defaults.model.primary`）总结长回复。
|
||||
- 将生成的音频附加到回复中。
|
||||
- 在 `mode: "final"` 中，对于流式最终回复，仍会在
|
||||
文本流完成后发送仅音频 TTS；生成的媒体会通过与普通回复附件相同的
|
||||
渠道媒体标准化流程。
|
||||
- 将生成的音频附加到回复。
|
||||
- 在 `mode: "final"` 中，对于流式传输的最终回复，仍会在文本流完成后发送仅音频的 TTS；生成的媒体会经过与普通回复附件相同的渠道媒体规范化流程。
|
||||
|
||||
如果回复超过 `maxLength` 且摘要已关闭（或摘要模型没有 API key），
|
||||
则跳过音频并发送普通文本回复。
|
||||
如果回复超过 `maxLength` 且摘要关闭（或摘要模型没有 API key），则会跳过音频，并发送普通文本回复。
|
||||
|
||||
```text
|
||||
Reply -> TTS enabled?
|
||||
@ -699,57 +701,57 @@ Reply -> TTS enabled?
|
||||
|
||||
## 按渠道划分的输出格式
|
||||
|
||||
| 目标 | 格式 |
|
||||
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 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。
|
||||
- **本地 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 重试。
|
||||
- **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/电话使用 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 重试。
|
||||
|
||||
OpenAI 和 ElevenLabs 输出格式按上方所列为每个渠道固定。
|
||||
OpenAI 和 ElevenLabs 输出格式按上方所列渠道固定。
|
||||
|
||||
## 字段参考
|
||||
## 字段参考
|
||||
|
||||
<AccordionGroup>
|
||||
<AccordionGroup>
|
||||
<Accordion title="Top-level messages.tts.*">
|
||||
<ParamField path="auto" type='"off" | "always" | "inbound" | "tagged"'>
|
||||
自动 TTS 模式。`inbound` 仅在收到入站语音消息后发送音频；`tagged` 仅在回复包含 `[[tts:...]]` 指令或 `[[tts:text]]` 块时发送音频。
|
||||
Auto-TTS 模式。`inbound` 只会在收到入站语音消息后发送音频；`tagged` 只会在回复包含 `[[tts:...]]` 指令或 `[[tts:text]]` 块时发送音频。
|
||||
</ParamField>
|
||||
<ParamField path="enabled" type="boolean" deprecated>
|
||||
旧版开关。`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"`。
|
||||
</ParamField>
|
||||
<ParamField path="persona" type="string">
|
||||
来自 `personas` 的活动 persona ID。会规范化为小写。
|
||||
来自 `personas` 的活动角色 ID。会规范化为小写。
|
||||
</ParamField>
|
||||
<ParamField path="personas.<id>" type="object">
|
||||
稳定的口语身份。字段：`label`、`description`、`provider`、`fallbackPolicy`、`prompt`、`providers.<provider>`。参见 [Personas](#personas)。
|
||||
稳定的语音身份。字段：`label`、`description`、`provider`、`fallbackPolicy`、`prompt`、`providers.<provider>`。参见 [Personas](#personas)。
|
||||
</ParamField>
|
||||
<ParamField path="summaryModel" type="string">
|
||||
用于自动摘要的低成本模型；默认为 `agents.defaults.model.primary`。接受 `provider/model` 或已配置的模型别名。
|
||||
用于自动摘要的低成本模型；默认使用 `agents.defaults.model.primary`。接受 `provider/model` 或已配置的模型别名。
|
||||
</ParamField>
|
||||
<ParamField path="modelOverrides" type="object">
|
||||
允许模型发出 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">
|
||||
请求超时时间，单位为毫秒。
|
||||
@ -766,7 +768,7 @@ Reply -> TTS enabled?
|
||||
<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="voiceNoteOutputFormat" type="string">语音便签输出的 Azure `X-Microsoft-OutputFormat`。默认 `ogg-24khz-16bit-mono-opus`。</ParamField>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="ElevenLabs">
|
||||
@ -774,53 +776,53 @@ Reply -> TTS enabled?
|
||||
<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="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="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>
|
||||
<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`，以确定性的 Gemini TTS 提示结构包装活动角色提示字段。</ParamField>
|
||||
<ParamField path="personaPrompt" type="string">附加到模板导演注释中的 Google 专用额外角色提示文本。</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="baseUrl" type="string">默认值 `https://api.gradium.ai`。</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="voiceId" type="string">默认值为 `Sarah`。</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="voiceId" type="string">默认值 `Sarah`。</ParamField>
|
||||
<ParamField path="temperature" type="number">采样温度 `0..2`。</ParamField>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="本地 CLI (tts-local-cli)">
|
||||
<Accordion title="Local 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（无 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="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>
|
||||
@ -830,73 +832,73 @@ Reply -> TTS enabled?
|
||||
|
||||
<Accordion title="MiniMax">
|
||||
<ParamField path="apiKey" type="string">回退到 `MINIMAX_API_KEY`。Token Plan 认证可通过 `MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY` 或 `MINIMAX_CODING_API_KEY`。</ParamField>
|
||||
<ParamField path="baseUrl" type="string">默认值为 `https://api.minimax.io`。环境变量：`MINIMAX_API_HOST`。</ParamField>
|
||||
<ParamField path="model" type="string">默认值为 `speech-2.8-hd`。环境变量：`MINIMAX_TTS_MODEL`。</ParamField>
|
||||
<ParamField path="voiceId" type="string">默认值为 `English_expressive_narrator`。环境变量：`MINIMAX_TTS_VOICE_ID`。</ParamField>
|
||||
<ParamField path="speed" type="number">`0.5..2.0`。默认值为 `1.0`。</ParamField>
|
||||
<ParamField path="vol" type="number">`(0, 10]`。默认值为 `1.0`。</ParamField>
|
||||
<ParamField path="pitch" type="number">整数 `-12..12`。默认值为 `0`。小数值会在请求前被截断。</ParamField>
|
||||
<ParamField path="baseUrl" type="string">默认值 `https://api.minimax.io`。环境变量：`MINIMAX_API_HOST`。</ParamField>
|
||||
<ParamField path="model" type="string">默认值 `speech-2.8-hd`。环境变量：`MINIMAX_TTS_MODEL`。</ParamField>
|
||||
<ParamField path="voiceId" type="string">默认值 `English_expressive_narrator`。环境变量：`MINIMAX_TTS_VOICE_ID`。</ParamField>
|
||||
<ParamField path="speed" type="number">`0.5..2.0`。默认值 `1.0`。</ParamField>
|
||||
<ParamField path="vol" type="number">`(0, 10]`。默认值 `1.0`。</ParamField>
|
||||
<ParamField path="pitch" type="number">整数 `-12..12`。默认值 `0`。请求前会截断小数值。</ParamField>
|
||||
</Accordion>
|
||||
|
||||
<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="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="instructions" type="string">显式 OpenAI `instructions` 字段。设置后，persona prompt 字段**不会**自动映射。</ParamField>
|
||||
<ParamField path="extraBody / extra_body" type="Record<string, unknown>">额外 JSON 字段，会在生成的 OpenAI TTS 字段之后合并进 `/audio/speech` 请求体。可用于 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>
|
||||
|
||||
<Accordion title="OpenRouter">
|
||||
<ParamField path="apiKey" type="string">环境变量：`OPENROUTER_API_KEY`。可复用 `models.providers.openrouter.apiKey`。</ParamField>
|
||||
<ParamField path="baseUrl" type="string">默认值为 `https://openrouter.ai/api/v1`。旧版 `https://openrouter.ai/v1` 会被规范化。</ParamField>
|
||||
<ParamField path="model" type="string">默认值为 `hexgrad/kokoro-82m`。别名：`modelId`。</ParamField>
|
||||
<ParamField path="voice" type="string">默认值为 `af_alloy`。别名：`voiceId`。</ParamField>
|
||||
<ParamField path="responseFormat" type='"mp3" | "pcm"'>默认值为 `mp3`。</ParamField>
|
||||
<ParamField path="baseUrl" type="string">默认值 `https://openrouter.ai/api/v1`。旧版 `https://openrouter.ai/v1` 会被规范化。</ParamField>
|
||||
<ParamField path="model" type="string">默认值 `hexgrad/kokoro-82m`。别名：`modelId`。</ParamField>
|
||||
<ParamField path="voice" type="string">默认值 `af_alloy`。别名：`voiceId`。</ParamField>
|
||||
<ParamField path="responseFormat" type='"mp3" | "pcm"'>默认值 `mp3`。</ParamField>
|
||||
<ParamField path="speed" type="number">提供商原生速度覆盖。</ParamField>
|
||||
</Accordion>
|
||||
|
||||
<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">应用密钥头。默认值为 `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">App key 标头。默认值 `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="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="appId / token / cluster" type="string" deprecated>旧版 Volcengine Speech Console 字段。环境变量：`VOLCENGINE_TTS_APPID`、`VOLCENGINE_TTS_TOKEN`、`VOLCENGINE_TTS_CLUSTER`（默认值为 `volcano_tts`）。</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="language" type="string">BCP-47 语言代码或 `auto`。默认值为 `en`。</ParamField>
|
||||
<ParamField path="responseFormat" type='"mp3" | "wav" | "pcm" | "mulaw" | "alaw"'>默认值为 `mp3`。</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="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>
|
||||
</Accordion>
|
||||
|
||||
<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="voice" type="string">默认值为 `mimo_default`。环境变量：`XIAOMI_TTS_VOICE`。</ParamField>
|
||||
<ParamField path="format" type='"mp3" | "wav"'>默认值为 `mp3`。环境变量：`XIAOMI_TTS_FORMAT`。</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="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>
|
||||
</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 语音备注（带有 `ptt: true` 的 `audio`）发送，并且会将可见文本与 PTT 音频**分开发送**，因为客户端不能稳定地在语音备注上呈现标题。
|
||||
WhatsApp 会通过 Baileys 将音频作为 PTT 语音便签发送（带有 `ptt: true` 的 `audio`），并且会将可见文本与 PTT 音频**分开发送**，因为客户端无法稳定渲染语音便签上的字幕。
|
||||
|
||||
该工具接受可选的 `channel` 和 `timeoutMs` 字段；`timeoutMs` 是每次调用的提供商请求超时时间，单位为毫秒。
|
||||
|
||||
## Gateway RPC
|
||||
## Gateway 网关 RPC
|
||||
|
||||
| 方法 | 用途 |
|
||||
| ----------------- | ---------------------------------------- |
|
||||
@ -925,7 +927,7 @@ WhatsApp 通过 Baileys 将音频作为 PTT 语音备注（带有 `ptt: true`
|
||||
- [Microsoft Speech 输出格式](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)
|
||||
- [xAI 文本转语音](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest)
|
||||
|
||||
## 相关
|
||||
## 相关内容
|
||||
|
||||
- [媒体概览](/zh-CN/tools/media-overview)
|
||||
- [音乐生成](/zh-CN/tools/music-generation)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user