API tùy chỉnh Hermes Agent: provider, phương thức truyền tải và kiểm tra lần gọi đầu tiên

Hermes Agent custom endpoint được cấu hình outbound, dưới dạng một mục có tên bên dưới providers: trong ~/.hermes/config.yaml, trong đó api là base URL và transport là giao thức truyền tải. Đây là một khái niệm khác với API server của Hermes, vốn trỏ theo hướng ngược lại. Cả hai đều được gọi là “Hermes custom API” trong kết quả tìm kiếm, và các trang tài liệu chính thức của mỗi loại đều xếp hạng cho cùng truy vấn — vì vậy hãy xác định đúng hướng trước.

Trang này nói về Hermes Agent, agent mã nguồn mở của Nous Research. Kiểm tra GitHub API ngày 21 tháng 9 năm 2026 trả về archived: false, disabled: false, giấy phép MIT và một lần push trong cùng ngày; bản phát hành mới nhất được công bố là Hermes Agent v0.21.3, gắn thẻ v2026.9.14 ngày 14 tháng 9 năm 2026, không phải bản prerelease. Các bề mặt mà trang này lấy cấu hình là repository đó và hermes-agent.nousresearch.com. hermes-agent.org nói về cùng dự án nhưng từ một domain bên ngoài nousresearch.com và tải analytics Microsoft Clarity (đã kiểm tra ngày 21 tháng 9 năm 2026); đó không phải bề mặt chính thức của dự án, vì vậy không lấy cấu hình từ đó. Đây cũng không phải Hermes 3 hay Hermes 4, dòng model open-weight của Nous, và không phải JavaScript engine cùng tên.

Hai khái niệm trái ngược cùng được gọi là Hermes custom API

Cả hai dòng đều được trích từ các trang riêng của Hermes, đọc ngày 21 tháng 9 năm 2026: tài liệu tham chiếu provider và trang API server. Có một điểm đặt tên cần kiểm tra trong bản cài đặt của bạn: trang API server ghi hermes gateway là lệnh chạy server, trong khi tài liệu tham chiếu CLI mô tả hermes gateway là trình quản lý messaging service với các subcommand run, start, stop và status. Hãy chạy hermes gateway --help thay vì đoán. Toàn bộ phần dưới đây nói về phía outbound.

Cấu hình outbound tối thiểu

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com/v1   # aliases accepted: base_url, url
    key_env: KUNAVO_API_KEY          # or inline api_key:, or key_cmd:
    transport: chat_completions      # set it by hand; see the transport section
    models:
      claude-sonnet-5:
        prompt_caching: true

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

KUNAVO_API_KEY=your-key

Theo từng trường, dựa trên tài liệu tham chiếu provider: config key là providers.<name>, trường base URL là api (chấp nhận base_url và url làm alias), credential là key_env, một api_key inline hoặc một key_cmd, và protocol là transport. Mục này cũng chấp nhận name, default_model, models, context_length, discover_models, extra_body, extra_headers, session_affinity_header, ssl_ca_cert / ssl_verify, catalog_provider và enabled: false. Chọn mục bằng model.provider: custom:kunavo, hoặc giữa phiên bằng /model custom:kunavo:<model-id>.

Hai lệnh này không thể thay thế cho nhau. hermes model, chạy bên ngoài phiên trò chuyện, là trình hướng dẫn thiết lập provider đầy đủ và là cách duy nhất có thể thêm provider hoặc nhận key. /model bên trong phiên chỉ chuyển đổi giữa những gì đã tồn tại. Với các enterprise endpoint cấp token thời hạn ngắn, key_cmd là lệnh in token ra stdout — ở dạng thuần hoặc JSON với trường access_token — Hermes sẽ chạy và cache token này cho đến ngay trước khi hết hạn; cách này tốt hơn api_key hoặc key_env tĩnh trong cùng mục.

Chọn transport thủ công thay vì để trống trường

