English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Gateway

Authentification

OpenClaw prend en charge OAuth et les clés API pour les fournisseurs de modèles. Pour les hôtes de Gateway toujours actifs, les clés API sont généralement l’option la plus prévisible. Les flux d’abonnement/OAuth sont également pris en charge lorsqu’ils correspondent au modèle de compte de votre fournisseur.

Consultez /concepts/oauth pour le flux OAuth complet et la disposition du stockage. Pour l’authentification basée sur SecretRef (fournisseurs env/file/exec), consultez Gestion des secrets. Pour les règles d’éligibilité des identifiants et des codes de motif utilisées par models status --probe, consultez Sémantique des identifiants d’authentification.

Configuration recommandée (clé API, tout fournisseur)

Si vous exécutez un Gateway longue durée, commencez avec une clé API pour le fournisseur choisi. Pour Anthropic en particulier, l’authentification par clé API reste la configuration serveur la plus prévisible, mais OpenClaw prend également en charge la réutilisation d’une connexion locale au Claude CLI.

  1. Créez une clé API dans la console de votre fournisseur.
  2. Placez-la sur l’hôte du Gateway (la machine qui exécute openclaw gateway).
export <PROVIDER>_API_KEY="..."
openclaw models status
  1. Si le Gateway s’exécute sous systemd/launchd, préférez placer la clé dans ~/.openclaw/.env afin que le démon puisse la lire :
cat >> ~/.openclaw/.env <<'EOF'
&lt;PROVIDER&gt;_API_KEY=...
EOF

Redémarrez ensuite le démon (ou redémarrez votre processus Gateway) et revérifiez :

openclaw models status
openclaw doctor

Si vous préférez ne pas gérer vous-même les variables d’environnement, l’onboarding peut stocker les clés API pour l’utilisation par le démon : openclaw onboard.

Consultez Aide pour plus de détails sur l’héritage d’environnement (env.shellEnv, ~/.openclaw/.env, systemd/launchd).

Anthropic : Claude CLI et compatibilité des jetons

L’authentification par setup-token Anthropic reste disponible dans OpenClaw en tant que chemin de jeton pris en charge. Depuis, le personnel d’Anthropic nous a indiqué que l’utilisation du Claude CLI à la manière d’OpenClaw était de nouveau autorisée ; OpenClaw considère donc la réutilisation du Claude CLI et l’utilisation de claude -p comme approuvées pour cette intégration, sauf si Anthropic publie une nouvelle politique. Lorsque la réutilisation du Claude CLI est disponible sur l’hôte, c’est désormais le chemin recommandé.

Pour les hôtes de Gateway longue durée, une clé API Anthropic reste la configuration la plus prévisible. Si vous souhaitez réutiliser une connexion Claude existante sur le même hôte, utilisez le chemin Anthropic Claude CLI dans l’onboarding/la configuration.

Configuration d’hôte recommandée pour la réutilisation du Claude CLI :

# Run on the gateway host
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

Il s’agit d’une configuration en deux étapes :

  1. Connectez Claude Code lui-même à Anthropic sur l’hôte du Gateway.
  2. Indiquez à OpenClaw de basculer la sélection de modèles Anthropic vers le backend local claude-cli et de stocker le profil d’authentification OpenClaw correspondant.

Si claude n’est pas dans PATH, installez d’abord Claude Code ou définissez agents.defaults.cliBackends.claude-cli.command sur le chemin réel du binaire.

Saisie manuelle du jeton (tout fournisseur ; écrit auth-profiles.json + met à jour la configuration) :

openclaw models auth paste-token --provider openrouter

auth-profiles.json stocke uniquement les identifiants. La forme canonique est :

{
  "version": 1,
  "profiles": {
    "openrouter:default": {
      "type": "api_key",
      "provider": "openrouter",
      "key": "OPENROUTER_API_KEY"
    }
  }
}

OpenClaw attend la forme canonique version + profiles à l’exécution. Si une installation plus ancienne possède encore un fichier plat tel que { "openrouter": { "apiKey": "..." } }, exécutez openclaw doctor --fix pour le réécrire en profil de clé API openrouter:default ; doctor conserve une copie .legacy-flat.*.bak à côté de l’original. Les détails de point de terminaison tels que baseUrl, api, les identifiants de modèles, les en-têtes et les délais d’expiration doivent se trouver sous models.providers.<id> dans openclaw.json ou models.json, et non dans auth-profiles.json.

Les routes d’authentification externes telles que Bedrock auth: "aws-sdk" ne sont pas non plus des identifiants. Si vous voulez une route Bedrock nommée, placez auth.profiles.<id>.mode: "aws-sdk" dans openclaw.json ; n’écrivez pas type: "aws-sdk" dans auth-profiles.json. openclaw doctor --fix déplace les anciens marqueurs AWS SDK du magasin d’identifiants vers les métadonnées de configuration.

