openclaw doctor

Проверки состояния и быстрые исправления для Gateway и каналов.

Связано:

• Устранение неполадок: Устранение неполадок
• Аудит безопасности: Безопасность

Зачем это использовать

openclaw doctor — это поверхность проверки состояния OpenClaw. Используйте ее, когда Gateway, каналы, plugins, Skills, маршрутизация моделей, локальное состояние или миграции конфигурации работают не так, как ожидается, и вам нужна одна команда, которая объяснит, что не так.

У doctor есть три режима:

Предпочитайте --lint, когда автоматизации нужен стабильный результат. Предпочитайте --fix, когда оператор-человек намеренно хочет, чтобы doctor изменил конфигурацию или состояние.

Примеры

openclaw doctoropenclaw doctor --lintopenclaw doctor --lint --jsonopenclaw doctor --lint --severity-min warningopenclaw doctor --lint --allopenclaw doctor --lint --allow-execopenclaw doctor --deepopenclaw doctor --fixopenclaw doctor --fix --non-interactiveopenclaw doctor --generate-gateway-tokenopenclaw doctor --post-upgradeopenclaw doctor --post-upgrade --json

Для разрешений, специфичных для канала, используйте проверки канала вместо doctor:

openclaw channels capabilities --channel discord --target channel:<channel-id>openclaw channels status --probe

Целевая проверка возможностей Discord сообщает эффективные разрешения бота в канале; проверка состояния аудитирует настроенные каналы Discord и цели автоматического подключения к голосовым каналам.

Параметры

• --no-workspace-suggestions: отключить предложения памяти/поиска рабочей области
• --yes: принимать значения по умолчанию без запроса
• --repair: применять рекомендуемые исправления, не относящиеся к сервисам, без запроса; установки и перезаписи сервиса Gateway по-прежнему требуют интерактивного подтверждения или явных команд Gateway
• --fix: псевдоним для --repair
• --force: применять агрессивные исправления, включая перезапись пользовательской конфигурации сервиса при необходимости
• --non-interactive: запускать без запросов; только безопасные миграции и исправления, не относящиеся к сервисам
• --generate-gateway-token: сгенерировать и настроить токен Gateway
• --allow-exec: разрешить doctor выполнять настроенные exec SecretRefs при проверке секретов
• --deep: сканировать системные сервисы на предмет дополнительных установок Gateway и сообщать о недавних передачах перезапуска супервизора Gateway
• --lint: запускать модернизированные проверки состояния в режиме только для чтения и выводить диагностические находки
• --post-upgrade: запускать проверки совместимости plugins после обновления; выводит находки в stdout; завершается с кодом 1, если присутствуют находки уровня error
• --json: с --lint выводить находки в JSON вместо человекочитаемого вывода; с --post-upgrade выводить машиночитаемую JSON-оболочку ({ probesRun, findings })
• --severity-min <level>: с --lint отбрасывать находки ниже info, warning или error
• --all: с --lint запускать все зарегистрированные проверки, включая опциональные проверки, исключенные из стандартного набора автоматизации
• --skip <id>: с --lint пропускать id проверки; повторите, чтобы пропустить больше одной
• --only <id>: с --lint запускать только id проверки; повторите, чтобы запустить небольшой выбранный набор

Режим lint

openclaw doctor --lint — это режим автоматизации только для чтения для проверок doctor. Он использует путь структурированных проверок состояния, не запрашивает ввод и не исправляет и не перезаписывает конфигурацию/состояние. Используйте его в CI, скриптах предварительной проверки и рабочих процессах review, когда нужны машиночитаемые находки вместо управляемых запросов на исправление. Параметры вывода lint, такие как --json, --severity-min, --all, --only и --skip, принимаются только вместе с --lint.

openclaw doctor --lintopenclaw doctor --lint --severity-min warningopenclaw doctor --lint --jsonopenclaw doctor --lint --allopenclaw doctor --lint --allow-execopenclaw doctor --lint --only core/doctor/gateway-config --json

Человекочитаемый вывод компактен:

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-вывод — это поверхность для скриптов при запусках lint:

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

Поведение завершения:

• 0: нет находок на выбранном пороге серьезности или выше
• 1: как минимум одна находка соответствует выбранному порогу
• 2: сбой команды/среды выполнения до того, как могут быть сформированы находки lint

--severity-min управляет как видимыми находками, так и порогом завершения. Например, openclaw doctor --lint --severity-min error может не вывести находок и завершиться с 0, даже если существуют находки меньшей серьезности info или warning.

--all управляет тем, какие проверки выбираются до фильтрации по серьезности. Стандартный запуск lint — это стабильный шлюз автоматизации, который исключает проверки, намеренно сделанные опциональными, потому что они глубокие, исторические или с большей вероятностью выявляют исправимые остатки legacy-состояния. Используйте --all, когда нужен полный инвентарь lint без перечисления каждого id проверки. --only <id> остается самым точным селектором и может запускать любую зарегистрированную проверку по id.

Структурированные проверки состояния

Современные проверки doctor используют небольшой структурированный контракт:

detect(ctx, scope?) -> HealthFinding[]repair?(ctx, findings) -> HealthRepairResult

detect() обеспечивает работу doctor --lint. repair() необязателен и рассматривается только doctor --fix / doctor --repair. Проверки, которые еще не мигрировали к этой форме, продолжают использовать legacy-поток вклада doctor.

Разделение намеренное: detect() отвечает за диагностику, а repair() отвечает за отчет о том, что было изменено или будет изменено. Контексты исправления могут переносить запросы dryRun/diff, а результаты исправления могут возвращать структурированные diffs для изменений конфигурации/файлов плюс effects для сервисов, процессов, пакетов, состояния или других побочных эффектов. Это позволяет преобразованным проверкам развиваться в сторону doctor --fix --dry-run и отчетов diff без переноса планирования мутаций в detect().

repair() сообщает, пыталась ли проверка выполнить запрошенное исправление, через status: "repaired" | "skipped" | "failed". Пропущенный статус означает repaired, поэтому простым проверкам исправления нужно возвращать только изменения. Когда исправление возвращает skipped или failed, doctor сообщает причину и не запускает валидацию для этой проверки.

После успешного структурированного исправления doctor повторно запускает detect() с исправленными находками в качестве области. Проверки могут использовать выбранные находки, пути или значения ocPath для сфокусированной валидации. Если находка все еще присутствует, doctor сообщает предупреждение об исправлении вместо того, чтобы считать изменение молча завершенным.

Находка включает:

Модернизированные базовые проверки doctor остаются привязанными к упорядоченному вкладу doctor, который владеет их человекочитаемым поведением doctor / doctor --fix. Общий структурированный реестр состояния — это точка расширения: встроенные и поддерживаемые plugins проверки запускаются после базовых проверок doctor, когда их владеющий пакет регистрирует их в активном пути команды. Подпуть openclaw/plugin-sdk/health предоставляет тот же контракт этим потребителям расширения.

Выбор проверок

Используйте --only и --skip, когда рабочему процессу нужен сфокусированный шлюз:

openclaw doctor --lint --only core/doctor/gateway-config --jsonopenclaw doctor --lint --skip core/doctor/skills-readinessopenclaw doctor --lint --all --skip core/doctor/session-locks

--only и --skip принимают полные id проверок и могут повторяться. Если id --only не зарегистрирован, для этого id не запускается ни одна проверка; используйте поля checksRun и checksSkipped команды, чтобы убедиться, что сфокусированный шлюз выбирает ожидаемые проверки.

Режим после обновления

openclaw doctor --post-upgrade запускает проверки совместимости plugins, предназначенные для цепочки после сборки или обновления. Находки выводятся в stdout; команда завершается с кодом 1, если у любой находки есть level: "error". Добавьте --json, чтобы получить машиночитаемую оболочку ({ probesRun, findings }), подходящую для CI, community-скилла fork-upgrade и других инструментов smoke-проверки после обновления. Если установленный индекс plugins отсутствует или некорректен, режим JSON все равно выводит эту оболочку с находкой ошибки plugin.index_unavailable.

Примечания:

• В режиме Nix (OPENCLAW_NIX_MODE=1) проверки doctor только для чтения продолжают работать, но doctor --fix, doctor --repair, doctor --yes и doctor --generate-gateway-token отключены, потому что openclaw.json неизменяем. Вместо этого редактируйте источник Nix для этой установки; для nix-openclaw используйте агент-ориентированный краткий старт.
• Интерактивные запросы (например, исправления keychain/OAuth) запускаются только когда stdin является TTY и не задан --non-interactive. Запуски без терминала (cron, Telegram, без терминала) будут пропускать запросы.
• Производительность: неинтерактивные запуски doctor пропускают упреждающую загрузку plugins, чтобы проверки состояния без терминала оставались быстрыми. Интерактивные сеансы doctor по-прежнему загружают поверхности plugin, необходимые для устаревшего потока проверки состояния и восстановления.
• --lint строже, чем --non-interactive: он всегда работает только для чтения, никогда не запрашивает ввод и никогда не применяет безопасные миграции. Запускайте doctor --fix или doctor --repair, когда хотите, чтобы doctor внес изменения.
• По умолчанию doctor не выполняет exec SecretRefs при проверке секретов. Используйте openclaw doctor --allow-exec или openclaw doctor --lint --allow-exec только когда вы намеренно хотите, чтобы doctor запускал эти настроенные резолверы секретов.
• --fix (псевдоним для --repair) записывает резервную копию в ~/.openclaw/openclaw.json.bak и удаляет неизвестные ключи конфигурации, перечисляя каждое удаление.
• Модернизированные проверки состояния могут предоставлять путь repair() для doctor --fix; проверки, которые его не предоставляют, продолжают выполняться через существующий поток восстановления doctor.
• doctor --fix --non-interactive сообщает об отсутствующих или устаревших определениях сервиса Gateway, но не устанавливает и не перезаписывает их вне режима восстановления обновления. Запустите openclaw gateway install для отсутствующего сервиса или openclaw gateway install --force, когда вы намеренно хотите заменить средство запуска.
• Проверки целостности состояния теперь обнаруживают осиротевшие файлы транскриптов в каталоге сеансов. Для их архивации как .deleted.<timestamp> требуется интерактивное подтверждение; --fix, --yes и запуски без терминала оставляют их на месте.
• Doctor также сканирует ~/.openclaw/cron/jobs.json (или cron.store) на наличие устаревших форм заданий Cron и переписывает их перед импортом канонических строк в SQLite.
• Doctor сообщает о заданиях Cron с явными переопределениями payload.model, включая количество пространств имен провайдеров и несовпадения с agents.defaults.model, чтобы запланированные задания, которые не наследуют модель по умолчанию, были видны при расследованиях аутентификации или биллинга.
• В Linux doctor предупреждает, когда crontab пользователя все еще запускает устаревший ~/.openclaw/bin/ensure-whatsapp.sh; этот скрипт больше не поддерживается и может регистрировать ложные сбои Gateway WhatsApp, когда Cron не имеет окружения пользовательской шины systemd.
• Когда WhatsApp включен, doctor проверяет деградировавший цикл событий Gateway при все еще запущенных локальных клиентах openclaw-tui. doctor --fix останавливает только проверенные локальные клиенты TUI, чтобы ответы WhatsApp не ставились в очередь за устаревшими циклами обновления TUI.
• Doctor переписывает устаревшие ссылки моделей openai-codex/* в канонические ссылки openai/* для основных моделей, fallback-моделей, моделей генерации изображений/видео, переопределений heartbeat/subagent/compaction, hooks, переопределений моделей каналов и устаревших закреплений маршрутов сеансов. --fix также мигрирует устаревшие профили аутентификации openai-codex:* и записи auth.order.openai-codex в openai:*, переносит намерение Codex в записи agentRuntime.id: "codex" с областью провайдера/модели, удаляет устаревшие закрепления runtime для всего агента/сеанса и сохраняет исправленные ссылки агентов OpenAI на маршрутизации аутентификации Codex вместо прямой аутентификации по API-ключу OpenAI.
• Doctor очищает устаревшее промежуточное состояние зависимостей plugin, созданное более старыми версиями OpenClaw, и повторно связывает пакет хоста openclaw для управляемых npm plugins, которые объявляют его peer-зависимостью. Он также восстанавливает отсутствующие загружаемые plugins, на которые ссылается конфигурация, например plugins.entries, настроенные каналы, настроенные параметры провайдера/поиска или настроенные runtime агентов. Во время обновлений пакетов doctor пропускает восстановление plugins менеджером пакетов, пока замена пакета не завершится; после этого повторно запустите openclaw doctor --fix, если настроенный plugin все еще требует восстановления. Если загрузка не удалась, doctor сообщает об ошибке установки и сохраняет настроенную запись plugin для следующей попытки восстановления.
• Doctor восстанавливает устаревшую конфигурацию plugins, удаляя отсутствующие идентификаторы plugins из plugins.allow/plugins.deny/plugins.entries, а также соответствующую висячую конфигурацию каналов, цели heartbeat и переопределения моделей каналов, когда обнаружение plugins работает корректно.
• Doctor помещает недопустимую конфигурацию plugin в карантин, отключая затронутую запись plugins.entries.<id> и удаляя ее недопустимую полезную нагрузку config. Запуск Gateway уже пропускает только этот проблемный plugin, поэтому другие plugins и каналы могут продолжать работу.
• Задайте OPENCLAW_SERVICE_REPAIR_POLICY=external, когда жизненным циклом Gateway управляет другой супервизор. Doctor по-прежнему сообщает о состоянии Gateway/сервиса и применяет исправления, не связанные с сервисом, но пропускает установку/запуск/перезапуск/bootstrap сервиса и очистку устаревшего сервиса.
• В Linux doctor игнорирует неактивные дополнительные systemd units, похожие на Gateway, и не переписывает метаданные команды/точки входа для работающего systemd-сервиса Gateway во время восстановления. Сначала остановите сервис или используйте openclaw gateway install --force, когда вы намеренно хотите заменить активное средство запуска.
• Doctor автоматически мигрирует устаревшую плоскую конфигурацию Talk (talk.voiceId, talk.modelId и родственные ключи) в talk.provider + talk.providers.<provider>.
• Повторные запуски doctor --fix больше не сообщают и не применяют нормализацию Talk, когда единственное различие заключается в порядке ключей объекта.
• Doctor включает проверку готовности поиска по памяти и может рекомендовать openclaw configure --section model, когда отсутствуют учетные данные embedding.
• Doctor предупреждает, когда владелец команд не настроен. Владелец команд — это учетная запись человека-оператора, которой разрешено запускать команды только для владельца и одобрять опасные действия. Сопряжение DM только позволяет кому-либо общаться с ботом; если вы одобрили отправителя до появления bootstrap первого владельца, задайте commands.ownerAllowFrom явно.
• Doctor сообщает информационную заметку, когда настроены агенты в режиме Codex и личные ресурсы Codex CLI существуют в Codex home оператора. Локальные запуски app-server Codex используют изолированные home для каждого агента, поэтому при необходимости сначала установите plugin Codex, затем используйте openclaw migrate plan codex, чтобы инвентаризировать ресурсы, которые следует продвигать намеренно.
• Doctor удаляет выведенный из эксплуатации plugins.entries.codex.config.codexDynamicToolsProfile; app-server Codex всегда сохраняет нативные инструменты рабочей области Codex нативными.
• Doctor предупреждает, когда Skills, разрешенные для агента по умолчанию, недоступны в текущей runtime-среде, потому что отсутствуют bins, env vars, config или требования ОС. doctor --fix может отключить эти недоступные Skills с помощью skills.entries.<skill>.enabled=false; если вы хотите сохранить Skill активным, вместо этого установите/настройте отсутствующее требование.
• Если режим sandbox включен, но Docker недоступен, doctor сообщает предупреждение с высоким уровнем сигнала и способом исправления (install Docker или openclaw config set agents.defaults.sandbox.mode off).
• Если присутствуют устаревшие файлы реестра sandbox или каталоги shards (~/.openclaw/sandbox/containers.json, ~/.openclaw/sandbox/browsers.json, ~/.openclaw/sandbox/containers/ или ~/.openclaw/sandbox/browsers/), doctor сообщает о них; openclaw doctor --fix мигрирует допустимые записи в SQLite и помещает недопустимые устаревшие файлы в карантин.
• Если gateway.auth.token/gateway.auth.password управляются SecretRef и недоступны в текущем пути команды, doctor сообщает предупреждение только для чтения и не записывает plaintext fallback credentials. Для SecretRefs на основе exec doctor пропускает выполнение, если отсутствует --allow-exec.
• Если проверка SecretRef канала завершается сбоем в пути исправления, doctor продолжает работу и сообщает предупреждение вместо раннего выхода.
• После миграций каталога состояния doctor предупреждает, когда включенные учетные записи Telegram или Discord по умолчанию зависят от env fallback, а TELEGRAM_BOT_TOKEN или DISCORD_BOT_TOKEN недоступны процессу doctor.
• Авторазрешение имени пользователя Telegram allowFrom (doctor --fix) требует разрешимый токен Telegram в текущем пути команды. Если проверка токена недоступна, doctor сообщает предупреждение и пропускает авторазрешение для этого прохода.

macOS: переопределения env launchctl

Если ранее вы запускали launchctl setenv OPENCLAW_GATEWAY_TOKEN ... (или ...PASSWORD), это значение переопределяет ваш файл конфигурации и может вызывать постоянные ошибки "unauthorized".

launchctl getenv OPENCLAW_GATEWAY_TOKENlaunchctl getenv OPENCLAW_GATEWAY_PASSWORD launchctl unsetenv OPENCLAW_GATEWAY_TOKENlaunchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

Связанное

• Справочник CLI
• Doctor Gateway