# Hermes 接入

[Hermes Agent](https://hermes-agent.nousresearch.com/)(Nous Research 出品,开源)是一个自治 AI 智能体:连接模型端点、执行任务,并通过持久记忆与技能不断改进。它既是 CLI,也带桌面/消息网关。它能接自定义模型端点,可用 `chat_completions`、`codex_responses`、`anthropic_messages` 三种 `api_mode` 对接 Clomio。


> **服务端边界:** Hermes/OpenClaw 的 `api_mode`、`api`、provider 枚举只是客户端侧选择。Clomio/sub2api 服务端不会识别“Hermes provider”或“OpenClaw enum”，只根据实际 HTTP path 与 API Key 绑定分组路由：Grok 对话走 `POST /v1/responses`，Claude 走 `POST /v1/messages`，OpenAI/Codex 走 Responses/Chat/Images/Embeddings 对应端点；Videos 只属于启用视频能力的 Grok 分组。

---

## 一、安装

macOS / Linux(Windows 用 **WSL2**):

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

安装器会把 Hermes 装到 `~/.hermes/`,创建 Python 3.11 虚拟环境并装好依赖与浏览器工具。需要 Python 3.11+。

---

## 二、接入 Clomio(交互式)

运行模型设置:

```bash
hermes model
```

选 **Custom endpoint(自定义端点 / 自托管)**,依次填:

| 项 | OpenAI-compatible | Anthropic-compatible |
|----|-------------------|----------------------|
| API 基础地址 | `https://api.clomio.ai/v1` | `https://api.clomio.ai` |
| API Key | 你的 Clomio 密钥 | 你的 Clomio 密钥 |
| API mode | `chat_completions` 或 `codex_responses` | `anthropic_messages` |
| 模型名 | 控制台中该分组开放的 GPT/Grok/Codex 模型 | 控制台中该分组开放的 Claude 模型 |

Hermes 当前自定义服务商以 `custom_providers` 保存配置,关键字段是 `api_mode`:

- `chat_completions`: OpenAI-compatible Chat Completions 形状
- `codex_responses`: OpenAI-compatible Responses / Codex Responses 形状
- `anthropic_messages`: Anthropic Messages 形状

> 地址也可换成另外两条[线路](#/gateway-lines)。OpenAI-compatible base URL 带 `/v1`;Anthropic-compatible base URL 不带 `/v1`。

建议按协议拆多个 provider,不要把 GPT、Grok、Claude 放进同一个自定义 provider:

- `clomio-openai`: `chat_completions`,给普通 OpenAI-compatible `/v1/chat/completions`
- `clomio-responses`: `codex_responses`,给 Codex / Responses / Grok Responses
- `clomio-anthropic`: `anthropic_messages`,给 Claude / Anthropic-compatible `/v1/messages`

这样 fallback、辅助模型和 `/model custom:<provider>:<model>` 切换时不会把 Key 发到错误协议。

---

## 三、配置文件方式

Hermes 把服务商配置存在 `~/.hermes/config.yaml`,密钥可放 `~/.hermes/.env`。推荐写 `custom_providers`,不要再使用旧式 `providers:` 写法。

### OpenAI-compatible 示例

适合 GPT、Grok、OpenAI-compatible 代理等。普通 Chat Completions 兼容端点用 `chat_completions`;如果目标分组明确要求 Responses/Codex Responses,改成 `codex_responses`。

```yaml
# ~/.hermes/config.yaml
custom_providers:
  - name: clomio-openai
    base_url: https://api.clomio.ai/v1
    key_env: CLOMIO_API_KEY
    api_mode: chat_completions
    models:
      - id: gpt-5.4
        context_window: 128000

model:
  provider: custom:clomio-openai
  default: gpt-5.4
```

如果接的是只支持 Responses 的分组,例如 Codex Responses 类接口:

```yaml
custom_providers:
  - name: clomio-responses
    base_url: https://api.clomio.ai/v1
    key_env: CLOMIO_API_KEY
    api_mode: codex_responses
    models:
      - id: gpt-5.4-codex
        context_window: 128000

model:
  provider: custom:clomio-responses
  default: gpt-5.4-codex
```

Grok 建议单独配置 Responses provider；Grok 分组也可使用 Chat Completions，Messages 是否可用以分组能力为准:

```yaml
custom_providers:
  - name: clomio-grok
    base_url: https://api.clomio.ai/v1
    key_env: CLOMIO_GROK_API_KEY
    api_mode: codex_responses
    models:
      - id: grok-4.3
        context_window: 1000000

model:
  provider: custom:clomio-grok
  default: grok-4.3
```

### Anthropic-compatible 示例

适合 Claude / Anthropic Messages 形状的分组。注意 base URL **不加** `/v1`。

```yaml
# ~/.hermes/config.yaml
custom_providers:
  - name: clomio-anthropic
    base_url: https://api.clomio.ai
    key_env: CLOMIO_API_KEY
    api_mode: anthropic_messages
    models:
      - id: claude-sonnet-4-6
        context_window: 200000

model:
  provider: custom:clomio-anthropic
  default: claude-sonnet-4-6
```

密钥写入 `~/.hermes/.env`:

```bash
CLOMIO_API_KEY=你的密钥
```

也可以用命令直接设值,免去手改文件:

```bash
hermes config set CLOMIO_API_KEY 你的密钥
```

排查 Hermes 时,先确认它到底读到哪份地址和 key:

| 来源 | 常见位置 | 排查重点 |
|------|----------|----------|
| `custom_providers[*].base_url` / `api_mode` | `~/.hermes/config.yaml` | 决定请求走 `/v1/chat/completions`、`/v1/responses` 还是 `/v1/messages` |
| `key_env` | 当前进程环境或 `~/.hermes/.env` | `hermes config set CLOMIO_API_KEY ...` 通常写到 `.env` |
| `fallback_providers[*].api_key/base_url/api_mode` | `~/.hermes/config.yaml` | 显式 fallback 值会覆盖你以为的默认 provider |
| 辅助模型 / review / vision / compression | `~/.hermes/config.yaml` | 这些槽位可能有自己的 `provider`、`base_url`、`api_mode`,不一定继承主聊天 |
| 旧式 `providers:` | 旧配置文件 | 不推荐;优先迁到 named `custom_providers` |

```bash
grep -nE 'custom_providers|provider|base_url|key_env|api_mode|fallback|auxiliary|vision|review|compression' ~/.hermes/config.yaml
grep -n 'CLOMIO' ~/.hermes/.env
env | grep -E 'CLOMIO|OPENAI|ANTHROPIC|XAI'
```

切换到某个自定义服务商的模型时,可在会话内使用 Hermes 的 custom provider 语法:

```text
/model custom:clomio-openai:gpt-5.4
/model custom:clomio-anthropic:claude-sonnet-4-6
```

Hermes 的 `base_url` 比 `provider` 更显式:同一个模型槽位里只写 `provider` 时,Hermes 使用该 provider 的内置鉴权和内置地址;一旦写了 `base_url`,这个槽位就按该 URL 直连,并使用该槽位的 `api_key`、`key_env` 或 `OPENAI_API_KEY` 这类环境变量鉴权。不要写成 `provider: openrouter` + `base_url: https://api.clomio.ai/v1` 后还以为在走 OpenRouter 规则；实际请求会打到 Clomio。Clomio 最稳写法是 named `custom_providers` + 显式 `api_mode`。

### Fallback 示例

fallback 也要保持协议一致。OpenAI Responses 失败时 fallback 到另一个 Responses provider;Anthropic Messages 失败时 fallback 到 Anthropic-compatible provider:

```yaml
fallback_providers:
  - provider: custom:clomio-responses-backup
    model: gpt-5.4-codex
    base_url: https://sub.qazwc.com/v1
    api_key: ${CLOMIO_BACKUP_OPENAI_KEY}
    api_mode: codex_responses
```

不要把 `anthropic_messages` fallback 填到 `codex_responses` 会话里,也不要用 Grok provider 做 Claude fallback;协议不匹配时通常表现为 400/404 或响应字段解析失败。

---

## 四、重要前提:上下文窗口

> Hermes 带工具的智能体用法**要求至少 64,000 token 的上下文**——窗口太小会在启动时被拒。请选择上下文足够大的模型(控制台分组里标注的大窗口模型)。

配置文件里可用 `context_window` 标注模型窗口,但真正是否能跑取决于上游模型实际支持的上下文。建议选择 64k 以上模型;Claude/GPT/Grok 的大窗口模型更适合 Hermes 的长任务和工具调用。

---

## 五、验证

### 先验证网关

Responses / Codex / Grok Responses:

```bash
curl https://api.clomio.ai/v1/responses \
  -H "Authorization: Bearer $CLOMIO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-5.4","input":"ping","max_output_tokens":8}'
```

Chat Completions:

```bash
curl https://api.clomio.ai/v1/chat/completions \
  -H "Authorization: Bearer $CLOMIO_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"gpt-5.4","messages":[{"role":"user","content":"ping"}],"max_tokens":8}'
```

Anthropic-compatible 可直接测 Messages:

```bash
curl https://api.clomio.ai/v1/messages \
  -H "Authorization: Bearer $CLOMIO_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

> Anthropic-compatible 的 **配置 base URL 不带 `/v1`**,但 HTTP 端点本身仍是 `/v1/messages`;客户端会拼接这段路径。Clomio 用户侧 API Key 默认推荐 `Authorization: Bearer`;只有目标网关或直连 Anthropic Console 明确要求时,才改用 `x-api-key`。

### 再验证 Hermes

```bash
hermes model
hermes
```

配好后启动 Hermes,发一条消息能正常回复即接入成功。若校验端点失败,先确认:

- OpenAI-compatible 的 `base_url` 是 `https://api.clomio.ai/v1`(带 `/v1`、无多余斜杠)
- Anthropic-compatible 的 `base_url` 是 `https://api.clomio.ai`(不带 `/v1`)
- `api_mode` 与分组协议匹配:`chat_completions` / `codex_responses` / `anthropic_messages`
- 密钥正确、分组与模型匹配
- 选用的模型上下文 ≥ 64k

---

## 常见问题

**配置文件应该写 `providers:` 还是 `custom_providers:`?** 写 `custom_providers:`。Hermes 当前自定义端点文档和向导都围绕 `custom_providers` 与 `api_mode`。

**OpenAI-compatible 到底选哪个 `api_mode`?** 普通 `/v1/chat/completions` 兼容服务选 `chat_completions`;需要 `/v1/responses` / Codex Responses 形状的服务选 `codex_responses`。如果选错,常见表现是 404、400、没有工具调用结果或响应字段解析失败。

**Anthropic-compatible 为什么配置不带 `/v1`?** Hermes 会在 `anthropic_messages` 模式下拼 `/v1/messages`。配置成 `https://api.clomio.ai/v1` 容易变成重复路径或端点不匹配。

**启动时提示上下文太小?** 换 64k 以上上下文模型,并确认 `context_window` 不要写小于 64000。仅修改本地标注不能扩大模型真实窗口。

**`hermes model` 找不到模型?** 先确认 Clomio 控制台分组开放了该模型;再确认 `custom_providers[*].models[*].id` 与 `model.default` 完全一致。

**鉴权失败?** 确认 `key_env` 指向的环境变量存在。可运行 `grep CLOMIO_API_KEY ~/.hermes/.env` 或在当前 shell 中 `echo ${CLOMIO_API_KEY:+set}` 检查。`hermes config set CLOMIO_API_KEY ...` 会把密钥写入 `.env`;非密钥设置才进入 `config.yaml`。

**同 base URL 多个 custom provider 串 key?** 先升级 Hermes,再把不同协议/不同 key 拆成不同 provider 名。官方配置说明里 `base_url` 会覆盖 `provider` 并使用该槽位的 `api_key`/环境变量;如果你把多个辅助槽位、fallback 或 custom provider 都写成同一个裸 URL,排查时很难判断实际用了哪把 Key。

**主聊天正常,但 background review / vision / fallback 失败?** 这通常不是 Clomio API 本身的问题,而是 Hermes 某个辅助路径没有继承 custom provider 的 `base_url`、`api_key` 或 `api_mode`。把辅助模型也显式写成 named `custom_providers` 条目,并在 fallback/vision/review 配置里引用同一个 provider;不要只写裸 `provider: custom` + `key_env`。

**同一个 Key 有时通、有时 404/401?** 先看当前会话的 `model.provider` 和请求协议。OpenAI-compatible / Codex / Grok 的 Base URL 是 `https://api.clomio.ai/v1`;Claude / Anthropic-compatible 的 Base URL 是 `https://api.clomio.ai`。如果错误里出现 `/v1/messages` 但你用了 OpenAI/Grok Key,就是 Key 分组或 `api_mode` 不匹配;如果出现 `/v1/chat/completions` 但你配置的是 Grok,就是 provider 应改成 `codex_responses`。

> 关于可视化使用:Hermes 自带桌面端,安装后按其向导用同一套自定义端点配置即可;命令行只负责打通模型调用这一层。其余问题见 [故障排查](#/troubleshooting)。

---

## 外部资料如何映射到 Clomio

- [Hermes AI Providers](https://hermes-agent.nousresearch.com/docs/integrations/providers/):Hermes 有多种内置 provider,也有 `Custom Endpoint`。接 Clomio 时不要套用内置 OpenRouter/xAI/Anthropic 的默认地址,而是按本页建 custom provider。
- [Hermes Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration/):辅助模型、fallback、vision、compression 等槽位都有自己的 `provider`/`model`/`base_url`/`api_key`。主聊天打通不代表这些辅助槽位一定继承 Clomio。
- [Hermes Adding Providers](https://hermes-agent.nousresearch.com/docs/developer-guide/adding-providers/):简单 API-key + OpenAI-compatible endpoint 走 custom provider 最清晰;只有要做专门鉴权/运行时适配时才需要新增内置 provider。
- 与 Clomio 的对应关系:OpenAI/Codex/Grok custom provider 使用 `https://api.clomio.ai/v1`;Claude/Anthropic-compatible custom provider 使用 `https://api.clomio.ai`;Videos 仍只属于 Grok 分组,不是 Hermes 的任意 provider 都能调用。