OpenAI Codex CLI stores all its configuration, credentials, session history, and logs in a structured directory hierarchy. Understanding these file locations helps you backup configurations, migrate between machines, troubleshoot issues, and customize Codex behavior.
Complete Directory Structure
Here is the full directory tree for Codex CLI configuration:
~/.codex/ # Main configuration directory
├── config.toml # Global configuration settings
├── auth.json # Credentials (if not using keyring)
├── history.jsonl # Command/session history
├── AGENTS.md # Global instructions for Codex
├── AGENTS.override.md # Override file for global instructions
├── rules/ # Custom rules directory
│ └── *.md # Individual rule files
├── logs/ # Application logs
│ └── codex-tui.log # Terminal UI log file
└── sessions/ # Session transcripts
└── YYYY/ # Year directory
└── MM/ # Month directory
└── DD/ # Day directory
└── rollout-*.jsonl # Session transcript files
For project-specific configuration:
<project-root>/
├── .codex/
│ ├── config.toml # Project-specific configuration
│ └── AGENTS.md # Project-specific instructions
└── AGENTS.md # Alternative location for project instructions
Platform-Specific Paths
Configuration file locations vary by operating system.
| File/Directory | macOS | Linux | Windows Native | Windows WSL |
|---|---|---|---|---|
| Main directory | ~/.codex/ | ~/.codex/ | %USERPROFILE%\.codex\ | ~/.codex/ |
| Global config | ~/.codex/config.toml | ~/.codex/config.toml | %USERPROFILE%\.codex\config.toml | ~/.codex/config.toml |
| Credentials | ~/.codex/auth.json or Keychain | ~/.codex/auth.json or keyring | %USERPROFILE%\.codex\auth.json | ~/.codex/auth.json or keyring |
| Sessions | ~/.codex/sessions/ | ~/.codex/sessions/ | %USERPROFILE%\.codex\sessions\ | ~/.codex/sessions/ |
| Logs | ~/.codex/logs/ | ~/.codex/logs/ | %USERPROFILE%\.codex\logs\ | ~/.codex/logs/ |
Note: On Windows, %USERPROFILE% typically resolves to C:\Users\YourUsername\.
Configuration Files Explained
Global Configuration: config.toml
The main configuration file uses TOML format and controls Codex behavior.
Location: ~/.codex/config.toml
# Model selection
model = "o3"
# Approval mode for file changes and commands
# Options: suggest, auto-edit, full-auto
approval_mode = "suggest"
# Sandbox mode for command execution
# Options: docker, none
sandbox = "docker"
# Credential storage location
# Options: file, keyring
cli_auth_credentials_store = "keyring"
# Disable telemetry
disable_telemetry = true
# Custom instructions file path (optional)
instructions_file = "~/.codex/custom-instructions.md"
# MCP (Model Context Protocol) server configuration
[mcp_servers]
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
env = { GITHUB_PERSONAL_ACCESS_TOKEN = "your-token-here" }
Project Configuration: .codex/config.toml
Project-specific configuration overrides global settings for that project only.
Location: <project-root>/.codex/config.toml
# Project-specific model
model = "o4-mini"
# More permissive approval for this project
approval_mode = "auto-edit"
# Project-specific MCP servers
[mcp_servers]
[mcp_servers.database]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
env = { DATABASE_URL = "postgresql://localhost/mydb" }
Credentials: auth.json
Stores authentication tokens when not using the system keyring.
Location: ~/.codex/auth.json
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"refresh_token": "v1:refresh:...",
"expires_at": "2025-02-15T10:30:00Z"
}
Security note: If cli_auth_credentials_store = "keyring" is set in config.toml, credentials are stored in the system keyring (macOS Keychain, Linux Secret Service, or Windows Credential Manager) instead of this file.
Global Instructions: AGENTS.md
Contains persistent instructions that Codex loads for every session.
Locations (in priority order):
~/.codex/AGENTS.override.md(highest priority)~/.codex/AGENTS.md<project-root>/.codex/AGENTS.md(project-specific, overrides global)<project-root>/AGENTS.md(alternative project location)
Example AGENTS.md:
# Global Codex Instructions
## Code Style
- Use TypeScript with strict mode
- Prefer functional programming patterns
- Add JSDoc comments to public functions
## Testing
- Write unit tests for new functions
- Use Jest as the testing framework
- Aim for 80% code coverage
## Security
- Never commit API keys or secrets
- Sanitize user input
- Use parameterized queries for databases
Session History: history.jsonl
Records command history across sessions.
Location: ~/.codex/history.jsonl
Each line is a JSON object representing a command:
{"timestamp":"2025-01-15T10:30:00Z","command":"codex \"refactor the auth module\"","cwd":"/Users/me/project"}
{"timestamp":"2025-01-15T11:45:00Z","command":"codex review","cwd":"/Users/me/project"}
Session Transcripts: sessions/
Full conversation transcripts organized by date.
Location: ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl
Example path: ~/.codex/sessions/2025/01/22/rollout-2025-01-22T10-30-00-abc123.jsonl
These files contain complete conversation history including:
- User messages and AI responses
- Tool calls and outputs
- File changes made
- Token usage statistics
Logs: codex-tui.log
Debug and error logs for troubleshooting.
Location: ~/.codex/logs/codex-tui.log
Useful for diagnosing issues with Codex CLI operation.
Rules Directory: rules/
Custom rules that extend Codex behavior.
Location: ~/.codex/rules/
Each Markdown file in this directory defines additional rules:
~/.codex/rules/
├── security-rules.md
├── code-review-rules.md
└── documentation-rules.md
Environment Variables
Environment variables can override file-based configuration.
| Variable | Purpose | Example |
|---|---|---|
CODEX_HOME | Override the main configuration directory | export CODEX_HOME=/custom/path/.codex |
OPENAI_API_KEY | API key for authentication | export OPENAI_API_KEY=sk-... |
CODEX_API_KEY | Alternative API key variable | export CODEX_API_KEY=sk-... |
OPENAI_BASE_URL | Custom API endpoint | export OPENAI_BASE_URL=https://api.custom.com/v1 |
Setting Environment Variables
macOS/Linux (add to ~/.zshrc or ~/.bashrc):
export CODEX_HOME="$HOME/.codex"
export OPENAI_API_KEY="sk-your-api-key-here"
Windows PowerShell:
$env:CODEX_HOME = "$env:USERPROFILE\.codex"
$env:OPENAI_API_KEY = "sk-your-api-key-here"
Windows (permanent via System Properties):
- Open System Properties > Advanced > Environment Variables
- Add new user variables for CODEX_HOME and OPENAI_API_KEY
Backup and Migration
Backing Up Your Configuration
To backup your Codex CLI configuration:
# Create a backup archive
tar -czvf codex-backup-$(date +%Y%m%d).tar.gz ~/.codex/
# Or copy specific files
cp ~/.codex/config.toml ~/backups/
cp ~/.codex/AGENTS.md ~/backups/
cp -r ~/.codex/rules/ ~/backups/
Migrating to a New Machine
- Copy configuration files:
# On old machine
scp -r ~/.codex/ user@newmachine:~/
# Or use the backup archive
scp codex-backup-*.tar.gz user@newmachine:~/
- Extract on new machine:
tar -xzvf codex-backup-*.tar.gz -C ~/
- Re-authenticate:
If credentials were stored in the system keyring, you will need to sign in again:
codex auth login
- Verify configuration:
codex --version
codex "hello"
Syncing Configuration Across Machines
For ongoing synchronization, consider:
- Git: Version control your config.toml, AGENTS.md, and rules/
- Dotfiles manager: Tools like chezmoi, yadm, or GNU Stow
- Cloud sync: Symlink ~/.codex/ to a synced folder (excluding auth.json)
Example Git-based sync:
# Initialize dotfiles repo
cd ~/.codex
git init
echo "auth.json" >> .gitignore
echo "sessions/" >> .gitignore
echo "logs/" >> .gitignore
git add config.toml AGENTS.md rules/
git commit -m "Initial Codex CLI configuration"
git remote add origin [email protected]:youruser/dotfiles.git
git push -u origin main
Viewing and Editing Configuration
View Current Configuration
# Display config file contents
cat ~/.codex/config.toml
# Check effective configuration (including defaults)
codex config show
Edit Configuration
# Open in default editor
codex config edit
# Or edit directly
nano ~/.codex/config.toml
code ~/.codex/config.toml
Reset Configuration
To reset to defaults:
# Backup first
mv ~/.codex/config.toml ~/.codex/config.toml.backup
# Codex will recreate with defaults on next run
codex
Troubleshooting Configuration Issues
Configuration Not Loading
- Check file permissions:
ls -la ~/.codex/config.toml
# Should be readable by your user
- Verify TOML syntax:
# Install toml validator
npm install -g toml-cli
# Validate
toml ~/.codex/config.toml
- Check for CODEX_HOME override:
echo $CODEX_HOME
Credentials Not Working
- Check storage location:
grep cli_auth_credentials_store ~/.codex/config.toml
- Re-authenticate:
codex auth logout
codex auth login
- Verify API key (if using environment variable):
echo $OPENAI_API_KEY | head -c 10
Sessions Not Saving
- Check write permissions:
ls -la ~/.codex/sessions/
- Verify disk space:
df -h ~/.codex/
- Check session directory structure:
find ~/.codex/sessions -name "*.jsonl" | head -5
Next Steps
- Learn installation basics with How to Install OpenAI Codex CLI
- Master session management with How to Resume Sessions in Codex CLI
- Explore official Codex CLI documentation
- Compare configurations with Gemini CLI and Claude Code