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

# Контракт плану застосування секретів

Ця сторінка визначає строгий контракт, який примусово застосовує `openclaw secrets apply`.

Якщо ціль не відповідає цим правилам, apply завершується помилкою до зміни конфігурації.

## Форма файлу плану

`openclaw secrets apply --from <plan.json>` очікує масив `targets` із цілями плану:

```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" },
    },
  ],
}
```

## Upsert-операції та видалення провайдерів

Плани також можуть містити два необов’язкові поля верхнього рівня, які змінюють мапу
`secrets.providers` разом із записами для окремих цілей:

* `providerUpserts` — об’єкт із ключами за псевдонімами провайдерів. Кожне значення є
  визначенням провайдера (та сама форма, яку приймає
  `secrets.providers.<alias>` в `openclaw.json`, наприклад провайдер `exec` або `file`).
* `providerDeletes` — масив псевдонімів провайдерів для видалення.

`providerUpserts` виконується перед `targets`, тому `target.ref.provider` може
посилатися на псевдонім провайдера, який той самий план вводить у
`providerUpserts`. Без цього плани, що посилаються на псевдонім, ще не
налаштований в `openclaw.json`, завершуються помилкою `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" },
    },
  ],
}
```

Провайдери exec, введені через `providerUpserts`, усе ще підпадають під правила
згоди для exec у [Поведінка згоди для exec-провайдера](#exec-provider-consent-behavior):
плани, що містять exec-провайдери, потребують `--allow-exec` у режимі запису.

## Підтримувана область цілей

Цілі плану приймаються для підтримуваних шляхів облікових даних у:

* [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface)

## Поведінка типів цілей

Загальне правило:

* `target.type` має бути розпізнаним і має відповідати нормалізованій формі `target.path`.

Псевдоніми сумісності залишаються прийнятими для наявних планів:

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

## Правила перевірки шляхів

Кожна ціль перевіряється за всіма наведеними нижче правилами:

* `type` має бути розпізнаним типом цілі.
* `path` має бути непорожнім dot-шляхом.
* `pathSegments` можна не вказувати. Якщо його надано, він має нормалізуватися точно до того самого шляху, що й `path`.
* Заборонені сегменти відхиляються: `__proto__`, `prototype`, `constructor`.
* Нормалізований шлях має відповідати зареєстрованій формі шляху для типу цілі.
* Якщо задано `providerId` або `accountId`, він має відповідати ідентифікатору, закодованому в шляху.
* Цілі `auth-profiles.json` потребують `agentId`.
* Під час створення нового зіставлення `auth-profiles.json` додайте `authProfileProvider`.

## Поведінка в разі помилки

Якщо ціль не проходить перевірку, apply завершується з помилкою на кшталт:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl
```

Для недійсного плану жодні записи не фіксуються.

## Поведінка згоди для exec-провайдера

* `--dry-run` типово пропускає перевірки exec SecretRef.
* Плани, що містять exec SecretRefs/провайдери, відхиляються в режимі запису, якщо не задано `--allow-exec`.
* Під час перевірки або застосування планів, що містять exec, передавайте `--allow-exec` і в dry-run, і в командах запису.

## Примітки щодо області runtime та аудиту

* Записи `auth-profiles.json` лише з посиланнями (`keyRef`/`tokenRef`) включені до runtime-визначення та аудиторського покриття.
* `secrets apply` записує підтримувані цілі `openclaw.json`, підтримувані цілі `auth-profiles.json` і необов’язкові цілі очищення.

## Перевірки оператора

```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
```

Якщо apply завершується помилкою з повідомленням про недійсний шлях цілі, повторно згенеруйте план за допомогою `openclaw secrets configure` або виправте шлях цілі до підтримуваної форми вище.

## Пов’язані документи

* [Керування секретами](/uk/gateway/secrets)
* [CLI `secrets`](/uk/cli/secrets)
* [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface)
* [Довідник конфігурації](/uk/gateway/configuration-reference)