How to use GPT-5.6 Sol, Terra, and Luna in Codex

Quick Setup

To use gpt-5.6-sol in Codex, you need three things:

1. The official Codex CLI.
2. A provider API key.
3. A Codex Base URL from your provider dashboard.

Then configure ~/.codex/auth.json and ~/.codex/config.toml.

Do not publish the provider’s backend URL in public tutorials, issue trackers, screenshots, or shared docs. Readers should copy the current Codex Base URL from their own dashboard.

Choose a GPT-5.6 Model

Model ID	Use it for
gpt-5.6-sol	Hard coding tasks, architecture, debugging, large refactors
gpt-5.6-terra	Everyday coding, review, planning, documentation
gpt-5.6-luna	Cheaper drafts, summaries, and high-volume low-risk tasks

OpenAI model docs also list gpt-5.6 as an alias for Sol. With a proxy provider, use the exact model name shown in the provider dashboard unless support confirms the alias works.

Install Codex

On macOS or Linux:

npm install -g @openai/codex
codex -V
mkdir -p ~/.codex

On macOS, Homebrew may also be available:

brew install codex

On Windows, install Git for Windows and Node.js first. Then run:

npm install -g @openai/codex
codex -V
New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"

If you already use Codex, back up your .codex folder before editing it. Do not blindly delete it just because another guide says to reset the folder.

Add Your API Key

Create auth.json in the Codex config folder.

macOS or Linux:

nano ~/.codex/auth.json

Windows PowerShell:

notepad "$env:USERPROFILE\.codex\auth.json"

Add:

{
  "OPENAI_API_KEY": "your provider API key"
}

Keep this file private.

Configure GPT-5.6 Sol

Create config.toml.

macOS or Linux:

nano ~/.codex/config.toml

Windows PowerShell:

notepad "$env:USERPROFILE\.codex\config.toml"

Use this template:

model_provider = "codex_provider"
model = "gpt-5.6-sol"
model_reasoning_effort = "xhigh"
disable_response_storage = true
preferred_auth_method = "apikey"

[model_providers.codex_provider]
name = "codex_provider"
base_url = "paste the Codex Base URL from your provider dashboard"
wire_api = "responses"

Restart the terminal, open a project, and run:

cd your-project-folder
codex

For the first test, ask for a read-only task:

Inspect this repository and summarize the build command, test command, and main source folders.
Do not modify files.

Switch Between Sol, Terra, and Luna

Change only the model line.

For Terra:

model = "gpt-5.6-terra"

For Luna:

model = "gpt-5.6-luna"

For Sol:

model = "gpt-5.6-sol"

Do not change the Base URL when you only want to switch models. Model selection and provider routing are separate.

Reasoning Effort

Start with:

model_reasoning_effort = "xhigh"

Use high or xhigh for normal coding. Use max only when your provider supports it and the task is worth the extra token cost.

Common Problems

Symptom	Check first
401 or unauthorized	API key, auth.json path, copied spaces
404 or model not found	Exact model name and provider model support
429 or rate limit	Quota, channel limits, repeated retries
Selected model is at capacity	Try Terra or Luna, reduce parallel work, or wait
Codex starts but tools fail	Wrong backend type, missing Responses API support, outdated Codex
Windows path issues	Check %USERPROFILE%\.codex and PowerShell quoting

If the setup fails, change one thing at a time: key, model, Base URL, Codex version, or provider channel. Randomly changing all of them is how a five-minute setup becomes a two-hour fog machine.

References

• OpenAI GPT-5.6 announcement
• OpenAI API model docs
• GPT 5.6 SOL IS HERE! How to use it.