Решение частых ошибок OpenClaw: полный гайд по диагностике и исправлению

· 7 мин чтения

OpenClaw — мощный персональный ИИ-ассистент, но иногда что-то идёт не так: агент не отвечает, gateway не запускается, каналы молчат. В этом руководстве — диагностика и решения самых частых проблем, от первого запуска до продвинутых случаев с плагинами и моделями.

Первые 60 секунд диагностики

Когда OpenClaw перестал работать, не нужно гуглить часами. Запустите эти команды по порядку — за минуту вы поймёте, что сломалось:

openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

Что ожидать от каждой команды:

  • openclaw status — показывает настроенные каналы, ошибки авторизации, статус агентов
  • openclaw status --all — полный отчёт (токены скрыты), можно вставлять в чат поддержки
  • openclaw gateway probe — проверяет доступность gateway. Reachable: yes — всё ок
  • openclaw gateway status — статус процесса: Runtime: running, Connectivity probe: ok
  • openclaw doctor — проверяет и чинит типовые проблемы конфигурации
  • openclaw channels status --probe — живой статус каждого канала (works / audit ok)
  • openclaw logs --follow — логи в реальном времени, ищите повторяющиеся ошибки

    • Важно: если openclaw gateway probe показывает Read probe: limited - missing scope: operator.read — это не ошибка подключения, а degraded diagnostics. Gateway работает, просто не все проверки доступны.

    OpenClaw не запускается: gateway не стартует

    Симптом: команда `openclaw gateway start` ничего не делает или падает

    Причина 1: порт уже занят. Другой процесс занял порт 18789 (по умолчанию).

    lsof -i :18789
# или
ss -tlnp | grep 18789

    Если порт занят другим процессом — убейте его или смените порт OpenClaw:

    export OPENCLAW_GATEWAY_PORT=18790
openclaw gateway start

    Причина 2: повреждённая конфигурация. Файл ~/.openclaw/openclaw.json содержит синтаксическую ошибку.

    openclaw doctor --fix

    Doctor проверяет конфигурацию, мигрирует устаревшие поля и чинит типовые проблемы.

    Причина 3: не хватает Node.js. OpenClaw требует Node 22.22.3+, 24.15+ или 25.9+.

    node --version

    Если версия ниже — обновите Node. Обратите внимание: Bun не поддерживается для запуска Gateway (не хватает node:sqlite).

    Симптом: gateway запускается, но сразу падает

    Проверьте логи:

    openclaw logs --follow
# или вручную:
tail -f "/tmp/openclaw/openclaw-$(date +%F).log"

    Типичные ошибки в логах:

  • EACCES — нет прав на запись. Проверьте владельца директорий
  • MODULE_NOT_FOUND — не хватает зависимостей. Запустите pnpm install (для git-установки)
  • EADDRINUSE — порт занят (см. выше)

    • Агент не отвечает на сообщения

    Канал подключён, но ответов нет

  • Проверьте модель. Возможно, API-ключ истёк или модель недоступна:
    • openclaw models status
  • Проверьте лимиты. Многие провайдеры имеют rate limits. Ошибка HTTP 429 значит, что вы превысили лимит запросов. Подождите или смените модель.
  • Проверьте токены. Если openclaw status показывает Tokens: 0 — агент не запускался. Проверьте, что gateway работает и модель настроена.
  • Проверьте tool profile. Если агент отвечает, но «не умеет» делать то, что должен — проверьте профиль инструментов:
    • openclaw status --all

    Возможные значения tools.profile:

    Профиль Что доступно
    `minimal` Только `session_status`
    `messaging` Только отправка сообщений
    `coding` Файлы, shell, рантайм (по умолчанию)
    `full` Всё без ограничений

    Изменить профиль можно в ~/.openclaw/openclaw.json:

    {
  "tools": {
    "profile": "full"
  }
}

    После изменения перезапустите gateway.

    Агент зависает при длинных задачах

    Используйте суб-агентов для тяжёлых или параллельных задач. Суб-агент работает в отдельной сессии и не блокирует основной чат:

    Запусти суб-агента для этой задачи

    Или через команду /subagents. Проверить загрузку gateway можно командой /status.

    Проблемы с подключением к API моделей

    «All models failed» / «Model not found»

    Причина 1: неправильный формат модели. OpenClaw использует формат provider/model:

    {
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-6"
      }
    }
  }
}

    Если указать просто claude-sonnet-4-6 без провайдера — OpenClaw попробует найти модель через алиасы, но это ненадёжно.

    Причина 2: API-ключ не настроен. Проверьте наличие ключа:

    echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY

    Ключи можно задать в ~/.openclaw/.env (рекомендуется) или в ~/.openclaw/openclaw.json:

    {
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-..."
  }
}

    Причина 3: модель недоступна в вашем регионе. Некоторые провайдеры блокируют доступ из определённых стран. Используйте OpenRouter как прокси:

    {
  "models": {
    "providers": {
      "openrouter": {
        "apiKey": "sk-or-..."
      }
    }
  }
}

    Ошибка «Model … is not allowed»

    Если в конфигурации задан modelPolicy.allow — это белый список разрешённых моделей. Модель вне списка будет заблокирована.

    Решение: добавьте модель в список или уберите ограничение:

    {
  "agents": {
    "defaults": {
      "modelPolicy": {
        "allow": ["anthropic/*", "openai/*"]
      }
    }
  }
}

    Локальная модель через Ollama не работает

  • Убедитесь, что Ollama запущена: ollama list
  • Проверьте, что модель скачана: ollama pull gemma4
  • В OpenClaw укажите провайдер ollama:
    • {
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/gemma4"
      }
    }
  }
}

    Для локальных моделей с небольшим контекстом может потребоваться отключить поддержку инструментов:

    {
  "models": {
    "providers": {
      "ollama": {
        "models": [{
          "id": "gemma4",
          "compat": {
            "supportsTools": false
          }
        }]
      }
    }
  }
}

    Проблемы с плагинами

    «package.json missing openclaw.extensions»

    Плагин использует устаревший формат. Нужно добавить openclaw.extensions в package.json плагина:

    {
  "name": "@openclaw/my-plugin",
  "version": "1.2.3",
  "openclaw": {
    "extensions": ["./dist/index.js"]
  }
}

    После исправления переустановите плагин.

    «Blocked plugin candidate: suspicious ownership»

    Файлы плагина принадлежат другому пользователю, чем процесс OpenClaw. Часто встречается в Docker (контейнер работает как node, uid 1000, а файлы примонтированы как root).

    sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
