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 zagregowane użycie w interfejsach użycia OpenClaw.

Nadrzędne dane uwierzytelniające i przekazywanie specyficzne dla dostawców pozostają w ClawRouter, dlatego na hoście OpenClaw nie trzeba instalować ani uwierzytelniać pluginu każdego nadrzędnego dostawcy. Plugin jest dołączony do OpenClaw (enabledByDefault: true); potrzebujesz jedynie wydanych danych uwierzytelniających ClawRouter.

Pierwsze kroki

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

openclaw models list --all --provider clawrouter

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

Zarządzane wdrożenie nieinteraktywne

Przechowuj klucz proxy w mechanizmie wstrzykiwania sekretów obciążenia, a w openclaw.json zapisuj wyłącznie SecretRef. Kanoniczne pola zarządzane to:

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, zachowaj istniejące wpisy i dodaj clawrouter. Zweryfikuj i zastosuj bez interaktywnego kreatora:

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

Przebieg próbny rozwiązuje SecretRef, ale nigdy nie wyświetla jego wartości. Aby zmienić dane uwierzytelniające, zaktualizuj zewnętrzny Secret dostarczający CLAWROUTER_API_KEY i uruchom ponownie obciążenie Gateway, aby wczytać nowe środowisko procesu. Plik konfiguracyjny i odwołanie do modelu pozostają bez zmian.

W przypadku samodzielnego Gateway Docker zbudowanego ze źródeł ClawRouter jest już zawarty w głównym środowisku uruchomieniowym. Wybierz tylko plugin kanału wymagający osobnego pakowania, na przykład OPENCLAW_EXTENSIONS=clickclack, slack lub msteams; zobacz obrazy zbudowane ze źródeł z wybranymi pluginami. Wdrożenia archiwalne i urządzeniowe muszą pakować ten sam włączony kod źródłowy we własnym potoku artefaktów zamiast korzystać z obrazu OCI.

Gotowość i weryfikacja na żywo

Te kontrole potwierdzają różne granice; nie zastępuj jednej drugą:

# Wyłącznie kondycja procesu ClawRouter; dane uwierzytelniające ani nadrzędny model nie są sprawdzane.curl -fsS https://clawrouter.internal.example/v1/health # Wyłącznie gotowość uruchomienia Gateway OpenClaw; wywołanie modelu nie jest wykonywane.curl -fsS http://127.0.0.1:18789/readyz # Wykrywanie katalogu ograniczonego zakresem danych uwierzytelniających.openclaw models list --all --provider clawrouter --json # Minimalna rzeczywista próba wnioskowania przez skonfigurowanego dostawcę ClawRouter.openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json # Test kanarkowy obciążenia z użyciem dokładnego przyznanego odwołania do modelu.openclaw agent --agent main \  --model clawrouter/openai/gpt-5.5 \  --message "Reply exactly: CLAWROUTER_CANARY_OK" \  --json

Użyj 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 gotowości ClawRouter, jego danych uwierzytelniających ani nadrzędnego dostawcy. Próba modelu i test kanarkowy agenta stanowią weryfikację wnioskowania.

Aby przeprowadzić diagnostykę na żywo, uruchom test kanarkowy i sprawdź standardowe dzienniki Gateway. Istniejące diagnostyki transportu modelu, zawierające wyłącznie metadane, generują wiersze w postaci:

[model-fetch] start provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses[model-fetch] response 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. Mapuje również diagnostyczny callId wywołania modelu (<run-id>:model:<n>) na X-Request-ID, dzięki czemu zdarzenie wywołania modelu OpenClaw można powiązać ze ścieżką audytu ClawRouter zawierają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> i deterministyczny skrót, dzięki czemu odrębne 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 przypisania agenta i sesji zachowują osobny 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 zapisuje danych uwierzytelniających, identyfikatorów żądań, promptów ani ukończonych odpowiedzi. Własne zdarzenie audytu ClawRouter udostępnia wybranego nadrzędnego dostawcę i stan przechowywania treści.

Wykrywanie modeli

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

• zasady danych uwierzytelniających 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ą strumieniową); 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: następne odświeżenie katalogu (buforowanego przez 60 sekund dla każdego zakresu danych uwierzytelniających) wykryje go. Model wymagający nowego protokołu komunikacji wymaga najpierw obsługi przez plugin.

Protokoły i pluginy dostawców

ClawRouter zarządza nadrzędnymi danymi uwierzytelniającymi; jego katalog informuje OpenClaw, którego transportu użyć, dzięki czemu nie trzeba instalować pluginu uwierzytelniania każdej nadrzędnej firmy.

Plugin stosuje również odpowiednie zasady odtwarzania i schematów narzędzi dla tych rodzin (zgodność schematów narzędzi OpenAI/DeepSeek/Gemini; natywne zasady odtwarzania Anthropic i Google Gemini). Dostawca katalogowy udostępniający wyłącznie nieobsługiwany format żądań celowo nie jest przedstawiany jako model tekstowy OpenClaw. Normalizuj takich dostawców do jednego z obsługiwanych kontraktów w ClawRouter zamiast wysyłać niezgodny ładunek.

Limity i użycie

Odpowiedź /v1/usage ClawRouter zasila standardowe interfejsy użycia dostawcy OpenClaw: sumy żądań, tokenów i wydatków, a także miesięczne okno budżetowe, gdy klucz ma określony limit. Klucze bez limitu nadal pokazują zagregowane użycie bez okna procentowego.

Wyszukiwanie limitu używa tego samego klucza o określonym zakresie co wykrywanie modeli. Nieudane wyszukiwanie limitu nie blokuje wykonywania modelu.

Sprawdź bieżący obraz stanu za pomocą:

openclaw status --usageopenclaw models status

Ten sam obraz stanu dostawcy jest dostępny dla /status na czacie oraz w interfejsie użycia OpenClaw. Budżet obowiązuje dla całych zasad, więc żądania wykonane przez innego klienta korzystającego z tych samych zasad ClawRouter mogą zmienić pozostałą wartość procentową.

Rozwiązywanie problemów

Zachowanie zabezpieczeń

• Wykrywanie katalogu jest ograniczone do skonfigurowanego klucza proxy i buforowane osobno dla każdego zakresu poświadczeń (katalogu agenta, katalogu obszaru roboczego, identyfikatora profilu uwierzytelniania i bazowego adresu URL).
• Klucz proxy jest dołączany wyłącznie podczas wysyłania żądania; nie jest przechowywany w metadanych modelu.
• Wartości automatycznego przypisania autorstwa i korelacji żądań są przed wysłaniem przycinane, a wartości zawierające znaki sterujące są odrzucane. Wartości przypisania autorstwa są ograniczone do 256 znaków, a identyfikatory żądań — do 128.
• Diagnostyka transportu modelu zawiera wyłącznie metadane i nigdy nie obejmuje klucza proxy ani treści modelu.
• Natywne identyfikatory modeli Anthropic i Gemini są zamieniane na ich identyfikatory nadrzędne wyłącznie podczas wysyłania żądania.
• Nieobsługiwane lub nieprzyznane pozycje katalogu są domyślnie odrzucane i nie można ich wybrać.

Powiązane