Исправление всех ошибок OpenClaw: API-ключи, лимиты запросов, токен шлюза — полное руководство по устранению неполадок (2026)

Ошибки OpenClaw, такие как 401 Unauthorized, 429 Rate Limit Exceeded и несовпадение токена шлюза, объединены общим первым шагом: выполните openclaw doctor --fix для автоматического исправления большинства проблем конфигурации. Это руководство охватывает все коды ошибок OpenClaw с пошаговой диагностикой, проверенными решениями и готовым к продакшену кодом для обработки сбоев в ваших приложениях. Независимо от того, столкнулись ли вы с ошибками аутентификации при свежей установке, лимитами запросов в продакшен-развёртывании или коварной проблемой переопределения переменных окружения в Docker — здесь вы найдёте точное решение.

Краткое содержание

Большинство ошибок OpenClaw попадают в пять категорий, каждая с определённым первоначальным действием. Для ошибок аутентификации 401 убедитесь, что формат API-ключа начинается с sk-ant-api03-, и выполните openclaw models status для проверки валидности учётных данных. Для ошибок лимита запросов 429 проверьте свой уровень (tier) в Anthropic и реализуйте экспоненциальную задержку с использованием заголовка retry-after. Для ошибок 400 (неверный запрос), например при использовании невалидных бета-флагов, убедитесь, что ваш провайдер поддерживает запрашиваемую бета-функцию. Для ошибок подключения 502/1008 перегенерируйте токен шлюза командой openclaw models auth setup-token. Для проблем, специфичных для Docker, проверьте, не переопределяет ли переменная окружения OPENCLAW_GATEWAY_TOKEN вашу конфигурацию. Универсальная диагностическая команда openclaw status --all определяет корневую причину практически любой ошибки за считанные секунды.

Быстрая диагностика — определите свою ошибку за 30 секунд

Каждая ошибка OpenClaw несёт в себе конкретный HTTP-код статуса или сообщение об ошибке, которое указывает непосредственно на корневую причину. Вместо того чтобы гадать, какое исправление применить, вы можете определить точную проблему менее чем за 30 секунд, сопоставив вывод ошибки с диагностическими шаблонами. Такой систематический подход предотвращает распространённую ошибку — применение неправильного решения, например, перегенерацию API-ключей, когда реальная проблема в лимите запросов, или настройку переменных окружения, когда проблема в повреждённом токене шлюза.

Начните с универсальной диагностической команды, которую OpenClaw предоставляет именно для этой цели. Выполнение openclaw status --all создаёт полный, безопасный для учётных данных отчёт о состоянии всей конфигурации, включая статус провайдеров, состояние аутентификации, подключение к шлюзу и активные условия ошибок. Эта единственная команда заменяет необходимость ручной проверки отдельных конфигурационных файлов и безопасна для обмена при обращении за помощью — она автоматически скрывает конфиденциальные значения.

Для более быстрой проверки, сфокусированной именно на аутентификации, используйте openclaw models status. Эта команда тестирует учётные данные каждого настроенного провайдера в реальном времени и сообщает об их валидности. Вы увидите чёткие индикаторы, такие как «valid», «invalid bearer token» или «no auth configured» для каждого провайдера. Когда вывод показывает «all in cooldown» для провайдера, ваши учётные данные могут быть совершенно правильными — OpenClaw временно заблокировал запросы из-за повторных ошибок, и это защитный механизм, а не проблема с учётными данными.

Инструмент автоматического восстановления openclaw doctor --fix обрабатывает структурные проблемы конфигурации, такие как некорректный JSON, отсутствующие обязательные поля и неправильные права доступа к файлам. Он не может генерировать новые API-ключи или исправлять истёкшие учётные данные, но устраняет удивительно большое количество проблем при первоначальной настройке. Всегда запускайте эту команду перед ручным устранением неполадок — если она решит вашу проблему, вы сэкономите значительное время.

Ошибки аутентификации (401) — API-ключи, токены и шлюз

Ошибки аутентификации — наиболее часто встречающиеся сбои OpenClaw, и одновременно самые запутанные, поскольку OpenClaw использует трёхуровневую архитектуру аутентификации, где сбои могут возникать на любом уровне. Понимание этой архитектуры критически важно для целенаправленного устранения неполадок, а не хаотичного перебора вариантов. Три уровня: ваша локальная конфигурация (каталог ~/.openclaw/), служба шлюза OpenClaw (работает на порту 18789 для WebSocket и 18791 для управления) и вышестоящий провайдер (API Anthropic по адресу api.anthropic.com). Каждый уровень имеет собственные требования к учётным данным и свои режимы отказа.

