Verwaltung von Secrets

OpenClaw unterstützt additive SecretRefs, damit unterstützte Anmeldedaten nicht als Klartext in der Konfiguration gespeichert werden müssen.

# Ziele und Laufzeitmodell

Secrets werden in einen In-Memory-Laufzeit-Snapshot aufgelöst.

• Die Auflösung erfolgt während der Aktivierung eager, nicht lazy auf Anfragepfaden.
• Der Start schlägt schnell fehl, wenn eine effektiv aktive SecretRef nicht aufgelöst werden kann.
• Reload verwendet atomaren Austausch: vollständiger Erfolg oder Beibehaltung des zuletzt als gut bekannten Snapshots.
• SecretRef-Richtlinienverstöße (zum Beispiel OAuth-Modus-Auth-Profile in Kombination mit SecretRef-Eingaben) lassen die Aktivierung vor dem Laufzeitaustausch fehlschlagen.
• Laufzeitanfragen lesen nur aus dem aktiven In-Memory-Snapshot.
• Nach der ersten erfolgreichen Konfigurationsaktivierung bzw. dem ersten erfolgreichen Laden lesen Laufzeit-Codepfade weiterhin diesen aktiven In-Memory-Snapshot, bis ein erfolgreicher Reload ihn austauscht.
• Ausgehende Zustellungspfade lesen ebenfalls aus diesem aktiven Snapshot (zum Beispiel Discord-Antwort-/Thread-Zustellung und Telegram-Aktionssendungen); sie lösen SecretRefs nicht bei jedem Senden erneut auf.

Dadurch bleiben Ausfälle von Secret-Providern von heißen Anfragepfaden fern.

# Filterung aktiver Oberflächen

SecretRefs werden nur auf effektiv aktiven Oberflächen validiert.

• Aktivierte Oberflächen: nicht aufgelöste Refs blockieren Start/Reload.
• Inaktive Oberflächen: nicht aufgelöste Refs blockieren Start/Reload nicht.
• Inaktive Refs geben nicht-fatale Diagnosen mit dem Code SECRETS_REF_IGNORED_INACTIVE_SURFACE aus.

# Gateway-Auth-Oberflächendiagnosen

Wenn eine SecretRef für gateway.auth.token, gateway.auth.password, gateway.remote.token oder gateway.remote.password konfiguriert ist, protokolliert Gateway-Start/Reload den Oberflächenstatus explizit:

• active: Die SecretRef ist Teil der effektiven Auth-Oberfläche und muss aufgelöst werden.
• inactive: Die SecretRef wird für diese Laufzeit ignoriert, weil eine andere Auth-Oberfläche gewinnt oder weil Remote-Auth deaktiviert/nicht aktiv ist.

Diese Einträge werden mit SECRETS_GATEWAY_AUTH_SURFACE protokolliert und enthalten den Grund, den die Richtlinie für aktive Oberflächen verwendet, sodass Sie sehen können, warum ein Anmeldedatum als aktiv oder inaktiv behandelt wurde.

# Onboarding-Referenz-Preflight

Wenn Onboarding im interaktiven Modus läuft und Sie SecretRef-Speicherung wählen, führt OpenClaw vor dem Speichern eine Preflight-Validierung aus:

• Env-Refs: validiert den Env-Variablennamen und bestätigt, dass während der Einrichtung ein nicht leerer Wert sichtbar ist.
• Provider-Refs (file oder exec): validiert die Provider-Auswahl, löst id auf und prüft den Typ des aufgelösten Werts.
• Quickstart-Wiederverwendungspfad: Wenn gateway.auth.token bereits eine SecretRef ist, löst Onboarding sie vor Probe-/Dashboard-Bootstrap auf (für env-, file- und exec-Refs) und verwendet dabei dasselbe Fail-Fast-Gate.

Wenn die Validierung fehlschlägt, zeigt Onboarding den Fehler an und lässt Sie erneut versuchen.

# SecretRef-Vertrag

