Codex 在 Windows 中的常见问题大全：安装、登录、网络、权限、PATH、WSL、报错完整排查指南

在这里插入图片描述

Codex 在 Windows 上现在已经可以原生使用。

截至 2026 年 8 月，官方已经提供 Windows PowerShell 安装脚本，因此以前网上很多“Codex Windows 必须通过 WSL 安装”的教程已经过时。

官方目前提供的 Windows 安装方式是：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

也仍然可以使用 npm：

npm install -g @openai/codex

安装完成后：

codex

即可启动。

但是 Windows 环境比 macOS / Linux 更复杂，因为还涉及：

PowerShell
Windows Terminal
PATH 环境变量
npm 全局目录
Node.js
Git
Windows Defender
企业安全软件
Windows Sandbox
UAC 权限
WSL
系统代理
本地代理
DNS
TLS
Codex Desktop
Codex CLI
VS Code / Cursor 插件

因此出现问题时，不要看到报错就直接重装。

这篇文章整理一套完整的 Windows Codex 排错思路。

一、首先搞清楚：你用的是哪个 Codex？

现在很多新手最容易混淆这一点。

Codex 至少有几种不同使用方式。

1. Codex CLI

终端里执行：

codex

这种就是：

Codex CLI

它直接运行在 Windows Terminal、PowerShell、CMD 或 WSL 中。

2. Codex Desktop App

Windows 桌面应用。

这种情况下你直接点击 Windows 里的 Codex 应用启动。

它不是简单的一个 PowerShell 窗口。

3. IDE 中的 Codex

例如：

VS Code
Cursor
Windsurf

里面安装 Codex 扩展。

4. Codex Web

浏览器中使用：

chatgpt.com/codex

所以遇到问题时，第一件事就是先搞清楚：

问题发生在：

CLI？
Desktop？
IDE？
还是 Web？

后面的排查方法完全可能不同。

二、Windows 推荐安装 Codex 的方式

现在 Windows 已经有官方安装脚本。

三、第二种安装方式：npm

如果电脑已经安装 Node.js，也可以：

npm install -g @openai/codex

安装完成检查：

codex --version

例如：

codex-cli 0.xxx.x

注意：

Codex 更新很快，版本号不要完全照抄网上教程。

判断是否安装成功应该执行：

codex --version

而不是判断：

是不是某个固定版本

四、安装完执行 codex 提示找不到命令

这是 Windows 上最常见的问题之一。

例如：

codex : 无法将“codex”项识别为 cmdlet、函数、脚本文件或可运行程序的名称

英文：

codex : The term 'codex' is not recognized as the name of a cmdlet,
function, script file, or operable program.

或者 CMD：

'codex' is not recognized as an internal or external command,
operable program or batch file.

核心含义只有一个：

Windows 找不到 codex

五、先判断 Codex 到底有没有安装

执行：

Get-Command codex

或者：

where.exe codex

正常情况下会返回：

C:\Users\xxx\...

如果没有任何返回：

说明当前 PATH 中找不到 Codex。

六、检查 Codex 版本

执行：

codex --version

如果成功：

codex-cli x.x.x

说明 CLI 基本安装正常。

如果失败，就继续向下排查。

七、为什么刚安装完 Codex，却提示命令不存在？

很常见的原因是：

环境变量已经修改
但是当前 PowerShell 还没有重新加载

最简单的处理：

关闭：

PowerShell
Windows Terminal
VS Code
Cursor

然后重新打开。

再次执行：

codex --version

很多时候就好了。

八、检查 PATH

PowerShell：

$env:Path

为了方便阅读：

$env:Path -split ";"

检查里面是否有 Codex 或 npm 的安装目录。

九、npm 安装的 Codex 在哪里？

查看 npm 全局目录：

npm root -g

或者：

npm prefix -g

然后：

where.exe codex

例如可能出现：

C:\Users\你的用户名\AppData\Roaming\npm\codex
C:\Users\你的用户名\AppData\Roaming\npm\codex.cmd

如果 npm 安装成功，但：

where.exe codex

查不到，就很可能是：

npm 全局 bin 目录没有加入 PATH

十、快速检查 Node、npm 和 Codex

执行：

node -v
npm -v
codex --version

三个都正常，基础环境才算完整。

十一、npm 本身都找不到

报错：

npm : The term 'npm' is not recognized

或者：

'npm' is not recognized as an internal or external command

说明问题根本不在 Codex。

而在：

Node.js / npm

检查：

node -v

如果 Node 也找不到：

需要先正确安装 Node.js。

十二、安装 Codex 报 PowerShell ExecutionPolicy 错误

可能出现：

running scripts is disabled on this system

或者：

cannot be loaded because running scripts is disabled

这是 PowerShell 执行策略。

查看：

Get-ExecutionPolicy

查看所有作用域：

Get-ExecutionPolicy -List

官方安装命令本身已经使用：

-ExecutionPolicy ByPass

例如：

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

所以一般不需要永久修改整台电脑的执行策略。

十三、PowerShell 安装脚本下载失败

可能出现：

Invoke-RestMethod

失败。

例如：

Unable to connect to the remote server

或者：

The request was aborted

或者：

Could not create SSL/TLS secure channel

这种问题通常不是 Codex 安装器本身。

而是：

网络
TLS
代理
DNS
证书
PowerShell 版本

十四、老 PowerShell 的 TLS 问题

部分 Windows PowerShell 5.1 环境可能因为 TLS 配置导致：

irm

下载失败。

可以先：

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

然后再执行：

irm https://chatgpt.com/codex/install.ps1 | iex

如果公司网络存在：

SSL inspection
HTTPS inspection
企业代理
自签证书

也可能导致类似问题。

十五、强制使用 GitHub Releases 安装

Codex 官方 Windows 安装器目前优先通过：

releases.openai.com

获取文件，同时可以回退到 GitHub Releases。

如果当前网络无法访问 OpenAI Releases，可以尝试：

$env:CODEX_INSTALLER_USE_RELEASES_OPENAI_COM='false'
irm https://chatgpt.com/codex/install.ps1 | iex

这样可以让安装器走 GitHub Releases。

十六、下载安装速度特别慢

重点测试：

curl.exe -I https://chatgpt.com

