kristianvast/hermes-claude-auth

hermes‑claude‑auth – Hermes AI 에이전트를 위한 OAuth 우회

무엇인가요

Anthropic이 2026‑04‑04에 서버 측 OAuth 검증을 도입한 후에도 Claude Code 구독 (Max/Pro)을 계속 사용할 수 있게 해주는 매우 작은 Python 전용 패치입니다.
hermes‑agent 소스 파일을 전혀 수정하지 않습니다. 대신, hermes 가상 환경이 시작될 때 build_anthropic_kwargs 함수를 모니키 패치하는 런타임 훅(.pth 쉴드를 통해)을 설치합니다.

왜 필요할 수 있나요

이 패치 없이 hermes‑agent의 OAuth 흐름은 거부되며, 요청은 Anthropic의 "추가 사용"(토큰당 과금) 요금제로 대체되거나 HTTP 400/401 오류로 실패합니다.
훅은 Claude Code가 기대하는 정확한 요금 청구 헤더, 시스템 프롬프트 레이아웃, 베타 플래그, 사용자 에이전트 지문을 추가하여 요청이 일반 구독 호출로 처리되도록 합니다.
또한 구독 윈도우 인식 자동 대기도 추가: Claude Pro/Max 할당량 윈도우(5시간, 1일, 7일)가 소진되면 에이전트는 윈도우가 재설정될 때까지 대기하고 중단하지 않고 재시도합니다.

작동 방식 (개요)

부트스트랩 – hermes venv의 site‑packages에 배치된 .pth 파일이 인터프리터 시작 시 작고 가벼운 부트스트랩 모듈을 가져옵니다.
MetaPathFinder 훅 – 부트스트랩은 agent.anthropic_adapter의 가져오기를 가로채고 build_anthropic_kwargs를 패치합니다.
요금 청구 헤더 – SHA‑256 서명된 x-anthropic-billing-header를 계산하고 첫 번째 시스템 메시지로 삽입합니다.
시스템 프롬프트 재배치 – 비정체성 시스템 항목을 첫 번째 사용자 메시지 내의 <system‑reminder> 블록으로 이동 (Claude Code가 기대하는 형식).
레트리미트 자동 대기 – HTTP 429 시 Anthropic의 anthropic‑ratelimit‑unified‑*‑reset 헤더를 읽어 가장 긴 윈도우를 선택하고, (윈도우당 제한 있음) 대기 후 자동 재시도합니다.
지문 일치 – user‑agent와 요금 청구 헤더가 동일한 Claude Code 버전(2.1.112 또는 로컬 감지된 버전)을 보고하도록 강제하고, x‑app: cli를 설정하여 Anthropic이 요청을 "추가 사용"으로 간주하지 않도록 합니다.

설치

제거

./uninstall.sh (Linux/macOS) 또는 . uninstall.ps1 (Windows) 실행. --purge / -Purge를 사용하면 패치 파일도 삭제됩니다.

hermes update 후 복구

hermes update는 이전에 훅을 보유한 sitecustomize.py를 삭제할 수 있습니다. 이 리포지토리는 두 가지 방어 조치를 제공합니다:
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가 이 시그니처를 변경하면 패치도 업데이트 필요.

핵심 요약

위 모든 세부 정보는 리포지토리의 README에서 직접 가져왔으며, 추가 기능은 추측되지 않았습니다.