Справочник по ошибкам OpenClaw: решение 20 типичных проблем (2026)

Кратко

При создании AI Agent на OpenClaw страшны не сложные настройки, а непонятные сообщения об ошибках без направления для диагностики. В этой статье собраны 20 самых частых ошибок OpenClaw, сгруппированных по пяти категориям: подключение API, конфигурация модели, права и безопасность, производительность и ресурсы, интеграция с платформами. Для каждой ошибки — анализ причины и пошаговое решение. В конце статьи — таблица быстрой справки: одного взгляда достаточно, чтобы понять, что делать.

Содержание

• Общий подход к диагностике
• Категория 1: Ошибки подключения API
• Категория 2: Ошибки конфигурации модели
• Категория 3: Ошибки прав и безопасности
• Категория 4: Ошибки производительности и ресурсов
• Категория 5: Ошибки интеграции с платформами
• Таблица быстрой справки: 20 ошибок — решение в одну строку
• Профилактика: как уменьшить количество ошибок
• Часто задаваемые вопросы (FAQ)
• Итоги

Общий подход к диагностике

Прежде чем разбирать каждую ошибку по отдельности, сформируем универсальную схему диагностики. 90% ошибок OpenClaw можно локализовать за три шага:

Шаг 1: Прочитайте само сообщение об ошибке. Ошибки OpenClaw обычно прямо сообщают, что пошло не так — model not found, 401 unauthorized, timeout. Не спешите искать в интернете, сначала внимательно прочитайте полное сообщение.

Шаг 2: Проверьте три ключевых параметра. Основная конфигурация OpenClaw — это три параметра: base_url (адрес API), API Key (ключ аутентификации), model (название модели). 80% ошибок связаны с одним из этих трёх.

Шаг 3: Изолируйте проблему. Попробуйте другую модель — если остальные работают, проблема в конкретной модели. Попробуйте другой API Key — если новый работает, проблема в старом ключе. Последовательное сужение диапазона гораздо эффективнее слепых предположений.

Теперь разберём каждую категорию.

---

Категория 1: Ошибки подключения API

Суть этих ошибок — OpenClaw не может установить соединение с API-сервером или соединение установлено, но аутентификация не прошла.

1. API Key invalid / 401 Unauthorized

Сообщение об ошибке:

Error: 401 Unauthorized - Invalid API Key

Причина: Аутентификация API Key не прошла, сервер отклонил запрос.

Решение:

1. Проверьте целостность ключа: откройте конфигурационный файл в ~/.openclaw/, убедитесь, что API Key не обрезан и не содержит лишних пробелов. При копировании через буфер обмена легко захватить пробел в начале или конце
2. Убедитесь, что ключ и base_url совпадают: самая частая ловушка — указан адрес Ofox с ключом от OpenAI, или наоборот. Ключ и адрес должны принадлежать одной платформе
3. Проверьте статус ключа: войдите в панель API-провайдера, убедитесь, что ключ не отозван и не истёк
4. Перегенерируйте ключ: если не уверены в валидности — просто создайте новый ключ в панели управления

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

2. Connection timeout

Сообщение об ошибке:

Error: connect ETIMEDOUT
Error: request to https://api.openai.com/v1/chat/completions failed, reason: connect ETIMEDOUT

Причина: OpenClaw не может подключиться к API-серверу. Часто возникает при прямом подключении из Китая к зарубежным API-адресам (api.openai.com, api.anthropic.com).

Решение:

1. Используйте API-платформу с узлами в Китае: при прямом подключении к зарубежным API-адресам это практически неизбежно. Ofox и другие агрегаторы имеют узлы ускорения в Китае — достаточно заменить base_url на адрес платформы
2. Проверьте статус API-провайдера: даже отечественные платформы могут временно сбоить. Проверьте страницу статуса провайдера
3. Проверьте локальную сеть: убедитесь, что ваша сеть имеет доступ в интернет. Корпоративная сеть может блокировать доступ файрволом
4. Увеличьте таймаут: в конфигурации OpenClaw увеличьте значение timeout (по умолчанию 30 секунд), чтобы дать больше времени медленной сети

