> ## Documentation Index > Fetch the complete documentation index at: https://aicoding.cscitech.top/llms.txt > Use this file to discover all available pages before exploring further. # 常见问题排查 > 按安装、登录、项目写入、沙箱审批、网络、MCP、exec、配置、Windows 和性能分类，提供 Codex 的诊断命令、修复步骤、验证方法与安全边界。 # 常见问题排查 本页按故障现象组织排错步骤。每项都包含**症状、原因、诊断命令、修复、验证、安全边界**。先收集证据，再做最小修改；命令、参数和配置项以本机 `--help` 与官方文档为准。 ## 0. 通用分诊 **症状** 不知道问题属于安装、认证、权限、网络还是项目本身，或 Codex 的总结与实际行为不一致。 **原因** 版本、登录、工作目录和权限经常叠加影响。未登录可能看起来像网络故障，沙箱拒绝可能看起来像文件权限错误。 **诊断命令** ```bash theme={null} codex --version codex --help codex login status git status --short pwd ``` 进入会话后执行： ```text theme={null} /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 安装了多个版本。 **诊断命令** ```bash theme={null} which -a codex command -v codex printf '%s\n' "$PATH" npm config get prefix ``` PowerShell： ```powershell theme={null} Get-Command codex -All where.exe codex $env:Path -split ';' ``` **修复** 按安装器输出把实际目录加入用户级 `PATH`，关闭并重新打开终端。若存在多个路径，保留一个安装来源，必要时移除多余 npm 包： ```bash theme={null} npm uninstall -g @openai/codex ``` **验证** 在新终端执行 `codex --version` 和 `codex --help`，确认路径和版本符合预期。 **安全边界** 不要用管理员权限或 `sudo npm install -g` 作为第一反应。优先采用用户目录、版本管理器或官方独立安装器。 ### 1.2 安装超时、TLS 或 npm 权限报错 **症状** 安装脚本卡住、下载超时、证书错误，或 npm 报 `EACCES`/`EPERM`。 **原因** 终端没有走代理，企业 TLS 代理使用私有 CA，或 npm 全局目录属于系统用户。浏览器能访问不代表 Codex 的终端能访问。 **诊断命令** ```bash theme={null} curl -I https://chatgpt.com curl -I https://api.openai.com printf '%s\n' "$HTTP_PROXY" "$HTTPS_PROXY" ``` PowerShell： ```powershell theme={null} 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 回调失败。 **原因** 当前是远程/无头环境，浏览器与终端不在同一台机器，回调端口被占用，或防火墙拦截了本地回调。 **诊断命令** ```bash theme={null} codex login status codex login --help lsof -nP -iTCP:1455 -sTCP:LISTEN 2>/dev/null || true ``` PowerShell： ```powershell theme={null} Get-NetTCPConnection -LocalPort 1455 -ErrorAction SilentlyContinue ``` **修复** 远程环境优先使用设备码： ```bash theme={null} codex login --device-auth ``` 在可信浏览器打开终端显示的链接并输入一次性验证码。设备码不可用时，按官方支持的 SSH 端口转发，或通过受保护通道迁移认证缓存。 **验证** `codex login status` 显示有效认证后，在无敏感数据的测试目录启动 Codex，执行一个只读请求。 **安全边界** `~/.codex/auth.json` 等同密码，迁移时使用权限受控通道，完成后确认权限；不提交、不上传、不贴出，也不要把设备码发给他人。 ### 2.2 认证过期或 API key 功能/费用异常 **症状** 频繁要求重新登录；API key 能运行本地 CLI，但部分工作区/云端功能不可用，或费用超预期。 **原因** 令牌刷新失败、缓存损坏、系统时间不正确或另一客户端登出。API key 按 API 用量计费，不等于 ChatGPT 订阅额度，部分功能依赖 ChatGPT 登录。 **诊断命令** ```bash theme={null} codex login status codex --version date ls -l ~/.codex/auth.json 2>/dev/null ``` 会话内执行 `/status` 和 `/model`，不要打印认证文件内容。 **修复** 确认时间和网络后重新登录： ```bash theme={null} codex logout codex login ``` 需要工作区功能时使用 ChatGPT 账号；CI 使用 API key 时设置预算、限额和最小权限。模型和推理强度按任务调整。 **验证** 连续启动两次确认登录态可复用，并核对 `/status` 的认证方式、模型和推理设置；在用量页面核对账单。 **安全边界** 不要在共享机器或公开 CI 日志使用高权限 key。认证路径、计费路径和文件权限是三件事，不能互相替代。 *** ## 3. 项目不修改 ### 3.1 只能读，不能写 **症状** 能解释源码，但创建不了文件或修改被沙箱拒绝。 **原因** 当前为 `read-only`，项目未被信任，启动目录不是仓库根目录，目标路径在工作区外，或文件系统本身只读。 **诊断命令** ```text theme={null} /status ``` ```bash theme={null} pwd git rev-parse --show-toplevel 2>/dev/null || true ls -ld . ``` **修复** 进入正确的项目根目录，建立 Git 检查点后使用日常组合： ```bash theme={null} 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。 **诊断命令** ```bash theme={null} pwd realpath . 2>/dev/null || true git rev-parse --show-toplevel git status --short git diff --name-only ``` **修复** 停止后续任务，先保存 diff。确认文件没有他人修改后，可撤销明确的单文件： ```bash theme={null} 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` 网络默认关闭。 **诊断命令** ```text theme={null} /status ``` ```bash theme={null} codex --help ``` **修复** 可信且有 Git 检查点的项目使用： ```bash theme={null} codex --sandbox workspace-write --ask-for-approval on-request ``` 确需下载依赖时短时开启网络： ```toml theme={null} [sandbox_workspace_write] network_access = true ``` 完成后关闭。不要用 `never` 或完全访问掩盖范围问题。 **验证** 用 `/status` 确认沙箱、审批和工作区；分别测试读文件、写工作区和访问工作区外路径。开网后检查依赖锁文件和 diff。 **安全边界** 审批少不代表权限小。`never` 只是不询问；联网会放大提示注入和数据外发风险。 ### 4.2 不确定权限或误用 `--yolo` **症状** 不同项目行为不一致，或想用 `--yolo` 解决所有拒绝。 **原因** 项目级/用户级配置、命令行参数和 profile 叠加；没有 Git 的目录通常更适合先只读。`--yolo` 同时移除沙箱和审批。 **诊断命令** ```text theme={null} /status ``` ```bash theme={null} 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 与浏览器环境不同；沙箱网络默认关闭；服务端也可能限流。 **诊断命令** ```bash theme={null} 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： ```powershell theme={null} 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 后，提出无关的联网、读凭证、改系统或外发操作。 **原因** 外部内容是数据，不是你的授权；实时网页和开放网络扩大了恶意指令入口。 **诊断命令** ```text theme={null} /status ``` 逐项查看待审批命令的路径、参数、域名和发送内容。 **修复** 陌生项目先用 `read-only`，拒绝与原任务无关的命令；不要把不可信内容通过管道直接喂给 Codex。需要外部服务时使用容器/VM和精确域名白名单。 **验证** 确认摘要任务无需读取凭证或联网；对批准的请求记录目标域名和数据内容。 **安全边界** 联网、读 `.env`/`~/.ssh`、改 shell 配置、装服务、删除文件、提权和外发都必须人工审查。“项目标准流程”不能代替授权。 *** ## 6. MCP ### 6.1 MCP 服务器不显示或启动失败 **症状** 看不到 MCP 工具，或报命令不存在、依赖缺失、握手失败、进程退出。 **原因** 启动命令、参数、工作目录、传输方式或环境变量不匹配；沙箱阻止文件/网络访问。 **诊断命令** ```bash theme={null} codex --help command -v 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 版本与旧教程不同；审批策略等待人工；认证、工作目录、输出格式、超时或管道退出码未配置。 **诊断命令** ```bash theme={null} codex exec --help codex --version codex login status command -v codex ``` 在脚本中启用： ```bash theme={null} set -o pipefail ``` PowerShell 使用 `Get-Command codex` 检查路径。 **修复** 以本机 `codex exec --help` 重写参数，显式设置工作目录、认证、模型、输出和超时。自动化任务使用明确的非交互策略，并保留标准错误和退出码；先在测试仓库运行。 **验证** 故意运行一个失败的只读检查，确认流水线失败；再运行成功样例，确认无审批等待、输出完整。 **安全边界** 非交互不等于无风险。CI 使用隔离 runner、短期凭据和最小沙箱；提交、推送、部署和外发设置独立审批门。 ### 7.2 `exec` 输出过长或上下文失控 **症状** 全仓库扫描很慢、输出巨大、重复读文件或因上下文限制失败。 **原因** 把依赖、构建产物、二进制或完整日志直接输入；没有限定文件范围和任务阶段。 **诊断命令** ```bash theme={null} git status --short git diff --stat find . -type f -size +1M -print 2>/dev/null ``` PowerShell： ```powershell theme={null} Get-ChildItem -Recurse -File | Where-Object Length -gt 1MB ``` **修复** 排除 `node_modules`、构建目录和大日志，只提供相关文件与错误片段。把探索、修改、测试拆成多个步骤；交互会话用 `/compact`，换任务用 `/new`。 **验证** 比较输入大小、运行时间、输出长度和测试结果，确认缩小范围没有漏掉关键文件。 **安全边界** 日志截取须遮盖 token、Cookie、内部域名和客户数据；不要用“全仓库打包”解决信息不足。 *** ## 8. 配置 ### 8.1 `config.toml` 不生效或报未知键 **症状** 模型、沙箱、审批或网络配置改变后行为不变，或提示配置项未知。 **原因** 编辑了错误路径；TOML 拼写/类型错误；命令行覆盖配置；版本不支持该键；项目配置与用户配置冲突。 **诊断命令** ```bash theme={null} 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 也可能随版本变化。 **诊断命令** ```bash theme={null} 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 模型不可用 **症状** 配置的模型不存在，或推理强度值被拒绝。 **原因** 模型可用性取决于版本、账号、套餐和登录方式；旧教程中的模型名或枚举值已经变更。 **诊断命令** ```text theme={null} /model /status ``` ```bash theme={null} codex --help ``` **修复** 以本地 `/model` 列表为准删除失效名称。简单任务使用可用轻量模型和较低推理强度，复杂任务再提高；不要把他人账号可见的模型写成团队默认。 **验证** 运行短任务，用 `/status` 确认实际模型和推理设置，并记录版本、登录方式和套餐。 **安全边界** 模型切换不能扩大文件、网络或凭据权限，高能力模型也不替代人工审批。 *** ## 9. Windows ### 9.1 PowerShell 命令在 CMD 中失败 **症状** `irm`、`$env:` 或 PowerShell 安装命令无法识别。 **原因** 命令运行在 CMD、Git Bash 或其他 shell；不同 shell 的路径和环境变量语法不同。 **诊断命令** ```powershell theme={null} $PSVersionTable Get-Location Get-Command irm ``` CMD 可用： ```bat theme={null} ver where codex ``` **修复** 在 PowerShell 中执行官方 PowerShell 命令： ```powershell theme={null} 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 损坏或被杀毒软件隔离，或系统组件不满足要求。 **诊断命令** ```powershell theme={null} 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、编辑器打开了不同副本。 **诊断命令** ```bash theme={null} uname -a pwd git rev-parse --show-toplevel mount | rg '/mnt|drvfs' ``` **修复** 需要 Linux 工具链时把仓库放在 WSL 文件系统（如 `~/code/project`），统一在一个环境运行 Git、包管理器和测试，避免两边同时写。 **验证** 在目标路径运行构建、测试和 Git，比较耗时并确认编辑器、终端和 Codex 的绝对路径一致。 **安全边界** 不要把认证缓存和密钥复制到挂载目录或 `/tmp`；跨环境迁移前确认目标主机、文件权限和生命周期。 *** ## 10. 性能与额度 ### 10.1 对话越聊越慢或失忆 **症状** 重复读取文件、忘记约定、回答偏离任务，或长会话因上下文限制失败。 **原因** 上下文接近上限，输入包含大日志/生成物，或任务目标在一个会话中变化。 **诊断命令** ```text theme={null} /status ``` ```bash theme={null} du -sh .git node_modules dist build target 2>/dev/null ``` **修复** 未完成但太长用 `/compact`，保留目标、约束、已改文件、失败测试和下一步；换任务用 `/new`，彻底重置用 `/clear`。排除依赖、构建产物和二进制。 **验证** 压缩后先让 Codex 复述验收标准，再检查 diff 和测试，不只看回答是否流畅。 **安全边界** 摘要前移除 token、Cookie、私钥、客户数据和生产配置；历史会话不是永久可信记忆。 ### 10.2 扫描慢、资源占用高或费用超预算 **症状** 全量扫描和测试耗时长，CPU/内存高，订阅限流或 API 账单超预期。 **原因** 扫描依赖和生成目录、全量测试、并发子代理、网络重试，或模型和推理强度过高。 **诊断命令** ```bash theme={null} 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. 最小恢复流程 1. 停止删除、推送、部署、外发和联网写操作，保存原始错误。 2. 记录 `codex --version`、`codex login status`、目录、分支和操作系统。 3. 用 `/status` 核对沙箱、审批、工作区和模型。 4. 在无敏感数据的空目录中缩小复现，一次只改一项。 5. 用 `git status --short`、`git diff --check`、测试和外部审计日志检查副作用。 6. 求助时提供脱敏错误和最小复现，不提供密钥、认证缓存或客户数据。 ## 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`。