Doctor

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

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

openclaw doctor

Автоматический режим / автоматизация

openclaw doctor --yes

Принимать значения по умолчанию без запроса подтверждения (включая перезапуск, восстановление сервиса и песочницы, когда применимо).

openclaw doctor --repair

Применять рекомендуемые исправления без запроса подтверждения (исправления и перезапуски, где это безопасно).

openclaw doctor --repair --force

Применять также агрессивные исправления (перезаписывает пользовательские конфигурации супервизора).

openclaw doctor --non-interactive

Запуск без запросов подтверждения, применяя только безопасные миграции (нормализация конфигурации и перемещение состояния на диске). Пропускает действия по перезапуску, сервису и песочнице, требующие подтверждения человека. Миграции устаревшего состояния выполняются автоматически при обнаружении.

openclaw doctor --deep

Сканировать системные сервисы на наличие дополнительных установок gateway (launchd/systemd/schtasks).

Если вы хотите проверить изменения перед записью, сначала откройте файл конфигурации:

cat ~/.openclaw/openclaw.json

Что делает команда (краткое описание)

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

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

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

Если это git-checkout и 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)

Эти миграции выполняются по принципу "лучшее усилие" и идемпотентны; doctor выдаст предупреждения, когда оставит какие-либо устаревшие папки в качестве резервных копий. Gateway/CLI также автоматически мигрирует устаревшие сессии и директорию агента при запуске, чтобы история/аутентификация/модели попали в путь для конкретного агента без ручного запуска doctor. Аутентификация WhatsApp намеренно мигрируется только через openclaw doctor.

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

Директория состояния — это операционный "ствол мозга". Если она исчезает, вы теряете сессии, учетные данные, логи и конфигурацию (если только у вас нет резервных копий где-то еще).

Doctor проверяет:

  • Отсутствующая директория состояния: предупреждает о катастрофической потере состояния, предлагает пересоздать директорию и напоминает, что восстановить отсутствующие данные невозможно.
  • Права доступа к директории состояния: проверяет возможность записи; предлагает восстановить права доступа (и выдает подсказку chown, когда обнаружено несоответствие владельца/группы).
  • Отсутствующие директории сессий: 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 также сообщает о профилях аутентификации, которые временно недоступны из-за:

  • кратковременного охлаждения (rate limits/таймауты/ошибки аутентификации)
  • более длительного отключения (сбои оплаты/кредита)

6) Валидация модели hooks

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

7) Восстановление образов песочницы

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

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

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

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

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

10) systemd linger (Linux)

Если запущен как пользовательский сервис systemd, doctor гарантирует, что lingering включен, чтобы gateway оставался активным после выхода из системы.

11) Статус навыков

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

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

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

13) Проверка здоровья Gateway и перезапуск

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

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

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

15) Аудит конфигурации супервизора и восстановление

Doctor проверяет установленную конфигурацию супервизора (launchd/systemd/schtasks) на отсутствующие или устаревшие значения по умолчанию (например, зависимости systemd network-online и задержку перезапуска). Когда обнаруживается несоответствие, он рекомендует обновление и может перезаписать файл сервиса/задачи на текущие значения по умолчанию.

Примечания:

  • openclaw doctor запрашивает подтверждение перед перезаписью конфигурации супервизора.
  • openclaw doctor --yes принимает запросы восстановления по умолчанию.
  • openclaw doctor --repair применяет рекомендуемые исправления без запросов.
  • openclaw doctor --repair --force перезаписывает пользовательские конфигурации супервизора.
  • Вы всегда можете принудительно выполнить полную перезапись через openclaw gateway install --force.

16) Диагностика среды выполнения Gateway и портов

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

17) Лучшие практики среды выполнения Gateway

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

18) Запись конфигурации и метаданные мастера

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

19) Советы по рабочей области (резервное копирование и система памяти)

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

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

← Назад к документации