Cài đặt

Thiết lập và chạy Hermes Agent trong vòng chưa đầy hai phút bằng trình cài đặt một dòng.

Cài đặt nhanh

Trình cài đặt một dòng (Linux / macOS / WSL2)

Đối với bản cài đặt dựa trên git theo dõi main và cung cấp cho bạn những thay đổi mới nhất ngay lập tức:

curl -fSSL https://raw.GitHubusercontent.com/NousResearch/Hermes-agent/main/scripts/install.sh | bash

`

### Windows (bản địa, PowerShell) - Bản Beta sớm

:::warning[Early BETA]
Hỗ trợ Windows gốc là **beta sớm**. Nó cài đặt và hoạt động trên các đường dẫn chung nhưng chưa được thử nghiệm rộng rãi như trình cài đặt POSIX của chúng tôi. Vui lòng [file issues](https://GitHub.com/NousResearch/Hermes-agent/issues) khi bạn chạm vào các cạnh thô. Để có thiết lập được thử nghiệm nhiều nhất trên Windows hiện nay, hãy sử dụng phần mềm Linux/macOS bên trên bên trong **WSL2**.

:::

Mở PowerShell và chạy:

``` powershell
iex (irm https://raw.GitHubusercontent.com/NousResearch/Hermes-agent/main/scripts/install.ps1)

`
``Trình cài đặt xử lý **mọi thứ**: 
`uv

, Python 3.11, Node.js 22, 
`ripgrep

, 
`ffmpeg

, **và Git Bash di động** (PortableGit — một bản phân phối Git-for-Windows độc lập cung cấp 
`bash.exe
` và chuỗi công cụ POSIX đầy đủ mà Hermes sử dụng cho các lệnh shell; trên Windows 32-bit, trình cài đặt quay trở lại MinGit, thiếu bash và vô hiệu hóa các tính năng của công cụ đầu cuối/trình duyệt tác nhân).  Nó sao chép repo theo 

%LOCALAPPDATA%\Hermes\Hermes-agent

, tạo virtualenv và thêm 
`Hermes
` vào **User PATH** của bạn.  Khởi động lại terminal của bạn (hoặc mở cửa sổ PowerShell mới) sau khi cài đặt để PATH chọn.

**Cách xử lý Git:**

1. Nếu 
`git
` đã có trên PATH của bạn, trình cài đặt sẽ sử dụng cài đặt hiện có của bạn.
2. Nếu không, nó sẽ tải xuống **PortableGit** di động (~50 MB, từ bản phát hành 
`git-for-Windows
` GitHub chính thức) và giải nén nó thành 

%LOCALAPPDATA%\Hermes\git

.  Không cần quyền quản trị.  Hoàn toàn bị cô lập - nó sẽ không can thiệp vào bất kỳ cài đặt Git nào của hệ thống, dù bị hỏng hay không.  (Trên Windows 32 bit, nó quay trở lại MinGit vì PortableGit chỉ cung cấp nội dung 64 bit và ARM64; các tính năng Hermes phụ thuộc vào bash sẽ không hoạt động trên máy chủ 32 bit.)

**Tại sao không sử dụng winget?** Các thiết kế trước đó đã tự động cài đặt Git thông qua 
`winget install Git.Git

, nhưng winget bị lỗi nặng khi cài đặt Git hệ thống ở trạng thái một phần hoặc bị hỏng (chính xác là khi người dùng cần trình cài đặt để hoạt động).  Phương pháp tiếp cận Git di động vượt qua winget, sổ đăng ký trình cài đặt Windows và bất kỳ hệ thống Git hiện có nào.  Nếu bản cài đặt Hermes Git bị hỏng, hãy 
`Remove-Item %LOCALAPPDATA%\Hermes\git
` và chạy lại trình cài đặt — không ảnh hưởng đến hệ thống, không có kịch tính khi gỡ cài đặt.

Trình cài đặt cũng đặt 
`Hermes_GIT_BASH_PATH
` thành 
`bash.exe
` được định vị để Hermes giải quyết nó một cách dứt khoát trong vỏ mới.

Nếu bạn thích WSL2 hơn, trình cài đặt Linux ở trên sẽ hoạt động bên trong nó; cả cài đặt gốc và WSL đều có thể cùng tồn tại mà không có xung đột (dữ liệu gốc nằm trong 

%LOCALAPPDATA%\Hermes

, dữ liệu WSL nằm trong 

~/.Hermes

).

**Trình cài đặt máy tính để bàn (thay thế):** Cũng có sẵn trình cài đặt GUI mỏng — tải xuống Hermes Desktop, chạy 

.exe
` và trong lần khởi chạy đầu tiên, nó gọi 
`install.ps1
` dưới phần mềm để cung cấp Python (thông qua 
`uv

), Node, PortableGit và phần còn lại của các phần phụ thuộc. Ứng dụng dành cho máy tính để bàn và CLI do PowerShell cài đặt có chung thư mục cài đặt và dữ liệu, vì vậy bạn có thể sử dụng một trong hai hoặc cả hai. Xem [Windows (Native) guide](../user-guide/Windows-native#desktop-installer-alternative) để biết chi tiết.

### Android / Termux

Hermes hiện cũng cung cấp đường dẫn cài đặt nhận biết Termux:

``` bash
curl -fSSL https://raw.GitHubusercontent.com/NousResearch/Hermes-agent/main/scripts/install.sh | bash

`
``Trình cài đặt tự động phát hiện Termux và chuyển sang luồng Android đã được thử nghiệm:

- sử dụng Termux 
`pkg
` cho các phần phụ thuộc hệ thống (
`git

, 
``` python

, 
`nodejs

, 
`ripgrep

, 
`ffmpeg

, công cụ xây dựng)

- tạo virtualenv với 
`Python -m venv

- tự động xuất 
`ANDROID_API_LEVEL
` cho các bản dựng bánh xe Android
- thích phần bổ sung 

.[Termux-all]
` rộng hơn và quay trở lại phần bổ sung 

.[Termux]
` nhỏ hơn (và cuối cùng là cài đặt cơ sở) nếu lần thử đầu tiên không biên dịch được
- bỏ qua trình duyệt chưa được kiểm tra / bootstrap WhatsApp theo mặc định

Nếu bạn muốn có đường dẫn đầy đủ rõ ràng, hãy làm theo [Termux guide](./Termux.md) chuyên dụng.

:::note[Windows Feature Parity (Early Beta)Windows gốc đang ở **phiên bản beta sớm**. Mọi thứ ngoại trừ terminal trò chuyện trên trang tổng quan dựa trên trình duyệt đều chạy tự nhiên trên Windows:]
- **CLI (
`Hermes chat

, 
`Hermes setup

, 
`Hermes gateway

, …)** — gốc, sử dụng terminal mặc định của bạn
- **Gateway (Telegram, Discord, Slack, …)** — gốc, chạy dưới dạng quy trình PowerShell nền
- **Bộ lập lịch Cron** — gốc
- **Công cụ trình duyệt** — gốc (Chromium qua Node.js)
- **Máy chủ MCP** — gốc (hỗ trợ cả truyền tải stdio và HTTP)
- **Khung terminal 

