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

TL;DR：Claude Code是一套代理式CLI，能讀取程式碼庫、執行命令及編輯檔案，並由5大系統管控：設定、權限、hooks、MCP與subagents。凡是每次都必須執行的工作，請使用hooks，而非prompts。

目前狀態（CLI v2.1.292，2026年10月6日；npm的latest與next皆為2.1.292，stable為2.1.285）：²³⁴

• 預設模型：Claude Opus 5.5（claude-opus-5-5），適用於Pro、Max、Team、Enterprise及Anthropic API，也適用於AWS、Amazon Bedrock及Google Cloud Agent Platform上的Claude Platform。Microsoft Foundry是例外：其預設模型為Sonnet 4.5，而opus別名指的是Opus 4.6。²²¹
• Opus 5.5概覽：每百萬tokens的費用為$4/$20，快取讀取費用為$0.20；在Anthropic API上預設提供1M context，而自v2.1.287起，Bedrock、Agent Platform及Foundry亦同；預設使用medium effort，且無法關閉thinking。Fast mode以$8/$40的費率執行。若任務不需要Opus，Sonnet 5.5（$2/$10；自v2.1.284起，在Anthropic API上以sonnet表示）是較經濟的選擇。^{220222223228232}
• Auto mode是所有方案與供應商在互動式終端機及VS Code工作階段中的初始權限模式（v2.1.283-284）；claude -p與Agent SDK工作階段則以Manual模式啟動，除非傳入--permission-mode auto（v2.1.302撤銷了v2.1.285針對第三方供應商及關閉遙測時預設啟用auto的變更）。²⁷¹ 對Enterprise與Claude API帳戶而言，其安全檢查會在伺服器端免費執行；AWS、Bedrock、Agent Platform及Foundry上的Claude Platform，以及透過閘道連線的環境亦然。若無法使用，則改以須計費的本機檢查作為備援。^{219227228229230}
• AGENTS.md：自v2.1.277起，若專案中沒有CLAUDE.md，系統會將AGENTS.md讀取為專案指示；但無法擷取功能旗標的環境（例如Bedrock），以及安裝或升級後的第一個工作階段除外。²¹⁹²²³

各版本的發布紀錄請參閱變更日誌。

Claude Code以代理式系統運作，而非具備程式設計知識的聊天介面。CLI會讀取程式碼庫、執行命令、修改檔案、管理git工作流程、透過MCP連接外部服務，並將複雜任務委派給專門的subagents。所有操作皆透過命令列介面進行，融入開發人員的實際工作方式。截至2026年2月，公開GitHub commits中有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，控制了從行為到自動化的一切。
• 將工作交由Delegation Layer處理：subagents會在乾淨的context windows中獨立探索，僅傳回摘要，避免context過度膨脹。
• Hooks保證執行，prompts則否：對於無論模型如何運作、每次都必須執行的linting、formatting及security checks，請使用hooks。
• 模型分級兼顧成本與品質：將subagent探索工作交由較便宜的模型處理，把Opus保留給真正需要架構推理的任務；若品質是唯一考量，也可全面統一使用Opus。
• MCP將Claude連接至您的工具鏈：資料庫、GitHub、Sentry及3,000多項整合，讓Claude的能力不再侷限於讀取檔案及執行bash命令。

我花了數月時間，在正式環境程式碼庫、CI/CD pipelines及企業部署中將Claude Code推向極限。本指南將這些經驗濃縮成一份完整參考資料，正是我開始使用時希望能找到的內容。每項功能均附有實際語法、真實設定範例，以及即使經驗豐富的使用者也容易踩到的陷阱。

選擇您的閱讀路徑

如何使用本指南

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

使用瀏覽器的Ctrl+F／Cmd+F搜尋特定flag、command或configuration key。文末的快速參考卡彙整了所有主要commands，方便快速瀏覽。

相關深入解析

以下文章深入探討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伺服器，以及企業部署，但開始使用並不需要先完成這些設定。

先決條件：只有舊版npm安裝方式需要Node 22+（自v2.1.198起由18提高；目前的安裝文件註明「Node.js 22或更新版本」，已於2026年8月7日驗證）；建議使用的原生安裝程式不依賴Node。支援macOS／Linux／Windows 10+。使用Claude Pro、Max、Team或Enterprise訂閱方案，或按token計費的Anthropic API金鑰，即可支付使用費用。如需各平台的具體說明、疑難排解，以及原生二進位檔安裝方式（自v2.1.113起成為預設方式），請參閱如何安裝Claude Code？。本指南會隨每個版本維護最新版本的佐證；目前的驗證時間戳記請參閱Changelog的最新一列。²⁶³

Claude Code的運作方式：心智模型

在深入瞭解各項功能之前，請先理解Claude Code的架構如何影響每一項操作。此系統分為3個層級運作：

┌─────────────────────────────────────────────────────────┐
│                    CLAUDE CODE LAYERS                    │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐    │
│  │   MCP   │  │  Hooks  │  │ Skills  │  │ Plugins │    │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘    │
│  External tools, deterministic automation, domain       │
│  expertise, packaged extensions                          │
├─────────────────────────────────────────────────────────┤
│  DELEGATION LAYER                                        │
│  ┌─────────────────────────────────────────────────┐    │
│  │           Subagents (20 concurrent default)      │    │
│  │   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 │
└─────────────────────────────────────────────────────────┘

核心層（Core Layer）：您的主要對話。每則訊息、每次讀取檔案，以及每項工具輸出，都會占用共用視窗的context（標準為200K tokens⁹¹；使用Opus 4.6或extended context models時為1M tokens）。當context用盡時，Claude會無法掌握先前的決策，品質也會隨之下降。此層按token計費。

委派層（Delegation Layer）：Subagents會以全新的context啟動、專注處理特定工作，並傳回摘要。探索結果不會讓主要對話變得臃腫，只會回傳結論。探索工作可交由較便宜的model tiers處理；若品質比成本更重要，也可全程使用主要model。

擴充層（Extension Layer）：MCP可連接外部服務（資料庫、GitHub、Sentry）。無論model如何運作，Hooks都能確保shell commands執行。Skills則封裝領域專業知識，供Claude自動套用。Plugins可將上述功能封裝，以便散布。

關鍵洞見：大多數使用者完全在核心層工作，眼看context日益膨脹、成本節節攀升。進階使用者則把探索與專業工作交給委派層，依照自身工作流程設定擴充層，並只在協調工作及做出最終決策時使用核心層。

目錄

1. 如何安裝Claude Code？
2. 快速開始：您的第一次工作階段
3. 核心互動模式
4. 深入解析設定系統
5. 我該選擇哪個Model？
6. Claude Code的費用是多少？
7. 決策框架
8. 權限系統如何運作？
9. Hooks如何運作？
10. 什麼是MCP（Model Context Protocol）？
11. 什麼是Subagents？
12. 什麼是Extended Thinking模式？
13. 輸出樣式
14. Slash Commands
15. Skills如何運作？
16. Plugin系統
17. Memory如何運作？
18. 圖片與多模態輸入
19. 語音模式
20. Git整合如何運作？
21. 如何在IDE中使用Claude Code？
22. 進階使用模式
23. 遠端與背景Agents［研究預覽］
24. Chrome中的Claude
25. Slack中的Claude Code［研究預覽］
26. 網頁版Claude Code［研究預覽］
27. Microsoft 365中的Claude（2026年5月）
28. 效能最佳化
29. 如何偵錯問題？
30. 企業部署
31. 鍵盤快速鍵參考
32. 最佳實務
33. 工作流程範例
34. 移轉指南
35. 針對不同讀者的指引
36. 快速參考卡
37. Changelog
38. 參考資料

如何安裝Claude Code？

系統需求

Claude Code可在macOS 13+、Ubuntu 20.04+/Debian 10+與Windows 10+（原生環境或WSL）上執行。系統至少需要4 GB RAM與有效的網際網路連線。⁹² Bash、Zsh或Fish能提供最佳的Shell相容性。

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

透過Proxy或Gateway時，切勿將版本固定在2.1.275。 在此版本中，若ANTHROPIC_BASE_URL指向Proxy或Gateway，每項請求都會因400 ... Input tag 'advisor_20260301'而失敗；2.1.276已修正這項迴歸問題。²¹⁸

NPM安裝（已棄用）

注意： 自v2.1.15起，npm安裝會顯示棄用通知。目前建議使用原生二進位檔進行安裝。請執行claude install完成移轉。

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

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

切勿搭配sudo執行npm安裝。這會引發權限問題，讓後續操作更為複雜。

從既有安裝移轉

若您使用的是較舊的npm安裝版本，請移轉至原生二進位檔：

claude install

驗證選項

Claude Code支援3種驗證方式，各有不同取捨：

Claude Console（API計費）

透過platform.claude.com（前身為console.anthropic.com）直接連線至Anthropic的API。建立帳號、設定計費方式，再透過CLI進行驗證。Console依用量計費，並提供完整的API存取權。系統會自動建立專用的「Claude Code」工作區；雖然無法為此工作區建立API金鑰，但仍可監控用量。自v2.1.243起，/login → Anthropic Console除了建立API金鑰外，也提供無金鑰登入方式「使用您的Console帳號登入」（建議）。因此，即使組織不允許使用API金鑰，仍能以Console憑證登入。²⁴⁶

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。¹⁵⁴ 信任作業系統CA憑證（v2.1.101+）： 企業TLS Proxy現在預設即可運作，因為Claude Code會信任作業系統的憑證存放區。若只想使用內建CA，請設定CLAUDE_CODE_CERT_STORE=bundled。¹⁴³

# 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

若企業部署位於Proxy後方或透過LLM Gateway連線：

# 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

Gateway提示標頭（v2.1.273）： Claude Code可新增供LLM Gateway進行路由與觀測的請求標頭，包括x-claude-code-request-class、x-claude-code-agent-type、x-claude-code-prev-tool-durations、x-claude-code-compaction、x-claude-code-context-compacted，以及自v2.1.283起加入的x-claude-code-prompt-id。後者是服務單次使用者提示之所有請求共用的隨機UUID，亦包含subagent回合。²¹⁷²²⁶ 使用自訂基礎URL或Bedrock等第三方供應商時，這些標頭預設為停用，必須設定CLAUDE_CODE_GATEWAY_HINT_HEADERS=1才會啟用。Gateway通訊協定文件另有說明：直接連線至Anthropic API時，預設會傳送這些標頭；設定CLAUDE_CODE_GATEWAY_HINT_HEADERS=0則可在所有連線中停止傳送。²²⁷

驗證安裝

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

自v2.1.268起，claude auth status --json會包含configDirectory，也就是CLI實際讀取的設定目錄。當CLAUDE_CONFIG_DIR間接指定目錄而造成混淆時，此資訊格外實用。²¹⁶

自v2.1.273起，以Claude帳號登入時，也會要求存取您的claude.ai plugins。²¹⁷

自v2.1.286起，claude auth status會將Console登入所儲存的API金鑰回報為api_key，而非claude.ai。²³¹

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

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 也會出現在轉送串流裡，並分別以產生該 subagent 的 Agent 呼叫之 tool_use ID 作為索引。因此，處理管線可以重建委派樹狀結構，而非只能看見扁平的文字清單。這項變更與同一版本恢復預設可在深度 3 進行巢狀產生的功能相輔相成；若沒有轉送功能，3 個層級中會有 2 個無法看見。¹⁹⁶

移至背景的 subagents 不再失去訊息（v2.1.273）：當 subagent 在執行途中移至背景時（例如透過 CLAUDE_AUTO_BACKGROUND_TASKS），SDK 與 stream-json 輸出不再遺漏該 subagent 剩餘的訊息及最終報告。²¹⁷

卡住的 -p 執行現在會回報錯誤（v2.1.277）：過去，claude -p 與 Agent SDK 工作階段遇到內部錯誤時，可能在沒有結果的情況下持續卡住。這是處理管線最糟糕的失敗模式，因為只能依賴外部逾時來終止執行。現在它們會回報錯誤並以結束碼 1 結束，因此下方的結束碼表再次成為完整規範。同一版本也讓無頭工作階段在結束時儲存成本與用量總計：無頭恢復（claude -p --resume、SDK、重新載入 VS Code 擴充功能視窗）不再將工作階段的總計重設為零，因此恢復後的無頭執行不會再低估成本。²¹⁹

結束碼：

控制 -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-5

# Bare mode: skip hooks, LSP, plugin sync, skill walks (v2.1.81+); only CLI-named MCP servers (v2.1.286)
claude -p "count files" --bare

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

# Restricted mode for eval harnesses and shared machines (v2.1.248+)
claude --restricted -p "query" --tools "Read,Grep,Glob"

# Unattended hosts: deny anything that would prompt (v2.1.259+)
claude -p "run the nightly checks" --permission-prompts none

受限模式（v2.1.248+）：--restricted（或 CLAUDE_CODE_RESTRICTED=1）專為在共用機器上驅動 claude 的評測框架而設計。此模式會移除用於執行命令或程式碼的內建工具，以及 WebFetch；除非您在 --tools 中逐一指定，且 default 預設集不算在內。它也會將內建檔案工具限制於工作目錄，只載入受管理的設定與 --settings（忽略使用者、專案及本機設定檔），拒絕 bypassPermissions，並拒絕建立雲端工作階段。²⁰⁶²⁰⁹

--permission-prompts none（v2.1.259）：這是無人值守主機的搭配選項。任何原本會觸發權限提示的操作都會遭到自動拒絕，而目前啟用的權限模式（包括自動模式）仍會自行做出所有不需您介入的決定。請勿將它與 --permission-prompt-tool 混為一談；後者會將提示委派給 MCP 工具，而不是直接拒絕。CLI 參考文件尚未列出這個新旗標；應以 CHANGELOG 為準。²¹¹

非互動工作階段中的 cd 會跨輪保留（v2.1.265）：以 stream-json 輸入餵送的 -p 工作階段、Agent SDK 工作階段及雲端工作階段，不再於每則新使用者訊息出現時重設 shell 工作目錄；某一輪執行的 cd，現在會延續至下一輪。²¹⁵

--system-prompt-snapshot off（v2.1.267）：預設情況下，對話會在每次請求中重複使用已記錄的系統提示詞。此旗標改為在每次請求時重新產生系統提示詞，適合反覆調整提示詞文字，讓每次執行都能採用最新修改，而非沿用快照；代價則是犧牲快照原本要維持的提示詞快取穩定性。²¹⁶

--bare 確實遵守其限制（v2.1.286）：--bare 現在只會連線至命令列中指定的 MCP 伺服器、不向模型傳送任何系統提醒，也不啟動背景工作；shell 命令達到逾時後會停止，而非轉移至背景。無頭模式文件指出，在 v2.1.286 之前，這些限制僅部分生效，並建議在指令碼與 SDK 呼叫中使用 --bare。²³¹²³³

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"

# Open the Claude desktop app on this directory, or on a session (v2.1.285)
claude --desktop
claude --desktop --continue

使用 /cd 移動執行中的工作階段（v2.1.169+；自 v2.1.246 起立即套用設定）：/cd path 可在不破壞提示詞快取的情況下變更工作目錄。自 v2.1.246 起，移動後會立即套用新目錄的專案設定、hooks、.mcp.json 伺服器（仍需經過一般核准提示）、skills 與 agents，不必等到使用 --resume。²⁵⁸²⁴⁵

與 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 徽章可透過 prUrlTemplate 設定（v2.1.119+）指向自訂程式碼審查 URL；若團隊會從 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。¹⁹² 自 v2.1.221 起，分支工作階段會建立自己的 worktree，不再使用原工作階段的 checkout；探索替代方案的分支因此不會再與主要工作階段尚未提交的檔案互相衝突，消除了派出副本進行實驗時的一大隱患。¹⁹⁹ v2.1.232 也讓建立分支成為 subagents 的預設行為：subagent_type: "fork" subagent 會繼承完整對話與提示詞快取，而互動式工作階段中產生的非隊友 agent，現在預設也會在背景執行。²⁵¹

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 已在官方文件新增的無障礙功能頁面中說明此模式及其互動方式。¹⁸⁶

每行輸出前不再暫停（v2.1.287）：螢幕閱讀器模式現在會直接寫入新增或變更的行，不再先將游標停在行首稍作暫停。CLAUDE_AX_PREPARK_MS 可設定該暫停的毫秒數；預設值現為 0（先前為 50），若要恢復原行為，請設定 CLAUDE_AX_PREPARK_MS=50。同一版本也修正了一系列螢幕閱讀器問題，包括搜尋框中的游標未停留在輸入文字旁，以及編輯核准提示未顯示變更行。²³²²³³

設定系統深入解析

Claude Code 採用分層式設定系統。理解這套層級至關重要：較高層級會覆寫較低層級，而企業設定則完全無法繞過。

設定層級

從提示列直接設定：/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-5",
  "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": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  },
  "sandbox": {
    "enabled": false,
    "autoAllowBashIfSandboxed": true,
    "excludedCommands": ["git", "docker"]
  },
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh"
  },
  "cleanupPeriodDays": 30,
  "outputStyle": "Explanatory",
  "language": "en",
  "respectGitignore": true,
  "showTurnDuration": true,
  "plansDirectory": ".claude/plans",
  "spinnerVerbs": ["Thinking", "Processing", "Analyzing"],
  "spinnerTipsOverride": {
    "label": "Team tips",
    "tips": [
      "Custom tip 1",
      {"id": "tip-2", "text": "Custom tip 2", "cooldownSessions": 5, "priority": 1}
    ],
    "tipsFile": "~/.claude/team-tips.json",
    "excludeDefault": true
  },
  "skillOverrides": {
    "legacy-skill": "off",
    "manual-only-skill": "user-invocable-only",
    "compact-skill": "name-only"
  },
  "includeGitInstructions": false,
  "modelOverrides": {
    "claude-opus-5-5": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/opus-prod",
    "claude-sonnet-5": "arn:aws:bedrock:us-east-2:123456789012:application-inference-profile/sonnet-prod"
  },
  "autoMemoryDirectory": ".claude/memory",
  "sandbox": {
    "enableWeakerNetworkIsolation": true
  }
}

當團隊擁有龐大的技能庫，但希望更嚴格地控管執行時的曝光範圍時，skillOverrides 便能派上用場。使用 off 可同時對模型與斜線選單隱藏某項技能；user-invocable-only 讓技能仍可依名稱呼叫，但不納入模型的選擇範圍；name-only 則只顯示技能名稱，不顯示完整描述。¹⁵⁶

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

