跳转至

对话模式

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)。Watch 使用 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 模式也保持原生。中继能力并不代表已通过身份验证:catalog 与会话创建仍会校验所选账户。基于订阅身份验证的 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 转发的文本,以及系统语音回读。Watch 上的 Talk 是常规 Watch 设置中包含的实时路径。参见独立语音设置。

Talk 文档页面

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

页面 适用场景
Talk 实时会话与委派 你在接入实时 Talk:语音选择、委派、引导与转录。
Talk 会话所有权 你需要智能体与会话解析、控制权限或关闭语义。
macOS 上的 Talk 与 Gateway 中继 你在 macOS 上运行 Talk,或启用流式实时 Gateway 中继。
Talk 客户端界面 你需要 macOS、Apple Watch 或 Android 的客户端控件与行为。

各小节迁移位置

上一版单页文档中的每个小节标题都在此保留其锚点,因此诸如 /nodes/talk#session-ownership 之类的现有链接仍然有效。每个条目指向现在承载对应内容的页面。

回复中的语音指令

助手可以在回复前加上一行 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-relay Talk 原生支持 GPT-Live。在 设置 → Talk 中,为公共 API 选择 gpt-live-1,或为 Codex 路由选择 gpt-live-1-codex。公共 API 需要 Platform 密钥;Codex 路由优先使用 OpenClaw ChatGPT OAuth 配置文件,并回退到 Platform API 密钥认证。Browser Talk 使用客户端 WebRTC,并由 Gateway 持有控制权。Gateway relay 对 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 browser session broker is unavailable”。

运行时限制:每个 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 原生处理打断,并且无需完成响应事件即可生成连续音频。Discord 通过委托的 OpenClaw 工作来保留每个发言者的身份。其语音模型连接按发言者保持独立;共享的房间上下文属于 OpenClaw 代理对话。有关配置以及主持人强制会议参与的限定,请参阅 Discord 中的 GPT-Live。

使用方 GPT-Live 状态
Browser Talk Codex 路由:OAuth 优先;公共 API 和未列出路由:Platform 密钥客户端 WebRTC
Gateway-relay Talk Codex 路由:OAuth 优先 WebRTC;公共 API 和未列出路由:直连 Platform 密钥传输
Discord 实时语音 与 Talk 使用相同的 Gateway 桥接:Codex OAuth 优先 WebRTC 或公共 Platform 密钥 WebSocket
语音通话与电话 Platform 密钥后端 WebSocket
iOS 客户端自有 Talk 已实现;GPT-Live 真机实时验证待完成
Apple Watch 独立 Talk 已实现 Gateway 控制的 WebRTC;实体 Watch 验证待完成
Android 实时 Talk Gateway 公布的已发布路由使用 relay;Android 实时音频验证待完成

这些行描述的是已实现的传输路径,并不代表账户权限,也不保证每台设备上都能成功进行实时通话。iOS 实现了无边框转录文本和 Gateway offer 交换。Android 遵循 Gateway 的 relay 能力提示,并且仅在该提示缺失时保留其旧版 GPT-Live 模型门控。有关模型能力限制,请参阅 Discord 语音策略 和 Voice Call 工具。

Gateway 自有的 WebRTC 路由可避免 OAuth 和 Platform 凭据暴露给 relay 客户端。后端 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。如果均未配置,Browser Talk 会回退到 OpenClaw ChatGPT OAuth 配置文件,并通过 Gateway 的一次性 offer broker 交换 SDP,因此 OAuth 令牌永远不会到达浏览器。如果已配置的 Platform 凭据无法解析,则会失败关闭(fail closed),而不是静默回退到 OAuth。

iOS 客户端自有 WebRTC 和 GA Gateway relay(包括 Android GA realtime)仍然仅支持 Platform 密钥。GA Browser Talk 保留现有的客户端自有数据通道和 talk.client.toolCall 循环。在 OAuth 下,只有凭据所有者和 SDP 交换路径会改变。Codex GPT-Live 路由在浏览器和 Gateway 自有 WebRTC(包括 Android Talk 和 Discord)中仍然以 OAuth 优先,并以 Platform 作为回退。公共 GPT-Live、直接后端 socket 以及未列出的 GPT-Live 路由仍然仅支持 Platform 密钥。

