Команды CLI

secrets

Используйте openclaw secrets для управления SecretRefs и поддержания работоспособности активного снимка среды выполнения. Роли команд:

  • reload: RPC-вызов шлюза (secrets.reload), который повторно разрешает ссылки и заменяет снимок среды выполнения только при полном успехе (без записи конфигурации).
  • audit: сканирование только для чтения хранилищ конфигурации, аутентификации, сгенерированных моделей и устаревших остатков на наличие открытого текста, неразрешенных ссылок и смещения приоритетов.
  • configure: интерактивный планировщик для настройки провайдера, сопоставления целей и предварительной проверки (требуется TTY).
  • apply: выполнение сохраненного плана (--dry-run только для проверки) с последующей очисткой целевых остатков открытого текста.

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

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

Примечание о кодах выхода для CI/ворот:

  • audit --check возвращает 1 при обнаружении проблем.
  • неразрешенные ссылки возвращают 2.

Связанные материалы:

Перезагрузка снимка среды выполнения

Повторно разрешите ссылки на секреты и атомарно замените снимок среды выполнения.

openclaw secrets reload
openclaw secrets reload --json

Примечания:

  • Использует RPC-метод шлюза secrets.reload.
  • Если разрешение не удалось, шлюз сохраняет последний известный исправный снимок и возвращает ошибку (без частичной активации).
  • JSON-ответ включает warningCount.

Аудит

Сканирование состояния OpenClaw на наличие:

  • хранения секретов в открытом тексте
  • неразрешенных ссылок
  • смещения приоритетов (учетные данные auth-profiles.json, перекрывающие ссылки openclaw.json)
  • остатков в сгенерированных agents/*/agent/models.json (значения apiKey провайдера и конфиденциальные заголовки провайдера)
  • устаревших остатков (записи устаревшего хранилища аутентификации, напоминания OAuth)

Примечание об остатках заголовков:

  • Обнаружение конфиденциальных заголовков провайдера основано на эвристике имен (распространенные имена и фрагменты заголовков аутентификации/учетных данных, такие как authorization, x-api-key, token, secret, password и credential).
openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json

Поведение при выходе:

  • --check завершается с ненулевым кодом при обнаружении проблем.
  • неразрешенные ссылки завершаются с кодом ненулевого приоритета.

Основные моменты структуры отчета:

  • status: clean | findings | unresolved
  • summary: plaintextCount, unresolvedRefCount, shadowedRefCount, legacyResidueCount
  • коды обнаружений:
    • PLAINTEXT_FOUND
    • REF_UNRESOLVED
    • REF_SHADOWED
    • LEGACY_RESIDUE

Настройка (интерактивный помощник)

Интерактивное создание изменений провайдера и SecretRef, выполнение предварительной проверки и опциональное применение:

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

Поток:

  • Сначала настройка провайдера (add/edit/remove для псевдонимов secrets.providers).
  • Затем сопоставление учетных данных (выбор полей и назначение ссылок {source, provider, id}).
  • В конце предварительная проверка и опциональное применение.

Флаги:

  • --providers-only: настроить только secrets.providers, пропустить сопоставление учетных данных.
  • --skip-provider-setup: пропустить настройку провайдера и сопоставить учетные данные с существующими провайдерами.
  • --agent <id>: ограничить обнаружение целей и запись в хранилище auth-profiles.json одним агентом.

Примечания:

  • Требуется интерактивный TTY.
  • Нельзя комбинировать --providers-only с --skip-provider-setup.
  • configure нацелен на поля, содержащие секреты, в openclaw.json, а также на auth-profiles.json для выбранной области агента.
  • configure поддерживает создание новых сопоставлений auth-profiles.json непосредственно в процессе выбора.
  • Каноническая поддерживаемая область: Область учетных данных SecretRef.
  • Выполняет предварительное разрешение перед применением.
  • Сгенерированные планы по умолчанию включают параметры очистки (scrubEnv, scrubAuthProfilesForProviderTargets, scrubLegacyAuthJson все включены).
  • Путь применения является односторонним для очищенных значений открытого текста.
  • Без --apply CLI все равно запросит Apply this plan now? после предварительной проверки.
  • С --apply (и без --yes) CLI запрашивает дополнительное необратимое подтверждение.

Примечание по безопасности провайдера exec:

  • Установки Homebrew часто предоставляют символические ссылки на бинарные файлы в /opt/homebrew/bin/*.
  • Устанавливайте allowSymlinkCommand: true только при необходимости для доверенных путей менеджера пакетов и сочетайте это с trustedDirs (например, ["/opt/homebrew"]).
  • В Windows, если проверка ACL недоступна для пути провайдера, OpenClaw завершается с ошибкой. Только для доверенных путей установите allowInsecurePath: true для этого провайдера, чтобы обойти проверки безопасности пути.

Применение сохраненного плана

Примените или выполните предварительную проверку плана, созданного ранее:

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json

Детали контракта плана (разрешенные пути целей, правила валидации и семантика сбоев):

Что apply может обновить:

  • openclaw.json (цели SecretRef + добавление/удаление провайдеров)
  • auth-profiles.json (очистка целей провайдера)
  • устаревшие остатки auth.json
  • известные ключи секретов ~/.openclaw/.env, чьи значения были перенесены

Почему нет резервных копий для отката

secrets apply намеренно не создает резервные копии для отката, содержащие старые значения открытого текста. Безопасность обеспечивается строгой предварительной проверкой + атомарным применением с восстановлением в памяти при сбое по возможности.

Пример

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

Если audit --check все еще сообщает о находках открытого текста, обновите оставшиеся указанные пути целей и повторно запустите аудит.

Песочница CLIбезопасность