Claude Code, Codex, Gemini 및 OpenAI 호환 클라이언트를 위한 자체 호스팅 AI API 게이트웨이

클로드 코드(Claude Code), 코덱스(Codex), 제미나이(Gemini) 및 OpenAI 호환 클라이언트를 위한 자체 호스팅 AI API 게이트웨이.

▶ 47초 개요 보기 · 중국어 버전

사용자는 여러 개의 AI 소스를 가질 수 있습니다. 공식 API 키, 타사 리레이 서비스, ChatGPT 또는 Claude 구독 등이 그것입니다. 각 클라이언트마다 별도로 설정해야 하며, 하나의 할당량(quota)이 소진되거나 상위(upstream) 시스템에 문제가 생기면 실행 중인 Claude Code나 Codex 세션이 중단됩니다.

ccLoad는 사용자의 컴퓨터나 서버에서 실행하는 게이트웨이입니다. 이 게이트웨이는 모든 소스를 관리하며, 모든 클라이언트는 ccLoad 주소와 ccLoad 토큰만 필요합니다:

Claude Code / Codex / Gemini / OpenAI-compatible tools
│ 하나의 주소 + 하나의 ccLoad 토큰
▼
...

아래 단계 전반에 걸쳐 세 가지 용어가 사용됩니다.

채널(Channel): "리레이 서비스의 URL 및 키" 또는 "로그인된 Codex 계정"과 같은 단일 상위 소스입니다. 각 채널은 제공하는 모델 목록을 나타냅니다.API 토큰(API token): ccLoad가 클라이언트에게 부여하는 키입니다. 클라이언트는 이 토큰으로만 ccLoad와 통신하며 실제 상위 키는 절대 볼 수 없습니다.관리 콘솔(Admin console): http://your-host:8080/web/에 접속하여 관리자 비밀번호 CCLOAD_PASS로 로그인하면 채널을 추가하고, 토큰을 생성하며, 로그와 비용을 확인할 수 있습니다.

여러 AI 구독을 가진 개발자: ChatGPT, Claude 및 기타 플랜과 여분의 API 키를 결합하여, 하나의 할당량이 소진되어도 Claude Code와 Codex가 계속 실행되도록 합니다.모델 접근 권한을 공유하는 팀: 각 팀원에게 모델, 예산, 동시성 제한이 있는 토큰을 부여합니다. 상위 인증 정보는 한 곳에 보관되며 언제든지 접근 권한을 취소할 수 있습니다.많은 채널을 운영하는 운영자: 우선순위, 상태 기반 정렬(health-based ordering), 예약 확인, CSV 가져오기 및 내보내기 기능을 통해 채널을 관리하고 모든 요청에 대한 로그 항목을 기록합니다.

ccLoad를 통해 Claude Code 또는 Codex를 작동시키는 데 필요한 다섯 가지 단계가 있습니다.

하나의 방법을 선택하십시오. 모든 방법은 관리자 비밀번호 CCLOAD_PASS를 요구하며, 이것이 없으면 서비스는 즉시 종료됩니다. 이 서비스는 기본적으로 포트 8080에서 리스닝합니다.Docker (권장):

데이터는 Docker 볼륨 ccload_data에 저장되므로 컨테이너를 제거하거나 업그레이드해도 데이터가 유지됩니다.

Docker Compose:

curl -o docker-compose.yml https://raw.githubusercontent.com/caidaoli/ccLoad/master/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/caidaoli/ccLoad/master/.env.docker.example
# .env 파일을 수정하고 CCLOAD_PASS를 관리자 비밀번호로 설정합니다.
...

Homebrew (macOS / Linux):

brew tap caidaoli/ccload https://github.com/caidaoli/ccLoad.git
brew install caidaoli/ccload/ccload
# 설정 디렉토리에 CCLOAD_PASS=your_admin_password 한 줄로 .env 파일을 생성합니다.
...

바이너리 다운로드: 릴리스(Releases)에서 사용 플랫폼에 맞는 파일을 받으세요 (ccload-linux-amd64, ccload-linux-arm64, ccload-darwin-arm64, ccload-darwin-amd64, ccload-windows-amd64.exe). Linux의 경우:

chmod +x ccload-linux-amd64
CCLOAD_PASS=your_admin_password ./ccload-linux-amd64

데이터는 기본적으로 현재 디렉토리의 data/ccload.db에 저장됩니다.

서버 없이도 Hugging Face Spaces에서 무료로 배포할 수 있습니다. 배포(Deployment) 섹션을 참고하세요.

