学了个寂寞

Appearance

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 安装（推荐） ​

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", // 或 "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 / Plivo 均需要公网可访问的 webhook URL。
  • mock 是本地开发提供商（无网络请求）。
  • Telnyx 需要 telnyx.publicKey（或 TELNYX_PUBLIC_KEY），除非将 skipSignatureVerification 设为 true。
  • skipSignatureVerification 仅用于本地测试。
  • 使用 ngrok 免费版时，需将 publicUrl 设为具体的 ngrok URL；签名验证始终强制执行。
  • tunnel.allowNgrokFreeTierLoopbackBypass: true 仅在 tunnel.provider="ngrok" 且 serve.bind 为回环地址时，允许无效签名的 Twilio webhook 通过。仅用于本地开发。
  • ngrok 免费版 URL 可能发生变化或出现插页行为；若 publicUrl 偏移，Twilio 签名将验证失败。生产环境推荐使用稳定域名或 Tailscale funnel。
  • 流媒体安全默认值：
    • streaming.preStartTimeoutMs 关闭从未发送有效 start 帧的 socket。
    • streaming.maxPendingConnections 限制未认证的待起 socket 总数。
    • streaming.maxPendingConnectionsPerIp 限制每个源 IP 的未认证待起 socket 数。
    • streaming.maxConnections 限制所有媒体流 socket 总数（待起 + 活跃）。

僵尸通话清理器 ​

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

推荐范围：

  • 生产环境： 通知类流程设置 120–300 秒。
  • 保持该值高于 maxDurationSeconds，让正常通话能顺利结束。推荐起点：maxDurationSeconds + 30–60 秒。

示例：

json5
{
  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> 回调中包含每轮令牌，过期/重放的语音回调无法满足新的待处理文字记录轮次。

当提供商所需签名头部缺失时，未认证的 webhook 请求会在读取正文前被拒绝。

voice-call webhook 使用共享的预认证正文配置（64 KB / 5 秒），以及签名验证前的每 IP 并发限制。

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

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

通话 TTS ​

Voice Call 使用核心 messages.tts 配置进行通话中的流式语音播放。你可以在插件配置下使用相同结构覆盖它——会与 messages.tts 进行深度合并。

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

注意事项：

  • Microsoft 语音不支持语音通话（电话音频需要 PCM；当前 Microsoft 传输层不暴露电话 PCM 输出）。
  • 启用 Twilio 媒体流时使用核心 TTS；否则通话回退到提供商原生语音。
  • 如果 Twilio 媒体流已激活，Voice Call 不会回退到 TwiML <Say>。若该状态下电话 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?",
}

inboundPolicy: "allowlist" 是低保证度的来电显示过滤。插件对提供商提供的 From 值进行规范化，并与 allowFrom 比对。Webhook 验证能认证提供商交付和载荷完整性，但无法证明 PSTN/VoIP 来电号码的所有权。将 allowFrom 视为来电显示过滤，而非强身份认证。

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

  • responseModel
  • responseSystemPrompt
  • responseTimeoutMs

语音输出契约 ​

对于自动回复，Voice Call 会在系统提示后追加严格的语音输出契约：

  • {"spoken":"..."}

Voice Call 随后防御性地提取语音文本：

  • 忽略标记为推理/错误内容的载荷。
  • 解析直接 JSON、围栏 JSON 或内联 "spoken" 键。
  • 回退到纯文本并移除可能的规划/元前导段落。

这使语音播放聚焦于面向来电者的文本，避免将规划文本泄露到音频中。

对话启动行为 ​

对于外拨 conversation 通话，首条消息处理与实时播放状态绑定：

  • 仅在初始问候语正在播放时，才会清除插话队列并抑制自动回复。
  • 如果初始播放失败，通话返回到 listening 状态，初始消息保持队列等待重试。
  • Twilio 流媒体的初始播放在流连接时启动，无额外延迟。

Twilio 流断开宽限期 ​

Twilio 媒体流断开时，Voice Call 会等待 2000ms 再自动结束通话：

  • 若在此窗口内流重新连接，自动结束将被取消。
  • 若宽限期后没有流重新注册，通话将被结束以防止卡死的活跃通话。

CLI 命令 ​

bash
openclaw voicecall call --to "+15555550123" --message "Hello from OpenClaw"
openclaw voicecall start --to "+15555550123"   # call 的别名
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 latency                     # 从日志中汇总轮次延迟
openclaw voicecall expose --mode funnel

latency 命令从默认 voice-call 存储路径读取 calls.jsonl。使用 --file <path> 指定其他日志文件，使用 --last <n> 限制分析最后 N 条记录（默认 200）。输出包含轮次延迟和监听等待时间的 p50/p90/p99。

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）

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策