• availableModels / enforceAvailableModels（受管理，v2.1.175+）：availableModels 允許清單限制工作階段可選用的模型。設定 enforceAvailableModels: true 後，允許清單也會約束 Default 模型：若 Default 會解析為不允許的模型，便改用第一個允許的模型；使用者與專案設定也無法再擴大受管理的 availableModels 清單。配套修正（v2.1.176）堵住了透過 ANTHROPIC_DEFAULT_*_MODEL 以別名選取而導向被封鎖模型的漏洞，且 /fast 現在會拒絕切換到允許清單以外的模型。¹⁷² 自 v2.1.187 起，組織可直接在 /model 選單、--model、/model 及 ANTHROPIC_MODEL 上強制執行模型限制；選取受限模型時，會顯示「restricted by your organization’s settings」訊息。¹⁷⁶
• language（v2.1.176 改進）：除了設定回應語言外，工作階段標題現在預設會以對話所用的語言產生；若要固定標題語言，請設定 language。¹⁷²
• footerLinksRegexes（v2.1.176）：在頁尾列顯示以正規表示式比對的連結徽章，可透過使用者或受管理設定進行設定。¹⁷²
• wheelScrollAccelerationEnabled（v2.1.174）：設為 false 即可在全螢幕模式下停用滑鼠滾輪捲動加速。¹⁷²

較新的設定（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）：autoMode 設定不再從儲存庫的 .claude/settings.local.json 讀取，請改在 ~/.claude/settings.json 中設定。此舉堵住了複製下來的儲存庫夾帶 auto 模式設定的途徑。¹⁸⁵

較新的設定（v2.1.217）：

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

較新的設定（v2.1.219）：

• sandbox.network.strictAllowlist（v2.1.219）：對沙箱中執行的指令，直接拒絕未列入允許清單的主機，不再提示，而非跳出權限對話框。請參閱沙箱模式。¹⁹⁶
• workflowSizeGuideline（v2.1.219）：可從任何設定檔（使用者、專案或受管理）設定建議性的 Dynamic workflow 規模準則，而不必只透過 /config。Dynamic workflows 預設採用 medium 準則（「aim for fewer than 15 agents」）；當設定檔已提供此值時，/config 中的對應列會自動隱藏。此準則僅供建議，並非強制上限。請參閱 Subagents。¹⁹⁶

較新的設定（v2.1.242–243）：

• modelPicker（使用者或受管理，v2.1.242+）：以有序且附標籤的模型清單，自訂 /model 選單。此設定為一個物件，包含 options 陣列（每列需有 model，可選填 label 與 description；model 會原樣採用，因此別名、Anthropic ID 以及 Bedrock/Vertex/Foundry/gateway ID 皆可使用），以及選填的 replaceBuiltInOptions 布林值（預設 false 會將這些列附加在內建清單之後；true 則只顯示您的列、Default 及工作階段目前正在使用的模型）。Claude Code 會從受管理設定、--settings 及使用者設定讀取此鍵，並忽略專案與本機設定中的值，因此複製下來的儲存庫無法重新標示選單；由設定此鍵的最高層級來源提供完整清單。availableModels 允許清單仍套用於每一列，而標籤只會改變選單顯示的內容，不會改變實際執行的模型。²⁴⁶²⁴⁴
• promptCacheTtl / subagentPromptCacheTtl（任何設定檔，v2.1.242+）：依請求類別設定 "5m" 或 "1h"，讓 API 金鑰與雲端供應商使用者能在主對話維持一小時快取，同時讓 subagents 維持五分鐘。請參閱快取策略。²⁴⁶²⁴⁴
• modelPricing（受管理，v2.1.243+）：組織簽約的各模型費率與折扣乘數，/cost、狀態列及遙測成本數據會改用此設定，而非牌價。請參閱檢視費用。²⁴⁶

較新的設定（v2.1.247）： - feedbackDrafts（v2.1.247）：控制新的 SendFeedback 工具。工作階段出問題時，Claude 可以草擬一份意見回饋報告，供您在 /feedback 中檢閱後送出；若要關閉草擬功能，請使用此設定。請參閱斜線命令中的 /feedback 一列。²⁴¹ - spinnerTipsOverride 結構擴充（v2.1.247）：提示項目除了純字串，現在也可以是 {id, text, cooldownSessions, priority} 物件；此物件也新增了 tipsFile 與 label 鍵，讓組織能將自己的提示與內建提示一併輪播（上方範例即為擴充後的結構）。設定參考文件現已收錄這些新鍵。²⁴¹²²⁷

較新的設定（v2.1.248–251）：

• desktopSessionCleanupPeriodDays（v2.1.248）：限制桌面版寫入的工作階段可免於逐字記錄清理的期限。與它一同推出的修正比這個設定本身更重要：Claude Desktop 與 Cowork 的工作階段過去會在 cleanupPeriodDays（預設 30 天）後消失；如今只要工作階段仍在應用程式中，清理就會保留它們，除非保留期限由組織政策管理。²⁰⁶
• 專案 env 限制（v2.1.251）：專案層級 .claude/settings.json 的 env 區塊不再能設定 CLAUDE_CONFIG_DIR、CLAUDE_CODE_TMPDIR 或 TMPDIR/TMP/TEMP。請改在 shell、使用者設定或受管設定中指定，如此一來，複製下來的儲存庫便無法改變 Claude Code 寫入設定與暫存檔的位置。²⁰⁶

較新的設定（v2.1.257-259）：

• timeFormat / timeZone（v2.1.257）：控制 Claude Code 呈現時間的方式，包括回合結束時的完成時鐘與逐字記錄時間戳記。timeFormat 接受 12 小時制、24 小時制、24 小時制 UTC，或明確的 strftime 格式；timeZone 則指定時區。²¹¹設定參考文件現已收錄這兩個鍵。²²⁷
• permissions.blockReadsOutsideWorkingDirectories（v2.1.257）：直接拒絕讀取工作階段工作目錄以外的檔案。未啟用時，auto mode 現在會在工作階段第一次進行此類讀取前詢問一次（請參閱 Auto Mode）。²¹¹ v2.1.273 補上兩個漏洞：檢查器無法完整分析的 Bash 命令會改為提示確認，而不再略過檢查；由儲存庫設定所指定的記憶目錄，在此設定下也不會被載入、召回或建立索引。²¹⁷
• managedMcpServers / managedSourcesBehavior：受管範圍的鍵，詳見企業部署：前者讓組織為每位使用者提供 MCP 伺服器（v2.1.259），後者則是跨受管來源的選擇性合併（於 v2.1.257 改進）。²¹¹²⁴⁰

較新的設定（v2.1.261）：

• bashOutputMaxChars / taskOutputMaxChars（v2.1.261）：分別提高 Claude 直接接收的命令輸出量與背景工作輸出量，超出部分會存入檔案，上限為 128K 字元。它們與 BASH_MAX_OUTPUT_LENGTH 環境變數的機制不同：該變數設定的是從命令工作輸出檔讀回的視窗大小（預設 30,000 字元，上限 150,000），而這兩個鍵控制的是直接呈現與寫入檔案之間的門檻。超過門檻後，輸出會存入檔案，供 Claude 視需要讀取，而不會遭到截斷。²¹⁴自 v2.1.265 起，寫入檔案的一側也有上限：存到磁碟的工具結果最多 1 GB，且對話中的預覽會註明已儲存的檔案是否遭到截斷。²¹⁵ 任務部分已於 v2.1.277 停用：已棄用的 TaskOutput 工具遭到移除，Claude 改以 Read 讀取背景工作的輸出檔，因此 taskOutputMaxChars 與 TASK_MAX_OUTPUT_LENGTH 已不再有任何作用。bashOutputMaxChars 不受影響。²¹⁹

較新的設定（v2.1.267-269）：

• maxEffortLevel（v2.1.267）：限制使用者可選擇的最高 effort 等級，可設在頂層，或在 modelSettings 下依模型個別設定，並適用於所有供應商，包括 Bedrock、Vertex 與 Foundry。使用者仍可選擇低於上限的等級；這是 /effort 在管理端的配套設定。²¹⁶
• advisorModel：由 /advisor 寫入使用者設定的已儲存 advisor 模型（fable、opus、sonnet 或完整 ID）。--advisor 可在單一工作階段中覆寫此值，CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 則會關閉此工具。請參閱 Advisor 工具。²⁷⁰
• sandbox.allowNestedUserNamespaces（v2.1.305）：允許 Linux 與 WSL2 上的沙箱命令建立使用者命名空間（例如 Chromium、rootless podman）。由於這會讓它們得以繞過沙箱的檔案保護，此設定只會從使用者設定或受管設定讀取。請參閱 Sandbox 模式。²⁷⁴²⁷⁵
• bashEditDiffEnabled（v2.1.269）：當 Bash 工具處理檔案編輯時，工具結果會附上該命令所變更檔案的 diff，讓對話中能清楚看出 sed 式編輯實際做了什麼。²¹⁶

較新的設定（v2.1.275）：

• syncClaudeAiSkills / syncClaudeAiPlugins（v2.1.275）：claude.ai 帳號上啟用的 skills 與 plugins，現在會同步到以同一帳號登入的終端機工作階段。將任一鍵設為 false，即可讓終端機工作階段只使用本機的 skills 與 plugins。請參閱 Skills 與 Plugin 系統。²¹⁸

較新的設定（v2.1.282-283）：

• maxProseWidth（v2.1.282）：限制寬終端機中 Claude 散文內容的寬度。段落、標題、清單與引言區塊會在指定欄數內換行，表格與程式碼區塊則維持全寬。數值為整數欄數，最小為 40。²²⁵²²⁷
• deniedModels / availableModelsMatch（受管，v2.1.283）：deniedModels 可封鎖特定模型，即使 availableModels 允許它們也一樣。像 "opus" 這樣的系列別名會封鎖整個系列，而 "claude-opus-5" 也會封鎖 Opus 5.5（若只要封鎖 Opus 5，請寫 "claude-opus-5-0"）。預設情況下，"claude-opus-5" 這類 availableModels 項目也會允許以其為前綴的後續版本；設定 availableModelsMatch: "exact" 後，每個項目只允許其指名的版本，因此新版本在您列入清單前都會保持封鎖。Claude Code 只會從受管設定讀取這兩個鍵。²²⁶²²⁷
• allowClaudeInChromeWithManagedMcp（受管，v2.1.282）：讓 claude --chrome 能與獨佔式的 managed-mcp.json 並行運作；Chrome 遭封鎖時顯示的錯誤訊息現在會指出此鍵。²²⁵設定參考文件現已收錄此鍵：它只會從裝置本身的受管設定讀取，且針對 claude-in-chrome 的 deniedMcpServers 項目仍會封鎖該伺服器。²³³

較新的設定（v2.1.285）：

• allowedProviders（受管，v2.1.285）：限制機器可使用的 API 供應商：Anthropic API、自訂端點、Bedrock、Mantle、Vertex AI、Foundry、Claude Platform on AWS 或 Cloud gateway。²²⁹設定參考文件已收錄此鍵；若伺服器受管設定也提供了清單，來自機器本身管理來源的清單仍會繼續套用，因此工作階段只能使用同時列於兩份清單中的供應商。²³³

設定速查：最常搜尋的旗標

如果您是為了依名稱尋找特定設定而來，這裡就是簡短索引。每個項目都標明其推出的版本，若該設定專屬於某個範圍，也會一併註明：

各主題的官方文件在哪裡？

本指南是一本實戰手冊，並非權威參考文件。如需查閱 Anthropic 各子系統的正式頁面，請參閱下列官方位置（本指南各章節皆已附上對應連結）：

環境變數參考

驗證與 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; credential/org/routing/API-behavior headers set from managed or project settings require approval (v2.1.251)[^238]

模型設定：

ANTHROPIC_MODEL=claude-opus-4-7                 # Override default model (Apr 16, 2026)
ANTHROPIC_DEFAULT_MODEL=claude-opus-5-5         # Model new sessions START on; a /model pick overrides + persists (v2.1.236)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5-5    # What the `opus` alias resolves to (Opus 5.5 since v2.1.280; Opus 5 v2.1.219-278)
ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5-20251001  # pin the haiku alias; on the Anthropic API it resolves to Haiku 5.5 (claude-haiku-5-5) as of v2.1.293[^274][^275]
CLAUDE_CODE_SUBAGENT_MODEL=sonnet               # Default model for subagents; an agent's model: field and per-spawn picks win (v2.1.251 demoted it from override to default)[^238]
CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1             # Turn the advisor tool off: /advisor becomes unavailable, advisorModel is ignored, --advisor is accepted but does nothing[^282]
CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1              # Force every subagent onto CLAUDE_CODE_SUBAGENT_MODEL (or the main model), ignoring agent-definition and per-spawn overrides -- the pre-v2.1.251 behavior, opt-in (v2.1.257)[^243]
CLAUDE_CODE_DISABLE_WORKFLOWS=1                 # Turn dynamic workflows off for one session; same effect as "disableWorkflows": true, and whichever of the two turned them off, the other cannot turn them back on. Workflows are on by default except on Pro, where "enableWorkflows": true (the Dynamic workflows row in /config) turns them on; the v2.1.147 opt-in CLAUDE_CODE_WORKFLOWS=1 no longer appears in the env-vars reference[^291]
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_MAX_TURNS=10                        # Cap agentic turns when no --max-turns is passed; the flag wins when both are set, and a value that is not a positive integer is rejected at startup[^291]
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
VERTEX_REGION_CLAUDE_HAIKU_5_5=us-east5          # Vertex region for Claude Haiku 5.5 (v2.1.293+)[^276]
CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1    # Opt in gateway /v1/models discovery for /model picker (v2.1.129+)[^164]
CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS=3000  # Extend the LLM gateway /v1/models discovery timeout (default 3s; v2.1.269+)[^252]
CLAUDE_CODE_GATEWAY_HINT_HEADERS=1              # Send the x-claude-code-* hint headers (request-class, agent-type, prev-tool-durations, compaction, context-compacted, and prompt-id from v2.1.283) through a gateway or third-party provider; a direct Anthropic API connection sends them by default, and =0 stops them everywhere (v2.1.273+)[^253][^262][^263]
CLAUDE_CODE_AUTO_MODE_SERVER=0                  # Opt out of the server-side auto-mode checks, the default since v2.1.278 for Enterprise and Claude API accounts, Claude Platform on AWS, Bedrock, Agent Platform, Foundry, and gateways (not charged when the server performs them; =1 was the v2.1.273-277 opt-in); also applies on a direct Anthropic API connection since v2.1.281, where server-side is the default with telemetry off since v2.1.282; the docs call it temporary[^253][^255][^259][^260][^261]
CLAUDE_CODE_AUTO_MODE_MODEL=claude-sonnet-5-5   # Model the client-side auto mode classifier uses; no effect on server-side auto mode (v2.1.302+)[^283]

行為控制：

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
CLAUDE_CODE_DISABLE_WEB_FETCH=1                 # Turn off the WebFetch tool; WebSearch stays available (v2.1.285+)[^265][^269]
CLAUDE_CODE_DISABLE_ARTIFACT=1                  # Turn the Artifact tool off for one session; while it is set, no settings file turns artifacts back on[^291]
CLAUDE_CODE_ARTIFACT_AUTO_OPEN=0                # Do not open the browser when a new artifact is published[^291]
CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES=2      # Cap re-sends of a non-streaming fallback request that timed out (v2.1.285+)[^265]
CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS=5000 # Starting delay of the exponential backoff between retries of a 529 overloaded request, default 500; whole milliseconds from 500 to 32000; no effect with CLAUDE_CODE_RETRY_WATCHDOG=1 or in fast mode (v2.1.292+)[^272][^276]
CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS=60000 # Ceiling of that backoff, default 32000 ms (v2.1.296+; in the env-vars docs since October 14)[^274][^280]
CLAUDE_CODE_RETRY_WATCHDOG=1                     # Unattended sessions: retry 429 and 529 capacity errors indefinitely, backing off up to 5 minutes or until the limit resets (v2.1.186+)[^276]
CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS=1800000   # Cap, per request, on how long the watchdog waits out 429 and 529 errors; unset means no limit (v2.1.295+)[^274][^276]
CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS=3600000 # Under the watchdog, end a request at a usage limit that resets further away than this instead of waiting it out (v2.1.301+)[^283]
CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS=60000 # Minimum interval between checks that a usage limit was lifted before its reset, while the watchdog waits on it (v2.1.305+)[^286][^287]
CLAUDE_CODE_RESTRICTED=1                        # Restricted mode: no command/code tools or WebFetch unless named in --tools; only managed settings load (v2.1.248+)[^238]
CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT=1      # Keep the dangerous-rm prompt waiting in auto mode and --dangerously-skip-permissions instead of denying after 2 minutes (v2.1.281+)[^260]
CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT=1    # Skip the prompt for a recursive rm whose target is only command-substitution output, such as rm -rf "$(pwd)" (v2.1.281+)[^260]
CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT=1     # Keep prompting for an rm built at run time inside a shell -c script Claude Code cannot read; such scripts no longer prompt by default (v2.1.299+; release-notes only as of 2026-10-14)[^279][^280]
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+)
CLAUDE_CODE_PROMPT_CACHE_TTL=1h                 # Main-conversation cache TTL, 5m or 1h; beats the promptCacheTtl setting (v2.1.242+)[^234]
CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL=5m        # TTL for subagents, workflows, forks, compaction, titles; beats subagentPromptCacheTtl (v2.1.242+)[^234]
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=0                     # Turn fork subagents off; on by default in the terminal and, since v2.1.302, in claude -p, the Agent SDK, the desktop app, and VS Code (=1 was the external-build opt-in from v2.1.117; claude mcp serve never offers them)[^160][^283]
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+). Since v2.1.290 an interactive session's budget refills instead of ending at 200 (next line); the env-vars docs, fetched Oct 6, still describe the 200 cap[^206][^271][^273]
CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR=100     # WebSearch budget refill rate: 100 calls/hour by default in an interactive session, 0 (off) in a non-interactive one (v2.1.290+)[^271][^276]
CLAUDE_CODE_DISABLE_ATTACHMENTS=1               # Send @-mentions as plain text instead of expanding file content; a repo's .claude/settings.json or settings.local.json can no longer set it (v2.1.290)[^271][^273]
CLAUDE_CODE_DISABLE_FILE_MENTIONS=1             # Hand Claude the path of an @ mention to read with its file tools, not the file's contents, so PreToolUse hooks see the read; ignored in project and local settings (v2.1.299+)[^279][^280]
CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS=900000        # WebFetch per-URL session cache TTL (default 15 min; v2.1.233+)[^226]
CLAUDE_CODE_WEBFETCH_DEADLINE_MS=300000         # WebFetch hard deadline: a server that never finishes its response fails the fetch after 300s by default; 0 disables (v2.1.268+)[^252]
CLAUDE_CODE_PROJECT_DIR_NAME=myproj             # Short name for the per-project transcript directory, for hosts that give each session its own config dir (v2.1.234+)[^227]
CLAUDE_CODE_GOAL_CHECKIN_MINUTES=30             # How long background tasks may keep a /goal waiting before Claude checks in on them; 0 disables (v2.1.234+)[^227]
CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION=200       # Per-session subagent-spawn cap (default 200 in v2.1.212–223; the default cap was REMOVED in v2.1.224 — set this to reimpose one)[^206][^218]
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_WORKFLOW_PREFIX_STAGGER_MS=0        # Disable the v2.1.229 workflow fan-out stagger (same-prefix sibling agents launch staggered so they read the cached prompt prefix instead of re-paying it)[^224]
CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS=64   # Raise the Workflow tool's per-run concurrent agent limit, 1-256, for inference-bound fan-outs (v2.1.269+)[^252]
CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL=sonnet         # Run every workflow agent on one model while other subagents keep theirs (v2.1.296; release-notes only as of 2026-10-14)[^274][^280]
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                    # Read-back window from the Bash working output file (default 30,000 chars, hard ceiling 150,000)
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_MAX_MCP_DESCRIPTION_LENGTH=8192     # Override the cap on MCP tool descriptions and server instructions, every server in the session: 4,096 chars since v2.1.296, 2,048 in v2.1.280-295; Anthropic's first-party servers at api.anthropic.com are uncut since v2.1.299[^279][^256][^274]
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]
CLAUDE_CODE_MCP_STARTUP_WAIT_MS=10000           # Bound how long the FIRST non-interactive turn waits for still-connecting MCP servers; 0 = don't wait (v2.1.274+)[^254]
CLAUDE_CODE_TOOL_MEMORY_LIMIT=4096              # Opt-in Linux memory cgroup (MB) for Bash tool commands — a runaway build can't stall the session (v2.1.233+)[^226]
CLAUDE_CODE_ENABLE_TODO_TOOLS=1                 # Offer the TodoWrite/TaskCreate-family tools on models outside v2.1.268's allowlist (Claude 3.x, Opus 4.0-4.7, Sonnet 4.0-4.6, Haiku 4.5); elsewhere they are off unless set (first turned off on newer models in v2.1.233)[^226][^252]
SLASH_COMMAND_TOOL_CHAR_BUDGET=15000            # Slash command context limit

