Перейти к содержимому
11 мин чтения

Настройка Hermes Agent: конфиг, API-ключи, модель и мессенджер

Hermes AgentИИ-агентынастройкаинструкцияself-hosted

Коротко. Настройка Hermes Agent — это два файла и пять команд. Все настройки лежат в каталоге ~/.hermes/: секреты в .env, всё остальное в config.yaml. Порядок такой: hermes model — выбрать провайдера и вписать API-ключ, hermes setup — пройти мастер по разделам, hermes gateway setup — подключить мессенджер, hermes config check и hermes doctor — убедиться, что конфигурация цела. Главное ограничение, о которое спотыкаются почти все: модель должна держать не меньше 64 000 токенов контекста — те, что меньше, агент отклоняет прямо при запуске. Второе по частоте — попытка вписать API-ключ в config.yaml: туда он не попадёт, ключи живут только в .env.

Ниже — разбор конфигурации по шагам. Каждая команда, каждый ключ и каждая переменная окружения сверены с документацией проекта и репозиторием. Всё проверено на Hermes Agent v0.21.4 — это тег релиза v2026.9.21 от 21 сентября 2026 года. Проект выпускает релизы почти каждую неделю, поэтому если вы читаете статью сильно позже, сверьтесь со страницей hermes-agent.nousresearch.com/docs. Предполагается, что агент у вас уже стоит; если нет — начните с пошаговой установки Hermes Agent, а затем возвращайтесь сюда.

Где Hermes Agent хранит настройки

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

~/.hermes/
├── config.yaml          # основные настройки
├── .env                 # API-ключи и секреты
├── auth.json            # OAuth-учётки провайдеров
├── SOUL.md              # личность и правила агента
├── memories/            # постоянная память
├── skills/              # навыки, созданные агентом
├── cron/                # запланированные задачи
├── sessions/            # сессии шлюза
└── logs/                # логи ошибок и шлюза

Путь к любому из двух файлов можно не искать руками:

hermes config path       # печатает путь к config.yaml
hermes config env-path   # печатает путь к .env

Правило, которое экономит час отладки

В документации оно сформулировано прямо: всякое имя в UPPER_SNAKE — это переменная окружения, и она сохраняется в .env, никогда в config.yaml; настройки с точкой в имени идут в config.yaml. То есть:

Что настраиваетеКак выглядитКуда попадёт
API-ключ, токен бота, парольOPENROUTER_API_KEY.env
Модель по умолчанию, таймауты, флагиmodel.defaultconfig.yaml

Разбирать это самостоятельно не нужно — команда hermes config set маршрутизирует значение сама:

hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxx   # уйдёт в .env
hermes config set model.default anthropic/claude-opus-4   # уйдёт в config.yaml

Полный набор подкоманд hermes config: show (показать текущие значения), edit (открыть config.yaml в редакторе), get <ключ> (получить одно значение по точечному пути; флаг --json даёт машиночитаемый вывод, --raw показывает секреты без маскирования), set, unset (удалить ключ и вернуться к значению по умолчанию), path, env-path, check и migrate.

Шаг 1. Провайдер нейросети и API-ключ

Быстрый путь — интерактивный выбор:

hermes model

Команда открывает выбор провайдера и модели: добавляет нового провайдера, проводит OAuth там, где он поддержан, принимает API-ключ и записывает выбранную модель как значение по умолчанию. По документации доступны Nous Portal (более 300 моделей одной учёткой) либо ручной выбор из 40+ провайдеров — среди них OpenAI, Anthropic, Google AI Studio, xAI, DeepSeek, GitHub Copilot, AWS Bedrock и произвольные OpenAI-совместимые эндпоинты.

Если хотите пройти всё разом, есть мастер с разделами:

hermes setup            # полный мастер
hermes setup --quick    # пропустить уже настроенное
hermes setup --portal   # быстрый путь через Nous Portal (OAuth одной командой)

