Przejdź do głównej treści
Ta strona definiuje ścisły kontrakt egzekwowany przez openclaw secrets apply. Jeśli cel nie spełnia tych reguł, apply kończy się niepowodzeniem przed zmodyfikowaniem konfiguracji.

​
Kształt pliku planu

openclaw secrets apply --from <plan.json> oczekuje tablicy targets z celami planu: 
{
  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" },
    },
  ],
}

​
Upserty i usunięcia providerów

Plany mogą także zawierać dwa opcjonalne pola najwyższego poziomu, które modyfikują mapę secrets.providers razem z zapisami dla poszczególnych celów:
  • providerUpserts — obiekt indeksowany aliasem providera. Każda wartość jest definicją providera (ten sam kształt, który jest akceptowany pod secrets.providers.<alias> w openclaw.json, np. provider exec lub file).
  • providerDeletes — tablica aliasów providerów do usunięcia.
providerUpserts uruchamia się przed targets, więc target.ref.provider może odwoływać się do aliasu providera wprowadzanego przez ten sam plan w providerUpserts. Bez tego plany odwołujące się do aliasu, który nie jest jeszcze skonfigurowany w openclaw.json, kończą się błędem provider "<alias>" is not configured. 
{
  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" },
    },
  ],
}
Providery exec wprowadzone przez providerUpserts nadal podlegają regułom zgody na exec w Zachowanie zgody dla providera exec: plany zawierające providery exec wymagają --allow-exec w trybie zapisu.

​
Obsługiwany zakres celów

Cele planu są akceptowane dla obsługiwanych ścieżek poświadczeń w:

​
Zachowanie typów celów

Reguła ogólna:
  • target.type musi być rozpoznany i musi odpowiadać znormalizowanemu kształtowi target.path.
Aliasy zgodności nadal są akceptowane dla istniejących planów:
  • models.providers.apiKey
  • skills.entries.apiKey
  • channels.googlechat.serviceAccount

​
Reguły walidacji ścieżek

Każdy cel jest walidowany według wszystkich poniższych reguł:
  • type musi być rozpoznanym typem celu.
  • path musi być niepustą ścieżką kropkową.
  • pathSegments można pominąć. Jeśli zostanie podane, musi normalizować się dokładnie do tej samej ścieżki co path.
  • Zabronione segmenty są odrzucane: __proto__, prototype, constructor.
  • Znormalizowana ścieżka musi pasować do zarejestrowanego kształtu ścieżki dla typu celu.
  • Jeśli ustawiono providerId lub accountId, musi ono pasować do identyfikatora zakodowanego w ścieżce.
  • Cele auth-profiles.json wymagają agentId.
  • Podczas tworzenia nowego mapowania auth-profiles.json uwzględnij authProfileProvider.

​
Zachowanie przy niepowodzeniu

Jeśli walidacja celu zakończy się niepowodzeniem, apply kończy działanie z błędem takim jak: 
Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl
Dla nieprawidłowego planu nie są zatwierdzane żadne zapisy.

​
Zachowanie zgody dla providera exec

  • --dry-run domyślnie pomija kontrole exec SecretRef.
  • Plany zawierające SecretRef/providery exec są odrzucane w trybie zapisu, chyba że ustawiono --allow-exec.
  • Podczas walidowania/stosowania planów zawierających exec przekaż --allow-exec zarówno w poleceniach dry-run, jak i zapisu.

​
Uwagi dotyczące zakresu runtime i audytu

  • Wpisy auth-profiles.json zawierające tylko referencje (keyRef/tokenRef) są uwzględniane w rozwiązywaniu runtime i pokryciu audytu.
  • secrets apply zapisuje obsługiwane cele openclaw.json, obsługiwane cele auth-profiles.json oraz opcjonalne cele scrub.

​
Kontrole operatora

# 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

# For exec-containing plans, opt in explicitly in both modes
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
Jeśli apply zakończy się niepowodzeniem z komunikatem o nieprawidłowej ścieżce celu, wygeneruj plan ponownie za pomocą openclaw secrets configure albo popraw ścieżkę celu do obsługiwanego kształtu opisanego powyżej.

​
Powiązana dokumentacja