Урок 7: Конфигурационные файлы

С возвращением, укротители агентов! В этом уроке мы погружаемся в самое сердце Hermes — конфигурационные файлы. Если вы когда-нибудь тонули в море YAML и переменных окружения, не бойтесь — мы сделаем всё максимально безболезненно.

Домашняя база Hermes

Всё хранится в ~/.hermes/. Представьте это как квартиру вашего агента. Вот что внутри:

~/.hermes/
├── config.yaml     # Настройки (модель, терминал, TTS, сжатие и т.д.)
├── .env            # API-ключи и секреты
├── auth.json       # Учётные данные OAuth-провайдеров (Nous Portal и др.)
├── SOUL.md         # Основная идентичность агента (слот #1 в системном промпте)
├── memories/       # Постоянная память (MEMORY.md, USER.md)
├── skills/         # Навыки, созданные агентом (управляются через инструмент skill_manage)
├── cron/           # Запланированные задачи
├── sessions/       # Сессии шлюза
└── logs/           # Журналы (errors.log, gateway.log — секреты автоматически редактируются)

Самый простой путь: настройка одной командой

Прежде чем мы углубимся в детали, вот профессиональный совет: выполните hermes setup --portal. Одна OAuth-авторизация даст вам провайдера моделей и все четыре инструмента Tool Gateway без единого касания YAML-файла. Подписчики Portal также получают скидку 10% на провайдеров с оплатой за токены. Это ленивый способ начать работу, и мы его обожаем.

Управление конфигурацией

Hermes предоставляет полный набор инструментов для управления настройками. Вот команды, которые вы будете использовать ежедневно:

hermes config              # Просмотр текущей конфигурации
hermes config edit         # Открыть config.yaml в вашем редакторе
hermes config get KEY      # Вывести вычисленное значение
hermes config set KEY VAL  # Установить конкретное значение
hermes config unset KEY    # Удалить значение, заданное пользователем
hermes config check        # Проверить отсутствующие опции (после обновлений)
hermes config migrate      # Интерактивно добавить недостающие опции

Вот несколько практических примеров:

hermes config get model
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config unset terminal.backend
hermes config set OPENROUTER_API_KEY sk-or-...  # Сохраняется в .env

Магический трюк: hermes config set автоматически направляет значения в нужный файл. API-ключи отправляются в .env, всё остальное — в config.yaml. Больше никаких догадок!

Что побеждает при конфликте?

Hermes разрешает настройки в следующем порядке (от высшего приоритета к низшему):

Аргументы CLI — например, hermes chat --model anthropic/claude-sonnet-4
~/.hermes/config.yaml — ваш основной конфигурационный файл
~/.hermes/.env — для секретов (API-ключи, токены, пароли)
Встроенные значения по умолчанию — безопасные захардкоженные значения

Эмпирическое правило: Секреты — в .env. Всё остальное — в config.yaml. Если заданы оба, config.yaml побеждает для несекретных настроек.

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

Вы можете ссылаться на переменные окружения в config.yaml, используя синтаксис ${VAR_NAME}:

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}

delegation:
  api_key: ${DELEGATION_KEY}

Множественные ссылки тоже работают: url: "${HOST}:${PORT}". Если переменная не задана, плейсхолдер остаётся как есть, а в журнал записывается предупреждение. Синтаксис в стиле Cursor ${env:VAR_NAME} также поддерживается, так что вы можете копировать фрагменты из конфигов Cursor или Claude без изменений.

Таймауты провайдеров

Вы можете задавать таймауты для каждого провайдера и каждой модели:

providers:
  some-provider:
    request_timeout_seconds: 600
    models:
      some-model:
        timeout_seconds: 300

Также существует stale_timeout_seconds для обнаружения зависших не-стриминговых вызовов. Эти настройки переопределяют устаревшие переменные окружения HERMES_API_TIMEOUT и HERMES_API_CALL_STALE_TIMEOUT.

Ограничения времени выполнения

Для долго работающих серверных поверхностей (шлюз, hermes serve --isolated) вы можете задать лимиты файловых дескрипторов:

runtime:
  nofile_soft_limit: 4096

Значение по умолчанию — 4096. Установите 0, false или null, чтобы отключить корректировку.

Поведение при обновлении

Настройки обновления находятся в разделе updates в config.yaml:

updates:
  pre_update_backup: quick

Подводим итоги

Вот и весь обзор конфигурации! Запомните: hermes setup --portal — для лёгкого пути, hermes config set — для быстрых изменений, и храните секреты в .env. Ваш агент скажет вам спасибо.

Дальше: мы исследуем AI-провайдеров и способы подключения ваших любимых моделей. Оставайтесь с нами!