Hermes Agent

Một nhà cung cấp được đặt tên trong ~/.hermes/config.yaml — api https://api.kunavo.com, transport anthropic_messages, được chọn bằng provider: custom:kunavo — kết nối Hermes Agent với Claude qua giao thức Messages, nơi Hermes Agent tự gửi các dấu mốc bộ nhớ đệm và giới hạn đầu ra.

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com        # origin — the Anthropic SDK adds /v1/messages
    key_env: KUNAVO_API_KEY            # the variable's NAME; the key goes in ~/.hermes/.env
    transport: anthropic_messages
    models:
      claude-sonnet-5:
        context_length: 1000000
        prompt_caching: true
      claude-haiku-4-5:
        context_length: 200000
        prompt_caching: true

model:
  default: claude-sonnet-5
  provider: custom:kunavo

Từng bước

1. Tạo khóa tại /app/keys rồi sao chép khóa — khóa chỉ hiển thị một lần.
2. Lưu khóa tại nơi Hermes cất thông tin bí mật: hermes config set KUNAVO_API_KEY sk-kn-... ghi khóa vào ~/.hermes/.env. Dòng key_env trong khối cấu hình chỉ định biến đó; bản thân khóa không bao giờ được ghi vào config.yaml.
3. Thêm khối cấu hình vào ~/.hermes/config.yaml — lệnh hermes config edit sẽ mở tệp. Nếu đã có mục model:, hãy thay các giá trị default và provider trong mục đó, giữ nguyên phần còn lại.
4. Hoặc để trình hướng dẫn ghi cấu hình: chạy hermes model trong cửa sổ dòng lệnh, bên ngoài mọi phiên trò chuyện, chọn Custom endpoint (self-hosted / VLLM / etc.) rồi trả lời các câu hỏi — URL cơ sở API, khóa API, tên mô hình, chế độ API và độ dài ngữ cảnh.
5. Khởi chạy hermes và đọc biểu ngữ: mô hình cùng cửa sổ ngữ cảnh được hiển thị ở đó, và cả hai phải khớp với khối cấu hình.
6. Gửi hai tin nhắn rồi mở /usage để xem các lượt đã sử dụng những gì. Để đổi mô hình trong phiên, dùng /model custom:kunavo:claude-opus-5-5.

Đã kiểm tra đối chiếu với Trang nhà cung cấp AI của Hermes Agent vào 5 tháng 10, 2026. Cài đặt của bên thứ ba có thể thay đổi; nếu tên trường ở đây không còn khớp với những gì bạn thấy, trang đó là nguồn có thẩm quyền, không phải trang này.

Xác minh trước khi gỡ lỗi ứng dụng khách

Một yêu cầu sẽ xác định liệu lỗi nằm ở endpoint, khóa hay tệp cấu hình. Nếu lệnh này trả về JSON, cùng base URL và khóa sẽ hoạt động trong Hermes Agent.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

Đặt model id nào vào trường

Mọi mô hình văn bản đều có thể truy cập bằng model id — danh sách đang hoạt động là GET /v1/models, còn danh mục kèm giá nằm trên trang mô hình. Mức giá tính bằng USD trên mỗi 1M token, đầu vào / đầu ra.

Giao thức tương thích OpenAI

Cùng khóa đó có thể dùng với mọi họ mô hình khác thông qua /v1/chat/completions, và với giao thức này chỉ cần dạng ngắn nhất được tài liệu Hermes hướng dẫn — một khối model: với provider: custom và base_url, cũng là những gì hermes model yêu cầu:

# ~/.hermes/config.yaml — the bare form, for an OpenAI-compatible endpoint
model:
  default: gpt-6-sol
  provider: custom
  base_url: https://api.kunavo.com/v1    # this wire keeps /v1
  key_env: KUNAVO_API_KEY
  context_length: 1050000

URL cơ sở giữ /v1 ở đây, theo cách dùng trong các ví dụ về máy chủ cục bộ của tài liệu Hermes, còn context_length cố định giới hạn cửa sổ để Hermes không phải tự nhận diện. Để cấu hình đồng thời cả hai giao thức, hãy tạo một mục riêng có tên — transport: chat_completions — rồi chuyển đổi bằng /model custom:<name>:<model>.

