OpenClaw

Платформа: Docker / VPS

Причина: Недостаточно RAM. OpenClaw требует минимум 4 GB (рекомендуется 8 GB). На дешёвых VPS с 1-2 GB — гарантированный OOM.

Container exited with code 137

Решение:

1. Увеличить RAM VPS до 4+ GB
2. Или добавить swap: fallocate -l 4G /swapfile && mkswap /swapfile && swapon /swapfile
3. Проверить лимиты: docker stats

Платформа: Docker

Причина: Bind mounts на хосте принадлежат другому пользователю. OpenClaw в контейнере работает под uid 1000.

EACCES: permission denied, open '/home/node/.openclaw/config.json'

Решение:

1. sudo chown -R 1000:1000 /path/to/openclaw-config
2. Или использовать named volumes вместо bind mounts

Платформа: Docker

Причина: CLI не подключается к Gateway. Переменная OPENCLAW_GATEWAY_TOKEN перезаписывает токен из конфига.

WebSocket connection failed: 1006 / 1008, token mismatch

Решение:

1. Убедиться, что OPENCLAW_GATEWAY_TOKEN в .env совпадает с токеном в конфиге
2. Диагностика: docker compose logs -f
3. Пересоздать pairing: openclaw onboard

Платформа: Docker / Local

Причина: API-ключ Anthropic не указан или в неверном формате. Ключ должен начинаться с sk-ant-api03-. OAuth-токены больше не работают с апреля 2026.

Agent failed before reply: No API key found for provider "anthropic"

Решение:

1. Получить ключ на console.anthropic.com
2. Указать через openclaw onboard → Anthropic → API Key
3. Проверить: openclaw status --all

Платформа: Docker / Local

Причина: С апреля 2026 Anthropic запретила подписочные OAuth-токены (Claude Pro/Max) в сторонних приложениях. Нужен API-ключ или Extra Usage credits.

LLM request rejected: You're out of extra usage

Решение:

1. Переключиться на API-ключ (рекомендуется)
2. Или купить Extra Usage credits на claude.ai/settings/usage
3. Или использовать API-прокси

Платформа: Docker / Local

Причина: В версии 2026.2.17 сломана OAuth для Anthropic и OpenAI. API Anthropic не поддерживает OAuth — только API-ключи.

OAuth authentication is currently not supported
invalid x-api-key

Решение:

1. Переключиться на API Key: openclaw onboard → провайдер → API Key
2. Не использовать OAuth для Anthropic

Платформа: Docker / Local / VPS

Причина: Закончились credits на OpenAI, или новый аккаунт не активирован (до 20 минут после оплаты).

Error code: 429 — You exceeded your current quota,
please check your plan and billing details

Решение:

1. Проверить баланс на platform.openai.com/usage
2. Пополнить credits
3. Настроить maxRequestsPerMinute в конфиге OpenClaw

Платформа: VPS / Local

Причина: IAM-токен YandexGPT живёт максимум 12 часов. Для бота нужен сервисный аккаунт с API-ключом. Часто путают FOLDER_ID и CATALOG_ID.

401 Unauthorized
IAM token is expired

Решение:

1. Создать сервисный аккаунт в Yandex Cloud
2. Использовать API-ключ (Api-Key header) вместо IAM-токена
3. Указать правильный FOLDER_ID (из URL консоли Yandex Cloud)

Платформа: Docker / Local

Причина: При онбординге Telegram определяется как «plugin», хотя это встроенный канал. Конфиг пишется в plugins.entries.telegram вместо channels.telegram.

Telegram plugin is not available

Решение:

1. Выполнить openclaw plugins enable telegram
2. Или вручную перенести конфиг в секцию channels.telegram в openclaw.json
3. Перезапустить OpenClaw

Платформа: Docker / VPS

Причина: Конфликт webhook и polling. Если ранее был настроен webhook, Telegram не отправляет сообщения через polling.

Решение:

1. Удалить webhook: curl https://api.telegram.org/bot<TOKEN>/deleteWebhook
2. Перезапустить OpenClaw
3. Если проблема с IPv6 — принудительно использовать IPv4

Платформа: Docker / Local

Причина: WhatsApp не имеет официального API для ботов. Библиотеки Baileys/Whiskay реверс-инженерят протокол, WhatsApp детектирует автоматизацию и банит.

Решение:

1. Использовать WhatsApp Business API (официальный, платный)
2. Или: ограничить частоту сообщений, не использовать в группах
3. Добавить случайные задержки, session persistence обязательна

Платформа: Docker / Local

Причина: Не включён привилегированный intent «Message Content» в Discord Developer Portal. С 2022 года это обязательно.

Решение:

