Gestione dei segreti

OpenClaw supporta SecretRef additivi, così le credenziali supportate non devono essere archiviate come testo in chiaro nella configurazione.

Obiettivi e modello di runtime

I segreti vengono risolti in uno snapshot di runtime in memoria.

• La risoluzione è anticipata durante l’attivazione, non pigra nei percorsi di richiesta.
• L’avvio fallisce rapidamente quando un SecretRef effettivamente attivo non può essere risolto.
• Il ricaricamento usa uno scambio atomico: successo completo, oppure mantiene l’ultimo snapshot noto come valido.
• Le violazioni della policy SecretRef (per esempio profili di autenticazione in modalità OAuth combinati con input SecretRef) fanno fallire l’attivazione prima dello scambio di runtime.
• Le richieste di runtime leggono solo dallo snapshot attivo in memoria.
• Dopo la prima attivazione/caricamento della configurazione riuscita, i percorsi di codice di runtime continuano a leggere quello snapshot attivo in memoria finché un ricaricamento riuscito non lo sostituisce.
• Anche i percorsi di recapito in uscita leggono da quello snapshot attivo (per esempio recapito di risposte/thread Discord e invii di azioni Telegram); non risolvono di nuovo i SecretRef a ogni invio.

Questo tiene le interruzioni dei provider di segreti fuori dai percorsi di richiesta caldi.

Confine di accesso dell’agente

I SecretRef proteggono le credenziali dalla persistenza nella configurazione supportata e nelle superfici dei modelli generate, ma non sono un confine di isolamento del processo. Se una credenziale in testo in chiaro rimane su disco in un percorso leggibile dall’agente, l’agente può aggirare l’oscuramento a livello API usando strumenti file o shell per ispezionare quel file.

Per i deployment di produzione in cui i file accessibili dall’agente sono nell’ambito, considera la migrazione SecretRef completa solo quando tutte queste condizioni sono vere:

• le credenziali supportate usano SecretRef invece di valori in testo in chiaro
• i residui legacy in testo in chiaro sono stati rimossi da openclaw.json, auth-profiles.json, .env e dai file models.json generati
• openclaw secrets audit --check è pulito dopo la migrazione
• eventuali credenziali rimanenti non supportate o a rotazione sono protette dall’isolamento del sistema operativo, dall’isolamento del container o da un proxy di credenziali esterno

Per questo il workflow audit/configure/apply è un gate di migrazione di sicurezza, non solo un helper di convenienza.

Filtraggio delle superfici attive

I SecretRef vengono convalidati solo sulle superfici effettivamente attive.

• Superfici abilitate: i riferimenti non risolti bloccano avvio/ricaricamento.
• Superfici inattive: i riferimenti non risolti non bloccano avvio/ricaricamento.
• I riferimenti inattivi emettono diagnostica non fatale con codice SECRETS_REF_IGNORED_INACTIVE_SURFACE.

Diagnostica della superficie di autenticazione Gateway

Quando un SecretRef è configurato su gateway.auth.token, gateway.auth.password, gateway.remote.token o gateway.remote.password, l’avvio/ricaricamento del Gateway registra esplicitamente lo stato della superficie:

• active: il SecretRef fa parte della superficie di autenticazione effettiva e deve essere risolto.
• inactive: il SecretRef viene ignorato per questo runtime perché un’altra superficie di autenticazione prevale, oppure perché l’autenticazione remota è disabilitata/non attiva.

Queste voci vengono registrate con SECRETS_GATEWAY_AUTH_SURFACE e includono il motivo usato dalla policy delle superfici attive, così puoi vedere perché una credenziale è stata trattata come attiva o inattiva.

Preflight dei riferimenti di onboarding

Quando l’onboarding viene eseguito in modalità interattiva e scegli l’archiviazione SecretRef, OpenClaw esegue la convalida preflight prima del salvataggio:

• Riferimenti env: convalida il nome della variabile env e conferma che un valore non vuoto sia visibile durante la configurazione.
• Riferimenti provider (file o exec): convalida la selezione del provider, risolve id e controlla il tipo del valore risolto.
• Percorso di riuso quickstart: quando gateway.auth.token è già un SecretRef, l’onboarding lo risolve prima del bootstrap di probe/dashboard (per riferimenti env, file ed exec) usando lo stesso gate fail-fast.

Se la convalida fallisce, l’onboarding mostra l’errore e ti consente di riprovare.

Contratto SecretRef

Usa ovunque una sola forma di oggetto:

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

Configurazione provider

Definisci i provider sotto 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" } }}

Chiavi API basate su file

Non inserire stringhe file:... nel blocco env della configurazione. Il blocco env è letterale e non sovrascrivente, quindi file:... non viene risolto.

Usa invece un SecretRef file su un campo credenziale supportato:

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

Per mode: "singleValue", l’id SecretRef è "value". Per mode: "json", usa un puntatore JSON assoluto come "/providers/xai/apiKey".

Consulta Superficie delle credenziali SecretRef per i campi di configurazione che accettano SecretRef.

Esempi di integrazione 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" },      },    },  },}

Variabili d'ambiente del server MCP

Le variabili d'ambiente del server MCP configurate tramite plugins.entries.acpx.config.mcpServers supportano SecretInput. Questo mantiene chiavi API e token fuori dalla configurazione in testo normale:

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

I valori stringa in testo normale continuano a funzionare. I riferimenti modello env come ${MCP_SERVER_API_KEY} e gli oggetti SecretRef vengono risolti durante l'attivazione del gateway prima dell'avvio del processo del server MCP. Come per le altre superfici SecretRef, i riferimenti non risolti bloccano l'attivazione solo quando il plugin acpx è effettivamente attivo.

