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

Эта страница — подробный runbook. Начните с /help/troubleshooting, если сначала нужен быстрый поток triage.

Лестница команд

Сначала выполните это, в таком порядке:

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 показывает живой статус транспорта по каждому аккаунту и, где поддерживается, результаты probe/audit, такие как 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. Ожидающие или неудачные handoff включают следующую команду для запуска.
• plugin load failed: dependency tree corrupted; run openclaw doctor --fix в разделе Channels. Это означает, что конфигурация канала все еще существует, но регистрация Plugin завершилась с ошибкой до того, как канал смог загрузиться.
• provider 401 после повторной авторизации. openclaw doctor --fix проверяет устаревшие OAuth auth shadows для отдельных агентов и удаляет старые копии, чтобы все агенты разрешали текущий общий профиль.

Split brain установки и защита более новой конфигурации

Используйте это, когда gateway service неожиданно останавливается после обновления или логи показывают, что один бинарный файл openclaw старше версии, которая последней записала openclaw.json.

OpenClaw помечает записи конфигурации через meta.lastTouchedVersion. Команды только для чтения все еще могут просматривать конфигурацию, записанную более новым OpenClaw, но мутации процессов и сервисов отказываются продолжать работу из более старого бинарного файла. Заблокированные действия включают запуск, остановку, перезапуск, удаление gateway service, принудительную переустановку сервиса, запуск Gateway в service-mode и очистку порта через gateway --force.

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

openclaw gateway install --forceopenclaw gateway restart

Несовпадение протокола после rollback

Используйте это, когда логи продолжают печатать protocol mismatch после downgrade или rollback OpenClaw. Это означает, что работает более старый 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 или wrapper, от которого вы откатились.

Исправление:

1. Остановите или перезапустите устаревший клиентский процесс OpenClaw, показанный gateway status --deep.
2. Перезапустите приложения или wrapper, которые встраивают OpenClaw, например локальные панели, редакторы, app-server helpers или долго работающие оболочки openclaw logs --follow.
3. Повторно выполните openclaw gateway status --deep или openclaw doctor --deep и убедитесь, что устаревший PID клиента исчез.

Не заставляйте более старый Gateway принимать более новый несовместимый протокол. Повышения версии протокола защищают wire contract; восстановление после rollback — это задача очистки процессов/версий.

Skill symlink пропущен как выход за пределы пути

Используйте это, когда логи содержат:

Skipping escaped skill path outside its configured root: ... reason=symlink-escape

OpenClaw рассматривает каждый корень skill как границу containment. Symlink внутри ~/.agents/skills, <workspace>/.agents/skills, <workspace>/skills или ~/.openclaw/skills пропускается, когда его реальная цель разрешается за пределами этого корня, если цель не является явно доверенной.

Проверьте ссылку:

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

Если цель намеренная, настройте и прямой корень skill, и разрешенную цель symlink:

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

Затем начните новую сессию или дождитесь обновления skills watcher. Перезапустите gateway, если работающий процесс был запущен до изменения конфигурации.

Не используйте широкие цели, такие как ~, / или целую синхронизируемую папку проекта. Ограничивайте allowSymlinkTargets реальным корнем skill, который содержит доверенные каталоги SKILL.md.

Если Skill Workshop apply также должен записывать через эти доверенные symlink-пути workspace skill, включите skills.workshop.allowSymlinkTargetWrites. Оставляйте это отключенным для общих корней skill только для чтения.

Связано:

• Конфигурация Skills
• Примеры конфигурации

Anthropic 429: требуется extra usage для длинного контекста

Используйте это, когда логи/ошибки содержат: HTTP 429: rate_limit_error: Extra usage is required for long context requests.

openclaw logs --followopenclaw models statusopenclaw config get agents.defaults.models

Ищите:

• Выбранная модель Anthropic — GA-capable модель Claude 4.x с 1M, или у модели есть legacy params.context1m: true.
• Текущие учетные данные Anthropic не подходят для использования длинного контекста.
• Запросы падают только в длинных сессиях/запусках модели, которым нужен путь контекста 1M.

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

Связано:

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

Ответы upstream 403 blocked

Используйте это, когда upstream LLM provider возвращает общий 403, например Your request was blocked.

