Claude Code CLI指南：安裝、設定、指令與環境變數

摘要：Claude Code是一套代理式CLI，透過分層的權限、hooks、MCP整合與subagents系統，讀取您的程式碼庫、執行命令並修改檔案。掌握5套核心系統（設定、權限、hooks、MCP與subagents），即可大幅提升生產力。請依各項工作選擇合適的模型層級：Opus適合複雜推理、Sonnet適合一般工作、Haiku適合快速探索；若品質是唯一考量，也可全面採用Opus。凡是必須每次執行的工作，請使用hooks，而非提示詞。截至v2.1.197（2026年6月30日），Claude Sonnet 5已成為Claude Code的預設模型——原生支援1M上下文，並於8月31日前提供$2/$10優惠價格；只要執行一次/model opus即可切換至Opus（自v2.1.219起，該別名會選用Claude Opus 5）。v2.1.198（7月1日）讓subagents預設在背景執行、使Chrome版Claude正式全面推出、允許背景代理完成worktree中的程式碼後提交、推送並開啟草稿PR，也會為背景工作階段觸發Notification hook（agent_needs_input／agent_completed）；v2.1.199（7月2日）可載入最多5個堆疊的slash-skill呼叫，並為訂閱者自動重試暫時性的429錯誤；v2.1.200（7月3日）在CLI、--help、VS Code與JetBrains中，將default權限模式重新命名為「Manual」（設定值維持不變，並接受manual作為別名），且預設不再讓AskUserQuestion對話框自動繼續；v2.1.202（7月6日）新增「Dynamic workflow size」/config控制項，並讓/review <pr>恢復為快速的單次審查，多代理審查則移至/code-review <level> <pr#>；v2.1.203–205（7月7日至9日）強化auto mode——禁止竄改逐字稿檔案、對無法解析變數所指定的rm -rf先行詢問，且背景工作通知會註明並無人工輸入（因此無法採納逐字稿中偽造的核准）——同時將/doctor改為完整的診斷與修復檢查（別名為/checkup）。^176177178 v2.1.217（7月21日）撤回了巢狀subagents的做法——subagents預設停止產生自己的subagents（3天後，v2.1.219又再次翻轉這項預設，恢復至3層深度；詳見下文）；預設最多可同時執行20個subagents（CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS），而--max-budget-usd現在會在達到上限時確實停止背景subagents。¹⁸⁹ v2.1.218（7月22日）將/code-review移至背景subagent——審查工作不再占用對話上下文——預設在背景執行context: fork skills（可在個別skill中設定background: false以停用），讓/deep-research僅於明確呼叫時啟動，並將危險rm、背景&與可疑Windows路徑的檢查交由auto-mode分類器處理，不再顯示權限對話框；此外，也不再執行來自不受信任資料夾的代理frontmatter hooks。¹⁹⁰ v2.1.219（7月24日）將Claude Opus 5（claude-opus-5）設為預設Opus模型——支援1M上下文、128K最大輸出，每MTok收費$5/$25（與Opus 4.8相同），預設啟用thinking，effort預設為high，知識截止日期為2026年5月——並修正先前版本造成的兩項現況：fast mode現在適用於Opus 5與Opus 4.8，每MTok收費$10/$50（基本費率的2倍，Opus 4.7則已完全退出fast mode），而且巢狀subagents再次預設啟用，深度為3層（設定CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1可停用巢狀結構）。同一版本還新增DirectoryAdded hook事件、sandbox.network.strictAllowlist設定、具有動態workflow的新workflowSizeGuideline設定鍵；後者現在預設採用中型規模準則（目標是少於15個代理），並在stream-json中支援巢狀subagent轉送。v2.1.220（7月25日）僅包含錯誤修正與可靠性改善。^191192193 截至v2.1.174–176（2026年6月12日），availableModels允許清單現在可透過新的enforceAvailableModels受管理設定限制Default模型（使用者／專案設定無法擴大受管理的清單）、工作階段標題會以您的對話語言產生（可用language設定固定語言）；此外，該版本還新增footerLinksRegexes與wheelScrollAccelerationEnabled設定、VSCode的/usage歸屬對話框，並修正hook的if條件，使其能比對Read／Edit／Write路徑模式。[^188] 截至v2.1.173（2026年6月11日），帶有[1m]後綴的Fable 5模型名稱會自動正規化並移除該後綴——Fable 5本身已預設包含1M上下文，因此不需要此後綴（它只對Opus／Sonnet有意義）。截至v2.1.172（2026年6月10日），sub-agents可遞迴產生自己的sub-agents，最多深入5層——這項預設一路維持至v2.1.216，並於v2.1.217關閉（詳見上文）——當未設定AWS_REGION時，Bedrock會從~/.aws讀取區域（/status會顯示來源）、/plugin新增市集搜尋列，而claude_code.lines_of_code.count OTEL指標則新增model屬性。截至v2.1.170（2026年6月9日），Claude Fable 5——位於Opus之上的新模型層級——可在執行claude update後，透過/model fable於Claude Code中選用（支援完整的low至max effort範圍，但無法停用thinking）；Opus 4.8仍是代理工作的預設模型。截至v2.1.169（2026年6月8日），--safe-mode（以及CLAUDE_CODE_SAFE_MODE）會啟動停用所有自訂項目的全新工作階段，以便進行疑難排解；/cd可將工作階段移至新的工作目錄，又不會破壞提示快取；disableBundledSkills則可向模型隱藏內建skills與slash commands。截至v2.1.166（2026年6月6日），fallbackModel設定可在主要模型過載時串接最多3個備用模型；glob "*"可用於MCP拒絕規則；MAX_THINKING_TOKENS=0／--thinking disabled則可在預設啟用thinking的模型上完全關閉thinking。截至v2.1.154（2026年5月28日），Opus 4.8成為新的預設模型，預設採用high effort，並新增/effort xhigh層級；dynamic workflows可透過/workflows在背景協調數十至數百個代理；Opus 4.8的Fast mode以標準費率2倍的成本提供2.5倍速度；除Haiku／Sonnet／Opus 4.7及更早版本外，所有模型現在預設使用精簡system prompt；/simplify恢復為僅執行清理的審查（與/code-review --fix分開）；claude agents接受! <command>以產生背景shell工作階段；plugins可宣告defaultEnabled: false；串流工具執行永遠啟用；stdio MCP伺服器會在環境中收到CLAUDE_CODE_SESSION_ID與CLAUDECODE=1。v2.1.153為plugin市集新增skipLfs、讓/model儲存為預設值（按s則僅套用於目前工作階段），並將COLUMNS／LINES加入狀態列環境。v2.1.152導入/code-review --fix（將發現的問題修正套用至工作樹）、skill frontmatter中的disallowed-tools、/reload-skills、新的MessageDisplay hook事件、SessionStart hook的reloadSkills／sessionTitle輸出、pluginSuggestionMarketplaces受管理設定，以及在工作階段中途切換--fallback-model的功能，並移除auto-mode的選擇加入機制。^{162 163 164 165 166 167 168} [^178] [^179] ¹⁹⁵ [^187]

Claude Code是以代理式系統運作，而不是具備程式設計知識的聊天介面。CLI會讀取您的程式碼庫、執行命令、修改檔案、管理git工作流程、透過MCP連接外部服務，並將複雜工作委派給專門的subagents。所有操作都透過命令列介面完成，融入開發人員的實際工作方式。截至2026年2月，公開GitHub提交中有4%（每日約135,000筆）由Claude Code撰寫——自研究預覽版發布後的13個月內成長42,896倍——而Anthropic本身90%的程式碼也由AI撰寫。¹⁰³

能否有效運用Claude Code，與只是偶爾使用之間的差異，取決於5套核心系統。掌握這些系統，Claude Code便能成為倍增生產力的利器：

1. 設定階層：控制行為
2. 權限系統：管控操作
3. Hook系統：實現具確定性的自動化
4. MCP協定：擴充能力
5. Subagent系統：處理複雜的多步驟工作

重點摘要

• 5套系統決定您的使用成效：設定階層、權限、hooks、MCP與subagents，控制從行為到自動化的一切。
• 將工作推送至委派層：subagents會在乾淨的上下文視窗中隔離探索工作，並僅傳回摘要，避免上下文過度膨脹。
• Hooks能保證執行，提示詞則否：凡是無論模型如何運作都必須每次執行的linting、格式化與安全性檢查，都應使用hooks。
• 模型分級可節省成本，又不犧牲品質：將subagent探索工作交給較便宜的模型，把Opus保留給真正需要架構推理的工作；若品質是唯一考量，也可全面採用Opus。
• MCP將Claude連接至您的工具鏈：資料庫、GitHub、Sentry以及3,000多項整合，讓Claude的能力超越檔案讀取與bash命令。

我花了數月時間，在正式環境程式碼庫、CI/CD管線與企業部署中，將Claude Code推向極限。本指南濃縮了這些經驗，成為我剛開始使用時最希望擁有的完整參考資料。每項功能都附有實際語法、真實設定範例，以及連資深使用者也容易踩到的陷阱與邊界案例。

選擇適合您的路徑

如何使用本指南

這是一份超過5,000行的參考資料，無須從頭到尾逐字閱讀。請依自身經驗程度選擇起點：

可使用瀏覽器的Ctrl+F／Cmd+F搜尋特定flag、命令或設定鍵。文末的快速參考卡提供所有主要命令的易讀摘要。

相關深度解析

下列部落格文章會深入探討Claude Code的特定面向：

60秒快速開始

如果您只想執行Claude Code並查看輸出，請依序操作：

# 1. Install (pick one)
npm install -g @anthropic-ai/claude-code          # npm users
brew install anthropic/claude/claude              # macOS + Homebrew
curl -sL claude.ai/install.sh | sh                # native installer

# 2. Launch in any project directory
cd ~/your-project && claude

# 3. Authenticate (browser opens automatically on first run)
/login

# 4. Ask your first question
> What does this repo do? Read the key files and summarize.

就是這樣。本節以下會延伸說明安裝選項、設定權限與 hooks、串接MCP伺服器，以及涵蓋企業部署；但開始使用並不需要這些內容。

先決條件：Node 18+僅適用於舊版 npm 路徑；建議使用的原生安裝程式不依賴 Node。支援 macOS / Linux / Windows 10+。Claude Pro、Max、Team 或 Enterprise 訂閱，或按 token 付費的Anthropic API金鑰，都可涵蓋使用量。平台細節、疑難排解，以及原生二進位檔路徑（自 v2.1.113 起為預設），請參閱如何安裝Claude Code？。本指南中的最新版本證據已對照 v2.1.154 檢查。¹⁹⁵

Claude Code如何運作：心智模型

深入功能之前，請先了解Claude Code的架構如何形塑您使用它時的一切操作。此系統分為三層運作：

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │              Subagents (up to 10 parallel)       │    │
│  │   Explore | Plan | General-purpose | Custom      │    │
│  └─────────────────────────────────────────────────┘    │
│  Isolated contexts for focused work, returns summaries  │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         Main Conversation Context                │    │
│  │   Tools: Read, Edit, Bash, Glob, Grep, etc.     │    │
│  └─────────────────────────────────────────────────┘    │
│  Your primary interaction; limited context; costs money │
└─────────────────────────────────────────────────────────┘

核心層：您的主要對話。每則訊息、檔案讀取與工具輸出，都會消耗共享視窗中的 context（標準為 200K tokens⁹¹，使用 Opus 4.6 或 extended context models 時為 1M tokens）。當 context 填滿時，Claude會失去對先前決策的掌握，品質也會下降。此層會按 token 產生成本。

委派層：Subagents 會以乾淨的 context 啟動，執行聚焦工作，並回傳摘要。探索結果不會膨脹您的主要對話；只有結論會回傳。可以將 subagents 指派到較便宜的 model tier 進行探索；若品質比成本更重要，也可以全程使用主要 model。

擴充層：MCP會連接外部服務（資料庫、GitHub、Sentry）。Hooks 可保證 shell commands 會執行，不受 model 行為影響。Skills 會編碼領域專業，讓Claude自動套用。Plugins 則將這些能力打包以便發佈。

關鍵洞見：多數使用者完全停留在核心層，看著 context 膨脹、成本攀升。進階使用者會把探索與專門工作推到委派層，讓擴充層維持符合自身工作流程的設定，並只把核心層用於協調與最終決策。

目錄

1. 如何安裝Claude Code？
2. 快速開始：您的第一次 session
3. 核心互動模式
4. 設定系統深入解析
5. 我該選擇哪個 model？
6. Claude Code費用是多少？
7. 決策框架
8. 權限系統如何運作？
9. Hooks 如何運作？
10. 什麼是MCP（Model Context Protocol）？
11. 什麼是 Subagents？
12. 什麼是 Extended Thinking Mode？
13. 輸出樣式
14. Slash Commands
15. Skills 如何運作？
16. Plugin System
17. Memory 如何運作？
18. 圖片與 Multimodal Input
19. Voice Mode
20. Git 整合如何運作？
21. 如何在我的 IDE 中使用Claude Code？
22. 進階使用模式
23. Remote & Background Agents [RESEARCH PREVIEW]
24. Chrome 中的Claude
25. Slack 中的Claude Code [RESEARCH PREVIEW]
26. Web 上的Claude Code [RESEARCH PREVIEW]
27. 效能最佳化
28. 如何偵錯問題？
29. 企業部署
30. 鍵盤快捷鍵參考
31. 最佳實務
32. Workflow Recipes
33. Migration Guide
34. 特定受眾指南
35. 快速參考卡
36. Changelog
37. References

如何安裝Claude Code？

系統需求

Claude Code可在macOS 13+、Ubuntu 20.04+/Debian 10+以及Windows 10+（原生或WSL）上執行。系統需要至少4 GB記憶體與穩定的網際網路連線。⁹²Shell相容性以Bash、Zsh或Fish最佳。

Windows方面，WSL 1與WSL 2均可運作。若您偏好原生Windows，Git Bash也可使用。Alpine Linux及其他基於musl的系統需要額外套件：

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

平台支援矩陣

安裝、更新、解除安裝速查

可快速掃描的查詢表——所有方式、所有指令、版本檢查一次呈現。下方各小節涵蓋每種方式的特定細節與疑難排解。

自v2.1.113起，標準的CLI透過各平台特定的選用相依套件來啟動原生Claude Code二進位檔，而非使用打包的JavaScript——請對已測試的發行版使用原生安裝程式。npm路徑仍可運作，但會率先收到自v2.1.15起新增的棄用通知。

安裝方式

原生安裝（建議）

原生二進位檔提供最簡潔的體驗，無需Node.js相依：

# macOS and Linux
curl -fsSL https://claude.ai/install.sh | bash

