# Hermes Agent 接入

> **最后核实**：2026-09-18 · 📄 依据官方文档（Hermes Agent v0.21.3 / tag 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 是 Nous Research 出的**通用 AI agent**（自带技能学习回路），形态是终端 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：命名 provider（推荐，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`。
- 命名 provider 的 URL 以 `/anthropic` 结尾时 Hermes 会自动识别 transport；`/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>` 填你在对应 provider 条目里声明过的模型 ID（Claude 腿如 `claude-sonnet-5`，OpenAI 腿如 `glm-5.3`）。

注意分工（官方原文）：`/model` 只能在**已经配好的** provider 与模型之间切换；**新增 provider 要退出会话后跑 `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 腿该路径存在，但 Anthropic 腿的 `/api/models` 不存在（实测 404），Claude 条目建议像上面一样显式关掉探测、用 `default_model` / `models` 点名。
- 国产模型别配到 `codex_responses` 上——QCode 的 Responses 腿只服务 GPT 系（对照见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)）。
- 没有 Gemini 适配器：官方 `transport` 枚举不含 Gemini 协议，接不了 `gemini-*` 模型。
- 想用 `OPENAI_BASE_URL` 指向 QCode？不行——官方文档明确该变量只对 `openai-api` 这一个 provider 生效，自定义端点一律走 `config.yaml`。
- 输出 token 上限不可配：官方已停止读取 `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)