Уровень 1: ошибки локальной конфигурации. Наиболее распространённый сбой аутентификации происходит прямо на старте — ваша локальная конфигурация OpenClaw либо не содержит учётных данных, либо содержит некорректные. Когда вы видите «No API key found for provider 'anthropic'» в диагностическом выводе, это означает, что хранилище учётных данных OpenClaw по адресу ~/.openclaw/openclaw.json не содержит учётных данных Anthropic вообще. Это происходит при свежих установках, пропустивших этап начальной настройки, или при создании новых агентов, которые не наследуют учётные данные из основной конфигурации. Исправление простое: выполните openclaw onboard и следуйте инструкциям для настройки аутентификации Anthropic. Мастер настройки проверит формат ключа и сохранит его правильно.

API-ключи Anthropic имеют строгий формат — они должны начинаться с sk-ant-api03-, за которым следует длинная буквенно-цифровая строка. Если ваш ключ не соответствует этому шаблону, он либо не является ключом Anthropic, был повреждён при копировании (проверьте наличие лишних пробелов или символов новой строки), либо это устаревший формат ключа от предыдущей версии API Anthropic. Вы можете проверить свой ключ независимо, выполнив прямой вызов API:

bash
curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_KEY_HERE" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-5-20250929","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}' \
  | head -c 200

Если эта команда возвращает корректный ответ, ваш ключ работает и проблема находится в другом месте стека OpenClaw. Если возвращается {"type":"error","error":{"type":"authentication_error"}}, сам ключ невалиден и его нужно заменить через консоль Anthropic.

Уровень 2: проблемы с токеном шлюза. Шлюз OpenClaw использует внутренний токен для аутентификации WebSocket-соединений между вашим локальным агентом и службой шлюза. Когда этот токен становится рассогласованным — обычно после перезапуска шлюза, миграции конфигурации или ручного редактирования — вы увидите ошибки «1008 token mismatch». Токен шлюза автоматически генерируется при первоначальной настройке и хранится как в вашей локальной конфигурации, так и в состоянии шлюза. Для его перегенерации необходимо выполнить openclaw models auth setup-token, что создаст новый токен и обновит обе стороны подключения. Для более глубокого анализа проблем аутентификации, специфичных для Anthropic, см. наше детальное руководство по ошибкам API-ключей Anthropic в OpenClaw.

Уровень 3: сбои вышестоящего провайдера. Даже при корректной локальной конфигурации и токенах шлюза аутентификация может завершиться неудачей на уровне API Anthropic. Наиболее распространённые сбои вышестоящего провайдера: истёкшие API-ключи (Anthropic может отозвать ключи за нарушение политики или проблемы с аккаунтом), недостаточный баланс аккаунта (ваш аккаунт Anthropic должен иметь пополнение минимум на $5 для достижения Tier 1, что необходимо для доступа к API по состоянию на февраль 2026 года, согласно platform.claude.com) и ограничения прав доступа (ключи, созданные с ограниченными правами, не могут обращаться ко всем моделям или функциям).

Механизм охлаждения (cooldown). Когда OpenClaw обнаруживает повторяющиеся ошибки аутентификации при обращении к провайдеру, он активирует период охлаждения на 30-60 минут, в течение которого запросы к этому провайдеру не отправляются. Сообщение об ошибке «No available auth profile for anthropic (all in cooldown)» указывает на это состояние. Ваши учётные данные могут быть совершенно валидными — возможно, временный сбой Anthropic вызвал охлаждение. Вы можете дождаться естественного окончания периода охлаждения или перезапустить службу шлюза OpenClaw для немедленного сброса. Механизм охлаждения существует для предотвращения пометки вашего аккаунта за чрезмерное количество неудачных попыток аутентификации, что может привести к окончательному отзыву ключа.

