ClawRouter

ClawRouter geeft OpenClaw één beleidsspecifieke sleutel voor meerdere upstreammodelproviders. De gebundelde Plugin clawrouter detecteert alleen de modellen die voor die sleutel zijn toegestaan, routeert elk model via het opgegeven protocol en rapporteert het budget en het totale gebruik van de sleutel in de gebruiksoverzichten van OpenClaw.

Upstreamreferenties en providerspecifieke doorsturing blijven in ClawRouter, zodat je nooit elke upstreamprovider-Plugin op de OpenClaw-host hoeft te installeren of te authenticeren. De Plugin wordt gebundeld met OpenClaw geleverd (enabledByDefault: true); je hebt alleen een uitgegeven ClawRouter-referentie nodig.

Aan de slag

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>

Beheerde niet-interactieve implementatie

Bewaar de proxysleutel in de geheime-injectie van de workload en sla in openclaw.json alleen een SecretRef op. De canonieke beheerde velden zijn:

Een implementatiecontroller kan bijvoorbeeld deze JSON5-patch beheren:

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

Als de implementatie plugins.allow instelt, behoud je de bestaande vermeldingen en voeg je clawrouter toe. Valideer en pas toe zonder interactieve wizard:

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

De proefuitvoering lost de SecretRef op, maar drukt de waarde nooit af. Om de referentie te roteren, werk je de externe Secret bij die CLAWROUTER_API_KEY levert en start je de Gateway-workload opnieuw, zodat de nieuwe procesomgeving wordt geladen. Het configuratiebestand en de modelreferentie veranderen niet.

Voor een zelfstandig vanuit broncode gebouwde Docker-Gateway is ClawRouter al opgenomen in de root-runtime. Selecteer alleen de kanaal-Plugin waarvoor aparte verpakking nodig is, zoals OPENCLAW_EXTENSIONS=clickclack, slack of msteams; zie vanuit broncode gebouwde images met geselecteerde Plugins. Archief-/appliance-implementaties moeten dezelfde opgenomen broncode via hun eigen artefactpijplijn verpakken in plaats van de OCI-image te gebruiken.

Gereedheid en live bewijs

Deze controles bewijzen verschillende grenzen; vervang de ene niet door de andere:

# Alleen de status van het ClawRouter-proces; er wordt geen referentie of upstreammodel gebruikt.curl -fsS https://clawrouter.internal.example/v1/health # Alleen de opstartgereedheid van de OpenClaw-Gateway; er wordt geen modelaanroep uitgevoerd.curl -fsS http://127.0.0.1:18789/readyz # Referentiespecifieke catalogusdetectie.openclaw models list --all --provider clawrouter --json # Minimale echte inferentieprobe via de geconfigureerde ClawRouter-provider.openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json # Workload-canary met een exacte toegekende modelreferentie.openclaw agent --agent main \  --model clawrouter/openai/gpt-5.5 \  --message "Antwoord exact: CLAWROUTER_CANARY_OK" \  --json

Gebruik een model dat door de specifieke catalogus wordt geretourneerd in plaats van het voorbeeldmodel klakkeloos te kopiëren. Een geslaagd /readyz-antwoord betekent dat de Gateway aanvragen kan verwerken; het bewijst niet dat ClawRouter, de bijbehorende referentie of een upstreamprovider gereed is. De modelprobe en agent-canary vormen het inferentiebewijs.

Voer voor live diagnostiek de canary uit en inspecteer de standaardlogs van de Gateway. De bestaande diagnostiek voor modeltransport met alleen metadata produceert regels met de volgende vorm:

