Как пользоваться этим руководством
Найдите симптом, который наблюдаете, прочитайте причину и решение. Все 20 ошибок — реальные случаи из GitHub Issues и Reddit-тредов сообщества OpenClaw.
Ошибки установки (1-5)
1. npm install -g openclaw завершается с EACCES
Симптом: npm ERR! Error: EACCES: permission denied
Причина: npm пытается записать в системную директорию, требующую прав администратора.
Решение:
# Вариант A: изменить директорию npm (рекомендуется)
mkdir ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g openclaw
# Вариант B: использовать nvm (лучшая практика)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
nvm install 22
nvm use 22
npm install -g openclaw2. OpenClaw не запускается: command not found
Симптом: после установки команда openclaw не найдена.
Причина: директория npm global bin не в PATH.
Решение:
# Найти путь к bin
npm root -g
# Добавить в PATH (замените путь на ваш)
echo 'export PATH="/usr/local/lib/node_modules/.bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
# Проверить
which openclaw
openclaw --version3. Ошибка на Windows: 'openclaw' is not recognized
Симптом: в PowerShell или CMD команда не найдена, хотя установка прошла успешно.
Причина: PATH не обновился после установки npm пакета.
Решение:
# Найти путь
npm config get prefix
# Добавить в PATH через System Settings → Environment Variables
# Или временно в сессии:
$env:PATH += ";C:\Users\Username\AppData\Roaming\npm"
# Проверить
openclaw --version4. Error: ENOENT: no such file or directory при инициализации
Симптом: openclaw init падает с ENOENT.
Причина: нет прав на создание директории ~/.openclaw/ или путь содержит спецсимволы.
Решение:
# Создать директорию вручную
mkdir -p ~/.openclaw
# Проверить права
ls -la ~ | grep openclaw
# Если имя пользователя содержит пробелы (Windows)
openclaw init --config "C:/openclaw/config.json"5. Node.js версия несовместима
Симптом: Error: The module was compiled against a different Node.js version
Причина: OpenClaw требует Node.js 20+, установлена более старая версия.
Решение:
node --version # проверить текущую версию
# Обновить через nvm
nvm install 22
nvm use 22
nvm alias default 22
# Переустановить openclaw
npm install -g openclawОшибки конфигурации и запуска (6-10)
6. API key invalid or missing
Симптом: агент запускается, но сразу падает с ошибкой ключа.
Причина: API-ключ не установлен, неверный, или истёк.
Решение:
# Проверить текущий ключ
openclaw config get llm.apiKey
# Установить ключ
openclaw config set llm.apiKey "sk-your-key-here"
# Проверить подключение к API
openclaw doctor --check llmЕсли ключ установлен, но ошибка остаётся — проверьте баланс на сайте провайдера (OpenAI/Anthropic).
7. Агент «завис» и не отвечает
Симптом: агент запущен, но на команды не реагирует минуту и более.
Причина A: медленный ответ API (особенно в часы пик). Причина B: слишком большой контекст, обработка занимает время. Причина C: агент ожидает разрешения на действие.
Решение:
# Проверить, что агент живой
openclaw status
# Посмотреть что агент делает прямо сейчас
openclaw logs --follow
# Принудительно прервать текущую задачу
Ctrl+C # или Ctrl+Z для паузы
# Если агент завис полностью
openclaw stop --force8. Permission denied при доступе к файлам
Симптом: Error: EACCES: permission denied, open '/path/to/file'
Причина: директория не включена в список разрешённых в конфиге.
Решение:
# Проверить текущие разрешения
openclaw config get permissions.fileAccess
# Добавить нужную директорию
openclaw config set permissions.fileAccess '["~/Documents", "~/Projects", "~/Downloads"]'
# На macOS: проверить системные разрешения
# Системные настройки → Конфиденциальность → Полный доступ к диску9. Браузер не открывается / агент не видит браузер
Симптом: агент говорит «не могу открыть браузер» или зависает при попытке.
Причина A: браузерная автоматизация не настроена. Причина B: Playwright не установлен.
Решение:
# Установить браузеры для Playwright
npx playwright install chromium
# Включить браузер в конфиге
openclaw config set permissions.browser true
openclaw config set browser.default chromium
# На macOS: разрешить управление компьютером
# Системные настройки → Конфиденциальность → Универсальный доступ
# Добавить Terminal (или приложение, из которого запускаете openclaw)10. Context length exceeded
Симптом: Error: This model's maximum context length is X tokens. Your messages resulted in Y tokens.
Причина: задача или история сессии превысила лимит контекстного окна.
Решение:
# Включить компактный режим
openclaw run --compact "задача"
# Уменьшить глубину истории
openclaw config set session.historyDepth 10
# Использовать модель с бо́льшим контекстом
openclaw config set llm.model gemini-1.5-pro # 1M токеновПодробнее: Context overflow: полное руководство.
Ошибки в работе агента (11-15)
11. Агент повторяет одно действие в цикле
Симптом: агент снова и снова выполняет одно и то же действие, не двигаясь дальше.
Причина: задача сформулирована неоднозначно, или агент не получает ожидаемого результата и пытается снова.
Решение:
# Остановить агента
Ctrl+C
# Переформулировать задачу точнее
# Плохо: "обнови данные"
# Хорошо: "прочитай файл data.csv, добавь колонку 'total' как сумму A+B, сохрани как data_updated.csv"
# Добавить явный критерий завершения
openclaw run "задача. Задача считается выполненной когда файл output.txt существует и содержит не менее 100 строк."12. Агент «галлюцинирует» — придумывает несуществующие файлы или данные
Симптом: агент ссылается на файлы, которых нет, или выдаёт данные, которых не существует.
Причина: агент генерирует ответ на основе обучения, а не реальных данных.
Решение:
# Явно указать агенту проверять наличие файлов
openclaw run "ВАЖНО: прежде чем ссылаться на любой файл, проверь его существование командой ls. Задача: ..."
# Включить режим строгой проверки
openclaw config set behavior.verifyBeforeReference true
# Использовать более мощную модель для задач с данными
openclaw run --model gpt-4o "задача с данными"13. Агент не может авторизоваться на сайте
Симптом: агент пытается войти на сайт, но авторизация не проходит.
Причина A: 2FA мешает автоматизации. Причина B: сайт блокирует автоматизированные браузеры. Причина C: куки истекли.
Решение:
# Передать сессию из вашего браузера
openclaw browser import-session --from chrome
# Использовать хранилище паролей для передачи credentials
openclaw config set browser.credentialStore keychain
# Для 2FA: передать код вручную
openclaw run "зайди на site.com, когда попросит 2FA код — остановись и запроси его у меня"14. Задача выполнена неверно — агент понял не так
Симптом: агент выполнил задачу, но результат не тот, что ожидался.
Причина: задача была неоднозначно сформулирована.
Лучшие практики формулировки задач:
# Плохо (неоднозначно)
openclaw run "почисти папку Downloads"
# Хорошо (конкретно)
openclaw run "
В папке ~/Downloads найди все файлы старше 30 дней.
Файлы с расширением .pdf перемести в ~/Documents/archive/.
Остальные файлы — удали безвозвратно.
Перед удалением покажи мне список и жди подтверждения.
"Правило: чем важнее задача, тем подробнее должна быть инструкция.
15. Агент не завершает задачу — останавливается на полпути
Симптом: агент начинает задачу, делает несколько шагов и останавливается без объяснений.
Причина A: кончился бюджет (dailyBudget в конфиге).
Причина B: достигнут лимит шагов.
Причина C: агент ждёт подтверждения (если включён confirmRequired).
Решение:
# Проверить статус и причину остановки
openclaw status --last
# Проверить бюджет
openclaw stats --today
# Продолжить с последней точки
openclaw resume
# Увеличить лимит шагов
openclaw run --max-steps 100 "задача"Ошибки производительности и стабильности (16-20)
16. Высокое потребление CPU / RAM
Симптом: OpenClaw потребляет > 50% CPU или > 4 GB RAM.
Причина A: параллельный запуск нескольких агентов. Причина B: браузерная автоматизация (каждая вкладка — отдельный процесс Chromium).
Решение:
# Ограничить количество параллельных агентов
openclaw config set runtime.maxConcurrent 2
# Закрывать вкладки после использования
openclaw config set browser.closeTabAfterUse true
# Использовать headless-режим браузера
openclaw config set browser.headless true17. Медленная работа в России / VPN-проблемы
Симптом: агент работает очень медленно, запросы занимают 5-30 секунд.
Причина: задержки при подключении к серверам OpenAI/Anthropic из России.
Решение:
# Использовать российский прокси/aitunnel
openclaw config set llm.baseUrl "https://aitunnel.ru/api/openai/v1"
openclaw config set llm.apiKey "your-aitunnel-key"
# Или использовать Groq (серверы быстрее для Llama)
openclaw config set llm.provider groq
openclaw config set llm.apiKey "your-groq-key"
openclaw config set llm.model "llama-3.3-70b-versatile"Подробнее: Установка OpenClaw через AiTunnel в России.
18. Агент теряет результаты после перезапуска
Симптом: после перезагрузки компьютера или переустановки агент «забыл» всё.
Причина: результаты хранились только в памяти сессии, не сохранялись в файлы.
Решение:
Добавьте в AGENTS.md правило:
## Сохранение результатов
Всегда сохраняй результаты работы в файлы:
- Итоги анализа → ~/openclaw-data/analysis/
- Промежуточные данные → ~/openclaw-data/temp/
- Важные решения → ~/openclaw-data/decisions/
Никогда не держи важные данные только в памяти сессии.19. Webhook не срабатывает (GitHub/Telegram интеграции)
Симптом: события от GitHub или Telegram не доходят до агента.
Причина A: агент запущен локально без публичного URL. Причина B: неверный webhook-секрет.
Решение:
# Для локальной разработки: использовать ngrok
ngrok http 3000
# Получить публичный URL и указать в настройках webhook:
# https://abc123.ngrok.io/webhooks/github
# Проверить секрет
openclaw webhook test --provider github20. ETIMEDOUT при долгих задачах
Симптом: Error: connect ETIMEDOUT при задачах длиннее 5-10 минут.
Причина: таймаут соединения с API при длинном контексте или медленном ответе.
Решение:
{
"api": {
"timeout": 120000,
"retries": 3,
"retryDelay": 5000
}
}# Или через CLI
openclaw run --timeout 120 "долгая задача"Когда ничего не помогло
# Полная диагностика
openclaw doctor --verbose
# Сброс до заводских настроек (осторожно — удалит конфиг)
openclaw reset --config-only
# Сообщить о баге
openclaw bug-report --attach-logsАктивное сообщество OpenClaw в русскоязычном сегменте: OpenClaw Community Russia.