OpenClaw SecretRef richtig einsetzen: Secrets, Rotationen und typische Fehlerbilder

Wenn ein API-Key direkt in openclaw.json steht, kann er auch in Config-Diffs, Backups oder Dateien landen, die ein Agent lesen darf. SecretRef trennt den Credential-Wert von der OpenClaw-Konfiguration: Im unterstützten Config-Feld steht nur eine Referenz, während der Wert aus einer Environment-Variable, einer separaten Datei oder einem externen Resolver kommt.

Diese Trennung verkleinert die lokale Leak-Fläche, ersetzt aber keinen sicheren Secret-Speicher. Eine frei lesbare Secret-Datei oder eine ungeeignet bereitgestellte Environment-Variable bleibt unsicher, auch wenn openclaw.json selbst sauber aussieht. Falls dir Aufbau und Speicherort der Hauptkonfiguration noch unklar sind, erklärt Teil 1 der Praxis-Serie die Gateway-Konfiguration mit openclaw.json und JSON5.

Voraussetzungen

Für die folgenden Schritte brauchst du:

• eine bestehende OpenClaw-Installation mit openclaw config set, openclaw config validate und openclaw secrets audit,
• Zugriff auf die aktive Konfiguration; openclaw config file zeigt ihren Pfad,
• ein Credential auf der offiziell unterstützten SecretRef-Oberfläche,
• Kenntnis darüber, wie der Gateway tatsächlich gestartet wird und woher dieser Prozess sein Environment erhält,
• für Server, Container oder Dienste Zugriff auf den zuständigen Prozessmanager beziehungsweise die Deployment-Konfiguration.

Prüfe die verfügbaren Befehle bei Bedarf mit:

openclaw config set --help
openclaw config validate --help
openclaw secrets audit --help

Wenn OPENCLAW_NIX_MODE=1 aktiv ist, verweigert OpenClaw schreibende Config-Befehle. Ändere in diesem Fall die Nix-Quelle der Installation statt openclaw config set zu verwenden. Lesende Befehle wie openclaw config file und openclaw config validate bleiben verfügbar.

So ist eine SecretRef aufgebaut

Eine SecretRef besteht aus source, provider und id:

• source benennt die Quellenart, etwa env, file oder exec.
• provider verweist auf den zuständigen Secret-Provider.
• id wählt den konkreten Wert innerhalb dieser Quelle aus.

Ein direkt eingetragener Modellprovider-Key sieht beispielsweise so aus:

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

Mit einer Env-Referenz enthält die Konfiguration stattdessen nur noch:

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

Plaintext-Credentials funktionieren weiterhin. SecretRefs sind pro unterstütztem Credential optional. Entscheidend ist außerdem der Zielpfad: models.providers.*.apiKey und channels.discord.token gehören zur unterstützten Oberfläche. Nicht jedes Feld, das wie ein Credential aussieht, akzeptiert automatisch eine SecretRef. Die offizielle Seite zur SecretRef-Credential-Surface ist dafür die verbindliche Liste.

Vor der Änderung: Laufzeitumgebung klären

Der häufigste Env-Fehler entsteht außerhalb von OpenClaw. Ein Befehl wie

export DISCORD_BOT_TOKEN="..."

setzt die Variable nur für die aktuelle Shell und von dort neu gestartete Kindprozesse. Er verändert das Environment eines bereits laufenden Gateway-Dienstes nicht. Bei einem späteren Dienststart wird die Variable ebenfalls nicht automatisch übernommen.

Kläre deshalb zuerst, wie dein Gateway läuft:

• Bei einem interaktiv gestarteten Gateway muss die Variable in genau der Shell verfügbar sein, aus der du den Prozess startest.
• Bei einem Systemdienst gehört sie in den dafür vorgesehenen Secret- oder Environment-Mechanismus des Prozessmanagers.
• Bei einem Container gehört sie in die Secret- oder Deployment-Konfiguration des Containers.
• In CI gehört sie in den geschützten Secret-Speicher der CI-Plattform, nicht in das Repository.

Verwende keine Kommandozeile, die den echten Wert als Argument enthält, wenn Shell-History, Prozesslisten oder Job-Logs ihn offenlegen könnten.

