TL;DR

opencodex는 Codex 및 Claude Code 클라이언트가 원래의 워크플로를 유지하면서 Anthropic, Google, Ollama, OpenRouter 등 40개 이상의 공급자와 로컬 모델을 즉시 사용하도록 로컬 프록시로 중계하는 도구이다. 프록시는 /v1/responses와 이미지 엔드포인트를 변환하여 스트리밍, 도구 호출, reasoning effort 메타데이터를 보존하고 공급자별 어댑터로 인증과 모델 자동 검색을 처리한다. 추가로 여러 ChatGPT/Codex 계정을 풀링하여 쿼터 기반 자동 라우팅과 세션 친화성을 제공하고, 시스템 서비스·shim·대시보드를 통해 운영성과 복구를 지원한다. 단점은 일부 공급자 정책상 프록시 사용이 제한될 수 있으며 README에서 해당 리스크를 명확히 경고하고 있어 사용 전에 공급자 약관을 검토해야 한다.

주요 기능

• Codex의 Responses API 요청을 공급자별 포맷으로 변환하여 스트리밍, 도구 호출, 이미지 생성 등 복합 기능을 양방향으로 유지한다. 로컬 데몬이 Codex 클라이언트와 업스트림 공급자 사이에서 프록시 역할을 하며 클라이언트 설정을 최소한으로 유지한다. 기본 포트는 10100이며 포트 충돌 시 자동으로 여유 포트로 대체된다.
• 40개 이상의 빌트인 공급자 어댑터와 공개된 OpenAI-호환 엔드포인트 지원을 통해 Anthropic, Google, Ollama, OpenRouter 등 다양한 모델을 즉시 사용 가능하다. 모델 목록은 공급자의 /v1/models 엔드포인트에서 자동으로 검색된다. 일부 공급자는 OAuth 로그인을 통해 키 없이 연결할 수 있다.
• ChatGPT/Codex 계정 풀링 기능을 통해 여러 계정의 쿼터를 집계하고 신규 세션을 사용량이 낮은 계정으로 자동 라우팅할 수 있다. 기존 세션은 계정 친화성(affinity)을 유지하여 장기 연결이 중간에 바뀌지 않도록 보장한다. 429 응답은 cooldown으로 처리되어 이후 라우팅 결정에 반영된다.
• Codex App의 모델 픽커에 라우팅된 모델을 노출하고 클라이언트에서 reasoning effort(추론 노력) 수준을 선택할 수 있도록 메타데이터를 주입한다. effort 단계는 공급자 구성에 따라 매핑되며 ultra는 클라이언트 측 다중 에이전트 위임을 트리거하는 동작을 유지한다. 일부 고급 위임 경로는 버전/표면(예: v1 vs v2)에 따라 차이가 있다.

어떻게 동작하는가

opencodex는 Codex의 /v1/responses 및 이미지 엔드포인트로 들어오는 요청을 가로채어 구성된 프로바이더 어댑터를 통해 업스트림 공급자 API로 재발송하는 리버스 프록시 아키텍처를 사용한다. 각 어댑터는 인증 방식, 모델 메타데이터 자동 수집, 요청·응답 매핑 규칙, reasoning effort 및 모델 id 별 스펙 변환을 구현하여 Codex 클라이언트가 원래 경험을 유지하게 만든다. 추가적으로 ChatGPT 계정 풀링, 포트 자동 선택, 데몬 서비스/시스템 통합, 대시보드 기반 설정 편집을 통해 운영성을 확보한다.

해결 문제

Codex와 Claude Code가 기본적으로 지원하지 않는 외부 모델을 사용하려면 공급자별로 별도 통합이 필요했는데, opencodex는 이 문제를 해결하여 개발자가 새로운 공급자의 지원을 기다리지 않아도 즉시 다양한 LLM을 Codex 워크플로에 연결할 수 있게 했다. 이 프록시는 Responses API와 이미지 엔드포인트를 변환·중계하면서 스트리밍, 도구 호출, reasoning 토큰 등 핵심 동작을 보존하므로 기존 Codex 사용성에 영향을 주지 않는다. 또한 여러 ChatGPT/Codex 계정을 풀로 관리하여 쿼터 회피와 세션 친화성을 동시에 확보한다.

지금 주목받는 이유

Codex와 Claude Code가 외부 모델을 직접 지원하지 않는 상황에서 40개 이상의 공급자를 즉시 연결할 수 있는 실용적 해결책을 제공하며 ChatGPT 계정 풀링 같은 운영 편의 기능을 갖춰 빠르게 관심을 받고 있다.

