Claude Code 호환 프록시 Lupin 공개

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

Claude Code를 변경하지 않고 다른 모델을 연결하기 위해 로컬 프록시 Lupin을 만들었으며, 이 프록시는 Anthropic 호환 공급자에 대해서는 패스스루로 동작하고 OpenAI 호환 공급자에 대해서는 변환 계층을 둔다. 개발은 spec-first, 테스트 픽스처 중심으로 진행되어 공급자별 특이 동작을 중앙 레지스트리 플래그로 관리하고, 실제 무헤드리스 세션 산출물로 판정하는 lupin doctor를 통해 호환성을 검증한다. 실무에서 마주한 문제로는 세션 로그의 subtype이 오해를 낳는 점과 키체인 접근 차이로 인한 자격증명 불일치가 있었고, 해당 문제들은 세션 상태 표기와 마커 필드로 보완했다.

커뮤니티 반응

댓글 반응은 실제 공급자 점수를 직접 실행해 달라는 요청과 기술적 질문이 섞인 형태로 나타났다. 관심 있는 사용자들은 특정 공급자에 대한 'doctor' 검증을 우선해 달라는 요청을 남겼고, 몇몇은 레지스트리 기반의 quirk 플래그 방식에 대해 구현 세부를 묻는 질문을 보냈다. 전반적으로는 소스와 설치 커맨드, 실제 작동을 확인할 수 있는 검사 도구가 공개된 점이 신뢰성을 높였다는 반응이 우세했다.

주요 논점

01찬성다수

프록시 계층으로 Claude Code를 바꾸지 않고도 여러 공급자를 시험할 수 있어 에코시스템 재구성 비용을 크게 줄인다.

02찬성다수

테스트 픽스처 기반의 호환성 정의와 중앙화된 quirk 레지스트리는 공급자별 특례가 코드 전체에 분산되는 문제를 방지한다.

합의점 vs 논쟁점

합의점

프록시 방식으로 Claude Code를 변경하지 않고 다른 모델을 연결하는 접근법이 실용적이라는 데 동의하는 의견이 많았다.
실제 실행 결과로 검증하는 'lupin doctor' 스타일의 검증이 단순한 API 스펙 체크보다 신뢰성이 높다는 점에서 공감대가 형성되었다.
공급자별 특이동작을 중앙 레지스트리로 관리하는 설계가 유지보수를 쉽게 만든다는 평가가 반복됐다.

논쟁점

일부 사용자는 프록시가 복잡도를 더할 수 있고 특정 엣지케이스에서 디버깅을 어렵게 만들 수 있다는 점을 지적했다.
어떤 공급자를 '공식 점수표'에 올릴지에 대한 우선순위와 공정성 기준을 둘러싸고 의견이 엇갈렸다.

실용적 조언

공급자별 동작을 코드 전반의 분기문으로 처리하지 말고, 모든 특이 동작을 플래그 형태로 중앙 레지스트리에 기록해 처리하는 패턴을 권한다. 이 방식은 새로운 공급자가 추가될 때 한 곳에서만 예외를 정의하고 테스트를 갱신하면 되므로 유지보수가 수월해진다.
호환성 검사는 실제 무헤드리스 세션에서 생성되는 산출물(편집된 파일, 실행된 스크립트)을 기준으로 하되, 해당 검사도구가 프록시 자체의 수리 작업을 감지하면 '보정된 결과'로 표시하도록 구분하라. 이렇게 하면 점수가 프록시의 보정으로 왜곡되는 일을 막을 수 있다.
공유 머신에서는 자격증명 접근 권한 차이로 인해 잘못된 상태 안내가 발생하므로, 민감한 토큰 대신 비밀이 아닌 마커 필드를 남겨 접근 불능 상태를 정확히 보고하게 만드는 운영 규칙을 적용하라.

섹션별 상세

Lupin의 기본 설계는 Claude Code를 바꾸지 않고 다른 공급자를 테스트할 수 있게 만드는 프록시 아키텍처에 있다. 구현은 두 가지 모드로 나뉘며, 하나는 Anthropic Messages API를 이미 지원하는 공급자에 대해 요청을 그대로 전달하는 passthrough 모드이고 다른 하나는 OpenAI 호환 인터페이스를 Anthropic 규약으로 변환하는 translate 모드이다. 이 구조는 Claude Code의 모든 파일과 훅, 스킬이 변경 없이 계속 작동하도록 보장하므로 기존 에코시스템을 재구축할 필요가 줄어든다.

