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:

EnvironmentConfig 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:

  1. Sign in with ChatGPT (codex login). The CLI, App, and IDE extension share one cached login; Codex Cloud requires it.
  2. 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.
  3. Device code (beta): codex login --device-auth, for remote or headless machines; it must first be enabled in ChatGPT security settings or workspace permissions.
  4. 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.toml ignores model_provider, model_providers, openai_base_url, chatgpt_base_url, profile, profiles, notify, and otel; set these in the user-level config.toml.
  • Profiles are now separate files next to config.toml: $CODEX_HOME/profile-name.config.toml, selected with --profile profile-name. Use -c key=value to override a single setting for one run.
  • approval_policy = "untrusted" is no longer supported and on-failure is deprecated; use on-request or never. See Permissions and Safety.
  • Web search defaults to cached; change it with the top-level web_search (disabled, cached, indexed, live) or the --search flag.
  • Use agents.enabled for the multi-agent switch; setting features.multi_agent explicitly 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.