자체 API 프록시 구축하기

이 장에서는 흔히 겪는 문제를 다룹니다: Claude, Codex 같은 해외 AI 서비스를 사용할 때 여러 불편이 따릅니다. 계정이 이유 없이 차단되기도 하고, 매번 수동으로 프록시를 활성화해야 하며, 혼자서 부담하기엔 구독 비용이 비싸고, 적절한 권한 관리 없이 친구들과 공유하기도 까다롭습니다.

저도 이 서비스들을 직접 사용하며 항상 자체 호스팅 API 릴레이에 의존해 왔습니다. 이 장에서는 전체 설정 과정을 안내합니다.

왜 자체 API 프록시를 구축해야 할까요

동기부터 살펴보면서 이 문제가 무엇을 해결하는지 이해해 봅시다.

Claude는 계정을 차단하는 경향이 있습니다. 많은 사람들이 여러 기기에서 다양한 IP로 로그인하다 보면 리스크 관리 시스템에 걸려 계정이 차단됩니다. 릴레이를 사용하면 단일 IP로 고정되어 모든 요청이 동일한 서버를 통해 전달되므로 차단 가능성이 크게 줄어듭니다.
사용이 더 편리합니다. 한 번 설정하면 매번 수동으로 프록시를 활성화할 필요 없이 서버에 직접 연결됩니다.
여러 명이 하나의 구독을 공유할 수 있습니다. Claude Max 및 Pro 구독은 저렴하지 않으므로 여러 사람이 비용을 나눌 수 있습니다. 릴레이를 통해 각 사용자마다 별도의 API 키를 생성할 수 있으며, 각 키는 독립적인 권한과 사용 통계를 가집니다.
타인에게서 구매하지 않는 이유는 위험이 너무 크기 때문입니다. 시장에는 많은 API 릴레이 서비스가 있지만, 진짜와 가짜를 구분하기 어렵고 언제든 사라질 수 있으며 데이터가 가로채질 위험이 있습니다.
데이터 보안 문제. 타인의 릴레이 서비스를 사용하면 모든 요청이 그들의 서버를 통과합니다. 민감한 콘텐츠는 통제되지 않은 제3자를 거쳐서는 안 됩니다.
여러 AI 제공자를 지원합니다. 이 설정은 Claude뿐만 아니라 Codex와 같은 다른 서비스도 지원합니다.

어떤 프로젝트를 사용할까

다음 오픈소스 프로젝트를 사용합니다: claude-relay-service

시작하기 전에 배포 요구 사항을 확인하세요:

VPS: 최소 사양으로 충분하며, 1코어 1GB RAM이면 됩니다.
운영 체제: Linux (Ubuntu/Debian 모두 가능)
가장 중요한 점: VPS가 Anthropic의 API에 직접 접근할 수 있어야 합니다. 즉, 서버 자체가 claude.ai에 도달할 수 있어야 합니다.

VPS란 무엇인가요? 간단히 말해, 24시간 내내 작동하는 임대 원격 서버입니다. 프로그램을 실행할 수 있고, 종료되지 않으며, 고정 공인 IP를 가집니다. 일반적인 국내 클라우드 서버(예: Alibaba Cloud ECS, Tencent Cloud CVM)도 비슷하지만 지역 제한으로 인해 작동하지 않으므로 해외 서버를 임대해야 합니다.

VPS 대신 개인 컴퓨터를 사용할 수 있나요? 이론적으로는 가능하지만 두 가지 엄격한 조건이 있습니다: 첫째, 컴퓨터가 24시간 켜져 있어야 하고; 둘째, 네트워크가 Anthropic 서버에 직접 연결될 수 있어야 합니다. 두 조건을 모두 충족해야 하며, 그렇지 않으면 작동하지 않습니다. 따라서 실제로는 해외 VPS를 임대하는 것이 훨씬 간단합니다.

