Codex CLI
Add a custom model_provider in ~/.codex/config.toml so OpenAI's Codex CLI uses this platform's /v1/responses
Codex CLI 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.
Get an API key#
Create one at qd.zsopc.com/dashboard/keys and export it (ideally in ~/.zshrc / ~/.bashrc):
export PLATFORM_API_KEY="sk-gpushare-xxx"
Setup#
Edit ~/.codex/config.toml (or $CODEX_HOME/config.toml if you set CODEX_HOME):
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_urlneeds/v1: Codex joins it with/responses, so the request goes tohttps://qd.zsopc.com/v1/responses.wire_apican only beresponses: 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.tomlignoresmodel_providerandmodel_providers. - The provider id can't be a reserved built-in name such as
openai,ollamaorlmstudio.
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. 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:
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.
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 |
Full error reference: Error codes. Timeouts and keepalives on long tasks: Streaming.
Other clients#
- Claude Code — Anthropic's terminal coding assistant
- Gemini CLI — Google's terminal coding assistant
- Cline — VS Code coding extension