# Homebrew alternative
brew install --cask claude-code

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# Windows CMD
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

針對特定版本安裝：

# Install specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58

# Install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Windows PowerShell - specific version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58

NPM安裝（已棄用）

注意：自v2.1.15起，npm安裝會顯示棄用通知。原生二進位檔現為建議的安裝方式。請使用claude install進行遷移。

對於仍需使用npm的舊環境：

npm install -g @anthropic-ai/claude-code

切勿在npm安裝時使用sudo，這會造成權限問題並導致後續一連串的麻煩。

從現有安裝遷移

若您有較舊的npm安裝，請遷移至原生二進位檔：

claude install

驗證選項

Claude Code支援三種驗證路徑，各有不同的取捨：

Claude Console（API計費）

透過platform.claude.com（先前為console.anthropic.com）直接連線至Anthropic的API。建立帳戶、設定計費，並透過CLI進行驗證。Console提供按用量計費並可完整存取API。系統會自動建立專屬的「Claude Code」工作區；您無法為此工作區建立API金鑰，但可以監控用量。

Claude Pro或Max訂閱

使用您的claude.ai帳戶憑證。此訂閱以單一月費方案同時涵蓋網頁介面與CLI使用。對於希望成本可預測的個人使用者而言，訂閱簡化了計費流程。

企業平台

AWS Bedrock、Google Vertex AI與Microsoft Foundry皆提供企業級存取，並沿用既有的雲端計費關係。Bedrock設定精靈（v2.1.92+）：登入畫面上的互動式精靈會引導您完成AWS驗證、區域選擇、憑證驗證以及模型釘選。¹³⁷ Vertex AI設定精靈（v2.1.98+）：Google Cloud的對應精靈，引導GCP驗證、專案與區域設定、憑證驗證以及模型釘選。¹⁴² Vertex AI mTLS Workload Identity Federation（v2.1.121+）：Vertex AI現已接受基於X.509憑證的Workload Identity Federation（mTLS Application Default Credentials）——由用戶端憑證所產生的短期GCP權杖，無需服務帳戶JSON。¹⁵⁴ OS CA憑證信任（v2.1.101+）：企業TLS代理現可預設運作——Claude Code信任作業系統憑證儲存區。設定CLAUDE_CODE_CERT_STORE=bundled則僅使用打包的CA。¹⁴³

# AWS Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1
export AWS_PROFILE=your-profile

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east5
export ANTHROPIC_VERTEX_PROJECT_ID=your-project

# Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_RESOURCE=your-resource-name
# Optional: API key auth (otherwise uses Entra ID)
export ANTHROPIC_FOUNDRY_API_KEY=your-key

# Amazon Bedrock via Mantle (v2.1.94+)
export CLAUDE_CODE_USE_MANTLE=1

針對位於代理伺服器後方或透過LLM閘道的企業部署：

# Corporate proxy
export HTTPS_PROXY='https://proxy.example.com:8080'

# LLM gateway (skip native auth)
export CLAUDE_CODE_USE_BEDROCK=1
export ANTHROPIC_BEDROCK_BASE_URL='https://your-gateway.com/bedrock'
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1

驗證

claude doctor

此指令會回報安裝類型、版本、系統設定以及任何偵測到的問題。

驗證管理（v2.1.41+）

無需進入REPL即可管理驗證：⁹⁰

claude auth login          # Log in or switch accounts
claude auth status         # Check current auth state (account, plan, expiry)
claude auth logout         # Clear stored credentials

切換帳戶或組織的常見流程：

claude auth logout && claude auth login

另請參閱：如何除錯問題？ 以排解驗證失敗問題。

更新

Claude Code預設會自動更新，於啟動時及執行階段定期檢查。更新會在背景下載，並於下次啟動時套用。

停用自動更新：

export DISABLE_AUTOUPDATER=1

或於settings.json中設定：

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

手動更新：

claude update

解除安裝

原生安裝（macOS/Linux/WSL）：

rm -f ~/.local/bin/claude
rm -rf ~/.claude-code

原生安裝（Windows PowerShell）：

Remove-Item -Path "$env:LOCALAPPDATA\Programs\claude-code" -Recurse -Force
Remove-Item -Path "$env:LOCALAPPDATA\Microsoft\WindowsApps\claude.exe" -Force

清除設定（移除所有設定）：

rm -rf ~/.claude
rm ~/.claude.json
rm -rf .claude
rm -f .mcp.json

快速開始：您的第一次工作階段

1. 安裝並啟動：

claude                           # Launch in current directory

2. 前往專案目錄：

cd ~/my-project && claude        # Or launch from any git repo

3. 請 Claude 執行任務：

> "Explain the architecture of this project"
> "Find all TODO comments and create a summary"
> "Add input validation to the signup form"

4. 在工作階段中使用鍵盤快速鍵：

/cost                            # Check token usage and cost
/compact                         # Free up context when it gets large
Alt+T                            # Toggle extended thinking for hard problems
Ctrl+C                           # Cancel current response

5. 稍後繼續：

claude -c                        # Resume your most recent session
claude --resume                  # Pick from session list

專家提示：在專案根目錄建立 CLAUDE.md 檔案，記錄建置指令、程式碼慣例與架構備註。Claude 會在每次工作階段讀取此檔案——這是提升品質最事半功倍的一項措施。

核心互動模式

互動式 REPL

啟動 Claude Code 時不帶任何引數，即可進入互動式讀取—求值—輸出迴圈：

cd your-project
claude

REPL 會跨回合保留對話脈絡。直接輸入查詢、接收回應並繼續互動，直到使用 /exit 或 Ctrl+D 結束。

使用初始提示詞啟動，讓工作階段聚焦於特定任務：

claude "explain the authentication flow in this project"

專家提示：即使發生脈絡壓縮，REPL 仍會保留狀態。當脈絡過於龐大時，Claude 會自動摘要較早的對話，同時保留關鍵決策與程式碼片段。您也可以使用 /compact 手動觸發，或加入自訂指示，指定要保留的內容。

非互動模式

列印模式（-p）會執行單次查詢後結束：

# Direct query
claude -p "list all TODO comments in this project"

# Process piped input
cat error.log | claude -p "identify the root cause of these failures"

# Chain with other tools
claude -p "generate a README" > README.md

若需要適合在指令碼中剖析的結構化輸出：

claude -p "count lines by file type" --output-format json

JSON 輸出包含自動化所需的一切資訊：

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.0034,
  "is_error": false,
  "duration_ms": 2847,
  "duration_api_ms": 1923,
  "num_turns": 4,
  "result": "Response text here...",
  "session_id": "abc-123-def"
}

若要即時處理串流輸出：

claude -p "build the application" --output-format stream-json | while read line; do
  echo "$line" | jq -r 'select(.result) | .result'
done

輸出格式選項：

stream-json 中的 subagent 文字（v2.1.211+）：預設情況下，stream-json 輸出只會包含主要工作階段的事件；subagents 內完成的工作則以摘要呈現。--forward-subagent-text 旗標（或 CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1）也會將 subagent 的文字與思考輸出轉送至串流，讓執行框架與記錄管線能即時觀察委派工作的進展，而非只能看到最終報告。¹⁸³

巢狀 subagents 現在也會轉送（v2.1.219）。最初只有深度為 1 的 subagents 會顯示。如今，於深度 2 及更深層級產生的 subagents 也會出現在轉送串流中；每個項目皆以產生它的 Agent 呼叫之 tool_use id 作為索引。因此，管線可以重建委派樹狀結構，而不是只看到扁平的文字清單。此功能正好配合相同版本恢復預設可在深度 3 產生巢狀 subagents；若缺少轉送功能，3 個層級中將有 2 個無法觀察。¹⁹¹

結束代碼：

控制 -p 模式中的代理行為：

# Limit autonomous turns (prevents runaway loops)
claude -p "refactor the auth module" --max-turns 10

# Allow specific tools without prompting
claude -p "fix lint errors" --allowedTools "Edit,Bash(npm run lint)"

# Use with a specific model
claude -p "explain this code" --model claude-sonnet-4-5-20250929

# Bare mode: skip hooks, LSP, plugin sync, skill walks (v2.1.81+)
claude -p "count files" --bare

# Channel permission relay: send approval prompts to Telegram/Discord (v2.1.81+)
claude --channels

CI/CD 整合模式：

# In a GitHub Action or CI pipeline
result=$(claude -p "review this diff for security issues" --output-format json 2>/dev/null)
is_error=$(echo "$result" | jq -r '.is_error')
if [ "$is_error" = "true" ]; then
  echo "Review failed"
  exit 1
fi
echo "$result" | jq -r '.result'

工作階段管理

工作階段會保留對話歷程，以便後續接續。對於跨越多個工作階段的複雜工作，工作階段持久化不可或缺：

# Continue most recent session
claude -c

# Continue with additional prompt
claude -c -p "now add error handling"

# Resume specific session by ID
claude -r "abc123" "implement the remaining tests"

# Fork a session for parallel exploration
claude -r "base-session" --fork-session "try a different approach"

連結 PR 的工作階段（v2.1.27+，於 v2.1.119+ 擴充）：啟動連結至特定 pull request 或 merge request 的工作階段。自 v2.1.119 起，除了 github.com 之外，--from-pr 也接受 GitLab MR、Bitbucket PR 與 GitHub Enterprise PR URL：⁷⁴¹⁵²

claude --from-pr 123                                                # GitHub PR number (assumes current repo's remote)
claude --from-pr https://github.com/org/repo/pull/123               # GitHub URL
claude --from-pr https://gitlab.com/org/repo/-/merge_requests/45    # GitLab MR (v2.1.119+)
claude --from-pr https://bitbucket.org/org/repo/pull-requests/67    # Bitbucket PR (v2.1.119+)
claude --from-pr https://ghe.example.com/org/repo/pull/89           # GitHub Enterprise (v2.1.119+)

如果您在工作階段中透過 gh pr create 建立 PR，工作階段也會自動連結至該 PR，方便日後繼續處理特定 PR。頁尾的 PR 徽章可以透過 prUrlTemplate 設定指向自訂程式碼審查 URL（v2.1.119+）；若團隊會從 PR 連結至另一套審查工具，此功能相當實用。¹⁵²

/resume 接受 PR URL（v2.1.122+）。現在只要將 PR URL 貼入 /resume 搜尋框，即可找到最初建立該 PR 的工作階段；支援 github.com、GitHub Enterprise、gitlab.com（包含自行託管的 GitLab）及 bitbucket.org。¹⁵⁴

具名工作階段：可在啟動時或工作階段進行期間命名：

# Name session at startup (v2.1.76+)
claude -n "auth-refactor"                  # --name flag sets display name[^125]

# Name current session
> /rename auth-refactor

# Resume by name or number
> /resume 1                    # Resume first session
> /resume auth-refactor        # Resume by name
claude --resume auth-refactor  # Resume from terminal
claude -r 3                    # Resume by number from terminal

# Fork for parallel exploration
claude --resume auth-refactor --fork-session

注意：--session-id 需要有效的 UUID（例如 550e8400-e29b-41d4-a716-446655440000）。若要使用易於閱讀的工作階段名稱，請改用 /rename 與 --resume。

/fork 會產生背景工作階段；/subtask 則是在目前工作階段內分支（v2.1.212）。現在，/fork 指令會將目前對話複製至新的背景工作階段。該工作階段會在 claude agents 中擁有自己的資料列，因此您可以讓副本探索其他方案，同時繼續主要工作階段。原本在目前工作階段內分支的行為，則以新名稱 /subtask 延續。¹⁸⁴ 自 v2.1.214 起，以分支形式啟動的工作階段會將 SessionStart hook 來源回報為 "fork"（先前為 "resume"），讓依來源比對的 hooks 能夠區分兩者。¹⁸⁵ v2.1.216 將 /fork 確認訊息精簡為一行，顯示新工作階段的名稱及其 claude attach id。¹⁸⁷

Claude Code 會將工作階段儲存為 JSONL 逐字記錄。Agent 執行時會指派唯一的 agentId 值，逐字記錄則儲存為 agent-{agentId}.jsonl。恢復工作階段時，會保留先前對話的完整脈絡。

計畫模式

計畫模式會將 Claude 限制為唯讀探索，不允許編輯檔案、執行 bash 或進行破壞性操作。Claude 會設計實作方案、將其寫入計畫檔案，並在執行任何操作前等待您的核准。

進入計畫模式：

# Cycle through modes during a session
Shift+Tab           # Cycles: normal → plan → auto-accept

# Or use the /plan command with an optional description (v2.1.72+)
/plan                                     # Enter plan mode
/plan refactor the auth module            # Enter plan mode with a description

# Or ask Claude directly
"Plan how to refactor the auth module"   # Claude may enter plan mode automatically

運作方式：

1. Claude 進入計畫模式（複雜任務會自動進入，也可透過 Shift+Tab 切換）
2. 使用唯讀工具探索程式碼庫：Read、Glob、Grep、WebSearch、WebFetch
3. 將計畫寫入 .claude/plans/{session-slug}.md
4. 使用 ExitPlanMode 結束計畫模式，並呈現計畫供您審閱
5. 您可以核准、要求修改或拒絕

計畫模式中可用的工具：Read、Glob、Grep、LS、WebSearch、WebFetch、AskUserQuestion。編輯工具（Edit、Write、Bash、NotebookEdit）會遭封鎖。

核准計畫後（v2.1.32+）：Claude 會提供 3 個選項： - 「是，清除脈絡並自動接受編輯」（Shift+Tab）——以完整的計畫脈絡重新開始 - 「是，並手動核准編輯」——保留脈絡，由您核准每項變更 - 「是，自動接受編輯」——保留脈絡，由 Claude 執行，不逐項要求核准

核准時自動清除脈絡是建議的工作流程。這會為計畫提供全新的脈絡視窗，顯著提升計畫遵循度；沒有舊對話的干擾，Claude 能更長時間維持正軌。

適合使用計畫模式的情境： - 涉及架構決策的新功能實作 - 希望先審閱方案的多檔案重構 - 應先探索再修改的不熟悉程式碼庫 - 任何存在多種可行方案，且您希望參與決策的任務

專家提示：投入計畫模式的時間越多，Claude 成功實作的機率通常越高。計畫模式實際上提供了零風險探索，不會呼叫高風險工具，也不會產生徒勞的編輯。不妨善加運用。

螢幕閱讀器模式（v2.1.208）

Claude Code 內建專用的螢幕閱讀器模式，可調整終端機 UI 以配合輔助科技。以下 3 種方式皆可啟用：¹⁸¹

# Flag at launch
claude --ax-screen-reader

# Environment variable
export CLAUDE_AX_SCREEN_READER=1

# Or persistently in settings.json
{ "axScreenReader": true }

