Secrets Management in OpenClaw

Secrets im Klartext in Konfigurationsdateien zu speichern ist riskant. Früher oder später landet ein API-Key versehentlich im Repository oder die Verwaltung von Umgebungsvariablen über verschiedene Umgebungen hinweg wird zum Chaos.

Du willst eine Lösung, die deine Credentials sicher verwaltet, ohne den Workflow zu unterbrechen. OpenClaw nutzt dafür SecretRefs, damit du sensible Daten auslagern kannst und sie nur im Arbeitsspeicher landen.

Voraussetzungen

Eine aktive OpenClaw-Instanz.
Unterstützte Credentials (z. B. für Provider oder das Gateway).

Schnellstart

In OpenClaw kannst du SecretRefs verwenden, um Credentials dynamisch aufzulösen. Das System ist “opt-in”: Plaintext funktioniert weiterhin, aber SecretRefs bieten mehr Sicherheit.

1. Das SecretRef-Format

Alle SecretRefs folgen demselben Schema:

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

2. Beispiele für Quellen

Umgebungsvariablen (env):

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

Dateibasierte Secrets (file): Hier nutzt du einen JSON-Pointer als id.

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

Externe Skripte (exec):

{ source: "exec", provider: "vault", id: "providers/openai/apiKey" }

3. Funktionsweise im Runtime-Modell

OpenClaw löst Secrets beim Start oder Reload sofort auf (“eager resolution”).

Wenn ein aktives Secret nicht aufgelöst werden kann, bricht der Start sofort ab (fail-fast).
Ein Reload nutzt einen “atomic swap”: Entweder alle neuen Secrets werden geladen, oder das System behält den letzten funktionierenden Snapshot.
Anfragen während der Laufzeit lesen nur aus dem In-Memory Snapshot, sodass Ausfälle des Secret-Providers den Traffic nicht blockieren.

Fehlerbehebung

Fehler: Startup/Reload schlägt fehl

Wenn eine SecretRef auf einer aktiven Surface liegt (z. B. ein aktivierter Account), muss sie auflösbar sein. Prüfe die Logs auf SECRETS_GATEWAY_AUTH_SURFACE. Dort siehst du den Status:

active: Das Secret muss geladen werden.
inactive: Das Secret wird ignoriert, da eine andere Auth-Methode Vorrang hat oder die Komponente deaktiviert ist.

Diagnosecode: SECRETS_REF_IGNORED_INACTIVE_SURFACE

Dies ist eine nicht-fatale Diagnose. Sie tritt auf, wenn du eine SecretRef für eine inaktive Surface konfiguriert hast, zum Beispiel:

Ein deaktivierter Channel oder Account.
Provider-Keys, die aktuell nicht über tools.web.search.provider ausgewählt sind.

Onboarding und Validierung

Wenn du das interaktive Onboarding nutzt, führt OpenClaw einen Preflight-Check durch:

Bei env wird geprüft, ob die Variable existiert und nicht leer ist.
Bei file oder exec wird der Provider validiert und der Rückgabetyp geprüft.

Falls die Validierung fehlschlägt, zeigt das Onboarding den Fehler direkt an, damit du ihn korrigieren kannst.

Hast du Fragen zur Einrichtung? Nutze den AI Setup Assistant.

Nächste Schritte

---
title: Provider config
description: So konfigurierst du verschiedene Quellen für deine Secrets in OpenClaw.
---

Secrets manuell zu verwalten ist oft anstrengend. Wenn du zwischen verschiedenen Umgebungen wechselst, verlierst du schnell den Überblick, welcher Key in einer Umgebungsvariable steckt und welcher in einem externen Vault liegt.

Eine zentrale Konfiguration löst dieses Problem. Du definierst einmal, wo deine Daten liegen, und OpenClaw kümmert sich um den Rest. Ich empfehle dir, die Provider-Struktur direkt zu Beginn sauber aufzusetzen, um späteres Refactoring zu vermeiden.

## Voraussetzungen

