Kipt

Your prompts and skills, one keystroke away.

Explore

Codex not working? Fixes for install, login, sandbox and more

Codex not working? Documented fixes for command not found, sign-in failures, startup errors after updates, retired models, network blocks, Windows, WSL and MCP.

By the Kipt team · Updated 26 October 2026

When Codex is not working, run codex doctor first. It checks your installation, configuration, sign-in, runtime, Git and terminal and tells you which part is broken. If the report is clean, match your symptom below. Common causes include a PATH issue, a sign-in that can't complete, a setting your new version no longer accepts, a retired model, or the sandbox blocking the network.

Every fix here comes from OpenAI's Codex docs on learn.chatgpt.com and the openai/codex repository, read on 26 October 2026. The latest CLI release that day was 0.164.0.

Where should you start when Codex isn't working?

Run these in order:

codex --version          # which version you are on
codex doctor             # full health report (add --summary for a short one)
codex login status       # which sign-in method is active
codex update             # update, if your install supports self-update

Then, inside a session:

  • /status shows the active model, approval policy, writable roots and remaining context.
  • /debug-config shows which config layer set each value, which explains most "my setting is ignored" problems.
  • /warnings shows warnings from earlier in the session.

If a feature works in the CLI but not the ChatGPT desktop app, or the other way round, they may be on different Codex versions. Features can reach one surface before the other. Compare codex --version with the version bundled in the app (on macOS, /Applications/Codex.app/Contents/Resources/codex --version).

How do you fix "command not found" and install problems?

Problem Fix
codex: command not found after the standalone installer The installer puts codex in ~/.local/bin on macOS and Linux, or %LOCALAPPDATA%\Programs\OpenAI\Codex\bin on Windows. Add it to PATH and open a new terminal. CODEX_INSTALL_DIR changes the location
The installer can't download It fetches from releases.openai.com and falls back to GitHub Releases. Set CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false to force GitHub
VS Code in WSL can't find codex Run which codex inside WSL. If it's missing, install the CLI inside WSL with the install script
You're on an old version Update the same way you installed: rerun the install script, npm install -g @openai/codex, or brew upgrade --cask codex

OpenAI's Codex CLI page lists every install method. The Codex CLI guide walks through setup.

How do you fix Codex sign-in problems?

Codex signs you in through a browser by default. When that fails:

  • Remote machine, SSH or container. Use device code login: codex login --device-auth, or choose Sign in with Device Code in the login screen. You must first enable device code login in your ChatGPT security settings, or your workspace admin must allow it.
  • Device code isn't available. Forward the login callback with ssh -L 1455:localhost:1455 user@remote, then run codex login in that session. Or sign in on a machine with a browser and copy ~/.codex/auth.json to the same path on the remote one.
  • Corporate proxy or private root CA. Set CODEX_CA_CERTIFICATE to your PEM bundle before codex login. It covers login, HTTPS and WebSocket traffic.
  • Codex logs you out and exits. Your admin may enforce forced_login_method or a specific workspace, and your credentials don't match. Sign in with the required method.
  • Wrong account or a stuck session. Run codex logout, then codex login.

Direct codex login runs write a codex-login.log in your log folder, which helps with browser or device code failures. Treat ~/.codex/auth.json like a password: it holds access tokens. Details are on OpenAI's authentication page.

Why won't Codex start after an update?

Recent releases retired or moved some settings. OpenAI says the first one below can stop Codex from starting. Check your config.toml, profile files and startup scripts for:

  • approval_policy = "untrusted". No longer supported, and OpenAI says it "can prevent either client from starting." Remove it. For read-only work, use sandbox_mode = "read-only" with approval_policy = "on-request". Marking a project trust_level = "untrusted" is still fine.
  • Profiles under [profiles.name]. If --profile seems ignored, move the profile to its own file, ~/.codex/<name>.config.toml, with top-level keys rather than a [profiles.name] table.
  • wire_api = "chat" on a custom provider. No longer supported: responses is the only accepted value. Point the provider at a compatible Responses API endpoint.
  • experimental_instructions_file. Deprecated; rename it to model_instructions_file.

The Codex config guide shows a current, valid file.

Why does Codex say a model isn't available?

The model in your config or script has probably retired. With ChatGPT sign-in, gpt-5.5 retired from Codex on 14 October 2026, gpt-5.3-codex-spark on 14 September, and gpt-5.4 and gpt-5.4-mini on 31 August. gpt-5.2 and gpt-5.3-codex are deprecated.

Replace the ID with one your plan offers, usually gpt-6.1-sol on paid plans or gpt-6-luna on Free and Go, and check scripts that pass --model. API-key sessions aren't affected. If a current model is missing from /model, your plan or workspace doesn't include it; on Enterprise and Edu an admin must enable new models. The Codex models guide has the full list.

Why can't Codex reach the network, edit files or commit?

These are often the sandbox working as designed, not a bug:

  • No network. In the CLI, IDE extension and app, commands run with network access off by default. Approve the request when Codex asks, or enable it for workspace-write mode:
[sandbox_workspace_write]
network_access = true
  • git commit needs approval. In workspace-write mode, .git is read-only, and so are .agents, .codex and .aws when they exist. Approve the commit or run it yourself.
  • Codex asks before editing another folder. Grant that folder with --add-dir rather than switching to full access.
  • codex exec refuses to run. It requires a Git repository. Use --skip-git-repo-check only if the folder is safe.
  • Project settings, hooks or rules are ignored. Untrusted projects skip their .codex/ layers. Trust the project, then check /debug-config.

The approvals and sandbox guide explains each mode.

How do you fix Codex on Windows and WSL?

Codex on Windows prefers the MXC sandbox where the device and policy support it (prefer_mxc = true under [features]), with elevated and unelevated as legacy fallbacks. OpenAI's Windows sandbox page covers these errors:

