Устранение неполадок

​

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

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 в разделе Channels: конфигурация канала по-прежнему существует, но регистрация плагина завершилась ошибкой до загрузки канала.
• Ошибки 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 устаревшего клиента исчез.

​

Символическая ссылка на Skill пропущена как выход за пределы пути

Пропуск пути Skill за пределами настроенного корневого каталога: ... причина=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 поддерживает общедоступный контекст 1M для Claude 4.x (Opus 4.6/4.7/4.8, Sonnet 4.6) либо конфигурация модели всё ещё содержит устаревший параметр params.context1m: true.
• Текущие учётные данные Anthropic не дают права использовать длинный контекст.
• Запросы завершаются ошибкой только в длинных сеансах или запусках модели, которым требуется контекст 1M.

• Anthropic
• Использование токенов и затраты
• Почему Anthropic возвращает HTTP 429?

​

Блокировка ответов 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":"привет"}],"stream":false}'
openclaw infer model run --model <provider/model> --prompt "привет" --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 проверки и 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 и кодом выхода, особенно если интервал между аварийным завершением и следующим запуском составляет около часа, а не несколько секунд. После серии аварийных завершений launchd в macOS применяет недокументированный механизм защиты от повторных запусков, из-за которого 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, подходящей для cron или LaunchAgent с интервалом 5 минут
   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

​

Цикл супервизора launchd в macOS при дублирующихся 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, нескольким шлюзам, отсутствующим областям доступа или неразрешённым ссылкам аутентификации.

• SSH tunnel failed to start; falling back to direct probes. → настройка SSH завершилась ошибкой, но команда всё равно попыталась использовать непосредственно настроенные адреса или адреса обратной петли.
• multiple reachable gateway identities detected → ответили разные шлюзы либо OpenClaw не удалось доказать, что доступные адреса ведут к одному шлюзу. SSH-туннель, URL прокси или настроенный удалённый URL к одному и тому же шлюзу считается одним шлюзом с несколькими транспортами, даже если порты транспортов различаются.
• 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 → шлюз ответил, но этому клиенту всё ещё требуется сопряжение или одобрение перед получением обычного операторского доступа.
• Текст предупреждения о неразрешённой ссылке SecretRef gateway.auth.* / gateway.remote.* → данные аутентификации были недоступны в этом пути выполнения команды для целевого адреса, подключение к которому завершилось ошибкой.

• 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
• Узлы

​

Инструмент браузера не работает

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