​

Gestione dei segreti

​

Obiettivi e modello runtime

• La risoluzione è eager durante l’attivazione, non lazy nei percorsi di richiesta.
• L’avvio fallisce rapidamente quando un SecretRef effettivamente attivo non può essere risolto.
• Il reload usa uno scambio atomico: successo completo, oppure viene mantenuta l’ultima istantanea valida conosciuta.
• Le violazioni della policy SecretRef (ad esempio profili auth in modalità OAuth combinati con input SecretRef) fanno fallire l’attivazione prima dello scambio runtime.
• Le richieste runtime leggono solo dall’istantanea attiva in memoria.
• Dopo la prima attivazione/caricamento riusciti della config, i percorsi di codice runtime continuano a leggere da quell’istantanea attiva in memoria finché un reload riuscito non la sostituisce.
• Anche i percorsi di consegna in uscita leggono da quell’istantanea attiva (ad esempio consegna di risposte/thread Discord e invio di azioni Telegram); non risolvono di nuovo i SecretRef a ogni invio.

​

Filtraggio delle superfici attive

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

• Voci canale/account disabilitate.
• Credenziali di canale di primo livello che nessun account abilitato eredita.
• Superfici strumento/funzionalità disabilitate.
• Chiavi specifiche del provider di ricerca web che non sono selezionate da tools.web.search.provider. In modalità auto (provider non impostato), le chiavi vengono consultate in ordine di precedenza per l’auto-rilevamento del provider finché una non si risolve. Dopo la selezione, le chiavi dei provider non selezionati vengono trattate come inattive finché non vengono selezionate.
• Materiale di autenticazione SSH della sandbox (agents.defaults.sandbox.ssh.identityData, certificateData, knownHostsData, più gli override per agente) è attivo solo quando il backend sandbox effettivo è ssh per l’agente predefinito o per un agente abilitato.
• I SecretRef gateway.remote.token / gateway.remote.password sono attivi se vale una di queste condizioni:
  • gateway.mode=remote
  • gateway.remote.url è configurato
  • gateway.tailscale.mode è serve o funnel
  • In modalità locale senza quelle superfici remote:
    • gateway.remote.token è attivo quando l’autenticazione token può prevalere e nessun token env/auth è configurato.
    • gateway.remote.password è attivo solo quando l’autenticazione password può prevalere e nessuna password env/auth è configurata.
• Il SecretRef gateway.auth.token è inattivo per la risoluzione auth all’avvio quando è impostato OPENCLAW_GATEWAY_TOKEN, perché per quel runtime prevale l’input token dell’env.

​

Diagnostica della superficie di autenticazione gateway

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

​

Preflight dei ref nell’onboarding

• Ref env: valida il nome della variabile env e conferma che durante il setup sia visibile un valore non vuoto.
• Ref provider (file o exec): valida 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 probe/dashboard (per ref env, file ed exec) usando lo stesso gate fail-fast.

​

Contratto SecretRef

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

​

source: "env"

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

• provider deve corrispondere a ^[a-z][a-z0-9_-]{0,63}$
• id deve corrispondere a ^[A-Z][A-Z0-9_]{0,127}$

​

source: "file"

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

• provider deve corrispondere a ^[a-z][a-z0-9_-]{0,63}$
• id deve essere un puntatore JSON assoluto (/...)
• Escape RFC6901 nei segmenti: ~ => ~0, / => ~1

​

source: "exec"

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

• provider deve corrispondere a ^[a-z][a-z0-9_-]{0,63}$
• id deve corrispondere a ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
• id non deve contenere . o .. come segmenti di percorso delimitati da slash (ad esempio a/../b viene rifiutato)

​

Configurazione del provider

{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json", // oppure "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,
    },
  },
}

​

Provider env

• Allowlist facoltativa tramite allowlist.
• Valori env mancanti/vuoti fanno fallire la risoluzione.

​

Provider file

