OpenCodex, start to finish
From download to a model that actually works. Follow the steps, try the illustrations and verify the result in your own setup.
In this guide
Estimated setup time, excluding registration with a provider.
Same Codex. More models.
Try the model picker below. In your own setup, models appear after you connect a provider and sync the catalog.
Build a simple task list with search.
Selected in the illustration: DeepSeek
Technically checked on 4 October 2026 · OpenCodex 2.76.0
Watch the full walkthrough · 9:28
The video is in Norwegian. Menus may have changed since recording; the steps below follow the documented workflow.
1Understand the setup before clicking
Codex is the workspace. OpenCodex routes the request to your chosen model. The provider processes the data and determines access and billing.
Start with one provider you already have access to. You can use another model directly without Astra or subagents. This guide uses macOS as its main example.
You know which provider to test and how usage is paid for.
Do I already have access?
A chat subscription and an API are different products. Check your provider account before choosing a connection method. OpenCodex does not grant free access to paid models.
2Install from the right source
Go to opencodex.me and open the Desktop App guide. Download the macOS release using the project link. Open the DMG, drag the app into Applications and open it there.
The desktop app includes the dashboard and local runtime. Windows and Linux have their own downloads and instructions on the same page. Follow the guide for your operating system.
OpenCodex opens its dashboard. On Mac, a menu bar icon also appears.
Already using the terminal version?
You do not need to reinstall to follow the rest. Use ocx gui to open the dashboard. Do not overwrite a working setup just to match the illustration.
3Check that the proxy is running
Open Dashboard and look for Online. This confirms the local proxy is available; it does not yet prove a provider model works.
The desktop app manages its runtime. “Start opencodex with Codex” permits an already installed launcher shim; the switch alone does not install automatic startup.
Dashboard shows Online and you can open Providers.
Offline or a startup error?
Use the app’s startup controls and read the error. Avoid starting multiple proxies or randomly changing ports. In a terminal setup, ocx status shows which runtime is running.
4Connect one provider
Open Providers → Add Provider and choose the provider you want to use. Select its supported connection method: an API key or account login. Complete this locally in OpenCodex.
A Meta API key and a Muse subscription login are not the same access. The same principle applies to other providers. Never paste keys on this website or in a public chat.
Add Provider
Enter your key only in OpenCodex, never on this website.
The provider is added and enabled. The model test in step 7 confirms whether the entire connection works.
401, 403 or missing access?
Check the key or login, model permissions and provider balance. OpenCode Zen supports keyed access; do not assume keyless “Free” models work in third-party clients.
5Connect OpenCodex to Codex
Open Integrations and find Codex. Enable the Codex integration if it is not already active. OpenCodex updates the Codex configuration to route requests through the local proxy.
Check both the switch and the card status. The switch reflects the desired setting; the status reflects observed state. They may briefly differ while the change is applied.
Codex requests go through the proxy
This card connects the workspace to the proxy.
The Codex integration is active. Next, make your chosen models visible.
Switch enabled but status lagging?
Let the change complete and read any error. Use the documented integration instead of adding multiple manual provider blocks to the Codex configuration.
6Make the models visible
Open Models and choose which available models to show. Use Sync models / Sync now in the dashboard. Fully quit and reopen Codex to load the updated catalog.
Open the model picker in a new task and select the model directly. A model name’s prefix identifies the provider route; similar names can have different access and billing.
Sync in OpenCodex, then reopen Codex.
The model appears in the Codex picker and the selected model is shown beside the composer.
Missing or greyed-out model?
Check that the provider is enabled and the model is available and visible, then sync again. Quit the entire Codex app before reopening it. A grey row can also reflect client access or quota restrictions.
7Run your first small task
Open the empty test folder in Codex, select your model and copy the task below. Ask for something you can open locally. This checks more than whether the model produces a convincing reply.
Run the result, add two tasks and try search and filtering. Then open Logs & Debug in OpenCodex. Confirm which model and provider handled the request; a green response alone is not enough.
Build a simple task list in this empty folder using plain HTML, CSS and JavaScript, without new dependencies. Include search and filtering. Explain how to open it locally and give me three concrete things to test.The app opens locally and behaves as described. The log shows the expected route.
It replies, but the app does not work?
Copy the specific error without keys or private data and ask the model to fix it. Test again. Log costs may be estimates; check the provider’s actual usage before drawing pricing conclusions.
8Let a main model delegate
OptionalThe basic setup now works. If a task benefits from multiple models, open Subagents and select the models it may use. In this example Astra leads at High, while Muse, DeepSeek and GLM can handle focused tasks.
These selections make delegation available; they do not force it. Ask for a specific division of work and verify that subtasks were actually completed. You can still use each model directly.
The main model assigns focused tasks when it chooses to delegate.
Inspect this test app. If delegation is available, give one subagent a focused task: check search and filtering. Make the final assessment yourself and state which tasks were actually delegated.You can inspect the delegated task and its result, or are told that delegation was not used.
Subagent fails to start?
Use the default v1 for cross-provider delegation and start a new conversation after changing modes. Existing conversations may retain their previous mode. Verify that the subagent model also works directly.
9Find the fault before adding more
Troubleshoot in order: local proxy → provider access → visible model → request → actual result. Use Logs & Debug to separate connection failures from a model that produces incorrect code.
Leave account pools, combos, fallback, web search and image analysis until the basic setup is verified. They have separate settings and may involve additional providers, costs and data routes.
Check these fields in your own request. No real log data is shown here.
You have a specific error and know which part to investigate.
Which error should I start with?
401: check authentication. 403: check provider permissions and plan. 429: check quota and retry timing. Connection refused: check the proxy. Share only redacted errors, never keys or entire private logs.
10Return to regular Codex
Open Integrations and disable the Codex integration. This removes OpenCodex routing for Codex while leaving the proxy available to other clients. Fully quit and reopen Codex.
To stop a desktop-managed proxy too, use Stop proxy or Quit in the menu bar/tray menu. An external ocx stop may trigger the desktop app’s automatic restart. Do not delete configuration files as a troubleshooting shortcut.
Regular Codex setup
Disable the Codex card in your own setup.
A new Codex task uses your regular setup. Check the model selection and that the task opens without a local proxy error.
Using the terminal setup?
ocx restore removes Codex routing without stopping the proxy. Follow the official recovery instructions for your version if normal disconnection fails. Keep your files until the setup is verified.
YOUR FIRST CHECK
The basic setup is ready when …
Check these after completing them in your own setup. This list does not store or send anything.
Sources and updates
OpenCodex changes quickly. Follow the project documentation if your menus differ. It is an independent tool, not an official OpenAI integration.
opencodex.me ↗