diff --git a/docs/uk/cli/memory.md b/docs/uk/cli/memory.md index 6227cb988..163cda74c 100644 --- a/docs/uk/cli/memory.md +++ b/docs/uk/cli/memory.md @@ -1,30 +1,30 @@ --- read_when: - Ви хочете індексувати або шукати семантичну пам’ять - - Ви налагоджуєте доступність пам’яті або індексацію - - Ви хочете перенести відновлену короткострокову пам’ять до `MEMORY.md` -summary: Довідник CLI для `openclaw memory` (status/index/search/promote/promote-explain/rem-harness) + - Ви налагоджуєте доступність пам’яті або індексування + - Ви хочете перенести відновлену короткочасну пам’ять до `MEMORY.md` +summary: Довідка CLI для `openclaw memory` (status/index/search/promote/promote-explain/rem-harness) title: Пам’ять x-i18n: - generated_at: "2026-04-24T04:12:35Z" + generated_at: "2026-04-27T12:59:58Z" model: gpt-5.4 provider: openai - source_hash: 4bcb1af05ecddceef7cd1d3244c8f0e4fc740d6d41fc5e9daa37177d1bfe3674 + source_hash: 965bcd0373e0146a0b1dac7e8166cab84e0d368c1d7d186e78a335f971917974 source_path: cli/memory.md workflow: 15 --- # `openclaw memory` -Керування індексацією та пошуком семантичної пам’яті. -Надається активним Plugin пам’яті (типово: `memory-core`; установіть `plugins.slots.memory = "none"`, щоб вимкнути). +Керує індексуванням і пошуком семантичної пам’яті. +Надається активним плагіном пам’яті (типово: `memory-core`; установіть `plugins.slots.memory = "none"`, щоб вимкнути). Пов’язане: -- Концепція пам’яті: [Memory](/uk/concepts/memory) -- Вікі пам’яті: [Memory Wiki](/uk/plugins/memory-wiki) -- Wiki CLI: [wiki](/uk/cli/wiki) -- Plugins: [Plugins](/uk/tools/plugin) +- Концепція Memory: [Пам’ять](/uk/concepts/memory) +- Вікі Memory: [Вікі пам’яті](/uk/plugins/memory-wiki) +- CLI вікі: [wiki](/uk/cli/wiki) +- Плагіни: [Плагіни](/uk/tools/plugin) ## Приклади @@ -53,61 +53,61 @@ openclaw memory index --agent main --verbose `memory status` і `memory index`: -- `--agent `: обмежити одним агентом. Без цього ці команди виконуються для кожного налаштованого агента; якщо список агентів не налаштовано, вони повертаються до типового агента. -- `--verbose`: виводити докладні журнали під час перевірок та індексації. +- `--agent `: обмежити одним агентом. Без цього параметра ці команди виконуються для кожного налаштованого агента; якщо список агентів не налаштовано, вони повертаються до типового агента. +- `--verbose`: виводити докладні журнали під час перевірок та індексування. `memory status`: -- `--deep`: перевірити доступність векторів і embeddings. -- `--index`: виконати повторну індексацію, якщо сховище брудне (має на увазі `--deep`). -- `--fix`: виправити застарілі блокування recall і нормалізувати метадані promotion. -- `--json`: вивести JSON. +- `--deep`: перевірити доступність векторів і embedding. Звичайна команда `memory status` залишається швидкою і не виконує живий ping embedding. +- `--index`: виконати повторне індексування, якщо сховище забруднене (має на увазі `--deep`). +- `--fix`: виправити застарілі блокування recall і нормалізувати метадані перенесення. +- `--json`: вивести результат у форматі JSON. -Якщо `memory status` показує `Dreaming status: blocked`, керований Cron для dreaming увімкнено, але heartbeat, який його запускає, не спрацьовує для типового агента. Див. [Dreaming never runs](/uk/concepts/dreaming#dreaming-never-runs-status-shows-blocked) щодо двох поширених причин. +Якщо `memory status` показує `Dreaming status: blocked`, це означає, що керований Cron Dreaming увімкнено, але Heartbeat, який його запускає, не спрацьовує для типового агента. Див. [Dreaming never runs](/uk/concepts/dreaming#dreaming-never-runs-status-shows-blocked) для двох найпоширеніших причин. `memory index`: -- `--force`: примусово виконати повну повторну індексацію. +- `--force`: примусово виконати повне повторне індексування. `memory search`: - Вхід запиту: передайте або позиційний `[query]`, або `--query `. -- Якщо вказано обидва, `--query` має пріоритет. -- Якщо не вказано жодного, команда завершується з помилкою. +- Якщо передано обидва, перевагу має `--query`. +- Якщо не передано жодного, команда завершується з помилкою. - `--agent `: обмежити одним агентом (типово: типовий агент). - `--max-results `: обмежити кількість повернених результатів. -- `--min-score `: відфільтрувати збіги з низькою оцінкою. -- `--json`: вивести результати у JSON. +- `--min-score `: відфільтрувати збіги з низьким балом. +- `--json`: вивести результати у форматі JSON. `memory promote`: -Попередній перегляд і застосування promotion короткострокової пам’яті. +Попередній перегляд і застосування перенесення короткочасної пам’яті. ```bash openclaw memory promote [--apply] [--limit ] [--include-promoted] ``` -- `--apply` -- записати promotion до `MEMORY.md` (типово: лише попередній перегляд). +- `--apply` -- записати перенесення до `MEMORY.md` (типово: лише попередній перегляд). - `--limit ` -- обмежити кількість показаних кандидатів. -- `--include-promoted` -- включити записи, уже promoted у попередніх циклах. +- `--include-promoted` -- включити записи, уже перенесені в попередніх циклах. Повні параметри: -- Ранжує короткострокових кандидатів із `memory/YYYY-MM-DD.md` за допомогою зважених сигналів promotion (`frequency`, `relevance`, `query diversity`, `recency`, `consolidation`, `conceptual richness`). -- Використовує короткострокові сигнали як із memory recalls, так і з щоденних проходів ingestion, а також легкі сигнали підкріплення з фаз light/REM. -- Коли dreaming увімкнено, `memory-core` автоматично керує одним завданням Cron, яке запускає повний цикл (`light -> REM -> deep`) у фоновому режимі (ручний `openclaw cron add` не потрібен). +- Ранжує короткочасних кандидатів із `memory/YYYY-MM-DD.md` за допомогою зважених сигналів перенесення (`frequency`, `relevance`, `query diversity`, `recency`, `consolidation`, `conceptual richness`). +- Використовує короткочасні сигнали як із recall пам’яті, так і з щоденних проходів ingest, а також легкі сигнали підкріплення фаз light/REM. +- Коли Dreaming увімкнено, `memory-core` автоматично керує одним завданням Cron, яке запускає повний цикл (`light -> REM -> deep`) у фоновому режимі (ручне `openclaw cron add` не потрібне). - `--agent `: обмежити одним агентом (типово: типовий агент). - `--limit `: максимальна кількість кандидатів для повернення/застосування. -- `--min-score `: мінімальна зважена оцінка promotion. +- `--min-score `: мінімальний зважений бал перенесення. - `--min-recall-count `: мінімальна кількість recall, потрібна для кандидата. -- `--min-unique-queries `: мінімальна кількість різних запитів, потрібна для кандидата. -- `--apply`: додати вибраних кандидатів до `MEMORY.md` і позначити їх як promoted. -- `--include-promoted`: включити вже promoted кандидатів у вивід. -- `--json`: вивести JSON. +- `--min-unique-queries `: мінімальна кількість унікальних запитів, потрібна для кандидата. +- `--apply`: додати вибраних кандидатів до `MEMORY.md` і позначити їх як перенесені. +- `--include-promoted`: включити до виводу кандидатів, уже перенесених раніше. +- `--json`: вивести результат у форматі JSON. `memory promote-explain`: -Пояснити конкретного кандидата на promotion і розбивку його оцінки. +Пояснити конкретного кандидата на перенесення і розбивку його оцінки. ```bash openclaw memory promote-explain [--agent ] [--include-promoted] [--json] @@ -115,35 +115,35 @@ openclaw memory promote-explain [--agent ] [--include-promoted] [ - ``: ключ кандидата, фрагмент шляху або фрагмент уривка для пошуку. - `--agent `: обмежити одним агентом (типово: типовий агент). -- `--include-promoted`: включити вже promoted кандидатів. -- `--json`: вивести JSON. +- `--include-promoted`: включити вже перенесених кандидатів. +- `--json`: вивести результат у форматі JSON. `memory rem-harness`: -Попередній перегляд REM-рефлексій, кандидатів на істини та виводу deep promotion без будь-якого запису. +Попередньо переглянути REM-рефлексії, кандидатів на істини та результат deep-перенесення без жодного запису. ```bash openclaw memory rem-harness [--agent ] [--include-promoted] [--json] ``` - `--agent `: обмежити одним агентом (типово: типовий агент). -- `--include-promoted`: включити вже promoted deep-кандидатів. -- `--json`: вивести JSON. +- `--include-promoted`: включити вже перенесених deep-кандидатів. +- `--json`: вивести результат у форматі JSON. ## Dreaming -Dreaming — це фонова система консолідації пам’яті з трьома взаємодіючими -фазами: **light** (сортування/підготовка короткострокового матеріалу), **deep** (promotion стійких -фактів до `MEMORY.md`) і **REM** (рефлексія та виявлення тем). +Dreaming — це фонова система консолідації пам’яті з трьома кооперативними +фазами: **light** (сортування/підготовка короткочасного матеріалу), **deep** (перенесення +стійких фактів до `MEMORY.md`) і **REM** (рефлексія та виявлення тем). - Увімкніть через `plugins.entries.memory-core.config.dreaming.enabled: true`. -- Перемикайте з чату через `/dreaming on|off` (або переглядайте через `/dreaming status`). +- Перемикайте з чату командою `/dreaming on|off` (або переглядайте через `/dreaming status`). - Dreaming працює за одним керованим розкладом циклів (`dreaming.frequency`) і виконує фази в порядку: light, REM, deep. - Лише фаза deep записує стійку пам’ять до `MEMORY.md`. -- Людинозрозумілий вивід фаз і записи щоденника записуються до `DREAMS.md` (або наявного `dreams.md`), з необов’язковими пофазними звітами в `memory/dreaming//YYYY-MM-DD.md`. -- Ранжування використовує зважені сигнали: частота recall, релевантність retrieval, різноманітність запитів, часова актуальність, консолідація між днями та похідна концептуальна насиченість. -- Promotion повторно читає live-щоденну нотатку перед записом у `MEMORY.md`, тому відредаговані або видалені короткострокові фрагменти не потрапляють у promotion зі застарілих знімків сховища recall. -- Заплановані й ручні запуски `memory promote` використовують однакові типові параметри фази deep, якщо ви не передасте перевизначення порогів через CLI. +- Зрозумілий для людини вивід фаз і записи щоденника записуються до `DREAMS.md` (або наявного `dreams.md`), з необов’язковими звітами по фазах у `memory/dreaming//YYYY-MM-DD.md`. +- Ранжування використовує зважені сигнали: частоту recall, релевантність отримання, різноманітність запитів, часову давність, консолідацію між днями та похідну концептуальну насиченість. +- Перед записом до `MEMORY.md` перенесення повторно зчитує актуальну щоденну нотатку, тож відредаговані або видалені короткочасні уривки не будуть перенесені зі застарілих знімків сховища recall. +- Заплановані й ручні запуски `memory promote` використовують однакові типові значення фази deep, якщо ви не передасте перевизначення порогів через CLI. - Автоматичні запуски розподіляються між налаштованими робочими просторами пам’яті. Типовий розклад: @@ -171,18 +171,18 @@ Dreaming — це фонова система консолідації пам’ Примітки: -- `memory index --verbose` виводить деталі по фазах (provider, model, sources, активність пакетів). -- `memory status` включає будь-які додаткові шляхи, налаштовані через `memorySearch.extraPaths`. -- Якщо поля ключів віддаленого API для фактично активної пам’яті налаштовані як SecretRef, команда розв’язує ці значення з активного знімка Gateway. Якщо Gateway недоступний, команда швидко завершується з помилкою. -- Примітка щодо розходження версій Gateway: цей шлях команди потребує Gateway, який підтримує `secrets.resolve`; старіші Gateway повертають помилку unknown-method. -- Налаштовуйте частоту запланованих циклів через `dreaming.frequency`. Політика deep promotion в іншому разі є внутрішньою; використовуйте прапорці CLI у `memory promote`, коли потрібні разові ручні перевизначення. -- `memory rem-harness --path --grounded` виконує попередній перегляд grounded `What Happened`, `Reflections` і `Possible Lasting Updates` з історичних щоденних нотаток без будь-якого запису. -- `memory rem-backfill --path ` записує зворотні grounded-записи щоденника до `DREAMS.md` для перегляду в UI. -- `memory rem-backfill --path --stage-short-term` також засіває grounded-стійких кандидатів у live-сховище promotion короткострокової пам’яті, щоб звичайна фаза deep могла їх ранжувати. -- `memory rem-backfill --rollback` видаляє раніше записані grounded-записи щоденника, а `memory rem-backfill --rollback-short-term` видаляє раніше підготовлених grounded-кандидатів короткострокової пам’яті. -- Див. [Dreaming](/uk/concepts/dreaming) для повних описів фаз і довідника з конфігурації. +- `memory index --verbose` виводить подробиці по фазах (провайдер, модель, джерела, активність пакетів). +- `memory status` включає всі додаткові шляхи, налаштовані через `memorySearch.extraPaths`. +- Якщо фактично активні поля ключів віддаленого API пам’яті налаштовані як SecretRefs, команда розв’язує ці значення з активного знімка Gateway. Якщо Gateway недоступний, команда завершується помилкою одразу. +- Примітка щодо розсинхронізації версій Gateway: цей шлях команди потребує Gateway, який підтримує `secrets.resolve`; старіші Gateway повертають помилку unknown-method. +- Налаштовуйте частоту запланованих циклів через `dreaming.frequency`. Політика deep-перенесення інакше є внутрішньою; використовуйте прапорці CLI в `memory promote`, коли потрібні одноразові ручні перевизначення. +- `memory rem-harness --path --grounded` попередньо переглядає прив’язані до джерела `What Happened`, `Reflections` і `Possible Lasting Updates` з історичних щоденних нотаток без жодного запису. +- `memory rem-backfill --path ` записує зворотні прив’язані до джерела записи щоденника в `DREAMS.md` для перегляду в UI. +- `memory rem-backfill --path --stage-short-term` також додає прив’язаних до джерела стійких кандидатів до активного короткочасного сховища перенесення, щоб звичайна фаза deep могла їх ранжувати. +- `memory rem-backfill --rollback` видаляє раніше записані прив’язані до джерела записи щоденника, а `memory rem-backfill --rollback-short-term` видаляє раніше підготовлених прив’язаних до джерела короткочасних кандидатів. +- Див. [Dreaming](/uk/concepts/dreaming) для повних описів фаз і довідки з конфігурації. ## Пов’язане -- [Довідник CLI](/uk/cli) +- [Довідка CLI](/uk/cli) - [Огляд пам’яті](/uk/concepts/memory) diff --git a/docs/uk/gateway/doctor.md b/docs/uk/gateway/doctor.md index c72d007d9..44c659e07 100644 --- a/docs/uk/gateway/doctor.md +++ b/docs/uk/gateway/doctor.md @@ -3,18 +3,18 @@ read_when: - Додавання або зміна міграцій doctor - Запровадження несумісних змін конфігурації sidebarTitle: Doctor -summary: 'Команда Doctor: перевірки стану, міграції конфігурації та кроки відновлення' +summary: 'Команда doctor: перевірки стану, міграції конфігурації та кроки відновлення' title: Doctor x-i18n: - generated_at: "2026-04-27T12:50:16Z" + generated_at: "2026-04-27T12:59:58Z" model: gpt-5.4 provider: openai - source_hash: 96495b143c6a400892d63e64cc5cd1933c0b500ed5f5b5615a0deb87b04b7d68 + source_hash: 38438465d9751bea6bb87b0fa17d06da19f5cc4487189ee5bcb3791c78c00486 source_path: gateway/doctor.md workflow: 15 --- -`openclaw doctor` — це інструмент відновлення + міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє справність і надає практичні кроки для відновлення. +`openclaw doctor` — це інструмент відновлення + міграції для OpenClaw. Він виправляє застарілу конфігурацію/стан, перевіряє стан системи та надає практичні кроки для відновлення. ## Швидкий старт @@ -22,7 +22,7 @@ x-i18n: openclaw doctor ``` -### Режими без інтерфейсу та автоматизації +### Режими без інтерфейсу та для автоматизації @@ -30,7 +30,7 @@ openclaw doctor openclaw doctor --yes ``` - Прийняти значення за замовчуванням без запитів (зокрема кроки перезапуску/сервісу/sandbox-відновлення, де це застосовно). + Приймає типові значення без запитів (зокрема кроки відновлення перезапуску/служб/пісочниці, де це застосовно). @@ -38,7 +38,7 @@ openclaw doctor openclaw doctor --repair ``` - Застосувати рекомендовані виправлення без запитів (виправлення + перезапуски там, де це безпечно). + Застосовує рекомендовані виправлення без запитів (виправлення + перезапуски, де це безпечно). @@ -46,7 +46,7 @@ openclaw doctor openclaw doctor --repair --force ``` - Застосувати також агресивні виправлення (перезаписує власні конфігурації supervisor). + Також застосовує агресивні виправлення (перезаписує користувацькі конфігурації супервізора). @@ -54,7 +54,7 @@ openclaw doctor openclaw doctor --non-interactive ``` - Запускати без запитів і застосовувати лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії з перезапуском/сервісом/sandbox, які потребують підтвердження людини. Міграції застарілого стану запускаються автоматично, коли їх виявлено. + Працює без запитів і застосовує лише безпечні міграції (нормалізація конфігурації + переміщення стану на диску). Пропускає дії перезапуску/служб/пісочниці, які потребують підтвердження людиною. Міграції застарілого стану виконуються автоматично, якщо їх виявлено. @@ -62,7 +62,7 @@ openclaw doctor openclaw doctor --deep ``` - Просканувати системні сервіси на наявність додаткових встановлень Gateway (launchd/systemd/schtasks). + Сканує системні служби на наявність додаткових інсталяцій Gateway (launchd/systemd/schtasks). @@ -73,78 +73,78 @@ openclaw doctor cat ~/.openclaw/openclaw.json ``` -## Що він робить (підсумок) +## Що він робить (коротко) - - - Необов’язкове попереднє оновлення для git-встановлень (лише інтерактивно). + + - Необов’язкове попереднє оновлення для git-інсталяцій (лише в інтерактивному режимі). - Перевірка актуальності протоколу UI (перебудовує Control UI, якщо схема протоколу новіша). - - Перевірка справності + запит на перезапуск. + - Перевірка стану + запит на перезапуск. - Підсумок стану Skills (доступні/відсутні/заблоковані) і стану плагінів. - Нормалізація конфігурації для застарілих значень. - - Міграція конфігурації Talk із застарілих плоских полів `talk.*` у `talk.provider` + `talk.providers.`. + - Міграція конфігурації Talk із застарілих плоских полів `talk.*` до `talk.provider` + `talk.providers.`. - Перевірки міграції браузера для застарілих конфігурацій розширення Chrome і готовності Chrome MCP. - Попередження про перевизначення провайдера OpenCode (`models.providers.opencode` / `models.providers.opencode-go`). - - Попередження про затінення OAuth Codex (`models.providers.openai-codex`). - - Перевірка передумов TLS для OAuth-профілів OpenAI Codex. - - Міграція застарілого стану на диску (sessions/каталог agent/автентифікація WhatsApp). - - Міграція ключів контрактів маніфесту застарілих плагінів (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). - - Міграція застарілого сховища Cron (`jobId`, `schedule.cron`, поля верхнього рівня delivery/payload, payload `provider`, прості резервні Webhook-завдання `notify: true`). - - Міграція застарілої runtime-policy agent у `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. + - Попередження про затінення Codex OAuth (`models.providers.openai-codex`). + - Перевірка TLS-передумов OAuth для профілів OpenAI Codex OAuth. + - Міграція застарілого стану на диску (сеанси/каталог агента/автентифікація WhatsApp). + - Міграція застарілих ключів контракту маніфесту плагіна (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders` → `contracts`). + - Міграція застарілого сховища Cron (`jobId`, `schedule.cron`, поля delivery/payload верхнього рівня, `provider` у payload, прості резервні завдання Webhook з `notify: true`). + - Міграція застарілої runtime-policy агента до `agents.defaults.agentRuntime` і `agents.list[].agentRuntime`. - Перевірка файлів блокування сеансів і очищення застарілих блокувань. - - Відновлення розшифровок сеансів для дубльованих гілок переписування prompt, створених збірками 2026.4.24, яких це стосується. - - Перевірки цілісності стану та прав доступу (sessions, transcripts, каталог стану). + - Відновлення транскриптів сеансів для дубльованих гілок переписування запитів, створених у збірках 2026.4.24, яких це стосується. + - Перевірки цілісності стану та прав доступу (сеанси, транскрипти, каталог стану). - Перевірки прав доступу до файлу конфігурації (`chmod 600`) під час локального запуску. - - Стан автентифікації моделей: перевіряє завершення строку дії OAuth, може оновлювати токени, термін дії яких спливає, і повідомляє про стани cooldown/disabled профілів автентифікації. + - Стан автентифікації моделей: перевіряє строк дії OAuth, може оновлювати токени, строк дії яких спливає, і повідомляє про стани cooldown/disabled профілю автентифікації. - Виявлення додаткового каталогу робочого простору (`~/openclaw`). - - - Відновлення образу sandbox, коли sandboxing увімкнено. - - Міграція застарілих сервісів і виявлення додаткових Gateway. + + - Відновлення образу пісочниці, якщо ізоляцію увімкнено. + - Міграція застарілих служб і виявлення додаткових Gateway. - Міграція застарілого стану каналу Matrix (у режимі `--fix` / `--repair`). - - Перевірки середовища виконання Gateway (сервіс встановлено, але не запущено; кешована мітка launchd). - - Попередження про стан каналу (перевіряються із запущеного Gateway). - - Аудит конфігурації supervisor (launchd/systemd/schtasks) з необов’язковим відновленням. - - Очищення вбудованого proxy-середовища для сервісів Gateway, які під час встановлення або оновлення захопили значення оболонки `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`. - - Перевірки найкращих практик середовища виконання Gateway (Node проти Bun, шляхи менеджерів версій). + - Перевірки середовища виконання Gateway (службу встановлено, але не запущено; кешована мітка launchd). + - Попередження про стан каналу (зондаж із запущеного Gateway). + - Аудит конфігурації супервізора (launchd/systemd/schtasks) з необов’язковим відновленням. + - Очищення середовища вбудованого проксі для служб Gateway, які підхопили значення оболонки `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` під час інсталяції або оновлення. + - Перевірки рекомендованих практик середовища виконання Gateway (Node чи Bun, шляхи менеджера версій). - Діагностика конфлікту порту Gateway (типово `18789`). - Попередження безпеки для відкритих політик DM. - - Перевірки автентифікації Gateway для режиму локального токена (пропонує створення токена, коли джерело токена відсутнє; не перезаписує конфігурації токенів SecretRef). - - Виявлення проблем зі сполученням пристроїв (очікувані запити першого сполучення, очікувані підвищення ролі/обсягу, дрейф застарілого локального кешу device-token і дрейф автентифікації записів сполучення). + - Перевірки автентифікації Gateway для локального режиму токена (пропонує створення токена, якщо джерела токена немає; не перезаписує конфігурації токенів SecretRef). + - Виявлення проблем зі сполученням пристроїв (очікувані перші запити на сполучення, очікувані оновлення ролей/областей дії, застарілий дрейф локального кешу токенів пристрою та дрейф автентифікації запису сполучення). - - Перевірка linger systemd у Linux. - - Перевірка розміру bootstrap-файла робочого простору (попередження про обрізання/наближення до ліміту для контекстних файлів). + - Перевірка systemd linger на Linux. + - Перевірка розміру bootstrap-файлу робочого простору (попередження про обрізання/наближення до ліміту для контекстних файлів). - Перевірка стану автодоповнення оболонки та автоматичне встановлення/оновлення. - - Перевірка готовності провайдера embeddings для пошуку в пам’яті (локальна модель, віддалений API-ключ або двійковий файл QMD). - - Перевірки встановлення з джерела (невідповідність робочого простору pnpm, відсутні ресурси UI, відсутній двійковий файл tsx). + - Перевірка готовності провайдера ембедингів для пошуку в пам’яті (локальна модель, віддалений API-ключ або бінарний файл QMD). + - Перевірки source-інсталяції (невідповідність робочого простору pnpm, відсутні ресурси UI, відсутній бінарний файл tsx). - Записує оновлену конфігурацію + метадані майстра. -## Backfill і reset у Dreams UI +## Заповнення назад і скидання Dreams UI -Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для процесу grounded Dreaming. Ці дії використовують RPC-методи в стилі gateway doctor, але вони **не** є частиною відновлення/міграції CLI `openclaw doctor`. +Сцена Dreams у Control UI містить дії **Backfill**, **Reset** і **Clear Grounded** для робочого процесу grounded dreaming. Ці дії використовують RPC-методи в стилі doctor Gateway, але вони **не** є частиною відновлення/міграції CLI `openclaw doctor`. Що вони роблять: -- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному робочому просторі, виконує grounded REM diary pass і записує оборотні записи backfill у `DREAMS.md`. -- **Reset** видаляє з `DREAMS.md` лише ці позначені записи щоденника backfill. -- **Clear Grounded** видаляє лише staged grounded-only короткострокові записи, що надійшли з історичного відтворення та ще не накопичили live recall або daily support. +- **Backfill** сканує історичні файли `memory/YYYY-MM-DD.md` в активному робочому просторі, запускає grounded REM diary pass і записує зворотні записи backfill у `DREAMS.md`. +- **Reset** видаляє з `DREAMS.md` лише позначені записи щоденника backfill. +- **Clear Grounded** видаляє лише staged grounded-only короткострокові записи, що походять з історичного відтворення та ще не накопичили live recall або daily support. Чого вони самі по собі **не** роблять: - вони не редагують `MEMORY.md` - вони не запускають повні міграції doctor -- вони не додають автоматично grounded candidates до live short-term promotion store, якщо ви спочатку явно не виконаєте staged CLI path +- вони не автоматично додають grounded candidates до 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 @@ -155,25 +155,25 @@ openclaw memory rem-backfill --path ./memory --stage-short-term ## Детальна поведінка та обґрунтування - - Якщо це 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` у мапу провайдера. + Це також охоплює застарілі плоскі поля Talk. Поточна публічна конфігурація Talk — це `talk.provider` + `talk.providers.`. Doctor переписує старі форми `talk.voiceId` / `talk.voiceAliases` / `talk.modelId` / `talk.outputFormat` / `talk.apiKey` у мапу провайдера. - - Коли конфігурація містить застарілі ключі, інші команди відмовляються виконуватися і просять вас запустити `openclaw doctor`. + + Коли конфігурація містить застарілі ключі, інші команди відмовляються запускатися і просять вас виконати `openclaw doctor`. Doctor: - Пояснить, які застарілі ключі було знайдено. - - Покажє застосовану міграцію. - - Перезапише `~/.openclaw/openclaw.json` за оновленою схемою. + - Покажет міграцію, яку він застосував. + - Перезапише `~/.openclaw/openclaw.json` оновленою схемою. - Gateway також автоматично запускає міграції doctor під час старту, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації виправляються без ручного втручання. Міграції сховища Cron обробляються через `openclaw doctor --fix`. + Gateway також автоматично запускає міграції doctor під час старту, коли виявляє застарілий формат конфігурації, тож застарілі конфігурації виправляються без ручного втручання. Міграції сховища завдань Cron обробляються командою `openclaw doctor --fix`. Поточні міграції: @@ -198,279 +198,279 @@ 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 може зберегти наявну відповідну іменовану/default-ціль) + - Для каналів з іменованими `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` (застарілий параметр relay розширення) - - застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (під час запуску Gateway також пропускаються провайдери, у яких `api` встановлено на майбутнє або невідоме значення enum, замість безпечної повної відмови) + - видалити `browser.relayBindHost` (застаріле налаштування relay для розширення) + - застаріле `models.providers.*.api: "openai"` → `"openai-completions"` (під час запуску Gateway також пропускає провайдерів, у яких `api` встановлено в майбутнє або невідоме значення enum, замість повної відмови) - Попередження doctor також містять вказівки щодо account-default для багатoоблікових каналів: + Попередження doctor також містять рекомендації щодо типового облікового запису для багатокористувацьких каналів: - - Якщо налаштовано два або більше записів `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис. - - Якщо `channels..defaultAccount` встановлено на невідомий id облікового запису, doctor попереджає та перелічує налаштовані id облікових записів. + - Якщо налаштовано два або більше записи `channels..accounts` без `channels..defaultAccount` або `accounts.default`, doctor попереджає, що резервна маршрутизація може вибрати неочікуваний обліковий запис. + - Якщо `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 нормалізує її до поточної моделі підключення host-local Chrome MCP: + Якщо конфігурація браузера все ще вказує на вилучений шлях розширення Chrome, doctor нормалізує її до поточної моделі підключення Chrome MCP на локальному вузлі: - `browser.profiles.*.driver: "extension"` стає `"existing-session"` - `browser.relayBindHost` видаляється - Doctor також перевіряє шлях host-local Chrome MCP, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: + Doctor також перевіряє шлях локального Chrome MCP на вузлі, коли ви використовуєте `defaultProfile: "user"` або налаштований профіль `existing-session`: - - перевіряє, чи встановлено Google Chrome на тому самому хості для типових профілів з автоматичним підключенням + - перевіряє, чи встановлено Google Chrome на тому самому вузлі для типових профілів з автоматичним підключенням - перевіряє виявлену версію Chrome і попереджає, якщо вона нижча за Chrome 144 - - нагадує увімкнути remote debugging на сторінці інспектування браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`) + - нагадує увімкнути remote debugging на сторінці inspect браузера (наприклад, `chrome://inspect/#remote-debugging`, `brave://inspect/#remote-debugging` або `edge://inspect/#remote-debugging`) - Doctor не може увімкнути параметр на боці Chrome за вас. Host-local Chrome MCP, як і раніше, вимагає: + Doctor не може увімкнути це налаштування на боці Chrome за вас. Локальний Chrome MCP на вузлі все ще потребує: - - браузер на базі Chromium 144+ на хості gateway/node - - локально запущений браузер - - увімкнений remote debugging у цьому браузері + - браузера на основі Chromium 144+ на вузлі Gateway/Node + - локально запущеного браузера + - увімкненого remote debugging у цьому браузері - підтвердження першого запиту згоди на підключення в браузері - Готовність тут стосується лише локальних передумов підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, як і раніше, потребують керованого браузера або сирого профілю CDP. + Готовність тут стосується лише локальних передумов для підключення. Existing-session зберігає поточні обмеження маршрутів Chrome MCP; розширені маршрути, як-от `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії, як і раніше, потребують керованого браузера або профілю raw CDP. - Ця перевірка **не** застосовується до Docker, sandbox, remote-browser або інших headless-потоків. Вони й надалі використовують raw CDP. + Ця перевірка **не** застосовується до Docker, пісочниці, remote-browser або інших безголових сценаріїв. Вони й надалі використовують raw CDP. - - Коли налаштовано профіль OAuth OpenAI Codex, doctor перевіряє endpoint авторизації OpenAI, щоб переконатися, що локальний стек TLS Node/OpenSSL може валідувати ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або самопідписаний сертифікат), doctor виводить вказівки з виправлення для конкретної платформи. На macOS із Node, встановленим через Homebrew, виправленням зазвичай є `brew postinstall ca-certificates`. Із `--deep` перевірка запускається, навіть якщо Gateway справний. + + Коли налаштовано профіль OpenAI Codex OAuth, doctor виконує перевірку кінцевої точки авторизації OpenAI, щоб переконатися, що локальний стек TLS Node/OpenSSL може перевірити ланцюжок сертифікатів. Якщо перевірка завершується помилкою сертифіката (наприклад, `UNABLE_TO_GET_ISSUER_CERT_LOCALLY`, прострочений сертифікат або self-signed cert), doctor виводить рекомендації з виправлення для конкретної платформи. На macOS із Node, встановленим через Homebrew, виправлення зазвичай таке: `brew postinstall ca-certificates`. З `--deep` перевірка виконується, навіть якщо Gateway у доброму стані. - Якщо ви раніше додавали застарілі параметри транспорту OpenAI у `models.providers.openai-codex`, вони можуть затіняти вбудований шлях провайдера Codex OAuth, який новіші випуски використовують автоматично. Doctor попереджає, коли бачить ці старі параметри транспорту поряд із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту та повернути вбудовану поведінку маршрутизації/резервного переходу. Користувацькі proxy та перевизначення лише заголовків, як і раніше, підтримуються й не викликають цього попередження. + Якщо раніше ви додали застарілі налаштування транспорту OpenAI у `models.providers.openai-codex`, вони можуть затінити вбудований шлях провайдера Codex OAuth, який новіші релізи використовують автоматично. Doctor попереджає, коли бачить ці старі налаштування транспорту поряд із Codex OAuth, щоб ви могли видалити або переписати застаріле перевизначення транспорту та повернути вбудовану поведінку маршрутизації/резервування. Користувацькі проксі та перевизначення лише заголовків, як і раніше, підтримуються і не викликають цього попередження. - - Коли вбудований плагін Codex увімкнено, doctor також перевіряє, чи первинні посилання на моделі `openai-codex/*` усе ще розв’язуються через типового виконавця PI. Така комбінація коректна, якщо ви хочете автентифікацію Codex OAuth/підписки через PI, але її легко сплутати з нативною harness app-server Codex. Doctor попереджає про це та вказує на явну форму app-server: `openai/*` плюс `agentRuntime.id: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`. + + Коли ввімкнено вбудований плагін Codex, doctor також перевіряє, чи основні посилання на моделі `openai-codex/*` і далі проходять через типовий раннер 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/підписки через звичайний виконавець OpenClaw». - - `openai/*` + `runtime: "codex"` означає «виконувати вбудований turn через нативний app-server Codex». - - `/codex ...` означає «керувати нативною розмовою Codex з чату або прив’язати її». + - `openai-codex/*` + PI означає «використовувати автентифікацію Codex OAuth/підписки через звичайний раннер OpenClaw». + - `openai/*` + `runtime: "codex"` означає «запускати вбудований turn через нативний app-server Codex». + - `/codex ...` означає «керувати або прив’язати нативну розмову Codex з чату». - `/acp ...` або `runtime: "acp"` означає «використовувати зовнішній адаптер ACP/acpx». - Якщо з’являється це попередження, виберіть потрібний вам маршрут і відредагуйте конфігурацію вручну. Залиште попередження без змін, якщо PI Codex OAuth використовується навмисно. + Якщо з’являється це попередження, виберіть маршрут, який ви мали на увазі, і відредагуйте конфігурацію вручну. Залишайте попередження як є, якщо PI Codex OAuth використовується навмисно. - Doctor може мігрувати старіші структури на диску до поточної структури: + Doctor може мігрувати старіші структури на диску до поточної: - - Сховище сеансів + розшифровки: + - Сховище сеансів + транскрипти: - з `~/.openclaw/sessions/` до `~/.openclaw/agents//sessions/` - - Каталог agent: + - Каталог агента: - з `~/.openclaw/agent/` до `~/.openclaw/agents//agent/` - Стан автентифікації WhatsApp (Baileys): - із застарілого `~/.openclaw/credentials/*.json` (крім `oauth.json`) - - до `~/.openclaw/credentials/whatsapp//...` (типовий id облікового запису: `default`) + - до `~/.openclaw/credentials/whatsapp//...` (типовий ID облікового запису: `default`) - Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виводить попередження, якщо залишає будь-які застарілі каталоги як резервні копії. Gateway/CLI також автоматично мігрує застарілі sessions + каталог agent під час запуску, тож history/auth/models потрапляють до шляху для конкретного agent без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація provider/provider-map Talk тепер порівнює за структурною рівністю, тому відмінності лише в порядку ключів більше не спричиняють повторних порожніх змін `doctor --fix`. + Ці міграції виконуються за принципом best-effort та є ідемпотентними; doctor виводить попередження, якщо залишає будь-які застарілі папки як резервні копії. Gateway/CLI також автоматично мігрує застарілі сеанси + каталог агента під час запуску, тож історія/автентифікація/моделі потрапляють у шлях конкретного агента без ручного запуску doctor. Автентифікація WhatsApp навмисно мігрується лише через `openclaw doctor`. Нормалізація provider/provider-map для Talk тепер порівнює за структурною рівністю, тож відмінності лише в порядку ключів більше не спричиняють повторних пустих змін `doctor --fix`. - - Doctor сканує всі встановлені маніфести плагінів на наявність застарілих ключів можливостей верхнього рівня (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх до об’єкта `contracts` і переписати файл маніфесту на місці. Ця міграція ідемпотентна; якщо ключ `contracts` уже містить ті самі значення, застарілий ключ видаляється без дублювання даних. + + Doctor сканує всі встановлені маніфести плагінів на наявність застарілих ключів можливостей верхнього рівня (`speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders`, `webSearchProviders`). Якщо їх знайдено, він пропонує перемістити їх до об’єкта `contracts` і переписати файл маніфесту на місці. Ця міграція є ідемпотентною; якщо ключ `contracts` уже містить ті самі значення, застарілий ключ видаляється без дублювання даних. - Doctor також перевіряє сховище Cron-завдань (`~/.openclaw/cron/jobs.json` за замовчуванням або `cron.store`, якщо його перевизначено) на наявність старих форм завдань, які планувальник і досі приймає для сумісності. + Doctor також перевіряє сховище завдань Cron (`~/.openclaw/cron/jobs.json` типово або `cron.store`, якщо його перевизначено) на старі форми завдань, які планувальник і далі приймає для сумісності. Поточні очищення Cron включають: - `jobId` → `id` - `schedule.cron` → `schedule.expr` - - поля корисного навантаження верхнього рівня (`message`, `model`, `thinking`, ...) → `payload` - - поля доставки верхнього рівня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` - - псевдоніми доставки payload `provider` → явний `delivery.channel` - - прості застарілі резервні Webhook-завдання `notify: true` → явне `delivery.mode="webhook"` з `delivery.to=cron.webhook` + - поля payload верхнього рівня (`message`, `model`, `thinking`, ...) → `payload` + - поля delivery верхнього рівня (`deliver`, `channel`, `to`, `provider`, ...) → `delivery` + - псевдоніми доставки `provider` у payload → явний `delivery.channel` + - прості застарілі резервні завдання Webhook з `notify: true` → явний `delivery.mode="webhook"` з `delivery.to=cron.webhook` - Doctor автоматично мігрує завдання `notify: true` лише тоді, коли може зробити це без зміни поведінки. Якщо завдання поєднує застарілий резервний notify з наявним режимом доставки не через webhook, doctor попереджає й залишає це завдання для ручної перевірки. + Doctor автоматично мігрує завдання `notify: true` лише тоді, коли це можна зробити без зміни поведінки. Якщо завдання поєднує застарілий резервний сценарій notify з наявним режимом доставки, що не є webhook, doctor попереджає і залишає це завдання для ручної перевірки. - Doctor сканує кожен каталог сеансів agent на наявність застарілих файлів блокування запису — файлів, що залишилися після аварійного завершення сеансу. Для кожного знайденого файла блокування він повідомляє: шлях, PID, чи PID усе ще активний, вік блокування та чи вважається воно застарілим (мертвий PID або старше 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше виводить примітку й радить повторити запуск з `--fix`. + Doctor сканує каталог сеансів кожного агента на наявність застарілих write-lock файлів — файлів, що залишилися після нештатного завершення сеансу. Для кожного знайденого файлу блокування він повідомляє: шлях, PID, чи PID ще активний, вік блокування та чи вважається воно застарілим (PID неактивний або старший за 30 хвилин). У режимі `--fix` / `--repair` він автоматично видаляє застарілі файли блокування; інакше виводить примітку та пропонує перезапустити з `--fix`. - - Doctor сканує файли JSONL сеансів agent на наявність дубльованої форми гілок, створеної помилкою переписування розшифровки prompt у версії 2026.4.24: покинутий user turn із внутрішнім контекстом середовища виконання OpenClaw плюс активний sibling з тим самим видимим user prompt. У режимі `--fix` / `--repair` doctor створює резервну копію кожного ураженого файла поруч з оригіналом і переписує розшифровку до активної гілки, щоб history Gateway і читачі пам’яті більше не бачили дубльовані turn. + + Doctor сканує JSONL-файли сеансів агентів на дубльовану форму гілок, створену помилкою переписування транскриптів запитів у 2026.4.24: покинутий користувацький turn із внутрішнім runtime-контекстом OpenClaw плюс активний сусідній turn, що містить той самий видимий запит користувача. У режимі `--fix` / `--repair` doctor створює резервну копію кожного зачепленого файлу поруч з оригіналом і переписує транскрипт на активну гілку, щоб історія Gateway і читачі пам’яті більше не бачили дубльованих turn. - Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите сеанси, облікові дані, журнали й конфігурацію (якщо тільки не маєте резервних копій деінде). + Каталог стану — це операційний стовбур мозку. Якщо він зникне, ви втратите сеанси, облікові дані, журнали та конфігурацію (якщо у вас немає резервних копій в іншому місці). Doctor перевіряє: - - **Каталог стану відсутній**: попереджає про катастрофічну втрату стану, пропонує відтворити каталог і нагадує, що не може відновити відсутні дані. + - **Відсутній каталог стану**: попереджає про катастрофічну втрату стану, пропонує заново створити каталог і нагадує, що не може відновити відсутні дані. - **Права доступу до каталогу стану**: перевіряє можливість запису; пропонує виправити права доступу (і виводить підказку `chown`, якщо виявлено невідповідність власника/групи). - - **Каталог стану macOS, синхронізований із хмарою**: попереджає, коли стан розташовано в iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) або `~/Library/CloudStorage/...`, оскільки шляхи із синхронізацією можуть спричиняти повільніший I/O та гонки блокування/синхронізації. - - **Каталог стану Linux на SD або eMMC**: попереджає, коли стан розташовано на джерелі монтування `mmcblk*`, оскільки випадковий I/O на SD або eMMC може бути повільнішим і швидше зношувати носій під час записів сеансів та облікових даних. - - **Каталоги сеансів відсутні**: `sessions/` і каталог сховища сеансів потрібні для збереження history та уникнення збоїв `ENOENT`. - - **Невідповідність розшифровок**: попереджає, коли в недавніх записах сеансів відсутні файли розшифровок. - - **Основний сеанс "1-line JSONL"**: позначає ситуацію, коли основна розшифровка має лише один рядок (history не накопичується). - - **Кілька каталогів стану**: попереджає, коли існує кілька каталогів `~/.openclaw` у різних домашніх каталогах або коли `OPENCLAW_STATE_DIR` вказує на інше місце (history може розділитися між встановленнями). - - **Нагадування про віддалений режим**: якщо `gateway.mode=remote`, doctor нагадує запускати його на віддаленому хості (саме там зберігається стан). - - **Права доступу до файла конфігурації**: попереджає, якщо `~/.openclaw/openclaw.json` доступний для читання групою/усіма, і пропонує обмежити права до `600`. + - **Каталог стану 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`. - - Doctor перевіряє OAuth-профілі в сховищі автентифікації, попереджає, коли токени ось-ось завершать дію або вже завершили, і може оновити їх, коли це безпечно. Якщо профіль OAuth/токена Anthropic застарів, він пропонує API-ключ Anthropic або шлях setup-token Anthropic. Запити на оновлення з’являються лише в інтерактивному режимі (TTY); `--non-interactive` пропускає спроби оновлення. + + Doctor перевіряє профілі 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` або провайдер повідомляє, що потрібно увійти знову), doctor повідомляє, що потрібна повторна автентифікація, і виводить точну команду `openclaw models auth login --provider ...`, яку треба виконати. - Doctor також повідомляє про профілі автентифікації, які тимчасово не можна використовувати через: + Doctor також повідомляє про профілі автентифікації, які тимчасово непридатні через: - - короткі cooldown (rate limits/timeouts/auth failures) - - довші вимкнення (billing/credit failures) + - короткі cooldown-и (обмеження швидкості/тайм-аути/збої автентифікації) + - триваліші вимкнення (збої білінгу/кредитів) - - Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель щодо каталогу та списку дозволів і попереджає, якщо воно не розв’язується або заборонене. + + Якщо встановлено `hooks.gmail.model`, doctor перевіряє посилання на модель за каталогом і allowlist та попереджає, якщо воно не розв’язується або заборонене. - - Коли sandboxing увімкнено, doctor перевіряє Docker-образи й пропонує зібрати або переключитися на застарілі назви, якщо поточний образ відсутній. + + Коли ізоляцію ввімкнено, doctor перевіряє Docker-образи та пропонує зібрати або переключитися на застарілі назви, якщо поточний образ відсутній. - - Doctor перевіряє залежності середовища виконання лише для вбудованих плагінів, які активні в поточній конфігурації або увімкнені типовим значенням у вбудованому маніфесті, наприклад `plugins.entries.discord.enabled: true`, застаріле `channels.discord.enabled: true` або вбудований провайдер, увімкнений за замовчуванням. Якщо чогось бракує, doctor повідомляє про пакети й установлює їх у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Для зовнішніх плагінів і далі використовуються `openclaw plugins install` / `openclaw plugins update`; doctor не встановлює залежності для довільних шляхів плагінів. + + Doctor перевіряє runtime-залежності лише для вбудованих плагінів, які активні в поточній конфігурації або ввімкнені типовим значенням у їхньому вбудованому маніфесті, наприклад `plugins.entries.discord.enabled: true`, застаріле `channels.discord.enabled: true` або типовий увімкнений вбудований провайдер. Якщо чогось бракує, doctor повідомляє про пакети й установлює їх у режимі `openclaw doctor --fix` / `openclaw doctor --repair`. Зовнішні плагіни, як і раніше, використовують `openclaw plugins install` / `openclaw plugins update`; doctor не встановлює залежності для довільних шляхів плагінів. - Під час відновлення doctor npm-встановлення залежностей середовища виконання для вбудованих плагінів показують прогрес через spinner у TTY-сеансах і періодичний построковий прогрес у перенаправленому/headless-виводі. Gateway і локальний CLI також можуть за потреби відновлювати активні залежності середовища виконання вбудованих плагінів перед імпортом вбудованого плагіна. Ці встановлення обмежені коренем встановлення середовища виконання плагіна, запускаються з вимкненими скриптами, не записують package lock і захищені блокуванням кореня встановлення, щоб одночасні запуски CLI або Gateway не змінювали одне й те саме дерево `node_modules` в один і той самий час. + Під час відновлення doctor встановлення npm runtime-залежностей для вбудованих плагінів показує прогрес spinner у TTY-сеансах і періодичний лінійний прогрес у конвеєрному/безголовому виводі. Gateway і локальний CLI також можуть за потреби відновлювати активні runtime-залежності вбудованих плагінів перед імпортом вбудованого плагіна. Ці встановлення обмежені коренем встановлення runtime плагіна, виконуються з вимкненими скриптами, не записують package lock і захищені блокуванням кореня встановлення, щоб одночасні запуски CLI або Gateway не змінювали одне й те саме дерево `node_modules` водночас. - - Doctor виявляє застарілі сервіси Gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити сервіс OpenClaw з використанням поточного порту Gateway. Він також може сканувати додаткові сервіси, схожі на Gateway, і виводити підказки щодо очищення. Іменовані за профілем сервіси Gateway OpenClaw вважаються повноцінними й не позначаються як «додаткові». + + Doctor виявляє застарілі служби gateway (launchd/systemd/schtasks) і пропонує видалити їх та встановити службу OpenClaw з використанням поточного порту Gateway. Він також може сканувати додаткові служби, схожі на gateway, і виводити підказки з очищення. Служби Gateway OpenClaw, названі за профілем, вважаються повноцінними й не позначаються як «додаткові». - - Коли обліковий запис каналу Matrix має очікувану або таку, що потребує дії, міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок стану до міграції, а потім запускає кроки міграції за принципом best-effort: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки логуються, а запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. + + Коли обліковий запис каналу Matrix має очікувану або застосовну міграцію застарілого стану, doctor (у режимі `--fix` / `--repair`) створює знімок стану до міграції, а потім запускає best-effort кроки міграції: міграцію застарілого стану Matrix і підготовку застарілого зашифрованого стану. Обидва кроки не є фатальними; помилки журналюються, а запуск триває. У режимі лише читання (`openclaw doctor` без `--fix`) ця перевірка повністю пропускається. - Тепер doctor перевіряє стан сполучення пристроїв як частину звичайного проходу перевірки справності. + Тепер doctor перевіряє стан сполучення пристроїв як частину звичайного проходу перевірки стану. Що він повідомляє: - - очікувані запити першого сполучення - - очікувані підвищення ролей для вже сполучених пристроїв - - очікувані підвищення обсягу для вже сполучених пристроїв - - виправлення невідповідності публічного ключа, коли id пристрою все ще збігається, але ідентичність пристрою більше не збігається зі схваленим записом - - сполучені записи без активного токена для схваленої ролі - - сполучені токени, чиї обсяги відійшли від схваленого базового рівня сполучення - - локальні кешовані записи device-token для поточної машини, які передують ротації токена на боці gateway або містять застарілі метадані обсягу + - очікувані перші запити на сполучення + - очікувані оновлення ролей для вже сполучених пристроїв + - очікувані оновлення областей дії для вже сполучених пристроїв + - виправлення невідповідності публічного ключа, коли ID пристрою все ще збігається, але ідентичність пристрою більше не збігається із затвердженим записом + - сполучені записи без активного токена для затвердженої ролі + - сполучені токени, чиї області дії виходять за межі затвердженого базового рівня сполучення + - локальні кешовані записи токенів пристрою для поточної машини, які передують ротації токена на боці gateway або містять застарілі метадані областей дії - Doctor не схвалює запити на сполучення автоматично і не виконує автоматичну ротацію токенів пристроїв. Натомість він виводить точні наступні кроки: + Doctor не затверджує запити на сполучення автоматично і не виконує автоматичну ротацію токенів пристрою. Натомість він виводить точні наступні кроки: - переглянути очікувані запити за допомогою `openclaw devices list` - - схвалити точний запит за допомогою `openclaw devices approve ` - - ротувати новий токен за допомогою `openclaw devices rotate --device --role ` - - видалити й повторно схвалити застарілий запис за допомогою `openclaw devices remove ` + - затвердити точний запит за допомогою `openclaw devices approve ` + - виконати ротацію нового токена за допомогою `openclaw devices rotate --device --role ` + - видалити застарілий запис і затвердити його знову за допомогою `openclaw devices remove ` - Це закриває поширену прогалину «вже сполучено, але все одно з’являється pairing required»: тепер doctor розрізняє перше сполучення, очікувані підвищення ролі/обсягу та дрейф застарілого токена/ідентичності пристрою. + Це закриває поширену прогалину «пристрій уже сполучено, але все одно з’являється вимога сполучення»: тепер doctor розрізняє перше сполучення, очікувані оновлення ролей/областей дії та дрейф застарілого токена/ідентичності пристрою. - Doctor виводить попередження, коли провайдер відкритий для DM без списку дозволів або коли політику налаштовано небезпечним чином. + Doctor виводить попередження, коли провайдер відкритий для DM без allowlist або коли політика налаштована небезпечним чином. - Якщо запуск виконується як користувацький сервіс systemd, doctor переконується, що linger увімкнено, щоб Gateway залишався активним після виходу з системи. + Якщо запуск виконується як користувацька служба systemd, doctor перевіряє, що linger увімкнено, щоб gateway залишався активним після виходу з системи. - Doctor виводить підсумок стану робочого простору для типового agent: + Doctor виводить підсумок стану робочого простору для типового агента: - - **Стан Skills**: кількість доступних, із відсутніми вимогами та заблокованих списком дозволів Skills. + - **Стан Skills**: кількість доступних, таких, яким бракує вимог, і заблокованих allowlist Skills. - **Застарілі каталоги робочого простору**: попереджає, коли `~/openclaw` або інші застарілі каталоги робочого простору існують поряд із поточним робочим простором. - - **Стан плагінів**: кількість увімкнених/вимкнених/помилкових плагінів; перелічує id плагінів для будь-яких помилок; повідомляє про можливості пакетів плагінів. - - **Попередження про сумісність плагінів**: позначає плагіни, що мають проблеми сумісності з поточним середовищем виконання. - - **Діагностика плагінів**: показує будь-які попередження або помилки під час завантаження, які видає реєстр плагінів. + - **Стан плагінів**: підраховує ввімкнені/вимкнені/помилкові плагіни; перелічує ID плагінів для всіх помилок; повідомляє про можливості bundle plugin. + - **Попередження про сумісність плагінів**: позначає плагіни, які мають проблеми сумісності з поточним runtime. + - **Діагностика плагінів**: показує всі попередження або помилки під час завантаження, які видає реєстр плагінів. - - Doctor перевіряє, чи наближаються bootstrap-файли робочого простору (наприклад, `AGENTS.md`, `CLAUDE.md` або інші ін’єктовані контекстні файли) до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файла кількість сирих та ін’єктованих символів, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість ін’єктованих символів як частку від загального бюджету. Коли файли обрізано або вони близькі до ліміту, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. + + Doctor перевіряє, чи наближаються bootstrap-файли робочого простору (наприклад, `AGENTS.md`, `CLAUDE.md` або інші ін’єктовані контекстні файли) до налаштованого бюджету символів або перевищують його. Він повідомляє для кожного файлу кількість сирих та ін’єктованих символів, відсоток обрізання, причину обрізання (`max/file` або `max/total`) і загальну кількість ін’єктованих символів як частку від загального бюджету. Коли файли обрізаються або наближаються до ліміту, doctor виводить поради щодо налаштування `agents.defaults.bootstrapMaxChars` і `agents.defaults.bootstrapTotalMaxChars`. - Коли `openclaw doctor --fix` видаляє відсутній плагін каналу, він також видаляє завислу конфігурацію рівня каналу, яка посилалася на цей плагін: записи `channels.`, цілі Heartbeat, що називали цей канал, і перевизначення `agents.*.models["/*"]`. Це запобігає циклам завантаження Gateway, коли середовище виконання каналу вже відсутнє, але конфігурація все ще вимагає, щоб gateway прив’язувався до нього. + Коли `openclaw doctor --fix` видаляє відсутній плагін каналу, він також видаляє завислу конфігурацію рівня каналу, яка посилалася на цей плагін: записи `channels.`, цілі Heartbeat, які називали цей канал, і перевизначення `agents.*.models["/*"]`. Це запобігає циклам завантаження Gateway, коли runtime каналу вже відсутній, але конфігурація все ще вимагає, щоб gateway прив’язувався до нього. Doctor перевіряє, чи встановлено автодоповнення tab для поточної оболонки (zsh, bash, fish або PowerShell): - - Якщо профіль оболонки використовує повільну динамічну схему автодоповнення (`source <(openclaw completion ...)`), doctor оновлює її до швидшого варіанту з кешованим файлом. - - Якщо автодоповнення налаштовано в профілі, але файл кешу відсутній, doctor автоматично повторно генерує кеш. - - Якщо автодоповнення взагалі не налаштовано, doctor пропонує встановити його (лише в інтерактивному режимі; пропускається з `--non-interactive`). + - Якщо профіль оболонки використовує повільний динамічний шаблон автодоповнення (`source <(openclaw completion ...)`), doctor оновлює його до швидшого варіанта з кешованим файлом. + - Якщо автодоповнення налаштоване в профілі, але кешований файл відсутній, doctor автоматично регенерує кеш. + - Якщо автодоповнення взагалі не налаштоване, doctor пропонує встановити його (лише в інтерактивному режимі; пропускається з `--non-interactive`). - Запустіть `openclaw completion --write-state`, щоб вручну повторно згенерувати кеш. + Виконайте `openclaw completion --write-state`, щоб вручну регенерувати кеш. - Doctor перевіряє готовність локальної автентифікації Gateway за токеном. + Doctor перевіряє готовність автентифікації локального токена gateway. - - Якщо режиму токена потрібен токен, а джерело токена відсутнє, doctor пропонує створити його. - - Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає й не перезаписує його відкритим текстом. - - `openclaw doctor --generate-gateway-token` примусово створює токен лише тоді, коли не налаштовано жодного token SecretRef. + - Якщо режим токена потребує токен, а джерела токена немає, doctor пропонує його згенерувати. + - Якщо `gateway.auth.token` керується через SecretRef, але недоступний, doctor попереджає і не перезаписує його відкритим текстом. + - `openclaw doctor --generate-gateway-token` примусово генерує токен лише тоді, коли не налаштовано token SecretRef. - - Деяким потокам відновлення потрібно перевіряти налаштовані облікові дані, не послаблюючи при цьому fail-fast поведінку середовища виконання. + + Деякі сценарії відновлення потребують перевірки налаштованих облікових даних без послаблення поведінки runtime fail-fast. - - `openclaw doctor --fix` тепер використовує ту саму модель зведення SecretRef лише для читання, що й команди сімейства status, для цільових виправлень конфігурації. - - Приклад: відновлення `allowFrom` / `groupAllowFrom` `@username` для Telegram намагається використовувати налаштовані облікові дані бота, коли вони доступні. - - Якщо токен Telegram-бота налаштовано через SecretRef, але він недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовано, але вони недоступні, і пропускає автоматичне розв’язання замість аварійного завершення або помилкового повідомлення, що токен відсутній. + - `openclaw doctor --fix` тепер використовує ту саму модель підсумку SecretRef у режимі лише читання, що й команди сімейства status, для цільових виправлень конфігурації. + - Приклад: виправлення Telegram `allowFrom` / `groupAllowFrom` `@username` намагається використовувати налаштовані облікові дані бота, коли вони доступні. + - Якщо токен Telegram-бота налаштований через SecretRef, але недоступний у поточному шляху команди, doctor повідомляє, що облікові дані налаштовані, але недоступні, і пропускає авторозв’язання замість аварійного завершення або хибного повідомлення про відсутність токена. - - Doctor запускає перевірку справності й пропонує перезапустити gateway, якщо той виглядає несправним. + + Doctor виконує перевірку стану і пропонує перезапустити gateway, якщо він виглядає нездоровим. - Doctor перевіряє, чи готовий налаштований провайдер embeddings для пошуку в пам’яті для типового agent. Поведінка залежить від налаштованого бекенда та провайдера: + Doctor перевіряє, чи готовий налаштований провайдер ембедингів для пошуку в пам’яті для типового агента. Поведінка залежить від налаштованого бекенду та провайдера: - - **QMD backend**: перевіряє, чи двійковий файл `qmd` доступний і чи може запускатися. Якщо ні — виводить вказівки з виправлення, зокрема npm-пакет і параметр ручного шляху до двійкового файла. + - **Бекенд QMD**: перевіряє, чи доступний і чи може запуститися бінарний файл `qmd`. Якщо ні, виводить рекомендації з виправлення, зокрема npm-пакет і ручний варіант шляху до бінарного файла. - **Явний локальний провайдер**: перевіряє наявність локального файла моделі або розпізнаного URL віддаленої/завантажуваної моделі. Якщо його немає, пропонує перейти на віддаленого провайдера. - - **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє наявність API-ключа в середовищі або сховищі автентифікації. Якщо ключ відсутній, виводить практичні підказки з виправлення. - - **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, а потім пробує кожного віддаленого провайдера в порядку автоматичного вибору. + - **Явний віддалений провайдер** (`openai`, `voyage` тощо): перевіряє, чи є API-ключ у середовищі або сховищі автентифікації. Якщо його немає, виводить практичні підказки з виправлення. + - **Автоматичний провайдер**: спочатку перевіряє доступність локальної моделі, потім пробує кожного віддаленого провайдера в порядку автодобору. - Коли доступний результат перевірки через gateway (gateway був справний на момент перевірки), doctor зіставляє його з видимою для CLI конфігурацією та зазначає будь-які розбіжності. + Коли доступний кешований результат перевірки gateway (gateway був у доброму стані на момент перевірки), doctor зіставляє його результат із конфігурацією, видимою для CLI, і зазначає будь-які розбіжності. Doctor не запускає новий ping ембедингів у типовому шляху; використовуйте команду глибокого стану пам’яті, якщо вам потрібна жива перевірка провайдера. - Використовуйте `openclaw memory status --deep`, щоб перевірити готовність embeddings під час роботи. + Використовуйте `openclaw memory status --deep`, щоб перевірити готовність ембедингів під час runtime. - Якщо gateway справний, doctor запускає перевірку стану каналів і повідомляє попередження з рекомендованими виправленнями. + Якщо gateway у доброму стані, doctor виконує зондаж стану каналів і повідомляє попередження з рекомендованими виправленнями. - - Doctor перевіряє встановлену конфігурацію supervisor (launchd/systemd/schtasks) на відсутні або застарілі значення за замовчуванням (наприклад, залежності network-online systemd і затримку перезапуску). Коли він знаходить невідповідність, рекомендує оновлення й може переписати файл сервісу/завдання до поточних значень за замовчуванням. + + Doctor перевіряє встановлену конфігурацію супервізора (launchd/systemd/schtasks) на відсутність або застарілі типові значення (наприклад, systemd-залежності network-online і затримка перезапуску). Коли він знаходить невідповідність, то рекомендує оновлення і може переписати файл служби/завдання до поточних типових значень. Примітки: - - `openclaw doctor` запитує підтвердження перед переписуванням конфігурації supervisor. - - `openclaw doctor --yes` приймає типові запити на відновлення. + - `openclaw doctor` запитує підтвердження перед переписуванням конфігурації супервізора. + - `openclaw doctor --yes` приймає типові запити на виправлення. - `openclaw doctor --repair` застосовує рекомендовані виправлення без запитів. - - `openclaw doctor --repair --force` перезаписує власні конфігурації supervisor. - - `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу сервісу gateway. Він усе одно повідомляє про стан сервісу й запускає виправлення, не пов’язані із сервісом, але пропускає встановлення/запуск/перезапуск/ініціалізацію сервісу, переписування конфігурації supervisor і очищення застарілих сервісів, бо цим життєвим циклом керує зовнішній supervisor. - - Якщо для автентифікації за токеном потрібен токен і `gateway.auth.token` керується через SecretRef, відновлення/встановлення сервісу doctor перевіряє SecretRef, але не зберігає розв’язані значення токенів відкритим текстом у метадані середовища сервісу supervisor. - - Doctor виявляє керовані `.env`/значення середовища сервісу на основі SecretRef, які старіші встановлення LaunchAgent, systemd або Windows Scheduled Task вбудовували безпосередньо, і переписує метадані сервісу так, щоб ці значення завантажувалися з джерела середовища виконання, а не з визначення supervisor. - - Якщо для автентифікації за токеном потрібен токен, а налаштований token SecretRef не розв’язується, doctor блокує шлях встановлення/відновлення й виводить практичні вказівки. + - `openclaw doctor --repair --force` перезаписує користувацькі конфігурації супервізора. + - `OPENCLAW_SERVICE_REPAIR_POLICY=external` залишає doctor у режимі лише читання для життєвого циклу служби gateway. Він усе ще повідомляє про стан служби й виконує відновлення, не пов’язані зі службою, але пропускає встановлення/запуск/перезапуск/bootstrap служби, переписування конфігурації супервізора та очищення застарілих служб, оскільки цим життєвим циклом керує зовнішній супервізор. + - Якщо для автентифікації токена потрібен токен, а `gateway.auth.token` керується через SecretRef, інсталяція/відновлення служби doctor перевіряє SecretRef, але не зберігає розв’язані значення токена відкритим текстом у метаданих середовища служби супервізора. + - Doctor виявляє керовані значення середовища служби `.env`/на основі SecretRef, які старіші інсталяції LaunchAgent, systemd або Windows Scheduled Task вбудовували inline, і переписує метадані служби так, щоб ці значення завантажувалися з runtime-джерела, а не з визначення супервізора. + - Якщо для автентифікації токена потрібен токен, а налаштований token SecretRef не розв’язується, doctor блокує шлях встановлення/відновлення з практичними рекомендаціями. - Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не встановлено, doctor блокує встановлення/відновлення, доки режим не буде явно задано. - - Для користувацьких unit systemd у Linux перевірки дрейфу токенів doctor тепер включають і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації сервісу. - - Відновлення сервісу doctor відмовляється переписувати, зупиняти чи перезапускати сервіс gateway зі старішого двійкового файла OpenClaw, якщо конфігурацію востаннє записано новішою версією. Див. [Усунення проблем Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). + - Для користувацьких unit-файлів Linux user-systemd перевірки дрейфу токенів doctor тепер охоплюють і джерела `Environment=`, і `EnvironmentFile=` під час порівняння метаданих автентифікації служби. + - Відновлення служб doctor відмовляється переписувати, зупиняти або перезапускати службу gateway зі старішого бінарного файла OpenClaw, якщо конфігурацію востаннє записано новішою версією. Див. [Усунення несправностей Gateway](/uk/gateway/troubleshooting#split-brain-installs-and-newer-config-guard). - Ви завжди можете примусово виконати повне переписування через `openclaw gateway install --force`. - - Doctor перевіряє середовище виконання сервісу (PID, останній статус завершення) і попереджає, коли сервіс установлено, але він фактично не запущений. Він також перевіряє конфлікти портів на порту Gateway (типово `18789`) і повідомляє ймовірні причини (Gateway уже запущено, SSH-тунель). + + Doctor перевіряє runtime служби (PID, останній статус завершення) і попереджає, коли службу встановлено, але вона фактично не запущена. Він також перевіряє конфлікти портів на порту gateway (типово `18789`) і повідомляє ймовірні причини (gateway уже запущений, SSH-тунель). - - Doctor попереджає, коли сервіс gateway працює на Bun або на шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджерів версій можуть ламатися після оновлень, бо сервіс не завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системне встановлення Node, якщо воно доступне (Homebrew/apt/choco). + + Doctor попереджає, коли служба gateway працює на Bun або на шляху Node, керованому менеджером версій (`nvm`, `fnm`, `volta`, `asdf` тощо). Канали WhatsApp + Telegram потребують Node, а шляхи менеджера версій можуть ламатися після оновлень, оскільки служба не завантажує ініціалізацію вашої оболонки. Doctor пропонує перейти на системне встановлення Node, якщо воно доступне (Homebrew/apt/choco). - Doctor зберігає будь-які зміни конфігурації та проставляє метадані майстра, щоб зафіксувати запуск doctor. + Doctor зберігає будь-які зміни конфігурації та проставляє метадані майстра для фіксації запуску doctor. - - Doctor пропонує систему пам’яті робочого простору, якщо її немає, і виводить пораду щодо резервного копіювання, якщо робочий простір ще не перебуває під git. + + Doctor пропонує систему пам’яті робочого простору, якщо вона відсутня, і виводить пораду щодо резервного копіювання, якщо робочий простір ще не перебуває під git. - Повний посібник зі структури робочого простору й резервного копіювання через git (рекомендовано приватний GitHub або GitLab) див. у [/concepts/agent-workspace](/uk/concepts/agent-workspace). + Див. [/concepts/agent-workspace](/uk/concepts/agent-workspace) для повного посібника зі структури робочого простору та резервного копіювання через git (рекомендовано приватний GitHub або GitLab). -## Пов’язано +## Пов’язане - [Runbook Gateway](/uk/gateway) -- [Усунення проблем Gateway](/uk/gateway/troubleshooting) +- [Усунення несправностей Gateway](/uk/gateway/troubleshooting) diff --git a/docs/uk/gateway/protocol.md b/docs/uk/gateway/protocol.md index 5ab34cd82..6a2ac89b9 100644 --- a/docs/uk/gateway/protocol.md +++ b/docs/uk/gateway/protocol.md @@ -1,39 +1,39 @@ --- read_when: - - Реалізація або оновлення клієнтів WS Gateway + - Реалізація або оновлення клієнтів шлюзу WS - Налагодження невідповідностей протоколу або збоїв підключення - Повторна генерація схеми/моделей протоколу -summary: 'Протокол WebSocket Gateway: рукостискання, фрейми, версіонування' +summary: 'Протокол Gateway WebSocket: рукостискання, фрейми, версіонування' title: Протокол Gateway x-i18n: - generated_at: "2026-04-27T12:51:01Z" + generated_at: "2026-04-27T12:59:59Z" model: gpt-5.4 provider: openai - source_hash: 8f28bf8e4276b9295dc33fa3c39aa25de741e08aad1140ca36bd678b25d6a0c1 + source_hash: 0cca49f3c8612e719ad97e1748cb263e8824e0e4c59548ba0809cb0bc095f363 source_path: gateway/protocol.md workflow: 15 --- -Протокол WS Gateway — це **єдина control plane + Node transport** для -OpenClaw. Усі клієнти (CLI, web UI, застосунок macOS, iOS/Android Nodes, headless -Nodes) підключаються через WebSocket і під час -рукостискання оголошують свою **роль** + **область**. +Протокол Gateway WS є **єдиною площиною керування + транспортом вузлів** для +OpenClaw. Усі клієнти (CLI, веб-інтерфейс, застосунок macOS, вузли iOS/Android, headless-вузли) +підключаються через WebSocket і оголошують свою **роль** + **область дії** під +час рукостискання. ## Транспорт -- WebSocket, текстові фрейми з JSON payload. +- WebSocket, текстові фрейми з JSON-корисним навантаженням. - Перший фрейм **має** бути запитом `connect`. -- Розмір фреймів до підключення обмежено 64 KiB. Після успішного рукостискання клієнти - мають дотримуватися обмежень `hello-ok.policy.maxPayload` і - `hello-ok.policy.maxBufferedBytes`. Коли діагностику ввімкнено, - надто великі вхідні фрейми та повільні вихідні буфери створюють події `payload.large` - до того, як gateway закриє або відкине відповідний фрейм. Ці події зберігають +- Розмір фреймів до підключення обмежений 64 KiB. Після успішного рукостискання клієнти + повинні дотримуватися обмежень `hello-ok.policy.maxPayload` і + `hello-ok.policy.maxBufferedBytes`. Якщо діагностику ввімкнено, + завеликі вхідні фрейми та повільні вихідні буфери породжують події `payload.large` + до того, як шлюз закриє або відкине відповідний фрейм. Ці події зберігають розміри, ліміти, поверхні та безпечні коди причин. Вони не зберігають тіло повідомлення, - вміст вкладень, тіло сирого фрейму, токени, cookies або секретні значення. + вміст вкладень, сире тіло фрейму, токени, cookie або секретні значення. ## Рукостискання (connect) -Gateway → Client (виклик до підключення): +Gateway → Клієнт (виклик до підключення): ```json { @@ -43,7 +43,7 @@ Gateway → Client (виклик до підключення): } ``` -Client → Gateway: +Клієнт → Gateway: ```json { @@ -78,7 +78,7 @@ Client → Gateway: } ``` -Gateway → Client: +Gateway → Клієнт: ```json { @@ -104,9 +104,9 @@ Gateway → Client: } ``` -`server`, `features`, `snapshot` і `policy` є обов’язковими за схемою +`server`, `features`, `snapshot` і `policy` є обов’язковими згідно зі схемою (`src/gateway/protocol/schema/frames.ts`). `auth` також є обов’язковим і повідомляє -узгоджені роль/області. `canvasHostUrl` є необов’язковим. +узгоджені роль/області дії. `canvasHostUrl` є необов’язковим. Коли токен пристрою не видається, `hello-ok.auth` повідомляє узгоджені дозволи без полів токена: @@ -120,15 +120,15 @@ Gateway → Client: } ``` -Довірені backend-клієнти в тому самому процесі (`client.id: "gateway-client"`, -`client.mode: "backend"`) можуть не передавати `device` у прямих loopback-підключеннях, коли -вони проходять автентифікацію за допомогою спільного токена/пароля gateway. Цей шлях зарезервовано -для внутрішніх RPC control plane і не дає застарілим базовим значенням зіставлення CLI/пристроїв -блокувати локальну backend-роботу, таку як оновлення сесій субагентів. Віддалені клієнти, -клієнти з browser-origin, Node-клієнти та явні клієнти з device-token/device-identity -і далі використовують звичайні перевірки зіставлення та підвищення scope. +Довірені backend-клієнти того ж процесу (`client.id: "gateway-client"`, +`client.mode: "backend"`) можуть не передавати `device` у прямих loopback-підключеннях, якщо +вони автентифікуються за допомогою спільного токена/пароля Gateway. Цей шлях зарезервовано +для внутрішніх RPC площини керування й дає змогу уникнути того, щоб застарілі базові значення +спарювання CLI/пристрою блокували локальну backend-роботу, як-от оновлення сесій субагентів. Віддалені клієнти, +клієнти з походженням із браузера, клієнти вузлів і явні клієнти з токеном пристрою/ідентичністю пристрою +усе ще використовують звичайні перевірки спарювання та підвищення області дії. -Коли видається токен пристрою, `hello-ok` також містить: +Коли токен пристрою видається, `hello-ok` також містить: ```json { @@ -140,8 +140,8 @@ Gateway → Client: } ``` -Під час передачі в довіреному bootstrap `hello-ok.auth` також може містити -додаткові обмежені записи ролей у `deviceTokens`: +Під час передавання довіреного bootstrap `hello-ok.auth` також може містити додаткові +обмежені записи ролей у `deviceTokens`: ```json { @@ -160,14 +160,14 @@ Gateway → Client: } ``` -Для вбудованого bootstrap-процесу Node/operator основний токен Node залишається -`scopes: []`, а будь-який переданий токен operator залишається обмеженим allowlist bootstrap-оператора -(`operator.approvals`, `operator.read`, -`operator.talk.secrets`, `operator.write`). Перевірки scope під час bootstrap залишаються -прив’язаними до префікса ролі: записи operator задовольняють лише запити operator, а ролі, -які не є operator, і далі потребують scopes під префіксом власної ролі. +Для вбудованого bootstrap-потоку вузол/оператор первинний токен вузла лишається +`scopes: []`, а будь-який переданий токен оператора лишається обмеженим списком +дозволених bootstrap-областей оператора (`operator.approvals`, `operator.read`, +`operator.talk.secrets`, `operator.write`). Перевірки bootstrap-областей дії лишаються +прив’язаними до префікса ролі: записи оператора задовольняють лише запити оператора, а ролям, +що не є оператором, усе ще потрібні області дії під префіксом їхньої власної ролі. -### Приклад Node +### Приклад вузла ```json { @@ -208,18 +208,18 @@ Gateway → Client: - **Відповідь**: `{type:"res", id, ok, payload|error}` - **Подія**: `{type:"event", event, payload, seq?, stateVersion?}` -Методи з побічними ефектами потребують **ключів ідемпотентності** (див. схему). +Методи з побічними ефектами вимагають **ключі ідемпотентності** (див. схему). -## Ролі + scopes +## Ролі + області дії ### Ролі -- `operator` = клієнт control plane (CLI/UI/автоматизація). +- `operator` = клієнт площини керування (CLI/UI/автоматизація). - `node` = хост можливостей (camera/screen/canvas/system.run). -### Scopes (operator) +### Області дії (operator) -Поширені scopes: +Поширені області дії: - `operator.read` - `operator.write` @@ -228,265 +228,265 @@ Gateway → Client: - `operator.pairing` - `operator.talk.secrets` -`talk.config` з `includeSecrets: true` потребує `operator.talk.secrets` +`talk.config` з `includeSecrets: true` вимагає `operator.talk.secrets` (або `operator.admin`). -RPC-методи Gateway, зареєстровані Plugin, можуть запитувати власний scope operator, але +RPC-методи Gateway, зареєстровані Plugin, можуть запитувати власну область дії оператора, але зарезервовані основні admin-префікси (`config.*`, `exec.approvals.*`, `wizard.*`, -`update.*`) завжди визначаються як `operator.admin`. +`update.*`) завжди зіставляються з `operator.admin`. -Scope методу — це лише перший шлюз. Деякі слеш-команди, викликані через -`chat.send`, додатково застосовують суворіші перевірки на рівні команди. Наприклад, -постійні записи `/config set` і `/config unset` потребують `operator.admin`. +Область дії методу — лише перший рівень перевірки. Деякі slash-команди, доступні через +`chat.send`, додатково застосовують суворіші перевірки на рівні команди. Наприклад, постійні +записи `/config set` і `/config unset` вимагають `operator.admin`. -`node.pair.approve` також має додаткову перевірку scope під час погодження поверх -базового scope методу: +`node.pair.approve` також має додаткову перевірку області дії під час схвалення поверх +базової області дії методу: - запити без команд: `operator.pairing` -- запити з Node-командами без exec: `operator.pairing` + `operator.write` -- запити, які містять `system.run`, `system.run.prepare` або `system.which`: +- запити з командами вузла, що не належать до exec: `operator.pairing` + `operator.write` +- запити, що містять `system.run`, `system.run.prepare` або `system.which`: `operator.pairing` + `operator.admin` ### Caps/commands/permissions (node) -Nodes оголошують claims можливостей під час підключення: +Вузли оголошують заявлені можливості під час підключення: -- `caps`: високорівневі категорії можливостей. -- `commands`: allowlist команд для invoke. +- `caps`: категорії можливостей високого рівня. +- `commands`: список дозволених команд для invoke. - `permissions`: детальні перемикачі (наприклад, `screen.record`, `camera.capture`). -Gateway розглядає їх як **claims** і застосовує allowlist на боці сервера. +Gateway розглядає їх як **заявлені можливості** й застосовує списки дозволів на боці сервера. ## Presence - `system-presence` повертає записи з ключами за ідентичністю пристрою. -- Записи presence включають `deviceId`, `roles` і `scopes`, щоб UI могли показувати один рядок на пристрій - навіть коли він підключається і як **operator**, і як **node**. +- Записи присутності містять `deviceId`, `roles` і `scopes`, щоб UI могли показувати один рядок на пристрій, + навіть якщо він підключається і як **operator**, і як **node**. -## Обмеження області broadcast-подій +## Обмеження областю дії для широкомовних подій -Broadcast-події WebSocket, які надсилає сервер, обмежуються scopes, щоб сесії лише з pairing-scope або лише для Node пасивно не отримували вміст сесій. +Широкомовні події WebSocket, які надсилає сервер, обмежуються областями дії, щоб сесії лише з областю спарювання або лише вузлові сесії пасивно не отримували вміст сесій. -- **Фрейми chat, agent і результатів tools** (включно з потоковими подіями `agent` і результатами викликів tools) потребують щонайменше `operator.read`. Сесії без `operator.read` повністю пропускають ці фрейми. -- **Broadcast `plugin.*`, визначені Plugin**, обмежуються `operator.write` або `operator.admin`, залежно від того, як Plugin їх зареєстрував. -- **Події статусу й транспорту** (`heartbeat`, `presence`, `tick`, життєвий цикл connect/disconnect тощо) залишаються без обмежень, щоб стан транспорту лишався видимим для кожної автентифікованої сесії. -- **Невідомі сімейства broadcast-подій** за замовчуванням обмежуються scopes (fail-closed), якщо лише зареєстрований обробник явно не послаблює це. +- **Фрейми чату, агента та результатів інструментів** (включно з потоковими подіями `agent` і результатами викликів інструментів) вимагають щонайменше `operator.read`. Сесії без `operator.read` повністю пропускають ці фрейми. +- **Широкомовні `plugin.*`, визначені Plugin**, обмежуються `operator.write` або `operator.admin` залежно від того, як Plugin їх зареєстрував. +- **Події стану й транспорту** (`heartbeat`, `presence`, `tick`, життєвий цикл connect/disconnect тощо) лишаються без обмежень, щоб стан транспорту залишався видимим для кожної автентифікованої сесії. +- **Невідомі сімейства широкомовних подій** за замовчуванням обмежуються областю дії (режим fail-closed), якщо зареєстрований обробник явно не послаблює це. -Кожне клієнтське підключення має власний номер послідовності для конкретного клієнта, тому broadcast-події зберігають монотонний порядок у цьому сокеті навіть тоді, коли різні клієнти бачать різні підмножини потоку подій, відфільтровані за scope. +Кожне клієнтське підключення підтримує власний порядковий номер на клієнта, тому широкомовні повідомлення зберігають монотонний порядок у цьому сокеті, навіть коли різні клієнти бачать різні підмножини потоку подій, відфільтровані за областями дії. ## Поширені сімейства RPC-методів Публічна WS-поверхня ширша, ніж наведені вище приклади рукостискання/автентифікації. Це не згенерований дамп — `hello-ok.features.methods` є консервативним -списком виявлення, побудованим із `src/gateway/server-methods-list.ts` плюс експортованих методів завантажених Plugin/channel. Розглядайте його як виявлення функцій, а не як повне -перерахування `src/gateway/server-methods/*.ts`. +списком виявлення, зібраним із `src/gateway/server-methods-list.ts` плюс експортованих методів завантажених Plugin/каналів. Розглядайте це як виявлення можливостей, а не як повний +перелік `src/gateway/server-methods/*.ts`. - - `health` повертає кешований або щойно перевірений snapshot стану gateway. - - `diagnostics.stability` повертає нещодавній обмежений recorder стабільності діагностики. Він зберігає операційні метадані, такі як назви подій, кількість, розміри в байтах, показники пам’яті, стан черги/сесії, назви channel/Plugin і session ids. Він не зберігає текст чату, тіла Webhook, результати tools, сирі тіла запитів або відповідей, токени, cookies чи секретні значення. Потрібен scope operator read. - - `status` повертає зведення gateway у стилі `/status`; чутливі поля включаються лише для operator-клієнтів зі scope admin. - - `gateway.identity.get` повертає ідентичність пристрою gateway, яка використовується потоками relay і pairing. - - `system-presence` повертає поточний snapshot presence для підключених пристроїв operator/node. - - `system-event` додає системну подію та може оновлювати/поширювати контекст presence. + - `health` повертає кешований або щойно перевірений знімок стану Gateway. + - `diagnostics.stability` повертає недавній обмежений записувач діагностичної стабільності. Він зберігає операційні метадані, як-от назви подій, кількість, розміри в байтах, показники пам’яті, стан черги/сесії, назви каналів/Plugin та ідентифікатори сесій. Він не зберігає текст чату, тіла Webhook, виводи інструментів, сирі тіла запитів або відповідей, токени, cookie чи секретні значення. Потрібна область дії operator read. + - `status` повертає підсумок Gateway у стилі `/status`; чутливі поля включаються лише для operator-клієнтів з admin-областю дії. + - `gateway.identity.get` повертає ідентичність пристрою Gateway, яка використовується потоками relay і pairing. + - `system-presence` повертає поточний знімок присутності для підключених пристроїв operator/node. + - `system-event` додає системну подію та може оновлювати/транслювати контекст присутності. - `last-heartbeat` повертає останню збережену подію Heartbeat. - - `set-heartbeats` перемикає обробку Heartbeat на gateway. + - `set-heartbeats` перемикає обробку Heartbeat на Gateway. - - `models.list` повертає каталог моделей, дозволених runtime. - - `usage.status` повертає зведення вікон використання провайдерів/залишкової квоти. - - `usage.cost` повертає агреговані зведення вартості використання за діапазон дат. - - `doctor.memory.status` повертає стан готовності vector-memory / embedding для активного робочого простору агента за замовчуванням. - - `sessions.usage` повертає зведення використання для кожної сесії. - - `sessions.usage.timeseries` повертає timeseries використання для однієї сесії. + - `models.list` повертає каталог моделей, дозволених під час виконання. + - `usage.status` повертає підсумки вікон використання провайдера/залишкової квоти. + - `usage.cost` повертає агреговані підсумки вартості використання для діапазону дат. + - `doctor.memory.status` повертає стан готовності векторної пам’яті / кешованих ембедингів для активного робочого простору агента за замовчуванням. Передавайте `{ "probe": true }` або `{ "deep": true }` лише тоді, коли викликач явно хоче живу перевірку провайдера ембедингів. + - `sessions.usage` повертає підсумки використання для кожної сесії. + - `sessions.usage.timeseries` повертає часовий ряд використання для однієї сесії. - `sessions.usage.logs` повертає записи журналу використання для однієї сесії. - - - `channels.status` повертає зведення стану вбудованих + bundled channels/Plugins. - - `channels.logout` виконує вихід із певного channel/account, якщо channel підтримує вихід. - - `web.login.start` запускає QR/web-процес входу для поточного web channel provider, який підтримує QR. - - `web.login.wait` очікує завершення цього QR/web-процесу входу і запускає channel у разі успіху. - - `push.test` надсилає тестовий APNs push до зареєстрованого iOS Node. - - `voicewake.get` повертає збережені тригери wake-word. - - `voicewake.set` оновлює тригери wake-word і поширює зміну. + + - `channels.status` повертає підсумки стану вбудованих і включених каналів/Plugin. + - `channels.logout` виконує вихід із певного каналу/облікового запису там, де канал підтримує вихід. + - `web.login.start` запускає QR-/веб-потік входу для поточного провайдера вебканалу з підтримкою QR. + - `web.login.wait` очікує завершення цього QR-/веб-потоку входу та в разі успіху запускає канал. + - `push.test` надсилає тестовий APNs push до зареєстрованого вузла iOS. + - `voicewake.get` повертає збережені тригери слів активації. + - `voicewake.set` оновлює тригери слів активації та транслює зміну. - - `send` — це прямий RPC доставки назовні для відправлень до channel/account/thread-target поза chat runner. - - `logs.tail` повертає tail налаштованого файлового журналу gateway з керуванням cursor/limit і максимальним числом байтів. + - `send` — це прямий RPC доставки назовні для надсилань, націлених на канал/обліковий запис/гілку, поза виконувачем чату. + - `logs.tail` повертає tail налаштованого файлового журналу Gateway з контролем cursor/limit і max-byte. - - `talk.config` повертає effective payload конфігурації Talk; `includeSecrets` потребує `operator.talk.secrets` (або `operator.admin`). - - `talk.mode` задає/поширює поточний стан режиму Talk для клієнтів WebChat/Control UI. - - `talk.speak` синтезує мовлення через активного speech provider Talk. - - `tts.status` повертає стан увімкнення TTS, активного provider, резервних providers і стан конфігурації provider. - - `tts.providers` повертає видимий інвентар TTS providers. + - `talk.config` повертає ефективне корисне навантаження конфігурації Talk; `includeSecrets` вимагає `operator.talk.secrets` (або `operator.admin`). + - `talk.mode` встановлює/транслює поточний стан режиму Talk для клієнтів WebChat/Control UI. + - `talk.speak` синтезує мовлення через активний провайдер мовлення Talk. + - `tts.status` повертає стан увімкнення TTS, активного провайдера, резервних провайдерів і стан конфігурації провайдера. + - `tts.providers` повертає видимий інвентар провайдерів TTS. - `tts.enable` і `tts.disable` перемикають стан налаштувань TTS. - - `tts.setProvider` оновлює бажаного TTS provider. - - `tts.convert` виконує одноразове перетворення text-to-speech. + - `tts.setProvider` оновлює бажаного провайдера TTS. + - `tts.convert` виконує одноразове перетворення тексту на мовлення. - - - `secrets.reload` повторно визначає активні SecretRef і змінює стан секретів runtime лише за повного успіху. - - `secrets.resolve` визначає присвоєння секретів, націлених на команди, для конкретного набору command/target. - - `config.get` повертає поточний snapshot конфігурації та hash. - - `config.set` записує валідований payload конфігурації. - - `config.patch` об’єднує часткове оновлення конфігурації. - - `config.apply` валідує + замінює повний payload конфігурації. - - `config.schema` повертає payload живої схеми конфігурації, яку використовують Control UI і CLI tooling: schema, `uiHints`, версію та метадані генерації, включно з метаданими схеми Plugin + channel, коли runtime може їх завантажити. Схема включає метадані полів `title` / `description`, отримані з тих самих міток і тексту довідки, які використовує UI, включно з гілками композиції вкладених об’єктів, wildcard, елементів масиву та `anyOf` / `oneOf` / `allOf`, коли для відповідних полів існує документація. - - `config.schema.lookup` повертає payload пошуку, обмежений шляхом, для одного шляху конфігурації: нормалізований шлях, неглибокий вузол схеми, відповідний hint + `hintPath` і зведення безпосередніх дочірніх елементів для деталізації в UI/CLI. Вузли схеми lookup зберігають орієнтовану на користувача документацію та поширені поля валідації (`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, числові/рядкові/масивні/об’єктні межі та прапори на кшталт `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`). Зведення дочірніх елементів показують `key`, нормалізований `path`, `type`, `required`, `hasChildren`, а також відповідні `hint` / `hintPath`. - - `update.run` запускає потік оновлення gateway і планує перезапуск лише тоді, коли саме оновлення було успішним. - - `update.status` повертає останній кешований sentinel перезапуску оновлення, включно з версією після перезапуску, якщо вона доступна. - - `wizard.start`, `wizard.next`, `wizard.status` і `wizard.cancel` відкривають onboarding wizard через WS RPC. + + - `secrets.reload` повторно резолвить активні SecretRefs і замінює стан секретів під час виконання лише в разі повного успіху. + - `secrets.resolve` резолвить призначення секретів, націлені на команди, для конкретного набору команд/цілей. + - `config.get` повертає поточний знімок конфігурації та hash. + - `config.set` записує валідований конфігураційний payload. + - `config.patch` зливає часткове оновлення конфігурації. + - `config.apply` валідовує й замінює повний конфігураційний payload. + - `config.schema` повертає payload схеми живої конфігурації, який використовують Control UI та інструменти CLI: схема, `uiHints`, версія та метадані генерації, включно з метаданими схем Plugin + каналів, коли середовище виконання може їх завантажити. Схема містить метадані полів `title` / `description`, похідні від тих самих міток і довідкового тексту, які використовує UI, зокрема для вкладених об’єктів, wildcard, елементів масиву та гілок композиції `anyOf` / `oneOf` / `allOf`, коли існує відповідна документація поля. + - `config.schema.lookup` повертає payload пошуку з обмеженням шляхом для одного шляху конфігурації: нормалізований шлях, поверхневий вузол схеми, зіставлену підказку + `hintPath` і зведення безпосередніх дочірніх елементів для деталізації в UI/CLI. Вузли схеми пошуку зберігають орієнтовану на користувача документацію та поширені поля валідації (`title`, `description`, `type`, `enum`, `const`, `format`, `pattern`, числові/рядкові/масивні/об’єктні межі та прапорці на кшталт `additionalProperties`, `deprecated`, `readOnly`, `writeOnly`). Зведення дочірніх елементів показують `key`, нормалізований `path`, `type`, `required`, `hasChildren`, а також зіставлені `hint` / `hintPath`. + - `update.run` запускає потік оновлення Gateway і планує перезапуск лише тоді, коли саме оновлення було успішним. + - `update.status` повертає останній кешований sentinel перезапуску оновлення, включно з версією, що працює після перезапуску, якщо вона доступна. + - `wizard.start`, `wizard.next`, `wizard.status` і `wizard.cancel` відкривають майстер onboarding через WS RPC. - + - `agents.list` повертає налаштовані записи агентів. - - `agents.create`, `agents.update` і `agents.delete` керують записами агентів і wiring робочого простору. - - `agents.files.list`, `agents.files.get` і `agents.files.set` керують файлами bootstrap-робочого простору, відкритими для агента. - - `agent.identity.get` повертає effective identity асистента для агента або сесії. - - `agent.wait` очікує завершення run і повертає terminal snapshot, якщо він доступний. + - `agents.create`, `agents.update` і `agents.delete` керують записами агентів і прив’язкою робочого простору. + - `agents.files.list`, `agents.files.get` і `agents.files.set` керують файлами bootstrap-робочого простору, доступними для агента. + - `agent.identity.get` повертає ефективну ідентичність помічника для агента або сесії. + - `agent.wait` очікує завершення запуску й повертає термінальний знімок, якщо він доступний. - `sessions.list` повертає поточний індекс сесій. - - `sessions.subscribe` і `sessions.unsubscribe` вмикають або вимикають підписки на події змін сесій для поточного WS-клієнта. - - `sessions.messages.subscribe` і `sessions.messages.unsubscribe` вмикають або вимикають підписки на події transcript/message для однієї сесії. - - `sessions.preview` повертає обмежені попередні перегляди transcript для конкретних ключів сесій. - - `sessions.resolve` визначає або канонізує ціль сесії. + - `sessions.subscribe` і `sessions.unsubscribe` вмикають або вимикають підписки на події змін сесії для поточного WS-клієнта. + - `sessions.messages.subscribe` і `sessions.messages.unsubscribe` вмикають або вимикають підписки на події стенограми/повідомлень для однієї сесії. + - `sessions.preview` повертає обмежені попередні перегляди стенограм для конкретних ключів сесій. + - `sessions.resolve` резолвить або канонізує ціль сесії. - `sessions.create` створює новий запис сесії. - `sessions.send` надсилає повідомлення в наявну сесію. - - `sessions.steer` — це варіант interrupt-and-steer для активної сесії. + - `sessions.steer` — це варіант переривання й коригування для активної сесії. - `sessions.abort` перериває активну роботу для сесії. - - `sessions.patch` оновлює метадані/перевизначення сесії. - - `sessions.reset`, `sessions.delete` і `sessions.compact` виконують обслуговування сесій. + - `sessions.patch` оновлює метадані/override сесії. + - `sessions.reset`, `sessions.delete` і `sessions.compact` виконують обслуговування сесії. - `sessions.get` повертає повний збережений рядок сесії. - - Виконання чату й далі використовує `chat.history`, `chat.send`, `chat.abort` і `chat.inject`. `chat.history` нормалізується для відображення для UI-клієнтів: вбудовані теги директив прибираються з видимого тексту, XML payload викликів tools у plain-text (включно з `...`, `...`, `...`, `...` і обрізаними блоками викликів tools) та витоки ASCII/full-width токенів керування моделлю прибираються, суто тихі рядки асистента, як-от точні `NO_REPLY` / `no_reply`, пропускаються, а надто великі рядки можуть замінюватися заповнювачами. + - Виконання чату, як і раніше, використовує `chat.history`, `chat.send`, `chat.abort` і `chat.inject`. `chat.history` нормалізується для відображення для UI-клієнтів: вбудовані теги директив прибираються з видимого тексту, XML-payload викликів інструментів у plain text (зокрема `...`, `...`, `...`, `...` і усічені блоки викликів інструментів) та витоки ASCII/full-width токенів керування моделлю прибираються, чисті рядки помічника з тихими токенами, як-от точні `NO_REPLY` / `no_reply`, пропускаються, а завеликі рядки можуть бути замінені заповнювачами. - - - `device.pair.list` повертає очікувані та схвалені зіставлені пристрої. - - `device.pair.approve`, `device.pair.reject` і `device.pair.remove` керують записами зіставлення пристроїв. - - `device.token.rotate` змінює токен зіставленого пристрою в межах його схваленої ролі та обмежень scope викликача. - - `device.token.revoke` відкликає токен зіставленого пристрою в межах його схваленої ролі та обмежень scope викликача. + + - `device.pair.list` повертає очікувані й схвалені спарені пристрої. + - `device.pair.approve`, `device.pair.reject` і `device.pair.remove` керують записами спарювання пристроїв. + - `device.token.rotate` ротує токен спареного пристрою в межах його схваленої ролі та меж області дії викликача. + - `device.token.revoke` відкликає токен спареного пристрою в межах його схваленої ролі та меж області дії викликача. - - - `node.pair.request`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.remove` і `node.pair.verify` охоплюють зіставлення Node і перевірку bootstrap. - - `node.list` і `node.describe` повертають стан відомих/підключених Nodes. - - `node.rename` оновлює мітку зіставленого Node. - - `node.invoke` пересилає команду до підключеного Node. + + - `node.pair.request`, `node.pair.list`, `node.pair.approve`, `node.pair.reject`, `node.pair.remove` і `node.pair.verify` охоплюють спарювання вузлів і bootstrap-перевірку. + - `node.list` і `node.describe` повертають стан відомих/підключених вузлів. + - `node.rename` оновлює мітку спареного вузла. + - `node.invoke` пересилає команду підключеному вузлу. - `node.invoke.result` повертає результат для запиту invoke. - - `node.event` передає події, що походять від Node, назад у gateway. - - `node.canvas.capability.refresh` оновлює токени можливостей canvas з обмеженою областю. - - `node.pending.pull` і `node.pending.ack` — це API черги для підключених Nodes. - - `node.pending.enqueue` і `node.pending.drain` керують надійною очікуваною роботою для offline/disconnected Nodes. + - `node.event` переносить події, що походять від вузла, назад у Gateway. + - `node.canvas.capability.refresh` оновлює токени можливостей canvas з обмеженням областю дії. + - `node.pending.pull` і `node.pending.ack` — це API черги підключеного вузла. + - `node.pending.enqueue` і `node.pending.drain` керують стійкою очікуваною роботою для офлайнових/відключених вузлів. - - - `exec.approval.request`, `exec.approval.get`, `exec.approval.list` і `exec.approval.resolve` охоплюють одноразові запити на погодження exec, а також пошук/повторення очікуваних погоджень. - - `exec.approval.waitDecision` очікує рішення для одного очікуваного погодження exec і повертає фінальне рішення (або `null` за тайм-аутом). - - `exec.approvals.get` і `exec.approvals.set` керують snapshot політики погоджень exec gateway. - - `exec.approvals.node.get` і `exec.approvals.node.set` керують локальною політикою погоджень exec Node через relay-команди Node. - - `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` і `plugin.approval.resolve` охоплюють потоки погоджень, визначені Plugin. + + - `exec.approval.request`, `exec.approval.get`, `exec.approval.list` і `exec.approval.resolve` охоплюють разові запити схвалення exec, а також пошук/повторення очікуваних схвалень. + - `exec.approval.waitDecision` очікує на одне очікуване схвалення exec і повертає остаточне рішення (або `null` у разі тайм-ауту). + - `exec.approvals.get` і `exec.approvals.set` керують знімками політики схвалення exec Gateway. + - `exec.approvals.node.get` і `exec.approvals.node.set` керують локальною для вузла політикою схвалення exec через relay-команди вузла. + - `plugin.approval.request`, `plugin.approval.list`, `plugin.approval.waitDecision` і `plugin.approval.resolve` охоплюють потоки схвалення, визначені Plugin. - - - Автоматизація: `wake` планує негайне або на наступний Heartbeat вбудовування тексту пробудження; `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` керують запланованою роботою. - - Skills і tools: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`. + + - Автоматизація: `wake` планує негайне або на наступний Heartbeat введення тексту пробудження; `cron.list`, `cron.status`, `cron.add`, `cron.update`, `cron.remove`, `cron.run`, `cron.runs` керують запланованою роботою. + - Skills та інструменти: `commands.list`, `skills.*`, `tools.catalog`, `tools.effective`. ### Поширені сімейства подій -- `chat`: оновлення чату UI, такі як `chat.inject` та інші - події чату лише для transcript. -- `session.message` і `session.tool`: оновлення transcript/потоку подій для - сесії з підпискою. +- `chat`: оновлення UI-чату, як-от `chat.inject` та інші події чату, + пов’язані лише зі стенограмою. +- `session.message` і `session.tool`: оновлення стенограми/потоку подій для + підписаної сесії. - `sessions.changed`: індекс сесій або метадані змінилися. -- `presence`: оновлення snapshot system presence. -- `tick`: періодична keepalive / liveness-подія. -- `health`: оновлення snapshot стану gateway. +- `presence`: оновлення знімка системної присутності. +- `tick`: періодична подія keepalive / перевірки життєздатності. +- `health`: оновлення знімка стану Gateway. - `heartbeat`: оновлення потоку подій Heartbeat. -- `cron`: подія зміни run/job Cron. -- `shutdown`: сповіщення про завершення роботи gateway. -- `node.pair.requested` / `node.pair.resolved`: життєвий цикл зіставлення Node. -- `node.invoke.request`: broadcast запиту invoke Node. -- `device.pair.requested` / `device.pair.resolved`: життєвий цикл зіставленого пристрою. -- `voicewake.changed`: конфігурація тригерів wake-word змінилася. +- `cron`: подія зміни запуску/завдання Cron. +- `shutdown`: сповіщення про вимкнення Gateway. +- `node.pair.requested` / `node.pair.resolved`: життєвий цикл спарювання вузла. +- `node.invoke.request`: широкомовний запит invoke вузла. +- `device.pair.requested` / `device.pair.resolved`: життєвий цикл спареного пристрою. +- `voicewake.changed`: змінилася конфігурація тригерів слів активації. - `exec.approval.requested` / `exec.approval.resolved`: життєвий цикл - погодження exec. + схвалення exec. - `plugin.approval.requested` / `plugin.approval.resolved`: життєвий цикл - погодження Plugin. + схвалення Plugin. -### Допоміжні методи Node +### Допоміжні методи вузла -- Nodes можуть викликати `skills.bins`, щоб отримати поточний список виконуваних файлів Skills +- Вузли можуть викликати `skills.bins`, щоб отримати поточний список виконуваних файлів Skills для перевірок auto-allow. -### Допоміжні методи operator +### Допоміжні методи оператора -- Operators можуть викликати `commands.list` (`operator.read`), щоб отримати runtime-інвентар - команд для агента. - - `agentId` необов’язковий; пропустіть його, щоб читати робочий простір агента за замовчуванням. - - `scope` керує тим, яку поверхню націлює основний `name`: +- Оператори можуть викликати `commands.list` (`operator.read`), щоб отримати + інвентар команд середовища виконання для агента. + - `agentId` є необов’язковим; опустіть його, щоб читати робочий простір агента за замовчуванням. + - `scope` керує тим, на яку поверхню націлено основне `name`: - `text` повертає основний текстовий токен команди без початкового `/` - - `native` і шлях за замовчуванням `both` повертають names native з урахуванням provider, + - `native` і стандартний шлях `both` повертають обізнані з провайдером native-імена, коли вони доступні - - `textAliases` містить точні slash-аліаси, такі як `/model` і `/m`. - - `nativeName` містить native name з урахуванням provider, коли вона існує. - - `provider` необов’язковий і впливає лише на native naming плюс доступність native - команд Plugin. - - `includeArgs=false` пропускає серіалізовані метадані аргументів у відповіді. -- Operators можуть викликати `tools.catalog` (`operator.read`), щоб отримати runtime-каталог tools для - агента. Відповідь містить згруповані tools і метадані походження: + - `textAliases` містить точні slash-аліаси, як-от `/model` і `/m`. + - `nativeName` містить обізнану з провайдером native-назву команди, коли вона існує. + - `provider` є необов’язковим і впливає лише на native-іменування та доступність native-команд + Plugin. + - `includeArgs=false` пропускає серіалізовані метадані аргументів із відповіді. +- Оператори можуть викликати `tools.catalog` (`operator.read`), щоб отримати каталог інструментів середовища виконання для + агента. Відповідь містить згруповані інструменти та метадані походження: - `source`: `core` або `plugin` - `pluginId`: власник Plugin, коли `source="plugin"` - - `optional`: чи є tool Plugin необов’язковим -- Operators можуть викликати `tools.effective` (`operator.read`), щоб отримати effective runtime-інвентар tools + - `optional`: чи є інструмент Plugin необов’язковим +- Оператори можуть викликати `tools.effective` (`operator.read`), щоб отримати фактичний інвентар інструментів середовища виконання для сесії. - - `sessionKey` обов’язковий. - - Gateway визначає довірений контекст runtime із сесії на боці сервера, замість того щоб приймати - наданий викликачем контекст auth або delivery. - - Відповідь має область сесії та відображає, що активна розмова може використовувати прямо зараз, - включно з tools core, Plugin і channel. -- Operators можуть викликати `skills.status` (`operator.read`), щоб отримати видимий + - `sessionKey` є обов’язковим. + - Gateway виводить довірений контекст середовища виконання із сесії на боці сервера, а не приймає + автентифікацію або контекст доставки, надані викликачем. + - Відповідь прив’язана до сесії й відображає те, що активна розмова може використовувати прямо зараз, + зокрема інструменти core, Plugin і каналів. +- Оператори можуть викликати `skills.status` (`operator.read`), щоб отримати видимий інвентар Skills для агента. - - `agentId` необов’язковий; пропустіть його, щоб читати робочий простір агента за замовчуванням. - - Відповідь містить eligibility, відсутні вимоги, перевірки конфігурації та + - `agentId` є необов’язковим; опустіть його, щоб читати робочий простір агента за замовчуванням. + - Відповідь містить придатність, відсутні вимоги, перевірки конфігурації та санітизовані параметри встановлення без розкриття сирих секретних значень. -- Operators можуть викликати `skills.search` і `skills.detail` (`operator.read`) для +- Оператори можуть викликати `skills.search` і `skills.detail` (`operator.read`) для метаданих виявлення ClawHub. -- Operators можуть викликати `skills.install` (`operator.admin`) у двох режимах: +- Оператори можуть викликати `skills.install` (`operator.admin`) у двох режимах: - Режим ClawHub: `{ source: "clawhub", slug, version?, force? }` встановлює - папку Skill у директорію `skills/` робочого простору агента за замовчуванням. - - Режим інсталятора gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` - запускає оголошену дію `metadata.openclaw.install` на хості gateway. -- Operators можуть викликати `skills.update` (`operator.admin`) у двох режимах: + теку skill до каталогу `skills/` робочого простору агента за замовчуванням. + - Режим інсталятора Gateway: `{ name, installId, dangerouslyForceUnsafeInstall?, timeoutMs? }` + запускає оголошену дію `metadata.openclaw.install` на хості Gateway. +- Оператори можуть викликати `skills.update` (`operator.admin`) у двох режимах: - Режим ClawHub оновлює один відстежуваний slug або всі відстежувані встановлення ClawHub у робочому просторі агента за замовчуванням. - - Режим конфігурації патчить значення `skills.entries.`, такі як `enabled`, + - Режим конфігурації змінює значення `skills.entries.`, як-от `enabled`, `apiKey` і `env`. -## Погодження exec +## Схвалення exec -- Коли запит exec потребує погодження, gateway поширює `exec.approval.requested`. -- Operator-клієнти виконують погодження, викликаючи `exec.approval.resolve` (потрібен scope `operator.approvals`). +- Коли запит exec потребує схвалення, Gateway транслює `exec.approval.requested`. +- Клієнти-оператори виконують підтвердження викликом `exec.approval.resolve` (потрібна область дії `operator.approvals`). - Для `host=node` `exec.approval.request` має містити `systemRunPlan` (канонічні `argv`/`cwd`/`rawCommand`/метадані сесії). Запити без `systemRunPlan` відхиляються. -- Після погодження переслані виклики `node.invoke system.run` повторно використовують цей канонічний - `systemRunPlan` як авторитетний контекст command/cwd/session. +- Після схвалення переслані виклики `node.invoke system.run` повторно використовують цей канонічний + `systemRunPlan` як авторитетний контекст команди/cwd/сесії. - Якщо викликач змінює `command`, `rawCommand`, `cwd`, `agentId` або - `sessionKey` між prepare і фінальним пересиланням погодженого `system.run`, - gateway відхиляє виконання замість того, щоб довіряти зміненому payload. + `sessionKey` між prepare і фінальним схваленим пересиланням `system.run`, шлюз + відхиляє запуск замість того, щоб довіряти зміненому payload. ## Резервна доставка агента -- Запити `agent` можуть містити `deliver=true`, щоб запитати вихідну доставку. -- `bestEffortDeliver=false` зберігає сувору поведінку: нерозв’язані або лише внутрішні цілі доставки повертають `INVALID_REQUEST`. -- `bestEffortDeliver=true` дозволяє резервний перехід до виконання лише в межах сесії, коли неможливо визначити зовнішній маршрут доставки (наприклад, internal/webchat-сесії або неоднозначні багатоканальні конфігурації). +- Запити `agent` можуть містити `deliver=true`, щоб запросити вихідну доставку. +- `bestEffortDeliver=false` зберігає сувору поведінку: невизначені або лише внутрішні цілі доставки повертають `INVALID_REQUEST`. +- `bestEffortDeliver=true` дозволяє резервне виконання лише в межах сесії, коли неможливо визначити зовнішній маршрут доставки (наприклад, для внутрішніх/webchat-сесій або неоднозначних конфігурацій кількох каналів). ## Версіонування @@ -499,136 +499,138 @@ Broadcast-події WebSocket, які надсилає сервер, обмеж ### Константи клієнта -Еталонний клієнт у `src/gateway/client.ts` використовує ці значення за замовчуванням. Ці значення +Референсний клієнт у `src/gateway/client.ts` використовує ці значення за замовчуванням. Вони стабільні в межах протоколу v3 і є очікуваною базовою лінією для сторонніх клієнтів. -| Константа | Значення за замовчуванням | Джерело | -| ----------------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- | -| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` | -| Тайм-аут запиту (для кожного RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) | -| Тайм-аут preauth / connect-challenge | `10_000` ms | `src/gateway/handshake-timeouts.ts` (clamp `250`–`10_000`) | -| Початковий backoff повторного підключення | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) | -| Максимальний backoff повторного підключення | `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) | -| Fast-retry clamp після закриття device-token | `250` ms | `src/gateway/client.ts` | -| Пільговий період force-stop перед `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | -| Тайм-аут `stopAndWait()` за замовчуванням | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | -| Інтервал tick за замовчуванням (до `hello-ok`) | `30_000` ms | `src/gateway/client.ts` | -| Закриття через тайм-аут tick | код `4000`, коли тиша перевищує `tickIntervalMs * 2` | `src/gateway/client.ts` | -| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` | +| Константа | Значення за замовчуванням | Джерело | +| ------------------------------------------ | ------------------------------------------------------ | ---------------------------------------------------------- | +| `PROTOCOL_VERSION` | `3` | `src/gateway/protocol/schema/protocol-schemas.ts` | +| Тайм-аут запиту (на RPC) | `30_000` ms | `src/gateway/client.ts` (`requestTimeoutMs`) | +| Тайм-аут preauth / connect-challenge | `10_000` ms | `src/gateway/handshake-timeouts.ts` (clamp `250`–`10_000`) | +| Початковий backoff повторного підключення | `1_000` ms | `src/gateway/client.ts` (`backoffMs`) | +| Максимальний backoff повторного підключення| `30_000` ms | `src/gateway/client.ts` (`scheduleReconnect`) | +| Fast-retry clamp після закриття device-token | `250` ms | `src/gateway/client.ts` | +| Пільговий інтервал force-stop перед `terminate()` | `250` ms | `FORCE_STOP_TERMINATE_GRACE_MS` | +| Тайм-аут `stopAndWait()` за замовчуванням | `1_000` ms | `STOP_AND_WAIT_TIMEOUT_MS` | +| Інтервал tick за замовчуванням (до `hello-ok`) | `30_000` ms | `src/gateway/client.ts` | +| Закриття через тайм-аут tick | код `4000`, коли тиша перевищує `tickIntervalMs * 2` | `src/gateway/client.ts` | +| `MAX_PAYLOAD_BYTES` | `25 * 1024 * 1024` (25 MB) | `src/gateway/server-constants.ts` | -Сервер оголошує effective `policy.tickIntervalMs`, `policy.maxPayload` -і `policy.maxBufferedBytes` у `hello-ok`; клієнти мають дотримуватися саме цих значень, +Сервер оголошує фактичні `policy.tickIntervalMs`, `policy.maxPayload` +і `policy.maxBufferedBytes` у `hello-ok`; клієнти повинні дотримуватися цих значень, а не значень за замовчуванням до рукостискання. -## Auth +## Автентифікація -- Автентифікація gateway через спільний секрет використовує `connect.params.auth.token` або - `connect.params.auth.password`, залежно від налаштованого режиму auth. -- Режими з ідентичністю, такі як Tailscale Serve +- Автентифікація Gateway за спільним секретом використовує `connect.params.auth.token` або + `connect.params.auth.password` залежно від налаштованого режиму автентифікації. +- Режими з ідентичністю, як-от Tailscale Serve (`gateway.auth.allowTailscale: true`) або не-loopback - `gateway.auth.mode: "trusted-proxy"`, задовольняють перевірку auth під час connect на основі - заголовків запиту, а не `connect.params.auth.*`. -- `gateway.auth.mode: "none"` для приватного ingress повністю пропускає auth connect через спільний секрет; не відкривайте цей режим у публічному/недовіреному ingress. -- Після зіставлення Gateway видає **токен пристрою**, обмежений роллю + scopes - підключення. Він повертається в `hello-ok.auth.deviceToken` і має - зберігатися клієнтом для майбутніх підключень. -- Клієнти мають зберігати основний `hello-ok.auth.deviceToken` після будь-якого + `gateway.auth.mode: "trusted-proxy"`, задовольняють перевірку автентифікації connect через + заголовки запиту замість `connect.params.auth.*`. +- Приватний ingress `gateway.auth.mode: "none"` повністю пропускає автентифікацію connect зі спільним секретом; не виставляйте цей режим у публічний/недовірений ingress. +- Після спарювання Gateway видає **токен пристрою** з обмеженням за роллю підключення + областями дії. Він повертається в `hello-ok.auth.deviceToken`, і клієнт повинен зберігати його для майбутніх підключень. +- Клієнти повинні зберігати основний `hello-ok.auth.deviceToken` після будь-якого успішного підключення. -- Повторне підключення з цим **збереженим** токеном пристрою також має повторно використовувати - збережений схвалений набір scope для цього токена. Це зберігає доступ на - читання/probe/status, який уже було надано, і не дає повторним підключенням непомітно звузитися до - вужчого неявного admin-only scope. -- Збирання client-side connect auth (`selectConnectAuth` у +- Повторне підключення з цим **збереженим** токеном пристрою також повинно повторно використовувати + збережений схвалений набір областей дії для цього токена. Це зберігає вже наданий доступ на + читання/перевірку/стан і запобігає тихому звуженню повторних підключень до + вужчої неявної області дії лише admin. +- Збирання автентифікації connect на боці клієнта (`selectConnectAuth` у `src/gateway/client.ts`): - - `auth.password` є ортогональним і завжди пересилається, якщо заданий. - - `auth.token` заповнюється в такому порядку пріоритету: спочатку явний shared token, - потім явний `deviceToken`, потім збережений токен для конкретного пристрою (ключ за + - `auth.password` є ортогональним і завжди пересилається, коли заданий. + - `auth.token` заповнюється в такому порядку пріоритету: спочатку явний спільний токен, + потім явний `deviceToken`, потім збережений токен для пристрою (з ключем за `deviceId` + `role`). - - `auth.bootstrapToken` надсилається лише тоді, коли жодне з попередніх значень не визначило - `auth.token`. Shared token або будь-який визначений токен пристрою його пригнічують. + - `auth.bootstrapToken` надсилається, лише коли жоден із варіантів вище не визначив + `auth.token`. Спільний токен або будь-який визначений токен пристрою його пригнічує. - Автопідвищення збереженого токена пристрою під час одноразової повторної спроби `AUTH_TOKEN_MISMATCH` обмежене **лише довіреними endpoint** — - loopback або `wss://` із pinned `tlsFingerprint`. Публічний `wss://` + loopback або `wss://` із закріпленим `tlsFingerprint`. Публічний `wss://` без pinning не підходить. -- Додаткові записи `hello-ok.auth.deviceTokens` — це токени передачі bootstrap. - Зберігайте їх лише тоді, коли connect використовував bootstrap auth через довірений transport, +- Додаткові записи `hello-ok.auth.deviceTokens` — це токени передавання bootstrap. + Зберігайте їх лише тоді, коли підключення використовувало bootstrap-автентифікацію на довіреному транспорті, наприклад `wss://` або loopback/local pairing. -- Якщо клієнт надає **явний** `deviceToken` або явні `scopes`, цей - запитаний викликачем набір scope залишається авторитетним; кешовані scopes повторно використовуються лише тоді, коли клієнт повторно використовує збережений токен для конкретного пристрою. -- Токени пристрою можна змінювати/відкликати через `device.token.rotate` і - `device.token.revoke` (потрібен scope `operator.pairing`). +- Якщо клієнт передає **явний** `deviceToken` або явні `scopes`, цей запитаний викликачем + набір областей дії лишається авторитетним; кешовані області дії повторно використовуються лише тоді, + коли клієнт повторно використовує збережений токен для пристрою. +- Токени пристрою можна ротувати/відкликати через `device.token.rotate` і + `device.token.revoke` (потрібна область дії `operator.pairing`). - Видача, ротація та відкликання токенів залишаються обмеженими схваленим набором ролей, - записаним у записі зіставлення цього пристрою; зміна токена не може розширити - або націлитися на роль пристрою, яку схвалення зіставлення ніколи не надавало. -- Для сесій токенів зіставлених пристроїв керування пристроями є self-scoped, якщо - викликач також не має `operator.admin`: викликачі без admin можуть видаляти/відкликати/змінювати + записаним у записі спарювання цього пристрою; зміна токена не може розширити + або націлитися на роль пристрою, яку схвалення спарювання ніколи не надавало. +- Для сесій із токеном спареного пристрою керування пристроєм обмежується самим пристроєм, якщо + викликач також не має `operator.admin`: викликачі без admin можуть видаляти/відкликати/ротувати лише **власний** запис пристрою. -- `device.token.rotate` і `device.token.revoke` також перевіряють набір scope цільового токена operator - відносно поточних scope сесії викликача. Викликачі без admin - не можуть змінювати або відкликати ширший токен operator, ніж той, який уже мають. -- Збої auth включають `error.details.code` плюс підказки для відновлення: +- `device.token.rotate` і `device.token.revoke` також перевіряють набір областей дії + цільового operator-токена відносно поточних областей дії сесії викликача. Викликачі без admin + не можуть ротувати або відкликати ширший operator-токен, ніж той, який вони вже мають. +- Збої автентифікації містять `error.details.code` плюс підказки щодо відновлення: - `error.details.canRetryWithDeviceToken` (boolean) - `error.details.recommendedNextStep` (`retry_with_device_token`, `update_auth_configuration`, `update_auth_credentials`, `wait_then_retry`, `review_auth_configuration`) - Поведінка клієнта для `AUTH_TOKEN_MISMATCH`: - - Довірені клієнти можуть виконати одну обмежену повторну спробу із кешованим токеном для конкретного пристрою. - - Якщо ця повторна спроба не вдається, клієнти мають зупинити автоматичні цикли повторного підключення й показати інструкції для дій оператора. + - Довірені клієнти можуть спробувати одну обмежену повторну спробу з кешованим токеном для пристрою. + - Якщо ця повторна спроба не вдасться, клієнти повинні зупинити автоматичні цикли повторного підключення й показати інструкції щодо дій оператора. -## Ідентичність пристрою + зіставлення +## Ідентичність пристрою + спарювання -- Nodes мають включати стабільну ідентичність пристрою (`device.id`), похідну від +- Вузли повинні включати стабільну ідентичність пристрою (`device.id`), похідну від відбитка keypair. -- Gateways видають токени для кожного пристрою + ролі. -- Для нових `device.id` потрібні погодження зіставлення, якщо не ввімкнено локальне auto-approval. -- Auto-approval зіставлення зосереджено на прямих локальних loopback-підключеннях. -- OpenClaw також має вузький локальний шлях self-connect для backend/container - для довірених потоків допоміжних засобів зі спільним секретом. -- Підключення tailnet або LAN на тому самому хості все одно розглядаються як віддалені для зіставлення й - потребують погодження. +- Gateway видає токени для кожного пристрою + ролі. +- Для нових ідентифікаторів пристроїв потрібні схвалення спарювання, якщо не ввімкнено локальне auto-approval. +- Auto-approval спарювання зосереджене на прямих локальних loopback-підключеннях. +- OpenClaw також має вузький шлях локального самопідключення backend/контейнера для + довірених допоміжних потоків зі спільним секретом. +- Підключення tailnet або LAN на тому самому хості все одно вважаються віддаленими для спарювання та + потребують схвалення. - WS-клієнти зазвичай включають ідентичність `device` під час `connect` (operator + - node). Єдині винятки operator без device — це явні довірені шляхи: - - `gateway.controlUi.allowInsecureAuth=true` для сумісності з insecure HTTP лише для localhost. - - успішна auth operator Control UI з `gateway.auth.mode: "trusted-proxy"`. + node). Єдині винятки для operator без пристрою — це явні довірені шляхи: + - `gateway.controlUi.allowInsecureAuth=true` для сумісності з небезпечним HTTP лише на localhost. + - успішна operator-автентифікація Control UI для `gateway.auth.mode: "trusted-proxy"`. - `gateway.controlUi.dangerouslyDisableDeviceAuth=true` (аварійний режим, серйозне зниження безпеки). - - прямі loopback-RPC backend `gateway-client`, автентифіковані спільним - токеном/паролем gateway. -- Усі підключення мають підписувати nonce `connect.challenge`, наданий сервером. + - backend-RPC `gateway-client` на прямому loopback, автентифіковані спільним + токеном/паролем Gateway. +- Усі підключення мають підписувати наданий сервером nonce `connect.challenge`. -### Діагностика міграції auth пристроїв +### Діагностика міграції автентифікації пристрою -Для застарілих клієнтів, які все ще використовують поведінку підписування до challenge, `connect` тепер повертає +Для застарілих клієнтів, які досі використовують поведінку підписування до виклику challenge, `connect` тепер повертає коди деталей `DEVICE_AUTH_*` у `error.details.code` зі стабільним `error.details.reason`. Поширені збої міграції: -| Повідомлення | details.code | details.reason | Значення | +| Повідомлення | details.code | details.reason | Значення | | --------------------------- | -------------------------------- | ------------------------ | -------------------------------------------------- | -| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Клієнт не передав `device.nonce` (або передав порожнє значення). | +| `device nonce required` | `DEVICE_AUTH_NONCE_REQUIRED` | `device-nonce-missing` | Клієнт пропустив `device.nonce` (або надіслав порожнє значення). | | `device nonce mismatch` | `DEVICE_AUTH_NONCE_MISMATCH` | `device-nonce-mismatch` | Клієнт підписав застарілим/неправильним nonce. | | `device signature invalid` | `DEVICE_AUTH_SIGNATURE_INVALID` | `device-signature` | Payload підпису не відповідає payload v2. | -| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Підписана позначка часу виходить за межі дозволеного зсуву. | -| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` не відповідає відбитку public key. | -| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Формат public key / канонізація не пройшли. | +| `device signature expired` | `DEVICE_AUTH_SIGNATURE_EXPIRED` | `device-signature-stale` | Підписана мітка часу поза дозволеним відхиленням. | +| `device identity mismatch` | `DEVICE_AUTH_DEVICE_ID_MISMATCH` | `device-id-mismatch` | `device.id` не відповідає відбитку відкритого ключа. | +| `device public key invalid` | `DEVICE_AUTH_PUBLIC_KEY_INVALID` | `device-public-key` | Не вдалося виконати форматування/канонізацію відкритого ключа. | Ціль міграції: - Завжди чекайте на `connect.challenge`. -- Підписуйте payload v2, який включає server nonce. +- Підписуйте payload v2, який містить серверний nonce. - Надсилайте той самий nonce у `connect.params.device.nonce`. -- Бажаний payload підпису — `v3`, який прив’язує `platform` і `deviceFamily` на додачу до полів device/client/role/scopes/token/nonce. -- Застарілі підписи `v2` і далі приймаються для сумісності, але прив’язка метаданих paired-device усе одно керує політикою команд під час повторного підключення. +- Бажаний payload підпису — `v3`, який прив’язує `platform` і `deviceFamily` + на додачу до полів device/client/role/scopes/token/nonce. +- Застарілі підписи `v2` і далі приймаються для сумісності, але pinning метаданих + спареного пристрою все одно керує політикою команд під час повторного підключення. ## TLS + pinning - TLS підтримується для WS-підключень. -- Клієнти за бажанням можуть закріпити відбиток сертифіката gateway (див. конфігурацію `gateway.tls` плюс `gateway.remote.tlsFingerprint` або CLI `--tls-fingerprint`). +- Клієнти можуть за бажанням закріплювати відбиток сертифіката Gateway (див. конфігурацію `gateway.tls` + плюс `gateway.remote.tlsFingerprint` або CLI `--tls-fingerprint`). ## Область -Цей протокол відкриває **повний API gateway** (status, channels, models, chat, -agent, sessions, nodes, approvals тощо). Точна поверхня визначається -схемами TypeBox у `src/gateway/protocol/schema.ts`. +Цей протокол відкриває **повний API Gateway** (status, channels, models, chat, +agent, sessions, nodes, approvals тощо). Точну поверхню визначають +схеми TypeBox у `src/gateway/protocol/schema.ts`. -## Пов’язані теми +## Пов’язане - [Протокол Bridge](/uk/gateway/bridge-protocol) - [Runbook Gateway](/uk/gateway)