Исправление ошибки OpenClaw Rate Limit Exceeded (429): Полное руководство [2026]

Ошибки ограничения скорости OpenClaw 429 возникают, когда квота вашего AI-провайдера исчерпана или превышен порог запросов в минуту. В отличие от ошибок аутентификации, указывающих на проблемы конфигурации, ошибка 429 означает, что ваша настройка корректна — вы просто достигли лимитов мощности провайдера. Хорошая новость в том, что это почти всегда временное состояние с несколькими эффективными решениями: от простого ожидания 60 секунд до настройки интеллектуальных fallback-моделей, которые автоматически переключают провайдеров при достижении лимитов.

Быстрая диагностика — найдите проблему за 60 секунд

Когда вы сталкиваетесь с ошибкой 429 в OpenClaw, первый шаг — точно определить, какой тип ограничения скорости вы достигли. Не все ошибки 429 одинаковы — некоторые указывают на полное исчерпание месячной квоты, в то время как другие просто означают, что нужно подождать несколько секунд перед следующим запросом. Понимание этого различия определяет, нужно ли вам немедленное решение или долгосрочная стратегия.

Самый быстрый способ диагностики — выполнить openclaw models status в терминале. Эта команда показывает текущее состояние всех настроенных провайдеров: какие находятся в режиме охлаждения, их оставшуюся ёмкость и когда они снова станут доступны. Если вы видите провайдера с пометкой «cooling down» и меткой времени, вы точно знаете, сколько ждать, пока этот провайдер снова примет запросы.

Диагностические команды для немедленного выполнения

Начните с этих трёх команд для полной картины ситуации:

bash

openclaw models status

# Глубокая проверка здоровья с верификацией провайдеров
openclaw status --deep

# Автоматическое исправление распространённых проблем конфигурации
openclaw doctor --fix

Вывод openclaw models status показывает, является ли ограничение временным (активное охлаждение) или основанным на квоте (достигнут дневной/месячный лимит). Если вы видите «cooldown» в статусе, решение обычно — ожидание или переключение провайдеров. Если видите «quota exhausted», нужно либо повысить уровень API, либо настроить альтернативных провайдеров.

Отличие 429 от других ошибок

Прежде чем погружаться в решения по ограничению скорости, убедитесь, что вы действительно имеете дело с ошибкой 429. Сообщение об ошибке должно содержать rate_limit_error или too_many_requests. Если вы видите authentication_error, вы столкнулись с проблемой API-ключа — обратитесь к нашему руководству по устранению ошибки Anthropic API key. Ошибки конфигурации, такие как недопустимые заголовки, выдают совершенно другие коды ошибок.

Настоящий ответ с ошибкой 429 выглядит так:

json
{
  "error": {
    "type": "rate_limit_error",
    "message": "You have exceeded your rate limit. Please retry after 60 seconds."
  }
}

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

Ошибки ограничения скорости в OpenClaw происходят при превышении квот запросов AI-провайдера. Вот что нужно знать:

