Troubleshooting Common Issues: Cannot Install, Cannot Log In, Won't Modify Files—Addressing Them One by One
📚 Series Navigation: The previous post [36 Best Practices] covers "how to use it right and smoothly," turning good habits into muscle memory. This post is the opposite—specifically diagnosing all kinds of friction: cannot install, cannot log in, it stubbornly refusing to edit your files, getting dumber mid-chat... breaking down common pitfalls one by one. The next post [38 Glossary] is the concluding dictionary of the Codex section for you to look up unfamiliar terms.
“Hey bro, I finished npm install, but when I type codex, it says command not found, what should I do?”
“My login is just spinning, the browser won't open, do I need a proxy?”
“It can read my code, but as soon as I ask it to modify a file, it throws an error saying the sandbox doesn't allow writing—I never set this thing up, though?”
These are the three most frequently asked questions in our groups over the past two years; almost someone runs into them every day. Frankly speaking, 90% of Codex issues are not bugs, but rather a misunderstanding of some default behavior—either lack of authentication, restricted permissions, or exhausted context. In this post, instead of piling up theories, I will address them one by one in the order you are most likely to encounter them, providing "Symptoms → Root Cause → Solution" for each, so you can troubleshoot them yourself.
After reading this post, you will get:
- A quick lookup of "Symptoms → Root Cause → Solution" for ten of the most frequent failures, ordered by real-world occurrence frequency
- Concrete solutions for the three major entry barriers: cannot install, cannot log in, and network spinning
- The truth about permissions behind "it won't modify files," and a single command to unlock it
- The criteria for deciding between
/compactor/newwhen the context is full and it gets dumber mid-chat - A universal troubleshooting checklist of "Check these three things first," helping you save yourself even when encountering unlisted new issues
⚠️ All specific commands, configuration options, and default behaviors mentioned below are based on the Codex official documentation; model names and version numbers may change with updates, so please refer to your local
codex --versionand the actual display in the/modelpanel. The permission-related solutions in this article are cross-referenced with the official Authentication and Permissions documentation, but permission profiles are marked by the official docs as Beta, subject to change.
01 Troubleshooting Mindset: Check These Three Things First, Before Talking Metaphysics
First, the conclusion: When encountering any Codex issue, do not rush to reinstall or replace it with other tools. First, verify three things in order—version, login, and permissions. Eighty percent of the problems are stuck at these three gates.
Analogy: Triage in a hospital. When you go to the ER, the nurse won't order a CT scan right away. Instead, they will first take your temperature, check your blood pressure, and ask where it hurts—ruling out major issues using three basic metrics. Troubleshooting Codex is the same: check the three "vital signs" first, then dive deeper:
# 1. 版本对不对、装没装上
codex --version
# 2. 登没登录、用的哪种认证
codex login status
# 3. 当前会话权限怎么配的（在交互界面里敲）
/statusThe first one tells you "whether it is installed and if it is too old"; the second tells you "whether authentication has dropped"; the third tells you "which tier the sandbox and approval are set to, and whether files can be written."
The habit I have developed is: Whenever anyone asks me about a Codex error, my first response is always "Send me the results of these three lines first." Eight times out of ten, the problem exposes itself while they are pasting the results—either the version is stuck half a year ago, or login status shows they aren't logged in at all.
💡 Summary in one sentence: Troubleshooting does not rely on metaphysics; first check the three vital signs of version, login, and permissions, then go deeper.
02 Cannot Install, Command Not Found
This is the first hurdle for beginners and has the highest dropout rate.
Symptoms: After npm install, typing codex returns command not found: codex in the terminal, or a bunch of red error messages appear halfway through installation.
Root Cause: Usually it is not the fault of Codex, but rather a configuration issue with your environment. The three most common causes are: the npm global bin directory is not in your PATH, the Node.js version is too old, or there are insufficient permissions for npm to write to the global directory.
Solution, try these in order of likelihood from highest to lowest:
- First, confirm the Node.js version. Type
node --version. If it's too old (for example, still stuck on a major version in the teens), many new tools simply won't install. If it is too low, upgrade Node.js first. command not foundis mostly becausePATHdoes not contain the npm global bin. Runnpm config get prefixto see where the global directory is, and make sure itsbinsubdirectory is in yourPATH.- A bunch of
EACCESpermission errors during installation indicates a lack of write permissions to the system directory. Do not usesudo npm install -gto force it—this will leave you with a host of permission pitfalls later. The correct way is to change the npm global directory to a location where you have permissions, or simply use Node.js installed via a version manager (like nvm). - If you want to avoid the hassle, don't use npm. The official Codex documentation also provides other installation methods; please refer to the installation guide corresponding to your platform. On a new Mac, to save trouble, when npm persistently threw permission errors, I switched to another method recommended by the official docs and got it done in three minutes.
Platform Differences: "Cannot install" for Windows users is often a different story (lacking WSL, path issues, etc.), which is discussed separately in [33 Windows Key Points] and will not be expanded here.
💡 Summary in one sentence:
command not foundis 80% likely due to the npm global bin not being inPATH; do not force installation with sudo for permission errors.
03 Login Failure, Authentication Expiry
Once installed, the second level is logging in.
Symptoms: After typing codex login, the browser does not pop up, or it pops up but fails to return to the terminal and keeps spinning; or while using it, you are suddenly prompted with "Unauthenticated" or "Session Expired," asking you to log in again.
Root Cause: Codex login defaults to a "browser callback"—it starts a temporary service locally on localhost:1455 and waits for the browser to send back the token. This step breaks in three scenarios: remote or headless machines without a browser, local network blocking this callback port, or your authentication cache is corrupted.
Solution:
- If the local machine is normal but just spins without returning, first confirm that the browser has indeed completed the login, and that
localhost:1455is not occupied or blocked by a firewall. - If you cannot log in in environments without a browser like servers, Docker, or SSH, the official preferred method is "Device Code Login" (device code, Beta):
codex login --device-authIt will give you a link and a one-time verification code. You can open the link on any machine with a browser, enter the code, and confirm, and then the terminal here will be authenticated. This is the easiest way for remote login.
- If the device code also fails, there is a workaround: run
codex loginon a machine that can log in normally, and then copy the cache file~/.codex/auth.jsonto the same path on the target machine. Note: This file stores the access token, which is equivalent to a password. Do not commit it to git, or paste it into support tickets or group chats. - "Losing login status during use": Codex login via ChatGPT will automatically refresh the token before it expires, so normally it should not drop frequently. If it does drop frequently, check the status via
codex login statusfirst, and if necessary, runcodex logoutfollowed bycodex loginto start over. The direct login logs will be written tocodex-login.log; refer to it when troubleshooting login issues.
| Your Environment | Recommended Login Method |
|---|---|
| Local machine has a browser | Directly codex login, run through the browser |
| Remote / Server / Headless | codex login --device-auth Device Code |
| Device code also fails | Log in locally and copy ~/.codex/auth.json over |
| Corporate TLS proxy / Private CA | Set CODEX_CA_CERTIFICATE to point to the PEM certificate first, then log in |
Last year, when configuring Codex on a headless server running CI, I foolishly ran codex login and waited for a browser to pop up, only realizing after five minutes that the machine had no desktop environment at all. I switched to codex login --device-auth, scanned the code and entered it on my phone, and it was done in twenty seconds. For remote machines, always prioritize device codes; don't fight with the browser.
💡 Summary in one sentence: Don't wait for the browser on remote machines;
codex login --device-authvia device code is the preferred choice.
04 Network Spinning, Do I Need a Proxy?
Symptoms: Long spinning times during login, conversation, or task execution, ultimately reporting a timeout or connection failure.
Root Cause: The Codex models reside on OpenAI servers, and direct connections from mainland China are highly unlikely to work. Additionally, corporate TLS proxies and private CA certificates may also cut off the connection.
Solution:
- Users in China generally need a proxy/VPN. This cannot be bypassed—Codex must connect to OpenAI services, and if the network is down, nothing can be done. Make sure your proxy is global or effective for the relevant domains; if you only open a browser extension and the terminal does not route through the proxy, it will still spin.
- Confirm that the terminal layer goes through the proxy. Many people assume everything is fine because their browser can access the internet, but Codex in the terminal doesn't route through the proxy. Set the appropriate
HTTP_PROXY/HTTPS_PROXYenvironment variables, or use a proxy tool in global mode. - If the corporate network uses a corporate TLS proxy or a private root CA, direct connection will break due to certificate verification failure. The official solution is to set an environment variable pointing to your PEM certificate bundle:
export CODEX_CA_CERTIFICATE=/path/to/corporate-root-ca.pem
codex loginWhen CODEX_CA_CERTIFICATE is not set, it will fall back to SSL_CERT_FILE. This custom CA set is effective for login, regular HTTPS requests, and encrypted WebSocket connections.
For a while, when I was on the corporate intranet, my browser could access ChatGPT, but Codex simply couldn't connect. After messing around for half a day, I discovered that the company's TLS man-in-the-middle proxy had replaced the certificates. Once I set CODEX_CA_CERTIFICATE to point to the root certificate provided by IT, it worked instantly. Keep in mind: "Browser can access the internet ≠ Codex can access the internet."
💡 Summary in one sentence: A proxy is generally needed in China, and the terminal must route through it; use
CODEX_CA_CERTIFICATEto save the day for corporate private CAs.
05 Wrong Model Selection, Cannot Find a Specific Model
Symptoms: You cannot see a model mentioned by others in the /model panel; or you configured a specific model name but startup throws an error saying "Model does not exist / is unavailable."
Root Cause: The models you can choose from depend on your login method (ChatGPT subscription vs. API key) and plan; some models are research previews limited to specific plans; in addition, several older models have been deprecated by the official providers.
Solution:
- Rely on what is actually listed in the
/modelpanel; don't memorize names. In the current system, the flagship default isgpt-5.5, and the lightweight one used for sub-agents isgpt-5.4-mini. Almost all accounts have access to these two. - It is normal if you don't see
gpt-5.3-codex-spark—it is a real-time research preview currently open only to ChatGPT Pro subscriptions; not having it does not mean you installed something incorrectly. - If you wrote a model in the configuration but it reports as unavailable, check your
~/.codex/config.tomlandcodex exec --modelparameters to see if you are still using deprecated old names (such asgpt-5.2orgpt-5.3-codex). These two have been deprecated under the ChatGPT login method, so switch to the latest ones. - If you want to confirm which model is currently in use, run
/statusin the session to check; don't go by feeling.
💡 Summary in one sentence: Available models depend on the login method and plan; always refer to the actual list in the
/modelpanel, and do not memorize names.
06 Blocked Permissions, Sandbox Won't Allow File Modifications
This is the root cause of "can read, cannot modify" issues, and it is the category that confuses beginners the most.
Symptoms: Codex can read code and write analyses fine, but as soon as you ask it to modify a file or run a write command, it errors out saying the sandbox does not allow it, or pops up a window at every step asking for your approval.
Root Cause: This is not a bug, but a default security design. Codex will not blindly modify files on your machine by default—it runs commands in a sandbox where write permissions are restricted by default; when touching areas outside the workspace or attempting network access, it will also pause to ask for your approval. If you feel "blocked," it is actually protecting you according to the default principle of least privilege.
Analogy: A rented apartment. The landlord (the default configuration of Codex) only gives you "viewing" permissions by default—walls cannot be knocked down, and furniture cannot be replaced. If you want to renovate, you must first sign a clear agreement with the landlord defining the "modifiable scope." It is not trying to make things difficult for you; it is just that without your explicit authorization, it does not dare to move things.
Solution, split into two paths:
- To grant temporary access once, use command-line parameters. Use
--sandbox(short for-s) for the sandbox, and--ask-for-approval(short for-a) for approvals. If you want it to edit freely within the current project and only prompt you when going outside the project, use the daily golden combination of "workspace write + on-request approval":
codex --sandbox workspace-write --ask-for-approval on-requestMore values and combinations are covered in depth in [15 Permissions, Sandbox, and Approvals], which won't be repeated here.
- To make it the long-term default, write it to
~/.codex/config.toml. The new permission profiles (Beta) provide three built-in profiles:
| Built-in Profile | What It Can Do | Applicable Scenarios |
|---|---|---|
:read-only | Read-only; executed commands are never allowed to write | Let it purely read code and generate analyses without touching files |
:workspace | Writable to workspace and system temp directories, read-only elsewhere | Daily development, freely modifying the current project |
:danger-full-access | Remove local sandbox restrictions | Use only in isolated containers; do not use on the host machine |
Set default_permissions to your desired profile name. Note a pitfall explicitly stated by the official docs: permission profiles and the old sandbox_mode settings cannot be mixed—as long as sandbox_mode appears in any configuration file or you pass --sandbox, Codex will use the old set, and the new permission profile will not take effect. Choose one of the two; do not write both.
Last winter, to save trouble, I directly ramped up permissions to full access in the global config.toml. As a result, when I asked it to "clean up unused files" in a temporary directory that hadn't initialized git, it almost turned my home directory upside down—the full access level is only suitable for isolated containers; making it a global default is setting a trap for yourself.
💡 Summary in one sentence: "Won't modify files" is the default safety protecting you; use
-s/-atemporarily, write toconfig.tomllong-term, and do not mix old and new permission settings.
07 MCP Connection Failures
Symptoms: You configured an MCP (Model Context Protocol) server, but you cannot see its tools in Codex, or it reports a connection failure at startup.
Root Cause: The MCP service is an independent process, and Codex starts/connects to it via defined methods. Connection failure is usually due to a few reasons: incorrect startup command, uninstalled dependencies, missing required environment variables (like a specific API key), or network/permission settings blocking its outbound requests.
Solution:
- First, run that MCP service independently. Step away from Codex, run the startup command directly in the terminal according to its documentation once, and see if it can run and what errors it throws. Nine times out of ten, the problem is exposed at this step—incorrect command path, missing dependencies, or missing environment variables.
- Check the MCP configurations in
config.toml. Align startup commands, arguments, and environment variables field by field; don't just settle for "looking similar." A missing key or a single typo in a path will prevent connection. - If the MCP service needs internet access, make sure the permission profile opens the network. The default sandbox network is disabled, meaning its outbound requests will be blocked.
- If it still cannot connect, check the Codex logs to locate whether it is "failed to start" or "started but handshake failed." Debugging MCP connections is essentially the same as debugging other external services: first verify the process is running, then check communication.
The concept of MCP as a USB port was explained in [20 MCP], so we only focus on troubleshooting here. I stuck for half an hour configuring my first MCP, only to find that I had missed an environment variable—running that service independently is ten times more effective than staring blankly at Codex.
💡 Summary in one sentence: If MCP fails to connect, run that service independently outside of Codex first, and the problem will usually manifest itself immediately.
08 Context Overflow, Getting Dumber Mid-Chat
Symptoms: After chatting in a session for too long, Codex starts to suffer from "amnesia"—forgetting agreements made earlier, repeating mistakes that were just corrected, and giving increasingly off-base answers.
Root Cause: Each session has a context window limit, which acts as its "short-term memory" capacity. Chatting too long and packing in too much content pushes older information out, naturally making it "forget things" and become less smart.
Analogy: A fully written whiteboard. A whiteboard is only so big; once filled, writing new things requires erasing old ones. It is not becoming stupid; its old memories are simply being displaced by new content.
Solution, the key is distinguishing between "compressing" and "restarting":
- If the task is not yet finished, but the chat is too long and starting to drift, use
/compact. It compresses the current conversation into a summary, freeing up tokens while preserving key information as much as possible. Suitable for "this task still needs work, but the history is too long." - To switch to a brand new task without contamination from old context, use
/newto start a clean conversation in the same CLI session, or/clearto reset both the interface and the conversation. The difference is:/newdoes not clear the screen, allowing you to scroll up to view historical output;/clearclears the terminal view while starting a new conversation. - Regularly use
/statusto check the remaining context capacity; don't wait until it starts getting dumb to react. My current habit for a long task is to glance at/statusevery once in a while, and proactively run/compactif not much is left, rather than chatting on until it starts talking nonsense.
| Your Situation | Which to Use |
|---|---|
| Current task not done, but chat is too long and starting to drift | /compact to compress summary, retaining key information |
| Switching to a brand new task, wanting to avoid bias from old context | /new to start a clean conversation |
| Want to thoroughly reset both the interface and conversation | /clear to clear all |
| Want to check the remaining capacity first | /status to check remaining context |
💡 Summary in one sentence: Getting dumber mid-chat means the context is full; use
/compactif not done, and/newwhen switching tasks; don't push through until it talks nonsense.
09 Cost / Quota Exceeded
Symptoms: Subscription plan prompts that quota is exhausted, leading to temporary rate limiting; or when using an API key, the bill is higher than expected.
Root Cause: The two billing methods are worlds apart—ChatGPT Subscription draws from within-plan quotas, rate limiting when reaching limits and refreshing periodically; API key bills directly by usage—the more you run, the stronger the model, and the heavier the reasoning, the faster it burns.
Solution:
- If the subscription is rate-limited, either wait for the quota to refresh or upgrade the plan. The key to daily quota saving is not to default to the maximum—use
gpt-5.4-miniwith low reasoning intensity for simple jobs, saving flagship models and high reasoning for the real tough nuts. This strategy is covered in depth in [30 Model Selection]. - If the API key bill exceeds expectations, first check if the selected model is too heavy or if the reasoning effort (
model_reasoning_effort) is cranked up too high. Using a flagship model withxhigheffort to fix a typo is as expensive as driving an excavator to weed grass. Adjusting reasoning effort based on task difficulty (minimal/low/medium/high/xhigh) will immediately lower your bill. For long-term changes, setmodel_reasoning_effort = "medium"in~/.codex/config.toml; for a temporary override for a single run, use-c model_reasoning_effort=medium. - Delegate batch tasks to sub-agents + lightweight models. For numerous simple jobs (e.g., bulk renaming files, clearing expired imports), the speed and cost advantages of mini will shine.
I once locked the default reasoning effort at xhigh for convenience, only to find that my API bill for the month was much higher than usual, spent entirely on a bunch of small tasks that should have been answered in seconds. Tuning the right model and reasoning effort is more effective than any cost-saving trick.
💡 Summary in one sentence: Spend within plan limits for subscriptions; lower the model and reasoning effort if the API exceeds budget, and don't max out for simple tasks.
10 Windows-Exclusive Pitfalls, and "How to Revert If It Makes a Mistake"
Finally, two categories: one platform-exclusive, and one everyone will encounter sooner or later.
Windows-Exclusive Issues
Symptoms: Path errors, sandbox behaviors differing from tutorials, or certain functions being restricted on native Windows.
Root Cause: The sandbox model of Codex on macOS / Linux is not exactly the same as on native Windows, with differences in paths, permissions, and network isolation.
Solution: For the closest Linux experience on native Windows, the official recommendation is to use WSL (Windows Subsystem for Linux). Exclusive pitfalls such as Windows installation, paths, and WSL configurations are covered collectively in [33 Windows Key Points]; go directly to that post to look up issues with a Windows flavor rather than trying blindly here.
How to Revert If It Makes a Mistake
Symptoms: Codex modifies things heavily, but ends up breaking or drifting them, and you want to revert.
Root Cause: Modifications made by Codex are applied directly to actual files, and it does not automatically back up files for you.
Solution, ordered by reliability:
- First choice: rely on git. This is why I repeatedly stress running a clean
git commitbefore letting Codex work. If it breaks something, usegit diffto see what it changed, and then usegit restore(orgit checkout) to revert files to the last commit. git is your most solid safety net. - For temporary directories not using git, there really is no elegant way back—which is why [36 Best Practices] lists "commit first, then let go" as an ironclad rule.
- Tighten permissions before making changes. If you are afraid of it making chaotic modifications, use
:read-onlyto let it propose a solution first, and only grant write access once you confirm; this is much more proactive than trying to patch things up afterwards.
I once learned the hard way by letting Codex make major modifications without committing first: it refactored a function beautifully, but also touched three files I didn't want it to touch. Since they weren't committed, I had to manually revert them one by one, losing half an hour. Ever since then, "commit first before letting it start" has become my unshakeable starting ritual.
💡 Summary in one sentence: Look up Windows pitfalls in [33 Windows]; to be able to revert at any time, the only reliable way is to
git commitbefore starting.
Summary
This article broke down ten of the most frequent Codex failures one by one. To sum it up in one sentence: Most cases of "friction" are not because Codex is broken, but because a certain default behavior is not understood.
Let's review the tools you have in hand now:
- Check three vital signs when in trouble:
codex --version,codex login status, and/status. Eighty percent of issues are stuck on version, login, or permissions. - Three entry barriers: Installation issues are mostly due to the npm global bin not being in
PATH; remote logins should usecodex login --device-auth; a proxy is generally required in China, and the terminal must route through it. - "Won't modify files" is the default security; use
-s/-atemporarily, write toconfig.tomlfor the long term, and do not mix old and new permission settings. - Getting dumber mid-chat is due to full context; use
/compactif not done, and/newwhen switching tasks. - If costs are exceeded, lower the model and reasoning effort first; rely on
git restorefor mistakes, provided you commit before starting.
Now you should be able to: face a Codex error without being completely in the dark, but instead locate and troubleshoot it yourself based on "Symptoms → Root Cause → Solution"—even when encountering new issues not listed in this post, you can save yourself using the "check the three vital signs first" approach.
The next article [38 Glossary] is the conclusion of the entire Codex section—compiling the terminology that appeared along the way (sandbox, approvals, reasoning effort, MCP, sub-agents, codex exec...) into a dictionary searchable by alphabet/pinyin, which you can look up whenever you get terms mixed up. Here is a small food for thought before you leave: among all the solutions in this article, several actually point to the same habit—think through your "retreat path" and "permissions" before starting. Can you count which ones they are?