OpenCodex is a lightweight local proxy that translates Codex's Responses API requests into each LLM provider's own protocol. It lets Codex CLI, App, SDK, and Claude Code use Anthropic, Google, xAI, Kimi, DeepSeek, GLM, Qwen, Ollama, and more. Streaming, tool calls, reasoning tokens, and image inputs are all converted bidirectionally.
1. Getting Started
Requirements
- Node.js 18 or later
- The Bun runtime is bundled as an npm dependency and runs through the Node launcher, so no separate installation is needed
- Caution: if
npmis configured to block lifecycle scripts during install, you'll get a "bundled Bun runtime is missing" error. In that case, either allow scripts and reinstall, or install Bun directly - A user-owned Node environment (nvm/fnm, etc.) is recommended over
sudo npm install -g
Install and run
# 1. Global install (auto-bundles the Bun runtime)
npm install -g @bitkyc08/opencodex
# 2. Interactive init (writes the config file + injects Codex config + guides you through installing the auto-start shim)
ocx init
# 3. Start the proxy
ocx start
From then on, using Codex normally routes requests through opencodex.
codex "Write a hello world in Rust"
The dashboard is available at http://localhost:10100.
Uninstalling and reverting
ocx stop # stop the proxy, stop the background service, restore Codex's original config
ocx uninstall # clean up leftover config (recommended before removing the npm package)
npm uninstall -g @bitkyc08/opencodex
Supported platforms
| OS | Status | Service manager |
|---|---|---|
| macOS (arm64/x64) | Supported | launchd |
| Linux (x64/arm64) | Supported | systemd |
| Windows (x64) | Supported (no WSL required) | Task Scheduler |
2. Advantages
| # | Item | Description |
|---|---|---|
| 1 | Model freedom | Supports 40+ built-in providers, including Anthropic, Google, xAI, Kimi, Ollama Cloud, Groq, OpenRouter, Azure, DeepSeek, GLM, and OpenAI itself. You can switch models within the same Codex workflow |
| 2 | Adapter-based translation | Absorbs most endpoints through 5 adapters: Anthropic Messages, Google Gemini, Azure, OpenAI Responses passthrough, and OpenAI-compatible Chat Completions |
| 3 | Simplified install/config | No need to build a proxy chain yourself — the interactive ocx init setup handles it. xAI, Anthropic, and Kimi support OAuth login, so you can connect without an API key |
| 4 | No binary modification | Rather than patching the Codex app binary, it injects providers into Codex's config file and model catalog. ocx stop restores the original config |
| 5 | Unified dashboard | Providers, API keys, model aliases, logs, and account management are all handled through a web dashboard |
| 6 | Model routing rules | Specify explicitly with provider/model syntax, or let it auto-match by model name pattern when the prefix is omitted (claude-* → Anthropic, gpt-* → OpenAI) |
| 7 | Codex App integration | Routed models appear in the Codex App's model picker alongside native models, with per-model reasoning effort adjustment |
| 8 | ChatGPT account pool | Register multiple ChatGPT/Codex accounts to refresh 5-hour, weekly, and 30-day quotas, routing new sessions to whichever account has the lowest usage. Existing threads stay pinned to the account that started them |
| 9 | Background service | Registers as a system service to auto-start on boot, designed to leave no leftover config or zombie processes when stopped |
3. Drawbacks and Risks
| # | Item | Description |
|---|---|---|
| 1 | ToS risk | Being technically able to connect an OAuth/subscription account doesn't mean the provider permits routing through a third-party proxy. The project's own documentation warns of possible account restrictions or suspension. The account-pooling feature in particular could be read as a way to circumvent usage limits |
| 2 | Extra layer of complexity | Adding a proxy layer on top of Codex creates more configuration decisions and more points to debug |
| 3 | Delayed feature compatibility | Since it's a custom API translation layer, the latest Codex or Claude Code features may not be reflected immediately |
| 4 | Project maturity | A smaller ecosystem than official tooling, with a very short release cadence (many weekly preview tags). Stability and long-term maintenance need further validation |
| 5 | Always-running dependency | Assumes a persistent Node environment and ocx daemon, using more resources than running Codex alone |
| 6 | Local credential concentration | API keys and OAuth tokens for many providers all end up in the local config (~/.opencodex/config.json). A compromised machine has a wider blast radius as a result |
4. Distinct Projects With Similar Names
Several projects share the name "OpenCodex." It's worth distinguishing them so their features aren't conflated.
| Project | Identity | Relationship to this document's subject |
|---|---|---|
| lidge-jun/opencodex | The subject of this document. A general-purpose provider proxy for Codex/Claude Code | — |
| AITabby/opencodex | A local gateway for Codex Desktop, with a Vision Bridge, a Computer Use engine, and a voice companion (OpenCodexBar) | A different project. The Vision Bridge and voice features belong here, not to the lidge-jun version |
| RyensX/OpenCodex | Codex Desktop middleware specialized for browser remote access | A different project. The remote-access feature belongs here |
| Open Codex (codingmoh) | A fully local CLI assistant. No API key required; supports local models like phi-4-mini | A different project |
5. Competing and Alternative Tools
| Tool | Description | Difference |
|---|---|---|
| OpenCode (SST) | Open-source terminal AI coding agent | A standalone agent, not a proxy. It supports many providers natively, so opencodex offers little practical benefit for OpenCode users |
| Claude Code | Anthropic's terminal coding assistant | Specialized for the Claude ecosystem. opencodex can also act as a proxy on the Claude Code side |
| Cursor | AI-native code editor | Centered on an in-IDE experience |
| GitHub Copilot | IDE-plugin-style coding assistant | Limited provider choice |
| Aider / Cline / Windsurf | Coding agents with different approaches | Different workflows and areas of specialization |
6. Comparison With Codex Alone
| Item | Codex Alone | Codex + OpenCodex |
|---|---|---|
| Available models | OpenAI family only | 40+ providers |
| Setup difficulty | Low | Medium |
| Cost optimization | Limited | Favorable via low-cost model routing |
| Customization | Limited | High |
| Operational risk | Low | Additional proxy failure point, provider ToS risk |
| Best fit | Casual users who want to get started immediately | Power users focused on model experimentation and cost optimization |
7. Overall Assessment
The technical design is reasonable. Choosing config injection over binary patching, and being able to revert with a single ocx stop, is the single most important safety mechanism for tools in this category. Abstracting the adapter layer into 5 types also lowers the cost of adding new providers.
That said, the variable that outweighs technical convenience when deciding whether to adopt this is ToS risk. API-key-based integration and subscription-account (OAuth)-based integration are fundamentally different in nature, and in particular, pooling multiple ChatGPT accounts could be judged by the provider as a way to circumvent usage policy. For a work environment, the safer configuration is to register only API-key-based providers and skip the account-pooling feature entirely.
The rapid pace of weekly preview releases is positive for feature growth, but it's still too early to treat this as a production dependency. Experimental adoption in a personal development environment is the appropriate level of use for now.