Plugin połączeń głosowych

​

Szybki start

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

​

Konfiguracja

{
  plugins: {
    entries: {
      "voice-call": {
        enabled: true,
        config: {
          provider: "twilio", // lub "telnyx" | "plivo" | "mock"
          fromNumber: "+15550001234", // lub TWILIO_FROM_NUMBER dla Twilio
          toNumber: "+15550005678",
          sessionScope: "per-phone", // per-phone | per-call
          numbers: {
            "+15550009999": {
              inboundGreeting: "Silver Fox Cards, w czym mogę pomóc?",
              responseSystemPrompt: "Jesteś zwięzłym specjalistą od kart baseballowych.",
              tts: {
                providers: {
                  openai: { speakerVoice: "alloy" },
                },
              },
            },
          },

          twilio: {
            accountSid: "ACxxxxxxxx",
            authToken: "...",
            // region: "ie1", // opcjonalnie: us1 | ie1 | au1; domyślnie us1
          },
          telnyx: {
            apiKey: "...",
            connectionId: "...",
            // Klucz publiczny Webhooka Telnyx z Mission Control Portal
            // (Base64; można go również ustawić za pomocą TELNYX_PUBLIC_KEY).
            publicKey: "...",
          },
          plivo: {
            authId: "MAxxxxxxxxxxxxxxxxxxxx",
            authToken: "...",
          },

          // Serwer Webhooka
          serve: {
            port: 3334,
            path: "/voice/webhook",
          },

          // Zabezpieczenia Webhooka (zalecane w przypadku tuneli/serwerów proxy)
          webhookSecurity: {
            allowedHosts: ["voice.example.com"],
            trustedProxyIPs: ["100.64.0.1"],
          },

          // Udostępnienie publiczne (wybierz jedną opcję)
          // publicUrl: "https://example.ngrok.app/voice/webhook",
          // tunnel: { provider: "ngrok" },
          // tailscale: { mode: "funnel", path: "/voice/webhook" },

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

          streaming: { enabled: true /* zobacz Transkrypcja strumieniowa */ },
          realtime: { enabled: false /* zobacz Konwersacje głosowe w czasie rzeczywistym */ },
        },
      },
    },
  },
}

​

Opis konfiguracji

​

Zakres sesji

​

Konwersacje głosowe w czasie rzeczywistym

• realtime.enabled jest obsługiwane w Twilio i Telnyx.
• realtime.provider jest opcjonalne. Jeśli nie jest ustawione, Voice Call używa pierwszego zarejestrowanego dostawcy głosu w czasie rzeczywistym.
• Wbudowani dostawcy głosu w czasie rzeczywistym: Google Gemini Live (google) i OpenAI (openai), rejestrowani przez ich Pluginy dostawców.
• Surowa konfiguracja należąca do dostawcy znajduje się w realtime.providers.<providerId>.
• Voice Call domyślnie udostępnia współdzielone narzędzie czasu rzeczywistego openclaw_agent_consult. Model czasu rzeczywistego może je wywołać, gdy rozmówca prosi o bardziej dogłębne rozumowanie, aktualne informacje lub zwykłe narzędzia OpenClaw.
• realtime.consultPolicy opcjonalnie dodaje wskazówki określające, kiedy model czasu rzeczywistego powinien wywołać openclaw_agent_consult.
• realtime.agentContext.enabled jest domyślnie wyłączone. Po włączeniu Voice Call podczas konfigurowania sesji wprowadza do instrukcji dostawcy czasu rzeczywistego ograniczony zestaw informacji o tożsamości agenta oraz wybranych plikach przestrzeni roboczej.
• realtime.fastContext.enabled jest domyślnie wyłączone. Po włączeniu Voice Call najpierw przeszukuje zaindeksowaną pamięć i kontekst sesji pod kątem pytania konsultacyjnego oraz zwraca znalezione fragmenty modelowi czasu rzeczywistego w czasie określonym przez realtime.fastContext.timeoutMs, a następnie przechodzi do pełnej konsultacji z agentem tylko wtedy, gdy realtime.fastContext.fallbackToConsult ma wartość true.
• Jeśli realtime.provider wskazuje niezarejestrowanego dostawcę albo nie zarejestrowano żadnego dostawcy głosu w czasie rzeczywistym, Voice Call zapisuje ostrzeżenie w dzienniku i pomija multimedia czasu rzeczywistego zamiast powodować błąd całego Pluginu.
• Gdy realtime.enabled ma wartość true, inboundPolicy nie może mieć wartości "disabled"; validateProviderConfig odrzuca taką kombinację.
• Klucze sesji konsultacyjnych ponownie wykorzystują zapisaną sesję połączenia, jeśli jest dostępna, a w przeciwnym razie korzystają ze skonfigurowanego sessionScope (domyślnie per-phone lub per-call w przypadku izolowanych połączeń).