Bộ nhớ đệm lời nhắc trên từng giao thức

Trên giao thức Anthropic, Hermes tự thêm các dấu mốc bộ nhớ đệm. Đối với nhà cung cấp tùy chỉnh, trang cấu hình mô hình hướng dẫn công tắc dùng trong khối phía trên — prompt_caching: true trên mô hình — và cho biết cách bố trí tùy theo giao thức: các khối gốc trên anthropic_messages, bố cục dạng bao bọc trên giao thức tương thích OpenAI. /v1/messages của Kunavo chuyển tiếp nguyên trạng nội dung yêu cầu và không tự thêm điểm ngắt nào, vì vậy trên giao thức này, các dấu mốc do Hermes gửi hoặc không có dấu mốc nào.

Tài liệu Hermes không nêu rõ thời hạn tồn tại khi dùng điểm cuối tùy chỉnh. prompt_caching.cache_ttl — 5m, 1h hoặc auto — được mô tả cho Claude thông qua API Anthropic gốc, OpenRouter và Nous Portal, nhưng không đề cập đến các điểm cuối khác. Kunavo chuyển tiếp dấu mốc nhận được và tính phí ghi theo cùng mức giá, vì vậy hãy xem dữ liệu sử dụng của chính bạn để biết: nếu lượt trao đổi sau mười phút tạm dừng vẫn hiển thị một lần đọc bộ nhớ đệm, thì mục nhập một giờ vẫn còn hiệu lực.

Trên giao thức tương thích OpenAI, Kunavo tự đặt các điểm ngắt cho mô hình Claude — trong prompt hệ thống, phần định nghĩa công cụ và cuối cuộc hội thoại — khi prompt đủ dài để được lưu vào bộ nhớ đệm, bất kể phía máy khách có gửi dấu mốc hay không. Mô hình GPT được nhà cung cấp lưu bộ nhớ đệm một cách ngầm định.

Dù bên nào đặt các điểm đánh dấu, hóa đơn vẫn như nhau. Với Claude Sonnet 5, một lần đọc bộ nhớ đệm có giá $0.14 cho mỗi 1M token, so với $1.40 cho đầu vào mới; một lần ghi bộ nhớ đệm có giá $1.75 — mức phụ phí ghi mà Claude tính thêm trên đầu vào, được tính theo cùng mức đó khi mục nhập yêu cầu thời hạn một giờ. Mỗi mục nhập tồn tại năm phút và mỗi lần đọc sẽ làm mới thời hạn, vì vậy chi phí của tác nhân phụ thuộc ít hơn vào mô hình và phụ thuộc nhiều hơn vào việc yêu cầu tiếp theo có đến trong khoảng thời gian đó hay không. Xem mức giá bộ nhớ đệm của từng mô hình trên trang bộ nhớ đệm lời nhắc.

Một hành vi của Hermes tốn kém hơn mọi mức giá: tài liệu Hermes lưu ý rằng khi đổi mô hình giữa phiên, tự động chuyển sang phương án dự phòng hoặc xoay vòng thông tin xác thực, bộ nhớ đệm prompt sẽ được đặt lại, nên tin nhắn tiếp theo phải đọc lại toàn bộ cuộc hội thoại với giá đầu vào đầy đủ. Hãy chọn mô hình trước khi bắt đầu một phiên dài.

Chi phí mỗi ngày của tác nhân luôn hoạt động

Trên Hermes, khi không ai nhập nội dung, khoản bị tính phí gồm mọi thứ bạn đã lên lịch và các tác vụ phụ phát sinh từ mỗi cuộc hội thoại. Tài liệu về cron cho biết mỗi lần chạy theo lịch bắt đầu một phiên mới, nên mỗi lần chạy đều bị tính phí toàn bộ prompt — hướng dẫn, lược đồ công cụ, kỹ năng đính kèm. Kích thước prompt tùy thuộc vào thiết lập của bạn, vì vậy bảng nêu rõ các giả định: 20.000 token mỗi lần chạy và một lần chạy sau mỗi 30 phút, tức 48 lần mỗi ngày. Hãy thay cả hai bằng số liệu của bạn.