/chat
` của bảng điều khiển** — **chỉ WSL2** (sử dụng POSIX PTY; Windows gốc không có tương đương).  Phần còn lại của trang tổng quan (phiên, công việc, số liệu) hoạt động nguyên bản — chỉ có tab terminal PTY được nhúng mới được kiểm soát.

Đặt 
`Hermes_DISABLE_Windows_UTF8=1
` trong môi trường của bạn nếu bạn gặp lỗi liên quan đến mã hóa và muốn quay lại đường dẫn stdio cp1252 cũ (hữu ích cho việc chia đôi).
:::

### Trình cài đặt làm gì

Trình cài đặt xử lý mọi thứ một cách tự động — tất cả các phần phụ thuộc (Python, Node.js, ripgrep, ffmpeg), bản sao kho lưu trữ, môi trường ảo, thiết lập lệnh 
`Hermes
` toàn cầu và cấu hình nhà cung cấp LLM. Cuối cùng, bạn đã sẵn sàng trò chuyện.

#### Bố cục cài đặt

Nơi trình cài đặt đặt mọi thứ tùy thuộc vào việc bạn cài đặt với tư cách người dùng bình thường hay người dùng root:

| Trình cài đặt | Mã sống tại |

Hermes
` nhị phân | Thư mục dữ liệu |
|---|---|---|---|
| cài đặt pip | Gói trang web Python |

~/.local/bin/Hermes
` (console_scripts) | 

~/.Hermes/
` |
| Mỗi người dùng (trình cài đặt git) |

~/.Hermes/Hermes-agent/
` | 

~/.local/bin/Hermes
` (liên kết tượng trưng) | 

