Chuyển đến nội dung chính

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.

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: 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

1

Install the plugin

openclaw plugins install @openclaw/voice-call
Nếu npm báo cáo gói thuộc sở hữu của OpenClaw là deprecated, phiên bản gói đó đến từ một chuỗi gói bên ngoài cũ hơn; hãy dùng bản dựng OpenClaw được đóng gói hiện tại hoặc đường dẫn thư mục cục bộ cho đến khi một gói npm mới hơn được phát hành.Sau đó khởi động lại Gateway để Plugin được tải.
2

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.
3

Verify setup

openclaw voicecall setup
Đầu ra mặc định dễ đọc trong nhật ký chat và terminal. Lệnh này kiểm tra việc bật Plugin, thông tin xác thực của nhà cung cấp, mức độ lộ diện Webhook và rằng chỉ một chế độ âm thanh (streaming hoặc realtime) đang hoạt động. Dùng --json cho script.
4

Smoke test

openclaw voicecall smoke
openclaw voicecall smoke --to "+15555550123"
Cả hai mặc định đều là chạy thử. Thêm --yes để thực sự thực hiện một cuộc gọi thông báo đi ngắn:
openclaw voicecall smoke --to "+15555550123" --yes
Với Twilio, Telnyx và Plivo, quá trình thiết lập phải phân giải thành một URL Webhook công khai. Nếu publicUrl, URL tunnel, URL Tailscale hoặc phương án dự phòng serve phân giải thành loopback hoặc vùng mạng riêng, thiết lập sẽ thất bại thay vì khởi động một nhà cung cấp không thể nhận Webhook từ nhà mạng.

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, 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.authTokenplugins.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.
{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio", // or "telnyx" | "plivo" | "mock"
          fromNumber: "+15550001234", // or TWILIO_FROM_NUMBER for Twilio
          toNumber: "+15550005678",

          twilio: {
            accountSid: "ACxxxxxxxx",
            authToken: "...",
          },
          telnyx: {
            apiKey: "...",
            connectionId: "...",
            // Telnyx webhook public key from the Mission Control Portal
            // (Base64; can also be set via TELNYX_PUBLIC_KEY).
            publicKey: "...",
          },
          plivo: {
            authId: "MAxxxxxxxxxxxxxxxxxxxx",
            authToken: "...",
          },

          // Webhook server
          serve: {
            port: 3334,
            path: "/voice/webhook",
          },

          // Webhook security (recommended for tunnels/proxies)
          webhookSecurity: {
            allowedHosts: ["voice.example.com"],
            trustedProxyIPs: ["100.64.0.1"],
          },

          // Public exposure (pick one)
          // publicUrl: "https://example.ngrok.app/voice/webhook",
          // tunnel: { provider: "ngrok" },
          // tailscale: { mode: "funnel", path: "/voice/webhook" },

          outbound: {
            defaultMode: "notify", // notify | conversation
          },

          streaming: { enabled: true /* see Streaming transcription */ },
          realtime: { enabled: false /* see Realtime voice */ },
        },
      },
    },
  },
}
  • Twilio, Telnyx và Plivo đều yêu cầu một URL Webhook có thể truy cập công khai.
  • mock là 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ặc TELNYX_PUBLIC_KEY) trừ khi skipSignatureVerification là true.
  • skipSignatureVerification chỉ dành cho kiểm thử cục bộ.
  • Trên gói miễn phí của ngrok, đặt publicUrl thành đúng URL ngrok; xác minh chữ ký luôn được thực thi.
  • tunnel.allowNgrokFreeTierLoopbackBypass: true cho phép Webhook Twilio có chữ ký không hợp lệ chỉ khi tunnel.provider="ngrok"serve.bind là 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 publicUrl bị 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.preStartTimeoutMs đóng các socket không bao giờ gửi frame start hợp lệ.
  • streaming.maxPendingConnections giới hạn tổng số socket trước khi start chưa xác thực.
  • streaming.maxPendingConnectionsPerIp giới hạn socket trước khi start chưa xác thực trên mỗi IP nguồn.
  • streaming.maxConnections giới hạn tổng số socket media stream đang mở (đang chờ + đang hoạt động).
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.sttProviderstreaming.provider
  • streaming.openaiApiKeystreaming.providers.openai.apiKey
  • streaming.sttModelstreaming.providers.openai.model
  • streaming.silenceDurationMsstreaming.providers.openai.silenceDurationMs
  • streaming.vadThresholdstreaming.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.
realtime.enabled không thể kết hợp với streaming.enabled. Chọn một chế độ âm thanh cho mỗi cuộc gọi.
Hành vi runtime hiện tại:
  • realtime.enabled được hỗ trợ cho Twilio Media Streams.
  • realtime.provider là 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.provider trỏ đế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áchHành vi
