常见问题排查

本页先列出 ChatGPT 桌面应用的常见问题，再列出 Codex CLI 的问题。

桌面应用复制本节链接

审阅面板里出现了 Codex 没改过的文件复制本节链接

审阅面板显示的是整个 Git 仓库的状态，你自己改的、其他未提交的改动都会出现在里面。只想看 Codex 最近一轮改了什么，把面板切到 Last turn 视图。

侧边栏里少了一些对话复制本节链接

点 Chats 旁边的筛选图标，选 Chronological（按时间排序）。还找不到的话，打开 Settings 看 Archived chats，它可能被归档了。

想把项目从侧边栏移除 / 加回来复制本节链接

鼠标移到项目名上，点三个点，选 Remove。要加回来，点 Chats 旁边的 Add new project，或按 Cmd+O / Ctrl+O。

选错了运行位置（Local / Worktree / Cloud）复制本节链接

取消当前这次运行，然后在输入框里按 ↑，就能找回刚才的提示词，重新选择后再发。

在 worktree 里代码跑不起来复制本节链接

worktree 在另一个目录里创建，默认只包含 Git 里提交过的文件，依赖和被忽略的配置文件（如 .env）不会带过去。可以配置本地环境的初始化脚本，或用 .worktreeinclude 复制需要的被忽略文件；也可以把改动检出到你平常的项目目录里运行。

macOS 弹窗要求访问"音乐"、"下载"等文件夹复制本节链接

macOS 上这些目录需要单独授权。Codex 要读取你的家目录时，系统会弹窗请你确认。只批准任务确实需要的目录。

权限菜单里没有 Approve for me，或者是灰色的复制本节链接

1. 先更新桌面应用，并在你要用的那个对话里查看权限菜单（本地和云端的选项可能不同）；
2. 检查本地配置里是否显式写了 features.guardian_approval = false，以及权限配置、审批策略、审批人（approvals reviewer）的设置；
3. 工作区账号可能被组织策略限制，本地设置无法覆盖，需要请管理员检查。

CLI 里能用的功能，桌面应用里没有复制本节链接

桌面应用和 CLI 内置的 Codex 版本可能不同，新功能有时先到其中一个。可以分别查看版本：

# CLI 的版本
codex --version

# macOS 上桌面应用内置的 Codex 版本
/Applications/Codex.app/Contents/Resources/codex --version

对话好像卡住了复制本节链接

1. 看看 Codex 是不是在等你批准某个操作；
2. 打开集成终端，运行一条简单命令，比如 git status；
3. 开一个新对话，把任务拆小、说得更具体。

