Secrets und API-Keys sicher verwalten – mit OpenClaw SecretRef

In vielen Agenten-Projekten stehen API-Keys, Bot-Tokens oder OAuth-Secrets im Klartext in der Konfiguration. Das schafft unnötige Angriffsflächen für Sicherheitslücken und unbeabsichtigte Leaks. Der SecretRef-Mechanismus von OpenClaw löst dieses Problem, indem er sensible Daten aus der Konfigurationsdatei herauszieht und sicher verwaltet. Dieser Artikel zeigt, wie SecretRef funktioniert und wie sich die Methode in die Praxis umsetzen lässt.

Was ist SecretRef?

SecretRef ist eine Funktion in OpenClaw, die es ermöglicht, Secrets wie API-Keys oder Passwörter nicht als Klartext in der openclaw.json zu speichern. Stattdessen wird eine strukturierte Referenz hinterlegt, die erst zur Laufzeit aufgelöst wird. Sensible Werte bleiben so strikt von der eigentlichen Konfiguration getrennt.

Ein einfaches Beispiel: Statt den Key direkt einzutragen:

{
  models: {
    providers: {
      openrouter: {
        apiKey: "sk-1234567890abcdef",
      },
    },
  },
}

verweist die Konfiguration auf einen SecretRef:

{
  models: {
    providers: {
      openrouter: {
        apiKey: { source: "env", provider: "default", id: "OPENROUTER_API_KEY" },
      },
    },
  },
}

Laut OpenClaw-Dokumentation ist die kanonische Form für einen SecretRef ein Objekt mit den Feldern source, provider und id. Plaintext bleibt weiterhin erlaubt, der Einsatz von SecretRefs ist pro Credential optional.

Die technische Funktionsweise

OpenClaw wählt bei der Verarbeitung von Secrets einen deterministischen Ansatz. Die Referenzen werden bereits beim Aktivieren der Konfiguration aufgelöst (Eager Resolution). Fehlen Secrets oder sind sie ungültig, bricht der Start oder Reload ab, bevor externe Requests ausgeführt werden.

Nach der erfolgreichen Auflösung landen alle Werte in einem konsistenten In-Memory-Snapshot. Bei einer Änderung der Konfiguration – etwa durch einen Reload – baut das System zunächst einen neuen Snapshot vollständig auf. Erst wenn dieser Prozess fehlerfrei durchläuft, wird das alte Abbild atomar ausgetauscht (Atomic Swap). Das schützt die laufenden Request-Pfade vor temporären Ausfällen externer Secret-Provider.

Zusätzlich greift ein Aktiv-Flächen-Filter: Das System validiert nur die Secrets, die für aktuell aktivierte Channels, Accounts oder Features zwingend benötigt werden. Sobald die Konfiguration läuft, lesen alle OpenClaw-Komponenten ausschließlich aus dem In-Memory-Snapshot. Ein Ausfall des Secret-Managers während des Betriebs hat somit keine direkten Auswirkungen auf die Laufzeit.

Aktive und inaktive Referenzen

OpenClaw unterscheidet dynamisch, ob eine Referenz tatsächlich benötigt wird. Inaktive Flächen blockieren den Start nicht, sondern erzeugen lediglich eine Diagnose-Meldung (SECRETS_REF_IGNORED_INACTIVE_SURFACE). Das ist besonders praktisch, um umfangreiche Konfigurationen mit vielen optionalen Secrets vorzuhalten, ohne dass alle Werte sofort präsent sein müssen.

Zu diesen inaktiven Flächen gehören beispielsweise deaktivierte Channel- oder Account-Einträge sowie Top-Level-Credentials, die von keinem aktiven Account geerbt werden. Auch deaktivierte Tools oder Features fallen in diese Kategorie.

Ein weiteres Beispiel sind Web-Search-Provider-Keys, die nicht aktiv ausgewählt wurden. Laut OpenClaw-Dokumentation wird im Auto-Mode der erste funktionierende Provider verwendet; die Keys aller anderen bleiben inaktiv. Ähnliches gilt für SSH-Auth-Material in Sandboxes: Solange keine Sandbox-SSH-Sessions laufen, bleiben die zugehörigen Secrets inaktiv und müssen nicht zwingend beim Start aufgelöst werden.

Drei Wege zur Speicherung von Secrets

SecretRef unterstützt mehrere Backends, die sich je nach Projektgröße und Sicherheitsbedarf flexibel einsetzen lassen.

