# Codex CLI

> Add a custom model_provider in ~/.codex/config.toml so OpenAI's Codex CLI uses this platform's /v1/responses

Source: https://qd.zsopc.com/en/docs/integrations/codex-cli

> [Codex CLI](https://github.com/openai/codex) is OpenAI's coding assistant for the terminal; it calls models through the Responses API. These steps were checked against Codex CLI 0.169.0 (released 2026-11-13) and the official [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference).

## Get an API key

Create one at [qd.zsopc.com/dashboard/keys](https://qd.zsopc.com/dashboard/keys) and export it (ideally in `~/.zshrc` / `~/.bashrc`):

```bash
export PLATFORM_API_KEY="sk-gpushare-xxx"
```

## Setup

Edit `~/.codex/config.toml` (or `$CODEX_HOME/config.toml` if you set `CODEX_HOME`):

```toml
model_provider = "xiaozhan"
model = "gpt-6.1-sol"

[model_providers.xiaozhan]
name = "xiaozhan"
base_url = "https://qd.zsopc.com/v1"   # Codex appends /responses
env_key = "PLATFORM_API_KEY"            # the environment variable that holds the key
wire_api = "responses"
```

Then just run `codex`. There's no need for `codex login`: a custom provider uses the environment variable named by `env_key` as its key.

Key points:

- **`base_url` needs `/v1`**: Codex joins it with `/responses`, so the request goes to `https://qd.zsopc.com/v1/responses`.
- **`wire_api` can only be `responses`**: it's the one supported value and the default; the old `"chat"` value was removed and now raises an error.
- **Provider settings belong in the user-level `~/.codex/config.toml`**: a project's `.codex/config.toml` ignores `model_provider` and `model_providers`.
- The provider id can't be a reserved built-in name such as `openai`, `ollama` or `lmstudio`.

## Choosing a model

Codex only uses `/v1/responses`, so `model` must support the OpenAI Responses protocol. Codex's prompts are tuned for GPT models; we suggest:

| Job | Model |
|---|---|
| Default / hard tasks | `gpt-6.1-sol`, `gpt-5.6-sol` |
| Everyday, cheaper | `gpt-6-luna`, `gpt-6.1-terra` |

A few non-GPT models such as `claude-opus-4-8` and `claude-sonnet-4-6` also have a Responses channel — see the OpenAI Responses column of the [compatibility matrix](../reference/compatibility-matrix.md). Models without one return 503 `no_channel_available`.

A model ID missing from Codex's built-in catalog runs with generic settings (Codex may warn at start-up). If needed, add `model_context_window = <window size>` or `model_reasoning_effort = "high"` at the top level.

## Optional: WebSocket transport

This platform serves the Responses API WebSocket transport on the same path (`GET /v1/responses`). Add one line to the provider:

```toml
supports_websockets = true
```

Codex then switches to WebSocket, and in long sessions each turn uploads only what's new instead of resending the whole history.

## Several setups (profiles)

Since Codex 0.134.0 a profile is a file of its own: put the top-level keys above into `~/.codex/<name>.config.toml` and load it with `codex --profile <name>`; it's applied on top of `config.toml`.

> Codex can also connect MCP servers. For this platform's image, video and music tools, see [MCP media tools](./mcp.md).

## Troubleshooting

| Symptom | What to check |
|---|---|
| 401 `invalid_api_key` | Whether `echo $PLATFORM_API_KEY` prints the key in the terminal that starts `codex`, and whether it was copied in full (76 characters) |
| 404 | Whether `base_url` ends in `/v1` |
| The settings have no effect | The provider sits in a project-level `.codex/config.toml`; move it to `~/.codex/config.toml` |
| 503 `no_channel_available` | That model has no Responses channel — pick one from the table above |
| 402 `quota_exceeded` | Balance exhausted. Every key shares one account balance — top up on the [Top up page](https://qd.zsopc.com/dashboard/billing) |

Full error reference: [Error codes](../reference/errors.md). Timeouts and keepalives on long tasks: [Streaming](../guides/streaming.md#long-requests-and-timeouts).

## Other clients

- [Claude Code](./claude-code.md) — Anthropic's terminal coding assistant
- [Gemini CLI](./gemini-cli.md) — Google's terminal coding assistant
- [Cline](./cline.md) — VS Code coding extension
