Доктор

• Необязательное предварительное обновление для git-установок (только интерактивно).
• Проверка актуальности протокола UI (пересобирает Control UI, когда схема протокола новее).
• Проверка работоспособности и запрос на перезапуск.
• Сводка состояния Skills (доступны/отсутствуют/заблокированы) и состояние Plugin.

• Нормализация конфигурации для устаревших значений.
• Миграция конфигурации Talk из устаревших плоских полей talk.* в talk.provider + talk.providers.<provider>.
• Проверки миграции браузера для устаревших конфигураций расширения 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:<channel-id>.
• Проверки отзывчивости 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).
• Записывает обновленную конфигурацию и метаданные мастера.

Если это git checkout и doctor запущен интерактивно, он предлагает выполнить обновление (fetch/rebase/build) перед запуском doctor.

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

Сюда входят устаревшие плоские поля Talk. Текущая публичная речевая конфигурация Talk — это talk.provider + talk.providers.<provider>, а конфигурация 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.<provider>
• устаревшие верхнеуровневые селекторы 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.<provider> (openai/elevenlabs/microsoft/edge) → messages.tts.providers.<provider>
• 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.<provider> (openai/elevenlabs/microsoft/edge) → channels.discord.voice.tts.providers.<provider>
• channels.discord.accounts.<id>.voice.tts.<provider> (openai/elevenlabs/microsoft/edge) → channels.discord.accounts.<id>.voice.tts.providers.<provider>
• plugins.entries.voice-call.config.tts.<provider> (openai/elevenlabs/microsoft/edge) → plugins.entries.voice-call.config.tts.providers.<provider>
• 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.<id>.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.<channel>.accounts без channels.<channel>.defaultAccount или accounts.default, doctor предупреждает, что резервная маршрутизация может выбрать неожиданную учетную запись.
• Если channels.<channel>.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/<agentId>/sessions/
• Каталог агента:
  • из ~/.openclaw/agent/ в ~/.openclaw/agents/<agentId>/agent/
• Состояние auth WhatsApp (Baileys):
  • из устаревших ~/.openclaw/credentials/*.json (кроме oauth.json)
  • в ~/.openclaw/credentials/whatsapp/<accountId>/... (идентификатор учетной записи по умолчанию: 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 <requestId>
• ротировать свежий токен с помощью openclaw devices rotate --device <deviceId> --role <role>
• удалить и заново одобрить устаревшую запись с помощью openclaw devices remove <deviceId>

Это закрывает распространенный пробел «уже сопряжено, но все еще требуется сопряжение»: 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.<id>, цели Heartbeat, где был назван канал, и переопределения agents.*.models["<channel>/*"]. Это предотвращает циклы загрузки 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.
• Вы всегда можете принудительно выполнить полную перезапись через 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 для полного руководства по структуре рабочей области и резервному копированию git (рекомендуется приватный GitHub или GitLab).