Сравнение методов аутентификации. OpenClaw поддерживает три метода аутентификации для Anthropic, каждый из которых подходит для различных сценариев развёртывания. Прямые API-ключи (формат sk-ant-api03-) — самые простые и рекомендуются для индивидуальных разработчиков и конвейеров CI/CD. OAuth-токены (использование учётных данных подписки Claude) полезны, когда вы хотите избежать управления API-ключами напрямую, но требуют периодического обновления токена. Метод с токеном настройки (openclaw models auth setup-token) предназначен для командных развёртываний, где центральный администратор предоставляет доступ. Выбирайте в зависимости от ваших операционных потребностей: API-ключи для простоты, OAuth для доступа на основе подписки, и токены настройки для управляемых окружений.

Лимиты запросов (429) — заголовки, уровни и предотвращение

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

Anthropic реализует систему лимитов на основе уровней, где более высокие уровни открывают значительно большие квоты. Ваш уровень определяется общей суммой приобретённых кредитов (не потраченных). Понимание вашего текущего уровня и его лимитов — первый шаг к диагностике и предотвращению проблем с лимитами запросов. Следующая таблица отражает текущие лимиты Anthropic по состоянию на февраль 2026 года (проверено через platform.claude.com/docs/en/api/rate-limits):

Скачок от Tier 3 к Tier 4 колоссален — RPM увеличивается в 20 раз, а лимиты токенов — примерно в 16 раз. Для продакшен-развёртываний достижение Tier 4 при покупке кредитов на $400 часто является наиболее экономичным способом полностью устранить проблемы с лимитами запросов.

Чтение заголовков лимита запросов. Каждый ответ от API Anthropic включает заголовки, которые раскрывают текущее состояние вашего лимита запросов. Эти заголовки — ваш самый ценный диагностический инструмент для понимания причин возникновения ошибок 429 и времени их разрешения. Большинство руководств упоминают заголовок retry-after, но упускают полный набор заголовков anthropic-ratelimit-*, обеспечивающих полную видимость потребления квоты:

Когда вы получаете ответ 429, всегда проверяйте anthropic-ratelimit-requests-remaining и anthropic-ratelimit-tokens-remaining, чтобы определить, какое измерение исчерпано. Если оставшиеся запросы равны 0, но оставшиеся токены высоки, вы отправляете слишком много мелких запросов — рассмотрите возможность объединения (батчинг). Если оставшиеся токены равны 0, но оставшиеся запросы положительны, ваши отдельные запросы слишком объёмны — рассмотрите сокращение длины контекста или разделение диалогов.

Ошибочная классификация FailoverError. Особенно коварная проблема, задокументированная в GitHub Issue #10368, приводит к тому, что ошибки лимита запросов ошибочно отображаются как ошибки переполнения контекста. Когда механизм аварийного переключения (failover) OpenClaw активируется во время события лимита запросов, сообщение об ошибке, показанное пользователю, может содержать «context_length_exceeded» вместо «rate_limit_error». Если вы видите ошибки переполнения контекста, которые появляются внезапно (а не постепенно по мере роста диалога), сначала проверьте заголовки лимита запросов — реальной причиной может быть 429, неправильно классифицированный при обработке аварийного переключения.

Для команд, которым нужна более высокая пропускная способность без повышения уровня, распределение запросов между несколькими API-ключами или использование сервиса-ретранслятора, такого как laozhang.ai, может распределить нагрузку по нескольким пулам лимитов, фактически умножая доступную квоту. Этот подход особенно полезен в периоды всплесков, когда временные пики превышают лимиты вашего уровня. Для всестороннего детального разбора стратегий работы с лимитами запросов см. наше полное руководство по лимитам запросов OpenClaw, а для управления расходами наряду с лимитами запросов изучите оптимизацию использования токенов и затрат.

Ошибки запросов (400) — бета-флаги и переполнение контекста

Ошибки запроса с HTTP-кодом 400 указывают на то, что ваш запрос был синтаксически корректным, но семантически неправильным — API понял, что вы отправили, но не может это обработать. В OpenClaw двумя наиболее распространёнными ошибками 400 являются невалидные бета-флаги и превышение длины контекста, каждая из которых требует разных стратегий диагностики и исправления.

