Cách cài đặt Hermes Agent trên Linux, macOS và WSL

Cài đặt Hermes Agent không chỉ là chạy một lệnh install rồi mở chatbot. Nếu muốn dùng Hermes trong môi trường làm việc nghiêm túc, bạn nên hiểu các bước tối thiểu: chuẩn bị hệ thống, cài CLI, chạy hermes setup, chọn model/provider, kiểm tra tool, và xác định cách quản lý quyền cho agent.

Bài này hướng dẫn theo hướng thực tế cho người dùng kỹ thuật, founder, marketer technical hoặc team nội bộ muốn thử Hermes Agent trên máy cá nhân/server Linux. Mục tiêu không phải “bật mọi thứ ngay lập tức”, mà là có một cài đặt sạch, kiểm tra được, và đủ an toàn để bắt đầu.

Nếu bạn chưa rõ Hermes Agent là gì và nó khác chatbot AI thông thường ở đâu, nên đọc trước bài Hermes Agent là gì. Khi đã hiểu bức tranh tổng quan, phần cài đặt dưới đây sẽ dễ theo dõi hơn.

Trước khi cài đặt Hermes Agent

Hermes Agent là open-source AI agent framework của Nous Research, phát hành theo giấy phép MIT. Hermes có thể chạy trong terminal, qua messaging gateway, và tích hợp vào workflow kỹ thuật thông qua tools, skills, memory, cron jobs, multi-provider và subagents.

Trước khi cài, bạn nên xác định ba việc:

• Bạn muốn dùng Hermes cho mục tiêu nào: coding, nghiên cứu, vận hành, tạo nội dung, báo cáo định kỳ hay trợ lý qua Telegram/Slack.
• Bạn sẽ dùng model/provider nào: OpenRouter, Anthropic, OpenAI, DeepSeek, Google Gemini, local endpoint hoặc provider khác.
• Bạn có sẵn API key hoặc cơ chế đăng nhập tương ứng chưa.

Một lỗi phổ biến khi thử AI agent là cài xong rồi bật quá nhiều quyền mà chưa có workflow cụ thể. Với Hermes, nên bắt đầu từ CLI và một provider ổn định, sau đó mới mở rộng sang gateway, cron hoặc subagents.

Yêu cầu môi trường cơ bản

Hermes Agent hỗ trợ Linux, macOS và WSL. Với người dùng Windows, cách dễ nhất thường là dùng WSL để có môi trường shell gần với Linux. Trong bài này, ví dụ dùng cú pháp terminal kiểu Linux/macOS.

Bạn cần có:

• Terminal có quyền chạy lệnh cài đặt.
• Kết nối internet để tải installer và gọi model provider.
• Một API key hoặc tài khoản/provider phù hợp.
• Quyền ghi vào thư mục home của user.
• Công cụ shell cơ bản như curl.

Nếu dùng trong công ty, nên cài trước ở máy cá nhân hoặc môi trường staging. Không nên cài trực tiếp trên server production rồi cấp quyền rộng cho agent khi chưa có chính sách vận hành.

Cài đặt Hermes Agent bằng script chính thức

Lệnh cài đặt theo tài liệu của Hermes Agent là:

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

Lệnh này tải installer và chạy trong shell hiện tại. Sau khi cài xong, mở terminal mới hoặc reload shell nếu hệ thống yêu cầu. Sau đó kiểm tra lệnh hermes đã sẵn sàng hay chưa:

hermes --version

Nếu terminal báo không tìm thấy lệnh, nguyên nhân thường là PATH chưa được cập nhật. Hãy mở shell mới, kiểm tra thông báo cuối của installer, hoặc xem file cấu hình shell như .bashrc, .zshrc tùy môi trường.

Với team nội bộ, nên ghi lại phiên bản Hermes đã cài và ngày cài đặt. AI agent framework thay đổi nhanh, vì vậy việc biết phiên bản giúp xử lý lỗi và tái lập môi trường dễ hơn.

Chạy hermes setup lần đầu

Sau khi cài, bước quan trọng nhất là chạy setup wizard:

hermes setup

hermes setup giúp bạn cấu hình những phần cơ bản như model/provider, terminal, gateway, tools hoặc agent tùy lựa chọn. Đây là cách tốt hơn so với tự sửa file config ngay từ đầu, vì wizard giúp giảm lỗi cấu hình ban đầu.

Trong lần chạy đầu, bạn nên tập trung vào ba phần:

• Chọn provider/model mặc định.
• Đảm bảo API key hoặc login provider hợp lệ.
• Kiểm tra terminal và tool cơ bản.

