# Hermes Agent Integration

> **Last verified**: 2026-09-18 · 📄 Per official docs (Hermes Agent v0.21.3 / tag v2026.9.14, released 2026-09-14)

## At a glance

| Item | Details |
|---|---|
| Models you can use | Claude ✅ (Anthropic protocol) · GPT ✅ · Chinese models ✅ · Gemini ❌ (no Gemini adapter in the official transport enum) |
| Protocol & Base URL | Anthropic: `https://api.qcode.cc/api` · OpenAI: `https://api.qcode.cc/openai/v1` |
| Where to configure | `~/.hermes/config.yaml` (keys live in `~/.hermes/.env`); native Windows installs under `%LOCALAPPDATA%\hermes` |
| Official docs | [Providers](https://github.com/NousResearch/hermes-agent/blob/main/website/docs/integrations/providers.md) |

Hermes Agent is a **general-purpose AI agent** built by Nous Research (it learns skills from experience): a terminal TUI plus a multi-channel gateway for Telegram / Discord / Slack / CLI. **It is not a code editor** — though it can act as an ACP server behind ACP-compatible editors (see [ACP Overview](/docs/ide/acp)). All model endpoints live in its own `config.yaml`, independent of any host editor.

## Prerequisites

- Hermes Agent installed (follow the [official README](https://github.com/NousResearch/hermes-agent); this page does not duplicate install commands).
- A QCode.cc `cr_` key ([dashboard](https://qcode.cc/dashboard)). No Nous Portal or model-vendor account is needed.
- Know the division of labour: secrets go to `~/.hermes/.env`, behaviour settings to `config.yaml`. `config.yaml` is the single source of truth for model and endpoint — the legacy `LLM_MODEL` env var has been removed upstream.

## Setup

### Route A: named providers (recommended; Claude and GPT/Chinese side by side)

In `~/.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
```

Then put the key in `~/.hermes/.env`:

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

Key points (all from the official providers doc):

- `transport` has exactly three canonical values: `chat_completions` / `anthropic_messages` / `codex_responses` (lowercase, underscores). Claude models on QCode must use `anthropic_messages`.
- The URL key in each provider entry is `api` in official examples (`base_url` / `url` are accepted aliases); the protocol key is `transport` (`api_mode` is the alias).
- `key_env` names an environment variable (no `$`); its value lives in `.env`.
- Hermes auto-detects the transport only when a provider URL ends in `/anthropic`; `api.qcode.cc/api` does **not** trigger detection, so `transport` must be written explicitly.

### Route B: single endpoint (OpenAI-compatible leg only)

To get GPT / Chinese models running first, use the flat official form (`provider: custom` = any OpenAI-compatible endpoint):

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

## Switching models mid-session

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

`<model-id>` is any model ID you declared for that provider (Claude leg e.g. `claude-sonnet-5`, OpenAI leg e.g. `glm-5.3`).

Official division of duties: `/model` only switches between providers and models you have already configured; **adding a provider requires exiting the session and running the `hermes model` wizard**.

## Verify it works

Start `hermes` and ask anything. If it fails, check in order:

1. Does the path and key arrive (OpenAI leg):

```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 = key invalid; 400 = path fine (missing body is expected)
```

2. YAML indentation of the `providers:` entries (two spaces, siblings).
3. `key_env` names match `.env` exactly.
4. Every request is logged at [probe.qcode.cc](https://probe.qcode.cc); still stuck? Use the [troubleshooting guide](/docs/reference/troubleshooting).

## Known limitations

- **Anthropic leg not live-tested**: every official `anthropic_messages` example uses a host+prefix URL **without `/v1`** (e.g. `https://proxy.example.com/anthropic`), so this page uses `https://api.qcode.cc/api`; how Hermes builds the final path has not been verified by us. If requests return 404, set `api` to the full path `https://api.qcode.cc/api/v1/messages` instead.
- `discover_models: false`: Hermes probes `<base>/models` on custom endpoints. That path exists on the QCode OpenAI leg, but `/api/models` does not (404, tested) — disable discovery on the Claude entry as shown and name models via `default_model` / `models`.
- Do not route Chinese models through `codex_responses` — the QCode Responses leg serves GPT models only (matrix: [Endpoints and API paths](/docs/getting-started/endpoints-and-api-paths)).
- No Gemini support: the official transport enum has no Gemini adapter, so `gemini-*` models are unavailable.
- `OPENAI_BASE_URL` will not point QCode anywhere: the docs state it is honoured only for the `openai-api` provider. Use `config.yaml`.
- Output-token caps are not configurable: upstream stopped reading `model.max_tokens` and friends, so old tutorials are stale.

## Related docs

- [Endpoints and API paths](/docs/getting-started/endpoints-and-api-paths)
- [Tool Compatibility Overview](/docs/ide/tool-compatibility)
- [ACP Overview](/docs/ide/acp)
- [Chinese Models](/docs/usage/cn-models)
- [Troubleshooting](/docs/reference/troubleshooting)