Aller au contenu principal

Commandes CLI

secrets

Utilisez openclaw secrets pour gérer les SecretRefs et maintenir l'instantané d'exécution actif en bonne santé. Rôles des commandes :

  • reload : RPC de la passerelle (secrets.reload) qui réévalue les références et échange l'instantané d'exécution uniquement en cas de succès complet (aucune écriture de configuration).
  • audit : analyse en lecture seule des magasins de configuration/d'authentification/de modèles générés et des résidus hérités pour détecter le texte en clair, les références non résolues et les dérives de priorité.
  • configure : planificateur interactif pour la configuration des fournisseurs, le mappage des cibles et la prévérification (TTY requis).
  • apply : exécute un plan sauvegardé (--dry-run pour validation uniquement), puis nettoie les résidus de texte en clair ciblés.

Boucle opérateur recommandée :

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload

Note sur le code de sortie pour CI/portes :

  • audit --check retourne 1 en cas de découvertes.
  • les références non résolues retournent 2.

Liens connexes :

Recharger l'instantané d'exécution​

Réévalue les références de secrets et échange atomiquement l'instantané d'exécution.

openclaw secrets reload
openclaw secrets reload --json

Notes :

  • Utilise la méthode RPC de la passerelle secrets.reload.
  • Si l'évaluation échoue, la passerelle conserve le dernier instantané valide connu et retourne une erreur (pas d'activation partielle).
  • La réponse JSON inclut warningCount.

Audit​

Analyse l'état d'OpenClaw pour détecter :

  • le stockage de secrets en texte clair
  • les références non résolues
  • les dérives de priorité (les identifiants de auth-profiles.json éclipsant les références de openclaw.json)
  • les résidus générés agents/*/agent/models.json (valeurs apiKey des fournisseurs et en-têtes sensibles des fournisseurs)
  • les résidus hérités (entrées de l'ancien magasin d'authentification, rappels OAuth)

Note sur les résidus d'en-têtes :

  • La détection des en-têtes sensibles des fournisseurs est basée sur une heuristique de noms (noms d'en-têtes d'authentification/d'identification courants et fragments tels que authorization, x-api-key, token, secret, password et credential).
openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json

Comportement de sortie :

  • --check quitte avec un code non nul en cas de découvertes.
  • les références non résolues quittent avec un code non nul de priorité plus élevée.

Aperçu de la structure du rapport :

  • status : clean | findings | unresolved
  • summary : plaintextCount, unresolvedRefCount, shadowedRefCount, legacyResidueCount
  • codes de découverte :
    • PLAINTEXT_FOUND
    • REF_UNRESOLVED
    • REF_SHADOWED
    • LEGACY_RESIDUE

Configurer (assistant interactif)​

Construisez interactivement les modifications des fournisseurs et des SecretRefs, exécutez une prévérification et appliquez éventuellement :

openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json

Déroulement :

  • Configuration des fournisseurs d'abord (add/edit/remove pour les alias secrets.providers).
  • Mappage des identifiants ensuite (sélectionnez les champs et attribuez les références {source, provider, id}).
  • Pré-vérification et application optionnelle à la fin.

Drapeaux :

  • --providers-only : configure uniquement secrets.providers, ignore le mappage des identifiants.
  • --skip-provider-setup : ignore la configuration des fournisseurs et mappe les identifiants vers les fournisseurs existants.
  • --agent : limite la découverte des cibles et les écritures auth-profiles.json à un seul magasin d'agent.

Notes :

  • Nécessite un TTY interactif.
  • Vous ne pouvez pas combiner --providers-only avec --skip-provider-setup.
  • configure cible les champs porteurs de secrets dans openclaw.json ainsi que auth-profiles.json pour la portée d'agent sélectionnée.
  • configure prend en charge la création de nouveaux mappages auth-profiles.json directement dans le flux du sélecteur.
  • Surface prise en charge canonique : Surface d'identification SecretRef.
  • Il effectue une pré-vérification de résolution avant l'application.
  • Les plans générés activent par défaut les options de nettoyage (scrubEnv, scrubAuthProfilesForProviderTargets, scrubLegacyAuthJson tous activés).
  • Le chemin d'application est unidirectionnel pour les valeurs en texte clair nettoyées.
  • Sans --apply, la CLI demande toujours Appliquer ce plan maintenant ? après la pré-vérification.
  • Avec --apply (et sans --yes), la CLI demande une confirmation supplémentaire irréversible.

Note de sécurité sur le fournisseur exec :

  • Les installations Homebrew exposent souvent des binaires liés symboliquement sous /opt/homebrew/bin/*.
  • Définissez allowSymlinkCommand: true uniquement lorsque nécessaire pour les chemins de gestionnaires de paquets de confiance, et associez-le à trustedDirs (par exemple ["/opt/homebrew"]).
  • Sous Windows, si la vérification ACL n'est pas disponible pour un chemin de fournisseur, OpenClaw échoue en mode fermé. Pour les chemins de confiance uniquement, définissez allowInsecurePath: true sur ce fournisseur pour contourner les vérifications de sécurité des chemins.

Appliquer un plan sauvegardé​

Appliquez ou pré-vérifiez un plan généré précédemment :

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json

Détails du contrat de plan (chemins cibles autorisés, règles de validation et sémantique d'échec) :

Ce que apply peut mettre à jour :

  • openclaw.json (cibles SecretRef + ajouts/suppressions de fournisseurs)
  • auth-profiles.json (nettoyage des cibles des fournisseurs)
  • résidus de l'ancien auth.json
  • ~/.openclaw/.env clés secrètes connues dont les valeurs ont été migrées

Pourquoi pas de sauvegardes de restauration​

secrets apply n'écrit intentionnellement pas de sauvegardes de restauration contenant les anciennes valeurs en texte clair. La sécurité provient d'une pré-vérification stricte + d'une application atomique avec une restauration en mémoire de meilleur effort en cas d'échec.

Exemple​

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

Si audit --check signale encore des découvertes de texte clair, mettez à jour les chemins cibles restants signalés et relancez l'audit.

CLI Bac à sablesécurité