opencodex는 OpenAI의 Codex 및 Claude Code와 같은 도구에서 기본적으로 지원하지 않는 다양한 Large Language Models(LLM)을 연동할 수 있게 해주는 경량 로컬 프록시(Local Proxy) 솔루션입니다. 이 도구는 Codex의 Responses API를 표준화된 인터페이스로 변환하여, 사용자가 Anthropic, Google, xAI, Ollama 등 40개 이상의 외부 모델 공급자를 Codex 환경에서 직접 사용할 수 있도록 설계되었습니다.

핵심 메커니즘 및 기술적 상세

1. Protocol Adapters: opencodex는 5개의 핵심 어댑터(OpenAI Responses, OpenAI Chat Completions, Anthropic Messages, Azure OpenAI, Google Gemini)를 통해 서로 다른 API 프로토콜을 Codex가 이해하는 형식으로 변환합니다. 이를 통해 스트리밍, 툴 호출(Tool calls), 추론 토큰(Reasoning tokens), 이미지 생성 등을 양방향으로 처리합니다.
2. Provider Proxy 및 모델 라우팅: provider/model 구문을 통해 특정 공급자의 모델을 호출합니다. 내부적으로는 v1/models 엔드포인트를 통해 모델 목록을 자동 탐색하며, 슬래시(/)가 포함된 모델 ID를 대시(-)로 변환하여 Codex CLI 및 앱과 호환성을 유지합니다.
3. ChatGPT 계정 풀링 및 상태 관리: 여러 개의 ChatGPT 계정을 등록하여 계정별 쿼터(5h, Weekly, 30d)를 관리할 수 있습니다.
   • Affinity: 기존 세션은 동일한 계정에 고정(Pinned)되어 SSH나 tmux 등 장기 연결 환경에서도 계정 점프 없이 안정적인 대화가 가능합니다.
   • Auto-routing: 새로운 세션 생성 시, 사용량(Usage)을 비교하여 가장 상태가 양호한 계정을 자동으로 할당하는 로드 밸런싱을 수행합니다.
   • Failover: 429(Too Many Requests) 에러 발생 시 자동 쿨다운 및 대체 계정으로의 전환을 지원합니다.
4. Codex 통합 및 역사 관리: ~/.opencodex/config.json을 통해 설정된 openai_base_url을 본인(Proxy)으로 지정하여, Codex의 기존 설정 변경을 최소화합니다. 특히 codex-history-backup.json을 사용하여 대화 내역(History)을 보존하며, 서비스 중단 시 ocx restore 명령을 통해 원래 상태로 복구하는 정교한 상태 복원 메커니즘을 갖추고 있습니다.
5. 추론 및 에이전트 제어: reasoningEfforts 구성을 통해 low, medium, high, xhigh, max, ultra 등의 추론 강도를 제어합니다. 특히 멀티 에이전트 환경에서 injectionModel과 injectionEffort를 삽입하여, 하위 에이전트 위임(Fork turns) 시 모델별 최적화된 지침을 제공합니다.

주요 기능 및 특징

• Claude Code 연동: ocx claude 명령을 통해 Claude Code를 런칭하고, gateway 모델 검색을 통해 연동된 모든 모델을 선택 가능하게 합니다.
• 인증 및 보안: OAuth 지원을 통해 API 키 없이도 Anthropic, xAI, Kimi 등의 계정 연동이 가능하며, LAN 환경에서는 x-opencodex-api-key 헤더를 통한 Constant-time 토큰 검증으로 보안을 유지합니다.
• 배포 및 관리: launchd, systemd, Task Scheduler를 통한 백그라운드 서비스 운영이 가능하며, ocx gui를 통해 대시보드에서 실시간 요청 로그 및 모델 상태를 모니터링할 수 있습니다.

본 프로젝트는 특정 업체에 종속되지 않는 유연한 LLM 워크플로우를 제공하는 데 목적이 있으며, 커뮤니티 기반의 독립적인 오픈소스 소프트웨어로 운영됩니다.