Sémantique des identifiants d’authentification

Cette sémantique maintient l’alignement entre le comportement d’authentification lors de la sélection et celui à l’exécution. Elle est partagée par :

• resolveAuthProfileOrder (ordre des profils)
• resolveApiKeyForProfile (résolution des identifiants à l’exécution)
• openclaw models status --probe
• les vérifications d’authentification d’openclaw doctor (doctor-auth)

Codes de motif de sondage stables

Les résultats de sondage comportent une catégorie status (ok, auth, rate_limit, billing, timeout, format, unknown, no_model), ainsi qu’un reasonCode stable lorsque le sondage n’a jamais atteint un appel de modèle :

Les vérifications d’éligibilité renvoient ok comme code de motif pour les identifiants utilisables.

Identifiants par jeton

Les identifiants par jeton (type: "token") prennent en charge token intégré et/ou tokenRef.

Règles d’éligibilité

1. Un profil de jeton est inéligible lorsque token et tokenRef sont tous deux absents (missing_credential).
2. expires est facultatif. Lorsqu’il est présent, il doit s’agir d’un nombre fini de millisecondes depuis l’époque Unix, supérieur à 0 et inférieur ou égal à l’horodatage maximal de Date en JavaScript (8640000000000000).
3. Si expires est invalide (type incorrect, NaN, 0, valeur négative, non finie ou supérieure à ce maximum), le profil est inéligible avec invalid_expires.
4. Si expires est dans le passé, le profil est inéligible avec expired.
5. tokenRef ne permet pas de contourner la validation d’expires.

Règles de résolution

1. La sémantique du résolveur correspond à celle de l’éligibilité pour expires.
2. Pour les profils éligibles, le contenu du jeton peut être résolu à partir de la valeur intégrée ou de tokenRef.
3. Les références impossibles à résoudre produisent unresolved_ref dans la sortie de models status --probe.

Portabilité des copies d’agents

L’héritage de l’authentification des agents fonctionne par lecture transparente. Lorsqu’un agent ne possède aucun profil local, il résout à l’exécution les profils depuis le magasin de l’agent principal/par défaut, sans copier les données secrètes dans son propre magasin d’identifiants (agents/<agentId>/agent/openclaw-agent.sqlite).

Les flux de copie explicites, tels que openclaw agents add, appliquent cette politique de portabilité :

• Les profils api_key et token sont portables, sauf si copyToAgents: false.
• Les profils oauth ne sont pas portables par défaut, car les jetons d’actualisation peuvent être à usage unique ou sensibles à la rotation.
• Les flux OAuth appartenant au fournisseur peuvent activer cette portabilité avec copyToAgents: true uniquement lorsque la copie des données d’actualisation entre agents est réputée sûre ; cette activation ne s’applique que lorsque le profil contient des données d’accès/d’actualisation intégrées.

Les profils non portables restent disponibles par héritage en lecture transparente, sauf si l’agent cible se connecte séparément et crée son propre profil local.

Routes d’authentification définies uniquement dans la configuration

Les entrées auth.profiles avec mode: "aws-sdk" sont des métadonnées de routage, et non des identifiants stockés. Elles sont valides lorsque le fournisseur cible utilise models.providers.<id>.auth: "aws-sdk", la route écrite par la configuration d’Amazon Bedrock appartenant au Plugin. Ces identifiants de profil peuvent figurer dans auth.order et les remplacements de session, même lorsqu’aucune entrée correspondante n’existe dans le magasin d’identifiants.

N’écrivez pas type: "aws-sdk" dans le magasin d’identifiants ; les identifiants stockés sont uniquement de type api_key, token ou oauth. Si un ancien fichier auth-profiles.json contient un tel marqueur, openclaw doctor --fix le déplace vers auth.profiles et le supprime du magasin.

Filtrage par ordre d’authentification explicite

• Lorsque auth.order.<provider> ou le remplacement de l’ordre du magasin d’authentification est défini pour un fournisseur, models status --probe ne sonde que les identifiants de profil qui restent dans l’ordre d’authentification résolu pour ce fournisseur. Le remplacement stocké prévaut sur la configuration auth.order.
• Un profil stocké pour ce fournisseur, mais omis de l’ordre explicite, n’est pas essayé silencieusement par la suite. La sortie du sondage le signale avec reasonCode: excluded_by_auth_order et le détail Excluded by auth.order for this provider.

Résolution de la cible du sondage

• Les cibles de sondage peuvent provenir des profils d’authentification, des identifiants d’environnement ou de models.json (source du résultat : profile, env, models.json).
• Si un fournisseur possède des identifiants, mais qu’OpenClaw ne peut résoudre aucun modèle candidat pouvant être sondé, models status --probe signale status: no_model avec reasonCode: no_model.

Détection des identifiants de CLI externes

• Les identifiants disponibles uniquement à l’exécution et appartenant à des CLI externes (Claude CLI pour claude-cli, Codex CLI pour openai, MiniMax CLI pour minimax-portal) ne sont détectés que lorsque le fournisseur, l’environnement d’exécution ou le profil d’authentification entre dans le périmètre de l’opération en cours, ou lorsqu’un profil local stocké existe déjà pour cette source externe.
• Les appelants du magasin d’authentification choisissent un mode explicite de détection des CLI externes : none pour l’authentification persistée/du Plugin uniquement, existing pour actualiser les profils de CLI externes déjà stockés, ou scoped pour un ensemble concret de fournisseurs/profils.
• Les chemins en lecture seule/de statut transmettent allowKeychainPrompt: false ; ils utilisent uniquement les identifiants des CLI externes stockés dans des fichiers et ne lisent ni ne réutilisent les résultats du trousseau macOS.

Garde de politique OAuth pour SecretRef

Les entrées SecretRef sont réservées aux identifiants statiques. Les identifiants OAuth sont modifiables à l’exécution (les flux d’actualisation enregistrent les jetons après rotation) ; des données OAuth adossées à SecretRef répartiraient donc l’état modifiable entre plusieurs magasins.

• Si l’identifiant d’un profil est de type: "oauth", les objets SecretRef sont rejetés pour tous les champs de données d’identification de ce profil.
• Si auth.profiles.<id>.mode vaut "oauth", les entrées keyRef/tokenRef adossées à SecretRef sont rejetées pour ce profil.
• Les violations entraînent des échecs définitifs (erreurs levées) dans les chemins de préparation des secrets au démarrage/rechargement et de résolution des profils.

Messages compatibles avec les anciennes versions

Pour assurer la compatibilité des scripts, la première ligne des erreurs de sondage reste inchangée :

Auth profile credentials are missing or expired.

Des détails lisibles et le code de motif stable suivent sur les lignes suivantes sous la forme ↳ Auth reason [code]: ....

Voir aussi

• Gestion des secrets
• Stockage de l’authentification