OpenClaw Talk Mode 提供三种语音对话形态：macOS/iOS/Android 原生本地语音（STT + Gateway chat + talk.speak）、浏览器实时语音（客户端或网关托管会话）、以及纯转录模式（用于字幕/听写，不包含语音回复）。配置集中在 openclaw.json 的 talk 节点，需指定 provider（如 elevenlabs）、silenceTimeoutMs、interruptOnSpeech。回复中可通过单行 JSON 临时切换 voice 或模型。实时语音需额外配置 realtime 节点，支持 OpenAI WebRTC 或 Google WebSocket。Android 需设置 talk.realtime.transport: "gateway-relay" 才能使用网关托管的实时语音，否则使用原生 STT/TTS 循环。

OpenClaw Talk Mode（语音对话）配置指南与常见问题

Talk mode 有三种运行时形态：

• 原生 macOS/iOS/Android Talk：使用本地语音识别、Gateway chat 和 talk.speak TTS。节点会广播 talk 能力，并声明支持的 talk.* 命令。
• 浏览器 Talk：使用 talk.client.create 创建客户端拥有的 webrtc 或 provider-websocket 会话，或使用 talk.session.create 创建 Gateway 拥有的 gateway-relay 会话。managed-room 保留用于 Gateway 交接和对讲房间。
• Android Talk 可启用 Gateway 托管的实时中继会话：设置 talk.realtime.mode: "realtime" 和 talk.realtime.transport: "gateway-relay"。否则依然使用原生语音识别、Gateway chat 和 talk.speak。
• 仅转录客户端：通过 talk.session.create({ mode: "transcription", transport: "gateway-relay", brain: "none" }) 创建会话，然后使用 talk.session.appendAudio、talk.session.cancelTurn 和 talk.session.close 管理音频流，订阅 talk.event 获取部分/最终转录结果。适用于字幕、听写等不需要语音回复的场景。

原生 Talk 是一个持续的语音对话循环：

1. 监听语音
2. 将转录文本通过活动会话发送到模型
3. 等待响应
4. 通过配置的 Talk provider（talk.speak）播放

浏览器实时 Talk 通过 talk.client.toolCall 转发 provider 的工具调用；浏览器客户端不直接调用 chat.send 处理实时请求。

仅转录 Talk 发出与实时和 STT/TTS 会话相同的通用 Talk 事件信封，但使用 mode: "transcription" 和 brain: "none"。它用于字幕、听写和只观察的语音捕获；一次性上传的语音笔记仍走 media/audio 路径。

macOS 上的语音对话行为

• 始终打开的浮窗：启用 Talk 模式后显示。
• 监听→思考→说话 阶段切换。
• 短停顿（静默窗口）后，当前转录文本被发送。
• 回复写入 WebChat（与手动输入相同）。
• 打断语音（默认开启）：用户开始说话时，若助手正在播放语音，则停止播放，并在下次提示中记录打断时间戳。

回复中的语音指令 JSON 格式

助手可以在回复开头加一个 单行 JSON 来控制语音：

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

规则：

• 仅首个非空行生效。
• 未知键被忽略。
• once: true 仅对当前回复生效。
• 不带 once 时，voice 成为 Talk Mode 的新默认值。
• 该 JSON 行在 TTS 播放前被剥除。

支持的键：

• 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 的 talk 节点

{
  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",
      },
      system: {},
    },
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          apiKey: "openai_api_key",
          model: "gpt-realtime-2",
          voice: "cedar",
        },
      },
      instructions: "Speak warmly and keep answers brief.",
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

默认值及回退逻辑：

