Ошибки OpenClaw: 7 групп + что проверять в каждой

Короткий ответ

В разборе на сайте семьдесят отдельных ошибок, но лечатся они не семьюдесятью способами. Почти всё укладывается в семь групп, и внутри группы порядок проверки один и тот же.

Эта страница — карта: находите свою группу по признаку, проходите проверку по порядку, а за точным текстом сообщения идёте в конкретный разбор.

ПолезноЕсли у вас есть точный текст ошибки, быстрее всего искать его целиком через поиск по сайту — разборы названы по машинному сообщению, а не по пересказу.

Правило, которое экономит больше всего времени

Прежде чем чинить, ответьте на один вопрос: что именно сломалось — установка, соединение, доступ или модель?

Три уровня, и они ломаются по-разному:

1. Программа не запускается — дело в установке и окружении. Логи агента вы даже не увидите.
2. Программа работает, но не отвечает или теряет инструменты — дело в шлюзе, соединении или сессии.
3. Программа отвечает, но неправильно — дело в модели, провайдере или правах.

Ошибка почти всегда выглядит страшнее своего уровня. «Tool not found» звучит как «сломан агент», а на деле это второй уровень: шлюз потерял соединение, и инструменты перестали регистрироваться.

1. Установка и окружение

Признак: команда не выполняется вовсе либо падает сразу после запуска. До логов дело не доходит.

Типичное: Cannot find module, npm error code ENOENT, spawn EINVAL, inappropriate ioctl for device, Failed to connect to bus, отсутствующие ассеты интерфейса.

Что проверять по порядку:

1. Версия Node. Большая часть ошибок этой группы — это несовпадение версии со сборкой пакета.
2. Глобальная установка против локальной. При глобальной части зависимостей может не оказаться — это отдельный класс Cannot find module.
3. Операционная система. Windows и Linux ломаются по-своему: на Windows это spawn EINVAL и ENOENT, на Ubuntu — ioctl и systemd.
4. Архитектура процессора. Сборка под Apple Silicon на Intel-маке не запустится, и сообщение об этом звучит обманчиво общо.

Конкретные разборы:

• Cannot find module при глобальной установке
• npm error code ENOENT на Windows
• spawn EINVAL при установке плагинов на Windows
• inappropriate ioctl for device на Ubuntu 24.04
• Failed to connect to bus при установке systemd-сервиса
• «приложение не поддерживается на этом Mac»
• Missing Control UI assets

Общая профилактика — пошаговая установка.

2. Авторизация и ключи

Признак: код 401, слова bearer, credential, authentication в сообщении. Программа работает, но провайдер её не пускает.

Что проверять по порядку:

1. Тип ключа. Ключ от подписки и ключ API — разные вещи, и подписочные учётные данные в агенте не работают. Это причина ошибки «This credential is only authorized for use with Claude Code».
2. Срок жизни токена. Там, где авторизация идёт по OAuth, токен живёт ограниченное время. Настроили один раз и забыли — через час всё встало.
3. Баланс. Ошибка биллинга приходит как ошибка провайдера и легко читается как поломка агента.
4. Куда подставился ключ. Переменная окружения, объявленная в профиле оболочки, до приложения, запущенного из интерфейса, не доходит.

Конкретные разборы:

• 401 Invalid bearer token через Claude Code OAuth
• HTTP 401 при аутентификации Anthropic OAuth
• 401 missing authentication header
• This credential is only authorized for use with Claude Code
• API provider returned a billing error

Если ключа ещё нет или он перестал работать из России — десять способов получить API.

3. Шлюз и соединение

Признак: агент запущен, но интерфейс не открывается, соединение рвётся, появляются слова gateway, pairing, disconnected, коды WebSocket 1005/1006/1008.

Это самая коварная группа: агент формально жив, и вы ищете проблему не там.

Что проверять по порядку:

1. Подтверждение устройства. pairing required — не ошибка, а незавершённая процедура: устройство не подтверждено.
2. Порт занят. Конфликт портов даёт «UI chat not opening» и выглядит как сломанный интерфейс.
3. Одновременно запущенные копии. Второй процесс, оставшийся от прошлого запуска, отбирает шлюз у первого.
4. Сеть между шлюзом и клиентом, если они на разных машинах.

Конкретные разборы:

• gateway closed (1006): no reason
• gateway connect failed: pairing required
• disconnected (1008): pairing required
• restart requested (reason=none)
• UI chat not opening: конфликт портов

4. Инструменты пропали

Признак: агент отвечает текстом там, где должен был что-то сделать. Либо прямо Tool not found.

Что проверять по порядку:

1. Видит ли агент инструменты вообще. Если пропали разом exec, read и write — это не про инструменты, это шлюз потерял соединение. Возвращайтесь к группе 3.
2. Версия. У этой группы самая явная привязка к конкретным сборкам: часть ошибок жила ровно между двумя релизами.
3. Формат вызова у провайдера. Некоторые API не поддерживают вызов инструментов в том виде, в каком его шлёт агент.
4. Умеет ли модель инструменты вообще. На локальных моделях это причина номер один: без поддержки вызова модель отвечает текстом. Какие модели умеют.

