Gestione dei segreti

​

Modello di runtime

• I segreti vengono risolti in uno snapshot del runtime in memoria, preventivamente durante l’attivazione, non in modo differito nei percorsi delle richieste.
• L’avvio termina immediatamente con un errore quando non è possibile risolvere una SecretRef effettivamente attiva.
• Il ricaricamento consiste in uno scambio atomico: riesce completamente oppure mantiene l’ultimo snapshot valido noto.
• Le violazioni dei criteri (ad esempio un profilo di autenticazione in modalità OAuth combinato con un input SecretRef) causano il fallimento dell’attivazione prima dello scambio del runtime.
• Le richieste di runtime leggono esclusivamente lo snapshot attivo in memoria. Le credenziali SecretRef dei provider di modelli attraversano l’archiviazione dell’autenticazione e le opzioni di streaming sotto forma di sentinelle locali al processo fino all’uscita. Anche i percorsi di consegna in uscita (consegna di risposte/thread Discord, invii di azioni Telegram) leggono tale snapshot e non risolvono nuovamente i riferimenti a ogni invio.

​

Inserimento al momento dell’uscita (sentinelle)

• Gli SDK con un’opzione fetch personalizzata ricevono la funzione fetch protetta di OpenClaw, così l’SDK conserva la sentinella.
• Gli SDK senza un’opzione fetch personalizzata estraggono il valore dalla sentinella immediatamente prima della creazione del client. Gli stream dei provider di proprietà dei Plugin e gli harness degli agenti eseguono l’estrazione nell’ultimo passaggio gestito dal core, perché tali trasporti non condividono la funzione fetch protetta di OpenClaw.

​

Limite di accesso dell’agente

• Le credenziali supportate usano SecretRef anziché valori in testo in chiaro.
• I residui legacy in testo in chiaro vengono rimossi da openclaw.json, auth-profiles.json, .env e dai file models.json generati.
• openclaw secrets audit --check non segnala problemi dopo la migrazione.
• Tutte le credenziali rimanenti non supportate o soggette a rotazione sono protette mediante isolamento del sistema operativo, isolamento del container o un proxy esterno per le credenziali.

​

Filtro delle superfici attive

• Superfici abilitate: i riferimenti non risolti bloccano l’avvio o il ricaricamento.
• Superfici inattive: i riferimenti non risolti non bloccano l’avvio o il ricaricamento; generano una diagnostica SECRETS_REF_IGNORED_INACTIVE_SURFACE non fatale.

​

Diagnostica delle superfici di autenticazione del Gateway

• active: la SecretRef fa parte della superficie di autenticazione effettiva e deve essere risolta.
• inactive: prevale un’altra superficie di autenticazione oppure l’autenticazione remota è disabilitata/non attiva.

​

Controllo preliminare dei riferimenti durante l’onboarding

• Riferimenti all’ambiente: convalida il nome della variabile di ambiente e verifica che durante la configurazione sia visibile un valore non vuoto.
• Riferimenti ai provider (file o exec): convalida la selezione del provider, risolve id e controlla il tipo del valore risolto.
• Flusso di avvio rapido: quando gateway.auth.token è già una SecretRef, l’onboarding la risolve prima del probe e dell’inizializzazione della dashboard (per i riferimenti env, file e exec) usando lo stesso punto di controllo con terminazione immediata in caso di errore.

​

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

​

Configurazione dei provider

{
  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": { "code": "NOT_FOUND" } }
}

​

Chiavi API basate su file

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

​

Esempi di integrazione exec

