Claude Code 速查表：指令、設定與快捷鍵

一站掌握所有CLI旗標、斜線指令、鍵盤快速鍵、設定鍵、hook 事件與環境變數。如需深入說明，請參閱完整的Claude Code指南。若是首次設定，請參閱快速入門。

1. 安裝

三種安裝方式，依建議優先順序排列。

# Native binary (recommended)
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew (macOS)
brew install --cask claude-code

# NPM (deprecated — migrate with `claude install`)
npm install -g @anthropic-ai/claude-code

安裝特定版本：

curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

驗證安裝：

claude doctor
claude --version

若您使用的是 2.1.288 至 2.1.290，請更新至 2.1.291 或更新版本：該版本修正了 2.1.288 的一項回歸問題（結束時可能遺失工作階段的最後幾則訊息），以及 2.1.290 的另一項回歸問題（雲端工作階段可能遺漏對權限提示的回答）。

驗證身分：

claude auth login       # Log in or switch accounts
claude auth status      # Check current auth state
claude auth logout      # Clear stored credentials

2. CLI 旗標

v2.1.212 新增的子命令： claude auto-mode reset 可從終端機重設您的 auto-mode 狀態；傳入 --yes 可略過確認提示。⁷

工作階段與資料子命令： claude attach <name> 與 claude logs <name> 可用背景工作階段名稱的一部分取代其 id（v2.1.290+）。claude purge [path] 會刪除專案的本機 Claude Code 狀態（--dry-run 可預覽）；在 v2.1.288 之前它叫做 claude project purge，舊名稱仍可使用，但會顯示提示訊息。自 v2.1.300 起，claude remote-control 不再接受 --sandbox 或 --no-sandbox（這兩個旗標原本就沒有效果；請改在設定中設定 sandbox.enabled）。自 v2.1.309 起，claude ultrareview 需要工作區信任：在終端機上會先詢問您，否則拒絕執行；腳本可傳入 --trust-workspace（不帶值；PR 編號或基底分支須放在它前面）或設定 CLAUDE_CODE_DISABLE_ULTRAREVIEW_TRUST_CHECK=1。¹⁴ claude self-hosted-runner --hold-idle-file <path> --max-hold-min <n> 會在您的主機持續修改該檔案期間保留閒置的工作階段，但無論如何都會在 n 分鐘後釋放（預設 1440；v2.1.311+）。

3. 斜線指令

自訂指令：建立 .claude/commands/my-command.md（專案層級）或 ~/.claude/commands/my-command.md（個人層級），再以 /my-command 呼叫。指令支援 YAML frontmatter，可設定描述、允許的工具、模型覆寫，以及透過 $ARGUMENTS 或位置參數 $1、$2 進行引數插值。

---
description: Fix a GitHub issue
allowed-tools: Read, Edit, Bash(git:*)
model: opus
argument-hint: [issue-number]
---

Fix GitHub issue #$ARGUMENTS following our coding standards.

用法：/fix-issue 123

4. 鍵盤快速鍵

一般操作

快速前綴

多行輸入

快速鍵可透過 /keybindings 自訂（儲存於 ~/.claude/keybindings.json）。自 v2.1.284 起，effortSlider:decreaseEffort、increaseEffort 與 toggleUltracode 動作可重新綁定 /effort 滑桿的方向鍵與 Tab 鍵。

5. 設定檔

優先順序階層（由高至低）

以最先符合者為準。企業設定無法繞過。

6. Settings.json 參考

主要設定及其型別與範例。可放入上述階層中的任一設定檔。

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-6",
  "permissions": {
    "allow": ["Read", "Glob", "Grep", "Bash(npm run:*)", "Bash(git:*)", "Edit(src/**)"],
    "deny": ["Read(.env*)", "Bash(rm -rf:*)", "Bash(sudo:*)"],
    "ask": ["WebFetch", "Bash(docker:*)"],
    "defaultMode": "acceptEdits",
    "additionalDirectories": ["../shared-lib"]
  },
  "env": {
    "NODE_ENV": "development"
  },
  "hooks": {},
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true
  },
  "cleanupPeriodDays": 30,
  "respectGitignore": true,
  "showTurnDuration": true,
  "language": "en",
  "autoMemoryDirectory": ".claude/memory",
  "plansDirectory": ".claude/plans"
}