背景指令時間限制（v2.1.285，v2.1.288 縮小適用範圍）：背景執行的 Bash 與 PowerShell 指令達到時間限制後即會停止。以 run_in_background 執行時，此限制即為指令的 timeout（預設 30 分鐘，上限 2 小時）；指令遭停止時，Claude 會收到通知。²²⁹自 v2.1.288 起，此限制僅適用於無人值守的工作階段（-p、Agent SDK、CI 與雲端工作階段）；終端機、桌面應用程式與 VS Code 工作階段中的背景指令則不受時間限制。工具參考文件亦證實此點：「Before v2.1.288, it applied in every session.」（在 v2.1.288 之前，此限制適用於所有工作階段。）²³⁴[^273]

網路與 Proxy：

HTTP_PROXY=http://proxy:8080                    # HTTP proxy
HTTPS_PROXY=https://proxy:8080                  # HTTPS proxy
CLAUDE_CODE_GZIP_REQUEST_BODIES=0              # Turn off gzip compression of large request bodies sent to api.anthropic.com, on even with telemetry off since v2.1.300[^281][^282]
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

UI 與終端機：

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; not settable from project-settings env (v2.1.251)[^238]
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; not settable from project-settings env, nor are TMPDIR/TMP/TEMP (v2.1.251)[^50][^238]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Hold ALL native-1M models to 200K via auto-compaction (v2.1.223 widened scope); also the opt-out for the v2.1.287 1M default on Bedrock/Vertex/Foundry/Claude apps gateway[^103][^217][^268]
CLAUDE_CODE_AUTO_COMPACT_WINDOW=200k           # Auto-compact window, 100000 to 1000000 tokens; k and M suffixes since v2.1.304 (200k had set a 100K window), out-of-range values warn[^286][^287]
CLAUDE_CODE_DISABLE_ULTRAREVIEW_TRUST_CHECK=1  # Let claude ultrareview run in a folder you have not trusted where it cannot ask, such as CI; environment only, not a settings env block (v2.1.309+)[^286][^287]
CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS=150000     # Context size at which idle compaction applies, default 200000; values below 100000 are raised to 100000; "idleCompaction": false in settings.json turns the feature off (v2.1.299; the docs date both to v2.1.290+)[^279][^280]
CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1  # Let unrecognized model IDs exceed the assumed context window (v2.1.223)[^217]
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_CODE_BG_TASKS_REPORT_RUNNING=0         # Restore pre-v2.1.269 behavior: remote/headless sessions may report "waiting for your input" while background agents still run[^252]
CLAUDE_AX_SCREEN_READER=1                     # Enable screen reader mode; same as --ax-screen-reader or "axScreenReader": true (v2.1.208+)[^203]
CLAUDE_AX_PREPARK_MS=50                       # Screen reader mode: pause before writing a changed line; default 0 since v2.1.287 (was 50)[^268][^269]
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+); as of v2.1.273 also puts real agent, skill, plugin, and MCP server names on cost and token metrics[^253]
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+)
OTEL_METRICS_INCLUDE_REPOSITORY=1             # Tag OTel metrics and events with vcs.* repository attributes; with OTEL_LOG_TOOL_DETAILS, commit events carry vcs.ref.head.* (v2.1.269+)[^252]
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.290 also skips the startup connection warm-up[^271]
CLAUDE_CODE_ATTRIBUTION_HEADER=0              # Omit the system-prompt attribution block; behind a Claude apps gateway, set it in the env of the gateway's code or cli policy (v2.1.299+)[^279][^280]

專案設定無法開啟遙測（v2.1.282）：專案與本機設定檔現在會忽略用來開啟匯出、設定匯出端點或擷取內容的 OpenTelemetry 變數，例如 CLAUDE_CODE_ENABLE_TELEMETRY、OTEL_*_EXPORTER 選擇器與 OTEL_LOG_*。用來關閉功能的值（匯出器選擇器設為 none、內容旗標設為 0）在這些檔案中依然有效。其餘變數請改在 shell、使用者設定或受管設定中設定。若專案檔案設定了其中任一變數，互動式工作階段會在啟動時顯示通知，/status 與 claude doctor 也會列出被忽略的名稱；-p 與 Agent SDK 工作階段則不會顯示通知，因此升級後請確認您的收集器仍持續收到資料。²²⁵²²⁷

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 日誌事件上的數值屬性現在以數字型別輸出（先前為字串），修正了對 schema 採嚴格型別檢查的下游 OTel 收集器問題。新增的 claude_code.at_mention 日誌事件會在 Claude Code 解析 @ 提及時觸發。¹⁵⁴

v2.1.300 屬性：api_request 事件將快取寫入拆分為 cache_creation_5m_tokens 與 cache_creation_1h_tokens；trace span 帶有 GenAI 語意慣例屬性（gen_ai.provider.name、gen_ai.conversation.id、gen_ai.tool.name、error.type）；user_prompt 事件與互動 span 記錄的是經 mod 的 prompt.submit hook 改寫後的提示；在 reftable 儲存庫中執行 git commit -q 後，tool_result 事件會帶有 git_commit_id。²⁶⁹

v2.1.301 與 v2.1.302 屬性：tool_decision 事件帶有 classifier_verdict 與 permission_mode，可藉此區分 auto mode 分類器的決策與權限規則的決策；若設定 OTEL_LOG_TOOL_DETAILS=1，還會帶有 classifier_category，指出分類器阻擋時所符合的內建規則（v2.1.301）。v2.1.302 為大多數先前缺漏的分類器阻擋補上 classifier_category，並在 OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT 偏低時，仍保留事件上的 tool_use_id、tool_source 與 tool_parameters。監控文件目前尚未列出這三個屬性。²⁷¹²⁷²

v2.1.307 事件：每當工具呼叫遭權限規則、auto mode、安全檢查、hook 或沙箱阻擋、要求確認或退回時，都會觸發 claude_code.safety_event；除回合結束事件外，皆帶有 tool_use_id。監控文件已列出此事件，並且現在也列出了 classifier_verdict（v2.1.301+）。²⁷⁴²⁷⁵

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 截斷上限。¹⁹⁰

v2.1.265 閘道遙測：若閘道的受管設定在 OTEL_EXPORTER_OTLP_ENDPOINT 中指定了收集器，Claude apps 閘道工作階段現在會直接將 OpenTelemetry 匯出至該收集器，不再經由閘道的中繼轉送；未指定收集器的工作階段則繼續使用中繼。同一版本也在 Claude Desktop 與 Cowork 經由 Claude apps 閘道傳送的遙測中加入 user.email 與 user.groups，與終端機工作階段一致。²¹⁵

v2.1.280 hook 遙測：hook_execution_complete OTel 事件現在帶有 hook 輸出大小，以及因過大而另存為檔案的輸出數量。²²⁰

v2.1.287 prompt_text：user_prompt 事件現在帶有 prompt_text，這是 prompt 的副本，供會將含點號鍵名巢狀化的後端使用。凡是您的管線會捨棄或遮罩 prompt 之處，也請對 prompt_text 比照辦理。²³²

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+); a Read call with allow_large can pass it when the context has room (v2.1.296+)[^274][^276]
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1   # Do not fall back to non-streaming API on streaming failures (v2.1.83+)
CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1      # Stop sending structured outputs, for Mantle or gateways that reject them; session titles, memory recall, and prompt hooks failed there before (v2.1.288+)[^270][^273]
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+)
MCP_SDK_GENERATION=v1                         # Opt out of the v2 MCP client; v2.1.274 made v2 the default on the last holdouts (Bedrock/Vertex/Foundry + telemetry-disabled installs)[^254]
MCP_PROTOCOL_NEGOTIATION=legacy               # Opt out of MCP 2026-07-28 protocol negotiation: with direct HTTP servers (default everywhere as of v2.1.274) and, since v2.1.292, with local (stdio) servers on every install, Bedrock, Vertex, and Foundry included and, since v2.1.299, with cloud session and Remote Control connectors[^279][^254][^272]

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提供多個層級的彈性模型切換方式。

可用模型

Claude Sonnet 5.5（2026年9月28日）：自v2.1.284起，成為Anthropic API上的預設Sonnet模型，sonnet別名也改為指向此模型；所有方案的預設模型仍為Opus 5.5。模型ID：claude-sonnet-5-5（Bedrock：anthropic.claude-sonnet-5-5）。輸入$2/MTok，輸出$10/MTok，與Sonnet 5相同；快取讀取費率為$0.10/MTok（定價頁列為輸入價格的0.05倍，比例與Opus 5.5相同；v2.1.296修正了Claude Code本身先前以$0.20計算的成本數據）。1M token上下文視窗，輸出上限為128K（在Batches API上搭配output-300k-2026-03-24測試版標頭時，最高可達300K）。可靠知識截止日期為2026年6月，與Opus 5.5及Fable 5.1相同。最早於2027年9月28日退役。在Claude Code中，Sonnet 5.5的effort預設為medium（Claude API本身預設為high），且無法關閉思考。依內容採取的備援處理：標記為網路安全相關的請求會改用Sonnet 5重新執行；標記為生物學相關的請求則會遭到拒絕，因為Sonnet 5.5沒有生物學備援模型。需要Claude Code v2.1.284或更新版本；若要繼續使用Sonnet 5，請固定設定為ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5。²²⁸²³⁰

模型頁面列出從Sonnet 5遷移API程式碼時的5項不相容變更：使用between_tools會關閉前置思考；強制使用工具會傳回錯誤；思考區塊會綁定模型與對話；Claude API及Google Cloud不接受computer_20251124；advisor工具不接受Opus 4.8、Opus 4.7及Sonnet 5作為顧問模型。工具呼叫之間的文字也會透過thinking區塊傳回，因此原本串流顯示這些文字的介面會停止顯示，直到設定可傳回文字的display值為止。²³⁰

Claude Opus 5.5（2026年9月22日）：自v2.1.280起，成為Claude Code的新預設Opus模型；根據模型設定文件依方案列出的表格，也是所有方案與第一方供應商的預設模型：Pro、Max、Team、Enterprise、Anthropic API、Claude Platform on AWS、Amazon Bedrock及Google Cloud的Agent Platform（Microsoft Foundry仍使用Sonnet 4.5，其opus別名則對應至Opus 4.6）。同一版本也將Pro與Team Standard的預設模型從Sonnet改為Opus，「與Max、Team Premium及Enterprise一致」，結束了自高階方案改用Opus以來，各方案預設模型不同的情況。模型ID：claude-opus-5-5（Bedrock：anthropic.claude-opus-5-5），採用不含日期的固定快照命名方式，與claude-opus-5相同。價格低於Opus 5：輸入$4/MTok，輸出$20/MTok（Opus 5為$5／$25），快取讀取費率為$0.20/MTok，即輸入價格的5%，為標準10%的一半（只有Fable 5.1與Mythos 5.1更低，為2.5%）。1M token上下文視窗，輸出上限為128K（在Batches API上搭配output-300k-2026-03-24測試版標頭時，最高可達300K）。自適應思考持續啟用：模型總覽表將其標示為與Fable相同的「自適應（持續啟用）」，不同於Opus 5預設啟用但可關閉的模式。effort預設為medium（Opus 5預設為high），v2.1.280也配合調整了設定沿用規則：在/effort改為依模型個別設定之前儲存的思考投入程度，不再套用至Opus 5.5等新發布的模型；在您選擇投入程度之前，模型會使用自身的預設值。可靠知識截止日期為2026年6月（訓練資料同樣截至2026年6月），與Fable 5.1並列為目前所有模型中最新。最早於2027年9月22日退役。需要Claude Code v2.1.280或更新版本。²²⁰²²¹

將API程式碼從Opus 5遷移至Opus 5.5時的不相容變更：²²²

1. 無法停用思考。thinking: {type: "disabled"}與thinking: {type: "enabled", budget_tokens: N}都會傳回400錯誤。請移除thinking欄位，改為選擇思考投入程度。
2. 強制使用工具會傳回錯誤。tool_choice僅接受auto與none；any與tool會傳回400錯誤，token計數端點也不例外。請使用auto搭配嚴格工具使用模式或結構化輸出。
3. 思考區塊會綁定模型。若路由器或備援機制將對話從Opus 5.5切換至其他模型，執行這些回合時便不會包含Opus 5.5的思考區塊（Claude API上的Fable 5.1與Mythos 5.1除外）。
4. Claude API及Google Cloud不接受computer_20251124。請改為宣告computer_toolset_20260801工具集；Bedrock仍保留舊版工具。 還有一項變更不會導致任何請求失敗，卻會改變回應結構：模型在工具呼叫之間撰寫的文字會以thinking區塊傳回，而在預設的display設定下，這些區塊的內容為空。原本會串流顯示這些說明文字的介面將不再顯示內容，直到將設定改為display: "updates"（beta）或"summarized"為止。²²²

Claude Code依內容切換備援模型。 Opus 5.5搭配安全分類器運作，最常標記的是生物學與網路安全內容。當分類器標記某個請求時，Claude Code會改用另一個模型重新執行，並顯示通知：標記為生物學的請求會轉交Opus 5，標記為網路安全的請求則轉交Opus 4.8。工作階段會持續使用備援模型，直到您透過/model切換回原模型。在/config中關閉訊息遭標記時切換模型（switchModelsOnFlag: false），即可改為每次先詢問。²²³ 自v2.1.287起，切換時會保留目前的推理投入程度，而非採用備援模型的預設值。因此，若工作階段使用Opus 5.5預設的medium，切換到預設為high的Opus 4.8後，仍會維持medium。²³²²³³

Claude Opus 5（2026年7月；上一代Opus層級）： 從v2.1.219（2026年7月24日）起，直到v2.1.280將Opus 5.5設為預設Opus模型之前，Opus 5一直是Opus層級的代表，也是opus別名所指向的模型；以下介紹其於2026年7月推出時的情況。Anthropic將它描述為可直接替換Opus 4.8的升級版本：輸入價格同為$5/MTok，輸出同為$25/MTok，「在相同成本下大幅提升效能」，且在最高推理程度下，平均使用的token數比Opus 4.8約少26%。它當時是Claude Max的預設模型，也是Claude Pro最強大的模型。模型ID：claude-opus-5——這是不帶日期的固定快照，採用與claude-opus-4-8和claude-sonnet-5相同的命名方式，並非持續指向最新版的別名。1M token上下文視窗（不需beta標頭，與Opus 4.8相同），最大輸出128K（在Batches API上搭配output-300k-2026-03-24 beta標頭，最高可達300K）。僅支援自適應思考，不支援thinking.type: "enabled"延伸思考。可靠知識截止日期：2026年5月（訓練資料截止日期也是2026年5月）。從推出之日起，直到Fable 5.1（知識截止日期為2026年6月）於2026年9月1日登場之前，它的知識截止日期是當時所有現行Claude模型中最新的。²³⁷ 隨著Opus 5推出，Opus 4.8移至文件中的舊版模型表格，與4.7及4.6並列；仍可使用，但不再是建議的預設模型。¹⁹⁷

將代理執行框架從Opus 4.8遷移至Opus 5時，有2項不相容變更：¹⁹⁷

1. 預設啟用思考。 在Opus 4.8上，未包含thinking欄位的請求會不經思考直接執行；在Opus 5上，相同請求則會啟用自適應思考。max_tokens仍是總輸出量的硬性上限，涵蓋思考內容與回應文字。因此，對於先前未使用思考功能的工作負載，請重新確認可用的輸出餘裕。傳入thinking: {type: "disabled"}即可恢復舊有行為，但須遵守下一項限制。
2. 停用思考時，推理投入程度最高只能設為high。 將thinking: {type: "disabled"}與xhigh或max推理投入程度搭配使用，會傳回400。系統會逐一檢查每個請求；即使同一段對話中的先前回合曾獲接受，在停用思考的情況下將推理投入程度提高至xhigh，仍會遭到拒絕。

就Claude Code而言：Opus 5的effort預設為high（與Claude API相同），並提供完整的程度選項：low、medium、high、xhigh、max。Anthropic官方的遷移建議是：若模型能力比token支出更重要，可測試max推理投入程度。快速模式支援Opus 5，價格為每MTok $10/$50（請參閱快速模式）。¹⁹⁷¹⁹⁸

Claude Fable 5.1（2026年9月1日）： Fable層級的新旗艦，自v2.1.257起也是fable別名所指向的模型（除非ANTHROPIC_DEFAULT_FABLE_MODEL固定指定其他模型）；best現在代表「您可使用的最新Fable模型」。最低版本需求需要釐清：模型設定文件指出，別名是在v2.1.255切換，而模型頁面則寫明Fable 5.1「需要Claude Code v2.1.255或更新版本」。不過，2.1.253-256從未發布至npm，因此v2.1.257（9月1日）才是首個可安裝且包含此模型的版本。模型ID：claude-fable-5-1（Bedrock：anthropic.claude-fable-5-1）。它與Fable 5屬於相同層級，每token價格也相同：輸入$10/MTok、輸出$50/MTok、1M上下文、最大輸出128K、始終啟用自適應思考，且effort預設為high。其中有一項價格變更對長時間的代理工作階段格外重要：快取讀取費用為$0.25/MTok，是輸入價格的0.025倍（2.5%），標準費率則為10%；只有Fable 5.1與Mythos 5.1採用此費率，快取寫入仍維持標準費率（5分鐘為$12.50，1小時為$20）。可靠知識截止日期：2026年6月（訓練資料截止日期也是2026年6月），是所有現行Claude模型中最新的；Opus 5.5於2026年9月22日推出後，以相同的2026年6月截止日期並列，Sonnet 5.5也於9月28日加入。最早將於2027年9月1日退役。自v2.1.301起，當組織無法使用最新Fable模型時，fable與best會改用上一版Fable模型重試1次，而非直接報錯。²⁷¹

