Gestion des secrets

OpenClaw prend en charge les SecretRefs additifs afin que les identifiants pris en charge n’aient pas besoin d’être stockés en clair dans la configuration.

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 avec empressement pendant l’activation, et non paresseusement sur les chemins de requête.
• Le démarrage échoue rapidement lorsqu’un SecretRef effectivement actif ne peut pas être résolu.
• Le rechargement utilise un échange atomique : réussite complète, ou conservation du dernier instantané valide connu.
• Les violations de la 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 réussie de la configuration, les chemins de code d’exécution continuent de lire cet instantané actif en mémoire jusqu’à ce qu’un rechargement réussi le remplace.
• Les chemins de livraison sortants lisent également cet instantané actif (par exemple la livraison de réponses/fils Discord et les envois d’actions Telegram) ; ils ne résolvent pas à nouveau les SecretRefs à chaque envoi.

Cela évite que les pannes du fournisseur de secrets affectent les chemins de requête critiques.

Limite d’accès de l’agent

Les SecretRefs empêchent la persistance des identifiants dans les surfaces de configuration et de modèles générés prises en charge, mais ils ne constituent pas une limite d’isolation de processus. Si un identifiant en clair reste sur le disque dans un chemin que l’agent peut lire, l’agent peut contourner la réduction d’information au niveau de l’API en utilisant des outils de fichier ou de shell pour inspecter ce fichier.

Pour les déploiements de production où les fichiers accessibles par l’agent sont concernés, considérez la migration SecretRef comme terminée uniquement lorsque toutes les conditions suivantes sont vraies :

• les identifiants pris en charge utilisent des SecretRefs au lieu de valeurs en clair
• les résidus hérités en clair ont été supprimés de openclaw.json, auth-profiles.json, .env et des fichiers models.json générés
• openclaw secrets audit --check est propre après la migration
• tout identifiant restant non pris en charge ou rotatif est protégé par l’isolation du système d’exploitation, l’isolation de conteneur ou un proxy d’identifiants externe

C’est pourquoi le flux audit/configuration/application est une barrière de migration de sécurité, et non un simple assistant de commodité.

Filtrage des surfaces actives

Les SecretRefs ne sont validés que sur les surfaces effectivement actives.

• Surfaces activées : les références non résolues bloquent le démarrage/rechargement.
• Surfaces inactives : les références non résolues ne bloquent pas le démarrage/rechargement.
• Les références inactives émettent des diagnostics non fatals avec le code SECRETS_REF_IGNORED_INACTIVE_SURFACE.

Diagnostics de la surface d’authentification Gateway

Lorsqu’un SecretRef est configuré 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 : le SecretRef fait partie de la surface d’authentification effective et doit être résolu.
• inactive : le SecretRef est ignoré pour cette exécution parce qu’une autre surface d’authentification l’emporte, ou parce que l’authentification distante est désactivée/inactive.

Ces entrées sont journalisées avec SECRETS_GATEWAY_AUTH_SURFACE et incluent la raison utilisée par la politique de surfaces actives, afin que vous puissiez voir pourquoi un identifiant a été traité comme actif ou inactif.

Prévalidation de référence pendant 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 :

• Références env : valide le nom de la variable env et confirme qu’une valeur non vide est visible pendant la configuration.
• Références fournisseur (file ou exec) : valide la sélection du fournisseur, résout id et vérifie le type de la valeur résolue.
• Chemin de réutilisation du quickstart : lorsque gateway.auth.token est déjà un SecretRef, l’onboarding le résout avant l’amorçage probe/dashboard (pour les références env, file et exec) en utilisant la même barrière d’échec rapide.

Si la validation échoue, l’onboarding affiche l’erreur et vous permet de réessayer.

Contrat SecretRef

Utilisez une forme d’objet unique partout :

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

"${OPENAI_API_KEY}""$OPENAI_API_KEY"

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

{ source: "exec", provider: "vault", id: "providers/openai/apiKey#value" }

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,      },      "team-secrets": {        source: "exec",        pluginIntegration: {          pluginId: "acme-secrets",          integrationId: "secret-store",        },      },    },    defaults: {      env: "default",      file: "filemain",      exec: "vault",    },    resolution: {      maxProviderConcurrency: 4,      maxRefsPerProvider: 512,      maxBatchBytes: 262144,    },  },}

