Hermes Agent 接入胜算云 API

Hermes Agent 是 Nous Research 开发的开源自进化 AI Agent，支持持久记忆、自动生成技能。通过胜算云 OpenAI 兼容接口，一个 Key 可调用数百种模型，且可与其它供应商并存。本文从安装 → 三种配置方式（Web to Agent / CC-Switch / 手动改配置）→ 测试与换模型，一步步带完。

一、安装 Hermes Agent

通过官方安装脚本安装（macOS / Linux / WSL），依赖由脚本自动处理。

方式 1：安装脚本（推荐）

macOS / Linux / WSL：

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

验证安装

hermes --version

能看到版本号即安装成功。

方式 A · Web to Agent 一键写入（推荐，浏览器内完成）

无需手动编辑配置文件：在下面卡片里输入胜算云 Key，组件自动拉取全部可用模型，授权 hermes 目录后一键写入 config.yaml（写入 custom_providers，自动备份原文件，保留其余配置）。

在上方卡片输入胜算云 Key（旁边「🗝 控制台获取 Key」可直达密钥页）。
组件自动拉取模型列表，下拉选择默认模型（推荐 openai/gpt-5.5）。
点「写入配置」，授权访问 hermes 目录（Win: C:\Users\<你>\AppData\Local\hermes；mac/linux: ~/.hermes）。
写入完成会自动备份原文件，回到终端运行 hermes chat 即可使用。

💡

Hermes 采用累加式供应商管理：胜算云会被加进 custom_providers 列表，model.provider 指向它，不会覆盖你已有的其它供应商，随时可以切回——这正是 CC-Switch 的写入方式。

方式 B · CC-Switch 桌面工具配置

CC-Switch 是桌面 GUI 工具，可管理多套供应商配置并一键切换。

1. 下载安装 CC-Switch

按你的系统选择推荐安装包，点击直接下载（均为 v3.18.0 稳定版）：

Windows：推荐 CC-Switch-v3.18.0-Windows.msi（MSI 安装包，支持自动更新）；或便携版 zip（解压即用，不写注册表）。Windows ARM64 设备请选文件名带 arm64 的对应制品。
macOS：推荐 CC-Switch-v3.18.0-macOS.dmg（拖入 Applications 即可）；或 zip 版（Universal Binary），tar.gz 用于 Homebrew 安装与自动更新。
Linux / 其他平台 / 历史版本：前往 Releases v3.18.0 页面查看全部制品。

2. 配置胜算云（详细步骤）

打开 CC-Switch，进入「供应商」管理页，工具选 Hermes Agent，点「新增供应商」。
在供应商列表中选择「胜算云」，API Key 和 Base URL 会自动填充。
粘贴你的胜算云 API Key，点「获取模型列表」拉取可用模型。
从模型列表里选择默认模型
点「启用 / 保存」，重启 Hermes（hermes restart）即可使用。

3. CC-Switch 配置注意事项

⚠

给 Hermes 用 CC-Switch，务必确认以下设置：

选「胜算云」供应商后，API Key 和 Base URL 会自动填充，不要手动改。
选 GPT 等模型时协议为 chat_completions（Base URL 带 /v1）；选 Claude 时为 anthropic_messages（Base URL 不带 /v1），CC-Switch 会自动切换。
必须勾选「写入通用配置」才能覆盖旧配置，否则改了不生效。

方式 C · 手动修改配置文件

直接编辑 config.yaml。位置：mac/linux ~/.hermes/config.yaml；Win %LOCALAPPDATA%\hermes\config.yaml（注意无点前缀）。

1. 写入配置（以 GPT 模型为例）

model:
  default: openai/gpt-5.5
  provider: shengsuanyun

custom_providers:
  - name: shengsuanyun
    base_url: https://router.shengsuanyun.com/api/v1
    api_key: sk-你的胜算云API Key
    api_mode: chat_completions
    models:
      - id: openai/gpt-5.5
        name: GPT-5.5
      - id: openai/gpt-5.4
        name: GPT-5.4

若用 Claude 模型，把 base_url 改成 https://router.shengsuanyun.com/api（去掉 /v1），api_mode 改成 anthropic_messages。

2. 校验并重启

hermes config validate
hermes restart

3. 配置项详细解析：为什么这么改 & 这样改有什么用

Hermes 启动时读 config.yaml，决定默认模型、走哪个供应商、什么协议。每个字段作用如下：

model.default
作用：默认使用的模型 ID。
为什么：Agent 执行任务时默认用这个模型，省得每次手动选；ID 要和胜算云控制台一致。

model.provider = "shengsuanyun"
作用：指向 custom_providers 里名为 shengsuanyun 的供应商。
为什么：Hermes 据此知道去哪个供应商取地址和 Key；不设会走默认（官方）供应商。

custom_providers
作用：自定义供应商列表（累加式）。
为什么：Hermes 用累加式管理，把胜算云加进列表不会覆盖你已有的其它供应商（如 OpenRouter），随时可切回——这是它和覆盖式配置的关键区别。

base_url
作用：供应商 API 地址。
为什么：用 GPT 等（chat_completions）时填 https://router.shengsuanyun.com/api/v1（带 /v1）；用 Claude（anthropic_messages）时填 /api（不带 /v1）。

api_key
作用：你的胜算云 Key。
为什么：Hermes 用它鉴权计费；注意 config.yaml 含明文密钥，勿提交到 Git。

api_mode
作用：调用协议。
为什么：必须和模型 + base_url 配套。GPT 等用 chat_completions，Claude 用 anthropic_messages；选错会请求错端点。

models
作用：声明该供应商下可用的模型清单。
为什么：只有写进这里的模型才会在 Hermes 里可选；按 id + name 添加。

4. CLI 快捷命令（不写文件，逐项设置）

hermes config set model.provider shengsuanyun
hermes config set model.default "openai/gpt-5.5"
hermes config set custom_providers.shengsuanyun.base_url "https://router.shengsuanyun.com/api/v1"
hermes config set custom_providers.shengsuanyun.api_key "sk-你的胜算云API Key"
hermes config set custom_providers.shengsuanyun.api_mode "chat_completions"
hermes config get model

5. 交互式向导（新手可选）

也可运行向导一步步配：

hermes model
# 或
hermes setup

向导里：Inference Provider 选 Custom endpoint → Base URL 填 https://router.shengsuanyun.com/api/v1 → 粘贴 Key → 默认 Model ID 填 openai/gpt-5.5。

首次运行与测试

查看状态：
```
hermes status
```
进入 TUI 交互测试：
```
hermes chat
```

📸 截图位置：hermes chat 对话界面

如何更换模型

临时切换：在 hermes chat 里切换模型。
永久修改：编辑 config.yaml 的 model.default，或运行 hermes config set model.default "模型ID"。
深度检查：hermes status --deep、hermes doctor。

常见问题排查

调用报错 / 协议不匹配 → api_mode 和 base_url 要配套：GPT 用 chat_completions + /api/v1，Claude 用 anthropic_messages + /api。
模型 ID 无效 → 必须与胜算云控制台模型列表完全一致。
改了配置没生效 → 运行 hermes restart 重启。
找不到配置文件（Windows） → 路径是 %LOCALAPPDATA%\hermes\config.yaml，注意目录名没有点前缀。
想和其它供应商共存 → 用 custom_providers 累加，不会覆盖。
更新 → hermes self-update 后重新运行 hermes model。