---
title: "排查 App 问题"
description: "这篇整理 Codex App 常见问题、日志位置和恢复方式。"
verifiedAt: "2026-05-07"
---

> [!NOTE]
> **这一篇用 10 分钟换什么**：把 Codex App 排障从"重装试试"重新理解成**8 层定位**——sidebar / review pane / worktree / local env / macOS 权限 / terminal / CLI 与 App 版本差 / logs。读完后你能用一张表锁定问题层级，而不是动不动就重启或删除项目。

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

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

```mermaid
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](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](codex://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](codex://settings)，检查 archived chats 或 archived threads section。

### Code doesn't run on a worktree

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

解决方式：

- 用 [local environment](https://developers.openai.com/codex/app/local-environments) 在 worktree 上运行 setup scripts。
- 或把 changes checkout 到你常规的 local project 中。

Worktrees 文档：

[https://developers.openai.com/codex/app/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 版本：

```bash
codex --version
```

查看 Codex App bundle 中的 Codex 版本：

```bash
/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](https://github.com/openai/codex/issues)。
2. 如果没有对应问题，再 [open a new GitHub issue](https://github.com/openai/codex/issues/new?template=2-bug-report.yml&steps=Uploaded%20thread%3A%20019c0d37-d2b6-74c0-918f-0e64af9b6e14)。

更多 logs 位置：

| 内容 | 位置 |
| --- | --- |
| App logs (macOS) | `~/Library/Logs/com.openai.codex/YYYY/MM/DD` |
| Session transcripts | `$CODEX_HOME/sessions`，默认 `~/.codex/sessions` |
| Archived sessions | `$CODEX_HOME/archived_sessions`，默认 `~/.codex/archived_sessions` |

如果要分享 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 恢复。

## 分层排障表

| 现象 | 优先检查 | 不要先做什么 |
| --- | --- | --- |
| Review panel 显示非 Codex 改动 | Git state、Last turn changes view | 不要回滚不认识的文件 |
| 找不到 thread | sidebar filter、Settings archived threads | 不要删除项目重加 |
| Worktree 跑不起来 | setup script、依赖、当前目录 | 不要直接怪 Codex 代码 |
| teammate 配置不生效 | `.codex` 是否在 project root | 不要复制一份配置到错误目录 |
| macOS 要求访问 Music / Downloads / Desktop | 当前任务是否需要读 home 目录 | 不要盲目授予全盘访问 |
| Automation worktrees 太多 | archive old runs、减少 pinned runs | 不要手动删仍在用的 worktree |
| CLI 有功能 App 没有 | CLI 和 App bundle 版本 | 不要假设两边版本一致 |
| Terminal stuck | 关闭重开 terminal、跑 `pwd` / `git status` | 不要重启所有 thread |

## 版本差异怎么确认

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

查看 CLI 版本：

```bash
codex --version
```

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

```bash
/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](codex://settings) pane 中配置 **Code font**。

## 官方资料

- [Codex App troubleshooting](https://developers.openai.com/codex/app/troubleshooting)
- [Review pane](https://developers.openai.com/codex/app/review)
- [Worktrees](https://developers.openai.com/codex/app/worktrees)
- [Local environments](https://developers.openai.com/codex/app/local-environments)
- [Codex GitHub issues](https://github.com/openai/codex/issues)

## 接下来去哪

<Cards>
  <Card title="App 核心" href="/docs/codex/official/01-products/33-app-core" description="排障前先有正确心智模型" />
  <Card title="App Review pane" href="/docs/codex/official/01-products/40-app-review" description="非 Codex 改动来源在这里看" />
  <Card title="本地运行环境" href="/docs/codex/official/01-products/39-local-runtime" description="worktree 跑不起来时的修法" />
  <Card title="Worktrees" href="/docs/codex/official/01-products/43-worktrees" description="worktree 的工作机制" />
  <Card title="App 设置" href="/docs/codex/official/01-products/34-app-settings" description="字体、archived threads、common prefs" />
  <Card title="Computer Use" href="/docs/codex/official/01-products/38-computer-use" description="App 控制系统时的额外排障路径" />
</Cards>
