Hướng dẫn cài đặt Hermes Agent: Thiết lập toàn diện từ ứng dụng desktop đến dòng lệnh

Khung tác tử trí tuệ nhân tạo nguồn mở (open-source AI agent framework) Hermes Agent do Nous Research phát triển cho phép người dùng triển khai và khởi chạy hoàn chỉnh trên môi trường máy tính cá nhân hoặc máy chủ chỉ trong chưa đầy hai phút. Nền tảng hỗ trợ đa dạng phương thức phân phối từ các gói ứng dụng Hermes Desktop có giao diện đồ họa trực quan đến cài đặt dòng lệnh trực tiếp thông qua curl hoặc PowerShell.

Quy trình cài đặt nhanh (Quick Install)

1. Gói ứng dụng Desktop trên macOS và Windows

Người dùng có thể tải trực tiếp gói cài đặt tương ứng với nền tảng hệ điều hành từ trang chủ của Hermes:

• Windows: Mở tệp tải về có đuôi .appinstaller bằng công cụ Windows App Installer. Thao tác này sẽ tự động cài đặt gói MSIX bundle đã được ký số hợp lệ và ghi nhận nguồn cập nhật của gói. Các gói phân phối qua Microsoft Store sẽ có quyền quản lý và sở hữu riêng biệt theo cơ chế của Store.
• macOS: Mở tệp DMG, sau đó kéo biểu tượng Hermes.app vào thư mục Applications. Tệp nén ZIP tải về chứa bản dựng ứng dụng đã ký số chuẩn mực được sử dụng bởi hệ thống tự động cập nhật (automatic updater).

Các gói cài đặt đóng gói sẵn (bundled packages) đã tích hợp đầy đủ nhân tác tử (agent core), môi trường Python, toàn bộ các phụ thuộc tương thích và giao diện dựng sẵn. Lần khởi chạy đầu tiên sẽ không phải biên dịch lại môi trường thực thi gốc này. Tuy nhiên, việc truy cập các nhà cung cấp mô hình (provider access) và các gói tích hợp bổ sung vẫn yêu cầu kết nối mạng Internet.

Trình cài đặt khởi tạo Hermes-Setup hoạt động theo cơ chế khác biệt: công cụ sẽ tải toàn bộ mã nguồn về và tiến hành biên dịch ứng dụng desktop cục bộ. Biến thể Light là bản dựng chỉ chạy kết nối từ xa (remote-only), không phải là môi trường đóng gói cục bộ độc lập.

2. Cài đặt môi trường dòng lệnh (không kèm Hermes Desktop)

Đối với nhu cầu triển khai tối giản chỉ sử dụng giao diện dòng lệnh (CLI-only) mà không cần giao diện đồ họa Hermes Desktop, người dùng thực thi các lệnh tương ứng dưới đây:

Trên Linux / macOS / WSL2

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Trên Windows (môi trường PowerShell gốc)

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

Nếu muốn bổ sung và kích hoạt giao diện Hermes Desktop sau khi đã hoàn tất cài đặt bản dòng lệnh, chỉ cần thực thi lệnh sau:

hermes desktop

3. Cài đặt trên Android / Termux

Trên các thiết bị Android kiến trúc aarch64, sử dụng gói Termux APT. Hãy cấu hình kho lưu trữ đã ký số của Hermes trước khi thực thi lệnh cài đặt pkg install hermes-agent. Cần lưu ý rằng các tập lệnh cài đặt desktop/máy chủ thông thường không tương thích với quy trình cài đặt trong môi trường Termux.

Cơ chế hoạt động của trình cài đặt mã nguồn

Khi thực thi tập lệnh cài đặt từ nguồn, hệ thống sẽ tự động sao chép mã nguồn (clone source), khởi tạo công cụ quản lý gói siêu tốc uv, và ủy quyền chuẩn bị phụ thuộc cho trình quản lý gói PM (Package Manager) của Hermes. PM chịu trách nhiệm cung cấp các phiên bản cố định (pinned) của Python, Node.js, npm, ripgrep và FFmpeg. Quá trình cài đặt nguồn sẽ tự động chọn gói phụ thuộc mở rộng all của Python.

PM cũng mặc định tích hợp sẵn các công cụ trình duyệt (browser tools) và tác vụ điều khiển máy tính (computer-use tools):

