進階功能 (Advanced Features)

本指南全面介紹 Claude Code 的進階功能，包含計畫模式 (Planning Mode)、延伸思考 (Extended Thinking)、自動模式 (Auto Mode)、背景任務 (Background Tasks)、權限模式 (Permission Modes)、列印模式 (Print Mode，非互動式)、工作階段管理 (Session Management)、互動功能 (Interactive Features)、頻道 (Channels)、語音聽寫 (Voice Dictation)、遠端控制 (Remote Control)、網頁工作階段 (Web Sessions)、桌面應用程式 (Desktop App)、任務列表 (Task List)、提示詞建議 (Prompt Suggestions)、Git 工作樹 (Git Worktrees)、沙盒化 (Sandboxing)、託管設定 (Managed Settings) 以及組態設定 (Configuration)。

目錄 (Table of Contents)

概述 (Overview)
計畫模式 (Planning Mode)
延伸思考 (Extended Thinking)
自動模式 (Auto Mode)
背景任務 (Background Tasks)
監測工具 (Monitor Tool，事件驅動流)
動態工作流 (Dynamic Workflows)
排程任務 (Scheduled Tasks)
權限模式 (Permission Modes)
無頭模式 (Headless Mode)
工作階段管理 (Session Management)
跨工作階段訊息傳遞 (Cross-Session Messaging)
互動功能 (Interactive Features)
輸出樣式 (Output Styles)
狀態列 (Status Line)
TUI 模式 (全螢幕) (TUI Mode)
語音聽寫 (Voice Dictation)
頻道 (Channels)
Chrome 整合 (Chrome Integration)
遠端控制 (Remote Control)
網頁工作階段 (Web Sessions)
桌面應用程式 (Desktop App)
任務列表 (Task List)
提示詞建議 (Prompt Suggestions)
Git 工作樹 (Git Worktrees)
沙盒化 (Sandboxing)
託管設定 (企業版) (Managed Settings)
組態與設定 (Configuration and Settings)
信任與權限範圍 (Trust and Permission Scoping)
代理團隊 (Agent Teams)
最佳實踐 (Best Practices)
其他資源 (Additional Resources)

概述 (Overview)

Claude Code 中的進階功能擴展了核心能力，加入了計畫、推理、自動化與控制機制。這些功能能為複雜的開發任務、程式碼審查 (Code Review)、自動化以及多工作階段管理提供靈活且強大的工作流 (Workflows)。

核心進階功能包括：

計畫模式 (Planning Mode)：在編寫程式碼之前建立詳細的實作計畫
延伸思考 (Extended Thinking)：針對複雜問題進行深度推理
自動模式 (Auto Mode)：背景安全分類器在執行每個動作前進行審查
背景任務 (Background Tasks)：執行長時間運作的操作而不阻塞對話
權限模式 (Permission Modes)：控制 Claude 可以執行的操作 (manual — 原為 default、acceptEdits、plan、auto、dontAsk、bypassPermissions)
列印模式 (Print Mode)：非互動式執行 Claude Code，適用於自動化與 CI/CD (claude -p)
工作階段管理 (Session Management)：管理多個工作階段
互動功能 (Interactive Features)：快捷鍵、多行輸入與命令歷史紀錄
語音聽寫 (Voice Dictation)：按住說話 (Push-to-talk) 語音輸入，支援 20 種語言 STT
頻道 (Channels)：MCP 伺服器將訊息推送至正在執行的工作階段中 (Research Preview)
遠端控制 (Remote Control)：從 Claude.ai 或 Claude 應用程式控制 Claude Code
網頁工作階段 (Web Sessions)：直接在瀏覽器 (claude.ai/code) 執行 Claude Code
桌面應用程式 (Desktop App)：獨立應用程式，支援視覺化 Diff 審查與多工作階段
任務列表 (Task List)：跨脈絡壓縮 (Context Compaction) 持久追蹤任務
提示詞建議 (Prompt Suggestions)：根據脈絡提供智慧命令建議
Git 工作樹 (Git Worktrees)：隔離的工作樹分支，用於平行開發
沙盒化 (Sandboxing)：作業系統層級的檔案系統與網路隔離
託管設定 (Managed Settings)：透過 plist、機碼 (Registry) 或託管檔案進行企業部署
組態設定 (Configuration)：使用 JSON 組態設定檔自訂行為

計畫模式 (Planning Mode)

計畫模式允許 Claude 在實作前深入思考複雜任務，建立您可以審查與批准的詳細計畫。

什麼是計畫模式？ (What is Planning Mode?)

計畫模式採用兩階段方法：

計畫階段 (Planning Phase)：Claude 分析任務並建立詳細的實作計畫
實作階段 (Implementation Phase)：獲得批准後，Claude 執行該計畫

何時使用計畫模式 (When to Use Planning Mode)

✅ 適合使用計畫模式的場景：

複雜的多檔案重構 (Refactoring)
新功能實作
架構調整
資料庫遷移 (Database Migrations)
重大 API 重構

❌ 不建議使用計畫模式的場景：

簡單的 Bug 修復
格式化調整
單一檔案修改
快速查詢

啟用計畫模式 (Activating Planning Mode)

斜線指令 (Slash command)：

bash

/plan Implement user authentication system

CLI 旗標 (CLI flag)：

bash

claude --permission-mode plan

設定為預設值 (Set as default)：

json

{
  "permissions": {
    "defaultMode": "plan"
  }
}

快捷鍵 (Keyboard shortcut)：

Shift + Tab - 切換權限模式（包含 plan）
Alt + M - 切換權限模式 (Windows/Linux)

計畫模式的優勢 (Benefits of Planning Mode)

結構化實作方法：詳細拆解實作步驟
審查與批准：在執行前批准或調整計畫
風險識別：在實作前找出潛在問題
明確階段：具體組織實作階段與里程碑

範例：功能實作 (Example: Feature Implementation)

User: /plan Add a real-time notification system

Claude: I'll create a plan for implementing real-time notifications.

## Implementation Plan

### Phase 1: Infrastructure Setup
1. Install WebSocket libraries (socket.io)
2. Set up WebSocket server
3. Configure connection management

### Phase 2: Backend Implementation
4. Create notification service
5. Implement notification queue
6. Add database schema for notifications
7. Create API endpoints

### Phase 3: Frontend Integration
8. Set up WebSocket client
9. Create notification UI components
10. Implement notification state management
11. Add notification permissions

### Phase 4: Testing & Deployment
12. Write unit tests
13. Write integration tests
14. Update documentation
15. Deploy to staging

Estimated time: 3-4 hours
Files to modify: 12
New files to create: 8

Ready to proceed? (yes/no/modify plan)

User: yes

Claude: [Begins implementation following the plan]

計畫修改 (Plan Modifications)

User: Modify the plan - skip the queue for now, we'll add it later

Claude: Updated plan:
[Shows modified plan with queue removed]

User: Looks good, proceed

Claude: [Implements modified plan]

計畫模式組態設定 (Planning Mode Configuration)

計畫模式可透過 CLI 旗標或斜線指令啟用：

bash

# Activate plan mode via CLI
claude --permission-mode plan

# Or use the /plan slash command inside the REPL
/plan Implement user authentication system

計畫用的模型別名 (Model alias for planning)： 使用 opusplan 做為模型別名，以 Opus 進行計畫、Sonnet 進行執行：

bash

claude --model opusplan "design and implement the new API"

在外部編輯器中編輯計畫 (Edit plan externally)： 按 Ctrl+G 可在外部編輯器中開啟當前計畫以進行詳細修改。

v2.1.112 更新：計畫檔案現在改以產生該計畫的提示詞命名（取代之前的隨機單字），方便瀏覽與重複使用。

v2.1.136 更新 — 計畫模式寫入區塊為無條件 (plan-mode write blocks are unconditional)：計畫模式現在會無條件阻止所有檔案寫入，即使 permissions.allow 中存在匹配的 Edit(...) 規則也不例外。過去在計畫模式中，寬鬆的 Edit(...) 規則可能會允許寫入；該繞過漏洞已被關閉。若工作流依賴過去的行為，請在編輯前退出計畫模式 (Shift+Tab)。

延伸思考 (Extended Thinking)

延伸思考允許 Claude 在提供解決方案前花費更多時間對複雜問題進行推理。

什麼是延伸思考？ (What is Extended Thinking?)

延伸思考是一個深思熟慮、循序漸進的推理過程，Claude 會：

拆解複雜問題
考量多種方法
評估權衡 (Trade-offs)
推理邊角情況 (Edge cases)

啟用延伸思考 (Activating Extended Thinking)

快捷鍵 (Keyboard shortcut)：

Option + T (macOS) / Alt + T (Windows/Linux) - 切換延伸思考

自動啟用 (Automatic activation)：

所有模型（Opus 5、Opus 4.8、Opus 4.7、Sonnet 4.6、Haiku 4.5）預設皆已啟用。
Opus 5 / Opus 4.8：具備自適應推理與努力等級 (Effort Levels)：low (○)、medium (◐)、high (●)、xhigh、max。在 Opus 5 (v2.1.219)、Opus 4.8 (v2.1.154)、Opus 4.6 與 Sonnet 4.6 上預設為 high，在 Opus 4.7 上預設為 xhigh。xhigh 可用於 Opus 5、Opus 4.8 與 Opus 4.7（在 Opus 4.6 / Sonnet 4.6 上會降級回 high）。max 可在 Opus 5、Opus 4.8/4.7/4.6 及 Sonnet 4.6 上運作（僅限工作階段）。Haiku 4.5 沒有努力等級。Opus 5、Opus 4.8 與 Opus 4.7 擁有 1M Token 的原生脈絡視窗（1M Context 修正已於 v2.1.117 推出 — 在此之前，/context 會誤將 Opus 4.7 當作 200K 視窗計算並觸發過早的自動壓縮）。自 v2.1.129 起，/context 僅在 UI 內顯示視覺化資訊；ASCII 視覺化圖表不再洩漏至對話脈絡中（每次呼叫節省約 1.6k Tokens），因此可以放心隨時呼叫 /context。
Opus 4.6 / Sonnet 4.6 上的 Pro/Max 訂戶：預設努力等級在 v2.1.117 中從 medium 提高到 high。
其他模型：固定配額最高 31,999 Tokens。

設定方式 (Configuration methods)：

切換：Alt+T / Option+T，或透過 /config
檢視推理：Ctrl+O（詳細模式 Verbose Mode）
設定努力等級：/effort 指令或 --effort 旗標

自訂配額 (Custom budget)：

bash

export MAX_THINKING_TOKENS=1024

努力等級 (Effort level)（支援 Opus 5、Opus 4.8、Opus 4.7、Opus 4.6 與 Sonnet 4.6 — Haiku 4.5 不支援）：

bash

export CLAUDE_CODE_EFFORT_LEVEL=high   # low (○), medium (◐), high (●), xhigh (Opus 5/4.8/4.7), or max — default is high on Opus 5 and Opus 4.8

CLI 旗標 (CLI flag)：

bash

claude --effort high "complex architectural review"

斜線指令 (Slash command)：

/effort high

注意： 提示詞中的關鍵字 "ultrathink" 會觸發深度推理模式。努力等級 low、medium、high 與 max 支援於 Opus 5、Opus 4.8、Opus 4.7、Opus 4.6 與 Sonnet 4.6（Haiku 4.5 不支援）。xhigh 適用於 Opus 5、Opus 4.8 與 Opus 4.7。Opus 5、Opus 4.8（以及 Opus 4.6 / Sonnet 4.6）的預設努力等級為 high，Opus 4.7 為 xhigh。與 Opus 4.8 和 Opus 4.7 在第一次執行時鎖定預設努力等級不同，Opus 5 沒有此限制 — 您先前設定的等級將持續沿用。/effort 選單還提供了 ultracode，這不是模型努力等級 — 它會發送 xhigh 並讓 Claude 調度動態工作流（僅限工作階段）。

Opus 5 上的安全分類器備援 (Safety-Classifier Fallback on Opus 5)

與 fallbackModel 設定（用於處理過載與不可用）不同，Claude Code 當安全分類器標記請求時會套用基於類別的備援 (Category-Based Fallback)。這需要 Claude Code v2.1.219 或更高版本。

Opus 5：被標記為資安 (Cybersecurity) 的請求會在 Opus 4.8 上重新執行。被標記為生物學 (Biology) 的請求則會直接拒絕，因為 Opus 5 執行自己的生物學分類器，沒有備援模型。從第一個被標記的請求起您就會收到這些拒絕。
在進攻性安全 (Offensive Security) 或生物學領域的工作負擔（滲透測試、CTF 競賽、生物學相關程式碼庫）會頻繁觸發備援，通常在第一次請求時就會發生。

為什麼這很重要：若您在 Opus 5 上執行資安審查子代理 (Security-Review Subagents) 或 CTF/滲透測試工作，資安提示詞可能會靜默地在 Opus 4.8 上重新執行（具備不同的努力等級上限與脈絡視窗），而生物學相關提示詞則會直接被拒絕。若此行為造成妨礙，請明確指定其他模型。

控制切換 (Controlling the switch) — switchModelsOnFlag 設定（v2.1.170+，預設為 true）決定是否靜默進行備援切換。將其設為 false，Claude Code 會改為暫停，讓您選擇切換模型或編輯提示詞。它在 /config 中顯示為 Switch models when a message is flagged。

json

{
  "switchModelsOnFlag": false
}

延伸思考的優勢 (Benefits of Extended Thinking)

深度推理 (Deep Reasoning)：花費更多時間思考複雜問題
更佳的架構決策：透徹評估後做出明智選擇
考量邊角情況：思考潛在問題與場景
周全分析：結構化解決複雜問題

範例：架構決策 (Example: Architectural Decision)

User: ultrathink Should we use microservices or a monolith for our e-commerce platform?

Claude: Let me think through this architectural decision carefully...

<extended_thinking>
## Context Analysis
- Team size: 5 developers
- Expected traffic: 10k daily users initially
- Need to scale to 100k+ users
- Limited DevOps resources
- 6-month timeline to MVP

## Approach 1: Microservices
Pros:
+ Independent scaling
+ Technology flexibility
+ Team independence
+ Fault isolation

Cons:
- Operational complexity
- Network overhead
- Distributed tracing needed
- Requires DevOps expertise
- Slower initial development

## Approach 2: Monolith
Pros:
+ Simpler deployment
+ Faster initial development
+ Easier debugging
+ Lower operational overhead
+ Single codebase

Cons:
- Scaling challenges later
- All-or-nothing deployments
- Technology lock-in
- Potential for tight coupling

## Decision Factors
1. Team size (5 devs) → Favors monolith
2. DevOps resources (limited) → Favors monolith
3. Timeline (6 months) → Favors monolith
4. Future scale (100k users) → Achievable with monolith + caching
5. Complexity budget → Limited

## Recommendation
Start with a **modular monolith**:
- Single deployment unit
- Clear module boundaries
- Clean interfaces between modules
- Prepare for future extraction to microservices if needed

This gives you:
✓ Fast initial development
✓ Low operational complexity
✓ Option to extract services later
✓ Clear architecture

Migration path: When you reach 50k+ users or specific modules need independent scaling, extract those modules into microservices.
</extended_thinking>

