ClawRouter

ClawRouter udostępnia OpenClaw jeden klucz o zakresie określonym przez zasady dla wielu nadrzędnych dostawców modeli. Dołączony Plugin clawrouter wykrywa wyłącznie modele dozwolone dla tego klucza, kieruje każdy model przez zadeklarowany dla niego protokół i raportuje budżet klucza oraz łączne użycie w interfejsach użycia OpenClaw. Poświadczenia nadrzędne i przekazywanie specyficzne dla dostawcy pozostają w ClawRouter, dlatego nie trzeba instalować ani uwierzytelniać każdego Pluginu dostawcy nadrzędnego na hoście OpenClaw. Plugin jest dołączony do OpenClaw (enabledByDefault: true); potrzebne jest tylko wydane poświadczenie ClawRouter.

Właściwość	Wartość
Dostawca	`clawrouter`
Plugin	dołączony (zawarty w OpenClaw)
Uwierzytelnianie	`CLAWROUTER_API_KEY`
Domyślny adres URL	`https://clawrouter.openclaw.ai`
Katalog modeli	Ograniczony zakresem poświadczenia przez `/v1/catalog`
Limity	Miesięczny budżet i użycie przez `/v1/usage`

Pierwsze kroki

Uzyskanie poświadczenia o określonym zakresie

Należy poprosić administratora ClawRouter o poświadczenie, którego zasady obejmują dostawców, modele i miesięczny budżet przeznaczone do użycia. Poświadczenia są ujawniane jednokrotnie podczas wydawania.

Konfigurowanie OpenClaw

export CLAWROUTER_API_KEY="..."
openclaw onboard --auth-choice clawrouter-api-key
openclaw plugins enable clawrouter

clawrouter jest dołączony i domyślnie włączony. Jeśli konfiguracja ustawia plugins.allow, przed włączeniem należy dodać clawrouter do tej listy. W przypadku niestandardowego wdrożenia należy ustawić models.providers.clawrouter.baseUrl na źródło ClawRouter; wartość domyślna to https://clawrouter.openclaw.ai.

Wyświetlanie przyznanych modeli

openclaw models list --all --provider clawrouter

Zwróconych odwołań do modeli należy używać dokładnie w pokazanej postaci. Zachowują one nadrzędną przestrzeń nazw, na przykład clawrouter/openai/gpt-5.5, clawrouter/anthropic/claude-sonnet-4-6 lub clawrouter/google/gemini-3.5-flash. Jeśli agents.defaults.models jest listą dozwolonych w konfiguracji, należy dodać do niej każde wybrane odwołanie ClawRouter.

Wybieranie modelu

openclaw models set clawrouter/<provider>/<model>

Zwrócony model można również wybrać dla pojedynczego uruchomienia za pomocą openclaw agent --model clawrouter/<provider>/<model> --message "...".

Zarządzane wdrożenie nieinteraktywne

Klucz serwera proxy należy przechowywać w mechanizmie wstrzykiwania sekretów obciążenia, a w openclaw.json zapisać wyłącznie SecretRef. Kanoniczne pola zarządzane to:

Przeznaczenie	Pole konfiguracji lub środowiska
Źródło routera	`models.providers.clawrouter.baseUrl`
Poświadczenie	`models.providers.clawrouter.apiKey` -> środowiskowy SecretRef
Wartość sekretu	`CLAWROUTER_API_KEY` w środowisku procesu Gateway
Model domyślny	`agents.defaults.model.primary` -> `clawrouter/<provider>/<model>`
Znacznik obciążenia	`models.providers.clawrouter.headers.X-ClawRouter-Project-Id` (opcjonalnie)

Na przykład kontroler wdrożenia może zarządzać następującą poprawką JSON5:

{
  plugins: {
    entries: { clawrouter: { enabled: true } },
  },
  models: {
    providers: {
      clawrouter: {
        baseUrl: "https://clawrouter.internal.example",
        apiKey: {
          source: "env",
          provider: "default",
          id: "CLAWROUTER_API_KEY",
        },
        headers: {
          "X-ClawRouter-Project-Id": "fakeco",
        },
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "clawrouter/openai/gpt-5.5" },
    },
  },
}