Nếu bạn chưa chắc provider nào phù hợp, hãy chọn một provider phổ biến, ổn định và có model đủ mạnh cho tác vụ bạn định làm. Với coding hoặc phân tích kỹ thuật, nên ưu tiên model có khả năng tool use và reasoning tốt. Với tác vụ tóm tắt hoặc nội dung nhẹ, có thể dùng model nhanh/rẻ hơn.

Phần chọn model/provider sẽ được giải thích kỹ hơn trong bài cấu hình model và provider cho Hermes.

Kiểm tra cấu hình sau setup

Sau khi chạy wizard, dùng các lệnh sau để kiểm tra trạng thái:

hermes config
hermes doctor
hermes status

hermes config hiển thị cấu hình hiện tại. hermes doctor giúp kiểm tra dependency và cấu hình thiếu. hermes status cho bạn cái nhìn tổng quan hơn về các thành phần Hermes.

Nếu có lỗi API key, provider hoặc model, đừng vội chỉnh nhiều thứ cùng lúc. Hãy kiểm tra từng lớp:

• API key đã được lưu đúng chưa.
• Provider có đúng tên không.
• Model có tồn tại và được provider hỗ trợ không.
• Máy có internet và không bị firewall/proxy chặn không.

Cách debug tốt nhất là thay đổi ít nhất có thể, chạy lại kiểm tra, rồi mới tiếp tục.

Chạy Hermes Agent lần đầu trong CLI

Để mở phiên chat tương tác:

hermes

Bạn có thể hỏi thử một câu đơn giản:

Tóm tắt ngắn Hermes Agent đang chạy trong môi trường nào.

Hoặc dùng chế độ single query:

hermes chat -q "Giải thích ngắn Hermes Agent là gì"

Chế độ tương tác phù hợp khi bạn muốn làm việc nhiều bước. Chế độ chat -q hữu ích cho script, test nhanh hoặc tác vụ một lần.

Trong lần chạy đầu, nên tránh yêu cầu agent chỉnh sửa file quan trọng hoặc chạy lệnh rủi ro. Hãy bắt đầu bằng tác vụ đọc hiểu: giải thích repo, tóm tắt tài liệu, tạo checklist, hoặc đọc một thư mục test không nhạy cảm.

Hiểu các file cấu hình quan trọng

Hermes lưu cấu hình và trạng thái chủ yếu trong thư mục home của user. Các đường dẫn thường gặp gồm:

• ~/.hermes/config.yaml: cấu hình chính.
• ~/.hermes/.env: API keys và secrets.
• ~/.hermes/skills/: skills đã cài hoặc tự tạo.
• ~/.hermes/sessions/: dữ liệu phiên và routing liên quan.
• ~/.hermes/logs/: log gateway và lỗi.

Bạn không cần sửa thủ công mọi file ngay từ đầu. Hermes CLI có các lệnh quản lý cấu hình:

hermes config path
hermes config env-path
hermes config edit
hermes config set KEY VALUE

Với môi trường doanh nghiệp, .env cần được xem như file nhạy cảm. Không commit vào Git, không chia sẻ qua chat công khai, và không đưa vào prompt nếu không cần thiết.

Thiết lập provider và API key

Tùy provider, Hermes có thể dùng API key hoặc OAuth/login. Một số provider phổ biến dùng biến môi trường như OPENROUTER_API_KEY, ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, DEEPSEEK_API_KEY hoặc các biến tương ứng khác.

Bạn có thể đặt key trong file .env của Hermes hoặc thông qua setup wizard. Nếu dùng nhiều provider, hãy đặt tên rõ và kiểm tra provider mặc định trong config.

Một cách tiếp cận thực tế:

• Dùng một provider chính cho tác vụ nặng.
• Dùng provider phụ cho tác vụ nhẹ hoặc dự phòng.
• Không dùng cùng một API key cho mọi môi trường nếu có thể tách riêng.
• Theo dõi chi phí nếu chạy agent thường xuyên hoặc có cron jobs.

Khi cấu hình lỗi, hãy chạy hermes doctor trước khi đoán nguyên nhân. Nhiều vấn đề ban đầu chỉ là thiếu env var hoặc model name không đúng.

Bật và kiểm tra tools

Hermes Agent mạnh vì có thể dùng tools. Nhưng cũng vì vậy, bạn cần quản lý tools cẩn thận. Kiểm tra danh sách tool bằng:

hermes tools list

Mở giao diện quản lý tool:

hermes tools

Một số nhóm tool thường gặp gồm terminal, file, web, browser, vision, image generation, tts, cronjob, messaging, session search, delegation và skills. Không phải workflow nào cũng cần tất cả.

