Verwaltung von Geheimnissen

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

Laufzeitmodell

• Geheimnisse werden während der Aktivierung vorab in einen speicherinternen Laufzeit-Snapshot aufgelöst, nicht erst bei Bedarf in Anfragepfaden.
• Der Start schlägt sofort fehl, wenn eine tatsächlich aktive SecretRef nicht aufgelöst werden kann.
• Ein Neuladen erfolgt als atomarer Austausch: entweder vollständig erfolgreich oder der letzte als funktionsfähig bekannte Snapshot bleibt erhalten.
• Richtlinienverstöße (beispielsweise ein Authentifizierungsprofil im OAuth-Modus in Kombination mit einer SecretRef-Eingabe) lassen die Aktivierung vor dem Austausch des Laufzeit-Snapshots fehlschlagen.
• Laufzeitanfragen lesen ausschließlich den aktiven speicherinternen Snapshot. SecretRef-Zugangsdaten für Modell-Provider werden bis zur ausgehenden Übertragung als prozesslokale Sentinel-Werte durch den Authentifizierungsspeicher und die Stream-Optionen weitergegeben. Ausgehende Zustellungspfade (Discord-Antwort-/Thread-Zustellung, das Senden von Telegram-Aktionen) lesen ebenfalls diesen Snapshot und lösen Referenzen nicht bei jedem Sendevorgang erneut auf.

Dadurch wirken sich Ausfälle von Geheimnis-Providern nicht auf häufig genutzte Anfragepfade aus.

Injektion bei der ausgehenden Übertragung (Sentinel-Werte)

Für Zugangsdaten von Modell-Providern, die auf SecretRefs basieren, erzeugt OpenClaw während der Auflösung der Modellauthentifizierung einen undurchsichtigen, prozesslokalen Sentinel-Wert. Authentifizierungsspeicher, Stream-Optionen, SDK-Konfiguration, Protokolle, Fehlerobjekte und die meisten Laufzeitinspektionen sehen daher einen Wert wie oc-sent-v1-... statt der Zugangsdaten des Providers. Der abgesicherte Modellabruf und verwaltete Zustandsprüfungen lokaler Provider ersetzen bekannte Sentinel-Werte in URL- und Header-Werten unmittelbar bevor die jeweilige Anfrage den Prozess verlässt.

Unbekannte Werte im Sentinel-Format führen vor jeglicher Netzwerkaktivität zu einem sicheren Abbruch. OpenClaw verweigert das Senden der Anfrage, statt einen nicht aufgelösten Sentinel-Wert an einen Provider weiterzuleiten. Aufgelöste Geheimniswerte werden außerdem zur exakten wertbasierten Schwärzung in Protokollen registriert, um eine zusätzliche Schutzebene zu schaffen.

Provider-Adapter verwenden den spätestmöglichen Injektionspunkt, den ihr SDK unterstützt:

• SDKs mit einer benutzerdefinierten Fetch-Option erhalten den abgesicherten Fetch von OpenClaw, sodass das SDK den Sentinel-Wert beibehält.
• SDKs ohne benutzerdefinierte Fetch-Option entpacken den Sentinel-Wert unmittelbar vor der Client-Erstellung. Plugin-eigene Provider-Streams und Agent-Harnesses entpacken ihn bei der letzten vom Kern verwalteten Übergabe, da diese Transporte den abgesicherten Fetch von OpenClaw nicht gemeinsam nutzen.

Sentinel-Werte verringern die Klartextexposition entlang der Modellaufrufkette, stellen jedoch keine Prozessisolierung dar. Der echte Wert ist weiterhin im Speicher desselben Prozesses vorhanden und erscheint an der abschließenden Adaptergrenze. Einfache Umgebungs-Zugangsdaten, die nicht über SecretRefs konfiguriert sind, bleiben im Klartext und fallen nicht unter diesen Mechanismus.

Setzen Sie OPENCLAW_SECRET_SENTINELS=off (akzeptiert ohne Berücksichtigung der Groß-/Kleinschreibung auch 0 oder false), um die Erzeugung von Sentinel-Werten bei der Reaktion auf Vorfälle oder bei der Behebung von Kompatibilitätsproblemen zu deaktivieren. Der Notausschalter deaktiviert nicht die Registrierung für die exakte wertbasierte Schwärzung.

