Configure Codex CLI

Codex talks to OpenAI by default. Switching it to StoryClaw takes two things: a provider block, and your key in an environment variable.

If Codex is not installed yet, start with Install Codex CLI. Create your key on the API Keys page of the console — see API Keys. Pick either option below; the result is identical.

Option A: manual setup

Write the following into ~/.codex/config.toml (create the file if it does not exist):

model_provider = "storyclaw"
model = "gpt-5.6-sol"

[model_providers.storyclaw]
name = "StoryClaw"
base_url = "https://llm.storyclaw.com/v1"
env_key = "STORYCLAW_API_KEY"
wire_api = "responses"
disable_response_storage = true

A few things in this block are easy to get wrong:

• storyclaw is a name you choose, but model_provider = "storyclaw" and [model_providers.storyclaw] must use the same word — rename both together. Avoid openai, ollama, and lmstudio; those are reserved in Codex.
• env_key holds the name of an environment variable, not the key itself — the key is set separately in the next step and never appears in this file.
• base_url must include /v1. Codex appends /responses to it.
• disable_response_storage = true is required. StoryClaw does not store responses, so without it Codex tries to continue conversations with previous_response_id and fails.
• model takes a single value — the default model. Available IDs are in Available models. Pass --model at launch to use a different one.

On macOS and Linux, one command writes the whole file:

mkdir -p ~/.codex && cat > ~/.codex/config.toml <<'EOF'
model_provider = "storyclaw"
model = "gpt-5.6-sol"

[model_providers.storyclaw]
name = "StoryClaw"
base_url = "https://llm.storyclaw.com/v1"
env_key = "STORYCLAW_API_KEY"
wire_api = "responses"
disable_response_storage = true
EOF

Then put the key in an environment variable:

# macOS / Linux — add to ~/.zshrc or ~/.bashrc to persist
export STORYCLAW_API_KEY="your-storyclaw-key"

# Windows (PowerShell) — reopen the terminal afterwards
setx STORYCLAW_API_KEY "your-storyclaw-key"

Option B: the CC Switch GUI

CC Switch is an open-source provider manager that configures the same thing through a GUI, with no TOML to write. It writes the settings into ~/.codex/config.toml, so the result is the same as Option A. On macOS, brew install --cask cc-switch is all it takes; other platforms are covered in CC Switch.

Add a provider

Launch CC Switch, switch to the Codex tab at the top, and click the + button in the upper right.

Fill in the settings

In the "Add new provider" dialog, click Custom configuration and start with the basics below.

Then expand Advanced options at the bottom of the form:

Model mapping, just below the advanced options, decides which models the /model command in Codex and the model dropdown in the desktop app can see. Fill it in three steps:

1. Click Fetch model list to pull the available models using the endpoint and key you just entered.
2. Click Add model to add a row to the table.
3. Click the dropdown arrow on that row and pick a model from the fetched list. You can also type one by hand — the Actual request model column must match Available models.

Repeat steps 2 and 3 for each model you want. Restart Codex afterwards for the list to refresh.

Finally, scroll on to the config.toml (TOML) block — it shows exactly what CC Switch will write. Tick Apply shared configuration in its upper right so the settings land in the global ~/.codex/config.toml and apply to every project, then click Add in the lower right.

CC Switch writes the settings — the key included — into ~/.codex/config.toml, so no files need editing by hand and the environment-variable step from Option A is unnecessary.

Enable the provider

Back in the provider list, hover the StoryClaw-Codex row and click the Enable button on its right. A highlighted row means it is active.

Verify the setup

Restart your terminal first — Codex reads environment variables at startup. Then go to any project directory:

codex

The startup screen shows the model in use. Send any message and a normal reply means the connection works.

Using the Codex desktop app? The same configuration applies immediately — see Codex desktop.

Available models

Codex speaks the OpenAI Responses protocol; it dropped Chat Completions support in February 2026. StoryClaw currently exposes three GPT models over Responses:

Check the current list any time:

curl https://llm.storyclaw.com/v1/models \
  -H "Authorization: Bearer YOUR_KEY"

Models that come back with a responses_api_url field are the ones Codex can use directly.

Choosing a model

Switch models with /model during a session, or set one at launch:

codex --model gpt-5.6-luna

Common adjustments

Troubleshooting

For install problems or a missing codex command, see Install Codex CLI.