Плагин голосовых вызовов

​

Быстрый старт

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", // or "telnyx" | "plivo" | "mock"
          fromNumber: "+15550001234", // or TWILIO_FROM_NUMBER for Twilio
          toNumber: "+15550005678",
          sessionScope: "per-phone", // per-phone | per-call
          numbers: {
            "+15550009999": {
              inboundGreeting: "Silver Fox Cards, how can I help?",
              responseSystemPrompt: "You are a concise baseball card specialist.",
              tts: {
                providers: {
                  openai: { speakerVoice: "alloy" },
                },
              },
            },
          },

          twilio: {
            accountSid: "ACxxxxxxxx",
            authToken: "...",
            // region: "ie1", // optional: us1 | ie1 | au1; defaults to us1
          },
          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 /* Twilio only; see Streaming transcription */ },
          realtime: { enabled: false /* see Realtime voice conversations */ },
        },
      },
    },
  },
}

​

Справочник по конфигурации

​

Область действия сеанса

​

Голосовые диалоги в реальном времени

• realtime.enabled поддерживается для Twilio и Telnyx.
• realtime.provider является необязательным. Если значение не задано, Voice Call использует первого зарегистрированного провайдера голосовой связи в реальном времени.
• Встроенные провайдеры голосовой связи в реальном времени: Google Gemini Live (google) и OpenAI (openai), зарегистрированные соответствующими плагинами провайдеров.
• Необработанная конфигурация, принадлежащая провайдеру, находится в 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 записывает предупреждение в журнал и пропускает обработку мультимедиа в реальном времени вместо завершения всего плагина с ошибкой.
• 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: "Говорите кратко. Вызывайте openclaw_agent_consult перед использованием более сложных инструментов.",
            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), зарегистрированные соответствующими плагинами провайдеров.
• Необработанная конфигурация, принадлежащая провайдеру, находится в streaming.providers.<providerId>.
• После получения от Twilio принятого сообщения потока start Voice Call немедленно регистрирует поток, ставит входящие мультимедийные данные в очередь для обработки провайдером транскрипции, пока тот подключается, и запускает начальное приветствие только после готовности транскрипции в реальном времени.
• Если streaming.provider указывает на незарегистрированного провайдера или ни один провайдер не зарегистрирован, Voice Call записывает предупреждение в журнал и пропускает потоковую передачу мультимедиа вместо завершения всего плагина с ошибкой.

​

Примеры потоковых провайдеров

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "openai",
            streamPath: "/voice/stream",
            providers: {
              openai: {
                apiKey: "sk-...", // необязательно, если задан OPENAI_API_KEY
                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}", // необязательно, если задан XAI_API_KEY
                endpointingMs: 800,
                language: "en",
              },
            },
          },
        },
      },
    },
  },
}

​

TTS для вызовов

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

• Устаревшие ключи tts.<provider> в конфигурации плагина (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: "Здравствуйте! Чем я могу помочь?",
}

​

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

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

{
  inboundGreeting: "Здравствуйте, вы позвонили на основную линию.",
  responseSystemPrompt: "Вы — голосовой помощник по умолчанию.",
  tts: {
    provider: "openai",
    providers: {
      openai: { speakerVoice: "coral" },
    },
  },
  numbers: {
    "+15550001111": {
      inboundGreeting: "Silver Fox Cards, чем я могу помочь?",
      responseSystemPrompt: "Вы — лаконичный специалист по бейсбольным карточкам.",
      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 "Привет от OpenClaw"
openclaw voicecall start --to "+15555550123"   # псевдоним для call
openclaw voicecall continue --call-id <id> --message "Есть вопросы?"
openclaw voicecall speak --call-id <id> --message "Одну минуту"
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                      # сводка задержек реплик из журналов
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",
          // или
          tunnel: { provider: "ngrok" },
          // или
          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 был перезапущен без включённого плагина Voice Call.

​

Ошибка проверки подписи

• Убедитесь, что 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 плагину Voice Call.
• Voice Call сохраняет TwiML с DTMF до подключения.
• Исходный TwiML Twilio обрабатывается и передаётся до начала обработки в реальном времени.
• Voice Call передаёт TwiML реального времени для вызова Twilio.
• Google Meet запрашивает вступительную речь с voicecall.speak после задержки, следующей за DTMF.

​

В вызове реального времени отсутствует речь

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

​

Связанные разделы

• Режим разговора
• Преобразование текста в речь
• Голосовая активация