Anthropic 的官方文件新增了無障礙功能頁面，說明此模式及其互動方式。¹⁸¹

深入解析設定系統

Claude Code採用分層設定系統。理解其階層至關重要，因為較高層級會覆寫較低層級，而且企業設定完全無法繞過。

設定階層

專家提示：在共用專案中，請使用.claude/settings.local.json儲存個人偏好設定（並將其加入.gitignore）。需要納入版本控制、供整個團隊共用的設定，則請使用.claude/settings.json。

從提示中設定組態：/config key=value（v2.1.181）

自v2.1.181起，/config key=value可直接從提示中設定任何項目，例如/config thinking=false，不必開啟互動式/config使用者介面；此功能適用於互動模式、-p及Remote Control工作階段。/config --help（v2.1.183）會列出可用的簡寫鍵。v2.1.183也調整了互動式/config使用者介面：Enter與Space皆可切換所選設定，Esc則會儲存並關閉（先前會還原變更）。¹⁶⁹

完整settings.json參考資料

以下完整設定範例涵蓋所有主要選項：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-5-20250929",
  "permissions": {
    "allow": [
      "Read",
      "Glob",
      "Grep",
      "Bash(npm run:*)",
      "Bash(git:*)",
      "Bash(make:*)",
      "Edit(src/**)",
      "mcp__github"
    ],
    "deny": [
      "Read(.env*)",
      "Read(secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Edit(package-lock.json)",
      "Edit(.git/**)"
    ],
    "ask": [
      "WebFetch",
      "Bash(curl:*)",
      "Bash(docker:*)"
    ],
    "additionalDirectories": [
      "../shared-lib",
      "../docs"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "app:*"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$FILE_PATH\""
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "tips": ["Custom tip 1", "Custom tip 2"],
    "excludeDefault": true
  },
  "skillOverrides": {
    "legacy-skill": "off",
    "manual-only-skill": "user-invocable-only",
    "compact-skill": "name-only"
  },
  "includeGitInstructions": false,
  "modelOverrides": {
    "bedrock": "us.anthropic.claude-opus-4-6-20260312-v1:0",
    "vertex": "claude-opus-4-6@20260312",
    "foundry": "anthropic.claude-opus-4-6"
  },
  "autoMemoryDirectory": ".claude/memory",
  "sandbox": {
    "enableWeakerNetworkIsolation": true
  }
}

當團隊擁有龐大的skill程式庫，但希望更嚴格地控制執行階段的公開範圍時，skillOverrides相當實用。使用off可同時在模型與斜線命令選擇器中隱藏skill；使用user-invocable-only可保留依名稱呼叫的能力，但不讓模型選用；使用name-only則只顯示skill名稱，不顯示完整說明。¹⁵⁶

較新的設定（v2.1.174–176）：

• availableModels / enforceAvailableModels（受管控，v2.1.175+）：availableModels允許清單會限制工作階段可選用的模型。設為enforceAvailableModels: true後，允許清單也會約束預設模型；若預設項目解析後指向不允許的模型，便會改用允許清單中的第一個模型。此外，使用者／專案設定也無法再擴大受管控的availableModels清單。配套修正（v2.1.176）封堵了別名選項可透過ANTHROPIC_DEFAULT_*_MODEL重新導向遭封鎖模型的漏洞；如今，若模型不在允許清單內，/fast也會拒絕切換。[^188] 自v2.1.187起，組織可直接對/model選擇器、--model、/model及ANTHROPIC_MODEL全面強制套用模型限制；選取受限制的模型時，會顯示「受您組織的設定限制」訊息。¹⁷¹
• language（v2.1.176改良）：除了設定回應語言外，工作階段標題現在預設會以對話所用的語言產生；設定language即可將標題固定為特定語言。[^188]
• footerLinksRegexes（v2.1.176）：在頁尾列中顯示符合正規表示式的連結徽章，可透過使用者設定或受管控設定進行配置。[^188]
• wheelScrollAccelerationEnabled（v2.1.174）：設為false可停用全螢幕模式下的滑鼠滾輪捲動加速。[^188]

較新的設定（v2.1.207–v2.1.212）：

• vimInsertModeRemaps（v2.1.208）：為vim插入模式自訂按鍵重新對應；經典範例是將jj對應至Escape（請參閱Vim模式）。¹⁸¹
• axScreenReader（v2.1.208）：持續啟用螢幕閱讀器模式（請參閱螢幕閱讀器模式）。¹⁸¹
• processWrapper（v2.1.208）：讓Claude Code為自身啟動的每個處理程序皆透過包裝函式執行檔運作；此功能專為企業啟動器而設計（請參閱企業啟動器）。¹⁸¹
• autoMode來源限制（v2.1.207）：系統不再從儲存庫的.claude/settings.local.json讀取autoMode設定；請改在~/.claude/settings.json中進行配置。如此可封堵複製而來的儲存庫夾帶自動模式設定的途徑。¹⁸⁰

較新的設定（v2.1.217）：

• emojiCompletionEnabled（v2.1.217）：在提示輸入框中自動完成表情符號短碼；輸入:heart:可插入❤️，輸入:hea之類的部分內容則會顯示建議。預設啟用；設為false即可停用。¹⁸⁹

較新的設定（v2.1.219）：

• sandbox.network.strictAllowlist（v2.1.219）：對沙箱命令拒絕不在允許清單內的主機，且不會顯示提示，而非開啟權限對話框。請參閱沙箱模式。¹⁹¹
• workflowSizeGuideline（v2.1.219）：可從任何設定檔（使用者、專案或受管控設定）設定具建議性質的Dynamic工作流程規模準則，不再僅能透過/config設定。Dynamic工作流程預設採用中等準則（「目標為少於15個agents」）；由設定檔提供此值時，/config中的對應列會自行隱藏。這只是建議，並非強制上限。請參閱Subagents。¹⁹¹

環境變數參考資料

驗證與API：

ANTHROPIC_API_KEY=sk-ant-...                    # Direct API authentication
ANTHROPIC_AUTH_TOKEN=token                      # Custom authorization header
ANTHROPIC_CUSTOM_HEADERS="X-Key: val"           # Additional request headers

模型設定：

ANTHROPIC_MODEL=claude-opus-4-7                 # Override default model (Apr 16, 2026)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-7    # Opus 4.7 (Max/Team Premium default)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Model for subagents
CLAUDE_CODE_WORKFLOWS=1                         # Enable Workflow tool for deterministic multi-agent orchestration (v2.1.147+)
MAX_THINKING_TOKENS=10000                       # (Opus 4.6 and Sonnet 4.6 only — removed in Opus 4.7)
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Enable agent teams (v2.1.32+)

雲端供應商設定：

CLAUDE_CODE_USE_BEDROCK=1                       # Use AWS Bedrock
CLAUDE_CODE_USE_VERTEX=1                        # Use Google Vertex AI
CLAUDE_CODE_USE_FOUNDRY=1                       # Use Microsoft Foundry
ANTHROPIC_BEDROCK_BASE_URL=https://...          # Custom Bedrock endpoint
ANTHROPIC_BEDROCK_SERVICE_TIER=priority         # Bedrock service tier (v2.1.122+): 'default', 'flex', or 'priority'; sent as X-Amzn-Bedrock-Service-Tier header[^162]
CLAUDE_CODE_SKIP_BEDROCK_AUTH=1                 # Skip Bedrock auth (for gateways)
CLAUDE_CODE_SKIP_VERTEX_AUTH=1                  # Skip Vertex auth
AWS_BEARER_TOKEN_BEDROCK=token                  # Bedrock bearer token
VERTEX_REGION_CLAUDE_3_7_SONNET=us-west1        # Override Vertex region
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1    # Opt in gateway /v1/models discovery for /model picker (v2.1.129+)[^164]

行為控制：

DISABLE_AUTOUPDATER=1                           # Prevent automatic background updates
DISABLE_UPDATES=1                               # Block ALL update paths including manual `claude update` (v2.1.118+, stricter than DISABLE_AUTOUPDATER)[^160]
CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1       # Homebrew/WinGet installs run package-manager upgrade in background, then prompt restart (v2.1.129+)[^164]
DISABLE_TELEMETRY=1                             # Opt out of usage telemetry
DISABLE_ERROR_REPORTING=1                       # Disable Sentry
DISABLE_BUG_COMMAND=1                           # Disable /bug command
DISABLE_COST_WARNINGS=1                         # Hide cost warnings
DISABLE_PROMPT_CACHING=1                        # Disable prompt caching globally
DISABLE_PROMPT_CACHING_SONNET=1                 # Disable for Sonnet only
DISABLE_PROMPT_CACHING_OPUS=1                   # Disable for Opus only
DISABLE_NON_ESSENTIAL_MODEL_CALLS=1             # Skip non-critical API calls
ENABLE_PROMPT_CACHING_1H=1                      # Opt into 1-hour prompt cache TTL (v2.1.108+, API/Bedrock/Vertex/Foundry)
ENABLE_PROMPT_CACHING_1H_BEDROCK=1              # Deprecated alias for the above; v2.1.108+ still honors it on Bedrock but logs a deprecation notice
FORCE_PROMPT_CACHING_5M=1                       # Force 5-minute cache TTL (v2.1.108+)
ENABLE_TOOL_SEARCH=true                         # Re-enable tool search on Vertex AI (disabled by default v2.1.119+ to avoid unsupported beta header). Valid values: true, false, auto, auto:N[^160]
CLAUDE_CODE_HIDE_CWD=1                          # Hide the working directory in the startup logo (v2.1.119+)[^160]
CLAUDE_CODE_FORK_SUBAGENT=1                     # Enable forked subagents on external builds (v2.1.117+)[^160]
CLAUDE_CODE_FORCE_SYNC_OUTPUT=1                 # Force synchronized terminal output when auto-detection misses it, such as Emacs eat (v2.1.129+)[^164]
CLAUDE_CODE_SESSION_ID=...                      # Read-only: present in the Bash tool subprocess; matches the session_id passed to hooks (v2.1.132+)[^168]
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1          # Skip the fullscreen alternate-screen renderer; keep the conversation in the terminal's native scrollback (v2.1.132+)[^168]
CLAUDE_EFFORT=...                               # Read-only: current effort level inside hooks and Bash tool subprocess (v2.1.133+)[^169]
CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1             # Include subagent text + thinking in stream-json output; pairs with --forward-subagent-text (v2.1.211+). Covers depth-2+ nested subagents as of v2.1.219[^205][^213]
CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=200    # Per-session WebSearch cap (default 200; v2.1.212+)[^206]
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=200       # Per-session subagent-spawn cap (default 200; /clear resets the budget; v2.1.212+)[^206]
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=20         # Cap on concurrently-RUNNING subagents (default 20; distinct from the per-session total above; v2.1.217+)[^211]
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=3          # Nested subagent spawn depth. Default 3 as of v2.1.219; set 1 to disable nesting. Default history: 5 (v2.1.172–v2.1.216) → 1 (v2.1.217) → 3 (v2.1.219). Set it explicitly[^211][^213]

工具設定：

BASH_DEFAULT_TIMEOUT_MS=30000                   # Bash command timeout (30s)
BASH_MAX_TIMEOUT_MS=600000                      # Maximum bash timeout (10min)
BASH_MAX_OUTPUT_LENGTH=50000                    # Bash output limit
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1     # Reset CWD after each bash
MCP_TIMEOUT=5000                                # MCP server startup timeout
MCP_TOOL_TIMEOUT=30000                          # MCP tool execution timeout
MAX_MCP_OUTPUT_TOKENS=25000                     # MCP output limit
CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=120000       # Threshold before a long MCP tool call moves to the background (default 2 min; v2.1.212+)[^206]
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

網路與Proxy：

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
NO_PROXY=localhost,example.com                  # Bypass proxy for domains
CLAUDE_CODE_CLIENT_CERT=/path/to/cert           # mTLS certificate
CLAUDE_CODE_CLIENT_KEY=/path/to/key             # mTLS private key
CLAUDE_CODE_CLIENT_KEY_PASSPHRASE=pass          # mTLS passphrase

使用者介面與終端機：

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory[^50]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Disable 1M context window (use standard 200K)[^103]
CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=120000       # Plugin marketplace git timeout (default 120s, was 30s)[^105]
CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1        # Remove built-in commit/PR instructions[^117]
CLAUDE_CODE_DISABLE_CRON=1                    # Stop scheduled cron jobs mid-session[^121]
CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=30000 # SessionEnd hooks timeout (default varies)[^123]
CLAUDE_CODE_USE_POWERSHELL_TOOL=1             # Enable Windows PowerShell tool on Linux/macOS (requires pwsh on PATH; v2.1.111+)[^153]
CLAUDE_CODE_DISABLE_MOUSE_CLICKS=1           # Disable mouse click/drag/hover in fullscreen mode; wheel scroll still works (v2.1.195+)[^196]
CLAUDE_ENABLE_STREAM_WATCHDOG=0              # Disable the streaming idle watchdog (on by default for all providers since v2.1.196: aborts+retries after 5 min of silence)[^198]
CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP=1 # Turn off automatic memory-pressure reaping of idle background shell commands (v2.1.193+)[^196]
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1             # Force Session Recap when telemetry disabled (v2.1.108+)[^153]
CLAUDE_AX_SCREEN_READER=1                     # Enable screen reader mode; same as --ax-screen-reader or "axScreenReader": true (v2.1.208+)[^203]
OTEL_LOG_RAW_API_BODIES=1                     # Emit full API request/response bodies as OTel log events (v2.1.111+)[^153]
TRACEPARENT=00-...                            # W3C Trace Context parent (v2.1.110+, SDK/headless)[^153]
TRACESTATE=vendor=value                       # W3C Trace Context state (v2.1.110+, SDK/headless)[^153]

OpenTelemetry匯出器與敏感欄位閘控：¹⁹⁶

OTEL_LOGS_EXPORTER=none                       # OTel logs exporter (supports 'none' for disable; v2.1.85 fixed crash)
OTEL_METRICS_EXPORTER=none                    # OTel metrics exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_TRACES_EXPORTER=none                     # OTel traces exporter (supports 'none'; v2.1.85 fixed crash)
OTEL_LOG_TOOL_CONTENT=1                       # Opt in to emitting tool content in OTel spans (v2.1.101+, sensitive by default)
OTEL_LOG_TOOL_DETAILS=1                       # Opt in to tool_parameters in OTel tool_result events (v2.1.85+)
OTEL_LOG_USER_PROMPTS=1                       # Opt in to emitting user prompts in OTel traces (v2.1.101+, sensitive by default)
OTEL_LOG_ASSISTANT_RESPONSES=0                # Gate the claude_code.assistant_response log event holding the model's response text (v2.1.193+)
CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH=60000     # Truncation limit for OTel content attributes (default 60 KB; v2.1.214+)[^207]
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1    # Disable release-notes fetch (v2.0.17+); v2.1.110 also stopped the auto-title Haiku request in headless/SDK when set

