---
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="/zh-Hant/docs/codex/official/01-products/33-app-core" description="排障前先有正確心智模型" />
  <Card title="App Review pane" href="/zh-Hant/docs/codex/official/01-products/40-app-review" description="非 Codex 改動來源在這裡看" />
  <Card title="本地執行環境" href="/zh-Hant/docs/codex/official/01-products/39-local-runtime" description="worktree 跑不起來時的修法" />
  <Card title="Worktrees" href="/zh-Hant/docs/codex/official/01-products/43-worktrees" description="worktree 的工作機制" />
  <Card title="App 設定" href="/zh-Hant/docs/codex/official/01-products/34-app-settings" description="字型、archived threads、common prefs" />
  <Card title="Computer Use" href="/zh-Hant/docs/codex/official/01-products/38-computer-use" description="App 控制系統時的額外排障路徑" />
</Cards>
