Cuộc gọi thoại cho OpenClaw thông qua một Plugin. Hỗ trợ thông báo đi, hội thoại nhiều lượt, giọng nói realtime song công toàn phần, bản chép lời streaming và cuộc gọi đến với chính sách allowlist. Nhà cung cấp hiện tại:Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
twilio (Programmable Voice + Media Streams),
telnyx (Call Control v2), plivo (Voice API + XML transfer + GetInput
speech), mock (phát triển/không dùng mạng).
Plugin Voice Call chạy bên trong tiến trình Gateway. Nếu bạn dùng
Gateway từ xa, hãy cài đặt và cấu hình Plugin trên máy đang chạy
Gateway, rồi khởi động lại Gateway để tải Plugin.
Bắt đầu nhanh
Install the plugin
- From npm
- From a local folder (dev)
Configure provider and webhook
Đặt cấu hình trong
plugins.entries.voice-call.config (xem
Cấu hình bên dưới để biết đầy đủ cấu trúc). Tối thiểu cần:
provider, thông tin xác thực của nhà cung cấp, fromNumber và một URL Webhook
có thể truy cập công khai.Verify setup
streaming hoặc realtime) đang hoạt động. Dùng
--json cho script.Cấu hình
Nếuenabled: true nhưng nhà cung cấp đã chọn thiếu thông tin xác thực,
Gateway sẽ ghi cảnh báo thiết lập chưa hoàn tất khi khởi động, kèm các khóa bị thiếu và
bỏ qua việc khởi động runtime. Các lệnh, lệnh gọi RPC và công cụ agent vẫn
trả về chính xác cấu hình nhà cung cấp còn thiếu khi được dùng.
Thông tin xác thực voice-call chấp nhận SecretRefs.
plugins.entries.voice-call.config.twilio.authToken và plugins.entries.voice-call.config.tts.providers.*.apiKey được phân giải qua bề mặt SecretRef tiêu chuẩn; xem bề mặt thông tin xác thực SecretRef.Provider exposure and security notes
Provider exposure and security notes
- Twilio, Telnyx và Plivo đều yêu cầu một URL Webhook có thể truy cập công khai.
mocklà nhà cung cấp phát triển cục bộ (không có lệnh gọi mạng).- Telnyx yêu cầu
telnyx.publicKey(hoặcTELNYX_PUBLIC_KEY) trừ khiskipSignatureVerificationlà true. skipSignatureVerificationchỉ dành cho kiểm thử cục bộ.- Trên gói miễn phí của ngrok, đặt
publicUrlthành đúng URL ngrok; xác minh chữ ký luôn được thực thi. tunnel.allowNgrokFreeTierLoopbackBypass: truecho phép Webhook Twilio có chữ ký không hợp lệ chỉ khitunnel.provider="ngrok"vàserve.bindlà loopback (agent cục bộ của ngrok). Chỉ dùng cho phát triển cục bộ.- URL gói miễn phí của ngrok có thể thay đổi hoặc thêm hành vi chuyển tiếp; nếu
publicUrlbị lệch, chữ ký Twilio sẽ thất bại. Sản xuất: ưu tiên một miền ổn định hoặc Tailscale funnel.
Streaming connection caps
Streaming connection caps
streaming.preStartTimeoutMsđóng các socket không bao giờ gửi framestarthợp lệ.streaming.maxPendingConnectionsgiới hạn tổng số socket trước khi start chưa xác thực.streaming.maxPendingConnectionsPerIpgiới hạn socket trước khi start chưa xác thực trên mỗi IP nguồn.streaming.maxConnectionsgiới hạn tổng số socket media stream đang mở (đang chờ + đang hoạt động).
Legacy config migrations
Legacy config migrations
Cấu hình cũ dùng
provider: "log", twilio.from, hoặc các khóa OpenAI
streaming.* cũ sẽ được viết lại bởi openclaw doctor --fix.
Runtime fallback hiện vẫn chấp nhận các khóa voice-call cũ, nhưng
đường dẫn viết lại là openclaw doctor --fix và lớp tương thích này
chỉ là tạm thời.Các khóa streaming được tự động di chuyển:streaming.sttProvider→streaming.providerstreaming.openaiApiKey→streaming.providers.openai.apiKeystreaming.sttModel→streaming.providers.openai.modelstreaming.silenceDurationMs→streaming.providers.openai.silenceDurationMsstreaming.vadThreshold→streaming.providers.openai.vadThreshold
Hội thoại thoại realtime
realtime chọn nhà cung cấp giọng nói realtime 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 chép lời realtime.
Hành vi runtime hiện tại:
realtime.enabledđược hỗ trợ cho Twilio Media Streams.realtime.providerlà tùy chọn. Nếu không đặt, Voice Call dùng nhà cung cấp giọng nói realtime đã đăng ký đầu tiên.- Nhà cung cấp giọng nói realtime đ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>. - Voice Call mặc định cung cấp công cụ realtime dùng chung
openclaw_agent_consult. Mô hình realtime 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ông cụ OpenClaw thông thường. - Nếu
realtime.providertrỏ đến một nhà cung cấp chưa đăng ký, hoặc không có nhà cung cấp giọng nói realtime nào được đăng ký, Voice Call ghi cảnh báo và bỏ qua media realtime thay vì làm toàn bộ Plugin thất bại. - Khóa phiên consult tái sử dụng phiên thoại hiện có khi có sẵn, rồi dự phòng sang số điện thoại người gọi/người nhận để các lần gọi consult tiếp theo giữ ngữ cảnh trong cuộc gọi.
Chính sách công cụ
realtime.toolPolicy kiểm soát lượt chạy consult:
| Chính sách | Hành vi |
|---|---|
safe-read-only | Cung cấp công cụ consult và giới hạn agent thông thường ở read, web_search, web_fetch, x_search, memory_search và memory_get. |
owner | Cung cấp công cụ consult và để agent thông thường dùng chính sách công cụ agent bình thường. |
none | Không cung cấp công cụ consult. realtime.tools tùy chỉnh vẫn được truyền qua cho nhà cung cấp realtime. |
Ví dụ nhà cung cấp realtime
- Google Gemini Live
- OpenAI
Mặc định: khóa API từ
realtime.providers.google.apiKey,
GEMINI_API_KEY, hoặc GOOGLE_GENERATIVE_AI_API_KEY; mô hình
gemini-2.5-flash-native-audio-preview-12-2025; giọng nói Kore.Chép lời streaming
streaming chọn một nhà cung cấp chép lời realtime cho âm thanh cuộc gọi trực tiếp.
Hành vi runtime hiện tại:
streaming.providerlà tùy chọn. Nếu không đặt, Voice Call dùng nhà cung cấp chép lời realtime đã đăng ký đầu tiên.- Nhà cung cấp chép lời realtime đ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>. - Nếu
streaming.providertrỏ đế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 media streaming thay vì làm toàn bộ Plugin thất bại.
Ví dụ nhà cung cấp streaming
- OpenAI
- xAI
Mặc định: khóa API
streaming.providers.openai.apiKey hoặc
OPENAI_API_KEY; mô hình gpt-4o-transcribe; silenceDurationMs: 800;
vadThreshold: 0.5.TTS cho cuộc gọi
Voice Call dùng cấu hình lõimessages.tts cho giọng nói phát trực tuyến
trong cuộc gọi. Bạn có thể ghi đè cấu hình này trong cấu hình plugin với
cùng cấu trúc — cấu hình này được hợp nhất sâu với messages.tts.
- Các khóa
tts.<provider>cũ trong cấu hình plugin (openai,elevenlabs,microsoft,edge) được sửa bởiopenclaw doctor --fix; cấu hình đã commit nên dùngtts.providers.<provider>. - Core TTS được dùng khi bật phát trực tuyến media Twilio; nếu không, cuộc gọi sẽ quay về dùng giọng nói gốc của nhà cung cấp.
- Nếu một stream media Twilio đã hoạt động, Voice Call không quay về TwiML
<Say>. Nếu TTS điện thoại không khả dụng trong trạng thái đó, yêu cầu phát sẽ thất bại thay vì trộn hai đường phát. - Khi TTS điện thoại quay về một nhà cung cấp phụ, Voice Call ghi log cảnh báo với chuỗi nhà cung cấp (
from,to,attempts) để gỡ lỗi. - Khi barge-in Twilio hoặc teardown stream xóa hàng đợi TTS đang chờ, các yêu cầu phát đã xếp hàng sẽ được hoàn tất thay vì khiến người gọi chờ mãi đến khi phát xong.
Ví dụ TTS
- Chỉ Core TTS
- Ghi đè sang ElevenLabs (chỉ cuộc gọi)
- Ghi đè mô hình OpenAI (hợp nhất sâu)
Cuộc gọi đến
Chính sách gọi đến mặc định làdisabled. Để bật cuộc gọi đến, đặt:
responseModel,
responseSystemPrompt, và responseTimeoutMs.
Hợp đồng đầu ra giọng nói
Đối với phản hồi tự động, Voice Call nối thêm một hợp đồng đầu ra giọng nói nghiêm ngặt vào system prompt:- Bỏ qua payload được đánh dấu là nội dung reasoning/lỗi.
- Phân tích JSON trực tiếp, JSON trong fenced block, hoặc các khóa
"spoken"nội tuyến. - Quay về văn bản thuần và loại bỏ các đoạn mở đầu có khả năng là lập kế hoạch/meta.
Hành vi khởi động cuộc trò chuyện
Đối với cuộc gọiconversation đi, cách xử lý tin nhắn đầu tiên gắn với trạng thái
phát trực tiếp:
- Xóa hàng đợi barge-in và phản hồi tự động chỉ bị chặn khi lời chào ban đầu đang được nói.
- Nếu lần phát ban đầu thất bại, cuộc gọi quay về
listeningvà tin nhắn ban đầu vẫn nằm trong hàng đợi để thử lại. - Lần phát ban đầu cho Twilio streaming bắt đầu khi stream kết nối mà không có độ trễ bổ sung.
- Barge-in hủy phát đang hoạt động và xóa các mục Twilio TTS đã xếp hàng nhưng chưa phát. Các mục bị xóa được resolve 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ờ phát.
- Các cuộc trò chuyện thoại realtime dùng lượt mở đầu riêng của realtime stream. Voice Call không gửi bản cập nhật TwiML
<Say>cũ cho tin nhắn ban đầu đó, nên các phiên<Connect><Stream>gọi đi vẫn được gắn kết.
Khoảng chờ ngắt kết nối stream Twilio
Khi một stream media Twilio ngắt kết nối, Voice Call chờ 2000 ms trước khi tự động kết thúc cuộc gọi:- Nếu stream kết nối lại trong khoảng thời gian đó, tự động kết thúc sẽ bị hủy.
- Nếu không có stream nào đăng ký lại sau khoảng chờ, cuộc gọi sẽ được kết thúc để tránh các cuộc gọi hoạt động bị kẹt.
Bộ dọn cuộc gọi cũ
DùngstaleCallReaperSeconds để kết thúc các cuộc gọi không bao giờ nhận được Webhook
kết thúc (ví dụ: cuộc gọi chế độ thông báo không bao giờ hoàn tất). Mặc định
là 0 (tắt).
Khoảng khuyến nghị:
- Production:
120–300giây cho luồng kiểu thông báo. - Giữ giá trị này cao hơn
maxDurationSecondsđể cuộc gọi bình thường có thể hoàn tất. Điểm bắt đầu tốt làmaxDurationSeconds + 30–60giây.
Bảo mật Webhook
Khi proxy hoặc tunnel nằm 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 header chuyển tiếp nào được tin cậy:Danh sách cho phép các host từ header chuyển tiếp.
Tin cậy header chuyển tiếp mà không cần danh sách cho phép.
Chỉ tin cậy header chuyển tiếp khi IP từ xa của yêu cầu khớp danh sách.
- Bảo vệ chống phát lại Webhook được bật cho Twilio và Plivo. Các yêu cầu Webhook hợp lệ bị phát lại sẽ đượ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 một token theo từng lượt trong callback
<Gather>, nên callback lời nói cũ/bị phát lại không thể thỏa mãn một lượt transcript đ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 body khi thiếu header chữ ký bắt buộc của nhà cung cấp.
- Webhook voice-call dùng hồ sơ body pre-auth dùng chung (64 KB / 5 giây) cộng với giới hạn in-flight theo từng IP trước khi xác minh chữ ký.
CLI
latency đọc calls.jsonl từ đường dẫn lưu trữ voice-call mặc định.
Dùng --file <path> để trỏ tới log khác và --last <n> để giới hạn
phân tích trong N bản ghi cuối (mặc định 200). Đầu ra bao gồm p50/p90/p99
cho độ trễ lượt và thời gian chờ nghe.
Công cụ agent
Tên công cụ:voice_call.
| Hành động | Đối số |
|---|---|
initiate_call | message, to?, mode? |
continue_call | callId, message |
speak_to_user | callId, message |
send_dtmf | callId, digits |
end_call | callId |
get_status | callId |
skills/voice-call/SKILL.md.
Gateway RPC
| Phương thức | Đối số |
|---|---|
voicecall.initiate | to?, message, mode? |
voicecall.continue | callId, message |
voicecall.speak | callId, message |
voicecall.dtmf | callId, digits |
voicecall.end | callId |
voicecall.status | callId |