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

摘要：Claude Code 是一套代理式 CLI，能透過由權限、hooks、MCP 整合與 subagents 組成的分層系統，讀取程式碼庫、執行命令及修改檔案。掌握5大核心系統（設定、權限、hooks、MCP 與 subagents），即可大幅提升生產力。請依各項任務選擇合適的模型層級——複雜推理使用 Opus、一般工作使用 Sonnet、快速探索使用 Haiku；若品質是唯一考量，也可統一採用 Opus。凡是必須每次執行的項目，請使用 hooks，而非提示詞。自2026年8月14日起，Pro、Max 與 Team 的新工作階段預設採用 Auto mode 權限模式（於8月7日公告，並在切換當日實際驗證；自主操作會經分類器審查——除非接受一次性的切換提示，否則自行設定的 defaultMode 仍會保留；Shift+Tab 可切換任何工作階段，disableAutoMode 則可在整個組織停用此模式）。²⁰³ 預設模型取決於您的方案：Max、Team Premium、Enterprise（自 v2.1.251 起採席次制）及 Anthropic API 預設使用 Claude Opus 5，而 Pro 與 Team Standard 預設使用 Sonnet 5——原生支援1M脈絡，標準定價為每 MTok $2/$10（原為上市優惠價，現已成為永久價格；原訂9月1日的漲價將不再實施）²²⁴²⁰⁷——v2.1.197 於2026年6月30日導入的全面預設 Sonnet 5 已成歷史，而 opus 別名會指向 Claude Opus 5（v2.1.219 以上版本）；v2.1.198（7月1日）讓 subagents 預設在背景執行、使 Chrome 中的 Claude 正式全面推出，並允許背景代理完成工作樹程式碼後提交、推送及開啟草稿 PR，同時針對背景工作階段觸發 Notification hook（agent_needs_input／agent_completed）；v2.1.199（7月2日）可載入最多5個堆疊的 slash-skill 呼叫，並會為訂閱者自動重試暫時性的429錯誤；v2.1.200（7月3日）在 CLI、--help、VS Code 與 JetBrains 中，將 default 權限模式重新命名為「Manual」（設定值維持不變，並接受 manual 作為別名），且預設不再讓 AskUserQuestion 對話框自動繼續；v2.1.202（7月6日）新增「Dynamic workflow size」/config 控制項，並將 /review <pr>（快速單次檢查）與 /code-review <level> <pr#> 分開——但 v2.1.223 又撤銷了這項拆分：/review 再次成為 /code-review 的別名，且不帶參數的 /code-review 會沿用您上次的投入程度；v2.1.203–205（7月7日至9日）強化 Auto mode——禁止竄改逐字稿檔案、對無法解析的變數執行 rm -rf 前會先詢問，背景任務通知也會明確說明未曾取得人工輸入（因此無法採信逐字稿內偽造的核准）——並將 /doctor 升級為完整的診斷與修復檢查（別名為 /checkup）。^181182183 v2.1.217（7月21日）改變了巢狀 subagents 的方針——subagents 預設不再產生自己的 subagents（3天後，v2.1.219 又再次反轉此預設值，改為最多3層；詳見下文）；預設最多可同時執行20個 subagents（CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS），而 --max-budget-usd 現在確實會在達到上限後停止背景 subagents。¹⁹⁴ v2.1.218（7月22日）將 /code-review 移至背景 subagent——審查工作不再占用對話內容——並讓使用 context: fork 的 skills 預設在背景執行（每項 skill 可透過 background: false 選擇停用）、讓 /deep-research 僅在明確呼叫時啟動、將危險的 rm、背景 & 與可疑 Windows 路徑檢查交由 Auto mode 分類器處理，而不再顯示權限對話框，並防止代理 frontmatter hooks 從未受信任的資料夾執行。¹⁹⁵ v2.1.219（7月24日）將 Claude Opus 5（claude-opus-5）設為預設 Opus 模型——具備1M脈絡、128K最大輸出、每 MTok $5/$25（與 Opus 4.8 相同），預設啟用思考、effort 預設為 high，知識截止日期為2026年5月——並修正先前版本造成的兩項狀況：Fast mode 現在適用於 Opus 5 與 Opus 4.8，價格為每 MTok $10/$50（基本價格的2倍，且 Opus 4.7 已完全從 Fast mode 移除）；巢狀 subagents 再次預設啟用，深度為3層（CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 可停用巢狀結構）。同一版本還新增 DirectoryAdded hook 事件、sandbox.network.strictAllowlist 設定、含動態工作流程的 workflowSizeGuideline 設定鍵（現預設採用中等規模準則，目標為少於15個代理），以及 stream-json 中的巢狀 subagent 轉送功能。v2.1.220（7月25日）僅包含錯誤修正與可靠性改善。v2.1.221–226（8月4日至7日）新增跨工作階段訊息功能（macOS／Linux 上可在您的工作階段之間使用 SendMessage／ListAgents）、雲端工作階段的自架 runner（Team／Enterprise）、具備 SHA-256 釘選的 archive plugin 來源、可辨識 JWT／SigV4 的沙箱憑證遮蔽、VSCode Focus 檢視，以及讓 /fork 副本擁有自己的工作樹——同時移除每個工作階段200個 subagents 的上限與 ultraplan。^{199200201202196197198} v2.1.227–229（8月10日至12日）以修正為主，並加入多項便利功能：plugin 市集新增 command 來源（由本機程式輸出 plugin 目錄，每個工作階段都會重新解析；mode: "link" 會直接使用該目錄）、claude remote-control --continue 可繼續最近一次 Remote Control 工作階段、ListAgents 會將中斷連線的 Remote Control 對等端標示為 offline，並將您的雲端工作階段標示為 cloud；/commit-push-pr 不再自動核准危險的 git 旗標（--force、--amend、--no-verify），而 Write 工具在較新模型上的規則也與 Edit 一致——覆寫尚未讀取的檔案，不再要求本次工作階段必須先讀取該檔案。^231229230 v2.1.232（8月13日）讓 subagent 分支成為預設行為（subagent_type: "fork" 會繼承完整對話與提示快取；互動式工作階段中產生的非隊友代理會在背景執行），可在提示詞中使用 @ 加名稱提及另一個即時工作階段（Claude 會透過 SendMessage 路由；若只輸入名稱且恰好符合唯一的即時工作階段，現在也能直接傳送，不需確認參照），確保每台機器上的互動式工作階段名稱不重複（採 name-word-word 變體），將跨工作階段的傳入控制項顯示為 /config 列，並實現 GitLab 功能對等——在沙箱中遮蔽9種 GitLab token 系列、提供 glab CLI 憑證保護，且純 gitlab.com 市集 URL（包括巢狀子群組）可像 GitHub URL 一樣複製。²²⁸ v2.1.233（8月14日）將 GitLab 功能對等延伸至 --worktree（支援 MR URL，並在 claude agents 中顯示為 !N），為 Bash 命令新增 Linux 記憶體限制（CLAUDE_CODE_TOOL_MEMORY_LIMIT）與 WebFetch 快取 TTL 調整選項，並在 Opus 4.8、Sonnet 5、Fable 5 及更新模型上預設停用待辦事項／任務追蹤工具（設定 CLAUDE_CODE_ENABLE_TODO_TOOLS=1 可恢復使用）——此版本也因 Auto mode 發生迴歸問題，回復了 v2.1.232 的部分 Windows Bash 權限變更。²²⁷ v2.1.234（8月17日）可讓 Claude Code 在 claude.ai 使用量限制重設後自動繼續工作階段（可在 /config 中關閉：「Continue automatically at usage limit」），允許在處理途中開啟 /permissions 與 /add-dir，新增 CLAUDE_CODE_PROJECT_DIR_NAME 及 /goal 背景任務進度確認（CLAUDE_CODE_GOAL_CHECKIN_MINUTES），針對已驗證 glab CLI 的儲存庫在頁尾顯示 GitLab MR 徽章（!N），並藉由按需載入參考文件，將內建 claude-api skill 的脈絡成本從約200k tokens 降至約25k tokens。²²⁶ v2.1.235–238（8月18日至20日）新增內建 「Concise」輸出樣式（結果優先，不含開場白或過程敘述——可在 /config 的 Output style 中選取）、ANTHROPIC_DEFAULT_MODEL 環境變數（設定新工作階段的起始模型；透過 /model 選擇的模型仍會覆寫並持續保留，與 ANTHROPIC_MODEL 不同）、選用的 spellcheck 設定（透過已安裝的 aspell、hunspell 或 ispell，在提示詞中為拼錯的字加上底線）、keybindingFlavor 設定（"readline" 會讓 Ctrl+W 像 Bash 一樣刪除至前一個空白處；此設定在 v2.1.261 中退場——readline 現為唯一行為）、plugin 市集及專案 .mcp.json 中的 headersHelper（由命令產生短效 HTTP 標頭；目錄項目 helper 僅在安裝／更新時執行，且會先顯示其命令；專案／plugin／代理範圍的 helper 則會在資料夾信任對話框之後執行，不會繼承憑證環境變數）、跨工作階段 SendMessage 的 notify_when_idle（其他本機工作階段下次進入閒置狀態時發出一次性通知），以及兩項權限行為變更：Auto mode 現在會擱置 Monitor 允許規則（Monitor 命令會像 Bash 一樣接受分類器審查），且 macOS 沙箱的萬用字元讀取拒絕規則（**/.env）在允許讀取的區域內具有優先權，無法透過重新命名遭拒檔案加以規避——此外，Bedrock、Vertex AI、Foundry 以及停用遙測時的 Auto mode 分類器，現在會使用 Claude API 預設值²¹⁹（自 v2.1.273 起，這些閘道「暫時」預設使用本機分類器；設定 CLAUDE_CODE_AUTO_MODE_SERVER=1 可改用平台的伺服器端分類器²¹³）。v2.1.239（8月21日）新增 /claude-api upgrade（將 Python 專案從 anthropic 0.x 遷移至1.x）、將資料駐留工作區僅限美國推論的 1.1倍額外費用納入成本估算（/cost、狀態列、--max-budget-usd），將跨工作階段訊息功能帶到 Windows，將與 claude.ai 同步的 plugins 顯示為 name@synced（可透過 claude plugin enable/disable 管理，且絕不會覆寫同名的本機安裝），讓 ListAgents 顯示工作階段本身的名稱及即時隊友，將 "readline" 延伸至 Bash 單字按鍵，降低 /goal 進度確認頻率（30分鐘→1小時→2小時），並在 Bedrock／Vertex／Foundry 上提供全螢幕轉譯器；v2.1.240–241（8月22日至23日）皆為錯誤修正版。同一週的文件摘要另標示兩項狀態變更：/design——一項研究預覽 skill，透過 artifacts 發布由可編輯 UI 畫板組成的畫布（適用 Pro／Max／Team／Enterprise，需 v2.1.233 以上版本）——以及 Remote Control 結束研究預覽階段；執行 claude remote-control 的機器會在 Claude 應用程式中顯示為裝置卡片。²⁰⁵ 自 v2.1.174–176（2026年6月12日）起，availableModels 允許清單現在可透過新的 enforceAvailableModels 受管理設定限制 Default 模型（使用者／專案設定無法擴充受管理清單）、工作階段標題會以您的對話語言產生（可透過 language 設定固定語言），並新增 footerLinksRegexes 與 wheelScrollAccelerationEnabled 設定、VSCode /usage 歸屬對話框，以及一項修正，使 hook 的 if 條件能比對 Read／Edit／Write 路徑模式，為此次版本更新畫下句點。¹⁷² 自 v2.1.173（2026年6月11日）起，帶有 [1m] 後綴的 Fable 5 模型名稱會自動正規化並移除該後綴——Fable 5 預設已包含1M脈絡，因此不需此後綴（它只曾對 Opus／Sonnet 有意義）。自 v2.1.172（2026年6月10日）起，sub-agents 可遞迴產生自己的 sub-agents，最深可達5層——此預設行為維持至 v2.1.216，並在 v2.1.217 中停用（詳見上文）——Bedrock 會在未設定 AWS_REGION 時從 ~/.aws 讀取區域（/status 會顯示來源）、/plugin 新增市集搜尋列，而 claude_code.lines_of_code.count OTEL 指標則新增 model 屬性。自 v2.1.170（2026年6月9日）起，Claude Fable 5——定位高於 Opus 的新模型層級——可在執行 claude update 後，透過 /model fable 於 Claude Code 中選取（支援完整的 low 至 max 投入程度範圍，但無法停用思考）；Opus 4.8 仍是代理式工作的預設模型。自 v2.1.169（2026年6月8日）起，--safe-mode（以及 CLAUDE_CODE_SAFE_MODE）會啟動停用所有自訂項目的乾淨工作階段，便於疑難排解；/cd 可將工作階段移至新的工作目錄，而不破壞提示快取；disableBundledSkills 則會對模型隱藏內建 skills 與 slash commands。自 v2.1.166（2026年6月6日）起，fallbackModel 設定可在主要模型超載時串接最多3個備援模型、萬用字元 "*" 可用於 MCP 拒絕規則，而 MAX_THINKING_TOKENS=0／--thinking disabled 可在預設啟用思考的模型上完全關閉思考。自 v2.1.154（2026年5月28日）起，Opus 4.8 成為新預設模型，預設採用高投入程度，並新增 /effort xhigh 層級；dynamic workflows 可透過 /workflows 在背景協調數十至數百個代理；Opus 4.8 的 Fast mode 以標準價格的2倍換取2.5倍速度；精簡系統提示詞現已成為除 Haiku／Sonnet／Opus 4.7 及更舊模型外的預設選項；/simplify 恢復為僅執行清理檢查（與 /code-review --fix 分開）；claude agents 接受 ! <command> 以產生背景 shell 工作階段；plugins 可宣告 defaultEnabled: false；串流工具執行一律啟用；stdio MCP 伺服器則會在環境中收到 CLAUDE_CODE_SESSION_ID 與 CLAUDECODE=1。v2.1.153 在 plugin 市集中新增 skipLfs、讓 /model 將選擇儲存為預設值（按 s 可僅套用於目前工作階段），並在狀態列環境中加入 COLUMNS／LINES。v2.1.152 導入 /code-review --fix（將發現的問題修正套用至工作樹）、skill frontmatter 中的 disallowed-tools、/reload-skills、新的 MessageDisplay hook 事件、SessionStart hook 的 reloadSkills／sessionTitle 輸出、pluginSuggestionMarketplaces 受管理設定、工作階段途中切換 --fallback-model，並移除 Auto mode 的選擇加入機制。^{162 163 164 165 166 167 168 169 170 240 171}

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

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

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

