对话模式

Talk 模式涵盖以下运行时形态：

• 原生 macOS/iOS/Android Talk：原生语音识别、Gateway 聊天和 talk.speak TTS。macOS/iOS 上的 Apple 语音识别可能使用网络服务。Android 行为取决于已安装的语音服务。节点会通告 talk 能力，并声明它们支持哪些 talk.* 命令。
• iOS Talk（实时）：针对选择 webrtc 传输或省略传输的 OpenAI 实时配置，使用客户端拥有的 WebRTC。该路径包括有帧和无帧的转写/音频事件。显式的 gateway-relay、provider-websocket 以及非 OpenAI 实时配置仍使用 Gateway 拥有的中继。非实时配置使用原生语音循环。
• Apple Watch 独立 Talk：通过 UDP 的原生 WebRTC/Opus，使用 Gateway 拥有的呼叫控制（gateway-control-v1）。手表使用 Gateway 配置的实时提供商。它将工具和转写所有权保留在 Gateway 上。不支持的配置会明显失败，且没有中继回退。
• 浏览器 Talk：使用 talk.client.create 创建客户端拥有的 webrtc/provider-websocket 会话，或使用 talk.session.create 创建 Gateway 拥有的 gateway-relay 会话。managed-room 保留用于 Gateway 交接和对讲机房间。
• Android Talk（实时）：当 talk.catalog 报告实时组就绪时，Android 使用 Gateway 拥有的中继实时功能。对于受支持的 GPT-Live 模型，Gateway 通过 talk.config 通告中继能力，因此 Android 会启动 talk.session.create，而不是使用原生语音识别和 talk.speak。Android 从不打开客户端拥有的 WebRTC 会话。缺少能力提示的旧版 Gateway 以及未列入 GPT-Live 路由会保留原生 Talk，并给出可见说明。显式的 stt-tts 模式也保持原生。中继能力并不等于身份验证就绪：目录和会话创建仍会验证所选账户。订阅身份验证的 Android 实时音频验证仍待定。
• 仅转写客户端：使用 talk.session.create({ mode: "transcription", transport: "gateway-relay", brain: "none" })，然后通过 talk.session.appendAudio 和 talk.session.close 获取字幕/听写，而无需助手语音响应。一次性上传的语音笔记仍使用媒体理解音频路径。

原生 Talk 是一个持续循环。它侦听语音。它通过活动会话将转写发送给模型。它等待响应。然后通过配置的 Talk 提供商（talk.speak）说出响应。

对于以围栏代码为主的回复，talk.speak 会使用一条简短的语音消息，引导听者查看屏幕。行内代码和普通散文仍作为语音回复的一部分。

Apple Watch 还保留了 Talk to Claw，即独立的单轮伴随流程。该流程使用原生听写、通过 iPhone 中继的文本以及系统语音回读。Talk on Watch 是普通手表设置中包含的实时路径。请参阅独立语音设置。

Talk 文档页面¶

Talk 模式记录在本页和四个子页面中，每个页面对应一种读者任务。 本页保留语音指令和 talk 配置参考。 打开与你的任务匹配的子页面。

各章节移动位置¶

上一单页版本中的每个章节标题都在此处保留其锚点，因此现有链接（如 /nodes/talk#session-ownership）仍然有效。每个条目指向现在包含相应内容的页面。

• 从聊天中选择 Talk 语音
• 会话所有权
• 行为（macOS）
• 行为（macOS）
• 通过 Gateway 中继的实时 Talk（macOS）
• 通过 Gateway 中继的实时 Talk（macOS）
• 当实时无法启动时
• macOS 界面
• Apple Watch 界面
• Android 界面

回复中的语音指令¶

助手可以在回复前添加一行 JSON 来控制语音：

{ "voice": "<voice-id>", "once": true }

规则：

• 仅限首个非空行。JSON 行会在 TTS 播放前被移除。
• 未知键会被忽略。
• once: true 仅应用于当前回复。没有它，该语音将成为新的 Talk 模式默认值。
• 支持的键：voice / voice_id / voiceId、model / model_id / modelId、speed、rate（WPM）、stability、similarity、style、speakerBoost、seed、normalize、lang、output_format、latency_tier、once。

配置 (~/.openclaw/openclaw.json)¶

尖括号中的值（如 <elevenlabs-api-key>）为占位符。请将它们替换为你自己的值。

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        voiceId: "<elevenlabs-voice-id>",
        modelId: "eleven_v3",
        outputFormat: "mp3_44100_128",
        apiKey: "<elevenlabs-api-key>",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
        // Fish S2 Pro can also use a local reference voice:
        // referenceAudioPath: "/Users/example/Voices/reference.wav",
        // referenceText: "Exact transcript of the reference clip.",
      },
      system: {},
    },
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          apiKey: "<openai-api-key>",
          model: "gpt-realtime-2.1",
          speakerVoice: "cedar",
        },
      },
      instructions: "Speak warmly and keep answers brief.",
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

OpenAI 浏览器 WebRTC 和 Gateway 中继 Talk 支持原生 GPT-Live。在 设置 → Talk 中，为公共 API 选择 gpt-live-1，或为 Codex 路由选择 gpt-live-1-codex。公共 API 需要 Platform 密钥；Codex 路由首选 OpenClaw ChatGPT OAuth 配置文件，并回退到 Platform API 密钥认证。浏览器 Talk 使用客户端 WebRTC，由 Gateway 负责控制。Gateway 中继对 gpt-live-1 使用直接的 Platform 密钥 WebSocket，对 gpt-live-1-codex 使用 Gateway 自有 WebRTC。Discord 在配置了相应 Live 模型时使用相同的 Gateway 桥接。