Verwenden Sie überall dieselbe Objektform:

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

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

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

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

# Provider-Konfiguration

Definieren Sie Provider unter secrets.providers:

{
  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,
    },
  },
}

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

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

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

# Exec-Integrationsbeispiele

{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        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" },
      },
    },
  },
}

{
  secrets: {
    providers: {
      vault_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/vault",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        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" },
      },
    },
  },
}

{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/sops",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        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" },
      },
    },
  },
}

# MCP-Server-Umgebungsvariablen

MCP-Server-Env-Variablen, die über plugins.entries.acpx.config.mcpServers konfiguriert werden, unterstützen SecretInput. Dadurch bleiben API-Schlüssel und Tokens aus der Klartextkonfiguration heraus:

{
  plugins: {
    entries: {
      acpx: {
        enabled: true,
        config: {
          mcpServers: {
            github: {
              command: "npx",
              args: ["-y", "@modelcontextprotocol/server-github"],
              env: {
                GITHUB_PERSONAL_ACCESS_TOKEN: {
                  source: "env",
                  provider: "default",
                  id: "MCP_GITHUB_PAT",
                },
              },
            },
          },
        },
      },
    },
  },
}

Klartext-Stringwerte funktionieren weiterhin. Env-Template-Refs wie ${MCP_SERVER_API_KEY} und SecretRef-Objekte werden während der Gateway-Aktivierung aufgelöst, bevor der MCP-Server-Prozess gestartet wird. Wie bei anderen SecretRef-Oberflächen blockieren nicht aufgelöste Refs die Aktivierung nur, wenn das acpx-Plugin effektiv aktiv ist.

# Sandbox-SSH-Auth-Material

Das Core-ssh-Sandbox-Backend unterstützt ebenfalls SecretRefs für SSH-Auth-Material:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        ssh: {
          target: "user@gateway-host:22",
          identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
      },
    },
  },
}

Laufzeitverhalten:

• OpenClaw löst diese Refs während der Sandbox-Aktivierung auf, nicht verzögert bei jedem SSH-Aufruf.
• Aufgelöste Werte werden mit restriktiven Berechtigungen in temporäre Dateien geschrieben und in der generierten SSH-Konfiguration verwendet.
• Wenn das effektive Sandbox-Backend nicht ssh ist, bleiben diese Refs inaktiv und blockieren den Start nicht.

# Unterstützte Anmeldeinformations-Oberfläche

Kanonisch unterstützte und nicht unterstützte Anmeldeinformationen sind aufgeführt in:

• SecretRef-Anmeldeinformations-Oberfläche

# Erforderliches Verhalten und Vorrang

• Feld ohne Ref: unverändert.
• Feld mit Ref: auf aktiven Oberflächen während der Aktivierung erforderlich.
• Wenn sowohl Klartext als auch Ref vorhanden sind, hat Ref auf unterstützten Vorrangspfaden Vorrang.
• Der Schwärzungs-Sentinel __OPENCLAW_REDACTED__ ist für interne Konfigurationsschwärzung/-wiederherstellung reserviert und wird als wörtlich übermittelte Konfigurationsdaten abgelehnt.

Warn- und Audit-Signale:

• SECRETS_REF_OVERRIDES_PLAINTEXT (Laufzeitwarnung)
• REF_SHADOWED (Audit-Befund, wenn Anmeldeinformationen aus auth-profiles.json Vorrang vor Refs aus openclaw.json haben)

Kompatibilitätsverhalten für Google Chat:

• serviceAccountRef hat Vorrang vor Klartext-serviceAccount.
• Der Klartextwert wird ignoriert, wenn eine benachbarte Ref gesetzt ist.

# Aktivierungsauslöser

Secret-Aktivierung läuft bei:

• Start (Preflight plus finale Aktivierung)
• Hot-Apply-Pfad zum Neuladen der Konfiguration
• Restart-Check-Pfad zum Neuladen der Konfiguration
• Manuellem Neuladen über secrets.reload
• Gateway-Konfigurationsschreib-RPC-Preflight (config.set / config.apply / config.patch) für die Auflösbarkeit von SecretRefs auf aktiven Oberflächen innerhalb der übermittelten Konfigurationsnutzlast vor dem Persistieren von Änderungen

Aktivierungsvertrag:

• Erfolg tauscht den Snapshot atomar aus.
• Ein Startfehler bricht den Gateway-Start ab.
• Ein Laufzeit-Neuladefehler behält den letzten als funktionierend bekannten Snapshot.
• Ein Write-RPC-Preflight-Fehler lehnt die übermittelte Konfiguration ab und lässt sowohl die Konfiguration auf der Festplatte als auch den aktiven Laufzeit-Snapshot unverändert.
• Das Bereitstellen eines expliziten kanalbezogenen Tokens pro Aufruf für einen ausgehenden Helper-/Tool-Aufruf löst keine SecretRef-Aktivierung aus; Aktivierungspunkte bleiben Start, Neuladen und explizites secrets.reload.

# Signale für eingeschränkten und wiederhergestellten Zustand

Wenn die Aktivierung beim Neuladen nach einem fehlerfreien Zustand fehlschlägt, wechselt OpenClaw in einen eingeschränkten Secrets-Zustand.

Einmalige Systemereignis- und Protokollcodes:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Verhalten:

• Eingeschränkt: Die Laufzeit behält den letzten als funktionierend bekannten Snapshot.
• Wiederhergestellt: Wird einmal nach der nächsten erfolgreichen Aktivierung ausgegeben.
• Wiederholte Fehler, während der Zustand bereits eingeschränkt ist, protokollieren Warnungen, erzeugen aber keine Ereignisflut.
• Start-Fail-Fast gibt keine Ereignisse für eingeschränkten Zustand aus, weil die Laufzeit nie aktiv wurde.

# Auflösung von Befehlspfaden

Befehlspfade können sich über Gateway-Snapshot-RPC für die unterstützte SecretRef-Auflösung anmelden.

Es gibt zwei allgemeine Verhaltensweisen:

Weitere Hinweise:

• Die Snapshot-Aktualisierung nach Secret-Rotation im Backend wird von openclaw secrets reload behandelt.
• Von diesen Befehlspfaden verwendete Gateway-RPC-Methode: secrets.resolve.

# Audit- und Konfigurationsworkflow

Standardablauf für Betreiber:

openclaw secrets audit --check

openclaw secrets configure

openclaw secrets audit --check

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

# Einweg-Sicherheitsrichtlinie

Sicherheitsmodell:

• Preflight muss vor dem Schreibmodus erfolgreich sein
• Laufzeitaktivierung wird vor dem Commit validiert
• Apply aktualisiert Dateien mit atomarem Dateiaustausch und Best-Effort-Wiederherstellung bei Fehlern

# Legacy-Auth-Kompatibilitätshinweise

Für statische Anmeldeinformationen hängt die Laufzeit nicht mehr von Legacy-Auth-Speicherung im Klartext ab.

• Quelle für Laufzeit-Anmeldeinformationen ist der aufgelöste In-Memory-Snapshot.
• Statische Legacy-api_key-Einträge werden bereinigt, wenn sie entdeckt werden.
• OAuth-bezogenes Kompatibilitätsverhalten bleibt getrennt.

# Hinweis zur Web-UI

Einige SecretInput-Unions lassen sich im Roh-Editor-Modus einfacher konfigurieren als im Formularmodus.

# Verwandte Themen

• Authentifizierung — Auth-Einrichtung
• CLI: Secrets — CLI-Befehle
• Umgebungsvariablen — Umgebungsvorrang
• SecretRef-Anmeldeinformations-Oberfläche — Anmeldeinformations-Oberfläche
• Secrets-Apply-Planvertrag — Planvertragsdetails
• Sicherheit — Sicherheitslage