Hermes Agent Integration

Point Hermes Agent (Nous Research) at QCode.cc through custom providers in config.yaml: the three transport values, keys in .env, and switching models mid-session

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

At a glance¶

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). All model endpoints live in its own config.yaml, independent of any host editor.

Prerequisites¶

• Hermes Agent installed (follow the official README; this page does not duplicate install commands).
• A QCode.cc cr_ key (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:

# ~/.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:

# ~/.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):

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¶

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

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)

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

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).
• 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
• Tool Compatibility Overview
• ACP Overview
• Chinese Models
• Troubleshooting