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 hoặc làm theo các bước thủ công để có toàn quyền kiểm soát.

Cài đặt nhanh

Linux / macOS / WSL2

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Android / Termux

Hermes hiện đã hỗ trợ đường dẫn cài đặt tương thích Termux:

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 quy trình Android đã được kiểm thử:

Sử dụng pkg của Termux cho các phụ thuộc hệ thống (git, python, nodejs, ripgrep, ffmpeg, build tools)
Tạo virtualenv bằng python -m venv
Tự động export ANDROID_API_LEVEL cho các bản build wheel Android
Cài đặt extra .[termux] đã được kiểm duyệt bằng pip
Mặc định bỏ qua bootstrap trình duyệt / WhatsApp chưa được kiểm thử

Nếu bạn muốn đường dẫn cài đặt chi tiết đầy đủ, hãy xem hướng dẫn Termux riêng.

Windows

Windows gốc không được hỗ trợ. Vui lòng cài đặt WSL2 và chạy Hermes Agent từ đó. Lệnh cài đặt ở trên hoạt động bên trong WSL2.

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

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

Sau khi cài đặt

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

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

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

hermes model          # Chọn nhà cung cấp LLM và mô hình
hermes tools          # Cấu hình công cụ nào được bật
hermes gateway setup  # Thiết lập nền tảng nhắn tin
hermes config set     # Đặt giá trị cấu hình riêng lẻ
hermes setup          # Hoặc chạy trình hướng dẫn thiết lập đầy đủ

Điều kiện tiên quyết

Đ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 (cho tự động hóa trình duyệt và cầu nối WhatsApp)
ripgrep (tìm kiếm tệp nhanh)
ffmpeg (chuyển đổi định dạng âm thanh cho TTS)

thông tin

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

Người dùng Nix

Nếu bạn sử dụng Nix (trên NixOS, macOS hoặc Linux), có đường dẫn thiết lập chuyên dụng với Nix flake, module NixOS khai báo và chế độ container tùy chọn. Xem hướng dẫn Thiết lập Nix & NixOS.

Cài đặt thủ công

Nếu bạn muốn toàn quyền kiểm soát quá trình cài đặt, hãy làm theo các bước sau.

Bước 1: Clone kho lưu trữ

Clone với --recurse-submodules để kéo các submodule cần thiết:

git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

Nếu bạn đã clone mà không có --recurse-submodules:

git submodule update --init --recursive

Bước 2: Cài đặt uv & Tạo môi trường ảo

# Cài đặt uv (nếu chưa có)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Tạo venv với Python 3.11 (uv tự tải nếu chưa có — không cần sudo)
uv venv venv --python 3.11

mẹo

Bạn không cần kích hoạt venv để sử dụng hermes. Điểm vào có shebang được mã hóa cứng trỏ đến venv Python, nên nó hoạt động toàn cục sau khi được symlink.

Bước 3: Cài đặt phụ thuộc Python

# Chỉ định venv cho uv
export VIRTUAL_ENV="$(pwd)/venv"

# Cài đặt với tất cả extras
uv pip install -e ".[all]"

Nếu bạn chỉ muốn tác nhân cốt lõi (không hỗ trợ Telegram/Discord/cron):

uv pip install -e "."

Chi tiết các extras tùy chọn

Extra	Chức năng	Lệnh cài đặt
`all`	Tất cả bên dưới	`uv pip install -e ".[all]"`
`messaging`	Cổng Telegram, Discord & Slack	`uv pip install -e ".[messaging]"`
`cron`	Phân tích biểu thức cron cho tác vụ định kỳ	`uv pip install -e ".[cron]"`
`cli`	Giao diện menu terminal cho trình hướng dẫn thiết lập	`uv pip install -e ".[cli]"`
`modal`	Backend thực thi đám mây Modal	`uv pip install -e ".[modal]"`
`tts-premium`	Giọng nói cao cấp ElevenLabs	`uv pip install -e ".[tts-premium]"`
`voice`	Đầu vào micro CLI + phát lại âm thanh	`uv pip install -e ".[voice]"`
`pty`	Hỗ trợ terminal PTY	`uv pip install -e ".[pty]"`
`termux`	Gói Android / Termux đã kiểm thử (`cron`, `cli`, `pty`, `mcp`, `honcho`, `acp`)	`python -m pip install -e ".[termux]" -c constraints-termux.txt`
`honcho`	Bộ nhớ AI-native (tích hợp Honcho)	`uv pip install -e ".[honcho]"`
`mcp`	Hỗ trợ Model Context Protocol	`uv pip install -e ".[mcp]"`
`homeassistant`	Tích hợp Home Assistant	`uv pip install -e ".[homeassistant]"`
`acp`	Hỗ trợ tích hợp ACP editor	`uv pip install -e ".[acp]"`
`slack`	Nhắn tin Slack	`uv pip install -e ".[slack]"`
`dev`	pytest & tiện ích kiểm thử	`uv pip install -e ".[dev]"`

