Chuyển tới nội dung chính

Nhóm thông tin xác thực

Nhóm thông tin xác thực cho phép bạn đăng ký nhiều khóa API hoặc mã thông báo OAuth cho cùng một nhà cung cấp. Khi một khóa đạt đến giới hạn tốc độ hoặc hạn ngạch thanh toán, Hermes sẽ tự động chuyển sang khóa lành mạnh tiếp theo — duy trì phiên của bạn mà không cần chuyển đổi nhà cung cấp.

Điều này khác với nhà cung cấp dự phòng, chuyển sang một nhà cung cấp khác hoàn toàn. Nhóm thông tin xác thực được luân chuyển cùng một nhà cung cấp; nhà cung cấp dự phòng là nhà cung cấp chuyển đổi dự phòng chéo. Các nhóm được thử trước tiên — nếu tất cả các khóa nhóm đã hết, sau đó nhà cung cấp dự phòng sẽ kích hoạt.

Nó hoạt động như thế nào

Your request
  → Pick key from pool (round_robin / least_used / fill_first / random)
  → Send to provider
  → 429 rate limit?
      → Retry same key once (transient blip)
      → Second 429 → rotate to next pool key
      → All keys exhausted → fallback_model (different provider)
  → 402 billing error?
      → Immediately rotate to next pool key (24h cooldown)
  → 401 auth expired?
      → Try refreshing the token (OAuth)
      → Refresh failed → rotate to next pool key
  → Success → continue normally

Bắt đầu nhanh

Nếu bạn đã đặt khóa API trong .env , Hermes sẽ tự động phát hiện khóa đó dưới dạng nhóm 1 khóa. Để hưởng lợi từ việc gộp chung, hãy thêm nhiều khóa hơn:

# Add a second OpenRouter key
hermes auth add openrouter --api-key sk-or-v1-your-second-key

# Add a second Anthropic key
hermes auth add anthropic --type api-key --api-key sk-ant-api03-your-second-key

# Add an Anthropic OAuth credential (Claude Code subscription)
hermes auth add anthropic --type oauth
# Opens browser for OAuth login

Kiểm tra hồ bơi của bạn:

hermes auth list

Đầu ra:

openrouter (2 credentials):
  #1  OPENROUTER_API_KEY   api_key env:OPENROUTER_API_KEY ←
  #2  backup-key           api_key manual

anthropic (3 credentials):
  #1  hermes_pkce          oauth   hermes_pkce ←
  #2  claude_code          oauth   claude_code
  #3  ANTHROPIC_API_KEY    api_key env:ANTHROPIC_API_KEY

← đánh dấu thông tin xác thực hiện được chọn.

Quản lý tương tác

Chạy hermes auth không có lệnh phụ cho trình hướng dẫn tương tác:

hermes auth

Điều này hiển thị trạng thái nhóm đầy đủ của bạn và cung cấp một menu:

What would you like to do?
  1. Add a credential
  2. Remove a credential
  3. Reset cooldowns for a provider
  4. Set rotation strategy for a provider
  5. Exit

Đối với các nhà cung cấp hỗ trợ cả khóa API và OAuth (Anthropic, Nous, Codex), quy trình thêm sẽ hỏi loại nào:

anthropic supports both API keys and OAuth login.
  1. API key (paste a key from the provider dashboard)
  2. OAuth login (authenticate via browser)
Type [1/2]:

Lệnh CLI

LệnhMô tả
hermes authThuật sĩ quản lý hồ bơi tương tác
hermes auth listHiển thị tất cả các nhóm và thông tin đăng nhập
hermes auth list <provider>Hiển thị nhóm nhà cung cấp cụ thể
hermes auth add <provider>Thêm thông tin xác thực (nhắc về loại và khóa)
hermes auth add <provider> --type api-key --api-key <key>Thêm khóa API không tương tác
hermes auth add <provider> --type oauthThêm thông tin xác thực OAuth thông qua đăng nhập trình duyệt
hermes auth remove <provider> <index>Xóa thông tin xác thực theo chỉ mục dựa trên 1
hermes auth reset <provider>Xóa tất cả trạng thái hồi chiêu/kiệt sức

Chiến lược luân chuyển

Định cấu hình qua hermes auth → "Đặt chiến lược xoay vòng" hoặc trong config.yaml :

credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used

Chiến lượcHành vi
fill_first (mặc định)Sử dụng phím lành mạnh đầu tiên cho đến khi hết thì chuyển sang phím tiếp theo
round_robinChuyển qua các phím một cách đồng đều, xoay vòng sau mỗi lần chọn
least_usedLuôn chọn khóa có số lượng yêu cầu thấp nhất
randomLựa chọn ngẫu nhiên trong số các phím khỏe mạnh

Khôi phục lỗi

Nhóm xử lý các lỗi khác nhau theo cách khác nhau:

LỗiHành viThời gian hồi chiêu
Giới hạn tỷ lệ 429Thử lại cùng một khóa một lần (tạm thời). Thứ hai liên tiếp 429 quay sang phím tiếp theo1 giờ
Thanh toán 402/Hạn ngạchXoay ngay sang phím tiếp theo24 giờ
401 Xác thực đã hết hạnTrước tiên hãy thử làm mới mã thông báo OAuth. Chỉ xoay nếu làm mới không thành công—
Tất cả các phím đã hếtChuyển sang fallback_model nếu được định cấu hình—

