語音通話（外掛）

透過外掛為 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 Mission Control Portal 的 webhook 公鑰
            // （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 允許在 tunnel.provider="ngrok" 且 serve.bind 為 loopback（ngrok 本機 agent）時，接受簽章無效的 Twilio webhook。僅限本機開發使用。
• ngrok 免費方案的 URL 可能變更或加入插頁行為；如果 publicUrl 偏移，Twilio 簽章會失敗。正式環境建議使用穩定網域或 Tailscale funnel。
• 串流安全性預設值：
  • streaming.preStartTimeoutMs 關閉從未傳送有效 start frame 的 socket。
  • streaming.maxPendingConnections 限制總未驗證的 pre-start socket 數。
  • streaming.maxPendingConnectionsPerIp 限制每個來源 IP 的未驗證 pre-start socket 數。
  • streaming.maxConnections 限制總開啟的媒體串流 socket 數（pending + active）。

過期通話回收器

使用 staleCallReaperSeconds 結束從未收到終端 webhook 的通話（例如 notify 模式中未完成的通話）。預設為 0（停用）。

建議範圍：

• 正式環境： notify 風格流程使用 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 對話回合包含每回合 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 附帶對應的技能文件。

Gateway RPC

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