• agent-browser: Đi kèm phiên bản trình duyệt Chromium cố định được kiểm thử tương thích cao.
• cua-driver: Trình điều khiển thao tác máy tính (computer-use driver) vận hành trên macOS, Windows và Linux nền glibc.

Nếu quá trình tải các công cụ trên gặp sự cố mạng, việc cài đặt chính vẫn sẽ hoàn tất và hiển thị câu lệnh để thử lại sau. Trình điều khiển trình duyệt mặc định (browser-harness, động cơ lõi của Browser Use CLI) là một phụ thuộc Python tiêu chuẩn, do đó mọi bản cài đặt bao gồm cả ứng dụng Desktop đều đã tích hợp sẵn.

Để lược bỏ các công cụ trình duyệt, hãy truyền thêm cờ --skip-browser trên hệ thống POSIX hoặc -SkipBrowser trên Windows; đối với driver điều khiển máy tính, sử dụng cờ --skip-computer-use hoặc -SkipComputerUse. Hermes Agent sẽ tự động lưu lại những lựa chọn này: các lần cập nhật tiếp theo bằng lệnh hermes update sẽ không tự động cài lại các thành phần đã bỏ qua. Khi cần kích hoạt lại, chỉ cần chạy:

hermes pm install agent-browser
# hoặc
hermes pm install cua-driver

Tập lệnh sẽ thiết lập trình khởi chạy (launcher) và chuẩn bị cấu trúc thư mục dữ liệu người dùng. Các phiên chạy tương tác sẽ tự động kích hoạt trình hướng dẫn thiết lập ban đầu (setup wizard) và cấu hình cổng tin nhắn (messaging gateway). Người dùng có thể truyền cờ --non-interactive trên POSIX hoặc -NonInteractive trên Windows để bỏ qua các bước yêu cầu nhập liệu. Tùy chọn --include-desktop hoặc -IncludeDesktop cho phép tự động biên dịch Hermes Desktop trực tiếp từ mã nguồn.

Trên cửa sổ terminal, tập lệnh hiển thị trạng thái từng bước và ghi toàn bộ dữ liệu nhật ký của git, uv cùng quá trình biên dịch vào tệp logs/install.log trong thư mục dữ liệu của Hermes. Nếu một bước thất bại, hệ thống sẽ in trực tiếp các dòng lỗi cuối cùng kèm đường dẫn tệp log. Trong môi trường CI (khi biến CI hoặc GITHUB_ACTIONS được kích hoạt), hoặc khi kích hoạt cờ --verbose / -Verbose, hệ thống sẽ truyền trực tiếp toàn bộ luồng thông tin ra màn hình.

Cấu trúc thư mục triển khai (Install layout)

Biến môi trường HERMES_HOME cho phép tùy chỉnh vị trí lưu trữ dữ liệu người dùng. Tham số --dir trên tập lệnh POSIX dùng để chỉ định đường dẫn mã nguồn riêng biệt; trên Windows, người dùng có thể sử dụng các tham số -HermesHome và -InstallDir. Việc chạy tập lệnh POSIX với quyền root sẽ mặc định lưu vào thư mục home của tài khoản root trừ khi có khai báo đường dẫn nguồn cụ thể.

Kho công cụ của PM và môi trường ảo Python có vòng đời quản lý riêng biệt. Lưu ý: Tuyệt đối không xóa thư mục gốc dữ liệu (data root) để cố gắng khắc phục sự cố cài đặt ứng dụng.

Các bước thiết lập sau khi cài đặt (After Installation)

Sau khi tiến trình cài đặt hoàn tất, hãy tải lại cấu hình shell và bắt đầu phiên tương tác đầu tiên:

source ~/.bashrc   # hoặc: source ~/.zshrc
hermes             # Bắt đầu phiên trò chuyện cùng tác tử!

Để cấu hình chi tiết từng thông số sau này, người dùng có thể sử dụng các lệnh chuyên biệt:

hermes model          # Lựa chọn nhà cung cấp LLM và mô hình hoạt động
hermes tools          # Cấu hình danh sách các công cụ được phép kích hoạt
hermes gateway setup  # Thiết lập kết nối các nền tảng nhắn tin (Telegram, Discord, Slack...)
hermes config set     # Gán giá trị cho từng biến cấu hình cụ thể
hermes config get     # Kiểm tra giá trị của biến cấu hình hiện tại
hermes setup          # Chạy toàn bộ trình hướng dẫn thiết lập hệ thống từ đầu

