> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kontrakt planu stosowania sekretów

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:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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`.

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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](#exec-provider-consent-behavior):
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:

* [Powierzchnia poświadczeń SecretRef](/pl/reference/secretref-credential-surface)

## 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:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
# 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

* [Zarządzanie sekretami](/pl/gateway/secrets)
* [CLI `secrets`](/pl/cli/secrets)
* [Powierzchnia poświadczeń SecretRef](/pl/reference/secretref-credential-surface)
* [Informacje o konfiguracji](/pl/gateway/configuration-reference)