Как подключить Hermes Agent к OpenRouter

Как подключить Hermes Agent к OpenRouter? Выберите один из трёх путей: интерактивным hermes model, быстрыми командами hermes config set OPENROUTER_API_KEY и hermes chat --provider openrouter --model, либо ручной правкой ~/.hermes/.env и ~/.hermes/config.yaml. Ключ OpenRouter открывает агенту доступ к более чем 400 моделям от свыше 70 провайдеров через один счёт.

Hermes Agent и модели Hermes 3/4: в чём разница

Путаница возникает потому, что Nous Research выпустила и приложение, и семейство языковых моделей под общим именем. В официальном руководстве OpenRouter это разведено прямо: Hermes Agent — открытый автономный CLI-агент, а Hermes 3 и Hermes 4 — отдельные языковые модели, которые могут служить ему бэкендом. Агент запускается установкой CLI и указанием модели; модель вызывается как model ID через провайдера.

Практический вывод: когда вы ищете «Hermes 3», «Hermes 4» или «Hermes 4 405B», речь обычно о моделях. Агент — это оболочка, которая эти модели запускает. Через OpenRouter агент может работать на любой модели каталога, включая модели Hermes как один из вариантов бэкенда.

Сам агент несёт больше 40 встроенных инструментов: веб-поиск, автоматизацию браузера, понимание изображений. Есть шлюз обмена сообщениями более чем к 20 платформам, включая Telegram, Discord, Slack, WhatsApp, Signal и Matrix. Отдельная особенность — постоянная память между сессиями: детали проекта не приходится повторять при каждом новом разговоре. Разворачивается агент локально или в средах Docker, SSH, Daytona, Modal и Singularity.

Запуск агента бесплатен по лицензии MIT, оплачиваются только токены модели. По данным руководства OpenRouter, Hermes Agent занимает первое место в рейтинге приложений OpenRouter по объёму токенов — более 17 триллионов обработанных токенов. Это объясняет зрелость интеграции: подключение отработано массово.

Создание ключа OpenRouter с лимитом расхода

Первый шаг подключения — ключ. В руководстве OpenRouter подключение описано как два действия: создать API-ключ, затем настроить Hermes на его использование. После настройки агент аутентифицируется в OpenRouter и применяет указанный в конфиге model slug для всех задач.

Порядок создания ключа:

1. Войдите в аккаунт OpenRouter и откройте раздел ключей на openrouter.ai/keys.
2. Создайте новый ключ. Он начинается с префикса sk-or- — этот префикс фигурирует в официальных примерах.
3. Задайте лимит расхода на ключ. Ограничение на ключе удобно тем, что агент может работать часами, а расход остаётся в заданных рамках.
4. Скопируйте ключ сразу: позже полное значение обычно недоступно.
5. Проверьте баланс аккаунта. Ошибки 401 и 403 в разборе ошибок OpenRouter связаны в том числе с отсутствием кредитов.

Ключ хранится как секрет. Документация Hermes Agent разделяет хранение: секреты и токены идут в ~/.hermes/.env, несекретные настройки — в ~/.hermes/config.yaml. Туториал justai.fr описывает то же разделение: секреты лежат в ~/.hermes/.env, настройки — в ~/.hermes/config.yaml. Ключ в репозиторий не коммитят.

Один ключ OpenRouter даёт агенту доступ к 400+ моделям от 70+ провайдеров с автоматическим переключением при сбое для поддерживаемых моделей, поэтому падение одного провайдера не останавливает сессию. Тот же ключ работает в любом кодинг-агенте или ИИ-инструменте.

Лимит расхода на ключе — это ваш инструмент контроля. Агент с длительными задачами тратит токены в фоне, и потолок на ключе ограничивает ущерб от зацикленного или ошибочного запуска. Для пробного запуска разумно начать с небольшого потолка и поднять его после проверки, что сессия идёт через OpenRouter.

Интерактивный путь hermes model и быстрый путь команд

Руководство OpenRouter рекомендует начинать с интерактивного выбора модели:

hermes model

Эта команда проводит через выбор провайдера и настройку модели. CLI Hermes активно развивается, поэтому точный поток шагов может меняться между версиями — сверяйтесь с актуальным cookbook интеграции. При выборе модели убедитесь, что у неё минимум 64K контекста. Рекомендуемый стартовый вариант — ~anthropic/claude-sonnet-latest.

Быстрый путь пропускает интерактив. Ключ сохраняется, и чат стартует сразу:

hermes config set OPENROUTER_API_KEY sk-or-...
hermes chat --provider openrouter --model '~anthropic/claude-sonnet-latest'

