В мире искусственного интеллекта, где границы между простыми чат-ботами и сложными автономными агентами стираются, надежность инфраструктуры становится критическим фактором успеха. Представьте себе сценарий: ваш AI-агент, работающий через Telegram или Discord, ведет многошаговую беседу с пользователем, выполняет сложные вычисления или управляет внешними инструментами. В этот момент провайдер модели, к которому вы подключены, испытывает сбои. Если у вас нет резервного плана, диалог обрывается, пользователь остается с непонятным сообщением, а доверие к вашему сервису падает. Именно для решения таких задач создается связка OpenClaw и OpenRouter.
OpenClaw — это мощная open-source платформа для запуска AI-агентов, которая объединяет работу с различными мессенджерами (Telegram, Discord, Slack, Signal, iMessage и WhatsApp) в едином интерфейсе. Однако сам по себе OpenClaw не генерирует ответы; ему необходима «мозговая» поддержка в виде модели языка (LLM). Подключение к одному провайдеру напрямую создает хрупкую архитектуру: один ключ, один счет и полная зависимость от стабильности конкретного сервиса. OpenRouter предлагает элегантное решение, выступая в роли универсального шлюза, который дает доступ к более чем 300 моделям от 70+ провайдеров, обеспечивая единое биллинг-окно и автоматический фоллбэк (резервирование) при сбоях.
В этой статье мы подробно разберем, как настроить эту связку, чтобы ваши агенты работали бесперебойно, экономно и безопасно. Мы пройдем путь от базовой команды подключения до тонкой настройки маршрутизации, контроля затрат и устранения распространенных ошибок. Это не просто инструкция по подключению, а руководство по построению устойчивой AI-инфраструктуры.
01Быстрое подключение: одна команда для старта
Самый простой и рекомендуемый способ связать OpenClaw с OpenRouter — использование встроенной команды онбординга. Это минимизирует риск ошибок конфигурации, которые часто возникают при ручном редактировании файлов. Все, что вам нужно, это ваш API-ключ от OpenRouter.
Выполните следующую команду в терминале, заменив переменную окружения на ваш реальный ключ:
openclaw onboard --auth-choice apiKey --token-provider openrouter --token $OPENROUTER_API_KEYЭта команда делает за вас всю грязную работу. Она автоматически записывает ваши учетные данные в конфигурационный файл ~/.openclaw/openclaw.json в домашней директории пользователя, от имени которого запущен OpenClaw. Кроме того, она устанавливает модель по умолчанию на openrouter/auto, что позволяет вам сразу начать работу с гибкой маршрутизацией.
Если вы предпочитаете полный контроль или работаете в среде, где интерактивные команды невозможны, вы можете отредактировать конфигурационный файл вручную. Минимально необходимая конфигурация должна содержать блок env с вашим ключом и блок agents с указанием модели. Вот пример такой структуры:
{
"env": {
"OPENROUTER_API_KEY": "sk-or-..."
},
"agents": {
"defaults": {
"model": {
"primary": "openrouter/openrouter/auto"
},
"models": {
"openrouter/openrouter/auto": {}
}
}
}
}Важный нюанс для серверных развертываний: если вы запускаете OpenClaw как сервис (например, через systemd), переменные окружения из вашего интерактивного профиля оболочки (bashrc, zshrc) не будут загружены. В этом случае обязательно указывайте ключ в блоке env внутри файла конфигурации. Этот блок инжектируется в процесс при его запуске, что гарантирует доступность ключа независимо от того, под каким пользователем или в какой оболочке работает сервис. После изменения ключа не забудьте перезапустить шлюз командой openclaw gateway run.
Чтобы убедиться, что подключение прошло успешно и модели загружены, выполните команду:
openclaw models listЕсли вы видите список доступных моделей, значит, ваш агент готов к работе.
02Синтаксис ссылок на модели: как правильно указывать LLM
OpenClaw использует специфический формат для обращения к моделям через OpenRouter. Понимание этой структуры критически важно, так как ошибки в названии модели — одна из самых частых причин сбоев. Формат выглядит следующим образом:
openrouter/<author>/<slug>
Здесь author — это автор или организация, создавшая модель (например, anthropic, google, meta-llama), а slug — уникальный идентификатор конкретной модели.
Версионирование и отслеживание обновлений
Одной из мощных особенностей OpenRouter является возможность отслеживания версий. Если вы добавите символ тильды (~) перед именем автора, вы будете автоматически использовать последнюю версию модели в этой семействе. Это удобно для получения актуальных улучшений без необходимости постоянно менять конфигурацию. Если же вам нужна стабильность и предсказуемость, уберите тильду — это зафиксирует конкретную версию модели.
Обратите внимание: идентификаторы моделей могут меняться по мере выхода новых версий. Поэтому перед тем как жестко закрепить модель в продакшене, рекомендуется проверить актуальный slug на странице моделей OpenRouter.
Вот примеры корректных ссылок для популярных моделей:
- Claude Sonnet (последняя версия):
openrouter/~anthropic/claude-sonnet-latest - Gemini Flash (последняя версия):
openrouter/~google/gemini-flash-latest - DeepSeek:
openrouter/deepseek/deepseek-chat - Kimi (последняя версия):
openrouter/~moonshotai/kimi-latest - Llama 3.3 70B:
openrouter/meta-llama/llama-3.3-70b-instruct
Суффиксы маршрутизации
Помимо базового пути, вы можете использовать суффиксы для изменения поведения маршрутизации для одной и той же модели. Это позволяет тонко настраивать баланс между скоростью, стоимостью и качеством ответов:
:free— маршрутизирует запрос к бесплатному эндпоинту. Идеально для тестов или простых задач, где не требуется высокая точность.:nitro— сортирует провайдеров по пропускной способности (throughput). Выбирает самых быстрых провайдеров, что критично для интерактивных приложений.:thinking— запрашивает расширенное рассуждение (extended thinking). Полезно для сложных логических задач, где модели нужно «подумать» перед ответом.
Чтобы изменить модель для конкретного агента в будущем, просто обновите поле agents.defaults.model.primary в конфигурации и перезапустите шлюз.
Особенность Auto Router
Самый важный момент, который часто вызывает путаницу: Auto Router (автоматический маршрутизатор) ссылается как openrouter/openrouter/auto. Здесь первый openrouter — это префикс провайдера, а второй openrouter — это имя автора (так как Auto Router является собственным продуктом OpenRouter), а auto — это slug. Двойное openrouter выглядит странно, но это правильный формат. Ошибка в этом пути — главная причина ошибки «unknown model».
:nitro для агентов, работающих в реальном времени (например, в чатах), чтобы минимизировать задержки. Для фоновых задач, таких как анализ документов, суффикс не обязателен.03Отказоустойчивость: как сохранить агента при сбое провайдера
В отличие от единичного API-запроса, который можно просто повторить при ошибке, AI-агент, ведущий многошаговую беседу, хранит состояние. Если запрос прерывается посередине диалога, пользователь может получить сообщение, которое кажется отправленным, но на самом деле не дошло, или инструмент, который вызвался, но не вернул результат. Это разрушает пользовательский опыт.
OpenRouter решает эту проблему на двух уровнях: автоматический фоллбэк провайдеров и явные фоллбэки моделей.
Автоматический фоллбэк провайдеров
Большинство популярных моделей на OpenRouter обслуживаются несколькими провайдерами. Если первый провайдер, выбранный для вашего запроса, недоступен или ограничивает скорость (rate-limiting), OpenRouter автоматически перенаправляет тот же запрос другому провайдеру. Вам не нужно настраивать это вручную. Вы платите только за успешный запрос. Это работает «из коробки» и не требует дополнительных конфигураций.
Явные фоллбэки моделей
Иногда проблема может быть не в провайдере, а в самой модели (например, модель временно недоступна у всех провайдеров). В этом случае на помощь приходит массив fallbacks. Вы можете указать список моделей, которые OpenRouter будет пытаться использовать по очереди, если основная модель не отвечает.
Пример конфигурации с фоллбэками:
"agents": {
"defaults": {
"model": {
"primary": "openrouter/~anthropic/claude-sonnet-latest",
"fallbacks": [
"openrouter/~google/gemini-flash-latest",
"openrouter/deepseek/deepseek-chat"
]
}
}
}В этом примере, если Claude Sonnet недоступен, система попробует Gemini Flash, а затем DeepSeek. Эти два механизма работают совместно: сначала OpenRouter пытается найти работающего провайдера для основной модели, и только если это невозможно, он переходит к следующей модели из списка фоллбэков. Вы можете проверить, какая именно модель была использована, посмотрев на поле model в ответе API.
data_collection и zdr для фильтрации провайдеров, которые не сохраняют данные запросов. Полный список таких провайдеров доступен в документации OpenRouter.04Контроль затрат: сопоставление моделей и агентов
Использование одной мощной и дорогой модели для всех задач агента — это расточительно. Разные задачи требуют разного уровня интеллекта. Исследовательский агент, анализирующий длинные документы, нуждается в сильной модели. Агегат-суммаризатор, обрабатывающий короткие тексты, отлично справится с бесплатной моделью Llama. Бот, отвечающий на простые вопросы, может использовать Gemini Flash.
Использование Auto Router для экономии
Auto Router (openrouter/openrouter/auto), работающий на базе технологии NotDiamond, автоматически выбирает наиболее экономичную модель для каждого запроса и взимает стандартную ставку этой модели без дополнительных комиссий за маршрутизацию. Это отличный выбор для агентов, которые выполняют много низкоуровневых задач, таких как проверки статуса (heartbeats) или простые ответы.
Ручное распределение моделей по агентам
Для полного контроля вы можете назначить разные модели разным агентам, используя поле agents.overrides. Это позволяет оптимизировать затраты, используя дорогие модели только там, где это действительно необходимо.
Пример конфигурации с разными моделями для разных агентов:
"agents": {
"overrides": {
"researcher": {
"model": {
"primary": "openrouter/anthropic/claude-opus-4.6"
}
},
"summarizer": {
"model": {
"primary": "openrouter/meta-llama/llama-3.3-70b-instruct:free"
}
}
}
}В этом примере агент «researcher» использует мощную и дорогую Claude Opus, а агент «summarizer» — бесплатную версию Llama. Это значительно снижает общие затраты на использование.
Что касается стоимости, OpenRouter не завышает цены провайдеров. При оплате по факту использования (pay-as-you-go) комиссия платформы составляет 5.5%, что покрывает единое биллинг-окно, фоллбэк и доступ ко всем провайдерам. Для низкоуровневых задач доступно более 20 бесплатных моделей, стоимость токенов в которых равна нулю. Если вы используете свои ключи провайдеров (BYOK), комиссия составляет 5%, но она отменяется для первых 1 миллионов запросов в месяц. Отслеживать расходы по моделям можно на панели Activity в личном кабинете OpenRouter.
05Устранение распространенных ошибок подключения
Даже при правильной настройке могут возникнуть проблемы. Вот как исправить самые частые ошибки:
Ошибка: «No API key found for provider 'openrouter'»
Это означает, что ключ не доходит до OpenClaw. Проверьте, правильно ли установлена переменная окружения, выполнив echo $OPENROUTER_API_KEY. Также проверьте конфигурацию аутентификации командой openclaw auth list. Если ключ не найден, повторно запустите команду onboard. На виртуальных серверах (VPS) частая причина в том, что переменная загружается в интерактивной оболочке, но не доступна для сервиса. В этом случае обязательно укажите ключ в блоке env конфигурационного файла.
Ошибка: «unknown model: openrouter/auto»
Это указывает на неправильный формат ссылки на Auto Router. Правильный путь — openrouter/openrouter/auto. Убедитесь, что вы добавили эту модель в раздел agents.defaults.models. OpenClaw ожидает полный путь в формате openrouter/<author>/<slug>, и для Auto Router автором является openrouter.
Ошибка: «OpenRouter not responding»
Это означает, что запросы уходят, но ответа нет. Проверьте следующее:
1. Убедитесь, что у вас есть кредитный баланс на openrouter.ai/keys.
2. Выполните openclaw models list, чтобы убедиться, что slug модели разрешается корректно.
3. Запустите openclaw logs --follow, чтобы увидеть детальную ошибку.
4. Проверьте, что ваш сервер может достичь https://openrouter.ai/api/v1. Блокировка исходящего трафика (egress rule) на вашем сервере или фаерволе часто является причиной этой проблемы.
Ошибки 401 или 403
Это ошибки на стороне аккаунта: ключ недействителен, отозван или на счету недостаточно средств. Проверьте ключ на openrouter.ai/keys, обновите env.OPENROUTER_API_KEY в конфигурации и перезапустите шлюз.
06Часто задаваемые вопросы (FAQ)
Как подключить OpenClaw к OpenRouter?
Выполните команду openclaw onboard --auth-choice apiKey --token-provider openrouter --token "$OPENROUTER_API_KEY". Она запишет ваши учетные данные и установит модель openrouter/auto. Вам не нужно настраивать базовый URL или блок models.providers.
Какой формат ссылок на модели использует OpenClaw?
Формат openrouter/<author>/<slug>, например, openrouter/deepseek/deepseek-chat. Добавьте ~ перед автором, чтобы отслеживать последнюю версию (например, openrouter/~anthropic/claude-sonnet-latest), или добавьте :free, :nitro или :thinking для изменения поведения маршрутизации.
Как исправить ошибку «unknown model: openrouter/auto»?
Используйте openrouter/openrouter/auto и добавьте ее в agents.defaults.models. OpenClaw ожидает полный путь, и автором Auto Router является openrouter.
Можно ли использовать бесплатные модели OpenRouter с OpenClaw?
Да. Добавьте :free к ссылке, например, openrouter/meta-llama/llama-3.3-70b-instruct:free. Рекомендуется использовать фоллбэк, чтобы агент продолжал работать, если бесплатный слот занят.
Нужно ли настраивать базовый URL для OpenClaw?
Нет. Встроенная поддержка OpenRouter в OpenClaw обрабатывает маршрутизацию внутренне. Просто установите API-ключ и укажите модели с помощью формата openrouter/<author>/<slug>.
07Что это значит на практике
Интеграция OpenClaw с OpenRouter — это не просто техническая настройка, это стратегическое решение для создания надежных и экономичных AI-продуктов. Вы получаете доступ к экосистеме из сотен моделей, не привязываясь к одному вендору. Это позволяет вам гибко масштабироваться, экспериментировать с новыми моделями и обеспечивать бесперебойную работу ваших агентов даже в условиях нестабильности сетевой инфраструктуры.
Для разработчиков в России и странах СНГ эта связка особенно актуальна. Используя OpenRouter, вы обходите потенциальные ограничения прямых подключений к некоторым западным провайдерам, получая при этом доступ к передовым моделям через единый интерфейс. Локальный запуск OpenClaw на вашем сервере или VPS, с ключом OpenRouter, позволяет полностью контролировать данные и затраты, что критически важно для коммерческих проектов.
Начните с простой настройки, используйте Auto Router для начального тестирования, а затем постепенно внедряйте фоллбэки и распределение моделей по агентам для оптимизации. Эта архитектура обеспечит вам стабильность, гибкость и контроль над расходами, что является фундаментом для успешного внедрения AI-агентов в любые бизнес-процессы.
Источник: OpenRouter ↗