Ba cài đặt có thể thay đổi con số đó, đều dựa trên tài liệu của Hermes. Tác vụ được lên lịch chạy bằng mô hình đặt riêng cho tác vụ đó; nếu không có thì dùng cron.model; nếu vẫn không có thì dùng mô hình chính — vì vậy, hermes config set cron.model claude-haiku-4-5 sẽ chuyển mọi tác vụ chưa ghim mô hình khỏi nhóm mô hình đắt tiền. Nếu tập lệnh của tác vụ in ra {"wakeAgent": false}, tác vụ sẽ bỏ qua mô hình trong lần chạy đó; tác vụ không dùng agent thì không gọi mô hình. Các tác vụ phụ — nén, tạo tiêu đề, xử lý hình ảnh — chạy trên mô hình chính, trừ khi auxiliary định tuyến chúng sang nơi khác:

# ~/.hermes/config.yaml — what decides the cost of an unattended day
compression:
  threshold_tokens: 256000         # compact here, not at half of a 1M window

auxiliary:
  compression:
    provider: kunavo               # the named entry above
    model: claude-haiku-4-5        # summaries on the cheapest tier
  title_generation:
    provider: kunavo
    model: claude-haiku-4-5

threshold_tokens là cài đặt quan trọng khi dùng cửa sổ ngữ cảnh lớn. Theo mặc định, quá trình rút gọn bắt đầu khi đạt một nửa độ dài ngữ cảnh, còn tài liệu Hermes nêu cài đặt này là cách đặt mức trần cố định cho chi phí của một lần gọi.

Số giờ tác nhân thực sự hoạt động là nửa còn lại của hóa đơn, và ở đó bộ nhớ đệm quyết định chi phí. Xét 100 yêu cầu liên tiếp, mỗi yêu cầu gửi lại ngữ cảnh 100.000 token, kèm thêm 2.000 token mới và trả về 800 token đầu ra. Với Claude Sonnet 5, chi phí khoảng $2.31 khi ngữ cảnh được đọc từ bộ nhớ đệm, và khoảng $14.84 khi ngữ cảnh đó được tính phí như đầu vào mới trong mỗi yêu cầu. Cùng một khối lượng công việc, cùng một mô hình: khác biệt nằm ở việc có đặt các điểm ngắt hay không và các yêu cầu cách nhau dưới năm phút.

Để có cơ sở so sánh, đây là số liệu đo được chứ không phải giả định: trong các tài khoản Kunavo chạy agent luôn hoạt động, một ngày hoạt động ở mức trung vị có chi phí $12.67, còn một ngày ở phân vị thứ 90 có chi phí khoảng $163. Đây là các khoản được tính phí tính đến 5 tháng 10, 2026, theo mức giá có hiệu lực trong từng ngày. Nhóm này nhỏ, vì vậy hãy xem số liệu như độ rộng của khoảng giá trị, không phải dự báo cho agent của bạn.

Khi số dư cạn

Kunavo dùng hình thức trả trước: mọi lệnh gọi đều được thanh toán từ ví, và một agent hoạt động khi bạn ngủ sẽ làm cạn ví trong lúc bạn ngủ. Yêu cầu mà số dư ví không đủ chi trả sẽ bị từ chối với HTTP 402 và mã insufficient_balance trên cả hai giao thức; yêu cầu đó không bị tính phí. Việc từ chối xảy ra trước khi số dư ví về không: mỗi yêu cầu trước tiên tạm giữ một khoản bằng chi phí tối đa có thể phát sinh, gồm prompt cộng với câu trả lời dài nhất được phép tạo ra. Vì vậy, giới hạn đầu ra agent yêu cầu càng cao thì các lệnh gọi càng sớm bắt đầu bị từ chối. Lỗi cho biết số tiền còn thiếu qua balance_usd và needed_usd.

Khi nhà cung cấp gặp lỗi, Hermes Agent dùng một chuỗi phương án dự phòng: fallback_providers trong config.yaml, được quản lý bằng hermes fallback và thử lần lượt theo từng lượt. Tài liệu liệt kê giới hạn tốc độ, lỗi máy chủ, lỗi xác thực và lỗi 404 là các nguyên nhân kích hoạt chuỗi này cho mô hình chính; đồng thời nêu HTTP 402 trong số các lỗi về năng lực khiến tác vụ phụ chuyển xuống phương án tiếp theo trong chuỗi. Tài liệu không nói rõ một lượt sẽ xử lý thế nào khi gặp lỗi 402 mà không có phương án dự phòng. Hãy dự liệu theo cách hiểu trực tiếp: lượt đó thất bại, và tác vụ được lên lịch cũng vậy; đồng thời nhớ rằng lượt nào chuyển sang phương án dự phòng cũng bắt đầu với bộ nhớ đệm prompt trống.