Замените sk-or-... на реальный ключ OpenRouter. Команда сохраняет ключ и запускает чат на алиасе ~anthropic/claude-sonnet-latest. Префикс ~ указывает OpenRouter разрешить алиас в последнюю модель этого семейства. Этот путь удобен при программной подготовке агентов, когда интерактивный поток нежелателен.

Документация Hermes Agent описывает тот же принцип распределения значений: hermes config set сам направляет значение в нужный файл. Пример из quickstart — hermes config set OPENROUTER_API_KEY sk-or-... для ключа и hermes config set model anthropic/claude-opus-4.6 для модели.

Успешная настройка узнаётся просто: после hermes chat появляется приглашение Hermes Agent с указанием подключённого провайдера и выбранной модели. Если видите 401 или сообщение «provider not found», обычно это значит, что ключ не сохранился или в имени провайдера опечатка. Повторный запуск команды настройки обычно это исправляет.

Ручной конфиг: .env и config.yaml

Ручной путь даёт полный контроль над файлами. Секреты хранятся в ~/.hermes/.env, настройки модели и провайдера — в ~/.hermes/config.yaml. В .env добавьте ключ и загружайте его из окружения или менеджера секретов:

OPENROUTER_API_KEY=<your-api-key>

В ~/.hermes/config.yaml укажите модель и провайдера:

model:
  provider: openrouter
  default: ~anthropic/claude-sonnet-latest

Этот подход удобен, когда вы версионируете конфигурацию или разворачиваете агентов программно. Функции вроде сжатия, auxiliary-моделей и прочих продвинутых опций настраиваются прямо в config.yaml.

Туториал justai.fr описывает ту же схему хранения: секреты в ~/.hermes/.env, настройки в ~/.hermes/config.yaml. Пути файлов для текущей настройки сверяйте с официальной документацией Hermes и OpenRouter.

Проверьте результат: запустите hermes chat и убедитесь, что в приглашении отображаются провайдер openrouter и выбранная модель. Если модель не отвечает, сверьте model ID в ~/.hermes/config.yaml с валидным значением формата provider/model-name в каталоге openrouter.ai/models.

Ручной конфиг стоит держать минимальным на первом запуске. Документация Hermes Agent советует: если агент не может провести обычный чат, не добавляйте новые функции. Сначала добейтесь одной чистой беседы, затем наслаивайте шлюз, cron, skills, voice или routing. Этот принцип экономит время при отладке.

Требование контекста 64K и фильтр моделей

Контекст — жёсткое ограничение. Большинству конфигураций нужно минимум 64K токенов контекста, и агент может отказаться стартовать с меньшим окном. Системный промпт и схемы инструментов уже занимают значительную часть окна до начала разговора.

Документация Hermes Agent формулирует требование так: агент требует модель минимум с 64 000 токенов контекста. Модели с меньшим окном не удерживают рабочую память для многошаговых сценариев с вызовом инструментов и отклоняются на старте. Большинство хостинговых моделей — Claude, GPT, Gemini, Qwen, DeepSeek — это требование проходят. Для локальной модели задайте размер контекста минимум 64K: например, --ctx-size 65536 для llama.cpp или -c 65536 для Ollama.

Обзор crewclaw.com приводит то же требование: Hermes требует минимум 64K токенов контекста.

Как фильтровать модели по длине контекста:

1. Откройте openrouter.ai/models.
2. Включите фильтр по длине контекста.
3. Убедитесь, что выбранная модель поддерживает минимум 64K токенов.
4. Проверьте цену и возможности модели на той же странице.
5. Зафиксируйте model ID в конфиге.

Руководство OpenRouter указывает требование контекста не меньше 64K. Если запуск не удался, проверьте контекст выбранной модели наряду с ключом и конфигурацией. Выберите модель, которая отвечает документированному требованию; причину конкретного сбоя уточняйте по сообщению об ошибке.

provider_routing и fallback_providers

После подключения маршрутизация в ~/.hermes/config.yaml определяет стоимость, надёжность и обработку сбоев. Три главных элемента файла — provider routing, цепочки fallback и выгрузка на auxiliary-модели — независимы, их можно комбинировать.

На верхнем уровне: выбор модели решает, какая задача уходит на какую модель; provider_routing решает, какой провайдер реально исполняет запрос; если этот провайдер падает, fallback_providers перехватывают запрос без разрыва сессии и потери контекста.

Поля provider_routing:

Документация Hermes Agent по provider routing уточняет значения sort: price — сначала самый дешёвый провайдер, throughput — самый быстрый по токенам в секунду, latency — наименьшее время до первого токена. Поле only задаёт белый список слагов провайдеров в нижнем регистре, ignore — чёрный список, order — явный приоритет, где не указанные провайдеры используются как запасные. data_collection принимает allow или deny и управляет тем, могут ли провайдеры использовать промпты для обучения. Есть также require_parameters: при true OpenRouter маршрутизирует только к провайдерам, поддерживающим все параметры запроса.

Важная оговорка из той же документации: provider routing работает только при использовании OpenRouter. На Nous Portal или прямые подключения провайдеров он не влияет. Nous Portal решает маршрутизацию централизованно по модели и не принимает предпочтения провайдеров от вызывающей стороны.

Суффиксы :nitro и :floor — сокращения уровня запроса для настройки sort. :nitro соответствует sort: throughput и приоритизирует скорость для конкретного запроса, :floor — sort: price и выбирает самого дешёвого доступного провайдера. Они переопределяют provider_routing только для одного вызова.

Fallback-цепочки описываются так:

fallback_providers:
  - provider: openrouter
    model: ~anthropic/claude-sonnet-latest
  - provider: openrouter
    model: ~google/gemini-flash-latest

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

Auxiliary-модели для дешёвых побочных задач

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

auxiliary:
  title:
    provider: openrouter
    model: ~google/gemini-flash-latest
  vision:
    provider: openrouter
    model: ~google/gemini-flash-latest
  compression:
    provider: openrouter
    model: ~google/gemini-flash-latest

Смысл в экономии: дорогую модель вроде Claude Sonnet незачем использовать для простых задач вроде генерации заголовка разговора. Выгрузка на более дешёвую модель, например Gemini Flash, снижает расходы и не меняет основной рабочий процесс. Практическое правило — направлять auxiliary-задачи на самую дешёвую модель, которой вы доверяете для этой работы.

Документация Hermes Agent добавляет, что auxiliary-задачи вроде сжатия и генерации заголовков настраиваются независимо через auxiliary.<task>.extra_body. Provider routing применяется к чат-запросам агента и сводкам по лимиту итераций через поле extra_body.provider.

Для контроля расходов без ручного сравнения моделей есть openrouter/pareto-code:

model:
  provider: openrouter
  model: openrouter/pareto-code

openrouter:
  min_coding_score: 0.65

С этой настройкой OpenRouter выбирает самую дешёвую модель, проходящую заданный порог для каждой задачи кодинга. Оценка кодинга идёт от 0.0 до 1.0: выше значение — сильнее и дороже модель. Стартовая точка — 0.65. Понижайте для рутинных правок, где важнее скорость и цена, повышайте для сложных рефакторингов, где важнее корректность. openrouter/pareto-code управляет основным циклом кодинга, auxiliary — побочными задачами; они работают вместе, и их можно сочетать с :floor для дополнительной экономии.

Как проверить, что запрос ушёл через OpenRouter

Всё, что использует агент, идёт через один API-ключ, поэтому активность видна в одном месте. Запросы, расходы и токены по всем сессиям Hermes Agent отслеживаются на openrouter.ai/activity с фильтрами по модели и временному диапазону.

Порядок проверки:

1. Отправьте в агенте простую задачу и дождитесь ответа.
2. Откройте openrouter.ai/activity.
3. Найдите свежую запись по времени.
4. Отфильтруйте по модели, чтобы убедиться, что запись относится к вашей сессии.
5. Сверьте расход токенов с ожидаемым.

Сведения выбранного маршрута видны в самом агенте: после hermes chat приглашение показывает подключённого провайдера и выбранную модель. Совпадение провайдера openrouter в приглашении и свежей записи в Activity — достаточное подтверждение, что запрос ушёл через OpenRouter.

Различайте уровни: маршрутизация модели и фактический upstream-провайдер за OpenRouter — разные вещи. provider_routing управляет тем, какой субпровайдер внутри OpenRouter исполняет запрос; Activity показывает запросы и расходы, но не стоит придумывать отдельное поле ответа для определения исполнителя. Для проверки базового факта «запрос идёт через OpenRouter» хватает приглашения агента и записи в Activity.

Если запись в Activity не появляется, проверьте, что ключ в ~/.hermes/.env совпадает с ключом, для которого вы смотрите активность. Ключи в аккаунте могут быть несколько, и активность привязана к конкретному ключу.

Таблица выбора модели под задачу

Выбор модели начинается с контекста: большинству конфигураций нужно минимум 64K токенов. После этого смотрите на задачу и цену.

