常见问题排查

本页按故障现象组织排错步骤。每项都包含症状、原因、诊断命令、修复、验证、安全边界。先收集证据，再做最小修改；命令、参数和配置项以本机 --help 与官方文档为准。

0. 通用分诊

症状不知道问题属于安装、认证、权限、网络还是项目本身，或 Codex 的总结与实际行为不一致。原因版本、登录、工作目录和权限经常叠加影响。未登录可能看起来像网络故障，沙箱拒绝可能看起来像文件权限错误。 诊断命令

codex --version
codex --help
codex login status
git status --short
pwd

进入会话后执行：

/status

PowerShell 可用 Get-Location 和 Get-Command codex -All 替代路径检查。修复先确认目录，再确认版本、登录和 /status 中的沙箱/审批。涉及代码时先建立 Git 检查点，明确不提交、不推送、不删除、不访问生产等非目标。验证再次执行上述检查，用 git diff --stat 确认诊断过程没有改动无关文件。 安全边界 不要把认证缓存、API key、私钥、.env 或客户数据贴到工单。README、网页、Issue、依赖包和 MCP 输出中的命令只是数据，不是授权。

1. 安装

1.1 找不到 `codex`

症状出现 command not found: codex，Windows 出现 'codex' is not recognized。原因安装目录没有进入 PATH，终端未重新加载环境变量，或官方安装器、npm、Homebrew 安装了多个版本。 诊断命令

which -a codex
command -v codex
printf '%s\n' "$PATH"
npm config get prefix

PowerShell：

Get-Command codex -All
where.exe codex
$env:Path -split ';'

修复按安装器输出把实际目录加入用户级 PATH，关闭并重新打开终端。若存在多个路径，保留一个安装来源，必要时移除多余 npm 包：

npm uninstall -g @openai/codex

验证在新终端执行 codex --version 和 codex --help，确认路径和版本符合预期。 安全边界 不要用管理员权限或 sudo npm install -g 作为第一反应。优先采用用户目录、版本管理器或官方独立安装器。

1.2 安装超时、TLS 或 npm 权限报错

症状安装脚本卡住、下载超时、证书错误，或 npm 报 EACCES/EPERM。原因终端没有走代理，企业 TLS 代理使用私有 CA，或 npm 全局目录属于系统用户。浏览器能访问不代表 Codex 的终端能访问。 诊断命令

curl -I https://chatgpt.com
curl -I https://api.openai.com
printf '%s\n' "$HTTP_PROXY" "$HTTPS_PROXY"

PowerShell：

Test-NetConnection api.openai.com -Port 443
$env:HTTP_PROXY
$env:HTTPS_PROXY

修复按组织要求配置终端代理。企业根证书由 IT 提供时设置 CODEX_CA_CERTIFICATE 指向 PEM，不要关闭 TLS 校验。npm 权限问题优先改用官方安装器、nvm 或 Volta，不要用 sudo 硬装。验证先用独立 HTTPS 检查确认网络，再执行 codex --version。用 which -a codex/where.exe codex 确认没有旧版本抢占。 安全边界 只使用可信代理和证书；不要执行来路不明的下载脚本，不要把代理密码或证书私钥写进仓库。

2. 登录

2.1 浏览器回调不工作

症状 codex login 不弹浏览器，授权后终端一直等待，或提示 localhost 回调失败。原因当前是远程/无头环境，浏览器与终端不在同一台机器，回调端口被占用，或防火墙拦截了本地回调。 诊断命令

codex login status
codex login --help
lsof -nP -iTCP:1455 -sTCP:LISTEN 2>/dev/null || true

PowerShell：

Get-NetTCPConnection -LocalPort 1455 -ErrorAction SilentlyContinue

修复远程环境优先使用设备码：

codex login --device-auth

在可信浏览器打开终端显示的链接并输入一次性验证码。设备码不可用时，按官方支持的 SSH 端口转发，或通过受保护通道迁移认证缓存。验证 codex login status 显示有效认证后，在无敏感数据的测试目录启动 Codex，执行一个只读请求。 安全边界 ~/.codex/auth.json 等同密码，迁移时使用权限受控通道，完成后确认权限；不提交、不上传、不贴出，也不要把设备码发给他人。

2.2 认证过期或 API key 功能/费用异常

