语音通话（插件）

OpenClaw 的语音通话功能，通过插件实现。支持外呼通知和多轮对话，以及来电策略。

目前支持的 Provider：

  • 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 远程）

语音通话插件运行在 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: "...",
          },

          telnyx: {
            apiKey: "...",
            connectionId: "...",
            // Telnyx webhook 公钥，来自 Telnyx Mission Control Portal
            // （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,
            streamPath: "/voice/stream",
            preStartTimeoutMs: 5000,
            maxPendingConnections: 32,
            maxPendingConnectionsPerIp: 4,
            maxConnections: 128,
          },
        },
      },
    },
  },
}

说明：

  • Twilio/Telnyx 需要一个公网可达的 webhook URL。
  • Plivo 需要一个公网可达的 webhook URL。
  • mock 是本地开发 provider（不发起网络请求）。
  • Telnyx 需要 telnyx.publicKey（或 TELNYX_PUBLIC_KEY），除非 skipSignatureVerification 为 true。
  • skipSignatureVerification 仅限本地测试使用。
  • 使用 ngrok 免费版时，将 publicUrl 设为 ngrok 的确切 URL；签名验证始终强制执行。
  • tunnel.allowNgrokFreeTierLoopbackBypass: true 允许 Twilio webhook 在签名无效时通过，仅当 tunnel.provider="ngrok" 且 serve.bind 为回环地址（ngrok 本地 agent）。仅限本地开发使用。
  • ngrok 免费版 URL 可能变化或出现中间页；如果 publicUrl 漂移，Twilio 签名会失败。生产环境建议使用稳定域名或 Tailscale funnel。
  • 流式传输安全默认值：
    • streaming.preStartTimeoutMs 关闭未发送有效 start 帧的 socket。
    • streaming.maxPendingConnections 限制未认证的 pre-start socket 总数。
    • streaming.maxPendingConnectionsPerIp 限制每个来源 IP 的未认证 pre-start socket。
    • streaming.maxConnections 限制打开的媒体流 socket 总数（pending + active）。

过期通话回收

使用 staleCallReaperSeconds 来结束未收到终止 webhook 的通话（例如从未完成的通知模式通话）。默认为 0（禁用）。

推荐范围：

  • 生产环境： 通知类流程 120–300 秒。
  • 该值应大于 maxDurationSeconds，让正常通话能完成。一个好的起点是 maxDurationSeconds + 30–60 秒。

示例：

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

Webhook 安全

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

webhookSecurity.allowedHosts 白名单来自转发头的主机名。

webhookSecurity.trustForwardingHeaders 无需白名单即信任转发头。

webhookSecurity.trustedProxyIPs 仅在请求来源 IP 匹配列表时信任转发头。

Twilio 和 Plivo 启用了 webhook 重放保护。重放的有效 webhook 请求会被确认但跳过副作用处理。

Twilio 对话轮次在 <Gather> 回调中包含每轮 token，因此过期/重放的语音回调无法满足更新的待处理转写轮次。

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

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

通话中的 TTS

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

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

说明：

  • Edge TTS 在语音通话中被忽略（电话音频需要 PCM；Edge 输出不可靠）。
  • 启用 Twilio 媒体流时使用核心 TTS；否则通话回退到 Provider 原生语音。

更多示例

仅使用核心 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",
            },
          },
        },
      },
    },
  },
}

来电

来电策略默认为 disabled。要启用来电：

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

inboundPolicy: "allowlist" 是一种低保障的来电显示过滤。插件会标准化 Provider 提供的 From 值并与 allowFrom 比较。Webhook 验证确保 Provider 投递和 payload 完整性，但不能证明 PSTN/VoIP 来电号码的所有权。将 allowFrom 视为来电显示过滤，而非强身份验证。

自动响应使用 agent 系统。可通过以下参数调整：

  • 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

Agent 工具

工具名：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）
arrow_back
上一页
Community
下一页
Zalouser
arrow_forward