Ошибки невалидного бета-флага. Сообщение об ошибке invalid_request_error: Invalid beta flag возникает, когда ваша конфигурация OpenClaw включает бета-флаг, который ваш провайдер не поддерживает. Это особенно часто встречается при использовании Anthropic Claude через сторонних провайдеров, таких как AWS Bedrock или Google Vertex AI, потому что эти провайдеры реализуют подмножество бета-функций Anthropic и могут отставать от прямого API по доступности функций. Например, бета-флаг, который отлично работает с прямым API Anthropic (api.anthropic.com), может не распознаваться конечной точкой Bedrock, вызывая запутанную ошибку 400.

Диагностический подход заключается в определении того, какие бета-флаги включены в вашей конфигурации, и проверке их поддержки вашим конкретным провайдером. Проверьте конфигурацию OpenClaw в ~/.openclaw/openclaw.json на наличие полей beta в настройках модели. Распространённые бета-флаги включают max-tokens-3-5-sonnet-2024-07-15 (для расширенного вывода на моделях Sonnet), prompt-caching-2024-07-31 (для кэширования промптов) и token-counting-2024-11-01 (для подсчёта токенов). Решение — либо удалить неподдерживаемые бета-флаги из конфигурации, либо переключиться на провайдера, который их поддерживает. Пошаговые инструкции см. в нашем подробном руководстве по устранению неполадок с невалидными бета-флагами.

Превышение длины контекста. Ошибка context_length_exceeded возникает, когда общий объём ввода (системный промпт + история диалога + текущее сообщение) превышает контекстное окно модели. Модели Claude в настоящее время поддерживают стандартный контекст в 200 тыс. токенов, с 1 млн токенов в бета-режиме (проверено через platform.claude.com, февраль 2026). В OpenClaw эта ошибка чаще всего возникает в длительных диалогах, где история сообщений накапливается сверх ёмкости модели.

OpenClaw предоставляет встроенный механизм управления историей через параметр конфигурации maxHistoryMessages. По умолчанию OpenClaw сохраняет последние 100 сообщений в контексте диалога. Если ваши диалоги регулярно превышают лимиты контекста, уменьшение этого значения — наиболее прямое решение. Установка maxHistoryMessages на 50 или даже 30 значительно сокращает потребление контекста, сохраняя при этом достаточную историю для связного взаимодействия.

Для программного управления контекстом реализуйте стратегию подсчёта токенов, которая отслеживает накопленные токены и суммирует или обрезает более старые сообщения до того, как общий объём превысит лимит. Это особенно важно для продакшен-приложений, где диалоги могут длиться часами. Ключевой принцип: переполнение контекста никогда не должно быть неожиданностью — реализуйте мониторинг, который предупреждает при 80% использования контекста, чтобы вы могли принять меры до критического сбоя. См. раздел управление длиной контекста в OpenClaw для шаблонов реализации.

Обратите внимание на ошибочную классификацию FailoverError, упомянутую в разделе «Лимиты запросов» — если вы видите ошибки context_length_exceeded, которые появляются внезапно, а не нарастают постепенно в ходе диалога, сначала проверьте статус лимита запросов. GitHub Issue #10368 документирует случаи, когда события лимита запросов ошибочно отображаются как переполнение контекста при обработке аварийного переключения.

Ошибки сервера и подключения (502, 1008, SSL)

Ошибки сервера и подключения указывают на проблемы инфраструктурного уровня между вашим агентом OpenClaw, шлюзом и вышестоящими провайдерами. В отличие от ошибок аутентификации или запросов, эти сбои часто разрешаются сами по себе по мере устранения временных проблем, но их постоянное возникновение требует систематической диагностики сетевого пути.

502 Bad Gateway. Ошибка 502 означает, что шлюз OpenClaw получил невалидный ответ от вышестоящего провайдера. Обычно это указывает на то, что API Anthropic (или другой используемый провайдер) испытывает сбой или снижение производительности. Проверьте страницу статуса Anthropic (status.anthropic.com), чтобы подтвердить наличие известного инцидента. Если страница статуса показывает, что все системы работают нормально, ошибка 502 может быть вызвана сетевой проблемой между вашим шлюзом и конечной точкой API — файрволы, ошибки DNS-разрешения или неправильные конфигурации прокси могут привести к ошибкам 502.

Диагностический подход для стойких ошибок 502 — протестировать сетевой путь напрямую. Используйте curl -v https://api.anthropic.com/v1/messages, чтобы убедиться, что ваш сервер может достичь конечной точки API Anthropic. Обратите внимание на завершение SSL-рукопожатия, корректное DNS-разрешение и успешное TCP-подключение. Если прямое подключение работает, а OpenClaw всё равно показывает 502, проблема, вероятнее всего, в конфигурации прокси шлюза или настройках пула соединений.

