Skip to main content
Cette page traite de l’authentification auprès des fournisseurs de modèles (clés API, OAuth, réutilisation de la CLI Claude, jeton de configuration Anthropic). Pour l’authentification de la connexion au Gateway (jeton, mot de passe, proxy de confiance), consultez Configuration et Authentification par proxy de confiance.
OpenClaw prend en charge OAuth et les clés API pour les fournisseurs de modèles. Pour un hôte Gateway fonctionnant en permanence, une clé API constitue l’option la plus prévisible ; les flux d’abonnement/OAuth fonctionnent également lorsqu’ils correspondent au modèle de compte de votre fournisseur.

​
Configuration recommandée : clé API (tout fournisseur)

  1. Créez une clé API dans la console de votre fournisseur.
  2. Placez-la sur l’hôte Gateway (la machine exécutant openclaw gateway) :
  1. Si le Gateway s’exécute sous systemd/launchd, placez la clé dans ~/.openclaw/.env afin que le démon puisse la lire :
  1. Redémarrez le processus Gateway (ou le démon), puis vérifiez de nouveau :
openclaw onboard peut également stocker les clés API destinées au démon si vous ne souhaitez pas gérer vous-même les variables d’environnement. Consultez Variables d’environnement pour connaître l’ordre de priorité complet du chargement de l’environnement (env.shellEnv, ~/.openclaw/.env, systemd/launchd).

​
Anthropic : réutilisation de la CLI Claude

L’authentification par jeton de configuration Anthropic reste prise en charge. La réutilisation de la CLI Claude (utilisation de type claude -p) est également approuvée pour cette intégration ; lorsqu’une connexion à la CLI Claude est disponible sur l’hôte, il s’agit de la méthode privilégiée pour une utilisation locale ou sur ordinateur de bureau. Pour les hôtes Gateway de longue durée, une clé API Anthropic reste le choix le plus prévisible, avec un contrôle explicite de la facturation côté serveur. Configuration de l’hôte pour la réutilisation de la CLI Claude :
Cette procédure comporte deux étapes : connecter Claude Code à Anthropic sur l’hôte, puis indiquer à OpenClaw d’acheminer la sélection des modèles Anthropic via le moteur local claude-cli et de stocker le profil d’authentification OpenClaw correspondant. Si claude ne figure pas dans PATH, installez Claude Code ou définissez agents.defaults.cliBackends.claude-cli.command sur le chemin du fichier binaire.

​
Saisie manuelle du jeton

Fonctionne avec tout fournisseur ; écrit dans le stockage d’authentification SQLite propre à l’agent et met à jour la configuration :
OpenClaw lit les profils d’authentification dans le fichier openclaw-agent.sqlite de chaque agent. Les détails des points de terminaison (baseUrl, api, identifiants de modèles, en-têtes, délais d’expiration) doivent figurer sous models.providers.<id> dans openclaw.json ou models.json, et non dans les profils d’authentification. Si une ancienne installation contient encore auth-profiles.json, auth-state.json ou une structure plate telle que { "openrouter": { "apiKey": "..." } }, exécutez openclaw doctor --fix pour l’importer dans SQLite ; le diagnostic conserve des sauvegardes horodatées à côté des fichiers JSON d’origine. Les méthodes d’authentification externes telles que auth: "aws-sdk" de Bedrock ne sont pas des identifiants. Pour une méthode Bedrock nommée, définissez auth.profiles.<id>.mode: "aws-sdk" dans openclaw.json — n’écrivez pas type: "aws-sdk" dans le stockage des profils d’authentification. openclaw doctor --fix migre les anciens marqueurs AWS SDK du stockage des identifiants vers les métadonnées de configuration.

​
Identifiants fondés sur SecretRef

  • Les identifiants api_key peuvent utiliser keyRef: { source, provider, id }
  • Les identifiants token peuvent utiliser tokenRef: { source, provider, id }
  • Les profils en mode OAuth refusent les identifiants SecretRef : si auth.profiles.<id>.mode vaut "oauth", un keyRef/tokenRef fondé sur SecretRef est refusé pour ce profil.

​
Vérification de l’état d’authentification des modèles

Vérification adaptée à l’automatisation, avec le code de sortie 1 en cas d’expiration ou d’absence, et 2 en cas d’expiration prochaine :
Sondes d’authentification en direct (ajoutez --probe-provider, --probe-profile, --probe-timeout, --probe-concurrency ou --probe-max-tokens pour restreindre la portée) :
Remarques :
  • Les lignes de sonde peuvent provenir des profils d’authentification, des identifiants d’environnement ou de models.json.
  • Si auth.order.<provider> omet un profil stocké, la sonde signale excluded_by_auth_order pour ce profil au lieu de le tester.
  • Si l’authentification existe, mais qu’OpenClaw ne peut pas déterminer de modèle pouvant être sondé pour ce fournisseur, la sonde signale status: no_model.
  • Les délais de récupération après limitation de débit peuvent être propres à un modèle : un profil en période de récupération pour un modèle peut toujours servir un modèle apparenté chez le même fournisseur.
Scripts d’exploitation facultatifs (systemd/Termux) : Scripts de surveillance de l’authentification.

​
Rotation des clés API (Gateway)