Thiết lập nhanh nhất: Cổng dịch vụ Nous Portal

Người dùng có thể đăng ký tài khoản Nous Portal để truy cập đồng thời hơn 300 mô hình AI cùng hạ tầng Tool Gateway (tích hợp sẵn tìm kiếm web, tạo ảnh, chuyển văn bản thành giọng nói TTS và trình duyệt đám mây) mà không cần cấu hình khóa API riêng cho từng dịch vụ:

hermes setup --portal

Lệnh trên sẽ tự động đăng nhập, thiết lập Nous làm nhà cung cấp chính và kích hoạt đầy đủ Tool Gateway chỉ trong một thao tác duy nhất.

Chuyển đổi dữ liệu và di chuyển giữa các máy trạm

Nếu đã thiết lập Hermes Agent trên máy trạm khác, bạn không cần phải cấu hình lại từ đầu. Hệ thống cho phép khôi phục toàn bộ bản sao lưu thông qua lệnh hermes import, hoặc di chuyển một profile tác tử cụ thể bằng lệnh hermes profile import. Cần lưu ý rằng việc xuất profile (profile export) mặc định sẽ loại trừ các thông tin xác thực nhạy cảm (credentials) nhằm bảo mật, vì vậy bản xuất profile không thay thế cho một bản sao lưu toàn diện (backup).

Yêu cầu tiền đề hệ thống (Prerequisites)

Đối với tập lệnh cài đặt nguồn trên hệ thống POSIX, máy tính cần được cài sẵn các tiện ích Git, curl, tar và công cụ kiểm tra hàm băm SHA-256. Trên Windows, tập lệnh có khả năng tự động tải về bản lưu trữ Git for Windows cố định nếu máy chưa có Git. Tập lệnh luôn tải gói uv đã được xác thực mã băm; các phiên bản uv có sẵn trên biến môi trường PATH sẽ không được sử dụng.

Các bản phát hành chính thức của Hermes Agent hiện vận hành trên môi trường Python 3.14. Dải phiên bản >=3.11,<3.15 trong tệp pyproject.toml nhằm hỗ trợ các cài đặt Python cũ hơn chạy công cụ cập nhật trước khi PM chuyển sang Python 3.14, không cam kết hỗ trợ môi trường chạy thực tế lâu dài trên Python 3.11–3.13. PM quản lý các phiên bản công cụ cố định từ pm/lock.json và không tự ý nhận các phiên bản Node của hệ điều hành làm môi trường thực thi.

Việc biên dịch từ mã nguồn có thể yêu cầu trình biên dịch mã gốc (native compiler) cùng các thư viện phát triển hệ thống. Bản phân phối Chromium trên Linux cũng đòi hỏi các thư viện hệ thống tương ứng.

Trên các bản phân phối Linux sử dụng thư viện glibc, môi trường Node.js do PM quản lý liên kết với thư viện libatomic.so.1, vốn thường bị lược bỏ trong các image tối giản của Debian, Ubuntu và dòng RHEL. Khi thiếu thư viện này, trình cài đặt và lệnh hermes update sẽ tự động gọi trình quản lý gói của hệ điều hành (libatomic1 trên apt và zypper, libatomic trên dnf/yum và apk, gcc-libs trên pacman). Trong phiên tương tác, hệ thống sẽ yêu cầu nhập mật khẩu sudo một lần trước khi cài đặt phụ thuộc; các phiên chạy kèm cờ --non-interactive sẽ không hỏi mật khẩu.

Cài đặt thủ công dành cho lập trình viên (Developer Installation)

Đối với các lập trình viên muốn can thiệp trực tiếp vào mã nguồn và phát triển tính năng, hãy bắt đầu với quy trình làm việc PM developer workflow. Tài liệu này cung cấp hướng dẫn chi tiết về kích hoạt môi trường làm việc, các câu lệnh quản trị thường nhật, làm mới cây phụ thuộc và xử lý các giới hạn khởi tạo.

Cài đặt dưới tài khoản dịch vụ hệ thống (Non-Sudo / Service User)

