故障排除

针对设置、webhook 暴露、凭据、签名验证、Google Meet 拨入和静默实时通话的修复。是 Voice call 插件指南的一部分。

故障排查¶

呼叫发起时无法保存其初始记录¶

Voice Call 在保存初始记录时预留待处理容量，只有在写入成功后才发布活跃呼叫并联系运营商。如果写入失败，发起过程会报告存储错误而不进行拨号，并释放预留。恢复对状态目录的访问后重试；失败的发起不会消耗 maxConcurrentCalls 容量。

Webhook 确认和基于转录的回复会等待呼叫记录持久化。绑定令牌的实时流会先等待待处理的呼叫更新，再匹配运营商 ID。失败的事件写入仍可重试，而关闭会在 webhook 和流生产者关闭后排空已接纳的呼叫工作。

如果在接纳期间另一个实时流变为活跃状态，创建新桥接失败时，该活跃呼叫仍保持连接。

设置时 webhook 暴露失败¶

请在与运行 Gateway 相同的环境中运行设置：

openclaw voicecall setup
openclaw 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 notify 模式的外呼呼叫会在 create-call 请求中直接发送初始的 <Say> TwiML，因此第一句语音消息不依赖于 Twilio 获取 webhook TwiML。状态回调、对话呼叫、连接前 DTMF、实时流和连接后呼叫控制仍然需要公共 webhook。

使用一个公共暴露路径：

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

配置更改在默认的混合重载模式下会自动生效（参见热重载）。应用后运行：

openclaw voicecall setup
openclaw 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。

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

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

请确认提供商控制台指向的公共 webhook URL 完全正确：

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

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

Voice webhook: https://voice.example.com/voice/webhook 使用 POST。
Status Callback: https://voice.example.com/voice/webhook?type=status 使用 POST。

Media Streams 的 stop/WebSocket 关闭处理是主要的自动结束路径，不依赖于 HTTP 状态回调。Twilio 可选的 ` 是独立的流诊断信号，对于拆除不是必需的。openclaw voicecall setup` 会验证本地配置和 webhook 暴露；它无法检查或更改 Twilio 控制台设置。

然后检查运行时状态：

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

常见原因：

publicUrl 与提供商配置的公共 webhook URL 不匹配。反向代理可能会将该公共路径映射到不同的 serve.path，但 publicUrl 必须保持为面向提供商的 URL。
隧道 URL 在 Gateway 启动后发生了更改。
代理转发了请求，但剥离或重写了 host/proto 请求头。
防火墙或 DNS 将公共主机名路由到了 Gateway 以外的其他地方。
Gateway 在未启用 Voice Call 插件的情况下被重启。

当 Gateway 前面有反向代理或隧道时，请将 webhookSecurity.allowedHosts 设置为公共主机名，或对已知的代理地址使用 webhookSecurity.trustedProxyIPs。只有在代理边界受你控制时才使用 webhookSecurity.trustForwardingHeaders。

签名验证失败¶

Twilio 和 Plivo 的 URL 签名在配置了 publicUrl 时会使用它：其 scheme、主机和路径会被保留，同时应用请求查询。如果没有 publicUrl，OpenClaw 会根据请求重建 URL。Telnyx 签名不包含请求 URL。如果签名验证失败：

确认提供商 webhook URL 与 publicUrl 完全匹配，包括 scheme、主机和路径。
对于 ngrok 免费版 URL，当隧道主机名更改时更新 publicUrl。
确保代理保留原始 host 和 proto 请求头，或配置 webhookSecurity.allowedHosts。
不要在本地测试之外启用 skipSignatureVerification。

Google Meet Twilio 加入失败¶

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

openclaw voicecall setup
openclaw 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、实时桥接已启动，并且初始问候已排队。

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