Voice Call (plugin)

OpenClaw 的语音通话 Plugin。支持呼出通知和多轮对话的呼入策略。

当前支持的服务商：

• twilio（Programmable Voice + Media Streams）
• telnyx（Call Control v2）
• plivo（Voice API + XML transfer + GetInput speech）
• mock（开发模式/无网络）

快速理解：

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

运行位置（本地 vs 远程）

Voice Call Plugin 运行在 Gateway 进程内部。

如果你使用远程 Gateway，需要在运行 Gateway 的机器上安装和配置 Plugin，然后重启 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 仅用于本地测试。
• 如果你使用 ngrok 免费版，需要将 publicUrl 设置为准确的 ngrok URL；签名验证始终会执行。
• tunnel.allowNgrokFreeTierLoopbackBypass: true 允许 Twilio Webhook 使用无效签名，仅当 tunnel.provider="ngrok" 且 serve.bind 是本地回环（ngrok 本地代理）时。仅用于本地开发。
• Ngrok 免费版 URL 可能会变化或添加中间页；如果 publicUrl 漂移，Twilio 签名会失败。生产环境建议使用稳定域名或 Tailscale funnel。

通话的 TTS

Voice Call 使用核心的 messages.tts 配置（OpenAI 或 ElevenLabs）来实现通话中的流式语音。你可以在 Plugin 配置下覆盖它，使用相同的结构 —— 它会与 messages.tts 深度合并。

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

注意事项：

• Edge TTS 在语音通话中会被忽略（电话音频需要 PCM 格式；Edge 输出不可靠）。
• 当 Twilio media streaming 启用时使用核心 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",
            },
          },
        },
      },
    },
  },
}

呼入电话

呼入策略默认为 disabled。要启用呼入电话，设置：

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

自动回复使用 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)