james-6-23/codex2api

Codex2API 是一个基于 Go + Gin + React/Vite 的 Codex 反向代理与管理后台项目

Codex2API – 풀링된 Codex 계정용 OpenAI 호환 게이트웨이

무엇인가요 – Codex2API는 여러 개의 Codex(OpenAI 스타일) 리프레시 토큰 또는 액세스 토큰 계정을 하나의 프로덕션 준비 완료된 API 엔드포인트로 통합하는 자체 호스팅 서비스입니다. OpenAI/Anthropic HTTP 경로(/v1/chat/completions, /v1/images/..., /v1/models 등)를 지원하면서 토큰 갱신, 건강 점수, 동적 병렬 처리, 레이트 제한 복구, 사용 기반 요금 청구, 관리 작업을 모두 처리합니다.

왜 중요한가요 – 많은 개발자들이 할당량 제한을 회피하기 위해 여러 개인 Codex 계정을 확보합니다. 이러한 토큰을 수동으로 관리하는 것은 실수를 유발하고 보안상 위험합니다. Codex2API는 풀을 자동화하고 가장 건강한 계정에 요청을 스케줄링하며, 어떤 클라이언트(Codex CLI, Claude Code, 공식 OpenAI SDK 등)도 호출할 수 있는 통합된 OpenAI 호환 인터페이스를 제공합니다.

핵심 기능

기능	제공되는 기능
통합된 OpenAI 스타일 API	채팅 완성, 응답, 이미지/비디오 생성, 모델 목록, 건강 상태 확인을 위한 엔드포인트가 모두 `/v1/*` 아래에서 사용 가능.
계정 풀 스케줄러	건강 등급, 병렬 처리 제한, 쿨다운, 최근 사용량 기반으로 계정 선택; `round_robin` 및 `remaining_quota` 전략 지원.
관리자 대시보드	React + Vite UI를 통해 토큰 임포트, 계정 테스트, API 키 관리, 프록시 풀, 프롬프트 필터, 사용량 분석, 시스템 설정을 관리.
두 가지 배포 형태	프로덕션 모드: PostgreSQL + Redis; 가벼운 모드: SQLite + 메모리 캐시(단일 컨테이너).
요금 청구 및 관찰성	계정별 USD 비용 추적(5시간/7일 슬라이딩 윈도우), 크레딧-쿼터 플래그, API 키 사용 로그, 트렌드 차트, 요청 로그.
OAuth PKCE 흐름	표준 OAuth PKCE 교환을 통해 리프레시 토큰을 획득할 수 있는 내장 엔드포인트. 수동 토큰 추출을 피함.
Docker 준비	프로덕션용 공식 `docker-compose.yml` 외에도 로컬 소스 빌드 및 SQLite 전용 배포용 변형 제공.

빠른 시작 (Docker, 프로덕션 모드)

# 리포지토리 클론 및 진입
git clone https://github.com/james-6-23/codex2api.git && cd codex2api

# 환경 템플릿 복사 및 필요 시 편집
cp .env.example .env   # DB 비밀번호, ADMIN_SECRET 등을 설정

# 이미지 다운로드 및 스택 시작
docker compose pull
docker compose up -d

# 로그 감시
docker compose logs -f codex2api

관리자 UI는 http://localhost:8080/admin/에서 접근 가능 (ADMIN_SECRET로 보호됨).

PostgreSQL/Redis 없이 단일 노드 설정을 원한다면 SQLite 컴포즈 파일 사용:

cp .env.sqlite.example .env
docker compose -f docker-compose.sqlite.yml up -d

API 사용 방법

모든 엔드포인트는 OpenAI 사양을 따르므로 기존 SDK는 즉시 사용 가능. 채팅 완성 예시:

curl https://your-host/v1/chat/completions \
  -H "Authorization: Bearer <your‑public‑api‑key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Hello"}]}'

공개 API 키가 설정되지 않은 경우 게이트웨이는 키 검증을 건너뜁니다.

관리

토큰 임포트 – POST /api/admin/accounts (리프레시 토큰) 또는 /api/admin/accounts/at (액세스 토큰). 단일 또는 배치(줄바꿈 구분) 업로드 지원.
파일 임포트 – TXT 또는 JSON 토큰 파일용 멀티파트 /api/admin/accounts/import.
OAuth PKCE – 인증 URL 생성, 브라우저에서 흐름 완료 후 /api/admin/oauth/exchange-code로 코드 교환.
API 키 – /admin/api-keys에서 클라이언트별 키 생성. 키는 DB에 저장되며 취소 가능.
스케줄러 설정 – 설정 페이지에서 SchedulerMode, MaxConcurrency, GlobalRPM 등을 조정. 변경 사항은 모든 실행 중인 인스턴스에 즉시 반영.

관찰성 및 요금 청구

대시보드는 요청량, 지연 시간, 토큰 건강 상태, 모델 사용량을 표시.
계정별 비용 추적(USD)은 5시간/7일 슬라이딩 윈도우 사용; 크레딧-쿼터 플래그로 지출 제한 가능.
Redis 캐시(또는 메모리 대체)는 연속 호출(previous_response_id)을 지원하기 위해 최근 응답 컨텍스트를 저장.

어떤 배포를 선택해야 할까?

상황	추천 모드
많은 계정을 다루는 프로덕션 서비스, 지속성과 수평 확장 필요	PostgreSQL + Redis (표준 컴포즈)
소규모 개인 사용, 빠른 테스트, 또는 CI 파이프라인	SQLite + 메모리 (sqlite 컴포즈)
Go 백엔드 또는 React UI를 수정하고 싶은 경우	`docker-compose.local.yml` (또는 `docker-compose.sqlite.local.yml`)을 사용해 소스에서 빌드

커뮤니티 및 지원

이슈 및 기여 – PR 워크플로우는 docs/CONTRIBUTING.md 참조.
데모 – 공개 데모는 https://codex2api‑latest‑vu8j.onrender.com에 호스팅됨 (비밀번호: codex2api). UI 탐색용으로만 사용. 실제 토큰은 업로드하지 마세요.
스폰서 – FastAIToken, AiXor, 星辰·AI가 스폰서로 등재되어 있으며, 상용 AI-API 게이트웨이 서비스를 제공합니다.

라이선스 및 면책 조항

리포지토리는 MIT 라이선스로 배포됩니다. 저자들은 데모를 실제 자격 증명과 함께 사용하지 말 것을 경고하며, 토큰 풀 게이트웨이를 운영하는 것은 하위 제공자의 이용 약관을 위반할 수 있다고 경고합니다.

결론 – Codex2API는 여러 Codex 계정을 통합하고 표준 OpenAI 호환 API를 제공하며, 토큰 관리, 요금 청구, 관찰성에 풍부한 관리자 UI를 제공하는 완전 기능의 Docker 준비 게이트웨이입니다. 더 높은 처리량이 필요하거나, 자체 스케줄러를 작성하지 않고도 토큰 관리를 중앙화하고 싶은 팀에게 적합합니다.