**Recommendation**: Implement a modular monolith with clean module boundaries.

This approach balances your current constraints (team size, timeline, DevOps resources) with future scalability needs. You can migrate specific modules to microservices later when there's a clear business need.

延伸思考組態設定 (Extended Thinking Configuration)

延伸思考可透過環境變數、快捷鍵與 CLI 旗標進行控制：

bash

# Set thinking token budget
export MAX_THINKING_TOKENS=16000

# Set effort level (Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 4.6): low (○), medium (◐), high (●), xhigh (Opus 5/4.8/4.7), or max — default is high on Opus 5 and Opus 4.8
export CLAUDE_CODE_EFFORT_LEVEL=high

在對話期間可使用 Alt+T / Option+T 進行切換，使用 /effort 設定努力等級，或透過 /config 進行設定。

精簡版系統提示詞 (Lean System Prompt, v2.1.154)： 精簡版系統提示詞現在是除了 Haiku、Sonnet 以及 Opus 4.7 與更早版本之外所有模型的預設值，從而降低了 Opus 5 與 Opus 4.8 上的基礎 Token 開銷。

自動模式 (Auto Mode)

自動模式 (Auto Mode) 是一種權限模式，使用背景安全分類器在執行每個動作前進行審查。它允許 Claude 自行運作，同時封鎖危險操作。所有方案均可使用，但需要符合條件的模型（Anthropic API 與 AWS Claude Platform 上的 Claude Opus 5、Opus 4.6+、Sonnet 4.6+ 或 Fable 5；Bedrock、Vertex、Foundry 與已登入的 Claude Apps Gateway 工作階段上的 Opus 5、Sonnet 5、Opus 4.7、Opus 4.8 或 Fable 5）。在 Team 與 Enterprise 方案中預設啟用 — 管理員可在託管設定中為全組織關閉此功能。

需求條件 (Requirements)

僅當您的帳戶符合以下所有條件時，自動模式才可用：

方案 (Plan)：所有方案。
組織 (Organization)：在 Team 與 Enterprise 方案中預設可用。管理員可透過在託管設定中將 permissions.disableAutoMode 設定為 "disable" 來為全組織關閉此功能。
模型 (Model)：在 Anthropic API 與 AWS Claude Platform 上 — Claude Opus 4.6 或更高版本（包含 Opus 5）、Sonnet 4.6 或更高版本、或 Fable 5。在 Amazon Bedrock、Google Cloud Agent Platform (Vertex AI)、Microsoft Foundry 及已登入的 Claude Apps Gateway 工作階段上 — 僅限 Claude Sonnet 5、Opus 4.7 或更高版本（包含 Opus 5）以及 Fable 5。任何提供者皆不支援舊型模型（Sonnet 4.5、Opus 4.5、Haiku 及 claude-3 模型）。
提供者 (Provider)：在 Anthropic API、AWS Claude Platform、Amazon Bedrock、Google Cloud Agent Platform (Vertex AI)、Microsoft Foundry 與已登入的 Claude Apps Gateway 工作階段上預設可用。在 v2.1.158 至 v2.1.206 中，除了 Anthropic API 與 AWS Claude Platform 之外，這些提供者上的自動模式預設為關閉，直到您設定 CLAUDE_CODE_ENABLE_AUTO_MODE=1 為止；v2.1.207 移除了該需求。為保持相容性，該變數仍被接受，但自 v2.1.207 起不起作用。
分類器 (Classifier)：在 Claude Sonnet 4.6 上執行（會增加額外 Token 成本）

啟用自動模式 (Enabling Auto Mode)

bash

# Unlock auto mode with CLI flag (no longer required for Max subscribers on Opus 4.7 — access it directly)
claude --enable-auto-mode

# Then cycle to it with Shift+Tab in the REPL

v2.1.112 更新：自動模式不再需要 --enable-auto-mode 旗標。Max 訂戶可以在 Opus 4.7 上直接使用。

v2.1.158 更新：自動模式在 Bedrock、Vertex 與 Foundry 上可用於 Opus 4.7/4.8，但需透過 CLAUDE_CODE_ENABLE_AUTO_MODE=1 開啟。
v2.1.207 更新：移除了手動選擇開啟的需求。自動模式現在預設適用於 Bedrock、Vertex AI、Microsoft Foundry 及已登入的 Claude Apps Gateway 工作階段（支援 Claude Sonnet 5、Opus 4.7、Opus 4.8 與 Fable 5，以及自 v2.1.219 起的 Opus 5）— 不需要旗標或環境變數。管理員可透過託管設定中的 disableAutoMode 將其停用。CLAUDE_CODE_ENABLE_AUTO_MODE 為相容性保留，但自 v2.1.207 起無效果。

或將其設定為預設權限模式：

bash

claude --permission-mode auto

透過設定檔進行設定：

json

{
  "permissions": {
    "defaultMode": "auto"
  }
}

分類器的運作方式 (How the Classifier Works)

背景分類器會依以下決策順序評估每個動作：

允許/拒絕規則 (Allow/deny rules) -- 優先檢查明確的權限規則
唯讀/編輯自動核准 (Read-only/edits auto-approved) -- 檔案讀取與編輯自動通過
分類器 (Classifier) -- 背景分類器審查該動作
備援 (Fallback) -- 在連續封鎖 3 次或累計封鎖 20 次後，退回提示詢問使用者

預設封鎖的動作 (Default Blocked Actions)

自動模式預設封鎖以下動作：

封鎖的動作	範例
管道傳輸至 Shell 安裝 (Pipe-to-shell installs)	`curl \| bash`
向外發送敏感資料	透過網路發送 API Key、憑證
生產環境部署	針對生產環境的部署指令
大規模刪除	在大資料夾上執行 `rm -rf`
IAM 變更	權限與角色修改
強制推送至 main 分支	`git push --force origin main`

更多決策交由分類器處理 (v2.1.218)：分類器現在也負責審查針對檔案系統根目錄或主目錄的刪除動作（如 rm -rf / 與 rm -rf ~），包括刪除指令位於命令替換或程序替換內的情況。在 v2.1.218 之前，純指令形式會提示請求核准，而替換形式在 v2.1.208 至 v2.1.217 期間會提示。背景 & 執行與可疑的 Windows 路徑檢查也不再跳出權限對話框 — 一律交由分類器判斷。

預設允許的動作 (Default Allowed Actions)

允許的動作	範例
本地檔案操作	讀取、寫入、編輯專案檔案
聲明的依賴套件安裝	根據清單執行 `npm install`、`pip install`
唯讀 HTTP	讀取文件用的 `curl`
推送至當前分支	`git push origin feature-branch`

組態自動模式 (Configuring Auto Mode)

印出預設規則 JSON (Print default rules as JSON)：

bash

claude auto-mode defaults

重置預設自動模式組態 (Restore default auto-mode configuration)（v2.1.212），會跳出確認提示（--yes 可跳過）：

bash

claude auto-mode reset
claude auto-mode reset --yes

設定信任的基礎設施 (Configure trusted infrastructure) 透過企業部署的 autoMode.environment 託管設定。允許管理員定義信任的 CI/CD 環境、部署目標與基礎設施模式。

使用 `"$defaults"` 擴充預設值 (v2.1.118)

自 v2.1.118 起，autoMode.allow、autoMode.soft_deny 與 autoMode.environment 接受 "$defaults" 標記，將您的規則附加至內建清單後面，而不是直接覆蓋它。在 v2.1.118 之前，任何使用者定義的陣列都會靜默覆蓋內建規則。

使用 `autoMode.hard_deny` 進行無條件封鎖 (v2.1.136)

autoMode.hard_deny（v2.1.136+）是一個分類器規則陣列，用來封鎖特定類型的動作，無論推斷出的使用者意圖為何。可用於絕不能在自動模式中執行的動作 — 例如在根路徑上執行 rm -rf 或在受保護分支上執行 git push --force。與 soft_deny 不同，hard-deny 規則無法透過分類器進行協商。

json

{
  "autoMode": {
    "hard_deny": ["Bash(rm -rf /:*)", "Bash(git push --force*)"]
  }
}

之前（覆蓋內建規則 — v2.1.118 之前的行為）：

json

{
  "autoMode": {
    "allow": ["Bash(gh pr list:*)"]
  }
}

之後（擴充內建規則 — v2.1.118+）：

json

{
  "autoMode": {
    "allow": ["$defaults", "Bash(gh pr list:*)"],
    "soft_deny": ["$defaults", "Bash(kubectl delete:*)"],
    "environment": ["$defaults", "trusted-ci.internal"]
  }
}

使用 "$defaults" 保留內建的基礎規則，同時在其上疊加組織或專案特定的補充規則。

使用 `autoMode.classifyAllShell` 分類所有 Shell 指令 (v2.1.193)

autoMode.classifyAllShell（布林值，v2.1.193+）將所有 Bash/PowerShell 指令路由至自動模式分類器。當您希望分類器檢查工作階段中的每一個 Shell 指令時可啟用此功能。

json

{
  "autoMode": {
    "classifyAllShell": true
  }
}

同一版本中，當自動模式封鎖某個動作時會顯示拒絕原因 (Denial Reason) — 可在逐字稿 (Transcript)、拒絕快顯通知 (Toast) 與 /permissions 底下的最近拒絕清單中檢視 (v2.1.193+)。

內建意圖保護 (Built-in intent-based protection, v2.1.183)

除了使用者設定的 hard_deny 外，自動模式預設會封鎖以下破壞性指令，除非您在該工作階段中明確要求執行：

git reset --hard、git checkout -- .、git clean -fd、git stash drop
git commit --amend（當該 Commit 不是代理人在該工作階段中所建立時）
terraform destroy、pulumi destroy、cdk destroy（除非您要求針對特定 Stack）

這是由推斷意圖驅動的內建預設保護 — 您不需要手動將這些加入 hard_deny 中。

設定等同自動模式的權限 (無需 Team 方案)

若您沒有 Team 方案，或想採用沒有背景分類器的簡化方法，您可以為 ~/.claude/settings.json 注入保守的安全權限規則基線。該腳本從唯讀與本地檢查規則開始，讓您僅在需要時手動選擇開啟編輯、測試、本地 Git 寫入、套件安裝與 GitHub 寫入動作。

檔案： 09-advanced-features/setup-auto-mode-permissions.py

bash

# Preview what would be added (no changes written)
python3 09-advanced-features/setup-auto-mode-permissions.py --dry-run

# Apply the conservative baseline
python3 09-advanced-features/setup-auto-mode-permissions.py

# Add more capability only when you need it
python3 09-advanced-features/setup-auto-mode-permissions.py --include-edits --include-tests
python3 09-advanced-features/setup-auto-mode-permissions.py --include-git-write --include-packages

腳本會新增跨越以下類別的規則：

類別	範例
核心唯讀工具	`Read()`, `Glob()`, `Grep()`, `Agent()`, `WebSearch()`, `WebFetch()`
本地檢查	`Bash(git status:)`, `Bash(git log:)`, `Bash(git diff:)`, `Bash(cat:)`
可選編輯	`Edit()`, `Write()`, `NotebookEdit(*)`
可選測試/建置	`Bash(pytest:)`, `Bash(python3 -m pytest:)`, `Bash(cargo test:*)`
可選 Git 寫入	`Bash(git add:)`, `Bash(git commit:)`, `Bash(git stash:*)`
Git (本地寫入)	`Bash(git add:)`, `Bash(git commit:)`, `Bash(git checkout:*)`
套件管理器	`Bash(npm install:)`, `Bash(pip install:)`, `Bash(cargo build:*)`
建置與測試	`Bash(make:)`, `Bash(pytest:)`, `Bash(go test:*)`
常見 Shell	`Bash(ls:)`, `Bash(cat:)`, `Bash(find:)`, `Bash(cp:)`, `Bash(mv:*)`
GitHub CLI	`Bash(gh pr view:)`, `Bash(gh pr create:)`, `Bash(gh issue list:*)`

危險操作（rm -rf、sudo、強制推送、DROP TABLE、terraform destroy 等）被刻意排除。腳本具備等冪性 (Idempotent) — 執行兩次不會產生重複規則。

背景任務 (Background Tasks)

背景任務允許長時間運作的操作在非阻塞對話的情況下執行。

什麼是背景任務？ (What Are Background Tasks?)

背景任務會在您繼續工作的同時非同步 (Asynchronously) 執行：

長時間測試套件 (Test Suites)
建置程序 (Build Processes)
資料庫遷移
部署腳本
分析工具

基本用法：

bash

User: Run tests in background

Claude: Started task bg-1234

/task list           # Show all tasks
/task status bg-1234 # Check progress
/task show bg-1234   # View output
/task cancel bg-1234 # Cancel task

啟動背景任務 (Starting Background Tasks)

User: Run the full test suite in the background

Claude: Starting tests in background (task-id: bg-1234)
You can continue working while tests run.

[You can continue the conversation]

User: Meanwhile, let's refactor the auth module

Claude: [Works on auth module while tests run in background]

[Later, when tests complete]

Claude: 📢 Background task bg-1234 completed:
✅ 245 tests passed
❌ 3 tests failed
View results: /task show bg-1234

管理背景任務 (Managing Background Tasks)

列出作用中的任務：

User: /task list

Active background tasks:
1. [bg-1234] Running tests (50% complete, 2min remaining)
2. [bg-1235] Building Docker image (25% complete, 8min remaining)
3. [bg-1236] Deploying to staging (90% complete, 30sec remaining)

檢查任務狀態：

User: /task status bg-1234

Task bg-1234: Running tests
Status: In progress
Progress: 120/245 tests (49%)
Started: 2025-11-08 10:30:15
Estimated completion: 2025-11-08 10:34:22

檢視任務輸出：

User: /task show bg-1234

[Shows live output from the test run]

取消任務：

User: /task cancel bg-1234

Cancelled background task bg-1234

範例：平行開發 (Example: Parallel Development)

User: Run the build in the background

Claude: Starting build... (task-id: bg-5001)

User: Also run the linter in background

Claude: Starting linter... (task-id: bg-5002)

User: While those run, let's implement the new API endpoint

Claude: [Implements API endpoint while build and linter run]

[10 minutes later]

Claude: 📢 Build completed successfully (bg-5001)
📢 Linter found 12 issues (bg-5002)

User: Show me the linter issues

Claude: [Shows linter output from bg-5002]

組態設定 (Configuration)

背景任務沒有專用的 settings.json 區塊，該功能由環境變數控制：

bash

# Turn background tasks off entirely
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=true

邊界並發數量也不是背景任務的單獨設定 — 有多少個代理人可以同時執行由 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS 控制（預設為 20）。

監測工具 (Monitor Tool，事件驅動流)

v2.1.98 新增：Monitor 工具讓 Claude 能夠監視背景指令的 stdout，並在符合條件的事件出現時立即做出反應 — 取代輪詢迴圈 (Polling loops) 與 sleep 來等待長時間運作的程序。

Monitor 可附加至任何會寫入 stdout 的 Shell 指令。該指令輸出的每一行 stdout 都會成為喚醒工作阶段的通知。Claude 指定指令；測試框架 (Harness) 串流輸出並在事件觸發時發送。請參閱相關的背景任務 (Background Tasks) 章節以了解如何啟動底層程序。

