OpenCodex 프로젝트 분석 — Codex·Claude Code용 멀티 LLM 프록시

OpenCodex는 Codex의 Responses API 요청을 각 LLM 제공자의 프로토콜로 변환하는 경량 로컬 프록시다. Codex CLI, App, SDK 및 Claude Code에서 Anthropic, Google, xAI, Kimi, DeepSeek, GLM, Qwen, Ollama 등을 사용할 수 있게 한다. 스트리밍, 도구 호출, 추론 토큰, 이미지 입력이 양방향으로 변환된다.

1. 시작하기

요구사항

Node.js 18 이상
Bun 런타임은 npm 의존성으로 번들되어 Node 런처를 통해 실행되므로 별도 설치 불필요
주의: npm이 lifecycle 스크립트를 차단한 상태로 설치하면 "bundled Bun runtime is missing" 오류가 발생한다. 이 경우 스크립트 허용 후 재설치하거나 Bun을 직접 설치해야 한다
sudo npm install -g 대신 nvm/fnm 등 사용자 소유 Node 환경 권장

설치 및 실행

# 1. 전역 설치 (Bun 런타임 자동 번들)
npm install -g @bitkyc08/opencodex

# 2. 대화형 초기화 (설정 파일 작성 + Codex 설정 주입 + 자동 시작 shim 설치 안내)
ocx init

# 3. 프록시 시작
ocx start

이후 Codex를 평소대로 사용하면 요청이 opencodex를 경유한다.

codex "Write a hello world in Rust"

대시보드는 http://localhost:10100에서 접근한다.

제거 및 원복

ocx stop        # 프록시 중지, 백그라운드 서비스 중지, Codex 설정 원복
ocx uninstall   # 잔여 설정 정리 (npm 제거 전 실행 권장)
npm uninstall -g @bitkyc08/opencodex

지원 플랫폼

OS	상태	서비스 매니저
macOS (arm64/x64)	지원	launchd
Linux (x64/arm64)	지원	systemd
Windows (x64)	지원 (WSL 불필요)	Task Scheduler

2. 장점

번호	항목	설명
1	모델 자유도	Anthropic, Google, xAI, Kimi, Ollama Cloud, Groq, OpenRouter, Azure, DeepSeek, GLM 및 OpenAI 자체를 포함해 40개 이상의 내장 제공자를 지원한다. 동일한 Codex 워크플로 안에서 모델을 전환할 수 있다
2	어댑터 기반 변환	Anthropic Messages, Google Gemini, Azure, OpenAI Responses 패스스루, OpenAI 호환 Chat Completions의 5개 어댑터로 대부분의 엔드포인트를 흡수한다
3	설치·설정 간소화	프록시 체인을 직접 구성할 필요 없이 `ocx init` 대화형 설정으로 완료된다. xAI, Anthropic, Kimi는 OAuth 로그인을 지원해 API 키 없이 연결 가능하다
4	바이너리 무수정	Codex 앱 바이너리를 패치하지 않고 Codex 설정 파일과 모델 카탈로그에 provider를 주입하는 방식이다. `ocx stop`으로 원본 설정이 복원된다
5	통합 대시보드	제공자, API 키, 모델 별칭(alias), 로그, 계정 관리를 웹 대시보드에서 처리한다
6	모델 라우팅 규칙	`provider/model` 형식으로 명시 지정하거나, prefix 생략 시 모델명 패턴으로 자동 매칭한다(`claude-` → Anthropic, `gpt-` → OpenAI)
7	Codex App 통합	라우팅된 모델이 Codex App 모델 선택기에 네이티브 모델과 함께 노출되며 모델별 reasoning effort 조절이 가능하다
8	ChatGPT 계정 풀	복수 ChatGPT/Codex 계정을 등록해 5시간·주간·30일 쿼터를 갱신하고 신규 세션을 사용량이 가장 낮은 계정으로 라우팅한다. 기존 스레드는 시작한 계정에 고정된다
9	백그라운드 서비스	시스템 서비스로 등록해 부팅 시 자동 실행되며, 중지 시 잔여 설정·좀비 프로세스를 남기지 않도록 설계되어 있다

3. 단점 및 리스크