然后：

curl.exe -I https://releases.openai.com

也可以：

Test-NetConnection chatgpt.com -Port 443

如果连接失败：

优先排查网络，而不是一直重装 Codex。

十七、安装报错：Unsupported architecture

可能出现：

Unsupported architecture

当前 Codex Windows 安装器会检测系统架构。

目前主要支持：

Windows x64
Windows ARM64

同时要求：

64 位 Windows

可以检查：

[Environment]::Is64BitOperatingSystem

以及：

$env:PROCESSOR_ARCHITECTURE

十八、怎么查看 Windows 架构？

执行：

Get-CimInstance Win32_OperatingSystem |
Select-Object OSArchitecture

或者：

systeminfo

十九、安装了两个 Codex，版本乱了

这是 Windows 上非常值得注意的问题。

例如：

你以前：

npm install -g @openai/codex

后来又执行：

irm https://chatgpt.com/codex/install.ps1 | iex

结果电脑上可能有：

npm Codex
Standalone Codex
Desktop bundled Codex

不同版本。

先执行：

where.exe codex

如果返回多个路径：

例如：

C:\Users\xxx\AppData\Roaming\npm\codex.cmd
C:\Users\xxx\.codex\...\codex.exe

说明你确实存在多个版本。

二十、到底执行的是哪个 Codex？

PowerShell：

Get-Command codex | Format-List *

或者：

where.exe codex

然后：

codex --version

这三个命令一起使用。

二十一、npm 更新后版本还是旧的

执行：

npm list -g @openai/codex

然后：

where.exe codex

有可能是：

你更新了一个 Codex
Windows 实际执行的是另外一个 Codex

解决问题的关键不是一直：

npm install -g @openai/codex@latest

而是先：

where.exe codex

二十二、Codex 更新时报 EPERM

Windows 上可能看到：

EPERM: operation not permitted

例如：

EPERM: operation not permitted, unlink '...\codex.exe'

这个错误翻译成人话就是：

Windows 不允许当前操作

常见原因：

codex.exe 正在运行
文件被其他程序占用
Windows Defender 正在扫描
杀毒软件锁定
没有权限
npm 正尝试删除正在执行的 codex.exe

二十三、更新 Codex 时怎么避免 EPERM？

先彻底关闭：

Codex
Windows Terminal 中运行的 Codex
VS Code 中的 Codex
Cursor 中的 Codex

然后打开新的 PowerShell。

执行：

npm install -g @openai/codex@latest

如果仍然失败：

打开任务管理器检查：

codex.exe

是否仍然存在。

二十四、查看 Codex 进程

PowerShell：

Get-Process codex -ErrorAction SilentlyContinue

如果确实需要结束：

Stop-Process -Name codex -Force

然后重新更新。

二十五、Missing optional dependency

npm 版 Codex 有时可能出现：

Missing optional dependency @openai/codex-win32-x64

或者类似：

Missing optional dependency

Windows npm 更新过程中如果平台对应包没有正确安装，就可能发生。

可以尝试：

npm uninstall -g @openai/codex

然后：

npm cache verify

重新安装：

npm install -g @openai/codex@latest

再检查：

codex --version

二十六、Codex 登录有哪几种方式？

运行：

codex

一般可以：

Sign in with ChatGPT

使用 ChatGPT 账号。

也可以配置 API Key。

这两种方式不要混淆。

二十七、ChatGPT 登录后还是 401

典型错误：

401 Unauthorized

例如：

unexpected status 401 Unauthorized

这里首先检查：

你到底是 ChatGPT 登录
还是 API Key 模式

二十八、ChatGPT 登录被旧 OPENAI_API_KEY 干扰

这是非常值得检查的一项。

PowerShell：

echo $env:OPENAI_API_KEY

再看：

echo $env:OPENAI_BASE_URL

如果你本来想：

Sign in with ChatGPT

但是系统环境变量里又设置了：

OPENAI_API_KEY
OPENAI_BASE_URL

就可能造成认证路径混乱。

尤其以前使用过：

New API
One API
自建 API
第三方中转 API
OpenRouter
自定义 OpenAI Base URL

的人特别容易遇到。

二十九、查看 OpenAI 相关环境变量

PowerShell：

Get-ChildItem Env: |
Where-Object Name -Match 'OPENAI|CODEX'

这是一个非常实用的排障命令。

三十、临时删除 OPENAI_API_KEY

当前 PowerShell：

Remove-Item Env:OPENAI_API_KEY -ErrorAction SilentlyContinue

删除：

Remove-Item Env:OPENAI_BASE_URL -ErrorAction SilentlyContinue

然后重新启动 Codex。

注意：

这只是当前 PowerShell 会话。

三十一、永久环境变量在哪里看？

Windows 搜索：

编辑系统环境变量

然后进入：

环境变量

检查：

OPENAI_API_KEY
OPENAI_BASE_URL
HTTP_PROXY
HTTPS_PROXY
ALL_PROXY
CODEX_HOME
CODEX_CLI_PATH

这些变量都可能影响 Codex。

三十二、401：Missing scopes

可能出现：

401 Unauthorized

并伴随：

You have insufficient permissions for this operation

或者：

Missing scopes

例如：

Missing scopes: api.responses.write

这种情况就不只是“密码错了”。

可能涉及：

登录状态
API 项目权限
Organization 权限
API Key 权限
环境变量污染
账号登录方式

首先建议：

退出 Codex 登录
清除冲突环境变量
重新登录

三十三、403 Forbidden

典型：

403 Forbidden

通常代表：

服务器知道你是谁
但当前请求没有权限

重点检查：

当前账号权限
API Key 权限
Organization
Project
模型权限
网络区域
企业策略

三十四、404 Model not found

例如：

404 Not Found

或者：

Model not found

类似：

unexpected status 404 Not Found:
Model not found xxx

说明 Codex 当前请求的：

模型名称不存在

或者：

你的服务端没有这个模型

三十五、自定义 API 最容易出现 Model not found

例如你配置：

OPENAI_BASE_URL=https://xxx

然后 Codex 请求：

gpt-xxx

但是你的中转接口只支持：

另一些模型

就会直接：

404 Model not found

因此一定要先确认：