Nguyên tắc khuyến nghị:

• Bắt đầu với toolset tối thiểu.
• Chỉ bật tool khi có nhu cầu thật.
• Với môi trường nhạy cảm, tắt web/browser nếu không cần.
• Với shell/terminal, dùng approval cho lệnh rủi ro.
• Sau khi thay đổi tool, bắt đầu phiên mới để cấu hình có hiệu lực.

Điều quan trọng là phân biệt giữa “AI có thể làm” và “AI nên được phép làm”. Agent càng có nhiều quyền, bạn càng cần quy trình kiểm soát rõ hơn.

Cài và dùng skills cơ bản

Skills là cách Hermes lưu quy trình tái sử dụng. Bạn có thể xem skills hiện có:

hermes skills list

Tìm skill trong hub:

hermes skills search QUERY

Cài skill:

hermes skills install ID

Trong phiên chat, có thể load skill bằng slash command:

/skill ten-skill

Ở giai đoạn đầu, bạn chưa cần tạo nhiều skill. Hãy dùng Hermes một thời gian, quan sát những workflow nào lặp lại, rồi mới đóng gói thành skill. Ví dụ: quy trình review PR, kiểm tra bài viết trước khi đăng, hoặc checklist debug hệ thống.

Một skill tốt nên có điều kiện sử dụng, các bước cụ thể, lệnh cần chạy, lỗi thường gặp và cách xác minh kết quả. Nếu skill chỉ là vài dòng mô tả chung chung, agent sẽ khó tái sử dụng hiệu quả.

Quy trình cài đặt khuyến nghị

Một quy trình an toàn cho lần đầu dùng Hermes Agent có thể như sau:

1. Cài Hermes bằng installer chính thức. 2. Chạy hermes setup và chọn provider/model. 3. Kiểm tra bằng hermes doctor. 4. Mở hermes và thử tác vụ hỏi đáp nhẹ. 5. Kiểm tra hermes tools list và chỉ bật tool cần thiết. 6. Dùng agent với một thư mục/project thử nghiệm. 7. Ghi lại workflow nào hiệu quả để sau này tạo skill. 8. Chỉ cấu hình cron/gateway khi đã có nhu cầu rõ.

Cách đi này chậm hơn một chút so với bật tất cả ngay từ đầu, nhưng phù hợp hơn với môi trường chuyên nghiệp. AI agent nên được triển khai như công cụ vận hành, không phải món đồ chơi thử nghiệm trong hệ thống quan trọng.

Lỗi thường gặp khi cài Hermes Agent

Lệnh hermes không tồn tại sau khi cài

Thường do PATH chưa cập nhật. Hãy mở terminal mới, kiểm tra thông báo của installer, hoặc reload file cấu hình shell. Nếu vẫn lỗi, kiểm tra thư mục cài đặt và biến PATH.

Provider báo thiếu API key

Kiểm tra ~/.hermes/.env hoặc chạy lại hermes setup. Đảm bảo key đúng provider, không thừa khoảng trắng, và chưa hết hạn/quota.

Model không chạy dù API key đúng

Có thể model name không được provider hỗ trợ, tài khoản chưa có quyền dùng model đó, hoặc provider đang lỗi. Thử model khác đơn giản hơn để xác định lỗi nằm ở model hay cấu hình chung.

Tool không xuất hiện trong phiên chat

Sau khi bật/tắt tool, bạn thường cần bắt đầu phiên mới. Trong CLI có thể thoát ra mở lại, hoặc dùng slash command phù hợp để reset phiên nếu đang trong môi trường hỗ trợ.

Agent chạy lệnh ngoài ý muốn

Kiểm tra approval mode, toolset đang bật và prompt bạn đã đưa. Với tác vụ có rủi ro, yêu cầu agent lập kế hoạch trước, chờ xác nhận, rồi mới thực thi.

Kết luận

Cài đặt Hermes Agent khá nhanh với lệnh curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash, nhưng phần quan trọng hơn là cấu hình đúng sau khi cài. hermes setup, hermes doctor, quản lý provider, kiểm soát tools và hiểu các file cấu hình là nền tảng để dùng Hermes an toàn.

Nếu bạn tiếp cận Hermes như một agent runtime thay vì một chatbot, hãy triển khai từng bước: CLI trước, workflow nhỏ trước, quyền tối thiểu trước. Khi mọi thứ ổn định, bạn có thể mở rộng sang skills, memory, cron, gateway và subagents.

Bài tiếp theo trong series sẽ đi sâu vào cấu hình model và provider cho Hermes, phần quyết định trực tiếp đến chất lượng, chi phí và độ ổn định của agent.