{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret

{  "protocolVersion": 1,  "values": {},  "errors": { "providers/openai/apiKey": { "message": "not found" } }}

Clés d’API adossées à des fichiers

Ne placez pas de chaînes file:... dans le bloc env de la configuration. Le bloc env est littéral et non prioritaire, donc file:... n’est pas résolu.

Utilisez plutôt un SecretRef de fichier sur un champ d’identifiant pris en charge :

{  secrets: {    providers: {      xai_key_file: {        source: "file",        path: "~/.openclaw/secrets/xai-api-key.txt",        mode: "singleValue",      },    },  },  models: {    providers: {      xai: {        apiKey: { source: "file", provider: "xai_key_file", id: "value" },      },    },  },}

Pour mode: "singleValue", l’id SecretRef est "value". Pour mode: "json", utilisez un pointeur JSON absolu tel que "/providers/xai/apiKey".

Consultez Surface d’identifiants SecretRef pour les champs de configuration qui acceptent les SecretRefs.

Exemples d’intégration exec

{  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" },      },    },  },}

{  secrets: {    providers: {      bws: {        source: "exec",        command: "/usr/local/bin/openclaw-bws-resolver.mjs",        passEnv: ["BWS_ACCESS_TOKEN", "BWS_SERVER_URL", "PATH", "BWS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "bws",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --allow-exec

{  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" },      },    },  },}

#!/usr/bin/env nodeconst { spawnSync } = require("node:child_process"); let stdin = "";process.stdin.setEncoding("utf8");process.stdin.on("data", (chunk) => {  stdin += chunk;});process.stdin.on("error", (err) => {  process.stderr.write(`${err.message}\n`);  process.exit(1);});process.stdin.on("end", () => {  let request;  try {    request = JSON.parse(stdin || "{}");  } catch (err) {    process.stderr.write(`Failed to parse request: ${err.message}\n`);    process.exit(1);  }   const passBin = process.env.PASS_BIN || "pass";  const values = {};  const errors = {};   for (const id of request.ids ?? []) {    const result = spawnSync(passBin, ["show", id], { encoding: "utf8" });    if (result.status === 0) {      values[id] = result.stdout.split(/\r?\n/, 1)[0] ?? "";    } else {      errors[id] = { message: (result.stderr || `pass exited ${result.status}`).trim() };    }  }   process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));});

{  secrets: {    providers: {      pass_store: {        source: "exec",        command: "/usr/local/bin/openclaw-pass-resolver",        passEnv: ["PATH", "HOME", "GNUPGHOME", "GPG_TTY", "PASSWORD_STORE_DIR", "PASS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "pass_store",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --checkopenclaw secrets audit --allow-exec

{  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 une configuration en texte 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 texte clair fonctionnent toujours. Les références de modèle d’environnement comme ${MCP_SERVER_API_KEY} et les objets SecretRef sont résolus pendant l’activation du Gateway, avant la création du processus du serveur MCP. Comme pour les autres surfaces SecretRef, les références non résolues ne bloquent l’activation que lorsque le plugin acpx est effectivement actif.

Données d’authentification SSH du sandbox

Le backend de sandbox principal ssh prend aussi en charge les SecretRefs pour les données 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 à l’exécution :

• OpenClaw résout ces références pendant l’activation du sandbox, pas 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 sandbox 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 listés dans :

• Surface des identifiants SecretRef

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 clair et une référence sont tous deux présents, la référence est prioritaire sur les chemins de précédence pris en charge.
• La sentinelle de masquage __OPENCLAW_REDACTED__ est réservée au masquage et à la restauration internes de la configuration, et elle 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 identifiants auth-profiles.json sont prioritaires sur les références openclaw.json)

Comportement de compatibilité Google Chat :

• serviceAccountRef est prioritaire sur serviceAccount en 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éflight plus activation finale)
• Chemin d’application à chaud du rechargement de configuration
• Chemin de vérification avec redémarrage du rechargement de configuration
• Rechargement manuel via secrets.reload
• Préflight RPC d’écriture de configuration du Gateway (config.set / config.apply / config.patch) pour vérifier que les SecretRefs des surfaces actives peuvent être résolus dans la charge utile de configuration soumise avant de persister les 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éflight d’écriture RPC rejette la configuration soumise et laisse inchangés la configuration sur disque et l’instantané d’exécution actif.
• Fournir un jeton de canal explicite par appel à un appel sortant d’assistant ou d’outil ne déclenche pas l’activation SecretRef ; les points d’activation restent le démarrage, le rechargement et secrets.reload explicite.

Signaux dégradés et récupérés

Quand l’activation au moment du rechargement échoue après un état sain, OpenClaw passe à l’état de secrets dégradé.

Codes d’événement système ponctuel et de journal :

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Comportement :

• Dégradé : l’exécution conserve le dernier instantané valide connu.
• Récupéré : émis une 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 commandes

Les chemins de commandes peuvent opter pour la résolution SecretRef prise en charge via la RPC d’instantané du Gateway.

Il existe deux grands comportements :

Autres notes :

• Le rafraîchissement de l’instantané après rotation de secret backend est géré par openclaw secrets reload.
• Méthode RPC du Gateway utilisée par ces chemins de commande : secrets.resolve.

Flux d’audit et de configuration

Flux opérateur par défaut :

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

Ne considérez pas la migration comme terminée tant que le réaudit n’est pas propre. Si l’audit signale encore des valeurs en clair au repos, le risque d’accès par l’agent est toujours présent même lorsque les API du runtime renvoient des valeurs masquées.

Si vous enregistrez un plan au lieu de l’appliquer pendant configure, appliquez ce plan enregistré avec openclaw secrets apply --from <plan-path> avant le réaudit.

openclaw secrets apply --from /tmp/openclaw-secrets-plan.jsonopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-runopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec

Politique de sécurité à sens unique

Modèle de sécurité :

• la vérification préliminaire doit réussir avant le mode écriture
• l’activation du runtime est validée avant la validation finale
• apply met à jour les fichiers avec remplacement atomique et restauration au mieux en cas d’échec

Notes de compatibilité de l’auth héritée

Pour les identifiants statiques, le runtime ne dépend plus du stockage auth hérité en clair.

• La source des identifiants du runtime est l’instantané résolu en mémoire.
• Les entrées héritées statiques api_key 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.

Connexe

• Authentification — configuration auth
• 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é