ClawRouter

ClawRouter stellt OpenClaw einen richtliniengebundenen Schlüssel für mehrere vorgelagerte Modell- Provider bereit. Das gebündelte Plugin clawrouter erkennt nur die für diesen Schlüssel zulässigen Modelle, leitet jedes Modell über sein deklariertes Protokoll weiter und zeigt das Budget des Schlüssels sowie die aggregierte Nutzung in den OpenClaw-Nutzungsansichten an.

Vorgelagerte Anmeldedaten und providerspezifische Weiterleitungen verbleiben in ClawRouter, sodass Sie nicht jedes vorgelagerte Provider-Plugin auf dem OpenClaw-Host installieren oder authentifizieren müssen. Das Plugin wird gebündelt mit OpenClaw ausgeliefert (enabledByDefault: true); Sie benötigen lediglich von ClawRouter ausgestellte Anmeldedaten.

Erste Schritte

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>

Verwaltete nicht interaktive Bereitstellung

Bewahren Sie den Proxy-Schlüssel in der Secret-Einspeisung der Workload auf und speichern Sie in openclaw.json nur eine SecretRef. Die kanonischen verwalteten Felder sind:

Beispielsweise kann ein Bereitstellungscontroller Eigentümer dieses JSON5-Patches sein:

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

Wenn die Bereitstellung plugins.allow festlegt, behalten Sie die vorhandenen Einträge bei und fügen Sie clawrouter hinzu. Validieren und übernehmen Sie die Konfiguration ohne interaktiven Assistenten:

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

Der Probelauf löst die SecretRef auf, gibt ihren Wert jedoch niemals aus. Um die Anmeldedaten zu rotieren, aktualisieren Sie das externe Secret, das CLAWROUTER_API_KEY bereitstellt, und starten Sie die Gateway-Workload neu, damit die neue Prozessumgebung geladen wird. Die Konfigurationsdatei und die Modellreferenz ändern sich nicht.

Für ein aus dem Quellcode erstelltes eigenständiges Docker-Gateway ist ClawRouter bereits in der Root-Laufzeit enthalten. Wählen Sie nur das Kanal-Plugin aus, das separat paketiert werden muss, beispielsweise OPENCLAW_EXTENSIONS=clickclack, slack oder msteams; siehe aus dem Quellcode erstellte Images mit ausgewählten Plugins. Archiv-/Appliance-Bereitstellungen müssen denselben übernommenen Quellcode über ihre eigene Artefakt-Pipeline paketieren, statt das OCI-Image zu verwenden.

Bereitschaft und Live-Nachweis

Diese Prüfungen weisen unterschiedliche Grenzen nach; ersetzen Sie keine durch eine andere:

# Nur Prozesszustand von ClawRouter; weder Anmeldedaten noch ein vorgelagertes Modell werden verwendet.curl -fsS https://clawrouter.internal.example/v1/health # Nur Startbereitschaft des OpenClaw-Gateways; es erfolgt kein Modellaufruf.curl -fsS http://127.0.0.1:18789/readyz # Anmeldedatengebundene Katalogerkennung.openclaw models list --all --provider clawrouter --json # Minimaler echter Inferenztest über den konfigurierten ClawRouter-Provider.openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json # Workload-Canary mit einer exakten freigegebenen Modellreferenz.openclaw agent --agent main \  --model clawrouter/openai/gpt-5.5 \  --message "Antworten Sie exakt: CLAWROUTER_CANARY_OK" \  --json

Verwenden Sie ein vom richtliniengebundenen Katalog zurückgegebenes Modell, anstatt das Beispielmodell blind zu kopieren. Eine erfolgreiche /readyz-Antwort bedeutet, dass das Gateway Anfragen verarbeiten kann; sie besagt nicht, dass ClawRouter, seine Anmeldedaten oder ein vorgelagerter Provider bereit sind. Der Modelltest und der Agent-Canary sind die Inferenznachweise.

Führen Sie für eine Live-Diagnose den Canary aus und prüfen Sie die Standardprotokolle des Gateways. Die vorhandene, ausschließlich Metadaten erfassende Modelltransportdiagnose gibt Zeilen in folgender Form aus:

[model-fetch] Start Provider=clawrouter API=openai-responses Modell=openai/gpt-5.5 Methode=POST URL=https://clawrouter.internal.example/v1/responses[model-fetch] Antwort Provider=clawrouter API=openai-responses Modell=openai/gpt-5.5 Status=200

