Cài Hermes Agent trên Windows, Ubuntu và macOS: hướng dẫn từng bước

Bạn hoàn toàn có thể cài Hermes Agent trên Windows, macOS lẫn Linux — đây đều là các nền tảng được hỗ trợ chính thức ở mức cao nhất (Tier 1), gồm macOS chip Apple Silicon, Windows 10/11, Linux/WSL2 và Docker. Với người ngại gõ lệnh, cách nhẹ nhàng nhất là dùng app Desktop; với người muốn agent chạy liên tục trên máy chủ thì cài bằng một dòng lệnh trên VPS Ubuntu. Bài này tôi đi từng bước: chọn cách cài phù hợp, chạy lệnh, cấu hình lần đầu, chat thử câu đầu tiên và xử lý các lỗi hay gặp.

Nếu bạn chưa rõ Hermes Agent là gì và nó khác chatbot thường ở điểm nào, nên đọc trước bài Hermes Agent là gì? Agent AI tự học của Nous Research cho người mới rồi quay lại đây để cài.

Chọn cách cài Hermes Agent nào hợp với bạn?

Có 4 cách cài, chọn theo thiết bị bạn đang có và mức độ quen gõ lệnh. Bảng dưới đây là bản tóm tắt để bạn quyết định trong một phút:

Cách cài	Chạy trên	Hợp với ai	Lưu ý
App Desktop	Windows, macOS	Người không muốn gõ lệnh	Dễ nhất; bộ cài Hermes-Setup.dmg chỉ dành cho Mac Apple Silicon
CLI một dòng lệnh	Linux, macOS, WSL2	Người có VPS hoặc đã quen terminal	Cài nhanh, dễ xử lý sự cố nhất
PowerShell (Windows native)	Windows 10/11	Người dùng Windows không muốn cài WSL	Không cần quyền admin
Docker	Máy chủ	Người quản trị hệ thống	Cập nhật bằng image mới, không dùng hermes update

Hai điểm dễ vấp mà bạn nên biết trước khi bắt tay:

• Không cài qua pip hay brew. Tài liệu chính thức nói rõ các cách pip install hermes-agent, uv tool install hermes-agent, brew install hermes-agent đều không được hỗ trợ. Thấy ai hướng dẫn kiểu đó thì bỏ qua.
• Mac chip Intel không chạy được bộ cài .dmg. Tài liệu ghi "The macOS installer is Apple Silicon only". Nếu máy bạn là MacBook đời Intel, hãy dùng bản darwin-x64 hoặc cài CLI trước rồi mở app Desktop sau.

Chi tiết nền tảng hỗ trợ bạn có thể đối chiếu tại trang Platform Support của Hermes Agent. Tôi kiểm các dữ kiện trong bài ngày 04/10/2026 — dự án này thay đổi khá nhanh nên trước khi cài bạn nên liếc lại trang chính thức một lượt.

Hermes Agent install Windows: Desktop, PowerShell hay WSL2?

Trên Windows có ba đường đi, và với đa số người dùng văn phòng tôi khuyên chọn PowerShell native hoặc app Desktop. Lý do: cả hai đều không bắt bạn cài thêm hệ điều hành phụ.

Cách 1 — PowerShell native. Mở PowerShell và chạy lệnh cài:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Ưu điểm lớn nhất, theo đúng mô tả trong tài liệu: "No admin rights required. The installer goes to %LOCALAPPDATA%\hermes\ and adds hermes to your User PATH". Nghĩa là nhân viên dùng máy công ty bị khoá quyền admin vẫn cài được. Sau khi cài xong, hãy đóng cửa sổ terminal cũ và mở một cửa sổ mới, vì PATH chỉ được nạp lại khi mở phiên mới — đây là nguyên nhân số một khiến người mới tưởng cài hỏng.

Cách 2 — gói MSIX / App Installer. Tài liệu ghi "The MSIX package requires Windows 11 22H2 or later". Máy Windows 10 thì bỏ qua cách này.

Cách 3 — WSL2. Chỉ nên chọn khi bạn đã quen Linux hoặc công việc cần môi trường POSIX (chạy script bash, công cụ dòng lệnh Linux). Với người chưa từng dùng Linux, WSL2 thêm một lớp phức tạp không cần thiết.

Phần mềm diệt virus báo uv.exe có virus thì sao?

Đó là báo nhầm. Kho mã nguồn của dự án gọi đúng tên hiện tượng này là false positive: một số phần mềm diệt virus cách ly file uv.exe dù file này an toàn. Hướng xử lý được khuyến nghị là thêm ngoại lệ cho cả thư mục cài đặt, không phải cho mã băm (hash) của riêng file — vì mỗi lần cập nhật, mã băm đổi và bạn lại phải khai báo lại từ đầu. Nếu máy do phòng IT quản lý, bạn gửi yêu cầu whitelist thư mục cho IT thay vì tự tắt phần mềm diệt virus.

