Gestion des secrets

​

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.

​

Injection à la sortie (sentinelles)

• 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.

​

Limite d’accès de l’agent

• 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.

​

Filtrage des surfaces 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

• 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.

​

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

• 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.

​

Contrat SecretRef

{ 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

{
  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

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

​

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 node
const { 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 --check
openclaw 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

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

​

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

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

• 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

​

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.

• 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)

​

Déclencheurs d’activation

• 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

• 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

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

• É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

• 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

openclaw secrets audit --check

openclaw secrets configure --apply

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

• 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

• 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

​

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é