Gateway

Vertrag für den Anwendungsplan von Geheimnissen

Diese Seite definiert den strikten Vertrag, der von openclaw secrets apply erzwungen wird.

Wenn ein Ziel nicht diesen Regeln entspricht, schlägt apply fehl, bevor die Konfiguration verändert wird.

Plan-Dateiform

openclaw secrets apply --from <plan.json> erwartet ein targets-Array mit Plan-Zielen:

json5

{  version: 1,  protocolVersion: 1,  targets: [    {      type: "models.providers.apiKey",      path: "models.providers.openai.apiKey",      pathSegments: ["models", "providers", "openai", "apiKey"],      providerId: "openai",      ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },    },    {      type: "auth-profiles.api_key.key",      path: "profiles.openai:default.key",      pathSegments: ["profiles", "openai:default", "key"],      agentId: "main",      ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },    },  ],}

Provider-Upserts und -Löschungen

Pläne können außerdem zwei optionale Felder auf oberster Ebene enthalten, die die secrets.providers-Map zusätzlich zu den Schreibvorgängen pro Ziel verändern:

providerUpserts — ein Objekt, das nach Provider-Alias verschlüsselt ist. Jeder Wert ist eine Provider-Definition (dieselbe Form, die unter secrets.providers.<alias> in openclaw.json akzeptiert wird, z. B. ein exec- oder file- Provider).
providerDeletes — ein Array von Provider-Aliassen, die entfernt werden sollen.

providerUpserts wird vor targets ausgeführt, sodass ein target.ref.provider auf einen Provider-Alias verweisen kann, den derselbe Plan in providerUpserts einführt. Ohne dies schlagen Pläne, die auf einen noch nicht in openclaw.json konfigurierten Alias verweisen, mit provider "<alias>" is not configured fehl.

json5

{  version: 1,  protocolVersion: 1,  providerUpserts: {    onepassword_anthropic: {      source: "exec",      command: "/usr/bin/op",      args: ["read", "op://Vault/Anthropic/credential"],    },  },  providerDeletes: ["legacy_unused_alias"],  targets: [    {      type: "models.providers.apiKey",      path: "models.providers.anthropic.apiKey",      pathSegments: ["models", "providers", "anthropic", "apiKey"],      providerId: "anthropic",      ref: { source: "exec", provider: "onepassword_anthropic", id: "credential" },    },  ],}

Exec-Provider, die über providerUpserts eingeführt werden, unterliegen weiterhin den Exec-Zustimmungsregeln in Zustimmungsverhalten für Exec-Provider: Pläne mit Exec-Providern erfordern im Schreibmodus --allow-exec.

Unterstützter Zielbereich

Plan-Ziele werden für unterstützte Anmeldeinformationspfade akzeptiert in:

SecretRef-Oberfläche für Anmeldeinformationen

Verhalten des Zieltyps

Allgemeine Regel:

target.type muss erkannt werden und der normalisierten Form von target.path entsprechen.

Kompatibilitäts-Aliasse bleiben für bestehende Pläne akzeptiert:

models.providers.apiKey
skills.entries.apiKey
channels.googlechat.serviceAccount

Regeln zur Pfadvalidierung

Jedes Ziel wird anhand aller folgenden Regeln validiert:

type muss ein erkannter Zieltyp sein.
path muss ein nicht leerer Punktpfad sein.
pathSegments kann weggelassen werden. Wenn es angegeben wird, muss es exakt auf denselben Pfad wie path normalisieren.
Verbotene Segmente werden abgelehnt: __proto__, prototype, constructor.
Der normalisierte Pfad muss der registrierten Pfadform für den Zieltyp entsprechen.
Wenn providerId oder accountId gesetzt ist, muss es mit der im Pfad kodierten ID übereinstimmen.
auth-profiles.json-Ziele erfordern agentId.
Beim Erstellen einer neuen auth-profiles.json-Zuordnung muss authProfileProvider enthalten sein.

Fehlerverhalten

Wenn die Validierung eines Ziels fehlschlägt, beendet apply mit einem Fehler wie:

text

Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl

Für einen ungültigen Plan werden keine Schreibvorgänge übernommen.

Zustimmungsverhalten für Exec-Provider

--dry-run überspringt Exec-SecretRef-Prüfungen standardmäßig.
Pläne mit Exec-SecretRefs/Providern werden im Schreibmodus abgelehnt, sofern --allow-exec nicht gesetzt ist.
Beim Validieren/Anwenden von Plänen mit Exec-Inhalten übergeben Sie --allow-exec sowohl in Dry-Run- als auch in Schreibbefehlen.

Hinweise zu Laufzeit- und Audit-Umfang

Nur-Ref-Einträge in auth-profiles.json (keyRef/tokenRef) sind in der Laufzeitauflösung und Audit-Abdeckung enthalten.
secrets apply schreibt unterstützte openclaw.json-Ziele, unterstützte auth-profiles.json-Ziele und optionale Bereinigungsziele.

Operator-Prüfungen

bash

# Validate plan without writesopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run # Then apply for realopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json # For exec-containing plans, opt in explicitly in both modesopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec

Wenn apply mit einer Meldung zu einem ungültigen Zielpfad fehlschlägt, generieren Sie den Plan mit openclaw secrets configure neu oder korrigieren Sie den Zielpfad auf eine oben unterstützte Form.