---
read_when:
    - Додавання або зміна міграцій doctor
    - Запровадження несумісних змін конфігурації
summary: 'Команда doctor: перевірки стану, міграції конфігурації та кроки відновлення'
title: Doctor
x-i18n:
    generated_at: "2026-04-23T20:52:47Z"
    model: gpt-5.4
    provider: openai
    source_hash: 783ea62808bd3d4407d2c5981aaec63ada98e7d60cca9c0af297929a1a4d119a
    source_path: gateway/doctor.md
    workflow: 15
---

`openclaw doctor` — це інструмент відновлення + міграції для OpenClaw. Він виправляє застарілий
стан/конфігурацію, перевіряє здоров’я системи та надає практичні кроки відновлення.

## Швидкий старт

```bash
openclaw doctor
```

### Безголовий режим / автоматизація

```bash
openclaw doctor --yes
```

Приймати типові значення без запитів (включно з кроками перезапуску/служби/sandbox-відновлення, де це застосовно).

```bash
openclaw doctor --repair
```

Застосувати рекомендовані відновлення без запитів (відновлення + перезапуски там, де це безпечно).

```bash
openclaw doctor --repair --force
```

Застосувати також агресивні відновлення (перезаписує власні конфігурації supervisor).

```bash
openclaw doctor --non-interactive
```

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

```bash
openclaw doctor --deep
```

Сканувати системні служби на наявність додаткових встановлень gateway (launchd/systemd/schtasks).

Якщо ви хочете переглянути зміни перед записом, спочатку відкрийте файл конфігурації:

```bash
cat ~/.openclaw/openclaw.json
```

## Що це робить (коротко)

- Необов’язкове попереднє оновлення для git-встановлень (лише в інтерактивному режимі).
- Перевірка актуальності UI protocol (перебудовує Control UI, якщо схема protocol новіша).
- Перевірка здоров’я + запит на перезапуск.
- Підсумок стану Skills (доступні/відсутні/заблоковані) і стан Plugin.
- Нормалізація конфігурації для застарілих значень.
- Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.<provider>`.
- Перевірки міграції browser для застарілих конфігурацій Chrome extension і готовності Chrome MCP.
- Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- Попередження про затінення Codex OAuth (`models.providers.openai-codex`).
- Перевірка передумов OAuth TLS для профілів OpenAI Codex OAuth.
- Міграція застарілого стану на диску (сесії/каталог агента/автентифікація WhatsApp).
- Міграція ключів контрактів застарілого маніфесту Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- Міграція сховища застарілого Cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, payload `provider`, прості резервні завдання Webhook `notify: true`).
- Перевірка файлів блокування сесій і очищення застарілих блокувань.
- Перевірки цілісності стану та прав доступу (сесії, transcript, каталог стану).
- Перевірки прав доступу до файла конфігурації (`chmod 600`) під час локального запуску.
- Стан автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled для профілів автентифікації.
- Виявлення додаткового каталогу робочого простору (`~/openclaw`).
- Відновлення образу sandbox, коли sandboxing увімкнено.
- Міграція застарілих служб і виявлення додаткових gateway.
- Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`).
- Перевірки runtime Gateway (службу встановлено, але не запущено; кешований ярлик launchd).
- Попередження про стан каналу (визначаються через запущений gateway).
- Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим відновленням.
- Перевірки найкращих практик runtime Gateway (Node проти Bun, шляхи version manager).
- Діагностика конфліктів порту Gateway (типово `18789`).
- Попередження безпеки для відкритих політик особистих повідомлень.
- Перевірки автентифікації Gateway для режиму локального токена (пропонує генерацію токена, коли джерело токена відсутнє; не перезаписує конфігурації token SecretRef).
- Виявлення проблем із pairing пристроїв (очікувані перші запити на pairing, очікувані підвищення ролі/області дії, застаріле розходження локального кешу device-token і розходження автентифікації в paired-record).
- Перевірка systemd linger у Linux.
- Перевірка розміру bootstrap-файлів робочого простору (попередження про усікання/наближення до ліміту для файлів контексту).
- Перевірка стану shell completion та автоматичне встановлення/оновлення.
- Перевірка готовності провайдера embeddings для пошуку в пам’яті (локальна модель, віддалений API key або двійковий файл QMD).
- Перевірки source install (невідповідність pnpm workspace, відсутні ресурси UI, відсутній двійковий файл tsx).
- Записує оновлену конфігурацію + метадані wizard.

