Plugin голосових викликів

​

Швидкий початок

openclaw plugins install @openclaw/voice-call

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

openclaw voicecall setup
openclaw voicecall setup --json

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

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

​

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

{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio", // або "telnyx" | "plivo" | "mock"
          fromNumber: "+15550001234", // або TWILIO_FROM_NUMBER для Twilio
          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: "...",
            // Відкритий ключ Webhook Telnyx із Mission Control Portal
            // (Base64; також можна встановити через TELNYX_PUBLIC_KEY).
            publicKey: "...",
          },
          plivo: {
            authId: "MAxxxxxxxxxxxxxxxxxxxx",
            authToken: "...",
          },

          // Сервер Webhook
          serve: {
            port: 3334,
            path: "/voice/webhook",
          },

          // Безпека Webhook (рекомендовано для тунелів/проксі)
          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 /* див. Потокове транскрибування */ },
          realtime: { enabled: false /* див. Голосові розмови в реальному часі */ },
        },
      },
    },
  },
}

​

Довідник із конфігурації

​

Область сеансу

​

Голосові розмови в реальному часі

• realtime.enabled підтримується для Twilio і Telnyx.
• realtime.provider є необов’язковим. Якщо його не задано, Voice Call використовує першого зареєстрованого постачальника голосового зв’язку в реальному часі.
• Вбудовані постачальники голосового зв’язку в реальному часі: Google Gemini Live (google) і OpenAI (openai), зареєстровані відповідними Plugin постачальників.
• Необроблена конфігурація, якою керує постачальник, розміщується в realtime.providers.<providerId>.
• За замовчуванням Voice Call надає спільний інструмент реального часу openclaw_agent_consult. Модель реального часу може викликати його, коли абонент просить про глибший аналіз, актуальну інформацію або звичайні інструменти OpenClaw.
• realtime.consultPolicy необов’язково додає вказівки щодо того, коли модель реального часу має викликати openclaw_agent_consult.
• realtime.agentContext.enabled за замовчуванням вимкнено. Коли цей параметр увімкнено, Voice Call під час налаштування сеансу додає до інструкцій постачальника реального часу обмежений опис ідентичності агента та вибраний набір файлів робочого простору.
• realtime.fastContext.enabled за замовчуванням вимкнено. Коли цей параметр увімкнено, Voice Call спочатку шукає контекст запитання для консультації в індексованій пам’яті та контексті сеансу й повертає ці фрагменти моделі реального часу протягом realtime.fastContext.timeoutMs, а до повноцінного агента консультацій переходить лише тоді, коли realtime.fastContext.fallbackToConsult має значення true.
• Якщо realtime.provider указує на незареєстрованого постачальника або жодного постачальника голосового зв’язку в реальному часі взагалі не зареєстровано, Voice Call записує попередження в журнал і пропускає медіа в реальному часі замість завершення роботи всього Plugin з помилкою.
• inboundPolicy не повинен мати значення "disabled", коли realtime.enabled має значення true; validateProviderConfig відхиляє таке поєднання.
• Ключі сеансів консультацій повторно використовують збережений сеанс виклику, якщо він доступний, а потім переходять до налаштованого sessionScope (за замовчуванням per-phone або per-call для ізольованих викликів).

​

Політика інструментів

​

Голосовий контекст агента

{
  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: "Speak briefly. Call openclaw_agent_consult before using deeper tools.",
            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}" },
            },
          },
        },
      },
    },
  },
}

​

Потокове транскрибування

• streaming.provider є необов’язковим. Якщо його не задано, Voice Call використовує першого зареєстрованого постачальника транскрибування в реальному часі.
• Вбудовані постачальники транскрибування в реальному часі: Deepgram (deepgram), ElevenLabs (elevenlabs), Mistral (mistral), OpenAI (openai) і xAI (xai), зареєстровані відповідними Plugin постачальників.
• Необроблена конфігурація, якою керує постачальник, розміщується в streaming.providers.<providerId>.
• Після того як Twilio надсилає прийняте повідомлення start для потоку, Voice Call негайно реєструє потік, ставить вхідні медіадані в чергу для обробки постачальником транскрибування, поки той підключається, і запускає початкове привітання лише після готовності транскрибування в реальному часі.
• Якщо streaming.provider указує на незареєстрованого постачальника або жодного постачальника не зареєстровано, Voice Call записує попередження в журнал і пропускає потокове передавання медіа замість завершення роботи всього Plugin з помилкою.

​

Приклади постачальників потокового передавання

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

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "xai",
            streamPath: "/voice/stream",
            providers: {
              xai: {
                apiKey: "${XAI_API_KEY}", // optional if XAI_API_KEY is set
                endpointingMs: 800,
                language: "en",
              },
            },
          },
        },
      },
    },
  },
}

