ClawRouter

ClawRouter stellt OpenClaw einen richtliniengebundenen Schlüssel für mehrere vorgelagerte Modell- Provider bereit. Das mitgelieferte Plugin clawrouter erkennt nur die für diesen Schlüssel zugelassenen Modelle, leitet jedes Modell über sein deklariertes Protokoll weiter und meldet das Budget des Schlüssels sowie die aggregierte Nutzung auf den OpenClaw-Nutzungsoberflächen.

Vorgelagerte Zugangsdaten und providerspezifische Weiterleitungen verbleiben in ClawRouter, sodass Sie niemals die Plugins der einzelnen vorgelagerten Provider auf dem OpenClaw-Host installieren oder authentifizieren müssen. Das Plugin wird mit OpenClaw mitgeliefert (enabledByDefault: true); Sie benötigen lediglich ausgestellte ClawRouter-Zugangsdaten.

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 ausschließlich eine SecretRef. Die kanonischen verwalteten Felder sind:

Beispielsweise kann ein Bereitstellungscontroller diesen JSON5-Patch verwalten:

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

Falls die Bereitstellung plugins.allow festlegt, behalten Sie die vorhandenen Einträge bei und fügen Sie clawrouter hinzu. Validieren und übernehmen Sie den Patch 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 Zugangsdaten 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.

Bei einem aus dem Quellcode erstellten eigenständigen 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; Zugangsdaten und vorgelagerte Modelle werden nicht geprüft.curl -fsS https://clawrouter.internal.example/v1/health # Nur Startbereitschaft des OpenClaw-Gateways; es wird kein Modellaufruf durchgeführt.curl -fsS http://127.0.0.1:18789/readyz # Zugangsdatengebundene Katalogerkennung.openclaw models list --all --provider clawrouter --json # Minimale echte Inferenzprüfung über den konfigurierten ClawRouter-Provider.openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json # Workload-Canary mit einer exakt 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, statt das Beispielmodell blind zu übernehmen. Eine erfolgreiche /readyz-Antwort bedeutet, dass das Gateway Anfragen bedienen kann; sie besagt nicht, dass ClawRouter, seine Zugangsdaten oder ein vorgelagerter Provider bereit sind. Die Modellprüfung und der Agent-Canary sind die Inferenznachweise.

Führen Sie zur Live-Diagnose den Canary aus und prüfen Sie die Standardprotokolle des Gateways. Die vorhandenen, ausschließlich metadatenbasierten Modelltransportdiagnosen erzeugen Zeilen wie:

[model-fetch] Start provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses[model-fetch] Antwort provider=clawrouter api=openai-responses model=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 Kennungen verfügbar sind. Es ordnet außerdem die diagnostische callId (<run-id>:model:<n>) des Modellaufrufs X-Request-ID zu, sodass ein OpenClaw-Modellaufrufereignis mit dem ausschließlich metadatenbasierten Audit-Trail von ClawRouter verknüpft werden kann. Werte innerhalb des 128-Zeichen-Budgets für Anforderungs-IDs sind identisch. Bei längeren Werten bleiben das Suffix :model:<n> und ein deterministischer Hash erhalten, sodass verschiedene Aufrufe begrenzt und verknüpfbar bleiben. Statische Bereitstellungsmetadaten wie X-ClawRouter-Project-Id können in der Provider-Zuordnung headers festgelegt werden. Header zur Agent- und Sitzungszuordnung behalten ihr separates Limit von 256 Zeichen. Automatische Anforderungs-IDs, die Zeichen außerhalb des ASCII-Kennungssatzes von ClawRouter enthalten, verwenden dieselbe deterministische begrenzte Form. Explizit konfigurierte Header, einschließlich jeder Groß-/Kleinschreibungsvariante von X-Request-ID, haben Vorrang vor automatischen Werten. Die Transportdiagnose zeichnet Routing- und Antwortmetadaten auf; sie protokolliert weder Zugangsdaten noch Anforderungs-IDs, Prompts oder Ausgaben. Das eigene Audit-Ereignis von ClawRouter liefert den ausgewählten vorgelagerten Provider und den Zustand der Inhaltsaufbewahrung.

Modellerkennung

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

• die Richtlinie der Zugangsdaten seinen Provider freigibt;
• das Katalogmodell eine unterstützte LLM-Funktion 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 nachstehenden Transporte bereitstellt.

Das Hinzufügen eines Modells zu einem unterstützten ClawRouter-Provider erfordert keine OpenClaw-Veröffentlichung: Bei der nächsten Katalogaktualisierung (60 Sekunden pro Zugangsdatenbereich 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 Zugangsdaten; sein Katalog teilt OpenClaw mit, welcher Transport verwendet werden 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 Werkzeugschemas für diese Familien an (Werkzeugschema-Kompatibilität für OpenAI/DeepSeek/Gemini/Perplexity; native Replay-Richtlinien von Anthropic und Google Gemini). Perplexity-Modelle erhalten eine strikte Schemaumschreibung: patternProperties und additionalProperties werden entfernt und jedes Objektschema deklariert properties, da Perplexity Werkzeugschemas ohne diese Angaben ablehnt. Ein Katalog-Provider, der ausschließlich ein nicht unterstütztes Anfrageformat bereitstellt, wird absichtlich nicht als OpenClaw- Textmodell angeboten. Normalisieren Sie diese Provider in ClawRouter auf einen der unterstützten Verträge, statt eine inkompatible Nutzlast zu senden.

Kontingente und Nutzung

Die Antwort /v1/usage von ClawRouter speist die normalen OpenClaw-Oberflächen zur Provider-Nutzung: Summen für Anfragen, Token und Ausgaben sowie ein monatliches Budgetfenster, wenn der Schlüssel ein Limit besitzt. Schlüssel ohne Mengenbegrenzung zeigen weiterhin die aggregierte Nutzung ohne Prozentfenster an.

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

Prüfen Sie den Live-Snapshot mit:

openclaw status --usageopenclaw models status

Derselbe Provider-Snapshot ist für /status im Chat und in der Nutzungsoberfläche von OpenClaw verfügbar. Das Budget gilt für die gesamte Richtlinie; daher können Anfragen eines anderen Clients, der dieselbe ClawRouter-Richtlinie verwendet, den verbleibenden Prozentsatz ändern.

Fehlerbehebung

Sicherheitsverhalten

• Die Katalogermittlung ist auf den konfigurierten Proxy-Schlüssel beschränkt und wird pro Anmeldedatenbereich (Agent-Verzeichnis, Workspace-Verzeichnis, Authentifizierungsprofil-ID und Basis-URL) zwischengespeichert.
• 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 gekürzt und bei enthaltenen Steuerzeichen abgelehnt. Zuordnungswerte sind auf 256 Zeichen begrenzt; Anfrage-IDs auf 128.
• Diagnosedaten zum Modelltransport 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 standardmäßig abgelehnt und können nicht ausgewählt werden.

Verwandte Themen