## Заповнення і скидання Dreams UI

Сцена Dreams у Control UI включає дії **Backfill**, **Reset** і **Clear Grounded**
для обґрунтованого процесу Dreaming. Ці дії використовують RPC-методи
в стилі doctor gateway, але вони **не** є частиною CLI
відновлення/міграції `openclaw doctor`.

Що вони роблять:

- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному
  робочому просторі, запускає обґрунтований прохід щоденника REM і записує зворотні записи backfill
  у `DREAMS.md`.
- **Reset** видаляє з `DREAMS.md` лише позначені записи щоденника backfill.
- **Clear Grounded** видаляє лише staged короткострокові записи лише з grounded,
  які походять з історичного повторного прогону і ще не накопичили live recall або щоденну
  підтримку.

Чого вони самі по собі **не** роблять:

- вони не редагують `MEMORY.md`
- вони не запускають повні міграції doctor
- вони не stage-ять автоматично grounded-кандидатів у live короткострокове
  сховище підвищення, якщо ви спершу явно не запустите staged CLI-шлях

Якщо ви хочете, щоб grounded історичний повторний прогін впливав на звичайну глибоку смугу
підвищення, використовуйте CLI-потік:

```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```

Це stage-ить grounded стійких кандидатів у короткострокове сховище Dreaming, водночас
залишаючи `DREAMS.md` поверхнею перегляду.

## Детальна поведінка та обґрунтування

### 0) Необов’язкове оновлення (git-встановлення)

Якщо це git checkout і doctor запущено в інтерактивному режимі, він пропонує
виконати оновлення (fetch/rebase/build) перед запуском doctor.

### 1) Нормалізація конфігурації

Якщо конфігурація містить застарілі форми значень (наприклад `messages.ackReaction`
без перевизначення для конкретного каналу), doctor нормалізує їх до поточної
схеми.

Це також включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це
`talk.provider` + `talk.providers.<provider>`. Doctor переписує старі форми
`talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` /
`talk.apiKey` у карту провайдерів.

### 2) Міграції застарілих ключів конфігурації

Коли конфігурація містить застарілі ключі, інші команди відмовляються працювати і просять
вас запустити `openclaw doctor`.

Doctor:

- Пояснить, які застарілі ключі було знайдено.
- Покажe міграцію, яку він застосував.
- Перезапише `~/.openclaw/openclaw.json` оновленою схемою.

Gateway також автоматично запускає міграції doctor під час старту, коли виявляє
застарілий формат конфігурації, тож застарілі конфігурації відновлюються без ручного втручання.
Міграції сховища завдань 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`
- `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>`
- `routing.agentToAgent` → `tools.agentToAgent`
- `routing.transcribeAudio` → `tools.media.audio.models`
- `messages.tts.<provider>` (`openai`/`elevenlabs`/`microsoft`/`edge`) → `messages.tts.providers.<provider>`
- `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.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 може зберегти наявну відповідну іменовану/типову ціль)
- `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`
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- видалити `browser.relayBindHost` (застаріле налаштування relay для extension)

Попередження doctor також включають вказівки щодо типового облікового запису для багатoоблікових каналів:

- Якщо налаштовано два або більше записів `channels.<channel>.accounts` без `channels.<channel>.defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис.
- Якщо `channels.<channel>.defaultAccount` установлено на невідомий ID облікового запису, doctor попереджає й перелічує ID налаштованих облікових записів.

### 2b) Перевизначення провайдера OpenCode

Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`,
це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`.
Це може примусово спрямувати моделі на неправильний API або обнулити вартість. Doctor попереджає про це, щоб ви
могли видалити перевизначення і відновити маршрутизацію API для кожної моделі + вартість.

### 2c) Міграція browser і готовність Chrome MCP

Якщо ваша конфігурація browser усе ще вказує на видалений шлях Chrome extension, doctor
нормалізує її до поточної моделі локального підключення до Chrome MCP на хості:

- `browser.profiles.*.driver: "extension"` стає `"existing-session"`
- `browser.relayBindHost` видаляється

Doctor також перевіряє локальний на хості шлях Chrome MCP, коли ви використовуєте `defaultProfile:
"user"` або налаштований профіль `existing-session`:

- перевіряє, чи встановлено Google Chrome на тому самому хості для типових
  профілів автопідключення
- перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144
- нагадує вам увімкнути remote debugging на сторінці inspect browser
  (наприклад `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging`,
  або `edge://inspect/#remote-debugging`)

