Sicheres Secrets-Management mit openclaw secrets

Secrets zu verwalten ist oft mühsam. Mal landet aus Versehen ein API-Key im Plaintext in einer Config-Datei, mal schlägt das Deployment fehl, weil eine Credential-Referenz ins Leere läuft. Es ist schwer, den Überblick zu behalten, welche Secrets noch aktuell sind und wo noch alte Reste in verstreuten JSON-Dateien herumliegen.

Diese manuellen Fehler führen meistens zu unsicheren Umgebungen oder kaputten Runtimes. Mit openclaw secrets kannst du diesen Prozess automatisieren und sicherstellen, dass deine Credentials nur dort landen, wo sie auch hingehören.

Voraussetzungen

• OpenClaw CLI
• Ein interaktives Terminal (TTY) für den configure Befehl
• Zugriff auf das Gateway (für RPC-Befehle wie reload)

Schnellstart

Hier ist der empfohlene Workflow, um deine Secrets zu prüfen, zu migrieren und die Runtime zu aktualisieren:

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

Secrets prüfen mit Audit

Der audit Befehl scannt deinen OpenClaw-Status auf kritische Probleme. Er findet Plaintext-Secrets, nicht aufgelöste Referenzen und “Precedence Drift” (wenn Credentials in auth-profiles.json deine openclaw.json Referenzen überschreiben).

openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json

Wenn du --check in deiner CI/CD-Pipeline nutzt, gibt der Befehl bei Funden den Exit-Code 1 zurück. Nicht aufgelöste Referenzen liefern den Code 2. Das ist der beste Weg, um Plaintext-Leaks vor einem Release zu verhindern.

Interaktive Konfiguration

Mit openclaw secrets configure startest du einen interaktiven Planer. Du kannst Provider-Setups anpassen und Credentials direkt auf SecretRefs mappen.

openclaw secrets configure --agent ops

Der Flow ist simpel: Zuerst konfigurierst du die Provider-Aliase, dann mappst du die Felder auf die entsprechenden Quellen. Am Ende erstellt das Tool einen Plan, den du speichern oder direkt anwenden kannst. Beachte, dass dieser Befehl ein interaktives TTY benötigt.

Änderungen anwenden

Wenn du einen Plan mit configure erstellt hast, nutzt du apply, um die Änderungen in openclaw.json und auth-profiles.json zu schreiben. Dabei werden Plaintext-Werte automatisch bereinigt (Scrubbing).

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

Es gibt absichtlich keine Rollback-Backups, die Plaintext-Werte enthalten. Die Sicherheit wird durch strikte Preflight-Checks und ein atomares Update-Verhalten gewährleistet.

Runtime aktualisieren

Nachdem die Dateien auf der Festplatte aktualisiert wurden, muss das Gateway die neuen Secrets laden. openclaw secrets reload nutzt einen RPC-Call, um den Runtime-Snapshot atomar auszutauschen.

openclaw secrets reload

Schlägt die Auflösung eines Secrets fehl, behält das Gateway den letzten funktionierenden Snapshot bei. Es gibt keine Teil-Aktivierungen, sodass deine API stabil bleibt.

Fehlerbehebung

• Audit meldet weiterhin Plaintext: Wenn audit --check nach einem apply noch Fehler zeigt, prüfe die gemeldeten Pfade manuell. Möglicherweise gibt es Reste in agents/*/agent/models.json, die manuell bereinigt werden müssen.
• Fehler bei Exec-Providern (macOS): Homebrew nutzt oft Symlinks unter /opt/homebrew/bin/. Setze in diesem Fall allowSymlinkCommand: true und füge den Pfad zu trustedDirs hinzu.
• Windows-Pfadsicherheit: Wenn die ACL-Verifizierung fehlschlägt, bricht OpenClaw ab. Für vertrauenswürdige Pfade kannst du allowInsecurePath: true beim Provider setzen.

Du hast Fragen zu einem spezifischen Setup? Nutze den AI Setup Assistant für schnelle Hilfe.

Nächste Schritte

• Secrets Management Guide
• SecretRef Credential Surface
• Security Guide
• Secrets Apply Plan Contract