Как подключить GPT, Claude или другую модель к Hermes Agent

Пошагово подключаем модель к Hermes Agent: выбираем провайдера и способ доступа, проверяем активный маршрут и разбираем ошибки 401, 403, 404 и 429.

Hermes Agent установлен, команда запускается, но до рабочего диалога ещё один шаг: нужно выбрать провайдера, способ авторизации и конкретную модель. Ошибка на этом этапе часто выглядит одинаково: Hermes не отвечает, показывает 401, 403, Model not found или упирается в 429. Причины при этом разные.

В этом гайде вы подключите модель через поддерживаемого провайдера или OpenAI-совместимый endpoint, проверите активную настройку без публикации секретов и отделите проблему модели от проблемы инструментов или Telegram Gateway.

Для первичной настройки откройте обычный терминал вне активного диалога Hermes и выполните:

hermes model

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

hermes chat --oneshot -q "Ответь одним словом: готово"

Внутри открытого диалога /model показывает и меняет модель. Для нового провайдера, которому нужны OAuth, API-ключ или настройка endpoint, используйте hermes model в терминале. Если отсутствует только модель у уже доступного провайдера, обновите каталог через /model --refresh или укажите точный provider:model. У провайдеров без ключа и аккаунта возможен выбор без предварительной авторизации, например /model free.

Для работы Hermes с инструментами официальная документация требует контекстное окно не менее 64 000 токенов. Модель с меньшим окном может быть отклонена при запуске. У локального сервера проверьте фактически выделенный контекст, а не только максимум в описании модели: настройка сервера по умолчанию может быть меньше. Значение model.context_length в Hermes должно соответствовать возможностям и настройке сервера; само по себе оно не увеличивает серверное окно.

До начала ответьте на три вопроса:

1. Какая модель вам нужна для реальной задачи?
2. Через какого провайдера вы получаете к ней доступ?
3. Кто выставляет счёт и где действуют лимиты: подписка, API-аккаунт или ваш сервер?

Если Hermes ещё не установлен, сначала пройдите гайд «Как установить Hermes Agent на VPS». Здесь считаем, что команда hermes уже доступна в терминале.

Проверьте, какой профиль и какие файлы вы собираетесь менять:

hermes config path
hermes config env-path
hermes config check

Первая команда показывает активный config.yaml, вторая — файл секретов текущего профиля. Это защищает от частой ошибки: модель настраивают в одном профиле, а запускают Hermes или Gateway в другом.

Hermes нужен как минимум один провайдер, который выполняет запросы к модели. Подключение возможно через встроенный провайдер, который Hermes знает напрямую, либо через OpenAI-совместимый endpoint.

Nous Portal

Nous Portal — рекомендуемый в официальной документации путь для Hermes Agent. Один OAuth-вход открывает доступ к каталогу моделей по правилам вашей подписки Nous.

Для первой настройки можно выполнить:

hermes setup --portal

Эта команда также включает Tool Gateway. Если нужен только выбор провайдера модели, начните с hermes model. На уже настроенной установке выберите в этом мастере Nous Portal. Мастер откроет OAuth-вход и сохранит поддерживаемую конфигурацию без ручного копирования токена.

GPT и Codex

Для прямого OpenAI API нужен отдельный API-ключ провайдера. Подписка ChatGPT и API-биллинг — разные способы доступа.

Hermes также поддерживает ChatGPT/Codex OAuth через пункт ChatGPT or Codex Subscription в мастере hermes model. Официальная документация Hermes описывает device-code вход, но не фиксирует, какие тарифы ChatGPT подходят и как именно расходуются их лимиты. Проверяйте доступ и квоту в своём аккаунте OpenAI, не считайте подписку универсальной заменой API.

Claude

Claude можно подключить прямым Anthropic API-ключом. Это pay-per-token биллинг API, независимый от обычной потребительской подписки.

OAuth-путь Anthropic в текущей документации Hermes работает только с Claude Max и дополнительно купленными extra usage credits. Базовый лимит Max не расходуется Hermes, а Claude Pro для этого OAuth-пути не подходит. Если условия не подходят, используйте Anthropic API-ключ.

Gemini и другие провайдеры

Для Gemini в Hermes документирован API-ключ Google AI Studio или Vertex AI с биллингом Google Cloud. Потребительский тариф Gemini сам по себе не является документированным OAuth-способом подключения.

OpenRouter, MiniMax, DeepSeek, Kimi, GLM и другие поддерживаемые провайдеры имеют собственные переменные, тарифы и каталоги моделей. Не переносите настройки одного сервиса в другой только потому, что названия моделей похожи.

Свой или локальный сервер

