Geheimnisse sicher verwalten

Secrets Management klingt langweilig, bis an dem Tag ein Provider-Key in einem Repo, einem Screenshot oder einem Config-Backup landet. Dann wird es plötzlich sehr lebendig.

OpenClaw unterstützt inzwischen SecretRefs, damit unterstützte Zugangsdaten nicht als Klartext in der Konfiguration liegen müssen. Der Sinn ist nicht, Setup künstlich komplizierter zu machen. Der Sinn ist, echte Credentials in sichererer Ablage zu halten, sie sauber in die Runtime zu laden und Fehler kontrolliert scheitern zu lassen.

Der offizielle Guide zu Secrets Management und die CLI-Referenz zu openclaw secrets sind die zwei wichtigsten Seiten, die du dir dazu merken solltest.

Was SecretRefs eigentlich lösen

Klartext-Credentials sind ungefähr fünf Minuten lang bequem. Danach werden sie zu Haftnotizen an deiner Infrastruktur. Sie landen in kopierten Configs, Shell-History, Support-Nachrichten und alten Backups.

SecretRefs geben OpenClaw einen saubereren Vertrag. Statt das Secret selbst in ein Config-Feld zu schreiben, speicherst du nur einen Verweis darauf, wo das Secret herkommen soll.

Env-Provider: gut für einfache Setups und serviceverwaltete Umgebungen
File-Provider: gut, wenn du bereits eine lokal abgesicherte Secrets-Datei pflegst
Exec-Provider: gut, wenn Passwort-Manager oder Vault die eigentliche Quelle bleiben sollen

Das nützliche Bild ist simpel: Die Konfiguration sollte den Weg zu einem Secret beschreiben, nicht selbst zum Secret werden.

Wie OpenClaw Secrets zur Laufzeit auflöst

Dieser Teil ist wichtiger als die Syntax. OpenClaw löst Secrets früh beim Aktivieren auf und nicht erst mitten in einer laufenden Anfrage. Wenn ein effektiv aktiver SecretRef nicht aufgelöst werden kann, scheitern Start oder Reload sofort.

Das klingt streng, weil es streng ist. Genau das ist aber der richtige Tradeoff. Du willst die schlechte Überraschung beim Aktivieren sehen, nicht während einer Live-Antwort oder mitten in einem Webhook-Flow.

Auflösung ist früh: kaputte Refs werden vor dem Runtime-Swap erkannt
Reload ist atomisch: vollständiger Erfolg oder der letzte gute Snapshot bleibt aktiv
Heiße Request-Pfade bleiben sauber: die Runtime liest nur den aktiven In-Memory-Snapshot
Inaktive Oberflächen blockieren keinen Boot: deaktivierte oder ungenutzte Refs dürfen warnen, ohne das Gateway zu stoppen

Stell dir das wie den Umbau einer Bühne vor, bevor der Vorhang aufgeht. Wenn die Verkabelung falsch ist, stoppst du vorher. Du wartest nicht, bis der Scheinwerfer mitten in der Aufführung ausfällt.

Die drei SecretRef-Quellen

Alle SecretRefs nutzen dieselbe Grundform. Was sich ändert, ist die Quelle.

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }
{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }
{ source: "exec", provider: "vault", id: "providers/openai/apiKey" }

Env

Der Env-Weg ist der einfachste. Er passt gut, wenn dein Gateway Credentials ohnehin über systemd, Docker, eine Hosting-Plattform oder die lokale Shell-Umgebung bekommt.

File

Der File-Provider ist praktisch, wenn du eine lokale JSON-Secrets-Datei mit strengeren Rechten als deinen normalen Workspace pflegen willst. OpenClaw validiert den Pfad und kann je nach Provider-Modus entweder JSON-Pointer oder einen einzelnen Rohwert lesen.

Exec

Exec ist die erwachsenere Variante für Teams und Operatoren, die schon 1Password, Vault oder einen eigenen Resolver nutzen. OpenClaw führt ein erlaubtes Binary direkt aus, ohne Shell, und erwartet strukturierte Ausgabe zurück.

Das macht exec flexibel, aber nicht verspielt. Wenn du es nutzt, sei streng bei Trusted Paths, Timeouts und den Umgebungsvariablen, die du überhaupt durchreichst.

Der Operator-Workflow, der Ordnung schafft

Die CLI gibt dir inzwischen einen sauberen Secrets-Kreislauf. Nutze ihn. Secret-Aufräumarbeiten per zufälligen Hand-Edits sind der klassische Weg von guter Absicht zu rätselhaften Ausfällen.

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

Das macht jeder Schritt in Wirklichkeit:

Audit: Klartextspeicherung, ungelöste Refs, shadowed Werte und alte Reste finden
Configure: Provider definieren und Credentials auf Felder mappen, ohne Feldformen zu erraten
Dry Run: den Plan prüfen, bevor Dateien angefasst werden
Apply: geplante Änderungen schreiben und gezielte Klartext-Reste aufräumen
Audit erneut: bestätigen, dass das Setup wirklich sauberer geworden ist
Reload: atomisch auf den neu aufgelösten Runtime-Snapshot wechseln

