Codex — Part 8 — Common Codex Issues and Fixes
A standing reference for the runtime problems that show up after installation: shared config that will not load, sessions that seem stuck, growing context windows, and the diagnostic commands that narrow any of it down fast.
Generates a diagnostic report covering local installation, config, auth, and runtime issues.
Shows session configuration and token usage for the current run.
Summarises the visible conversation to free up context before it forces an automatic compaction.
Introduction
Part 2 covered installation problems. This post picks up afterward: Codex runs and signs in fine, but something is not behaving as expected, shared configuration is not loading, a session looks stuck, or a long-running task is eating more context than seems reasonable.
Start Here: Diagnostic Commands
| Command | Shows |
|---|---|
codex doctor | Diagnostic report for local installation, config, auth, and runtime issues |
codex login status | Which authentication method is currently active |
/status | Session configuration and token usage for the current run |
codex --version | Installed version, useful when a feature behaves differently across machines or surfaces |
Configuration Not Applying
| Symptom | Likely Cause | Fix |
|---|---|---|
| A teammate’s shared local environment is not picked up | Configuration is not in the .codex folder at the actual project root |
In a monorepo, open Codex in the directory that directly contains .codex, not a parent or sibling folder. |
| AGENTS.md changes do not seem to be taking effect | Codex rebuilds the instruction chain per run and may be reading a different file than expected | Verify what actually loaded: codex --ask-for-approval never "Summarize current instructions." |
| A skill never triggers automatically | The description does not match how you phrase requests, or allow_implicit_invocation: false is set |
Rephrase closer to the skill’s description, or invoke it explicitly with $skill-name if it is meant to be manual-only. |
| Feature works in one surface but not another | The CLI, IDE extension, and desktop app can ship different Codex versions | Compare versions directly, for example codex --version against the version reported by the other surface. |
Stuck Sessions and Approvals
| Symptom | Likely Cause | Fix |
|---|---|---|
| A task appears unresponsive | Codex is waiting on an approval you have not noticed, often from an inactive thread | Check for a pending approval prompt first. If none, run a basic command like git status to confirm the session is actually alive, then start a smaller, more focused prompt. |
| Terminal panel seems frozen | The panel itself, not the session, has stopped responding | Close and reopen the terminal panel and test with a basic command such as pwd. Restart the app if it persists. |
Growing Context and Token Usage
Codex compacts long conversations automatically as they approach the context limit, tunable through a compaction threshold in config. You do not have to wait for that to happen automatically.
# Summarise the current conversation manually before starting the next chunk of work
/compact/compact yourself at the end of a logical chunk of work rather than letting context grow until auto-compaction forces the issue mid-task. Check /status periodically on a long session to see where token usage actually stands.
Sandbox and Install Issues
Windows sandbox setup failures, the npm package-name mix-up, and other install-time errors are covered in full in Part 2. If codex doctor flags a sandbox or authentication problem, that post’s troubleshooting table is the more detailed reference to check first.
Final Thoughts
Most Codex problems past installation come down to three things: configuration living in a folder Codex is not actually looking in, a session waiting silently on approval, or a context window that has grown long enough to need a manual compact. None of the three require guessing, codex doctor, /status, and a quick check of the .codex folder location cover almost everything.
With installation and everyday configuration covered, the last piece of this series is connecting Codex to systems outside your local machine.
codex doctor before assuming a bug. Check for a pending approval before assuming a session is dead, and run /compact proactively on long sessions rather than waiting for auto-compaction to kick in mid-task.
Next, we connect Codex to systems outside your local machine with MCP: what it is, how to add a server, and how it compares to MCP support in Claude Code.