重點摘要

• 5大系統決定您的運用成效：設定階層、權限、hooks、MCP 與 subagents，控制從行為到自動化的一切。
• 將工作推向委派層：subagents 會在獨立、乾淨的脈絡視窗中進行探索，且僅回傳摘要，避免脈絡過度膨脹。
• Hooks 能保證執行，提示詞則不能：對於每次都必須執行的 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及可用的網際網路連線。⁹² Shell相容性以Bash、Zsh或Fish最佳。

在Windows上，WSL 1和WSL 2皆可使用。若您偏好原生Windows環境，也可使用Git Bash。Alpine Linux及其他採用musl的系統需要安裝額外套件：

apk add libgcc libstdc++ ripgrep
export USE_BUILTIN_RIPGREP=0

平台支援矩陣

安裝、更新與解除安裝一覽

快速查閱所有方式、命令及版本檢查，一目了然。以下小節將說明各種方式的細節與疑難排解。

自v2.1.113起，標準CLI會透過各平台的選用相依套件產生原生Claude Code二進位檔，不再使用隨附的JavaScript。若需要經過測試的發行方式，請使用原生安裝程式。npm方式仍可使用，但會顯示最早於v2.1.15加入的棄用通知。

安裝方式

原生安裝（建議）

原生二進位檔不依賴Node.js，能提供最簡潔流暢的使用體驗：

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

# Homebrew alternative
brew install --cask claude-code

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

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

若要安裝特定版本：

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

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

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

NPM安裝（已棄用）

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

若舊版環境仍需使用npm：

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

使用npm安裝時，切勿使用sudo。這會造成權限問題，讓後續處理更加棘手。

從現有安裝移轉

若您目前使用舊版npm安裝，請移轉至原生二進位檔：

claude install

驗證選項

Claude Code支援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閘道：

# 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

閘道提示標頭（v2.1.273，選用）：設定CLAUDE_CODE_GATEWAY_HINT_HEADERS=1後，Claude Code會新增5個可供LLM閘道路由與觀察的請求標頭：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。²¹³

驗證安裝

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。²¹³

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

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 輸出不再遺漏其後續訊息與最終報告。²¹³

結束代碼：

控制 -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+)
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，如今會延續至下一輪。[^251]

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

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"

使用 /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 設定指向自訂的程式碼審查 URL（v2.1.119+）。若團隊會從 PR 連結至獨立的審查工具，此功能相當實用。¹⁵²

/resume 接受 PR URL（v2.1.122+）。在 /resume 搜尋框中貼上 PR URL，即可找到最初建立該 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 的官方文件新增了無障礙功能頁面，說明此模式及其互動方式。¹⁸⁶

設定系統深入解析

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

設定階層

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

