Skip to content

Manual configuration for Codex

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

Open in ClaudeOpen in ChatGPT

On this page · 7 sections
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.scalemax.pro/v1
  • OpenAI token-pack key: https://api.scalemax.pro/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 (Windows: %USERPROFILE%\.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.scalemax.pro/token/v1. This opens the file in an editor, creating it if needed:

bash
mkdir -p ~/.codex && ${EDITOR:-nano} ~/.codex/config.toml
config.toml
model = "gpt-5.6-terra"
model_provider = "scalemax"

[model_providers.scalemax]
name = "ScaleMax"
base_url = "https://api.scalemax.pro/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 "ScaleMax API key: "
IFS= read -r -s SCALEMAX_API_KEY
printf "\n"
printf "%s" "$SCALEMAX_API_KEY" | codex login --with-api-key
unset SCALEMAX_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

  • gpt-6.1-sol — GPT-6.1 Sol
  • gpt-6-sol — GPT-6 Sol
  • gpt-6-luna — GPT-6 Luna
  • gpt-6-astra — GPT-6 Astra
  • gpt-5.6-terra — GPT-5.6 Terra
  • gpt-5.6-sol — GPT-5.6 Sol
  • gpt-5.6-luna — GPT-5.6 Luna

Use an exact ID. gpt-5.6-terra is the default in the config above; the GPT-6 models work the same way. gpt-5.6-luna is useful for a low-cost connectivity check. Your key's own list is always at GET /v1/models.

Verify with a tiny request

For a direct one-token API check, set the key only in the current terminal, run this request, and then clear it (unset SCALEMAX_API_KEY, or in PowerShell Remove-Item Env:SCALEMAX_API_KEY):

bash
export SCALEMAX_API_KEY="YOUR_SCALEMAX_KEY"

curl -sS "https://api.scalemax.pro/v1/responses" \
  -H "Authorization: Bearer $SCALEMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-luna",
    "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.6-luna \
  --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 scalemax@latest
scalemax

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 scalemax 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 ScaleMax key or redirect provider credentials for other users.