跳转至

语音和言语

语音与语音

语音合成(TTS)
捆绑的 `openai` 插件为 `tts` 表面注册语音合成。

| 设置      | 配置路径                                            | 默认值                          |
| ------------- | --------------------------------------------------------- | ----------------------------------- |
| 模型        | `tts.providers.openai.model`                  | `gpt-4o-mini-tts`                |
| 语音        | `tts.providers.openai.speakerVoice`           | `coral`                          |
| 速度        | `tts.providers.openai.speed`                  | (未设置)                          |
| 指令        | `tts.providers.openai.instructions`           | (未设置,仅限 `gpt-4o-mini-tts` 系列)  |
| 格式        | `tts.providers.openai.responseFormat`         | `opus` 用于语音笔记,`mp3` 用于文件 |
| API 密钥      | `tts.providers.openai.apiKey`                 | 回退到 `OPENAI_API_KEY`   |
| 基础 URL     | `tts.providers.openai.baseUrl`                | `https://api.openai.com/v1`      |
| 额外请求体   | `tts.providers.openai.extraBody` / `extra_body` | (未设置)                        |

可用模型:`gpt-4o-mini-tts`、`gpt-4o-mini-tts-2025-12-15`、`tts-1`、
`tts-1-hd`。可用语音:`alloy`、`ash`、`ballad`、`cedar`、`coral`、
`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、
`verse`。

`extraBody` 会在 OpenClaw 生成的字段之后合并到 `/audio/speech` 请求 JSON 中,
因此请将其用于需要额外键(例如 `lang`)的 OpenAI 兼容端点。原型键会被忽略。

```json5
{
  tts: {
    providers: {
      openai: { model: "gpt-4o-mini-tts", speakerVoice: "coral" },
    },
  },
}
```

Note

设置 OPENAI_TTS_BASE_URL 可覆盖 TTS 基础 URL,而不影响聊天 API 端点。 OpenAI TTS 需要 OpenAI Platform API 密钥。 仅 OAuth 安装在账户具有访问权限时,可以使用基于 Codex 的聊天模型, 以及通过 ChatGPT 订阅使用的 GA Realtime browser Talk(参见 Realtime 折叠面板)。 OpenAI TTS 以及 GA Realtime Voice Call、Gateway 中继和 Discord 会话 仍需要 Platform API 密钥。Codex GPT-Live 通过共享的 Gateway 拥有的桥接支持 ChatGPT OAuth, 包括 Discord 和 Voice Call。

语音转文本

捆绑的 openai 插件通过 OpenClaw 的媒体理解转录表面注册批量语音转文本。

当账户允许时,批量转录可以在标准转录端点上使用所选的 OpenAI API-key 或 ChatGPT OAuth 配置文件。已配置的模型、提示词和语言提示通过同一请求路径生效。访问和配额错误会直接报告, 而不会切换凭据类型;支持 OAuth 并不意味着包含在内或无限转录。 自定义端点和请求覆盖需要 API-key 配置文件。 如需选择单独的音频 API-key 配置文件,请参见 音频和语音笔记。

  • 默认模型:gpt-4o-transcribe
  • 端点:OpenAI REST /v1/audio/transcriptions
  • 输入路径:multipart 音频文件上传
  • 用于任何入站音频转录读取 tools.media.audio 的地方, 包括 Discord 语音频道片段和频道音频附件

要强制入站音频转录使用 OpenAI:

{
  tools: {
    media: {
      models: [
        {
          type: "provider",
          provider: "openai",
          model: "gpt-4o-transcribe",
          capabilities: ["audio"],
        },
      ],
      audio: {
        enabled: true,
      },
    },
  },
}

当共享音频媒体配置或每次调用的转录请求提供语言提示和提示词提示时, 它们会被转发给 OpenAI。

实时转录
捆绑的 `openai` 插件为 Voice Call 插件注册实时转录。

| 设置          | 配置路径                                                          | 默认值 |
| ----------------- | ----------------------------------------------------------------------- | --------- |
| 模型            | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
| 语言         | `...openai.language`                                                 | (未设置) |
| 提示词           | `...openai.prompt`                                                   | (未设置) |
| 静音时长 | `...openai.silenceDurationMs`                                        | `800`   |
| VAD 阈值    | `...openai.vadThreshold`                                             | `0.5`   |
| 认证             | `...openai.apiKey`、`OPENAI_API_KEY` 或 `openai` API-key 配置文件    | 需要 Platform API 密钥 |

Note

使用到 wss://api.openai.com/v1/realtime 的 WebSocket 连接, 音频为 G.711 u-law(g711_ulaw / audio/pcmu)。对于 openai API-key 配置文件,Gateway 会在打开 WebSocket 之前生成一个临时的 Realtime 转录客户端密钥。 此流式提供商用于 Voice Call 的实时转录路径;Discord 语音记录短片段, 并改用批量 tools.media.audio 转录路径。

实时语音
捆绑的 `openai` 插件为 Voice Call 插件注册实时语音。

| 设置                               | 配置路径                                                              | 默认值             |
设置 配置路径 默认值
--------------------------------------- ---------------------------------------------------------------------------- ----------------------
模型 plugins.entries.voice-call.config.realtime.providers.openai.model gpt-realtime-2.1
语音 ...openai.voice alloy
温度(Azure 部署桥接) ...openai.temperature 0.8
VAD 阈值 ...openai.vadThreshold 0.5
静音时长 ...openai.silenceDurationMs 500
前缀填充 ...openai.prefixPaddingMs 300
推理强度 ...openai.reasoningEffort (未设置)
身份验证 openai 身份验证配置文件、...openai.apiKey 或 OPENAI_API_KEY GPT-Live API:需要 Platform;Codex GPT-Live:优先 OAuth;普通 GA 浏览器:优先 Platform
    可用于 `gpt-realtime-2.1` 的内置 Realtime 语音:`alloy`、`ash`、
    `ballad`、`coral`、`echo`、`sage`、`shimmer`、`verse`、`marin`、`cedar`。
    OpenAI 推荐 `marin` 和 `cedar` 以获得最佳 Realtime 质量。这与
    上述文本转语音语音是不同的一组;仅用于 TTS 的语音(例如 `fable`、`nova` 或 `onyx`)
    不适用于 Realtime 会话。如果你偏好更小、成本更低的 Realtime 2.1 变体,
    请显式将模型设置为 `gpt-realtime-2.1-mini`。

    #### 自定义 Realtime 端点 {#custom-realtime-endpoints}

    将 `talk.realtime.providers.openai.baseUrl` 设置为 OpenAI Realtime 兼容服务器的完整 WebSocket 端点,
    并选择 `gateway-relay`。保持 `provider: "openai"`:自定义 URL 不会注册新的 provider。

    ```json5
    {
      talk: {
        realtime: {
          provider: "openai",
          transport: "gateway-relay",
          model: "your-realtime-model",
          providers: {
            openai: {
              apiKey: "${REALTIME_API_KEY}",
              baseUrl: "wss://voice.example.com/custom/realtime?realtime=true",
            },
          },
        },
      },
    }
    ```

    默认值为 `wss://api.openai.com/v1/realtime`。URL 的路径和查询参数会被保留;
    OpenClaw 会根据所选模型设置 `model` 查询参数。适用标准 URL 解析;对于签名端点,
    请使用正确 URL 编码的查询。包含完整的端点路径,而不仅仅是 `/v1` 这样的 API 根路径。
    `https:` 和 `http:` URL 会分别转换为 `wss:` 和 `ws:`。在受信任的本地网络之外优先使用 TLS。
    包含嵌入凭据或片段的 URL 会被拒绝。

    相同的 `baseUrl` 选项也可用于 Voice Call 和其他 Gateway 侧语音桥接的 OpenAI realtime provider 块。
    它不会更改聊天、转录或 TTS 端点。当自定义端点没有显式模型时,仍会使用 GA Realtime 默认值,
    而不是 GPT-Live。

    这是服务器端 Realtime WebSocket 覆盖,而不是一般的协议适配器:该服务必须支持 OpenClaw 的 Realtime 会话事件、
    音频格式、语音和工具。不隐含特定 provider 的兼容性,包括 DashScope。API 密钥保留在 Gateway 上,
    并直接对套接字进行身份验证;不需要浏览器客户端密钥端点。浏览器 WebRTC、GPT-Live 和 Azure 端点/部署设置
    不能与此覆盖组合。这些组合会失败,而不是将凭据或音频发送到默认 OpenAI 端点。

    #### Gateway 控制的 Realtime 通话清理 {#gateway-controlled-realtime-call-cleanup}

    关闭 Gateway 控制的 GA Realtime WebRTC 会话会使其 Gateway 权限失效,并在请求 OpenAI 挂断 provider 通话之前
    关闭本地 sideband。这些是独立事件;控制关闭不会建立 provider 确认,也不会召回已排队媒体。

    如果挂断失败,显式取消或清理会报告失败。broker 会在 1 秒后自动重试,然后在 5 秒后重试,
    每次尝试使用现有的 30 秒超时。在所有三次尝试失败后,日志会报告 `cleanup INCOMPLETE`。
    确切的清理义务及其容量仍被保留,包括跨插件替换:全局八个会话,每个 Gateway 客户端两个。
    恢复 provider 连接;稍后的 OpenAI broker/插件运行时清理可以重试这些保留的通话。
    重复 End 或 `talk.client.close` 不是该重试边界,因为 Gateway 会话可能已经失效。

    清理义务仅存在于内存中。Gateway 退出、崩溃或重启可能会丢失它们;重启并不能证明 provider 通话已结束。
    适配器的 30 分钟活动会话租约不是远程生命周期保证,也不是挂断失败后的回退。

    #### GA Realtime 浏览器身份验证 {#ga-realtime-browser-authentication}

    普通 GA 浏览器 Talk 会按以下顺序优先尝试 Platform 身份验证:已配置的 realtime 密钥、
    `openai` API-key 配置文件,然后是 `OPENAI_API_KEY`。当 Platform 凭据可用时,
    Gateway 会签发一个临时客户端密钥,浏览器直接执行 SDP 交换。

当未配置 Platform 凭证来源时,普通的 GA 浏览器 Talk 会回退到 OpenClaw ChatGPT OAuth 订阅配置文件。一次性使用的 Gateway offer 代理将 OAuth 保留在服务端,交换浏览器的 SDP,并且只返回 answer SDP。显式配置但不可用的 Platform 凭证会导致失败,而不是回退到 OAuth。

Gateway 控制的 GA 中继、iOS 客户端自有的 WebRTC、GA Voice Call、直接后端套接字以及 GA Discord 实时语音都需要 Platform 认证。

GPT-Live API

Talk 和 Gateway 中继会话在未配置模型时会选择 GPT-Live。OpenAI Platform 密钥、API-key 配置文件或 OPENAI_API_KEY 会选择 gpt-live-1 并使用 marin;仅 ChatGPT 账户会选择 gpt-live-1-codex 并使用 cove。已配置的 Platform 凭证优先于 ChatGPT 登录,即使该凭证需要修复也是如此。

GPT-Live 仅支持音频,因此 Control UI 在此默认设置下不提供摄像头采集。要使用摄像头,请显式选择 gpt-realtime-2.1。talk.catalog 描述所配置 Talk 代理为其发现面提供的默认设置;作用域为另一个代理的会话在启动时会解析该代理的账户。