權限規則語法：Tool(pattern:*) 提供前綴比對。Bash(npm run test:*) 允許 npm run test、npm run test:unit 等指令。檔案模式使用 glob 語法：Edit(src/**)。自 v2.1.214 起，單一路徑段的 dir/** allow 規則只會比對 <cwd>/dir，不再比對目錄樹中任何位置的 dir/；若要比對任意深度，請寫成 Edit(**/src/**)。deny/ask 規則仍維持任意深度比對，而 hook 的 if: 條件也套用同樣的 cwd 範圍限制。自 v2.1.299 起，MCP 的 allow 規則只涵蓋其指名的伺服器：mcp__a 不再涵蓋名為 a__b 或 a_ 的伺服器；請以完整的正規化名稱寫成 mcp__<server>__*。

新增鍵值（v2.1.118+）：

完整的設定結構描述請參閱完整指南中的設定深入解析。

7. CLAUDE.md 快速參考

CLAUDE.md 是專案的指令檔案。Claude 會在每次工作階段開始時讀取它。

存放位置：

AGENTS.md（v2.1.277+）： 在沒有 CLAUDE.md 的專案中，Claude Code 會改為讀取 AGENTS.md，可在 /config 的「Project instructions」下變更此行為（Bedrock/Vertex/Foundry 尚未支援）。

應包含的內容：

# Project Name

## Stack
- Backend: FastAPI, Python 3.11+
- Frontend: HTMX + Alpine.js + Bootstrap 5

## Commands
- Dev: `uvicorn app.main:app --reload --port 8000`
- Test: `python -m pytest -v`
- Lint: `ruff check .`

## Conventions
- Conventional commits: feat:, fix:, docs:, refactor:
- Never force push to main
- Always activate venv before Python commands

## Key Files
- app/main.py — FastAPI app and routes
- app/models.py — SQLAlchemy models

保持一目瞭然。冗長的文字每次工作階段都會浪費 context token。請使用項目符號、表格和簡短的程式碼區塊。避免長段落：Claude 會在每次工作階段開始時讀取 CLAUDE.md，因此每個字都會消耗 context。

實用技巧： - 在 REPL 中使用 # 前綴，不必編輯 CLAUDE.md 即可將內容加入自動記憶：# Always use TypeScript strict mode - 當 Claude 讀取子目錄中的檔案時，會載入該子目錄的 CLAUDE.md - 團隊共用的規則放在 .claude/rules/*.md，便於模組化管理

8. 權限模式

Auto Mode（v2.1.85+）是互動式終端機與 VS Code 工作階段在所有方案與供應商上的內建起始模式：v2.1.283 將其擴展至第三方供應商與關閉遙測的工作階段，v2.1.284 再擴展至所有方案與供應商；在此之前，它僅是 Pro、Max 與 Team 方案的預設值（自 2026年8月14日起）。從 v2.1.285 到 v2.1.301，在第三方供應商上或關閉遙測的 claude -p 與 Python Agent SDK 工作階段，在未設定權限模式時也會以 auto 模式啟動；v2.1.302 推翻了這點：未設定權限模式的 claude -p 或 Agent SDK 工作階段，在第三方供應商上、關閉遙測時以及全新安裝時都會以 Manual 啟動，一如能取得功能旗標的環境向來的行為，而 --permission-mode auto 則維持 auto。¹³ permissions.defaultMode 會覆寫內建預設值（"default" 固定為 Manual），disableAutoMode 則可在整個組織範圍停用它。它是 --dangerously-skip-permissions 的建議替代方案。唯讀操作與檔案編輯會自動核准；自 v2.1.281 起，在分類器審查於伺服器端執行的環境中，唯讀與沙箱化的 shell 命令同樣會等待審查，並在被標記時遭到封鎖。自訂的允許/拒絕規則優先解析。其餘所有操作都交由安全分類器處理。預設自動封鎖：curl | bash、強制推送至 main、正式環境部署、大規模雲端刪除、IAM 變更、將敏感資料傳送至外部。¹

熔斷機制：連續 3 次封鎖或單一工作階段累計 20 次封鎖，就會暫停並回到手動提示。

Auto 模式在讀取工作目錄以外的內容前所顯示的提示，提供 Yes, but ask again next time 選項（v2.1.284+）：允許該次讀取，之後的讀取仍會再次詢問。

無人值守模式中的危險 rm（v2.1.281）： 在 auto 模式與 --dangerously-skip-permissions 下，危險 rm 的提示會等待 2 分鐘，然後拒絕該命令並附上改寫提示，讓工作階段得以繼續。目標僅為命令替換輸出的遞迴 rm（例如 rm -rf "$(pwd)"），現在即使有 Bash 允許規則也會詢問。

# Enable at startup (--enable-auto-mode was removed in v2.1.111)
claude --permission-mode auto

# Cycle during session
Shift+Tab    # Manual (aka default) -> acceptEdits -> auto -> plan

權限變更（v2.1.288-290）： pyright 不再視為唯讀，會先詢問，更多形式的 ps 也是如此（v2.1.290）。專案的設定檔無法再啟用 Claude in Chrome；請改用 --chrome、/chrome 或您的使用者設定（v2.1.290）。用戶端的 auto 模式分類器會忽略指定 Sonnet 5.5 或 Opus 5.5 的 ANTHROPIC_DEFAULT_SONNET_MODEL 固定設定，並改用 Claude Sonnet 5（v2.1.288）。

PowerShell 自動核准（v2.1.119+）： PowerShell 工具命令在權限模式中的自動核准方式與 Bash 命令相同。像 PowerShell(Get-*:*) 這類允許規則可讓唯讀操作略過提示。大量使用 PowerShell 的工作流程請使用 v2.1.149+；該版本修正了內建 cd 的權限繞過、前綴/萬用字元允許規則的比對，以及目錄變數追蹤過時的問題。

9. Hook 事件

| InstructionsLoaded | CLAUDE.md 已載入 | 否 | | ConfigChange | 設定檔在工作階段中途變更 | 可 | | DirectoryAdded | /add-dir 或 SDK register_repo_root 在工作階段中途新增工作目錄（v2.1.219+） | 否 | | WorktreeCreate | 正在建立 worktree | 可 | | WorktreeRemove | 正在移除 worktree | 否 | | PreCompact | context 壓縮前 | 否 | | PostCompact | context 壓縮後 | 否 | | Elicitation | MCP 要求結構化輸入 | 可 | | ElicitationResult | 使用者回應 MCP 對話框 | 可 | | StopFailure | 回合因 API 錯誤而結束 | 否 | | PermissionRequest | 顯示權限對話框 | 可 | | PermissionDenied | Auto 模式拒絕某個動作（v2.1.88+） | 否 | | CwdChanged | 工作目錄變更（v2.1.83+） | 否 | | FileChanged | 監看中的檔案遭外部修改（v2.1.83+） | 否 | | TaskCreated | 建立新任務（v2.1.84+） | 否 | | TeammateIdle | Agent 團隊成員閒置 | 可 | | TaskCompleted | 任務標記為完成 | 可 |

完整的 hook 協定（輸入/輸出 JSON、matcher、結束代碼）請參閱完整指南中的 Hooks 深入解析。

10. Hook 設定

Hooks 存放於 settings.json 或專用的 hooks.json。最精簡的範例：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ]
  }
}

Matcher 語法：

結束代碼：

非同步 hooks 在背景執行而不會封鎖：在 hook 物件中加入 "async": true 即可。² 自 v2.1.302 起，同一事件的 prompt 與 agent hooks 最多同時執行 12 個；其餘則依序等候。¹³

Hook 輸出/輸入欄位：

• PostToolUse / PostToolUseFailure hook 輸入中的 duration_ms（v2.1.119+）：工具執行時間，不含權限提示與 PreToolUse hooks。
• hookSpecificOutput.updatedToolOutput（v2.1.121+）：替換任何工具的輸出（v2.1.118 僅為 MCP 引入此功能；v2.1.121 擴展至所有工具）。
• hookSpecificOutput.sessionTitle（v2.1.96+）：從 UserPromptSubmit hook 設定工作階段標題。
• 命令 hooks 上的 args: string[]（v2.1.139+）：傳遞結構化的 argv，無需 shell 引號處理。
• Skill hook 上限（v2.1.304+）：單一來源（一個 repo、您自己的資料夾或一個 plugin）的 skills 每個工作階段最多可註冊 1,024 個 hooks 與 16,384 個 matcher 字元；某個 skill 的 once hook 不再會移除另一個 skill 的相同 hook。
• PostToolUse hooks 上的 continueOnBlock（v2.1.139+）：將封鎖原因回饋給 Claude 並繼續該回合。
• Agent hook 輸入中的 subagent_type（v2.1.140+）：識別正在執行的 agent 類型。
• Hook JSON 輸出中的 terminalSequence（v2.1.141+）：發出終端機控制序列，用於通知、視窗標題與響鈴。
• 命令與 HTTP hooks 上的 onFailure: "block"（v2.1.295+）：hook 若無法啟動、逾時、以 0 或 2 以外的代碼結束、收到 HTTP 錯誤或印出無效的 JSON，就會封鎖該動作（效果等同結束代碼 2 在該事件上的作用；在 PermissionRequest 上則為拒絕）。預設為 "continue"；在 Stop、SubagentStop、TaskCompleted、TeammateIdle 與非同步 hooks 上會被忽略。

11. MCP 快速設定

只需一道命令即可新增 MCP 伺服器：

# Remote HTTP server (recommended)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# Remote with auth header
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer $TOKEN"

# Local stdio server
claude mcp add --transport stdio postgres \
  --env "DATABASE_URL=postgresql://user:pass@localhost/db" \
  -- npx -y @anthropic-ai/mcp-server-postgres

範圍控制：

claude mcp add --scope project ...   # Team-shared (.mcp.json)
claude mcp add --scope user ...      # Personal (~/.claude.json)

專案 .mcp.json 範例：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-postgres"],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost/db"
      }
    }
  }
}

MCP 目前每月下載量達 1 億次，已收錄超過 3,000 個伺服器。³ 如需瞭解傳輸類型、資訊徵詢與工具搜尋設定，請參閱完整指南中的 MCP 章節。

alwaysLoad（v2.1.121+）：讓受信任的伺服器略過 Tool Search 的延後載入機制。該伺服器的所有工具會在工作階段啟動時載入，無須透過 ToolSearch 往返查詢：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "alwaysLoad": true
    }
  }
}

alwaysLoad: false（v2.1.287+）的作用恰好相反：該伺服器的所有工具都會延後至工具搜尋時才載入。

自動重試（v2.1.121+）：MCP 伺服器若在啟動時發生錯誤，系統會重試最多 3 次，之後才將其標記為已中斷連線。

URL 提示（v2.1.287+）：使用 2025-11-25 協定的 MCP 伺服器可開啟 URL 提示，例如引導登入。若伺服器在更新後無法連線，請在其 MCP 設定項目中加入 "bareElicitationCapability": true。

SDK mcp_authenticate redirectUri（v2.1.121+）：使用自訂 URI 配置完成 OAuth 時的必要設定，適用於桌面應用程式與 claude.ai 連接器流程。

11.5. plugins CLI 命令

Mods（v2.1.287+）：mod 是一種 plugin，其 JavaScript 或 TypeScript 處理常式在 Claude Code 內執行：可繪製面板、新增命令，以及監看或修改工具呼叫。Mods 預設啟用；--safe-mode 可在單一工作階段停用它們，"disableAllHooks": true 則會在所有工作階段停用，但這兩種方式都不會停用內建 mods。⁸

LSP 伺服器（v2.1.288+）：LSP 伺服器項目可設定以毫秒為單位的 requestTimeout（預設為 60000）。因此，若伺服器始終未回應，請求會在 60 秒後判定為失敗，避免持續卡住。

12. subagents 類型

Claude 會自動將工作委派給 subagents。您也能明確要求使用：

> Use the explore agent to find all auth-related files
> Have a subagent analyze the database schema

自訂 subagents 以 Markdown 檔案定義，包含 YAML 前置中繼資料，存放於 .claude/agents/（專案）或 ~/.claude/agents/（個人）。預設最多可同時執行 20 個 subagents；可透過 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 調整上限。⁴ 自 v2.1.292 起，Agent 工具接受 effort 參數，因此可要求 Claude 以指定的投入程度執行 subagent；代理名稱的長度上限為 256 個字元（skill 或 plugin 檔案中超過此長度的 name 會被忽略）。自 v2.1.302 起，除了終端機，claude -p、Agent SDK、桌面應用程式與 VS Code 也都預設啟用 fork subagents（subagent_type: "fork"）（設為 CLAUDE_CODE_FORK_SUBAGENT=0 可停用；claude mcp serve 一律不提供此功能），而桌面應用程式與 VS Code 一律會在背景執行主對話的 subagents。¹³

在目前版本中，claude agents 會開啟 Agent View：這是研究預覽版的操作畫面，可查看執行中、受阻及已完成的 Claude Code 工作階段。claude agents --cwd <path> 可將檢視範圍限於單一目錄（v2.1.141+）；v2.1.142 新增背景工作階段的派送旗標；v2.1.143 則將這些旗標一致套用於儀表板與背景工作階段：--add-dir、--settings、--mcp-config、--plugin-dir、--permission-mode、--model、--effort 與 --dangerously-skip-permissions。v2.1.144 新增背景工作階段的 /resume 支援，並以 bg 標示；v2.1.145 新增 claude agents --json、等待輸入分頁的計數，並修正 Agent View 回覆面板的問題；v2.1.147 新增可釘選的背景工作階段，閒置時仍保持運作，更新時會在原處重新啟動；v2.1.287 新增 n:<text> 篩選器，可比對工作階段名稱與任務；v2.1.288 新增 Ctrl+F，可依名稱尋找工作階段，以及 Alt+Up / Alt+Down，可在群組間跳轉，兩者皆可在 keybindings.json 重新綁定（Ctrl+F 對應 agents:find）。請將 Agent View 用於監控，勿將其視為工作已通過品質檢核的證明。⁶

自訂代理的前置中繼資料欄位：

自訂代理範例（.claude/agents/security-reviewer.md）：

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after code changes to auth or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer. Analyze for OWASP Top 10 vulnerabilities,
secrets, hardcoded credentials, and SQL injection. Report findings with severity
levels and remediation steps.

13. 環境變數

驗證與 API

網路與代理伺服器

14. 成本參考

每100萬個token的定價（截至2026年10月）。⁵¹⁰

一般的工作階段約消耗50K-200K輸入token與10K-50K輸出token。Haiku 5.5工作階段：以100K token以內提示的費率計算，約$0.01-$0.05。Opus 5.5工作階段：$0.40-$1.80。

Claude Code中的預設模型（依方案）：自v2.1.280（2026年9月22日）起，所有方案皆預設為Opus——Pro與Team Standard從Sonnet改為Opus，與Max、Team Premium及Enterprise一致——而預設的Opus模型為Opus 5.5（claude-opus-5-5），opus別名現在即指向此模型。v2.1.251的分流（進階方案用Opus 5、Pro/Team Standard用Sonnet 5）與v2.1.197全面預設Sonnet 5的做法皆已成為歷史。管理員可設定組織層級的預設模型，在/model中顯示為「Org default」（v2.1.196+）。AWS上的Claude Platform、Amazon Bedrock與Google Cloud的Agent Platform同樣預設為Opus 5.5；Microsoft Foundry是唯一的例外（預設為Sonnet 4.5，也是唯一將opus解析為Opus 4.6之處）——可透過ANTHROPIC_DEFAULT_OPUS_MODEL／ANTHROPIC_DEFAULT_SONNET_MODEL固定特定模型。

Opus 5.5、Sonnet 5.5、Haiku 5.5、Sonnet 5、Opus 5、Opus 4.8、Fable 5與Fable 5.1僅使用自適應推理（沒有固定的思考預算），最困難的程式撰寫／代理式工作可使用/effort xhigh。這些模型的effort皆預設為high，但Opus 5.5與Sonnet 5.5例外，預設為medium，Haiku 5.5在Claude API上亦同——而且自v2.1.280起，在/effort改為依模型個別設定之前所儲存的effort等級，不再沿用至Opus 5.5等新發布的模型，因此新模型會從自身的預設值開始，直到您另行選擇為止。Opus 5.5、Sonnet 5.5與Fable系列模型無法關閉思考（MAX_THINKING_TOKENS=0在這些模型上無效）。Opus 5相較於Opus 4.8的重大變更：省略thinking欄位的請求預設開啟思考，而thinking: {type: "disabled"}搭配effort xhigh或max會回傳400錯誤。

快速模式（/fast）適用於Opus 5.5與Opus 5，以及2026年11月30日前的Opus 4.8（10月30日起棄用；移除後，在Opus 4.8上提出的快速模式請求會直接報錯，而非改以標準速度執行），自v2.1.280起以Opus 5.5為預設——Opus 5.5每MTok $8／$40，Opus 5與4.8為$10／$50（皆為基本價格的2倍），輸出速度最高可達每秒2.5倍的token。Opus 4.7已移除：claude-opus-4-7搭配speed: "fast"現在會報錯，而不再退回標準速度。目前為研究預覽，僅限Claude API與訂閱方案（不含Bedrock／Vertex／Foundry或AWS上的Claude Platform）；切換速度會使提示快取失效。自v2.1.271起，快速模式也可在Claude Code Remote工作階段（雲端與自架執行器）中使用：在組織允許的範圍內，主機的快速模式設定或在工作階段中輸入的/fast皆會生效。

在工作階段中切換模型：

/model opus       # Switch to Opus 5.5 (v2.1.280+)
/model sonnet     # Switch to Sonnet 5.5 on the Anthropic API (v2.1.284+)
/model haiku      # Switch to Haiku 5.5 on the Anthropic API (v2.1.293+)
/model fable      # Switch to Fable 5.1 (tier above Opus, v2.1.257+)
/effort xhigh     # Recommended for the hardest coding/agentic work

決策原則：簡單的探索交給Haiku。成本敏感的日常程式撰寫交給Sonnet。困難的推理、架構設計、代理式迴圈與安全分析交給Opus。複雜的重構可使用opusplan（由Opus規劃、Sonnet執行）。

15. 重要檔案位置

16. 變更紀錄

17. 參考資料

本速查表是完整 Claude Code CLI 指南的快速查閱配套。如需安裝設定的逐步說明，請參閱 Claude Code 快速入門。若是 iOS 與 macOS 專案，請參閱 iOS Agent 開發指南、XcodeBuildMCP 整合模式，以及 Apple 生態系系列。最後更新：2026年10月6日。