English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

CLI commands

Секрети

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.

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

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.

Пов’язане:

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

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

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).
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 і, за потреби, застосуйте їх:

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.
  • Перед 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, згенерованого раніше:

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, правила валідації та семантика помилок):

Що може оновити 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 у разі помилки.

Приклад

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

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

Пов’язане