OpenCodex 완벽 정리 — Codex에 Claude·Gemini·로컬 LLM까지 붙이는 유니버설 프록시

OpenAI의 Codex는 강력한 코딩 에이전트지만, 기본적으로는 OpenAI 계열 모델에 묶여 있습니다. 손에 익은 Claude나 Gemini, 혹은 사내망에 띄운 로컬 모델을 Codex에서 그대로 쓰고 싶어도 공식 지원을 기다려야 하는 경우가 많았습니다. OpenCodex는 바로 그 간극을 메우는 오픈소스 프로젝트입니다. 로컬에 가벼운 프록시를 하나 띄워 Codex의 API 호출을 40개가 넘는 프로바이더로 중계하고 서로 다른 프로토콜을 자동으로 번역합니다. 이 글에서는 OpenCodex가 무엇인지, 왜 필요한지, 설치부터 프로바이더 연결과 모델 라우팅까지 공식 문서를 기준으로 정리해 드리겠습니다.

OpenCodex란 무엇인가

OpenCodex는 "유니버설 프로바이더 프록시"로 소개됩니다. 쉽게 말해 Codex CLI, App, SDK, 그리고 Claude Code 같은 도구와 각 LLM 제공사 사이에 끼어 통역사 역할을 하는 로컬 프로그램입니다. 명령줄 도구는 ocx라는 이름으로 제공되며, 프록시는 기본적으로 localhost:10100에서 돌아갑니다. 실행에는 Node 18 이상이 필요하고 런타임으로 Bun이 함께 번들되어 별도 설치 부담이 적습니다.

핵심은 "각 도구가 새 프로바이더를 직접 지원할 때까지 기다리지 않아도 된다"는 점입니다. Codex가 보내는 Responses API 호출을 프록시가 가로채 목적지 프로바이더의 형식으로 바꿔 전달합니다. 그 덕분에 도구 쪽 코드를 건드리지 않고도 사용하는 모델만 바꿔 끼울 수 있습니다.

왜 이런 프록시가 필요한가

LLM 생태계는 제공사마다 API 규격이 조금씩 다릅니다. Anthropic의 Messages API, 구글 Gemini의 프로토콜, Azure OpenAI의 별도 설정, 그리고 Ollama나 vLLM 같은 OpenAI 호환 엔드포인트가 각자의 방식을 씁니다. 도구 하나가 이 모든 규격을 직접 품으려면 유지보수 부담이 큽니다.

OpenCodex는 이 문제를 중간 계층에서 해결합니다. 프로바이더별 어댑터를 프록시가 대신 들고 있으니 Codex는 언제나 익숙한 한 가지 방식으로만 요청을 보내면 됩니다. 여러 LLM을 상황에 맞게 갈아 쓰거나 비용과 성능을 비교하려는 개발자에게 특히 실용적입니다. 사내 정책상 외부 API 대신 로컬 모델을 써야 하는 환경에서도 같은 흐름으로 연결할 수 있습니다.

설치와 첫 실행

설치와 초기 구동은 명령 세 줄로 끝납니다. 공식 문서 기준 절차는 다음과 같습니다.

이후 Codex나 Claude Code를 평소처럼 사용하면 요청이 프록시를 거쳐 원하는 프로바이더로 흘러갑니다. 프록시를 내리고 원래 Codex 설정으로 되돌리려면 ocx stop을 쓰면 됩니다.

프로바이더 추가와 모델 라우팅

프로바이더 등록은 웹 대시보드에서 편하게 할 수 있습니다. ocx gui를 실행하면 브라우저에서 http://localhost:10100으로 대시보드가 열리고, "Add Provider"에서 40여 종의 내장 옵션 중 하나를 고르거나 OpenAI 호환 커스텀 엔드포인트를 직접 등록합니다. API 키는 직접 입력하거나 OAuth로 연결할 수 있으며 Anthropic·xAI·Kimi가 OAuth를 지원합니다. 등록하면 사용 가능한 모델은 프로바이더 엔드포인트에서 자동으로 조회됩니다.

실제 사용할 때는 provider/model 형식으로 목적지를 지정합니다. 예를 들어 이런 식입니다.

codex -m "anthropic/claude-opus-4-8" "이 에러를 설명해줘"
codex -m "google/gemini-3-pro" "테스트 코드를 작성해줘"
codex -m "ollama/llama3" "이 코드를 리팩터링해줘"

