Soju06/codex-lb

codex‑lb – ChatGPT 계정용 로드 밸런서 및 프록시

무엇인가요

• OpenAI 호환 클라이언트(Codex CLI, OpenCode, 공식 OpenAI Python SDK 등)와 하나 이상의 ChatGPT 계정 사이에 위치하는 자체 호스팅 서비스입니다.
• 요청을 계정 풀에 분산하고, 각 계정의 토큰 사용량과 비용을 추적하며, API 키별로 요청 제한을 설정할 수 있습니다.
• 이 모든 기능은 인증(비밀번호 + 선택적 TOTP)이 필요한 웹 대시보드에서 확인할 수 있습니다.

주요 기능

기능	설명
계정 풀링	여러 ChatGPT 계정을 등록하고, 각 요청에 대해 가장 적합한 계정을 선택하여 전체 할당량을 효과적으로 늘립니다.
사용량 추적	SQLite(기본값) 또는 PostgreSQL 데이터베이스에 계정별 토큰 수, 비용, 28일 간의 추세를 저장합니다.
API 키 관리	토큰 수, 비용, 시간 창, 모델 등 사용자 정의 제한을 가진 키를 생성하여 다른 사용자나 서비스에 프록시를 공개할 때 보호할 수 있습니다.
OpenAI 호환 엔드포인트	공식 OpenAI API를 기대하는 모든 클라이언트와 호환되는 /v1 및 /backend-api/codex 엔드포인트를 제공합니다.
대시보드	웹 UI(기본값: http://localhost:2455)를 통해 계정, 사용량 그래프, 키 관리를 확인할 수 있습니다.
자동 모델 동기화	OpenAI에서 사용 가능한 모델 목록을 가져와 프록시가 각 계정이 제공할 수 있는 모델을 항상 파악할 수 있도록 합니다.
어디서든 배포 가능	Docker 이미지, uvx 단일 명령어, Nix 패키지 지원; Kubernetes 배포도 가능합니다.

빠른 시작(Docker, 권장 방법)

# SQLite DB용 지속성 볼륨 생성
docker volume create codex-lb-data
# 선택 사항: 컨테이너용 격리 네트워크
docker network create codex-lb-net
# 최신 이미지 실행
docker run -d --name codex-lb \
  --network codex-lb-net \
  -p 2455:2455 -p 1455:1455 \
  -v codex-lb-data:/var/lib/codex-lb \
  ghcr.io/soju06/codex-lb:latest

http://localhost:2455를 열고 첫 번째 ChatGPT 계정을 추가한 후, 어떤 클라이언트든 프록시로 연결할 수 있습니다.

클라이언트 설정 예시 (Codex CLI)

model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
model_provider = "codex-lb"

[model_providers.codex-lb]
name = "openai"
base_url = "http://127.0.0.1:2455/backend-api/codex"
wire_api = "responses"
supports_websockets = true
requires_openai_auth = true

OpenCode, OpenClaw, 공식 OpenAI Python SDK 및 기타 도구에 대해 유사한 설정 절차가 존재하며, 모두 https://soju06.github.io/codex-lb/에 문서화되어 있습니다.

구성

• 설정은 CODEX_LB_로 시작하는 환경 변수 또는 .env.local 파일에서 읽습니다. 예시 파일(.env.example)이 제공됩니다.
• 기본적으로 SQLite가 사용됩니다(Docker 내 /var/lib/codex-lb). 더 큰 규모의 배포에서는 CODEX_LB_DATABASE_URL을 PostgreSQL 인스턴스로 지정할 수 있습니다.

개발

• 백엔드는 uv run codex-lb로 실행합니다(포트 2455에서 대기).
• 프론트엔드(React/Vite)는 frontend 폴더에 있으며, bun run dev(포트 5173)로 실행하여 핫 리로딩을 사용할 수 있습니다.
• Docker Compose 감시 모드와 Nix flakes도 지원됩니다.

왜 사용하고 싶을까

• 할당량 확장: 여러 개인 또는 팀용 ChatGPT 계정이 있다면, codex‑lb를 통해 하나의 논리적 API 엔드포인트로 사용할 수 있습니다.
• 비용 시각화: 각 계정이 얼마나 많은 토큰을 사용했는지, 그에 따른 금전적 비용을 정확히 확인할 수 있습니다.
• 안전성: 팀원이나 CI 파이프라인에 범위 제한된 API 키를 발급하여 한 사용자가 전체 풀을 고갈시키는 것을 방지할 수 있습니다.
• 호환성: 기존의 OpenAI 호환 도구에 코드 변경 없이 새 기준 URL로 연결만 하면 됩니다.

추가 정보

• 전체 문서, 문제 해결 및 배포 가이드: https://soju06.github.io/codex-lb/.
• macOS, Linux, Home Assistant 등에 대한 커뮤니티 제작 상태바 통합 기능은 README에 나와 있습니다.