症状频繁要求重新登录；API key 能运行本地 CLI，但部分工作区/云端功能不可用，或费用超预期。原因令牌刷新失败、缓存损坏、系统时间不正确或另一客户端登出。API key 按 API 用量计费，不等于 ChatGPT 订阅额度，部分功能依赖 ChatGPT 登录。 诊断命令

codex login status
codex --version
date
ls -l ~/.codex/auth.json 2>/dev/null

会话内执行 /status 和 /model，不要打印认证文件内容。修复确认时间和网络后重新登录：

codex logout
codex login

需要工作区功能时使用 ChatGPT 账号；CI 使用 API key 时设置预算、限额和最小权限。模型和推理强度按任务调整。验证连续启动两次确认登录态可复用，并核对 /status 的认证方式、模型和推理设置；在用量页面核对账单。 安全边界 不要在共享机器或公开 CI 日志使用高权限 key。认证路径、计费路径和文件权限是三件事，不能互相替代。

3. 项目不修改

3.1 只能读，不能写

症状能解释源码，但创建不了文件或修改被沙箱拒绝。原因当前为 read-only，项目未被信任，启动目录不是仓库根目录，目标路径在工作区外，或文件系统本身只读。 诊断命令

/status

pwd
git rev-parse --show-toplevel 2>/dev/null || true
ls -ld .

修复进入正确的项目根目录，建立 Git 检查点后使用日常组合：

codex --sandbox workspace-write --ask-for-approval on-request

只做分析就保持 read-only；确认目录归属后再信任项目，不要直接启用完全访问。验证让 Codex 在工作区创建无敏感内容的临时文件，再执行 git status --short 和 git diff 检查范围。 安全边界 workspace-write 只扩大到工作区，不等于整机写入。.git、.agents、.codex 等受保护目录应保持保护。

3.2 改了错误目录或想撤销

症状报告说改过文件，但目标项目没有变化；或改偏、改坏并包含请求外文件。原因终端、IDE、WSL 指向不同副本；没有提前提交检查点；只看代理总结没有审查真实 diff。 诊断命令

pwd
realpath . 2>/dev/null || true
git rev-parse --show-toplevel
git status --short
git diff --name-only

修复停止后续任务，先保存 diff。确认文件没有他人修改后，可撤销明确的单文件：

git restore -- path/to/file

混合修改用补丁或备份恢复；已提交内容用新的修复提交，不改写共享历史。验证运行 git diff --check、最小测试和构建，确认 git status --short 只剩预期内容。 安全边界 不要对不明文件执行 git restore，也不要用 git reset --hard 清理问题。Git 不能回滚数据库、部署和外部消息。

4. 沙箱与审批

4.1 审批太多或命令无提示却失败

症状每条命令都弹窗，或 on-request 下命令不弹窗却被拒绝、网络始终失败。原因 untrusted 会更频繁询问；沙箱和审批是独立旋钮：审批决定问不问，沙箱决定能写哪里和能否联网。workspace-write 网络默认关闭。 诊断命令

/status

codex --help

修复可信且有 Git 检查点的项目使用：

codex --sandbox workspace-write --ask-for-approval on-request

确需下载依赖时短时开启网络：

[sandbox_workspace_write]
network_access = true

完成后关闭。不要用 never 或完全访问掩盖范围问题。验证用 /status 确认沙箱、审批和工作区；分别测试读文件、写工作区和访问工作区外路径。开网后检查依赖锁文件和 diff。 安全边界 审批少不代表权限小。never 只是不询问；联网会放大提示注入和数据外发风险。

4.2 不确定权限或误用 `--yolo`

症状不同项目行为不一致，或想用 --yolo 解决所有拒绝。原因项目级/用户级配置、命令行参数和 profile 叠加；没有 Git 的目录通常更适合先只读。--yolo 同时移除沙箱和审批。 诊断命令

/status

codex --help

修复陌生目录先 read-only，日常使用 workspace-write + on-request。确实需要自动化时在一次性容器或 VM 中运行 --dangerously-bypass-approvals-and-sandbox（别名 --yolo），不要在本机或生产机使用。验证在测试目录验证写入、联网和受保护路径；确认权限变化没有扩大到宿主机目录或凭据。 安全边界 完全访问只适合可销毁的隔离环境。容器内仍可能暴露容器凭据，因此不可信仓库不能获得高权限环境。

