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

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

目前狀況（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上的Claude Platform、Amazon Bedrock與Google Cloud的Agent Platform。Microsoft Foundry是例外：其預設模型為Sonnet 4.5，而opus別名代表Opus 4.6。²²¹
• Opus 5.5重點一覽：每百萬個token的輸入／輸出費用為$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與Python Agent SDK工作階段亦自v2.1.285起採用此模式。其他-p與SDK工作階段則以Manual模式啟動。Enterprise與Claude API帳戶、AWS上的Claude Platform、Bedrock、Agent Platform、Foundry，以及透過閘道執行時，其安全檢查會在伺服器端免費進行；若無法使用，則改用計費的本機檢查。^{219227228229230}
• AGENTS.md：自v2.1.277起，若專案沒有CLAUDE.md，系統會將AGENTS.md讀取為專案指示；但無法擷取功能旗標的環境（例如Bedrock），以及安裝或升級後的第一個工作階段除外。²¹⁹²²³

各版本的發布歷程請參閱變更記錄。

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

能否有效運用Claude Code，而不只是淺嘗輒止，關鍵在於五大核心系統。掌握這些系統後，Claude Code便能大幅提升您的工作效能：

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

重點摘要

• 五大系統決定使用成效：設定階層、權限、hooks、MCP與subagents掌控從行為到自動化的一切。
• 將工作推送至委派層：subagents會在乾淨的context window中獨立進行探索，僅傳回摘要，避免context過度膨脹。
• Hooks能保證執行，提示詞不能：針對無論模型如何運作、每次都必須執行的lint、格式化與安全性檢查，請使用hooks。
• 模型分級可節省成本，又不犧牲品質：將subagent探索工作交給較便宜的模型，並保留Opus處理真正需要架構推理的任務；如果品質是唯一考量，也可統一採用Opus。
• MCP將Claude連接至您的工具鏈：資料庫、GitHub、Sentry與3,000多項整合功能，讓Claude的能力不再侷限於讀取檔案與執行bash命令。

我花了數月時間，在正式環境程式碼庫、CI/CD管線與企業部署中，將Claude Code的能力推向極致。本指南濃縮了這些經驗，成為我初次使用時最希望能擁有的完整參考資料。每項功能均包含實際語法、真實設定範例，以及即使經驗豐富的使用者也容易踩到的陷阱。

選擇適合您的閱讀路徑

如何使用本指南

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

使用瀏覽器的Ctrl+F／Cmd+F，即可搜尋特定旗標、命令或設定鍵。文末的快速參考卡彙整了所有主要命令，方便快速瀏覽。

相關深度解析

以下部落格文章深入探討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 UI；此功能適用於互動式、-p 與 Remote Control 工作階段。/config --help（v2.1.183）會列出可用的簡寫鍵。v2.1.183 也調整了互動式 /config UI：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
  }
}

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

較新的設定（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 中強制套用模型限制；選擇受限模型時，會顯示「受您組織設定限制」的訊息。¹⁷⁶
• 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）：系統不再從儲存庫的 .claude/settings.local.json 讀取 autoMode 設定，請改在 ~/.claude/settings.json 中進行設定。如此可防止複製的儲存庫夾帶自動模式設定。¹⁸⁵

較新的設定（v2.1.217）：

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

較新的設定（v2.1.219）：

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

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

• modelPicker（使用者或受管理設定，v2.1.242+）：使用依序排列且附有標籤的模型清單，精選 /model 選擇器中的項目。此物件包含 options 陣列（每列都必須提供 model，並可選擇提供 label 與 description；model 會原樣採用，因此別名、Anthropic ID，以及 Bedrock／Vertex／Foundry／閘道 ID 均可使用），另可選擇設定 replaceBuiltInOptions 布林值（預設為 false，會將這些列附加在內建模型陣容之後；設為 true 則只顯示您設定的列、Default，以及工作階段目前執行的模型）。Claude Code 會從受管理設定、--settings 與使用者設定讀取此鍵，並忽略專案及本機設定，因此複製的儲存庫無法重新標記選擇器；設定此鍵的最高層級來源會提供完整模型陣容。availableModels 允許清單仍適用於每一列，而標籤只會改變選擇器的顯示內容，不會改變實際執行的模型。²⁴⁷²⁴⁵
• promptCacheTtl / subagentPromptCacheTtl（任何檔案，v2.1.242+）：可依每個請求儲存區設定 "5m" 或 "1h"，讓 API 金鑰與雲端供應商的使用者在主要對話中保留 1 小時快取，同時讓 subagents 維持 5 分鐘。請參閱快取策略。²⁴⁷²⁴⁵
• 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小時制、UTC 24小時制，或明確的strftime模式；timeZone則指定時區。²¹¹ 設定參考文件現已說明這兩個鍵。²²⁷
• permissions.blockReadsOutsideWorkingDirectories（v2.1.257）：直接拒絕讀取工作階段工作目錄以外的檔案。若未啟用，自動模式現在會在工作階段首次嘗試這類讀取前詢問一次（請參閱自動模式）。²¹¹ 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）：限制使用者可選擇的投入程度，可在頂層或modelSettings下針對個別模型設定；此限制適用於所有供應商，包括Bedrock、Vertex與Foundry。使用者仍可選擇低於上限的程度；這是管理員端與/effort相對應的設定。²¹⁶
• bashEditDiffEnabled（v2.1.269）：當Bash工具處理檔案編輯時，工具結果會附上該命令所變更檔案的差異，讓對話呈現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）：即使availableModels允許使用，deniedModels仍可封鎖特定模型。"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遭封鎖時顯示的錯誤現在也會指明此鍵。²²⁵ 設定參考文件現已說明此鍵：系統只會從裝置本身的受管理設定讀取，而且deniedMcpServers中若有claude-in-chrome項目，仍會封鎖該伺服器。²³³

較新的設定（v2.1.285）：

• allowedProviders（受管理，v2.1.285）：限制機器可使用哪些API供應商：Anthropic API、自訂端點、Bedrock、Mantle、Vertex AI、Foundry、AWS上的Claude Platform，或Cloud閘道。²²⁹ 設定參考文件已說明此鍵；即使伺服器管理的設定也提供一份清單，來自機器本身管理員來源的清單仍會生效，因此工作階段只能使用同時出現在兩份清單中的供應商。²³³

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

若您是為了尋找某個特定設定而來，以下是簡明索引。每個項目都會標示推出版本；若設定隸屬特定範圍，也會一併註明：

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
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_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_WORKFLOWS=1                         # Enable Workflow tool for deterministic multi-agent orchestration (v2.1.147+)
MAX_THINKING_TOKENS=10000                       # (Opus 4.6 and Sonnet 4.6 only — removed in Opus 4.7)
CLAUDE_CODE_MAX_OUTPUT_TOKENS=4000              # Limit output length
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1          # Enable agent teams (v2.1.32+)

雲端供應商設定：

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

行為控制：

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_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 # Longer base delay for the backoff when retrying an overloaded (529) request; example value, the release notes give no default (v2.1.292; release-notes only as of 2026-10-06)[^272]
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]
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=1                     # Enable forked subagents on external builds (v2.1.117+)[^160]
CLAUDE_CODE_FORCE_SYNC_OUTPUT=1                 # Force synchronized terminal output when auto-detection misses it, such as Emacs eat (v2.1.129+)[^164]
CLAUDE_CODE_SESSION_ID=...                      # Read-only: present in the Bash tool subprocess; matches the session_id passed to hooks (v2.1.132+)[^168]
CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1          # Skip the fullscreen alternate-screen renderer; keep the conversation in the terminal's native scrollback (v2.1.132+)[^168]
CLAUDE_EFFORT=...                               # Read-only: current effort level inside hooks and Bash tool subprocess (v2.1.133+)[^169]
CLAUDE_CODE_FORWARD_SUBAGENT_TEXT=1             # Include subagent text + thinking in stream-json output; pairs with --forward-subagent-text (v2.1.211+). Covers depth-2+ nested subagents as of v2.1.219[^205][^213]
CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=200    # Per-session WebSearch cap (default 200; v2.1.212+). 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     # Interactive WebSearch budget refill rate, 100 calls/hour by default; 0 turns the refill off (v2.1.290; release-notes only as of 2026-10-06)[^271]
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_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_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=2048     # Override the 2,048-char cap on MCP tool descriptions and server instructions, every server in the session (v2.1.280+)[^256]
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工作階段中的背景指令則不受時間限制。工具參考文件亦明確指出：「v2.1.288之前，此限制適用於所有工作階段。」²³⁴²³⁷

