# Codex Setup: Connect the CLI and IDE

> Configure the Codex CLI and IDE extension to use ZRouter as a custom Responses API provider, with your account key, a model choice, and the supported features.

## Compatibility first

**Full Codex sessions still require compatibility validation.** Account keys accept Responses function tools and explicit text tool results, but stored response continuation, encrypted reasoning replay, and custom free-form tools remain unsupported. Codex can depend on those features, so this configuration does not guarantee full agent-session compatibility.

Create a dedicated account API key, add credit, and choose an available tool-capable model that supports Responses requests. A successful text response alone does not establish full Codex compatibility. Review [account compatibility](/docs/integrations/troubleshooting) before using an agent workflow.

## Configure the provider

Set the key in the environment used to launch Codex:

```bash
export ZROUTER_API_KEY="YOUR_ZROUTER_KEY"
```

Merge this configuration into **`~/.codex/config.toml`**, preserving unrelated settings. Replace the model with an enabled identifier from your ZRouter dashboard:

```toml
model = "PROVIDER_INSTANCE/MODEL_ID"
model_provider = "zrouter"

[model_providers.zrouter]
name = "ZRouter"
base_url = "https://zrouter.si/v1"
env_key = "ZROUTER_API_KEY"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
```

Codex custom providers use the Responses protocol. The URL includes `/v1` once. WebSockets are disabled because this setup uses the gateway's HTTP/SSE endpoint. Custom provider selection belongs in user-level configuration; project-local provider settings are not applied. See [Codex advanced configuration](https://learn.chatgpt.com/docs/config-file/config-advanced) and the [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference).

## Launch and verify

```bash
curl "https://zrouter.si/v1/responses" \
  -H "Authorization: Bearer $ZROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"PROVIDER_INSTANCE/MODEL_ID","input":"Say hello","max_output_tokens":256,"store":false}'

codex
```

The curl request consumes provider tokens. Check that Codex selects ZRouter, then try a small task and review gateway logs for Responses and tool compatibility. Some model/provider combinations cannot satisfy all agent features.

## IDE extension

Use the same user-level provider configuration for the Codex IDE extension. Make the environment key available to the extension process, then restart the editor. Do not assume an editor opened from the desktop inherits your shell variables. Keep provider secrets out of project configuration and source control.

## Troubleshooting

- A missing environment-key error means `ZROUTER_API_KEY` is unavailable to that process.
- A `/v1/v1/responses` error means the API version was appended twice.
- A provider or model error requires an enabled gateway model that supports the requested behavior.
- A prepaid custom-tool, encrypted-reasoning, or continuation rejection identifies a feature outside the supported function-tool subset.

See [shared troubleshooting](/docs/integrations/troubleshooting). A ChatGPT subscription does not supply ZRouter credits or transfer subscription usage to this custom provider.