safe-read-onlyCung cấp công cụ consult và giới hạn agent thông thường ở read, web_search, web_fetch, x_search, memory_searchmemory_get.
ownerCung 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.
noneKhô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

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.
{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          provider: "twilio",
          inboundPolicy: "allowlist",
          allowFrom: ["+15550005678"],
          realtime: {
            enabled: true,
            provider: "google",
            instructions: "Speak briefly. Call openclaw_agent_consult before using deeper tools.",
            toolPolicy: "safe-read-only",
            providers: {
              google: {
                apiKey: "${GEMINI_API_KEY}",
                model: "gemini-2.5-flash-native-audio-preview-12-2025",
                voice: "Kore",
              },
            },
          },
        },
      },
    },
  },
}
Xem nhà cung cấp Googlenhà cung cấp OpenAI để biết các tùy chọn giọng nói realtime dành riêng cho nhà cung cấp.

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.provider là 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.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 media streaming thay vì làm toàn bộ Plugin thất bại.

Ví dụ nhà cung cấp streaming

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.
{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "openai",
            streamPath: "/voice/stream",
            providers: {
              openai: {
                apiKey: "sk-...", // optional if OPENAI_API_KEY is set
                model: "gpt-4o-transcribe",
                silenceDurationMs: 800,
                vadThreshold: 0.5,
              },
            },
          },
        },
      },
    },
  },
}

TTS cho cuộc gọi

Voice Call dùng cấu hình lõi messages.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.
{
  tts: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        voiceId: "pMsXgVXv3BLzUgSXRplE",
        modelId: "eleven_multilingual_v2",
      },
    },
  },
}
Microsoft speech bị bỏ qua cho cuộc gọi thoại. Âm thanh điện thoại cần PCM; transport Microsoft hiện tại không cung cấp đầu ra PCM cho điện thoại.
Ghi chú về hành vi:
  • Các khóa tts.<provider> cũ trong cấu hình plugin (openai, elevenlabs, microsoft, edge) được sửa bởi openclaw doctor --fix; cấu hình đã commit nên dùng tts.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

{
  messages: {
    tts: {
      provider: "openai",
      providers: {
        openai: { voice: "alloy" },
      },
    },
  },
}

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:
{
  inboundPolicy: "allowlist",
  allowFrom: ["+15550001234"],
  inboundGreeting: "Hello! How can I help?",
}
inboundPolicy: "allowlist" là một lớp lọc ID người gọi có độ đảm bảo thấp. Plugin chuẩn hóa giá trị From do nhà cung cấp gửi và so sánh với allowFrom. Xác minh Webhook xác thực việc gửi từ nhà cung cấp và tính toàn vẹn của payload, nhưng không chứng minh quyền sở hữu số người gọi PSTN/VoIP. Hãy xem allowFrom là lọc ID người gọi, không phải danh tính người gọi mạnh.
Phản hồi tự động dùng hệ thống agent. Tinh chỉnh bằng 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:
{"spoken":"..."}
Voice Call trích xuất văn bản giọng nói theo cách phòng thủ:
  • 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.
Điều này giữ phần phát giọng nói tập trung vào văn bản dành cho người gọi và tránh rò rỉ văn bản lập kế hoạch vào âm thanh.

Hành vi khởi động cuộc trò chuyện

Đối với cuộc gọi conversation đ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ề listening và 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ùng staleCallReaperSeconds để 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: 120300 giâ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–60 giây.
{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          maxDurationSeconds: 300,
          staleCallReaperSeconds: 360,
        },
      },
    },
  },
}

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:
webhookSecurity.allowedHosts
string[]
Danh sách cho phép các host từ header chuyển tiếp.
webhookSecurity.trustForwardingHeaders
boolean
Tin cậy header chuyển tiếp mà không cần danh sách cho phép.
webhookSecurity.trustedProxyIPs
string[]
Chỉ tin cậy header chuyển tiếp khi IP từ xa của yêu cầu khớp danh sách.
Các biện pháp bảo vệ bổ sung:
  • 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ý.
Ví dụ với một host 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 "Hello from OpenClaw"
openclaw voicecall start --to "+15555550123"   # alias for call
openclaw voicecall continue --call-id <id> --message "Any questions?"
openclaw voicecall speak --call-id <id> --message "One moment"
openclaw voicecall dtmf --call-id <id> --digits "ww123456#"
openclaw voicecall end --call-id <id>
openclaw voicecall status --call-id <id>
openclaw voicecall tail
openclaw voicecall latency                      # summarize turn latency from logs
openclaw voicecall expose --mode funnel
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_callmessage, to?, mode?
continue_callcallId, message
speak_to_usercallId, message
send_dtmfcallId, digits
end_callcallId
get_statuscallId
Repo này cung cấp tài liệu skill tương ứng tại skills/voice-call/SKILL.md.

Gateway RPC

Phương thứcĐối số
voicecall.initiateto?, message, mode?
voicecall.continuecallId, message
voicecall.speakcallId, message
voicecall.dtmfcallId, digits
voicecall.endcallId
voicecall.statuscallId

Liên quan