Codex 发出的模型名

与你的 API 服务实际支持的模型一致。

三十六、Falling back from WebSockets to HTTPS transport

可能看到：

Falling back from WebSockets to HTTPS transport

这个信息本身不一定代表 Codex 已经彻底坏了。

它表示：

WebSocket 连接没有正常工作
Codex 尝试切换 HTTPS

如果切换之后能够正常工作，不一定需要处理。

如果随后不断：

reconnecting
stream disconnected
connection error

就需要检查网络。

三十七、stream disconnected before completion

典型：

stream disconnected before completion

或者：

stream error

通常重点排查：

代理
网络
WebSocket
防火墙
企业网关
VPN
Base URL
API 中转服务

而不是第一时间认为：

模型坏了

三十八、error sending request for url

例如：

error sending request for url

这基本已经在告诉你：

HTTP 请求没正常发送完成

重点检查：

Test-NetConnection chatgpt.com -Port 443

然后：

curl.exe -I https://chatgpt.com

三十九、Windows 代理环境变量怎么检查？

执行：

Get-ChildItem Env: |
Where-Object Name -Match 'PROXY'

可能看到：

HTTP_PROXY
HTTPS_PROXY
ALL_PROXY
NO_PROXY

四十、本地代理的典型配置

例如代理软件监听：

127.0.0.1:7890

可以临时：

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"

然后：

codex

具体端口以你的代理软件为准。

四十一、SOCKS5 代理可能出现问题

Windows 下某些 Codex 版本 / 网络环境下：

SOCKS5

代理可能出现连接不稳定。

例如：

stream disconnected
tunnel error
unexpected end of file

这种情况下可以测试：

HTTP_PROXY
HTTPS_PROXY

形式，而不是只配置：

ALL_PROXY=socks5://...

四十二、代理明明开了，Codex 还是连不上

这里必须理解：

Windows 系统代理
PowerShell 环境变量
Codex Sandbox
WSL

不是同一个网络环境。

所以：

浏览器能访问

不代表：

Codex CLI 一定能访问

同样：

Windows PowerShell 能 npm install

也不代表：

Codex Sandbox 里的 npm install 一定成功

四十三、getaddrinfo EAI_AGAIN

典型：

getaddrinfo EAI_AGAIN registry.npmjs.org

意思是：

DNS 解析暂时失败

重点检查：

nslookup registry.npmjs.org

再：

npm ping

再：

curl.exe -I https://registry.npmjs.org

如果宿主 PowerShell 正常，而 Codex 内失败：

很可能需要进一步检查：

Codex Sandbox 网络

四十四、connect EPERM 127.0.0.1:xxxx

例如：

connect EPERM 127.0.0.1:7897

这通常意味着：

Codex 沙箱不允许当前网络连接

特别是访问：

Windows 本地代理

时可能出现。

这跟：

代理软件没启动

不是完全一回事。

四十五、spawn EPERM 是什么？

这是 Windows Codex 中非常重要的报错。

例如：

Error: spawn EPERM

含义大概是：

Codex 想启动一个子进程
但是 Windows 拒绝了

常见于：

Node child_process
esbuild
npm
pip
Computer Use
Codex Sandbox

四十六、spawn EPERM 常见原因

重点包括：

Windows 沙箱限制
Codex Desktop Sandbox
Windows Defender
企业杀毒软件
Controlled Folder Access
没有执行权限
文件被锁定
Child Process 被限制
WindowsApps ACL
Codex 版本 Bug

四十七、怎么判断是不是 Codex Sandbox？

假设 Codex 里面执行：

npm install

报：

spawn EPERM

你自己打开 Windows Terminal。

进入同一个项目：

cd C:\你的项目

执行：

npm install

如果：

宿主 PowerShell 成功
Codex 里面失败

那么项目本身大概率没坏。

重点怀疑：

Codex Sandbox

四十八、esbuild 报 spawn EPERM

例如：

Error: spawn EPERM

堆栈中有：

esbuild
child_process.spawn

这种情况尤其可能是：

Node 想拉起 esbuild 子进程
被 Windows 沙箱拦截

可以先在普通 Windows Terminal 测试：

npm run build

如果外面能运行，Codex 里不能运行：

排查方向就很明确了。

四十九、Codex 无法调用 WSL

有时可能看到：

Access is denied

或者：

Wsl/Service/CreateInstance/E_ACCESSDENIED

意味着 Codex 当前进程或 Sandbox：

无法创建 WSL 实例

先退出 Codex。

直接在 Windows Terminal：

wsl

如果可以：

说明 WSL 本身正常。

问题可能发生在：

Codex → WSL

这一层。

五十、检查 WSL 状态

执行：

wsl --status

查看发行版：

wsl -l -v

例如：

NAME      STATE      VERSION
Ubuntu    Running    2

五十一、什么时候建议直接使用 WSL？

如果项目本身高度依赖：

Linux shell
bash
chmod
apt
Linux toolchain
Docker Linux
复杂 npm native build
Python Linux 环境

那么可以考虑直接：

WSL2 + Ubuntu

运行 Codex。

因为这样环境更接近：

Linux 生产环境

五十二、但是 Windows 原生 Codex 不等于必须 WSL

这点一定要区分。

现在：

Windows 原生 Codex CLI

本身已经存在。

WSL 是：

可选方案

不是：

安装 Codex 的硬性前提

五十三、Codex 工作目录错了

Windows 上可能出现这种现象：

你启动：

cd D:\projects\myapp
codex

但是 Codex 执行命令时却跑到了：

C:\

或者其他目录。

首先确认当前：

Get-Location

再：

codex

进入 Codex 后让它执行：

pwd

或者：

Get-Location

确认工作目录。

五十四、路径里有中文怎么办？

例如：

C:\Users\王仕宇\Desktop\项目

现代程序通常应该支持 Unicode 路径。

但实际 Windows 工具链中：

老版本 npm
Python 包
Rust 工具
Shell
第三方插件
MCP
自定义脚本

仍可能对中文路径处理不好。

遇到很奇怪的路径问题，可以测试：

C:\code\myproject

这样简单的纯英文路径。

如果立刻恢复正常：

就很可能和路径编码有关。

五十五、路径里有空格

