diff --git a/docs/uk/channels/whatsapp.md b/docs/uk/channels/whatsapp.md
index e7a4453c0..e4aed1e74 100644
--- a/docs/uk/channels/whatsapp.md
+++ b/docs/uk/channels/whatsapp.md
@@ -1,26 +1,26 @@
---
read_when:
- - Робота над поведінкою каналу WhatsApp/web або маршрутизацією вхідних повідомлень
-summary: Підтримка каналу WhatsApp, засоби контролю доступу, поведінка доставки та експлуатація
+ - Робота над поведінкою каналу WhatsApp/веб або маршрутизацією вхідних повідомлень
+summary: Підтримка каналу WhatsApp, засоби керування доступом, поведінка доставки та операції
title: WhatsApp
x-i18n:
- generated_at: "2026-04-30T02:42:22Z"
+ generated_at: "2026-05-01T21:50:43Z"
model: gpt-5.5
provider: openai
- source_hash: 5d0268e068de0001a11a6ed87fe70df8e685d1dcc87c8142ee5b3c77d7a727f3
+ source_hash: d97215e7f3ae30457e464b35177ad0b0b3631ef6d9b242eaab490eee76bf87f9
source_path: channels/whatsapp.md
workflow: 16
---
-Стан: готовий до продакшену через WhatsApp Web (`Baileys`). Gateway керує пов’язаними сеансами.
+Стан: production-ready через WhatsApp Web (Baileys). Gateway керує пов’язаними сеансами.
-## Встановлення (на вимогу)
+## Встановлення (за потреби)
- Онбординг (`openclaw onboard`) і `openclaw channels add --channel whatsapp`
- пропонують встановити Plugin WhatsApp під час першого вибору.
-- `openclaw channels login --channel whatsapp` також пропонує процес встановлення, коли
- Plugin ще відсутній.
-- Канал розробки + git checkout: типово використовує локальний шлях Plugin.
+ пропонують установити WhatsApp Plugin під час першого вибору.
+- `openclaw channels login --channel whatsapp` також пропонує потік установлення, коли
+ Plugin ще немає.
+- Канал розробки + git checkout: стандартно використовує локальний шлях Plugin.
- Stable/Beta: використовує npm-пакет `@openclaw/whatsapp`, коли актуальний пакет
опубліковано.
@@ -30,19 +30,19 @@ x-i18n:
openclaw plugins install @openclaw/whatsapp
```
-Якщо npm повідомляє, що пакет, яким володіє OpenClaw, застарілий або відсутній, використовуйте
-актуальну упаковану збірку OpenClaw або локальний checkout, доки черга npm-пакетів
-не наздожене зміни.
+Якщо npm повідомляє, що пакет, який належить OpenClaw, застарілий або відсутній, використайте
+актуальну пакетовану збірку OpenClaw або локальний checkout, доки ланцюг npm-пакетів
+не наздожене.
- Стандартна політика DM — сполучення для невідомих відправників.
+ Стандартна політика DM — pairing для невідомих відправників.
- Діагностика між каналами та інструкції з відновлення.
+ Міжканальна діагностика та інструкції з відновлення.
- Повні шаблони конфігурації каналів і приклади.
+ Повні шаблони й приклади конфігурації каналу.
@@ -102,13 +102,13 @@ openclaw pairing list whatsapp
openclaw pairing approve whatsapp
```
- Запити на сполучення спливають через 1 годину. Кількість очікуваних запитів обмежена 3 на канал.
+ Запити pairing спливають через 1 годину. Кількість очікуваних запитів обмежена 3 на канал.
-OpenClaw рекомендує за можливості запускати WhatsApp на окремому номері. (Метадані каналу та процес налаштування оптимізовані для такої схеми, але налаштування з особистим номером також підтримуються.)
+OpenClaw рекомендує за можливості запускати WhatsApp на окремому номері. (Метадані каналу й потік налаштування оптимізовані для такого варіанта, але налаштування з особистим номером також підтримуються.)
## Шаблони розгортання
@@ -118,8 +118,8 @@ OpenClaw рекомендує за можливості запускати Whats
Це найчистіший операційний режим:
- окрема ідентичність WhatsApp для OpenClaw
- - зрозуміліші allowlist DM і межі маршрутизації
- - нижча ймовірність плутанини із чатом із самим собою
+ - зрозуміліші allowlist для DM і межі маршрутизації
+ - нижча ймовірність плутанини із self-chat
Мінімальний шаблон політики:
@@ -137,20 +137,20 @@ OpenClaw рекомендує за можливості запускати Whats
- Онбординг підтримує режим особистого номера та записує базову конфігурацію, зручну для чату із самим собою:
+ Онбординг підтримує режим особистого номера та записує базову конфігурацію, зручну для self-chat:
- `dmPolicy: "allowlist"`
- `allowFrom` містить ваш особистий номер
- `selfChatMode: true`
- Під час виконання захисти для чату із самим собою спираються на пов’язаний власний номер і `allowFrom`.
+ Під час виконання захисти self-chat спираються на пов’язаний власний номер і `allowFrom`.
- Канал платформи обміну повідомленнями базується на WhatsApp Web (`Baileys`) у поточній архітектурі каналів OpenClaw.
+ Канал платформи повідомлень у поточній архітектурі каналів OpenClaw базується на WhatsApp Web (`Baileys`).
- У вбудованому реєстрі чат-каналів немає окремого каналу обміну повідомленнями Twilio WhatsApp.
+ У вбудованому реєстрі чат-каналів немає окремого каналу повідомлень Twilio WhatsApp.
@@ -158,22 +158,22 @@ OpenClaw рекомендує за можливості запускати Whats
## Модель виконання
- Gateway керує сокетом WhatsApp і циклом повторного підключення.
-- Watchdog повторного підключення використовує активність транспорту WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку, тому тихий сеанс пов’язаного пристрою не перезапускається лише через те, що останнім часом ніхто не надсилав повідомлень. Довший ліміт тиші застосунку все одно примусово виконує повторне підключення, якщо транспортні кадри продовжують надходити, але повідомлення застосунку не обробляються протягом вікна watchdog; після тимчасового повторного підключення для нещодавно активного сеансу ця перевірка тиші застосунку використовує звичайний тайм-аут повідомлень для першого вікна відновлення.
-- Таймінги сокета Baileys явно задаються в `web.whatsapp.*`: `keepAliveIntervalMs` керує ping-запитами застосунку WhatsApp Web, `connectTimeoutMs` керує тайм-аутом початкового handshake, а `defaultQueryTimeoutMs` керує тайм-аутами запитів Baileys.
+- Watchdog повторного підключення використовує активність транспорту WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку, тому тихий сеанс пов’язаного пристрою не перезапускається тільки через те, що нещодавно ніхто не надсилав повідомлень. Довший ліміт тиші застосунку все одно примусово виконує повторне підключення, якщо транспортні фрейми продовжують надходити, але повідомлення застосунку не обробляються протягом вікна watchdog; після тимчасового повторного підключення для нещодавно активного сеансу ця перевірка тиші застосунку використовує звичайний тайм-аут повідомлень для першого вікна відновлення.
+- Таймінги сокета Baileys явно задаються в `web.whatsapp.*`: `keepAliveIntervalMs` керує ping WhatsApp Web на рівні застосунку, `connectTimeoutMs` керує тайм-аутом початкового handshake, а `defaultQueryTimeoutMs` керує тайм-аутами запитів Baileys.
- Вихідні надсилання потребують активного слухача WhatsApp для цільового облікового запису.
-- Статусні та broadcast-чати ігноруються (`@status`, `@broadcast`).
-- Watchdog повторного підключення відстежує активність транспорту WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку: тихі сеанси пов’язаних пристроїв залишаються активними, доки транспортні кадри продовжують надходити, але зупинка транспорту примушує повторне підключення задовго до пізнішого шляху віддаленого від’єднання.
-- Прямі чати використовують правила сеансів DM (`session.dmScope`; типове значення `main` згортає DM до головного сеансу агента).
+- Чати статусів і broadcast ігноруються (`@status`, `@broadcast`).
+- Watchdog повторного підключення відстежує активність транспорту WhatsApp Web, а не лише обсяг вхідних повідомлень застосунку: тихі сеанси пов’язаних пристроїв залишаються активними, доки транспортні фрейми продовжують надходити, але зупинка транспорту примушує повторне підключення значно раніше за пізніший шлях віддаленого від’єднання.
+- Прямі чати використовують правила сеансу DM (`session.dmScope`; стандартне `main` зводить DM до головного сеансу агента).
- Групові сеанси ізольовані (`agent::whatsapp:group:`).
-- Транспорт WhatsApp Web поважає стандартні змінні середовища проксі на хості Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / варіанти в нижньому регістрі). Надавайте перевагу конфігурації проксі на рівні хоста над налаштуваннями проксі WhatsApp для окремого каналу.
-- Коли `messages.removeAckAfterReply` увімкнено, OpenClaw очищає реакцію підтвердження WhatsApp після доставки видимої відповіді.
+- Транспорт WhatsApp Web поважає стандартні змінні середовища проксі на хості Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / варіанти в нижньому регістрі). Надавайте перевагу конфігурації проксі на рівні хоста, а не специфічним для каналу налаштуванням проксі WhatsApp.
+- Коли ввімкнено `messages.removeAckAfterReply`, OpenClaw очищає ack-реакцію WhatsApp після доставлення видимої відповіді.
## Хуки Plugin і приватність
Вхідні повідомлення WhatsApp можуть містити особистий вміст повідомлень, номери телефонів,
-ідентифікатори груп, імена відправників і поля кореляції сеансів. З цієї причини
-WhatsApp не транслює вхідні payload хуків `message_received` до plugins,
-якщо ви явно не погодитеся:
+ідентифікатори груп, імена відправників і поля кореляції сеансу. З цієї причини
+WhatsApp не транслює вхідні payload хуків `message_received` до плагінів,
+якщо ви явно не ввімкнете це:
```json5
{
@@ -187,7 +187,7 @@ WhatsApp не транслює вхідні payload хуків `message_received
}
```
-Можна обмежити згоду одним обліковим записом:
+Можна обмежити opt-in одним обліковим записом:
```json5
{
@@ -205,8 +205,8 @@ WhatsApp не транслює вхідні payload хуків `message_received
}
```
-Увімкніть це лише для plugins, яким ви довіряєте отримувати вміст вхідних повідомлень
-WhatsApp та ідентифікатори.
+Увімкніть це лише для плагінів, яким ви довіряєте отримання вмісту та ідентифікаторів
+вхідних повідомлень WhatsApp.
## Контроль доступу й активація
@@ -214,84 +214,84 @@ WhatsApp та ідентифікатори.
`channels.whatsapp.dmPolicy` керує доступом до прямих чатів:
- - `pairing` (типово)
+ - `pairing` (стандартно)
- `allowlist`
- `open` (потребує, щоб `allowFrom` містив `"*"`)
- `disabled`
`allowFrom` приймає номери у стилі E.164 (нормалізуються внутрішньо).
- Перевизначення для кількох облікових записів: `channels.whatsapp.accounts..dmPolicy` (і `allowFrom`) мають пріоритет над типовими налаштуваннями рівня каналу для цього облікового запису.
+ Перевизначення для кількох облікових записів: `channels.whatsapp.accounts..dmPolicy` (і `allowFrom`) мають пріоритет над стандартами рівня каналу для цього облікового запису.
Деталі поведінки під час виконання:
- - сполучення зберігаються в allow-store каналу та об’єднуються з налаштованим `allowFrom`
- - якщо allowlist не налаштовано, зв’язаний власний номер дозволено за замовчуванням
- - OpenClaw ніколи автоматично не сполучає вихідні DM `fromMe` (повідомлення, які ви надсилаєте собі зі зв’язаного пристрою)
+ - pairing зберігаються в allow-store каналу та об’єднуються з налаштованим `allowFrom`
+ - якщо allowlist не налаштовано, пов’язаний власний номер дозволено стандартно
+ - OpenClaw ніколи автоматично не створює pairing для вихідних DM `fromMe` (повідомлень, які ви надсилаєте собі з пов’язаного пристрою)
-
+
Доступ до груп має два рівні:
1. **Allowlist членства в групах** (`channels.whatsapp.groups`)
- - якщо `groups` пропущено, придатні всі групи
+ - якщо `groups` пропущено, усі групи придатні
- якщо `groups` присутній, він діє як allowlist груп (`"*"` дозволено)
- 2. **Політика відправників групи** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`)
+ 2. **Політика відправників у групах** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`)
- `open`: allowlist відправників обходиться
- - `allowlist`: відправник має відповідати `groupAllowFrom` (або `*`)
- - `disabled`: блокує всі вхідні повідомлення груп
+ - `allowlist`: відправник має збігатися з `groupAllowFrom` (або `*`)
+ - `disabled`: блокувати всі вхідні повідомлення груп
- Резервний варіант allowlist відправників:
+ Fallback для allowlist відправників:
- якщо `groupAllowFrom` не задано, runtime повертається до `allowFrom`, коли він доступний
- - allowlists відправників оцінюються перед активацією за згадкою/відповіддю
+ - allowlist відправників оцінюються до активації згадкою/відповіддю
- Примітка: якщо блоку `channels.whatsapp` взагалі немає, резервна групова політика runtime — `allowlist` (із журналюванням попередження), навіть якщо `channels.defaults.groupPolicy` задано.
+ Примітка: якщо блок `channels.whatsapp` взагалі відсутній, fallback group-policy під час виконання — `allowlist` (із попередженням у журналі), навіть якщо задано `channels.defaults.groupPolicy`.
-
- Групові відповіді за замовчуванням потребують згадки.
+
+ Групові відповіді стандартно потребують згадки.
- Виявлення згадок охоплює:
+ Виявлення згадки охоплює:
- явні згадки WhatsApp ідентичності бота
- - налаштовані regex-шаблони згадок (`agents.list[].groupChat.mentionPatterns`, резервний варіант `messages.groupChat.mentionPatterns`)
+ - налаштовані regex-шаблони згадок (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
- транскрипти вхідних голосових нотаток для авторизованих групових повідомлень
- - неявне виявлення відповіді боту (відправник відповіді відповідає ідентичності бота)
+ - неявне виявлення відповіді боту (відправник відповіді збігається з ідентичністю бота)
- Примітка з безпеки:
+ Примітка щодо безпеки:
- цитата/відповідь лише задовольняє перевірку згадки; вона **не** надає авторизацію відправнику
- - з `groupPolicy: "allowlist"` відправники поза allowlist усе одно блокуються, навіть якщо вони відповідають на повідомлення користувача з allowlist
+ - з `groupPolicy: "allowlist"` відправники поза allowlist усе одно блокуються, навіть якщо відповідають на повідомлення користувача з allowlist
- Команда активації рівня сесії:
+ Команда активації на рівні сеансу:
- `/activation mention`
- `/activation always`
- `activation` оновлює стан сесії (не глобальну конфігурацію). Вона обмежена власником.
+ `activation` оновлює стан сеансу (не глобальну конфігурацію). Вона обмежена власником.
-## Поведінка особистого номера та чату із собою
+## Поведінка особистого номера й self-chat
-Коли зв’язаний власний номер також присутній у `allowFrom`, активуються запобіжники WhatsApp для чату із собою:
+Коли пов’язаний власний номер також присутній у `allowFrom`, активуються захисти self-chat WhatsApp:
-- пропускати сповіщення про прочитання для ходів чату із собою
-- ігнорувати поведінку автозапуску за mention-JID, яка інакше пінгувала б вас самих
-- якщо `messages.responsePrefix` не задано, відповіді в чаті із собою за замовчуванням мають формат `[{identity.name}]` або `[openclaw]`
+- пропускати read receipts для ходів self-chat
+- ігнорувати поведінку mention-JID auto-trigger, яка інакше ping-увала б вас самих
+- якщо `messages.responsePrefix` не задано, відповіді self-chat стандартно мають префікс `[{identity.name}]` або `[openclaw]`
## Нормалізація повідомлень і контекст
-
- Вхідні повідомлення WhatsApp обгортаються у спільний вхідний envelope.
+
+ Вхідні повідомлення WhatsApp обгортаються в спільний вхідний envelope.
- Якщо існує цитована відповідь, контекст додається в такій формі:
+ Якщо існує процитована відповідь, контекст додається в такій формі:
```text
[Replying to id:]
@@ -303,8 +303,8 @@ WhatsApp та ідентифікатори.
-
- Вхідні повідомлення лише з медіа нормалізуються з плейсхолдерами, як-от:
+
+ Вхідні повідомлення лише з медіа нормалізуються з placeholders, як-от:
- ``
- ``
@@ -313,20 +313,20 @@ WhatsApp та ідентифікатори.
- ``
Авторизовані групові голосові нотатки транскрибуються перед перевіркою згадки, коли
- тіло містить лише ``, тож промовлена згадка бота в голосовій нотатці може
- запустити відповідь. Якщо транскрипт усе одно не згадує бота, він
- зберігається в очікуваній історії групи замість сирого плейсхолдера.
+ тіло містить лише ``, тому згадка бота, сказана в голосовій нотатці, може
+ запустити відповідь. Якщо транскрипт усе ще не згадує бота, його
+ зберігають в очікуваній історії групи замість сирого placeholder.
- Тіла місцезнаходження використовують стислий текст координат. Мітки/коментарі місцезнаходження та дані контакту/vCard відтворюються як fenced ненадійні метадані, а не як вбудований текст промпта.
+ Тіла локацій використовують стислий текст координат. Мітки/коментарі локацій і дані контактів/vCard відображаються як fenced untrusted metadata, а не як inline prompt text.
-
- Для груп необроблені повідомлення можуть буферизуватися та вставлятися як контекст, коли бот нарешті запускається.
+
+ Для груп необроблені повідомлення можуть буферизуватися й додаватися як контекст, коли бот нарешті спрацьовує.
- - типовий ліміт: `50`
+ - стандартний ліміт: `50`
- конфігурація: `channels.whatsapp.historyLimit`
- - резервний варіант: `messages.groupChat.historyLimit`
+ - fallback: `messages.groupChat.historyLimit`
- `0` вимикає
Маркери вставлення:
@@ -336,8 +336,8 @@ WhatsApp та ідентифікатори.
-
- Сповіщення про прочитання ввімкнені за замовчуванням для прийнятих вхідних повідомлень WhatsApp.
+
+ Read receipts стандартно ввімкнені для прийнятих вхідних повідомлень WhatsApp.
Вимкнути глобально:
@@ -351,7 +351,7 @@ WhatsApp та ідентифікатори.
}
```
- Перевизначення для окремого облікового запису:
+ Перевизначення для облікового запису:
```json5
{
@@ -367,56 +367,56 @@ WhatsApp та ідентифікатори.
}
```
- Ходи чату із собою пропускають сповіщення про прочитання, навіть коли вони ввімкнені глобально.
+ Ходи self-chat пропускають read receipts, навіть коли їх глобально ввімкнено.
-## Доставка, поділ на фрагменти та медіа
+## Доставлення, chunking і медіа
-
- - типовий ліміт фрагмента: `channels.whatsapp.textChunkLimit = 4000`
+
+ - стандартний ліміт chunk: `channels.whatsapp.textChunkLimit = 4000`
- `channels.whatsapp.chunkMode = "length" | "newline"`
- - режим `newline` віддає перевагу межам абзаців (порожнім рядкам), а потім повертається до безпечного за довжиною поділу на фрагменти
+ - режим `newline` надає перевагу межам абзаців (порожнім рядкам), а потім переходить до chunking, безпечного за довжиною
- - підтримує зображення, відео, аудіо (голосову нотатку PTT) і документи
- - аудіомедіа надсилаються через payload Baileys `audio` з `ptt: true`, тому клієнти WhatsApp відображають їх як голосову нотатку push-to-talk
- - payload відповідей зберігає `audioAsVoice`; вихід голосових нотаток TTS для WhatsApp лишається на цьому шляху PTT, навіть коли провайдер повертає MP3 або WebM
+ - підтримує зображення, відео, аудіо (голосову нотатку PTT) і документні payloads
+ - аудіомедіа надсилається через Baileys `audio` payload з `ptt: true`, тому клієнти WhatsApp відображають його як голосову нотатку push-to-talk
+ - payloads відповідей зберігають `audioAsVoice`; вивід голосової нотатки TTS для WhatsApp залишається на цьому PTT-шляху, навіть коли провайдер повертає MP3 або WebM
- нативне аудіо Ogg/Opus надсилається як `audio/ogg; codecs=opus` для сумісності з голосовими нотатками
- - аудіо не в Ogg, зокрема вихід Microsoft Edge TTS MP3/WebM, транскодується за допомогою `ffmpeg` у моно Ogg/Opus 48 кГц перед доставкою PTT
- - `/tts latest` надсилає останню відповідь асистента як одну голосову нотатку й запобігає повторному надсиланню тієї самої відповіді; `/tts chat on|off|default` керує автоматичним TTS для поточного чату WhatsApp
+ - аудіо не у форматі Ogg, зокрема вивід Microsoft Edge TTS MP3/WebM, транскодується за допомогою `ffmpeg` у моно Ogg/Opus 48 кГц перед доставкою PTT
+ - `/tts latest` надсилає останню відповідь асистента як одну голосову нотатку й пригнічує повторні надсилання тієї самої відповіді; `/tts chat on|off|default` керує auto-TTS для поточного чату WhatsApp
- відтворення анімованих GIF підтримується через `gifPlayback: true` під час надсилання відео
- - підписи застосовуються до першого медіаелемента під час надсилання payload відповідей із кількома медіа, але голосові нотатки PTT надсилають спочатку аудіо, а видимий текст окремо, оскільки клієнти WhatsApp не відображають підписи голосових нотаток стабільно
- - джерелом медіа може бути HTTP(S), `file://` або локальні шляхи
+ - підписи застосовуються до першого медіаелемента під час надсилання payloads відповідей із кількома медіа, крім голосових нотаток PTT: вони надсилають аудіо спочатку, а видимий текст окремо, бо клієнти WhatsApp не завжди стабільно відображають підписи до голосових нотаток
+ - джерело медіа може бути HTTP(S), `file://` або локальними шляхами
- - ліміт збереження вхідних медіа: `channels.whatsapp.mediaMaxMb` (за замовчуванням `50`)
- - ліміт надсилання вихідних медіа: `channels.whatsapp.mediaMaxMb` (за замовчуванням `50`)
+ - обмеження збереження вхідних медіа: `channels.whatsapp.mediaMaxMb` (типово `50`)
+ - обмеження надсилання вихідних медіа: `channels.whatsapp.mediaMaxMb` (типово `50`)
- перевизначення для окремого облікового запису використовують `channels.whatsapp.accounts..mediaMaxMb`
- - зображення автоматично оптимізуються (зміна розміру/перебирання якості), щоб укластися в ліміти
- - у разі помилки надсилання медіа fallback для першого елемента надсилає текстове попередження замість тихого відкидання відповіді
+ - зображення автоматично оптимізуються (зміна розміру/підбір якості), щоб уміститися в обмеження
+ - у разі помилки надсилання медіа fallback для першого елемента надсилає текстове попередження, а не мовчки відкидає відповідь
-## Цитування відповідей
+## Цитування відповіді
-WhatsApp підтримує нативне цитування відповідей, коли вихідні відповіді видимо цитують вхідне повідомлення. Керуйте ним за допомогою `channels.whatsapp.replyToMode`.
+WhatsApp підтримує нативне цитування відповідей, коли вихідні відповіді видимо цитують вхідне повідомлення. Керуйте цим за допомогою `channels.whatsapp.replyToMode`.
-| Значення | Поведінка |
-| ----------- | --------------------------------------------------------------------- |
-| `"off"` | Ніколи не цитувати; надсилати як звичайне повідомлення |
-| `"first"` | Цитувати лише перший фрагмент вихідної відповіді |
-| `"all"` | Цитувати кожен фрагмент вихідної відповіді |
-| `"batched"` | Цитувати відповіді в черзі, залишаючи негайні відповіді без цитування |
+| Значення | Поведінка |
+| ----------- | ------------------------------------------------------------------- |
+| `"off"` | Ніколи не цитувати; надсилати як звичайне повідомлення |
+| `"first"` | Цитувати лише перший фрагмент вихідної відповіді |
+| `"all"` | Цитувати кожен фрагмент вихідної відповіді |
+| `"batched"` | Цитувати поставлені в чергу пакетні відповіді, залишаючи негайні відповіді без цитування |
-За замовчуванням `"off"`. Перевизначення для окремого облікового запису використовують `channels.whatsapp.accounts..replyToMode`.
+Типове значення — `"off"`. Перевизначення для окремого облікового запису використовують `channels.whatsapp.accounts..replyToMode`.
```json5
{
@@ -430,16 +430,16 @@ WhatsApp підтримує нативне цитування відповіде
## Рівень реакцій
-`channels.whatsapp.reactionLevel` керує тим, наскільки широко агент використовує емодзі-реакції у WhatsApp:
+`channels.whatsapp.reactionLevel` керує тим, наскільки широко агент використовує emoji-реакції в WhatsApp:
-| Рівень | Ack-реакції | Реакції, ініційовані агентом | Опис |
-| ------------- | ----------- | ---------------------------- | ------------------------------------------------ |
-| `"off"` | Ні | Ні | Жодних реакцій |
-| `"ack"` | Так | Ні | Лише Ack-реакції (підтвердження перед відповіддю) |
-| `"minimal"` | Так | Так (обережно) | Ack + реакції агента з обережними вказівками |
-| `"extensive"` | Так | Так (заохочується) | Ack + реакції агента із заохочувальними вказівками |
+| Рівень | Реакції підтвердження | Реакції, ініційовані агентом | Опис |
+| ------------ | --------------------- | ---------------------------- | ------------------------------------------------------ |
+| `"off"` | Ні | Ні | Без реакцій узагалі |
+| `"ack"` | Так | Ні | Лише реакції підтвердження (підтвердження отримання перед відповіддю) |
+| `"minimal"` | Так | Так (консервативно) | Підтвердження + реакції агента з консервативними вказівками |
+| `"extensive"` | Так | Так (заохочується) | Підтвердження + реакції агента із заохочувальними вказівками |
-За замовчуванням: `"minimal"`.
+Типово: `"minimal"`.
Перевизначення для окремого облікового запису використовують `channels.whatsapp.accounts..reactionLevel`.
@@ -455,8 +455,8 @@ WhatsApp підтримує нативне цитування відповіде
## Реакції підтвердження
-WhatsApp підтримує негайні Ack-реакції під час отримання вхідного повідомлення через `channels.whatsapp.ackReaction`.
-Ack-реакції обмежуються `reactionLevel` — вони пригнічуються, коли `reactionLevel` має значення `"off"`.
+WhatsApp підтримує негайні реакції підтвердження на отримання вхідного повідомлення через `channels.whatsapp.ackReaction`.
+Реакції підтвердження обмежуються `reactionLevel` — вони пригнічуються, коли `reactionLevel` дорівнює `"off"`.
```json5
{
@@ -475,31 +475,33 @@ Ack-реакції обмежуються `reactionLevel` — вони приг
Нотатки щодо поведінки:
- надсилаються негайно після прийняття вхідного повідомлення (перед відповіддю)
-- помилки записуються в журнал, але не блокують звичайну доставку відповіді
-- режим групи `mentions` реагує на звернення, спричинені згадкою; активація групи `always` діє як обхід цієї перевірки
+- помилки журналюються, але не блокують звичайну доставку відповіді
+- груповий режим `mentions` реагує на ходи, запущені згадкою; групова активація `always` діє як обхід цієї перевірки
- WhatsApp використовує `channels.whatsapp.ackReaction` (застарілий `messages.ackReaction` тут не використовується)
## Кілька облікових записів і облікові дані
-
+
- ідентифікатори облікових записів беруться з `channels.whatsapp.accounts`
- - вибір облікового запису за замовчуванням: `default`, якщо він присутній, інакше перший налаштований ідентифікатор облікового запису (відсортований)
- - ідентифікатори облікових записів нормалізуються внутрішньо для пошуку
+ - типовий вибір облікового запису: `default`, якщо він є, інакше перший налаштований ідентифікатор облікового запису (відсортовано)
+ - ідентифікатори облікових записів внутрішньо нормалізуються для пошуку
-
+
- поточний шлях автентифікації: `~/.openclaw/credentials/whatsapp//creds.json`
- файл резервної копії: `creds.json.bak`
- - застаріла автентифікація за замовчуванням у `~/.openclaw/credentials/` досі розпізнається/мігрується для потоків облікового запису за замовчуванням
+ - застаріла типова автентифікація в `~/.openclaw/credentials/` усе ще розпізнається/мігрується для потоків типового облікового запису
`openclaw channels logout --channel whatsapp [--account ]` очищає стан автентифікації WhatsApp для цього облікового запису.
- У застарілих каталогах автентифікації `oauth.json` зберігається, тоді як файли автентифікації Baileys видаляються.
+ Коли Gateway доступний, вихід спочатку зупиняє активний слухач WhatsApp для вибраного облікового запису, щоб пов’язана сесія не продовжувала отримувати повідомлення до наступного перезапуску. `openclaw channels remove --channel whatsapp` також зупиняє активний слухач перед вимкненням або видаленням конфігурації облікового запису.
+
+ У застарілих каталогах автентифікації `oauth.json` зберігається, а файли автентифікації Baileys видаляються.
@@ -507,16 +509,16 @@ Ack-реакції обмежуються `reactionLevel` — вони приг
## Інструменти, дії та записи конфігурації
- Підтримка інструментів агента включає дію реакції WhatsApp (`react`).
-- Обмеження дій:
+- Обмежувачі дій:
- `channels.whatsapp.actions.reactions`
- `channels.whatsapp.actions.polls`
-- Записи конфігурації, ініційовані каналом, увімкнені за замовчуванням (вимкнення через `channels.whatsapp.configWrites=false`).
+- Записи конфігурації, ініційовані каналом, увімкнені типово (вимкніть через `channels.whatsapp.configWrites=false`).
## Усунення несправностей
-
- Симптом: стан каналу повідомляє, що його не прив’язано.
+
+ Симптом: статус каналу повідомляє, що його не пов’язано.
Виправлення:
@@ -527,16 +529,16 @@ Ack-реакції обмежуються `reactionLevel` — вони приг
-
- Симптом: прив’язаний обліковий запис із повторними від’єднаннями або спробами повторного підключення.
+
+ Симптом: пов’язаний обліковий запис із повторними від’єднаннями або спробами повторного підключення.
- Тихі облікові записи можуть залишатися підключеними після звичайного таймауту повідомлень; watchdog
- перезапускається, коли транспортна активність WhatsApp Web зупиняється, сокет закривається або
- активність на рівні застосунку лишається бездіяльною довше за подовжене безпечне вікно.
+ Тихі облікові записи можуть залишатися підключеними після звичайного тайм-ауту повідомлень; watchdog
+ перезапускається, коли активність транспорту WhatsApp Web припиняється, сокет закривається або
+ активність на рівні застосунку залишається тихою довше за довше безпечне вікно.
- Якщо журнали показують повторюване `status=408 Request Time-out Connection was lost`, налаштуйте
+ Якщо журнали показують повторювані `status=408 Request Time-out Connection was lost`, налаштуйте
таймінги сокета Baileys у `web.whatsapp`. Почніть зі скорочення
- `keepAliveIntervalMs` нижче таймауту простою вашої мережі та збільшення
+ `keepAliveIntervalMs` нижче за тайм-аут простою вашої мережі та збільшення
`connectTimeoutMs` на повільних або нестабільних з’єднаннях:
```json5
@@ -558,79 +560,87 @@ Ack-реакції обмежуються `reactionLevel` — вони приг
openclaw logs --follow
```
- За потреби повторно прив’яжіть через `channels login`.
+ Якщо `~/.openclaw/logs/whatsapp-health.log` повідомляє `Gateway inactive`, але
+ `openclaw gateway status` і `openclaw channels status --probe` показують, що
+ Gateway і WhatsApp справні, запустіть `openclaw doctor`. У Linux doctor
+ попереджає про застарілі записи crontab, які досі викликають
+ `~/.openclaw/bin/ensure-whatsapp.sh`; видаліть ці застарілі записи за допомогою
+ `crontab -e`, бо cron може не мати середовища користувацької шини systemd і
+ змушувати цей старий скрипт неправильно повідомляти про стан Gateway.
+
+ За потреби повторно пов’яжіть за допомогою `channels login`.
-
- Симптом: `openclaw channels login --channel whatsapp` завершується помилкою до показу придатного QR-коду з `status=408 Request Time-out` або розривом TLS-сокета.
+
+ Симптом: `openclaw channels login --channel whatsapp` завершується помилкою до показу придатного QR-коду з `status=408 Request Time-out` або від’єднанням TLS-сокета.
- Вхід у WhatsApp Web використовує стандартне проксі-середовище хоста gateway (`HTTPS_PROXY`, `HTTP_PROXY`, варіанти в нижньому регістрі та `NO_PROXY`). Переконайтеся, що процес gateway успадковує env проксі та що `NO_PROXY` не збігається з `mmg.whatsapp.net`.
+ Вхід у WhatsApp Web використовує стандартне проксі-середовище хоста Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, варіанти в нижньому регістрі та `NO_PROXY`). Перевірте, що процес Gateway успадковує env проксі й що `NO_PROXY` не збігається з `mmg.whatsapp.net`.
- Вихідне надсилання швидко завершується помилкою, коли для цільового облікового запису немає активного слухача gateway.
+ Вихідні надсилання швидко завершуються помилкою, коли для цільового облікового запису немає активного слухача Gateway.
- Переконайтеся, що gateway запущено й обліковий запис прив’язано.
+ Переконайтеся, що Gateway запущено, а обліковий запис пов’язано.
-
- Рядки транскрипту записують те, що згенерував агент. Доставка WhatsApp перевіряється окремо: OpenClaw вважає автоматичну відповідь надісланою лише після того, як Baileys повертає ідентифікатор вихідного повідомлення принаймні для одного видимого тексту або медіанадсилання.
+
+ Рядки транскрипта записують те, що згенерував агент. Доставка WhatsApp перевіряється окремо: OpenClaw вважає автоматичну відповідь надісланою лише після того, як Baileys поверне ідентифікатор вихідного повідомлення принаймні для одного видимого текстового або медіанадсилання.
- Ack-реакції є незалежними підтвердженнями перед відповіддю. Успішна реакція не доводить, що пізнішу текстову або медіавідповідь було прийнято WhatsApp.
+ Реакції підтвердження є незалежними підтвердженнями отримання перед відповіддю. Успішна реакція не доводить, що пізнішу текстову або медіавідповідь було прийнято WhatsApp.
- Перевірте журнали gateway на `auto-reply delivery failed` або `auto-reply was not accepted by WhatsApp provider`.
+ Перевірте журнали Gateway на `auto-reply delivery failed` або `auto-reply was not accepted by WhatsApp provider`.
-
- Перевіряйте в такому порядку:
+
+ Перевірте в такому порядку:
- `groupPolicy`
- `groupAllowFrom` / `allowFrom`
- записи allowlist у `groups`
- - обмеження згадками (`requireMention` + шаблони згадок)
- - дублікати ключів у `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому тримайте один `groupPolicy` для кожної області
+ - обмеження за згадкою (`requireMention` + шаблони згадок)
+ - дублікати ключів в `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому зберігайте один `groupPolicy` для кожної області
- Середовище виконання gateway WhatsApp має використовувати Node. Bun позначено як несумісний для стабільної роботи gateway WhatsApp/Telegram.
+ Середовище виконання WhatsApp gateway має використовувати Node. Bun позначено як несумісний зі стабільною роботою WhatsApp/Telegram gateway.
-## Системні промпти
+## Системні prompts
-WhatsApp підтримує системні промпти в стилі Telegram для груп і прямих чатів через мапи `groups` і `direct`.
+WhatsApp підтримує системні prompts у стилі Telegram для груп і прямих чатів через мапи `groups` і `direct`.
-Ієрархія вирішення для групових повідомлень:
+Ієрархія розв’язання для групових повідомлень:
-Ефективна мапа `groups` визначається першою: якщо обліковий запис визначає власну `groups`, вона повністю замінює кореневу мапу `groups` (без глибокого злиття). Потім пошук промпта виконується на отриманій єдиній мапі:
+Ефективна мапа `groups` визначається спочатку: якщо обліковий запис визначає власні `groups`, вона повністю замінює кореневу мапу `groups` (без глибокого злиття). Потім пошук prompt виконується в отриманій єдиній мапі:
-1. **Системний промпт для конкретної групи** (`groups[""].systemPrompt`): використовується, коли конкретний запис групи існує в мапі **і** його ключ `systemPrompt` визначено. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується й системний промпт не застосовується.
-2. **Системний промпт wildcard для групи** (`groups["*"].systemPrompt`): використовується, коли конкретного запису групи в мапі взагалі немає або коли він існує, але не визначає ключ `systemPrompt`.
+1. **Системний prompt для конкретної групи** (`groups[""].systemPrompt`): використовується, коли конкретний запис групи існує в мапі **і** його ключ `systemPrompt` визначено. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується й системний prompt не застосовується.
+2. **Wildcard системний prompt групи** (`groups["*"].systemPrompt`): використовується, коли конкретний запис групи повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`.
-Ієрархія вирішення для прямих повідомлень:
+Ієрархія розв’язання для прямих повідомлень:
-Ефективна мапа `direct` визначається першою: якщо обліковий запис визначає власну `direct`, вона повністю замінює кореневу мапу `direct` (без глибокого злиття). Потім пошук промпта виконується на отриманій єдиній мапі:
+Ефективна мапа `direct` визначається спочатку: якщо обліковий запис визначає власні `direct`, вона повністю замінює кореневу мапу `direct` (без глибокого злиття). Потім пошук prompt виконується в отриманій єдиній мапі:
-1. **Системний промпт для конкретного прямого чату** (`direct[""].systemPrompt`): використовується, коли конкретний запис peer існує в мапі **і** його ключ `systemPrompt` визначено. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується й системний промпт не застосовується.
-2. **Системний промпт wildcard для прямих чатів** (`direct["*"].systemPrompt`): використовується, коли конкретного запису peer у мапі взагалі немає або коли він існує, але не визначає ключ `systemPrompt`.
+1. **Системний prompt для конкретного direct** (`direct[""].systemPrompt`): використовується, коли конкретний запис peer існує в мапі **і** його ключ `systemPrompt` визначено. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується й системний prompt не застосовується.
+2. **Wildcard системний prompt direct** (`direct["*"].systemPrompt`): використовується, коли конкретний запис peer повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`.
-`dms` лишається легким bucket перевизначення історії для окремих DM (`dms..historyLimit`). Перевизначення промптів розміщуються в `direct`.
+`dms` залишається легким контейнером перевизначення історії для окремих DM (`dms..historyLimit`). Перевизначення prompt розміщуються в `direct`.
-**Відмінність від поведінки кількох облікових записів Telegram:** У Telegram коренева `groups` навмисно пригнічується для всіх облікових записів у конфігурації з кількома обліковими записами — навіть для облікових записів, які не визначають власної `groups`, — щоб запобігти отриманню ботом групових повідомлень для груп, до яких він не належить. WhatsApp не застосовує цей запобіжник: кореневі `groups` і коренева `direct` завжди успадковуються обліковими записами, які не визначають перевизначення на рівні облікового запису, незалежно від кількості налаштованих облікових записів. У конфігурації WhatsApp з кількома обліковими записами, якщо вам потрібні промпти для груп або прямих чатів на рівні окремого облікового запису, явно визначте повну мапу в кожному обліковому записі, а не покладайтеся на кореневі значення за замовчуванням.
+**Відмінність від поведінки Telegram із кількома обліковими записами:** У Telegram кореневі `groups` навмисно пригнічуються для всіх облікових записів у конфігурації з кількома обліковими записами — навіть для облікових записів, які не визначають власні `groups`, — щоб запобігти отриманню ботом групових повідомлень для груп, до яких він не належить. WhatsApp не застосовує цей запобіжник: кореневі `groups` і кореневі `direct` завжди успадковуються обліковими записами, які не визначають перевизначення на рівні облікового запису, незалежно від кількості налаштованих облікових записів. У конфігурації WhatsApp із кількома обліковими записами, якщо вам потрібні prompts для груп або direct для окремого облікового запису, явно визначте повну мапу в кожному обліковому записі, а не покладайтеся на кореневі типові значення.
Важлива поведінка:
-- `channels.whatsapp.groups` є одночасно картою конфігурації для окремих груп і списком дозволених груп на рівні чату. На рівні кореня або акаунта `groups["*"]` означає, що "усі групи допускаються" для цієї області.
-- Додавайте груповий wildcard `systemPrompt` лише тоді, коли ви вже хочете, щоб ця область допускала всі групи. Якщо ви й надалі хочете, щоб допустимим був лише фіксований набір ID груп, не використовуйте `groups["*"]` для типового промпта. Натомість повторіть промпт у кожному явно дозволеному записі групи.
-- Допуск групи та авторизація відправника є окремими перевірками. `groups["*"]` розширює набір груп, які можуть перейти до обробки груп, але сам собою не авторизує кожного відправника в цих групах. Доступ відправників і надалі окремо контролюється через `channels.whatsapp.groupPolicy` і `channels.whatsapp.groupAllowFrom`.
-- `channels.whatsapp.direct` не має такого самого побічного ефекту для приватних повідомлень. `direct["*"]` лише надає типову конфігурацію прямого чату після того, як приватне повідомлення вже допущено через `dmPolicy` разом із правилами `allowFrom` або сховища сполучення.
+- `channels.whatsapp.groups` є одночасно мапою конфігурації для окремих груп і списком дозволених груп на рівні чату. На кореневому рівні або в межах облікового запису `groups["*"]` означає «усі групи допущено» для цієї області.
+- Додавайте wildcard-групу `systemPrompt` лише тоді, коли ви вже хочете, щоб ця область допускала всі групи. Якщо ви все ще хочете, щоб придатним був лише фіксований набір ID груп, не використовуйте `groups["*"]` для стандартного промпта. Натомість повторіть промпт у кожному явно дозволеному записі групи.
+- Допуск групи та авторизація відправника є окремими перевірками. `groups["*"]` розширює набір груп, які можуть потрапити до обробки груп, але сам по собі не авторизує кожного відправника в цих групах. Доступ відправників усе ще окремо контролюється `channels.whatsapp.groupPolicy` і `channels.whatsapp.groupAllowFrom`.
+- `channels.whatsapp.direct` не має такого самого побічного ефекту для особистих повідомлень. `direct["*"]` лише надає стандартну конфігурацію прямого чату після того, як особисте повідомлення вже допущено через `dmPolicy` плюс `allowFrom` або правила сховища сполучень.
Приклад:
@@ -672,19 +682,19 @@ WhatsApp підтримує системні промпти в стилі Telegr
}
```
-## Вказівники довідника конфігурації
+## Вказівники на довідку з конфігурації
-Основний довідник:
+Основна довідка:
-- [Довідник конфігурації - WhatsApp](/uk/gateway/config-channels#whatsapp)
+- [Довідка з конфігурації - WhatsApp](/uk/gateway/config-channels#whatsapp)
-Високосигнальні поля WhatsApp:
+Найважливіші поля WhatsApp:
- доступ: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`
-- доставка: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`, `reactionLevel`
-- кілька акаунтів: `accounts..enabled`, `accounts..authDir`, перевизначення на рівні акаунта
+- доставлення: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`, `reactionLevel`
+- кілька облікових записів: `accounts..enabled`, `accounts..authDir`, перевизначення на рівні облікового запису
- операції: `configWrites`, `debounceMs`, `web.enabled`, `web.heartbeatSeconds`, `web.reconnect.*`, `web.whatsapp.*`
-- поведінка сесії: `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms..historyLimit`
+- поведінка сеансу: `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms..historyLimit`
- промпти: `groups..systemPrompt`, `groups["*"].systemPrompt`, `direct..systemPrompt`, `direct["*"].systemPrompt`
## Пов’язане
@@ -693,5 +703,5 @@ WhatsApp підтримує системні промпти в стилі Telegr
- [Групи](/uk/channels/groups)
- [Безпека](/uk/gateway/security)
- [Маршрутизація каналів](/uk/channels/channel-routing)
-- [Маршрутизація між кількома агентами](/uk/concepts/multi-agent)
+- [Маршрутизація кількох агентів](/uk/concepts/multi-agent)
- [Усунення несправностей](/uk/channels/troubleshooting)
diff --git a/docs/uk/cli/channels.md b/docs/uk/cli/channels.md
index e36253b23..23160506a 100644
--- a/docs/uk/cli/channels.md
+++ b/docs/uk/cli/channels.md
@@ -1,26 +1,26 @@
---
read_when:
- Ви хочете додати/видалити облікові записи каналів (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (Plugin)/Signal/iMessage/Matrix)
- - Ви хочете перевірити стан каналу або переглянути останні записи журналів каналу
+ - Ви хочете перевірити статус каналу або переглядати журнали каналу в реальному часі
summary: Довідник CLI для `openclaw channels` (облікові записи, статус, вхід/вихід, журнали)
title: Канали
x-i18n:
- generated_at: "2026-05-01T07:53:17Z"
+ generated_at: "2026-05-01T21:50:54Z"
model: gpt-5.5
provider: openai
- source_hash: 1f673a626b46cd4c8ba7eb28963d27e7e3f630dd86723332faab9b4c86553da9
+ source_hash: c9cfde99d49d63397756b182a20ae3936a6b23f2455616dc86ceb3f16a205c06
source_path: cli/channels.md
workflow: 16
---
# `openclaw channels`
-Керуйте обліковими записами чат-каналів і їхнім станом виконання на Gateway.
+Керуйте обліковими записами каналів чату та їхнім станом виконання на Gateway.
-Пов’язані документи:
+Пов’язана документація:
- Посібники з каналів: [Канали](/uk/channels)
-- Конфігурація Gateway: [Конфігурація](/uk/gateway/configuration)
+- Налаштування Gateway: [Налаштування](/uk/gateway/configuration)
## Поширені команди
@@ -40,7 +40,11 @@ openclaw channels logs --channel all
- `channels resolve`: ``, `--channel `, `--account `, `--kind `, `--json`
- `channels logs`: `--channel `, `--lines `, `--json`
-`channels status --probe` — це живий шлях: на доступному Gateway він запускає для кожного облікового запису перевірки `probeAccount` і, за потреби, `auditAccount`, тому вивід може містити стан транспорту, а також результати перевірок, як-от `works`, `probe failed`, `audit ok` або `audit failed`. Якщо Gateway недоступний, `channels status` повертається до зведень лише з конфігурації замість виводу живої перевірки.
+`channels status --probe` — це живий шлях: на доступному Gateway він виконує для кожного облікового запису
+перевірки `probeAccount` і необов’язкові `auditAccount`, тому вивід може містити стан
+транспорту, а також результати перевірки, як-от `works`, `probe failed`, `audit ok` або `audit failed`.
+Якщо Gateway недоступний, `channels status` повертається до підсумків лише з конфігурації
+замість виводу живої перевірки.
## Додавання / видалення облікових записів
@@ -54,9 +58,10 @@ openclaw channels remove --channel telegram --delete
`openclaw channels add --help` показує прапорці для кожного каналу (токен, приватний ключ, токен застосунку, шляхи signal-cli тощо).
-`channels remove` працює лише зі встановленими/налаштованими Plugin каналів. Для каналів із каталогу, які можна встановити, спочатку використайте `channels add`.
+`channels remove` працює лише з установленими/налаштованими Plugin каналів. Спершу використайте `channels add` для каналів із каталогу, які можна встановити.
+Для Plugin каналів із підтримкою середовища виконання `channels remove` також просить запущений Gateway зупинити вибраний обліковий запис перед оновленням конфігурації, тому вимкнення або видалення облікового запису не залишає старий слухач активним до перезапуску.
-Поширені неінтерактивні поверхні додавання:
+Поширені неінтерактивні поверхні додавання охоплюють:
- канали з bot-token: `--token`, `--bot-token`, `--app-token`, `--token-file`
- поля транспорту Signal/iMessage: `--signal-number`, `--cli-path`, `--http-url`, `--http-host`, `--http-port`, `--db-path`, `--service`, `--region`
@@ -64,29 +69,29 @@ openclaw channels remove --channel telegram --delete
- поля Matrix: `--homeserver`, `--user-id`, `--access-token`, `--password`, `--device-name`, `--initial-sync-limit`
- поля Nostr: `--private-key`, `--relay-urls`
- поля Tlon: `--ship`, `--url`, `--code`, `--group-channels`, `--dm-allowlist`, `--auto-discover-channels`
-- `--use-env` для автентифікації типового облікового запису через env, де це підтримується
+- `--use-env` для автентифікації типового облікового запису через змінні середовища там, де це підтримується
-Якщо Plugin каналу потрібно встановити під час команди додавання, керованої прапорцями, OpenClaw використовує типове джерело встановлення каналу, не відкриваючи інтерактивний запит встановлення Plugin.
+Якщо Plugin каналу потрібно встановити під час команди додавання, керованої прапорцями, OpenClaw використовує типове джерело встановлення каналу, не відкриваючи інтерактивний запит установлення Plugin.
Коли ви запускаєте `openclaw channels add` без прапорців, інтерактивний майстер може запитати:
-- ідентифікатори облікових записів для кожного вибраного каналу
-- необов’язкові відображувані назви для цих облікових записів
+- ідентифікатори облікових записів для вибраного каналу
+- необов’язкові відображувані імена для цих облікових записів
- `Bind configured channel accounts to agents now?`
-Якщо підтвердити прив’язку зараз, майстер запитає, який агент має володіти кожним налаштованим обліковим записом каналу, і запише прив’язки маршрутизації з областю облікового запису.
+Якщо ви підтвердите прив’язування зараз, майстер запитає, який агент має володіти кожним налаштованим обліковим записом каналу, і запише прив’язки маршрутизації в межах облікового запису.
-Ті самі правила маршрутизації також можна пізніше керувати через `openclaw agents bindings`, `openclaw agents bind` і `openclaw agents unbind` (див. [агенти](/uk/cli/agents)).
+Ви також можете керувати тими самими правилами маршрутизації пізніше за допомогою `openclaw agents bindings`, `openclaw agents bind` і `openclaw agents unbind` (див. [агенти](/uk/cli/agents)).
-Коли ви додаєте нетиповий обліковий запис до каналу, який досі використовує налаштування верхнього рівня для одного облікового запису, OpenClaw переносить значення верхнього рівня з областю облікового запису в мапу облікових записів каналу перед записом нового облікового запису. Більшість каналів розміщують ці значення в `channels..accounts.default`, але вбудовані канали можуть натомість зберегти наявний відповідний перенесений обліковий запис. Поточний приклад — Matrix: якщо вже існує один іменований обліковий запис або `defaultAccount` вказує на наявний іменований обліковий запис, перенесення зберігає цей обліковий запис замість створення нового `accounts.default`.
+Коли ви додаєте нетиповий обліковий запис до каналу, який досі використовує однорівневі налаштування одного облікового запису, OpenClaw підвищує значення верхнього рівня в межах облікового запису до мапи облікових записів каналу перед записом нового облікового запису. Більшість каналів розміщують ці значення в `channels..accounts.default`, але вбудовані канали натомість можуть зберегти наявний відповідний підвищений обліковий запис. Matrix — поточний приклад: якщо один іменований обліковий запис уже існує або `defaultAccount` указує на наявний іменований обліковий запис, підвищення зберігає цей обліковий запис замість створення нового `accounts.default`.
-Поведінка маршрутизації лишається узгодженою:
+Поведінка маршрутизації залишається узгодженою:
-- Наявні прив’язки лише до каналу (без `accountId`) і далі відповідають типовому обліковому запису.
+- Наявні прив’язки лише каналу (без `accountId`) і далі відповідають типовому обліковому запису.
- `channels add` не створює автоматично й не переписує прив’язки в неінтерактивному режимі.
-- Інтерактивне налаштування може за бажанням додати прив’язки з областю облікового запису.
+- Інтерактивне налаштування може необов’язково додати прив’язки в межах облікового запису.
-Якщо ваша конфігурація вже була в змішаному стані (наявні іменовані облікові записи й досі задані значення верхнього рівня для одного облікового запису), запустіть `openclaw doctor --fix`, щоб перемістити значення з областю облікового запису в перенесений обліковий запис, вибраний для цього каналу. Більшість каналів переносять у `accounts.default`; Matrix натомість може зберегти наявну іменовану/типову ціль.
+Якщо ваша конфігурація вже була в змішаному стані (іменовані облікові записи наявні, а значення одного облікового запису верхнього рівня все ще задані), запустіть `openclaw doctor --fix`, щоб перемістити значення в межах облікового запису до підвищеного облікового запису, вибраного для цього каналу. Більшість каналів підвищують до `accounts.default`; Matrix натомість може зберегти наявну іменовану/типову ціль.
## Вхід і вихід (інтерактивно)
@@ -97,18 +102,19 @@ openclaw channels logout --channel whatsapp
- `channels login` підтримує `--verbose`.
- `channels login` і `logout` можуть визначити канал, коли налаштовано лише одну підтримувану ціль входу.
-- Запускайте `channels login` з термінала на хості Gateway. Агентський `exec` блокує цей інтерактивний потік входу; нативні для каналу інструменти входу агента, як-от `whatsapp_login`, слід використовувати з чату, коли вони доступні.
+- `channels logout` надає перевагу живому шляху Gateway, коли він доступний, тому вихід зупиняє будь-який активний слухач перед очищенням стану автентифікації каналу. Якщо локальний Gateway недоступний, він повертається до локального очищення автентифікації.
+- Запускайте `channels login` з термінала на хості Gateway. Agent `exec` блокує цей інтерактивний потік входу; нативні для каналу інструменти входу агента, як-от `whatsapp_login`, слід використовувати з чату, коли вони доступні.
## Усунення несправностей
- Запустіть `openclaw status --deep` для широкої перевірки.
- Використовуйте `openclaw doctor` для керованих виправлень.
-- `openclaw channels list` друкує `Claude: HTTP 403 ... user:profile` → знімку використання потрібна область `user:profile`. Використайте `--no-usage`, або надайте ключ сесії claude.ai (`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`), або повторно автентифікуйтеся через Claude CLI.
-- `openclaw channels status` повертається до зведень лише з конфігурації, коли Gateway недоступний. Якщо підтримувані облікові дані каналу налаштовано через SecretRef, але вони недоступні в поточному шляху команди, він повідомляє цей обліковий запис як налаштований із примітками про погіршений стан замість показу його як неналаштованого.
+- `openclaw channels list` виводить `Claude: HTTP 403 ... user:profile` → знімку використання потрібна область `user:profile`. Використайте `--no-usage`, або надайте ключ сеансу claude.ai (`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`), або повторно автентифікуйтеся через Claude CLI.
+- `openclaw channels status` повертається до підсумків лише з конфігурації, коли Gateway недоступний. Якщо облікові дані підтримуваного каналу налаштовано через SecretRef, але вони недоступні в поточному шляху команди, він повідомляє цей обліковий запис як налаштований із примітками про погіршений стан, а не показує його як неналаштований.
## Перевірка можливостей
-Отримайте підказки можливостей провайдера (intents/scopes, де доступно) плюс статичну підтримку функцій:
+Отримайте підказки щодо можливостей провайдера (intents/scopes там, де доступно), а також статичну підтримку функцій:
```bash
openclaw channels capabilities
@@ -117,14 +123,14 @@ openclaw channels capabilities --channel discord --target channel:123
Примітки:
-- `--channel` необов’язковий; пропустіть його, щоб перелічити кожен канал (включно з extensions).
+- `--channel` необов’язковий; опустіть його, щоб перелічити кожен канал (включно з extensions).
- `--account` дійсний лише з `--channel`.
- `--target` приймає `channel:` або необроблений числовий ідентифікатор каналу та застосовується лише до Discord.
- Перевірки залежать від провайдера: Discord intents + необов’язкові дозволи каналу; області Slack bot + user; прапорці Telegram bot + Webhook; версія демона Signal; токен застосунку Microsoft Teams + ролі/області Graph (анотовано там, де відомо). Канали без перевірок повідомляють `Probe: unavailable`.
-## Перетворення назв на ідентифікатори
+## Перетворення імен на ідентифікатори
-Перетворюйте назви каналів/користувачів на ідентифікатори за допомогою каталогу провайдера:
+Перетворюйте імена каналів/користувачів на ідентифікатори за допомогою каталогу провайдера:
```bash
openclaw channels resolve --channel slack "#general" "@jane"
@@ -135,9 +141,9 @@ openclaw channels resolve --channel matrix "Project Room"
Примітки:
- Використовуйте `--kind user|group|auto`, щоб примусово задати тип цілі.
-- Під час розв’язання перевага надається активним збігам, коли кілька записів мають однакову назву.
-- `channels resolve` доступний лише для читання. Якщо вибраний обліковий запис налаштовано через SecretRef, але ці облікові дані недоступні в поточному шляху команди, команда повертає погіршені нерозв’язані результати з примітками замість переривання всього запуску.
-- `channels resolve` не встановлює Plugin каналів. Використайте `channels add --channel ` перед розв’язанням назв для каналу з каталогу, який можна встановити.
+- Розв’язання надає перевагу активним збігам, коли кілька записів мають однакове ім’я.
+- `channels resolve` доступна лише для читання. Якщо вибраний обліковий запис налаштовано через SecretRef, але ці облікові дані недоступні в поточному шляху команди, команда повертає погіршені нерозв’язані результати з примітками замість переривання всього запуску.
+- `channels resolve` не встановлює Plugin каналів. Використайте `channels add --channel ` перед розв’язанням імен для каналу з каталогу, який можна встановити.
## Пов’язане
diff --git a/docs/uk/cli/doctor.md b/docs/uk/cli/doctor.md
index 1fb72f223..bdd0f32a7 100644
--- a/docs/uk/cli/doctor.md
+++ b/docs/uk/cli/doctor.md
@@ -1,14 +1,14 @@
---
read_when:
- - У вас проблеми з підключенням або автентифікацією, і ви хочете отримати покрокові виправлення
- - Ви оновилися й хочете базову перевірку
+ - У вас виникли проблеми з підключенням або автентифікацією, і вам потрібні покрокові виправлення
+ - Ви оновилися й хочете виконати базову перевірку
summary: Довідник CLI для `openclaw doctor` (перевірки справності + керовані виправлення)
title: Діагностика
x-i18n:
- generated_at: "2026-05-01T20:36:47Z"
+ generated_at: "2026-05-01T21:50:48Z"
model: gpt-5.5
provider: openai
- source_hash: 5471c76e345021e3ee8d42ea7c6b0a9dd30066636e00f80e2408071bad891b61
+ source_hash: 8b15e5e5d062ae3e6f236775567b098d57ea6518171c0d45c78cab5b985e215e
source_path: cli/doctor.md
workflow: 16
---
@@ -17,9 +17,9 @@ x-i18n:
Перевірки стану + швидкі виправлення для Gateway і каналів.
-Пов’язано:
+Пов’язане:
-- Усунення неполадок: [Усунення неполадок](/uk/gateway/troubleshooting)
+- Усунення несправностей: [Усунення несправностей](/uk/gateway/troubleshooting)
- Аудит безпеки: [Безпека](/uk/gateway/security)
## Приклади
@@ -35,40 +35,41 @@ openclaw doctor --generate-gateway-token
## Параметри
- `--no-workspace-suggestions`: вимкнути пропозиції пам’яті/пошуку робочої області
-- `--yes`: приймати типові значення без запитів
-- `--repair`: застосувати рекомендовані виправлення, не пов’язані зі службами, без запитів; встановлення й переписування служби Gateway все одно потребують інтерактивного підтвердження або явних команд Gateway
+- `--yes`: приймати типові значення без запиту
+- `--repair`: застосувати рекомендовані виправлення, не пов’язані зі службами, без запиту; встановлення та перезапис служб Gateway усе ще потребують інтерактивного підтвердження або явних команд Gateway
- `--fix`: псевдонім для `--repair`
- `--force`: застосувати агресивні виправлення, зокрема перезапис користувацької конфігурації служби за потреби
-- `--non-interactive`: запуск без запитів; лише безпечні міграції та виправлення, не пов’язані зі службами
+- `--non-interactive`: запускати без запитів; лише безпечні міграції та виправлення, не пов’язані зі службами
- `--generate-gateway-token`: згенерувати й налаштувати токен Gateway
- `--deep`: просканувати системні служби на наявність додаткових встановлень Gateway
Примітки:
-- Інтерактивні запити (наприклад, виправлення keychain/OAuth) виконуються лише тоді, коли stdin є TTY і **не** задано `--non-interactive`. Запуски без інтерфейсу (cron, Telegram, без термінала) пропускатимуть запити.
-- Продуктивність: неінтерактивні запуски `doctor` пропускають завчасне завантаження plugin, щоб перевірки стану без інтерфейсу залишалися швидкими. Інтерактивні сеанси все одно повністю завантажують plugins, коли перевірці потрібен їхній внесок.
-- `--fix` (псевдонім для `--repair`) записує резервну копію в `~/.openclaw/openclaw.json.bak` і видаляє невідомі ключі конфігурації, перелічуючи кожне видалення.
-- `doctor --fix --non-interactive` повідомляє про відсутні або застарілі визначення служби Gateway, але не встановлює й не переписує їх поза режимом виправлення оновлення. Запустіть `openclaw gateway install` для відсутньої служби або `openclaw gateway install --force`, коли ви навмисно хочете замінити засіб запуску.
-- Перевірки цілісності стану тепер виявляють осиротілі файли transcript у каталозі сеансів. Архівування їх як `.deleted.` потребує інтерактивного підтвердження; `--fix`, `--yes` і запуски без інтерфейсу залишають їх на місці.
-- Doctor також сканує `~/.openclaw/cron/jobs.json` (або `cron.store`) на наявність застарілих форм завдань Cron і може переписати їх на місці до того, як планувальнику доведеться автоматично нормалізувати їх під час виконання.
-- Doctor очищає застарілий проміжний стан залежностей plugin, створений старішими версіями OpenClaw. Він також виправляє відсутні налаштовані завантажувані plugins, коли registry може їх визначити.
-- Doctor виправляє застарілу конфігурацію plugin, видаляючи відсутні ідентифікатори plugin з `plugins.allow`/`plugins.entries`, а також відповідну завислу конфігурацію каналів, цілі heartbeat і перевизначення моделей каналів, коли виявлення plugin працює коректно.
-- Doctor ізолює недійсну конфігурацію plugin, вимикаючи відповідний запис `plugins.entries.` і видаляючи його недійсне корисне навантаження `config`. Запуск Gateway уже пропускає лише цей несправний plugin, тож інші plugins і канали можуть продовжувати роботу.
-- Задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли інший supervisor керує життєвим циклом Gateway. Doctor і далі повідомляє про стан Gateway/служби та застосовує виправлення, не пов’язані зі службами, але пропускає встановлення/запуск/перезапуск/bootstrap служби та очищення застарілої служби.
-- У Linux doctor ігнорує неактивні додаткові systemd units, схожі на Gateway, і не переписує метадані команди/entrypoint для запущеної служби Gateway systemd під час виправлення. Спершу зупиніть службу або використайте `openclaw gateway install --force`, коли ви навмисно хочете замінити активний засіб запуску.
-- Doctor автоматично мігрує застарілу пласку конфігурацію Talk (`talk.voiceId`, `talk.modelId` тощо) у `talk.provider` + `talk.providers.`.
-- Повторні запуски `doctor --fix` більше не повідомляють і не застосовують нормалізацію Talk, коли єдина відмінність — порядок ключів об’єкта.
-- Doctor містить перевірку готовності memory-search і може рекомендувати `openclaw configure --section model`, коли бракує облікових даних для embeddings.
-- Doctor попереджає, коли не налаштовано власника команд. Власник команд — це обліковий запис людини-оператора, якому дозволено виконувати команди лише для власника та схвалювати небезпечні дії. DM pairing лише дає змогу комусь спілкуватися з bot; якщо ви схвалили відправника до появи bootstrap першого власника, задайте `commands.ownerAllowFrom` явно.
-- Doctor попереджає, коли налаштовано агентів у режимі Codex і в Codex home оператора існують особисті assets Codex CLI. Локальні запуски app-server Codex використовують ізольовані home для кожного агента, тому використайте `openclaw migrate codex --dry-run`, щоб інвентаризувати assets, які слід просувати свідомо.
-- Якщо sandbox mode увімкнено, але Docker недоступний, doctor повідомляє високосигнальне попередження з remediation (`install Docker` або `openclaw config set agents.defaults.sandbox.mode off`).
-- Якщо `gateway.auth.token`/`gateway.auth.password` керуються SecretRef і недоступні в поточному шляху команди, doctor повідомляє попередження лише для читання й не записує fallback credentials відкритим текстом.
-- Якщо inspection SecretRef каналу не вдається у шляху виправлення, doctor продовжує роботу й повідомляє попередження замість дострокового завершення.
-- Автовизначення імені користувача Telegram `allowFrom` (`doctor --fix`) потребує токена Telegram, який можна визначити в поточному шляху команди. Якщо inspection токена недоступна, doctor повідомляє попередження й пропускає автовизначення для цього проходу.
+- Інтерактивні запити (наприклад, виправлення keychain/OAuth) виконуються лише тоді, коли stdin є TTY і **не** задано `--non-interactive`. Безголові запуски (cron, Telegram, без термінала) пропускатимуть запити.
+- Продуктивність: неінтерактивні запуски `doctor` пропускають завчасне завантаження Plugin, щоб безголові перевірки стану залишалися швидкими. Інтерактивні сеанси все одно повністю завантажують Plugin, коли перевірці потрібен їхній внесок.
+- `--fix` (псевдонім для `--repair`) записує резервну копію в `~/.openclaw/openclaw.json.bak` і відкидає невідомі ключі конфігурації, перелічуючи кожне видалення.
+- `doctor --fix --non-interactive` повідомляє про відсутні або застарілі визначення служби Gateway, але не встановлює й не перезаписує їх поза режимом виправлення оновлення. Запустіть `openclaw gateway install` для відсутньої служби або `openclaw gateway install --force`, коли навмисно хочете замінити launcher.
+- Перевірки цілісності стану тепер виявляють осиротілі файли транскриптів у каталозі сеансів. Архівування їх як `.deleted.` потребує інтерактивного підтвердження; `--fix`, `--yes` і безголові запуски залишають їх на місці.
+- Doctor також сканує `~/.openclaw/cron/jobs.json` (або `cron.store`) на наявність застарілих форм завдань cron і може перезаписати їх на місці до того, як scheduler муситиме автоматично нормалізувати їх під час виконання.
+- У Linux doctor попереджає, коли crontab користувача все ще запускає застарілий `~/.openclaw/bin/ensure-whatsapp.sh`; цей скрипт більше не підтримується й може реєструвати хибні збої Gateway WhatsApp, коли cron не має середовища user-bus systemd.
+- Doctor очищає застарілий проміжний стан залежностей Plugin, створений старішими версіями OpenClaw. Він також відновлює відсутні налаштовані завантажувані Plugin, коли реєстр може їх розв’язати.
+- Doctor виправляє застарілу конфігурацію Plugin, видаляючи відсутні ідентифікатори Plugin із `plugins.allow`/`plugins.entries`, а також відповідну висячу конфігурацію каналів, цілі Heartbeat і перевизначення моделей каналів, коли виявлення Plugin працює коректно.
+- Doctor поміщає недійсну конфігурацію Plugin у карантин, вимикаючи відповідний запис `plugins.entries.` і видаляючи його недійсний payload `config`. Запуск Gateway уже пропускає лише цей несправний Plugin, тож інші Plugin і канали можуть продовжувати працювати.
+- Установіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли інший supervisor керує життєвим циклом Gateway. Doctor і далі повідомляє про стан Gateway/служби та застосовує виправлення, не пов’язані зі службами, але пропускає встановлення/запуск/перезапуск/bootstrap служби та очищення застарілих служб.
+- У Linux doctor ігнорує неактивні додаткові systemd units, схожі на Gateway, і не перезаписує метадані команди/entrypoint для запущеної служби Gateway systemd під час виправлення. Спершу зупиніть службу або використайте `openclaw gateway install --force`, коли навмисно хочете замінити активний launcher.
+- Doctor автоматично мігрує застарілу пласку конфігурацію Talk (`talk.voiceId`, `talk.modelId` і пов’язані ключі) у `talk.provider` + `talk.providers.`.
+- Повторні запуски `doctor --fix` більше не повідомляють і не застосовують нормалізацію Talk, коли єдина відмінність полягає в порядку ключів об’єкта.
+- Doctor містить перевірку готовності пошуку в пам’яті та може рекомендувати `openclaw configure --section model`, коли відсутні облікові дані embeddings.
+- Doctor попереджає, коли не налаштовано власника команд. Власник команд — це обліковий запис оператора-людини, якому дозволено запускати команди лише для власника та схвалювати небезпечні дії. Сполучення через DM лише дозволяє комусь спілкуватися з ботом; якщо ви схвалили відправника до появи bootstrap першого власника, задайте `commands.ownerAllowFrom` явно.
+- Doctor попереджає, коли налаштовано агентів у режимі Codex і в Codex home оператора існують особисті ресурси Codex CLI. Локальні запуски app-server Codex використовують ізольовані home для кожного агента, тому використовуйте `openclaw migrate codex --dry-run`, щоб інвентаризувати ресурси, які слід просувати свідомо.
+- Якщо режим sandbox увімкнено, але Docker недоступний, doctor повідомляє високосигнальне попередження з remediation (`install Docker` або `openclaw config set agents.defaults.sandbox.mode off`).
+- Якщо `gateway.auth.token`/`gateway.auth.password` керуються SecretRef і недоступні в поточному шляху команди, doctor повідомляє попередження лише для читання й не записує plaintext fallback credentials.
+- Якщо інспекція SecretRef каналу зазнає невдачі в шляху виправлення, doctor продовжує роботу й повідомляє попередження замість дострокового виходу.
+- Автоматичне розв’язання імен користувачів Telegram `allowFrom` (`doctor --fix`) потребує розв’язуваного токена Telegram у поточному шляху команди. Якщо інспекція токена недоступна, doctor повідомляє попередження й пропускає автоматичне розв’язання для цього проходу.
## macOS: перевизначення env `launchctl`
-Якщо ви раніше запускали `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (або `...PASSWORD`), це значення перевизначає ваш файл конфігурації та може спричиняти сталі помилки «unauthorized».
+Якщо ви раніше запускали `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (або `...PASSWORD`), це значення перевизначає ваш файл конфігурації й може спричиняти постійні помилки “unauthorized”.
```bash
launchctl getenv OPENCLAW_GATEWAY_TOKEN
@@ -78,7 +79,7 @@ launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
```
-## Пов’язано
+## Пов’язане
- [Довідник CLI](/uk/cli)
- [Gateway doctor](/uk/gateway/doctor)
diff --git a/docs/uk/gateway/doctor.md b/docs/uk/gateway/doctor.md
index d82ce4646..552f00310 100644
--- a/docs/uk/gateway/doctor.md
+++ b/docs/uk/gateway/doctor.md
@@ -1,20 +1,20 @@
---
read_when:
- - Додавання або змінення doctor-міграцій
- - Запровадження несумісних змін конфігурації
+ - Додавання або змінення міграцій doctor
+ - Запровадження змін конфігурації, що порушують сумісність
sidebarTitle: Doctor
-summary: 'Команда doctor: перевірки працездатності, міграції конфігурації та кроки виправлення'
+summary: 'Команда doctor: перевірки справності, міграції конфігурації та кроки відновлення'
title: Діагностика
x-i18n:
- generated_at: "2026-05-01T20:37:48Z"
+ generated_at: "2026-05-01T21:50:52Z"
model: gpt-5.5
provider: openai
- source_hash: fbd833a7324e17fd15fb931925cf113dae8eaff8773e3ac99623b6c3e3f712d7
+ source_hash: bbcac6787b25db196dfc6bf7afc44afc26e9b19d219106c407e32e1d090c2344
source_path: gateway/doctor.md
workflow: 16
---
-`openclaw doctor` — це інструмент відновлення й міграції для OpenClaw. Він виправляє застарілі конфігурацію/стан, перевіряє справність і надає практичні кроки для відновлення.
+`openclaw doctor` — це інструмент відновлення та міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє справність і надає практичні кроки для відновлення.
## Швидкий старт
@@ -22,7 +22,7 @@ x-i18n:
openclaw doctor
```
-### Режими без інтерфейсу та автоматизації
+### Безголові режими та режими автоматизації
@@ -30,7 +30,7 @@ openclaw doctor
openclaw doctor --yes
```
- Приймати стандартні значення без запитів (зокрема кроки відновлення перезапуску/служби/пісочниці, коли застосовно).
+ Прийняти типові значення без запитів (зокрема кроки відновлення перезапуску/служби/пісочниці, коли це застосовно).
@@ -38,7 +38,7 @@ openclaw doctor
openclaw doctor --repair
```
- Застосувати рекомендовані відновлення без запитів (відновлення + перезапуски там, де це безпечно).
+ Застосувати рекомендовані виправлення без запитів (виправлення + перезапуски там, де це безпечно).
@@ -46,7 +46,7 @@ openclaw doctor
openclaw doctor --repair --force
```
- Застосувати також агресивні відновлення (перезаписує власні конфігурації супервізора).
+ Також застосувати агресивні виправлення (перезаписує користувацькі конфігурації супервізора).
@@ -54,7 +54,7 @@ openclaw doctor
openclaw doctor --non-interactive
```
- Запустити без запитів і застосувати лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/служби/пісочниці, які потребують підтвердження людиною. Міграції застарілого стану запускаються автоматично, коли їх виявлено.
+ Запустити без запитів і застосувати лише безпечні міграції (нормалізацію конфігурації + переміщення стану на диску). Пропускає дії з перезапуском/службою/пісочницею, які потребують підтвердження людини. Міграції застарілого стану запускаються автоматично після виявлення.
@@ -62,7 +62,7 @@ openclaw doctor
openclaw doctor --deep
```
- Сканувати системні служби на наявність додаткових встановлень Gateway (launchd/systemd/schtasks).
+ Сканувати системні служби на наявність додаткових інсталяцій gateway (launchd/systemd/schtasks).
@@ -77,10 +77,10 @@ cat ~/.openclaw/openclaw.json
- - Необов’язкове попереднє оновлення для git-встановлень (лише інтерактивно).
+ - Необов’язкове попереднє оновлення для git-інсталяцій (лише інтерактивно).
- Перевірка актуальності протоколу UI (перезбирає Control UI, коли схема протоколу новіша).
- Перевірка справності + запит на перезапуск.
- - Зведення стану Skills (придатні/відсутні/заблоковані) і стан Plugin.
+ - Підсумок стану Skills (придатні/відсутні/заблоковані) і стан Plugin.
@@ -88,50 +88,50 @@ cat ~/.openclaw/openclaw.json
- Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.`.
- Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP.
- Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`).
- - Попередження про затінення OAuth Codex (`models.providers.openai-codex`).
+ - Попередження про затінення Codex OAuth (`models.providers.openai-codex`).
- Перевірка передумов OAuth TLS для профілів OpenAI Codex OAuth.
- - Попередження щодо списку дозволених Plugin/інструментів, коли `plugins.allow` обмежувальний, але політика інструментів усе ще запитує wildcard або інструменти, що належать Plugin.
- - Міграція застарілого стану на диску (sessions/agent dir/WhatsApp auth).
+ - Попередження allowlist Plugin/інструментів, коли `plugins.allow` є обмежувальним, але політика інструментів усе ще запитує wildcard або інструменти, що належать Plugin.
+ - Міграція застарілого стану на диску (сесії/каталог агента/автентифікація WhatsApp).
- Міграція застарілих ключів контракту маніфесту Plugin (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`).
- - Міграція застарілого сховища Cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, payload `provider`, прості резервні завдання webhook `notify: true`).
- - Міграція застарілої runtime-політики агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`.
- - Очищення застарілої конфігурації Plugin, коли Plugin увімкнено; коли `plugins.enabled=false`, застарілі посилання на Plugin вважаються інертною конфігурацією ізоляції та зберігаються.
+ - Міграція застарілого сховища cron (`jobId`, `schedule.cron`, поля доставки/корисного навантаження верхнього рівня, `provider` у корисному навантаженні, прості fallback-завдання Webhook `notify: true`).
+ - Міграція застарілої політики runtime агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`.
+ - Очищення застарілої конфігурації Plugin, коли плагіни увімкнені; коли `plugins.enabled=false`, застарілі посилання на Plugin вважаються інертною конфігурацією ізоляції та зберігаються.
- Перевірка файлів блокування сесій і очищення застарілих блокувань.
- Відновлення транскриптів сесій для дубльованих гілок переписування промптів, створених ураженими збірками 2026.4.24.
- - Виявлення tombstone для відновлення після перезапуску завислого субагента з підтримкою `--fix` для очищення застарілих прапорців перерваного відновлення, щоб запуск не продовжував вважати дочірній процес перерваним через перезапуск.
+ - Виявлення tombstone для відновлення після перезапуску завислого субагента з підтримкою `--fix` для очищення застарілих прапорців перерваного відновлення, щоб запуск не продовжував трактувати дочірній процес як перерваний перезапуском.
- Перевірки цілісності стану та дозволів (сесії, транскрипти, каталог стану).
- Перевірки дозволів файлу конфігурації (chmod 600) під час локального запуску.
- - Справність автентифікації моделі: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled для auth-profile.
+ - Справність автентифікації моделі: перевіряє завершення строку дії OAuth, може оновлювати токени, що скоро спливають, і повідомляє про cooldown/вимкнені стани auth-profile.
- Виявлення додаткового каталогу робочого простору (`~/openclaw`).
- - Відновлення образу пісочниці, коли пісочницю ввімкнено.
- - Міграція застарілої служби та виявлення додаткових Gateway.
+ - Відновлення образу пісочниці, коли пісочницю увімкнено.
+ - Міграція застарілої служби та виявлення додаткових gateway.
- Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`).
- Перевірки runtime Gateway (службу встановлено, але вона не запущена; кешована мітка launchd).
- - Попередження про стан каналів (перевіряються із запущеного Gateway).
+ - Попередження стану каналів (перевіряються з запущеного gateway).
- Аудит конфігурації супервізора (launchd/systemd/schtasks) з необов’язковим відновленням.
- - Очищення середовища вбудованого проксі для служб Gateway, які захопили значення оболонки `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час встановлення або оновлення.
+ - Очищення середовища вбудованого проксі для служб gateway, які захопили значення shell `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час інсталяції або оновлення.
- Перевірки найкращих практик runtime Gateway (Node проти Bun, шляхи менеджера версій).
- - Діагностика конфлікту портів Gateway (стандартний `18789`).
+ - Діагностика конфлікту порту Gateway (типово `18789`).
-
+
- Попередження безпеки для відкритих політик DM.
- - Перевірки автентифікації Gateway для режиму локального токена (пропонує генерацію токена, коли немає джерела токена; не перезаписує конфігурації токена SecretRef).
- - Виявлення проблем зі сполученням пристроїв (очікувані запити першого сполучення, очікувані оновлення ролі/області, дрейф застарілого локального кешу device-token і дрейф автентифікації paired-record).
+ - Перевірки автентифікації Gateway для режиму локального токена (пропонує згенерувати токен, коли джерела токена немає; не перезаписує конфігурації токена SecretRef).
+ - Виявлення проблем зі спарюванням пристрою (очікувані запити першого спарювання, очікувані підвищення ролі/обсягу, застаріле розходження кешу локального device-token і розходження автентифікації paired-record).
-
+
- Перевірка systemd linger у Linux.
- - Перевірка розміру файлу bootstrap робочого простору (попередження про обрізання/наближення до ліміту для контекстних файлів).
- - Перевірка стану автодоповнення оболонки та автоматичне встановлення/оновлення.
- - Перевірка готовності провайдера embedding для пошуку пам’яті (локальна модель, ключ віддаленого API або QMD binary).
- - Перевірки встановлення з вихідного коду (невідповідність pnpm workspace, відсутні UI-ресурси, відсутній tsx binary).
+ - Перевірка розміру bootstrap-файлу робочого простору (попередження про усічення/наближення до ліміту для контекстних файлів).
+ - Перевірка стану shell completion і автоінсталяція/оновлення.
+ - Перевірка готовності провайдера embedding для пошуку в пам’яті (локальна модель, ключ віддаленого API або бінарний файл QMD).
+ - Перевірки інсталяції з вихідного коду (невідповідність pnpm workspace, відсутні UI-активи, відсутній бінарний файл tsx).
- Записує оновлену конфігурацію + метадані майстра.
@@ -139,42 +139,43 @@ cat ~/.openclaw/openclaw.json
## Зворотне заповнення та скидання UI Dreams
-Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для grounded dreaming workflow. Ці дії використовують RPC-методи Gateway у стилі doctor, але вони **не** є частиною відновлення/міграції CLI `openclaw doctor`.
+Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для grounded dreaming workflow. Ці дії використовують RPC-методи gateway у стилі doctor, але вони **не** є частиною CLI-відновлення/міграції `openclaw doctor`.
Що вони роблять:
- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному робочому просторі, запускає grounded REM diary pass і записує оборотні записи зворотного заповнення в `DREAMS.md`.
-- **Reset** видаляє з `DREAMS.md` лише ці позначені записи щоденника зворотного заповнення.
-- **Clear Grounded** видаляє лише підготовлені grounded-only короткострокові записи, які походять з історичного відтворення й ще не накопичили live recall або daily support.
+- **Reset** видаляє лише ці позначені diary-записи зворотного заповнення з `DREAMS.md`.
+- **Clear Grounded** видаляє лише підготовлені короткострокові записи only-grounded, які надійшли з історичного відтворення й ще не накопичили live recall або daily support.
-Чого вони самі по собі **не** роблять:
+Що вони **не** роблять самі по собі:
- вони не редагують `MEMORY.md`
- вони не запускають повні міграції doctor
-- вони не ставлять автоматично grounded-кандидатів у live short-term promotion store, якщо ви спочатку явно не запустите staged CLI path
+- вони не готують grounded-кандидатів автоматично в live short-term promotion store, якщо ви явно не запустите staged CLI path спочатку
-Якщо ви хочете, щоб grounded historical replay впливав на звичайну deep promotion lane, натомість використовуйте CLI-потік:
+Якщо ви хочете, щоб grounded historical replay впливав на звичайний deep promotion lane, натомість використовуйте CLI-потік:
```bash
openclaw memory rem-backfill --path ./memory --stage-short-term
```
-Це ставить grounded durable candidates у short-term dreaming store, залишаючи `DREAMS.md` поверхнею для перегляду.
+Це готує grounded durable candidates у short-term dreaming store, залишаючи `DREAMS.md` поверхнею для перегляду.
## Детальна поведінка та обґрунтування
-
- Якщо це git checkout і doctor запускається інтерактивно, він пропонує оновити (fetch/rebase/build) перед запуском doctor.
+
+ Якщо це git checkout і doctor запускається інтерактивно, він пропонує оновитися (fetch/rebase/build) перед запуском doctor.
Якщо конфігурація містить застарілі форми значень (наприклад, `messages.ackReaction` без перевизначення для конкретного каналу), doctor нормалізує їх у поточну схему.
- Це включає застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у map провайдера.
+ Це охоплює застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у мапу провайдера.
Doctor також попереджає, коли `plugins.allow` не порожній, а політика інструментів використовує
wildcard або записи інструментів, що належать Plugin. `tools.allow: ["*"]` відповідає лише інструментам
- із Plugin, які фактично завантажуються; він не обходить ексклюзивний список дозволених Plugin.
+ із Plugin, які фактично завантажуються; це не обходить ексклюзивний
+ allowlist Plugin.
@@ -186,7 +187,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
- Покаже застосовану міграцію.
- Перепише `~/.openclaw/openclaw.json` з оновленою схемою.
- Gateway також автоматично запускає міграції doctor під час запуску, коли виявляє застарілий формат конфігурації, тому застарілі конфігурації відновлюються без ручного втручання. Міграції сховища завдань Cron обробляються командою `openclaw doctor --fix`.
+ Gateway також автоматично запускає міграції doctor під час старту, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації виправляються без ручного втручання. Міграції сховища завдань Cron обробляються через `openclaw doctor --fix`.
Поточні міграції:
@@ -211,24 +212,24 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
- `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 може зберегти наявну відповідну іменовану/стандартну ціль)
+ - Для каналів із іменованими `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`
- видаліть `agents.defaults.llm`; використовуйте `models.providers..timeoutSeconds` для тайм-аутів повільних провайдерів/моделей
- `browser.ssrfPolicy.allowPrivateNetwork` → `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `browser.profiles.*.driver: "extension"` → `"existing-session"`
- - видаліть `browser.relayBindHost` (застаріле налаштування ретранслятора розширення)
- - застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (запуск Gateway також пропускає провайдерів, у яких `api` задано майбутнім або невідомим значенням enum, замість аварійного завершення із закритою відмовою)
+ - видаліть `browser.relayBindHost` (застаріле налаштування реле розширення)
+ - застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (запуск Gateway також пропускає провайдерів, у яких `api` встановлено на майбутнє або невідоме значення enum, замість аварійного завершення в закритому режимі)
- Попередження doctor також містять настанови щодо стандартного облікового запису для багатоканальних облікових записів:
+ Попередження doctor також містять настанови щодо стандартного облікового запису для каналів із кількома обліковими записами:
- Якщо налаштовано два або більше записів `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис.
- - Якщо `channels..defaultAccount` задано невідомим ID облікового запису, doctor попереджає і перелічує налаштовані ID облікових записів.
+ - Якщо `channels..defaultAccount` задано як невідомий ID облікового запису, doctor попереджає про це й перелічує налаштовані ID облікових записів.
-
- Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Це може примусово спрямувати моделі на неправильний API або обнулити вартість. Doctor попереджає, щоб ви могли видалити перевизначення й відновити маршрутизацію API та вартість для кожної моделі.
+
+ Якщо ви вручну додали `models.providers.opencode`, `opencode-zen` або `opencode-go`, це перевизначає вбудований каталог OpenCode з `@mariozechner/pi-ai`. Це може примусово спрямувати моделі до неправильного API або обнулити витрати. Doctor попереджає, щоб ви могли видалити перевизначення й відновити маршрутизацію API та витрати для кожної моделі.
Якщо ваша конфігурація браузера досі вказує на видалений шлях розширення Chrome, doctor нормалізує її до поточної моделі підключення Chrome MCP на локальному хості:
@@ -238,45 +239,45 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
Doctor також перевіряє шлях Chrome MCP на локальному хості, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`:
- - перевіряє, чи встановлено Google Chrome на тому самому хості для стандартних профілів автопідключення
+ - перевіряє, чи встановлено Google Chrome на тому самому хості для стандартних профілів автоматичного підключення
- перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144
- нагадує ввімкнути віддалене налагодження на сторінці інспектування браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`)
- Doctor не може ввімкнути це налаштування з боку Chrome за вас. Chrome MCP на локальному хості все одно потребує:
+ Doctor не може ввімкнути налаштування на боці Chrome замість вас. Chrome MCP на локальному хості все ще потребує:
- - браузера на базі Chromium 144+ на хості gateway/node
- - локально запущеного браузера
- - увімкненого віддаленого налагодження в цьому браузері
- - підтвердження першого запиту згоди на підключення в браузері
+ - браузер на основі Chromium 144+ на хості Gateway/Node
+ - браузер, запущений локально
+ - віддалене налагодження, увімкнене в цьому браузері
+ - схвалення першого запиту згоди на підключення в браузері
- Готовність тут стосується лише локальних передумов підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, все ще потребують керованого браузера або raw CDP-профілю.
+ Готовність тут стосується лише передумов локального підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, усе ще потребують керованого браузера або профілю raw CDP.
Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-потоків. Вони й надалі використовують raw CDP.
- Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє endpoint авторизації OpenAI, щоб підтвердити, що локальний стек Node/OpenSSL TLS може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor виводить інструкції з виправлення для конкретної платформи. На macOS з Homebrew Node виправлення зазвичай таке: `brew postinstall ca-certificates`. З `--deep` перевірка виконується, навіть якщо Gateway справний.
+ Коли налаштовано профіль OpenAI Codex OAuth, doctor перевіряє кінцеву точку авторизації OpenAI, щоб переконатися, що локальний стек Node/OpenSSL TLS може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor виводить настанови з виправлення для конкретної платформи. На macOS із Homebrew Node виправлення зазвичай таке: `brew postinstall ca-certificates`. З `--deep` перевірка виконується навіть тоді, коли gateway справний.
- Якщо ви раніше додали застарілі транспортні налаштування OpenAI у `models.providers.openai-codex`, вони можуть затінити вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі транспортні налаштування разом із Codex OAuth, щоб ви могли видалити або переписати застаріле транспортне перевизначення й повернути вбудовану поведінку маршрутизації/резервування. Користувацькі проксі та перевизначення лише заголовків і надалі підтримуються та не викликають цього попередження.
+ Якщо ви раніше додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі налаштування транспорту поряд із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту й повернути вбудовану поведінку маршрутизації/резервування. Користувацькі проксі та перевизначення лише заголовків усе ще підтримуються й не викликають цього попередження.
- Коли ввімкнено вбудований Plugin Codex, doctor також перевіряє, чи посилання основних моделей `openai-codex/*` досі розв'язуються через стандартний runner PI. Така комбінація коректна, якщо вам потрібна автентифікація Codex OAuth/передплати через PI, але її легко сплутати з нативним app-server harness Codex. Doctor попереджає і вказує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`.
+ Коли ввімкнено вбудований Plugin Codex, doctor також перевіряє, чи основні посилання на моделі `openai-codex/*` досі вирішуються через стандартний runner PI. Ця комбінація чинна, коли вам потрібна автентифікація Codex OAuth/підписки через PI, але її легко сплутати з нативним app-server harness Codex. Doctor попереджає й вказує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`.
- Doctor не виправляє це автоматично, бо обидва маршрути коректні:
+ Doctor не виправляє це автоматично, оскільки обидва маршрути чинні:
- - `openai-codex/*` + PI означає "використовувати автентифікацію Codex OAuth/передплати через звичайний runner OpenClaw."
- - `openai/*` + `runtime: "codex"` означає "виконувати вбудований turn через нативний app-server Codex."
- - `/codex ...` означає "керувати або прив'язати нативну розмову Codex із чату."
+ - `openai-codex/*` + PI означає "використовувати автентифікацію Codex OAuth/підписки через звичайний runner OpenClaw."
+ - `openai/*` + `runtime: "codex"` означає "запустити вбудований хід через нативний Codex app-server."
+ - `/codex ...` означає "керувати нативною розмовою Codex або прив'язати її з чату."
- `/acp ...` або `runtime: "acp"` означає "використовувати зовнішній адаптер ACP/acpx."
- Якщо з'являється попередження, виберіть потрібний маршрут і відредагуйте конфігурацію вручну. Залишайте попередження без змін, коли PI Codex OAuth є навмисним.
+ Якщо з'являється попередження, виберіть потрібний маршрут і вручну відредагуйте конфігурацію. Залиште попередження без змін, коли PI Codex OAuth є навмисним.
-
- Doctor може мігрувати старіші розкладки на диску в поточну структуру:
+
+ Doctor може мігрувати старіші структури на диску до поточної структури:
- - Сховище сесій + транскрипти:
+ - Сховище сеансів + транскрипти:
- з `~/.openclaw/sessions/` до `~/.openclaw/agents//sessions/`
- Каталог агента:
- з `~/.openclaw/agent/` до `~/.openclaw/agents//agent/`
@@ -284,214 +285,216 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
- із застарілого `~/.openclaw/credentials/*.json` (крім `oauth.json`)
- до `~/.openclaw/credentials/whatsapp//...` (стандартний ID облікового запису: `default`)
- Ці міграції виконуються за принципом best-effort і є ідемпотентними; doctor видаватиме попередження, коли залишатиме будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сесії + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапили в шлях для окремого агента без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація провайдера talk/карти провайдерів тепер порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не спричиняють повторних no-op змін `doctor --fix`.
+ Ці міграції виконуються за принципом найкращого зусилля та є ідемпотентними; doctor виводитиме попередження, коли залишатиме будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сеанси + каталог агента під час запуску, щоб історія/автентифікація/моделі потрапляли в шлях для кожного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація провайдера/карти провайдерів Talk тепер порівнює за структурною рівністю, тож відмінності лише в порядку ключів більше не спричиняють повторні no-op зміни `doctor --fix`.
- Doctor сканує всі встановлені маніфести Plugin на наявність застарілих верхньорівневих ключів можливостей (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Коли їх знайдено, він пропонує перемістити їх в об'єкт `contracts` і переписати файл маніфесту на місці. Ця міграція ідемпотентна; якщо ключ `contracts` уже має ті самі значення, застарілий ключ видаляється без дублювання даних.
+ Doctor сканує всі встановлені маніфести plugin на наявність застарілих верхньорівневих ключів можливостей (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Коли їх знайдено, він пропонує перемістити їх в об'єкт `contracts` і переписати файл маніфесту на місці. Ця міграція є ідемпотентною; якщо ключ `contracts` уже має такі самі значення, застарілий ключ видаляється без дублювання даних.
-
- Doctor також перевіряє сховище завдань cron (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, якщо перевизначено) на наявність старих форм завдань, які scheduler усе ще приймає для сумісності.
+
+ 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`
- - delivery-аліаси payload `provider` → явний `delivery.channel`
- - прості застарілі резервні завдання webhook `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook`
+ - верхньорівневі поля доставки (`deliver`, `channel`, `to`, `provider`, ...) → `delivery`
+ - псевдоніми доставки payload `provider` → явний `delivery.channel`
+ - прості застарілі резервні webhook-завдання `notify: true` → явний `delivery.mode="webhook"` із `delivery.to=cron.webhook`
- Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий резервний notify з наявним режимом delivery не-webhook, doctor попереджає і залишає це завдання для ручного перегляду.
+ Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий резервний notify з наявним режимом доставки, відмінним від webhook, doctor попереджає й залишає це завдання для ручного перегляду.
+
+ На 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 сканує кожен каталог сесій агента на наявність застарілих файлів write-lock — файлів, що залишилися після аварійного завершення сесії. Для кожного знайденого файлу блокування він повідомляє: шлях, PID, чи PID ще живий, вік блокування та чи вважається воно застарілим (мертвий PID або старше за 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше виводить примітку й інструктує повторно запустити з `--fix`.
+
+ Лікар сканує кожен каталог сеансів агента на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сеансу. Для кожного знайденого файла блокування він повідомляє: шлях, PID, чи PID досі активний, вік блокування та чи вважається воно застарілим (мертвий PID або старіше за 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше друкує примітку та вказує повторно запустити з `--fix`.
-
- Doctor сканує JSONL-файли сесій агента на дубльовану форму гілки, створену багом переписування транскрипта prompt від 2026.4.24: покинутий user turn із внутрішнім runtime context OpenClaw плюс активний sibling, що містить той самий видимий user prompt. У режимі `--fix` / `--repair` doctor створює резервну копію кожного ураженого файлу поруч з оригіналом і переписує транскрипт до активної гілки, щоб історія gateway і читачі memory більше не бачили дубльованих turns.
+
+ Лікар сканує JSONL-файли сеансів агента на дубльовану форму гілки, створену помилкою переписування транскрипту підказки 2026.4.24: покинутий хід користувача з внутрішнім runtime-контекстом OpenClaw плюс активний сусідній хід із тією самою видимою підказкою користувача. У режимі `--fix` / `--repair` лікар створює резервну копію кожного ураженого файла поруч з оригіналом і переписує транскрипт на активну гілку, щоб історія Gateway і читачі пам’яті більше не бачили дубльовані ходи.
-
- Каталог стану є операційним стовбуром системи. Якщо він зникне, ви втратите сесії, облікові дані, журнали й конфігурацію (якщо у вас немає резервних копій деінде).
+
+ Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите сеанси, облікові дані, журнали та конфігурацію (якщо не маєте резервних копій деінде).
- Doctor перевіряє:
+ Лікар перевіряє:
- - **Відсутній каталог стану**: попереджає про катастрофічну втрату стану, пропонує повторно створити каталог і нагадує, що відновити відсутні дані неможливо.
+ - **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує повторно створити каталог і нагадує, що не може відновити відсутні дані.
- **Дозволи каталогу стану**: перевіряє можливість запису; пропонує виправити дозволи (і виводить підказку `chown`, коли виявлено невідповідність власника/групи).
- - **Каталог стану macOS із хмарною синхронізацією**: попереджає, коли стан визначається в iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, оскільки шляхи із синхронізацією можуть спричиняти повільніший ввід-вивід і перегони блокувань/синхронізації.
- - **Каталог стану Linux на SD або eMMC**: попереджає, коли стан визначається на джерелі монтування `mmcblk*`, оскільки випадковий ввід-вивід на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сеансів і облікових даних.
- - **Відсутні каталоги сеансів**: `sessions/` і каталог сховища сеансів потрібні для збереження історії та уникнення збоїв `ENOENT`.
- - **Невідповідність транскрипту**: попереджає, коли в нещодавніх записах сеансів відсутні файли транскриптів.
+ - **Каталог стану macOS, синхронізований із хмарою**: попереджає, коли стан розв’язується всередині iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, оскільки шляхи з синхронізацією можуть спричиняти повільніше I/O та перегони блокувань/синхронізації.
+ - **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розв’язується до джерела монтування `mmcblk*`, оскільки випадкове I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сеансів та облікових даних.
+ - **Каталоги сеансів відсутні**: `sessions/` і каталог сховища сеансів потрібні для збереження історії та уникнення збоїв `ENOENT`.
+ - **Невідповідність транскрипту**: попереджає, коли в недавніх записах сеансів бракує файлів транскрипту.
- **Основний сеанс "1-line JSONL"**: позначає випадки, коли основний транскрипт має лише один рядок (історія не накопичується).
- - **Кілька каталогів стану**: попереджає, коли кілька папок `~/.openclaw` існують у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує на інше місце (історія може розділятися між встановленнями).
- - **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запускати його на віддаленому хості (стан зберігається там).
- - **Дозволи файлу конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/усім, і пропонує звузити дозволи до `600`.
+ - **Кілька каталогів стану**: попереджає, коли кілька папок `~/.openclaw` існують у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує деінде (історія може розділитися між інсталяціями).
+ - **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, лікар нагадує запустити його на віддаленому хості (стан живе там).
+ - **Дозволи конфігураційного файла**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групі/усім, і пропонує посилити дозволи до `600`.
-
- Doctor перевіряє профілі OAuth у сховищі автентифікації, попереджає, коли токени скоро закінчаться або вже закінчилися, і може безпечно оновити їх, коли це можливо. Якщо профіль OAuth/токена Anthropic застарів, він пропонує ключ API Anthropic або шлях setup-token Anthropic. Запити на оновлення зʼявляються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення.
+
+ Лікар перевіряє OAuth-профілі в сховищі автентифікації, попереджає, коли токени скоро закінчаться або вже закінчилися, і може оновити їх, коли це безпечно. Якщо OAuth/токен-профіль Anthropic застарів, він пропонує ключ API Anthropic або шлях setup-token Anthropic. Запити на оновлення з’являються лише під час інтерактивного запуску (TTY); `--non-interactive` пропускає спроби оновлення.
- Коли оновлення OAuth остаточно завершується помилкою (наприклад `refresh_token_reused`, `invalid_grant` або провайдер повідомляє, що потрібно знову ввійти), doctor повідомляє, що потрібна повторна автентифікація, і друкує точну команду `openclaw models auth login --provider ...`, яку треба виконати.
+ Коли оновлення OAuth остаточно не вдається (наприклад, `refresh_token_reused`, `invalid_grant` або провайдер каже увійти знову), лікар повідомляє, що потрібна повторна автентифікація, і друкує точну команду `openclaw models auth login --provider ...`, яку треба виконати.
- Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні через:
+ Лікар також повідомляє про профілі автентифікації, які тимчасово непридатні через:
- - короткі періоди очікування (ліміти частоти/тайм-аути/помилки автентифікації)
- - довші вимкнення (помилки білінгу/кредитів)
+ - короткі періоди очікування (ліміти швидкості/тайм-аути/збої автентифікації)
+ - триваліші вимкнення (збої білінгу/кредитів)
-
- Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель за каталогом і allowlist та попереджає, коли воно не розвʼязується або заборонене.
+
+ Якщо `hooks.gmail.model` задано, лікар перевіряє посилання на модель за каталогом і списком дозволених та попереджає, коли його неможливо розв’язати або воно заборонене.
-
- Коли пісочницю ввімкнено, doctor перевіряє образи Docker і пропонує зібрати образ або перемкнутися на застарілі назви, якщо поточний образ відсутній.
+
+ Коли пісочницю ввімкнено, лікар перевіряє Docker-образи та пропонує зібрати або перемкнутися на застарілі назви, якщо поточний образ відсутній.
- Doctor видаляє застарілий стан проміжного розміщення залежностей Plugin, згенерований OpenClaw, у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Це охоплює застарілі згенеровані корені залежностей, старі каталоги етапу встановлення та локальні для пакета залишки від попереднього коду відновлення залежностей bundled-plugin.
+ Лікар видаляє застарілий створений OpenClaw проміжний стан залежностей Plugin у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Це охоплює застарілі згенеровані корені залежностей, старі каталоги етапу встановлення та локальні для пакета залишки від попереднього коду виправлення залежностей вбудованих Plugin.
- Doctor також може повторно встановити налаштовані завантажувані plugins, коли конфігурація посилається на них, але локальний реєстр Plugin не може їх знайти. Запуск Gateway і перезавантаження конфігурації не запускають менеджери пакетів; встановлення Plugin залишаються явною роботою doctor/install/update.
+ Лікар також може повторно встановити налаштовані завантажувані plugins, коли конфігурація посилається на них, але локальний реєстр plugin не може їх знайти. Запуск Gateway і перезавантаження конфігурації не запускають менеджери пакетів; установлення plugin лишається явною роботою doctor/install/update.
-
- Doctor виявляє застарілі служби Gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити службу OpenClaw із поточним портом Gateway. Він також може сканувати додаткові служби, схожі на Gateway, і друкувати підказки з очищення. Служби Gateway OpenClaw із назвами профілів вважаються повноцінними й не позначаються як "зайві."
+
+ Лікар виявляє застарілі сервіси gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити сервіс OpenClaw з використанням поточного порту gateway. Він також може сканувати додаткові сервіси, схожі на gateway, і друкувати підказки з очищення. Сервіси OpenClaw gateway, названі за профілем, вважаються повноцінними і не позначаються як "додаткові".
- На Linux, якщо служба Gateway рівня користувача відсутня, але існує служба Gateway OpenClaw рівня системи, doctor не встановлює автоматично другу службу рівня користувача. Перевірте через `openclaw gateway status --deep` або `openclaw doctor --deep`, потім видаліть дублікат або встановіть `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли системний супервізор керує життєвим циклом Gateway.
+ У Linux, якщо сервіс gateway рівня користувача відсутній, але сервіс OpenClaw gateway системного рівня існує, лікар не встановлює другий сервіс рівня користувача автоматично. Перевірте за допомогою `openclaw gateway status --deep` або `openclaw doctor --deep`, а потім видаліть дублікат або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, коли системний супервізор керує життєвим циклом gateway.
- Коли обліковий запис каналу Matrix має очікувану або придатну до виконання міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім виконує найкращі доступні кроки міграції: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а запуск продовжується. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається.
+ Коли обліковий запис каналу Matrix має очікувану або придатну до дії міграцію застарілого стану, лікар (у режимі `--fix` / `--repair`) створює знімок перед міграцією, а потім виконує міграційні кроки з найкращим зусиллям: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, і запуск продовжується. У режимі лише для читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається.
-
- Doctor тепер перевіряє стан спарювання пристроїв як частину звичайної перевірки працездатності.
+
+ Тепер лікар перевіряє стан сполучення пристроїв як частину звичайного проходу перевірки стану.
Що він повідомляє:
- - очікувані запити першого спарювання
- - очікувані підвищення ролей для вже спарених пристроїв
- - очікувані підвищення scopes для вже спарених пристроїв
- - виправлення невідповідності відкритого ключа, коли id пристрою все ще збігається, але ідентичність пристрою більше не збігається із затвердженим записом
- - спарені записи без активного токена для затвердженої ролі
- - спарені токени, scopes яких відхилилися від затвердженої бази спарювання
- - локальні кешовані записи device-token для поточної машини, створені до ротації токена на боці Gateway або з застарілими метаданими scope
+ - очікувані запити першого сполучення
+ - очікувані підвищення ролей для вже сполучених пристроїв
+ - очікувані підвищення scope для вже сполучених пристроїв
+ - виправлення невідповідності публічного ключа, коли ідентифікатор пристрою все ще збігається, але ідентичність пристрою більше не збігається із затвердженим записом
+ - сполучені записи, у яких відсутній активний токен для затвердженої ролі
+ - сполучені токени, чиї scopes відхиляються за межі затвердженої базової лінії сполучення
+ - локально кешовані записи device-token для поточної машини, які передують ротації токена на боці gateway або містять застарілі метадані scope
- Doctor не затверджує автоматично запити на спарювання і не ротує автоматично токени пристроїв. Натомість він друкує точні наступні кроки:
+ Лікар не затверджує запити на сполучення автоматично і не обертає токени пристроїв автоматично. Натомість він друкує точні наступні кроки:
- - переглянути очікувані запити через `openclaw devices list`
- - затвердити точний запит через `openclaw devices approve `
- - згенерувати свіжий токен через `openclaw devices rotate --device --role `
- - видалити й повторно затвердити застарілий запис через `openclaw devices remove `
+ - перегляньте очікувані запити за допомогою `openclaw devices list`
+ - затвердьте точний запит за допомогою `openclaw devices approve `
+ - оберніть свіжий токен за допомогою `openclaw devices rotate --device --role `
+ - видаліть і повторно затвердьте застарілий запис за допомогою `openclaw devices remove `
- Це закриває поширену прогалину "пристрій уже спарено, але все ще потрібно спарювання": doctor тепер відрізняє перше спарювання від очікуваних підвищень ролі/scope і від застарілого дрейфу токена/ідентичності пристрою.
+ Це закриває поширену прогалину "already paired but still getting pairing required": тепер лікар відрізняє перше сполучення від очікуваних підвищень ролі/scope і від дрейфу застарілого токена/ідентичності пристрою.
- Doctor виводить попередження, коли провайдер відкритий для особистих повідомлень без allowlist або коли політику налаштовано небезпечно.
+ Лікар видає попередження, коли провайдер відкритий для DM без списку дозволених або коли політику налаштовано небезпечно.
- Якщо запущено як користувацьку службу systemd, doctor забезпечує ввімкнення lingering, щоб Gateway залишався активним після виходу з облікового запису.
+ Якщо запущено як користувацький сервіс systemd, лікар гарантує, що lingering увімкнено, щоб gateway залишався активним після виходу з системи.
- Doctor друкує підсумок стану робочого простору для типового агента:
+ Лікар друкує підсумок стану робочого простору для агента за замовчуванням:
- - **Стан Skills**: підраховує придатні, з відсутніми вимогами та заблоковані allowlist skills.
+ - **Стан Skills**: рахує skills, які відповідають вимогам, мають відсутні вимоги та заблоковані списком дозволених.
- **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору існують поруч із поточним робочим простором.
- - **Стан Plugin**: підраховує ввімкнені/вимкнені/помилкові plugins; перелічує ID Plugin для будь-яких помилок; повідомляє можливості bundle Plugin.
- - **Попередження сумісності Plugin**: позначає plugins, які мають проблеми сумісності з поточним середовищем виконання.
- - **Діагностика Plugin**: показує будь-які попередження або помилки часу завантаження, виведені реєстром Plugin.
+ - **Стан Plugin**: рахує ввімкнені/вимкнені/помилкові plugins; перелічує ідентифікатори plugin для будь-яких помилок; повідомляє можливості bundle plugin.
+ - **Попередження сумісності Plugin**: позначає plugins, які мають проблеми сумісності з поточним runtime.
+ - **Діагностика Plugin**: показує будь-які попередження або помилки під час завантаження, видані реєстром plugin.
-
- Doctor перевіряє, чи файли bootstrap робочого простору (наприклад `AGENTS.md`, `CLAUDE.md` або інші вставлені контекстні файли) близькі до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файлу сирі та вставлені кількості символів, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість вставлених символів як частку загального бюджету. Коли файли обрізано або вони близькі до ліміту, doctor друкує поради з налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`.
+
+ Лікар перевіряє, чи bootstrap-файли робочого простору (наприклад, `AGENTS.md`, `CLAUDE.md` або інші вставлені контекстні файли) наближаються до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файла сирі та вставлені кількості символів, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість вставлених символів як частку загального бюджету. Коли файли обрізано або вони наближаються до ліміту, лікар друкує поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`.
-
- Коли `openclaw doctor --fix` видаляє відсутній Plugin каналу, він також видаляє завислу конфігурацію в межах каналу, яка посилалася на цей Plugin: записи `channels.`, цілі Heartbeat, що називали канал, і перевизначення `agents.*.models["/*"]`. Це запобігає циклам запуску Gateway, коли середовище виконання каналу зникло, але конфігурація все ще просить Gateway привʼязатися до нього.
+
+ Коли `openclaw doctor --fix` видаляє відсутній channel plugin, він також видаляє висячу конфігурацію в області каналу, яка посилалася на цей plugin: записи `channels.`, цілі heartbeat, що називали канал, і перевизначення `agents.*.models["/*"]`. Це запобігає циклам завантаження Gateway, коли runtime каналу зник, але конфігурація все ще просить gateway прив’язатися до нього.
- Doctor перевіряє, чи встановлено автодоповнення клавішею Tab для поточної оболонки (zsh, bash, fish або PowerShell):
+ Лікар перевіряє, чи встановлено автодоповнення табуляцією для поточної оболонки (zsh, bash, fish або PowerShell):
- - Якщо профіль оболонки використовує повільний динамічний шаблон доповнення (`source <(openclaw completion ...)`), doctor оновлює його до швидшого варіанта з кешованим файлом.
- - Якщо доповнення налаштовано в профілі, але файл кешу відсутній, doctor автоматично регенерує кеш.
- - Якщо доповнення взагалі не налаштовано, doctor пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`).
+ - Якщо профіль оболонки використовує повільний динамічний шаблон автодоповнення (`source <(openclaw completion ...)`), лікар оновлює його до швидшого варіанта з кешованим файлом.
+ - Якщо автодоповнення налаштовано в профілі, але файл кешу відсутній, лікар автоматично повторно генерує кеш.
+ - Якщо автодоповнення взагалі не налаштовано, лікар пропонує встановити його (лише інтерактивний режим; пропускається з `--non-interactive`).
- Запустіть `openclaw completion --write-state`, щоб регенерувати кеш вручну.
+ Запустіть `openclaw completion --write-state`, щоб повторно згенерувати кеш вручну.
- Doctor перевіряє готовність автентифікації локального токена Gateway.
+ Лікар перевіряє готовність автентифікації локального gateway токеном.
- - Якщо режим токена потребує токена, а джерела токена немає, doctor пропонує згенерувати його.
- - Якщо `gateway.auth.token` керується SecretRef, але недоступний, doctor попереджає і не перезаписує його відкритим текстом.
- - `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано SecretRef токена.
+ - Якщо режим токена потребує токен, а джерела токена немає, лікар пропонує згенерувати його.
+ - Якщо `gateway.auth.token` керується SecretRef, але недоступний, лікар попереджає і не перезаписує його відкритим текстом.
+ - `openclaw doctor --generate-gateway-token` примусово генерує лише тоді, коли не налаштовано SecretRef для токена.
-
- Деякі потоки відновлення мають перевіряти налаштовані облікові дані без послаблення поведінки швидкого збою під час виконання.
+
+ Деякі потоки виправлення мають перевіряти налаштовані облікові дані без послаблення runtime-поведінки швидкого збою.
- `openclaw doctor --fix` тепер використовує ту саму модель підсумку SecretRef лише для читання, що й команди сімейства status, для цільових виправлень конфігурації.
- - Приклад: відновлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використовувати налаштовані облікові дані бота, коли вони доступні.
- - Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розвʼязання замість збою або хибного повідомлення про відсутній токен.
+ - Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використати налаштовані облікові дані бота, коли вони доступні.
+ - Якщо токен бота Telegram налаштовано через SecretRef, але він недоступний у поточному шляху команди, лікар повідомляє, що облікові дані налаштовані, але недоступні, і пропускає автоматичне розв’язання замість аварійного завершення або помилкового повідомлення про відсутній токен.
- Doctor виконує перевірку стану й пропонує перезапустити Gateway, коли він виглядає несправним.
+ Лікар виконує перевірку стану і пропонує перезапустити gateway, коли він виглядає несправним.
-
- Doctor перевіряє, чи налаштований провайдер embedding для пошуку памʼяті готовий для типового агента. Поведінка залежить від налаштованого бекенда й провайдера:
+
+ Лікар перевіряє, чи налаштований провайдер embedding для пошуку в пам’яті готовий для агента за замовчуванням. Поведінка залежить від налаштованого backend і провайдера:
- - **Бекенд QMD**: перевіряє, чи доступний і придатний до запуску бінарний файл `qmd`. Якщо ні, друкує вказівки з виправлення, включно з пакетом npm і варіантом ручного шляху до бінарного файла.
- - **Явний локальний провайдер**: перевіряє наявність локального файлу моделі або розпізнаної віддаленої/завантажуваної URL-адреси моделі. Якщо відсутня, пропонує перемкнутися на віддаленого провайдера.
- - **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи ключ API присутній у середовищі або сховищі автентифікації. Друкує дієві підказки з виправлення, якщо його немає.
+ - **Бекенд QMD**: перевіряє, чи доступний і чи може запускатися виконуваний файл `qmd`. Якщо ні, виводить інструкції з виправлення, зокрема npm-пакет і варіант ручного шляху до бінарного файлу.
+ - **Явний локальний провайдер**: перевіряє наявність локального файла моделі або розпізнаної URL-адреси віддаленої/завантажуваної моделі. Якщо відсутній, пропонує перейти на віддаленого провайдера.
+ - **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє наявність API-ключа в середовищі або сховищі автентифікації. Якщо ключ відсутній, виводить дієві підказки для виправлення.
- **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, потім пробує кожного віддаленого провайдера в порядку автоматичного вибору.
- Коли доступний кешований результат зондування Gateway (Gateway був справний на момент перевірки), doctor зіставляє його результат із конфігурацією, видимою для CLI, і зазначає будь-які розбіжності. Doctor не запускає новий ping embedding у типовому шляху; використовуйте глибоку команду стану памʼяті, коли потрібна жива перевірка провайдера.
+ Коли доступний кешований результат перевірки Gateway (Gateway був справним на момент перевірки), doctor зіставляє його результат із конфігурацією, видимою для CLI, і зазначає будь-які розбіжності. Doctor не запускає новий ping вбудовувань на типовому шляху; використовуйте команду глибокого статусу пам’яті, коли потрібна жива перевірка провайдера.
- Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embedding під час виконання.
+ Використовуйте `openclaw memory status --deep`, щоб перевірити готовність вбудовувань під час виконання.
-
- Якщо gateway справний, doctor запускає перевірку стану каналу й повідомляє про попередження із запропонованими виправленнями.
+
+ Якщо Gateway справний, doctor запускає перевірку статусу каналів і повідомляє попередження із запропонованими виправленнями.
-
- Doctor перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутні або застарілі стандартні налаштування (наприклад, залежності systemd від network-online і затримку перезапуску). Коли він знаходить невідповідність, рекомендує оновлення й може переписати service file/task до поточних стандартних налаштувань.
+
+ Doctor перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутні або застарілі типові значення (наприклад, залежності systemd від network-online і затримку перезапуску). Коли він знаходить невідповідність, рекомендує оновлення й може переписати файл служби/завдання до поточних типових значень.
Примітки:
- `openclaw doctor` запитує підтвердження перед переписуванням конфігурації супервізора.
- - `openclaw doctor --yes` приймає стандартні запити на відновлення.
+ - `openclaw doctor --yes` приймає типові запити на відновлення.
- `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів.
- `openclaw doctor --repair --force` перезаписує користувацькі конфігурації супервізора.
- - `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби gateway. Він усе ще повідомляє про справність служби й виконує відновлення, не пов’язані зі службою, але пропускає install/start/restart/bootstrap служби, переписування конфігурації супервізора та очищення застарілих служб, бо цим життєвим циклом керує зовнішній супервізор.
- - У Linux doctor не переписує метадані command/entrypoint, доки відповідний systemd gateway unit активний. Він також ігнорує неактивні додаткові gateway-подібні одиниці, що не є застарілими, під час сканування duplicate-service, щоб супровідні service files не створювали зайвий шум очищення.
- - Якщо token auth вимагає token і `gateway.auth.token` керується SecretRef, doctor service install/repair перевіряє SecretRef, але не зберігає розв’язані відкриті значення token у метаданих середовища служби супервізора.
- - Doctor виявляє керовані значення середовища служби на основі `.env`/SecretRef, які старіші інсталяції LaunchAgent, systemd або Windows Scheduled Task вбудували inline, і переписує метадані служби так, щоб ці значення завантажувалися з runtime source замість визначення супервізора.
- - Doctor виявляє, коли команда служби все ще закріплює старий `--port` після зміни `gateway.port`, і переписує метадані служби на поточний порт.
- - Якщо token auth вимагає token, а налаштований token SecretRef не розв’язано, doctor блокує шлях install/repair з практичними вказівками.
- - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує install/repair, доки mode не буде задано явно.
- - Для Linux user-systemd units перевірки розбіжностей token у doctor тепер охоплюють джерела і `Environment=`, і `EnvironmentFile=` під час порівняння service auth metadata.
- - Відновлення служб doctor відмовляються переписувати, зупиняти або перезапускати службу gateway зі старішого бінарного файлу OpenClaw, коли конфігурацію востаннє записала новіша версія. Див. [усунення несправностей Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
+ - `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби Gateway. Він усе ще повідомляє про стан служби й виконує відновлення, не пов’язані зі службою, але пропускає install/start/restart/bootstrap служби, переписування конфігурації супервізора та очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній супервізор.
+ - У Linux doctor не переписує метадані команди/точки входу, доки відповідний systemd-модуль Gateway активний. Він також ігнорує неактивні додаткові модулі, схожі на Gateway і не застарілі, під час пошуку дубльованих служб, щоб супутні файли служб не створювали зайвий шум очищення.
+ - Якщо автентифікація токеном вимагає токен і `gateway.auth.token` керується SecretRef, встановлення/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення токена відкритим текстом у метаданих середовища служби супервізора.
+ - Doctor виявляє керовані значення середовища служби на основі `.env`/SecretRef, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудували inline, і переписує метадані служби так, щоб ці значення завантажувалися з джерела виконання, а не з визначення супервізора.
+ - Doctor виявляє, коли команда служби досі фіксує старий `--port` після зміни `gateway.port`, і переписує метадані служби на поточний порт.
+ - Якщо автентифікація токеном вимагає токен, а налаштований SecretRef токена не розв’язано, doctor блокує шлях встановлення/відновлення з дієвими інструкціями.
+ - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, doctor блокує встановлення/відновлення, доки режим не буде задано явно.
+ - Для користувацьких systemd-модулів Linux перевірки дрейфу токена doctor тепер враховують як джерела `Environment=`, так і `EnvironmentFile=` під час порівняння метаданих автентифікації служби.
+ - Відновлення служби doctor відмовляються переписувати, зупиняти або перезапускати службу Gateway зі старішого бінарного файла OpenClaw, коли конфігурацію востаннє було записано новішою версією. Див. [усунення неполадок Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard).
- Ви завжди можете примусово виконати повне переписування через `openclaw gateway install --force`.
-
- Doctor перевіряє runtime служби (PID, останній exit status) і попереджає, коли службу встановлено, але вона фактично не працює. Він також перевіряє конфлікти портів на порту gateway (стандартно `18789`) і повідомляє про ймовірні причини (gateway already running, SSH tunnel).
+
+ Doctor перевіряє середовище виконання служби (PID, останній статус виходу) і попереджає, коли служба встановлена, але фактично не працює. Він також перевіряє конфлікти портів на порту Gateway (типово `18789`) і повідомляє ймовірні причини (Gateway уже працює, SSH-тунель).
-
- Doctor попереджає, коли служба gateway працює на Bun або шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджерів версій можуть ламатися після оновлень, бо служба не завантажує ваш shell init. Doctor пропонує мігрувати на системну інсталяцію Node, коли вона доступна (Homebrew/apt/choco).
+
+ Doctor попереджає, коли служба Gateway працює на Bun або шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджерів версій можуть ламатися після оновлень, оскільки служба не завантажує ініціалізацію вашої оболонки. Doctor пропонує мігрувати на системне встановлення Node, коли воно доступне (Homebrew/apt/choco).
- Нововстановлені або відновлені служби зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні каталоги user-bin, але вгадані fallback-каталоги менеджера версій записуються до service PATH лише тоді, коли ці каталоги існують на диску. Це утримує згенерований supervisor PATH узгодженим із тим самим аудитом minimal-PATH, який doctor запускає пізніше.
+ Нововстановлені або відновлені служби зберігають явні корені середовища (`NVM_DIR`, `FNM_DIR`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `BUN_INSTALL`, `PNPM_HOME`) і стабільні користувацькі каталоги bin, але припущені резервні каталоги менеджерів версій записуються в PATH служби лише тоді, коли ці каталоги існують на диску. Це узгоджує згенерований PATH супервізора з тим самим аудитом мінімального PATH, який doctor запускає пізніше.
-
- Doctor зберігає будь-які зміни конфігурації та ставить мітку метаданих майстра, щоб зафіксувати запуск doctor.
+
+ Doctor зберігає будь-які зміни конфігурації та ставить позначку в метаданих майстра, щоб зафіксувати запуск doctor.
-
- Doctor пропонує систему пам’яті workspace, коли її бракує, і виводить пораду щодо резервного копіювання, якщо workspace ще не перебуває під git.
+
+ Doctor пропонує систему пам’яті робочого простору, коли її бракує, і виводить пораду щодо резервної копії, якщо робочий простір ще не перебуває під керуванням git.
- Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб отримати повний посібник зі структури workspace і резервного копіювання git (рекомендовано приватний GitHub або GitLab).
+ Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace), щоб отримати повний посібник зі структури робочого простору та резервного копіювання в git (рекомендовано приватний GitHub або GitLab).
## Пов’язане
-- [рунбук Gateway](/uk/gateway)
-- [усунення несправностей Gateway](/uk/gateway/troubleshooting)
+- [Runbook Gateway](/uk/gateway)
+- [Усунення неполадок Gateway](/uk/gateway/troubleshooting)