網路與Proxy：

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

使用者介面與終端機：

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory; 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_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]

專案設定無法開啟遙測功能（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 屬性：現在會在 LLM 請求 span 上發送 stop_reason、gen_ai.response.finish_reasons 與 user_system_prompt。由於 user_system_prompt 可能包含個人識別資訊（PII），因此只有在設定 OTEL_LOG_USER_PROMPTS=1 時才會發送。¹⁵⁴

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

v2.1.193+ claude_code.assistant_response 日誌事件：Claude Code 可將模型的完整回應文字作為 OTel 日誌事件發送，並由 OTEL_LOG_ASSISTANT_RESPONSES 控管。此控管機制有一項升級時務必留意的陷阱：若未設定 OTEL_LOG_ASSISTANT_RESPONSES，其行為會跟隨 OTEL_LOG_USER_PROMPTS，因此任何已記錄提示內容的部署環境，都會在升級後開始收到助理回應內容。若要讓遙測維持僅記錄提示，請設定 OTEL_LOG_ASSISTANT_RESPONSES=0。¹⁷⁹

v2.1.214 遙測功能新增項目：OTel 日誌事件現在會附帶 message.uuid、client_request_id 與 tool_source 屬性，用於訊息層級的關聯分析與工具來源追蹤；subagentStatusLine 承載內容包含 subagent 的推理強度，因此自訂狀態列可同時呈現模型與推理強度；此外，新的 CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH 環境變數可設定 OTel 內容屬性的 60 KB 截斷上限。¹⁹⁰

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

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+)
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[^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]

skills變數（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可在多個層級靈活切換模型。

可用模型

模型頁面列出 API 程式碼從 Sonnet 5 遷移時的 5 項破壞性變更：使用 between_tools 時會關閉預先思考、強制使用工具會傳回錯誤、思考區塊會綁定模型與對話、Claude API 與 Google Cloud 不接受 computer_20251124，以及 advisor 工具不接受以 Opus 4.8、Opus 4.7 和 Sonnet 5 作為 advisor。工具呼叫之間的文字也會在 thinking 區塊中傳回，因此串流顯示這些文字的介面會保持無聲，直到設定可傳回文字的 display 值為止。²³⁰

Claude Opus 5.5（2026年9月22日）： 自 v2.1.280 起，這是 Claude Code 中的新預設 Opus 模型；此外，根據模型設定文件中的方案對照表，它也是所有方案與第一方供應商的預設模型：包括 Pro、Max、Team、Enterprise、Anthropic API、AWS 上的 Claude Platform、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：輸入每 MTok $4，輸出每 MTok $20（Opus 5：$5／$25）；快取讀取費用為每 MTok $0.20，相當於輸入價格的 5%，僅為標準 10% 的一半（只有 Fable 5.1 與 Mythos 5.1 更低，為 2.5%）。1M token 上下文視窗，最大輸出 128K（在 Batches API 中搭配 output-300k-2026-03-24 beta header，最高可達 300K）。永遠啟用的自適應思考——模型概覽表將它標示為與 Fable 相同的「Adaptive (always on)」，而非 Opus 5 預設啟用但可關閉的形式。effort 預設為 medium（Opus 5 預設為 high），v2.1.280 也同步調整了沿用規則：在 /effort 改為依模型設定之前儲存的 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 欄位，改為選擇 effort 層級。
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 toolset；Bedrock 則保留舊版工具。

另一項變更雖不會導致要求失敗，卻會改變回應結構：模型在工具呼叫之間產生的文字會在 thinking 區塊中傳回，且在預設 display 設定下為空。串流顯示這段敘述的介面會保持無聲，直到將其設為 display: "updates"（beta）或 "summarized"。²²²

Claude Code 中依內容切換備援模型。 Opus 5.5 會搭配安全分類器執行，最常標記生物學與網路安全內容。若其中一個分類器標記某項要求，Claude Code 會改用另一個模型重新執行並顯示通知：遭生物學分類器標記的要求會轉至 Opus 5，遭網路安全分類器標記的要求則轉至 Opus 4.8；工作階段會繼續使用備援模型，直到您透過 /model 切換回原模型。若希望每次都先詢問，請在 /config 中關閉 Switch models when a message is flagged（switchModelsOnFlag: false）。²²³ 自 v2.1.287 起，切換時會保留目前的 effort 層級，而非採用備援模型的預設值。因此，在 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 層級以及 opus 別名所解析到的模型；以下是其於2026年7月推出時的概況。Anthropic 將其描述為 Opus 4.8 的直接升級版本：輸入價格同為每百萬 token 5 美元，輸出價格同為每百萬 token 25 美元、「以相同成本大幅提升效能」，而且在最高推理強度下，平均使用的 token 約比 Opus 4.8 少26%。它是 Claude Max 的預設模型，也是 Claude Pro 上最強大的模型。模型 ID：claude-opus-5——這是不含日期的固定快照，命名方式與 claude-opus-4-8 和 claude-sonnet-5 相同，並非持續指向最新版的指標。100萬 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一同移至文件的 Legacy models 表格——仍可使用，但不再是建議的預設選擇。¹⁹⁷

將 harness 從 Opus 4.8 移轉至 Opus 5 時，有兩項破壞性變更：¹⁹⁷

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

特別是在 Claude Code 中：Opus 5 的 effort 預設為 high（與 Claude API 相同），並提供完整層級——low、medium、high、xhigh、max。Anthropic 自己的移轉指南建議：若模型能力比 token 支出更重要，請測試 max effort。Fast mode 支援 Opus 5，價格為每百萬 token 10／50美元（請參閱 Fast Mode）。¹⁹⁷¹⁹⁸

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至2.1.256從未發布至 npm——v2.1.257（9月1日）才是首個可安裝且包含此模型的版本。模型 ID：claude-fable-5-1（Bedrock：anthropic.claude-fable-5-1）。其層級與每 token 價格和 Fable 5 相同——輸入每百萬 token 10美元、輸出每百萬 token 50美元、100萬上下文、最大輸出128K、自適應思考永遠開啟，且 effort 預設為 high——但有一項會影響長時間 agentic 工作階段的價格變更：快取讀取成本為每百萬 token 0.25美元，相當於輸入價格的0.025倍（2.5%），而非標準的10%；僅 Fable 5.1 和 Mythos 5.1 採用此費率，快取寫入價格則維持標準費率（5分鐘每百萬 token 12.50美元、1小時每百萬 token 20美元）。可靠知識截止日期：2026年6月（訓練資料亦截止於2026年6月）——這是所有現行 Claude 模型中最新的日期；2026年9月22日推出的 Opus 5.5（知識截止於2026年6月）以及9月28日推出的 Sonnet 5.5 均與之並列。最早不會在2027年9月1日前退役。

相較於 Fable 5，有三項破壞性變更：強制使用工具會回傳錯誤、較早的模型無法讀取其思考區塊，以及編輯先前輪次會使思考區塊失效。另有五項新增變更：每則訊息的 effort（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一同移至文件的 Legacy models 表格。

版本資訊另指出一項 gateway 注意事項：在 Claude apps gateway 工作階段中，fable 和 best 目前仍會解析至 Fable 5——尚未設定支援5.1的 gateway 會拒絕該模型——因此請在該處的 /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 將所有方案預設為 Opus 5.5 的設定取代（2026年9月22日）。^211238239221

