OpenCodex: use multiple models inside Codex and Claude Code

a local proxy that routes your existing codex or claude code setup to gemini, groq, kimi, openrouter, or a model on your own machine — without migrating anything. the full install, a one-provider first test, and the security checklist.

Keep the coding setup you already have — repo, skills, MCPs, muscle memory — and swap the model underneath it. OpenCodex is a local proxy that sits between Codex or Claude Code and whichever provider you point it at.

Last checked: July 21, 2026. OpenCodex is a community project, not an official OpenAI or Anthropic product. Provider support, free tiers, and model names change — always use the dashboard's discovered model list instead of copying an old model ID from a post like this one.

What this actually changes

OpenCodex runs a local proxy between your coding agent and the model providers you configure. Everything you've built up — your repository, instructions, skills, MCPs, and the interface you work in — stays exactly where it is. Only the provider and model behind it change.

That's the whole pitch. If you already like Codex or Claude Code and want to route requests to Anthropic, Google Gemini, xAI, Kimi, OpenRouter, Groq, DeepSeek, a local Ollama or LM Studio model, or any other OpenAI-compatible endpoint, this gets you there without migrating your workspace.

One thing it does not do: make paid models free. Every route still needs a valid API key, an OAuth login, a subscription, or a model running on your own hardware. OpenCodex moves requests around; it doesn't pay for them.

Before you start

Node.js 18 or newer. Check with node --version.
Codex CLI/app and/or Claude Code already installed and working normally.
One provider to test. Just one. Add the rest after the first request succeeds.
A public or throwaway repo for the first run. Don't learn a new proxy on sensitive client code.

OpenCodex bundles Bun automatically — you don't need to install it separately.

Which provider should you try first?

Local Ollama or LM Studio — best for private experiments and open-weight models. "Free" here means no per-token API bill; your machine supplies the compute. Hardware, speed, and model quality still decide whether it's actually usable.
OpenRouter's free router — the fastest cloud test. A small, rate-limited free allowance through the openrouter/free route. Good for proving the plumbing, not for production, and the model it selects can vary.
Google Gemini API — some models have a limited free tier. Quotas vary by model, and Google currently treats free-tier and paid-tier data use differently. Read the pricing page before a long run.
Groq — fast inference on selected open models, with a free plan and published per-model limits on requests, tokens, and daily usage.
Kimi (OAuth or API key) — uses whatever access your Kimi account already has. OAuth access is not the same thing as unlimited free use.

For the least confusing first run: one OpenRouter free route, or one local model. Don't connect five providers before you know the proxy works at all.

Step 1 — Install OpenCodex

npm install -g @bitkyc08/opencodex

Prefer a user-owned Node installation through a version manager like nvm or fnm. Avoid sudo npm install -g unless your existing setup genuinely requires it.

Then run the interactive setup:

ocx init

This writes the OpenCodex configuration, connects it to Codex, and offers an on-demand startup shim. Accept the shim if you want OpenCodex to start automatically whenever you launch codex — or add it later with:

ocx codex-shim install

Start the proxy and confirm it's alive:

ocx start
ocx status

Then open the local dashboard:

ocx gui

It should open at http://localhost:10100 unless that port was already taken.

Step 2 — Connect one provider

In the dashboard:

Open Providers and choose Add Provider
Pick a built-in provider, or add a custom OpenAI-compatible endpoint
Authenticate with an API key or the supported OAuth flow
Let OpenCodex discover the provider's current models
Enable only the one model you want for the first test

For supported OAuth providers you can also start login from the terminal:

ocx login kimi
ocx login anthropic
ocx login xai

Run only the command for the provider you actually intend to connect.

Option A — OpenRouter's free router

Create an OpenRouter API key, add OpenRouter in the dashboard, store the key, and select the discovered free router — currently exposed as openrouter/free. This proves the route works. Free models have low limits and the router may pick different models over time, so treat it as a test lane, not a daily driver.

Option B — a local Ollama or LM Studio model

Install and start Ollama or LM Studio separately, load one model in that app, then add the matching local provider in OpenCodex pointed at its OpenAI-compatible endpoint. Common defaults: http://localhost:11434/v1 for Ollama, or the URL LM Studio shows for its local server. Leave the API key blank if the local server doesn't require one.

"Local" means no provider token bill. It does not guarantee the model is fast enough or capable enough for agentic coding on your hardware — that's a separate test.

Option C — Gemini or Groq

Create an API key in the provider's own console, add Google Gemini or Groq in the dashboard, paste the key, and use the model list OpenCodex discovers. Check that model's current free-tier and rate-limit page before running anything long. Not every model visible in a provider catalog is free.

Step 3 — Use the routed model in Codex

Refresh the discovered models and the Codex integration:

ocx sync

Open Codex normally — routed models should appear in the model picker (/model opens it). In the CLI you can also target one directly with provider/model syntax:

codex -m "provider/model" "Inspect this public test project and summarize its structure. Do not modify files."

Replace provider/model with the exact route shown in your OpenCodex dashboard. Provider model IDs change constantly — copy the discovered route, don't guess it. Routed models can also expose reasoning controls when the provider configuration supports them.

Step 4 — Use the routed model in Claude Code

