# 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://tw.llmoxy.com/docs/code-tutorials/hermes-agent 的 markdown 版本。
