OpenAI의 Codex CLI는 2026년에 조용히 문 하나를 닫았다. 터미널 에이전트가 Chat Completions와 더 이상 통신하지 않게 되면서, 예전 방식으로 연결된 모든 서드파티 모델이 실행 시점부터 실패하기 시작했다. 커뮤니티 프록시인 OpenCodex가 그 문을 다시 열었다.
Codex CLI가 커뮤니티 LLM을 밀어낸 방식
Codex CLI는 2026년에 wire_api = "chat"(Chat Completions)을 제거한 뒤 이제 단 하나의 와이어 형식, 즉 OpenAI의 Responses API인 wire_api = "responses"만 허용한다. 아직 chat 모드로 설정된 커스텀 프로바이더는 시작하자마자 하드 에러로 실패한다 . 문제가 되는 지점은 여기에 있다. OpenAI가 아닌 대부분의 호스트는 Responses API를 네이티브로 지원하지 않기 때문에, 예전에는 Codex를 Claude나 로컬 모델로 돌릴 수 있게 해주던 [model_providers] 우회로가 더 이상 작동하지 않게 됐다.
빠른 답: Codex CLI는 이제 wire_api = "responses"를 요구하며, 예전 Chat Completions 프로바이더는 시작 시점에 거부한다. OpenCodex는 Codex가 계속 localhost:10100과 통신하게 두고, 각 요청을 다섯 가지 프로토콜 어댑터를 거쳐 대상 모델이 실제로 이해하는 방식으로 변환하는 로컬 프록시다. v2.7.31 기준(2026년 7월 21일) 40개 이상의 프로바이더를 지원한다.
OpenCodex는 바로 그 빈틈을 메운다. Codex는 계속 http://localhost:10100/v1로 네이티브 Responses API 요청을 보내고, OpenCodex는 각각의 요청을 스트리밍, 도구 호출, 추론 토큰, 이미지까지 포함해 다섯 가지 프로토콜 어댑터(Anthropic Messages, Google Gemini, Azure OpenAI, Responses 패스스루, 그리고 OpenAI 호환 Chat 엔드포인트)로 변환해 대상 프로바이더가 실제로 쓰는 방식에 맞춘다 .
| 범위(2026년 7월 21일 기준) | 값 |
|---|---|
| 최신 버전(npm) | @bitkyc08/opencodex 2.7.31 |
| 내장 프로바이더 | 40개 이상 |
| GitHub 스타 / 커밋 | 약 2.4천 / 1,643 |
| 저장소 / 라이선스 | lidge-jun/opencodex / MIT |
이 수치는 저장소와 릴리스 메타데이터 기준이다 . 단순히 CLI를 다시 포장한 또 다른 open-codex 포크가 아니라, 요청을 변환하는 프록시라는 점에 유의해야 한다.
ocx init 전에 확인할 것
ocx init을 실행하기 전에 네 가지가 준비돼 있어야 한다. 최신 Node 런타임, 정상 작동하는 Codex CLI, 대상 모델용 자격 증명 하나 이상, 그리고 비어 있는 프록시 포트다. 이 조건을 맞춰두면 설정은 한 번의 대화형 과정으로 끝난다. 하나라도 빠지면 init이 멈추거나, 사용자가 모르는 사이 설정을 우회적으로 패치한다.
- Node 18+. OpenCodex가 의존하는 Bun 런타임은
npm install -g @bitkyc08/opencodex중에 번들로 함께 자동 설치된다 . Bun을 별도로 설정할 필요는 없다. - Codex CLI가 이미 설치되어 정상 작동해야 한다. OpenCodex는
$CODEX_HOME/config.toml을 그 자리에서 수정하며, 해당 파일 구조가 이미 존재한다고 가정한다 . Codex 자체를 대신 만들어주지는 않는다. - 대상 모델용 자격 증명 하나. Anthropic, Google, xAI, Mistral, Groq, Ollama, OpenRouter 또는 OpenAI 호환 엔드포인트라면 사용할 수 있다. OAuth 로그인(xAI, Anthropic, Kimi)이나 원시 API 키 방식 모두 가능하다 .
- 포트 10100이 비어 있어야 한다. 기본값은 이 포트다. 이미 사용 중이면
ocx init이 충돌을 감지하고, 빈 포트를 골라 Codex 설정을 자동으로 패치한다 .
Codex CLI와 모든 LLM 사이에 ocx를 연결하는 방법
필수 조건이 준비되면 OpenCodex를 Codex에 연결하는 과정은 설치, 초기화, 시작, 호출이라는 네 가지 명령으로 끝납니다. OpenCodex는 로컬 변환 프록시로 실행됩니다. Codex는 localhost를 향해 기존처럼 네이티브 Responses API로 통신하고, ocx가 각 요청을 대상 모델이 실제로 이해하는 형식으로 바꿉니다 (source: OpenCodex repo). Codex 바이너리를 패치할 필요는 없습니다. ocx는 Codex가 원래 읽는 설정만 수정합니다.
1. 설치. 전역 npm 명령 하나로 패키지와 서로 바꿔 쓸 수 있는 두 별칭 ocx, opencodex가 설치되며, 설치 직후 바로 사용할 수 있습니다 (source: npm, 2026-07):
npm install -g @bitkyc08/opencodex2. 설정. ocx init을 실행합니다. 대화형 마법사가 공급자 선택과 인증 정보를 받고, 프록시 포트(기본값 10100)를 설정한 뒤, $CODEX_HOME/config.toml에 라우팅을 주입하고 선택적으로 자동 시작 shim을 설치하기 전에 권한을 요청합니다. 자체 설정은 ~/.opencodex/config.json에 기록됩니다 (source: OpenCodex quickstart).
3. 실행. ocx start는 http://localhost:<port>/v1에 바인딩하고, ~/.opencodex/ocx.pid를 작성하며, 라우팅된 모델을 Codex의 자체 모델 카탈로그와 동기화해 선택 목록에 표시되도록 합니다 (source: OpenCodex docs).
4. 호출. 명시적인 provider/model 형식을 사용하세요. 결정적이며 권장되는 방식입니다 (source: OpenRouter tutorial):
codex -m "anthropic/claude-opus-4-8"
codex -m "ollama-cloud/glm-5.2"공급자 접두사를 생략하면 내장 패밀리 접두사(claude-*, gpt-*, llama-*, gemma-*)가 대체 경로로 자동 해석됩니다 (source: OpenRouter). 개념적으로 Codex는 더 이상 채팅 전송 계층을 직접 소유하지 않고, ocx가 라우팅할 의도만 내보냅니다. 아래 예시 모델은 설치 과정의 일부가 아니며, 이 단일 홉 구조를 보여주기 위한 것입니다:
class CodexCLI:
def __init__(self, router):
self.router = router
def send(self, prompt):
# Codex CLI no longer owns a chat-wire transport; it just emits intent.
return self.router.route({"source": "codex-cli", "prompt": prompt})
class OpenCodexRouter:
def route(self, message):
model = "opencodex-chat"
return f"{message['source']} -> {model}: {message['prompt']}"
if __name__ == "__main__":
cli = CodexCLI(OpenCodexRouter())
print(cli.send("dropped chat-wire; route this"))5. 복원. ocx stop은 config.toml에 가한 모든 수정을 되돌리고 pid 파일을 제거합니다. 따라서 잔여 패치 없이 Codex의 기본 동작으로 돌아가며, 이 낮은 전환 비용 덕분에 ocx를 부담 없이 시험해 볼 수 있습니다 (source: OpenCodex site).
LLM 프록시에서 문제가 될 수 있는 지점
전환 비용이 낮다고 해서 법적 또는 운영상 위험까지 낮다는 뜻은 아닙니다. OpenCodex는 자신이 “OpenAI, Anthropic 또는 그 밖의 어떤 공급자와도 제휴하거나 보증받지 않은” 커뮤니티 프로젝트라고 명시하며, 일부 공급자는 프록시 릴레이를 통해 라우팅되는 계정을 제한할 수 있다고 경고합니다 . 프로덕션 인증 정보를 ocx에 연결하기 전에 공급자의 서비스 약관을 읽어야 합니다. Responses API를 벤더의 네이티브 표면으로 변환하는 프록시는 일부 벤더가 문제 삼는 바로 그 패턴입니다.
가장 뚜렷한 경계는 Anthropic OAuth입니다. Anthropic의 Claude Code 법적 문서는 OAuth 로그인이 네이티브 Anthropic 앱을 위한 것이며, 서드파티 개발자가 사용자를 대신해 Claude.ai 로그인을 제공하거나 Free, Pro, Max 플랜 인증 정보로 요청을 라우팅해서는 안 된다고 설명합니다 . Codex 뒤에서 Claude를 쓰고 싶다면 원시 Anthropic API 키가 더 낮은 위험의 전송 방식입니다. 소비자 플랜 로그인을 전달하는 방식은 계정 제한으로 이어질 가능성이 가장 큽니다.
“OpenCodex는 독립 프로젝트이며 OpenAI, Anthropic 또는 그 밖의 어떤 공급자와도 제휴하거나 보증받지 않았습니다.” — OpenCodex project README (source: lidge-jun/opencodex)
위험 범위에는 두 가지 기능적 한계도 더해집니다. v2.7.31 기준으로 경계 간 서브 에이전트 인계는 알려진 공개 이슈입니다 . 네이티브 Codex 부모가 라우팅된 OpenCodex 자식을 생성하면 작업 본문이 암호화되어 읽을 수 없는 상태로 도착할 수 있고, 그 결과 위임된 작업이 조용히 누락될 수 있습니다 . 또한 모델을 Codex 카탈로그에 동기화한다고 해서 그 모델에 대한 접근 권한이 생기는 것은 아닙니다. 롤아웃 제한이 걸린 업스트림 모델, 계정 등급, 지역별 가용성이 여전히 실제 호출 성공 여부를 결정합니다 . 카탈로그는 권한 목록이 아니라 라우팅 테이블로 보아야 합니다.
번역이 시작되면: 풀링, 사이드카, 대시보드
OpenCodex가 번역을 시작하면 부가 기능들이 본격적으로 쓸모 있어집니다. 계정 풀링은 ChatGPT/Codex 자격 증명 묶음을 관리하고 5시간, 주간, 30일이라는 세 가지 quota 창을 추적합니다. 새 세션은 사용량이 가장 낮은 정상 계정으로 자동 라우팅하고, 기존 스레드는 세션 affinity를 통해 처음 배정된 계정에 고정합니다 . 실패 방식도 보수적입니다. HTTP 429가 발생하면 cooldown과 failover가 트리거되고, 토큰 실패는 조용히 다른 계정으로 바꾸는 대신 재인증 대상으로 표시됩니다 .
같은 인스턴스는 Codex만 처리하지 않습니다. ocx claude를 실행하면 공유 proxy 포트를 바라보는 Claude Code가 시작되므로, Codex CLI와 Claude Code가 하나의 OpenCodex 프로세스를 통해 동시에 번역합니다 . 검색과 vision sidecar는 전체 context를 primary model로 밀어 넣지 않고도 번역 경로에 붙을 수 있고, 라우팅된 모델 또는 native 모델을 최대 5개까지 sub-agent로 실행할 수 있습니다 . 마지막으로 ocx gui는 번역 상태, 계정별 quota 사용량, 세션별 사용량을 볼 수 있는 브라우저 대시보드를 엽니다 . 핵심은 간단합니다. 풀링과 대시보드는 관측성 도구로 보고, 한 번 설치한 뒤 의도적으로 라우팅하면 됩니다.
자주 묻는 질문
OpenCodex를 설치할 때 정확한 npm 패키지 이름은 무엇인가요?
패키지는 @bitkyc08/opencodex입니다. npm scope가 GitHub repo와 다르다는 점에 주의해야 합니다. GitHub repo는 lidge-jun/opencodex에 있습니다. npm install -g @bitkyc08/opencodex로 전역 설치하면 ocx와 opencodex alias가 모두 노출됩니다. Node 18+가 필요하며, Bun runtime은 설치 중 자동으로 포함되므로 따로 설치하지 않아도 됩니다 .
OpenCodex는 Codex CLI뿐 아니라 Claude Code에서도 작동하나요?
네. ocx claude를 실행하면 Codex가 사용하는 동일한 localhost 포트를 바라보도록 Claude Code가 시작되므로, 두 client가 공유 proxy binding을 통해 하나의 OpenCodex 인스턴스를 함께 사용합니다 . 즉 별도 proxy를 여러 개 띄우지 않고도 Codex CLI, Codex App, Codex SDK, Claude Code를 같은 라우팅 모델에 연결해 사용할 수 있습니다 .
ocx init은 실제로 Codex config에 무엇을 쓰나요?
bind address에 따라 달라집니다. loopback bind에서는 $CODEX_HOME/config.toml에 top-level openai_base_url = "http://127.0.0.1:10100/v1"을 주입하고 Codex의 built-in openai provider를 유지합니다. non-loopback bind에서는 대신 wire_api = "responses"와 x-opencodex-api-key header가 포함된 전용 [model_providers.opencodex] block을 추가합니다 . 두 변경 사항 모두 ocx stop으로 완전히 되돌릴 수 있으며, native Codex 상태가 깔끔하게 복원됩니다 .
Anthropic OAuth 자격 증명을 OpenCodex를 통해 라우팅해도 안전한가요?
법적으로 애매하므로 실제 리스크로 봐야 합니다. Anthropic의 Claude Code 약관은 OAuth 로그인을 native Anthropic app으로 제한하고, third-party developer가 사용자를 대신해 Claude.ai login을 제공하거나 Free, Pro, Max plan 자격 증명을 통해 요청을 라우팅할 수 없다고 명시합니다 . plan-tier OAuth를 proxy로 라우팅하는 것은 그 정책을 위반할 가능성이 큽니다. raw API key를 쓰는 쪽이 리스크가 낮습니다. OpenCodex 자체도 독립 프로젝트이며 어떤 provider와도 제휴하거나 보증받지 않았다고 밝히고, 일부 provider가 proxy-routed account를 제한할 수 있다고 경고합니다 .
OpenCodex에는 어떤 wire protocol adapter가 포함되어 있나요?
protocol adapter는 다섯 가지입니다. Anthropic Messages API(Claude), Google Gemini, Azure OpenAI, OpenAI Responses passthrough, 그리고 OpenAI-compatible Chat Completions endpoint입니다 . 마지막 adapter가 긴 provider 목록을 열어 줍니다. DeepSeek, Ollama(local 및 cloud), Groq, Mistral, xAI/Grok, vLLM, LM Studio는 모두 Chat Completions를 지원합니다. 그래서 OpenCodex는 이 다섯 adapter 위에 40개 이상의 built-in provider를 제공한다고 설명합니다 .
이 글이 도움이 되셨다면, 새 글이 올라올 때마다 이메일로 받아보세요.