• Legge il file locale da path.
• mode: "json" si aspetta un payload oggetto JSON e risolve id come puntatore.
• mode: "singleValue" si aspetta l’ID ref "value" e restituisce il contenuto del file.
• Il percorso deve superare i controlli di proprietà/permessi.
• Nota fail-closed su Windows: se la verifica ACL non è disponibile per un percorso, la risoluzione fallisce. Solo per percorsi fidati, imposta allowInsecurePath: true su quel provider per bypassare i controlli di sicurezza sul percorso.

​

Provider exec

• Esegue il percorso assoluto del binario configurato, senza shell.
• Per impostazione predefinita, command deve puntare a un file regolare (non a un symlink).
• Imposta allowSymlinkCommand: true per consentire percorsi comando symlink (ad esempio shim Homebrew). OpenClaw valida il percorso di destinazione risolto.
• Abbina allowSymlinkCommand a trustedDirs per i percorsi del gestore pacchetti (ad esempio ["/opt/homebrew"]).
• Supporta timeout, timeout senza output, limiti di byte in output, allowlist env e directory fidate.
• Nota fail-closed su Windows: se la verifica ACL non è disponibile per il percorso del comando, la risoluzione fallisce. Solo per percorsi fidati, imposta allowInsecurePath: true su quel provider per bypassare i controlli di sicurezza sul percorso.

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

​

Esempi di integrazione exec

​

1Password CLI

{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true, // richiesto per i binari symlink di Homebrew
        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" },
      },
    },
  },
}

​

HashiCorp Vault CLI

{
  secrets: {
    providers: {
      vault_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/vault",
        allowSymlinkCommand: true, // richiesto per i binari symlink di Homebrew
        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" },
      },
    },
  },
}

​

sops

{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/sops",
        allowSymlinkCommand: true, // richiesto per i binari symlink di Homebrew
        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 di ambiente del server 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",
                },
              },
            },
          },
        },
      },
    },
  },
}

​

Materiale di autenticazione SSH della sandbox