• Немедленное исправление: Подождите 60 секунд для пополнения token bucket или перезапустите шлюз OpenClaw для сброса охлаждения
• Краткосрочное решение: Настройте fallback-модели в openclaw.json, чтобы запросы автоматически направлялись к резервным провайдерам
• Долгосрочная профилактика: Повысьте уровень API (Anthropic Tier 4 предлагает в 80 раз больше ёмкости, чем Tier 1), реализуйте логику повторных попыток с экспоненциальным откатом и распределите нагрузку между несколькими провайдерами
• Известные баги: Экспоненциальный откат OpenClaw задокументирован, но может не работать как ожидается (Issue #5159), и одна модель, достигшая лимита, может вызвать охлаждение всего провайдера (Issue #5744)
• Ключевые команды: openclaw models status (проверка охлаждения), openclaw status --deep (верификация провайдеров), openclaw doctor --fix (автоисправление)

Немедленные исправления — быстрое восстановление сервиса

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

Вариант 1: Ожидание пополнения Token Bucket (60 секунд)

Большинство AI-провайдеров используют систему ограничения скорости token bucket, которая непрерывно пополняется. Если вы достигли временного ограничения, а не исчерпали дневную квоту, простое ожидание 60 секунд часто решает проблему. За это время bucket пополняется новой ёмкостью запросов. Вы можете отслеживать обратный отсчёт с помощью openclaw models status — наблюдайте, как таймер охлаждения достигает нуля.

Этот подход лучше всего работает, когда вы сделали всплеск запросов за короткий период. Провайдер не заблокировал вас; он просто просит замедлиться. Системы token bucket разработаны для разрешения всплесков с последующими периодами восстановления, поэтому эта временная пауза — ожидаемое поведение, а не признак проблемы конфигурации.

Вариант 2: Перезапуск Gateway для сброса охлаждения

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

bash
# Остановить и перезапустить OpenClaw
openclaw stop
openclaw start

# Или если используется фоновый сервис
systemctl restart openclaw  # Linux
brew services restart openclaw  # macOS

После перезапуска шлюз рассматривает всех провайдеров как новых, без истории охлаждения. Это особенно полезно, когда охлаждение было вызвано багом (например, Issue #5744, где одна модель может вызвать охлаждение всего провайдера), а не фактическими ответами об ограничении скорости от провайдера.

Вариант 3: Переключение на доступного провайдера

Если у вас настроено несколько AI-провайдеров, вы можете немедленно направить запросы к тому, который не ограничен по скорости. Проверьте, какие провайдеры доступны:

bash
openclaw models status

Ищите провайдеров со статусом «available». Затем вы можете либо вручную указать этого провайдера в запросе, либо положиться на автоматический fallback OpenClaw, если он настроен. Для пользователей Claude, достигших лимитов Anthropic, переключение на модели OpenAI или Google обеспечивает немедленное облегчение, пока квота Anthropic восстанавливается.

Понимание ограничений скорости по провайдерам

Каждый AI-провайдер реализует ограничение скорости по-разному, с различными уровнями, лимитами и поведением сброса. Понимание этих различий помогает выбрать правильного провайдера для вашей нагрузки и настроить соответствующие fallback'и, когда один провайдер достигает ёмкости.

Anthropic (Claude)

Anthropic использует систему на основе уровней, где ваша история расходов определяет лимиты. Новые аккаунты начинают с Tier 1 с умеренными лимитами, и уровни автоматически повышаются по мере увеличения расходов:

Переход от Tier 1 к Tier 4 представляет 80-кратное увеличение ёмкости запросов. Если вы регулярно достигаете ограничений скорости Anthropic, проверка текущего уровня через консоль Anthropic должна быть первым шагом. Многие разработчики работают на Tier 1, не осознавая, что небольшая дополнительная покупка значительно увеличит их лимиты.

OpenAI (GPT-4, GPT-4o)

Лимиты OpenAI также основаны на уровнях, но с другими порогами:

Бесплатный уровень OpenAI с всего 3 запросами в минуту крайне ограничен и не подходит для реальной нагрузки. Даже базовый Tier 1 при расходах $5 даёт 166-кратное улучшение ёмкости запросов.

Google (Gemini)

API Gemini от Google имеет как бесплатный, так и платный уровни:

Дневное ограничение бесплатного уровня в 1,500 запросов делает его подходящим в качестве резервного провайдера, но не основного для активной разработки. Платный уровень полностью снимает дневные ограничения.

Стратегический выбор провайдера

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

Настройка Fallback моделей

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

Базовая конфигурация Fallback

В файле конфигурации openclaw.json добавьте массив fallback к конфигурации модели:

json
{
  "models": {
    "claude-sonnet": {
      "provider": "anthropic",
      "model": "claude-3-5-sonnet-20241022",
      "fallback": [
        "gpt-4o",
        "gemini-pro"
      ]
    },
    "gpt-4o": {
      "provider": "openai",
      "model": "gpt-4o"
    },
    "gemini-pro": {
      "provider": "google",
      "model": "gemini-1.5-pro"
    }
  }
}

С этой конфигурацией, когда Claude достигает ограничения скорости, запросы автоматически направляются к GPT-4o. Если GPT-4o тоже ограничен, Gemini Pro служит последним резервом. Это создаёт трёхуровневый слой устойчивости, значительно снижающий вероятность полного прерывания сервиса.

Расширенный Fallback с условиями

Для большего контроля вы можете указать условия fallback:

json
{
  "models": {
    "claude-sonnet": {
      "provider": "anthropic",
      "model": "claude-3-5-sonnet-20241022",
      "fallback": {
        "models": ["gpt-4o", "gemini-pro"],
        "on": ["rate_limit", "timeout", "unavailable"],
        "maxAttempts": 3
      }
    }
  }
}

Массив on указывает, какие типы ошибок вызывают fallback. Установка "on": ["rate_limit"] гарантирует, что fallback активируется только при ограничении скорости, а не при других ошибках, которые могут указывать на проблему конфигурации, требующую изучения.

Использование прокси-сервисов как Fallback

Для профессиональных развёртываний рассмотрите добавление прокси-сервиса, такого как laozhang.ai, в качестве дополнительного уровня fallback:

json
{
  "models": {
    "claude-sonnet": {
      "provider": "anthropic",
      "model": "claude-3-5-sonnet-20241022",
      "fallback": [
        {
          "provider": "laozhang",
          "model": "claude-3-5-sonnet",
          "baseUrl": "https://api.laozhang.ai/v1"
        },
        "gpt-4o"
      ]
    }
  }
}

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

Понимание механизма охлаждения

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

Как срабатывает охлаждение

Когда OpenClaw получает ответ 429 от любого провайдера, он отмечает этого провайдера как «в охлаждении» на рассчитанную продолжительность. Документированная стратегия отката использует экспоненциальные интервалы: 1 минута для первого случая, затем 5, 25 и 60 минут для последующих попаданий в пределах окна. Однако Issue #5159 документирует, что фактическая реализация может отличаться, при этом некоторые пользователи наблюдают гораздо более короткие интервалы в 1-27 секунд.

Охлаждение применяется на уровне провайдера, а не модели. Это означает, что если вы используете Claude Sonnet и достигаете ограничения скорости, Claude Opus также будет отмечен как недоступный, хотя Opus имеет отдельные ограничения скорости в Anthropic. Issue #5744 отслеживает это поведение как известное ограничение.

Token Bucket vs Фиксированное окно

Большинство провайдеров используют ограничение скорости token bucket, которое работает иначе, чем лимиты фиксированного окна:

• Token Bucket: Ёмкость непрерывно пополняется с постоянной скоростью. Вы можете делать всплески запросов, пока в bucket есть токены, и он пополняется даже во время выполнения запросов. Лимит 60 RPM с token bucket означает примерно 1 токен, добавляемый в секунду.

• Фиксированное окно: Ёмкость полностью сбрасывается через определённые интервалы. Лимит 60 RPM с фиксированными окнами означает, что вы можете ждать полную минуту, если исчерпаете своё распределение раньше.

Anthropic и OpenAI используют системы token bucket, поэтому стандартный совет «подождать 60 секунд» часто работает — bucket полностью пополняется к тому времени, даже если вы его полностью опустошили.

Ручной сброс охлаждения

Поскольку состояние охлаждения хранится в процессе шлюза OpenClaw, перезапуск шлюза немедленно сбрасывает все охлаждения. Это безопасно делать, когда вы считаете, что охлаждение было вызвано некорректно (например, багом) или когда вы устранили основную проблему (например, повысили уровень API). После перезапуска OpenClaw будет запрашивать провайдеров заново без памяти об охлаждении от предыдущих сессий.

bash
# Просмотр текущих состояний охлаждения
openclaw models status --verbose

# Сброс всех охлаждений перезапуском
openclaw restart

Известные проблемы и обходные решения

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

Issue #5159: Экспоненциальный откат не работает как задокументировано

Документация OpenClaw описывает интервалы экспоненциального отката 1, 5, 25 и 60 минут. Однако Issue #5159 сообщает, что фактическое поведение значительно отличается, с наблюдаемыми откатами всего 1-27 секунд. Эта проблема закрыта как «не планируется к исправлению», что означает, что вы не можете полагаться на документированное поведение отката.

Обходное решение: Не полагайтесь на внутренний откат OpenClaw. Реализуйте собственную логику повторных попыток на уровне приложения (см. раздел «Реализация логики повторных попыток») или настройте fallback-модели, чтобы вообще не ждать отката.

Issue #5744: Одна модель вызывает охлаждение всего провайдера

Когда одна модель от провайдера достигает ограничения скорости, OpenClaw отмечает весь провайдер как в охлаждении. Это означает, что достижение лимитов на Claude Sonnet также блокирует Claude Opus, хотя они имеют отдельные ограничения скорости в Anthropic.

Обходное решение: Настройте fallback-модели от разных провайдеров, а не разные модели от того же провайдера. Fallback от Claude Sonnet к Claude Opus не поможет, если оба блокируются вместе.

Если вы сталкиваетесь с ошибками, связанными с конфигурацией AWS Bedrock, наряду с ограничениями скорости, ознакомьтесь с нашим руководством по ошибке invalid beta flag при использовании AWS Bedrock — они иногда появляются вместе, когда конфигурации провайдеров неожиданно взаимодействуют.

Issue #4766: Gateway возвращает пустые сообщения (исправлено)

Более ранние версии OpenClaw иногда возвращали пустые ответы при ограничении скорости вместо правильных сообщений об ошибках. Это исправлено в версии 2026.1.x и более поздних, но если вы используете старую версию, вы можете видеть тихие сбои вместо ошибок 429.

Обходное решение: Обновитесь до последней версии OpenClaw командой openclaw update или проверьте обновления в менеджере пакетов.

Сводка известных проблем

Реализация логики повторных попыток

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

Реализация на Python с Tenacity

Библиотека tenacity предоставляет надёжную логику повторных попыток с экспоненциальным откатом и джиттером:

python
from tenacity import retry, wait_random_exponential, stop_after_attempt, retry_if_exception_type
import openai

# Настройка повторов для ошибок ограничения скорости
@retry(
    wait=wait_random_exponential(min=1, max=60),
    stop=stop_after_attempt(6),
    retry=retry_if_exception_type(openai.RateLimitError)
)
def call_openai(messages):
    client = openai.OpenAI(
        base_url="http://localhost:5000/v1",  # Шлюз OpenClaw
        api_key="your-key"
    )
    return client.chat.completions.create(
        model="claude-sonnet",
        messages=messages
    )

# Использование
try:
    response = call_openai([{"role": "user", "content": "Привет"}])
except openai.RateLimitError:
    print("Ограничение скорости сохраняется после 6 попыток")

Функция wait_random_exponential добавляет джиттер для предотвращения проблем «громового стада», когда несколько повторяющих клиентов одновременно обращаются к API.

Реализация на JavaScript

Для приложений Node.js реализуйте аналогичную логику с async/await:

javascript
async function callWithRetry(messages, maxRetries = 6) {
  let lastError;

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch('http://localhost:5000/v1/chat/completions', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': 'Bearer your-key'
        },
        body: JSON.stringify({
          model: 'claude-sonnet',
          messages: messages
        })
      });

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') ||
                          Math.min(Math.pow(2, attempt) + Math.random(), 60);
        console.log(`Ограничение скорости, ожидание ${retryAfter}с (попытка ${attempt + 1})`);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }

      if (!response.ok) {
        throw new Error(`HTTP ${response.status}`);
      }

      return await response.json();
    } catch (error) {
      lastError = error;
    }
  }

  throw lastError;
}