- Eine Konfigurationsdatei für OpenClaw.
- Zugriff auf deine Umgebungsvariablen oder lokale Secret-Dateien.

## Schnellstart

Definiere deine Provider unter `secrets.providers`. Hier ist ein Beispiel, wie du `env`, `file` und `exec` gleichzeitig konfigurierst:

```json
{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json", // or "singleValue"
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        args: ["--profile", "prod"],
        passEnv: ["PATH", "VAULT_ADDR"],
        jsonOnly: true,
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
    resolution: {
      maxProviderConcurrency: 4,
      maxRefsPerProvider: 512,
      maxBatchBytes: 262144,
    },
  },
}

Env provider

Der env Provider ist der einfachste Weg. Du kannst optional eine allowlist nutzen, um den Zugriff einzuschränken. Wenn Umgebungsvariablen fehlen oder leer sind, schlägt die Resolution fehl.

File provider

Dieser Provider liest lokale Dateien von einem definierten path.

mode: “json”: Erwartet ein JSON-Objekt und nutzt die id als Pointer.
mode: “singleValue”: Erwartet die Ref-ID "value" und gibt den kompletten Dateiinhalt zurück.

Sicherheit ist hier wichtig: Der Pfad muss Ownership- und Permission-Checks bestehen. Falls du auf Windows arbeitest und die ACL-Verifizierung für einen Pfad nicht verfügbar ist, schlägt die Resolution fehl. Für Pfade, denen du vertraust, kannst du allowInsecurePath: true setzen, um die Sicherheitsprüfungen zu umgehen.

Exec provider

Hiermit führst du eine binäre Datei über einen absoluten Pfad aus (ohne Shell).

Standardmäßig muss command auf eine reguläre Datei zeigen, nicht auf einen Symlink.
Mit allowSymlinkCommand: true erlaubst du Symlinks (wichtig für Homebrew shims). OpenClaw validiert den Zielpfad.
Kombiniere allowSymlinkCommand am besten mit trustedDirs (z. B. ["/opt/homebrew"]).

Der Provider unterstützt Timeouts, Output-Limits und eine env Allowlist.

Request Payload (stdin):

{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

Response Payload (stdout):

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "\<openai-api-key\>" } } // pragma: allowlist secret

Falls ein Fehler auftritt, kannst du optionale Fehlermeldungen pro ID zurückgeben:

{
  "protocolVersion": 1,
  "values": {},
  "errors": { "providers/openai/apiKey": { "message": "not found" } }
}

Fehlerbehebung

Fehlende Umgebungsvariablen: Wenn ein Wert im env Provider nicht gesetzt ist, bricht die Resolution ab. Prüfe deine .env oder Shell-Session.
Windows ACL Fehler: Falls die Sicherheitsprüfung fehlschlägt, setze allowInsecurePath: true für diesen spezifischen Provider.
Symlink-Probleme: Wenn dein Command ein Symlink ist, stelle sicher, dass allowSymlinkCommand: true aktiv ist und der Pfad in trustedDirs steht.
Exec Timeout: Falls externe Resolver zu lange brauchen, prüfe die Timeout-Einstellungen in der Config.

Hast du Fragen zur Einrichtung? Nutze den AI Setup Assistant.

Nächste Schritte

Es ist immer das gleiche Problem: API-Keys im Klartext in Konfigurationsdateien zu speichern, ist ein Sicherheitsrisiko. Gleichzeitig ist es extrem nervig, Secrets ständig manuell als Umgebungsvariablen zu setzen oder sie zwischen verschiedenen Tools hin- und herzuschieben, nur um eine Verbindung zur API herzustellen.

Die `exec`-Quelle löst dieses Problem. Du kannst damit Secrets direkt aus den CLI-Tools abrufen, die du ohnehin schon für dein Key-Management nutzt. Das ist der sicherste Weg, um mit sensiblen Daten in deiner Entwicklungsumgebung umzugehen.

## Voraussetzungen

- 1Password CLI, HashiCorp Vault CLI oder `sops`
- Installierte CLI-Binaries (z. B. in `/opt/homebrew/bin`)
- Zugriff auf deine verschlüsselten Secrets oder Vault-Instanzen

## Schnellstart

Du kannst den `exec`-Provider nutzen, um Befehle direkt auszuführen und deren Output als Secret zu verwenden. Hier sind die gängigsten Integrationen.

### 1Password CLI
Wenn du 1Password für deine Secrets nutzt, kannst du den `op` Befehl einbinden. Achte darauf, `HOME` zu übergeben, damit die CLI deine Session findet.

```json
{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true, // Erforderlich für Homebrew Symlinks
        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" },
      },
    },
  },
}

