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

​

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

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.

​

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

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-копії автентифікаційних даних окремих агентів і видаляє старі копії, щоб усі агенти використовували поточний спільний профіль.

​

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

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

openclaw gateway install --force
openclaw gateway restart

​

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

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 застарілого клієнта зник.

​

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

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

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

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

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

​

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

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.

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

​

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

openclaw status
openclaw gateway status
openclaw logs --follow

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

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

​

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

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

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.
• Збої сервера, які виникають лише за більшої кількості токенів запиту або з повними запитами середовища виконання агента.

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

​

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

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 → відправника або канал відфільтровано політикою.

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

​

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

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

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

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

​

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

openclaw --version
openclaw doctor
openclaw gateway status

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

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

​

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

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).

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

​

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

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 / настільних хостах, призначених для постійної роботи як сервери:
   sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0
   
   Це суттєво зменшує, але не усуває повністю базові перебої в роботі драйвера. Система все одно може переходити в деякі режими обслуговування під час сну для підтримки TCP keepalive та mDNS незалежно від цих прапорців.
3. Додайте засіб контролю працездатності, щоб у майбутньому швидко виявити серію аварійних завершень, після якої launchd припинить повторні запуски:
   # Приклад перевірки працездатності з урахуванням 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
• Журналювання
• Doctor

​

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

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; її видалення зупинить ці функції на цьому хості:
   openclaw node uninstall
   
2. Установіть постійну обгортку Gateway, яка очищає успадковані маркери launchd перед запуском OpenClaw. Використовуйте підтримуваний параметр --wrapper; не редагуйте згенерований файл у ~/.openclaw/service-env/, оскільки повторне встановлення служби, оновлення та відновлення за допомогою Doctor повторно генерують цей файл:
   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, а не лише прослуховує з’єднання:
   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, видаліть обхідне рішення та перевстановіть звичайну керовану службу:
   OPENCLAW_WRAPPER= openclaw gateway install --force
   rm ~/.local/bin/openclaw-launchd-workaround
   

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

​

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

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.

• Стан Gateway
• Експорт діагностики
• Сеанси

​

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

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.* для кожного шляху конфігурації та видаляє старіші під час ротації.

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

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

​

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

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

​

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

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 → проблема з автентифікацією або дозволами каналу.

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

​

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

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).

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

​

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

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 → команду заблоковано списком дозволених команд.

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

​

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

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.

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

​

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

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

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

openclaw gateway install --force
openclaw gateway restart

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

​

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

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