Hermes Agent 可以通过 hermes model 的 Custom Endpoint 向导接入 OpenAI-compatible Chat Completions 服务。

第一步：安装 Hermes Agent

先阅读 Hermes Agent 官方安装文档，再使用官方安装方式。macOS、Linux 或 WSL2 可以先把脚本下载到本地并检查内容：

curl -fsSL https://hermes-agent.nousresearch.com/install.sh \
  -o /tmp/hermes-install.sh
less /tmp/hermes-install.sh
bash /tmp/hermes-install.sh

安装器可能安装 Python、uv、虚拟环境并更新 shell 配置。完成后重新打开终端，再检查：

hermes --version
hermes doctor

如果安装中断，不要把“开始下载”当作安装完成；先保存输出并区分网络、Python、uv 或依赖构建问题。

第二步：创建 Hermes 专用 API 密钥

  1. 登录 青云TOP API 控制台。
  2. 打开“令牌管理”，新建一个只供 Hermes 使用的令牌。
  3. 选择需要使用的模型分组。
  4. 复制令牌并妥善保存；截图时必须保持掩码。

第三步：确认模型与协议

export QINGYUN_TOP_API_KEY="你的 青云TOP API API 密钥"

curl "https://top.qingyuntop.ai/v1/models" \
  -H "Authorization: Bearer $QINGYUN_TOP_API_KEY"

从返回结果中复制准确的模型 ID。下文用 gpt-4o-mini 举例，并选择 chat_completions。如果目标模型只支持 Responses 或 Anthropic Messages，不能直接套用本页协议。

第四步：选择配置方式

方法 A：使用 CC Switch

  1. 在 CC Switch 顶部选择 Hermes。
  2. 点击“添加供应商”→“自定义配置”。
  3. API 模式选择 OpenAI Chat Completions。
  4. API 端点填 https://top.qingyuntop.ai/v1，再填入 Hermes 专用 青云TOP API 密钥。
CC Switch Hermes 分支中的 青云TOP API Provider 配置

CC Switch 中填写 青云TOP API Hermes Provider；密钥保持掩码

点击“添加模型”，填写 /v1/models 实际返回的模型 ID。第一个模型会写入 Hermes 顶层 model.default；下图使用 gpt-4o-mini。

CC Switch Hermes 分支中的 青云TOP API 模型配置

在 Hermes Provider 中添加 青云TOP API 默认模型

保存后点击“启用”。卡片显示“使用中”且出现“切换成功”，才表示 CC Switch 已把 青云TOP API 写入 Hermes 配置。

CC Switch 已启用 青云TOP API Hermes Provider

青云TOP API Hermes Provider 已启用

方法 B：使用 Hermes Custom Endpoint 向导

运行：

hermes model

在交互菜单中选择 Custom Endpoint，然后依次填写：

  • Name：青云TOP API
  • Base URL：https://top.qingyuntop.ai/v1
  • API mode：chat_completions
  • API Key：青云TOP API 专用令牌
  • Default model：gpt-4o-mini

Base URL 不要追加 /chat/completions。向导会把 API mode 写入 ~/.hermes/config.yaml；不要依赖 URL 自动判断协议。

第五步：检查保存后的配置

保存后，配置结构应与下面一致。真实密钥应放在环境变量或 ~/.hermes/.env，不要写进 config.yaml：

model:
  default: gpt-4o-mini
  provider: custom:青云TOP API

custom_providers:
  - name: 青云TOP API
    base_url: https://top.qingyuntop.ai/v1
    key_env: QINGYUN_TOP_API_KEY
    api_mode: chat_completions

将密钥写入 Hermes 的秘密文件时，只写变量，不把该文件提交到代码仓库：

QINGYUN_TOP_API_KEY=你的 青云TOP API API 密钥

Hermes 官方配置说明把 ~/.hermes/config.yaml 用于非秘密设置，把 ~/.hermes/.env 用于 API Key、Bot Token 和密码。

第六步：选择 青云TOP API 模型

再次运行 hermes model，在自定义 Provider 中选择 青云TOP API，然后选择 gpt-4o-mini。进入会话后也可以使用 Hermes 的模型切换命令：

/model custom:青云TOP API:gpt-4o-mini

确认当前 Provider 与模型已经切换，再发送消息。

第七步：发送第一条消息

hermes

在原生交互界面中发送：

只回复 HERMES_青云TOP API_OK，不要添加其他内容。

必须同时看到 Hermes 的正文回复，并在 青云TOP API 控制台找到同一时间、同一模型的请求记录，才能认定接入完成。配置被保存、模型出现在菜单或 HTTP 请求开始发送，都不能替代最终回复。

第八步：再启用工具与 Gateway

先保持工具、记忆、定时任务和 Gateway 关闭。普通文本成功后，再逐项启用。Telegram、Discord、Slack 等 Gateway 需要外部账号或 Bot Token，不要在 Provider 尚未通过基础对话时同时配置。

常见问题

  • 安装失败：保存安装器输出，分别检查 GitHub 下载、Python、uv 和依赖构建。
  • Unknown provider：检查 provider: custom:青云TOP API 与 custom_providers[].name 是否一致。
  • 提示 401：确认 QINGYUN_TOP_API_KEY 已被当前 Hermes 进程读取，且 .env 没有多余引号或空格。
  • 提示 404：检查 Base URL、模型 ID 和 api_mode: chat_completions。
  • 模型可选择但对话失败：关闭工具，只保留普通文本，再核对模型是否支持 Chat Completions。
  • Gateway 失败：先回到普通 CLI 会话验证 Provider，再单独排查外部平台凭据和配对。

发布前检查

以下检查适用于客户端中选择 OpenAI 兼容 或 Responses 提供商的场景；如果你选择的是 Anthropic、Gemini 等原生协议，请按对应协议的接口和返回结构配置。

  1. 模型 ID：先用目标 API Key 请求 GET https://top.qingyuntop.ai/v1/models，把返回的 data[].id 原样填入客户端。截图、教程和历史配置中的模型名不保证仍可用。
  2. 协议选择：新 OpenAI 集成优先选择 Responses；只有客户端或模型明确要求 Chat Completions 时才选择 Chat。Responses 的返回从 output 读取，Chat 的返回从 choices[].message 读取。
  3. Base URL：通常填写 https://top.qingyuntop.ai/v1，也就是只保留一个 /v1。要求完整接口地址的客户端才追加 /responses 或 /chat/completions，不要重复追加。
  4. 流式与重试：流式响应必须按所选协议解析事件；连接中断后不要盲目重放可能已被服务端接受的生成请求。对 429 和 5xx 使用带抖动的退避，并设置连接、读取和总超时。
  5. 上线前验证：分别验证普通文本、流式文本、工具调用或结构化输出中实际用到的能力，并记录 request id、HTTP 状态、业务状态和完成原因，避免只根据 HTTP 200 判定成功。