1008 Несовпадение токена WebSocket. Код закрытия WebSocket 1008 с сообщением «token mismatch» специфичен для внутренней аутентификации шлюза OpenClaw. Шлюз использует общий секретный токен для аутентификации WebSocket-соединений от вашего локального агента. Когда этот токен становится рассинхронизированным — обычно после перезапуска шлюза без надлежащей миграции токена или после ручного редактирования конфигурационных файлов — каждая попытка WebSocket-подключения мгновенно завершается с ошибкой 1008.

Для исправления необходимо перегенерировать токен шлюза на обеих сторонах подключения. Выполните openclaw models auth setup-token, чтобы сгенерировать новый токен и обновить локальную конфигурацию. Если шлюз работает на удалённом сервере, вам также потребуется скопировать новый токен в конфигурацию шлюза. После перегенерации перезапустите как локального агента, так и службу шлюза, чтобы обе стороны использовали новый токен.

Ошибки SSL-сертификатов. Сбои SSL-рукопожатия в OpenClaw делятся на две категории: проблемы с цепочкой сертификатов (шлюз или вышестоящий API предъявляет сертификат, которому ваша система не доверяет) и истечение срока действия сертификата (сертификат в цепочке истёк). Для самоподписанных сертификатов в средах разработки вы можете настроить OpenClaw на их принятие, установив NODE_TLS_REJECT_UNAUTHORIZED=0 в переменных окружения — но никогда не используйте это в продакшене, так как это отключает всю валидацию сертификатов.

Для корпоративных сред с собственными центрами сертификации добавьте ваш CA-сертификат в хранилище доверия Node.js, установив переменную окружения NODE_EXTRA_CA_CERTS, указывающую на файл пакета CA. Это правильный продакшен-подход для сред с прокси TLS-инспекции или внутренней инфраструктурой PKI.

Устранение неполадок Docker и развёртывания

Docker-развёртывания создают уникальную категорию ошибок OpenClaw, которых не существует при установке на «голое железо». Наиболее коварной является проблема переопределения переменных окружения, задокументированная в GitHub Issue #9028, которая затронула 12+ пользователей до того, как была выявлена. Понимание режимов отказа, специфичных для Docker, критически важно, потому что они могут заставить правильно настроенные установки выглядеть сломанными.

Проблема переопределения OPENCLAW_GATEWAY_TOKEN. При запуске OpenClaw в Docker переменные окружения, установленные в docker-compose.yml или команде docker run, незаметно переопределяют значения из смонтированных конфигурационных файлов. Это означает, что даже если ваш ~/.openclaw/openclaw.json содержит правильный токен шлюза, устаревшая переменная окружения OPENCLAW_GATEWAY_TOKEN из предыдущего развёртывания будет иметь приоритет. Симптом — стойкие ошибки «1008 token mismatch», которые не поддаются всем обычным методам устранения неполадок, поскольку конфигурационные файлы выглядят корректно.

Диагностический подход — проверить наличие переопределений переменных окружения внутри работающего контейнера. Выполните docker exec <container_name> env | grep OPENCLAW, чтобы увидеть все переменные окружения, связанные с OpenClaw. Если OPENCLAW_GATEWAY_TOKEN присутствует в выводе и отличается от значения в смонтированном конфигурационном файле, вы нашли проблему. Решение — либо удалить переменную окружения из конфигурации Docker, либо обновить её до соответствия текущему токену шлюза.

Сетевая конфигурация Docker. Шлюзу OpenClaw необходимо связаться как с вашим локальным агентом, так и с API вышестоящего провайдера. В Docker сеть bridge по умолчанию может помешать шлюзу достучаться до сервисов на хосте или в других контейнерах. Используйте сетевой режим host для простейшей конфигурации или явно настройте сеть bridge с правильным DNS-разрешением. Для развёртываний docker-compose убедитесь, что все сервисы OpenClaw находятся в одной сети:

yaml

