kristianvast/hermes-claude-auth

hermes‑claude‑auth – Hermes AIエージェント向けのOAuthバイパス

何であるか

• Anthropicが2026‑04‑04にサーバーサイドのOAuth検証を導入した後、Claude Codeサブスクリプション（Max/Pro）を継続して使用できるようにする、非常に小さなPython専用パッチ。
• hermes‑agentのソースファイルを一切変更しない。代わりに、Python仮想環境の起動時にbuild_anthropic_kwargs関数をモニキーパッチするランタイムフック（.pthシム経由）をインストールする。

なぜ必要か

• このパッチがないと、hermes‑agentのOAuthフローは拒否され、Anthropicの「追加使用」（トークン課金）の請求にフォールバックするか、HTTP 400/401で失敗する。
• フックはClaude Codeが期待する正確な請求ヘッダー、システムプロンプトのレイアウト、ベータフラグ、およびユーザーエージェントのフィンガープリントを追加するため、リクエストは通常のサブスクリプション呼び出しとして扱われる。
• また、サブスクリプションウィンドウ対応の自動待機も追加：Claude Pro/Maxのクォータウィンドウ（5時間、1日、7日）が満了した場合、エージェントはウィンドウがリセットされるまで待機し、中断せずに再試行する。

動作方法（概要）

1. ブートストラップ – hermes venvのsite‑packagesに配置された.pthファイルが、インタプリタ起動時に小さなブートストラップモジュールをインポートする。
2. MetaPathFinderフック – ブートストラップはagent.anthropic_adapterのインポートを傍受し、build_anthropic_kwargsをパッチするフィンダを登録する。
3. 請求ヘッダー – SHA‑256署名付きのx-anthropic-billing-headerを計算し、最初のシステムメッセージとして挿入する。
4. システムプロンプトの再配置 – 非IDのシステムエントリを最初のユーザーメッセージ内の<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 – 1行コマンド：curl … | bash またはリポジトリをクローンして./install.shを実行。
• Windows – PowerShell 1行コマンド：irm … | iex またはクローンして. install.ps1を実行。
• インストーラーは自動的に：
  • hermesデータディレクトリ（$HERMES_HOMEまたはデフォルト）を検出。
  • anthropic_billing_bypass.pyを<hermes‑dir>/patches/にコピー。
  • .pthシムとブートストラップモジュールをhermes仮想環境内に配置。
  • OSの資格情報ストアからClaude Codeの資格情報を~/.claude/.credentials.jsonにミラーリング。
  • Linuxでhermes‑gateway.serviceが実行中であれば再起動。

アンインストール

• ./uninstall.sh（Linux/macOS）または. uninstall.ps1（Windows）を実行。--purge / -Purgeを指定すると、パッチファイルも削除される。

hermes update後の回復

• hermes updateは以前のsitecustomize.py（フックを保持していた）を上書きする可能性がある。このリポジトリは2つの防御策を提供する：
  1. リポジトリ外に配置されたGitフック（core.hooksPath経由）がマージ後にインストーラーを再実行する。
  2. Hermesゲートウェイが起動中の間、15分ごとにローダーを復元するcronスタイルのウォッチドッグ（restore_loader.sh）。
• インストーラーは--post-updateおよび--checkフラグも提供し、パッチファイルがリポジトリと一致しているか確認し、欠落したローダーを復元できる。

検証 インストール後、Hermesゲートウェイログに以下の行が表示されるべきです：

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

以下の成功したチャットコマンドがextra usageやHTTP 400エラーなしで完了するはずです：

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

互換性

• hermes‑agent ≥ Python 3.11、Linux/macOS/Windows。
• 複数のhermesプロファイルに対応。パッチはデータルートにあり、共有される。
• 内部関数build_anthropic_kwargs(is_oauth=…)に依存。hermes‑agentがこのシグネチャを変更した場合、パッチも更新が必要。

主なポイント

• ソースコードの変更なし – すべての変更はインポートフックによるランタイム適用。
• OAuth検証とサブスクリプションウィンドウの制限の両方を処理し、ハードフェイルをスムーズな待機・再試行に変換。
• 自己修復 – Gitフック + cron回復により、hermes更新後もバイパスが維持される。

---

上記のすべての詳細はリポジトリのREADMEから直接取得；追加機能は推測されていない。