集成终端没反应时，先关掉终端面板，再按 Ctrl+` 重新打开；还是不行，就等进行中的对话结束后重启应用。

Windows：PowerShell 提示禁止运行脚本复制本节链接

第一次在 PowerShell 里用 npm 等工具时，可能会看到类似 npm.ps1 cannot be loaded because running scripts is disabled on this system 的错误。常见的解决办法是把执行策略改为 RemoteSigned（修改前请先阅读微软的执行策略说明）：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

Windows：Git 相关功能用不了复制本节链接

Windows 上没有装原生 Git 时，部分功能无法使用。在 PowerShell 里安装：

winget install --id Git.Git

Windows：从 \\wsl$ 打开的项目识别不到 Git复制本节链接

目前最稳妥的做法是：把项目放在 Windows 磁盘上，在 WSL 里通过 /mnt/<盘符>/... 访问。如果希望 Codex 代理本身运行在 WSL 里，在 Settings 里把代理从 Windows 原生切换到 WSL，然后重启应用。

Windows：需要用管理员权限运行命令复制本节链接

以管理员身份启动桌面应用（开始菜单里找到应用，选择 Run as administrator），Codex 代理会继承这个权限级别。没有必要时不建议这样做。

桌面应用和 WSL 里的 CLI 配置不同步复制本节链接

Windows 桌面应用用的是 %USERPROFILE%\.codex，而 WSL 里的 CLI 默认用 Linux 家目录下的 ~/.codex，两边的配置、登录和会话默认不共享。想共享的话，在 WSL 里设置：

export CODEX_HOME=/mnt/c/Users/<Windows 用户名>/.codex

日志在哪复制本节链接

• macOS 应用日志：~/Library/Logs/com.openai.codex/YYYY/MM/DD
• 会话记录：~/.codex/sessions
• 归档的会话：~/.codex/archived_sessions

在输入框里输入 /feedback 可以把日志发给官方团队。分享前请检查里面有没有敏感信息。

Codex CLI复制本节链接

用 CLI 遇到问题时，先运行：

codex doctor

它会生成一份本地诊断报告，检查安装、配置、登录、运行环境、Git、终端等几个方面。很多问题看报告就能定位。

安装与启动复制本节链接

提示 codex: command not found复制本节链接

• 新开一个终端窗口再试，让 PATH 的变更生效；

• 用 npm 安装时，确认 npm 的全局 bin 目录在 PATH 里；

• 在 WSL 里用 VS Code 时，Codex 必须装在 WSL 内部。在 WSL 终端里检查：

  复制代码

  which codex || echo "codex not found"

升级后启动不了，提示配置有问题复制本节链接

最常见的原因是配置文件里还留着已退役的设置：

检查配置时，--strict-config 很有用：配置里有当前版本不认识的字段时，它会直接报错，而不是悄悄忽略：

codex --strict-config

脚本里的 --full-auto 不能用了复制本节链接

--full-auto 已经移除。改用：

codex exec --sandbox workspace-write "<任务>"
# 或
codex exec --approve-for-me "<任务>"

沙箱相关复制本节链接

Linux / WSL 启动时警告找不到 bwrap复制本节链接

Linux 和 WSL2 的沙箱依赖 bubblewrap：

sudo apt install bubblewrap   # Ubuntu / Debian
sudo dnf install bubblewrap   # Fedora

Ubuntu 24.04 装了 bubblewrap 仍提示无法创建 user namespace复制本节链接

这是 AppArmor 的限制。官方给的解决办法是加载 bwrap 的 AppArmor 配置：

sudo apt update
sudo apt install apparmor-profiles apparmor-utils
sudo install -m 0644 \
  /usr/share/apparmor/extra-profiles/bwrap-userns-restrict \
  /etc/apparmor.d/bwrap-userns-restrict
sudo apparmor_parser -r /etc/apparmor.d/bwrap-userns-restrict

WSL1 用不了复制本节链接

从 Codex 0.115 起不再支持 WSL1，请升级到 WSL2。

命令装不了依赖 / 访问不了网络复制本节链接

本地沙箱默认禁止命令联网。Codex 需要联网时会请求审批，批准即可；如果项目经常需要，可以在配置里打开：

[sandbox_workspace_write]
network_access = true

Codex 改不了 .git 或 .codex 目录里的文件复制本节链接

这是设计如此：workspace-write 模式下 .git、.codex、.agents、.aws 都是只读的受保护路径。

配置与说明不生效复制本节链接

• 配置改了没效果：在 Codex 里输入 /debug-config，看每一层配置的实际值和优先级。
• 项目里的 .codex/config.toml 没加载：项目配置只在你信任该项目时才加载。
• AGENTS.md 没生效：确认文件不是空的，没有被上层的 AGENTS.override.md 覆盖，然后重启 Codex。
• CODEX_HOME 指错了：运行 echo $CODEX_HOME。如果有值，Codex 读的是那个目录，而不是 ~/.codex。

codex exec 拒绝运行复制本节链接

codex exec 默认要求在 Git 仓库里运行。确认环境安全时，可以加 --skip-git-repo-check。

任务卡住了复制本节链接

模型选不到复制本节链接

/model 只显示你的账号可用的模型。如果某个模型不在列表里，说明当前套餐或工作区没有开放，换一个列表里有的即可。

想看更详细的日志复制本节链接

# 把 TUI 日志写到指定目录
codex -c log_dir=./.codex-log
tail -F ./.codex-log/codex-tui.log

会话记录在 ~/.codex/sessions。在 Codex 里输入 /feedback，可以把日志发给官方团队。

还是解决不了复制本节链接

• 账号、登录、额度相关的问题，见登录问题和 FAQ；
• Codex 本身的 bug，可以在 openai/codex Issues 搜索或提交；
• 账号交付相关的问题，请联系售后。

参考资料复制本节链接

• Troubleshooting（官方）
• ChatGPT desktop app for Windows：Troubleshooting and FAQ（官方）
• codex doctor 命令参考（官方）
• Sandbox：Prerequisites（官方）
• Migrate from the retired untrusted approval policy（官方）
• Installing & building：Tracing / verbose logging（GitHub）