OpenClaw Secrets Apply: Plan-Vertrag korrekt umsetzen

Secrets zu verwalten kann echt nervig sein. Ein falscher Pfad in der Konfiguration und schon läuft nichts mehr. Damit du beim Ausrollen deiner API-Keys keine bösen Überraschungen erlebst, gibt es einen klaren Contract für deine Pläne.

Diese Seite definiert den strikten Contract, den openclaw secrets apply erzwingt. Wenn ein Ziel nicht diesen Regeln entspricht, bricht der Vorgang ab, bevor die Konfiguration verändert wird.

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

• SecretRef Credential Surface

Verhalten der Zieltypen

Allgemeine Regel:

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

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

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

Validierungsregeln für Pfade

Jedes Ziel wird anhand der folgenden Punkte geprüft:

• type muss ein bekannter Zieltyp sein.
• path muss ein Dot-Pfad sein, der nicht leer ist.
• pathSegments kann weggelassen werden. Falls du es angibst, muss es exakt dem gleichen Pfad wie path entsprechen.
• Verbotene Segmente wie __proto__, prototype oder constructor werden abgelehnt.
• Der normalisierte Pfad muss der registrierten Pfadform für den Zieltyp entsprechen.
• Wenn providerId oder accountId gesetzt ist, muss dies mit der im Pfad kodierten ID übereinstimmen.
• auth-profiles.json Ziele benötigen zwingend eine agentId.
• Wenn du ein neues auth-profiles.json Mapping erstellst, muss authProfileProvider enthalten sein.

Verhalten bei Fehlern

Wenn ein Ziel die Validierung nicht besteht, bricht der Befehl mit einer Fehlermeldung ab:

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

Bei einem ungültigen Plan werden keine Änderungen vorgenommen oder gespeichert.

Hinweise zu Runtime und Audit-Scope

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

Prüfungen für Operator

# Validate plan without writes
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

# Then apply for real
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

Falls der Vorgang mit einer Meldung über einen ungültigen Pfad fehlschlägt, generiere den Plan mit openclaw secrets configure neu oder korrigiere den Pfad auf eine der oben genannten unterstützten Formen.

Verwandte Dokumente

• Secrets Management
• CLI secrets
• SecretRef Credential Surface
• Configuration Reference

Nächste Schritte

• Schau dir das Secrets Management an, um die Grundlagen zu verstehen.
• Erfahre mehr über die CLI secrets Befehle.

AI Setup Assistant