Hermes Agent의 claude-subscription-directsdk 플러그인은 왜 Claude Pro/Max 구독을 API 키 없이 쓰게 하려는 걸까요?

요약 보기

이 플러그인의 핵심 아이디어는 꽤 단순해요. Hermes Agent가 모델을 직접 API로 부르는 대신, 이미 공식 Claude Code CLI에 로그인해 둔 사용자의 Claude Pro/Max 구독을 빌려서 요청을 보내게 하겠다는 거예요. 그래서 별도의 API 키를 이 플러그인에 넣지 않고, 평소 Hermes가 하던 에이전트 루프·도구 호출·승인·컨텍스트 압축은 그대로 Hermes가 맡아요. 이름에 DirectSDK가 들어가지만, 설명만 보면 파이썬 Agent SDK 패키지에 의존하는 방식이 아니라 공식 CLI 실행 파일을 요청 단위의 클라이언트처럼 다루는 쪽에 더 가깝다고 이해하면 돼요.

배경을 먼저 풀면, 여기서 중요한 구분은 "모델 자체"와 "그 모델을 호출하는 길"이에요. 이 플러그인은 모델 능력을 바꾸려는 게 아니라, Hermes가 Claude에 닿는 통로를 공식 CLI 쪽으로 바꾸려는 거예요. 가상의 비유로 말하면, 같은 식당 주방에 주문을 넣더라도 배달 앱 API로 주문하는 대신, 이미 회원권이 연결된 공식 키오스크를 통해 주문을 넣는 셈이에요. 주방이 바뀌는 게 아니라 주문 창구가 바뀌고, 홀 운영은 여전히 Hermes가 맡는다는 그림이죠. 그래서 문서가 계속 강조하는 것도 "Hermes는 자기 루프를 유지한다", "인증은 공식 CLI 소관이다"라는 점이에요.

대신 조건은 꽤 분명해요. Hermes 버전이 너무 낮으면 아예 반쯤 작동하는 상태로 두지 않고 로드 실패 경고를 내고 멈추게 되어 있어요. 또 Python 3.10 이상과 공식 Claude Code CLI 설치·로그인이 필요해요. 특히 이 플러그인은 자기 자격 증명을 따로 갖고 있지 않아서, 모든 인증과 계정 상태를 `claude` CLI에 맡겨요. 그래서 `claude`가 없을 때는 플러그인 로드 시점, 모델 선택 시점, 실제 요청 직전까지 여러 지점에서 계속 확인하고, 없으면 추측해서 진행하지 않고 설치 힌트를 보여주며 멈춘다고 설명해요. 배경지식이 부족하면 이 부분이 귀찮아 보일 수 있는데, 사실은 문제를 뒤늦게 터뜨리지 않으려는 안전장치에 가까워요.

설정 흐름도 그 철학을 따라가요. 제공자 선택을 저장하기 전에 먼저 로컬에 `claude`가 있는지, 그리고 로그인됐는지를 Claude CLI에게 직접 묻는다고 해요. 설치가 안 되어 있으면 설정 파일을 건드리지 않고 멈추고, 로그인되지 않았으면 터미널에서는 로그인 절차를 이어 주고, 터미널이 아닌 환경에서는 안내만 하고 멈춰요. 즉, 나중에 요청을 날릴 때 갑자기 실패하는 대신, 시작 단계에서 빠르게 막아 두는 방식이에요. 이것도 결국 "조용히 우회하지 않겠다"는 설계 원칙의 한 부분으로 읽으면 돼요.

인증과 비용 쪽은 더 조심해서 읽어야 해요. 문서는 "별도 API 키가 필요 없다"고 말하지만, 그게 곧 "비용 관련 위험이 완전히 없다"는 뜻은 아니에요. 인증은 전부 공식 CLI가 맡고, 이 플러그인은 자격 증명 파일을 열거나 복사하거나 출력하지 않는다고 해요. 또 기존 환경에 남아 있는 API 키나 커스텀 엔드포인트 같은 우회 경로가 있으면, 그것들을 몰래 쓰지 않고 충돌 변수 이름을 알려 주며 실행을 거부해요. 동시에 구독 한도와 초과 사용 설정은 여전히 사용자 계정과 원래 서비스 쪽 소관이라고 못 박아요. 초과 과금이 싫다면 계정에서 extra usage를 꺼야 하고, 실행 중 보이는 리스트 가격 환산치는 실제로 구독에서 얼마 청구됐는지 증명하는 값이 아니라고 선을 그어요.

기술적으로는 Hermes가 요청할 때마다 새 프로세스를 따로 띄우고, 임시 디렉터리 안에서 고립된 상태로 Claude CLI를 실행해요. 여기서 중요한 목적은 'Claude 쪽 기본 기능이 멋대로 끼어들지 않게 하기'예요. 문서에 따르면 네이티브 도구, 스킬, 설정 소스는 꺼 두고, MCP를 통해 현재 Hermes가 가진 도구 목록만 광고해요. 게다가 실행은 네이티브 쪽에서 `dontAsk`로 막아 둔다고 하니, 실질적 도구 통제권은 Hermes 쪽에 남겨 두려는 설계죠. 큰 시스템 프롬프트와 도구 스키마는 별도 파일과 추가 바디로 전달하는데, 그 이유도 운영체제의 인자 길이 제한을 피하면서 인증·신원 필드는 건드리지 않기 위해서라고 설명해요. 쉽게 말해, Hermes가 감독관이고 Claude CLI는 그때그때 고용되는 현장 작업자처럼 쓰려는 구조예요.

이 플러그인이 특히 공을 들인 부분은 "한 번의 Hermes 요청이 위쪽 서비스 요청 하나로 끝나게 만드는 것"이에요. 문서에 따르면 네이티브 Claude Code는 `--max-turns 1`을 줘도 추가 생성이나 복구 시도를 할 수 있어서, 플러그인 쪽에 로컬 루프백 릴레이를 두고 첫 번째 Messages 요청만 통과시키고 그다음 시도는 로컬에서 거절해요. 왜 이런 장치를 넣느냐면, Hermes는 이미 자기 승인·도구·재시도 규칙을 갖고 있는데, 아래쪽 CLI가 한 번 더 독자적으로 움직이면 누가 흐름의 주인인지 꼬이기 쉬워서예요. 이 릴레이는 첫 응답의 텍스트, 사용량, 중단 이유, 서명된 thinking 같은 걸 먼저 붙잡아 두고, 네이티브 복구가 그것을 다른 형태로 바꾸기 전에 Hermes에 넘겨준다고 설명해요. 그래서 "첫 응답은 살리고, 뒤늦은 복구 시도만 차단한다"가 핵심이라고 보면 돼요.

히스토리 재생 방식도 중요한데, 이 플러그인은 Claude 쪽에 세션을 오래 붙들어 두지 않고 Hermes가 가진 대화 기록을 순서대로 다시 흘려보내는 방식을 택해요. 과거 사용자 메시지는 조회만 하도록 보내고, 마지막 사용자나 도구 결과 프레임에서만 실제 질의를 건다고 해요. 네이티브 승인 대기나 인위적인 '계속해' 프롬프트를 추가하지 않는다는 설명도 있어요. 이 말은 곧, 대화의 정본은 Hermes가 쥐고 있고 Claude CLI는 매번 그 정본을 받아 새로 계산한다는 뜻에 가까워요. 다만 이렇게 재생한다고 해서 바이트 단위로 완전히 똑같은 프롬프트가 된다는 보장은 없고, 네이티브 쪽 다른 주석은 남는다고 적혀 있어요. 즉, 의도는 Hermes 중심의 일관성이지만, 내부 표현까지 완전 동일하다고 주장하는 문서는 아니에요.