Env-SecretRef mit der CLI einrichten

Das folgende Beispiel setzt eine Referenz für einen Discord-Bot-Token. Hinterlege DISCORD_BOT_TOKEN vorher im Environment des tatsächlichen Gateway-Prozesses. Die Erzeugung des Bots, die nötigen Intents und die Serverrechte behandelt die separate Anleitung OpenClaw mit Discord verbinden.

Prüfe die geplante Config-Änderung zunächst ohne Schreibzugriff:

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

Der Dry-run prüft die geplante Änderung, schreibt sie aber nicht in openclaw.json. Wenn er erfolgreich ist, wendest du dieselbe Operation ohne --dry-run an:

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

Für einen OpenRouter-Key lautet der unterstützte Zielpfad:

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

Danach folgen getrennte Prüfungen:

openclaw config validate
openclaw secrets audit --check

openclaw config validate validiert die aktuelle Konfiguration gegen das aktive Schema, ohne den Gateway zu starten. Prüfe anschließend die Aktivierung im echten Gateway-Prozess, weil die Schema-Validierung die Erreichbarkeit der Secret-Provider zur Laufzeit nicht testet.

openclaw secrets audit --check prüft Plaintext-Funde, nicht auflösbare Referenzen und Abweichungen durch Credential-Prioritäten. Bei Funden endet der Befehl mit einem von null verschiedenen Exit-Code.

Beachte bei Env-Refs: Wenn du das Audit aus einer Shell ausführst, die andere Variablen als der Gateway-Dienst erhält, kann die CLI eine Referenz anders bewerten als der spätere Gateway-Prozess. Der entscheidende Test bleibt deshalb die Aktivierung in der echten Laufzeitumgebung.

File-Provider einrichten

Ein File-Provider trennt Secrets von der Hauptkonfiguration, sofern die Datei selbst geschützt und für den Gateway-Prozess lesbar ist. Eine JSON-Datei kann zum Beispiel diese Struktur haben:

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

Erzeuge und befülle diese Datei mit dem Secret-Mechanismus deines Zielsystems. Vermeide Befehle, die den Wert in Shell-History oder Logs schreiben. Prüfe anschließend:

• Die Datei liegt außerhalb des Repositorys und anderer agent-lesbarer Arbeitsverzeichnisse.
• Der tatsächliche Gateway-Benutzer ist Eigentümer oder erhält gezielt Leserechte.
• Andere Benutzer erhalten keine Leserechte; auf Unix-Systemen ist 0600 ein typischer Ausgangspunkt.
• Backups, Diagnosewerkzeuge und Editoren erzeugen keine ungeschützten Kopien.

Kontrolliere Eigentümer und Rechte mit den Werkzeugen deines Betriebssystems, beispielsweise unter Unix:

ls -l /etc/openclaw/secrets.json

Der angezeigte Eigentümer muss zum Benutzer passen, unter dem der Gateway läuft. Ein restriktiver Modus allein hilft nicht, wenn die Datei dem falschen Benutzer gehört.

Registriere den Provider zunächst per Dry-run:

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

Wende die geprüfte Änderung anschließend an:

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

Nun setzt du den Credential-Pfad auf den Wert in der JSON-Datei. Im Modus json ist die ID ein absoluter JSON Pointer mit führendem /:

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

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

Die resultierende Struktur entspricht sinngemäß:

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

Für mode: "singleValue" lautet die ID dagegen immer value. Vermische die beiden Regeln nicht: Ein JSON Pointer gehört zum Modus json, nicht zu singleValue.

Schließe die Config-Prüfung wieder mit diesen Befehlen ab:

openclaw config validate
openclaw secrets audit --check

Exec-Provider gezielt einsetzen

Ein Exec-Provider kann externe Secret-Manager oder interne Resolver anbinden. Eine Referenz kann beispielsweise so aussehen:

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

Die sichere Konfiguration hängt vom aufgerufenen Programm und dessen Ausgabeformat ab. Übernimm deshalb keinen unvollständigen Beispielblock in eine produktive Konfiguration. Prüfe in der aktuellen OpenClaw-Dokumentation insbesondere Kommando, Argumente, erlaubte Environment-Variablen, Timeout und Ausgabeformat.