Hermes Agent install Ubuntu: cài bằng một dòng lệnh

Trên Ubuntu (và cả macOS, WSL2), toàn bộ việc cài gói gọn trong một lệnh. Các bước theo thứ tự:

1. Chuẩn bị sẵn Git, curl và tar trên máy. Trên một VPS Ubuntu mới tinh, ba thứ này đôi khi chưa có đủ.
2. Chạy lệnh cài: curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
3. Nạp lại shell: source ~/.bashrc (nếu bạn dùng zsh, chẳng hạn trên macOS, thì dùng source ~/.zshrc).
4. Gõ hermes để khởi động lần đầu.

Hai quy tắc cần nhớ để khỏi phải cài lại:

• Đừng dùng sudo với bộ cài. Mục FAQ của dự án ghi thẳng: "Don't use sudo with the installer — it installs to ~/.local/bin". Chạy bằng sudo sẽ đẩy file vào thư mục của user root, còn tài khoản thường của bạn thì không thấy lệnh hermes đâu cả.
• Cài cho user nào thì đăng nhập bằng chính user đó. Nếu bạn định cho agent chạy dưới một user dịch vụ riêng trên VPS, hãy chuyển sang user đó rồi mới chạy bộ cài.

Về chuyện chạy agent trên máy chủ: tôi không cài trên laptop mà cài trên một VPS Linux, vì các trợ lý của tôi cần chạy liên tục kể cả khi tôi đã tắt máy. Laptop thì ngủ, mất mạng, hết pin — còn VPS thì không. Nếu bạn cũng định đi đường này, nên đọc thêm bài Chạy AI agent an toàn trong doanh nghiệp: sandbox, phân quyền và VPS trước khi giao cho agent quyền đụng vào dữ liệu thật.

Hermes Agent desktop app: khi nào nên dùng?

App Desktop hợp với người thấy màn hình đen của terminal là thấy ngại. Hiện có bản cho macOS và Windows, và điểm hay nhất là nó dùng chung cấu hình, khoá API, phiên làm việc, skill và bộ nhớ với bản CLI — tức là bạn không phải cài đặt hai lần, cũng không sợ hai bên lệch dữ liệu.

Nếu bạn đã cài CLI theo hướng dẫn ở trên rồi, chỉ cần gõ:

hermes desktop

Theo kinh nghiệm của tôi khi hướng dẫn nhân viên văn phòng: cứ cài CLI trước, rồi mở app Desktop để dùng hằng ngày. Lý do là khi có sự cố, mọi hướng dẫn xử lý trong tài liệu đều viết theo dòng lệnh. Biết mở terminal và gõ vài lệnh kiểm tra sẽ giúp bạn tự gỡ rối thay vì ngồi đợi người khác.

Cấu hình lần đầu: hermes setup, hermes model và câu chat đầu tiên

Cài xong chưa dùng được ngay — bạn cần khai báo nhà cung cấp mô hình và khoá API. Trình tự tôi hay làm:

1. Chạy hermes setup để đi qua trình hướng dẫn cấu hình đầy đủ.
2. Chạy hermes model để chọn nhà cung cấp và mô hình.
3. Chọn mô hình có cửa sổ ngữ cảnh tối thiểu 64.000 token — tài liệu Quickstart ghi rõ mức "64,000 tokens". Mô hình ngữ cảnh nhỏ hơn sẽ hụt hơi khi agent phải đọc file và nhớ nhiều bước.

Câu chat thử đầu tiên nên là một việc thật, nhỏ, có thể kiểm chứng bằng mắt. Ví dụ tôi hay dùng với các cửa hàng và công ty thương mại: chuẩn bị file don-hang-tuan.csv gồm các cột ma_don, ngay, khach_hang, tong_tien, trang_thai, rồi gõ:

Đọc file don-hang-tuan.csv (cột ma_don, ngay, khach_hang, tong_tien, trang_thai) và cho biết 3 khách mua nhiều nhất.

Một yêu cầu như vậy kiểm tra được cả ba thứ cùng lúc: agent có đọc được file trên máy không, mô hình có trả lời đúng không, và bạn có tự đối chiếu kết quả với file gốc được không. Đừng bắt đầu bằng việc giao cho nó sửa dữ liệu thật.

Dữ liệu cấu hình của Hermes Agent nằm trong thư mục ~/.hermes/, gồm các thành phần như config.yaml, .env, SOUL.md, memories/ và skills/. Cấu trúc này có thể đổi theo phiên bản, nên nếu bạn đọc bài này sau thời điểm 04/10/2026 thì hãy mở tài liệu chính thức để đối chiếu.

Thói quen tôi giữ từ ngày đầu và khuyên bạn làm theo: trước mỗi lần vá config.yaml, sao lưu bản cũ lại. Có lần tôi sửa sai, loay hoay mãi không ra, cuối cùng chỉ cần chép lại bản cũ là chạy bình thường.