Fable 5.1 推出期間修正（v2.1.260，9月3日）： 推出後的首個版本修正了四項不完善之處。對於有權使用 Fable 5.1 的組織，/model 選擇器現在會顯示該模型——在此修正之前，只有完整輸入 /model claude-fable-5-1 才能使用。Fable 5.1 的提示快取現在也涵蓋工具結果之後附加的上下文；先前這些內容會在每一個工具呼叫輪次都以未快取輸入重新傳送——無形中抵銷了0.025倍快取讀取費率原本要為長時間 agentic 工作階段帶來的經濟效益。在工作階段進行期間變更 /effort，也不再使提示快取失效。此外，當 ANTHROPIC_DEFAULT_FABLE_MODEL 固定值含有 [1m] 標籤時，model: fable agents 現在會正確採用該標籤，不再悄然以200K上下文視窗執行。²¹²

Claude Fable 5（2026年6月9日；自2026年9月1日起列為 legacy）： 這是位於 Opus 之上的新模型層級——Anthropic 最強大、最智慧的模型，在幾乎所有受測基準上皆達到最先進水準，並專為在數百萬 token 的上下文中維持連貫性而打造。Fable 5 是經過安全調整、可供一般用途使用的「Mythos-class」前沿模型：它內建安全分類器，遇到網路安全、生物化學和模型蒸餾查詢時會回退至 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 預設即包含100萬上下文視窗，因此不必加上 [1m] 後綴——而且自 v2.1.173（2026年6月11日）起，claude-fable-5[1m] 模型名稱會自動正規化／移除後綴，成為 claude-fable-5（該後綴僅對 Opus／Sonnet 有意義，因為這兩者需透過 [1m] 才能啟用100萬上下文）；最大輸出128K。價格為輸入每百萬 token 10美元、輸出每百萬 token 50美元——約為 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 相同，支援完整的 effort 層級（low／medium／high／xhigh／max，預設為 high）。Fable 5 無法關閉思考功能——工作階段思考切換開關、alwaysThinkingEnabled 設定以及 MAX_THINKING_TOKENS=0 均不會產生作用；模型一律採用自適應推理。完整的 fable 系列設定介面與 Opus 選項相互對應：ANTHROPIC_DEFAULT_FABLE_MODEL 可固定 fable 別名所解析到的模型（適用於 Bedrock／Vertex／Foundry），DISABLE_PROMPT_CACHING_FABLE 可讓 Fable 停用提示快取，而企業 gateway 則會依內容自動回退。/model opus 現在會選擇 Opus 5.5（v2.1.280；effort 預設為 medium，最困難的任務請使用 /effort xhigh），而且開箱即用的預設模型不再依方案而異——除了 Microsoft Foundry 之外，所有由 Anthropic 營運的方案皆預設使用 Opus 5.5；若您需要最高能力上限，請透過 /model fable 刻意選擇 Fable 層級——自 v2.1.257 起，這代表 Fable 5.1。^{258197207239220221} Opus 4.7（2026年4月16日）：上一代旗艦模型，目前仍完整提供。100萬token上下文視窗採用標準定價，不收取長上下文額外費用。最大輸出量為128K，僅支援adaptive thinking（已移除extended thinking），並新增xhigh effort層級，建議將其作為程式設計與代理型工作負載的起點。¹⁴⁵可靠知識截止日期：2026年1月。訓練資料截止日期：2026年1月。模型ID：claude-opus-4-7。定價與Opus 4.6相同，每百萬token輸入／輸出為$5/$25；5分鐘快取寫入為$6.25、1小時快取寫入為$10，快取讀取則為每百萬token $0.50。¹⁴⁴在SWE-Bench上，Opus 4.7解決的正式環境任務數量是Opus 4.6的3倍；CursorBench得分為70%（4.6為58%），在Anthropic包含93項任務的內部程式設計基準測試中，解決率也提升13%。¹⁴⁴此模型採用新的tokenizer；相同文字的token數量預計約為原本的1倍至1.35倍，因此請提高max_tokens的預留空間與壓縮觸發門檻。¹⁴⁵視覺功能支援最高2,576 px／3.75 MP的影像，並採用1:1像素座標。¹⁴⁵

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

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

自v2.1.280（2026年9月22日）起，各方案之間的差異已經取消：所有由Anthropic營運的方案與第一方供應商均預設使用Opus 5.5，唯一的例外是Microsoft Foundry。過去這裡最重要的問題——「我使用哪一種方案？」——如今已不再影響答案。

Opus 4.7中Messages API的破壞性變更（呼叫端可見）：¹⁴⁵

• 已移除extended thinking的budget_tokens。請改用thinking: {type: "adaptive"}。adaptive thinking預設為關閉；未包含thinking欄位的請求將不使用thinking。
• 將temperature、top_p或top_k設為非預設值會傳回HTTP 400。請省略這些參數，改以提示詞引導模型。
• 回應預設不包含thinking內容。請設定thinking.display: "summarized"以恢復可見的推理內容（若產品會將thinking串流傳送給使用者，則必須如此設定）。

任務預算（beta標頭task-budgets-2026-03-13）可透過output_config.task_budget，向模型提供涵蓋完整代理型迴圈的token目標；最低為20K token。¹⁴⁵

Opus 4.6（舊版）：目前仍可透過claude-opus-4-6使用，具備100萬token上下文與128K最大輸出量。若需要更出色的代理型程式設計能力，建議遷移至Opus 4.7。Opus 4.6最初於2026年2月5日發布。⁷⁹¹⁴⁴自v2.1.117（2026年4月22日）起，Pro與Max訂閱者使用Opus 4.6及Sonnet 4.6時，預設effort為high（先前為medium）；Opus 4.7則維持xhigh。這項調整恢復了3月4日至4月7日降低effort後受損的智慧水準；相關情況記載於4月23日的事後檢討中。¹⁵²¹⁵³

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（無日期的固定快照）。100萬token上下文視窗、128K最大輸出量（在Batches API上搭配output-300k-2026-03-24 beta標頭時，最高可達300K），且僅支援adaptive thinking。可靠知識截止日期：2026年1月。定價：每百萬token輸入／輸出為$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）的模型，直到v2.1.280於2026年9月22日將這些方案改為Opus。Sonnet 5如今已不是Claude Code任何方案的預設模型；自v2.1.284起，/model sonnet在Anthropic API上會改選Sonnet 5.5。若要繼續使用Sonnet 5，請使用/model claude-sonnet-5或ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-5。請參閱上方的方案表格。^{181207220221228}

Sonnet 4.6（2026年2月17日，現已由Sonnet 5取代）：均衡型模型；取代Sonnet 4.5，成為claude.ai與Claude Cowork的預設模型。⁹³定價與Sonnet 4.5相同（每百萬token為$3/$15）。提升代理型搜尋效能，同時減少token用量。支援extended thinking、adaptive thinking，以及100萬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時，每個工作階段的成本為$0.10至$0.45。使用定價為$4/$20的Opus 5.5時，相同工作階段的成本為$0.40至$1.80，高出4倍（尚未計入提示快取折扣）。若任務不需要Opus，請使用Sonnet或Haiku。¹²²²

各模型的適用時機

Haiku：適合用於執行探索、簡單檔案搜尋與快速問答的subagents。其成本約比Opus低5倍，回應速度也更快。非常適合不需要深度推理的背景任務。 Sonnet：當成本至關重要時，適合日常開發的主力模型——自v2.1.284起，Anthropic API採用Sonnet 5.5，價格與Sonnet 5相同，皆為每MTok $2/$10²²⁸——而且自v2.1.280將Pro和Team Standard改用Opus後，它便不再是任何方案的預設模型（原生1M context，標準定價為每MTok $2/$10；原訂於9月1日調漲的價格已取消）。^181248207220 這正是此處需要掌握的變化：Sonnet如今是需要主動選擇的模型，而選擇它的理由可歸結為成本計算——同樣具備1M context，每token成本僅為Opus 5.5的一半。它足以處理大多數程式開發任務，包括實作功能、修正錯誤、撰寫測試與程式碼審查。歷史沿革：長期以來，包括本指南在內，皆將v2.1.197（2026年6月30日）描述為讓Sonnet 5成為所有環境的預設模型；然而，模型設定文件按方案區分的說明顯示，premium/API自v2.1.154起預設使用Opus 4.8，自v2.1.219起則使用Opus 5，因此所謂「所有環境」其實僅指標準層級——而v2.1.280連這項預設也告終止。Sonnet 4.6則一路擔任Sonnet層級的主力，直至2026年6月。^93147207221 當您需要更低廉的token、更快的回應速度，或更符合成本效益的subagents時，請選擇Sonnet。