v2.1.121+ LLM請求span屬性：stop_reason、gen_ai.response.finish_reasons及user_system_prompt現在會在LLM請求span上發出。由於user_system_prompt可能包含個人識別資訊（PII），因此須透過OTEL_LOG_USER_PROMPTS=1才能啟用。¹⁵⁴

v2.1.122+事件層級變更：api_request與api_error記錄事件中的數值屬性，現在會以數值而非字串形式發出；此修正解決下游OTel收集器對結構描述採用嚴格型別時的問題。當Claude Code解析@提及時，會觸發新的claude_code.at_mention記錄事件。¹⁵⁴

v2.1.193+ claude_code.assistant_response記錄事件：Claude Code可將模型的完整回應文字作為OTel記錄事件發出，並由OTEL_LOG_ASSISTANT_RESPONSES控制。此閘控機制有一項升級時務必留意的陷阱：若未設定OTEL_LOG_ASSISTANT_RESPONSES，它會跟隨OTEL_LOG_USER_PROMPTS；因此，任何已記錄提示內容的部署在升級後，也會開始收到助理回應內容。若希望遙測資料仍僅包含提示，請設定OTEL_LOG_ASSISTANT_RESPONSES=0。¹⁷⁴

v2.1.214遙測新增項目：OTel記錄事件現在包含message.uuid、client_request_id及tool_source屬性，可供訊息層級關聯與工具來源追蹤；subagentStatusLine承載資料包含subagent的推理強度，因此自訂狀態列可同時呈現模型與強度；新的CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH環境變數則可設定OTel內容屬性的60 KB截斷上限。¹⁸⁵

API／模型控制：¹⁹⁶

CLAUDE_CODE_EXTRA_BODY='{...}'                # Inject extra body fields into API calls; v2.1.113 fixed 400 errors with output_config.effort on Vertex/subagent calls
CLAUDE_CODE_MAX_CONTEXT_TOKENS=200000         # Override max context tokens (pre-existing var; v2.1.98 fixed handling of DISABLE_COMPACT when both are set)
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS=25000 # Override default token limit for file read operations (v2.1.0+)
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1   # Do not fall back to non-streaming API on streaming failures (v2.1.83+)
ANTHROPIC_BETAS=beta1,beta2                   # Enable beta API headers; v2.1.78 fixed silent ignore on Haiku models
ANTHROPIC_SMALL_FAST_MODEL=arn:...            # Fast model ID (Bedrock ARN supported; v0.2.125 stopped escaping slashes in ARN)

Plugins／MCP：¹⁹⁶

CLAUDE_CODE_PLUGIN_CACHE_DIR=~/.claude/plugins # Plugin cache directory (v2.1.72 fixed literal '~' dir on some shells)
CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 # Preserve plugin marketplace cache when git pull fails (offline-friendly; v2.1.90+)
CLAUDE_CODE_MCP_SERVER_NAME=server1           # Passed to MCP headersHelper scripts so one helper can serve multiple servers (v2.1.85+)
CLAUDE_CODE_MCP_SERVER_URL=https://...        # Passed to MCP headersHelper scripts alongside the name (v2.1.85+)

Shell／IDE：¹⁹⁶

CLAUDE_CODE_SHELL_PREFIX="time "              # Wrap every Claude-invoked shell command with a prefix (v1.0.61+)
CLAUDE_CODE_GIT_BASH_PATH=C:\Program\ Files\Git\bin\bash.exe  # Custom Git Bash path on Windows (v2.1.98+)
CLAUDE_CODE_EXIT_AFTER_STOP_DELAY=60000       # SDK: exit after N ms idle (v2.0.35+)
CLAUDE_CODE_AUTO_CONNECT_IDE=false            # Disable IDE auto-connection (v1.0.61+)

企業／驗證：¹⁹⁶

CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1            # Opt into proxy-side DNS resolution (v2.0.55 moved this from default-on to opt-in)
CLAUDE_CODE_API_KEY_HELPER_TTL_MS=300000      # TTL for dynamically generated API keys via apiKeyHelper (apiKeyHelper refresh added v0.2.74 with 5-min default; env var added v0.2.117)
CLAUDE_CODE_PROCESS_WRAPPER=/path/to/wrapper  # Route all Claude Code self-spawned processes through a wrapper executable; same as the processWrapper setting (v2.1.208+)[^203]

Skill變數（v2.1.69+）：

${CLAUDE_SKILL_DIR}                            # Self-reference for skills to locate their own directory[^117]

SDK呼叫端身分（v2.1.51+）：

CLAUDE_CODE_ACCOUNT_UUID=uuid                  # Provide account UUID synchronously for SDK callers
CLAUDE_CODE_USER_EMAIL=user@example.com        # Provide user email for SDK callers
CLAUDE_CODE_ORGANIZATION_UUID=uuid             # Provide organization UUID for SDK callers

除錯：

ANTHROPIC_LOG=debug                             # Enable API request logging

我該選擇哪個模型？

針對每項任務選擇合適的模型，會顯著影響成本與品質。Claude Code提供多層級的彈性模型切換機制。

可用模型

將執行框架從Opus 4.8移轉至Opus 5時，有兩項破壞性變更：¹⁹²

1. 思考功能預設開啟。在Opus 4.8中，未提供thinking欄位的要求會在不思考的情況下執行；相同要求在Opus 5中則會使用自適應思考。max_tokens仍是總輸出的硬性上限——包含思考與回應文字——因此，凡是先前未使用思考功能的工作負載，都應重新檢查預留空間。若要恢復舊有行為，請傳入thinking: {type: "disabled"}，但須遵守下一項限制。
2. 停用思考時，effort最高只能設為high。若將thinking: {type: "disabled"}與xhigh或max effort搭配使用，會傳回400。此檢查會逐項要求執行；即使同一對話中先前的輪次已獲接受，在停用思考時將effort提高至xhigh仍會遭到拒絕。

就Claude Code而言：Opus 5的effort預設為high（與Claude API相同），並提供完整級別：low、medium、high、xhigh、max。Anthropic本身的移轉指南建議，若能力比Token支出更重要，應測試max effort。快速模式支援Opus 5，價格為每百萬Token $10/$50（請參閱快速模式）。¹⁹²¹⁹³

Claude Fable 5（2026年6月9日）：這是位於Opus之上的全新模型級別——Anthropic旗下最強大、最智慧的模型，在幾乎所有受測基準上都達到最先進水準，並能在數百萬Token的上下文中保持連貫一致。Fable 5是可供一般使用的「Mythos級」前沿模型：它配備安全分類器，遇到網路、生物化學及模型蒸餾查詢時會改用Opus 4.8（Claude Mythos 5是同一模型，但針對獲授權研究人員移除了這些安全防護）。自v2.1.170（2026年6月9日）起，Claude Code即可選用此模型——先執行claude update，再執行/model fable（簡短別名；/model claude-fable-5與best別名也會選取此模型）——並於2026年6月22日前逐步開放至各訂閱方案。模型ID：claude-fable-5。Fable 5預設即具備1M上下文視窗，因此無須使用[1m]後綴；自v2.1.173（2026年6月11日）起，claude-fable-5[1m]模型名稱會自動正規化並移除後綴（該後綴原本只對Opus/Sonnet有意義，因為這些模型必須透過[1m]才能啟用1M上下文）；最高輸出為128K。輸入價格為每百萬Token $10，輸出為每百萬Token $50——約為Opus 4.8的2倍——因此應留給真正艱難的推理任務，而非例行編輯。其要求介面與Opus 4.8相同（僅支援自適應思考；已移除temperature/top_p/top_k及budget_tokens），但有一項新差異：明確傳入thinking: {type: "disabled"}會傳回400，因此若要在不思考的情況下執行，請完全省略thinking參數。[^186]

就Claude Code而言：Fable 5與Opus 5一樣支援完整的effort級別（low/medium/high/xhigh/max，預設為high）。Fable 5無法關閉思考功能——工作階段的思考切換、alwaysThinkingEnabled設定及MAX_THINKING_TOKENS=0均不會生效；它一律採用自適應推理。完整的fable系列設定介面與Opus控制項相互對應：ANTHROPIC_DEFAULT_FABLE_MODEL可固定fable別名所解析的模型（適用於Bedrock/Vertex/Foundry），DISABLE_PROMPT_CACHING_FABLE可讓Fable不使用提示快取，而企業閘道則會套用依內容判斷的自動後援機制。/model opus現在會選取Opus 5（預設為high effort，最困難的任務可使用/effort xhigh）；自v2.1.197起，Sonnet 5已成為開箱即用的預設模型。若需要能力上限，請明確使用/model fable選取Fable 5。[^186]¹⁹²

Opus 4.7（2026年4月16日）：上一代旗艦模型，目前仍可完整使用。1M Token上下文視窗採用標準價格，沒有長上下文附加費。最高輸出為128K，僅支援自適應思考（已移除延伸思考），並新增xhigh effort級別，建議將其作為程式設計與代理式工作負載的起始設定。¹⁴⁵可靠知識截止日期：2026年1月。訓練資料截止日期：2026年1月。模型ID：claude-opus-4-7。價格與Opus 4.6相同，輸入/輸出為每百萬Token $5/$25；5分鐘快取寫入為$6.25、1小時快取寫入為$10，快取讀取則為每百萬Token $0.50。¹⁴⁴在SWE-Bench上，Opus 4.7解決的正式環境任務數量是Opus 4.6的3倍；CursorBench得分為70%（4.6為58%），在Anthropic內部的93項程式設計任務基準中，解決率提高13%。¹⁴⁴此模型使用新的Tokenizer——相同文字的Token數量預期約為原本的1倍至1.35倍；請提高max_tokens的預留空間及壓縮觸發門檻。¹⁴⁵視覺功能支援最高2,576 px／3.75 MP的影像，並採用1:1像素座標。¹⁴⁵

Opus 4.7程式設計基準（2026年4月）：¹⁵¹

各方案的預設模型（Claude Code）：¹⁴⁷

Opus 4.7中Messages API的破壞性變更（呼叫端可見）：¹⁴⁵ - 延伸思考的budget_tokens已移除。請改用thinking: {type: "adaptive"}。自適應思考預設為關閉；若請求中沒有thinking欄位，則不會進行思考。 - 將temperature、top_p或top_k設為非預設值時，會傳回HTTP 400。請省略這些參數，改以提示詞引導模型。 - 預設不會在回應中顯示思考內容。若要恢復顯示推理內容，請設定thinking.display: "summarized"（若您的產品會向使用者串流思考內容，則必須設定）。

任務預算（beta標頭task-budgets-2026-03-13）讓您能透過output_config.task_budget，告知模型整個代理式迴圈的目標token數；最低為20K tokens。¹⁴⁵

Opus 4.6（舊版）：仍可透過claude-opus-4-6使用，提供1M上下文與128K最大輸出。若要獲得更出色的代理式程式設計能力，建議遷移至Opus 4.7。Opus 4.6最初於2026年2月5日推出。⁷⁹¹⁴⁴ 自v2.1.117（2026年4月22日）起，Pro與Max訂閱者使用Opus 4.6及Sonnet 4.6時，預設採用higheffort（先前為medium）；Opus 4.7則維持xhigh。此項調整恢復了模型能力，扭轉4月23日事後分析中記錄的3月4日至4月7日effort降級。¹⁵²¹⁵³

Sonnet 5（2026年6月30日）：目前的Sonnet級別，定位為「速度與智慧的最佳組合」。Anthropic指出，其效能接近Opus 4.8，但價格更低；相較於Sonnet 4.6，在代理式推理、工具使用、程式設計及知識工作方面均有顯著進步。同時，整體不良行為的發生率更低，而網路安全能力則遠弱於Opus模型（正因這項安全取捨，才得以在不受出口管制限制的情況下推出）。模型ID：claude-sonnet-5（無日期的固定快照）。1M token上下文視窗、128K最大輸出（使用output-300k-2026-03-24beta標頭時，Batches API最高可達300K），僅支援自適應思考。可靠知識截止日期：2026年1月。定價：每MTok輸入／輸出$3/$15；2026年8月31日前的上市優惠價為$2/$10，約比Opus 4.8的$5/$25低40%。在Claude Code中，Sonnet 5的effort參數預設為high（若要變更，請明確設定）。可使用/model sonnet（或/model claude-sonnet-5）選取。¹⁷⁵ 自v2.1.197（2026年6月30日）起，Sonnet 5成為Claude Code新工作階段的預設模型，取代原先開箱即用的Opus 4.8；Opus仍可完整選用。¹⁷⁶

Sonnet 4.6（2026年2月17日，現已由Sonnet 5取代）：兼顧效能與成本的模型；在claude.ai與Claude Cowork中取代Sonnet 4.5成為預設模型。⁹³ 定價與Sonnet 4.5相同（每MTok $3/$15）。在減少token用量的同時，提升代理式搜尋效能。支援延伸思考、自適應思考，以及1M token上下文視窗（beta）。最大輸出為64K（v2.1.77的上限為128K）。¹¹⁹ 知識截止日期：2025年8月（可靠）、2026年1月（訓練資料）。模型ID：claude-sonnet-4-6。

Claude Mythos Preview（2026年4月7日）：透過Project Glasswing提供的防禦性網路安全研究預覽前沿模型。¹³⁹ 僅限受邀者使用，尚未全面開放。Anthropic明確將Opus 4.7設計為在網路安全方面弱於Mythos，這是一項安全取捨；同時也在https://claude.com/form/cyber-use-case開設Cyber Verification Program，供需要提高存取權限的正當安全研究人員申請。¹⁴⁶

這些價差為何重要：一般程式設計工作階段會消耗50K–200K輸入tokens與10K–50K輸出tokens。使用Haiku時，每個工作階段的成本為$0.10–$0.45；使用Opus時，同一工作階段則需$0.50–$2.25，貴上5倍。請將Opus保留給真正棘手的問題。¹

各模型的適用時機

Haiku：適合用於執行探索、簡單檔案搜尋及快速問答的subagents。價格約為Opus的五分之一，回應速度也更快。非常適合不需要深入推理的背景任務。

Sonnet：成本為重要考量時，日常開發的主力模型。足以處理多數程式設計工作，包括實作功能、修正錯誤、撰寫測試及程式碼審查。相較於Sonnet 4.5，Sonnet 4.6具備更出色的代理式搜尋能力與token效率，並以標準價格提供自適應思考及1M上下文視窗。⁹³ 自Opus 4.7推出（2026年4月16日）起，Claude Code僅在Max與Team Premium方案中預設使用Opus；Pro、Team Standard、Enterprise及API帳戶仍以Sonnet 4.6為預設，直到Enterprise與API於2026年4月23日改用Opus 4.7。¹⁴⁷ 當您需要更低廉的token、更短的延遲或更符合subagent成本效益的選擇時，請使用Sonnet。

