Codex Router는 Kimi·DeepSeek·Grok·Anthropic·Ollama Cloud·Qwen Plan·Z.ai·opencode Go/Zen 등 외부 모델을 OpenAI Codex App/CLI의 기본 모델 picker에 병합해 보여 주는 로컬 라우터다. Codex의 Responses API와 외부 provider의 Chat Completions/기타 프로토콜 사이를 LiteLLM·forwarder로 변환하고, native GPT 요청과 외부 모델 요청의 인증 경계를 분리하는 것이 핵심이다.
한눈에 보기
- 프로젝트 성격: JavaScript/Node.js 기반의 독립적인 커뮤니티 프로젝트. README는 OpenAI·Anthropic·Moonshot AI·DeepSeek·OpenRouter·opencode 등과 제휴/공식 endorsement가 없다고 명시한다.
- 지원 target: 고정 커밋의
AGENTS.md는 현재codex만 지원한다고 안내한다. opencode는 별도 앱 target이 아니라 Codex 안에서 사용할 수 있는 provider family로 남아 있다. - 사용자 표면: 외부 모델을
provider/model네임스페이스로 Codex catalog에 합치고, 기존 GPT picker·profiles·ChatGPT login을 보존하는 설치/업데이트/doctor/rollback 흐름을 제공한다. - 실행면: Node.js 로컬 프로세스, LiteLLM gateway, Kimi OAuth/API forwarder, API-key forwarder, 플랫폼별 per-user background service가 loopback으로 묶인다.
- 버전 스냅샷:
package.json의 버전은0.4.0-beta.2다. 이 summary의 기능 설명과 지표는 2026-08-08 KST에 확인한 고정 커밋 기준이며 현재 HEAD의 영속적 사실로 일반화하지 않는다.
공식 확인 — Codex와 외부 모델 사이의 경로
Responses API를 중심으로 한 이중 라우팅
HOW-IT-WORKS.md와 router.mjs가 설명하는 구조는 다음과 같다.
Codex App/CLI
└─ managed capability URL + Responses request
└─ Router :4102
├─ native GPT model
│ └─ allow-listed Codex headers → ChatGPT Codex backend
└─ namespaced external model
└─ LiteLLM :4100
├─ Kimi Code OAuth :4101 → refreshed Kimi bearer
└─ API forwarder :4103 → selected provider API key- Codex는 Responses API와 Codex-shaped model catalog를 기대한다.
- 외부 모델은 대체로 OpenAI-compatible Chat Completions API를 노출하므로, router는 Responses 요청·stream·tool call을 LiteLLM으로 넘겨 변환한다.
- native GPT route는 기존 ChatGPT/Codex 인증을 허용 목록 범위에서 전달한다.
- external route는 들어온 Codex 계정·설치·attestation·private header와 authorization을 upstream으로 전달하지 않고, 선택된 provider 인증만 주입한다.
- standalone
/images/generations와/images/edits는 외부 provider로 보내지 않고 native OpenAI Codex backend를 통과한다.
하나의 registry와 별도 local policy
문서는 provider/model registry가 catalog generation, router, LiteLLM config, API forwarder, doctor에서 공유된다고 설명한다. enabled-providers.json은 별도의 사용자 정책으로서 다음을 함께 제어한다.
- Codex picker에 보일 provider
- dispatcher가 실제 요청을 허용할 provider
- credential/OAuth session이 준비된 provider만 catalog에 포함하는 조건
숨겨진 provider의 알려진 namespaced model은 native 모델로 오인되지 않고 provider_not_enabled 로컬 오류로 닫힌다. 외부 요청마다 policy를 다시 읽으므로 provider visibility 변경에 local service 재시작이 필요하지 않지만, Codex picker catalog를 다시 읽으려면 Codex 재시작이 필요하다.
OpenAI login이 확인되지 않은 signed-out catalog에서는 외부 model을 ChatGPT desktop이 허용하는 native GPT slug에 alias하는 별도 경로도 제공한다. 이때 native-aliases.json이 canonical slug와 picker slug를 매핑하고, signed-in catalog가 생성되면 alias map을 지워 native GPT routing을 복원한다.
고정 커밋에서 문서화된 provider 표면
README와 HOW-IT-WORKS.md가 명시한 대표 모델/인증 조합은 다음과 같다.
| provider family | 예시 model ID | 인증/과금 경계 |
|---|---|---|
| Kimi Code OAuth | kimi-oauth/kimi-for-coding, kimi-oauth/k3 | 공식 Kimi CLI OAuth session |
| Kimi Platform API | kimi-api/kimi-k3 | 별도 Kimi Platform API key |
| DeepSeek | deepseek/deepseek-v4-flash, deepseek/deepseek-v4-pro | DeepSeek API key |
| Grok | grok-oauth/grok-4.5, grok-api/grok-4.5 | 공식 Grok CLI OAuth 또는 xAI API key |
| Anthropic | anthropic-api/claude-opus-4.8 | Anthropic API key |
| Ollama Cloud | ollama-cloud/glm-5.2, ollama-cloud/kimi-k2.7-code | Ollama Cloud API key/계정 |
| Qwen Plan | qwen-plan/qwen3.8-max, qwen-plan/deepseek-v4-pro | Alibaba Model Studio plan key |
| Z.ai Coding | zai-coding/glm-5.2, zai-coding/glm-5-turbo | GLM Coding Plan API key |
| opencode Go/Zen | opencode-go/grok-4.5 등 | opencode subscription/Zen API key family |
| Command Code | commandcode/..., commandcode-messages/... | Provider plan + key 또는 공식 CLI sign-in |
| Meta | meta/muse-spark-1.2 등 | Meta Model API key |
README는 API-key provider의 live /v1/models를 사용자가 직접 curation해 local user-models.json으로 보강할 수 있다고 설명한다. 이 curated model은 repository가 검증한 registry model과 달리 해당 머신에만 적용되며, provider endpoint가 모델 존재 여부를 결정한다.
인증·보안 경계
SECURITY.md, src/caller-auth.mjs, src/file-security.mjs, src/provider-credentials.mjs에서 확인한 방어 모델은 다음과 같다.
분리된 credential classes
- Native GPT: ChatGPT/Codex authentication을 allow-list 범위에서만 전달한다.
- Kimi OAuth:
$KIMI_CODE_HOME또는~/.kimi-code의 공식 CLI session을 읽고, router state에 복사하지 않는다. - API-key provider: Kimi Platform, DeepSeek, xAI, Anthropic 및 기타 provider key를 별도 protected file/environment/legacy Keychain 경로에서 조회한다.
- Internal trust: Codex-to-router caller capability와 내부 gateway/service key를 provider credential과 분리한다.
기본 state 디렉터리 아래 internal-secret, caller-secret, provider *-api-key.secret, native/merged catalog, generated LiteLLM config, provider selection, install manifest와 migration/support bundle을 current-user-only로 보호한다. POSIX에서는 파일 mode 600, state directory는 700으로 다루며 Windows에서는 현재 사용자 SID 중심 ACL을 적용한다고 문서화한다.
loopback과 request filtering
- Router·LiteLLM·OAuth/API forwarder는
127.0.0.1에만 bind한다. - 관리된 URL path에 random caller capability를 넣고 router가 이를 검증한 뒤에만 model request를 읽거나 upstream에 접속한다.
- 내부 gateway/forwarder에는 별도 random service key가 필요하다.
- JSON 요청만 허용하고 browser-origin header를 거부하며 CORS 권한을 주지 않는다.
- Codex config에는 random local-only capability가 들어갈 수 있으므로 완전한 URL은 민감 정보로 취급하고 상태 출력/diagnostic에서는 redacted form을 사용한다.
- 같은 OS user로 이미 실행 중인 악성 코드까지 막는 보안 경계는 아니다.
0.0.0.0bind, port tunnel, shared network 노출을 하지 말라는 운영 경고가 있다.
Codex 설정과 migration 안전성
설치기는 다음을 보존하는 것을 목표로 한다.
- 기존
model,model_provider, reasoning 설정, profiles - 기존 ChatGPT authentication
- 사용자가 관리하는 unmarked
openai_base_url,model_catalog_json, agent concurrency 값
router가 관리하는 marked block만 추가·갱신하고, 최초 변경 전 ~/.codex/config.toml.pre-codex-router를 만들며, 인식된 구형 router만 snapshot 후 중지·이관한다. unknown catalog owner나 unrecognized origin URL은 자동 교체하지 않는다. 문제가 생기면 config와 service를 원복하고, migrations/ snapshot과 rollback 명령으로 이전 설치를 되돌리는 경로를 둔다.
설치·운영 흐름
공식 설치 문서가 요구하는 환경은 다음과 같다.
- Codex App 또는 CLI
- Node.js 22.19 이상(Node.js 24 LTS 권장)
uv또는 Python 3.10+ withvenv- managed checkout/rollback을 위한 Git
- 최소 하나의 Kimi OAuth, Kimi API 또는 DeepSeek API credential
기본 설치는 macOS/Linux의 install.sh --target codex --guided, Windows의 install.ps1 -Target codex -Guided이며, 사용자가 선택한 provider를 확인하고 credential onboarding, locked Node dependencies, pinned LiteLLM, catalog generation, per-user service 등록, local layer health check, doctor 실행을 순서대로 수행한다고 설명한다. --smoke-test는 실제 provider quota를 사용할 수 있어 기본값이 아니다.
점검 명령은 ./bin/model-router codex doctor다. 문서상 핵심 성공 조건은 config privacy, merged catalog, caller capability, internal key, service, router health, 선택된 credential이 OK인 것이다. 고정 커밋의 AGENTS.md는 최종 Codex 재시작을 사용자가 직접 하도록 요구하며, 설치 agent가 token/API key를 chat·argument·log에 요청하지 않도록 명시한다.
T3 Code는 별도 router target이 아니다. 공식 호환 문서는 T3 Code가 공식 CLI를 감싸는 GUI이므로 그 underlying Codex adapter에 router를 설치하면 model list를 상속하고, T3 Code를 완전히 재실행해 picker를 다시 읽으면 된다고 설명한다.
transport·compaction·subagent 경계
- 현재 Codex build가 먼저 시도하는 Responses WebSocket에는 HTTP
426으로 응답한 뒤 HTTP fallback을 유도한다. - request body의 Zstandard, gzip, deflate, Brotli를 안전하게 decompress한 뒤 model ID를 검사한다.
- external Chat Completions provider가 OpenAI의 opaque encrypted compaction payload를 만들 수 없으므로 selected external model에 continuation summary를 요청하고 router-owned
kcr1:payload로 감싼다. - replay 시 해당 payload를 plain continuation message로 변환한다.
- native Codex collaboration subagent의 opaque encrypted task는 external provider가 직접 읽지 못하므로, routed subagent에 한해 native backend를 통한 제한된 relay를 사용한다. ChatGPT sign-in이 없으면 ciphertext를 외부로 보내지 않고 fail closed한다.
- commands, permissions, MCP tools, skills, task state는 Codex에 남고, router는 model inference와 external-model compaction 중심으로만 동작한다.
해석 — 이 프로젝트가 제공하는 추상화
Codex Router의 핵심은 “여러 모델 API를 한 endpoint로 묶는다”보다 Codex가 이미 가진 UX·catalog·session·subagent 실행면을 보존한 채 provider 선택권을 외부화하는 credential-isolating switchboard에 있다.
- 모델 교체가 앱 교체가 아니다. 외부 model을 native picker 옆에 병합하고 model slug를 명시적으로 namespacing해, 사용자는 Codex의 작업/프로필/도구 표면을 유지한 채 inference provider만 바꾼다.
- 인증은 provider별 신뢰 경계다. native GPT 요청과 Kimi/DeepSeek/Grok/API-key 요청을 같은 proxy credential로 섞지 않고, caller capability·internal key·provider key를 각기 분리한다.
- 설치기는 하네스의 일부다. config ownership, migration detection, rollback snapshot, catalog generation, doctor와 per-user service까지 포함해 “proxy 실행”보다 운영 상태 보존을 더 넓게 다룬다.
- registry가 곧 제품 계약이다. model slug·gateway ID·upstream ID·reasoning effort·context·modality·request profile을 declarative registry에 넣고, listed model은 live compatibility test 후에만 전역 노출하도록 요구한다.
- 로컬 우선이지만 provider는 외부다. local network surface와 credential storage는 제한하지만, 실제 모델 추론·검색·과금·OAuth는 각 vendor 시스템의 정책과 quota를 따른다.
변화하는 GitHub 스냅샷
GitHub REST API와 main ref를 2026-08-08 KST에 확인한 값이다.
- 918 stars · 75 forks · 11 open issues
- JavaScript · MIT · archived 아님
- repository size: 1,257 KB
- 기본 브랜치:
main - 확인 커밋:
6f03437e59c44eadc9acde8b140d5c832e36a69f - 커밋 시각:
2026-08-07T20:43:36Z - 커밋 메시지:
fix(gemini-api,service): sanitize non-user images, drop store/logit_bias, harden Windows startup - README byte SHA-256:
0febc27268008d361f2536c5d4753ecfae52cd0bb591a8061eefee564ba66f86
아직 검증하지 않은 것
이번 노트는 고정 커밋의 GitHub metadata, README, 설치/작동/보안/개발/트러블슈팅 문서, package metadata, selected source file을 읽어 정리한 것이다. 다음은 이 환경에서 실행하지 않았다.
npm ci,npm run check,npm test,npm audit- install.sh/install.ps1의 실제 설치·Node/Python/LiteLLM dependency setup
- Codex App/CLI의 실제 config migration, catalog picker, service registration, doctor 결과
- Kimi OAuth, Grok/Command Code sign-in, provider API-key onboarding
- local ports 4100–4103 기동과 Responses/Chat Completions streaming·tool call·compaction round-trip
- 실제 external provider quota/과금·model availability·rate-limit 동작
- native subagent encrypted payload relay와 login-free alias behavior의 실행 재현
- macOS/Linux/Windows 서비스·tray·desktop companion 빌드와 실행
- 독립 보안 감사, 악성 문서/renderer exploit/sandbox escape/동일 사용자 악성 코드 방어 검증
따라서 이 노트에서 “지원한다”는 표현은 해당 고정 커밋의 문서·소스가 그 경로를 정의한다는 뜻이며, 이 환경에서 설치·실행 성공을 재현했다는 뜻이 아니다.
관련 노트
- 2026-08-17-commandcode-ai — coding taste·Skills·MCP·권한을 결합한 상용 AI 코딩 하네스
- raw source:
github-duolahypercho-codex-router— 고정 커밋과 선택 원문 파일 해시를 보존한 provenance pointer - moc-ai-coding — Codex·AI 코딩 도구와 운영면 지도
- moc-ai-agents-harness — 라우팅·credential·migration·doctor를 하네스/운영 제어면으로 보는 연결
- moc-dev-tools — 개발 도구·로컬 서비스·CLI 운영 연결
- 2026-08-08-github-criptogus-hermesoffice — Hermes Agent를 기본 AI 경로로 붙인 Electron 오피스와 비교
- 2026-08-08-github-agentplugins-agent-plugins-spec — skills/MCP 확장 패키징 표준과 Codex Router의 registry/provider 계약 비교
출처 및 검증
- 공식 저장소: duolahypercho/codex-router
- 고정 커밋: 6f03437
- README pinned raw: README.md, byte SHA-256
0febc27268008d361f2536c5d4753ecfae52cd0bb591a8061eefee564ba66f86 - 작동 설명: HOW-IT-WORKS.md
- 설치/마이그레이션: INSTALL.md
- 보안 정책: SECURITY.md
- REST metadata: GitHub API