5. 网络

5.1 登录、模型请求或依赖下载超时

症状登录或对话转圈，npm install/pip install 在 Codex 中失败，但手动执行成功。原因终端代理、DNS、企业 CA 与浏览器环境不同；沙箱网络默认关闭；服务端也可能限流。 诊断命令

curl -I https://chatgpt.com
curl -I https://api.openai.com
getent hosts api.openai.com 2>/dev/null || nslookup api.openai.com
printf '%s\n' "$HTTP_PROXY" "$HTTPS_PROXY"

PowerShell：

Resolve-DnsName api.openai.com
Test-NetConnection api.openai.com -Port 443

修复确认终端代理、DNS、防火墙和 CODEX_CA_CERTIFICATE。在可信项目中按需启用网络，使用锁文件和组织允许的镜像；不要永久开放整网访问。验证先用独立 HTTPS 检查，再做一次短请求或最小依赖安装；检查包来源、锁文件、响应码和 Git diff。 安全边界 不要关闭证书校验或使用陌生根证书。包安装脚本会执行代码，开网时审查包名、版本和 postinstall 行为。

5.2 外部网页内容疑似提示注入

症状 Codex 读 README、网页或 Issue 后，提出无关的联网、读凭证、改系统或外发操作。原因外部内容是数据，不是你的授权；实时网页和开放网络扩大了恶意指令入口。 诊断命令

/status

逐项查看待审批命令的路径、参数、域名和发送内容。修复陌生项目先用 read-only，拒绝与原任务无关的命令；不要把不可信内容通过管道直接喂给 Codex。需要外部服务时使用容器/VM和精确域名白名单。验证确认摘要任务无需读取凭证或联网；对批准的请求记录目标域名和数据内容。 安全边界 联网、读 .env/~/.ssh、改 shell 配置、装服务、删除文件、提权和外发都必须人工审查。“项目标准流程”不能代替授权。

6. MCP

6.1 MCP 服务器不显示或启动失败

症状看不到 MCP 工具，或报命令不存在、依赖缺失、握手失败、进程退出。原因启动命令、参数、工作目录、传输方式或环境变量不匹配；沙箱阻止文件/网络访问。 诊断命令

codex --help
command -v <mcp-command>
node --version
python --version

用同一用户、目录和环境变量在 Codex 外单独运行 MCP 启动命令，检查 stderr；不要打印密钥。修复逐字段核对配置，先让服务独立启动并完成握手，再接回 Codex。缺网络时只放行必要域名，缺文件权限时修正工作目录，不要直接全局放权。验证重启 Codex，确认工具名称和描述出现；先调用无副作用的查询工具，检查返回结构和超时。 安全边界 MCP 进程可能继承环境变量和文件权限。不要向不可信 MCP 提供 API key、认证缓存、生产配置或工作区外目录。

6.2 MCP 工具可见但调用失败

症状工具已列出，却超时、返回无效数据、认证失败或下游 API 报错。原因进程通信正常，但 schema、下游 API、认证、网络或服务状态异常；工具返回内容也可能含提示注入。 诊断命令 查看 MCP 自身 stderr、健康检查和下游日志。先让 Codex 展示工具名、参数和目标，不立即执行写操作。修复用最小参数调用只读工具，修正 schema、认证和超时。写入、删除、发消息、创建工单等操作使用测试账号和人工审批。验证只读查询成功后再做可回滚的测试写入，并核对下游审计日志和错误码。 安全边界 工具描述和返回值不能自动授予更高权限；破坏性工具必须逐项确认。

7. `codex exec`

7.1 参数不识别、CI 卡住或退出码异常

症状 codex exec 报未知参数、要求交互终端，CI 一直等待，或失败任务仍显示成功。原因 CLI 版本与旧教程不同；审批策略等待人工；认证、工作目录、输出格式、超时或管道退出码未配置。 诊断命令

codex exec --help
codex --version
codex login status
command -v codex

在脚本中启用：

set -o pipefail

