sybil-solutions/codex-shim

codex‑shim – Codex Desktop용 로컬 라우팅 쉴드

무엇인가요

• Codex Desktop이 기대하는 OpenAI Responses API를 위장하는 작고 가벼운 Python + aiohttp 서버입니다.
• 127.0.0.1:8765에서 작동하며, 사용자가 설정한 업스트림 모델(OpenAI, Anthropic, DeepSeek, Gemini, OpenRouter, 로컬 Ollama 서버, 또는 공식 ChatGPT Codex 엔드포인트)로 각 요청을 전달합니다.
• 요청/응답 형식(스트리밍 SSE, 도구 호출, 이미지 입력 등)을 변환하여 Codex Desktop은 네이티브 UI와 에이전트 루프를 변경하지 않고 그대로 사용할 수 있습니다.

왜 사용할까

• 자신의 모델(BYOK) 도입 – 앱을 재빌드하지 않고 Codex Desktop에 사용자 모델을 추가할 수 있습니다. 모델 정보를 기술한 JSON 파일을 배치하기만 하면 피커에 모델이 나타납니다.
• Codex UX 유지 – 함수 호출, 추론 블록, 이미지 처리, 스트리밍이 내장 모델과 동일하게 작동합니다.
• 옵션 ChatGPT 패스스루 – 유효한 Codex 액세스 토큰이 있다면, gpt‑5.5 슬러그로 공식 ChatGPT Codex 백엔드에 /v1/responses를 전달할 수 있습니다.
• Cursor 통합 – Cursor에 로그인한 상태에서 별도의 대시보드 API 키 없이 composer‑2‑5 모델을 노출할 수 있습니다.
• 스마트 자동 라우터(옵션) – 저렴한 분류기가 주어진 작업을 처리할 수 있는 가장 저렴한 모델을 자동으로 선택합니다.
• 프록시 친화적 – 다른 로컬 프록시를 쉴드 앞에 배치하여 지시를 삽입하거나 프롬프트 중복 제거 또는 정책 강제를 할 수 있습니다.

작동 방식

1. 설정 – ~/.codex‑shim/models.json을 생성하거나 --settings로 사용자 정의 파일을 전달합니다. 각 항목에는 다음을 포함합니다:
   • model / slug
   • provider (openai, anthropic, generic-chat-completion-api 등)
   • base_url 및 인증(api_key 또는 api_key_env)
   • 선택적 UI 힌트(display_name, max_context_limit, no_image_support 등)
2. 카탈로그 생성 – codex‑shim generate가 JSON을 읽고 Codex 호환 카탈로그(custom_model_catalog.json)와 프로바이더 설정(config.toml)을 생성합니다.
3. 쉴드 실행 – codex‑shim start로 loopback 주소에서 대기하는 aiohttp 데몬을 시작합니다.
4. Codex Desktop에 연결 – codex‑shim app .로 Codex Desktop을 시작하고, ~/.codex/config.toml에 로컬 프로바이더를 삽입합니다. 이제 사용자가 나열한 모든 모델과, 토큰이 있다면 선택적 gpt‑5.5 패스스루를 인식합니다.
5. 모델 전환 – codex‑model list로 슬러그를 확인하고, codex‑model <slug>로 선택한 후 codex‑app으로 재시작하여 새 기본값을 적용합니다.

지원되는 업스트림

프로바이더	업스트림 엔드포인트
openai	OpenAI /v1/chat/completions
generic-chat-completion-api	어떤 OpenAI 형식의 채팅 엔드포인트든
anthropic	Anthropic /v1/messages
ollama (generic을 통해)	로컬 Ollama /v1/chat/completions
opencode‑go (refresh 명령어)	OpenCode Go 카탈로그 API

쉴드는 자체 엔드포인트에서 Anthropic 형식의 Messages 요청을 수신하고, 적절한 형태로 업스트림에 변환할 수 있습니다.

주요 명령어

• codex‑shim generate – 모델 목록에서 카탈로그 생성.
• codex‑shim start – 로컬 서버 실행.
• codex‑shim status – 상태 확인 및 모델 수 표시.
• codex‑shim list – 어떤 슬러그가 어떤 업스트림에 매핑되는지 표시.
• codex‑shim app – 쉴드가 연결된 상태에서 Codex Desktop 실행.
• codex‑shim model use <slug> – 다음 세션용 모델 선택.
• codex‑shim disable – Codex 설정에서 쉴드 관리 블록 제거.
• codex‑shim patch‑app / restore‑app – macOS 전용 ASAR 패치. Codex Desktop의 피커에 커스텀 슬러그를 표시하게 함(공식 앱이 알 수 없는 모델을 숨기기 때문에 macOS에서는 필수).
• codex‑shim opencode‑go refresh – 최신 OpenCode Go 모델 목록을 자동으로 가져옴.

설치

git clone https://github.com/0xSero/codex-shim ~/codex-shim
cd ~/codex-shim
python3 -m pip install --user -e .   # `codex-shim` CLI 설치

(Windows 사용자는 py -3.11로 동일한 단계를 수행할 수 있습니다.)

플랫폼 지원

• macOS, Linux, WSL, Git Bash, 네이티브 Windows PowerShell/cmd에서 작동.
• 핵심 쉴드는 순수 Python으로 구성되며, 옵션의 macOS 피커 패치만 npx와 codesign을 필요로 함.
• Windows Store/MSIX 빌드의 Codex는 커스텀 슬러그를 숨길 수 있지만, 라우팅은 여전히 작동함. UI는 내장 모델만 표시함.

일반 워크플로우

# 1. 모델 정의
cat ~/.codex-shim/models.json   # (스키마는 README 참조)

# 2. 카탈로그 생성 및 쉴드 실행
codex-shim generate && codex-shim start

# 3. 쉴드를 통해 Codex Desktop 실행
codex-shim app .

# 4. 드롭다운에서 모델 선택(또는 CLI로)
codex-model list
codex-model gpt-5.5
codex-app   # 새 기본값 적용을 위해 재시작

얻을 수 있는 것

• Codex Desktop의 모든 고급 기능(함수 호출, 도구 출력, 이미지 지원, 스트리밍)이 그대로 작동.
• 간단한 작업에는 저렴한 로컬 모델(Ollama 등)로 라우팅하고, 어려운 작업에는 자동으로 더 강력한 클라우드 모델로 전환.
• Codex Desktop을 재빌드하거나 재서명할 필요 없음(옵션의 macOS 피커 패치 제외).

---

결론: codex‑shim은 상용 Codex Desktop 코딩 어시스턴트가 OpenAI 호환, Anthropic, 또는 로컬 호스팅된 LLM을 원하는 대로 사용할 수 있도록 해주는 실용적인 브리지입니다. 앱의 네이티브 경험을 유지하면서도 순수 Python 기반의 크로스플랫폼 쉴드이며, 새로운 모델이나 학습 프레임워크가 아닙니다.