Dry-runs und Audits führen Exec-Resolver standardmäßig nicht einfach aus. --allow-exec erlaubt solche Auflösungsprüfungen ausdrücklich und kann Provider-Kommandos starten. Verwende die Option nur, wenn du das konfigurierte Programm, seine Nebenwirkungen und sein Logging geprüft hast.

Was beim Start und Reload wirklich passiert

OpenClaw löst benötigte SecretRefs bei der Aktivierung in einen In-Memory-Snapshot auf. Requests lesen anschließend aus diesem aktiven Snapshot; der Provider wird nicht bei jeder Anfrage erneut abgefragt.

Ein nicht auflösbares Secret führt dabei nicht in jedem Fall zum vollständigen Startabbruch. Beim Kaltstart kann OpenClaw einen wiederholbaren SecretRef-Fehler für einen bekannten, isolierbaren Nicht-Gateway-Owner auf diesen Owner begrenzen. Der Gateway startet dann, markiert die betroffene Komponente als configured-unavailable und protokolliert eine redigierte Degradationswarnung.

Strenge Fehler brechen die Aktivierung dagegen weiterhin ab. Dazu gehören laut aktueller Dokumentation unter anderem Gateway-Ingress-Authentifizierung, strukturell ungültige Referenzen oder aufgelöste Werte, ausdrücklich fail-closed behandelte Owner und Referenzen ohne zuordenbaren Runtime-Owner.

Beim Reload prüft OpenClaw die zugeordneten Owner einzeln und veröffentlicht danach einen atomaren Snapshot:

• Gesunde Owner erhalten ihre neuen Werte.
• Ein dafür geeigneter fehlgeschlagener Owner darf seinen letzten funktionierenden Wert als stale behalten, wenn Ref-Identitäten, Provider-Definitionen und der vollständige nicht geheime Owner-Vertrag unverändert geblieben sind.
• Ein neuer oder geänderter fehlgeschlagener Owner wird cold und steht nicht mit einem alten Wert zur Verfügung.
• Ein strenger Fehler verwirft den Reload; der zuvor aktive Snapshot bleibt erhalten.

Der Snapshot ist atomar. Die Vorprüfung und die resultierenden Owner-Zustände bleiben differenziert. Die alte Kurzform „entweder alle neuen Secrets oder vollständig der alte Zustand“ bildet dieses Verhalten nicht korrekt ab.

Inaktive SecretRefs richtig einordnen

Nicht jede konfigurierte Credential-Oberfläche ist aktuell wirksam. Ein deaktivierter Channel oder ein nicht ausgewählter Provider kann eine Referenz enthalten, ohne den Start zu blockieren. OpenClaw kann solche Fälle als inaktive Secret-Oberfläche melden.

Eine solche Meldung bestätigt die Funktionsfähigkeit der Referenz noch nicht. Prüfe Provider und ID, bevor du die zugehörige Komponente aktivierst. Andernfalls wird aus dem Wartungshinweis beim nächsten Konfigurationswechsel ein cold-, stale- oder strenger Aktivierungsfehler.

Rotation ohne veralteten Snapshot

Bei einer Rotation bleibt die Referenz gewöhnlich gleich, während sich der Wert im Backend ändert. Damit der Gateway den neuen Wert verwendet, muss eine neue Aktivierung stattfinden.

Gehe in dieser Reihenfolge vor:

1. Hinterlege den neuen Wert sicher im Backend beziehungsweise im Environment des später gestarteten Gateway-Prozesses.
2. Prüfe die Konfiguration mit openclaw config validate.
3. Führe openclaw secrets audit --check in einem geeigneten operativen Kontext aus.
4. Lade oder starte den Gateway kontrolliert über den Mechanismus deiner Installation neu.
5. Prüfe Status und Logs auf redigierte Degradations-, cold-, stale- oder strict-Meldungen.
6. Teste gezielt den betroffenen Channel oder Provider.
7. Widerrufe den alten Key spätestens nach dem geplanten Übergang, sofern der Vorfall nicht ohnehin einen sofortigen Widerruf verlangt.

Es gibt keinen universellen Reload-Befehl für jede Installationsart. Verwende den Prozessmanager, Container-Orchestrator oder Startweg, über den dein Gateway tatsächlich betrieben wird.