Jeśli wdrożenie ustawia plugins.allow, należy zachować istniejące wpisy i dodać clawrouter. Walidację i zastosowanie bez interaktywnego kreatora wykonuje się następująco:

openclaw config patch --file ./clawrouter.patch.json5 --dry-run --json
openclaw config patch --file ./clawrouter.patch.json5

Przebieg próbny rozwiązuje SecretRef, ale nigdy nie wyświetla jego wartości. Aby przeprowadzić rotację poświadczenia, należy zaktualizować zewnętrzny Secret dostarczający CLAWROUTER_API_KEY i ponownie uruchomić obciążenie Gateway, aby zostało wczytane nowe środowisko procesu. Plik konfiguracji i odwołanie do modelu nie ulegają zmianie. W przypadku samodzielnego Gateway Docker zbudowanego ze źródeł ClawRouter jest już zawarty w głównym środowisku uruchomieniowym. Należy wybrać tylko Plugin kanału wymagający oddzielnego pakowania, na przykład OPENCLAW_EXTENSIONS=clickclack, slack lub msteams; zobacz obrazy zbudowane ze źródeł z wybranymi Pluginami. Wdrożenia archiwalne lub urządzeniowe muszą pakować ten sam wdrożony kod źródłowy za pośrednictwem własnego potoku artefaktów zamiast korzystać z obrazu OCI.

Gotowość i weryfikacja na żywo

Te kontrole potwierdzają różne granice; nie należy zastępować jednej drugą:

# Tylko kondycja procesu ClawRouter; nie jest używane poświadczenie ani model nadrzędny.
curl -fsS https://clawrouter.internal.example/v1/health

# Tylko gotowość uruchomienia Gateway OpenClaw; nie jest wykonywane wywołanie modelu.
curl -fsS http://127.0.0.1:18789/readyz

# Wykrywanie katalogu ograniczone zakresem poświadczenia.
openclaw models list --all --provider clawrouter --json

# Minimalna rzeczywista próba inferencji przez skonfigurowanego dostawcę ClawRouter.
openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json

# Test kanarkowy obciążenia wykorzystujący dokładne odwołanie do przyznanego modelu.
openclaw agent --agent main \
  --model clawrouter/openai/gpt-5.5 \
  --message "Odpowiedz dokładnie: CLAWROUTER_CANARY_OK" \
  --json

Należy użyć modelu zwróconego przez katalog o określonym zakresie zamiast bezrefleksyjnie kopiować model z przykładu. Pomyślna odpowiedź /readyz oznacza, że Gateway może obsługiwać żądania; nie potwierdza ona gotowości ClawRouter, jego poświadczenia ani dostawcy nadrzędnego. Próba modelu i test kanarkowy agenta stanowią weryfikację inferencji. W celu diagnostyki na żywo należy wykonać test kanarkowy i sprawdzić standardowe dzienniki Gateway. Istniejąca diagnostyka transportu modelu obejmująca wyłącznie metadane emituje wiersze o następującej postaci:

[model-fetch] uruchomienie provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses
[model-fetch] odpowiedź provider=clawrouter api=openai-responses model=openai/gpt-5.5 status=200