Cờ has_retried_429 đặt lại trên mỗi lệnh gọi API thành công, do đó, một lệnh 429 tạm thời sẽ không kích hoạt xoay vòng.

Nhóm điểm cuối tùy chỉnh

Các điểm cuối tương thích với OpenAI tùy chỉnh (Together.ai, RunPod, máy chủ cục bộ) có nhóm riêng, được khóa bằng tên điểm cuối từ custom_providers trong config.yaml.Khi bạn thiết lập điểm cuối tùy chỉnh thông qua hermes model , nó sẽ tự động tạo một tên như "Together.ai" hoặc "Local (localhost:8080)". Tên này trở thành chìa khóa nhóm.

# After setting up a custom endpoint via hermes model:
hermes auth list
# Shows:
#   Together.ai (1 credential):
#     #1  config key    api_key config:Together.ai ←

# Add a second key for the same endpoint:
hermes auth add Together.ai --api-key sk-together-second-key

Nhóm điểm cuối tùy chỉnh được lưu trữ trong auth.json bên dưới credential_pool với tiền tố custom::

{
  "credential_pool": {
    "openrouter": [...],
    "custom:together.ai": [...]
  }
}

Tự động phát hiện

Hermes tự động phát hiện thông tin xác thực từ nhiều nguồn và tạo nhóm khi khởi động:

NguồnVí dụTự động gieo hạt?
Biến môi trườngOPENROUTER_API_KEY , ANTHROPIC_API_KEYCó
Mã thông báo OAuth (auth.json)Mã thiết bị Codex, mã thiết bị NousCó
Thông tin đăng nhập Mã Claude~/.claude/.credentials.jsonCó (Anthropic)
Hermes PKCE OAuth~/.hermes/auth.jsonCó (Anthropic)
Cấu hình điểm cuối tùy chỉnhmodel.api_key trong config.yamlCó (điểm cuối tùy chỉnh)
Nhập thủ côngĐã thêm qua hermes auth addKiên trì trong auth.json

Các mục nhập được gieo hạt tự động được cập nhật trên mỗi lần tải nhóm — nếu bạn xóa một biến env, mục nhập nhóm của nó sẽ tự động được cắt bớt. Các mục nhập thủ công (được thêm qua hermes auth add ) không bao giờ được tự động cắt bớt.

Phân quyền & Chia sẻ đại lý phụ

Khi tác nhân sinh ra các tác nhân phụ thông qua delegate_task , nhóm thông tin xác thực của tác nhân gốc sẽ tự động được chia sẻ với trẻ em:

  • Cùng một nhà cung cấp — đứa trẻ nhận được toàn bộ quỹ của cha mẹ, cho phép xoay vòng khóa theo giới hạn tỷ lệ
  • Nhà cung cấp khác — con tải nhóm riêng của nhà cung cấp đó (nếu được định cấu hình)
  • Không có nhóm nào được định cấu hình — thành phần con quay lại sử dụng khóa API duy nhất được kế thừa

Điều này có nghĩa là các tác nhân phụ được hưởng lợi từ khả năng phục hồi giới hạn tỷ lệ giống như tác nhân gốc mà không cần cấu hình bổ sung. Cho thuê thông tin xác thực theo từng nhiệm vụ đảm bảo trẻ em không xung đột với nhau khi xoay phím đồng thời.

An toàn chủ đề

Nhóm thông tin xác thực sử dụng khóa luồng cho tất cả các đột biến trạng thái ( select() , mark_exhausted_and_rotate() , try_refresh_current() , mark_used() ). Điều này đảm bảo truy cập đồng thời an toàn khi cổng xử lý nhiều phiên trò chuyện cùng một lúc.

Kiến trúc

Để biết sơ đồ luồng dữ liệu đầy đủ, hãy xem docs/credential-pool-flow.excalidraw trong kho lưu trữ.

Nhóm thông tin xác thực tích hợp ở lớp phân giải của nhà cung cấp:

  1. ** agent/credential_pool.py ** — Trình quản lý nhóm: lưu trữ, lựa chọn, xoay vòng, thời gian hồi chiêu
  2. ** hermes_cli/auth_commands.py ** — Lệnh CLI và trình hướng dẫn tương tác
  3. ** hermes_cli/runtime_provider.py ** — Độ phân giải thông tin xác thực nhận biết nhóm
  4. ** run_agent.py ** — Khôi phục lỗi: 429/402/401 → xoay nhóm → dự phòng

Lưu trữ

Trạng thái nhóm được lưu trữ trong ~/.hermes/auth.json dưới khóa credential_pool:

{
  "version": 1,
  "credential_pool": {
    "openrouter": [
      {
        "id": "abc123",
        "label": "OPENROUTER_API_KEY",
        "auth_type": "api_key",
        "priority": 0,
        "source": "env:OPENROUTER_API_KEY",
        "access_token": "sk-or-v1-...",
        "last_status": "ok",
        "request_count": 142
      }
    ]
  },
}

Các chiến lược được lưu trữ trong config.yaml (không phải auth.json ):

credential_pool_strategies:
  openrouter: round_robin
  anthropic: least_used