OpenClaw unterstützt additive SecretRefs, damit unterstützte Anmeldedaten nicht als Klartext in der Konfiguration gespeichert werden müssen.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
Klartext funktioniert weiterhin. SecretRefs sind pro Anmeldedatum opt-in.
Ziele und Laufzeitmodell
Secrets werden in einen In-Memory-Laufzeit-Snapshot aufgelöst.- Die Auflösung erfolgt während der Aktivierung eager, nicht lazy auf Anfragepfaden.
- Der Start schlägt schnell fehl, wenn eine effektiv aktive SecretRef nicht aufgelöst werden kann.
- Reload verwendet atomaren Austausch: vollständiger Erfolg oder Beibehaltung des zuletzt als gut bekannten Snapshots.
- SecretRef-Richtlinienverstöße (zum Beispiel OAuth-Modus-Auth-Profile in Kombination mit SecretRef-Eingaben) lassen die Aktivierung vor dem Laufzeitaustausch fehlschlagen.
- Laufzeitanfragen lesen nur aus dem aktiven In-Memory-Snapshot.
- Nach der ersten erfolgreichen Konfigurationsaktivierung bzw. dem ersten erfolgreichen Laden lesen Laufzeit-Codepfade weiterhin diesen aktiven In-Memory-Snapshot, bis ein erfolgreicher Reload ihn austauscht.
- Ausgehende Zustellungspfade 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.
Filterung aktiver Oberflächen
SecretRefs werden nur auf effektiv aktiven Oberflächen validiert.- Aktivierte Oberflächen: nicht aufgelöste Refs blockieren Start/Reload.
- Inaktive Oberflächen: nicht aufgelöste Refs blockieren Start/Reload nicht.
- Inaktive Refs geben nicht-fatale Diagnosen mit dem Code
SECRETS_REF_IGNORED_INACTIVE_SURFACEaus.
Beispiele für inaktive Oberflächen
Beispiele für inaktive Oberflächen
- Deaktivierte Kanal-/Kontoeinträge.
- Top-Level-Kanalanmeldedaten, die kein aktiviertes Konto erbt.
- Deaktivierte Tool-/Feature-Oberflächen.
- Websuche-Provider-spezifische Schlüssel, die nicht durch
tools.web.search.providerausgewählt sind. Im Automatikmodus (Provider nicht gesetzt) werden Schlüssel in Prioritätsreihenfolge für die automatische Provider-Erkennung herangezogen, bis einer aufgelöst wird. Nach der Auswahl werden nicht ausgewählte Provider-Schlüssel als inaktiv behandelt, bis sie ausgewählt werden. - Sandbox-SSH-Auth-Material (
agents.defaults.sandbox.ssh.identityData,certificateData,knownHostsDatasowie Überschreibungen pro Agent) ist nur aktiv, wenn das effektive Sandbox-Backend für den Standard-Agenten oder einen aktivierten Agentensshist. gateway.remote.token/gateway.remote.password-SecretRefs sind aktiv, wenn eine der folgenden Bedingungen zutrifft:gateway.mode=remotegateway.remote.urlist konfiguriertgateway.tailscale.modeistserveoderfunnel- Im lokalen Modus ohne diese Remote-Oberflächen:
gateway.remote.tokenist aktiv, wenn Token-Auth gewinnen kann und kein Env-/Auth-Token konfiguriert ist.gateway.remote.passwordist nur aktiv, wenn Passwort-Auth gewinnen kann und kein Env-/Auth-Passwort konfiguriert ist.
- Die
gateway.auth.token-SecretRef ist für die Start-Auth-Auflösung inaktiv, wennOPENCLAW_GATEWAY_TOKENgesetzt ist, weil die Env-Token-Eingabe für diese Laufzeit gewinnt.
Gateway-Auth-Oberflächendiagnosen
Wenn eine SecretRef fürgateway.auth.token, gateway.auth.password, gateway.remote.token oder gateway.remote.password konfiguriert ist, protokolliert Gateway-Start/Reload den Oberflächenstatus explizit:
active: Die SecretRef ist Teil der effektiven Auth-Oberfläche und muss aufgelöst werden.inactive: Die SecretRef wird für diese Laufzeit ignoriert, weil eine andere Auth-Oberfläche gewinnt oder weil Remote-Auth deaktiviert/nicht aktiv ist.
SECRETS_GATEWAY_AUTH_SURFACE protokolliert und enthalten den Grund, den die Richtlinie für aktive Oberflächen verwendet, sodass Sie sehen können, warum ein Anmeldedatum als aktiv oder inaktiv behandelt wurde.
Onboarding-Referenz-Preflight
Wenn Onboarding im interaktiven Modus läuft und Sie SecretRef-Speicherung wählen, führt OpenClaw vor dem Speichern eine Preflight-Validierung aus:- Env-Refs: validiert den Env-Variablennamen und bestätigt, dass während der Einrichtung ein nicht leerer Wert sichtbar ist.
- Provider-Refs (
fileoderexec): validiert die Provider-Auswahl, löstidauf und prüft den Typ des aufgelösten Werts. - Quickstart-Wiederverwendungspfad: Wenn
gateway.auth.tokenbereits eine SecretRef ist, löst Onboarding sie vor Probe-/Dashboard-Bootstrap auf (fürenv-,file- undexec-Refs) und verwendet dabei dasselbe Fail-Fast-Gate.
SecretRef-Vertrag
Verwenden Sie überall dieselbe Objektform:- env
- file
- exec
providermuss^[a-z][a-z0-9_-]{0,63}$entsprechenidmuss^[A-Z][A-Z0-9_]{0,127}$entsprechen
Provider-Konfiguration
Definieren Sie Provider untersecrets.providers:
Env-Provider
Env-Provider
- Optionale Allowlist über
allowlist. - Fehlende/leere Env-Werte lassen die Auflösung fehlschlagen.
File-Provider
File-Provider
- Liest lokale Datei aus
path. mode: "json"erwartet eine JSON-Objekt-Payload und löstidals Pointer auf.mode: "singleValue"erwartet die Ref-ID"value"und gibt den Dateiinhalt zurück.- Der Pfad muss Besitz-/Berechtigungsprüfungen bestehen.
- Windows-Fail-Closed-Hinweis: Wenn die ACL-Verifizierung für einen Pfad nicht verfügbar ist, schlägt die Auflösung fehl. Nur für vertrauenswürdige Pfade können Sie
allowInsecurePath: truefür diesen Provider setzen, um Pfadsicherheitsprüfungen zu umgehen.
Exec-Provider
Exec-Provider
- Führt den konfigurierten absoluten Binärpfad aus, ohne Shell.
- Standardmäßig muss
commandauf eine reguläre Datei zeigen (kein Symlink). - Setzen Sie
allowSymlinkCommand: true, um Symlink-Befehlspfade zuzulassen (zum Beispiel Homebrew-Shims). OpenClaw validiert den aufgelösten Zielpfad. - Kombinieren Sie
allowSymlinkCommandmittrustedDirsfür Paketmanager-Pfade (zum Beispiel["/opt/homebrew"]). - Unterstützt Timeout, Timeout bei fehlender Ausgabe, Ausgabe-Byte-Limits, Env-Allowlist und vertrauenswürdige Verzeichnisse.
- Windows-Fail-Closed-Hinweis: Wenn die ACL-Verifizierung für den Befehlspfad nicht verfügbar ist, schlägt die Auflösung fehl. Nur für vertrauenswürdige Pfade können Sie
allowInsecurePath: truefür diesen Provider setzen, um Pfadsicherheitsprüfungen zu umgehen.
Exec-Integrationsbeispiele
1Password CLI
1Password CLI
HashiCorp Vault CLI
HashiCorp Vault CLI
sops
sops
MCP-Server-Umgebungsvariablen
MCP-Server-Env-Variablen, die überplugins.entries.acpx.config.mcpServers konfiguriert werden, unterstützen SecretInput. Dadurch bleiben API-Schlüssel und Tokens aus der Klartextkonfiguration heraus:
${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.
Sandbox-SSH-Auth-Material
Das Core-ssh-Sandbox-Backend unterstützt ebenfalls SecretRefs für SSH-Auth-Material:
- OpenClaw löst diese Refs während der Sandbox-Aktivierung auf, nicht verzögert bei jedem SSH-Aufruf.
- Aufgelöste Werte werden mit restriktiven Berechtigungen in temporäre Dateien geschrieben und in der generierten SSH-Konfiguration verwendet.
- Wenn das effektive Sandbox-Backend nicht
sshist, bleiben diese Refs inaktiv und blockieren den Start nicht.
Unterstützte Anmeldeinformations-Oberfläche
Kanonisch unterstützte und nicht unterstützte Anmeldeinformationen sind aufgeführt in:Zur Laufzeit erzeugte oder rotierende Anmeldeinformationen und OAuth-Aktualisierungsmaterial sind absichtlich von der schreibgeschützten SecretRef-Auflösung ausgeschlossen.
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 Vorrangspfaden Vorrang.
- Der Schwärzungs-Sentinel
__OPENCLAW_REDACTED__ist für interne Konfigurationsschwärzung/-wiederherstellung reserviert und wird als wörtlich übermittelte Konfigurationsdaten abgelehnt.
SECRETS_REF_OVERRIDES_PLAINTEXT(Laufzeitwarnung)REF_SHADOWED(Audit-Befund, wenn Anmeldeinformationen ausauth-profiles.jsonVorrang vor Refs ausopenclaw.jsonhaben)
serviceAccountRefhat Vorrang vor Klartext-serviceAccount.- Der Klartextwert wird ignoriert, wenn eine benachbarte Ref gesetzt ist.
Aktivierungsauslöser
Secret-Aktivierung läuft bei:- Start (Preflight plus finale Aktivierung)
- Hot-Apply-Pfad zum Neuladen der Konfiguration
- Restart-Check-Pfad zum 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
- Erfolg tauscht den Snapshot atomar aus.
- Ein Startfehler bricht den Gateway-Start ab.
- Ein Laufzeit-Neuladefehler behält den letzten als funktionierend bekannten Snapshot.
- Ein Write-RPC-Preflight-Fehler lehnt die übermittelte Konfiguration ab und lässt sowohl die Konfiguration auf der Festplatte als auch den aktiven Laufzeit-Snapshot unverändert.
- Das Bereitstellen eines expliziten kanalbezogenen 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 eingeschränkten und wiederhergestellten Zustand
Wenn die Aktivierung beim Neuladen nach einem fehlerfreien Zustand fehlschlägt, wechselt OpenClaw in einen eingeschränkten Secrets-Zustand. Einmalige Systemereignis- und Protokollcodes:SECRETS_RELOADER_DEGRADEDSECRETS_RELOADER_RECOVERED
- Eingeschränkt: Die Laufzeit behält den letzten als funktionierend bekannten Snapshot.
- Wiederhergestellt: Wird einmal nach der nächsten erfolgreichen Aktivierung ausgegeben.
- Wiederholte Fehler, während der Zustand bereits eingeschränkt ist, protokollieren Warnungen, erzeugen aber keine Ereignisflut.
- Start-Fail-Fast gibt keine Ereignisse für eingeschränkten Zustand aus, weil die Laufzeit nie aktiv wurde.
Auflösung von Befehlspfaden
Befehlspfade können sich über Gateway-Snapshot-RPC für die unterstützte SecretRef-Auflösung anmelden. Es gibt zwei allgemeine Verhaltensweisen:- Strict command paths
- Read-only command paths
Zum Beispiel
openclaw memory-Remote-Memory-Pfade und openclaw qr --remote, wenn Remote-Shared-Secret-Refs benötigt werden. Sie lesen aus dem aktiven Snapshot und schlagen schnell fehl, wenn eine erforderliche SecretRef nicht verfügbar ist.- Die Snapshot-Aktualisierung nach Secret-Rotation im Backend wird von
openclaw secrets reloadbehandelt. - Von diesen Befehlspfaden verwendete Gateway-RPC-Methode:
secrets.resolve.
Audit- und Konfigurationsworkflow
Standardablauf für Betreiber:secrets audit
secrets audit
Befunde umfassen:
- Klartextwerte im Ruhezustand (
openclaw.json,auth-profiles.json,.envund generierteagents/*/agent/models.json) - Klartextreste sensibler Provider-Header in generierten
models.json-Einträgen - nicht aufgelöste Refs
- Vorrangsschatten (
auth-profiles.jsonhat Priorität vor Refs ausopenclaw.json) - Legacy-Reste (
auth.json, OAuth-Erinnerungen)
- Standardmäßig überspringt das Audit Auflösbarkeitsprüfungen für Exec-SecretRefs, um Befehlsnebeneffekte zu vermeiden.
- Verwenden Sie
openclaw secrets audit --allow-exec, um Exec-Provider während des Audits auszuführen.
- Die Erkennung sensibler Provider-Header basiert auf Namensheuristiken (gängige Namen und Fragmente von Authentifizierungs-/Anmeldeinformations-Headern wie
authorization,x-api-key,token,secret,passwordundcredential).
secrets configure
secrets configure
Interaktiver Helper, der:
- zuerst
secrets.providerskonfiguriert (env/file/exec, hinzufügen/bearbeiten/entfernen) - Sie unterstützte Secret-tragende Felder in
openclaw.jsonplusauth-profiles.jsonfür einen Agent-Scope auswählen lässt - direkt in der Zielauswahl ein neues
auth-profiles.json-Mapping erstellen kann - SecretRef-Details erfasst (
source,provider,id) - Preflight-Auflösung ausführt
- sofort anwenden kann
- Preflight überspringt Exec-SecretRef-Prüfungen, sofern
--allow-execnicht gesetzt ist. - Wenn Sie direkt aus
configure --applyanwenden und der Plan Exec-Refs/-Provider enthält, lassen Sie--allow-execauch für den Apply-Schritt gesetzt.
openclaw secrets configure --providers-onlyopenclaw secrets configure --skip-provider-setupopenclaw secrets configure --agent <id>
configure-Apply-Standardeinstellungen:- passende statische Anmeldeinformationen aus
auth-profiles.jsonfür gezielte Provider bereinigen - statische Legacy-
api_key-Einträge ausauth.jsonbereinigen - passende bekannte Secret-Zeilen aus
<config-dir>/.envbereinigen
secrets apply
secrets apply
Einen gespeicherten Plan anwenden:Exec-Hinweis:
- Dry-run überspringt Exec-Prüfungen, sofern
--allow-execnicht gesetzt ist. - Schreibmodus lehnt Pläne mit Exec-SecretRefs/-Providern ab, sofern
--allow-execnicht gesetzt ist.
Einweg-Sicherheitsrichtlinie
Sicherheitsmodell:- Preflight muss vor dem Schreibmodus erfolgreich sein
- Laufzeitaktivierung wird vor dem Commit validiert
- Apply aktualisiert Dateien mit atomarem Dateiaustausch und Best-Effort-Wiederherstellung bei Fehlern
Legacy-Auth-Kompatibilitätshinweise
Für statische Anmeldeinformationen hängt die Laufzeit nicht mehr von Legacy-Auth-Speicherung im Klartext ab.- Quelle für Laufzeit-Anmeldeinformationen 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 einfacher konfigurieren als im Formularmodus.Verwandte Themen
- Authentifizierung — Auth-Einrichtung
- CLI: Secrets — CLI-Befehle
- Umgebungsvariablen — Umgebungsvorrang
- SecretRef-Anmeldeinformations-Oberfläche — Anmeldeinformations-Oberfläche
- Secrets-Apply-Planvertrag — Planvertragsdetails
- Sicherheit — Sicherheitslage