version: '3.8'
services:
  openclaw-gateway:
    image: openclaw/gateway:latest
    ports:
      - "18789:18789"
      - "18791:18791"
    volumes:
      - ./openclaw-config:/root/.openclaw
    environment:
      - NODE_ENV=production
      # Do NOT set OPENCLAW_GATEWAY_TOKEN here unless intentional
    networks:
      - openclaw-net

  openclaw-agent:
    image: openclaw/agent:latest
    depends_on:
      - openclaw-gateway
    volumes:
      - ./openclaw-config:/root/.openclaw
    networks:
      - openclaw-net

networks:
  openclaw-net:
    driver: bridge

Права доступа при монтировании томов. Конфигурационные файлы, смонтированные с хоста в Docker-контейнеры, могут иметь неправильные права доступа внутри контейнера, что препятствует чтению или записи конфигурации OpenClaw. Убедитесь, что смонтированные файлы доступны для чтения пользователем контейнера (обычно root в большинстве Docker-образов OpenClaw). Используйте docker exec <container> ls -la /root/.openclaw/ для проверки прав доступа и chmod на хосте при необходимости.

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

Загрузка навыков и ошибки конфигурации

Система навыков OpenClaw расширяет возможности агента через конфигурационные файлы на основе Markdown. Когда навыки не загружаются, агент работает без расширенных возможностей — пользовательские инструменты не отображаются, специализированное поведение не активируется, и агент может казаться «глупым» по сравнению с ожидаемой производительностью. Сбои навыков по умолчанию происходят молча, что делает их обнаружение сложнее, чем явные сообщения об ошибках.

Синтаксические ошибки файлов навыков. Навыки OpenClaw определяются в файлах .md со специфическим форматом frontmatter. Наиболее распространённые синтаксические ошибки: отсутствующий или некорректный YAML-frontmatter (разделители --- должны находиться на отдельных строках), невалидные типы полей (использование строки там, где ожидается список) и проблемы кодировки (символы не в формате UTF-8 в описаниях навыков). Диагностическая команда openclaw skills list показывает все обнаруженные навыки и их статус загрузки. Навыки, которые не удалось распарсить, отображаются с индикатором ошибки и кратким описанием синтаксической проблемы.

Когда файл навыка не удаётся распарсить, OpenClaw логирует конкретную ошибку парсинга, но продолжает загрузку остальных навыков. Это означает, что один сломанный файл навыка не препятствует загрузке других навыков — но также означает, что вы можете не заметить сбой, если не проверите явно. Решение — валидация синтаксиса файла навыка по схеме OpenClaw. Каждый файл навыка должен содержать как минимум поле name, поле description и тело навыка. Необязательные поля, такие как dependencies, permissions и triggers, следуют определённым требованиям формата, задокументированным в справочнике по навыкам OpenClaw.

Требования к структуре каталогов. OpenClaw ищет навыки в определённых каталогах, и неправильное размещение файлов навыков — распространённая причина ошибок «skill not found». Стандартные каталоги навыков: ~/.openclaw/skills/ для навыков уровня пользователя (доступных всем агентам) и .openclaw/skills/ в каталоге проекта для навыков, специфичных для проекта. Навыки, размещённые за пределами этих каталогов, не будут обнаружены загрузчиком навыков OpenClaw.

Сбои разрешения зависимостей. Некоторые навыки объявляют зависимости от внешних инструментов или других навыков. Когда зависимость не может быть удовлетворена — например, навык требует python3, но в среде доступен только python — навык молча пропускается. Проверьте поле dependencies вашего навыка на соответствие доступным инструментам в вашей среде. Выполнение openclaw doctor --fix может выявить и иногда автоматически устранить проблемы зависимостей, установив недостающие инструменты или создав необходимые символические ссылки.

Обработка ошибок в продакшене — логика повторных попыток и переключение между провайдерами

Переход от устранения неполадок в среде разработки к надёжности в продакшене требует реализации систематической обработки ошибок, выходящей за рамки исправления отдельных ошибок. Продакшен-приложения должны классифицировать ошибки, применять соответствующие стратегии повторных попыток, переключаться на альтернативных провайдеров при сбое основных и обеспечивать видимость паттернов ошибок через мониторинг. Следующие реализации охватывают Python и JavaScript — два наиболее распространённых языка для интеграций с OpenClaw.

