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