HashiCorp Vault CLI

Für Setups mit HashiCorp Vault nutzt du den vault Befehl. Hier ist es wichtig, die Adresse und den Token über passEnv zu reichen.

{
  secrets: {
    providers: {
      vault_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/vault",
        allowSymlinkCommand: true, // Erforderlich für Homebrew Symlinks
        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" },
      },
    },
  },
}

sops

Falls du deine Secrets mit sops verschlüsselt in Dateien speicherst, kannst du den Wert gezielt extrahieren.

{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/sops",
        allowSymlinkCommand: true, // Erforderlich für Homebrew Symlinks
        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" },
      },
    },
  },
}

Fehlerbehebung

Fehler beim Ausführen der CLI-Binary: Wenn du Tools über Homebrew installiert hast, musst du allowSymlinkCommand: true setzen, da diese oft über Symlinks aufgerufen werden.
Secret wird nicht gefunden: Überprüfe, ob du alle notwendigen Umgebungsvariablen (wie HOME, VAULT_ADDR oder SOPS_AGE_KEY_FILE) in der passEnv Liste eingetragen hast.

Hast du Fragen zur Konfiguration? Nutze den AI Setup Assistant für schnelle Hilfe.

Nächste Schritte

Man kennt das: Man schiebt Credentials im Plaintext in die Config, nur um sie kurz zu testen, und plötzlich landen sie im Repo oder werden zum Sicherheitsrisiko. Wenn dann noch die Rotation der Keys dazukommt, verliert man schnell den Überblick, welche Version gerade aktiv ist und ob das Gateway die Änderungen übernommen hat.

Hier kommt SecretRef ins Spiel. Damit trennst du deine sensiblen Daten sauber von der Konfiguration und nutzt automatisierte Abläufe für die Aktivierung.

Voraussetzungen

Zugriff auf die Dokumentation der SecretRef Credential Surface
Ein laufendes OpenClaw Gateway für die Snapshot-Auflösung

Schnellstart

In 5 Minuten hast du die Grundlagen für SecretRef implementiert:

Ref definieren: Nutze in deiner Konfiguration ein Feld mit einem Ref (z. B. serviceAccountRef) statt des Plaintext-Werts.
Priorität prüfen: Wenn du sowohl Plaintext als auch einen Ref angibst, hat der Ref auf allen unterstützten Pfaden Vorrang.
Gateway starten: Die Aktivierung der Secrets erfolgt automatisch beim Startup. Schlägt dies fehl, bricht der Startvorgang ab (Fail-fast).
Manuell aktualisieren: Nach einer Rotation deiner Secrets im Backend kannst du die neuen Werte mit openclaw secrets reload einspielen.

Funktionsweise und Prioritäten

Wenn du Felder konfigurierst, gelten klare Regeln für die Auflösung. Ein Feld ohne Ref bleibt unverändert. Sobald ein Ref vorhanden ist, wird dieser auf aktiven Surfaces während der Aktivierung zwingend benötigt.

Besonders wichtig ist das Verhalten bei Google Chat:

serviceAccountRef überschreibt den Plaintext serviceAccount.
Der Plaintext-Wert wird komplett ignoriert, wenn ein Geschwister-Ref gesetzt ist.

Warnungen und Audit-Signale

