Hermes Agent 接入

在 Hermes Agent（Nous Research）的 config.yaml 里把 QCode.cc 配成 custom provider：transport 三协议写法、密钥放 .env、会话内热切模型

最后核实：2026-09-18 · 📄 依据官方文档（Hermes Agent v0.21.3 / tag v2026.9.14，2026-09-14 发布）

接入速览¶

Hermes Agent 是 Nous Research 出的通用 AI agent（自带技能学习回路），形态是终端 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：命名 provider（推荐，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。
• 命名 provider 的 URL 以 /anthropic 结尾时 Hermes 会自动识别 transport；/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> 填你在对应 provider 条目里声明过的模型 ID（Claude 腿如 claude-sonnet-5，OpenAI 腿如 glm-5.3）。

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

相关文档¶

• 接入点与 API 格式
• 工具兼容总览
• ACP 接入总览
• 国产模型接入
• 故障排查指南