跳转至

对话和语音

统一 Talk 会话控制器、其支持的会话组合,以及从已移除 Talk 系列迁移的方法映射。属于 Plugin SDK 迁移 指南的一部分。

Talk 与实时语音迁移

实时语音、电话、会议和浏览器 Talk 代码共享一个由 openclaw/plugin-sdk/realtime-voice 导出的 Talk 会话控制器。该控制器负责通用的 Talk 事件信封、活动轮次状态、捕获状态、输出音频状态、近期事件历史以及过期轮次拒绝。Provider 插件负责供应商特定的实时会话。浏览器会议插件使用 openclaw/plugin-sdk/meeting-runtime 处理会话、浏览器、音频、node-host、agent-consult 和 voice-call 机制,然后实现 MeetingPlatformAdapter 以处理 URL 规则、DOM 脚本、手动操作映射、字幕、创建和拨入计划。平台 REST API、OAuth、工件、选择器和 wire 名称保留在插件中。浏览器权限计划会接收请求的会议 URL,以便每个平台只授予其确切支持的源。会话运行时还必须在确认浏览器离开后规范化平台特定的实时健康状态;历史转录字段可以保留,但字幕和音频就绪状态在离开后不得保持活动。

所有内置表面都运行在共享控制器上:浏览器中继、managed-room 交接、voice-call 实时、voice-call 流式 STT、Google Meet 实时和原生 push-to-talk。Gateway 在 hello-ok.features.events 中广播一个实时 Talk 事件通道:talk.event。

新代码不应直接调用 createTalkEventSequencer(...),除非正在实现低层适配器或测试 fixture。请使用共享控制器,以便轮次范围事件不能在没有 turn id 的情况下发出,过期的 turnEnd / turnCancel 调用不能清除较新的活动轮次,并且输出音频生命周期事件在电话、会议、浏览器中继、managed-room 交接和原生 Talk 客户端之间保持一致。

公共 API 形状:

// Gateway-owned Talk session API.
await gateway.request("talk.session.create", {
  mode: "realtime",
  transport: "gateway-relay",
  brain: "agent-consult",
  sessionKey: "main",
});
await gateway.request("talk.session.appendAudio", { sessionId, audioBase64 });
// Capture this before stopping playback from the active output `talk.event`.
const turnId = activeOutputTalkEvent.talkEvent.turnId;
await gateway.request("talk.session.cancelOutput", { sessionId, turnId, reason: "barge-in" });
await gateway.request("talk.session.submitToolResult", {
  sessionId,
  callId,
  result: { status: "working" },
  options: { willContinue: true },
});
await gateway.request("talk.session.submitToolResult", {
  sessionId,
  callId,
  result: { status: "already_delivered" },
  options: { suppressResponse: true },
});
await gateway.request("talk.session.submitToolResult", { sessionId, callId, result });
await gateway.request("talk.session.close", { sessionId });

// Client-owned provider session API.
await gateway.request("talk.client.create", {
  mode: "realtime",
  transport: "webrtc",
  brain: "agent-consult",
  sessionKey: "main",
});
await gateway.request("talk.client.toolCall", { sessionKey, callId, name, args });
await gateway.request("talk.client.steer", { sessionKey, text, mode: "steer" });

浏览器拥有的 WebRTC/provider-websocket 会话使用 talk.client.create,因为浏览器拥有 provider 协商和媒体传输,而 Gateway 拥有凭据、指令和工具策略。talk.session.* 是 gateway-relay 实时、gateway-relay 转录和 managed-room 原生 STT/TTS 会话的通用 Gateway 管理表面。

将实时选择器放在 talk.provider / talk.providers 旁边的旧配置应使用 openclaw doctor --fix 修复;运行时 Talk 不会将语音/TTS provider 配置重新解释为实时 provider 配置。

支持的 talk.session.create 组合有意保持精简:

模式 传输 Brain 所有者 备注
realtime gateway-relay agent-consult Gateway 通过 Gateway 桥接的全双工 provider 音频;工具调用通过 agent-consult 工具路由。
transcription gateway-relay none Gateway 仅流式 STT;调用方发送输入音频并接收转录事件。
stt-tts managed-room agent-consult 原生/客户端房间 客户端拥有捕获/播放、Gateway 拥有轮次状态的 push-to-talk 和对讲机风格房间。
stt-tts managed-room direct-tools 原生/客户端房间 仅管理员的房间模式,用于直接执行 Gateway 工具操作的可信第一方表面。

对于从旧的 talk.realtime.* / talk.transcription.* / talk.handoff.* 系列(均已移除)迁移的读者,方法映射如下:

旧 新
talk.realtime.session talk.client.create
talk.realtime.toolCall talk.client.toolCall
talk.realtime.relayAudio talk.session.appendAudio
talk.realtime.relayCancel talk.session.cancelOutput
talk.realtime.relayToolResult talk.session.submitToolResult
talk.realtime.relayStop talk.session.close
旧 新
talk.transcription.session talk.session.create({ mode: "transcription" })
talk.transcription.relayAudio talk.session.appendAudio
talk.transcription.relayCancel talk.session.close
talk.transcription.relayStop talk.session.close
talk.handoff.create talk.session.create({ transport: "managed-room" })
talk.handoff.revoke talk.session.close

统一控制词汇表也刻意保持精简:

方法 适用于 契约
talk.session.appendAudio realtime/gateway-relay, transcription/gateway-relay 向由同一 Gateway 连接拥有的提供商会话追加一个 base64 PCM 音频块。
talk.session.cancelOutput realtime/gateway-relay 停止助手音频输出,而不一定结束用户轮次。
talk.session.submitToolResult realtime/gateway-relay 在其桥接暴露的任何异步完成后,完成提供商工具调用;对于中间输出,传递 options.willContinue,或者在受支持时传递 options.suppressResponse 以避免再次生成助手响应。
talk.session.steer 由 agent 支持的 Talk 会话 向从 Talk 会话解析出的活动嵌入式运行发送语音 status、steer、cancel 或 followup 控制。
talk.session.close 所有统一会话 停止中继会话或撤销 managed-room 状态,然后清除统一会话 id。

不要为了使其工作而在核心中引入提供商或平台特例。 核心拥有 Talk 会话语义。提供商插件拥有供应商会话设置。 Voice-call 和 Google Meet 拥有电话/会议适配器。浏览器和原生 应用拥有设备捕获/播放用户体验。

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