显式选择的模型以及该模型支持的语音仍然有效;显式选择 GPT-Live 模型即为仅音频。要求视频或强制代理咨询回复的请求在未固定模型时保留 gpt-realtime-2.1。未使用显式模型的直接工具桥接、Discord 和 Voice Call,以及 Azure 部署保留其现有默认设置。Discord 或 Voice Call 中显式使用 GPT-Live 模型会使用共享的 Gateway 中继桥接和提供商自有委派。安装更新不会重写已保存的配置,也不会切换活动会话。

对于公开的 GPT-Live API,请将 talk.realtime.model 显式设置为 gpt-live-1。GPT-Live 负责语音对话,而委派任务则通过你配置的 OpenClaw 代理运行。它可以边说话边收听;打断语音本身并不会取消代理工作。

该模型需要具有模型访问权限的 OpenAI Platform API 密钥,可从已配置的 realtime 密钥、openai API-key 配置文件或 OPENAI_API_KEY 中选择。ChatGPT 订阅凭证不能作为 gpt-live-1 的回退。

{
  talk: {
    realtime: {
      provider: "openai",
      model: "gpt-live-1",
      speakerVoice: "marin",
      transport: "webrtc",
    },
  },
}

浏览器 Talk 使用 Gateway 中介的 WebRTC;Platform 密钥保留在 Gateway 上。对于直接服务器 WebSocket 路径,请设置 transport: "gateway-relay"。Discord 实时语音和 Voice Call 与 gpt-live-1 一起使用相同的 Gateway 拥有的直接 WebSocket 桥接和原生代理委派。

