설치

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

기본 로컬 경로는 기존 ChatGPT/Codex 로그인만으로 바로 사용할 수 있습니다. OpenAI API 키를 포함한 어떤 프로바이더 API 키도 필요하지 않습니다.

사전 요구 사항

요구 사항	이유
Node ≥ 18	작은 launcher가 macOS, Linux, Windows의 amd64/x64 및 arm64용 Go 바이너리를 정확히 확인한 뒤 실행합니다. Bun을 직접 설치할 필요는 없습니다.
OpenAI Codex(CLI, App, 또는 SDK)	opencodex가 앞단에 위치하는 클라이언트입니다. opencodex는 $CODEX_HOME/config.toml(기본값 ~/.codex/config.toml)에 기록합니다.
ChatGPT/Codex 로그인	기본 내장 openai 경로는 codex login 또는 Codex 앱이 만든 계정 세션을 전달합니다. API 키가 아닙니다.
업스트림 프로바이더 계정 또는 API 키(선택 사항)	Anthropic, xAI, Kimi, Ollama Cloud, OpenRouter, 다른 호스팅 프로바이더 또는 인증이 필요한 사용자 지정 경로를 직접 추가한 경우에만 필요합니다.

설치

npm install -g @bitkyc08/opencodex

Bun이 계속 설치되는 이유

Bun 의존성은 이전 updater, 기존 Codex shim을 한 번 갱신하는 전환 경로, Bun 패키지 API를 명시적으로 쓰는 호출자를 위해 당분간 남아 있습니다. 지원되는 6개 대상의 일반 명령에서는 Bun이 실행되지 않습니다. 미지원 플랫폼에서는 호환 bridge가 Bun을 사용할 수 있으며, 이 전환 경로를 정리한 뒤에 의존성을 제거할 예정입니다.

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

ocx --version
opencodex --version

기본 로컬 경로를 즉시 시작할 수 있습니다:

ocx start

이 터미널을 열어 둔 채 다른 터미널에서 ocx codex를 실행하세요. Codex에 로그인한 적이 없다면 codex login을 한 번 실행합니다. ocx gui는 실제 프록시 포트에서 대시보드를 열고 필요하면 프록시를 먼저 시작합니다.

로컬 시작에는 API 키가 필요 없음

업스트림 프로바이더 API 키는 직접 추가한 선택적 프로바이더를 인증합니다. OpenCodex 접근 키는 프록시를 비루프백 주소로 공개할 때만 /v1/*를 보호합니다. localhost와 ChatGPT/Codex 로그인을 사용하는 기본 경로에는 둘 다 필요하지 않습니다.

배포 채널

안정화 채널인 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 자체를 직접 수정하려면 로컬에 bun CLI를 설치하고 PATH에 등록해야 합니다:

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, 호스트명, 포트.
$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가 사용하는 네이티브 및 라우팅 모델 카탈로그.

참고

opencodex는 절대 Codex 설정을 삭제하지 않습니다. 모든 주입은 되돌릴 수 있습니다 — ocx stop, ocx restore, 또는 ocx eject는 opencodex가 추가한 줄만 정확히 제거하고 네이티브 Codex를 복원합니다.

다음

Quickstart로 이동해 키가 필요 없는 로컬 기본값을 시작하거나, 아키텍처를 알아보려면 작동 방식을 읽어 보세요.