Opus：截至2026年4月16日的旗艦級別，也是Max與Team Premium方案的預設模型。¹⁴⁴¹⁴⁷ 請將成本較高的推理能力用在物有所值的情境：架構決策、棘手的除錯、理解複雜系統、安全分析，以及長期執行的代理式工作。Opus 4.7在SWE-Bench上解決的正式環境任務數是Opus 4.6的3倍；CursorBench得分達70%（相較之下為58%），並在一項包含93個任務的內部程式設計基準中，將解決率提高13%。¹⁴⁴ Claude Code在Opus 4.7上預設採用xhigheffort，可透過/effort調整（v2.1.111以上版本）。¹⁴⁶¹⁴⁷ Max訂閱者可透過Anthropic API在Opus 4.7上使用Auto Mode，無須指定--enable-auto-mode；其他方案／供應商的可用性則依方案及管理員設定而定。¹⁴⁶ 以標準價格提供1M上下文，不收取長上下文附加費。值得留意的行為變更：Opus 4.7會更嚴格地按字面遵循指示、依任務複雜度調整回應長度、預設執行較少的subagents，且語氣更直接，較少使用偏向肯定使用者的措辭。若您的提示詞包含用於強制提供中途進度訊息或反覆檢查的鷹架，不妨嘗試移除。¹⁴⁵

Opusplan：混合模式，以Opus進行規劃（最需要推理品質的階段），再由Sonnet執行（最重視速度的階段）。非常適合複雜的重構工作：既能取得最佳計畫，又不必讓每項個別編輯都使用Opus等級的推理能力。

切換模型

工作階段進行期間：

> /model opus
> /model sonnet
> /model haiku

啟動時：

claude --model opus

透過環境變數：

export ANTHROPIC_MODEL=opus

在settings.json中：

{
  "model": "claude-sonnet-4-5-20250929"
}

專門用於subagents：

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

備援模型鏈（v2.1.166以上版本）：fallbackModel設定可配置最多3個備援模型；主要模型過載或無法使用時，會依序嘗試這些模型。--fallback-model旗標（先前只能在工作階段中途切換）現在也會從啟動時套用至互動式工作階段。[^184]

{
  "model": "claude-opus-4-8",
  "fallbackModel": ["claude-sonnet-4-6", "claude-haiku-4-5"]
}

當API傳回非預期且無法重試的錯誤時，Claude Code現在也會先使用備援模型重試該回合1次，再呈現失敗結果。如此一來，主要模型的暫時性問題只會使服務平順降級，而不會直接中斷該回合。[^184]

自v2.1.178起，壓縮也會遵循備援鏈。若主要模型在壓縮途中過載或無法使用，壓縮步驟會改用已設定的fallbackModel／--fallback-model鏈，而不會讓該回合失敗。對長時間自主執行而言，這補上了原先的缺口：可恢復的壓縮作業不再因暫時性模型錯誤而中斷整個工作階段。[^189]

延伸上下文

若要處理大型程式碼庫或長時間工作階段，請啟用1M token上下文：

claude --model sonnet[1m]
claude --model opus[1m]           # Opus 4.7 with 1M context

或在工作階段中執行：

> /model sonnet[1m]
> /model opus[1m]

Opus 4.7、Opus 4.6及Sonnet 4.6皆以標準價格提供完整的1M token上下文視窗，不收取長上下文附加費。¹⁴⁸ 900K-token請求與9K-token請求採用相同的每token費率。提示快取及批次處理折扣在完整上下文視窗中皆按標準費率適用。

Max、Team及Enterprise訂閱會自動納入具備1M上下文的Opus，無須使用[1m]後綴（自v2.1.75，2026年3月13日起預設啟用）。¹¹⁷¹⁴⁷ Pro可透過額外用量使用1M上下文。API及隨用隨付使用者則可按標準每token費率完整使用1M上下文。¹⁴⁷

若要在模型選擇器中停用1M上下文變體，請設定CLAUDE_CODE_DISABLE_1M_CONTEXT=1。

查看目前模型

> /status

此命令會顯示目前的模型、帳戶資訊、已套用的設定，以及其他工作階段狀態。 模型選擇器標籤（v2.1.51+）： /model 選擇器現在會針對固定版本顯示易於理解的標籤（例如「Sonnet 4.6」），不再顯示原始模型 ID；若有較新版本可用，也會提供升級提示。⁹⁸ v2.1.219 修正了合併後的 Opus 列，現在會顯示為單純的「Opus」，而非 「Opus（1M context）」；新版亮顯範圍也縮小至最新模型的名稱，讓亮顯真正標示本次推出的項目，而不是清單中任意一段內容。¹⁹¹

Fast Mode（v2.1.36+）

Fast mode 可讓同一個模型大幅加快輸出；它不會切換至較便宜的模型。在工作階段中使用 /fast 即可切換。⁸⁶

> /fast            # Toggle fast mode on/off

適用模型（截至 v2.1.219）： fast mode 適用於 Claude Opus 5 和 Claude Opus 4.8。v2.1.219 已從 fast mode 移除 Opus 4.7，而此功能從未支援 Sonnet、Haiku 或 Fable。它仍僅是 Claude API（包括 Claude Managed Agents）上的研究預覽功能，不適用於 Amazon Bedrock、Google Cloud、Microsoft Foundry 或 AWS 上的 Claude Platform。此功能設有存取限制：請聯絡您的客戶經理或加入候補名單。¹⁹¹¹⁹³

定價（Opus 5／Opus 4.8 fast mode）：¹⁹³

Opus 4.7 的陷阱（v2.1.219）。 不受支援的模型並非都會採取相同行為。現在向 claude-opus-4-7 傳送含有 speed: "fast" 的請求時，會傳回錯誤，而不會悄悄退回標準速度。Opus 4.6 是值得特別留意的例外：它會接受 speed: "fast"，但仍以標準速度執行、按標準費率計費，並回報 usage.speed: "standard"。若您的工具框架固定使用 4.7，並仰賴 fast-mode 請求自動降級而不中斷，現在這類請求將直接失敗；請將固定版本遷移至 Opus 5 或 4.8。¹⁹³

適合使用 fast mode 的情況： - 快速反覆調整小幅變更，且延遲是主要瓶頸 - 產生測試、樣板或重複性程式碼，且速度比成本更重要 - 依序處理一系列相似工作

不適合使用 fast mode 的情況： - 長時間執行的代理型工作（整個執行過程的成本仍會加倍） - 背景 subagent 工作（沒有人在等待輸出） - 注重預算的工作階段

Fast mode 包含完整的 1M context window（v2.1.50+）。整個 context 一律採用固定倍數計價，包括輸入 token 超過 200K 的請求，不另收長 context 附加費；此倍數還會疊加在提示快取與資料駐留的計價倍數之上。⁹⁶¹⁹³

操作注意事項。 Fast mode 有獨立於標準 Opus 限制的速率限制；超出限制時會傳回含有 retry-after 的 429（anthropic-fast-*-tokens-* 回應標頭會回報剩餘容量）。在 fast 與標準模式間切換會使提示快取失效。不同速度的請求不會共用已快取的前綴，因此在工作階段中途切換 /fast 會造成快取未命中。Fast mode 無法搭配 Batch API 或 Priority Tier 承諾使用。¹⁹³

專家提示： Fast mode 無法與 opusplan 搭配使用（opusplan 已混合使用 Opus 與 Sonnet；fast mode 只會影響 Opus 部分）。當延遲比成本更重要時再啟用，執行自主或批次工作時則應停用。/fast 需要額外用量；Team／Enterprise 管理員可能必須先啟用此功能（v2.1.37 修正）。若要完全停用，請設定 CLAUDE_CODE_DISABLE_FAST_MODE=1。自 v2.1.218 起，當透過 /config model=<x> 或 Remote Control 切換模型並改變 fast-mode 狀態時，Claude Code 會發出通知；v2.1.219 也修正了 Remote Control 用戶端在切換、重新連線或組織檢查失敗後仍保留過期 fast-mode 狀態的問題。^86149190191

Effort Control（v2.1.111+，Opus 4.7）

Opus 4.7 新增了 effort 調節功能，可調整速度與智慧程度之間的取捨。在工作階段中使用 /effort：

> /effort              # opens an interactive slider (arrow keys + Enter)
> /effort xhigh        # set directly

Max 上的 Auto Mode（v2.1.111+）

Auto Mode 是 --dangerously-skip-permissions 更安全的替代方案。Max 訂閱者可透過 Anthropic API 在 Opus 4.7 上使用，無須加上 --enable-auto-mode。¹⁴⁶ Sonnet-4.6 分類器會在執行前審查每項動作，確認是否符合意圖並檢查安全性。注意（v2.1.111+）： --enable-auto-mode 旗標已移除；請改用 --permission-mode auto 以 Auto Mode 啟動工作階段。Auto Mode 不適用於 Pro；根據 Anthropic 的權限模式文件，此功能預設可直接透過 Anthropic API 使用。Bedrock／Vertex／Foundry（v2.1.158+）： 在這些閘道上，Opus 4.7 與 Opus 4.8 的 Auto Mode 改為選用功能，需設定 CLAUDE_CODE_ENABLE_AUTO_MODE=1。¹⁹⁴ 自 v2.1.207 起，已不再需要選用設定： Auto Mode 可直接在 AWS Bedrock、Google Vertex AI 與 Microsoft Foundry 上使用，無須設定 CLAUDE_CODE_ENABLE_AUTO_MODE；若管理員希望停用，可使用 disableAutoMode 受管理設定。同一版本也讓 Bedrock、Vertex AI 與 AWS 上的 Claude Platform 預設採用 Claude Opus 4.8，並停止從儲存庫的 .claude/settings.local.json 讀取 autoMode 設定；請改在 ~/.claude/settings.json 中設定 auto-mode 規則。¹⁸⁰

自訂規則且保留預設值（v2.1.118+）。 舊版的 autoMode.allow、autoMode.soft_deny 與 autoMode.environment 必須二擇一：一旦定義自己的清單，就會失去內建安全規則。$defaults 哨兵值解決了這個問題——它會在您放置的位置就地展開為內建清單，讓您能在預設規則前後疊加自訂規則：¹⁵²

// .claude/settings.json
{
  "autoMode": {
    "allow": [
      "Bash(npm test:*)",        // your additions, prepended
      "$defaults",                // built-in allow list inserted here
      "Bash(git push:origin/feature/*)"  // appended after
    ]
  }
}

「不再詢問」選用選項（v2.1.118+）。 Auto Mode 選用提示現在提供「不再詢問」選項，經常使用此功能的人無須編寫旗標指令碼，即可隱藏說明內容。¹⁵²

破壞性命令防護機制（v2.1.183）。 除非您在工作階段中明確提出要求，否則 Auto Mode 現在會強制封鎖一組無法復原的命令：若您未要求捨棄本機工作，便會封鎖破壞性的 git 操作（git reset --hard、git checkout -- .、git clean -fd、git stash drop）；若該次 commit 並非代理程式在此工作階段中建立，則封鎖 git commit --amend；若您未指定具體 stack，則封鎖基礎架構拆除命令（terraform destroy、pulumi destroy、cdk destroy）。這項機制精準限縮了分類器對可能悄然造成工作遺失或拆除環境之操作的影響範圍。代理程式仍可執行這些命令，但只能依照您的明確指示，不能自行決定。¹⁶⁹

分類每個 shell 命令（v2.1.193）。 根據預設，auto-mode 分類器只會審查符合任意程式碼執行模式的 shell 命令；例行命令則會略過。新的 autoMode.classifyAllShell 設定可讓所有 Bash／PowerShell 命令都經過分類器審查。這會稍微增加延遲，但若您希望每次 shell 呼叫都受到檢查，便能提供更嚴密的安全防護。同一版本也會在逐字稿、拒絕提示通知及 /permissions 的近期拒絕記錄中顯示 auto-mode 拒絕原因，因此命令遭到封鎖時，現在會說明具體原因。¹⁷⁴ 另外3項強化規則（v2.1.205）。 Auto mode 現在會阻止竄改工作階段逐字記錄檔案——稽核軌跡本身不允許代理程式碰觸；若要對無法從上下文解析的變數執行 rm -rf，則會先行詢問——防止因 rm -rf $DIR 中的 $DIR 未知而引發意外；此外，背景工作通知現在會明確指出未發生任何人為輸入，因此，逐字記錄中偽造的「使用者已核准」文字，無法再被粉飾成可據以採取行動的核准。¹⁷⁸ 第3項是值得銘記在心的提示詞注入防禦措施：核准必須透過核准通道送達，而執行框架現在已明確採用這項前提。

命令替換無法再掩藏災難性操作（v2.1.208）。 rm -rf ~ 等災難性移除操作，即使藏在 $(...)、反引號或程序替換（<(...)）中，現在仍會顯示提示——而且即便處於 --dangerously-skip-permissions 和 auto mode，提示照樣會觸發。將破壞性命令包進替換語法，已無法再使其蒙混過關、避開安全防護網。¹⁸¹

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

claude auto-mode reset          # Confirmation prompt
claude auto-mode reset --yes    # Skip confirmation (scripts)

減少對話方塊，審查依舊嚴謹（v2.1.218）。 過去有3項檢查會以權限對話方塊中斷 auto mode，分別是危險的 rm、背景執行的 &，以及可疑的 Windows 路徑；現在已不再如此。這些情況改由 auto-mode 分類器裁決，因此安全審查仍會執行，卻不會每次命中都要求您介入。同一版本也將此機制擴及搭配 auto 的 plan mode：若靜態分析器無法證明 Bash 命令僅供讀取，現在也不會顯示提示，而是由分類器判斷，不再退回對話方塊。¹⁹⁰

v2.1.105–v2.1.114 的新命令¹⁴⁶¹⁵⁰

推播通知（v2.1.110+）

若 Remote Control 已啟用「由 Claude 決定是否推播」，Claude 現在可自行判斷，透過新的推播通知工具傳送行動裝置推播通知。此功能可與既有的 Remote Control 行動裝置／網頁介面搭配使用。¹⁴⁶ /context、/exit 和 /reload-plugins 現在也能從 Remote Control 用戶端使用。

Windows PowerShell 工具（v2.1.111+，逐步推出）