성능과 검증 쪽에서는 저자가 꽤 구체적인 실험 결과를 내놓지만, 그걸 곧바로 "실서비스 준비 완료"로 읽으면 안 돼요. 문서에는 실제 구독 기반 검토에서 Hermes 호출 수와 상위 요청 수가 정확히 일치했고, 도구 실행과 결과도 여러 차례 이어졌다고 적혀 있어요. 또 긴 컨텍스트에서 처음에는 캐시 재사용이 나빴는데, 네이티브 토큰 예산 리마인더를 끄자 후속 요청의 캐시 읽기 비율이 크게 안정됐다고 주장해요. 이런 수치는 '설계가 의도대로 어느 정도 작동했다'는 근거로는 쓸 수 있어요. 하지만 동시에 이 빌드는 리뷰용이며, 완전한 동등성이나 운영환경 준비 상태를 주장하는 것이 아니라고 분명히 말해요. 더구나 비용 수치도 실제 청구액 검증이 아니라 리스트 가격 환산치라고 못 박고 있어요.

지원 범위와 미지원 범위도 알아둘 필요가 있어요. 문서상으로는 텍스트, 이미지·문서 입력의 일부 형식, 도구와 도구 결과, 출력 토큰 한도, 정지 시퀀스, 추론 on/off와 노력 수준, JSON 스키마 기반 응답 형식 같은 번역은 지원해요. 반면 미지의 매개변수는 조용히 무시하지 않고 명시적으로 실패시키고, assistant prefill, 강제 도구 선택, `n>1`, 임의 헤더나 바디 필드, 원격 이미지 다운로드 같은 여러 표면은 지원하지 않아요. 이건 사용성이 떨어져 보일 수 있지만, 사실상 플러그인이 다루는 범위를 좁혀서 예측 가능한 동작을 확보하려는 선택으로 읽혀요. 다만 큰 프롬프트는 여전히 네이티브나 운영체제 한계의 영향을 받는다고 하니, 긴 문맥 작업에서 무한정 안전한 것은 아니에요.

수명주기와 취소 처리도 이 플러그인의 실제 사용감에 큰 영향을 줘요. 문서에 따르면 동기·비동기 호출을 모두 지원하고, 스트림도 비동기 반복으로 받을 수 있어요. 그리고 `cancel()`은 소유한 프로세스 트리를 통째로 종료해, npm 래퍼 뒤에 남은 자식 프로세스가 취소 뒤에도 살아남지 않게 설계했다고 해요. `close()`는 새 호출을 막고 유휴 스트림을 정리하지만, 이미 돌아가는 소비자는 취소 후에 풀리도록 한다고 설명해요. 이런 세부 동작은 겉으로는 사소해 보여도, 에이전트 도구 실행 중간에 사용자가 중단 버튼을 눌렀을 때 시스템이 말끔하게 정리되는지와 직결돼요.

정리하면, 이 저장소가 말하는 가치는 "Hermes의 제어권은 유지하면서, 공식 Claude CLI에 로그인된 구독을 호출 경로로 활용하자"에 있어요. 다만 그 주장은 어디까지나 실험적 제공자라는 전제 위에서 읽어야 해요. 저자는 설치 확인, 로그인 확인, 인증 우회 차단, 추가 생성 차단, 도구 통제, 취소 시 프로세스 정리 같은 장치를 통해 반쯤 작동하는 위험한 상태를 줄이려 했다고 설명해요. 반대로 완전한 기능 동등성, 모든 히스토리 변형에 대한 보장, 모든 모델·계정 상태에서의 동일한 과금·한도 동작까지 약속하는 문서는 아니에요. 관심 있는 입장에서는 'API 키 없는 Claude 구독 연동'이 포인트이고, 실제 도입 판단에서는 '공식 CLI 의존, 제한된 기능 표면, 리뷰 빌드'라는 조건을 같이 봐야 해요.