1. Project Overview
OpenCodex is a lightweight local proxy that lets developers route any large language model โ Claude, Gemini, Grok, GLM, DeepSeek, Kimi, Qwen, Ollama, and more โ through coding assistants like Codex, Claude Code, Claude Desktop, and Grok Build, which are otherwise locked to a single provider.
2. Background & Positioning
Proprietary coding assistants are typically hard-wired to one model provider, forcing developers to pick a single vendor for their entire workflow even when a different model might be better suited to a specific task. OpenCodex was built to remove that lock-in: it acts as a universal adapter that translates API requests between provider formats while preserving feature parity for streaming responses, tool calls, reasoning tokens, and image inputs.
Unlike simple API key switchers or single-provider wrappers, OpenCodex focuses on protocol-level translation (converting to and from the Responses API format), multi-account pooling with quota awareness, and operational tooling (a web dashboard, background service management, health checks) โ making it closer to a small self-hosted gateway than a one-off script.
3. Feature Categories
๐ Model Routing โ 40+ providers, unlimited models
Route any configured provider and model using simple provider/model syntax. Representative examples: anthropic/claude-opus-5, OpenAI, Google, xAI, and custom OpenAI-compatible endpoints. Purpose: let one coding assistant call any backend model without code changes.
๐ฅ Account Management โ pooling across ChatGPT/Codex accounts
Pools multiple ChatGPT/Codex accounts, tracks quota usage, and keeps thread affinity so a conversation doesn't switch accounts mid-stream. Includes lowest-usage, round-robin, and fill-first auto-routing policies. Purpose: maximize throughput and avoid rate-limit interruptions across accounts.
๐ก๏ธ Reliability Features โ failover and redundancy
Weighted round-robin "combos" and automatic failover across models, plus sub-agent support that inherits the same routing rules. Purpose: keep coding sessions running even if one provider or account becomes unavailable.
๐ Authentication & Extensions โ OAuth and sidecar capabilities
Native OAuth integration for xAI, Anthropic, and Kimi, plus web search and vision support for non-OpenAI models via ChatGPT sidecars. Purpose: bring OpenAI-exclusive features (like vision or web browsing) to other providers.
โ๏ธ Operations โ dashboard and service management
Web dashboard at localhost:10100, systemd/launchd/Task Scheduler service integration, and health/readiness endpoints. Purpose: run OpenCodex as a persistent, monitorable local service rather than a one-off CLI call.
4. Key Highlights
- Provider-agnostic routing โ swap the underlying model with a
provider/modelstring, no assistant-side reconfiguration needed. - Feature-parity translation โ streaming, tool calls, reasoning tokens, and images are preserved across provider format conversions, not just plain text.
- Quota-aware account pooling โ automatically spreads load across multiple ChatGPT/Codex accounts using configurable routing policies.
- Memory-bounded state management โ byte-accounted stores with eviction policies, 60-second expiry sweeps, and generation-based reconciliation to avoid stale data.
- Cross-platform native services โ installs as a proper background service on macOS, Linux, and Windows, not just a foreground process.
- Built-in web dashboard โ configure providers, accounts, and combos through a local UI instead of hand-editing config files.
5. Use Cases by Role
General Developers โ Use whichever model fits the task (e.g., a cheaper model for boilerplate, a stronger model for hard bugs) inside the same coding assistant, without switching tools.
DevOps/SRE โ Run OpenCodex as a managed background service with health/readiness endpoints for monitoring, and use failover combos to keep coding assistants available during provider outages.
Project Managers โ Pool team ChatGPT/Codex accounts with quota tracking to control usage and cost across a team without manual coordination.
6. Getting Started
Find what you need
Browse the documentation site for provider setup guides and configuration reference:
https://opencodex.me/
Install / Integrate
npm install -g @bitkyc08/opencodex
ocx start # Launches proxy + dashboard
Requires Node 18+ (Bun runtime bundles automatically). Then route a request through a coding assistant:
codex -m "anthropic/claude-opus-5" "Your prompt here"
Contribute
Read CONTRIBUTING.md in the repository, then open a pull request:
https://github.com/lidge-jun/opencodex/blob/main/CONTRIBUTING.md
7. Project Structure
opencodex/
โโโ bin/ # Binary executables
โโโ dist/bin/ # Distributed binaries
โโโ docs/ # Documentation files
โโโ docs-site/ # Public documentation site source
โโโ gui/ # Web dashboard interface
โโโ readme/ # Localized README files
โโโ src/ # Source code
โโโ structure/ # Maintainer notes and architecture
โโโ tests/ # Test suite
src/ holds the core proxy and translation logic; gui/ implements the local web dashboard; docs-site/ powers the public documentation at opencodex.me.
8. Related Ecosystem
OpenCodex sits between coding assistants (Codex, Claude Code, Claude Desktop, Grok Build) and LLM providers (OpenAI, Anthropic, Google, xAI, and open-source/self-hosted options like Ollama, DeepSeek, Qwen, GLM, and Kimi). It is complementary to tools like OpenRouter in spirit โ both aim to abstract provider differences โ but OpenCodex specifically targets local integration with coding-assistant CLIs and desktop apps rather than being a hosted API gateway.
9. License
โ
Use, copy, modify, merge, publish, distribute, and sublicense the software (MIT License)
โ
Use it for commercial and private projects
โ Hold the authors liable for damages arising from use of the software
โน๏ธ OpenCodex is an independent project and is not affiliated with OpenAI, Anthropic, or other model providers; routing API traffic through third-party proxies may violate some providers' Terms of Service, so review each provider's policy before use
10. FAQ
Q: Which coding assistants does OpenCodex work with?
A: Codex, Claude Code, Claude Desktop, and Grok Build, via the local proxy started with ocx start.
Q: Can I use models that aren't from OpenAI?
A: Yes โ OpenCodex supports 40+ providers including Anthropic, Google, xAI, and open-source models like DeepSeek, Qwen, GLM, Kimi, and Ollama, selected with provider/model syntax (e.g. anthropic/claude-opus-5).
Q: Is it safe to route my provider account through OpenCodex?
A: Functionally yes, but some providers may restrict accounts that route traffic through third-party proxies โ review each provider's Terms of Service before connecting an account.
Q: How do I manage multiple ChatGPT/Codex accounts?
A: Use ocx account <...> to pool accounts; OpenCodex tracks quota per account and can auto-route using lowest-usage, round-robin, or fill-first policies.
Q: What platforms are supported?
A: macOS (arm64/x64), Linux (x64/arm64), and Windows (x64), each with native background service integration (launchd, systemd, Task Scheduler).
11. Quick Links
- Repository: https://github.com/lidge-jun/opencodex
- Official Site / Docs: https://opencodex.me/
- Contributing Guide: https://github.com/lidge-jun/opencodex/blob/main/CONTRIBUTING.md
- npm Package: https://www.npmjs.com/package/@bitkyc08/opencodex
12. Summary
OpenCodex removes the single-provider lock-in of popular coding assistants by acting as a local, protocol-translating proxy that supports 40+ LLM providers with full feature parity. It's most valuable for developers and teams who want the flexibility to mix models across tasks, pool multiple accounts efficiently, and keep their coding workflow resilient to provider-specific outages or quota limits.