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 texte brut dans la configuration.

Modèle d’exécution

• Les secrets sont résolus dans un instantané d’exécution en mémoire, de manière anticipée lors de l’activation, et non à la demande dans les chemins de requête.
• Le démarrage échoue immédiatement lorsqu’un SecretRef effectivement actif ne peut pas être résolu.
• Le rechargement est un remplacement atomique : soit il réussit entièrement, soit le dernier instantané valide connu est conservé.
• Les violations de stratégie (par exemple, un profil d’authentification en mode OAuth combiné à une entrée SecretRef) font échouer l’activation avant le remplacement de l’instantané d’exécution.
• Les requêtes d’exécution lisent uniquement l’instantané actif en mémoire. Les identifiants SecretRef des fournisseurs de modèles transitent par le stockage d’authentification et les options de flux sous forme de sentinelles locales au processus jusqu’à leur sortie. Les chemins de livraison sortante (livraison des réponses et fils de discussion Discord, envois d’actions Telegram) lisent également cet instantané et ne résolvent pas de nouveau les références à chaque envoi.

Cela évite que les indisponibilités des fournisseurs de secrets affectent les chemins critiques des requêtes.

Injection à la sortie (sentinelles)

Pour les identifiants de fournisseurs de modèles reposant sur des SecretRefs, OpenClaw crée une sentinelle opaque et locale au processus lors de la résolution de l’authentification du modèle. Le stockage d’authentification, les options de flux, la configuration du SDK, les journaux, les objets d’erreur et la plupart des mécanismes d’introspection d’exécution voient donc une valeur telle que oc-sent-v1-..., et non l’identifiant du fournisseur. La récupération protégée du modèle et les sondes d’intégrité gérées des fournisseurs locaux remplacent les sentinelles connues dans les valeurs d’URL et d’en-tête juste avant que chaque requête quitte le processus.

Les valeurs inconnues ayant la forme d’une sentinelle provoquent un échec sécurisé avant toute activité réseau. OpenClaw refuse d’envoyer la requête plutôt que de transmettre une sentinelle non résolue à un fournisseur. Les valeurs de secrets résolues sont également enregistrées afin d’être masquées dans les journaux lorsqu’elles correspondent exactement, comme mesure de défense en profondeur.

Les adaptateurs de fournisseurs utilisent le point d’injection le plus tardif pris en charge par leur SDK :

• Les SDK disposant d’une option de récupération personnalisée reçoivent la fonction de récupération protégée d’OpenClaw, de sorte que le SDK conserve la sentinelle.
• Les SDK dépourvus d’option de récupération personnalisée extraient la valeur de la sentinelle juste avant la construction du client. Les flux de fournisseurs détenus par des Plugins et les environnements d’exécution d’agents l’extraient lors du dernier transfert détenu par le cœur, car ces transports ne partagent pas la fonction de récupération protégée d’OpenClaw.

Les sentinelles réduisent l’exposition en texte brut tout au long de la chaîne d’appel du modèle, mais elles ne constituent pas une isolation de processus. La valeur réelle existe toujours dans la mémoire du même processus et apparaît à la limite de l’adaptateur final. Les identifiants d’environnement en texte brut qui ne sont pas configurés au moyen de SecretRefs restent en texte brut et ne relèvent pas de ce mécanisme.

Définissez OPENCLAW_SECRET_SENTINELS=off (accepte également 0 ou false, sans distinction entre majuscules et minuscules) pour désactiver la création de sentinelles lors de la réponse à un incident ou du dépannage de problèmes de compatibilité. Ce mécanisme d’arrêt d’urgence ne désactive pas l’enregistrement du masquage des valeurs exactes.

Limite d’accès de l’agent

Les SecretRefs empêchent la persistance des identifiants dans la configuration et les fichiers de modèles générés, mais ne constituent pas une limite d’isolation de processus. Un identifiant en texte brut laissé sur le disque dans un chemin accessible en lecture par l’agent reste lisible au moyen des outils de fichiers ou d’interpréteur de commandes, contournant ainsi le masquage au niveau de l’API.

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

