{"id":51217536,"url":"https://github.com/lidge-jun/opencodex","last_synced_at":"2026-06-30T10:01:06.246Z","repository":{"id":365799322,"uuid":"1273824907","full_name":"lidge-jun/opencodex","owner":"lidge-jun","description":"Universal provider proxy for OpenAI Codex — use any LLM with Codex CLI, App, and SDK","archived":false,"fork":false,"pushed_at":"2026-06-28T03:09:54.000Z","size":11577,"stargazers_count":144,"open_issues_count":2,"forks_count":12,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-28T05:22:02.758Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lidge-jun.png","metadata":{"files":{"readme":"README.ko.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-18T23:03:18.000Z","updated_at":"2026-06-28T03:19:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lidge-jun/opencodex","commit_stats":null,"previous_names":["lidge-jun/opencodex"],"tags_count":39,"template":false,"template_full_name":null,"purl":"pkg:github/lidge-jun/opencodex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lidge-jun%2Fopencodex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lidge-jun%2Fopencodex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lidge-jun%2Fopencodex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lidge-jun%2Fopencodex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lidge-jun","download_url":"https://codeload.github.com/lidge-jun/opencodex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lidge-jun%2Fopencodex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34961549,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-28T05:00:29.301Z","updated_at":"2026-06-30T10:01:06.148Z","avatar_url":"https://github.com/lidge-jun.png","language":"TypeScript","funding_links":[],"categories":["Tools"],"sub_categories":["Development Tools"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/banner.png\" alt=\"opencodex — 어떤 LLM이든 Codex에서 사용\" width=\"820\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"README.md\"\u003eEnglish\u003c/a\u003e · \u003cb\u003e한국어\u003c/b\u003e · \u003ca href=\"README.zh-CN.md\"\u003e简体中文\u003c/a\u003e · 📖 \u003ca href=\"https://lidge-jun.github.io/opencodex/ko/\"\u003e\u003cb\u003e전체 문서 →\u003c/b\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/architecture.png\" alt=\"opencodex 아키텍처 — Codex CLI가 opencodex 프록시를 통해 모든 LLM 프로바이더로 라우팅\" width=\"820\"\u003e\n\u003c/p\u003e\n\nCodex는 오직 Responses API(`/v1/responses`)만 사용합니다. opencodex는 Codex와 LLM 프로바이더 사이에서\n프로토콜을 실시간으로 변환해 줍니다. streaming, tool 호출, reasoning, 이미지까지 양방향으로 처리합니다.\n\n```\nCodex CLI / App / SDK ──/v1/responses──▶ opencodex ──▶ Any provider\n                                              │\n              Anthropic · Google · xAI · Kimi · Ollama Cloud · Groq\n              OpenRouter · Azure · DeepSeek · GLM · …and OpenAI itself\n```\n\n## 지원 플랫폼\n\n| OS | 지원 상태 | 서비스 관리자 |\n|---|---|---|\n| macOS (arm64 / x64) | 완전 지원 | launchd |\n| Linux (x64 / arm64) | 완전 지원 | systemd (user unit) |\n| Windows (x64) | 완전 지원 | Task Scheduler |\n\n[Node](https://nodejs.org) 18 이상이 필요합니다. Bun 런타임은 `npm install` 시 자동으로 번들되므로 따로 설치할 필요가 없습니다. 세 플랫폼 모두 네이티브로 동작합니다 (Windows에서도 WSL 없이 사용 가능합니다).\n\n## 빠른 시작\n\n```bash\n# 설치 (Bun 런타임이 자동으로 번들됩니다 — Node 18+ 만 있으면 됩니다)\nnpm install -g @bitkyc08/opencodex\n\n# 대화형 설정 (config 작성 + Codex 주입 + 자동 시작 shim 설치 선택)\nocx init\n\n# 프록시 시작\nocx start\n\n# init에서 건너뛰었다면 나중에 온디맨드 자동 시작 shim 설치\nocx codex-shim install\n\n# Codex를 평소처럼 사용하세요 — opencodex를 통해 라우팅됩니다\ncodex \"Write a hello world in Rust\"\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e\"bundled Bun runtime is missing\" 오류가 나나요?\u003c/b\u003e\u003c/summary\u003e\n\n\u003cbr/\u003e\n\nopencodex는 Bun 런타임을 의존성으로 번들하고 Node 런처로 실행하므로 Bun을 직접 설치할 필요가 **없습니다**. \"bundled Bun runtime is missing\" 오류가 보이면 설치 과정에서 lifecycle 스크립트나 optional 의존성이 건너뛰어진 경우입니다. 해당 플래그 없이 다시 설치하세요:\n\n```bash\nnpm install -g @bitkyc08/opencodex   # --ignore-scripts, --omit=optional 없이\n```\n\n\u003c/details\u003e\n\n## 프로바이더 추가하기\n\n가장 쉬운 방법은 웹 대시보드를 이용하는 것입니다.\n\n```bash\nocx gui        # 브라우저에서 localhost:10100 대시보드를 엽니다\n```\n\n대시보드에서 할 수 있는 일:\n\n1. **프로바이더 선택** — 20개 이상의 내장 프로바이더(Anthropic, Google, xAI, Ollama Cloud 등)에서 원하는 것을 고르세요.\n2. **API 키 입력** — 키를 붙여넣으면 바로 저장됩니다. OAuth를 지원하는 프로바이더는 로그인 버튼으로 인증할 수도 있습니다.\n3. **모델 자동 감지** — 프로바이더를 추가하면 사용 가능한 모델을 자동으로 가져옵니다. Codex 모델 선택기에도 곧바로 반영됩니다.\n\n물론 `~/.opencodex/config.json`을 직접 편집해도 됩니다. 하지만 대시보드가 훨씬 편리합니다.\n\n## 모델 라우팅\n\n`provider/model` 형식으로 원하는 모델을 직접 지정할 수 있습니다:\n\n```bash\ncodex -m \"anthropic/claude-opus-4-8\"   \"이 스택 트레이스를 설명해 줘\"\ncodex -m \"google/gemini-2.5-pro\"       \"이 코드를 리팩터링해 줘\"\ncodex -m \"ollama-cloud/glm-5.2\"        \"SQL 마이그레이션 작성\"\ncodex -m \"xai/grok-4\"                  \"이 PR을 리뷰해 줘\"\n```\n\n프로바이더 이름 없이 모델명만 쓰면 `defaultProvider`로 라우팅됩니다.\n\n## 주요 기능\n\n- **다섯 가지 adapter**로 Anthropic Messages, Google Gemini, Azure, OpenAI Responses passthrough, 그리고 **모든 OpenAI 호환 Chat Completions** 엔드포인트를 지원합니다. 프로바이더가 OpenAI 호환 API를 제공한다면 별도 adapter 없이 바로 연결할 수 있습니다.\n- **OAuth, API 키, ChatGPT forward** 중 원하는 인증 방식을 선택하세요. xAI / Anthropic / Kimi 계정으로 OAuth 로그인하면 토큰이 자동 갱신됩니다. `codex login`을 forward 하거나, API 키를 직접 입력해도 됩니다(`${ENV_VARS}` 지원). 18개 프로바이더의 API 키 카탈로그(**Ollama Cloud** 포함)가 기본 내장되어 있습니다.\n- **Codex CLI, TUI, App, SDK에 바로 연결됩니다.** `$CODEX_HOME/config.toml`(기본 `~/.codex/config.toml`)에 `[model_providers.opencodex]` 테이블을 자동 주입하고, 공유 모델 카탈로그를 작성합니다. 라우팅된 모델이 Codex 모델 선택기에 자동으로 나타납니다.\n- **서브에이전트 제어.** `subagentModels` 또는 웹 대시보드에서 최대 5개의 모델을 골라 Codex `spawn_agent` 선택기에 우선 노출할 수 있습니다.\n- **기본은 HTTP/SSE, WebSocket은 opt-in.** 프록시에 Responses WebSocket 엔드포인트가 있지만, `\"websockets\": true`로 설정할 때만 `supports_websockets`를 광고합니다.\n- **Sidecar로 기능 확장.** OpenAI가 아닌 모델에서도 ChatGPT 로그인을 통한 `gpt-5.4-mini`로 실제 **웹 검색**과 **이미지 이해** 기능을 사용할 수 있습니다.\n- **웹 대시보드** 하나로 프로바이더 관리, OAuth 로그인, 모델 선택, 요청 로그 확인까지 가능합니다.\n- **깔끔한 종료, 잔여물 제로.** `ocx stop`(또는 대시보드의 Stop 버튼)을 누르면 프록시가 종료되고, 백그라운드 서비스가 설치돼 있으면 함께 내려가며, Codex 설정이 원본으로 복원됩니다. 이후 `codex` 명령은 opencodex 없이 원래대로 동작합니다.\n\n## 프로바이더 및 adapter\n\n| Provider | Adapter | 인증 방식 |\n|---|---|---|\n| OpenAI (ChatGPT 로그인) | `openai-responses` | forward (키 불필요) |\n| OpenAI (API 키) | `openai-responses` | key |\n| Umans AI Coding Plan | `anthropic` | key |\n| Anthropic Claude | `anthropic` | oauth / key |\n| xAI Grok | `openai-chat` | oauth / key |\n| Kimi (Moonshot) | `openai-chat` | oauth / key |\n| Google Gemini | `google` | key |\n| Azure OpenAI | `azure` | key |\n| Ollama Cloud + 17개 프로바이더 카탈로그 | `openai-chat` | key |\n| Ollama / vLLM / LM Studio (로컬) | `openai-chat` | key (보통 비워둠) |\n| 모든 OpenAI 호환 엔드포인트 | `openai-chat` | key |\n\n## CLI\n\n```bash\nocx init                       # 대화형 설정\nocx start [--port 10100]       # 프록시 시작; 포트가 사용 중이면 빈 포트로 자동 전환\nocx stop                       # 프록시 중지 + Codex 원래 설정 복원\nocx restore                    # 중지 없이 복원 (별칭: ocx eject)\nocx uninstall                  # service/shim/config 제거 + Codex 원본 복원\nocx ensure                     # 필요 시 시작 + Codex config/cache 갱신\nocx sync                       # 모델 갱신 + Codex에 재주입\nocx status                     # 프록시 실행 중인지 확인\nocx login \u003cxai|anthropic|kimi\u003e # OAuth 로그인\nocx logout \u003cprovider\u003e          # 저장된 로그인 정보 삭제\nocx gui                        # 웹 대시보드 열기\nocx codex-shim install         # codex 실행 시 `ocx ensure` 실행\nocx service \u003cinstall|start|stop|status|uninstall\u003e   # 백그라운드 서비스 (launchd/systemd/schtasks)\nocx update [--tag preview]     # opencodex 업데이트; preview 설치는 @preview 유지\n```\n\n### 자동 시작: service vs shim\n\nopencodex에는 프록시를 자동 시작하는 두 가지 방법이 있습니다:\n\n| | `ocx service install` | `ocx codex-shim install` |\n|---|---|---|\n| **방식** | OS 서비스 관리자 (launchd / systemd / schtasks) | `codex` 스크립트 런처를 래핑하며 실제 `codex.exe`는 건드리지 않음 |\n| **시점** | 로그인 후 항상 실행 | 온디맨드 — `codex` 실행 시 `ocx ensure` 실행 |\n| **재시작** | 크래시 시 자동 재시작 | `codex` 호출마다 한 번 시작 |\n| **Codex 업데이트** | 영향 없음 | `ocx codex-shim install` 또는 `ocx update` 시 복구 |\n| **제거** | `ocx service uninstall` | `ocx codex-shim uninstall` |\n\n항상 프록시를 켜두려면 **service** (개발 머신 권장), 가볍게 온디맨드로 쓰려면 **shim**을 사용하세요.\nshim 자동 시작은 기본으로 켜져 있으며 GUI 대시보드에서 끌 수 있습니다. 설정된 프록시 포트가 이미 사용\n중이면 `ocx start`가 자동으로 다른 빈 로컬 포트를 고르고 Codex 설정도 그 포트로 갱신합니다.\n\n### 삭제\n\nnpm 패키지를 지우기 전에 로컬 상태를 먼저 정리하세요:\n\n```bash\nocx uninstall\nnpm uninstall -g @bitkyc08/opencodex\n```\n\n`ocx uninstall`은 프록시 중지, 설치된 service 제거, Codex shim 제거, Codex config/catalog/history\n원복, `~/.opencodex` 삭제를 처리합니다.\n\n## 설정\n\n설정 파일은 `~/.opencodex/config.json`에 저장됩니다. 파일이 깨진 경우(잘못된 JSON 등)\nopencodex는 `config.json.invalid-\u003ctimestamp\u003e`로 백업하고 경고를 출력한 뒤 기본값으로 시작합니다.\n원본 파일이 조용히 사라지는 일은 없습니다.\n\n최소 설정 예시:\n\n```json\n{\n  \"port\": 10100,\n  \"defaultProvider\": \"anthropic\",\n  \"providers\": {\n    \"anthropic\": {\n      \"adapter\": \"anthropic\",\n      \"baseUrl\": \"https://api.anthropic.com\",\n      \"authMode\": \"oauth\",\n      \"defaultModel\": \"claude-sonnet-4-6\"\n    },\n    \"ollama-cloud\": {\n      \"adapter\": \"openai-chat\",\n      \"baseUrl\": \"https://ollama.com/v1\",\n      \"apiKey\": \"${OLLAMA_API_KEY}\",\n      \"defaultModel\": \"glm-5.2\"\n    }\n  }\n}\n```\n\n로컬에서 Ollama나 LM Studio를 실행 중이라면 이렇게 추가하세요:\n\n```json\n{\n  \"ollama-local\": {\n    \"adapter\": \"openai-chat\",\n    \"baseUrl\": \"http://localhost:11434/v1\",\n    \"apiKey\": \"\",\n    \"defaultModel\": \"llama3.1\"\n  }\n}\n```\n\nWebSocket 전송은 기본적으로 꺼져 있습니다. Codex가 HTTP/SSE 대신 Responses WebSocket 경로를 사용하게 하려면 `\"websockets\": true`를 설정하세요.\n\n### 원격 접근\n\n기본적으로 opencodex는 `127.0.0.1`(루프백)에 바인딩되며 별도 인증이 필요 없습니다.\n`\"hostname\": \"0.0.0.0\"`으로 LAN에 노출할 경우, opencodex는 관리 API(`/api/*`)와 데이터 플레인(`/v1/responses`) 모두에 bearer 토큰을 요구합니다:\n\n```bash\nexport OPENCODEX_API_AUTH_TOKEN=\"your-secret-token\"\nocx start\n```\n\n비루프백 바인딩 시 이 환경 변수가 없으면 프록시 시작이 거부됩니다. LAN 접근용 백그라운드\n서비스를 설치할 때도 같은 셸에서 이 변수를 먼저 설정한 뒤 `ocx service install`을 실행해야 합니다.\n클라이언트(스크립트, 원격 머신)는 모든 요청에 토큰을 포함해야 합니다:\n\n```\nx-opencodex-api-key: your-secret-token\n```\n\n토큰은 타이밍 공격 방지를 위해 상수 시간으로 비교됩니다.\n\n모든 필드에 대한 자세한 내용은 **[설정 레퍼런스](https://lidge-jun.github.io/opencodex/ko/reference/configuration/)** 를 참고하세요.\n\n## 문서\n\n공개 문서(설치, 프로바이더, 라우팅, sidecar, Codex 통합, Codex App 모델 선택기, CLI/설정 레퍼런스)는 [`docs-site/`](./docs-site)의 Astro 사이트로 빌드되어\n**[lidge-jun.github.io/opencodex](https://lidge-jun.github.io/opencodex/ko/)** 에 게시됩니다.\n\n유지보수용 source of truth는 [`structure/`](./structure)에, 과거 조사/진단 노트는 [`docs/`](./docs)에 있습니다.\n\n## 개발\n\n```bash\ngit clone https://github.com/lidge-jun/opencodex.git\ncd opencodex\nbun install\nbun run dev          # dev 모드로 프록시 시작\nbun x tsc --noEmit   # 타입 체크\n```\n\n`bun run dev`는 프록시 API(`/healthz`, `/v1/responses`, `/api/*`)만 시작합니다. 패키징된\n대시보드 `/`를 함께 서빙하지 않습니다. 대시보드는 설치된 `ocx gui`를 쓰거나, 프론트엔드를\n수정할 때는 별도로 실행하세요:\n\n```bash\ncd gui\nbun install\nbun dev\n```\n\n**[기여하기](https://lidge-jun.github.io/opencodex/ko/contributing/)** 를 참고하세요.\n\n## 면책 조항\n\nopencodex는 독립적인 커뮤니티 프로젝트이며, **OpenAI, Anthropic 등 어떤 제공업체와도 제휴하거나 보증을 받지 않습니다.**\n\n일부 제공업체 — 특히 Anthropic (Claude) — 는 서드파티 프록시를 통한 API 트래픽 라우팅 시 계정을 정지하거나 제한할 수 있습니다. **사용에 따른 책임은 본인에게 있습니다 (UAYOR).** 제공업체를 연결하기 전에 해당 서비스 약관에서 프록시 기반 접근이 허용되는지 확인하세요. opencodex 유지보수자는 업스트림 제공업체의 계정 조치에 대해 책임을 지지 않습니다.\n\n## 라이선스\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flidge-jun%2Fopencodex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flidge-jun%2Fopencodex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flidge-jun%2Fopencodex/lists"}