CPA 프록시 배포 가이드: CLIProxyAPI + NewAPI 계정 풀

게시일: 2026-06-07

개발자와 사이트 운영자를 위한 실무 CPA 프록시 배포 가이드: CLIProxyAPI, NewAPI, 계정 풀, 배포, 클라이언트 설정, 보안 점검, 문제 해결.

짧은 요약

CPA 프록시를 만들 때 어려운 부분은 보통 “어떤 패널을 설치할까”가 아닙니다. 진짜 문제는 Codex, Claude Code, Gemini CLI, Grok Build, 또는 OpenAI 호환 업스트림을 관리·라우팅하고 NewAPI, 팀 이용자, 코딩 에이전트에 넘길 수 있는 안정적인 API로 바꾸는 방법입니다.

흔한 CPA 프록시 구조는 다음과 같습니다.

이 구성은 통제 가능한 계정 풀 API 게이트웨이가 필요한 개발자, 소규모 팀, 사이트 운영자에게 가장 유용합니다. 개인적으로 쓰거나, 팀 안에서 나누거나, 여러 업스트림을 시험하거나, 프록시 공급망이 어떻게 동작하는지 연구할 수 있습니다. 공개할 계획이면 이용자를 올리기 전에 남용 방지, 자격 증명 분리, 접근 제어, 정책 경계를 먼저 정리하세요.

CPA 프록시란?

CPA는 보통 CLIProxyAPI의 줄임말로 씁니다. 프로젝트는 CLIProxyAPI를 CLI 도구에 OpenAI, Gemini, Claude, Codex, Grok 호환 API 엔드포인트를 제공하는 프록시 서버로 설명합니다. OAuth 로그인, 다중 계정 순환, 스트리밍 응답, 함수 호출, 멀티모달 입력, OpenAI 호환 업스트림 서비스를 지원합니다.

CPA + NewAPI 구조에서 역할은 보통 다음과 같습니다.

계층	책임
계정 계층	Codex, Claude Code, Gemini CLI, Grok Build, AI Studio, OpenAI 호환 업스트림
CPA 계층	계정, OAuth 세션, 업스트림 키를 통합 API로 바꿉니다
NewAPI 계층	채널, 사용자, 토큰, 한도, 모델 요금, 공개 엔드포인트를 관리합니다
클라이언트 계층	Claude Code, Codex, Cursor, OpenCode, Cherry Studio, SDK

완전한 CPA 프록시에는 보통 두 계층이 있습니다. CPA는 “계정이 어떻게 API가 되나?”에 답합니다. NewAPI는 “그 API를 이용자에게 어떻게 나누나?”에 답합니다. 비공개 사용만 필요하면 CPA만으로 시작하세요. 여러 사람이 접근해야 하면 배포 계층을 추가합니다.

CPA + NewAPI를 쓸 때

첫날부터 시스템을 무겁게 만들지 마세요. CPA + NewAPI는 팀 배포를 풀 수 있지만, 설정, 보안, 디버깅 비용도 늘어납니다.

목표	권장 구성
계정 하나를 자기용 API로 바꾸기	CPA만 배포
2-10명 팀에 통합 키 하나 발급	CPA + NewAPI, 또는 CPA + 가벼운 패널
Codex, Claude Code, Gemini CLI 등 소스를 합치기	CPA + NewAPI가 더 맞습니다
가입, 충전, 한도, 요금을 운영	NewAPI 같은 배포 계층이 보통 필요합니다
구독 계정 용량을 공개 재판매	플랫폼 약관, 리스크 관리, 자격 증명 분리를 이해하기 전에는 피하세요

첫 배포에서는 자신만 접근할 수 있는 로컬 또는 비공개 버전을 만드세요. 계정 하나, 모델 하나, 클라이언트 하나를 씁니다. CPA 호출이 되고, NewAPI 채널 시험이 통과하고, 클라이언트가 엔드포인트를 안정적으로 쓴 뒤에 도메인, Cloudflare, 과금, 사용자 관리를 추가하세요.

배포 전

준비할 것:

Linux 서버. Ubuntu 22.04 이상이 좋고, 최소 2 vCPU와 2 GB RAM.
Docker와 Docker Compose v2.
이후 NewAPI 또는 공개 API 엔드포인트용 도메인.
사용이 허용된 업스트림 계정 또는 API 키.
위험이 낮은 시험 API 키. 한도가 큰 메인 계정 키로 시작하지 마세요.

권장 포트:

서비스	흔한 포트	권장
CPA / CLIProxyAPI	`8317`	NewAPI 또는 신뢰할 수 있는 IP에만 노출
NewAPI	`3000`	앞에 HTTPS와 도메인을 둡니다
Nginx / Caddy	`80` / `443`	TLS와 리버스 프록시를 처리

CPA와 NewAPI가 같은 서버에서 돌면 CPA를 localhost 또는 사설망에 묶는 편이 낫습니다. 공개 진입점은 보통 CPA 관리 화면이 아니라 NewAPI여야 합니다.

1단계: CLIProxyAPI, CPA 계층 배포

공식 프로젝트는 macOS, Linux, Windows, Docker, Docker Compose를 지원합니다. 사이트 운영에는 Docker Compose가 설정, 인증 파일, 백업을 다루기 쉬워 더 분명한 선택인 경우가 많습니다.

최소 Docker 명령은 비슷합니다.

docker run --rm \
  -p 8317:8317 \
  -v /path/to/your/config.yaml:/CLIProxyAPI/config.yaml \
  -v /path/to/your/auth-dir:/root/.cli-proxy-api \
  eceasy/cli-proxy-api:latest

Docker Compose에서는 보통 저장소를 클론하고 config.example.yaml을 config.yaml로 복사한 뒤 서비스를 시작합니다.

git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI
cp config.example.yaml config.yaml
docker compose up -d

먼저 로그를 확인합니다.

docker compose logs -f

NewAPI를 바로 연결하지 마세요. 먼저 CPA 자체가 올바르게 기동하는지 확인한 뒤 계정 로그인과 업스트림 설정을 처리합니다.

2단계: 기본 CPA 보안 설정

CPA는 요청 인증, 구성, 계정 자격 증명을 다룹니다. 일반 블로그 관리 패널보다 더 심각하게 다루세요.

config.yaml에서 먼저 이 필드를 확인합니다.

host: "127.0.0.1"
port: 8317

remote-management:
  allow-remote: false
  secret-key: "replace-with-a-strong-random-admin-secret"

auth-dir: "~/.cli-proxy-api"

api-keys:
  - "replace-with-a-strong-random-key-for-newapi"

debug: false
logging-to-file: true
usage-statistics-enabled: true

요점은 블록을 무작정 복사하지 않는 것입니다. 경계를 이해하세요.

host가 127.0.0.1이면 CPA는 로컬 트래픽만 받습니다. NewAPI가 같은 기계에서 돌 때 맞습니다.
remote-management.allow-remote를 함부로 켜지 마세요. 관리 API는 런타임 구성과 인증 파일을 바꿀 수 있습니다.
강한 난수 secret-key를 쓰세요. admin, 123456, 프로젝트 이름은 쓰지 마세요.
api-keys는 CPA 서비스 인증 계층입니다. NewAPI는 CPA를 호출할 때 이 키 중 하나를 씁니다.
auth-dir은 자격 증명을 저장합니다. 신중히 백업하고 권한을 좁히세요.

NewAPI와 CPA가 다른 서버에 있으면 포트 8317을 인터넷 전체에 열지 마세요. 최소한 방화벽 허용 목록, 리버스 프록시 인증, 강한 키, 로그 감사를 쓰세요.

3단계: 로그인 또는 업스트림 계정 추가

CPA는 여러 업스트림 종류를 지원합니다. 사이트 운영에서 가장 흔한 대상은 Codex, Claude Code, Gemini CLI, OpenAI 호환 서비스입니다.

Docker Compose 배포의 공식 로그인 명령에는 다음이 있습니다.

# OpenAI Codex
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --codex-login

# Claude Code
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --claude-login

# Gemini CLI
docker compose exec cli-proxy-api /CLIProxyAPI/CLIProxyAPI -no-browser --login

