---
title: "09 - 疑難排解與速查表"
type: note
specialty: Programming
tags: [codex-cli從0開始使用教學, 09-速查表, troubleshooting]
created: 2026-08-04
updated: "2026"
modified: 2026-08-04
---

# 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 有）→ 只能靠控制範圍和批次大小 |

### 找不到指令 / 版本差異

**最可靠的兩個指令**：

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

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

---

## Part 2：Cheat Sheet

```bash
# ── 基本 ──────────────────────────────
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`

```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.md`** | Codex 的專案指示檔（Claude Code 用的是 `CLAUDE.md`）|
| **`AGENTS.override.md`** | 覆蓋檔，優先序高於同層的 `AGENTS.md` |
| **`config.toml`** | Codex 的行為設定，在 `~/.codex/` |
| **Profile** | `config.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`）

---

## 🔗 相關筆記

- [[00-Index]] — 回到目錄
- [[04-Sandbox與Approval權限模型]] — 兩個旋鈕的完整說明
- [[08-實戰-被Claude指揮的雙手]] — 三層護欄的完整範例
- [[Programming/Claude-Code/Claude-Code-CLI從0開始使用教學/14-疑難排解與速查表|Claude Code CLI 14]] — 另一支的排錯表
- [[Programming/Herdr/Herdr從0開始使用教學/13-疑難排解與術語速查表|Herdr 13]] — 編排層的排錯表

---

*最後更新：2026-08-04*