例如：

C:\Users\xxx\My Projects\app

Shell 命令记得：

cd "C:\Users\xxx\My Projects\app"

而不是：

cd C:\Users\xxx\My Projects\app

五十六、OneDrive 项目目录容易产生奇怪权限问题

例如项目在：

C:\Users\xxx\OneDrive\Desktop\project

可能遇到：

同步锁
文件占用
权限
rename 失败
delete 失败
EPERM
文件刚生成又被同步

出现这些问题，可以测试把项目移动到：

C:\code\project

再运行。

五十七、Access is denied

经典 Windows：

Access is denied

或者：

Permission denied

优先判断：

哪个文件？
哪个目录？
哪个程序？

不要一上来就：

管理员运行所有程序

五十八、Windows Defender Controlled Folder Access

如果开启：

Controlled Folder Access

可能阻止 Codex 修改：

Documents
Desktop
Pictures
其他保护目录

如果 Codex：

能看文件
不能修改

就值得检查这一项。

五十九、不要长期用管理员权限跑 Codex

有人遇到权限问题就：

Run as administrator

虽然有时能绕过某些权限问题，但是长期让 AI Coding Agent：

管理员权限运行

风险会明显增加。

六十、Windows App 打不开

可能表现为：

点击 Codex
没有任何反应

或者：

窗口一闪而过

或者：

后台有进程
但是没有窗口

先打开：

任务管理器

搜索：

Codex
ChatGPT

结束相关进程。

然后重新打开。

六十一、Codex failed to start

可能出现：

Codex failed to start

甚至：

Codex app-server websocket closed

这种问题说明：

桌面 UI 已经启动
但是内部 Codex 服务没有正常启动

先：

完全关闭 Codex
任务管理器结束 Codex
重启电脑
Windows Store 检查更新
应用修复
应用重置

六十二、Windows App 提示 Unable to locate Codex CLI binary

近期 Windows App 曾出现：

Unable to locate the Codex CLI binary

甚至：

ChatGPT failed to start.
Unable to locate the Codex CLI binary.

翻译一下：

Codex 桌面应用找不到它应该调用的 Codex CLI 可执行文件

这和普通：

PowerShell 找不到 codex

并不完全一样。

六十三、先检查系统 Codex

执行：

where.exe codex

以及：

codex --version

如果 CLI 正常，但 Desktop 仍然：

Unable to locate Codex CLI

说明更可能是：

Desktop 自己的 bundled CLI / runtime

出了问题。

优先：

更新 / Repair / Reset / 重装 Codex App

六十四、CODEX_CLI_PATH

Codex Desktop 某些故障情况下会涉及：

CODEX_CLI_PATH

查看：

echo $env:CODEX_CLI_PATH

如果以前手工配过，先确认路径是否还存在。

六十五、不要随便把 CODEX_CLI_PATH 指向 codex.cmd

Windows npm 安装一般会产生：

codex.cmd

但桌面 App 某些版本中，如果直接拿：

codex.cmd

作为原生可执行文件 Spawn，可能出现：

spawn EINVAL

因为：

.cmd

本质是 Windows 批处理包装脚本，不是真正的：

codex.exe

六十六、spawn EINVAL

典型：

spawn EINVAL

意思一般是：

调用 child_process.spawn 时参数 / 可执行目标不符合 Windows 要求

如果你刚刚手工设置：

CODEX_CLI_PATH=xxx\codex.cmd

就特别值得检查。

六十七、怎么寻找真正的 codex.exe？

如果你使用 npm，可以尝试：