• interruptOnSpeech：默认为 true
• silenceTimeoutMs：未设置时，Talk 使用平台默认停顿窗口——macOS 和 Android 为 700ms，iOS 为 900ms
• provider：选择活动的 Talk provider。使用 elevenlabs、mlx 或 system 走 macOS 本地播放路径。
• providers.<provider>.voiceId：回退到 ELEVENLABS_VOICE_ID / SAG_VOICE_ID（或 API key 可用时的第一个 ElevenLabs voice）
• providers.elevenlabs.modelId：未设置时默认 eleven_v3
• providers.elevenlabs.apiKey：回退到 ELEVENLABS_API_KEY（或网关 shell profile 中的密钥）
• consultThinkingLevel：可选，覆盖实时 openclaw_agent_consult 调用的思考级别
• consultFastMode：可选，覆盖实时 openclaw_agent_consult 调用的快速模式
• realtime.provider：选择活动的浏览器/服务器实时语音 provider。使用 openai 走 WebRTC，google 走 provider WebSocket，或通过 Gateway relay 使用仅桥接的 provider。
• realtime.providers.<provider>：存储 provider 拥有的实时配置。浏览器仅接收临时或受限的会话凭证，不会获得标准 API key。
• realtime.providers.openai.voice：OpenAI Realtime 内置语音 ID。gpt-realtime-2 当前支持 alloy、ash、ballad、coral、echo、sage、shimmer、verse、marin、cedar；推荐使用 marin 和 cedar 获得最佳质量。
• realtime.transport：webrtc 和 provider-websocket 是浏览器实时传输方式。Android 仅当设为 gateway-relay 时使用实时中继；否则 Android Talk 使用本地 STT/TTS 循环。
• realtime.brain：agent-consult 通过 Gateway 策略路由实时工具调用；direct-tools 是旧版直接工具兼容行为；none 用于转录或外部编排。
• realtime.instructions：追加 provider 端的系统指令到 OpenClaw 内置实时提示之后。用于控制语音风格和语气；OpenClaw 保留默认 openclaw_agent_consult 指引。
• talk.catalog：暴露每个 provider 的有效模式、传输方式、brain 策略、实时音频格式和能力标志，让第一方 Talk 客户端避免使用不支持的组合。
• speechLocale：可选的 BCP 47 区域标识符，用于 iOS/macOS 设备端语音识别。留空则使用设备默认语言。
• outputFormat：macOS/iOS 默认 pcm_44100，Android 默认 pcm_24000（设置 mp3_* 强制 MP3 流式传输）

macOS UI

• 菜单栏开关：Talk
• 配置标签页：Talk Mode 分组（voice id + 打断开关）
• 浮窗：
  • 监听中：云朵随麦克风电平脉动
  • 思考中：下沉动画
  • 说话中：辐射光环
  • 点击云朵：停止语音播放
  • 点击 X：退出 Talk Mode

Android UI

• 语音标签页开关：Talk
• 手动 麦克风 和 Talk 是互斥的运行态捕获模式。
• 手动麦克风在应用进入后台或用户离开语音标签页时停止。
• Talk Mode 持续运行，直到手动关闭或 Android 节点断开连接，期间使用 Android 的麦克风前台服务类型。

注意事项

• 需要 语音 + 麦克风权限。
• 原生 Talk 使用活动 Gateway 会话，仅在响应事件不可用时回退到历史轮询。
• 浏览器实时 Talk 使用 talk.client.toolCall 处理 openclaw_agent_consult，而非向 provider 拥有的浏览器会话暴露 chat.send。
• 仅转录 Talk 使用 talk.session.create、talk.session.appendAudio、talk.session.cancelTurn 和 talk.session.close；客户端订阅 talk.event 获取部分/最终转录结果。
• Gateway 通过 talk.speak 使用活动的 Talk provider 解析语音播放。Android 仅在 RPC 不可用时回退到本地系统 TTS。
• macOS 本地 MLX 播放使用捆绑的 openclaw-mlx-tts 辅助程序（如果存在），或 PATH 中的可执行文件。开发时可设置 OPENCLAW_MLX_TTS_BIN 指向自定义辅助程序。
• eleven_v3 的 stability 有效值为 0.0、0.5 或 1.0；其他模型接受 0..1。
• latency_tier 设置时有效值为 0..4。
• Android 支持 pcm_16000、pcm_22050、pcm_24000 和 pcm_44100 输出格式，用于低延迟 AudioTrack 流式播放。

常见问题

OpenClaw Talk Mode 启用后没有声音或语音不播放怎么办？

检查 openclaw.json 的 talk 节点是否配置了正确的 provider 和 API key。确认 talk.speak RPC 可用（Android 会回退到系统 TTS）。验证 silenceTimeoutMs 是否设置过短导致转录发送过晚。查看日志是否有 talk.speak 错误或 provider 认证失败。

Talk Mode 在 Android 上怎么使用实时对话（不需要按麦克风按钮）？

需要在 openclaw.json 中设置 talk.realtime.mode: "realtime" 和 talk.realtime.transport: "gateway-relay"，同时配置 realtime.provider 及其密钥。启用后 Android Talk Mode 会使用 Gateway 托管的实时中继会话，支持持续语音到语音对话。否则 Android 保持原生 STT/TTS 循环。

语音回复中的 JSON 指令怎么用？为什么我的 voice 没变化？

助手必须在其回复的第一行放置单行 JSON，例如 {"voice":"marin","once":true}。once: true 只对当前回复生效；不带 once 时 voice 会成为新的默认值。注意 JSON 行在 TTS 播放前会被剥除，不会出现在聊天记录中。如果助手未输出该行，则跳过语音指令。

相关文档

• Voice wake（语音唤醒）
• Audio and voice notes（音频与语音笔记）
• Media understanding（媒体理解）