번호	항목	설명
1	약관 리스크	OAuth·구독 계정 연동은 기술적으로 가능하더라도 해당 제공자가 서드파티 프록시 경유를 허용한다는 의미가 아니다. 프로젝트 문서 자체가 계정 제한·정지 가능성을 경고하고 있다. 특히 계정 풀 기능은 사용량 우회로 해석될 여지가 있다
2	추가 계층의 복잡성	Codex 위에 프록시 계층이 하나 더 생겨 설정 결정과 디버깅 지점이 늘어난다
3	기능 호환성 지연	자체 API 변환 계층이므로 Codex나 Claude Code의 최신 기능이 즉시 반영되지 않을 수 있다
4	프로젝트 성숙도	공식 도구 대비 생태계가 작고, 릴리스 주기가 매우 짧다(주 단위 preview 태그 다수). 안정성과 장기 유지보수에 대한 검증이 필요하다
5	상시 실행 의존성	Node 환경과 `ocx` 데몬의 상시 구동이 전제된다. Codex 단독 사용 대비 리소스를 더 사용한다
6	로컬 자격증명 집중	다수 제공자의 API 키와 OAuth 토큰이 로컬 설정(`~/.opencodex/config.json`)에 모인다. 단말 침해 시 피해 범위가 확대된다

4. 이름이 유사한 별개 프로젝트

"OpenCodex"라는 이름을 쓰는 프로젝트가 여러 개 존재한다. 기능을 혼동하지 않도록 구분이 필요하다.

프로젝트	정체	본 문서 대상과의 관계
lidge-jun/opencodex	본 문서의 대상. Codex/Claude Code용 범용 제공자 프록시	—
AITabby/opencodex	Codex Desktop용 로컬 게이트웨이. Vision Bridge, Computer Use 엔진, 음성 컴패니언(OpenCodexBar) 보유	별개 프로젝트. Vision Bridge·음성 기능은 이쪽 기능이며 lidge-jun 버전의 기능이 아니다
RyensX/OpenCodex	Codex Desktop 미들웨어. 브라우저 원격 접근에 특화	별개 프로젝트. 원격 접근 기능은 이쪽 기능이다
Open Codex (codingmoh)	완전 로컬 실행 CLI 어시스턴트. API 키 불필요, phi-4-mini 등 로컬 모델 지원	별개 프로젝트

5. 경쟁·대체 도구

도구	설명	차이점
OpenCode (SST)	오픈소스 터미널 AI 코딩 에이전트	프록시가 아닌 독립 에이전트. 다수 제공자를 자체 지원하므로 OpenCode 사용자에게는 opencodex의 실익이 적다
Claude Code	Anthropic 터미널 코딩 어시스턴트	Claude 생태계 특화. opencodex는 Claude Code 측 프록시로도 동작한다
Cursor	AI 네이티브 코드 에디터	IDE 내장형 경험 중심
GitHub Copilot	IDE 플러그인형 코딩 어시스턴트	제공자 선택 폭이 제한적
Aider / Cline / Windsurf	각기 다른 접근의 코딩 에이전트	워크플로와 특화 영역이 상이

6. Codex와의 비교

항목	Codex 단독	Codex + OpenCodex
사용 가능 모델	OpenAI 계열	40개 이상 제공자
설정 난이도	낮음	중간
비용 최적화	제한적	저가 모델 라우팅으로 유리
맞춤화	제한적	높음
운영 리스크	낮음	프록시 장애 지점 추가, 제공자 약관 리스크
적합 사용자	즉시 사용을 원하는 일반 사용자	모델 실험·비용 최적화를 중시하는 파워 유저

7. 종합 평가

기술적 설계는 합리적이다. 바이너리 패치 대신 설정 주입 방식을 택하고 ocx stop 한 줄로 원복되는 구조는 이 범주의 도구에서 가장 중요한 안전장치다. 어댑터를 5종으로 추상화한 점도 제공자 확장 비용을 낮춘다.

다만 도입 판단에서 기술적 편의보다 앞서는 변수는 약관 리스크다. API 키 기반 연동과 구독 계정(OAuth) 기반 연동은 성격이 전혀 다르며, 특히 다중 ChatGPT 계정 풀링은 제공자 관점에서 사용량 정책 우회로 판단될 수 있다. 업무용 환경이라면 API 키 기반 제공자만 등록하고 계정 풀 기능은 사용하지 않는 구성이 안전하다.

주 단위로 preview 릴리스가 쏟아지는 개발 속도는 기능 확장 측면에서는 긍정적이나, 프로덕션 의존성으로 삼기에는 아직 이르다. 개인 개발 환경에서의 실험적 도입이 현재 적정 수준이다.