~/.Hermes/
` |
| Chế độ gốc (
`sudo curl … \| sudo bash

) | 

/usr/local/lib/Hermes-agent/
` | 

/usr/local/bin/Hermes
` | 

/root/.Hermes/
` (hoặc 

$Hermes_HOME

) |

Chế độ gốc **Bố cục FHS** (

/usr/local/lib/…

, 

/usr/local/bin/Hermes

) phù hợp với nơi các công cụ dành cho nhà phát triển trên toàn hệ thống khác có trên Linux. Tính năng này hữu ích cho việc triển khai máy dùng chung trong đó một bản cài đặt hệ thống sẽ phục vụ mọi người dùng. Cấu hình mỗi người dùng (xác thực, kỹ năng, phiên) vẫn tồn tại dưới 

~/.Hermes/
` hoặc 
`Hermes_HOME
` rõ ràng của mỗi người dùng.

### Sau khi cài đặt

Tải lại shell của bạn và bắt đầu trò chuyện:

``` bash
source ~/.bashrc   # or: source ~/.zshrc
Hermes             # Start chatting!

`
``Để cấu hình lại các cài đặt riêng lẻ sau này, hãy sử dụng các lệnh chuyên dụng:

`bash
Hermes model          # Choose your LLM provider and model
Hermes tools          # Configure which tools are enabled
Hermes gateway setup  # Set up messaging platforms
Hermes config set     # Set individual config values
Hermes setup          # Or run the full setup wizard to configure everything at once

`

:::tip[Fastest path: Nous Portal]
Một đăng ký bao gồm hơn 300 kiểu máy cùng với [Tool Gateway](/docs/user-guide/features/tool-gateway) (tìm kiếm trên web, tạo hình ảnh, TTS, trình duyệt đám mây). Bỏ qua việc tung hứng phím trên mỗi công cụ:

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

:::

---

## Điều kiện tiên quyết`**cài đặt pip:** Không có điều kiện tiên quyết nào ngoài Python 3.11+. Mọi thứ khác được xử lý tự động.

**Trình cài đặt Git:** Điều kiện tiên quyết duy nhất là **Git**. Trình cài đặt tự động xử lý mọi thứ khác:
- **uv** (trình quản lý gói Python nhanh)
- **Python 3.11** (thông qua uv, không cần sudo)
- **Node.js v22** (dành cho tự động hóa trình duyệt và cầu nối WhatsApp)
- **ripgrep** (tìm kiếm tập tin nhanh)
- **ffmpeg** (chuyển đổi định dạng âm thanh cho TTS)

:::info
Bạn **không** cần cài đặt Python, Node.js, ripgrep hoặc ffmpeg theo cách thủ công. Trình cài đặt sẽ phát hiện những gì còn thiếu và cài đặt nó cho bạn. Chỉ cần đảm bảo có sẵn 
`git
` (
`git --version

).
:::

:::tip[Nix users]
Nếu bạn sử dụng Nix (trên NixOS, macOS hoặc Linux), sẽ có đường dẫn thiết lập chuyên dụng với phần mềm Nix, mô-đun NixOS khai báo và chế độ vùng chứa tùy chọn. Xem hướng dẫn **[Nix & NixOS Setup](./nix-setup.md)**.
:::

---

## Cài đặt thủ công / dành cho nhà phát triển

Nếu bạn muốn sao chép kho lưu trữ và cài đặt từ nguồn — để đóng góp, chạy từ một nhánh cụ thể hoặc có toàn quyền kiểm soát môi trường ảo — hãy xem phần [Development Setup](../developer-guide/contributing.md#development-setup) trong hướng dẫn Đóng góp.

---

## Số lượt cài đặt của người dùng dịch vụ hệ thống / không phải Sudo

Hỗ trợ chạy Hermes với tư cách là người dùng chuyên dụng không có đặc quyền (ví dụ: tài khoản dịch vụ hệ thống 
`Hermes
` hoặc bất kỳ người dùng nào không có quyền truy cập 
`sudo

). Điều duy nhất trên đường dẫn cài đặt thực sự cần root là bước 

--with-deps
` của Playwright, bước này 
`apt
` cài đặt các thư viện dùng chung (
`libnss3