自v2.1.181起，/config key=value 可直接從提示設定任何項目，例如 /config thinking=false，無須開啟互動式 /config UI；互動模式、-p 與遠端控制工作階段皆可使用。/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"
  },
  "includeCoAuthoredBy": true,
  "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": {
    "bedrock": "us.anthropic.claude-opus-5",
    "vertex": "claude-opus-5",
    "foundry": "claude-opus-4-8"
  },
  "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個代理程式」）；當設定檔提供此值時，/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鍵，讓組織可將自訂提示與內建提示一併輪替顯示（上方範例展示了擴充後的結構）。設定文件尚未記載這些新鍵——目前唯一來源是CHANGELOG。²¹⁸

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

• desktopSessionCleanupPeriodDays（v2.1.248）：限制由桌面版寫入的工作階段可免於逐字稿清理的時間。與此設定一併推出的修正更為重要：Claude Desktop與Cowork工作階段過去會在cleanupPeriodDays後消失（預設為30天）；如今只要仍存在於應用程式中，清理機制就會予以保留，除非組織原則另行管理保留期限。²⁰⁶
• 專案env限制（v2.1.251）：專案層級的.claude/settings.json中，env區塊已無法設定CLAUDE_CONFIG_DIR、CLAUDE_CODE_TMPDIR或TMPDIR/TMP/TEMP——請改在shell、使用者或受管理設定中設定，以免複製下來的儲存庫重新導向Claude Code寫入設定與暫存檔案的位置。²⁰⁶

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

• timeFormat / timeZone（v2.1.257）：控制Claude Code顯示時間的方式，包括每輪結束時的完成時間與逐字稿時間戳記。timeFormat接受12小時制、24小時制、24小時制UTC，或明確的strftime模式；timeZone則指定時區。設定文件尚未記載這些設定——目前來源是CHANGELOG。²¹¹
• 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視需要讀取，而非直接截斷。[^250] 自v2.1.265起，儲存端也設有上限：寫入磁碟的工具結果以1 GB為限，且對話中的預覽會在已儲存檔案遭截斷時加以說明。[^251]

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

• maxEffortLevel（v2.1.267）：限制使用者可選擇的努力程度——可在頂層設定，或於modelSettings中依模型設定——並適用於所有供應商，包括Bedrock、Vertex與Foundry。使用者仍可選擇低於上限的程度；這是管理端與/effort相對應的設定。²¹²
• bashEditDiffEnabled（v2.1.269）：當Bash工具處理檔案編輯時，工具結果會包含該指令所變更檔案的差異，讓對話呈現sed類型的編輯實際做了哪些變更。²¹²

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

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

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           # Model new sessions START on; a /model pick overrides + persists (v2.1.236)
ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-5      # What the `opus` alias resolves to (Opus 5 since v2.1.219)
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 five x-claude-code-* hint headers (request-class, agent-type, prev-tool-durations, compaction, context-compacted) for LLM gateways (opt-in; v2.1.273+)[^253]
CLAUDE_CODE_AUTO_MODE_SERVER=1                  # Use the platform's server-side auto-mode classifier on Bedrock/Vertex/Foundry; since v2.1.273 the local classifier is the default there "for now"[^253]

行為控制：

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_RESTRICTED=1                        # Restricted mode: no command/code tools or WebFetch unless named in --tools; only managed settings load (v2.1.248+)[^238]
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+)[^206]
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_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_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

網路與代理伺服器：

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

UI 與終端機：

CLAUDE_CODE_DISABLE_TERMINAL_TITLE=1            # Don't update terminal title
CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1             # Skip IDE extension install
CLAUDE_CODE_SHELL=/bin/zsh                      # Override shell detection
USE_BUILTIN_RIPGREP=1                           # Use included ripgrep (default)
CLAUDE_CONFIG_DIR=~/.myconfig                   # Custom config directory; not settable from project-settings env (v2.1.251)[^238]
IS_DEMO=1                                       # Hide sensitive UI elements[^37]
CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1          # Disable background tasks and Ctrl+B[^46]
CLAUDE_CODE_TMPDIR=/path/to/tmp                 # Override temp directory; not settable from project-settings env, nor are TMPDIR/TMP/TEMP (v2.1.251)[^50][^238]
CLAUDE_CODE_DISABLE_1M_CONTEXT=1               # Hold ALL native-1M models to 200K via auto-compaction (v2.1.223 widened scope)[^103][^217]
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]
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.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 閘道傳送的遙測資料，使其與終端機工作階段一致。[^251]

API／模型控制：²⁴¹

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

Plugins／MCP：²⁴¹

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

Shell／IDE：²⁴¹

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

企業／驗證：²⁴¹

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

Skill變數（v2.1.69+）：

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

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

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

偵錯：

ANTHROPIC_LOG=debug                             # Enable API request logging

我該選擇哪個模型？

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

可用模型

將工具框架從 Opus 4.8 移轉至 Opus 5 時，有兩項重大變更：¹⁹⁷

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

在 Claude Code 中，Opus 5 的 effort 預設為 high（與 Claude API 相同），並提供完整層級：low、medium、high、xhigh、max。Anthropic 自己的移轉指南建議：若能力比 token 支出更重要，請測試 max 強度。快速模式涵蓋 Opus 5，費率為每 MTok $10/$50（請參閱快速模式）。¹⁹⁷¹⁹⁸

Claude Fable 5.1（2026年9月1日）：Fable 層級的新頂尖模型；自 v2.1.257 起，fable 別名會解析至此模型（除非 ANTHROPIC_DEFAULT_FABLE_MODEL 固定使用其他模型）；best 現在代表「您可使用的最新 Fable 模型」。最低版本需求有一處需要釐清：模型設定文件指出別名於 v2.1.255 切換，模型頁面則表示 Fable 5.1「需要 Claude Code v2.1.255 或更新版本」，但 2.1.253 至 2.1.256 從未發布至 npm——因此，v2.1.257（9月1日）才是首個可安裝且包含此模型的版本。模型 ID：claude-fable-5-1（Bedrock：anthropic.claude-fable-5-1）。其層級與每 token 價格和 Fable 5 相同——輸入 $10/MTok、輸出 $50/MTok、1M 上下文、最大輸出 128K、永遠開啟的自適應思考，且 effort 預設為 high——但有一項定價變更會影響長時間的代理式工作階段：快取讀取成本為 $0.25/MTok，相當於輸入價格的 0.025 倍（2.5%），而非標準的 10%；僅 Fable 5.1 與 Mythos 5.1 採用此費率，快取寫入費率則維持標準（5 分鐘 $12.50、1 小時 $20）。可靠知識截止日期：2026年6月（訓練資料亦截止於2026年6月）——是所有現行 Claude 模型中最新的日期。最早將於2027年9月1日退役。相較於 Fable 5，有三項重大變更：強制使用工具會傳回錯誤、較舊模型無法讀取其思考區塊，以及編輯先前輪次會使思考區塊失效。另有五項新增功能：依訊息設定推理強度（beta）、限單輪生效的系統訊息（beta）、在工具呼叫之間提供進度更新（display: "updates"，beta）、更便宜的快取讀取，以及內容來源資訊。Claude Mythos 5.1 是規格完全相同的同一模型，僅能透過 Project Glasswing 邀請使用。隨著此版本推出，Fable 5 與 Opus 4.8/4.7/4.6/4.5、Sonnet 4.6/4.5 一同移至文件中的舊版模型表格。版本資訊另指出一項閘道注意事項：目前在 Claude 應用程式閘道工作階段中，fable 與 best 仍會解析至 Fable 5——尚未設定支援 5.1 的閘道會拒絕該模型——因此請在 /model 中明確選擇 Fable 5.1；請注意，在 v2.1.260 之前，/model 選擇器不會列出 Fable 5.1，因此若要明確選擇，必須輸入完整的 /model claude-fable-5-1（請參閱下方的發布期修正）。方案預設值維持不變：進階方案使用 Opus 5，Pro 與 Team Standard 使用 Sonnet 5。^211214215

Fable 5.1 發布期修正（v2.1.260，9月3日）：發布後的第一個版本修正了四項不完善之處。對於可使用 Fable 5.1 的組織，/model 選擇器現在會顯示該模型——修正前，只有完整輸入 /model claude-fable-5-1 才會接受此模型。Fable 5.1 的提示詞快取現在也涵蓋附加於工具結果之後的上下文；先前每次工具呼叫輪次都會將這些內容當成未快取的輸入重新傳送，恰好在最需要 0.025 倍快取讀取費率的長時間代理式工作階段中，悄然削弱其成本效益。在工作階段中途變更 /effort，也不再使提示詞快取失效。此外，使用 model: fable 的 agents 現在會遵循 ANTHROPIC_DEFAULT_FABLE_MODEL 固定值上的 [1m] 標籤，不會再默默以 200K 上下文視窗執行。[^248]