Для обычного OpenAI-совместимого подключения сервер должен поддерживать Chat Completions, обычно по маршруту /v1/chat/completions. В мастере hermes model выберите custom endpoint, укажите базовый URL, API-ключ, если сервер требует авторизацию, и точный model ID. Имя переменной key_env используется при отдельной настройке именованного провайдера; это не значение API-ключа в мастере. Hermes также поддерживает другие API-транспорты у именованных провайдеров, поэтому сверяйте выбранный режим с документацией сервера.

Для своего сервера также нужна поддержка вызова инструментов выбранной моделью и её серверной реализацией. У vLLM необходимо включить автоматический выбор инструмента и выбрать parser, подходящий семейству модели; универсального parser для всех моделей нет. Если вместо вызова инструмента вы видите JSON обычным текстом, проверьте настройки tool calling по официальной документации сервера. При отказе из-за малого контекста согласуйте окно сервера и model.context_length в Hermes; для Ollama окно настраивается на стороне сервера, а не запросом к OpenAI-совместимому API.

Не копируйте чужой config.yaml целиком. В нём могут быть другой адрес, другая модель, другой профиль и лишние настройки, которые трудно диагностировать.

Закройте активный диалог Hermes или откройте отдельный терминал. Запустите:

hermes model

Дальше:

1. Выберите провайдера.
2. Выберите способ доступа, который этот провайдер реально поддерживает.
3. Завершите OAuth либо введите API-ключ локально.
4. Выберите модель из каталога провайдера или укажите точный ID для совместимого сервера.
5. Сохраните выбор как настройку по умолчанию.
6. Запустите новый диалог Hermes.

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

Это две разные команды.

• hermes model запускается в терминале. Она добавляет провайдера, проводит OAuth, принимает ключи, настраивает endpoint и сохраняет default.
• /model вводится внутри диалога Hermes. Она показывает и меняет модель, в том числе по точному provider:model.

Если отсутствует только модель у уже доступного провайдера, обновите каталог через /model --refresh или укажите точный provider:model. Отсутствие модели в списке не означает, что провайдер не авторизован. Для нового провайдера, которому нужны OAuth, API-ключ или настройка endpoint, используйте hermes model в терминале. Провайдеры без ключа и аккаунта могут быть доступны сразу, например через /model free. Обычно выбор действует в текущей сессии; --global сохраняет его как настройку по умолчанию. Если настройка по умолчанию ещё не задана, первый выбор сохраняется; поведение также может менять model.persist_switch_by_default. Смена модели сбрасывает кэш контекста запроса: может потеряться скидка за кэшированный контекст и увеличиться стоимость следующего запроса. Условия зависят от провайдера и тарифа.

Начните со статуса без публикации секретов:

hermes status --all
hermes auth list
hermes auth status <provider>

Замените <provider> на ID выбранного встроенного провайдера. Сопоставьте модель и провайдера из статуса с выбранной настройкой, а в списке авторизаций проверьте наличие учётных данных и отметки об ограничениях. hermes auth status показывает сохранённое состояние авторизации; для API-ключа это может быть лишь проверка его наличия, без запроса к провайдеру. Для custom endpoint отсутствие записи в этом статусе само по себе не доказывает сбой. Фактический доступ подтверждает тестовый запрос ниже. Перед пересылкой вывода просмотрите его и удалите лишние идентификаторы.

Затем проверьте выполнение запроса к модели:

hermes chat --oneshot -q "Ответь одним словом: готово"

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

Hermes Agent простым языком — это связка модели, памяти, инструментов и правил работы. Модель создаёт ответы и решения. Browser, web search, MCP, терминал и другие инструменты имеют собственные настройки и доступы.

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

hermes tools --summary

Кроме того, vision, compression и другие вспомогательные задачи могут использовать отдельный auxiliary model route. Не требуйте, чтобы каждый tool call обязательно шёл через ту же модель, что и основной диалог.

Команда hermes tools открывает настройку инструментов. Вывод hermes tools --summary показывает их состояние, но сам по себе не проверяет выполнение. После настройки выполните один безопасный вызов нужного инструмента.

Сначала добейтесь стабильной работы одного provider:model. Затем, если нужен резерв на случай 429, 5xx, auth failure или недоступности сервиса, настройте cross-provider fallback:

hermes fallback add
hermes fallback list

Credential pool и fallback решают разные задачи. Pool переключает несколько credentials одного провайдера. Fallback переходит на другой provider:model и срабатывает после обработки credentials и retries. Отдельная официальная страница Fallback Providers описывает переключение на текущий запрос пользователя и возврат к основному маршруту на следующем запросе с учётом времени сброса ограничения. Возврат зависит от состояния лимита: пока время его сброса не наступило, Hermes может оставаться на резервном провайдере. Для своей версии проверьте фактический маршрут следующего запроса.

401 Unauthorized

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

hermes config env-path
hermes auth status <provider>