Лучшие практики для логики повторных попыток

При реализации повторов следуйте этим рекомендациям, чтобы не усугубить проблемы с ограничением скорости:

• Добавляйте джиттер: Случайные задержки предотвращают одновременные повторные попытки нескольких клиентов
• Уважайте заголовки Retry-After: Когда провайдеры отправляют этот заголовок, используйте его значение вместо расчёта собственного
• Устанавливайте максимальное число попыток: Бесконечные повторы могут быстрее исчерпать квоты; обычно достаточно 5-6 попыток
• Логируйте попытки повторов: Видимость частоты повторов помогает определить, когда нужно больше ёмкости
• Рассмотрите circuit breaker: После нескольких сбоев временно прекратите повторы, чтобы дать провайдеру восстановиться

Предотвращение и оптимизация

Лучший подход к ограничениям скорости — предотвращение их возникновения в первую очередь. Эти стратегии снижают вероятность достижения лимитов и обеспечивают плавную деградацию вашего приложения, когда лимиты неизбежны.

Мониторинг паттернов использования

Регулярно проверяйте потребление API для выявления тенденций до того, как они станут проблемами:

bash
# Проверить текущий статус по всем провайдерам
openclaw status --deep

# Мониторинг паттернов запросов за время
openclaw logs --filter="429" --since="1h"