Doctor не може увімкнути налаштування на боці Chrome за вас. Локальний на хості Chrome MCP
як і раніше вимагає:

- browser на основі Chromium 144+ на хості gateway/node
- локально запущений browser
- увімкнений remote debugging у цьому browser
- схвалення першого запиту на attach consent у browser

Готовність тут стосується лише передумов локального attach. Existing-session зберігає
поточні обмеження маршрутів Chrome MCP; просунуті маршрути, такі як `responsebody`, експорт PDF,
перехоплення завантажень і пакетні дії, як і раніше, потребують керованого
browser або сирого профілю CDP.

Ця перевірка **не** стосується Docker, sandbox, remote-browser або інших
headless-потоків. Вони й далі використовують сирий CDP.

### 2d) Передумови OAuth TLS

Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє кінцеву точку
авторизації OpenAI, щоб підтвердити, що локальний стек TLS Node/OpenSSL може
валідувати ланцюг сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад
`UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат),
doctor виводить платформо-специфічні вказівки з виправлення. На macOS з Node від Homebrew
виправленням зазвичай є `brew postinstall ca-certificates`. З `--deep` перевірка виконується
навіть якщо gateway працює нормально.

### 2c) Перевизначення провайдера Codex OAuth

Якщо ви раніше додали застарілі налаштування транспорту OpenAI у
`models.providers.openai-codex`, вони можуть затіняти вбудований шлях
провайдера Codex OAuth, який новіші випуски автоматично використовують. Doctor попереджає, коли бачить
ці старі налаштування транспорту поруч із Codex OAuth, щоб ви могли видалити або переписати
застаріле перевизначення транспорту й повернути вбудовану поведінку
маршрутизації/запасних варіантів. Власні проксі та перевизначення лише заголовків і далі підтримуються й не
викликають цього попередження.

### 3) Міграції застарілого стану (структура на диску)

Doctor може мігрувати старі структури на диску до поточної:

- Сховище сесій + transcript:
  - з `~/.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`. Нормалізація Talk provider/provider-map тепер
порівнює за структурною рівністю, тож відмінності лише в порядку ключів більше не спричиняють
повторних порожніх змін `doctor --fix`.

### 3a) Міграції застарілого маніфесту Plugin

Doctor сканує всі встановлені маніфести Plugin на наявність застарілих capability-ключів верхнього рівня
(`speechProviders`, `realtimeTranscriptionProviders`,
`realtimeVoiceProviders`, `mediaUnderstandingProviders`,
`imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`,
`webSearchProviders`). Коли їх знайдено, він пропонує перемістити їх до об’єкта `contracts`
і переписати файл маніфесту на місці. Ця міграція ідемпотентна;
якщо ключ `contracts` уже містить ті самі значення, застарілий ключ видаляється
без дублювання даних.

### 3b) Міграції застарілого сховища Cron

Doctor також перевіряє сховище завдань Cron (`~/.openclaw/cron/jobs.json` типово,
або `cron.store`, якщо перевизначено) на наявність старих форм завдань, які планувальник і далі
приймає заради сумісності.

Поточні очищення Cron включають:

- `jobId` → `id`
- `schedule.cron` → `schedule.expr`
- поля payload верхнього рівня (`message`, `model`, `thinking`, ...) → `payload`
- поля delivery верхнього рівня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
- псевдоніми доставки payload `provider` → явний `delivery.channel`
- прості застарілі резервні завдання Webhook `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook`

Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це
без зміни поведінки. Якщо завдання поєднує застарілий резервний варіант notify з уже наявним
режимом доставки не через webhook, doctor попереджає й залишає це завдання для ручного перегляду.

### 3c) Очищення блокувань сесій

Doctor сканує кожен каталог сесій агента на наявність застарілих файлів блокування запису — файлів, залишених
після аварійного завершення сесії. Для кожного знайденого файла блокування він повідомляє:
шлях, PID, чи PID ще живий, вік блокування та чи
вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair`
він автоматично видаляє застарілі файли блокування; інакше лише виводить примітку і
просить повторно запустити з `--fix`.

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

Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите
сесії, облікові дані, журнали та конфігурацію (якщо у вас немає резервних копій в іншому місці).

