All-in-one setup with OpenCodex

For an easier way to connect your coding tools and agents, we recommend OpenCodex. It gives you a local dashboard for API connections, model selection and request logs. You add our API key once, then connect the tools you use.

OpenCodex runs on your computer. It sends model requests to the API you configure; it does not run the AI model locally. It is an independent, open-source project. You can also connect directly without installing it. For an existing agent installation, see the native setup for Hermes or OpenClaw.

Before you start

Have your service API key, a funded balance and your chosen tool installed. The connection card above shows our Base URL. Use a model that supports tool calling for coding agents; a successful text response alone does not establish agent compatibility.

This guide covers text models. You do not need account pooling, Combos, web-search sidecars or image bridges for this setup.

1. Install and open OpenCodex

The simplest option is the OpenCodex desktop app, currently offered as a beta. Download it from the project’s release page:

Install and open the app. It opens the dashboard and starts its bundled local proxy when needed. If it finds an existing proxy, follow the app’s connection prompt rather than starting a second instance. The Windows installer is currently unsigned, so Windows may show a publisher warning; verify that you downloaded the release from the project’s repository.

If OpenCodex is already running, open its dashboard and continue to step 2. Its default browser address is http://localhost:10100; use your configured port if you changed it.

npm install -g @bitkyc08/opencodex
ocx start

2. Add our API connection

1. Open Providers and select Add Provider.
2. Choose Custom provider (the picker also offers “Provider not listed? Add a custom one”).
3. Fill in the settings below.
4. Select Add provider to save.

Choose Custom provider, rather than a vendor-login preset. This connects the key to our service. OpenCodex’s openai-chat adapter sends requests to /v1/chat/completions and translates the client formats it supports, including Responses and Messages.

The name my-api belongs only to your local OpenCodex setup. It does not change your service account or the model IDs accepted by our API.

3. Choose the models you want

The Models page controls which models OpenCodex makes available to your tools. You can enable the full discovered list or keep only the models you plan to use.

1. Open Models and find the my-api connection you added.
2. Review the model IDs discovered with your service key. The list can include GPT, Claude, Gemini, DeepSeek, Qwen and other families, depending on which models your account can access. The service catalog helps you compare them; the authenticated models endpoint gives the exact IDs available to your key.
3. Enable the rows you want to see in your tools. For example, keep one coding model and one lower-cost model for shorter tasks. You do not need to enable every row.
4. Save any pending changes, then refresh the connection or restart your tool if it still shows the old list.

If discovery is off, open the provider’s settings and enable Discover models from provider. If the list stays empty, check the Base URL and key, or add an exact model ID from our API. Do not guess an ID from a display name.

A selected row can appear as my-api/<model-id>. Select or copy the exact entry OpenCodex shows. The local my-api/ prefix tells OpenCodex which connection to use; OpenCodex sends the underlying model ID to our API.

Enabling a model makes it visible; it does not switch every conversation to that model. Choose the active model in your tool’s picker, or set a default where the tool offers one. For coding agents, choose a model with tool-calling support. Existing conversations may keep their previous selection.

4. Connect your tool

Open Connect and choose your tool. Use the matching instructions below. You configure the API connection once; each tool still needs its own connection enabled.

Codex CLI and Codex desktop app

1. Turn on the Codex connection in the Connect overview. Review any configuration changes OpenCodex presents.
2. Allow the model catalog to sync. If OpenCodex reports a sync problem, resolve it before continuing.
3. Fully quit and reopen the Codex desktop app, or start a new Codex CLI session.
4. Open the model picker (/model in the CLI) and select an entry from my-api.
5. Start a new conversation and send a short prompt. Check that OpenCodex records the request under my-api.

Existing conversations can keep their previous model selection. Reopening a window alone may leave the app running; fully quit it before reopening. If Codex asks for its own sign-in, follow its sign-in flow; adding a service API key does not itself sign you into the application.

Claude Code

1. Open Connect → Claude and enable Claude connection.
2. Under General, set Auth Mode to Proxy (no account needed) for this API-key setup and save the settings.
3. Open a terminal and launch Claude Code through OpenCodex:

ocx claude