Не предполагайте, что это всегда проблема конфигурации OpenClaw. Ответ может приходить от upstream security layer, например CDN, WAF, правила bot-management или reverse proxy перед OpenAI-compatible endpoint.

openclaw statusopenclaw gateway statusopenclaw logs --follow

Ищите:

• несколько моделей у одного provider падают одинаковым образом
• HTML или общий security text вместо нормальной ошибки provider API
• security events на стороне provider в то же время запроса
• маленький прямой probe через curl успешен, а обычные SDK-shaped requests падают

Сначала исправьте фильтрацию на стороне provider, когда доказательства указывают на блокировку WAF/CDN. Предпочитайте узко ограниченное правило allow или skip для API path, который использует OpenClaw, и избегайте отключения защиты для всего сайта.

Связано:

• OpenAI-compatible endpoints
• Конфигурация provider
• Логи

Локальный OpenAI-compatible backend проходит прямые probes, но agent runs падают

Используйте это, когда:

• curl ... /v1/models работает
• крошечные прямые вызовы /v1/chat/completions работают
• запуски моделей OpenClaw падают только на обычных agent turns

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 падают только на больших prompts
• ошибки model_not_found или 404, хотя прямой /v1/chat/completions работает с тем же bare model id
• ошибки backend о том, что messages[].content ожидает строку
• периодические предупреждения incomplete turn detected ... stopReason=stop payloads=0 с OpenAI-compatible local backend
• сбои backend, которые появляются только с большими prompt-token counts или полными agent runtime prompts

Связано:

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

Нет ответов

Если каналы работают, но никто не отвечает, проверьте маршрутизацию и политики, прежде чем что-либо переподключать.

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

Ищите:

• Ожидание сопряжения для отправителей DM.
• Ограничение упоминаниями в группах (requireMention, mentionPatterns).
• Несоответствия allowlist канала/группы.

Типичные признаки:

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

Связанные материалы:

• Устранение неполадок каналов
• Группы
• Сопряжение

Подключение пользовательского интерфейса управления Dashboard

Если Dashboard/пользовательский интерфейс управления не подключается, проверьте URL, режим аутентификации и предположения о безопасном контексте.

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

Ищите:

• Правильный URL проверки и URL Dashboard.
• Несоответствие режима аутентификации/токена между клиентом и gateway.
• Использование HTTP там, где требуется идентификация устройства.

Если локальный браузер не может подключиться к 127.0.0.1:18789 после обновления, сначала восстановите локальную службу Gateway и убедитесь, что она отдает Dashboard:

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

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

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

Используйте error.details.code из неудачного ответа connect, чтобы выбрать следующее действие:

Проверка миграции аутентификации устройства v2:

openclaw --versionopenclaw doctoropenclaw gateway status

Если журналы показывают ошибки nonce/подписи, обновите подключающийся клиент и проверьте его:

Если openclaw devices rotate / revoke / remove неожиданно отклоняется:

• сеансы токенов сопряженных устройств могут управлять только своим собственным устройством, если у вызывающей стороны также нет operator.admin
• openclaw devices rotate --scope ... может запрашивать только операторские области доступа, которые уже есть у сеанса вызывающей стороны

Связанные материалы:

• Конфигурация (режимы аутентификации gateway)
• Control UI
• Устройства
• Удаленный доступ
• Аутентификация доверенного прокси

Служба Gateway не запущена

Используйте это, когда служба установлена, но процесс не остается запущенным.

openclaw gateway statusopenclaw statusopenclaw logs --followopenclaw doctoropenclaw gateway status --deep   # also scan system-level services

Ищите:

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

Связанные материалы:

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

Gateway на macOS беззвучно перестает отвечать, а затем возобновляет работу, когда вы открываете Dashboard