相較於Fable 5，有3項不相容變更：強制使用工具會傳回錯誤、較早的模型無法讀取其思考區塊，以及編輯先前回合會使思考區塊失效。另外新增5項功能：逐則訊息設定推理投入程度（beta）、僅限單一回合生效的系統訊息（beta）、工具呼叫之間的進度更新（display: "updates"，beta）、更便宜的快取讀取，以及內容來源資訊。Claude Mythos 5.1是規格完全相同的同一模型，僅透過Project Glasswing邀請使用。隨著此次推出，Fable 5移至文件中的舊版模型表格，與Opus 4.8/4.7/4.6/4.5及Sonnet 4.6/4.5並列。

版本說明中有一項閘道注意事項：在Claude應用程式的閘道工作階段中，fable與best目前仍會指向Fable 5，因為尚未設定支援5.1的閘道會拒絕該模型。因此，在這類工作階段中，請於/model明確選取Fable 5.1。請注意，v2.1.260之前的/model選擇器並未列出Fable 5.1，因此明確選取時必須輸入完整的/model claude-fable-5-1（請參閱下方推出初期的修正）。推出時各方案的預設模型為：高階方案使用Opus 5，Pro與Team Standard使用Sonnet 5；這項設定已由v2.1.280取代，自2026年9月22日起，所有方案皆預設使用Opus 5.5。^211237238221

Fable 5.1推出初期的修正（v2.1.260，9月3日）： 推出後的首個版本修正了4項問題。/model選擇器現在會為具備使用權限的組織顯示Fable 5.1；修正前，只有輸入完整的/model claude-fable-5-1才會接受此模型。Fable 5.1的提示快取現在也涵蓋附加在工具結果之後的上下文。先前，這些內容會在每個工具呼叫回合中，以未快取的輸入重新傳送，無形中抵銷了0.025倍快取讀取費率的成本效益，尤其影響這項優惠原本要服務的長時間代理工作階段。在工作階段中途變更/effort，也不再使提示快取失效。此外，model: fable代理現在會遵循ANTHROPIC_DEFAULT_FABLE_MODEL固定設定中的[1m]標記，不再無聲無息地以200K上下文視窗執行。²¹²

Claude Fable 5（2026年6月9日；自2026年9月1日起列為舊版）： 這是高於Opus的全新模型層級，也是Anthropic能力最強、最聰明的模型。在幾乎所有接受測試的基準評測中，它都達到最先進的水準，並能在數百萬token的上下文中維持連貫性。Fable 5是經過安全調整、可供一般用途使用的「Mythos級」前沿模型：它內建安全分類器，遇到網路安全、生化與模型蒸餾相關查詢時，會改用Opus 4.8處理（Claude Mythos 5則是向授權研究人員解除這些防護措施的同一模型）。自v2.1.170（2026年6月9日）起，即可在Claude Code中選用：先執行claude update，再執行/model fable（這是簡短別名，自v2.1.257起會指向Fable 5.1；目前若要選用Fable 5，請使用/model claude-fable-5）。它也逐步開放給各訂閱方案，並於2026年6月22日完成。模型ID：claude-fable-5。Fable 5預設提供1M上下文視窗，因此不需要[1m]後綴。自v2.1.173（2026年6月11日）起，claude-fable-5[1m]模型名稱會自動移除後綴，正規化為claude-fable-5（該後綴向來只對Opus/Sonnet有意義，這些模型須透過[1m]啟用1M上下文）；最大輸出為128K。輸入價格為$10/MTok，輸出為$50/MTok，約為Opus 4.8的2倍，因此建議留給高難度推理任務使用，日常編輯則無須動用。它採用與Opus 4.8相同的請求介面（僅支援自適應思考；已移除temperature/top_p/top_k與budget_tokens），但多了一項差異：明確傳入thinking: {type: "disabled"}會傳回400，因此若要停用思考，請完全省略thinking參數。²⁵⁷ 就Claude Code而言：Fable 5與Opus 5一樣，支援完整的推理強度範圍（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.5（v2.1.280；預設推理強度為medium，最困難的任務可使用/effort xhigh），而開箱即用的預設模型也不再依方案而異——除Microsoft Foundry外，所有由Anthropic營運的方案皆預設使用Opus 5.5；若追求最高能力，請明確透過/model fable選擇Fable級別——自v2.1.257起，這代表Fable 5.1。^{257197207238220221}

Opus 4.7（2026年4月16日）：上一代旗艦模型，仍完整提供使用。1M token上下文視窗採用標準定價，不另收長上下文費用。最大輸出為128K，僅支援適應性思考（已移除延伸思考），並新增xhigh推理強度，建議作為程式開發與代理工作負載的起始設定。¹⁴⁵可靠知識截止日期：2026年1月。訓練資料截止日期：2026年1月。模型ID：claude-opus-4-7。定價與Opus 4.6相同，每MTok為$5/$25；5分鐘快取寫入為$6.25，1小時快取寫入為$10，快取讀取則為每MTok $0.50。¹⁴⁴Opus 4.7在SWE-Bench上解決的正式環境任務數量為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）：²⁰⁷²²¹

自v2.1.280（2026年9月22日）起，預設模型不再依方案區分：所有由Anthropic營運的方案及第一方供應商皆預設使用Opus 5.5，唯一例外是Microsoft Foundry。過去最關鍵的問題——「我使用哪個方案？」——如今已不再影響答案。

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時，預設推理強度為high（先前為medium）；Opus 4.7則維持xhigh。4月23日的事後檢討記錄了3月4日至4月7日期間推理強度遭調降的情況，而這次調整恢復了模型的智慧表現。¹⁵²¹⁵³

Sonnet 5（2026年6月30日；上一代Sonnet級別）：自v2.1.197起，Anthropic API上的sonnet別名對應至此模型，直到v2.1.284才改為Sonnet 5.5。推出時，Anthropic將其定位為「速度與智慧的最佳組合」。Anthropic表示，其效能接近Opus 4.8，但價格更低，在代理推理、工具使用、程式開發及知識工作方面皆大幅優於Sonnet 4.6；同時，不理想行為的整體發生率較低，資安能力也遠弱於Opus模型（這項安全取捨使其得以推出，不受出口管制阻擋）。模型ID：claude-sonnet-5（不含日期的固定快照）。1M token上下文視窗，128K最大輸出（在Batches API中搭配output-300k-2026-03-24 beta標頭，最高可達300K），僅支援適應性思考。可靠知識截止日期：2026年1月。定價：每MTok輸入／輸出為$2/$10，目前已是標準牌價。Anthropic推出時宣布$2/$10為截至2026年8月31日的上市優惠價，之後則保留此價格：定價頁面指出，原訂9月1日調漲至$3/$15的計畫「不會實施」；v2.1.243也更新了/model選擇器及隨附的claude-api skill，將$2/$10標示為牌價，而非限時優惠。²⁴⁷這比Opus 5.5的$4/$20低50%（也比Opus 5的$5/$25低60%）。在Claude Code中，Sonnet 5的effort參數預設為high（如需變更，請明確設定）。使用/model claude-sonnet-5即可選取。¹⁸⁰²³⁰

v2.1.197（2026年6月30日）將Sonnet 5設為Claude Code的預設模型，適用於當時的新工作階段。它持續作為標準級別（Pro、Team Standard）的預設模型，直到2026年9月22日，v2.1.280將這些方案改為Opus。Sonnet 5如今已不是Claude Code中任何方案的預設模型；自v2.1.284起，Anthropic API上的/model sonnet也改為選取Sonnet 5.5。使用/model claude-sonnet-5或ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5可繼續使用Sonnet 5。請參閱上方的方案表格。^{181207220221228}

Sonnet 4.6（2026年2月17日，現已由Sonnet 5接替）：均衡型模型；取代Sonnet 4.5，成為claude.ai與Claude Cowork的預設模型。⁹³定價與Sonnet 4.5相同（每MTok為$3/$15）。代理搜尋效能有所提升，同時消耗更少tokens。支援延伸思考、適應性思考，以及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個輸入token及10K–50K個輸出token。以Haiku 5.5針對不超過100K個token的提示所採用的費率計算，每次工作階段約需$0.01–$0.05。若使用費率為$4/$20的Opus 5.5，同樣的工作階段需花費$0.40–$1.80，約為40倍（尚未計入提示快取折扣）。任務不需要Opus時，請使用Sonnet或Haiku。¹²²²

各模型的適用時機

Haiku：適合執行探索工作的subagents、簡單的檔案搜尋，以及快速問答。以不超過100K個token的提示費率計算，成本約為Opus 5.5的1/40（超過100K個token的提示則為1/8），回應速度也更快。非常適合不需要深入推理的背景任務。

Sonnet：重視成本時，日常開發的主力模型——自v2.1.284起，Anthropic API提供Sonnet 5.5，費率與Sonnet 5相同，為$2/$10²²⁸——但自v2.1.280將Pro及Team Standard改為使用Opus後，Sonnet已不再是任何方案的預設模型（原生支援1M上下文，標準牌價為每百萬token $2/$10；原訂9月1日的漲價已取消）。^181247207220這裡需要掌握的變化是：Sonnet現在是需要主動選用的模型，而選用的理由很直接——同樣提供1M上下文，每個token的成本只有Opus 5.5的一半。它能處理大多數程式開發任務，包括實作功能、修正錯誤、撰寫測試及程式碼審查。歷史紀錄：v2.1.197（2026年6月30日）長期以來被報導為將Sonnet 5設為所有方案的預設模型，本指南也曾如此記載。但模型設定文件依方案列出的資訊顯示，高階方案／API的預設模型自v2.1.154起對應至Opus 4.8，自v2.1.219起則對應至Opus 5。因此，「所有方案」實際上僅指標準層級，而v2.1.280連這項預設也取消了。直到2026年6月底，Sonnet系列的主力仍是Sonnet 4.6。^93147207221需要降低token成本、縮短回應延遲，或控制subagents的使用成本時，請選用Sonnet。

Opus：深入推理層級的模型——自v2.1.280起，opus別名會選用Claude Opus 5.5（每百萬token $4/$20、1M上下文，effort預設為medium），而且從該版本起，所有方案也都以Opus作為初始模型。因此，真正需要決定的是何時切換出去：進行架構決策、棘手的除錯、理解複雜系統、資安分析及長期自主代理工作時，請繼續使用Opus；若任務足夠例行，將token價格減半比額外推理能力更重要，則切換至/model sonnet。²²⁰²²¹（從v2.1.219到v2.1.278，opus別名對應的是費率為$5/$25的Opus 5。）¹⁹⁷本段其餘內容描述的是Opus 4.7於2026年4月16日推出時的情況，保留作為歷史紀錄。¹⁴⁴¹⁴⁷Opus 4.7在SWE-Bench上解決的正式環境任務數為Opus 4.6的3倍，CursorBench得分達70%（前者為58%），並在一項包含93個任務的內部程式開發基準測試中，將解決率提高13%。¹⁴⁴Claude Code在Opus 4.7上預設使用xhigh推理強度，可透過/effort調整（v2.1.111以上版本）。¹⁴⁶¹⁴⁷Max訂閱者透過Anthropic API使用Opus 4.7時，可使用自動模式，無須加上--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-5"
}

自訂模型選擇器（modelPicker，v2.1.242以上版本）：使用者設定檔或受管理設定檔可列出/model提供的模型，並指定排列順序與顯示名稱，讓選單不再只有內建選項。每個項目指定一個model（接受--model支援的任何寫法，包括Vertex及Bedrock ID），並可選填label與description；將replaceBuiltInOptions設為true，即可只顯示這些項目、預設選項，以及目前工作階段使用的模型。專案及本機設定中的這個設定鍵會被忽略，availableModels允許清單仍會篩選這些項目。Claude Code會移除無法提供的項目，將目前無法選取的項目顯示為灰色並說明原因；若沒有任何項目可用，則退回內建選項。²⁴⁶²⁴⁴

{
  "modelPicker": {
    "options": [
      { "model": "us.anthropic.claude-opus-4-8", "label": "Opus (production)" },
      {
        "model": "us.anthropic.claude-sonnet-4-6",
        "label": "Sonnet (production)",
        "description": "Day-to-day work"
      }
    ]
  }
}

專門針對subagents：

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

自v2.1.251起，CLAUDE_CODE_SUBAGENT_MODEL設定的是subagents的預設模型，不再覆寫所有模型選擇：代理定義中的model:以及每次建立代理時明確指定的模型，都具有更高的優先順序。²⁰⁶自v2.1.257起，可選擇啟用CLAUDE_CODE_SUBAGENT_MODEL_FORCE來恢復舊行為：它會將CLAUDE_CODE_SUBAGENT_MODEL指定的模型（若未設定，則使用主要對話的模型）套用至所有subagents，忽略每次建立時的模型選擇及代理定義中的model:。²¹¹

備援模型鏈（v2.1.166以上版本）：fallbackModel設定最多可指定3個備援模型，在主要模型負載過高或無法使用時依序嘗試。--fallback-model旗標先前只能在工作階段中途使用，現在也可在啟動互動式工作階段時套用。²⁵⁹

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

當API傳回非預期且不可重試的錯誤時，Claude Code現在也會先使用備援模型重試該回合1次，再回報失敗。如此一來，主要模型暫時發生問題時，仍可透過備援繼續處理，不至於直接中斷該回合。²⁵⁹自v2.1.286起，當Anthropic API拒絕使用預設設定或別名所對應的模型時，Claude Code會改用同層級的前一代模型重試1次，避免每個回合都失敗；因拒絕使用而觸發的重試，以及透過--fallback-model進行的重試，若改用的模型不支援快速模式，便會以標準速度執行。²³¹

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

擴充上下文

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

claude --model sonnet[1m]
claude --model opus[1m]           # 1M for a model that reaches it only through [1m], such as Opus 4.6

或在工作階段中：

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

何時需要後綴（2026年10月）：在Anthropic API上，Fable 5.1、Fable 5、Sonnet 5.5、Sonnet 5，以及Opus 4.7與後續版本（包括Opus 5.5），在所有方案中都使用1M上下文視窗，因此加上[1m]不會有任何影響。自v2.1.287起，Amazon Bedrock、Google Cloud的Agent Platform、Microsoft Foundry及Claude應用程式閘道也採用相同行為：Opus 4.7與後續版本以及Fable預設使用1M視窗，無須加上[1m]後綴；設定CLAUDE_CODE_DISABLE_1M_CONTEXT=1則會將其維持在200K。在v2.1.287之前，Opus 4.8與後續版本在這些供應商上預設使用200K，除非ANTHROPIC_DEFAULT_OPUS_MODEL中指定的模型ID帶有[1m]；10月1日擷取的Bedrock及Agent Platform文件頁面，仍將此後綴描述為在這些平台上取得1M上下文的方式。Sonnet 5在所有供應商上皆使用1M。對Opus 4.6及Sonnet 4.6而言，這個後綴仍有作用，因為只有它們的[1m]變體能達到1M。^223232233

Opus 4.7、Opus 4.6及Sonnet 4.6皆以標準價格提供完整的1M個token上下文視窗，不另收長上下文加價。¹⁴⁸900K個token的請求與9K個token的請求，採用相同的每token費率。提示快取及批次處理折扣在整個上下文視窗範圍內皆依標準費率適用。 能否使用[1m]變體取決於方案：Max、Team和Enterprise已包含具備1M上下文的Opus 4.6；所有訂閱方案（包括Max）若要使用具備1M上下文的Sonnet 4.6，都需要額外用量額度。²³³（自2026年3月13日發布的v2.1.75起，具備1M上下文的Opus成為Max、Team和Enterprise的預設模型。）¹¹⁷¹⁴⁷ API與隨用隨付使用者皆可依標準每token費率使用完整的1M上下文。¹⁴⁷

若要在模型選擇器中停用1M上下文變體，請設定CLAUDE_CODE_DISABLE_1M_CONTEXT=1。自v2.1.223起，此變數的適用範圍已有調整：它會透過自動壓縮，將所有原生具備1M視窗的模型限制在200K，而不再只適用於固定的已知變體清單。若自動壓縮實際上未將工作階段維持在200K內，啟動時便會顯示警告。如果您原本為了讓某個模型系列的成本更可預期而設定此變數，現在新推出的1M模型也會立即受到限制，不會再悄悄失效。同一版本也讓自動壓縮將使用無法辨識之模型ID的工作階段維持在推定的上下文視窗內，避免超出範圍；若閘道註冊的自訂ID實際具備更大的視窗，可設定CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1恢復舊有行為。²⁰⁰自v2.1.287起，Bedrock、Vertex、Foundry及Claude apps閘道上的Opus 4.7及後續版本與Fable已預設使用1M上下文；若要將它們維持在200K，也需使用此變數。²³²

自v2.1.247起，Sonnet 5的預設自動壓縮視窗涵蓋完整的1M上下文：使用1M視窗的工作階段，現在約在967K tokens時觸發自動壓縮，而非原先的約934K。²⁴¹ v2.1.260將接近上限才自動壓縮的行為擴展至其餘1M模型：Opus與Fable工作階段現在也會在接近1M-token上限時才壓縮，而極大型上下文的復原壓縮也不再於10分鐘後逾時。²¹²

自訂基底URL也能使用1M視窗（v2.1.285）。透過自訂ANTHROPIC_BASE_URL執行的工作階段，現在會使用模型本身具備的1M上下文視窗（Opus 4.7及後續版本、Sonnet 5及後續版本、Fable）。若您的閘道上限為200K，請執行/autocompact 200k。²²⁹²³³

自v2.1.271起，--resume會保留[1m]視窗：恢復的工作階段若使用與設定中預設模型不同的模型系列，不再遺失[1m]後綴。²¹⁶

v2.1.273修正了上下文用量計與自動壓縮將advisor工具回合計為實際上下文大小約2倍的問題——此問題原本會導致自動壓縮在實際視窗用量約達一半時就觸發。²¹⁷

查看目前模型

> /status

此命令會顯示目前模型、帳號資訊、已套用的設定，以及其他工作階段狀態。

模型選擇器標籤（v2.1.51+）：對於固定版本，/model選擇器現在會顯示易讀的標籤（例如「Sonnet 4.6」），而非原始模型ID；有較新版本時，也會提供升級提示。⁹⁸ v2.1.219修正了合併後的Opus列僅顯示「Opus」、未顯示「Opus（1M上下文）」的問題，並將新版本的醒目標示限縮至最新模型的名稱，讓標示準確指出實際推出的模型，而非清單中任意一段。¹⁹⁶ v2.1.283在Opus已具備1M上下文視窗的情況下，移除了Opus列與預設模型名稱中的「（1M上下文）」；視窗大小本身並未改變。²²⁶

