Zum Hauptinhalt springen

​
Vault-SecretRefs

Das gebündelte Vault-Plugin ermöglicht OpenClaw, exec-SecretRefs beim Start des Gateways und beim Neuladen aus HashiCorp Vault aufzulösen. OpenClaw speichert Vault-Referenzen in der Konfiguration, hält aufgelöste Werte im In-Memory- Snapshot der Secrets und schreibt die aufgelösten API-Schlüssel nicht zurück in openclaw.json. Verwenden Sie dies, wenn Sie Vault bereits betreiben oder die Schlüssel für Modell-Provider außerhalb der OpenClaw-Konfigurationsdateien speichern möchten. Informationen zum Laufzeitmodell für SecretRefs finden Sie unter Secrets-Verwaltung.

​
Bevor Sie beginnen

Sie benötigen:
  • OpenClaw mit verfügbarem gebündeltem vault-Plugin
  • einen erreichbaren Vault-Server
  • eine Vault-Authentifizierung, die ein Client-Token mit Lesezugriff auf die Secret-Pfade erzeugen kann, die OpenClaw auflösen soll
  • die Umgebung, die den Gateway startet, muss VAULT_ADDR und entweder VAULT_TOKEN, OPENCLAW_VAULT_AUTH_METHOD=token_file mit VAULT_TOKEN_FILE oder eine konfigurierte JWT-/Kubernetes-Anmeldung enthalten
Der Resolver kommuniziert von Node aus über HTTP mit Vault. Der Gateway benötigt die Vault-CLI nicht, um SecretRefs aufzulösen. Aktivieren Sie das gebündelte Plugin, bevor Sie die openclaw vault-Befehle ausführen:

​
Einen Provider-Schlüssel in Vault speichern

OpenClaw verwendet standardmäßig KV v2, das unter secret eingehängt ist, wie in den Beispielen für den Vault-Entwicklungsserver. Legen Sie für eine Produktivumgebung von Vault OPENCLAW_VAULT_KV_MOUNT auf Ihren tatsächlichen KV-Einhängepfad fest, bevor Sie SecretRef-IDs erstellen. Mit den Standardeinstellungen von OpenClaw liest diese SecretRef-ID:
dieses Vault-Feld:
Eine Möglichkeit, es mit der Vault-CLI zu erstellen, ist:
Verwenden Sie für OpenClaw ein auf den erforderlichen Umfang beschränktes Client-Token und kein Root-Token. Für das standardmäßige KV-v2-Layout sieht eine minimale Richtlinie für Schlüssel von Modell-Providern wie folgt aus:

​
Vault für den Gateway zugänglich machen

Exportieren Sie für einen lokalen Gateway ohne Container die Vault-Einstellungen in derselben Shell, in der OpenClaw gestartet wird. Die standardmäßige Authentifizierungsmethode liest ein Vault-Client-Token aus VAULT_TOKEN:
Wenn Vault Agent eine Token-Sink-Datei schreibt, verwenden Sie die Token-Datei-Authentifizierung:
Installieren Sie für einen Vault-Server, der von einer privaten CA signiert ist, entweder diese CA im Vertrauensspeicher des Hosts und aktivieren Sie den Systemvertrauensspeicher von Node:
Oder stellen Sie direkt ein PEM-Bundle bereit:
Diese Variablen müssen beim Start von OpenClaw vorhanden sein. Das Vault-Plugin leitet sie an seinen Resolver-Prozess weiter. Verwenden Sie für die nicht interaktive JWT-Authentifizierung eine Workload-JWT-Datei und eine Vault-Rolle vom Typ jwt:
Die JWT-Datei sollte ein projiziertes Workload-Token sein, beispielsweise ein Kubernetes-Service-Account-Token mit einer Zielgruppe, die von der Vault-Rolle akzeptiert wird. Die interaktive OIDC-Anmeldung im Browser ist für Menschen nützlich, die Gateway-Laufzeit benötigt jedoch eine nicht interaktive JWT-Anmeldung oder eine Token-Datei. Verwenden Sie für die Kubernetes-Authentifizierungsmethode von Vault kubernetes. Diese ist für Gateways vorgesehen, die als Pods ausgeführt werden; der standardmäßige Einhängepunkt ist kubernetes, und die standardmäßige JWT-Datei befindet sich unter dem üblichen Pfad für Service-Account-Token:
Legen Sie OPENCLAW_VAULT_AUTH_MOUNT nur fest, wenn die Kubernetes-Authentifizierung in Vault an einer anderen Stelle als auth/kubernetes eingehängt ist. Legen Sie OPENCLAW_VAULT_JWT_FILE nur fest, wenn das Service-Account-Token unter einem benutzerdefinierten Pfad projiziert wird. Optionale Einstellungen:
Prüfen Sie, was für die aktuelle Shell sichtbar ist:
Wenn mehr als ein Vault-gestützter Secret-Provider konfiguriert ist, wählen Sie einen anhand seines Alias aus:
openclaw vault status gibt VAULT_TOKEN niemals aus; der Befehl meldet lediglich, ob das Token, die Token-Datei und die JWT-Datei festgelegt sind.
Wenn der Gateway als Dienst, LaunchAgent, systemd-Unit, geplante Aufgabe oder Container ausgeführt wird, muss diese Laufzeitumgebung dieselben Vault-Variablen erhalten. Das Festlegen von Variablen in einer interaktiven Shell weist nur deren Verfügbarkeit in dieser Shell nach, nicht im bereits ausgeführten Gateway.