​

Zasady używania narzędzi

​

Kontekst głosowy agenta

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

​

Przykłady dostawców czasu rzeczywistego

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          provider: "twilio",
          inboundPolicy: "allowlist",
          allowFrom: ["+15550005678"],
          realtime: {
            enabled: true,
            provider: "google",
            instructions: "Mów zwięźle. Wywołaj openclaw_agent_consult przed użyciem bardziej zaawansowanych narzędzi.",
            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}" },
            },
          },
        },
      },
    },
  },
}

​

Transkrypcja strumieniowa

• streaming.provider jest opcjonalne. Jeśli nie jest ustawione, Voice Call używa pierwszego zarejestrowanego dostawcy transkrypcji w czasie rzeczywistym.
• Wbudowani dostawcy transkrypcji w czasie rzeczywistym: Deepgram (deepgram), ElevenLabs (elevenlabs), Mistral (mistral), OpenAI (openai) i xAI (xai), rejestrowani przez ich Pluginy dostawców.
• Surowa konfiguracja należąca do dostawcy znajduje się w streaming.providers.<providerId>.
• Gdy Twilio wyśle zaakceptowaną wiadomość start strumienia, Voice Call natychmiast rejestruje strumień, kolejkuje przychodzące multimedia za pośrednictwem dostawcy transkrypcji podczas nawiązywania przez niego połączenia i rozpoczyna powitanie początkowe dopiero po przygotowaniu transkrypcji w czasie rzeczywistym.
• Jeśli streaming.provider wskazuje niezarejestrowanego dostawcę albo nie zarejestrowano żadnego dostawcy, Voice Call zapisuje ostrzeżenie w dzienniku i pomija strumieniowanie multimediów zamiast powodować błąd całego Pluginu.

​

Przykłady dostawców strumieniowania

{
  plugins: {
    entries: {
      "voice-call": {
        config: {
          streaming: {
            enabled: true,
            provider: "openai",
            streamPath: "/voice/stream",
            providers: {
              openai: {
                apiKey: "sk-...", // opcjonalne, jeśli ustawiono 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}", // opcjonalne, jeśli ustawiono XAI_API_KEY
                endpointingMs: 800,
                language: "en",
              },
            },
          },
        },
      },
    },
  },
}

​

TTS dla połączeń

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

• Starsze klucze tts.<provider> w konfiguracji Pluginu (openai, elevenlabs, microsoft, edge) są naprawiane przez openclaw doctor --fix; zatwierdzona konfiguracja powinna używać tts.providers.<provider>.
• Podstawowy mechanizm TTS jest używany, gdy włączone jest strumieniowanie multimediów Twilio; w przeciwnym razie połączenia korzystają z głosów natywnych dla dostawcy.
• Jeśli strumień multimediów Twilio jest już aktywny, Voice Call nie przechodzi awaryjnie do TwiML <Say>. Jeśli w tym stanie telefoniczny TTS jest niedostępny, żądanie odtwarzania kończy się niepowodzeniem zamiast łączyć dwie ścieżki odtwarzania.
• Gdy telefoniczny TTS przechodzi awaryjnie do dostawcy zapasowego, Voice Call zapisuje w dzienniku ostrzeżenie zawierające łańcuch dostawców (from, to, attempts) na potrzeby debugowania.
• Gdy funkcja przerywania wypowiedzi Twilio lub zamknięcie strumienia czyści oczekującą kolejkę TTS, zakolejkowane żądania odtwarzania zostają rozstrzygnięte zamiast powodować zawieszenie rozmówców oczekujących na zakończenie odtwarzania.

