Hướng dẫn cấu hình Hermes Agent với Beeknoee

Hermes Agent là gì?

Hermes Agent là AI coding agent chạy trong terminal, do Nous Research phát triển. Điểm mạnh của Hermes là bộ cài đặt "tất cả trong một" — trình cài tự lo luôn Python, Node.js, ripgrep, ffmpeg nên không phải chuẩn bị môi trường trước.

💡 Hermes có sẵn tuỳ chọn Custom endpoint cho mọi API nói được giao thức OpenAI, nên nối với Beeknoee rất gọn.

Yêu cầu

• Linux, macOS, WSL2, Windows hoặc Termux (Android)
• API Key từ Beeknoee Platform

💡 Không cần cài sẵn Python hay Node.js — trình cài của Hermes tự lo.

📌 Bước 1: Tạo API Key

1. Truy cập https://platform.beeknoee.com/api-keys
2. Đăng nhập bằng tài khoản Google
3. Nhấn "Tạo API Key"
4. Copy API Key (dạng sk-bee-xxxx...)

⚠️ API key chỉ hiển thị 24 giờ đầu — copy và lưu ngay!

📌 Bước 2: Cài đặt Hermes

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

source ~/.bashrc    # hoặc ~/.zshrc nếu bạn dùng zsh

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

Kiểm tra:

hermes --version

📌 Bước 3: Cấu hình Beeknoee

Cách 1: Qua giao diện hỏi đáp (khuyên dùng)

hermes model

Chọn "Custom endpoint (self-hosted / VLLM / etc.)", rồi điền:

⚠️ Base URL kết thúc bằng /v1, không thêm /chat/completions (Hermes tự nối phần đó) và không có dấu / ở cuối.

Cách 2: Sửa thẳng file cấu hình

Hermes tách bí mật (~/.hermes/.env) khỏi thiết lập (~/.hermes/config.yaml), và cho phép tham chiếu biến bằng ${...} ngay trong file cấu hình. Đây là cách Quick Setup ghi, và cũng là cách nên làm khi cấu hình tay:

1. Đặt key vào ~/.hermes/.env:

BEEKNOEE_API_KEY="sk-bee-YOUR_API_KEY"

2. Trỏ ~/.hermes/config.yaml sang Beeknoee:

model:
  default: deepseek/deepseek-v3.2
  provider: custom
  base_url: https://platform.beeknoee.com/v1
  api_key: ${BEEKNOEE_API_KEY}
display:
  streaming: true

💡 display.streaming: true cho chữ hiện dần ra terminal thay vì đợi trả lời xong mới in. Quick Setup chỉ đặt giá trị này khi bạn chưa tự đặt.

⚠️ Ghi thẳng api_key: sk-bee-... vào config.yaml vẫn chạy, nhưng key sẽ nằm trong file dễ bị chia sẻ nhầm khi bạn gửi cấu hình cho người khác.

Kiểm tra cấu hình sau khi sửa:

hermes config check

Khai báo nhiều cấu hình cùng lúc

Nếu bạn muốn chuyển qua lại giữa các model, khai báo dạng danh sách:

custom_providers:
  - name: beeknoee
    base_url: https://platform.beeknoee.com/v1
    key_env: BEEKNOEE_API_KEY

Rồi đặt biến môi trường BEEKNOEE_API_KEY, và chuyển model ngay trong phiên:

/model custom:beeknoee:deepseek/deepseek-v3.2

💡 Dùng key_env thay vì ghi thẳng api_key sẽ an toàn hơn — key không nằm trong file cấu hình.

📌 Bước 4: Sử dụng

cd /path/to/your/project
hermes

Gõ yêu cầu bằng tiếng Việt hoặc tiếng Anh, Hermes sẽ đọc code, đề xuất thay đổi và chạy lệnh khi cần.

Models khuyên dùng với Hermes

💡 Model ID chính xác và giá theo thời gian thực xem tại trang Các Mô Hình AI — ấn nút Copy ID.

Nâng cao: thêm tham số riêng cho request

Hermes cho phép chèn thêm trường vào thân request gửi lên. Ví dụ bật web search của Beeknoee cho mọi câu hỏi:

custom_providers:
  - name: beeknoee
    base_url: https://platform.beeknoee.com/v1
    key_env: BEEKNOEE_API_KEY
    extra_body:
      tools:
        - type: web_search

💡 Xem thêm Web Search — phụ phí 200đ mỗi lần tìm thành công.

🆓 Models miễn phí qua BeeSynapse

Khi đã kết nối email tại trang BeeSynapse Integrations, hệ thống tự động ưu tiên free quota:

Bạn không cần đổi cấu hình — Beeknoee tự route qua free quota trước, hết quota mới trừ VNĐ.

Xử lý lỗi

Lỗi 404 khi gọi model

• Base URL đúng: https://platform.beeknoee.com/v1
• ❌ Sai: có dấu / ở cuối → thành //chat/completions
• ❌ Sai: dán cả /chat/completions vào — Hermes tự nối phần này
• ℹ️ /api/v1 cũng chạy được (tự chuyển hướng sang /v1) — dùng /v1 cho gọn

"Unauthorized" hoặc "Invalid API key"

• Key phải bắt đầu bằng sk-bee-
• Nếu dùng key_env, kiểm tra biến đã được nạp: echo $BEEKNOEE_API_KEY
• Kiểm tra key chưa bị thu hồi tại API Keys

Lệnh hermes không tìm thấy sau khi cài

Nạp lại shell: source ~/.bashrc (hoặc ~/.zshrc), hoặc mở terminal mới.

Model suy luận bị timeout

Model reasoning có thể "nghĩ" hơn 120 giây. Hermes mặc định dùng streaming nên thường không sao. Xem Error Handling.

So sánh với các agent khác

HOÀN TẤT! 🎉

Cần hỗ trợ thêm? Sử dụng Support Chat (góc dưới phải trên platform) hoặc liên hệ qua email.