Codex Manual
Config and Login
Most Codex config issues come from editing the wrong config.toml or setting environment variables in the wrong environment.
Common config paths:
| Environment | Config file |
|---|---|
| macOS / Linux | ~/.codex/config.toml |
| Windows native | %USERPROFILE%\.codex\config.toml |
| WSL2 | ~/.codex/config.toml inside WSL |
Windows native and WSL2 are separate environments.
Sign-in methods:
- Sign in with ChatGPT (
codex login). The CLI, App, and IDE extension share one cached login; Codex Cloud requires it. - Sign in with an OpenAI API key:
printenv OPENAI_API_KEY | codex login --with-api-key. Usage is billed at standard API rates and some ChatGPT-dependent features are limited. - Device code (beta):
codex login --device-auth, for remote or headless machines; it must first be enabled in ChatGPT security settings or workspace permissions. - A custom provider such as XAI Router.
codex login status shows the active method and codex logout clears credentials. By default credentials are stored in plaintext in auth.json under CODEX_HOME, so protect it like a password; cli_auth_credentials_store can switch to keyring, auto, or ephemeral (in memory for the current process only).
Basic settings:
approval_policy = "on-request"
sandbox_mode = "workspace-write"This lets Codex write inside the workspace and request approval when higher privileges are needed. Choose authentication with codex login or the authentication settings of a custom provider.
Also worth knowing:
- A project-level
.codex/config.tomlignoresmodel_provider,model_providers,openai_base_url,chatgpt_base_url,profile,profiles,notify, andotel; set these in the user-levelconfig.toml. - Profiles are now separate files next to
config.toml:$CODEX_HOME/profile-name.config.toml, selected with--profile profile-name. Use-c key=valueto override a single setting for one run. approval_policy = "untrusted"is no longer supported andon-failureis deprecated; useon-requestornever. See Permissions and Safety.- Web search defaults to
cached; change it with the top-levelweb_search(disabled,cached,indexed,live) or the--searchflag. - Use
agents.enabledfor the multi-agent switch; settingfeatures.multi_agentexplicitly now shows a deprecation warning.
If CODEX_HOME is set, Codex uses that directory for configuration and state. Most users do not need to set it manually.
When config does not apply, check the current OS environment, config path, environment variables, CLI overrides, profiles, and whether the App or terminal needs a restart.