OpenClaw SecretRef richtig einsetzen: Secrets, Rotationen und typische Fehlerbilder

Wenn OpenClaw plötzlich mit ungültigen Tokens startet, ein Channel nach einer Rotation keine Replies mehr verschickt oder openclaw.json keine Klartext-Secrets mehr enthalten soll, landet man schnell bei SecretRef. Genau dort entstehen in der Praxis die typischen Fehler: ein falscher Provider, eine inaktive Referenz, ein Secret im Git-Verlauf oder ein sauberer Ref auf einen unsicheren Speicherort.

OpenClaw bietet mit SecretRef einen klaren Weg aus dieser Falle. Statt den sensiblen Wert selbst in openclaw.json zu speichern, verweist die Konfiguration nur auf eine strukturierte Referenz. Der eigentliche Wert kommt zur Laufzeit aus einem Secret-Backend, etwa aus einer Environment-Variable, einer separaten Datei oder einem externen Resolver.

Das passt zur Sicherheitslogik von OpenClaw: Produktive Zugangsdaten bleiben aus agent-lesbaren Standarddateien heraus, und Validierung, Audit sowie Runtime-Aktivierung fangen kaputte Konfigurationen möglichst früh ab.

Kurz gesagt: In der normalen Konfiguration steht nur noch, wo OpenClaw einen Key holen soll. Der eigentliche Wert liegt außerhalb der üblichen Konfigurationsblöcke. Das kostet etwas Bequemlichkeit, macht Leaks und Rotationen im Betrieb aber deutlich beherrschbarer.

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, also Environment, Datei, Vault oder ein anderer Manager, muss weiterhin korrekt abgesichert werden.

Ebenfalls wichtig: SecretRefs funktionieren nicht auf beliebigen Config-Feldern. Sie greifen nur auf der offiziell unterstützten Credential-Oberfläche. Wenn du einen nicht unterstützten Pfad per Ref beschicken willst, lehnt OpenClaw das ab.

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.

Die drei Felder lesen sich so:

• source: Art der Quelle, zum Beispiel env, file oder exec.
• provider: welcher konfigurierte Secret-Provider verwendet wird.
• id: welcher konkrete Wert innerhalb dieser Quelle gemeint ist.

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 bleiben also pro Credential optional. Für produktive Setups ist die Referenzform die robustere Wahl, weil sie Konfiguration und Geheimnis trennt.

Welche Fehler SecretRef wirklich verhindert

SecretRef verschiebt Secrets aus lesbaren Konfigurationsblöcken in einen anderen Speicherort. Das verhindert nicht jeden Vorfall, reduziert aber die häufigsten Leaks deutlich:

• API-Keys stehen nicht mehr offen in openclaw.json oder anderen unterstützten Klartextfeldern.
• Generierte Modellkataloge und normale Config-Diffs enthalten weniger produktive Zugangsdaten.
• Ein Reload kann fehlschlagen, bevor ein halbfertiger Zustand live geht.
• Rotationen lassen sich durchführen, ohne an mehreren Stellen neue Klartextwerte einzutragen.

Nicht verschwinden dadurch alle Probleme rund um den Zielspeicher. Wenn ein Secret weiter in .env, Backups oder alten generierten Dateien liegt, bleibt es angreifbar. Genau deshalb gehört zu einer SecretRef-Migration immer auch die Prüfung alter Klartextreste.

Typische Symptome, wenn SecretRefs schiefgehen

SecretRef-Fehler sehen im Betrieb selten dramatisch aus, sind aber gut eingrenzbar. Besonders häufig sind drei Muster:

• Startup oder Reload bricht sofort ab. Das passiert, wenn eine effektiv aktive Referenz nicht aufgelöst werden kann. OpenClaw löst aktive SecretRefs beim Aktivieren der Konfiguration auf und scheitert bewusst früh, statt erst auf dem Request-Pfad.

• Ein Secret ist konfiguriert, wird aber ignoriert. Das betrifft inaktive Oberflächen, etwa deaktivierte Channels, nicht ausgewählte Provider oder andere aktuell nicht wirksame Credential-Surfaces. Solche Fälle blockieren den Start nicht, tauchen aber als Diagnose auf.

• Die Rotation war erfolgreich, der betroffene Channel bleibt trotzdem kaputt. Dann wurde der neue Wert zwar im Backend abgelegt, aber der aktive Runtime-Snapshot wurde nicht erfolgreich neu geladen. OpenClaw liest im Betrieb aus einem aktiven In-Memory-Snapshot, nicht bei jeder Anfrage erneut aus dem Provider.

Diese Unterscheidung ist wichtig: Manche Secret-Probleme sind Konfigurationsfehler, andere Aktivierungsfehler, wieder andere schlicht nicht neu geladene Laufzeitdaten.

Sicherer Standardablauf mit der CLI

Ich würde Secrets in produktiven Setups konsequent über die OpenClaw-Config-CLI ändern. So lassen sich Änderungen vorab 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 unterstützte Credential-Pfade. 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.

Diagnose: Was du zuerst prüfen solltest

Wenn ein SecretRef-Setup nicht sauber läuft, hilft eine feste Reihenfolge mehr als hektisches Editieren:

1. Prüfe, welche Konfigurationsdatei OpenClaw gerade wirklich nutzt.
2. Validiere die Konfiguration vor jedem Reload.
3. Prüfe, ob der Ref auf einer aktiven oder inaktiven Oberfläche liegt.
4. Suche nach alten Klartextresten, bevor du dem Ref selbst misstraust.

Der knappe Minimalpfad dafür ist:

openclaw config file
openclaw config validate
openclaw secrets audit --check

Was du dabei suchst:

• openclaw config file bestätigt, ob du überhaupt die aktive Konfiguration bearbeitest.
• openclaw config validate fängt Syntax- und Auflösungsprobleme vor dem Reload ab.
• openclaw secrets audit --check zeigt, ob zwar schon Ref-Objekte existieren, aber irgendwo weiter Klartextreste in üblichen Secret-Oberflächen liegen.

Gerade der letzte Punkt wird leicht übersehen. Ein Setup kann formal SecretRefs verwenden und trotzdem unsauber bleiben, wenn openclaw.json, auth-profiles.json, .env oder generierte Modell-Dateien alte Werte weitertragen.

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.

Das ist gut für lokale Tests, weil du keine zusätzliche Secret-Datei einrichten musst. Für Teams oder Server wird es schnell unsauber, wenn unklar ist, welche Prozesse die Variable sehen oder welche Logs sie ausgeben.

{
  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 eingecheckten .env-Dateien hinterlässt. 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 absolutem 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" },
      },
    },
  },
}

Wichtig ist der Unterschied zwischen den beiden Modi:

• Bei mode: "json" muss id ein absoluter JSON Pointer mit führendem / sein.
• Bei mode: "singleValue" ist id immer value.

Verwende hier nach Möglichkeit klare, kontrollierte Pfade. Die OpenClaw-Doku zeigt zwar auch ~ in Provider-Beispielen, in produktiven Setups sind explizite Pfade trotzdem meist wartungsärmer.

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#value" }

Wichtig: Beim Exec-Provider ist der genaue Provider-Block entscheidend. Definiere Command, Argumente, Allowlist-Umgebung, Timeouts 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.

Recovery nach Rotation oder Fehlkonfiguration

SecretRef macht Rotationen sauberer, aber nicht automatisch. Wenn ein Key getauscht wurde und die Integration weiter fehlschlägt, geh in dieser Reihenfolge vor:

1. Secret im Backend prüfen oder neu setzen.
2. openclaw config validate erneut ausführen.
3. Den betroffenen Dienst oder die Gateway-Konfiguration kontrolliert neu laden.
4. Erst danach den betroffenen Channel oder Provider testen.

Wichtig ist der Runtime-Mechanismus dahinter: OpenClaw verwendet nach erfolgreicher Aktivierung einen aktiven In-Memory-Snapshot. Bei einem Reload wird dieser Snapshot atomar ersetzt. Entweder der neue Satz Secrets ist vollständig gültig, oder OpenClaw bleibt beim letzten funktionierenden Zustand. Das schützt vor halben Rotationen, erklärt aber auch, warum ein korrekt aktualisiertes Backend allein noch keinen laufenden Dienst sicherstellt.

Wenn du einen produktiven Vorfall aufräumst, hilft deshalb die Reihenfolge:

• kompromittierten Key widerrufen oder rotieren
• Klartextreste beseitigen
• Ref validieren
• Reload durchführen
• Zielintegration testen

Ohne diesen Ablauf bleibt oft unklar, ob der Fehler noch vom alten Leak, von einem defekten Ref oder vom nicht übernommenen Snapshot kommt.

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:

1. Secret im Anbieterportal rotieren oder widerrufen.
2. Plaintext aus der aktuellen Konfiguration entfernen.
3. SecretRef eintragen.
4. Repository-Verlauf und Artefakte prüfen, wenn der Leak relevant war.
5. 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. OpenClaw markiert solche Fälle explizit als inaktive Secret-Oberfläche statt als harten Startfehler. Behandle diese Hinweise 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.

Wenn du mit einem File-Provider arbeitest und trotzdem weiter Leaks befürchtest, ist das oft ein Zeichen dafür, dass der Speicherort selbst zu nah an den agent-lesbaren Dateien liegt. In solchen Fällen ist ein externer Resolver oder ein klar getrennter Secret-Manager meist die bessere Wahl.

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.

Beliebige Config-Felder per SecretRef bestücken wollen

Nicht jedes Feld, das wie ein Secret aussieht, ist automatisch SecretRef-fähig. OpenClaw hat dafür eine offizielle Supported-Surface-Liste. Typische unterstützte Ziele sind etwa channels.discord.token, models.providers.*.apiKey oder bestimmte Gateway- und Plugin-Credentials. Andere Felder, etwa runtime-mutierbare oder OAuth-nahe Oberflächen, sind bewusst ausgenommen.

Faustregel: Wenn du mit openclaw config set --ref-* arbeitest, bleib bei dokumentierten Credential-Pfaden und behandle die SecretRef-Credential-Surface als harte Grenze.

Praktische Checkliste

Vor dem Produktivbetrieb solltest du mindestens prüfen:

openclaw config file
openclaw config validate
openclaw secrets audit --check

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?

Was jetzt zählt

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.
• Klarere Diagnose: Aktive und inaktive Secret-Oberflächen lassen sich besser unterscheiden.
• 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 und openclaw secrets audit --check machen 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.