Appearance
使用 Codex App 遇到异常时的快速排查手册。涵盖最常见的几类问题：Review 面板文件范围问题、线程找不到（归档/过滤）、Worktree 缺少依赖、本地环境配置不生效，以及应用或终端卡住时的恢复步骤和日志收集方法。
Codex App 故障排查
常见问题
Review 面板显示了 Codex 没有编辑过的文件
Review 面板反映的是 Git 仓库的完整状态，不只是 Codex 改动的部分——包括你自己的改动和其他未提交内容。
在 Review 面板里可以切换：
- Staged 和 Unstaged 视图
- 与 main 分支的对比
只想看最近一次 Codex 操作的改动：把 diff 面板切换到 Last turn changes 视图。
如何从侧边栏移除项目
悬停在项目名称上 → 点击三点菜单 → 选择 Remove。要恢复：点击 Threads 旁边的 Add new project 按钮，或按 Cmd+O。
找不到归档的线程
归档线程在设置（Settings）里查找。取消归档后线程会恢复到侧边栏原来的位置。
侧边栏只显示部分线程
侧边栏可以按项目状态过滤线程。如果缺少线程：点击 Threads 旁边的过滤图标，切换为 Chronological（按时间）。如果仍然找不到，打开 Settings 检查归档线程。
Worktree 里代码无法运行
Worktree 创建在独立目录，只继承 Git 里已提交的文件——未纳入版本控制的依赖和生成文件不会自动复制过来。
解决方案：
- 配置本地环境 Setup 脚本，在 Worktree 创建时自动安装依赖
- 或者把改动 Checkout 到普通本地项目继续工作
队友共享的本地环境配置没有生效
本地环境配置必须放在项目根目录的 .codex 文件夹里。如果是 monorepo 含多个子项目，确认打开的是包含 .codex 目录的那个子目录。
Codex 提示要访问 Apple Music（macOS）
macOS 上某些目录（Music、Downloads、Desktop 等）需要额外授权。Codex 需要读取主目录时，系统会弹窗询问这些文件夹的访问权限——这是正常的 macOS 系统权限机制，批准即可。
Automations 创建了太多 Worktree
频繁运行的 Automations 会随时间积累大量 Worktree。清理方法：归档不再需要的 Automation 运行记录，不要 Pin 不打算长期保留的运行。
误选了线程目标（Local/Worktree/Cloud），丢失了 Prompt
取消当前运行，然后在 Composer 里按上箭头键恢复上一条 Prompt。
某功能在 Codex CLI 里正常，Codex App 里没有
Codex App 和 Codex CLI 使用同一个底层 Agent 和配置，但两者可能运行不同版本，某些实验性功能会先在 CLI 里落地。
查看版本：
bash
# CLI 版本
codex --version
# macOS App 内置版本
/Applications/Codex.app/Contents/Resources/codex --version提交反馈与查看日志
在 Composer 里输入 / 打开反馈入口。在已有对话里触发反馈时，可以选择是否附带当前 session 日志。提交后会收到一个 session ID，可提供给 OpenAI 团队。
报告 Bug：
- 查看 GitHub Issues 是否已有相关记录
- 提交新 Issue
日志文件位置：
| 类型 | 路径 |
|---|---|
| App 日志（macOS） | ~/Library/Logs/com.openai.codex/YYYY/MM/DD |
| Session 记录 | $CODEX_HOME/sessions（默认 ~/.codex/sessions） |
| 归档 Session | $CODEX_HOME/archived_sessions |
分享日志前先检查是否包含敏感信息。
卡死状态与恢复
线程卡住：
- 检查 Codex 是否在等待审批
- 打开终端，运行
git status等基础命令确认环境状态 - 新建一个更聚焦、更小范围的线程重新开始
Worktree 创建被意外取消、Prompt 丢失：在 Composer 里按上箭头键恢复。
终端卡住：
- 关闭终端面板
- 用
Cmd+J重新打开 - 运行
pwd或git status确认目录和分支
如果问题持续，等待当前所有 Codex 线程完成后重启应用。
字体显示异常：Codex 在 Review 面板、集成终端和代码显示区域使用同一套字体，在 Settings 里修改 Code font 即可统一调整。
常见问题
Q: Worktree 里总是提示找不到 node_modules，每次都要手动 npm install？
A: 配置本地环境 Setup 脚本，在 Setup 脚本里加上 npm install，之后每次新建 Worktree 时会自动运行，无需手动操作。
Q: 归档的线程还能恢复吗？
A: 可以。在 Settings 的 Archived threads 区域找到对应线程，点击 Unarchive 即可恢复，线程会回到侧边栏原来的位置。