iOS 使用相同的中介 WebRTC 路径,并显示公开的 Live 字幕。物理设备语音验证仍处于待定状态。

默认语音为 marin。支持的内置语音包括 alloy、ash、ballad、beacon、bossa、cedar、cinder、coral、delta、echo、gleam、marin、meridian、quartz、ripple、sage、shimmer、stone、tempo、verse、vesper 和 willow。不支持的已配置语音会回退到 marin。在开始会话之前选择语音。cove 属于 gpt-live-1-codex;将其与公开的 gpt-live-1 模型一起选择会回退到 marin。

公开 API 使用 /v1/live/sessions 进行 WebRTC 创建和主 WebSocket。直接套接字以 session.start 开始;浏览器会话在 SDP 交换期间开始。Gateway 侧带处理委派工作,而浏览器媒体保留在 WebRTC 上。公开 Live 指令将 session.thinking.append 描述为静默上下文,将 session.commentary.append 描述为语音更新。自定义指令应保留这种区别;Codex 路由使用其单独的 commentary/speakable 通道契约。

两条路由都指示语音模型等待委派结果,而不是重复相同的后端请求。新的用户追问、更正和显式重试仍然允许。这些指令仅指导模型行为;它们不保证每个请求只执行一次。

公开的转录事件是片段,而不是完整的轮次。Gateway 拥有有界接收文本快照的持久化;客户端显示字幕而不另存副本。实时字幕和已保存快照都可能跨越同一说话者的多次交流;它们不会重建时间顺序上的轮次或跨说话者的时间安排。重叠的片段不能标识一个完整的语句。保存文本并不表示语音或播放已经结束。有关公开会话和语音契约,请参阅 OpenAI 的 会话指南。

已发布的 GPT-Live 浏览器与 Gateway 中继身份验证

独立的 Codex GPT-Live 模型 gpt-live-1-codex 保留其 ChatGPT 订阅路由。其浏览器和 Gateway 中继 WebRTC 首先尝试 OpenClaw ChatGPT OAuth 订阅配置文件。当 OAuth 不可用时,Gateway 按以下顺序回退到 Platform 认证:已配置的 realtime 密钥、openai API-key 配置文件,然后是 OPENAI_API_KEY。使用 openclaw models auth login --provider openai 创建 OAuth 配置文件。

当 channels.discord.voice.realtime.model 为 gpt-live-1-codex 时,Discord 使用相同的 Gateway 拥有的 WebRTC 桥接。将 channels.discord.voice.realtime.speakerVoice 设置为 cove 以使用 Codex 默认语音。其他支持的语音包括 arbor、breeze、ember、juniper、maple、sol、spruce 和 vale。语音选择特定于其模型路由,无论客户端是 Talk、Discord 还是 Voice Call。

当 plugins.entries.voice-call.config.realtime.providers.openai.model 为 gpt-live-1-codex 时,Voice Call 使用同一个支持 OAuth 的桥接;在该 provider 块中设置 voice: "cove"。其音频适配器将运营商 G.711 mu-law 8 kHz 音频与模型的 24 kHz PCM 流相互转换,适用于 WebRTC 和直接 WebSocket 两种路由。初始问候语和 voicecall.speak 请求使用原生会话上下文。