openrouter/auto — опциональный режим маршрутизации: он автоматически выбирает сильную модель под каждый запрос на основе совокупного расхода сообщества OpenRouter за скользящее окно в 7 дней для такого типа задач. Это хорошая стартовая точка, когда предпочтительной модели нет, а нужен надёжный результат без бенчмарков. Когда нужен больший контроль, используйте поля provider routing.

Префикс ~ в model ID — это сокращение маршрутизации: он указывает OpenRouter автоматически разрешить последнюю доступную версию семейства моделей вместо привязки к конкретному релизу. Model ID в OpenRouter используют формат provider/model-name.

OpenRouter также предоставляет более 25 бесплатных моделей от нескольких провайдеров. Бесплатная модель с контекстом 64K+ позволяет собрать малозатратную или нулевую по стоимости конфигурацию для хобби, оставив Pareto-маршрутизацию для задач, которым действительно нужны модели выше качеством. Актуальные цены и доступность бесплатного уровня смотрите на openrouter.ai/pricing.

Типовые ошибки: 401/403, provider not found, отказ на старте

Большинство проблем настройки попадает в две категории. Если Hermes вообще не находит API-ключ, проблема локальная: обычно ключ не сохранён в ~/.hermes/.env. Если ключ есть, но аутентификация не проходит, дело на стороне аккаунта: ключ может быть недействительным, истёкшим, или на аккаунте OpenRouter не осталось кредитов.

Разбор по симптомам:

• 401 или 403. Ключ недействителен, истёк или на аккаунте нет кредитов. Проверьте ключ на openrouter.ai/keys и подтвердите баланс.
• «provider not found». Обычно ключ не сохранён корректно или в имени провайдера опечатка. Повторный запуск команды настройки обычно это исправляет.
• Отказ модели на старте из-за контекста. Если модель работает в других настройках, но отказывается стартовать в Hermes Agent, причина обычно в требовании 64K. Переключитесь на модель с большим контекстом вместо отладки YAML.
• Модель недоступна или странное поведение fallback. Настройки provider routing или fallback слишком агрессивны. Держите routing выключенным, пока базовый провайдер не стабилен.
• Пустые или сломанные ответы. Ошибка аутентификации провайдера или выбора модели. Запустите hermes model снова и подтвердите провайдера, модель и аутентификацию.

Если при доступе к конкретной модели возникает ошибка доступа, проверьте страницу этой модели на openrouter.ai/models: некоторые модели требуют особых условий допуска у провайдера. В большинстве случаев переключение на другую модель решает вопрос.

Документация Hermes Agent предлагает порядок восстановления при сбоях: hermes doctor, затем hermes model, затем hermes setup, затем hermes sessions list, затем hermes --continue, затем hermes gateway status. Эта последовательность быстро возвращает из сломанного состояния в известное рабочее.

Частые вопросы

Hermes Agent и Hermes 3 / Hermes 4 — это одно и то же?

Нет. Hermes Agent — открытое автономное CLI-приложение от Nous Research, а Hermes 3 и Hermes 4 — отдельные семейства языковых моделей той же команды. Агент можно запускать на модели Hermes как бэкенде или на любой модели через OpenRouter. Разница в том, что агент — это приложение, а модели — его «мозг».

Нужны ли отдельные аккаунты провайдеров?

Для большинства поддерживаемых моделей нет. Один ключ OpenRouter даёт Hermes Agent доступ к 400+ моделям от 70+ провайдеров с автоматическим переключением при сбое. Отдельные аккаунты нужны только там, где модель требует особых условий допуска у провайдера.

Какую модель выбрать для старта?

Начните с ~anthropic/claude-sonnet-latest: это документированный дефолт базовой настройки, и он проходит требование 64K контекста. Когда всё заработает, openrouter/auto сам маршрутизирует на сильную модель без вашего выбора, а openrouter/pareto-code оптимизирует стоимость для задач кодинга.

Почему Hermes Agent отклоняет мою модель на старте?

Большинству конфигураций нужно минимум 64K токенов контекста; меньшее окно может не вместить системный промпт и схемы инструментов. Переключитесь на модель с большим контекстом. Фильтруйте по длине контекста на openrouter.ai/models, чтобы найти кандидатов.

OpenRouter берёт доплату за запуск Hermes Agent?

Наценки на цену провайдера нет. Актуальные платформенные сборы и детали биллинга, включая обработку неудачных запросов, смотрите на openrouter.ai/pricing. Сам агент открытый (MIT) и бесплатен в запуске — вы платите только за токены модели.