openclaw secrets

Verwende openclaw secrets, um SecretRefs zu verwalten und den aktiven Laufzeit-Snapshot gesund zu halten.

Befehlsrollen:

  • reload: Gateway-RPC (secrets.reload), der Refs erneut auflöst und den Laufzeit-Snapshot nur bei vollständigem Erfolg austauscht (keine Konfigurationsschreibvorgänge).
  • audit: Schreibgeschützter Scan von Konfigurations-/Auth-/generierten Modell-Stores und Legacy-Rückständen auf Klartext, unaufgelöste Refs und Prioritätsdrift.
  • configure: Interaktiver Planer für Provider-Setup, Ziel-Mapping und Vorabprüfung (TTY erforderlich).
  • apply: Einen gespeicherten Plan ausführen (--dry-run nur zur Validierung), dann gezielte Klartext-Rückstände bereinigen.

Empfohlener Betreiber-Ablauf:

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload

Exit-Code-Hinweis für CI/Gates:

  • audit --check gibt 1 bei Befunden zurück.
  • Unaufgelöste Refs geben 2 zurück.

Verwandte Themen:

Laufzeit-Snapshot neu laden

Secret-Refs erneut auflösen und den Laufzeit-Snapshot atomar austauschen.

openclaw secrets reload
openclaw secrets reload --json

Hinweise:

  • Verwendet die Gateway-RPC-Methode secrets.reload.
  • Wenn die Auflösung fehlschlägt, behält das Gateway den zuletzt bekannten guten Snapshot bei und gibt einen Fehler zurück (keine teilweise Aktivierung).
  • Die JSON-Antwort enthält warningCount.

Audit

OpenClaw-Zustand scannen auf:

  • Klartext-Secret-Speicherung
  • Unaufgelöste Refs
  • Prioritätsdrift (auth-profiles.json-Anmeldedaten, die openclaw.json-Refs überschatten)
  • Generierte agents/*/agent/models.json-Rückstände (Provider-apiKey-Werte und sensible Provider-Header)
  • Legacy-Rückstände (Legacy-Auth-Store-Einträge, OAuth-Erinnerungen)

Hinweis zu Header-Rückständen:

  • Die Erkennung sensibler Provider-Header basiert auf Namensheuristiken (gängige Auth-/Credential-Header-Namen und Fragmente wie authorization, x-api-key, token, secret, password und credential).
openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json

Exit-Verhalten:

  • --check beendet mit einem Nicht-Null-Code bei Befunden.
  • Unaufgelöste Refs beenden mit einem höher priorisierten Nicht-Null-Code.

Berichtsstruktur-Highlights:

  • status: clean | findings | unresolved
  • summary: plaintextCount, unresolvedRefCount, shadowedRefCount, legacyResidueCount
  • Befundcodes:
    • PLAINTEXT_FOUND
    • REF_UNRESOLVED
    • REF_SHADOWED
    • LEGACY_RESIDUE

Configure (interaktiver Helfer)

Provider- und SecretRef-Änderungen interaktiv erstellen, Vorabprüfung durchführen und optional anwenden:

openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json

Ablauf:

  • Zuerst Provider-Setup (add/edit/remove für secrets.providers-Aliase).
  • Dann Credential-Mapping (Felder auswählen und {source, provider, id}-Refs zuweisen).
  • Zum Schluss Vorabprüfung und optionales Anwenden.

Flags:

  • --providers-only: Nur secrets.providers konfigurieren, Credential-Mapping überspringen.
  • --skip-provider-setup: Provider-Setup überspringen und Credentials vorhandenen Providern zuordnen.
  • --agent <id>: auth-profiles.json-Ziel-Erkennung und Schreibvorgänge auf einen Agenten-Store beschränken.

Hinweise:

  • Erfordert ein interaktives TTY.
  • --providers-only und --skip-provider-setup können nicht kombiniert werden.
  • configure zielt auf geheimnistragende Felder in openclaw.json plus auth-profiles.json für den ausgewählten Agentenbereich.
  • configure unterstützt das Erstellen neuer auth-profiles.json-Zuordnungen direkt im Picker-Flow.
  • Kanonisch unterstützte Oberfläche: SecretRef Credential Surface.
  • Es führt eine Vorabauflösung vor dem Anwenden durch.
  • Generierte Pläne haben standardmäßig Bereinigungsoptionen (scrubEnv, scrubAuthProfilesForProviderTargets, scrubLegacyAuthJson alle aktiviert).
  • Der Anwendungspfad ist einbahnig für bereinigte Klartextwerte.
  • Ohne --apply fragt die CLI trotzdem Apply this plan now? nach der Vorabprüfung.
  • Mit --apply (und ohne --yes) fordert die CLI eine zusätzliche Bestätigung für die unwiderrufliche Aktion an.

Sicherheitshinweis zum Exec-Provider:

  • Homebrew-Installationen stellen oft symlinkte Binärdateien unter /opt/homebrew/bin/* bereit.
  • Setze allowSymlinkCommand: true nur wenn nötig für vertrauenswürdige Paketmanager-Pfade, und kombiniere es mit trustedDirs (zum Beispiel ["/opt/homebrew"]).
  • Unter Windows, wenn die ACL-Verifizierung für einen Provider-Pfad nicht verfügbar ist, schlägt OpenClaw geschlossen fehl. Nur für vertrauenswürdige Pfade setze allowInsecurePath: true auf diesem Provider, um die Pfad-Sicherheitsprüfungen zu umgehen.

Gespeicherten Plan anwenden

Einen zuvor generierten Plan anwenden oder vorab prüfen:

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json

Details zum Plan-Vertrag (erlaubte Zielpfade, Validierungsregeln und Fehlerverhalten):

Was apply aktualisieren kann:

  • openclaw.json (SecretRef-Ziele + Provider-Upserts/Deletes)
  • auth-profiles.json (Provider-Ziel-Bereinigung)
  • Legacy-auth.json-Rückstände
  • ~/.openclaw/.env bekannte Secret-Keys, deren Werte migriert wurden

Warum keine Rollback-Backups

secrets apply schreibt absichtlich keine Rollback-Backups, die alte Klartextwerte enthalten.

Sicherheit ergibt sich aus strikter Vorabprüfung + quasi-atomarem Anwenden mit Best-Effort-In-Memory-Wiederherstellung bei Fehlern.

Beispiel

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

Wenn audit --check weiterhin Klartext-Befunde meldet, aktualisiere die verbleibenden gemeldeten Zielpfade und führe den Audit erneut aus.

arrow_back
Zurück
Sandbox
Weiter
Security
arrow_forward