实时和流式

全双工实时语音、挂断检测、工具与咨询策略、智能体语音上下文，以及 Twilio Media Streams 转录。是 Voice call 插件 指南的一部分。

实时语音对话¶

realtime 为实时通话音频选择全双工实时语音提供商。 它与 streaming 不同，后者仅将音频转发给实时转录提供商。

运行时行为：

• 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。
• 在具有共享上下文解析器的主机上，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 使用与 Discord 和 Talk 相同的由 Gateway 拥有的 GPT-Live 桥接。 选择 gpt-live-1-codex 并搭配 cove，以使用 ChatGPT OAuth 路由；它会先尝试 路由智能体的 OpenClaw ChatGPT 配置文件，然后尝试已配置的 Platform 密钥、API 密钥配置文件和 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 不会添加本地语音触发的取消。 初始问候和 voicecall.speak 请求使用相同的原生会话 上下文路径。委托的工作会保留通话的智能体、工具策略和 取消生命周期。

GPT-Live 会拒绝 realtime.consultPolicy: "always"：它拥有委托控制权， 无法强制执行主机触发的转录咨询。请使用 "auto" 或 "substantive" 指导，或选择支持主机控制轮次的模型。 realtime.toolPolicy: "none" 也会禁用原生委托的智能体咨询。 上述结束通话和自定义函数工具限制仍然适用。

挂断检测¶

实时通话通常在运营商发送流停止事件或关闭 媒体 WebSocket 时结束。如果中间件没有及时转发该关闭， OpenClaw 会将 30 秒没有入站媒体视为断开连接，等待 2 秒宽限期让媒体恢复，然后结束通话。

如果实时提供商先结束其会话，OpenClaw 也会结束运营商 通话，包括当提供商报告正常关闭时。这可防止在语音会话结束后，静默的 电话连接仍然保持打开。

支持函数工具的模型也可以在主叫方要求挂断时调用 openclaw_end_call。模型必须在调用该工具之前说出任何最后的话：成功 调用会立即结束当前提供商会话和电话连接， 因此之后不会再说出回复。如果运营商无法结束通话， 桥接会保持连接，模型会收到一个错误，它可以向主叫方解释。配置的 realtime.tools 无法按名称替换此内置工具。

对于传入的 Twilio 号码，还需使用 POST 配置状态回调，指向你的公共 webhook URL，并在 URL 后附加 ?type=status，例如 https://voice.example.com/voice/webhook?type=status。包含 completed 呼叫事件。由 OpenClaw 创建的出站呼叫会自动配置其回调。该回调提供最快的拆除信号，而流关闭和非活动兜底机制仍独立于它。

工具策略¶

realtime.toolPolicy 仅控制 consult 运行。在支持函数工具的模型上，它永远不会禁用 openclaw_end_call：

realtime.consultPolicy 用于指导实时模型。always 还会在提供商不进行 consult 时启用主机转录回退，并且在 GPT-Live 中不受支持：

当主机工具运行报告取消时，实时模型会收到一个已取消的结果，电话呼叫保持打开状态。超时和其他工具失败仍视为错误；结束电话会话会抑制待处理的 consult 结果。

代理语音上下文¶

在具有共享上下文解析器的主机上，每个实时会话都包含一个代理上下文段落，说明语音模型代表一个拥有多个会话的 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 限制整个可选胶囊，包括身份、标题和截断标记。较新的多会话段落在该路径上不可用。当受支持的主机最低版本包含共享上下文解析器时，此兼容性路径将退役。

上下文在创建实时会话时添加，因此不会增加每轮延迟。对 openclaw_agent_consult 的调用仍会运行完整的 OpenClaw 代理，应将其用于工具工作、当前信息、记忆查找或工作区状态。

{
  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"],
            },
          },
        },
      },
    },
  },
}

实时提供商示例¶

{
  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",
              },
            },
          },
        },
      },
    },
  },
}

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          realtime: {
            enabled: true,
            provider: "openai",
            providers: {
              openai: { apiKey: "${OPENAI_API_KEY}" },
            },
          },
        },
      },
    },
  },
}

有关特定提供商的实时语音选项，请参阅 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 会记录警告并跳过媒体流，而不是让整个插件失败。

流式提供商示例¶

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "openai",
            streamPath: "/voice/stream",
            providers: {
              openai: {
                apiKey: "sk-...", // optional if OPENAI_API_KEY is set
                model: "gpt-4o-transcribe",
                silenceDurationMs: 800,
                vadThreshold: 0.5,
              },
            },
          },
        },
      },
    },
  },
}

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "xai",
            streamPath: "/voice/stream",
            providers: {
              xai: {
                apiKey: "${XAI_API_KEY}", // optional if XAI_API_KEY is set
                endpointingMs: 800,
                language: "en",
              },
            },
          },
        },
      },
    },
  },
}