3. Rate limit exceeded / 429

Сообщение об ошибке:

Error: 429 Too Many Requests - Rate limit exceeded

Причина: Частота запросов превысила лимит, установленный API-провайдером. Бесплатные и начальные платные тарифы обычно имеют строгие ограничения.

Решение:

1. Подождите и повторите: 429 обычно временная ошибка, подождите 1–2 минуты и попробуйте снова
2. Снизьте параллелизм: если работают несколько Agent одновременно, ограничьте число параллельных запросов в конфигурации
3. Повысьте тариф: провайдеры устанавливают разные лимиты скорости по тарифам; пополнение или переход на более высокий тариф расширяет лимиты
4. Используйте агрегатор: платформы вроде Ofox имеют многоузловую балансировку нагрузки на бэкенде, фактический лимит скорости выше, чем при прямом подключении

4. SSL/TLS Certificate Error

Сообщение об ошибке:

Error: unable to verify the first certificate
Error: self signed certificate in certificate chain

Причина: Ошибка проверки SSL-сертификата, обычно возникает в корпоративных сетях — прокси или шлюз безопасности подменяет оригинальный сертификат.

Решение:

1. Добавьте корневой сертификат компании: внесите корневой CA-сертификат компании в список доверенных сертификатов операционной системы
2. Установите переменную окружения:

   export NODE_EXTRA_CA_CERTS=/path/to/company-root-ca.pem

3. Обратитесь в IT-отдел: если не знаете сетевую политику компании, попросите IT предоставить правильный файл сертификата
4. Временное решение для разработки:

   export NODE_TLS_REJECT_UNAUTHORIZED=0

   ⚠️ Только для локальной разработки и тестирования, в продуктивной среде использовать нельзя

---

Категория 2: Ошибки конфигурации модели

Конфигурация модели — самый проблемный участок в OpenClaw. Ошибка в одной букве названия модели или выбор неподдерживаемой модели приводят к ошибке.

5. «There’s an issue with the selected model»

Сообщение об ошибке:

There's an issue with the selected model (claude-sonnet-4-6). It may not exist or you may not have access to it. Run /model to pick a different model.

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

Решение:

Проверяйте в следующем порядке:

1. Выполните /model: переключитесь на другую модель (например, GPT-4o или DeepSeek V3.2), чтобы понять, проблема глобальная или локальная
2. Проверьте баланс: посмотрите в панели провайдера, не равен ли баланс нулю
3. Сверьте название модели: убедитесь, что поле model точно совпадает с ID модели у провайдера (таблица соответствий ниже)
4. Проверьте base_url: при использовании агрегатора нужен адрес платформы, а не официальный адрес API
5. Проверьте сетевую доступность: выполните curl к вашему base_url, чтобы убедиться в доступности

Таблица соответствия популярных названий моделей:

6. Model not found

Сообщение об ошибке:

Error: The model 'xxx' does not exist or you do not have access to it.

Причина: API-провайдер явно сообщает: запрошенный ID модели не существует. В отличие от ошибки #5, это сообщение приходит от сервера API.

Решение:

1. Проверьте список моделей в документации провайдера: ID моделей не полностью совпадают на разных платформах. Например, у Claude официально — claude-sonnet-4-6-20260514, а на платформе Ofox достаточно claude-sonnet-4-6
2. Проверьте, не снята ли модель: AI-модели обновляются быстро, старые версии могут быть сняты. GPT-4 Turbo, Claude 3.5 и подобные уже заменены новыми версиями
3. Регистр и орфография: ID модели строго чувствителен к регистру и написанию

7. Context length exceeded

Сообщение об ошибке:

Error: This model's maximum context length is 200000 tokens. However, your messages resulted in 245891 tokens.

Причина: Общее число токенов истории диалогов + системного промпта превысило лимит контекстного окна модели. Agent в OpenClaw накапливает большой контекст (память, история диалогов, результаты вызовов инструментов), что легко приводит к превышению.