Materiale di autenticazione SSH della sandbox

Anche il backend sandbox core ssh supporta SecretRef per il materiale di autenticazione 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" },        },      },    },  },}

Comportamento di runtime:

• OpenClaw risolve questi riferimenti durante l'attivazione della sandbox, non in modo lazy durante ogni chiamata SSH.
• I valori risolti vengono scritti in file temporanei con permessi restrittivi e usati nella configurazione SSH generata.
• Se il backend sandbox effettivo non è ssh, questi riferimenti restano inattivi e non bloccano l'avvio.

Superficie delle credenziali supportata

Le credenziali canoniche supportate e non supportate sono elencate in:

• Superficie delle credenziali SecretRef

Comportamento richiesto e precedenza

• Campo senza riferimento: invariato.
• Campo con riferimento: richiesto sulle superfici attive durante l'attivazione.
• Se sono presenti sia testo normale sia riferimento, il riferimento ha la precedenza sui percorsi di precedenza supportati.
• Il sentinella di redazione __OPENCLAW_REDACTED__ è riservato alla redazione/ripristino interno della configurazione e viene rifiutato come dato di configurazione letterale inviato.

Segnali di avviso e audit:

• SECRETS_REF_OVERRIDES_PLAINTEXT (avviso di runtime)
• REF_SHADOWED (risultato di audit quando le credenziali di auth-profiles.json hanno la precedenza sui riferimenti di openclaw.json)

Comportamento di compatibilità Google Chat:

• serviceAccountRef ha la precedenza su serviceAccount in testo normale.
• Il valore in testo normale viene ignorato quando è impostato il riferimento fratello.

Trigger di attivazione

L'attivazione dei segreti viene eseguita su:

• Avvio (preflight più attivazione finale)
• Percorso hot-apply di ricaricamento della configurazione
• Percorso di controllo riavvio del ricaricamento della configurazione
• Ricaricamento manuale tramite secrets.reload
• Preflight RPC di scrittura della configurazione Gateway (config.set / config.apply / config.patch) per la risolvibilità dei SecretRef della superficie attiva nel payload di configurazione inviato prima di persistere le modifiche

Contratto di attivazione:

• Il successo sostituisce lo snapshot atomicamente.
• Un errore all'avvio interrompe l'avvio del gateway.
• Un errore di ricaricamento a runtime mantiene l'ultimo snapshot valido noto.
• Un errore di preflight write-RPC rifiuta la configurazione inviata e mantiene invariati sia la configurazione su disco sia lo snapshot di runtime attivo.
• Fornire un token di canale esplicito per chiamata a un helper/tool call in uscita non attiva SecretRef; i punti di attivazione restano avvio, ricaricamento e secrets.reload esplicito.

Segnali degradati e ripristinati

Quando l'attivazione in fase di ricaricamento fallisce dopo uno stato sano, OpenClaw entra nello stato di segreti degradati.

Evento di sistema una tantum e codici di log:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Comportamento:

• Degradato: il runtime mantiene l'ultimo snapshot valido noto.
• Ripristinato: emesso una volta dopo la successiva attivazione riuscita.
• Errori ripetuti mentre lo stato è già degradato registrano avvisi ma non generano eventi ripetuti.
• Il fail-fast all'avvio non emette eventi degradati perché il runtime non è mai diventato attivo.

Risoluzione del percorso dei comandi

I percorsi dei comandi possono aderire alla risoluzione SecretRef supportata tramite RPC dello snapshot Gateway.

Esistono due comportamenti generali:

Altre note:

• L'aggiornamento dello snapshot dopo la rotazione dei segreti del backend è gestito da openclaw secrets reload.
• Metodo RPC del Gateway usato da questi percorsi di comando: secrets.resolve.

Flusso di lavoro di audit e configurazione

Flusso predefinito dell'operatore:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

Non considerare la migrazione completa finché il nuovo audit non è pulito. Se l'audit segnala ancora valori in testo normale a riposo, il rischio di accesso dell'agente è ancora presente anche quando le API runtime restituiscono valori redatti.

Se salvi un piano invece di applicarlo durante configure, applica quel piano salvato con openclaw secrets apply --from <plan-path> prima del nuovo 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

Policy di sicurezza unidirezionale

Modello di sicurezza:

• il preflight deve riuscire prima della modalità di scrittura
• l'attivazione runtime viene convalidata prima del commit
• apply aggiorna i file usando la sostituzione atomica dei file e il ripristino best-effort in caso di errore

Note sulla compatibilità dell'autenticazione legacy

Per le credenziali statiche, il runtime non dipende più dall'archiviazione legacy dell'autenticazione in testo normale.

• L'origine delle credenziali runtime è lo snapshot in memoria risolto.
• Le voci api_key statiche legacy vengono rimosse quando vengono rilevate.
• Il comportamento di compatibilità relativo a OAuth rimane separato.

Nota sull'interfaccia Web

Alcune unioni SecretInput sono più facili da configurare in modalità editor grezzo che in modalità modulo.

Correlati

• Autenticazione — configurazione dell'autenticazione
• CLI: secrets — comandi CLI
• Variabili di ambiente — precedenza dell'ambiente
• Superficie delle credenziali SecretRef — superficie delle credenziali
• Contratto del piano di Secrets Apply — dettagli del contratto del piano
• Sicurezza — postura di sicurezza