语音和言语

语音与言语¶

捆绑的 `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" },
    },
  },
}
```

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

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

| 设置          | 配置路径                                                          | 默认值 |
| ----------------- | ----------------------------------------------------------------------- | --------- |
| 模型            | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
| 语言         | `...openai.language`                                                 | （未设置） |
| Prompt           | `...openai.prompt`                                                   | （未设置） |
| 静音时长 | `...openai.silenceDurationMs`                                        | `800`   |
| VAD 阈值    | `...openai.vadThreshold`                                             | `0.5`   |
| 认证             | `...openai.apiKey`、`OPENAI_API_KEY` 或 `openai` API 密钥配置    | 需要平台 API 密钥 |

捆绑的 `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 质量。这与上面提到的文本转语音（Text-to-speech）语音是独立的一套；仅用于 TTS 的语音（如 fable、nova 或 onyx）不能用于 Realtime 会话。

如果你偏好更小、成本更低的 Realtime 2.1 变体，请将模型显式设置为 gpt-realtime-2.1-mini。

网关控制的 Realtime 通话清理¶

关闭由网关控制的 GA Realtime WebRTC 会话时，会在请求 OpenAI 挂断提供商通话之前，先撤销其 Gateway 权限并关闭本地 sideband。这些是独立的事件；控制关闭并不构成提供商的确认，也不会撤回已排队的媒体。

如果挂断失败，显式取消或清理会报告失败。broker 会在 1 秒后自动重试，然后在 5 秒后再次重试，每次尝试仍使用现有的 30 秒超时。三次尝试全部失败后，日志会报告 cleanup INCOMPLETE。确切的清理义务及其容量会继续保留，即使在插件替换之后也是如此：全局 8 个会话，每个 Gateway 客户端 2 个。恢复提供商连接后，后续的 OpenAI broker/插件运行时清理可以重试这些保留的通话。重复执行 End 或 talk.client.close 并不是这个重试边界，因为 Gateway 会话可能已经被撤销。

清理义务仅保存在内存中。Gateway 退出、崩溃或重启可能会导致其丢失；重启并不能证明提供商通话已经结束。适配器的 30 分钟活动会话租约不是远程生命周期保证，也不是挂断失败后的回退方案。

GA Realtime 浏览器身份验证¶

普通 GA 浏览器 Talk 会按以下顺序首先尝试 Platform 认证：已配置的 realtime 密钥、openai API-key 配置文件，然后是 OPENAI_API_KEY。当存在 Platform 凭据时，Gateway 会生成一个临时客户端密钥（client secret），浏览器会直接执行 SDP 交换。

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

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

GPT-Live API¶

Talk 和 Gateway relay 会话在未配置模型时会选择 GPT-Live。OpenAI Platform 密钥、API-key 配置文件或 OPENAI_API_KEY 会选择带有 marin 的 gpt-live-1；仅 ChatGPT 账户会选择带有 cove 的 gpt-live-1-codex。已配置的 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 relay 桥接和提供商拥有的委托。安装更新不会重写已保存的配置，也不会切换活动会话。

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

此模型需要一个具有模型访问权限的 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",
    },
  },
}

Browser Talk 使用由 Gateway 代理的 WebRTC；Platform 密钥保留在 Gateway 上。对于直接服务器 WebSocket 路径，请设置 transport: "gateway-relay"。Discord 实时语音和 Voice Call 在使用 gpt-live-1 时，使用相同的由 Gateway 拥有的直接 WebSocket 桥接和原生 agent 委派。

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"。其音频适配器在 WebRTC 和直接 WebSocket 路由中，将运营商 G.711 mu-law 8 kHz 与模型的 24 kHz PCM 流相互转换。初始问候和 voicecall.speak 请求使用原生会话上下文。

两种 GPT-Live 路由都会产生连续音频并负责中断。Gateway WebSocket 和 WebRTC 使用相同的采样时钟，以麦克风输入的录制速率发送麦克风输入，并在采集之间提供静音。Discord 不会添加说话人开始取消，也不会等待 response-done 事件来播放简短回复。显式的 Discord requireWakeName: true 或 consultPolicy: "always" 会被拒绝，因为 GPT-Live 无法执行这些主机策略；其默认使用自动 provider 委派。每个说话人的委派工作保留其 Discord 身份和权限。共享的 OpenClaw agent 对话提供房间上下文，而每个说话人的语音模型连接具有独立的声学对话历史。请参阅 Discord 中的 GPT-Live。

Voice Call 在 Live 播放期间也会保持麦克风输入打开，并且不会添加主机语音开始取消。原生委派使用现有的由通话拥有的 agent 咨询，包括其工具策略和取消生命周期。显式的 realtime.consultPolicy: "always" 对 GPT-Live 会被拒绝。openclaw_end_call 和自定义 realtime.tools 需要原生 function-tool 支持，并且在 GPT-Live 上仍不可用；委派不会公开它们。请参阅 Voice Call 中的 GPT-Live。

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

Gateway 中继 WebRTC 以连续采样时钟为基准对麦克风音频进行节奏控制，因此在较长通话期间定时器延迟不会累积。调度器暂停后，排队音频以正常节奏恢复播放，同时时间戳会计入已流逝的间隔。通话会掩盖格式错误的传入音频包，并继续播放后续音频。一次被拒绝的音频包发送不会结束原本已连接的通话。不可用的编解码器状态、意外的流变更以及终止连接状态仍会结束通话。丢包诊断会省略原始错误详情。

已启用的 OpenAI 插件会自动启动 broker，包括在 Gateway 启动后你登录时。broker 只在你启动语音会话时打开 provider 会话；登录不会打开麦克风或加入 Discord 语音。登录后返回浏览器会刷新聊天麦克风的就绪状态。

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

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

使用账户签发的实时模型值。未列出的模型值可作为自由格式的 Talk 配置接受，但不会通过目录或诊断发布。使用 talk.realtime.model 显式选择加入；已发布模型仍为默认值。

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

未列出或私有浏览器 WebRTC 的前置条件，按顺序如下：

1. 通过 talk.realtime.providers.openai.apiKey、openai API 密钥配置或 OPENAI_API_KEY 配置的 Platform API 密钥。
2. 将 talk.realtime.model 设置为账户签发值——通过 Control UI 中的 设置 → Talk 或以下配置。
3. 以完整模式注册捆绑的 openai 插件。限制性 plugins.allow 列表会失败，并显示 "OpenAI realtime browser session broker is unavailable"。

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

Gateway 中继使用直接双向传输：

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

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

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

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 桥接使用 Realtime WebSocket 会话结构，该结构不接受 `session.temperature`；公开的 GPT-Live API 使用其自身的 Live 会话结构，而 Codex 以及未列出/私有路由保留各自独立的传输契约。Azure OpenAI 部署仍可通过 `azureEndpoint` 和 `azureDeployment` 使用，并保持与部署兼容的会话结构（包括 `temperature`）。支持双向工具调用和 G.711 u-law 音频。

!!! note

    Realtime 语音在会话创建时选定。GA Realtime 允许大多数会话字段稍后更改，但在模型输出音频后无法更改语音。GPT-Live 在启动时固定其模型、语音、音频格式和委托模式。OpenClaw 将内置 Realtime 语音 ID 作为字符串暴露。

!!! note

    Control UI Talk 使用浏览器 WebRTC 会话。Codex GPT-Live 浏览器/Gateway 拥有的路由会先通过 Gateway offer broker 尝试 ChatGPT OAuth，使 OAuth 保持在服务端。当 OAuth 不可用时，它会按以下顺序回退到平台凭据：已配置的 realtime 密钥、API 密钥配置，然后是 `OPENAI_API_KEY`。公开的 `gpt-live-1` API、直接后端套接字以及未列出或私有 realtime 路由需要平台凭据。维护者实时验证可通过 `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` 进行短时间的重复连接、回话和关闭浸泡测试。