从零配置 Hermes

准备（Preparation） ​

本页适用于 Hermes 自身支持的上游 Provider，例如一个实际兼容 OpenAI 的端点。预计 10 分钟；准备 CC Switch v3.20.0、Hermes 和专用 Key。CC Switch 可以管理 Provider，不代表任何从 /v1/models 发现的模型都能被 Hermes 的运行时协议调用。

下载（Download） ​

从 Hermes Agent 官方仓库 或 官方文档 安装。Windows 官方安装命令是 iex (irm https://hermes-agent.nousresearch.com/install.ps1)；macOS、Linux 与 WSL2 的官方命令是 curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash。CC Switch 固定使用 v3.20.0 Release。打开已安装的 CC Switch，进入 关于，确认显示 v3.20.0；若实际版本不一致，先停止，不要继续配置。安装后新开终端并运行 hermes --version；命令必须成功并打印版本号，找不到命令时先修复 shell 重载或 PATH。

首次启动（First launch） ​

运行 hermes 或 hermes setup，完成 Hermes 自己的初始设置后退出。Windows 默认配置文件是 %LOCALAPPDATA%\hermes\config.yaml，macOS/Linux 默认是 ~/.hermes/config.yaml。实际目录按以下优先级解析：CC Switch 设置中的 Hermes 配置目录覆盖优先，其次是非空的 HERMES_HOME，最后才是平台默认目录；HERMES_HOME 填目录而不是 config.yaml 文件。若设置了多项，以优先级最高者为准。不要在客户端正在更新配置时同时编辑或保存 Provider。

API Key 与分组（API Key and group） ​

在梭子蟹创建仅供 Hermes 使用的 Key，并选择已允许目标模型、端点和能力的分组。只记录 Key 标签，完整 Key 只输入到受信任的本地表单。若计划使用工具，先确认分组权限而不是在失败后反复更换模型。

模型目录：GET /v1/models ​

先使用同一 Key 执行 GET https://suoxie.codes/v1/models，并将返回的 data[].id 原样用作 <MODEL_FROM_V1_MODELS>。下文的 <API_KEY> 只是说明要输入专用 Key；真实值通过隐藏提示临时进入环境变量，不写入命令历史。

$secureKey = Read-Host "API key" -AsSecureString
$credential = [System.Net.NetworkCredential]::new("", $secureKey)
$env:SUOXIE_API_KEY = $credential.Password
try {
  curl.exe --fail-with-body https://suoxie.codes/v1/models `
    -H "Authorization: Bearer $env:SUOXIE_API_KEY"
}
finally {
  Remove-Item Env:SUOXIE_API_KEY
  Remove-Variable secureKey, credential
}

read -rsp "API key: " SUOXIE_API_KEY
printf '\n'
export SUOXIE_API_KEY
curl --fail-with-body https://suoxie.codes/v1/models \
  -H "Authorization: Bearer $SUOXIE_API_KEY"
unset SUOXIE_API_KEY

在 CC Switch 配置 Provider ​

选择 Hermes，新增自定义 Provider，Provider ID/名称都填 suoxie-openai。Base URL 填 https://suoxie.codes/v1，Key 填专用 Key，模型填 <MODEL_FROM_V1_MODELS>，API Mode 选择合法的 chat_completions。若上游实际使用 Anthropic Messages 或 Codex Responses，应分别选择 anthropic_messages 或 codex_responses，不能靠 URL 自动猜测。点击保存只会把 Provider 写入 YAML 的 custom_providers 序列；它不会同时把该 Provider 设为当前。

custom_providers:
  - name: suoxie-openai
    base_url: https://suoxie.codes/v1
    api_key: <API_KEY>
    api_mode: chat_completions
    model: <MODEL_FROM_V1_MODELS>
    models:
      <MODEL_FROM_V1_MODELS>: {}

name 必须等于 Provider ID；模型映射值不写不会被 v3.20.0 序列化的显示 name。不要在 base_url 中追加 /v1/responses 或 /v1/chat/completions，除非 Hermes 的具体 Provider 文档明确要求端点路径。

模型映射与协议（Model mapping and protocol） ​

保存后的 Provider 映射是 suoxie-openai 到 <MODEL_FROM_V1_MODELS>；真实上游模型仍是 <MODEL_FROM_V1_MODELS>。只有另行设为当前后，顶层活动段才应成为：

model:
  provider: suoxie-openai
  default: <MODEL_FROM_V1_MODELS>

默认、快速和备用选择只能来自当前 Key 的模型目录，并且必须被 Hermes 的选定 Provider 协议接受。CC Switch 的本地转换/代理不是对任意模型或私有 API 的普适适配。

保存、启用与重启（Save, enable, and reload） ​

先保存 Provider 并确认它出现在列表中，再在 Provider 卡片执行 设为当前/切换；这项独立操作才会写入顶层 model.provider 和 model.default。关闭 Hermes，重新运行 hermes model，确认当前项是 suoxie-openai 与 <MODEL_FROM_V1_MODELS>，再启动 hermes。若旧模型仍显示，按 CC Switch override、HERMES_HOME、平台默认的优先级检查实际配置目录，并核对 YAML 缩进与字段名。

第一个请求（First request） ​

在干净会话中发送 Reply with OK，然后查看 /model 输出。成功标准是短文本响应和正确的 provider/model；失败时不要同时换 Key、分组、模型和 Base URL，而是逐项定位。

Key 用量（Key usage） ​

打开 Key 用量，用请求时间、Key、分组、端点和真实模型核对请求数、输入/输出 Token 与费用。若暂未看到记录，先刷新和放宽时间范围，再决定是否需要复测。

错误处理（Errors） ​

回滚与安全（Rollback and security） ​

先在 hermes model 恢复旧 Provider/模型，并发送短请求确认；然后移除 custom_providers.suoxie-openai 和本次活动 model 修改，或恢复 CC Switch 在 backups/hermes 创建的时间戳 YAML 备份。不要导出 auth 数据或上传 config.yaml；若正式凭据已泄露，应另行轮换。确认旧 Provider 路径的短请求正常后，最后撤销本轮临时测试 Key。若这里配置的是仍在使用的正式专用 Key，应继续保留它，只撤销本轮临时测试 Key，不影响正在使用的正式 Key。