Grenze des Agentenzugriffs

SecretRefs verhindern, dass Zugangsdaten in Konfigurationsdateien und generierten Modelldateien gespeichert werden, stellen jedoch keine Prozessisolierungsgrenze dar. Klartext-Zugangsdaten, die auf dem Datenträger in einem für den Agenten lesbaren Pfad verbleiben, können weiterhin über Datei- oder Shell-Werkzeuge gelesen werden, wodurch die Schwärzung auf API-Ebene umgangen wird.

Betrachten Sie bei Produktionsbereitstellungen, in denen für Agenten zugängliche Dateien relevant sind, die Migration erst dann als abgeschlossen, wenn alle folgenden Bedingungen erfüllt sind:

• Unterstützte Zugangsdaten verwenden SecretRefs anstelle von Klartextwerten.
• Veraltete Klartextreste wurden aus openclaw.json, auth-profiles.json, .env und generierten models.json-Dateien entfernt.
• openclaw secrets audit --check meldet nach der Migration keine Probleme.
• Alle verbleibenden nicht unterstützten oder rotierenden Zugangsdaten werden durch Betriebssystemisolierung, Containerisolierung oder einen externen Zugangsdaten-Proxy geschützt.

Deshalb ist der Audit-/Konfigurations-/Anwendungs-Workflow ein Sicherheitstor für die Migration und nicht nur eine Komfortfunktion.

Filterung aktiver Oberflächen

SecretRefs werden nur auf tatsächlich aktiven Oberflächen validiert:

• Aktivierte Oberflächen: Nicht aufgelöste Referenzen blockieren den Start/das Neuladen.
• Inaktive Oberflächen: Nicht aufgelöste Referenzen blockieren den Start/das Neuladen nicht; sie erzeugen eine nicht schwerwiegende SECRETS_REF_IGNORED_INACTIVE_SURFACE-Diagnose.

Diagnose der Gateway-Authentifizierungsoberflächen

Wenn eine SecretRef für gateway.auth.token, gateway.auth.password, gateway.remote.token oder gateway.remote.password festgelegt ist, protokolliert der Gateway-Start bzw. das Neuladen den Oberflächenstatus unter dem Code SECRETS_GATEWAY_AUTH_SURFACE:

• active: Die SecretRef ist Teil der tatsächlich verwendeten Authentifizierungsoberfläche und muss aufgelöst werden.
• inactive: Eine andere Authentifizierungsoberfläche hat Vorrang oder die Remote-Authentifizierung ist deaktiviert/nicht aktiv.

Der Protokolleintrag enthält den Grund, den die Richtlinie für aktive Oberflächen verwendet hat.

Vorabprüfung von Referenzen beim Onboarding

Wenn Sie beim interaktiven Onboarding die Speicherung als SecretRef auswählen, wird vor dem Speichern eine Vorabvalidierung ausgeführt:

• Umgebungsreferenzen: Der Name der Umgebungsvariable wird validiert und es wird bestätigt, dass während der Einrichtung ein nicht leerer Wert sichtbar ist.
• Provider-Referenzen (file oder exec): Die Provider-Auswahl wird validiert, id wird aufgelöst und der Typ des aufgelösten Werts wird geprüft.
• Schnellstart-Workflow: Wenn gateway.auth.token bereits eine SecretRef ist, löst das Onboarding sie vor der Initialisierung der Prüfung/des Dashboards mit derselben Sofortabbruchprüfung auf (für env-, file- und exec-Referenzen).

Bei einem Validierungsfehler wird der Fehler angezeigt und Sie können es erneut versuchen.

SecretRef-Vertrag

Überall dieselbe Objektstruktur:

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

Dateibasierte API-Schlüssel

Setzen Sie keine file:...-Zeichenfolgen in den Konfigurationsblock env. Dieser Block ist literal und überschreibt nichts, daher wird file:... dort niemals aufgelöst.

Verwenden Sie stattdessen eine Datei-SecretRef in einem unterstützten Anmeldedatenfeld:

{  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" lautet die SecretRef-id "value". Verwenden Sie für mode: "json" einen absoluten JSON-Zeiger wie "/providers/xai/apiKey".

Die Felder, die SecretRefs akzeptieren, finden Sie unter SecretRef-Anmeldedatenoberfläche.

Beispiele für die Exec-Integration

{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // erforderlich für über Homebrew verknüpfte Binärdateien        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, // erforderlich für über Homebrew verknüpfte Binärdateien        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(`Anfrage konnte nicht geparst werden: ${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 wurde mit ${result.status} beendet`).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, // erforderlich für über Homebrew verknüpfte Binärdateien        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" },      },    },  },}

Umgebungsvariablen für MCP-Server

Über plugins.entries.acpx.config.mcpServers konfigurierte Umgebungsvariablen für MCP-Server akzeptieren SecretInput, sodass API-Schlüssel und Token nicht im Klartext in der Konfiguration stehen:

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

Zeichenfolgenwerte im Klartext funktionieren weiterhin. Referenzen aus Umgebungsvorlagen wie ${MCP_SERVER_API_KEY} und SecretRef-Objekte werden während der Gateway-Aktivierung aufgelöst, bevor der MCP-Serverprozess gestartet wird. Wie bei anderen SecretRef-Oberflächen blockieren nicht aufgelöste Referenzen die Aktivierung nur, wenn das acpx-Plugin tatsächlich aktiv ist.

SSH-Authentifizierungsmaterial für die Sandbox

Das zentrale ssh-Sandbox-Backend unterstützt auch SecretRefs für SSH-Authentifizierungsmaterial:

{  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 Referenzen während der Sandbox-Aktivierung auf, nicht verzögert bei jedem SSH-Aufruf.
• Aufgelöste Werte werden mit restriktiven Dateiberechtigungen (0o600) in ein temporäres Verzeichnis geschrieben und in der generierten SSH-Konfiguration verwendet.
• Wenn das tatsächlich verwendete Sandbox-Backend nicht ssh ist (oder der Sandbox-Modus off lautet), bleiben diese Referenzen inaktiv und blockieren den Start nicht.

Unterstützte Anmeldedatenoberfläche

Die kanonisch unterstützten und nicht unterstützten Anmeldedaten sind unter SecretRef-Anmeldedatenoberfläche aufgeführt.

Erforderliches Verhalten und Priorität

• Feld ohne Referenz: unverändert.
• Feld mit Referenz: auf aktiven Oberflächen während der Aktivierung erforderlich.
• Wenn sowohl Klartext als auch eine Referenz vorhanden sind, hat die Referenz auf unterstützten Prioritätspfaden Vorrang.
• Der Schwärzungs-Sentinel __OPENCLAW_REDACTED__ ist für die interne Schwärzung/Wiederherstellung der Konfiguration reserviert und wird als literal übermittelte Konfigurationsangabe abgelehnt.

Warn- und Auditsignale:

• SECRETS_REF_OVERRIDES_PLAINTEXT (Laufzeitwarnung)
• REF_SHADOWED (Audit-Feststellung, wenn Anmeldedaten aus auth-profiles.json Vorrang vor Referenzen aus openclaw.json haben)

Google-Chat-Kompatibilität: serviceAccountRef hat Vorrang vor serviceAccount im Klartext; der Klartextwert wird ignoriert, sobald die gleichgeordnete Referenz gesetzt ist.

Aktivierungsauslöser

Die Secret-Aktivierung wird ausgelöst bei:

• Start (Vorabprüfung und abschließende Aktivierung)
• Hot-Apply-Pfad beim Neuladen der Konfiguration
• Neustartprüfungspfad beim Neuladen der Konfiguration
• Manuellem Neuladen über secrets.reload
• Vorabprüfung des Gateway-RPC zum Schreiben der Konfiguration (config.set / config.apply / config.patch), wobei vor dem Speichern von Änderungen geprüft wird, ob SecretRefs auf aktiven Oberflächen innerhalb der übermittelten Konfigurationsnutzlast aufgelöst werden können

Aktivierungsvertrag:

• Bei Erfolg wird der Snapshot atomar ausgetauscht.
• Ein Fehler beim Start bricht den Gateway-Start ab.
• Bei einem Fehler beim Neuladen zur Laufzeit bleibt der letzte bekanntermaßen funktionsfähige Snapshot erhalten.
• Schlägt die Vorabprüfung des Schreib-RPC fehl, wird die übermittelte Konfiguration abgelehnt; sowohl die Konfiguration auf dem Datenträger als auch der aktive Laufzeit-Snapshot bleiben unverändert.
• Die Angabe eines expliziten, aufrufsspezifischen Kanal-Tokens für einen ausgehenden Helfer-/Tool-Aufruf löst keine SecretRef-Aktivierung aus; die Aktivierungspunkte bleiben der Start, das Neuladen und der explizite Aufruf von 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 Secret-Zustand und gibt einmalige Systemereignisse und Protokollcodes aus:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Verhalten:

• Beeinträchtigt: Die Laufzeit behält den letzten bekanntermaßen funktionsfähigen Snapshot bei.
• Wiederhergestellt: Wird nach der nächsten erfolgreichen Aktivierung einmalig ausgegeben.
• Wiederholte Fehler, während bereits eine Beeinträchtigung besteht, werden als Warnungen protokolliert, lösen das Ereignis jedoch nicht erneut aus.
• Ein schneller Abbruch beim Start löst niemals ein Ereignis für eine Beeinträchtigung aus, da die Laufzeit nie aktiv wurde.

Auflösung von Befehlspfaden

Befehlspfade können sich über einen Gateway-Snapshot-RPC für die unterstützte SecretRef-Auflösung entscheiden. Dabei gelten zwei allgemeine Verhaltensweisen:

Weitere Hinweise:

• Die Aktualisierung des Snapshots nach der Rotation eines Geheimnisses im Backend erfolgt über openclaw secrets reload.
• Von diesen Befehlspfaden verwendete Gateway-RPC-Methode: secrets.resolve.

Audit- und Konfigurationsablauf

Standardablauf für Betreiber:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

Betrachten Sie die Migration erst dann als abgeschlossen, wenn die erneute Prüfung keine Beanstandungen ergibt. Wenn das Audit weiterhin unverschlüsselte gespeicherte Werte meldet, besteht das Risiko des Agentenzugriffs fort, selbst wenn Laufzeit-APIs geschwärzte Werte zurückgeben.

Wenn Sie während configure einen Plan speichern, statt ihn anzuwenden, wenden Sie diesen gespeicherten Plan vor der erneuten Prüfung 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:

• Die Vorabprüfung muss erfolgreich sein, bevor der Schreibmodus beginnt.
• Die Laufzeitaktivierung wird vor dem Commit validiert.
• Beim Anwenden werden Dateien durch atomaren Dateiaustausch aktualisiert; bei einem Fehler wird nach Möglichkeit der vorherige Zustand wiederhergestellt.

Hinweise zur Kompatibilität mit veralteter Authentifizierung

Bei statischen Anmeldedaten ist die Laufzeit nicht mehr von der veralteten unverschlüsselten Authentifizierungsspeicherung abhängig.

• Die Quelle der Laufzeitanmeldedaten ist der aufgelöste In-Memory-Snapshot.
• Veraltete statische api_key-Einträge werden entfernt, sobald sie gefunden werden.
• OAuth-bezogenes Kompatibilitätsverhalten bleibt davon getrennt.

Hinweis zur Web-Benutzeroberfläche

Einige SecretInput-Unions lassen sich im Rohbearbeitungsmodus einfacher konfigurieren als im Formularmodus.

Verwandte Themen

• Authentifizierung - Einrichtung der Authentifizierung
• CLI: Geheimnisse - CLI-Befehle
• Vault-SecretRefs - Einrichtung des HashiCorp-Vault-Providers
• Umgebungsvariablen - Vorrang von Umgebungsvariablen
• Anmeldedatenoberfläche für SecretRefs - Anmeldedatenoberfläche
• Vertrag für den Plan zur Anwendung von Geheimnissen - Einzelheiten zum Planvertrag
• Sicherheit - Sicherheitskonzept