Package Exports

@bitkyc08/opencodex
@bitkyc08/opencodex/src/index.ts

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@bitkyc08/opencodex) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

opencodex (`ocx`)

Universal provider proxy for OpenAI Codex — use any LLM with Codex CLI, App, and SDK.

English · 한국어 · 简体中文

📖 Full documentation →

opencodex dashboard — a dark provider control panel showing live proxy status, routed providers, and available models

Codex only speaks the Responses API (/v1/responses). opencodex sits between Codex and your LLM provider, translating the protocol on the fly — streaming, tool calls, reasoning, and images included — in both directions.

Codex CLI / App / SDK ──/v1/responses──▶ opencodex ──▶ Any provider
                                              │
              Anthropic · Google · xAI · Kimi · Ollama Cloud · Groq
              OpenRouter · Azure · DeepSeek · GLM · …and OpenAI itself

Supported platforms

OS	Status	Service manager
macOS (arm64 / x64)	Fully supported	launchd
Linux (x64 / arm64)	Fully supported	systemd (user unit)
Windows (x64)	Fully supported	Task Scheduler

Requires Bun 1.1+. All three platforms work natively (no WSL needed on Windows).

Quick start

# Install
npm install -g @bitkyc08/opencodex      # or: bun install -g @bitkyc08/opencodex

# Interactive setup (writes config + injects into Codex)
ocx init

# Start the proxy
ocx start

# Use Codex normally — it now routes through opencodex
codex "Write a hello world in Rust"

Don't have bun? — install it first (opencodex runs on bun)

# macOS / Linux / WSL
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

Then re-run npm install -g @bitkyc08/opencodex. (The ocx binary is bun-native, so bun must be on your PATH.)

Target a specific routed model with the provider/model form:

codex -m "anthropic/claude-opus-4-8" "Explain this stack trace"
codex -m "ollama-cloud/glm-5.2"      "Write a SQL migration"

Highlights

Five adapters cover Anthropic Messages, Google Gemini, Azure, the OpenAI Responses passthrough, and every OpenAI-compatible Chat Completions endpoint.
OAuth, API key, or ChatGPT forward. Log in with your xAI / Anthropic / Kimi account (tokens auto-refresh), forward your codex login, or paste a key (${ENV_VARS} supported). An 18-provider API-key catalog (incl. Ollama Cloud) is built in.
Drops into Codex. Injects a [model_providers.opencodex] table into $CODEX_HOME/config.toml (default ~/.codex/config.toml) and merges routed models into Codex's catalog and subagent picker — fully reversible.
Sidecars. Give non-OpenAI models real web search and image understanding via a gpt-5.4-mini over your ChatGPT login.
Web dashboard for providers, OAuth login, model selection, and request logs.

Providers & adapters

Provider	Adapter	Auth
OpenAI (ChatGPT login)	`openai-responses`	forward (no key)
OpenAI (API key)	`openai-responses`	key
Anthropic Claude	`anthropic`	oauth / key
xAI Grok	`openai-chat`	oauth / key
Kimi (Moonshot)	`openai-chat`	oauth / key
Google Gemini	`google`	key
Azure OpenAI	`azure-openai`	key
Ollama Cloud + 17-provider catalog	`openai-chat`	key
Ollama / vLLM / LM Studio (local)	`openai-chat`	key (usually blank)
Any OpenAI-compatible endpoint	`openai-chat`	key

CLI

ocx init                       # interactive setup
ocx start [--port 10100]       # start the proxy
ocx stop                       # stop + restore native Codex
ocx restore                    # restore without stopping (alias: ocx eject)
ocx sync                       # refresh models + re-inject into Codex
ocx status                     # is the proxy running?
ocx login <xai|anthropic|kimi> # OAuth login
ocx logout <provider>          # remove a stored login
ocx gui                        # open the web dashboard
ocx service <install|start|stop|status|uninstall>   # background service (launchd/systemd/schtasks)
ocx update                     # update opencodex to the latest published version

Configuration

Config lives at ~/.opencodex/config.json. Minimal example:

{
  "port": 10100,
  "defaultProvider": "anthropic",
  "providers": {
    "anthropic": {
      "adapter": "anthropic",
      "baseUrl": "https://api.anthropic.com",
      "authMode": "oauth",
      "defaultModel": "claude-sonnet-4-6"
    },
    "ollama-cloud": {
      "adapter": "openai-chat",
      "baseUrl": "https://ollama.com/v1",
      "apiKey": "${OLLAMA_API_KEY}",
      "defaultModel": "glm-5.2"
    }
  }
}

See the Configuration reference for every field.

Documentation

The full developer documentation — architecture, every adapter, the request lifecycle, the sidecars, Codex integration, and the CLI/config reference — is an Astro site under docs-site/ and published to lidge-jun.github.io/opencodex. Deep implementation notes live under docs/, including the Codex App/model catalog path that makes routed opencodex models appear in the Codex App picker.

Development

git clone https://github.com/lidge-jun/opencodex.git
cd opencodex
bun install
bun run dev          # start the proxy in dev mode
bun x tsc --noEmit   # typecheck

See Contributing.

License

MIT

@bitkyc08/opencodex