Codex CLI

The Codex CLI (OpenAI's open-source coding agent) reads its providers from a config file, so it's a first-class connect target — one command and you're done. There's no API key to set up: the proxy admits you with your wallet's on-chain seal, so the provider it writes carries no key at all.

Before you start

Do the shared setup from How-to guides first: the proxy must be running (zs-proxy proxy start) and funded (zs-proxy fund).

Connect it

Write the config: zs-proxy connect codex

zs-proxy connect codex                          # configure Codex to use the proxy
zs-proxy connect codex --model qwen3-coder      # ...and set it as the default model
zs-proxy connect codex --print                  # preview the merged config, write nothing

This merges a zerosignal provider into your existing ~/.codex/config.toml (backing the original up to config.toml.bak) and makes it the active provider. Your other Codex settings are preserved. What it writes:

model = 'qwen3-coder'            # only when you pass --model
model_context_window = 262144    # only alongside a model the proxy advertises
model_provider = 'zerosignal'

[model_providers]
[model_providers.zerosignal]
base_url = 'http://127.0.0.1:9376/v1'
name = 'ZeroSignal'
wire_api = 'responses'

Two things about the shape: keys come out alphabetically sorted with single-quoted strings, because connect re-serializes the whole file rather than splicing text. That also means comments in an existing config.toml are not preserved — use --print to preview, and config.toml.bak to recover.

There's deliberately no env_key line — Codex treats it as optional, and a provider that sets neither env_key nor requires_openai_auth needs no authentication at all, which is exactly right here. You can confirm it with codex doctor: it reports "OpenAI auth is not required for the active model provider".

model_context_window is there because Codex looks the active model up in a built-in model catalog to learn its context window — and that catalog only ever contains OpenAI models. Without this line Codex would run a ZeroSignal model on a guessed context length. connect writes it only when you select a model the proxy actually advertises, and clears it again if you switch to one whose window the proxy doesn't publish. If the proxy can't describe the model at all — no operator serving it answered while connect was running — the existing line is left exactly as it was, neither updated nor removed. Nothing else about Codex's model list is touched, so the built-in models stay selectable.

If Codex's config lives somewhere non-standard, point connect at it with CODEX_HOME=/path/to/dir (the directory holding config.toml) or --config-path.

Run Codex

codex

Send a message; the first reply confirms the whole path — encrypt, pay, route — is working.

info

Codex talks the Responses API (wire_api = 'responses'), which the proxy serves at POST /v1/responses. That's already handled — you don't need to configure anything for it. Note this is the only wire API Codex still supports; if you're following an older guide that sets wire_api = 'chat', that value was removed from Codex in early 2026 and will not connect.

Troubleshooting

Symptom	Fix
Auth error / "missing API key" on send	An older config still has an env_key line under [model_providers.zerosignal]. Re-run zs-proxy connect codex — it removes the line — or delete it from ~/.codex/config.toml by hand.
connect says Codex wasn't detected	Name it explicitly — zs-proxy connect codex configures the named tool even without detection, writing ~/.codex/config.toml.
Codex isn't using the proxy	Confirm model_provider = 'zerosignal' in ~/.codex/config.toml.
ZeroSignal models don't appear in Codex's model picker	Expected. Codex's picker only lists models from its own catalog, which contains OpenAI models only — there is no way for a custom provider to add entries to it. Choose your model with zs-proxy connect codex --model <id> instead. Picking a gpt-* entry from the picker leaves model_provider pointing at the proxy while asking for a model it doesn't serve — and since model_context_window is a global setting rather than a per-provider one, the ZeroSignal model's window stays applied to whatever you picked. Re-run connect codex --model <id> to put both back.
stream closed before response.completed	Codex received a reply that stopped early. This is the proxy or the operator, not your config — check the proxy's log (zs-proxy proxy logs) for a sse pump ended with error or operator returned stream error line, which names the real cause.
Connection refused / can't reach the endpoint	The proxy isn't running or the base URL is wrong. Confirm with curl http://localhost:9376/healthz and start it with zs-proxy proxy start.
wallet_unfunded / payment errors	Add funds with zs-proxy fund — see Wallet & funding.

What's next

• Connecting AI tools — every connect flag and the other supported tools.
• Routing preferences — pin an operator or set a price ceiling.
• Pricing — what an agent turn costs.
• How-to guides — connect another app.