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；未推断任何额外功能。