新手問題排除

返回 Codex 教學總目錄

目標與使用方式

示意圖的 01 是記錄症狀，02 是依表選一個最小檢查，03 是修正原因後重做原操作。不是遇到錯誤就立即重試；先保留輸入、狀態及原本可用的環境，再縮小問題。

第一步：記錄現象與最後成功的動作

先記錄時間、平台、應用程式／CLI 版本、目前資料夾、完整命令或操作、預期結果及錯誤原文。只分享和問題有關的訊息，遮蔽帳號、私有路徑與金鑰。若是安裝成功後才找不到指令，保留安裝結果；若是另一個任務仍在跑，保留任務名稱與主機。不要把錯誤截成只剩紅字，因為上一行命令與工作目錄通常決定下一步。

# Troubleshooting record
- Time and timezone:
- Surface: desktop / CLI / IDE / mobile / web
- OS and app or CLI version:
- Working folder or execution host (redacted if shared):
- Exact command or UI action:
- Expected result:
- Actual error and exit status:
- Last successful action:
- One change attempted:
- Result after that change:
- Files or settings to restore:

安裝、登入與平台入口

codex 找不到或不是內外部命令: CLI 安裝

PowerShell 阻擋腳本: Windows CLI

macOS／Linux 安裝位置不同: macOS · Linux／WSL

登入後還是未授權: 帳號與額度

找不到桌面或手機的某按鈕: 平台選擇

同一台電腦上的 Windows、WSL、容器與遠端主機不一定共用登入或設定；先確認出錯的是哪個環境。

Windows 可以用 Get-Command codex 看找到的是哪個執行檔；macOS／Linux 用 command -v codex。看到多個安裝來源時先記錄，不立刻刪除舊版或更改全機安全政策。登入問題先分辨 ChatGPT 登入、API key 與組織限制；額度耗盡不會因重裝而增加。服務可能異常時查看官方狀態頁，對照你的錯誤時間與服務項目，不把網站整體正常視為自己的網路與權限都正常。

工作目錄、MD 與設定

改了程式但頁面沒變: 路徑 · 瀏覽器

AGENTS.md 好像沒作用: 規則層級

把 README 當成永久規則: 文件分工

config.toml 解析失敗: 設定排錯

續接後沿用舊結論: 工作階段 · 交接

一次只改一個條件。設定恢復正常後保留必要改動，移走你自己加的診斷標記，不能把整份設定覆蓋成網路上的範本。

可重現演練：找到真正的資料夾

在檔案管理員建立全新的 path-trouble，裡面有 project 與 other 兩個空白資料夾。只在 project 裡建立 marker.md，內容為下方一行。先從 other 開終端機，故意嘗試讀 marker.md；這會重現檔案找不到，不需要 Codex 也不會動到正式專案。接著查目前目錄與檔案清單，再用明確相對路徑讀到 marker，最後 cd 進 project 並重做原讀檔命令。

# Correct folder: PATH-PRACTICE-1

Get-Content -LiteralPath .\marker.md
Get-Location
Get-ChildItem
Get-Content -LiteralPath ..\project\marker.md
Set-Location -LiteralPath ..\project
Get-Content -LiteralPath .\marker.md

cat ./marker.md
pwd
ls
cat ../project/marker.md
cd ../project
cat ./marker.md

第一個讀檔失敗，後面兩次應顯示相同 PATH-PRACTICE-1；marker 內容未改，修正的是操作位置。完成後回到原本工作目錄，練習資料可保留，不需要遞迴刪除。若套用到 Codex，先請它回報目前根目錄及指定檔案是否存在，再決定是否開錯專案。不要把桌面同名任務、另一個 worktree 或手機看到的舊內容當成同一資料夾。

如果需要記錄成功狀態，PowerShell 的 Get-Content 是 cmdlet，應立即保存 $?；$LASTEXITCODE 主要用於 codex、node 等原生程式。前面的路徑練習結束後，終端機應在 project，以下先讀不存在的 other/marker.md，再讀真正的 marker。PowerShell 預期依序 False、True；shell 則先非零、後 0。不要等其他命令跑完才讀狀態。

Get-Content -LiteralPath ..\other\marker.md
$practiceReadOk = $?
$practiceReadOk
Get-Content -LiteralPath .\marker.md
$practiceReadOk = $?
$practiceReadOk

cat ../other/marker.md
practice_read_exit=$?
printf '%s\n' "$practice_read_exit"
cat ./marker.md
practice_read_exit=$?
printf '%s\n' "$practice_read_exit"

自動變數的精確定義見 PowerShell 官方文件。兩次讀檔都不改 marker；若檔案內容改了，另記為未預期修改並先找原因。這樣交接時能把「路徑錯誤已修正」和「檔案原文保持」分開核對。

工具、遠端與自動化

Skill 出現但做錯: 技能驗收

Plugin 已安裝但無法查資料: 插件排錯

MCP 設定存在但工具不可用: MCP 排錯

手機讀到舊版本: 遠端設定 · 跨裝置

子代理說完成卻有衝突: 代理品質 · 平行整合

排程逾時或重複: 自動化恢復

JSON 有答案但程序失敗: JSON／JSONL

依症狀只處理相關層，例如已安裝插件與來源帳號有權讀取是不同狀態。

完成排錯與恢復工作

修正後重做原本會失敗的操作，再加一個相鄰案例確認沒有破壞既有行為。例如修 Completed 後也測 Active；修改 config 後確認先前正常的設定還在；重連 MCP 後真的讀一份虛構文件，而非只看綠色連線圖示。把問題、原因、單一修正與驗證寫回 issue-notes.md，需要交給別人時提供最小可重現輸入及已試過的步驟。問題未解決就寫未解決，保留可用狀態與下一個要查的證據。

最後撤回自己加入的測試標記與暫時設定，保留必要修正、備份及錯誤紀錄。不要藉排錯一次清空所有設定、刪除工作階段或公開敏感內容。這個索引不要求照表從頭做完；從自己的症狀選一列即可，讀完專篇可由篇首或篇尾回到教學總目錄，再用功能名、指令或 MD 檔名搜尋下一步。各平台未提供的功能應記為不支援或尚未開放，與安裝故障分開處理。

返回 Codex 教學總目錄

閱讀完整文字說明

Symptom to One check to Retry

• AI 工具
• 教學
• Codex