Claude Relay Service

Claude Relay Service(줄여서 CRS)는 직접 배포해 사용할 수 있는 AI API 중계 서비스입니다. 공식 소개 문구는 「자체 구축 Claude Code 미러, 원스톱 오픈소스 중계 서비스」입니다. Claude, OpenAI, Gemini, Droid 등의 구독 계정을 하나로 통합해 연결할 수 있고, 여러 사람이 계정을 함께 쓰는 카풀 방식으로 비용을 나눌 수 있습니다. 모든 요청은 사용자 본인의 서버만 거쳐 업스트림 API로 직접 전달됩니다.

보안 안내: 공식 README에 따르면 v1.1.248 이하 버전에는 심각한 관리자 인증 우회 취약점이 있어, 공격자가 권한 없이 관리 패널에 접근할 수 있습니다. v1.1.249 이상으로 업그레이드하거나, 공식에서 권장하는 차세대 프로젝트인 CRS 2.0(sub2api)으로 이전하세요.

규정 준수 위험: 공식적으로 이 프로젝트를 사용하면 Anthropic의 서비스 약관을 위반할 수 있으며, 그 위험은 사용자 본인이 부담한다고 명시하고 있습니다. 이 프로젝트는 기술 학습과 연구 목적으로만 제공되며, 작성자는 계정 정지나 서비스 중단 등으로 인한 손실에 책임지지 않습니다.

주요 기능

• 다중 계정 관리: 여러 Claude 계정을 추가하고 OAuth 인증으로 연결하며 자동으로 순환합니다. 계정에 문제가 생기면 다음 계정으로 자동 전환됩니다.
• 사용자 지정 API Key: 사용자마다 독립적인 Key(cr_로 시작)를 발급하고, 속도 제한, 동시성 제한, 모델 제한, 클라이언트 제한을 설정할 수 있습니다.
• 멀티 플랫폼 계정 풀: /claude/, /antigravity/api/, /gemini/, /openai/, /droid/claude/, /droid/openai/ 등 라우트 접두사로 계정 유형을 구분하며, 같은 Key를 공통으로 사용할 수 있습니다.
• 사용량 통계 및 모니터링: 웹 관리 화면(/web)에서 Key별 토큰 사용량을 확인하고 공식 가격 기준으로 비용을 환산해 볼 수 있습니다. /health 상태 점검 엔드포인트도 있습니다.
• 일시 중지 및 쿨다운: 업스트림에서 503, 5xx, 과부하, 인증 오류, 타임아웃 오류가 발생하면 시스템이 해당 계정으로의 라우팅을 일시 중지합니다. 쿨다운 시간은 전역 또는 계정 단위로 설정할 수 있습니다.
• 보안 제어: 접근 제한, 속도 제어, User-Agent를 통한 클라이언트 식별(ClaudeCode, Gemini-CLI 등)을 지원합니다.
• 프록시 지원: HTTP/SOCKS5 프록시를 지원하며, 계정별로 고정 프록시 IP를 지정할 수 있습니다.
• 성능 최적화: 커넥션 풀과 캐시를 사용해 지연 시간을 줄입니다.

대상 사용자 및 활용 사례

• 친구들과 Claude Code Max 같은 구독 요금을 나눠 내고 싶은 소규모 그룹
• 제3자 미러 사이트에 대화 내용이 노출되는 것을 원하지 않는, 데이터 프라이버시를 중시하는 개발자
• 어느 정도 기술 지식이 있고 직접 구축하고 유지보수할 의향이 있는 사용자
• 장기적으로 안정적인 접근이 필요하고 제3자 미러 사이트에 의존하고 싶지 않은 사용자
• 거주 지역에서 Claude 서비스에 직접 접속할 수 없는 사용자

클라이언트 연결

공식 README에서는 다음 클라이언트의 설정 예시를 제공합니다.

• Claude Code: ANTHROPIC_BASE_URL과 ANTHROPIC_AUTH_TOKEN 환경 변수를 설정합니다.
• Gemini CLI: Gemini Assist API 또는 Gemini API 두 가지 방식으로 연결할 수 있습니다.
• Codex: ~/.codex/config.toml과 auth.json에서 설정하며, OpenAI Responses 형식만 지원합니다.
• Droid CLI: ~/.factory/config.json에 사용자 지정 모델을 추가합니다.
• Cherry Studio 등 서드파티 도구: 해당하는 공급자 유형을 선택하고 서비스 주소와 API Key를 입력합니다.
• VSCode Claude 플러그인: ~/.claude/config.json에 primaryApiKey를 설정해야 합니다.

배포 방법

하드웨어 요구 사항(최소): CPU 1코어, 메모리 512MB(1GB 권장), 사용 가능한 디스크 30GB. 공식적으로는 2코어 4GB면 충분하다고 안내하며, 미국 등 Anthropic API에 접속할 수 있는 지역의 서버를 사용하길 권장합니다. 또한 알리바바 클라우드와 텐센트 클라우드의 해외 호스트는 테스트 결과 Cloudflare에 의해 차단된다고 공식에서 알리고 있습니다.

소프트웨어 요구 사항: Node.js 18+, Redis 6+, Linux 사용을 권장합니다.

1. 스크립트 원클릭 배포(공식 권장): manage.sh install을 내려받아 실행하면 의존성 설치, 대화형 설정, 서비스 시작이 자동으로 이루어지며, 이후 crs 명령으로 서비스를 관리할 수 있습니다(install/start/stop/restart/status/update/uninstall). Ubuntu/Debian, CentOS/RedHat, Arch Linux, macOS를 지원합니다.
2. 수동 배포: 저장소를 클론하고 npm install을 실행한 뒤, config/config.example.js와 .env.example을 복사해 JWT_SECRET, ENCRYPTION_KEY를 설정합니다. 프런트엔드를 빌드한 후 npm run setup으로 초기화하고 npm run service:start:daemon으로 백그라운드에서 실행합니다.
3. Docker Compose: 공식 스크립트로 docker-compose.yml을 생성한 뒤 docker-compose up -d를 실행합니다. 구성에는 Redis, 데이터 영속화, 상태 점검, 자동 재시작이 포함되어 있습니다.

관리자 계정은 자동으로 생성되며(data/init.json에 저장), ADMIN_USERNAME과 ADMIN_PASSWORD 환경 변수로 미리 지정할 수도 있습니다. 프로덕션 환경에서는 Caddy 또는 Nginx Proxy Manager를 이용한 리버스 프록시를 권장합니다. Nginx로 리버스 프록시하면서 Codex CLI를 사용할 때는 http 블록에 underscores_in_headers on;을 추가해야 합니다.

참고 사항

• MIT 라이선스를 채택했으며, 기술 스택은 Node.js와 Redis, 프런트엔드는 관리 대시보드 SPA입니다.
• 데모 사이트와 공지 채널이 제공되며, 영문 README도 있습니다.
• 사용 전에 반드시 Anthropic 서비스 약관을 읽어 보고, 보안 수정이 포함된 버전으로 신속하게 업데이트하세요.