Das System gibt dir direkt Feedback, wenn Prioritäten greifen:

SECRETS_REF_OVERRIDES_PLAINTEXT: Eine Warnung zur Laufzeit, wenn ein Ref den Plaintext ersetzt.
REF_SHADOWED: Ein Audit-Befund, falls Credentials aus der auth-profiles.json Vorrang vor Refs in der openclaw.json haben.

Aktivierung und Status

Die Aktivierung deiner Secrets wird durch vier Ereignisse ausgelöst:

Startup (Preflight und finale Aktivierung)
Config reload (Hot-apply Pfad)
Config reload (Restart-check Pfad)
Manueller Reload via secrets.reload

Ein erfolgreicher Vorgang tauscht den Snapshot atomar aus. Sollte ein Reload im laufenden Betrieb fehlschlagen, behält das System den letzten funktionierenden Zustand (last-known-good snapshot) bei.

Fehlerzustände (Degraded)

Wenn eine Aktivierung nach einem zuvor gesunden Zustand feitlschlägt, wechselt OpenClaw in den Status “degraded”. Du erkennst das an diesen Log-Codes:

SECRETS_RELOADER_DEGRADED
SECRETS_RELOADER_RECOVERED (wird einmalig nach der nächsten erfolgreichen Aktivierung gesendet)

Wichtig: Wiederholte Fehler im “degraded” Zustand loggen zwar Warnungen, spammen aber keine neuen Events.

Auflösung in Command-Paths

Befehlspfade nutzen den Gateway Snapshot RPC (secrets.resolve) für die Auflösung. Hier gibt es zwei Verhaltensweisen:

Strict command paths Diese Pfade lesen aus dem aktiven Snapshot und brechen bei fehlenden SecretRefs sofort ab. Beispiele sind:

openclaw memory (Remote-Memory Pfade)
openclaw qr --remote

Read-only command paths Diese Befehle bevorzugen den aktiven Snapshot, gehen aber bei Fehlern in einen eingeschränkten Modus über, statt abzubrechen. Dazu gehören:

openclaw status und openclaw status --all
openclaw channels status und openclaw channels resolve

Falls das Gateway nicht verfügbar ist, versuchen diese Befehle ein lokales Fallback. Bleibt der Ref unerreichbar, wird die Ausgabe als “degraded” markiert (z. B. „configured but unavailable in this command path“). Dieses Verhalten ist lokal begrenzt und beeinflusst nicht die Sicherheit des laufenden Gateways oder der Auth-Pfade.

Fehlerbehebung

Startup bricht ab: Prüfe, ob alle via SecretRef referenzierten Quellen erreichbar sind. Ein Fail-fast beim Start erzeugt keine “degraded” Events, da das System nie aktiv war.
Veraltete Secrets nach Rotation: Nutze den Befehl openclaw secrets reload, um den Snapshot manuell zu aktualisieren.
Fehlende Werte in Read-only Commands: Wenn die Diagnose „configured but unavailable“ anzeigt, prüfe die Verbindung zum Gateway RPC oder das lokale Fallback.
Eingeschränkte Auflösung: Beachte, dass Runtime-minted Credentials, rotierende Credentials oder OAuth Refresh-Material absichtlich von der Read-only SecretRef Auflösung ausgeschlossen sind.

Du hast Fragen zur Konfiguration oder brauchst Hilfe bei der Integration? Der AI Setup Assistant hilft dir gerne weiter.

Nächste Schritte

Kennst du das? Du arbeitest an deinem Projekt und plötzlich merkst du, dass API-Keys im Klartext in deinen Config-Dateien oder in der .env gelandet sind. Das ist ein Sicherheitsrisiko und wird schnell unübersichtlich, wenn dein Setup wächst. Secrets manuell zu verwalten, macht keinen Spaß und führt oft zu Fehlern.

In diesem Guide zeige ich dir, wie du den Workflow für Secrets in OpenClaw nutzt, um deine Umgebung sauber und sicher zu halten.