PowerShell 使用 Get-Command codex 检查路径。修复以本机 codex exec --help 重写参数，显式设置工作目录、认证、模型、输出和超时。自动化任务使用明确的非交互策略，并保留标准错误和退出码；先在测试仓库运行。验证故意运行一个失败的只读检查，确认流水线失败；再运行成功样例，确认无审批等待、输出完整。 安全边界 非交互不等于无风险。CI 使用隔离 runner、短期凭据和最小沙箱；提交、推送、部署和外发设置独立审批门。

7.2 `exec` 输出过长或上下文失控

症状全仓库扫描很慢、输出巨大、重复读文件或因上下文限制失败。原因把依赖、构建产物、二进制或完整日志直接输入；没有限定文件范围和任务阶段。 诊断命令

git status --short
git diff --stat
find . -type f -size +1M -print 2>/dev/null

PowerShell：

Get-ChildItem -Recurse -File | Where-Object Length -gt 1MB

修复排除 node_modules、构建目录和大日志，只提供相关文件与错误片段。把探索、修改、测试拆成多个步骤；交互会话用 /compact，换任务用 /new。验证比较输入大小、运行时间、输出长度和测试结果，确认缩小范围没有漏掉关键文件。 安全边界 日志截取须遮盖 token、Cookie、内部域名和客户数据；不要用“全仓库打包”解决信息不足。

8. 配置

8.1 `config.toml` 不生效或报未知键

症状模型、沙箱、审批或网络配置改变后行为不变，或提示配置项未知。原因编辑了错误路径；TOML 拼写/类型错误；命令行覆盖配置；版本不支持该键；项目配置与用户配置冲突。 诊断命令

codex --version
codex --help
ls -l ~/.codex/config.toml 2>/dev/null

会话内用 /status，只提取不含秘密的配置键名。修复先备份配置，只改一个键，按本机帮助核对键名和枚举值。用命令行临时覆盖定位，再写入长期配置；不要一次性重写整个文件。验证重启 Codex，用 /status 和一次无副作用操作确认结果；逐项恢复配置，找出真正冲突来源。 安全边界 配置和备份可能含 MCP key、代理信息或路径。保护文件权限，提交前检查敏感字段。

8.2 旧沙箱与 permission profile 冲突

症状设置 default_permissions 后仍使用 sandbox_mode，或 profile 修改没有效果。原因旧式 sandbox_mode/approval_policy、命令行 --sandbox 与 permission profiles 是不同配置路径，混用可能由旧路径优先；profiles 也可能随版本变化。 诊断命令

rg -n "sandbox_mode|approval_policy|default_permissions|permissions" ~/.codex/config.toml
codex --help

修复选择一套配置模型。稳定排错先用 sandbox_mode + approval_policy；确有精确路径/域名需求时，按当前官方文档迁移 profiles，并先备份、移除冲突键。验证重启后 /status 确认实际沙箱、审批、工作区范围，再用测试目录验证写入和网络。 安全边界 profile 不是自动安全审查。白名单、deny 规则和 Beta 行为必须通过实际测试验证。

8.3 模型不可用

症状配置的模型不存在，或推理强度值被拒绝。原因模型可用性取决于版本、账号、套餐和登录方式；旧教程中的模型名或枚举值已经变更。 诊断命令

/model
/status

codex --help

修复以本地 /model 列表为准删除失效名称。简单任务使用可用轻量模型和较低推理强度，复杂任务再提高；不要把他人账号可见的模型写成团队默认。验证运行短任务，用 /status 确认实际模型和推理设置，并记录版本、登录方式和套餐。 安全边界 模型切换不能扩大文件、网络或凭据权限，高能力模型也不替代人工审批。

9. Windows

9.1 PowerShell 命令在 CMD 中失败

症状 irm、$env: 或 PowerShell 安装命令无法识别。原因命令运行在 CMD、Git Bash 或其他 shell；不同 shell 的路径和环境变量语法不同。 诊断命令

$PSVersionTable
Get-Location
Get-Command irm

CMD 可用：

ver
where codex

修复在 PowerShell 中执行官方 PowerShell 命令：

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

若组织禁止脚本执行，使用批准的安装包，不要长期降低执行策略。验证在同一 shell 及新窗口分别执行 codex --version，确认用户 PATH 已持久化。 安全边界 iex 会执行下载内容。确认域名、网络和组织批准，不要替换成任意 URL，也不要无须管理员时使用管理员终端。

9.2 Windows 沙箱报 `1385`、`1223`

