ClawCN - OpenClaw 中文版

主题

语音通话(插件) ​

通过插件为 OpenClaw 提供语音通话功能。支持出站通知和带入站策略的多轮对话。

当前支持的提供商:

  • twilio (可编程语音 + 媒体流)
  • telnyx (呼叫控制 v2)
  • plivo (语音 API + XML 转接 + GetInput 语音)
  • mock (开发/无网络)

快速理解:

  • 安装插件
  • 重启 Gateway
  • 在 plugins.entries.voice-call.config 下配置
  • 使用 openclaw voicecall ... 或 voice_call 工具

运行位置(本地 vs 远程) ​

语音通话插件在 Gateway 进程内部运行。

如果您使用远程 Gateway,请在运行 Gateway 的机器上安装/配置插件,然后重启 Gateway 以加载它。

安装 ​

选项 A:从 npm 安装(推荐) ​

bash
openclaw plugins install @openclaw/voice-call

之后重启 Gateway。

选项 B:从本地文件夹安装(开发,无需复制) ​

bash
openclaw plugins install ./extensions/voice-call
cd ./extensions/voice-call && pnpm install

之后重启 Gateway。

配置 ​

在 plugins.entries.voice-call.config 下设置配置:

json5
{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio", // or "telnyx" | "plivo" | "mock"
          fromNumber: "+15550001234",
          toNumber: "+15550005678",

          twilio: {
            accountSid: "ACxxxxxxxx",
            authToken: "...",
          },

          plivo: {
            authId: "MAxxxxxxxxxxxxxxxxxxxx",
            authToken: "...",
          },

          // Webhook server
          serve: {
            port: 3334,
            path: "/voice/webhook",
          },

          // Webhook security (recommended for tunnels/proxies)
          webhookSecurity: {
            allowedHosts: ["voice.example.com"],
            trustedProxyIPs: ["100.64.0.1"],
          },

          // Public exposure (pick one)
          // publicUrl: "https://example.ngrok.app/voice/webhook",
          // tunnel: { provider: "ngrok" },
          // tailscale: { mode: "funnel", path: "/voice/webhook" }

          outbound: {
            defaultMode: "notify", // notify | conversation
          },

          streaming: {
            enabled: true,
            streamPath: "/voice/stream",
          },
        },
      },
    },
  },
}

注意事项:

  • Twilio/Telnyx 需要可公开访问的 webhook URL。
  • Plivo 需要可公开访问的 webhook URL。
  • mock 是本地开发提供商(无网络调用)。
  • skipSignatureVerification 仅用于本地测试。
  • 如果您使用 ngrok 免费版,请将 publicUrl 设置为确切的 ngrok URL;始终强制执行签名验证。
  • tunnel.allowNgrokFreeTierLoopbackBypass: true 仅当 tunnel.provider="ngrok" 且 serve.bind 为本地回环(ngrok 本地代理)时,允许具有无效签名的 Twilio webhook。仅用于本地开发。
  • Ngrok 免费版 URL 可能会改变或添加插页行为;如果 publicUrl 漂移,Twilio 签名将失败。对于生产环境,建议使用稳定域名或 Tailscale funnel。

Webhook 安全 ​

当代理或隧道位于 Gateway 前面时,插件会重建公共 URL 用于签名验证。这些选项控制信任哪些转发头。

webhookSecurity.allowedHosts 将转发头中的主机列入允许列表。

webhookSecurity.trustForwardingHeaders 无需允许列表即信任转发头。

webhookSecurity.trustedProxyIPs 仅当请求的远程 IP 匹配列表时才信任转发头。

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

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

通话的 TTS ​

语音通话使用核心 messages.tts 配置(OpenAI 或 ElevenLabs)在通话中进行流式语音合成。您可以在插件配置下使用相同的结构覆盖它 —— 它与 messages.tts 深度合并。

json5
{
  tts: {
    provider: "elevenlabs",
    elevenlabs: {
      voiceId: "pMsXgVXv3BLzUgSXRplE",
      modelId: "eleven_multilingual_v2",
    },
  },
}

注意事项:

  • 语音通话会忽略 Edge TTS(电话音频需要 PCM;Edge 输出不可靠)。
  • 当启用 Twilio 媒体流时使用核心 TTS;否则通话会回退到提供商原生语音。

更多示例 ​

仅使用核心 TTS(无覆盖):

json5
{
  messages: {
    tts: {
      provider: "openai",
      openai: { voice: "alloy" },
    },
  },
}

仅为通话覆盖到 ElevenLabs(在其他地方保留核心默认值):

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

仅覆盖通话的 OpenAI 模型(深度合并示例):

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

入站通话 ​

入站策略默认为 disabled。要启用入站通话,请设置:

json5
{
  inboundPolicy: "allowlist",
  allowFrom: ["+15550001234"],
  inboundGreeting: "Hello! How can I help?",
}

自动响应使用代理系统。可以调整:

  • responseModel
  • responseSystemPrompt
  • responseTimeoutMs

CLI ​

bash
openclaw voicecall call --to "+15555550123" --message "Hello from OpenClaw"
openclaw voicecall continue --call-id <id> --message "Any questions?"
openclaw voicecall speak --call-id <id> --message "One moment"
openclaw voicecall end --call-id <id>
openclaw voicecall status --call-id <id>
openclaw voicecall tail
openclaw voicecall expose --mode funnel

代理工具 ​

工具名称:voice_call

操作:

  • initiate_call (message, to?, mode?)
  • continue_call (callId, message)
  • speak_to_user (callId, message)
  • end_call (callId)
  • get_status (callId)

此仓库在 skills/voice-call/SKILL.md 提供匹配的技能文档。

Gateway RPC ​

  • voicecall.initiate (to?, message, mode?)
  • voicecall.continue (callId, message)
  • voicecall.speak (callId, message)
  • voicecall.end (callId)
  • voicecall.status (callId)