為什麼這很重要 (Why It Matters)

使用 /loop 或 sleep 進行輪詢會在每個週期消耗完整的 API 來回，無論是否有變化。Monitor 會保持沉默直到事件觸發，在指令安靜時消耗 零 Tokens。當事件發生時，Claude 會立即回應 — 無需等待下一次輪詢週期的延遲。對於任何運行超過幾分鐘的操作，這都比輪詢迴圈更便宜且更快速。

兩種常見模式 (Two Common Patterns)

串流過濾器 (Stream Filters) 監視來自長時間運作來源的持續輸出。指令永久執行；每個符合的行都是一個事件。

bash

tail -f /var/log/app.log | grep --line-buffered "ERROR"

輪詢與發送過濾器 (Poll-and-emit Filters) 定期檢查來源，僅在發生變化時發送。適用於 API、資料庫或任何沒有原生串流的來源。

bash

last=$(date -u +%Y-%m-%dT%H:%M:%SZ)
while true; do
  gh api "repos/owner/repo/issues/123/comments?since=$last" || true
  last=$(date -u +%Y-%m-%dT%H:%M:%SZ)
  sleep 30
done

具體範例 (Concrete Example)

「啟動我的開發伺服器並監測是否有錯誤。」Claude 將伺服器作為背景任務啟動，附加 Monitor 過濾器 (tail -F server.log | grep --line-buffered -E "ERROR|FATAL")，然後工作階段進入沉靜狀態。當日誌中出現錯誤行時，Claude 立即被喚醒、讀取錯誤並進行回應 — 重啟伺服器、修復 Bug 或回報給您 — 無需您手動檢查。

警告：透過管道傳輸給 grep 時，務必使用 grep --line-buffered。如果沒有它，grep 會在 4KB 區塊中快取 stdout，這可能會在低流量串流中將事件延遲數分鐘。這是 Monitor 在實作中最常失敗的原因 — 若您的過濾器看起來沒有反應，請先檢查是否有 --line-buffered 旗標。

動態工作流 (Dynamic Workflows)

v2.1.154 新增

動態工作流 (Dynamic Workflows) 允許 Claude 確定性地 (Deterministically) 調度數十至數百個背景子代理 (Subagents) — 扇出 (Fan-out)、管道 (Pipelines) 與平行階段均透過腳本編碼，而非交給模型即興發揮。單一代理人僅能持有單一脈絡視窗，而工作流將任務拆分至多個代理人並重新組合其結果。

自 v2.1.219 起，動態工作流預設採用 中等規模指南（目標少於 15 個代理人）。可透過 /config 中的 Dynamic workflow size 選擇其他規模（或不限制），或在設定檔中設定 workflowSizeGuideline 鍵。運作中的工作流狀態列會顯示當前規模並引導至 /config 進行變更。

何時使用 (When to Use Them)

全面覆蓋 — 在多個檔案/維度上記錄審查或平行審查。
信心保證 — 產生獨立的視角，並在提交前進行對抗式驗證。
超越單一脈絡 — 單一脈絡無法容納的大型遷移、廣泛掃描或研究。

對於您已經理解的一次性任務，單一代理人（或直接編輯）仍是正確的工具 — 當工作呈現散開發散時，工作流才會展現價值。

啟動與檢視 (Launching and Viewing)

啟動：要求 Claude 為任務建立工作流（例如 "run a workflow to review every file in src/"）。Claude 會編寫調度腳本並在背景執行。
檢視：/workflows 指令顯示執行中與已完成的工作流，並提供即時進度。
ultracode：在 /effort 選單中選擇 ultracode 會為該工作階段開啟此功能 — 它會向模型發送 xhigh，並讓 Claude 預設調度動態工作流。這僅限工作階段，設定檔中不接受。（自 v2.1.160 起，觸發關鍵字為 ultracode；單獨的單字 "workflow" 不再觸發執行。）

工作流建立在子代理模型之上 — 關於個別代理人如何定義與界定範圍，請參閱子代理 (Subagents)。

排程任務 (Scheduled Tasks)

排程任務 (Scheduled Tasks) 允許您按重複的時間表或作為一次性提醒自動執行提示詞。任務的作用域為工作階段 (Session-scoped) — 它們在 Claude Code 作用期間執行，並在工作階段結束時清除。自 v2.1.72+ 起可用。

在 claude.com 上稱為 "Routines" (2026-05-14)：Anthropic 的產品部落格將此介面稱為 Routines。CLI 指令仍保持為 /schedule；本指南為保持連貫性使用原始的 "Scheduled Tasks" 名稱。若您在 claude.com 文件或桌面應用程式中看到 "Routines"，指的是相同的功能。

`/loop` 指令

bash

# Explicit interval
/loop 5m check if the deployment finished

# Natural language
/loop check build status every 30 minutes

也支援標準的 5 欄位 Cron 表達式以進行精確排程。

一次性提醒 (One-time Reminders)

設定在特定時間觸發一次的提醒：

remind me at 3pm to push the release branch
in 45 minutes, run the integration tests

管理排程任務 (Managing Scheduled Tasks)

工具	說明
`CronCreate`	建立新的排程任務
`CronList`	列出所有作用中的排程任務。自 v2.1.136 起，輸出亦包含限定條件與排程的提示詞內容，因此無需開啟即可審查每個 Cron 將執行的內容。
`CronDelete`	刪除排程任務

限制與行為：

每個工作階段最多 50 個排程任務
工作階段作用域 — 工作階段結束時清除
重複執行的任務在 3 天 後自動過期
任務僅在 Claude Code 執行期間觸發 — 錯過的時間點不會補執行 (No catch-up)

行為細節 (Behavior Details)

方面	細節
重複執行抖動 (Recurring jitter)	最多為間隔時間的 10%（最多 15 分鐘）
一次性抖動 (One-shot jitter)	在 :00/:30 邊界最多 90 秒
錯過觸發 (Missed fires)	不會補執行 — 若 Claude Code 未執行則直接跳過
持久性 (Persistence)	重啟後不會保留

雲端排程任務 (Cloud Scheduled Tasks)

使用 /schedule 建立在 Anthropic 基礎設施上執行的雲端排程任務：

/schedule daily at 9am run the test suite and report failures

雲端排程任務跨重啟持久保留，且不需要 Claude Code 在本地運作。

停用排程任務 (Disabling Scheduled Tasks)

bash

export CLAUDE_CODE_DISABLE_CRON=1

/schedule 因 API Key 層級自動停用 (v2.1.139)：當設定了 ANTHROPIC_API_KEY、ANTHROPIC_AUTH_TOKEN 或 apiKeyHelper 中的任何一個時，雲端 /schedule 會靜默不可用 — 即使您同時登入了 claude.ai。相同的條件也會停用遠端控制 (Remote Control)、claude.ai MCP 連接器與通知偏好設定。取消設定 API Key（或在 Pro/Max OAuth 層級上執行）以使用 /schedule。本地的 CronCreate 不受影響。

範例：監測部署 (Example: Monitoring a Deployment)

/loop 5m check the deployment status of the staging environment.
        If the deploy succeeded, notify me and stop looping.
        If it failed, show the error logs.

提示：排程任務僅限工作階段作用域。對於跨重啟的持久自動化，請改用 CI/CD 管道、GitHub Actions 或桌面應用程式的排程任務。

權限模式 (Permission Modes)

權限模式控制 Claude 在沒有明確批准的情況下可以採取哪些動作。

可用的權限模式 (Available Permission Modes)

模式	行為
`manual`	僅讀取檔案；其他所有動作均需提示確認。在 v2.1.200 中由 `default` 更名 — `default` 仍被接受作為別名
`acceptEdits`	讀取與編輯檔案；指令仍需提示確認
`plan`	僅讀取檔案（研究模式，禁止編輯）
`auto`	所有動作經由背景安全分類器檢查。需要符合條件的模型（多數提供者上的 Opus 5、Sonnet 5、Opus 4.7/4.8 或 Fable 5）與提供者 — 適用於所有方案，請參閱自動模式 (Auto Mode)
`bypassPermissions`	所有動作皆可執行，無權限檢查（危險）
`dontAsk`	僅執行預先批准的工具；其他一律拒絕

注意：互動式預設模式在 v2.1.200 中已更名為 Manual（涵蓋 CLI、--help、VS Code 與 JetBrains），且在啟用時頁尾會顯示灰色的 ⏸ 標籤 (v2.1.203)。--permission-mode manual 與 --permission-mode default 均可運作，設定檔中的 "defaultMode": "manual" 與 "defaultMode": "default" 亦同。請注意，設定檔的鍵值為 permissions.defaultMode — 沒有 permissions.mode 鍵，因此範例均使用標準拼寫。

計畫模式將 Shell 指令委派給分類器 (v2.1.218)：當自動模式可用且 useAutoModeDuringPlan 設定開啟時（預設為開啟），分類器會在計畫期間審查 Shell 指令，而不是提示您。經批准的指令會執行，被拒絕的會被封鎖。計畫模式仍無條件封鎖檔案寫入。

自 v2.1.160 起，即使是 acceptEdits 模式，在寫入 Shell 啟動檔案（.zshenv、.zlogin、.bash_login、~/.config/git/）與執行程式碼的建置組態檔（.npmrc、.yarnrc*、bunfig.toml、.bazelrc、.pre-commit-config.yaml、.devcontainer/ 等）前也會發出提示，以避免非預期的指令執行。

--dangerously-skip-permissions 擴展路徑覆蓋範圍 (v2.1.121, v2.1.126)：--dangerously-skip-permissions CLI 旗標（以及同等的 bypassPermissions 模式）現在對更廣泛的允許清單寫入跳過提示 — .claude/skills/、.claude/agents/、.claude/commands/、.claude/、.git/、.vscode/ 以及 Shell 組態檔。毀滅性的刪除指令（rm -rf / 等）在此模式下仍會發出提示（在自動模式中則由分類器判斷 — 參閱自動模式）。請將該旗標視為比以前更犀利的工具；僅在拋棄式沙盒中使用。

Windows Shell 偵測 (v2.1.120, v2.1.126)：不再強制需要 Git for Windows / Git Bash。當缺乏 Git Bash 時，Claude Code 會使用 PowerShell 作為 Shell 工具。自 v2.1.126 起，當 PowerShell 工具啟用時，PowerShell 會是主要 Shell，且偵測覆蓋透過 Microsoft Store、無 PATH 的 MSI 或作為 .NET global tool 安裝的 PowerShell 7。

Bedrock/Vertex/Foundry 在 Windows 上預設啟用 PowerShell 工具 (v2.1.143)：自 v2.1.143 起，PowerShell 工具在 Windows 上為 Bedrock、Vertex 與 Foundry 使用者預設啟用。Claude Code 以 -ExecutionPolicy Bypass 調用 PowerShell，因此即使系統策略為 Restricted 腳本也能執行。要讓 Claude Code 遵循系統執行策略，請設定 CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1。若要完全停用 PowerShell 工具，請設定 CLAUDE_CODE_USE_POWERSHELL_TOOL=0。

啟用方式 (Activation Methods)

快捷鍵：

bash

Shift + Tab  # Cycle through all 6 modes

斜線指令：

bash

/plan                  # Enter plan mode

CLI 旗標：

bash

claude --permission-mode plan
claude --permission-mode auto

設定檔：

json

{
  "permissions": {
    "defaultMode": "auto"
  }
}

權限模式範例 (Permission Mode Examples)

預設模式 (Default Mode)

Claude 在執行重大動作前會要求確認：

User: Fix the bug in auth.ts

Claude: I need to modify src/auth.ts to fix the bug.
The change will update the password validation logic.

Approve this change? (yes/no/show)

計畫模式 (Plan Mode)

在執行前審查實作計畫：

User: /plan Implement user authentication system

Claude: I'll create a plan for implementing authentication.

## Implementation Plan
[Detailed plan with phases and steps]

Ready to proceed? (yes/no/modify)

自動接受編輯模式 (Accept Edits Mode)

自動接受檔案修改：

User: acceptEdits
User: Fix the bug in auth.ts

Claude: [Makes changes without asking]

使用場景 (Use Cases)

程式碼審查 (Code Review)：

User: claude --permission-mode plan
User: Review this PR and suggest improvements

Claude: [Reads code, provides feedback, but cannot modify]

結對程式設計 (Pair Programming)：

User: claude --permission-mode default
User: Let's implement the feature together

Claude: [Asks for approval before each change]

自動化任務 (Automated Tasks)：

User: claude --permission-mode acceptEdits
User: Fix all linting issues in the codebase

Claude: [Auto-accepts file edits without asking]

無頭模式 (Headless Mode)

列印模式 (Print Mode, claude -p) 允許 Claude Code 在沒有互動式輸入的情況下執行，非常適合自動化與 CI/CD。這是非互動式模式，取代了較舊的 --headless 旗標。

什麼是列印模式？ (What is Print Mode?)

列印模式可實現：

自動化腳本執行
CI/CD 整合
批次處理 (Batch Processing)
排程任務

在列印模式下執行 (非互動式)

bash

# Run specific task
claude -p "Run all tests"

# Process piped content
cat error.log | claude -p "Analyze these errors"

# CI/CD integration (GitHub Actions)
- name: AI Code Review
  run: claude -p "Review PR"

其他列印模式用法範例

bash

# Run a specific task with output capture
claude -p "Run all tests and generate coverage report"

# With structured output
claude -p --output-format json "Analyze code quality"

# With input from stdin
echo "Analyze code quality" | claude -p "explain this"

範例：CI/CD 整合 (Example: CI/CD Integration)

GitHub Actions：

yaml

# .github/workflows/code-review.yml
name: AI Code Review

on: [pull_request]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Run Claude Code Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          claude -p --output-format json \
            --max-turns 3 \
            "Review this PR for:
            - Code quality issues
            - Security vulnerabilities
            - Performance concerns
            - Test coverage
            Output results as JSON" > review.json

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const review = JSON.parse(fs.readFileSync('review.json', 'utf8'));
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: JSON.stringify(review, null, 2)
            });

列印模式組態設定 (Print Mode Configuration)

列印模式 (claude -p) 支援多個用於自動化的旗標：

bash

# Limit autonomous turns
claude -p --max-turns 5 "refactor this module"

# Structured JSON output
claude -p --output-format json "analyze this codebase"

# With schema validation
claude -p --json-schema '{"type":"object","properties":{"issues":{"type":"array"}}}' \
  "find bugs in this code"

# Disable session persistence
claude -p --no-session-persistence "one-off analysis"

安全模式 (排錯用) (Safe Mode)

--safe-mode（以及 CLAUDE_CODE_SAFE_MODE 環境變數，如 CLAUDE_CODE_SAFE_MODE=1）在停用所有自訂設定的情況下啟動 Claude Code — CLAUDE.md、外掛程式 (Plugins)、技能 (Skills)、掛鉤 (Hooks) 與 MCP 伺服器都會關閉。

bash

# Launch with every customization disabled
claude --safe-mode

# Equivalent via environment variable
CLAUDE_CODE_SAFE_MODE=1 claude