Если вы постоянно достигаете лимитов в определённое время (например, в рабочие часы), рассмотрите реализацию очередей запросов или планирование интенсивных операций на непиковые периоды.

Оптимизация эффективности запросов

Сокращение числа вызовов API напрямую снижает давление ограничения скорости:

• Пакетные операции: Объединяйте несколько вопросов в один промпт, где это уместно
• Кэширование ответов: Сохраняйте результаты для идентичных или похожих запросов, чтобы избежать избыточных вызовов API
• Разумное использование стриминга: Стриминговые ответы считаются как один запрос, но держат соединения открытыми дольше
• Правильный выбор модели: Используйте меньшие, более быстрые модели для простых задач; резервируйте мощные модели для сложной работы

Реализация плавной деградации

Проектируйте приложение так, чтобы оно оставалось функциональным даже при ограничении скорости:

• Показывайте значимые состояния ожидания: Вместо общих индикаторов загрузки сообщайте пользователям «Высокий спрос — ответ может занять больше времени»
• Ставьте в очередь несрочные запросы: Позвольте пользователям продолжать работать, пока фоновые запросы ждут ёмкости
• Предлагайте альтернативы: Когда функции ИИ ограничены, переключайтесь на не-ИИ альтернативы, где возможно

Проактивное планирование ёмкости

