Codex config.toml: locations, precedence, and a minimal setup
Find the configuration Codex actually loads, separate user and project settings, and verify changes with a minimal TOML example.
Start with this guideCodexFree · Independent configuration notes
A handbook for Codex.
Configuration notes for the Client + CLI, from using your own API to project instructions, MCP, and troubleshooting. Each guide includes examples, steps, and sources.
Configuration notes
Connect Codex to your API: Base URL, model, and env_key
Map your provider’s URL, model ID, and credential variable to user-level Codex configuration, then verify Responses compatibility.
Codex Profiles: separate files, overrides, and migration
Keep scenario-specific differences in separate profile files, understand precedence, and migrate the retired inline profile format.
Codex authentication: ChatGPT, API keys, and auth.json
Separate authentication from provider routing and credential storage, including why exporting a key is not the same as signing in.
Write AGENTS.md for Codex: global rules, project rules, and overrides
Turn project structure, validation commands, and working agreements into reusable instructions, with a template and a loading check.
Configure MCP in Codex: HTTP, local servers, and connection checks
Distinguish HTTP from STDIO, configure authentication, discover tools, and validate one small call before expanding access.
Codex permissions: sandboxing, approvals, and networking
Separate what commands can do from when approval is requested, with read-only and workspace-editing examples and a migration note.
Troubleshoot Codex configuration: 401, 404, stale models, and client differences
Narrow down configuration, authentication, routing, and execution failures one layer at a time, with a redacted reproduction template.
Setup assistant
Choose your operating system, install CC Switch, and follow the configuration steps.
Have an API key but don't know where it goes?
CC Switch is an open-source app with a visual interface. It writes the Codex configuration for you; prepare only the Base URL, API key, and model name.
CC Switch / CodexNo ChatGPT account needed
- 01
Open CC Switch and click Codex at the top
Claude, Codex, and Gemini store separate configurations, so choose the correct tab.
- 02
Click + and add your API
Enter the provider's Base URL, API key, and model. Turn on local routing if it only offers a Chat endpoint.
- 03
Click Enable, then reopen Codex
Wait until it shows active. A running Codex Client does not reload the new configuration automatically.
When it shows active, reopen Codex
No ChatGPT sign-in · Model requests go to your API
Common questions
Do I have to sign in to ChatGPT?
You can use a compatible third-party API without signing in to ChatGPT or OpenAI, but you still need an API key from your provider. Cloud tasks and account sync may still require an official account.
Is the free API available now?
Not yet. Email registration is a waitlist. Available models, quotas, rate limits, and timing will be explained when access opens. Signing up does not issue a key immediately.
Does this work for both the Client and CLI?
This site covers the Codex Client + CLI. They generally share ~/.codex, but you should verify CODEX_HOME and credential sources, then restart the relevant process after changes.
Will any OpenAI-compatible API work?
Not necessarily. Codex requires the Responses API. Providers that only support Chat Completions need adaptation. Our guide and tools explain the protocol, URL, and model checks.
Do I enter my API key on this website?
No. Configure the key on your own computer using CC Switch or Codex settings. Our config generator asks for an environment variable name, not your secret. The free API waitlist only asks for an email address.
Free API notifications
Access is not open yet. Leave your email to receive a key, base URL, models, quota details, and setup instructions when available.
Used only for API access notices. See the privacy policy.