這是一個排錯工具：當自訂設定引發問題時，在安全模式下啟動以隔離問題是出在您的設定中還是 Claude Code 本身。

工作階段管理 (Session Management)

有效地管理多個 Claude Code 工作階段。

工作階段管理指令 (Session Management Commands)

指令	說明
`/resume`	依 ID 或名稱恢復對話
`/rename`	為當前工作階段命名
`/fork [prompt]`	將對話複製到一個新的獨立背景工作階段中，並在此處繼續工作 (v2.1.212+)
`/subtask <task>`	衍生一個繼承完整對話的派生子代理，並將結果回報至此處 (v2.1.212+)
`/branch [name]`	切換至在此時間點複製的對話中，並保留原始對話
`claude -c`	繼續最近的對話
`claude -r "session"`	依名稱或 ID 恢復工作階段

恢復工作階段 (Resuming Sessions)

繼續上次對話：

bash

claude -c

恢復已命名的工作階段：

bash

claude -r "auth-refactor" "finish this PR"

重新命名當前工作階段（在 REPL 內部）：

/rename auth-refactor

v2.1.212 更新：在代理人檢視中輸入 /resume（不帶引數）會開啟過去工作階段的選擇器 — 包含已從可見清單中移除的工作階段 — 並將選擇的工作階段作為背景工作階段恢復。

分叉與分支工作階段 (Forking and Branching Sessions)

有三個指令可以複製對話，它們的差異在於複製出的內容在哪裡執行：

/subtask <task> 會衍生一個繼承完整對話的派生子代理，並在您繼續工作的同時執行任務 — 在 claude agents 中有其自己的行，並在完成時將結果傳回您的對話中：

/subtask Investigate why the auth tests are flaky

/fork [prompt] 則將對話複製到一個新的背景工作階段中。複製出來的內容包含截至目前的所有內容並獨立執行 — 不會有任何內容傳回當前對話：

/fork Try the OAuth approach end to end

若要自己切換到副本中而不是委派出去，請使用 /branch [name]，它會保留原始對話並允許您使用 /resume 返回：

/branch try-oauth-instead

注意：/fork 與 /subtask 在 v2.1.212 中調換了角色。在 v2.1.161 之前，/fork 是 /branch 的別名；從 v2.1.161 到 v2.1.211，它開始啟動派生子代理 — 即現在由 /subtask 承載的行為。當代理人檢視關閉時，/subtask 不可用，而 /fork 保留派生子代理的行為。

或從 CLI 進行分叉：

bash

claude --resume auth-refactor --fork-session "try OAuth instead"

工作階段持久性 (Session Persistence)

工作階段會自動儲存且可以恢復：

bash

# Continue last conversation
claude -c

# Resume specific session by name or ID
claude -r "auth-refactor"

# Resume and fork for experimentation
claude --resume auth-refactor --fork-session "alternative approach"

使用額度限制自動繼續 (v2.1.234)

自 v2.1.234 起，因 claude.ai 使用額度限制而阻塞的工作階段會在該限制重置後自動繼續 — 無需手動重新提示。可在 /config 中的 "Continue automatically at usage limit" 切換此功能。

工作階段摘要 (Session Recap, v2.1.108)

當您離開一段時間後返回工作階段，Claude 可以顯示已完成內容的簡短摘要。對於已停用遙測 (Telemetry) 的使用者（Bedrock、Vertex、Foundry 使用者），此功能預設啟用。

OTEL 遙測 — 重新啟用意見回饋調查 (v2.1.136+)：擷取 OpenTelemetry 資料的組織可透過設定 CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL=1 來重新啟用 Anthropic 的工作階段品質調查。調查在 OTEL 部署中預設關閉，因為先前它會從遙測管道中重定向出去。

OTEL 遙測 — assistant_response 日誌事件 (v2.1.193+)：Claude Code 會發出包含模型回應文字的 claude_code.assistant_response OpenTelemetry 日誌事件，讓 OTEL 管道在現有工具/事件遙測旁邊擷取 Claude 所說的內容。

控制摘要行為：

bash

/recap                                 # manually trigger a recap
/config                                # toggle auto-recap on/off

或透過環境變數：

bash

CLAUDE_CODE_ENABLE_AWAY_SUMMARY=0 claude   # disable recap
CLAUDE_CODE_ENABLE_AWAY_SUMMARY=1 claude   # force enable recap

跨工作階段訊息傳遞 (Cross-Session Messaging)

v2.1.224 加入，擴充至 v2.1.239。適用於 macOS、Linux 與（自 v2.1.239 起）Windows。

工作階段過去是孤島。跨工作階段訊息傳遞允許一個 Claude Code 工作階段與另一個工作階段交談 — 包含您其他機器上的工作階段與雲端工作階段 — 因此您可以將問題交給已經載入正確脈絡的工作階段，而無需重新解釋。

探索工作階段 (Discovering Sessions)

ListAgents 會列出您可以發送訊息的所有目標：您衍生的子代理、本機上的其他本地工作階段、您的雲端工作階段，以及（當連線 Remote Control 時）您其他機器上的工作階段。每一行都會標註類型，且自 v2.1.229 起，行中還帶有 offline 與 cloud 標籤，方便分辨可到達的工作階段與休眠的工作階段。

每行中的名稱就是地址 — 那就是您發送訊息的目標。

發送訊息 (Sending a Message)

SendMessage 接受目標與訊息：

text

SendMessage({ to: "<session name>", message: "What did you conclude about the retry logic?" })

自 v2.1.232 起，單純的名稱就足夠了 — 您不再需要附加用來消除歧義的引用標籤，除非兩行確實共享相同的名稱。

等待工作階段進入空閒 (`notify_when_idle`, v2.1.236)

當您傳送訊息的工作階段正處於任務中途時，您通常希望在它完成時收到通知，而不是主動輪詢。SendMessage 接受 notify_when_idle 輸入正是為了這一點：

text

SendMessage({
  to: "auth-refactor",
  message: "ping me when the migration finishes",
  notify_when_idle: true
})

這是單次觸發 (One-shot) 且需選擇性開啟 (Opt-in) 的 — 目標工作階段會在下次進入空閒時發送單一通知，之後訂閱即結束。沒有輪詢迴圈，若工作階段再次忙碌與空閒，也不會發送重複通知。

兩個相關的 v2.1.239 變更：ListAgents 現在還會報告工作階段自己的名稱（以便工作階段告訴其他目標如何尋址），以及跨工作階段訊息傳遞可在 Windows 上使用。

`@`-Mention 簡寫 (v2.1.232)

無需明確調用工具，您可以直接在提示詞中 @-mention 工作階段來聯絡它：

text

@auth-refactor did the migration tests pass?

控制接收內容：`crossSessionInbound`

傳入的訊息由 crossSessionInbound 設定管理 (v2.1.224+)：

數值	行為
`"accept"`	傳入的訊息會交付給此工作階段中的 Claude
`"hold"`	您會看到訊息到達的通知；但不會交付給 Claude
`"refuse"`	傳入的訊息會被丟棄

這些數值形成階梯 — accept < hold < refuse — 且專案與本地設定僅在比使用者範圍數值更嚴格時才生效。專案可以收緊傳入交付，但不能放寬。自 v2.1.232 起，該設定在 /config 中也有一行：「Messages from your other sessions」。

範圍與限制 (Reach and Limits)

同一台機器上的本地工作階段，外加您的雲端工作階段。
您其他機器上的 Remote Control 工作階段，可依名稱尋址 (v2.1.225)。
雲端工作階段可接收您的訊息，但目前無法傳回訊息給本地工作階段 — 請在其自身的逐字稿中閱讀其回答。
macOS 與 Linux 自 v2.1.224 起支援；Windows 自 v2.1.239 起支援。

互動功能 (Interactive Features)

快捷鍵 (Keyboard Shortcuts)

Claude Code 支援多種快捷鍵以提高效率。以下是官方文件的完整參考：

快捷鍵	說明
`Ctrl+C`	取消當前輸入/生成
`Ctrl+D`	退出 Claude Code
`Ctrl+G`	在外部編輯器中編輯計畫
`Ctrl+L`	重新繪製畫面（僅重新繪製 — 雙擊 `/clear` 的快捷鍵已在 v2.1.238 中移除）
`Ctrl+O`	切換詳細輸出（檢視推理過程）
`Ctrl+R`	反向搜尋歷史紀錄。預設為所有專案中的所有提示詞 (v2.1.129+)；在選擇器中按 `Ctrl+S` 可縮小範圍至當前專案。早期版本預設僅限當前專案。
`Ctrl+T`	切換任務列表檢視
`Ctrl+B`	將執行中的任務轉入背景
`Esc+Esc`	倒回 (Rewind) 程式碼/對話
`Shift+Tab` / `Alt+M`	切換權限模式
`Option+P` / `Alt+P`	切換模型
`Option+T` / `Alt+T`	切換延伸思考
`Option+O` / `Alt+O`	切換快速模式 (`/fast`)
`Ctrl+X` `Ctrl+K`	停止所有背景子代理
`Ctrl+S`	暫存 (Stash) 當前提示詞；再次按可還原
`Ctrl+_`	復原 (Undo) 對提示詞輸入的上次編輯
`:`	在單字開頭輸入 `:` 可開啟 Emoji 短碼補全，例如 `:heart:` (v2.1.217+)

行編輯 (標準 readline 快捷鍵)：

快捷鍵	動作
`Ctrl + A`	移動至行首
`Ctrl + E`	移動至行尾
`Ctrl + K`	剪切至行尾
`Ctrl + U`	剪切至行首
`Ctrl + W`	向後刪除單字
`Ctrl + Y`	貼上 (Yank)
`Tab`	自動補全 (Autocomplete)
`↑ / ↓`	命令歷史紀錄

輔助功能 (Accessibility)

螢幕閱讀器模式 (Screen Reader Mode, v2.1.208+) 將 CLI 切換為專為螢幕閱讀器設計的純文字轉譯模式。可透過 CLI 旗標、環境變數或設定鍵啟用：

bash

claude --ax-screen-reader

bash

export CLAUDE_AX_SCREEN_READER=1

json

{
  "axScreenReader": true
}

自訂按鍵綁定 (Customizing Keybindings)

透過執行 /keybindings 開啟 ~/.claude/keybindings.json 進行自訂按鍵綁定編輯 (v2.1.18+)。

組態格式：

json

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+u": null,
        "ctrl+k ctrl+s": "chat:stash"
      }
    },
    {
      "context": "Confirmation",
      "bindings": {
        "ctrl+a": "confirmation:yes"
      }
    }
  ]
}

將綁定設定為 null 可取消預設快捷鍵。

可用的內容情境 (Available Contexts)

按鍵綁定會限定在特定的 UI 情境中：

情境	主要動作
Chat	`submit`, `cancel`, `cycleMode`, `modelPicker`, `thinkingToggle`, `undo`, `externalEditor`, `stash`, `imagePaste`
Confirmation	`yes`, `no`, `previous`, `next`, `nextField`, `cycleMode`, `toggleExplanation`
Global	`interrupt`, `exit`, `toggleTodos`, `toggleTranscript`
Autocomplete	`accept`, `dismiss`, `next`, `previous`
HistorySearch	`search`, `previous`, `next`
Settings	情境特定的設定導覽
Tabs	分頁切換與管理
Help	說明面板導覽

共有 18 個情境，包含 Transcript、Task、ThemePicker、Attachments、Footer、MessageSelector、DiffDialog、ModelPicker 與 Select。

和弦按鍵支援 (Chord Support)

按鍵綁定支援和弦序列 (Chord Sequences，多按鍵組合)：

"ctrl+k ctrl+s"   → Two-key sequence: press ctrl+k, then ctrl+s
"ctrl+shift+p"    → Simultaneous modifier keys

按鍵語法：

修飾鍵：ctrl、alt（或 opt）、shift、meta（或 cmd）
大寫代表 Shift：K 等同於 shift+k
特殊按鍵：escape、enter、return、tab、space、backspace、delete、方向鍵

保留鍵與衝突按鍵 (Reserved and Conflicting Keys)

按鍵	狀態	附註
`Ctrl+C`	保留	無法重新綁定 (中断 Interrupt)
`Ctrl+D`	保留	無法重新綁定 (退出 Exit)
`Ctrl+B`	終端機衝突	tmux 前綴鍵
`Ctrl+A`	終端機衝突	GNU Screen 前綴鍵
`Ctrl+Z`	終端機衝突	程序暫停 (Process suspend)

提示：若快捷鍵不起作用，請檢查是否與您的終端機模擬器或多工器 (Multiplexer) 衝突。

Tab 補全 (Tab Completion)

Claude Code 提供智慧 Tab 補全：

User: /rew<TAB>
→ /rewind

User: /plu<TAB>
→ /plugin

User: /plugin <TAB>
→ /plugin install
→ /plugin enable
→ /plugin disable

命令歷史紀錄 (Command History)

存取先前輸入的命令：

User: <↑>  # Previous command
User: <↓>  # Next command
User: Ctrl+R  # Search history