1. Discord Developer Portal → Bot → Privileged Gateway Intents
2. Включить «Message Content Intent»
3. Перезапустить OpenClaw

Платформа: Docker / Local

Причина: В Q1 2026 три релиза подряд содержали breaking changes. Формат openclaw.json меняется без автоматической миграции.

Invalid configuration
Unknown config key: "plugins.entries.telegram"

Решение:

1. Перед обновлением: cp openclaw.json openclaw.json.bak
2. После: openclaw doctor --fix
3. Если не помогает — ручная правка по changelog

Платформа: Docker / VPS (публичный доступ)

Причина: Версии до 2026.1.29 имели auth: none по умолчанию на Control Plane WebSocket. Любой мог выполнить произвольный код на сервере.

Решение:

1. Обновить OpenClaw до версии ≥ 2026.1.29
2. Проверить, что gateway.auth не установлен в none
3. Не выставлять порт 18789 наружу без аутентификации

Платформа: VPS (Ubuntu/Debian)

Причина: Нет опыта с серверами. Бот работает локально, но непонятно, как перенести на VPS, чтобы он работал 24/7.

Решение (минимальный VPS — 1 vCPU, 2 GB RAM):

1. Купить VPS (Timeweb, Selectel, Aéza — от 300 руб/мес). Выбрать Ubuntu 22.04
2. Подключиться по SSH: ssh root@IP_ВАШЕГО_СЕРВЕРА
3. Установить Node.js 22+: curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && apt install -y nodejs
4. Установить OpenClaw: npm install -g openclaw
5. Настроить: openclaw onboard (мастер проведёт через настройку)
6. Запустить как сервис: openclaw gateway install --daemon

Платформа: Все

Причина: Три разных способа авторизации у AI-провайдеров вызывают путаницу. Подписка Claude Pro/Max — это НЕ то же самое, что API-ключ.

Разница:

1. Подписка (Claude Pro/Max, ChatGPT Plus) — для сайтов claude.ai / chatgpt.com. Для ботов не подходит
2. API-ключ — специальный токен для программ. Оплата за использование (по токенам). Это то, что нужно для OpenClaw
3. OAuth — вход через аккаунт. С апреля 2026 сломан для Anthropic. Не рекомендуется

Где получить API-ключ: Anthropic, OpenAI, Google AI.

Платформа: Все

Причина: Без файла SOUL.md (или с пустым файлом) бот использует дефолтную личность — общую и безликую. Он не знает, кто он, как разговаривать и какие задачи решать.

Решение:

1. Создать файл SOUL.md в рабочей директории OpenClaw
2. Описать: имя бота, роль, стиль общения, запреты, целевую аудиторию
3. Перезапустить: openclaw gateway restart
4. Проверить загрузку: openclaw status --all (в секции Bootstrap Files)

Платформа: Все

Причина: Контекст раздувается до 100K+ токенов на длинных диалогах. Каждое сообщение отправляет всю историю в API — расход растёт экспоненциально.

context_length_exceeded -- input tokens: 135,892, max: 128,000

Решение:

1. Включить компактификацию: openclaw config set context.compaction.enabled true
2. Ограничить контекст: openclaw config set context.maxTokens 4000
3. Использовать дешёвую модель для рутины: Claude Haiku или GPT-4o-mini (~$0.15/1M токенов vs $15 у Opus)
4. Использовать локальную модель через Ollama для тестирования (бесплатно)

Платформа: VPS / Local

Причина: Российские модели используют нестандартную авторизацию. YandexGPT — IAM-токены с коротким сроком жизни. GigaChat — OAuth 2.0 с hashing. Стандартный OpenAI-совместимый endpoint не работает.

YandexGPT:

1. Создать сервисный аккаунт в Yandex Cloud с ролью ai.languageModels.user
2. Получить API-ключ (не IAM-токен — он протухает за 12 часов)
3. Добавить как OpenAI-compatible провайдер с endpoint https://llm.api.cloud.yandex.net/foundationModels/v1/completion

GigaChat:

1. Получить client_id и client_secret на developers.sber.ru
2. GigaChat требует отдельный proxy-слой — стандартный OpenAI-формат не работает
3. Рекомендация: использовать GigaChain как прокси

Платформа: Docker / Local

Причина: OpenClaw загружает только 8 конкретных файлов: SOUL.md, AGENTS.md, USER.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md. Файл с другим именем или в неправильной директории молча игнорируется. Симлинки за пределами workspace тоже отклоняются без ошибки.

openclaw status --all
Bootstrap Files: SOUL.md (not found)

Решение:

