Усунення несправностей

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

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

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

openclaw statusopenclaw gateway statusopenclaw logs --followopenclaw doctoropenclaw channels status --probe

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

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

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

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

openclaw status --allopenclaw update status --jsonopenclaw gateway status --deepopenclaw doctor --fixopenclaw 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.

which openclawopenclaw --versionopenclaw gateway status --deepopenclaw config get meta.lastTouchedVersion

openclaw gateway install --forceopenclaw gateway restart

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

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

openclaw --versionwhich -a openclawopenclaw gateway status --deepopenclaw doctor --deepopenclaw 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 пропущено через вихід за межі шляху

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

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

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

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

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

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

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

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

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

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

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

• Конфігурація Skills
• Приклади конфігурації

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

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

openclaw logs --followopenclaw models statusopenclaw 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.

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

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

• Anthropic
• Використання токенів і витрати
• Чому я бачу помилку HTTP 429 від Anthropic?

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

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

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

openclaw statusopenclaw gateway statusopenclaw logs --follow

Перевірте:

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

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

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

• Кінцеві точки, сумісні з OpenAI
• Конфігурація провайдера
• Журнали

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

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

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

curl http://127.0.0.1:1234/v1/modelscurl 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" --jsonopenclaw logs --follow

Перевірте:

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

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

• Конфігурація
• Локальні моделі
• Кінцеві точки, сумісні з OpenAI

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

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

openclaw statusopenclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw config get channelsopenclaw logs --follow

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

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

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

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

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

• Усунення проблем із каналами
• Групи
• Сполучення

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

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

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --json

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

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

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

openclaw gateway restartlsof -i :18789curl http://127.0.0.1:18789

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

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

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

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

openclaw --versionopenclaw doctoropenclaw gateway status

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

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

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

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

• Конфігурація (режими автентифікації Gateway)
• Інтерфейс керування
• Пристрої
• Віддалений доступ
• Автентифікація довіреного проксі

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

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

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # також перевірити служби системного рівня

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

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

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

• Фонове виконання та інструмент процесів
• Конфігурація
• Doctor

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

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

ls ~/.openclaw/logs/stability/ | tail -5openclaw gateway stability --bundle latestpmset -g log | grep -iE "sleep|wake|maintenance" | tail -50launchctl 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 / настільних хостах, призначених для постійної роботи як сервери:

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

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

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

   # Приклад перевірки працездатності з урахуванням launchd, придатної для 5-хвилинного cron або LaunchAgentstate=$(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.gatewayfi

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

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

• Примітки щодо платформи macOS
• Журналювання
• Doctor

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

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

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

for i in 1 2 3 4; do  ps aux | grep 'openclaw.*index.js' | grep -v grep | awk '{print $2}'  sleep 10done openclaw gateway status --deepopenclaw node statuslaunchctl 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; її видалення зупинить ці функції на цьому хості:

   openclaw node uninstall

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

   mkdir -p ~/.local/bincat >~/.local/bin/openclaw-launchd-workaround <<'EOF'#!/bin/shset -euunset OPENCLAW_LAUNCHD_LABEL LAUNCH_JOB_LABEL LAUNCH_JOB_NAME XPC_SERVICE_NAME || trueexec openclaw "$@"EOFchmod 700 ~/.local/bin/openclaw-launchd-workaround openclaw gateway install \  --wrapper ~/.local/bin/openclaw-launchd-workaround \  --force

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

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

   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 10done

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

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

   OPENCLAW_WRAPPER= openclaw gateway install --forcerm ~/.local/bin/openclaw-launchd-workaround

Пов’язане:

• Примітки щодо платформи macOS
• Doctor
• CLI Gateway

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

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

openclaw gateway status --deepopenclaw logs --followopenclaw gateway stability --bundle latestopenclaw 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
• Експорт діагностики
• Сеанси

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

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

openclaw logs --followopenclaw config fileopenclaw config validateopenclaw doctor

Шукайте:

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

CONFIG="$(openclaw config file)"ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | headdiff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"openclaw config validateopenclaw doctor

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

• Конфігурація
• Конфігурація: гаряче перезавантаження
• Конфігурація: сувора перевірка
• Doctor

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

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

openclaw gateway probeopenclaw gateway probe --jsonopenclaw 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
• Кілька Gateway на одному хості
• Віддалений доступ

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

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

openclaw channels status --probeopenclaw pairing list --channel <channel> [--account <id>]openclaw status --deepopenclaw logs --followopenclaw config get channels

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

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

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

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

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

• Усунення несправностей каналів
• Discord
• Telegram
• WhatsApp

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

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

openclaw cron statusopenclaw cron listopenclaw cron runs --id <jobId> --limit 20openclaw system heartbeat lastopenclaw 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).

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

• Heartbeat
• Заплановані завдання
• Заплановані завдання: усунення несправностей

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

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

openclaw nodes statusopenclaw nodes describe --node <idOrNameOrIp>openclaw approvals get --node <idOrNameOrIp>openclaw logs --followopenclaw status

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

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

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

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

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

• Схвалення виконання команд
• Усунення несправностей Node
• Node

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

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

openclaw browser statusopenclaw browser start --browser-profile openclawopenclaw browser profilesopenclaw logs --followopenclaw doctor

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

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

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

• Браузер (керований OpenClaw)
• Усунення несправностей браузера

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

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

openclaw gateway statusopenclaw config get gateway.modeopenclaw config get gateway.remote.urlopenclaw config get gateway.auth.mode

openclaw config get gateway.bindopenclaw config get gateway.auth.modeopenclaw config get gateway.auth.tokenopenclaw gateway statusopenclaw logs --follow

openclaw devices listopenclaw pairing list --channel <channel> [--account <id>]openclaw logs --followopenclaw doctor

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

openclaw gateway install --forceopenclaw gateway restart

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

• Автентифікація
• Фонове виконання та інструмент процесів
• Сполучення Node

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

• Doctor
• Поширені запитання
• Операційний посібник Gateway