Bắt đầu nhanh

Hướng dẫn này đưa bạn từ con số 0 đến thiết lập Hermes hoạt động có thể tồn tại trong quá trình sử dụng thực tế. Cài đặt, chọn nhà cung cấp, xác minh cuộc trò chuyện đang hoạt động và biết chính xác phải làm gì khi có sự cố.

Thích xem hơn?

Onchain AI Garage tổng hợp hướng dẫn Masterclass về cài đặt, thiết lập và các lệnh cơ bản — một người bạn đồng hành tốt với trang này nếu bạn muốn theo dõi trên video. Để biết thêm, hãy xem danh sách phát Hermes Agent Tutorials & Use Cases đầy đủ.`<div style=&#123;&#123;position: 'relative', paddingBottom: '56.25%', height: 0, overflow: 'hidden', maxWidth: '100%', marginBottom: '1.5rem'}}> <iframe style=&#123;&#123;position: 'absolute', top: 0, left: 0, width: '100%', height: '100%'}} src="https://www.youtube-nocookie.com/embed/R3YOGfTBcQg" title="Hermes Agent Masterclass: Installation, Setup, Basic Commands" frameBorder="0" allow="accelerometer; CLIpboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen </iframe </div

Đây là dành cho ai

• Thương hiệu mới và muốn có con đường ngắn nhất để thiết lập hoạt động
• Chuyển đổi nhà cung cấp và không muốn mất thời gian config nhầm
• Thiết lập Hermes cho quy trình làm việc nhóm, bot hoặc luôn hoạt động
• Mệt mỏi vì "cài rồi mà vẫn không làm gì"

Con đường nhanh nhất

Chọn hàng phù hợp với mục tiêu của bạn:

Mục tiêu	Làm điều này trước	Sau đó làm điều này
Tôi chỉ muốn Hermes làm việc trên máy của tôi

Hermes setup ` | Chạy một cuộc trò chuyện thực sự và xác minh nó phản hồi | | Tôi đã biết nhà cung cấp của mình |

Hermes model ` | Lưu cấu hình rồi bắt đầu trò chuyện | | Tôi muốn có bot hoặc thiết lập luôn bật |

Hermes gateway setup ` sau khi CLI hoạt động | Kết nối Telegram, Discord, Slack hoặc nền tảng khác | | Tôi muốn một mô hình cục bộ hoặc tự lưu trữ |

Hermes model ` → điểm cuối tùy chỉnh | Xác minh điểm cuối, tên mô hình và độ dài ngữ cảnh | | Tôi muốn dự phòng nhiều nhà cung cấp |

Hermes model ` đầu tiên | Chỉ thêm định tuyến và dự phòng sau khi trò chuyện cơ sở hoạt động |

Quy tắc chung: nếu Hermes không thể hoàn thành cuộc trò chuyện bình thường thì chưa thêm tính năng nào khác. Trước tiên, hãy thực hiện một cuộc trò chuyện rõ ràng, sau đó xếp lớp vào cổng, cron, kỹ năng, giọng nói hoặc định tuyến.

---

##1. Cài đặt Đại lý Hermes`Tùy chọn A - pip (đơn giản nhất):

pip install Hermes-agent
Hermes postinstall     # optional: installs Node.js, browser, ripgrep, ffmpeg + runs setup

`
``PyPI phát hành các phiên bản được gắn thẻ theo dõi (bản phát hành chính/nhỏ), không phải mọi cam kết trên 
`main

. Để có tính năng vượt trội, hãy sử dụng Tùy chọn B.

**Tùy chọn B — trình cài đặt git (theo dõi nhánh chính):**

`bash

# Linux / macOS / WSL2 / Android (Termux)
curl -fSSL https://raw.GitHubusercontent.com/NousResearch/Hermes-agent/main/scripts/install.sh | bash

`

:::tip[Android / Termux]
Nếu bạn đang cài đặt trên điện thoại, hãy xem [Termux guide](./Termux.md) chuyên dụng để biết đường dẫn thủ công đã được kiểm tra, các tính năng bổ sung được hỗ trợ và các giới hạn hiện tại dành riêng cho Android.
:::