Классификация ошибок: повторяемые и фатальные. Первое решение в любом конвейере обработки ошибок — повторять или завершиться немедленно. Повтор фатальной ошибки расходует время и квоту; отказ при повторяемой ошибке снижает надёжность. Таблица классификации помогает в принятии решения:

Реализация повторных попыток на Python для продакшена:

python
import time
import httpx
from typing import Optional

class OpenClawRetryHandler:
    def __init__(self, max_retries: int = 3, base_delay: float = 1.0):
        self.max_retries = max_retries
        self.base_delay = base_delay
        self.retryable_codes = {429, 529, 502, 408}

    def execute_with_retry(self, request_fn, **kwargs):
        last_error = None
        for attempt in range(self.max_retries + 1):
            try:
                response = request_fn(**kwargs)
                return response
            except httpx.HTTPStatusError as e:
                last_error = e
                status = e.response.status_code
                if status not in self.retryable_codes:
                    raise  # Fatal error, don't retry
                delay = self._calculate_delay(e.response, attempt)
                print(f"Attempt {attempt+1} failed ({status}), "
                      f"retrying in {delay:.1f}s...")
                time.sleep(delay)
        raise last_error

    def _calculate_delay(self, response, attempt: int) -> float:
        # Prefer retry-after header when available
        retry_after = response.headers.get("retry-after")
        if retry_after:
            return float(retry_after)
        # Exponential backoff with jitter
        import random
        delay = self.base_delay * (2 ** attempt)
        jitter = random.uniform(0, delay * 0.1)
        return min(delay + jitter, 60.0)  # Cap at 60 seconds

Реализация повторных попыток на JavaScript для продакшена:

javascript
class OpenClawRetryHandler {
  constructor({ maxRetries = 3, baseDelay = 1000 } = {}) {
    this.maxRetries = maxRetries;
    this.baseDelay = baseDelay;
    this.retryableCodes = new Set([429, 529, 502, 408]);
  }

  async executeWithRetry(requestFn) {
    let lastError;
    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
      try {
        return await requestFn();
      } catch (error) {
        lastError = error;
        const status = error.status || error.response?.status;
        if (!this.retryableCodes.has(status)) throw error;
        const delay = this._calculateDelay(error, attempt);
        console.log(`Attempt ${attempt+1} failed (${status}), `
          + `retrying in ${(delay/1000).toFixed(1)}s...`);
        await new Promise(r => setTimeout(r, delay));
      }
    }
    throw lastError;
  }

  _calculateDelay(error, attempt) {
    const retryAfter = error.response?.headers?.get?.('retry-after');
    if (retryAfter) return parseFloat(retryAfter) * 1000;
    const delay = this.baseDelay * Math.pow(2, attempt);
    const jitter = Math.random() * delay * 0.1;
    return Math.min(delay + jitter, 60000);
  }
}

Переключение между провайдерами. Для максимальной надёжности настройте OpenClaw с несколькими провайдерами, чтобы при сбое одного запросы автоматически перенаправлялись на альтернативный. Паттерн аварийного переключения расширяет обработчик повторных попыток, перебирая провайдеров перед окончательным отказом. Именно здесь такие сервисы, как laozhang.ai, демонстрируют свою ценность — единый API-интерфейс, маршрутизирующий запросы к нескольким провайдерам моделей (Anthropic, OpenAI, Google) через одну конечную точку, значительно упрощая конфигурацию аварийного переключения.

python
class MultiProviderFailover:
    def __init__(self, providers: list):
        self.providers = providers  # Ordered by preference
        self.retry_handler = OpenClawRetryHandler(max_retries=2)

    def execute(self, request_fn):
        errors = []
        for provider in self.providers:
            try:
                return self.retry_handler.execute_with_retry(
                    request_fn, provider=provider
                )
            except Exception as e:
                errors.append((provider, e))
                print(f"Provider {provider} failed, "
                      f"trying next...")
        raise Exception(
            f"All providers failed: "
            f"{[(p, str(e)) for p, e in errors]}"
        )

Этот паттерн гарантирует, что временный сбой Anthropic, событие лимита запросов или проблема аутентификации у одного провайдера не выведет из строя всё ваше приложение. В сочетании с логикой повторных попыток выше он обеспечивает три уровня устойчивости: повтор в рамках провайдера, переключение между провайдерами и плавная деградация, когда все провайдеры недоступны.

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

