ClawRouter

ClawRouter fornisce a OpenClaw un'unica chiave con ambito definito da criteri per più provider di modelli upstream. Il plugin clawrouter incluso rileva solo i modelli consentiti per tale chiave, instrada ciascun modello tramite il protocollo dichiarato e riporta il budget della chiave e l'utilizzo aggregato nelle superfici di utilizzo di OpenClaw.

Le credenziali upstream e l'inoltro specifico per provider rimangono in ClawRouter, quindi non è mai necessario installare o autenticare ogni plugin del provider upstream sull'host OpenClaw. Il plugin è incluso con OpenClaw (enabledByDefault: true); serve solo una credenziale ClawRouter emessa.

Per iniziare

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>

Distribuzione gestita non interattiva

Conservare la chiave del proxy nel sistema di inserimento dei segreti del carico di lavoro e archiviare solo un SecretRef in openclaw.json. I campi gestiti canonici sono:

Ad esempio, un controller di distribuzione può gestire questa patch 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" },    },  },}

Se la distribuzione imposta plugins.allow, conservarne le voci esistenti e aggiungere clawrouter. Convalidare e applicare senza una procedura guidata interattiva:

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

L'esecuzione di prova risolve il SecretRef, ma non ne stampa mai il valore. Per ruotare la credenziale, aggiornare il Secret esterno che fornisce CLAWROUTER_API_KEY e riavviare il carico di lavoro del Gateway affinché venga caricato il nuovo ambiente del processo. Il file di configurazione e il riferimento del modello non cambiano.

Per un Gateway Docker autonomo compilato dal sorgente, ClawRouter è già incluso nel runtime radice. Selezionare solo il plugin del canale che richiede una pacchettizzazione separata, come OPENCLAW_EXTENSIONS=clickclack, slack o msteams; vedere immagini compilate dal sorgente con plugin selezionati. Le distribuzioni di tipo archivio/appliance devono creare il pacchetto dallo stesso sorgente integrato tramite la propria pipeline degli artefatti, anziché utilizzare l'immagine OCI.

Disponibilità e verifica in tempo reale

Questi controlli verificano limiti diversi; non sostituirne uno con un altro:

# Solo integrità del processo ClawRouter; non viene usata alcuna credenziale né alcun modello upstream.curl -fsS https://clawrouter.internal.example/v1/health # Solo disponibilità all'avvio del Gateway OpenClaw; non viene effettuata alcuna chiamata a un modello.curl -fsS http://127.0.0.1:18789/readyz # Rilevamento del catalogo con ambito definito dalla credenziale.openclaw models list --all --provider clawrouter --json # Sonda minima di inferenza reale tramite il provider ClawRouter configurato.openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json # Canary del carico di lavoro mediante un riferimento esatto a un modello concesso.openclaw agent --agent main \  --model clawrouter/openai/gpt-5.5 \  --message "Rispondi esattamente: CLAWROUTER_CANARY_OK" \  --json

Utilizzare un modello restituito dal catalogo con ambito definito anziché copiare senza verifiche il modello di esempio. Una risposta /readyz riuscita indica che il Gateway può gestire le richieste; non garantisce che ClawRouter, la relativa credenziale o un provider upstream siano pronti. La sonda del modello e il canary dell'agente costituiscono le verifiche dell'inferenza.

Per la diagnosi in tempo reale, eseguire il canary e consultare i log standard del Gateway. La diagnostica esistente, limitata ai metadati, del trasporto del modello genera righe con una struttura simile alla seguente:

[model-fetch] avvio provider=clawrouter api=openai-responses model=openai/gpt-5.5 metodo=POST url=https://clawrouter.internal.example/v1/responses[model-fetch] risposta provider=clawrouter api=openai-responses model=openai/gpt-5.5 stato=200

Il plugin invia gli header limitati X-ClawRouter-Client, X-ClawRouter-Agent-Id e X-ClawRouter-Session-Id quando tali identificatori sono disponibili. Inoltre, associa il valore diagnostico callId (<run-id>:model:<n>) della chiamata al modello a X-Request-ID, in modo che un evento di chiamata al modello OpenClaw possa essere correlato alla traccia di controllo di ClawRouter limitata ai metadati. I valori che rientrano nel limite di 128 caratteri per l'ID richiesta sono identici. I valori più lunghi mantengono il suffisso :model:<n> e un hash deterministico, in modo che le chiamate distinte rimangano limitate e correlabili. I metadati statici della distribuzione, come X-ClawRouter-Project-Id, possono essere impostati nella mappa headers del provider. Gli header di attribuzione dell'agente e della sessione mantengono il proprio limite separato di 256 caratteri. Gli ID richiesta automatici contenenti caratteri non inclusi nell'insieme di identificatori ASCII di ClawRouter usano la stessa forma deterministica e limitata. Gli header configurati esplicitamente, incluse tutte le varianti di maiuscole e minuscole di X-Request-ID, prevalgono sui valori automatici. La diagnostica del trasporto registra i metadati di instradamento e risposta, ma non registra credenziali, ID richiesta, prompt o completamenti. L'evento di controllo di ClawRouter fornisce il provider upstream selezionato e lo stato di conservazione dei contenuti.

