Gestione dei segreti

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

# Obiettivi e modello runtime

I segreti vengono risolti in uno snapshot runtime in memoria.

• La risoluzione è eager durante l'attivazione, non lazy sui percorsi delle richieste.
• L'avvio fallisce rapidamente quando un SecretRef effettivamente attivo non può essere risolto.
• Il reload usa uno swap atomico: successo completo, oppure mantiene l'ultimo snapshot noto valido.
• Le violazioni della policy SecretRef (per esempio profili di autenticazione in modalità OAuth combinati con input SecretRef) fanno fallire l'attivazione prima dello swap runtime.
• Le richieste runtime leggono solo dallo snapshot attivo in memoria.
• Dopo la prima attivazione/caricamento della configurazione riuscita, i percorsi di codice runtime continuano a leggere quello snapshot attivo in memoria finché un reload 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 mantiene le interruzioni dei provider di segreti fuori dai percorsi caldi delle richieste.

# Filtro delle superfici attive

I SecretRef vengono validati solo sulle superfici effettivamente 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.

# 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/reload 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é prevale un'altra superficie di autenticazione, 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 durante l'onboarding

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

• Ref env: valida il nome della variabile env e conferma che durante la configurazione 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 di probe/dashboard (per ref env, file ed exec) usando lo stesso gate fail-fast.

Se la validazione fallisce, l'onboarding mostra l'errore e ti consente di riprovare.

# Contratto SecretRef

Usa ovunque una singola forma di oggetto:

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

# Configurazione del 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,
      },
    },
    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" } }
}

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

# Variabili d'ambiente del server MCP

Le variabili env del server MCP configurate tramite plugins.entries.acpx.config.mcpServers supportano SecretInput. Questo tiene API key e token fuori dalla configurazione in testo in chiaro:

{
  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 in chiaro continuano a funzionare. I ref con template env come ${MCP_SERVER_API_KEY} e gli oggetti SecretRef vengono risolti durante l'attivazione del gateway prima che venga generato il processo del server MCP. Come per le altre superfici SecretRef, i ref 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 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 un riferimento: invariato.
• Campo con un riferimento: richiesto sulle superfici attive durante l'attivazione.
• Se sono presenti sia testo in chiaro sia riferimento, il riferimento ha la precedenza nei percorsi di precedenza supportati.
• Il sentinel di redazione __OPENCLAW_REDACTED__ è riservato alla redazione/ripristino della configurazione interna e viene rifiutato come dato di configurazione inviato letterale.

Segnali di avviso e audit:

• SECRETS_REF_OVERRIDES_PLAINTEXT (avviso runtime)
• REF_SHADOWED (riscontro 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 chiaro.
• Il valore in chiaro 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 restart-check di ricaricamento della configurazione
• Ricaricamento manuale tramite secrets.reload
• Preflight RPC di scrittura della configurazione del Gateway (config.set / config.apply / config.patch) per la risolvibilità SecretRef della superficie attiva nel payload di configurazione inviato prima di rendere persistenti le modifiche

Contratto di attivazione:

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

# Segnali degradati e recuperati

Quando l'attivazione in fase di ricaricamento fallisce dopo uno stato integro, 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 noto valido.
• Recuperato: emesso una volta dopo la successiva attivazione riuscita.
• Errori ripetuti mentre è già degradato registrano avvisi ma non generano spam di eventi.
• Il fail-fast all'avvio non emette eventi degradati perché il runtime non è mai diventato attivo.

# Risoluzione dei percorsi di comando

I percorsi di comando possono scegliere di usare la risoluzione SecretRef supportata tramite RPC di snapshot del gateway.

Esistono due comportamenti generali:

Altre note:

• L'aggiornamento dello snapshot dopo la rotazione di un segreto del backend viene 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 operatore predefinito:

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

# Criterio di sicurezza unidirezionale

Modello di sicurezza:

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

# Note di compatibilità dell'autenticazione legacy

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

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

# Nota Web UI

Alcune unioni SecretInput sono più facili da configurare in modalità editor raw che in modalità form.

# Correlati

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