kristianvast/hermes-claude-auth

hermes‑claude‑auth – Hermes AI 代理的 OAuth 繞過方案

是什麼

• 一個極小的純 Python 補丁，可在 Anthropic 於 2026‑04‑04 引入伺服器端 OAuth 驗證後，讓 hermes‑agent（一個開源的基於 Claude 的聊天機器人/助手）繼續使用 Claude Code 訂閱（Max/Pro）。
• 它不修改任何 hermes‑agent 源碼。而是透過一個 .pth 沙盒，在 hermes 虛擬環境啟動時立即安裝一個 執行時鈎子，對 build_anthropic_kwargs 函數進行猴子補丁。

為何你需要它

• 沒有此補丁，hermes‑agent 的 OAuth 流程將被拒絕，請求會回退到 Anthropic 的「額外使用」（按令牌計費）計費模式，或直接因 HTTP 400/401 錯誤失敗。
• 該鈎子添加了 Claude Code 所期望的精確計費頭、系統提示佈局、Beta 標誌和使用者代理指紋，使請求被視為正常的訂閱呼叫。
• 它還添加了 訂閱視窗感知的自動等待：當 Claude Pro/Max 配額視窗（5 小時、1 天、7 天）耗盡時，代理將休眠直至視窗重置，而不是直接中止。

工作原理（概覽）

1. 引導 – 將一個 .pth 檔案放置在 hermes 虛擬環境的 site‑packages 中，該檔案在解釋器啟動時導入一個微型引導模組。
2. MetaPathFinder 鈎子 – 引導模組註冊一個查找器，攔截 agent.anthropic_adapter 的匯入，並修補 build_anthropic_kwargs。
3. 計費頭 – 計算一個 SHA‑256 簽名的 x-anthropic-billing-header，並作為第一個系統訊息注入。
4. 系統提示重定位 – 將非身份相關的系統項目移至第一個使用者訊息內的 <system‑reminder> 塊中（Claude Code 期望的格式）。
5. 速率限制自動等待 – 在收到 HTTP 429 時，鈎子讀取 Anthropic 的 anthropic‑ratelimit‑unified‑*‑reset 頭，選擇最長的視窗，休眠（每視窗有上限）並透明重試。
6. 指紋一致性 – 強制 user‑agent 和計費頭報告相同的 Claude Code 版本（2.1.112 或本地檢測到的版本），並設定 x‑app: cli，以防止 Anthropic 將請求視為「額外使用」。

安裝

• Linux/macOS – 一行命令：curl … | bash 或克隆倉儲後執行 ./install.sh。
• Windows – PowerShell 一行命令：irm … | iex 或克隆後執行 . install.ps1。
• 安裝程式會自動：
  • 檢測 hermes 資料目錄（$HERMES_HOME 或預設值）。
  • 將 anthropic_billing_bypass.py 複製到 <hermes‑dir>/patches/。
  • 將 .pth 沙盒和引導模組放置在 hermes 虛擬環境內。
  • 將 Claude Code 憑證從作業系統憑證儲存鏡像至 ~/.claude/.credentials.json。
  • 若 Linux 上的 hermes‑gateway.service 正在執行，則重新啟動它。

卸載

• 執行 ./uninstall.sh（Linux/macOS）或 . uninstall.ps1（Windows）。使用 --purge / -Purge 可同時刪除補丁檔案。

hermes update 後的恢復

• hermes update 可能會清除之前保存鈎子的 sitecustomize.py。本倉儲安裝了兩種防禦措施：
  1. Git 鈎子：放置在倉儲外（core.hooksPath）的鈎子，在合併後重新執行安裝程式。
  2. cron 風格的看門狗（restore_loader.sh）：只要 Hermes 網關運行，每 15 分鐘恢復一次載入器。
• 安裝程式還提供 --post-update 和 --check 標誌，用於驗證補丁檔案是否與倉儲匹配，並恢復遺失的載入器。

驗證 安裝後，你應該在 Hermes 網關日誌中看到類似以下內容：

[anthropic_billing_bypass] Bypass installed
[anthropic_billing_bypass] Rate‑limit auto‑wait installed

成功的聊天命令，例如：

hermes chat --provider anthropic -m claude‑sonnet‑4‑6 -q "OK" -Q

應能順利完成，且無 extra usage 或 HTTP 400 錯誤。

相容性

• hermes‑agent ≥ Python 3.11，支援 Linux/macOS/Windows。
• 支援多個 hermes 配置檔；補丁位於資料根目錄，可共用。
• 依賴內部函數 build_anthropic_kwargs(is_oauth=…)；若 hermes‑agent 更改該簽名，補丁需更新。

關鍵要點

• 無原始碼修改 – 所有變更均透過匯入鈎子在執行時應用。
• 同時處理 OAuth 驗證和訂閱視窗限流，將硬性失敗轉化為優雅的等待與重試。
• 自愈能力 – Git 鈎子 + cron 恢復機制確保在 hermes 更新後補丁仍有效。

---

以上所有細節均直接來自倉儲的 README；未推斷任何額外功能。