Claude Fable 5（2026年6月9日；自2026年9月1日起列為舊版）：這是位居 Opus 之上的新模型層級——Anthropic 最強大、最智慧的模型，在幾乎所有受測基準上皆達到當時最先進的水準，並能在數百萬 token 的上下文中保持前後一致。Fable 5 是經過安全處理、可供一般使用的「Mythos 級」前沿模型：它內建安全分類器，在面對網路安全、生物化學及模型蒸餾查詢時，會改用 Opus 4.8（Claude Mythos 5 是同一模型，但針對獲授權研究人員移除了這些防護措施）。自 v2.1.170（2026年6月9日）起，便可在 Claude Code 中選用——執行 claude update，再執行 /model fable（這個短別名自 v2.1.257 起會解析至 Fable 5.1——目前若要選擇 Fable 5，請使用 /model claude-fable-5）——並於2026年6月22日前逐步開放至各訂閱方案（現已完成）。模型 ID：claude-fable-5。Fable 5 預設即包含 1M 上下文視窗，因此不需要 [1m] 後綴；自 v2.1.173（2026年6月11日）起，claude-fable-5[1m] 模型名稱會自動正規化並移除後綴（該後綴只對 Opus/Sonnet 有意義，因為它們需透過 [1m] 才能啟用 1M）；最大輸出為 128K。定價為輸入 $10/MTok、輸出 $50/MTok——約為 Opus 4.8 的 2 倍——因此應保留給真正困難的推理工作，而非例行編輯。其請求介面與 Opus 4.8 相同（僅支援自適應思考；已移除 temperature/top_p/top_k 與 budget_tokens），但有一項新變化：明確設定 thinking: {type: "disabled"} 會傳回 400，因此若要在不進行思考的情況下執行，請完全省略 thinking 參數。²³⁴ 在Claude Code中特別值得注意的是：Fable 5 與 Opus 5 一樣支援完整的 effort 等級（low/medium/high/xhigh/max，預設為high）。Fable 5 的 thinking 無法關閉——工作階段中的 thinking 切換開關、alwaysThinkingEnabled設定及MAX_THINKING_TOKENS=0全都不會生效；它一律採用自適應推理。完整的fable系列設定介面與 Opus 選項相互對應：ANTHROPIC_DEFAULT_FABLE_MODEL可固定fable別名解析至哪個模型（適用於 Bedrock/Vertex/Foundry），DISABLE_PROMPT_CACHING_FABLE可讓 Fable 不使用提示快取，而企業閘道則會套用依內容判定的自動備援機制。/model opus現在會選取 Opus 5（預設採用 high effort，最困難的任務可使用/effort xhigh），開箱即用的預設模型則取決於您的方案——進階方案使用 Opus 5，Pro/Team Standard 使用 Sonnet 5；若需要最高效能，請透過/model fable明確選擇 Fable 層級——自 v2.1.257 起，這代表 Fable 5.1。^234197207215

Opus 4.7（2026年4月16日）：上一代旗艦模型，目前仍完整開放使用。1M token context window 採用標準定價，不收取長 context 額外費用。最大輸出為 128K，僅支援 adaptive thinking（extended thinking 已移除），並新增xhigh effort 等級，建議作為程式開發與 agentic 工作負載的起點。¹⁴⁵可靠知識截止日期：2026年1月。訓練資料截止日期：2026年1月。模型 ID：claude-opus-4-7。定價與 Opus 4.6 相同，每 MTok 輸入／輸出分別為 $5/$25；5 分鐘快取寫入為 $6.25、1 小時快取寫入為 $10、快取讀取為每 MTok $0.50。¹⁴⁴相較於 Opus 4.6，Opus 4.7 在 SWE-Bench 解決的實際生產任務多出 3 倍，在 CursorBench 取得 70%（4.6 為 58%），並在Anthropic內部的 93 項程式開發基準測試中將解決率提高 13%。¹⁴⁴它採用新的 tokenizer——相同文字的 token 數量預計約為原本的 1 至 1.35 倍；請提高max_tokens的預留空間與 compaction 觸發門檻。¹⁴⁵Vision 支援最高 2,576 px／3.75 MP 的圖片，並採用 1:1 像素座標。¹⁴⁵

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

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

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 串流傳送給使用者，則必須設定）。

Task budgets（beta header：task-budgets-2026-03-13）可讓您透過output_config.task_budget向模型提供涵蓋完整 agentic 迴圈的 token 目標；最低為 20K token。¹⁴⁵

Opus 4.6（舊版）：仍可透過claude-opus-4-6使用，具備 1M context 與最大 128K 輸出。若要改善 agentic 程式開發表現，建議遷移至 Opus 4.7。Opus 4.6 最初於 2026年2月5日推出。⁷⁹¹⁴⁴自 v2.1.117（2026年4月22日）起，Pro 與 Max 訂閱者使用 Opus 4.6 和 Sonnet 4.6 時，預設採用high effort（先前為medium）；Opus 4.7 則維持xhigh。此項調整恢復了模型的智慧表現，扭轉了 4 月 23 日事後分析中記載的 3 月 4 日至 4 月 7 日 effort 降級。¹⁵²¹⁵³

Sonnet 5（2026年6月30日）：目前的 Sonnet 層級，定位為「速度與智慧的最佳組合」。Anthropic表示，其效能接近 Opus 4.8，但價格更低；在 agentic 推理、工具使用、程式開發及知識工作方面，相較 Sonnet 4.6 均有顯著提升——同時，整體不當行為的發生率更低，資安能力則遠弱於 Opus 模型（正是這項安全取捨，使其得以在不受出口管制限制的情況下推出）。模型 ID：claude-sonnet-5（無日期的固定快照）。1M token context window、最大 128K 輸出（在 Batches API搭配output-300k-2026-03-24 beta header 時最高可達 300K），且僅支援 adaptive thinking。可靠知識截止日期：2026年1月。定價：每 MTok 輸入／輸出分別為 $2/$10，目前已是標準牌價。Anthropic在發布時宣布 $2/$10 為截至 2026年8月31日的優惠定價，之後決定維持此價格：定價頁面指出，原訂 9 月 1 日調漲至 $3/$15 的計畫「將不會實施」，而 v2.1.243 也更新了/model選擇器與內建的claude-api skill，將 $2/$10 顯示為標準牌價，而非限時優惠。²²⁴這比 Opus 5 的 $5/$25 低 60%。在Claude Code中，Sonnet 5 的effort參數預設為high（若要變更，請明確設定）。可使用/model sonnet（或/model claude-sonnet-5）選取。¹⁸⁰v2.1.197（2026年6月30日）當時將 Sonnet 5 設為Claude Code新工作階段的預設模型；如今它仍是標準層級（Pro、Team Standard）的預設模型，而進階方案與Anthropic API則預設使用 Opus 5——請參閱上方的方案表格。¹⁸¹²⁰⁷

Sonnet 4.6（2026年2月17日，現已由 Sonnet 5 取代）：均衡型模型；取代 Sonnet 4.5，成為 claude.ai 與Claude Cowork 的預設模型。⁹³定價與 Sonnet 4.5 相同（每 MTok 為 $3/$15）。在減少 token 消耗的同時，提升 agentic 搜尋效能。支援 extended thinking、adaptive thinking，以及 1M token context window（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。使用 Opus 執行相同工作階段則需 $0.50 至 $2.25，成本高出 5 倍。請將 Opus 留給真正困難的問題。¹

各模型的適用時機

Haiku：適合用於執行探索、簡單檔案搜尋及快速問答的 subagents。它的成本約比 Opus 低 5 倍，回應速度也更快。對於不需要深入推理的背景任務，堪稱恰到好處。 Sonnet：當成本是重要考量時，Sonnet 是日常開發的主力，也是標準層級、Pro 與 Team Standard 的預設模型（原生 1M context，標準牌價為每 MTok $2/$10；原訂於9月1日調漲的價格已取消）。^181224207 足以處理大多數程式設計工作，包括實作功能、修正錯誤、撰寫測試及程式碼審查。歷史紀錄：長期以來，包括本指南在內，皆將 v2.1.197（2026年6月30日）描述為把 Sonnet 5 設為所有層級的預設模型；然而，模型設定文件按方案區分的說明顯示，premium/API 的預設模型自 v2.1.154 起解析為 Opus 4.8，並自 v2.1.219 起解析為 Opus 5，因此所謂「所有層級」實際上僅指標準層級。Sonnet 4.6 在2026年6月以前一直擔任 Sonnet 模型的角色。^93147207 若需要成本較低的 token、更短的延遲，或更符合成本效益的 subagent，請使用 Sonnet。

