opencode-rate-limit: плагин для автопереключения моделей при 429 в OpenCode

429 Too Many Requests во время активной сессии в OpenCode ломает поток — приходится вручную идти в настройки, менять модель и заново объяснять контекст новой модели. Решение — плагин opencode-rate-limit, который перехватывает 429/quota-ошибки от AI-провайдеров и переключается на следующую модель из пула без потери контекста и без участия разработчика.

Проблема

OpenCode позволяет работать с разными AI-провайдерами — Claude, Gemini, OpenAI. Это мощно. Но у каждого провайдера есть rate limits. Claude Sonnet — лимит по RPM. Gemini Pro — квота по дню. Если активно используешь несколько агентов или работаешь интенсивными сессиями, ты будешь видеть 429 регулярно.

Проблема не в том, что лимит существует. Проблема в том, что при hit-е лимита OpenCode останавливается и ждёт тебя. Ты должен сам заметить, сам пойти переключить, сам объяснить контекст. Это стоит минуты — каждый раз. А минута выброшенная из потока это не минута, это 10-15 минут на возврат концентрации.

Я хотел: если Claude упёрся в лимит — автоматически взять Gemini. Если Gemini тоже — взять Flash. Без моего участия, без потери контекста, прозрачно.

Решение

Написал OpenCode плагин — opencode-rate-limit. Он перехватывает HTTP ответы от AI-провайдеров, детектирует 429/quota errors и переключается на следующую модель из твоего пула.

Установка — два шага.

Шаг 1. Добавить плагин в opencode.json:

{
  "plugins": ["opencode-rate-limit"]
}

OpenCode сам скачает пакет при следующем запуске. Можно также поставить вручную: npm install opencode-rate-limit.

Шаг 2. Создать файл конфигурации ~/.opencode/rate-limit-fallback.json:

echo '{
  "fallbackModels": [
    { "providerID": "anthropic", "modelID": "claude-sonnet-4-20250514" },
    { "providerID": "google", "modelID": "gemini-2.5-pro" },
    { "providerID": "google", "modelID": "gemini-2.5-flash" }
  ]
}' > ~/.opencode/rate-limit-fallback.json

Готово. Следующий раз когда Claude упрётся в лимит — плагин незаметно переключится на Gemini Pro. Ты продолжишь работать.

Что происходит под капотом

Несколько вещей, которые мне было важно сделать правильно.

Circuit Breaker. Если модель стабильно падает — она не просто уходит в cooldown, она отключается. Зачем тратить запросы на модель которая точно не ответит?

Cooldown с памятью. Модель вернётся в пул через заданное время. По умолчанию 60 секунд. Настраивается.

Dynamic prioritization. Плагин читает SQLite базу данных OpenCode (~/.opencode/data/opencode.db) и видит историю ретраев за последние 30 дней. Модель с меньшим количеством сбоев поднимается в приоритете автоматически.

Контекст не теряется. Переключение происходит в рамках той же сессии OpenCode. Агент продолжает с того места где остановился.

Расширенная конфигурация (для тех кто хочет больше контроля):

{
  "enabled": true,
  "cooldownMs": 60000,
  "fallbackMode": "cycle",
  "fallbackModels": [
    { "providerID": "anthropic", "modelID": "claude-sonnet-4-20250514" },
    { "providerID": "google", "modelID": "gemini-2.5-pro" }
  ],
  "retryPolicy": {
    "maxRetries": 3,
    "strategy": "exponential",
    "baseDelayMs": 1000,
    "jitterEnabled": true
  },
  "circuitBreaker": {
    "enabled": true,
    "failureThreshold": 5,
    "recoveryTimeoutMs": 60000
  },
  "dynamicPrioritization": {
    "enabled": true,
    "updateInterval": 10
  }
}

fallbackMode: "cycle" — крутится по кругу пока хоть кто-то живой. "stop" — останавливается когда все исчерпаны.

Мониторинг

Внутри OpenCode доступна команда /rate-limit-status. Она выводит markdown-отчёт: какие модели активны, сколько fallback-ов было за сессию, кто сейчас на cooldown, исторические данные за 30 дней.

Команда устанавливается автоматически при загрузке плагина.

Если хочется дебажить подробнее — добавь "verbose": true в конфиг и в консоль OpenCode пойдут логи каждого решения circuit breaker-а.

Pro Tips: Как получить максимум

• Добавь 3+ модели в пул — Claude + Gemini Pro + Gemini Flash даёт тройное перекрытие. Шанс что все три упрутся одновременно близок к нулю.
• Gemini Flash как последний резерв — у него щедрый бесплатный tier и очень высокий RPM. Хорошо работает как safety net.
• Следи за /rate-limit-status после тяжёлых сессий — видно какие модели работали больше всего и можно перераспределить нагрузку.

Common Pitfalls: Где люди ошибаются

• Только одна модель в пуле — тогда это просто retry с cooldown. Смысл плагина в нескольких провайдерах.
• Невалидный JSON в конфиге — плагин молча не запускается. Проверь через cat ~/.opencode/rate-limit-fallback.json | python3 -m json.tool.
• Неверный modelID — OpenCode вернёт ошибку при попытке переключиться. Проверяй точные идентификаторы в документации провайдера.

Плагин опубликован на npm: opencode-rate-limit. Исходники и issues — на GitHub.

Если этот плагин экономит время на рутинном переключении моделей, другой похожий инструмент — ponytail для Claude Code — экономит время на поиске мёртвого кода и неиспользуемых зависимостей в проекте.