# Hướng dẫn cấu hình Hermes Agent

> Qua ~/.hermes/config.yaml và .env, trỏ Custom Provider của Hermes Agent tới LLMoxy để kết nối toàn bộ mô hình GPT / Claude / Gemini.

Trang web：[https://hermes-agent.nousresearch.com（nhấp để chuyển！）](https://hermes-agent.nousresearch.com)

> **📌 Về Hermes Agent**
> Hermes Agent là trợ lý AI终端 mã nguồn mở của Nous Research, hỗ trợ CLI / TUI / API Server, có thể kết nối bất kỳ endpoint tương thích OpenAI nào.

## Mã nguồn

- GitHub：[NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)
- Tài liệu chính thức：[hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs)

## 1. Cài đặt Hermes Agent

### Cách 1: pip (khuyến nghị)

```bash
pip install hermes-agent
hermes postinstall    # tùy chọn: tự động cài Node.js / trình duyệt / ripgrep / ffmpeg
```

### Cách 2: script (theo nhánh main)

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

Sau khi cài xong, tải lại Shell：

```bash
source ~/.zshrc    # hoặc source ~/.bashrc
```

## 2. Quy trình cấu hình cốt lõi

Cấu hình Hermes Agent tập trung trong thư mục `~/.hermes/`：

| Tệp | Mục đích |
| --- | --- |
| `~/.hermes/config.yaml` | Tất cả cấu hình không nhạy cảm: mô hình, Provider, terminal, nén, v.v. |
| `~/.hermes/.env` | Thông tin xác thực nhạy cảm như API Key |

### 1. Cấu hình config.yaml (Custom Provider)

Mở hoặc tạo `~/.hermes/config.yaml`, viết khối `model` dưới dạng `custom` Provider và trỏ `base_url` tới LLMoxy：

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

Hoặc dùng CLI để ghi nhanh (tự động lưu vào `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. Cấu hình .env (ghi API Key)

Ghi token LLMoxy vào `~/.hermes/.env`：

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

Hoặc dùng CLI (khuyến nghị, tự động chuyển đến `.env`, không lộ vào YAML)：

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

Thay `<LLMOXY_API_KEY>xxxxxxxxxxxxxxx` bằng token thật lấy từ [bảng điều khiển LLMoxy](https://llmoxy.com/).

> **💡 Mẹo**
> Hãy dùng token nhóm **auto**. Hermes Agent gọi LLMoxy qua giao thức OpenAI Chat Completions, `base_url` phải có `/v1`.

## 3. Cấu hình tương tác nhanh (tùy chọn)

Nếu không muốn sửa YAML thủ công, chạy `hermes model` để vào trình hướng dẫn tương tác：

```bash
hermes model
```

Lần lượt chọn：

1. Trong tùy chọn Provider, chọn **Custom Endpoint**
2. Nhập Base URL `https://llmoxy.com/v1`
3. Dán token LLMoxy vào API Key
4. Nhập Model `grok-4.7`

## 4. Khởi động Hermes

```bash
hermes          # CLI cổ điển
hermes --tui    # Giao diện TUI hiện đại (khuyến nghị)
```

Sau khi khởi động, biểu ngữ chào mừng sẽ hiển thị mô hình và Provider đang kích hoạt; bạn có thể nhập prompt kiểm tra để xác nhận kết nối.

## Ví dụ cấu hình đầy đủ

```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
```

> **💡 Mẹo quy tắc đặt tên mô hình**
> `grok-4.7` là ID mô hình chuẩn trên LLMoxy, có thể xem trong「Danh sách mô hình」của bảng điều khiển. Các ID thường dùng khác：
> - **Dòng GPT**：`gpt-6.1-sol`
> - **Dòng Claude**：`claude-opus-5-5`、`claude-fable-5-2`

## Thứ tự ưu tiên cấu hình

Khi đọc cấu hình, Hermes Agent tuân theo thứ tự ưu tiên (từ cao xuống thấp)：

1. Tham số dòng lệnh
2. `~/.hermes/config.yaml`
3. `~/.hermes/.env`
4. Giá trị mặc định

Sau khi sửa cấu hình, không cần khởi động lại Hermes; phiên mới sẽ tự động tải `config.yaml` mới nhất.

Đây là bản markdown của https://vi.llmoxy.com/docs/code-tutorials/hermes-agent.
