Частые ошибки OpenClaw и их решения | open-claw.su

Собрали самые частые ошибки при установке и использовании OpenClaw — с объяснениями и пошаговыми решениями. Если вы столкнулись с проблемой — скорее всего, ответ здесь.

Ошибки при установке

«command not found: openclaw»

OpenClaw не найден в PATH после установки.

Решение:

# macOS / Linux: проверьте, что OpenClaw доступен:
which openclaw

# Если не найден — проверьте путь npm global:
npm root -g
# Убедитесь, что родительская директория ../bin есть в $PATH

# Переустановите глобально:
npm install -g openclaw@latest

# Если npm global bin не в PATH — добавьте вручную:
NPM_ROOT=$(npm root -g)
echo "export PATH=\"${NPM_ROOT%/lib/node_modules}/bin:\$PATH\"" >> ~/.zshrc
source ~/.zshrc

Windows (PowerShell):

# Переустановите глобально:
npm install -g openclaw@latest

# Проверьте, доступна ли команда:
Get-Command openclaw

# Если нет — перезапустите терминал

«Permission denied» при установке (macOS/Linux)

# Если не хватает прав — используйте sudo для глобальной установки:
sudo npm install -g openclaw@latest

«EACCES: permission denied» (npm)

# Исправьте права npm:
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Установщик не скачивается

Если npm-реестр недоступен из России:

# Вариант 1: установка через npm
npm install -g openclaw@latest

# Вариант 2: через GitHub напрямую
git clone https://github.com/openclaw/openclaw.git
cd openclaw
npm install
npm start

Ошибки конфигурации

«Access not configured»

Одна из самых частых ошибок. Означает, что API-ключ не настроен или недействителен.

Проверьте:

Ключ задан в openclaw.json (~/.openclaw/openclaw.json):

{
  agent: {
    model: "openrouter/deepseek/deepseek-chat",  // формат: провайдер/модель
  },
}

Переменная окружения установлена:

echo $OPENROUTER_API_KEY
# Должен вывести ваш ключ. Если пусто — добавьте в ~/.openclaw/.env:
# OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxx

Ключ начинается с правильного префикса:
- OpenRouter: sk-or-v1-...
- OpenAI: sk-...
- Anthropic: sk-ant-...
- DeepSeek (прямой): sk-...
Баланс на аккаунте не нулевой — проверьте на сайте провайдера
Модель указана в формате провайдер/модель:

Провайдер	Формат модели
OpenRouter	`"openrouter/deepseek/deepseek-chat"`
OpenAI	`"openai/gpt-4o"`
Anthropic	`"anthropic/claude-opus-4-6"`
Ollama	`"ollama/qwen2.5:32b"`

«Invalid API key»

# Проверьте, нет ли лишних пробелов или переносов строки:
echo -n "$OPENROUTER_API_KEY" | wc -c
# Сравните с длиной ключа на сайте провайдера

# Пересоздайте ключ на сайте провайдера, если не помогает

Ошибка в openclaw.json

Ошибка синтаксиса JSON в конфигурационном файле.

Частые ошибки:

// НЕПРАВИЛЬНО — лишняя запятая после последнего элемента (в обычном JSON):
{
  "agent": {
    "model": "openrouter/deepseek/deepseek-chat",  // ← в JSON5 это допустимо, в JSON — нет
  }
}

// НЕПРАВИЛЬНО — одинарные кавычки (в обычном JSON):
{ 'agent': { 'model': 'openrouter/deepseek/deepseek-chat' } }

// ПРАВИЛЬНО (JSON5 — поддерживается OpenClaw):
{
  agent: {
    model: "openrouter/deepseek/deepseek-chat",
  },
}

Проверка синтаксиса:

# Проверка конфигурации:
openclaw doctor

Ошибки Telegram

«Could not resolve telegram» / «Connection error»

Агент не может подключиться к Telegram API.

Решения:

Проверьте интернет:

ping api.telegram.org
curl -s https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getMe

Проверьте токен бота:

# Должен вернуть JSON с информацией о боте:
curl "https://api.telegram.org/bot123456789:ABCdef.../getMe"

Если токен устарел — получите новый через @BotFather:
- Отправьте /revoke
- Выберите бота
- Получите новый токен
- Обновите openclaw.json
Проверьте firewall/VPN — Telegram API должен быть доступен

