---
read_when:
    - Центр усунення несправностей спрямував вас сюди для поглибленої діагностики
    - Вам потрібні стабільні розділи оперативної інструкції на основі симптомів із точними командами
sidebarTitle: Troubleshooting
summary: Поглиблений посібник з усунення несправностей Gateway, каналів, автоматизації, вузлів і браузера
title: Усунення несправностей
x-i18n:
    generated_at: "2026-07-16T18:06:07Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: f53064a0d42e601ec1a1904fc9d0e8ebb9def7a2fb9d2579c7f10ca675b8f7fd
    source_path: gateway/troubleshooting.md
    workflow: 16
---

Це докладний посібник з експлуатації. Спочатку перейдіть до [/help/troubleshooting](/uk/help/troubleshooting), щоб виконати швидку первинну діагностику.

## Послідовність команд

Виконуйте в такому порядку:

```bash
openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor
openclaw channels status --probe
```

Ознаки справної роботи:

- `openclaw gateway status` показує `Runtime: running`, `Connectivity probe: ok` і рядок `Capability: ...`.
- `openclaw doctor` не повідомляє про проблеми конфігурації чи служби, що блокують роботу.
- `openclaw channels status --probe` показує актуальний стан транспорту для кожного облікового запису, а там, де це підтримується, — `works` або `audit ok`.

## Після оновлення

Використовуйте, якщо оновлення завершилося, але Gateway не працює, канали порожні або виклики моделей завершуються помилками 401.

```bash
openclaw status --all
openclaw update status --json
openclaw gateway status --deep
openclaw doctor --fix
openclaw gateway restart
```

Перевірте:

- `Update restart` у `openclaw status` / `openclaw status --all`. Для незавершених або невдалих передавань указано наступну команду, яку потрібно виконати.
- `plugin load failed: dependency tree corrupted; run openclaw doctor --fix` у розділі каналів: конфігурація каналу досі існує, але реєстрація плагіна завершилася помилкою до завантаження каналу.
- Помилки 401 від провайдера після повторної автентифікації: `openclaw doctor --fix` перевіряє застарілі OAuth-копії автентифікаційних даних окремих агентів і видаляє старі копії, щоб усі агенти використовували поточний спільний профіль.

## Розділені інсталяції та захист від новішої конфігурації

Використовуйте, якщо служба Gateway несподівано зупиняється після оновлення або журнали показують, що один бінарний файл `openclaw` старіший за версію, яка востаннє записала `openclaw.json`.

OpenClaw позначає записи конфігурації за допомогою `meta.lastTouchedVersion`. Команди лише для читання можуть перевіряти конфігурацію, записану новішою версією OpenClaw, але старіший бінарний файл відмовляється виконувати зміни процесів і служб. Блокуються такі дії: запуск, зупинення, перезапуск і видалення служби Gateway, примусове перевстановлення служби, запуск Gateway у режимі служби та очищення порту `gateway --force`.

```bash
which openclaw
openclaw --version
openclaw gateway status --deep
openclaw config get meta.lastTouchedVersion
```

<Steps>
  <Step title="Виправте PATH">
    Виправте `PATH`, щоб `openclaw` указував на новішу інсталяцію, а потім повторіть дію.
  </Step>
  <Step title="Перевстановіть службу Gateway">
    Перевстановіть потрібну службу Gateway із новішої інсталяції:

    ```bash
    openclaw gateway install --force
    openclaw gateway restart
    ```

  </Step>
  <Step title="Видаліть застарілі обгортки">
    Видаліть застарілі записи системного пакета або старої обгортки, які досі вказують на старий бінарний файл `openclaw`.
  </Step>
</Steps>

<Warning>
Лише для навмисного повернення до попередньої версії або аварійного відновлення встановіть `OPENCLAW_ALLOW_OLDER_BINARY_DESTRUCTIVE_ACTIONS=1` для однієї команди. Для звичайної роботи залишайте цю змінну невстановленою.
</Warning>

## Невідповідність протоколу після повернення до попередньої версії

Використовуйте, якщо після зниження версії або повернення до попередньої версії в журналах постійно з’являється `protocol mismatch`. Працює старіший Gateway, але новіший локальний клієнтський процес досі повторно підключається з діапазоном протоколу, який старіший Gateway не підтримує.

```bash
openclaw --version
which -a openclaw
openclaw gateway status --deep
openclaw doctor --deep
openclaw logs --follow
```

Перевірте:

- `protocol mismatch ... client=... v<version> min=<n> max=<n> expected=<n>` у журналах Gateway.
- `Established clients:` у `openclaw gateway status --deep` або `Gateway clients` у `openclaw doctor --deep`: активні TCP-клієнти, підключені до порту Gateway, із PID та командними рядками, якщо це дозволяє ОС.
- Клієнтський процес, командний рядок якого вказує на новішу інсталяцію або обгортку OpenClaw, від якої було виконано повернення.

Виправлення:

1. Зупиніть або перезапустіть застарілий клієнтський процес OpenClaw, показаний у `gateway status --deep`.
2. Перезапустіть застосунки або обгортки, у які вбудовано OpenClaw: локальні панелі керування, редактори, допоміжні процеси серверів застосунків або довготривалі оболонки `openclaw logs --follow`.
3. Повторно виконайте `openclaw gateway status --deep` або `openclaw doctor --deep` і переконайтеся, що PID застарілого клієнта зник.

Не змушуйте старіший Gateway приймати новіший несумісний протокол. Підвищення версії протоколу захищає контракт обміну даними; відновлення після повернення версії потребує очищення процесів і версій.

## Символьне посилання Skills пропущено через вихід за межі шляху

Використовуйте, якщо журнали містять:

```text
Пропуск шляху Skills, що виходить за межі налаштованого кореня: ... reason=symlink-escape
```

Кожен корінь Skills є межею ізоляції. Символьне посилання в `~/.agents/skills`, `<workspace>/.agents/skills`, `<workspace>/skills` або `~/.openclaw/skills` пропускається, якщо його фактична ціль розташована за межами цього кореня, якщо тільки ціль не позначено як довірену явно.

Перевірте посилання:

```bash
ls -l ~/.agents/skills/<name>
realpath ~/.agents/skills/<name>
openclaw config get skills.load
```

Якщо ціль вибрано навмисно, налаштуйте як безпосередній корінь Skills, так і дозволену ціль символьного посилання:

```json5
{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}
```

Потім почніть новий сеанс або зачекайте, поки засіб спостереження за Skills оновить дані. Перезапустіть Gateway, якщо запущений процес передує зміні конфігурації.

Не використовуйте широкі цілі, як-от `~`, `/` або всю синхронізовану папку проєкту. Обмежте `allowSymlinkTargets` фактичним коренем Skills, який містить довірені каталоги `SKILL.md`.

