25 KiB
25 KiB
| read_when | sidebarTitle | summary | title | x-i18n | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Secrets management | Gestion des secrets : contrat SecretRef, comportement des instantanés d’exécution et nettoyage irréversible sécurisé | Gestion des secrets |
|
OpenClaw prend en charge les SecretRefs additives afin que les identifiants pris en charge n’aient pas besoin d’être stockés en clair dans la configuration.
Le texte en clair fonctionne toujours. Les SecretRefs sont optionnelles pour chaque identifiant.Objectifs et modèle d’exécution
Les secrets sont résolus dans un instantané d’exécution en mémoire.
- La résolution est effectuée de manière anticipée pendant l’activation, pas paresseusement sur les chemins de requête.
- Le démarrage échoue rapidement lorsqu’une SecretRef effectivement active ne peut pas être résolue.
- Le rechargement utilise un échange atomique : réussite complète, ou conservation du dernier instantané valide connu.
- Les violations de politique SecretRef (par exemple des profils d’authentification en mode OAuth combinés à une entrée SecretRef) font échouer l’activation avant l’échange d’exécution.
- Les requêtes d’exécution lisent uniquement l’instantané actif en mémoire.
- Après la première activation/charge de configuration réussie, les chemins de code d’exécution continuent à lire cet instantané actif en mémoire jusqu’à ce qu’un rechargement réussi le remplace.
- Les chemins de livraison sortants lisent également depuis cet instantané actif (par exemple la livraison de réponses/fils Discord et les envois d’actions Telegram) ; ils ne re-résolvent pas les SecretRefs à chaque envoi.
Cela maintient les pannes de fournisseurs de secrets hors des chemins de requête critiques.
Filtrage des surfaces actives
Les SecretRefs sont validées uniquement sur les surfaces effectivement actives.
- Surfaces activées : les refs non résolues bloquent le démarrage/rechargement.
- Surfaces inactives : les refs non résolues ne bloquent pas le démarrage/rechargement.
- Les refs inactives émettent des diagnostics non fatals avec le code
SECRETS_REF_IGNORED_INACTIVE_SURFACE.
Diagnostics de surface d’authentification du Gateway
Lorsqu’une SecretRef est configurée sur gateway.auth.token, gateway.auth.password, gateway.remote.token ou gateway.remote.password, le démarrage/rechargement du Gateway journalise explicitement l’état de la surface :
active: la SecretRef fait partie de la surface d’authentification effective et doit être résolue.inactive: la SecretRef est ignorée pour cette exécution, car une autre surface d’authentification prévaut, ou parce que l’authentification distante est désactivée/non active.
Ces entrées sont journalisées avec SECRETS_GATEWAY_AUTH_SURFACE et incluent la raison utilisée par la politique de surface active, afin que vous puissiez voir pourquoi un identifiant a été traité comme actif ou inactif.
Prévalidation des références lors de l’onboarding
Lorsque l’onboarding s’exécute en mode interactif et que vous choisissez le stockage SecretRef, OpenClaw exécute une validation préalable avant l’enregistrement :
- Refs env : valide le nom de variable d’environnement et confirme qu’une valeur non vide est visible pendant la configuration.
- Refs de fournisseur (
fileouexec) : valide la sélection du fournisseur, résoutidet vérifie le type de la valeur résolue. - Chemin de réutilisation quickstart : lorsque
gateway.auth.tokenest déjà une SecretRef, l’onboarding la résout avant le bootstrap de la sonde/du tableau de bord (pour les refsenv,fileetexec) avec le même garde-fou d’échec rapide.
Si la validation échoue, l’onboarding affiche l’erreur et vous permet de réessayer.
Contrat SecretRef
Utilisez partout la même forme d’objet :
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
Validation :
- `provider` doit correspondre à `^[a-z][a-z0-9_-]{0,63}$`
- `id` doit correspondre à `^[A-Z][A-Z0-9_]{0,127}$`
Validation :
- `provider` doit correspondre à `^[a-z][a-z0-9_-]{0,63}$`
- `id` doit être un pointeur JSON absolu (`/...`)
- Échappement RFC6901 dans les segments : `~` => `~0`, `/` => `~1`
Validation :
- `provider` doit correspondre à `^[a-z][a-z0-9_-]{0,63}$`
- `id` doit correspondre à `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$`
- `id` ne doit pas contenir `.` ou `..` comme segments de chemin délimités par des barres obliques (par exemple `a/../b` est rejeté)
Configuration des fournisseurs
Définissez les fournisseurs sous secrets.providers :
{
secrets: {
providers: {
default: { source: "env" },
filemain: {
source: "file",
path: "~/.openclaw/secrets.json",
mode: "json", // or "singleValue"
},
vault: {
source: "exec",
command: "/usr/local/bin/openclaw-vault-resolver",
args: ["--profile", "prod"],
passEnv: ["PATH", "VAULT_ADDR"],
jsonOnly: true,
},
},
defaults: {
env: "default",
file: "filemain",
exec: "vault",
},
resolution: {
maxProviderConcurrency: 4,
maxRefsPerProvider: 512,
maxBatchBytes: 262144,
},
},
}
Charge utile de requête (stdin) :
```json
{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }
```
Charge utile de réponse (stdout) :
```jsonc
{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret
```
Erreurs optionnelles par id :
```json
{
"protocolVersion": 1,
"values": {},
"errors": { "providers/openai/apiKey": { "message": "not found" } }
}
```
Exemples d’intégration exec
```json5 { secrets: { providers: { onepassword_openai: { source: "exec", command: "/opt/homebrew/bin/op", allowSymlinkCommand: true, // required for Homebrew symlinked binaries trustedDirs: ["/opt/homebrew"], args: ["read", "op://Personal/OpenClaw QA API Key/password"], passEnv: ["HOME"], jsonOnly: false, }, }, }, models: { providers: { openai: { baseUrl: "https://api.openai.com/v1", models: [{ id: "gpt-5", name: "gpt-5" }], apiKey: { source: "exec", provider: "onepassword_openai", id: "value" }, }, }, }, } ``` ```json5 { secrets: { providers: { vault_openai: { source: "exec", command: "/opt/homebrew/bin/vault", allowSymlinkCommand: true, // required for Homebrew symlinked binaries trustedDirs: ["/opt/homebrew"], args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"], passEnv: ["VAULT_ADDR", "VAULT_TOKEN"], jsonOnly: false, }, }, }, models: { providers: { openai: { baseUrl: "https://api.openai.com/v1", models: [{ id: "gpt-5", name: "gpt-5" }], apiKey: { source: "exec", provider: "vault_openai", id: "value" }, }, }, }, } ``` ```json5 { secrets: { providers: { sops_openai: { source: "exec", command: "/opt/homebrew/bin/sops", allowSymlinkCommand: true, // required for Homebrew symlinked binaries trustedDirs: ["/opt/homebrew"], args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"], passEnv: ["SOPS_AGE_KEY_FILE"], jsonOnly: false, }, }, }, models: { providers: { openai: { baseUrl: "https://api.openai.com/v1", models: [{ id: "gpt-5", name: "gpt-5" }], apiKey: { source: "exec", provider: "sops_openai", id: "value" }, }, }, }, } ```Variables d’environnement du serveur MCP
Les variables d’environnement du serveur MCP configurées via plugins.entries.acpx.config.mcpServers prennent en charge SecretInput. Cela évite de placer les clés API et les jetons dans la configuration en clair :
{
plugins: {
entries: {
acpx: {
enabled: true,
config: {
mcpServers: {
github: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-github"],
env: {
GITHUB_PERSONAL_ACCESS_TOKEN: {
source: "env",
provider: "default",
id: "MCP_GITHUB_PAT",
},
},
},
},
},
},
},
},
}
Les valeurs de chaîne en clair fonctionnent toujours. Les refs de modèle d’environnement comme ${MCP_SERVER_API_KEY} et les objets SecretRef sont résolus pendant l’activation du Gateway avant que le processus du serveur MCP ne soit lancé. Comme pour les autres surfaces SecretRef, les refs non résolues bloquent l’activation uniquement lorsque le Plugin acpx est effectivement actif.
Matériel d’authentification SSH du bac à sable
Le backend de bac à sable ssh du cœur prend également en charge les SecretRefs pour le matériel d’authentification SSH :
{
agents: {
defaults: {
sandbox: {
mode: "all",
backend: "ssh",
ssh: {
target: "user@gateway-host:22",
identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
},
},
},
},
}
Comportement d’exécution :
- OpenClaw résout ces références pendant l’activation du bac à sable, et non paresseusement lors de chaque appel SSH.
- Les valeurs résolues sont écrites dans des fichiers temporaires avec des permissions restrictives et utilisées dans la configuration SSH générée.
- Si le backend de bac à sable effectif n’est pas
ssh, ces références restent inactives et ne bloquent pas le démarrage.
Surface d’identifiants prise en charge
Les identifiants canoniques pris en charge et non pris en charge sont répertoriés dans :
Les identifiants créés à l’exécution ou rotatifs et le matériel d’actualisation OAuth sont volontairement exclus de la résolution SecretRef en lecture seule.Comportement requis et précédence
- Champ sans référence : inchangé.
- Champ avec référence : requis sur les surfaces actives pendant l’activation.
- Si du texte en clair et une référence sont tous deux présents, la référence a priorité sur les chemins de précédence pris en charge.
- La sentinelle de caviardage
__OPENCLAW_REDACTED__est réservée au caviardage et à la restauration internes de la configuration, et est rejetée comme donnée de configuration littérale soumise.
Signaux d’avertissement et d’audit :
SECRETS_REF_OVERRIDES_PLAINTEXT(avertissement à l’exécution)REF_SHADOWED(constat d’audit lorsque les identifiantsauth-profiles.jsonont priorité sur les référencesopenclaw.json)
Comportement de compatibilité Google Chat :
serviceAccountRefa priorité sur leserviceAccounten texte clair.- La valeur en texte clair est ignorée lorsque la référence sœur est définie.
Déclencheurs d’activation
L’activation des secrets s’exécute lors de :
- Démarrage (précontrôle puis activation finale)
- Chemin d’application à chaud du rechargement de configuration
- Chemin de vérification de redémarrage du rechargement de configuration
- Rechargement manuel via
secrets.reload - Précontrôle RPC d’écriture de configuration du Gateway (
config.set/config.apply/config.patch) pour la résolubilité SecretRef de surface active dans la charge utile de configuration soumise avant la persistance des modifications
Contrat d’activation :
- Une réussite remplace l’instantané atomiquement.
- Un échec au démarrage interrompt le démarrage du Gateway.
- Un échec de rechargement à l’exécution conserve le dernier instantané valide connu.
- Un échec de précontrôle Write-RPC rejette la configuration soumise et laisse à la fois la configuration disque et l’instantané d’exécution actif inchangés.
- Fournir un jeton de canal explicite par appel à un appel d’assistant ou d’outil sortant ne déclenche pas l’activation SecretRef ; les points d’activation restent le démarrage, le rechargement et
secrets.reloadexplicite.
Signaux de dégradation et de récupération
Lorsque l’activation au moment du rechargement échoue après un état sain, OpenClaw entre dans un état de secrets dégradé.
Événement système unique et codes de journalisation :
SECRETS_RELOADER_DEGRADEDSECRETS_RELOADER_RECOVERED
Comportement :
- Dégradé : l’exécution conserve le dernier instantané valide connu.
- Récupéré : émis une seule fois après la prochaine activation réussie.
- Les échecs répétés alors que l’état est déjà dégradé journalisent des avertissements, mais ne saturent pas les événements.
- L’échec rapide au démarrage n’émet pas d’événements dégradés, car l’exécution n’est jamais devenue active.
Résolution des chemins de commande
Les chemins de commande peuvent opter pour la résolution SecretRef prise en charge via la RPC d’instantané du Gateway.
Il existe deux grands comportements :
Par exemple les chemins de mémoire distante `openclaw memory` et `openclaw qr --remote` lorsqu’ils nécessitent des références de secret partagé distant. Ils lisent depuis l’instantané actif et échouent rapidement lorsqu’un SecretRef requis est indisponible. Par exemple `openclaw status`, `openclaw status --all`, `openclaw channels status`, `openclaw channels resolve`, `openclaw security audit`, ainsi que les flux de doctor/config repair en lecture seule. Ils préfèrent aussi l’instantané actif, mais se dégradent au lieu d’abandonner lorsqu’un SecretRef ciblé est indisponible dans ce chemin de commande.Comportement en lecture seule :
- Lorsque le Gateway est en cours d’exécution, ces commandes lisent d’abord depuis l’instantané actif.
- Si la résolution du Gateway est incomplète ou si le Gateway est indisponible, elles tentent un repli local ciblé pour la surface de commande spécifique.
- Si un SecretRef ciblé reste indisponible, la commande continue avec une sortie en lecture seule dégradée et des diagnostics explicites tels que « configuré mais indisponible dans ce chemin de commande ».
- Ce comportement dégradé est uniquement local à la commande. Il n’affaiblit pas les chemins de démarrage, de rechargement, d’envoi ou d’authentification à l’exécution.
Autres notes :
- L’actualisation de l’instantané après rotation de secret backend est gérée par
openclaw secrets reload. - Méthode RPC du Gateway utilisée par ces chemins de commande :
secrets.resolve.
Workflow d’audit et de configuration
Flux opérateur par défaut :
```bash openclaw secrets audit --check ``` ```bash openclaw secrets configure ``` ```bash openclaw secrets audit --check ``` Les constats incluent :- valeurs en texte clair au repos (`openclaw.json`, `auth-profiles.json`, `.env` et `agents/*/agent/models.json` généré)
- résidus d’en-têtes fournisseur sensibles en texte clair dans les entrées `models.json` générées
- références non résolues
- masquage par précédence (`auth-profiles.json` prioritaire sur les références `openclaw.json`)
- résidus hérités (`auth.json`, rappels OAuth)
Note d’exécution :
- Par défaut, l’audit ignore les vérifications de résolubilité SecretRef exec afin d’éviter les effets de bord des commandes.
- Utilisez `openclaw secrets audit --allow-exec` pour exécuter les fournisseurs exec pendant l’audit.
Note sur les résidus d’en-têtes :
- La détection des en-têtes fournisseur sensibles repose sur une heuristique de noms (noms et fragments courants d’en-têtes d’authentification ou d’identifiants tels que `authorization`, `x-api-key`, `token`, `secret`, `password` et `credential`).
- configure d’abord `secrets.providers` (`env`/`file`/`exec`, ajouter/modifier/supprimer)
- vous permet de sélectionner les champs pris en charge contenant des secrets dans `openclaw.json`, ainsi que `auth-profiles.json` pour une portée d’agent
- peut créer un nouveau mappage `auth-profiles.json` directement dans le sélecteur de cible
- capture les détails SecretRef (`source`, `provider`, `id`)
- exécute une résolution de précontrôle
- peut appliquer immédiatement
Note d’exécution :
- Le précontrôle ignore les vérifications SecretRef exec sauf si `--allow-exec` est défini.
- Si vous appliquez directement depuis `configure --apply` et que le plan inclut des références/fournisseurs exec, gardez aussi `--allow-exec` défini pour l’étape d’application.
Modes utiles :
- `openclaw secrets configure --providers-only`
- `openclaw secrets configure --skip-provider-setup`
- `openclaw secrets configure --agent <id>`
Valeurs par défaut d’application de `configure` :
- nettoyer les identifiants statiques correspondants de `auth-profiles.json` pour les fournisseurs ciblés
- nettoyer les entrées `api_key` statiques héritées de `auth.json`
- nettoyer les lignes de secrets connus correspondantes de `<config-dir>/.env`
```bash
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
```
Note d’exécution :
- dry-run ignore les vérifications exec sauf si `--allow-exec` est défini.
- le mode écriture rejette les plans contenant des SecretRefs/fournisseurs exec sauf si `--allow-exec` est défini.
Pour les détails stricts du contrat cible/chemin et les règles exactes de rejet, consultez [Contrat de plan Secrets Apply](/fr/gateway/secrets-plan-contract).
Politique de sécurité à sens unique
OpenClaw n’écrit volontairement pas de sauvegardes de restauration contenant des valeurs secrètes historiques en texte clair.Modèle de sécurité :
- le précontrôle doit réussir avant le mode écriture
- l’activation à l’exécution est validée avant la validation
- l’application met à jour les fichiers avec remplacement atomique et restauration au mieux en cas d’échec
Notes de compatibilité de l’authentification héritée
Pour les identifiants statiques, l’exécution ne dépend plus du stockage d’authentification hérité en texte clair.
- La source des identifiants d’exécution est l’instantané en mémoire résolu.
- Les entrées
api_keystatiques héritées sont nettoyées lorsqu’elles sont découvertes. - Le comportement de compatibilité lié à OAuth reste séparé.
Note sur l’interface Web
Certaines unions SecretInput sont plus faciles à configurer en mode éditeur brut qu’en mode formulaire.
Associé
- Authentification — configuration de l’authentification
- CLI : secrets — commandes CLI
- Variables d’environnement — précédence de l’environnement
- Surface d’identifiants SecretRef — surface d’identifiants
- Contrat de plan Secrets Apply — détails du contrat de plan
- Sécurité — posture de sécurité