Разделы мастера: model (провайдер и модель), tts (синтез речи), terminal (бэкенд и песочница), gateway (мессенджеры), tools (инструменты по платформам), agent (поведение агента). Есть также --non-interactive и --reset.

Вписать ключ вручную

Если настраиваете сервер скриптом, интерактивный мастер не нужен — достаточно положить переменные в ~/.hermes/.env. Точные имена:

ПровайдерПеременная с ключомПереопределение адреса
OpenRouterOPENROUTER_API_KEYOPENROUTER_BASE_URL
AnthropicANTHROPIC_API_KEYANTHROPIC_BASE_URL
OpenAIOPENAI_API_KEYOPENAI_BASE_URL
DeepSeekDEEPSEEK_API_KEYDEEPSEEK_BASE_URL
GoogleGOOGLE_API_KEY / GEMINI_API_KEYGEMINI_BASE_URL
OllamaOLLAMA_API_KEYOLLAMA_BASE_URL

Ключ одного провайдера не работает у другого — в документации это вынесено отдельной строкой, потому что ошибка массовая: ключ OpenAI, вписанный в поле OpenRouter, даёт отказ авторизации, который читается как «ключ протух».

Несколько ключей на одного провайдера

Если упираетесь в лимиты, Hermes умеет держать пул учётных данных и ротировать их. Управление — через hermes auth:

hermes auth list                  # показать все пулы
hermes auth add <провайдер>        # добавить ключ или OAuth-учётку
hermes auth status <провайдер>     # состояние авторизации
hermes auth reset <провайдер>      # сбросить кулдауны
hermes auth remove <индекс>        # удалить учётку по номеру

Порядок перебора задаётся командой hermes auth priority. Старые hermes login и hermes logout помечены в документации как устаревшие — используйте hermes auth.

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

Шаг 2. Модель и контекст

Требование, которое стоит выписать отдельно: Hermes Agent требует модель как минимум с 64 000 токенов контекста, модели ниже этого порога отклоняются при запуске. Это не рекомендация и не «желательно» — агенту нужно место под историю диалога, описания инструментов и результаты их вызовов, и на коротком контексте он просто не работает.

Модель по умолчанию и, если нужно, явная длина контекста задаются в config.yaml:

model:
  default: anthropic/claude-opus-4
  context_length: 131072

Формат ссылки на модель — провайдер/имя-модели. Разово переопределить её можно флагом при запуске:

hermes chat --model anthropic/claude-sonnet-4

Внутри уже идущего диалога работает команда /model. Важная деталь: она переключает только между уже настроенными провайдерами и по умолчанию действует в пределах сессии — чтобы изменение сохранилось, нужен флаг --global. Если /model показывает одного провайдера, это не баг: выйдите из сессии, добавьте провайдера через hermes model и начните диалог заново.

Отдельно настраивается вспомогательная модель — например, для сжатия контекста, где дорогая модель не нужна:

auxiliary:
  compression:
    provider: openrouter
    model: google/gemini-2.5-flash

Шаг 3. Своя или локальная модель

Hermes умеет ходить в любой OpenAI-совместимый сервер — Ollama, vLLM, llama.cpp, SGLang, LocalAI. Эндпоинт описывается как именованный провайдер:

providers:
  llamacpp:
    base_url: http://127.0.0.1:8081/v1
    model: my-model