账户签发、未列出的路由可以在 talk.realtime.model 中设置，但不会通过目录或诊断信息发布。它们从不使用 OAuth，需要 Platform 密钥。GPT-Live 浏览器 Talk 还要求以完整模式注册随附的 openai 插件。限制严格的 plugins.allow 列表会导致会话创建失败，并提示"OpenAI GPT-Live 浏览器会话代理不可用"。

运行时限制：每个 Gateway 最多 8 个并发会话，会话 TTL 为 30 分钟。浏览器会话还使用 60 秒的一次性 offer 令牌。

Codex 路由使用 arbor、breeze、cove、ember、juniper、maple、sol、spruce 和 vale，其中 cove 为默认值。公共 API 默认为 marin，并有自己的语音列表。在 Talk 和 Discord 中选择相同的模型和受支持的语音以使用相同的声音；cove 搭配公共 gpt-live-1 模型时会回退到 marin。未列出的路由使用账户签发的语音合约；当前未列出的 Platform 配置文件接受 marin 和 cedar。被拒绝的会话本身不会指明原因。请检查所选的账户、模型和语音。

GPT-Live 原生支持打断，并能生成连续音频，无需依赖 completed-response 事件。Discord 通过委托给 OpenClaw 的任务保留每个说话者的身份。其语音模型连接按说话者保持分离；共享的房间上下文属于 OpenClaw 代理会话。有关配置以及主持人强制会议参与的限制，请参阅 Discord 中的 GPT-Live。

这些行描述的是已实现的传输路径，而非账户授权或每台设备上的成功实时通话。iOS 实现了无边框转录和 Gateway offer 交换。Android 遵循 Gateway 中继能力提示，并且仅在该提示缺失时才保留其遗留的 GPT-Live 模型门控。有关模型能力限制，请参阅 Discord 语音策略 和 语音通话工具。

Gateway 自有的 WebRTC 路由确保 OAuth 和 Platform 凭据不会到达中继客户端。后端 WebSocket 路径将 Platform 密钥保留在 Gateway 上。OpenClaw 在电话 G.711 u-law 音频与 GPT-Live 的 24 kHz PCM 格式之间进行转换。

对于 GA gpt-realtime-2.1、gpt-realtime-2.1-mini 和 gpt-realtime-2 浏览器会话，Platform 凭据仍按以下顺序优先：配置的 realtime API 密钥、openai API 密钥配置文件，然后才是 OPENAI_API_KEY。若未配置任何项，浏览器 Talk 会回退到 OpenClaw ChatGPT OAuth 配置文件，并通过 Gateway 的一次性 offer 代理交换 SDP，因此 OAuth 令牌永远不会到达浏览器。已配置但无法解析的 Platform 凭据将失败关闭，而不是静默回退到 OAuth。

iOS 客户端自有 WebRTC 和 GA Gateway 中继（包括 Android GA realtime）仍仅限 Platform 密钥。GA 浏览器 Talk 保留现有的客户端自有数据通道和 talk.client.toolCall 循环。在 OAuth 下，只有凭据所有者和 SDP 交换路径发生变化。Codex GPT-Live 路由在浏览器和 Gateway 自有 WebRTC（包括 Android Talk 和 Discord）中仍保持 OAuth 优先、Platform 回退。公共 GPT-Live、直接后端套接字和未列出的 GPT-Live 路由仍仅限 Platform 密钥。

talk.catalog 公开规范提供商 ID 和注册表别名。它公开每个提供商的有效模式/传输/brain 策略/实时音频格式/能力标志。它公开运行时选择的就绪结果。第一方 Talk 客户端应读取该目录，而不是在本地维护提供商别名。对于省略组就绪状态的旧版 Gateway，应视为未验证，而不是明确未配置。流式转录提供商通过 talk.catalog.transcription 发现。当前 Gateway 中继使用 Voice Call 流式提供商配置，直到专用的 Talk 转录配置界面发布。

备注¶

• 原生语音识别需要平台的语音和麦克风访问权限。独立的 Watch 实时功能需要麦克风访问权限，而不是本地语音识别。
• 原生 Talk 使用活动的 Gateway 会话，仅在响应事件不可用时回退到历史轮询。
• Gateway 通过 talk.speak 使用活动的 Talk 提供商解析 Talk 播放。仅当该 RPC 不可用时，Android 才回退到本地系统 TTS。
• macOS 本地 MLX 播放若存在捆绑的 openclaw-mlx-tts 辅助程序则使用它，否则使用 PATH 上的可执行文件。开发期间，设置 OPENCLAW_MLX_TTS_BIN 以指向自定义辅助程序二进制文件。该辅助程序流式传输 PCM，保持一个选定模型常驻，并通过 providers.mlx.referenceAudioPath 加上 referenceText 支持 Fish S2 Pro 参考音频。
• 语音指令值范围（ElevenLabs）：stability、similarity 和 style 键接受 0..1。speed 键接受 0.5..2。latency_tier 键接受 0..4。

相关¶

• 语音唤醒
• 音频和语音笔记
• 媒体理解
• Google Meet 插件
• 媒体概览 — 媒体工具如何协同工作