Opus：深度推理層級——自 v2.1.219 起，opus 別名會選用 Claude Opus 5（每 MTok $5/$25、1M context，effort 預設為 high）。¹⁹⁷ 以下段落說明的是2026年4月16日推出時的 Opus 4.7，特此保留作為歷史紀錄。¹⁴⁴¹⁴⁷ 建議將成本較高的推理能力留給能充分發揮價值的工作，例如架構決策、棘手的偵錯、理解複雜系統、安全性分析，以及長期自主執行的代理工作。Opus 4.7 在 SWE-Bench 上解決的實際生產工作數量是 Opus 4.6 的3倍，在 CursorBench 上獲得70%的成績（相較之下為58%），並在一項包含93項工作的內部程式設計基準測試中，將問題解決率提升13%。¹⁴⁴ 在 Opus 4.7 上，Claude Code 的 effort 預設為 xhigh，可透過 /effort 調整（v2.1.111+）。¹⁴⁶¹⁴⁷ Max 訂閱者可透過 Anthropic API 在 Opus 4.7 上使用 Auto Mode，無須指定 --enable-auto-mode；其他方案與供應商是否提供此功能，則視個別方案及管理員控制設定而定。¹⁴⁶ 以標準價格提供 1M context，沒有長 context 加價。值得留意的行為變更：Opus 4.7 會更嚴格地依照指示執行，根據工作複雜度調整回覆長度，預設執行較少的 subagent，且語氣更加直接，減少以肯定對方為主的措辭。若提示中包含用來強制回報階段性進度或進行雙重檢查的輔助指示，不妨嘗試移除。¹⁴⁵

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"
      }
    ]
  }
}

專供 subagent 使用：

export CLAUDE_CODE_SUBAGENT_MODEL=haiku

自 v2.1.251 起，CLAUDE_CODE_SUBAGENT_MODEL 會設定 subagent 的預設模型，而不再覆寫所有設定：代理定義中的 model: 與每次產生時明確指定的模型，優先順序皆高於此設定。²⁰⁶ 自 v2.1.257 起，CLAUDE_CODE_SUBAGENT_MODEL_FORCE 可選擇恢復舊有行為：它會將 CLAUDE_CODE_SUBAGENT_MODEL（若未設定，則使用主要對話的模型）套用至每個 subagent，忽略每次產生時的選擇及代理定義中的 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.178 起，壓縮也會遵循備援鏈——若主要模型在壓縮期間超載或無法使用，壓縮步驟會改用已設定的 fallbackModel/--fallback-model 鏈，而不會使該回合失敗。對於長時間自主執行的工作而言，這補上了一項缺口：原本可恢復的壓縮作業，不再會因暫時性的模型錯誤而導致工作階段中斷。¹⁷³

延伸 Context

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

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

或在工作階段中執行：

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

Opus 4.7、Opus 4.6 與 Sonnet 4.6 均以標準價格提供完整的 1M token context window，不收取長 context 加價。¹⁴⁸ 包含900K token 的請求與包含9K token 的請求，會採用相同的單位 token 費率計費。提示快取與批次處理折扣皆依標準費率套用於完整的 context window。

對於 Max、Team 與 Enterprise 訂閱，Opus 會自動包含 1M context，無須加上 [1m] 後綴（自2026年3月13日發布的 v2.1.75 起預設啟用）。¹¹⁷¹⁴⁷ Pro 可透過額外用量使用 1M context。API 與隨用隨付使用者能以標準的單位 token 費率完整使用 1M context。¹⁴⁷

若要停用模型選擇器中的 1M context 版本，請設定 CLAUDE_CODE_DISABLE_1M_CONTEXT=1。自 v2.1.223 起，此變數的作用範圍有所變更：它會透過自動壓縮，將每個具有原生 1M window 的模型限制在200K，而不再僅套用至固定的已知版本清單；若自動壓縮並未確實將工作階段限制在200K，啟動時便會顯示警告。如果您為某個模型系列設定此變數以確保成本可預測，那麼新推出的 1M 模型從發布當天起也會受到限制，不會在不知不覺間失效。同一版本也讓自動壓縮能將使用無法辨識模型 ID 的工作階段維持在推定的 context window 內，不再任其超出；若閘道註冊的自訂 ID 實際具有更大的 window，可設定 CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 恢復舊有行為。²⁰⁰

自 v2.1.247 起，Sonnet 5 的預設自動壓縮 window 是完整的 1M context：使用 1M window 的工作階段現在會在約967K token 時自動壓縮，而非約934K。²¹⁸ v2.1.260 將接近上限時的自動壓縮擴及其餘 1M 層級：Opus 與 Fable 工作階段現在也會在接近 1M token 上限前進行壓縮，而超大型 context 的復原壓縮也不再於10分鐘後逾時。[^248]

自 v2.1.271 起，--resume 會保留 [1m] window：恢復模型系列與已設定預設模型不同的工作階段時，不再移除 [1m] 後綴。²¹²

v2.1.273 修正了 context 計量器與自動壓縮將顧問工具回合計算為實際 context 大小約2倍的問題——自動壓縮原先會在實際 window 約一半的位置觸發。²¹³

查看目前模型

> /status

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

模型選擇器標籤（v2.1.51+）：/model 選擇器現在會為鎖定版本顯示人類可讀的標籤（例如「Sonnet 4.6」），而非原始模型 ID；如有較新版本，也會顯示升級提示。⁹⁸ v2.1.219 修正了合併後的 Opus 列，使其顯示為單純的「Opus」，而非 「Opus (1M context)」；同時將新版本醒目標示縮小至最新模型的名稱，讓標示能準確指出實際發布的項目，而非清單中的任意片段。¹⁹⁶

Fast Mode（v2.1.36+）

Fast mode 可讓相同模型大幅加快輸出速度，並不會切換至成本較低的模型。若要在工作階段中切換，請使用 /fast。⁸⁶

> /fast            # Toggle fast mode on/off

可用模型（截至v2.1.219）：fast mode適用於Claude Opus 5與Claude Opus 4.8。v2.1.219已將Opus 4.7移出fast mode，而Sonnet、Haiku或Fable從未支援此功能。此功能仍僅在Claude API（包括Claude Managed Agents）中以研究預覽形式提供，不適用於Amazon Bedrock、Google Cloud、Microsoft Foundry或AWS上的Claude Platform。存取權限受到管制：請聯絡您的客戶經理或加入候補名單。¹⁹⁶¹⁹⁸

Remote工作階段（v2.1.271）：fast mode現在也支援Claude Code Remote工作階段，包括雲端工作階段與自行託管的執行器。您可以沿用主機的fast mode設定，也可以直接在工作階段中輸入/fast；兩者都只有在組織允許fast mode時才會生效。同一版本也修正了/fast off：組織停用fast mode時，此指令現在會關閉fast mode，不再回覆「Fast mode unavailable」。²¹²

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

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

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

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

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

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

專家提示：fast mode無法與opusplan搭配使用（opusplan本身已混用Opus與Sonnet；fast mode只會影響Opus部分）。只有在延遲比成本更重要時才建議使用；自主或批次工作則應將其停用。/fast需要額外用量；Team／Enterprise管理員可能必須先啟用此功能（v2.1.37修正）。若要徹底停用，請設定CLAUDE_CODE_DISABLE_FAST_MODE=1。自v2.1.218起，透過/config model=<x>或Remote Control切換模型而改變fast mode狀態時，Claude Code會顯示通知；v2.1.219則修正了Remote Control用戶端在切換、重新連線或組織檢查失敗後仍保留過期fast mode狀態的問題。^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.257進一步調整了這兩種控制方式：/effort現在接受s作為僅限目前工作階段的選擇，與/model的慣例一致；--effort旗標現在也僅限目前工作階段——它只會在該工作階段中解除新模型的預設effort限制，而不會永久變更設定（CLI參考資料指出，它會「覆寫」預設值，且「僅適用於此工作階段，不會持續保留」）。²¹¹²¹⁶

Max上的Auto Mode（v2.1.111以上版本）

