排查 App 问题

这篇整理 Codex App 常见问题、日志位置和恢复方式。

排查 Codex App 时，先判断问题属于哪一层：sidebar / thread 状态、review pane、worktree、local environment、macOS permission、terminal、CLI/App version drift、logs。不同层的处理方式不同，不要一上来就重装 App 或删除项目。

flowchart TB
    Q["🚨 现象"]
    L1["Sidebar / threads"]
    L2["Review pane / Git diff"]
    L3["Worktree / 当前目录"]
    L4["Local env / .codex setup"]
    L5["macOS 权限"]
    L6["Terminal"]
    L7["CLI vs App 版本"]
    L8["Logs / 日志"]
    Q --> L1
    Q --> L2
    Q --> L3
    Q --> L4
    Q --> L5
    Q --> L6
    Q --> L7
    Q --> L8
    L8 -.->|脱敏后再分享| Share["📤 提交 issue"]

Frequently Asked Questions

Files appear in the side panel that Codex didn't edit

如果 project 位于 Git repository 中，review panel 会根据整个 project 的 Git state 自动显示 changes，其中也包括不是 Codex 做出的 changes。

在 review pane 中，你可以：

• 在 staged changes 和尚未 staged 的 changes 之间切换。
• 把当前 branch 和 main 对比。
• 如果只想看上一个 Codex turn 的改动，把 diff pane 切换到 "Last turn changes" view。

Review pane 使用方式：

https://developers.openai.com/codex/app/review

Remove a project from the sidebar

从 sidebar 移除 project：

1. hover project name。
2. 点击 three dots。
3. 选择 Remove。

恢复方式：

• 点击 Threads 旁边的 Add new project 重新添加。
• 或使用 Cmd+O。

Find archived threads

Archived threads 可以在 Settings 中找到。unarchive 某个 thread 后，它会重新出现在 sidebar 的原始位置。

Only some threads appear in the sidebar

sidebar 会根据 project state 过滤 threads。如果你看不到某些 threads：

1. 点击 Threads label 旁边的 filter icon。
2. 切换到 Chronological。
3. 如果仍然看不到，打开 Settings，检查 archived chats 或 archived threads section。

Code doesn't run on a worktree

Worktrees 创建在不同目录中，只继承已经 check into Git 的 files。根据你的 dependency 和 tooling 管理方式，worktree 可能需要额外 setup。

解决方式：

• 用 local environment 在 worktree 上运行 setup scripts。
• 或把 changes checkout 到你常规的 local project 中。

Worktrees 文档：

https://developers.openai.com/codex/app/worktrees

排查顺序：

1. 在 worktree terminal 里跑 pwd，确认当前目录。
2. 跑 git status，确认 branch / detached HEAD 状态。
3. 检查依赖目录是否存在。
4. 检查 .codex local environment setup script 是否运行。
5. 手动跑最小 build 或 test。
6. 如果只在 Local 能跑，考虑 handoff 回 Local。

App doesn't pick up a teammate's shared local environment

local environment configuration 必须位于 project root 的 .codex folder 中。

如果你在 monorepo 中工作，并且里面有多个 projects，要确保你打开的是包含 .codex folder 的那个 project directory。

Codex asks to access Apple Music

根据任务不同，Codex 可能需要浏览 file system。macOS 上有些 directories 需要用户额外 approval，包括 Music、Downloads 和 Desktop。

如果 Codex 需要读取你的 home directory，macOS 会提示你批准这些 folders 的访问权限。

Automations create many worktrees

高频 automations 会随时间创建很多 worktrees。把不再需要的 automation runs archive 掉，并避免 pinning runs，除非你确实打算保留它们的 worktrees。

Recover a prompt after selecting the wrong target

如果你不小心用错误 target 启动 thread，例如 Local、Worktree 或 Cloud，可以 cancel 当前 run，然后在 composer 中按 up arrow key 恢复之前的 prompt。

Feature is working in the Codex CLI but not in the Codex app

Codex App 和 Codex CLI 使用同一个底层 Codex agent 和 configuration，但它们在任意时刻可能依赖不同版本的 agent。有些 experimental features 也可能先进入 Codex CLI。

查看系统中 Codex CLI 版本：

codex --version

查看 Codex App bundle 中的 Codex 版本：

/Applications/Codex.app/Contents/Resources/codex --version

Feedback and logs

在 message composer 中输入 /，可以向团队提供 feedback。如果你在已有 conversation 中触发 feedback，可以选择把 existing session 和 feedback 一起分享。提交后，你会收到一个 session ID，可以把它提供给团队。

报告 issue：

1. 先在 Codex GitHub repo 查找 existing issues。
2. 如果没有对应问题，再 open a new GitHub issue。

更多 logs 位置：

如果要分享 logs，先 review，确认里面没有 sensitive information。

Stuck states and recovery patterns

如果 thread 看起来 stuck：

1. 检查 Codex 是否正在等待 approval。
2. 打开 terminal，运行一个基础命令，例如 git status。
3. 用更小、更聚焦的 prompt 启动一个新 thread。

如果你误取消了 worktree creation 并丢失 prompt，在 composer 中按 up arrow key 恢复。

分层排障表

版本差异怎么确认

Codex App 和 Codex CLI 使用同一个底层 agent 和 configuration，但任意时刻可能依赖不同版本。有些 experimental features 可能先进入 CLI。

查看 CLI 版本：

codex --version

查看 macOS Codex App bundle 里的 Codex 版本：

/Applications/Codex.app/Contents/Resources/codex --version

如果同一功能 CLI 可用、App 不可用，先记录两个版本，再查 changelog 或 issue。

分享日志前的脱敏

日志可能包含：

• 本机路径。
• repository name。
• prompt 内容。
• terminal output。
• error stack。
• 文件名和 diff。
• 可能的 secrets 或 token。

分享前至少做三件事：

1. 搜索 token、key、secret、Authorization、.env。
2. 移除本机隐私路径和账号信息。
3. 只截取与问题相关的时间窗口。

Terminal issues

Terminal appears stuck

处理步骤：

1. 关闭 terminal panel。
2. 用 Cmd+J 重新打开。
3. 重新运行基础命令，例如 pwd 或 git status。

如果 commands 行为和预期不同，先在 terminal 中确认当前 directory 和 branch。

如果仍然 stuck，等 active Codex threads 完成后，重启 App。

Fonts aren't rendering correctly

Codex App 内 review pane、integrated terminal，以及其他 code display 都使用同一套 font。

你可以在 Settings pane 中配置 Code font。

官方资料

• Codex App troubleshooting
• Review pane
• Worktrees
• Local environments
• Codex GitHub issues

接下来去哪