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 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: "...",
          },
          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 */ },
        },
      },
    },
  },
}

​

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

​

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

• realtime.enabled поддерживается для Twilio Media Streams.
• realtime.provider необязателен. Если он не задан, Voice Call использует первого зарегистрированного провайдера голоса в реальном времени.
• Встроенные провайдеры голоса в реальном времени: Google Gemini Live (google) и OpenAI (openai), регистрируемые их provider-Plugin.
• Сырая конфигурация, принадлежащая провайдеру, находится в realtime.providers.<providerId>.
• Voice Call по умолчанию предоставляет общий инструмент реального времени openclaw_agent_consult. Модель реального времени может вызывать его, когда вызывающий просит более глубокое рассуждение, актуальную информацию или обычные инструменты OpenClaw.
• realtime.consultPolicy необязательно добавляет указания о том, когда модель реального времени должна вызывать openclaw_agent_consult.
• realtime.agentContext.enabled по умолчанию выключен. Когда он включен, Voice Call внедряет ограниченную идентичность агента и выбранную капсулу workspace-file в инструкции провайдера реального времени при настройке сеанса.
• realtime.fastContext.enabled по умолчанию выключен. Когда он включен, Voice Call сначала ищет в индексированной памяти/контексте сеанса вопрос для consult и возвращает эти фрагменты модели реального времени в пределах realtime.fastContext.timeoutMs, прежде чем перейти к полному consult-агенту только если realtime.fastContext.fallbackToConsult равен true.
• Если realtime.provider указывает на незарегистрированного провайдера или если вообще не зарегистрирован ни один провайдер голоса в реальном времени, Voice Call записывает предупреждение и пропускает realtime-медиа вместо того, чтобы завершить весь Plugin ошибкой.
• Ключи consult-сеанса повторно используют сохраненный сеанс вызова, когда он доступен, затем переходят к настроенному 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-2.5-flash-native-audio-preview-12-2025",
                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-...", // 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> внутри конфигурации плагина (openai, elevenlabs, microsoft, edge) исправляются командой openclaw doctor --fix; зафиксированная конфигурация должна использовать tts.providers.<provider>.
• Core TTS используется, когда включена потоковая передача медиа Twilio; в противном случае вызовы возвращаются к нативным голосам провайдера.
• Если поток медиа Twilio уже активен, Voice Call не возвращается к TwiML <Say>. Если телефонный TTS недоступен в этом состоянии, запрос воспроизведения завершается ошибкой вместо смешивания двух путей воспроизведения.
• Когда телефонный TTS возвращается к вторичному провайдеру, Voice Call записывает предупреждение с цепочкой провайдеров (from, to, attempts) для отладки.
• Когда barge-in 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" },
        },
      },
    },
  },
}

​

Контракт речевого вывода

{"spoken":"..."}

• Игнорирует полезные нагрузки, помеченные как содержимое рассуждения или ошибки.
• Разбирает прямой JSON, JSON в огражденном блоке или встроенные ключи "spoken".
• Возвращается к обычному тексту и удаляет вероятные вступительные абзацы планирования или метаданных.

​

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

• Очистка очереди barge-in и автоответ подавляются только пока начальное приветствие активно произносится.
• Если начальное воспроизведение завершается ошибкой, вызов возвращается в состояние listening, а начальное сообщение остается в очереди для повторной попытки.
• Начальное воспроизведение для потоковой передачи Twilio запускается при подключении потока без дополнительной задержки.
• Barge-in прерывает активное воспроизведение и очищает поставленные в очередь, но еще не воспроизводимые записи Twilio TTS. Очищенные записи разрешаются как пропущенные, поэтому логика последующего ответа может продолжаться без ожидания аудио, которое никогда не будет воспроизведено.
• Голосовые разговоры в реальном времени используют собственный начальный ход потока реального времени. Voice Call не отправляет устаревшее обновление TwiML <Say> для этого начального сообщения, поэтому исходящие сеансы <Connect><Stream> остаются подключенными.

​

Льготный период при отключении потока Twilio

• Если поток повторно подключается в течение этого окна, автоматическое завершение отменяется.
• Если после льготного периода ни один поток не регистрируется повторно, вызов завершается, чтобы предотвратить зависшие активные вызовы.

​

Очистка устаревших вызовов

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

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

​

Безопасность Webhook

• Защита от повторного воспроизведения Webhook включена для Twilio и Plivo. Повторно воспроизведенные валидные Webhook-запросы подтверждаются, но пропускаются для побочных эффектов.
• Ходы разговора Twilio включают токен для каждого хода в обратных вызовах <Gather>, поэтому устаревшие или повторно воспроизведенные речевые обратные вызовы не могут удовлетворить более новый ожидающий ход транскрипта.
• Неаутентифицированные Webhook-запросы отклоняются до чтения тела, если отсутствуют обязательные заголовки подписи провайдера.
• Webhook voice-call использует общий pre-auth профиль тела (64 КБ / 5 секунд) плюс ограничение на количество одновременных запросов по IP перед проверкой подписи.

{
  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

​

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

​

Gateway RPC

​

Устранение неполадок

​

Настройка не может открыть 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.
• Plivo: plivo.authId, plivo.authToken и fromNumber.

​

Вызовы запускаются, но Webhook провайдера не приходят

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

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

• publicUrl указывает на путь, отличный от serve.path.
• URL туннеля изменился после запуска Gateway.
• Прокси пересылает запрос, но удаляет или переписывает заголовки host/proto.
• Firewall или DNS направляет публичное имя хоста куда-то помимо Gateway.
• Gateway был перезапущен без включенного Plugin Voice Call.

​

Проверка подписи не проходит

• Убедитесь, что URL Webhook у провайдера точно совпадает с publicUrl, включая схему, хост и путь.
• Для URL ngrok free-tier обновляйте publicUrl, когда имя хоста туннеля меняется.
• Убедитесь, что прокси сохраняет исходные заголовки host и proto, или настройте 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 сохраняет pre-connect DTMF TwiML.
• Начальный TwiML Twilio потребляется и отдается до realtime-обработки.
• Voice Call отдает realtime TwiML для вызова Twilio.
• Google Meet запрашивает вступительную речь через voicecall.speak после задержки post-DTMF.

​

В realtime-вызове нет речи

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

​

См. также

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