Решение:

1. Очистите диалог: выполните /clear для сброса истории текущей сессии
2. Сократите системный промпт: если определение роли Agent слишком длинное, оставьте только ключевую информацию
3. Переключитесь на модель с большим контекстом: Gemini 3.1 Pro — до 2 млн токенов, Claude Opus/Sonnet — до 1 млн токенов
4. Настройте стратегию памяти: установите более агрессивное сжатие истории в конфигурации OpenClaw для своевременной архивации старых диалогов

8. Invalid request format / 400 Bad Request

Сообщение об ошибке:

Error: 400 Bad Request - Invalid request body
Error: Unsupported parameter: 'tools'

Причина: Тело запроса OpenClaw к API содержит параметры, не поддерживаемые целевым провайдером. Разные провайдеры по-разному совместимы с протоколом OpenAI.

Решение:

1. Проверьте дополнительные параметры: если вы вручную добавили temperature, top_p, tools и другие параметры, убедитесь, что целевой провайдер их поддерживает
2. Удалите несовместимые параметры: оставьте в конфигурации только три ключевых поля — base_url, api_key, model
3. Используйте платформу с хорошей совместимостью: Ofox и другие агрегаторы автоматически обрабатывают различия параметров между провайдерами, снижая проблемы совместимости

---

Категория 3: Ошибки прав и безопасности

9. Permission denied (системный уровень)

Сообщение об ошибке:

Error: EACCES: permission denied, open '/etc/openclaw/config'
Error: Permission denied (os error 13)

Причина: OpenClaw пытается читать/записывать файл или каталог, к которому нет прав доступа. Часто встречается в Linux/Mac при неверных правах на файлы конфигурации.

Решение:

1. Проверьте права каталога конфигурации:

   ls -la ~/.openclaw/

   Убедитесь, что текущий пользователь имеет права чтения и записи
2. Исправьте права:

   chmod -R 755 ~/.openclaw/
   chown -R $(whoami) ~/.openclaw/

3. Не запускайте через sudo: установка через sudo может привести к тому, что файлы конфигурации будут принадлежать root, и обычный пользователь получит ошибку прав

10. Permission denied (уровень платформы)

Сообщение об ошибке:

Error: Bot does not have permission to send messages in this channel
Error: Missing required scope: messages:write

Причина: При интеграции OpenClaw с Feishu, DingTalk, Telegram и другими платформами бот не получил необходимых API-прав.

Решение:

1. Проверьте права бота: в панели разработчика платформы убедитесь, что бот имеет нужные права (отправка сообщений, чтение сообщений, загрузка файлов и т.д.)
2. Переавторизуйте: на некоторых платформах после изменения прав нужно переустановить/переавторизовать бота
3. Проверьте настройки группы: в некоторых группах ботам запрещено отправлять сообщения — обратитесь к администратору

11. Insufficient quota / balance

Сообщение об ошибке:

Error: You exceeded your current quota. Please check your plan and billing details.
Error: Insufficient balance

Причина: Баланс API-аккаунта равен нулю или бесплатный лимит исчерпан.

Решение:

1. Пополните баланс: в панели API-провайдера. Ofox поддерживает оплату через Alipay/WeChat, зачисление за несколько минут
2. Настройте уведомления о низком балансе: большинство платформ поддерживают email/SMS-уведомления при низком балансе, чтобы избежать внезапных прерываний
3. Временно переключитесь на бесплатную модель: у DeepSeek есть стартовый баланс при регистрации, у Google Gemini — бесплатный тариф
4. Проверьте утечку токенов: если баланс расходуется аномально быстро, возможно, API Key утёк. Немедленно отзовите старый ключ и создайте новый

---

Категория 4: Ошибки производительности и ресурсов

12. Response timeout / 504

Сообщение об ошибке:

Error: 504 Gateway Timeout
Error: Response timeout after 30000ms