프로바이더 접두어를 생략하면 기본 프로바이더로 가거나 모델 이름 패턴을 보고 자동으로 매칭됩니다. 덕분에 한 세션 안에서도 작업 성격에 따라 모델을 바꿔 가며 쓰기 편합니다.

지원하는 프로바이더 범위

OpenCodex가 소개하는 지원 범위는 넓습니다. 프로토콜 계열별로 정리하면 다음과 같습니다.

• Claude 계열을 위한 Anthropic Messages API
• 구글 프로토콜을 통한 Google Gemini
• Azure 전용 설정을 갖춘 Azure OpenAI
• Ollama, vLLM, DeepSeek, Groq, OpenRouter 등을 아우르는 OpenAI 호환 엔드포인트
• 쿼터 관리와 계정 어피니티를 지원하는 ChatGPT 로그인 풀링

여기에 xAI Grok, Kimi(Moonshot), Together, Mistral, 그리고 로컬 설치 모델까지 더해집니다. 하나의 프록시로 상용 API와 로컬 모델을 같은 방식으로 다룰 수 있다는 점이 강점입니다.

계정 풀링과 백그라운드 서비스

여러 ChatGPT 계정을 함께 굴려야 하는 상황도 고려되어 있습니다. OpenCodex는 계정 풀을 관리하면서 쿼터를 갱신하고 세션 어피니티와 페일오버를 처리합니다. 한 계정의 한도가 차면 다른 계정으로 자연스럽게 넘어가도록 설계되어 있어 대량 작업에서 끊김을 줄일 수 있습니다.

프록시를 매번 손으로 켜기 번거롭다면 서비스로 등록하는 방법도 있습니다. ocx service install로 운영체제 수준의 자동 시작을 걸 수 있고 launchd·systemd·작업 스케줄러를 각각 지원합니다. 필요할 때만 자동으로 뜨는 방식을 원한다면 ocx codex-shim install로 온디맨드 래퍼를 설치할 수도 있습니다.

주요 CLI 명령어 정리

• ocx init — 대화형 초기 설정
• ocx start / ocx stop — 프록시 실행 및 종료(종료 시 원래 Codex 설정 복원)
• ocx gui — 웹 대시보드 열기
• ocx claude [args] — 프록시와 연동된 Claude Code 실행
• ocx login — OAuth 인증
• ocx account — 계정 풀과 API 키 관리
• ocx service install / ocx codex-shim install — 자동 시작 설치

설정 파일 살펴보기

설정은 ~/.opencodex/config.json에 JSON 형식으로 저장됩니다. 포트와 기본 프로바이더, 그리고 프로바이더별 어댑터와 인증 방식을 지정하는 구조입니다. 예를 들어 기본 프로바이더를 Anthropic으로 두고 OAuth 인증을 쓰도록 잡을 수 있습니다. 로컬 모델은 Ollama나 vLLM 같은 OpenAI 호환 서버로 연결하는데 이때 API 키는 비워 두고 http://localhost:11434/v1 같은 로컬 baseUrl을 지정하면 됩니다.

기능 측면에서는 스트리밍과 툴 콜, reasoning 토큰, 이미지를 양방향으로 지원합니다. Codex CLI와 TUI, App, SDK에서 자동으로 동작하며 스레드 히스토리와 프로바이더 메타데이터도 주입 방식으로 보존한다고 소개됩니다.

마치며

OpenCodex는 "도구는 그대로 두고 모델만 자유롭게"라는 발상을 프록시 한 겹으로 풀어낸 프로젝트입니다. Codex나 Claude Code를 쓰면서도 Claude, Gemini, 로컬 모델을 오가고 싶은 개발자라면 한 번 살펴볼 만합니다. 설치가 명령 몇 줄로 끝나고 대시보드로 프로바이더를 관리할 수 있어 진입 장벽도 낮은 편입니다. 다만 이 글은 공식 저장소와 문서를 정리한 소개이므로 실제 도입 전에는 본인 환경에서 직접 설치해 원하는 프로바이더 연결과 모델 라우팅이 매끄럽게 되는지 확인해 보시길 권합니다. 오픈소스인 만큼 저장소의 최신 문서와 이슈를 함께 참고하면 더 정확합니다.

참조 링크

• OpenCodex GitHub 저장소공식 소스 코드와 문서
• npm: @bitkyc08/opencodex패키지 설치 페이지