Tài liệu tham chiếu provider liệt kê ba giá trị được chấp nhận cho transport trong một mục custom. Tài liệu cũng nói rằng trình hướng dẫn hermes model Custom Endpoint hiện yêu cầu chỉ rõ protocol và lưu câu trả lời vào config.yaml, đồng thời tự động phát hiện dựa trên URL “vẫn được thực hiện như phương án dự phòng khi trường bị bỏ trống”. Quy tắc phát hiện duy nhất được nêu rõ là đường dẫn /anthropic ánh xạ tới anthropic_messages, còn base URL của Kunavo không khớp; phần còn lại của heuristic không được liệt kê trên bất kỳ trang nào đã đọc ở đây, đó là lý do nên ghi trường này thay vì suy đoán kết quả. Kunavo cung cấp /v1/chat/completions, /v1/messages và /v1/responses, vì vậy về lý thuyết mỗi transport đều có route tương ứng.

Dòng Anthropic cần được nêu kèm lưu ý thay vì đưa ra câu trả lời chắc chắn. Hướng dẫn Azure Foundry của Hermes nói rằng /v1 bị loại khỏi URL cơ sở vì Anthropic SDK nối /v1/messages vào mọi yêu cầu — nhưng câu này nằm dưới tiêu đề Azure, còn ví dụ riêng của tài liệu tham chiếu nhà cung cấp (api: https://proxy.example.com/anthropic) không nói Hermes nối hậu tố nào cho một proxy thông thường. Vì vậy cả hai phương án ở trên đều có thể đúng và một trong hai có thể gây lỗi 404 do /v1 bị lặp. Hãy kiểm tra đường dẫn yêu cầu mà lần gọi đầu tiên thực sự ghi nhận; tài liệu về URL cơ sở giải thích sự nhầm lẫn giữa địa chỉ gốc và địa chỉ có /v1, vốn gây ra phần lớn lỗi 404 trên giao thức này. Xác thực là mối lo nhỏ hơn: tuyến Messages của Kunavo chấp nhận cả Authorization: Bearer và x-api-key, vì vậy dù Anthropic SDK gửi tiêu đề nào cho một proxy thông thường thì tiêu đề đó cũng có lẽ sẽ được chấp nhận — nhưng Hermes không ghi rõ lựa chọn đó, nên “có lẽ” là cách nói trung thực.

Một câu hỏi mở khác mà trang này cũng không thể trả lời. Hermes ghi nhận việc tự động nâng cấp tên model thuộc họ GPT-5.x lên codex_responses ngay cả khi config.yaml vẫn là chat_completions — nhưng câu này xuất hiện dưới provider: azure-foundry trong khi được diễn đạt như một cơ chế phát hiện tên model. Việc một GPT slug trên provider: custom có kích hoạt chuyển đổi tương tự hay không chưa được tài liệu hóa. Nếu chọn model lớp GPT, hãy ghi lại route mà lần gọi đầu tiên đã đi qua.

Những gì custom endpoint không tự động có được, theo từng transport

Không mục nào trong số này là giới hạn của gói. Theo FAQ trên trang chủ của dự án, Hermes Agent “miễn phí và mã nguồn mở theo giấy phép MIT”, còn dict providers: được tài liệu hóa như cấu hình thông thường chứ không phải tính năng theo cấp. Đây là các giới hạn về khả năng, và chúng khác nhau theo từng giao thức.

Có hai tùy chọn xử lý riêng cho cổng kết nối. catalog_provider chấp nhận ID nhà cung cấp Hermes hoặc ID models.dev và cho phép các mô hình trong mục cấu hình kế thừa siêu dữ liệu của danh mục đó — chỉ dùng để tra cứu, các yêu cầu vẫn được gửi đến URL api của bạn bằng khóa của bạn. Còn discover_models: false bỏ qua hoàn toàn bước thăm dò /models và chỉ sử dụng các mô hình bạn đã liệt kê trong mục cấu hình; đây là cách khắc phục khi quá trình khám phá mô hình trả về nhiều thông tin nhiễu hoặc diễn ra chậm. Việc phản hồi /v1/models của Kunavo có đáp ứng bước thăm dò của Hermes hay không chưa được kiểm thử ở đây; nếu không đáp ứng, quá trình phát hiện kích thước ngữ cảnh sẽ chuyển sang giá trị mặc định 128K đó. Phần giải thích về chi phí đằng sau các thiết lập này — các vị trí phụ trợ, tiến trình thực thi được ủy nhiệm và tính liên tục của bộ nhớ đệm — nằm trên trang Giá Hermes Agent thay vì được lặp lại ở đây.

Quy trình xác minh cần chạy trước khi chuyển sang công việc thật

Đây là các bước để bạn tự chạy cùng kết quả cần quan sát, không phải kết quả Kunavo đã thu được. Chưa có lần chạy Hermes nào với Kunavo, chưa có hướng dẫn thiết lập Kunavo cho Hermes, và không nên đọc bất kỳ nội dung nào trên trang này như một tích hợp đã được kiểm thử. Hãy duy trì route đang hoạt động trong suốt quá trình.

1. Thêm provider, sau đó chẩn đoán. hermes model thêm provider; hermes doctor được ghi nhận là chẩn đoán các vấn đề về cấu hình và dependency, còn tài liệu tham chiếu CLI ghi lại hai kiểm tra cấu hình custom endpoint mà nó thực hiện — một key custom_providers không phải YAML list và một mục list cũ không có mục providers: tương ứng. Cả hai chỉ cảnh báo và --fix không tự sửa chúng.
2. Xác nhận key đã được tải trước khi phát sinh chi phí. hermes dump in ra bản tóm tắt thiết lập có thể sao chép-dán — version, provider, model và việc API key có hiện diện hay không. Hãy kỳ vọng model id của bạn và trạng thái key là hiện diện. hermes prompt-size chạy offline và báo cáo phân bổ byte của system prompt cùng tool schema; đây là phần cố định mà mỗi lượt đều mang theo trước mọi nội dung hội thoại.
3. Một lượt văn bản không streaming. Hãy kỳ vọng có phản hồi và request đã đi đến path bạn dự định. Custom endpoint “hoạt động” nhưng trả về dữ liệu rác là một trường trong bảng xử lý sự cố quickstart của Hermes; bảng này nêu base URL sai, tên model sai hoặc endpoint thực tế không tương thích với OpenAI, đồng thời yêu cầu xác minh endpoint trước bằng một client riêng.
4. Một lượt truyền trực tuyến. Hãy chờ đầu ra gia tăng thay vì một khối duy nhất ở cuối. Trang này chưa kiểm tra việc khung truyền của một endpoint cụ thể có đáp ứng khả năng phân tích tiến trình của Hermes hay không.
5. Một vòng gọi công cụ. Hãy chờ công cụ thực thi. Nếu lệnh gọi được in dưới dạng văn bản thay vì vậy, đó là vấn đề về khả năng hỗ trợ gọi công cụ của phía cung cấp dịch vụ, không phải của giao thức truyền tải.
6. Đọc đồng hồ đo. /usage là bảng token, chi phí và ngữ cảnh trong phiên. Hãy đối chiếu nó với khoản phí mà tài khoản nhà cung cấp của bạn thực sự ghi nhận — phép tính riêng của tác nhân dựa trên số token được báo cáo chỉ là ước tính, không phải sổ cái. Xem tài liệu về mức sử dụng.

Chi phí của toàn bộ chuỗi cấp độ và chi phí của việc chuyển đổi giữa phiên

Giả sử sáu bước ở trên gửi tổng cộng 26.000 token đầu vào và nhận tổng cộng 1.150 token đầu ra — một prompt hệ thống cố định và lược đồ công cụ trong mỗi lần gọi trong số ba lần gọi, cộng với một kết quả công cụ được gửi lại một lần. Đây chỉ là giả định minh họa; hermes prompt-size báo cáo prompt cố định của bạn dưới dạng phân rã theo byte, gần với thực tế hơn một con số mà trang này có thể phỏng đoán. Mức giá là giá hiện hành trong catalog Kunavo trên mỗi triệu token.

Đây là phép tính token minh họa theo mức giá trong catalog, không phải tác vụ Hermes được đo lường và không phải mức trần hóa đơn. Phép tính không bao gồm việc ghi bộ nhớ đệm, công cụ bên ngoài và thuế. Ý nghĩa của con số này nằm ở sự nhỏ bé của nó: xác minh một tuyến tốn ít hơn nhiều so với việc phát hiện cấu hình sai sau một tuần chạy tác vụ theo lịch.

Con số thứ hai là con số mà lệnh /model che giấu. Bộ nhớ đệm prompt được lập khóa theo mô hình phục vụ yêu cầu, vì vậy bất kỳ thay đổi mô hình nào giữa cuộc trò chuyện cũng khiến tin nhắn tiếp theo đọc lại toàn bộ cuộc trò chuyện theo giá đầu vào đầy đủ thay vì mức giá đọc từ bộ nhớ đệm, điều mà Hermes mô tả là rẻ hơn khoảng 75 đến 90 phần trăm. Với một cuộc trò chuyện 120.000 token và Claude Sonnet 5, chênh lệch giữa $1,40 trên mỗi triệu token và mức đọc bộ nhớ đệm $0,14 là khoảng $0,151 cho một lượt đó — một lần thì không đáng kể, nhưng lặp lại thường xuyên thì không. Khoản tiền trong catalog của Kunavo là mức sàn thanh toán chứ không phải mức trần: khi upstream báo phí, hóa đơn là giá trị lớn hơn giữa chi phí theo catalog và chi phí upstream nhân với phần tăng giá áp dụng. Mức tối thiểu là khoản nạp trả trước trị giá $10, không có gói thuê bao. Xem thanh toán.

Hoàn tác cấu hình

Hermes có tài liệu mô tả đường dẫn hoàn tác, đó là lý do việc dùng thử có rủi ro thấp. enabled: false trong mục cấu hình sẽ ẩn nó mà không xóa. Các bản sao tại thời điểm cụ thể của config.yaml được ghi vào backups/config/config.yaml.<reason>.<timestamp> trước khi hermes setup hoặc hermes migrate ghi đè lên nó và mỗi khi tệp được phân tích, các bản sao trùng hệt được bỏ qua và chỉ giữ lại năm bản mới nhất cho mỗi lý do; nếu sau đó tệp không thể phân tích, Hermes sẽ cung cấp bản sao tốt mới nhất thay vì giá trị mặc định tích hợp. Tài liệu tham chiếu cấu hình cũng chú thích model.base_url là “được xóa khi chuyển nhà cung cấp”, vì vậy việc chuyển lại sang nhà cung cấp tích hợp được ghi nhận là xóa URL cơ sở cũ thay vì để nó trong tệp — hãy kiểm tra giá trị đã ghi sau đó, đừng mặc định rằng nó đã được xử lý.

Ba bẫy này xuất phát từ các hướng dẫn cũ. Danh sách custom_providers: cấp cao nhất cũ vẫn hoạt động và hermes update tự động di chuyển nó vào từ điển providers:, trong đó model cũ trở thành default_model và api_mode cũ trở thành transport. LLM_MODEL trong .env đã bị xóa hoàn toàn — config.yaml là nguồn sự thật duy nhất. Và OPENAI_BASE_URL được hai trang chính thức hiện hành mô tả theo hai cách: tài liệu tham chiếu nhà cung cấp nói rằng nó chỉ được áp dụng cho nhà cung cấp openai-api, trong khi tài liệu tham chiếu biến môi trường liệt kê nó là URL cơ sở cho một endpoint tùy chỉnh. Mâu thuẫn này chưa được giải quyết, vì vậy hãy cấu hình endpoint trong config.yaml và đừng dựa vào biến môi trường đó làm tuyến.

Nếu bạn đang chọn nhà cung cấp thay vì kết nối một nhà cung cấp, API tương thích với OpenAI trình bày phạm vi mà bề mặt tương thích hỗ trợ và không hỗ trợ, còn Hermes so với OpenClaw so sánh hai tác nhân. Khi sẵn sàng kiểm thử tuyến này bằng khóa đã nạp tiền, hãy tạo tài khoản Kunavo.

Câu hỏi thường gặp

Tài liệu Hermes Agent — tài liệu tham chiếu nhà cung cấp, trang máy chủ API, trang cấu hình mô hình, trang cấu hình, tài liệu tham chiếu CLI, tài liệu tham chiếu lệnh gạch chéo, hướng dẫn bắt đầu nhanh và trang chủ dự án — được đọc vào ngày 21 tháng 9 năm 2026. Trạng thái kho lưu trữ và bản phát hành mới nhất được đối chiếu với API GitHub cùng ngày. Ba tuyến API của Kunavo được xác nhận trong mã nguồn của chính Kunavo. Mọi con số đô la đều là phép tính token minh họa theo mức giá trực tiếp trong catalog, không phải chi phí của một tác vụ được đo lường. Cấu hình Hermes được báo cáo từ các tài liệu nguồn; chưa thực hiện lần chạy Hermes nào với Kunavo.