Cài đặt Hermes và cấu hình OmniProxy

Hermes là một trợ lý có thể lưu lại cuộc trò chuyện và kinh nghiệm xử lý tác vụ; những việc đã làm có thể được sắp xếp thành kỹ năng để tiếp tục sử dụng về sau. Trợ lý này cũng có thể kết nối với Telegram, Discord, Slack, WhatsApp, Signal và terminal thông qua cùng một Gateway; có thể hiểu Gateway là cổng tiếp nhận và chuyển tiếp tin nhắn thống nhất. Bạn có thể giao cho Hermes việc đánh giá mã, ghi chép sự cố hoặc xử lý tài liệu khách hàng từ công cụ trò chuyện quen thuộc, sau đó để trợ lý quay lại repository và tiếp tục công việc.

Chuẩn bị trước khi cài đặt

Trước tiên, hãy chọn phương thức cài đặt theo hệ điều hành của máy tính. macOS và Windows có thể dùng trực tiếp gói cài đặt có giao diện cửa sổ; Linux, macOS và WSL2 có thể dùng script trong terminal. WSL2 là tính năng chạy môi trường Linux trong Windows. Termux trên điện thoại Android và Docker cũng có cách cài đặt riêng, nhưng bài này chỉ giới thiệu cách cài trên máy tính thông thường.

Muốn có cửa sổ

macOS, Windows

• macOS: mở DMG
• Windows: mở gói cài đặt
• Đưa ứng dụng vào hệ thống

Chỉ cần terminal

Linux, macOS, WSL2

• Một lệnh install.sh
• Trên Windows, dùng install.ps1
• Sau khi cài, nhập hermes

Tạm thời không dùng

pip, brew, AUR

• Các cách cài này không được hỗ trợ chính thức
• Sau khi cài cũng khó cập nhật
• Hãy dùng một trong hai cách bên trái

Trước khi bắt đầu, hãy chuẩn bị một máy tính macOS, Windows hoặc Linux và xác nhận máy có thể mở terminal cũng như truy cập GitHub. Nếu định cài đặt trên ổ cứng di động, bạn cũng cần kết nối ổ đĩa trước và xác nhận ổ có đủ dung lượng.

Cài đặt và khởi chạy lần đầu

Nếu bạn muốn có giao diện cửa sổ

Truy cập khu vực tải xuống trên trang web Hermes, sau đó tải gói cài đặt tương ứng với hệ điều hành. Gói cài đặt đã bao gồm môi trường chạy nên trong lần mở đầu tiên, bạn không cần biên dịch trực tiếp trên máy tính.

• macOS: Mở DMG và đưa Hermes.app vào thư mục Applications. DMG là định dạng ảnh đĩa cài đặt thường dùng trên macOS. Gói cài đặt này chỉ hỗ trợ chip Apple; Intel Mac không thuộc phạm vi hỗ trợ.
• Windows: Dùng trình cài đặt ứng dụng của Windows để mở tệp .appinstaller. Tệp này cài một gói MSIX đã được ký; MSIX là một loại gói cài đặt ứng dụng dùng trên Windows.
• Linux: Gói cài đặt dành cho máy tính để bàn chỉ có trên macOS và Windows. Với Linux, hãy dùng lệnh terminal bên dưới; sau khi cài xong, bạn có thể chạy hermes desktop.

Nếu bạn chỉ cần terminal

Nếu dùng Linux, macOS hoặc WSL2, hãy chạy trong terminal:

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

Nếu dùng PowerShell tích hợp sẵn trong Windows, hãy chạy:

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

Trình cài đặt sẽ tải mã của Hermes và các chương trình cần thiết để chạy. Nếu quá trình tải xuống bị gián đoạn giữa chừng, chỉ cần chạy lại đúng lệnh đó. Sau khi cài đặt hoàn tất, hãy đóng terminal hiện tại, mở một cửa sổ mới rồi nhập:

hermes

Nếu thấy lời nhắc của Hermes, điều đó có nghĩa là lệnh đã sẵn sàng để sử dụng. Tiếp theo, bạn có thể chạy hermes doctor; đây là công cụ kiểm tra cài đặt và sẽ cho biết hệ thống hiện còn thiếu thành phần nào.

Đặt chương trình trên ổ cứng di động

Ngày 9 tháng 10 năm 2026, Hermes Agent v0.21.6 đã được cài đặt trên ổ cứng di động của một máy Mac. Chương trình nằm tại /Volumes/AItools/tools/hermes-agent, lệnh khởi chạy nằm tại ~/.local/bin/hermes, còn cấu hình và cuộc trò chuyện vẫn được lưu trong ~/.hermes.

