---
read_when:
- Добавление или изменение миграций doctor
- Внесение критических изменений конфигурации
sidebarTitle: Doctor
summary: 'Команда doctor: проверки работоспособности, миграции конфигурации и шаги восстановления'
title: Доктор
x-i18n:
generated_at: "2026-06-28T22:56:50Z"
model: gpt-5.5
postprocess_version: locale-links-v1
provider: openai
source_hash: fdb5e3fb437a8678c427dee698a0ea6004b22b71c6e38cc6f75ba674fa4fcc5e
source_path: gateway/doctor.md
workflow: 16
---
`openclaw doctor` — это инструмент восстановления и миграции для OpenClaw. Он исправляет устаревшую конфигурацию и состояние, проверяет работоспособность и предоставляет применимые шаги восстановления.
## Быстрый старт
```bash
openclaw doctor
```
### Режимы без интерфейса и автоматизации
```bash
openclaw doctor --yes
```
Принимать значения по умолчанию без запросов (включая шаги восстановления перезапуска, службы и песочницы, когда применимо).
```bash
openclaw doctor --fix
```
Применять рекомендуемые исправления без запросов (исправления и перезапуски там, где это безопасно).
```bash
openclaw doctor --lint
openclaw doctor --lint --json
```
Запускать структурированные проверки работоспособности для CI или предварительной автоматизации. Этот режим доступен
только для чтения: он не запрашивает ввод, не исправляет, не мигрирует конфигурацию, не перезапускает службы и не
изменяет состояние.
```bash
openclaw doctor --fix --force
```
Также применять агрессивные исправления (перезаписывает пользовательские конфигурации супервизора).
```bash
openclaw doctor --non-interactive
```
Запускать без запросов и применять только безопасные миграции (нормализация конфигурации и перемещение состояния на диске). Пропускает действия с перезапуском, службами и песочницей, требующие подтверждения человеком. Миграции устаревшего состояния запускаются автоматически при обнаружении.
```bash
openclaw doctor --deep
```
Сканировать системные службы на наличие дополнительных установок Gateway (launchd/systemd/schtasks).
Если вы хотите просмотреть изменения перед записью, сначала откройте файл конфигурации:
```bash
cat ~/.openclaw/openclaw.json
```
## Режим lint только для чтения
`openclaw doctor --lint` — это удобный для автоматизации аналог
`openclaw doctor --fix`. Оба используют проверки работоспособности doctor, но их режим работы
различается:
| Режим | Запросы | Записывает конфигурацию/состояние | Вывод | Для чего использовать |
| ------------------------ | --------- | --------------------------------- | ----------------------------- | ---------------------------------- |
| `openclaw doctor` | да | нет | удобный отчет о состоянии | проверка состояния человеком |
| `openclaw doctor --fix` | иногда | да, согласно политике исправлений | удобный журнал исправлений | применение одобренных исправлений |
| `openclaw doctor --lint` | нет | нет | структурированные результаты | CI, предварительные проверки и review-gates |
Модернизированные проверки работоспособности могут предоставлять необязательную реализацию `repair()`.
`doctor --fix` применяет эти исправления, когда они есть, и продолжает использовать
существующий поток восстановления doctor для проверок, которые еще не были мигрированы.
Структурированный контракт восстановления также отделяет отчетность об исправлениях от обнаружения:
`detect()` сообщает о текущих результатах, а `repair()` может сообщать об изменениях,
diff конфигурации/файлов и побочных эффектах вне файлов. Это сохраняет открытым путь миграции
для будущего `doctor --fix --dry-run` и вывода diff, не заставляя lint-проверки
планировать мутации.
Примеры:
```bash
openclaw doctor --lint
openclaw doctor --lint --severity-min warning
openclaw doctor --lint --json
openclaw doctor --lint --all
openclaw doctor --lint --only core/doctor/gateway-config --json
```
JSON-вывод включает:
- `ok`: достиг ли какой-либо видимый результат выбранного порога серьезности
- `checksRun`: количество выполненных проверок работоспособности
- `checksSkipped`: проверки, пропущенные выбранным профилем, `--only` или `--skip`
- `findings`: структурированная диагностика с `checkId`, `severity`, `message` и
необязательными `path`, `line`, `column`, `ocPath` и `fixHint`
Коды выхода:
- `0`: нет результатов на выбранном пороге или выше него
- `1`: один или несколько результатов достигли выбранного порога
- `2`: сбой команды/среды выполнения до того, как результаты lint могли быть выведены
Используйте `--severity-min info|warning|error`, чтобы управлять и тем, что печатается, и тем, что
вызывает ненулевой код выхода lint. Используйте `--all`, чтобы запускать полный набор lint-проверок,
включая более глубокие opt-in проверки, исключенные из стандартного набора автоматизации. Используйте `--only ` для узких предварительных проверок и
`--skip `, чтобы временно исключить шумную проверку, сохранив остальную часть
lint-запуска активной.
Параметры вывода lint, такие как `--json`, `--severity-min`, `--all`, `--only` и
`--skip`, должны использоваться вместе с `--lint`; обычные запуски doctor и восстановления
их отклоняют.
## Что он делает (кратко)
- Необязательное предварительное обновление для git-установок (только интерактивно).
- Проверка актуальности протокола UI (пересобирает Control UI, когда схема протокола новее).
- Проверка работоспособности и запрос на перезапуск.
- Сводка состояния Skills (доступны/отсутствуют/заблокированы) и состояние Plugin.
- Нормализация конфигурации для устаревших значений.
- Миграция конфигурации Talk из устаревших плоских полей `talk.*` в `talk.provider` + `talk.providers.`.
- Проверки миграции браузера для устаревших конфигураций расширения Chrome и готовности Chrome MCP.
- Предупреждения о переопределении провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- Миграция устаревшего провайдера/профиля OpenAI Codex (`openai-codex` → `openai`) и предупреждения о затенении для устаревшего `models.providers.openai-codex`.
- Проверка предварительных условий OAuth TLS для OAuth-профилей OpenAI Codex.
- Предупреждения о allowlist Plugin/инструментов, когда `plugins.allow` ограничителен, но политика инструментов все еще запрашивает wildcard или инструменты, принадлежащие Plugin.
- Миграция устаревшего состояния на диске (сессии/каталог агента/аутентификация WhatsApp).
- Миграция устаревших ключей контракта манифеста Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Миграция устаревшего хранилища cron (`jobId`, `schedule.cron`, поля доставки/payload верхнего уровня, payload `provider`, резервные задания webhook `notify: true`).
- Очистка устаревшей runtime-policy для всего агента; runtime-policy провайдера/модели является активным селектором маршрута.
- Очистка устаревшей конфигурации Plugin, когда плагины включены; когда `plugins.enabled=false`, устаревшие ссылки на Plugin считаются инертной containment-конфигурацией и сохраняются.
- Проверка lock-файлов сессий и очистка устаревших lock.
- Восстановление транскриптов сессий для дублированных веток prompt-rewrite, созданных затронутыми сборками 2026.4.24.
- Обнаружение tombstone восстановления после перезапуска зависшего subagent, с поддержкой `--fix` для очистки устаревших флагов прерванного восстановления, чтобы запуск не продолжал считать дочерний процесс restart-aborted.
- Проверки целостности состояния и разрешений (сессии, транскрипты, каталог состояния).
- Проверки разрешений файла конфигурации (chmod 600) при локальном запуске.
- Работоспособность аутентификации модели: проверяет истечение OAuth, может обновлять истекающие токены и сообщает о состояниях cooldown/disabled для auth-profile.
- Восстановление образа песочницы, когда включена sandboxing.
- Миграция устаревших служб и обнаружение дополнительного Gateway.
- Миграция устаревшего состояния канала Matrix (в режиме `--fix` / `--repair`).
- Проверки среды выполнения Gateway (служба установлена, но не запущена; кэшированная метка launchd).
- Предупреждения о состоянии каналов (проверяются из работающего Gateway).
- Проверки разрешений для отдельных каналов находятся в `openclaw channels capabilities`; например, разрешения голосового канала Discord проверяются с помощью `openclaw channels capabilities --channel discord --target channel:`.
- Проверки отзывчивости WhatsApp при ухудшении здоровья event-loop Gateway, когда локальные TUI-клиенты все еще запущены; `--fix` останавливает только проверенные локальные TUI-клиенты.
- Восстановление маршрутов Codex для устаревших ссылок моделей `openai-codex/*` в основных моделях, fallback, моделях генерации изображений/видео, переопределениях Heartbeat/subagent/Compaction, hooks, переопределениях моделей каналов и закреплениях маршрутов сессий; `--fix` переписывает их в `openai/*`, мигрирует auth-профили/порядок `openai-codex:*` в `openai:*`, удаляет устаревшие закрепления среды выполнения сессий/всего агента и оставляет канонические ссылки агентов OpenAI на стандартном harness Codex.
- Аудит конфигурации супервизора (launchd/systemd/schtasks) с необязательным исправлением.
- Очистка среды встроенного proxy для служб Gateway, которые захватили значения shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` во время установки или обновления.
- Проверки лучших практик среды выполнения Gateway (Node против Bun, пути менеджеров версий).
- Диагностика конфликта порта Gateway (по умолчанию `18789`).
- Предупреждения безопасности для открытых политик DM.
- Проверки аутентификации Gateway для режима локального токена (предлагает генерацию токена, когда источник токена отсутствует; не перезаписывает конфигурации token SecretRef).
- Обнаружение проблем сопряжения устройств (ожидающие первичные запросы сопряжения, ожидающие повышения роли/области, дрейф устаревшего локального кэша device-token и дрейф аутентификации paired-record).
- Проверка systemd linger в Linux.
- Проверка размера bootstrap-файла рабочей области (предупреждения об усечении/приближении к лимиту для файлов контекста).
- Проверка готовности Skills для агента по умолчанию; сообщает разрешенные навыки с отсутствующими bin, env, config или требованиями ОС, а `--fix` может отключать недоступные навыки в `skills.entries`.
- Проверка состояния автодополнения shell и автоустановка/обновление.
- Проверка готовности провайдера embeddings для поиска в памяти (локальная модель, ключ удаленного API или бинарный файл QMD).
- Проверки установки из исходников (несоответствие pnpm workspace, отсутствующие UI-ресурсы, отсутствующий бинарный файл tsx).
- Записывает обновленную конфигурацию и метаданные мастера.
## Обратное заполнение и сброс Dreams UI
Сцена Dreams в Control UI включает действия **Backfill**, **Reset** и **Clear Grounded** для grounded dreaming workflow. Эти действия используют RPC-методы в стиле gateway doctor, но они **не** являются частью CLI-восстановления/миграции `openclaw doctor`.
Что они делают:
- **Backfill** сканирует исторические файлы `memory/YYYY-MM-DD.md` в активной рабочей области, запускает grounded REM diary pass и записывает обратимые записи backfill в `DREAMS.md`.
- **Reset** удаляет только эти помеченные записи дневника backfill из `DREAMS.md`.
- **Clear Grounded** удаляет только подготовленные краткосрочные записи только grounded, которые пришли из исторического replay и еще не накопили live recall или daily support.
Чего они сами по себе **не** делают:
- они не редактируют `MEMORY.md`
- они не запускают полные миграции doctor
- они не помещают автоматически grounded-кандидаты в live short-term promotion store, если вы явно не запустите сначала staged CLI path
Если вы хотите, чтобы grounded historical replay влиял на обычную deep promotion lane, используйте вместо этого CLI-поток:
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
Это помещает grounded durable candidates в short-term dreaming store, сохраняя `DREAMS.md` как поверхность review.
## Подробное поведение и обоснование
Если это git checkout и doctor запущен интерактивно, он предлагает выполнить обновление (fetch/rebase/build) перед запуском doctor.
Если конфигурация содержит устаревшие формы значений (например, `messages.ackReaction` без переопределения для конкретного канала), doctor нормализует их в текущую схему.
Сюда входят устаревшие плоские поля Talk. Текущая публичная речевая конфигурация Talk — это `talk.provider` + `talk.providers.`, а конфигурация realtime voice — `talk.realtime.*`. Doctor переписывает старые формы `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` в карту провайдера и переписывает устаревшие селекторы realtime верхнего уровня (`talk.mode`, `talk.transport`, `talk.brain`, `talk.model`, `talk.voice`) в `talk.realtime`.
Doctor также предупреждает, когда `plugins.allow` не пуст, а политика инструментов использует
wildcard или записи инструментов, принадлежащие Plugin. `tools.allow: ["*"]` сопоставляется только с инструментами
из Plugin, которые действительно загружены; это не обходит эксклюзивный
список разрешенных Plugin.
Когда конфигурация содержит устаревшие ключи, другие команды отказываются запускаться и просят выполнить `openclaw doctor`.
Doctor выполнит следующее:
- Объяснит, какие устаревшие ключи были найдены.
- Покажет примененную миграцию.
- Перезапишет `~/.openclaw/openclaw.json` с обновленной схемой.
Запуск Gateway отклоняет устаревшие форматы конфигурации и просит выполнить `openclaw doctor --fix`; он не перезаписывает `openclaw.json` при запуске. Миграции хранилища заданий Cron также выполняются через `openclaw doctor --fix`.
Текущие миграции:
- `routing.allowFrom` → `channels.whatsapp.allowFrom`
- `routing.groupChat.requireMention` → `channels.whatsapp/telegram/imessage.groups."*".requireMention`
- `routing.groupChat.historyLimit` → `messages.groupChat.historyLimit`
- `routing.groupChat.mentionPatterns` → `messages.groupChat.mentionPatterns`
- `channels.telegram.requireMention` → `channels.telegram.groups."*".requireMention`
- удалить выведенные из использования `channels.webchat` и `gateway.webchat`
- `routing.queue` → `messages.queue`
- `routing.bindings` → верхнеуровневый `bindings`
- `routing.agents`/`routing.defaultAgentId` → `agents.list` + `agents.list[].default`
- устаревшие `talk.voiceId`/`talk.voiceAliases`/`talk.modelId`/`talk.outputFormat`/`talk.apiKey` → `talk.provider` + `talk.providers.`
- устаревшие верхнеуровневые селекторы Talk в реальном времени (`talk.mode`/`talk.transport`/`talk.brain`/`talk.model`/`talk.voice`) + `talk.provider`/`talk.providers` → `talk.realtime`
- `routing.agentToAgent` → `tools.agentToAgent`
- `routing.transcribeAudio` → `tools.media.audio.models`
- `messages.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.`
- `messages.tts.provider: "edge"` и `messages.tts.providers.edge` → `messages.tts.provider: "microsoft"` и `messages.tts.providers.microsoft`
- поля выбора говорящего TTS (`voice`/`voiceName`/`voiceId`) → `speakerVoice`/`speakerVoiceId`
- `channels.discord.voice.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.voice.tts.providers.`
- `channels.discord.accounts..voice.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `channels.discord.accounts..voice.tts.providers.`
- `plugins.entries.voice-call.config.tts.` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `plugins.entries.voice-call.config.tts.providers.`
- `plugins.entries.voice-call.config.tts.provider: "edge"` и `plugins.entries.voice-call.config.tts.providers.edge` → `provider: "microsoft"` и `providers.microsoft`
- `plugins.entries.voice-call.config.provider: "log"` → `"mock"`
- `plugins.entries.voice-call.config.twilio.from` → `plugins.entries.voice-call.config.fromNumber`
- `plugins.entries.voice-call.config.streaming.sttProvider` → `plugins.entries.voice-call.config.streaming.provider`
- `plugins.entries.voice-call.config.streaming.openaiApiKey|sttModel|silenceDurationMs|vadThreshold` → `plugins.entries.voice-call.config.streaming.providers.openai.*`
- `bindings[].match.accountID` → `bindings[].match.accountId`
- Для каналов с именованными `accounts`, но сохраняющимися верхнеуровневыми значениями канала для одной учетной записи, переместить эти значения с областью действия учетной записи в повышенную учетную запись, выбранную для этого канала (`accounts.default` для большинства каналов; Matrix может сохранить существующую совпадающую именованную/default-цель)
- `identity` → `agents.list[].identity`
- `agent.*` → `agents.defaults` + `tools.*` (tools/elevated/exec/sandbox/subagents)
- `agent.model`/`allowedModels`/`modelAliases`/`modelFallbacks`/`imageModelFallbacks` → `agents.defaults.models` + `agents.defaults.model.primary/fallbacks` + `agents.defaults.imageModel.primary/fallbacks`
- удалить `agents.defaults.llm`; используйте `models.providers..timeoutSeconds` для тайм-аутов медленных провайдеров/моделей и держите тайм-аут агента/запуска выше этого значения, когда весь запуск должен длиться дольше
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- удалить `browser.relayBindHost` (устаревшая настройка ретранслятора расширения)
- устаревшее `models.providers.*.api: "openai"` → `"openai-completions"` (запуск Gateway также пропускает провайдеров, у которых `api` задан как будущее или неизвестное значение enum, вместо того чтобы аварийно завершаться)
- удалить `plugins.entries.codex.config.codexDynamicToolsProfile`; сервер приложения Codex всегда сохраняет собственные инструменты рабочей области Codex как нативные
Предупреждения Doctor также включают рекомендации по учетной записи по умолчанию для каналов с несколькими учетными записями:
- Если настроены две или более записи `channels..accounts` без `channels..defaultAccount` или `accounts.default`, doctor предупреждает, что резервная маршрутизация может выбрать неожиданную учетную запись.
- Если `channels..defaultAccount` задан как неизвестный идентификатор учетной записи, doctor предупреждает и перечисляет настроенные идентификаторы учетных записей.
Если вы вручную добавили `models.providers.opencode`, `opencode-zen` или `opencode-go`, это переопределяет встроенный каталог OpenCode из `openclaw/plugin-sdk/llm`. Это может принудительно направить модели на неправильный API или обнулить стоимость. Doctor предупреждает, чтобы вы могли удалить переопределение и восстановить маршрутизацию API + стоимость для каждой модели.
Если ваша конфигурация браузера все еще указывает на удаленный путь расширения Chrome, doctor нормализует ее к текущей модели подключения Chrome MCP на локальном хосте:
- `browser.profiles.*.driver: "extension"` становится `"existing-session"`
- `browser.relayBindHost` удаляется
Doctor также проверяет путь Chrome MCP на локальном хосте, когда вы используете `defaultProfile: "user"` или настроенный профиль `existing-session`:
- проверяет, установлен ли Google Chrome на том же хосте для профилей автоматического подключения по умолчанию
- проверяет обнаруженную версию Chrome и предупреждает, если она ниже Chrome 144
- напоминает включить удаленную отладку на странице инспекции браузера (например, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` или `edge://inspect/#remote-debugging`)
Doctor не может включить настройку на стороне Chrome за вас. Chrome MCP на локальном хосте по-прежнему требует:
- браузер на базе Chromium 144+ на хосте gateway/node
- локально запущенный браузер
- включенную удаленную отладку в этом браузере
- подтверждение первого запроса согласия на подключение в браузере
Готовность здесь касается только предварительных условий локального подключения. Existing-session сохраняет текущие ограничения маршрутов Chrome MCP; продвинутые маршруты, такие как `responsebody`, экспорт PDF, перехват загрузок и пакетные действия, по-прежнему требуют управляемого браузера или raw CDP-профиля.
Эта проверка **не** применяется к Docker, sandbox, remote-browser или другим headless-потокам. Они продолжают использовать raw CDP.
Когда настроен OAuth-профиль OpenAI Codex, doctor проверяет конечную точку авторизации OpenAI, чтобы убедиться, что локальный стек Node/OpenSSL TLS может проверить цепочку сертификатов. Если проверка завершается ошибкой сертификата (например, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, истекший сертификат или самоподписанный сертификат), doctor выводит рекомендации по исправлению для конкретной платформы. На macOS с Homebrew Node исправление обычно заключается в `brew postinstall ca-certificates`. С `--deep` проверка выполняется даже если gateway исправен.
Если ранее вы добавили устаревшие настройки транспорта OpenAI в `models.providers.openai-codex`, они могут перекрыть встроенный путь провайдера Codex OAuth, который новые выпуски используют автоматически. Doctor предупреждает, когда видит эти старые настройки транспорта рядом с Codex OAuth, чтобы вы могли удалить или переписать устаревшее переопределение транспорта и вернуть встроенное поведение маршрутизации/резервирования. Пользовательские прокси и переопределения только заголовков по-прежнему поддерживаются и не вызывают это предупреждение.
Doctor проверяет устаревшие ссылки на модели `openai-codex/*`. Нативная маршрутизация обвязки Codex использует канонические ссылки на модели `openai/*`; ходы агента OpenAI проходят через обвязку сервера приложения Codex, а не через путь провайдера OpenAI в OpenClaw.
В режиме `--fix` / `--repair` doctor переписывает затронутые ссылки агента по умолчанию и отдельных агентов, включая основные модели, fallback-варианты, модели генерации изображений/видео, переопределения heartbeat/subagent/compaction, hooks, переопределения моделей каналов и устаревшее сохраненное состояние маршрута сессии:
- `openai-codex/gpt-*` становится `openai/gpt-*`.
- Намерение Codex переносится в записи `agentRuntime.id: "codex"` с областью действия провайдер/модель для восстановленных ссылок модели агента.
- Устаревшая конфигурация среды выполнения всего агента и сохраненные привязки среды выполнения сессии удаляются, поскольку выбор среды выполнения имеет область действия провайдер/модель.
- Существующая политика среды выполнения провайдера/модели сохраняется, если только восстановленная устаревшая ссылка на модель не требует маршрутизации Codex, чтобы сохранить старый путь auth.
- Существующие списки fallback-моделей сохраняются с переписанными устаревшими записями; скопированные настройки для каждой модели переносятся из устаревшего ключа в канонический ключ `openai/*`.
- Сохраненные `modelProvider`/`providerOverride`, `model`/`modelOverride`, уведомления о fallback и привязки auth-профиля сессии восстанавливаются во всех обнаруженных хранилищах сессий агентов.
- `/codex ...` означает «управлять нативным разговором Codex из чата или привязать его».
- `/acp ...` или `runtime: "acp"` означает «использовать внешний адаптер ACP/acpx».
Doctor также сканирует обнаруженные хранилища сессий агентов на предмет устаревшего автоматически созданного состояния маршрута после переноса настроенных моделей или среды выполнения с маршрута, принадлежащего Plugin, например Codex.
`openclaw doctor --fix` может очистить автоматически созданное устаревшее состояние, такое как привязки моделей `modelOverrideSource: "auto"`, метаданные модели среды выполнения, закрепленные идентификаторы обвязок, привязки CLI-сессий и автоматические переопределения auth-профилей, когда их владеющий маршрут больше не настроен. Явные пользовательские или устаревшие выборы модели сессии сообщаются для ручной проверки и остаются без изменений; переключите их с помощью `/model ...`, `/new` или сбросьте сессию, когда этот маршрут больше не нужен.
Doctor может мигрировать старые разметки на диске в текущую структуру:
- Хранилище сессий + транскрипты:
- из `~/.openclaw/sessions/` в `~/.openclaw/agents//sessions/`
- Каталог агента:
- из `~/.openclaw/agent/` в `~/.openclaw/agents//agent/`
- Состояние auth WhatsApp (Baileys):
- из устаревших `~/.openclaw/credentials/*.json` (кроме `oauth.json`)
- в `~/.openclaw/credentials/whatsapp//...` (идентификатор учетной записи по умолчанию: `default`)
Эти миграции выполняются по возможности и идемпотентны; doctor будет выдавать предупреждения, когда оставит устаревшие папки как резервные копии. Gateway/CLI также автоматически мигрирует устаревшие сессии + каталог агента при запуске, чтобы история/auth/модели попадали в путь отдельного агента без ручного запуска doctor. Auth WhatsApp намеренно мигрируется только через `openclaw doctor`. Нормализация провайдера/карты провайдеров Talk теперь сравнивает по структурному равенству, поэтому различия только в порядке ключей больше не вызывают повторные изменения `doctor --fix` без эффекта.
Doctor сканирует все установленные манифесты Plugin на наличие устаревших ключей возможностей верхнего уровня (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). При обнаружении он предлагает перенести их в объект `contracts` и переписать файл манифеста на месте. Эта миграция идемпотентна: если ключ `contracts` уже содержит те же значения, устаревший ключ удаляется без дублирования данных.
Doctor также проверяет хранилище заданий Cron (`~/.openclaw/cron/jobs.json` по умолчанию или `cron.store`, если переопределено) на старые формы заданий, которые планировщик все еще принимает для совместимости.
Текущие очистки Cron включают:
- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
- поля полезной нагрузки верхнего уровня (`message`, `model`, `thinking`, ...) → `payload`
- поля доставки верхнего уровня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- псевдонимы доставки `provider` в полезной нагрузке → явный `delivery.channel`
- устаревшие резервные задания Webhook с `notify: true` → явная доставка Webhook из `cron.webhook`, если она задана; задания announce сохраняют доставку в чат и получают `delivery.completionDestination`. Когда `cron.webhook` не задан, инертный маркер верхнего уровня `notify` удаляется для заданий без цели (существующая доставка, включая announce, сохраняется), поскольку доставка во время выполнения никогда его не читает
Gateway также очищает некорректные строки Cron во время загрузки, чтобы допустимые задания продолжали выполняться. Исходные некорректные строки копируются в `jobs-quarantine.json` рядом с активным хранилищем перед удалением из `jobs.json`; doctor сообщает о помещенных в карантин строках, чтобы вы могли просмотреть или исправить их вручную.
Запуск Gateway нормализует проекцию времени выполнения и игнорирует маркер верхнего уровня `notify`, но оставляет сохраненную конфигурацию Cron для исправления через doctor. Когда `cron.webhook` не задан, doctor удаляет инертный маркер для заданий без цели миграции (`delivery.mode` none/отсутствует, непригодная цель Webhook или существующая доставка announce/chat), оставляя существующую доставку нетронутой, поэтому повторные запуски `doctor --fix` больше не предупреждают о том же задании. Если `cron.webhook` задан, но не является допустимым URL HTTP(S), doctor все равно предупреждает и оставляет маркер, чтобы вы могли исправить URL.
В Linux doctor также предупреждает, когда crontab пользователя все еще вызывает устаревший `~/.openclaw/bin/ensure-whatsapp.sh`. Этот локальный для хоста скрипт не поддерживается текущим OpenClaw и может записывать ложные сообщения `Gateway inactive` в `~/.openclaw/logs/whatsapp-health.log`, когда Cron не может подключиться к пользовательской шине systemd. Удалите устаревшую запись crontab с помощью `crontab -e`; используйте `openclaw channels status --probe`, `openclaw doctor` и `openclaw gateway status` для текущих проверок состояния.
Doctor сканирует каждый каталог сеанса агента на устаревшие файлы блокировки записи — файлы, оставшиеся после аварийного завершения сеанса. Для каждого найденного файла блокировки он сообщает: путь, PID, жив ли еще PID, возраст блокировки и считается ли она устаревшей (мертвый PID, некорректные метаданные владельца, старше 30 минут или живой PID, который доказуемо принадлежит процессу не OpenClaw). В режиме `--fix` / `--repair` он автоматически удаляет блокировки с мертвыми, осиротевшими, повторно использованными, старыми некорректными владельцами или владельцами не OpenClaw. Старые блокировки, которые все еще принадлежат живому процессу OpenClaw, выводятся в отчете, но остаются на месте, чтобы doctor не отключил активный процесс записи транскрипта.
Doctor сканирует файлы JSONL сеансов агента на дублированную форму ветки, созданную ошибкой переписывания транскрипта промпта от 2026.4.24: заброшенный пользовательский ход с внутренним контекстом времени выполнения OpenClaw плюс активная соседняя ветка с тем же видимым пользовательским промптом. В режиме `--fix` / `--repair` doctor создает резервную копию каждого затронутого файла рядом с оригиналом и переписывает транскрипт на активную ветку, чтобы история Gateway и считыватели памяти больше не видели дублированные ходы.
Каталог состояния — операционный ствол системы. Если он исчезнет, вы потеряете сеансы, учетные данные, журналы и конфигурацию (если только у вас нет резервных копий где-то еще).
Doctor проверяет:
- **Каталог состояния отсутствует**: предупреждает о катастрофической потере состояния, предлагает заново создать каталог и напоминает, что не может восстановить отсутствующие данные.
- **Права каталога состояния**: проверяет возможность записи; предлагает исправить права (и выводит подсказку `chown`, когда обнаружено несоответствие владельца/группы).
- **Каталог состояния macOS, синхронизируемый с облаком**: предупреждает, когда состояние разрешается внутри iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) или `~/Library/CloudStorage/...`, потому что пути с синхронизацией могут вызывать более медленный ввод-вывод и гонки блокировок/синхронизации.
- **Каталог состояния Linux на SD или eMMC**: предупреждает, когда состояние разрешается в источник монтирования `mmcblk*`, потому что случайный ввод-вывод на SD или eMMC может быть медленнее и быстрее изнашивать носитель при записи сеансов и учетных данных.
- **Волатильный каталог состояния Linux**: предупреждает, когда состояние разрешается в `tmpfs` или `ramfs`, потому что сеансы, учетные данные, конфигурация и состояние SQLite с сопутствующими файлами WAL/журнала исчезнут при перезагрузке. Монтирования Docker `overlay` намеренно не помечаются, потому что их записываемые слои сохраняются между перезагрузками хоста, пока контейнер остается.
- **Каталоги сеансов отсутствуют**: `sessions/` и каталог хранилища сеансов необходимы для сохранения истории и предотвращения сбоев `ENOENT`.
- **Несоответствие транскрипта**: предупреждает, когда у недавних записей сеансов отсутствуют файлы транскриптов.
- **Основной сеанс "1-line JSONL"**: помечает случай, когда основной транскрипт содержит только одну строку (история не накапливается).
- **Несколько каталогов состояния**: предупреждает, когда несколько папок `~/.openclaw` существуют в разных домашних каталогах или когда `OPENCLAW_STATE_DIR` указывает в другое место (история может разделиться между установками).
- **Напоминание о удаленном режиме**: если `gateway.mode=remote`, doctor напоминает запустить его на удаленном хосте (состояние находится там).
- **Права файла конфигурации**: предупреждает, если `~/.openclaw/openclaw.json` доступен для чтения группе/всем, и предлагает ужесточить права до `600`.
Doctor проверяет профили OAuth в хранилище аутентификации, предупреждает, когда токены скоро истекут или уже истекли, и может обновить их, когда это безопасно. Если профиль OAuth/токена Anthropic устарел, он предлагает ключ API Anthropic или путь setup-token Anthropic. Подсказки обновления появляются только при интерактивном запуске (TTY); `--non-interactive` пропускает попытки обновления.
Когда обновление OAuth завершается постоянной ошибкой (например, `refresh_token_reused`, `invalid_grant` или провайдер сообщает, что нужно войти снова), doctor сообщает, что требуется повторная аутентификация, и печатает точную команду `openclaw models auth login --provider ...`, которую нужно выполнить.
Doctor также сообщает о профилях аутентификации, которые временно непригодны из-за:
- коротких периодов ожидания (лимиты частоты/тайм-ауты/сбои аутентификации)
- более длительных отключений (сбои оплаты/кредитов)
Устаревшие профили OAuth Codex, токены которых находятся в macOS Keychain (более старый onboarding до файлового макета sidecar), исправляются только через doctor. Один раз запустите `openclaw doctor --fix` из интерактивного терминала, чтобы встроенно мигрировать устаревшие токены из Keychain в `auth-profiles.json`; после этого встроенные ходы (Telegram, Cron, диспетчеризация субагентов) разрешают их как канонические профили OAuth OpenAI.
Если `hooks.gmail.model` задан, doctor проверяет ссылку на модель по каталогу и allowlist и предупреждает, когда она не разрешается или запрещена.
Когда песочница включена, doctor проверяет образы Docker и предлагает собрать образ или переключиться на устаревшие имена, если текущий образ отсутствует.
Doctor удаляет устаревшее созданное OpenClaw промежуточное состояние зависимостей Plugin в режиме `openclaw doctor --fix` / `openclaw doctor --repair`. Это охватывает устаревшие созданные корни зависимостей, старые каталоги этапа установки, локальный для пакета мусор от более раннего кода исправления зависимостей встроенных Plugin, а также осиротевшие или восстановленные управляемые npm-копии встроенных Plugin `@openclaw/*`, которые могут затенять текущий встроенный манифест. Doctor также заново связывает хост-пакет `openclaw` с управляемыми npm Plugin, объявляющими `peerDependencies.openclaw`, чтобы локальные для пакета импорты времени выполнения, такие как `openclaw/plugin-sdk/*`, продолжали разрешаться после обновлений или исправлений npm.
Doctor также может переустановить отсутствующие загружаемые Plugin, когда конфигурация ссылается на них, но локальный реестр Plugin не может их найти. Примеры включают материальные `plugins.entries`, настроенные параметры канала/провайдера/поиска и настроенные среды выполнения агентов. Во время обновлений пакета doctor избегает запуска исправления Plugin через менеджер пакетов, пока основной пакет заменяется; снова запустите `openclaw doctor --fix` после обновления, если настроенному Plugin все еще требуется восстановление. Запуск Gateway и перезагрузка конфигурации не запускают менеджеры пакетов; установки Plugin остаются явной работой doctor/install/update.
Doctor обнаруживает устаревшие сервисы Gateway (launchd/systemd/schtasks) и предлагает удалить их и установить сервис OpenClaw с текущим портом Gateway. Он также может сканировать дополнительные сервисы, похожие на Gateway, и печатать подсказки по очистке. Сервисы Gateway OpenClaw с именами профилей считаются полноценными и не помечаются как "лишние".
В Linux, если пользовательский сервис Gateway отсутствует, но существует системный сервис Gateway OpenClaw, doctor не устанавливает автоматически второй пользовательский сервис. Проверьте с помощью `openclaw gateway status --deep` или `openclaw doctor --deep`, затем удалите дубликат или задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, когда системный супервизор управляет жизненным циклом Gateway.
Когда у учетной записи канала Matrix есть ожидающая или требующая действия миграция устаревшего состояния, doctor (в режиме `--fix` / `--repair`) создает снимок перед миграцией, а затем выполняет шаги миграции по мере возможности: миграцию устаревшего состояния Matrix и подготовку устаревшего зашифрованного состояния. Оба шага не являются фатальными; ошибки записываются в журнал, и запуск продолжается. В режиме только чтения (`openclaw doctor` без `--fix`) эта проверка полностью пропускается.
Doctor теперь проверяет состояние сопряжения устройств как часть обычного прохода проверки состояния.
Что он сообщает:
- ожидающие первичные запросы на сопряжение
- ожидающие повышения роли для уже сопряженных устройств
- ожидающие расширения областей доступа для уже сопряженных устройств
- исправления несоответствия открытого ключа, когда id устройства все еще совпадает, но идентичность устройства больше не соответствует одобренной записи
- сопряженные записи, у которых отсутствует активный токен для одобренной роли
- сопряженные токены, области доступа которых отклонились от одобренной базовой линии сопряжения
- локальные кэшированные записи токена устройства для текущей машины, которые предшествуют ротации токена на стороне Gateway или содержат устаревшие метаданные областей доступа
Doctor не одобряет запросы на сопряжение автоматически и не ротирует токены устройств автоматически. Вместо этого он печатает точные следующие шаги:
- просмотреть ожидающие запросы с помощью `openclaw devices list`
- одобрить точный запрос с помощью `openclaw devices approve `
- ротировать свежий токен с помощью `openclaw devices rotate --device --role `
- удалить и заново одобрить устаревшую запись с помощью `openclaw devices remove `
Это закрывает распространенный пробел «уже сопряжено, но все еще требуется сопряжение»: doctor теперь отличает первичное сопряжение от ожидающих повышения роли/области действия и от дрейфа устаревшего токена/идентичности устройства.
Doctor выдает предупреждения, когда провайдер открыт для DM без списка разрешений или когда политика настроена опасным образом.
При запуске как пользовательская служба systemd doctor проверяет, что lingering включен, чтобы Gateway оставался активным после выхода из системы.
Doctor выводит сводку состояния рабочей области для агента по умолчанию:
- **Состояние Skills**: подсчитывает Skills, подходящие, с отсутствующими требованиями и заблокированные списком разрешений.
- **Состояние Plugin**: подсчитывает включенные/отключенные/ошибочные плагины; перечисляет ID плагинов для любых ошибок; сообщает возможности пакетных плагинов.
- **Предупреждения совместимости Plugin**: отмечает плагины, у которых есть проблемы совместимости с текущей средой выполнения.
- **Диагностика Plugin**: показывает любые предупреждения или ошибки времени загрузки, выданные реестром плагинов.
- **Восстановление TaskFlow**: показывает подозрительные управляемые TaskFlows, которые требуют ручной проверки или отмены.
Doctor проверяет, находятся ли bootstrap-файлы рабочей области (например, `AGENTS.md`, `CLAUDE.md` или другие внедренные файлы контекста) близко к настроенному лимиту символов или превышают его. Он сообщает по каждому файлу количество необработанных и внедренных символов, процент усечения, причину усечения (`max/file` или `max/total`) и общее количество внедренных символов как долю общего лимита. Когда файлы усечены или близки к лимиту, doctor выводит советы по настройке `agents.defaults.bootstrapMaxChars` и `agents.defaults.bootstrapTotalMaxChars`.
Когда `openclaw doctor --fix` удаляет отсутствующий плагин канала, он также удаляет висящую конфигурацию в области канала, которая ссылалась на этот плагин: записи `channels.`, цели Heartbeat, где был назван канал, и переопределения `agents.*.models["/*"]`. Это предотвращает циклы загрузки Gateway, когда среда выполнения канала уже отсутствует, но конфигурация все еще просит Gateway привязаться к ней.
Doctor проверяет, установлено ли автодополнение по Tab для текущей оболочки (zsh, bash, fish или PowerShell):
- Если профиль оболочки использует медленный динамический шаблон автодополнения (`source <(openclaw completion ...)`), doctor обновляет его до более быстрого варианта с кэшированным файлом.
- Если автодополнение настроено в профиле, но файл кэша отсутствует, doctor автоматически регенерирует кэш.
- Если автодополнение вообще не настроено, doctor предлагает установить его (только в интерактивном режиме; пропускается с `--non-interactive`).
Запустите `openclaw completion --write-state`, чтобы регенерировать кэш вручную.
Doctor проверяет готовность аутентификации локального Gateway по токену.
- Если режим токена требует токен, а источник токена отсутствует, doctor предлагает сгенерировать его.
- Если `gateway.auth.token` управляется SecretRef, но недоступен, doctor предупреждает и не перезаписывает его открытым текстом.
- `openclaw doctor --generate-gateway-token` принудительно генерирует токен только когда не настроен SecretRef токена.
Некоторым потокам восстановления нужно проверять настроенные учетные данные, не ослабляя fail-fast поведение среды выполнения.
- `openclaw doctor --fix` теперь использует ту же модель сводки SecretRef только для чтения, что и команды семейства status, для целевых исправлений конфигурации.
- Пример: восстановление Telegram `allowFrom` / `groupAllowFrom` `@username` пытается использовать настроенные учетные данные бота, когда они доступны.
- Если токен бота Telegram настроен через SecretRef, но недоступен в текущем пути команды, doctor сообщает, что учетные данные настроены, но недоступны, и пропускает авторазрешение вместо сбоя или ошибочного сообщения, что токен отсутствует.
Doctor выполняет проверку работоспособности и предлагает перезапустить Gateway, когда он выглядит неработоспособным.
Doctor проверяет, готов ли настроенный провайдер embeddings для поиска памяти для агента по умолчанию. Поведение зависит от настроенного backend и провайдера:
- **Backend QMD**: проверяет, доступен ли и запускается ли бинарный файл `qmd`. Если нет, выводит рекомендации по исправлению, включая npm-пакет и вариант ручного пути к бинарному файлу.
- **Явный локальный провайдер**: проверяет наличие локального файла модели или распознанного URL удаленной/загружаемой модели. Если он отсутствует, предлагает переключиться на удаленного провайдера.
- **Явный удаленный провайдер** (`openai`, `voyage` и т. д.): проверяет наличие API-ключа в окружении или хранилище аутентификации. Выводит практичные подсказки по исправлению, если ключ отсутствует.
- **Устаревший автоматический провайдер**: трактует `memorySearch.provider: "auto"` как OpenAI, проверяет готовность OpenAI, а `doctor --fix` переписывает его в `provider: "openai"`.
Когда доступен кэшированный результат проверки Gateway (Gateway был работоспособен на момент проверки), doctor сопоставляет его результат с конфигурацией, видимой CLI, и отмечает любые расхождения. Doctor не запускает новый ping embeddings в пути по умолчанию; используйте команду глубокого состояния памяти, когда нужна живая проверка провайдера.
Используйте `openclaw memory status --deep`, чтобы проверить готовность embeddings во время выполнения.
Если Gateway работоспособен, doctor выполняет проверку состояния канала и сообщает предупреждения с предлагаемыми исправлениями.
Doctor проверяет установленную конфигурацию супервизора (launchd/systemd/schtasks) на отсутствующие или устаревшие значения по умолчанию (например, зависимости systemd от network-online и задержку перезапуска). Когда он находит несоответствие, он рекомендует обновление и может переписать файл службы/задачу до текущих значений по умолчанию.
Примечания:
- `openclaw doctor` запрашивает подтверждение перед перезаписью конфигурации супервизора.
- `openclaw doctor --yes` принимает стандартные запросы на исправление.
- `openclaw doctor --fix` применяет рекомендованные исправления без запросов (`--repair` является псевдонимом).
- `openclaw doctor --fix --force` перезаписывает пользовательские конфигурации супервизора.
- `OPENCLAW_SERVICE_REPAIR_POLICY=external` оставляет doctor в режиме только для чтения для жизненного цикла службы Gateway. Он по-прежнему сообщает о работоспособности службы и выполняет исправления, не связанные со службой, но пропускает установку/запуск/перезапуск/bootstrap службы, перезаписи конфигурации супервизора и очистку устаревшей службы, потому что этим жизненным циклом управляет внешний супервизор.
- В Linux doctor не переписывает метаданные команды/entrypoint, пока соответствующий systemd unit Gateway активен. Он также игнорирует неактивные неустаревшие дополнительные похожие на Gateway units во время сканирования дублирующихся служб, чтобы сопутствующие файлы служб не создавали лишний шум очистки.
- Если аутентификация по токену требует токен, а `gateway.auth.token` управляется SecretRef, установка/восстановление службы doctor проверяет SecretRef, но не сохраняет разрешенные значения токена открытым текстом в метаданные окружения службы супервизора.
- Doctor обнаруживает управляемые значения окружения службы на основе `.env`/SecretRef, которые старые установки LaunchAgent, systemd или Windows Scheduled Task встроили inline, и переписывает метаданные службы так, чтобы эти значения загружались из источника среды выполнения, а не из определения супервизора.
- Doctor обнаруживает, когда команда службы все еще фиксирует старый `--port` после изменения `gateway.port`, и переписывает метаданные службы на текущий порт.
- Если аутентификация по токену требует токен, а настроенный SecretRef токена не разрешен, doctor блокирует путь установки/восстановления с практичными рекомендациями.
- Если настроены и `gateway.auth.token`, и `gateway.auth.password`, а `gateway.auth.mode` не задан, doctor блокирует установку/восстановление, пока режим не будет задан явно.
- Для пользовательских units systemd в Linux проверки дрейфа токена doctor теперь учитывают источники и `Environment=`, и `EnvironmentFile=` при сравнении метаданных аутентификации службы.
- Восстановления службы doctor отказываются переписывать, останавливать или перезапускать службу Gateway из более старого бинарного файла OpenClaw, когда конфигурация в последний раз была записана более новой версией. См. [Устранение неполадок Gateway](/ru/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
- Вы всегда можете принудительно выполнить полную перезапись через `openclaw gateway install --force`.
Doctor проверяет среду выполнения службы (PID, последний статус выхода) и предупреждает, когда служба установлена, но фактически не запущена. Он также проверяет конфликты портов на порту Gateway (по умолчанию `18789`) и сообщает вероятные причины (Gateway уже запущен, SSH-туннель).
Doctor предупреждает, когда служба Gateway работает на Bun или пути Node, управляемом менеджером версий (`nvm`, `fnm`, `volta`, `asdf` и т. д.). Каналам WhatsApp + Telegram требуется Node, а пути менеджеров версий могут ломаться после обновлений, потому что служба не загружает инициализацию вашей оболочки. Doctor предлагает миграцию на системную установку Node, когда она доступна (Homebrew/apt/choco).
Новоустановленные или восстановленные macOS LaunchAgents используют канонический системный PATH (`/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`) вместо копирования PATH интерактивной оболочки, поэтому системные бинарные файлы, управляемые Homebrew, остаются доступны, а Volta, asdf, fnm, pnpm и другие каталоги менеджеров версий не меняют, какой Node разрешают дочерние процессы. Службы Linux по-прежнему сохраняют явные корни окружения (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) и стабильные пользовательские bin-каталоги, но предполагаемые резервные каталоги менеджеров версий записываются в PATH службы только когда эти каталоги существуют на диске.
Doctor сохраняет любые изменения конфигурации и ставит метку метаданных мастера, чтобы зафиксировать запуск doctor.
Doctor предлагает систему памяти рабочей области, когда она отсутствует, и выводит совет по резервному копированию, если рабочая область еще не находится под git.
См. [/concepts/agent-workspace](/ru/concepts/agent-workspace) для полного руководства по структуре рабочей области и резервному копированию git (рекомендуется приватный GitHub или GitLab).
## Связанные материалы
- [Runbook Gateway](/ru/gateway)
- [Устранение неполадок Gateway](/ru/gateway/troubleshooting)