1. Файл должен называться точно SOUL.md (не soul.md, не Soul.md)
2. Лежать в корне workspace (рядом с openclaw.json)
3. Не быть симлинком за пределами workspace
4. После обновления выполнить: openclaw doctor --deep --yes
5. Проверить: openclaw status --all — в секции Bootstrap Files должен быть SOUL.md

Платформа: Docker / Local

Причина: Skills требуют строгую структуру: папка skills/<id>/SKILL.md, а не просто файл skills/my-skill.md. Также ломаются при: двоеточии в name/description (ломает YAML), коллизии имён, BOM-маркере в файле.

openclaw skills list
Loaded: 8/13 skills (5 skipped)

Решение:

1. Проверить структуру: skills/my-skill/SKILL.md (папка, внутри SKILL.md)
2. Диагностика: openclaw skills check
3. Убрать : из name и description в frontmatter (или обернуть в кавычки)
4. Проверить кодировку: файл должен быть UTF-8 без BOM
5. Приоритет загрузки: <workspace>/skills → bundled → skills.load.extraDirs

Платформа: Все

Причина: Длинные диалоги компактируются (сжимаются), теряя детали. При смене темы бот «забывает» предыдущий контекст. Долгосрочная память работает только через MEMORY.md, который надо настроить явно.

Решение:

1. Для долгосрочных фактов — попросить бота записать в MEMORY.md: «запомни, что меня зовут Иван»
2. Настроить компактификацию: openclaw config set context.compaction.threshold 0.8
3. Увеличить окно контекста (если модель позволяет): openclaw config set context.maxTokens 16000
4. Диагностика: OPENCLAW_LOG_CONTEXT_SIZE=true openclaw logs --follow

Платформа: Все

Причина: Фото и голосовые сообщения молча игнорируются, если: модель не поддерживает vision (например, Claude Haiku старых версий), не установлен speech-to-text skill для голоса, или Ollama-модель без vision.

Решение для изображений:

1. Убедиться, что модель поддерживает vision: Claude Sonnet/Opus, GPT-4o, Gemini Pro
2. Для Ollama: использовать модель с vision (llava, llama3.2-vision)

Решение для голоса:

1. Установить Whisper skill: openclaw skills install whisper-stt
2. Или подключить внешний STT через API (Google Speech, Yandex SpeechKit)

Платформа: Docker / VPS

Причина: По умолчанию Telegram-боты работают в Privacy Mode — они не видят сообщения в группах, только команды (/start) и прямые ответы на свои сообщения.

Решение:

1. Открыть @BotFather → /setprivacy → выбрать бота → Disable
2. Или сделать бота админом группы (тогда Privacy Mode не действует)
3. Критично: после переключения удалить и заново добавить бота в каждую группу
4. Для ограничения доступа: настроить channels.telegram.groupAllowFrom в конфиге

Платформа: VPS / Docker

Причина: AI-провайдеры ограничивают запросы: Anthropic — 50 RPM на бесплатном тире, OpenAI — зависит от уровня. При rate limit OpenClaw ставит провайдера в cooldown, и следующие запросы тоже отклоняются.

429 Too Many Requests
Provider "anthropic" entered cooldown (300s)

Решение:

1. Настроить лимиты: openclaw config set providers.anthropic.maxRequestsPerMinute 30
2. Добавить fallback-провайдер (OpenAI или Ollama) — при cooldown бот переключится
3. Увеличить API tier у провайдера (пополнить баланс)
4. Проверить статус: openclaw models status

Платформа: Все

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

Диагностические команды:

openclaw status --deep          # полная диагностика с health probe
openclaw doctor --deep --yes     # авторемонт (решает ~80% проблем)
openclaw logs --follow           # логи в реальном времени
openclaw logs --level error --tail 50  # последние 50 ошибок
openclaw config validate         # валидация конфига
openclaw channels status --probe # статус всех каналов
openclaw skills check            # проверка skills
openclaw health --json           # полный snapshot для отчёта

Платформа: Docker

Причина: OpenClaw выпускает релизы каждые 1-2 дня, часто с breaking changes. Команда docker compose pull && docker compose up -d может сломать конфиг. А config.apply заменяет ВЕСЬ конфиг — частичные объекты удаляют всё остальное.

Безопасное обновление:

1. Бэкап: cp openclaw.json openclaw.json.bak
2. Пинить версию в docker-compose: image: openclaw/openclaw:2026.3.23-2
3. Обновить: docker compose pull && docker compose up -d
4. Мигрировать конфиг: docker compose exec openclaw openclaw doctor --fix
5. Для мелких правок: openclaw config set key value (не config.apply!)

Платформа: VPS / Docker

Причина: Каждый экземпляр OpenClaw запускает свой Gateway на порту 18789 по умолчанию. Два бота с одним портом — конфликт.