Opus：深度推理層級——自v2.1.280起，opus別名會選用Claude Opus 5.5（每MTok $4/$20、1M context，effort預設為medium）；自該版本起，所有方案也都會以Opus作為起始模型。因此，真正需要判斷的是何時該離開它：進行架構決策、棘手的除錯、理解複雜系統、安全性分析及長期自主代理工作時，請繼續使用Opus；若任務已屬例行工作，且token價格減半比額外推理能力更重要，則切換至/model sonnet。²²⁰²²¹（從v2.1.219至v2.1.278，opus別名會解析為每MTok $5/$25的Opus 5。）¹⁹⁷ 本段其餘內容描述Opus 4.7於2026年4月16日推出時的情況，保留供歷史參考。¹⁴⁴¹⁴⁷ Opus 4.7在SWE-Bench上解決的實際生產任務數量比Opus 4.6多3倍；CursorBench得分為70%（相較之下，Opus 4.6為58%）；在93項內部程式開發基準測試中，解決率則提高13%。¹⁴⁴ Claude Code在Opus 4.7上預設採用xhigh effort，並可透過/effort調整（v2.1.111以上版本）。¹⁴⁶¹⁴⁷ Max訂閱者可透過Anthropic API在Opus 4.7上使用Auto Mode，無須指定--enable-auto-mode；其他方案與供應商的可用性則依方案及管理員控制而定。¹⁴⁶ 1M context採標準定價——不收取long-context額外費用。值得留意的行為變化：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後，只會顯示這些列、Default及工作階段目前使用的模型。此鍵會忽略專案與本機設定，而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會設定subagent的預設模型，而非覆寫所有設定：agent定義中的model:與每次spawn時明確指定的模型，優先順序都高於它。²⁰⁶ 自v2.1.257起，CLAUDE_CODE_SUBAGENT_MODEL_FORCE可選擇性恢復舊有行為：它會將CLAUDE_CODE_SUBAGENT_MODEL（若未設定，則使用主要對話的模型）套用至每個subagent，忽略每次spawn時選取的模型及agent定義中的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現在也會先在備援模型上重試該輪對話一次，再顯示失敗。因此，短暫的主要模型問題可以平順降級處理，不致直接中斷該輪對話。²⁶⁰ 自v2.1.286起，若Anthropic API拒絕使用預設模型或別名解析出的模型，Claude Code會改用同層級的前一個模型重試一次，避免每輪對話都失敗；若因拒絕或--fallback-model而重試至無法使用fast模式的模型，則會以標準速度執行。²³¹

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

擴充Context

對於大型程式碼庫或長時間工作階段，請啟用1M token context：

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 apps gateway亦是如此：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 context視窗——不收取long-context額外費用。¹⁴⁸ 900K-token請求與9K-token請求採用相同的每token費率計費。Prompt caching與批次處理折扣均以標準費率套用至完整context視窗。

[1m]變體的使用資格取決於方案：具備1M context的Opus 4.6包含在Max、Team和Enterprise方案中；具備1M context的Sonnet 4.6則在所有訂閱方案（包括Max）中都需要使用額度。²³³（具備1M的Opus自v2.1.75，即2026年3月13日起，成為Max、Team和Enterprise的預設模型。）¹¹⁷¹⁴⁷ API與隨用隨付使用者可按標準每token費率完整使用1M context。¹⁴⁷ 若要在模型選擇器中停用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維持在200K；這些平台已改以1M為預設值。²³²

自v2.1.247起，Sonnet 5的預設自動壓縮視窗為完整的1M上下文：採用1M視窗的工作階段現在會在約967K個token時自動壓縮，而非約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-tool輪次計為約實際上下文大小兩倍的問題——這曾導致自動壓縮在實際視窗約一半時便觸發。²¹⁷

查看目前模型

> /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或AWS上的Claude Platform。存取權限受到管制：請聯絡您的客戶經理或加入候補名單。^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"。若您的harness鎖定4.7，且仰賴快速模式請求自動無聲降級，現在這類請求將直接失敗；請將鎖定版本遷移至Opus 5.5、Opus 5或Opus 4.8。¹⁹⁸

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

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

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

操作注意事項。快速模式有獨立於標準Opus限制的速率限制；超出後會傳回含retry-after的429（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

Effort控制（v2.1.111+，Opus 4.7）

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

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

依模型儲存（v2.1.251+）：/effort 現在會依模型儲存您的預設 effort 層級，因此切換模型時，每個模型都會保留各自的設定——您在 Opus 上慣用的 xhigh 不再跟著套用至 Haiku（CHANGELOG：「已變更 /effort，依模型儲存您的預設 effort 層級，因此切換模型時，每個模型都會保留各自的設定」）。max 僅限當次工作階段的例外規則仍然適用。²⁰⁶ v2.1.284 滑桿按鍵：effortSlider:decreaseEffort、increaseEffort 和 toggleUltracode 按鍵繫結動作，讓您能在 keybindings.json 中重新繫結滑桿的方向鍵與 Tab 鍵。²²⁸ v2.1.257 改進兩項調整功能：/effort 接受 s 來指定僅限當次工作階段的選項，與 /model 的慣例一致；--effort 旗標現在也僅適用於當次工作階段——它只會在該工作階段解除新模型對預設 effort 的鎖定，而不會永久變更（CLI 參考文件指出，它會「覆寫」預設值，「僅適用於本次工作階段且不會持續保存」）。²¹¹²⁴⁰

Max 上的 Auto Mode（v2.1.111+）

Auto Mode 是所有方案與供應商在互動式終端機及 VS Code 工作階段中的內建初始權限模式（v2.1.283-284）；自 v2.1.285 起，在第三方供應商或停用遙測時，claude -p 與 Python Agent SDK 工作階段亦採用此模式。自 2026年8月14日起，它便已成為 Pro、Max 和 Team 的預設模式（於 8月7日公布）。如需查看公告中的研究數據、退出方式，以及仍以 Manual 啟動的工作階段，請參閱權限模式。^{203226227228229}

自 v2.1.210 起，另一個獨立的分類器模型 Claude Sonnet 5 會在每項動作執行前進行審查，確認該動作符合您的意圖且安全無虞。¹⁸⁷ 若要以 auto mode 啟動工作階段，請使用 --permission-mode auto；v2.1.111 已移除舊有的 --enable-auto-mode 旗標。

可用範圍的擴展歷程：

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

