--- read_when: - У вас проблемы с подключением или аутентификацией, и вам нужны пошаговые исправления - Вы обновили и хотите выполнить проверку на здравый смысл summary: Справочник CLI для `openclaw doctor` (проверки работоспособности + управляемые исправления) title: Doctor x-i18n: generated_at: "2026-06-28T22:43:16Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: cf7c07cd39053fce7efa81d968ef0f2666f6f5331581e72d2684843519c63b43 source_path: cli/doctor.md workflow: 16 --- # `openclaw doctor` Проверки состояния и быстрые исправления для Gateway и каналов. Связано: - Устранение неполадок: [Устранение неполадок](/ru/gateway/troubleshooting) - Аудит безопасности: [Безопасность](/ru/gateway/security) ## Зачем это использовать `openclaw doctor` — это поверхность проверки состояния OpenClaw. Используйте ее, когда Gateway, каналы, plugins, Skills, маршрутизация моделей, локальное состояние или миграции конфигурации работают не так, как ожидается, и вам нужна одна команда, которая объяснит, что не так. У doctor есть три режима: | Режим | Команда | Поведение | | ------- | ------------------------ | ------------------------------------------------------------------------------- | | Проверка | `openclaw doctor` | Проверки для человека и управляемые подсказки. | | Исправление | `openclaw doctor --fix` | Применяет поддерживаемые исправления, используя подсказки, если неинтерактивное исправление небезопасно. | | Lint | `openclaw doctor --lint` | Структурированные находки только для чтения для CI, предварительной проверки и проверочных шлюзов. | Предпочитайте `--lint`, когда автоматизации нужен стабильный результат. Предпочитайте `--fix`, когда оператор-человек намеренно хочет, чтобы doctor изменил конфигурацию или состояние. ## Примеры ```bash openclaw doctor openclaw doctor --lint openclaw doctor --lint --json openclaw doctor --lint --severity-min warning openclaw doctor --lint --all openclaw doctor --lint --allow-exec openclaw doctor --deep openclaw doctor --fix openclaw doctor --fix --non-interactive openclaw doctor --generate-gateway-token openclaw doctor --post-upgrade openclaw doctor --post-upgrade --json ``` Для разрешений, специфичных для канала, используйте проверки канала вместо `doctor`: ```bash openclaw channels capabilities --channel discord --target channel: 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 `: с `--lint` отбрасывать находки ниже `info`, `warning` или `error` - `--all`: с `--lint` запускать все зарегистрированные проверки, включая опциональные проверки, исключенные из стандартного набора автоматизации - `--skip `: с `--lint` пропускать id проверки; повторите, чтобы пропустить больше одной - `--only `: с `--lint` запускать только id проверки; повторите, чтобы запустить небольшой выбранный набор ## Режим lint `openclaw doctor --lint` — это режим автоматизации только для чтения для проверок doctor. Он использует путь структурированных проверок состояния, не запрашивает ввод и не исправляет и не перезаписывает конфигурацию/состояние. Используйте его в CI, скриптах предварительной проверки и рабочих процессах review, когда нужны машиночитаемые находки вместо управляемых запросов на исправление. Параметры вывода lint, такие как `--json`, `--severity-min`, `--all`, `--only` и `--skip`, принимаются только вместе с `--lint`. ```bash openclaw doctor --lint openclaw doctor --lint --severity-min warning openclaw doctor --lint --json openclaw doctor --lint --all openclaw doctor --lint --allow-exec openclaw doctor --lint --only core/doctor/gateway-config --json ``` Человекочитаемый вывод компактен: ```text 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: ```json { "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. ## Структурированные проверки состояния Современные проверки doctor используют небольшой структурированный контракт: ```ts 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 сообщает предупреждение об исправлении вместо того, чтобы считать изменение молча завершенным. Находка включает: | Поле | Назначение | | ----------------- | ------------------------------------------------------ | | `checkId` | Стабильный id для фильтров skip/only и allowlist в CI. | | `severity` | `info`, `warning` или `error`. | | `message` | Человекочитаемое описание проблемы. | | `path` | Путь конфигурации, файла или логический путь, когда доступен. | | `line` / `column` | Местоположение в исходном коде, когда доступно. | | `ocPath` | Точный адрес `oc://`, когда проверка может указать на него. | | `fixHint` | Предлагаемое действие оператора или сводка исправления. | Модернизированные базовые проверки doctor остаются привязанными к упорядоченному вкладу doctor, который владеет их человекочитаемым поведением `doctor` / `doctor --fix`. Общий структурированный реестр состояния — это точка расширения: встроенные и поддерживаемые plugins проверки запускаются после базовых проверок doctor, когда их владеющий пакет регистрирует их в активном пути команды. Подпуть `openclaw/plugin-sdk/health` предоставляет тот же контракт этим потребителям расширения. ## Выбор проверок Используйте `--only` и `--skip`, когда рабочему процессу нужен сфокусированный шлюз: ```bash openclaw doctor --lint --only core/doctor/gateway-config --json openclaw doctor --lint --skip core/doctor/skills-readiness openclaw 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 используйте агент-ориентированный [краткий старт](https://github.com/openclaw/nix-openclaw#quick-start). - Интерактивные запросы (например, исправления 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.` требуется интерактивное подтверждение; `--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.` и удаляя ее недопустимую полезную нагрузку `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.`. - Повторные запуски `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..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". ```bash launchctl getenv OPENCLAW_GATEWAY_TOKEN launchctl getenv OPENCLAW_GATEWAY_PASSWORD launchctl unsetenv OPENCLAW_GATEWAY_TOKEN launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD ``` ## Связанное - [Справочник CLI](/ru/cli) - [Doctor Gateway](/ru/gateway/doctor)