自2026年8月14日起，Auto Mode已成為Pro、Max與Team方案的預設權限模式（於8月7日公布）——公告中的研究數據、退出方式，以及仍須選擇啟用的方案與閘道，請參閱權限模式。²⁰³ Auto Mode最初是--dangerously-skip-permissions的更安全替代方案，最早透過Anthropic API向使用Opus 4.7的Max訂閱者提供。¹⁴⁶ 每項操作執行前，都會由另一個分類器模型審查意圖是否相符及操作是否安全；自v2.1.210起，此模型為Claude Sonnet 5。¹⁸⁷ 注意（v2.1.111以上版本）：--enable-auto-mode旗標已移除；請改用--permission-mode auto，以Auto Mode啟動工作階段。Pro在Auto Mode發展歷程中的大部分時間都無法使用此功能，而8月14日的預設啟用已終結這項限制。Bedrock／Vertex／Foundry（v2.1.158以上版本）：在這些閘道上，Opus 4.7與Opus 4.8可透過CLAUDE_CODE_ENABLE_AUTO_MODE=1選擇啟用Auto Mode。²³⁹ 自v2.1.207起，不再需要選擇啟用：Auto Mode無須設定CLAUDE_CODE_ENABLE_AUTO_MODE，即可在AWS Bedrock、Google Vertex AI及Microsoft Foundry上運作；若管理員想停用此功能，可使用受管理的disableAutoMode設定。同一版本也讓Bedrock、Vertex AI及AWS上的Claude Platform預設使用Claude Opus 4.8，並停止從儲存庫的.claude/settings.local.json讀取autoMode設定——請改在~/.claude/settings.json中設定Auto Mode規則。¹⁸⁵ 自v2.1.247起，Bash權限提示會顯示指向Auto Mode的提示，並提供按一下按鍵即可選取的「是，並切換至Auto Mode」選項。²¹⁸ 自v2.1.273起，Bedrock、Vertex AI與Foundry上的Auto Mode「目前」預設使用本機分類器——若要使用平台的伺服器端分類器，請設定CLAUDE_CODE_AUTO_MODE_SERVER=1。這是在不同面向上的狀態變更，與v2.1.236的分類器預設值說明並不相同：本機或伺服器端屬於執行機制，而先前版本從未揭露這項區別。²¹³ 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，讓代理程式改用 curl；下載的封存檔解壓縮至暫存目錄，其中包含資訊清單、7 筆以 Base85/zlib 編碼的資料記錄、一個原生二進位檔，以及一個 struct.py；Claude 拒絕執行不受信任的二進位檔，接著自行編寫 Python 解碼器，並從該目錄內執行；解碼器匯入 base64，base64 再匯入 struct，而 Python 會優先解析攻擊者的 struct.py。整個流程中沒有任何一條指示顯然帶有惡意；注入只需讓遭入侵的路徑看起來像是完成工作的最合理方式。Rehberger 也指出，在少數幾次執行中，Claude 察覺遭到入侵後嘗試終止惡意軟體行程，但 auto mode 拒絕了清理命令。²¹⁰他以 Anthropic 曾宣傳的一項數據為背景來說明整個發現：一項委託第三方進行的評估，針對 auto mode 下的 Opus 5 測試了 72 種情境，每種執行 10 次，回報的提示注入攻擊成功率為 0.00%。他的攻擊鏈不在該測試集中，因此 0.00% 的基準測試結果與實際可用的程式碼執行攻擊鏈可以同時為真；但在他看來，這兩種訊息彼此扞格。²¹⁰也請留意這項攻擊的分類：Simon Willison 在8月30日的更新中認同一位讀者的觀點，指出這並非典型的提示注入，因為模型從未讀取並遵循攻擊者的指示，而是一種「混淆環境攻擊」。²¹⁰

Anthropic 將該報告以 Informative 結案，認定此行為符合設計；而 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 則會以單一文件形式在編輯器中開啟。²²²²²⁰

「Don’t ask again」選擇性停用提示（v2.1.118+）。Auto Mode 的啟用提示現在提供「Don’t ask again」選項，經常使用此功能的人不必透過指令碼設定旗標，也能隱藏說明提示。¹⁵²

破壞性命令防護措施（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 拒絕原因，因此命令遭封鎖時，現在會說明封鎖原因。¹⁷⁹

另外3項強化規則（v2.1.205）。Auto mode 現在會封鎖竄改工作階段對話記錄檔案的行為，代理程式不得觸碰稽核軌跡本身；若要對無法根據內容解析的變數執行 rm -rf，系統會事先詢問，藉此避免 rm -rf $DIR 中 $DIR 不明所造成的意外；此外，背景工作通知現在會明確指出尚未有人類輸入，因此無法再把對話記錄中捏造的「使用者已核准」字樣，偷渡成可據以採取行動的核准。¹⁸³第3項是值得銘記在心的提示注入防禦措施：核准必須透過核准管道傳入，而控制框架現在已明確揭示這項前提。

命令替換無法再隱藏災難性操作（v2.1.208）。即使 rm -rf ~ 等災難性移除命令藏在 $(...)、反引號或處理程序替換（<(...)）之中，現在仍會觸發提示，而且即使處於 --dangerously-skip-permissions 或 auto mode，也照樣會提示。將破壞性命令包在替換語法中，已無法再瞞天過海、繞過安全網。¹⁸⁶

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

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

減少對話方塊，維持同等審查（v2.1.218）。過去有3項檢查會以權限對話方塊中斷 auto mode：危險的 rm、背景執行的 &，以及可疑的 Windows 路徑。如今這些檢查不再顯示對話方塊，而是交由 auto mode 分類器裁決，因此安全審查仍會進行，卻不會每次命中都要求您介入。同一版本也將此機制延伸至 plan mode with auto：靜態分析器無法證明為唯讀的 Bash 命令不再觸發提示，而是由分類器判斷，不再退回對話方塊。¹⁹⁵

圍堵逃逸規則（v2.1.257）。分類器的「永不自動核准」清單新增「Containment Escape」規則：除非環境將雲端中繼資料憑證擷取、規避網路輸出流量限制及跨租戶存取標記為預期行為，否則不再自動核准。請依照上述警語所建立的框架來理解：這只是持續強化分類器，新增另一類明列的拒絕規則，並未改變 auto mode 的本質。²¹¹ 首次讀取工作目錄以外的檔案時提示（v2.1.257）。 Auto 模式現在會在工作階段首次讀取工作目錄以外的檔案前詢問一次。搭配的 permissions.blockReadsOutsideWorkingDirectories 設定則會將提示改為拒絕，直接封鎖這類讀取作業。²¹¹ v2.1.273 將這兩種行為延伸至檢查器無法掌握的範圍：若 Bash 命令無法被完整分析，系統會顯示提示，而不再略過檢查；啟用封鎖設定時，由儲存庫設定所指定的記憶體目錄也不再載入提示詞、被回想、建立索引，或用於記憶擷取。²¹³

圖表轉譯器 URL 視同上傳（v2.1.261）。 若連結將內容封裝在公開圖表轉譯器的 URL 中（如 mermaid.live，資料本身編碼於 URL 內），除非您明確要求，否則不再自動核准。分類器會將這類連結視為上傳：封裝的資料會透過 URL 本身傳送；頁面開啟後，轉譯器網站自己的指令碼即可讀取。以 mermaid.live 類型的連結為例，承載內容位於 URL 片段中，瀏覽器會將其交給頁面的 JavaScript，而不會隨網路請求送出。這與前述注意事項屬於同一脈絡：只是強化分類器時又封堵了一條資料外洩管道，並非建立新的安全邊界。[^250]

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

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 條（針對新推出的 AI 系統，自 2026年8月2日起執行）。此系統包含兩個元件：生成文字中的隱形統計浮水印，以及依據 C2PA 開放標準，附加於 .svg、.png 和 .jpg 等生成檔案的簽署來源中繼資料。²²⁵²⁰⁴ 新聞標題常模糊處理的細節是：兩個元件都遵循相同的模型時程。 根據支援頁面，「2026年8月2日當日或之後推出的 Claude 模型，會在發布時支援機器可讀標記」；在該日期之前推出的模型，也就是目前的完整產品陣容（Fable 5、Opus 5、Sonnet 5、Haiku 4.5），則適用歐盟法律的過渡期，而 Anthropic「也正努力為這些模型加入標記支援」。²⁰⁴ 目前透過 Claude Code 生成的任何內容，無論文字或檔案，都不帶有標記；未來模型的輸出則會在所有介面加入標記，包括 Claude Platform（API）、claude.ai、Claude Code、Claude Cowork、Claude Tag，以及各種雲端閘道，因為標記是在模型層級實作。值得明確指出的一項推論是，某篇廣為流傳的討論串正好說反了：在目前模型中察覺到的任何風格或行為變化，都不可能源自浮水印，因為目前任何模型都尚未啟用此功能。

運作方式：採用 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。[^248]

代理流量不再破壞自身的快取前綴（v2.1.265）： 兩項修正堵住了委派工作中的提示詞快取漏洞。繼續執行由前景產生的 subagent 時，不再變更其工具清單與系統提示詞前綴；代理隊友和繼續執行的 subagents 在後續回合中，也不再將 SubagentStart hook 上下文與預先載入的 skills 移出提示詞前綴。這兩個錯誤都會破壞提示詞快取的重複使用：前綴一旦改變，其後所有內容都會以未快取輸入重新傳送。這種問題恰好發生在快取成本效益最重要的長時間代理工作階段中（與 v2.1.260 為 Fable 5.1 工具呼叫回合修復的失敗模式相同）。[^251]

