[AI 활용팁] 코덱스는 그대로, 모델만 바꾼다…오픈코덱스 설치와 설정법

1. 오픈코덱스가 하는 일

🎯 코덱스 워크플로는 그대로, 안에서 일하는 모델만 교체한다

오픈코덱스(opencodex)는 오픈AI 코덱스가 보내는 요청을 각 AI 제공사의 형식으로 바꿔 주는 가벼운 로컬 프록시다. 코덱스는 자기 형식(Responses API)으로 요청을 보내고, 오픈코덱스가 그것을 앤트로픽이나 구글의 형식으로 옮겨 전달한다. 코덱스 입장에서는 평소처럼 동작하고, 실제 답을 만드는 모델만 바뀐다.

지원 대상은 클로드와 제미나이, 그록, GLM, 딥시크, 키미, 큐원, 올라마 등이다. 코덱스 CLI와 앱, SDK 모두에서 쓸 수 있고, 오픈AI가 공식 지원을 추가하기를 기다릴 필요가 없다.

2. 설치

🔧 번(Bun) 먼저, 그다음 오픈코덱스

오픈코덱스는 번(Bun) 1.1 이상에서 돌아간다. 번이 없다면 먼저 설치한다.

맥·리눅스: curl -fsSL https://bun.sh/install | bash
윈도우(파워셸): powershell -c “irm bun.sh/install.ps1 | iex”

그다음 오픈코덱스를 전역 설치한다. 맥과 리눅스, 윈도우 모두 네이티브로 작동하며 윈도우에서 WSL이 필요하지 않다.

설치: npm install -g @bitkyc08/opencodex
초기 설정: ocx init
실행: ocx start

3. 제공자 추가

📌 웹 대시보드가 가장 빠르다

ocx gui를 실행하면 localhost:10100에 대시보드가 표시된다. 여기서 ‘Add Provider’를 누르고 40여 개 내장 제공자 중 하나를 고른 뒤 API 키를 붙여 넣는다. 앤트로픽과 xAI, 키미는 API 키 대신 OAuth 로그인을 쓸 수 있다. 모델 목록은 제공자의 /v1/models 응답에서 자동으로 읽어 온다. 다시 시작하지 않아도 바로 반영된다.

4. 모델 지정

⚡ provider/model 형식으로 부른다

codex -m “anthropic/claude-opus-4-8” “이 스택 트레이스를 설명해 줘”
codex -m “google/gemini-3-pro” “auth.ts 단위 테스트를 작성해 줘”
codex -m “ollama/llama3” “이 함수를 리팩터링해 줘”

provider/를 빼면 기본 제공자로 가거나, 모델 이름 패턴에 따라 자동으로 연결된다. claude-로 시작하면 앤트로픽, gpt-로 시작하면 오픈AI로 간다. 지정한 모델은 코덱스 앱의 모델 선택 화면에도 표시되며, 모델별로 추론 강도를 따로 정할 수 있다.

5. 원상복구

✨ ocx stop 한 줄이면 흔적이 남지 않는다

ocx stop을 실행하면 프록시가 멈추고, 백그라운드 서비스가 설치돼 있으면 함께 내려간다. 코덱스 설정도 원래대로 되돌아간다. 이후 codex 명령은 설치 전과 똑같이 작동한다.

명령	하는 일
ocx init	대화형 초기 설정
ocx start	프록시 실행 (기본 포트 10100)
ocx stop	중지 후 코덱스 원상복구
ocx sync	모델 목록 갱신·재주입
ocx status	실행 여부 확인
ocx login	OAuth 로그인 (xai·anthropic·kimi)
ocx gui	웹 대시보드 열기

6. 알아 둘 것

설정 파일은 ~/.opencodex/config.json에 저장된다. 로컬에서 돌리는 올라마나 vLLM, LM 스튜디오도 OpenAI 호환 주소만 적어 주면 연결된다. 스트리밍과 툴 호출, 추론 토큰, 이미지가 양방향으로 지원된다.

라이선스는 MIT이며 소스는 공개돼 있다. 최신 버전은 6월 20일 공개된 2.0.0이다. 다만 저장소의 스타는 20개, 포크는 3개로 아직 이용자가 많지 않은 초기 프로젝트다. 업무에 바로 넣기보다 따로 시험해 본 뒤 쓰는 편이 안전하다.

🔗 공식 저장소: github.com/lidge-jun/opencodex
🔗 공식 문서: lidge-jun.github.io/opencodex

자세한 내용은 오픈코덱스 공식 저장소에서 확인할 수 있다.

이미지 출처: 오픈코덱스