Doctor перевіряє:

- **Відсутній каталог стану**: попереджає про катастрофічну втрату стану, пропонує відтворити
  каталог і нагадує, що не може відновити відсутні дані.
- **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує відновити права
  (і виводить підказку `chown`, якщо виявлено невідповідність owner/group).
- **Cloud-synced каталог стану на macOS**: попереджає, коли стан визначається під iCloud Drive
  (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або
  `~/Library/CloudStorage/...`, оскільки шляхи на основі синхронізації можуть спричиняти повільніший I/O
  і гонки блокувань/синхронізації.
- **Каталог стану на Linux на SD або eMMC**: попереджає, коли стан визначається на джерелі монтування `mmcblk*`,
  оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношуватися
  під час запису сесій і облікових даних.
- **Відсутні каталоги сесій**: `sessions/` і каталог сховища сесій
  потрібні для збереження історії та уникнення збоїв `ENOENT`.
- **Невідповідність transcript**: попереджає, коли в нещодавніх записах сесій відсутні
  файли transcript.
- **Головна сесія “1-line JSONL”**: позначає випадок, коли головний transcript має лише один
  рядок (історія не накопичується).
- **Кілька каталогів стану**: попереджає, коли існує кілька тек `~/.openclaw` у різних
  домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує в інше місце (історія може
  розділятися між встановленнями).
- **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує вам запускати
  його на віддаленому хості (там і зберігається стан).
- **Права доступу до файла конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json`
  доступний для читання групі/усім і пропонує посилити права до `600`.

### 5) Стан автентифікації моделей (строк дії OAuth)

Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає, коли строк дії токенів
спливає/сплив, і може оновлювати їх, коли це безпечно. Якщо профіль Anthropic
OAuth/token застарів, він пропонує API key Anthropic або
шлях Anthropic setup-token.
Запити на оновлення з’являються лише в інтерактивному режимі (TTY); `--non-interactive`
пропускає спроби оновлення.

Коли оновлення OAuth остаточно не вдається (наприклад `refresh_token_reused`,
`invalid_grant` або коли провайдер повідомляє, що потрібно знову ввійти), doctor повідомляє,
що потрібна повторна автентифікація, і виводить точну команду `openclaw models auth login --provider ...`,
яку слід запустити.

Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні через:

- короткі cooldown (обмеження частоти/тайм-аути/збої автентифікації)
- довші вимкнення (помилки billing/credit)

### 6) Перевірка моделі Hooks

Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель за
каталогом і списком дозволу та попереджає, коли його не вдається визначити або воно заборонене.

### 7) Відновлення образу sandbox

Коли sandboxing увімкнено, doctor перевіряє образи Docker і пропонує зібрати їх або
перемкнутися на застарілі назви, якщо поточний образ відсутній.

### 7b) Runtime-залежності вбудованих Plugin

Doctor перевіряє runtime-залежності лише для вбудованих Plugin, які активні в
поточній конфігурації або ввімкнені типовим значенням у вбудованому маніфесті, наприклад
`plugins.entries.discord.enabled: true`, застарілий
`channels.discord.enabled: true` або вбудований провайдер, увімкнений за замовчуванням. Якщо будь-яких
залежностей бракує, doctor повідомляє про пакети й встановлює їх у режимі
`openclaw doctor --fix` / `openclaw doctor --repair`. Зовнішні Plugins, як і раніше,
використовують `openclaw plugins install` / `openclaw plugins update`; doctor не
встановлює залежності для довільних шляхів Plugin.

### 8) Міграції служб Gateway і підказки з очищення

Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і
пропонує видалити їх та встановити службу OpenClaw з використанням поточного порту gateway.
Він також може сканувати наявність додаткових gateway-подібних служб і виводити підказки з очищення.
Служби gateway OpenClaw з іменем профілю вважаються повноцінними і не
позначаються як "додаткові".

### 8b) Стартова міграція Matrix

Коли обліковий запис каналу Matrix має очікувану або придатну для дії міграцію застарілого стану,
doctor (у режимі `--fix` / `--repair`) створює знімок до міграції, а потім
запускає кроки best-effort міграції: міграцію застарілого стану Matrix і підготовку
застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки логуються, і
запуск триває. У режимі лише для читання (`openclaw doctor` без `--fix`) ця перевірка
повністю пропускається.

### 8c) Pairing пристроїв і дрейф автентифікації

Doctor тепер перевіряє стан pairing пристроїв як частину звичайної перевірки здоров’я.

Що він повідомляє:

- очікувані перші запити на pairing
- очікувані підвищення ролі для вже спарених пристроїв
- очікувані підвищення області дії для вже спарених пристроїв
- відновлення невідповідності публічного ключа, коли id пристрою ще збігається, але
  identity пристрою більше не збігається зі схваленим записом
- спарені записи, яким бракує активного токена для схваленої ролі
- спарені токени, області дії яких виходять за межі схваленого базового рівня pairing
- локальні кешовані записи device-token для поточної машини, які передують
  ротації токена на боці gateway або містять застарілі метадані області дії

Doctor не схвалює запити на pairing автоматично і не виконує автоматичну ротацію токенів пристроїв. Натомість
він виводить точні наступні кроки:

- переглянути очікувані запити через `openclaw devices list`
- схвалити точний запит через `openclaw devices approve <requestId>`
- повернути свіжий токен через `openclaw devices rotate --device <deviceId> --role <role>`
- видалити та повторно схвалити застарілий запис через `openclaw devices remove <deviceId>`

Це закриває поширену проблему "вже спарено, але все одно з’являється pairing required":
doctor тепер розрізняє перше pairing, очікувані підвищення ролі/області дії
та дрейф застарілого токена/identity пристрою.

### 9) Попередження безпеки

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

### 10) systemd linger (Linux)

Якщо запуск відбувається як служба користувача systemd, doctor переконується, що linger увімкнено, щоб
gateway залишався активним після виходу з системи.

### 11) Стан робочого простору (Skills, Plugins і застарілі каталоги)

Doctor виводить підсумок стану робочого простору для типового агента:

- **Стан Skills**: кількість доступних, з відсутніми вимогами та заблокованих списком дозволу Skills.
- **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору
  існують поруч із поточним робочим простором.
- **Стан Plugin**: кількість завантажених/вимкнених/помилкових Plugin; перелічує ID Plugin для будь-яких
  помилок; повідомляє про можливості bundle Plugin.
- **Попередження про сумісність Plugin**: позначає Plugins, які мають проблеми сумісності з
  поточним runtime.
- **Діагностика Plugin**: показує будь-які попередження або помилки під час завантаження, які видає
  реєстр Plugin.

### 11b) Розмір bootstrap-файлів

Doctor перевіряє, чи bootstrap-файли робочого простору (наприклад `AGENTS.md`,
`CLAUDE.md` або інші вставлені файли контексту) наближаються або перевищують налаштований
ліміт символів. Він повідомляє для кожного файла кількість сирих та вставлених символів, відсоток
усікання, причину усікання (`max/file` або `max/total`) і загальну кількість вставлених
символів як частку від загального бюджету. Коли файли усікаються або наближаються до ліміту,
doctor виводить поради з налаштування `agents.defaults.bootstrapMaxChars`
і `agents.defaults.bootstrapTotalMaxChars`.

### 11c) Shell completion

Doctor перевіряє, чи встановлено tab completion для поточної оболонки
(zsh, bash, fish або PowerShell):

- Якщо профіль оболонки використовує повільний динамічний шаблон completion
  (`source <(openclaw completion ...)`), doctor оновлює його до швидшого
  варіанта з кешованим файлом.
- Якщо completion налаштовано в профілі, але файл кешу відсутній,
  doctor автоматично відновлює кеш.
- Якщо completion взагалі не налаштовано, doctor пропонує встановити його
  (лише в інтерактивному режимі; пропускається з `--non-interactive`).

Запустіть `openclaw completion --write-state`, щоб вручну відновити кеш.

### 12) Перевірки автентифікації Gateway (локальний токен)

Doctor перевіряє готовність локальної автентифікації токеном для gateway.

- Якщо режим токена потребує токен, а джерело токена відсутнє, doctor пропонує згенерувати його.
- Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає і не перезаписує його відкритим текстом.
- `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано token SecretRef.

### 12b) Відновлення з урахуванням SecretRef у режимі лише для читання

Деякі потоки відновлення мають перевіряти налаштовані облікові дані, не послаблюючи при цьому поведінку fail-fast під час виконання.

- `openclaw doctor --fix` тепер використовує ту саму модель підсумку SecretRef лише для читання, що й команди сімейства status, для цільових відновлень конфігурації.
- Приклад: відновлення `allowFrom` / `groupAllowFrom` Telegram для `@username` намагається використати налаштовані облікові дані бота, якщо вони доступні.
- Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовано, але вони недоступні, і пропускає автоматичне визначення замість аварійного завершення або хибного повідомлення, що токен відсутній.

### 13) Перевірка здоров’я Gateway + перезапуск

Doctor запускає перевірку здоров’я і пропонує перезапустити gateway, якщо він
виглядає нездоровим.

### 13b) Готовність пошуку в пам’яті

Doctor перевіряє, чи готовий налаштований провайдер embeddings для пошуку в пам’яті
для типового агента. Поведінка залежить від налаштованого бекенда і провайдера:

- **Бекенд QMD**: перевіряє, чи доступний і чи може запускатися двійковий файл `qmd`.
  Якщо ні, виводить вказівки з виправлення, включно з npm-пакетом і варіантом ручного шляху до двійкового файла.
- **Явний локальний провайдер**: перевіряє наявність локального файла моделі або розпізнаного
  віддаленого URL моделі/URL для завантаження. Якщо відсутній, пропонує перейти на віддаленого провайдера.
- **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи присутній API key
  у середовищі або сховищі автентифікації. Якщо відсутній, виводить практичні вказівки з виправлення.
- **Автопровайдер**: спочатку перевіряє доступність локальної моделі, потім пробує кожного віддаленого
  провайдера в порядку автоматичного вибору.

Коли доступний результат перевірки gateway (gateway був здоровим на момент
перевірки), doctor звіряє його з видимою CLI конфігурацією і зазначає
будь-які розбіжності.

Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embeddings під час виконання.

### 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.
- Якщо автентифікація токеном потребує токен і `gateway.auth.token` керується через SecretRef, doctor під час встановлення/відновлення служби перевіряє SecretRef, але не зберігає визначені відкриті значення токенів у метадані середовища служби supervisor.
- Якщо автентифікація токеном потребує токен, а налаштований token SecretRef не визначено, doctor блокує шлях встановлення/відновлення і надає практичні вказівки.
- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не встановлено, doctor блокує встановлення/відновлення, доки режим не буде явно задано.
- Для Linux user-systemd units перевірки дрейфу токена в doctor тепер включають і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби.
- Ви завжди можете примусово виконати повне переписування через `openclaw gateway install --force`.

### 16) Діагностика runtime Gateway + портів

Doctor перевіряє runtime служби (PID, останній статус виходу) і попереджає, коли
службу встановлено, але вона фактично не запущена. Він також перевіряє конфлікти портів
на порту gateway (типово `18789`) і повідомляє ймовірні причини (gateway уже
працює, SSH tunnel).

### 17) Найкращі практики runtime Gateway

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

### 18) Запис конфігурації + метадані wizard

Doctor зберігає всі зміни конфігурації та ставить позначки в метаданих wizard, щоб зафіксувати
запуск doctor.

### 19) Поради щодо робочого простору (резервне копіювання + система пам’яті)

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

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