Auto Mode 並非安全邊界。下文大多是在強化分類器，而分類器並不是沙箱。2026年8月26日，提示詞注入研究員 Johann Rehberger 公布了一條可在 auto mode 下攻擊 Claude Code Opus 5 的有效攻擊鏈。他指出，在小型樣本中，攻擊成功率為 60% 至 80%——主要攻擊鏈會產生隔離的 python3 子行程，5 次執行中成功 3 次；另一個變體的酬載會產生無頭 claude -p 執行個體，其兩種設定分別在 5 次執行中成功 3 次與 4 次。他也特別提醒，這些只是小型樣本，並非普遍性的攻擊成功率衡量結果。²¹⁰ 這條攻擊鏈值得深入理解，因為其中每個步驟看似都合情合理：伺服器以 HTTP 415 回應 WebFetch，促使 Agent 改用 curl；下載的封存檔展開至暫存目錄，其中包含一份資訊清單、7 筆以 Base85/zlib 編碼的資料記錄、一個原生二進位檔，以及一個 struct.py；Claude 拒絕執行不受信任的二進位檔，接著自行撰寫 Python 解碼器，並從該目錄內執行；解碼器匯入 base64，base64 再匯入 struct，而 Python 會優先解析到攻擊者的 struct.py。整個流程中沒有任何顯然惡意的指令——注入只需讓受攻擊路徑看起來像是完成任務最合理的方式。Rehberger 另指出，在少數幾次執行中，Claude 察覺系統遭入侵後曾嘗試終止惡意軟體行程，但 auto mode 拒絕了清除指令。²¹⁰ 他將整項發現與 Anthropic 曾宣傳的一項數據並列討論：一項委託第三方進行的評估指出，Opus 5 在 auto mode 下，針對 72 種情境各執行 10 次後，提示詞注入攻擊成功率為 0.00%。他的攻擊鏈並未包含在該測試集中，因此 0.00% 的基準測試結果與有效的程式碼執行攻擊鏈可以同時為真；他認為這兩項訊息彼此扞格不入。²¹⁰ 另外也應留意其分類：Simon Willison 在 8月30日的更新中認同一位讀者的觀點，指出這並非典型的提示詞注入——模型從未讀取並遵循攻擊者的指令——而是混淆環境攻擊。²¹⁰ Anthropic 將該報告以「資訊性」結案——亦即此行為符合設計預期——而 Rehberger 轉述的立場，正是設計時應依循的前提：auto mode 是盡力而為的分類器，並非安全保證；由個別看似無害的步驟組成、刻意設計的注入鏈，並不屬於分類器預期能攔截的範圍；真正的圍堵邊界是作業系統層級的隔離與網路出口控制。²¹⁰ 這並不與下方的強化措施矛盾——反而是理解這些措施的正確框架。Auto mode 能減少需要回應的提示數量，並封鎖文件中列明的破壞性操作；但它無法讓處理不受信任輸入的工作階段變得安全。若工作階段會接觸可能受攻擊者影響的內容——擷取的網頁、下載的封存檔、議題文字、第三方 MCP 伺服器——真正能限制損害的，是模型之外的控制措施：容器或 VM、受限的網路出口、監控代理程式的實際行為，以及不存放您不願遺失之 SSH 金鑰與雲端憑證的家目錄。Auto mode 核准並不能證明某項操作安全無虞。

在不失去預設規則的情況下自訂規則（v2.1.118+）。 舊版中的 autoMode.allow、autoMode.soft_deny 與 autoMode.environment 只能二選一：定義自己的清單，就會失去內建安全規則。$defaults 哨兵值解決了這個問題——它會在您放置的確切位置，原地展開為內建清單，讓您能在其前後疊加自訂規則：¹⁵²

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

從 /permissions 編輯分類器規則（v2.1.246）。 執行 /permissions 並開啟 Auto mode 分頁；只有工作階段可使用 auto mode 時，這個分頁才會出現。它會列出分類器從所有範圍讀取的 allow、soft_deny、hard_deny 與 environment 項目，並顯示各區段是否套用內建規則；來自受管理設定或 --settings 的項目為唯讀，所有變更都會儲存至 ~/.claude/settings.json。在區段中新增第一條規則時，系統也會插入 "$defaults"，確保內建規則持續生效。您可以分別切換各區段的內建規則（區段至少要有一條自訂規則，才能停用其內建規則），而 environment 會在編輯器中以單一文件開啟。²⁴⁶²⁴⁴

「不要再詢問」選擇加入（v2.1.118+）。 Auto Mode 的選擇加入提示現在提供「不要再詢問」選項，經常使用的使用者無須撰寫旗標指令碼，即可隱藏說明。

破壞性指令防護措施（v2.1.183）。 除非您在工作階段中明確要求，否則 auto mode 現在會硬性封鎖一組無法復原的指令：當您未要求捨棄本機工作時，封鎖破壞性的 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）。 根據預設，auto mode 分類器只會審查符合任意程式碼執行模式的 shell 指令；例行指令則會略過。新的 autoMode.classifyAllShell 設定會改為將所有 Bash/PowerShell 指令交由分類器處理。若希望每次 shell 呼叫都經過審查，可用些許延遲換取更嚴密的安全防護。同一版本也會在對話記錄、拒絕快顯通知及 /permissions 的近期拒絕項目中顯示 auto mode 拒絕原因，因此指令遭封鎖時，現在會說明封鎖理由。¹⁷⁹

新增三項強化規則（v2.1.205）。 Auto mode 現在會封鎖竄改工作階段對話記錄檔案的行為——稽核軌跡本身禁止代理程式存取；在對無法從情境解析的變數執行 rm -rf 前，系統會先行詢問——藉此防止 rm -rf $DIR 中 $DIR 未知所引發的意外；此外，背景工作通知現在會明確註明未曾收到任何人為輸入，使對話記錄中偽造的「使用者已核准」文字，無法被粉飾成可據以執行的核准。¹⁸³ 第三項是值得牢記的提示注入防禦：核准必須透過核准管道送達，而工具框架現在會明確表達這項前提。

指令替換無法再隱藏災難性操作（v2.1.208）。 即使將 rm -rf ~ 等災難性移除操作藏在 $(...)、反引號或程序替換（<(...)）之中，現在仍會觸發提示——而且即使在 --dangerously-skip-permissions 與 auto mode 中也會提示。將破壞性指令包在替換語法裡，再也無法蒙混繞過安全防護。¹⁸⁶

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

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

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

圍堵逃逸規則（v2.1.257）。 分類器的「永不自動核准」清單新增了「圍堵逃逸」規則：除非環境將其標示為預期行為，否則雲端中繼資料憑證擷取、規避網路出口限制及跨租戶存取，都不再獲得自動核准。請依照上述注意事項所建立的框架理解此變更：這是分類器持續強化的一環——新增一類記載於文件中的拒絕項目，並未改變 auto mode 的本質。²¹¹

首次讀取工作目錄以外的檔案時提示（v2.1.257）。 Auto mode 現在會在工作階段首次讀取工作目錄以外的檔案前詢問一次；自 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）。 在此版本之前，若安全檢查未能傳回可用的判定，auto mode 並沒有因應方式；從操作人員的角度來看，兩種缺口的表現如出一轍：某個回合持續打轉，在永遠不會獲准的操作上耗費 token。v2.1.280 為兩者分別提供了終止狀態。

伺服器審查涵蓋更多命令（v2.1.281）。 在分類器審查於伺服器端執行的情況下，唯讀與沙箱化的shell命令現在也會等待審查，並在被標記時遭到封鎖。拒絕訊息也有所變更，使Claude將拒絕視為涵蓋該操作結果，而不只是完全相同的命令。工作階段在新處理程序中恢復後，分類器可重複使用先前的prompt cache，無須重新寫入。/insights也新增auto mode建議，估算auto mode原本可在您近期的工作階段中處理多少個權限提示。²²⁴

無人值守的工作階段不再持續等待rm提示（v2.1.281）。 在auto mode與--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變數後接頂層目錄名稱、目標為衍生自工作目錄的變數，或目標僅包含反斜線。²²⁴

行內! shell不再經過分類器；subagent的交接則改由分類器審查（v2.1.271）。 這兩項是機制調整，並非新增拒絕類別。skill或slash command中的行內! shell命令，現在會遵循default mode的權限規則，而非分類器；若沒有任何規則能判定某個命令，該命令會以受審查的tool call執行。此外，subagent現在會透過專用的交接呼叫向呼叫端回報，並由安全分類器審查；不再於事後審查其最後一則訊息——檢查點已從交接後移至交接動作本身。²¹⁶

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）請求時的退避基礎延遲；版本資訊未提供預設值。Agent tool新增effort參數，因此Claude能以您指定的effort等級執行sub-agent；截至10月6日擷取的subagents文件，僅將effort記載為frontmatter欄位。claude plugin install --marketplace <source>可透過單一shell命令新增marketplace並從中安裝。每次安裝時，本機（stdio）MCP伺服器現在預設協商2026-07-28版協定，亦涵蓋Bedrock、Vertex與Foundry；若要停用，請設定MCP_PROTOCOL_NEGOTIATION=legacy。Agent名稱上限為256個字元：超出上限的名稱會遭拒；skill或plugin檔案中過長的name會被忽略；subagents文件現在也明確記載name欄位的上限。若subagent檔案中的名稱過長，該檔案會被略過，並在debug log中記錄錯誤。一項安全性修正可防止PreToolUse hook核准與auto mode繞過讀取網路（UNC）路徑檔案時的提示。Mods新增prompt.autocomplete、$.model.complete中的prompt caching，以及agent.spawn中的workflow agents；claude plugin test現在也會因stub answer遭拒而失敗。除本指南引用文件頁面的項目外，截至2026年10月6日，這些內容僅見於版本資訊。²³⁶²³⁷

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設定。²³⁵²³⁷