Get-ChildItem "$(npm root -g)\@openai" `
-Recurse `
-Filter codex.exe `
-ErrorAction SilentlyContinue

找到真正：

codex.exe

之后再判断是否需要进一步配置。

这是高级排查手段，一般用户优先选择：

重新安装 / Repair

而不是手工修改内部路径。

六十八、桌面 App 一直卡 Logo

表现：

Codex Logo
一直转
不进入主界面

首先：

结束进程
重启

如果长期存在：

可能涉及：

.codex 状态目录
本地数据库
插件
Runtime
旧配置迁移

六十九、.codex 目录在哪里？

默认一般在：

C:\Users\你的用户名\.codex

PowerShell：

$HOME\.codex

检查：

Get-ChildItem $HOME\.codex

七十、不要直接删除 .codex

因为里面可能包含：

登录状态
配置
历史状态
插件数据
本地数据库
Sandbox 信息

更稳妥的测试方式是：

Rename-Item "$HOME\.codex" ".codex-backup"

然后重新启动 Codex。

如果恢复正常：

说明旧：

.codex

很可能存在状态或配置问题。

确认后再决定如何处理旧目录。

七十一、Windows App Not Responding

可能出现：

Codex is not responding

如果长会话、插件、Computer Use 等功能启用以后发生：

先测试：

新建一个全新会话

再测试：

暂时关闭插件

这样可以判断：

App 全局问题

还是：

某个会话 / 插件问题

七十二、Computer Use 开启后 Codex 卡死

Windows 上已经出现过：

启用 Computer Use
Codex Desktop 变得无响应

这种时候非常简单的隔离方法是：

关闭 Computer Use
重启 Codex

如果恢复正常：

基本已经找到问题方向。

七十三、Computer Use：spawn EPERM

可能出现：

spawn EPERM

这种情况目前 Windows 下确实可能涉及：

Computer Use helper
Windows Sandbox
ACL
WindowsApps
权限

它不一定是你自己的项目代码导致的。

七十四、EnumWindows failed

可能看到：

EnumWindows failed

甚至：

The system cannot find the path specified.
0x80070003

这类错误属于：

Computer Use / Windows helper

层面。

不是普通 SQL、Node、Python 项目报错。

所以不要跑去：

npm reinstall

项目依赖。

七十五、Windows sandbox helper not found

可能看到：

codex-windows-sandbox-setup.exe not found

或者：

program not found

类似：

windows sandbox failed

这种属于：

Codex Windows Sandbox Helper

没有正确找到或安装。

优先：

更新 Codex
重新安装
Repair

而不是修改项目代码。

七十六、Windows doesn't fully support CET

某些较老 Windows 11 版本可能出现：

Fatal error.
Your Windows doesn't fully support CET.
Please install all available Windows updates.

这种报错重点不是 Codex 项目。

而是：

Codex bundled PowerShell / .NET Runtime

与当前 Windows 版本兼容性。

首先：

Windows Update

把系统升级到受支持的最新版本。

七十七、Codex 里执行 PowerShell 命令崩溃

如果：

普通 Windows PowerShell 正常
Codex 内置 PowerShell 崩

可以先测试：

powershell.exe -Version

以及：

pwsh -Version

判断：

Windows PowerShell 5.1
PowerShell 7
Codex bundled PowerShell

到底是哪一个出问题。

七十八、PATH 修改了，但 Codex App 看不到

这是非常典型的桌面程序问题。

你刚修改：

Windows 环境变量 PATH

然后：

PowerShell 能找到新命令
Codex App 找不到

原因可能只是：

Codex App 进程启动时已经缓存了旧环境

所以需要：

完全退出 Codex
结束后台进程
重新启动

必要时：

注销 Windows

或者：

重启电脑

七十九、Codex 找不到 Git

报错可能类似：

git is not recognized

或者：

git: command not found

检查：

git --version

如果不行：

说明 Git 本身没装好或者 PATH 不对。

八十、检查 Git 路径

where.exe git

常见：

C:\Program Files\Git\cmd\git.exe

如果普通 PowerShell：

git --version

正常。

但 Codex 内不正常：

重新启动 Codex。

八十一、not a git repository

典型：

fatal: not a git repository

不是 Codex 出问题。

而是：

当前目录不是 Git 仓库

检查：

git status

如果项目本来就没有初始化：

git init

八十二、dubious ownership

Git 可能出现：

detected dubious ownership in repository

这种问题通常涉及：

仓库所有者
当前 Windows 用户
WSL 用户
Docker
挂载目录

不要无脑：

safe.directory=*

最好只把明确可信的项目加入：

git config --global --add safe.directory "D:/code/myproject"

八十三、LF / CRLF 问题

Windows 常见：

CRLF

Linux 常见：

LF

Git 可能提示：

LF will be replaced by CRLF

不一定是错误。

查看：

git config --global core.autocrlf

这属于：

Git 换行符策略

不是 Codex 本身故障。

八十四、PowerShell 与 Bash 命令不一样

这是新手使用 Codex 时特别常见的问题。

Linux：

ls -la

Windows PowerShell：

Get-ChildItem -Force

虽然 PowerShell 对一些命令有 Alias，但并不是完整兼容 Bash。

例如：

Linux：

export API_KEY=123

PowerShell：

$env:API_KEY="123"

八十五、&& 为什么不能运行？

老 Windows PowerShell：

command1 && command2

可能不能像 Bash 一样使用。

PowerShell 版本不同，行为也不同。

检查：

$PSVersionTable.PSVersion

如果教程明显是：

Linux / Bash

不要无脑复制到 Windows PowerShell。

八十六、rm -rf 在 PowerShell 里不要照抄

Linux：

rm -rf node_modules

PowerShell 推荐：

Remove-Item node_modules -Recurse -Force

同理：

grep
sed
awk
chmod
sudo

也不完全等价。

八十七、Codex 生成 Linux 命令怎么办？

直接告诉 Codex：

我当前环境是 Windows 11 + PowerShell，
后续所有命令都使用 PowerShell，
不要给 Bash/Linux 命令。

这是最简单的解决方法。

八十八、Windows 下项目依赖安装失败

例如：

npm ERR!

一定先脱离 Codex 测试：

npm install

如果普通终端也失败：

说明：

项目 / npm / Node / 网络

有问题。

如果普通终端成功，只有 Codex 失败：

再查：

Sandbox
权限
网络

八十九、npm ERR! EPERM

例如：

npm ERR! code EPERM

npm ERR! syscall unlink

operation not permitted

Windows 经典问题。

常见原因：

文件占用
编辑器锁文件
杀毒软件
OneDrive
正在运行的 Node
权限

九十、删除 node_modules 失败

可以先：

Get-Process node -ErrorAction SilentlyContinue

如果确认可以结束：

Stop-Process -Name node -Force

然后：

Remove-Item node_modules -Recurse -Force

九十一、端口被占用

例如：

EADDRINUSE

address already in use

这不是 Codex 报错。

而是项目启动端口已经被占。

例如查：

netstat -ano | findstr :3000

可能看到：

LISTENING 12345

然后：

tasklist | findstr 12345

九十二、结束占用端口的进程

确认之后：

taskkill /PID 12345 /F

不要看到 PID 就无脑杀。

先确认：

这个进程到底是什么

九十三、Python 找不到

Codex 可能执行：

python: command not found

Windows：

python --version

再：

py --version

Windows 很多时候：

python

没有。

但是：

py

有。

九十四、pip 找不到

检查：

python -m pip --version

比直接：

pip

更可靠。

安装：

python -m pip install package

九十五、Python Microsoft Store Alias 干扰

Windows 有时候：

python

会跳 Microsoft Store。

可以检查：

设置
→ 应用
→ 高级应用设置
→ 应用执行别名

里面的：

python.exe
python3.exe

别名。

九十六、MCP Server 启动失败

可能出现：

MCP server failed

或者：

Failed to start MCP server

先不要认为：

Codex 模型坏了

MCP 本质上通常是：

本地子进程

先把 MCP 配置里的命令拿出来。

直接在 PowerShell 执行。

九十七、例如 npx MCP

配置类似：

npx -y xxx-mcp

先直接：

npx -y xxx-mcp

如果这里都报错：

问题就在：

Node / npm / MCP 包

而不是 Codex。

九十八、MCP spawn ENOENT

典型：

spawn ENOENT

一般表示：

找不到要执行的程序

例如：

node 找不到
npx 找不到
python 找不到
uvx 找不到

检查：

where.exe node
where.exe npx
where.exe python

九十九、MCP spawn EPERM

和前面的：

spawn EPERM

一样。

意思偏向：

程序找到了
但是不能执行

重点看：

权限 / Sandbox / 安全软件

一百、MCP 超时

例如：

MCP server timed out

先单独运行 MCP。

判断它：

是不是一直在下载依赖
是不是需要登录
是不是网络不通
是不是启动时报错

一百零一、Codex 读取不到新安装的软件

例如你刚安装：

ffmpeg
ImageMagick
Python
Git
Node

普通终端已经可以：

ffmpeg -version

但是 Codex：

command not found

先彻底退出 Codex。

重新打开。

因为：

环境变量可能是在进程启动时读取的

一百零二、检查一个命令真正在哪里

PowerShell：

Get-Command ffmpeg

或者：

where.exe ffmpeg

这个技巧适用于：

git
node
npm
python
ffmpeg
magick
codex
java
go

几乎所有工具。

一百零三、Codex 无法创建文件

先检查项目目录：

Get-Location

再检查：

Get-Acl .

然后自己测试：

"test" | Out-File test.txt

如果你自己都不能创建：

这就不是 Codex 的问题。

一百零四、只读目录

例如：

Program Files
WindowsApps
系统目录

权限本身就比较严格。

项目不要随便放：

C:\Program Files\myproject

更推荐：

C:\code\myproject

或者：

D:\code\myproject

一百零五、WindowsApps 权限问题

Microsoft Store App 常涉及：

WindowsApps

这是 Windows 保护目录。

不要为了修 Codex：

直接修改整个 WindowsApps ACL

这个操作风险很高。

优先：

Repair
Reset
重装应用
更新应用

一百零六、Codex 一直 Connecting

表现：

Connecting...

一直不动。

按下面顺序：

1. 普通浏览器能否访问 ChatGPT
2. curl 能否访问
3. DNS 是否正常
4. 代理是否正常
5. HTTP_PROXY 是否正确
6. 是否配置错误 Base URL
7. 是否企业防火墙拦截

一百零七、网络快速检查

Test-NetConnection chatgpt.com -Port 443

DNS：

Resolve-DnsName chatgpt.com

HTTPS：

curl.exe -I https://chatgpt.com

一百零八、DNS 有问题

先：

ipconfig /flushdns

然后：

nslookup chatgpt.com

如果公司 DNS 或校园网 DNS 本身拦截：

需要解决网络层问题。

一百零九、代理端口到底开没开？

假设：

127.0.0.1:7890

执行：

Test-NetConnection 127.0.0.1 -Port 7890

如果：

TcpTestSucceeded : False

说明：

这个代理端口根本没监听

Codex 肯定连不上。

一百一十、设置了错误 OPENAI_BASE_URL

检查：

echo $env:OPENAI_BASE_URL

例如以前设置：

https://old-api.example.com/v1

后来忘了。

结果 Codex 一直：

401
404
502
连接失败

这种问题非常隐蔽。

一百一十一、502 Bad Gateway

如果自定义 API：

502 Bad Gateway

一般不是 Codex 本地权限。

而是：

Codex
↓
API 网关
↓
上游模型

中间某层失败。

重点看 API 中转服务器日志。

一百一十二、503 Service Unavailable

例如：

503 Service Unavailable

通常表示：

上游暂时不可用
服务过载
模型无容量

如果官方接口和本地环境均正常：

可以稍后重新发起。

如果你用自己的 API：

重点检查：

你的上游

一百一十三、429 Too Many Requests

典型：

429 Too Many Requests

可能意味着：

请求过快
API Rate Limit
Token Limit
账号额度
服务限流
并发太高

不要把：

理解成：

Codex 没装好

一百一十四、Request timed out

可能原因：

网络慢
API 慢
模型响应时间长
代理超时
中转服务超时
请求上下文太大

如果自建 Nginx / API Gateway：

还需要检查：

proxy_read_timeout
proxy_send_timeout

等配置。

一百一十五、Context 太大

长时间使用 Codex：

大量文件
大量终端日志
超长会话
大量图片
复杂任务

会使上下文越来越大。

可能表现：

速度越来越慢
compact 失败
响应异常

可以尝试：

新建任务 / 新建会话

判断是不是当前上下文状态造成的。

一百一十六、remote compact task 失败

可能出现：

Error running remote compact task

以及：

stream disconnected before completion

如果同时有：

代理
SOCKS5
网络波动

优先排查网络。

一百一十七、Codex 能聊天，但是执行命令失败

这种问题很关键。

如果：

AI 能正常回复

说明：

账号
模型连接
基础网络

大概率正常。

但：

执行 shell 命令失败

说明重点应该转到：

Shell
Sandbox
权限
PATH
工作目录

而不是继续折腾登录。

一百一十八、Codex 能读文件，不能写

重点检查：

Sandbox 权限
项目目录权限
Windows Defender
Controlled Folder Access
只读文件

一百一十九、Codex 修改文件时报文件占用

Windows 很容易：

The process cannot access the file because it is being used by another process

可能占用文件的：

Node
Java
VS Code
Excel
Git
npm
OneDrive
杀毒软件

可以使用：

Resource Monitor
Process Explorer

寻找占用进程。

一百二十、日志从哪里看？

CLI 问题先直接看终端。

如果需要更深排查：

检查：

%USERPROFILE%\.codex

PowerShell：

Get-ChildItem "$HOME\.codex" -Recurse |
Select-Object FullName

不要一上来全部删除。

一百二十一、Codex Doctor

如果当前版本提供：

codex doctor

可以优先执行。

它可以帮助检查：

版本
运行环境
app-server
配置
Sandbox

对于提交 GitHub Issue 也很有帮助。

一百二十二、最值得保存的 Windows Codex 排错命令

Codex

codex --version

找 Codex

where.exe codex

PowerShell 找 Codex

Get-Command codex

Node

node -v

npm

npm -v

Git

git --version

npm 全局目录

npm root -g

当前路径

Get-Location

PATH

$env:Path -split ";"

Codex / OpenAI 环境变量

Get-ChildItem Env: |
Where-Object Name -Match 'OPENAI|CODEX'

代理

Get-ChildItem Env: |
Where-Object Name -Match 'PROXY'

网络

Test-NetConnection chatgpt.com -Port 443

DNS

Resolve-DnsName chatgpt.com

WSL

wsl --status

WSL 发行版

wsl -l -v

Codex 进程

Get-Process codex -ErrorAction SilentlyContinue

一百二十三、常见报错与原因速查表

报错	重点排查
`codex is not recognized`	PATH / 安装
`The term 'codex' is not recognized`	PATH
`npm is not recognized`	Node/npm
`git is not recognized`	Git/PATH
`401 Unauthorized`	登录/API Key/环境变量
`403 Forbidden`	账号/项目权限
`404 Model not found`	模型名/API
`429 Too Many Requests`	限流/额度
`502 Bad Gateway`	API 网关/上游
`503 Service Unavailable`	上游不可用
`spawn ENOENT`	程序找不到
`spawn EPERM`	权限/Sandbox
`spawn EINVAL`	Windows Spawn 目标/参数
`EAI_AGAIN`	DNS
`ECONNREFUSED`	服务未启动/端口
`ETIMEDOUT`	网络/代理
`EADDRINUSE`	端口占用
`Access is denied`	Windows 权限
`Permission denied`	权限
`EPERM unlink codex.exe`	文件被占用
`Missing optional dependency`	npm 安装不完整
`Unable to locate Codex CLI binary`	Desktop bundled CLI
`Codex failed to start`	App Runtime / app-server
`stream disconnected`	网络/代理/WebSocket
`Falling back to HTTPS`	WebSocket 失败
`MCP server failed`	MCP 子进程
`MCP timed out`	MCP 启动/网络
`Wsl ... E_ACCESSDENIED`	Sandbox/WSL 权限
`not a git repository`	当前目录
`dubious ownership`	Git 所有权
`running scripts is disabled`	PowerShell Policy
`Could not create SSL/TLS secure channel`	TLS/代理/证书

一百二十四、看到 spawn ENOENT 怎么判断？

一句话：

ENOENT = 找不到

例如：

spawn node ENOENT

说明：

找不到 node

执行：

where.exe node

一百二十五、看到 spawn EPERM 怎么判断？

一句话：

EPERM = 找到了，但是不让执行

重点：

Windows 权限
Sandbox
Defender
安全软件
文件占用

一百二十六、看到 ECONNREFUSED 怎么判断？

一句话：

目标存在，但没有服务接受连接

例如：

ECONNREFUSED 127.0.0.1:3000

说明：

3000 端口没有对应服务

检查：

netstat -ano | findstr :3000

一百二十七、看到 ENOTFOUND 怎么判断？

通常：

域名解析失败

执行：

nslookup 域名

一百二十八、看到 ETIMEDOUT 怎么判断？

表示：

连接尝试了
但是一直没有结果

重点：

网络
代理
防火墙
服务器
超时配置

一百二十九、看到 EAI_AGAIN 怎么判断？

表示：

DNS 临时解析失败

重点检查：

Resolve-DnsName 域名

一百三十、Windows Codex 万能排查顺序

以后 Codex 出问题，不要马上重装。

按照下面这个顺序。

第一步
确认是哪一个 Codex
CLI / App / IDE
        ↓
第二步
确认 Codex 能否运行
codex --version
        ↓
第三步
检查路径
where.exe codex
Get-Command codex
        ↓
第四步
检查基础工具
node
npm
git
        ↓
第五步
检查环境变量
OPENAI
CODEX
PROXY
        ↓
第六步
检查网络
DNS
HTTPS
代理
        ↓
第七步
检查登录
ChatGPT / API Key
        ↓
第八步
检查工作目录
PATH
权限
        ↓
第九步
检查 Sandbox
spawn EPERM
网络限制
        ↓
第十步
再考虑
更新 / Repair / Reset / 重装

一百三十一、我最推荐的 Windows 排查脚本

直接在 PowerShell 依次执行：

Write-Host "=== Codex ==="
codex --version

Write-Host "=== Codex Path ==="
where.exe codex

Write-Host "=== PowerShell Command ==="
Get-Command codex -ErrorAction SilentlyContinue

Write-Host "=== Node ==="
node -v

Write-Host "=== npm ==="
npm -v

Write-Host "=== Git ==="
git --version

Write-Host "=== Location ==="
Get-Location

Write-Host "=== OpenAI / Codex Env ==="
Get-ChildItem Env: |
Where-Object Name -Match 'OPENAI|CODEX'

Write-Host "=== Proxy Env ==="
Get-ChildItem Env: |
Where-Object Name -Match 'PROXY'

Write-Host "=== Network ==="
Test-NetConnection chatgpt.com -Port 443

Write-Host "=== WSL ==="
wsl --status

这套结果基本已经能判断大量问题。

一百三十二、如果 Codex 完全打不开

按照：

1. 重启 Windows Terminal
2. codex --version
3. where.exe codex
4. 检查 PATH
5. 检查 npm/Standalone 是否冲突
6. 重装 CLI

Desktop：

1. Task Manager 杀进程
2. Windows Store 更新
3. Repair
4. Reset
5. 重装
6. 检查 .codex

一百三十三、如果 Codex 能打开但不能联网

按照：

1. 浏览器访问 ChatGPT
2. curl chatgpt.com
3. Test-NetConnection 443
4. DNS
5. PROXY 环境变量
6. OPENAI_BASE_URL
7. Sandbox 网络

一百三十四、如果 Codex 能聊天但不能执行命令

按照：

1. Get-Location
2. PATH
3. 命令是否存在
4. 项目权限
5. Sandbox
6. Defender
7. 普通 PowerShell 对比测试

这里最重要的是：

对比测试

同一条命令：

Codex 里失败
普通 PowerShell 成功

基本就能排除：

项目本身

一百三十五、如果 Codex 只有 npm / pip 失败

先普通终端：

npm ping

npm install

python -m pip install xxx

如果宿主正常：

重点：

Sandbox
DNS
代理
子进程权限

一百三十六、如果换电脑突然正常

这种情况非常有价值。

说明：

账号本身大概率没问题

重点比较：

Windows 版本
Codex 版本
Node 版本
PATH
代理
.codex
Defender
WSL
PowerShell
企业软件

一百三十七、什么时候最适合重装？

符合下面情况再重装：

CLI binary 缺失
npm 包损坏
Desktop runtime 缺失
Windows Store 更新失败
.codex 与新版本迁移冲突
Sandbox helper 文件缺失

如果是：

401
404
代理
DNS
端口占用
Git

重装通常没什么用。

一百三十八、不要陷入“遇事重装”的循环

这是 Windows 新手最容易出现的动作：

Codex 出错
↓
卸载
↓
重装
↓
还是报错
↓
继续重装

真正应该做的是先判断：

错误发生在哪一层

一百三十九、Codex Windows 故障可以分成 7 层

可以直接记住这个模型：

第 1 层：安装层
Codex 有没有安装

第 2 层：Shell 层
PowerShell / CMD / PATH

第 3 层：环境层
Node / npm / Git / Python

第 4 层：网络层
DNS / Proxy / TLS / WebSocket

第 5 层：认证层
ChatGPT / API Key / 权限

第 6 层：执行层
Sandbox / EPERM / 文件权限

第 7 层：项目层
代码 / 依赖 / Git / Build

只要先定位属于哪一层，排查速度会快很多。

一百四十、最后给 Windows 新手的建议

如果你准备长期使用 Codex，建议 Windows 环境尽量简单一些。

项目目录：

C:\code\

或者：

D:\code\

尽量避免一开始就放：

OneDrive
Program Files
WindowsApps
复杂中文目录

常用基础工具：

Windows Terminal
PowerShell
Git
Node.js
Python
WSL2（按需）

再把这些命令记住：

codex --version

where.exe codex

Get-Command codex

node -v

npm -v

git --version

Get-Location

$env:Path

Get-ChildItem Env:

Test-NetConnection chatgpt.com -Port 443

基本已经可以解决绝大多数 Windows Codex 环境问题。

总结

Codex 在 Windows 上真正容易出问题的，不一定是 Codex 本身。

更多时候是：

PATH
PowerShell
npm
Node
Git
代理
DNS
权限
Sandbox
Windows App Runtime

所以以后看到报错，不要只搜索：

Codex Windows 打不开怎么办

而应该先读报错中的关键词。

例如：

ENOENT
→ 找不到程序

EPERM
→ 权限 / Sandbox

EINVAL
→ Windows Spawn 参数 / 目标异常

EAI_AGAIN
→ DNS

ECONNREFUSED
→ 端口 / 服务

401
→ 身份认证

403
→ 权限

404
→ 路径 / 模型

429
→ 限流

502 / 503
→ 网关 / 上游

stream disconnected
→ 网络 / 代理 / WebSocket

最后记住 Windows Codex 排错最核心的一句话：

先判断问题发生在哪一层，再修这一层；不要把所有问题都归结成“Codex 没装好”。

posted @ 2026-08-31 10:26 JavaPub 阅读(382) 评论(0) 收藏举报

刷新页面返回顶部

JavaPub

少年应有鸿鹄志，当骑骏马踏平川。

Codex 在 Windows 中的常见问题大全：安装、登录、网络、权限、PATH、WSL、报错完整排查指南

一、首先搞清楚：你用的是哪个 Codex？

1. Codex CLI

2. Codex Desktop App

3. IDE 中的 Codex

4. Codex Web

二、Windows 推荐安装 Codex 的方式

三、第二种安装方式：npm

四、安装完执行 codex 提示找不到命令

五、先判断 Codex 到底有没有安装

六、检查 Codex 版本

七、为什么刚安装完 Codex，却提示命令不存在？

八、检查 PATH

九、npm 安装的 Codex 在哪里？

十、快速检查 Node、npm 和 Codex

十一、npm 本身都找不到

十二、安装 Codex 报 PowerShell ExecutionPolicy 错误

十三、PowerShell 安装脚本下载失败

十四、老 PowerShell 的 TLS 问题

十五、强制使用 GitHub Releases 安装

十六、下载安装速度特别慢

十七、安装报错：Unsupported architecture

十八、怎么查看 Windows 架构？

十九、安装了两个 Codex，版本乱了

二十、到底执行的是哪个 Codex？

二十一、npm 更新后版本还是旧的

二十二、Codex 更新时报 EPERM

二十三、更新 Codex 时怎么避免 EPERM？

二十四、查看 Codex 进程

二十五、Missing optional dependency

二十六、Codex 登录有哪几种方式？

二十七、ChatGPT 登录后还是 401

二十八、ChatGPT 登录被旧 OPENAI_API_KEY 干扰

二十九、查看 OpenAI 相关环境变量

三十、临时删除 OPENAI_API_KEY

三十一、永久环境变量在哪里看？

三十二、401：Missing scopes

三十三、403 Forbidden

三十四、404 Model not found

三十五、自定义 API 最容易出现 Model not found

三十六、Falling back from WebSockets to HTTPS transport

三十七、stream disconnected before completion

三十八、error sending request for url

三十九、Windows 代理环境变量怎么检查？

四十、本地代理的典型配置

四十一、SOCKS5 代理可能出现问题

四十二、代理明明开了，Codex 还是连不上

四十三、getaddrinfo EAI_AGAIN

四十四、connect EPERM 127.0.0.1:xxxx

四十五、spawn EPERM 是什么？

四十六、spawn EPERM 常见原因

四十七、怎么判断是不是 Codex Sandbox？

四十八、esbuild 报 spawn EPERM

四十九、Codex 无法调用 WSL

五十、检查 WSL 状态

五十一、什么时候建议直接使用 WSL？

五十二、但是 Windows 原生 Codex 不等于必须 WSL

五十三、Codex 工作目录错了

五十四、路径里有中文怎么办？

五十五、路径里有空格

五十六、OneDrive 项目目录容易产生奇怪权限问题

五十七、Access is denied

五十八、Windows Defender Controlled Folder Access

五十九、不要长期用管理员权限跑 Codex

六十、Windows App 打不开

六十一、Codex failed to start

六十二、Windows App 提示 Unable to locate Codex CLI binary

六十三、先检查系统 Codex

六十四、CODEX_CLI_PATH

六十五、不要随便把 CODEX_CLI_PATH 指向 codex.cmd

六十六、spawn EINVAL

六十七、怎么寻找真正的 codex.exe？

六十八、桌面 App 一直卡 Logo

六十九、.codex 目录在哪里？

七十、不要直接删除 .codex

七十一、Windows App Not Responding

七十二、Computer Use 开启后 Codex 卡死

七十三、Computer Use：spawn EPERM