Das ist der Unterschied zwischen "ich habe irgendwo ein paar Keys geändert" und "ich kann genau erklären, was sich geändert hat und warum die Runtime gesund ist".

SecretRefs versus Env-Substitution

OpenClaw unterstützt sowohl $${VAR_NAME}-artige Env-Substitution als auch SecretRef-Objekte. Beides hängt zusammen, ist aber nicht dasselbe.

Nutze Env-Substitution, wenn ein Config-String einfach einen Wert aus der Umgebung ziehen soll.
Nutze SecretRefs, wenn das Feld den Secrets-Workflow unterstützt und du Audits, Provider-Abstraktion und strukturiertes Secret-Handling willst.

Wenn du auf einer privaten Maschine nur einen simplen API-Key verdrahtest, reicht Env-Substitution oft aus. Für ernsthaftere Setups mit Audits, mehreren Providern oder sauberer Rotation sind SecretRefs langfristig die bessere Wahl.

Häufige Fehler

Secrets im Workspace lassen, weil er privat genug wirkt

Der Workspace ist privater Kontext, aber kein Tresor. Er ist der falsche Ort für Credentials, die du ungern in einem Backup, Diff oder geteilten Bildschirm sehen würdest.

Secrets migrieren, aber Audit nicht erneut laufen lassen

Den aktiven Config-Wert zu verschieben ist noch nicht die ganze Arbeit. Alte Klartextkopien überleben oft in Auth-Stores, generierten Model-Dateien oder Hilfs-Env-Dateien.

Die Regeln zu aktiven Oberflächen vergessen

Nicht jedes konfigurierte Secret ist bei jedem Start relevant. OpenClaw unterscheidet zwischen aktiven und inaktiven Oberflächen. Das ist nützlich, heißt aber auch, dass du verstehen solltest, welche Kanäle, Tools oder Auth-Modi wirklich live sind.

Exec-Provider wie lockere Shell-Hacks behandeln

Exec-Provider sind mächtig, weil sie OpenClaw mit externen Secret-Systemen verbinden. Genau deshalb gehören sie zu deiner Trust Boundary. Halte den Command-Pfad explizit, die Env-Allowlist kurz und den Resolver langweilig.

Wann einfach völlig reicht

Nicht jedes Setup braucht am ersten Tag Vault. Ein Solo-Builder auf einem privaten Host ist oft schon mit Umgebungsvariablen plus SecretRefs für die wichtigsten unterstützten Felder gut bedient.

Komplexität ist nicht das Ziel. Saubere Kontrolle ist das Ziel. Starte mit dem kleinsten Secret-System, das noch den Test besteht: "Wäre ich genervt, diesen Leak später erklären zu müssen?"

Die Kurzfassung

Lege echte Credentials nicht unnötig als zufälligen Klartext in Config-Dateien ab
Nutze SecretRefs als Verweise auf env-, file- oder exec-gestützte Secret-Quellen
Lass Audit und Apply die Aufräumarbeit machen, statt blind per Hand zu editieren
Vertraue atomischen Reloads mehr als improvisierten Secret-Swaps
Halte Exec-Provider streng, langweilig und eng begrenzt

Secrets Management ist nicht glamourös. Gut so. Die besten Sicherheitsgewohnheiten sind oft genau die, die unspektakulär werden.

Need help from people who already use this stuff?

Du räumst deine OpenClaw-Secrets auf?

Bring dein Setup in die Community und vergleiche Secret-Workflows, bevor eine chaotische Migration in einem kaputten Deploy endet.

Join My AI Agent Profit Lab See the community page

FAQ

Muss ich sofort jedes Secret auf SecretRefs umstellen?

Nein. Klartext funktioniert weiterhin. SecretRefs sind optional. Sinnvoll ist, zuerst die wichtigen Zugangsdaten zu migrieren, danach Audit erneut laufen zu lassen und keine große riskante Aufräumaktion in einem Rutsch zu erzwingen.

Was ist der Unterschied zwischen ${ENV_VAR} und einem SecretRef?

${ENV_VAR} ist String-Substitution in Konfigurationswerten. SecretRefs sind strukturierte Secret-Objekte, die beim Aktivieren aufgelöst werden und dem eigenen Secrets-Workflow folgen. Beides kann aus Umgebungsvariablen lesen, aber SecretRefs geben dir den saubereren Operator-Pfad für Audits, Provider und Reloads.

Zerlegt ein kaputter Secret-Provider den Agenten mitten im normalen Nachrichtenbetrieb?

Nicht, wenn das Gateway bereits einen last-known-good Runtime-Snapshot hat. OpenClaw löst Secrets früh beim Aktivieren auf und tauscht nur bei vollständigem Erfolg. So bleiben Provider-Ausfälle vom laufenden Request-Pfad fern.

Wann nutze ich env-, file- oder exec-Provider?

Env passt zu einfachen Deployments und typischen Service-Managern. File passt, wenn du bereits eine sauber abgesicherte Secrets-Datei pflegst. Exec passt, wenn 1Password, Vault oder ein anderes Secret-System die eigentliche Quelle der Wahrheit bleiben soll.