[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

De Plugin verzendt begrensde headers X-ClawRouter-Client, X-ClawRouter-Agent-Id en X-ClawRouter-Session-Id wanneer die identificatoren beschikbaar zijn. De Plugin koppelt ook de diagnostische callId (<run-id>:model:<n>) van de modelaanroep aan X-Request-ID, zodat een modelaanroepgebeurtenis van OpenClaw kan worden gekoppeld aan het auditspoor van ClawRouter dat alleen metadata bevat. Waarden binnen het budget van 128 tekens voor de aanvraag-ID zijn identiek. Langere waarden behouden het achtervoegsel :model:<n> en een deterministische hash, zodat afzonderlijke aanroepen begrensd en koppelbaar blijven. Statische implementatiemetadata zoals X-ClawRouter-Project-Id kunnen worden ingesteld in de provider-map headers. Headers voor agent- en sessietoeschrijving behouden hun afzonderlijke limiet van 256 tekens. Automatische aanvraag-ID's met tekens buiten de ASCII-identificatorenset van ClawRouter gebruiken dezelfde deterministische begrensde vorm. Expliciet geconfigureerde headers, inclusief elke variant in hoofdlettergebruik van X-Request-ID, hebben voorrang op automatische waarden. De transportdiagnostiek registreert routerings- en antwoordmetadata; deze logt geen referenties, aanvraag-ID's, prompts of voltooiingen. De eigen auditgebeurtenis van ClawRouter bevat de geselecteerde upstreamprovider en de status voor het bewaren van inhoud.

Modeldetectie

GET /v1/catalog retourneert { providers: [...] }, waarbij elke providervermelding de eigen models[] vermeldt (met upstream-ID, mogelijkheden en prijzen) en de ondersteunde aanvraagroutes. OpenClaw levert geen tweede, vaste lijst met ClawRouter-modellen. Een catalogusmodel wordt als OpenClaw-model aangeboden wanneer:

• het beleid van de referentie de provider ervan toestaat;
• het catalogusmodel een ondersteunde LLM-mogelijkheid aankondigt (llm.responses, llm.chat, llm.messages of llm.stream met een overeenkomende streamingroute); en
• de provider een overeenkomende route beschikbaar stelt voor een van de onderstaande transporten.

Voor het toevoegen van een model aan een ondersteunde ClawRouter-provider is geen OpenClaw-release nodig: de volgende catalogusvernieuwing (60 seconden per referentiebereik in de cache) detecteert het. Voor een model waarvoor een nieuw wire-protocol nodig is, moet eerst ondersteuning aan de Plugin worden toegevoegd.

Protocol- en provider-Plugins

ClawRouter beheert upstreamreferenties; de catalogus vertelt OpenClaw welk transport moet worden gebruikt, zodat je nooit de authenticatie-Plugin van elk upstreambedrijf hoeft te installeren.

De Plugin past ook het bijbehorende beleid voor opnieuw afspelen en toolschema's toe op die families (compatibiliteit van toolschema's voor OpenAI/DeepSeek/Gemini/Perplexity; native beleid voor opnieuw afspelen van Anthropic en Google Gemini). Perplexity-modellen krijgen een strikte schemaherschrijving: patternProperties en additionalProperties worden verwijderd en elk objectschema declareert properties, omdat Perplexity toolschema's zonder deze declaraties afwijst. Een catalogusprovider die alleen een niet-ondersteunde aanvraagindeling beschikbaar stelt, wordt bewust niet aangeboden als OpenClaw-tekstmodel. Normaliseer die providers in ClawRouter naar een van de ondersteunde contracten in plaats van een incompatibele payload te verzenden.

Quota's en gebruik

Het antwoord /v1/usage van ClawRouter voedt de normale providergebruiksweergaven van OpenClaw: totalen voor aanvragen, tokens en uitgaven, plus een maandbudgetvenster wanneer de sleutel een limiet heeft. Sleutels zonder meting tonen nog steeds het totale gebruik, maar zonder percentagevenster.

Bij het opzoeken van quota's wordt dezelfde specifieke sleutel gebruikt als bij modeldetectie. Een mislukte quotaopzoeking blokkeert de modeluitvoering niet.

Controleer de live momentopname met:

openclaw status --usageopenclaw models status

Dezelfde providermomentopname is beschikbaar voor /status in de chat en in de gebruiksinterface van OpenClaw. Het budget geldt voor het hele beleid, dus aanvragen van een andere client die hetzelfde ClawRouter-beleid gebruikt, kunnen het resterende percentage veranderen.

Probleemoplossing

Beveiligingsgedrag

• Catalogusdetectie is beperkt tot de geconfigureerde proxysleutel en wordt per referentiebereik in de cache opgeslagen (agentmap, werkruimtemap, authenticatieprofiel-id en basis-URL).
• De proxysleutel wordt alleen bij het verzenden van de aanvraag toegevoegd; deze wordt niet opgeslagen in de modelmetadata.
• Waarden voor automatische toeschrijving en aanvraagcorrelatie worden vóór verzending ontdaan van witruimte en bij controletekens geweigerd. Toeschrijvingswaarden zijn beperkt tot 256 tekens; aanvraag-id's tot 128.
• Diagnostische gegevens over het modeltransport bevatten alleen metadata en nooit de proxysleutel of modelinhoud.
• Model-id's van native Anthropic- en Gemini-modellen worden alleen bij verzending herschreven naar hun upstream-id's.
• Niet-ondersteunde catalogusrijen of catalogusrijen waarvoor geen toestemming is verleend, worden standaard geweigerd en kunnen niet worden geselecteerd.

Gerelateerd