Бот не отвечает на сообщения

Проверьте настройку канала Telegram в openclaw.json:

{
  channels: {
    telegram: {
      botToken: "123456789:ABCdef...",
    },
  },
}

Узнайте свой ID: напишите @userinfobot в Telegram
Проверьте логи: посмотрите вывод терминала, где запущен gateway, или запустите с флагом --verbose:

openclaw gateway --port 18789 --verbose

Бот не добавлен в группу или не имеет прав на чтение сообщений

«Unauthorized» (401)

Токен бота недействителен. Получите новый через BotFather.

«Too many requests» (429)

Telegram ограничивает частоту. Решения:

Подождите 30–60 секунд и перезапустите gateway
Проверьте настройки канала в openclaw.json

Ошибки подключения (pairing)

Что такое pairing

Когда канал (Telegram, WhatsApp и др.) использует политику pairing для входящих сообщений, новые пользователи не получают доступ автоматически. Они отправляют сообщение боту, и OpenClaw создаёт запрос на подключение, который нужно одобрить вручную.

Как одобрить запрос

# Посмотреть ожидающие запросы
openclaw pairing list telegram

# Одобрить запрос (8-символьный код)
openclaw pairing approve telegram ABCD1234

Коды запросов действительны 1 час. Максимум — 3 ожидающих запроса на канал.

Для устройств (nodes) процедура аналогична:

# Список запросов от устройств
openclaw devices list

# Одобрить устройство
openclaw devices approve <requestId>

«Pairing required» / соединение разрывается

Убедитесь, что ваш ID одобрен — проверьте openclaw pairing list <channel>
Если запрос истёк (старше 1 часа) — отправьте сообщение боту заново
Проверьте, что gateway запущен: openclaw gateway status
Для диагностики: openclaw gateway probe

Отключение и переподключение

Если агент теряет связь с каналом и не переподключается автоматически:

# Проверьте статус gateway
openclaw gateway status

# Расширенная диагностика
openclaw gateway probe

# Перезапустите gateway
openclaw gateway restart

# Проверьте логи для деталей
openclaw logs

Полный список команд pairing и диагностики — в справочнике CLI.

Ошибки LLM (языковой модели)

«Rate limit exceeded»

Превышен лимит запросов к API.

Подождите несколько минут и попробуйте снова. Или перейдите на платный тариф провайдера с более высокими лимитами.

«Context length exceeded»

Сообщение слишком длинное для модели. Попробуйте начать новый диалог командой /new в мессенджере, или используйте модель с большим контекстным окном.

«Model not found»

Неверное имя модели.

Провайдер	Правильное имя модели (формат `провайдер/модель`)
OpenRouter + DeepSeek	`openrouter/deepseek/deepseek-chat`, `openrouter/deepseek/deepseek-r1`
OpenAI	`openai/gpt-4o`, `openai/gpt-4o-mini`
Anthropic	`anthropic/claude-opus-4-6`
Google Gemini	`google/gemini-3-pro-preview`
Ollama	`ollama/qwen2.5:32b` (имя скачанной модели)

«Connection refused» (Ollama)

Ollama-сервер не запущен.

# Запустите сервер:
ollama serve

# Проверьте:
curl http://localhost:11434/api/tags

Медленные ответы

Причина	Решение
Перегрузка API	Попробуйте позже или смените провайдера
Большая модель в Ollama	Используйте модель поменьше
Нет GPU	Для Ollama GPU ускоряет в 5–10 раз
Длинный контекст	Уменьшите `num_ctx`

Ошибки heartbeat / процесса

«Heartbeat timeout»

Агент потерял связь с основным процессом.

# Остановите gateway (Ctrl+C в терминале) и запустите заново:
openclaw gateway --port 18789

# Если процесс завис — найдите и завершите вручную:
ps aux | grep openclaw
kill <PID>

# Затем запустите снова:
openclaw gateway --port 18789

Агент зависает или не отвечает

# Проверьте состояние через дашборд:
# Откройте http://127.0.0.1:18789/ в браузере

# Посмотрите вывод терминала, где запущен gateway

# Принудительная остановка — нажмите Ctrl+C в терминале gateway
# Или найдите процесс вручную:
ps aux | grep openclaw
kill -9 <PID>

Агент перезапускается в цикле

Обычно проблема в openclaw.json:

# Посмотрите вывод терминала, где запущен gateway

