Secrets-Apply-Plan-Vertrag

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

Wenn ein Ziel diese Regeln nicht erfüllt, schlägt Apply fehl, bevor die Konfiguration verändert wird.

Plan-Dateiformat

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 Credential-Pfade akzeptiert in:

SecretRef Credential Surface

Zieltyp-Verhalten

Allgemeine Regel:

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

Kompatibilitäts-Aliase werden für bestehende Pläne weiterhin akzeptiert:

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

Pfad-Validierungsregeln

Jedes Ziel wird wie folgt validiert:

type muss ein erkannter Zieltyp sein.
path muss ein nicht-leerer Punkt-Pfad sein.
pathSegments kann weggelassen werden. Falls angegeben, muss es auf exakt denselben Pfad wie path normalisiert werden.
Verbotene Segmente werden abgelehnt: __proto__, prototype, constructor.
Der normalisierte Pfad muss zur registrierten Pfadform für den Zieltyp passen.
Wenn providerId oder accountId gesetzt ist, muss es mit der im Pfad codierten ID übereinstimmen.
auth-profiles.json-Ziele erfordern agentId.
Beim Erstellen eines neuen auth-profiles.json-Mappings authProfileProvider angeben.

Fehlerverhalten

Wenn ein Ziel die Validierung nicht besteht, beendet sich Apply mit einem Fehler wie:

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

Bei einem ungültigen Plan werden keine Schreibvorgänge durchgeführt.

Runtime- und Audit-Scope-Hinweise

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

Operator-Prüfungen

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

# Dann tatsächlich anwenden
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

Wenn Apply mit einer ungültigen Zielpfad-Meldung fehlschlägt, generiere den Plan mit openclaw secrets configure neu oder korrigiere den Zielpfad auf eine unterstützte Form.