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. When one key hits a rate limit or billing quota, Hermes automatically rotates to the next healthy key — keeping your session alive without switching providers.

Điều này khác với fallback providers, vốn 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 (requires Claude Max plan + extra usage credits)
Hermes auth add Anthropic --type OAuth
# Opens browser for OAuth login

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

``` bash
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:

`bash
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ệnh | Mô tả |
|----------|-------------|
| 
`Hermes auth
` | Thuật sĩ quản lý hồ bơi tương tác |
| 
`Hermes auth list
` | Hiể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 OAuth
` | Thê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

:

``` yaml
credential_pool_strategies:
  OpenRouter: round_robin
  Anthropic: least_used

`

| Chiến lược | Hà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_robin
` | Chuyển qua các phím một cách đồng đều, xoay vòng sau mỗi lần chọn |
| 
`least_used
` | Luôn chọn khóa có số lượng yêu cầu thấp nhất |
| 
`random
` | Lự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ỗi | Hành vi | Thời gian hồi chiêu |
|-------|----------|----------|
| **Giới hạn tỷ lệ 429** | Thử 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 theo | 1 giờ |
| **Thanh toán 402/Hạn ngạch** | Xoay ngay sang phím tiếp theo | 24 giờ |
| **401 Xác thực đã hết hạn** | Trướ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ết** | Chuyể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

Custom OpenAI-compatible endpoints (Together.ai, RunPod, local servers) get their own pools, keyed by the endpoint name from 
`custom_providers
` in 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.

`bash

# 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
` trong 
`credential_pool
` với tiền tố 
`custom:

:

``` json
{
  "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ồn | Ví dụ | Tự động gieo hạt? |
|--------|----------|-------------|
| Biến môi trường |

OpenRouter_API_KEY

, 
`Anthropic_API_KEY
` | Có |
| Mã thông báo OAuth (auth.JSON) | Mã thiết bị Codex, mã thiết bị Nous | Có |
| Thông tin đăng nhập Mã Claude |

~/.Claude/.credentials.JSON
` | Có (Anthropic) |
| Hermes PKCE OAuth |

~/.Hermes/auth.JSON
` | Có (Anthropic) |
| Cấu hình điểm cuối tùy chỉnh |

model.API_key
` trong config.yaml | Có (điểm cuối tùy chỉnh) |
| Nhập thủ công | Đã thêm qua 
`Hermes auth add
` | Kiê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 [XPROTECTX48XPROTECTX](https://excalidraw.com/#JSON=2Ycqhqpi6f12E_3ITyiwh,c7u9jSt5BwrmiVzHGbm87g) 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

:

``` json
{
  "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

):

`YAML
credential_pool_strategies:
  OpenRouter: round_robin
  Anthropic: least_used

`