openclaw doctor: что он проверяет и как читать вывод

Коротко

openclaw doctor — единая точка входа для проверки здоровья и починки: один и тот же реестр правил работает в режиме lint (только чтение) и в режиме fix (правки).
Режим --lint ничего не пишет в конфиг и не чинит. Его ставят в CI и preflight, читают поле ok и массив findings в JSON.
--fix применяет только разрешённые починки. Ключ --only <id> запускает одну конкретную проверку по её идентификатору.

Сверено с документацией OpenClaw 2026.9.8, 7 октября 2026.

Doctor в OpenClaw 2026.9.8 сводит в одну команду проверки Gateway, каналов, плагинов, навыков, маршрутов моделей и локального состояния. Один реестр правил работает в двух режимах: lint только читает и формирует отчёт, fix применяет починки. Команда ниже запускает обычный интерактивный прогон с подсказками.

openclaw doctor

Что именно проверяет doctor

Сводка по областям — на странице /gateway/doctor/checks. Полный список из семи страниц документации — на /cli/doctor. Проверки сгруппированы так.

Здоровье, Control UI и обновления: версия протокола Control UI, состояние навыков и плагинов, схемы инструментов MCP, опциональное обновление для git-установок.
Конфиг и миграции: нормализация устаревших полей, перенос talk.* в talk.provider, миграции Tailscale и OpenAI Codex, конфиги QMD, перенос TOOLS.md в AGENTS.md.
Gateway и сервисы: статус службы, состояние песочницы, миграции устаревших служб, столкновения портов, маршруты Codex, конфиги systemd/launchd/schtasks.
Авторизация и безопасность: открытые DM-политики, локальный токен Gateway, парные устройства, расхождение локального кэша токенов.
Рабочая среда и оболочка: клоны из реестра, systemd linger на Linux, размеры bootstrap-файлов, готовность навыков и эмбеддингов памяти, статус автодополнения.

Блокирующие и информационные находки

У каждой находки в JSON есть поле severity: info, warning или error. На уровне lint порог задаёт ключ --severity-min: warning по умолчанию. Этот же порог определяет код выхода: 0 без находок на уровне порога, 1 при находках, 2 при падении до формирования отчёта. Ниже короткий отчёт lint, который выводит doctor.

doctor --lint: ran 6 check(s), 1 finding(s)
  [warning] core/doctor/gateway-config gateway.mode - gateway.mode is unset; gateway start will be blocked.
    fix: Run `openclaw configure` and set Gateway mode (local/remote), or `openclaw config set gateway.mode local`.

В JSON-отчёте те же поля структурированы для скриптов.

{
  "schemaVersion": 1,
  "ok": false,
  "checksRun": 5,
  "checksSkipped": 0,
  "findings": [
    {
      "checkId": "core/doctor/gateway-config",
      "severity": "warning",
      "message": "gateway.mode is unset; gateway start will be blocked.",
      "path": "gateway.mode",
      "fixHint": "Run `openclaw configure` and set Gateway mode (local/remote), or `openclaw config set gateway.mode local`."
    }
  ]
}

Режимы запуска: что выбрать

openclaw doctor — интерактивный, спрашивает, делает безопасные миграции и подтверждённые починки.
openclaw doctor --json без подсказок и записей отдаёт JSON-отчёт. Выходит с 0, даже если ok: false; скрипты читают ok сами.
openclaw doctor --fix применяет рекомендованные починки без подсказок (--repair как псевдоним).
openclaw doctor --lint без подсказок и записей читает состояние. Используется в CI, preflight и ревью. Без --all пропускает opt-in проверки.

Коды выхода явного --lint: 0 нет находок на уровне порога, 1 есть находки, 2 упало до формирования отчёта. CI должен опираться на ok и findings.

Как читать отчёт и где чинить

В каждой находке есть path или ocPath (путь в конфиге OpenClaw), fixHint (что запустить), иногда requirement и source для точной диагностики. Несколько конкретных случаев из документации.

Служба Gateway: статус проверяется отдельным разделом, починка сервиса подчиняется правилам сохранения службы.
Каналы: состояние читается с живого Gateway; при проблемах с входом смотрите openclaw channels dead-letters list.
SecretRef: при деградации владельцев doctor печатает предупреждение Secret runtime degradation и подсказывает openclaw secrets reload.
MCP-серверы: при сбое подпроцесса doctor сохраняет выводы и добавляет диагностику очистки; перед повторным запуском остановите процессы.
Tailscale: старые HTTPS-маршруты из LAN-bound Gateway doctor не трогает, потому что не может доказать владение; там же выводит команды ручной очистки.

Границы: что doctor не покрывает

Часть проверок вынесена в отдельные команды, а не в doctor.

Логи Gateway: если сессия в кэше расхода не обновилась, doctor скажет об этом, но причину смотрите в логах и через повторный запрос usage.
Конфиг вручную: перед --fix откройте cat ~/.openclaw/openclaw.json и просмотрите изменения.
Сторонние секреты: PLAINTEXT_FOUND, REF_SHADOWED, LEGACY_RESIDUE приходят из openclaw secrets audit, а не из doctor.

Частые ошибки

Запускать doctor --json в CI как интерактивный doctor. Для гейтов нужен явный --lint, иначе выйдет 0 даже при ok: false.
Считать предупреждения lint (warning) всегда проходящими в preflight. На уровне --severity-min warning они уже дают код 1.
Смотреть только хвост stderr от упавшего обновления. Полезные находки лежат в JSON-поле findings отчёта, а не в логе.
Стирать резервные копии, чтобы убрать предупреждение core/doctor/skill-workshop-relocation. Сохранённые корни требуют ручного ревью, а не удаления.
Путать --fix с --fix --force. Второй ключ применяет агрессивные починки и затрагивает конфиг и состояние шире, чем обычный fix.