Installation and Configuration Tips

You installed Codex, ran your first prompt, and got decent results. But your colleague who has been using it for a month somehow gets answers twice as fast, never hits approval prompts for basic commands, and always has the right MCP servers loaded. The difference is not talent — it is a well-tuned config.toml and a few environment tweaks you have not made yet.

What You’ll Walk Away With

A production-ready config.toml you can adapt to your workflow
Authentication patterns for personal use, CI, and team deployments
Environment preparation tips that prevent the agent from wasting tokens on setup
Profile configurations for switching between review, development, and automation modes

Installation Essentials

Install All Three Surfaces

Codex is most powerful when you use multiple surfaces together. Install all three:

# CLI (primary standalone installer; no Node.js required)
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# Desktop -- download ChatGPT from chatgpt.com/download and select Codex mode
# IDE Extension -- install from your editor's marketplace (VS Code, Cursor, Windsurf)

On Windows PowerShell use irm https://chatgpt.com/codex/install.ps1 | iex. Homebrew and npm install -g @openai/codex remain alternatives; the npm wrapper requires Node.js 16+.

The App and IDE Extension sync automatically when both are open in the same project. You get auto-context from your editor (open files, cursor position) in the App’s composer without any additional configuration.

Verify Your Installation

# Check CLI version and auth status
codex --version
codex login status

If login status exits with code 0, you are authenticated. If not, run codex login to open the browser OAuth flow.

Config.toml Recipes

The Development Config

This is the config most individual developers should start with:

# Terra works on Free and Go and remains a balanced choice on higher plans.
model = "gpt-5.6-terra"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
file_opener = "cursor"  # or vscode, windsurf

# Speed up repeated commands
[features]
shell_snapshot = true

# Clickable notifications when tasks complete
[tui]
notifications = ["agent-turn-complete", "approval-requested"]

Free and Go expose Terra in Codex. Eligible Plus, Pro, Business, and Enterprise users can select Sol, Terra, or Luna, subject to workspace policy. Treat model = ... as an explicit workflow choice, not as documentation of a universal product default.

The Automation Config

For CI/CD and scripting, you want minimal friction and structured output:

# ~/.codex/ci.config.toml -- external profile file (Codex 0.134+)
model = "gpt-5.6-terra"
# Explicitly trusted unattended CI: never prompt, but stay workspace-scoped.
approval_policy = "never"
sandbox_mode = "workspace-write"
hide_agent_reasoning = true
web_search = "disabled"

Use it only on a reviewed, isolated runner: codex exec --profile ci "Fix the failing test". never disables prompts; workspace-write still limits filesystem and network access.

Config Validation with Schema

Add this line to the top of your config.toml to get autocompletion and validation in VS Code or Cursor with the Even Better TOML extension:

#:schema https://developers.openai.com/codex/config-schema.json

Now your editor highlights invalid keys and suggests valid values.

Authentication Tips

Personal Use

The default browser OAuth flow is the simplest:

codex login

This opens your browser, authenticates with ChatGPT, and stores credentials in the configured OS keychain or auth.json fallback.

CI/CD Authentication

For headless environments, pipe an API key:

printenv OPENAI_API_KEY | codex login --with-api-key

Or use device auth when you have a terminal but no browser:

codex login --device-auth

Control Credential Storage

# Store credentials in a file instead of the keychain
cli_auth_credentials_store = "file"

# Or explicitly use the OS keychain
cli_auth_credentials_store = "keyring"

Use file in containers and CI runners where keychain access is unavailable.

Environment Preparation

Pre-activate Your Environment

Codex inherits your shell environment. Set up your development environment before launching Codex so it does not spend tokens probing what to activate:

# Activate your Python venv BEFORE launching Codex
source .venv/bin/activate

# Start required daemons
docker compose up -d postgres redis

# Export variables Codex will need
export DATABASE_URL="postgresql://localhost:5432/myapp"

# Now launch Codex
codex

Shell Environment Policy

Control which environment variables Codex can see to avoid leaking secrets:

[shell_environment_policy]
inherit = "core"
exclude = ["AWS_*", "AZURE_*", "GITHUB_TOKEN"]
set = { NODE_ENV = "development" }

This keeps PATH and HOME but strips cloud credentials. The set table injects variables into every subprocess Codex spawns.

Install Shell Completions

Tab-completion for all Codex commands and flags:

# Zsh (add to ~/.zshrc, after compinit)
eval "$(codex completion zsh)"

# Bash (add to ~/.bashrc)
eval "$(codex completion bash)"

# Fish
codex completion fish | source

Now codex ex<TAB> expands to codex exec and all flags autocomplete.

Profile Switching

Create Profiles for Different Workflows

Keep the base model in ~/.codex/config.toml, then create one external file per profile. Since Codex 0.134, legacy [profiles.name] tables and the top-level profile = "name" selector are rejected.

model = "gpt-5.6-sol"
model_reasoning_effort = "high"
approval_policy = "on-request"
review_model = "gpt-5.6-sol"

model = "gpt-5.6-terra"
approval_policy = "on-request"

oss_provider = "ollama"  # or "lmstudio"

The review profile assumes Sol is available to your plan and workspace role. If it is not, keep Terra or choose another model shown by /model.

Switch on the fly:

codex --profile review     # Deep analysis mode
codex --profile quick      # Fast iteration mode
codex --profile oss --oss  # Local model via the configured OSS provider

Profiles are selected explicitly with --profile; there is no supported top-level default-profile selector in current Codex.

Feature Flags

Inspect Stable Features

# List all available feature flags
codex features list

shell_snapshot is stable and on by default. unified_exec is stable and on by default except on Windows, and persisted goals are stable and on by default. Use codex features enable|disable <name> only when you intentionally override those defaults.

One-Off Overrides

Override any config value for a single run without editing files:

# Use a different model for one task
codex --model gpt-5.6-terra "Quick question about this function"

# Override nested config values
codex -c sandbox_workspace_write.network_access=true "Install this npm package"

# Enable live web search for one run
codex --search "What's the latest React 19 API for this pattern?"

When This Breaks

Shell completions not working: The eval line must come after compinit in your shell config. For Zsh, add autoload -Uz compinit && compinit before the eval line if you see command not found: compdef.
Config not loading: Run codex features list to see which features are active. Check for syntax errors in your TOML file using the schema validation.
Credentials lost after restart: Switch from keyring to file credential storage if your OS keychain resets on login. Check cli_auth_credentials_store in config.
Wrong profile applied: Profile names are case-sensitive. Verify with codex --profile <name> features list to confirm the profile loads correctly.
Environment variables leaking: Audit your shell_environment_policy settings. Run Codex and ask it to echo $SECRET_VAR to verify exclusions work.

What’s Next

App Features — Master the desktop App after your config is dialed in
CLI Commands — Get the most out of the CLI with your new config
AGENTS.md Optimization — Layer project instructions on top of your config