차별점

• 기본적인 차별점은 공급자 어댑터의 광범위성이다. README에 따르면 40개 이상의 빌트인 공급자를 즉시 추가할 수 있으며 OpenAI-호환 엔드포인트를 사용자 정의로 넣을 수도 있다. 이로 인해 새로운 공급자 지원을 기다릴 필요 없이 즉시 라우팅이 가능하다.
• Codex App의 모델 픽커에 라우팅된 모델과 reasoning effort 컨트롤을 노출하는 점이 독특하다. opencodex는 effort 단계 매핑을 유지하여 클라이언트의 고급 위임 동작과 호환되게 메타데이터를 주입한다. 이를 통해 사용자는 동일한 Codex UI에서 다른 백엔드를 투명하게 선택할 수 있다.
• ChatGPT/Codex 계정 풀링과 자동 라우팅 로직은 장기 세션 친화성과 쿼터 분산을 동시에 달성한다. 기존 세션은 계정에 고정되어 로그아웃·재인증 상황에서도 히스토리 일관성을 보장하며 신규 세션은 최저 사용 계정으로 분배된다. 실패 상황에서는 cooldown·reauth 표식을 사용하여 안전하게 처리한다.
• 경량 로컬 데몬 형태로 동작하며 시스템 서비스(launchd/systemd/Task Scheduler) 혹은 codex shim 방식으로 자동 시작을 구성할 수 있다. 설치 시 Bun 런타임을 번들로 포함하여 별도 Bun 설치 없이 동작하도록 설계되어 설치 진입 장벽을 낮춘다. 포트가 점유된 경우 자동으로 대체 포트를 선택하여 Codex 설정을 갱신한다.

사용 사례

• 사설 또는 로컬 호스팅 모델을 Codex 워크플로에서 바로 사용하려는 상황에서 opencodex는 로컬 OpenAI-호환 엔드포인트를 포워딩하여 동일한 Codex 경험을 유지하면서 모델을 교체할 수 있게 만든다. 구성 예시로 Ollama나 vLLM을 baseUrl로 지정하면 로컬 모델이 Codex에 노출된다. 이로써 내부 데이터나 온프레미스 모델을 기존 도구들과 통합할 수 있다.
• 다중 계정 쿼터를 관리해야 하는 환경에서 ChatGPT/Codex 계정 풀링 기능은 신규 세션을 덜 사용된 계정으로 분산시키고 기존 세션의 affinity를 보존하여 장시간 SSH나 모바일 연결 세션의 중간 계정 변경을 방지한다. 쿼터 조회와 cooldown 정책이 자동화되어 운영 부담을 낮춘다.
• 특정 작업은 고성능 추론 모델로, 반복적·저비용 작업은 경량 모델로 분산 처리하려는 워크플로에서 대시보드로 서브에이전트 모델과 effort 레벨을 구성하여 태스크별 모델 위임을 구현할 수 있다. v2 multi-agent 표면에서는 compact delegation guidance를 주입하여 교차 모델 위임 규칙(fork_turns 등)을 적용한다.

시작하기

설치와 초기화는 npm 전역 패키지로 제공되며 Node 18+ 환경에서 npm install -g @bitkyc08/opencodex로 설치한 뒤 ocx init으로 대화형 설정을 완료하고 ocx start로 프록시를 기동하면 기본 포트 10100에서 대기한다. 대시보드(ocx gui)를 통해 공급자 추가, OAuth 로그인, 모델 자동 검색을 수행할 수 있으며 providers는 /v1/models에서 모델을 자동으로 인식하여 즉시 사용 가능하게 만든다. 시스템 서비스나 codex-shim 설치는 ocx service install 또는 ocx codex-shim install로 처리하며 ocx stop/ocx uninstall로 원상 복구가 가능하다.

요구사항

• Node 18 이상의 런타임이 필수이며 설치 과정에서 번들로 포함된 Bun 런타임을 사용하므로 별도 Bun 설치는 필요 없다. 운영체제 측면에서는 macOS(arm64/x64), Linux(x64/arm64), Windows(x64)를 모두 공식 지원한다. 로컬 LAN 바인딩을 사용하려면 OPENCODEX_API_AUTH_TOKEN 환경변수를 설정해야 하며 프록시가 loopback 외 바인딩 시 토큰이 없으면 시작을 거부한다.

이미지 분석