v2.1.290，teams與gateways。 Claude apps gateway的登入核准頁面新增Deny按鈕，最低支援的PostgreSQL版本則從14降至11。在self-hosted runners上，claude --environment <id>會透過目前的Sessions API建立工作階段。claude --teleport與/teleport會拒絕可能刪除檔案的stash：當某個資料夾取代同名的已追蹤檔案時，即屬此情況；--channels relay則會忽略重複的回覆ID，而非誤核准另一個提示。在Slack中，!fast可將討論串切換至fast mode，!fast off則可切換回原模式。VS Code預設顯示訊息時間戳記（可透過Claude Code: Show Message Timestamps設定將其關閉）。²³⁵

v2.1.289（10月3日）。 Mods新增供teammates使用的agent.spawn、在plugin hook事件之間共用同一個agent id，以及$.agent.list()中的idle與waiting狀態；claude plugin validate不再略過資料夾中同時包含marketplace manifest的plugin；此外，sandbox auto-allow下的兩個Bash拒絕規則漏洞也已修補。²³⁵²³⁷

v2.1.288（10月2日）。 claude project purge現已更名為claude purge；舊名稱仍可使用，但會顯示通知。背景命令的時間限制僅適用於無人值守的工作階段（-p、Agent SDK、CI、cloud）。/code-review --max-findings <n>|all可變更發現項目的數量上限，直到您傳入--max-findings default為止。/autocompact會依model儲存其window。CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS可針對拒絕structured outputs的Mantle或gateways停用該功能。路徑範圍規則與巢狀CLAUDE.md檔案現在會在Write和Edit時載入，不再只於Read時載入。Language servers會在60秒後逾時（每個伺服器的requestTimeout），不再無限期停滯。在auto mode下，若對話長度超出client-side classifier的處理能力，系統會壓縮對話，而非對每個tool call顯示提示；client-side classifier也會忽略將Claude Sonnet 5.5或Opus 5.5指定為名稱的ANTHROPIC_DEFAULT_SONNET_MODEL固定設定，改用Claude Sonnet 5。Mods新增$.ui.selection()；未配備GitHub CLI的雲端工作階段會提供內建gh api；在空白提示上按下Up，可恢復先前由Ctrl+C清除的草稿。²³⁴²³⁷

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

推播通知（v2.1.110+）

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

Windows PowerShell工具（v2.1.111+，分階段推出）

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

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

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

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

分散式追蹤（v2.1.110+）

SDK與無頭工作階段現在會從環境讀取TRACEPARENT和TRACESTATE，將Claude Code執行作業串聯至分散式追蹤。搭配OTEL_LOG_RAW_API_BODIES=1（v2.1.111+），即可將完整的API要求／回應本文以OpenTelemetry日誌事件形式發出，便於偵錯。¹⁴⁶

原生二進位檔發行方式（v2.1.113+）¹⁵⁰

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

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

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

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

Subagents若在串流途中停滯，現在會在10分鐘後明確回報錯誤，不再無聲懸置。可搭配CLAUDE_STREAM_IDLE_TIMEOUT_MS（v2.1.84+）使用，更全面地涵蓋串流API的程序卡住問題。

v2.1.114穩定性修正¹⁵⁰

v2.1.114（2026年4月18日）僅包含一項修正：當Agent Teams隊友要求工具權限時，權限對話框可能會當機。若您使用Agent Teams，建議升級。

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

Anthropic宣布為Claude生成的內容加入機器可讀標記，起因是歐盟《人工智慧法》第50條（自2026年8月2日起，對新推出的AI系統具有強制效力）。此系統包含兩個元件：生成文字中的不可見統計浮水印，以及依循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的模型頁面與最新功能頁面，都未提及標記。^238222230 8月前模型的輸出不含任何標記，無論文字或檔案皆然；較新模型的輸出則會在所有介面上帶有標記，包括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 個前綴漏洞：在 /clear 後繼續的工作階段（重新啟動、--continue、--resume），若 SessionStart hook 印出輸出，首則訊息會遺漏一部分，造成提示詞快取完全未命中；恢復的 subagents 與隊友會重新呈現已載入的 MCP 工具定義，破壞該代理的提示詞快取；先前記錄於對話中的附件則會在恢復或重新啟動後重新呈現，導致延伸思考內容遺失並錯過提示詞快取。這與 v2.1.265–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 5 小時速率限制加倍，取消 Pro 與 Max 帳戶在尖峰時段的用量縮減，並「大幅」提高 Claude Opus 模型的 API 速率限制。其容量保障來自 SpaceX Colossus 1 協議：「當月內新增超過 300 百萬瓦的運算容量（超過 220,000 顆 NVIDIA GPUs）。」¹⁵⁷

自2026年9月14日起的每週限制（8月29日公告）：自 5 月提升用量以來實施的臨時每週限制增加 50% 措施，將於 9 月14日結束，並由永久措施取代：Pro、Max、Team 與按席次計費的 Enterprise 方案，相較提升前的基準永久增加 25%。依 Anthropic 對這項變更的計算：「與目前相比，Claude Code 的每週限制實際將減少 17%。」如果目前的每週上限為 150 單位，9 月14日起將變為 125。5 小時限制不在本次公告範圍內；5 月的加倍措施依然有效。若您會執行長時間的無人值守工作階段，現在就應針對較低的上限進行規劃：重設時自動繼續切換開關（v2.1.234）與 /usage，是兩項最重要的控制工具。²¹³

API Token 定價（2026年9月）^1144222

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

1M 上下文定價（2026年4月）：Opus 4.7、Opus 4.6、Sonnet 4.6 與 Mythos Preview 均以標準每 MTok 費率提供 1M 上下文，不收取長上下文額外費用。¹⁴⁸ 這是近期統一後的定價；先前關於 Opus 4.6 或 Sonnet 4.6 在輸入 token 超過 200K 後，須支付 2 倍輸入／1.5 倍輸出費用的說明，已不再適用。舊版 Opus 4.5 及更早的模型，仍維持原本的定價結構。

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

提示詞快取可大幅降低重複輸入的成本：快取寫入費用為基礎價格的 1.25 倍（5 分鐘快取）或 2 倍（1 小時快取），但快取讀取僅為 0.1 倍，可節省 90%。另有兩個費率更低的例外：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%）。²³⁸²²² 對於會重複使用上下文的 RAG 系統與程式碼助理，快取可降低 88–95% 的成本。

批次 API 為隔夜測試套件等非緊急任務提供 50% 折扣，並於 24 小時內完成。

多帳戶政策⁵²

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

允許的情境：

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

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

實際案例：2026年1月，進階使用者 Jeffrey Emanuel（@doodlestein）的 22 個 Max 帳戶遭自動標記並暫時封鎖。Anthropic 員工 Thariq（@trq212）確認屬於正當使用後，在 4 小時內解決問題。如果您同時在多個帳戶中大量使用 Claude Code 處理工作與個人專案，這正是服務原本支援的使用方式；但請勿試圖鑽系統漏洞。

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

成本因素

實際成本範例

成本依牌價計算（Haiku 4.5 每 MTok 為 $1/$5、Sonnet 5.5 為 $2/$10、Opus 5.5 為 $4/$20），尚未計入提示詞快取折扣。

節省成本要點：使用 Haiku 執行探索型 subagents，並以 Sonnet 進行實作，相較於所有工作皆使用 Sonnet，通常可降低 40–50% 的成本。

團隊成本管理

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

隱藏的工具費用

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

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

節省成本的策略