이 ‘Anthropic에 도달 가능’이라는 마지막 조건이 많은 사람들을 막히게 합니다. VPS의 위치가 작동 여부를 직접 결정합니다. 저는 데이터센터 IP를 가진 일본 VPS를 사용하는데, 추가 설정 없이 직접 연결됩니다. 싱가포르, 미국, 일본의 데이터센터는 일반적으로 괜찮습니다. 중국 내 서버는 확실히 작동하지 않으며, 일부 홍콩 데이터센터도 차단될 수 있습니다. 구매 전에 확인하는 것이 좋습니다.

원클릭 배포

VPS 터미널에 연결하고 다음 명령어를 실행하세요:

curl -fsSL https://pincc.ai/manage.sh -o manage.sh && chmod +x manage.sh && ./manage.sh install

Enter를 누르고 완료될 때까지 기다리세요. 설치가 성공하면 터미널에 다음과 같은 출력이 나타납니다:

Access URLs:
  Local Web: http://localhost:8080/web
  Public Web: http://YOUR_IP:8080/web

Admin credentials saved to: data/init.json

YOUR_IP는 VPS의 공인 IP입니다. 관리자 비밀번호는 data/init.json 파일에 저장되어 있습니다; cat data/init.json으로 확인할 수 있습니다. 공개 URL과 비밀번호를 기록해 두세요. 관리자 패널에 로그인할 때 필요합니다.

설치 후 시스템은 서비스 관리를 위한 crs 명령어를 등록합니다:

crs install   # Install the service
crs start     # Start the service
crs stop      # Stop the service
crs restart   # Restart the service
crs status    # Check status
crs update    # Update the service
crs uninstall # Uninstall the service

나중에 업그레이드하려면 VPS에 연결하여 crs update를 실행하기만 하면 됩니다—설치 과정을 반복할 필요가 없습니다.

관리자 패널 접속

앞서 기록한 공개 URL을 브라우저에서 열고 관리자 비밀번호를 입력하면 다음과 같은 대시보드가 나타납니다:

이것은 시스템 대시보드로, 현재 API 키 수, 서비스 계정, 오늘의 요청 수, 토큰 소비 등을 보여줍니다. 관리자 패널은 각 API 키의 사용 세부 정보를 볼 수 있어 공유 시 누가 얼마나 사용했는지 명확히 알 수 있습니다. 자유롭게 탐색해 보세요.

상단 탐색에는 두 가지 핵심 설정 항목이 있습니다(이미지에서 빨간색으로 강조 표시됨):

API Keys: 사용자용 API 키를 생성하고 관리합니다.
Account Management: 구매한 Claude 구독 계정을 연결합니다.

다음으로, 먼저 계정을 연결한 후 API 키를 생성하겠습니다.

1단계: Claude 계정 연결

상단의 ‘Account Management’를 클릭한 후 ‘Add Account’를 클릭하세요. 계정 추가 대화상자가 나타납니다.

1단계 — 기본 정보

다음 정보를 입력하세요:

플랫폼 선택: Claude (Anthropic)를 선택하세요. 다른 옵션으로 OpenAI, Gemini 등이 있습니다.
특정 플랫폼 유형 선택: Claude Code (Official)를 선택하세요. 이것이 주요 방법입니다.
추가 방법: OAuth Authorization (Usage Visualization)을 선택하세요. 관리자 패널에서 자세한 사용 데이터를 볼 수 있습니다.
계정 이름: 알아볼 수 있는 이름을 입력하세요. 예: ‘내 Max 계정’.

아래로 더 스크롤하면 몇 가지 중요한 옵션이 있습니다:

구독 유형은 정확해야 합니다—실제로 구매한 것을 선택하세요:

Claude Max: Max 구독이 있는 경우 선택하세요.
Claude Pro: Pro 구독이 있는 경우 선택하세요.

아래에는 ‘5시간 사용 제한에 가까워지면 자동 중지 예약’ 및 ‘워밍업 요청 차단’과 같은 고급 옵션도 있습니다. 초보자는 기본값을 유지하고 필요에 따라 나중에 조정하면 됩니다.