• Les identifiants pris en charge utilisent des SecretRefs plutôt que des valeurs en texte brut.
• Les anciens résidus en texte brut sont supprimés de openclaw.json, auth-profiles.json, .env et des fichiers models.json générés.
• openclaw secrets audit --check ne signale plus aucun problème après la migration.
• Tous les identifiants restants non pris en charge ou soumis à rotation sont protégés par une isolation du système d’exploitation, une isolation de conteneur ou un proxy d’identifiants externe.

C’est pourquoi le flux d’audit, de configuration et d’application constitue une étape de sécurité obligatoire de la migration, et pas seulement un outil pratique.

Filtrage des surfaces actives

Les SecretRefs sont validés uniquement sur les surfaces effectivement actives :

• Surfaces activées : les références non résolues bloquent le démarrage ou le rechargement.
• Surfaces inactives : les références non résolues ne bloquent pas le démarrage ou le rechargement ; elles produisent un diagnostic SECRETS_REF_IGNORED_INACTIVE_SURFACE non fatal.

Diagnostics de la surface d’authentification du Gateway

Lorsqu’un SecretRef est défini sur gateway.auth.token, gateway.auth.password, gateway.remote.token ou gateway.remote.password, le démarrage ou le rechargement du Gateway consigne l’état de la surface sous le code SECRETS_GATEWAY_AUTH_SURFACE :

• active : le SecretRef fait partie de la surface d’authentification effective et doit être résolu.
• inactive : une autre surface d’authentification prévaut, ou l’authentification distante est désactivée ou inactive.

L’entrée de journal comprend la raison appliquée par la stratégie de surface active.

Vérification préalable des références lors de l’intégration

Lors de l’intégration interactive, la sélection du stockage SecretRef exécute une validation préalable avant l’enregistrement :

• Références d’environnement : valide le nom de la variable d’environnement et confirme qu’une valeur non vide est visible pendant la configuration.
• Références de fournisseur (file ou exec) : valide la sélection du fournisseur, résout id et vérifie le type de la valeur résolue.
• Flux de démarrage rapide : lorsque gateway.auth.token est déjà un SecretRef, l’intégration le résout avant la sonde ou l’initialisation du tableau de bord (pour les références env, file et exec) en utilisant le même mécanisme d’échec immédiat.

En cas d’échec de la validation, l’erreur s’affiche et vous pouvez réessayer.

Contrat SecretRef

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", // ou "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": { "code": "NOT_FOUND" } }}

Clés API stockées dans des fichiers

Ne placez pas de chaînes file:... dans le bloc env de la configuration. Ce bloc est littéral et ne permet aucune substitution ; file:... n’y est donc jamais résolu.

Utilisez plutôt une SecretRef de fichier sur un champ d’identification 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", la SecretRef id est "value". Pour mode: "json", utilisez un pointeur JSON absolu tel que "/providers/xai/apiKey".

Consultez Surface d’identification SecretRef pour connaître les champs qui acceptent des SecretRefs.

Exemples d’intégration exec

Pour consulter un guide consacré à 1Password couvrant les comptes de service, la compétence d’agent incluse et le dépannage, consultez 1Password.

{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // requis pour les binaires Homebrew liés symboliquement        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, // requis pour les binaires Homebrew liés symboliquement        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, // requis pour les binaires Homebrew liés symboliquement        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 des serveurs MCP

Les variables d’environnement des serveurs MCP configurées via plugins.entries.acpx.config.mcpServers acceptent SecretInput, ce qui permet de conserver les clés API et les jetons hors de la 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 restent prises en charge. Les références de modèle d’environnement telles que ${MCP_SERVER_API_KEY} et les objets SecretRef sont résolus lors de l’activation du Gateway, avant le lancement 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.

Éléments d’authentification SSH du bac à sable

Le moteur de bac à sable principal ssh prend également en charge les SecretRefs pour les éléments 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 lors de l’activation du bac à sable, et non de manière différée à chaque appel SSH.
• Les valeurs résolues sont écrites dans un répertoire temporaire avec des permissions de fichiers restrictives (0o600) et utilisées dans la configuration SSH générée.
• Si le backend effectif du bac à sable n’est pas ssh (ou si le mode du bac à sable est off), 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 ou non sont répertoriés dans Surface d’identifiants SecretRef.

Comportement requis et priorité

• Champ sans référence : inchangé.
• Champ avec une référence : requis sur les surfaces actives pendant l’activation.
• Si une valeur en texte brut et une référence sont toutes deux présentes, la référence est prioritaire sur les chemins de priorité pris en charge.
• La sentinelle de masquage __OPENCLAW_REDACTED__ est réservée au masquage et à la restauration internes de la configuration ; elle est rejetée en tant que 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)