Ежеквартально пересматривайте свои уровни и повышайте их до того, как достижение лимитов станет рутиной:

• Anthropic: Повышение уровней происходит автоматически на основе расходов, но вы можете предоплатить для более быстрого достижения более высоких уровней
• OpenAI: Аналогичная автоматическая прогрессия; мониторьте панель использования для отслеживания перехода уровней
• Google: Переход с бесплатного на платный уровень полностью снимает дневные лимиты

Для критически важных приложений поддержание отношений с несколькими провайдерами и прокси-сервисами, такими как laozhang.ai, гарантирует, что у вас всегда есть альтернативная ёмкость.

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

Сколько нужно ждать после получения ошибки 429?

Для большинства провайдеров, использующих ограничение скорости token bucket, ожидание 60 секунд позволяет bucket полностью пополниться. Однако оптимальное время ожидания зависит от вашей конкретной ситуации. Проверьте заголовок Retry-After в ответе 429, если он предоставлен — это даёт рекомендуемое время ожидания от провайдера. Если заголовка нет, 60 секунд — безопасное значение по умолчанию. Для более агрессивного восстановления вы можете попробовать снова через 10-15 секунд, поскольку token bucket непрерывно пополняется.

Могу ли я увеличить лимиты скорости без дополнительных трат?

Как правило, нет — ограничения скорости привязаны к вашему уровню расходов у большинства провайдеров. Однако вы можете эффективно увеличить общую ёмкость, распределяя запросы между несколькими провайдерами. Настройка Claude, GPT-4 и Gemini как fallback друг для друга утраивает вашу совокупную ёмкость без увеличения расходов у любого отдельного провайдера. Кроме того, некоторые провайдеры предлагают повышение лимитов для корпоративных клиентов, берущих на себя обязательства по минимальным расходам.

Почему OpenClaw показывает охлаждение, хотя я не делал много запросов?

Обычно это происходит из-за Issue #5744, где одна модель, достигшая лимитов, вызывает охлаждение всего провайдера. Даже если вы использовали только Claude Sonnet, попытка запроса Claude Opus может показаться ограниченной по скорости. Другая распространённая причина — устаревшее состояние охлаждения от предыдущих сессий — попробуйте перезапустить шлюз OpenClaw для сброса накопленных охлаждений.

Нужно ли реализовывать логику повторов, если настроены fallback'и?

Да, они служат разным целям. Fallback'и направляют неудачные запросы к альтернативным провайдерам, обеспечивая немедленную непрерывность. Логика повторов пытается снова обратиться к тому же провайдеру после задержки, что полезно, когда провайдер быстро восстановится. Идеальная настройка использует оба: fallback'и для немедленной доступности, плюс логику повторов внутри каждого fallback для обработки временных лимитов. Этот многоуровневый подход максимизирует вашу вероятность успеха.

Как узнать свой текущий уровень в Anthropic или OpenAI?

Оба провайдера отображают текущий уровень в своих панелях оплаты. Для Anthropic посетите console.anthropic.com и проверьте страницу Настройки > Лимиты. Для OpenAI посетите platform.openai.com/account/limits. Эти страницы показывают ваш текущий уровень, ограничения скорости и сколько ещё нужно потратить для достижения следующего уровня. Если вы только что сделали платёж, уровни обычно обновляются в течение нескольких часов.