14 - 疑難排解與速查表
← 13-實戰-套用在兩個repo | 00-Index
Part 1：症狀 → 對策
安裝與啟動
| 症狀 | 對策 |
|---|
claude 找不到 | 重開終端機或檢查 PATH。claude doctor 診斷 |
安裝指令噴 syntax error near unexpected token '<' 或 403 | 見官方 Troubleshoot installation |
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，或改用 WSL |
設定壞掉
| 症狀 | 對策 |
|---|
| 開起來就爆 / 行為完全不對 | claude --safe-mode（停用所有客製） |
| 想知道設定檔哪裡有語法錯誤 | claude doctor（不開 session）或 /doctor（會提修正） |
| 不確定載入了什麼 | /context 看 Memory files |
某個 skill 沒出現在 / 選單 | ① 檢查 user-invocable 是不是 false ② 如果是新建的頂層 skills 目錄，要重開 Claude Code |
| 改了 skill 沒生效 | 一般會 live reload；新建的頂層目錄需重開 |
CLAUDE.md 沒被遵守
按這個順序排查：
/context → Memory files 裡有沒有那個檔案？沒有 = Claude 根本看不到- 檔案位置對嗎？（一定要從 repo 根目錄開
claude）
- 指示夠具體嗎？（「用 2 空格縮排」> 「格式弄好」）
- 有沒有互相矛盾的指示？ 跨多份 CLAUDE.md 檢查——矛盾時 Claude 會任意挑一條
- 這條規則其實是「必須在某時點執行」？→ 改成 hook
- 進階：裝
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 |
| 畫面花掉 / 部分空白 | 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
claude --debug "api,mcp" # 分類過濾
claude --debug-file /tmp/claude.log # 寫檔
Part 2：指令 Cheat Sheet
# ── 啟動 ──────────────────────────────
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 邏輯）
開工前
收工前
🔗 相關筆記
最後更新：2026-08-04