:::tip[Windows Users]
Trước tiên hãy cài đặt [WSL2](https://learn.Microsoft.com/en-us/Windows/wsl/install), sau đó chạy lệnh trên bên trong terminal WSL2 của bạn.
:::

Sau khi hoàn tất, hãy tải lại shell của bạn:

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

`
``Để biết các tùy chọn cài đặt chi tiết, điều kiện tiên quyết và cách khắc phục sự cố, hãy xem [Installation guide](./installation.md).

## 2. Chọn nhà cung cấp

Bước thiết lập quan trọng nhất. Sử dụng 
`Hermes model
` để xem qua lựa chọn một cách tương tác:

`bash
Hermes model

`

:::tip[Easiest path: Nous Portal]
Một đăng ký bao gồm hơn 300 kiểu máy cùng với [Tool Gateway](../user-guide/features/tool-gateway.md) (tìm kiếm trên web, tạo hình ảnh, TTS, trình duyệt đám mây). Khi cài đặt mới:

`bash
Hermes setup --portal

`
``Thao tác này sẽ giúp bạn đăng nhập, đặt Nous làm nhà cung cấp của bạn và bật Cổng công cụ bằng một lệnh.

:::

Mặc định tốt:| Nhà cung cấp | Nó là gì | Cách thiết lập |
|----------|-------------|---------------|
| **Nous Portal** | Dựa trên đăng ký, không cấu hình | Đăng nhập OAuth qua 
`Hermes model
` |
| **OpenAI Codex** | ChatGPT OAuth, sử dụng mô hình Codex | Xác thực mã thiết bị qua 
`Hermes model
` |
| **Anthropic** | Trực tiếp mô hình Claude — Gói tối đa + tín dụng sử dụng bổ sung (OAuth) hoặc khóa API để trả cho mỗi mã thông báo |

Hermes model
` → đăng nhập OAuth (yêu cầu tối đa + tín dụng bổ sung) hoặc khóa API Anthropic |
| **OpenRouter** | Định tuyến nhiều nhà cung cấp trên nhiều mô hình | Nhập khóa API của bạn |
| **Z.AI** | Các mô hình được lưu trữ trên máy chủ GLM / Zhipu | Đặt 
`GLM_API_KEY
` / 
`ZAI_API_KEY
` |
| **Kimi / Moonshot** | Các mô hình trò chuyện và mã hóa được lưu trữ trên Moonshot | Đặt 
`Kimi_API_KEY
` (hoặc 
`Kimi_CODING_API_KEY
` dành riêng cho Mã hóa Kimi) |
| **Kimi / Moonshot Trung Quốc** | Điểm cuối Moonshot khu vực Trung Quốc | Đặt 
`Kimi_CN_API_KEY
` |
| **Arcee AI** | Mô hình ba ngôi | Đặt 
`ARCEEAI_API_KEY
` |
| **Đám mây GMI** | API trực tiếp đa mô hình | Đặt 
`GMI_API_KEY
` |
| **MiniMax (OAuth)** | MiniMax-M2.7 qua trình duyệt OAuth — không cần khóa API |

Hermes model
` → MiniMax (OAuth) |
| **MiniMax** | Điểm cuối MiniMax quốc tế | Đặt 
`MiniMax_API_KEY
` |
| **MiniMax China** | Điểm cuối MiniMax khu vực Trung Quốc | Đặt 
`MiniMax_CN_API_KEY
` |
| **Alibaba Cloud** | Mô hình Qwen qua DashScope | Đặt 
`DASHSCOPE_API_KEY
` |
| **Hugging Face** | Hơn 20 mô hình mở thông qua unified router (Qwen, DeepSeek, Kimi, v.v.) | Đặt 
`HF_TOKEN
` |
| **AWS Bedrock** | Claude, Nova, Llama, DeepSeek thông qua API Converse gốc | Vai trò IAM hoặc 
`aws configure
` ([guide](../guides/aws-bedrock.md)) |
| **KiloCode** | Các mô hình được lưu trữ trên KiloCode | Đặt 
`KILOCODE_API_KEY
` |
| **OpenCode Zen** | Quyền truy cập trả tiền khi bạn di chuyển vào các mô hình được quản lý | Đặt 
`OPENCODE_ZEN_API_KEY
` |
| **OpenCode Go** | Đăng ký $10/tháng cho các mô hình mở | Đặt 
`OPENCODE_GO_API_KEY
` |
| **DeepSeek** | Truy cập API DeepSeek trực tiếp | Đặt 
`DeepSeek_API_KEY
` |
| **NVIDIA NIM** | Các mô hình Nemotron qua build.nvidia.com hoặc NIM địa phương | Đặt 
`NVIDIA_API_KEY
` (tùy chọn: 
`NVIDIA_BASE_URL

) |
| **GitHub Copilot** | Đăng ký GitHub Copilot (GPT-5.x, Claude, Gemini, v.v.) | OAuth qua 
`Hermes model
` hoặc 
`COPILOT_GitHub_TOKEN
` / 
`GH_TOKEN
` |
| **GitHub Copilot ACP** | Phần phụ trợ tác nhân Copilot ACP (sinh ra 
`copilot
` CLI cục bộ) | 
`Hermes model
` (yêu cầu 
`copilot
` CLI + 
`copilot login

) |
| **Vercel AI Gateway** | Định tuyến cổng Vercel AI | Đặt 
`AI_GATEWAY_API_KEY
` |
| **Custom Endpoint** | vLLM, SGLang, OLlama hoặc bất kỳ API tương thích với OpenAI nào | Đặt URL cơ sở + khóa API |

Đối với hầu hết người dùng lần đầu: hãy chọn nhà cung cấp, chấp nhận các giá trị mặc định trừ khi bạn biết lý do bạn thay đổi chúng. Danh mục nhà cung cấp đầy đủ với các biến env và các bước thiết lập có trên trang [Providers](../integrations/providers.md).

:::caution[Minimum context: 64K tokens]
Đại lý Hermes yêu cầu một mô hình có ít nhất **64.000 mã thông báo** bối cảnh. Các mô hình có cửa sổ nhỏ hơn không thể duy trì đủ bộ nhớ làm việc cho quy trình gọi công cụ nhiều bước và sẽ bị từ chối khi khởi động. Hầu hết các mô hình được lưu trữ (Claude, GPT, Gemini, Qwen, DeepSeek) đều dễ dàng đáp ứng được điều này. Nếu bạn đang chạy mô hình cục bộ, hãy đặt kích thước ngữ cảnh của mô hình đó thành ít nhất 64K (ví dụ: 

--ctx-size 65536
` cho Llama.cpp hoặc 

-c 65536
` cho OLlama).
:::

:::tip
Bạn có thể chuyển đổi nhà cung cấp bất kỳ lúc nào với 
`Hermes model

 - không cần khóa. Để biết danh sách đầy đủ tất cả các nhà cung cấp được hỗ trợ và chi tiết thiết lập, hãy xem [AI Providers](../integrations/providers.md).
:::

### Cách lưu trữ cài đặt

Hermes tách bí mật khỏi cấu hình thông thường:
- **Bí mật và mã thông báo** → 

~/.Hermes/.env

- **Cài đặt không bí mật** → 

~/.Hermes/config.yaml
``Cách dễ nhất để đặt giá trị chính xác là thông qua CLI:

``` bash
Hermes config set model Anthropic/Claude-opus-4.6
Hermes config set terminal.backend Docker
Hermes config set OpenRouter_API_KEY sk-or-...

`
``Giá trị phù hợp sẽ tự động chuyển đến đúng tệp.

## 3. Chạy cuộc trò chuyện đầu tiên của bạn

`bash
Hermes            # classic CLI
Hermes --TUI      # modern TUI (recommended)

`
``Bạn sẽ thấy biểu ngữ chào mừng có mô hình, công cụ có sẵn và kỹ năng của bạn. Sử dụng lời nhắc cụ thể và dễ xác minh:

:::tip[Pick your interface]
Hermes cung cấp hai giao diện đầu cuối: 
`prompt_toolkit
` CLI cổ điển và [TUI](../user-guide/TUI.md) mới hơn với lớp phủ phương thức, lựa chọn chuột và đầu vào không chặn. Cả hai đều có chung phiên, lệnh gạch chéo và cấu hình — hãy thử từng phiên với 
`Hermes
` và 
`Hermes --TUI

.

:::

`
Summarize this repo in 5 bullets and tell me what the main entrypoint is.

`

`

Check my current directory and tell me what looks like the main project file.

`

`

Help me set up a clean GitHub PR workflow for this codebase.

`
``**Thành công trông như thế nào:**- Biểu ngữ hiển thị mô hình/nhà cung cấp bạn đã chọn
- Hermes trả lời không sai sót
- Nó có thể sử dụng một công cụ nếu cần (terminal, đọc tệp, tìm kiếm trên web)
- Cuộc trò chuyện tiếp tục bình thường trong hơn một lượt

Nếu cách đó hiệu quả thì bạn đã vượt qua phần khó khăn nhất.

## 4. Xác minh phiên làm việc

Trước khi tiếp tục, hãy đảm bảo sơ yếu lý lịch hoạt động:

``` bash
Hermes --Continue    # Resume the most recent session
Hermes -c            # Short form

`
``Điều đó sẽ đưa bạn trở lại phiên bạn vừa có. Nếu không, hãy kiểm tra xem bạn có ở trong cùng một hồ sơ hay không và phiên có thực sự được lưu hay không. Điều này quan trọng sau này khi bạn sắp xếp nhiều thiết lập hoặc máy móc.

## 5. Dùng thử các tính năng chính

### Sử dụng terminal

`
❯ What's my disk usage? Show the top 5 largest directories.

`
``Tác nhân thay mặt bạn chạy các lệnh đầu cuối và hiển thị kết quả.

### Lệnh gạch chéo

Nhập 

/
` để xem danh sách thả xuống tự động hoàn thành của tất cả các lệnh:

| Lệnh | Nó làm gì |
|----------|-------------|
| 

/help
` | Hiển thị tất cả các lệnh có sẵn |
| 

/tools
` | Liệt kê các công cụ có sẵn |
| 

/model
` | Chuyển đổi mô hình tương tác |
| 

/personality pirate
` | Hãy thử tính cách vui vẻ |
| 

/save
` | Lưu cuộc trò chuyện |

### Nhập nhiều dòng

Nhấn 
`Alt+Enter

, 
`Ctrl+J
` hoặc 
`Shift+Enter
` để thêm dòng mới. 
`Shift+Enter
` yêu cầu terminal gửi nó dưới dạng một chuỗi riêng biệt (Kitty / foot / WezTerm / Ghostty theo mặc định; terminal iTerm2 / Alacritty / VS Code sau khi giao thức bàn phím Kitty được bật). 
`Alt+Enter
` và 
`Ctrl+J
` hoạt động ở mọi terminal.

### Ngắt đại lý

If the agent is taking too long, type a new message and press Enter — it interrupts the current task and switches to your new instructions. 
`Ctrl+C
` cũng hoạt động.

## 6. Thêm lớp tiếp theo

Chỉ sau khi trò chuyện cơ bản hoạt động. Chọn những gì bạn cần:

### Bot hoặc trợ lý chung

`bash
Hermes gateway setup    # Interactive platform configuration

`
``Kết nối [Telegram](/docs/user-guide/messaging/Telegram), [Discord](/docs/user-guide/messaging/Discord), [Slack](/docs/user-guide/messaging/Slack), [WhatsApp](/docs/user-guide/messaging/WhatsApp), [Signal](/docs/user-guide/messaging/Signal), [Email](/docs/user-guide/messaging/email) hoặc [Home Assistant](/docs/user-guide/messaging/homeassistant) hoặc [Microsoft Teams](/docs/user-guide/messaging/teams).

### Tự động hóa và công cụ
- 
`Hermes tools
` — điều chỉnh quyền truy cập công cụ trên mỗi nền tảng

- 
`Hermes skills

 - duyệt và cài đặt các quy trình công việc có thể tái sử dụng
- Cron — chỉ sau khi thiết lập bot hoặc CLI của bạn ổn định

### Thiết bị đầu cuối có hộp cát

Để an toàn, hãy chạy tác nhân trong vùng chứa Docker hoặc trên máy chủ từ xa:

``` bash
Hermes config set terminal.backend Docker    # Docker isolation
Hermes config set terminal.backend SSH       # Remote server

`

### Chế độ giọng nói

`bash

# From the Hermes install directory (the curl installer placed it at
# ~/.Hermes/Hermes-agent on Linux/macOS or %LOCALAPPDATA%\Hermes\Hermes-agent on Windows):
cd ~/.Hermes/Hermes-agent
uv pip install -e ".[voice]"
# Includes faster-whisper for free local speech-to-text

`
``Sau đó trong CLI: 

/voice on

. Nhấn 
`Ctrl+B
` để ghi. Xem [Voice Mode](../user-guide/features/voice-mode.md).

### Kỹ năng

``` bash
Hermes skills search Kubernetes
Hermes skills install OpenAI/skills/k8s

`
``Hoặc sử dụng 

/skills
` trong phiên trò chuyện.

### máy chủ MCP

`YAML

# Add to ~/.Hermes/config.yaml
MCP_servers:
  GitHub:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-GitHub"]
    env:
      GitHub_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

`

### Tích hợp trình chỉnh sửa (ACP)

Hỗ trợ ACP đi kèm với các tính năng bổ sung 

[all]
` tiêu chuẩn, do đó trình cài đặt cuộn tròn đã bao gồm nó. Chỉ cần chạy:

``` bash
Hermes ACP

`
``(Nếu bạn đã cài đặt mà không có 

[all]

, trước tiên hãy chạy 
`cd ~/.Hermes/Hermes-agent && uv pip install -e ".[ACP]"

.)

