在 Hermes 客户端中配置 ZetaAPI

在 Hermes CLI 客户端里把推理 provider 指向 ZetaAPI，一次配置永久生效。注意 OpenAI 兼容模式与 Anthropic 模式的 Base URL 写法不同（是否带 /v1），配错会报「连接失败 / 404」。

更新于 2026-08-24

适用场景

Hermes 是一个命令行 AI Agent 客户端，支持把推理 provider 切换到任意 OpenAI / Anthropic 兼容端点。将 provider 指向 ZetaAPI 后，Hermes 的对话、工具调用、Agent 任务都继续可用，按 ZetaAPI 的倍率计费，余额与用量在控制台实时可查。

⚠️ 最容易踩的坑：OpenAI 兼容模式的 Base URL 要带 /v1，Anthropic 模式的 Base URL 不能带 /v1。写反了会报 连接失败: fetch failed / 404 Invalid URL。详见下方「配置步骤」与「常见问题」。

准备工作

已安装 Hermes CLI（命令行可执行 hermes）
已在 ZetaAPI 控制台获取 API Key（以 sk- 开头）
建议先在控制台开启「低余额提醒」

配置步骤

按你要用的模型协议二选一。大多数用户（用 gpt-5.x 等 OpenAI 系模型）选方式 A。

方式 A：OpenAI 兼容模式（推荐）

hermes config set model.provider custom
hermes config set model.base_url https://api.staging.cosmos-router.com/v1   # ← 必须带 /v1
hermes config set model.api_key  sk-你的Key                  # 或 export OPENAI_API_KEY=sk-...
hermes config set model.default  gpt-5.5                     # 填 ZetaAPI 支持的模型名

方式 B：Anthropic 模式（用 Claude 系列模型）

hermes config set model.provider anthropic
hermes config set model.base_url https://api.staging.cosmos-router.com      # ← 不带 /v1
hermes config set model.api_key  sk-你的Key
hermes config set model.default  claude-sonnet-4-6           # 填 ZetaAPI 支持的 Claude 模型名

也可以运行 hermes setup model 走交互式向导完成同样的配置。

关键：Base URL 是否带 `/v1`

provider 模式	Base URL 写法	说明
`custom`（OpenAI 兼容）	`https://api.staging.cosmos-router.com/v1`	带 `/v1`
`anthropic`	`https://api.staging.cosmos-router.com`	不带 `/v1`

原因：Anthropic 模式下客户端会自动在 Base URL 后追加 /v1/messages，如果 Base URL 已经带了 /v1，就会拼成 /v1/v1/messages 导致 404。

常见问题

Q: 报「连接失败: fetch failed」或「404 Invalid URL」怎么办？

几乎都是 Base URL 的 /v1 写法与 provider 模式不匹配：

custom 模式却填了不带 /v1 的 https://api.staging.cosmos-router.com → 请求打到 /chat/completions（缺 /v1）→ 404；
anthropic 模式却填了带 /v1 的 https://api.staging.cosmos-router.com/v1 → 请求打到 /v1/v1/messages（双 /v1）→ 404。

按上表把 Base URL 改成对应写法即可。

Q: 我在 Codex 里用同一个 Base URL 是好的，为什么 Hermes 不行？

Codex 用的是 OpenAI Responses 协议，Base URL 带 /v1（https://api.staging.cosmos-router.com/v1）。这个写法在 Hermes 的 custom 模式下同样可用；但如果你在 Hermes 里选了 anthropic 模式，同一个带 /v1 的 Base URL 会被拼成双 /v1 而失败。想和 Codex 保持一致，就用 方式 A（custom + 带 /v1）。

Q: 支持哪些模型？

与 ZetaAPI 平台一致（gpt-5.x、Claude 系列等）。用 model.default 指定模型名，模型名要与控制台/文档中的名称完全一致。

Q: 提示余额不足？

ZetaAPI 会返回 402 Payment Required。前往控制台充值后即时恢复，无需重启 Hermes。