Skip to content
Get packs

Guide · Open source

How to use opencodex: install, start and connect your tools

Updated · written with AI from the project's own documentation and checked against our catalogue data

opencodex is an open-source local gateway that sits between AI coding tools such as Codex and Claude Code and the model providers behind them. This guide is for developers who want to point those tools at models like Claude, Gemini, Grok, DeepSeek or Ollama. By the end you will know how to install the CLI, start the proxy and dashboard, and connect your tool.

opencodexlidge-jun/opencodex · ★ 18.2k · MIT

Quick start

  1. 1Install the CLI. Run npm install -g @bitkyc08/opencodex with Node.js 18 or newer installed.
  2. 2Start the proxy. Run ocx start to launch the proxy and dashboard on localhost:10100.
  3. 3Open the dashboard. Go to http://localhost:10100 and add your providers and models.
  4. 4Connect your tool. Enable Codex on the Connect page, run ocx claude for Claude Code, or set a custom base URL for other tools.
  5. 5Run your session. Start the tool as usual and choose a routed model from its model list.

What opencodex does

opencodex runs on your computer as a local gateway. It accepts requests in the Responses, Chat Completions and Anthropic Messages formats and translates each one into what your chosen provider expects.

Streaming, tool calls, reasoning and images are carried through only where the client, model and provider support them, so results can vary.

Install opencodex on your computer

The CLI is installed from npm. The project requires Node.js 18 or newer; the README notes that the Bun runtime is bundled automatically.

  • Check that Node.js 18+ is installed.
  • Install the CLI globally with the command below.
npm install -g @bitkyc08/opencodex

Start the proxy and open the dashboard

Start the proxy with the command below. It runs the proxy and web dashboard on localhost port 10100. Open http://localhost:10100 in your browser to add providers, pick models and manage accounts.

Use ocx service to run it in the background, and ocx gui to reopen the dashboard later.

  • Dashboard: http://localhost:10100
  • Add providers from the built-in list or any OpenAI-compatible endpoint.
ocx start

Connect Codex, Claude Code or another tool

Each tool connects differently. For Claude Code, the README says that with the claude CLI installed you run ocx claude, which starts the proxy if needed and launches Claude Code through it. For Codex, turn on the Codex switch on the dashboard's Connect page, then run codex as usual.

For any other tool, set a custom OpenAI-compatible base URL of http://localhost:10100/v1, or an Anthropic base URL of http://localhost:10100. The client support page lists the path and protocol for each tool.

  • Codex: enable the switch on the Connect page, then run codex.
  • Claude Code: run ocx claude.
  • Claude Desktop: run ocx claude desktop, then fully quit and reopen the app.
  • Other tools: use the base URLs above.

Use the optional desktop app

The README describes a desktop app (beta) that runs the same proxy and dashboard in a native window with a tray. It is available as a macOS .dmg, a Windows .msi and Linux .AppImage or .deb files on the latest release page. Each release file has a matching .sha256 file for checking.

On Windows, the README notes that until a release is signed, SmartScreen may ask once; choose More info, then Run anyway.

Use a ChatGPT account pool

The README says opencodex can manage a ChatGPT account pool for Codex auth. You add accounts, refresh their quotas in the dashboard, and new sessions auto-route to the lowest-usage healthy account. Existing threads stay pinned to the account that started them.

What people use it for

  • Running Codex with a non-OpenAI model from the provider list.
  • Running Claude Code with a model routed through the proxy.
  • Using local models served by Ollama inside a coding tool.
  • Managing several provider keys and models from one dashboard.
  • Routing different sessions to different accounts or models.

Frequently asked questions

Is opencodex free to use?

opencodex is released under the MIT licence, as stated in the project's README. Any costs depend on the model providers you connect, which you pay for directly.

What do I need to install opencodex?

The README lists Node.js 18 or newer as the prerequisite. The Bun runtime is bundled automatically, and the CLI installs with npm install -g @bitkyc08/opencodex.

Which models can opencodex connect to?

The README names Claude, Gemini, Grok, GLM, DeepSeek, Kimi, Qwen and Ollama, and says the dashboard has 40+ built-in providers or accepts any OpenAI-compatible endpoint.

Why does a feature not work through opencodex?

The README says streaming, tool calls, reasoning and images work only where the client, model and provider support them. Check the client support page for what each tool supports.

How do I run opencodex in the background?

Use the ocx service command, as described in the README quick start.

How does opencodex compare with LiteLLM, Claude Code Router or OpenRouter?

These are comparable projects named in the analysis. opencodex runs locally as a gateway for Codex and Claude Code, while OpenRouter is a hosted service. Choose based on whether you want a local tool, a hosted router or a proxy library.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

opencodex suits developers who already use Codex or Claude Code and want to try other providers or manage several keys from one local dashboard. If you use only one provider, or are not comfortable installing Node packages and editing tool configs, a simpler setup will likely serve you better.

Install options & downloads