Bạn có thể kết hợp các extras: uv pip install -e ".[messaging,cron]"

Người dùng Termux

.[all] hiện không khả dụng trên Android vì extra voice sử dụng faster-whisper, phụ thuộc vào wheel ctranslate2 chưa được phát hành cho Android. Hãy dùng .[termux] cho đường dẫn cài đặt di động đã kiểm thử, sau đó thêm từng extra riêng lẻ khi cần.

Bước 4: Cài đặt Submodule tùy chọn (nếu cần)

# Backend huấn luyện RL (tùy chọn)
uv pip install -e "./tinker-atropos"

Cả hai đều là tùy chọn — nếu bạn bỏ qua, các bộ công cụ tương ứng sẽ không khả dụng.

Bước 5: Cài đặt phụ thuộc Node.js (Tùy chọn)

Chỉ cần thiết cho tự động hóa trình duyệt (Browserbase) và cầu nối WhatsApp:

npm install

Bước 6: Tạo thư mục cấu hình

# Tạo cấu trúc thư mục
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}

# Sao chép tệp cấu hình mẫu
cp cli-config.yaml.example ~/.hermes/config.yaml

# Tạo tệp .env trống cho khóa API
touch ~/.hermes/.env

Bước 7: Thêm khóa API của bạn

Mở ~/.hermes/.env và thêm tối thiểu một khóa nhà cung cấp LLM:

# Bắt buộc — ít nhất một nhà cung cấp LLM:
OPENROUTER_API_KEY=sk-or-v1-your-key-here

# Tùy chọn — bật thêm công cụ:
FIRECRAWL_API_KEY=fc-your-key          # Tìm kiếm & thu thập web (hoặc tự host, xem docs)
FAL_KEY=your-fal-key                   # Tạo hình ảnh (FLUX)

Hoặc đặt qua CLI:

hermes config set OPENROUTER_API_KEY sk-or-v1-your-key-here

Bước 8: Thêm `hermes` vào PATH

mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes

Nếu ~/.local/bin chưa nằm trong PATH, hãy thêm vào cấu hình shell:

# Bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

# Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

# Fish
fish_add_path $HOME/.local/bin

Bước 9: Cấu hình nhà cung cấp

hermes model       # Chọn nhà cung cấp LLM và mô hình

Bước 10: Xác minh cài đặt

hermes version    # Kiểm tra lệnh có sẵn
hermes doctor     # Chạy chẩn đoán để xác minh mọi thứ hoạt động
hermes status     # Kiểm tra cấu hình
hermes chat -q "Hello! What tools do you have available?"

Tham khảo nhanh: Cài đặt thủ công (rút gọn)

Dành cho những ai chỉ cần các lệnh:

# Cài đặt uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone & vào thư mục
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# Tạo venv với Python 3.11
uv venv venv --python 3.11
export VIRTUAL_ENV="$(pwd)/venv"

# Cài đặt mọi thứ
uv pip install -e ".[all]"
uv pip install -e "./tinker-atropos"
npm install  # tùy chọn, cho công cụ trình duyệt và WhatsApp

# Cấu hình
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
cp cli-config.yaml.example ~/.hermes/config.yaml
touch ~/.hermes/.env
echo 'OPENROUTER_API_KEY=sk-or-v1-your-key' >> ~/.hermes/.env

# Đưa hermes vào toàn cục
mkdir -p ~/.local/bin
ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes

# Xác minh
hermes doctor
hermes

Khắc phục sự cố

Vấn đề	Giải pháp
`hermes: command not found`	Tải lại shell (`source ~/.bashrc`) hoặc kiểm tra PATH
`API key not set`	Chạy `hermes model` để cấu hình nhà cung cấp, hoặc `hermes config set OPENROUTER_API_KEY your_key`
Thiếu cấu hình sau cập nhật	Chạy `hermes config check` rồi `hermes config migrate`

Để biết thêm chẩn đoán, 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.

Cài đặt nhanh​

Linux / macOS / WSL2​

Android / Termux​

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

Sau khi cài đặt​

Điều kiện tiên quyết​

Cài đặt thủ công​

Bước 1: Clone kho lưu trữ​

Bước 2: Cài đặt uv & Tạo môi trường ảo​

Bước 3: Cài đặt phụ thuộc Python​

Bước 4: Cài đặt Submodule tùy chọn (nếu cần)​

Bước 5: Cài đặt phụ thuộc Node.js (Tùy chọn)​

Bước 6: Tạo thư mục cấu hình​

Bước 7: Thêm khóa API của bạn​

Bước 8: Thêm hermes vào PATH​

Bước 9: Cấu hình nhà cung cấp​

Bước 10: Xác minh cài đặt​

Tham khảo nhanh: Cài đặt thủ công (rút gọn)​

Khắc phục sự cố​