Plugin cuộc gọi thoại

Cuộc gọi thoại cho OpenClaw thông qua một plugin: thông báo gọi đi, hội thoại nhiều lượt, thoại thời gian thực song công toàn phần, phiên âm trực tuyến và cuộc gọi đến với các chính sách danh sách cho phép.

Nhà cung cấp: mock (phát triển, không dùng mạng), plivo (Voice API + chuyển tiếp XML + nhận dạng giọng nói GetInput), telnyx (Call Control v2), twilio (Programmable Voice + Media Streams).

Bắt đầu nhanh

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

Cấu hình

Nếu enabled: true nhưng nhà cung cấp đã chọn thiếu thông tin xác thực, khi Gateway khởi động, nhật ký sẽ ghi cảnh báo thiết lập chưa hoàn tất kèm các khóa bị thiếu và bỏ qua việc khởi động môi trường chạy. Khi được sử dụng, các lệnh, lệnh gọi RPC và công cụ tác nhân vẫn trả về chính xác cấu hình còn thiếu.

{  plugins: {    entries: {      "voice-call": {        enabled: true,        config: {          provider: "twilio", // hoặc "telnyx" | "plivo" | "mock"          fromNumber: "+15550001234", // hoặc TWILIO_FROM_NUMBER cho Twilio          toNumber: "+15550005678",          sessionScope: "per-phone", // theo số điện thoại | theo cuộc gọi          numbers: {            "+15550009999": {              inboundGreeting: "Silver Fox Cards, tôi có thể giúp gì cho bạn?",              responseSystemPrompt: "Bạn là chuyên gia ngắn gọn về thẻ bóng chày.",              tts: {                providers: {                  openai: { speakerVoice: "alloy" },                },              },            },          },           twilio: {            accountSid: "ACxxxxxxxx",            authToken: "...",            // khu vực: "ie1", // tùy chọn: us1 | ie1 | au1; mặc định là us1          },          telnyx: {            apiKey: "...",            connectionId: "...",            // Khóa công khai webhook Telnyx từ Mission Control Portal            // (Base64; cũng có thể đặt qua TELNYX_PUBLIC_KEY).            publicKey: "...",          },          plivo: {            authId: "MAxxxxxxxxxxxxxxxxxxxx",            authToken: "...",          },           // Máy chủ webhook          serve: {            port: 3334,            path: "/voice/webhook",          },           // Bảo mật webhook (khuyến nghị cho đường hầm/proxy)          webhookSecurity: {            allowedHosts: ["voice.example.com"],            trustedProxyIPs: ["100.64.0.1"],          },           // Công khai khả năng truy cập (chọn một)          // publicUrl: "https://example.ngrok.app/voice/webhook",          // tunnel: { provider: "ngrok" },          // tailscale: { mode: "funnel", path: "/voice/webhook" },           outbound: {            defaultMode: "notify", // thông báo | hội thoại          },           streaming: { enabled: true /* Chỉ Twilio; xem Phiên âm trực tuyến */ },          realtime: { enabled: false /* xem Hội thoại thoại thời gian thực */ },        },      },    },  },}

Tham chiếu cấu hình

Các khóa cấp cao nhất trong plugins.entries.voice-call.config không được hiển thị ở trên:

Twilio mặc định sử dụng điểm cuối REST US1. Để xử lý cuộc gọi trong một Region ngoài Hoa Kỳ được hỗ trợ, hãy đặt twilio.region thành ie1 hoặc au1 và sử dụng thông tin xác thực từ Region đó. Xem hướng dẫn API REST ngoài Hoa Kỳ của Twilio.

Phạm vi phiên

Theo mặc định, Voice Call sử dụng sessionScope: "per-phone" để các cuộc gọi lặp lại từ cùng một người gọi duy trì bộ nhớ hội thoại. Đặt sessionScope: "per-call" khi mỗi cuộc gọi của nhà mạng cần bắt đầu với ngữ cảnh mới, chẳng hạn như các luồng lễ tân, đặt chỗ, IVR hoặc cầu nối Google Meet, trong đó cùng một số điện thoại có thể đại diện cho các cuộc họp khác nhau.

Voice Call lưu các khóa phiên được tạo trong không gian tên tác nhân đã cấu hình (agent:<agentId>:voice:*). Các khóa tích hợp tường minh thô được phân giải vào cùng không gian tên: khóa agent:<configuredAgentId>:* chuẩn sẽ giữ nguyên chủ sở hữu đó và tuân theo bí danh session.mainKey/phạm vi toàn cục của lõi; đầu vào agent:* ngoại lai hoặc sai định dạng được giới hạn phạm vi như một khóa bất định trong tác nhân đã cấu hình; global và unknown vẫn là các giá trị canh gác toàn cục.

Hội thoại thoại thời gian thực

realtime chọn một nhà cung cấp thoại thời gian thực song công toàn phần cho âm thanh cuộc gọi trực tiếp. Nó tách biệt với streaming, vốn chỉ chuyển tiếp âm thanh đến các nhà cung cấp phiên âm thời gian thực.

Hành vi hiện tại của môi trường chạy:

• realtime.enabled được hỗ trợ cho Twilio và Telnyx.
• realtime.provider là tùy chọn. Nếu không được đặt, Voice Call sử dụng nhà cung cấp giọng nói thời gian thực được đăng ký đầu tiên.
• Các nhà cung cấp giọng nói thời gian thực đi kèm: Google Gemini Live (google) và OpenAI (openai), được đăng ký bởi các plugin nhà cung cấp tương ứng.
• Cấu hình thô do nhà cung cấp sở hữu nằm trong realtime.providers.<providerId>.
• Theo mặc định, Voice Call cung cấp công cụ thời gian thực dùng chung openclaw_agent_consult. Mô hình thời gian thực có thể gọi công cụ này khi người gọi yêu cầu suy luận sâu hơn, thông tin hiện tại hoặc các công cụ OpenClaw thông thường.
• realtime.consultPolicy có thể tùy chọn thêm hướng dẫn về thời điểm mô hình thời gian thực nên gọi openclaw_agent_consult.
• realtime.agentContext.enabled mặc định bị tắt. Khi được bật, Voice Call đưa danh tính agent có giới hạn và một tập tin không gian làm việc đã chọn vào hướng dẫn dành cho nhà cung cấp thời gian thực khi thiết lập phiên.
• realtime.fastContext.enabled mặc định bị tắt. Khi được bật, trước tiên Voice Call tìm kiếm câu hỏi tư vấn trong ngữ cảnh bộ nhớ/phiên đã lập chỉ mục và trả về các đoạn trích đó cho mô hình thời gian thực trong phạm vi realtime.fastContext.timeoutMs, rồi chỉ chuyển sang agent tư vấn đầy đủ nếu realtime.fastContext.fallbackToConsult là true.
• Nếu realtime.provider trỏ đến một nhà cung cấp chưa đăng ký hoặc hoàn toàn không có nhà cung cấp giọng nói thời gian thực nào được đăng ký, Voice Call ghi cảnh báo và bỏ qua phương tiện thời gian thực thay vì làm hỏng toàn bộ plugin.
• inboundPolicy không được là "disabled" khi realtime.enabled là true; validateProviderConfig từ chối tổ hợp đó.
• Khóa phiên tư vấn tái sử dụng phiên cuộc gọi đã lưu khi có thể, sau đó chuyển sang sessionScope đã cấu hình (mặc định là per-phone hoặc per-call đối với các cuộc gọi cô lập).

Chính sách công cụ

realtime.toolPolicy kiểm soát lượt chạy tư vấn:

realtime.consultPolicy chỉ kiểm soát hướng dẫn dành cho mô hình thời gian thực:

Ngữ cảnh giọng nói của agent

Bật realtime.agentContext khi cầu nối giọng nói cần có âm điệu giống như agent OpenClaw đã cấu hình mà không phải trả chi phí cho một lượt đi-về tư vấn agent đầy đủ trong các lượt thông thường. Tập ngữ cảnh được thêm một lần khi phiên thời gian thực được tạo, vì vậy không làm tăng độ trễ trên mỗi lượt. Các lệnh gọi đến openclaw_agent_consult vẫn chạy agent OpenClaw đầy đủ và nên được sử dụng cho công việc bằng công cụ, thông tin hiện tại, tra cứu bộ nhớ hoặc trạng thái không gian làm việc.

{  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"],            },          },        },      },    },  },}

Ví dụ về nhà cung cấp thời gian thực

{  plugins: {    entries: {      "voice-call": {        config: {          provider: "twilio",          inboundPolicy: "allowlist",          allowFrom: ["+15550005678"],          realtime: {            enabled: true,            provider: "google",            instructions: "Nói ngắn gọn. Gọi openclaw_agent_consult trước khi sử dụng các công cụ chuyên sâu hơn.",            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}" },            },          },        },      },    },  },}

Xem nhà cung cấp Google và nhà cung cấp OpenAI để biết các tùy chọn giọng nói thời gian thực dành riêng cho từng nhà cung cấp.

Phiên âm trực tuyến

streaming kết nối Twilio Media Streams với một nhà cung cấp phiên âm thời gian thực. Đường dẫn truyền phát cổ điển yêu cầu provider: "twilio"; cấu hình với Telnyx, Plivo hoặc mock sẽ bị từ chối. Âm thanh trực tiếp của Telnyx sử dụng đường dẫn realtime.enabled được xác thực riêng.

Hành vi thời gian chạy hiện tại:

• streaming.provider là tùy chọn. Nếu không được đặt, Voice Call sử dụng nhà cung cấp phiên âm thời gian thực được đăng ký đầu tiên.
• Các nhà cung cấp phiên âm thời gian thực đi kèm: Deepgram (deepgram), ElevenLabs (elevenlabs), Mistral (mistral), OpenAI (openai) và xAI (xai), được đăng ký bởi các plugin nhà cung cấp tương ứng.
• Cấu hình thô do nhà cung cấp sở hữu nằm trong streaming.providers.<providerId>.
• Sau khi Twilio gửi một thông báo start luồng đã được chấp nhận, Voice Call đăng ký luồng ngay lập tức, đưa phương tiện đến vào hàng đợi qua nhà cung cấp phiên âm trong khi nhà cung cấp kết nối và chỉ bắt đầu lời chào ban đầu sau khi phiên âm thời gian thực sẵn sàng.
• Nếu streaming.provider trỏ đến một nhà cung cấp chưa đăng ký hoặc không có nhà cung cấp nào được đăng ký, Voice Call ghi cảnh báo và bỏ qua việc truyền phát phương tiện thay vì làm hỏng toàn bộ plugin.

Ví dụ về nhà cung cấp truyền phát

{  plugins: {    entries: {      "voice-call": {        config: {          streaming: {            enabled: true,            provider: "openai",            streamPath: "/voice/stream",            providers: {              openai: {                apiKey: "sk-...", // tùy chọn nếu OPENAI_API_KEY được đặt                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}", // tùy chọn nếu XAI_API_KEY được đặt                endpointingMs: 800,                language: "en",              },            },          },        },      },    },  },}

TTS cho cuộc gọi

Voice Call sử dụng cấu hình messages.tts cốt lõi để truyền phát giọng nói trong cuộc gọi. Bạn có thể ghi đè cấu hình này trong cấu hình plugin bằng cùng một cấu trúc — cấu hình đó được hợp nhất sâu với messages.tts.

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

Ghi chú về hành vi:

• Các khóa tts.<provider> cũ trong cấu hình plugin (openai, elevenlabs, microsoft, edge) được openclaw doctor --fix sửa chữa; cấu hình đã cam kết nên sử dụng tts.providers.<provider>.
• TTS cốt lõi được sử dụng khi truyền phát phương tiện Twilio được bật; nếu không, cuộc gọi sẽ chuyển sang giọng nói gốc của nhà cung cấp.
• Nếu một luồng phương tiện Twilio đã hoạt động, Voice Call không chuyển sang OPENCLAW_DOCS_MARKER:calloutOpen:U2F5 của TwiML. Nếu TTS điện thoại không khả dụng trong trạng thái đó, yêu cầu phát lại sẽ thất bại thay vì kết hợp hai đường dẫn phát lại.
• Khi TTS điện thoại chuyển sang một nhà cung cấp phụ, Voice Call ghi cảnh báo kèm chuỗi nhà cung cấp (from, to, attempts) để gỡ lỗi.
• Khi thao tác ngắt lời hoặc kết thúc luồng của Twilio xóa hàng đợi TTS đang chờ, các yêu cầu phát lại trong hàng đợi sẽ được hoàn tất thay vì bị treo khiến người gọi phải chờ phát lại hoàn tất.

Ví dụ về TTS

{messages: {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",        },      },    },  },},},},}

Cuộc gọi đến

Chính sách cuộc gọi đến mặc định là disabled. Để bật cuộc gọi đến, hãy đặt:

{inboundPolicy: "allowlist",allowFrom: ["+15550001234"],inboundGreeting: "Xin chào! Tôi có thể giúp gì?",}

Phản hồi tự động sử dụng hệ thống tác nhân. Điều chỉnh bằng responseModel, responseSystemPrompt và responseTimeoutMs.

Định tuyến theo từng số

Sử dụng numbers khi một Plugin Cuộc gọi Thoại nhận cuộc gọi cho nhiều số điện thoại và mỗi số cần hoạt động như một đường dây khác nhau. Ví dụ, một số có thể sử dụng trợ lý cá nhân thân thiện, trong khi số khác sử dụng một vai trò doanh nghiệp, tác nhân phản hồi khác và giọng TTS khác.

Các tuyến được chọn từ số To đã quay do nhà cung cấp cung cấp. Khóa phải là số E.164. Khi có cuộc gọi đến, Cuộc gọi Thoại phân giải tuyến phù hợp một lần, lưu tuyến đã khớp vào bản ghi cuộc gọi và tái sử dụng cấu hình hiệu lực đó cho lời chào, luồng phản hồi tự động cổ điển, luồng tham vấn thời gian thực và phát lại TTS. Nếu không có tuyến nào khớp, cấu hình Cuộc gọi Thoại toàn cục sẽ được sử dụng. Cuộc gọi đi không sử dụng numbers; hãy truyền rõ đích cuộc gọi đi, tin nhắn và phiên khi bắt đầu cuộc gọi.

Các phần ghi đè tuyến hiện được hỗ trợ:

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

Giá trị tuyến tts được hợp nhất sâu lên trên cấu hình tts của Cuộc gọi Thoại toàn cục, vì vậy thông thường bạn chỉ cần ghi đè giọng của nhà cung cấp:

{inboundGreeting: "Xin chào từ đường dây chính.",responseSystemPrompt: "Bạn là trợ lý giọng nói mặc định.",tts: {  provider: "openai",  providers: {    openai: { speakerVoice: "coral" },  },},numbers: {  "+15550001111": {    inboundGreeting: "Silver Fox Cards xin nghe, tôi có thể giúp gì?",    responseSystemPrompt: "Bạn là chuyên gia ngắn gọn về thẻ bóng chày.",    tts: {      providers: {        openai: { speakerVoice: "alloy" },      },    },  },},}

Hợp đồng đầu ra lời nói

Đối với phản hồi tự động, Cuộc gọi Thoại nối thêm một hợp đồng đầu ra lời nói nghiêm ngặt vào lời nhắc hệ thống, yêu cầu phản hồi JSON {"spoken":"..."}. Cuộc gọi Thoại trích xuất văn bản lời nói theo cách phòng vệ:

• Bỏ qua tải dữ liệu được đánh dấu là nội dung suy luận/lỗi.
• Phân tích JSON trực tiếp, JSON có hàng rào hoặc các khóa "spoken" nội dòng.
• Dùng văn bản thuần làm phương án dự phòng và loại bỏ các đoạn mở đầu có khả năng là nội dung lập kế hoạch/siêu thông tin.

Điều này giúp nội dung phát lời nói tập trung vào văn bản dành cho người gọi và tránh làm lộ văn bản lập kế hoạch vào âm thanh.

Hành vi khởi động cuộc hội thoại

Đối với cuộc gọi conversation đi, việc xử lý tin nhắn đầu tiên gắn với trạng thái phát trực tiếp:

• Việc xóa hàng đợi khi người gọi chen lời và phản hồi tự động chỉ bị ngăn khi lời chào ban đầu đang được phát.
• Nếu phát ban đầu thất bại, cuộc gọi trở về listening và tin nhắn ban đầu vẫn nằm trong hàng đợi để thử lại.
• Việc phát ban đầu cho luồng Twilio bắt đầu khi luồng kết nối mà không có độ trễ bổ sung.
• Việc chen lời hủy phát đang hoạt động và xóa các mục TTS Twilio đã xếp hàng nhưng chưa phát. Các mục bị xóa được phân giải là đã bỏ qua, để logic phản hồi tiếp theo có thể tiếp tục mà không phải chờ âm thanh sẽ không bao giờ được phát.
• Cuộc hội thoại giọng nói thời gian thực sử dụng lượt mở đầu riêng của luồng thời gian thực. Cuộc gọi Thoại không đăng bản cập nhật TwiML OPENCLAW_DOCS_MARKER:calloutOpen:U2F5 cũ cho tin nhắn ban đầu đó, vì vậy các phiên <Connect><Stream> đi vẫn được gắn kết.

Thời gian gia hạn khi luồng Twilio ngắt kết nối

Khi một luồng phương tiện Twilio ngắt kết nối, Cuộc gọi Thoại chờ 2000 ms trước khi tự động kết thúc cuộc gọi:

• Nếu luồng kết nối lại trong khoảng thời gian đó, việc tự động kết thúc sẽ bị hủy.
• Nếu không có luồng nào đăng ký lại sau thời gian gia hạn, cuộc gọi sẽ bị kết thúc để ngăn cuộc gọi đang hoạt động bị mắc kẹt.

Trình thu hồi cuộc gọi cũ

Sử dụng staleCallReaperSeconds (mặc định 120) để kết thúc các cuộc gọi không bao giờ được trả lời và không bao giờ đạt trạng thái hội thoại trực tiếp, ví dụ các cuộc gọi ở chế độ thông báo mà nhà cung cấp không bao giờ gửi Webhook kết thúc. Đặt thành 0 để tắt.

Trình thu hồi chạy mỗi 30 giây và chỉ kết thúc các cuộc gọi không có dấu thời gian answeredAt và chưa ở trạng thái kết thúc hoặc trực tiếp (speaking/listening), vì vậy các cuộc hội thoại đã được trả lời sẽ không bao giờ bị trình hẹn giờ này thu hồi; maxDurationSeconds (mặc định 300) là giới hạn riêng để kết thúc các cuộc gọi đã được trả lời nhưng kéo dài quá lâu.

Đối với các luồng kiểu thông báo, nơi nhà mạng có thể chậm gửi Webhook đổ chuông/trả lời, hãy tăng staleCallReaperSeconds cao hơn giá trị mặc định để các cuộc gọi chậm nhưng bình thường không bị thu hồi sớm; 120-300 giây là một khoảng hợp lý cho môi trường sản xuất.

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

Bảo mật Webhook

Khi proxy hoặc đường hầm nằm phía trước Gateway, Plugin tái tạo URL công khai để xác minh chữ ký. Các tùy chọn này kiểm soát những tiêu đề chuyển tiếp nào được tin cậy:

Các biện pháp bảo vệ bổ sung:

• Tính năng bảo vệ chống phát lại Webhook được bật cho Twilio, Telnyx và Plivo. Các yêu cầu Webhook hợp lệ bị phát lại được xác nhận nhưng bỏ qua tác dụng phụ.
• Các lượt hội thoại Twilio bao gồm token theo từng lượt trong lệnh gọi lại <Gather>, vì vậy lệnh gọi lại lời nói cũ/bị phát lại không thể đáp ứng một lượt bản chép lời đang chờ mới hơn.
• Các yêu cầu Webhook chưa xác thực bị từ chối trước khi đọc phần thân nếu thiếu tiêu đề chữ ký bắt buộc của nhà cung cấp.
• Webhook voice-call sử dụng hồ sơ đọc phần thân trước xác thực dùng chung (phần thân tối đa 64 KB, thời gian chờ đọc 5 giây) cùng giới hạn số yêu cầu đang xử lý theo mỗi khóa (mặc định 8 yêu cầu đồng thời cho mỗi khóa) trước khi xác minh chữ ký.

Ví dụ với máy chủ công khai ổn định:

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

CLI

openclaw voicecall call --to "+15555550123" --message "Xin chào từ OpenClaw"openclaw voicecall start --to "+15555550123"   # bí danh của callopenclaw voicecall continue --call-id <id> --message "Có câu hỏi nào không?"openclaw voicecall speak --call-id <id> --message "Vui lòng chờ một chút"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                      # tóm tắt độ trễ lượt từ nhật kýopenclaw voicecall expose --mode funnel

Khi Gateway đang chạy, các lệnh voicecall vận hành ủy quyền cho runtime voice-call do Gateway sở hữu để CLI không liên kết với máy chủ Webhook thứ hai. Nếu không thể truy cập Gateway, các lệnh sẽ dùng runtime CLI độc lập làm phương án dự phòng.

latency đọc calls.jsonl từ đường dẫn lưu trữ voice-call mặc định. Sử dụng --file <path> để trỏ đến nhật ký khác và --last <n> để giới hạn phân tích ở N bản ghi gần nhất (mặc định 200). Đầu ra bao gồm giá trị nhỏ nhất/lớn nhất/trung bình, p50 và p95 cho độ trễ lượt và thời gian chờ nghe.

Công cụ tác nhân

Tên công cụ: voice_call.

Plugin voice-call đi kèm một kỹ năng tác nhân tương ứng.

RPC Gateway

dtmfSequence chỉ hợp lệ với mode: "conversation"; các cuộc gọi ở chế độ thông báo nên sử dụng voicecall.dtmf sau khi cuộc gọi đã tồn tại nếu cần gửi các chữ số sau khi kết nối.

Khắc phục sự cố

Thiết lập không thể công khai Webhook

Chạy thiết lập từ cùng môi trường chạy Gateway:

openclaw voicecall setupopenclaw voicecall setup --json

Đối với twilio, telnyx và plivo, webhook-exposure phải có trạng thái xanh. Một publicUrl đã được cấu hình vẫn không hoạt động khi trỏ đến không gian mạng cục bộ hoặc riêng tư, vì nhà mạng không thể gọi lại vào các địa chỉ đó. Không sử dụng 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 hoặc các dải NAT cấp nhà mạng khác làm publicUrl.

Các cuộc gọi đi ở chế độ thông báo của Twilio gửi trực tiếp TwiML OPENCLAW_DOCS_MARKER:calloutOpen:U2F5 ban đầu trong yêu cầu tạo cuộc gọi, vì vậy thông báo thoại đầu tiên không phụ thuộc vào việc Twilio tìm nạp TwiML của Webhook. Vẫn cần Webhook công khai cho các lệnh gọi lại trạng thái, cuộc gọi hội thoại, DTMF trước khi kết nối, luồng thời gian thực và điều khiển cuộc gọi sau khi kết nối.

Sử dụng một phương thức công khai:

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

Sau khi thay đổi cấu hình, hãy khởi động lại hoặc tải lại Gateway, rồi chạy:

openclaw voicecall setupopenclaw voicecall smoke

voicecall smoke là lần chạy thử trừ khi truyền --yes.

Thông tin xác thực của nhà cung cấp không hợp lệ

Kiểm tra nhà cung cấp đã chọn và các trường thông tin xác thực bắt buộc:

• Twilio: twilio.accountSid, twilio.authToken và fromNumber, hoặc TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN và TWILIO_FROM_NUMBER.
• Telnyx: telnyx.apiKey, telnyx.connectionId, telnyx.publicKey và fromNumber, hoặc TELNYX_API_KEY, TELNYX_CONNECTION_ID và TELNYX_PUBLIC_KEY.
• Plivo: plivo.authId, plivo.authToken và fromNumber, hoặc PLIVO_AUTH_ID và PLIVO_AUTH_TOKEN.

Thông tin xác thực phải tồn tại trên máy chủ Gateway. Việc chỉnh sửa hồ sơ shell cục bộ không ảnh hưởng đến Gateway đang chạy cho đến khi Gateway khởi động lại hoặc tải lại môi trường.

Cuộc gọi bắt đầu nhưng Webhook của nhà cung cấp không đến

Xác nhận bảng điều khiển của nhà cung cấp trỏ đến chính xác URL Webhook công khai:

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

Sau đó kiểm tra trạng thái thời gian chạy:

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

Các nguyên nhân thường gặp:

• publicUrl trỏ đến đường dẫn khác với serve.path.
• URL đường hầm đã thay đổi sau khi Gateway khởi động.
• Proxy chuyển tiếp yêu cầu nhưng loại bỏ hoặc viết lại các tiêu đề máy chủ/giao thức.
• Tường lửa hoặc DNS định tuyến tên máy chủ công khai đến nơi khác thay vì Gateway.
• Gateway đã được khởi động lại mà không bật Plugin Voice Call.

Khi có proxy ngược hoặc đường hầm phía trước Gateway, hãy đặt webhookSecurity.allowedHosts thành tên máy chủ công khai hoặc sử dụng webhookSecurity.trustedProxyIPs cho một địa chỉ proxy đã biết. Chỉ sử dụng webhookSecurity.trustForwardingHeaders khi bạn kiểm soát ranh giới proxy.

Xác minh chữ ký không thành công

Chữ ký của nhà cung cấp được kiểm tra dựa trên URL công khai mà OpenClaw dựng lại từ yêu cầu đến. Nếu chữ ký không hợp lệ:

• Xác nhận URL Webhook của nhà cung cấp khớp chính xác với publicUrl, bao gồm giao thức, máy chủ và đường dẫn.
• Đối với URL ngrok cấp miễn phí, hãy cập nhật publicUrl khi tên máy chủ đường hầm thay đổi.
• Đảm bảo proxy giữ nguyên các tiêu đề máy chủ và giao thức ban đầu hoặc cấu hình webhookSecurity.allowedHosts.
• Không bật skipSignatureVerification bên ngoài môi trường kiểm thử cục bộ.

Không thể tham gia Google Meet qua Twilio

Google Meet sử dụng Plugin này để tham gia bằng số quay vào của Twilio. Trước tiên, hãy xác minh Voice Call:

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

Sau đó xác minh cụ thể phương thức truyền tải Google Meet:

openclaw googlemeet setup --transport twilio

Nếu Voice Call có trạng thái xanh nhưng người tham gia Meet không bao giờ vào được, hãy kiểm tra số quay vào Meet, mã PIN và --dtmf-sequence. Cuộc gọi điện thoại có thể hoạt động bình thường trong khi cuộc họp từ chối hoặc bỏ qua một chuỗi DTMF không chính xác.

Google Meet khởi tạo chặng điện thoại Twilio thông qua voicecall.start với một chuỗi DTMF trước khi kết nối. Các chuỗi được tạo từ mã PIN bao gồm voiceCall.dtmfDelayMs của Plugin Google Meet (mặc định 12000 ms) làm các chữ số chờ Twilio ở đầu, vì lời nhắc quay số vào Meet có thể đến muộn. Sau đó, Voice Call chuyển hướng trở lại xử lý thời gian thực trước khi yêu cầu lời chào mở đầu.

Sử dụng openclaw logs --follow để xem dấu vết giai đoạn trực tiếp. Một lần tham gia Meet qua Twilio bình thường ghi nhật ký theo thứ tự sau:

• Google Meet ủy quyền việc tham gia qua Twilio cho Voice Call.
• Voice Call lưu TwiML DTMF trước khi kết nối.
• TwiML ban đầu của Twilio được sử dụng và phục vụ trước khi xử lý thời gian thực.
• Voice Call phục vụ TwiML thời gian thực cho cuộc gọi Twilio.
• Google Meet yêu cầu lời nói mở đầu bằng voicecall.speak sau khoảng trễ hậu DTMF.

openclaw voicecall tail vẫn hiển thị các bản ghi cuộc gọi được lưu trữ lâu dài; hữu ích cho trạng thái cuộc gọi và bản chép lời, nhưng không phải mọi chuyển tiếp Webhook/thời gian thực đều xuất hiện ở đó.

Cuộc gọi thời gian thực không có tiếng nói

Xác nhận chỉ bật một chế độ âm thanh: realtime.enabled và streaming.enabled không thể đồng thời là true.

Đối với các cuộc gọi Twilio/Telnyx thời gian thực, hãy xác minh thêm:

• Một Plugin nhà cung cấp thời gian thực đã được tải và đăng ký.
• realtime.provider chưa được đặt hoặc chỉ định một nhà cung cấp đã đăng ký.
• Khóa API của nhà cung cấp khả dụng cho tiến trình Gateway.
• openclaw logs --follow hiển thị TwiML thời gian thực đã được phục vụ, cầu nối thời gian thực đã khởi động và lời chào ban đầu đã được đưa vào hàng đợi.

Liên quan

• Chế độ trò chuyện
• Chuyển văn bản thành giọng nói
• Kích hoạt bằng giọng nói