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_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:

JobModel
Default / hard tasksgpt-6.1-sol, gpt-5.6-sol
Everyday, cheapergpt-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#

SymptomWhat to check
401 invalid_api_keyWhether echo $PLATFORM_API_KEY prints the key in the terminal that starts codex, and whether it was copied in full (76 characters)
404Whether base_url ends in /v1
The settings have no effectThe provider sits in a project-level .codex/config.toml; move it to ~/.codex/config.toml
503 no_channel_availableThat model has no Responses channel — pick one from the table above
402 quota_exceededBalance 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