快速模式（v2.1.36+）

快速模式能讓同一個模型大幅加快輸出速度，不會切換至較便宜的模型。可在工作階段中使用/fast切換。⁸⁶

> /fast            # Toggle fast mode on/off

適用模型（截至v2.1.280）：快速模式適用於Claude Opus 5.5、Opus 5及Opus 4.8；自v2.1.280起，Opus 5.5成為快速模式的預設模型（自v2.1.219起的預設模型原為Opus 5）。v2.1.219已移除Opus 4.7的快速模式支援，而Sonnet、Haiku與Fable從未提供此功能。此功能仍為研究預覽版，僅在Claude API（包括Claude Managed Agents）上提供，不支援Amazon Bedrock、Google Cloud、Microsoft Foundry或Claude Platform on AWS。使用資格受到限制：請聯絡您的客戶經理或加入候補名單。^196198223

遠端工作階段（v2.1.271）：快速模式現已支援Claude Code Remote工作階段，包括雲端工作階段與自行託管的執行器。系統會套用主機的快速模式設定，也可直接在工作階段中輸入/fast；兩種方式都必須在組織允許快速模式時才有效。同一版本也修正了/fast off：當組織停用快速模式時，此命令現在會關閉快速模式，不再回覆「快速模式無法使用」。²¹⁶

定價（快速模式）：^198222223

Opus 4.7的陷阱（v2.1.219）。不支援快速模式的模型，行為並不一致。現在，對claude-opus-4-7傳送含有speed: "fast"的請求會傳回錯誤，不會自動退回標準速度且不另行通知。Opus 4.6則是需要特別留意的例外：它接受speed: "fast"，但仍以標準速度執行、依標準費率計費，並回報usage.speed: "standard"。如果您的執行框架固定使用4.7，且仰賴快速模式請求自動降回標準模式，這些請求現在會直接失敗；請將固定版本改為Opus 5.5、Opus 5或Opus 4.8。¹⁹⁸

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

不適合使用快速模式的情況： - 長時間執行的代理任務（整個執行過程的費用仍會加倍） - 背景subagents工作（沒有人在等待輸出） - 需要控制預算的工作階段

快速模式包含完整的1M上下文視窗（v2.1.50+）。整個上下文皆套用固定的計價倍數，包括輸入超過200K tokens的請求，不會另收長上下文附加費；此倍數也會與提示快取及資料駐留的計價倍數疊加。⁹⁶¹⁹⁸

運作注意事項。快速模式有獨立的速率限制，與標準Opus限制分開計算；超過限制時會傳回429與retry-after（anthropic-fast-*-tokens-*回應標頭會回報剩餘額度）。在快速與標準模式之間切換會使提示快取失效：不同速度的請求不會共用已快取的前綴，因此在工作階段中途切換/fast會導致快取未命中。快速模式無法搭配Batch API或Priority Tier承諾用量方案使用。¹⁹⁸

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

Advisor工具（實驗性）

Advisor工具讓Claude能在任務的關鍵時刻諮詢另一個通常能力更強的模型，例如確定執行方案前、錯誤反覆出現時，或宣告工作完成前。Advisor以伺服器工具的形式，在Anthropic基礎架構的伺服器端執行。它會接收完整對話，包括每一次工具呼叫與結果，再傳回建議，供Claude採用後繼續工作。Claude會自行決定何時呼叫；您也能在提示中要求諮詢，但沒有設定可限制呼叫次數或強制呼叫。此工具仍屬實驗性功能，透過Anthropic API提供給訂閱帳號與依API計費的帳號，並於v2.1.300開始支援Claude Platform on AWS（文件頁面仍將該平台列為不支援）。透過閘道使用時，請求必須完整送達Anthropic API；此功能也需要擷取功能旗標，因此設定DISABLE_TELEMETRY之類的變數會使其維持停用狀態。²⁶⁹²⁷⁰ 啟用方式。共有3種方式：在工作階段中使用/advisor <model>，將選擇儲存至使用者設定的advisorModel（單獨輸入/advisor會在終端機開啟選擇器；在-p、SDK、桌面版與Remote Control工作階段中，則會顯示目前的顧問模型。這些工作階段自v2.1.260起支援文字形式；/advisor off可將其關閉）；在設定檔中加入"advisorModel": "opus"；或使用claude --advisor <model>，僅套用於單一工作階段。這個旗標未列於--help，優先順序高於設定檔；若模型配對無效，程式會在啟動時結束。可使用fable、opus和sonnet別名，或完整的模型ID。CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1會移除指令、忽略設定，並讓旗標失去作用。²⁷⁰

配對、費用與顯示資訊。顧問模型的等級必須等於或高於主要模型：Opus 4.7與4.8接受Fable、Opus 4.7以上版本，以及Sonnet 5.5（自v2.1.287起）；Sonnet 5.5接受Fable、Opus 5以上版本，以及Sonnet 5.5；Opus 5與5.5接受Fable和Opus 5以上版本；Fable 5.1僅接受Fable 5.1；Haiku 4.5可呼叫顧問模型，但無法擔任顧問。若顧問模型等級低於主要模型，系統不會掛載，並會顯示通知；若遭API拒絕，則會在後續對話中停用，且不另行通知。Subagents會繼承顧問模型，並接受相同的配對檢查，也會遵循availableModels允許清單。每次呼叫皆依顧問模型的輸入與輸出費率計費，或計入方案用量限制；但若方案中的Fable是以用量額度計費，Fable顧問模型也會如此計費，前提是已透過/model fable完成一次性同意。切換顧問模型的開關狀態會保留主要模型的提示快取；顧問模型本身讀取對話的內容則一律不會快取。對話紀錄中的Advising列會顯示已檢閱、已婉拒或無法使用，按下Ctrl+O即可查看建議。Mods會在turn.step上以serverToolUses看到顧問模型呼叫（v2.1.290）。²⁷⁰

推理投入程度控制（v2.1.111+，Opus 4.7）

Opus 4.7新增推理投入程度調整功能，可在速度與智慧表現之間取捨。在工作階段中使用/effort：

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

依模型儲存（v2.1.251+）：/effort現在會為各模型分別儲存預設推理投入等級，因此切換模型時，每個模型都會保留自己的設定。習慣在Opus上使用的xhigh，不會再跟著套用到Haiku（CHANGELOG：「已將/effort改為依模型儲存預設推理投入等級，因此切換模型時，每個模型都會保留自己的設定」）。max僅適用於單一工作階段的例外規則仍然有效。²⁰⁶ v2.1.284滑桿按鍵：effortSlider:decreaseEffort、increaseEffort和toggleUltracode按鍵繫結動作，讓您能在keybindings.json中重新指定滑桿的方向鍵與Tab鍵。²²⁸ v2.1.257改進兩項調整控制：/effort接受以s選取僅適用於本次工作階段的設定，與/model的慣例一致；--effort旗標現在也僅限本次工作階段生效。它只會在該工作階段解除新模型維持預設推理投入等級的限制，不會永久解除（CLI參考文件指出，它會「覆寫」預設值，「僅適用於本次工作階段，且不會持續保存」）。²¹¹²³⁹

Max方案的自動模式（v2.1.111+）

在所有方案與供應商上，自動模式都是互動式終端機與VS Code工作階段內建的初始權限模式（v2.1.283–284）。自v2.1.285起，透過第三方供應商或關閉遙測時執行的claude -p與Python Agent SDK工作階段也曾採用此預設值，直到v2.1.302撤回這項變更；Pro、Max和Team則自2026年8月14日起便預設使用自動模式（於8月7日公布）。如需公告中的研究數據、停用方式，以及仍以手動模式啟動的工作階段，請參閱權限模式。^{203226227228229}

獨立的分類模型會在每項動作執行前進行審查，確認動作符合您的意圖且安全；自v2.1.210起，這個模型為Claude Sonnet 5。¹⁸⁷ 使用--permission-mode auto即可在自動模式下啟動工作階段；v2.1.111已移除舊的--enable-auto-mode旗標。

支援範圍的擴展歷程：

• 選擇退出：CLAUDE_CODE_AUTO_MODE_SERVER=0會保留本機分類器，其請求會計入用量；設為1則選擇加入。在v2.1.281之前，直接連線至Anthropic API時不會讀取此變數；v2.1.281起也會在這種連線下套用，自動模式計費文件現已註明，直接連線時需要v2.1.281或更新版本。²²⁴²²⁷文件將此變數稱為暫時性變數。若未設定此變數，設定CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1也會停止伺服器端檢查。
• 伺服器端檢查無法用於工作階段時：最常見的原因是閘道或代理伺服器移除了請求中的safeguards欄位、刪除了回應中的safeguard_results，或改寫了工具使用ID。Claude Code會顯示一次性通知（「此工作階段不符合資格」），若能辨識閘道，也會指出其名稱，並在該工作階段剩餘期間改用自身會計費的分類器請求。在-p模式下，通知會輸出至stderr，stream-json輸出則會發出system警告。Pro、Max和Team工作階段不會看到此通知。閘道端的修正方式是原封不動地傳遞請求欄位與回應鍵值。
• 檢查工作階段：/status會顯示自動模式伺服器列。當伺服器端檢查負責判定工作階段中的動作時，該列顯示Enabled；一旦退回備援機制，則顯示Disabled。²¹⁹

自動模式並非安全邊界。以下大多數措施都是在強化分類器，而分類器並不是沙箱。2026年8月26日，提示注入研究員Johann Rehberger公開了一條可在自動模式下攻擊Claude Code Opus 5的有效攻擊鏈，並回報在小樣本測試中的攻擊成功率為60–80%：主要攻擊鏈會啟動隔離的python3子程序，5次執行中有3次成功；另一變體的酬載會啟動無介面的claude -p執行個體，其兩種設定分別在5次執行中成功3次與4次。他也提醒，這些只是小樣本，並非普遍適用的攻擊成功率測量結果。²¹⁰這條攻擊鏈值得理解，因為每個步驟單獨看來都合情合理：伺服器以HTTP 415回應WebFetch，讓代理改用curl；下載的封存檔解壓縮至暫存目錄，其中包含一份資訊清單、7筆以Base85/zlib編碼的資料記錄、一個原生二進位檔，以及一個struct.py；Claude拒絕執行不受信任的二進位檔，接著自行撰寫Python解碼器，並在該目錄內執行；解碼器匯入base64，base64匯入struct，而Python會優先解析到攻擊者的struct.py。整個過程沒有任何明顯惡意的指令；注入只需要讓遭到入侵的執行路徑成為完成任務最合理的方式。Rehberger也回報，在幾次執行中，Claude察覺遭到入侵後曾嘗試終止惡意軟體程序，但自動模式卻拒絕了清理命令。²¹⁰他將整項發現與Anthropic曾用於行銷的一項數據對照：一項委託第三方進行的評估，在72種情境中各執行10次測試，回報Opus 5在自動模式下的提示注入攻擊成功率為0.00%。他的攻擊鏈並未納入該測試集，因此0.00%的基準測試結果與一條有效的程式碼執行攻擊鏈可以同時成立；在他看來，這兩種訊息彼此並不相容。²¹⁰也請留意攻擊的分類：Simon Willison在8月30日的更新中認同一位讀者的觀點，指出這並非典型的提示注入，因為模型從未讀取並遵循攻擊者的指令，而是一種混淆環境攻擊。²¹⁰

Anthropic將這份通報以Informative（資訊性）結案，認定其行為符合設計。Rehberger轉述的立場，正是設計防護時應採用的前提：自動模式是盡力而為的分類器，並非安全保證；精心策劃、由個別無害步驟組成的注入攻擊鏈，不在分類器預期能攔截的範圍內；真正能限制影響範圍的邊界，是作業系統層級的隔離與網路對外連線控管。²¹⁰這並不否定下述強化措施，而是理解這些措施的正確框架。自動模式能減少需要回應的提示，並封鎖文件列出的破壞性操作，但無法讓處理不受信任輸入的工作階段變得安全。若工作階段會接觸可能受攻擊者影響的內容，例如擷取的網頁、下載的封存檔、議題文字或第三方MCP伺服器，真正能限制損害的控制措施都在模型之外：容器或VM、受限的網路對外連線、監控代理實際執行的動作，以及不存放您不願外洩的SSH金鑰與雲端憑證的家目錄。自動模式核准某項動作，並不能證明該動作安全。

自訂規則，同時保留預設規則（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
    ]
  }
}

從/permissions編輯分類器規則（v2.1.246）。執行/permissions並開啟自動模式分頁；只有工作階段可使用自動模式時，才會顯示此分頁。它會列出分類器讀取的各個設定範圍中的allow、soft_deny、hard_deny與environment項目，並顯示每個區段的內建規則是否生效。來自受管理設定或--settings的項目為唯讀，所有變更都會儲存至~/.claude/settings.json。在區段中新增第一條規則時，也會插入"$defaults"，讓內建規則持續生效。各區段的內建規則可分別開關，但必須先加入至少一條自訂規則，才能關閉該區段的內建規則；environment則會在編輯器中以單一文件開啟。²⁴⁵²⁴³

啟用提示中的「不再詢問」選項（v2.1.118+）。自動模式的啟用提示現已提供「不再詢問」選項，讓經常使用的使用者無須透過指令碼設定旗標，就能停用說明提示。¹⁵²

破壞性命令防護措施（v2.1.183）。自動模式現在會強制封鎖一組不可逆的命令，除非您在工作階段中明確要求執行：未要求捨棄本機工作成果時，封鎖破壞性git操作（git reset --hard、git checkout -- .、git clean -fd、git stash drop）；若提交並非由代理在本次工作階段建立，則封鎖git commit --amend；除非已指明特定堆疊，否則封鎖基礎設施拆除操作（terraform destroy、pulumi destroy、cdk destroy）。這能針對會悄悄遺失工作成果或拆除環境的操作，縮小分類器誤判可能造成的損害範圍。代理仍可執行這些操作，但必須有您的明確指示，不能自行決定。¹⁷⁴

對每個shell命令進行分類（v2.1.193）。預設情況下，自動模式分類器只會審查符合任意程式碼執行模式的shell命令；一般命令會略過分類器。新的autoMode.classifyAllShell設定會改為將所有Bash/PowerShell命令送交分類器，以些許延遲換取更嚴密的防護，適合希望審查每次shell呼叫的情況。同一版本也會在對話記錄、拒絕操作的浮動通知，以及/permissions的近期拒絕記錄中顯示自動模式的拒絕原因，讓遭到封鎖的命令都有原因可查。¹⁷⁹

另外3項強化規則（v2.1.205）。自動模式現在會封鎖對工作階段對話記錄檔的竄改，禁止代理動到稽核軌跡本身；當rm -rf的目標是無法從上下文解析的變數時，會先詢問，防止在$DIR未知的情況下執行rm -rf $DIR這類意外；此外，背景任務通知現在會明確註明沒有任何人類輸入，避免對話記錄中偽造的「使用者已核准」文字被冒充為有效核准並據此執行。¹⁸³第3項是值得牢記的提示注入防禦原則：核准必須透過核准管道傳入，而代理執行框架現已明確說明這項前提。 命令替換也藏不住災難性操作（v2.1.208）。 rm -rf ~ 等災難性刪除操作，即使藏在 $(...)、反引號或程序替換（<(...)）中，現在也會觸發確認提示，即使在 --dangerously-skip-permissions 與自動模式下也一樣。將破壞性命令包在替換語法中，已無法繞過安全防護。¹⁸⁶

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

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

減少對話框，審查依然嚴謹（v2.1.218）。 過去會以權限對話框中斷自動模式的 3 項檢查——危險的 rm、背景執行的 & 與可疑的 Windows 路徑——現在改由自動模式分類器判定，不再跳出對話框。安全審查仍會執行，但不必每次觸發檢查都請您介入。同一版本也將此行為擴展至搭配自動模式的計畫模式：靜態分析器無法確認為唯讀的 Bash 命令，不再回退至對話框提示，而是交由分類器判定。¹⁹⁵

隔離逃逸規則（v2.1.257）。 分類器的「永不自動核准」清單新增「隔離逃逸」（Containment Escape）規則：從雲端中繼資料擷取憑證、規避對外網路傳輸限制，以及跨租戶存取，除非環境已標示為預期行為，否則不再自動核准。請依前述提醒理解這項變更：這是分類器持續強化的一環，新增了另一項有文件記載的拒絕類別，並未改變自動模式的本質。²¹¹

讀取工作目錄以外的檔案時，先提示一次（v2.1.257）。 自動模式現在會在工作階段首次讀取工作目錄以外的檔案前詢問一次；自 v2.1.284 起，提示也提供是，但下次再次詢問選項。²²⁸ 搭配使用的 permissions.blockReadsOutsideWorkingDirectories 設定則會將提示改為拒絕，直接封鎖這類讀取。²¹¹ v2.1.273 將這兩種行為擴展至檢查器無法掌握的情況：遇到無法完整分析的 Bash 命令時，會顯示提示，不再略過檢查；啟用封鎖設定後，由儲存庫設定指定的記憶目錄，也不再載入提示內容、用於記憶回溯、建立索引，或供記憶擷取使用。²¹⁷

圖表繪製服務的 URL 視同上傳（v2.1.261）。 將內容封裝在公開圖表繪製服務 URL 中的連結，例如 mermaid.live 這類將資料直接編碼進 URL 的連結，除非是您要求的，否則不再自動核准。分類器會將這類連結視為上傳：封裝的資料透過 URL 本身傳遞，頁面開啟後，繪圖網站自己的指令碼就能讀取。mermaid.live 這類連結將承載資料放在 URL 片段中；瀏覽器會將該片段交給頁面的 JavaScript，而非隨網路請求送出。仍應依前述提醒理解：這是持續強化的分類器封堵了另一條資料外洩管道，並非建立新的邊界。²¹⁴

分類器的兩種失敗情況都有了停止條件（v2.1.280）。 在此版本之前，若安全檢查未傳回可用的判定，自動模式並無應對方式。從操作者的角度來看，這兩個缺口呈現相同症狀：回合持續空轉，為永遠不會獲准的動作消耗 token。v2.1.280 為這兩種情況各自加入了終止狀態。

伺服器審查涵蓋更多命令（v2.1.281）。 當分類器審查在伺服器端執行時，唯讀及沙箱內的 shell 命令現在也必須等待審查；若被標記為有問題，就會遭到封鎖。拒絕訊息也有所調整，讓 Claude 將拒絕理解為針對該操作結果，而不只是針對那條特定命令。在新程序中繼續工作階段後，分類器可重用先前的提示快取，無須重新寫入。此外，/insights 新增自動模式建議，可估算近期工作階段中有多少權限提示原本能由自動模式處理。²²⁴