Problem Fix
Elevated sandbox setup fails Usually a declined admin prompt or a policy blocking local users, firewall rules or logon rights. Retry and approve, ask IT, or use unelevated if policy allows
Windows error 1385 Policy denies the sandbox users' logon type. Ask IT to grant the logon rights; use unelevated meanwhile
Warning that folders are writable by Everyone Remove Everyone write access from the listed folders and restart Codex
npm.ps1 cannot be loaded because running scripts is disabled PowerShell execution policy. A common fix is Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
IDE extension installed but unresponsive Install Visual Studio Build Tools (C++ workload) and the Visual C++ Redistributable, then restart VS Code
Git features missing in the app Install Git: winget install Git.Git

For WSL: WSL1 stopped being supported in Codex 0.115, so use WSL2. Keep repos under your Linux home, not /mnt/c, for speed. The CLI in WSL uses its own ~/.codex; to share config, sign-in and sessions with the Windows app, set CODEX_HOME=/mnt/c/Users/<windows-user>/.codex. Logs for sandbox problems are in CODEX_HOME/.sandbox/sandbox.log.

Why is the IDE extension or desktop app misbehaving?

  • Environment variables are missing. Desktop apps and IDE extensions may not inherit your shell's variables. Put them in ~/.codex/.env and restart.
  • The review panel shows changes Codex didn't make. It reflects your Git state. Switch to the Last turn view.
  • Code doesn't run in a worktree. By default, worktrees only get files checked into Git. Add a setup script or copy ignored files with .worktreeinclude.
  • A chat looks stuck. Check whether it's waiting for an approval, run git status in the terminal, then start a new chat with a smaller prompt.
  • A prompt vanished after picking the wrong target. Cancel and press the up arrow in the composer to recover it.

The Codex IDE extension guide and Codex app guide cover setup.

Why won't an MCP server load?

Run /mcp verbose for server diagnostics, and /mcp login <name> if the server needs OAuth. MCP servers get 10 seconds to start and 60 seconds per tool call by default. Raise them per server with startup_timeout_sec and tool_timeout_sec. A server marked required = true that fails to start stops the session from starting, and makes codex exec exit with an error. The Codex MCP guide has config examples.

What happens when you hit your usage limit?

Check /status in the CLI, or the usage dashboard linked from OpenAI's Codex pricing page. If you reach your limit during an active turn, OpenAI says the agent can finish that turn, subject to fair use limits. After that, Plus and Pro users can buy credits, Business, Edu and Enterprise workspaces with flexible pricing can buy workspace credits, and anyone can keep working locally with an API key at API rates. Lighter models stretch your allowance much further; see the Codex pricing guide.

How do you report a Codex bug?

  1. Search existing issues on GitHub, and add to a matching one.
  2. Run /feedback to send logs to the maintainers. You get a session ID to share.
  3. Attach codex doctor --json, a redacted report.

For deeper logs, run codex -c log_dir=./.codex-log and read ./.codex-log/codex-tui.log, or set RUST_LOG=debug. Session transcripts are in ~/.codex/sessions, and macOS app logs are in ~/Library/Logs/com.openai.codex/. Review logs for secrets before you share them.

Keep your setup safe while you fix things

If you are tempted to delete ~/.codex and start fresh, back it up first: it holds your config, sign-in and saved sessions. Kipt keeps your prompts and Agent Skills as Markdown in a private GitHub repo you own, so a reinstall is one command: npx skills add https://github.com/<you>/<repo>.git --all -g. The free SKILL.md generator turns a prompt into a skill in the browser.

Questions

How do I check what is wrong with my Codex install?

Run codex doctor. It writes a local diagnostic report covering installation, configuration, authentication, runtime, Git, terminal, app-server and thread inventory health. Add --summary for a short version or --json for a redacted report you can attach to a support issue.

Why does my terminal say codex: command not found?

The folder the installer used is not on your PATH. The standalone installer puts codex in ~/.local/bin on macOS and Linux, or %LOCALAPPDATA%\Programs\OpenAI\Codex\bin on Windows, unless you set CODEX_INSTALL_DIR. Add that folder to PATH, open a new terminal and run codex --version.

Why won't Codex start after I updated it?

A common cause is a setting your new version no longer accepts. approval_policy = "untrusted" is retired and can stop Codex from starting, profiles now live in separate ~/.codex/<name>.config.toml files, and custom providers must use the Responses API. Remove or update the setting and start Codex again.

Why does Codex say my model isn't available?

Several models retired from Codex for ChatGPT sign-in in 2026: gpt-5.5 on 14 October, gpt-5.3-codex-spark on 14 September, and gpt-5.4 and gpt-5.4-mini on 31 August. Replace the old ID in config.toml, profiles and scripts with one your plan offers, such as gpt-6.1-sol or gpt-6-luna.

How do I sign in to Codex on a remote server or over SSH?

Run codex login --device-auth and enter the one-time code in a browser on any device. Device code login must first be enabled in your ChatGPT security settings or workspace permissions. Alternatives are forwarding port 1455 over SSH or copying ~/.codex/auth.json from a machine where you signed in.

Why can't Codex install packages or reach the internet?

In the CLI, IDE extension and desktop app, Codex runs with network access off by default. Approve the request when Codex asks, or turn it on for workspace-write mode with network_access = true under [sandbox_workspace_write] in config.toml.

More in Codex

All guides

Keep your prompts and skills in one place, in your own GitHub. Install every skill with one command.

Get started

Kipt is an independent product, not affiliated with or endorsed by Anthropic, OpenAI, Cursor or GitHub. Claude, ChatGPT, Codex, Cursor and GitHub are trademarks of their owners.