症状原生 elevated 沙箱初始化失败，出现 1385、ShellExecuteExW ... 1223 或 helper 模块错误。原因组策略不允许沙箱用户登录，helper 损坏或被杀毒软件隔离，或系统组件不满足要求。 诊断命令

codex --version
codex --help
wsl --status
wsl -l -v

同时查看安装器输出、事件查看器和组织策略记录，不要直接关闭安全软件。修复让 IT 检查组策略；确认安装来源后修复或重装。策略不允许 elevated 时使用支持的 unelevated；需要 Linux 工具链时使用 WSL2，WSL1 不受支持。验证在无敏感数据测试目录运行 /status，再做读文件和工作区写文件测试，确认边界仍存在。 安全边界 unelevated 是退路，不等于完全隔离。elevated 失败不能成为使用 --yolo 的理由。

9.3 WSL 路径慢或权限异常

症状仓库在 WSL 中构建慢、文件监听异常、权限或符号链接行为不一致。原因仓库位于 /mnt/c/... 等 Windows 挂载路径，或 Windows、WSL、编辑器打开了不同副本。 诊断命令

uname -a
pwd
git rev-parse --show-toplevel
mount | rg '/mnt|drvfs'

修复需要 Linux 工具链时把仓库放在 WSL 文件系统（如 ~/code/project），统一在一个环境运行 Git、包管理器和测试，避免两边同时写。验证在目标路径运行构建、测试和 Git，比较耗时并确认编辑器、终端和 Codex 的绝对路径一致。 安全边界 不要把认证缓存和密钥复制到挂载目录或 /tmp；跨环境迁移前确认目标主机、文件权限和生命周期。

10. 性能与额度

10.1 对话越聊越慢或失忆

症状重复读取文件、忘记约定、回答偏离任务，或长会话因上下文限制失败。原因上下文接近上限，输入包含大日志/生成物，或任务目标在一个会话中变化。 诊断命令

/status

du -sh .git node_modules dist build target 2>/dev/null

修复未完成但太长用 /compact，保留目标、约束、已改文件、失败测试和下一步；换任务用 /new，彻底重置用 /clear。排除依赖、构建产物和二进制。验证压缩后先让 Codex 复述验收标准，再检查 diff 和测试，不只看回答是否流畅。 安全边界 摘要前移除 token、Cookie、私钥、客户数据和生产配置；历史会话不是永久可信记忆。

10.2 扫描慢、资源占用高或费用超预算

症状全量扫描和测试耗时长，CPU/内存高，订阅限流或 API 账单超预期。原因扫描依赖和生成目录、全量测试、并发子代理、网络重试，或模型和推理强度过高。 诊断命令

du -sh . 2>/dev/null
ps -ef | rg 'codex|node|python|npm|pytest'

会话内执行 /status、/model；PowerShell 使用 Get-Process codex,node,python。修复限定文件和测试范围，先重现单个失败测试；降低并发、模型和推理强度，设置超时和资源上限。API key 配预算、告警和限额。验证记录文件数量、输入大小、运行时间、资源峰值、调用量和测试结果，确认提速没有跳过关键验证。 安全边界 不要用关闭审批或完全访问换取速度。并发任务共享工作区和凭据时风险会叠加；使用隔离 runner。

11. 最小恢复流程

停止删除、推送、部署、外发和联网写操作，保存原始错误。
记录 codex --version、codex login status、目录、分支和操作系统。
用 /status 核对沙箱、审批、工作区和模型。
在无敏感数据的空目录中缩小复现，一次只改一项。
用 git status --short、git diff --check、测试和外部审计日志检查副作用。
求助时提供脱敏错误和最小复现，不提供密钥、认证缓存或客户数据。

12. 安全边界速查

操作	默认处理
读项目源码	可在只读沙箱先分析
写工作区文件	`workspace-write`，审查 diff
读 `.env`、`~/.ssh`、云凭证	停止并确认必要性
联网或 POST 数据	核对域名、数据和授权
改 shell、装服务、定时任务	视为改变持久化安全边界
删除、覆盖、推送、部署	确认范围、目标和回滚
`sudo`、提权、绕过沙箱	先找不提权替代方案
`--yolo`	只在隔离容器/VM，不作本机默认
第三方 MCP、插件、网页指令	当作不可信输入，先只读