無人值守的工作階段不再卡在 rm 提示（v2.1.281）。 在自動模式與 --dangerously-skip-permissions 下，危險 rm 操作的提示現在會等待 2 分鐘；若未獲回應，就會拒絕命令並提供改寫提示，讓無人值守的工作階段繼續執行。設定 CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT=1 可關閉逾時機制。若遞迴 rm 的目標完全來自命令替換的輸出，例如 rm -rf "$(pwd)"，過去在這兩種模式下都會直接執行，不顯示提示；現在即使符合 Bash 允許規則，也會先詢問，除非設定了 CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT=1。危險 rm 檢查也會標記以下刪除目標：shell 變數後接頂層目錄名稱、由工作目錄衍生的變數，或僅含反斜線的目標。²²⁴ 自 v2.1.299 起，未執行 rm 的 shell -c 指令碼不再觸發提示；若 rm 是在 Claude Code 無法讀取的指令碼內於執行階段組成，則只有設定 CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT=1 時才會顯示提示。²⁶⁷

行內 ! shell 不再交由分類器審查；subagents 的回傳則納入審查（v2.1.271）。 這是兩項機制調整，並未新增拒絕類別。skills 或斜線命令中的行內 ! shell 命令，現在遵循預設模式的權限規則，不再交由分類器判定；若沒有規則能決定如何處理，該命令就會以經過審查的工具呼叫執行。此外，subagents 現在會透過專用的回傳呼叫，向呼叫端回報結果，並由安全分類器審查該呼叫，不再事後審查最後一則訊息。也就是說，檢查點從交接之後移到了交接當下。²¹⁶

v2.1.309 與 v2.1.310 的新功能

Claude Code 2.1.309 於 2026年10月22日推出（npm：UTC 20:34；GitHub 版本發布：UTC 22:18，共 79 項），2.1.310 於 10月23日推出（npm：UTC 21:20；GitHub 版本發布：UTC 23:39，共 26 項），兩者皆與權威版本的 CHANGELOG 完全一致。npm 的 latest 與 next 均為 2.1.310，stable 則從 2.1.292 更新至 2.1.308；後者的完整版本說明只有「錯誤修正與可靠性改善」一句。2.1.303（10月18日）也使用同一句說明。2.1.302 至 2.1.310 之間沒有略過任何版本。²⁷⁴

沙箱與權限修正（v2.1.309）。 macOS 與 Linux 上的沙箱 Bash 命令，不再於每次執行命令前，在沙箱外執行 shell 啟動檔案；macOS 的 denyWrite 萬用字元模式，若透過符號連結存取模式中的資料夾，會套用至路徑的實際位置；沙箱命令與自動接受的編輯，不再能修改透過 --mcp-config 傳入的 MCP 設定檔；Linux 的寫入拒絕限制，不再因背景命令持續執行至工作階段結束之後而解除；對於設定中排除於沙箱之外的命令，若沙箱已啟用卻無法運作，現在寫入沙箱允許寫入清單中的路徑前會先詢問，並拒絕在該情況下回退至無沙箱執行。Bash 權限檢查不再信任由重新導向可能失敗的命令所設定的變數；若 git 前有經過包裝或帶有前綴的 cd，會先顯示提示；也會將 Edit(path) 拒絕規則套用至子 shell 內的 Bash 重新導向。worktree 隔離防護會拒絕更多帶有地區設定前綴的命令，以及 zsh 算術命令；設定檔儲存區的寫入保護，也會套用至透過符號連結存取的設定目錄。sed -i 現在會顯示標準 Bash 提示，並依原命令執行，不再模擬檔案編輯預覽；與其他 Bash 編輯一樣，也不再能透過 /rewind 還原。請參閱沙箱模式。²⁷⁴ 信任、worktrees與skills（v2.1.309）。 claude ultrareview要求信任工作區：在終端機中會詢問是否信任，其他情況則拒絕執行；指令碼可傳入不接受值的--trust-workspace，或設定CLAUDE_CODE_DISABLE_ULTRAREVIEW_TRUST_CHECK=1。在桌面應用程式與VS Code的略過權限模式中，危險的rm和rmdir操作原本會觸發提示，現在會立即拒絕命令並提供改寫建議，讓無人值守的工作階段得以繼續執行。建立與重用worktree時不再按需擷取git物件（搭配Bash沙箱的部分複製會先擷取物件），worktrees與分支切換也會忽略git replace參照。巢狀CLAUDE.md若超過大小限制，現在只會載入開頭內容，避免工作階段在讀取其所屬目錄下的檔案後反覆壓縮。若--add-dir資料夾中的skill名稱已被其他skill使用，會以<folder>:<name>提供；/verify與/code-review也能找到巢狀套件自己的skill。分割窗格中的代理程式隊友會繼承領導者的工具拒絕規則與--tools規則，而/rewind會列出透過/code-review --fix、subagent或shell命令變更檢查點檔案的回合。²⁷⁴

v2.1.310。 Monitor工具與plugin監控器可在Bedrock、Vertex和Foundry上運作，也適用於停用遙測或非必要流量的情況；這些環境現在也會阻擋長時間的前景休眠。若閘道後方或相容伺服器拒絕effort-2025-11-24 beta值或對話中途的系統訊息，系統會移除這些內容後重試請求。發生「提示過長」錯誤後，壓縮不再保留過多base64或SVG等高密度文字；當cleanupPeriodDays設為很大的值時，背景清理不再刪除貼上圖片等近期檔案；檔案讀取提示會顯示符號連結的目標位置；自動模式在首次讀取工作目錄以外的位置前，會在提示中說明何時阻擋這些讀取會導致shell命令要求權限；非互動式工作階段在壓縮超大型對話記錄時使用的記憶體更少；在Ubuntu上，/sandbox與啟動警告會明確指出AppArmor對使用者命名空間的限制，以及解除方式；mod的Image可在啟用allow-passthrough與focus-events的tmux中繪製，也能在使用全螢幕繪製的kitty、Ghostty與iTerm2 3.5+中顯示；若非互動式工作階段中的MCP工具呼叫逾時，且伺服器的資訊徵詢尚未獲得回覆，系統會告知Claude不要重複呼叫。雲端工作階段與Remote Control權限也已納入Enterprise自訂角色。²⁷⁴

v2.1.307的新功能

Claude Code 2.1.307於2026年10月21日發布（npm為20:47 UTC；GitHub版本為22:17 UTC；共43個項目，與官方CHANGELOG完全一致），接續於2.1.306（10月21日02:28 UTC）之後。2.1.306包含2項修正：在雲端工作階段中執行claude -p時，即使缺少該工作階段的環境變數，也不再回報「尚未登入」；在具有大量MCP工具的工作階段中，API錯誤也不再被「提示過長」取代，並觸發不必要的壓縮。2.1.308（10月22日04:19 UTC）是僅有一行說明的可靠性更新版本，並成為stable版本。²⁷⁴

遙測與API skill。 每當工具呼叫遭權限規則、自動模式、安全檢查、hook或沙箱阻擋、要求確認或退回時，都會觸發claude_code.safety_event OpenTelemetry事件（請參閱環境變數參考）。/claude-api api-version會將Claude API程式碼遷移至API版本2026-10-21；/claude-api managed-agents-secure（v2.1.304）則會比對Managed Agents代理程式的設定與Anthropic發布的安全指南，不會進行任何變更。此skill現在會以multiagent_20261001建立Managed Agents subagent團隊，並預設啟用動態工作流程（v2.1.309）。²⁷⁴²⁷⁵

修正與行為變更。 CLAUDE_CODE_DISABLE_1M_CONTEXT搭配帶有[1m]後綴的別名（例如opus[1m]）時，不再產生找不到模型的錯誤；透過自訂ANTHROPIC_BASE_URL閘道或在Foundry上運作時，不再傳送prompt-caching-scope beta標頭；因macOS登入鑰匙圈鎖定而無法連線的MCP伺服器，現在會說明原因，解鎖後再次執行即可連線，不必重新登入；HTTP MCP工具呼叫不再因連線中途關閉而傳送2次，現在只會重試唯讀或具冪等性的工具；已修正讀取大量PDF頁面或圖片的回合中出現的「自動壓縮反覆執行」錯誤；無法剖析的工具呼叫最多會重試2次，之後才以錯誤結束回合；同時啟動的fork subagents會各自獲知哪次啟動屬於自己；/permissions > 最近遭拒的項目會顯示遭拒的shell命令；axScreenReader設定與設定檔env區塊中的CLAUDE_AX_SCREEN_READER，僅在來自使用者、受管理或--settings設定時才會生效（自2.1.305起）；自架執行器的checkout hooks預設會在30分鐘後停止（--checkout-hook-timeout-min，設為0表示不限時間）。Code Review新增@claude review stop（也可使用off與pause），用來結束@claude review always訂閱。²⁷⁴

v2.1.304與v2.1.305的新功能

Claude Code 2.1.304於2026年10月19日發布（npm為19:47 UTC；GitHub版本為21:34 UTC；共76個項目），2.1.305則於10月20日發布（npm為19:29 UTC；GitHub版本為20:46 UTC；共38個項目），兩者皆與官方CHANGELOG完全一致；2.1.303（10月18日）是僅有一行說明的可靠性更新版本。²⁷⁴

自動模式設定與/usage修正。 /auto-mode-setup（v2.1.304）提供引導式設定流程，會讀取專案與近期工作階段，草擬autoMode.environment項目；也適用於Bedrock、Vertex、Foundry、Claude應用程式閘道，以及停用遙測的工作階段。自動模式設定文件已涵蓋此功能。/usage（v2.1.305）會將每則警告轉為一行修正建議，並指出來源，按下f即可套用修正；這些建議也會顯示於VS Code與/doctor。/usage也會說明用量資料的速率限制何時解除。在Pro與Max方案中，若恢復閒置對話將占用5小時用量上限中相當程度的額度，現在會顯示警告，並提供另開新對話的選項（v2.1.304）。請參閱Max方案的自動模式，以及斜線命令中的/usage項目。²⁷⁴²⁷⁵

設定與環境。 sandbox.allowNestedUserNamespaces（v2.1.305）允許Linux上的沙箱命令建立使用者命名空間（Chromium、無根權限的podman），代價是這些命令能繞過沙箱的檔案保護。CLAUDE_CODE_RETRY_WATCHDOG_USAGE_LIMIT_RECHECK_MS（v2.1.305）讓無人值守重試模式能偵測到在重設時間之前提前解除的用量限制。CLAUDE_CODE_AUTO_COMPACT_WINDOW與--autocompact一樣接受k與M後綴，並會對超出範圍的值發出警告（先前200k會在沒有提示的情況下設定為100K視窗）。allowedMcpServers不再篩除僅在env中使用${VAR}的managed-mcp.json stdio伺服器，因此先前未列入允許清單的這類伺服器會在升級後載入（可使用deniedMcpServers維持停用）。透過自訂ANTHROPIC_BASE_URL連線時，工具搜尋預設啟用（v2.1.304）；v2.1.305也修正了2.1.304的回歸問題：在Vertex、Bedrock及其他端點拒絕工具搜尋的供應商上，每個請求原本都會失敗，現在Claude Code會停用工具搜尋後重試。在allowManagedPermissionRulesOnly下，由Claude Desktop依路徑掛載的plugins會失去其allowed-tools。截至10月23日，除了工具搜尋的預設行為之外，上述內容皆已納入文件。²⁷⁴²⁷⁵

Mods、skills與hooks。 mod的tool.check事件帶有e.isReadOnly，回應可設定decider: "person"，使核准只能透過權限對話框或主機端回呼進行；settings.read hooks會接收各層設定，並改寫合併後的設定；對話記錄會以一行文字指出哪個plugin略過了您的hook；停駐窗格的寬度則維持在終端機寬度的45%以內（v2.1.305）。壓縮完成後會再次將skill清單傳送給Claude，而/reload-skills只會傳送新增或變更的skills；同一來源的skills在每個工作階段中最多可註冊1,024個hooks，且比對器字元總數不得超過16,384；某個skill的once hook不再移除另一個skill中相同的hook。恢復工作流程時，已完成的pipeline()與parallel()代理程式會直接取用該次執行日誌中的結果，不再重新執行（v2.1.305）；自行調整間隔的/loop在達到1小時上限時，不再恰好於提示快取過期後喚醒；當HEAD處於分離狀態或位於其他分支時，claude --worktree不再於結束時未經詢問就移除worktree及其分支；對已掛載磁碟或其最上層資料夾執行rm -r會觸發安全提示；Code Review則新增審查層級（快速、標準、深入），並提供審查GitHub組織中所有儲存庫的選項。Opus 5.5的/fast對話框已移除「（研究預覽）」標籤。²⁷⁴

v2.1.302的新功能

Claude Code 2.1.302於2026年10月16日發布：npm於UTC 16:48發布，GitHub版本隨後於UTC 20:53發布，包含與正式CHANGELOG相同的63項更新。npm的latest與next皆指向此版本，stable則維持在2.1.292。此版本接續2.1.301（10月15日，51項更新），並未跳過任何版本。10月17日擷取的文件已收錄2.1.301的vim移動指令與VS Code數學式顯示功能，但尚未收錄以下項目，因此各項皆以CHANGELOG為依據。²⁷¹²⁷²

claude -p與SDK再次預設以手動模式啟動。 未指定權限模式的claude -p或Agent SDK工作階段，在使用第三方供應商、關閉遙測或全新安裝的情況下，現在會以default（手動）模式啟動；指定--permission-mode auto則仍使用自動模式。這項變更撤回了v2.1.285讓這些工作階段以自動模式啟動的規則。互動式終端機與VS Code工作階段則維持原樣：所有方案與供應商皆使用自動模式。權限模式文件仍描述v2.1.285的行為。請參閱權限模式。²⁷¹²⁷²

Fork subagents與背景執行預設值。 Fork subagents（subagent_type: "fork"）現在於claude -p、Agent SDK、桌面應用程式與VS Code中預設啟用，與原本的終端機行為一致；設定CLAUDE_CODE_FORK_SUBAGENT=0可停用，claude mcp serve則一律不提供此功能。桌面應用程式與VS Code現在會與終端機一樣，一律在背景執行主對話的subagents，不再由Claude決定。至於subagent本身發出的Agent呼叫，在claude -p、SDK、桌面應用程式與VS Code中則預設於前景執行。提示詞與代理程式hooks現在針對同一事件最多同時執行12個，其餘依序等待。環境變數與subagents文件仍寫著fork模式僅在互動式工作階段啟用。請參閱什麼是Subagents？。²⁷¹²⁷²

自動模式與壓縮。 CLAUDE_CODE_AUTO_MODE_MODEL可指定用戶端自動模式分類器使用的模型，不會變更伺服器端自動模式的模型。使用伺服器端分類器時，若對話過長而無法進行安全檢查，現在會壓縮對話，不再拒絕每一次受檢查的工具呼叫。/config新增閒置壓縮項目，可關閉或重新開啟閒置壓縮；閒置壓縮後顯示的通知也會說明如何關閉此功能。已修正在壓縮途中停止回合時出現「提示詞過長」錯誤的問題。此外，當閘道使用anthropic/claude-opus-4-1這類帶有前綴的名稱識別Opus 4或4.1時，/autocompact與/effort現在會將設定儲存至正確的模型。²⁷¹

Claude Design將於2026年12月14日前關閉。 /design-sync與/design-login現在會顯示通知，說明獨立版Claude Design（claude.ai/design）將於該日期前關閉。/design consent與/design revoke也會將雲端工作階段導向claude.ai/design/settings，而非/design-login。請參閱斜線指令中的/design項目。²⁷¹

值得留意的修正。 Read工具不再將任意大小的圖片，或名稱看似圖片的管線與裝置，完整載入記憶體：超過128 MB的圖片來源會遭到拒絕。在工作階段途中新增的工具，透過ToolSearch或在壓縮後再次載入時，不再造成提示詞快取未命中。claude plugin與其他子指令會等待佇列中的設定寫入完成才結束執行，因此變更不再遺失或殘留為.tmp檔案。當git預設採用reftable參照格式時，plugins市集不再於每次重新整理時重新複製儲存庫，git plugins也不再將版本顯示為「未知」；在git 2.56或更新版本中，即使殘留的.git檔案指向不存在的目錄，worktree隔離仍可正常運作。協商使用2026-07-28協定版本，但省略resultType、ttlMs或cacheScope的MCP伺服器，現在也能顯示其工具。回覆若以用量點數計費，之後便不再提供提示詞建議。在工作階段途中切換至Vertex或Bedrock後，請求不再因「diagnostics：不允許額外輸入」而失敗。安裝大量plugins時啟動更快，Windows上的改善尤其明顯；Windows也不再拒絕向exFAT或FAT32磁碟寫入檔案。²⁷¹

雲端工作階段與Claude Tag。 例行工作頁面會顯示橫幅，說明上次執行未啟動的原因，例如組織的雲端工作階段同時執行數上限；每則訊息皆可使用「回溯至此處」（自行託管的執行器須使用v2.1.246或更新版本）；執行至一半失敗的工作，不再於1小時後從頭重跑；雲端工作階段在新處理程序中恢復後，費用與用量也不再歸零重算。Claude Tag管理設定已重新整理為套件組合、連接器、skills與plugins，以及頻道等分頁；在Slack中附加的HEIC、SVG、TIFF與BMP圖片，現在會以檔案形式傳送給Claude；若組織依角色限制使用權限，管理者角色現在也能使用Slack中的Claude Tag。²⁷¹

v2.1.301的新功能

Claude Code 2.1.301於2026年10月15日發布（npm於UTC 14:34發布；UTC 19:22發布的GitHub版本包含與正式CHANGELOG相同的51項更新）。npm的latest隔天便移至2.1.302，因此此處一併介紹這兩個版本。²⁷¹

無人值守重試新增用量限制等待上限。 CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS可讓無人值守重試模式（CLAUDE_CODE_RETRY_WATCHDOG）在達到用量限制、且距離重設時間過久時結束請求，不再持續等待；此變數與CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS並列於環境變數參考。另有幾項維運相關變更：切換至上下文視窗較小的模型時，若對話長度超出新模型可容納的範圍，現在會由原模型產生摘要，不再未經詢問就花費用量點數產生摘要；當組織無法使用最新的Fable模型時，fable與best別名會改用前一版Fable模型重試1次；透過LLM閘道進行對話時，若回應中的模型名稱與請求指定的模型不同，也不再反覆壓縮對話。²⁷¹

