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.

# 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 (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 quickstart : lorsque gateway.auth.token est déjà une SecretRef, l’onboarding la résout avant le bootstrap de la sonde/du tableau de bord (pour les refs env, file et exec) 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: "..." }

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

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

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

# 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,
    },
  },
}

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

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

{
  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 :

• Surface d’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 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 identifiants auth-profiles.json ont priorité sur les références openclaw.json)

Comportement de compatibilité Google Chat :

• serviceAccountRef a priorité sur le 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é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.reload explicite.

# 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_DEGRADED
• SECRETS_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 :

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 :

openclaw secrets audit --check

openclaw secrets configure

openclaw secrets audit --check

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

# Politique de sécurité à sens unique

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_key statiques 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é