Подключение Hermes Agent

QCode.cc как custom provider в config.yaml Hermes Agent (Nous Research): три транспорта, ключ в .env и переключение моделей прямо в сессии

Последняя проверка: 2026-09-18 · 📄 По официальной документации (Hermes Agent v0.21.3 / тег v2026.9.14, выпуск 2026-09-14)

Кратко¶

Hermes Agent — это универсальный AI-агент от Nous Research (со встроенным циклом обучения навыкам): терминальный TUI плюс шлюз к Telegram / Discord / Slack / CLI. Это не редактор кода, хотя может работать ACP-сервером — бэкендом для совместимых редакторов (см. Обзор ACP). Все эндпоинты моделей описаны в собственном config.yaml и не зависят от редактора-хоста.

Предварительные требования¶

• Установленный Hermes Agent (установка — по официальному README; дублировать команды здесь не будем).
• Ключ QCode.cc с префиксом cr_ (консоль). Аккаунт Nous Portal или вендоров моделей не нужен.
• Разделение ролей: секреты — в ~/.hermes/.env, поведение — в config.yaml. config.yaml — единственный источник истины для модели и эндпоинта; старая переменная LLM_MODEL официально удалена.

Настройка¶

Маршрут A: именованные провайдеры (рекомендуется; Claude и GPT/китайские рядом)¶

В ~/.hermes/config.yaml:

# ~/.hermes/config.yaml
model:
  provider: custom:qcode_claude
  default: claude-sonnet-5

providers:
  qcode_claude:
    api: https://api.qcode.cc/api
    key_env: QCODE_API_KEY
    transport: anthropic_messages
    default_model: claude-sonnet-5
    discover_models: false
  qcode_openai:
    api: https://api.qcode.cc/openai/v1
    key_env: QCODE_API_KEY
    transport: chat_completions
    default_model: glm-5.3

Затем ключ в ~/.hermes/.env:

# ~/.hermes/.env
QCODE_API_KEY=cr_your-QCode-key

Важно (всё из официальной документации providers):

• У transport ровно три канонических значения: chat_completions / anthropic_messages / codex_responses (строчные, с подчёркиваниями). Для Claude на QCode — только anthropic_messages.
• Ключ URL в записи провайдера по официальным примерам — api (base_url / url — допустимые псевдонимы); ключ протокола — transport (api_mode — псевдоним).
• В key_env пишется имя переменной (без $), её значение лежит в .env.
• Автоопределение transport срабатывает, только если URL провайдера заканчивается на /anthropic; окончание /api его не запускает, поэтому transport указываем явно.

Маршрут B: один эндпоинт (нога OpenAI-совместимая)¶

Чтобы для начала запустить GPT / китайские модели — официальная плоская форма (provider: custom = любой OpenAI-совместимый эндпоинт):

model:
  provider: custom
  base_url: https://api.qcode.cc/openai/v1
  api_key: cr_your-QCode-key
  default: gpt-5.6

Переключение моделей в сессии¶

/model custom:qcode_claude:<model-id>
/model custom:qcode_openai:<model-id>

<model-id> — любой ID модели, объявленный для этого провайдера (нога Claude, например claude-sonnet-5; нога OpenAI — glm-5.3).

Разделение по официальной документации: /model переключает только уже настроенные провайдеры и модели; новый провайдер добавляется вне сессии — через мастер hermes model.

Проверка подключения¶

Запустите hermes и задайте любой вопрос. Если не работает — по порядку:

1. Достигают ли путь и ключ цели (нога OpenAI):

curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/openai/v1/chat/completions \
  -H "Authorization: Bearer $QCODE_API_KEY"
# → 401 = ключ недействителен; 400 = путь в порядке (тело запроса отсутствует — ожидаемо)

1. Целостность отступов YAML в записях providers: (два пробела, один уровень).
2. Совпадение имени key_env с переменной в .env до символа.
3. Все запросы видны в probe.qcode.cc; не помогло — устранение неполадок.

Известные ограничения¶

• Нога Anthropic не проверялась вживую: все официальные примеры anthropic_messages используют URL «хост + префикс» без /v1 (например https://proxy.example.com/anthropic), поэтому здесь стоит https://api.qcode.cc/api; как именно Hermes собирает итоговый путь, мы не проверяли. При 404 укажите в api полный путь https://api.qcode.cc/api/v1/messages.
• discover_models: false: Hermes настраивает поиск моделей на кастомных эндпоинтах запросом <base>/models. На ноге QCode OpenAI такой путь есть, а /api/models отсутствует (404, проверено) — на записи Claude поиск лучше отключить, как выше, и задать default_model / models явно.
• Не направляйте китайские модели через codex_responses — нога Responses у QCode обслуживает только семейство GPT (матрица: Эндпоинты и пути API).
• Gemini недоступен: в официальном перечне transport адаптера Gemini нет, gemini-* модели не подключить.
• Через OPENAI_BASE_URL на QCode не указать: по документации переменная действует только для провайдера openai-api. Всё в config.yaml.
• Ограничение выходных токенов не настраивается: апстрим перестал читать model.max_tokens и родненные ключи, старые туториалы устарели.

Связанные документы¶

• Эндпоинты и пути API
• Обзор совместимости инструментов
• Обзор ACP
• Китайские модели
• Устранение неполадок