Nếu ổ đĩa của bạn có tên khác, hãy thay đường dẫn sau --dir bằng thư mục của riêng bạn. Ổ đĩa này phải luôn được kết nối khi chạy Hermes.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o install.sh
bash install.sh --dir /Volumes/AItools/tools/hermes-agent --non-interactive

Chương trình

Ổ cứng di động

• tools/hermes-agent
• Mã nguồn nằm ở đây

Lệnh

~/.local/bin/hermes

• Nhập hermes trong terminal
• Có hiệu lực sau khi mở cửa sổ mới

Cấu hình và cuộc trò chuyện

~/.hermes

• config.yaml nằm ở đây
• Thoát trước khi tháo ổ cứng

Lấy thông số kết nối từ OmniProxy

Trong hướng dẫn này, Hermes kết nối với OmniProxy chứ không kết nối trực tiếp với Grok hoặc Gemini. Địa chỉ dịch vụ của Grok và Gemini được cấu hình trong OmniProxy; không nhập trực tiếp các địa chỉ đó vào Hermes.

Máy tính của bạn

Hermes

→

Gateway cục bộ

OmniProxy

• Địa chỉ kết thúc bằng /v1

→

Grok

• grok-4.7

Gemini

• gemini-3.8-flash

Model ID là tên chính xác mà giao diện API dùng để nhận diện mô hình. Hai mô hình lần lượt sử dụng các tên sau:

• Với Grok, nhập grok-4.7. Giao diện API của xAI là https://api.x.ai/v1, còn yêu cầu trò chuyện đi qua /v1/chat/completions. Xem tài liệu về mô hình Grok.
• Với Gemini, nhập gemini-3.8-flash. Giao diện tương thích OpenAI của Google là https://generativelanguage.googleapis.com/v1beta/openai/. Xem hướng dẫn tương thích OpenAI của Gemini.

Nếu muốn chuyển sang Gemini trong Hermes, bạn chỉ cần đổi tên mô hình thành gemini-3.8-flash; địa chỉ giao diện vẫn là địa chỉ của OmniProxy.

Sao chép địa chỉ giao diện và khóa từ OmniProxy, sau đó nhập Model ID tương ứng:

Base URL: https://your-omniproxy-origin.example/v1
API Key:  <YOUR_OMNIPROXY_API_KEY>
Model ID: grok-4.7

Base URL là địa chỉ giao diện mà Hermes dùng để gửi yêu cầu; tại đây, địa chỉ phải kết thúc bằng /v1. API Key là khóa do OmniProxy cấp cho Hermes. Hãy thay bằng nội dung của riêng bạn và không đăng khóa lên trang công khai.

Nếu OmniProxy trên máy cục bộ không yêu cầu khóa, bạn có thể để trống API Key; nếu người khác có thể truy cập địa chỉ này, bạn nên thiết lập khóa. Đồng thời, hãy xác nhận rằng địa chỉ đó có thể được truy cập từ môi trường nơi Hermes đang chạy. Khi Hermes và OmniProxy cùng chạy trên một máy tính, bạn có thể dùng địa chỉ cục bộ.

Nhập cấu hình công cụ

Trước tiên, hãy thoát khỏi cuộc trò chuyện đang diễn ra, sau đó chạy trong terminal:

hermes model

Chọn Custom endpoint (self-hosted / VLLM / etc.). Custom endpoint là điểm cuối tùy chỉnh, nghĩa là Hermes sẽ kết nối với địa chỉ dịch vụ do bạn chỉ định thay vì dùng nhà cung cấp được thiết lập sẵn.

Trình hướng dẫn sẽ lần lượt hỏi địa chỉ giao diện, khóa và tên mô hình. Hãy nhập ba giá trị từ phần trước. Nếu muốn dùng Gemini, hãy nhập gemini-3.8-flash làm tên mô hình.

Bạn cũng có thể chỉnh sửa trực tiếp ~/.hermes/config.yaml. YAML là định dạng văn bản dùng thụt lề để thể hiện quan hệ cấu hình. Dưới đây là cấu hình cho Grok:

model:
  default: grok-4.7
  provider: custom
  base_url: https://your-omniproxy-origin.example/v1
  api_key: <YOUR_OMNIPROXY_API_KEY>

Khi dùng Gemini, hãy đổi default thành gemini-3.8-flash; ba mục còn lại giữ nguyên:

model:
  default: gemini-3.8-flash
  provider: custom
  base_url: https://your-omniproxy-origin.example/v1
  api_key: <YOUR_OMNIPROXY_API_KEY>

Sau khi lưu, hãy chạy lại hermes rồi bắt đầu trò chuyện. Trong một phiên đã mở, /model chỉ có thể chuyển đổi giữa các nguồn đã được lưu, không thể dùng để thêm cấu hình này.