​

Przykłady 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",
              },
            },
          },
        },
      },
    },
  },
}

​

Połączenia przychodzące

{
  inboundPolicy: "allowlist",
  allowFrom: ["+15550001234"],
  inboundGreeting: "Cześć! Jak mogę pomóc?",
}

​

Trasowanie według numeru

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

{
  inboundGreeting: "Witamy na głównej linii.",
  responseSystemPrompt: "Jesteś domyślnym asystentem głosowym.",
  tts: {
    provider: "openai",
    providers: {
      openai: { speakerVoice: "coral" },
    },
  },
  numbers: {
    "+15550001111": {
      inboundGreeting: "Silver Fox Cards, w czym mogę pomóc?",
      responseSystemPrompt: "Jesteś zwięzłym specjalistą od kart baseballowych.",
      tts: {
        providers: {
          openai: { speakerVoice: "alloy" },
        },
      },
    },
  },
}

​

Kontrakt wypowiedzi głosowej

• Ignoruje ładunki oznaczone jako treść rozumowania lub błędu.
• Analizuje bezpośredni JSON, JSON w bloku kodu lub osadzone klucze "spoken".
• W razie niepowodzenia używa zwykłego tekstu i usuwa prawdopodobne początkowe akapity dotyczące planowania lub metadanych.

​

Zachowanie podczas rozpoczynania konwersacji

• Czyszczenie kolejki przy przerwaniu wypowiedzi i automatyczna odpowiedź są wstrzymywane tylko wtedy, gdy początkowe powitanie jest aktywnie wypowiadane.
• Jeśli początkowe odtwarzanie się nie powiedzie, połączenie wraca do stanu listening, a początkowa wiadomość pozostaje w kolejce do ponowienia.
• Początkowe odtwarzanie dla strumieniowania Twilio rozpoczyna się po połączeniu strumienia bez dodatkowego opóźnienia.
• Przerwanie wypowiedzi zatrzymuje aktywne odtwarzanie i usuwa z kolejki wpisy TTS Twilio, których odtwarzanie jeszcze się nie rozpoczęło. Usunięte wpisy są rozstrzygane jako pominięte, dzięki czemu logika kolejnej odpowiedzi może działać dalej bez oczekiwania na dźwięk, który nigdy nie zostanie odtworzony.
• Rozmowy głosowe w czasie rzeczywistym używają własnej tury otwierającej strumienia czasu rzeczywistego. Voice Call nie wysyła starszej aktualizacji TwiML <Say> dla tej początkowej wiadomości, dzięki czemu wychodzące sesje <Connect><Stream> pozostają połączone.

​

Okres karencji po rozłączeniu strumienia Twilio

• Jeśli strumień połączy się ponownie w tym czasie, automatyczne zakończenie zostanie anulowane.
• Jeśli po okresie karencji żaden strumień nie zarejestruje się ponownie, połączenie zostanie zakończone, aby zapobiec pozostawieniu zablokowanych aktywnych połączeń.

​

Mechanizm usuwania nieaktualnych połączeń

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

​

Bezpieczeństwo Webhooka

