diff --git a/docs/uk/gateway/configuration.md b/docs/uk/gateway/configuration.md index aedda38f3..4c1bd1c5a 100644 --- a/docs/uk/gateway/configuration.md +++ b/docs/uk/gateway/configuration.md @@ -1,33 +1,33 @@ --- read_when: - - Перше налаштування OpenClaw - - Пошук поширених шаблонів конфігурації - - Перехід до конкретних розділів конфігурації + - Налаштування OpenClaw уперше + - Шукаєте поширені шаблони конфігурації + - Перехід до певних розділів конфігурації summary: 'Огляд конфігурації: поширені завдання, швидке налаштування та посилання на повний довідник' title: Конфігурація x-i18n: - generated_at: "2026-04-22T22:25:45Z" + generated_at: "2026-04-22T22:37:31Z" model: gpt-5.4 provider: openai - source_hash: 2296617a25a339048cb1df7b895fec35e96b0740851c89add907fc49307e08d1 + source_hash: 966f6a6500fc2f649ee4612404092fd70305065544807c1d8bbc80aa840f9e97 source_path: gateway/configuration.md workflow: 15 --- # Конфігурація -OpenClaw читає необов’язковий конфігураційний файл **JSON5** з `~/.openclaw/openclaw.json`. +OpenClaw зчитує необов’язкову конфігурацію **JSON5** з `~/.openclaw/openclaw.json`. Якщо файл відсутній, OpenClaw використовує безпечні значення за замовчуванням. Типові причини додати конфігурацію: - Підключити канали та керувати тим, хто може надсилати повідомлення боту -- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (cron, hooks) -- Тонко налаштувати сеанси, медіа, мережу або UI +- Налаштувати моделі, інструменти, ізоляцію або автоматизацію (Cron, hooks) +- Тонко налаштувати сесії, медіа, мережу або UI Перегляньте [повний довідник](/uk/gateway/configuration-reference), щоб побачити всі доступні поля. -**Вперше налаштовуєте конфігурацію?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) з повними конфігураціями для копіювання. +**Вперше працюєте з конфігурацією?** Почніть з `openclaw onboard` для інтерактивного налаштування або перегляньте посібник [Приклади конфігурації](/uk/gateway/configuration-examples) із готовими конфігураціями для копіювання. ## Мінімальна конфігурація @@ -45,8 +45,8 @@ OpenClaw читає необов’язковий конфігураційний ```bash - openclaw onboard # full onboarding flow - openclaw configure # config wizard + openclaw onboard # повний процес початкового налаштування + openclaw configure # майстер конфігурації ``` @@ -58,11 +58,11 @@ OpenClaw читає необов’язковий конфігураційний Відкрийте [http://127.0.0.1:18789](http://127.0.0.1:18789) і використовуйте вкладку **Config**. - Control UI відображає форму на основі живої схеми конфігурації, включно з - метаданими документації полів `title` / `description`, а також схемами Plugin і каналів, коли - вони доступні, з редактором **Raw JSON** як запасним варіантом. Для - UI з деталізацією та інших інструментів gateway також надає `config.schema.lookup` для - отримання одного вузла схеми, обмеженого шляхом, і підсумків його безпосередніх дочірніх елементів. + Control UI відображає форму з живої схеми конфігурації, включно з метаданими документації полів + `title` / `description`, а також схемами plugin і каналів, коли вони + доступні, з редактором **Raw JSON** як запасним варіантом. Для деталізованих + UI та інших інструментів Gateway також надає `config.schema.lookup`, щоб + отримати один вузол схеми для вказаного шляху разом зі зведеннями про безпосередніх дочірніх елементів. Відредагуйте `~/.openclaw/openclaw.json` безпосередньо. Gateway відстежує файл і автоматично застосовує зміни (див. [гаряче перезавантаження](#config-hot-reload)). @@ -72,57 +72,60 @@ OpenClaw читає необов’язковий конфігураційний ## Сувора валідація -OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, неправильні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на рівні кореня — `$schema` (рядок), щоб редактори могли підключати метадані JSON Schema. +OpenClaw приймає лише конфігурації, які повністю відповідають схемі. Невідомі ключі, некоректні типи або недійсні значення призводять до того, що Gateway **відмовляється запускатися**. Єдиний виняток на рівні кореня — `$schema` (рядок), щоб редактори могли додавати метадані JSON Schema. Примітки щодо інструментів схеми: -- `openclaw config schema` виводить ту саму сім’ю JSON Schema, яку використовують Control UI - і валідація конфігурації. -- Розглядайте цей вивід схеми як канонічний машиночитний контракт для - `openclaw.json`; цей огляд і довідник із конфігурації його узагальнюють. +- `openclaw config schema` виводить те саме сімейство JSON Schema, яке використовується в Control UI + і для валідації конфігурації. +- Вважайте цей вивід схеми канонічним машиночитним контрактом для + `openclaw.json`; цей огляд і довідник з конфігурації його узагальнюють. - Значення полів `title` і `description` переносяться до виводу схеми для - редакторів та інструментів форм. -- Вкладені об’єкти, шаблони (`*`) та елементи масиву (`[]`) успадковують ті самі - метадані документації, якщо для відповідного поля існує документація. -- Гілки композицій `anyOf` / `oneOf` / `allOf` також успадковують ті самі + редакторів і інструментів форм. +- Вкладені об’єкти, записи wildcard (`*`) та елементи масиву (`[]`) успадковують ті самі + метадані документації там, де існує відповідна документація поля. +- Гілки композиції `anyOf` / `oneOf` / `allOf` також успадковують ті самі метадані документації, тож варіанти union/intersection зберігають ту саму довідку полів. - `config.schema.lookup` повертає один нормалізований шлях конфігурації з поверхневим вузлом схеми (`title`, `description`, `type`, `enum`, `const`, поширені обмеження - та подібні поля валідації), відповідними метаданими підказок UI і підсумками - безпосередніх дочірніх елементів для інструментів деталізації. -- Схеми Plugin/каналів часу виконання об’єднуються, коли gateway може завантажити + та подібні поля валідації), відповідні метадані UI-підказок і зведення про безпосередніх дочірніх елементів + для інструментів детального перегляду. +- Схеми plugin/каналів під час виконання об’єднуються, коли gateway може завантажити поточний реєстр маніфестів. -- `pnpm config:docs:check` виявляє розбіжності між артефактами базових конфігурацій, - орієнтованими на документацію, і поточною поверхнею схеми. +- `pnpm config:docs:check` виявляє розходження між базовими артефактами конфігурації для документації + і поточною поверхнею схеми. Коли валідація не проходить: - Gateway не запускається - Працюють лише діагностичні команди (`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`) -- Виконайте `openclaw doctor`, щоб побачити точні проблеми -- Виконайте `openclaw doctor --fix` (або `--yes`), щоб застосувати виправлення +- Запустіть `openclaw doctor`, щоб побачити точні проблеми +- Запустіть `openclaw doctor --fix` (або `--yes`), щоб застосувати виправлення -Gateway також зберігає довірену останню коректну копію після успішного запуску. Якщо -`openclaw.json` пізніше буде змінено поза OpenClaw і він перестане проходити валідацію, запуск -і гаряче перезавантаження збережуть пошкоджений файл як позначений часом знімок `.clobbered.*`, -відновлять останню коректну копію та запишуть помітне попередження з причиною відновлення. -Якщо перед інакше коректною JSON-конфігурацією випадково буде додано рядок статусу/журналу, +Gateway також зберігає довірену останню відому коректну копію після успішного запуску. Якщо +`openclaw.json` пізніше змінюється поза OpenClaw і більше не проходить валідацію, під час запуску +та гарячого перезавантаження зламаний файл зберігається як `.clobbered.*`-знімок із часовою позначкою, +відновлюється остання відома коректна копія, а в журнал записується помітне попередження з причиною відновлення. +Відновлення під час читання на старті також вважає критичними ознаками пошкодження різке зменшення розміру, +відсутні метадані конфігурації та відсутність `gateway.mode`, коли в останній відомій коректній +копії ці поля були. +Якщо перед інакше коректною конфігурацією JSON випадково додається рядок статусу/журналу, запуск gateway і `openclaw doctor --fix` можуть прибрати цей префікс, зберегти забруднений файл як `.clobbered.*` і продовжити роботу з відновленим JSON. -Наступний хід основного агента також отримує попередження про системну подію, яке повідомляє, що -конфігурацію було відновлено і її не можна бездумно перезаписувати. Оновлення останньої коректної версії -відбувається після валідованого запуску та після прийнятих гарячих перезавантажень, включно з -записами конфігурації, виконаними самим OpenClaw, якщо хеш збереженого файлу все ще збігається з прийнятим -записом. Оновлення пропускається, якщо кандидат містить замасковані заповнювачі секретів -на кшталт `***` або скорочені значення токенів. +Наступний хід головного агента також отримує попередження системної події про те, що +конфігурацію було відновлено і її не можна бездумно перезаписувати. Підвищення статусу останньої відомої коректної копії +оновлюється після валідованого запуску і після прийнятих гарячих перезавантажень, включно з +записами конфігурації, виконаними самим OpenClaw, якщо хеш збереженого файла все ще збігається з прийнятим +записом. Підвищення пропускається, коли кандидат містить замасковані заповнювачі секретів, +такі як `***` або скорочені значення токенів. ## Поширені завдання - Кожен канал має власний розділ конфігурації в `channels.`. Перегляньте окрему сторінку каналу для кроків налаштування: + Кожен канал має власний розділ конфігурації в `channels.`. Дивіться окрему сторінку каналу для кроків налаштування: - [WhatsApp](/uk/channels/whatsapp) — `channels.whatsapp` - [Telegram](/uk/channels/telegram) — `channels.telegram` @@ -135,7 +138,7 @@ JSON. - [iMessage](/uk/channels/imessage) — `channels.imessage` - [Mattermost](/uk/channels/mattermost) — `channels.mattermost` - Усі канали використовують однаковий шаблон політики особистих повідомлень: + Усі канали використовують однаковий шаблон політики DM: ```json5 { @@ -153,7 +156,7 @@ JSON. - Встановіть основну модель і необов’язкові резервні варіанти: + Задайте основну модель і необов’язкові резервні варіанти: ```json5 { @@ -173,30 +176,30 @@ JSON. ``` - `agents.defaults.models` визначає каталог моделей і слугує allowlist для `/model`. - - Використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи allowlist без видалення наявних моделей. Звичайні заміни, які призвели б до видалення записів, відхиляються, якщо не передати `--replace`. + - Використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додати записи до allowlist без видалення наявних моделей. Звичайні заміни, які видаляють записи, відхиляються, якщо не передати `--replace`. - Посилання на моделі використовують формат `provider/model` (наприклад, `anthropic/claude-opus-4-6`). - - `agents.defaults.imageMaxDimensionPx` керує зменшенням розміру зображень у транскриптах/інструментах (типове значення `1200`); менші значення зазвичай зменшують використання vision-token у сценаріях із великою кількістю скриншотів. - - Див. [Models CLI](/uk/concepts/models), щоб перемикати моделі в чаті, і [Model Failover](/uk/concepts/model-failover) щодо ротації автентифікації та поведінки резервного перемикання. - - Для користувацьких/self-hosted провайдерів див. [Custom providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику. + - `agents.defaults.imageMaxDimensionPx` керує зменшенням розміру зображень у transcript/tool (типове значення `1200`); менші значення зазвичай зменшують використання vision-токенів у сценаріях із великою кількістю скриншотів. + - Дивіться [Models CLI](/uk/concepts/models) для перемикання моделей у чаті та [Model Failover](/uk/concepts/model-failover) для ротації авторизації та поведінки резервних моделей. + - Для власних/self-hosted provider див. [Custom providers](/uk/gateway/configuration-reference#custom-providers-and-base-urls) у довіднику. - Доступ до особистих повідомлень керується окремо для кожного каналу через `dmPolicy`: + Доступ до DM керується окремо для кожного каналу через `dmPolicy`: - - `"pairing"` (типово): невідомі відправники отримують одноразовий код pairing для схвалення - - `"allowlist"`: лише відправники з `allowFrom` (або зі сховища парного allow) - - `"open"`: дозволити всі вхідні особисті повідомлення (потрібно `allowFrom: ["*"]`) - - `"disabled"`: ігнорувати всі особисті повідомлення + - `"pairing"` (типово): невідомі відправники отримують одноразовий код pairing для підтвердження + - `"allowlist"`: лише відправники з `allowFrom` (або зі сховища paired allow) + - `"open"`: дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) + - `"disabled"`: ігнорувати всі DM Для груп використовуйте `groupPolicy` + `groupAllowFrom` або allowlist, специфічні для каналу. - Див. [повний довідник](/uk/gateway/configuration-reference#dm-and-group-access) для деталей по кожному каналу. + Дивіться [повний довідник](/uk/gateway/configuration-reference#dm-and-group-access) для подробиць по кожному каналу. - - Групові повідомлення типово **вимагають згадки**. Налаштуйте шаблони для кожного агента: + + Для групових повідомлень типово **потрібна згадка**. Налаштуйте шаблони для кожного агента: ```json5 { @@ -218,15 +221,15 @@ JSON. } ``` - - **Metadata mentions**: нативні @-згадки (WhatsApp tap-to-mention, Telegram @bot тощо) - - **Text patterns**: безпечні шаблони regex у `mentionPatterns` - - Див. [повний довідник](/uk/gateway/configuration-reference#group-chat-mention-gating) для перевизначень на рівні каналів і режиму self-chat. + - **Згадки в метаданих**: нативні @-згадки (tap-to-mention у WhatsApp, @bot у Telegram тощо) + - **Текстові шаблони**: безпечні regex-шаблони в `mentionPatterns` + - Дивіться [повний довідник](/uk/gateway/configuration-reference#group-chat-mention-gating) для по-канальних перевизначень і режиму self-chat. - Використовуйте `agents.defaults.skills` для спільного базового набору, а потім перевизначайте конкретні - агенти через `agents.list[].skills`: + Використовуйте `agents.defaults.skills` для спільної базової конфігурації, а потім перевизначайте конкретних + агентів через `agents.list[].skills`: ```json5 { @@ -235,23 +238,23 @@ JSON. skills: ["github", "weather"], }, list: [ - { id: "writer" }, // inherits github, weather - { id: "docs", skills: ["docs-search"] }, // replaces defaults - { id: "locked-down", skills: [] }, // no skills + { id: "writer" }, // успадковує github, weather + { id: "docs", skills: ["docs-search"] }, // замінює значення за замовчуванням + { id: "locked-down", skills: [] }, // без Skills ], }, } ``` - - Не вказуйте `agents.defaults.skills`, щоб типово не обмежувати Skills. + - Не вказуйте `agents.defaults.skills`, якщо типово Skills не мають бути обмежені. - Не вказуйте `agents.list[].skills`, щоб успадкувати значення за замовчуванням. - - Установіть `agents.list[].skills: []`, щоб не було Skills. - - Див. [Skills](/uk/tools/skills), [конфігурація Skills](/uk/tools/skills-config) і - [Довідник із конфігурації](/uk/gateway/configuration-reference#agents-defaults-skills). + - Встановіть `agents.list[].skills: []`, щоб не дозволити жодних Skills. + - Дивіться [Skills](/uk/tools/skills), [конфігурацію Skills](/uk/tools/skills-config) і + [Довідник з конфігурації](/uk/gateway/configuration-reference#agents-defaults-skills). - + Керуйте тим, наскільки агресивно gateway перезапускає канали, які виглядають неактивними: ```json5 @@ -274,20 +277,20 @@ JSON. } ``` - - Встановіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски монітору стану. - - `channelStaleEventThresholdMinutes` має бути більшим або рівним інтервалу перевірки. - - Використовуйте `channels..healthMonitor.enabled` або `channels..accounts..healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу або облікового запису без вимкнення глобального моніторингу. - - Див. [Health Checks](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів. + - Встановіть `gateway.channelHealthCheckMinutes: 0`, щоб глобально вимкнути перезапуски через моніторинг стану. + - `channelStaleEventThresholdMinutes` має бути більшим або дорівнювати інтервалу перевірки. + - Використовуйте `channels..healthMonitor.enabled` або `channels..accounts..healthMonitor.enabled`, щоб вимкнути автоперезапуски для одного каналу або облікового запису без вимкнення глобального монітора. + - Дивіться [Health Checks](/uk/gateway/health) для операційного налагодження та [повний довідник](/uk/gateway/configuration-reference#gateway) для всіх полів. - - Сеанси керують безперервністю розмови та ізоляцією: + + Сесії керують безперервністю розмови та ізоляцією: ```json5 { session: { - dmScope: "per-channel-peer", // recommended for multi-user + dmScope: "per-channel-peer", // рекомендовано для багатьох користувачів threadBindings: { enabled: true, idleHours: 24, @@ -302,15 +305,15 @@ JSON. } ``` - - `dmScope`: `main` (спільний) | `per-peer` | `per-channel-peer` | `per-account-channel-peer` - - `threadBindings`: глобальні значення за замовчуванням для маршрутизації сеансів, прив’язаних до гілок (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`). - - Див. [Керування сеансами](/uk/concepts/session) щодо області видимості, зв’язків ідентичності та політики надсилання. - - Див. [повний довідник](/uk/gateway/configuration-reference#session) для всіх полів. + - `dmScope`: `main` (спільна) | `per-peer` | `per-channel-peer` | `per-account-channel-peer` + - `threadBindings`: глобальні значення за замовчуванням для маршрутизації сесій, прив’язаних до thread (Discord підтримує `/focus`, `/unfocus`, `/agents`, `/session idle` і `/session max-age`). + - Дивіться [Керування сесіями](/uk/concepts/session) для області дії, зв’язків ідентичностей і політики надсилання. + - Дивіться [повний довідник](/uk/gateway/configuration-reference#session) для всіх полів. - Запускайте сеанси агента в ізольованих середовищах sandbox: + Запускайте сесії агентів в ізольованих runtime ізолятора: ```json5 { @@ -327,14 +330,14 @@ JSON. Спочатку зберіть образ: `scripts/sandbox-setup.sh` - Див. [Sandboxing](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/configuration-reference#agentsdefaultssandbox) для всіх параметрів. + Дивіться [Sandboxing](/uk/gateway/sandboxing) для повного посібника та [повний довідник](/uk/gateway/configuration-reference#agentsdefaultssandbox) для всіх параметрів. - - Push через relay налаштовується в `openclaw.json`. + + Relay-backed push налаштовується в `openclaw.json`. - Установіть це в конфігурації gateway: + Укажіть це в конфігурації gateway: ```json5 { @@ -343,7 +346,7 @@ JSON. apns: { relay: { baseUrl: "https://relay.example.com", - // Необов’язково. Типово: 10000 + // Необов’язково. Типове значення: 10000 timeoutMs: 10000, }, }, @@ -352,7 +355,7 @@ JSON. } ``` - Еквівалент у CLI: + Еквівалент через CLI: ```bash openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com @@ -361,30 +364,30 @@ JSON. Що це робить: - Дозволяє gateway надсилати `push.test`, сигнали пробудження та сигнали повторного підключення через зовнішній relay. - - Використовує грант надсилання в межах реєстрації, який пересилає спарений застосунок iOS. Gateway не потрібен токен relay для всього розгортання. - - Прив’язує кожну реєстрацію через relay до ідентичності gateway, з якою був спарений застосунок iOS, тому інший gateway не може повторно використати збережену реєстрацію. - - Залишає локальні/ручні збірки iOS на прямому APNs. Надсилання через relay застосовується лише до офіційних розповсюджуваних збірок, які зареєструвалися через relay. - - Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації та надсилання потрапляв до того самого розгортання relay. + - Використовує grant на надсилання в межах реєстрації, який пересилає спарений застосунок iOS. Gateway не потрібен relay-токен для всього розгортання. + - Прив’язує кожну relay-backed реєстрацію до ідентичності gateway, з якою було спарено застосунок iOS, тож інший gateway не може повторно використати збережену реєстрацію. + - Залишає локальні/ручні збірки iOS на прямому APNs. Relay-backed надсилання застосовується лише до офіційно розповсюджених збірок, які зареєструвалися через relay. + - Має збігатися з базовим URL relay, вбудованим в офіційну/TestFlight збірку iOS, щоб трафік реєстрації й надсилання потрапляв до одного й того самого розгортання relay. - Наскрізний процес: + Повний потік end-to-end: 1. Установіть офіційну/TestFlight збірку iOS, скомпільовану з тим самим базовим URL relay. - 2. Налаштуйте `gateway.push.apns.relay.baseUrl` у gateway. - 3. Спарте застосунок iOS із gateway і дозвольте підключитися сеансам node та оператора. - 4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує корисне навантаження `push.apns.register` через relay до спареного gateway. - 5. Gateway зберігає дескриптор relay і грант надсилання, а потім використовує їх для `push.test`, сигналів пробудження та повторного підключення. + 2. Налаштуйте `gateway.push.apns.relay.baseUrl` на gateway. + 3. Спарте застосунок iOS із gateway і дочекайтеся підключення як node-, так і operator-сесій. + 4. Застосунок iOS отримує ідентичність gateway, реєструється в relay за допомогою App Attest і квитанції застосунку, а потім публікує relay-backed payload `push.apns.register` у спарений gateway. + 5. Gateway зберігає relay handle і send grant, а потім використовує їх для `push.test`, сигналів пробудження та сигналів повторного підключення. Операційні примітки: - - Якщо ви перемкнете застосунок iOS на інший gateway, повторно підключіть застосунок, щоб він міг опублікувати нову реєстрацію relay, прив’язану до цього gateway. - - Якщо ви випустите нову збірку iOS, яка вказує на інше розгортання relay, застосунок оновить кешовану реєстрацію relay замість повторного використання старого джерела relay. + - Якщо ви перемикаєте застосунок iOS на інший gateway, перепідключіть застосунок, щоб він міг опублікувати нову relay-реєстрацію, прив’язану до цього gateway. + - Якщо ви випускаєте нову збірку iOS, що вказує на інше розгортання relay, застосунок оновлює кешовану relay-реєстрацію замість повторного використання старого relay-origin. Примітка щодо сумісності: - `OPENCLAW_APNS_RELAY_BASE_URL` і `OPENCLAW_APNS_RELAY_TIMEOUT_MS` усе ще працюють як тимчасові перевизначення через env. - - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` залишається аварійним варіантом для розробки лише на loopback; не зберігайте URL relay з HTTP у конфігурації. + - `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` лишається запасним варіантом для розробки лише в local loopback; не зберігайте HTTP relay URL у конфігурації. - Див. [застосунок iOS](/uk/platforms/ios#relay-backed-push-for-official-builds) для наскрізного процесу та [Потік автентифікації й довіри](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay. + Дивіться [iOS App](/uk/platforms/ios#relay-backed-push-for-official-builds) для повного end-to-end потоку та [Authentication and trust flow](/uk/platforms/ios#authentication-and-trust-flow) для моделі безпеки relay. @@ -404,12 +407,12 @@ JSON. - `every`: рядок тривалості (`30m`, `2h`). Установіть `0m`, щоб вимкнути. - `target`: `last` | `none` | `` (наприклад, `discord`, `matrix`, `telegram` або `whatsapp`) - - `directPolicy`: `allow` (типово) або `block` для цілей Heartbeat у стилі особистих повідомлень - - Див. [Heartbeat](/uk/gateway/heartbeat) для повного посібника. + - `directPolicy`: `allow` (типово) або `block` для цілей Heartbeat у стилі DM + - Дивіться [Heartbeat](/uk/gateway/heartbeat) для повного посібника. - + ```json5 { cron: { @@ -424,14 +427,14 @@ JSON. } ``` - - `sessionRetention`: видаляти завершені ізольовані сеанси запуску з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути). - - `runLog`: очищати `cron/runs/.jsonl` за розміром і кількістю рядків, що зберігаються. - - Див. [Cron jobs](/uk/automation/cron-jobs) для огляду можливостей і прикладів CLI. + - `sessionRetention`: очищати завершені ізольовані сесії запуску з `sessions.json` (типово `24h`; установіть `false`, щоб вимкнути). + - `runLog`: очищати `cron/runs/.jsonl` за розміром і кількістю збережених рядків. + - Дивіться [Завдання Cron](/uk/automation/cron-jobs) для огляду функції та прикладів CLI. - Увімкніть HTTP-ендпоїнти Webhook у Gateway: + Увімкніть HTTP-ендпоїнти Webhook на Gateway: ```json5 { @@ -455,20 +458,20 @@ JSON. ``` Примітка щодо безпеки: - - Вважайте весь вміст корисного навантаження hook/Webhook недовіреним вводом. + - Увесь вміст payload hook/Webhook слід вважати недовіреним введенням. - Використовуйте окремий `hooks.token`; не використовуйте повторно спільний токен Gateway. - - Автентифікація hook працює лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в рядку запиту відхиляються. - - `hooks.path` не може бути `/`; залишайте вхід Webhook на окремому підшляху, наприклад `/hooks`. - - Залишайте прапорці обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте вузькоспеціалізоване налагодження. - - Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також установіть `hooks.allowedSessionKeyPrefixes`, щоб обмежити ключі сеансів, які може вибирати викликач. - - Для агентів, керованих через hook, надавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс sandboxing, де це можливо). + - Автентифікація hook працює лише через заголовки (`Authorization: Bearer ...` або `x-openclaw-token`); токени в query-рядку відхиляються. + - `hooks.path` не може бути `/`; використовуйте для входу Webhook окремий підшлях, наприклад `/hooks`. + - Тримайте прапорці обходу небезпечного вмісту вимкненими (`hooks.gmail.allowUnsafeExternalContent`, `hooks.mappings[].allowUnsafeExternalContent`), якщо не виконуєте вузькоспрямоване налагодження. + - Якщо ви вмикаєте `hooks.allowRequestSessionKey`, також задайте `hooks.allowedSessionKeyPrefixes`, щоб обмежити session key, які може вибрати викликач. + - Для агентів, керованих hook, надавайте перевагу сильним сучасним рівням моделей і суворій політиці інструментів (наприклад, лише обмін повідомленнями плюс ізоляція, де це можливо). - Див. [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів зіставлення та інтеграції Gmail. + Дивіться [повний довідник](/uk/gateway/configuration-reference#hooks) для всіх параметрів mappings та інтеграції Gmail. - Запускайте кілька ізольованих агентів з окремими робочими просторами та сеансами: + Запускайте кілька ізольованих агентів з окремими workspace і сесіями: ```json5 { @@ -485,12 +488,12 @@ JSON. } ``` - Див. [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/configuration-reference#multi-agent-routing) для правил прив’язки та профілів доступу для кожного агента. + Дивіться [Multi-Agent](/uk/concepts/multi-agent) і [повний довідник](/uk/gateway/configuration-reference#multi-agent-routing) для правил bindings і профілів доступу для кожного агента. - Використовуйте `$include`, щоб упорядковувати великі конфігурації: + Використовуйте `$include` для організації великих конфігурацій: ```json5 // ~/.openclaw/openclaw.json @@ -503,12 +506,12 @@ JSON. } ``` - - **Один файл**: замінює об’єкт, у якому міститься - - **Масив файлів**: об’єднується через deep-merge у вказаному порядку (пізніші мають пріоритет) - - **Сусідні ключі**: об’єднуються після include (перевизначають включені значення) - - **Вкладені include**: підтримуються до 10 рівнів вкладеності - - **Відносні шляхи**: обчислюються відносно файла, який включає - - **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу та циклічних include + - **Один файл**: замінює об’єкт, що його містить + - **Масив файлів**: глибоко об’єднується за порядком (пізніші значення мають пріоритет) + - **Сусідні ключі**: об’єднуються після includes (перевизначають включені значення) + - **Вкладені includes**: підтримуються до 10 рівнів вкладеності + - **Відносні шляхи**: обчислюються відносно файлу, який виконує включення + - **Обробка помилок**: зрозумілі помилки для відсутніх файлів, помилок парсингу та циклічних includes @@ -517,27 +520,27 @@ JSON. Gateway відстежує `~/.openclaw/openclaw.json` і автоматично застосовує зміни — для більшості налаштувань ручний перезапуск не потрібен. -Прямі зміни файлу вважаються недовіреними, доки не пройдуть валідацію. Спостерігач чекає, -поки завершаться тимчасові записи/перейменування редактора, читає остаточний файл і відхиляє -недійсні зовнішні зміни, відновлюючи останню коректну конфігурацію. Записи конфігурації, -виконані самим OpenClaw, використовують ту саму схему перевірки перед записом; руйнівні перезаписи, -наприклад видалення `gateway.mode` або зменшення файлу більш ніж удвічі, відхиляються +Прямі редагування файлу вважаються недовіреними, доки не пройдуть валідацію. Спостерігач чекає, +поки завершаться тимчасові записи/перейменування редактора, читає підсумковий файл і відхиляє +некоректні зовнішні редагування, відновлюючи останню відому коректну конфігурацію. Власні записи конфігурації OpenClaw +використовують той самий контроль схеми перед записом; руйнівні пошкодження, такі +як видалення `gateway.mode` або зменшення файлу більш ніж удвічі, відхиляються і зберігаються як `.rejected.*` для перевірки. Якщо ви бачите `Config auto-restored from last-known-good` або -`config reload restored last-known-good config` у журналах, перегляньте відповідний -файл `.clobbered.*` поруч із `openclaw.json`, виправте відхилене корисне навантаження, а потім виконайте -`openclaw config validate`. Див. [Усунення проблем Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config) +`config reload restored last-known-good config` у журналах, перевірте відповідний +файл `.clobbered.*` поруч із `openclaw.json`, виправте відхилений payload, а потім запустіть +`openclaw config validate`. Дивіться [усунення проблем Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config) для контрольного списку відновлення. ### Режими перезавантаження -| Режим | Поведінка | -| ---------------------- | ---------------------------------------------------------------------------------------- | -| **`hybrid`** (типово) | Миттєво гаряче застосовує безпечні зміни. Автоматично перезапускається для критичних. | -| **`hot`** | Гаряче застосовує лише безпечні зміни. Логує попередження, коли потрібен перезапуск — ви обробляєте це самі. | -| **`restart`** | Перезапускає Gateway при будь-якій зміні конфігурації, безпечній чи ні. | -| **`off`** | Вимикає відстеження файлу. Зміни набувають чинності при наступному ручному перезапуску. | +| Режим | Поведінка | +| ---------------------- | -------------------------------------------------------------------------------------- | +| **`hybrid`** (типово) | Миттєво гаряче застосовує безпечні зміни. Автоматично перезапускається для критичних. | +| **`hot`** | Гаряче застосовує лише безпечні зміни. Записує попередження, коли потрібен перезапуск — ви виконуєте його самі. | +| **`restart`** | Перезапускає Gateway за будь-якої зміни конфігурації, безпечної чи ні. | +| **`off`** | Вимикає відстеження файлу. Зміни набудуть чинності під час наступного ручного перезапуску. | ```json5 { @@ -553,40 +556,40 @@ Gateway відстежує `~/.openclaw/openclaw.json` і автоматично | Категорія | Поля | Потрібен перезапуск? | | ------------------ | ----------------------------------------------------------------- | -------------------- | -| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані канали та канали Plugin | Ні | -| Агент і моделі | `agent`, `agents`, `models`, `routing` | Ні | +| Канали | `channels.*`, `web` (WhatsApp) — усі вбудовані канали й канали plugin | Ні | +| Агенти й моделі | `agent`, `agents`, `models`, `routing` | Ні | | Автоматизація | `hooks`, `cron`, `agent.heartbeat` | Ні | -| Сеанси й повідомлення | `session`, `messages` | Ні | +| Сесії та повідомлення | `session`, `messages` | Ні | | Інструменти й медіа | `tools`, `browser`, `skills`, `audio`, `talk` | Ні | | UI та інше | `ui`, `logging`, `identity`, `bindings` | Ні | | Сервер Gateway | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **Так** | | Інфраструктура | `discovery`, `canvasHost`, `plugins` | **Так** | -`gateway.reload` і `gateway.remote` — винятки: їхня зміна **не** спричиняє перезапуск. +`gateway.reload` і `gateway.remote` — винятки; їх зміна **не** спричиняє перезапуск. -## Config RPC (програмні оновлення) +## RPC конфігурації (програмні оновлення) -RPC control plane для запису (`config.apply`, `config.patch`, `update.run`) мають обмеження швидкості: **3 запити за 60 секунд** на `deviceId+clientIp`. При спрацюванні обмеження RPC повертає `UNAVAILABLE` з `retryAfterMs`. +RPC керуючої площини для запису (`config.apply`, `config.patch`, `update.run`) мають обмеження швидкості — **3 запити за 60 секунд** на `deviceId+clientIp`. При спрацюванні обмеження RPC повертає `UNAVAILABLE` з `retryAfterMs`. -Безпечний/типовий процес: +Безпечний/типовий потік: -- `config.schema.lookup`: перевірити одне піддерево конфігурації, обмежене шляхом, з поверхневим - вузлом схеми, відповідними метаданими підказок і підсумками безпосередніх дочірніх елементів +- `config.schema.lookup`: переглянути одне піддерево конфігурації для вказаного шляху з поверхневим + вузлом схеми, відповідними метаданими підказок і зведеннями про безпосередніх дочірніх елементів - `config.get`: отримати поточний знімок + хеш -- `config.patch`: бажаний шлях часткового оновлення +- `config.patch`: бажаний шлях для часткового оновлення - `config.apply`: лише повна заміна конфігурації -- `update.run`: явне самооновлення + перезапуск +- `update.run`: явне self-update + перезапуск -Коли ви не замінюєте всю конфігурацію, надавайте перевагу `config.schema.lookup`, +Якщо ви не замінюєте всю конфігурацію, надавайте перевагу `config.schema.lookup`, а потім `config.patch`. - Перевіряє + записує повну конфігурацію та перезапускає Gateway за один крок. + Виконує валідацію + записує повну конфігурацію та перезапускає Gateway одним кроком. `config.apply` замінює **всю конфігурацію**. Використовуйте `config.patch` для часткових оновлень або `openclaw config set` для окремих ключів. @@ -594,16 +597,16 @@ RPC control plane для запису (`config.apply`, `config.patch`, `update.r Параметри: - - `raw` (string) — корисне навантаження JSON5 для всієї конфігурації - - `baseHash` (optional) — хеш конфігурації з `config.get` (обов’язковий, якщо конфігурація існує) - - `sessionKey` (optional) — ключ сеансу для ping пробудження після перезапуску - - `note` (optional) — примітка для sentinel перезапуску - - `restartDelayMs` (optional) — затримка перед перезапуском (типово 2000) + - `raw` (string) — payload JSON5 для всієї конфігурації + - `baseHash` (необов’язково) — хеш конфігурації з `config.get` (обов’язковий, якщо конфігурація існує) + - `sessionKey` (необов’язково) — session key для wake-up ping після перезапуску + - `note` (необов’язково) — примітка для sentinel перезапуску + - `restartDelayMs` (необов’язково) — затримка перед перезапуском (типово 2000) - Запити на перезапуск об’єднуються, якщо один уже очікує/виконується, і між циклами перезапуску діє 30-секундний період охолодження. + Запити на перезапуск об’єднуються, якщо один уже очікує або виконується, і між циклами перезапуску діє 30-секундний період охолодження. ```bash - openclaw gateway call config.get --params '{}' # capture payload.hash + openclaw gateway call config.get --params '{}' # зафіксувати payload.hash openclaw gateway call config.apply --params '{ "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }", "baseHash": "", @@ -622,11 +625,11 @@ RPC control plane для запису (`config.apply`, `config.patch`, `update.r Параметри: - - `raw` (string) — JSON5 лише з ключами, які потрібно змінити - - `baseHash` (required) — хеш конфігурації з `config.get` - - `sessionKey`, `note`, `restartDelayMs` — такі самі, як у `config.apply` + - `raw` (string) — JSON5 лише з тими ключами, які потрібно змінити + - `baseHash` (обов’язково) — хеш конфігурації з `config.get` + - `sessionKey`, `note`, `restartDelayMs` — так само, як у `config.apply` - Поведінка перезапуску збігається з `config.apply`: об’єднання відкладених перезапусків і 30-секундний період охолодження між циклами перезапуску. + Поведінка перезапуску відповідає `config.apply`: об’єднання очікуваних перезапусків плюс 30-секундний період охолодження між циклами перезапуску. ```bash openclaw gateway call config.patch --params '{ @@ -640,12 +643,12 @@ RPC control plane для запису (`config.apply`, `config.patch`, `update.r ## Змінні середовища -OpenClaw читає змінні середовища з батьківського процесу, а також з: +OpenClaw зчитує env vars із батьківського процесу, а також з: - `.env` у поточному робочому каталозі (якщо є) -- `~/.openclaw/.env` (глобальний резервний варіант) +- `~/.openclaw/.env` (глобальний запасний варіант) -Жоден із цих файлів не перевизначає вже наявні змінні середовища. Ви також можете встановлювати вбудовані змінні середовища в конфігурації: +Жоден із цих файлів не перевизначає вже наявні env vars. Ви також можете задавати вбудовані env vars у конфігурації: ```json5 { @@ -656,8 +659,8 @@ OpenClaw читає змінні середовища з батьківсько } ``` - - Якщо це ввімкнено й очікувані ключі не встановлені, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі: + + Якщо його ввімкнено і очікувані ключі не встановлені, OpenClaw запускає вашу login shell і імпортує лише відсутні ключі: ```json5 { @@ -671,7 +674,7 @@ OpenClaw читає змінні середовища з батьківсько - Посилайтеся на змінні середовища в будь-якому рядковому значенні конфігурації за допомогою `${VAR_NAME}`: + Посилайтеся на env vars у будь-якому рядковому значенні конфігурації за допомогою `${VAR_NAME}`: ```json5 { @@ -682,7 +685,7 @@ OpenClaw читає змінні середовища з батьківсько Правила: -- Збігаються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*` +- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*` - Відсутні/порожні змінні спричиняють помилку під час завантаження - Екрануйте через `$${VAR}` для буквального виводу - Працює всередині файлів `$include` @@ -723,16 +726,16 @@ OpenClaw читає змінні середовища з батьківсько } ``` -Докладніше про SecretRef (включно з `secrets.providers` для `env`/`file`/`exec`) див. у [Керування секретами](/uk/gateway/secrets). -Підтримувані шляхи облікових даних перелічено в [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface). +Подробиці про SecretRef (включно з `secrets.providers` для `env`/`file`/`exec`) наведені в [Керуванні секретами](/uk/gateway/secrets). +Підтримувані шляхи облікових даних наведені в [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface). -Див. [Середовище](/uk/help/environment) для повного порядку пріоритетів і джерел. +Дивіться [Середовище](/uk/help/environment) для повного порядку пріоритетів і джерел. ## Повний довідник -Повний довідник по полях див. у **[Довідник із конфігурації](/uk/gateway/configuration-reference)**. +Повний довідник по всіх полях див. у **[Довіднику з конфігурації](/uk/gateway/configuration-reference)**. --- -_Пов’язане: [Приклади конфігурації](/uk/gateway/configuration-examples) · [Довідник із конфігурації](/uk/gateway/configuration-reference) · [Doctor](/uk/gateway/doctor)_ +_Пов’язане: [Приклади конфігурації](/uk/gateway/configuration-examples) · [Довідник з конфігурації](/uk/gateway/configuration-reference) · [Doctor](/uk/gateway/doctor)_ diff --git a/docs/uk/gateway/troubleshooting.md b/docs/uk/gateway/troubleshooting.md index 42754668a..b8fc1f282 100644 --- a/docs/uk/gateway/troubleshooting.md +++ b/docs/uk/gateway/troubleshooting.md @@ -2,25 +2,25 @@ read_when: - Центр усунення несправностей направив вас сюди для глибшої діагностики - Вам потрібні стабільні розділи посібника на основі симптомів із точними командами -summary: Детальний посібник з усунення несправностей для Gateway, каналів, автоматизації, Node і браузера +summary: Глибокий посібник із пошуку та усунення несправностей для Gateway, каналів, автоматизації, Node і браузера title: Усунення несправностей x-i18n: - generated_at: "2026-04-22T20:50:00Z" + generated_at: "2026-04-22T22:37:31Z" model: gpt-5.4 provider: openai - source_hash: 6df9cfcce30542401fc3d815781e226d45bb5462580722fa5353e404eef28ee6 + source_hash: 426d90f3f9b693d49694d0bbd6dab2434c726ddd34cd47a753c91096e50ca6d8 source_path: gateway/troubleshooting.md workflow: 15 --- # Усунення несправностей Gateway -Ця сторінка — детальний посібник. -Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спочатку хочете швидкий сценарій діагностики. +Ця сторінка — поглиблений посібник. +Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спочатку хочете пройти швидкий потік первинної діагностики. -## Послідовність команд +## Сходинки команд -Спочатку виконайте ці команди в такому порядку: +Спочатку виконайте це в такому порядку: ```bash openclaw status @@ -34,10 +34,10 @@ openclaw channels status --probe - `openclaw gateway status` показує `Runtime: running`, `Connectivity probe: ok` і рядок `Capability: ...`. - `openclaw doctor` не повідомляє про блокувальні проблеми конфігурації/сервісу. -- `openclaw channels status --probe` показує живий стан транспорту для кожного облікового запису та, - де це підтримується, результати probe/audit, такі як `works` або `audit ok`. +- `openclaw channels status --probe` показує живий стан транспорту для кожного облікового запису і, + де це підтримується, результати probe/audit, наприклад `works` або `audit ok`. -## Anthropic 429: для довгого контексту потрібне додаткове використання +## Додаткове використання Anthropic 429 потрібне для довгого контексту Використовуйте це, коли журнали/помилки містять: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`. @@ -48,31 +48,31 @@ openclaw models status openclaw config get agents.defaults.models ``` -Зверніть увагу на таке: +Шукайте таке: -- Для вибраної моделі Anthropic Opus/Sonnet встановлено `params.context1m: true`. -- Поточні облікові дані Anthropic не дають права на використання довгого контексту. -- Запити не вдаються лише для довгих сесій/запусків моделі, яким потрібен beta-шлях 1M. +- Вибрана модель Anthropic Opus/Sonnet має `params.context1m: true`. +- Поточні облікові дані Anthropic не мають права на використання довгого контексту. +- Запити збиваються лише на довгих сесіях/запусках моделей, яким потрібен шлях beta 1M. Варіанти виправлення: 1. Вимкніть `context1m` для цієї моделі, щоб повернутися до звичайного вікна контексту. -2. Використайте облікові дані Anthropic, які мають право на запити з довгим контекстом, або перейдіть на Anthropic API key. +2. Використовуйте облікові дані Anthropic, які мають право на запити з довгим контекстом, або перейдіть на ключ Anthropic API. 3. Налаштуйте резервні моделі, щоб запуски продовжувалися, коли запити Anthropic із довгим контекстом відхиляються. -Пов’язане: +Пов’язано: - [/providers/anthropic](/uk/providers/anthropic) - [/reference/token-use](/uk/reference/token-use) - [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/uk/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) -## Локальний OpenAI-compatible backend проходить прямі probe, але запуски агента не вдаються +## Локальний сумісний із OpenAI бекенд проходить прямі probe, але запуски агента збиваються Використовуйте це, коли: - `curl ... /v1/models` працює -- малі прямі виклики `/v1/chat/completions` працюють -- запуски моделей OpenClaw не вдаються лише під час звичайних ходів агента +- маленькі прямі виклики `/v1/chat/completions` працюють +- запуски моделі OpenClaw збиваються лише на звичайних ходах агента ```bash curl http://127.0.0.1:1234/v1/models @@ -83,35 +83,38 @@ openclaw infer model run --model --prompt "hi" --json openclaw logs --follow ``` -Зверніть увагу на таке: +Шукайте таке: -- прямі малі виклики успішні, але запуски OpenClaw не вдаються лише на більших prompt -- backend повертає помилки про те, що `messages[].content` очікує рядок -- backend аварійно завершується лише за більшої кількості токенів у prompt або з повними prompt середовища виконання агента +- прямі маленькі виклики успішні, але запуски OpenClaw збиваються лише на більших prompts +- помилки бекенда про те, що `messages[].content` очікує рядок +- збої бекенда, які з’являються лише за більшої кількості prompt-токенів або повних + prompts середовища виконання агента Поширені ознаки: -- `messages[...].content: invalid type: sequence, expected a string` → backend +- `messages[...].content: invalid type: sequence, expected a string` → бекенд відхиляє структуровані частини вмісту Chat Completions. Виправлення: установіть `models.providers..models[].compat.requiresStringContent: true`. -- прямі малі запити успішні, але запуски агентів OpenClaw не вдаються через аварії backend/моделі - (наприклад, Gemma у деяких збірках `inferrs`) → транспорт OpenClaw, - імовірно, уже налаштований правильно; проблема в тому, що backend не справляється з більшою формою prompt середовища агента. -- збої зменшуються після вимкнення інструментів, але не зникають → схеми інструментів - були частиною навантаження, але решта проблеми все ще пов’язана з upstream-обмеженнями моделі/сервера або помилкою backend. +- прямі маленькі запити успішні, але запуски агента OpenClaw збиваються через збої + бекенда/моделі (наприклад, Gemma на деяких збірках `inferrs`) → транспорт OpenClaw + імовірно вже налаштований правильно; бекенд збивається через більшу форму prompt + середовища виконання агента. +- збоїв стає менше після вимкнення інструментів, але вони не зникають → схеми інструментів + були частиною навантаження, але решта проблеми все ще є обмеженням моделі/сервера + вгору за стеком або помилкою бекенда. Варіанти виправлення: -1. Установіть `compat.requiresStringContent: true` для backend Chat Completions, які підтримують лише рядковий вміст. -2. Установіть `compat.supportsTools: false` для моделей/backend, які не можуть надійно обробляти - поверхню схем інструментів OpenClaw. -3. Де можливо, зменште навантаження від prompt: менший bootstrap робочого простору, коротша - історія сесії, легша локальна модель або backend із кращою підтримкою довгого контексту. -4. Якщо прямі малі запити й далі успішні, а ходи агента OpenClaw все одно аварійно завершуються - всередині backend, вважайте це обмеженням upstream-сервера/моделі й подайте туди - відтворюваний приклад із прийнятною формою payload. +1. Установіть `compat.requiresStringContent: true` для бекендів Chat Completions, що підтримують лише рядки. +2. Установіть `compat.supportsTools: false` для моделей/бекендів, які не можуть + надійно працювати з поверхнею схем інструментів OpenClaw. +3. Де можливо, зменште навантаження на prompt: менший bootstrap робочого простору, коротша + історія сесії, легша локальна модель або бекенд із кращою підтримкою довгого контексту. +4. Якщо маленькі прямі запити й далі проходять, а ходи агента OpenClaw усе одно збиваються + всередині бекенда, розглядайте це як обмеження сервера/моделі вгору за стеком і подайте + туди відтворюваний приклад із прийнятою формою payload. -Пов’язане: +Пов’язано: - [/gateway/local-models](/uk/gateway/local-models) - [/gateway/configuration](/uk/gateway/configuration) @@ -119,7 +122,7 @@ openclaw logs --follow ## Немає відповідей -Якщо канали працюють, але відповідей немає, перевірте маршрутизацію та політику, перш ніж щось перепідключати. +Якщо канали працюють, але відповідей немає, перевірте маршрутизацію та політики, перш ніж щось перепідключати. ```bash openclaw status @@ -129,25 +132,25 @@ openclaw config get channels openclaw logs --follow ``` -Зверніть увагу на таке: +Шукайте таке: -- Для відправників у DM pairing очікує підтвердження. -- Обмеження згадування для груп (`requireMention`, `mentionPatterns`). +- Pairing очікує підтвердження для відправників у DM. +- Обмеження згадкою в групі (`requireMention`, `mentionPatterns`). - Невідповідності allowlist каналу/групи. Поширені ознаки: -- `drop guild message (mention required` → повідомлення групи ігнорується, доки немає згадування. -- `pairing request` → відправнику потрібне схвалення. +- `drop guild message (mention required` → повідомлення групи ігнорується, доки немає згадки. +- `pairing request` → відправник потребує схвалення. - `blocked` / `allowlist` → відправника/канал було відфільтровано політикою. -Пов’язане: +Пов’язано: - [/channels/troubleshooting](/uk/channels/troubleshooting) - [/channels/pairing](/uk/channels/pairing) - [/channels/groups](/uk/channels/groups) -## Підключення UI dashboard/control +## Підключення dashboard/control UI Коли dashboard/control UI не підключається, перевірте URL, режим автентифікації та припущення щодо безпечного контексту. @@ -159,50 +162,51 @@ openclaw doctor openclaw gateway status --json ``` -Зверніть увагу на таке: +Шукайте таке: -- Правильний probe URL і URL dashboard. -- Невідповідність режиму автентифікації/токена між клієнтом і gateway. +- Правильний URL probe і URL dashboard. +- Невідповідність режиму автентифікації/токена між клієнтом і Gateway. - Використання HTTP там, де потрібна ідентичність пристрою. Поширені ознаки: - `device identity required` → небезпечний контекст або відсутня автентифікація пристрою. -- `origin not allowed` → `Origin` браузера не входить до `gateway.controlUi.allowedOrigins` - (або ви підключаєтеся з browser origin не на loopback без явного +- `origin not allowed` → `Origin` браузера відсутній у `gateway.controlUi.allowedOrigins` + (або ви підключаєтеся з origin браузера не на loopback без явного allowlist). - `device nonce required` / `device nonce mismatch` → клієнт не завершує - автентифікацію пристрою на основі challenge (`connect.challenge` + `device.nonce`). + challenge-based потік автентифікації пристрою (`connect.challenge` + `device.nonce`). - `device signature invalid` / `device signature expired` → клієнт підписав неправильний - payload (або використав застарілу часову позначку) для поточного handshake. + payload (або використав застарілу часову мітку) для поточного handshake. - `AUTH_TOKEN_MISMATCH` з `canRetryWithDeviceToken=true` → клієнт може виконати одну довірену повторну спробу з кешованим токеном пристрою. -- Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений із прив’язаним +- Ця повторна спроба з кешованим токеном повторно використовує кешований набір scopes, збережений із парним токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` зберігають - запитаний ними набір scope. -- Поза цим шляхом повторної спроби пріоритет автентифікації connect такий: явний спільний - token/password спочатку, потім явний `deviceToken`, потім збережений токен пристрою, - потім bootstrap token. -- У шляху async Tailscale Serve Control UI невдалі спроби для одного й того самого - `{scope, ip}` серіалізуються до того, як limiter зафіксує збій. Тому дві хибні + свій запитаний набір scopes. +- Поза цим шляхом повторної спроби пріоритет автентифікації підключення такий: явний спільний + токен/пароль спочатку, далі явний `deviceToken`, далі збережений токен пристрою, + далі bootstrap-токен. +- На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого + `{scope, ip}` серіалізуються до того, як обмежувач зафіксує невдачу. Тому дві хибні одночасні повторні спроби від того самого клієнта можуть показати `retry later` у другій спробі замість двох звичайних невідповідностей. -- `too many failed authentication attempts (retry later)` від loopback-клієнта з browser origin - → повторні збої з того самого нормалізованого `Origin` тимчасово блокуються; інший localhost origin використовує окремий bucket. -- повторюване `unauthorized` після цієї повторної спроби → розсинхронізація shared token/device token; оновіть конфігурацію токена та повторно схваліть/перевипустіть токен пристрою за потреби. -- `gateway connect failed:` → неправильна ціль host/port/url. +- `too many failed authentication attempts (retry later)` від loopback-клієнта з browser-origin + → повторні невдачі від того самого нормалізованого `Origin` тимчасово блокуються; + інший localhost origin використовує окремий bucket. +- повторюваний `unauthorized` після цієї повторної спроби → розсинхронізація shared token/device token; оновіть конфігурацію токена та за потреби повторно схваліть/ротуйте токен пристрою. +- `gateway connect failed:` → неправильний хост/порт/цільовий url. -### Коротка карта кодів деталей автентифікації +### Швидка карта кодів деталей автентифікації -Використовуйте `error.details.code` з невдалої відповіді `connect`, щоб вибрати наступну дію: +Використовуйте `error.details.code` з невдалого `connect` response, щоб вибрати наступну дію: | Код деталей | Значення | Рекомендована дія | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | Клієнт не надіслав обов’язковий спільний token. | Вставте/установіть token у клієнті й повторіть спробу. Для шляхів dashboard: `openclaw config get gateway.auth.token`, потім вставте його в налаштуваннях Control UI. | -| `AUTH_TOKEN_MISMATCH` | Спільний token не збігся з токеном автентифікації gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені scope; виклики з явними `deviceToken` / `scopes` зберігають запитані scope. Якщо збій повторюється, виконайте [контрольний список відновлення розсинхронізації токенів](/cli/devices#token-drift-recovery-checklist). | -| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен для конкретного пристрою застарів або відкликаний. | Перевипустіть/повторно схваліть токен пристрою за допомогою [CLI пристроїв](/cli/devices), а потім підключіться знову. | -| `PAIRING_REQUIRED` | Ідентичність пристрою потребує схвалення. Перевірте `error.details.reason`: `not-paired`, `scope-upgrade`, `role-upgrade` або `metadata-upgrade`, і використовуйте `requestId` / `remediationHint`, якщо вони є. | Схваліть очікуваний запит: `openclaw devices list`, потім `openclaw devices approve `. Підвищення scope/ролей використовує той самий процес після перевірки запитаного доступу. | +| `AUTH_TOKEN_MISSING` | Клієнт не надіслав обов’язковий спільний токен. | Вставте/установіть токен у клієнті та повторіть спробу. Для шляхів dashboard: `openclaw config get gateway.auth.token`, потім вставте його в налаштування Control UI. | +| `AUTH_TOKEN_MISMATCH` | Спільний токен не збігся з токеном автентифікації Gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені scopes; виклики з явним `deviceToken` / `scopes` зберігають запитані scopes. Якщо все одно не працює, виконайте [контрольний список відновлення після розсинхронізації токенів](/cli/devices#token-drift-recovery-checklist). | +| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен для пристрою застарів або був відкликаний. | Ротуйте/повторно схваліть токен пристрою за допомогою [CLI devices](/cli/devices), потім підключіться знову. | +| `PAIRING_REQUIRED` | Ідентичність пристрою потребує схвалення. Перевірте `error.details.reason` для `not-paired`, `scope-upgrade`, `role-upgrade` або `metadata-upgrade` і використовуйте `requestId` / `remediationHint`, якщо вони є. | Схваліть очікуваний запит: `openclaw devices list`, потім `openclaw devices approve `. Оновлення scope/role використовують той самий потік після того, як ви переглянете запитаний доступ. | -Перевірка міграції device auth v2: +Перевірка міграції автентифікації пристроїв v2: ```bash openclaw --version @@ -210,20 +214,20 @@ openclaw doctor openclaw gateway status ``` -Якщо журнали показують помилки nonce/signature, оновіть клієнт, який підключається, і переконайтеся, що він: +Якщо в журналах видно помилки nonce/signature, оновіть клієнт, що підключається, і перевірте, що він: -1. чекає на `connect.challenge` +1. очікує на `connect.challenge` 2. підписує payload, прив’язаний до challenge -3. надсилає `connect.params.device.nonce` з тим самим nonce challenge +3. надсилає `connect.params.device.nonce` з тим самим challenge nonce -Якщо `openclaw devices rotate` / `revoke` / `remove` неочікувано заборонено: +Якщо `openclaw devices rotate` / `revoke` / `remove` несподівано заборонено: -- сесії з токеном прив’язаного пристрою можуть керувати лише **власним** пристроєм, якщо +- сесії токенів парних пристроїв можуть керувати лише **власним** пристроєм, якщо виклик також не має `operator.admin` -- `openclaw devices rotate --scope ...` може запитувати лише ті operator scope, +- `openclaw devices rotate --scope ...` може запитувати лише ті operator scopes, які сесія виклику вже має -Пов’язане: +Пов’язано: - [/web/control-ui](/web/control-ui) - [/gateway/configuration](/uk/gateway/configuration) (режими автентифікації gateway) @@ -243,28 +247,28 @@ openclaw doctor openclaw gateway status --deep # also scan system-level services ``` -Зверніть увагу на таке: +Шукайте таке: - `Runtime: stopped` із підказками щодо завершення. -- Невідповідність конфігурації сервісу (`Config (cli)` проти `Config (service)`). -- Конфлікти порту/слухача. +- Невідповідність конфігурації сервісу (`Config (cli)` vs `Config (service)`). +- Конфлікти портів/слухачів. - Додаткові встановлення launchd/systemd/schtasks, коли використовується `--deep`. - Підказки очищення `Other gateway-like services detected (best effort)`. Поширені ознаки: -- `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → локальний режим gateway не ввімкнено, або файл конфігурації було пошкоджено і він втратив `gateway.mode`. Виправлення: установіть `gateway.mode="local"` у своїй конфігурації або повторно виконайте `openclaw onboard --mode local` / `openclaw setup`, щоб знову проставити очікувану конфігурацію локального режиму. Якщо ви запускаєте OpenClaw через Podman, типовий шлях до конфігурації: `~/.openclaw/openclaw.json`. -- `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху автентифікації gateway (token/password або trusted-proxy, якщо налаштовано). +- `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → локальний режим Gateway не ввімкнений, або файл конфігурації був пошкоджений і втратив `gateway.mode`. Виправлення: установіть `gateway.mode="local"` у своїй конфігурації або повторно запустіть `openclaw onboard --mode local` / `openclaw setup`, щоб знову проставити очікувану конфігурацію локального режиму. Якщо ви запускаєте OpenClaw через Podman, стандартний шлях до конфігурації — `~/.openclaw/openclaw.json`. +- `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху автентифікації gateway (токен/пароль або trusted-proxy, якщо налаштовано). - `another gateway instance is already listening` / `EADDRINUSE` → конфлікт порту. -- `Other gateway-like services detected (best effort)` → існують застарілі або паралельні launchd/systemd/schtasks unit. У більшості конфігурацій на одну машину має бути один gateway; якщо вам справді потрібно більше одного, ізолюйте порти + config/state/workspace. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host). +- `Other gateway-like services detected (best effort)` → існують застарілі або паралельні юніти launchd/systemd/schtasks. У більшості конфігурацій слід тримати один Gateway на машину; якщо вам справді потрібно більше одного, ізолюйте порти + конфігурацію/стан/робочий простір. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host). -Пов’язане: +Пов’язано: - [/gateway/background-process](/uk/gateway/background-process) - [/gateway/configuration](/uk/gateway/configuration) - [/gateway/doctor](/uk/gateway/doctor) -## Gateway відновив останню відому справну конфігурацію +## Gateway відновив останню відому коректну конфігурацію Використовуйте це, коли Gateway запускається, але в журналах сказано, що він відновив `openclaw.json`. @@ -275,22 +279,22 @@ openclaw config validate openclaw doctor ``` -Зверніть увагу на таке: +Шукайте таке: - `Config auto-restored from last-known-good` - `gateway: invalid config was restored from last-known-good backup` - `config reload restored last-known-good config after invalid-config` -- Файл `openclaw.json.clobbered.*` з часовою позначкою поруч з активною конфігурацією +- Файл `openclaw.json.clobbered.*` із часовою міткою поруч з активною конфігурацією - Системну подію головного агента, що починається з `Config recovery warning` Що сталося: - Відхилена конфігурація не пройшла валідацію під час запуску або гарячого перезавантаження. - OpenClaw зберіг відхилений payload як `.clobbered.*`. -- Активну конфігурацію було відновлено з останньої валідованої останньої відомої справної копії. -- Наступний хід головного агента отримує попередження не переписувати сліпо відхилену конфігурацію. +- Активну конфігурацію було відновлено з останньої перевіреної останньої відомої коректної копії. +- Наступний хід головного агента отримує попередження не переписувати відхилену конфігурацію навмання. -Перевірка й виправлення: +Перевірка та виправлення: ```bash CONFIG="$(openclaw config file)" @@ -302,10 +306,11 @@ openclaw doctor Поширені ознаки: -- Існує `.clobbered.*` → було відновлено зовнішнє пряме редагування або зчитування під час запуску. -- Існує `.rejected.*` → запис конфігурації, виконаний OpenClaw, не пройшов перевірки схеми або цілісності перед commit. +- існує `.clobbered.*` → було відновлено зовнішнє пряме редагування або читання під час запуску. +- існує `.rejected.*` → запис конфігурації, який виконував сам OpenClaw, не пройшов перевірки схеми або clobber перед підтвердженням. - `Config write rejected:` → запис намагався прибрати обов’язкову структуру, різко зменшити файл або зберегти невалідну конфігурацію. -- `Config last-known-good promotion skipped` → кандидат містив замасковані placeholder секретів, наприклад `***`. +- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` або `size-drop-vs-last-good:*` → під час запуску поточний файл було визнано пошкодженим, бо порівняно з останньою відомою коректною резервною копією він втратив поля або розмір. +- `Config last-known-good promotion skipped` → кандидат містив редаговані заповнювачі секретів, наприклад `***`. Варіанти виправлення: @@ -314,16 +319,16 @@ openclaw doctor 3. Перед перезапуском виконайте `openclaw config validate`. 4. Якщо редагуєте вручну, зберігайте повну конфігурацію JSON5, а не лише частковий об’єкт, який хотіли змінити. -Пов’язане: +Пов’язано: - [/gateway/configuration#strict-validation](/uk/gateway/configuration#strict-validation) - [/gateway/configuration#config-hot-reload](/uk/gateway/configuration#config-hot-reload) - [/cli/config](/cli/config) - [/gateway/doctor](/uk/gateway/doctor) -## Попередження probe Gateway +## Попередження Gateway probe -Використовуйте це, коли `openclaw gateway probe` до чогось доходить, але все одно виводить блок попередження. +Використовуйте це, коли `openclaw gateway probe` до чогось достукується, але все одно виводить блок попередження. ```bash openclaw gateway probe @@ -331,20 +336,20 @@ openclaw gateway probe --json openclaw gateway probe --ssh user@gateway-host ``` -Зверніть увагу на таке: +Шукайте таке: - `warnings[].code` і `primaryTargetId` у виводі JSON. -- Чи стосується попередження SSH fallback, кількох gateway, відсутніх scope або нерозв’язаних auth ref. +- Чи стосується попередження SSH fallback, кількох Gateway, відсутніх scopes або нерозв’язаних auth ref. Поширені ознаки: - `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не вдалося, але команда все одно спробувала прямі налаштовані/loopback-цілі. -- `multiple reachable gateways detected` → відповіло більше однієї цілі. Зазвичай це означає навмисну конфігурацію з кількома gateway або застарілі/дубльовані listener. -- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але деталізований RPC обмежено scope; прив’яжіть ідентичність пристрою або використайте облікові дані з `operator.read`. -- `Capability: pairing-pending` або `gateway closed (1008): pairing required` → gateway відповів, але цьому клієнту все ще потрібне pairing/схвалення перед звичайним доступом оператора. -- нерозв’язане попередження SecretRef для `gateway.auth.*` / `gateway.remote.*` → auth-матеріал був недоступний у цьому шляху команди для цілі, що завершилась невдачею. +- `multiple reachable gateways detected` → відповіло більше однієї цілі. Зазвичай це означає навмисну конфігурацію з кількома Gateway або застарілі/дубльовані слухачі. +- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але детальний RPC обмежений scopes; виконайте pairing ідентичності пристрою або використайте облікові дані з `operator.read`. +- `Capability: pairing-pending` або `gateway closed (1008): pairing required` → Gateway відповів, але цьому клієнту все ще потрібне pairing/схвалення перед звичайним operator-доступом. +- нерозв’язане попередження SecretRef для `gateway.auth.*` / `gateway.remote.*` → у цьому шляху виконання команди для цільового вузла, що не пройшов перевірку, матеріал автентифікації був недоступний. -Пов’язане: +Пов’язано: - [/cli/gateway](/cli/gateway) - [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host) @@ -352,7 +357,7 @@ openclaw gateway probe --ssh user@gateway-host ## Канал підключений, але повідомлення не проходять -Якщо стан каналу — connected, але потік повідомлень не працює, зосередьтеся на політиці, дозволах і правилах доставки, специфічних для каналу. +Якщо стан каналу — підключено, але потік повідомлень мертвий, зосередьтеся на політиках, дозволах і правилах доставки, специфічних для каналу. ```bash openclaw channels status --probe @@ -362,19 +367,19 @@ openclaw logs --follow openclaw config get channels ``` -Зверніть увагу на таке: +Шукайте таке: -- Політику DM (`pairing`, `allowlist`, `open`, `disabled`). -- Allowlist групи та вимоги до згадувань. +- Політика DM (`pairing`, `allowlist`, `open`, `disabled`). +- Allowlist групи та вимоги щодо згадки. - Відсутні дозволи/scopes API каналу. Поширені ознаки: -- `mention required` → повідомлення ігнорується політикою згадування в групі. +- `mention required` → повідомлення ігнорується політикою згадок у групі. - `pairing` / сліди очікування схвалення → відправника не схвалено. -- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема з автентифікацією/дозволами каналу. +- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема автентифікації/дозволів каналу. -Пов’язане: +Пов’язано: - [/channels/troubleshooting](/uk/channels/troubleshooting) - [/channels/whatsapp](/uk/channels/whatsapp) @@ -383,7 +388,7 @@ openclaw config get channels ## Доставка Cron і Heartbeat -Якщо Cron або Heartbeat не запустилися чи не доставили результат, спочатку перевірте стан scheduler, а потім ціль доставки. +Якщо Cron або Heartbeat не запустилися чи не доставилися, спочатку перевірте стан планувальника, а потім ціль доставки. ```bash openclaw cron status @@ -393,31 +398,31 @@ openclaw system heartbeat last openclaw logs --follow ``` -Зверніть увагу на таке: +Шукайте таке: -- Cron увімкнено, і присутнє наступне пробудження. -- Статус історії виконання завдань (`ok`, `skipped`, `error`). +- Cron увімкнено та є наступне пробудження. +- Стан історії виконання завдань (`ok`, `skipped`, `error`). - Причини пропуску Heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`). Поширені ознаки: - `cron: scheduler disabled; jobs will not run automatically` → Cron вимкнено. -- `cron: timer tick failed` → збій тіку scheduler; перевірте помилки файлів/журналів/середовища виконання. +- `cron: timer tick failed` → збій тіку планувальника; перевірте помилки файлів/журналів/середовища виконання. - `heartbeat skipped` з `reason=quiet-hours` → поза вікном активних годин. -- `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожні рядки / markdown-заголовки, тому OpenClaw пропускає виклик моделі. -- `heartbeat skipped` з `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але жодне із завдань не має виконуватися під час цього тіку. -- `heartbeat: unknown accountId` → недійсний account id для цілі доставки Heartbeat. -- `heartbeat skipped` з `reason=dm-blocked` → ціль Heartbeat була визначена як пункт призначення стилю DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для конкретного агента) встановлено в `block`. +- `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожні рядки / заголовки markdown, тому OpenClaw пропускає виклик моделі. +- `heartbeat skipped` з `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але жодне із завдань не має бути виконане на цьому тіку. +- `heartbeat: unknown accountId` → невалідний account id для цілі доставки Heartbeat. +- `heartbeat skipped` з `reason=dm-blocked` → ціль Heartbeat визначилася як призначення в стилі DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для конкретного агента) установлено в `block`. -Пов’язане: +Пов’язано: - [/automation/cron-jobs#troubleshooting](/uk/automation/cron-jobs#troubleshooting) - [/automation/cron-jobs](/uk/automation/cron-jobs) - [/gateway/heartbeat](/uk/gateway/heartbeat) -## Збій інструмента прив’язаного Node +## Збій інструмента парного Node -Якщо Node прив’язано, але інструменти не працюють, ізолюйте стан foreground, дозволів і схвалення. +Якщо Node виконала pairing, але інструменти не працюють, ізолюйте стан foreground, дозволів і схвалення. ```bash openclaw nodes status @@ -427,11 +432,11 @@ openclaw logs --follow openclaw status ``` -Зверніть увагу на таке: +Шукайте таке: - Node онлайн з очікуваними можливостями. - Надані дозволи ОС для камери/мікрофона/геолокації/екрана. -- Стан схвалення exec і allowlist. +- Стан схвалень exec і allowlist. Поширені ознаки: @@ -440,15 +445,15 @@ openclaw status - `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec. - `SYSTEM_RUN_DENIED: allowlist miss` → команду заблоковано allowlist. -Пов’язане: +Пов’язано: - [/nodes/troubleshooting](/uk/nodes/troubleshooting) - [/nodes/index](/uk/nodes/index) - [/tools/exec-approvals](/uk/tools/exec-approvals) -## Збій browser tool +## Збій інструмента браузера -Використовуйте це, коли дії browser tool не вдаються, хоча сам gateway справний. +Використовуйте це, коли дії інструмента браузера не працюють, хоча сам Gateway справний. ```bash openclaw browser status @@ -458,42 +463,42 @@ openclaw logs --follow openclaw doctor ``` -Зверніть увагу на таке: +Шукайте таке: - Чи встановлено `plugins.allow` і чи містить він `browser`. -- Валідний шлях до виконуваного файла браузера. +- Коректний шлях до виконуваного файлу браузера. - Досяжність профілю CDP. - Наявність локального Chrome для профілів `existing-session` / `user`. Поширені ознаки: -- `unknown command "browser"` або `unknown command 'browser'` → вбудований browser Plugin виключено через `plugins.allow`. -- browser tool відсутній / недоступний, хоча `browser.enabled=true` → `plugins.allow` виключає `browser`, тому Plugin ніколи не завантажився. +- `unknown command "browser"` або `unknown command 'browser'` → вбудований Plugin браузера виключено через `plugins.allow`. +- інструмент браузера відсутній / недоступний, хоча `browser.enabled=true` → `plugins.allow` виключає `browser`, тому Plugin ніколи не завантажувався. - `Failed to start Chrome CDP on port` → не вдалося запустити процес браузера. - `browser.executablePath not found` → налаштований шлях недійсний. -- `browser.cdpUrl must be http(s) or ws(s)` → налаштований CDP URL використовує непідтримувану схему, таку як `file:` або `ftp:`. -- `browser.cdpUrl has invalid port` → налаштований CDP URL має помилковий або неприпустимий порт. -- `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session ще не зміг під’єднатися до вибраного каталогу даних браузера. Відкрийте сторінку inspect браузера, увімкніть remote debugging, тримайте браузер відкритим, схваліть перший запит на підключення, а потім повторіть спробу. Якщо стан входу не потрібен, віддайте перевагу керованому профілю `openclaw`. -- `No Chrome tabs found for profile="user"` → профіль підключення Chrome MCP не має відкритих локальних вкладок Chrome. -- `Remote CDP for profile "" is not reachable` → налаштований віддалений endpoint CDP недосяжний із хоста gateway. -- `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль лише з attach не має досяжної цілі, або HTTP endpoint відповів, але CDP WebSocket все одно не вдалося відкрити. -- `Playwright is not available in this gateway build; '' is unsupported.` → у поточній інсталяції gateway бракує вбудованої залежності середовища виконання `playwright-core` для browser Plugin; виконайте `openclaw doctor --fix`, потім перезапустіть gateway. Знімки ARIA та базові знімки сторінок усе ще можуть працювати, але навігація, AI snapshots, знімки елементів за CSS-селекторами та експорт PDF залишаться недоступними. +- `browser.cdpUrl must be http(s) or ws(s)` → налаштований URL CDP використовує непідтримувану схему, наприклад `file:` або `ftp:`. +- `browser.cdpUrl has invalid port` → налаштований URL CDP має хибний або неприпустимий порт. +- `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session поки не зміг приєднатися до вибраного каталогу даних браузера. Відкрийте сторінку inspect браузера, увімкніть віддалене налагодження, тримайте браузер відкритим, схваліть перший запит на приєднання, а потім повторіть спробу. Якщо авторизований стан не потрібен, надавайте перевагу керованому профілю `openclaw`. +- `No Chrome tabs found for profile="user"` → профіль приєднання Chrome MCP не має відкритих локальних вкладок Chrome. +- `Remote CDP for profile "" is not reachable` → налаштована віддалена кінцева точка CDP недосяжна з хоста Gateway. +- `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль лише для приєднання не має досяжної цілі, або HTTP-ендпоінт відповів, але CDP WebSocket усе одно не вдалося відкрити. +- `Playwright is not available in this gateway build; '' is unsupported.` → у поточному встановленні Gateway бракує залежності середовища виконання `playwright-core` вбудованого browser Plugin; виконайте `openclaw doctor --fix`, потім перезапустіть Gateway. Знімки ARIA та базові знімки сторінки все ще можуть працювати, але навігація, AI-знімки, знімки елементів за CSS-селекторами та експорт PDF залишатимуться недоступними. - `fullPage is not supported for element screenshots` → запит на знімок екрана поєднав `--full-page` з `--ref` або `--element`. -- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → виклики знімків екрана Chrome MCP / `existing-session` повинні використовувати захоплення сторінки або `--ref` зі snapshot, а не CSS `--element`. -- `existing-session file uploads do not support element selectors; use ref/inputRef.` → хуки завантаження файлів у Chrome MCP потребують snapshot ref, а не CSS-селекторів. -- `existing-session file uploads currently support one file at a time.` → для профілів Chrome MCP надсилайте по одному файлу за виклик. +- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → виклики знімків екрана Chrome MCP / `existing-session` мають використовувати захоплення сторінки або `--ref` зі snapshot, а не CSS `--element`. +- `existing-session file uploads do not support element selectors; use ref/inputRef.` → хуки завантаження файлів Chrome MCP потребують snapshot ref, а не CSS-селекторів. +- `existing-session file uploads currently support one file at a time.` → для профілів Chrome MCP надсилайте одне завантаження за виклик. - `existing-session dialog handling does not support timeoutMs.` → хуки діалогів у профілях Chrome MCP не підтримують перевизначення timeout. - `response body is not supported for existing-session profiles yet.` → `responsebody` поки що потребує керованого браузера або сирого профілю CDP. -- застарілі перевизначення viewport / dark-mode / locale / offline у профілях attach-only або remote CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну керовану сесію й звільнити стан емуляції Playwright/CDP без перезапуску всього gateway. +- застарілі перевизначення viewport / dark-mode / locale / offline у профілях attach-only або remote CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну сесію керування та звільнити стан емуляції Playwright/CDP без перезапуску всього Gateway. -Пов’язане: +Пов’язано: - [/tools/browser-linux-troubleshooting](/uk/tools/browser-linux-troubleshooting) - [/tools/browser](/uk/tools/browser) -## Якщо ви оновилися і щось раптово зламалося +## Якщо ви оновилися і щось раптом зламалося -Більшість збоїв після оновлення — це дрейф конфігурації або жорсткіші типові значення, які тепер примусово застосовуються. +Більшість збоїв після оновлення — це дрейф конфігурації або застосування суворіших типових значень. ### 1) Змінилася поведінка автентифікації та перевизначення URL @@ -506,15 +511,15 @@ openclaw config get gateway.auth.mode Що перевірити: -- Якщо `gateway.mode=remote`, виклики CLI можуть бути спрямовані на віддалений Gateway, тоді як ваш локальний сервіс справний. +- Якщо `gateway.mode=remote`, виклики CLI можуть бути націлені на віддалений вузол, тоді як ваш локальний сервіс справний. - Явні виклики `--url` не повертаються до збережених облікових даних. Поширені ознаки: -- `gateway connect failed:` → неправильна ціль URL. -- `unauthorized` → endpoint досяжний, але автентифікація неправильна. +- `gateway connect failed:` → неправильний цільовий URL. +- `unauthorized` → ендпоінт досяжний, але автентифікація неправильна. -### 2) Обмеження прив’язки та автентифікації стали жорсткішими +### 2) Запобіжники для bind і автентифікації стали суворішими ```bash openclaw config get gateway.bind @@ -526,13 +531,13 @@ openclaw logs --follow Що перевірити: -- Прив’язки не до loopback (`lan`, `tailnet`, `custom`) потребують дійсного шляху автентифікації Gateway: спільна автентифікація token/password або правильно налаштоване розгортання `trusted-proxy` не на loopback. +- Прив’язки не до loopback (`lan`, `tailnet`, `custom`) потребують дійсного шляху автентифікації gateway: shared token/password auth або правильно налаштоване розгортання `trusted-proxy` не на loopback. - Старі ключі на кшталт `gateway.token` не замінюють `gateway.auth.token`. Поширені ознаки: - `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху автентифікації gateway. -- `Connectivity probe: failed`, тоді як runtime запущено → gateway живий, але недоступний із поточною auth/url. +- `Connectivity probe: failed` при запущеному runtime → Gateway живий, але недоступний з поточними auth/url. ### 3) Змінився стан pairing та ідентичності пристрою @@ -550,17 +555,17 @@ openclaw doctor Поширені ознаки: -- `device identity required` → автентифікацію пристрою не виконано. +- `device identity required` → не виконано автентифікацію пристрою. - `pairing required` → відправника/пристрій потрібно схвалити. -Якщо після перевірок конфігурація сервісу та runtime все ще не збігаються, перевстановіть метадані сервісу з того самого каталогу profile/state: +Якщо після перевірок конфігурація сервісу та runtime все ще не збігаються, перевстановіть метадані сервісу з того самого каталогу профілю/стану: ```bash openclaw gateway install --force openclaw gateway restart ``` -Пов’язане: +Пов’язано: - [/gateway/pairing](/uk/gateway/pairing) - [/gateway/authentication](/uk/gateway/authentication)