Documentation 2026-11-13 23:02 UTC to 2026-11-14 03:01 UTC

14 14 

15## checkpointing 如何運作15## checkpointing 如何運作

16 16 

17當您啟用檔案 checkpointing 時，SDK 會在透過 Write、Edit 或 NotebookEdit 工具修改檔案之前建立檔案備份。回應串流中的使用者訊息包含一個 checkpoint UUID，您可以將其用作還原點。17當您啟用檔案檢查點功能時，SDK 會在透過 Write、Edit 或 NotebookEdit 工具修改檔案之前建立檔案備份。每個開始一個回合的提示詞都是一個檢查點，而其使用者訊息的 UUID 就是還原點。

18 18 

19> [!NOTE]19> [!NOTE]

20>20>

147 147 

148**2. 捕捉 checkpoint UUID 和工作階段 ID**148**2. 捕捉 checkpoint UUID 和工作階段 ID**

149 149 

150設定 `replay-user-messages` 選項後，回應串流中的每個使用者訊息都有一個 UUID，可作為 checkpoint。150設定 `replay-user-messages` 選項後，每個開始一個回合的提示詞所對應的使用者訊息都有一個 UUID，可作為檢查點。攜帶工具結果的使用者訊息也有 UUID，但該 UUID 並不是檢查點。

151 151 