遙測、vim與mods。 OpenTelemetry的tool_decision事件新增classifier_verdict與permission_mode，可區分自動模式分類器的決策與權限規則；設定OTEL_LOG_TOOL_DETAILS=1時，還會提供classifier_category，指出分類器封鎖操作時所符合的內建規則。Vim模式新增%移動指令：可單獨使用，或搭配d、c、y跳至配對括號（互動模式文件已列出此指令）。Mods的Input新增rows，可在終端機中建立多行文字欄位；按Enter送出，按Shift+Enter或在Enter前輸入反斜線則另起一行。Mod hook的.catch處理函式現在僅在hook擲出例外或逾時時執行；$.env.set在變數設定或取消設定完成後會回傳{}，或回傳{ deny }說明拒絕原因；$.model.fork不再於新處理程序的首次回應前回傳nothing-to-fork；在VS Code、桌面與行動應用程式中，繪製於問題對話方塊上方的樹狀結構可包含Markdown，最多48列。請參閱Mods與Vim模式。²⁷¹²⁷²

值得留意的修正。 結束程式時，若WorktreeCreate hook建立的worktree可能含有尚未推送的提交，便不再未經詢問就將其移除。搜尋程式執行失敗時，Grep與Glob會回報錯誤，不再顯示「無符合項目」。參數名稱數量過多或過長的skills與指令不再停頓數秒：現在只會補齊前64個名稱，每個最多64個字元。Read工具不再將.xlsm、.parquet、.epub與.heic等二進位檔案當作文字讀取。執行/rewind後，會再次向模型列出skills。若工具呼叫在權限檢查期間被回合途中傳入的訊息中斷，不再向模型回報為使用者拒絕。在vim模式中按Esc不再丟棄已輸入的AskUserQuestion答案：自由文字欄位支援NORMAL模式，只有在該模式下按Esc才會取消。磁碟已滿時，現在會回報指出該磁碟的錯誤，不再顯示誤導性的「請執行/login」。即使受管理設定限制了MCP伺服器，從Slack啟動的自行託管執行器仍可附加儲存庫（使用deniedMcpServers可持續停用這些工具）。VS Code可顯示回覆中的LaTeX數學式，包括$$與\[ ... \]區塊，並在Pro與Max的用量限制橫幅上顯示「取得更多用量」連結。²⁷¹

v2.1.300的新功能

Claude Code 2.1.300於2026年10月14日發布，距離2.1.299僅數小時：npm於UTC 14:27以next標籤發布，GitHub版本隨後於UTC 18:24發布，包含與正式CHANGELOG相同的88項更新。到了當天晚間，npm的latest與next皆指向2.1.300，stable則從2.1.287移至2.1.292。並未跳過任何版本。²⁶⁹ advisor 工具已支援 AWS 上的 Claude Platform。 /advisor 現已可在 AWS 上的 Claude Platform 使用；必須先透過 /advisor、advisorModel 或 --advisor 選定顧問模型，才會執行顧問功能，設定 CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1 則可停用此工具。截至10月14日，advisor 文件頁面仍將 AWS 上的 Claude Platform 列為不支援的供應商。此工具讓 Claude 在需要決策時諮詢第二個模型，早在本次版本發布前就已推出，詳見顧問工具。²⁶⁹²⁷⁰

Mods 與遙測。 Mods 新增 virtualText 提示裝飾文字（顯示在提示輸入框中，但不會加入草稿的文字）、可在主檢視中顯示代理對話紀錄的 $.ui.view({ agentId })（使用 $.ui.view({}) 返回）、Text 上用於由右至左文字列的 dir 屬性，以及用於偵測非鍵入編輯所造成之提示輸入框變更的 prompt.change hook（例如叫回歷史紀錄、清除、復原或由 plugin 填入內容）；agent.spawn 現在可改寫工作流程代理的 prompt 與 model，不再只能拒絕啟動，mods 參考文件則將 next.error.cause 的 rewritten 原因標記為自 v2.1.300 起提供。OpenTelemetry 的 api_request 事件將快取寫入分為 cache_creation_5m_tokens 與 cache_creation_1h_tokens，追蹤跨度帶有 GenAI 語意慣例屬性，例如 gen_ai.provider.name、gen_ai.conversation.id、gen_ai.tool.name 與 error.type，而經 mod 的 prompt.submit hook 改寫或捨棄的提示，也不再於 user_prompt 事件中記錄為使用者鍵入的內容。本機對話紀錄現在也會記錄每次 API 請求的系統提示、工具與參數，因此分享的對話紀錄可用來精確重現請求（請參閱 Mods 與遙測）。²⁶⁹²⁷⁰

操作與行為變更。 即使關閉遙測，傳送至 api.anthropic.com 的大型請求仍會使用 gzip；設定 CLAUDE_CODE_GZIP_REQUEST_BODIES=0 可停用。來自 PreToolUse 與 PermissionRequest hooks 的 updatedInput，會比照 Claude 本身的輸入進行驗證：未知的索引鍵會被移除，若工具拒絕該輸入，呼叫也會遭到拒絕。結束時，背景命令若在收到停止要求後1.5秒仍持續執行，就會遭到強制終止。claude remote-control 移除了原本沒有作用的 --sandbox 與 --no-sandbox 旗標；傳入任一旗標都會以錯誤結束，這類工作階段應改用設定中的 sandbox.enabled 啟用沙箱。受 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST 管理的工作階段，會忽略設定中的 CA 憑證套件、工具代理、git TLS 與 git 設定變數，例如 SSL_CERT_FILE。在 Cowork 雲端工作階段中，PermissionRequest hook 的 setMode 會被忽略，其餘核准內容仍會生效。當 forceLoginGatewayUrl 指向由 Anthropic 營運、且為該工作階段主機名稱提供服務的閘道時，Claude Desktop 的 Code 分頁會套用受管理設定；claude gateway 若遇到無法使用的 desktop: 原則索引鍵，則會在啟動時停止。/sandbox 選項的文字改為「在沙箱中執行命令」。VS Code 新增 claudeCode.attachSelection，可讓編輯器中選取的內容不附加到訊息。在 Slack 中，只要管理員允許，Claude Tag 就能在 Slack Connect 頻道回覆。²⁶⁹

值得留意的修正。 即使結束時仍有背景命令執行中，SessionEnd hooks 也會執行；ENABLE_TOOL_SEARCH=auto 不再於對話途中停用；遭 forceLoginOrgUUID 拒絕的登入，不再留下該組織的權杖；無介面與 SDK 工作階段在壓縮後恢復時，會保留壓縮所留下的訊息與摘要；當 API 拒絕 MCP 工具的輸入結構描述時，對話不再每一輪都因 400 錯誤而失敗（改為傳送不含參數的工具）；代理 hooks 會遵循其 model 設定；當標籤或分支名稱與提交 ID 相同時，--worktree 工作階段會從正確的提交啟動，且可在 reftable 儲存庫中重新開啟；claude daemon stop --any 會等待、強制終止卡住的服務，若服務仍存在則以結束碼 1 結束；Cowork 雲端工作階段中的 Write 與 Edit，不再對您電腦上的路徑回報成功；無法讀取組織原則時，雲端工作階段不再每輪停滯5分鐘；自行託管的執行器也不再因無人讀取其輸出而凍結。²⁶⁹

v2.1.299 新功能

Claude Code 2.1.299 於2026年10月14日發布（npm 為 UTC 00:23；UTC 02:49 發布的 GitHub 版本，包含與正式 CHANGELOG 相同的190個項目）。2.1.297 與 2.1.298 從未發布，因此並未遺漏任何版本。npm 的 latest 一度為 2.1.299，直到當天稍晚 2.1.300 被設為最新版本（請參閱 v2.1.300 新功能）。²⁶⁷²⁶⁹ 從 2.1.296 升級：本版本修正了該版本引入的兩項退化問題。第一項是在 Cowork 與 claude.ai 雲端工作階段中，若訊息在 UserPromptSubmit 或 mod prompt.submit hooks 執行期間被停止，編輯與重試功能會失敗。第二項是雲端或無介面工作階段在重新啟動後恢復時，若有新訊息抵達，已核准的工具呼叫會執行兩次。

閒置壓縮（v2.1.299）。 終端機對話若累積200K以上的 token，並閒置約54分鐘，現在會在其1小時的提示快取到期前先進行壓縮，讓下一則訊息不必重新處理完整上下文。CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS 可調整200K的最低門檻（低於100,000的值會提高至100,000），在 settings.json 中設定 "idleCompaction": false 則可停用；設定參考文件與環境變數頁面均列出這兩項設定，並標示為適用於 v2.1.290 或更新版本。設定 CLAUDE_CODE_DISABLE_FILE_MENTIONS=1 後，@ 提及會將路徑交給 Claude，讓它透過檔案工具讀取，而非直接提供檔案內容，因此讀取時會執行您的 PreToolUse hooks；專案與本機設定無法設定此變數（請參閱環境變數參考）。²⁶⁷²⁶⁸ v2.1.302 在 /config 新增了閒置壓縮項目，可用來停用或重新啟用此功能，閒置壓縮後顯示的通知也會說明操作方式。²⁷¹

權限與 MCP。 mcp__a 這類允許規則現在只會涵蓋名為 a 的伺服器，不會涵蓋 a__b 或 a_；請以伺服器正規化後的完整名稱撰寫 mcp__<server>__*。若伺服器名稱包含 __，也應以相同方式列在代理的 tools: 清單中，現在該項目只會納入這台伺服器的工具。對於正規化名稱含有雙底線的伺服器，拒絕與詢問規則已恢復生效。Anthropic 位於 api.anthropic.com 的第一方 MCP 伺服器，其工具說明與伺服器指示會完整傳送給 Claude，不再截斷於4,096個字元。未擷取任何功能旗標的安裝環境中，雲端工作階段與 Remote Control 連接器預設會協商使用 MCP 協定 2026-07-28（可設定 MCP_PROTOCOL_NEGOTIATION=legacy 停用）；傳送至 claude.ai 連接器代理及 Anthropic 託管之 MCP 伺服器的請求，不再跟隨 HTTP 重新導向；MCP OAuth 現在會傳送已設定的 headers 與 headersHelper 值；空白的 .mcp.json 不再被回報為無效，名為 constructor 或 prototype 的伺服器也能連線。沙箱內的命令不再能寫入 --plugin-dir 資料夾，或透過符號連結存取遭拒絕的路徑；未執行 rm 的 shell -c 指令碼不再觸發 rm 確認提示；若指令碼無法由 Claude Code 讀取，且在執行時才組合出 rm，則只有設定 CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT=1 才會顯示確認提示。²⁶⁷

Hooks 與 mods。 UserPromptSubmit hooks 會在 skill 或自訂斜線命令展開前執行，因此阻擋提示的 hook 也會阻止其中嵌入的 shell 命令執行；skill 自身在前置中繼資料中設定的 UserPromptSubmit hook，則會從呼叫該 skill 之後的下一則提示開始執行。若無法將動作交給 plugin hook，或無法取得其回覆，現在會拒絕該動作，不再放行；若工具已執行，則會扣留其結果。Mods 方面，turn.start hook 也會接收 subagents 與團隊成員的回合事件（透過 e.agentId 區分）；skill.prompt 會收到 skill 的前置中繼資料、來源、plugin 名稱與檔案路徑（mods 參考文件將這些功能標示為自 v2.1.299 起提供）；$.prompt.media 讓受管理設定中的 mod 透過 prompt.submit hook 讀取附加的圖片或文件；$.session.identity() 會回報工作階段的登入方式；Text 支援 size、weight、mono 與 tabular，Box 則支援具名間距級距（bold 已棄用，改用 weight）；session.append 新增 queue 入口；恢復 subagent 或團隊成員時，也會觸發 agent.spawn，並設定 resume。遠端停用的 mods 會在回合之間卸載，而在組織管理 Claude Code 的環境中，/plugin 與 claude plugin validate 會列出遭略過的 hooks 名稱（請參閱 Mods）。²⁶⁷²⁶⁸ 指令、介面與操作。 /usage 會針對最高推理強度、工作流程、常駐上下文及大型工具結果發出警告。在代理檢視中，/effort 和 /fast 會設定新工作階段的起始值；單獨輸入 /model、/effort 或 /fast 會開啟選擇器；預覽面板則會為以 --safe-mode 啟動的工作階段顯示安全模式資訊。當略過權限檢查的選項可用，導致 Plan 模式不會在大多數編輯前詢問時，系統會顯示一次性提示。claude plugin eval 支援 --disallow-tools 和測試案例的 disallowed_tools 欄位；若執行因 API 錯誤而結束，該次執行會得到 0 分，整個測試套件也會判定失敗。claude self-hosted-runner orchestrator --shutdown-drain-sec 會在收到 SIGTERM 時，留時間讓進行中的輪詢與啟動 hooks 完成。透過 Claude 應用程式閘道運作時，在 code 或 cli 政策的 env 中設定 CLAUDE_CODE_ATTRIBUTION_HEADER=0，即可移除歸屬資訊區塊。在 Cowork 雲端工作階段中，PermissionRequest hook 無法再於自動模式核准 shell 指令或 subagents；在已核准網站上，若 Claude in Chrome 的操作遭安全分類器標記，系統會改為詢問您，而非直接拒絕。結束時顯示的恢復指令會以 ID 指定工作階段；非互動式工作階段中的 /btw 會在 11 分鐘後逾時；本機工作階段可監看已發布成品的數量從 10 個提高至 25 個；網路安全防護通知也不再要求您申請加入 Cyber Verification Program。²⁶⁷

值得留意的修正。 透過自訂 ANTHROPIC_BASE_URL 傳輸的串流會等待資料 300 秒，不再於 180 秒時中止；傳送至 Anthropic 的功能旗標、啟動、快速模式、設定檔與伺服器管理設定請求，不再附帶第三方閘道的 API 金鑰；/usage 和狀態列不再顯示超過 100% 的使用量；日光節約時間結束而出現重複時段時，排程任務與迴圈不再於每回合結束後再次觸發；使用 --debug 或父程序停止讀取 stderr 時，記憶體用量不再無限制增長；SendMessage 可在重新啟動後依名稱找到 subagent；Read 可處理含有位元組順序標記的 UTF-16LE 檔案，Write 則不再默默將 Windows-1252、Shift-JIS、GBK 或 UTF-16BE 檔案轉換為 UTF-8；在 Windows 上，若未安裝 Git for Windows，未設定 shell 的 PreToolUse 與 PermissionRequest hooks 會阻擋呼叫，不再於失敗時放行。²⁶⁷

v2.1.293-v2.1.296 新功能

2026年10月7日至10月9日共發布了 4 個版本。npm 的 latest 和 next 均為 2.1.296；stable 則從 2.1.285 更新至 2.1.287。[^274] 本次重點是新模型：Claude Haiku 5.5 於 v2.1.293 推出，成為在 Anthropic API 上使用 haiku 時選取的模型（請參閱可用模型）。若您透過受管理設定登入 Claude 應用程式閘道，請升級至 v2.1.296：此版本修正了 v2.1.295 引入的問題，先前在 forceLoginMethod 設為 gateway 卻未設定 forceLoginGatewayUrl 時，系統會忽略已儲存的閘道登入狀態。

v2.1.296（10月9日）。 /cost、狀態列、--max-budget-usd 及 SDK 的費用數據，現在以每百萬 token $0.10 計算 Sonnet 5.5 的快取讀取費用，先前使用的費率為 $0.20。預先傳送的 MCP 工具描述，以及 MCP 伺服器指示，其預設長度上限均從 2,048 提高至 4,096 個字元。Subagent 的 frontmatter 和 --agents 定義支援 autoCompactWindow，讓 subagent 能比主對話更早自動壓縮上下文。CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL 可讓所有工作流程代理使用同一個模型，其他 subagents 則維持各自的模型；CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS 可為 529 錯誤的退避重試設定更長的延遲上限。Read 工具支援 allow_large，讓 Claude 在上下文仍有空間時，以單次呼叫讀取超過一般大小限制的文字檔案。受管理設定中的 PreToolUse hooks 若以 "continue": false 拒絕工具呼叫，或受管理的 prompt hooks 阻擋工具呼叫，現在除了拒絕呼叫，也會結束回合。--debug 會列出自訂代理檔案中無法辨識的 frontmatter 欄位，並記錄每個指令 hook 的指令、plugin、結果與執行時間。Claude 應用程式閘道在 managed.policies[] 下新增 code 索引鍵，設定項目與 cli 相同，也會套用至 Claude Desktop 的 Code 分頁。若在 ← 將工作階段移至背景的同時啟動回合或 ! 指令，系統現在會停止該操作，不再於看不見的背景中完成。文件後來已補上其中兩項：hooks 參考文件將每個 hook 的 --debug 記錄行標示為 v2.1.296 新增，Claude 應用程式閘道文件則說明了 code 政策索引鍵；截至10月14日，sub-agents 與 env-vars 文件已分別收錄 autoCompactWindow 和 CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS；截至2026年10月14日，CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL 仍僅見於版本資訊。[^274][^276]²⁶⁶²⁶⁸

v2.1.295（10月8日）。 指令與 HTTP hooks 支援 onFailure: "block"：若 hook 無法啟動、逾時或以非預期的結束碼退出，便會阻擋操作，不再放行（請參閱 Hook 輸入／輸出協定）。CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS 可限制無人值守重試模式在遇到 429 和 529 錯誤時的等待時間。Subagents 最多會從 skills 欄位預先載入 32 個 skills；透過工具搜尋載入的 MCP 工具描述，截斷長度則從 2,048 提高至 16,384 個字元。在沒有受管理設定的電腦上，現在也能於個人使用者設定中使用 forceLoginMethod: "gateway" 和 forceLoginGatewayUrl，讓 /login 直接開啟該閘道；閘道文件現已說明此設定方式。每個閘道上游都支援選填的 models 清單，並可用 * 作為萬用字元；雲端上游也會遵循 timeouts.upstream_ttfb_ms。實作 Program Status Protocol（OSC 7501）的終端機可顯示 Claude Code 正在工作、等待您回應或已完成。透過 Claude 應用程式閘道傳送的背景請求，會在閘道提供 Haiku 4.5 時使用該模型，取代工作階段的模型。若閘道、Bedrock、Vertex 或 Foundry 拒絕 [1m] 模型的 context-1m beta 選項，系統會移除該選項後重新傳送請求，不再直接失敗。在已連接的背景工作階段中，於閒置提示符號按下 Ctrl+C 不會影響待執行的 /loop 喚醒，因此連按兩次即可中斷連接，迴圈仍會持續執行；按 Esc 則會停止迴圈。未擷取任何旗標的安裝環境中，claude.ai 連接器預設會協商使用 MCP 協定 2026-07-28。/copy 提供引文文字選項；claude -p 會在最後一個回合結束後，透過 stderr 說明目前正在等待什麼；mods 則新增 $.ui.notify。網頁搜尋和 agent hook 評估在 xhigh 與 max 推理強度下，不再耗費明顯更長的時間。[^274][^276]

v2.1.294（10月8日）。 針對以指示文字撰寫的 prompt 和 agent hooks 提供兩項修正：像「阻擋符合下列條件的指令……」這類 hook，不再放行原本應阻擋的操作；對於「若建置失敗，請繼續執行」這類 Stop 與 SubagentStop hooks，判定方式也已調整，降低 Claude 過早停止的可能性。[^274]