서비스가 실행 중인지 확인합니다:

curl http://localhost:8080/health

서버의 경우, 이 가이드에 있는 모든 localhost를 서버의 IP 주소 또는 도메인으로 교체하세요.

http://localhost:8080/web/에 접속하여 1단계에서 설정한 CCLOAD_PASS로 로그인합니다.

**채널(Channels)**로 이동하여 **채널 추가(Add Channel)**를 클릭합니다:

API 키 업스트림(공식 API, 중계 서비스): 가장 쉬운 방법은 **자동 채널 구성(Auto-fill channel configuration)**입니다. 제공업체가 준 주소와 키(예: OPENAI_BASE_URL=https://api.example.com 및 OPENAI_API_KEY=sk-...)를 붙여넣으면, ccLoad가 연결을 확인하고 모델 목록을 가져옵니다. 수동으로 양식을 채울 때는 /v1 없이 기본 URL만 입력하세요.

또는 엔드포인트 경로입니다. 구독 계정(Codex/ChatGPT, Claude, Antigravity, xAI, CodeBuddy, Z.ai Coding Plan, Cursor, Zed): Channels에서 계정 유형을 선택하고 프롬프트를 따라 브라우저에서 인증하거나 자격 증명을 가져옵니다.

모델 목록이 채널 사용 여부를 결정합니다. ccLoad는 클라이언트가 요청하는 모델 이름에 따라 채널을 선택합니다. 만약 클라이언트가 claude-sonnet-4-6를 요청한다면, 일부 채널에는 claude-sonnet-4-6가 목록으로 포함되어야 합니다. Fetch Models 또는 Common Models로 모델을 추가하고; 업스트림이 다른 이름을 사용하는 경우, Redirect Target에 업스트림 이름을 넣으세요.

저장 후, 채널에서 Test를 클릭하여 응답하는지 확인합니다.

API 토큰(/web/tokens.html)으로 이동하여 토큰을 생성하고 복사합니다. 모든 클라이언트는 ccLoad에 도달하기 위해 이를 사용하며, 토큰 없이 /v1/* 및 /v1beta/* 요청은 401을 반환합니다.

curl로 먼저 테스트하세요. your-api-token을 4단계의 토큰으로, 모델을 채널에 구성된 모델 중 하나로 대체합니다:

curl -X POST http://localhost:8080/v1/messages \
-H "Content-Type: application/json" \
-H "Authorization: Bearer your-api-token" \
...

Claude Code:

편집

~/.claude/settings.json
(Windows에서는 %USERPROFILE%\.claude\settings.json). 존재하지 않으면 생성하세요. 이미 다른 설정이 있는 경우, 이 두 항목만 env에 병합합니다: { "env": { "ANTHROPIC_BASE_URL": "http://localhost:8080", "ANTHROPIC_AUTH_TOKEN": "your-api-token" } }

주소에서 /v1을 제외하세요. Claude Code가 자체적으로 /v1/messages를 붙입니다. 이 파일의 설정은 모든 터미널 및 IDE 확장 프로그램에 적용되므로 셸 프로필 변경이 필요하지 않습니다. -
모델 이름이 일치하는지 확인하세요. 주 모델 외에도 Claude Code는 Haiku 모델(예: claude-haiku-4-5)을 사용합니다.

) 제목 생성과 같은 백그라운드 작업을 위해, 그리고 이러한 이름들은 채널의 모델 목록에 반드시 나타나야 합니다. 만약 채널에 해당 이름이 없다면, 채널이 가지고 있는 모델을 가리키도록 설정하십시오. 전체 파일은 다음과 같습니다:{ "env": { "ANTHROPIC_BASE_URL": "http://localhost:8080", "ANTHROPIC_AUTH_TOKEN": "your-api-token", "ANTHROPIC_DEFAULT_OPUS_MODEL": "채널에서 가져온 모델 이름", "ANTHROPIC_DEFAULT_SONNET_MODEL": "채널에서 가져온 모델 이름", "ANTHROPIC_DEFAULT_HAIKU_MODEL": "채널에서 가져온 모델 이름" } }

검증: 실행

claude -p "hello"

; 답장이 오면 작동한다는 의미입니다. 대화형 모드에서는 /status를 사용하여 현재 기본 URL을 확인할 수 있습니다.

Codex CLI:

ccLoad 토큰으로 로그인합니다 (이는 Codex의 기존 ChatGPT 로그인을 대체하며, Windows PowerShell에서도 동일한 명령어가 작동합니다):

echo your-api-token | codex login --with-api-key

편집

~/.codex/config.toml
(
Windows에서는 %USERPROFILE%\.codex\config.toml)
파일이 존재하지 않으면 생성하고 아래 내용을 붙여넣으십시오. 이미 내용이 있다면, 두 부분을 분리하여 추가하십시오: model_provider = "ccload" 라인을 파일의 가장 맨 위(어떤 [...] 섹션보다 앞)에 넣어야 합니다 (그렇지 않으면 적용되지 않습니다). 그리고 전체 [model_providers.ccload] 블록을 파일의 끝에 붙여넣으십시오:

model_provider = "ccload"
[model_providers.ccload]
name = "OpenAI"
base_url = "http://localhost:8080/v1"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = true

base_url에는 반드시 /v1이 포함되어야 하며, .requires_openai_auth = true는 Codex가 이전 단계의 토큰을 사용하도록 하고, supports_websockets = true는 Responses WebSocket을 활성화합니다. -
검증: 실행

codex exec --skip-git-repo-check "hello"

; 답장이 오면 작동한다는 의미입니다.앱 서버 데몬(app-server daemon)을 사용하는 경우(예를 들어 codex agents 또는 codex remote-control): 데몬은 장시간 실행되는 프로세스이므로 모든 변경 사항이 즉시 적용되지는 않습니다. config.toml을 편집한 후, 이미 열려 있는 세션은 이전 설정을 유지하며 오직 새로운 세션에서만 변경 사항이 적용됩니다. 또한 codex login을 실행한 후에}<tool_call|>```json
{

새 토큰으로 다시 시작해도 데몬은 재시작할 때까지 이전 토큰을 계속 사용합니다. 설정을 변경하거나 다시 로그인한 후 다음 명령어를 실행하세요: codex app-server daemon restart

데몬이 실행 중인지 확인하려면 다음 명령어를 실행하세요:

codex app-server daemon version

; failed to connect 오류는 실행되고 있지 않다는 의미이며 재시작할 필요가 없습니다.

다른 OpenAI 호환 도구들 (Cherry Studio, SDK 등): 기본 URL을 http://localhost:8080/v1로, API 키를 ccLoad 토큰으로 설정하세요.

클라이언트 프로토콜이 상위 시스템과 일치할 필요는 없습니다. ccLoad가 다를 경우 그 사이에서 변환합니다. 더 많은 엔드포인트와 옵션은 사용 가이드(Usage Guide)에 있습니다.

서비스가 시작 직후 종료되는 경우: CCLOAD_PASS가 설정되지 않았습니다. 비밀번호에 $가 포함된 경우, .env 파일에서 작은따옴표로 감싸세요. 예를 들어 CCLOAD_PASS='abc$def'와 같이 합니다.

요청 반환: 클라이언트가 토큰을 보내지 않거나 잘못 보낸 경우입니다. 4단계의 ccLoad 토큰을 사용하고, 상위 시스템 키나 관리자 비밀번호를 사용하지 마세요.
401: 해당 모델 이름에 대한 채널 목록이 없거나, 사용 가능한 모든 채널이 냉각 중인 경우입니다. 채널의 모델 목록을 확인하고 각 시도 실패 이유를 404 model: xxx 또는 503 no available upstream에서 확인하세요.

로그 페이지: 포트 8080이 사용 중인 경우: PORT 환경 변수를 설정하거나, Docker의 경우 -p의 왼쪽 부분을 변경하세요.다른 기기에서 연결할 수 없는 경우: 방화벽과 포트 매핑을 확인하세요. 공개 배포를 위해서는 ccLoad를 HTTPS 리버스 프록시 뒤에 배치하세요. 보안(Security) 섹션을 참조하세요.

리버스 프록시는 요청을 전달합니다. ccLoad는 긴 응답을 스트리밍하고, 몇 시간 동안 실행되며, 실제 비용이 발생하는 코딩 에이전트를 위해 구축되었으므로, 모든 설계 선택은 세션을 활성화 상태로 유지하고 청구서를 예측 가능하게 만드는 데 중점을 둡니다.

구독 계정, 단순 API 키를 넘어: Codex (ChatGPT), Claude, Antigravity, xAI, CodeBuddy, Z.ai Coding Plan, Cursor 및 Zed 계정을 채널로 로그인합니다. 토큰은 자동으로 새로고침되며, 할당량 사용량은 각 제공업체의 재설정 기간에 맞춰 추적됩니다.모든 업스트림의 모든 클라이언트용: Anthropic Messages, OpenAI Chat, Codex Responses 및 Gemini 클라이언트는 모델을 제공하는 모든 채널을 사용할 수 있습니다. 프로토콜이 다를 경우 (WebSocket을 통한 Codex Responses 포함) 요청과 스트리밍 응답은 변환됩니다.클라이언트가 절대 알지 못하는 장애 복구: 업스트림에서 첫 바이트가 클라이언트에 도달하기 전에 실패하면, ccLoad는 다음 후보로 재시도합니다. HTTP 200으로 위장되거나 SSE 스트림 내의 속도 제한 오류도 실패로 간주됩니다.적절한 범위에서의 냉각 시간: 취소된 키, 속도 제한 모델 또는 만료된 URL은 자체적으로 지수 백오프(exponential backoff)를 통해 냉각되며 업스트림 재설정 시간을 준수합니다. 나머지 채널은 계속 서비스를 제공합니다.확인하고 제한할 수 있는 비용: 가격 책정에는 캐시 읽기 및 쓰기, 긴 컨텍스트 계층, OpenAI service_tier 및 이미지 생성이 포함됩니다. 채널별 일일 지출 한도와 총 토큰당 일일 또는 월간 한도를 설정할 수 있습니다.가볍게 실행 가능: SQLite가 내장되고 빌트인 관리 콘솔을 갖춘 단일 Go 바이너리입니다. MySQL이나 PostgreSQL은 필요할 때만 추가하거나 Hugging Face Spaces에서 무료로 실행할 수 있습니다.우선순위 라우팅: 우선순위가 높은 채널이 먼저 선택되며, 동일한 우선순위의 채널은 건강 기반 동적 정렬과 함께 부드러운 가중치 로빈(smooth weighted round-robin) 방식을 사용합니다.범위 지정 장애 복구: 오류는 키-, 모델-, 채널- 또는 클라이언트 수준으로 분류되며, 실패한 범위만 건너뜁니다. 냉각 시간은 하나의 지수 백오프 정책을 사용하고 명시적인 업스트림 재설정 시간을 준수합니다.모델 인식 냉각 시간: 실패하는 모델은 단독으로 냉각됩니다. 동일 채널의 다른 모델은 계속 사용할 수 있습니다. 모든 구성된 모델 또는 활성화된 키 중 하나라도 냉각될 때만 채널이 냉각됩니다.소프트 오류 감지: 에러 본문을 포함하는 HTTP 200 응답, SSE error

명시적인 속도 제한(rate limits) 및 할당량 오류(quota errors)가 발생하면 일반적인 상위 스트림 실패와 동일한 장애 조치 경로를 트리거합니다.채널별 다중 URL: 독립적인 URL별 쿨다운을 적용하는 지연 시간 가중치 기반 선택 방식입니다.채널 제한: 일일 비용, 분당 요청 수(RPM), 동시성, 사용 가능 시간 창, 키별 모델 허용 목록 등이 채널을 라우팅에서 제외시키지만 쿨다운은 발생하지 않습니다.채널별 상위 스트림 프록시: http/https/socks5/socks5h를 지원하며, 연결 풀이 격리됩니다.예정된 확인(Scheduled checks): 백그라운드 프로빙을 통해 실패한 채널을 감지합니다.

모든 채널에 네 가지 클라이언트 프로토콜: Anthropic, OpenAI, Codex (Responses), 및 Gemini입니다. 각 상위 스트림 URL은 자신이 수락하는 와이어 프로토콜을 선언하거나, ccLoad가 이를 감지하고 캐시합니다. 클라이언트와 상위 스트림이 다를 경우 요청은 프로토콜 간에 변환됩니다.응답 WebSocket: Codex 클라이언트는 다운스트림 WebSocket을 유지하며, 각 후보는 네이티브 Codex WebSocket 또는 HTTP/SSE를 사용합니다.계정 기반 채널: Codex (ChatGPT) OAuth 및 개인 액세스 토큰, Anthropic (Claude), Antigravity, xAI OAuth, Z.ai Coding Plan, Cursor, 및 Zed가 지원됩니다. 여기에는 지원되는 경우 토큰 새로 고침, 일괄 가져오기(batch import), 할당량 새로 고침, 영구적으로 거부된 자격 증명 자동 비활성화 기능이 포함됩니다.모델 사고 접미사 (Model thinking suffix):
model(high)
또는
model(16384)