openclaw doctor --fix

    Если запускаете OpenClaw от root:

    sudo chown -R root:root /path/to/openclaw-config/npm
openclaw doctor --fix

    Плагин установлен, но не обновляется

    Проверьте security.installPolicy — возможно, политика безопасности блокирует обновления.

    openclaw doctor --deep
openclaw plugins update --all
openclaw status --all

    Если политика намеренно строгая — временно ослабьте её на время обновления, затем верните.

    Проблемы с каналами (Telegram, Discord, WhatsApp)

    Telegram-бот не отвечает

  • Проверьте токен бота:
    • openclaw channels status --probe
  • Проверьте, что webhook не конфликтует. Если бот ранее использовался с другим фреймворком — нужно удалить старый webhook.
  • Проверьте логи на ошибки авторизации Telegram API.

    • Discord-бот подключился, но не реагирует

  • Убедитесь, что бот приглашён на сервер с правильными правами (Send Messages, Read Message History)
  • Проверьте intents в настройках бота на Discord Developer Portal
  • openclaw channels status --probe для проверки соединения

    • WhatsApp: сессия не создаётся

    WhatsApp Web использует QR-код для авторизации. Если сессия сломалась:

  • Удалите старую сессию
  • Перезапустите gateway
  • Отсканируйте новый QR-код

    • Диагностика через `openclaw doctor`

    openclaw doctor — это швейцарский нож для диагностики. Он проверяет и чинит:

  • Синтаксис конфигурации
  • Устаревшие поля (мигрирует автоматически)
  • Права доступа к файлам
  • Целостность плагинов
  • Доступность моделей
    • # Базовая проверка
openclaw doctor

# Глубокая проверка с исправлениями
openclaw doctor --fix

# Проверка + генерация токена gateway
openclaw doctor --fix --generate-gateway-token

    Продвинутая отладка

    Watch mode для разработчиков

    Если вы разрабатываете плагины или хотите видеть логи в реальном времени:

    pnpm gateway:watch

    Это запускает gateway в tmux-сессии с автоматическим перезапуском при изменениях кода. Для просмотра:

    tmux attach -t openclaw-gateway-watch-main

    Трассировка плагинов

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

    OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins list

    Показывает пофазовую загрузку: config read → slot selection → registry refresh.

    Runtime debug overrides

    Команда /debug позволяет менять конфигурацию на лету без перезаписи файла:

    /debug set channels.whatsapp.responsePrefix="[openclaw]"
/debug show
/debug reset

    Включается флагом commands.debug: true в конфигурации.

    FAQ

    OpenClaw установился, но `openclaw status` показывает ошибки

    Запустите openclaw doctor --fix. В 90% случаев это решает проблему с конфигурацией после установки.

    Как сменить модель без перезапуска?

    Отправьте сообщение /model прямо в чат с ботом. Например: /model anthropic/claude-sonnet-4-6. Смена действует только для текущей сессии.

    Gateway работает, но Control UI не открывается

    Проверьте, что вы открываете правильный URL. По умолчанию: http://127.0.0.1:18789/. Если нужно подключиться удалённо — используйте SSH-туннель:

    ssh -N -L 18789:127.0.0.1:18789 user@gateway-host

    Как увидеть полные логи?

    openclaw logs --follow

    Если RPC недоступен — читайте файл напрямую:

    tail -f "/tmp/openclaw/openclaw-$(date +%F).log"

    Агент использует инструменты, которые мне не нужны

    Проверьте tool profile через openclaw status --all. Измените на minimal или messaging, если не нужны инструменты кодирования и файлов. Или настройте конкретные инструменты через agents.entries.*.tools.

    *Статья основана на официальной документации OpenClaw. Актуально на июль 2026 года.*