Gateway

Sémantique des identifiants d’authentification

Ce document définit les sémantiques canoniques d’éligibilité et de résolution des identifiants utilisées 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 motif de sonde stables

ok
excluded_by_auth_order
missing_credential
invalid_expires
expired
unresolved_ref
no_model

Identifiants par jeton

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

Règles d’éligibilité

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

Règles de résolution

Les sémantiques du résolveur correspondent aux sémantiques d’éligibilité pour expires.
Pour les profils éligibles, le matériau de jeton peut être résolu depuis une valeur en ligne ou tokenRef.
Les références impossibles à résoudre produisent unresolved_ref dans la sortie de models status --probe.

Portabilité des copies d’agent

L’héritage d’authentification des agents est en lecture traversante. Lorsqu’un agent n’a aucun profil local, il peut résoudre des profils depuis le magasin de l’agent par défaut/principal à l’exécution sans copier de matériau 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 le fournisseur peuvent s’inscrire explicitement avec copyToAgents: true uniquement lorsque la copie du matériau d’actualisation entre agents est réputée sûre.

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

Routes d’authentification uniquement en 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" ou la route AWS SDK de configuration Amazon Bedrock détenue par le plugin. 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 la sonde le signale avec reasonCode: excluded_by_auth_order et le détail Excluded by auth.order for this provider.

Résolution des cibles 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 celui-ci, models status --probe signale status: no_model avec reasonCode: no_model.

Découverte des identifiants de CLI externes

Les identifiants utilisables uniquement à l’exécution détenus par des CLI externes sont découverts uniquement lorsque le fournisseur, l’environnement d’exécution ou le profil d’authentification est dans le périmètre de l’opération en cours, 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 externes déjà stockés, ou scoped pour un ensemble concret de fournisseurs/profils.
Les chemins en lecture seule/d’état transmettent allowKeychainPrompt: false ; ils utilisent uniquement les identifiants de CLI externes adossés à des fichiers et ne lisent ni ne réutilisent les résultats du trousseau macOS.

Garde-fou de politique SecretRef OAuth

L’entrée SecretRef est destinée uniquement aux identifiants statiques.
Si un identifiant de profil est type: "oauth", les objets SecretRef ne sont pas pris en charge pour le matériau d’identification 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 stricts 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 motif stables peuvent être ajoutés sur les lignes suivantes.

Connexe

Was this useful?