Certains fournisseurs retentent une requête avec une autre clé configurée lorsqu’un appel atteint la limite de débit du fournisseur. Ordre de priorité des clés pour chaque fournisseur :
  1. OPENCLAW_LIVE_<PROVIDER>_KEY (remplacement unique qui impose une seule clé)
  2. <PROVIDER>_API_KEYS (liste séparée par des virgules, des espaces ou des points-virgules)
  3. <PROVIDER>_API_KEY
  4. <PROVIDER>_API_KEY_* (toute variable d’environnement portant ce préfixe)
Les fournisseurs Google (google, google-vertex) utilisent également GOOGLE_API_KEY comme solution de repli. Les doublons sont supprimés de la liste combinée avant utilisation. OpenClaw passe à la clé suivante uniquement lorsque le message d’erreur correspond à : rate_limit, rate limit, 429, quota exceeded/quota_exceeded, resource exhausted/resource_exhausted ou too many requests. Les autres erreurs ne provoquent pas de nouvelle tentative avec d’autres clés. Si toutes les clés échouent, l’erreur finale de la dernière tentative est renvoyée.
Les expressions propres aux fournisseurs telles que ThrottlingException, concurrency limit reached ou workers_ai ... quota limit exceeded déterminent la classification du basculement et des nouvelles tentatives (changement de modèle ou de fournisseur en cas d’échecs répétés), un mécanisme distinct de la rotation des clés API décrite ci-dessus.
La suppression des informations d’authentification enregistrées ne révoque pas la clé auprès du fournisseur — renouvelez-la ou révoquez-la dans le tableau de bord du fournisseur lorsque vous devez l’invalider côté fournisseur.

​
Suppression de l’authentification d’un fournisseur pendant l’exécution du Gateway

Lorsque vous supprimez l’authentification d’un fournisseur via le plan de contrôle du Gateway, OpenClaw supprime les profils d’authentification enregistrés pour ce fournisseur et interrompt les exécutions actives de discussions ou d’agents dont le fournisseur du modèle sélectionné correspond à celui qui a été supprimé. Les exécutions interrompues émettent les événements habituels d’annulation et de cycle de vie avec stopReason: "auth-revoked", afin que les clients connectés puissent indiquer que l’exécution s’est arrêtée parce que les identifiants ont été supprimés.

​
Contrôle de l’identifiant utilisé

​
OpenAI et anciens identifiants openai-codex

Les profils de clé API OpenAI et les profils OAuth ChatGPT/Codex utilisent tous l’identifiant de fournisseur canonique openai. Utilisez les identifiants de profil openai:* et auth.order.openai dans les nouvelles configurations. Si openai-codex apparaît dans une ancienne configuration, dans des identifiants de profil d’authentification ou dans auth.order.openai-codex, considérez-le comme une donnée d’entrée de migration héritée — ne créez pas de nouveaux profils openai-codex. Exécutez :
Le diagnostic réécrit les anciens identifiants de profil openai-codex:* et les entrées auth.order.openai-codex vers la méthode canonique openai. Pour l’acheminement propre à OpenAI des modèles et de l’exécution, consultez OpenAI.

​
Pendant la connexion (CLI)

--profile-id permet de conserver séparément plusieurs connexions OAuth au même fournisseur au sein d’un agent. --force supprime les profils d’authentification enregistrés pour ce fournisseur dans le répertoire de l’agent sélectionné, puis relance le même flux d’authentification. Utilisez cette option lorsqu’un profil enregistré est bloqué, expiré ou associé au mauvais compte. Elle ne révoque pas les identifiants auprès du fournisseur.

​
Par session (commande de discussion)

  • /model <alias-or-id>@<profileId> impose un identifiant précis du fournisseur pour la session actuelle (exemples d’identifiants de profil : anthropic:default, anthropic:work).
  • /model (ou /model list) affiche un sélecteur compact ; /model status affiche la vue complète (candidats et prochain profil d’authentification, ainsi que les détails du point de terminaison du fournisseur lorsqu’ils sont configurés).
Si vous modifiez l’ordre d’authentification ou l’épinglage du profil pour une discussion déjà en cours, envoyez /new ou /reset afin de démarrer une nouvelle session — les sessions existantes conservent leur sélection actuelle de modèle et de profil jusqu’à leur réinitialisation.

​
Par agent (remplacement via la CLI)

Les remplacements de l’ordre d’authentification sont stockés dans l’état d’authentification SQLite de cet agent :
Utilisez --agent <id> pour cibler un agent précis ; omettez cette option pour utiliser l’agent par défaut configuré. openclaw models status --probe affiche les profils stockés omis sous la forme excluded_by_auth_order au lieu de les ignorer silencieusement.

​
Résolution des problèmes

​
« Aucun identifiant trouvé »

Configurez une clé API Anthropic sur l’hôte Gateway, ou configurez la méthode par jeton de configuration Anthropic, puis vérifiez de nouveau :

​
Jeton proche de l’expiration ou expiré

Exécutez openclaw models status pour identifier le profil qui arrive à expiration. Si un profil de jeton Anthropic est absent ou expiré, actualisez-le au moyen du jeton de configuration ou migrez vers une clé API Anthropic.

​
Rubriques connexes