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

Використовуйте `openclaw secrets` для керування SecretRefs і підтримання активного runtime snapshot у справному стані.

Ролі команд:

* `reload`: gateway RPC (`secrets.reload`), який повторно визначає refs і замінює runtime snapshot лише за повного успіху (без запису в конфігурацію).
* `audit`: режим лише читання для сканування configuration/auth/generated-model stores і legacy residues на plaintext, unresolved refs і precedence drift (exec refs пропускаються, якщо не встановлено `--allow-exec`).
* `configure`: інтерактивний planner для налаштування provider, target mapping і preflight (потрібен TTY).
* `apply`: виконує збережений plan (`--dry-run` лише для валідації; dry-run типово пропускає exec checks, а режим запису відхиляє плани, що містять exec, якщо не встановлено `--allow-exec`), а потім очищає цільові plaintext residues.

Рекомендований цикл для оператора:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload
```

Якщо ваш plan містить `exec` SecretRefs/providers, передавайте `--allow-exec` і для dry-run, і для команд `apply` у режимі запису.

Примітка про коди виходу для CI/gates:

* `audit --check` повертає `1` за наявності findings.
* unresolved refs повертають `2`.

Пов’язане:

* Посібник із секретів: [Керування секретами](/uk/gateway/secrets)
* Поверхня облікових даних SecretRef: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface)
* Посібник із безпеки: [Безпека](/uk/gateway/security)

## Перезавантаження runtime snapshot

Повторно визначте посилання на секрети й атомарно замініть runtime snapshot.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw secrets reload
openclaw secrets reload --json
openclaw secrets reload --url ws://127.0.0.1:18789 --token <token>
```

Примітки:

* Використовує метод gateway RPC `secrets.reload`.
* Якщо визначення не вдається, gateway зберігає останній відомий справний snapshot і повертає помилку (без часткової активації).
* Відповідь JSON містить `warningCount`.

Параметри:

* `--url <url>`
* `--token <token>`
* `--timeout <ms>`
* `--json`

## Аудит

Сканує стан OpenClaw на наявність:

* зберігання секретів у plaintext
* unresolved refs
* precedence drift (облікові дані в `auth-profiles.json`, які затіняють refs у `openclaw.json`)
* residues у згенерованому `agents/*/agent/models.json` (значення `apiKey` provider і чутливі заголовки provider)
* legacy residues (записи legacy auth store, нагадування OAuth)

Примітка щодо residues у заголовках:

* Виявлення чутливих заголовків provider базується на евристиці за назвами (поширені назви й фрагменти заголовків авторизації/облікових даних, такі як `authorization`, `x-api-key`, `token`, `secret`, `password` і `credential`).

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json
openclaw secrets audit --allow-exec
```

Поведінка кодів виходу:

* `--check` завершується з ненульовим кодом за наявності findings.
* unresolved refs завершуються з ненульовим кодом вищого пріоритету.

Основні елементи структури звіту:

* `status`: `clean | findings | unresolved`
* `resolution`: `refsChecked`, `skippedExecRefs`, `resolvabilityComplete`
* `summary`: `plaintextCount`, `unresolvedRefCount`, `shadowedRefCount`, `legacyResidueCount`
* коди findings:
  * `PLAINTEXT_FOUND`
  * `REF_UNRESOLVED`
  * `REF_SHADOWED`
  * `LEGACY_RESIDUE`

## Configure (інтерактивний помічник)

Інтерактивно створіть зміни provider і SecretRef, виконайте preflight і, за потреби, застосуйте їх:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json
```

Хід роботи:

* Спочатку налаштування provider (`add/edit/remove` для псевдонімів `secrets.providers`).
* Потім mapping облікових даних (вибір полів і призначення refs `{source, provider, id}`).
* Наприкінці preflight і необов’язкове apply.

Прапорці:

* `--providers-only`: налаштовує лише `secrets.providers`, пропускає mapping облікових даних.
* `--skip-provider-setup`: пропускає налаштування provider і виконує mapping облікових даних до наявних providers.
* `--agent <id>`: обмежує виявлення target і записи в `auth-profiles.json` одним store агента.
* `--allow-exec`: дозволяє перевірки exec SecretRef під час preflight/apply (може виконувати команди provider).

Примітки:

* Потрібен інтерактивний TTY.
* Не можна поєднувати `--providers-only` з `--skip-provider-setup`.
* `configure` націлюється на поля, що містять секрети, у `openclaw.json`, а також на `auth-profiles.json` для вибраного обсягу агента.
* `configure` підтримує створення нових mappings у `auth-profiles.json` безпосередньо в picker flow.
* Канонічна підтримувана поверхня: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface).
* Перед apply виконується preflight resolution.
* Якщо preflight/apply містить exec refs, зберігайте `--allow-exec` увімкненим для обох кроків.
* Згенеровані плани типово вмикають параметри очищення (`scrubEnv`, `scrubAuthProfilesForProviderTargets`, `scrubLegacyAuthJson`).
* Шлях apply є незворотним для очищених значень plaintext.
* Без `--apply` CLI все одно запитує `Apply this plan now?` після preflight.
* З `--apply` (і без `--yes`) CLI додатково запитує незворотне підтвердження.
* `--json` виводить plan + звіт preflight, але команда все одно потребує інтерактивний TTY.

Примітка про безпеку exec provider:

* Інсталяції Homebrew часто надають symlinked binaries у `/opt/homebrew/bin/*`.
* Встановлюйте `allowSymlinkCommand: true` лише за потреби для довірених шляхів package manager і поєднуйте це з `trustedDirs` (наприклад, `["/opt/homebrew"]`).
* У Windows, якщо перевірка ACL недоступна для шляху provider, OpenClaw блокує виконання за принципом fail closed. Лише для довірених шляхів встановлюйте `allowInsecurePath: true` для цього provider, щоб обійти перевірки безпеки шляху.

## Застосування збереженого plan

Застосуйте або виконайте preflight для plan, згенерованого раніше:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json
```

Поведінка exec:

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

Деталі контракту plan (дозволені шляхи target, правила валідації та семантика помилок):

* [Контракт plan для Secrets Apply](/uk/gateway/secrets-plan-contract)

Що може оновити `apply`:

* `openclaw.json` (target-и SecretRef + upsert/delete providers)
* `auth-profiles.json` (очищення provider-target)
* legacy residues в `auth.json`
* відомі ключі секретів у `~/.openclaw/.env`, чиї значення було мігровано

## Чому немає rollback backups

`secrets apply` навмисно не записує rollback backups, що містять старі значення plaintext.

Безпека забезпечується суворим preflight + майже атомарним apply з відновленням у пам’яті за принципом best-effort у разі помилки.

## Приклад

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check
```

Якщо `audit --check` усе ще повідомляє про findings plaintext, оновіть решту вказаних шляхів target і повторно запустіть аудит.

## Пов’язане

* [Довідник CLI](/uk/cli)
* [Керування секретами](/uk/gateway/secrets)