对话模式
Talk 模式涵盖以下运行时形态:
- 原生 macOS/iOS/Android Talk:原生语音识别、Gateway 聊天与
talk.speakTTS。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 之类的现有链接仍然有效。每个条目指向现在承载对应内容的页面。
- 从聊天中选择 Talk 语音
- 会话所有权
- 行为(macOS)
- 行为(macOS)
- 通过 Gateway 中继的实时 Talk(macOS)
- 通过 Gateway 中继的实时 Talk(macOS)
- 当实时无法启动时
- macOS 界面
- Apple Watch 界面
- Android 界面
回复中的语音指令¶
助手可以在回复前加上一行 JSON 来控制语音:
规则:
- 仅限首个非空行。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。
相关¶
- 语音唤醒
- 音频和语音笔记
- 媒体理解
- Google Meet 插件
- 媒体概览 — 媒体工具如何协同工作
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw