Перейти к основному содержанию

​
Доктор

openclaw doctor — это инструмент восстановления и миграции для OpenClaw. Он исправляет устаревший конфиг и состояние, проверяет здоровье системы и предоставляет конкретные шаги по исправлению.

​
Быстрый старт

openclaw doctor

​
Без интерфейса / автоматизация

openclaw doctor --yes
Принять значения по умолчанию без запросов (включая шаги по перезапуску/сервису/sandbox, когда применимо). 
openclaw doctor --repair
Применить рекомендуемые исправления без запросов (исправления + перезапуски, где это безопасно). 
openclaw doctor --repair --force
Применить также агрессивные исправления (перезаписывает пользовательские конфиги supervisor). 
openclaw doctor --non-interactive
Запуск без запросов и применение только безопасных миграций (нормализация конфига + перемещение состояния на диске). Пропускает действия перезапуска/сервиса/sandbox, требующие подтверждения человека. Миграции устаревшего состояния выполняются автоматически при обнаружении. 
openclaw doctor --deep
Сканировать системные сервисы на наличие дополнительных установок gateway (launchd/systemd/schtasks). Если вы хотите просмотреть изменения перед записью, сначала откройте файл конфига: 
cat ~/.openclaw/openclaw.json

​
Что делает (кратко)

  • Необязательное предварительное обновление для git-установок (только интерактивно).
  • Проверка актуальности UI-протокола (пересборка Control UI, когда схема протокола новее).
  • Проверка здоровья + предложение перезапуска.
  • Сводка статуса Skills (доступные/отсутствующие/заблокированные).
  • Нормализация конфига для устаревших значений.
  • Предупреждения о переопределениях провайдера OpenCode Zen (models.providers.opencode).
  • Миграция устаревшего состояния на диске (сеансы/директория агента/авторизация WhatsApp).
  • Проверки целостности состояния и прав доступа (сеансы, транскрипты, директория состояния).
  • Проверки прав доступа к файлу конфига (chmod 600) при локальном запуске.
  • Проверка здоровья аутентификации моделей: проверка истечения OAuth, возможность обновить истекающие токены, отчёт о cooldown/disabled состояниях профилей аутентификации.
  • Обнаружение дополнительных директорий рабочего пространства (~/openclaw).
  • Восстановление образов sandbox, когда sandboxing включён.
  • Миграция устаревших сервисов и обнаружение дополнительных gateway.
  • Проверки времени выполнения Gateway (сервис установлен, но не запущен; кэшированная метка launchd).
  • Предупреждения о статусе каналов (зондирование запущенного gateway).
  • Аудит конфига supervisor (launchd/systemd/schtasks) с возможным исправлением.
  • Проверки лучших практик времени выполнения Gateway (Node vs Bun, пути version-manager).
  • Диагностика конфликтов портов Gateway (по умолчанию 18789).
  • Предупреждения по безопасности для открытых политик личных сообщений.
  • Предупреждения об аутентификации Gateway, когда не задан gateway.auth.token (локальный режим; предлагается генерация токена).
  • Проверка systemd linger на Linux.
  • Проверки установок из исходников (несоответствие pnpm workspace, отсутствующие UI-ассеты, отсутствующий бинарник tsx).
  • Запись обновлённого конфига + метаданные мастера.

​
Подробное поведение и обоснование

​
0. Необязательное обновление (git-установки)

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

​
1. Нормализация конфига

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

​
2. Миграции устаревших ключей конфига

Когда конфиг содержит устаревшие ключи, другие команды отказываются запускаться и просят выполнить openclaw doctor. Doctor:
  • Объясняет, какие устаревшие ключи были найдены.
  • Показывает применённую миграцию.
  • Перезаписывает ~/.openclaw/openclaw.json с обновлённой схемой.
Gateway также автоматически запускает миграции doctor при старте, когда обнаруживает устаревший формат конфига, поэтому старые конфиги исправляются без ручного вмешательства. Текущие миграции:
  • 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
  • routing.queue → messages.queue
  • routing.bindings → верхнеуровневый bindings
  • routing.agents/routing.defaultAgentId → agents.list + agents.list[].default
  • routing.agentToAgent → tools.agentToAgent
  • routing.transcribeAudio → tools.media.audio.models
  • bindings[].match.accountID → bindings[].match.accountId
  • 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

​
2b) Переопределения провайдера OpenCode Zen

Если вы вручную добавили models.providers.opencode (или opencode-zen), он переопределяет встроенный каталог OpenCode Zen из @mariozechner/pi-ai. Это может принудительно направить все модели на один API или обнулить стоимость. Doctor выдаёт предупреждение, чтобы вы могли удалить переопределение и восстановить маршрутизацию API и стоимость для каждой модели.

​
3. Миграции устаревшего состояния (расположение на диске)

Doctor может мигрировать старые структуры на диске в текущую структуру:
  • Хранилище сеансов + транскрипты:
    • из ~/.openclaw/sessions/ в ~/.openclaw/agents/<agentId>/sessions/
  • Директория агента:
    • из ~/.openclaw/agent/ в ~/.openclaw/agents/<agentId>/agent/
  • Состояние авторизации WhatsApp (Baileys):
    • из устаревшего ~/.openclaw/credentials/*.json (кроме oauth.json)
    • в ~/.openclaw/credentials/whatsapp/<accountId>/... (id аккаунта по умолчанию: default)
Эти миграции выполняются по принципу best-effort и идемпотентны; doctor выдаёт предупреждения, когда оставляет какие-либо устаревшие папки в качестве резервных копий. Gateway/CLI также автоматически мигрирует устаревшие сеансы и директорию агента при старте, чтобы история, авторизация и модели попадали в путь для конкретного агента без ручного запуска doctor. Авторизация WhatsApp намеренно мигрируется только через openclaw doctor.

​
4. Проверки целостности состояния (сохранение сеансов, маршрутизация и безопасность)

Директория состояния — это операционный «ствол мозга». Если она исчезает, вы теряете сеансы, учётные данные, логи и конфиг (если у вас нет резервных копий в другом месте). Doctor проверяет:
  • Директория состояния отсутствует: предупреждает о катастрофической потере состояния, предлагает пересоздать директорию и напоминает, что восстановить отсутствующие данные невозможно.
  • Права доступа к директории состояния: проверяет возможность записи; предлагает исправить права (и выдаёт подсказку chown при обнаружении несоответствия owner/group).
  • Директории сеансов отсутствуют: sessions/ и директория хранилища сеансов необходимы для сохранения истории и предотвращения сбоев ENOENT.
  • Несоответствие транскриптов: предупреждает, когда у недавних записей сеансов отсутствуют файлы транскриптов.
  • Основной сеанс «1-строчный JSONL»: отмечает, когда основной транскрипт содержит только одну строку (история не накапливается).
  • Несколько директорий состояния: предупреждает, когда существует несколько папок ~/.openclaw в разных домашних директориях или когда OPENCLAW_STATE_DIR указывает в другое место (история может разделяться между установками).
  • Напоминание об удалённом режиме: если gateway.mode=remote, doctor напоминает запускать его на удалённом хосте (там хранится состояние).
  • Права доступа к файлу конфига: предупреждает, если ~/.openclaw/openclaw.json доступен для чтения группе/всем, и предлагает ужесточить до 600.

​
5. Проверка здоровья аутентификации моделей (истечение OAuth)

Doctor проверяет OAuth-профили в хранилище аутентификации, предупреждает о истекающих/истёкших токенах и может обновить их, когда это безопасно. Если профиль Anthropic Claude Code устарел, он предлагает выполнить claude setup-token (или вставить setup-token). Запросы на обновление появляются только при интерактивном запуске (TTY); --non-interactive пропускает попытки обновления. Doctor также сообщает о профилях аутентификации, которые временно недоступны из‑за:
  • коротких cooldown (rate limits/тайм-ауты/сбои аутентификации)
  • более длительных отключений (ошибки биллинга/кредита)

​
6. Валидация модели хуков

Если задан hooks.gmail.model, doctor проверяет ссылку на модель по каталогу и списку разрешённых и предупреждает, когда она не разрешается или запрещена.

​
7. Восстановление образов sandbox

Когда sandboxing включён, doctor проверяет Docker-образы и предлагает собрать или переключиться на устаревшие имена, если текущий образ отсутствует.

​
8. Миграции сервисов Gateway и подсказки по очистке

Doctor обнаруживает устаревшие сервисы gateway (launchd/systemd/schtasks) и предлагает удалить их и установить сервис OpenClaw, используя текущий порт gateway. Он также может сканировать наличие дополнительных gateway-подобных сервисов и выводить подсказки по очистке. Сервисы gateway OpenClaw с именами профилей считаются первоклассными и не помечаются как «лишние».

​
9. Предупреждения по безопасности

Doctor выдаёт предупреждения, когда провайдер открыт для личных сообщений без списка разрешённых, или когда политика настроена опасным образом.

​
10. systemd linger (Linux)

При запуске как пользовательский сервис systemd doctor убеждается, что linger включён, чтобы gateway продолжал работать после выхода из системы.

​
11. Статус Skills

Doctor выводит краткую сводку доступных/отсутствующих/заблокированных skills для текущего рабочего пространства.

​
12. Проверки аутентификации Gateway (локальный токен)

Doctor предупреждает, когда gateway.auth отсутствует на локальном gateway, и предлагает сгенерировать токен. Используйте openclaw doctor --generate-gateway-token, чтобы принудительно создать токен в автоматизации.

​
13. Проверка здоровья Gateway + перезапуск

Doctor выполняет проверку здоровья и предлагает перезапустить gateway, когда он выглядит нездоровым.

​
14. Предупреждения о статусе каналов

Если gateway здоров, doctor выполняет зондирование статуса каналов и сообщает предупреждения с предлагаемыми исправлениями.

​
15. Аудит и исправление конфига supervisor

Doctor проверяет установленный конфиг supervisor (launchd/systemd/schtasks) на наличие отсутствующих или устаревших значений по умолчанию (например, зависимости systemd network-online и задержку перезапуска). При обнаружении несоответствий он рекомендует обновление и может перезаписать файл сервиса/задачу до текущих значений по умолчанию. Примечания:
  • openclaw doctor запрашивает подтверждение перед перезаписью конфига supervisor.
  • openclaw doctor --yes принимает стандартные запросы на исправление.
  • openclaw doctor --repair применяет рекомендуемые исправления без запросов.
  • openclaw doctor --repair --force перезаписывает пользовательские конфиги supervisor.
  • Вы всегда можете принудительно выполнить полную перезапись через openclaw gateway install --force.

​
16. Диагностика времени выполнения Gateway и портов

Doctor проверяет время выполнения сервиса (PID, последний статус выхода) и предупреждает, когда сервис установлен, но фактически не запущен. Он также проверяет конфликты портов на порту gateway (по умолчанию 18789) и сообщает вероятные причины ( gateway уже запущен, SSH-туннель).

​
17. Лучшие практики времени выполнения Gateway

Doctor предупреждает, когда сервис gateway работает на Bun или на пути Node, управляемом version-manager (nvm, fnm, volta, asdf и т. д.). Каналы WhatsApp и Telegram требуют Node, а пути version-manager могут ломаться после обновлений, поскольку сервис не загружает инициализацию вашей оболочки. Doctor предлагает миграцию на системную установку Node, когда она доступна (Homebrew/apt/choco).

​
18. Запись конфига + метаданные мастера

Doctor сохраняет любые изменения конфига и проставляет метаданные мастера, фиксируя запуск doctor.

​
19. Подсказки по рабочему пространству (резервное копирование + система памяти)

Doctor предлагает систему памяти рабочего пространства, когда она отсутствует, и выводит подсказку по резервному копированию, если рабочее пространство ещё не находится под git. /concepts/agent-workspace для полного руководства по структуре рабочего пространства и резервному копированию через git (рекомендуется приватный GitHub или GitLab).