Quickstart

Fresh local installs use the built-in openai provider, which forwards your existing ChatGPT/Codex login. You do not need a provider API key, and you do not have to run ocx init, before the first start.

1. Start the proxy

ocx start            # defaults to port 10100
ocx start --port 8080

Leave that terminal running. On start, opencodex:

• loads the keyless ChatGPT-forward provider when no config exists,
• writes its PID to ~/.opencodex/ocx.pid (and refuses to start twice),
• discovers live models where the provider supports it and syncs native and routed entries into Codex’s model catalog,
• injects the local proxy into Codex’s config, reversibly, and
• listens on http://localhost:<port>/v1.

If the requested port is busy, ocx start selects a free port, records it in runtime-port.json, and updates Codex to use the live listener.

Check it or open the dashboard from another terminal:

ocx status
ocx gui       # opens the dashboard on the live port

2. Use your ChatGPT/Codex login

If Codex is already signed in to ChatGPT, there is nothing else to configure. If it is not, sign in once through Codex’s normal flow:

codex login

Then launch Codex already wired to the running proxy:

ocx codex

Bare native model ids such as gpt-5.6-sol use the built-in ChatGPT-forward route. The account still needs access to the requested model; a catalog entry does not grant upstream access.

Which credential is it asking about?

Three different credentials can appear in opencodex. They are not interchangeable:

Credential	When you need it	What it is
ChatGPT/Codex login	Default local openai route	The account session created by codex login or the Codex app. It is not an API key.
Upstream provider credential	Only after you deliberately add another provider	That provider’s API key or OAuth/account login. Local providers usually need neither.
OpenCodex admission key	Data-plane clients connecting to a non-loopback/LAN bind	A key generated by ocx host enable --new-key --yes to protect /v1/*. It is not a provider billing credential and is not needed on localhost.

If a client reports opencodex API key required, it reached a non-loopback listener without the OpenCodex admission key. Point it at the local loopback listener, or configure the generated admission key for that client. Do not buy or paste a provider API key to fix that message. See Web Dashboard: remote access.

3. Add another provider (optional)

The dashboard is the simplest route: run ocx gui, open Add provider, and choose account login, API key, local server, or a custom endpoint. To reconfigure a fresh install from the terminal, use:

ocx init

At Select default provider, press Enter to accept provider 1, OpenAI — ChatGPT login (no key). ocx init then asks only for what the selected provider actually needs:

1. ChatGPT forward — no API key; it uses the Codex login.
2. Account login (OAuth) — save the provider, then run the displayed ocx login <provider>.
3. API-key provider — paste that upstream provider’s key or reference an environment variable such as ${ANTHROPIC_API_KEY}.
4. Local provider — usually leave the key blank.
5. Proxy and Codex integration — choose the port, injection, and optional autostart shim.

The result is saved to $OPENCODEX_HOME/config.json (default ~/.opencodex/config.json).

GPT-5.6 rollout entries

Stable v2.7.1 seeds GPT-5.6 Sol/Terra/Luna for ChatGPT passthrough, OpenAI API-key, OpenRouter, and the experimental Cursor adapter. They work only when that upstream account has access. The OpenAI API-key and OpenRouter presets advertise a 372,000-token usable context window; Cursor keeps its own adapter metadata.

To target a specific routed model, use the provider/model form Codex’s model picker shows:

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

Choose sub-agent models (optional)

A fresh config features five native models in Codex’s sub-agent picker: gpt-5.5, gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna, and gpt-5.4-mini. Open ocx gui to replace or reorder up to five native or routed models. The dashboard can also set one preferred sub-agent model and reasoning effort; opencodex adds that guidance to v1 collaboration requests.

Account login for optional providers

Some providers support real account login (OAuth, auto-refreshed):

ocx login xai          # or: anthropic, kimi, kiro, google-antigravity, cursor
ocx logout xai

OpenAI itself needs no provider key — the default provider forwards your existing codex login credentials (see Providers).

Stopping & restoring

ocx stop          # stop the proxy and restore native Codex
ocx restore       # restore native Codex without stopping (alias: ocx eject)
ocx restore back  # route Codex through the still-running proxy again

Next

• How It Works — what happens to each request.
• Providers — every way to authenticate.
• Configuration — the full config.json reference.