-no-browser는 로그인 URL을 출력하므로 서버에서 유용합니다. 로그인 후 인증 파일은 마운트한 auth-dir에 기록됩니다. 그 디렉터리가 계정 풀의 핵심 자산입니다.

OpenRouter나 다른 호환 Base URL 같은 OpenAI 호환 업스트림을 쓰면 base-url, api-key, 모델 목록, 별칭을 포함한 프로바이더 구성을 추가합니다.

4단계: NewAPI를 붙이기 전에 CPA 시험

NewAPI에 연결하기 전에 가능한 한 작은 CPA 요청을 만드세요. CPA가 로컬 포트 8317에서 열려 있고 CPA_API_KEY를 설정했다고 가정합니다.

export CPA_BASE_URL="http://127.0.0.1:8317/v1"
export CPA_API_KEY="the api key from config.yaml"

curl -sS "$CPA_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $CPA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5-codex",
    "messages": [
      {
        "role": "user",
        "content": "Reply with exactly: cpa-ok"
      }
    ],
    "stream": false
  }'

이게 실패하면 아직 NewAPI를 건드리지 마세요. 먼저 CPA를 디버깅합니다.

오류	먼저 확인할 것
401	CPA API 키가 `config.yaml`과 맞는지
404	Base URL에 `/v1`이 들어가야 하는지, 모델 이름이 있는지
429	업스트림 계정이 속도 제한이거나 한도를 넘었는지
502 / 503	업스트림 로그인 세션, 프록시, 네트워크, 계정 상태
HTML 응답	요청이 잘못된 리버스 프록시 주소나 패널 포트에 닿았을 가능성이 큽니다

5단계: CPA를 NewAPI에 연결

NewAPI는 CPA를 관리 가능한 채널로 바꿉니다. 흔한 흐름은 다음과 같습니다.

NewAPI 관리 패널에 로그인합니다.
채널 관리를 열고 새 채널을 추가합니다.
OpenAI 호환 채널 종류, 또는 가장 가까운 호환 종류를 고릅니다.
Base URL을 CPA 주소로 설정합니다. 예: http://127.0.0.1:8317/v1.
키를 CPA의 api-keys 중 하나로 설정합니다.
NewAPI가 노출할 모델 목록을 추가합니다.
저장하고 채널 시험을 실행합니다.
NewAPI 토큰을 만든 뒤 이용자에게 NewAPI Base URL과 토큰을 줍니다.

두 서비스가 같은 서버에서 돌면 NewAPI는 127.0.0.1 또는 Docker 네트워크 서비스 이름으로 CPA에 닿을 수 있습니다. 공개 이용자에게 CPA 키를 직접 주지 마세요. NewAPI가 발급한 사용자 토큰을 받아야 합니다.

CPA, NewAPI, 클라이언트 필드

Base URL과 API 키를 섞는 것이 가장 흔한 실패 원인입니다. 먼저 맞추세요.

위치	Base URL	API 키	사용 주체
CPA 로컬 시험	`http://127.0.0.1:8317/v1`	`config.yaml`의 CPA `api-keys`	관리자 자체 시험
NewAPI 채널	CPA 비공개/로컬 주소. 예: `http://127.0.0.1:8317/v1`	CPA `api-keys`	CPA를 호출하는 NewAPI
최종 사용자 클라이언트	공개 NewAPI 주소. 예: `https://api.example.com/v1`	NewAPI가 발급한 사용자 토큰	Codex, Claude Code, Cursor, SDK
피할 것	공개된 CPA 주소	CPA 하위 키	최종 사용자

한 줄 요약: CPA 키는 최종 사용자가 아니라 NewAPI에 주세요. 최종 사용자는 NewAPI Base URL과 토큰을 써야 합니다.

6단계: 개발자 클라이언트에서 쓰기

CPA 프록시의 목적은 개발 도구가 안정적으로 연결되게 하는 것입니다. 클라이언트마다 프로토콜 세부 사항이 다릅니다.

Codex

공식 Codex 클라이언트 설정은 보통 ~/.codex/config.toml과 ~/.codex/auth.json을 씁니다. CPA에 직접 연결하면 base_url은 흔히 다음과 같습니다.