Для OAuth Hermes сначала пытается обновить токен. Если обновление не удаётся, пройдите вход заново через hermes auth add <provider> или мастер hermes model.

403 Forbidden

Учётные данные могут быть действительны, но не иметь доступа к модели, тарифу, организации или региону. Не меняйте ключ вслепую. Сначала проверьте права доступа и доступность выбранной модели в кабинете провайдера, затем выберите разрешённую модель.

404 или Model not found

Вероятные причины: неверный model ID, модель отсутствует в каталоге выбранного провайдера, указан неправильный endpoint или маршрут не поддерживает нужный API. Для доступного провайдера обновите каталог через /model --refresh или укажите точный provider:model. Если нужно изменить авторизацию или endpoint, откройте hermes model в терминале. Для custom endpoint сверяйте ID с ответом именно вашего сервера.

429 Rate limit или quota

429 может быть кратковременным ограничением частоты либо исчерпанной квотой. Смотрите текст ответа, Retry-After и время сброса. После обычного 429 Hermes может повторить запрос, а при повторном отказе переключить credential или fallback. Ограничение тарифа обычно не исчезает от мгновенного повтора.

Проверьте состояние пула:

hermes auth list

Не добавляйте запасные credentials до понимания того, какой аккаунт оплачивает запросы.

500, 502 или 503

Это ошибки сервера или перегрузки. Не меняйте все настройки одновременно. Зафиксируйте время, provider, model и endpoint, проверьте страницу статуса провайдера и повторите короткий тест после паузы. При настроенном fallback Hermes может перейти на резерв после исчерпания retries.

CLI отвечает, а Telegram нет

Успешный ответ в CLI подтверждает только проверенный маршрут модели. У Telegram могут быть отдельные настройки модели для платформы или канала. Сравните их, а затем проверьте Gateway, профиль и настройки Telegram. Проверьте:

hermes gateway status
hermes gateway list

Сравните профиль Gateway с профилем, где вы выполняли hermes model. Перезапуск Gateway относится к отдельной операционной процедуре: сначала убедитесь, что меняете нужный процесс и профиль.

Считайте этап пройденным, когда выполнены все проверки:

1. hermes config check не показывает обязательных пропусков.
2. Для встроенного провайдера проверено сохранённое состояние через hermes auth status <provider>; для custom endpoint сверены адрес, model ID и способ доступа. Рабочую авторизацию подтверждает реальный запрос, а не один статус.
3. Новый диалог отвечает на короткий запрос без HTTP-ошибки.
4. Модель справляется с одним реальным вопросом из вашей задачи.
5. Нужные инструменты проверены отдельно.
6. Вы понимаете, какой провайдер обслуживает основной диалог, где действуют лимиты и кто выставляет счёт.

После короткого ответа проверьте один безопасный вызов инструмента: попросите Hermes определить текущую дату через доступный инструмент и убедитесь, что вызов действительно выполнен. Затем попросите развёрнутый ответ, например подробный план по тестовой задаче. Это помогает заметить ошибки, которые не проявились на коротком запросе. Если вы подключили Telegram, повторите все три теста там: короткий ответ, вызов инструмента и длинный ответ. Сравните фактические provider, model и профиль с CLI. Если для Telegram намеренно выбран отдельный маршрут, проверьте его отдельно и зафиксируйте различие.

Можно ли подключить модель без API-ключа?

Да, если выбранный провайдер поддерживает OAuth или иной подписочный вход. Есть и провайдеры без ключа и аккаунта, например OpenCode Free через /model free. Это не универсальное правило: условия зависят от провайдера и тарифа. hermes model показывает поддерживаемые варианты.

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

После изменения авторизации или endpoint через hermes model начните новый диалог. Если у доступного провайдера не видна только модель, используйте /model --refresh или точный provider:model внутри сессии. /model показывает и меняет модель; для провайдера без ключа и аккаунта возможен выбор через /model free. Обычно смена действует в текущей сессии, а --global сохраняет default. При смене модели может потеряться скидка за кэшированный контекст.

Почему модель отвечает, а web search или browser нет?

Модель и инструменты имеют отдельные настройки. Проверьте hermes tools --summary, credentials соответствующего tool backend и auxiliary model route, если он задан.

Нужно ли сразу настраивать fallback?

Нет. Сначала подтвердите один основной маршрут. Затем добавьте резерв и проверьте, какой provider:model будет использоваться при сбое и как это влияет на стоимость.

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

Если базовый чат уже работает и вы хотите собрать вокруг него Telegram, инструменты, память и рабочие сценарии, посмотрите программу воркшопа Codex + Hermes.

• Quickstart: первый запуск Hermes
• LLM and Model Providers
• CLI Commands
• Credential Pools
• Fallback Providers

Материал проверен 14 сентября 2026 года. Повторная техническая проверка — через 30 дней или раньше после изменения интерфейса Hermes Agent.