Codex not working? Fixes from OpenAI's docs, step by step

If Codex is not working, start with three checks: whether OpenAI has an incident, whether you are signed in, and whether you are on a current version. Most problems come down to one of those. This guide covers the fixes that OpenAI's own docs and the Codex repository describe, for the CLI, the desktop app and the IDE extension.

OpenAI's docs do not list every error message. Where a fix is not documented, this guide says so instead of guessing.

Check whether Codex is down first

Open status.openai.com. It lists Codex Web, Codex API, the CLI and the VS Code extension as separate components. When we checked on November 3, 2026, the page showed no active incidents and 99.94% uptime for each of the four. If one shows an incident, wait. Nothing on your machine will fix it.

Sign in again

The most common local fix is a fresh login. From the Codex auth docs:

codex login status    # shows the active sign-in method
codex logout          # clears stored credentials
codex login           # opens the browser flow

The CLI and the IDE extension share cached login details. Logging out of one signs you out of the other.

Two sign-in methods exist. Sign in with ChatGPT uses your subscription, and Codex cloud requires it. An API key uses usage-based billing and limits features that depend on a ChatGPT workspace or cloud services. If a cloud feature is missing, check that you did not sign in with an API key.

To log in with an API key from the command line:

printenv OPENAI_API_KEY | codex login --with-api-key

Fix login on a remote or locked-down machine

If the browser login fails, the docs give three options, in this order:

1. Run codex login --device-auth, open the link and enter the one-time code. This is in beta, and your ChatGPT security settings or workspace permissions must allow it.
2. Log in on a machine with a browser, then copy ~/.codex/auth.json to the other machine. Treat that file like a password, because it holds access tokens.
3. Forward the callback port over SSH with ssh -L 1455:localhost:1455 user@remote, then run codex login in that session.

Behind a corporate TLS proxy, set CODEX_CA_CERTIFICATE to a PEM bundle before logging in. If it is unset, Codex falls back to SSL_CERT_FILE. If login still fails, read codex-login.log in your log directory.

One more case: if forced_login_method or forced_chatgpt_workspace_id does not match your credentials, Codex logs you out and exits. That setting usually comes from an admin.

Update or reinstall Codex

The CLI page says to update by running the same installer again. On macOS and Linux:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

The Codex repository lists other methods: npm install -g @openai/codex, brew install --cask codex, a PowerShell installer on Windows, or a binary from GitHub Releases. If the installer fails to download, the standalone installers use releases.openai.com by default and fall back to GitHub Releases. Set CODEX_INSTALLER_USE_RELEASES_OPENAI_COM=false to go straight to GitHub.

Check the install guide for requirements: macOS 12 or newer, Ubuntu 20.04 or Debian 10 or newer, or Windows 11 through WSL2, with at least 4 GB of RAM and 8 GB recommended. For a step-by-step install, see our guide on how to install Codex.

When the app works differently from the CLI

The desktop app and the CLI can ship different versions. If a feature works in one and not the other, compare versions with codex --version. On macOS the app's bundled copy is at /Applications/Codex.app/Contents/Resources/codex --version.

When a chat is stuck

OpenAI's troubleshooting page suggests three steps:

1. Check whether Codex is waiting for an approval.
2. Run a basic command such as git status in the terminal.
3. Start a new chat with a smaller, more focused prompt.

If the built-in terminal hangs, close the panel, reopen it with Ctrl+, and run pwdorgit status`. If it stays stuck, wait for active chats to finish and restart the app.

Code that runs in your project but fails in a worktree is a known case. Worktrees live in a different directory and inherit only Git-tracked files. Run setup through a local environment, or copy ignored files with .worktreeinclude.

Read the logs

Set log_dir in ~/.codex/config.toml to get a plaintext log named codex-tui.log. For one run, use:

codex -c log_dir=./.codex-log

Codex also honors RUST_LOG. App logs on macOS are in ~/Library/Logs/com.openai.codex/, and session transcripts are in ~/.codex/sessions. Review logs for sensitive data before sharing them.

Still stuck

Search the open issues for your error text, or file a new bug report. In the app, typing / in the composer sends feedback with your session attached. If you are also wondering what you can inspect or change in the tool itself, see is Codex open source.