Xác minh bằng một tác vụ thực tế

1

hermes doctor

• Kiểm tra cài đặt đã đạt

2

Gửi một câu ngắn

• Thấy phản hồi của Hermes

3

Mở nhật ký lệnh gọi

• Kiểm tra tên mô hình

1. Chạy hermes doctor để kiểm tra quá trình cài đặt có đầy đủ hay không.
2. Chạy hermes, sau đó yêu cầu trợ lý mô tả bằng một câu về những gì mình có thể làm. Bạn sẽ thấy một đoạn phản hồi.
3. Mở nhật ký lệnh gọi của OmniProxy, xác nhận yêu cầu này đến từ Hermes và kiểm tra xem tên mô hình có phải là grok-4.7 hoặc gemini-3.8-flash hay không.

Việc chỉ thấy trình hướng dẫn báo lưu thành công hoặc giao diện API trả về thành công vẫn chưa đủ để chứng minh Hermes đã có thể hoàn thành tác vụ cho bạn. Tên mô hình trong nhật ký lệnh gọi phải trùng khớp với nội dung đã nhập.

Nếu muốn trò chuyện trong trình duyệt, bạn có thể chạy lệnh sau trên máy cục bộ:

hermes dashboard --no-open --host 127.0.0.1 --port 9119

Sau đó mở http://127.0.0.1:9119. Địa chỉ này chỉ có hiệu lực trên máy tính hiện tại.

Các lỗi thường gặp

• Nhập hermes nhưng nhận thông báo không tìm thấy lệnh: Trước tiên, hãy đóng terminal rồi mở một cửa sổ mới. Nếu vẫn không tìm thấy, hãy xác nhận ~/.local/bin đã có trong PATH; PATH là danh sách các vị trí mà hệ thống dùng để tìm thư mục chứa lệnh. Trên Windows, hãy xác nhận thư mục khởi chạy do trình cài đặt ghi vào đã có trong PATH.
• Quá trình tải xuống cài đặt bị ngắt giữa chừng: Chạy lại cùng một lệnh cài đặt; phần đã tải xuống sẽ tiếp tục được sử dụng.
• Hermes không phản hồi hoặc báo không thể kết nối: Xác nhận OmniProxy đang chạy và kiểm tra Base URL có kết thúc bằng /v1 hay không. Nếu Hermes chạy trong Docker còn OmniProxy chạy trên máy chủ, không dùng 127.0.0.1 chỉ có hiệu lực bên trong container.
• Có thông báo khóa không hợp lệ: Cập nhật khóa của OmniProxy, sau đó sửa api_key trong config.yaml. Khóa của xAI hoặc Google thuộc phần thiết lập nhà cung cấp trong OmniProxy; không nhập các khóa đó vào trường này của Hermes.
• Có thông báo không tồn tại mô hình này: Mở danh sách mô hình hiện tại của OmniProxy rồi sao chép nguyên văn grok-4.7 hoặc gemini-3.8-flash theo cách hiển thị trong danh sách.
• Hermes có phản hồi nhưng không thể làm những việc như đọc tệp hoặc chạy lệnh: Chuyển sang một mô hình khác có các khả năng này trong OmniProxy, sau đó mở một phiên Hermes mới.
• Chương trình được đặt trên ổ cứng di động và hermes doctor báo lỗi lưu trữ sau khi rút ổ: Trước tiên, hãy kết nối lại ổ cứng đó. Không để Hermes ghi thêm một bộ cấu hình khác khi ổ cứng chưa được kết nối.

Tài liệu tham khảo chính thức

Xem các bước cài đặt trong tài liệu cài đặt Hermes và hỗ trợ nền tảng. Cấu hình Custom endpoint có trong tài liệu Hermes Provider. Model ID lần lượt có trong tài liệu về mô hình Grok và hướng dẫn tương thích OpenAI của Gemini.

Quá trình cài đặt trên macOS đã được thực hiện đầy đủ vào ngày 2026-10-09 bằng Hermes Agent v0.21.6. grok-4.7 và gemini-3.8-flash là các Model ID tiêu chuẩn trong tài liệu của xAI và Google vào ngày đó. Khi nhập cấu hình thực tế, hãy dùng tên hiển thị trong OmniProxy.

Thay thế mọi chỗ giữ chỗ bằng giá trị từ cấu hình OmniProxy của riêng bạn. Không bao giờ công bố khóa thật.

Kết quả được lưu hoặc mã HTTP 200 đơn lẻ không chứng minh khả năng tương thích đầy đủ của Agent. Hãy kiểm tra nguồn và mô hình trong bản ghi lệnh gọi của OmniProxy.

Nguồn chính thức · Hermes ↗