Das Plugin sendet begrenzte Header X-ClawRouter-Client, X-ClawRouter-Agent-Id und X-ClawRouter-Session-Id, wenn diese Bezeichner verfügbar sind. Außerdem ordnet es die diagnostische callId des Modellaufrufs (<run-id>:model:<n>) X-Request-ID zu, sodass ein OpenClaw-Modellaufrufereignis mit dem ausschließlich Metadaten enthaltenden Audit-Trail von ClawRouter verknüpft werden kann. Werte innerhalb des Budgets von 128 Zeichen für die Anfrage-ID sind identisch. Längere Werte behalten das Suffix :model:<n> und einen deterministischen Hash bei, sodass verschiedene Aufrufe begrenzt und verknüpfbar bleiben. Statische Bereitstellungsmetadaten wie X-ClawRouter-Project-Id können in der Provider-Map headers festgelegt werden. Header zur Agent- und Sitzungszuordnung behalten ihre separate Grenze von 256 Zeichen bei. Automatische Anfrage-IDs mit Zeichen außerhalb des ASCII-Bezeichnersatzes von ClawRouter verwenden dieselbe deterministische, begrenzte Form. Explizit konfigurierte Header, einschließlich aller Varianten der Groß-/Kleinschreibung von X-Request-ID, haben Vorrang vor automatischen Werten. Die Transportdiagnose zeichnet Routing- und Antwortmetadaten auf; sie protokolliert weder Anmeldedaten, Anfrage-IDs, Prompts noch Vervollständigungen. Das eigene Audit-Ereignis von ClawRouter stellt den ausgewählten vorgelagerten Provider und den Zustand der Inhaltsaufbewahrung bereit.

Modellerkennung

GET /v1/catalog gibt { providers: [...] } zurück, wobei jeder Provider-Eintrag seine eigenen models[] (mit vorgelagerter ID, Fähigkeiten und Preisen) sowie seine unterstützten Anfragerouten auflistet. OpenClaw liefert keine zweite, feste Liste von ClawRouter-Modellen aus. Ein Katalogmodell wird als OpenClaw-Modell angeboten, wenn:

• die Richtlinie der Anmeldedaten seinen Provider freigibt;
• das Katalogmodell eine unterstützte LLM-Fähigkeit angibt (llm.responses, llm.chat, llm.messages oder llm.stream mit einer passenden Streaming- Route); und
• der Provider eine passende Route für einen der folgenden Transporte bereitstellt.

Das Hinzufügen eines Modells zu einem unterstützten ClawRouter-Provider erfordert keine OpenClaw-Version: Bei der nächsten Katalogaktualisierung (60 Sekunden pro Anmeldedatenbereich zwischengespeichert) wird es erkannt. Ein Modell, das ein neues Übertragungsprotokoll benötigt, erfordert zunächst Unterstützung durch das Plugin.

Protokoll- und Provider-Plugins

ClawRouter verwaltet die vorgelagerten Anmeldedaten; sein Katalog teilt OpenClaw mit, welchen Transport es verwenden soll, sodass Sie nicht das Authentifizierungs-Plugin jedes vorgelagerten Unternehmens installieren müssen.

Das Plugin wendet außerdem die passenden Richtlinien für Replay und Tool-Schemas für diese Familien an (Tool-Schema-Kompatibilität für OpenAI/DeepSeek/Gemini; native Replay-Richtlinien für Anthropic und Google Gemini). Ein Katalog-Provider, der nur ein nicht unterstütztes Anfrageformat bereitstellt, wird absichtlich nicht als OpenClaw- Textmodell angeboten. Normalisieren Sie solche Provider in ClawRouter auf einen der unterstützten Verträge, anstatt eine inkompatible Nutzlast zu senden.

Kontingente und Nutzung

Die Antwort von ClawRouter unter /v1/usage speist die normalen OpenClaw-Ansichten für die Provider-Nutzung: Gesamtwerte für Anfragen, Token und Ausgaben sowie ein monatliches Budgetfenster, wenn der Schlüssel eine Begrenzung hat. Schlüssel ohne Verbrauchsmessung zeigen weiterhin die aggregierte Nutzung ohne ein Prozentfenster an.

Die Kontingentabfrage verwendet denselben richtliniengebundenen Schlüssel wie die Modellerkennung. Eine fehlgeschlagene Kontingentabfrage blockiert die Modellausführung nicht.

Prüfen Sie die Live-Momentaufnahme mit:

openclaw status --usageopenclaw models status

Dieselbe Provider-Momentaufnahme steht /status im Chat und der Nutzungsoberfläche von OpenClaw zur Verfügung. Das Budget gilt richtlinienweit, sodass Anfragen eines anderen Clients, der dieselbe ClawRouter-Richtlinie verwendet, den verbleibenden Prozentsatz verändern können.

Fehlerbehebung

Sicherheitsverhalten

• Die Katalogerkennung ist auf den konfigurierten Proxy-Schlüssel beschränkt und wird pro Anmeldedatenbereich zwischengespeichert (Agent-Verzeichnis, Workspace-Verzeichnis, Authentifizierungsprofil-ID und Basis-URL).
• Der Proxy-Schlüssel wird erst beim Senden der Anfrage angefügt; er wird nicht in den Modellmetadaten gespeichert.
• Werte für die automatische Zuordnung und Anfragekorrelation werden vor dem Senden von Leerzeichen bereinigt und bei enthaltenen Steuerzeichen abgelehnt. Zuordnungswerte sind auf 256 Zeichen begrenzt, Anfrage-IDs auf 128.
• Modelltransportdiagnosen enthalten ausschließlich Metadaten und niemals den Proxy-Schlüssel oder Modellinhalte.
• Native Anthropic- und Gemini-Modell-IDs werden erst beim Senden in ihre Upstream-IDs umgeschrieben.
• Nicht unterstützte oder nicht freigegebene Katalogeinträge werden nach dem Fail-Closed-Prinzip abgelehnt und können nicht ausgewählt werden.

Verwandte Themen