实时和流式
全双工实时语音、挂断检测、工具与咨询策略、代理语音上下文,以及 Twilio Media Streams 转录。属于 Voice call plugin 指南的一部分。
实时语音对话¶
realtime 为实时通话音频选择全双工实时语音提供商。
它与 streaming 不同,后者仅将音频转发给实时转录提供商。
Warning
realtime.enabled 不能与 streaming.enabled 同时使用。每次通话只能选择一种音频模式。
运行时行为:
realtime.enabled支持 Twilio 和 Telnyx。realtime.provider可选。如果未设置,Voice Call 会按提供商优先级顺序选择第一个已配置的实时语音提供商。即使已有其他提供商处于活动状态,realtime.providers中列出的提供商也会被发现;插件禁用和允许/拒绝规则仍然适用。- 内置实时语音提供商:Google Gemini Live(
google)和 OpenAI(openai),由其提供商插件注册。 - 提供商拥有的原始配置位于
realtime.providers.<providerId>下。 - 对于支持函数工具的模型,Voice Call 会暴露内置的
openclaw_end_call实时工具。它不接受参数或通话 ID;活动语音桥接会将其绑定到当前通话。 - Voice Call 默认暴露共享的
openclaw_agent_consult实时工具。GPT-Live 改为使用原生委托到同一通话拥有的代理咨询。当来电者要求更深入推理、当前信息或普通 OpenClaw 工具时,实时模型可以委托。 realtime.consultPolicy可选地为实时模型何时应调用openclaw_agent_consult添加指导。realtime.idleHangupMs可选地在双方均未产生语音达到配置的毫秒正数后结束活动通话。计时器在代理咨询运行期间暂停,未设置时禁用。- 在具有共享上下文解析器的主机上,Voice Call 始终告知实时模型,它代表一个可能拥有其他会话和工作的 OpenClaw 代理发言。
realtime.agentContext.enabled默认关闭,并控制额外配置的标识和配置文件上下文。受支持的旧主机保留 旧版上下文行为。 realtime.fastContext.enabled默认关闭。启用后,Voice Call 首先针对咨询问题搜索索引化的内存/会话上下文,并在realtime.fastContext.timeoutMs内将授权片段返回给实时模型,仅当realtime.fastContext.fallbackToConsult为 true 时才回退到完整咨询代理。活动内存插件授权会话转录命中;不具备该能力的插件对会话命中采用失败关闭,而普通内存命中仍可用。- 如果
realtime.provider指向未注册的提供商,或根本没有注册任何实时语音提供商,Voice Call 会记录警告并跳过实时媒体,而不是让整个插件失败。 - 当
realtime.enabled为 true 时,inboundPolicy不得为"disabled";validateProviderConfig会拒绝该组合。 - 咨询会话密钥在可用时复用已存储的通话会话,然后回退到配置的
sessionScope(默认为per-phone,隔离通话为per-call,或配置代理的主会话为main)。
GPT-Live 使用代理委托而不是原生函数工具。被委托的
代理只能通过通话范围的 voice_call 绑定结束活动通话。
其他 voice_call 操作和自定义 realtime.tools 通过原生委托仍不可用。
主机语音检测在代理咨询进行中时暂停本地打断。一旦活动通话助手接受挂断,取消咨询 不会中断该控制操作。助手在操作前仍会检查其绑定的通话是否处于活动状态。
GPT-Live¶
Voice Call 使用与 Discord 和 Talk 相同的 Gateway 拥有的 GPT-Live 桥接。
选择 gpt-live-1-codex 并配合 cove 以使用 ChatGPT OAuth 路由;它会先尝试
路由代理的 OpenClaw ChatGPT 配置文件,然后尝试配置的 Platform
密钥、API-key 配置文件和 OPENAI_API_KEY。选择 gpt-live-1 并配合 marin 以使用
公共 Platform API 路由。保持模型未设置会保留 Voice Call 的
提供商默认值。
{
plugins: {
entries: {
"voice-call": {
config: {
realtime: {
enabled: true,
provider: "openai",
consultPolicy: "auto",
providers: {
openai: { model: "gpt-live-1-codex", voice: "cove" },
},
},
},
},
},
},
}
桥接将运营商 8 kHz 的 G.711 mu-law 音频与模型的 24 kHz PCM 流相互转换。GPT-Live 在播放期间接收麦克风输入并拥有
语音打断;Voice Call 不添加本地语音触发的取消。
外呼初始问候被固定为以其原始语言逐字回复的第一条回复。Voice Call 等待被叫方的第一句语音,并为
静默接听提供 3 秒回退。当启用 Twilio 应答机检测时,外呼会话通话会保持实时输入和开场白,直到得到
人工或未知结果,桥接就绪后有 30 秒上限。将
voicemail.holdOpeningMaxMs 设置为毫秒正整数以调整此上限(默认 30000)。该上限仅释放无分类的保持;
人工和未知结果会立即释放。三十秒可容纳较长的应答机问候,同时避免缺失回调无限期保持开场白。机器结果(包括 machine_start)会抑制
超过上限的实时语音;主机拥有语音信箱播放。入呼问候时序不变。voicecall.speak 请求使用相同的原生会话上下文路径。
委托工作保留通话的代理、工具策略和取消生命周期。
GPT-Live 拒绝 realtime.consultPolicy: "always":它拥有委托,并且
无法强制主机触发的转录咨询。使用 "auto" 或
"substantive" 指导,或选择支持主机控制轮次的模型。
realtime.toolPolicy: "none" 也会禁用原生委托的代理咨询。
每次通话简报与差事¶
外呼 initiate_call、voicecall.initiate 和 CLI 接受可选的
brief。它仅适用于该通话,并会同时到达语音模型及其代理咨询。开场 message
保持为第一句逐字说出的内容。
每个简报字段都是可选的:
| 字段 | 含义 |
|---|---|
task |
以纯文本说明要达成的目标。 |
context |
任务所需的事实,例如日期、地址和参考编号。 |
language |
BCP-47 语言标签或语言描述。 |
identity |
介绍文本,或 { introduction, disclose: "volunteer" \| "when-asked" }。 |
disclosures |
语音可分享的详细信息数组;默认除身份外无其他内容。 |
approvals |
语音可以同意的内容;默认不允许付款或额外承诺。 |
voicemailMessage |
检测到语音信箱时要留下的确切留言。 |
successCriteria |
什么算完成任务。 |
maxDurationSeconds |
正整数覆盖值,受插件 maxDurationSeconds 上限限制。 |
编码后的简报限制为 8,000 个字符。有关单个字段限制和水管工预约示例,请参阅插件 README。将简报和实时引导都视为所有者的授权;对方陈述不会扩大批准或披露权限。
steer_call 和 voicecall.steer 接受 callId、message 以及可选的 mode
(默认为 guidance,或 say 用于逐字语音)。引导仅限于请求方会话或已授权操作员,并要求精确的活跃通话 ID。原生委托使用宿主的语音响应路径。后续咨询会收到最近八条所有者指令。
可选插件配置:
```json5 validate=false { reports: { enabled: true, includeTranscript: true }, live: { transcript: true, minIntervalMs: 5000 }, callbacks: { enabled: true, windowMinutes: 60 }, voicemail: { detection: "twilio", onMachine: "leave-message" }, }
报告会根据简报总结转录内容,并包含时长、结束原因、答录机分类,以及在启用时包含完整转录。长转录会通过请求方存储的通道路由,以有序文本片段发送。`reports.summaryModel` 可选地选择摘要模型;`reports.inboundSessionKey` 为普通来电提供目标。现有本地或 webchat 会话通过 SDK 转录写入器接收助手文本,该写入器会发布会话更新,而无需另一个代理轮次或管理员权限。不可用的请求方会话会产生已记录的投递错误;转录仍保留在通话历史中。所有四项功能默认禁用。
在 `inboundPolicy: "allowlist"` 下,启用的回调仅当实时语音启用时,才接受在配置窗口内拨打的精确 E.164 号码。经典 STT/TTS 路径从不接受回调。回调会关联到外呼通话,并使用接待员简报来留言,而不分享详细信息。`callbacks.greeting` 和 `callbacks.brief` 可选地自定义该行为。窗口外的号码遵循现有来电策略。
Twilio 会收到指向经过签名验证的语音 webhook 的 `AsyncAmdStatusCallback`,并带有 `AsyncAmdStatusCallbackMethod: "POST"`。使用 `DetectMessageEnd` 时,Twilio 会立即报告人类,但仅在问候语结束时报告机器;在此模式下不保证提前出现 `machine_start`。参见 [Twilio AMD](https://www.twilio.com/docs/voice/answering-machine-detection)。每个收到的分类都会连同通话 ID 和时间戳记录。通话元数据保留 `answeredByFirst` 和最新的 `answeredBy`。
Twilio 答录机检测会等待 `machine_end_*`,然后再留下简报中的语音信箱留言。缺少留言时,会使用提供的身份介绍或中性的联系原因,并承诺稍后再试。它从不朗读任务。实时语音会将默认内容翻译为简报的语言;明确提供的留言保持逐字不变。运营商回退默认支持英语、西班牙语、法语、德语、意大利语、葡萄牙语和加泰罗尼亚语;其他语言除非提供明确留言,否则回退到英语。
活跃的实时桥接会通过实时引导相同的宿主语音路径朗读留言。如果约 1.5 秒内没有可听见的模型输出,宿主会结束通话,该时间以节奏化音频离开队列来衡量。静音帧不会延长播放。缺失或未完成的响应会在 45 秒后失败,并以错误结束通话。仅在无活跃桥接时,才使用运营商文本转语音后挂断。
在等待检测期间,远端持续语音超过三秒会触发一次简短确认,使用简报的语言。开场会保持挂起,直到分类完成或达到配置的保持上限。参见 [AMD 调优](configuration.md#twilio-voicemail-detection-tuning)。简报会告知语音和咨询代理,宿主拥有已检测到的语音信箱,防止模型发出第二条留言。通知通话会等待检测,然后再向人类播放开场消息,或向机器播放语音信箱留言。`onMachine: "hang-up"` 会立即结束机器通话。模拟提供商可以模拟检测;其他运营商保持不变。
### 挂断检测 {#hangup-detection}
实时通话通常在运营商发送流停止事件或关闭媒体 WebSocket 时结束。如果中间件没有及时转发该关闭,OpenClaw 会将 30 秒没有入站媒体视为断开连接,等待 2 秒宽限期让媒体恢复,然后结束通话。
设置 `realtime.idleHangupMs` 可在通话连接后,经过这么长时间的语音静默时结束通话。来电者语音、来电者转写、助手转写/音频,以及进行中的代理咨询都会重置或暂停此计时器。未设置则保持此行为禁用。等待音乐不是语音,因此请选择适合预期保持时间的值。
如果 realtime 提供方先结束其会话,OpenClaw 也会结束运营商通话,包括提供方报告正常关闭的情况。这可以防止语音会话结束后,静音的电话连接仍然保持开启。
支持函数工具的模型也可以在来电者要求挂断时调用 `openclaw_end_call`。模型必须在调用该工具前说完任何结束语:成功调用会立即结束当前的提供方会话和电话连接,因此之后不会再说出任何回复。如果运营商无法结束通话,桥接会保持连接,模型会收到一个可向来电者解释的错误。配置的 `realtime.tools` 不能按名称替换这个内置工具。
对于 Twilio 入站号码,还要配置一个使用 `POST` 到你的公共 webhook URL 并附加 `?type=status` 的状态回调(Status Callback),例如 `https://voice.example.com/voice/webhook?type=status`。包括 `completed` 呼叫事件。OpenClaw 创建的出站呼叫会自动配置其回调。该回调提供最快的拆线信号,而流关闭和不活动兜底仍独立于它。
### 工具策略 {#tool-policy}
`realtime.toolPolicy` 仅控制咨询运行。在支持函数工具的模型上,它绝不会禁用 `openclaw_end_call`:
| Policy | Behavior |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `safe-read-only` | 暴露咨询工具,并将常规代理限制为 `read`、`web_search`、`web_fetch`、`x_search`、`memory_search` 和 `memory_get`。 |
| `owner` | 暴露咨询工具,并让常规代理使用正常的代理工具策略。 |
| `none` | 禁用咨询工具和原生代理委托。在支持函数工具的模型上,内置的结束通话工具和自定义 `realtime.tools` 仍然可用。 |
`realtime.consultPolicy` 指导 realtime 模型。`always` 还会在提供方不进行咨询时启用主机转写回退,并且在 GPT-Live 下不受支持:
| Policy | Guidance |
| ------------- | ----------------------------------------------------------------------------------------------- |
| `auto` | 保持默认提示,并让提供方决定何时调用咨询工具。 |
| `substantive` | 直接回答简单的对话衔接语,并在涉及事实、记忆、工具或上下文之前进行咨询。 |
| `always` | 在每次实质性回答之前进行咨询。 |
每次通话中同时只能运行一个原生咨询。在活动语音会话中重放相同的提供方调用会共享其待处理结果。新的调用会收到一个 busy 错误,包含 `started: false` 和 `retryable: true`,即使其参数相同也不例外。realtime 模型应等待活动咨询的结果后再重试,而不是在其运行期间轮询。当无关的主机强制咨询运行时,原生请求也会收到 busy;只有匹配的强制问题(在去除空白后)才能共享该结果。仅相似的措辞并不能识别为同一个请求。
重叠的调用不能替换待处理咨询的来电者上下文。完成活动咨询只会消耗它使用的语音;被拒绝的来电者语音在现有转写窗口内仍可重试。
当主机工具运行报告取消时,realtime 模型会收到已取消的结果,电话通话保持打开。超时和其他工具失败仍视为错误;结束电话会话会抑制待处理的咨询结果。
### 代理语音上下文 {#agent-voice-context}
在具有共享上下文解析器的主机上,每个 realtime 会话都包含一段代理上下文段落,说明语音模型代表一个具有多个会话的 OpenClaw 代理发言。它将关于其他会话、正在运行的工作、进度或优先级的问题引导到 OpenClaw。当 `realtime.agentContext.enabled` 为 `false` 时,该段落仍然存在。
启用 `realtime.agentContext` 可将所配置代理的身份和选定的配置文件添加到普通语音轮次中。`includeIdentity` 控制所配置的名称、表情符号、氛围、主题以及生物/角色字段;`includeWorkspaceFiles` 控制 `files` 中列出的文件。共享核心解析器通过正常的引导路径加载 `IDENTITY.md`、`USER.md` 和 `SOUL.md`,并遵循引导钩子和工作区访问权限。其他工作区相对文件使用安全的工作区读取;缺失或不可读的文件会被跳过。`maxChars` 限定配置文件块的大小,默认值为 6000 个字符,并且不包括代理上下文段落和所配置的身份。
OpenClaw 2026.9.6 缺少该共享解析器。在此受支持的主机上,Voice Call 保留其随附的可选上下文胶囊:`enabled: false` 会省略该胶囊;启用时,身份字段和选定的安全工作区相对文件遵循各自的控件。`maxChars` 限定整个可选胶囊,包括身份、标题和截断标记。较新的多会话段落在此路径上不可用。当受支持的主机最低版本包含共享上下文解析器后,此兼容路径将退役。
上下文在 realtime 会话创建时添加,因此不会增加逐轮延迟。对 `openclaw_agent_consult` 的调用仍然会运行完整的 OpenClaw 代理,应用于工具工作、当前信息、记忆查询或工作区状态。
```json5
{
plugins: {
entries: {
"voice-call": {
config: {
agentId: "main",
realtime: {
enabled: true,
provider: "google",
toolPolicy: "safe-read-only",
consultPolicy: "substantive",
agentContext: {
enabled: true,
maxChars: 6000,
includeIdentity: true,
includeWorkspaceFiles: true,
files: ["SOUL.md", "IDENTITY.md", "USER.md"],
},
},
},
},
},
},
}
实时提供商示例¶
默认值:API 密钥来自 realtime.providers.google.apiKey、GEMINI_API_KEY 或 GOOGLE_API_KEY;模型为 gemini-3.1-flash-live-preview;语音为 Kore。sessionResumption 和 contextWindowCompression 默认开启,适用于更长、可重连的通话。使用 silenceDurationMs、startSensitivity 和 endSensitivity 可调整电话音频中更快的轮流发言。
{
plugins: {
entries: {
"voice-call": {
config: {
provider: "twilio",
inboundPolicy: "allowlist",
allowFrom: ["+15550005678"],
realtime: {
enabled: true,
provider: "google",
instructions: "Speak briefly. Call openclaw_agent_consult before using deeper tools.",
toolPolicy: "safe-read-only",
consultPolicy: "substantive",
consultThinkingLevel: "low",
consultFastMode: true,
agentContext: { enabled: true },
providers: {
google: {
apiKey: "${GEMINI_API_KEY}",
model: "gemini-3.1-flash-live-preview",
speakerVoice: "Kore",
silenceDurationMs: 500,
startSensitivity: "high",
},
},
},
},
},
},
},
}
有关特定提供商的实时语音选项,请参阅 Google 提供商 和 OpenAI 提供商。
流式转录¶
streaming 将 Twilio Media Streams 连接到实时转录提供商。经典流式路径要求 provider: "twilio";使用 Telnyx、Plivo 或 mock 的配置会被拒绝。Telnyx 实时音频改为使用单独认证的 realtime.enabled 路径。
运行时行为:
streaming.provider是可选的。如果未设置,Voice Call 会按提供商优先级顺序选择第一个已配置的实时转录提供商。即使另一个提供商已经处于活动状态,streaming.providers中列出的提供商也会被发现;插件禁用和允许/拒绝规则仍然适用。- 内置实时转录提供商:Deepgram(
deepgram)、ElevenLabs(elevenlabs)、Mistral(mistral)、OpenAI(openai)和 xAI(xai),由其提供商插件注册。 - 由提供商拥有的原始配置位于
streaming.providers.<providerId>下。 - 在 Twilio 发送已接受的流
start消息后,Voice Call 会立即注册该流,在提供商连接期间通过转录提供商排队传入媒体,并且仅在实时转录就绪后才开始初始问候。 - 如果
streaming.provider指向未注册的提供商,或者没有任何提供商注册,Voice Call 会记录警告并跳过媒体流,而不是让整个插件失败。
流式提供商示例¶
默认值:API 密钥为 streaming.providers.openai.apiKey 或 OPENAI_API_KEY;模型为 gpt-4o-transcribe;silenceDurationMs: 800;vadThreshold: 0.5。
默认值:API 密钥为 streaming.providers.xai.apiKey 或 XAI_API_KEY(如果两者都未设置,则回退到 xAI OAuth 认证配置);端点为 wss://api.x.ai/v1/stt;编码为 mulaw;采样率为 8000;endpointingMs: 800;interimResults: true。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw