CC Gateway: Claude Code의 API 텔레메트리를 하나의 정체성으로 정규화하는 리버스 프록시

9bow · 6월 7, 2026, 12:30오후

CC Gateway 소개

CC Gateway는 Claude Code와 Anthropic API 사이에 놓여 기기 식별 정보와 환경 텔레메트리(telemetry)를 하나의 정규(canonical) 프로필로 통일하는 리버스 프록시(reverse proxy)입니다. 작성자는 Claude Code가 "640+ telemetry event types" 를 세 개의 병렬 채널로 수집하고 "40+ environment dimensions" 로 기기를 식별한다고 설명하며, 기기 ID, 이메일, OS 버전, 설치된 런타임, 셸 종류, CPU 아키텍처, 물리 RAM 같은 정보가 지속적으로 보고된다고 주장합니다. 여러 대의 기기에서 Claude Code를 쓰면 각 기기마다 고유한 영구 식별자가 생기는데, 사용자가 자신의 정체성이 API에 어떻게 표현되는지를 관리할 내장 수단은 없다는 것이 프로젝트가 제시하는 문제의식입니다.

핵심 접근은 클라이언트가 API로 보내는 요청 본문, 헤더, 시스템 프롬프트 텍스트를 게이트웨이가 가로채 하나의 정규 프로필로 다시 쓰는 것 입니다. 여러 기기가 모두 같은 기기 ID, 같은 이메일, 같은 환경 값을 보고하도록 만들어, API 입장에서는 한 사람이 한 대의 기기를 쓰는 것과 구분되지 않게 합니다. 게이트웨이는 모든 트래픽을 단일 고정 IP로 라우팅하고 OAuth 토큰 갱신을 내부에서 관리하므로, 클라이언트 머신은 platform.claude.com 에 직접 접속하지 않습니다.

이 프로젝트는 README에 "Alpha — This project is under active development. Test with a non-primary account first." 라고 명시된 알파 단계입니다. 또한 README의 별도 면책 조항(disclaimer)에서 "This project is for educational and research purposes only" 라고 밝히며 계정 공유나 Anthropic 이용약관 위반, 상업적 용도에는 사용하지 말 것을 당부하고 있습니다. 도입을 검토한다면 저장소의 면책 조항과 알파 상태를 먼저 확인하는 편이 좋습니다.

CC Gateway가 다시 쓰는 데이터 계층

CC Gateway가 정규화하는 대상은 README의 "What Gets Rewritten" 표에 계층별로 정리되어 있습니다. 식별 계층에서는 메타데이터와 이벤트의 device_id, 그리고 email 을 정규 값으로 바꿉니다. 환경 계층에서는 플랫폼, 아키텍처, Node.js 버전, 터미널, 패키지 매니저, 런타임, CI 플래그 등 40여 개 필드가 담긴 env 객체를 부분 수정이 아니라 통째로 교체합니다.

프로세스 계층에서는 물리 RAM(constrainedMemory)을 정규 값으로 마스킹하고 rss, heapTotal, heapUsed 같은 힙 지표를 현실적인 범위 안에서 무작위화합니다. 헤더 계층에서는 세션별 지문 해시를 담은 x-anthropic-billing-header 를 통째로 제거하는데, 작성자는 이것이 공식 환경 변수 CLAUDE_CODE_ATTRIBUTION_HEADER=false 와 동일한 동작이며 세션 간 프롬프트 캐시 공유를 가능하게 해 시스템 프롬프트 비용을 약 85% 줄인다고 주장합니다. 프롬프트 텍스트 계층에서는 모든 프롬프트에 주입되는 <env> 블록의 플랫폼, 셸, OS 버전, 작업 디렉토리 경로를 정규 값으로 다시 씁니다.

게이트웨이는 SSE(Server-Sent Events) 스트림을 그대로 통과시키며, 프록시 사용 사실을 노출할 수 있는 baseUrl 과 gateway 필드를 분석 이벤트에서 제거하는 누출 방지 처리도 포함합니다.

CC Gateway 설치 및 사용 방법

설치에는 Node.js 22 이상과 해당 머신에 이미 로그인된 Claude Code가 필요합니다. 로컬에서는 한 번의 명령으로 셋업이 끝납니다.

git clone https://github.com/motiful/cc-gateway.git
cd cc-gateway
npm install
bash scripts/quick-setup.sh

이 스크립트는 macOS 키체인에서 OAuth 자격 증명을 추출하고, 정규 기기 정체성과 클라이언트 토큰을 생성하고, config.yaml 을 작성한 뒤, ./clients/cc-<hostname> 런처를 만들고 게이트웨이를 http://localhost:8443 에서 시작합니다. 다른 터미널에서 생성된 런처를 실행하면 Claude Code가 게이트웨이를 통해 동작합니다.

여러 사람이 쓸 때는 관리자가 사람별 런처를 발급합니다.

bash scripts/add-client.sh alice
bash scripts/add-client.sh bob

각 런처는 자체 토큰을 가진 독립 스크립트이며, 받은 사람은 ./cc-alice install 로 ccg 명령을 설치한 뒤 ccg 로 Claude Code를 게이트웨이를 통해 실행합니다. ccg hijack 으로 기존 claude 명령까지 게이트웨이를 거치게 만들 수 있고 ccg release 로 되돌립니다. 다중 머신 배포 시 README는 관리자 머신을 포함한 모든 기기가 게이트웨이를 사용해야 별도의 기기 지문이 생기지 않는다고 안내합니다.

원격 배포에는 TLS 인증서를 생성해 config.yaml 의 tls 섹션을 활성화하거나, 모든 기기에 Tailscale이 설치되어 있으면 메시 안의 아무 머신에서 게이트웨이를 띄우는 방식을 제안합니다. Docker 기반 프로덕션 배포는 bash scripts/admin-setup.sh 대화형 스크립트로 진행합니다.

CC Gateway의 한계와 참고 자료

README의 "Caveats" 섹션은 몇 가지 한계를 명시합니다. mcp-proxy.anthropic.com 은 하드코딩되어 ANTHROPIC_BASE_URL 을 따르지 않으므로, 공식 MCP 서버를 쓰는 클라이언트의 해당 요청은 게이트웨이를 우회합니다. 필요 없다면 Clash 같은 도구로 해당 도메인을 차단하라고 안내합니다. 또한 새로운 Claude Code 버전이 새 텔레메트리 필드나 엔드포인트를 도입할 수 있으므로 업그레이드 후 연결 시도를 모니터링하라고 권합니다.

이 프로젝트는 instructkr/claude-code의 역난독화된 Claude Code 소스를 텔레메트리 분석에 활용했고, 빌링 헤더가 프롬프트 캐시 공유를 깨뜨린다는 점을 A/B 테스트로 보인 cc-cache-audit 위에 구축되었다고 밝히고 있습니다. 본문에 인용한 텔레메트리 이벤트 수와 비용 절감 수치는 모두 작성자의 분석·주장이므로, 도입 전 자신의 환경에서 직접 검증할 것을 권합니다.

CC Gateway의 라이선스

CC Gateway는 MIT 라이선스로 공개되어 있습니다. 다만 라이선스와 별개로, README의 면책 조항은 이 도구를 교육·연구 목적으로만 쓰고 계정 공유나 이용약관 위반, 상업적 용도에는 사용하지 말 것을 명시하고 있으므로 실제 사용 시 함께 고려해야 합니다.

CC Gateway GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다.

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

아래쪽에 좋아요를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~