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 clair 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 : réussite complète, ou conservation du dernier instantané valide connu.
• 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 remise sortante (remise de réponses/fils Discord, envois d’actions Telegram) lisent également cet instantané et ne résolvent pas à nouveau les références à chaque envoi.

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

Injection au moment de la sortie (sentinelles)

Pour les identifiants de fournisseurs de modèles reposant sur des SecretRefs, OpenClaw crée une sentinelle opaque 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 à l’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 ne 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 par correspondance exacte, 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 dotés d’une option de récupération personnalisée reçoivent la fonction de récupération protégée d’OpenClaw, afin 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 appartenant à des Plugins et les infrastructures d’agents l’extraient lors du transfert final géré 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 du texte clair dans 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 clair qui ne sont pas configurés par l’intermédiaire de SecretRefs restent en texte clair 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 d’une réponse à incident ou d’un diagnostic de compatibilité. Ce mécanisme d’arrêt ne désactive pas l’enregistrement du masquage par correspondance exacte des valeurs.

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 ils ne constituent pas une limite d’isolation de processus. Un identifiant en texte clair laissé sur le disque dans un chemin lisible par l’agent reste accessible par les outils de fichiers ou de shell, 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 clair.
• Les anciens résidus en texte clair 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 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 externe d’identifiants.

C’est pourquoi le workflow d’audit/configuration/application constitue une barrière de migration de sécurité, et pas seulement un utilitaire 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/rechargement.
• Surfaces inactives : les références non résolues ne bloquent pas le démarrage/rechargement ; elles émettent un diagnostic non bloquant SECRETS_REF_IGNORED_INACTIVE_SURFACE.

Diagnostics des surfaces 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/rechargement du Gateway journalise 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/inactive.

L’entrée de journal inclut la raison utilisée par la stratégie de surface active.

Prévalidation des références lors de l’intégration initiale

Lors de l’intégration initiale interactive, le choix 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 initiale le résout avant l’amorçage de la sonde/du tableau de bord (pour les références env, file et exec) à l’aide de la même barrière d’échec immédiat.

Un échec de validation affiche l’erreur et vous permet de réessayer.

Contrat SecretRef

Une seule forme d’objet 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 d’API reposant sur des fichiers

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

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

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

Exemples d’intégration exec

{  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(`Échec de l’analyse de la requête : ${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 s’est terminé avec le code ${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 évite de stocker les clés d’API et les jetons en clair dans la configuration :

{  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 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 pendant 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.

Données d’authentification SSH du bac à sable

Le backend de bac à sable ssh du cœur prend également 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 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 autorisations de fichier restrictives (0o600) et utilisées dans la configuration SSH générée.
• Si le backend de bac à sable effectif n’est pas ssh (ou si le mode de 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 et non pris en charge 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 clair et une référence sont toutes deux présentes, la référence prévaut 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 lorsqu’elle est soumise comme donnée de configuration littérale.

Signaux d’avertissement et d’audit :

• SECRETS_REF_OVERRIDES_PLAINTEXT (avertissement à l’exécution)
• REF_SHADOWED (constat d’audit lorsque les identifiants de auth-profiles.json prévalent sur les références de openclaw.json)

Compatibilité Google Chat : serviceAccountRef prévaut sur la valeur en clair serviceAccount ; la valeur en clair 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 opérations suivantes :

• 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 contrôle la résolubilité des SecretRefs des 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é d’exécution actif restent tous deux inchangés.
• La fourniture explicite d’un jeton de canal propre à un appel à un assistant ou 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 au moment du rechargement échoue après un état sain, OpenClaw passe à un état dégradé des secrets et émet des événements système ponctuels et des codes de journal :

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Comportement :

• Dégradé : l’environnement d’exécution conserve le dernier instantané valide connu.
• Rétabli : é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 n’émettent pas de nouveau l’événement.
• L’échec immédiat au démarrage n’émet jamais d’événement de dégradation, car l’environnement d’exécution n’est jamais devenu actif.

Résolution des chemins de commande

Les chemins de commande peuvent activer la résolution des SecretRef prises en charge au moyen d’un RPC d’instantané du Gateway. Deux grands comportements s’appliquent :

Autres remarques :

• L’actualisation de l’instantané après la rotation d’un secret du système dorsal 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 de 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 demeure, même lorsque les API de l’environnement 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 de l’environnement d’exécution est validée avant la validation définitive.
• L’application met à jour les fichiers par remplacement atomique et tente de les restaurer en cas d’échec, dans la mesure du possible.

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

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

• La source des identifiants de l’environnement d’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 connexes

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