Plugin wysyła ograniczone nagłówki X-ClawRouter-Client, X-ClawRouter-Agent-Id i X-ClawRouter-Session-Id, gdy te identyfikatory są dostępne. Odwzorowuje również diagnostyczny identyfikator callId (<run-id>:model:<n>) wywołania modelu na X-Request-ID, dzięki czemu zdarzenie wywołania modelu OpenClaw można połączyć ze ścieżką audytu ClawRouter obejmującą wyłącznie metadane. Wartości mieszczące się w limicie 128 znaków dla identyfikatora żądania są identyczne. Dłuższe wartości zachowują sufiks :model:<n> oraz deterministyczny skrót, dzięki czemu różne wywołania pozostają ograniczone i możliwe do powiązania. Statyczne metadane wdrożenia, takie jak X-ClawRouter-Project-Id, można ustawić w mapie headers dostawcy. Nagłówki atrybucji agenta i sesji zachowują oddzielny limit 256 znaków. Automatyczne identyfikatory żądań zawierające znaki spoza zestawu identyfikatorów ASCII ClawRouter używają tej samej deterministycznej, ograniczonej postaci. Jawnie skonfigurowane nagłówki, w tym dowolny wariant wielkości liter X-Request-ID, mają pierwszeństwo przed wartościami automatycznymi. Diagnostyka transportu rejestruje metadane routingu i odpowiedzi; nie rejestruje poświadczeń, identyfikatorów żądań, promptów ani ukończeń. Własne zdarzenie audytu ClawRouter zawiera wybranego dostawcę nadrzędnego oraz stan przechowywania treści.

Wykrywanie modeli

GET /v1/catalog zwraca { providers: [...] }, gdzie każdy wpis dostawcy zawiera własne models[] (z identyfikatorem nadrzędnym, możliwościami i cenami) oraz obsługiwane trasy żądań. OpenClaw nie dostarcza drugiej, stałej listy modeli ClawRouter. Model katalogowy jest udostępniany jako model OpenClaw, gdy:

zasady poświadczenia przyznają dostęp do jego dostawcy;
model katalogowy deklaruje obsługiwaną możliwość LLM (llm.responses, llm.chat, llm.messages lub llm.stream z pasującą trasą strumieniowania); oraz
dostawca udostępnia pasującą trasę dla jednego z poniższych transportów.

Dodanie modelu do obsługiwanego dostawcy ClawRouter nie wymaga wydania nowej wersji OpenClaw: zostanie on wykryty przy następnym odświeżeniu katalogu (buforowanym przez 60 sekund dla każdego zakresu poświadczenia). Model wymagający nowego protokołu transmisji wymaga najpierw obsługi przez Plugin.

Protokoły i Pluginy dostawców

ClawRouter zarządza poświadczeniami nadrzędnymi; jego katalog informuje OpenClaw, którego transportu użyć, więc nie trzeba instalować Pluginu uwierzytelniającego każdej firmy nadrzędnej.

Możliwość/trasa katalogu	Transport OpenClaw
`llm.responses` (dostawca zgodny z OpenAI)	`openai-responses`
`llm.chat` (dostawca zgodny z OpenAI)	`openai-completions`
`llm.messages` + trasa `anthropic.messages`	`anthropic-messages`
`llm.stream` + strumieniowa trasa `google.generate_content`	`google-generative-ai`

Plugin stosuje również odpowiednie zasady ponawiania i schematów narzędzi dla tych rodzin (zgodność schematów narzędzi OpenAI/DeepSeek/Gemini/Perplexity; natywne zasady ponawiania Anthropic i Google Gemini). Modele Perplexity otrzymują rygorystyczne przekształcenie schematu: patternProperties i additionalProperties są usuwane, a każdy schemat obiektu deklaruje properties, ponieważ Perplexity odrzuca schematy narzędzi bez tych deklaracji. Dostawca katalogowy udostępniający wyłącznie nieobsługiwany format żądań celowo nie jest udostępniany jako tekstowy model OpenClaw. Takich dostawców należy normalizować w ClawRouter do jednego z obsługiwanych kontraktów zamiast wysyłać niezgodny ładunek.

Limity i użycie

Odpowiedź /v1/usage ClawRouter zasila standardowe interfejsy użycia dostawców OpenClaw: sumy żądań, tokenów i wydatków oraz miesięczne okno budżetowe, gdy klucz ma określony limit. Klucze bez limitu nadal pokazują łączne użycie bez okna procentowego. Wyszukiwanie limitu używa tego samego klucza o określonym zakresie co wykrywanie modeli. Nieudane wyszukanie limitu nie blokuje wykonywania modelu. Bieżący stan można sprawdzić za pomocą:

openclaw status --usage
openclaw models status

Ten sam stan dostawcy jest dostępny dla /status na czacie oraz w interfejsie użycia OpenClaw. Budżet obejmuje całe zasady, dlatego żądania wykonane przez innego klienta używającego tych samych zasad ClawRouter mogą zmienić pozostałą wartość procentową.

Rozwiązywanie problemów

Objaw	Kontrola
Brak modeli ClawRouter	Należy potwierdzić, że Plugin jest włączony i dozwolony przez `plugins.allow`, a następnie sprawdzić, czy poświadczenie jest aktywne i przyznaje dostęp do co najmniej jednego gotowego dostawcy.
Brakuje skonfigurowanego modelu ClawRouter	Należy sprawdzić jego możliwość `/v1/catalog` i obsługę tras. Nieobsługiwane kontrakty transportu są celowo odfiltrowywane.
`Unknown model: clawrouter/...`	Należy dodać dokładne odwołanie katalogowe do `agents.defaults.models`, gdy ta mapa konfiguracji jest używana jako lista dozwolonych.
`401` lub `403` z katalogu lub danych użycia	Należy ponownie wydać poświadczenie ClawRouter lub zmienić jego zakres; OpenClaw nie przełącza się awaryjnie na klucze dostawców nadrzędnych.
Wywołanie modelu kończy się niepowodzeniem po jego wykryciu	Należy sprawdzić połączenie z dostawcą i kondycję systemu nadrzędnego w ClawRouter, a następnie ponowić próbę po przywróceniu jego gotowości.
Użycie zawiera sumy, ale nie wartość procentową	Zasady nie mają limitu; należy dodać miesięczny budżet w ClawRouter, aby udostępnić okno procentowe.

Zachowanie zabezpieczeń

Wykrywanie katalogu jest ograniczone do skonfigurowanego klucza serwera proxy i buforowane osobno dla każdego zakresu poświadczeń (katalog agenta, katalog obszaru roboczego, identyfikator profilu uwierzytelniania i bazowy adres URL).
Klucz serwera proxy jest dołączany dopiero podczas wysyłania żądania; nie jest przechowywany w metadanych modelu.
Wartości automatycznego przypisania i korelacji żądań są przed wysłaniem przycinane, a wartości zawierające znaki sterujące — odrzucane. Wartości przypisania są ograniczone do 256 znaków, a identyfikatory żądań — do 128.
Dane diagnostyczne transportu modelu zawierają wyłącznie metadane i nigdy nie obejmują klucza serwera proxy ani treści modelu.
Natywne identyfikatory modeli Anthropic i Gemini są zastępowane identyfikatorami systemów nadrzędnych dopiero podczas wysyłania.
Nieobsługiwane lub nieprzyznane pozycje katalogu są domyślnie odrzucane i nie można ich wybrać.

Overview

Concepts and configuration

Providers

Pierwsze kroki

Zarządzane wdrożenie nieinteraktywne

Gotowość i weryfikacja na żywo

Wykrywanie modeli

Protokoły i Pluginy dostawców

Limity i użycie

Rozwiązywanie problemów

Zachowanie zabezpieczeń

Powiązane materiały

Dostawcy modeli

Śledzenie użycia

​Pierwsze kroki

​Zarządzane wdrożenie nieinteraktywne

​Gotowość i weryfikacja na żywo

​Wykrywanie modeli

​Protokoły i Pluginy dostawców

​Limity i użycie

​Rozwiązywanie problemów

​Zachowanie zabezpieczeń

​Powiązane materiały

Dostawcy modeli

Śledzenie użycia

Pierwsze kroki

Zarządzane wdrożenie nieinteraktywne

Gotowość i weryfikacja na żywo

Wykrywanie modeli

Protokoły i Pluginy dostawców

Limity i użycie

Rozwiązywanie problemów

Zachowanie zabezpieczeń

Powiązane materiały