Xem [ACP Editor Integration](../user-guide/features/ACP.md).

---

## Các chế độ lỗi thường gặp

Đây là những vấn đề gây lãng phí thời gian nhất:

| Triệu chứng | Nguyên nhân có thể | Sửa chữa |
|---|---|---|
| Hermes mở đầu nhưng trả lời trống rỗng hoặc đứt quãng | Xác thực nhà cung cấp hoặc lựa chọn mô hình là sai | Chạy lại 
`Hermes model
` và xác nhận nhà cung cấp, kiểu máy và xác thực |
| Custom Endpoint "hoạt động" nhưng trả về rác | URL cơ sở, tên mẫu máy sai hoặc không thực sự tương thích với OpenAI | Trước tiên hãy xác minh điểm cuối trong một ứng dụng khách riêng biệt |
| Cổng khởi động nhưng không ai có thể nhắn tin cho nó | Mã thông báo bot, danh sách cho phép hoặc thiết lập nền tảng chưa hoàn tất | Chạy lại 
`Hermes gateway setup
` và kiểm tra 
`Hermes gateway status
` |
| 
`Hermes --Continue
` không tìm thấy phiên cũ | Hồ sơ hoặc phiên đã chuyển đổi không bao giờ được lưu | Kiểm tra 
`Hermes sessions list
` và xác nhận bạn đang truy cập đúng hồ sơ |
| Mô hình không có sẵn hoặc hành vi dự phòng kỳ lạ | Cài đặt định tuyến hoặc dự phòng của nhà cung cấp quá linh hoạt | Tiếp tục tắt định tuyến cho đến khi nhà cung cấp cơ sở ổn định |
| Sự cố cấu hình cờ 
`Hermes doctor
` | Giá trị cấu hình bị thiếu hoặc cũ | Sửa cấu hình, test lại chat đơn giản trước khi thêm tính năng |