개발 워크플로우는 spec-first 원칙과 테스트 픽스처 중심으로 조직되어 있다. 구현 전에 레포에 번역 규칙, 공급자 레지스트리, CLI 설계와 의사결정 로그를 문서로 남기고, 번역 핵심 동작은 실제 Anthropic 요청과 해당 공급자가 반환한 정확한 바이트 수준 출력으로 된 테스트 픽스처에서 출발한다. 이 방식은 공급자별 특이점을 코드 곳곳의 분기문으로 흩뜨리지 않고 중앙 플래그 레지스트리에 모아 유지보수를 단순화하며 장기적으로 행위 일관성을 유지하게 했다.

호환성 검증은 단순한 JSON 변환을 넘어서서 '모델이 하네스(harness)를 살아남는가'를 기준으로 삼았다. 글에서 제시된 lupin doctor는 에페메랄 포트에서 실제 무헤드리스(헤드리스) Claude Code 세션을 실행해 디스크상의 아티팩트로 판단하고, 파일이 실제로 편집되었는지와 스크립트가 실제로 실행되었는지를 검사해 점수를 매긴다. 또한 이전에는 subtype만 보고 세션을 성공으로 처리하던 문제를 수정해, 모델에 전혀 도달하지 못한 경우에는 'notRun'과 원인을 보고하도록 바꾸어 프록시 결함이 모델 책임으로 오인되는 상황을 제거했다.

운영상에서 만난 실무적 문제로는 자격증명 관리의 비대칭성이 있다. 동일 머신에 설치된 두 인스턴스가 OS 키체인 접근 권한 차이로 서로 다른 상태를 보고하는 사례가 있었고, 저자는 비밀 값을 남기지 않는 마커 필드를 두어 키체인을 읽지 못하는 인스턴스가 실제 상태를 정확히 보고하게 했다. 이처럼 프록시가 환경별 차이를 보정하면 사용자는 불필요한 로그인을 요구받지 않게 되고 운영 장벽이 줄어든다.

용어 해설

Claude Code: — Claude Code는 Anthropic Messages API를 사용해 세션, 스킬, 훅, 메모리, 플러그인 등을 관리하는 에이전트 실행 환경으로, 글에서는 이 환경을 변경하지 않고 다른 모델을 붙이기 위해 프록시 설계를 전제로 삼았다.
Anthropic Messages API: — Anthropic Messages API는 Claude Code와 같은 클라이언트가 주고받는 메시지 포맷과 동작 규약을 규정하는 프로토콜로, Lupin은 이 규약을 기준으로 통과모드와 변환모드를 구현해 다른 공급자를 연결한다.
Lupin: — Lupin은 로컬 프록시로 Claude Code와 모델 공급자 사이에 위치하며, Anthropic 호환 공급자는 그대로 전달하고 OpenAI 호환 공급자는 요청과 응답을 변환해 Claude Code가 변경 없이 동일한 프로토콜로 동작하도록 만든 도구이다.

코드 예제

json

{"subtype":"success","is_error":true,"num_turns":1,"terminal_reason":"api_error"}

Claude Code 세션 로그에서 받은 실제 응답 예시로, subtype이 "success"로 나왔지만 is_error가 true여서 모델에 도달하지 못한 실행을 판별할 때 쓰인 원본 문자열이다. 이 문자열을 통해 점수 매김 로직이 잘못된 필드를 참조했음을 확인하고 세션을 'notRun'으로 바꾸는 계기로 사용했다.

bash

npx lupin-code@latest init

프로젝트를 로컬에서 시도할 때 사용하라는 한 줄 명령으로, README에 적힌 초기화 커맨드의 원형이다. 글에서는 이 명령으로 Lupin을 시작해 실제 공급자를 대상으로 'doctor' 검사까지 돌려볼 것을 안내한다.

언급된 도구

Lupin추천링크

Claude Code와 모델 공급자 사이에 위치해 Anthropic 규약을 유지한 채 타 공급자를 연결하는 로컬 프록시

Claude Code중립

MCP 서버, 스킬, 훅, 메모리, 플러그인을 운영하는 에이전트 실행 환경으로 Anthropic Messages API를 사용함

Anthropic Messages API중립

Claude Code와 서로 통신하는 메시지 포맷과 동작 규약을 규정하는 프로토콜

언급된 리소스

GitHubFanfulla/Lupin