GPT-Live 两条路由都会产生连续音频并自行处理中断。Gateway WebSocket 和 WebRTC 使用相同的采样时钟,以录制速率发送麦克风输入,并在采集间隙提供静音。Discord 不添加发言者开始取消逻辑,也不会等待响应完成事件才播放简短回复。显式设置 Discord requireWakeName: true 或 consultPolicy: "always" 会被拒绝,因为 GPT-Live 无法强制执行这些主机策略;其默认使用自动 provider 委派。每位发言者的委派工作保留其 Discord 身份和权限。共享的 OpenClaw agent 对话提供房间上下文,而每位发言者的语音模型连接具有独立的声学对话历史。参见 Discord 中的 GPT-Live。

Voice Call 还会在 Live 播放期间保持麦克风输入开启,并且不添加主机说话开始取消。原生委派使用调用方已有的 agent 咨询,包括其工具策略和取消生命周期。对于 GPT-Live,显式设置 realtime.consultPolicy: "always" 会被拒绝。openclaw_end_call 和自定义 realtime.tools 需要原生函数工具支持,在 GPT-Live 上仍然不可用;委派不会暴露它们。参见 Voice Call 中的 GPT-Live。

两种凭据类型都保留在 Gateway 中。一次性 offer broker 交换浏览器的 SDP,并且只返回 answer SDP;它不会向浏览器发送 OAuth token、Platform key 或临时客户端密钥。

Gateway-relay WebRTC 以连续采样时钟为基准调节麦克风音频的发送节奏,因此在较长的通话中计时器延迟不会累积。在调度器暂停之后,排队的音频以正常节奏恢复,同时时间戳考虑经过的间隙。通话会隐藏格式错误的传入音频数据包,并继续播放后续音频。单个音频数据包发送被拒绝不会结束原本已连接的通话。不可用的编解码器状态、意外的流更改以及终态连接状态仍然会结束通话。丢包诊断不会显示原始错误详细信息。

已启用的 OpenAI 插件会自动启动 broker,即使在 Gateway 启动之后您才登录也会如此。broker 仅在您启动语音会话时打开 provider 会话;登录不会打开麦克风或加入 Discord 语音。登录后返回浏览器会刷新聊天麦克风的就绪状态。

未列出和私有的实时传输路径

未列出或私有的浏览器 Talk 使用带有 Gateway 所属控制的 Platform-key 客户端 WebRTC。Gateway relay 和其他直接后端消费者使用 Platform-key 双向传输。凭据和 provider 控制仍保留在 Gateway 上。

使用账户发放的实时模型值。未列出的模型值可作为自由格式的 Talk 配置接受,但不会通过目录或诊断信息发布。通过 talk.realtime.model 显式选择启用;正式发布的模型仍为默认值。

当前的 Platform-key 会话接受 marin 和 cedar。OpenClaw 默认使用 marin,并将不支持的已配置语音映射回 marin。

未列出或私有的浏览器 WebRTC 先决条件,按顺序如下:

  1. 通过 talk.realtime.providers.openai.apiKey、openai API 密钥配置文件或 OPENAI_API_KEY 配置的 Platform API 密钥。
  2. 将 talk.realtime.model 设置为账户发放的值 — 可通过 Control UI 中的 Settings → Talk 或下面的配置完成。
  3. 捆绑的 openai 插件以完整模式注册。限制性的 plugins.allow 列表会失败,提示 "OpenAI realtime browser session broker is unavailable"。
{
  talk: {
    realtime: {
      provider: "openai",
      model: "<account-issued-realtime-model>",
      transport: "webrtc",
    },
  },
}

Gateway relay 使用直接双向传输:

{
  talk: {
    realtime: {
      provider: "openai",
      model: "<account-issued-realtime-model>",
      transport: "gateway-relay",
    },
  },
}

浏览器 Talk 使用 transport: "webrtc"。

使用方 未列出/私有路由状态
Browser Talk 支持 Platform-key 客户端 WebRTC 和 Gateway 所属边带
Gateway-relay Talk 支持直接 Platform-key 传输
Discord 双向语音 支持 Platform-key 后端 WebSocket
Voice Call 与电话 支持 Platform-key 后端 WebSocket
iOS 客户端自有 Talk 已实现;设备实机验证待定
Android 实时 Talk 待 Android 设备实机验证通过后切换;Android 暂保持原生 Talk

