Sémantique des identifiants d’authentification

Ce document définit la sémantique canonique d’éligibilité et de résolution des identifiants utilisée dans :

• resolveAuthProfileOrder
• resolveApiKeyForProfile
• models status --probe
• doctor-auth

L’objectif est de maintenir l’alignement entre le comportement au moment de la sélection et le comportement à l’exécution.

# Codes de raison stables de sonde

• ok
• excluded_by_auth_order
• missing_credential
• invalid_expires
• expired
• unresolved_ref
• no_model

# Identifiants de jeton

Les identifiants de jeton (type: "token") prennent en charge token et/ou tokenRef en ligne.

# Règles d’éligibilité

1. Un profil de jeton est inéligible lorsque token et tokenRef sont tous deux absents.
2. expires est facultatif.
3. Si expires est présent, il doit être un nombre fini supérieur à 0.
4. Si expires est invalide (NaN, 0, négatif, non fini ou de type incorrect), le profil est inéligible avec invalid_expires.
5. Si expires est dans le passé, le profil est inéligible avec expired.
6. tokenRef ne contourne pas la validation de expires.

# Règles de résolution

1. La sémantique du résolveur correspond à la sémantique d’éligibilité pour expires.
2. Pour les profils éligibles, le contenu du jeton peut être résolu depuis une valeur en ligne ou tokenRef.
3. Les références non résolubles produisent unresolved_ref dans la sortie de models status --probe.

# Portabilité des copies d’agent

L’héritage d’authentification des agents se fait par lecture transparente. Lorsqu’un agent n’a pas de profil local, il peut résoudre les profils depuis le magasin de l’agent par défaut/principal à l’exécution sans copier le contenu secret dans son propre auth-profiles.json.

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

• Les profils api_key sont portables sauf si copyToAgents: false.
• Les profils 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 détenus par un fournisseur peuvent s’inscrire avec copyToAgents: true uniquement lorsque la copie du contenu d’actualisation entre agents est connue comme sûre.

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 configurées uniquement

Les entrées auth.profiles avec mode: "aws-sdk" sont des métadonnées de routage, pas des identifiants stockés. Elles sont valides lorsque le fournisseur cible utilise models.providers.<id>.auth: "aws-sdk" ou la route AWS SDK par défaut intégrée d’Amazon Bedrock. Ces identifiants de profil peuvent apparaître dans auth.order et les remplacements de session même lorsqu’aucune entrée correspondante n’existe dans auth-profiles.json.

N’écrivez pas type: "aws-sdk" dans auth-profiles.json. Si une installation héritée possède un tel marqueur, openclaw doctor --fix le déplace vers auth.profiles et supprime le marqueur du magasin d’identifiants.

# Filtrage explicite de l’ordre d’authentification

• Lorsque auth.order.<provider> ou le remplacement d’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.
• Un profil stocké pour ce fournisseur qui est omis de l’ordre explicite n’est pas essayé silencieusement plus tard. La sortie de sonde le signale avec reasonCode: excluded_by_auth_order et le détail Excluded by auth.order for this provider.

# Résolution de la cible de sonde

• Les cibles de sonde peuvent provenir de profils d’authentification, d’identifiants d’environnement ou de models.json.
• Si un fournisseur dispose d’identifiants mais qu’OpenClaw ne peut pas résoudre de modèle sondable candidat pour lui, models status --probe signale status: no_model avec reasonCode: no_model.

# Découverte d’identifiants de CLI externes

• Les identifiants utilisés uniquement à l’exécution et détenus par des CLI externes ne sont découverts que lorsque le fournisseur, l’environnement d’exécution ou le profil d’authentification est dans le périmètre de l’opération actuelle, ou lorsqu’un profil local stocké pour cette source externe existe déjà.
• Les appelants du magasin d’authentification doivent choisir un mode explicite de découverte de CLI externe : none pour l’authentification persistée/Plugin uniquement, existing pour actualiser les profils de CLI externe 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 de CLI externes sauvegardés par fichier et ne lisent ni ne réutilisent les résultats du trousseau macOS.

# Garde-fou de politique OAuth SecretRef

• L’entrée SecretRef est réservée aux identifiants statiques.
• Si un identifiant de profil est type: "oauth", les objets SecretRef ne sont pas pris en charge pour le contenu d’identifiant de ce profil.
• Si auth.profiles.<id>.mode est "oauth", l’entrée keyRef/tokenRef adossée à SecretRef pour ce profil est rejetée.
• Les violations sont des échecs bloquants dans les chemins de résolution d’authentification au démarrage/rechargement.

# Messagerie compatible avec l’héritage

Pour la compatibilité des scripts, les erreurs de sonde conservent cette première ligne inchangée :

Auth profile credentials are missing or expired.

Des détails lisibles par l’humain et des codes de raison stables peuvent être ajoutés sur les lignes suivantes.

# Connexe

• Gestion des secrets
• Stockage de l’authentification