Use Codex CLI

This guide explains how to use available models in Codex CLI through Cubicspaces.

Prerequisites

• Codex CLI is installed.
• You have a Cubicspaces API key.
• You know the exact model name available to your account. Use the name shown in the Cubicspaces console.

Provide your API key

Set the API key as an environment variable in the same terminal session from which you launch Codex:

Windows PowerShell

$env:CODEX_GATEWAY_API_KEY = "YOUR_API_KEY"
codex

macOS / Linux / WSL

export CODEX_GATEWAY_API_KEY="YOUR_API_KEY"
codex

Replace YOUR_API_KEY with your key. Do not commit it to a repository or share it. You can also use a secrets manager to inject this environment variable into the Codex CLI process.

Use the Windows desktop app

If you launch the Codex desktop app from the Start menu, it will not inherit a variable set temporarily in a separate PowerShell window. Set CODEX_GATEWAY_API_KEY as a Windows user environment variable instead:

1. Press Win + R, enter sysdm.cpl, and press Enter.
2. Open Advanced → Environment Variables.
3. Under User variables at the top, select New.
4. Set the variable name to CODEX_GATEWAY_API_KEY and the value to your Cubicspaces API key, then save.
5. Fully quit the Codex desktop app and reopen it.

The desktop app and CLI use the same Codex configuration file. On Windows, its default path is %USERPROFILE%\.codex\config.toml. Do not put your API key in the TOML file.

Configure Codex CLI

The configuration file is located at:

• Windows: %USERPROFILE%\.codex\config.toml
• macOS, Linux, and WSL: ~/.codex/config.toml

Add or merge this configuration. This example uses gpt-6-astra; confirm that your Codex version recognizes it and that your Cubicspaces account can access this exact model name. If the gateway uses a custom alias that Codex does not recognize, ask your administrator for the matching model catalog configuration.

model = "gpt-6-astra"
review_model = "gpt-6-astra"
model_reasoning_effort = "high"
model_provider = "cubicspaces"

[model_providers.cubicspaces]
name = "Cubicspaces"
base_url = "https://cubicspaces.cloud/v1"
wire_api = "responses"
env_key = "CODEX_GATEWAY_API_KEY"

model, review_model, model_reasoning_effort, and model_provider are top-level settings. If the file already has sections such as [desktop], put these four lines at the beginning of the file, before its first table; do not put them under [desktop]. [model_providers.cubicspaces] is a separate table, not nested under [desktop]. Do not add a second definition of an existing key or table.

If your account or administrator provides a dedicated API endpoint, use it in place of the example base_url. Do not put your API key in the configuration file.

Verify the connection

After launching Codex CLI, run /status and confirm the selected model and provider. Then send a simple prompt, for example:

Reply with exactly: gateway-ok

A reply confirms that a basic request reached the service. Also test streaming, multi-turn conversation, and continuing a conversation after a tool call. A successful text reply alone does not prove that streaming and tool round trips are compatible; full compatibility depends on Codex CLI, the selected model, and the gateway's handling of Responses API events and conversation items.

Troubleshooting

401 or authentication failed

Check that the environment variable is named CODEX_GATEWAY_API_KEY, contains a valid Cubicspaces API key, and is set in the terminal where Codex CLI is launched.

404 or request path not found

Check the base_url. The default is https://cubicspaces.cloud/v1; keep the trailing /v1.

Model unavailable

Set model and review_model to the exact model names available to your account. The selected model must be supported by both Codex CLI and the gateway.

For more information about custom model providers in Codex, see the official gateway compatibility guide.