这些行描述的是已实现的传输,而非账户授权或完整的模型能力对等。在为这些使用方选择未列出或私有路由之前,请参阅 Discord 语音策略限制 和 Voice Call 工具限制。

Warning

未列出或私有路由需要使用 Platform API 密钥,且该密钥须有权访问所配置的账户签发模型。OAuth 不是它们的回退方案。如果会话创建被拒绝,请确认该密钥和所配置的模型属于同一个 Platform 项目。

`403 Voice session access denied` 响应具有多重含义,仅凭该响应本身并不能证明账户权限问题:无效语音也会产生相同的响应。请先将模型和语音与上述可接受列表进行核对,再确认 Platform 密钥和所配置的模型属于同一个项目。

Codex GPT-Live 的 Gateway 持有 WebRTC 路由优先使用 OAuth,并以 Platform 作为回退;它通过已配置的 OpenClaw 代理路由边带委派,并避免向中继客户端暴露凭证。未列出或私有的浏览器 WebRTC 以及直接后端套接字仍仅限 Platform 凭证。直接套接字支持 Discord 语音以及 Voice Call/电话;OpenClaw 将 G.711 u-law 电话音频与提供商的 24 kHz PCM 流进行相互转换。Android 的客户端侧闸门保持关闭,直到 Gateway 中继路径获得来自 Android 设备的实时证明。

WebRTC 路径会创建提供商呼叫并加入其边带。直接未列出/私有后端路径会打开一个双向会话,发送 Frameless `session.update`,然后通过该套接字传输 PCM 音频、转录文本、委派及委派结果。

维护者可以通过选择加入的实时测试来演练 Platform 直接路径和独立的 GA 浏览器 OAuth 路径。账户签发的实时模型从 `talk.realtime.model` 读取;缺少凭证或模型配置会产生脱敏跳过,且这些测试从不打印这两个值中的任何一个:

```bash
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_GPT_LIVE=1 node --import tsx scripts/test-live.mts -- extensions/openai/realtime-quicksilver.live.test.ts
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_GPT_LIVE=1 node --import tsx scripts/test-live.mts -- extensions/openai/realtime-quicksilver-gateway-bridge.live.test.ts
```

Note

GA 后端的 OpenAI 实时桥接使用 Realtime WebSocket 会话结构,该结构不接受 session.temperature;公共 GPT-Live API 使用其自身的 Live 会话结构,而 Codex 以及未列出/私有路由则保留各自独立的传输契约。Azure OpenAI 部署仍可通过 azureEndpoint 和 azureDeployment 使用,并保持与部署兼容的会话结构(包括 temperature)。支持双向工具调用和 G.711 u-law 音频。

Note

实时语音在会话创建时选定。GA Realtime 允许此后更改大多数会话字段,但在模型发出音频后,语音便无法更改。GPT-Live 在启动时固定其模型、语音、音频格式和委派模式。OpenClaw 将内置的 Realtime 语音 ID 以字符串形式公开。

Note

Control UI Talk 使用浏览器 WebRTC 会话。Codex GPT-Live 的浏览器/Gateway 持有路由通过 Gateway 的 offer 代理首先尝试 ChatGPT OAuth,并将 OAuth 保留在服务端。当 OAuth 不可用时,它会按以下顺序回退到 Platform 凭证:已配置的实时密钥、API 密钥配置文件,然后是 OPENAI_API_KEY。公共 gpt-live-1 API、直接后端套接字以及未列出或私有实时路由都需要 Platform 凭证。维护者可通过 OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts 进行实时验证;OpenAI 分支会验证后端 WebSocket 桥接、合成的 PCM24 语音到响应音频往返,以及浏览器 WebRTC SDP 交换,且不会记录机密。传入 --openai-only 可在没有 Google 凭证的情况下运行这些分支。使用 --openai-audio-cycles 3 进行短时间的重复连接、对讲和关闭浸泡测试。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw