Run codex doctor first. It checks runtime, auth, network reachability, config, terminal, and MCP in one command, and it has a JSON mode for support tickets. After that, assume the sandbox: network errors during package installs, silent write failures, and commands that fail only inside Codex are almost always workspace-write doing its job, because it disables network access by default. Check sandbox_mode and approval_policy before assuming anything is broken. The other frequent surprise is billing: codex login status tells you whether the session is on your ChatGPT plan or on an API key, which bills separately at standard API rates.
- Start with
codex doctor. One command, and it has a--jsonmode for bug reports. - Network errors on install:
workspace-writedisables the network by default. - Cannot write anything: the sandbox is
read-only. - Billed per token: the session is signed in with an API key, not your plan.
- Test with full access once, to isolate. Then put the boundary back.
- On Linux and WSL2 the sandbox needs
bubblewrapinstalled.
Start with codex doctor
Codex ships a single diagnostic that covers most of what you would otherwise check by hand. It landed in v0.131.0 and has grown since; as of August 2026 it reports runtime, authentication, network reachability, terminal environment, configuration, Git state, and MCP server resolution in one grouped, colour-coded report.
codex --version
codex doctor
# structured and redacted, for a bug report or a support ticket
codex doctor --jsonThe dominant cause
| Symptom | Actually | Fix |
|---|---|---|
ECONNREFUSED during npm install | Network off in workspace-write | Enable network_access |
EAI_AGAIN, DNS failures, hanging fetches | Same | Same |
| Cannot write any file | Sandbox is read-only | --sandbox workspace-write |
| Cannot write outside the project | Working as designed | Add a writable_roots entry |
Cannot write to /tmp | exclude_slash_tmp or exclude_tmpdir_env_var set | Unset it, or add the path |
| A command works in your shell, not in Codex | Sandbox restriction | Check the mode first |
| Constant approval prompts | approval_policy is untrusted | Use on-request |
| No prompts at all, and edits everywhere | Someone left --yolo on | Put the boundary back |
# does it work with restrictions removed?
codex --sandbox danger-full-access --ask-for-approval never
# if yes, it was policy, not a bug. Fix the config; do not stay here.The two dials, and what each one actually controls.
| Setting | Values | Controls |
|---|---|---|
sandbox_mode | read-only, workspace-write, danger-full-access | What Codex can do |
approval_policy | untrusted, on-request, never | When it has to ask |
They are independent, which is why the failure is confusing: you can have a permissive approval policy and still be blocked by the sandbox, and the message you see comes from the command that failed rather than from Codex explaining its own policy. As of August 2026 the default pairing in a version-controlled folder is workspace-write with on-request.
The network default
This is the single highest-traffic Codex complaint, and it is one line of configuration. In workspace-write, outbound network access is off unless you turn it on.
sandbox_mode = "workspace-write"
approval_policy = "on-request"
[sandbox_workspace_write]
network_access = true
writable_roots = ["/Users/you/.cache/pnpm"]codex -c sandbox_workspace_write.network_access=trueBilling and authentication
| Symptom | Cause | Fix |
|---|---|---|
| Charged per token despite a ChatGPT plan | Signed in with an API key, not the plan | codex logout, then codex login |
| Login never completes | No browser, or a proxy | codex login --device-auth |
| Asked to log in every launch | ~/.codex/auth.json not writable | Check ownership of ~/.codex |
401 after a while | Session expired | codex logout, then codex login |
| Works locally, fails on a server | No browser on the host | Device auth, or an API key |
| Signed in as the wrong workspace | Multiple ChatGPT workspaces | codex login status to confirm |
codex login status # the active method: ChatGPT sign-in, or an API key
codex logout && codex login
# headless box with no browser
codex login --device-auth
# or explicitly with a key, without leaving it in your shell profile
printenv OPENAI_API_KEY | codex login --with-api-keyWhere the sandbox actually comes from
The sandbox is not one implementation, and knowing which one you are on explains most of the platform-specific weirdness.
Sandbox enforcement by platform, as of August 2026.
| Platform | Mechanism | You need to |
|---|---|---|
| macOS | The built-in Seatbelt framework | Nothing. It works out of the box. |
| Linux and WSL2 | bubblewrap, plus kernel filtering | Install bubblewrap with your package manager |
| Windows, PowerShell | The native Windows sandbox | Nothing |
| Windows, WSL2 | The Linux implementation | Install bubblewrap inside the distribution |
sudo apt-get install bubblewrap # Ubuntu and Debian
sudo dnf install bubblewrap # Fedora
which bwrap # Codex uses the first bwrap on PATHEverything else
| Symptom | Check |
|---|---|
codex: command not found | New terminal, then PATH, then a moved Node prefix |
| Vanished after upgrading Node | npm global prefix moved. Reinstall, or use Homebrew. |
| Behaviour changed overnight | codex --version, then the release notes |
| Slow in WSL | The project is on /mnt/c. Move it. |
| MCP server missing | codex doctor reports stdio command resolution and permissions |
| Answers feel shallow on a hard task | model_reasoning_effort. Values run minimal to xhigh. |
| Need to see what it actually did | Turn on a log directory and tail it |
# log_dir defaults to $CODEX_HOME/log. Setting it explicitly also turns on
# the opt-in plaintext TUI log, codex-tui.log, in that directory:
codex -c log_dir=./.codex-log
tail -F ./.codex-log/codex-tui.log
# non-interactive mode prints its messages inline, so there is no file to watch
codex exec "run the test suite and summarise failures"Questions people ask
codex doctor. As of August 2026 it checks runtime, authentication, network reachability for the provider you are actually using, terminal environment, configuration, Git state, and MCP servers in one command, and codex doctor --json produces a redacted report you can attach to a bug report.
Because workspace-write disables outbound network access by default. Set network_access = true under [sandbox_workspace_write] in config.toml when you need it, or pass it for one run with codex -c sandbox_workspace_write.network_access=true.
The sandbox is probably read-only. Run with --sandbox workspace-write, or set sandbox_mode in config.toml. If it can write inside the project but not outside, that is workspace-write working correctly; add the path to writable_roots rather than removing the sandbox.
Run once with --sandbox danger-full-access --ask-for-approval never. If the failure disappears, it was policy rather than a defect. Then fix the configuration narrowly instead of staying without a boundary.
The session is authenticated with an API key rather than your ChatGPT sign-in, and OpenAI bills API key usage through your Platform account at standard API rates. Run codex login status to see the active method, then codex logout and codex login to sign in with ChatGPT. To pin a machine to one rail, set forced_login_method to chatgpt in config.toml.
Use codex login --device-auth, which completes the flow on another device. Alternatively pipe a key in with printenv OPENAI_API_KEY | codex login --with-api-key, or copy ~/.codex/auth.json from an already authenticated machine and treat it like a password.
Yes. In PowerShell it uses the native Windows sandbox, and in WSL2 it uses the Linux implementation, which needs bubblewrap installed inside the distribution. Codex prints a startup warning when it cannot enforce the sandbox, and that warning is worth reading rather than dismissing.
log_dir defaults to $CODEX_HOME/log, and setting it explicitly also turns on the opt-in plaintext TUI log. Start with codex -c log_dir=./.codex-log and tail ./.codex-log/codex-tui.log. Non-interactive codex exec prints its messages inline instead, and honours RUST_LOG.
Sources
Every figure above was read from these pages on August 2026. Vendors reprice without notice; if you find a stale number, tell us.