English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Gateway

Vertrag für Secrets-apply-Pläne

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

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

Struktur der Plan-Datei

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

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

Unterstützter Zielbereich

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

Verhalten des Zieltyps

Allgemeine Regel:

  • target.type muss erkannt werden und mit der normalisierten Form von target.path übereinstimmen.

Kompatibilitätsaliase bleiben für bestehende Pläne weiterhin akzeptiert:

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

Regeln zur Pfadvalidierung

Jedes Ziel wird mit allen folgenden Regeln validiert:

  • type muss ein erkannter Zieltyp sein.
  • path muss ein nicht leerer Punktpfad sein.
  • pathSegments kann weggelassen werden. Wenn angegeben, muss es sich zu genau demselben Pfad wie path normalisieren.
  • Verbotene Segmente werden abgelehnt: __proto__, prototype, constructor.
  • Der normalisierte Pfad muss mit der registrierten Pfadform für den Zieltyp übereinstimmen.
  • Wenn providerId oder accountId gesetzt ist, muss es mit der im Pfad kodierten ID übereinstimmen.
  • Ziele für auth-profiles.json erfordern agentId.
  • Wenn eine neue Zuordnung in auth-profiles.json erstellt wird, muss authProfileProvider enthalten sein.

Fehlerverhalten

Wenn ein Ziel die Validierung nicht besteht, beendet apply den Vorgang mit einem Fehler wie:

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

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

Verhalten bei Zustimmung für Exec-Anbieter

  • --dry-run überspringt standardmäßig Exec-SecretRef-Prüfungen.
  • Pläne mit Exec-SecretRefs/-Anbietern werden im Schreibmodus abgelehnt, sofern --allow-exec nicht gesetzt ist.
  • Wenn Pläne mit Exec-Inhalt validiert/angewendet werden, übergeben Sie --allow-exec sowohl bei Dry-Run- als auch bei Schreibbefehlen.

Hinweise zu Laufzeit- und Audit-Bereich

  • Rein referenzielle Einträge in auth-profiles.json (keyRef/tokenRef) sind in der Laufzeitauflösung und im Audit-Bereich enthalten.
  • secrets apply schreibt unterstützte Ziele in openclaw.json, unterstützte Ziele in auth-profiles.json und optionale Scrub-Ziele.

Operator-Prüfungen

# Plan ohne Schreibvorgänge validieren
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

# Dann wirklich anwenden
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

# Für Pläne mit Exec-Inhalt in beiden Modi explizit aktivieren
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw 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.

Verwandte Dokumente