Secrets und API-Keys sicher verwalten – mit OpenClaw SecretRef

In vielen Agenten-Projekten landen API-Keys, Bot-Tokens oder OAuth-Secrets aus Bequemlichkeit direkt in der Konfiguration. Das ist riskant: Ein versehentliches Commit, ein Debug-Log oder ein ungeschütztes Backup reicht aus, um produktive Zugangsdaten offenzulegen.

OpenClaw bietet dafür den SecretRef-Mechanismus. Statt den sensiblen Wert selbst in openclaw.json zu schreiben, speichert die Konfiguration nur eine strukturierte Referenz. Der eigentliche Wert kommt zur Laufzeit aus einem Secret-Backend, zum Beispiel aus einer Environment-Variable oder aus einer separaten Secret-Datei.

Das Thema ergänzt die breitere Sicherheitslogik von OpenClaw: Während Security-Audits und Approval-Hooks riskante Aktionen und Credential-Leaks sichtbarer machen, sorgt SecretRef dafür, dass sensible Werte gar nicht erst dauerhaft in normalen Konfigurationsblöcken landen müssen. Für den laufenden Betrieb passt das auch zu einer sauberen Backup- und Update-Routine, weil Konfiguration und Geheimnisse getrennt behandelt werden können.

Voraussetzungen

Für die Beispiele brauchst du:

eine bestehende OpenClaw-Installation,
Zugriff auf die aktive Konfigurationsdatei (openclaw config file zeigt sie an),
die OpenClaw-CLI mit openclaw config set und openclaw config validate,
ein konkretes Credential, das du aus der Hauptkonfiguration entfernen willst.

Wichtig: SecretRef ist kein Ersatz für einen sicheren Secret-Store. Die Referenz verhindert Plaintext in der Hauptkonfiguration. Das Backend selbst – Environment, Datei, Vault, 1Password, SOPS oder ein anderer Manager – muss weiterhin korrekt abgesichert werden.

Was ist SecretRef?

SecretRef ist eine strukturierte Referenz auf ein Secret. Die kanonische Form besteht laut OpenClaw-Dokumentation aus den Feldern source, provider und id.

Statt einen API-Key direkt einzutragen:

{
  models: {
    providers: {
      openrouter: {
        apiKey: "<YOUR_API_KEY>",
      },
    },
  },
}

verweist die Konfiguration nur noch auf eine Quelle:

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

Plaintext-Werte sind in OpenClaw weiterhin möglich, SecretRefs sind also pro Credential optional. Für produktive Setups ist die Referenzform aber die robustere Wahl, weil sie Konfiguration und Geheimnis trennt.

Sicherer Standardablauf mit der CLI

Am sichersten änderst du Secrets nicht per Hand im Editor, sondern über die OpenClaw-Config-CLI. So kannst du Änderungen vorher prüfen und anschließend validieren.

Beispiel für einen Discord-Bot-Token aus einer Environment-Variable:

export DISCORD_BOT_TOKEN="..."

openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN \
  --dry-run

openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN

openclaw config validate

Das gleiche Muster funktioniert auch für andere Credential-Pfade, sofern der jeweilige Konfigurationspfad in deinem Setup existiert. Beispiel für einen Modellprovider-Key:

export OPENROUTER_API_KEY="..."

openclaw config set models.providers.openrouter.apiKey \
  --ref-provider default \
  --ref-source env \
  --ref-id OPENROUTER_API_KEY \
  --dry-run

openclaw config set models.providers.openrouter.apiKey \
  --ref-provider default \
  --ref-source env \
  --ref-id OPENROUTER_API_KEY

openclaw config validate

Nutze --dry-run konsequent vor Änderungen an produktiven Konfigurationen. openclaw config validate ist danach Pflicht, bevor du einen Reload oder Neustart einplanst.

Wie OpenClaw SecretRefs verarbeitet

