Geheimnisverwaltung

OpenClaw unterstützt additive SecretRefs, sodass unterstützte Zugangsdaten nicht als Klartext in der Konfiguration gespeichert werden müssen.

Ziele und Laufzeitmodell

Secrets werden in einen In-Memory-Laufzeit-Snapshot aufgelöst.

• Die Auflösung erfolgt während der Aktivierung eifrig, nicht lazy auf Anfragepfaden.
• Der Start schlägt schnell fehl, wenn ein effektiv aktiver SecretRef nicht aufgelöst werden kann.
• Reload verwendet atomaren Austausch: vollständiger Erfolg oder Beibehaltung des zuletzt als gut bekannten Snapshots.
• SecretRef-Policy-Verstöße (zum Beispiel Auth-Profile im OAuth-Modus in Kombination mit SecretRef-Eingabe) lassen die Aktivierung vor dem Laufzeitaustausch fehlschlagen.
• Laufzeitanfragen lesen ausschließlich aus dem aktiven In-Memory-Snapshot.
• Nach der ersten erfolgreichen Konfigurationsaktivierung bzw. dem ersten erfolgreichen Laden lesen Laufzeit-Codepfade weiter aus diesem aktiven In-Memory-Snapshot, bis ein erfolgreicher Reload ihn austauscht.
• Ausgehende Zustellpfade lesen ebenfalls aus diesem aktiven Snapshot (zum Beispiel Discord-Antwort-/Thread-Zustellung und Telegram-Aktionssendungen); sie lösen SecretRefs nicht bei jedem Senden erneut auf.

Dadurch bleiben Ausfälle von Secret-Providern von heißen Anfragepfaden fern.

Agent-Zugriffsgrenze

SecretRefs schützen Zugangsdaten davor, in unterstützter Konfiguration und generierten Modelloberflächen persistiert zu werden, sie sind jedoch keine Prozessisolationsgrenze. Wenn ein Klartext-Zugangsdatenwert auf der Festplatte in einem Pfad verbleibt, den der Agent lesen kann, kann der Agent Redaktion auf API-Ebene umgehen, indem er Datei- oder Shell-Tools verwendet, um diese Datei einzusehen.

Behandeln Sie bei Produktionsbereitstellungen, bei denen für Agents zugängliche Dateien im Geltungsbereich liegen, die SecretRef-Migration nur dann als abgeschlossen, wenn all dies zutrifft:

• unterstützte Zugangsdaten verwenden SecretRefs statt Klartextwerten
• veraltete Klartextreste wurden aus openclaw.json, auth-profiles.json, .env und generierten models.json-Dateien entfernt
• openclaw secrets audit --check ist nach der Migration sauber
• alle verbleibenden nicht unterstützten oder rotierenden Zugangsdaten sind durch Betriebssystemisolation, Container-Isolation oder einen externen Zugangsdaten-Proxy geschützt

Deshalb ist der Audit-/Configure-/Apply-Workflow ein Sicherheitsmigrations-Gate und nicht nur ein Komfort-Helper.

Filterung aktiver Oberflächen

SecretRefs werden nur auf effektiv aktiven Oberflächen validiert.

• Aktivierte Oberflächen: nicht aufgelöste Referenzen blockieren Start/Reload.
• Inaktive Oberflächen: nicht aufgelöste Referenzen blockieren Start/Reload nicht.
• Inaktive Referenzen geben nicht-fatale Diagnosen mit dem Code SECRETS_REF_IGNORED_INACTIVE_SURFACE aus.

Diagnosen der Gateway-Auth-Oberfläche

Wenn ein SecretRef auf gateway.auth.token, gateway.auth.password, gateway.remote.token oder gateway.remote.password konfiguriert ist, protokolliert Gateway-Start/Reload den Oberflächenzustand explizit:

• active: Der SecretRef ist Teil der effektiven Auth-Oberfläche und muss aufgelöst werden.
• inactive: Der SecretRef wird für diese Laufzeit ignoriert, weil eine andere Auth-Oberfläche Vorrang hat oder weil Remote-Auth deaktiviert/nicht aktiv ist.

Diese Einträge werden mit SECRETS_GATEWAY_AUTH_SURFACE protokolliert und enthalten den Grund, den die Policy für aktive Oberflächen verwendet. So können Sie sehen, warum ein Zugangsdatenwert als aktiv oder inaktiv behandelt wurde.

Onboarding-Referenz-Preflight