​
SecretRef-Plan erstellen und anwenden

Erstellen Sie einen Plan, der den API-Schlüssel des Modell-Providers OpenRouter Vault zuordnet:
Wenden Sie den Plan an und überprüfen Sie ihn:
Verwenden Sie --allow-exec, da das Vault-Plugin die Auflösung über einen von OpenClaw verwalteten exec-SecretRef-Provider durchführt. Wenn der Gateway noch nicht ausgeführt wird, starten Sie ihn nach dem Anwenden des Plans wie gewohnt, anstatt openclaw secrets reload auszuführen.

​
Weitere Provider-Schlüssel konfigurieren

Integrierte Kurzformen:
Mehrere Provider-Schlüssel in einem Plan:
Verwenden Sie für gebündelte Provider ohne Kurzformen oder bereits konfigurierte OpenAI-kompatible und benutzerdefinierte Modell-Provider --provider-key:
Jede Angabe von --provider-key <provider=id> schreibt eine SecretRef nach models.providers.<provider>.apiKey. Bei benutzerdefinierten Providern werden dadurch die Einstellungen baseUrl, api oder models des Providers nicht erstellt; konfigurieren Sie diese zuerst. Verwenden Sie --target <path=id> für jeden bekannten SecretRef-Zielpfad:
Reine Zielpfade gelten für openclaw.json. Verwenden Sie auth-profiles:<agentId>:<path> für vorhandene Ziele in auth-profiles.json. Der Zielpfad muss ein registriertes OpenClaw-SecretRef-Ziel sein. Der Einrichtungsbefehl erstellt keine beliebig benannten Geheimnisse in OpenClaw; Vault bleibt der Geheimnisspeicher, und OpenClaw speichert SecretRefs nur in unterstützten Konfigurationsfeldern.

​
Format der SecretRef-ID

Vault-SecretRef-IDs verwenden diese Konvention:
Beispiele: Das zurückgegebene Vault-Feld muss eine Zeichenfolge sein. Legen Sie für KV v1 Folgendes fest:
Dann liest providers/openrouter/apiKey Folgendes:

​
Was OpenClaw speichert

Beim Anwenden eines Vault-Einrichtungsplans wird ein vom Plugin verwalteter Provider gespeichert:
Anmeldedatenfelder verweisen auf diesen Provider:
Der aufgelöste Wert ist nur im aktiven Laufzeit-Snapshot der Geheimnisse enthalten.

​
Container und verwaltete Bereitstellungen

Containerisierte Gateways verwenden weiterhin dieselbe Plugin- und SecretRef-Konfiguration. Der Container muss Folgendes erhalten:
  • VAULT_ADDR
  • eine Authentifizierungsquelle:
    • VAULT_TOKEN
    • OPENCLAW_VAULT_AUTH_METHOD=token_file zusammen mit VAULT_TOKEN_FILE
    • OPENCLAW_VAULT_AUTH_METHOD=jwt zusammen mit OPENCLAW_VAULT_AUTH_MOUNT, OPENCLAW_VAULT_AUTH_ROLE und OPENCLAW_VAULT_JWT_FILE
    • OPENCLAW_VAULT_AUTH_METHOD=kubernetes zusammen mit OPENCLAW_VAULT_AUTH_ROLE; optional können OPENCLAW_VAULT_AUTH_MOUNT oder OPENCLAW_VAULT_JWT_FILE überschrieben werden
  • optional VAULT_NAMESPACE, OPENCLAW_VAULT_KV_MOUNT und OPENCLAW_VAULT_KV_VERSION
Bevorzugen Sie bei der Verwendung von Kubernetes OPENCLAW_VAULT_AUTH_METHOD=kubernetes, wenn in Vault die Kubernetes-Authentifizierung für den Cluster konfiguriert ist. Verwenden Sie OPENCLAW_VAULT_AUTH_METHOD=jwt nur, wenn Vault so konfiguriert ist, dass der Cluster als generischer JWT-/OIDC-Aussteller behandelt wird. Beide Optionen sind besser als ein langlebiges Vault- Token in einem Kubernetes-Secret. Bereitstellungen mit Vault-Agent-Sidecar oder -Injector können stattdessen token_file verwenden. Behalten Sie bei mandantenfähigen Vault-Konfigurationen die Mandantenweiterleitung in der Vault-Richtlinie und der Bereitstellungskonfiguration bei. OpenClaw erfordert keinen festen Mount, keine feste Rolle und keinen festen Pfad: Jede Gateway-Umgebung kann eigene Werte für OPENCLAW_VAULT_KV_MOUNT, OPENCLAW_VAULT_AUTH_ROLE und eigene SecretRef-IDs festlegen. Wenn ein gemeinsam genutzter Gateway gleichzeitig Geheimnisse für verschiedene Vault-Benutzer auflösen muss, verwenden Sie manuell konfigurierte exec-Provider, die unterschiedliche Authentifizierungsumgebungen kapseln, oder verteilen Sie die Mandanten auf Gateway- Umgebungen mit separaten Vault-Umgebungsvariablen.

​
Verwandte Themen