OpenClaw trennt zwischen der sichtbaren Konfigurationsstruktur und dem tatsächlichen Credential-Wert. Bei der Aktivierung der Konfiguration werden benötigte SecretRefs aufgelöst und validiert. Fehlt ein notwendiges Secret oder ist es nicht auflösbar, soll die Konfiguration nicht stillschweigend mit einem kaputten Credential weiterlaufen.

Die OpenClaw-Dokumentation beschreibt außerdem eine Credential-Surface-Logik: Nicht jede Referenz ist in jedem Zustand aktiv. Entscheidend ist, ob der zugehörige Channel, Account, Provider oder das Feature tatsächlich verwendet wird. Dadurch können größere Konfigurationen optionale Bereiche enthalten, ohne dass jedes optionale Secret sofort vorhanden sein muss.

Praktisch bedeutet das:

Secrets für aktive Komponenten müssen auflösbar sein.
Secrets für deaktivierte oder nicht genutzte Flächen können als inaktiv behandelt werden.
Diagnosemeldungen zu inaktiven oder ignorierten Referenzen solltest du trotzdem ernst nehmen, weil sie beim späteren Aktivieren eines Features zu echten Start- oder Reload-Fehlern werden können.

Verlasse dich nicht darauf, dass eine inaktive Referenz dauerhaft ungefährlich bleibt. Prüfe sie spätestens, bevor du das zugehörige Feature aktivierst.

Drei Wege zur Speicherung von Secrets

SecretRef ist nur die Referenz. Wo der Wert tatsächlich liegt, hängt vom Backend ab.

1. Env-Provider

Der einfachste Einstieg ist der Env-Provider. Die Konfiguration verweist auf eine Environment-Variable, zum Beispiel OPENROUTER_API_KEY.

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

CLI-Variante:

export OPENROUTER_API_KEY="..."

openclaw config set models.providers.openrouter.apiKey \
  --ref-provider default \
  --ref-source env \
  --ref-id OPENROUTER_API_KEY

openclaw config validate

Achte darauf, dass du Secrets nicht versehentlich in Shell-History, Prozesslisten, CI-Logs oder .env-Dateien eincheckst. Für lokale Tests ist Environment oft ausreichend. Für Teams oder Produktion ist ein zentraler Secret-Manager meist sauberer.

2. File-Provider

Für lokale oder serverseitige Setups kannst du Secrets in einer separaten JSON-Datei halten und diese Datei restriktiv berechtigen.

Beispiel für eine Secret-Datei:

{
  "providers": {
    "openrouter": {
      "apiKey": "..."
    }
  }
}

Lege sie zum Beispiel außerhalb des Projekt-Repositorys ab:

sudo install -m 600 -o "$USER" -g "$USER" /dev/null /etc/openclaw/secrets.json

Dann registrierst du den File-Provider in OpenClaw:

openclaw config set secrets.providers.vaultfile \
  --provider-source file \
  --provider-path /etc/openclaw/secrets.json \
  --provider-mode json

Anschließend verweist das Credential per JSON-Pointer auf den Wert in der Datei:

openclaw config set models.providers.openrouter.apiKey \
  --ref-provider vaultfile \
  --ref-source file \
  --ref-id /providers/openrouter/apiKey

openclaw config validate

Die entsprechende JSON5-Struktur sieht sinngemäß so aus:

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

Verwende hier nach Möglichkeit absolute Pfade. Ob Shell-Kürzel wie ~ an jeder Stelle expandiert werden, solltest du nicht voraussetzen.

3. Exec-Provider für externe Secret-Manager

Für professionelle Setups bietet sich ein Exec-Provider an, der einen externen Secret-Manager anbindet, zum Beispiel Vault, 1Password, SOPS oder ein internes Tool. Die OpenClaw-Konfiguration enthält dann nicht den Wert, sondern eine Referenz auf den konfigurierten Exec-Provider und eine ID innerhalb dieses Providers.

Ein SecretRef kann dann beispielsweise so aussehen:

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

Wichtig: Beim Exec-Provider ist der genaue Provider-Block entscheidend. Definiere Command, Argumente und Ausgabeformat strikt nach der aktuellen OpenClaw-Dokumentation und teste den Resolver separat, bevor du ihn in einer produktiven Gateway-Konfiguration verwendest. Ein Exec-Provider ist nur so sicher wie das aufgerufene Programm, dessen Berechtigungen und dessen Logging.

