playbook/outfitter-agents/plugins/outfitter/skills/codex-config/references/troubleshooting.md

Troubleshooting Codex Configuration

Common issues and solutions for Codex CLI configuration.

Common Issues

Config Not Loading

Symptoms: Settings not applied, defaults used instead

Solutions:

1. Verify ~/.codex/config.toml exists
2. Check TOML syntax
3. Use -c to override and test

# Test with override
codex -c model="gpt-5.2" --help

# Validate TOML syntax
cat ~/.codex/config.toml | toml-lint

MCP Server Not Connecting

Symptoms: Tools not available, connection errors

Checklist:

1. Check command path is correct
2. Verify API keys in env section
3. Check enabled = true
4. Review tool_timeout_sec

# List servers and status
codex mcp list

# Test server connection
codex mcp test server-name

Skills Not Found

Symptoms: $skill-name not recognized

Checklist:

1. Verify path hierarchy
2. Check skill directory structure
3. Ensure SKILL.md exists in skill folder

Skills path precedence:

1. $CWD/.codex/skills/
2. $CWD/../.codex/skills/
3. $REPO_ROOT/.codex/skills/
4. ~/.codex/skills/
5. /etc/codex/skills/
6. Built-in skills

Sandbox Too Restrictive

Symptoms: Permission denied, can't access files

Solutions:

• Use -s workspace-write for normal development
• Check project trust level
• Consider --add-dir for additional paths

# Add additional writable directory
codex --add-dir /path/to/data "task requiring data access"

# Check current sandbox mode
codex -c sandbox_mode

Debug Commands

Check Current Configuration

# View current features
codex features

# Check effective config
codex config show

Session Management

# Resume previous session
codex resume

# Resume last session
codex resume --last

# List recent sessions
codex sessions

Sandbox Debugging

# Run command in sandbox debug mode
codex sandbox <command>

# Check sandbox permissions
codex sandbox --check

Validation

TOML Syntax

# Using toml-lint
cat ~/.codex/config.toml | toml-lint

# Using Python
python -c "import toml; toml.load(open('$HOME/.codex/config.toml'))"

Test Config Override

# Test model setting
codex -c model="gpt-5.2-codex" --help

# Test multiple settings
codex -c model="gpt-5.2" -c model_verbosity="high" --help

Verify MCP Servers

# List all configured servers
codex mcp list

# Check specific server
codex mcp test graphite

Log Locations

Codex logs are typically in:

• ~/.codex/logs/ (if logging enabled)
• System journal (on Linux with systemd)

Reset Configuration

If configuration is corrupted:

# Backup current config
cp ~/.codex/config.toml ~/.codex/config.toml.bak

# Start fresh
rm ~/.codex/config.toml

# Recreate with defaults
codex config init