Przejdź do głównej treści

​
Kontrakt planu secrets apply

Ta strona definiuje ścisły kontrakt egzekwowany przez openclaw secrets apply. Jeśli cel nie spełnia tych reguł, apply kończy się błędem przed wprowadzeniem zmian w konfiguracji.

​
Kształt pliku planu

openclaw secrets apply --from <plan.json> oczekuje tablicy targets zawierającej cele 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" },
    },
  ],
}

​
Obsługiwany zakres celów

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

​
Zachowanie typu celu

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

​
Reguły walidacji ścieżki

Każdy cel jest walidowany według wszystkich poniższych zasad:
  • type musi być rozpoznawanym typem celu.
  • path musi być niepustą ścieżką rozdzielaną kropkami.
  • pathSegments można pominąć. Jeśli jest podane, musi normalizować się dokładnie do tej samej ścieżki co path.
  • Niedozwolone segmenty są odrzucane: __proto__, prototype, constructor.
  • Znormalizowana ścieżka musi odpowiadać zarejestrowanemu kształtowi ścieżki dla typu celu.
  • Jeśli ustawiono providerId lub accountId, musi odpowiadać identyfikatorowi zakodowanemu w ścieżce.
  • Cele auth-profiles.json wymagają agentId.
  • Przy tworzeniu nowego mapowania auth-profiles.json uwzględnij authProfileProvider.

​
Zachowanie w przypadku błędu

Jeśli cel nie przejdzie walidacji, apply kończy działanie błędem podobnym do: 
Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl
Dla nieprawidłowego planu żadne zapisy nie są zatwierdzane.

​
Zachowanie zgody dla dostawcy exec

  • --dry-run domyślnie pomija sprawdzenia exec SecretRef.
  • Plany zawierające exec SecretRef/provider są odrzucane w trybie zapisu, chyba że ustawiono --allow-exec.
  • Podczas walidacji/stosowania planów zawierających exec przekazuj --allow-exec zarówno w dry-run, jak i w poleceniu zapisu.

​
Uwagi dotyczące runtime i zakresu audytu

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

​
Sprawdzenia operatora

# Zweryfikuj plan bez zapisu
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

# Następnie zastosuj go naprawdę
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

# Dla planów zawierających exec jawnie wyraź zgodę w obu trybach
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 kończy się błędem z komunikatem o nieprawidłowej ścieżce celu, wygeneruj plan ponownie za pomocą openclaw secrets configure albo popraw ścieżkę celu do jednego z obsługiwanych kształtów podanych powyżej.

​
Powiązana dokumentacja