Claude Code 正在逐步推出原生 Windows PowerShell 工具。在 Linux／macOS 上，請以 CLAUDE_CODE_USE_POWERSHELL_TOOL=1 啟用（PATH 中必須有 pwsh）。在 Windows 上，逐步推出期間同樣使用此變數控制選擇啟用或停用。¹⁴⁶

權限模式自動核准（v2.1.119+）。 PowerShell 工具命令現在可在權限模式下自動獲准，運作方式與 Bash 命令相同。PowerShell(Get-*:*) 等允許規則與既有的模式語法，現在可讓唯讀操作略過提示，提供與 Linux／macOS 團隊一致的操作便利性。¹⁵²

減少權限提示：唯讀 Bash（v2.1.111+）

帶有 glob 引數的唯讀 Bash 模式（例如 ls *.ts、cat src/*.md），以及以 cd <project-dir> && 開頭的命令，不再觸發權限提示。¹⁴⁶ 搭配 /less-permission-prompts 使用，日常工作流程中的中斷次數可望大幅減少。

分散式追蹤（v2.1.110+）

SDK 和無頭工作階段現在會從環境中讀取 TRACEPARENT 與 TRACESTATE，將 Claude Code 執行連結至分散式追蹤。搭配 OTEL_LOG_RAW_API_BODIES=1（v2.1.111+），即可將完整的 API 請求／回應主體輸出為 OpenTelemetry 記錄事件，以利偵錯。¹⁴⁶

原生二進位檔散布（v2.1.113+）¹⁵⁰

v2.1.113 變更了 CLI 的啟動方式：claude 現在會透過各平台專屬的選用相依套件，啟動原生 Claude Code 二進位檔，不再執行隨附的 JavaScript。安裝與更新命令維持不變，團隊無須修改部署指令碼。

提示詞編輯器快速鍵（v2.1.113+）¹⁵⁰

提示詞編輯器在多行輸入中新增 readline 風格的導覽操作，以及全螢幕檢視區捲動功能：

Subagent 停滯逾時（v2.1.113+）¹⁵⁰

Subagents 若在串流途中停滯，現在會在10分鐘後明確回報錯誤，不再無聲無息地持續等待。搭配 CLAUDE_STREAM_IDLE_TIMEOUT_MS（v2.1.84+），可更全面地涵蓋 API 串流程序卡住的情況。

v2.1.114 穩定性修正¹⁵⁰

v2.1.114（2026年4月18日）只包含一項修正：當 agent-teams 的隊友要求工具權限時，權限對話方塊可能會當機。若您使用 Agent Teams，請升級。

Claude Code 的費用是多少？

瞭解並控制成本，是長期使用 Claude Code 的關鍵。若要瞭解模型功能，另請參閱模型選擇；若要依任務選擇合適的模型，請參閱決策框架。

查看費用

> /cost

輸出：

Total cost:            $0.55
Total duration (API):  6m 19.7s
Total duration (wall): 6h 33m 10.2s
Total code changes:    247 lines added, 89 lines removed

訂閱使用者可在 /cost 中查看各模型與快取命中的明細，清楚掌握哪些模型消耗了 token，以及有多少內容由快取提供（v2.1.92+）。¹³⁷

訂閱方案

速率限制（2025年8月）：Anthropic 為付費訂閱者導入每週速率限制。Max 訂閱者超出速率限制後，可按標準 API 費率購買額外用量。¹⁴

速率限制加倍（2026年5月6日）：在 Code with Claude SF 活動期間，Anthropic 將 Pro、Max、Team 與按席次計費的 Enterprise 方案之 Claude Code 5 小時速率限制全面加倍，取消 Pro 和 Max 帳戶在尖峰時段的額度縮減，並「大幅」提高 Claude Opus 模型的 API 速率限制。其運算容量後盾來自 SpaceX Colossus 1 協議：「在一個月內新增超過 300 百萬瓦的容量（逾 220,000 個 NVIDIA GPU）」。¹⁵⁷

API Token 定價（2026年4月）¹¹⁴⁴

對採 API 計費的使用者，每百萬 token 的價格如下：

1M 上下文定價（2026年4月）：Opus 4.7、Opus 4.6、Sonnet 4.6 與 Mythos Preview 均以每百萬 token 的標準費率提供 1M 上下文，不收取長上下文附加費。¹⁴⁸ 這是近期整併後的結果；過去關於 Opus 4.6 或 Sonnet 4.6 在輸入 token 超過 200K 時，輸入費率為 2 倍、輸出費率為 1.5 倍的說明，現已不再適用。舊版 Opus 4.5 及更早的模型仍沿用原有定價結構。

資料落地區域定價：透過 inference_geo 指定僅在美國進行推論，所有 token 定價皆會乘以 1.1 倍，包括快取讀取與寫入（適用於 Opus 4.6 以上模型）。¹⁴⁸

提示詞快取可大幅降低重複輸入的成本：快取寫入費用為基礎費率的 1.25 倍（5 分鐘快取）或 2 倍（1 小時快取），但快取讀取僅為 0.1 倍，可節省 90%。對於會重複使用上下文的 RAG 系統與程式碼助理，快取可降低 88～95% 的成本。

Batch API 為非緊急任務提供 5 折優惠，並在 24 小時內完成，適合夜間測試套件等工作。

多帳戶政策⁵²

可以擁有多個 Claude 帳戶嗎？可以，只要用途正當。當多個帳戶各有不同用途時，Anthropic 明確允許使用者持有多個帳戶。

允許的情況：

技術限制： - 同一個電話號碼最多可驗證 3 個帳戶 - 明確支援從相同 IP／網路使用多個付費訂閱 - 各帳戶完全獨立，無法在帳戶之間轉移聊天記錄或專案

禁止的行為（依據使用政策）： - 遭停權後建立帳戶以規避停權 - 跨帳戶協同進行惡意活動以躲避偵測 - 使用多個帳戶規避速率限制或免費方案額度

實際案例：2026年1月，重度使用者 Jeffrey Emanuel（@doodlestein）的 22 個 Max 帳戶遭系統自動標記並暫時停權。Anthropic 員工 Thariq（@trq212）確認用途正當後，在 4 小時內解決此事。如果您為了工作與個人專案而透過多個帳戶大量使用 Claude Code，這正是此服務的設計用途；但請勿試圖鑽系統漏洞。

若有疑問：請聯絡 Anthropic 支援中心，以書面方式確認您的特定設定是否符合規範。

成本因素

實際成本範例

節省成本要點：探索工作交由 Haiku subagents、實作則使用 Sonnet，通常比所有工作一律使用 Sonnet 節省 40～50% 的成本。

團隊成本管理

依團隊規模建議的 TPM／RPM：

隱藏的工具費用

除了按 token 計價外，部分工具還會另外收費：⁹

這些費用在代理迴圈中會逐步累積。進行 100 次迭代的偵錯週期，僅 Bash 的額外負擔就會耗用約 24,500 個額外輸入 token。

節省成本策略

1. subagents 使用 Haiku：大多數探索工作不需要 Sonnet
2. 啟用提示詞快取：預設已啟用，但請確認未遭停用
3. 設定最大輪數：claude --max-turns 5 可避免對話失控
4. 設定費用上限：claude --max-budget-usd 5 會在支出達到上限時強制停止工作階段。自 v2.1.217 起，此上限也會管控背景 subagents；一旦達到上限，系統將拒絕建立新的 subagents，並停止執行中的背景代理（過去背景代理不受預算限制）¹⁸⁹
5. 使用規劃模式進行探索：不執行操作，就不會意外觸發昂貴作業
6. 主動壓縮：上下文越小，token 越少
7. 限制輸出：export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
8. 非緊急工作使用 Batch API：輸入與輸出 token 均享 5 折優惠

監控用量

• Claude Console：platform.claude.com（需要 Admin 或 Billing 角色）
• 工作區限制：為各工作區設定支出上限
• Bedrock／Vertex：使用雲端平台原生的成本監控功能
• LiteLLM：搭配第三方供應商，詳細追蹤各使用者的用量

背景 Token 用量

部分作業會在背景中消耗 token： - 為 /resume 摘要對話 - /cost 與 /status 指令 - 自動壓縮

每個工作階段通常低於 $0.04。

Claude Code 分析 API（Team／Enterprise）⁴⁶

透過 Admin API，以程式方式存取組織的 Claude Code 使用分析與生產力指標。

端點：GET /v1/organizations/usage_report/claude_code

需求： - Admin API 金鑰（sk-ant-admin...） - Team 或 Enterprise 方案 - Admin、Billing 或 Developer 角色

可用指標：

請求範例：

curl "https://api.anthropic.com/v1/organizations/usage_report/claude_code?starting_at=2026-01-15" \
  -H "x-api-key: sk-ant-admin..." \
  -H "anthropic-version: 2023-06-01"

使用情境： - 開發者生產力分析（工作階段、commit、PR） - 工具使用指標（Edit、Write 等工具的接受／拒絕率） - 跨團隊的成本追蹤與分攤 - AI 程式設計工具的 ROI 理由說明

注意：資料會在活動完成後 1 小時內出現。為確保一致性，回應中僅包含至少 1 小時前的資料。

決策框架

僅知道有哪些功能還不夠。您還需要掌握各功能的適用時機。以下決策樹能協助您將知識付諸實踐。

我該使用哪個模型？

START → Is the task simple? (file search, quick question, formatting)
         │
         ├── YES → Use Haiku
         │         Cost: ~$0.03/task
         │         Speed: Fastest
         │
         └── NO → Does it require deep reasoning?
                  (architecture, complex debugging, security analysis)
                  │
                  ├── YES → Use Opus 4.7 (xhigh effort default)
                  │         Cost: ~$2.00/task
                  │         Quality: Highest (1M context at standard price, adaptive reasoning)
                  │
                  └── NO → Use Sonnet
                           Cost: ~$0.75/task
                           Balance: Best overall when cost matters

經驗法則：Max與Team Premium預設使用Opus 4.7。Pro／Team Standard／Enterprise／API則預設使用Sonnet 4.6（Enterprise + Anthropic API將於2026年4月23日切換至Opus 4.7）。¹⁴⁷ subagents可改用Haiku。若Sonnet的回答流於表面，請升級至Opus。使用agent teams（v2.1.32+）時，Opus可以協調多個agent，讓它們針對不同子任務平行作業。⁷⁹

Command、Skill、Subagent或Agent Team？

Do you want explicit control over when it runs?
│
├── YES → Use Slash Command
│         Example: /deploy, /test, /security-review
│         You invoke it. You control timing.
│
└── NO → Should the expertise apply automatically based on context?
         │
         ├── YES → Use Skill
         │         Example: Security patterns, domain rules, code standards
         │         Claude recognizes context and applies expertise.
         │
         └── NO → Does the work need isolated context?
                  │
                  ├── YES → Is there one subtask or many parallel subtasks?
                  │         │
                  │         ├── ONE → Use Subagent (Task tool)
                  │         │         Example: Deep exploration, parallel analysis
                  │         │         Prevents context bloat in main conversation.
                  │         │
                  │         └── MANY → Use Agent Team (v2.1.32+)
                  │                   Example: 5 agents reviewing different modules simultaneously
                  │                   Opus coordinates; each agent works independently.
                  │
                  └── NO → Just prompt directly
                           Not everything needs abstraction.

Hook或Prompt？

Must the action ALWAYS happen, regardless of Claude's judgment?
│
├── YES → Use Hook (deterministic)
│         Examples:
│         - Format code after every edit
│         - Log all bash commands
│         - Block access to .env files
│         Claude cannot skip, forget, or decide otherwise.
│
└── NO → Use Prompt (probabilistic)
         Examples:
         - "Consider adding tests"
         - "Think about edge cases"
         - "Review for security if relevant"
         Claude decides based on context.

何時該使用延伸思考？

Is this a genuinely hard problem?
│
├── Architectural decision with many tradeoffs → YES, use thinking
├── Complex debugging with unclear root cause → YES, use thinking
├── Security analysis requiring careful reasoning → YES, use thinking
├── Understanding unfamiliar codebase → YES, use thinking
│
├── Routine bug fix → NO, skip thinking
├── Simple refactoring → NO, skip thinking
├── Code formatting → NO, skip thinking
└── Quick questions → NO, skip thinking

在工作階段中按下Alt+T即可切換。較高的思考預算會增加成本；建議先從最低設定開始，只有在回應顯得倉促時才逐步提高。

Opus 4.6自適應思考：Opus 4.6會依問題複雜度自動調整思考深度。對大多數任務而言，無須明確控制思考預算——Opus會在處理難題時加深思考，面對簡單問題時則保持迅速。若使用Sonnet並希望強制進行更深入的分析，手動切換思考模式最為實用。

該選擇哪種執行介面？

Where should this work happen?
│
├── Requires YOUR local files and tools
│   │
│   ├── Interactive, iterative work → Main REPL session
│   ├── One-shot scripted task → claude -p "prompt" (print mode)
│   ├── CI/CD automation → claude -p --json (non-interactive + structured output)
│   └── Parallel isolated tasks → Subagents via Task tool
│
├── Requires SOMEONE ELSE'S environment
│   │
│   └── Remote codebase or server → Background agent (cloud)
│
└── Doesn't require any environment
    │
    ├── Research or analysis → Subagent with Explore type
    └── Web content extraction → WebFetch / WebSearch tools

Agent Teams、Subagents與平行工作階段

Do you need multiple agents working on related subtasks?
│
├── YES → Are the subtasks independent (no shared state)?
│         │
│         ├── YES → Can they share the same codebase?
│         │         │
│         │         ├── YES → Use Agent Team (v2.1.32+)
│         │         │         Opus coordinates. Agents share repo access.
│         │         │         Example: "Review auth, API, and DB modules in parallel"
│         │         │
│         │         └── NO → Use Parallel Sessions (separate terminals)
│         │                  Each has its own working directory.
│         │                  Example: "Fix repo-A and repo-B simultaneously"
│         │
│         └── NO → Use Sequential Subagents
│                  Results from one feed into the next.
│                  Example: "Explore → Plan → Implement"
│
└── NO → Use Single Subagent or Main REPL

該使用哪種Hook類型？

What kind of automation do you need?
│
├── Run a shell command at a specific event?
│   │
│   └── Use Command Hook
│       Trigger: PreToolUse, PostToolUse, Notification, Stop, SubagentStop
│       Example: "Run prettier after every file edit"
│       Config: hooks.PostToolUse[].command = "prettier --write $FILE"
│
├── Modify Claude's system prompt based on context?
│   │
│   └── Use Prompt Hook (v2.1.35+)
│       Trigger: Same events
│       Example: "Inject project rules when working in /src/auth/"
│       Config: hooks.PreToolUse[].prompt = "When editing auth files..."
│
└── Have Claude make a judgment call before proceeding?
    │
    └── Use Agent Hook (v2.1.35+)
        Trigger: Same events
        Example: "Evaluate if this bash command is safe before running"
        Config: hooks.PreToolUse[].agent = { prompt: "Is this safe?" }

何時該使用/fast？

Is response speed more important than depth right now?
│
├── YES → Use /fast   (Opus 5 or Opus 4.8 only, v2.1.219+)
│         Same model, ~2.5× output speed at 2× price
│         Good for: quick questions, simple edits, code explanations,
│                   file searches, formatting tasks
│
└── NO → Stay in normal mode
         Good for: architecture decisions, complex debugging,
                   security reviews, multi-file refactors,
                   anything requiring deep reasoning

/fast可切換目前工作階段的快速模式。此模式仍使用相同模型——截至v2.1.219，快速模式僅支援Opus 5或Opus 4.8——但會最佳化輸出速度。它不會切換至較便宜的模型；以每百萬token輸入／輸出$10／$50的價格計算，成本也不會更低。¹⁹¹¹⁹³

權限系統如何運作？

Claude Code的權限系統可細緻控管允許執行的操作。若要兼顧安全性與工作流程效率，充分理解此系統至關重要。另請參閱企業部署，了解如何透過受管理設定，在整個組織中強制執行權限政策。

權限層級

唯讀工具（自動核准）： - Read－讀取檔案內容 - Glob－依模式尋找檔案 - Grep－搜尋檔案內容 - WebSearch－搜尋網頁 - LSP－程式碼智慧功能（前往定義、尋找參照、游標暫留文件）¹⁸

LSP工具功能（v2.0.74+）：LSP工具提供類似IDE的程式碼智慧功能： - 前往定義：跳至符號的定義位置 - 尋找參照：列出整個程式碼庫中使用該符號的所有位置 - 游標暫留文件：取得任何符號的型別資訊與文件 - 適用於TypeScript、Python、Go、Rust及其他支援LSP的語言 - 必須有可用的語言伺服器（通常會隨工具鏈一併安裝）

修改工具（需要核准）： - Edit－修改現有檔案 - Write－建立新檔案 - Bash－執行shell命令 - WebFetch－擷取URL內容 - NotebookEdit－修改Jupyter筆記本

修改工具第一次執行時，Claude Code會要求核准。除非另有明確設定，否則核准結果會在整個工作階段持續有效。

EndConversation工具（v2.1.214）。Claude Code現在具備與Claude自2025年起在claude.ai上相同的結束對話能力：在極少數輸入極度濫用，或持續嘗試越獄的情況下，Claude可透過內建的EndConversation工具直接結束工作階段。這是用於抵禦濫用並維護模型福祉的措施，不是工作流程功能；一般開發工作階段不會觸發此功能。¹⁸⁵¹⁸⁸

權限模式

自v2.1.200起，default模式標示為「Manual」。此次重新命名涵蓋CLI、--help、VS Code及JetBrains；設定值並未變更，因此"defaultMode": "default"仍然有效，而--permission-mode manual／"defaultMode": "manual"現在也可作為別名使用。行為完全相同，也就是每項工具首次使用時提示；只是標籤不再讓人誤以為這是「恰好預設採用的模式」，而能準確表達其手動核准模式的本質。同一版本中，AskUserQuestion對話方塊預設不再自動繼續；subagent提出問題後，現在會等待您的回答，不會在逾時後逕自繼續。若要恢復閒置逾時行為，可透過/config選擇啟用。

即使採用acceptEdits，程式碼執行設定檔現在也會要求核准（v2.1.160）。acceptEdits會自動核准一般編輯，但自v2.1.160起，在寫入可能讓命令悄然執行的檔案前會先停止並提示，包括shell啟動檔（.zshenv、.zlogin、.bash_login）、~/.config/git/，以及建置工具設定（.npmrc、.yarnrc*、bunfig.toml、.bazelrc、.pre-commit-config.yaml、.devcontainer/等）。原因在於，編輯這些檔案可能使下一次啟動shell、安裝或提交成為執行途徑；因此，即使是在原本會直接放行編輯的受信任專案模式中，仍須經過明確把關。這與既有針對.claude/、.git/及.vscode/的寫入保護採用相同威脅模型，只是進一步涵蓋更廣泛的「編輯即可能導致執行」檔案。[^182]

Auto Mode（v2.1.85+）：這是比--dangerously-skip-permissions更安全的替代方案。獨立的分類器模型（Sonnet 4.6）會在執行前檢查每項操作，確認其符合使用者意圖且安全無虞。¹²⁴

運作方式： - 工作目錄中的唯讀操作與檔案編輯會自動核准 - 自訂允許／拒絕規則會優先套用 - 其餘操作全數交由分類器評估 - 若遭封鎖，Claude會自動嘗試其他做法

預設自動封鎖：curl | bash、強制推送至main、正式環境部署／遷移、大規模刪除雲端資源、變更IAM／權限，以及向外部傳送敏感資料。¹²⁵

斷路機制：連續封鎖3次，或單一工作階段累計封鎖20次後，會暫停並恢復手動提示。¹²⁵

# Enable at startup
claude --enable-auto-mode

# Or cycle into it during a session
Shift+Tab  # Cycles through: Manual (aka default) → acceptEdits → auto → plan

適用範圍：優先提供給Team方案使用者，之後擴及Enterprise與API。需要Sonnet 4.6或Opus 4.6。¹²⁴

YOLO模式（v2.0.68+）：若要在沒有任何安全分類器的情況下完全自主運作，請使用--dangerously-skip-permissions旗標。此旗標會對所有操作一律同意，包括檔案編輯、bash命令及所有工具呼叫。「dangerous」一詞是刻意採用的警示。對多數使用情境而言，建議改用Auto Mode。⁵⁴

claude --dangerously-skip-permissions

透過CLI設定模式：

claude --permission-mode auto  # or acceptEdits, plan, bypassPermissions

在工作階段中切換：

Shift+Tab  # Cycles through modes

在settings.json中設定：

{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

權限規則語法

細緻規則可控管特定操作。規則會依序評估，第一個相符項目即生效。

Bash命令模式：

{
  "allow": [
    "Bash(npm run build)",
    "Bash(npm run test:*)",
    "Bash(git commit:*)",
    "Bash(make:*)"
  ],
  "deny": [
    "Bash(rm -rf:*)",
    "Bash(sudo:*)",
    "Bash(curl|wget:*)"
  ]
}

星號提供前綴比對：Bash(npm run test:*)允許npm run test、npm run test:unit及npm run test:integration。

重要限制：Bash模式僅比對前綴，不支援regex。Bash(curl http:*)之類的模式不會符合curl -X GET http://...，因為選項出現在URL之前。若要可靠封鎖，請拒絕整個命令：Bash(curl:*)。

檔案操作模式：

{
  "allow": [
    "Edit(src/**)",
    "Read(docs/**)"
  ],
  "deny": [
    "Read(.env*)",
    "Read(secrets/**)",
    "Edit(.git/**)",
    "Edit(node_modules/**)"
  ]
}

路徑語法： - 相對路徑：Edit(src/**)－相對於工作目錄 - 從設定檔起算的絕對路徑：Edit(/build/**)－相對於設定檔所在位置 - 真正的絕對路徑：Edit(//tmp/**)－以//開頭 - 主目錄：Read(~/.zshrc)

單一區段的dir/**允許規則現在只會符合<cwd>/dir（v2.1.214）－請稽核現有規則。在v2.1.214之前，Edit(src/**)之類的允許規則會自動核准寫入目錄樹中任何名為src的資料夾，例如vendor/src/、packages/foo/src/等，無一例外。現在只會符合工作目錄正下方的src資料夾。若原本仰賴舊有的任意深度行為，請將規則改寫為Edit(**/src/**)。deny與ask規則仍保留任意深度比對；此變更只會縮小自動核准範圍，絕不會縮小封鎖範圍。若規則在升級後悄然不再符合，系統會顯示新的權限提示，而非回報錯誤。因此，請檢查所有採用單一區段形式撰寫的允許規則。hooks的if:條件也在此版本採用相同的cwd範圍限制（請參閱比對器）。¹⁸⁵

請使用Edit(path)／Read(path)，不要使用Write(path)／NotebookEdit(path)／Glob(path)（v2.1.210）。對於使用Write(path)、NotebookEdit(path)或Glob(path)撰寫的權限規則，Claude Code現在會在啟動時顯示警告。標準形式是實際控管檔案存取的兩類規則：Edit(path)涵蓋所有檔案寫入工具（包括Write與NotebookEdit），而Read(path)涵蓋所有檔案讀取工具（包括Glob）。請遷移所有舊版規則，消除警告並明確表達規則意圖。¹⁸²

「Always allow」會儲存至儲存庫根目錄（v2.1.211）。透過「Always allow」提示選項建立的權限規則，現在會寫入儲存庫根目錄，而非目前的worktree。因此，在某個worktree中授予的核准會跨工作階段持續生效，也會套用至該儲存庫的每個worktree，無須再於各個平行簽出中重複核准相同命令。¹⁸³

MCP工具模式：

{
  "allow": [
    "mcp__github",
    "mcp__database__query",
    "mcp__myserver__*"
  ],
  "deny": [
    "mcp__dangerous_server",
    "mcp__untrusted__*"
  ]
}

使用萬用字元語法mcp__server__*，即可允許或拒絕特定MCP伺服器的所有工具。³²萬用字元語法適合用來快速啟用受信任伺服器的所有工具，或封鎖來自不受信任來源的整部伺服器。

自v2.1.166起，拒絕規則也接受工具名稱位置中的glob：在工具名稱欄位單獨使用"*"會拒絕所有工具，因此可先封鎖一切，再回頭允許少數特定工具。相較之下，允許規則會拒絕非MCP的glob，也就是不能用相同方式廣泛允許所有工具，藉此維持嚴格的預設安全姿態。[^184]

參數層級比對－Tool(param:value)（v2.1.178）：

除了工具名稱，規則也可比對工具的輸入參數，並以*作為值的萬用字元：

{
  "deny": [
    "Agent(model:opus)"
  ]
}

Agent(model:opus)會封鎖任何以Opus層級產生的subagent；遭拒絕的是產生操作本身，不只是提示要求避免使用Opus。這使權限控管從「可使用哪項工具」進一步深入至「如何呼叫工具」，並以確定性規則取代提示層級的要求。此功能可搭配受管理的enforceAvailableModels設定：允許清單定義工作階段中可用的模型層級，而Tool(model:...)規則則限制subagents如何從中選用模型。[^189]

自v2.1.186起，這些Agent(...)規則也會套用於具名subagent產生操作：透過工作流程、--agents或agent團隊啟動特定具名agent時，Agent(agent_type)拒絕規則及Agent(x,y)允許類型限制現在都會生效，不再僅限於匿名的Task型產生操作。產生操作會在啟動時遭到封鎖，補上具名agent可能規避既有限制規則的缺口。¹⁷⁰

WebFetch模式：

{
  "allow": [
    "WebFetch(domain:github.com)",
    "WebFetch(domain:api.example.com)"
  ]
}

其他目錄

將Claude的存取範圍擴展至目前專案以外：

{
  "permissions": {
    "additionalDirectories": [
      "../shared-lib",
      "../docs",
      "~/reference-projects/design-system"
    ]
  }
}

對於monorepo，或Claude需要參照同層其他目錄中的程式碼時，加入其他目錄至關重要。

Sandbox模式

啟用檔案系統與網路隔離：

> /sandbox

或在設定中配置：

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"],
    "network": {
      "allowUnixSockets": ["~/.ssh/agent-socket"],
      "allowLocalBinding": true,
      "deniedDomains": ["pastebin.com", "transfer.sh", "0x0.st"]
    }
  }
}

自v2.1.187起，sandbox.credentials設定可阻止sandbox中的命令讀取認證檔案與機密環境變數，提供縱深防禦，避免sandbox命令將機密資料外洩。¹⁷¹

自v2.1.216起，sandbox.filesystem.disabled設定可略過檔案系統隔離，同時保留網路出口控管；當檔案系統隔離環境導致建置工具無法運作，但仍希望對外連線強制套用網域允許清單時，此設定相當實用。¹⁸⁷

自v2.1.219起，sandbox.network.strictAllowlist設定會直接拒絕未列入允許清單的主機，且不顯示提示。依預設，sandbox中的命令若連線至allowedDomains以外的主機，會觸發權限提示；啟用strictAllowlist後，連線會直接遭到拒絕。此設定適合用於無人值守的執行環境，例如CI、背景agents及隔夜迴圈。在這些情境中，無人回應的提示只會造成停滯，而「遇到非預期的對外連線時詢問我」本來就不是適當政策。這也補齊網路控管的三大要素：allowedDomains定義允許項目，deniedDomains（如下所述）可在廣泛允許範圍中排除例外，而strictAllowlist則決定其餘項目要提示還是直接失敗。¹⁹¹

在sandbox中： - 檔案系統存取僅限於專案目錄 - 網路存取受到控管 - 特定命令不受sandbox限制 - 若autoAllowBashIfSandboxed為true，Bash命令會自動獲准

專家提示：在不受信任的程式碼庫上執行Claude時，Sandbox模式極為實用。探索陌生專案或希望多加一層防護時，建議啟用。Anthropic的內部測試發現，sandbox可減少84%的權限提示。³⁸sandbox使用作業系統層級的原生機制（macOS seatbelt、Linux bubblewrap）隔離檔案系統與網路，因此即使提示注入成功，也會受到完整限制。Anthropic已將sandbox執行環境開放原始碼，供建置自有agents的團隊使用。⁸²

安全性注意事項（v2.1.34+）：先前，透過sandbox.excludedCommands或dangerouslyDisableSandbox排除於sandbox之外的命令，可能會在啟用autoAllowBashIfSandboxed時繞過Bash的詢問權限規則；此問題已於v2.1.34修正。⁸⁷自v2.1.38起，Sandbox模式會封鎖對.claude/skills的寫入，防止提示注入修改skill定義。⁸⁸v2.1.77新增allowRead sandbox檔案系統設定，可在denyRead區域中重新允許讀取；若要封鎖目錄樹的大部分區域，但將特定子目錄列入允許清單，此功能便相當實用。¹¹⁹

.claude/ agent設定豁免（v2.1.121+）：--dangerously-skip-permissions寫入.claude/skills/、.claude/agents/及.claude/commands/時，不再顯示提示。¹⁵⁴

巢狀.claude/解析（v2.1.178）：在某個目錄下處理檔案時，該目錄內巢狀.claude/skills中的skills現在會自動載入，不再僅限於儲存庫根目錄；若名稱衝突，可使用<dir>:<name>存取巢狀skill，讓兩者都能使用。專案介面的其他部分也以相同方式解析：不同巢狀.claude/目錄中的agent、工作流程或輸出樣式名稱若發生衝突，會採用最接近工作目錄的項目；儲存專案範圍的工作流程時，則會以最接近的現有.claude/workflows/為目標。對monorepo或由多個儲存庫組成的儲存庫而言，這能讓各套件專屬工具依情境啟用，不必共用單一扁平的全域介面。[^189]

自訂bubblewrap與socat路徑（v2.1.133+）：受管理設定sandbox.bwrapPath與sandbox.socatPath可讓管理員將Linux／WSL部署指向非標準的bubblewrap及socat二進位檔位置。若發行版將這些工具安裝在$PATH以外，或組織自行提供經過強化的建置版本，此功能便相當實用。¹⁶⁰

v2.1.113的安全性強化：¹⁵⁰

• sandbox.network.deniedDomains會封鎖特定主機，即使較廣泛的allowedDomains萬用字元原本會允許這些主機。利用封鎖清單即可阻擋文字貼上網站、檔案投遞服務或已知惡意主機，無須重寫整套允許政策。若希望允許清單以外的一切項目都直接遭到拒絕，而非顯示提示，請搭配sandbox.network.strictAllowlist（v2.1.219，見上文）使用。
• 包裝命令拒絕規則。Bash拒絕規則現在能比對包裝在env、sudo、watch、ionice、setsid及類似exec包裝工具中的命令。Bash(rm:*)之類的規則現在能攔截env rm -rf、sudo rm -rf及其他同類規避模式。
• Bash(find:*)允許規則不再自動核准find -exec或find -delete。這些旗標會執行命令及刪除檔案，因此Claude Code會將其導向一般權限流程。
• macOS刪除防護。Bash(rm:*)允許規則現在會將/private/etc、/private/var、/private/tmp及/private/home視為危險的刪除目標。/var、/etc及/tmp是指向/private/的符號連結，因此先前的規則形式未涵蓋這些標準目標。

v2.1.214的權限預設拒絕強化：¹⁸⁵

同一版本一併修補多項權限檢查缺口，並全面採取預設拒絕原則；只要分析器無法確定安全性，就會顯示提示：

• 修正Windows PowerShell 5.1規避問題。先前，在PowerShell 5.1工作階段中執行的命令可能繞過權限檢查。
• Bash檔案描述符重新導向採取預設拒絕。若bash解析重新導向形式的方式與權限分析器不同，現在會顯示提示，不再直接執行。
• 超過10,000個字元的命令一律提示。先前系統可能誤判極長命令；現在絕不會自動執行。
• [[ ]]中的zsh下標與修飾符會觸發提示。[[ ]]比較式內的變數下標及修飾符先前被視為靜態文字，但它們其實可以執行程式碼，因此現在需要核准。
• 不安全的help／man變體不再自動核准。某些呼叫可能假借閱讀文件之名，執行不安全選項、命令替換或反斜線路徑。
• 遠端工作階段提示順序。遠端工作階段的權限提示，無法再於本機確認對話方塊之前繼續。
• docker daemon重新導向旗標會觸發提示。帶有--url、--connection、--identity或Podman遠端模式的docker命令（包括Podman的dockershim）先前不經提示即可執行；這些旗標其實會將命令導向完全不同的daemon。
• 要求file指定寫入來源時，不再享有唯讀免審權限。file -m／--magic-file及-f／--files-from現在需要權限，不再以唯讀操作自動核准。

Hooks 如何運作？

Hooks 會在 Claude Code 工作流程的特定節點執行確定性的 shell 指令。不同於透過提示要求 Claude 執行動作，hooks 不受模型行為影響，能確保指令必定執行。對於落實團隊標準及自動化重複性工作而言，hooks 至關重要。請參閱決策框架，其中的「該選擇哪種 Hook 類型？」決策樹涵蓋 command、prompt 與 agent hooks。

為何使用 hooks 而非提示：要求 Claude「編輯檔案後一律執行 Prettier」有時確實有效。但 Claude 可能忘記、以速度為優先，或認為變更「微不足道」。Hooks 則能確保每次執行：每次 Edit 或 Write 都會觸發格式化工具，無一例外。面對合規、安全性及團隊標準時，確定性勝過機率性。⁴

可用事件

SessionStart 的 source 值。SessionStart hook 輸入包含 source 欄位，用來說明工作階段如何開始："startup"、"resume"、"clear" 或 "compact"。自 v2.1.214 起，若工作階段一開始就是 fork，會回報 source: "fork"，而非 "resume"——這是 hook 端對應於 v2.1.212 /fork 轉為背景執行的變更。若 SessionStart hook 依 source 分支處理（例如只在 "resume" 時重新注入脈絡），請更新比對清單，一併涵蓋 "fork"。¹⁸⁵

Hook 設定

在 settings.json 或專用的 hooks.json 中定義 hooks：

{
  "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"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/inject-context.sh"
          }
        ]
      }
    ]
  }
}

Matchers

matcher 欄位決定哪些工具會觸發 hook：

{"matcher": "*"}              // Match all tools
{"matcher": "Bash"}           // Match Bash only
{"matcher": "Edit|Write"}     // Match Edit or Write
{"matcher": "mcp__github"}    // Match MCP server tools
{"matcher": ""}               // Match for events without tools (like UserPromptSubmit)

使用 | 比對多個工具（Edit|Write）。自 v2.1.191 起，以逗號分隔的 matchers（例如 Bash,PowerShell）也能正確觸發；舊版會直接忽略，因此使用逗號 matcher 的 hook 完全不會執行。¹⁷³ 自 v2.1.195 起，包含連字號識別碼的 matchers（例如 code-reviewer、mcp__brave-search）會進行精確比對，不再意外採用子字串比對。因此，matcher 不會再因非預期工具名稱僅含有該字串而觸發。若要比對某個連字號命名之 MCP 伺服器的所有工具，請使用 mcp__brave-search__.* 這類明確模式。¹⁷⁴

自 v2.1.214 起，Hook if: 路徑條件以 cwd 為範圍。同樣影響權限允許規則的單一路徑區段範圍變更（請參閱權限規則語法），也適用於 hook if: 條件：dir/** 這類條件現在只會比對 <cwd>/dir，而非目錄樹中的每個 dir/。若要恢復任意深度比對，請使用 **/dir/**。¹⁸⁵

Hook 輸入／輸出協定

Hooks 會透過 stdin 接收 JSON：

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123"
}

Hook 事件資訊擴充（v2.1.69+）：由 subagent 或 --agent 工作階段觸發時，所有 hook 事件現在都會包含 agent_id 與 agent_type 欄位；狀態列 hook 指令中也會包含 worktree 欄位。¹¹⁰

Stop/SubagentStop hooks（v2.1.47+）會收到額外的 last_assistant_message 欄位，其中包含 Claude 的最終回應文字，讓 hooks 不必剖析逐字記錄檔案即可檢查輸出：

{
  "session_id": "abc-123",
  "last_assistant_message": "I've completed the refactoring. Here's what changed..."
}

不阻擋的柔性回饋（v2.1.163+）：Stop 與 SubagentStop hooks 可在其 JSON 輸出中傳回 hookSpecificOutput.additionalContext，向 Claude 提供回饋並讓回合繼續，且回應不會被標記為 hook 錯誤。在此之前，Stop hook 唯一實際可用的手段是以結束碼 2 阻擋（看似錯誤，且會計入連續阻擋上限）；additionalContext 則新增一條引導管道，可傳達「這是您遺漏的內容，請繼續」之類的指示，又不會干擾迴圈。[^183]

結束碼會控制行為： - 0：成功：操作繼續。在詳細模式（Ctrl+O）中顯示 stdout。若為 UserPromptSubmit 和 SessionStart，stdout 會加入脈絡。 - 2：阻擋錯誤：操作停止。Stderr 會成為回傳給 Claude 的錯誤訊息。 - 1、3 等：非阻擋錯誤：操作繼續。在詳細模式中以警告顯示 stderr。

若需要進階控制，hooks 可以輸出 JSON：

{
  "decision": "allow",
  "message": "Command validated and modified",
  "modifications": {
    "tool_input": {
      "command": "npm test -- --coverage"
    }
  }
}

PreToolUse 決策控制（建議格式）：PreToolUse hooks 使用 hookSpecificOutput 提供更完整的控制能力：3 種結果（allow/deny/ask），並可修改工具輸入及注入脈絡：⁸⁹

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

注意：PreToolUse 已棄用頂層的 decision 與 reason 欄位。請改用 hookSpecificOutput.permissionDecision 和 hookSpecificOutput.permissionDecisionReason。其他事件（PostToolUse、Stop 等）仍使用頂層 decision。⁸⁹

UserPromptSubmit 工作階段標題（v2.1.94+）：UserPromptSubmit hooks 可透過 hookSpecificOutput.sessionTitle 設定工作階段標題。¹⁴⁰

非同步 Hooks（2026年1月）

Hooks 現在可以在背景執行，不會阻擋 Claude Code 的執行流程。請在 hook 設定中加入 async: true：⁸¹

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/notify-slack.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

適合使用非同步 hooks 的情境： - 不應拖慢工作階段的通知（Slack、電子郵件、Pushover） - 可在背景執行的記錄與遙測 - 非關鍵的後續處理（分析、備份）

不適合使用非同步 hooks 的情境： - 格式化（必須在下一次編輯前完成） - 驗證（失敗時必須阻擋） - 任何需要修改工具輸入／輸出的 hook

Prompt 型與 Agent 型 Hooks（v2.1.32+）

除了 shell command hooks（type: "command"）之外，Claude Code 還支援 2 種由 LLM 驅動的 hook 類型；它們運用 AI 推理而非指令碼來評估條件。⁸⁹

Prompt hooks（type: "prompt"）會向快速的 Claude 模型傳送單回合提示。模型傳回 { "ok": true } 即允許，傳回 { "ok": false, "reason": "..." } 則阻擋：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all requested tasks are complete and tests pass.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

HTTP hooks（type: "http"）會將事件的 JSON 輸入以 POST 要求傳送至 URL，並接收傳回的 JSON。適用於 webhooks、外部通知服務或以 API 為基礎的驗證（v2.1.63+）：¹⁰⁴

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "http",
            "url": "https://api.example.com/notify",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

HTTP hooks 使用與 command hooks 相同的決策格式（傳回包含 decision 和 reason 的 JSON）。啟用沙箱時，要求會透過沙箱網路 Proxy 路由。SessionStart/Setup 事件不支援此類 hooks。

Agent hooks（type: "agent"）會產生具有工具存取權（Read、Grep、Glob）的 subagent，以執行多回合驗證。當檢查作業需要實際查看檔案或測試輸出時，請使用此類 hooks：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

使用 $ARGUMENTS 作為 hook 的 JSON 輸入預留位置。兩種類型皆支援 model（預設為快速模型）與 timeout 欄位。支援的事件包括：PreToolUse、PostToolUse、PostToolUseFailure、PermissionRequest、UserPromptSubmit、Stop、SubagentStop、TaskCompleted。TeammateIdle 不支援 prompt/agent hooks。

MCP 工具 Hooks（v2.1.118+）

Hooks 現在可以透過 type: "mcp_tool" 直接叫用 MCP 工具，不必再包裝會呼叫伺服器的 Bash 子行程。¹⁵²

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "linear",
            "tool": "create_comment",
            "input": {"issue_id": "ENG-123", "body": "Auto-updated by Claude Code"}
          }
        ]
      }
    ]
  }
}

此功能可與使用者現有的 MCP 伺服器相輔相成：凡是能透過 /mcp 存取的工具，皆可由 hook 呼叫。

PostToolUse Hooks 中的 duration_ms（v2.1.119+）

PostToolUse 與 PostToolUseFailure hook 輸入現在包含 duration_ms，也就是工具的執行時間，但不含權限提示與 PreToolUse hooks。¹⁵² 適合用於偵測緩慢工具、稽核記錄及各工具的延遲指標：

# Stderr-flagged warning when an Edit takes more than 10 seconds
DUR=$(jq -r '.duration_ms')
if [ "$DUR" -gt 10000 ]; then
  echo "[slow-edit] ${DUR}ms — investigate $TOOL_INPUT_FILE_PATH" >&2
fi

適用所有工具的 updatedToolOutput（v2.1.121+）

在 v2.1.118 中，MCP Tool Hooks 取得了透過 hookSpecificOutput.updatedToolOutput 取代工具輸出的能力。自 v2.1.121 起，同一欄位適用於任何 PostToolUse hook——包括內建工具（Bash、Read、Edit、Glob、Grep 等）、subagent 工具與 MCP 工具。適用情境包括：遮蔽任何工具輸出中的敏感內容、將結構標準化以供下游取用，以及在 agent 讀取結果前注入中繼資料。¹⁵⁴

Hook 環境變數

Hooks 可存取用於解析路徑的環境變數：⁸⁹

從 SessionStart 保存環境變數：

#!/bin/bash
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
fi
exit 0

HTTP hook 安全性（v2.1.51+）：若 HTTP hooks 將環境變數插入標頭，現在必須提供明確的 allowedEnvVars 清單。這可防止任意環境變數透過標頭值外洩。啟用沙箱時，HTTP hooks 也會透過沙箱網路 Proxy 路由，並強制套用網域允許清單。HTTP hooks 不支援 SessionStart/Setup 事件。⁹⁸

{
  "hooks": {
    "PostToolUse": [{
      "hooks": [{
        "type": "command",
        "command": "curl -H 'Authorization: Bearer $MY_TOKEN' https://api.example.com/notify",
        "allowedEnvVars": ["MY_TOKEN"]
      }]
    }]
  }
}

Hook 工作區信任（v2.1.51+）：statusLine 與 fileSuggestion hook 指令現在必須先在互動模式中接受工作區信任，才會執行，藉此封堵潛在的安全漏洞。⁹⁸

實用 Hook 範例

編輯後自動格式化 TypeScript 檔案：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c '[[ \"$FILE_PATH\" == *.ts ]] && npx prettier --write \"$FILE_PATH\" || true'"
          }
        ]
      }
    ]
  }
}

記錄所有 bash 指令：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/bash-history.log"
          }
        ]
      }
    ]
  }
}

阻擋敏感檔案的存取：

#!/bin/bash
# .claude/hooks/protect-files.sh
data=$(cat)
path=$(echo "$data" | jq -r '.tool_input.file_path // empty')

if [[ "$path" == *".env"* ]] || [[ "$path" == *"secrets/"* ]] || [[ "$path" == *".pem"* ]]; then
  echo "Blocked: Cannot access sensitive file $path" >&2
  exit 2  # Exit 2 = block the tool call. Exit 1 = non-blocking error (hook failure only).
fi
exit 0