, 
`libxkbcommon

, v.v.) được sử dụng bởi Chrome. Trình cài đặt sẽ phát hiện xem sudo có sẵn hay không và giảm dần khi không có — nó sẽ cài đặt tệp nhị phân Chrome vào bộ nhớ đệm Playwright của chính người dùng dịch vụ và in lệnh chính xác mà quản trị viên cần chạy riêng.**Phần chia được đề xuất (Debian/Ubuntu):**
1. **Một lần, với tư cách là người dùng quản trị viên có sudo**, hãy cài đặt các thư viện hệ thống mà Chrome cần:

``` bash
   sudo npx playwright install-deps chromium

`
   (Bạn có thể chạy cái này từ bất cứ đâu - 
`npx
` sẽ tìm nạp Nhà viết kịch một cách nhanh chóng.)
2. **Là người dùng dịch vụ không có đặc quyền**, hãy chạy trình cài đặt thông thường. Nó sẽ phát hiện sudo bị thiếu, bỏ qua 

`
--with-deps
` và cài đặt Chrome vào bộ đệm Playwright cục bộ của người dùng:

``` bash
   curl -fSSL https://raw.GitHubusercontent.com/NousResearch/Hermes-agent/main/scripts/install.sh | bash

``Nếu bạn muốn bỏ qua hoàn toàn bước Nhà viết kịch — chẳng hạn vì bạn đang chạy không đầu và không cần tự động hóa trình duyệt — hãy vượt qua 

`
--skip-browser

:

``` bash
   curl -fSSL https://raw.GitHubusercontent.com/NousResearch/Hermes-agent/main/scripts/install.sh | bash -s -- --skip-browser

3. ** Cung cấp 
`Hermes
` cho hệ vỏ của người dùng dịch vụ.** Trình cài đặt ghi trình khởi chạy vào 

~/.local/bin/Hermes

. Các tài khoản dịch vụ hệ thống thường có PATH tối thiểu không bao gồm 

~/.local/bin

. Hoặc thêm nó vào môi trường của người dùng hoặc liên kết tượng trưng trình khởi chạy vào một vị trí hệ thống:

`bash

   # Option A — add to the service user's profile
   echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

# Option B — symlink system-wide (run as an admin)
   sudo ln -s /home/Hermes/.Hermes/Hermes-agent/venv/bin/Hermes /usr/local/bin/Hermes

4. **Xác minh:** 
`Hermes doctor
` bây giờ sẽ chạy sạch. Nếu bạn nhận được 
`ModuleNotFoundError: No module named 'dotenv'

, bạn đang gọi tệp 
`Hermes
` nguồn repo (

~/.Hermes/Hermes-agent/Hermes

) bằng Python hệ thống thay vì trình khởi chạy venv (

~/.Hermes/Hermes-agent/venv/bin/Hermes

) — sửa bước 3.

Mẫu tương tự hoạt động trên Arch (trình cài đặt sử dụng pacman với cùng logic phát hiện sudo), Fedora/RHEL và openSUSE — những bản phân phối đó hoàn toàn không hỗ trợ 

--with-deps

, vì vậy quản trị viên luôn cài đặt riêng các thư viện hệ thống. Các lệnh 
`dnf

/
`zypper
` có liên quan được trình cài đặt in ra.

---

## Khắc phục sự cố

| Vấn đề | Giải pháp |
|----------|----------|
| 
`Hermes: command not found
` | Tải lại shell của bạn (
`source ~/.bashrc

) hoặc kiểm tra PATH |
| 
`API key not set
` | Chạy 
`Hermes model
` để định cấu hình nhà cung cấp của bạn hoặc 
`Hermes config set OpenRouter_API_KEY your_key
` |
| Thiếu cấu hình sau khi cập nhật | Chạy 
`Hermes config check
` rồi 
`Hermes config migrate
` |

Để biết thêm chẩn đoán, hãy chạy 
`Hermes doctor

 - nó sẽ cho bạn biết chính xác những gì còn thiếu và cách khắc phục.

## Tự động phát hiện phương thức cài đặt

Hermes tự động phát hiện xem nó đã được cài đặt qua 
`pip

, trình cài đặt git, Homebrew hay NixOS và 
`Hermes update
` in lệnh cập nhật phù hợp cho đường dẫn đó. Không có biến env nào để đặt — việc phát hiện dựa trên bố cục cài đặt (gói trang web Python, 

~/.Hermes/Hermes-agent/

, tiền tố Homebrew hoặc đường dẫn cửa hàng Nix). 
`Hermes doctor
` cũng hiển thị phương pháp được phát hiện trong bản tóm tắt môi trường của nó.