Как исправить ошибку «API-ключ OpenClaw не работает»? Начните с команды openclaw status --all, чтобы определить конкретный сбой. Если вывод показывает «No API key found», выполните openclaw onboard для настройки учётных данных Anthropic. Если показывает «invalid bearer token», убедитесь, что ваш ключ начинается с sk-ant-api03- и срок его действия не истёк. Если показывает «all in cooldown», перезапустите шлюз или подождите 30-60 минут до окончания периода охлаждения. Команда автоматического восстановления openclaw doctor --fix решает большинство проблем с ключами, связанных с конфигурацией.

Почему OpenClaw выдаёт «unauthorized», хотя API-ключ правильный? Трёхуровневая аутентификация OpenClaw означает, что «unauthorized» может исходить из трёх разных источников. Ваш ключ может быть валидным для API Anthropic, но токен шлюза может быть рассогласован (ошибка 1008), или переменная окружения, такая как ANTHROPIC_API_KEY, может переопределять вашу конфигурацию старым значением. Проверьте все три уровня: локальная конфигурация (cat ~/.openclaw/openclaw.json | grep -i key), токен шлюза (openclaw models auth setup-token --check) и прямой тест API (команда curl из раздела «Аутентификация» выше).

Как сбросить токен шлюза OpenClaw? Выполните openclaw models auth setup-token для генерации нового токена шлюза. Это обновит как локальную конфигурацию, так и состояние шлюза. Если ваш шлюз работает на удалённом сервере, вам потребуется скопировать новый токен в удалённый конфигурационный файл и перезапустить службу шлюза. После перегенерации перезапустите как локального агента, так и шлюз, чтобы обе стороны использовали обновлённый токен.

Что вызывает лимитирование запросов OpenClaw и как его предотвратить? Лимитирование запросов происходит, когда ваши запросы превышают квоту уровня Anthropic по любому измерению — запросы в минуту (RPM), входные токены в минуту (ITPM) или выходные токены в минуту (OTPM). Наиболее эффективная профилактика — повышение уровня за счёт покупки дополнительных кредитов (Tier 4 за $400 предлагает 4 000 RPM). Для немедленного облегчения реализуйте экспоненциальную задержку с учётом заголовка retry-after, снизьте частоту запросов или распределите нагрузку между несколькими API-ключами.

Как исправить ошибку OpenClaw context_length_exceeded? Сократите историю диалога, установив меньшее значение maxHistoryMessages в конфигурации OpenClaw (по умолчанию 100, попробуйте 30-50). Для программного управления реализуйте подсчёт токенов, который суммирует более старые сообщения до того, как общий объём превысит контекстное окно модели в 200 тыс. токенов. Примечание: если эта ошибка появляется внезапно, а не нарастает постепенно в ходе диалога, проверьте статус лимита запросов — GitHub Issue #10368 документирует случаи ошибочной классификации лимитов запросов как переполнения контекста при аварийном переключении.

Почему навыки OpenClaw не загружаются? Выполните openclaw skills list для проверки статуса загрузки навыков. Распространённые причины: синтаксические ошибки YAML-frontmatter (отсутствующие разделители ---), файлы навыков, размещённые за пределами распознаваемых каталогов (~/.openclaw/skills/ или .openclaw/skills/), и неудовлетворённые зависимости, объявленные в поле dependencies навыка. Команда openclaw doctor --fix может выявить и иногда автоматически устранить проблемы с зависимостями.

Как исправить ошибку Docker «gateway token mismatch» в OpenClaw? Это почти всегда вызвано переменной окружения OPENCLAW_GATEWAY_TOKEN в конфигурации Docker, переопределяющей значение в смонтированных конфигурационных файлах. Выполните docker exec <container> env | grep OPENCLAW для проверки переопределений переменных окружения. Либо удалите переменную окружения из docker-compose.yml, либо обновите её до соответствия текущему токену шлюза в конфигурационном файле.

Есть ли способ протестировать все подключения OpenClaw сразу? Да — openclaw status --all тестирует каждый настроенный провайдер, подключение к шлюзу и состояние аутентификации одной командой. Для целенаправленной проверки доступа к моделям используйте openclaw models status, которая проверяет учётные данные каждого провайдера в реальном времени. Обе команды выдают безопасный для учётных данных вывод, который можно передавать для отладки без раскрытия конфиденциальных значений.