v2.1.267 快取穩定性修正批次： 一個版本、約 10 項修正，針對的都是同一種失敗模式：某項機制在對話中途重寫提示詞前綴，導致其後所有內容都以未快取輸入重新傳送。繼續先前的工作階段時，不再重寫工具清單、重新轉譯工具說明，或在連接器重新連線前重寫較早的 MCP 工具公告；使用 /model 切換模型時，不再重新傳送每項工具定義（提交與 PR 的署名文字現在會以對話附註形式送達，並在模型變更時更新）；以 --system-prompt 或 --append-system-prompt 啟動的 subagents 與工作階段，只會記錄系統提示詞及工具定義一次；而工作階段中途加入的 MCP 與 plugin 工具，會以延後定義的形式送達未使用 ToolSearch 的工作階段，而非重寫工具清單。此批修正將 v2.1.260 與 v2.1.265 的成果延伸至繼續工作階段、切換模型及 MCP 重新連線等情境。²¹²

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

訂閱方案

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

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

自2026年9月14日起的每週限制（8月29日公布）： 自5月提升後實施的臨時每週限制增加 50% 措施，將於9月14日結束；取而代之的是 Pro、Max、Team 及按席次計費的 Enterprise 方案，相較提升前基準永久增加 25%。Anthropic 對此變動的計算如下：「與目前相比，這等同於 Claude Code 的每週限制減少 17%。」若您目前的每週上限為 150 單位，9月14日起將調整為 125。此次公告不涉及五小時限制；5月的加倍措施維持不變。若您會執行長時間無人值守的工作階段，現在就應針對較低的上限預作規劃：重設時自動繼續的切換選項（v2.1.234）與 /usage，是兩項關鍵控制機制。[^249]

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

對按 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 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 支援團隊，以書面方式確認您的特定設定。

成本因素

實際成本範例

節省成本要點： 探索型 subagents 使用 Haiku、實作時使用 Sonnet，相較於所有工作一律使用 Sonnet，通常可降低 40–50% 的成本。

團隊成本管理

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

隱藏工具費用

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

這些費用會在代理迴圈中不斷累積。使用 Bash 進行 100 次反覆偵錯，單是額外負擔就會增加約 24,500 個輸入 token。

節省成本策略

1. subagents 使用 Haiku：多數探索工作不需要 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 分析 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"

使用情境： - 開發人員生產力分析（工作階段、提交、PR） - 工具使用指標（Edit、Write 等操作的接受率／拒絕率） - 跨團隊成本追蹤與分攤 - AI 程式設計工具的 ROI 合理性佐證

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

決策框架

僅僅知道有哪些功能還不夠，還必須瞭解何時該使用各項功能。這些決策樹能將知識轉化為行動。

我該使用哪個模型？

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

經驗法則：預設模型取決於您的方案——高階方案與Anthropic API使用 Opus 5，Pro 和 Team Standard 則使用 Sonnet 5；/model opus可將 Sonnet 工作階段升級至 Opus 5。^181197207 subagents 可改用 Haiku。若覺得 Sonnet 的回答流於表面，請升級至 Opus。使用 agent teams（v2.1.32+）時，Opus 能協調多個 agent，並行處理不同的子任務。⁷⁹

Command、Skill、Subagent，還是 Agent Team？

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

Hook 還是 Prompt？

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

何時該使用延伸思考？

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

在工作階段中按下Alt+T即可切換。思考預算越高，成本也越高；請從最低值開始，只有在回應顯得倉促時才逐步提高。

Opus 4.6 自適應思考：Opus 4.6 會依據問題複雜度，自動調整思考深度。對大多數任務而言，無須明確控制思考預算——Opus 遇到難題時會加深思考，面對簡單問題時則維持快速回應。若您希望強制進行更深入的分析，手動切換思考模式主要適用於 Sonnet。

該選擇哪種執行介面？

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

Agent Teams、Subagents，還是並行工作階段？

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

該使用哪種 Hook 類型？

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

何時該使用 /fast？

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

/fast可切換目前工作階段的快速模式。它仍會使用相同的模型——截至 v2.1.219，快速模式僅支援 Opus 5 或 Opus 4.8——但會最佳化輸出速度。它不會切換至較便宜的模型；以每 MTok 10／50 美元計價，也不會比較便宜。¹⁹⁶¹⁹⁸

權限系統如何運作？

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

權限層級

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

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

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

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

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

權限模式

自v2.1.200起，default模式標示為「Manual」。此次更名涵蓋CLI、--help、VS Code與JetBrains；設定值並未改變，因此"defaultMode": "default"仍然有效，現在也接受--permission-mode manual與"defaultMode": "manual"作為別名。行為完全相同，仍會在每項工具首次使用時提示；只是標籤不再讓人誤以為這是「碰巧取得的預設模式」，而是清楚表明它是手動核准模式。同一版本中，AskUserQuestion對話方塊預設不再自動繼續；subagent提出問題後，現在會等待您的回答，不會在逾時後自行繼續。如需恢復閒置逾時，可透過/config選擇啟用。

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

即使使用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/寫入保護採用相同的威脅模型，只是擴大至更廣泛的「編輯即執行」檔案類別。²³⁸

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

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

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

斷路器：連續攔截3次或單一工作階段內累計攔截20次後，會暫停auto模式並恢復手動提示。¹²⁵

# Enable at startup
claude --permission-mode auto

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

auto模式不再需要選擇啟用（v2.1.152），在Bedrock/Vertex/Foundry上也無須環境旗標即可運作（v2.1.207），且自2026年8月14日起已成為Pro/Max/Team的預設模式。^240185203

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

claude --dangerously-skip-permissions

透過CLI設定模式：

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

在工作階段中切換：

Shift+Tab  # Cycles through modes

在settings.json中：

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

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起，如果允許規則將萬用字元放在子命令之前，無論該規則來自設定檔、受管設定，還是--allowedTools／--settings值，Claude Code都會在啟動時顯示警告。修正方式是改用您真正需要的精確值，例如以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；即使在auto模式下，cd ... && grep也會觸發提示。這是參數層級涵蓋範圍的第三次反覆調整：v2.1.232推出、v2.1.233撤回、v2.1.257加入目前仍保留的重新導向與讀取命令子集、v2.1.259擴充至參數，最後v2.1.260又撤回該擴充。因此截至v2.1.260，拒絕規則會攔截重新導向與讀取命令，但不會攔截藏在任意命令參數中的路徑；此狀態由v2.1.260確立並延續至今。後續變更只是針對特定繞過手法的個別修正，並非第四次全面調整（詳見下一段）。²¹¹[^248]

撤回後的個別修正，以及第二次小範圍撤回（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提示；藏有危險rm的子shell不再能在bypass模式下略過確認；由儲存庫設定指定的記憶體目錄，也不再依該設定載入、回想或建立索引。簡而言之，對於檢查器無法分析的Bash命令列，最終規則是：拒絕規則會提示而非直接拒絕，blockReadsOutsideWorkingDirectories也會提示而非略過。²¹²²¹³

檔案操作模式：

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

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

