설치

opencodex를 설치하면 같은 실행 파일을 가리키는 ocx와 opencodex 명령이 함께 제공됩니다. 둘 다 Bun 기반의 작은 로컬 HTTP 서버를 실행합니다. 모델 요청은 라우팅으로 선택된 프로바이더에 전달되며, 필요할 때 vision 및 웹 검색 sidecar가 ChatGPT 로그인을 사용할 수도 있습니다.

사전 요구 사항

요구 사항	이유
Node ≥ 18	`ocx`는 Bun 런타임에서 실행되지만, 런타임이 `npm install` 시 자동으로 번들되므로 Bun을 직접 설치할 필요가 없습니다.
OpenAI Codex(CLI, App, 또는 SDK)	opencodex가 앞단에 위치하는 클라이언트입니다. opencodex는 `$CODEX_HOME/config.toml`(기본값 `~/.codex/config.toml`)에 기록합니다.
프로바이더 계정 또는 API 키	Anthropic, xAI, Kimi, Ollama Cloud, OpenRouter, OpenAI API 키, OpenAI 호환 엔드포인트, 또는 ChatGPT 로그인.

설치

npm install -g @bitkyc08/opencodex

최신 npm은 bun의 postinstall 스크립트를 차단할 수 있습니다(npm warn install-scripts ... blocked because they are not covered by allowScripts). 이 경우 번들 Bun 런타임이 준비되지 않을 수 있습니다. 런처는 허용된 번들 복구를 시도한 다음, 절대 경로 PATH 디렉터리의 실행 가능한 Bun을 검증합니다. 정식 버전의 major가 패키지 pin과 같고 minor가 pin 이상이면 사용할 수 있습니다. 현재 의존성 1.4.2에서는 1.4.0 이상, 2.0.0 미만입니다. 제한 시간 안에 버전 정책과 identity를 확인하며, bun --version 출력이 bun -e로 확인한 Bun.version과 같아야 합니다. POSIX에서는 런처가 상위 디렉터리와 심볼릭 링크를 따라 도달하는 구성 요소를 포함한 후보 경로 전체를 검사합니다. 검사하는 각 디렉터리와 심볼릭 링크, 최종 실행 파일은 root 또는 런처의 유효 사용자 소유여야 합니다. 디렉터리와 최종 실행 파일에 그룹 또는 다른 사용자의 쓰기 권한이 있으면 거부하며, 심볼릭 링크의 권한 비트는 사용하지 않습니다. /tmp 같은 공유 쓰기 가능 상위 디렉터리는 sticky bit가 있어도 거부하므로 실행 파일과 바로 위 부모 디렉터리만 보호하는 것으로는 충분하지 않습니다. 선택한 Bun 버전을 stderr 한 줄로 알립니다. Bun은 계속 패키지에 포함되므로 별도 설치는 선택 사항입니다.

사용할 런타임이 없고 의존성이 빠져 있으면 오류에 “the bun dependency is not installed”가 표시됩니다. macOS에서는 실행 가능한 Desktop CLI가 있으면 /Applications/OpenCodex.app/Contents/MacOS/ocx 또는 ~/Applications/OpenCodex.app/Contents/MacOS/ocx 경로도 안내합니다. 이 경로를 직접 실행할 수 있지만 패키지 런처가 자동 위임하거나 PATH shim을 설치하지는 않습니다.

번들 런타임을 복구하려면 bun 스크립트를 허용해서 재설치하세요. npm 경고의 축약 명령에는 패키지 이름이 빠져 있어 현재 디렉터리를 재설치하게 되니, 항상 패키지 이름을 명시해야 합니다:

npm install -g --allow-scripts=bun @bitkyc08/opencodex

# 처음에 sudo로 설치했다면 sudo를 유지하세요:
sudo npm install -g --allow-scripts=bun @bitkyc08/opencodex

두 명령이 모두 PATH에 잡히는지 확인합니다:

ocx --version
opencodex --version