Wenn Onboarding im interaktiven Modus läuft und Sie SecretRef-Speicherung auswählen, führt OpenClaw vor dem Speichern eine Preflight-Validierung aus:

• Env-Referenzen: validiert den Namen der Env-Variable und bestätigt, dass während der Einrichtung ein nicht leerer Wert sichtbar ist.
• Provider-Referenzen (file oder exec): validiert die Provider-Auswahl, löst id auf und prüft den Typ des aufgelösten Werts.
• Quickstart-Wiederverwendungspfad: Wenn gateway.auth.token bereits ein SecretRef ist, löst Onboarding ihn vor Probe-/Dashboard-Bootstrap (für env-, file- und exec-Referenzen) mit demselben Fail-Fast-Gate auf.

Wenn die Validierung fehlschlägt, zeigt Onboarding den Fehler an und lässt Sie es erneut versuchen.

SecretRef-Vertrag

Verwenden Sie überall dieselbe Objektform:

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

Provider-Konfiguration

Definieren Sie Provider unter 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" } }}

Dateibasierte API-Schlüssel

Legen Sie keine file:...-Strings in den env-Block der Konfiguration. Der env-Block ist literal und nicht überschreibend, daher wird file:... nicht aufgelöst.

Verwenden Sie stattdessen einen Datei-SecretRef auf einem unterstützten Zugangsdatenfeld:

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

Für mode: "singleValue" ist die SecretRef-id "value". Für mode: "json" verwenden Sie einen absoluten JSON-Pointer wie "/providers/xai/apiKey".

Siehe SecretRef-Zugangsdatenoberfläche für die Konfigurationsfelder, die SecretRefs akzeptieren.

Exec-Integrationsbeispiele

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

MCP-Server-Umgebungsvariablen

MCP-Server-Env-Vars, die über plugins.entries.acpx.config.mcpServers konfiguriert sind, unterstützen SecretInput. Dadurch bleiben API-Schlüssel und Tokens außerhalb der Klartextkonfiguration:

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

Klartext-String-Werte funktionieren weiterhin. Env-Template-Refs wie ${MCP_SERVER_API_KEY} und SecretRef-Objekte werden während der Gateway-Aktivierung aufgelöst, bevor der MCP-Server-Prozess gestartet wird. Wie bei anderen SecretRef-Oberflächen blockieren nicht aufgelöste Refs die Aktivierung nur, wenn das acpx-Plugin effektiv aktiv ist.

SSH-Auth-Material für Sandbox

Das zentrale ssh-Sandbox-Backend unterstützt ebenfalls SecretRefs für SSH-Auth-Material:

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

Laufzeitverhalten:

• OpenClaw löst diese Refs während der Sandbox-Aktivierung auf, nicht verzögert bei jedem SSH-Aufruf.
• Aufgelöste Werte werden in temporäre Dateien mit restriktiven Berechtigungen geschrieben und in der generierten SSH-Konfiguration verwendet.
• Wenn das effektive Sandbox-Backend nicht ssh ist, bleiben diese Refs inaktiv und blockieren den Start nicht.

Unterstützte Anmeldeinformationsoberfläche

Kanonisch unterstützte und nicht unterstützte Anmeldeinformationen sind hier aufgeführt:

• SecretRef-Anmeldeinformationsoberfläche

Erforderliches Verhalten und Vorrang

• Feld ohne Ref: unverändert.
• Feld mit Ref: auf aktiven Oberflächen während der Aktivierung erforderlich.
• Wenn sowohl Klartext als auch Ref vorhanden sind, hat Ref auf unterstützten Vorrangpfaden Vorrang.
• Der Redaktions-Sentinel __OPENCLAW_REDACTED__ ist für interne Konfigurationsredaktion/-wiederherstellung reserviert und wird als wörtlich übermittelte Konfigurationsdaten abgelehnt.

Warn- und Audit-Signale:

• SECRETS_REF_OVERRIDES_PLAINTEXT (Laufzeitwarnung)
• REF_SHADOWED (Audit-Befund, wenn auth-profiles.json-Anmeldeinformationen Vorrang vor openclaw.json-Refs haben)

Google Chat-Kompatibilitätsverhalten:

• serviceAccountRef hat Vorrang vor Klartext-serviceAccount.
• Der Klartextwert wird ignoriert, wenn eine benachbarte Ref gesetzt ist.

Aktivierungsauslöser

Die Geheimnisaktivierung wird ausgeführt bei:

• Start (Preflight plus abschließende Aktivierung)
• Hot-Apply-Pfad beim Neuladen der Konfiguration
• Restart-Check-Pfad beim Neuladen der Konfiguration
• Manuellem Neuladen über secrets.reload
• Gateway-Konfigurationsschreib-RPC-Preflight (config.set / config.apply / config.patch) für die Auflösbarkeit von SecretRefs auf aktiven Oberflächen innerhalb der übermittelten Konfigurationsnutzlast vor dem Persistieren von Änderungen

Aktivierungsvertrag:

• Erfolg tauscht den Snapshot atomar aus.
• Ein Startfehler bricht den Gateway-Start ab.
• Ein Laufzeit-Neuladefehler behält den zuletzt bekannten funktionsfähigen Snapshot bei.
• Ein Write-RPC-Preflight-Fehler lehnt die übermittelte Konfiguration ab und lässt sowohl die Datenträgerkonfiguration als auch den aktiven Laufzeit-Snapshot unverändert.
• Das Bereitstellen eines expliziten Kanal-Tokens pro Aufruf für einen ausgehenden Helper-/Tool-Aufruf löst keine SecretRef-Aktivierung aus; Aktivierungspunkte bleiben Start, Neuladen und explizites secrets.reload.

Signale für beeinträchtigten und wiederhergestellten Zustand

Wenn die Aktivierung beim Neuladen nach einem fehlerfreien Zustand fehlschlägt, wechselt OpenClaw in einen beeinträchtigten Geheimniszustand.

Einmalige Systemereignis- und Protokollcodes:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Verhalten:

• Beeinträchtigt: Die Laufzeit behält den zuletzt bekannten funktionsfähigen Snapshot bei.
• Wiederhergestellt: Wird einmal nach der nächsten erfolgreichen Aktivierung ausgegeben.
• Wiederholte Fehler, während der Zustand bereits beeinträchtigt ist, protokollieren Warnungen, erzeugen aber keine Ereignisflut.
• Start-Fail-Fast gibt keine Ereignisse für beeinträchtigten Zustand aus, weil die Laufzeit nie aktiv wurde.

Befehlspfadauflösung

Befehlspfade können sich über Gateway-Snapshot-RPC für unterstützte SecretRef-Auflösung entscheiden.

Es gibt zwei allgemeine Verhaltensweisen:

Weitere Hinweise:

• Die Snapshot-Aktualisierung nach einer Secret-Rotation im Backend wird von openclaw secrets reload behandelt.
• Von diesen Befehlspfaden verwendete Gateway-RPC-Methode: secrets.resolve.

Audit- und Konfigurationsworkflow

Standardmäßiger Operator-Flow:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

Betrachten Sie die Migration erst als abgeschlossen, wenn der erneute Audit sauber ist. Wenn der Audit weiterhin Klartextwerte im Ruhezustand meldet, besteht das Risiko des Agent-Zugriffs weiterhin, auch wenn Laufzeit-APIs redigierte Werte zurückgeben.

Wenn Sie während configure einen Plan speichern, statt ihn anzuwenden, wenden Sie diesen gespeicherten Plan vor dem erneuten Audit mit openclaw secrets apply --from <plan-path> an.

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

Einweg-Sicherheitsrichtlinie

Sicherheitsmodell:

• Preflight muss erfolgreich sein, bevor der Schreibmodus verwendet wird
• Laufzeitaktivierung wird vor dem Commit validiert
• Apply aktualisiert Dateien mit atomarer Dateiersetzung und Best-Effort-Wiederherstellung bei Fehlern

Hinweise zur Legacy-Auth-Kompatibilität

Für statische Zugangsdaten hängt die Laufzeit nicht mehr von Klartext-Legacy-Auth-Speicher ab.

• Die Quelle für Laufzeit-Zugangsdaten ist der aufgelöste In-Memory-Snapshot.
• Statische Legacy-api_key-Einträge werden bereinigt, wenn sie entdeckt werden.
• OAuth-bezogenes Kompatibilitätsverhalten bleibt getrennt.

Hinweis zur Web-UI

Einige SecretInput-Unions lassen sich im Roh-Editor-Modus leichter konfigurieren als im Formularmodus.

Verwandte Themen

• Authentifizierung — Auth-Einrichtung
• CLI: secrets — CLI-Befehle
• Umgebungsvariablen — Umgebungspriorität
• SecretRef-Zugangsdatenoberfläche — Zugangsdatenoberfläche
• Secrets Apply Plan-Vertrag — Details zum Planvertrag
• Sicherheit — Sicherheitsstatus