v2.1.293（10月7日）。 Claude Haiku 5.5（claude-haiku-5-5）成為 Anthropic API 上的預設 Haiku 模型：上下文為 1M，每百萬 token $0.10/$0.50，提示超過 100K 時則為 $0.50/$2.50。subagentStatusLine 酬載新增 agentType，讓狀態列指令碼能區分自訂 subagent 類型；mods 的 $.tool.register 新增 isDeferred。本版撤回兩項變更：其一是 v2.1.281 的自動模式拒絕訊息，該訊息會告知 Claude，拒絕範圍涵蓋操作結果，而不僅限於該特定指令；其二是 v2.1.290 針對容器重新啟動後遺失 /loop 喚醒的雲端工作階段修正，因此這類工作階段會再次持續休眠。此外，Claude 在壓縮上下文後，不再將壓縮前自己最後執行的操作視為已完成；HTTP MCP 連線不再將所有已傳送的請求保留到連線關閉；claude purge 會列出無法移除的項目，並以結束碼 1 退出，不再悄然停止；沒有工作階段正在使用時，claude.ai 的 skill 同步檢查間隔從 10 分鐘改為 40 分鐘；Team 與 Enterprise 啟動時會更早擷取政策與受管理設定，並在請求停滯 3 秒後重試。[^274][^276]

v2.1.288-v2.1.292 新功能

2026年10月2日至10月6日共發布了 5 個版本。npm 的 latest 和 next 均為 2.1.292；stable 維持在 2.1.285。²³⁴ 若您使用的是 2.1.288、2.1.289 或 2.1.290，請升級：v2.1.291 修正了 2.1.288 引入的問題，該問題可能導致結束時遺失工作階段的最後幾則訊息；也修正了 2.1.290 引入的問題，該問題可能導致雲端工作階段遺失權限提示的回覆。²³⁵ v2.1.292（10月6日）。設定 CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS 可延長過載（529）請求重試時的退避基礎延遲；環境變數文件現已列出預設值500毫秒，以及允許範圍500至32000。Agent工具接受 effort 參數，因此 Claude 能以您指定的推理投入程度執行子代理；subagents 文件現已說明這項每次呼叫皆可指定的參數。它會覆寫 frontmatter 欄位，並在子代理恢復執行時持續生效，而 CLAUDE_CODE_EFFORT_LEVEL 的優先順序高於兩者。claude plugin install --marketplace <source> 可用一個 shell 指令新增市集並從中安裝。本機（stdio）MCP 伺服器現在於所有安裝環境中，預設皆協商使用2026-07-28版協定，包含 Bedrock、Vertex 與 Foundry；可用 MCP_PROTOCOL_NEGOTIATION=legacy 停用此行為。MCP 文件現已說明，預設會要求 stdio 伺服器使用該版本。代理名稱上限為256個字元：超過上限的名稱會遭拒絕，skill 或 plugin 檔案中過長的 name 則會被忽略。subagents 文件現已註明 name 欄位的上限；名稱超長的子代理檔案會被略過，並在偵錯記錄中寫入錯誤。一項安全性修正可防止 PreToolUse hook 核准與自動模式略過讀取網路（UNC）路徑檔案時的確認提示。Mods 新增 prompt.autocomplete、$.model.complete 的提示快取，以及 agent.spawn 的工作流程代理；claude plugin test 現在會在 stub 回覆遭拒絕時判定失敗。截至2026年10月6日，其餘項目僅記載於版本說明中。²³⁶[^273][^276]

v2.1.290（10月5日）。互動式 WebSearch 的呼叫額度改為每小時補充100次（CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR；設為 0 可停用補充），不再於200次呼叫後用盡。claude attach 與 claude logs 接受部分工作階段名稱。/claude-api managed-agents-onboard <url> 可將說明 Managed Agents 模式的頁面轉為 ant apply 檔案；/claude-api managed-agents-onboard <quickstart-name> 則透過 ant CLI 建立 Console 快速入門範本，例如 deep-researcher。多項預設限制更加嚴格：專案設定不再能啟用 Chrome 中的 Claude；儲存庫的 .claude/settings.json 或 .claude/settings.local.json 不再能設定 CLAUDE_CODE_DISABLE_ATTACHMENTS；pyright 與更多形式的 ps 會在執行前要求確認；受管理設定檔若連結至受管理設定資料夾以外的位置，則會觸發警告。WebFetch 現在會告知頁面超過100,000個字元後，有多少內容尚未讀取，並接受 offset 以繼續讀取；以往則會直接捨棄這些文字而不告知。CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC 也會略過啟動時的連線預熱，而 CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS=5m 不再被解讀為5毫秒：帶有單位後綴的值會改用 dialogExpiry 設定。²³⁵[^273]

v2.1.290，團隊與閘道。Claude 應用程式閘道的登入核准頁面新增「拒絕」按鈕，最低支援的 PostgreSQL 版本也從14降為11。在自行託管的執行器上，claude --environment <id> 會透過目前的 Sessions API 建立工作階段。如果同名資料夾取代了受追蹤的檔案，而還原 stash 會刪除該資料夾中的檔案，claude --teleport 與 /teleport 就會拒絕該 stash；--channels 轉送機制則會忽略重複的回覆 ID，避免誤核准其他提示。在 Slack 中，!fast 可將討論串切換至快速模式，!fast off 則可切換回來。VS Code 預設顯示訊息時間戳記（可透過 Claude Code: Show Message Timestamps 設定關閉）。²³⁵

v2.1.289（10月3日）。Mods 新增用於隊友代理的 agent.spawn、跨 plugin hook 事件共用的單一代理 ID，以及 $.agent.list() 中的閒置與等待狀態；claude plugin validate 不再略過資料夾中同時含有市集資訊清單的 plugin；另修補了沙箱自動允許機制下，Bash 拒絕規則的2項漏洞。²³⁵[^273]

v2.1.288（10月2日）。claude project purge 現已更名為 claude purge；舊名稱仍可使用，但會顯示通知。背景指令的時間限制僅適用於無人值守的工作階段（-p、Agent SDK、CI、雲端）。/code-review --max-findings <n>|all 可變更審查發現數量的上限，直到傳入 --max-findings default 為止。/autocompact 會為各模型分別儲存視窗設定。CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS 可針對 Mantle 或拒絕結構化輸出的閘道關閉結構化輸出。限定路徑的規則與巢狀 CLAUDE.md 檔案會在使用 Write 與 Edit 時載入，不再僅於 Read 時載入。語言伺服器會在60秒後逾時（可透過各伺服器的 requestTimeout 設定），不再持續停滯。在自動模式下，對話若過長而無法由用戶端分類器處理，系統會壓縮對話，不再為每次工具呼叫顯示確認提示；若 ANTHROPIC_DEFAULT_SONNET_MODEL 指定 Claude Sonnet 5.5 或 Opus 5.5，用戶端分類器會忽略該指定，改用 Claude Sonnet 5。Mods 新增 $.ui.selection()；未安裝 GitHub CLI 的雲端工作階段會提供內建的 gh api；在空白提示輸入框中按向上鍵，可還原被 Ctrl+C 清除的草稿。²³⁴[^273]

v2.1.105–v2.1.114 新增指令¹⁴⁶¹⁵⁰

工作階段回顧（v2.1.108+）

這項新的工作階段層級功能，會在您返回暫停的工作階段時呈現先前脈絡。預設啟用，可透過 /config 或 CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0 停用。模型也能透過 Skill 工具呼叫內建斜線指令（/init、/review、/security-review），進一步延伸子代理與 skill 的運作模式。¹⁴⁶

推播通知（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式游標移動功能，以及全螢幕檢視區捲動功能：

subagents停滯逾時（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，建議升級。

內容標記：文字浮水印與C2PA檔案中繼資料（2026年8月）

因應歐盟《人工智慧法》第50條（自2026年8月2日起適用於新推出的AI系統），Anthropic宣布為Claude產生的內容加入機器可讀標記。此系統包含兩個部分：在產生的文字中嵌入不可見的統計浮水印，以及依據C2PA開放標準，為.svg、.png和.jpg等產生的檔案附上經簽署的來源中繼資料。²⁴⁸²⁰⁴新聞標題容易模糊的一個細節是：兩個部分都遵循相同的模型推出時程。根據支援頁面，「在2026年8月2日或之後推出的Claude模型，將在推出時支援機器可讀標記」。在該日期之前推出的模型，也就是當時所有現有模型（Fable 5、Opus 5、Sonnet 5、Haiku 4.5），則適用歐盟法律的過渡期；Anthropic也表示「正努力為這些模型加入標記支援」。²⁰⁴

上述清單反映的是8月的情況。Fable 5.1（9月1日）、Opus 5.5（9月22日）和Sonnet 5.5（9月28日）都在分界日期之後推出，因此依規定應在推出時就支援標記。Fable 5.1的發佈說明將內容來源資訊列為新增功能，但Opus 5.5的模型頁面與遷移指南，以及Sonnet 5.5的模型頁面與新功能頁面，都未提及標記。^2372222308月之前推出的模型，其輸出無論是文字或檔案都不帶標記；較新模型的輸出則會帶有標記，且涵蓋所有使用介面與管道，包括Claude Platform（API）、claude.ai、Claude Code、Claude Cowork、Claude Tag和雲端閘道，因為標記是在模型層級實作的。有一點值得說明，因為一則廣為流傳的討論串把這件事說反了：如果您察覺某個8月之前推出的模型在風格或行為上有所改變，那不可能是浮水印造成的，因為這些模型尚未啟用標記。

運作方式：採用Google DeepMind的SynthID-Text變體。當Claude在語意相同的選項之間做選擇時，浮水印會改變「選詞時所用的隨機性來源」。這個過程不會加入字元，也不涉及後處理；根據Anthropic的內部測試，「浮水印不會影響內容、創意程度或可讀性」。²⁴⁸

Claude Code使用者會關心的是：程式碼帶有稀疏的浮水印。能正常運作的程式碼，可任意選擇的空間不多，因此標記會集中在有選擇餘地的地方，例如註解與命名。Anthropic表示，這「對實際產生的程式碼影響微乎其微」。²⁴⁸標記能否保留取決於機率，也因標記類型而異：對文字而言，小幅編輯「可能不會完全移除浮水印」，全面改寫則會，而由Claude產生的譯文會帶有自己的新標記；對檔案中繼資料而言，格式轉換、重新儲存和擷取螢幕畫面都可能移除C2PA簽章。²⁰⁴目前規劃提供偵測用API；偵測結果為陽性，只能證明「Claude很可能曾在某個階段參與此內容」，而且明確無法區分「這是Claude撰寫的」與「這是Claude大幅編輯過的」。支援頁面也指出，沒有標記同樣無法證明任何事。目前未提及任何客戶方案可選擇停用標記。²⁴⁸²⁰⁴

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+）。¹³⁷

使用合約費率而非定價表價格（modelPricing，受管理，v2.1.243+）：採用議定模型費率或折扣乘數的組織，可透過受管理設定modelPricing部署這些費率；此後，/cost、狀態列與遙測成本數據都會改用合約費率，而非定價表價格，讓開發人員看到的數字與組織實際支付的金額一致。²⁴⁶自v2.1.271起，乘數也能設為大於1，最高可達10，供向內部團隊收取加成費率的組織使用。²¹⁶

個別工作階段的提示快取資訊列（v2.1.251+）：/cost會新增該工作階段的提示快取資訊列，顯示命中率、未命中次數、重新快取的 token 數量，以及快取處於暖快取或冷快取狀態；狀態列指令碼也會收到相應的prompt_cache物件。此物件會在主要對話首次收到API回應後出現，不計入 subagent 請求，並依據API回應中的快取 token 數量計算，因此適用於所有供應商。/usage也會在其Prompt cache (main)資訊列顯示相同統計資料。²⁰⁶²⁰⁹自v2.1.260起，/cost資訊列與狀態列的prompt_cache物件還會指出快取未命中的可能原因，例如工具定義或系統提示有所變更，或工作階段閒置時間超過快取 TTL。²¹²

代理程式流量不再破壞自身的快取前綴（v2.1.265）：兩項修正解決委派工作中的提示快取流失問題。恢復前景啟動的 subagent 時，不再變更其工具清單與系統提示前綴；代理程式隊友與恢復執行的 subagents，也不再於後續輪次將SubagentStart hook 的內容與預先載入的 skills 移出提示前綴。這兩項錯誤都會破壞提示快取的重複使用：前綴一旦變更，後續所有內容便會以未快取輸入重新傳送。這恰好發生在快取成本效益最為重要的長時間代理工作階段中（與v2.1.260針對Fable 5.1工具呼叫輪次修復的失效模式相同）。²¹⁵

v2.1.267快取穩定性修正批次：單一版本、約10項修正，全都源於相同的失效模式：某項操作在對話途中重寫提示前綴，導致後續所有內容以未快取輸入重新傳送。恢復的工作階段不再重寫工具清單、重新轉譯工具說明，或在連接器重新連線前重寫先前的MCP工具公告；使用/model切換模型時，也不再重新傳送所有工具定義（commit 與 PR 的歸屬文字現在會以對話附註傳入，並在模型變更時更新）；透過--system-prompt或--append-system-prompt啟動的 subagents 與工作階段，只會記錄系統提示與工具定義一次；對話途中加入的MCP與 plugin 工具，也會以延後載入的定義送達未使用 ToolSearch 的工作階段，而不再重寫工具清單。這批修正將v2.1.260與v2.1.265的成果延伸至恢復、模型切換及MCP重新連線等情境。²¹⁶

v2.1.273讓對話得以延續：/login、/upgrade與/extra-usage原本會捨棄對話中先前的思考內容，迫使下一個請求完整重寫提示快取。²¹⁷

v2.1.277再修補3處前綴流失：若 SessionStart hook 印出輸出，在/clear後延續的工作階段（重新啟動、--continue、--resume）會遺失首則訊息的一部分，造成提示快取完全未命中；恢復的 subagents 與隊友會重新轉譯已載入的MCP工具定義，破壞該代理程式的提示快取；對話中先前記錄的附件則會在恢復或重新啟動後重新轉譯，導致延伸思考內容遭捨棄，且提示快取未命中。失效模式與v2.1.265至v2.1.267的修正批次相同：某項操作重寫前綴，後續所有內容便以未快取形式重新傳送。如今修正範圍已涵蓋 SessionStart 輸出、恢復執行之代理程式的MCP定義，以及已記錄的附件。²¹⁹

v2.1.280再新增2項修正：當Claude執行工作時，從主機應用程式（Claude Desktop、VS Code、SDK）切換模型，不再導致下一個提示發生快取未命中；恢復的分支 subagent 現在也會重新傳送最初使用的工具清單，而非重新建立清單，後者原本會破壞該代理程式的提示快取。²²⁰

v2.1.281再新增3項修正：當權限提示仍待處理時重新啟動並恢復工作階段，不再傳送與先前不同的歷程，避免從該處開始破壞提示快取；對話途中中斷連線，或恢復工作階段後仍在連線的MCP伺服器，在工具搜尋關閉時（例如位於 Proxy 或 Gateway 後方）不再造成快取成本；恢復的工作階段也不再以變更後的形式重新傳送先前輪次，以免API捨棄對話先前的推理內容。²²⁴

訂閱方案

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

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

自2026年9月14日起實施的每週限制（8月29日公布）：自5月提升用量後實施至今的臨時每週限制增幅50%，將於9月14日結束；Pro、Max、Team 與按席位計費的 Enterprise 方案會改為較提升前基準永久增加25%。Anthropic對此變動的計算如下：「與目前相比，Claude Code每週限制將減少17%。」若目前的每週上限為150單位，9月14日後將變為125。五小時限制不在此次公告的調整範圍內，5月的加倍措施依然有效。若您會執行長時間無人看管的工作階段，現在就應為較低的上限預作準備：重設時自動繼續的切換開關（v2.1.234）與/usage是最重要的兩項控制功能。²¹³

API Token定價（2026年10月）^1144222[^275]

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

1M context定價（2026年4月）：Opus 4.7、Opus 4.6、Sonnet 4.6與Mythos Preview皆以每MTok標準費率提供1M context，不收取長 context 額外費用。¹⁴⁸這是近期整併後的結果；先前關於Opus 4.6或Sonnet 4.6在輸入超過200K個 token 時，輸入費率為2倍、輸出費率為1.5倍的說明，已不再適用。舊版Opus 4.5及更早的模型則維持原有定價結構。

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

提示快取可大幅降低重複輸入的成本：快取寫入費用為基本費率的1.25倍（5分鐘快取）或2倍（1小時快取），但快取讀取僅為0.1倍，可節省90%。另有兩項例外，費率更低：Claude Opus 5.5的讀取費率為0.05倍（$0.20／MTok，節省95%），而Claude Fable 5.1與Mythos 5.1的讀取費率為0.025倍（Fable 5.1為$0.25／MTok，節省97.5%）。²³⁷²²²對於具有重複 context 的RAG系統與程式設計助理，快取可降低88%至95%的成本。

批次API為非緊急工作提供50%折扣，並於24小時內完成，例如夜間測試套件。

多帳戶政策⁵²

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

允許的情況：

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

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

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

如有疑問：請聯絡Anthropic支援，並要求以書面方式確認您的特定設定。

成本因素

實際成本範例

成本依定價表價格計算（提示不超過100K個 token 時，Haiku 5.5為$0.10／$0.50；Sonnet 5.5為$2／$10；Opus 5.5為$4／$20，皆以每MTok計），尚未計入提示快取折扣。

節省成本的要點：使用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. 主動壓縮：context越小，token越少
7. 限制輸出：export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
8. 非緊急工作使用批次API：輸入與輸出token皆享五折
9. 分析專案的Claude API支出：/claude-api cost-optimize（v2.1.247+）可分析現有專案的Claude API支出，並逐一衡量與調整各項成本槓桿（快取、token控管、批次處理、投入程度、模型選擇）。此功能適用於您透過API建置的應用程式，而非Claude Code工作階段本身²⁴¹

監控用量

• Claude Console：platform.claude.com（需要Admin或Billing角色）
• Workspace限制：為每個Workspace設定支出上限
• 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 5.5 (medium effort default; /effort high or xhigh for harder)
                  │         Cost: ~$1.60/task
                  │         Quality: Highest (1M context at standard price, adaptive reasoning)
                  │
                  └── NO → Use Sonnet
                           Cost: ~$0.50/task
                           Balance: Best overall when cost matters

經驗法則：自v2.1.280起，預設模型不再依方案而定——除Microsoft Foundry外，每個工作階段都會從Opus 5.5開始——因此，過去的「升級至Opus」如今正好相反：當任務不需要推理能力時，使用/model sonnet降級，可將token價格減半。^{181197207220221} subagents則改用Haiku。如果降級後的回答流於表面，請繼續使用Opus。使用agent teams（v2.1.32以上版本）時，Opus可協調多個agents，針對不同子任務平行作業。⁷⁹

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