跳转到主要内容

​
Voice Call（插件）

通过插件为 OpenClaw 提供语音通话。支持出站通知和带有入站策略的多轮对话。 支持外呼通知以及 具备来电策略的多轮对话。 当前提供商：
  • twilio（Programmable Voice + Media Streams）
  • telnyx（Call Control v2）
  • plivo（Voice API + XML transfer + GetInput speech）
  • mock（开发/无网络）
快速心智模型：
  • 安装插件
  • 重启 Gateway 网关
  • 在 plugins.entries.voice-call.config 下配置
  • 使用 openclaw voicecall ... 或 voice_call 工具

​
运行位置（本地 vs 远程）

Voice Call 插件运行在 Gateway 网关进程内部。 如果你使用远程 Gateway 网关，在运行 Gateway 网关的机器上安装/配置插件，然后重启 Gateway 网关以加载它。

​
安装

​
选项 A：从 npm 安装（推荐）

openclaw plugins install @openclaw/voice-call
之后重启 Gateway 网关。

​
选项 B：从本地文件夹安装（开发，不复制）

openclaw plugins install ./extensions/voice-call
cd ./extensions/voice-call && pnpm install
之后重启 Gateway 网关。

​
配置

在 plugins.entries.voice-call.config 下设置配置： 
{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio", // 或 "telnyx" | "plivo" | "mock"
          fromNumber: "+15550001234",
          toNumber: "+15550005678",

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

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

          // Webhook 服务器
          serve: {
            port: 3334,
            path: "/voice/webhook",
          },

          // 公开暴露（选一个）
          // 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 为 true，否则 Telnyx 需要 telnyx.publicKey（或 TELNYX_PUBLIC_KEY）。
  • skipSignatureVerification 仅用于本地测试。
  • 如果你使用 ngrok 免费版，将 publicUrl 设置为确切的 ngrok URL；签名验证始终强制执行。
  • tunnel.allowNgrokFreeTierLoopbackBypass: true 允许带有无效签名的 Twilio webhooks，仅当 tunnel.provider="ngrok" 且 serve.bind 是 loopback（ngrok 本地代理）时。仅用于本地开发。 Use for local dev only.
  • Ngrok 免费版 URL 可能会更改或添加中间页面行为；如果 publicUrl 漂移，Twilio 签名将失败。对于生产环境，优先使用稳定域名或 Tailscale funnel。 For production, prefer a stable domain or Tailscale funnel.

​
Webhook Security

When a proxy or tunnel sits in front of the Gateway, the plugin reconstructs the public URL for signature verification. These options control which forwarded headers are trusted. webhookSecurity.allowedHosts allowlists hosts from forwarding headers. webhookSecurity.trustForwardingHeaders trusts forwarded headers without an allowlist. webhookSecurity.trustedProxyIPs only trusts forwarded headers when the request remote IP matches the list. Example with a stable public host: 
{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          publicUrl: "https://voice.example.com/voice/webhook",
          webhookSecurity: {
            allowedHosts: ["voice.example.com"],
          },
        },
      },
    },
  },
}

​
通话的 TTS

Voice Call 使用核心 messages.tts 配置（OpenAI 或 ElevenLabs）进行通话中的流式语音。你可以在插件配置下使用相同的结构覆盖它——它会与 messages.tts 深度合并。 You can override it under the plugin config with the same shape — it deep‑merges with messages.tts. 
{
  tts: {
    provider: "elevenlabs",
    elevenlabs: {
      voiceId: "pMsXgVXv3BLzUgSXRplE",
      modelId: "eleven_multilingual_v2",
    },
  },
}
注意事项：
  • 语音通话忽略 Edge TTS（电话音频需要 PCM；Edge 输出不可靠）。
  • 当启用 Twilio 媒体流时使用核心 TTS；否则通话回退到提供商原生语音。

​
更多示例

仅使用核心 TTS（无覆盖）： 
{
  messages: {
    tts: {
      provider: "openai",
      openai: { voice: "alloy" },
    },
  },
}
仅为通话覆盖为 ElevenLabs（其他地方保持核心默认）： 
{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          tts: {
            provider: "elevenlabs",
            elevenlabs: {
              apiKey: "elevenlabs_key",
              voiceId: "pMsXgVXv3BLzUgSXRplE",
              modelId: "eleven_multilingual_v2",
            },
          },
        },
      },
    },
  },
}
仅为通话覆盖 OpenAI 模型（深度合并示例）： 
{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          tts: {
            openai: {
              model: "gpt-4o-mini-tts",
              voice: "marin",
            },
          },
        },
      },
    },
  },
}

​
入站通话

  1. 入站策略默认设置为 disabled。 2. 要启用入站呼叫，请设置：
{
  inboundPolicy: "allowlist",
  allowFrom: ["+15550001234"],
  inboundGreeting: "Hello! How can I help?",
}
  1. 自动回复使用代理系统。 5. 可通过以下参数进行调优：
  • responseModel
  • responseSystemPrompt
  • responseTimeoutMs

​
CLI

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

​
11. 代理工具

工具名称：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 提供了配套的 skill 文档。

​
Gateway 网关 RPC

  • voicecall.initiate（to?、message、mode?）
  • voicecall.continue（callId、message）
  • voicecall.speak（callId、message）
  • voicecall.end（callId）
  • voicecall.status（callId）