Typische Fallstricke

Plaintext bleibt im Git-Verlauf

Wenn ein Secret bereits committed wurde, reicht es nicht, es in der aktuellen Datei durch SecretRef zu ersetzen. Der alte Wert kann weiter im Git-Verlauf, in CI-Artefakten, Backups oder Logs liegen.

Sicherer Ablauf:

Secret im Anbieterportal rotieren oder widerrufen.
Plaintext aus der aktuellen Konfiguration entfernen.
SecretRef eintragen.
Repository-Verlauf und Artefakte prüfen, wenn der Leak relevant war.
OpenClaw-Konfiguration validieren und neu laden.

Diagnosemeldungen ignorieren

Inaktive Referenzen blockieren nicht zwingend sofort den Betrieb. Das ist bequem, aber gefährlich, wenn später ein Feature aktiviert wird und das Secret dann fehlt. Behandle Secret-Diagnosen als Wartungsliste: Was heute optional ist, kann morgen produktionskritisch sein.

Rotation ohne Reload

Die Referenz bleibt bei einer Rotation gleich, aber der Wert im Backend ändert sich. Plane deshalb nach einer Rotation einen kontrollierten Reload oder Neustart ein und prüfe danach die betroffenen Integrationen. SecretRef nimmt dir die Rotation nicht ab; es macht sie nur sauberer, weil die Hauptkonfiguration unverändert bleiben kann.

Unsichere Secret-Dateien

Ein File-Provider ist nur dann sinnvoll, wenn die Datei nicht im Repository liegt und restriktive Rechte hat. Für Server-Setups sind typische Mindestanforderungen:

Datei außerhalb des Projektverzeichnisses,
keine Aufnahme in Backups ohne passende Verschlüsselung,
0600 oder vergleichbar restriktive Rechte,
Eigentümer passend zum OpenClaw-Prozess,
keine Ausgabe der Datei in Debug-Logs.

Zu viel Vertrauen in SecretRef

SecretRef reduziert Leak-Flächen in der Konfiguration. Es bedeutet nicht automatisch:

Verschlüsselung der Secret-Datei,
automatische Rotation,
Schutz vor einem kompromittierten OpenClaw-Prozess,
Schutz vor falsch konfigurierten Logs,
Berechtigungsprüfung im externen Secret-Manager.

Diese Punkte musst du separat lösen.

Praktische Checkliste

Vor dem Produktivbetrieb solltest du mindestens prüfen:

openclaw config file
openclaw config validate

Zusätzlich sinnvoll:

Enthält openclaw.json noch Klartext-Keys?
Sind Secret-Dateien außerhalb des Repositories abgelegt?
Sind Dateirechte restriktiv gesetzt?
Funktioniert der Reload nach einer Test-Rotation?
Werden Debug-Logs ohne Secret-Werte geschrieben?
Sind alte Keys nach Migration auf SecretRef rotiert?

Zusammenfassung

SecretRef trennt OpenClaw-Konfiguration und sensible Werte. Für kleine Setups reichen oft Env-Referenzen oder ein File-Provider. Für Teams und Produktion sind externe Secret-Manager über einen sauber getesteten Provider meist die bessere Wahl.

Die wichtigsten Vorteile:

Weniger Plaintext in der Hauptkonfiguration: API-Keys und Tokens müssen nicht in openclaw.json stehen.
Sauberere Rotation: Die Referenz bleibt stabil, während der Wert im Backend ausgetauscht wird.
Bessere Trennung von Backup-Domänen: Konfiguration und Geheimnisse können unterschiedlich gesichert und berechtigt werden.
Prüfbare Aktivierung: openclaw config validate macht fehlende oder falsch referenzierte Secrets früh sichtbar.

Auch wenn Plaintext-Keys technisch weiterhin möglich sind, ist SecretRef für ernsthafte OpenClaw-Setups die deutlich robustere Grundlage.