Launch Claude Code through OpenCodex:

ocx claude

Then open the model picker inside Claude Code with /model. Routed aliases appear in the native picker with a pattern like:

claude-ocx-<provider>--<model>

This picker integration needs a current Claude Code version — OpenCodex specifies 2.1.129 or newer. Claude-specific slots and model maps live on the dashboard's Claude page.

Prove it before you trust it

Run this first prompt against your public test project:

Read this repository without changing any files. Tell me:
1. the main language,
2. the test command you found,
3. one small improvement you would make.

Then verify all four:

The routed model is visible in the Codex or Claude Code picker
The answer arrives successfully
The OpenCodex dashboard request log names the provider you selected
No secret, private path, or account token appears in the log

The request log is the proof that matters. A model name in a picker only shows configuration; the log shows the request actually reached the route you chose.

A practical routing starter

Don't treat model selection as a permanent leaderboard. Start with roles, then keep your own evidence:

Fast scan — a low-cost or local model for repository mapping and simple transformations
Visual/frontend iteration — whichever model gives you the best results on your actual components and screenshots
Long coding run — a model you've verified can sustain tool use, recover from errors, and finish the test suite
Second opinion — a different provider reviewing the first model's plan or diff

Change one variable at a time. Give two models the same bounded task and compare correctness, tool behavior, time, and cost. Your own repo is the only benchmark that counts.

Can one model call another inside the same session?

Yes — through a subagent workflow. The main model stays on the parent thread, delegates a bounded task to a child agent configured with a different model, and receives the result back. OpenCodex can expose up to five routed or native models in Codex's subagent picker.

Treat cross-provider delegation as experimental for now. OpenCodex documents a limitation where a native parent on the v2 multi-agent surface can lose the task body when spawning a routed child; its current workaround is using the v1 surface for reliable cross-provider delegation. Test with a harmless task before wiring it into anything important — and if you plan to claim a cross-model workflow publicly, capture the parent model, child model, delegated prompt, and returned result as evidence.

Security checklist

Keep the default loopback-only bind. 127.0.0.1 means the proxy is reachable only from your machine.
Don't expose the proxy to your local network or the public internet for a first setup. If you intentionally bind to 0.0.0.0, configure OPENCODEX_API_AUTH_TOKEN and understand the network risk first.
Never paste provider keys into a prompt, source file, screenshot, or screen recording. Use environment-variable references where practical.
Review each provider's data policy and terms — a free tier may handle your data differently from a paid tier.
Remember OpenCodex is an independent proxy. Review its repository and release history before running it against sensitive code.
Skip account-pooling and experimental adapters until the basic single-provider route is stable and you've read the provider's terms.

Troubleshooting

`ocx` is not found

Your global npm binary directory probably isn't on PATH. Check where it lives:

npm prefix -g
npm bin -g

If npm bin -g is unavailable in your npm version, the executable is usually under the global prefix's bin directory on macOS and Linux.

"Bundled Bun runtime is missing"

The install likely blocked Bun's lifecycle script or optional dependency. Reinstall with scripts allowed for that package:

npm install -g --allow-scripts=bun @bitkyc08/opencodex

Don't use --ignore-scripts or --omit=optional for this install.

The provider is connected but the model is missing

ocx status
ocx sync

Then check the provider's authentication and discovered-model list in the dashboard, and copy the route shown there. Restart the Codex or Claude Code client if its picker still shows stale entries.

Codex works, but Claude Code doesn't show routed models

Launch it with ocx claude, confirm your Claude Code version meets the current minimum, and check the dashboard's Claude configuration page.

A routed request fails

Open the dashboard request log first and see which layer failed: authentication, provider quota, an unsupported model, or the local proxy itself. Diagnose before you touch credentials — and if you're screen-recording the session, don't rotate or re-paste keys on camera.

I want native Codex back

ocx stop

stops the proxy and restores the original Codex configuration. You can also restore without stopping via ocx restore (ocx eject is an alias for the same command).

Clean uninstall

Order matters — clean the local integration before removing the package:

ocx uninstall
npm uninstall -g @bitkyc08/opencodex

The first command removes the OpenCodex service, shim, and configuration, and restores native Codex. The second removes the global npm package.

Common questions

How is this different from Cursor?

Cursor already offers multiple models from a curated catalog, plus a limited set of documented bring-your-own-key providers. If Cursor is your workspace and its models cover you, use Cursor. OpenCodex is for the opposite case: your repo, instructions, skills, MCPs, and muscle memory already live in Codex or Claude Code, and you want to change the provider layer without migrating the workspace. It's also broader for Kimi OAuth, OpenRouter, Groq, arbitrary OpenAI-compatible endpoints, and local Ollama or LM Studio routes.

Does OpenCodex make Claude, Gemini, Grok, or Kimi free?

No. It routes requests. Cost and limits come from the provider or the local hardware you choose.

Will my existing Codex threads disappear?

OpenCodex says its local injection keeps native provider tags and restores the original Codex configuration on stop. Still — test with a non-critical project first and keep normal backups of anything important.

Sources

The goal isn't to collect models. It's to keep the setup you've already tuned and pick a better tool for the task in front of you.