Skip to content

Manual configuration for Codex

Connect Codex to CloudService through the Responses API without npx or a project-level secret.

This page is for Codex, not Claude Code. Codex uses an OpenAI-compatible Responses provider. For Claude Code's Anthropic Messages settings, use Manual configuration for Claude Code.

Choose the URL that belongs to the key

  • API-credit key: https://api.yourdomain.example/v1
  • OpenAI token-pack key: https://api.yourdomain.example/token/v1

The key types are intentionally isolated. Do not use an API-credit key on the token URL or a token-pack key on the credit URL. Claude token-pack keys cannot use the Codex model catalog.

Configure the Responses provider

Create ~/.codex/config.toml, or merge these fields into the user config while preserving unrelated settings. If you bought an OpenAI token pack, change only base_url to https://api.yourdomain.example/token/v1.

toml
model = "gpt-5.6-terra"
model_provider = "cloudservice"

[model_providers.cloudservice]
name = "CloudService"
base_url = "https://api.yourdomain.example/v1"
wire_api = "responses"
requires_openai_auth = true

wire_api = "responses" is required. Do not set this provider to Anthropic Messages, and do not put the API key in config.toml or a repository-level .codex/config.toml.

Log in without exposing the key

Codex CLI and the Codex IDE extension share the same user configuration and authentication. This prompt does not echo the key or place it in shell history:

bash
printf "CloudService API key: "
IFS= read -r -s CLOUDSERVICE_API_KEY
printf "\n"
printf "%s" "$CLOUDSERVICE_API_KEY" | codex login --with-api-key
unset CLOUDSERVICE_API_KEY

Codex stores the credential in its configured authentication store. To replace it, run the login command again; to remove it, run codex logout.

Available Codex models

  • codex-auto-review
  • gpt-5.3-codex
  • gpt-5.4
  • gpt-5.4-mini
  • gpt-5.5
  • gpt-5.6-luna
  • gpt-5.6-sol
  • gpt-5.6-terra

Use an exact ID. gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna are available through the Codex provider; gpt-5.4-mini is useful for a low-cost connectivity check.

Verify with a tiny request

For a direct one-token API check, export the key only in the current shell, run this request, and then unset CLOUDSERVICE_API_KEY:

bash
curl -sS "https://api.yourdomain.example/v1/responses" \
  -H "Authorization: Bearer $CLOUDSERVICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4-mini","input":"K","max_output_tokens":1}'

A successful response has an id and an output item. Then verify that Codex itself reads the provider:

bash
codex exec \
  --model gpt-5.4-mini \
  --sandbox read-only \
  --skip-git-repo-check \
  "Reply with the single uppercase letter K."

Automatic configuration

Install the reusable CLI once, then run it directly—no npx is required:

bash
npm install -g cloudservice@latest
cloudservice

Select Codex and the key's detected billing mode. The CLI backs up the existing user config, writes the Responses provider, authenticates safely, and verifies the selected model. Run cloudservice doctor afterward for a repeatable health check.

Security boundary

Keep authentication in the Codex user store. Project configuration can select a model but should never contain a CloudService key or redirect provider credentials for other users.