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

# 14 - 疑難排解與速查表

← [[13-實戰-套用在兩個repo]] | [[00-Index]]

---

## Part 1：症狀 → 對策

### 安裝與啟動

| 症狀 | 對策 |
|---|---|
| `claude` 找不到 | 重開終端機或檢查 PATH。`claude doctor` 診斷 |
| 安裝指令噴 `syntax error near unexpected token '<'` 或 403 | 見官方 [Troubleshoot installation](https://code.claude.com/docs/en/troubleshoot-install) |
| `The token '&&' is not a valid statement separator` | 你在 **PowerShell** 卻用了 CMD 的指令 |
| `'irm' is not recognized` | 你在 **CMD** 卻用了 PowerShell 的指令 |
| Homebrew / WinGet 裝的版本很舊 | 這兩種**不會自動更新**，自己 `brew upgrade` / `winget upgrade` |
| 明明有訂閱卻叫我用 API key | 你設了 `ANTHROPIC_API_KEY` 環境變數 → 取消它 |
| 原生 Windows 上 bash 指令都不能用 | 裝 [Git for Windows](https://git-scm.com/downloads/win)，或改用 WSL |

### 設定壞掉

| 症狀 | 對策 |
|---|---|
| **開起來就爆 / 行為完全不對** | **`claude --safe-mode`**（停用所有客製）|
| 想知道設定檔哪裡有語法錯誤 | `claude doctor`（不開 session）或 `/doctor`（會提修正）|
| 不確定載入了什麼 | `/context` 看 **Memory files** |
| 某個 skill 沒出現在 `/` 選單 | ① 檢查 `user-invocable` 是不是 `false` ② 如果是新建的**頂層** skills 目錄，要重開 Claude Code |
| 改了 skill 沒生效 | 一般會 live reload；新建的頂層目錄需重開 |

### CLAUDE.md 沒被遵守

按這個順序排查：

1. **`/context`** → **Memory files** 裡有沒有那個檔案？沒有 = Claude 根本看不到
2. 檔案位置對嗎？（一定要從 repo 根目錄開 `claude`）
3. 指示夠具體嗎？（「用 2 空格縮排」> 「格式弄好」）
4. **有沒有互相矛盾的指示？** 跨多份 CLAUDE.md 檢查——矛盾時 Claude 會**任意挑一條**
5. 這條規則其實是「必須在某時點執行」？→ 改成 **hook**
6. 進階：裝 `InstructionsLoaded` hook 記錄實際載入了什麼

| 症狀 | 對策 |
|---|---|
| `/compact` 之後指示不見了 | 專案根目錄的 CLAUDE.md 會自動重讀；**子目錄的不會**，要等下次讀那個子目錄的檔案。只在對話裡講過的指示會消失 → 寫進 CLAUDE.md |
| CLAUDE.md 太大 | `/doctor` 會提出精簡建議；用 path-scoped rules 拆。⚠️ 拆成 `@` imports **不省 context** |
| 我在 CLAUDE.md 提到路徑卻被當成 import | 用反引號包起來：`` `@README` `` |

### 權限

| 症狀 | 對策 |
|---|---|
| 一直被問同一個指令 | `/permissions` 加 allow 規則，或跑 `/fewer-permission-prompts` 讓它幫你產 allowlist |
| allow 規則好像沒用 | ① 是不是 protected path？（allow 規則**不能**預先核准那些）② 是不是進了 auto mode（寬鬆的 `Bash(*)` 這類會被丟掉）|
| `Bash(git diff*)` 連 `git diff-index` 都中 | **`*` 前面要有空格**：`Bash(git diff *)` |
| auto mode 一直擋我的正常操作 | 連續 3 次或累計 20 次會自動退回詢問。`/permissions` 的 Recently denied 分頁按 `r` 重試。要根治請設定 trusted infrastructure |
| 設了 `defaultMode: "auto"` 但沒生效 | `auto` 在 `.claude/settings.json` / `settings.local.json` 會被**忽略**（防止 repo 自己給自己 auto mode）→ 移到 `~/.claude/settings.json` |
| 我說「不要 push」但它還是 push 了 | 對話裡的界線是 classifier 從 transcript 重讀的，**`/compact` 可能把它壓掉**。要硬保證用 **deny 規則** |
| `--dangerously-skip-permissions` 說不能用 root/sudo | 這是刻意的安全檢查。改用 dev container（以非 root 執行）|

### 快捷鍵

| 症狀 | 對策 |
|---|---|
| macOS 上 `Alt+B` / `Alt+F` / `Alt+P` 沒反應 | 終端機要把 Option 設成 Meta（iTerm2 設 "Esc+"；Terminal.app 勾 "Use Option as Meta Key"；VS Code 設 `terminal.integrated.macOptionIsMeta`）|
| Windows / WSL 貼圖沒反應 | 用 **`Alt+V`**（`Ctrl+V` 常被終端機攔截）|
| `Shift+Enter` 沒作用 | 終端機沒把它回報成獨立的修飾 Enter。見官方 [Terminal configuration](https://code.claude.com/docs/en/terminal-config) |
| 畫面花掉 / 部分空白 | `Ctrl+L` 重繪 |

### 腳本 / 非互動

| 症狀 | 對策 |
|---|---|
| `--bare` 之後說沒登入 | bare mode **不讀 OAuth 憑證和 keychain**，要設 `ANTHROPIC_API_KEY` |
| pipe 進去的內容被拒 | stdin 上限 **10MB**。寫成檔案、在 prompt 裡提路徑 |
| `--json-schema` 直接錯誤退出 | schema 無效。注意 `format` 只當註解、不驗證 |
| 背景 dev server 被砍掉 | `claude -p` 結束後約 5 秒會終止背景 shell |
| 卡住不結束 | 背景 subagent 預設等 10 分鐘（`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` 可調）|
| MCP server 好像沒載入但沒報錯 | 看 `system/init` 事件的 `mcp_server_errors` 欄位。**stderr 被導向時不會印警告** |
| 兩個指令之間 `--resume <id>` 找不到 session | 要在**同一個目錄**跑（session ID 查詢以專案目錄為範圍）|

### 找 log

```bash
claude --debug "api,mcp"                 # 分類過濾
claude --debug-file /tmp/claude.log      # 寫檔
```

---

## Part 2：指令 Cheat Sheet

```bash
# ── 啟動 ──────────────────────────────
claude                              # 互動
claude "任務"                        # 帶起始 prompt
claude -p "問題"                     # 跑完就結束
claude -c                           # 接續目前目錄最近一次
claude -r ["id|name"]               # resume
claude -w feature-x                 # 在隔離 worktree 開
claude --bg "背景任務"               # 背景 agent
claude --safe-mode                  # 救援模式
claude --permission-mode plan       # 起始權限模式

# ── 帳號 / 維運 ────────────────────────
claude auth login|logout|status
claude doctor
claude update
claude setup-token

# ── 背景 session ──────────────────────
claude agents [--json]
claude attach <id> | logs <id> | stop <id> | respawn <id> | rm <id>

# ── 腳本 ──────────────────────────────
cat x.log | claude -p "解釋" --output-format json | jq -r '.result'
claude --bare -p "..." --allowedTools "Read" --max-budget-usd 1.00
claude -p "..." --output-format json --json-schema '{...}' | jq '.structured_output'
```

### Session 內指令

```
/context        看 context 用量與載入的 memory files
/compact [指示]  壓縮對話
/clear          清空開新的
/plan [描述]     進 plan mode
/permissions    管理權限規則
/memory         編輯記憶檔
/model opus     換模型
/effort high    調思考力度
/diff           看未 commit 的變更
/usage          看花費
/doctor         setup 檢查
/hooks          看 hook 設定
/mcp            管理 MCP
/init           產生 CLAUDE.md
/resume         接續之前的對話
/fork [prompt]  複製成新的背景 session
/btw <問題>      問個小問題不進對話
/export         匯出對話
```

### 快捷鍵

```
Shift+Tab   切權限模式          Esc         打斷 Claude
Esc Esc     清草稿 / 開 rewind   Ctrl+O      transcript viewer
Ctrl+R      搜尋指令歷史         Ctrl+B      丟到背景
Ctrl+G      用編輯器改 prompt    Ctrl+L      重繪畫面
Ctrl+T      切換 to-do 清單      Ctrl+S      暫存 / 還原 prompt
Alt+V       貼圖（Windows/WSL）  Alt+P       換模型
Alt+T       切 extended thinking Alt+O       切 fast mode
Ctrl+X Ctrl+K  停掉所有背景 subagent
```

### 輸入框前綴

```
/  指令或 skill        !  跑 shell 指令並把輸出加進對話
@  檔案路徑補完        :  emoji 短碼        ?  快捷鍵說明（輸入框空的時候）
```

---

## Part 3：術語速查

| 術語 | 說明 |
|---|---|
| **Agentic** | 會自己執行多步驟工作，不只回答 |
| **Surface** | 介面：terminal / VS Code / JetBrains / desktop / web / mobile / Slack |
| **CLAUDE.md** | 你寫的持久指示，每個 session 開頭載入。**是上下文，不是強制設定** |
| **Auto memory** | Claude 自己記的學習成果，存在 `~/.claude/projects/<project>/memory/` |
| **`.claude/rules/`** | 模組化指示，可用 `paths:` 限定何時載入 |
| **Skill** | `SKILL.md`，可重複的流程。**用到才載入**，長內容幾乎不花 context |
| **Subagent** | 有自己 context window 的專門助手，`.claude/agents/*.md` |
| **Background agent / Agent view** | 多個獨立 session 平行跑、一個畫面監看 |
| **Agent team** | 會互相溝通的多個 session |
| **Hook** | 在生命週期特定時點一定會執行的 shell 指令。**硬保證** |
| **MCP** | Model Context Protocol，接外部工具（你的 PubMed 走這條）|
| **Permission mode** | `default`(Manual) / `acceptEdits` / `plan` / `auto` / `dontAsk` / `bypassPermissions` |
| **Auto mode classifier** | 獨立的模型，在 auto mode 下逐一審查動作 |
| **Protected paths** | 一組永遠不會被自動核准寫入的路徑（`.git`、`.claude`、shell rc、`.mcp.json`…）|
| **Plan mode** | 研究並提計畫但不改原始碼；`Ctrl+G` 可直接編輯計畫 |
| **Compaction** | 壓縮對話釋放 context。專案根 CLAUDE.md 會被重新注入 |
| **Rewind** | `Esc Esc`（輸入框空時）開的還原選單 |
| **Bare mode** | `--bare`，跳過所有自動探索。**不讀 OAuth 憑證** |
| **Effort** | 思考力度 `low`/`medium`/`high`/`xhigh`/`max` |
| **Worktree isolation** | `-w` 或 subagent 的 `isolation: worktree`，拿 repo 的隔離副本 |
| **Routines** | 跑在 Anthropic 機器上的排程，電腦關機也會跑 |

---

## Part 4：三張「別忘記」小抄

### 安全三層

```
CLAUDE.md（軟：上下文）
    ↓ 不夠硬
權限規則 allow/ask/deny（硬：路徑與指令比對）
    ↓ 不夠靈活
Hook（硬：任意 shell 邏輯）
```

### 開工前

- [ ] `cd` 到 repo 根目錄了嗎？（不然讀不到 CLAUDE.md）
- [ ] `/context` 確認 Memory files 有載入
- [ ] 大改動 → `Shift+Tab` 進 plan mode

### 收工前

- [ ] `/diff` 看過所有變更
- [ ] 跑過驗證腳本（`validate.py` / `lint.py`）
- [ ] 醫學內容：**PMID 都查證過了嗎？** 不確定的標「需查證」了嗎？
- [ ] push 前 `git pull --rebase`

---

## 🔗 相關筆記

- [[00-Index]] — 回到目錄
- [[05-權限模式與安全]] — 權限問題的完整說明
- [[06-CLAUDE-md與記憶系統]] — 記憶問題的完整說明
- [[13-實戰-套用在兩個repo]] — 實際設定建議
- 官方 Troubleshooting：<https://code.claude.com/docs/en/troubleshooting>
- 官方 Error reference：<https://code.claude.com/docs/en/errors>

---

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