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

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

## Кратко

| Параметр | Описание |
|---|---|
| Доступные модели | Claude ✅ (протокол Anthropic) · GPT ✅ · китайские модели ✅ · Gemini ❌ (в официальном перечне transport адаптера Gemini нет) |
| Протокол и Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| Где настраивается | `~/.hermes/config.yaml` (ключи — в `~/.hermes/.env`); нативная сборка Windows живёт в `%LOCALAPPDATA%\hermes` |
| Официальная документация | [Providers](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/integrations/providers.md) |

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

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

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

## Настройка

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

В `~/.hermes/config.yaml`:

```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`:

```text
# ~/.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-совместимый эндпоинт):

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

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

```text
/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):

```bash
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 = путь в порядке (тело запроса отсутствует — ожидаемо)
```

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

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

- **Нога 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](/docs/getting-started/endpoints-and-api-paths)).
- Gemini недоступен: в официальном перечне transport адаптера Gemini нет, `gemini-*` модели не подключить.
- Через `OPENAI_BASE_URL` на QCode не указать: по документации переменная действует только для провайдера `openai-api`. Всё в `config.yaml`.
- Ограничение выходных токенов не настраивается: апстрим перестал читать `model.max_tokens` и родненные ключи, старые туториалы устарели.

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

- [Эндпоинты и пути API](/docs/getting-started/endpoints-and-api-paths)
- [Обзор совместимости инструментов](/docs/ide/tool-compatibility)
- [Обзор ACP](/docs/ide/acp)
- [Китайские модели](/docs/usage/cn-models)
- [Устранение неполадок](/docs/reference/troubleshooting)