Можно указать и корень сервера (http://127.0.0.1:8080), и полный адрес с /v1: при проверке Hermes пробует оба варианта и сохраняет тот, который реально отдал список моделей, — чтобы запросы уходили туда же, откуда пришёл список. Старый формат custom_providers: ещё поддерживается и мигрируется в providers: автоматически.

Ключ для конкретного эндпоинта задаётся двумя способами — литералом или ссылкой на переменную:

providers:
  myendpoint:
    api_key: "sk-..."        # прямое значение — так лучше не делать
    key_env: MY_API_KEY_VAR  # ссылка на переменную из .env — предпочтительно

Если заданы оба, выигрывает api_key. В документации рекомендован вариант с key_env: секрет остаётся в .env, а config.yaml можно спокойно положить в репозиторий. Работает и подстановка прямо в значении — ${VAR_NAME} (а также cursor-подобный синтаксис ${env:VAR_NAME}); если переменная не задана, плейсхолдер остаётся в тексте как есть и пишется предупреждение — то есть молчаливой поломки не будет, но и ключа тоже.

Три вещи, которые ломают локальную модель

  • Контекст. Через OpenAI-совместимый API длину контекста задать нельзя — она настраивается на стороне сервера (для Ollama — через num_ctx или Modelfile). Документация называет это источником путаницы номер один и предупреждает: /api/show у Ollama возвращает максимальный контекст модели, а не фактический num_ctx, поэтому выставленное значение нужно продублировать в model.context_length.
  • Таймауты. Локальные эндпоинты Hermes определяет сам и поднимает таймаут чтения со 120 до 1800 секунд, отключая детектор «застывшего» потока. Если всё равно рвётся — HERMES_STREAM_READ_TIMEOUT=1800 и HERMES_API_TIMEOUT=1800. Для Ollama пригодится OLLAMA_KEEP_ALIVE=24h: по умолчанию он выгружает простаивающую модель через пять минут, и первый запрос после паузы уходит в долгую загрузку.
  • Тихого отката в облако не будет. hermes chat --provider ollama завершится ошибкой, если для этого алиаса нигде не настроен адрес, — даже когда облачный ключ прописан. Это сделано намеренно: счёт за «локальную» модель не прилетит.

Шаг 4. Подключить мессенджер

Интерактивный путь — одна команда, она же спросит токен и список разрешённых пользователей:

hermes gateway setup

Для Telegram руками порядок такой. Создайте бота у @BotFather командой /newbot, задайте имя и уникальный username (обязан заканчиваться на bot) — в ответ придёт токен. Если бот нужен в группах, там же отключите режим приватности: /mybots → ваш бот → Bot Settings → Group Privacy → Turn off. Свой числовой ID узнайте у @userinfobot. Затем допишите в ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

TELEGRAM_ALLOWED_USERS — это список числовых ID через запятую, и относиться к нему стоит как к замку на двери: агент с доступом к терминалу, открытый всем желающим, — это чужой shell на вашем сервере. Если нужно, чтобы агент в Telegram отвечал сотрудникам, а не кому попало, разграничение доступа настраивается именно здесь, до первого запуска шлюза.

Имена переменных для остальных платформ: DISCORD_BOT_TOKEN, SLACK_BOT_TOKEN и SLACK_APP_TOKEN, для WhatsApp Cloud — WHATSAPP_CLOUD_PHONE_NUMBER_ID, WHATSAPP_CLOUD_ACCESS_TOKEN, WHATSAPP_CLOUD_APP_SECRET и WHATSAPP_CLOUD_VERIFY_TOKEN.

Запуск шлюза: в переднем плане или сервисом

hermes gateway run        # в переднем плане
hermes gateway install    # поставить фоновый сервис (systemd/launchd)
hermes gateway start      # запустить фоновый сервис
hermes gateway status     # состояние
hermes gateway list       # все профили и статус их шлюзов

Документация рекомендует run для WSL, Docker и Termux — и отдельно отмечает, что поддержка systemd в WSL ненадёжна, так что фоновый сервис там лучше не пытаться поднимать. Есть также stop, restart, uninstall и флаг --all, применяющий команду ко всем профилям.

Какие инструменты доступны в мессенджере

hermes tools

Эта команда включает и выключает инструменты отдельно для каждой платформы — Telegram, Discord, Slack, Signal, SMS, WhatsApp и прочих настроенных. Логика понятная: то, что позволено вам в локальном терминале, не обязано быть позволено боту в общем чате. Разобраться, какие инструменты агент действительно может вызвать и чем это закончится, — отдельная работа; при необходимости мы проверим периметр агента и разложим права по платформам.

Шаг 5. Убедиться, что конфигурация жива

hermes config check    # найти отсутствующие и устаревшие настройки
hermes config migrate  # добавить появившиеся в новой версии опции
hermes doctor          # общая диагностика зависимостей и конфига
hermes config show     # показать текущие значения

hermes config migrate стоит запускать после каждого обновления: новые версии приносят новые опции, и команда предлагает их интерактивно, вместо того чтобы молча работать на значениях по умолчанию. У hermes doctor есть флаг --fix, который пытается починить найденное сам.

Полезно знать про два флага для диагностики: --ignore-user-config запускает агента на встроенных значениях, минуя ваш config.yaml, а --ignore-rules отключает автоподстановку AGENTS.md, SOUL.md и .cursorrules. Если агент ведёт себя странно, это первый способ понять, виновата конфигурация или нет.

Что ломается чаще всего

  1. Ключ вписан не туда. Симптом — провайдер отвечает отказом авторизации. Проверьте hermes config show и загляните в ~/.hermes/.env: конфликтующая запись там перебивает то, что вы настроили позже.
  2. Контекст кончился. Сообщение выглядит так: Context length exceeded: compression could not reduce the rebuilt request below the safe threshold. Измерить размер запроса можно командой hermes prompt-size, а внутри сессии — /usage. Лечится сжатием сессии или явным model.context_length.
  3. Шлюз не стартует. Смотрите hermes gateway status и хвост ~/.hermes/logs/gateway.log, проверьте, не занят ли порт. Если не хватает зависимостей для мессенджеров, документация предлагает доустановить их в окружение агента и перезапустить шлюз.
  4. «/model показывает одного провайдера». Это не поломка: внутри сессии переключаться можно только между уже настроенными. Выйдите, добавьте через hermes model, начните диалог заново.
  5. После обновления часть настроек «пропала». Почти всегда это новые опции со значениями по умолчанию. hermes config migrate покажет, что появилось.

Когда не стоит настраивать самому

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

У нас это устроено как подписка: сервер, установка, ключи, модели, обновления и присмотр за расходом — на нашей стороне. Нейросеть, сервер и резервные копии оплачиваются сверх подписки — напрямую или одним счётом через нас; состав и актуальные цифры смотрите на странице с тарифами и условиями. Если коротко: поставим Hermes Agent на обслуживание — ключи, модели и шлюз под присмотром, а вы занимаетесь задачами, ради которых его заводили.

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

Можно ли настроить Hermes Agent без интерактивных диалогов?

Да. У hermes setup есть флаг --non-interactive, а любое отдельное значение ставится командой hermes config set, которая сама решает, положить его в .env или в config.yaml. Для разворачивания скриптом этого достаточно.

Где посмотреть, какой конфиг сейчас активен?

hermes config path печатает путь к config.yaml, hermes config env-path — к .env, hermes config show показывает итоговые значения. Секреты в выводе маскируются; чтобы увидеть их как есть, нужен hermes config get <ключ> --raw.

Почему агент отказывается работать с моей моделью?

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

Как держать несколько агентов на одной машине?

Через профили: флаг -p <имя> (он же --profile) выбирает профиль для любой команды, у каждого профиля свои настройки, учётки и сессии. Так удобно разводить рабочего агента и тестового, не путая их ключи.

Настройки OpenRouter влияют на остальных провайдеров?

Нет. Блок provider_routing в config.yaml (с параметрами sort, only, ignore, order) действует только на OpenRouter — на Nous Portal и на прямые подключения к провайдерам он не влияет. Это прямо оговорено в документации.

Чем настройка Hermes Agent отличается от настройки OpenClaw?

Идея одна, реализация разная: у Hermes секреты и настройки строго разведены по .env и config.yaml, а единый мастер hermes setup разбит на именованные разделы. Разбор соседнего агента — в статье про первичную настройку OpenClaw, а выбор между ними — в сравнении OpenClaw и Hermes Agent для бизнеса.

Настройка Hermes Agent: конфиг, API-ключи, модель и мессенджер — SynthIQ Agent