Причина: В отличие от таймаута подключения (ошибка #2), здесь соединение установлено, но модель обрабатывает запрос слишком медленно и не укладывается в таймаут. Большие модели (Opus, GPT-5.4 Thinking) при сложных задачах часто провоцируют эту ошибку.

Решение:

1. Увеличьте таймаут: в конфигурации OpenClaw установите timeout на 60–120 секунд
2. Включите потоковую передачу: убедитесь, что stream: true — в потоковом режиме таймауты случаются реже
3. Упростите задачу: разбейте сложную задачу на более мелкие шаги, чтобы уменьшить объём обработки одного запроса
4. Используйте лёгкую модель: для простых задач GPT-4o-mini или Gemini Flash отвечают гораздо быстрее

13. Memory / Storage errors

Сообщение об ошибке:

Error: ENOSPC: no space left on device
Error: JavaScript heap out of memory

Причина: Нехватка места на диске или переполнение памяти Node.js. При длительной работе OpenClaw файлы логов и данные памяти постоянно растут.

Решение:

1. Очистите диск: проверьте размер файлов логов, удалите устаревшие логи и временные файлы
2. Увеличьте лимит памяти Node.js:

   export NODE_OPTIONS="--max-old-space-size=4096"

3. Периодически архивируйте память: система памяти OpenClaw сжимает данные автоматически, но после длительной работы ручная очистка эффективнее
4. При облачном развёртывании: выбирайте достаточный объём диска и памяти

14. Agent stuck in loop

Сообщение об ошибке:

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

Причина: Agent столкнулся с невыполнимой задачей, но не имеет механизма выхода и зацикливается в бесконечных повторах. Типичные причины: расплывчатое описание задачи, сбой вызова инструмента при отсутствии логики отказа, недостаточные возможности модели для данной задачи.

Решение:

1. Немедленно прервите: Ctrl+C для остановки текущей задачи
2. Установите максимум итераций: добавьте max_iterations в конфигурацию (рекомендуется 20–50), задача автоматически завершится при превышении
3. Установите бюджет токенов: ограничьте максимальный расход токенов на одну задачу
4. Уточните описание задачи: дайте Agent более точные инструкции и условия выхода — «если после трёх попыток задача не выполнена, остановись и сообщи причину»
5. Повысьте уровень модели: бюджетные модели (GPT-4o-mini) чаще зацикливаются на сложных задачах; переключение на Claude Sonnet или Opus обычно решает проблему

15. JSON parse error in response

Сообщение об ошибке:

Error: Unexpected token '<' at position 0
SyntaxError: Unexpected end of JSON input

Причина: API вернул не JSON. Unexpected token '<' — вернулась HTML-страница (обычно страница защиты Cloudflare, ошибка 502 или страница входа). Unexpected end — ответ обрезан.

Решение:

1. Повторите запрос: в большинстве случаев это временная сетевая нестабильность или блокировка CDN, повтор помогает
2. Проверьте base_url: убедитесь, что в URL нет лишних путей. Правильный формат обычно https://api.xxx.com/v1, не добавляйте /chat/completions
3. Исключите сетевое промежуточное ПО: прокси/файрвол корпоративной сети может модифицировать ответ API. Попробуйте прямое подключение (без прокси) для сравнения
4. Просмотрите полный ответ: включите режим debug-логирования OpenClaw, посмотрите сырой ответ API для быстрой локализации проблемного звена

---

Категория 5: Ошибки интеграции с платформами

16. Channel / Platform connection failed

Сообщение об ошибке:

Error: Failed to connect to Telegram
Error: Feishu webhook verification failed
Error: Discord bot token invalid

Причина: OpenClaw не может подключиться к коммуникационной платформе (Feishu, DingTalk, Telegram, Discord и др.) — обычно проблема в конфигурации на стороне платформы.

Решение:

1. Сверьте учётные данные платформы: Bot Token, Webhook URL, App ID/Secret — убедитесь, что скопированы актуальные версии из панели платформы
2. Проверьте доступность Webhook: если OpenClaw развёрнут во внутренней сети, Webhook-коллбэки от Feishu/DingTalk могут не достичь вашего сервера. Нужен туннель или развёртывание на публичном сервере
3. Проверьте статус бота: в панели разработчика убедитесь, что бот в статусе «Опубликован», а не «В разработке»
4. Проверьте занятость порта: Webhook-сервис OpenClaw слушает определённый порт, убедитесь, что он не занят другим процессом

17. Search provider configuration error

Сообщение об ошибке:

Error: Search provider 'tavily' is not configured
Error: TAVILY_API_KEY is not set

Причина: Функция интернет-поиска OpenClaw требует отдельной настройки поискового провайдера (Tavily, Google Search и др.). Если провайдер выбран, но ключ не указан — ошибка.

Решение:

1. Заполните API Key поиска: зарегистрируйтесь на Tavily, получите API Key и внесите в конфигурацию OpenClaw
2. Или отключите поиск: если Agent не нуждается в интернет-поиске, установите Search Provider в none или оставьте пустым
3. Смените поискового провайдера: если проблемы с Tavily — переключитесь на Google Custom Search или Bing Search

18. Webhook signature verification failed

Сообщение об ошибке:

Error: Invalid signature
Error: Webhook verification token mismatch

Причина: Feishu, DingTalk и другие платформы проверяют подпись Webhook-запросов. Несовпадение подписи означает неверную конфигурацию ключа верификации.

Решение:

1. Сверьте Verification Token: скопируйте актуальный Verification Token или Encrypt Key из панели платформы в конфигурацию OpenClaw
2. Проверьте настройки шифрования: некоторые платформы поддерживают зашифрованный и открытый режимы — конфигурация OpenClaw должна совпадать с настройками платформы
3. Внимание к кодировке: при копировании токена не захватите лишние переводы строк или пробелы

19. File upload / download failed

Сообщение об ошибке:

Error: File size exceeds limit
Error: Unsupported file type
Error: Failed to download file from URL

Причина: OpenClaw столкнулся с ограничениями при загрузке/скачивании файлов — файл слишком большой, формат не поддерживается, URL для скачивания недоступен.

Решение:

1. Проверьте лимит размера: разные платформы имеют разные ограничения (Feishu — 25 МБ, Telegram — 50 МБ и т.д.), сожмите или разделите большие файлы
2. Проверьте формат файла: уточните список поддерживаемых типов файлов у платформы
3. Доступность URL для скачивания: если OpenClaw должен скачать внешний файл, убедитесь, что URL доступен с сервера

20. Multi-Agent communication error

Сообщение об ошибке:

Error: Agent 'assistant-2' not found
Error: Failed to route message between agents
Error: Shared memory access conflict

Причина: В конфигурации с несколькими Agent возникла проблема связи между ними или конфликт общих ресурсов.

Решение:

1. Проверьте имена Agent: убедитесь, что все имена Agent в конфигурации уникальны и ссылки корректны
2. Проверьте конфигурацию общей памяти: одновременная запись нескольких Agent в общую память может вызвать конфликт — настройте правильную стратегию чтения/записи
3. Упростите архитектуру Agent: сначала отладьте процесс на одном Agent, после подтверждения работоспособности постепенно добавляйте новых

---

Таблица быстрой справки: 20 ошибок — решение в одну строку

---

Профилактика: как уменьшить количество ошибок

Лучше предотвратить ошибку, чем каждый раз её диагностировать:

На этапе настройки

• Используйте openclaw onboard для пошаговой настройки: не редактируйте конфигурационный файл вручную — мастер автоматически проверяет формат
• Выбирайте API-платформу с хорошей совместимостью: Ofox и другие агрегаторы поддерживают стандартный протокол OpenAI, проблем совместимости меньше, чем при прямом подключении к нишевым провайдерам
• Настройте резервную модель: установите fallback-модель, чтобы при сбое основной происходило автоматическое переключение

На этапе эксплуатации

• Настройте уведомления о балансе: автоматическое уведомление при низком балансе, чтобы избежать внезапных прерываний
• Установите бюджет токенов: лимит на каждую задачу предотвращает зацикливание Agent
• Регулярно проверяйте логи: привычка просматривать логи OpenClaw помогает заметить предупреждения до того, как они станут ошибками
• Обновляйтесь: сообщество OpenClaw активно обновляет продукт, новые версии исправляют известные баги и проблемы совместимости

На архитектурном уровне

• Используйте агрегатор для единого управления: вместо регистрации у 5 API-провайдеров используйте одну платформу-агрегатор (например, Ofox) для единого управления ключами и биллингом — при проблеме диагностировать нужно только одно место
• Стратегия разделения моделей по уровням: повседневные задачи — Sonnet/GPT-4o, сложные — Opus/GPT-5.4 Thinking, простые — Flash/mini — сокращает ненужный расход ресурсов

---

Часто задаваемые вопросы (FAQ)

Что делать, если не понимаю сообщение об ошибке на английском?

Скопируйте полное сообщение об ошибке любому AI-помощнику (ChatGPT, Claude, DeepSeek) и попросите объяснить причину и решение на русском. Сообщения об ошибках OpenClaw обычно содержат достаточно ключевых слов для быстрой идентификации проблемы.

Есть ли у OpenClaw официальный канал обратной связи?

Да. Основной канал — GitHub Issues: github.com/openclaw/openclaw/issues. При создании Issue приложите полное сообщение об ошибке, версию OpenClaw, информацию об ОС — сообщество отвечает быстро. Также есть Discord-сообщество для обсуждений в реальном времени.

Ошибка появилась один раз, потом всё заработало — стоит ли волноваться?

Единичные ошибки (таймаут из-за сетевой нестабильности, временный сбой API) обычно не требуют особого внимания. Но если одна и та же ошибка повторяется, нужно искать корневую причину. Рекомендуется включить логирование OpenClaw для ретроспективного анализа.

Несколько ошибок появляются одновременно — как диагностировать?

Начинайте с самой базовой ошибки — обычно первая ошибка является корневой причиной, остальные — цепная реакция. Например, недействительный API Key (401) может повлечь за собой недоступность модели, сбой поиска и серию других ошибок. Исправление 401, скорее всего, устранит и остальные.

С платформой Ofox эти ошибки всё равно будут появляться?

Их станет значительно меньше, но полностью избежать нельзя. Ofox автоматически решает проблемы совместимости API, ускорения сети в Китае и переключения между моделями — поэтому таймауты подключения и несовместимость протоколов практически не встречаются. Но нулевой баланс, ошибка в названии модели, конфигурация прав — это пользовательские проблемы, которые нужно решать самостоятельно на любой платформе.

---

Итоги

Ошибок в OpenClaw немало по видам, но все они сводятся к пяти категориям: подключение API, конфигурация модели, права и безопасность, производительность и ресурсы, интеграция с платформами. Запомните трёхшаговый метод диагностики — прочитайте сообщение об ошибке, проверьте три ключевых параметра (base_url / Key / model), изолируйте проблему — и большинство проблем решится за несколько минут.

Чтобы уменьшить количество ошибок на корневом уровне, рекомендуем:

1. Используйте Ofox или аналогичный агрегатор для единого управления API — автоматическое решение проблем подключения и совместимости
2. Настройте fallback-модель — автоматическое переключение при сбое основной
3. Установите бюджет токенов и уведомления о балансе — предотвращение неконтролируемых расходов и прерываний сервиса

При неразрешимых проблемах — приходите с полным сообщением об ошибке на GitHub Issues OpenClaw, сообщество поможет.

Справочные материалы

• Официальная документация OpenClaw — устранение неполадок — официальное руководство по диагностике
• GitHub Issues OpenClaw — обсуждения проблем в сообществе
• Документация Ofox AI API — руководство по подключению API и коды ошибок
• Руководство по интеграции Ofox + OpenClaw — специализированная инструкция для OpenClaw
• Руководство по API и настройке моделей OpenClaw — полное руководство по использованию в России