​

TTS для викликів

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

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

​

Приклади 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",
              },
            },
          },
        },
      },
    },
  },
}

​

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

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

​

Маршрутизація за номером

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

{
  inboundGreeting: "Hello from the main line.",
  responseSystemPrompt: "You are the default voice assistant.",
  tts: {
    provider: "openai",
    providers: {
      openai: { speakerVoice: "coral" },
    },
  },
  numbers: {
    "+15550001111": {
      inboundGreeting: "Silver Fox Cards, how can I help?",
      responseSystemPrompt: "You are a concise baseball card specialist.",
      tts: {
        providers: {
          openai: { speakerVoice: "alloy" },
        },
      },
    },
  },
}

​

Контракт голосового виведення

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

​

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

• Очищення черги під час перебивання та автоматична відповідь блокуються лише тоді, коли початкове привітання активно озвучується.
• Якщо початкове відтворення завершується помилкою, виклик повертається до стану listening, а початкове повідомлення залишається в черзі для повторної спроби.
• Початкове відтворення для потокового передавання Twilio запускається після підключення потоку без додаткової затримки.
• Перебивання припиняє активне відтворення та очищає записи TTS Twilio, які перебувають у черзі, але ще не відтворюються. Очищені записи завершуються як пропущені, тому логіка наступної відповіді може продовжитися, не очікуючи аудіо, яке ніколи не буде відтворено.
• Голосові розмови в реальному часі використовують власну початкову репліку потоку реального часу. Voice Call не надсилає застаріле оновлення TwiML <Say> для цього початкового повідомлення, тому вихідні сеанси <Connect><Stream> залишаються підключеними.

​

Період очікування після відключення потоку Twilio

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

​

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

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

​

Безпека Webhook

• Захист від повторного відтворення Webhook увімкнено для Twilio, Telnyx і Plivo. Повторно надіслані дійсні запити Webhook підтверджуються, але їхні побічні дії пропускаються.
• Репліки розмови Twilio містять окремий токен для кожної репліки у зворотних викликах <Gather>, тому застарілі або повторно відтворені зворотні виклики мовлення не можуть задовольнити новішу очікувану репліку транскрипту.
• Неавтентифіковані запити Webhook відхиляються до читання тіла, якщо відсутні обов’язкові заголовки підпису провайдера.
• Webhook voice-call використовує спільний профіль читання тіла до автентифікації (максимальний розмір тіла — 64 КБ, час очікування читання — 5 секунд), а також обмеження кількості активних запитів для кожного ключа (типово 8 одночасних запитів на ключ) до перевірки підпису.

{
  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

​

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

​

RPC Gateway

​

Усунення несправностей

​

Налаштуванню не вдається опублікувати Webhook

openclaw voicecall setup
openclaw voicecall setup --json

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

openclaw voicecall setup
openclaw 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.

​

Виклики починаються, але Webhook постачальника не надходять

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

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

• publicUrl указує на шлях, відмінний від serve.path.
• URL-адреса тунелю змінилася після запуску Gateway.
• Проксі пересилає запит, але видаляє або переписує заголовки хосту чи протоколу.
• Брандмауер або DNS спрямовує публічне ім’я хосту не на Gateway.
• Gateway було перезапущено без увімкненого Plugin голосових викликів.

​

Не вдається перевірити підпис

• Переконайтеся, що URL-адреса Webhook постачальника точно відповідає publicUrl, включно зі схемою, хостом і шляхом.
• Для URL-адрес безплатного рівня ngrok оновлюйте publicUrl, коли змінюється ім’я хосту тунелю.
• Переконайтеся, що проксі зберігає початкові заголовки хосту та протоколу, або налаштуйте webhookSecurity.allowedHosts.
• Не вмикайте skipSignatureVerification поза межами локального тестування.

​

Не вдається приєднатися до Google Meet через Twilio

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

openclaw googlemeet setup --transport twilio

• Google Meet делегує приєднання через Twilio голосовому виклику.
• Голосовий виклик зберігає TwiML із DTMF перед підключенням.
• Початковий TwiML Twilio обробляється й надається до обробки в реальному часі.
• Голосовий виклик надає TwiML реального часу для виклику Twilio.
• Google Meet запитує вступне мовлення через voicecall.speak після затримки, що настає після DTMF.

​

У виклику в реальному часі немає мовлення

• Plugin постачальника роботи в реальному часі завантажено й зареєстровано.
• realtime.provider не задано або він указує на зареєстрованого постачальника.
• API-ключ постачальника доступний процесу Gateway.
• openclaw logs --follow показує надання TwiML реального часу, запуск моста реального часу та додавання початкового привітання до черги.

​

Пов’язане

• Режим розмови
• Перетворення тексту на мовлення
• Голосове пробудження