Rilevamento dei modelli

GET /v1/catalog restituisce { providers: [...] }, dove ogni voce del provider elenca i propri models[] (con ID upstream, funzionalità e prezzi) e le route di richiesta supportate. OpenClaw non include un secondo elenco fisso di modelli ClawRouter. Un modello del catalogo viene presentato come modello OpenClaw quando:

• i criteri della credenziale concedono il relativo provider;
• il modello del catalogo dichiara una funzionalità LLM supportata (llm.responses, llm.chat, llm.messages o llm.stream con una route di streaming corrispondente); e
• il provider espone una route corrispondente per uno dei trasporti seguenti.

L'aggiunta di un modello a un provider ClawRouter supportato non richiede alcuna versione di OpenClaw: il successivo aggiornamento del catalogo, memorizzato nella cache per 60 secondi per ambito della credenziale, lo rileva. Un modello che richiede un nuovo protocollo di comunicazione necessita prima del supporto del plugin.

Plugin di protocollo e provider

ClawRouter gestisce le credenziali upstream; il suo catalogo indica a OpenClaw quale trasporto utilizzare, quindi non è mai necessario installare il plugin di autenticazione di ogni azienda upstream.

Il plugin applica inoltre i criteri di riproduzione e dello schema degli strumenti corrispondenti per tali famiglie (compatibilità dello schema degli strumenti OpenAI/DeepSeek/Gemini/Perplexity; criteri di riproduzione nativi di Anthropic e Google Gemini). I modelli Perplexity ricevono una riscrittura rigorosa dello schema: patternProperties e additionalProperties vengono rimossi e ogni schema di oggetto dichiara properties, perché Perplexity rifiuta gli schemi degli strumenti che ne sono privi. Un provider del catalogo che espone solo un formato di richiesta non supportato non viene intenzionalmente presentato come modello di testo OpenClaw. Normalizzare tali provider in base a uno dei contratti supportati in ClawRouter anziché inviare un payload incompatibile.

Quote e utilizzo

La risposta /v1/usage di ClawRouter alimenta le normali superfici di utilizzo dei provider di OpenClaw: totali di richieste, token e spesa, oltre a una finestra del budget mensile quando la chiave prevede un limite. Le chiavi senza misurazione mostrano comunque l'utilizzo aggregato senza una finestra percentuale.

La ricerca delle quote utilizza la stessa chiave con ambito definito impiegata per il rilevamento dei modelli. Un errore nella ricerca delle quote non blocca l'esecuzione dei modelli.

Controllare l'istantanea in tempo reale con:

openclaw status --usageopenclaw models status

La stessa istantanea del provider è disponibile per /status nella chat e nell'interfaccia di utilizzo di OpenClaw. Il budget si applica all'intero criterio, pertanto le richieste effettuate da un altro client che utilizza lo stesso criterio ClawRouter possono modificare la percentuale rimanente.

Risoluzione dei problemi

Comportamento di sicurezza

• L'individuazione del catalogo è limitata alla chiave proxy configurata e memorizzata nella cache per ambito delle credenziali (directory dell'agente, directory dell'area di lavoro, ID del profilo di autenticazione e URL di base).
• La chiave proxy viene associata solo al momento dell'invio della richiesta; non viene memorizzata nei metadati del modello.
• I valori di attribuzione automatica e di correlazione delle richieste vengono privati degli spazi superflui e rifiutati se contengono caratteri di controllo prima dell'invio. I valori di attribuzione sono limitati a 256 caratteri; gli ID delle richieste sono limitati a 128.
• La diagnostica del trasporto del modello contiene solo metadati e non include mai la chiave proxy né il contenuto del modello.
• Gli ID dei modelli nativi Anthropic e Gemini vengono riscritti con i rispettivi ID upstream solo al momento dell'invio.
• Le righe del catalogo non supportate o non autorizzate vengono rifiutate in modo sicuro e non sono selezionabili.

Contenuti correlati