작성을 완료한 후 ‘Next’를 클릭하여 인증을 진행하세요.

2단계 — 인증

이 단계에서는 Claude 계정이 릴레이 서비스를 사용하도록 인증합니다. ‘Generate Authorization Link’ 버튼을 클릭하세요:

생성된 링크가 입력 필드에 나타납니다. 예: https://claude.ai/oauth/authorize?.... 오른쪽의 복사 아이콘을 클릭하여 링크를 복사하세요.

그런 다음 브라우저에서 이 링크를 여세요 (프록시를 사용하는 것을 잊지 마세요):

페이지에 ‘Claude Code would like to connect to your Claude chat account’가 표시됩니다. Authorize 버튼을 클릭하여 인증을 완료하세요.

인증이 성공하면 페이지에 Authorization Code가 제공됩니다. 이 코드를 복사하여 대화상자의 입력 필드에 붙여넣고 ‘Complete Authorization’을 클릭하세요.

이제 계정이 연결되었습니다.

2단계: API 키 생성

계정을 연결한 후 상단의 ‘API Keys’ 탭을 클릭하여 API 키 관리로 들어갑니다:

오른쪽 상단의 ‘+ Create New Key’ 버튼을 클릭하세요:

다음 정보를 입력하세요:

이름: 이 키에 이름을 지정하세요. 예: ‘개인용’, ‘가족용’. 나중에 관리하기 쉽도록 사람이나 용도별로 이름을 지정하는 것이 좋습니다.
속도 제한 설정 (선택 사항): 여러 사람이 공유하는 경우 각 키에 대해 요청 빈도와 비용 제한을 설정할 수 있습니다. 무제한으로 하려면 비워 두세요.

작성을 완료한 후 Confirm을 클릭하세요. 생성이 성공하면 다음 대화상자가 나타납니다:

중요 알림: 전체 API 키를 볼 수 있는 유일한 기회입니다. 이 창을 닫으면 시스템이 다시 표시하지 않습니다.

‘Copy Claude Configuration‘을 클릭하면 다음과 같은 내용을 얻을 수 있습니다:

export ANTHROPIC_BASE_URL="your_server_public_url"
export ANTHROPIC_AUTH_TOKEN="cr_217627747170e5aa5691134fab8278b0dfec1b0ac2e59345ae180dc6d5f9643d"

이것이 API 주소와 키입니다. 안전하게 저장하세요.

다음에 사용하는 방법

ANTHROPIC_BASE_URL과 ANTHROPIC_AUTH_TOKEN을 확보한 후에는 API 호환 클라이언트에서 사용할 수 있습니다.

Claude Code에서 구성하는 방법은 Claude Code 설정 가이드를 참조하세요.

저도 이 설정을 직접 사용하고 있으며 배포 이후 계정이 차단되지 않았습니다.

요약

오늘 배운 내용:

자체 릴레이를 구축하는 이유: 차단 방지를 위한 고정 IP, 다중 사용자 공유, 데이터 보안에 대한 완전한 통제.
사용할 프로젝트: claude-relay-service, 오픈소스 자체 호스팅.
배포 방법: 하나의 명령어로 모든 것이 완료됩니다; 설치 후 공개 URL과 관리자 비밀번호를 얻습니다.
계정 연결 과정: Account Management → Add Account → Select Claude → 구독 유형 선택 → OAuth 인증.
API 키 생성 과정: API Keys → Create New Key → 이름 입력 → Claude 구성 복사 (한 번만 표시됨!).

핵심 사항:

전체 API 키는 생성 시에만 표시되므로 즉시 복사하여 저장하세요.
올바른 구독 유형을 선택하세요: Max와 Pro는 지원하는 모델이 다릅니다; Pro는 Opus 4를 지원하지 않습니다.
인증 중에는 프록시를 사용하는 것을 잊지 마세요; 브라우저와 서버가 동일한 프록시를 사용하는 것이 가장 좋습니다.