Kiểm tra sức khoẻ bằng hermes doctor

Khi nghi ngờ có gì đó chưa đúng, lệnh đầu tiên nên chạy là:

hermes doctor

Lệnh này rà soát môi trường, báo bạn đang thiếu gì và gợi ý cách sửa. Muốn để nó tự thử sửa, thêm tuỳ chọn --fix. Tôi thường chạy bản không có --fix trước để đọc xem nó định đụng vào cái gì, rồi mới cho sửa.

Lỗi hay gặp khi cài Hermes Agent và cách xử lý

Phần lớn sự cố khi cài đặt rơi vào sáu tình huống dưới đây, và đều có cách xử lý trong vài phút:

Triệu chứng	Nguyên nhân thường gặp	Cách xử lý
hermes: command not found	Shell chưa nạp lại PATH	Chạy source ~/.bashrc (hoặc source ~/.zshrc), hoặc mở terminal mới rồi kiểm tra PATH
API key not set	Chưa khai báo nhà cung cấp mô hình	Chạy hermes model
Thiếu cấu hình sau khi cập nhật	File cấu hình cũ chưa khớp phiên bản mới	Chạy hermes config check rồi hermes config migrate
Antivirus cách ly uv.exe	Báo nhầm (false positive)	Thêm ngoại lệ cho thư mục, không phải cho mã băm file
Dán lệnh vào VPS bị lỗi ký tự : hoặc @	Console web của nhà cung cấp VPS đổi bố cục bàn phím	Kết nối bằng SSH rồi dán lệnh
Từng lỡ cài bằng sudo	File nằm sai thư mục user	Dọn sạch bản cũ rồi cài lại, lần này không dùng sudo

Riêng tình huống thứ năm hay làm người mới hoảng: bạn dán đúng lệnh mà terminal báo URL sai. Lý do là console web dạng VNC của nhiều nhà cung cấp VPS xử lý ký tự đặc biệt không chuẩn. Cứ mở SSH từ máy của bạn rồi dán lại, lệnh sẽ chạy đúng.

Cập nhật và sao lưu trước khi cập nhật

Luôn sao lưu trước, cập nhật sau. Lệnh sao lưu:

hermes backup

Lệnh này tạo một file zip chứa cấu hình, skill, phiên làm việc và dữ liệu — tức là thứ bạn cần để quay về trạng thái cũ nếu bản mới có vấn đề.

Sau khi đã có bản sao lưu:

• Bản cài từ mã nguồn: chạy hermes update.
• Bản chạy Docker: không dùng hermes update. Tài liệu ghi rõ "Docker installs do not support hermes update. Updating is done by running a new image" — bạn cập nhật bằng cách chạy image mới.

Với doanh nghiệp, tôi khuyên đặt lịch cố định cho việc này, ví dụ chiều thứ Sáu hàng tuần: sao lưu, cập nhật, chạy hermes doctor, chat thử một câu quen thuộc để chắc chắn mọi thứ còn hoạt động. Mười phút đó tiết kiệm cho bạn cả buổi sáng thứ Hai.

Tóm lại và bước tiếp theo

Ba ý cần nhớ khi cài Hermes Agent:

1. Chọn đúng đường cài theo thiết bị: Windows dùng PowerShell native hoặc app Desktop; Linux và macOS dùng lệnh cài một dòng; máy chủ dùng Docker. Đừng cài qua pip hay brew.
2. Không dùng sudo, không cần quyền admin — và luôn mở terminal mới (hoặc source ~/.bashrc) sau khi cài xong.
3. Sao lưu trước mỗi lần sửa cấu hình hoặc cập nhật bằng hermes backup, và dùng hermes doctor làm lệnh kiểm tra đầu tiên khi nghi có trục trặc.

Việc nên làm ngay hôm nay: chọn một máy (laptop của bạn hoặc một VPS nhỏ), cài theo đúng cách tương ứng ở trên, chạy hermes setup và hermes model, rồi thử câu chat đầu tiên với một file CSV thật nhưng không quan trọng. Khi đã chạy được câu đầu tiên, hãy đọc tiếp Hermes Agent là gì? để hiểu cách agent ghi nhớ và tự học, và Chạy AI agent an toàn trong doanh nghiệp để đặt rào chắn trước khi cho agent chạm vào dữ liệu công ty.

Mọi lệnh trong bài tôi lấy nguyên văn từ tài liệu chính thức, kiểm lại ngày 04/10/2026 tại trang hướng dẫn cài đặt Hermes Agent và kho mã nguồn NousResearch/hermes-agent. Dự án thay đổi nhanh, nên nếu lệnh nào không chạy, bạn hãy mở hai nguồn này đối chiếu trước khi tìm giải pháp ở nơi khác.