Andrew的筆記園地

閱讀時間約 8 分鐘

⬇ MD

09 - 疑難排解與速查表

← 08-實戰-被Claude指揮的雙手 | 00-Index

Part 1：症狀 → 對策

安裝與登入

症狀對策
codex 找不到npm 全域 bin 目錄不在 PATH。npm bin -g 看路徑
Windows 上行為怪異 / 不穩Windows 支援是 experimental。官方建議改在 WSL2 裡跑
無法開瀏覽器登入（SSH / 遠端）codex login --device-auth 走 device code 流程
用了 API key 但想用訂閱檢查有沒有設到相關環境變數；codex login 重新用 ChatGPT 登入
模型不見了 / 報錯說模型不存在⚠️ gpt-5.4 / gpt-5.4-mini 於 2026-08-31 從 ChatGPT 登入的 Codex 退場 → 換 gpt-5.6-terra / gpt-5.6-luna

執行

症狀對策
說必須在 git repo 裡這是安全設計。真的要在非 repo 跑：codex exec --skip-git-repo-check
它改不了檔案sandbox 是 read-only。改 sandbox_mode 或換 profile
它一直停下來問我approval_policy 太嚴。改 never，或用 --full-auto
我用了 --full-auto 但它還是寫不出 repo正常。--full-auto 只把 sandbox 設成 workspace-write，不是 danger-full-access
它連不到網路裝套件[sandbox_workspace_write] network_access = true（想清楚再開）
多行輸入時 Enter 直接送出用 Ctrl+J 換行（跨終端機最可靠）
想中斷但不想離開Esc 打斷；Ctrl+C 或 /quit 才是離開

品質問題

症狀對策
產出格式對但內容不符我的規矩它讀不到 CLAUDE.md 和你的 Claude skill。 規則要寫進三層護欄（全域 AGENTS.md / repo AGENTS.md / 任務檔）
它編造了 PMID / 數字在全域 AGENTS.md 加「不確定標 [需查證]，不要編」。這是最該裝的一條護欄
它自己 commit 了全域 AGENTS.md 加「不要 git commit、不要 git push」
它順手改了範圍外的東西任務檔明確寫「範圍之外不要動」+ 用 read-only 做盤點類任務
輸出被截斷 / 讀不完整讓它寫檔（-o）然後讀檔，不要從畫面撈

額度

症狀對策
額度很快就用完① 平行 worker 減到 2–3 個 ② 量產用 model_reasoning_effort = "medium" ③ 縮小批次
不知道還剩多少/status
⚠️ 想設花費上限Codex 沒有 --max-budget-usd 這種內建煞車（Claude Code 有）→ 只能靠控制範圍和批次大小

找不到指令 / 版本差異

最可靠的兩個指令：

codex --help          # CLI 層
/help                 # session 內

⚠️ Codex 迭代很快，斜線指令和旗標會增減。任何教學（包括這份）都可能落後於你安裝的版本。以 --help 為準。

Part 2：Cheat Sheet

# ── 基本 ──────────────────────────────
codex                              # 互動 session
codex "任務"                        # 帶起始 prompt
codex login                        # 登入
codex login --device-auth          # 無瀏覽器環境
codex --version
codex --help                       # ⭐ 最可靠的指令來源
 
# ── Profile / 權限 ────────────────────
codex --profile audit              # 用 config.toml 的 profile
codex --full-auto                  # 不問核准 + workspace-write
 
# ── Session ───────────────────────────
codex resume                       # 接續目前 repo 最近的
codex resume --all                 # 找其他目錄的
 
# ── 非互動 ────────────────────────────
codex exec "任務"                   # 別名 codex e
codex exec --json "任務"            # JSONL 事件串流
codex exec -o out.txt "任務"        # 最後訊息寫檔（同時仍印 stdout）
codex exec --skip-git-repo-check "任務"
codex exec resume "接著做..."
 
# ── 其他 ──────────────────────────────
codex app                          # 開桌面體驗
codex mcp-server                   # 把 Codex 自己當成 MCP server

Session 內斜線指令（以 /help 為準）

/help          說明 ⭐
/model         選模型
/permissions   權限（/approvals 是別名）
/status        session 狀態、額度
/mcp           MCP 工具與資源
/resume        接續 session
/title         命名對話
/review        review 模式
/agent         agent thread
/plugins       plugin
/copy          複製
/fast          速度模式
/personality   回應風格
/raw           原始輸出
/quit          離開

快捷鍵

Ctrl+J    換行 ⭐（跨終端機最可靠）
Esc       打斷目前工作
Ctrl+C    離開

Part 3：設定速查

~/.codex/config.toml

model = "gpt-5.6-terra"
model_reasoning_effort = "medium"       # minimal/low/medium/high/xhigh（依模型）
approval_policy = "on-request"          # untrusted / on-request / never
sandbox_mode = "workspace-write"        # read-only / workspace-write / danger-full-access
 
[sandbox_workspace_write]
network_access = false
# writable_roots = ["/tmp/scratch"]
 
[profiles.audit]
approval_policy = "never"
sandbox_mode = "read-only"
 
[profiles.worker]
approval_policy = "never"
sandbox_mode = "workspace-write"

AGENTS.md 解析順序

~/.codex/AGENTS.override.md   ← 最高優先的全域覆蓋
~/.codex/AGENTS.md            ← 全域預設
    ↓
repo root → 各層子目錄
（越靠近目前工作目錄，優先序越高；後面的覆蓋前面的）

每層先看 AGENTS.override.md，再看 AGENTS.md。檔案大小預設上限 32 KiB。

Part 4：術語速查

術語說明
sandbox_mode技術上能做什麼（OS 層隔離）：read-only / workspace-write / danger-full-access
approval_policy什麼時候問你：untrusted / on-request / never
--full-auto= 不問核准 + 強制 workspace-write
AGENTS.mdCodex 的專案指示檔（Claude Code 用的是 CLAUDE.md）
AGENTS.override.md覆蓋檔，優先序高於同層的 AGENTS.md
config.tomlCodex 的行為設定，在 ~/.codex/
Profileconfig.toml 裡的具名設定組，用 --profile 一鍵切換
codex exec非互動模式（別名 codex e），對應 claude -p
-o / --output-last-message把最後一則 agent 訊息寫檔（同時仍印 stdout）
--skip-git-repo-check跳過「必須在 git repo」守衛。不會關掉 sandbox
codex mcp-server把 Codex 當成 MCP server 給別的工具用
Max（思考模式）給單一任務更多思考時間
Ultra（思考模式）用 subagent 平行處理複雜任務的不同部分

Part 5：三張「別忘記」小抄

兩個旋鈕

sandbox_mode    = 安全帶（永遠繫著）
approval_policy = 速限（可以放寬）

❌ 常見錯誤：因為一直被問，就跳到 danger-full-access
✅ 正確做法：調 approval_policy，不要調 sandbox_mode

三層護欄

~/.codex/AGENTS.md   →  永遠適用（不要 commit、不要猜、標 [需查證]）
repo/AGENTS.md       →  這個專案的慣例
任務檔                →  這批工作的規格 + 完成條件

2026-08 待辦 ⚠️

  • 檢查 config.toml 和所有 profile 的 model
  • 檢查編排腳本裡有沒有寫死 gpt-5.4
  • 檢查排程任務 / automation 設定
  • （gpt-5.4 / gpt-5.4-mini 於 2026-08-31 退場 → gpt-5.6-terra / gpt-5.6-luna）

🔗 相關筆記

最後更新：2026-08-04

關係圖譜

反向連結