​

Voice Call (плагін)

• 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

​

Де це працює (локально чи віддалено)

​

Установлення

​

Варіант A: установлення з npm (рекомендовано)

openclaw plugins install @openclaw/voice-call

​

Варіант B: установлення з локальної папки (розробка, без копіювання)

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

​

Конфігурація

{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio", // or "telnyx" | "plivo" | "mock"
          fromNumber: "+15550001234",
          toNumber: "+15550005678",

          twilio: {
            accountSid: "ACxxxxxxxx",
            authToken: "...",
          },

          telnyx: {
            apiKey: "...",
            connectionId: "...",
            // Telnyx webhook public key from the Telnyx Mission Control Portal
            // (Base64 string; 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,
            provider: "openai", // optional; first registered realtime transcription provider when unset
            streamPath: "/voice/stream",
            providers: {
              openai: {
                apiKey: "sk-...", // optional if OPENAI_API_KEY is set
                model: "gpt-4o-transcribe",
                silenceDurationMs: 800,
                vadThreshold: 0.5,
              },
            },
            preStartTimeoutMs: 5000,
            maxPendingConnections: 32,
            maxPendingConnectionsPerIp: 4,
            maxConnections: 128,
          },
        },
      },
    },
  },
}

• Для Twilio/Telnyx потрібен публічно доступний URL webhook.
• Для Plivo потрібен публічно доступний URL webhook.
• mock — це локальний провайдер для розробки (без мережевих викликів).
• Якщо у старих конфігураціях досі використовується provider: "log", twilio.from або застарілі ключі OpenAI в streaming.*, запустіть openclaw doctor --fix, щоб переписати їх.
• Для Telnyx потрібен telnyx.publicKey (або TELNYX_PUBLIC_KEY), якщо тільки skipSignatureVerification не має значення true.
• skipSignatureVerification призначено лише для локального тестування.
• Якщо ви використовуєте безкоштовний рівень ngrok, установіть publicUrl на точний URL ngrok; перевірка підпису завжди примусово виконується.
• tunnel.allowNgrokFreeTierLoopbackBypass: true дозволяє webhook-виклики Twilio з невалідними підписами лише коли tunnel.provider="ngrok" і serve.bind — це loopback (локальний агент ngrok). Використовуйте лише для локальної розробки.
• URL-адреси ngrok на безкоштовному рівні можуть змінюватися або додавати проміжну поведінку; якщо publicUrl зміниться, підписи Twilio перестануть проходити перевірку. Для production краще використовувати стабільний домен або Tailscale funnel.
• Типові параметри безпеки streaming:
  • streaming.preStartTimeoutMs закриває сокети, які так і не надсилають валідний кадр start.
• streaming.maxPendingConnections обмежує загальну кількість неавтентифікованих сокетів до старту.
• streaming.maxPendingConnectionsPerIp обмежує кількість неавтентифікованих сокетів до старту для кожної IP-адреси джерела.
• streaming.maxConnections обмежує загальну кількість відкритих сокетів медіапотоку (очікування + активні).
• Runtime fallback поки що все ще приймає ці старі ключі voice-call, але шлях переписування — це openclaw doctor --fix, а shim сумісності є тимчасовим.

​

Транскрибування потоку

• streaming.provider є необов’язковим. Якщо його не задано, Voice Call використовує першого зареєстрованого провайдера транскрибування в реальному часі.
• Наразі bundled-провайдером є OpenAI, зареєстрований bundled-плагіном openai.
• Сирий конфіг провайдера зберігається в streaming.providers.<providerId>.
• Якщо streaming.provider вказує на незареєстрованого провайдера або якщо взагалі не зареєстровано жодного провайдера транскрибування в реальному часі, Voice Call записує попередження в журнал і пропускає потокову передачу медіа замість того, щоб аварійно завершити весь плагін.

• API-ключ: streaming.providers.openai.apiKey або OPENAI_API_KEY
• модель: 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,
              },
            },
          },
        },
      },
    },
  },
}

• streaming.sttProvider → streaming.provider
• streaming.openaiApiKey → streaming.providers.openai.apiKey
• streaming.sttModel → streaming.providers.openai.model
• streaming.silenceDurationMs → streaming.providers.openai.silenceDurationMs
• streaming.vadThreshold → streaming.providers.openai.vadThreshold

​

Очищення застарілих дзвінків

• Production: 120–300 секунд для потоків у стилі notify.
• Зберігайте це значення більшим за maxDurationSeconds, щоб звичайні дзвінки могли завершитися. Хороша початкова точка — maxDurationSeconds + 30–60 секунд.

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

​

Безпека webhook

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

​

TTS для дзвінків

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

• Застарілі ключі tts.<provider> у конфігурації плагіна (openai, elevenlabs, microsoft, edge) автоматично мігруються в tts.providers.<provider> під час завантаження. У конфігурації, що зберігається в репозиторії, віддавайте перевагу структурі providers.
• Microsoft speech ігнорується для голосових дзвінків (телефонному аудіо потрібен PCM; поточний транспорт Microsoft не надає телефонний вихід PCM).
• Під час увімкненого потокового медіа Twilio використовується ядровий TTS; інакше дзвінки переходять до нативних голосів провайдера.
• Якщо медіапотік Twilio уже активний, Voice Call не переходить на TwiML <Say>. Якщо в цьому стані телефонний TTS недоступний, запит на відтворення завершується помилкою замість змішування двох шляхів відтворення.
• Коли телефонний TTS переходить на резервного провайдера, Voice Call записує попередження в журнал із ланцюжком провайдерів (from, to, attempts) для налагодження.

​

Більше прикладів

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

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

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

​

Вхідні дзвінки

{
  inboundPolicy: "allowlist",
  allowFrom: ["+15550001234"],
  inboundGreeting: "Hello! How can I help?",
}

• responseModel
• responseSystemPrompt
• responseTimeoutMs

​

Контракт озвученого виводу

• {"spoken":"..."}

• Ігнорує payload, позначений як контент міркування/помилки.
• Аналізує прямий JSON, JSON у fenced-блоках або вбудовані ключі "spoken".
• Повертається до звичайного тексту й видаляє абзаци на початку, які ймовірно є плануванням/метатекстом.

​

Поведінка запуску розмови

• Очищення черги barge-in і автовідповідь пригнічуються лише поки активно озвучується початкове привітання.
• Якщо початкове відтворення не вдається, дзвінок повертається до стану listening, а початкове повідомлення лишається в черзі для повторної спроби.
• Початкове відтворення для потоків Twilio починається після підключення потоку без додаткової затримки.

​

Пільговий період після від’єднання потоку Twilio

• Якщо потік повторно підключиться протягом цього вікна, автоматичне завершення скасовується.
• Якщо після завершення пільгового періоду потік не буде повторно зареєстровано, дзвінок завершується, щоб запобігти зависанню активних дзвінків.

​

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

​

Інструмент агента

• initiate_call (message, to?, mode?)
• continue_call (callId, message)
• speak_to_user (callId, message)
• end_call (callId)
• get_status (callId)

​

Gateway RPC

• voicecall.initiate (to?, message, mode?)
• voicecall.continue (callId, message)
• voicecall.speak (callId, message)
• voicecall.end (callId)
• voicecall.status (callId)