4. In Claude Code, open /model and choose your routed model. The Available models list in OpenCodex’s Claude page shows the picker aliases.
5. Send a short prompt and check the resolved connection and model in the logs.

This launcher is the straightforward path across supported systems. The separate Auto-connect setting is macOS-only and requires fully quitting and reopening the terminal app. It is optional; you do not need it when using ocx claude.

A terminal tab or editor that starts claude directly does not automatically inherit the launcher’s settings. Use the launcher there too, or follow OpenCodex’s Claude Code guide for direct-launch configuration. Claude Desktop has its own Connect section; it is a separate integration from Claude Code.

OpenCode, OpenClaw, Hermes and other listed clients

1. Open the tool’s card or tab under Connect.
2. Turn on its connection. Review the destination and preview of changes, then confirm the operation if prompted.
3. Open the tool’s model picker and select a model exported by OpenCodex. Start a new session, or restart the tool if it still shows the old list.

OpenCodex writes its connection block into that tool’s local configuration and keeps recovery snapshots. If it reports a conflict with existing settings, review the difference before allowing a replacement.

These are named integrations, not a promise about every extension with a similar name. For example, Cline CLI and the Cline editor extension have different configuration. Further listed clients include gjc, DeepSeek Harness, MiniMax Code and Command Code; follow the Connect panel’s instructions for your installed version. See the project’s integration guide for client-specific details.

Cursor

Regular Cursor cannot reach a proxy on your computer through a localhost Base URL. Its custom-endpoint requests are made from Cursor’s servers. For regular Cursor, use our public Base URL and service key directly where its settings support them, or follow the project’s separate bridge instructions.

If you already use Cursor Private Inference, its local gateway can connect to OpenCodex. Open Connect → Cursor in OpenCodex and copy the gateway values it displays. In that Cursor build, open Settings → Models → Gateway → Configure gateway, paste those values and select Refresh model list.

Use the local gateway key shown by OpenCodex, not your service key. The service key stays in the provider connection you added in step 2. This Cursor build has different capabilities and availability from regular Cursor; see OpenCodex’s Cursor guide before choosing it.

5. Start automatically next time

For the desktop app, enable Start at Login in the OpenCodex menu and check Startup in the dashboard. Keep the app running in the background while using connected tools.

For a terminal installation, use the background service instead of keeping ocx start open:

ocx service install
ocx service status

The project uses launchd on macOS, a user systemd service on Linux and Task Scheduler by default on Windows. Its Startup page shows the installed mechanism and any repair it needs. If the desktop app already owns the proxy, keep its Start at Login setup rather than installing a competing service.

The optional Codex launcher shim starts the proxy on demand for supported CLI launches. It does not cover every Codex desktop launch, so the desktop app or background service is the simpler choice for several tools.

6. Check a request and keep control

Start a fresh conversation in your tool and ask for a short text response. In OpenCodex, open Logs & Debug and check the connection, resolved model, status, duration and token counts where available. That confirms which route the request actually used.

OpenCodex can show estimated costs. Use our service dashboard for your actual balance and billed usage. Local log and debug settings are separate from our service’s logging policy; inspect them before sharing logs or screenshots. Hide keys and private request content.

You can change model selections in OpenCodex and refresh or restart the client as needed. To disconnect a managed tool, turn off its connection under Connect and review the cleanup. Do not delete OpenCodex’s state directory as a substitute for disconnecting it.

If something does not appear

• Dashboard does not open: open the desktop app or check ocx service status. Confirm the port shown by your installation; 10100 is the default, not a required port.
• No models: check the service Base URL, key permissions and model discovery. A model listed in the dashboard still needs to be enabled for export to a client.
• Models are in OpenCodex but not in your tool: check its Connect switch, finish the catalog sync, then fully restart it and open a new conversation.
• Claude Code uses a different connection: launch it with ocx claude, choose the routed model explicitly and inspect the resolved model in Logs & Debug.
• An API request fails: check the key’s limits, available balance and the model’s supported parameters. See our API troubleshooting.
• A model chats but agent actions fail: confirm tool-calling support. A local proxy translates supported protocols; it cannot add a capability the selected model or client does not support.

This guide follows OpenCodex 2.88.0. For the latest UI and platform details, use the OpenCodex documentation. Screens and labels can change between releases.