{
  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 risolve questi ref 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 config SSH generata.
• Se il backend sandbox effettivo non è ssh, questi ref restano inattivi e non bloccano l’avvio.

​

Superficie delle credenziali supportata

• Superficie delle credenziali SecretRef

​

Comportamento richiesto e precedenza

• Campo senza ref: invariato.
• Campo con ref: richiesto sulle superfici attive durante l’attivazione.
• Se sono presenti sia testo in chiaro sia ref, il ref ha precedenza nei percorsi di precedenza supportati.
• Il sentinel di redazione __OPENCLAW_REDACTED__ è riservato alla redazione/ripristino interno della config ed è rifiutato come dato letterale inviato nella config.

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

• serviceAccountRef ha precedenza su serviceAccount in chiaro.
• Il valore in chiaro viene ignorato quando il ref sibling è impostato.

​

Trigger di attivazione

• Avvio (preflight più attivazione finale)
• Percorso hot-apply del reload config
• Percorso restart-check del reload config
• Reload manuale tramite secrets.reload
• Preflight degli RPC di scrittura config del Gateway (config.set / config.apply / config.patch) per la risolvibilità dei SecretRef di superfici attive all’interno del payload config inviato prima di persistere le modifiche

• Il successo sostituisce l’istantanea in modo atomico.
• Il fallimento all’avvio interrompe l’avvio del gateway.
• Il fallimento del reload runtime mantiene l’ultima istantanea valida conosciuta.
• Il fallimento del preflight di Write-RPC rifiuta la config inviata e mantiene invariati sia la config su disco sia l’istantanea runtime attiva.
• Fornire un token di canale esplicito per chiamata a una helper/tool call in uscita non attiva l’attivazione SecretRef; i punti di attivazione restano avvio, reload e secrets.reload esplicito.

​

Segnali di stato degradato e ripristinato

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

• Degradato: il runtime mantiene l’ultima istantanea valida conosciuta.
• Ripristinato: emesso una sola volta dopo l’attivazione riuscita successiva.
• Fallimenti ripetuti mentre si è già in stato degradato registrano avvisi ma non saturano gli eventi.
• Il fail-fast all’avvio non emette eventi di stato degradato perché il runtime non è mai diventato attivo.

​

Risoluzione nel percorso dei comandi

• I percorsi di comando rigorosi (ad esempio i percorsi di memoria remota di openclaw memory e openclaw qr --remote quando necessita di ref di segreto condiviso remoto) leggono dall’istantanea attiva e falliscono rapidamente quando un SecretRef richiesto non è disponibile.
• I percorsi di comando di sola lettura (ad esempio openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, openclaw security audit e i flussi di sola lettura doctor/config repair) preferiscono anch’essi l’istantanea attiva, ma degradano invece di interrompersi quando un SecretRef mirato non è disponibile in quel percorso di comando.

• Quando il gateway è in esecuzione, questi comandi leggono prima dall’istantanea attiva.
• Se la risoluzione del gateway è incompleta o il gateway non è disponibile, tentano un fallback locale mirato per la specifica superficie del comando.
• Se un SecretRef mirato resta comunque non disponibile, il comando continua con un output di sola lettura degradato e diagnostica esplicita come “configured but unavailable in this command path”.
• Questo comportamento degradato vale solo localmente per il comando. Non indebolisce avvio runtime, reload o percorsi send/auth.

• L’aggiornamento dell’istantanea dopo la rotazione dei segreti nel backend viene gestito da openclaw secrets reload.
• Metodo RPC Gateway usato da questi percorsi di comando: secrets.resolve.

​

Flusso di lavoro audit e configure

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

​

secrets audit

• valori in chiaro a riposo (openclaw.json, auth-profiles.json, .env e agents/*/agent/models.json generati)
• residui in chiaro di header sensibili dei provider nelle voci generate di models.json
• ref non risolti
• shadowing di precedenza (auth-profiles.json che ha priorità sui ref di openclaw.json)
• residui legacy (auth.json, promemoria OAuth)

• Per impostazione predefinita, audit salta i controlli di risolvibilità dei SecretRef exec per evitare effetti collaterali del comando.
• Usa openclaw secrets audit --allow-exec per eseguire i provider exec durante l’audit.

• Il rilevamento degli header sensibili dei provider è basato su euristiche di nome (nomi e frammenti comuni di header auth/credenziali come authorization, x-api-key, token, secret, password e credential).

​

secrets configure

• configura prima secrets.providers (env/file/exec, aggiunta/modifica/rimozione)
• ti consente di selezionare i campi supportati che contengono segreti in openclaw.json più auth-profiles.json per un ambito di agente
• può creare direttamente una nuova mappatura auth-profiles.json nel selettore della destinazione
• acquisisce i dettagli SecretRef (source, provider, id)
• esegue la risoluzione preflight
• può applicare immediatamente

• Il preflight salta i controlli exec SecretRef a meno che non sia impostato --allow-exec.
• Se applichi direttamente da configure --apply e il piano include ref/provider exec, mantieni --allow-exec attivo anche per il passaggio di apply.

• openclaw secrets configure --providers-only
• openclaw secrets configure --skip-provider-setup
• openclaw secrets configure --agent <id>

• rimuove le credenziali statiche corrispondenti da auth-profiles.json per i provider di destinazione
• rimuove le voci statiche legacy api_key da auth.json
• rimuove le righe di segreti note corrispondenti da <config-dir>/.env

​

secrets apply

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

• Il dry-run salta i controlli exec a meno che non sia impostato --allow-exec.
• La modalità di scrittura rifiuta i piani che contengono SecretRef/provider exec a meno che non sia impostato --allow-exec.

• Contratto del piano Secrets Apply

​

Policy di sicurezza unidirezionale

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

​

Note di compatibilità auth legacy

• La sorgente delle credenziali runtime è l’istantanea risolta in memoria.
• Le voci statiche legacy api_key vengono rimosse quando rilevate.
• Il comportamento di compatibilità relativo a OAuth resta separato.

​

Nota sulla Web UI

​

Documentazione correlata

• Comandi CLI: secrets
• Dettagli del contratto del piano: Contratto del piano Secrets Apply
• Superficie delle credenziali: Superficie delle credenziali SecretRef
• Configurazione auth: Autenticazione
• Postura di sicurezza: Sicurezza
• Precedenza environment: Variabili di ambiente