152對於大多數使用案例，捕捉第一個使用者訊息 UUID（`message.uuid`）；回溯到它會將受追蹤的檔案還原到其原始狀態。若要儲存多個 checkpoint 並回溯到中間狀態，請參閱[多個還原點](#multiple-restore-points)。152對於大多數使用案例，捕捉第一個使用者訊息 UUID（`message.uuid`）；回溯到它會將受追蹤的檔案還原到其原始狀態。若要儲存多個 checkpoint 並回溯到中間狀態，請參閱[多個還原點](#multiple-restore-points)。

153 153 

171 171 

172### 在危險操作前進行 checkpoint172### 在危險操作前進行 checkpoint

173 173 

174此模式只保留最新的 checkpoint UUID，在每個代理程式轉向前更新它。如果在處理期間出現問題，您可以立即回溯到最後的安全狀態並跳出迴圈。174此模式只保留最新的 checkpoint UUID，並在每個開始新回合的提示詞處更新它。如果在處理期間出現問題，您可以立即回溯到最後的安全狀態並跳出迴圈。

175 175 

176執行此範例前，請將 `your_revert_condition`（Python）或 `yourRevertCondition`（TypeScript）替換為您自己的檢查，例如錯誤偵測或驗證失敗；此範例中未定義預留位置。176執行此範例前，請將 `your_revert_condition`（Python）或 `yourRevertCondition`（TypeScript）替換為您自己的檢查，例如錯誤偵測或驗證失敗；此範例中未定義預留位置。

177 177 

193 await client.query("Refactor the authentication module")193 await client.query("Refactor the authentication module")

194 194 

195 async for message in client.receive_response():195 async for message in client.receive_response():

196 # Update checkpoint before each agent turn starts196 # Update checkpoint at each prompt you send; a tool result isn't one

197 # This overwrites the previous checkpoint. Only keep the latest197 # This overwrites the previous checkpoint. Only keep the latest

198 if isinstance(message, UserMessage) and message.uuid:198 if (

199 isinstance(message, UserMessage)

200 and message.uuid

201 and message.tool_use_result is None

202 and message.parent_tool_use_id is None

203 ):

199 safe_checkpoint = message.uuid204 safe_checkpoint = message.uuid

200 205 

201 # Decide when to revert based on your own logic206 # Decide when to revert based on your own logic

225 let safeCheckpoint: string | undefined;230 let safeCheckpoint: string | undefined;

226 231 

227 for await (const message of response) {232 for await (const message of response) {

228 // Update checkpoint before each agent turn starts233 // Update checkpoint at each prompt you send; a tool result isn't one

229 // This overwrites the previous checkpoint. Only keep the latest234 // This overwrites the previous checkpoint. Only keep the latest

230 if (message.type === "user" && message.uuid) {235 if (message.type === "user" && "isReplay" in message && message.isReplay && message.uuid) {

231 safeCheckpoint = message.uuid;236 safeCheckpoint = message.uuid;

232 }237 }

233 238 

246 251 

247### 多個還原點252### 多個還原點

248 253 

249如果 Claude 在多個轉向中進行變更，您可能想要回溯到特定點而不是一直回到開始。例如，如果 Claude 在第一個轉向中重構檔案，在第二個轉向中新增測試，您可能想要保留重構但撤銷測試。254如果 Claude 在多個提示詞中進行變更，您可能想要回溯到特定點而不是一直回到開始。例如，如果您的第一個提示詞重構了檔案，第二個提示詞新增了測試，請回溯到第二個提示詞的 checkpoint，以保留重構並撤銷測試。

250 255 

251此模式將所有 checkpoint UUID 儲存在具有中繼資料的陣列中。工作階段完成後，您可以回溯到任何先前的 checkpoint：256此模式將每個 checkpoint UUID 連同中繼資料儲存在陣列中。工作階段完成後，您可以回溯到任何先前的 checkpoint：

252 257 

253```python Python theme={null}258```python Python theme={null}

254import asyncio259import asyncio

284 await client.query("Refactor the authentication module")289 await client.query("Refactor the authentication module")

285 290 

286 async for message in client.receive_response():291 async for message in client.receive_response():

287 if isinstance(message, UserMessage) and message.uuid:292 if (

293 isinstance(message, UserMessage)

294 and message.uuid

295 and message.tool_use_result is None

296 and message.parent_tool_use_id is None

297 ):

288 checkpoints.append(298 checkpoints.append(

289 Checkpoint(299 Checkpoint(

290 id=message.uuid,300 id=message.uuid,

338 348 

339 try {349 try {

340 for await (const message of response) {350 for await (const message of response) {

341 if (message.type === "user" && message.uuid) {351 if (message.type === "user" && "isReplay" in message && message.isReplay && message.uuid) {

342 checkpoints.push({352 checkpoints.push({

343 id: message.uuid,353 id: message.uuid,

344 description: `After turn ${checkpoints.length + 1}`,354 description: `After turn ${checkpoints.length + 1}`,

638 648 

639* 檔案 checkpointing 未在原始工作階段上啟用（`enable_file_checkpointing` 或 `enableFileCheckpointing` 未設定為 `true`）649* 檔案 checkpointing 未在原始工作階段上啟用（`enable_file_checkpointing` 或 `enableFileCheckpointing` 未設定為 `true`）

640* 在嘗試恢復和回溯之前，工作階段未正確完成650* 在嘗試恢復和回溯之前，工作階段未正確完成

651* UUID 來自攜帶工具結果的使用者訊息，而該訊息並非檢查點

641 652 

642**解決方案**：確保在原始工作階段上設定了 `enable_file_checkpointing=True`（Python）或 `enableFileCheckpointing: true`（TypeScript），然後使用範例中顯示的模式：捕捉第一個使用者訊息 UUID，完全完成工作階段，然後使用空提示恢復並呼叫 `rewindFiles()` 一次。653**解決方案**：確保在原始工作階段上設定了 `enable_file_checkpointing=True`（Python）或 `enableFileCheckpointing: true`（TypeScript），然後使用範例中顯示的模式：捕捉第一個使用者訊息 UUID，完全完成工作階段，然後使用空提示恢復並呼叫 `rewindFiles()` 一次。

643 654 

496| **持久性** | 每個專案檔案 | 儲存為檔案 | 僅限會話 | 僅限會話 |496| **持久性** | 每個專案檔案 | 儲存為檔案 | 僅限會話 | 僅限會話 |

497| **可重複使用性** | 每個專案 | 跨專案 | 程式碼重複 | 程式碼重複 |497| **可重複使用性** | 每個專案 | 跨專案 | 程式碼重複 | 程式碼重複 |

498| **管理** | 在檔案系統上 | CLI + 檔案 | 在程式碼中 | 在程式碼中 |498| **管理** | 在檔案系統上 | CLI + 檔案 | 在程式碼中 | 在程式碼中 |

499| **預設工具** | 保留 | 保留 | 保留 | 遺失（除非包含） |499| **工具指引** | 保留 | 保留 | 保留 | 遺失（除非包含） |

500| **內建安全** | 維持 | 維持 | 維持 | 必須新增 |500| **內建安全** | 維持 | 維持 | 維持 | 必須新增 |

501| **自訂程度** | 僅新增 | 新增；可省略程式設計指示 | 僅新增 | 完全控制 |501| **自訂程度** | 僅新增 | 新增；可省略程式設計指示 | 僅新增 | 完全控制 |

502| **版本控制** | 與專案一起 | 是 | 與程式碼一起 | 與程式碼一起 |502| **版本控制** | 與專案一起 | 是 | 與程式碼一起 | 與程式碼一起 |

875| `allowed_tools` | `list[str]` | `[]` | 無需提示即可自動核准的工具，但從[網路路徑](https://code.claude.com/docs/zh-TW/permissions.md#network-paths)讀取的操作除外。這不會限制 Claude 只使用這些工具。如果您在此處命名其中一個[任務追蹤工具](https://code.claude.com/docs/zh-TW/agent-sdk/todo-tracking.md#model-availability)，Claude Code 也會為工作階段選擇加入。其他未列出的工具會進入 `permission_mode` 和 `can_use_tool`。使用 `disallowed_tools` 來封鎖工具。請參閱[權限](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#allow-and-deny-rules) |875| `allowed_tools` | `list[str]` | `[]` | 無需提示即可自動核准的工具，但從[網路路徑](https://code.claude.com/docs/zh-TW/permissions.md#network-paths)讀取的操作除外。這不會限制 Claude 只使用這些工具。如果您在此處命名其中一個[任務追蹤工具](https://code.claude.com/docs/zh-TW/agent-sdk/todo-tracking.md#model-availability)，Claude Code 也會為工作階段選擇加入。其他未列出的工具會進入 `permission_mode` 和 `can_use_tool`。使用 `disallowed_tools` 來封鎖工具。請參閱[權限](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#allow-and-deny-rules) |

876| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | 系統提示詞設定。傳遞字串以取得自訂提示詞、`{"type": "preset", "preset": "claude_code"}` 以取得 Claude Code 的系統提示詞（含選用的 `"append"`）、`{"type": "custom", "prompt": "..."}` 以取得也可以設定 `"snapshot"` 的自訂提示詞，或 `{"type": "file", "path": "..."}` 以從磁碟載入大型提示詞。請參閱 [`SystemPromptPreset`](#systempromptpreset)、[`SystemPromptCustom`](#systempromptcustom) 和 [`SystemPromptFile`](#systempromptfile) |876| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | 系統提示詞設定。傳遞字串以取得自訂提示詞、`{"type": "preset", "preset": "claude_code"}` 以取得 Claude Code 的系統提示詞（含選用的 `"append"`）、`{"type": "custom", "prompt": "..."}` 以取得也可以設定 `"snapshot"` 的自訂提示詞，或 `{"type": "file", "path": "..."}` 以從磁碟載入大型提示詞。請參閱 [`SystemPromptPreset`](#systempromptpreset)、[`SystemPromptCustom`](#systempromptcustom) 和 [`SystemPromptFile`](#systempromptfile) |

877| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 伺服器設定或設定檔的路徑 |877| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 伺服器設定或設定檔的路徑 |

878| `strict_mcp_config` | `bool` | `False` | 當為 `True` 時，僅使用在 `mcp_servers` 中傳遞的伺服器，並忽略專案 `.mcp.json`、使用者設定、外掛提供的 MCP 伺服器和 [claude.ai 連接器](https://code.claude.com/docs/zh-TW/mcp.md#use-mcp-servers-from-claude-ai)。對應至 CLI `--strict-mcp-config` 旗標 |878| `strict_mcp_config` | `bool` | `False` | 當為 `True` 時，使用在 `mcp_servers` 中傳遞的伺服器，並忽略專案 `.mcp.json`、使用者設定、外掛提供的 MCP 伺服器和 [claude.ai 連接器](https://code.claude.com/docs/zh-TW/mcp.md#use-mcp-servers-from-claude-ai)。對應至 CLI `--strict-mcp-config` 旗標 |

879| `permission_mode` | `PermissionMode \| None` | `None` | 工具使用的權限模式 |879| `permission_mode` | `PermissionMode \| None` | `None` | 工具使用的權限模式 |

880| `continue_conversation` | `bool` | `False` | 繼續最近的對話 |880| `continue_conversation` | `bool` | `False` | 繼續最近的對話 |

881| `resume` | `str \| None` | `None` | 要繼續的工作階段 ID |881| `resume` | `str \| None` | `None` | 要繼續的工作階段 ID |

340| `Read`、`Edit`、`Glob` | 分析和修改代碼 |340| `Read`、`Edit`、`Glob` | 分析和修改代碼 |

341| `Read`、`Edit`、`Bash`、`Glob`、`Grep` | 完全自動化 |341| `Read`、`Edit`、`Bash`、`Glob`、`Grep` | 完全自動化 |

342 342 

343若要將 agent 的內建工具限制為其中一組，請將其作為 `tools` 傳入。如果您改為在 `allowedTools` 中列出一組工具，則是[預先核准這些工具](https://code.claude.com/docs/zh-TW/agent-sdk/custom-tools.md#configure-allowed-tools)，agent 仍可呼叫其他工具，但須遵循您的權限模式。

344 

343**權限模式**控制您想要多少人工監督。SDK 會按照固定順序評估活躍模式以及您的允許和拒絕規則，詳見[權限如何被評估](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#how-permissions-are-evaluated)。如需完整的模式列表、其行為以及何時使用各個模式，請參閱[代理迴圈如何運作中的權限模式](https://code.claude.com/docs/zh-TW/agent-sdk/agent-loop.md#permission-mode)。345**權限模式**控制您想要多少人工監督。SDK 會按照固定順序評估活躍模式以及您的允許和拒絕規則，詳見[權限如何被評估](https://code.claude.com/docs/zh-TW/agent-sdk/permissions.md#how-permissions-are-evaluated)。如需完整的模式列表、其行為以及何時使用各個模式，請參閱[代理迴圈如何運作中的權限模式](https://code.claude.com/docs/zh-TW/agent-sdk/agent-loop.md#permission-mode)。

344 346 

345## 後續步驟347## 後續步驟

146| `prompt` | `string` | 是 | 代理的系統提示，定義其角色和行為 |146| `prompt` | `string` | 是 | 代理的系統提示，定義其角色和行為 |

147| `tools` | `string[]` | 否 | 允許的工具名稱陣列。如果省略，會繼承[子代理可用的每個工具](https://code.claude.com/docs/zh-TW/sub-agents.md#available-tools) |147| `tools` | `string[]` | 否 | 允許的工具名稱陣列。如果省略，會繼承[子代理可用的每個工具](https://code.claude.com/docs/zh-TW/sub-agents.md#available-tools) |

148| `disallowedTools` | `string[]` | 否 | 要從代理工具集中移除的工具名稱陣列。也接受 MCP 伺服器層級的模式：`mcp__server` 或 `mcp__server__*` 會移除該伺服器的每個工具，而 `mcp__*` 會移除任何伺服器的每個 MCP 工具 |148| `disallowedTools` | `string[]` | 否 | 要從代理工具集中移除的工具名稱陣列。也接受 MCP 伺服器層級的模式：`mcp__server` 或 `mcp__server__*` 會移除該伺服器的每個工具，而 `mcp__*` 會移除任何伺服器的每個 MCP 工具 |

149| `model` | `string` | 否 | 此代理的模型覆寫。接受別名，例如 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'`，或完整的模型 ID。`'inherit'` 使用主要模型。當您省略它時，Claude Code 會選擇[子代理模型順序](https://code.claude.com/docs/zh-TW/sub-agents.md#choose-a-model)中的模型 |149| `model` | `string` | 否 | 此 agent 的模型覆寫。接受別名，例如 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'`，或完整的模型 ID。`'inherit'` 使用產生此 agent 的那個 agent 的模型。當您省略 `model` 時，Claude Code 會選擇[subagent 模型順序](https://code.claude.com/docs/zh-TW/sub-agents.md#choose-a-model)中的模型 |

150| `skills` | `string[]` | 否 | 在啟動時預先載入 agent 上下文的 skill 名稱清單。清單中最多只會預先載入[前 32 個不重複的名稱](https://code.claude.com/docs/zh-TW/sub-agents.md#preload-skills-into-subagents)。未列出的 skill 仍可透過 Skill 工具叫用 |150| `skills` | `string[]` | 否 | 在啟動時預先載入 agent 上下文的 skill 名稱清單。清單中最多只會預先載入[前 32 個不重複的名稱](https://code.claude.com/docs/zh-TW/sub-agents.md#preload-skills-into-subagents)。未列出的 skill 仍可透過 Skill 工具叫用 |

151| `memory` | `'user' \| 'project' \| 'local'` | 否 | 此代理的記憶來源 |151| `memory` | `'user' \| 'project' \| 'local'` | 否 | 此代理的記憶來源 |

152| `mcpServers` | `(string \| object)[]` | 否 | 此代理可用的 MCP 伺服器，按名稱或內嵌設定 |152| `mcpServers` | `(string \| object)[]` | 否 | 此代理可用的 MCP 伺服器，按名稱或內嵌設定 |

589| `skills` | `string[] \| 'all'` | `undefined` | 工作階段可用的 skill。傳入 `'all'` 以啟用所有探索到的 skill，或傳入 skill 名稱清單。僅傳入確切名稱。在 Agent SDK v0.3.221 或更新版本中，SDK 會在啟動 Claude Code 程序之前以錯誤拒絕格式錯誤和萬用字元形式的名稱。設定此項時，SDK 會自動將 Skill 工具加入 `allowedTools`。若您同時傳入 `tools`，請在該清單中包含 `'Skill'`。請參閱 [Skills](https://code.claude.com/docs/zh-TW/agent-sdk/skills.md) |589| `skills` | `string[] \| 'all'` | `undefined` | 工作階段可用的 skill。傳入 `'all'` 以啟用所有探索到的 skill，或傳入 skill 名稱清單。僅傳入確切名稱。在 Agent SDK v0.3.221 或更新版本中，SDK 會在啟動 Claude Code 程序之前以錯誤拒絕格式錯誤和萬用字元形式的名稱。設定此項時，SDK 會自動將 Skill 工具加入 `allowedTools`。若您同時傳入 `tools`，請在該清單中包含 `'Skill'`。請參閱 [Skills](https://code.claude.com/docs/zh-TW/agent-sdk/skills.md) |

590| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | 用於產生 Claude Code 程序的自訂函式。用於在 VM、容器或遠端環境中執行 Claude Code |590| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | 用於產生 Claude Code 程序的自訂函式。用於在 VM、容器或遠端環境中執行 Claude Code |

591| `stderr` | `(data: string) => void` | `undefined` | stderr 輸出的回呼 |591| `stderr` | `(data: string) => void` | `undefined` | stderr 輸出的回呼 |

592| `strictMcpConfig` | `boolean` | `false` | 僅使用 `mcpServers` 中傳入的伺服器，並忽略專案 `.mcp.json`、使用者設定、外掛提供的 MCP 伺服器以及 [claude.ai 連接器](https://code.claude.com/docs/zh-TW/mcp.md#use-mcp-servers-from-claude-ai) |592| `strictMcpConfig` | `boolean` | `false` | 使用在 `mcpServers` 中傳遞的伺服器，並忽略專案的 `.mcp.json`、使用者設定、外掛提供的 MCP 伺服器，以及 [claude.ai 連接器](https://code.claude.com/docs/zh-TW/mcp.md#use-mcp-servers-from-claude-ai) |

593| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined`（最簡提示詞） | 系統提示詞設定。傳入字串以使用自訂提示詞，或傳入 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系統提示詞。傳入字串陣列，並在靜態部分與逐請求部分之間放置匯出的 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 常數，即可[快取自訂提示詞的靜態部分](https://code.claude.com/docs/zh-TW/agent-sdk/modifying-system-prompts.md#cache-the-static-part-of-a-custom-prompt)。使用預設物件形式時，加入 `append` 以附加額外指令，並設定 `excludeDynamicSections: true` 將每個工作階段的上下文移至第一則使用者訊息，以[在不同機器間更好地重複使用提示詞快取](https://code.claude.com/docs/zh-TW/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines)。設定 `snapshot: false` 可在每次請求時重新建構提示詞，而不是[重複使用工作階段在第一次請求時記錄的提示詞](https://code.claude.com/docs/zh-TW/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session)。若要在自訂提示詞上設定 `snapshot`，請傳入 `{ type: 'custom', prompt }` 形式。`{ type: 'custom' }` 形式和 `snapshot` 欄位需要 TypeScript Agent SDK v0.3.257 或更新版本 |593| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined`（最簡提示詞） | 系統提示詞設定。傳入字串以使用自訂提示詞，或傳入 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系統提示詞。傳入字串陣列，並在靜態部分與逐請求部分之間放置匯出的 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 常數，即可[快取自訂提示詞的靜態部分](https://code.claude.com/docs/zh-TW/agent-sdk/modifying-system-prompts.md#cache-the-static-part-of-a-custom-prompt)。使用預設物件形式時，加入 `append` 以附加額外指令，並設定 `excludeDynamicSections: true` 將每個工作階段的上下文移至第一則使用者訊息，以[在不同機器間更好地重複使用提示詞快取](https://code.claude.com/docs/zh-TW/agent-sdk/modifying-system-prompts.md#improve-prompt-caching-across-users-and-machines)。設定 `snapshot: false` 可在每次請求時重新建構提示詞，而不是[重複使用工作階段在第一次請求時記錄的提示詞](https://code.claude.com/docs/zh-TW/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session)。若要在自訂提示詞上設定 `snapshot`，請傳入 `{ type: 'custom', prompt }` 形式。`{ type: 'custom' }` 形式和 `snapshot` 欄位需要 TypeScript Agent SDK v0.3.257 或更新版本 |

594| `taskBudget` | `{ total: number }` | `undefined` | *Alpha。* API 端的任務預算（以 token 計）。設定後，模型會被告知其剩餘的 token 預算，以便調整工具使用節奏並在達到上限前收尾 |594| `taskBudget` | `{ total: number }` | `undefined` | *Alpha。* API 端的任務預算（以 token 計）。設定後，模型會被告知其剩餘的 token 預算，以便調整工具使用節奏並在達到上限前收尾 |

595| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 支援的模型為 `{ type: 'adaptive' }` | 控制 Claude 的思考／推理行為。選項請參閱 [`ThinkingConfig`](#thinkingconfig) |595| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 支援的模型為 `{ type: 'adaptive' }` | 控制 Claude 的思考／推理行為。選項請參閱 [`ThinkingConfig`](#thinkingconfig) |

1285| `tools` | 否 | 允許的工具名稱陣列。若省略，則繼承所有[可供 subagent 使用的工具](https://code.claude.com/docs/zh-TW/sub-agents.md#available-tools)。若要將 Skills 預先載入 agent 的上下文，請使用 `skills` 欄位，而不是在此列出 `'Skill'` |1285| `tools` | 否 | 允許的工具名稱陣列。若省略，則繼承所有[可供 subagent 使用的工具](https://code.claude.com/docs/zh-TW/sub-agents.md#available-tools)。若要將 Skills 預先載入 agent 的上下文，請使用 `skills` 欄位，而不是在此列出 `'Skill'` |

1286| `disallowedTools` | 否 | 要為此 agent 明確禁止的工具名稱陣列。也接受 MCP 伺服器層級的模式：`mcp__server` 或 `mcp__server__*` 會移除該伺服器的所有工具，而 `mcp__*` 會移除任何伺服器的所有 MCP 工具 |1286| `disallowedTools` | 否 | 要為此 agent 明確禁止的工具名稱陣列。也接受 MCP 伺服器層級的模式：`mcp__server` 或 `mcp__server__*` 會移除該伺服器的所有工具，而 `mcp__*` 會移除任何伺服器的所有 MCP 工具 |

1287| `prompt` | 是 | agent 的系統提示詞 |1287| `prompt` | 是 | agent 的系統提示詞 |

1288| `model` | 否 | 此 agent 的模型覆寫。接受別名，例如 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'`，或完整的模型 ID。`'inherit'` 使用主模型。省略時，Claude Code 會依照 [subagent 模型順序](https://code.claude.com/docs/zh-TW/sub-agents.md#choose-a-model)選擇模型 |1288| `model` | 否 | 此 agent 的模型覆寫。接受別名，例如 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'`，或完整的模型 ID。`'inherit'` 會使用產生此 agent 之 agent 的模型。當您省略 `model` 時，Claude Code 會依照 [subagent 模型順序](https://code.claude.com/docs/zh-TW/sub-agents.md#choose-a-model)選擇模型 |

1289| `mcpServers` | 否 | 此 agent 的 MCP 伺服器規格 |1289| `mcpServers` | 否 | 此 agent 的 MCP 伺服器規格 |

1290| `skills` | 否 | 要預先載入 agent 上下文的 skill 名稱陣列 |1290| `skills` | 否 | 要預先載入 agent 上下文的 skill 名稱陣列 |

1291| `initialPrompt` | 否 | 當此 agent 作為主執行緒 agent 執行時，會自動提交為第一個使用者回合 |1291| `initialPrompt` | 否 | 當此 agent 作為主執行緒 agent 執行時，會自動提交為第一個使用者回合 |

102>102>

103> `tmux` 在某些作業系統上有已知限制，傳統上在 macOS 上效果最佳。在 iTerm2 中使用 `tmux -CC` 是進入 `tmux` 的建議入口點。103> `tmux` 在某些作業系統上有已知限制，傳統上在 macOS 上效果最佳。在 iTerm2 中使用 `tmux -CC` 是進入 `tmux` 的建議入口點。

104 104 

105預設值是 `"in-process"`。設定 `"auto"` 以在您已在 tmux 工作階段內運行或您的終端是已安裝 `it2` CLI 的 iTerm2 時啟用分割窗格，否則回退到 in-process。`"tmux"` 設定啟用分割窗格模式，並根據您的終端自動偵測是否使用 tmux 或 iTerm2。105在 agent teams [已啟用](#enable-agent-teams)的情況下，請按照以下步驟為每個隊友提供自己的窗格：

106 106 

107設定 `"iterm2"` 以明確使用 iTerm2 原生分割窗格。此模式需要 [`it2` CLI](https://github.com/mkusaka/it2)，如果 `it2` 遺失，會顯示帶有安裝命令的錯誤。當您的終端是 iTerm2 且 tmux 可作為備用方案時，在 `"auto"` 或 `"tmux"` 下會出現提供安裝 `it2` 或切換到 tmux 的設定提示。107**1. 安裝 tmux 或設定 iTerm2**

108 108 

109若要覆蓋預設值，請在 `~/.claude/settings.json` 中設定 [`teammateMode`](https://code.claude.com/docs/zh-TW/settings-reference#teammatemode)：109分割窗格模式需要 [tmux](https://github.com/tmux/tmux/wiki) 或 iTerm2 搭配 [`it2` CLI](https://github.com/mkusaka/it2)。請設定您將用來執行 Claude Code 的那一個：

110 

111* **tmux**：透過您系統的套件管理器安裝。請參閱 [tmux wiki](https://github.com/tmux/tmux/wiki/Installing) 以了解平台特定的指示。

112* **iTerm2**：安裝 [`it2` CLI](https://github.com/mkusaka/it2)，然後在 **iTerm2 > Settings > General > Magic > Enable Python API** 中啟用 Python API。

113 

114**2. 開啟分割窗格**

115 

116在您變更 [`teammateMode`](https://code.claude.com/docs/zh-TW/settings-reference#teammatemode) 設定之前，隊友會以 in-process 方式運行。

117 

118在 `~/.claude/settings.json` 中將其設定為 `"auto"`：

110 119 

111```json theme={null}120```json theme={null}

112{121{

114}123}

115```124```

116 125 

126使用 `"auto"` 時，當您在 tmux 或 iTerm2 內執行 Claude Code，隊友會在分割窗格中開啟；在其他終端機中則以 in-process 方式運行。

127 

128**3. 啟動 Claude Code 並生成隊友**

129 

130在 tmux 內或 iTerm2 中執行 `claude`，然後要求 Claude 生成隊友。

131 

132如果 iTerm2 中出現 `it2` 的設定提示，請選擇 **Install it2 now**，以在您的 iTerm2 視窗中開啟窗格。

133 

134如果您在 tmux 和 iTerm2 之外執行 Claude Code，或窗格未在您的 iTerm2 視窗中開啟，請再次變更 `teammateMode`：

135 

136* **在 tmux 和 iTerm2 之外**：在已安裝 tmux 的情況下，將 `teammateMode` 設定為 `"tmux"`。窗格會在獨立的 tmux 工作階段中開啟。若要查看它們，請從 Claude Code 提示字元中的 `View teammates` 行複製命令，並在第二個終端機中執行該命令。

137* **窗格未在您的 iTerm2 視窗中開啟**：將 `teammateMode` 設定為 `"iterm2"` 以使用 iTerm2 自身的窗格。如此一來，只有當您在已設定 `it2` 的 iTerm2 中執行 Claude Code 時，隊友才會啟動。

138 

117若要為單個工作階段設定模式，請將其作為旗標傳遞：139若要為單個工作階段設定模式，請將其作為旗標傳遞：

118 140 

119```bash theme={null}141```bash theme={null}

122 144 

123`--teammate-mode` 旗標是實驗性的，不會出現在 `claude --help` 中。145`--teammate-mode` 旗標是實驗性的，不會出現在 `claude --help` 中。

124 146 

125分割窗格模式需要 [tmux](https://github.com/tmux/tmux/wiki) 或 iTerm2 搭配 [`it2` CLI](https://github.com/mkusaka/it2)。若要手動安裝：

126 

127* **tmux**：透過您系統的套件管理器安裝。請參閱 [tmux wiki](https://github.com/tmux/tmux/wiki/Installing) 以了解平台特定的指示。

128* **iTerm2**：安裝 [`it2` CLI](https://github.com/mkusaka/it2)，然後在 **iTerm2 → Settings → General → Magic → Enable Python API** 中啟用 Python API。

129 

130### 指定隊友和模型147### 指定隊友和模型

131 148 

132Claude 根據您的任務決定要生成的隊友數量，或者您可以指定您想要的確切內容：149Claude 根據您的任務決定要生成的隊友數量，或者您可以指定您想要的確切內容：

497* **沒有來自 in-process 隊友的背景 subagent**：in-process 隊友自己的 subagent 在前景中執行，因為隊友的背景工作無法超越主管的程序。Claude Code 在隊友生成定義設定 `background: true` 的 subagent 時會傳回錯誤。隊友的 `run_in_background: true` 請求也會失敗，可能傳回錯誤或在前景中無聲執行。從主要對話啟動的 subagent 遵循[背景預設](https://code.claude.com/docs/zh-TW/sub-agents.md#run-subagents-in-foreground-or-background)。514* **沒有來自 in-process 隊友的背景 subagent**：in-process 隊友自己的 subagent 在前景中執行，因為隊友的背景工作無法超越主管的程序。Claude Code 在隊友生成定義設定 `background: true` 的 subagent 時會傳回錯誤。隊友的 `run_in_background: true` 請求也會失敗，可能傳回錯誤或在前景中無聲執行。從主要對話啟動的 subagent 遵循[背景預設](https://code.claude.com/docs/zh-TW/sub-agents.md#run-subagents-in-foreground-or-background)。

498* **主管是固定的**：主要工作階段在其生命週期內是主管。您無法將隊友提升為主管或轉移領導權。515* **主管是固定的**：主要工作階段在其生命週期內是主管。您無法將隊友提升為主管或轉移領導權。

499* **生成時無法為每個隊友設定權限模式**：隊友開始時具有 [權限](#permissions) 下所述的權限模式。516* **生成時無法為每個隊友設定權限模式**：隊友開始時具有 [權限](#permissions) 下所述的權限模式。

500* **分割窗格需要 tmux 或 iTerm2**：預設 in-process 模式在任何終端中工作。VS Code 的整合終端、Windows Terminal 或 Ghostty 不支援分割窗格模式。517* **分割窗格需要 tmux 或 iTerm2**：預設 in-process 模式在任何終端機中都能運作。

501 518 

502## 後續步驟519## 後續步驟

503 520 

144| 形狀 | 意義 |144| 形狀 | 意義 |

145| :- | :- |145| :- | :- |

146| `✻` 或動畫 `✽` | 工作階段程序正在執行，或工作階段需要您的輸入 |146| `✻` 或動畫 `✽` | 工作階段程序正在執行，或工作階段需要您的輸入 |

147| `∙` | 程序已結束。您仍然可以查看該列，當您回覆或附加時，Claude 會從其已儲存的對話重新啟動它 |147| `∙` | 程序已結束。您仍然可以查看該列，當您回覆或按 `Enter` 時，Claude 會從其已儲存的對話重新啟動它 |

148| `✢` | 在迭代之間休眠的 [`/loop`](https://code.claude.com/docs/zh-TW/scheduled-tasks) 工作階段。該列顯示其執行次數和倒數計時 |148| `✢` | 在迭代之間休眠的 [`/loop`](https://code.claude.com/docs/zh-TW/scheduled-tasks) 工作階段。該列顯示其執行次數和倒數計時 |

149 149 

150可能出現在列右邊緣的 `#N` 或 `!N` 標籤是指向工作階段的 [pull request 或 merge request](#pull-request-status) 的連結，不是狀態圖示的一部分。150可能出現在列右邊緣的 `#N` 或 `!N` 標籤是指向工作階段的 [pull request 或 merge request](#pull-request-status) 的連結，不是狀態圖示的一部分。

316* 在群組標題上按 `Enter` 以摺疊群組，但 [篩選](#filter-sessions) 啟用時除外，此時所有群組都會保持展開316* 在群組標題上按 `Enter` 以摺疊群組，但 [篩選](#filter-sessions) 啟用時除外，此時所有群組都會保持展開

317* 按 `Ctrl+X` 停止工作階段，並在兩秒內再次按 `Ctrl+X` 將其從清單中刪除，或按 `Esc` 關閉確認而不刪除。即使停止嘗試失敗（例如因為 [背景服務沒有回應](#agent-view-says-the-background-service-did-not-respond)），第二次按下仍會刪除工作階段。在這種情況下，確認狀態會再維持兩秒，而刪除動作會自行結束工作階段的程序317* 按 `Ctrl+X` 停止工作階段，並在兩秒內再次按 `Ctrl+X` 將其從清單中刪除，或按 `Esc` 關閉確認而不刪除。即使停止嘗試失敗（例如因為 [背景服務沒有回應](#agent-view-says-the-background-service-did-not-respond)），第二次按下仍會刪除工作階段。在這種情況下，確認狀態會再維持兩秒，而刪除動作會自行結束工作階段的程序

318 318 

319在群組標題上按 `Ctrl+X` 會在確認後刪除該群組中的每個工作階段。除了 [刪除工作階段會移除什麼](#what-deleting-a-session-removes) 中說明的保留情況外，刪除會將工作階段從清單中移除。Claude 為其建立的 worktree 會被移除、保留或留在原位，取決於您的刪除方式以及 worktree 中的內容。對話逐字稿保留在您的本機上，可透過 `claude --resume` 取得。319在群組標題上按 `Ctrl+X` 會在確認後刪除該群組中的每個工作階段，但 Claude Code [拒絕刪除](#delete-a-session-after-claude-code-refuses) 的工作階段除外。若要了解每個工作階段的 worktree 會如何處理，請參閱 [刪除工作階段會移除什麼](#what-deleting-a-session-removes)。對話逐字稿保留在您的本機上，可透過 `claude --resume` 取得。

320 320 

321螢幕上放不下的已完成工作階段會摺疊成 `… N more` 列。`Completed` 群組會填滿即時群組之後剩餘的垂直空間。在較矮的終端機上，標題會壓縮成單一摘要行，讓工作中或需要輸入的工作階段保持可見。321螢幕上放不下的已完成工作階段會摺疊成 `… N more` 列。`Completed` 群組會填滿即時群組之後剩餘的垂直空間。在較矮的終端機上，標題會壓縮成單一摘要行，讓工作中或需要輸入的工作階段保持可見。

322 322 

622 622 

623#### 刪除工作階段會移除什麼623#### 刪除工作階段會移除什麼

624 624 

625在 [agent view](#organize-the-list) 中按兩次 `Ctrl+X`，或使用 [`claude rm`](#manage-sessions-from-the-shell) 刪除工作階段。除了下方保留的情況外，工作階段會從清單中移除。其逐字稿會透過 `claude --resume` 保留在您的電腦上，且移除在 supervisor 重新啟動後仍然有效。625在 [agent view](#organize-the-list) 中按兩次 `Ctrl+X`，或使用 [`claude rm`](#manage-sessions-from-the-shell) 刪除工作階段。工作階段會從清單中消失，除非 Claude Code [拒絕刪除它](#delete-a-session-after-claude-code-refuses)。其逐字稿會保留在您的電腦上，可透過 `claude --resume` 存取。

626 626 

627Claude 為工作階段建立的 worktree 會如何處理：627Claude 為工作階段建立的 worktree 會如何處理：

628 628 

629* Agent view 會移除它，包括未提交的變更，因此請先提交您想保留的內容。629* Agent view 會移除它，包括未提交的變更，因此請先提交您想保留的內容。

630* `claude rm` 在它有未提交的變更時會保留它，連同工作階段列一起保留。630* `claude rm` 在它有未提交的變更時會保留它，連同工作階段列一起保留。

631* 當另一個執行中的工作階段正在使用或已鎖定某個 worktree 時，agent view 和 `claude rm` 都不會移除它，再次刪除也不會改變這一點。Claude Code 會保留 worktree 和工作階段，並指出保留的目錄及原因；在 agent view 中，工作階段的列會顯示 `not removed`。請關閉另一個工作階段，然後再次刪除。

632* 當您刪除的工作階段，其 worktree 有 Claude Code 無法確認已保存在其他地方的提交時，Claude Code 會保留 worktree 和工作階段，且訊息會指出 worktree 的分支以及有多少提交尚未推送。訊息也會提供兩種後續做法：推送提交，或再次刪除以捨棄它們。

633 631 

634 遠端上的提交不會阻擋刪除。位於您 `origin` 遠端預設分支之本機副本上的提交也不會，前提是該分支已在您的主簽出中簽出，也就是儲存庫目錄本身，而不是 worktree。632Claude Code 拒絕刪除工作階段的原因之一是[其 worktree 中有未推送的提交](https://code.claude.com/docs/zh-TW/errors.md#worktree-has-commits-that-are-not-pushed-anywhere)。若要保留這些提交，請在刪除工作階段之前推送它們。

635 633 

636 在該拒絕之後，您可以選擇：634無論您使用 agent view 或 `claude rm`，某些 worktree 都會保留在磁碟上：

637 635 

638 * 若要保留提交，請推送它們，或將它們合併到該預設分支，然後再次刪除工作階段。636* 如果您自己建立了 worktree 並從其中啟動工作階段，該 worktree 會保留在磁碟上，由您決定保留或移除。

639 * 若要捨棄它們，請在不推送的情況下再次刪除工作階段：在 agent view 中於其列上按兩次 `Ctrl+X`，或執行拒絕訊息所印出的 `claude rm <id> --discard-unpushed` 命令。這會移除工作階段和 worktree 及其分支，捨棄未推送的提交和任何未提交的變更。637* 如果 Claude 在您的儲存庫內建立的 worktree 目錄已不再有其 `.git` 檔案，該目錄會保留在磁碟上，由您自行移除。worktree 的分支會保留在儲存庫中，因此您會保有該分支上的提交。

640 638 

641 當您再次刪除時，Claude Code 只會捨棄拒絕訊息所顯示的內容：如果 worktree 在此之後新增了提交，Claude Code 會再次保留它並顯示更新後的狀態。639##### 在 Claude Code 拒絕後刪除工作階段

642 640 

643 當另一個已完成工作階段的記錄也指向該 worktree 時，您再次刪除時它仍會保留；請推送提交，然後再次刪除。641當 Claude Code 因工作階段的 worktree 而拒絕刪除它時，請依照其顯示的訊息操作。如果訊息指出有未推送的提交，請參閱 [Worktree has commits that are not pushed anywhere](https://code.claude.com/docs/zh-TW/errors.md#worktree-has-commits-that-are-not-pushed-anywhere)。

644* git 已無法辨識的 worktree（例如在 `git worktree prune` 之後）不會阻擋刪除。Claude Code 會刪除工作階段，並將目錄留在磁碟上。

645* 當 git 或您的 [`WorktreeRemove` hook](https://code.claude.com/docs/zh-TW/hooks#worktreeremove) 無法移除 worktree 時，Claude Code 會保留 worktree 和工作階段，且訊息會指出原因。若是 hook，訊息會說明其結束方式（例如 `exited 1`），並引用其 stderr 的開頭。訊息也會告訴您接下來可以執行以下哪一項：

646 642 

647 * 再次刪除工作階段以強制移除目錄，方法是在 agent view 中於其列上按兩次 `Ctrl+X`，或執行 `claude rm` 拒絕訊息所印出的 `claude rm <id> --force-remove-worktree <worktree-id>` 命令。worktree 的分支會保留在儲存庫中。643##### 解決 `Worktree not removed` 訊息

648 644 

649 只有在 Claude Code 能確認以下所有條件時，才會提供此選項：645`Worktree not removed` 訊息表示 Claude Code 或您的 [`WorktreeRemove` hook](https://code.claude.com/docs/zh-TW/hooks#worktreeremove) 未能完成移除工作階段的 worktree。請推送任何提交並複製出您想保留的任何檔案，然後依照訊息操作。

650 646 

651 * 該目錄是儲存庫在 `.claude/worktrees/` 下的連結 worktree 之一647##### 解決 `files that weren't checked against a repository` 訊息

652 * worktree 及已簽出的 submodule 對追蹤檔案都沒有未提交的變更

653 * 沒有其他工作階段的記錄指向它

654 648 

655 當 Claude Code 無法驗證 submodule 簽出的狀態時（例如已被獨立 git 儲存庫取代的 submodule），也不會提供此選項。649來自 `claude rm` 的此訊息表示，在不屬於任何 git 儲存庫或由 [`WorktreeCreate` hook](https://code.claude.com/docs/zh-TW/hooks#worktreecreate) 管理的 worktree 目錄中仍有檔案。請複製出您想保留的任何檔案，然後依您的情況採取對應步驟：

656 * 修正造成阻礙的問題，例如提交或 stash 未提交的變更、將獨立的 git 儲存庫移出 worktree、關閉正在使用該目錄的任何程式，或修正 hook，然後再次刪除工作階段。

657 * 自行移除目錄，然後再次刪除工作階段。

658 650 

659您自己建立並在其中啟動工作階段的 worktree，無論哪種情況都會保留在原處。651| 您的情況 | 處理方式 |

660 652| :- | :- |

661worktree 目錄不屬於任何 git 儲存庫的工作階段（因為儲存庫已被刪除，或 [`WorktreeCreate` hook](https://code.claude.com/docs/zh-TW/hooks#worktreecreate) 在其他位置建立了該目錄）仍然可以刪除。當目錄中仍有檔案時：653| 沒有 `WorktreeCreate` hook 管理該目錄 | 若要捨棄這些檔案，請在 agent view 中於工作階段的列上按兩次 `Ctrl+X`。或自行移除該目錄，然後再次執行 `claude rm <id>` |

662 654| 有 `WorktreeCreate` hook 管理該目錄，且您有 [`WorktreeRemove` hook](https://code.claude.com/docs/zh-TW/hooks#worktreeremove) | 若要嘗試以您的 hook 移除該目錄，請在 agent view 中於工作階段的列上按兩次 `Ctrl+X`。或自行移除該目錄，然後再次執行 `claude rm <id>` |

663* Agent view 在捨棄它們之前，會要求相同的 `Ctrl+X` 連按兩次。對於 hook 建立的目錄，它會改為執行您的 [`WorktreeRemove` hook](https://code.claude.com/docs/zh-TW/hooks#worktreeremove)，若沒有該 hook，則會拒絕刪除並保留工作階段。655| 有 `WorktreeCreate` hook 管理該目錄，且您沒有 `WorktreeRemove` hook | 自行移除該目錄，然後再次執行 `claude rm <id>` |

664* `claude rm` 會保留工作階段和 worktree，並指出原因。

665 

666無論哪種方式，都會保留另一個已完成工作階段的記錄所指向的目錄。

667 656 

668### 設定模型、effort 與快速模式657### 設定模型、effort 與快速模式

669 658 

774| [`--add-dir <path>`](https://code.claude.com/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) | 授予對額外目錄的檔案存取權限 |763| [`--add-dir <path>`](https://code.claude.com/docs/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) | 授予對額外目錄的檔案存取權限 |

775| [`--plugin-dir <path>`](https://code.claude.com/docs/zh-TW/plugins/create#load-a-directory-or-archive-for-one-session) | 從本機目錄載入外掛 |764| [`--plugin-dir <path>`](https://code.claude.com/docs/zh-TW/plugins/create#load-a-directory-or-archive-for-one-session) | 從本機目錄載入外掛 |

776| [`--mcp-config <file-or-json>`](https://code.claude.com/docs/zh-TW/mcp) | 從設定檔或 JSON 字串載入 MCP 伺服器 |765| [`--mcp-config <file-or-json>`](https://code.claude.com/docs/zh-TW/mcp) | 從設定檔或 JSON 字串載入 MCP 伺服器 |

777| `--strict-mcp-config` | 僅使用來自 `--mcp-config` 的 MCP 伺服器，忽略其他 MCP 設定。關於此旗標在受管 MCP 檔案下的行為，請參閱[使用 managed-mcp.json 進行獨佔控制](https://code.claude.com/docs/zh-TW/managed-mcp.md#exclusive-control-with-managed-mcp-json) |766| `--strict-mcp-config` | 略過在 `.mcp.json` 等位置設定的 MCP 伺服器，並載入您以 `--mcp-config` 傳遞的 MCP 伺服器。關於此旗標在受管 MCP 檔案下的行為，請參閱[使用 managed-mcp.json 進行獨佔控制](https://code.claude.com/docs/zh-TW/managed-mcp.md#exclusive-control-with-managed-mcp-json) |

778 767 

779每個值各重複一次 `--add-dir`、`--plugin-dir` 或 `--mcp-config`。`claude agents` 不支援以空格分隔的形式，例如 `--add-dir a b c`。768每個值各重複一次 `--add-dir`、`--plugin-dir` 或 `--mcp-config`。`claude agents` 不支援以空格分隔的形式，例如 `--add-dir a b c`。

780 769 

802| `claude stop <id>` | 停止工作階段。也接受 `claude kill` |791| `claude stop <id>` | 停止工作階段。也接受 `claude kill` |

803| `claude respawn <id>` | 重新啟動工作階段（執行中或已停止），例如用於採用更新的 Claude Code 二進位檔案。具有已儲存對話的工作階段會繼續該對話 |792| `claude respawn <id>` | 重新啟動工作階段（執行中或已停止），例如用於採用更新的 Claude Code 二進位檔案。具有已儲存對話的工作階段會繼續該對話 |

804| `claude respawn --all` | 重新啟動每個執行中的工作階段，例如一次將所有工作階段移至更新的 Claude Code 二進位檔案 |793| `claude respawn --all` | 重新啟動每個執行中的工作階段，例如一次將所有工作階段移至更新的 Claude Code 二進位檔案 |

805| `claude rm <id>` | 從清單中移除工作階段，以及 Claude 為其建立的 worktree（當安全刪除時）；請參閱 [刪除工作階段會移除什麼](#what-deleting-a-session-removes)。對話逐字稿會保留在您的本機上，並可透過 `claude --resume` 繼續使用 |794| `claude rm <id>` | 從清單中移除工作階段，以及 Claude 為其建立的 worktree（當可安全刪除時）。如果 Claude Code 因其 worktree 而拒絕刪除工作階段，請參閱 [在 Claude Code 拒絕後刪除工作階段](#delete-a-session-after-claude-code-refuses)。對話逐字稿會保留在您的本機上，並可透過 `claude --resume` 繼續使用 |

806| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 刪除因未推送提交而拒絕刪除的工作階段，捨棄 worktree 及其分支和提交。傳遞拒絕列印的確切值；請參閱 [刪除工作階段會移除什麼](#what-deleting-a-session-removes)。需要 v2.1.260 或更新版本 |795| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | 在 Claude Code 因未推送的提交而拒絕後，再次嘗試刪除工作階段並捨棄其 worktree。請從提供此命令的 `claude rm` 訊息中複製該命令；請參閱 [Worktree has commits that are not pushed anywhere](https://code.claude.com/docs/zh-TW/errors.md#worktree-has-commits-that-are-not-pushed-anywhere)。需要 v2.1.260 或更新版本 |

807| `claude rm <id> --force-remove-worktree <worktree-id>` | 刪除因 git 或 `WorktreeRemove` hook 無法移除其 worktree 而拒絕刪除的工作階段，無論如何刪除 worktree 目錄並在儲存庫中保留其分支。傳遞拒絕列印的確切值；請參閱 [刪除工作階段會移除什麼](#what-deleting-a-session-removes)。需要 v2.1.268 或更新版本 |796| `claude rm <id> --force-remove-worktree <worktree-id>` | 在 Claude Code 因無法移除 worktree 而拒絕後，再次嘗試刪除工作階段，並無論如何移除其 worktree 目錄。請從提供此命令的 `claude rm` 訊息中複製該命令；請參閱 [解決 `Worktree not removed` 訊息](#resolve-a-worktree-not-removed-message)。需要 v2.1.268 或更新版本 |

808| `claude daemon status` | 列印 [supervisor](#the-supervisor-process) 的狀態、版本、socket 目錄和 worker 計數 |797| `claude daemon status` | 列印 [supervisor](#the-supervisor-process) 的狀態、版本、socket 目錄和 worker 計數 |

809| `claude daemon logs` | 追蹤 supervisor 的日誌檔案 [`~/.claude/daemon.log`](#where-state-is-stored)，在新行出現時列印出來，直到您按下 `Ctrl+C` |798| `claude daemon logs` | 追蹤 supervisor 的日誌檔案 [`~/.claude/daemon.log`](#where-state-is-stored)，在新行出現時列印出來，直到您按下 `Ctrl+C` |

810| `claude daemon stop --any` | 停止 supervisor 程序及其託管的背景工作階段。傳遞 `--keep-workers` 以保持背景工作階段執行中，以便[下一個 supervisor](#the-supervisor-process) 可以重新連接到它們。下一個 `claude agents` 或 `claude --bg` 會啟動全新的 supervisor |799| `claude daemon stop --any` | 停止 supervisor 程序及其託管的背景工作階段。傳遞 `--keep-workers` 以保持背景工作階段執行中，以便[下一個 supervisor](#the-supervisor-process) 可以重新連接到它們。下一個 `claude agents` 或 `claude --bg` 會啟動全新的 supervisor |

939 928 

940 在該列上按 `Enter`，頁尾會顯示 `Press enter again to resume this session (it ended while the background service was off), or ctrl+x to remove it.` 在同一列上再次按 `Enter` 以恢復其已儲存的對話。回覆或 `claude attach <id>` 會在沒有該頁尾提示的情況下恢復它。929 在該列上按 `Enter`，頁尾會顯示 `Press enter again to resume this session (it ended while the background service was off), or ctrl+x to remove it.` 在同一列上再次按 `Enter` 以恢復其已儲存的對話。回覆或 `claude attach <id>` 會在沒有該頁尾提示的情況下恢復它。

941 930 

942當[逐字稿清理](https://code.claude.com/docs/zh-TW/settings-reference.md#cleanupperioddays)已移除停止工作階段的已儲存對話時，Claude Code 會拒絕開啟該列：訊息會說明沒有可恢復的內容。`claude rm <id>` 會刪除該列（上述[保留的情況](#what-deleting-a-session-removes)除外），而 `claude respawn <id>` 會再次執行其原始提示詞。請參閱[此工作階段的已儲存對話已不在磁碟上](https://code.claude.com/docs/zh-TW/errors.md#this-sessions-saved-conversation-is-no-longer-on-disk)。931當[逐字稿清理](https://code.claude.com/docs/zh-TW/settings-reference.md#cleanupperioddays)已移除停止工作階段的已儲存對話時，Claude Code 會拒絕開啟該列：訊息會說明沒有可恢復的內容。`claude rm <id>` 會刪除該列，除非 [Claude Code 拒絕刪除](#what-deleting-a-session-removes)，而 `claude respawn <id>` 會再次執行其原始提示詞。請參閱[此工作階段的已儲存對話已不在磁碟上](https://code.claude.com/docs/zh-TW/errors.md#this-sessions-saved-conversation-is-no-longer-on-disk)。

943 932 

944單純的睡眠不會停止工作階段。工作階段在睡眠期間會被保留，監督程序在喚醒時會重新連接到它們。933單純的睡眠不會停止工作階段。工作階段在睡眠期間會被保留，監督程序在喚醒時會重新連接到它們。

945 934 

973 962 

974當背景工作階段的程序在完成啟動前退出，且主機記憶體不足時，該列的狀態會說明退出情況並附加 `possibly low memory — free some up and retry`。963當背景工作階段的程序在完成啟動前退出，且主機記憶體不足時，該列的狀態會說明退出情況並附加 `possibly low memory — free some up and retry`。

975 964 

976該註記是一個假設，而不是已確認的原因。Claude Code 只在程序無聲退出（未寫入錯誤，也未被信號停止）且主機在該時刻回報記憶體不足時才會附加它。當程序在退出前確實寫入了錯誤時，該列會改為顯示該錯誤。965> [!NOTE]

966>

967> 該註記是一個假設，而不是已確認的原因。Claude Code 只在程序無聲退出（未寫入錯誤，也未被信號停止）且主機在該時刻回報記憶體不足時才會附加它。當程序在退出前確實寫入了錯誤時，該列會改為顯示該錯誤。

977 968 

978釋放機器上的記憶體，然後附加或回覆該列，監督程序會為工作階段啟動新的程序。當記憶體持續不足時，監督程序也會自行[停止閒置工作階段](#the-supervisor-process)以釋放資源，如果停止其他工作階段沒有釋放任何資源，也會停止閒置的釘選工作階段。969釋放主機上的記憶體，然後在該列上按 `Enter`，如果[頁尾要求](#opening-a-session-says-it-has-no-saved-transcript)，請再按一次。[監督程序](#the-supervisor-process)會為工作階段啟動新的程序。當記憶體持續不足時，監督程序也會自行[停止閒置工作階段](#the-supervisor-process)以釋放資源，如果停止其他工作階段沒有釋放任何資源，也會停止閒置的釘選工作階段。

979 970 

980### Agent view 表示背景服務未回應971### Agent view 表示背景服務未回應

981 972 

1036 1027 

1037### `.claude/worktrees/` 正在填滿1028### `.claude/worktrees/` 正在填滿

1038 1029 

1039在 agent view 中刪除工作階段會移除 Claude 為其建立的 worktree，但[某些刪除會保留 worktree 或在磁碟上留下其目錄](#what-deleting-a-session-removes)，因此剩餘目錄可能會累積。Git 不再識別的目錄不會出現在 `git worktree list` 中，因此請手動移除這些目錄。1030在 agent view 中刪除工作階段會移除 Claude 為其建立的 worktree，但[某些 worktree 目錄會保留在磁碟上](#what-deleting-a-session-removes)。Git 不再識別的目錄不會出現在 `git worktree list` 中，因此請手動移除這些目錄。

1040 1031 

1041在專案目錄中使用 `git worktree list` 列出剩餘項目，並使用 `git worktree remove <path>` 逐一移除。請參閱[清理 worktree](https://code.claude.com/docs/zh-TW/worktrees.md#clean-up-worktrees)。1032在專案目錄中使用 `git worktree list` 列出剩餘項目，並使用 `git worktree remove <path>` 逐一移除。如果 Git 拒絕，請參閱[清理 subagent 和背景工作階段的 worktree](https://code.claude.com/docs/zh-TW/worktrees.md#clean-up-subagent-and-background-session-worktrees)。

1042 1033 

1043## 限制1034## 限制

1044 1035 

1046 1037 

1047* **速率限制適用**：背景工作階段與互動工作階段一樣消耗您的訂閱使用量，因此並行執行十個代理的使用配額速度快十倍。1038* **速率限制適用**：背景工作階段與互動工作階段一樣消耗您的訂閱使用量，因此並行執行十個代理的使用配額速度快十倍。

1048* **工作階段是本地的**：背景工作階段在您的機器上執行。它們在睡眠時保留，但如果機器關閉則停止。1039* **工作階段是本地的**：背景工作階段在您的機器上執行。它們在睡眠時保留，但如果機器關閉則停止。

1049* **Claude 建立的 worktrees 在 agent view 中隨工作階段刪除**：在刪除在其自己的 worktree 中編輯檔案的工作階段之前，提交變更。[某些刪除會改為保留 worktree](#what-deleting-a-session-removes)。1040* **Claude 建立的 worktrees 在 agent view 中隨工作階段刪除**：在刪除在其自己的 worktree 中編輯檔案的工作階段之前，提交變更。[某些 worktree 會保留在磁碟上](#what-deleting-a-session-removes)。

1050 1041 

1051## 相關資源1042## 相關資源

1052 1043 

432 432 

433要設定在自動刪除之前保留成品的時間，請前往 [**組織設定 > 資料和隱私**](https://claude.ai/admin-settings/data-privacy-controls)。您可以為仍然是其作者私人的成品和已共享的成品設定單獨的保留期。433要設定在自動刪除之前保留成品的時間，請前往 [**組織設定 > 資料和隱私**](https://claude.ai/admin-settings/data-privacy-controls)。您可以為仍然是其作者私人的成品和已共享的成品設定單獨的保留期。

434 434 

435### 檢查稽核日誌435### 使用 Compliance API 稽核 artifact 活動

436 436 

437發佈、分享和刪除成品各自出現在您組織的稽核日誌中，位於 `claude_artifact_*` 事件類型下，與在 claude.ai 對話中建立的成品使用的相同系列。437在 Enterprise 方案上，查詢 Compliance API 的 [Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed)，即可查看誰發佈、分享或刪除了 artifact。要找出可用於篩選的活動類型，請在 [Activity Feed 參考](https://platform.claude.com/docs/en/api/compliance/activities/list)中展開 `activity_types`，並尋找名稱包含 `artifact` 的項目。

438 438 

439### 允許列表檢視器網域439### 允許列表檢視器網域

440 440 

163Claude 決定您在對話中發送的每條訊息去向：163Claude 決定您在對話中發送的每條訊息去向：

164 164 

165* 快速問題通常在對話中得到回答。165* 快速問題通常在對話中得到回答。

166* 新工作進入新執行緒或已在該區域工作的執行緒，Claude 告訴您哪個。每個新執行緒在您的訊息下顯示為卡片：一個帶有執行緒標題和狀態的框，您點擊打開執行緒。166* 新工作進入新執行緒或已在該區域工作的執行緒，Claude 告訴您哪個。每個新執行緒都會出現在對話中，點擊它即可開啟該執行緒。

167* 一條訊息中的多個不相關任務成為單獨的執行緒。167* 一條訊息中的多個不相關任務成為單獨的執行緒。

168 168 

169如果 Claude 路由的內容與您想要的不同，請說出來。[調整 Claude 執行 project 的方式](#tune-how-claude-runs-a-project) 列出了您可以告訴它的內容，例如為後續工作重用現有執行緒或就地回答而不是啟動執行緒。169如果 Claude 路由的內容與您想要的不同，請說出來。[調整 Claude 執行 project 的方式](#tune-how-claude-runs-a-project) 列出了您可以告訴它的內容，例如為後續工作重用現有執行緒或就地回答而不是啟動執行緒。

170 170 

171執行緒的完整結果保留在執行緒中，您可以開啟對話中的卡片來讀取。執行緒產生的檔案也會出現在 project 的 [**Library**](#see-what-needs-you-in-overview) 中。171執行緒的完整結果保留在執行緒中，因此請開啟該執行緒來讀取。執行緒產生的檔案也會出現在 project 的 [**Library**](#see-what-needs-you-in-overview) 中。

172 172 

173有時 Claude 在 **Suggested threads** 清單中提議執行緒而不是啟動它們。點擊建議上的箭頭啟動該執行緒。當列出多個時，清單下的按鈕啟動所有這些。173有時 Claude 在 **Suggested threads** 清單中提議執行緒而不是啟動它們。點擊建議上的箭頭啟動該執行緒。當列出多個時，清單下的按鈕啟動所有這些。

174 174 

180* **Pull request**：當您要求時打開一個，並可以為錯誤修復或另一個具體變更自己打開一個。180* **Pull request**：當您要求時打開一個，並可以為錯誤修復或另一個具體變更自己打開一個。

181* **打開後**：使用 [auto-fix](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md#auto-fix-pull-requests) 打開監視提取請求，無論 auto-fix 是否對您的其他雲端工作階段打開。它在 CI 失敗時推送修復，解決審查評論，並在檢查通過且提取請求準備好供您審查時在執行緒中回覆。181* **打開後**：使用 [auto-fix](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md#auto-fix-pull-requests) 打開監視提取請求，無論 auto-fix 是否對您的其他雲端工作階段打開。它在 CI 失敗時推送修復，解決審查評論，並在檢查通過且提取請求準備好供您審查時在執行緒中回覆。

182 182 

183當執行緒推送了分支或打開了提取請求時，其在對話中的卡片可以顯示下一步的按鈕：

184 

185* **Resolve conflicts**、**Fix CI**、**Address comments** 和 **Merge it** 將該指示作為來自您的訊息發送到執行緒，因此您可以自己提示執行緒而不是等待它對提取請求做出反應。

186* **Review PR** 在 GitHub 上打開提取請求。

187* **Create PR** 出現在閒置執行緒已推送分支但尚未打開提取請求時。點擊它會直接從該分支建立提取請求，而不是向執行緒發送打開提取請求的指示。

188 

189要更改執行緒何時打開提取請求，例如僅在您要求時，或它們從哪個分支開始，請在任務或 [project 指示](#write-project-instructions) 中說出來。183要更改執行緒何時打開提取請求，例如僅在您要求時，或它們從哪個分支開始，請在任務或 [project 指示](#write-project-instructions) 中說出來。

190 184 

191### 在 Overview 中查看需要您的內容185### 在 Overview 中查看需要您的內容

212 206 

213### 當您需要控制時打開執行緒207### 當您需要控制時打開執行緒

214 208 

215點擊對話中執行緒的卡片或 Overview 中該執行緒的列，即可在 Overview 窗格中開啟其逐字稿。您可以在那裡：209點擊對話中的執行緒或 Overview 中該執行緒的列，即可在 Overview 窗格中開啟該執行緒。您可以在那裡：

216 210 

217* 逐步讀取 Claude 所做的內容。211* 逐步讀取 Claude 所做的內容。

218* 通過在執行緒自己的訊息框中寫入來引導任務。那裡的訊息直接進入該執行緒，而 project 對話中的後續工作只有在 Claude 將後續工作與該執行緒匹配時才會到達它。212* 通過在執行緒自己的訊息框中寫入來引導任務。那裡的訊息直接進入該執行緒，而 project 對話中的後續工作只有在 Claude 將後續工作與該執行緒匹配時才會到達它。

128| `--session-id` | 為對話使用特定工作階段 ID（必須是有效的 UUID） | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |128| `--session-id` | 為對話使用特定工作階段 ID（必須是有效的 UUID） | `claude --session-id "550e8400-e29b-41d4-a716-446655440000"` |

129| `--setting-sources` | 要載入的設定來源的逗號分隔清單（`user`、`project`、`local`）。請參閱[代理程式檢視](https://code.claude.com/docs/zh-TW/agent-view.md#what-carries-over-when-you-background)和[代理程式團隊](https://code.claude.com/docs/zh-TW/agent-teams.md#context-and-communication)以了解您從此工作階段啟動的工作階段繼承清單 | `claude --setting-sources user,project` |129| `--setting-sources` | 要載入的設定來源的逗號分隔清單（`user`、`project`、`local`）。請參閱[代理程式檢視](https://code.claude.com/docs/zh-TW/agent-view.md#what-carries-over-when-you-background)和[代理程式團隊](https://code.claude.com/docs/zh-TW/agent-teams.md#context-and-communication)以了解您從此工作階段啟動的工作階段繼承清單 | `claude --setting-sources user,project` |

130| `--settings` | 設定 JSON 檔案或內嵌 JSON 字串的路徑。您在此設定的值會覆蓋此工作階段的 `settings.json` 檔案中的相同金鑰。您省略的金鑰會保留其檔案型值。檔案必須是不超過 2 MiB 的一般檔案。請參閱[設定優先順序](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence) | `claude --settings ./settings.json` |130| `--settings` | 設定 JSON 檔案或內嵌 JSON 字串的路徑。您在此設定的值會覆蓋此工作階段的 `settings.json` 檔案中的相同金鑰。您省略的金鑰會保留其檔案型值。檔案必須是不超過 2 MiB 的一般檔案。請參閱[設定優先順序](https://code.claude.com/docs/zh-TW/settings.md#settings-precedence) | `claude --settings ./settings.json` |

131| `--strict-mcp-config` | 僅使用 `--mcp-config` 中的 MCP 伺服器，忽略所有其他 MCP 設定。請參閱[使用 managed-mcp.json 進行獨佔控制](https://code.claude.com/docs/zh-TW/managed-mcp.md#exclusive-control-with-managed-mcp-json)以了解旗標在受管 MCP 檔案下執行的操作 | `claude --strict-mcp-config --mcp-config ./mcp.json` |131| `--strict-mcp-config` | 跳過在 `.mcp.json`、`~/.claude.json` 或外掛等位置設定的 MCP 伺服器，並載入您透過 `--mcp-config` 傳遞的伺服器。請參閱[使用 managed-mcp.json 進行獨佔控制](https://code.claude.com/docs/zh-TW/managed-mcp.md#exclusive-control-with-managed-mcp-json)以了解此旗標在受管 MCP 檔案下的作用 | `claude --strict-mcp-config --mcp-config ./mcp.json` |

132| `--system-prompt` | 使用自訂文字取代整個系統提示 | `claude --system-prompt "You are a Python expert"` |132| `--system-prompt` | 使用自訂文字取代整個系統提示 | `claude --system-prompt "You are a Python expert"` |

133| `--system-prompt-file` | 從檔案載入系統提示，取代預設提示 | `claude --system-prompt-file ./custom-prompt.txt` |133| `--system-prompt-file` | 從檔案載入系統提示，取代預設提示 | `claude --system-prompt-file ./custom-prompt.txt` |

134| `--system-prompt-snapshot` | 傳遞 `off` 以在每個要求上重建系統提示，而不是重複使用[在對話的第一個要求上記錄](#system-prompt-flags-in-resumed-conversations)的提示，例如在您跨 `--continue` 執行反覆運算 `--append-system-prompt` 文字時。需要 Claude Code v2.1.257 或更新版本 | `claude --system-prompt-snapshot off` |134| `--system-prompt-snapshot` | 傳遞 `off` 以在每個要求上重建系統提示，而不是重複使用[在對話的第一個要求上記錄](#system-prompt-flags-in-resumed-conversations)的提示，例如在您跨 `--continue` 執行反覆運算 `--append-system-prompt` 文字時。需要 Claude Code v2.1.257 或更新版本 | `claude --system-prompt-snapshot off` |

2127 2127 

2128若要防止這種情況，請同時在 Claude Desktop 原則中（Windows 上位於 `HKLM`）部署 `forceLoginOrgUUID`，並設為您的 claude.ai 組織 ID。除非原則本身[選擇了 Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api#choose-an-authentication-approach)，否則 Claude Desktop 會在應用程式下次啟動時停止使用個人自己的 API 金鑰或 Console 帳戶。2128若要防止這種情況，請同時在 Claude Desktop 原則中（Windows 上位於 `HKLM`）部署 `forceLoginOrgUUID`，並設為您的 claude.ai 組織 ID。除非原則本身[選擇了 Claude API](https://claude.com/docs/third-party/claude-desktop/claude-api#choose-an-authentication-approach)，否則 Claude Desktop 會在應用程式下次啟動時停止使用個人自己的 API 金鑰或 Console 帳戶。

2129 2129 

2130部署之前，請先檢查兩種情況：2130部署之前，請先檢查三種情況：

2131 2131 

2132* **Claude Console 組織**：請勿單獨以 Claude Console 組織的 ID 部署 `forceLoginOrgUUID`，否則您組織的成員將無法使用 Claude Desktop。請改為參閱[哪些裝置提供 Claude API 帳戶登入](https://claude.com/docs/third-party/claude-desktop/claude-api#which-devices-offer-the-claude-api-account-sign-in)。2132* **Claude Console 組織**：請勿單獨以 Claude Console 組織的 ID 部署 `forceLoginOrgUUID`，否則您組織的成員將無法使用 Claude Desktop。請改為參閱[哪些裝置提供 Claude API 帳戶登入](https://claude.com/docs/third-party/claude-desktop/claude-api#which-devices-offer-the-claude-api-account-sign-in)。

2133* **Enterprise Admin Console**：如果它負責傳遞您電腦的 Claude Desktop 設定，請先將這些電腦更新至 Claude Desktop v2.37337.0 或更新版本，因為一旦設定此鍵，較早的版本就會忽略它。請參閱[讓裝置保持使用其受管設定檔](https://claude.com/docs/third-party/claude-desktop/admin-console#keep-a-device-on-its-managed-profile)。2133* **Enterprise Admin Console**：如果它負責傳遞您電腦的 Claude Desktop 設定，請先將這些電腦更新至 Claude Desktop v2.37337.0 或更新版本，因為一旦設定此鍵，較早的版本就會忽略它。請參閱[讓裝置保持使用其受管設定檔](https://claude.com/docs/third-party/claude-desktop/admin-console#keep-a-device-on-its-managed-profile)。

2134* **第三方提供者**：如果使用者在應用程式中自行設定了[第三方推論設定](https://claude.com/docs/third-party/claude-desktop/in-app-configuration)，從您部署此鍵後的下一次啟動起，Claude Desktop 就會忽略該設定。若要讓使用者繼續使用 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 LLM 閘道，請在同一個 Claude Desktop 原則中將[設定部署](https://claude.com/docs/third-party/claude-desktop/configuration)到他們的電腦。

2134 2135 

2135### 網路存取需求2136### 網路存取需求

2136 2137 

182* **Review allowed permissions**：從 **Always allowed** 面板查看和撤銷此任務的已儲存工具批准182* **Review allowed permissions**：從 **Always allowed** 面板查看和撤銷此任務的已儲存工具批准

183* **Delete**：移除任務。任務建立的工作階段會被[封存](https://code.claude.com/docs/zh-TW/desktop.md#organize-and-find-sessions)，而非刪除。存放任務 `SKILL.md` 檔案的資料夾會保留在磁碟上的 `~/.claude/scheduled-tasks/<task-name>/`，或者如果您設定了 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-TW/env-vars) 變數，則位於其下的 `scheduled-tasks/<task-name>/`。若要移除該資料夾，請自行刪除。183* **Delete**：移除任務。任務建立的工作階段會被[封存](https://code.claude.com/docs/zh-TW/desktop.md#organize-and-find-sessions)，而非刪除。存放任務 `SKILL.md` 檔案的資料夾會保留在磁碟上的 `~/.claude/scheduled-tasks/<task-name>/`，或者如果您設定了 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-TW/env-vars) 變數，則位於其下的 `scheduled-tasks/<task-name>/`。若要移除該資料夾，請自行刪除。

184 184 

185您也可以透過在任何 Desktop 工作階段中詢問 Claude 來列出、建立、編輯和暫停任務。例如，「暫停我的 dependency-audit 任務」或「顯示我的排程任務」。若要刪除任務，請使用其詳細資料頁面上的 **Delete** 按鈕。185您也可以透過詢問 Claude、讓任務自行更新，或在磁碟上編輯任務的提示詞來管理任務：

186 186 

187若要讓任務使用 `update_scheduled_task` MCP 工具變更其自己的排程或提示詞，請按一下 **Run now** 並每次核准該呼叫。187* **詢問 Claude**：在任何 Desktop 工作階段中詢問 Claude 來列出、建立、編輯和暫停任務。例如，「暫停我的 dependency-audit 任務」或「顯示我的排程任務」。若要刪除任務，請使用其詳細資料頁面上的 **Delete** 按鈕。

188 188* **讓任務自行更新**：若要讓任務使用 `update_scheduled_task` MCP 工具變更其自己的排程或提示詞，請按一下 **Run now** 並每次核准該呼叫

189若要在磁碟上編輯任務的提示詞，請開啟 `~/.claude/scheduled-tasks/<task-name>/SKILL.md`（如果設定了 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-TW/env-vars)，則在其下）。該檔案使用 YAML frontmatter 作為 `name` 和 `description`，提示詞作為主體。變更在下一次執行時生效。排程、資料夾和啟用狀態不在此檔案中：透過 Edit 表單變更它們或詢問 Claude。189* **在磁碟上編輯提示詞**：開啟 `~/.claude/scheduled-tasks/<task-name>/SKILL.md`，或者如果您設定了 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-TW/env-vars) 變數，則開啟其下的 `scheduled-tasks/<task-name>/SKILL.md`。該檔案使用 YAML frontmatter 作為 `name` 和 `description`，提示詞作為主體。變更在下一次執行時生效。排程、資料夾和啟用狀態不在此檔案中：透過 Edit 表單變更它們或詢問 Claude。

190 190 

191## 相關資源191## 相關資源

192 192 

356| `CLAUDE_CODE_PERFORCE_MODE` | 設為 `1` 以啟用可感知 Perforce 的寫入保護。設定後，若目標檔案缺少擁有者寫入位元，Edit、Write 與 NotebookEdit 會失敗並提示 `p4 edit <file>`；Perforce 會清除已同步檔案的此位元，直到 `p4 edit` 開啟它們為止。這可防止 Claude Code 繞過 Perforce 變更追蹤 |356| `CLAUDE_CODE_PERFORCE_MODE` | 設為 `1` 以啟用可感知 Perforce 的寫入保護。設定後，若目標檔案缺少擁有者寫入位元，Edit、Write 與 NotebookEdit 會失敗並提示 `p4 edit <file>`；Perforce 會清除已同步檔案的此位元，直到 `p4 edit` 開啟它們為止。這可防止 Claude Code 繞過 Perforce 變更追蹤 |

357| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | 覆寫外掛根目錄。儘管名稱如此，此變數設定的是上層目錄，而非快取本身：市集與外掛快取位於此路徑下的子目錄中。預設為 `~/.claude/plugins` |357| `CLAUDE_CODE_PLUGIN_CACHE_DIR` | 覆寫外掛根目錄。儘管名稱如此，此變數設定的是上層目錄，而非快取本身：市集與外掛快取位於此路徑下的子目錄中。預設為 `~/.claude/plugins` |

358| `CLAUDE_CODE_PLUGIN_DIRS` | 要為工作階段載入的外掛目錄，每個目錄的載入方式與 [`--plugin-dir`](https://code.claude.com/docs/zh-TW/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 旗標相同。在 Unix 上以 `:` 分隔多個路徑，在 Windows 上以 `;` 分隔。請以絕對路徑提供每個路徑，或以 `~` 開頭，因為 Claude Code 會略過相對路徑。需要 Claude Code v2.1.280 或更新版本。請參閱[為單一工作階段載入外掛](https://code.claude.com/docs/zh-TW/plugins/create.md#load-a-directory-or-archive-for-one-session) |358| `CLAUDE_CODE_PLUGIN_DIRS` | 要為工作階段載入的外掛目錄，每個目錄的載入方式與 [`--plugin-dir`](https://code.claude.com/docs/zh-TW/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 旗標相同。在 Unix 上以 `:` 分隔多個路徑，在 Windows 上以 `;` 分隔。請以絕對路徑提供每個路徑，或以 `~` 開頭，因為 Claude Code 會略過相對路徑。需要 Claude Code v2.1.280 或更新版本。請參閱[為單一工作階段載入外掛](https://code.claude.com/docs/zh-TW/plugins/create.md#load-a-directory-or-archive-for-one-session) |

359| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 控制 Claude Code 是否在 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) 的檔案變更時重新載入該 mod。重新載入適用於您使用 `--plugin-dir` 從目錄載入的 mod，且在互動式工作階段中預設為開啟。設為 `1` 可在非互動式工作階段中也開啟，或設為 `0` 在所有工作階段中關閉。需要 Claude Code v2.1.287 或更新版本。請參閱 [mod 設定與環境變數](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#settings-and-environment-variables) |359| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 控制 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) 在其檔案變更時是否重新載入。預設情況下，[skills 目錄](https://code.claude.com/docs/zh-TW/plugins/org.md#keep-skills-directory-plugins-loading)中的 mod 會在任何超過一個提示詞的工作階段中重新載入，包括[非互動](https://code.claude.com/docs/zh-TW/headless.md)工作階段。`--plugin-dir` 目錄中的 mod 僅在互動式終端機工作階段中重新載入。設為 `1` 可讓它們像 skills 目錄中的 mod 一樣重新載入，設為 `0` 則在所有地方關閉重新載入。需要 Claude Code v2.1.287 或更新版本 |

360| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 複製或重新整理外掛市集的逾時時間（毫秒）（預設：120000）。對於大型儲存庫或緩慢的網路連線，請調高此值。請參閱 [Git clone timed out](https://code.claude.com/docs/zh-TW/plugins/troubleshooting.md#git-clone-timed-out-after-120s) |360| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 複製或重新整理外掛市集的逾時時間（毫秒）（預設：120000）。對於大型儲存庫或緩慢的網路連線，請調高此值。請參閱 [Git clone timed out](https://code.claude.com/docs/zh-TW/plugins/troubleshooting.md#git-clone-timed-out-after-120s) |

361| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設為 `1` 可在市集重新整理無法連線至遠端或無法通過遠端身分驗證時，略過重新複製的嘗試並繼續使用現有的市集 checkout。適用於離線或氣隙隔離環境，在這類環境中重新複製也會以相同方式失敗。請參閱[市集更新在離線環境中失敗](https://code.claude.com/docs/zh-TW/plugins/troubleshooting.md#marketplace-updates-keep-failing-offline) |361| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設為 `1` 可在市集重新整理無法連線至遠端或無法通過遠端身分驗證時，略過重新複製的嘗試並繼續使用現有的市集 checkout。適用於離線或氣隙隔離環境，在這類環境中重新複製也會以相同方式失敗。請參閱[市集更新在離線環境中失敗](https://code.claude.com/docs/zh-TW/plugins/troubleshooting.md#marketplace-updates-keep-failing-offline) |

362| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設為 `1` 可透過 HTTPS 而非 SSH 複製 GitHub `owner/repo` 簡寫來源。適用於外掛安裝與更新，以及 `/plugin marketplace add` 與 `update`。適用於 CI 執行器、容器，或任何未為 `github.com` 設定 SSH 金鑰的環境 |362| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設為 `1` 可透過 HTTPS 而非 SSH 複製 GitHub `owner/repo` 簡寫來源。適用於外掛安裝與更新，以及 `/plugin marketplace add` 與 `update`。適用於 CI 執行器、容器，或任何未為 `github.com` 設定 SSH 金鑰的環境 |

5556 5556 

5557### Worktree 有未推送到任何地方的提交5557### Worktree 有未推送到任何地方的提交

5558 5558 

5559您嘗試刪除[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md#what-deleting-a-session-removes)，其 worktree 包含 Claude Code 無法確認已在其他地方儲存的提交。Claude Code 保留 worktree 和工作階段列，而不是在您未察覺的情況下銷毀提交。`claude rm` 命名分支和未推送的提交，並說明如何進行：5559您嘗試刪除[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md#what-deleting-a-session-removes)，其 worktree 包含 Claude Code 無法確認已在其他地方儲存的提交。`claude rm` 會說明如何進行：

5560 5560 

5561```text theme={null}5561```text theme={null}

5562kept 7c5dcf5d — its worktree is still at “/home/you/project/.claude/worktrees/fix-login”5562kept 7c5dcf5d — its worktree is still at “/home/you/project/.claude/worktrees/fix-login”

5566 5566 

5567當 Claude Code 無法總結提交時，詳細行改為顯示 `The worktree has unpushed commits`。在 [agent 檢視](https://code.claude.com/docs/zh-TW/agent-view.md)中，工作階段的列顯示 `not removed`，原因相同。5567當 Claude Code 無法總結提交時，詳細行改為顯示 `The worktree has unpushed commits`。在 [agent 檢視](https://code.claude.com/docs/zh-TW/agent-view.md)中，工作階段的列顯示 `not removed`，原因相同。

5568 5568 

5569遠端上的提交不會阻止刪除。您的 `origin` 遠端預設分支的本機副本上的提交也不會，只要該分支在您的主簽出（即儲存庫目錄本身而不是 worktree）中簽出。

5570 

5571**該怎麼做：**5569**該怎麼做：**

5572 5570 

5573* 要保留提交，推送 worktree 的分支，或將其合併到在主簽出中簽出的預設分支，然後再次刪除工作階段5571* 要保留提交，請推送它們。一旦推送將它們放到遠端追蹤分支（例如 `origin/claude/fix-login`）上，請再次嘗試刪除工作階段。

5574* 要捨棄提交，執行訊息列印的 `claude rm <id> --discard-unpushed` 命令，或在 agent 檢視中的工作階段列上再次按 `Ctrl+X` 兩次。這會移除工作階段和 worktree 以及其分支、未推送的提交和任何未提交的變更。如果刪除再次被拒絕，請依照新的訊息操作。5572* 如果訊息提供捨棄提交的選項，請先確認您不需要該 worktree、這些提交或任何未提交的變更。然後執行訊息提供的步驟：在 agent 檢視中的工作階段列上按 `Ctrl+X` 兩次，或執行 `claude rm` 列印的 `claude rm <id> --discard-unpushed <commit>@<worktree-id>` 命令。如果 Claude Code 再次拒絕，請依照新的訊息操作。

5575* 當訊息說 worktree 也由另一個已完成的工作階段記錄時，再次刪除不會捨棄它：推送提交，然後再次刪除工作階段5573* 當訊息說 worktree 也由另一個已完成的工作階段記錄時，再次刪除不會捨棄它：推送提交，然後再次嘗試刪除工作階段

5576 5574 

5577在 v2.1.268 之前，`claude rm` 將提交摘要放在 `kept` 行本身上。當 `claude rm` 無法總結提交時，`kept` 行會以 `worktree has commits that are not pushed anywhere` 代替摘要。5575在 v2.1.268 之前，`claude rm` 將提交摘要放在 `kept` 行本身上。當 `claude rm` 無法總結提交時，`kept` 行會以 `worktree has commits that are not pushed anywhere` 代替摘要。

5578 5576 

5579在 v2.1.260 之前，訊息未命名分支或提交，也沒有捨棄的途徑。您仍然可以刪除工作階段，這會遺失未提交的變更，但會保留分支和提交。使用拒絕訊息列印的路徑執行 `git worktree remove --force --force <path>`，然後執行 `claude rm <id>`。對於已鎖定的 worktree，Git 需要兩次 `--force`。5577在 v2.1.260 之前，訊息未命名分支或提交，也沒有捨棄的途徑。您仍然可以刪除工作階段，這會遺失未提交的變更，但會保留分支和提交。使用拒絕訊息列印的路徑執行 `git worktree remove --force --force <path>`，然後執行 `claude rm <id>`。對於已鎖定的 worktree，Git 需要兩次 `--force`。

5580 5578 

5581在 v2.1.248 之前，在主簽出中簽出的預設分支不計算在內：您已經合併到那裡的分支仍然會觸發此拒絕，直到其提交到達遠端。

5582 

5583### Terminal host process died5579### Terminal host process died

5584 5580 

5585每個[背景工作階段的](https://code.claude.com/docs/zh-TW/agent-view.md)終端機在背景服務下的主機程序中執行，該程序在服務仍保持其連線時死亡，因此無法連線到工作階段。5581每個[背景工作階段的](https://code.claude.com/docs/zh-TW/agent-view.md)終端機在背景服務下的主機程序中執行，該程序在服務仍保持其連線時死亡，因此無法連線到工作階段。

35以下功能在不同供應商之間有所差異：35以下功能在不同供應商之間有所差異：

36 36 

37* **MCP 伺服器**：只有當您的 claude.ai 訂閱是目前使用中的身分驗證方式時，才會載入[來自 claude.ai 的連接器](https://code.claude.com/docs/zh-TW/mcp.md#use-mcp-servers-from-claude-ai)。Microsoft Foundry [託管於 Azure 的部署](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)不支援[工具搜尋](https://code.claude.com/docs/zh-TW/mcp.md#configure-tool-search)。在 Google Cloud's Agent Platform 上，早於 Claude Opus 4.5、Claude Sonnet 4.5 與 Claude Haiku 4.5 的模型不支援工具搜尋37* **MCP 伺服器**：只有當您的 claude.ai 訂閱是目前使用中的身分驗證方式時，才會載入[來自 claude.ai 的連接器](https://code.claude.com/docs/zh-TW/mcp.md#use-mcp-servers-from-claude-ai)。Microsoft Foundry [託管於 Azure 的部署](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)不支援[工具搜尋](https://code.claude.com/docs/zh-TW/mcp.md#configure-tool-search)。在 Google Cloud's Agent Platform 上，早於 Claude Opus 4.5、Claude Sonnet 4.5 與 Claude Haiku 4.5 的模型不支援工具搜尋

38* **Subagent**：當主要對話執行 Fable 時，若使用 Claude 訂閱、Anthropic Console 帳戶，或透過 `ANTHROPIC_BASE_URL` 連線的 [LLM 閘道](https://code.claude.com/docs/zh-TW/llm-gateway)，內建的 [Explore subagent](https://code.claude.com/docs/zh-TW/sub-agents.md#built-in-subagents) 會在 Opus 上執行。在其他供應商上（包括 Claude Platform on AWS），它會在 Fable 上執行38* **Subagents**：當父對話執行 Fable 時，若使用 Claude 訂閱、Anthropic Console 帳戶，或透過 `ANTHROPIC_BASE_URL` 連線的 [LLM 閘道](https://code.claude.com/docs/zh-TW/llm-gateway)，內建的 [Explore subagent](https://code.claude.com/docs/zh-TW/sub-agents.md#built-in-subagents) 會在 Opus 上執行。在其他供應商（包括 Claude Platform on AWS）上，它會在 Fable 上執行

39* **[命令](https://code.claude.com/docs/zh-TW/commands.md#all-commands)**：39* **[命令](https://code.claude.com/docs/zh-TW/commands.md#all-commands)**：

40 * `/design-sync` 與 `/import`（及其 `claude import` 子命令形式）在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 與 Claude Platform on AWS 上無法使用，透過 [Claude apps 閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway#availability-and-limitations)也無法使用40 * `/design-sync` 與 `/import`（及其 `claude import` 子命令形式）在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 與 Claude Platform on AWS 上無法使用，透過 [Claude apps 閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway#availability-and-limitations)也無法使用

41 * `/voice` 需要 claude.ai 帳戶41 * `/voice` 需要 claude.ai 帳戶

188>188>

189> **將防護措施放在 hook 中。** 在 CLAUDE.md 或 skill 中寫下「絕不編輯 `.env`」這類指令只是請求，而非保證。封鎖該編輯的 `PreToolUse` hook 才是強制執行。如果某條規則每次都必須成立，請將其設為 hook，而不是提示詞指令。189> **將防護措施放在 hook 中。** 在 CLAUDE.md 或 skill 中寫下「絕不編輯 `.env`」這類指令只是請求，而非保證。封鎖該編輯的 `PreToolUse` hook 才是強制執行。如果某條規則每次都必須成立，請將其設為 hook，而不是提示詞指令。

190>190>

191> **Hook 輸出會進入上下文。** 執行 linter 的 `PostToolUse` hook 會將結果以文字形式回饋給 Claude 閱讀；`/fix-lint` skill 則告訴 Claude 如何解決這些問題。191> **將 hook 與 skill 搭配使用。** 使用 `PostToolUse` hook 執行您的 linter，並[將錯誤傳送給 Claude](https://code.claude.com/docs/zh-TW/hooks.md#exit-code-2-behavior-per-event)。若要提供 Claude 您自己的錯誤修正規則，請撰寫 `/fix-lint` 之類的 skill。

192 192 

193### 了解功能如何分層193### 了解功能如何分層

194 194 

283 283 

284### 沙箱機制284### 沙箱機制

285 285 

286Bash 工具的 OS 層級檔案系統和網路隔離。命令在您預先定義的邊界內執行，因此 Claude 可以在其中自由工作，無需針對每個命令顯示核准提示。沙箱機制是與[權限規則](#permission-rule)分開的一層。286Bash 工具的 OS 層級檔案系統和網路隔離。命令在您預先定義的邊界內執行。沙箱機制是與[權限規則](#permission-rule)分開的一層。

287 287 

288了解更多：[沙箱機制](https://code.claude.com/docs/zh-TW/sandboxing.md)288了解更多：[沙箱機制](https://code.claude.com/docs/zh-TW/sandboxing.md)

289 289 

242 242 

243### 封鎖對受保護檔案的編輯243### 封鎖對受保護檔案的編輯

244 244 

245防止 Claude 修改敏感檔案，例如 `.env`、`package-lock.json` 或 `.git/` 中的任何內容。Claude 會收到說明編輯遭封鎖原因的回饋，以便調整其做法。245防止 Claude 的 `Edit` 和 `Write` 工具修改敏感檔案，例如 `.env`、`package-lock.json` 或 `.git/` 中的任何內容。Claude 會收到說明編輯遭封鎖原因的回饋，以便調整其做法。

246 246 

247此範例使用由 hook 呼叫的獨立指令碼檔案。該指令碼會將目標檔案路徑與受保護模式清單進行比對，並以退出碼 2 結束來封鎖編輯。247此範例使用由 hook 呼叫的獨立指令碼檔案。該指令碼會將目標檔案路徑與受保護模式清單進行比對，並以退出碼 2 結束來封鎖編輯。

248 248 

306 306 

307要求 Claude 在您的 `.env` 檔案中新增註解。Claude Code 會在編輯執行前將其封鎖，並將指令碼的 `Blocked:` 訊息作為回饋傳遞給 Claude。307要求 Claude 在您的 `.env` 檔案中新增註解。Claude Code 會在編輯執行前將其封鎖，並將指令碼的 `Blocked:` 訊息作為回饋傳遞給 Claude。

308 308 

309Claude 仍可透過 shell 命令變更受保護的檔案。若要封鎖其中部分命令，請在 `.claude/settings.json` 的 `permissions.deny` 下，為每個路徑新增一條 [`Edit` 拒絕規則](https://code.claude.com/docs/zh-TW/permissions#what-read-and-edit-rules-cover)，例如針對專案根目錄 `.env` 的 `Edit(/.env)`。

310 

311即使有這些規則，Claude 仍可透過其他方式變更 `.env`。若要限制命令可以寫入哪些檔案，請參閱[設定沙箱機制](https://code.claude.com/docs/zh-TW/sandboxing.md#configure-sandboxing)。

312 

309### 在壓縮後重新注入上下文313### 在壓縮後重新注入上下文

310 314 

311當 Claude 的上下文視窗填滿時，壓縮會摘要對話以釋放空間。這可能會遺失重要細節。使用帶有 `compact` matcher 的 `SessionStart` hook，在每次壓縮後重新注入關鍵上下文。315當 Claude 的上下文視窗填滿時，壓縮會摘要對話以釋放空間。這可能會遺失重要細節。使用帶有 `compact` matcher 的 `SessionStart` hook，在每次壓縮後重新注入關鍵上下文。

296* 頂層的 `output_config.effort` 欄位。[自動重試和錯誤轉發](#automatic-retry-and-error-forwarding)涵蓋拒絕它的上游296* 頂層的 `output_config.effort` 欄位。[自動重試和錯誤轉發](#automatic-retry-and-error-forwarding)涵蓋拒絕它的上游

297* 自適應推理的 `thinking` 欄位，它沒有測試版標頭297* 自適應推理的 `thinking` 欄位，它沒有測試版標頭

298* 承載[對話中途系統訊息](#feature-pass-through)的 `role: "system"` 項目298* 承載[對話中途系統訊息](#feature-pass-through)的 `role: "system"` 項目

299* 自動模式[伺服器端分類器審查](https://code.claude.com/docs/zh-TW/permission-modes.md#server-side-classifier-review)的 `anthropic-beta` 值和 `safeguards` 欄位，適用於該審查保持開啟的工作階段，例如 `/status` 將 **Auto mode server** 顯示為 `Enabled` 時。若要關閉審查，請在啟動工作階段之前設定 `CLAUDE_CODE_AUTO_MODE_SERVER=0`。在終端機中，`/status` 隨後會將 **Auto mode server** 顯示為 `Disabled`。

299* 訂閱身分驗證所需的 OAuth `anthropic-beta` 值300* 訂閱身分驗證所需的 OAuth `anthropic-beta` 值

300* 開發人員透過 [`ANTHROPIC_BETAS`](https://code.claude.com/docs/zh-TW/env-vars) 或 [`CLAUDE_CODE_EXTRA_BODY`](https://code.claude.com/docs/zh-TW/env-vars) 自行添加的標頭值和請求體欄位301* 開發人員透過 [`ANTHROPIC_BETAS`](https://code.claude.com/docs/zh-TW/env-vars) 或 [`CLAUDE_CODE_EXTRA_BODY`](https://code.claude.com/docs/zh-TW/env-vars) 自行添加的標頭值和請求體欄位

301 302 

30| 模式 | 功能 | 設定 |30| 模式 | 功能 | 設定 |

31| :- | :- | :- |31| :- | :- | :- |

32| **停用 MCP** | 沒有伺服器載入，除了 [在獨佔控制下載入的少數伺服器](#exclusive-control-with-managed-mcp-json) | `managed-mcp.json` 搭配空白伺服器對應 |32| **停用 MCP** | 沒有伺服器載入，除了 [在獨佔控制下載入的少數伺服器](#exclusive-control-with-managed-mcp-json) | `managed-mcp.json` 搭配空白伺服器對應 |

33| **固定部署** | 每個使用者都取得相同的伺服器，無法新增其他伺服器 | `managed-mcp.json` 搭配您想要的伺服器 |33| **固定部署** | 每個使用者都取得您列出的伺服器，而他們自己設定的伺服器不會載入 | `managed-mcp.json` 搭配您想要的伺服器 |

34| **提供的伺服器** | 每個使用者都取得您列出的遠端伺服器，並保留他們自己的伺服器 | 受管設定中的 `managedMcpServers` |34| **提供的伺服器** | 每個使用者都取得您列出的遠端伺服器，並保留他們自己的伺服器 | 受管設定中的 `managedMcpServers` |

35| **已核准的目錄** | 發佈已核准伺服器的清單；使用者新增他們想要的伺服器，其他任何伺服器都會被封鎖 | `allowedMcpServers` + `allowManagedMcpServersOnly: true` |35| **已核准的目錄** | 發佈已核准伺服器的清單；使用者新增他們想要的伺服器，其他任何伺服器都會被封鎖 | `allowedMcpServers` + `allowManagedMcpServersOnly: true` |

36| **僅限外掛程式伺服器** | 使用者無法透過 `~/.claude.json` 或 `.mcp.json` 新增伺服器；[skills 目錄外掛](https://code.claude.com/docs/zh-TW/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings) 不再以外掛形式載入，而來自其他外掛的伺服器仍會載入 | [`strictPluginOnlyCustomization`](https://code.claude.com/docs/zh-TW/settings-reference#strictpluginonlycustomization) 搭配清單中的 `mcp` |36| **僅限外掛程式伺服器** | 使用者無法透過 `~/.claude.json` 或 `.mcp.json` 新增伺服器；[skills 目錄外掛](https://code.claude.com/docs/zh-TW/plugins/loading.md#skills-directory-plugins-blocked-by-managed-settings) 不再以外掛形式載入，而來自其他外掛的伺服器仍會載入 | [`strictPluginOnlyCustomization`](https://code.claude.com/docs/zh-TW/settings-reference#strictpluginonlycustomization) 搭配清單中的 `mcp` |

49* 該檔案定義的伺服器49* 該檔案定義的伺服器

50* 您[透過 `managedMcpServers` 提供的伺服器](#provide-servers-through-managed-settings)50* 您[透過 `managedMcpServers` 提供的伺服器](#provide-servers-through-managed-settings)

51* 啟動工作階段的應用程式註冊的同處理程序伺服器，例如 VS Code 擴充功能自己的伺服器或[桌面應用程式提供的連接器](https://code.claude.com/docs/zh-TW/mcp.md#how-connectors-reach-claude-code)51* 啟動工作階段的應用程式註冊的同處理程序伺服器，例如 VS Code 擴充功能自己的伺服器或[桌面應用程式提供的連接器](https://code.claude.com/docs/zh-TW/mcp.md#how-connectors-reach-claude-code)

52* Claude Code 在 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) [新增工具](https://code.claude.com/docs/zh-TW/plugins/mods/api.md#add-a-tool)時建立的伺服器。若要封鎖使用者的 mod 所新增的工具，請[阻止使用者安裝的 mod 載入](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#stop-user-installed-mods-from-loading)。

52* 內建的[Chrome 中的 Claude](https://code.claude.com/docs/zh-TW/chrome.md) 伺服器，如果您[允許它與受管集合並存](#allow-claude-in-chrome-alongside-the-managed-set)53* 內建的[Chrome 中的 Claude](https://code.claude.com/docs/zh-TW/chrome.md) 伺服器，如果您[允許它與受管集合並存](#allow-claude-in-chrome-alongside-the-managed-set)

53 54 

54使用者無法新增、修改或使用任何其他 MCP 伺服器，包括外掛程式提供的伺服器和透過 [`--mcp-config` CLI 旗標](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags)傳遞的伺服器。該檔案也會抑制 Claude Code 自行擷取的 claude.ai 連接器，除非您[允許它們與受管集合並存](#allow-claude-ai-connectors-alongside-the-managed-set)。55使用者無法新增、修改或使用任何其他 MCP 伺服器，包括外掛程式提供的伺服器和透過 [`--mcp-config` CLI 旗標](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags)傳遞的伺服器。該檔案也會抑制 Claude Code 自行擷取的 claude.ai 連接器，除非您[允許它們與受管集合並存](#allow-claude-ai-connectors-alongside-the-managed-set)。

137}138}

138```139```

139 140 

140`claude mcp add` 失敗，並顯示上述企業原則錯誤。使用者之前設定的伺服器在下次啟動工作階段時停止載入，沒有警告說明原則是原因。您透過 `managedMcpServers` 提供的伺服器和您允許與受管集合並存的任何其他內容仍在空對應下載入，因此請保持那些金鑰未設定以完全停用 MCP。141`claude mcp add` 失敗，並顯示上述企業原則錯誤。使用者之前設定的伺服器在下次啟動工作階段時停止載入，沒有警告說明原則是原因。您透過 `managedMcpServers` 提供的伺服器，以及您允許與受管集合並存的任何其他內容，在空對應下[仍會載入](#exclusive-control-with-managed-mcp-json)，因此請勿設定那些鍵。

141 142 

142### 允許 claude.ai 連接器與受管集合並存143### 允許 claude.ai 連接器與受管集合並存

143 144 

806 806 

807* 將其加入 [`disabledMcpjsonServers`](https://code.claude.com/docs/zh-TW/settings-reference#disabledmcpjsonservers)，這會在每種權限模式中封鎖它。807* 將其加入 [`disabledMcpjsonServers`](https://code.claude.com/docs/zh-TW/settings-reference#disabledmcpjsonservers)，這會在每種權限模式中封鎖它。

808* 使用 [`--setting-sources`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 或 SDK 的 `settingSources` 選項完全排除專案設定。808* 使用 [`--setting-sources`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 或 SDK 的 `settingSources` 選項完全排除專案設定。

809* 使用 [`--strict-mcp-config`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 啟動工作階段。Claude Code 隨後只會使用您透過 `--mcp-config` 傳入的 MCP 伺服器。對於 Claude Code 未載入的 project 範圍伺服器略過核准提示，需要 Claude Code v2.1.246 或更新版本；在 v2.1.246 之前，strict 工作階段仍會等待這些伺服器的核准，導致背景工作階段在啟動時停滯等待。如需此旗標在受管 MCP 檔案下的作用，請參閱[使用 managed-mcp.json 進行獨佔控制](https://code.claude.com/docs/zh-TW/managed-mcp.md#exclusive-control-with-managed-mcp-json)。809* 使用 [`--strict-mcp-config`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 啟動工作階段。Claude Code 隨後會載入您透過 `--mcp-config` 傳入的伺服器，並略過在 `.mcp.json` 等位置設定的伺服器。對於 Claude Code 未載入的 project 範圍伺服器略過核准提示，需要 Claude Code v2.1.246 或更新版本。如需此旗標在受管 MCP 檔案下的作用，請參閱[使用 managed-mcp.json 進行獨佔控制](https://code.claude.com/docs/zh-TW/managed-mcp.md#exclusive-control-with-managed-mcp-json)。

810 810 

811[Project 伺服器核准與工作區信任](#project-server-approvals-and-workspace-trust)說明提交至儲存庫的核准如何與工作區信任互動。811[Project 伺服器核准與工作區信任](#project-server-approvals-and-workspace-trust)說明提交至儲存庫的核准如何與工作區信任互動。

812 812 

273* **`/model`**：Claude Code 會以錯誤拒絕切換273* **`/model`**：Claude Code 會以錯誤拒絕切換

274* **`--model` 旗標、`ANTHROPIC_MODEL` 或 `model` 設定**：Claude Code 會在啟動時替換該值，並顯示同時列出請求模型與替代模型的警告，工作階段會以預設模型啟動274* **`--model` 旗標、`ANTHROPIC_MODEL` 或 `model` 設定**：Claude Code 會在啟動時替換該值，並顯示同時列出請求模型與替代模型的警告，工作階段會以預設模型啟動

275* **[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)**：Claude Code 會忽略該變數275* **[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)**：Claude Code 會忽略該變數

276* **Subagent 或隊員覆寫**：Claude Code 會以備援模型執行該 subagent 或隊員，而不是讓請求失敗。subagent 的備援請參閱[選擇模型](https://code.claude.com/docs/zh-TW/sub-agents.md#choose-a-model)，隊員的備援請參閱[指定隊員與模型](https://code.claude.com/docs/zh-TW/agent-teams.md#specify-teammates-and-models)。276* **Subagent 或隊員覆寫**：Claude Code 會以備援模型執行該 subagent 或隊員，而不是讓請求失敗。subagent 的備援請參閱[當允許清單封鎖 subagent 模型時](https://code.claude.com/docs/zh-TW/sub-agents.md#when-an-allowlist-blocks-a-subagent-model)，隊員的備援請參閱[指定隊員與模型](https://code.claude.com/docs/zh-TW/agent-teams.md#specify-teammates-and-models)。

277 277 

278 在互動式工作階段中，當 Claude Code 透過此備援或上述的最新允許版本替代來替換 subagent 的模型時，會向您發出警告，並列出請求的模型與替代的模型；隊員的備援則不會回報。278 在互動式工作階段中，當 Claude Code 替換頂層 subagent 的模型時，會向您發出警告。隊員的備援則不會回報。

279 279 

280 在上述最新允許版本替代適用的情況下，被封鎖的系列別名會改為遵循該替代方式。在 v2.1.222 之前，別名在所有提供者上都會如同其他被封鎖的值一樣改用備援280 在上述最新允許版本替代適用的情況下，被封鎖的系列別名會改為遵循該替代方式。在 v2.1.222 之前，別名在所有提供者上都會如同其他被封鎖的值一樣改用備援

281* **Skill 或命令覆寫**：Claude Code 會忽略該覆寫（包括被封鎖的系列別名），skill 或命令會以工作階段模型執行。[在 subagent 中執行](https://code.claude.com/docs/zh-TW/skills.md#run-skills-in-a-subagent)的 skill 或命令則改為遵循上述的 subagent 行為281* **Skill 或命令覆寫**：Claude Code 會忽略該覆寫（包括被封鎖的系列別名），skill 或命令會以工作階段模型執行。[在 subagent 中執行](https://code.claude.com/docs/zh-TW/skills.md#run-skills-in-a-subagent)的 skill 或命令則改為遵循上述的 subagent 行為

50| 您想要 | 開始使用 | 所需的隔離 | 注意 |50| 您想要 | 開始使用 | 所需的隔離 | 注意 |

51| :- | :- | :- | :- |51| :- | :- | :- | :- |

52| 自己審查每個操作 | Manual 模式：`claude --permission-mode default` | 無 | 敏感工作、不熟悉的程式碼 |52| 自己審查每個操作 | Manual 模式：`claude --permission-mode default` | 無 | 敏感工作、不熟悉的程式碼 |

53| 在本地迭代，提示更少，無需分類器 | Manual 模式加上 Bash 沙箱在[自動允許模式](https://code.claude.com/docs/zh-TW/sandboxing.md#sandbox-modes)中：`claude --permission-mode default`，然後執行 `/sandbox` 並選擇自動允許 | 內建 Bash 沙箱，在 macOS、Linux 和 WSL2 上 | 拒絕規則仍然適用，詢問規則命名命令（例如 `Bash(git push *)`）仍然提示。[自動允許模式](https://code.claude.com/docs/zh-TW/sandboxing.md#auto-allow-mode)涵蓋其他可能提示的命令。若要改為從設定檔開啟沙箱，請將 [`sandbox.enabled`](https://code.claude.com/docs/zh-TW/settings-reference#sandbox-enabled) 設定為 `true` |53| 在本地迭代，提示更少，無需分類器 | Manual 模式加上 Bash 沙箱在[自動允許模式](https://code.claude.com/docs/zh-TW/sandboxing.md#sandbox-modes)中：`claude --permission-mode default`，然後執行 `/sandbox` 並選擇自動允許 | 內建 Bash 沙箱，在 macOS、Linux 和 WSL2 上 | 拒絕規則仍然適用，詢問規則命名命令（例如 `Bash(git push *)`）仍然提示。[自動允許模式](https://code.claude.com/docs/zh-TW/sandboxing.md#auto-allow-mode)涵蓋其他可能提示的命令。若要改為從設定檔開啟沙箱，請將 [`sandbox.enabled`](https://code.claude.com/docs/zh-TW/settings-reference#sandbox-enabled) 和 [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/zh-TW/settings-reference#sandbox-autoallowbashifsandboxed) 設定為 `true` |

54| 在變更任何內容前探索 | `claude --permission-mode plan` | 無 | Claude Code 會阻止編輯，直到您[批准計畫](#review-and-approve-a-plan) |54| 在變更任何內容前探索 | `claude --permission-mode plan` | 無 | Claude Code 會阻止編輯，直到您[批准計畫](#review-and-approve-a-plan) |

55| 在自動模式中無人值守工作 | `claude --permission-mode auto`、[內建起始權限模式](#which-mode-a-session-starts-in)（v2.1.283 或更新版本） | 無；沙箱或容器增加深度防禦 | 需要[支援的模型](#eliminate-prompts-with-auto-mode)，您的組織可以[關閉自動模式](#eliminate-prompts-with-auto-mode) |55| 在自動模式中無人值守工作 | `claude --permission-mode auto`、[內建起始權限模式](#which-mode-a-session-starts-in)（v2.1.283 或更新版本） | 無；沙箱或容器增加深度防禦 | 需要[支援的模型](#eliminate-prompts-with-auto-mode)，您的組織可以[關閉自動模式](#eliminate-prompts-with-auto-mode) |

56| 在 CI 中使用精確允許清單執行 | `claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"` | 無，超出您的 CI 執行器提供的 | [雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)忽略設定檔中的 `dontAsk` |56| 在 CI 中使用精確允許清單執行 | `claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(npm test)" "Read"` | 無，超出您的 CI 執行器提供的 | [雲端工作階段](https://code.claude.com/docs/zh-TW/claude-code-on-the-web.md)忽略設定檔中的 `dontAsk` |

743 743 

744使用兩者進行深度防禦，因為即使提示注入繞過 Claude 的決策制定，沙箱限制仍然適用。來自沙箱設定和權限規則的路徑和網域會 [合併到最終沙箱設定](https://code.claude.com/docs/zh-TW/sandboxing.md#permission-rules)。744使用兩者進行深度防禦，因為即使提示注入繞過 Claude 的決策制定，沙箱限制仍然適用。來自沙箱設定和權限規則的路徑和網域會 [合併到最終沙箱設定](https://code.claude.com/docs/zh-TW/sandboxing.md#permission-rules)。

745 745 

746當您啟用沙箱並將 `autoAllowBashIfSandboxed` 保留在其預設值 `true` 時，沙箱化 Bash 命令無需提示即可執行，即使您的權限包括 bare `Bash` ask 規則，或 [等效的 `Bash(*)` 形式](#match-all-uses-of-a-tool)：沙箱邊界替代整個工具提示。746當您啟用沙箱機制並將 [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/zh-TW/settings-reference#sandbox-autoallowbashifsandboxed) 設為 `true` 時，沙箱化 Bash 命令無需提示即可執行。即使存在 bare `Bash` ask 規則或[等效的 `Bash(*)` 形式](#match-all-uses-of-a-tool)，這一點仍然成立：沙箱邊界會取代該整個工具的提示。

747 747 

748在 [plan mode](https://code.claude.com/docs/zh-TW/permission-modes.md#analyze-before-you-edit-with-plan-mode) 中，Claude Code 會跳過此替代。沒有 ask 規則時，[內建唯讀命令](#read-only-commands)仍然無需提示即可執行，任何其他 shell 命令在您仍在規劃時會通過常規權限流程；請參閱 [plan mode](https://code.claude.com/docs/zh-TW/permission-modes.md#analyze-before-you-edit-with-plan-mode) 以了解 Claude Code 如何在那裡控制命令。使用 bare `Bash` ask 規則時，每個 Bash 命令都會提示，包括沙箱化唯讀命令，與沙箱外相同。748在 [plan mode](https://code.claude.com/docs/zh-TW/permission-modes.md#analyze-before-you-edit-with-plan-mode) 中，Claude Code 會跳過此替代。沒有 ask 規則時，[內建唯讀命令](#read-only-commands)仍然無需提示即可執行，任何其他 shell 命令在您仍在規劃時會通過常規權限流程；請參閱 [plan mode](https://code.claude.com/docs/zh-TW/permission-modes.md#analyze-before-you-edit-with-plan-mode) 以了解 Claude Code 如何在那裡控制命令。使用 bare `Bash` ask 規則時，每個 Bash 命令都會提示，包括沙箱化唯讀命令，與沙箱外相同。

749 749 

438 438 

439* **`backdrop` 欄位**：`scene` 是您為 hook 所繪製的背景選擇的[名稱](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#limits)。關於其他欄位與 `overrideColorScheme`，請參閱[適用於您建置版本的型別](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#get-the-types-for-your-build)。439* **`backdrop` 欄位**：`scene` 是您為 hook 所繪製的背景選擇的[名稱](https://code.claude.com/docs/zh-TW/plugins/mods/reference.md#limits)。關於其他欄位與 `overrideColorScheme`，請參閱[適用於您建置版本的型別](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#get-the-types-for-your-build)。

440* **背景是否已繪製**：當連線到工作階段的 Desktop 或行動應用程式表示它會繪製背景時，`$.theme.set` 會以 `isDrawn: true` 解析。否則 `isDrawn` 為 `false`，而 `reason` 會說明原因。440* **背景是否已繪製**：當連線到工作階段的 Desktop 或行動應用程式表示它會繪製背景時，`$.theme.set` 會以 `isDrawn: true` 解析。否則 `isDrawn` 為 `false`，而 `reason` 會說明原因。

441* **每個工作階段一個背景**：`$.theme.set` 呼叫會取代工作階段的背景，而 `$.theme.clear()` 會移除該背景，無論是哪個 mod 設定的。請只在使用者要求時才呼叫 `$.theme.clear()`。441* **每個工作階段一個主題**：呼叫 `$.theme.set` 的 mod 會取代工作階段的背景與[色彩](#change-the-colors-of-the-desktop-app)，而呼叫 `$.theme.clear()` 的 mod 會移除它們，無論是哪個 mod 設定的。請只在使用者要求時才呼叫 `$.theme.clear()`。

442 

443### 變更 Desktop 應用程式的色彩

444 

445若要使用 mod 變更 Desktop 應用程式 Code 分頁的色彩，請[請 Claude 建立一個](#ask-claude-for-a-colors-mod)或[自行撰寫一個](#write-a-colors-mod-yourself)。這兩種方式都需要 Code 分頁中的 Claude Code 為 v2.1.324 或更新版本，因此請先[在該處確認版本](https://code.claude.com/docs/zh-TW/desktop.md#claude-code-version-in-the-code-tab)。終端機中的 Claude Code 會保留自己的色彩。

446 

447#### 請 Claude 建立色彩 mod

448 

449**1. 描述色彩**

450 

451在 Code 分頁中開始一個本機工作階段，並告訴 Claude 您想要的色彩。例如，輸入 `make a mod that makes the app cream in light mode and dark brown in dark mode`。Claude 會撰寫 mod 的檔案。

452 

453**2. 核准 mod**

454 

455回答 Claude Code 針對 mod 的檔案與熱重新載入所提出的問題。關於各個回答的作用，請參閱[請 Claude 建立 mod](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#ask-claude-for-a-mod)。

456 

457**3. 檢查色彩**

458 

459mod 載入時，Code 分頁的色彩就會變更。若要調整某個色彩，請告訴 Claude 要變更什麼。若沒有任何變化，請參閱[修正缺少的 mod 色彩](#fix-missing-mod-colors-in-the-desktop-app)。

460 

461#### 自行撰寫色彩 mod

462 

463`makeColors` 是一個以幾個十六進位色彩建立主題的函式。以下步驟會建立一個使用它、名為 `paper` 的 mod。

464 

465**1. 請 Claude 複製 makeColors**

466 

467在 Code 分頁中開始一個本機工作階段，並輸入 `copy make-colors.js and make-colors.d.ts from your plugin-authoring skill into ~/.claude/skills/paper/hooks/`。確認這兩個檔案都在該目錄中。

468 

469**2. 儲存 manifest 與 hooks.json**

470 

471依照[自行撰寫 mod](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#write-a-mod-yourself)，將 `.claude-plugin/plugin.json` 和 `hooks/hooks.json` 儲存到 `~/.claude/skills/paper/` 中，並在這兩個檔案中將 `first-mod` 改為 `paper`。[位於 `~/.claude/skills/` 之下](https://code.claude.com/docs/zh-TW/plugins/create#scaffold-a-plugin-that-loads-every-session)的 mod 會在您開始工作階段時載入。

472 

473**3. 撰寫程式碼**

474 

475將此檔案儲存為 `~/.claude/skills/paper/hooks/register.js`。工作階段開始時，程式碼會以淺色模式與深色模式的色彩呼叫 `$.theme.set`：

476 

477```javascript theme={null}

478import { makeColors } from './make-colors.js'

479 

480const { theme } = makeColors({

481 label: 'Paper',

482 // surface-0 is the background, text-primary is the main text, and text-muted is the faint text

483 light: {

484 gray: { anchors: { 'surface-0': '#efe6d3', 'text-primary': '#2a241d', 'text-muted': '#6a5f50' } },

485 },

486 dark: {

487 gray: { anchors: { 'surface-0': '#1f1a15', 'text-primary': '#f0e7d7', 'text-muted': '#aca08d' } },

488 },

489})

490 

491export function register(on) {

492 on('session.start', async ($, e, next) => {

493 await $.theme.set({ colors: theme })

494 return next(e)

495 })

496}

497```

498 

499若要使用您自己的色彩，請將這些十六進位值替換為其他六位數的十六進位色彩。

500 

501**4. 檢查色彩**

502 

503在 Code 分頁中開始新的本機工作階段。使用範例中的值時，背景在淺色模式下為米色，在深色模式下為深棕色。若沒有任何變化，請參閱[修正缺少的 mod 色彩](#fix-missing-mod-colors-in-the-desktop-app)。

504 

505### 修正 Desktop 應用程式中缺少的 mod 色彩

506 

507若您在 [Claude Desktop v5.11492.5 或更早版本](https://code.claude.com/docs/zh-TW/desktop.md#check-your-version)中使用[第三方供應商](https://code.claude.com/docs/zh-TW/third-party-integrations.md)而非 Claude 帳戶，Code 分頁會保留自己的色彩，因此請略過這些檢查。否則，若 mod 的色彩未出現在 Code 分頁中，或色彩消失，請檢查下列原因：

508 

509* **版本過舊**：[更新 Desktop 應用程式](https://code.claude.com/docs/zh-TW/desktop.md#claude-code-version-in-the-code-tab)、重新啟動它，並在 Code 分頁中開始新的本機工作階段。若 mod 是 Claude 撰寫的，請在該處再次請 Claude 建立。

510* **mod 未載入**：若 mod 是 Claude 撰寫的，請參閱[請 Claude 建立 mod](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#ask-claude-for-a-mod) 了解其載入時機。若 mod 是您自行撰寫的，請將您的檔案及其路徑與[自行撰寫色彩 mod](#write-a-colors-mod-yourself) 進行比對。

511* **主題遭拒絕**：請要求 Claude 執行 mod 的 [`makeColors`](#write-a-colors-mod-yourself) 呼叫。若該呼叫擲出錯誤，或其 `problems` 清單中有以 `Desktop won't paint this theme` 開頭的項目，請讓 Claude 修正主題。若 mod 是您安裝的，請將 Claude 發現的內容傳送給其作者。

512* **另一個 `$.theme` 呼叫**：當工作階段中任何 mod 呼叫 `$.theme.set` 或 `$.theme.clear()` 時，先前呼叫所設定的色彩與[背景](#put-a-backdrop-behind-the-conversation)就會消失。在您自己的 mod 中，請在同一個 `$.theme.set` 呼叫中傳入 `colors` 和 `backdrop`。一次只使用一個設定主題的 mod。

513 

514### 從 Desktop 應用程式移除 mod 色彩

515 

516若要從 Code 分頁移除 mod 的色彩，請先關閉該 mod。仍處於開啟狀態的 mod 可能會再次設定其色彩。

517 

518**1. 關閉 mod**

519 

520* **mod 由 Claude 撰寫**：將其目錄移出 Claude 撰寫它時所在工作階段的 [mod 資料夾](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#ask-claude-for-a-mod)。

521* **您將 mod 放在 `~/.claude/skills/` 之下**：將其目錄（例如 `~/.claude/skills/paper/`）移到 `~/.claude/skills/` 以外的位置。

522* **mod 是您安裝的**：在 Desktop 應用程式中，從 **Manage plugins** [停用或解除安裝其外掛](https://code.claude.com/docs/zh-TW/desktop.md#install-plugins)。若您沒有看到 **Manage plugins**，且您有 [CLI](https://code.claude.com/docs/zh-TW/quickstart.md)，可以[從您的 shell 停用或解除安裝市集外掛](https://code.claude.com/docs/zh-TW/plugins/install.md#manage-plugins-from-your-shell)。

523 

524**2. 開始新的工作階段**

525 

526在 Code 分頁中開始新的本機工作階段。

527 

528**3. 移除仍然保留的色彩**

529 

530若色彩仍然存在，請從 Code 分頁開啟 **Settings**，並在其中搜尋 `code appearance`。開啟搜尋結果，然後選取 **Remove colors**。

442 531 

443## 從元素建立樹532## 從元素建立樹

444 533 

677 766 

678相同的按鍵，或在全螢幕渲染中點擊該列，會再次展開帶狀區域。在此之前，沒有任何方式能按下其中的按鈕：沒有快捷鍵、沒有在空白提示詞輸入區中輸入的數字，也沒有按鈕 [`action`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#elements) 的快捷鍵。如果使用者收合帶狀區域時它具有鍵盤焦點，焦點會返回提示詞輸入區，且在收合期間 Ctrl+X 然後 Tab 會略過帶狀區域。767相同的按鍵，或在全螢幕渲染中點擊該列，會再次展開帶狀區域。在此之前，沒有任何方式能按下其中的按鈕：沒有快捷鍵、沒有在空白提示詞輸入區中輸入的數字，也沒有按鈕 [`action`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#elements) 的快捷鍵。如果使用者收合帶狀區域時它具有鍵盤焦點，焦點會返回提示詞輸入區，且在收合期間 Ctrl+X 然後 Tab 會略過帶狀區域。

679 768 

680帶狀區域會保持收合，直到使用者展開它，即使在 `/clear` 之後也是如此，並會在下次 Claude Code 啟動時再次展開。您的 mod 無法展開它，也無法得知它已收合：`ui.render` hook 會持續執行，`e.props` 中也沒有任何內容表明這一點。請勿讓帶狀區域成為您的 mod 顯示使用者必須回應之內容的唯一位置。769帶狀區域會保持收合，直到使用者展開它，即使在 `/clear` 之後也是如此，並會在下次 Claude Code 啟動時再次展開。您的 mod 無法展開它。請勿讓帶狀區域成為您的 mod 顯示使用者必須回應之內容的唯一位置。若要僅在帶狀區域收合時於其他位置顯示該內容，請在您的 `ui.render` hook 中讀取 `e.props.isCollapsed`，該 hook 會持續執行。`isCollapsed` 需要 Claude Code v2.1.321 或更新版本。

681 770 

682### 取得輸入的文字並為每個項目繪製一列771### 取得輸入的文字並為每個項目繪製一列

683 772 

212 212 

213其中部分事件也會針對 Claude Code 自身的動作觸發，因此在拒絕某個事件之前，請先檢查 `next.origin.plugin` 是否為 `engine`。213其中部分事件也會針對 Claude Code 自身的動作觸發，因此在拒絕某個事件之前，請先檢查 `next.origin.plugin` 是否為 `engine`。

214 214 

215#### Claude Code 自身 `http.fetch` 請求上的欄位

216 

217在 `http.fetch` hook 中，值為 `{ plugin: 'engine', tier: 'core' }` 的 [`next.origin`](#the-hook-function) 標示 Claude Code 自身的請求之一，例如模型請求，而非 mod 的 `$.http.fetch` 呼叫。在已載入[內建防護](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#know-what-happens-by-default)的情況下，除非您的 mod [被視為您組織的 mod](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#install-your-organizations-mods)，否則您的 hook 不會收到這些事件。

218 

219在這些事件上，`e.init` 以及 `next(e)` 所解析的 `value` 可能包含下列欄位等：

220 

221| 欄位 | 意義 |

222| :- | :- |

223| `e.init.compress` | 當 Claude Code 在您的 hook 之後壓縮本文時設定。`e.init.body` 存放未壓縮的本文。若要以未壓縮的形式傳送本文，請呼叫 `next({ ...e, init: { ...e.init, compress: undefined } })`。 |

224| `value.isStreaming` | 設為 `true`，因為 Claude Code 會自行讀取回應本文，所以 `value.text` 為空。請改為讀取 `value.status` 與 `value.headers`。若要以您自己的 `text` 回應，請回傳不含 `isStreaming` 的 `value`。 |

225 

226這些事件與欄位需要 Claude Code v2.1.321 或更新版本。

227 

215## Mods API 方法228## Mods API 方法

216 229 

217mods API 是每個 hook 接收的 `$` 引數。其方法依命名空間分組，例如 `$.ui`。此表依名稱列出每個命名空間的方法，因此 `$.ui` 列中的 `open` 即為呼叫 `$.ui.open(...)`。指南會示範常用方法的用法，而[您建置版本的型別](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#get-the-types-for-your-build)則以範例記錄每個方法。230mods API 是每個 hook 接收的 `$` 引數。其方法依命名空間分組，例如 `$.ui`。此表依名稱列出每個命名空間的方法，因此 `$.ui` 列中的 `open` 即為呼叫 `$.ui.open(...)`。指南會示範常用方法的用法，而[您建置版本的型別](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#get-the-types-for-your-build)則以範例記錄每個方法。

222| [`$.ui`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、[`place`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#place-a-row-in-the-transcript)、`focus`、`scroll`、`toast`、`notify`、`status`、`log`、`notice`、`ask`、`copy`、`selection`、`blit`、`view`。`view` 需要 Claude Code v2.1.300 或更新版本，`place` 需要 v2.1.314 或更新版本。 |235| [`$.ui`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、[`place`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#place-a-row-in-the-transcript)、`focus`、`scroll`、`toast`、`notify`、`status`、`log`、`notice`、`ask`、`copy`、`selection`、`blit`、`view`。`view` 需要 Claude Code v2.1.300 或更新版本，`place` 需要 v2.1.314 或更新版本。 |

223| [`$.theme`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`、`clear`：設定供 Desktop 或行動應用程式繪製的背景，以及移除該背景。需要 Claude Code v2.1.319 或更新版本。 |236| [`$.theme`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`、`clear`：設定供 Desktop 或行動應用程式繪製的背景，以及移除該背景。需要 Claude Code v2.1.319 或更新版本。 |

224| [`$.command`](https://code.claude.com/docs/zh-TW/plugins/mods/api#add-a-command) | `register`、`run`、`list` |237| [`$.command`](https://code.claude.com/docs/zh-TW/plugins/mods/api#add-a-command) | `register`、`run`、`list` |

225| [`$.tool`](https://code.claude.com/docs/zh-TW/plugins/mods/api#add-a-tool) | `register`、`call`、`check`、`list` |238| [`$.tool`](https://code.claude.com/docs/zh-TW/plugins/mods/api#add-a-tool) | `register`、`call`、`check`、`list`。當某個 `call` 需要由人員核准時，例如 hook 或您的組織以 `ask` 回應的呼叫，它會以 `{ deny: "<tool> wasn't run: this call needs a person's approval, and a mod's own call can't ask for it." }` 解析，其中 `<tool>` 為該工具的名稱。 |

226| `$.agent` | `register`、`spawn`、`list`。`list()` 會回傳此工作階段的 subagent 與隊友，每個都帶有 `status`，其值為 `pending`、`running`、`waiting`、`idle`、`completed`、`failed` 或 `killed`，其中 `idle` 與 `waiting` 需要 Claude Code v2.1.289 或更新版本。 |239| `$.agent` | `register`、`spawn`、`list`。`list()` 會回傳此工作階段的 subagent 與隊友，每個都帶有 `status`，其值為 `pending`、`running`、`waiting`、`idle`、`completed`、`failed` 或 `killed`，其中 `idle` 與 `waiting` 需要 Claude Code v2.1.289 或更新版本。 |

227| [`$.model`](https://code.claude.com/docs/zh-TW/plugins/mods/api#call-a-model) | `complete`、`fork`、`classify` |240| [`$.model`](https://code.claude.com/docs/zh-TW/plugins/mods/api#call-a-model) | `complete`、`fork`、`classify` |

228| [`$.prompt`](https://code.claude.com/docs/zh-TW/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`、`read`、`fill`、`suggest`、`compose`。Claude 會在一個指明您的 mod 為傳送者的句子之後，讀取來自 `submit({ text })` 的文字。`submit({ text, asUser: true })` 會將文字當作使用者本人的話傳送，不附帶該句子。 |241| [`$.prompt`](https://code.claude.com/docs/zh-TW/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`、`read`、`fill`、`suggest`、`compose`。Claude 會在一個指明您的 mod 為傳送者的句子之後，讀取來自 `submit({ text })` 的文字。`submit({ text, asUser: true })` 會將文字當作使用者本人的話傳送，不附帶該句子。 |

250| 位置 | `e.props` | `e.requestId` | 轉譯於 |263| 位置 | `e.props` | `e.requestId` | 轉譯於 |

251| :- | :- | :- | :- |264| :- | :- | :- | :- |

252| [`Pane`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#pick-where-to-draw) | `title`、`isFocused`、`bodyColumns`、`placement`、`scroll`、`view` | 窗格的 `id` | 終端機、Desktop、VS Code |265| [`Pane`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#pick-where-to-draw) | `title`、`isFocused`、`bodyColumns`、`placement`、`scroll`、`view` | 窗格的 `id` | 終端機、Desktop、VS Code |

253| [`AbovePrompt`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`、`isWorking`、`maxRows`、`bodyColumns`、`scroll`、`view` | 單一實例 | 終端機、Desktop |266| [`AbovePrompt`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`、[`isCollapsed`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#when-the-user-collapses-the-band)、`isWorking`、`maxRows`、`bodyColumns`、`scroll`、`view` | 單一實例 | 終端機、Desktop |

254| `AbovePromptList`，即 `AbovePrompt` 列的堆疊 | `rows`，一個清單，其中每個 mod 的列各有一個 `{ plugin, tree }`，另加上 `AbovePrompt` 的 prop | 單一實例 | 終端機、Desktop。需要 Claude Code v2.1.323 或更新版本。 |267| `AbovePromptList`，即 `AbovePrompt` 列的堆疊 | `rows`，一個清單，其中每個 mod 的列各有一個 `{ plugin, tree }`，另加上 `AbovePrompt` 的 prop | 單一實例 | 終端機、Desktop。需要 Claude Code v2.1.323 或更新版本。 |

255| [`Placed`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#place-a-row-in-the-transcript) | `id`、`plugin`、`onScreen` | `$.ui.place` 傳回的 `requestId` | 終端機 |268| [`Placed`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#place-a-row-in-the-transcript) | `id`、`plugin`、`onScreen` | `$.ui.place` 傳回的 `requestId` | 終端機 |

256| [`Backdrop`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`、`plugin`、`glass`、`overrideColorScheme`。在 v2.1.323 之前，`scene` 為 `id`，`overrideColorScheme` 為 `colorScheme`。 | `backdrop` | `desktop` 與 `mobile` 使用介面。當 Desktop 或行動應用程式要求繪製背景時，您的 hook 就會執行。 |269| [`Backdrop`](https://code.claude.com/docs/zh-TW/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`、`plugin`、`glass`、`overrideColorScheme`。在 v2.1.323 之前，`scene` 為 `id`，`overrideColorScheme` 為 `colorScheme`。 | `backdrop` | `desktop` 與 `mobile` 使用介面。當 Desktop 或行動應用程式要求繪製背景時，您的 hook 就會執行。 |

426| 名稱 | 位置 | 作用 |439| 名稱 | 位置 | 作用 |

427| :- | :- | :- |440| :- | :- | :- |

428| `CLAUDE_CODE_PLUGIN_DIRS` | 環境，或 `~/.claude/settings.json` 中的 `env` | 以 `--plugin-dir` 的方式載入的外掛目錄，供無法傳入旗標的應用程式使用。以 `:` 分隔的絕對路徑，在 Windows 上則以 `;` 分隔。 |441| `CLAUDE_CODE_PLUGIN_DIRS` | 環境，或 `~/.claude/settings.json` 中的 `env` | 以 `--plugin-dir` 的方式載入的外掛目錄，供無法傳入旗標的應用程式使用。以 `:` 分隔的絕對路徑，在 Windows 上則以 `;` 分隔。 |

429| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 環境 | `1` 會讓長時間執行的非互動式工作階段在儲存時重新載入 `--plugin-dir` mod |442| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 環境 | mod 是否在儲存時重新載入。預設值與可用值請參閱[環境變數參考](https://code.claude.com/docs/zh-TW/env-vars.md) |

430| `prependPlugins`、`appendPlugins` | 受管設定。僅在沒有受管設定或 [`managed-mcp.json`](https://code.claude.com/docs/zh-TW/managed-mcp#deploy-managed-mcp-json) 檔案的機器上、且工作階段的憑證不是 Team 或 Enterprise `/login` 時，才可使用使用者設定。 | 外掛 id 的清單，例如 `acme-guard@acme-tools`。`prependPlugins` 中的 mod 會在使用者安裝的每個 mod 之前執行，`appendPlugins` 中的 mod 則在之後執行，並依列出的順序。請參閱 [mod 執行順序](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#the-order-mods-run-in)。 |443| `prependPlugins`、`appendPlugins` | 受管設定。僅在沒有受管設定或 [`managed-mcp.json`](https://code.claude.com/docs/zh-TW/managed-mcp#deploy-managed-mcp-json) 檔案的機器上、且工作階段的憑證不是 Team 或 Enterprise `/login` 時，才可使用使用者設定。 | 外掛 id 的清單，例如 `acme-guard@acme-tools`。`prependPlugins` 中的 mod 會在使用者安裝的每個 mod 之前執行，`appendPlugins` 中的 mod 則在之後執行，並依列出的順序。請參閱 [mod 執行順序](https://code.claude.com/docs/zh-TW/plugins/mods/events.md#the-order-mods-run-in)。 |

431| `allowManagedModsOnly` | 受管設定，作為[內建防護的選項](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#set-options-on-the-built-in-guard) | 只有[屬於您組織的](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#install-your-organizations-mods) mod，以及內建於 Claude Code 的 mod，會執行其 hook。使用者的設定 hook 會繼續執行。 |444| `allowManagedModsOnly` | 受管設定，作為[內建防護的選項](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#set-options-on-the-built-in-guard) | 只有[屬於您組織的](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#install-your-organizations-mods) mod，以及內建於 Claude Code 的 mod，會執行其 hook。使用者的設定 hook 會繼續執行。 |

432| `allowModsToOverrideDenyRules` | 受管設定，作為[內建防護的選項](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#set-options-on-the-built-in-guard) | 允許使用者安裝的 mod 核准工具呼叫，越過大部分[預設會維持生效的結果](https://code.claude.com/docs/zh-TW/permissions.md#precedence-among-rules-hooks-and-mods)，包括 `deny` 規則 |445| `allowModsToOverrideDenyRules` | 受管設定，作為[內建防護的選項](https://code.claude.com/docs/zh-TW/plugins/mods/admin.md#set-options-on-the-built-in-guard) | 允許使用者安裝的 mod 核准工具呼叫，越過大部分[預設會維持生效的結果](https://code.claude.com/docs/zh-TW/permissions.md#precedence-among-rules-hooks-and-mods)，包括 `deny` 規則 |

115 115 

116### 遵循測試套件的規則116### 遵循測試套件的規則

117 117 

118測試套件有一些自己的規則，違反其中一個會產生新測試作者首先遇到的錯誤：

119 

120* **在測試首次呼叫 `$` 之前註冊每個 stub。** 在此之後呼叫 `on` 會拋出錯誤，例如 `on("ui.render") after the test first called $`。118* **在測試首次呼叫 `$` 之前註冊每個 stub。** 在此之後呼叫 `on` 會拋出錯誤，例如 `on("ui.render") after the test first called $`。

121 119 

122* **[`session.start`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#session) 不會自行執行。** 每個測試都以您的模組新鮮載入開始，其 hooks 都未被呼叫，因此模組級變數保持其初始值。如果 hook 依賴於 `session.start` 設定的內容，請先觸發它：120* **[`session.start`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#session) 不會自行執行。** 每個測試都以您的模組新鮮載入開始，其 hooks 都未被呼叫，因此模組級變數保持其初始值。如果 hook 依賴於 `session.start` 設定的內容，請先觸發它：

132 130 

133 第二個 stub 回答 `session.start` hook（例如 [tutorial's](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#write-a-mod-yourself)）進行的 `$.command.register` 呼叫。沒有它，該呼叫會以 `no implementation for command.register` 拒絕，套件會跳過您的 hook，因此 hook 中呼叫之後的任何內容都不會執行。測試在該點不會失敗。只有當稍後的檢查失敗時，跳過的 hook 才會在 `the engine reported:` 下列出。131 第二個 stub 回答 `session.start` hook（例如 [tutorial's](https://code.claude.com/docs/zh-TW/plugins/mods/create.md#write-a-mod-yourself)）進行的 `$.command.register` 呼叫。沒有它，該呼叫會以 `no implementation for command.register` 拒絕，套件會跳過您的 hook，因此 hook 中呼叫之後的任何內容都不會執行。測試在該點不會失敗。只有當稍後的檢查失敗時，跳過的 hook 才會在 `the engine reported:` 下列出。

134 132 

135* **返回 `next(e)` 的 hook 需要 stub 來回答。** 例如，當您的 [`ui.render`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#interface) hook 返回 `next(e)` 時，為了在 Claude 閒置時不繪製任何內容，[mounting it](#test-a-drawing) 會失敗，並顯示 `no implementation for ui.render`。註冊一個返回元素作為純資料的 stub：133* **註冊 `ui.render` stub 以選擇 `next(e)` 返回的內容。** 當您的 [`ui.render`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#interface) hook 返回 `next(e)` 時（例如為了在 Claude 閒置時不繪製任何內容），即使沒有 stub，[掛載](#test-a-drawing)也會成功。若要讓 `next(e)` 返回您選擇的元素，請註冊一個將該元素作為純資料返回的 stub：

136 134 

137 ```typescript theme={null}135 ```typescript theme={null}

138 // Stands for what Claude Code would draw at the site136 // Stands for what Claude Code would draw at the site

139 on('ui.render', () => ({ type: 'Text', props: {}, children: ['drawn by Claude Code'] }))137 on('ui.render', () => ({ type: 'Text', props: {}, children: ['drawn by Claude Code'] }))

140 ```138 ```

141 139 

142 註冊 stub 後，掛載成功，每當您的 hook 返回 `next(e)` 時，`ui.find({ type: 'Text' })` 都會返回該元素。在 v2.1.323 或更新版本中，若是針對 band，請將您的 mod 名稱作為第二個引數傳給 `on`，例如 `{ plugin: 'my-mod' }`。若未傳入，stub 不會回答您的 `next(e)`。140 在該位置[可以繪製該元素](https://code.claude.com/docs/zh-TW/plugins/mods/interface.md#change-what-claude-code-already-draws)的情況下，當您的 hook 返回 `next(e)` 時，`ui.find({ type: 'Text' })` 會返回該元素。在 v2.1.323 或更新版本中，若是針對 band，請將您的 mod 名稱作為第二個引數傳給 `on`，例如 `{ plugin: 'my-mod' }`。若未傳入，stub 不會回答您的 `next(e)`。在 v2.1.321 之前，除非您註冊該 stub，否則掛載會失敗，並顯示 `no implementation for ui.render`。

143 141 

144* **`turn.step` 的 stub 是一個非同步生成器**，測試會讀取流直到結束以獲得結果：142* **`turn.step` 的 stub 是一個非同步生成器**，測試會讀取流直到結束以獲得結果：

145 143 

316| `press({ key: 'more' })` | 按下具有該 key 的 `Button` |314| `press({ key: 'more' })` | 按下具有該 key 的 `Button` |

317| `input({ key: 'new-note', text: 'buy milk' })` | 將文字輸入到具有該 key 的 `Input` 中並按 Enter。新增 `kind: 'change'` 以輸入而不提交。對於具有 `rows` 的欄位，文字可以包含 `\n`。 |315| `input({ key: 'new-note', text: 'buy milk' })` | 將文字輸入到具有該 key 的 `Input` 中並按 Enter。新增 `kind: 'change'` 以輸入而不提交。對於具有 `rows` 的欄位，文字可以包含 `\n`。 |

318| `select({ key: 'size', value: 'large' })` | 在具有該 key 的 `Select` 中選擇具有該值的選項 |316| `select({ key: 'size', value: 'large' })` | 在具有該 key 的 `Select` 中選擇具有該值的選項 |

317| `keepsBeneath()` | 在沒有 `ui.render` stub 的測試中，當繪圖包含 `next(e)` 傳回的內容時，它解析為 `true`；當您的 hook 將其省略時，則解析為 `false`。在有註冊 stub 的測試中，請使用 `find` 尋找該 stub 繪製的內容。需要 Claude Code v2.1.321 或更新版本。 |

319| `find({ key: 'more' })` 或 `find({ type: 'Text', text: 'Count: 2' })` | 返回第一個匹配的元素作為 `{ type, props, children }`，或 `undefined`。`text` 可以是字串或正規表達式。 |318| `find({ key: 'more' })` 或 `find({ type: 'Text', text: 'Count: 2' })` | 返回第一個匹配的元素作為 `{ type, props, children }`，或 `undefined`。`text` 可以是字串或正規表達式。 |

320| `unmount()` | 移除繪圖 |319| `unmount()` | 移除繪圖 |

321 320 

41 41 

42| 您想要 | 開始使用 |42| 您想要 | 開始使用 |

43| :- | :- |43| :- | :- |

44| 在您自己的機器上減少日常工作中的權限提示 | [沙箱化 Bash 工具](https://code.claude.com/docs/zh-TW/sandboxing.md)，使用 `/sandbox` 設定 |44| 在您自己的機器上減少日常工作中的權限提示 | 自動允許模式下的 [沙箱化 Bash 工具](https://code.claude.com/docs/zh-TW/sandboxing.md)，使用 `/sandbox` 設定 |

45| 讓 Claude 使用 `--dangerously-skip-permissions` 或自動模式無人值守工作 | 預先設定的 [開發容器](https://code.claude.com/docs/zh-TW/devcontainer.md)、任何容器或虛擬機，或 [沙箱執行時](#sandbox-runtime) |45| 讓 Claude 使用 `--dangerously-skip-permissions` 或自動模式無人值守工作 | 預先設定的 [開發容器](https://code.claude.com/docs/zh-TW/devcontainer.md)、任何容器或虛擬機，或 [沙箱執行時](#sandbox-runtime) |

46| 隔離 MCP 伺服器和 hooks 以及 Bash，無需 Docker | 沙箱執行時 |46| 隔離 MCP 伺服器和 hooks 以及 Bash，無需 Docker | 沙箱執行時 |

47| 在團隊中標準化沙箱化環境 | 預先設定的 [開發容器](https://code.claude.com/docs/zh-TW/devcontainer.md)，複製到您的儲存庫中 |47| 在團隊中標準化沙箱化環境 | 預先設定的 [開發容器](https://code.claude.com/docs/zh-TW/devcontainer.md)，複製到您的儲存庫中 |

6 6 

7> 使用內建沙箱限制 Claude Code 的 shell 命令可存取的檔案與網路主機。啟用沙箱、設定邊界，並修正它所造成的問題。7> 使用內建沙箱限制 Claude Code 的 shell 命令可存取的檔案與網路主機。啟用沙箱、設定邊界，並修正它所造成的問題。

8 8 

9Bash 沙箱是作業系統在 Claude 於您的電腦上執行的 shell 命令周圍所強制實施的邊界。您可以設定這些命令能存取哪些檔案和網路網域，這些限制適用於 Bash、PowerShell 和 Monitor 命令，以及它們所啟動的程序。由於作業系統會在命令執行期間套用這些限制，Claude Code 可以[執行沙箱化的命令而無需詢問您](#sandbox-modes)是否核准每一個命令。9Bash 沙箱是作業系統在 Claude 於您的電腦上執行的 shell 命令周圍所強制實施的邊界。您可以設定這些命令能存取哪些檔案和網路網域，這些限制適用於 Bash、PowerShell 和 Monitor 命令，以及它們所啟動的程序。沙箱化的命令仍會經過一般的權限流程，除非您選擇[自動允許模式](#sandbox-modes)，該模式可以在不詢問您的情況下執行這些命令。

10 10 

11沙箱僅涵蓋 shell 命令。Claude 的檔案工具、MCP 伺服器和 hook [在沙箱之外執行](#what-runs-outside-the-sandbox)。11沙箱僅涵蓋 shell 命令。Claude 的檔案工具、MCP 伺服器和 hook [在沙箱之外執行](#what-runs-outside-the-sandbox)。

12 12 

394| `credentials.envVars` `deny` 和 `mask` 項目 | 強制執行。環境變數清除獨立於檔案系統層 |394| `credentials.envVars` `deny` 和 `mask` 項目 | 強制執行。環境變數清除獨立於檔案系統層 |

395| 以遮罩方式套用的 [`credentials.files` `mask` 項目](#mask-credential-files) | 強制執行：遮罩獨立於檔案系統層。[退回 `deny`](#mask-credential-files) 的項目則不強制執行，與任何 `deny` 項目相同 |395| 以遮罩方式套用的 [`credentials.files` `mask` 項目](#mask-credential-files) | 強制執行：遮罩獨立於檔案系統層。[退回 `deny`](#mask-credential-files) 的項目則不強制執行，與任何 `deny` 項目相同 |

396 396 

397另有兩項變化：397沙箱化命令也會繼承您 shell 的 `$TMPDIR`，而非每位使用者專屬的暫存目錄，因為每個暫存目錄都可寫入，Claude Code 不再將命令重新導向至每位使用者專屬的暫存目錄。

398 398 

399* 沙箱化命令會繼承您 shell 的 `$TMPDIR`，而非每位使用者專屬的暫存目錄，因為每個暫存目錄都可寫入，Claude Code 不再將命令重新導向至每位使用者專屬的暫存目錄。399在 Linux 上，此變數在父 shell 中通常未設定。Bash 工具指引會告知 Claude 使用 `mktemp -d` 建立暫用目錄，而不是依賴 `$TMPDIR`。

400 

401 在 Linux 上，此變數在父 shell 中通常未設定。Bash 工具指引會告知 Claude 使用 `mktemp -d` 建立暫用目錄，而不是依賴 `$TMPDIR`。

402* [`autoAllowBashIfSandboxed`](https://code.claude.com/docs/zh-TW/settings-reference#sandbox-autoallowbashifsandboxed) 仍預設為 `true`，因此沙箱化命令會持續在不顯示提示的情況下執行。將其設為 `false` 即可針對沙箱化命令顯示提示。

403 400 

404### 保護憑證401### 保護憑證

405 402 

1095}1092}

1096```1093```

1097 1094 

1098這會開啟[自動允許模式](#sandbox-modes)。若要使用一般權限模式，請同時將 [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/zh-TW/settings-reference#sandbox-autoallowbashifsandboxed) 設定為 `false`。此變更會在 Claude 執行下一個 shell 命令時於您執行中的工作階段生效，之後 `/sandbox` 的 **Mode** 分頁會標示目前生效的模式。1095這會開啟[一般權限模式](#sandbox-modes)。若要使用自動允許模式，請同時將 [`sandbox.autoAllowBashIfSandboxed`](https://code.claude.com/docs/zh-TW/settings-reference#sandbox-autoallowbashifsandboxed) 設定為 `true`。此變更會在 Claude 執行下一個 shell 命令時於您執行中的工作階段生效，之後 `/sandbox` 的 **Mode** 分頁會標示目前生效的模式。

1099 1096 

1100## 限制1097## 限制

1101 1098 

25 25 

26為了降低代理系統中的風險：26為了降低代理系統中的風險：

27 27 

28* **沙箱化 bash 工具**：[Sandbox](https://code.claude.com/docs/zh-TW/sandboxing.md) bash 命令具有檔案系統和網路隔離，減少權限提示同時保持安全性。使用 `/sandbox` 進行配置以定義 Claude Code 可以自主工作的邊界28* **沙箱化 Bash 工具**：以檔案系統和網路隔離將 Bash 命令置於[沙箱](https://code.claude.com/docs/zh-TW/sandboxing.md)中。使用 `/sandbox` 進行設定

29* **工作目錄邊界**：在手動模式中，Claude Code 的檔案工具在讀取或寫入啟動它的資料夾及其子資料夾以外的位置前，會先詢問您。此邊界是一種權限提示，因此您核准的 Bash 命令仍可寫入您的使用者帳戶可寫入的任何位置29* **工作目錄邊界**：在手動模式中，Claude Code 的檔案工具在讀取或寫入啟動它的資料夾及其子資料夾以外的位置前，會先詢問您。此邊界是一種權限提示，因此您核准的 Bash 命令仍可寫入您的使用者帳戶可寫入的任何位置

30 * 若要在沒有提示的情況下讀取某個資料夾，請將其新增為[額外目錄](https://code.claude.com/docs/zh-TW/permissions.md#working-directories)30 * 若要在沒有提示的情況下讀取某個資料夾，請將其新增為[額外目錄](https://code.claude.com/docs/zh-TW/permissions.md#working-directories)

31 * 若要在作業系統層級限制 Bash 命令，請開啟[沙箱機制](https://code.claude.com/docs/zh-TW/sandboxing.md#filesystem-isolation)31 * 若要在作業系統層級限制 Bash 命令，請開啟[沙箱機制](https://code.claude.com/docs/zh-TW/sandboxing.md#filesystem-isolation)

62* **信任驗證**：在互動式工作階段中，當您在尚未信任的資料夾中啟動 Claude Code 時，Claude Code 會顯示工作區信任對話框。專案 `.mcp.json` 中的伺服器有其各自的核准提示，而[專案範圍](https://code.claude.com/docs/zh-TW/mcp.md#project-scope)列出了會略過該提示的工作階段62* **信任驗證**：在互動式工作階段中，當您在尚未信任的資料夾中啟動 Claude Code 時，Claude Code 會顯示工作區信任對話框。專案 `.mcp.json` 中的伺服器有其各自的核准提示，而[專案範圍](https://code.claude.com/docs/zh-TW/mcp.md#project-scope)列出了會略過該提示的工作階段

63 * 注意：`-p` 工作階段不會顯示上述任何一種提示。[在您信任資料夾之前會執行什麼](https://code.claude.com/docs/zh-TW/permissions.md#what-runs-before-you-trust-a-folder)列出了儲存庫的檔案在該情況下可以執行的內容63 * 注意：`-p` 工作階段不會顯示上述任何一種提示。[在您信任資料夾之前會執行什麼](https://code.claude.com/docs/zh-TW/permissions.md#what-runs-before-you-trust-a-folder)列出了儲存庫的檔案在該情況下可以執行的內容

64 * 注意：當您直接在家目錄中啟動 Claude Code 時，信任接受僅在當前工作階段期間保持，不會寫入磁碟，因此提示在每次啟動時都會重新出現。沒有設定可以持久化它。改為從專案子目錄啟動 Claude Code，其中信任接受按目錄保存64 * 注意：當您直接在家目錄中啟動 Claude Code 時，信任接受僅在當前工作階段期間保持，不會寫入磁碟，因此提示在每次啟動時都會重新出現。沒有設定可以持久化它。改為從專案子目錄啟動 Claude Code，其中信任接受按目錄保存

65* **命令注入偵測**：在手動模式中，Claude Code 在執行無法完全分析的 Bash 命令之前會先詢問。針對命令一部分的允許規則（例如 `Bash(git *)`）不會略過該提示。[沙箱化的命令](https://code.claude.com/docs/zh-TW/permissions.md#how-permissions-interact-with-sandboxing)可以在沒有該提示的情況下執行65* **命令注入偵測**：在手動模式中，Claude Code 在執行無法完全分析的 Bash 命令之前會先詢問。針對命令一部分的允許規則（例如 `Bash(git *)`）不會略過該提示。在[自動允許模式](https://code.claude.com/docs/zh-TW/sandboxing.md#auto-allow-mode)中，[沙箱化的命令](https://code.claude.com/docs/zh-TW/permissions.md#how-permissions-interact-with-sandboxing)可以在沒有該提示的情況下執行

66* **故障關閉匹配**：在手動模式中，不匹配的命令預設需要批准66* **故障關閉匹配**：在手動模式中，不匹配的命令預設需要批准

67* **安全的憑證儲存**：API 金鑰和 token 在可用時儲存於 macOS Keychain 中。在 Linux 上，它們儲存在模式為 `0600` 的檔案中；在 Windows 上，則儲存在繼承您使用者設定檔目錄存取控制的檔案中。請參閱 [Credential Management](https://code.claude.com/docs/zh-TW/authentication.md#credential-management)67* **安全的憑證儲存**：API 金鑰和 token 在可用時儲存於 macOS Keychain 中。在 Linux 上，它們儲存在模式為 `0600` 的檔案中；在 Windows 上，則儲存在繼承您使用者設定檔目錄存取控制的檔案中。請參閱 [Credential Management](https://code.claude.com/docs/zh-TW/authentication.md#credential-management)

68 68 

1355 1355 

1356### `sandbox.autoAllowBashIfSandboxed`1356### `sandbox.autoAllowBashIfSandboxed`

1357 1357 

1358讓 Claude Code 在不顯示權限提示的情況下執行沙箱化的 Bash 命令。無法在沙箱中執行的命令仍會經過一般權限流程，且 `deny` 規則和限定內容的 `ask` 規則（例如 `Bash(git push *)`）仍然適用；單純的 `Bash` ask 規則則會對沙箱化命令略過。將其設為 `false` 可讓沙箱化命令也經過一般權限流程，`/sandbox` 的 **Mode** 分頁將此稱為一般權限模式。1358讓 Claude Code 在沒有權限提示的情況下執行沙箱中的 Bash 命令。無法在沙箱中執行的命令仍會經過一般的權限流程。`deny` 規則以及 `Bash(git push *)` 等限定內容的 `ask` 規則仍然適用，但單純的 `Bash` ask 規則會對沙箱中的命令略過。若要在受管設定中將其設為 `true`，請將其加入您[優先順序最高的受管來源](https://code.claude.com/docs/zh-TW/managed-settings.md#how-claude-code-combines-managed-sources)的 `sandbox` 區塊中。

1359 1359 

1360* **範圍**：[`Any file`](#scopes)1360* **範圍**：[`Any file`](#scopes)

1361* **類型**：布林值1361* **類型**：布林值

1362 * `true`：Claude Code 會在不顯示權限提示的情況下執行沙箱化的 Bash 命令，但[自動允許模式](https://code.claude.com/docs/zh-TW/sandboxing.md#auto-allow-mode)所述的情況除外；`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 會關閉自動允許1362 * `true`：Claude Code 會在不顯示權限提示的情況下執行沙箱化的 Bash 命令，但[自動允許模式](https://code.claude.com/docs/zh-TW/sandboxing.md#auto-allow-mode)所述的情況除外；`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 會關閉自動允許

1363 * `false`：沙箱化命令會經過一般權限流程，因此由您的允許規則和權限模式決定。`/sandbox` 的 **Mode** 分頁將此稱為一般權限模式1363 * `false`：沙箱化命令會經過一般權限流程，因此由您的允許規則和權限模式決定。`/sandbox` 的 **Mode** 分頁將此稱為一般權限模式

1364* **預設值**：`true`1364* **預設值**：`false`。在 v2.1.324 之前，預設值為 `true`

1365 1365 

1366以下設定會保持沙箱開啟，並讓沙箱化命令經過一般權限流程：1366若要保持沙箱開啟並在沒有權限提示的情況下執行沙箱中的命令，請在 `sandbox` 區塊中同時設定這兩個設定鍵：

1367 1367 

1368```json settings.json theme={null}1368```json settings.json theme={null}

1369{1369{

1370 "sandbox": {1370 "sandbox": {

1371 "enabled": true,1371 "enabled": true,

1372 "autoAllowBashIfSandboxed": false1372 "autoAllowBashIfSandboxed": true

1373 }1373 }

1374}1374}

1375```1375```

1653}1653}

1654```1654```

1655 1655 

1656關閉此層後，Claude Code 不會強制執行 `denyRead` 或 `credentials.files` 的 `deny` 項目，而 `credentials.envVars` 項目和已套用的 `mask` 項目則會繼續運作。[`autoAllowBashIfSandboxed`](#sandbox-autoallowbashifsandboxed) 的預設值仍為 `true`，因此若要繼續提示，請將其設為 `false`。關於可設定此鍵的完整來源清單以及關閉隔離後的變化，請參閱 [停用檔案系統隔離](https://code.claude.com/docs/zh-TW/sandboxing.md#disable-filesystem-isolation)。1656關閉此層時，Claude Code 不會強制執行 `denyRead` 或 `credentials.files` 的 `deny` 項目，而 `credentials.envVars` 項目與已套用的 `mask` 項目則會持續運作。關於可以設定此鍵之來源的完整清單，以及關閉隔離時會有哪些變化，請參閱[停用檔案系統隔離](https://code.claude.com/docs/zh-TW/sandboxing.md#disable-filesystem-isolation)。

1657 1657 

1658### `sandbox.ignoreViolations`1658### `sandbox.ignoreViolations`

1659 1659 

4870 4870 

4871### `agentPushNotifEnabled`4871### `agentPushNotifEnabled`

4872 4872 

4873允許 Claude 在決定值得傳送時，向您的手機傳送推播通知，例如當長時間任務完成時。在本機工作階段中，Claude 可以在 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 連線時傳送通知。在 `/config` 中顯示為 **Push when Claude decides**。當您在那裡變更此設定時，Claude Code 也會將該值儲存到您的帳戶。4873允許 Claude 在決定值得傳送時，向您的手機傳送推播通知，例如當長時間任務完成時。在本機工作階段中，Claude 可以在 [Remote Control](https://code.claude.com/docs/zh-TW/remote-control.md) 連線時傳送通知。在 `/config` 中顯示為 **Push when Claude decides**。

4874 4874 

4875* **範圍**：[`任何檔案`](#scopes)。Claude Code 也會讀取舊版本在 `~/.claude.json` 中留下的值。4875* **範圍**：[`任何檔案`](#scopes)。Claude Code 也會讀取舊版本在 `~/.claude.json` 中留下的值。

4876* **類型**：布林值4876* **類型**：布林值

4884}4884}

4885```4885```

4886 4886 

4887如果您在 [`claude remote-control`](https://code.claude.com/docs/zh-TW/remote-control#start-a-remote-control-session) 伺服器下執行工作階段，這些工作階段會遵循儲存在您帳戶中的值，而非此金鑰。若要變更該值，請在終端機中的 Claude Code 工作階段執行 `/config`，並將 **Push when Claude decides** 開啟或關閉。如果切換開關已顯示您想要的值，請先將其變更再改回，讓 Claude Code 將該值儲存到您的帳戶。4887僅設定此金鑰並不會讓您收到通知。若要設定通知，請依照[行動推播通知](https://code.claude.com/docs/zh-TW/remote-control.md#mobile-push-notifications)中的步驟操作。

4888 4888 

4889請參閱[行動推播通知](https://code.claude.com/docs/zh-TW/remote-control.md#mobile-push-notifications)。4889如果您在 [`claude remote-control`](https://code.claude.com/docs/zh-TW/remote-control#start-a-remote-control-session) 伺服器下執行工作階段，這些工作階段會遵循儲存在您帳戶中的值，而非此金鑰。若要變更該值，請在終端機中的 Claude Code 工作階段執行 `/config`，並將 **Push when Claude decides** 開啟或關閉。如果切換開關已顯示您想要的值，請先將其變更再改回，讓 Claude Code 將該值儲存到您的帳戶。

4890 4890 

4891### `awaySummaryEnabled`4891### `awaySummaryEnabled`

4892 4892 

5043}5043}

5044```5044```

5045 5045 

5046請參閱[行動推播通知](https://code.claude.com/docs/zh-TW/remote-control.md#mobile-push-notifications)。5046僅設定此金鑰並不會讓您收到通知。若要設定通知，請依照[行動推播通知](https://code.claude.com/docs/zh-TW/remote-control.md#mobile-push-notifications)中的步驟操作。

5047 5047 

5048### `preferredNotifChannel`5048### `preferredNotifChannel`

5049 5049 

5421 5421 

5422### `minimumVersion`5422### `minimumVersion`

5423 5423 

5424防止背景自動更新和 `claude update` 安裝低於此版本的任何版本，因此移至 `"stable"` 頻道不會從較新的 `"latest"` 組建中降級您。當您在 `/config` 中選擇在切換頻道時保持在目前版本時，Claude Code 會為您寫入此金鑰，並在您切換回 `"latest"` 時清除它。5424防止背景自動更新和 `claude update` 安裝低於您所設定版本的任何版本。當您在 `/config` 中切換頻道時選擇保持在目前版本，Claude Code 會為您寫入此金鑰。當您在 `/config` 中切換回 `"latest"` 時，Claude Code 會清除此金鑰。

5425 5425 

5426* **範圍**：[`Any file`](#scopes)。在受管設定中設定以固定組織範圍的最小值，使用者和專案設定無法降低。5426* **範圍**：[`Any file`](#scopes)。在受管設定中設定此金鑰，以固定使用者和專案設定無法覆寫的組織範圍最小值。

5427* **類型**：字串，版本號碼，例如 `"2.1.100"`；不是有效版本的值會被忽略5427* **類型**：字串，版本號碼，例如 `"2.1.323"`；不是有效版本的值會被忽略

5428* **預設**：未設定，因此更新可以安裝頻道提供的任何版本5428* **預設**：未設定，因此更新可以安裝頻道提供的任何版本

5429 5429 

5430此範例遵循穩定頻道，並拒絕安裝低於 2.1.100 的任何版本：5430此範例遵循穩定頻道，並拒絕安裝低於 2.1.323 的任何版本：

5431 5431 

5432```json settings.json theme={null}5432```json settings.json theme={null}

5433{5433{

5434 "autoUpdatesChannel": "stable",5434 "autoUpdatesChannel": "stable",

5435 "minimumVersion": "2.1.100"5435 "minimumVersion": "2.1.323"

5436}5436}

5437```5437```

5438 5438 

40>40>

41> **macOS、Linux、WSL：**41> **macOS、Linux、WSL：**

42>42>

43> ```bash theme={null}43> ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

44> curl -fsSL https://claude.ai/install.sh | bash44> curl -fsSL https://claude.ai/install.sh | bash

45> ```45> ```

46>46>

48>48>

49> **Windows PowerShell：**49> **Windows PowerShell：**

50>50>

51> ```powershell theme={null}51> ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

52> irm https://claude.ai/install.ps1 | iex52> irm https://claude.ai/install.ps1 | iex

53> ```53> ```

54>54>

55> **Windows CMD：**55> **Windows CMD：**

56>56>

57> ```batch theme={null}57> ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

58> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd58> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

59> ```59> ```

60>60>

72 72 

73> [tab] Homebrew73> [tab] Homebrew

74>74>

75> ```bash theme={null}75> ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

76> brew install --cask claude-code76> brew install --cask claude-code

77> ```77> ```

78>78>

84 84 

85> [tab] WinGet85> [tab] WinGet

86>86>

87> ```powershell theme={null}87> ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

88> winget install Anthropic.ClaudeCode88> winget install Anthropic.ClaudeCode

89> ```89> ```

90>90>

220}220}

221```221```

222 222 

223使用此設定時，即使穩定版本比您目前的版本舊，原生安裝仍會更新至該穩定版本。若要避免降級，請同時[固定最低版本](#pin-a-minimum-version)。

224 

223新推出的模型可能需要比穩定通道所提供版本更新的 Claude Code 版本。若要立即執行該模型，請切換至最新通道。225新推出的模型可能需要比穩定通道所提供版本更新的 Claude Code 版本。若要立即執行該模型，請切換至最新通道。

224 226 

225對於企業部署，您可以使用[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)在整個組織中強制執行一致的發行版本通道。227對於企業部署，您可以使用[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)在整個組織中強制執行一致的發行版本通道。

230 232 

231### 固定最低版本233### 固定最低版本

232 234 

233`minimumVersion` 設定建立一個下限。背景自動更新和 `claude update` 拒絕安裝低於此值的任何版本，因此如果您已經在較新的 `"latest"` 組建上，移至 `"stable"` 通道不會降級您。235若要將原生安裝移至 `"stable"` [發行版本通道](#configure-release-channel)而不降級，請將 [`minimumVersion`](https://code.claude.com/docs/zh-TW/settings-reference#minimumversion) 設定為您目前執行的版本。背景自動更新和 `claude update` 會拒絕安裝任何低於此最低版本的版本。

236 

237在 `/config` 中設定最低版本可讓 Claude Code 自動填入您目前的版本；在設定檔中設定則需自行輸入版本號：

234 238 

235透過 `/config` 從 `"latest"` 切換到 `"stable"` 會提示您保留目前版本或允許降級。選擇保留會將 `minimumVersion` 設定為該版本。切換回 `"latest"` 會清除它。239* **在 `/config` 中**：將**自動更新通道**切換為 stable，然後選取**保留目前版本**。如果您在 `/config` 中切換回 latest，Claude Code 會清除最低版本。

240* **在您的[設定檔](https://code.claude.com/docs/zh-TW/settings.md)中**：在 shell 中執行 `claude --version`，並將 `minimumVersion` 設定為輸出開頭的版本號。在同一次編輯中，將 `autoUpdatesChannel` 設定為 `"stable"`。

236 241 

237將其新增到您的 [settings.json 檔案](https://code.claude.com/docs/zh-TW/settings.md)以明確固定下限：242以下 `~/.claude/settings.json` 會將版本 2.1.323 上的安裝切換至 stable：

238 243 

239```json theme={null}244```json theme={null}

240{245{

241 "autoUpdatesChannel": "stable",246 "autoUpdatesChannel": "stable",

242 "minimumVersion": "2.1.100"247 "minimumVersion": "2.1.323"

243}248}

244```249```

245 250 

246在[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)中，這會強制執行使用者和專案設定無法覆蓋的組織範圍最低版本。251該安裝會保持在 2.1.323，直到穩定通道提供更新的版本為止。

252 

253#### 為您的組織設定版本限制

254 

255在[受管設定](https://code.claude.com/docs/zh-TW/managed-settings.md)中，`minimumVersion` 會強制執行使用者和專案設定無法覆寫的組織範圍最低版本。

247 256 

248`minimumVersion` 固定只會限制更新。若要讓 Claude Code 拒絕在版本範圍外啟動，請改為使用受管設定 `requiredMinimumVersion` 和 `requiredMaximumVersion`。更新也會遵守 `requiredMaximumVersion` 上限。請參閱[`requiredMinimumVersion`](https://code.claude.com/docs/zh-TW/settings-reference#requiredminimumversion)和[`requiredMaximumVersion`](https://code.claude.com/docs/zh-TW/settings-reference#requiredmaximumversion)。257`minimumVersion` 固定只會限制更新。若要讓 Claude Code 拒絕在版本範圍外啟動，請改為使用受管設定 `requiredMinimumVersion` 和 `requiredMaximumVersion`。更新也會遵守 `requiredMaximumVersion` 上限。請參閱[`requiredMinimumVersion`](https://code.claude.com/docs/zh-TW/settings-reference#requiredminimumversion)和[`requiredMaximumVersion`](https://code.claude.com/docs/zh-TW/settings-reference#requiredmaximumversion)。

249 258 

22 22 

23Claude Code 包含一組捆綁技能，例如 `/doctor`、`/code-review`、`/batch`、`/debug`、`/loop` 和 `/claude-api`。捆綁技能是基於提示的：它們為 Claude 提供詳細的指示，並讓它使用其工具來協調工作。大多數內建命令則直接執行固定邏輯。23Claude Code 包含一組捆綁技能，例如 `/doctor`、`/code-review`、`/batch`、`/debug`、`/loop` 和 `/claude-api`。捆綁技能是基於提示的：它們為 Claude 提供詳細的指示，並讓它使用其工具來協調工作。大多數內建命令則直接執行固定邏輯。

24 24 

25您可以透過輸入 `/` 後跟 skill 名稱的方式來調用隨附 skill。Claude 會在相關時自動調用某些隨附 skill；其他 skill（包括 [`/verify`](#run-and-verify-your-app)）只有在您調用時才會執行。25您可以透過輸入 `/` 後跟 skill 名稱的方式來調用隨附 skill。Claude 會在相關時自動調用某些隨附 skill。

26 26 

27大多數捆綁技能在每個工作階段中都可用。少數技能取決於特定功能：例如 `/workflow-authoring` 只有在[動態工作流程](https://code.claude.com/docs/zh-TW/workflows.md)啟用時才可用。27大多數捆綁技能在每個工作階段中都可用。少數技能取決於特定功能：例如 `/workflow-authoring` 只有在[動態工作流程](https://code.claude.com/docs/zh-TW/workflows.md)啟用時才可用。

28 28 

320 320 

321如果您建立在工作階段啟動時不存在的頂層技能目錄，請執行 [`/reload-skills`](https://code.claude.com/docs/zh-TW/commands#all-commands) 以拾取您放在那裡的技能。Claude Code 還沒有監視該目錄，因此在稍後每次變更後再次執行 `/reload-skills`。321如果您建立在工作階段啟動時不存在的頂層技能目錄，請執行 [`/reload-skills`](https://code.claude.com/docs/zh-TW/commands#all-commands) 以拾取您放在那裡的技能。Claude Code 還沒有監視該目錄，因此在稍後每次變更後再次執行 `/reload-skills`。

322 322 

323即時變更偵測僅涵蓋 `SKILL.md` 文字。對於也是[外掛程式](https://code.claude.com/docs/zh-TW/plugins/loading.md#plugins-shared-through-a-repository)的技能資料夾，`hooks/`、`.mcp.json`、`agents/` 和 `output-styles/` 的變更需要 `/reload-plugins` 才能生效。323> [!NOTE]

324>

325> 即時變更偵測涵蓋 `SKILL.md` 文字。對於同時也是[外掛](https://code.claude.com/docs/zh-TW/plugins/loading.md#plugins-shared-through-a-repository)的 skill 資料夾，`.mcp.json`、`agents/` 和 `output-styles/` 的變更需要 `/reload-plugins` 才能生效。`hooks/` 的變更也需要，但 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) 的模組檔案在[自行重新載入](https://code.claude.com/docs/zh-TW/env-vars.md)時除外。

324 326 

325### 移除技能327### 移除技能

326 328 

36>36>

37> 一個快速、唯讀的代理，針對搜尋和分析程式碼庫進行最佳化。37> 一個快速、唯讀的代理，針對搜尋和分析程式碼庫進行最佳化。

38>38>

39> * **Model**：主要對話的模型。當主要對話在 Fable 上執行時，Explore 的模型取決於您的連線方式：39> * **Model**：[主要對話](#which-model-a-nested-subagent-runs-on)的模型。當主要對話在 Fable 上執行時，Explore 會在 Opus 上執行或維持使用 Fable，取決於您的連線方式。

40> * 使用 Claude 訂閱、Anthropic Console 帳戶，或透過 `ANTHROPIC_BASE_URL` 連線的 [LLM 閘道](https://code.claude.com/docs/zh-TW/llm-gateway)時，Explore 會在 [`opus` 別名](https://code.claude.com/docs/zh-TW/model-config#model-aliases)所解析的 Opus 模型上執行。40> * 使用 Claude 訂閱、Anthropic Console 帳戶，或透過 `ANTHROPIC_BASE_URL` 連線的 [LLM 閘道](https://code.claude.com/docs/zh-TW/llm-gateway)時，Explore 會在 [`opus` 別名](https://code.claude.com/docs/zh-TW/model-config#model-aliases)所解析的 Opus 模型上執行。

41> * 在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[AWS 上的 Claude Platform](https://code.claude.com/docs/zh-TW/claude-platform-on-aws.md) 或 [Claude apps 閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway)上，Explore 會維持使用主要對話的模型。41> * 在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[AWS 上的 Claude Platform](https://code.claude.com/docs/zh-TW/claude-platform-on-aws.md) 或 [Claude apps 閘道](https://code.claude.com/docs/zh-TW/claude-apps-gateway)上，Explore 會維持使用 Fable。

42> * **Tools**：唯讀工具；Write 和 Edit 被拒絕42> * **Tools**：唯讀工具；Write 和 Edit 被拒絕

43> * **Purpose**：檔案發現、程式碼搜尋、程式碼庫探索43> * **Purpose**：檔案發現、程式碼搜尋、程式碼庫探索

44>44>

52>52>

53> 一個研究代理，在 [plan mode](https://code.claude.com/docs/zh-TW/permission-modes.md#analyze-before-you-edit-with-plan-mode) 期間使用，以在呈現計畫之前收集上下文。53> 一個研究代理，在 [plan mode](https://code.claude.com/docs/zh-TW/permission-modes.md#analyze-before-you-edit-with-plan-mode) 期間使用，以在呈現計畫之前收集上下文。

54>54>

55> * **Model**：繼承自主要對話，除非您設定 `CLAUDE_CODE_SUBAGENT_MODEL` 並[強制將其套用至每個 subagent](#run-every-subagent-on-one-model)55> * **Model**：繼承自[主要對話](#which-model-a-nested-subagent-runs-on)，除非您設定 `CLAUDE_CODE_SUBAGENT_MODEL` 並[強制將其套用至每個 subagent](#run-every-subagent-on-one-model)

56> * **Tools**：唯讀工具；Write 和 Edit 被拒絕56> * **Tools**：唯讀工具；Write 和 Edit 被拒絕

57> * **Purpose**：用於規劃的程式碼庫研究57> * **Purpose**：用於規劃的程式碼庫研究

58>58>

62>62>

63> 一個能力強大的代理，用於需要探索和行動的複雜多步驟任務。63> 一個能力強大的代理，用於需要探索和行動的複雜多步驟任務。

64>64>

65> * **Model**：如果您設定了 [`CLAUDE_CODE_SUBAGENT_MODEL`](#choose-a-model) 模型且沒有其他方式指派模型，則為該模型，否則為主要對話的模型；[選擇模型](#choose-a-model)說明完整順序，[在一個模型上執行每個 subagent](#run-every-subagent-on-one-model) 展示如何讓變數覆蓋這些來源65> * **Model**：預設為主要對話的模型，遵循[模型順序](#choose-a-model)

66> * **Tools**：[可供 subagents 使用](#available-tools)的每個工具66> * **Tools**：[可供 subagents 使用](#available-tools)的每個工具

67> * **Purpose**：複雜研究、多步驟操作、程式碼修改67> * **Purpose**：複雜研究、多步驟操作、程式碼修改

68>68>

346 346 

347### 選擇模型347### 選擇模型

348 348 

349`model` 欄位控制子代理使用的模型：349預設情況下，您定義的 subagent 會在與啟動它的對話相同的模型上執行。若要自行選擇其模型，請在其定義中將 [`model`](#supported-frontmatter-fields) 欄位設定為下列其中一個值：

350 350 

351* **模型別名**：使用可用別名之一：`sonnet`、`opus`、`haiku` 或 `fable`351* **模型別名**：`sonnet`、`opus`、`haiku` 或 `fable`

352* **完整模型 ID**：使用完整模型 ID，例如 `claude-opus-5-5` 或 `claude-sonnet-5`。接受與 `--model` 旗標相同的值352* **完整模型 ID**：[`--model`](https://code.claude.com/docs/zh-TW/cli-reference#cli-flags) 旗標接受的值，例如 `claude-opus-5-5` 或 `claude-sonnet-5`

353* **inherit**：使用與主對話相同的模型353* **`inherit`**：主對話的模型，或對[巢狀 subagent](#which-model-a-nested-subagent-runs-on) 而言，為產生它的 subagent 的模型

354 354 

355當 Claude 叫用 subagent 時，它也可以為該次叫用傳遞 `model` 參數。在 Agent 工具呼叫中，該參數接受模型別名：`sonnet`、`opus`、`haiku` 或 `fable`。Claude 無法在該呼叫中傳遞完整模型 ID 或 `inherit`。Claude Code 會依此順序解析 subagent 的模型：355當有多個來源設定模型時，Claude Code 會依此順序使用第一個：

356 356 

3571. 每次叫用 `model` 參數3571. 每次叫用的 `model` 參數，Claude 可在啟動 subagent 時傳遞它。在 Agent 工具呼叫中，該參數接受模型別名，而不接受完整模型 ID 或 `inherit`。

3582. 子代理定義的 `model` frontmatter，其中 `inherit` 選擇主對話的模型3582. subagent 定義中的 `model` 欄位，包括 `inherit`

3593. [`CLAUDE_CODE_SUBAGENT_MODEL`](https://code.claude.com/docs/zh-TW/model-config#environment-variables) 環境變數，當您將其設定為模型別名或模型 ID 時3593. [`CLAUDE_CODE_SUBAGENT_MODEL`](https://code.claude.com/docs/zh-TW/model-config#environment-variables) 環境變數

3604. 主對話的模型3604. 主對話的模型，或對巢狀 subagent 而言，為產生它的 subagent 的模型

361 361 

362如果已安裝的 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) 在其 [`agent.spawn`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#subagents) hook 中設定了模型，Claude Code 會以該模型取代每次叫用的參數。362如果 Claude 傳遞了別名，subagent 在[被繼續或收到後續訊息](#resume-subagents)時會保留該別名。如果已安裝的 [mod](https://code.claude.com/docs/zh-TW/plugins/mods/overview.md) 在其 [`agent.spawn`](https://code.claude.com/docs/zh-TW/plugins/mods/reference#subagents) hook 中設定了模型，Claude Code 會以該模型取代每次叫用的參數。

363 

364在兩種情況下，每次叫用參數或 frontmatter 中的家族別名（例如 `opus`）解析為主對話的模型，而不是[別名指向的版本](https://code.claude.com/docs/zh-TW/model-config.md#model-aliases)：

365 

366* **主對話的模型屬於該家族**：子代理在主對話的確切模型上執行，包括任何 `[1m]` 尾碼，因此它獲得與主對話相同的[擴展上下文](https://code.claude.com/docs/zh-TW/model-config.md#extended-context)視窗。

367* **Claude Code 無法判斷主對話的模型家族，在[Anthropic API 以外的提供者](https://code.claude.com/docs/zh-TW/third-party-integrations.md)上**：這可能發生在 Amazon Bedrock 上的[應用程式推論設定檔 ARN](https://code.claude.com/docs/zh-TW/amazon-bedrock.md#iam-configuration)，Claude Code 尚未解析為支援模型。此情況僅涵蓋 `opus` 別名，當您設定 [`ANTHROPIC_DEFAULT_OPUS_MODEL`](https://code.claude.com/docs/zh-TW/model-config#environment-variables) 時不適用，因為 `opus` 然後解析為您設定的模型。

368 

369`CLAUDE_CODE_SUBAGENT_MODEL` 中的別名一律解析為別名指向的版本，即使它指定的是主對話的家族。將此變數設定為 `inherit` 等同於不設定它。

370 363 

371單獨設定 `CLAUDE_CODE_SUBAGENT_MODEL` 不會改變內建 Explore 和 Plan 子代理執行的模型。若要改變它，請參閱[在一個模型上執行每個子代理](#run-every-subagent-on-one-model)。364單獨設定 `CLAUDE_CODE_SUBAGENT_MODEL` 不會改變內建 Explore 和 Plan 子代理執行的模型。若要改變它，請參閱[在一個模型上執行每個子代理](#run-every-subagent-on-one-model)。

372 365 

373在 v2.1.251 之前，`CLAUDE_CODE_SUBAGENT_MODEL` 在此順序中排在第一位，並覆蓋每次叫用參數和 frontmatter，包括 `model: inherit`。366#### 巢狀 subagent 在哪個模型上執行

374 367 

375Claude Code 根據您組織的 [`availableModels`](https://code.claude.com/docs/zh-TW/model-config#restrict-model-selection) 允許清單檢查每次叫用參數、frontmatter 和環境變數值。對於被阻止的值，它替換另一個模型：368預設情況下，您定義的[巢狀 subagent](#let-subagents-spawn-their-own-subagents) 會在其父項（即產生它的 subagent）的模型上執行。若要讓巢狀 subagent 在其他模型上執行，請將其 `model` 欄位設定為該模型。

376 369 

377* 當被阻止的值是家族別名（例如 `opus`）時，Claude Code 在允許清單允許的該家族的最新版本上執行子代理，遵循與 `/model` 相同的[替換規則和提供者範圍](https://code.claude.com/docs/zh-TW/model-config.md#restrict-model-selection)。在 v2.1.222 之前，Claude Code 也在被阻止的家族別名的繼承模型上執行子代理。370例如，假設您的主對話在 Opus 上執行，並在 Haiku 上啟動一個 reviewer subagent。預設情況下，當 reviewer 產生下列 subagent 時，它們會在 Haiku 而非 Opus 上執行：

378* 對於任何其他被阻止的值，在該替換不操作的提供者上，或當允許清單允許該家族的沒有版本時，Claude Code 改為在繼承模型上執行子代理。如果您設定 `CLAUDE_CODE_SUBAGENT_MODEL`，Claude Code 首先嘗試該模型，在這些相同的規則下。

379 371 

380在互動工作階段中，Claude Code 顯示警告，命名請求的模型和子代理執行的模型，用於任一替換。372* 具有 `model: inherit` 或沒有 `model` 欄位的 subagent

373* 內建的 Explore、Plan 和 general-purpose subagent

374* [分叉](#fork-the-current-conversation)

381 375 

382若要檢查 subagent 正在執行的模型，請執行 [`/tasks`](https://code.claude.com/docs/zh-TW/commands)。Claude Code 會在 subagent 的列上列出模型，並在有為該 subagent 設定 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)時一併顯示。需要 Claude Code v2.1.242 或更新版本。376在 plan mode 中，如果您將工作階段的模型設定為 [`opusplan`](https://code.claude.com/docs/zh-TW/model-config#opusplan-model-setting)，這些 subagent 會在 Opus 上執行；如果您將其設定為 `haiku`，則會在 Sonnet 上執行。

383 377 

384每次叫用的 `model` 參數也適用於 subagent [被繼續或收到後續訊息](#resume-subagents)時，因此 subagent 會保持在該模型上。378#### 檢查 subagent 的模型

385 379 

386從 v2.1.198 開始，子代理也繼承主對話的[擴展思考](https://code.claude.com/docs/zh-TW/model-config.md#extended-thinking)設定：如果思考在您的工作階段中開啟，它對子代理開啟，如果關閉，它保持關閉。沒有每個子代理思考設定。在 v2.1.198 之前，子代理執行時禁用擴展思考，無論主對話的設定如何。380若要檢查 subagent 正在執行的模型，請執行 [`/tasks`](https://code.claude.com/docs/zh-TW/commands)。Claude Code 會在 subagent 的列上列出模型，並在有為該 subagent 設定 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)時一併顯示。需要 Claude Code v2.1.242 或更新版本。

387 381 

388#### 在一個模型上執行每個子代理382#### 在一個模型上執行每個子代理

389 383 

390`CLAUDE_CODE_SUBAGENT_MODEL` 是預設值，因此子代理的定義或 Claude 傳遞的模型仍然優先於它。若要將一個模型應用於每個子代理、[隊友](https://code.claude.com/docs/zh-TW/agent-teams.md#specify-teammates-and-models) 和[工作流代理](https://code.claude.com/docs/zh-TW/workflows.md)，也設定 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` 為 `1`。需要 Claude Code v2.1.257 或更新版本。384若要將同一個模型套用於每個 subagent、[隊員](https://code.claude.com/docs/zh-TW/agent-teams.md#specify-teammates-and-models)和[工作流程 agent](https://code.claude.com/docs/zh-TW/workflows.md)，請將 `CLAUDE_CODE_SUBAGENT_MODEL` 設定為該模型，並將 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` 設定為 `1`。需要 Claude Code v2.1.257 或更新版本。

391 

392* 如果您設定兩個變數，子代理在 `CLAUDE_CODE_SUBAGENT_MODEL` 中的模型上執行。

393* 如果您只設定 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`，subagent 會在主對話的模型上執行，但內建的 Explore subagent 例外，它會在[內建 subagent 中為其列出的模型](#built-in-subagents)上執行。

394 385 

395例如，若要在 Haiku 上執行每個子代理，在[設定檔](https://code.claude.com/docs/zh-TW/settings.md)的 `env` 區塊中設定兩個變數：386例如，若要在 Haiku 上執行每個子代理，在[設定檔](https://code.claude.com/docs/zh-TW/settings.md)的 `env` 區塊中設定兩個變數：

396 387 

405 396 

406若要檢查設定是否生效，在子代理執行時執行 [`/tasks`](https://code.claude.com/docs/zh-TW/commands)。子代理的列顯示它執行的模型。397若要檢查設定是否生效，在子代理執行時執行 [`/tasks`](https://code.claude.com/docs/zh-TW/commands)。子代理的列顯示它執行的模型。

407 398 

408當 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` [開啟](https://code.claude.com/docs/zh-TW/env-vars.md)時，Claude Code 會忽略 subagent 定義中的 `model` 欄位，且 Claude 在啟動 subagent 時無法傳遞模型。以下 subagent 仍會在主對話的模型上執行：399當 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` [開啟](https://code.claude.com/docs/zh-TW/env-vars.md)時，Claude Code 會忽略 subagent 定義中的 `model` 欄位，且 Claude 在啟動 subagent 時無法傳遞模型。以下 subagent 仍會在其父對話的模型上執行：

409 400 

410* [分叉](#fork-the-current-conversation)401* [分叉](#fork-the-current-conversation)

411* [在子代理中執行的技能](https://code.claude.com/docs/zh-TW/skills.md#run-skills-in-a-subagent)，具有 `model: inherit`402* [在子代理中執行的技能](https://code.claude.com/docs/zh-TW/skills.md#run-skills-in-a-subagent)，具有 `model: inherit`

412 403 

404如果您只設定 `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`，subagent 會在主對話的模型上執行，但內建的 Explore subagent 例外，它會在[內建 subagent 中為其列出的模型](#built-in-subagents)上執行。

405 

406#### 模型別名選擇哪個版本

407 

408預設情況下，具有模型別名的 subagent 會在[該別名指向的版本](https://code.claude.com/docs/zh-TW/model-config.md#model-aliases)上執行。當 `model` 欄位或每次叫用參數中使用家族別名（例如 `opus`）時，subagent 在兩種情況下會在其父對話的模型上執行：

409 

410* **相同家族**：例如，如果您的主對話在 `claude-opus-4-7` 上執行，具有 `model: opus` 的 subagent 也會在該版本上執行。若要執行其他版本，請在 `model` 欄位中設定完整模型 ID。

411* **未知家族**：Claude Code 無法判斷父模型的家族，例如使用它[無法查詢](https://code.claude.com/docs/zh-TW/amazon-bedrock.md#iam-configuration)的 Amazon Bedrock ARN 時。此情況僅適用於[Anthropic API 以外之提供者](https://code.claude.com/docs/zh-TW/third-party-integrations.md)上的 `opus` 別名。若要選擇 Opus 版本，請設定 [`ANTHROPIC_DEFAULT_OPUS_MODEL`](https://code.claude.com/docs/zh-TW/model-config#environment-variables)。

412 

413#### 當允許清單封鎖 subagent 模型時

414 

415如果您組織的 [`availableModels`](https://code.claude.com/docs/zh-TW/model-config#restrict-model-selection) 允許清單封鎖了為 subagent 設定的模型，subagent 會在下列第一個適用的模型上執行：

416 

4171. 對於被封鎖的家族別名，在[支援此替換的提供者](https://code.claude.com/docs/zh-TW/model-config.md#restrict-model-selection)上，該家族中允許的最新版本

4182. `CLAUDE_CODE_SUBAGENT_MODEL` 中的模型（如果您有設定），並適用相同的規則

4193. 主對話的模型，或對巢狀 subagent 而言，為產生它的 subagent 的模型

420 

421對於互動工作階段中的頂層 subagent，會有警告列出請求的模型及其替代模型。若要執行特定模型，請將被封鎖的值改為允許清單允許的值。

422 

423### subagent 中的延伸思考

424 

425subagent 會繼承主對話的[延伸思考](https://code.claude.com/docs/zh-TW/model-config.md#extended-thinking)設定。沒有每個 subagent 個別的思考設定。

426 

413### 選擇 effort 等級427### 選擇 effort 等級

414 428 

415若要讓 subagent 以其自己的 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)執行，請在其定義中設定 [`effort`](#supported-frontmatter-fields) 欄位。429若要讓 subagent 以其自己的 [effort 等級](https://code.claude.com/docs/zh-TW/model-config.md#adjust-effort-level)執行，請在其定義中設定 [`effort`](#supported-frontmatter-fields) 欄位。

426 440 

427#### 可用工具441#### 可用工具

428 442 

429子代理繼承[內建工具](https://code.claude.com/docs/zh-TW/tools-reference.md)和主對話中可用的 MCP 工具，由兩個篩選器縮小：第一個從每個子代理移除工具的簡短列表，第二個減少在[背景中](#run-subagents-in-foreground-or-background)執行的子代理的內建工具集，這是預設值。在 macOS、Linux 和 WSL 上，當主對話沒有時，子代理也可以接收 Glob 和 Grep 工具，如[Glob 工具行為](https://code.claude.com/docs/zh-TW/tools-reference.md#glob-tool-behavior)下所述。[分叉](#fork-the-current-conversation)跳過兩個篩選器並接收主對話的確切工具池。第一個篩選器移除這些工具，即使在 `tools` 欄位中列出：443subagent 會繼承主對話中可用的[內建工具](https://code.claude.com/docs/zh-TW/tools-reference.md)和 MCP 工具，並經過兩個篩選器縮小範圍。第一個篩選器會從每個 subagent 移除一小份工具清單。第二個篩選器會縮減在[背景中](#run-subagents-in-foreground-or-background)執行之 subagent 的內建工具集，這是預設情況。

444 

445在 macOS、Linux 和 WSL 上，當主對話沒有 Glob 和 Grep 工具時，subagent 也可以取得它們，如 [Glob 工具行為](https://code.claude.com/docs/zh-TW/tools-reference.md#glob-tool-behavior)中所述。[分叉](#fork-the-current-conversation)會跳過兩個篩選器，並取得其父對話完全相同的工具池。第一個篩選器會移除這些工具，即使它們列在 `tools` 欄位中：

430 446 

431* `Agent`，當子代理在[深度限制](#let-subagents-spawn-their-own-subagents)時；在[分叉](#fork-the-current-conversation)中工具保持列出但返回錯誤而不是生成447* `Agent`，當子代理在[深度限制](#let-subagents-spawn-their-own-subagents)時；在[分叉](#fork-the-current-conversation)中工具保持列出但返回錯誤而不是生成

432* `AskUserQuestion`448* `AskUserQuestion`

1077 1093 

1078使用此值，您的 subagents 可以委派給自己的第二層，該第二層無法進一步委派。設定 `1` 以關閉巢狀。1094使用此值，您的 subagents 可以委派給自己的第二層，該第二層無法進一步委派。設定 `1` 以關閉巢狀。

1079 1095 

1080巢狀 subagent 的設定方式與頂層 subagent 相同，並從相同的 [範圍](#choose-the-subagent-scope) 解析。若要在巢狀開啟時防止某個 subagent 產生 subagents，例如應保持唯讀的審查者，請從其 [`tools`](#available-tools) 列表中省略 `Agent` 或將其新增到 `disallowedTools`。1096在與頂層 subagent 相同的 [範圍](#choose-the-subagent-scope) 中定義巢狀 subagent。預設情況下，您定義的巢狀 subagent 會在 [進行產生的 subagent 的模型](#which-model-a-nested-subagent-runs-on) 上執行。若要在巢狀開啟時防止某個 subagent 產生 subagents，例如應保持唯讀的審查者，請從其 [`tools`](#available-tools) 列表中省略 `Agent` 或將其新增到 `disallowedTools`。

1081 1097 

1082在終端機中，Claude Code 會在提示輸入下方的 subagent 面板中將巢狀 subagents 顯示為樹狀結構，並用 `(+N)` 計數標記面板中仍有後代的每一列。開啟一列以查看該 subagent 的同級和直接子代，以及返回到 `main` 的路徑。1098在終端機中，Claude Code 會在提示輸入下方的 subagent 面板中將巢狀 subagents 顯示為樹狀結構，並用 `(+N)` 計數標記面板中仍有後代的每一列。開啟一列以查看該 subagent 的同級和直接子代，以及返回到 `main` 的路徑。

1083 1099 

1221>1237>

1222> 當[agent 檢視已關閉](https://code.claude.com/docs/zh-TW/agent-view.md#turn-off-agent-view)時，`/subtask` 無法使用，`/fork` 會改為啟動 forked subagent；否則 `/fork` 會將整個工作階段複製到新的[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md#from-inside-a-session)。1238> 當[agent 檢視已關閉](https://code.claude.com/docs/zh-TW/agent-view.md#turn-off-agent-view)時，`/subtask` 無法使用，`/fork` 會改為啟動 forked subagent；否則 `/fork` 會將整個工作階段複製到新的[背景工作階段](https://code.claude.com/docs/zh-TW/agent-view.md#from-inside-a-session)。

1223 1239 

1224Fork 是一個 subagent，它繼承到目前為止的整個對話，而不是從頭開始。這會放棄 subagents 否則提供的輸入隔離：fork 看到與主工作階段相同的系統提示、工具、模型和訊息歷史記錄，因此您可以將側面任務交給它，而無需重新解釋情況。Fork 自己的工具呼叫仍然保持在您的對話之外，只有其最終結果返回，因此您的主要上下文視窗保持乾淨。當任何其他 subagent 需要太多背景才能有用時，或當您想從相同的起點並行嘗試多種方法時，使用 fork。1240Fork 是一個 subagent，它繼承到目前為止的整個對話，而不是從頭開始。當任何其他 subagent 需要太多背景資訊才能發揮作用時，或當您想從相同的起點並行嘗試多種方法時，請使用 fork。

1241 

1242* **輸入**：fork 看到的系統提示詞、工具、[模型](#which-model-a-nested-subagent-runs-on)和訊息歷史記錄與其父對話相同

1243* **輸出**：fork 自己的工具呼叫會保持在其父對話之外，只有其最終結果會傳回

1225 1244 

1226在 fork 模式開啟期間（預設即為開啟），Claude 可以自行啟動 fork。若要停止 fork，請參閱[關閉 fork 模式](#turn-fork-mode-on-or-off)。1245在 fork 模式開啟期間（預設即為開啟），Claude 可以自行啟動 fork。若要停止 fork，請參閱[關閉 fork 模式](#turn-fork-mode-on-or-off)。

1227 1246 

1257 1276 

1258### Forks 與其他 subagents 的區別1277### Forks 與其他 subagents 的區別

1259 1278 

1260Fork 繼承主工作階段在產生時擁有的所有內容。任何其他 subagent 從其定義開始新鮮。

1261 

1262| | Fork | 非 fork subagent |1279| | Fork | 非 fork subagent |

1263| :- | :- | :- |1280| :- | :- | :- |

1264| Context | 完整對話歷史記錄 | 新鮮上下文，帶有您傳遞的提示 |1281| Context | 完整對話歷史記錄 | 新鮮上下文，帶有您傳遞的提示 |

1265| 系統提示和工具 | 與主工作階段相同 | 來自 subagent 的[定義檔](#write-subagent-files)，[針對背景執行進行篩選](#available-tools) |1282| 系統提示詞和工具 | 與父對話相同 | 來自 subagent 的[定義檔](#write-subagent-files)，[針對背景執行進行篩選](#available-tools) |

1266| Model | 與主工作階段相同 | 來自 subagent 的 `model` 欄位 |1283| 模型 | 與[父對話](#which-model-a-nested-subagent-runs-on)相同 | 遵循 [subagent 模型順序](#choose-a-model) |

1267| Prompt cache | 與主工作階段共享 | 單獨的快取 |1284| 提示快取 | 與父對話共享 | 單獨的快取 |

1268 1285 

1269因為 fork 的系統提示詞和工具定義與父級相同，其第一個請求重複使用父級的[提示快取](https://code.claude.com/docs/zh-TW/prompt-caching.md#subagents-and-the-cache)。由於這種重複使用，對於需要相同上下文的任務，fork 的成本比新的 subagent 更低。1286因為 fork 的系統提示詞和工具定義與父級相同，其第一個請求重複使用父級的[提示快取](https://code.claude.com/docs/zh-TW/prompt-caching.md#subagents-and-the-cache)。由於這種重複使用，對於需要相同上下文的任務，fork 的成本比新的 subagent 更低。

1270 1287 

454* 在大型執行前檢查 `/model`，如果您通常為日常工作切換到較小的模型454* 在大型執行前檢查 `/model`，如果您通常為日常工作切換到較小的模型

455* 當您描述任務時，要求 Claude 為不需要最強模型的階段使用較小的模型455* 當您描述任務時，要求 Claude 為不需要最強模型的階段使用較小的模型

456 456 

457當您組織的 [`availableModels` 允許清單](https://code.claude.com/docs/zh-TW/model-config#restrict-model-selection)封鎖指令碼為 agent 請求的模型時，該 agent 會改為在替代模型上執行，並遵循與 [subagent 相同的替代規則](https://code.claude.com/docs/zh-TW/sub-agents.md#choose-a-model)。457當您組織的 [`availableModels` 允許清單](https://code.claude.com/docs/zh-TW/model-config#restrict-model-selection)封鎖指令碼為 agent 請求的模型時，該 agent 會改為在替代模型上執行，並遵循與 [subagent 相同的替代規則](https://code.claude.com/docs/zh-TW/sub-agents.md#when-an-allowlist-blocks-a-subagent-model)。

458 458 

459### 設定大小指南459### 設定大小指南

460 460 

232 232 

233使用預設 `"fresh"` [基礎](#choose-the-base-branch)，當以下所有條件都成立時，重新開啟的 worktree 會重設為儲存庫的預設分支，而不是在其舊的頂端繼續：233使用預設 `"fresh"` [基礎](#choose-the-base-branch)，當以下所有條件都成立時，重新開啟的 worktree 會重設為儲存庫的預設分支，而不是在其舊的頂端繼續：

234 234 

235* 它沒有未提交的變更或未追蹤的檔案。235* [沙箱](https://code.claude.com/docs/zh-TW/sandboxing.md#filesystem-isolation)未在您的工作階段中限制檔案寫入，且 worktree 和主要檢出的 `.claude` 設定檔都未啟用沙箱。

236* worktree 沒有未提交的變更或未追蹤的檔案。

236* 它仍在 Claude Code 為其建立的分支上。237* 它仍在 Claude Code 為其建立的分支上。

237* 它沒有自己的提交，或其拉取請求或合併請求已合併且其遠端分支已刪除。238* 它沒有自己的提交，或其拉取請求或合併請求已合併且其遠端分支已刪除。