cc-gateway 딥다이브
— Claude Code 앞에 앉는 리버스 프록시, 여러 기기를 한 대처럼 보이게 한다

1프로젝트 한줄 요약

cc-gateway는 Claude Code와 Anthropic API 사이에 끼어 앉아, 각 기기가 본사로 보내는 디바이스 ID·이메일·환경 정보·텔레메트리를 가로채 하나의 통일된 신원으로 다시 써서 전달하는 리버스 프록시다. 여러 대의 컴퓨터에서 같은 계정을 써도, 본사 입장에서는 "단 한 대의 기기"로만 보이게 만든다.

2왜 주목받는가

요즘 AI 서비스는 "한 사람당 하나의 계정"을 강제한다. 하지만 사람들은 데스크톱·노트북·회사 PC·서버에서 같은 계정을 쓰고 싶어 한다. Claude Code는 각 기기마다 다른 디바이스 ID와 텔레메트리를 본사에 보내기 때문에 — 본사 입장에서는 "한 계정이 다섯 기기에서 동시에"라는 신호가 된다. cc-gateway는 이 신호 자체를 지운다.

이 레포가 학습 자료로 좋은 이유

3기술 스택 전체 지도

언어 / 런타임

외부 의존성 — 단 2개 (확인됨)

배포 / DevOps

4아키텍처 심화 분석

시스템 구조도

핵심 설계 패턴 ①: 인터셉터 체인 (요청 변환의 순서)

이 프로젝트에서 가장 흥미로운 코드는 rewriter.ts다. 클라이언트의 요청 한 건이 들어오면 아래 6단계를 순서대로 거친다.

핵심 설계 패턴 ②: SSE 스트리밍을 건드리지 않는다

요청은 통째로 바꾸지만, 응답은 한 글자도 안 건드린다. 코드로 보면 이 한 줄이다 — proxyRes.pipe(res). 업스트림 응답을 클라이언트 응답에 통째로 흘려보낸다.

핵심 설계 패턴 ③: x-anthropic-billing-header 전략

가장 까다로운 부분은 x-anthropic-billing-header 처리다. Claude Code가 보내는 이 빌링 헤더에는 메시지 본문 기반 검증값이 포함돼 있는데, 게이트웨이가 본문을 리라이트하면 불일치가 발생할 수 있다. v0.2.0에서는 이 헤더를 완전히 제거(strip)하는 방식으로 전략이 바뀌었다 — Anthropic 공식 환경변수 CLAUDE_CODE_ATTRIBUTION_HEADER=false와 동일한 효과이며, 프롬프트 캐시 공유의 부산물이기도 하다.

핵심 설계 패턴 ④: 고정값 대신 "현실적인 랜덤"

5디렉토리 구조 해부

구조를 읽는 법: proxy.ts가 들어오는 연결을 받고 → rewriter.ts가 요청을 변환하고 → oauth.ts가 신원을 주입하고 → 다시 proxy.ts가 업스트림으로 포워딩한다. 파일 8개만 읽으면 전체 흐름이 손에 잡히는 크기라서 입문용 리딩 대상으로 이상적이다.

6학습 포인트 (기술별)

A. 순수 Node.js HTTP 서버 — 프레임워크 없는 본질

배울 것: http.createServer()로 서버를 만들고, https.request()로 업스트림을 호출하고, pipe()로 스트림을 잇는 — 모든 Node.js 웹 서버의 토대. Express/Fastify가 마법처럼 느껴지는 이유는 이 기초를 안 봤기 때문이다.

B. 리버스 프록시 & 인터셉터 체인

배울 것: 인증 → 본문/헤더 변환 → 포워딩의 파이프라인 설계. 경로별 분기(/v1/messages vs /event_logging)로 같은 진입점에서 서로 다른 변환을 적용하는 라우팅 감각.

C. SSE 스트리밍 무손실 통과

배울 것: 요청은 버퍼링해 변환하되, 응답은 버퍼링 없이 즉시 흘려보내야 하는 이유. 백프레셔(backpressure)를 자동 처리하는 pipe()의 가치.

D. OAuth 토큰 사전 갱신 (Proactive Renewal)

배울 것: 외부 OAuth 라이브러리 없이 토큰 캐싱·만료 추적·setTimeout 사전 갱신을 직접 구현하는 법. 만료 5분 전 자동 갱신으로 서비스 중단을 막는다.

E. 암호 해시 & 역공학 사고법

배울 것: crypto 빌트인의 SHA-256 사용법과, 관찰 → 가설 → 시뮬레이션 → 복원으로 이어지는 리버스 엔지니어링 절차. "입력 한 글자가 바뀌면 출력이 완전히 달라진다"는 해시의 성질을 실전에서 다룬다.

F. 미니멀 의존성 & 공급망 보안

배울 것: 의존성 2개라는 극단적 선택이 주는 보안·유지보수 이점. 빌트인으로 충분한 일을 굳이 패키지로 끌어오지 않는 판단 기준.

G. Docker 멀티 스테이지 & TypeScript 빌드 파이프라인

배울 것: tsx watch로 개발하고 tsc로 dist/를 만든 뒤 컨테이너에 담는 흐름. 빌드 환경과 런타임 환경을 분리해 최종 이미지를 줄이는 패턴은 Python·Go·Rust에도 그대로 적용된다.

7하드웨어 / 시스템 요구사항

8직접 해볼 수 있는 실습 과제

// echo-proxy.mjs
import http from 'http';
import https from 'https';

http.createServer((req, res) => {
  // 업스트림으로 그대로 포워딩
  const up = https.request(
    { host: 'httpbin.org', path: req.url, method: req.method, headers: req.headers },
    (proxyRes) => {
      res.writeHead(proxyRes.statusCode, proxyRes.headers);
      proxyRes.pipe(res);   // ← SSE도 이 한 줄로 무손실 통과
    });
  req.pipe(up);
}).listen(8787);

9관련 기술 심화 학습 로드맵

1주차: Node.js HTTP의 기초

2주차: 리버스 프록시 & 변환

3주차: 인증 · OAuth · 암호

4주차: 배포 & 운영

10핵심 키워드 사전

11참고 링크

• GitHub 레포 — motiful/cc-gateway
• rewriter.ts — 인터셉터 체인 본체
• oauth.ts — 토큰 사전 갱신
• rewriter.test.ts — 16개 테스트
• Node.js 공식 문서 — http 모듈
• Node.js — Stream.pipe()
• Node.js — crypto (SHA-256)
• MDN — Server-Sent Events
• RFC 6749 — OAuth 2.0
• mitmproxy 공식 문서