语音通话插件

通过插件为 OpenClaw 提供语音通话：出站通知、多轮 对话、全双工实时语音、流式转写，以及 采用允许列表策略的入站通话。

提供商： mock（开发，无网络）、plivo（语音 API + XML 转接 + GetInput 语音）、telnyx（Call Control v2）、twilio（可编程语音 + 媒体流）。

快速开始

openclaw plugins install @openclaw/voice-call

PLUGIN_SRC=./path/to/local/voice-call-pluginopenclaw plugins install "$PLUGIN_SRC"cd "$PLUGIN_SRC" && pnpm install

openclaw voicecall setupopenclaw voicecall setup --json

openclaw voicecall smokeopenclaw voicecall smoke --to "+15555550123"

openclaw voicecall smoke --to "+15555550123" --yes

配置

如果 enabled: true，但所选提供商缺少凭据，Gateway 网关 启动时会记录一条设置未完成警告，其中包含缺失的键，并跳过 启动运行时。使用命令、RPC 调用和智能体工具时，仍会返回 确切缺失的配置。

{  plugins: {    entries: {      "voice-call": {        enabled: true,        config: {          provider: "twilio", // 或 "telnyx" | "plivo" | "mock"          fromNumber: "+15550001234", // 对于 Twilio，也可使用 TWILIO_FROM_NUMBER          toNumber: "+15550005678",          sessionScope: "per-phone", // per-phone | per-call          numbers: {            "+15550009999": {              inboundGreeting: "这里是 Silver Fox Cards，请问有什么可以帮你？",              responseSystemPrompt: "你是一名回答简洁的棒球卡专家。",              tts: {                providers: {                  openai: { speakerVoice: "alloy" },                },              },            },          },           twilio: {            accountSid: "ACxxxxxxxx",            authToken: "...",            // region: "ie1", // 可选：us1 | ie1 | au1；默认为 us1          },          telnyx: {            apiKey: "...",            connectionId: "...",            // 来自 Mission Control Portal 的 Telnyx webhook 公钥            //（Base64；也可通过 TELNYX_PUBLIC_KEY 设置）。            publicKey: "...",          },          plivo: {            authId: "MAxxxxxxxxxxxxxxxxxxxx",            authToken: "...",          },           // Webhook 服务器          serve: {            port: 3334,            path: "/voice/webhook",          },           // Webhook 安全设置（建议用于隧道/代理）          webhookSecurity: {            allowedHosts: ["voice.example.com"],            trustedProxyIPs: ["100.64.0.1"],          },           // 公网暴露方式（任选其一）          // publicUrl: "https://example.ngrok.app/voice/webhook",          // tunnel: { provider: "ngrok" },          // tailscale: { mode: "funnel", path: "/voice/webhook" },           outbound: {            defaultMode: "notify", // notify | conversation          },           streaming: { enabled: true /* 仅限 Twilio；参见流式转写 */ },          realtime: { enabled: false /* 参见实时语音对话 */ },        },      },    },  },}

配置参考

上方未列出的 plugins.entries.voice-call.config 下顶层键：

Twilio 默认使用其 US1 REST 端点。若要在受支持的 非美国 Region 中处理通话，请将 twilio.region 设置为 ie1 或 au1，并使用 该 Region 的凭据。参见 Twilio 的非美国 REST API 指南。

会话范围

默认情况下，语音通话使用 sessionScope: "per-phone"，因此来自 同一来电者的重复通话会保留对话记忆。当每次运营商通话都应 使用全新上下文开始时，请设置 sessionScope: "per-call"，例如前台接待、 预约、IVR 或 Google Meet 桥接流程，因为在这些流程中，同一个电话号码可能 代表不同的会议。

语音通话会将生成的会话键存储在已配置的智能体命名空间 （agent:<agentId>:voice:*）下。原始的显式集成键会解析到 同一命名空间中：规范的 agent:<configuredAgentId>:* 键会保留该 所有者，并遵循核心 session.mainKey/全局范围别名；外部或 格式错误的 agent:* 输入会作为不透明键，限定在已配置的 智能体下；global 和 unknown 仍为全局哨兵值。

实时语音对话

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

当前运行时行为：

• realtime.enabled 支持 Twilio 和 Telnyx。
• realtime.provider 是可选的。如果未设置，Voice Call 将使用第一个已注册的实时语音提供商。
• 内置实时语音提供商：Google Gemini Live（google）和 OpenAI（openai），由各自的提供商插件注册。
• 提供商拥有的原始配置位于 realtime.providers.<providerId> 下。
• Voice Call 默认公开共享的 openclaw_agent_consult 实时工具。当呼叫者要求进行更深入的推理、获取当前信息或使用常规 OpenClaw 工具时，实时模型可以调用该工具。
• realtime.consultPolicy 可选择性地添加指导，说明实时模型应在何时调用 openclaw_agent_consult。
• realtime.agentContext.enabled 默认关闭。启用后，Voice Call 会在会话设置期间，将有界的智能体身份和选定的工作区文件上下文包注入实时提供商的指令中。
• 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）。

工具策略

realtime.toolPolicy 控制咨询运行：

realtime.consultPolicy 仅控制实时模型指令：

智能体语音上下文

如果希望语音桥接听起来像配置的 OpenClaw 智能体，同时又不想让普通轮次承担一次完整的智能体咨询往返开销，请启用 realtime.agentContext。上下文包仅在创建实时会话时添加一次，因此不会增加每轮延迟。调用 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: "简短回答。在使用更深入的工具之前调用 openclaw_agent_consult。",            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 provider。

流式转录

streaming 将 Twilio Media Streams 连接到实时转录提供商。 经典流式传输路径要求使用 provider: "twilio"；使用 Telnyx、Plivo 或 mock 的配置会被拒绝。Telnyx 实时音频改用单独进行身份验证的 realtime.enabled 路径。

当前运行时行为：

• streaming.provider 是可选的。如果未设置，Voice Call 将使用第一个已注册的实时转录提供商。
• 内置实时转录提供商：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-...", // 如果已设置 OPENAI_API_KEY，则此项可选                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}", // 如果已设置 XAI_API_KEY，则此项可选                endpointingMs: 800,                language: "en",              },            },          },        },      },    },  },}

通话 TTS

Voice Call 使用核心 messages.tts 配置进行通话中的流式语音合成。 你可以在插件配置下使用相同结构覆盖该配置——它会与 messages.tts 进行深度合并。

{  tts: {    provider: "elevenlabs",    providers: {      elevenlabs: {        speakerVoiceId: "pMsXgVXv3BLzUgSXRplE",        modelId: "eleven_multilingual_v2",      },    },  },}

行为说明：

• 插件配置中的旧版 tts.<provider> 键（openai、elevenlabs、microsoft、edge）会由 openclaw doctor --fix 修复；提交的配置应使用 tts.providers.<provider>。
• 启用 Twilio 媒体流式传输时使用核心 TTS；否则通话会回退到提供商原生语音。
• 如果 Twilio 媒体流已经处于活动状态，Voice Call 不会回退到 TwiML OPENCLAW_DOCS_MARKER:calloutOpen:U2F5。如果在该状态下无法使用电话 TTS，播放请求会失败，而不会混用两条播放路径。
• 当电话 TTS 回退到次级提供商时，Voice Call 会记录一条包含提供商链（from、to、attempts）的警告，以便调试。
• 当 Twilio 插话或流拆除清空待处理的 TTS 队列时，已排队的播放请求会正常结束，而不会让正在等待播放完成的呼叫者一直挂起。

TTS 示例

{messages: {tts: {provider: "openai",providers: {  openai: { speakerVoice: "alloy" },},},},}

{plugins: {entries: {"voice-call": {  config: {    tts: {      provider: "elevenlabs",      providers: {        elevenlabs: {          apiKey: "elevenlabs_key",          speakerVoiceId: "pMsXgVXv3BLzUgSXRplE",          modelId: "eleven_multilingual_v2",        },      },    },  },},},},}

{plugins: {entries: {"voice-call": {  config: {    tts: {      providers: {        openai: {          model: "gpt-4o-mini-tts",          speakerVoice: "marin",        },      },    },  },},},},}

来电

来电策略默认为 disabled。要启用来电，请设置：

{inboundPolicy: "allowlist",allowFrom: ["+15550001234"],inboundGreeting: "你好！我能为你做些什么？",}

自动响应使用智能体系统。可通过 responseModel、 responseSystemPrompt 和 responseTimeoutMs 进行调整。

按号码路由

当一个 Voice Call 插件接收多个电话号码的来电，并且每个号码都应像不同线路一样运行时，请使用 numbers。例如，一个号码可以使用随和的个人助理，而另一个号码则使用商务角色、不同的响应智能体和不同的 TTS 语音。

路由根据提供商给出的被叫 To 号码进行选择。键必须是 E.164 号码。来电时，Voice Call 会解析一次匹配的路由，将匹配的路由存储在通话记录中，并为问候语、经典自动响应路径、实时咨询路径和 TTS 播放复用该有效配置。如果没有匹配的路由，则使用全局 Voice Call 配置。外呼不使用 numbers；发起通话时请显式传入外呼目标、消息和会话。

路由覆盖目前支持：

• inboundGreeting
• tts
• agentId
• responseModel
• responseSystemPrompt
• responseTimeoutMs

tts 路由值会深度合并到全局 Voice Call tts 配置之上，因此通常只需覆盖提供商语音：

{inboundGreeting: "你好，这里是总机。",responseSystemPrompt: "你是默认语音助理。",tts: {  provider: "openai",  providers: {    openai: { speakerVoice: "coral" },  },},numbers: {  "+15550001111": {    inboundGreeting: "这里是 Silver Fox Cards，请问需要什么帮助？",    responseSystemPrompt: "你是一名言简意赅的棒球卡专家。",    tts: {      providers: {        openai: { speakerVoice: "alloy" },      },    },  },},}

语音输出契约

对于自动响应，Voice Call 会在系统提示词后附加严格的语音输出契约，要求返回 {"spoken":"..."} JSON。Voice Call 会以防御性方式提取语音文本：

• 忽略标记为推理/错误内容的载荷。
• 解析直接 JSON、带围栏的 JSON 或内联 "spoken" 键。
• 回退到纯文本，并删除可能属于规划/元信息引导语的段落。

这能让语音播放聚焦于面向来电者的文本，并避免将规划文本泄露到音频中。

对话启动行为

对于外呼 conversation 通话，首条消息的处理与实时播放状态绑定：

• 仅在初始问候语正在主动播放时，才会抑制插话队列清除和自动响应。
• 如果初始播放失败，通话会返回 listening，且初始消息仍保留在队列中以供重试。
• Twilio 流式传输的初始播放会在流连接时立即开始，不会增加额外延迟。
• 插话会中止当前播放，并清除已排队但尚未播放的 Twilio TTS 条目。被清除的条目会以已跳过状态完成，因此后续响应逻辑可以继续执行，而不必等待永远不会播放的音频。
• 实时语音对话使用实时流自身的开场轮次。Voice Call 不会为该初始消息发送旧版 OPENCLAW_DOCS_MARKER:calloutOpen:U2F5 TwiML 更新，因此外呼 <Connect><Stream> 会话会保持连接。

Twilio 流断开宽限期

当 Twilio 媒体流断开时，Voice Call 会等待 2000 ms，然后再自动结束通话：

• 如果流在此时间窗口内重新连接，则取消自动结束。
• 如果宽限期过后仍没有流重新注册，则结束通话，以防止通话卡在活动状态。

过期通话清理器

使用 staleCallReaperSeconds（默认值为 120）结束始终无人接听且从未进入实时对话状态的通话，例如提供商始终未投递终止 Webhook 的通知模式通话。将其设为 0 可禁用此功能。

清理器每 30 秒运行一次，并且仅结束没有 answeredAt 时间戳、且尚未处于终止或实时（speaking/listening）状态的通话，因此已接听的对话绝不会被此计时器清理；maxDurationSeconds（默认值为 300）是另一个独立上限，用于结束持续时间过长的已接听通话。

对于运营商可能延迟投递响铃/接听 Webhook 的通知式流程，请将 staleCallReaperSeconds 提高到默认值以上，以免过早清理速度较慢但正常的通话；120-300 秒是合理的生产环境范围。

{plugins: {entries: {  "voice-call": {    config: {      maxDurationSeconds: 300,      staleCallReaperSeconds: 120,    },  },},},}

Webhook 安全性

当 Gateway 网关前方设有代理或隧道时，插件会重建用于签名验证的公共 URL。以下选项控制信任哪些转发标头：

其他保护措施：

• Twilio、Telnyx 和 Plivo 已启用 Webhook 重放保护。重放的有效 Webhook 请求会得到确认，但会跳过其副作用。
• Twilio 对话轮次会在 <Gather> 回调中包含每轮令牌，因此过期或重放的语音回调无法满足较新的待处理转录轮次。
• 当缺少提供商要求的签名标头时，未经身份验证的 Webhook 请求会在读取正文前被拒绝。
• voice-call Webhook 在签名验证前使用共享的身份预验证正文读取配置（正文最大 64 KB，读取超时 5 秒），并应用按键限制的进行中请求上限（默认每个键 8 个并发请求）。

使用稳定公共主机的示例：

{plugins: {entries: {  "voice-call": {    config: {      publicUrl: "https://voice.example.com/voice/webhook",      webhookSecurity: {        allowedHosts: ["voice.example.com"],      },    },  },},},}

CLI

openclaw voicecall call --to "+15555550123" --message "来自 OpenClaw 的问候"openclaw voicecall start --to "+15555550123"   # call 的别名openclaw voicecall continue --call-id <id> --message "还有什么问题吗？"openclaw voicecall speak --call-id <id> --message "请稍等"openclaw voicecall dtmf --call-id <id> --digits "ww123456#"openclaw voicecall end --call-id <id>openclaw voicecall status --call-id <id>openclaw voicecall tailopenclaw voicecall latency                      # 根据日志汇总轮次延迟openclaw voicecall expose --mode funnel

当 Gateway 网关已在运行时，操作类 voicecall 命令会委托给 Gateway 网关拥有的 voice-call 运行时，因此 CLI 不会绑定第二个 Webhook 服务器。如果无法连接任何 Gateway 网关，这些命令会回退到独立的 CLI 运行时。

latency 从默认 voice-call 存储路径读取 calls.jsonl。使用 --file <path> 指向其他日志，并使用 --last <n> 将分析限制为最后 N 条记录（默认 200）。输出包含轮次延迟和监听等待时间的最小值/最大值/平均值、p50 和 p95。

智能体工具

工具名称：voice_call。

voice-call 插件附带一个匹配的智能体技能。

Gateway RPC 参考

dtmfSequence 仅可与 mode: "conversation" 一起使用；如果通知模式的通话需要在连接后发送 数字，应在通话建立后使用 voicecall.dtmf。

故障排查

设置因 webhook 暴露失败

在运行 Gateway 网关的同一环境中运行设置：

openclaw voicecall setupopenclaw voicecall setup --json

对于 twilio、telnyx 和 plivo，webhook-exposure 必须为绿色。 即使配置了 publicUrl，如果它指向本地或私有网络空间，仍会失败， 因为运营商无法回调这些地址。 请勿将 localhost、127.0.0.1、0.0.0.0、10.x、172.16.x-172.31.x、 192.168.x、169.254.x、fc00::/7、fd00::/8 或其他运营商级 NAT 地址范围用作 publicUrl。

Twilio 通知模式的出站通话会在创建通话请求中直接发送其初始 OPENCLAW_DOCS_MARKER:calloutOpen:U2F5 TwiML， 因此第一条语音消息不依赖 Twilio 获取 webhook TwiML。状态回调、对话通话、 连接前 DTMF、实时流和连接后通话控制仍需要公共 webhook。

使用一种公共暴露方式：

{plugins: {entries: {"voice-call": {  config: {    publicUrl: "https://voice.example.com/voice/webhook",    // 或    tunnel: { provider: "ngrok" },    // 或    tailscale: { mode: "funnel", path: "/voice/webhook" },  },},},},}

更改配置后，重启或重新加载 Gateway 网关，然后运行：

openclaw voicecall setupopenclaw voicecall smoke

除非传入 --yes，否则 voicecall smoke 仅执行试运行。

提供商凭据失败

检查所选提供商和必需的凭据字段：

• Twilio：twilio.accountSid、twilio.authToken 和 fromNumber，或者 TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN 和 TWILIO_FROM_NUMBER。
• Telnyx：telnyx.apiKey、telnyx.connectionId、telnyx.publicKey 和 fromNumber，或者 TELNYX_API_KEY、TELNYX_CONNECTION_ID 和 TELNYX_PUBLIC_KEY。
• Plivo：plivo.authId、plivo.authToken 和 fromNumber，或者 PLIVO_AUTH_ID 和 PLIVO_AUTH_TOKEN。

凭据必须存在于 Gateway 网关主机上。编辑本地 shell 配置文件不会影响已在运行的 Gateway 网关，除非它重启或重新加载其环境。

通话已开始，但未收到提供商 webhook

确认提供商控制台指向准确的公共 webhook URL：

https://voice.example.com/voice/webhook

然后检查运行时状态：

openclaw voicecall status --call-id <id>openclaw voicecall tailopenclaw logs --follow

常见原因：

• publicUrl 指向的路径与 serve.path 不同。
• Gateway 网关启动后，隧道 URL 发生了变化。
• 代理转发了请求，但移除或重写了 host/proto 标头。
• 防火墙或 DNS 将公共主机名路由到了 Gateway 网关之外的位置。
• Gateway 网关重启时未启用 Voice Call 插件。

当 Gateway 网关前方有反向代理或隧道时，将 webhookSecurity.allowedHosts 设置为公共主机名，或者对已知代理地址使用 webhookSecurity.trustedProxyIPs。仅当代理边界 由你控制时，才使用 webhookSecurity.trustForwardingHeaders。

签名验证失败

提供商签名会根据 OpenClaw 从传入请求重建的公共 URL 进行检查。 如果签名失败：

• 确认提供商 webhook URL 与 publicUrl 完全匹配，包括协议、主机和路径。
• 对于 ngrok 免费层 URL，当隧道主机名发生变化时更新 publicUrl。
• 确保代理保留原始 host 和 proto 标头，或者配置 webhookSecurity.allowedHosts。
• 不要在本地测试以外的环境中启用 skipSignatureVerification。

Google Meet Twilio 加入失败

Google Meet 使用此插件进行 Twilio 拨号加入。首先验证 Voice Call：

openclaw voicecall setupopenclaw voicecall smoke --to "+15555550123"

然后明确验证 Google Meet 传输：

openclaw googlemeet setup --transport twilio

如果 Voice Call 状态为绿色，但 Meet 参与者始终未加入，请检查 Meet 拨入号码、PIN 和 --dtmf-sequence。即使电话通话状态正常， 会议仍可能拒绝或忽略错误的 DTMF 序列。

Google Meet 通过 voicecall.start 启动 Twilio 电话通话段，并附带 连接前 DTMF 序列。由 PIN 派生的序列会将 Google Meet 插件的 voiceCall.dtmfDelayMs（默认 12000 ms）作为开头的 Twilio 等待数字，因为 Meet 拨入提示可能延迟出现。随后，Voice Call 会在请求开场问候语之前 重定向回实时处理。

使用 openclaw logs --follow 查看实时阶段跟踪。正常的 Twilio Meet 加入会按以下顺序记录日志：

• Google Meet 将 Twilio 加入委托给 Voice Call。
• Voice Call 存储连接前 DTMF TwiML。
• 在实时处理之前，Twilio 初始 TwiML 已被使用并提供。
• Voice Call 为 Twilio 通话提供实时 TwiML。
• Google Meet 在 DTMF 后延迟结束后，使用 voicecall.speak 请求开场语音。

openclaw voicecall tail 仍会显示持久化的通话记录；它适用于查看 通话状态和转录记录，但并非所有 webhook/实时转换 都会显示在其中。

实时通话没有语音

确认仅启用一种音频模式：realtime.enabled 和 streaming.enabled 不能同时为 true。

对于实时 Twilio/Telnyx 通话，还需验证：

• 已加载并注册实时提供商插件。
• realtime.provider 未设置，或指定了已注册的提供商。
• Gateway 网关进程可以访问提供商 API 密钥。
• openclaw logs --follow 显示已提供实时 TwiML、实时桥接已启动，并且初始问候语已加入队列。

相关内容

• Talk 模式
• 文本转语音
• 语音唤醒