排查 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

接下來去哪