ClawRouter

ClawRouter fournit à OpenClaw une clé unique, limitée par une politique, pour plusieurs fournisseurs de modèles en amont. Le Plugin clawrouter inclus découvre uniquement les modèles autorisés pour cette clé, achemine chaque modèle via son protocole déclaré et indique le budget de la clé ainsi que son utilisation cumulée dans les interfaces d’utilisation d’OpenClaw.

Les identifiants en amont et le transfert propre à chaque fournisseur restent dans ClawRouter ; ainsi, vous n’installez ni n’authentifiez jamais chaque Plugin de fournisseur en amont sur l’hôte OpenClaw. Le Plugin est inclus avec OpenClaw (enabledByDefault: true) ; vous avez uniquement besoin d’un identifiant ClawRouter délivré.

Prise en main

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>

Déploiement non interactif administré

Conservez la clé du proxy dans le mécanisme d’injection de secrets de la charge de travail et stockez uniquement une SecretRef dans openclaw.json. Les champs administrés canoniques sont les suivants :

Par exemple, un contrôleur de déploiement peut gérer ce correctif 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" },    },  },}

Si le déploiement définit plugins.allow, conservez ses entrées existantes et ajoutez clawrouter. Validez et appliquez sans assistant interactif :

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

La simulation résout la SecretRef, mais n’affiche jamais sa valeur. Pour renouveler l’identifiant, mettez à jour le Secret externe qui fournit CLAWROUTER_API_KEY et redémarrez la charge de travail Gateway afin que le nouvel environnement du processus soit chargé. Le fichier de configuration et la référence du modèle ne changent pas.

Pour un Gateway Docker autonome construit à partir des sources, ClawRouter est déjà inclus dans l’environnement d’exécution racine. Sélectionnez uniquement le Plugin de canal qui nécessite un paquet distinct, tel que OPENCLAW_EXTENSIONS=clickclack, slack ou msteams ; consultez les images construites à partir des sources avec des Plugins sélectionnés. Les déploiements sous forme d’archive ou d’appliance doivent empaqueter les mêmes sources intégrées via leur propre pipeline d’artefacts plutôt que d’utiliser l’image OCI.

Disponibilité et preuve en conditions réelles

Ces vérifications prouvent des limites différentes ; ne les substituez pas les unes aux autres :

# État du processus ClawRouter uniquement ; aucun identifiant ni modèle en amont n’est sollicité.curl -fsS https://clawrouter.internal.example/v1/health # Disponibilité au démarrage du Gateway OpenClaw uniquement ; aucun appel de modèle n’est effectué.curl -fsS http://127.0.0.1:18789/readyz # Découverte du catalogue limitée par l’identifiant.openclaw models list --all --provider clawrouter --json # Sonde minimale d’inférence réelle via le fournisseur ClawRouter configuré.openclaw models status --probe --probe-provider clawrouter --probe-max-tokens 8 --json # Test canari de la charge de travail utilisant une référence exacte de modèle accordée.openclaw agent --agent main \  --model clawrouter/openai/gpt-5.5 \  --message "Répondez exactement : CLAWROUTER_CANARY_OK" \  --json

Utilisez un modèle renvoyé par le catalogue limité plutôt que de copier aveuglément le modèle de l’exemple. Une réponse /readyz réussie signifie que le Gateway peut traiter les requêtes ; elle ne garantit pas que ClawRouter, son identifiant ou un fournisseur en amont est prêt. La sonde de modèle et le test canari de l’agent constituent les preuves d’inférence.

Pour un diagnostic en conditions réelles, lancez le test canari et consultez les journaux standard du Gateway. Les diagnostics existants du transport de modèles, limités aux métadonnées, produisent des lignes de la forme suivante :

[model-fetch] démarrage provider=clawrouter api=openai-responses model=openai/gpt-5.5 method=POST url=https://clawrouter.internal.example/v1/responses[model-fetch] réponse provider=clawrouter api=openai-responses model=openai/gpt-5.5 status=200

Le Plugin envoie les en-têtes bornés X-ClawRouter-Client, X-ClawRouter-Agent-Id et X-ClawRouter-Session-Id lorsque ces identifiants sont disponibles. Il associe également le callId de diagnostic de l’appel de modèle (<run-id>:model:<n>) à X-Request-ID, afin qu’un événement d’appel de modèle OpenClaw puisse être relié à la piste d’audit de ClawRouter limitée aux métadonnées. Les valeurs respectant la limite de 128 caractères de l’identifiant de requête sont identiques. Les valeurs plus longues conservent le suffixe :model:<n> et un hachage déterministe afin que les appels distincts restent bornés et puissent être reliés. Les métadonnées statiques de déploiement, telles que X-ClawRouter-Project-Id, peuvent être définies dans la table headers du fournisseur. Les en-têtes d’attribution de l’agent et de la session conservent leur limite distincte de 256 caractères. Les identifiants de requête automatiques contenant des caractères qui ne font pas partie du jeu d’identifiants ASCII de ClawRouter utilisent la même forme déterministe bornée. Les en-têtes configurés explicitement, y compris toute variante de casse de X-Request-ID, prévalent sur les valeurs automatiques. Le diagnostic de transport enregistre les métadonnées de routage et de réponse ; il ne journalise ni les identifiants, ni les identifiants de requête, ni les invites, ni les réponses générées. L’événement d’audit propre à ClawRouter fournit le fournisseur en amont sélectionné et l’état de conservation du contenu.

