---
read_when:
- Добавление или изменение миграций doctor
- Внесение несовместимых изменений в конфигурацию
sidebarTitle: Doctor
summary: 'Команда doctor: проверки состояния, миграции конфигурации и действия по восстановлению'
title: Диагностика
x-i18n:
generated_at: "2026-07-13T19:47:12Z"
model: gpt-5.6
postprocess_version: locale-links-v1
prompt_version: 24
provider: openai
source_hash: 617de9d36a6b00f9de425f4a5d924b4206cdfc73a3091365b75ad6d28211ed0c
source_path: gateway/doctor.md
workflow: 16
---
`openclaw doctor` — это инструмент восстановления и миграции OpenClaw. Он исправляет устаревшие конфигурацию и состояние, проверяет работоспособность и предлагает конкретные шаги по устранению проблем.
## Быстрый старт
```bash
openclaw doctor
```
### Режимы без пользовательского интерфейса и автоматизации
```bash
openclaw doctor --yes
```
Принимать значения по умолчанию без запросов (включая перезапуск, обслуживание и восстановление песочницы, когда применимо).
```bash
openclaw doctor --fix
```
Применять рекомендуемые исправления без запросов (`--repair` — псевдоним).
```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
```
## Режим проверки только для чтения
`openclaw doctor --lint` — предназначенный для автоматизации аналог
`openclaw doctor --fix`. Они используют один реестр правил Doctor, но
выбирают и применяют правила по-разному:
| Режим | Запросы | Запись конфигурации/состояния | Вывод | Назначение |
| ----------------------- | --------- | ----------------------------- | ------------------------------- | --------------------------------------- |
| `openclaw doctor` | да | нет | понятный отчёт о работоспособности | ручная проверка состояния |
| `openclaw doctor --fix` | иногда | да, согласно политике исправления | понятный журнал исправлений | применение утверждённых исправлений |
| `openclaw doctor --lint` | нет | нет | структурированные результаты | CI, предварительные проверки и контрольные этапы ревью |
По умолчанию `doctor --lint` запускает широкий безопасный профиль автоматизации: проверки,
которые являются статическими, локальными и полезными в выводе CI или предварительной проверки. Он пропускает проверки,
требующие явного включения, имеющие рекомендательный характер, зависящие от окружения или работающей службы,
связанные с инвентаризацией учётной записи или рабочего пространства либо с очисткой исторических данных.
Используйте `doctor --lint --all`, если нужен полный зарегистрированный аудит,
включая проверки с явным включением, или `--only ` для
целевой проверки.
`doctor --fix` не использует профиль проверки по умолчанию и не принимает
`--all`. Он выполняет упорядоченный путь исправления Doctor: современные проверки работоспособности могут предоставлять
необязательную реализацию `repair()`, а в более старых областях всё ещё используется устаревший
процесс исправления Doctor. Некоторые результаты проверки намеренно служат только для диагностики, поэтому
наличие проверки в `--lint --all` не означает, что `--fix` изменит эту область.
Контракт отделяет `detect()` (сообщает о результатах) от `repair()` (сообщает
об изменениях, различиях и побочных эффектах), сохраняя возможность будущего
`doctor --fix --dry-run` без превращения проверок в планировщики изменений.
Некоторые встроенные проверки внутренне отключены по умолчанию, чтобы оставаться доступными для
`--all`, `--only` и процессов исправления Doctor, не становясь частью стандартного
профиля автоматизации `doctor --lint`. Уровень серьёзности по-прежнему указывается для каждого
результата (`info`, `warning` или `error`); выбор по умолчанию не является уровнем
серьёзности.
```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`, `source`, `target`, `requirement`, `fixHint`
Коды завершения:
| Код | Значение |
| --- | -------------------------------------------------------------- |
| `0` | нет результатов с выбранным порогом серьёзности или выше |
| `1` | один или несколько результатов соответствуют выбранному порогу |
| `2` | сбой команды или среды выполнения до формирования результатов |
Флаги:
- `--severity-min info|warning|error` (по умолчанию `warning`): определяет как выводимые данные, так и условия ненулевого кода завершения.
- `--all`: запускает все зарегистрированные проверки, включая проверки с явным включением, исключённые из стандартного набора автоматизации.
- `--only ` (можно указывать несколько раз): запускать только проверки с указанными идентификаторами; неизвестный идентификатор выводится как результат с ошибкой.
- `--skip ` (можно указывать несколько раз): исключить проверку, продолжая выполнять остальные.
- `--json`, `--severity-min`, `--all`, `--only` и `--skip` требуют `--lint`; обычные запуски `openclaw doctor` и `--fix` отклоняют их.
## Что делает инструмент (кратко)
- Необязательное предварительное обновление для установок из git (только в интерактивном режиме).
- Проверка актуальности протокола интерфейса (пересобирает Control UI, если схема протокола новее).
- Проверка работоспособности и запрос на перезапуск.
- Сводка состояния Skills (доступны/отсутствуют/заблокированы) и состояния плагинов.
- Нормализация устаревших форматов значений конфигурации.
- Миграция конфигурации Talk из устаревших плоских полей `talk.*` в `talk.provider` + `talk.providers.`.
- Проверки миграции браузера для устаревших конфигураций расширения Chrome и готовности Chrome MCP.
- Предупреждения о переопределении провайдера OpenCode (`models.providers.opencode` / `opencode-zen` / `opencode-go`).
- Миграция устаревшего провайдера и профиля OpenAI Codex (`openai-codex` → `openai`) и предупреждения о перекрытии из-за устаревшего `models.providers.openai-codex`.
- Проверка предварительных требований TLS для профилей OAuth OpenAI Codex.
- Предупреждения о списках разрешённых плагинов и инструментов, когда `plugins.allow` устанавливает ограничения, но политика инструментов всё ещё запрашивает подстановочный знак или инструменты, принадлежащие плагинам.
- Миграция устаревшего состояния на диске (сеансы/каталог агента/аутентификация WhatsApp).
- Миграция устаревших ключей контракта манифеста плагина (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Миграция устаревшего хранилища Cron (`jobId`, `schedule.cron`, поля доставки и полезной нагрузки верхнего уровня, `provider` полезной нагрузки, задания резервного Webhook `notify: true`).
- Исправление закрепления среды выполнения Codex CLI (`agentRuntime.id: "codex-cli"` → `"codex"`) в `agents.defaults`, `agents.list[]` и `models.providers.*` (включая записи для отдельных моделей).
- Очистка устаревшей конфигурации плагинов, когда плагины включены; при `plugins.enabled=false` устаревшие ссылки на плагины сохраняются как неактивная изолирующая конфигурация.
- Проверка файлов блокировки сеансов и удаление устаревших блокировок.
- Восстановление журналов сеансов с дублированными ветвями перезаписи запросов, созданными затронутыми сборками 2026.4.24.
- Обнаружение маркеров восстановления после перезапуска зависших субагентов с поддержкой `--fix` для удаления устаревших флагов прерванного восстановления, чтобы при запуске дочерний процесс не продолжал считаться прерванным из-за перезапуска.
- Проверки целостности состояния и разрешений (сеансы, журналы, каталог состояния).
- Проверки разрешений файла конфигурации (chmod 600) при локальном запуске.
- Состояние аутентификации моделей: проверяет истечение срока OAuth, может обновлять истекающие токены и сообщает о периодах ожидания и отключённых состояниях профиля аутентификации.
- Восстановление образа песочницы, когда изоляция включена.
- Миграция устаревших служб и обнаружение дополнительных Gateway.
- Миграция устаревшего состояния канала Matrix (в режиме `--fix` / `--repair`).
- Проверки среды выполнения Gateway (служба установлена, но не запущена; кэшированная метка launchd).
- Предупреждения о состоянии каналов (полученные при проверке работающего Gateway).
- Проверки разрешений для отдельных каналов находятся в `openclaw channels capabilities`; например, разрешения голосовых каналов Discord проверяются с помощью `openclaw channels capabilities --channel discord --target channel:`.
- Проверки отзывчивости WhatsApp при ухудшении состояния цикла событий Gateway, когда локальные клиенты TUI всё ещё работают; `--fix` останавливает только проверенные локальные клиенты TUI.
- Исправление маршрутов Codex для устаревших ссылок на модели `openai-codex/*` в основных моделях, резервных вариантах, моделях генерации изображений и видео, переопределениях heartbeat/субагентов/compaction, хуках, переопределениях моделей каналов и закреплённых маршрутах сеансов; `--fix` заменяет их на `openai/*`, переносит профили и порядок аутентификации `openai-codex:*` в `openai:*`, удаляет устаревшие закрепления среды выполнения сеанса и всего агента и позволяет исправленному эффективному маршруту определять совместимость Codex.
- Аудит конфигурации супервизора (launchd/systemd/schtasks) с необязательным исправлением.
- Очистка переменных окружения встроенного прокси для служб Gateway, сохранивших значения оболочки `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` при установке или обновлении.
- Проверки среды выполнения Gateway (неподдерживаемые устаревшие службы Bun, пути менеджеров версий).
- Диагностика конфликтов порта Gateway (по умолчанию `18789`).
- Предупреждения безопасности для открытых политик личных сообщений.
- Проверки аутентификации Gateway в режиме локального токена (предлагает создать токен, если источник токена отсутствует; не перезаписывает конфигурации SecretRef токена).
- Обнаружение проблем с сопряжением устройств (ожидающие запросы на первое сопряжение, ожидающие повышения роли или области доступа, рассинхронизация устаревшего локального кэша токена устройства и рассинхронизация аутентификации записи сопряжения).
- Проверка linger systemd в Linux.
- Проверка размера загрузочных файлов рабочего пространства (предупреждения об усечении или приближении к пределу для файлов контекста).
- Проверка готовности Skills для агента по умолчанию; сообщает о разрешённых навыках с отсутствующими исполняемыми файлами, переменными окружения, конфигурацией или требованиями к ОС, а `--fix` может отключить недоступные навыки в `skills.entries`.
- Проверка состояния автодополнения оболочки и автоматическая установка или обновление.
- Проверка готовности провайдера векторных представлений для поиска по памяти (локальная модель, ключ удалённого API или бинарный файл QMD).
- Проверки установки из исходного кода (несоответствие рабочего пространства pnpm, отсутствие ресурсов интерфейса, отсутствие бинарного файла tsx).
- Запись обновлённой конфигурации и метаданных мастера настройки.
## Заполнение и сброс интерфейса Dreams UI
Сцена Dreams в Control UI включает действия **Заполнить историю**, **Сбросить** и **Очистить привязанные к фактам** для рабочего процесса Dreaming с привязкой к фактам. Они используют RPC-методы Gateway в стиле диагностики, но **не** являются частью исправления или миграции через CLI `openclaw doctor`.
| Действие | Что оно делает |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Заполнить историю | Сканирует исторические файлы `memory/YYYY-MM-DD.md` в активном рабочем пространстве, выполняет проход дневника REM с привязкой к фактам и записывает обратимые записи заполнения истории в `DREAMS.md`. |
| Сбросить | Удаляет из `DREAMS.md` только помеченные записи дневника, созданные при заполнении истории. |
| Очистить привязанные к фактам | Удаляет только подготовленные краткосрочные записи, созданные исключительно с привязкой к фактам при воспроизведении истории и ещё не накопившие поддержку от фактического извлечения или ежедневной обработки. |
Ни одно из этих действий не изменяет `MEMORY.md`, не запускает полные диагностические миграции и само по себе не помещает кандидатов с привязкой к фактам в рабочее хранилище продвижения краткосрочных записей. Чтобы направить воспроизведение истории с привязкой к фактам в обычный поток глубокого продвижения, используйте вместо этого процесс CLI:
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
Эта команда помещает устойчивые кандидаты с привязкой к фактам в краткосрочное хранилище Dreaming, а `DREAMS.md` остаётся поверхностью для проверки.
## Подробное поведение и обоснование
Если это рабочая копия git и диагностика выполняется интерактивно, перед её запуском предлагается выполнить обновление (fetch/rebase/build).
Диагностика преобразует устаревшие формы значений в текущую схему. Текущая конфигурация речи Talk — `talk.provider` + `talk.providers.`, а конфигурация голоса в реальном времени находится в `talk.realtime.*`. Диагностика преобразует старые формы `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` в карту провайдеров, а устаревшие селекторы реального времени верхнего уровня (`talk.mode`, `talk.transport`, `talk.brain`, `talk.model`, `talk.voice`) — в `talk.realtime`.
Диагностика также предупреждает, если `plugins.allow` не пуст и политика инструментов использует подстановочный знак или записи инструментов, принадлежащие плагинам. `tools.allow: ["*"]` сопоставляется только с инструментами фактически загруженных плагинов; он не позволяет обойти эксклюзивный список разрешённых плагинов.
Если конфигурация содержит устаревший ключ с активной миграцией, другие команды отказываются запускаться и предлагают выполнить `openclaw doctor`. Диагностика объясняет, какие устаревшие ключи были обнаружены, показывает применённую миграцию и перезаписывает `~/.openclaw/openclaw.json` с обновлённой схемой. Gateway отказывается запускаться с устаревшими форматами конфигурации и предлагает выполнить `openclaw doctor --fix`; при запуске он не перезаписывает `openclaw.json`. Миграции хранилища заданий Cron также выполняются командой `openclaw doctor --fix`.
Автоматические миграции сохраняются в диагностике лишь примерно два месяца после
вывода ключа из эксплуатации. Для более старых устаревших ключей (например исходных
`routing.queue`, `routing.bindings`, `routing.agents`/`defaultAgentId`,
`routing.transcribeAudio`, верхнеуровневого `agent.*` или верхнеуровневого `identity`
из формы конфигурации до появления поддержки нескольких агентов) пути миграции
больше нет; теперь конфигурация с такими ключами не преобразуется, а не проходит
проверку. Исправьте эти ключи вручную в соответствии с текущим справочником
конфигурации, прежде чем диагностика сможет продолжить работу.
Активные миграции:
| Устаревший ключ | Текущий ключ |
| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `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` | удалены (WebChat выведен из эксплуатации) |
| `channels.feishu.accounts..botName` | `channels.feishu.accounts..name` |
| `session.threadBindings.ttlHours`, `channels..threadBindings.ttlHours` (в том числе для отдельных учётных записей) | `...threadBindings.idleHours` |
| устаревшие `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.realtime` |
| `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..tts.` / `channels..accounts..tts.` (все каналы, кроме Discord) | `...tts.providers.` |
| `channels..voice.tts.` / `channels..accounts..voice.tts.` (все каналы, включая Discord) | `...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"` / `...tts.providers.edge` | `provider: "microsoft"` / `...tts.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.*` |
| `models.providers.*.api: "openai"` | `"openai-completions"` (при запуске Gateway также пропускает провайдеров, у которых `api` содержит будущее или неизвестное значение перечисления, вместо отказа с запретом по умолчанию) |
| `browser.ssrfPolicy.allowPrivateNetwork` | `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` |
| `browser.profiles.*.driver: "extension"` | `"existing-session"` |
| `browser.relayBindHost` | удалён (устаревшая настройка ретранслятора расширения Chrome) |
| `mcp.servers.*.type` (встроенные псевдонимы CLI) | `mcp.servers.*.transport` |
| `plugins.entries.codex.config.codexDynamicToolsProfile` | удалён (сервер приложения Codex всегда сохраняет инструменты рабочего пространства Codex в их исходном формате) |
| `commands.modelsWrite` | удалён (`/models add` устарел) |
| `agents.defaults/list[].silentReplyRewrite`, `surfaces.*.silentReplyRewrite` | удалены (точное значение `NO_REPLY` больше не преобразуется в видимый резервный текст) |
| `agents.defaults/list[].systemPromptOverride` | удалён (OpenClaw управляет создаваемым системным промптом) |
| `agents.defaults/list[].embeddedPi` | `embeddedAgent` |
| `agents.defaults/list[].sandbox.perSession` | `sandbox.scope` |
| `agents.defaults.llm` | удалён (используйте `models.providers..timeoutSeconds` для тайм-аутов медленных моделей или провайдеров, сохраняя значение ниже предельного тайм-аута агента или запуска) |
| верхнеуровневый `memorySearch` | `agents.defaults.memorySearch` |
| `memorySearch.provider: "auto"` | `"openai"` |
| `memorySearch.store.path` (на любом уровне) | удалён (индексы памяти находятся в базе данных каждого агента) |
| верхнеуровневый `heartbeat` | `agents.defaults.heartbeat` / `channels.defaults.heartbeat` |
| идентификаторы политик `plugins.openai-codex` | `plugins.openai` |
| `tools.web.x_search.apiKey` | `plugins.entries.xai.config.webSearch.apiKey` |
| `session.maintenance.rotateBytes`, `session.parentForkMaxTokens` | удалены (устарели) |
| `diagnostics.memoryPressureBundle` | `diagnostics.memoryPressureSnapshot` |
Строки `plugins.entries.voice-call.config.*` выше нормализуются самим плагином
Voice Call при каждой загрузке конфигурации, а не командой `openclaw
doctor`. Плагин также регистрирует при запуске предупреждение со ссылкой на `openclaw
doctor --fix`, но в настоящее время диагностика не перезаписывает
`openclaw.json` для этих ключей; изменение во время выполнения
применяется собственной нормализацией плагина.
Рекомендации по учётной записи по умолчанию для каналов с несколькими учётными записями:
- Если настроены две или более записи `channels..accounts` без `channels..defaultAccount` или `accounts.default`, диагностика предупреждает, что резервная маршрутизация может выбрать неожиданную учётную запись.
- Если в `channels..defaultAccount` указан неизвестный идентификатор учётной записи, диагностика выводит предупреждение и перечисляет идентификаторы настроенных учётных записей.
Если вы вручную добавили `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/узла, с включённой удалённой отладкой и подтверждённым в браузере первым запросом согласия на подключение.
Проверка готовности здесь охватывает только предварительные требования для локального подключения. Режим Existing-session сохраняет текущие ограничения маршрутов Chrome MCP; для расширенных маршрутов, таких как `responsebody`, экспорт PDF, перехват загрузок и пакетные действия, по-прежнему требуется управляемый браузер или профиль с прямым CDP. Эта проверка не применяется к Docker, песочнице, удалённому браузеру и другим безголовым сценариям, которые продолжают использовать прямой CDP.
Если настроен профиль OAuth OpenAI Codex, doctor проверяет конечную точку авторизации OpenAI, чтобы убедиться, что локальный стек TLS Node/OpenSSL может проверить цепочку сертификатов. Если проверка завершается ошибкой сертификата (например, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, истёкший или самоподписанный сертификат), doctor выводит инструкции по устранению проблемы для конкретной платформы. В macOS с Node из Homebrew обычно помогает `brew postinstall ca-certificates`. При использовании `--deep` проверка выполняется, даже если gateway исправен.
Если вы ранее добавили устаревшие настройки транспорта OpenAI в `models.providers.openai-codex`, они могут перекрывать встроенный путь провайдера OAuth Codex. Doctor предупреждает, когда обнаруживает эти старые настройки транспорта вместе с OAuth Codex, чтобы вы могли удалить или переписать устаревшее переопределение транспорта и восстановить текущее поведение маршрутизации. Пользовательские прокси и переопределения только заголовков по-прежнему поддерживаются и не вызывают это предупреждение, однако созданные таким образом маршруты запросов не могут использоваться для неявного выбора Codex.
Doctor проверяет наличие устаревших ссылок на модели `openai-codex/*`. Нативная маршрутизация через среду Codex использует канонические ссылки на модели `openai/*`, однако один лишь префикс никогда не выбирает Codex. Если политика среды выполнения не задана или установлена в `auto`, подходит только точный официальный маршрут HTTPS Platform Responses или ChatGPT Responses без созданного пользователем переопределения запроса. См. [неявную среду выполнения агента OpenAI](/ru/providers/openai#implicit-agent-runtime).
В режиме `--fix` / `--repair` doctor переписывает затронутые ссылки агента по умолчанию и отдельных агентов, включая основные модели, резервные варианты, модели генерации изображений и видео, переопределения Heartbeat/субагентов/Compaction, перехватчики, переопределения моделей каналов и устаревшее сохранённое состояние маршрутов сеансов:
- `openai-codex/gpt-*` заменяется на `openai/gpt-*`.
- Намерение использовать Codex переносится в записи `agentRuntime.id: "codex"`, относящиеся к провайдеру и модели, для исправленных ссылок на модели агента.
- Устаревшая конфигурация среды выполнения всего агента и сохранённые закрепления среды выполнения сеанса удаляются, поскольку выбор среды выполнения определяется провайдером и моделью.
- Существующая политика среды выполнения для провайдера и модели сохраняется, если только исправленной устаревшей ссылке на модель не требуется маршрутизация Codex для сохранения прежнего пути аутентификации.
- Существующие списки резервных моделей сохраняются, а их устаревшие записи переписываются; скопированные настройки отдельных моделей переносятся из устаревшего ключа в канонический ключ `openai/*`.
- Сохранённые данные сеанса `modelProvider`/`providerOverride`, `model`/`modelOverride`, уведомления о переходе на резервный вариант и закрепления профилей аутентификации исправляются во всех обнаруженных хранилищах сеансов агентов.
- Doctor отдельно заменяет устаревшие закрепления `agentRuntime.id: "codex-cli"` (отдельный устаревший идентификатор среды выполнения) на `"codex"` в записях моделей `agents.defaults`, `agents.list[]` и `models.providers.*`.
- `/codex ...` означает «управлять нативным диалогом Codex из чата или привязать его».
- `/acp ...` или `runtime: "acp"` означает «использовать внешний адаптер ACP/acpx».
Doctor также сканирует обнаруженные хранилища сеансов агентов на наличие устаревшего автоматически созданного состояния маршрута после переноса настроенных моделей или среды выполнения с маршрута, принадлежащего плагину, например Codex.
`openclaw doctor --fix` может удалять автоматически созданное устаревшее состояние, включая закрепления моделей `modelOverrideSource: "auto"`, метаданные модели среды выполнения, закреплённые идентификаторы среды, привязки сеансов CLI и автоматические переопределения профиля аутентификации, когда соответствующий маршрут больше не настроен. Явно выбранные пользователем или устаревшие модели сеансов указываются для ручной проверки и остаются без изменений; переключите их с помощью `/model ...`, `/new` или сбросьте сеанс, если этот маршрут больше не нужен.
Doctor может перенести старые структуры на диске в текущую структуру:
- Хранилище сеансов и расшифровки: из `~/.openclaw/sessions/` в `~/.openclaw/agents//sessions/`
- Каталог агента: из `~/.openclaw/agent/` в `~/.openclaw/agents//agent/`
- Состояние аутентификации WhatsApp (Baileys): из устаревшего `~/.openclaw/credentials/*.json` (кроме `oauth.json`) в `~/.openclaw/credentials/whatsapp//...` (идентификатор учётной записи по умолчанию: `default`)
Эти миграции выполняются по мере возможности и идемпотентны; doctor выводит предупреждения, если оставляет какие-либо устаревшие каталоги в качестве резервных копий. Gateway/CLI также автоматически переносит устаревшие сеансы и каталог агента при запуске, чтобы история, данные аутентификации и модели оказались в каталоге соответствующего агента без ручного запуска doctor. Состояние аутентификации WhatsApp намеренно переносится только через `openclaw doctor`. При нормализации провайдера Talk и карты провайдеров используется структурное сравнение, поэтому различия только в порядке ключей больше не приводят к повторным изменениям `doctor --fix`, не оказывающим эффекта.
Doctor сканирует все манифесты установленных плагинов на наличие устаревших ключей возможностей верхнего уровня (`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`, если значение задано; задания объявлений сохраняют доставку в чат и получают `delivery.completionDestination`. Если `cron.webhook` не задан, неактивный маркер верхнего уровня `notify` удаляется для заданий без цели (существующая доставка, включая объявления, сохраняется), поскольку доставка во время выполнения никогда его не считывает.
Gateway также очищает некорректные строки Cron во время загрузки, чтобы допустимые задания продолжали выполняться. Исходные некорректные строки копируются в `jobs-quarantine.json` рядом с активным хранилищем перед удалением из `jobs.json`; doctor сообщает о помещённых в карантин строках, чтобы вы могли проверить или исправить их вручную.
При запуске Gateway нормализует представление среды выполнения и игнорирует маркер верхнего уровня `notify`, но оставляет сохранённую конфигурацию Cron для исправления через doctor. Если `cron.webhook` не задан, doctor удаляет неактивный маркер для заданий без цели миграции (`delivery.mode` отсутствует или имеет значение none, цель Webhook непригодна для использования либо уже настроена доставка объявлений/чата), не изменяя существующую доставку, поэтому повторные запуски `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` он автоматически удаляет блокировки, владельцы которых завершены, потеряны, повторно используют PID, имеют старые некорректные метаданные или не относятся к 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/...`, поскольку пути с синхронизацией могут замедлять ввод-вывод и вызывать конфликты блокировок и синхронизации.
- **Каталог состояния на SD или eMMC в Linux**: предупреждает, когда каталог состояния находится в источнике монтирования `mmcblk*`, поскольку произвольный ввод-вывод на SD/eMMC может быть медленнее, а накопитель — быстрее изнашиваться при записи сеансов и учётных данных.
- **Энергозависимый каталог состояния в Linux**: предупреждает, когда каталог состояния находится в `tmpfs` или `ramfs`, поскольку сеансы, учётные данные, конфигурация и состояние SQLite (с побочными файлами WAL/журнала) исчезают после перезагрузки. Монтирования Docker `overlay` намеренно не помечаются, поскольку их доступные для записи слои сохраняются после перезагрузки хоста, пока контейнер продолжает существовать.
- **Отсутствуют каталоги сеансов**: `sessions/` и каталог хранилища сеансов необходимы для сохранения истории и предотвращения сбоев `ENOENT`.
- **Несоответствие транскриптов**: предупреждает, когда у недавних записей сеансов отсутствуют файлы транскриптов.
- **«Однострочный JSONL» основного сеанса**: сообщает, когда основной транскрипт содержит только одну строку (история не накапливается).
- **Несколько каталогов состояния**: предупреждает, когда в домашних каталогах существует несколько папок `~/.openclaw` или когда `OPENCLAW_STATE_DIR` указывает в другое место (история может разделиться между установками).
- **Напоминание об удалённом режиме**: если `gateway.mode=remote`, doctor напоминает, что его нужно запустить на удалённом хосте (состояние хранится там).
- **Разрешения файла конфигурации**: предупреждает, если `~/.openclaw/openclaw.json` доступен для чтения группе или всем пользователям, и предлагает ужесточить разрешения до `600`.
Doctor проверяет профили OAuth в хранилище аутентификации, предупреждает об истекающих или истёкших токенах и может безопасно обновить их. Если профиль OAuth/токена Anthropic устарел, предлагается ключ API Anthropic или путь с токеном настройки Anthropic. Запросы на обновление появляются только при интерактивном запуске (TTY); `--non-interactive` пропускает попытки обновления.
Если обновление OAuth завершается окончательной ошибкой (например, `refresh_token_reused`, `invalid_grant` или провайдер требует снова выполнить вход), doctor сообщает о необходимости повторной аутентификации и выводит точную команду `openclaw models auth login --provider ...`, которую нужно выполнить.
Doctor также сообщает о профилях аутентификации, которые временно недоступны из-за коротких периодов ожидания (ограничения частоты запросов, тайм-ауты или ошибки аутентификации) либо более длительных отключений (ошибки оплаты или исчерпания средств).
Устаревшие профили OAuth Codex, токены которых хранятся в Связке ключей macOS (старый процесс первоначальной настройки до появления файловой схемы побочного хранилища), исправляются только с помощью doctor. Один раз запустите `openclaw doctor --fix` в интерактивном терминале, чтобы на месте перенести устаревшие токены из Связки ключей в `auth-profiles.json`; после этого встроенные обращения (Telegram, cron, запуск субагентов) разрешают их как канонические профили OAuth OpenAI.
Если задано `hooks.gmail.model`, doctor проверяет ссылку на модель по каталогу и списку разрешённых моделей и предупреждает, если она не разрешается или запрещена.
Когда изоляция в песочнице включена, doctor проверяет образы Docker и предлагает собрать образ или переключиться на устаревшие имена, если текущий образ отсутствует.
Doctor удаляет устаревшее промежуточное состояние зависимостей плагинов, созданное OpenClaw, в режиме `openclaw doctor --fix` / `openclaw doctor --repair`: устаревшие созданные корни зависимостей, старые каталоги этапов установки, локальные остатки пакетов от прежнего кода восстановления зависимостей встроенных плагинов, а также потерянные или восстановленные управляемые npm-копии встроенных плагинов `@openclaw/*`, которые могут перекрывать текущий встроенный манифест. Doctor также заново связывает пакет хоста `openclaw` с управляемыми npm-плагинами, объявляющими `peerDependencies.openclaw`, чтобы локальные импорты среды выполнения пакета, такие как `openclaw/plugin-sdk/*`, продолжали разрешаться после обновлений или восстановления npm.
Doctor также может переустановить отсутствующие загружаемые плагины, когда конфигурация ссылается на них, но локальный реестр плагинов не может их найти (существенные `plugins.entries`, настроенные параметры каналов, провайдеров или поиска, настроенные среды выполнения агентов). Во время обновления пакетов doctor не переустанавливает пакеты плагинов, пока заменяется основной пакет; после обновления снова запустите `openclaw doctor --fix`, если настроенный плагин по-прежнему требуется восстановить. За исключением описанного ниже запуска образа контейнера, запуск Gateway и перезагрузка конфигурации не выполняют восстановление пакетов; установка плагинов остаётся явной операцией doctor/install/update.
Для запуска контейнеризированного Gateway предусмотрено узкое исключение при обновлении: когда `openclaw gateway run` запускается с новой версией OpenClaw, перед переходом в состояние готовности он выполняет безопасные миграции состояния и существующее согласование плагинов после обновления ядра, а затем записывает контрольную точку для каждой версии. Этот этап запуска может очистить устаревшие записи встроенных плагинов, восстановить локальные ссылки на плагины, переустановить настроенные пакеты плагинов, если этого требует процесс согласования, и проверить активные данные плагинов. Если при запуске невозможно безопасно выполнить восстановление, один раз запустите тот же образ с `openclaw doctor --fix` для того же смонтированного состояния и конфигурации, прежде чем перезапускать контейнер в обычном режиме.
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 проверяет состояние сопряжения устройств в рамках обычной проверки работоспособности и сообщает о следующем:
- ожидающие запросы на первичное сопряжение
- ожидающие повышения роли или области разрешений для уже сопряжённых устройств
- исправления несоответствия открытого ключа, когда идентификатор устройства всё ещё совпадает, но идентичность устройства больше не соответствует одобренной записи
- записи сопряжения без активного токена для одобренной роли
- токены сопряжённых устройств, области разрешений которых вышли за пределы одобренной базовой конфигурации сопряжения
- локальные кэшированные записи токенов устройства для текущего компьютера, созданные до ротации токена на стороне Gateway или содержащие устаревшие метаданные областей разрешений
Doctor не одобряет запросы на сопряжение и не ротирует токены устройств автоматически. Он выводит точные дальнейшие действия:
- проверить ожидающие запросы с помощью `openclaw devices list`
- одобрить конкретный запрос с помощью `openclaw devices approve `
- создать новый токен с помощью ротации через `openclaw devices rotate --device --role `
- удалить и повторно одобрить устаревшую запись с помощью `openclaw devices remove `
Это позволяет отличить первичное сопряжение от ожидающих повышений роли или области разрешений и от расхождения устаревшего токена или идентичности устройства, устраняя распространённую ситуацию «устройство уже сопряжено, но требование сопряжения продолжает появляться».
Doctor выводит предупреждения, когда провайдер открыт для личных сообщений без списка разрешённых отправителей или когда политика настроена опасным образом.
При работе в качестве пользовательской службы systemd doctor обеспечивает включение сохранения пользовательского сеанса, чтобы Gateway продолжал работать после выхода пользователя.
Doctor выводит сводку состояния рабочей области для агента по умолчанию:
- **Состояние Skills**: подсчитывает подходящие Skills, Skills с невыполненными требованиями и Skills, заблокированные списком разрешений.
- **Состояние плагинов**: подсчитывает включённые, отключённые плагины и плагины с ошибками; перечисляет идентификаторы плагинов для всех ошибок; сообщает о возможностях плагинов комплекта.
- **Предупреждения о совместимости плагинов**: отмечает плагины с проблемами совместимости с текущей средой выполнения.
- **Диагностика плагинов**: показывает все предупреждения и ошибки времени загрузки, выданные реестром плагинов.
- **Восстановление TaskFlow**: показывает подозрительные управляемые TaskFlow, которые требуют ручной проверки или отмены.
Doctor проверяет, приближаются ли файлы начальной загрузки рабочей области (например, `AGENTS.md`, `CLAUDE.md` или другие внедряемые файлы контекста) к настроенному бюджету символов или превышают его. Для каждого файла он сообщает исходное и внедрённое количество символов, процент усечения, причину усечения (`max/file` или `max/total`) и общее количество внедрённых символов как долю общего бюджета. Когда файлы усечены или близки к пределу, doctor выводит рекомендации по настройке `agents.defaults.bootstrapMaxChars` и `agents.defaults.bootstrapTotalMaxChars`.
Doctor проверяет, установлено ли автодополнение по клавише табуляции для текущей командной оболочки (zsh, bash, fish или PowerShell):
- Если профиль командной оболочки использует медленную схему динамического автодополнения (`source <(openclaw completion ...)`), doctor обновляет её до более быстрого варианта с кэшированным файлом.
- Если автодополнение настроено в профиле, но файл кэша отсутствует, doctor автоматически создаёт кэш заново.
- Если автодополнение вообще не настроено, doctor предлагает установить его (только в интерактивном режиме; пропускается с `--non-interactive`).
Запустите `openclaw completion --write-state`, чтобы создать кэш заново вручную.
Когда `openclaw doctor --fix` удаляет отсутствующий плагин канала, он также удаляет оставшуюся конфигурацию области канала, которая ссылалась на этот плагин: записи `channels.`, цели Heartbeat с именем этого канала и переопределения `agents.*.models["/*"]`. Это предотвращает циклы загрузки Gateway, когда среда выполнения канала уже отсутствует, но конфигурация всё ещё требует от Gateway привязаться к нему.
Doctor проверяет готовность аутентификации локального Gateway по токену.
- Если для режима токена требуется токен, но его источник отсутствует, doctor предлагает создать токен.
- Если `gateway.auth.token` управляется через SecretRef, но недоступен, doctor предупреждает об этом и не заменяет его открытым текстом.
- `openclaw doctor --generate-gateway-token` принудительно создаёт токен, только если SecretRef токена не настроен.
Некоторым процессам восстановления требуется проверять настроенные учётные данные, не ослабляя поведение среды выполнения с немедленным завершением при ошибке.
- `openclaw doctor --fix` использует ту же модель сводки SecretRef только для чтения, что и команды семейства status, для целевого исправления конфигурации.
- Пример: исправление Telegram `allowFrom` / `groupAllowFrom` `@username` пытается использовать настроенные учетные данные бота, если они доступны.
- Если токен бота Telegram настроен через SecretRef, но недоступен в текущем пути выполнения команды, doctor сообщает, что учетные данные настроены, но недоступны, и пропускает автоматическое разрешение вместо аварийного завершения или ошибочного сообщения об отсутствии токена.
Doctor выполняет проверку работоспособности и предлагает перезапустить Gateway, если тот выглядит неработоспособным.
Doctor проверяет, готов ли настроенный поставщик эмбеддингов для поиска по памяти к работе с агентом по умолчанию. Поведение зависит от настроенных бэкенда и поставщика:
- **Бэкенд QMD**: проверяет доступность и возможность запуска исполняемого файла `qmd`. Если он недоступен, выводит рекомендации по исправлению, включая `npm install -g @tobilu/qmd` (или эквивалент для Bun), и вариант с указанием пути к исполняемому файлу вручную.
- **Явно заданный локальный поставщик**: проверяет наличие локального файла модели либо распознаваемого удаленного URL модели или URL для ее скачивания. Если он отсутствует, предлагает перейти на удаленного поставщика.
- **Явно заданный удаленный поставщик** (`openai`, `voyage` и т. д.): проверяет наличие ключа API в окружении или хранилище аутентификации. Если ключ отсутствует, выводит практические рекомендации по исправлению.
- **Устаревший автоматический поставщик**: рассматривает `memorySearch.provider: "auto"` как OpenAI, проверяет готовность OpenAI, а `doctor --fix` заменяет это значение на `provider: "openai"`.
Если доступен кэшированный результат проверки Gateway (Gateway был работоспособен на момент проверки), doctor сопоставляет его с конфигурацией, видимой через CLI, и отмечает любые расхождения. В стандартном пути doctor не запускает новую проверку эмбеддингов; для оперативной проверки поставщика используйте команду углубленной проверки состояния памяти.
Используйте `openclaw memory status --deep`, чтобы проверить готовность эмбеддингов во время выполнения.
Если 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. Doctor по-прежнему сообщает о работоспособности службы и выполняет исправления, не связанные со службой, но пропускает установку, запуск, перезапуск и начальную настройку службы, перезапись конфигурации супервизора и очистку устаревших служб, поскольку этим жизненным циклом управляет внешний супервизор.
- В Linux doctor не перезаписывает метаданные команды или точки входа, пока соответствующий модуль Gateway systemd активен. Кроме того, при поиске дублирующихся служб он игнорирует неактивные дополнительные модули, похожие на Gateway и не являющиеся устаревшими, чтобы сопутствующие файлы служб не создавали лишних сообщений об очистке.
- Если для аутентификации по токену требуется токен, а `gateway.auth.token` управляется через SecretRef, при установке или исправлении службы doctor проверяет SecretRef, но не сохраняет разрешенные значения токена в виде открытого текста в метаданных окружения службы супервизора.
- Doctor обнаруживает управляемые значения окружения службы, основанные на `.env`/SecretRef, которые старые установки LaunchAgent, systemd или Windows Scheduled Task встраивали непосредственно, и перезаписывает метаданные службы, чтобы эти значения загружались из источника среды выполнения, а не из определения супервизора.
- Doctor обнаруживает, когда команда службы после изменения `gateway.port` по-прежнему закрепляет старый `--port`, и перезаписывает метаданные службы, указывая текущий порт.
- Если для аутентификации по токену требуется токен, а настроенный SecretRef токена не разрешается, doctor блокирует установку или исправление и выводит практические рекомендации.
- Если настроены одновременно `gateway.auth.token` и `gateway.auth.password`, а `gateway.auth.mode` не задан, doctor блокирует установку или исправление до явного указания режима.
- Для пользовательских модулей 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` и т. д.). Bun не может открыть хранилище состояния OpenClaw `node:sqlite`, поэтому при исправлении устаревшие службы Bun переносятся на Node. Пути менеджеров версий могут перестать работать после обновлений, поскольку служба не загружает файл инициализации оболочки. Doctor предлагает перейти на системную установку Node, если она доступна (Homebrew/apt/choco).
Вновь установленные или исправленные LaunchAgent в macOS используют канонический системный 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`) и стабильные пользовательские каталоги исполняемых файлов, однако предполагаемые резервные каталоги менеджеров версий записываются в PATH службы только при их фактическом наличии на диске.
Doctor сохраняет все изменения конфигурации и записывает метаданные мастера, регистрируя запуск doctor.
Если система памяти рабочего пространства отсутствует, doctor предлагает ее настроить, а если рабочее пространство еще не находится под управлением git, выводит совет по резервному копированию.
Полное руководство по структуре рабочего пространства и резервному копированию с помощью git (рекомендуется приватный репозиторий GitHub или GitLab) см. в разделе [/concepts/agent-workspace](/ru/concepts/agent-workspace).
## Связанные материалы
- [Руководство по эксплуатации Gateway](/ru/gateway)
- [Устранение неполадок Gateway](/ru/gateway/troubleshooting)