start, stop, restart, service와 Bun CLI가 처리하는 update에서는 CLI와 실행 중인 프록시의 버전이 다르면 짧은 stderr 안내가 나올 수 있습니다. 안내는 명령 종료 코드를 바꾸지 않으며 JSON·도움말 모드에서는 실행하지 않습니다. Bun CLI 시작 전에 Node 런처가 처리하는 npm/pnpm update에는 이 안내가 적용되지 않습니다. ocx status, ocx doctor, ocx resolve는 기존 진단에서 버전 차이를 표시합니다.

독립 실행형 바이너리(npm 없음)

릴리스에는 지원되는 macOS, Linux, Windows용 독립 실행형 ocx 바이너리도 포함됩니다. Bun 런타임과 대시보드가 포함되어 있으므로 npm, Node 또는 별도의 Bun 설치가 필요하지 않습니다. 플랫폼에 맞는 아카이브를 다운로드해 압축을 풀고 다음과 같이 실행하세요.

./ocx --version
./ocx start

대시보드를 제공하려면 압축을 푼 gui/dist 디렉터리를 바이너리 옆에 그대로 두어야 합니다.

배포 채널

안정화 채널인 latest에도 ChatGPT, OpenAI API 키, OpenRouter, 실험 단계의 Cursor 경로를 위한 GPT-5.6 Sol/Terra/Luna 카탈로그 정보가 이미 들어 있습니다. 다만 모델 사용 권한까지 생기는 것은 아닙니다. 아직 정식 배포되지 않은 opencodex 빌드를 시험할 때만 preview 채널을 사용하세요:

npm install -g @bitkyc08/opencodex@preview
ocx update --tag preview

소스에서 실행

opencodex 자체를 직접 수정하며 작업하려면:

git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
bun install
bun run dev:proxy   # 개발 모드로 프록시 API 시작 (src/cli/index.ts start)
bun run dev:gui     # 대시보드 dev 서버 시작 (다른 터미널)

bun run dev는 bun run dev:proxy의 별칭으로 남아 있습니다. 프록시 API는 /healthz, /v1/responses, /api/*를 노출하며, GET /는 bun run build:gui가 gui/dist를 생성한 뒤에만 패키징된 대시보드를 서빙합니다. 대시보드를 수정할 때는 bun run dev:gui로 프론트엔드를 별도로 실행하세요.

생성되는 항목

opencodex 상태 파일은 $OPENCODEX_HOME(기본값 ~/.opencodex) 아래에, Codex 연동 파일은 $CODEX_HOME(기본값 ~/.codex) 아래에 저장됩니다.

경로	용도
`$OPENCODEX_HOME/config.json`	프로바이더, 기본 프로바이더, 포트, 옵션.
`$OPENCODEX_HOME/ocx.pid`	실행 중인 프록시의 PID(단일 인스턴스 가드).
`$OPENCODEX_HOME/runtime-port.json`	현재 PID, 호스트명, 포트. `config.port`가 `0`이면 OS가 할당한 포트도 포함합니다.
`$OPENCODEX_HOME/auth.json`	저장된 OAuth 자격 증명(`ocx login` 시).
`$OPENCODEX_HOME/catalog-backup*.json`	opencodex가 수정하기 전에 만든 Codex 모델 카탈로그 백업.
`$CODEX_HOME/config.toml`	로컬 전용 구성에서는 opencodex가 관리하는 루트 `openai_base_url`을 추가합니다. 로컬이 아닌 주소에 바인딩할 때는 Codex가 API 인증 헤더를 보낼 수 있도록 `model_provider = "opencodex"`와 `[model_providers.opencodex]`를 사용합니다.
`$CODEX_HOME/opencodex.config.toml`	기본 Codex 설정과 함께 생성되는 참고용 fallback 프로필.
`$CODEX_HOME/opencodex-catalog.json`	Codex가 사용하는 네이티브 및 라우팅 모델 카탈로그.

Quickstart로 이동해 첫 프로바이더를 설정하거나, 아키텍처를 알아보려면 작동 방식을 읽어 보세요.