Découverte des modèles

GET /v1/catalog renvoie { providers: [...] }, où chaque entrée de fournisseur répertorie ses propres models[] (avec l’identifiant en amont, les capacités et la tarification) et ses routes de requête prises en charge. OpenClaw ne fournit pas de seconde liste fixe de modèles ClawRouter. Un modèle du catalogue est annoncé comme modèle OpenClaw lorsque :

• la politique de l’identifiant autorise son fournisseur ;
• le modèle du catalogue annonce une capacité LLM prise en charge (llm.responses, llm.chat, llm.messages ou llm.stream avec une route de diffusion en continu correspondante) ; et
• le fournisseur expose une route correspondante pour l’un des transports ci-dessous.

L’ajout d’un modèle à un fournisseur ClawRouter pris en charge ne nécessite aucune version d’OpenClaw : la prochaine actualisation du catalogue (mise en cache pendant 60 secondes par périmètre d’identifiant) le découvre. Un modèle nécessitant un nouveau protocole de communication requiert d’abord sa prise en charge par le Plugin.

Protocoles et Plugins de fournisseurs

ClawRouter gère les identifiants en amont ; son catalogue indique à OpenClaw quel transport utiliser, de sorte que vous n’installez jamais le Plugin d’authentification de chaque entreprise en amont.

Le Plugin applique également les politiques correspondantes de relecture et de schéma d’outils pour ces familles (compatibilité des schémas d’outils OpenAI/DeepSeek/Gemini/Perplexity ; politiques de relecture natives d’Anthropic et de Google Gemini). Les modèles Perplexity bénéficient d’une réécriture stricte du schéma : patternProperties et additionalProperties sont supprimés, et chaque schéma d’objet déclare properties, car Perplexity rejette les schémas d’outils qui en sont dépourvus. Un fournisseur du catalogue qui expose uniquement un format de requête non pris en charge n’est volontairement pas annoncé comme modèle de texte OpenClaw. Normalisez ces fournisseurs selon l’un des contrats pris en charge dans ClawRouter plutôt que d’envoyer une charge utile incompatible.

Quotas et utilisation

La réponse /v1/usage de ClawRouter alimente les interfaces habituelles d’utilisation des fournisseurs OpenClaw : totaux des requêtes, des jetons et des dépenses, ainsi qu’une fenêtre de budget mensuel lorsque la clé possède une limite. Les clés sans compteur affichent tout de même l’utilisation cumulée sans fenêtre en pourcentage.

La recherche de quota utilise la même clé limitée que la découverte des modèles. L’échec d’une recherche de quota ne bloque pas l’exécution des modèles.

Consultez l’instantané en temps réel avec :

openclaw status --usageopenclaw models status

Le même instantané du fournisseur est disponible pour /status dans la conversation et dans l’interface d’utilisation d’OpenClaw. Le budget s’applique à l’ensemble de la politique ; les requêtes effectuées par un autre client utilisant la même politique ClawRouter peuvent donc modifier le pourcentage restant.

Dépannage

Comportement de sécurité

• La découverte du catalogue est limitée à la clé de proxy configurée et mise en cache par périmètre d’identifiants (répertoire de l’agent, répertoire de l’espace de travail, identifiant du profil d’authentification et URL de base).
• La clé de proxy est jointe uniquement lors de l’envoi de la requête ; elle n’est pas stockée dans les métadonnées du modèle.
• Les valeurs d’attribution automatique et de corrélation des requêtes sont débarrassées des espaces superflus et rejetées si elles contiennent des caractères de contrôle avant l’envoi. Les valeurs d’attribution sont limitées à 256 caractères ; les identifiants de requête sont limités à 128.
• Les diagnostics de transport du modèle contiennent uniquement des métadonnées et n’incluent jamais la clé de proxy ni le contenu du modèle.
• Les identifiants de modèles Anthropic et Gemini natifs sont remplacés par leurs identifiants en amont uniquement lors de l’envoi.
• Les entrées de catalogue non prises en charge ou non autorisées échouent de manière sécurisée et ne peuvent pas être sélectionnées.

Voir aussi