Có hai thiết lập liên quan đến việc này, và mỗi thiết lập đảm nhiệm một việc khác nhau:

• Tự động nạp, trong Thanh toán. Lưu thẻ một lần và thiết lập ba con số: ngưỡng số dư để nạp thêm, số tiền nạp mỗi lần và hạn mức hàng tháng. Sau đó, ví sẽ được nạp lại trong vòng vài giây sau một lệnh gọi khiến số dư ở dưới ngưỡng, miễn là lần nạp không bị các giới hạn nạp tiền chặn lại; các giới hạn này gồm có hạn mức trừ tiền hàng tháng mà bạn đặt, số lần trừ tiền thẻ tối đa mỗi ngày, một khoảng chờ ngắn trước lần nạp tiếp theo và một khoảng chờ dài hơn sau một lần trừ tiền thẻ bị từ chối. Khi số dư ví không đủ cho một yêu cầu, Kunavo sẽ nạp tiền với cùng ngưỡng và cùng các giới hạn đó rồi thử lại yêu cầu thêm một lần trước khi phản hồi; nếu đang có một lần nạp diễn ra, yêu cầu sẽ chờ lần nạp đó trong vài giây. 402 vẫn được trả về khi không có lần nạp nào được thực hiện (ví dụ thẻ bị từ chối, đã chạm một giới hạn, hoặc số dư không thấp hơn ngưỡng), khi lần nạp đang diễn ra chưa vào ví trong vài giây đó, hoặc khi sau lần nạp, số dư ví vẫn không đủ cho khoản cần tạm giữ cho yêu cầu. Số dư được so với ngưỡng là số dư trước khi trừ đi các khoản đang được tạm giữ cho những yêu cầu và tác vụ đang chạy, vì vậy khi số dư không thấp hơn ngưỡng thì sẽ không có lần nạp nào, kể cả khi, sau khi trừ các khoản tạm giữ đó, phần còn lại không đủ cho yêu cầu tiếp theo. Cần có thẻ hoặc Link — không thể tự động tính phí qua Alipay, WeChat Pay, Pix và các phương thức thanh toán địa phương khác.
• Giới hạn hàng tháng cho khóa, trong Khóa API. Cấp cho tác nhân một khóa riêng và đặt mức chi tiêu tối đa mà khóa đó được phép sử dụng trong một tháng dương lịch. Khi vượt quá mức này, các lệnh gọi của khóa sẽ bị từ chối với 402 và không phát sinh khoản phí nào, trong khi các khóa khác của bạn vẫn hoạt động. Đây là mức trần cần thiết để ngăn vòng lặp chạy mất kiểm soát, điều mà ví không thể cung cấp vì mọi khóa đều dùng chung một ví.

Đặt ngưỡng nạp tiền cao hơn khoản tiền một yêu cầu tạm giữ, và chọn số tiền nạp dựa trên chi phí một ngày hoạt động của tác nhân, thay vì chọn mức tối thiểu: lần nạp nhỏ nhất là $10, còn chi phí trung vị cho một ngày hoạt động liên tục ở trên là $12.67. Các giới hạn của tính năng nạp tiền tự động được nêu trên trang thanh toán, còn toàn bộ nội dung lỗi có trên trang lỗi.

Hướng dẫn liên quan

• API tùy chỉnh của Hermes Agent — lý do nhà cung cấp đầu ra không phải là máy chủ API đầu vào, giải thích về trường transport và các bước kiểm tra cần thực hiện trong lần gọi đầu tiên.
• Chi phí Hermes Agent — chi phí vận hành ngoài giá mỗi token.
• Hết thời gian chờ khi nén ngữ cảnh Hermes — ý nghĩa của lỗi khi bộ tóm tắt bị treo và cách khôi phục.
• Hermes so với OpenClaw — và cách thiết lập tương tự cho agent còn lại trên trang OpenClaw.