model_provider = "cliproxyapi"
model = "gpt-5.5"
model_reasoning_effort = "high"

[model_providers.cliproxyapi]
name = "cliproxyapi"
base_url = "http://127.0.0.1:8317/v1"
wire_api = "responses"

auth.json:

{
  "OPENAI_API_KEY": "sk-dummy"
}

이용자가 NewAPI를 거치면 base_url을 공개 NewAPI 주소로, 키를 NewAPI 토큰으로 바꿉니다.

OAuth 로그인 모드를 쓰면 공식 예시에 experimental_bearer_token, requires_openai_auth, supports_websockets 같은 필드가 있을 수 있습니다. 모든 옵션을 한 번에 섞지 마세요. 모드 하나를 골라 검증한 뒤 모델과 추론 수준을 조정합니다.

Claude Code

Claude Code는 보통 다음과 같은 환경 변수를 씁니다.

export ANTHROPIC_BASE_URL="http://127.0.0.1:8317"
export ANTHROPIC_AUTH_TOKEN="your working key"
export ANTHROPIC_DEFAULT_OPUS_MODEL="gpt-5-codex(high)"
export ANTHROPIC_DEFAULT_SONNET_MODEL="gpt-5-codex(medium)"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="gpt-5-codex(low)"

중요: 평범한 OpenAI 채팅 요청이 된다고 Claude Code가 된다고 증명되지 않습니다. Claude Code는 모델 이름, 스트리밍 동작, Anthropic 호환 동작에 더 민감합니다. 따로 시험하세요.

CC Switch

공식 API, NewAPI, CPA, 로컬 모델을 자주 바꾸면 검증된 Base URL과 키를 CC Switch에 넣으세요. 순서가 중요합니다. 먼저 직접 확인한 뒤 구성을 프로필 관리자에 넘깁니다.

흔한 CPA 프록시 구조

비공개 구조

flowchart TD client("로컬 클라이언트") cpa("CPA") upstream("Codex / Claude Code / Gemini CLI / 호환 업스트림") client -->|"로컬 호출"| cpa cpa -->|"계정 라우팅"| upstream

개인 개발자 사용에 가장 맞습니다. 단순하고 실패 지점이 적습니다.

소규모 팀 구조

2-20명에 가장 맞습니다. NewAPI가 키를 발급하고 한도를 제한하며 사용량을 추적합니다. CPA가 계정 풀을 관리합니다.

공개 배포 구조

공개 배포를 하면 어려운 부분은 더 이상 CPA 배포만이 아닙니다. 결제, 남용, 로그, 백업, 계정 장애, 지원도 처리해야 합니다.

공개 전 점검표

항목	통과 기준
CPA 관리 API	공개되지 않음, 강한 시크릿, 가능하면 localhost 또는 허용 목록만
CPA API 키	관리 시크릿과 다른 강한 난수 키
인증 디렉터리	백업됨, 권한 통제, 공개 저장소에 커밋하지 않음
NewAPI 채널	채널 시험 통과. 모델 목록과 요금을 추측하지 않음
클라이언트 시험	curl, Codex, Claude Code에서 최소 요청이 통과
로그	실패는 보이되, 평문 사용자 키는 기록하지 않음
남용 방지	사용자별 한도, 속도 제한, 이상 요청 처리가 있음
도메인과 인증서	공개로는 HTTPS만 노출

흔한 함정

1. CPA와 NewAPI Base URL을 섞기

CPA 패널 주소, CPA API 주소, 공개 NewAPI 주소는 같은 것이 아닙니다.

주소	용도
`http://127.0.0.1:8317`	CPA 서비스 또는 관리 패널
`http://127.0.0.1:8317/v1`	흔한 OpenAI 호환 CPA API 주소
`https://api.example.com/v1`	이용자용 공개 NewAPI 엔드포인트

클라이언트가 잘못된 주소를 쓰면 증상은 종종 404, HTML 응답, 모델 누락입니다.

2. CPA 키를 이용자에게 직접 주기

