OpenClaw 中文文档
本页内容

本页内容

查看 Markdown以纯文本查看本页在 ChatGPT 中打开针对本页提问在 Claude 中打开针对本页提问

插件指南

语音通话故障排除

修复了设置、Webhook 暴露、凭据、签名验证、Google Meet 拨入和静默实时通话。 语音通话插件指南的一部分。

故障排查

呼叫放置未能保存其初始记录

语音呼叫在保存初始记录的同时保留待处理容量，然后仅在写入成功后发布活动呼叫并联系运营商。如果写入失败，placement会报告存储错误，无需拨号，并释放预留。恢复对状态目录的访问，然后重试；失败的放置不会消耗 maxConcurrentCalls 容量。

Webhook 确认和转录驱动的回复等待通话记录持久化。令牌绑定的实时流在匹配运营商 ID 之前等待挂起的呼叫更新。失败的事件写入仍然可以重试，并且关闭 webhook 和流生成器后会耗尽已承认的调用工作。

如果另一个实时流在准入期间变为活动状态，则创建新桥失败会导致该活动呼叫保持连接状态。

Setup webhook 暴露失败

从运行 Gateway 的相同环境中运行 setup：

bash
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，或其他 carrier-grade-NAT 地址段用作 publicUrl。

Twilio notify-mode outbound calls 会在 create-call 请求中直接发送其初始 <Say> TwiML，因此第一条播报消息不依赖于 Twilio 获取 webhook TwiML。即便如此，状态回调、会话通话、预连接 DTMF、实时流以及连接后通话控制仍然需要一个公共 webhook。

使用一种公共暴露路径：

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

配置更改会自动应用默认的混合重新加载模式（请参阅 HHot reload）。应用后，运行：

bash
openclaw voicecall setupopenclaw voicecall smoke

voicecall smoke 是一次演练，除非您通过了 --yes。

提供商凭据失败

检查所选提供商以及所需的凭据字段：

  • 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。

凭证必须存在于网关主机上。编辑本地 shell 配置文件不会更改网关的运行环境。更改基于环境的凭据时，更新其服务环境并重新启动网关。

呼叫开始但提供商 webhook 未到达

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

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

对于Twilio呼入号码，在Twilio控制台中配置两个号码级回调：

  • Voice webhook： https://voice.example.com/voice/webhook 使用 POST。
  • 状态回调： https://voice.example.com/voice/webhook?type=status使用POST。

媒体流 stop/WebSocket 关闭处理是主要自动结束路径，不依赖于 HTTP 状态回调。 Twilio 的可选 <Stream statusCallback> 是一个单独的流诊断信号，拆卸时不需要。 openclaw voicecall setup 验证本地配置和 webhook 暴露；它无法检查或更改 Twilio 控制台设置。

然后检查运行时状态：

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

常见原因：

  • publicUrl 与提供商配置的公共 webhook URL 不匹配。反向代理可以将该公共路径映射到不同的 serve.path，但 publicUrl 必须保持为面向提供商的 URL。
  • Gateway 启动后隧道 URL 发生了变化。
  • 代理转发了请求，但移除或重写了 host/proto 头。
  • 防火墙或 DNS 将公共主机名路由到了 Gateway 以外的位置。
  • Gateway 重启时未启用 Voice Call 插件。

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

签名验证失败

Twilio 和 Plivo URL 签名在配置时使用 publicUrl：在应用请求查询时，保留其方案、主机和路径。如果没有 publicUrl，OpenClaw 将根据请求重建 URL。 Telnyx 签名不包括请求 URL。如果签名失败：

  • 确认提供商 webhook URL 与 publicUrl 完全一致，包括 scheme、host 和 path。
  • 对于 ngrok 免费层 URL，当隧道主机名更改时更新 publicUrl。
  • 检查代理是否保留原始主机和原始标头，或配置 webhookSecurity.allowedHosts。
  • 不要在本地测试之外启用 skipSignatureVerification。

Google Meet Twilio 加入失败

Google Meet 使用此插件来完成 Twilio 拨入加入。首先验证 Voice Call：

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

然后显式验证 Google Meet 传输：

bash
openclaw googlemeet setup --transport twilio

如果 Voice Call 是绿色的，但参会者始终未加入，请检查 Meet 的拨入号码、PIN 以及 --dtmf-sequence。电话呼叫本身可能是正常的，但会议会拒绝或忽略错误的 DTMF 序列。

Google Meet 通过 voicecall.start 使用预连接 DTMF 序列启动 Twilio 电话线路。 PIN- 派生序列包括 Google Meet 插件的 voiceCall.dtmfDelayMs（默认 12000 ms）作为前导 Twilio 等待数字，因为 Meet 拨入提示可能会延迟到达。然后，在请求介绍问候语之前，语音呼叫将重定向回实时处理。

使用 openclaw logs --follow 查看实时阶段追踪。健康的 Twilio Meet 加入日志顺序如下：

  • Google Meet 将 Twilio 加入委托给 Voice Call。
  • Voice Call 存储预连接 DTMF TwiML。
  • 在实时处理之前，Twilio 初始 TwiML 被消耗并提供。
  • Voice Call 为 Twilio 呼叫提供实时 TwiML。
  • Google Meet 在 post-DTMF 延迟后使用 voicecall.speak 请求介绍语音。

openclaw voicecall tail 仍显示持续通话记录；对于呼叫状态和转录很有用，但并非每个 webhook/realtime 转换都会出现在那里。

实时呼叫没有语音

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

对于实时 Twilio/Telnyx 呼叫，还要验证：

  • 已加载并注册实时提供商插件。
  • realtime.provider 未设置，或指定了一个已注册的提供商。
  • 提供商 API key 对 Gateway 进程可用。
  • openclaw logs --follow 显示已提供实时 TwiML、实时桥接已启动，并且初始问候语已排队。
本页有帮助吗？