# Hermes Agent 配置指南

> 通过 ~/.hermes/config.yaml 与 .env 将 Hermes Agent 的自定义 Provider 指向 LLMoxy，接入 GPT / Claude / Gemini 全系模型。

网址：[https://hermes-agent.nousresearch.com（单击跳转！）](https://hermes-agent.nousresearch.com)

> **📌 关于 Hermes Agent**
> Hermes Agent 是 Nous Research 推出的开源终端 AI 代理，支持 CLI / TUI / API Server 三种入口，可对接任意 OpenAI 兼容端点。

## 源码地址

- GitHub：[NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)
- 官方文档：[hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs)

## 一、安装 Hermes Agent

### 方式 1：pip 安装（推荐）

```bash
pip install hermes-agent
hermes postinstall    # 可选：自动安装 Node.js / 浏览器 / ripgrep / ffmpeg
```

### 方式 2：脚本安装（跟随 main 分支）

```bash
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
```

安装完成后重载 Shell：

```bash
source ~/.zshrc    # 或 source ~/.bashrc
```

## 二、核心配置流程

Hermes Agent 的设置集中在 `~/.hermes/` 目录下：

| 文件 | 用途 |
| --- | --- |
| `~/.hermes/config.yaml` | 模型、Provider、终端、压缩等所有非敏感配置 |
| `~/.hermes/.env` | API Key 等敏感凭证 |

### 1. 配置 config.yaml（自定义 Provider）

打开或创建 `~/.hermes/config.yaml`，把 `model` 块写成 `custom` Provider，并将 `base_url` 指向 LLMoxy：

```yaml
model:
  provider: custom
  base_url: "https://llmoxy.com/v1"
  model: "grok-4.7"
```

也可以使用 CLI 一键写入（自动落到 `config.yaml`）：

```bash
hermes config set model.provider custom
hermes config set model.base_url https://llmoxy.com/v1
hermes config set model.model grok-4.7
```

### 2. 配置 .env（写入 API Key）

把 LLMoxy 令牌写入 `~/.hermes/.env`：

```
OPENAI_API_KEY=<LLMOXY_API_KEY>xxxxxxxxxxxxxxx
```

或使用 CLI（推荐，会自动路由到 `.env`，不会泄露到 YAML 里）：

```bash
hermes config set OPENAI_API_KEY <LLMOXY_API_KEY>xxxxxxxxxxxxxxx
```

将 `<LLMOXY_API_KEY>xxxxxxxxxxxxxxx` 替换为从 [LLMoxy 控制台](https://llmoxy.com/) 获取的真实令牌。

> **💡 提示**
> 请使用 **auto** 分组的令牌。Hermes Agent 通过 OpenAI Chat Completions 协议调用 LLMoxy，`base_url` 必须带 `/v1`。

## 三、交互式快速配置（可选）

如果不想手改 YAML，可运行 `hermes model` 进入交互向导：

```bash
hermes model
```

依次选择：

1. Provider 选项里挑 **Custom Endpoint**
2. Base URL 输入 `https://llmoxy.com/v1`
3. API Key 粘贴 LLMoxy 令牌
4. Model 输入 `grok-4.7`

## 四、启动 Hermes

```bash
hermes          # 经典 CLI
hermes --tui    # 现代 TUI 界面（推荐）
```

启动后欢迎横幅会显示当前激活的模型与 Provider，可输入测试 prompt 验证连通性。

## 完整配置示例

```yaml
# ~/.hermes/config.yaml
model:
  provider: custom
  base_url: "https://llmoxy.com/v1"
  model: "grok-4.7"
```

```
# ~/.hermes/.env
OPENAI_API_KEY=<LLMOXY_API_KEY>xxxxxxxxxxxxxxx
```

> **💡 模型命名规则提示**
> `grok-4.7` 为 LLMoxy 上的标准模型 ID，可在控制台「模型列表」查看。其它常用：
> - **GPT 系列**：`gpt-6.1-sol`
> - **Claude 系列**：`claude-opus-5-5`、`claude-fable-5-2`

## 配置优先级

Hermes Agent 读取配置时遵循以下优先级（从高到低）：

1. 命令行参数
2. `~/.hermes/config.yaml`
3. `~/.hermes/.env`
4. 内置默认值

修改配置后无需重启 Hermes，下一次新会话会自动加载最新的 `config.yaml`。

本文是 https://llmoxy.com/docs/code-tutorials/hermes-agent 的 markdown 版本。