键 默认值 说明
agentId 已配置的默认代理 拥有在未显式指定代理作用域会话密钥时创建的 Talk 会话。
provider - 当前活动的 Talk TTS 提供商。对于 macOS 本地播放路径,使用 elevenlabs、mlx 或 system。
providers.<id>.voiceId - ElevenLabs 会回退到 ELEVENLABS_VOICE_ID / SAG_VOICE_ID,或使用具有 API 密钥的第一个可用语音。
speechLocale 设备默认值 用于 Android、iOS 和 macOS 原生语音识别的 BCP 47 语言区域设置,以及 iOS 系统语音回退。Apple Speech 可能会使用网络服务;Android 还会将语言组件转发到实时输入转录。
providers.elevenlabs.modelId eleven_multilingual_v2
providers.mlx.modelId mlx-community/Soprano-80M-bf16
providers.mlx.referenceAudioPath - 对于支持语音克隆的 MLX 模型,可选的客户端本地参考录音。该路径在原生 macOS 应用主机上解析。
providers.mlx.referenceText - referenceAudioPath 的精确转录文本;Fish S2 Pro 使用这两个值进行本地语音克隆。
providers.elevenlabs.apiKey - 回退到 ELEVENLABS_API_KEY(如果可用,则回退到网关 shell 配置文件)。
silenceTimeoutMs 700 ms macOS/Android、900 ms iOS Talk 发送转录文本前的暂停窗口。
interruptOnSpeech true
providers.<id>.outputFormat pcm_44100 macOS/iOS、pcm_24000 Android 设置 mp3_* 以强制使用 MP3 流式传输。
consultThinkingLevel 未设置 实时 openclaw_agent_consult 调用背后的代理运行的思考级别覆盖。
consultFastMode 未设置 实时 openclaw_agent_consult 调用的快速模式覆盖。
realtime.provider - openai 用于 WebRTC,google 用于提供商 WebSocket,或通过 Gateway 中继的仅桥接提供商。
realtime.providers.<id> - 由提供商拥有的实时配置。浏览器仅接收临时/受限的会话凭据,绝不会接收标准 API 密钥。
键 默认值 说明
realtime.providers.openai.speakerVoice alloy(GA);GPT-Live 为路由特定值 内置 OpenAI 实时语音 id(旧的 voice 键仍然有效,但已弃用)。GA 语音:alloy、ash、ballad、cedar、coral、echo、marin、sage、shimmer、verse。GPT-Live 使用上文文档中说明的路由特定语音系列。
realtime.model 提供商默认值 实时语音模型。当两者都设置时,会覆盖 realtime.providers.<id>.model —— 与 talk.client.create 在会话时应用的优先级相同。
realtime.transport - webrtc:在 iOS、浏览器以及带 Gateway 控制的 Watch 上使用 OpenAI WebRTC。provider-websocket:由浏览器拥有,在 iOS 上保持使用 Gateway 中继。gateway-relay:将提供商音频保留在 Gateway 上;Android 仅在此传输方式下使用实时功能。
realtime.brain - agent-consult 将实时工具调用通过 Gateway 策略路由;direct-tools 是旧版直接工具兼容性;none 用于转录/外部编排。
realtime.consultRouting - provider-direct 在跳过 openclaw_agent_consult 时保留提供商的直接回复;force-agent-consult 改为将最终用户转录通过 OpenClaw 路由。
realtime.instructions - 将面向提供商的系统指令追加到 OpenClaw 内置的实时提示中。

实时 Talk 读取 talk.realtime。如果旧安装从 Voice Call 继承了实时 设置,Doctor 会将它们复制到 Talk 中,同时保留显式的 Talk 设置并备份配置。之后对 Voice Call 的编辑不再更改 实时 Talk。参见 Talk 实时迁移。

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。

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