1. 使用 Haiku 執行 subagents：多數探索工作不需要 Sonnet
2. 啟用提示詞快取：預設已啟用，但請確認未遭停用
3. 設定最大輪次：claude --max-turns 5 可防止對話失控
4. 設定金額上限：claude --max-budget-usd 5 會在支出達到上限時強制停止工作階段。自 v2.1.217 起，此上限也會管控背景 subagents——達到上限後，系統將拒絕產生新的代理，並停止正在執行的背景代理（過去背景代理不受預算限制）¹⁹⁴
5. 使用規劃模式進行探索：不執行操作，就不會意外觸發高成本作業
6. 主動壓縮：上下文越小，token 越少
7. 限制輸出：export CLAUDE_CODE_MAX_OUTPUT_TOKENS=2000
8. 非緊急工作使用批次 API：輸入與輸出 token 均享 50% 折扣
9. 分析專案的 Claude API 支出：/claude-api cost-optimize（v2.1.247+）會分析現有專案的 Claude API 支出，並逐一透過可量測的變更調整各項成本槓桿（快取、token 整理、批次處理、投入程度、模型選擇）。此功能適用於您使用 API 建置的應用程式，而非 Claude Code 工作階段本身²⁴²

監控用量

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

背景 Token 用量

部分操作會在背景消耗 token： - 為 /resume 進行對話摘要 - /cost 與 /status 命令 - 自動壓縮

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

Claude Code Analytics 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"

使用情境： - 開發人員生產力分析（工作階段、commits、PRs） - 工具使用指標（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

該選擇哪種Hook類型？

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

何時該使用/fast？

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

/fast可切換目前工作階段的快速模式。它仍會使用相同模型——Opus 5.5（自v2.1.280起的快速模式預設模型）、Opus 5或Opus 4.8——但會最佳化輸出速度。它不會切換至較便宜的模型；以Opus 5.5每MTok輸入／輸出$8／$40（Opus 5與4.8則為$10／$50）的價格計算，也不會比較便宜。^196198223

權限系統如何運作？

Claude Code 的權限系統可精細控制允許執行的操作。無論是確保安全性，還是提升工作流程效率，理解此系統都至關重要。若要瞭解如何透過受管理的設定，在整個組織內強制套用權限，另請參閱企業部署。

權限層級

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

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

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

修改工具首次執行時，Claude Code 會提示您核准。除非另有明確設定，核准狀態會在該工作階段內持續有效。

EndConversation 工具（v2.1.214）。Claude Code 現在具備與 Claude 自 2025 年起在 claude.ai 上相同的結束對話能力：遇到極少數極具侮辱性的輸入或持續嘗試 jailbreak 時，Claude 可透過內建的 EndConversation 工具直接結束工作階段。這是為了抵禦濫用並保障模型福祉，而非工作流程功能；一般開發工作階段不會觸發此工具。¹⁹⁰¹⁹³

權限模式

v2.1.285 將此變更擴及非互動式工作階段。第三方供應商或停用遙測時的 claude -p 與 Python Agent SDK 工作階段，若未設定權限模式，現在會「如同互動式工作階段」以自動模式啟動；--permission-mode 仍可覆寫此行為。當使用者設定的預設值為其他模式時，詢問是否要將自動模式設為預設權限模式的一次性提示，現在也會出現在第三方供應商與停用遙測的情況。於 10月1日擷取的權限模式文件目前也與此一致：在 v2.1.285 或更新版本中，未擷取功能旗標的 -p 或 Agent SDK 工作階段（例如使用第三方供應商或停用遙測時）會以 auto 啟動；會擷取功能旗標的工作階段則以 default（Manual）啟動。若組織政策未提供 auto 預設值，工作階段也會以 default（Manual）啟動。²²⁹²³³

v2.1.283 與 v2.1.284 將互動式預設值擴及所有方案與供應商。自動模式現在也是 Enterprise、Claude API 與第三方供應商之互動式終端機和 VS Code 工作階段的內建起始模式。若要維持 Manual，請在 ~/.claude/settings.json、專案的 .claude/settings.json 或受管理的設定中，將 permissions.defaultMode 設為 "default"；專案設定檔中的 "auto" 值不會生效。²²⁶²²⁷v2.1.283 的版本說明明確提及第三方供應商與停用遙測的工作階段；v2.1.284 的說明指出，此預設值適用於「所有方案與供應商」；權限模式文件則將該預設值追溯至 v2.1.283。²²⁷²²⁸此外，自 v2.1.284 起，自動模式在讀取工作目錄以外的位置前所顯示的提示，新增了 Yes, but ask again next time 選項。此選項只允許當次讀取，後續讀取仍會再次詢問。²²⁸

自動模式於 2026年8月14日成為 Pro、Max 與 Team 的預設模式——此變更於 8月7日公布，並於正式切換當天在官方權限模式文件中確認上線。文件目前的措辭還補充了兩項值得留意的適用範圍細節：此預設值適用於新的工作階段；而且「除非您接受一次性的切換提示，否則自行設定的預設值會維持不變；由組織管理的預設值也不會改變。」這些方案的新工作階段會以自動模式啟動；該模式「會透過分類器檢查每次工具呼叫，旨在阻擋不可逆、具破壞性或以您環境之外為目標的操作。」Anthropic 說明這項切換的依據：一項涵蓋 1,053 名測試者的研究顯示，自動模式攔截了 89% 的危險指令，而人工審查僅攔截 13.6%；況且使用者仍會核准 97% 的權限提示，這正是手動審查在實務上成效不彰的原因。分類器的 token 額外用量不再向 Pro/Max/Team 計費（自公告發布時起生效）。按一次 Shift+Tab（或使用桌面版的模式下拉式選單）即可切換回原模式；如要固定使用其他預設模式，可在設定中配置 defaultMode；組織管理員則可透過受管理的 disableAutoMode 設定，完全停用自動模式。切換當時，Enterprise、Claude API、AWS 上的 Claude Platform、Bedrock、Google Cloud 的 Agent Platform 與 Foundry 仍需選擇啟用；Anthropic 當時計畫在「接下來一個月內」將預設模式擴及這些平台。²⁰³若要瞭解自動模式未承諾的能力，以及研究人員示範並促使 Anthropic 作出說明的繞過方式，請參閱Max 上的自動模式。

即使使用 acceptEdits，程式碼執行設定檔現在也會要求確認（v2.1.160）。acceptEdits 會自動核准一般編輯，但自 v2.1.160 起，在寫入可能默許執行指令的檔案前會暫停並顯示提示，包括 shell 啟動檔（.zshenv、.zlogin、.bash_login）、~/.config/git/，以及建置工具設定（.npmrc、.yarnrc*、bunfig.toml、.bazelrc、.pre-commit-config.yaml、.devcontainer/ 與其他類似項目）。理由是，編輯這類檔案可能讓下一次啟動 shell、安裝套件或提交變更時成為執行程式碼的途徑。因此，即使在通常會直接放行編輯的受信任專案模式中，這些操作仍須經過明確把關。其威脅模型與現有的 .claude/、.git/ 和 .vscode/ 寫入保護相同，只是進一步涵蓋範圍更廣的「編輯後即可執行」檔案。²⁶²

自動模式（v2.1.85+）：比 --dangerously-skip-permissions 更安全的替代方案。每次執行操作前，會由獨立的分類器模型（自 v2.1.210 起為 Claude Sonnet 5，最初為 Sonnet 4.6）進行審查，確認操作符合使用者意圖且安全無虞。¹²⁴¹⁸⁷

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

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

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

# Enable at startup
claude --permission-mode auto

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

自動模式不再需要選擇啟用（v2.1.152），可在 Bedrock／Vertex／Foundry 上運作而無須設定環境旗標（v2.1.207），並於 2026年8月14日成為 Pro／Max／Team 的預設模式。自 v2.1.283-284 起，它也是所有方案與供應商之互動式工作階段的內建起始模式。^{264185203226228} YOLO 模式（v2.0.68+）：若要在不使用任何安全分類器的情況下完全自主執行，請使用 --dangerously-skip-permissions 旗標。此旗標會一概同意所有操作：檔案編輯、Bash 命令以及所有工具呼叫。「危險」一詞是刻意為之。對大多數使用情境而言，建議改用 Auto Mode。⁵⁴

claude --dangerously-skip-permissions

透過 CLI 設定模式：

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

在工作階段期間切換：

Shift+Tab  # Cycles through modes

在 settings.json 中：

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