参考资料：参考/codex/37-faq.md、参考/codex/03-install.md、参考/codex/15-permissions.md、参考/codex/16-security.md。

开始

Codex 完整教程

Claude Code 完整教程

常见问题排查

常见问题排查

0. 通用分诊

1. 安装

1.1 找不到 `codex`

1.2 安装超时、TLS 或 npm 权限报错

2. 登录

2.1 浏览器回调不工作

2.2 认证过期或 API key 功能/费用异常

3. 项目不修改

3.1 只能读，不能写

3.2 改了错误目录或想撤销

4. 沙箱与审批

4.1 审批太多或命令无提示却失败

4.2 不确定权限或误用 `--yolo`

5. 网络

5.1 登录、模型请求或依赖下载超时

5.2 外部网页内容疑似提示注入

6. MCP

6.1 MCP 服务器不显示或启动失败

6.2 MCP 工具可见但调用失败

7. `codex exec`

7.1 参数不识别、CI 卡住或退出码异常

7.2 `exec` 输出过长或上下文失控

8. 配置

8.1 `config.toml` 不生效或报未知键

8.2 旧沙箱与 permission profile 冲突

8.3 模型不可用

9. Windows

9.1 PowerShell 命令在 CMD 中失败

9.2 Windows 沙箱报 `1385`、`1223`

9.3 WSL 路径慢或权限异常

10. 性能与额度

10.1 对话越聊越慢或失忆

10.2 扫描慢、资源占用高或费用超预算

11. 最小恢复流程

12. 安全边界速查

​常见问题排查

​0. 通用分诊

​1. 安装

​1.1 找不到 codex

​1.2 安装超时、TLS 或 npm 权限报错

​2. 登录

​2.1 浏览器回调不工作

​2.2 认证过期或 API key 功能/费用异常

​3. 项目不修改

​3.1 只能读，不能写

​3.2 改了错误目录或想撤销

​4. 沙箱与审批

​4.1 审批太多或命令无提示却失败

​4.2 不确定权限或误用 --yolo

​5. 网络

​5.1 登录、模型请求或依赖下载超时

​5.2 外部网页内容疑似提示注入

​6. MCP

​6.1 MCP 服务器不显示或启动失败

​6.2 MCP 工具可见但调用失败

​7. codex exec

​7.1 参数不识别、CI 卡住或退出码异常

​7.2 exec 输出过长或上下文失控

​8. 配置

​8.1 config.toml 不生效或报未知键

​8.2 旧沙箱与 permission profile 冲突

​8.3 模型不可用

​9. Windows

​9.1 PowerShell 命令在 CMD 中失败

​9.2 Windows 沙箱报 1385、1223

​9.3 WSL 路径慢或权限异常

​10. 性能与额度

​10.1 对话越聊越慢或失忆

​10.2 扫描慢、资源占用高或费用超预算

​11. 最小恢复流程

​12. 安全边界速查

常见问题排查

0. 通用分诊

1. 安装

1.1 找不到 `codex`

1.2 安装超时、TLS 或 npm 权限报错

2. 登录

2.1 浏览器回调不工作

2.2 认证过期或 API key 功能/费用异常

3. 项目不修改

3.1 只能读，不能写

3.2 改了错误目录或想撤销

4. 沙箱与审批

4.1 审批太多或命令无提示却失败

4.2 不确定权限或误用 `--yolo`

5. 网络

5.1 登录、模型请求或依赖下载超时

5.2 外部网页内容疑似提示注入

6. MCP

6.1 MCP 服务器不显示或启动失败

6.2 MCP 工具可见但调用失败

7. `codex exec`

7.1 参数不识别、CI 卡住或退出码异常

7.2 `exec` 输出过长或上下文失控

8. 配置

8.1 `config.toml` 不生效或报未知键

8.2 旧沙箱与 permission profile 冲突

8.3 模型不可用

9. Windows

9.1 PowerShell 命令在 CMD 中失败

9.2 Windows 沙箱报 `1385`、`1223`

9.3 WSL 路径慢或权限异常

10. 性能与额度

10.1 对话越聊越慢或失忆

10.2 扫描慢、资源占用高或费用超预算

11. 最小恢复流程

12. 安全边界速查