Wenn die Integration danach noch den alten oder keinen Wert verwendet, prüfe zuerst:

• Hat der Gateway-Prozess wirklich Zugriff auf den neuen Wert?
• Wurde die Runtime tatsächlich neu aktiviert?
• Ist der Owner stale, cold oder configured-unavailable?
• Wurde versehentlich eine andere aktive Config-Datei bearbeitet?
• Greift eine andere Credential-Quelle mit höherer Priorität?

Diagnoseablauf bei Fehlern

Beginne mit der aktiven Datei und den getrennten Prüfebenen:

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

Die Befehle beantworten unterschiedliche Fragen:

• openclaw config file: Welche Konfigurationsdatei verwendet diese CLI-Umgebung?
• openclaw config validate: Entspricht die aktuelle Konfiguration dem aktiven Schema?
• openclaw secrets audit --check: Gibt es Plaintext-Funde, nicht auflösbare Referenzen oder Credential-Prioritätsabweichungen?

Aktiviere danach den Gateway in seiner echten Dienstumgebung und kontrolliere den Zustand der benötigten Komponenten. Nur dort zeigt sich, ob die Provider erreichbar sind und welcher Owner-Zustand entsteht. Auch ein laufender Gateway kann einen isolierbaren Owner als nicht verfügbar führen; teste deshalb zusätzlich den betroffenen Channel oder Provider.

Ein belastbares Erfolgskriterium besteht aus vier Teilen:

1. Die Konfiguration ist schema-gültig.
2. Das Audit meldet keine ungeklärten Funde.
3. Die Aktivierung erzeugt für die benötigte Komponente keinen unerwarteten cold-, stale-, strict- oder Degradationszustand.
4. Ein gezielter Funktionstest des Channels oder Providers gelingt.

Plaintext-Reste nach der Migration beseitigen

Eine neue SecretRef entfernt keine alten Kopien. Prüfe nach der Migration insbesondere:

• openclaw.json,
• .env-Dateien,
• alte oder archivierte Auth-Profile,
• generierte Dateien unter Agent-Verzeichnissen,
• Git-Verlauf, CI-Artefakte, Logs und Backups.

Wenn ein echter Key bereits in Git, Logs oder einem ungeschützten Artefakt lag, behandle ihn als offengelegt. Ersetze die Config durch eine Referenz und rotiere oder widerrufe den Credential-Wert beim Anbieter.

Grenzen von SecretRef

SecretRef reduziert Klartext in unterstützten OpenClaw-Credential-Feldern. Daraus folgen weder automatische Verschlüsselung noch automatische Rotation. Auch ein kompromittierter OpenClaw-Prozess kann auf Credentials zugreifen, die er für seine Arbeit benötigt.

Prüfe daher zusätzlich:

• Berechtigungen und Verschlüsselung des Secret-Backends,
• Zugriffsregeln des externen Secret-Managers,
• Redaction in Logs und Monitoring,
• Schutz von Backups und temporären Dateien,
• Rotation und Widerruf beim jeweiligen Anbieter.

Kernpunkte

Prüfe vor der Produktivnutzung zuerst die aktive Datei und die statischen Gates:

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

Danach müssen auch die Laufzeitbedingungen stimmen. Das Credential-Feld liegt auf der offiziell unterstützten SecretRef-Oberfläche, und der echte Wert steht nicht mehr als Plaintext in der aktiven OpenClaw-Konfiguration. Der Gateway-Prozess kann den Provider und die angegebene ID auflösen. Secret-Dateien liegen außerhalb des Repositorys und sind für den richtigen Benutzer restriktiv lesbar.

Aktiviere die Runtime nach einer Testrotation neu und teste die Zielintegration. Alte oder offengelegte Keys werden widerrufen. Erst dieses Zusammenspiel aus Backend, Prozessumgebung, Aktivierung und Funktionstest macht die SecretRef-Migration betrieblich belastbar.

SecretRef ist kein vollständiges Secret-Management-System. Es ist die OpenClaw-Schnittstelle, mit der unterstützte Credentials aus der Hauptkonfiguration herausgelöst und kontrolliert in den Runtime-Snapshot übernommen werden.