{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true, // obbligatorio per i file binari di Homebrew collegati simbolicamente
        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, // obbligatorio per i file binari di Homebrew collegati simbolicamente
        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(`Impossibile analizzare la richiesta: ${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 è terminato con stato ${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, // obbligatorio per i file binari di Homebrew collegati simbolicamente
        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 dei 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 riferimenti durante l’attivazione della sandbox, non in modo differito a ogni chiamata SSH.
• I valori risolti vengono scritti in una directory temporanea con autorizzazioni restrittive per i file (0o600) e utilizzati nella configurazione SSH generata.
• Se il backend effettivo della sandbox non è ssh (o la modalità sandbox è off), questi riferimenti restano inattivi e non bloccano l’avvio.

​

Superficie delle credenziali supportata

​

Comportamento richiesto e precedenza

• Campo senza riferimento: invariato.
• Campo con un riferimento: obbligatorio sulle superfici attive durante l’attivazione.
• Se sono presenti sia il testo in chiaro sia il riferimento, quest’ultimo ha la precedenza nei percorsi di precedenza supportati.
• Il valore sentinella di oscuramento __OPENCLAW_REDACTED__ è riservato all’oscuramento/ripristino interno della configurazione e viene rifiutato come dato di configurazione letterale inviato.

• SECRETS_REF_OVERRIDES_PLAINTEXT (avviso in fase di esecuzione)
• REF_SHADOWED (rilievo del controllo quando le credenziali auth-profiles.json hanno la precedenza sui riferimenti openclaw.json)

​

Trigger di attivazione

• Avvio (controllo preliminare e attivazione finale)
• Percorso di applicazione a caldo del ricaricamento della configurazione
• Percorso di verifica del riavvio del ricaricamento della configurazione
• Ricaricamento manuale tramite secrets.reload
• Controllo preliminare dell’RPC di scrittura della configurazione del Gateway (config.set / config.apply / config.patch), che verifica la risolvibilità dei SecretRef delle superfici attive nel payload di configurazione inviato prima di rendere persistenti le modifiche

• In caso di esito positivo, lo snapshot viene sostituito atomicamente.
• Un errore all’avvio interrompe l’avvio del Gateway.
• In caso di errore durante il ricaricamento in fase di esecuzione, viene mantenuto l’ultimo snapshot valido noto.
• Un errore nel controllo preliminare dell’RPC di scrittura rifiuta la configurazione inviata; sia la configurazione su disco sia lo snapshot attivo in fase di esecuzione restano invariati.
• Fornire un token di canale esplicito per singola chiamata a una chiamata di strumento/helper in uscita non attiva SecretRef; i punti di attivazione restano l’avvio, il ricaricamento e secrets.reload esplicito.

​

Segnali di stato degradato e ripristinato

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

• Stato degradato: l’ambiente di esecuzione mantiene l’ultimo snapshot valido noto.
• Stato ripristinato: viene emesso una sola volta dopo la successiva attivazione riuscita.
• Gli errori ripetuti quando lo stato è già degradato registrano avvisi, ma non emettono nuovamente l’evento.
• L’interruzione immediata all’avvio non emette mai un evento di stato degradato, perché l’ambiente di esecuzione non è mai diventato attivo.

​

Risoluzione dei percorsi dei comandi

• L’aggiornamento dello snapshot dopo la rotazione dei segreti del backend viene gestito da openclaw secrets reload.
• Metodo RPC del Gateway utilizzato da questi percorsi dei comandi: secrets.resolve.

​

Flusso di controllo e configurazione

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

​

Criterio di sicurezza unidirezionale

• Il controllo preliminare deve riuscire prima della modalità di scrittura.
• L’attivazione in fase di esecuzione viene convalidata prima del commit.
• L’applicazione aggiorna i file mediante sostituzione atomica e tenta il ripristino in caso di errore.

​

Note sulla compatibilità dell’autenticazione legacy

• La fonte delle credenziali in fase di esecuzione è lo snapshot risolto in memoria.
• Le voci statiche legacy api_key vengono rimosse quando rilevate.
• Il comportamento di compatibilità relativo a OAuth resta separato.

​

Nota sull’interfaccia web

​

Risorse correlate

• Autenticazione - configurazione dell’autenticazione
• CLI: segreti - comandi CLI
• SecretRef di Vault - configurazione del provider HashiCorp Vault
• Variabili di ambiente - precedenza delle variabili di ambiente
• Superficie delle credenziali SecretRef - superficie delle credenziali
• Contratto del piano di applicazione dei segreti - dettagli del contratto del piano
• Sicurezza - strategia di sicurezza