Voraussetzungen

OpenClaw CLI
Konfigurationsdateien wie openclaw.json, auth-profiles.json oder .env
Bestehende Agent-Konfigurationen in agents/*/agent/models.json

Schnellstart

Der Standard-Workflow für Operator besteht aus drei einfachen Schritten. So prüfst du dein System und behebst gefundene Probleme direkt:

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

Der Secrets-Workflow im Detail

`secrets audit`

Mit diesem Befehl scannst du deine Umgebung nach Schwachstellen. Das CLI findet für dich:

Klartext-Werte in Dateien wie openclaw.json, auth-profiles.json, .env und den generierten models.json der Agents.
Rückstände von sensiblen Provider-Headern in models.json.
Nicht aufgelöste Referenzen (unresolved refs).
Precedence Shadowing (wenn z. B. auth-profiles.json Priorität gegenüber openclaw.json Referenzen hat).
Alte Rückstände wie auth.json oder OAuth-Erinnerungen.

Hinweis zu Header-Rückständen: Die Erkennung von sensiblen Headern basiert auf Namens-Heuristiken. Das Tool sucht nach typischen Begriffen wie authorization, x-api-key, token, secret, password oder credential.

`secrets configure`

Das ist dein interaktiver Helfer. Er führt dich durch folgende Schritte:

Konfiguration von secrets.providers (env, file oder exec). Du kannst diese hinzufügen, bearbeiten oder entfernen.
Auswahl von Feldern in openclaw.json und auth-profiles.json, die Secrets enthalten.
Erstellung neuer Mappings für auth-profiles.json direkt im Picker.
Erfassung von SecretRef Details wie source, provider und id.
Durchführung einer Preflight-Prüfung vor dem Speichern.

Du kannst den Befehl mit diesen Flags steuern:

openclaw secrets configure --providers-only: Nur die Provider einrichten.
openclaw secrets configure --skip-provider-setup: Die Provider-Einrichtung überspringen.
openclaw secrets configure --agent <id>: Konfiguration auf einen bestimmten Agent einschränken.

Wenn du die Konfiguration anwendest, löscht OpenClaw automatisch statische Credentials aus der auth-profiles.json, alte api_key Einträge aus der auth.json und bekannte Secret-Zeilen aus deiner .env.

`secrets apply`

Wenn du bereits einen fertigen Plan hast, kannst du diesen direkt anwenden:

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

Details zu den Regeln für Ablehnungen findest du im Secrets Apply Plan Contract.

Sicherheit und Legacy-Kompatibilität

OpenClaw verfolgt eine One-way safety policy. Das bedeutet, dass absichtlich keine Rollback-Backups erstellt werden, die historische Klartext-Secrets enthalten könnten.

Der Preflight muss erfolgreich sein, bevor das Tool in den Schreibmodus wechselt.
Die Runtime-Aktivierung wird vor dem Commit validiert.
Dateien werden atomar ersetzt. Bei Fehlern wird ein Best-Effort Restore versucht.

Für alte Setups gilt: Die Runtime ist nicht mehr auf Klartext-Speicher angewiesen. Sobald statische api_key Einträge gefunden werden, bereinigt das System diese. Das Verhalten für OAuth bleibt davon getrennt.

Fehlerbehebung

Falls du Probleme bei der Konfiguration hast, helfen diese Punkte:

Komplexe Konfigurationen: Einige SecretInput Unions lassen sich im Raw Editor Mode der Web UI einfacher konfigurieren als im Form Mode.
Fehlgeschlagene Validierung: Nutze secrets audit, um sicherzustellen, dass keine unresolved refs vorhanden sind, bevor du secrets apply ausführst.

Hast du Fragen zu deinem Setup? Frag den AI Setup Assistant.

Nächste Schritte

OpenClaw Expert

Noch festgefahren?

Wenn diese Seite nicht hilft, frage OpenClaw Expert nach Schritt-fuer-Schritt-Loesungen.