語音通話外掛

透過外掛為 OpenClaw 提供語音通話：撥出通知、多輪 對話、全雙工即時語音、串流轉錄，以及 具允許清單政策的來電。

供應商： mock（開發用，無網路）、plivo（語音 API + XML 轉接 + GetInput 語音）、telnyx（Call Control v2）、twilio（可程式化語音 + 媒體串流）。

快速開始

openclaw plugins install @openclaw/voice-call

PLUGIN_SRC=./path/to/local/voice-call-pluginopenclaw plugins install "$PLUGIN_SRC"cd "$PLUGIN_SRC" && pnpm install

openclaw voicecall setupopenclaw voicecall setup --json

openclaw voicecall smokeopenclaw voicecall smoke --to "+15555550123"

openclaw voicecall smoke --to "+15555550123" --yes

設定

如果 enabled: true，但所選供應商缺少認證資訊，閘道 啟動時會記錄設定未完成警告及缺少的鍵，並略過 啟動執行階段。命令、RPC 呼叫和代理程式工具在使用時仍會傳回 確切缺少的設定。

{  plugins: {    entries: {      "voice-call": {        enabled: true,        config: {          provider: "twilio", // 或 "telnyx" | "plivo" | "mock"          fromNumber: "+15550001234", // Twilio 也可使用 TWILIO_FROM_NUMBER          toNumber: "+15550005678",          sessionScope: "per-phone", // per-phone | per-call          numbers: {            "+15550009999": {              inboundGreeting: "Silver Fox Cards，請問有什麼可以協助你的？",              responseSystemPrompt: "你是一位言簡意賅的棒球卡專家。",              tts: {                providers: {                  openai: { speakerVoice: "alloy" },                },              },            },          },           twilio: {            accountSid: "ACxxxxxxxx",            authToken: "...",            // region: "ie1", // 選用：us1 | ie1 | au1；預設為 us1          },          telnyx: {            apiKey: "...",            connectionId: "...",            // 來自 Mission Control Portal 的 Telnyx 網路鉤子公開金鑰            //（Base64；也可透過 TELNYX_PUBLIC_KEY 設定）。            publicKey: "...",          },          plivo: {            authId: "MAxxxxxxxxxxxxxxxxxxxx",            authToken: "...",          },           // 網路鉤子伺服器          serve: {            port: 3334,            path: "/voice/webhook",          },           // 網路鉤子安全性（建議用於通道／Proxy）          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 /* 僅限 Twilio；請參閱串流轉錄 */ },          realtime: { enabled: false /* 請參閱即時語音對話 */ },        },      },    },  },}

設定參考

上方未顯示的 plugins.entries.voice-call.config 頂層鍵：

Twilio 預設使用其 US1 REST 端點。若要在支援的 非美國區域處理通話，請將 twilio.region 設為 ie1 或 au1，並使用來自 該區域的認證資訊。請參閱 Twilio 的非美國 REST API 指南。

工作階段範圍

語音通話預設使用 sessionScope: "per-phone"，因此同一位來電者 重複來電時會保留對話記憶。當每次電信商通話都應以全新內容 開始時，請設定 sessionScope: "per-call"；例如接待、預約、 IVR 或 Google Meet 橋接流程，其中相同電話號碼可能 代表不同會議。

語音通話會將產生的工作階段鍵儲存在已設定的代理程式命名空間下 （agent:<agentId>:voice:*）。原始的明確整合鍵會解析至 相同命名空間：標準 agent:<configuredAgentId>:* 鍵會保留該 擁有者，並遵循核心 session.mainKey/全域範圍別名；外部或 格式錯誤的 agent:* 輸入會在已設定的代理程式下，作為不透明鍵限定範圍； global 和 unknown 仍為全域哨兵值。

即時語音對話

realtime 會為即時通話音訊選取全雙工即時語音供應商。 它與 streaming 分開，後者只會將音訊轉送至即時 轉錄供應商。

目前的執行階段行為：

• realtime.enabled 支援 Twilio 和 Telnyx。
• realtime.provider 為選用設定。若未設定，語音通話會使用第一個已註冊的即時語音提供者。
• 內建的即時語音提供者：Google Gemini Live（google）和 OpenAI（openai），由各自的提供者外掛註冊。
• 由提供者擁有的原始設定位於 realtime.providers.<providerId> 下。
• 語音通話預設公開共用的 openclaw_agent_consult 即時工具。當來電者要求更深入的推理、目前資訊或一般 OpenClaw 工具時，即時模型可以呼叫該工具。
• realtime.consultPolicy 可選擇性加入指引，說明即時模型應在何時呼叫 openclaw_agent_consult。
• realtime.agentContext.enabled 預設關閉。啟用後，語音通話會在工作階段設定時，將有長度限制的代理程式身分與所選工作區檔案摘要注入即時提供者指令。
• realtime.fastContext.enabled 預設關閉。啟用後，語音通話會先在已建立索引的記憶體／工作階段脈絡中搜尋諮詢問題，並在 realtime.fastContext.timeoutMs 範圍內將這些片段傳回即時模型；只有在 realtime.fastContext.fallbackToConsult 為 true 時，才會改用完整的諮詢代理程式。
• 如果 realtime.provider 指向未註冊的提供者，或完全沒有註冊任何即時語音提供者，語音通話會記錄警告並略過即時媒體，而不會導致整個外掛失敗。
• 當 realtime.enabled 為 true 時，inboundPolicy 不得為 "disabled"；validateProviderConfig 會拒絕該組合。
• 諮詢工作階段金鑰會在可用時重複使用已儲存的通話工作階段，否則改用設定的 sessionScope（預設為 per-phone，隔離通話則為 per-call）。

工具政策

realtime.toolPolicy 控制諮詢執行：

realtime.consultPolicy 僅控制即時模型指令：

代理程式語音脈絡

如果希望語音橋接聽起來像設定的 OpenClaw 代理程式， 但不想讓一般對話輪次承擔完整代理程式諮詢的往返成本，請啟用 realtime.agentContext。 脈絡摘要只會在建立即時工作階段時加入一次， 因此不會增加每輪延遲。對 openclaw_agent_consult 的呼叫仍會執行完整的 OpenClaw 代理程式，並應用於工具作業、目前資訊、記憶查詢或工作區狀態。

{  plugins: {    entries: {      "voice-call": {        config: {          agentId: "main",          realtime: {            enabled: true,            provider: "google",            toolPolicy: "safe-read-only",            consultPolicy: "substantive",            agentContext: {              enabled: true,              maxChars: 6000,              includeIdentity: true,              includeWorkspaceFiles: true,              files: ["SOUL.md", "IDENTITY.md", "USER.md"],            },          },        },      },    },  },}

即時提供者範例

{  plugins: {    entries: {      "voice-call": {        config: {          provider: "twilio",          inboundPolicy: "allowlist",          allowFrom: ["+15550005678"],          realtime: {            enabled: true,            provider: "google",            instructions: "簡短說明。在使用更深入的工具前，先呼叫 openclaw_agent_consult。",            toolPolicy: "safe-read-only",            consultPolicy: "substantive",            consultThinkingLevel: "low",            consultFastMode: true,            agentContext: { enabled: true },            providers: {              google: {                apiKey: "${GEMINI_API_KEY}",                model: "gemini-3.1-flash-live-preview",                speakerVoice: "Kore",                silenceDurationMs: 500,                startSensitivity: "high",              },            },          },        },      },    },  },}

{  plugins: {    entries: {      "voice-call": {        config: {          realtime: {            enabled: true,            provider: "openai",            providers: {              openai: { apiKey: "${OPENAI_API_KEY}" },            },          },        },      },    },  },}

如需提供者專屬的即時語音選項，請參閱 Google 提供者和 OpenAI 提供者。

串流轉錄

streaming 將 Twilio Media Streams 連接至即時轉錄提供者。 傳統串流路徑需要 provider: "twilio"；使用 Telnyx、Plivo 或模擬提供者的設定會遭到拒絕。Telnyx 即時音訊則使用 另行驗證身分的 realtime.enabled 路徑。

目前的執行階段行為：

• streaming.provider 為選用設定。若未設定，語音通話會使用第一個已註冊的即時轉錄提供者。
• 內建的即時轉錄提供者：Deepgram（deepgram）、ElevenLabs（elevenlabs）、Mistral（mistral）、OpenAI（openai）和 xAI（xai），由各自的提供者外掛註冊。
• 由提供者擁有的原始設定位於 streaming.providers.<providerId> 下。
• Twilio 傳送已接受的串流 start 訊息後，語音通話會立即註冊串流，在提供者連線期間透過轉錄提供者將傳入媒體排入佇列，並僅在即時轉錄就緒後開始初始問候語。
• 如果 streaming.provider 指向未註冊的提供者，或沒有註冊任何提供者，語音通話會記錄警告並略過媒體串流，而不會導致整個外掛失敗。

串流提供者範例

{  plugins: {    entries: {      "voice-call": {        config: {          streaming: {            enabled: true,            provider: "openai",            streamPath: "/voice/stream",            providers: {              openai: {                apiKey: "sk-...", // 若已設定 OPENAI_API_KEY，則為選用                model: "gpt-4o-transcribe",                silenceDurationMs: 800,                vadThreshold: 0.5,              },            },          },        },      },    },  },}

{  plugins: {    entries: {      "voice-call": {        config: {          streaming: {            enabled: true,            provider: "xai",            streamPath: "/voice/stream",            providers: {              xai: {                apiKey: "${XAI_API_KEY}", // 若已設定 XAI_API_KEY，則為選用                endpointingMs: 800,                language: "en",              },            },          },        },      },    },  },}

通話的 TTS

語音通話會使用核心 tts 設定來處理通話中的串流語音。 你可以在外掛設定下使用相同結構覆寫該設定—— 它會與 tts 深度合併。

{  tts: {    provider: "elevenlabs",    providers: {      elevenlabs: {        speakerVoiceId: "pMsXgVXv3BLzUgSXRplE",        modelId: "eleven_multilingual_v2",      },    },  },}

行為說明：

• 外掛設定中的舊版 tts.<provider> 鍵（openai、elevenlabs、microsoft、edge）會由 openclaw doctor --fix 修復；提交的設定應使用 tts.providers.<provider>。
• 啟用 Twilio 媒體串流時會使用核心 TTS；否則通話會改用提供者原生語音。
• 如果 Twilio 媒體串流已在運作，語音通話不會改用 TwiML OPENCLAW_DOCS_MARKER:calloutOpen:U2F5。若在此狀態下無法使用電話 TTS，播放要求會失敗，而不會混用兩條播放路徑。
• 當電話 TTS 改用次要提供者時，語音通話會記錄包含提供者鏈（from、to、attempts）的警告，以便偵錯。
• 當 Twilio 插話或串流終止清除待處理的 TTS 佇列時，已排入佇列的播放要求會完成結算，而不會讓等待播放完成的來電者持續卡住。

TTS 範例

{tts: {provider: "openai",providers: {openai: { speakerVoice: "alloy" },},},}

{plugins: {entries: {"voice-call": {  config: {    tts: {      provider: "elevenlabs",      providers: {        elevenlabs: {          apiKey: "elevenlabs_key",          speakerVoiceId: "pMsXgVXv3BLzUgSXRplE",          modelId: "eleven_multilingual_v2",        },      },    },  },},},},}

{plugins: {entries: {"voice-call": {  config: {    tts: {      providers: {        openai: {          model: "gpt-4o-mini-tts",          speakerVoice: "marin",        },      },    },  },},},},}

來電

來電政策預設為 disabled。若要啟用來電，請設定：

{inboundPolicy: "allowlist",allowFrom: ["+15550001234"],inboundGreeting: "你好！有什麼可以幫你的嗎？",}

自動回覆使用代理程式系統。可透過 responseModel、 responseSystemPrompt 和 responseTimeoutMs 調整。

依號碼路由

當單一 Voice Call 外掛接收多個電話號碼的來電，且每個號碼應如不同線路般運作時， 請使用 numbers。例如，其中一個號碼可以使用輕鬆風格的個人助理， 另一個號碼則使用商務角色、不同的回覆代理程式，以及不同的 TTS 語音。

路由會根據供應商提供的受撥 To 號碼選取。鍵必須是 E.164 號碼。來電時，Voice Call 會解析一次相符的路由， 將相符路由儲存於通話記錄中，並針對問候語、傳統自動回覆路徑、即時 諮詢路徑及 TTS 播放重複使用該有效設定。若沒有相符路由，則使用全域 Voice Call 設定。撥出電話不使用 numbers；發起通話時，請明確傳入撥出 目標、訊息和工作階段。

路由覆寫目前支援：

• inboundGreeting
• tts
• agentId
• responseModel
• responseSystemPrompt
• responseTimeoutMs

tts 路由值會深層合併至全域 Voice Call tts 設定之上，因此 通常只需覆寫供應商語音：

{inboundGreeting: "你好，這裡是總機。",responseSystemPrompt: "你是預設的語音助理。",tts: {  provider: "openai",  providers: {    openai: { speakerVoice: "coral" },  },},numbers: {  "+15550001111": {    inboundGreeting: "Silver Fox Cards，你好，有什麼可以幫你的嗎？",    responseSystemPrompt: "你是一位言簡意賅的棒球卡專家。",    tts: {      providers: {        openai: { speakerVoice: "alloy" },      },    },  },},}

語音輸出合約

針對自動回覆，Voice Call 會在系統提示詞附加嚴格的語音輸出合約， 要求回覆 {"spoken":"..."} JSON。Voice Call 會以防禦性方式 擷取語音文字：

• 忽略標記為推理／錯誤內容的酬載。
• 剖析直接 JSON、圍欄 JSON 或行內 "spoken" 鍵。
• 退回使用純文字，並移除可能是規劃／中繼內容的前導段落。

如此可讓語音播放聚焦於提供給來電者的文字，並避免將 規劃文字洩漏至音訊中。

對話啟動行為

對於撥出的 conversation 通話，第一則訊息的處理會與即時 播放狀態連動：

• 僅在初始問候語正在播放時，才會抑制插話佇列清除及自動回覆。
• 若初始播放失敗，通話會返回 listening，且初始訊息會保留在佇列中以供重試。
• Twilio 串流的初始播放會在串流連線時立即開始，不會額外延遲。
• 插話會中止目前播放，並清除已排入佇列但尚未播放的 Twilio TTS 項目。已清除的項目會以已略過狀態完成，因此後續回覆邏輯可繼續執行，無須等待永遠不會播放的音訊。
• 即時語音對話會使用即時串流本身的開場輪次。Voice Call 不會針對該初始訊息發送舊式 OPENCLAW_DOCS_MARKER:calloutOpen:U2F5 TwiML 更新，因此撥出的 <Connect><Stream> 工作階段會維持連線。

Twilio 串流中斷寬限期

當 Twilio 媒體串流中斷時，Voice Call 會等待 2000 ms，再 自動結束通話：

• 若串流在此期間重新連線，將取消自動結束。
• 若寬限期後仍沒有串流重新註冊，則會結束通話，以免通話卡在啟用狀態。

過期通話清理器

使用 staleCallReaperSeconds（預設為 120）結束從未接聽且從未 進入即時對話狀態的通話，例如供應商從未傳送終止網路鉤子的通知模式 通話。將其設為 0 可停用。

清理器每 30 秒執行一次，且只會結束沒有 answeredAt 時間戳記，並且尚未處於終止或即時 （speaking/listening）狀態的通話，因此已接聽的對話絕不會被此計時器清理； maxDurationSeconds（預設為 300）是另一項上限， 用於結束持續時間過長的已接聽通話。

對於電信業者可能較慢傳送響鈴／接聽網路鉤子的通知型流程， 請將 staleCallReaperSeconds 提高至預設值以上，以免較慢但正常的 通話遭到提早清理；120-300 秒是合理的正式環境 範圍。

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

網路鉤子安全性

當閘道前方設有 Proxy 或通道時，外掛會重建 用於簽章驗證的公開 URL。下列選項控制信任哪些 轉送標頭：

其他防護措施：

• Twilio、Telnyx 和 Plivo 已啟用網路鉤子重放防護。重放的有效網路鉤子請求會獲得確認，但會略過其副作用。
• Twilio 對話輪次在 <Gather> 回呼中包含每輪權杖，因此過期／重放的語音回呼無法滿足較新的待處理轉錄輪次。
• 若缺少供應商要求的簽章標頭，未經驗證的網路鉤子請求會在讀取本文前遭拒絕。
• voice-call 網路鉤子會在簽章驗證前，使用共用的預先驗證本文讀取設定檔（本文上限 64 KB、讀取逾時 5 秒），以及每個鍵的執行中數量上限（每個鍵預設最多 8 個並行請求）。

使用固定公開主機的範例：

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

命令列介面

openclaw voicecall call --to "+15555550123" --message "來自 OpenClaw 的問候"openclaw voicecall start --to "+15555550123"   # call 的別名openclaw voicecall continue --call-id <id> --message "有任何問題嗎？"openclaw voicecall speak --call-id <id> --message "請稍候"openclaw voicecall dtmf --call-id <id> --digits "ww123456#"openclaw voicecall end --call-id <id>openclaw voicecall status --call-id <id>openclaw voicecall tailopenclaw voicecall latency                      # 從日誌彙整輪次延遲openclaw voicecall expose --mode funnel

當閘道已在執行時，操作型 voicecall 命令會 委派給閘道所擁有的 voice-call 執行階段，讓命令列介面不會繫結 第二個網路鉤子伺服器。若無法連線至任何閘道，命令會退回使用 獨立的命令列介面執行階段。

latency 會從預設 voice-call 儲存路徑讀取 calls.jsonl。使用 --file <path> 可指定其他日誌，使用 --last <n> 可將 分析限制為最後 N 筆記錄（預設為 200）。輸出包含輪次延遲及聆聽等待時間的 最小值／最大值／平均值、p50 和 p95。

代理程式工具

工具名稱：voice_call。

voice-call 外掛隨附相符的代理程式 Skill。

閘道 RPC

dtmfSequence 僅能搭配 mode: "conversation" 使用；若通知模式通話需要在連線後 輸入數字，應在通話建立後使用 voicecall.dtmf。

疑難排解

設定無法公開網路鉤子

請在執行閘道的相同環境中執行設定：

openclaw voicecall setupopenclaw voicecall setup --json

對於 twilio、telnyx 和 plivo，webhook-exposure 必須為綠色。即使已設定 publicUrl，若它指向本機或私人網路空間，仍會失敗， 因為電信業者無法回呼這些位址。請勿將 localhost、127.0.0.1、0.0.0.0、10.x、172.16.x-172.31.x、 192.168.x、169.254.x、fc00::/7、fd00::/8 或其他電信業者級 NAT 範圍用作 publicUrl。

Twilio 通知模式的撥出電話會直接在建立通話的要求中傳送初始 OPENCLAW_DOCS_MARKER:calloutOpen:U2F5 TwiML， 因此第一則語音訊息不依賴 Twilio 擷取網路鉤子 TwiML。狀態 回呼、對話通話、連線前 DTMF、即時串流及 連線後通話控制仍需要公開網路鉤子。

請使用一種公開存取方式：

{plugins: {entries: {"voice-call": {  config: {    publicUrl: "https://voice.example.com/voice/webhook",    // 或    tunnel: { provider: "ngrok" },    // 或    tailscale: { mode: "funnel", path: "/voice/webhook" },  },},},},}

變更設定後，重新啟動或重新載入閘道，然後執行：

openclaw voicecall setupopenclaw voicecall smoke

除非傳入 --yes，否則 voicecall smoke 僅會進行試執行。

提供者認證資訊失敗

檢查所選的提供者及必要的認證資訊欄位：

• Twilio：twilio.accountSid、twilio.authToken 和 fromNumber，或 TWILIO_ACCOUNT_SID、TWILIO_AUTH_TOKEN 和 TWILIO_FROM_NUMBER。
• Telnyx：telnyx.apiKey、telnyx.connectionId、telnyx.publicKey 和 fromNumber，或 TELNYX_API_KEY、TELNYX_CONNECTION_ID 和 TELNYX_PUBLIC_KEY。
• Plivo：plivo.authId、plivo.authToken 和 fromNumber，或 PLIVO_AUTH_ID 和 PLIVO_AUTH_TOKEN。

認證資訊必須存在於閘道主機上。在閘道重新啟動或重新載入其 環境之前，編輯本機 shell 設定檔不會影響已在執行中的閘道。

通話已開始，但未收到提供者的網路鉤子

確認提供者主控台指向確切的公開網路鉤子 URL：

https://voice.example.com/voice/webhook

接著檢查執行階段狀態：

openclaw voicecall status --call-id <id>openclaw voicecall tailopenclaw logs --follow

常見原因：

• publicUrl 指向的路徑與 serve.path 不同。
• 閘道啟動後，通道 URL 發生變更。
• Proxy 轉送要求，但移除或重寫了主機／通訊協定標頭。
• 防火牆或 DNS 將公開主機名稱路由至閘道以外的位置。
• 重新啟動閘道時未啟用 Voice Call 外掛。

當閘道前方有反向 Proxy 或通道時，請將 webhookSecurity.allowedHosts 設為公開主機名稱，或針對已知的 Proxy 位址使用 webhookSecurity.trustedProxyIPs。僅在 Proxy 邊界 由你控制時，才使用 webhookSecurity.trustForwardingHeaders。

簽章驗證失敗

提供者簽章會根據 OpenClaw 從傳入要求重建的公開 URL 進行檢查。 若簽章驗證失敗：

• 確認提供者的網路鉤子 URL 與 publicUrl 完全相符，包括通訊協定、主機和路徑。
• 對於 ngrok 免費方案 URL，請在通道主機名稱變更時更新 publicUrl。
• 確保 Proxy 保留原始主機與通訊協定標頭，或設定 webhookSecurity.allowedHosts。
• 請勿在本機測試以外的環境啟用 skipSignatureVerification。

Google Meet 的 Twilio 加入失敗

Google Meet 使用此外掛透過 Twilio 撥入加入會議。請先驗證 Voice Call：

openclaw voicecall setupopenclaw voicecall smoke --to "+15555550123"

接著明確驗證 Google Meet 傳輸：

openclaw googlemeet setup --transport twilio

若 Voice Call 顯示綠色，但 Meet 參與者始終未加入，請檢查 Meet 撥入號碼、PIN 和 --dtmf-sequence。電話通話可能正常， 但會議仍可能拒絕或忽略不正確的 DTMF 序列。

Google Meet 會透過 voicecall.start 啟動 Twilio 電話端， 並附帶連線前 DTMF 序列。由 PIN 衍生的序列會將 Google Meet 外掛的 voiceCall.dtmfDelayMs（預設為 12000 ms）納入為開頭的 Twilio 等待數字，因為 Meet 撥入提示可能延遲出現。接著，Voice Call 會在要求開場問候語之前，重新導向回即時處理。

使用 openclaw logs --follow 查看即時階段追蹤。正常的 Twilio Meet 加入流程會依下列順序記錄：

• Google Meet 將 Twilio 加入作業委派給 Voice Call。
• Voice Call 儲存連線前 DTMF TwiML。
• 初始 Twilio TwiML 會在即時處理前被取用並提供。
• Voice Call 為 Twilio 通話提供即時 TwiML。
• Google Meet 會在 DTMF 後延遲結束後，使用 voicecall.speak 要求播放開場語音。

openclaw voicecall tail 仍會顯示已保存的通話記錄；這對於 通話狀態和逐字稿很有用，但並非每次網路鉤子／即時轉換 都會顯示在其中。

即時通話沒有語音

確認只啟用一種音訊模式：realtime.enabled 和 streaming.enabled 不可同時為 true。

對於即時 Twilio／Telnyx 通話，也請確認：

• 已載入並註冊即時提供者外掛。
• realtime.provider 未設定，或指定了已註冊的提供者。
• 閘道程序可使用提供者 API 金鑰。
• openclaw logs --follow 顯示已提供即時 TwiML、已啟動即時橋接器，且初始問候語已排入佇列。

相關內容

• 交談模式
• 文字轉語音
• 語音喚醒