Конкретные разборы:

• Tool not found в 2026.3.11–2026.3.12
• Tool not found: exec/read/write пропадают через несколько минут
• Отсутствие инструментов exec и browser
• Gateway running unreachable, no exec/read/write tools
• Вызов инструментов не работает с api: openai-completions

Если инструменты подключаются через MCP — отдельный список причин в восьми ошибках подключения.

5. Контекст и память

Признак: агент отвечал и перестал; ответы обрываются; процесс съедает память и падает.

Что проверять по порядку:

1. Размер сессии. Длинные переписки в мессенджерах растут до мегабайтов, и в какой-то момент история перестаёт помещаться в окно модели.
2. Окно контекста самой модели. У локальных моделей по умолчанию оно бывает меньше того минимума, который агенту нужен для работы.
3. Память процесса. JavaScript heap out of memory — это уже не про модель, а про Node: процессу не хватило оперативной памяти.
4. Механизм сброса памяти — если он срабатывает через раз, история копится незаметно.

Конкретные разборы:

• Context overflow: сессии Telegram растут до мегабайтов
• Переполнение токенов: причины и как избежать
• Model context window too small (4096 tokens)
• JavaScript heap out of memory
• memoryFlush срабатывает только через раз

Как устроена память агента и что с ней делать заранее — память и постоянный контекст.

6. Каналы и мессенджеры

Признак: агент работает, но конкретный канал молчит, отваливается или зацикливается.

Отдельная группа, потому что причина почти никогда не в агенте: ломается плагин канала либо сама платформа.

Что проверять по порядку:

1. Установлен ли плагин канала. plugin not found и plugin not available — это два разных состояния: в первом плагина нет, во втором он есть, но не загрузился.
2. Жива ли сессия платформы. Привязки WhatsApp и подобные протухают, и переподключение делается заново.
3. Не сбоит ли сама платформа. Часть ошибок Discord и Matrix — временные отказы на их стороне, и чинить у себя нечего.
4. Нет ли петли. Отправка самому себе в iMessage даёт бесконечное эхо — классика, которая выглядит как сошедший с ума агент.

Конкретные разборы:

• plugin not found: telegram
• telegram plugin not available
• No active WhatsApp Web listener
• WhatsApp linking stuck at logging in
• WebSocket 1005/1006 в Discord
• Silently lost connection to Slack
• Зацикливание эха в iMessage

7. Модель и провайдер

Признак: в сообщении фигурирует имя модели, код 400 или 422, слова schema, payload, Unknown model.

Что проверять по порядку:

1. Точное имя модели. У каждого провайдера свой каталог имён, и Unknown model — почти всегда опечатка или устаревшее имя из чужой инструкции.
2. Совместимость формата. Ошибки 400 и 422 обычно означают, что агент шлёт поле, которого этот провайдер не понимает.
3. Таймауты. «LLM request timed out» может приходить не от модели, а от внутреннего ограничения, которое не учитывает вашу настройку.
4. Локальный сервер моделей. LMStudio и подобные говорят на своём диалекте, и часть ошибок живёт именно на стыке.

Конкретные разборы:

• Unknown model: google-antigravity/claude-opus-4-6-thinking
• Unknown model: volcengine-plan/ark-code-latest
• 400 Item rs_… of type reasoning
• HTTP 422 при работе с локальной моделью QWEN
• LLM request failed: provider rejected the request schema
• LLM request timed out
• Unhandled API in mapOptionsForApi при работе с LMStudio

Что делать, если группа не подошла

Проверьте версию. Заметная часть разборов на сайте привязана к конкретным сборкам: ошибка появилась в одном релизе и ушла в следующем. Первое, что стоит сделать с необъяснимой поломкой, — посмотреть, на какой вы версии и что менялось.

Откатитесь на предыдущую версию. Если поломка появилась сразу после обновления, это самый быстрый способ отделить «сломалось у них» от «сломалось у меня».

Посмотрите логи целиком, а не последнюю строку. Настоящая причина обычно на несколько строк выше того сообщения, которое вы скопировали.

Не чините всё сразу. Меняйте по одному параметру и проверяйте. Три изменения одновременно — это три новых переменных и ни одного вывода.

ОсторожноСовет из интернета «выдать полные права» или «отключить проверки» решает симптом и создаёт проблему. Прежде чем расширять доступ, убедитесь, что дело действительно в правах — разрешения агента.

Коротко о главном

• Семьдесят разборов укладываются в семь групп, и внутри группы порядок проверки одинаков.
• Сначала определите уровень: не запускается, не отвечает или отвечает неправильно. Это отсекает шесть групп из семи.
• Пропавшие инструменты чаще всего означают проблему со шлюзом, а не с инструментами.
• Ошибки, привязанные к версии, — заметная часть списка. Версия проверяется первой.
• Расширять права как способ починки — последнее, что стоит делать, и почти всегда лишнее.

Полный список разборов — в рубрике ошибок. Если вашей нет, точный текст сообщения стоит поискать по сайту целиком.