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. zs-proxy connect codex writes a keyless provider; your wallet is the credential.

Before you start

The proxy must be running (zs-proxy proxy start) and funded — see How-to guides.

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 kept. 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'

connect rewrites the whole file rather than splicing text, so keys come out alphabetically sorted, strings single-quoted, and comments in an existing config.toml are lost. Use --print to preview, and config.toml.bak to recover.

There's no env_key line: Codex treats it as optional, and a provider that sets neither env_key nor requires_openai_auth needs no authentication. codex doctor confirms it: "OpenAI auth is not required for the active model provider".

Codex learns the active model's context window from its built-in model catalog, which contains only OpenAI models. Without model_context_window, Codex would run a ZeroSignal model on a guessed context length. connect writes the line only when you select a model the proxy advertises, and clears it if you switch to one whose window the proxy doesn't publish. If no operator serving the model answered while connect was running, the existing line is left unchanged. 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; a reply confirms the setup works.

info

Codex talks the Responses API (wire_api = 'responses'), which the proxy serves at POST /v1/responses; there's nothing to configure for it. It is the only wire API Codex still supports. wire_api = 'chat', which older guides set, 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. The picker lists only Codex's own catalog, which contains only OpenAI models, and a custom provider can't add entries to it. Choose your model with zs-proxy connect codex --model <id> instead.
404 no_operator ("no operator is currently advertising the model") after choosing a gpt-* model in Codex's picker	model_provider still points at the proxy, which doesn't serve that model. model_context_window is global, not per-provider, so the ZeroSignal model's window also stays applied. Re-run zs-proxy 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 in the chat app, or with zs-proxy fund for a proxy-only wallet — 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.