Les références de profil d’authentification sont également prises en charge pour les identifiants statiques :

  • Les identifiants api_key peuvent utiliser keyRef: { source, provider, id }
  • Les identifiants token peuvent utiliser tokenRef: { source, provider, id }
  • Les profils en mode OAuth ne prennent pas en charge les identifiants SecretRef ; si auth.profiles.<id>.mode est défini sur "oauth", l’entrée keyRef/tokenRef adossée à SecretRef pour ce profil est rejetée.

Vérification adaptée à l’automatisation (sortie 1 si expiré/manquant, 2 si proche de l’expiration) :

openclaw models status --check

Sondes d’authentification en direct :

openclaw models status --probe

Remarques :

  • Les lignes de sonde peuvent provenir des profils d’authentification, des identifiants d’environnement ou de models.json.
  • Si auth.order.<provider> explicite omet un profil stocké, la sonde signale excluded_by_auth_order pour ce profil au lieu d’essayer de l’utiliser.
  • Si une authentification existe mais qu’OpenClaw ne peut pas résoudre un candidat de modèle sondable pour ce fournisseur, la sonde signale status: no_model.
  • Les délais de récupération après limite de débit peuvent être propres à un modèle. Un profil en délai de récupération pour un modèle peut rester utilisable pour un modèle apparenté chez le même fournisseur.

Les scripts d’exploitation facultatifs (systemd/Termux) sont documentés ici : Scripts de surveillance de l’authentification

Note Anthropic

Le backend Anthropic claude-cli est de nouveau pris en charge.

  • Le personnel d’Anthropic nous a indiqué que ce chemin d’intégration OpenClaw est de nouveau autorisé.
  • OpenClaw considère donc la réutilisation du Claude CLI et l’utilisation de claude -p comme approuvées pour les exécutions appuyées par Anthropic, sauf si Anthropic publie une nouvelle politique.
  • Les clés API Anthropic restent le choix le plus prévisible pour les hôtes de Gateway longue durée et le contrôle explicite de la facturation côté serveur.

Vérifier l’état d’authentification des modèles

openclaw models status
openclaw doctor

Comportement de rotation des clés API (Gateway)

Certains fournisseurs prennent en charge la nouvelle tentative d’une requête avec d’autres clés lorsqu’un appel API atteint une limite de débit du fournisseur.

  • Ordre de priorité :
    • OPENCLAW_LIVE_&lt;PROVIDER&gt;_KEY (remplacement unique)
    • &lt;PROVIDER&gt;_API_KEYS
    • &lt;PROVIDER&gt;_API_KEY
    • &lt;PROVIDER&gt;_API_KEY_*
  • Les fournisseurs Google incluent également GOOGLE_API_KEY comme solution de repli supplémentaire.
  • La même liste de clés est dédupliquée avant utilisation.
  • OpenClaw réessaie avec la clé suivante uniquement pour les erreurs de limite de débit (par exemple 429, rate_limit, quota, resource exhausted, Too many concurrent requests, ThrottlingException, concurrency limit reached ou workers_ai ... quota limit exceeded).
  • Les erreurs qui ne sont pas liées à une limite de débit ne sont pas réessayées avec d’autres clés.
  • Si toutes les clés échouent, l’erreur finale de la dernière tentative est renvoyée.

Contrôler l’identifiant utilisé

Par session (commande de chat)

Utilisez /model <alias-or-id>@<profileId> pour épingler un identifiant de fournisseur spécifique pour la session actuelle (exemples d’identifiants de profil : anthropic:default, anthropic:work).

Utilisez /model (ou /model list) pour un sélecteur compact ; utilisez /model status pour la vue complète (candidats + prochain profil d’authentification, ainsi que les détails de point de terminaison du fournisseur lorsqu’ils sont configurés).

Par agent (remplacement CLI)

Définissez un remplacement explicite de l’ordre des profils d’authentification pour un agent (stocké dans le auth-state.json de cet agent) :

openclaw models auth order get --provider anthropic
openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic

Utilisez --agent <id> pour cibler un agent spécifique ; omettez-le pour utiliser l’agent par défaut configuré. Lorsque vous déboguez des problèmes d’ordre, openclaw models status --probe affiche les profils stockés omis comme excluded_by_auth_order au lieu de les ignorer silencieusement. Lorsque vous déboguez des problèmes de délai de récupération, n’oubliez pas que les délais de récupération liés aux limites de débit peuvent être associés à un identifiant de modèle plutôt qu’à l’ensemble du profil fournisseur.

Dépannage

« Aucun identifiant trouvé »

Si le profil Anthropic est manquant, configurez une clé API Anthropic sur l’hôte du Gateway ou configurez le chemin setup-token Anthropic, puis revérifiez :

openclaw models status

Jeton proche de l’expiration/expiré

Exécutez openclaw models status pour confirmer quel profil arrive à expiration. Si un profil de jeton Anthropic est manquant ou expiré, actualisez cette configuration via setup-token ou migrez vers une clé API Anthropic.

Connexe