defaultMode 的範圍限制（v2.1.257）：專案的 .claude/settings.json 或 .claude/settings.local.json 已無法設定 defaultMode: "bypassPermissions"——其中的值會被忽略，與原本的 "auto" 相同。文件現在明確說明這項規則：permissions.defaultMode 的 auto 與 bypassPermissions 值「不會從專案或本機設定生效」——請在使用者或受管理的設定中指定，或透過 --permission-mode 為各工作階段設定。因此，複製的儲存庫無法夾帶會讓工作階段一開始就略過權限的設定檔。（上例使用的是 acceptEdits，任何範圍皆可設定；本指南先前也從未記錄既有的 auto 限制——現在兩者均已載明。）²¹¹²⁴⁰

權限規則語法

細緻的規則可控制特定操作。規則會依序評估：第一個符合的規則生效。

Bash 命令模式：

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

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

重要限制：Bash 模式只比對前綴，並非正規表示式。Bash(curl http:*) 這類模式不會符合 curl -X GET http://...，因為選項出現在 URL 之前。若要可靠地封鎖，請直接拒絕整個命令：Bash(curl:*)。

請將 * 放在子命令之後。 Claude Code 會依照原樣比對第一個 * 之前的所有內容，因此正是這些字詞限制了規則：Bash(git log *) 僅允許 git log 命令；而在 Bash(git * main) 中，* 會代替子命令及其前面的所有選項。這也包括 -c，它可讓 git 執行您指定的程式，因此 Bash(git * main) 也會核准 git -c core.fsmonitor=<script> diff main。自 v2.1.246 起，若允許規則將萬用字元放在子命令之前，Claude Code 會在啟動時發出警告；無論該規則位於設定檔、受管理的設定，還是 --allowedTools/--settings 值中皆然。修正方式是改用您確切想要的值，例如以 Bash(git checkout main) 取代 Bash(git * main)。²⁴⁶²⁴⁴

檔案拒絕規則可追查重新導向；引數擴充功能推出後不到一天便遭還原（v2.1.257-260）。 Bash 命令中的 Read(...) 與 Edit(...) 拒絕規則會涵蓋輸入重新導向（< file），以及 tac、egrep 等讀取命令（v2.1.257）——這正是 v2.1.232 的輸入重新導向檢查於 v2.1.233 還原時所承諾的較窄版本；此部分仍然有效。v2.1.259 將相同的涵蓋範圍擴展至隱藏在選項值與運算元中的檔案路徑（--ignore-revs-file=.env、-f.env、@file 引數、git diff 與 git grep 運算元、cd DIR && cat FILE 複合命令；若 grep -r/cp -r 的目錄含有遭拒檔案，則會先詢問），但 v2.1.260 在隔天便還原了這項擴充：在所有模式下，Read(./**/build/**) 規則都會拒絕 npm run build，而 cd ... && grep 即使在 auto 模式中也會顯示提示。這是引數層級涵蓋範圍的第3次反覆調整——v2.1.232 推出、v2.1.233 還原、v2.1.257 納入目前仍有效的重新導向與讀取命令子集、v2.1.259 擴展至引數、v2.1.260 再次還原該擴充。因此，截至 v2.1.260，拒絕規則會攔截重新導向與讀取命令，但不會攔截隱藏在任意命令引數中的路徑——這項由 v2.1.260 確立的狀態至今不變；後續變更是針對特定繞過方式的個別修正，而非第4次反覆調整（見下一段）。²¹¹²¹²

還原後的個別修正，以及第2次小範圍還原（v2.1.268-273）。 引數相關的還原仍然有效；這些版本修補了特定的繞過方式——其中一項修正本身後來也遭撤回。v2.1.268：對以符號連結連結的系統目錄（macOS 上的 /etc、/tmp、/var；Linux 上的 /bin）設定拒絕與詢問規則後，即使以其實際位置表示路徑，規則現在也會生效；Bash 命令也不再忽略以符號連結形式撰寫的拒絕規則——這兩項修正均仍有效。同一版本也讓權限檢查器無法分析的 env -C、eval 或類似命令，在與 Read 或 Edit 拒絕規則位於同一行時，不再能規避該規則——但 v2.1.273 恰好還原了這項檢查：「time -p make build 之類的命令會再次顯示提示，而非遭到拒絕。」v2.1.269：Edit() 拒絕規則與寫入路徑檢查現在會涵蓋 Bash tee 命令寫入的檔案；Bash(tee:*) 允許規則不再涵蓋工作目錄之外的目的地；以 ! 開頭的拒絕或詢問規則只會在寫入該規則的設定來源內生效（單獨的 ! 否定會被忽略）。v2.1.271 修正了檢查器本身：即使 fmt、column 與類似命令所讀取的檔案位於檢查器無法辨識的選項之後，仍會受到檢查；當萬用字元位於模式或選項值中時，它所展開的檔案會受到檢查（例如 grep -v dir/* file）；Shell 變數宣告旗標不再能歪曲實際執行的命令；包含兩次目錄切換、子 Shell，或 cd+git 鏈結的命令，在 bypass 與 auto 模式下不再能略過 permissions.blockReadsOutsideWorkingDirectories 的提示。v2.1.273 除了進行還原，還納入3項個別修正：無法分析的 Bash 命令不再能略過 permissions.blockReadsOutsideWorkingDirectories 的提示；藏在子 Shell 中的危險 rm 不再能於 bypass 模式略過確認；由儲存庫設定選取的記憶體目錄，也不再依據該設定載入、回憶或建立索引。簡而言之，檢查器無法分析 Bash 命令列時的最終規則是：拒絕規則會顯示提示，而非直接拒絕；blockReadsOutsideWorkingDirectories 會顯示提示，而非略過。²¹⁶²¹⁷

寫入操作依實際落點判定，而非依路徑寫法判定（v2.1.280）。 上述 v2.1.268 修正涵蓋透過以符號連結連結的系統目錄進行的讀取。本次則補上寫入方面的缺口，而且影響更為重大：透過符號連結路徑進行寫入時，系統原本會依據其樹狀結構內的路徑寫法判定，因此看似位於本機的路徑，實際上可能寫入連結指向的任何位置。原文如下：「修正透過符號連結路徑進行寫入時，依其樹狀結構內路徑寫法判定的問題：提示現在會指出實際寫入位置，而 acceptEdits、允許規則與 auto 模式也不再核准落在外部的寫入操作。」以下3項後果值得牢記，因為它們原本都是不易察覺的靜默失效：

• acceptEdits 的曝險範圍最廣。 acceptEdits 的基本前提是「此專案內的編輯不成問題」。樹狀結構中的符號連結意味著，看似已獲核准的編輯可能在沒有提示的情況下寫入外部位置，因為規則比對的是路徑寫法，而非實際目的地。
• Edit(src/**) 類型的允許規則不再穿透連結。 規則現在必須符合位元組的實際寫入位置，因此 src/vendor -> /etc 這類連結無法再替路徑魚目混珠。
• 提示文字已變更，而這正是您應該仔細閱讀的部分。 寫入操作顯示提示時，現在會指出實際落點路徑。如果提示顯示的目的地與 Claude 輸入的路徑不符，這是符號連結如實揭露真相，而非顯示錯誤。

目前讀取與寫入遵循一致的通則：權限檢查器會先解析路徑，再做出判定。 如果您一直仰賴以符號連結形式撰寫的拒絕規則，或允許規則的範圍曾被連結悄然擴大，請依據實際目的地重新檢視兩者。²²⁰

Shell 寫入也隨之調整（v2.1.287）。 透過已提交至儲存庫的符號連結執行 Shell 寫入時，若實際落在敏感檔案或工作樹之外，現在會指出寫入位置並等待人員確認；這也包括目標含有 ~ 的命令列。涵蓋整個工具的 Bash 允許規則與允許操作的 hooks，若要透過 Shell 寫入 Claude Code 的檔案工具會直接拒絕的檔案，例如 Anthropic 設定檔儲存區與主機認證檔案，現在會顯示提示，而非直接執行。同一版本也修正了危險的 rm 命令在同時將輸出重新導向至 ~ 或萬用字元路徑時，可能失去一律詢問保護措施的問題，例如針對 / 或家目錄執行的命令。²³²