(reverse-i-search)`test': run all tests

多行輸入 (Multi-line Input)

對於複雜的查詢，可使用多行模式：

bash

User: \
> Long complex prompt
> spanning multiple lines
> \end

範例：

User: \
> Implement a user authentication system
> with the following requirements:
> - JWT tokens
> - Email verification
> - Password reset
> - 2FA support
> \end

Claude: [Processes the multi-line request]

行內編輯 (Inline Editing)

在發送前編輯指令：

User: Deploy to prodcution<Backspace><Backspace>uction

[Edit in-place before sending]

Vim 模式 (Vim Mode)

啟用 Vi/Vim 按鍵綁定以進行文字編輯：

啟用方式：

透過 /config 啟用（切換 "Editor / Vim mode"）或在 ~/.claude/settings.json 中設定 editorMode: "vim"。獨立的 /vim 斜線指令已被移除（參閱 issue #43370）；Vim 模式現在由組態驅動。
使用 Esc 切換至 NORMAL 模式，i/a/o 切換至 INSERT 模式，v 切換至 VISUAL 模式，V 切換至 VISUAL-LINE 模式 (v2.1.118+)

導覽按鍵：

h / l - 向左/向右移動
j / k - 向下/向上移動
w / b / e - 依單字移動
0 / $ - 移動至行首/行尾
gg / G - 跳躍至文字開頭/結尾

文字物件 (Text objects)：

iw / aw - 內部/包含單字
i" / a" - 內部/包含引號字串
i( / a( - 內部/包含括號

Visual 模式 (v2.1.118+)：

按鍵	模式	行為
`v`	Visual	字元層級選擇並帶有視覺反白；可搭配移動鍵擴展
`V`	Visual-line	行層級選擇；總是選擇整行
`y`	Yank	複製當前 Visual 選擇內容
`d` / `x`	Delete	刪除當前 Visual 選擇內容
`c`	Change	刪除選擇內容並進入 INSERT 模式
`Esc`	Exit	返回 NORMAL 模式

Visual 選擇內容會在輸入欄位中高亮顯示，讓您在執行操作前精確確認將被複製、刪除或變更的內容。

Bash 模式 (Bash Mode)

使用 ! 前綴直接執行 Shell 指令：

bash

! npm test
! git status
! cat src/index.js

適合用於快速指令執行，無需切換情境。

自 v2.1.193 起： Bash 模式 (!) 具備即時檔案路徑自動補全，在輸入 Shell 指令時路徑會自動補全，無需離開提示詞。

自 v2.1.186 起： ! 指令的輸出會自動發送給 Claude，由 Claude 對其做出回應。若要保持先前的行為（僅將輸出加入脈絡而不發出回應），請在 settings.json 中設定 "respondToBashCommands": false。

輸出樣式 (Output Styles)

輸出樣式會改變 Claude 如何回應，而非它知道什麼。它們會修改系統提示詞 (System Prompt) 以設定角色、語氣與預設回應格式。當您每個 Turn 都重複提示相同的語氣，或希望 Claude 扮演軟體工程師以外的角色時，可以使用輸出樣式。

關於專案或程式碼庫的具體指令，請改用 CLAUDE.md — 那是具備不同權衡取捨的另一種機制。

內建樣式 (Built-in Styles)

樣式	行為
Default	標準系統提示詞，針對高效完成軟體工程任務進行調校
Proactive	Claude 立即執行並做出合理的假設，而非在例行決策時暫停。擁有比自動模式更強的自主執行引導，但它不會改變您的權限模式 — 您仍會看到權限提示
Explanatory	在步驟之間加入教育性的「Insights」，解釋實作選擇與程式碼庫模式
Learning	邊做邊學的協作模式。Claude 分享洞見並留下 `TODO(human)` 標記，供您自己實作小型的策略性部分
Concise (v2.1.237)	Claude 直接給出結果並跳過前言與敘述。周全性保持不變 — 僅丟棄開場白與周邊文字。在 `/config` → Output style 中選擇，或設定 `"outputStyle": "Concise"`

選擇樣式 (Selecting a Style)

執行 /config 並選擇 Output style。選擇結果會儲存至 .claude/settings.local.json。若要在沒有選單的情況下設定，可直接編輯設定值：

json

{
  "outputStyle": "Explanatory"
}

注意：獨立的 /output-style 指令在 v2.1.73 中已被廢棄，並在 v2.1.91 中移除。請使用 /config 或 outputStyle 設定。

輸出樣式是系統提示詞的一部分，Claude Code 會在工作階段開始時讀取一次 — 變更會在 /clear 後或在新工作階段中生效。

自訂輸出樣式 (Custom Output Styles)

自訂樣式是帶有 Frontmatter 前置資料的 Markdown 檔案，可儲存在三個層級之一：

使用者層級：~/.claude/output-styles/
專案層級：.claude/output-styles/
託管策略層級：託管設定目錄內部的 .claude/output-styles/

專案樣式會從工作目錄至 Repo 根目錄之間的每一個 .claude/output-styles/ 中載入。自 v2.1.178 起，當巢狀目錄定義了相同的樣式名稱時，最接近工作目錄的樣式獲勝。

markdown

---
name: Diagrams first
description: Lead every explanation with a diagram
keep-coding-instructions: true
---

When explaining code, architecture, or data flow, start with a Mermaid diagram
showing the structure, then explain in prose.

Frontmatter	目的	預設值
`name`	樣式名稱（若與檔名不同）	繼承自檔名
`description`	顯示在 `/config` 選擇器中	無
`keep-coding-instructions`	保留 Claude Code 內建的軟體工程指令	`false`
`force-for-plugin`	僅限外掛程式樣式：只要外掛程式啟用就自動套用，覆蓋使用者的 `outputStyle`	`false`

當您改變 Claude 的溝通方式但仍希望它以相同的格式編寫程式碼時，請設定 keep-coding-instructions: true。當 Claude 完全不做軟體工程時（例如寫作助手或資料分析師），則可省略。

範圍與成本 (Scope and Cost)

輸出樣式僅套用於主對話。子代理執行其自己的系統提示詞，因此樣式不會改變子代理的回應方式；Fork 是個例外，因為它繼承了父級的完整系統提示詞。

新增指令會增加 Input Tokens，但提示詞快取 (Prompt Caching) 在第一次請求後會吸收大部分開銷。Explanatory 與 Learning 模式在設計上會產生較長的回應，這會增加 Output Tokens。

比較參考 (How it Compares)

功能	運作方式	使用時機
輸出樣式	修改系統提示詞	您希望每個 Turn 擁有不同的角色、語氣或格式
CLAUDE.md	在系統提示詞後新增使用者訊息	Claude 應始終了解您的專案慣例
`--append-system-prompt`	附加至系統提示詞而不移除任何內容	單次執行的臨時補充
子代理 (Subagents)	以其自身的系統提示詞、模型與工具執行	您希望擁有獨立限定範圍的助手
技能 (Skills)	被調用時載入任務特定指令	您擁有可重複使用的工作流

狀態列 (Status Line)

狀態列是一個自訂指令，其輸出會呈現於工作階段底部。使用 /statusline 設定，或直接進行設定：

json

{
  "statusLine": {
    "type": "command",
    "command": "~/.claude/statusline.sh",
    "padding": 0
  }
}

padding 預設為 0。Claude Code 會透過 stdin 將 JSON 物件管道傳輸給該指令，因此由腳本決定要顯示什麼內容。

可用的輸入欄位 (Available Input Fields)

分組	欄位
Session	`session_id`, `session_name`, `prompt_id`, `transcript_path`, `cwd`, `version`
Model	`model.id`, `output_style.name`, `effort.level`, `fast_mode`, `thinking.enabled`
Agent	`agent.name`, `vim.mode`
Cost	`cost.total_cost_usd`, `cost.total_duration_ms`, `cost.total_api_duration_ms`, `cost.total_lines_added`
Context	`context_window.context_window_size`, `.current_usage`, `.remaining_percentage`, `.total_input_tokens`, `.used_percentage`
Limits	`rate_limits.five_hour.used_percentage`, `.resets_at`
Repo	`pr.number`, `pr.review_state`, `workspace.project_dir`, `workspace.added_dirs`, `workspace.git_worktree`, `workspace.repo.host`
Worktree	`worktree.name`, `.branch`, `.path`, `.original_branch`, `.original_cwd`

範例 (Example)

bash

#!/bin/bash
# ~/.claude/statusline.sh — model, context usage, and cost
input=$(cat)
model=$(echo "$input" | jq -r '.model.id')
used=$(echo "$input" | jq -r '.context_window.used_percentage')
cost=$(echo "$input" | jq -r '.cost.total_cost_usd')
printf '%s | ctx %.0f%% | $%.2f' "$model" "$used" "$cost"

注意：statusLine 需要工作區信任 (Workspace Trust)。狀態列腳本在其環境中還會收到 COLUMNS 與 LINES (v2.1.153+)，以便能根據終端機調整輸出大小。

TUI 模式 (全螢幕) (TUI Mode)

v2.1.110 新增

TUI (Text User Interface) 模式以無閃爍的全螢幕渲染 Claude Code — 非常適合 tmux 等終端機多工器或 iTerm2 的分頁視窗。

啟用 TUI 模式 (Enabling TUI Mode)

使用 /tui 指令切換 TUI 模式，或使用 --tui 旗標啟動：

bash

/tui          # toggle from within a session
claude --tui  # start directly in TUI mode

組態設定 (Configuration)

設定	說明	預設值
`autoScrollEnabled`	自動捲動至最新訊息	`true`

透過 /config 或 settings.json 停用自動捲動：

json

{
  "autoScrollEnabled": false
}

聚焦檢視 (Focus View)

/focus 指令可切換聚焦檢視 — 一個無干擾的顯示介面，僅顯示最相關的輸出。Ctrl+O 現在僅在普通與詳細逐字稿之間切換（聚焦檢視為 /focus）。

語音聽寫 (Voice Dictation)

語音聽寫 (Voice Dictation) 為 Claude Code 提供按住說話 (Push-to-talk) 語音輸入，允許您直接口述提示詞而非打字。

啟用語音聽寫 (Activating Voice Dictation)

/voice

功能特色 (Features)

功能	說明
按住說話 (Push-to-talk)	按住按鍵錄音，放開時發送
20 種語言	語音轉文字 (STT) 支援 20 種語言
自訂按鍵綁定	透過 `/keybindings` 設定按住說話按鍵
帳戶需求	需要 Claude.ai 帳戶進行 STT 處理

組態設定 (Configuration)

在您的按鍵綁定檔案 (/keybindings) 中自訂按住說話按鍵綁定。語音聽寫使用您的 Claude.ai 帳戶進行語音轉文字處理。

頻道 (Channels)

頻道 (Channels) 是一項 Research Preview 功能，可透過 MCP 伺服器將來自外部服務的事件推送至運作中的 Claude Code 工作階段。來源包含 Telegram、Discord、iMessage 與任意 Webhook，允許 Claude 無需輪詢即可對即時通知做出反應。

驗證 (v2.1.128+)：--channels 現在可同時搭配 Pro/Max OAuth 與 API Key（Console）驗證使用。早期版本需要 OAuth。

訂閱頻道 (Subscribing to Channels)

bash

# Subscribe to channel plugins at startup
claude --channels discord,telegram

# Subscribe to multiple sources
claude --channels discord,telegram,imessage,webhooks

支援的整合 (Supported Integrations)

整合	說明
Discord	在工作階段中接收並回應 Discord 訊息
Telegram	在工作階段中接收並回應 Telegram 訊息
iMessage	在工作階段中接收 iMessage 通知
Webhooks	接收來自任意 Webhook 來源的事件

組態設定 (Configuration)

在啟動時使用 --channels 旗標組態頻道。對於企業部署，請使用託管設定來控制允許哪些頻道外掛程式：

json

{
  "allowedChannelPlugins": ["discord", "telegram"]
}

allowedChannelPlugins 託管設定控制全組織允許使用哪些頻道外掛程式。

運作原理 (How It Works)

MCP 伺服器作為頻道外掛程式連線至外部服務
傳入的訊息與事件被推送至作用中的 Claude Code 工作階段
Claude 可在工作階段脈絡中讀取與回應訊息
頻道外掛程式必須透過 allowedChannelPlugins 託管設定進行批准
無需輪詢 — 事件即時推送

Chrome 整合 (Chrome Integration)

Chrome 整合將 Claude Code 連接至您的 Chrome 或 Microsoft Edge 瀏覽器，進行即時網頁自動化與排錯。這是自 v2.0.73+ 起可用的 Beta 功能（Edge 支援新增於 v1.0.36+）。

啟用 Chrome 整合 (Enabling Chrome Integration)

在啟動時：

bash

claude --chrome      # Enable Chrome connection
claude --no-chrome   # Disable Chrome connection

在工作階段內：

/chrome

選擇 "Enabled by default" 為所有未來的工作階段啟用 Chrome 整合。Claude Code 會共享您瀏覽器的登入狀態，因此它可以與已驗證的 Web 應用程式進行互動。

功能能力 (Capabilities)

能力	說明
即時排錯 (Live Debugging)	讀取 Console 日誌、檢查 DOM 元素、即時排錯 JavaScript
設計驗證	將渲染後的頁面與設計 Mockup 進行比較
表單驗證	測試表單提交、輸入驗證與錯誤處理
Web 應用測試	與已驗證的應用程式 (Gmail, Google Docs, Notion 等) 互動
資料提取	從網頁抓取與處理內容
工作階段錄製	將瀏覽器互動錄製為 GIF 檔案

網站層級權限 (Site-level Permissions)

Chrome 擴充功能管理個別網站的存取權限。隨時透過擴充功能快顯視窗為特定網站授予或撤銷存取權限。Claude Code 僅會與您明確允許的網站進行互動。

運作原理 (How it Works)

Claude Code 在可見的視窗中控制瀏覽器 — 您可以即時觀看動作的發生。當瀏覽器遇到登入頁面或驗證碼 (CAPTCHA) 時，Claude 會暫停並等待您手動處理後再繼續。

已知限制 (Known Limitations)

瀏覽器支援：僅限 Chrome 與 Edge — 不支援 Brave、Arc 及其他 Chromium 瀏覽器
WSL：在 Windows Subsystem for Linux 中不可用
第三方提供者：在使用 Bedrock、Vertex 或 Foundry API 提供者時不受支援
Service Worker 空閒：Chrome 擴充功能的 Service Worker 可能會在長時間工作階段期間進入空閒狀態

提示：Chrome 整合是一項 Beta 功能。瀏覽器支援可能會在未來的版本中擴展。

遠端控制 (Remote Control)

遠端控制允許您從手機、平板電腦或任何瀏覽器繼續執行在本地運作的 Claude Code 工作階段。您的本地工作階段會保持在您的機器上執行 — 不會有任何內容轉移至雲端。適用於 Pro、Max、Team 與 Enterprise 方案 (v2.1.51+)。

遠端控制不再是 Research Preview — 該標籤已於 2026 年第 34 週移除。任何執行 claude remote-control 的機器現在都會在 Claude 應用程式的 Code 分頁中顯示為裝置卡片 (Device Card)，因此您可以直接從手機啟動該機器上的工作階段，而無需先在機器上啟動然後連線至該工作階段。

啟動遠端控制 (Starting Remote Control)

從 CLI 啟動：

bash

# Start with default session name
claude remote-control

# Start with a custom name
claude remote-control --name "Auth Refactor"

從工作階段內啟動：

/remote-control
/remote-control "Auth Refactor"

可用的旗標：

旗標	說明
`--name "title"`	自訂工作階段標題以利識別
`--verbose`	顯示詳細的連線日誌
`--sandbox`	啟用檔案系統與網路隔離
`--no-sandbox`	停用沙盒化（預設值）

連線至工作階段 (Connecting to a Session)

從其他裝置連線的三種方式：

工作階段 URL — 工作階段啟動時印出至終端機；可在任何瀏覽器中開啟
QR Code — 啟動後按 Spacebar 顯示可掃描的 QR Code
依名稱尋找 — 在 claude.ai/code 或 Claude 行動應用程式 (iOS/Android) 中瀏覽您的工作階段

安全性 (Security)

無傳入埠 (Inbound Ports) 打開於您的機器上
僅限傳出 HTTPS 透過 TLS
限定範圍的憑證 (Scoped Credentials) — 多個短命、嚴格限定範圍的 Token
工作階段隔離 — 每個遠端工作階段均獨立

遠端控制 vs 網頁版 Claude Code

方面	遠端控制 (Remote Control)	網頁版 Claude Code (Web)
執行位置	於您的本地機器執行	於 Anthropic 雲端執行
本地工具	完整存取本地 MCP 伺服器、檔案與 CLI	無本地依賴
使用場景	從其他裝置繼續本地工作	從任何瀏覽器全新開始

限制 (Limitations)

每個 Claude Code 執行個體僅限一個遠端工作階段
主機機器上的終端機必須保持開啟
若網路無法到達，工作階段會在約 10 分鐘後逾時

使用場景 (Use Cases)

在離開座位時，從行動裝置或平板電腦控制 Claude Code
使用更豐富的 claude.ai UI，同時保持本地工具的執行
透過您完整的本地開發環境進行隨時隨地的快速程式碼審查

推送通知 (Push Notifications, v2.1.110)

當遠端控制啟用且 /config 中的 "Push when Claude decides" 啟用時，Claude 可以向您的手機發送行動推送通知 — 例如當長時間任務完成或需要您的輸入時。

要啟用：

啟用遠端控制：/remote-control 或 claude --rc
開啟 /config 並啟用 Push when Claude decides

推送通知需要 Claude 訂閱與 Claude 行動應用程式。

停用遠端控制 (`disableRemoteControl`, v2.1.128+)

Team 或 Enterprise 方案的管理員可以使用 disableRemoteControl 設定完全封鎖遠端控制。當設為 true 時，claude remote-control 與 /remote-control 都將拒絕啟動。

json

{
  "disableRemoteControl": true
}

該設定在 託管/策略 (managed/policy) 範圍內生效（例如 macOS 上的 /Library/Application Support/ClaudeCode/managed-settings.json），因此個別使用者無法覆蓋它。適用於必須在全組織強制執行僅限本地執行的情況。

當遠端控制因 API Key 層級自動停用時 (v2.1.139)：當設定了以下任何一項時，遠端控制會被靜默停用，即使您同時登入了 claude.ai：
ANTHROPIC_API_KEY
ANTHROPIC_AUTH_TOKEN
apiKeyHelper (settings.json)
相同的條件也會停用 /schedule、claude.ai MCP 連接器與通知偏好設定 — 所有四個與 claude.ai 橋接的介面均要求 OAuth 登入為作用中的憑證。取消設定 API Key（或在 Pro/Max OAuth 層級上執行）以使用這些功能。

網頁工作階段 (Web Sessions)

網頁工作階段允許您直接在瀏覽器 (claude.ai/code) 中執行 Claude Code，或從 CLI 建立網頁工作階段。

建立網頁工作階段 (Creating a Web Session)

bash

# Create a new web session from the CLI
claude --remote "implement the new API endpoints"

這會在 claude.ai 上啟動一個 Claude Code 工作階段，您可以從任何瀏覽器存取。

在本地恢復網頁工作階段 (Resuming Web Sessions Locally)

若您在網頁上啟動了工作階段並想在本地繼續：

bash

# Resume a web session in the local terminal — opens a picker of your web sessions
claude --teleport

或從互動式 REPL 內部：

text

/teleport

/tp 是 /teleport 的別名。兩者都需要 claude.ai 訂閱。雲端工作階段會顯示 /teleport 提示，說明如何在本地繼續 (v2.1.223)。

變更日誌來源：v2.1.223 變更日誌顯示了一種引數形式 claude --teleport <session id>，可直接跳轉至已知的工作階段。CLI 參考文件僅記錄了無引數的選擇器形式，因此除非您手頭已有工作階段 ID，否則建議優先使用 claude --teleport。

使用場景 (Use Cases)

在一台機器上開始工作並在另一台機器上繼續
與團隊成員共享工作階段 URL
使用網頁 UI 進行視覺化 Diff 審查，然後切換至終端機進行執行

桌面應用程式 (Desktop App)

Claude Code 桌面應用程式提供了一個獨立應用程式，具備視覺化 Diff 審查、平行工作階段與整合連接器。適用於 macOS 與 Windows（Pro、Max、Team 與 Enterprise 方案）。

安裝 (Installation)

從 claude.ai 下載適用於您平台的版本：

macOS：通用建置版 (Universal build，Apple Silicon 與 Intel)
Windows：提供 x64 與 ARM64 安裝程式

請參閱 Desktop Quickstart 以獲取設定說明。

從 CLI 轉接 (Handing off from CLI)

將您當前的 CLI 工作階段轉移至桌面應用程式：

/desktop

核心功能 (Core Features)

功能	說明
Diff 檢視	逐檔案的視覺化審查與行內註解；Claude 讀取註解並進行修訂
應用預覽 (App Preview)	自動啟動開發伺服器，並提供嵌入式瀏覽器進行即時驗證
PR 監測	GitHub CLI 整合，可自動修復 CI 失敗並在檢查通過時自動合併
平行工作階段	側邊欄中的多個工作階段，具備自動 Git 工作樹隔離
排程任務	當應用程式開啟時執行的重複任務（每小時、每天、工作日、每週）
豐富渲染	具備語法高亮的程式碼、Markdown 與圖表渲染；GitHub-Flavored-Markdown 任務列表核取方塊 (`- [ ]` / `- [x]`) 會渲染為核取方塊 (v2.1.149+)

應用預覽組態 (App Preview Configuration)

在 .claude/launch.json 中設定開發伺服器行為：

json

{
  "command": "npm run dev",
  "port": 3000,
  "readyPattern": "ready on",
  "persistCookies": true
}

連接器 (Connectors)

連接外部服務以獲得更豐富的脈絡：

連接器	能力
GitHub	PR 監測、Issue 追蹤、程式碼審查
Slack	通知、頻道脈絡
Linear	Issue 追蹤、Sprint 管理
Notion	文件、知識庫存取
Asana	任務管理、專案追蹤
Calendar	行程感知、會議脈絡

注意：遠端（雲端）工作階段無法使用連接器。

遠端與 SSH 工作階段 (Remote and SSH Sessions)

遠端工作階段 (Remote Sessions)：於 Anthropic 雲端基礎設施執行；即使應用程式關閉也會繼續運作。可從 claude.ai/code 或 Claude 行動應用程式存取
SSH 工作階段：透過 SSH 連線至遠端機器，擁有對遠端檔案系統與工具的完整存取權限。遠端機器上必須安裝 Claude Code

桌面版中的權限模式 (Permission Modes in Desktop)

桌面應用程式支援與 CLI 相同的權限模式：

模式	行為
Ask permissions (預設)	審查與批准每個編輯與指令
Auto accept edits	檔案編輯自動批准；指令需要手動批准
Plan mode	在做出任何變更前審查方法
Bypass permissions	自動執行（僅限沙盒，由管理員控制）

企業功能 (Enterprise Features)

管理主控台 (Admin Console)：控制全組織的 Code 分頁存取與權限設定
MDM 部署：在 macOS 上透過 MDM 或在 Windows 上透過 MSIX 進行部署
SSO 整合：要求組織成員使用單一簽入 (SSO)
託管設定：集中管理團隊組態與模型可用性

任務列表 (Task List)

任務列表 (Task List) 功能提供持久的任務追蹤，即使經過脈絡壓縮 (Context Compacting，當對話歷史紀錄被裁剪以符合脈絡視窗時) 也能存留。

切換任務列表 (Toggling the Task List)

在工作階段期間按 Ctrl+T 可開啟或關閉任務列表檢視。

持久任務 (Persistent Tasks)

任務能在脈絡壓縮後繼續存留，確保長時間運作的工作項目不會在對話脈絡被裁剪時遺失。對於複雜的多步驟實作特別有用。

具名的任務目錄 (Named Task Directories)

使用 CLAUDE_CODE_TASK_LIST_ID 環境變數建立跨工作階段共享的具名任務目錄：

bash

export CLAUDE_CODE_TASK_LIST_ID=my-project-sprint-3

這允許多個工作階段共享相同的任務列表，非常適合團隊工作流或跨工作階段專案。

提示詞建議 (Prompt Suggestions)

提示詞建議 (Prompt Suggestions) 會根據您的 Git 歷史紀錄與當前對話脈絡顯示深灰色的範例指令。

運作原理 (How It Works)

建議以深灰色文字顯示在您的輸入提示詞下方
按 Tab 接受建議
按 Enter 接受並立即提交
建議具備脈絡感知能力，取材自 Git 歷史紀錄與對話狀態

停用提示詞建議 (Disabling Prompt Suggestions)

bash

export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false

Git 工作樹 (Git Worktrees)

Git 工作樹允許您在隔離的工作樹中啟動 Claude Code，從而在不同分支上進行平行開發，而無需暫存 (Stash) 或切換分支。

在工作樹中啟動 (Starting in a Worktree)

bash

# Start Claude Code in an isolated worktree
claude --worktree
# or
claude -w

工作樹位置 (Worktree Location)

工作樹建立於：

<repo>/.claude/worktrees/<name>

Monorepo 的稀疏檢出 (Sparse Checkout for Monorepos)

使用 worktree.sparsePaths 設定在 Monorepo 中執行稀疏檢出 (Sparse-checkout)，從而減少磁碟使用量與複製時間：

json

{
  "worktree": {
    "sparsePaths": ["packages/my-package", "shared/"]
  }
}

基底分支引用 (`worktree.baseRef`)

worktree.baseRef（v2.1.133 新增）— 控制 claude --worktree 是從 origin/<default> 還是從本地 HEAD 分支。

"fresh"（預設值）— 從 origin/<default-branch> 分支，忽略本地未推送的 Commit。這恢復了 v2.1.128 中引入的行為，因此在 v2.1.128 之後依賴本地 HEAD 分支的使用者必須手動重新選擇開啟。
"head" — 從本地 HEAD 分支，保留未推送的 Commit。

在 ~/.claude/settings.json 中設定：

json

{ "worktree": { "baseRef": "head" } }

背景工作階段隔離 (`worktree.bgIsolation`)

worktree.bgIsolation（v2.1.143 新增）— 控制背景工作階段（例如來自 /bg、claude --bg 或代理人檢視）是取得其自己的工作樹，還是直接編輯前景工作副本。

（預設值） — 背景工作階段在 <repo>/.claude/worktrees/ 下建立隔離的工作樹，方式與 --worktree 相同。
"none" — 背景工作階段直接編輯當前的工作副本。當工作樹不切實際時（例如大型的原生建置產物）或當背景代理人必須與前景工作階段協調編輯時使用。

json

{ "worktree": { "bgIsolation": "none" } }

權衡："none" 移除了工作樹隔離的安全網 — 來自背景與前景工作階段的邊界並發編輯可能會在即時工作副本中產生合併衝突。

工作樹工具與掛鉤 (Worktree Tools and Hooks)

項目	說明
`EnterWorktree`	進入工作樹的工具；自 v2.1.157 起，可在工作階段中途切換 Claude 托管的工作樹
`ExitWorktree`	退出並清理當前工作樹的工具
`WorktreeCreate`	建立工作樹時發出的掛鉤事件
`WorktreeRemove`	移除工作樹時發出的掛鉤事件

自 v2.1.157 起，由 Claude 管理的工作樹會在代理人完成時保持解鎖狀態，以便 git worktree remove/prune 可以清理它們。

自動清理 (Auto-Cleanup)

若未在工作樹中進行任何變更，則在工作階段結束時會自動清理該工作樹。

使用場景 (Use Cases)

在保持 main 分支不受影響的情況下在 Feature 分支上工作
在隔離環境中執行測試，而不影響工作目錄
在拋棄式環境中嘗試實驗性變更
在 Monorepo 中稀疏檢出特定套件以實現更快啟動

沙盒化 (Sandboxing)

沙盒化為 Claude Code 執行的 Bash 指令提供作業系統層級的檔案系統與網路隔離。這是對權限規則的補充，並提供了額外的安全層。

啟用沙盒化 (Enabling Sandboxing)

斜線指令：

/sandbox

CLI 旗標：

bash

claude --sandbox       # Enable sandboxing
claude --no-sandbox    # Disable sandboxing

組態設定 (Configuration Settings)

設定	說明
`sandbox.enabled`	啟用或停用沙盒化
`sandbox.failIfUnavailable`	若沙盒化無法啟用則失敗
`sandbox.filesystem.allowWrite`	允許寫入存取的路徑
`sandbox.filesystem.allowRead`	允許讀取存取的路徑
`sandbox.filesystem.denyRead`	拒絕讀取存取的路徑
`sandbox.network.allowedDomains`	允許由 Bash 啟動的程序存取的網域（支援 `*.` 通配符）
`sandbox.network.deniedDomains`	即使 `allowedDomains` 通配符允許也依然封鎖的網域 (v2.1.113+)
`sandbox.network.strictAllowlist`	(v2.1.219) 針對沙盒指令無提示拒絕非允許清單的主機
`sandbox.enableWeakerNetworkIsolation`	在 macOS 上啟用較弱的網路隔離
`sandbox.bwrapPath`	(v2.1.133+, Linux/WSL) `bubblewrap` 二進位檔路徑。預設：`$PATH` 搜尋。
`sandbox.socatPath`	(v2.1.133+, Linux/WSL) `socat` 二進位檔路徑。預設：`$PATH` 搜尋。
`sandbox.credentials`	(v2.1.187+) 封鎖沙盒指令讀取憑證檔案與秘密環境變數。
`sandbox.allowAppleEvents`	(v2.1.181+, macOS) 選擇性允許沙盒指令發送 Apple Events。
`sandbox.filesystem.disabled`	(v2.1.216+) 完全跳過檔案系統隔離，同時保持網路隔離強制執行 — 當檔案沙盒化破壞工具但網路傳出控制必須保持作用時很有用。僅在使用者設定、託管設定或 `--settings` 中生效；專案設定無法設定它。

Linux/WSL 二進位檔路徑 (v2.1.133+) — 指向非標準安裝位置的 Claude Code：

json

{
  "sandbox": {
    "bwrapPath": "/opt/bubblewrap/bin/bwrap",
    "socatPath": "/opt/socat/bin/socat"
  }
}

deniedDomains 覆蓋廣泛通配符的範例 (v2.1.113+)：

json

{
  "sandbox": {
    "network": {
      "allowedDomains": ["*.example.com"],
      "deniedDomains": ["evil.example.com"]
    }
  }
}

通配符允許 example.com 上的所有內容通過，但 deniedDomains 仍會封鎖明確命名的主機。

附註 (v2.1.243)：沙盒 Bash 工具的權限提示不再列出允許的網路主機。Claude 只是嘗試請求，您在出現新的主機時分別批准它 — 因此不要期待提示會預先顯示允許清單。同一版本中，當封鎖的指令恰好以 0 退出時，也不再丟棄網路違規細節，因此看起來靜默成功的操作仍會回報被封鎖的內容。

憑證遮蔽 (Credential Masking, v2.1.221, v2.1.224)

變更日誌來源：這些 sandbox.credentials 選項取材自 v2.1.221 與 v2.1.224 變更日誌條目；設定參考文件尚未詳細說明。

在 v2.1.221 之前，sandbox.credentials 只能 deny 憑證檔案 — 需要該憑證的沙盒指令會直接失敗。mode: "mask" 讓指令保持運作而不洩漏秘密：沙盒程序讀取檔案的哨兵 (Sentinel) 副本，沙盒代理伺服器 (Proxy) 在出口前往網路途中將真實數值替換上去。

json

{
  "sandbox": {
    "network": { "tlsTerminate": true },
    "credentials": {
      "files": [
        { "path": "~/.aws/credentials", "mode": "mask" }
      ]
    }
  }
}

能力	起始版本	作用
憑證檔案的 `mode: "mask"`	v2.1.221	沙盒指令讀取哨兵；Proxy 在出口替換真實值。僅限 Linux 與 WSL — 在 macOS 上檔案遮蔽退回至 `deny`。
`extract` / `onExtractNoMatch`	v2.1.224	遮蔽結構化環境數值內部的單一欄位而非整個變數，並決定當模式不匹配時發生什麼事。
`decode: "jwt"` 與 `maskClaims`	v2.1.224	解碼 JWT 並僅遮蔽具名的 Claims，保持其餘內容可讀。
`awsPairs` / `sigv4`	v2.1.224	在 Proxy 替換真實 Access Key 後重新簽署 AWS SigV4 請求。

容易忽略的兩個限制：

所有遮蔽均需要 network.tlsTerminate — Proxy 必須能看到請求內部才能替換數值。
這些選項僅在使用者設定、託管設定或 --settings 中生效。專案設定無法開啟遮蔽或變更遮蔽的內容。

組態範例 (Example Configuration)

json

{
  "sandbox": {
    "enabled": true,
    "failIfUnavailable": true,
    "filesystem": {
      "allowWrite": ["/Users/me/project"],
      "allowRead": ["/Users/me/project", "/usr/local/lib"],
      "denyRead": ["/Users/me/.ssh", "/Users/me/.aws"]
    },
    "enableWeakerNetworkIsolation": true
  }
}

運作原理 (How It Works)

Bash 指令在受限檔案系統存取的沙盒環境中執行
網路存取可被隔離，以防止非預期的外部連線
與權限規則協同運作以實現縱深防禦 (Defense in depth)
在 macOS 上，使用 sandbox.enableWeakerNetworkIsolation 進行網路限制（macOS 上無法實現完全網路隔離）

使用場景 (Use Cases)

安全地執行不受信任的或生成的程式碼
防止意外修改專案外的檔案
在自動化任務期間限制網路存取

託管設定 (企業版) (Managed Settings)

託管設定允許企業管理員使用平台原生管理工具在全組織部署 Claude Code 組態。

部署方法 (Deployment Methods)

平台	方法	起始版本
macOS	託管 plist 檔案 (MDM)	v2.1.51+
Windows	Windows 機碼 (Registry)	v2.1.51+
跨平台	託管組態檔案	v2.1.51+
跨平台	託管 Drop-ins (`managed-settings.d/` 目錄)	v2.1.83+

託管 Drop-ins (Managed Drop-ins)

自 v2.1.83 起，管理員可以將多個託管設定檔部署至 managed-settings.d/ 目錄中。檔案依字母順序合併，允許跨團隊模組化組態：

~/.claude/managed-settings.d/
  00-org-defaults.json
  10-team-policies.json
  20-project-overrides.json

可用的託管設定 (Available Managed Settings)

設定	說明
`disableBypassPermissionsMode`	防止使用者啟用 bypassPermissions 模式
`availableModels`	限制使用者可以選擇的模型
`enforceAvailableModels`	(v2.1.175) 當設為 `true` 時，`availableModels` 允許清單也會限制預設 (Default) 模型 — 若組態的預設模型不在清單中，Claude Code 會退回至第一個允許的模型。使用者與專案設定無法再擴大託管的 `availableModels` 清單。
`allowedChannelPlugins`	控制允許使用哪些頻道外掛程式
`autoMode.environment`	為自動模式設定信任的基礎設施
`workflowSizeGuideline`	(v2.1.219) 設定建議性的動態工作流規模指南。可從任何設定檔讀取，不限於託管設定；當設定此項時，`/config` 中的 Dynamic workflow size 行會被隱藏
`wslInheritsWindowsSettings`	僅限 Windows/WSL (v2.1.118+)：當設為 `true` 時，在 WSL 內部執行的 Claude Code 會繼承來自 Windows 主機的託管設定，因此透過 Registry/MDM 部署的企業策略可在 Windows 與 WSL Shell 間保持一致
`parentSettingsBehavior`	(v2.1.133+, 管理員層級) 控制 SDK 的 `managedSettings` 如何與父程序設定合併。`"first-wins"` 保持現有的優先權（衝突時早期設定獲勝）；`"merge"` 進行深度合併 (Deep-merge)。
自訂策略 (Custom policies)	組織特定的權限與工具策略

範例：macOS Plist (Example: macOS Plist)

xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>disableBypassPermissionsMode</key>
  <true/>
  <key>availableModels</key>
  <array>
    <string>claude-sonnet-4-6</string>
    <string>claude-haiku-4-5</string>
  </array>
</dict>
</plist>

組態與設定 (Configuration and Settings)

組態檔案位置 (Configuration File Locations)

全域組態：~/.claude/config.json
專案組態：./.claude/config.json
使用者組態：~/.config/claude-code/settings.json

完整組態範例 (Complete Configuration Example)

核心進階功能組態：

json

{
  "permissions": {
    "defaultMode": "manual"
  },
  "hooks": {
    "PreToolUse:Edit": "eslint --fix ${file_path}",
    "PostToolUse:Write": "~/.claude/hooks/security-scan.sh"
  },
  "mcp": {
    "enabled": true,
    "servers": {
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"]
      }
    }
  }
}

擴展組態範例：

json

{
  "permissions": {
    "defaultMode": "manual",
    "allowedTools": ["Bash(git log:*)", "Read"],
    "disallowedTools": ["Bash(rm -rf:*)"]
  },

  "hooks": {
    "PreToolUse": [{ "matcher": "Edit", "hooks": ["eslint --fix ${file_path}"] }],
    "PostToolUse": [{ "matcher": "Write", "hooks": ["~/.claude/hooks/security-scan.sh"] }],
    "Stop": [{ "hooks": ["~/.claude/hooks/notify.sh"] }]
  },

  "mcp": {
    "enabled": true,
    "servers": {
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_TOKEN": "${GITHUB_TOKEN}"
        }
      }
    }
  }
}

個別使用者其他設定 (Additional Per-User Settings)

這些鍵值位於 ~/.claude/settings.json（或專案 .claude/settings.json）中，控制單個使用者的互動行為：

設定	說明
`askUserQuestionTimeout`	在空閒時間後自動繼續未回答的 `AskUserQuestion` 對話框。自 v2.1.200 起對話框預設不再自動繼續 — 設定此項以重新選擇開啟定時自動繼續。
`enableArtifact`	個別使用者啟用/停用 Artifact 工具 (v2.1.196)。
`crossSessionInbound`	(v2.1.224) 傳入的跨工作階段訊息如何處理 — `"accept"`、`"hold"` 或 `"refuse"`。專案與本地數值僅在沿 `accept < hold < refuse` 階梯更嚴格時生效。自 v2.1.232 起在 `/config` 中公開為 "Messages from your other sessions"。
`dialogExpiry`	(v2.1.224) 未回答的對話框保持開啟多久。預設 `"5m"`；接受 `"60s"`、`"5m"`、`"10m"` 或 `"never"`。會被 `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` 覆蓋。自 v2.1.232 起在 `/config` 中公開為 "Dialog expiry"。
`modelPicker`	(v2.1.243) 選擇 `/model` 選擇器列出的模型，並指定您自己的順序與標籤。這是少數跨設定層級覆蓋而非合併的設定之一 — 最接近範圍的數值直接勝出。
`promptCacheTtl`	(v2.1.243) 選擇主對話的提示詞快取生存時間 (TTL)。
`subagentPromptCacheTtl`	(v2.1.243) 子代理與主對話外其他請求的相同選擇。
`modelPricing`	(v2.1.243) 託管設定。提供您組織的合約費率，以便 `/cost`、狀態列與遙測報告該費率而非定價清單。
`keybindingFlavor`	自 v2.1.261 起已被廢棄且無效果。提示詞的單字編輯按鍵始終遵循 readline 慣例，如 Bash 一樣：`Ctrl+W` 向上刪除至空白，`Alt+F` 與 `Alt+D` 在單字結尾停止，標點符號分隔單字。Claude Code 仍接受該按鍵，因此設定它的設定檔依然有效。（在 v2.1.238–v2.1.260 中它在 `"classic"` 與 `"readline"` 之間選擇。）
`spellcheck`	(v2.1.235) 使用 `PATH` 上的 `aspell`、`hunspell` 或 `ispell`（按此順序嘗試）在提示詞輸入中標記拼錯的單字。物件型數值 — `{"enabled": true, "language": "en_GB"}` — 且預設關閉。僅從使用者設定、`--settings` 旗標與託管設定讀取：專案 `.claude/settings.json` 或 `.claude/settings.local.json` 中的 `spellcheck` 區塊會被忽略。
`bashOutputMaxChars`	(v2.1.261) Claude 在行內收到的成功 Bash 或 PowerShell 指令輸出的字元數，最多 128K。超過限制時 Claude Code 會將輸出儲存至檔案，Claude 取得簡短預覽外加路徑。設定此項會使 Claude Code 忽略 `BASH_MAX_OUTPUT_LENGTH`。
`taskOutputMaxChars`	(v2.1.261) Claude 使用 `TaskOutput` 工具讀取背景任務的輸出時在行內收到的字元數，最多 128K。對於較長的已完成任務，Claude 收到最近的字元。設定此項會使 Claude Code 忽略 `TASK_MAX_OUTPUT_LENGTH`。

備援模型 (`fallbackModel`)

fallbackModel 設定允許您組態最多三個備援模型，依序嘗試，當主要模型過載或不可用時使用。

json

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

自 v2.1.166 起，--fallback-model 旗標也適用於互動式工作階段（不限於 Headless）。發生備援時，Claude Code 會重試一次非預期的非重試錯誤；驗證、速率限制、請求大小與傳輸錯誤仍會立即失敗。

環境變數 (Environment Variables)

使用環境變數覆蓋組態：

bash

# Model selection
export ANTHROPIC_MODEL=claude-opus-4-8
export ANTHROPIC_DEFAULT_MODEL=claude-opus-4-8   # (v2.1.236) Model new sessions start on. Unlike ANTHROPIC_MODEL, a /model pick still overrides it — and that pick persists across restarts
export ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-8
export ANTHROPIC_DEFAULT_SONNET_MODEL=claude-sonnet-4-6
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5

# API configuration
export ANTHROPIC_API_KEY=sk-ant-...

# Thinking configuration
export MAX_THINKING_TOKENS=16000
export CLAUDE_CODE_EFFORT_LEVEL=high   # low, medium, high, xhigh (Opus 5/4.8/4.7), or max — default is high on Opus 5 and Opus 4.8 (supported on Opus 5, Opus 4.8, Opus 4.7, Opus 4.6, Sonnet 4.6)

# Feature toggles
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=true
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=true
export CLAUDE_CODE_DISABLE_CRON=1
export CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=true
export CLAUDE_CODE_DISABLE_TERMINAL_TITLE=true
export CLAUDE_CODE_DISABLE_1M_CONTEXT=true
export CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=true
export CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false
export CLAUDE_CODE_ENABLE_TASKS=true
export CLAUDE_CODE_SIMPLE=true              # Set by --bare flag

# MCP configuration
export MAX_MCP_OUTPUT_TOKENS=50000
export ENABLE_TOOL_SEARCH=true

# Prompt caching
export ENABLE_PROMPT_CACHING_1H=1      # Use 1-hour prompt cache TTL (default is 5 min)

# Task management
export CLAUDE_CODE_TASK_LIST_ID=my-project-tasks

# Agent teams (experimental)
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# Subagent and plugin configuration
export CLAUDE_CODE_SUBAGENT_MODEL=sonnet
export CLAUDE_CODE_PLUGIN_SEED_DIR=./my-plugins
export CLAUDE_CODE_NEW_INIT=1

# Subprocess and streaming
export CLAUDE_CODE_SUBPROCESS_ENV_SCRUB="SECRET_KEY,DB_PASSWORD"
export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80
export CLAUDE_STREAM_IDLE_TIMEOUT_MS=30000
export ANTHROPIC_CUSTOM_MODEL_OPTION=my-custom-model
export SLASH_COMMAND_TOOL_CHAR_BUDGET=50000

# Output and package manager (v2.1.129+)
export CLAUDE_CODE_FORCE_SYNC_OUTPUT=1                      # Force synchronous output for terminals where auto-detect misses (Emacs eat, etc.)
export CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1            # Enable background upgrades for Homebrew/WinGet installs
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1         # Opt in to /v1/models gateway discovery when ANTHROPIC_BASE_URL is set

# Windows PowerShell tool (v2.1.143+) — default-on for Bedrock/Vertex/Foundry on Windows
export CLAUDE_CODE_USE_POWERSHELL_TOOL=0                    # Disable the PowerShell tool entirely
export CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1    # Honor system ExecutionPolicy instead of `-ExecutionPolicy Bypass`

# Workload identity federation (v2.1.141+)
export ANTHROPIC_WORKSPACE_ID=ws_abc123                     # Scope the federated token to a specific workspace when the rule covers multiple

# Stop hook safety cap (v2.1.143+)
export CLAUDE_CODE_STOP_HOOK_BLOCK_CAP=8                    # Max consecutive Stop-hook blocks before the session ends with a warning. Set 0 to disable the cap.

# Session-wide spawn caps (v2.1.212)
export CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION=200         # Cap on WebSearch tool calls per session, to stop runaway search loops. Default 200.

# Accessibility (v2.1.208)
export CLAUDE_AX_SCREEN_READER=1                            # Enable plain-text screen reader rendering mode. Same effect as --ax-screen-reader or "axScreenReader": true in settings.

# Newer variables (v2.1.221–v2.1.234) — changelog-sourced; the CLI reference has no env-var section
export CLAUDE_CODE_ENABLE_TODO_TOOLS=1                      # (v2.1.233) Restore the todo/task-tracking tools (TaskCreate/Get/Update/List, TodoWrite), which are off on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, and newer models
export CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS=900000             # (v2.1.233) WebFetch URL cache TTL. Default 15 minutes.
export CLAUDE_CODE_TOOL_MEMORY_LIMIT=2G                     # (v2.1.233, Linux) Opt-in memory cgroup applied to Bash commands
export ANTHROPIC_BEDROCK_REGION_PREFIX=us                   # (v2.1.224) Prefer a specific Bedrock cross-region inference profile
export CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1  # (v2.1.223) Restore pre-v2.1.223 auto-compact behavior on unrecognized model IDs
export CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS=0             # (v2.1.229) Disable prefix staggering on dynamic-workflow fan-out
export CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS=300000            # (v2.1.224) Overrides the dialogExpiry setting
export CLAUDE_CODE_PROJECT_DIR_NAME=my-app                  # (v2.1.234) Short name for the per-project transcript directory, for hosts that give each session its own config directory
export CLAUDE_CODE_GOAL_CHECKIN_MINUTES=30                  # (v2.1.234) Minutes a background task may stall before Claude checks in while a /goal is active. Set 0 to disable check-ins.

v2.1.223 — CLAUDE_CODE_DISABLE_1M_CONTEXT 擴大範圍：該變數現在會將每一個具備原生 1M Token 視窗的 Claude 模型透過自動壓縮壓低至 200K，而不僅限於固定 ID 的模型清單。

v2.1.108：ENABLE_PROMPT_CACHING_1H=1 — 使用 1 小時的提示詞快取 TTL 而非預設的 5 分鐘 TTL。在長時間穩定的工作階段中減少快取未命中 (Cache misses)。（v2.1.129 修復了 1 小時 TTL 被靜默降級為 5 分鐘的迴歸問題。）

v2.1.129：CLAUDE_CODE_FORCE_SYNC_OUTPUT=1 強制對自動偵測能力失敗的終端機進行同步輸出（如 Emacs eat）。CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 啟用 Homebrew/WinGet 安裝的背景升級，否則它們永遠不會自動更新。

組態管理指令 (Configuration Management Commands)

User: /config
[Opens interactive configuration menu]

/config 指令提供互動式選單來切換以下設定：

Extended thinking 開/關
詳細輸出 (Verbose Output)
權限模式 (Permission Mode)
模型選擇 (Model Selection)
動態工作流規模 (Dynamic Workflow Size, v2.1.219) — 當設定檔中設定了 workflowSizeGuideline 時隱藏，參閱動態工作流

在互動式選單中，按 Enter 或 Space 變更選擇的設定，按 Esc 儲存並關閉 (v2.1.183+)。

您也可以直接從提示詞中設定設定值，無需開啟選單：

bash

/config thinking=false      # set a single setting inline (v2.1.181+)
/config --help              # list available shorthand keys (v2.1.183+)

key=value 簡寫適用於互動式工作階段、搭配 -p 以及 Remote Control。

專案專屬組態 (Per-Project Configuration)

在專案中建立 .claude/config.json：

json

{
  "hooks": {
    "PreToolUse": [{ "matcher": "Bash", "hooks": ["npm test && npm run lint"] }]
  },
  "permissions": {
    "defaultMode": "manual"
  },
  "mcp": {
    "servers": {
      "project-db": {
        "command": "mcp-postgres",
        "env": {
          "DATABASE_URL": "${PROJECT_DB_URL}"
        }
      }
    }
  }
}

信任與權限範圍 (Trust and Permission Scoping)

變更日誌來源 (v2.1.222, v2.1.232)：這些收緊措施取材自變更日誌；設定參考文件尚未詳細說明。

最近版本的一個重複主題：安全性相關設定無法再被您複製 (Clone) 的儲存庫放寬。需要了解的三項變更：

巢狀儲存庫需要自己的信任確認 (v2.1.232)。 位於信任父目錄內部的 Git 儲存庫不再繼承該信任。若您信任 ~/work/monorepo 且其包含 Vendor 的 Submodule，在 Claude Code 第一次在其內部工作時，您將被要求單獨信任該 Submodule。

sandbox.ripgrep 僅限使用者範圍 (v2.1.232)。 指定沙盒所用 ripgrep 二進位檔名稱的設定僅在使用者設定、託管設定或 --settings 中生效。專案設定無法再將沙盒指向不同的二進位檔。

Remote Control 自動啟動僅限使用者範圍 (v2.1.222)。 Repo 本地設定無法啟用 Remote Control 自動啟動；它只能透過 /config 在使用者範圍啟用。

要內化的模式：若某項設定會讓簽入 (Checked-in) 的檔案擴大 Claude Code 允許在您機器上執行的操作，請假設它現在僅限使用者範圍。

代理團隊 (Agent Teams)

代理團隊 (Agent Teams) 是一項實驗性功能，允許多個 Claude Code 執行個體在同一任務上進行協作。預設停用。

啟用代理團隊 (Enabling Agent Teams)

透過環境變數或設定檔啟用：

bash

# Environment variable
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

或新增至您的設定 JSON：

json

{
  "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}

代理團隊的運作方式 (How Agent Teams Work)

團隊領導者 (Team Lead) 協調整體任務並將子任務委派給隊友
隊友 (Teammates) 獨立工作，各自擁有獨立的脈絡視窗
共享任務列表 (Shared Task List) 實現團隊成員之間的自我協調
使用子代理定義（.claude/agents/ 或 --agents 旗標）定義隊友的角色與專業化

顯示模式 (Display Modes)

代理團隊支援兩種顯示模式，使用 --teammate-mode 旗標進行組態：

模式	說明
`in-process` (預設)	隊友在相同的終端機程序中執行
`tmux`	每個隊友獲得專用的分割視窗（需要 tmux 或 iTerm2）
`auto`	自動選擇最佳顯示模式

bash

# Use tmux split panes for teammate display
claude --teammate-mode tmux

# Explicitly use in-process mode
claude --teammate-mode in-process

使用場景 (Use Cases)

大型重構任務，不同隊友處理不同模組
平行程式碼審查與實作
跨程式碼庫的協調多檔案變更

注意：代理團隊為實驗性功能，可能會在未來版本中變更。請參閱 code.claude.com/docs/en/agent-teams 取得完整參考。

最佳實踐 (Best Practices)

計畫模式 (Planning Mode)

✅ 用於複雜的多步驟任務
✅ 在批准前審查計畫
✅ 在需要時修改計畫
❌ 不要用於簡單任務

延伸思考 (Extended Thinking)

✅ 用於架構決策
✅ 用於複雜問題解決
✅ 審查思考過程
❌ 不要用於簡單查詢

背景任務 (Background Tasks)

✅ 用於長時間運作的操作
✅ 監測任務進度
✅ 優雅地處理任務失敗
❌ 不要啟動過多的邊界並發任務

權限 (Permissions)

✅ 程式碼審查使用 plan（唯讀）
✅ 互動式開發使用 default
✅ 自動化工作流使用 acceptEdits
✅ 帶有安全護欄的自主工作使用 auto
❌ 除非絕對必要，否則不要使用 bypassPermissions

工作階段 (Sessions)

✅ 為不同的任務使用獨立的工作階段
✅ 儲存重要的工作階段狀態
✅ 清理舊的工作階段
❌ 不要在一工作階段中混用不相關的工作

其他資源 (Additional Resources)

獲取更多關於 Claude Code 及相關功能的資訊：

官方互動模式文件 (Official Interactive Mode Documentation)
官方無頭模式文件 (Official Headless Mode Documentation)
CLI 參考文件 (CLI Reference)
檢查點指南 (Checkpoints Guide) - 工作階段管理與倒回
斜線指令指南 (Slash Commands Guide) - 指令參考
記憶體指南 (Memory Guide) - 持久脈絡
技能指南 (Skills Guide) - 自主能力
子代理指南 (Subagents Guide) - 委派任務執行
MCP 指南 (MCP Guide) - 外部資料存取
掛鉤指南 (Hooks Guide) - 事件驅動自動化
外掛程式指南 (Plugins Guide) - 打包擴充功能
官方排程任務文件 (Official Scheduled Tasks Documentation)
官方 Chrome 整合文件 (Official Chrome Integration Documentation)
官方遠端控制文件 (Official Remote Control Documentation)
官方按鍵綁定文件 (Official Keybindings Documentation)
官方桌面應用程式文件 (Official Desktop App Documentation)
官方代理團隊文件 (Official Agent Teams Documentation)

最後更新：2026 年 9 月 6 日 Claude Code 版本：2.1.263 資料來源：

https://code.claude.com/docs/en/settings
https://code.claude.com/docs/en/sandboxing
https://code.claude.com/docs/en/commands
https://code.claude.com/docs/en/cli-reference
https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
https://code.claude.com/docs/en/model-config
https://code.claude.com/docs/en/permission-modes
https://code.claude.com/docs/en/settings.md
https://code.claude.com/docs/en/settings-reference
https://code.claude.com/docs/en/whats-new/2026-w34相容模型：Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5

進階功能 (Advanced Features) ​

目錄 (Table of Contents) ​

概述 (Overview) ​

計畫模式 (Planning Mode) ​

什麼是計畫模式？ (What is Planning Mode?) ​

何時使用計畫模式 (When to Use Planning Mode) ​

啟用計畫模式 (Activating Planning Mode) ​

計畫模式的優勢 (Benefits of Planning Mode) ​

範例：功能實作 (Example: Feature Implementation) ​

計畫修改 (Plan Modifications) ​

計畫模式組態設定 (Planning Mode Configuration) ​

延伸思考 (Extended Thinking) ​

什麼是延伸思考？ (What is Extended Thinking?) ​

啟用延伸思考 (Activating Extended Thinking) ​

Opus 5 上的安全分類器備援 (Safety-Classifier Fallback on Opus 5) ​

延伸思考的優勢 (Benefits of Extended Thinking) ​

範例：架構決策 (Example: Architectural Decision) ​

延伸思考組態設定 (Extended Thinking Configuration) ​

自動模式 (Auto Mode) ​

需求條件 (Requirements) ​

啟用自動模式 (Enabling Auto Mode) ​

分類器的運作方式 (How the Classifier Works) ​

預設封鎖的動作 (Default Blocked Actions) ​

預設允許的動作 (Default Allowed Actions) ​

組態自動模式 (Configuring Auto Mode) ​

使用 "$defaults" 擴充預設值 (v2.1.118) ​

使用 autoMode.hard_deny 進行無條件封鎖 (v2.1.136) ​

使用 autoMode.classifyAllShell 分類所有 Shell 指令 (v2.1.193) ​

內建意圖保護 (Built-in intent-based protection, v2.1.183) ​

設定等同自動模式的權限 (無需 Team 方案) ​

背景任務 (Background Tasks) ​

什麼是背景任務？ (What Are Background Tasks?) ​

啟動背景任務 (Starting Background Tasks) ​

管理背景任務 (Managing Background Tasks) ​

範例：平行開發 (Example: Parallel Development) ​

組態設定 (Configuration) ​

監測工具 (Monitor Tool，事件驅動流) ​

為什麼這很重要 (Why It Matters) ​

兩種常見模式 (Two Common Patterns) ​

具體範例 (Concrete Example) ​

動態工作流 (Dynamic Workflows) ​

何時使用 (When to Use Them) ​

啟動與檢視 (Launching and Viewing) ​

排程任務 (Scheduled Tasks) ​

/loop 指令 ​

一次性提醒 (One-time Reminders) ​

管理排程任務 (Managing Scheduled Tasks) ​

行為細節 (Behavior Details) ​

雲端排程任務 (Cloud Scheduled Tasks) ​

停用排程任務 (Disabling Scheduled Tasks) ​

範例：監測部署 (Example: Monitoring a Deployment) ​

權限模式 (Permission Modes) ​

可用的權限模式 (Available Permission Modes) ​

啟用方式 (Activation Methods) ​

權限模式範例 (Permission Mode Examples) ​

預設模式 (Default Mode) ​

計畫模式 (Plan Mode) ​

自動接受編輯模式 (Accept Edits Mode) ​

使用場景 (Use Cases) ​

無頭模式 (Headless Mode) ​

什麼是列印模式？ (What is Print Mode?) ​

在列印模式下執行 (非互動式) ​

其他列印模式用法範例 ​

範例：CI/CD 整合 (Example: CI/CD Integration) ​

列印模式組態設定 (Print Mode Configuration) ​

安全模式 (排錯用) (Safe Mode) ​

工作階段管理 (Session Management) ​

工作階段管理指令 (Session Management Commands) ​

恢復工作階段 (Resuming Sessions) ​

分叉與分支工作階段 (Forking and Branching Sessions) ​

工作階段持久性 (Session Persistence) ​

使用額度限制自動繼續 (v2.1.234) ​

工作階段摘要 (Session Recap, v2.1.108) ​

跨工作階段訊息傳遞 (Cross-Session Messaging) ​

探索工作階段 (Discovering Sessions) ​

發送訊息 (Sending a Message) ​

等待工作階段進入空閒 (notify_when_idle, v2.1.236) ​

@-Mention 簡寫 (v2.1.232) ​

控制接收內容：crossSessionInbound ​

範圍與限制 (Reach and Limits) ​

進階功能 (Advanced Features)

目錄 (Table of Contents)

概述 (Overview)

計畫模式 (Planning Mode)

什麼是計畫模式？ (What is Planning Mode?)

何時使用計畫模式 (When to Use Planning Mode)

啟用計畫模式 (Activating Planning Mode)

計畫模式的優勢 (Benefits of Planning Mode)

範例：功能實作 (Example: Feature Implementation)

計畫修改 (Plan Modifications)

計畫模式組態設定 (Planning Mode Configuration)

延伸思考 (Extended Thinking)

什麼是延伸思考？ (What is Extended Thinking?)

啟用延伸思考 (Activating Extended Thinking)

Opus 5 上的安全分類器備援 (Safety-Classifier Fallback on Opus 5)

延伸思考的優勢 (Benefits of Extended Thinking)

範例：架構決策 (Example: Architectural Decision)

延伸思考組態設定 (Extended Thinking Configuration)

自動模式 (Auto Mode)

需求條件 (Requirements)

啟用自動模式 (Enabling Auto Mode)

分類器的運作方式 (How the Classifier Works)

預設封鎖的動作 (Default Blocked Actions)

預設允許的動作 (Default Allowed Actions)

組態自動模式 (Configuring Auto Mode)

使用 `"$defaults"` 擴充預設值 (v2.1.118)

使用 `autoMode.hard_deny` 進行無條件封鎖 (v2.1.136)

使用 `autoMode.classifyAllShell` 分類所有 Shell 指令 (v2.1.193)

內建意圖保護 (Built-in intent-based protection, v2.1.183)

設定等同自動模式的權限 (無需 Team 方案)

背景任務 (Background Tasks)

什麼是背景任務？ (What Are Background Tasks?)

啟動背景任務 (Starting Background Tasks)

管理背景任務 (Managing Background Tasks)

範例：平行開發 (Example: Parallel Development)

組態設定 (Configuration)

監測工具 (Monitor Tool，事件驅動流)

為什麼這很重要 (Why It Matters)

兩種常見模式 (Two Common Patterns)

具體範例 (Concrete Example)

動態工作流 (Dynamic Workflows)

何時使用 (When to Use Them)

啟動與檢視 (Launching and Viewing)

排程任務 (Scheduled Tasks)

`/loop` 指令

一次性提醒 (One-time Reminders)

管理排程任務 (Managing Scheduled Tasks)

行為細節 (Behavior Details)

雲端排程任務 (Cloud Scheduled Tasks)

停用排程任務 (Disabling Scheduled Tasks)

範例：監測部署 (Example: Monitoring a Deployment)

權限模式 (Permission Modes)

可用的權限模式 (Available Permission Modes)

啟用方式 (Activation Methods)

權限模式範例 (Permission Mode Examples)

預設模式 (Default Mode)

計畫模式 (Plan Mode)

自動接受編輯模式 (Accept Edits Mode)

使用場景 (Use Cases)

無頭模式 (Headless Mode)

什麼是列印模式？ (What is Print Mode?)

在列印模式下執行 (非互動式)

其他列印模式用法範例

範例：CI/CD 整合 (Example: CI/CD Integration)

列印模式組態設定 (Print Mode Configuration)

安全模式 (排錯用) (Safe Mode)

工作階段管理 (Session Management)

工作階段管理指令 (Session Management Commands)

恢復工作階段 (Resuming Sessions)

分叉與分支工作階段 (Forking and Branching Sessions)

工作階段持久性 (Session Persistence)

使用額度限制自動繼續 (v2.1.234)

工作階段摘要 (Session Recap, v2.1.108)

跨工作階段訊息傳遞 (Cross-Session Messaging)

探索工作階段 (Discovering Sessions)

發送訊息 (Sending a Message)

等待工作階段進入空閒 (`notify_when_idle`, v2.1.236)

`@`-Mention 簡寫 (v2.1.232)

控制接收內容：`crossSessionInbound`

範圍與限制 (Reach and Limits)