單一區段的dir/**允許規則現在只會比對<cwd>/dir（v2.1.214），請稽核現有規則。在v2.1.214之前，Edit(src/**)這類允許規則會自動核准寫入目錄樹中任何名為src的目錄，包括vendor/src/、packages/foo/src/等所有位置。現在它只會比對工作目錄正下方的src目錄。若您依賴舊有的任意深度行為，請將規則改寫為Edit(**/src/**)。deny與ask規則仍保留任意深度比對；此變更只會縮小自動核准範圍，絕不會縮小攔截範圍。升級後，原本默默停止比對的規則會呈現為新的權限提示，而不是錯誤。因此，請檢查所有採用單一區段形式的允許規則。Hook的if:條件在此版本中也採用相同的cwd範圍限定（請參閱比對器）。¹⁹⁰

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

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

包含括號的路徑與格式錯誤的模式會以安全方式失敗（v2.1.260）。此版本修正了3項檔案權限規則剖析問題，其中第一項屬於安全性修正。路徑包含括號的Edit／Write／Read規則，例如Next.js路由群組Edit(src/app/(admin)/**)，過去會因無效而遭捨棄，或被Bash沙箱忽略，導致管理員以為設為唯讀的資料夾仍可寫入；現在這些規則會正確套用。先前，若檔案拒絕規則包含無法編譯的模式（例如未關閉的[），會導致每次檔案編輯皆因Invalid regular expression而失敗；現在這類規則會保護其字面指定的路徑。此外，對於Edit(C:\dir\(name)\**)這類規則，由於其中的\(會被解讀為逸出的括號，而非路徑分隔符號，設定錯誤現在會建議明確無歧義的寫法。同一版本也不再默默忽略右括號後仍有文字的規則（Bash(ls) x從未能比對任何內容）；現在會將其回報為無效設定。[^248]

MCP工具模式：

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

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

自v2.1.166起，拒絕規則也接受工具名稱位置中的glob：在工具名稱欄位放置單獨的"*"，會拒絕所有工具，讓您可以先全面封鎖，再僅允許一小組工具。相較之下，允許規則會拒絕非MCP的glob，您無法以相同方式廣泛允許所有工具，從而維持嚴格的預設安全態勢。²³⁶

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

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

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

Agent(model:opus)會封鎖任何以Opus層級建立的subagent；遭拒絕的是建立動作本身，而不只是要求提示避免使用它。這項功能將權限控制從「使用哪個工具」延伸至「如何呼叫工具」，並以確定性規則取代提示層級的要求。它可搭配受管的enforceAvailableModels設定：允許清單定義工作階段可用的模型層級，而Tool(model:...)規則則限制subagent如何從中選用模型。¹⁷³

自v2.1.186起，這些Agent(...)規則也會套用於具名subagent的建立動作：透過工作流程、--agents或agent團隊啟動特定具名agent時，Agent(agent_type)拒絕規則與Agent(x,y)允許類型限制現在都會生效，而不再只適用於匿名的Task式建立動作。建立動作會在啟動時遭到攔截，封堵具名agent規避限制規則的漏洞。¹⁷⁵

WebFetch模式：

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

自v2.1.268起，一般WebFetch拒絕與詢問規則不再套用於Artifact工具的讀取及更新操作；若要封鎖或管控這些操作，請撰寫Artifact規則或WebFetch(domain:claude.ai)。²¹²

額外目錄

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

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

對於monorepo，或Claude需要參照相鄰目錄中的程式碼時，額外目錄至關重要。

沙箱模式

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

> /sandbox

或在設定中進行配置：

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

自v2.1.187起，sandbox.credentials設定會禁止沙箱中的命令讀取認證檔案與機密環境變數，形成縱深防禦，避免沙箱命令外洩機密。¹⁷⁶

自v2.1.221起，認證檔案除了允許／拒絕之外，又增加第三種模式：mode: "mask"（Linux與WSL）。沙箱中的命令讀取檔案時，取得的是哨兵副本，可以是整個檔案，也可以只替換由extract規則運算式擷取的區段；沙箱proxy則會在流出時代入真實值。命令仍可正常運作（可透過proxy進行驗證），但機密絕不會出現在其環境中。當遭提示注入的命令四處搜尋token時，這正是您需要的特性。在無法使用proxy代換機制的macOS上，mask會退回deny；因此，為Linux CI撰寫的設定會安全地降級，而不會在無聲無息間暴露檔案。¹⁹⁹

v2.1.224將遮罩功能擴展至靜態檔案內容以外。extract與onExtractNoMatch可處理結構化的環境值；搭配maskClaims的decode: "jwt"可遮罩JWT中的特定claim，而非整個token，讓命令仍能讀取token的路由中繼資料，同時讓敏感claim維持哨兵值；awsPairs／sigv4則會在proxy端重新簽署AWS SigV4要求，這是讓遮罩功能能搭配AWS CLI使用的關鍵，因為經遮罩的金鑰否則將無法通過簽章驗證。上述功能皆須使用network.tlsTerminate，且只會接受來自使用者、受管或--settings範圍的設定；儲存庫無法夾帶會暗中重新導向您認證的遮罩設定。²⁰¹

自v2.1.216起，sandbox.filesystem.disabled設定可略過檔案系統隔離，同時保留網路流出控制。當檔案系統隔離區造成建置工具故障，但您仍希望對外流量強制執行網域允許清單時，此設定相當實用。¹⁹²

自v2.1.219起，sandbox.network.strictAllowlist設定會直接拒絕不在允許清單中的主機，不顯示提示。在預設情況下，沙箱中的命令若要連線至allowedDomains以外的主機，會觸發權限提示；開啟strictAllowlist後，連線會直接遭到拒絕。對於無人值守的執行作業，例如CI、背景agent及隔夜迴圈，這正是合適的設定。在這些情境中，無人回應的提示只會造成停滯，而且「遇到非預期的流出連線就詢問我」本就不是恰當的原則。它補齊了網路控制的三大要素：allowedDomains指定允許的項目，deniedDomains（見下文）可在廣泛允許範圍中排除例外，而strictAllowlist則決定其餘項目是要詢問還是失敗。¹⁹⁶v2.1.229也進一步收緊網域清單語法：IPv6常值必須置於方括號中（[::1]:443），語意不明的寫法會以封閉失敗方式處理，且/doctor會將其標示出來。²³⁰v2.1.236又新增兩項強化措施：在macOS上，萬用字元讀取拒絕規則（例如**/.env）現在於允許讀取區域內具有優先權，會涵蓋相符目錄的內容，也無法透過重新命名遭拒檔案予以繞過；auto模式啟用時，Monitor允許規則會暫時擱置，Monitor命令會像Bash命令一樣接受分類器審查。auto模式分類器本身現在於Bedrock、Vertex AI與Foundry，以及停用遙測時，皆採用與Claude API相同的預設值，包括依嚴重程度評分的分類。²¹⁹v2.1.273變更了這些gateway上的預設機制：auto模式目前在這些平台上預設使用本機分類器，設定CLAUDE_CODE_AUTO_MODE_SERVER=1則可選擇使用平台的伺服器端分類器。²¹³

auto模式中的逐命令allowed_domains（v2.1.271）：啟用沙箱後，auto模式中的Bash、PowerShell及Monitor命令可攜帶各自的allowed_domains。命令所需的主機會連同命令本身一併接受審查，並只為該命令開放；其他主機則會遭到拒絕。流出權限不再是工作階段層級的授權：每個命令都會指定其目的地，審查範圍也精確涵蓋這組配對。²¹²

嚴格沙箱模式與!例外（sandbox.allowUnsandboxedCommands，v2.1.260）。這是本指南先前未曾提及的設定：在預設情況下，若命令無法於沙箱中執行，可透過dangerouslyDisableSandbox逃生機制在沙箱外重試，但仍須遵循一般權限流程。sandbox.allowUnsandboxedCommands: false（在/sandbox的Overrides分頁中顯示為Strict sandbox mode）會關閉此逃生機制：該參數將被忽略，每個命令都必須在沙箱中執行，或列入excludedCommands。自v2.1.260起，您親自在! bash模式提示中輸入的命令，即使在嚴格沙箱模式下，也會於沙箱外執行，「就像在自己的終端機中輸入一樣」。嚴格限制所管控的是Claude執行的內容，而非您親自輸入的內容。若您的威脅模型仰賴!命令繼承隔離區，現在已不再如此。[^248]

在沙箱中： - 檔案系統存取僅限於專案目錄 - 網路存取受到控制 - 特定命令不受沙箱限制 - 若autoAllowBashIfSandboxed為true，則自動允許Bash命令

專家提示：沙箱模式非常適合讓Claude處理不受信任的程式碼庫。探索陌生專案或需要額外一層保護時，建議啟用。Anthropic的內部測試發現，沙箱可減少84%的權限提示。³⁸沙箱利用作業系統層級的基本機制（macOS seatbelt、Linux bubblewrap）隔離檔案系統與網路，因此即使提示注入成功，也會受到完整限制。Anthropic已將沙箱執行階段開放原始碼，供建立自有agent的團隊使用。⁸²

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

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

巢狀.claude/解析（v2.1.178）：當您處理某個目錄下的檔案時，巢狀.claude/skills目錄中的skills現在會自動載入，不再僅從儲存庫根目錄載入。若名稱衝突，可用<dir>:<name>存取巢狀skill，因此兩者皆能保留。專案的其他介面也採用相同解析方式：當agent、工作流程或輸出樣式名稱在巢狀.claude/目錄之間衝突時，以最接近工作目錄者為準；儲存專案範圍工作流程時，則會以最接近的現有.claude/workflows/為目的地。對monorepo或由多個儲存庫組成的儲存庫而言，這讓各套件的工具能依情境啟用，不必全部擠在單一扁平的全域介面中。¹⁷³

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

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

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

v2.1.214的權限封閉失敗強化：¹⁹⁰

此版本一次修補多項權限檢查漏洞，並一律採取封閉失敗方向：分析器無法確認時便會顯示提示。

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

Hooks 如何運作？

Hooks 會在 Claude Code 工作流程的特定時點執行確定性的 shell 指令。不同於透過提示要求 Claude 執行動作，hooks 無論模型如何運作，都能保證執行。若要落實團隊標準並自動處理重複性工作，hooks 不可或缺。請參閱決策架構，其中的「該選擇哪一種 Hook 類型？」決策樹涵蓋 command、prompt 與 agent hooks。

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

可用事件