# Частые причины:
# - Ошибка синтаксиса JSON в openclaw.json
# - Несуществующая модель
# - Недействительный API-ключ

# Проверьте конфигурацию:
openclaw doctor

Ошибки скиллов

«Skill not found»

# Переустановите скилл:
clawhub install skill-name

# Перезапустите gateway (Ctrl+C и заново):
openclaw gateway --port 18789

«Permission denied» при выполнении скилла

Скилл пытается получить доступ к ресурсу без прав. Проверьте настройки скилла в openclaw.json:

{
  skills: {
    entries: {
      "file-ops": { enabled: true },
    },
  },
}

Агент не использует скилл

Проверьте, что скилл установлен: загляните в ~/.openclaw/workspace/skills/
Проверьте description в манифесте — он должен ясно описывать назначение
Добавьте подсказку в SOUL.md (~/.openclaw/workspace/SOUL.md):

rules:
  - Для поиска в интернете всегда используй скилл web-search
  - Для работы с файлами используй file-ops

Отладка

Включение подробных логов

# Запуск с подробными логами:
openclaw gateway --port 18789 --verbose

Проверка конфигурации

# Валидация конфигурации:
openclaw doctor

# Просмотр текущей конфигурации — откройте файл напрямую:
cat ~/.openclaw/openclaw.json

Тест подключения к API

# Диагностика подключений:
openclaw doctor

# Проверить Telegram:
openclaw channels login

Как удалить OpenClaw

Через CLI (рекомендуется)

Самый простой способ — встроенная команда:

# Интерактивное удаление (с подтверждениями)
openclaw uninstall

# Полное неинтерактивное удаление
openclaw uninstall --all --yes

# Симуляция — показывает что будет удалено, ничего не трогает
openclaw uninstall --dry-run

Важно: команда openclaw uninstall удаляет gateway-сервис и локальные данные, но сохраняет саму CLI-утилиту. Чтобы удалить и её — выполните npm rm -g openclaw после.

Полное ручное удаление

Если CLI недоступен или нужно удалить всё вручную:

macOS / Linux:

# 1. Остановите gateway
openclaw gateway stop
# Или вручную, если CLI не работает:
ps aux | grep openclaw
kill <PID>

# 2. Удалите системный сервис
openclaw gateway uninstall
# Или вручную на macOS:
launchctl bootout gui/$UID/bot.molt.gateway
rm ~/Library/LaunchAgents/bot.molt.gateway.plist
# Или вручную на Linux:
systemctl --user disable openclaw-gateway.service
systemctl --user stop openclaw-gateway.service
rm ~/.config/systemd/user/openclaw-gateway.service

# 3. Удалите данные, конфигурацию и workspace (SOUL.md, память и т.д.)
rm -rf ~/.openclaw

# 4. Удалите CLI-утилиту
npm rm -g openclaw

# 5. macOS: удалите десктопное приложение (если установлено)
rm -rf /Applications/OpenClaw.app

Windows (PowerShell):

# 1. Остановите gateway
openclaw gateway stop

# 2. Удалите запланированную задачу (системный сервис)
openclaw gateway uninstall
# Или вручную:
schtasks /Delete /TN "OpenClaw Gateway" /F

# 3. Удалите данные
Remove-Item -Recurse -Force "$env:USERPROFILE\.openclaw"

# 4. Удалите CLI-утилиту
npm rm -g openclaw

Переустановка

Для чистой переустановки (сохранив настройки):

# Сохраните конфигурацию
cp ~/.openclaw/openclaw.json ~/openclaw-backup.json

# Удалите
openclaw uninstall --all --yes
npm rm -g openclaw

# Установите заново
curl -fsSL https://openclaw.ai/install.sh | bash

# Восстановите конфигурацию
cp ~/openclaw-backup.json ~/.openclaw/openclaw.json

Не нашли решение?

Проверьте официальную документацию
Поищите в GitHub Issues
Задайте вопрос в Telegram-чате сообщества

Что дальше

Быстрый старт — правильная установка с нуля
Установка на Mac — пошаговый гайд
Установка на Windows — пошаговый гайд
Установка на Linux — пошаговый гайд
Gateway: как устроен и как настроить — запуск, дашборд, удалённый доступ
Справочник команд CLI — все команды OpenClaw с примерами
Настройка в России — доступ без VPN