Codex CLI and Desktop

Codex CLI and the desktop app use the Responses-compatible gateway. Install the CLI from the OpenAI Codex documentation:

npm install -g @openai/codex
codex --version

Install the desktop app using OpenAI's current instructions. The CLI and desktop app share the user configuration described below.

Configure the provider

The provider configuration must be in the user-level ~/.codex/config.toml file. On Windows, use %USERPROFILE%\\.codex\\config.toml. Do not put this provider in a project-level .codex/config.toml; provider redirection there is ignored.

model = "<FULL_MODEL_ID>"
model_provider = "gateway"
model_supports_reasoning_summaries = false

[model_providers.gateway]
name = "AI Gateway"
base_url = "http://127.0.0.1:11113/v1"
env_key = "AI_GATEWAY_API_KEY"
wire_api = "responses"
supports_websockets = false

Codex custom providers currently use Responses. The gateway exposes a stateless Responses subset over HTTP/SSE, so do not enable WebSocket support. Use the complete public model ID copied from /models.

Provide the API key

export AI_GATEWAY_API_KEY="YOUR_API_KEY"

Verify

From the CLI, run codex and send a read-only task. For the desktop app, fully quit and reopen it, select Codex, and send a task. Check Request Logs for both clients.

Troubleshooting

• Configuration ignored: Confirm it is in the user-level config, not .codex/config.toml in the project.
• 401: Check that the environment variable is visible to the CLI or GUI process.
• 404: The base URL must include /v1 and must not include /responses.
• Model or tool errors: The model must support agent and tool use.
• Features that call stateful Responses sessions, WebSockets, or APIs outside /v1/responses are outside this integration.