Contrat du plan d’application des secrets

Cette page définit le contrat strict appliqué par openclaw secrets apply. Si une cible ne respecte pas ces règles, l’application échoue avant de modifier le moindre fichier.

Structure du fichier de plan

openclaw secrets apply --from <plan.json> attend un tableau targets contenant les cibles du plan :

{  version: 1,  protocolVersion: 1,  targets: [    {      type: "models.providers.apiKey",      path: "models.providers.openai.apiKey",      pathSegments: ["models", "providers", "openai", "apiKey"],      providerId: "openai",      ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },    },    {      type: "auth-profiles.api_key.key",      path: "profiles.openai:default.key",      pathSegments: ["profiles", "openai:default", "key"],      agentId: "main",      ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },    },  ],}

openclaw secrets configure génère des plans respectant cette structure. Vous pouvez également en rédiger ou en modifier un manuellement.

Ajouts ou mises à jour et suppressions de fournisseurs

Les plans peuvent également inclure deux champs facultatifs de premier niveau qui modifient la table secrets.providers en même temps que les écritures propres à chaque cible :

• providerUpserts -- un objet indexé par alias de fournisseur. Chaque valeur est une définition de fournisseur (de la même structure que celle acceptée sous secrets.providers.<alias> dans openclaw.json, par exemple un fournisseur exec ou file).
• providerDeletes -- un tableau d’alias de fournisseurs à supprimer.

providerUpserts s’exécute avant targets. Ainsi, un champ target.ref.provider peut référencer un alias de fournisseur introduit par le même plan dans providerUpserts. Sans cet ordre d’exécution, les plans qui référencent un alias pas encore configuré dans openclaw.json échouent avec provider "<alias>" is not configured.

{  version: 1,  protocolVersion: 1,  providerUpserts: {    onepassword_anthropic: {      source: "exec",      command: "/usr/bin/op",      args: ["read", "op://Vault/Anthropic/credential"],    },  },  providerDeletes: ["legacy_unused_alias"],  targets: [    {      type: "models.providers.apiKey",      path: "models.providers.anthropic.apiKey",      pathSegments: ["models", "providers", "anthropic", "apiKey"],      providerId: "anthropic",      ref: { source: "exec", provider: "onepassword_anthropic", id: "credential" },    },  ],}

Les fournisseurs d’exécution introduits via providerUpserts restent soumis aux règles de consentement à l’exécution décrites dans Comportement du consentement pour les fournisseurs d’exécution : les plans contenant des fournisseurs d’exécution nécessitent --allow-exec en mode écriture.

Périmètre des cibles prises en charge

Les cibles de plan sont acceptées pour les chemins d’identifiants pris en charge dans Surface des identifiants SecretRef.

Comportement des types de cible

target.type doit être un type de cible reconnu, et le champ target.path normalisé doit correspondre à la structure de chemin enregistrée pour ce type.

Certains types de cible acceptent également un alias de compatibilité dans target.type pour les plans existants, en plus de leur nom de type canonique :

Règles de validation des chemins

Chaque cible est validée selon toutes les règles suivantes :

• type doit être un type de cible reconnu.
• path doit être un chemin à points non vide.
• pathSegments peut être omis. S’il est fourni, sa normalisation doit produire exactement le même chemin que path.
• Les segments interdits sont rejetés : __proto__, prototype, constructor.
• Le chemin normalisé doit correspondre à la structure de chemin enregistrée pour le type de cible.
• Si providerId ou accountId est défini, il doit correspondre à l’identifiant encodé dans le chemin.
• Les cibles de auth-profiles.json nécessitent agentId.
• Lors de la création d’une nouvelle association dans auth-profiles.json, incluez authProfileProvider.

Comportement en cas d’échec

Si la validation d’une cible échoue, l’application se termine avec une erreur telle que :

Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl

Aucune écriture n’est validée pour un plan non valide : la résolution des cibles et la validation des chemins s’exécutent avant toute modification de fichier. Par ailleurs, une fois qu’un plan valide commence les écritures, l’application crée d’abord un instantané de chaque fichier concerné, puis restaure ces instantanés si une écriture ultérieure échoue au cours de la même exécution. Ainsi, une écriture partielle ne peut jamais désynchroniser la configuration, les profils d’authentification ou l’état des variables d’environnement.

Comportement du consentement pour les fournisseurs d’exécution

• --dry-run ignore par défaut les vérifications des SecretRef d’exécution.
• Les plans contenant des SecretRef ou des fournisseurs d’exécution sont rejetés en mode écriture, sauf si --allow-exec est défini.
• Lors de la validation ou de l’application de plans contenant des éléments d’exécution, transmettez --allow-exec aux commandes de simulation et d’écriture.

Remarques sur le périmètre d’exécution et d’audit

• Les entrées de auth-profiles.json contenant uniquement des références (keyRef/tokenRef) sont incluses dans la résolution des identifiants à l’exécution et dans la couverture de l’audit.
• secrets apply écrit les cibles prises en charge dans openclaw.json, les cibles prises en charge dans auth-profiles.json et effectue trois passes de nettoyage facultatives, toutes activées par défaut : scrubEnv (supprime de .env les valeurs en clair migrées), scrubAuthProfilesForProviderTargets (supprime dans auth-profiles.json les valeurs en clair et les résidus de références inutilisées pour les fournisseurs que le plan vient de migrer) et scrubLegacyAuthJson (supprime les entrées api_key migrées des anciens stockages auth.json). Définissez l’une des options options.scrubEnv, options.scrubAuthProfilesForProviderTargets ou options.scrubLegacyAuthJson sur false dans le plan pour ignorer la passe correspondante.

Vérifications de l’opérateur

# Valider le plan sans effectuer d’écritureopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run # Puis l’appliquer réellementopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json # Pour les plans contenant des éléments d’exécution, donner explicitement son accord dans les deux modesopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec

Si l’application échoue avec un message signalant un chemin de cible non valide, régénérez le plan avec openclaw secrets configure ou corrigez le chemin de la cible pour qu’il corresponde à l’une des structures prises en charge ci-dessus.

Documentation associée

• Gestion des secrets
• CLI secrets
• Surface des identifiants SecretRef
• Référence de configuration