Compatibilité avec Google Chat : serviceAccountRef est prioritaire sur la valeur en texte brut serviceAccount ; la valeur en texte brut est ignorée dès que la référence associée est définie.

Déclencheurs d’activation

L’activation des secrets s’exécute lors des événements suivants :

• Démarrage (vérification préalable, puis activation finale)
• Chemin d’application à chaud du rechargement de la configuration
• Chemin de vérification du redémarrage lors du rechargement de la configuration
• Rechargement manuel via secrets.reload
• Vérification préalable du RPC d’écriture de la configuration du Gateway (config.set / config.apply / config.patch), qui vérifie la résolvabilité des SecretRef sur les surfaces actives dans la charge utile de configuration soumise avant de conserver les modifications

Contrat d’activation :

• En cas de réussite, l’instantané est remplacé de manière atomique.
• Un échec au démarrage interrompt le démarrage du Gateway.
• Un échec du rechargement à l’exécution conserve le dernier instantané valide connu.
• Un échec de la vérification préalable du RPC d’écriture rejette la configuration soumise ; la configuration sur disque et l’instantané actif à l’exécution restent tous deux inchangés.
• Fournir un jeton de canal explicite propre à l’appel à un assistant ou à un outil sortant ne déclenche pas l’activation de SecretRef ; les points d’activation restent le démarrage, le rechargement et l’appel explicite à secrets.reload.

Signaux de dégradation et de récupération

Lorsque l’activation lors du rechargement échoue après un état sain, OpenClaw passe à un état dégradé des secrets et émet une seule fois des événements système et des codes de journalisation :

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Comportement :

• État dégradé : l’exécution conserve le dernier instantané valide connu.
• Récupération : signal émis une seule fois après l’activation réussie suivante.
• Les échecs répétés alors que l’état est déjà dégradé consignent des avertissements, mais ne réémettent pas l’événement.
• L’échec immédiat au démarrage n’émet jamais d’événement de dégradation, car l’exécution n’est jamais devenue active.

Résolution des chemins de commande

Les chemins de commande peuvent activer la résolution SecretRef prise en charge par l’intermédiaire d’un RPC d’instantané du Gateway. Deux comportements généraux s’appliquent :

Autres remarques :

• L’actualisation de l’instantané après la rotation d’un secret du backend est gérée 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 par défaut pour l’opérateur :

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

Ne considérez pas la migration comme terminée tant que le nouvel audit n’est pas exempt de problèmes. Si l’audit signale encore des valeurs en texte brut au repos, le risque d’accès par l’agent subsiste, même lorsque les API d’exécution 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 nouvel 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éalable doit réussir avant le mode écriture.
• L’activation à l’exécution est validée avant la validation définitive.
• L’application met à jour les fichiers au moyen d’un remplacement atomique et tente, dans la mesure du possible, de les restaurer en cas d’échec.

Remarques sur la compatibilité avec l’authentification héritée

Pour les identifiants statiques, l’exécution ne dépend plus du stockage d’authentification hérité en texte brut.

• La source des identifiants à l’exécution est l’instantané résolu en mémoire.
• Les entrées statiques héritées api_key sont supprimées lorsqu’elles sont détectées.
• Le comportement de compatibilité lié à OAuth reste distinct.

Remarque sur l’interface Web

Certaines unions SecretInput sont plus faciles à configurer en mode éditeur brut qu’en mode formulaire.

Pages associées

• Authentification - configuration de l’authentification
• CLI : secrets - commandes CLI
• SecretRef de Vault - configuration du fournisseur HashiCorp Vault
• Variables d’environnement - priorité des variables d’environnement
• Surface d’identifiants SecretRef - surface d’identifiants
• Contrat du plan d’application des secrets - détails du contrat du plan
• Sécurité - posture de sécurité