• Ochrona przed ponownym odtworzeniem Webhooka jest włączona dla Twilio, Telnyx i Plivo. Ponownie odtworzone prawidłowe żądania Webhooka są potwierdzane, ale ich skutki uboczne są pomijane.
• Tury konwersacji Twilio zawierają token przypisany do tury w wywołaniach zwrotnych <Gather>, dzięki czemu nieaktualne lub ponownie odtworzone wywołania zwrotne mowy nie mogą zrealizować nowszej oczekującej tury transkrypcji.
• Nieuwierzytelnione żądania Webhooka są odrzucane przed odczytaniem treści, jeśli brakuje wymaganych przez dostawcę nagłówków podpisu.
• Webhook voice-call używa współdzielonego profilu odczytu treści przed uwierzytelnieniem (maksymalnie 64 KB treści, limit czasu odczytu 5 sekund) oraz limitu trwających żądań dla każdego klucza (domyślnie 8 równoczesnych żądań na klucz) przed weryfikacją podpisu.

{
  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

​

Narzędzie agenta

​

RPC Gatewaya

​

Rozwiązywanie problemów

​

Konfiguracja ekspozycji Webhooka kończy się niepowodzeniem

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

​

Poświadczenia dostawcy są nieprawidłowe

• Twilio: twilio.accountSid, twilio.authToken i fromNumber albo TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN i TWILIO_FROM_NUMBER.
• Telnyx: telnyx.apiKey, telnyx.connectionId, telnyx.publicKey i fromNumber albo TELNYX_API_KEY, TELNYX_CONNECTION_ID i TELNYX_PUBLIC_KEY.
• Plivo: plivo.authId, plivo.authToken i fromNumber albo PLIVO_AUTH_ID i PLIVO_AUTH_TOKEN.

​

Połączenia są inicjowane, ale webhooki dostawcy nie docierają

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

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

• publicUrl wskazuje inną ścieżkę niż serve.path.
• Adres URL tunelu zmienił się po uruchomieniu Gateway.
• Serwer proxy przekazuje żądanie, ale usuwa lub przepisuje nagłówki hosta/protokołu.
• Zapora sieciowa lub DNS kieruje publiczną nazwę hosta w inne miejsce niż Gateway.
• Gateway został ponownie uruchomiony bez włączonego pluginu połączeń głosowych.

​

Weryfikacja podpisu kończy się niepowodzeniem

• Potwierdź, że adres URL webhooka dostawcy dokładnie odpowiada publicUrl, włącznie ze schematem, hostem i ścieżką.
• W przypadku adresów URL bezpłatnego planu ngrok aktualizuj publicUrl, gdy zmieni się nazwa hosta tunelu.
• Upewnij się, że serwer proxy zachowuje oryginalne nagłówki hosta i protokołu, albo skonfiguruj webhookSecurity.allowedHosts.
• Nie włączaj skipSignatureVerification poza testami lokalnymi.

​

Dołączanie do Google Meet przez Twilio kończy się niepowodzeniem

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

openclaw googlemeet setup --transport twilio

• Google Meet deleguje dołączanie przez Twilio do połączeń głosowych.
• Połączenia głosowe zapisują TwiML DTMF wykonywane przed połączeniem.
• Początkowy TwiML Twilio zostaje użyty i udostępniony przed obsługą w czasie rzeczywistym.
• Połączenia głosowe udostępniają TwiML czasu rzeczywistego dla połączenia Twilio.
• Google Meet żąda odtworzenia mowy wprowadzającej za pomocą voicecall.speak po opóźnieniu następującym po DTMF.

​

W połączeniu w czasie rzeczywistym nie ma mowy

• Plugin dostawcy obsługi w czasie rzeczywistym jest załadowany i zarejestrowany.
• realtime.provider nie jest ustawione albo wskazuje zarejestrowanego dostawcę.
• Klucz API dostawcy jest dostępny dla procesu Gateway.
• openclaw logs --follow pokazuje udostępnienie TwiML czasu rzeczywistego, uruchomienie mostu czasu rzeczywistego i dodanie początkowego powitania do kolejki.

​

Powiązane

• Tryb rozmowy
• Synteza mowy
• Aktywacja głosowa