사이트를 운영한다면 하위 CPA 키를 최종 이용자에게 주지 마세요. 이용자는 NewAPI 토큰을 받아야 합니다. CPA 키가 새면 누군가 사용자, 한도, 과금 계층을 우회할 수 있습니다.

3. 답장이 오는지만 시험하기

프록시가 짧은 메시지 하나에 답하면, 가장 작은 채팅 요청만 증명한 것입니다. 개발자는 다음도 시험해야 합니다.

스트리밍이 안정적인지.
Codex Responses API 동작이 되는지.
Claude Code Anthropic 호환 변수가 적용되는지.
긴 컨텍스트가 잘리는지.
NewAPI 사용량과 과금이 반환된 사용량과 대략 맞는지.

4. 원격 관리를 너무 일찍 켜기

CLIProxyAPI의 관리 API는 런타임 구성과 인증 파일을 관리할 수 있습니다. 공식 문서도 관리 API 요청에 관리 시크릿이 필요하다고 적습니다. 원격 관리 자체가 금지된 것은 아니지만, 인터넷에 그대로 여는 것은 무모합니다.

5. 계정 풀을 SLA처럼 다루기

다중 계정 순환은 단일 계정 속도 제한을 줄일 수 있지만, 신뢰성과는 다릅니다. 업스트림 규칙 변경, 계정 리스크 관리, OAuth 만료, 모델 삭제로 CPA 프록시가 갑자기 깨질 수 있습니다.

흔한 오류 문제 해결

증상	먼저 확인할 것
401 Unauthorized	잘못된 키, 또는 CPA 직접 시험에서 NewAPI 사용자 키를 사용
404 Not Found	Base URL 계층이 틀림. 종종 `/v1`이 없거나 패널 주소에 닿음
429 Too Many Requests	업스트림 계정이 속도 제한이거나 한도를 넘었거나, 클라이언트가 너무 자주 재시도
502 / 503	CPA 업스트림 로그인 만료, 프록시/네트워크 문제, 또는 계정 사용 불가
HTML 응답	요청이 NewAPI 패널, Nginx 기본 페이지, 또는 잘못된 도메인에 닿음
Model not found	CPA 모델 이름, NewAPI 모델 매핑, 클라이언트 모델 이름이 맞지 않음
curl은 되고 Claude Code / Codex는 실패	프로토콜, 스트리밍, Responses API, 또는 Anthropic 호환 동작 불일치

디버깅 순서

문제가 나면 NewAPI 패널 필드를 반복해서 바꾸지 말고 이 체인을 디버깅하세요.

업스트림 계정 상태: 로그인 세션, 한도, 차단, 리전, 프록시.
CPA 상태: 로그, 구성, 모델 이름, API 키, 인증 디렉터리.
CPA 최소 curl: NewAPI 전에 CPA를 시험합니다.
NewAPI 채널: Base URL, 키, 모델 매핑, 채널 상태.
클라이언트 동작: Codex, Claude Code, Cursor 프로토콜과 환경 변수.
리버스 프록시: Nginx, Cloudflare, HTTPS, 헤더, 타임아웃.

이 순서가 시간을 아낍니다. 많은 “모델 사용 불가” 실패는 클라이언트 설정 버그처럼 보이지만, 실제 원인은 종종 CPA 로그인 상태, Base URL, 업스트림 계정 상태입니다.

권장 최종 구성

사용 사례	권장 구성	경계
개인 개발자 사용	CPA만 + 로컬 클라이언트 직접 연결	계정, 모델, 클라이언트를 검증하는 가장 단순한 방법
소규모 팀	CPA + NewAPI + 내부 토큰 + 허용 목록 접근	공유 Base URL, 토큰, 한도 관리에 맞음
소규모 공개 배포	비공개 CPA + 공개 NewAPI + HTTPS + 한도 제한 + 로그 감사	통제된 시험은 가능하나 규모와 업스트림 리스크를 관리
피할 것	공개 CPA + 약한 관리 시크릿 + 이용자에게 CPA 키 직접 지급 + 남용 방지 없음	사용자, 한도, 접근 제어 계층을 우회. 실제 운영에 부적합