## Bộ công cụ khôi phục

Khi có điều gì đó không ổn, hãy sử dụng thứ tự này:
1. 
`Hermes doctor

`
2. 
`Hermes model

3. 
`Hermes setup

4. 
`Hermes sessions list

5. 
`Hermes --Continue

6. 
`Hermes gateway status
``Trình tự đó đưa bạn từ "những rung cảm tan vỡ" trở lại trạng thái đã biết một cách nhanh chóng.

---

## Tham khảo nhanh| Lệnh | Mô tả |
|----------|-------------|
| 
`Hermes
` | Bắt đầu trò chuyện |
| 
`Hermes model
` | Chọn nhà cung cấp và mô hình LLM của bạn |
| 
`Hermes tools
` | Định cấu hình công cụ nào được bật trên mỗi nền tảng |
| 
`Hermes setup
` | Trình hướng dẫn thiết lập đầy đủ (cấu hình mọi thứ cùng một lúc) |
| 
`Hermes doctor
` | Chẩn đoán sự cố |
| 
`Hermes update
` | Cập nhật lên phiên bản mới nhất |
| 
`Hermes gateway
` | Bắt đầu cổng nhắn tin |
| 
`Hermes --Continue
` | Tiếp tục phiên cuối cùng |

## Các bước tiếp theo
- **[CLI Guide](../user-guide/CLI.md)** — Làm chủ giao diện đầu cuối
- **[Configuration](../user-guide/configuration.md)** — Tùy chỉnh thiết lập của bạn
- **[Messaging Gateway](../user-guide/messaging/index.md)** — Kết nối Telegram, Discord, Slack, WhatsApp, Signal, Email, Trợ lý tại nhà, Nhóm, v.v.
- **[Tools & Toolsets](../user-guide/features/tools.md)** — Khám phá các khả năng sẵn có
- **[AI Providers](../integrations/providers.md)** — Danh sách nhà cung cấp đầy đủ và chi tiết thiết lập
- **[Skills System](../user-guide/features/skills.md)** — Kiến thức và quy trình làm việc có thể tái sử dụng
- **[Tips & Best Practices](../guides/tips.md)** — Lời khuyên dành cho người dùng thành thạo