Khi triển khai Hermes Agent dưới dạng một tiến trình dịch vụ chạy nền (daemon/system service), hãy thực thi tập lệnh cài đặt nguồn trực tiếp dưới danh tính của tài khoản dịch vụ đó. Toàn bộ thư mục home, kho công cụ, cấu hình và trình khởi chạy phải thuộc quyền sở hữu của người dùng dịch vụ:

1. Với tư cách quản trị viên hệ thống (root/sudo), cài đặt các phụ thuộc biên dịch nguồn và toàn bộ thư viện Linux cần thiết cho backend trình duyệt.
2. Chuyển sang tài khoản dịch vụ và thực thi tập lệnh cài đặt tiêu chuẩn:

   curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

3. Thêm thư mục chứa launcher vào biến môi trường shell của tài khoản dịch vụ:

   export PATH="$HOME/.local/bin:$PATH"

4. Thực thi lệnh hermes doctor từ tài khoản dịch vụ để kiểm tra tính toàn vẹn hệ thống (sử dụng launcher đã cài đặt, không gọi trực tiếp đường dẫn cố định venv/bin/hermes).
5. Đối với các dịch vụ người dùng trên Linux cần tiếp tục hoạt động liên tục sau khi tài khoản đăng xuất, quản trị viên cần kích hoạt tính năng duy trì phiên (lingering):

   sudo loginctl enable-linger SERVICE_USER

Tập lệnh cài đặt nguồn hiện tại không tự động chạy bước --with-deps của Playwright và không tự ý cài đặt các gói cấp hệ thống (ngoại trừ libatomic). PM chịu trách nhiệm quản lý các tệp nhị phân công cụ, trong khi quản trị viên hệ thống có trách nhiệm cấu hình đầy đủ các thư viện nền tảng.

Xử lý các sự cố thường gặp (Troubleshooting)

Để thực hiện chẩn đoán chuyên sâu toàn diện cho toàn bộ hệ thống, hãy thực thi lệnh hermes doctor. Công cụ này sẽ quét toàn bộ môi trường, phát hiện chính xác các thành phần còn thiếu hoặc cấu hình sai lệch và cung cấp giải pháp khắc phục cụ thể.

Quản lý liên kết tượng trưng và ổ đĩa lưu trữ ngoài

Hermes hỗ trợ đầy đủ việc đặt liên kết tượng trưng (symlink) cho biến HERMES_HOME cũng như các thư mục con bên trong, bao gồm hooks, skills, sessions và logs. Trong quá trình khởi tạo môi trường, các liên kết thư mục hiện hữu luôn được bảo toàn nguyên vẹn.

Nếu đối tượng liên kết bị thiếu, không thể truy cập hoặc không phải là một thư mục hợp lệ, quá trình khởi tạo sẽ dừng lại và thông báo lỗi lưu trữ chi tiết. Hermes Agent tuyệt đối không tự ý thay thế liên kết hay tự tạo thư mục đích bị thiếu, nhằm ngăn chặn nguy cơ ghi đè dữ liệu cục bộ khi ổ đĩa ngoài hoặc phân vùng mạng NAS chưa được gắn kết (unmounted). Lệnh hermes doctor sẽ báo cáo sự cố này dưới dạng lỗi lưu trữ phần cứng thay vì lỗi cú pháp YAML; người dùng nên giữ nguyên tệp config.yaml thay vì chạy lại lệnh hermes setup.

Cơ chế tự động nhận diện phương thức cài đặt

Hệ thống quản lý và cập nhật của Hermes phụ thuộc trực tiếp vào phương thức cài đặt ban đầu của ứng dụng: các bản cài từ mã nguồn sẽ sử dụng tiến trình cập nhật Git tự động; trong khi các gói ứng dụng Desktop, Docker, Nix và Termux sẽ duy trì cơ chế cập nhật thông qua trình quản lý gói tương ứng của nền tảng đó. Người dùng có thể sử dụng lệnh hermes doctor để xác minh nguồn gốc xuất xứ của bản cài đặt hiện tại.

Nguồn: Hermes Agent Documentation (Nous Research)

LIÊN HỆ TƯ VẤN CÁC DỊCH VỤ AI

Hỗ trợ tư vấn, đào tạo và chuyển giao AI cho cá nhân, doanh nghiệp và tổ chức.

📞 Điện thoại: 0981243678 Liên hệ qua Zalo