Используйте это, когда каналы (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 увеличивается в течение дня, но в ~/Library/Logs/openclaw/gateway.log нет соответствующей строки received SIG*; shutting down: корректные остановки пишут сигнал в журнал; временные сбои этого не делают.

Что делать:

1. Обновите Gateway, если используете выпуск до 2026.5.26. После обновления будущие ошибки ENETDOWN будут записываться как предупреждения, а не завершать процесс.

2. Сократите активность maintenance sleep на Mac mini / настольных хостах, которые должны работать как постоянно включенные серверы:

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

   Это значительно уменьшает, но не устраняет полностью базовый сбой драйвера. Система все равно может выполнять некоторые maintenance sleep для TCP keepalive и обслуживания mDNS независимо от этих флагов.

3. Добавьте сторожевой механизм доступности, чтобы будущая серия сбоев, остановленная launchd, быстро обнаруживалась:

   # Example launchd-aware liveness check, suitable for a 5-minute cron or 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

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.
• Счетчики памяти Linux cgroup, когда 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: близки к лимиту кучи → снизьте нагрузку от prompts/сессий, уменьшите параллельную работу или увеличьте лимит кучи Node только после подтверждения, что такая рабочая нагрузка ожидаема.
• Memory pressure: critical/rss_growth → память быстро выросла в пределах одного окна выборки. Проверьте последние журналы на крупный импорт, неконтролируемый вывод инструмента, повторяющиеся повторы или пакет поставленных в очередь задач агента.
• Критическое давление памяти появляется в журналах, но пакет отсутствует → это поведение по умолчанию. Установите diagnostics.memoryPressureSnapshot: true, чтобы при будущих событиях критического давления памяти записывать пред-OOM пакет стабильности.

Пакет стабильности не содержит полезной нагрузки. Он включает операционные свидетельства по памяти и отредактированные относительные пути файлов, но не текст сообщений, тела webhook, учетные данные, токены, cookies или сырые идентификаторы сессий. Прикладывайте экспорт диагностики к отчетам об ошибках вместо копирования сырых журналов.

Связано:

• Состояние 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, отсутствующим scopes или неразрешенным ссылкам auth.

Типичные признаки:

• SSH tunnel failed to start; falling back to direct probes. → настройка SSH не удалась, но команда все равно попробовала прямые настроенные/loopback цели.
• multiple reachable gateway identities detected → ответили разные Gateway, или OpenClaw не смог доказать, что достижимые цели являются одним и тем же Gateway. SSH-туннель, proxy URL или настроенный удаленный URL к тому же Gateway считается одним Gateway с несколькими транспортами, даже если порты транспортов различаются.
• Read-probe diagnostics are limited by gateway scopes (missing operator.read) → подключение сработало, но подробный RPC ограничен scope; свяжите идентификатор устройства или используйте учетные данные с 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 ответил, но этому клиенту все еще требуется pairing/approval перед обычным операторским доступом.
• Текст предупреждения о неразрешенных gateway.auth.* / gateway.remote.* SecretRef → материал auth был недоступен в этом пути команды для неудачной цели.

Связано:

• Gateway
• Несколько Gateway на одном хосте
• Удаленный доступ

Канал подключен, но сообщения не проходят

Если состояние канала подключено, но поток сообщений не работает, сосредоточьтесь на policy, разрешениях и правилах доставки, специфичных для канала.

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

Ищите:

• Policy для DM (pairing, allowlist, open, disabled).
• Allowlist групп и требования mention.
• Отсутствующие разрешения/scopes API канала.

Типичные признаки:

• mention required → сообщение проигнорировано policy упоминаний в группе.
• pairing / следы ожидающего approval → отправитель не одобрен.
• missing_scope, not_in_channel, Forbidden, 401/403 → проблема auth/разрешений канала.

Связано:

• Устранение неполадок каналов
• 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 сопряжен, инструмент не работает

Если узел сопряжен, но инструменты не работают, изолируйте состояние переднего плана, разрешений и одобрений.

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

Проверьте:

• Node онлайн с ожидаемыми возможностями.
• Разрешения ОС для камеры, микрофона, местоположения и экрана.
• Состояние одобрений exec и allowlist.

Распространенные сигнатуры:

• NODE_BACKGROUND_UNAVAILABLE → приложение узла должно быть на переднем плане.
• *_PERMISSION_REQUIRED / LOCATION_PERMISSION_REQUIRED → отсутствует разрешение ОС.
• SYSTEM_RUN_DENIED: approval required → ожидается одобрение exec.
• SYSTEM_RUN_DENIED: allowlist miss → команда заблокирована allowlist.

Связанные разделы:

• Одобрения exec
• Устранение неполадок Node
• Nodes

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

Используйте это, когда действия инструмента браузера не выполняются, хотя сам 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

Связанные разделы:

• Аутентификация
• Фоновый exec и инструмент процесса
• Сопряжение, управляемое Gateway

Связанные разделы

• Doctor
• FAQ
• Runbook Gateway