Якщо застосування Skill Workshop також має записувати дані через ці довірені символьні посилання на шляхи Skills робочого простору, увімкніть `skills.workshop.allowSymlinkTargetWrites`. Залишайте цей параметр вимкненим для спільних коренів Skills, доступних лише для читання.

Пов’язані матеріали:

- [Конфігурація Skills](/uk/tools/skills-config#symlinked-skill-roots)
- [Приклади конфігурації](/uk/gateway/configuration-examples#symlinked-sibling-skill-repo)

## Для довгого контексту Anthropic 429 потрібне додаткове використання

Використовуйте, якщо журнали або помилки містять: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`.

```bash
openclaw logs --follow
openclaw models status
openclaw config get agents.defaults.models
```

Перевірте:

- Вибрана модель Anthropic є моделлю Claude 4.x із загальнодоступною підтримкою контексту 1M (Opus 4.6/4.7/4.8, Sonnet 4.6) або конфігурація моделі досі містить застарілий параметр `params.context1m: true`.
- Поточні облікові дані Anthropic не мають права на використання довгого контексту.
- Запити завершуються помилкою лише під час довгих сеансів або запусків моделей, яким потрібен контекст 1M.

Варіанти виправлення:

<Steps>
  <Step title="Використовуйте стандартне контекстне вікно">
    Перейдіть на модель зі стандартним контекстним вікном або видаліть застарілий параметр `context1m` зі старої
    конфігурації моделі, яка не має загальнодоступної підтримки контексту 1M.
  </Step>
  <Step title="Використовуйте придатні облікові дані">
    Використовуйте облікові дані Anthropic, придатні для запитів із довгим контекстом, або перейдіть на ключ API Anthropic.
  </Step>
  <Step title="Налаштуйте резервні моделі">
    Налаштуйте резервні моделі, щоб виконання продовжувалося, коли запити Anthropic із довгим контекстом відхиляються.
  </Step>
</Steps>

Пов’язані матеріали:

- [Anthropic](/uk/providers/anthropic)
- [Використання токенів і витрати](/uk/reference/token-use)
- [Чому я бачу помилку HTTP 429 від Anthropic?](/uk/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic)

## Відповіді 403 із блокуванням від вищого рівня

Використовуйте, якщо зовнішній провайдер LLM повертає загальну помилку `403`, наприклад `Your request was blocked`.

Не вважайте, що це завжди проблема конфігурації OpenClaw. Відповідь може надходити від зовнішнього рівня безпеки, як-от CDN, WAF, правило керування ботами або зворотний проксі перед кінцевою точкою, сумісною з OpenAI.

```bash
openclaw status
openclaw gateway status
openclaw logs --follow
```

Перевірте:

- Кілька моделей одного провайдера завершуються однаковою помилкою.
- Замість звичайної помилки API провайдера повертається HTML або загальний текст системи безпеки.
- Події безпеки на боці провайдера за той самий час запиту.
- Мінімальний безпосередній пробний запит `curl` успішний, тоді як звичайні запити у форматі SDK завершуються помилкою.

Якщо докази вказують на блокування WAF/CDN, спочатку виправте фільтрацію на боці провайдера. Надавайте перевагу вузько обмеженому правилу дозволу або пропуску для шляху API, який використовує OpenClaw, і не вимикайте захист для всього сайту.

<Warning>
Успішний мінімальний запит `curl` не гарантує, що справжні запити у стилі SDK пройдуть через той самий зовнішній рівень безпеки.
</Warning>

Пов’язані матеріали:

- [Кінцеві точки, сумісні з OpenAI](/uk/gateway/configuration-reference#openai-compatible-endpoints)
- [Конфігурація провайдера](/uk/providers)
- [Журнали](/uk/logging)

## Локальний сервер, сумісний з OpenAI, проходить прямі перевірки, але запуски агентів завершуються помилкою

Використовуйте, якщо:

- `curl ... /v1/models` працює.
- Малі прямі виклики `/v1/chat/completions` працюють.
- Запуски моделей OpenClaw завершуються помилкою лише під час звичайних кроків агента.

```bash
curl http://127.0.0.1:1234/v1/models
curl http://127.0.0.1:1234/v1/chat/completions \
  -H 'content-type: application/json' \
  -d '{"model":"<id>","messages":[{"role":"user","content":"hi"}],"stream":false}'
openclaw infer model run --model <provider/model> --prompt "hi" --json
openclaw logs --follow
```

Перевірте:

- Малі прямі виклики успішні, але запуски OpenClaw завершуються помилкою лише для більших запитів.
- Помилки `model_not_found` або 404, хоча прямий запит `/v1/chat/completions` працює з тим самим ідентифікатором моделі без префікса.
- Помилки сервера про те, що `messages[].content` очікує рядок.
- Періодичні попередження `incomplete turn detected ... stopReason=stop payloads=0` з локальним сервером, сумісним з OpenAI.
- Збої сервера, які виникають лише за більшої кількості токенів запиту або з повними запитами середовища виконання агента.

<AccordionGroup>
  <Accordion title="Поширені ознаки">
    - `model_not_found` з локальним сервером у стилі MLX/vLLM: переконайтеся, що `baseUrl` містить `/v1`, `api` має значення `"openai-completions"` для серверів `/v1/chat/completions`, а `models.providers.<provider>.models[].id` є локальним ідентифікатором провайдера без префікса. Вибирайте його з префіксом провайдера один раз, наприклад `mlx/mlx-community/Qwen3-30B-A3B-6bit`; запис у каталозі залишайте як `mlx-community/Qwen3-30B-A3B-6bit`.
    - `messages[...].content: invalid type: sequence, expected a string`: сервер відхиляє структуровані частини вмісту Chat Completions. Виправлення: установіть `models.providers.<provider>.models[].compat.requiresStringContent: true`.
    - `validation.keys` або дозволені ключі повідомлень, як-от `["role","content"]`: сервер відхиляє метадані повторного відтворення у стилі OpenAI в повідомленнях Chat Completions. Виправлення: установіть `models.providers.<provider>.models[].compat.strictMessageKeys: true`.
    - `incomplete turn detected ... stopReason=stop payloads=0`: сервер виконав запит Chat Completions, але не повернув видимого користувачеві тексту асистента для цього кроку. OpenClaw один раз повторює безпечні для повторного відтворення порожні кроки, сумісні з OpenAI; постійні помилки зазвичай означають, що сервер повертає порожній або нетекстовий вміст чи приховує текст остаточної відповіді.
    - Малі прямі запити успішні, але запуски агентів OpenClaw завершуються збоями сервера або моделі (наприклад, Gemma у деяких збірках `inferrs`): транспорт OpenClaw, імовірно, уже налаштовано правильно; сервер не може обробити більшу структуру запиту середовища виконання агента.
    - Після вимкнення інструментів кількість помилок зменшується, але вони не зникають: схеми інструментів створювали частину навантаження, але решта проблеми все одно пов’язана з ресурсами зовнішньої моделі чи сервера або з помилкою сервера.

  </Accordion>
  <Accordion title="Варіанти виправлення">
    1. Установіть `compat.requiresStringContent: true` для серверів Chat Completions, які підтримують лише рядки.
    2. Установіть `compat.strictMessageKeys: true` для строгих серверів Chat Completions, які приймають у кожному повідомленні лише `role` і `content`.
    3. Установіть `compat.supportsTools: false` для моделей або серверів, які не можуть надійно обробляти набір схем інструментів OpenClaw.
    4. За можливості зменште навантаження запиту: скоротіть початкове завантаження робочого простору, історію сеансу, використовуйте легшу локальну модель або сервер із кращою підтримкою довгого контексту.
    5. Якщо малі прямі запити залишаються успішними, але кроки агента OpenClaw досі спричиняють збій сервера, розглядайте це як обмеження зовнішнього сервера або моделі та надайте його розробникам приклад відтворення з прийнятою структурою корисного навантаження.
  </Accordion>
</AccordionGroup>

Пов’язані матеріали:

- [Конфігурація](/uk/gateway/configuration)
- [Локальні моделі](/uk/gateway/local-models)
- [Кінцеві точки, сумісні з OpenAI](/uk/gateway/configuration-reference#openai-compatible-endpoints)

## Немає відповідей

Якщо канали працюють, але відповіді немає, перевірте маршрутизацію та політики, перш ніж щось перепідключати.

```bash
openclaw status
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw config get channels
openclaw logs --follow
```

Зверніть увагу на:

- Очікування сполучення для відправників особистих повідомлень.
- Обмеження згадування в групі (`requireMention`, `mentionPatterns`).
- Невідповідності списків дозволених каналів і груп.

Поширені ознаки:

- `drop guild message (mention required` → групове повідомлення ігнорується до згадування.
- `pairing request` → відправнику потрібне схвалення.
- `blocked` / `allowlist` → відправника або канал відфільтровано політикою.

Пов’язані матеріали:

- [Усунення проблем із каналами](/uk/channels/troubleshooting)
- [Групи](/uk/channels/groups)
- [Сполучення](/uk/channels/pairing)

## Підключення інтерфейсу керування панеллю

Якщо панель або інтерфейс керування не підключається, перевірте URL-адресу, режим автентифікації та припущення щодо захищеного контексту.

```bash
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --json
```

Зверніть увагу на:

- Правильні URL-адреси перевірки та панелі.
- Невідповідність режиму автентифікації або токена між клієнтом і Gateway.
- Використання HTTP там, де потрібна ідентифікація пристрою.

Якщо після оновлення локальний браузер не може підключитися до `127.0.0.1:18789`, спочатку відновіть локальну службу Gateway і переконайтеся, що вона обслуговує панель:

```bash
openclaw gateway restart
lsof -i :18789
curl http://127.0.0.1:18789
```

Якщо `curl` повертає HTML OpenClaw, Gateway працює, а проблема, найімовірніше, пов’язана з кешем браузера, старим глибоким посиланням або застарілим станом вкладки. Відкрийте `http://127.0.0.1:18789` безпосередньо й перейдіть із панелі. Якщо після перезапуску служба не залишається запущеною, виконайте `openclaw gateway start` і повторно перевірте `openclaw gateway status`.

<AccordionGroup>
  <Accordion title="Ознаки підключення та автентифікації">
    - `device identity required` → незахищений контекст або відсутня автентифікація пристрою.
    - `origin not allowed` → браузерний `Origin` відсутній у `gateway.controlUi.allowedOrigins` (або підключення виконується з браузерного джерела, що не є loopback, без явного списку дозволених).
    - `device nonce required` / `device nonce mismatch` → клієнт не завершує процес автентифікації пристрою на основі виклику (`connect.challenge` + `device.nonce`).
    - `device signature invalid` / `device signature expired` → клієнт підписав неправильні дані (або використав застарілу позначку часу) для поточного рукостискання.
    - `AUTH_TOKEN_MISMATCH` з `canRetryWithDeviceToken=true` → клієнт може виконати одну довірену повторну спробу з кешованим токеном пристрою.
    - Ця повторна спроба з кешованим токеном повторно використовує кешований набір областей доступу, збережений із токеном сполученого пристрою. Натомість виклики з явним `deviceToken` / явним `scopes` зберігають запитаний набір областей доступу.
    - `AUTH_SCOPE_MISMATCH` → токен пристрою розпізнано, але його схвалені області доступу не охоплюють цей запит на підключення; повторно сполучіть пристрій або схваліть запитаний контракт областей доступу замість ротації спільного токена Gateway.
    - Поза цим шляхом повторної спроби пріоритет автентифікації підключення такий: спочатку явно заданий спільний токен або пароль, потім явний `deviceToken`, далі збережений токен пристрою, а потім початковий токен.
    - В асинхронному шляху інтерфейсу керування Tailscale Serve невдалі спроби для того самого `{scope, ip}` серіалізуються до того, як обмежувач зареєструє помилку. Тому дві одночасні невдалі повторні спроби від одного клієнта можуть призвести до `retry later` під час другої спроби замість двох звичайних повідомлень про невідповідність.
    - `too many failed authentication attempts (retry later)` від loopback-клієнта браузерного джерела → повторні помилки від того самого нормалізованого `Origin` тимчасово блокуються; інше джерело localhost використовує окрему групу.
    - Повторний `unauthorized` після цієї повторної спроби → розбіжність спільного токена й токена пристрою; оновіть конфігурацію токена та за потреби повторно схваліть або замініть токен пристрою.
    - `gateway connect failed:` → неправильний цільовий хост, порт або URL-адреса.

  </Accordion>
</AccordionGroup>

### Коротка таблиця кодів деталей автентифікації

Використовуйте `error.details.code` з невдалої відповіді `connect`, щоб вибрати наступну дію:

| Код деталі                  | Значення                                                                                                                                                                                      | Рекомендована дія                                                                                                                                                                                                                                                                       |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AUTH_TOKEN_MISSING`         | Клієнт не надіслав обов’язковий спільний токен.                                                                                                                                                 | Вставте або задайте токен у клієнті та повторіть спробу. Для шляхів панелі: `openclaw config get gateway.auth.token`, а потім вставте його в налаштування інтерфейсу керування.                                                                                                                                              |
| `AUTH_TOKEN_MISMATCH`        | Спільний токен не збігається з токеном автентифікації Gateway.                                                                                                                                               | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені області доступу; виклики з явним `deviceToken` / `scopes` зберігають запитані області доступу. Якщо помилка не зникає, виконайте [контрольний список відновлення після розбіжності токенів](/uk/cli/devices#token-drift-recovery-checklist). |
| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен окремого пристрою застарів або був відкликаний.                                                                                                                                                 | Замініть або повторно схваліть токен пристрою за допомогою [CLI пристроїв](/uk/cli/devices), а потім підключіться знову.                                                                                                                                                                                                        |
| `AUTH_SCOPE_MISMATCH`        | Токен пристрою дійсний, але його схвалена роль або області доступу не охоплюють цей запит на підключення.                                                                                                       | Повторно сполучіть пристрій або схваліть запитаний контракт областей доступу; не розглядайте це як розбіжність спільного токена.                                                                                                                                                                                     |
| `PAIRING_REQUIRED`           | Ідентифікація пристрою потребує схвалення. Перевірте `error.details.reason` на наявність `not-paired`, `scope-upgrade`, `role-upgrade` або `metadata-upgrade` і використовуйте `requestId` / `remediationHint`, коли вони наявні. | Схваліть запит, що очікує: `openclaw devices list`, а потім `openclaw devices approve <requestId>`. Для підвищення областей доступу або ролі використовується той самий процес після перевірки запитаного доступу.                                                                                                               |

<Note>
Прямі RPC-виклики до loopback-сервера, автентифіковані за допомогою спільного токена або пароля Gateway, не повинні залежати від базового набору областей доступу сполученого пристрою в CLI. Якщо підагенти або інші внутрішні виклики й далі завершуються помилкою `scope-upgrade`, переконайтеся, що виклик використовує `client.id: "gateway-client"` і `client.mode: "backend"` та не примусово задає явний `deviceIdentity` або токен пристрою.
</Note>

Перевірка міграції автентифікації пристрою v2:

```bash
openclaw --version
openclaw doctor
openclaw gateway status
```

Якщо журнали містять помилки одноразового значення або підпису, оновіть клієнт, що підключається, і перевірте його:

<Steps>
  <Step title="Дочекайтеся connect.challenge">
    Клієнт очікує на виданий Gateway `connect.challenge`.
  </Step>
  <Step title="Підпишіть дані">
    Клієнт підписує дані, прив’язані до виклику.
  </Step>
  <Step title="Надішліть одноразове значення пристрою">
    Клієнт надсилає `connect.params.device.nonce` із тим самим одноразовим значенням виклику.
  </Step>
</Steps>

Якщо `openclaw devices rotate` / `revoke` / `remove` неочікувано відхилено:

- Сеанси токенів сполучених пристроїв можуть керувати лише **власним** пристроєм, якщо виклик також не має `operator.admin`.
- `openclaw devices rotate --scope ...` може запитувати лише ті операторські області доступу, які вже має сеанс виклику.

Пов’язані матеріали:

- [Конфігурація](/uk/gateway/configuration) (режими автентифікації Gateway)
- [Інтерфейс керування](/uk/web/control-ui)
- [Пристрої](/uk/cli/devices)
- [Віддалений доступ](/uk/gateway/remote)
- [Автентифікація довіреного проксі](/uk/gateway/trusted-proxy-auth)

## Служба Gateway не працює

Використовуйте цей розділ, якщо службу встановлено, але процес не залишається запущеним.

```bash
openclaw gateway status
openclaw status
openclaw logs --follow
openclaw doctor
openclaw gateway status --deep   # також перевірити служби системного рівня
```

Зверніть увагу на:

- `Runtime: stopped` з підказками щодо завершення.
- Невідповідність конфігурації служби (`Config (cli)` і `Config (service)`).
- Конфлікти порту або прослуховувача.
- Додаткові інсталяції launchd, systemd або schtasks, коли використовується `--deep`.
- Підказки щодо очищення `Other gateway-like services detected (best effort)`.

<AccordionGroup>
  <Accordion title="Поширені ознаки">
    - `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 (токен або пароль чи довірений проксі, якщо його налаштовано).
    - `another gateway instance is already listening` / `EADDRINUSE` → конфлікт порту.
    - `Other gateway-like services detected (best effort)` → існують застарілі або паралельні модулі launchd, systemd чи schtasks. У більшості конфігурацій слід використовувати один Gateway на комп’ютер; якщо потрібно більше одного, ізолюйте порти, конфігурацію, стан і робочий простір. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host).
    - `System-level OpenClaw gateway service detected` від doctor → системний модуль systemd існує, а служба рівня користувача відсутня. Видаліть або вимкніть дублікат, перш ніж дозволяти doctor установити службу користувача, або задайте `OPENCLAW_SERVICE_REPAIR_POLICY=external`, якщо системний модуль є запланованим супервізором.
    - `Gateway service port does not match current gateway config` → установлений супервізор досі закріплює старий `--port`. Виконайте `openclaw doctor --fix` або `openclaw gateway install --force`, а потім перезапустіть службу Gateway.

  </Accordion>
</AccordionGroup>

Пов’язані матеріали:

- [Фонове виконання та інструмент процесів](/uk/gateway/background-process)
- [Конфігурація](/uk/gateway/configuration)
- [Doctor](/uk/gateway/doctor)

## Gateway у macOS непомітно припиняє відповідати, а потім відновлює роботу після взаємодії з панеллю

Використовуйте, коли канали (Telegram, WhatsApp тощо) на хості macOS замовкають на період від кількох хвилин до кількох годин, а Gateway, схоже, відновлює роботу щойно ви відкриваєте Control UI, підключаєтеся через SSH або іншим чином взаємодієте з хостом. Зазвичай у `openclaw status` немає очевидних симптомів, оскільки на момент перевірки Gateway уже знову працює.

```bash
ls ~/.openclaw/logs/stability/ | tail -5
openclaw gateway stability --bundle latest
pmset -g log | grep -iE "sleep|wake|maintenance" | tail -50
launchctl print gui/$UID/ai.openclaw.gateway | grep -E "state|last exit|runs"
```

Шукайте:

- Один або кілька пакетів `*-uncaught_exception.json` у `~/.openclaw/logs/stability/`, де `error.code` має код тимчасової мережевої помилки, як-от `ENETDOWN`, `ENETUNREACH`, `EHOSTUNREACH` або `ECONNREFUSED`.
- Рядки `pmset -g log`, як-от `Entering Sleep state due to 'Maintenance Sleep'` або `en0 driver is slow (msg: WillChangeState to 0)`, що збігаються в часі з аварійними завершеннями. Power Nap / Maintenance Sleep ненадовго переводить драйвер Wi-Fi у стан 0; будь-який вихідний `connect()`, що припадає на цей проміжок, може завершитися помилкою `ENETDOWN` навіть на хості, який в інших випадках має повноцінне мережеве з’єднання.
- Вивід `launchctl print`, що показує `state = not running` із кількома нещодавніми `runs` і кодом виходу, особливо якщо проміжок між аварійним завершенням і наступним запуском становить близько години, а не кілька секунд. Після серії аварійних завершень macOS launchd застосовує недокументований механізм захисту від повторних запусків, через який може перестати виконувати `KeepAlive=true`, доки зовнішній тригер, як-от інтерактивний вхід, підключення панелі керування або `launchctl kickstart`, не активує його знову.

Типові ознаки:

- Пакет стабільності, у якому `error.code` має значення `ENETDOWN` або споріднений код, а стек викликів указує на Node `net` `lookupAndConnect` / `Socket.connect`. OpenClaw `2026.5.26` і новіші версії класифікують їх як безпечні тимчасові мережеві помилки, тому вони більше не передаються до верхньорівневого обробника неперехоплених помилок; якщо використовується старіша версія, спочатку оновіть її.
- Тривалі періоди без активності, які завершуються одразу після підключення до Control UI або входу на хост через SSH: саме видима для користувача активність повторно активує механізм повторного запуску launchd, а не будь-яка дія панелі керування над Gateway.
- Лічильник `runs` збільшується протягом дня без відповідного рядка `received SIG*; shutting down` у `~/Library/Logs/openclaw/gateway.log`: під час штатного завершення роботи сигнал записується в журнал, а під час тимчасових аварійних завершень — ні.

Що робити:

1. **Оновіть Gateway**, якщо використовується версія, старіша за `2026.5.26`. Після оновлення майбутні помилки `ENETDOWN` записуватимуться як попередження замість завершення процесу.
2. **Зменште активність режиму обслуговування під час сну** на Mac mini / настільних хостах, призначених для постійної роботи як сервери:

   ```bash
   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0
   ```

   Це суттєво зменшує, але не усуває повністю базові перебої в роботі драйвера. Система все одно може переходити в деякі режими обслуговування під час сну для підтримки TCP keepalive та mDNS незалежно від цих прапорців.

3. **Додайте засіб контролю працездатності**, щоб у майбутньому швидко виявити серію аварійних завершень, після якої launchd припинить повторні запуски:

   ```bash
   # Приклад перевірки працездатності з урахуванням launchd, придатної для 5-хвилинного cron або LaunchAgent
   state=$(launchctl print gui/$UID/ai.openclaw.gateway 2>/dev/null | awk -F'= ' '/state =/ {print $2; exit}')
   if [ "$state" != "running" ]; then
     launchctl kickstart -k gui/$UID/ai.openclaw.gateway
   fi
   ```

   Мета полягає в тому, щоб ззовні повторно активувати механізм повторного запуску; лише `KeepAlive=true` недостатньо в macOS після серії аварійних завершень.

Пов’язані матеріали:

- [Примітки щодо платформи macOS](/uk/platforms/macos)
- [Журналювання](/uk/logging)
- [Doctor](/uk/gateway/doctor)

## Цикл супервізора macOS launchd із дубльованими LaunchAgent для Gateway/Node

Використовуйте, коли інсталяція macOS постійно перезапускається кожні кілька секунд, перевірки працездатності `openclaw`
почергово показують доступність і недоступність, а надсилання через канали зупиняється,
хоча служба, схоже, працює.

Це спостерігалося в старіших інсталяціях, де одночасно були активні LaunchAgent `ai.openclaw.gateway` і
`ai.openclaw.node`, кожен із яких додавав
`OPENCLAW_LAUNCHD_LABEL`. У такому стані OpenClaw може виявити супервізію launchd,
спробувати передати керування перезапуском назад launchd і потрапити у швидкий цикл
`EADDRINUSE`/повторного запуску замість підтримання одного стабільного процесу Gateway.

```bash
for i in 1 2 3 4; do
  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'
  sleep 10
done

openclaw gateway status --deep
openclaw node status
launchctl print gui/$UID/ai.openclaw.gateway | grep -E 'state|last exit|runs'
tail -n 80 ~/Library/Logs/openclaw/gateway.log
```

Шукайте:

- Кілька PID Gateway у 30-секундній вибірці замість одного стабільного
  процесу.
- `EADDRINUSE`, `another gateway instance is already listening` або повторювані
  рядки перезапуску/передавання керування в `gateway.log`.
- Одночасно завантажені `~/Library/LaunchAgents/ai.openclaw.gateway.plist` і
  `~/Library/LaunchAgents/ai.openclaw.node.plist` на хості, де має працювати лише одна
  керована служба Gateway.

Що робити:

1. Якщо на цьому хості має працювати лише служба Gateway, видаліть керовану службу Node
   за допомогою OpenClaw. **Пропустіть цей крок**, якщо служба Node активно використовується
   для віддалених функцій Node; її видалення зупинить ці функції на
   цьому хості:

   ```bash
   openclaw node uninstall
   ```

2. Установіть постійну обгортку Gateway, яка очищає успадковані маркери launchd
   перед запуском OpenClaw. Використовуйте підтримуваний параметр `--wrapper`; не
   редагуйте згенерований файл у `~/.openclaw/service-env/`, оскільки повторне встановлення
   служби, оновлення та відновлення за допомогою Doctor повторно генерують цей файл:

   ```bash
   mkdir -p ~/.local/bin
   cat >~/.local/bin/openclaw-launchd-workaround <<'EOF'
   #!/bin/sh
   set -eu
   unset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || true
   exec openclaw "$@"
   EOF
   chmod 700 ~/.local/bin/openclaw-launchd-workaround

   openclaw gateway install \
     --wrapper ~/.local/bin/openclaw-launchd-workaround \
     --force
   ```

   `gateway install` зберігає шлях до обгортки під час примусових перевстановлень,
   оновлень і виправлень за допомогою doctor.

3. Переконайтеся, що Gateway працює стабільно й обслуговує RPC, а не лише прослуховує з’єднання:

   ```bash
   openclaw gateway status --deep --require-rpc

   for i in 1 2 3 4; do
     ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'
     sleep 10
   done
   ```

   Вибірка PID має показувати один стабільний процес замість змінного набору
   PID, а диспетчеризація вхідних повідомлень каналів має відновитися.

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

   ```bash
   OPENCLAW_WRAPPER= openclaw gateway install --force
   rm ~/.local/bin/openclaw-launchd-workaround
   ```

Пов’язане:

- [Примітки щодо платформи macOS](/uk/platforms/mac/bundled-gateway)
- [Doctor](/uk/gateway/doctor)
- [CLI Gateway](/uk/cli/gateway)

## Gateway завершує роботу під час інтенсивного використання пам’яті

Використовуйте, коли Gateway зникає під навантаженням, супервізор повідомляє про перезапуск у стилі OOM або в журналах згадується `critical memory pressure bundle written`.

```bash
openclaw gateway status --deep
openclaw logs --follow
openclaw gateway stability --bundle latest
openclaw gateway diagnostics export
```

Шукайте:

- `Reason: diagnostic.memory.pressure.critical` в останньому пакеті стабільності.
- `Memory pressure:` з `critical/rss_threshold`, `critical/heap_threshold` або `critical/rss_growth`.
- Значення `V8 heap:` поблизу граничного обсягу купи.
- Записи `Largest session files:`, як-от `agents/<agent>/sessions/<session>.jsonl` або `sessions/<session>.jsonl`.
- Лічильники пам’яті cgroup у Linux, коли Gateway працює в контейнері або службі з обмеженням пам’яті.

Поширені ознаки:

- `critical memory pressure bundle written` з’являється незадовго до перезапуску → OpenClaw зберіг пакет стабільності перед OOM. Перевірте його за допомогою `openclaw gateway stability --bundle latest`.
- `memory pressure: level=critical ... memoryPressureSnapshot=disabled` з’являється в журналах Gateway → OpenClaw виявив критичний тиск на пам’ять, але знімок стабільності перед OOM вимкнено.
- `Largest session files:` указує на дуже великий шлях до редагованої стенограми → скоротіть збережену історію сеансів, перевірте зростання сеансу або перемістіть старі стенограми з активного сховища перед перезапуском.
- Кількість використаних байтів `V8 heap:` близька до граничного обсягу купи → зменште навантаження від підказок і сеансів, скоротіть кількість одночасних завдань або збільште граничний обсяг купи Node лише після підтвердження, що таке робоче навантаження є очікуваним.
- `Memory pressure: critical/rss_growth` → обсяг пам’яті швидко зріс у межах одного інтервалу вибірки. Перевірте останні журнали на наявність великого імпорту, неконтрольованого виведення інструментів, повторюваних спроб або пакета поставлених у чергу завдань агентів.
- У журналах з’являється критичний тиск на пам’ять, але пакета немає → це типова поведінка. Установіть `diagnostics.memoryPressureSnapshot: true`, щоб під час майбутніх подій критичного тиску на пам’ять зберігався пакет стабільності перед OOM.

Пакет стабільності не містить корисного навантаження. Він містить операційні дані про пам’ять і редаговані відносні шляхи до файлів, але не текст повідомлень, тіла webhook, облікові дані, токени, файли cookie або необроблені ідентифікатори сеансів. Додавайте експорт діагностики до звітів про помилки замість копіювання необроблених журналів.

Пов’язане:

- [Стан Gateway](/uk/gateway/health)
- [Експорт діагностики](/uk/gateway/diagnostics)
- [Сеанси](/uk/cli/sessions)

## Gateway відхилив недійсну конфігурацію

Використовуйте, коли запуск Gateway завершується помилкою `Invalid config` або журнали гарячого перезавантаження повідомляють, що недійсне редагування було пропущено.

```bash
openclaw logs --follow
openclaw config file
openclaw config validate
openclaw doctor
```

Шукайте:

- `Invalid config at ...`
- `config reload skipped (invalid config): ...`
- `Config write rejected: ...`
- Файл `openclaw.json.rejected.*` із позначкою часу поруч з активною конфігурацією.
- Файл `openclaw.json.clobbered.*` із позначкою часу, якщо `doctor --fix` виправив пошкоджене безпосереднє редагування.
- OpenClaw зберігає останні 32 файли `.clobbered.*` для кожного шляху конфігурації та видаляє старіші під час ротації.

<AccordionGroup>
  <Accordion title="Що сталося">
    - Конфігурація не пройшла перевірку під час запуску, гарячого перезавантаження або запису, виконаного OpenClaw.
    - Запуск Gateway завершується безпечною відмовою замість перезапису `openclaw.json`.
    - Гаряче перезавантаження пропускає недійсні зовнішні редагування та залишає чинну конфігурацію середовища виконання активною.
    - Записи, виконувані OpenClaw, відхиляють недійсне або руйнівне корисне навантаження перед фіксацією та зберігають `.rejected.*`.
    - `openclaw doctor --fix` відповідає за виправлення. Він може видалити префікси, що не належать до JSON, або відновити останню відому справну копію, зберігши відхилене корисне навантаження як `.clobbered.*`.
    - Коли для одного шляху конфігурації виконується багато виправлень, OpenClaw видаляє старіші файли `.clobbered.*` під час ротації, щоб найновіше виправлене корисне навантаження залишалося доступним.

  </Accordion>
  <Accordion title="Перевірка та виправлення">
    ```bash
    CONFIG="$(openclaw config file)"
    ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
    diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
    openclaw config validate
    openclaw doctor
    ```
  </Accordion>
  <Accordion title="Поширені ознаки">
    - `.clobbered.*` існує → doctor зберіг пошкоджене зовнішнє редагування під час виправлення активної конфігурації.
    - `.rejected.*` існує → запис конфігурації, виконаний OpenClaw, не пройшов перевірку схеми або перезапису перед фіксацією.
    - `Config write rejected:` → під час запису була спроба вилучити обов’язкову структуру, різко зменшити файл або зберегти недійсну конфігурацію.
    - `config reload skipped (invalid config):` → безпосереднє редагування не пройшло перевірку, тому запущений Gateway його проігнорував.
    - `Invalid config at ...` → запуск завершився помилкою до завантаження служб Gateway.
    - `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` або `size-drop-vs-last-good:*` → запис, виконаний OpenClaw, було відхилено, оскільки порівняно з останньою справною резервною копією було втрачено поля або зменшено розмір.
    - `Config last-known-good promotion skipped` → кандидат містив замінники прихованих секретів, як-от `***`.

  </Accordion>
  <Accordion title="Варіанти виправлення">
    1. Запустіть `openclaw doctor --fix`, щоб doctor виправив конфігурацію з префіксом або наслідками перезапису чи відновив останню справну версію.
    2. Скопіюйте лише потрібні ключі з `.clobbered.*` або `.rejected.*`, а потім застосуйте їх за допомогою `openclaw config set` або `config.patch`.
    3. Перед перезапуском виконайте `openclaw config validate`.
    4. Під час ручного редагування зберігайте повну конфігурацію JSON5, а не лише частковий об’єкт, який потрібно змінити.
  </Accordion>
</AccordionGroup>

Пов’язані матеріали:

- [Конфігурація](/uk/cli/config)
- [Конфігурація: гаряче перезавантаження](/uk/gateway/configuration#config-hot-reload)
- [Конфігурація: сувора перевірка](/uk/gateway/configuration#strict-validation)
- [Doctor](/uk/gateway/doctor)

## Попередження перевірки Gateway

Використовуйте, коли `openclaw gateway probe` встановлює з’єднання, але все одно виводить блок попереджень.

```bash
openclaw gateway probe
openclaw gateway probe --json
openclaw gateway probe --ssh user@gateway-host
```

Зверніть увагу на:

- `warnings[].code` і `primaryTargetId` у виведенні JSON.
- Чи стосується попередження резервного підключення через SSH, кількох Gateway, відсутніх областей доступу або нерозпізнаних посилань на автентифікаційні дані.

Поширені ознаки:

- `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH завершилося помилкою, але команда все одно спробувала підключитися безпосередньо до налаштованих цілей або цілей зворотного зв’язку.
- `multiple reachable gateway identities detected` → відповіли різні Gateway або OpenClaw не зміг підтвердити, що доступні цілі є тим самим Gateway. Тунель SSH, URL-адреса проксі або налаштована віддалена URL-адреса того самого Gateway вважаються одним Gateway із кількома транспортами, навіть якщо їхні порти відрізняються.
- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення успішне, але детальний RPC обмежений областю доступу; сполучіть ідентичність пристрою або використайте облікові дані з `operator.read`.
- `Gateway accepted the WebSocket connection, but follow-up read diagnostics failed` → підключення успішне, але виконання повного набору діагностичних RPC завершилося через перевищення часу очікування або з помилкою. Вважайте цей Gateway доступним, але з обмеженою діагностикою; порівняйте `connect.ok` і `connect.rpcOk` у виведенні `--json`.
- `Capability: pairing-pending` або `gateway closed (1008): pairing required` → Gateway відповів, але цьому клієнту все ще потрібне сполучення або схвалення для звичайного операторського доступу.
- Текст попередження про нерозпізнане посилання на секрет `gateway.auth.*` / `gateway.remote.*` → автентифікаційні дані були недоступні в цьому шляху команди для цілі, підключення до якої завершилося помилкою.

Пов’язані матеріали:

- [Gateway](/uk/cli/gateway)
- [Кілька Gateway на одному хості](/uk/gateway#multiple-gateways-same-host)
- [Віддалений доступ](/uk/gateway/remote)

## Канал підключено, але повідомлення не надходять

Якщо стан каналу — підключено, але обмін повідомленнями не відбувається, зосередьтеся на політиках, дозволах і специфічних для каналу правилах доставлення.

```bash
openclaw channels status --probe
openclaw pairing list --channel <channel> [--account <id>]
openclaw status --deep
openclaw logs --follow
openclaw config get channels
```

Зверніть увагу на:

- Політику особистих повідомлень (`pairing`, `allowlist`, `open`, `disabled`).
- Список дозволених груп і вимоги щодо згадок.
- Відсутні дозволи або області доступу API каналу.

Поширені ознаки:

- `mention required` → повідомлення проігноровано через групову політику згадок.
- `pairing` / сліди очікування схвалення → відправника не схвалено.
- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема з автентифікацією або дозволами каналу.

Пов’язані матеріали:

- [Усунення несправностей каналів](/uk/channels/troubleshooting)
- [Discord](/uk/channels/discord)
- [Telegram](/uk/channels/telegram)
- [WhatsApp](/uk/channels/whatsapp)

## Доставлення Cron і Heartbeat

Якщо Cron або Heartbeat не запустився чи не виконав доставлення, спочатку перевірте стан планувальника, а потім ціль доставлення.

```bash
openclaw cron status
openclaw cron list
openclaw cron runs --id <jobId> --limit 20
openclaw system heartbeat last
openclaw logs --follow
```

Зверніть увагу на:

- Чи ввімкнено Cron і чи вказано час наступного пробудження.
- Стан історії запусків завдання (`ok`, `skipped`, `error`).
- Причини пропуску Heartbeat (`quiet-hours`, `requests-in-flight`, `cron-in-progress`, `lanes-busy`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`).

<AccordionGroup>
  <Accordion title="Поширені ознаки">
    - `cron: scheduler disabled; jobs will not run automatically` → Cron вимкнено.
    - `cron: timer tick failed` → такт планувальника завершився помилкою; перевірте помилки файлів, журналів і середовища виконання.
    - `heartbeat skipped` з `reason=quiet-hours` → поза межами вікна активних годин.
    - `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожні рядки, коментарі, заголовки, огорожі блоків або заготовку порожнього списку завдань, тому OpenClaw пропускає виклик моделі.
    - `heartbeat skipped` з `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але на цьому такті жодне із завдань не має виконуватися.
    - `heartbeat: unknown accountId` → недійсний ідентифікатор облікового запису для цілі доставлення Heartbeat.
    - `heartbeat skipped` з `reason=dm-blocked` → ціль Heartbeat визначено як призначення типу особистого повідомлення, коли `agents.defaults.heartbeat.directPolicy` (або перевизначення для окремого агента) має значення `block`.

  </Accordion>
</AccordionGroup>

Пов’язані матеріали:

- [Heartbeat](/uk/gateway/heartbeat)
- [Заплановані завдання](/uk/automation/cron-jobs)
- [Заплановані завдання: усунення несправностей](/uk/automation/cron-jobs#troubleshooting)

## Node сполучено, але інструмент не працює

Якщо Node сполучено, але інструменти не працюють, окремо перевірте стан переднього плану, дозволів і схвалення.

```bash
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>
openclaw approvals get --node <idOrNameOrIp>
openclaw logs --follow
openclaw status
```

Зверніть увагу на:

- Чи перебуває Node в мережі та чи має очікувані можливості.
- Надані дозволи ОС на камеру, мікрофон, геопозицію та екран.
- Схвалення виконання команд і стан списку дозволених команд.

Поширені ознаки:

- `NODE_BACKGROUND_UNAVAILABLE` → застосунок Node має перебувати на передньому плані.
- `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → відсутній дозвіл ОС.
- `SYSTEM_RUN_DENIED: approval required` → очікується схвалення виконання команди.
- `SYSTEM_RUN_DENIED: allowlist miss` → команду заблоковано списком дозволених команд.

Пов’язані матеріали:

- [Схвалення виконання команд](/uk/tools/exec-approvals)
- [Усунення несправностей Node](/uk/nodes/troubleshooting)
- [Node](/uk/nodes/index)

## Інструмент браузера не працює

Використовуйте, коли дії інструмента браузера завершуються помилкою, хоча сам Gateway працює справно.

```bash
openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw logs --follow
openclaw doctor
```

Зверніть увагу на:

- Чи задано `plugins.allow` і чи містить воно `browser`.
- Чинний шлях до виконуваного файлу браузера.
- Доступність профілю CDP.
- Наявність локального Chrome для профілів `existing-session` / `user`.

<AccordionGroup>
  <Accordion title="Ознаки 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)` → налаштована URL-адреса CDP використовує непідтримувану схему, як-от `file:` або `ftp:`.
    - `browser.cdpUrl has invalid port` → налаштована URL-адреса CDP має недійсний порт або порт поза допустимим діапазоном.
    - `Playwright is not available in this gateway build; '<feature>' is unsupported.` → у поточній інсталяції Gateway відсутня основна залежність середовища виконання браузера; перевстановіть або оновіть OpenClaw, а потім перезапустіть Gateway. Знімки ARIA та базові знімки сторінок усе ще можуть працювати, але навігація, знімки ШІ, знімки елементів за CSS-селекторами й експорт у PDF залишатимуться недоступними.

  </Accordion>
  <Accordion title="Ознаки Chrome MCP / наявного сеансу">
    - `Could not find DevToolsActivePort for chrome` → наявному сеансу Chrome MCP ще не вдалося підключитися до вибраного каталогу даних браузера. Відкрийте сторінку перевірки браузера, увімкніть віддалене налагодження, залиште браузер відкритим, схваліть перший запит на підключення, а потім повторіть спробу. Якщо стан входу в обліковий запис не потрібен, віддайте перевагу керованому профілю `openclaw`.
    - `No browser tabs found for profile="user"` → у профілі підключення Chrome MCP немає відкритих локальних вкладок Chrome.
    - `Remote CDP for profile "<name>" is not reachable` → налаштована віддалена кінцева точка CDP недоступна з хоста Gateway.
    - `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль лише для підключення не має доступної цілі або кінцева точка HTTP відповіла, але WebSocket CDP усе одно не вдалося відкрити.

  </Accordion>
  <Accordion title="Ознаки елементів / знімків екрана / передавання файлів">
    - `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` знімка, а не CSS `--element`.
    - `existing-session file uploads do not support element selectors; use ref/inputRef.` → обробникам передавання файлів Chrome MCP потрібні посилання на знімки, а не CSS-селектори.
    - `existing-session file uploads currently support one file at a time.` → у профілях Chrome MCP передавайте один файл за один виклик.
    - `existing-session dialog handling does not support timeoutMs.` → обробники діалогів у профілях Chrome MCP не підтримують перевизначення часу очікування.
    - `existing-session type does not support timeoutMs overrides.` → не вказуйте `timeoutMs` для `act:type` у профілях `profile="user"` / наявного сеансу Chrome MCP або використовуйте керований профіль чи профіль браузера CDP, якщо потрібен власний час очікування.
    - `response body is not supported for existing-session profiles yet.` → для `responsebody` усе ще потрібен керований браузер або необроблений профіль CDP.
    - Застарілі перевизначення області перегляду, темного режиму, локалі або автономного режиму в профілях лише для підключення чи віддалених профілях CDP → запустіть `openclaw browser stop --browser-profile <name>`, щоб закрити активний сеанс керування та звільнити стан емуляції Playwright/CDP без перезапуску всього Gateway.

  </Accordion>
</AccordionGroup>

Пов’язані матеріали:

- [Браузер (керований OpenClaw)](/uk/tools/browser)
- [Усунення несправностей браузера](/uk/tools/browser-linux-troubleshooting)

## Якщо після оновлення щось раптово перестало працювати

Більшість несправностей після оновлення спричинена розбіжностями конфігурації або застосуванням суворіших стандартних налаштувань.

<AccordionGroup>
  <Accordion title="1. Поведінка автентифікації та перевизначення URL змінилася">
    ```bash
    openclaw gateway status
    openclaw config get gateway.mode
    openclaw config get gateway.remote.url
    openclaw config get gateway.auth.mode
    ```

    Що перевірити:

    - Якщо `gateway.mode=remote`, виклики CLI можуть спрямовуватися до віддаленого сервісу, тоді як локальний сервіс працює справно.
    - Явні виклики `--url` не використовують збережені облікові дані як резервний варіант.

    Типові ознаки:

    - `gateway connect failed:` → неправильна цільова URL-адреса.
    - `unauthorized` → кінцева точка доступна, але автентифікація неправильна.

  </Accordion>
  <Accordion title="2. Обмеження прив’язування та автентифікації стали суворішими">
    ```bash
    openclaw config get gateway.bind
    openclaw config get gateway.auth.mode
    openclaw config get gateway.auth.token
    openclaw gateway status
    openclaw logs --follow
    ```

    Що перевірити:

    - Прив’язування не до loopback-інтерфейсу (`lan`, `tailnet`, `custom`) потребує коректного шляху автентифікації Gateway: автентифікації за спільним токеном/паролем або правильно налаштованого розгортання `trusted-proxy` не на loopback-інтерфейсі.
    - Старі ключі на кшталт `gateway.token` не замінюють `gateway.auth.token`.

    Типові ознаки:

    - `refusing to bind gateway ... without auth` → прив’язування не до loopback-інтерфейсу без коректного шляху автентифікації Gateway.
    - `Connectivity probe: failed`, коли середовище виконання працює → Gateway працює, але недоступний із поточними параметрами автентифікації або URL-адреси.

  </Accordion>
  <Accordion title="3. Стан сполучення та ідентичності пристрою змінився">
    ```bash
    openclaw devices list
    openclaw pairing list --channel <channel> [--account <id>]
    openclaw logs --follow
    openclaw doctor
    ```

    Що перевірити:

    - Очікують схвалення пристрої для панелі керування/вузлів.
    - Очікують схвалення запити на сполучення через приватні повідомлення після змін політики або ідентичності.

    Типові ознаки:

    - `device identity required` → вимоги автентифікації пристрою не виконано.
    - `pairing required` → відправника/пристрій необхідно схвалити.

  </Accordion>
</AccordionGroup>

Якщо після перевірок конфігурація сервісу та середовище виконання все ще не узгоджуються, повторно встановіть метадані сервісу з того самого каталогу профілю/стану:

```bash
openclaw gateway install --force
openclaw gateway restart
```

Пов’язані матеріали:

- [Автентифікація](/uk/gateway/authentication)
- [Фонове виконання та інструмент процесів](/uk/gateway/background-process)
- [Сполучення Node](/uk/gateway/pairing)

## Пов’язані матеріали

- [Doctor](/uk/gateway/doctor)
- [Поширені запитання](/uk/help/faq)
- [Операційний посібник Gateway](/uk/gateway)