Env-Provider

Die unkomplizierteste Variante ist der Env-Provider. OpenClaw validiert dabei den Namen und die Auflösbarkeit des Environment-Keys direkt beim Aktivieren der Konfiguration. Fehlende oder leere Werte führen zu einem sofortigen Abbruch (Fail-Fast).

{
  models: {
    providers: {
      openrouter: {
        apiKey: { source: "env", provider: "default", id: "OPENROUTER_API_KEY" },
      },
    },
  },
}

File-Provider

Alternativ lassen sich Secrets in einer separaten Datei verwalten. Laut Dokumentation wird der Provider unter secrets.providers definiert. Anschließend verweist ein absoluter JSON-Pointer auf den entsprechenden Wert in einer JSON-Datei.

{
  secrets: {
    providers: {
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json",
      },
    },
  },
  models: {
    providers: {
      openrouter: {
        apiKey: { source: "file", provider: "filemain", id: "/providers/openrouter/apiKey" },
      },
    },
  },
}

Exec-Provider für externe Secret-Manager

Für professionelle Setups mit Tools wie 1Password, Vault oder SOPS bietet sich der Exec-Provider an. Der Resolver läuft hierbei als konfigurierter Prozess und liefert die Secret-Werte strukturiert an OpenClaw zurück.

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

Dieser Ansatz ist ideal für Produktionsumgebungen, in denen Secrets zentral und außerhalb von Umgebungsvariablen oder lokalen Dateien verwaltet werden sollen.

Fallstricke in der Praxis

Plaintext in der Konfiguration

Es mag verlockend sein, Keys für schnelle Tests im Klartext zu belassen. Ein versehentliches Commit, ein Log-Leak oder ein ungesichertes Backup reichen jedoch aus, um diese Daten zu kompromittieren. Die konsequente Nutzung von SecretRef trennt Konfiguration und Geheimnisse sauber voneinander und minimiert dieses Risiko deutlich.

Inaktive Features und Diagnose-Meldungen

Bei Konfigurationen mit vielen optionalen Komponenten fehlen oft SecretRefs für deaktivierte Channels oder Tools. Das ist architektonisch unproblematisch, da der Startvorgang nicht blockiert wird. Es lohnt sich jedoch, die Diagnose-Meldungen im Blick zu behalten. So lassen sich fehlende Keys rechtzeitig ergänzen, bevor ein Feature später aktiviert wird und der Reload fehlschlägt.

Regelmäßige Rotation

Die Auslagerung der Secrets erleichtert die regelmäßige Rotation. Da die Referenzen in der Konfiguration stabil bleiben, muss lediglich der Wert im Secret-Manager oder in der Datei ausgetauscht werden. Ein anschließender Reload der Konfiguration reicht aus, um die neuen Keys über den Atomic-Swap ohne Downtime systemweit bereitzustellen.

SSH-Auth-Material

Sandbox-SSH-Sessions nutzen eigene Secrets für Identitäten, Zertifikate und Known-Hosts. Werden diese Sessions benötigt, müssen die entsprechenden SecretRefs zwingend vorhanden sein. Eine kurze Prüfung vor der Aktivierung der Sandbox-Features stellt sicher, dass die Sessions reibungslos starten.

Fazit

Die Trennung von Konfiguration und sensiblen Daten ist eine wichtige architektonische Grundlage für sichere Agenten-Projekte. Für kleinere Setups genügen Env-Referenzen oder ein File-Provider, während Teams in Produktionsumgebungen von Exec-Providern und externen Secret-Managern profitieren.

Die konsequente Nutzung bietet drei zentrale Vorteile:

• Keine Plaintext-Keys in der Versionskontrolle: Das Risiko versehentlicher Leaks sinkt drastisch.
• Unterbrechungsfreie Updates: Rotationen und Änderungen erfolgen durch atomare Swaps ohne Downtime.
• Flexibler Aktiv-Flächen-Filter: Konfigurationen lassen sich testen, ohne dass sofort alle optionalen Secrets bereitstehen müssen.

Der initiale Aufwand für die Einrichtung von SecretRef ist gering, der Gewinn an Stabilität und Sicherheit dafür umso höher. Auch wenn Plaintext-Keys technisch weiterhin unterstützt werden, bildet SecretRef das robustere Fundament für den produktiven Betrieb.