Решение через Docker Compose (рекомендуется):

# docker-compose.yml
services:
  bot-support:
    image: openclaw/openclaw:2026.3.23-2
    volumes:
      - ./bot-support:/workspace
    ports: ["18789:18789"]
  bot-sales:
    image: openclaw/openclaw:2026.3.23-2
    volumes:
      - ./bot-sales:/workspace
    ports: ["18790:18789"]

Каждому боту — своя директория с отдельными openclaw.json, SOUL.md и API-ключами.

Платформа: VPS / Docker

Причина: Несколько возможных причин: Gateway process упал (systemd не перезапустил), Telegram webhook протух, Ollama cold start занимает 13-46 секунд и вызывает timeout, или хостинг усыпляет VPS.

LLM HTTP request timeout (60s exceeded)

Решение:

1. Проверить Gateway: openclaw gateway status
2. Запустить как systemd-сервис: openclaw gateway install --daemon (автоперезапуск)
3. Для Ollama: увеличить timeout — openclaw config set providers.ollama.requestTimeout 120000
4. Если Ollama на Docker: host.docker.internal:11434/v1 (не localhost!)
5. Проверить, что VPS не засыпает (дешёвые хостинги отключают idle-машины)

Платформа: Telegram

Причина: После релизов Telegram Bot API в 2026 году (особенно 7.10+) часть прежних паттернов перестала работать: webhook требует более строгой проверки SSL-цепочки, polling чаще выдаёт Conflict: terminated by other getUpdates request, появились новые rate limits на sendMessage в группах, поведение parseMode=MarkdownV2 стало строже к экранированию.

Conflict: terminated by other getUpdates request
Bad Request: can't parse entities: character '.' is reserved
429 Too Many Requests: retry after 30

Решение:

1. Один токен — один процесс. Если тот же BOT_TOKEN используется в нескольких местах (основной бот + локальный тест + сторонний сервис), на getUpdates возникает deadlock. Решение: либо webhook (можно мульти-сервис на разных URL), либо ровно один поллер
2. Webhook: использовать сертификат от Let's Encrypt, не self-signed. Telegram теперь жёстче проверяет цепочку. Установка: curl -F "url=https://your.domain/webhook" https://api.telegram.org/bot<TOKEN>/setWebhook
3. Проверить webhook: curl https://api.telegram.org/bot<TOKEN>/getWebhookInfo — поле last_error_message покажет проблему
4. На polling-боте при Conflict: curl https://api.telegram.org/bot<TOKEN>/deleteWebhook?drop_pending_updates=true — снимет конкурирующего слушателя
5. Для MarkdownV2 экранировать _*[]()~`>#+-=|{}.! обратным слэшем. Удобнее переключиться на parseMode=HTML — там нужно экранировать только <, >, &
6. Rate limit в группах: 20 сообщений в минуту. На массовых рассылках добавить time.sleep(3) между отправками или использовать exponential backoff на 429
7. Следить за changelog: core.telegram.org/bots/api#recent-changes — Telegram объявляет breaking-изменения за 2-4 недели

Источник: Telegram Bot API changelog

Платформа: WhatsApp / Discord / Telegram

Причина: При работе с несколькими каналами одного типа (два WhatsApp Business номера, несколько Discord-серверов) токены протухают чаще обычного, при перезапуске контейнера сессии не восстанавливаются, на Discord после обновлений политики 2026 года появляется Privileged Intent Missing. Meta усилила ротацию токенов WhatsApp Business, Discord обновил Intent-политику.

WhatsApp: token expired, session not found
Discord: Privileged Intent Missing (Message Content)
Telegram: BOT_TOKEN collision detected

Решение:

1. WhatsApp Business API: Permanent Access Token хранить в персистентном volume (/data/sessions/), не в памяти контейнера. После рестарта подгружается заново
2. Включить автоматический refresh: в конфиге OpenClaw для WhatsApp-плагина указать auto_refresh: true и проверять expiration по cron раз в сутки
3. Для нескольких WhatsApp-номеров — отдельный подкаталог сессии на каждый номер: /data/sessions/whatsapp/<phone_number>/. Иначе один токен перезатирает другой
4. Discord: после обновлений Intent-политики 2026 для чтения сообщений нужен включённый Message Content Intent в Developer Portal плюс ручное согласие при превышении 75 серверов
5. Discord-боты на 100+ серверах требуют верификацию Discord — без неё Privileged Intents отключаются автоматически
6. Telegram multi-bot — каждый бот свой BOT_TOKEN в отдельном environment-блоке docker-compose.yaml, не делить токены между сервисами
7. Логировать все обновления токенов в отдельный лог /data/logs/oauth.log — потом проще диагностировать