Documentation — Spybara

agent-sdk/agent-loop.md +7 −7

Details

111SDK 包含與 Claude Code 相同的工具：111SDK 包含與 Claude Code 相同的工具：

112 112

113| 類別 | 工具 | 它們的作用 |113| 類別 | 工具 | 它們的作用 |

114| :------- | :-------------------------------------------- | :---------------------- |114| :------- | :---------------------------------------------------------- | :---------------------- |

116| **搜尋** | `Glob`、`Grep` | 按模式查找檔案、使用正規表達式搜尋內容 |116| **搜尋** | `Glob`、`Grep` | 按模式查找檔案、使用正規表達式搜尋內容 |

117| **執行** | `Bash` | 執行 shell 命令、指令碼、git 操作 |117| **執行** | `Bash` | 執行 shell 命令、指令碼、git 操作 |

118| **Web** | `WebSearch`、`WebFetch` | 搜尋網路、擷取和解析頁面 |118| **Web** | `WebSearch`、`WebFetch` | 搜尋網路、擷取和解析頁面 |

119| **探索** | `ToolSearch` | 動態查找和按需加載工具，而不是預先加載所有工具 |119| **探索** | `ToolSearch` | 動態查找和按需加載工具，而不是預先加載所有工具 |

120| **協調** | `Agent`、`Skill`、`AskUserQuestion`、`TodoWrite` | 生成子代理程式、呼叫技能、詢問使用者、追蹤任務 |120| **協調** | `Agent`、`Skill`、`AskUserQuestion`、`TaskCreate`、`TaskUpdate` | 生成子代理程式、呼叫技能、詢問使用者、追蹤任務 |

121 121

122除了內建工具，您還可以：122除了內建工具，您還可以：

123 123

197 197

198## 上下文視窗198## 上下文視窗

199 199

200上下文視窗是工作階段期間可用於 Claude 的資訊總量。它不會在工作階段內的回合之間重置。所有內容都會累積：系統提示、工具定義、對話歷史記錄、工具輸入和工具輸出。在回合之間保持相同的內容（系統提示、工具定義、CLAUDE.md）會自動 [提示快取](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)，這會減少重複前綴的成本和延遲。200上下文視窗是工作階段期間可用於 Claude 的資訊總量。它不會在工作階段內的回合之間重置。所有內容都會累積：系統提示、工具定義、對話歷史記錄、工具輸入和工具輸出。在回合之間保持相同的內容（系統提示、工具定義、CLAUDE.md）會自動進行 [提示快取](https://platform.claude.com/docs/zh-TW/build-with-claude/prompt-caching)，這會減少重複前綴的成本和延遲。

201 201

202### 什麼消耗上下文202### 什麼消耗上下文

203 203

204以下是每個元件如何影響 SDK 中上下文的方式：204以下是每個元件如何影響 SDK 中上下文的方式：

205 205

206| 來源 | 何時加載 | 影響 |206| 來源 | 何時加載 | 影響 |

207| :--------------- | :------------------------------------------------------------------ | :----------------------------------------------------------------------------- |207| :--------------- | :------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

213 213

244長時間執行代理程式的幾個策略：244長時間執行代理程式的幾個策略：

245 245

246* **為子任務使用子代理程式。** 每個子代理程式以新鮮的對話開始（沒有先前的訊息歷史記錄，儘管它確實加載自己的系統提示和專案級上下文，如 CLAUDE.md）。它看不到父級的回合，只有其最終回應作為工具結果返回給父級。主代理程式的上下文增長該摘要，而不是完整的子任務成績單。請參閱 [子代理程式繼承什麼](/zh-TW/agent-sdk/subagents#what-subagents-inherit) 以了解詳細資訊。246* **為子任務使用子代理程式。** 每個子代理程式以新鮮的對話開始（沒有先前的訊息歷史記錄，儘管它確實加載自己的系統提示和專案級上下文，如 CLAUDE.md）。它看不到父級的回合，只有其最終回應作為工具結果返回給父級。主代理程式的上下文增長該摘要，而不是完整的子任務成績單。請參閱 [子代理程式繼承什麼](/zh-TW/agent-sdk/subagents#what-subagents-inherit) 以了解詳細資訊。

247* **選擇性地使用工具。** 每個工具定義都佔用上下文空間。在 [`AgentDefinition`](/zh-TW/agent-sdk/subagents#agentdefinition-configuration) 上使用 `tools` 欄位將子代理程式限制在它們需要的最小集合，並使用 [MCP 工具搜尋](/zh-TW/agent-sdk/mcp#mcp-tool-search) 按需加載工具，而不是預先加載所有工具。247* **選擇性地使用工具。** 每個工具定義都佔用上下文空間。在 [`AgentDefinition`](/zh-TW/agent-sdk/subagents#agentdefinition-configuration) 上使用 `tools` 欄位將子代理程式限制在它們需要的最小集合。

248* **監視 MCP 伺服器成本。** 每個 MCP 伺服器將其所有工具架構添加到每個請求。具有許多工具的幾個伺服器可以在代理程式執行任何工作之前消耗大量上下文。`ToolSearch` 工具可以透過按需加載工具而不是預先加載所有工具來幫助。請參閱 [MCP 工具搜尋](/zh-TW/agent-sdk/mcp#mcp-tool-search) 以了解配置。248* **監視 MCP 伺服器成本。** [MCP 工具搜尋](/zh-TW/agent-sdk/mcp#mcp-tool-search) 預設延遲 MCP 工具架構，並按需加載它們。當工具搜尋關閉、在 Vertex AI 上或在非第一方 `ANTHROPIC_BASE_URL` 後面時，每個 MCP 伺服器將其所有工具架構添加到每個請求，因此具有許多工具的幾個伺服器可以在代理程式執行任何工作之前消耗大量上下文。

249* **為常規任務使用較低的努力。** 為僅需要讀取檔案或列出目錄的代理程式設定 [努力](#effort-level) 為 `"low"`。這會減少代幣使用量和成本。249* **為常規任務使用較低的努力。** 為僅需要讀取檔案或列出目錄的代理程式設定 [努力](#effort-level) 為 `"low"`。這會減少代幣使用量和成本。

250 250

251有關每個功能上下文成本的詳細分解，請參閱 [了解上下文成本](/zh-TW/features-overview#understand-context-costs)。251有關每個功能上下文成本的詳細分解，請參閱 [了解上下文成本](/zh-TW/features-overview#understand-context-costs)。

agent-sdk/python.md +35 −14

Details

19### 快速比較19### 快速比較

20 20

21| 功能 | `query()` | `ClaudeSDKClient` |21| 功能 | `query()` | `ClaudeSDKClient` |

~~22| :------------------ | :------------ | :---------------- |~~22| :------------------ | :----------------------------------------- | :---------------- |

26| **Streaming Input** | ✅ 支援 | ✅ 支援 |26| **Streaming Input** | ✅ 支援 | ✅ 支援 |

27| **Interrupts** | ❌ 不支援 | ✅ 支援 |27| **Interrupts** | ❌ 不支援 | ✅ 支援 |

28| **Hooks** | ✅ 支援 | ✅ 支援 |28| **Hooks** | ✅ 支援 | ✅ 支援 |

29| **Custom Tools** | ✅ 支援 | ✅ 支援 |29| **Custom Tools** | ✅ 支援 | ✅ 支援 |

32 32

~~33### 何時使用 `query()`（每次新 session）~~33### 何時使用 `query()`（一次性任務）

34 34

35**最適合：**35**最適合：**

36 36

53 53

54### `query()`54### `query()`

55 55

~~56為每次與 Claude Code 的互動建立新 session。返回一個非同步迭代器，在消息到達時產生消息。每次呼叫 `query()` 都會重新開始，不記得先前的互動。~~56為每次與 Claude Code 的互動建立新 session。返回一個非同步迭代器，在消息到達時產生消息。每次呼叫 `query()` 都會重新開始，不記得先前的互動，除非您傳遞 `continue_conversation=True` 或在 [`ClaudeAgentOptions`](#claudeagentoptions) 中傳遞 `resume`。請參閱 [Sessions](/zh-TW/agent-sdk/sessions)。

57 57

58```python theme={null}58```python theme={null}

59async def query(59async def query(

790 plugins: list[SdkPluginConfig] = field(default_factory=list)790 plugins: list[SdkPluginConfig] = field(default_factory=list)

791 max_thinking_tokens: int | None = None # Deprecated: use thinking instead791 max_thinking_tokens: int | None = None # Deprecated: use thinking instead

792 thinking: ThinkingConfig | None = None792 thinking: ThinkingConfig | None = None

793 effort: Literal["low", "medium", "high", "xhigh", "max"] | None = None793 effort: EffortLevel | None = None

794 enable_file_checkpointing: bool = False794 enable_file_checkpointing: bool = False

795 session_store: SessionStore | None = None795 session_store: SessionStore | None = None

796 session_store_flush: SessionStoreFlushMode = "batched"796 session_store_flush: SessionStoreFlushMode = "batched"

843 843

1039 initialPrompt: str | None = None1039 initialPrompt: str | None = None

1040 maxTurns: int | None = None1040 maxTurns: int | None = None

1041 background: bool | None = None1041 background: bool | None = None

1042 effort: Literal["low", "medium", "high", "xhigh", "max"] | int | None = None1042 effort: EffortLevel | int | None = None

1043 permissionMode: PermissionMode | None = None1043 permissionMode: PermissionMode | None = None

1044```1044```

1045 1045

1056| `initialPrompt` | 否 | 當此代理作為主執行緒代理執行時自動提交為第一個使用者轉 |1056| `initialPrompt` | 否 | 當此代理作為主執行緒代理執行時自動提交為第一個使用者轉 |

1057| `maxTurns` | 否 | 代理停止前的最大代理轉數 |1057| `maxTurns` | 否 | 代理停止前的最大代理轉數 |

1058| `background` | 否 | 當呼叫時將此代理作為非阻塞背景任務執行 |1058| `background` | 否 | 當呼叫時將此代理作為非阻塞背景任務執行 |

1059| `effort` | 否 | 此代理的推理努力級別。接受命名級別或整數 |1059| `effort` | 否 | 此代理的推理努力級別。接受命名級別或整數。見 [`EffortLevel`](#effortlevel) |

1060| `permissionMode` | 否 | 此代理內 tool 執行的權限模式。見 [`PermissionMode`](#permissionmode) |1060| `permissionMode` | 否 | 此代理內 tool 執行的權限模式。見 [`PermissionMode`](#permissionmode) |

1061 1061

1062<Note>1062<Note>

1077]1077]

1078```1078```

1079 1079

1080### `EffortLevel`

1081

1082用於指導思考深度的努力級別。

1083

1084```python theme={null}

1085EffortLevel = Literal[

1086 "low", # Minimal thinking, fastest responses

1087 "medium", # Moderate thinking

1088 "high", # Deep reasoning

1089 "xhigh", # Extended reasoning (Opus 4.7 only; falls back to "high" on other models)

1090 "max", # Maximum effort

1091]

1092```

1093

1080### `CanUseTool`1094### `CanUseTool`

1081 1095

1082tool 權限回呼函數的類型別名。1096tool 權限回呼函數的類型別名。

1224控制擴展思考行為。三個配置的聯合：1238控制擴展思考行為。三個配置的聯合：

1225 1239

1226```python theme={null}1240```python theme={null}

1241ThinkingDisplay = Literal["summarized", "omitted"]

1242

1243

1227class ThinkingConfigAdaptive(TypedDict):1244class ThinkingConfigAdaptive(TypedDict):

1228 type: Literal["adaptive"]1245 type: Literal["adaptive"]

1246 display: NotRequired[ThinkingDisplay]

1229 1247

1230 1248

1231class ThinkingConfigEnabled(TypedDict):1249class ThinkingConfigEnabled(TypedDict):

1232 type: Literal["enabled"]1250 type: Literal["enabled"]

1233 budget_tokens: int1251 budget_tokens: int

1252 display: NotRequired[ThinkingDisplay]

1234 1253

1235 1254

1236class ThinkingConfigDisabled(TypedDict):1255class ThinkingConfigDisabled(TypedDict):

1241```1260```

1242 1261

1243| 變體 | 欄位 | 描述 |1262| 變體 | 欄位 | 描述 |

1244| :--------- | :---------------------- | :--------------- |1263| :--------- | :--------------------------------- | :--------------- |

1248 1267

1268可選的 `display` 欄位控制思考文本是否返回為 `"summarized"` 或 `"omitted"`。在 Claude Opus 4.7 及更新版本上，API 預設為 `"omitted"`，因此設定 `"summarized"` 以在 [`ThinkingBlock`](#thinkingblock) 輸出中接收思考內容。

1269

1249因為這些是 `TypedDict` 類別，它們在執行時是純字典。要麼將它們構造為字典字面量，要麼呼叫類別作為構造函數；兩者都產生 `dict`。使用 `config["budget_tokens"]` 存取欄位，而不是 `config.budget_tokens`：1270因為這些是 `TypedDict` 類別，它們在執行時是純字典。要麼將它們構造為字典字面量，要麼呼叫類別作為構造函數；兩者都產生 `dict`。使用 `config["budget_tokens"]` 存取欄位，而不是 `config.budget_tokens`：

1250 1271

1251```python theme={null}1272```python theme={null}

2177 hookEventName: Literal["PostToolUse"]2198 hookEventName: Literal["PostToolUse"]

2178 additionalContext: NotRequired[str]2199 additionalContext: NotRequired[str]

2179 updatedToolOutput: NotRequired[Any]2200 updatedToolOutput: NotRequired[Any]

2180 updatedMCPToolOutput: NotRequired[Any]2201 updatedMCPToolOutput: NotRequired[Any] # Deprecated: use updatedToolOutput, which works for all tools

2181 2202

2182 2203

2183class PostToolUseFailureHookSpecificOutput(TypedDict):2204class PostToolUseFailureHookSpecificOutput(TypedDict):

2646**Tool 名稱：** `TodoWrite`2667**Tool 名稱：** `TodoWrite`

2647 2668

2648<Note>2669<Note>

2649 `TodoWrite` 已棄用，將在未來版本中移除。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。設定 `CLAUDE_CODE_ENABLE_TASKS=1` 以選擇加入。見 [遷移到 Task tools](/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools) 以了解如何監視程式碼變更。2670 自 Claude Code v2.1.142 起，`TodoWrite` 預設為停用。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。見 [遷移到 Task tools](/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools) 以更新您的監視程式碼，或設定 `CLAUDE_CODE_ENABLE_TASKS=0` 以還原為 `TodoWrite`。

2650</Note>2671</Note>

2651 2672

2652**輸入：**2673**輸入：**

agent-sdk/sessions.md +3 −3

Details

46 46

47### Python：`ClaudeSDKClient`47### Python：`ClaudeSDKClient`

48 48

49[`ClaudeSDKClient`](/zh-TW/agent-sdk/python#claudesdkclient) 在內部處理 session ID。每次呼叫 `client.query()` 都會自動繼續相同的 session。呼叫 [`client.receive_response()`](/zh-TW/agent-sdk/python#claudesdkclient) 以迭代當前查詢的訊息。客戶端必須用作非同步上下文管理器。49[`ClaudeSDKClient`](/zh-TW/agent-sdk/python#claudesdkclient) 在內部處理 session ID。每次呼叫 `client.query()` 都會自動繼續相同的 session。呼叫 [`client.receive_response()`](/zh-TW/agent-sdk/python#claudesdkclient) 以迭代當前查詢的訊息。客戶端通常用作非同步上下文管理器。

50 50

51此示例針對相同的 `client` 運行兩個查詢。第一個要求代理分析一個模組；第二個要求它重構該模組。因為兩個呼叫都通過相同的客戶端實例進行，第二個查詢具有來自第一個的完整上下文，無需任何明確的 `resume` 或 session ID：51此示例針對相同的 `client` 運行兩個查詢。第一個要求代理分析一個模組；第二個要求它重構該模組。因為兩個呼叫都通過相同的客戶端實例進行，第二個查詢具有來自第一個的完整上下文，無需任何明確的 `resume` 或 session ID：

52 52

100 100

101### TypeScript：`continue: true`101### TypeScript：`continue: true`

102 102

103穩定的 TypeScript SDK（整個文檔中使用的 `query()` 函數，有時稱為 V1）沒有像 Python 的 `ClaudeSDKClient` 那樣的 session 持有客戶端物件。相反，在每個後續 `query()` 呼叫上傳遞 `continue: true`，SDK 會在當前目錄中拾取最近的 session。無需 ID 追蹤。103TypeScript SDK 沒有像 Python 的 `ClaudeSDKClient` 那樣的 session 持有客戶端物件。相反，在每個後續 `query()` 呼叫上傳遞 `continue: true`，SDK 會在當前目錄中拾取最近的 session。無需 ID 追蹤。

104 104

105此示例進行兩個單獨的 `query()` 呼叫。第一個創建一個新 session；第二個設定 `continue: true`，這告訴 SDK 在磁碟上找到並恢復最近的 session。代理具有來自第一個呼叫的完整上下文：105此示例進行兩個單獨的 `query()` 呼叫。第一個創建一個新 session；第二個設定 `continue: true`，這告訴 SDK 在磁碟上找到並恢復最近的 session。代理具有來自第一個呼叫的完整上下文：

106 106

132```132```

133 133

134<Note>134<Note>

135 實驗性的 [V2 session API](/zh-TW/agent-sdk/typescript-v2-preview)（提供了 `createSession()` 與 `send` / `stream` 模式）已棄用。改用 V1 `query()` 函數和本頁面上描述的 session 選項。135 實驗性的 [V2 session API](/zh-TW/agent-sdk/typescript-v2-preview)（提供了 `createSession()` 與 `send` / `stream` 模式）已在 TypeScript Agent SDK 0.3.142 中移除。改用 `query()` 函數和本頁面上描述的 session 選項。

136</Note>136</Note>

137 137

138## 使用 session 選項與 `query()`138## 使用 session 選項與 `query()`

agent-sdk/todo-tracking.md +69 −4

Details

8 8

9待辦事項追蹤提供了一種結構化的方式來管理任務並向用戶顯示進度。Claude Agent SDK 包含內置的待辦事項功能，可幫助組織複雜的工作流程並讓用戶了解任務進度。9待辦事項追蹤提供了一種結構化的方式來管理任務並向用戶顯示進度。Claude Agent SDK 包含內置的待辦事項功能，可幫助組織複雜的工作流程並讓用戶了解任務進度。

10 10

11<Note>

12 自 TypeScript Agent SDK 0.3.142 和 Claude Code v2.1.142 起，會話使用結構化的 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 和 `TaskList`，而不是 `TodoWrite`。請參閱[遷移到 Task 工具](#migrate-to-task-tools)以了解監控代碼如何變更。此頁面上的範例設置 `CLAUDE_CODE_ENABLE_TASKS=0` 以繼續為尚未遷移的會話顯示 `TodoWrite`。

13</Note>

11### 待辦事項生命週期15### 待辦事項生命週期

12 16

13待辦事項遵循可預測的生命週期：17待辦事項遵循可預測的生命週期：

36 40

37 for await (const message of query({41 for await (const message of query({

38 prompt: "Optimize my React app performance and track progress with todos",42 prompt: "Optimize my React app performance and track progress with todos",

~~39 options: { maxTurns: 15 }~~43 // Re-enable TodoWrite, which this example monitors. Without it, the SDK uses

44 // Task tools instead and these tool_use blocks never appear.

45 options: { maxTurns: 15, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }

40 })) {46 })) {

41 // Todo updates are reflected in the message stream47 // Todo updates are reflected in the message stream

42 if (message.type === "assistant") {48 if (message.type === "assistant") {

61 67

62 async for message in query(68 async for message in query(

63 prompt="Optimize my React app performance and track progress with todos",69 prompt="Optimize my React app performance and track progress with todos",

~~64 options=ClaudeAgentOptions(max_turns=15),~~70 # Re-enable TodoWrite, which this example monitors. Without it, the SDK uses

71 # Task tools instead and these tool_use blocks never appear.

72 options=ClaudeAgentOptions(max_turns=15, env={"CLAUDE_CODE_ENABLE_TASKS": "0"}),

65 ):73 ):

66 # Todo updates are reflected in the message stream74 # Todo updates are reflected in the message stream

67 if isinstance(message, AssistantMessage):75 if isinstance(message, AssistantMessage):

112 async trackQuery(prompt: string) {120 async trackQuery(prompt: string) {

113 for await (const message of query({121 for await (const message of query({

114 prompt,122 prompt,

115 options: { maxTurns: 20 }123 // Re-enable TodoWrite, which this tracker watches for.

124 options: { maxTurns: 20, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }

116 })) {125 })) {

117 if (message.type === "assistant") {126 if (message.type === "assistant") {

118 for (const block of message.message.content) {127 for (const block of message.message.content) {

167 print(f"{i + 1}. {icon} {text}")176 print(f"{i + 1}. {icon} {text}")

168 177

169 async def track_query(self, prompt: str):178 async def track_query(self, prompt: str):

170 async for message in query(prompt=prompt, options=ClaudeAgentOptions(max_turns=20)):179 async for message in query(

180 prompt=prompt,

181 # Re-enable TodoWrite, which this tracker watches for.

182 options=ClaudeAgentOptions(max_turns=20, env={"CLAUDE_CODE_ENABLE_TASKS": "0"}),

183 ):

171 if isinstance(message, AssistantMessage):184 if isinstance(message, AssistantMessage):

172 for block in message.content:185 for block in message.content:

173 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":186 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

181 ```194 ```

182</CodeGroup>195</CodeGroup>

183 196

197## 遷移到 Task 工具

198

199Task 工具將單個 `TodoWrite` 呼叫分割為每個新項目的 `TaskCreate` 和每個狀態變更的 `TaskUpdate`，並提供 `TaskList` 和 `TaskGet` 供模型讀回當前清單。您的監控代碼仍然檢查助手流中的 `tool_use` 區塊，但維護一個由任務 ID 鍵入的映射，而不是在每次呼叫時替換整個清單。{/* min-version: 2.1.142 */}Task 工具是 TypeScript Agent SDK 0.3.142 和 Claude Code v2.1.142 起的預設值，因此不需要 `options.env` 變更。

200

201| 使用 `TodoWrite` | 使用 Task 工具 |

202| -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

203| 一個工具呼叫重寫完整的 `todos` 陣列 | `TaskCreate` 新增一個項目，`TaskUpdate` 按 `taskId` 修補一個項目 |

204| 匹配 `block.name === "TodoWrite"` | 匹配 `block.name === "TaskCreate"` 或 `"TaskUpdate"` |

205| 項目形狀：`{ content, status, activeForm }` | `TaskCreate` 輸入：`{ subject, description, activeForm?, metadata? }`。`TaskUpdate` 輸入：`{ taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }`。`status` 是 `"pending"`、`"in_progress"` 或 `"completed"`；設置 `status: "deleted"` 以刪除 |

206| 直接呈現 `block.input.todos` | 跨呼叫累積項目，或從 `TaskList` 工具結果讀取快照 |

207

208指派的任務 ID 不在 `TaskCreate` 輸入中。它在匹配的 `tool_result` 中作為 `{ task: { id, subject } }` 返回，因此從結果區塊捕獲它以鍵入您的映射。以下範例顯示了對[監控待辦事項變更](#monitoring-todo-changes)迴圈的最小變更。要呈現完整清單，請在流中監視 `TaskList` 工具結果或將 `TaskCreate` 結果和 `TaskUpdate` 輸入累積到映射中：

209

210<CodeGroup>

211 ```typescript TypeScript theme={null}

212 import { query } from "@anthropic-ai/claude-agent-sdk";

213

214 for await (const message of query({

215 prompt: "Optimize my React app performance",

216 })) {

217 if (message.type !== "assistant") continue;

218 for (const block of message.message.content) {

219 if (block.type !== "tool_use") continue;

220 if (block.name === "TaskCreate") {

221 const input = block.input as { subject: string };

222 console.log(`+ ${input.subject}`);

223 } else if (block.name === "TaskUpdate") {

224 const input = block.input as { taskId: string; status?: string };

225 if (input.status) console.log(` ${input.taskId} -> ${input.status}`);

226 }

227 }

228 }

229 ```

230

231 ```python Python theme={null}

232 from claude_agent_sdk import query, AssistantMessage, ToolUseBlock

233

234 async for message in query(

235 prompt="Optimize my React app performance",

236 ):

237 if not isinstance(message, AssistantMessage):

238 continue

239 for block in message.content:

240 if not isinstance(block, ToolUseBlock):

241 continue

242 if block.name == "TaskCreate":

243 print(f"+ {block.input['subject']}")

244 elif block.name == "TaskUpdate" and block.input.get("status"):

245 print(f" {block.input['taskId']} -> {block.input['status']}")

246 ```

247</CodeGroup>

248

184## 相關文檔249## 相關文檔

185 250

186* [TypeScript SDK 參考](/zh-TW/agent-sdk/typescript)251* [TypeScript SDK 參考](/zh-TW/agent-sdk/typescript)

agent-sdk/typescript.md +12 −8

Details

418| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined`（最小提示） | 系統提示配置。傳遞字符串以獲得自定義提示，或 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系統提示。使用預設對象形式時，添加 `append` 以使用其他指令擴展它，並設置 `excludeDynamicSections: true` 以將每個會話上下文移到第一個用戶消息中以獲得 [跨機器更好的提示緩存重用](/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |418| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined`（最小提示） | 系統提示配置。傳遞字符串以獲得自定義提示，或 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系統提示。使用預設對象形式時，添加 `append` 以使用其他指令擴展它，並設置 `excludeDynamicSections: true` 以將每個會話上下文移到第一個用戶消息中以獲得 [跨機器更好的提示緩存重用](/zh-TW/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

419| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 支持的模型為 `{ type: 'adaptive' }` | 控制 Claude 的思考/推理行為。見 [`ThinkingConfig`](#thinkingconfig) 了解選項 |419| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 支持的模型為 `{ type: 'adaptive' }` | 控制 Claude 的思考/推理行為。見 [`ThinkingConfig`](#thinkingconfig) 了解選項 |

1847創建和管理結構化任務列表以跟蹤進度。1847創建和管理結構化任務列表以跟蹤進度。

1848 1848

1849<Note>1849<Note>

1850 `TodoWrite` 已棄用，將在未來版本中移除。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。設置 `CLAUDE_CODE_ENABLE_TASKS=1` 以選擇加入。見 [遷移到 Task 工具](/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools) 了解如何監視代碼更改。1850 自 TypeScript Agent SDK 0.3.142 起，`TodoWrite` 預設為禁用。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。見 [遷移到 Task 工具](/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools) 更新您的監視代碼，或設置 `CLAUDE_CODE_ENABLE_TASKS=0` 以恢復為 `TodoWrite`。

1851</Note>1851</Note>

1852 1852

1853### TaskCreate1853### TaskCreate

2344返回之前和更新的任務列表。2344返回之前和更新的任務列表。

2345 2345

2346<Note>2346<Note>

2347 `TodoWrite` 已棄用，將在未來版本中移除。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。設置 `CLAUDE_CODE_ENABLE_TASKS=1` 以選擇加入。請參閱[遷移到 Task 工具](/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools)以了解如何監視代碼更改。2347 自 TypeScript Agent SDK 0.3.142 起，`TodoWrite` 預設為禁用。改用 `TaskCreate`、`TaskGet`、`TaskUpdate` 和 `TaskList`。請參閱[遷移到 Task 工具](/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools)以更新您的監視代碼，或設置 `CLAUDE_CODE_ENABLE_TASKS=0` 以恢復為 `TodoWrite`。

2348</Note>2348</Note>

2349 2349

2350### TaskCreate2350### TaskCreate

2433};2433};

2434```2434```

2435 2435

2436返回退出規劃模式後的計劃狀態。2436返回退出 Plan Mode 後的計劃狀態。

2437 2437

2438### ListMcpResources2438### ListMcpResources

2439 2439

2739控制 Claude 的思考/推理行為。優先於已棄用的 `maxThinkingTokens`。2739控制 Claude 的思考/推理行為。優先於已棄用的 `maxThinkingTokens`。

2740 2740

2741```typescript theme={null}2741```typescript theme={null}

2742type ThinkingDisplay = "summarized" | "omitted";

2743

2742type ThinkingConfig =2744type ThinkingConfig =

2743 | { type: "adaptive" } // 模型確定何時以及多少推理（Opus 4.6+）2745 | { type: "adaptive"; display?: ThinkingDisplay } // 模型確定何時以及多少推理（Opus 4.6+）

2744 | { type: "enabled"; budgetTokens?: number } // 固定思考令牌預算2746 | { type: "enabled"; budgetTokens?: number; display?: ThinkingDisplay } // 固定思考令牌預算

2745 | { type: "disabled" }; // 無擴展思考2747 | { type: "disabled" }; // 無擴展思考

2746```2748```

2747 2749

2750可選的 `display` 字段控制思考文本是否返回為 `"summarized"` 或 `"omitted"`。在 Claude Opus 4.7 及更高版本上，API 默認值為 `"omitted"`，因此設置 `"summarized"` 以在 `thinking` 塊中接收思考內容。

2751

2748### `SpawnedProcess`2752### `SpawnedProcess`

2749 2753

2750自定義進程生成的介面（與 `spawnClaudeCodeProcess` 選項一起使用）。`ChildProcess` 已滿足此介面。2754自定義進程生成的介面（與 `spawnClaudeCodeProcess` 選項一起使用）。`ChildProcess` 已滿足此介面。

3158```3162```

3159 3163

3160| 屬性 | 類型 | 默認值 | 描述 |3164| 屬性 | 類型 | 默認值 | 描述 |

3161| :------------------------ | :--------- | :---------- | :--------------------------------------- |3165| :------------------------ | :--------- | :---------- | :------------------------------------------------------------------------------------------------------------------------ |

agent-sdk/typescript-v2-preview.md +7 −5

Details

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.

4 4

~~5# TypeScript SDK V2 會話 API（已棄用）~~5# TypeScript SDK V2 會話 API（已移除）

6 6

~~7> 已棄用的 V2 TypeScript Agent SDK 會話 API 參考，具有用於多輪對話的基於會話的 send/stream 模式。~~7> 已移除的 V2 TypeScript Agent SDK 會話 API 參考，具有用於多輪對話的基於會話的 send/stream 模式。

8 8

9<Warning>9<Warning>

10 V2 會話 API 函數 `unstable_v2_createSession`、`unstable_v2_resumeSession` 和 `unstable_v2_prompt` 已棄用，將在未來版本中移除。請改用 [V1 `query()` API](/zh-TW/agent-sdk/typescript)。10 V2 會話 API 不再受支援。TypeScript Agent SDK 0.3.142 移除了 `unstable_v2_createSession`、`unstable_v2_resumeSession`、`unstable_v2_prompt` 以及 `SDKSession` 和 `SDKSessionOptions` 類型。

12 若要遷移，請使用 [`query()` API](/zh-TW/agent-sdk/typescript) 和它接受的[會話選項](/zh-TW/agent-sdk/sessions)。傳遞 `AsyncIterable<SDKUserMessage>` 進行多輪對話，或使用 `options.resume` 繼續已保存的會話。如果您在 Agent SDK 0.2.x 或更早版本上維護程式碼，此頁面保留供參考。

11</Warning>13</Warning>

12 14

13V2 是一個實驗性會話 API，消除了對非同步生成器和 yield 協調的需求。與其在各輪之間管理生成器狀態，每一輪都是一個單獨的 `send()`/`stream()` 週期。API 表面縮減為三個概念：15V2 是一個實驗性會話 API，消除了對非同步生成器和 yield 協調的需求。與其在各輪之間管理生成器狀態，每一輪都是一個單獨的 `send()`/`stream()` 週期。API 表面縮減為三個概念：

18 20

19## 安裝21## 安裝

20 22

~~21V2 介面包含在現有的 SDK 套件中：~~23Agent SDK 0.2.x 是包含 V2 介面的最後一個版本。套件版本從 0.2.x 直接跳到 0.3.142，因此上面的移除版本和下面的安裝固定版本描述的是同一個邊界。若要安裝最後一個 V2 相容版本，請固定主要和次要版本：

22 24

23```bash theme={null}25```bash theme={null}

~~24npm install @anthropic-ai/claude-agent-sdk~~26npm install @anthropic-ai/claude-agent-sdk@0.2

25```27```

26 28

27<Note>29<Note>

agent-view.md +80 −29

Details

72 72

73執行 `claude agents` 開啟 agent view。它接管整個終端並列出按狀態分組的每個工作階段，固定的工作階段和需要您的工作階段在頂部。每行顯示工作階段的名稱、當前活動和上次更改的時間。73執行 `claude agents` 開啟 agent view。它接管整個終端並列出按狀態分組的每個工作階段，固定的工作階段和需要您的工作階段在頂部。每行顯示工作階段的名稱、當前活動和上次更改的時間。

74 74

75該列表涵蓋您啟動的每個背景工作階段，跨越所有您的專案。在一個儲存庫中工作的工作階段和在不同 worktree 中工作的另一個工作階段都會出現在這裡，無論您從哪個目錄開啟 agent view。您在其他終端中開啟的互動工作階段在您 [背景化它們](#from-inside-a-session) 之前不會出現。[Subagents](/zh-TW/sub-agents) 和 [teammates](/zh-TW/agent-teams) 工作階段產生的不會列為單獨的行。75根據預設，該列表顯示您啟動的每個背景工作階段，跨越所有您的專案。在一個儲存庫中工作的工作階段和在不同 worktree 中工作的另一個工作階段都會出現在這裡，無論您從哪個目錄開啟 agent view。要將檢視範圍限制在一個專案，請傳遞 `--cwd`（需要 Claude Code v2.1.141 或更新版本）：

76 76

77要將檢視範圍限制在一個專案，使用 `claude agents --cwd <path>` 啟動。只有在該目錄下啟動的工作階段會出現，包括在從它分派的任何 [worktree](/zh-TW/worktrees) 中執行的工作階段。77```bash theme={null}

78claude agents --cwd ~/projects/my-app

79```

81這只會顯示在該目錄下啟動的工作階段。已 [移入 worktree](#how-file-edits-are-isolated) 在 `~/projects/my-app/.claude/worktrees/` 下的工作階段仍然算作屬於 `~/projects/my-app`。

83您在其他終端中開啟的互動工作階段在您 [背景化它們](#from-inside-a-session) 之前不會出現。[Subagents](/zh-TW/sub-agents) 和 [teammates](/zh-TW/agent-teams) 工作階段產生的不會列為單獨的行。

78 84

79```text theme={null}85```text theme={null}

80Pinned86Pinned

117| `∙` | 程序已退出。您仍然可以查看、回覆或附加，Claude 從中斷的地方重新啟動 |123| `∙` | 程序已退出。您仍然可以查看、回覆或附加，Claude 從中斷的地方重新啟動 |

118| `✢` | 一個 [`/loop`](/zh-TW/scheduled-tasks) 工作階段在迭代之間休眠。該行顯示其執行計數和倒計時 |124| `✢` | 一個 [`/loop`](/zh-TW/scheduled-tasks) 工作階段在迭代之間休眠。該行顯示其執行計數和倒計時 |

119 125

126出現在行右邊緣的 `●` 是 [拉取請求狀態](#pull-request-status) 指示器，不是狀態圖示的一部分。它前面的數字是工作階段開啟的拉取請求計數。

127

120背景工作階段不需要任何開啟的終端即可繼續工作。單獨的 [監督程序](#the-supervisor-process) 執行它們，因此您可以關閉 agent view、關閉 shell 或啟動新的互動工作階段，您分派的工作會繼續進行。128背景工作階段不需要任何開啟的終端即可繼續工作。單獨的 [監督程序](#the-supervisor-process) 執行它們，因此您可以關閉 agent view、關閉 shell 或啟動新的互動工作階段，您分派的工作會繼續進行。

121 129

122工作階段狀態通過自動更新和監督程序重新啟動在磁碟上持久化。如果您的機器進入睡眠或關閉，執行中的工作階段會停止；使用 `claude respawn --all` 重新啟動它們。130工作階段狀態通過自動更新和監督程序重新啟動在磁碟上持久化。工作階段也會在您的機器進入睡眠時保留。它們的程序在喚醒時恢復，監督程序會重新連接到它們，而不是將時間間隔視為閒置。關閉仍會停止執行中的工作階段；請參閱 [工作階段在關閉後顯示為失敗](#sessions-show-as-failed-after-shutdown) 以了解如何恢復它們。

123 131

124### 行摘要132### 行摘要

125 133

158 166

159分離永遠不會停止背景工作階段：`←`、`Ctrl+C`、`Ctrl+D`、`Ctrl+Z` 和 `/exit` 都會讓它繼續執行。要從內部結束工作階段，執行 `/stop`。167分離永遠不會停止背景工作階段：`←`、`Ctrl+C`、`Ctrl+D`、`Ctrl+Z` 和 `/exit` 都會讓它繼續執行。要從內部結束工作階段，執行 `/stop`。

160 168

161在您分派或背景化工作階段後，在空提示上按 `←` 可從任何 Claude Code 工作階段工作，而不僅僅是您從 agent view 附加的工作階段。它背景化當前工作階段並開啟 agent view，預先選擇該工作階段，因此您可以在不離開終端的情況下切換工作階段。您可以在 `/config` 中關閉此快捷鍵。169在您分派或背景化工作階段後，在空提示上按 `←` 可從任何 Claude Code 工作階段工作，而不僅僅是您從 agent view 附加的工作階段。它背景化當前工作階段並開啟 agent view，預先選擇該工作階段，因此您可以在不離開終端的情況下切換工作階段。該行會被建立，即使是從沒有對話歷史的全新工作階段，所以 `→` 會返回到它。當該行是唯一的行時，agent view 會在其下方顯示一個入門提示。您可以在 `/config` 中關閉此快捷鍵（`leftArrowOpensAgents` 設定）。

162 170

163### 組織列表171### 組織列表

164 172

173 181

174要移除工作階段，按 `Ctrl+X` 停止它，然後在兩秒內再次按 `Ctrl+X` 刪除它。在組標題上按 `Ctrl+X` 會在確認後刪除該組中的每個工作階段。182要移除工作階段，按 `Ctrl+X` 停止它，然後在兩秒內再次按 `Ctrl+X` 刪除它。在組標題上按 `Ctrl+X` 會在確認後刪除該組中的每個工作階段。

175 183

176刪除會從 agent view 中移除工作階段並清理其 [worktree](#how-file-edits-are-isolated)，包括其中的任何未提交的更改，因此在刪除前推送或提交您想保留的工作。對話記錄保留在磁碟上，並通過 `claude --resume` 保持可用。184刪除會從 agent view 中移除工作階段並移除其對話記錄。如果 Claude [為工作階段建立了 worktree](#how-file-edits-are-isolated)，刪除會移除該 worktree，包括其中的任何未提交的更改，因此在刪除前推送或提交您想保留的工作。您自己建立的 worktree 並在其中啟動工作階段的會保留在原地。

177 185

178較舊的已完成工作階段摺疊為 `… N more` 行以保持列表簡短。失敗和具有開啟拉取請求的工作階段始終保持可見。186較舊的已完成工作階段摺疊為 `… N more` 行以保持列表簡短。失敗和具有開啟拉取請求的工作階段始終保持可見。

179 187

192在 agent view 中按 `?` 查看每個快捷鍵。下表總結了它們。200在 agent view 中按 `?` 查看每個快捷鍵。下表總結了它們。

193 201

194| 快捷鍵 | 動作 |202| 快捷鍵 | 動作 |

195| :-------------------- | :------------------------------- |203| :-------------------- | :-------------------------------- |

196| `↑` / `↓` | 在行之間移動 |204| `↑` / `↓` | 在行之間移動 |

200| `→` | 附加到選定的工作階段 |208| `→` | 附加到選定的工作階段 |

202| `Tab` | 在空輸入上，瀏覽所有 subagents。否則應用突出顯示的建議 |210| `Tab` | 在空輸入上，瀏覽所有 subagents。否則應用突出顯示的建議 |

209| `Esc` | 關閉查看面板、清除輸入或退出 |217| `Esc` | 關閉查看面板、清除輸入或退出 |

247 255

248### 從工作階段內部256### 從工作階段內部

249 257

250執行 `/background` 或其別名 `/bg` 將當前對話移動到背景工作階段。傳遞提示，例如 `/bg run the test suite and fix any failures`，在分派前發送一個額外的指令。258執行 `/background` 或其別名 `/bg` 將當前對話移動到背景工作階段。傳遞提示，例如 `/bg run the test suite and fix any failures`，以在分派前發送一個額外的指令。

251 259

252從互動工作階段背景化會啟動一個新的進程，該進程從保存的對話恢復，因此執行 subagents、[monitors](/zh-TW/tools-reference#monitor-tool) 和背景命令不會轉移到它。當任何正在執行時，Claude 會要求您在背景化前確認。進入背景後，工作階段可以啟動新的 subagents、monitors 和背景命令，這些命令在稍後分離和重新附加時保持執行。260從互動工作階段背景化會啟動一個新的進程，該進程從保存的對話恢復，因此執行 subagents、[monitors](/zh-TW/tools-reference#monitor-tool) 和背景命令不會轉移到它。當任何正在執行時，Claude 會要求您在背景化前確認。進入背景後，工作階段可以啟動新的 subagents、monitors 和背景命令，這些命令在稍後分離和重新附加時保持執行。

253 261

254### 從 shell262來自原始啟動的配置標誌會傳遞到背景化工作階段，因此其 MCP servers、settings 和備用模型保持有效：

263

264* `--mcp-config` 和 `--strict-mcp-config`

265* `--settings`

266* `--add-dir`

267* `--plugin-dir`

268* `--fallback-model`

269* `--allow-dangerously-skip-permissions`

270

271傳遞 `--allow-dangerously-skip-permissions` 會在背景化工作階段中保持 `bypassPermissions` 可達，但它不會授予任何新的權限。該模式仍然需要在任何工作階段使用它之前進行相同的一次性互動接受，如 [Permission mode, model, and effort](#permission-mode-model-and-effort) 中所述。

272

273### 從您的 shell

255 274

256傳遞 `--bg` 啟動直接進入背景的工作階段：275傳遞 `--bg` 啟動直接進入背景的工作階段：

257 276

283 302

284### 檔案編輯如何隔離303### 檔案編輯如何隔離

285 304

286每個背景工作階段，無論是從 agent view、`/bg` 或 `claude --bg` 啟動，都在您的工作目錄中啟動。編輯檔案前，Claude 將工作階段移動到 `.claude/worktrees/` 下的隔離 [git worktree](/zh-TW/worktrees) 中，因此並行工作階段可以讀取相同的檢出，但每個都寫入自己的。當工作階段已在 `.claude/worktrees/` 下、工作目錄不是 git 存儲庫或寫入工作目錄外時，Claude 會跳過此操作。305每個背景工作階段，無論是從 agent view、`/bg` 或 `claude --bg` 啟動，都在您的工作目錄中啟動。編輯檔案前，Claude 將工作階段移動到 `.claude/worktrees/` 下的隔離 [git worktree](/zh-TW/worktrees) 中，因此並行工作階段可以讀取相同的檢出，但每個都寫入自己的。

306

307Claude 在以下情況下跳過 worktree：

308

309* 工作階段已在連結的 git worktree 內，無論 Claude 是在 `.claude/worktrees/` 下建立它，還是您使用 `git worktree add` 在其他地方建立它

310* 工作目錄不是 git 存儲庫

311* 寫入在工作目錄外

312

313要為 git worktrees 不實用的存儲庫關閉 worktree 隔離，請將 [`worktree.bgIsolation`](/zh-TW/settings#worktree-settings) 設定為 `"none"`。背景工作階段隨後直接編輯您的工作副本，無需先移動到 worktree。將設定新增到專案的 `.claude/settings.json`：

314

315```json theme={null}

316{

317 "worktree": {

318 "bgIsolation": "none"

319 }

320}

321```

322

323<Note>

324 `worktree.bgIsolation` 設定需要 Claude Code v2.1.143 或更新版本。

325</Note>

287 326

288在 git 存儲庫外，工作階段直接寫入工作目錄，彼此之間不隔離，因此避免分派編輯相同檔案的並行工作階段。327在 git 存儲庫外，工作階段直接寫入工作目錄，彼此之間不隔離，因此避免分派編輯相同檔案的並行工作階段。

289 328

290當您刪除工作階段時，worktree 被移除，因此在刪除前合併或推送您想保留的更改。要找到工作階段的 worktree 路徑，查看工作階段或附加並檢查其工作目錄。329在 agent view 中刪除工作階段（`Ctrl+X` 兩次）會移除 Claude 為其建立的 worktree，包括任何未提交的更改，因此在刪除前合併或推送您想保留的更改。從 shell 使用 [`claude rm`](#manage-sessions-from-the-shell) 刪除會保留具有未提交更改的 worktree 並列印其路徑，以便您可以自己清理它。您自己建立並在其中啟動工作階段的 worktree 無論如何都會保留在原位。

330

331要找到工作階段的 worktree 路徑，查看工作階段或附加並檢查其工作目錄。

291 332

292要使 subagent 始終在其自己的 worktree 中執行，無論如何啟動，請在其 frontmatter 中設定 [`isolation: worktree`](/zh-TW/sub-agents#supported-frontmatter-fields)。333要使 subagent 始終在其自己的 worktree 中執行，無論如何啟動，請在其 frontmatter 中設定 [`isolation: worktree`](/zh-TW/sub-agents#supported-frontmatter-fields)。

293 334

294### 設定模型335### 設定模型

295 336

296agent view 標題中顯示的模型名稱是分派預設值。您從輸入啟動的新工作階段使用此模型，這與 [`/model`](/zh-TW/model-config) 在任何工作階段中控制的設定相同。要為整個 agent view 工作階段覆蓋它，請在開啟 agent view 時傳遞 `--model`。請參閱[權限模式、模型和努力](#permission-mode-model-and-effort)。337agent view 標題中顯示的模型名稱是分派預設值。您從輸入啟動的新工作階段使用此模型，這與 [`/model`](/zh-TW/model-config) 在任何工作階段中控制的設定相同。要為整個 agent view 工作階段覆蓋它，請在開啟 agent view 時傳遞 `--model`。請參閱 [Permission mode, model, and effort](#permission-mode-model-and-effort)。

297 338

298每個背景工作階段可以在不同的模型上執行。要為一個工作階段覆蓋它：339每個背景工作階段可以在不同的模型上執行。要為一個工作階段覆蓋它：

299 340

301* 附加到執行中的工作階段並在那裡執行 `/model`。如果工作階段被重新生成，更改會持續。342* 附加到執行中的工作階段並在那裡執行 `/model`。如果工作階段被重新生成，更改會持續。

302* 分派一個 [subagent](/zh-TW/sub-agents)，其 frontmatter 設定 `model` 欄位。343* 分派一個 [subagent](/zh-TW/sub-agents)，其 frontmatter 設定 `model` 欄位。

303 344

304### 權限模式、模型和努力345### Permission mode, model, and effort

305 346

306背景工作階段從它執行的目錄讀取其 [settings](/zh-TW/settings)，就像您在那裡啟動了 `claude` 一樣。347背景工作階段從它執行的目錄讀取其 [settings](/zh-TW/settings)，就像您在那裡啟動了 `claude` 一樣。

307 348

308[permission mode](/zh-TW/permissions) 取決於您如何啟動工作階段。使用 `/bg` 或 `←` 背景化現有工作階段會保持當前權限模式，因此您切換到 `acceptEdits` 或 `auto` 的工作階段在分離後仍保持該模式。從 agent view 輸入分派或從 shell 執行 `claude --bg` 使用該目錄設定中的 `defaultMode`，或分派的 [subagent 的 frontmatter](/zh-TW/sub-agents#supported-frontmatter-fields) 中的 `permissionMode`。349[permission mode](/zh-TW/permissions) 取決於您如何啟動工作階段。使用 `/bg` 或 `←` 背景化現有工作階段會保持當前權限模式，因此您切換到 `acceptEdits` 或 `auto` 的工作階段在分離後仍保持該模式。從 agent view 輸入分派或從 shell 執行 `claude --bg` 使用該目錄設定中的 `defaultMode`，或分派的 [subagent 的 frontmatter](/zh-TW/sub-agents#supported-frontmatter-fields) 中的 `permissionMode`。

309 350

351您啟動背景工作階段時的權限模式在監督者稍後 [stops and restarts](#the-supervisor-process) 工作階段的進程時持續。您使用 `claude --bg --dangerously-skip-permissions` 或 `claude --bg --permission-mode bypassPermissions` 啟動的工作階段在該重新啟動後保持 `bypassPermissions`，而不是回退到目錄的 `defaultMode`。

352

310要為您從 agent view 分派的每個工作階段設定預設值，請在開啟它時傳遞 `--permission-mode`、`--model` 或 `--effort` 中的任何一個：353要為您從 agent view 分派的每個工作階段設定預設值，請在開啟它時傳遞 `--permission-mode`、`--model` 或 `--effort` 中的任何一個：

311 354

312```bash theme={null}355```bash theme={null}

313claude agents --permission-mode plan --model opus --effort high356claude agents --permission-mode plan --model opus --effort high

314```357```

315 358

359`claude agents` 也接受 `--dangerously-skip-permissions` 作為 `--permission-mode bypassPermissions` 的簡寫，以及 `--allow-dangerously-skip-permissions` 以在每個分派工作階段的 `Shift+Tab` 循環中提供 `bypassPermissions`，而不是以該模式啟動。兩者都與 [top-level CLI flags](/zh-TW/cli-reference) 相符。

360

316<Note>361<Note>

317 傳遞 `--permission-mode`、`--model` 或 `--effort` 到 `claude agents` 需要 Claude Code v2.1.142 或更新版本。較早的版本會以未知選項錯誤拒絕這些標誌。362 傳遞 `--permission-mode`、`--model`、`--effort` 或 `--dangerously-skip-permissions` 到 `claude agents` 需要 Claude Code v2.1.142 或更新版本。`--allow-dangerously-skip-permissions` 在 `claude agents` 上需要 v2.1.143 或更新版本。較早的版本會以未知選項錯誤拒絕這些標誌。

318</Note>363</Note>

319 364

320活動預設值出現在分派輸入下方的頁腳中。365活動預設值出現在分派輸入下方的頁腳中。

323 368

324使用 `bypassPermissions` 或 `auto` 被拒絕，直到您通過以互動方式運行 `claude` 接受該模式，因為這些模式讓您未監視的工作階段無需批准即可行動。無論您是將模式傳遞給 `claude agents` 還是 `claude --bg --permission-mode`，同樣的規則也適用。369使用 `bypassPermissions` 或 `auto` 被拒絕，直到您通過以互動方式運行 `claude` 接受該模式，因為這些模式讓您未監視的工作階段無需批准即可行動。無論您是將模式傳遞給 `claude agents` 還是 `claude --bg --permission-mode`，同樣的規則也適用。

325 370

326### Settings、plugins 和 MCP servers371### Settings, plugins, and MCP servers

327 372

328Agent view 接受與 `claude` 相同的配置標誌，用於載入 settings、plugins、MCP servers 和額外目錄。每個標誌適用於 agent view 本身，並傳遞給您從它分派的每個工作階段，因此以這種方式載入的 plugin 或 MCP server 在這些工作階段中也可用。373Agent view 接受與 `claude` 相同的配置標誌，用於載入 settings、plugins、MCP servers 和額外目錄。這些標誌需要 Claude Code v2.1.142 或更新版本。每個標誌適用於 agent view 本身，並傳遞給您從它分派的每個工作階段，因此以這種方式載入的 plugin 或 MCP server 在這些工作階段中也可用。

329 374

330| 標誌 | 效果 |375| 標誌 | 效果 |

331| :-------------------------------------------------------------------------------------------------- | :--------------------------------------------- |376| :-------------------------------------------------------------------------------------------------- | :--------------------------------------------- |

348每個背景工作階段都有一個短 ID，您可以從 shell 使用。當您使用 `claude --bg` 啟動工作階段時會列印該 ID，每個工作階段的 ID 是其在 `~/.claude/jobs/` 下的目錄名稱。這些命令對於指令碼編寫或當您不想開啟 agent view 時很有用。393每個背景工作階段都有一個短 ID，您可以從 shell 使用。當您使用 `claude --bg` 啟動工作階段時會列印該 ID，每個工作階段的 ID 是其在 `~/.claude/jobs/` 下的目錄名稱。這些命令對於指令碼編寫或當您不想開啟 agent view 時很有用。

349 394

350| 命令 | 目的 |395| 命令 | 目的 |

351| :--------------------- | :----------------------------------------------- |396| :--------------------------- | :-------------------------------------------------------------------------------------------- |

398| `claude agents --cwd <path>` | 開啟 agent view，範圍限定於在 `<path>` 下啟動的工作階段 |

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

359 406

360## 背景工作階段如何被託管407## 背景工作階段如何被託管

361 408

385 432

433要在不直接讀取檔案的情況下檢查此狀態，請執行 `claude daemon status`。它報告監督程序是否可達、其程序 ID 和版本、socket 目錄，以及有多少背景工作階段處於活動狀態。`/doctor` 包含相同檢查的摘要。在 Windows 上，當 daemon 的 pipe-key 檔案被鎖定或無法讀取時，`claude daemon status` 會顯示基礎檔案錯誤，而不是報告通用連接失敗。

434

386### 關閉 agent view435### 關閉 agent view

387 436

388要完全關閉背景代理和 agent view，將 `disableAgentView` [設定](/zh-TW/settings)設為 `true` 或設定 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 環境變數。管理員可以通過[受管設定](/zh-TW/permissions#managed-settings)強制執行此操作。437要完全關閉背景代理和 agent view，將 `disableAgentView` [設定](/zh-TW/settings)設為 `true` 或設定 `CLAUDE_CODE_DISABLE_AGENT_VIEW` 環境變數。管理員可以通過[受管設定](/zh-TW/permissions#managed-settings)強制執行此操作。

397 446

398### Agent view 開啟時沒有工作階段447### Agent view 開啟時沒有工作階段

399 448

400Agent view 在您分派第一個工作階段之前為空。在底部的輸入框中輸入提示並按 `Enter`。449在您分派第一個工作階段之前，agent view 會顯示簡短的入門提示，並在工作階段清單的位置顯示範例提示。在底部的輸入框中輸入提示並按 `Enter` 以分派您的第一個工作階段。

401 450

402### 無法開啟代理，因為背景工作正在執行451### 無法開啟代理，因為背景工作正在執行

403 452

407 456

408分派輸入期望任務描述，而不是對話開場白。短於四個字元的提示會被拒絕並顯示 `Too short` 提示，以便隨意按鍵不會啟動工作階段。描述您希望工作階段執行的操作，例如 `investigate the flaky checkout test`。457分派輸入期望任務描述，而不是對話開場白。短於四個字元的提示會被拒絕並顯示 `Too short` 提示，以便隨意按鍵不會啟動工作階段。描述您希望工作階段執行的操作，例如 `investigate the flaky checkout test`。

409 458

410### 機器喚醒後工作階段顯示為已停止459### 工作階段在關閉後顯示為失敗

460

461關閉或重新啟動您的機器會停止執行中的背景工作階段，因此當您下次開啟 agent view 時，它們會顯示為失敗。附加、查看或回覆任何工作階段，工作階段會從中斷的地方重新啟動。

411 462

412背景工作階段不能在睡眠或關閉後存活。附加、查看或回覆任何已停止的工作階段，它會從中斷的地方重新啟動。要一次重新啟動所有工作階段，執行 `claude respawn --all`。463睡眠單獨不會導致這種情況。工作階段在睡眠期間會被保留，監督程序在喚醒時會重新連接到它們。

413 464

414### 附加後工作階段響應緩慢465### 附加後工作階段響應緩慢

415 466

416一旦工作階段完成並在未附加的情況下閒置約一小時，監督程序停止其程序以釋放資源。附加啟動從中斷的地方開始的新程序，這需要一些時間。正在工作或等待您的工作階段永遠不會以這種方式停止。467一旦工作階段完成並在未附加的情況下閒置約一小時，監督程序會停止其程序以釋放資源。附加會啟動從中斷的地方開始的新程序，這需要一些時間。正在工作或等待您的工作階段永遠不會以這種方式停止。

417 468

418### `.claude/worktrees/` 正在填滿469### `.claude/worktrees/` 正在填滿

419 470

420當您刪除建立 worktrees 的工作階段時，worktrees 會被移除。如果工作階段在沒有清理的情況下結束，在專案目錄中使用 `git worktree list` 列出剩餘條目，並使用 `git worktree remove <path>` 移除每個。請參閱[清理 worktrees](/zh-TW/worktrees#clean-up-worktrees)。471在 agent view 中刪除工作階段會移除 Claude 為其建立的 worktree。`claude rm` 會保留具有未提交變更的 worktree 並列印其路徑。在專案目錄中使用 `git worktree list` 列出剩餘條目，並使用 `git worktree remove <path>` 移除每個。請參閱[清理 worktrees](/zh-TW/worktrees#clean-up-worktrees)。

421 472

422## 限制473## 限制

423 474

424Agent view 是研究預覽版本，具有以下限制：475Agent view 是研究預覽版本，具有以下限制：

425 476

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

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

428* **Worktrees 隨工作階段刪除**：在刪除在其自己的 worktree 中編輯檔案的工作階段之前，合併或推送更改。479* **Claude 建立的 worktrees 在 agent view 中隨工作階段刪除**：在刪除在其自己的 worktree 中編輯檔案的工作階段之前，合併或推送更改。`claude rm` 保留具有未提交更改的 worktree；您自己建立的 worktree 會保留在原位。

429 480

430## 相關資源481## 相關資源

431 482

cli-reference.md +5 −4

Details

11您可以使用這些命令來啟動工作階段、管道內容、繼續對話和管理更新：11您可以使用這些命令來啟動工作階段、管道內容、繼續對話和管理更新：

12 12

13| 命令 | 描述 | 範例 |13| 命令 | 描述 | 範例 |

14| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------- |14| :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------- |

24| `claude auth login` | 登入您的 Anthropic 帳戶。使用 `--email` 預先填入您的電子郵件地址，使用 `--sso` 強制進行 SSO 驗證，使用 `--console` 以 Anthropic Console 登入以進行 API 使用計費，而不是 Claude 訂閱 | `claude auth login --console` |24| `claude auth login` | 登入您的 Anthropic 帳戶。使用 `--email` 預先填入您的電子郵件地址，使用 `--sso` 強制進行 SSO 驗證，使用 `--console` 以 Anthropic Console 登入以進行 API 使用計費，而不是 Claude 訂閱 | `claude auth login --console` |

27| `claude agents` | 開啟 [agent view](/zh-TW/agent-view) 以監控和分派平行背景工作階段。使用 `--cwd <path>` 僅顯示在該目錄下啟動的工作階段 | `claude agents` |27| `claude agents` | 開啟 [agent view](/zh-TW/agent-view) 以監控和分派平行背景工作階段。使用 `--cwd <path>` 僅顯示在該目錄下啟動的工作階段。傳遞 `--permission-mode`、`--model` 或 `--effort` 以設定 [分派工作階段的預設值](/zh-TW/agent-view#permission-mode-model-and-effort)。接受 `--settings`、`--add-dir`、`--plugin-dir` 和 `--mcp-config`，如同頂層 `claude` 命令。需要互動式終端 | `claude agents --cwd ~/projects/my-app` |

29| `claude auto-mode defaults` | 以 JSON 格式列印內建的 [auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器規則。使用 `claude auto-mode config` 查看您的有效設定及套用的設定 | `claude auto-mode defaults > rules.json` |29| `claude auto-mode defaults` | 以 JSON 格式列印內建的 [auto mode](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode) 分類器規則。使用 `claude auto-mode config` 查看您的有效設定及套用的設定 | `claude auto-mode defaults > rules.json` |

30| `claude daemon status` | 列印背景工作階段 [supervisor](/zh-TW/agent-view#the-supervisor-process) 的狀態、版本、socket 目錄和工作者計數以進行診斷。如果 supervisor 未執行則以代碼 1 退出 | `claude daemon status` |

32| `claude plugin` | 管理 Claude Code [plugins](/zh-TW/plugins)。別名：`claude plugins`。請參閱 [plugin 參考](/zh-TW/plugins-reference#cli-commands-reference) 以了解子命令 | `claude plugin install code-review@claude-plugins-official` |33| `claude plugin` | 管理 Claude Code [plugins](/zh-TW/plugins)。別名：`claude plugins`。請參閱 [plugin 參考](/zh-TW/plugins-reference#cli-commands-reference) 以了解子命令 | `claude plugin install code-review@claude-plugins-official` |

33| `claude project purge [path]` | 刪除專案的所有本機 Claude Code 狀態：文字記錄、工作清單、偵錯日誌、檔案編輯歷史記錄、提示歷史記錄行和專案在 `~/.claude.json` 中的項目。省略 `[path]` 以從互動式清單中選擇。旗標：`--dry-run` 以預覽，`-y`/`--yes` 以跳過確認，`-i`/`--interactive` 以確認每個項目，`--all` 用於每個專案。請參閱 [清除本機資料](/zh-TW/claude-directory#clear-local-data) | `claude project purge ~/work/repo --dry-run` |34| `claude project purge [path]` | 刪除專案的所有本機 Claude Code 狀態：文字記錄、工作清單、偵錯日誌、檔案編輯歷史記錄、提示歷史記錄行和專案在 `~/.claude.json` 中的項目。省略 `[path]` 以從互動式清單中選擇。旗標：`--dry-run` 以預覽，`-y`/`--yes` 以跳過確認，`-i`/`--interactive` 以確認每個項目，`--all` 用於每個專案。請參閱 [清除本機資料](/zh-TW/claude-directory#clear-local-data) | `claude project purge ~/work/repo --dry-run` |

34| `claude remote-control` | 啟動 [Remote Control](/zh-TW/remote-control) 伺服器以從 Claude.ai 或 Claude 應用程式控制 Claude Code。在伺服器模式下執行（無本機互動式工作階段）。請參閱 [伺服器模式旗標](/zh-TW/remote-control#start-a-remote-control-session) | `claude remote-control --name "My Project"` |35| `claude remote-control` | 啟動 [Remote Control](/zh-TW/remote-control) 伺服器以從 Claude.ai 或 Claude 應用程式控制 Claude Code。在伺服器模式下執行（無本機互動式工作階段）。請參閱 [伺服器模式旗標](/zh-TW/remote-control#start-a-remote-control-session) | `claude remote-control --name "My Project"` |

35| `claude respawn <id>` | 重新啟動已停止的 [background session](/zh-TW/agent-view#manage-sessions-from-the-shell)，保持其對話完整。使用 `--all` 重新啟動每個已停止的工作階段 | `claude respawn 7c5dcf5d` |36| `claude respawn <id>` | 重新啟動 [background session](/zh-TW/agent-view#manage-sessions-from-the-shell)（執行中或已停止），保持其對話完整。使用 `--all` 重新啟動每個執行中的工作階段，例如以取得更新的 Claude Code 二進位檔 | `claude respawn 7c5dcf5d` |

68| `--effort` | 為目前工作階段設定 [effort level](/zh-TW/model-config#adjust-effort-level)。選項：`low`、`medium`、`high`、`xhigh`、`max`；可用的層級取決於模型。覆蓋此工作階段的 [`effortLevel`](/zh-TW/settings#available-settings) 設定，且不會持久化 | `claude --effort high` |69| `--effort` | 為目前工作階段設定 [effort level](/zh-TW/model-config#adjust-effort-level)。選項：`low`、`medium`、`high`、`xhigh`、`max`；可用的層級取決於模型。覆蓋此工作階段的 [`effortLevel`](/zh-TW/settings#available-settings) 設定，且不會持久化 | `claude --effort high` |

69| `--enable-auto-mode` | {/* max-version: 2.1.110 */}在 v2.1.111 中移除。Auto mode 現在預設在 `Shift+Tab` 循環中；使用 `--permission-mode auto` 以它開始 | `claude --permission-mode auto` |70| `--enable-auto-mode` | {/* max-version: 2.1.110 */}在 v2.1.111 中移除。Auto mode 現在預設在 `Shift+Tab` 循環中；使用 `--permission-mode auto` 以它開始 | `claude --permission-mode auto` |

70| `--exclude-dynamic-system-prompt-sections` | 將每台機器的系統提示部分（工作目錄、環境資訊、記憶體路徑、git 狀態）移至第一個使用者訊息。改善在執行相同工作的不同使用者和機器之間的提示快取重複使用。僅適用於預設系統提示；設定 `--system-prompt` 或 `--system-prompt-file` 時忽略。與 `-p` 搭配使用以進行指令碼化、多使用者工作負載 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |71| `--exclude-dynamic-system-prompt-sections` | 將每台機器的系統提示部分（工作目錄、環境資訊、記憶體路徑、git 狀態）移至第一個使用者訊息。改善在執行相同工作的不同使用者和機器之間的提示快取重複使用。僅適用於預設系統提示；設定 `--system-prompt` 或 `--system-prompt-file` 時忽略。與 `-p` 搭配使用以進行指令碼化、多使用者工作負載 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

74| `--ide` | 如果恰好有一個有效的 IDE 可用，在啟動時自動連線到 IDE | `claude --ide` |75| `--ide` | 如果恰好有一個有效的 IDE 可用，在啟動時自動連線到 IDE | `claude --ide` |

code-review.md +5 −5

Details

29 29

30一旦管理員為您的組織[啟用 Code Review](#set-up-code-review)，審查將在 PR 開啟時、每次推送時或手動請求時觸發，具體取決於存儲庫的配置行為。在任何模式下，評論 `@claude review` [在 PR 上啟動審查](#manually-trigger-reviews)。30一旦管理員為您的組織[啟用 Code Review](#set-up-code-review)，審查將在 PR 開啟時、每次推送時或手動請求時觸發，具體取決於存儲庫的配置行為。在任何模式下，評論 `@claude review` [在 PR 上啟動審查](#manually-trigger-reviews)。

31 31

32當審查運行時，多個代理在 Anthropic 基礎設施上並行分析差異和周圍程式碼。每個代理尋找不同類別的問題，然後驗證步驟檢查候選項目是否符合實際程式碼行為，以過濾掉誤報。結果被去重、按嚴重程度排名，並作為內聯評論發佈在發現問題的特定行上，並在審查正文中提供摘要。如果未發現問題，Claude 會在 PR 上發佈簡短的確認評論。32當審查運行時，多個代理在 Anthropic 基礎設施上並行分析差異和周圍程式碼。每個代理尋找不同類別的問題，然後驗證步驟檢查候選項目是否符合實際程式碼行為，以過濾掉誤報。結果被去重、按嚴重程度排名，並作為內聯評論發佈在發現問題的特定行上，並在審查正文中提供摘要。如果未發現問題，Code Review 會更新 GitHub 檢查運行以顯示未檢測到任何問題。Claude 也可能在 PR 上發佈簡短的確認評論。

33 33

~~34審查成本隨著 PR 大小和複雜性而擴展，平均在 20 分鐘內完成。管理員可以通過 [分析儀表板](#view-usage) 監控審查活動和支出。~~34審查成本隨著 PR 大小和複雜性而擴展，平均在 20 分鐘內完成。管理員可以通過[分析儀表板](#view-usage)監控審查活動和支出。

35 35

36### 嚴重程度級別36### 嚴重程度級別

37 37

49 49

50每個來自 Claude 的審查評論都已附加 👍 和 👎，因此兩個按鈕都會在 GitHub UI 中出現，以便一鍵評分。如果發現有用，請點擊 👍；如果發現錯誤或嘈雜，請點擊 👎。Anthropic 在 PR 合併後收集反應計數，並使用它們來調整審查者。反應不會觸發重新審查或更改 PR 上的任何內容。50每個來自 Claude 的審查評論都已附加 👍 和 👎，因此兩個按鈕都會在 GitHub UI 中出現，以便一鍵評分。如果發現有用，請點擊 👍；如果發現錯誤或嘈雜，請點擊 👎。Anthropic 在 PR 合併後收集反應計數，並使用它們來調整審查者。反應不會觸發重新審查或更改 PR 上的任何內容。

51 51

52回覆內聯評論不會提示 Claude 回應或更新 PR。要對發現採取行動，請修復程式碼並推送。如果 PR 訂閱了推送觸發的審查，下一次運行將在問題修復時解決線程。要在不推送的情況下請求新審查，請作為 [頂級 PR 評論](#manually-trigger-reviews) 評論 `@claude review once`。52回覆內聯評論不會提示 Claude 回應或更新 PR。要對發現採取行動，請修復程式碼並推送。如果 PR 訂閱了推送觸發的審查，下一次運行將在問題修復時解決線程。要在不推送的情況下請求新審查，請作為[頂級 PR 評論](#manually-trigger-reviews)評論 `@claude review once`。

53 53

54### 檢查運行輸出54### 檢查運行輸出

55 55

73 73

74### Code Review 檢查的內容74### Code Review 檢查的內容

75 75

76默認情況下，Code Review 專注於正確性：會破壞生產的錯誤，而不是格式設置偏好或缺失的測試覆蓋。您可以通過 [添加指導文件](#customize-reviews) 到您的存儲庫來擴展它檢查的內容。76默認情況下，Code Review 專注於正確性：會破壞生產的錯誤，而不是格式設置偏好或缺失的測試覆蓋。您可以通過[添加指導文件](#customize-reviews)到您的存儲庫來擴展它檢查的內容。

77 77

78## 設定 Code Review78## 設定 Code Review

79 79

225 225

226## 定價226## 定價

227 227

228Code Review 根據令牌使用情況計費。每次審查平均花費 \$15-25，隨著 PR 大小、程式碼庫複雜性和需要驗證的問題數量而擴展。Code Review 使用通過 [extra usage](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 單獨計費，不計入您計劃的包含使用情況。228Code Review 根據令牌使用情況計費。每次審查平均花費 \$15-25，隨著 PR 大小、程式碼庫複雜性和需要驗證的問題數量而擴展。Code Review 使用通過 [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 單獨計費，不計入您計劃的包含使用情況。

229 229

230您選擇的審查觸發器影響總成本：230您選擇的審查觸發器影響總成本：

231 231

commands.md +1 −1

Details

63| `/effort [level\|auto]` | 設定模型[努力程度](/zh-TW/model-config#adjust-effort-level)。接受 `low`、`medium`、`high`、`xhigh` 或 `max`；可用的程度取決於模型，`max` 僅限工作階段。`auto` 重設為模型預設值。不帶引數時，開啟互動式滑塊；使用左右箭頭選擇程度，按 `Enter` 應用。立即生效，無需等待目前回應完成 |63| `/effort [level\|auto]` | 設定模型[努力程度](/zh-TW/model-config#adjust-effort-level)。接受 `low`、`medium`、`high`、`xhigh` 或 `max`；可用的程度取決於模型，`max` 僅限工作階段。`auto` 重設為模型預設值。不帶引數時，開啟互動式滑塊；使用左右箭頭選擇程度，按 `Enter` 應用。立即生效，無需等待目前回應完成 |

66| `/extra-usage` | 配置額外使用量以在達到速率限制時繼續工作 |

67| `/fast [on\|off]` | 切換[快速模式](/zh-TW/fast-mode)開啟或關閉 |66| `/fast [on\|off]` | 切換[快速模式](/zh-TW/fast-mode)開啟或關閉 |

69| `/fewer-permission-prompts` | **[Skill](/zh-TW/skills#bundled-skills).** 掃描您的記錄以查找常見的唯讀 Bash 和 MCP 工具呼叫，然後將優先允許清單添加到專案 `.claude/settings.json` 以減少權限提示 |68| `/fewer-permission-prompts` | **[Skill](/zh-TW/skills#bundled-skills).** 掃描您的記錄以查找常見的唯讀 Bash 和 MCP 工具呼叫，然後將優先允許清單添加到專案 `.claude/settings.json` 以減少權限提示 |

125| `/ultrareview [PR]` | 在雲端沙箱中使用 [ultrareview](/zh-TW/ultrareview) 運行深度、多 agent 程式碼審閱。Pro 和 Max 上包括 3 次免費執行，然後需要[額外使用](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |124| `/ultrareview [PR]` | 在雲端沙箱中使用 [ultrareview](/zh-TW/ultrareview) 運行深度、多 agent 程式碼審閱。Pro 和 Max 上包括 3 次免費執行，然後需要[額外使用](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

127| `/usage` | 顯示工作階段成本、方案使用限制和活動統計資訊。請參閱[成本追蹤指南](/zh-TW/costs#using-the-%2Fusage-command)以了解訂閱特定的詳細資訊。`/cost` 和 `/stats` 是別名 |126| `/usage` | 顯示工作階段成本、方案使用限制和活動統計資訊。請參閱[成本追蹤指南](/zh-TW/costs#using-the-%2Fusage-command)以了解訂閱特定的詳細資訊。`/cost` 和 `/stats` 是別名 |

127| `/usage-credits` | 配置使用量額度以在達到限制時繼續工作。先前為 `/extra-usage` |

128| `/vim` | {/* max-version: 2.1.91 */}在 v2.1.92 中移除。若要在 Vim 和一般編輯模式之間切換，請使用 `/config` → Editor mode |128| `/vim` | {/* max-version: 2.1.91 */}在 v2.1.92 中移除。若要在 Vim 和一般編輯模式之間切換，請使用 `/config` → Editor mode |

129| `/voice [hold\|tap\|off]` | 切換[語音聽寫](/zh-TW/voice-dictation)，或在特定模式下啟用它。需要 Claude.ai 帳戶 |129| `/voice [hold\|tap\|off]` | 切換[語音聽寫](/zh-TW/voice-dictation)，或在特定模式下啟用它。需要 Claude.ai 帳戶 |

130| `/web-setup` | 使用您的本地 `gh` CLI 認證將您的 GitHub 帳戶連接到[網頁上的 Claude Code](/zh-TW/web-quickstart#connect-from-your-terminal)。如果 GitHub 未連接，`/schedule` 會自動提示此操作 |130| `/web-setup` | 使用您的本地 `gh` CLI 認證將您的 GitHub 帳戶連接到[網頁上的 Claude Code](/zh-TW/web-quickstart#connect-from-your-terminal)。如果 GitHub 未連接，`/schedule` 會自動提示此操作 |

debug-your-config.md +3 −3

Details

87大多數設定意外可以追溯到一小組位置和語法規則。在假設有 bug 之前檢查這些：87大多數設定意外可以追溯到一小組位置和語法規則。在假設有 bug 之前檢查這些：

88 88

89| 症狀 | 原因 | 修正 |89| 症狀 | 原因 | 修正 |

90| :------------------------------------------------------- | :----------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |90| :------------------------------------------------------- | :----------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

93| Hook 永遠不觸發 | Hooks 在獨立的 `.claude/hooks.json` 檔案中 | 沒有獨立的 hooks 檔案。在 `settings.json` 中的 `"hooks"` 鍵下定義 hooks。請參閱 [hook 設定](/zh-TW/hooks)。 |93| Hook 永遠不觸發 | Hooks 在獨立檔案而不是 `settings.json` 中定義 | 專案或使用者設定沒有獨立的 hooks 檔案。在 `settings.json` 中的 `"hooks"` 鍵下定義 hooks。只有 [plugins](/zh-TW/plugins-reference#hooks) 載入獨立的 `hooks/hooks.json`。請參閱 [hook 設定](/zh-TW/hooks)。 |

95| `settings.json` 值似乎被忽略 | 相同的鍵在 `settings.local.json` 中設定 | `settings.local.json` 覆蓋 `settings.json`，兩者都覆蓋 `~/.claude/settings.json`。請參閱 [settings 優先順序](/zh-TW/settings#how-scopes-interact)。 |95| `settings.json` 值似乎被忽略 | 相同的鍵在 `settings.local.json` 中設定 | `settings.local.json` 覆蓋 `settings.json`，兩者都覆蓋 `~/.claude/settings.json`。請參閱 [settings 優先順序](/zh-TW/settings#how-scopes-interact)。 |

97| Skill 出現在 `/skills` 中但 Claude 永遠不呼叫它 | Skill 在其 frontmatter 中有 `disable-model-invocation: true`，或其描述與您表述請求的方式不符 | 檢查 `/skills` 中的徽章：「user-only」標籤表示 Claude 不會自動觸發它。請參閱 [skill 呼叫](/zh-TW/skills)。 |97| Skill 出現在 `/skills` 中但 Claude 永遠不呼叫它 | Skill 在其 frontmatter 中有 `disable-model-invocation: true`，或其描述與您表述請求的方式不符 | 檢查 `/skills` 中的徽章：「user-only」標籤表示 Claude 不會自動觸發它。請參閱 [skill 呼叫](/zh-TW/skills)。 |

98| 子目錄 `CLAUDE.md` 指令似乎被忽略 | 子目錄檔案按需載入，而不是在工作階段開始時載入 | 它們在 Claude 使用 Read 工具讀取該目錄中的檔案時載入，而不是在啟動時，也不是在寫入或建立檔案時。請參閱 [CLAUDE.md 檔案如何載入](/zh-TW/memory#how-claude-md-files-load)。 |98| 子目錄 `CLAUDE.md` 指令似乎被忽略 | 子目錄檔案按需載入，而不是在工作階段開始時載入 | 它們在 Claude 使用 Read 工具讀取該目錄中的檔案時載入，而不是在啟動時，也不是在寫入或建立檔案時。請參閱 [CLAUDE.md 檔案如何載入](/zh-TW/memory#how-claude-md-files-load)。 |

102| 新增在 `settings.json` 中的 `mcpServers` 下的 MCP servers 永遠不出現 | `settings.json` 不讀取 `mcpServers` 鍵 | 在儲存庫根目錄的 `.mcp.json` 中定義專案 servers，或執行 `claude mcp add --scope user` 以取得使用者範圍的 servers。請參閱 [MCP 設定](/zh-TW/mcp)。 |102| 新增在 `settings.json` 中的 `mcpServers` 下的 MCP servers 永遠不出現 | `settings.json` 不讀取 `mcpServers` 鍵 | 在儲存庫根目錄的 `.mcp.json` 中定義專案 servers，或執行 `claude mcp add --scope user` 以取得使用者範圍的 servers。請參閱 [MCP 設定](/zh-TW/mcp)。 |

desktop.md +2 −1

Details

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.

4 4

~~5# 使用 Claude Code Desktop~~5# Desktop 應用程式

6 6

7> 充分利用 Claude Code Desktop：具有 Git 隔離的並行會話、拖放窗格佈局、整合終端機和檔案編輯器、側邊聊天、電腦使用、從您的手機 Dispatch 會話、視覺化差異檢查、應用程式預覽、PR 監控、連接器和企業配置。7> 充分利用 Claude Code Desktop：具有 Git 隔離的並行會話、拖放窗格佈局、整合終端機和檔案編輯器、側邊聊天、電腦使用、從您的手機 Dispatch 會話、視覺化差異檢查、應用程式預覽、PR 監控、連接器和企業配置。

8 8

707* **Linux**：桌面應用程式僅在 macOS 和 Windows 上可用。在 Linux 上，請使用 [CLI](/zh-TW/quickstart)。707* **Linux**：桌面應用程式僅在 macOS 和 Windows 上可用。在 Linux 上，請使用 [CLI](/zh-TW/quickstart)。

708* **內嵌程式碼建議**：Desktop 不提供自動完成樣式的建議。它透過對話提示和明確的程式碼變更進行工作。708* **內嵌程式碼建議**：Desktop 不提供自動完成樣式的建議。它透過對話提示和明確的程式碼變更進行工作。

709* **Agent teams**：多代理協調可透過 [CLI](/zh-TW/agent-teams) 和 [Agent SDK](/zh-TW/headless) 使用，不在 Desktop 中。709* **Agent teams**：多代理協調可透過 [CLI](/zh-TW/agent-teams) 和 [Agent SDK](/zh-TW/headless) 使用，不在 Desktop 中。

710* **Terminal-dialog 命令**：在終端機中開啟互動式面板的內建命令，例如 `/permissions`、`/config`、`/agents` 和 `/doctor`，在 Code 標籤中不可用，並回覆 `isn't available in this environment`。直接編輯[設定檔案](/zh-TW/settings)以管理權限規則和配置，或從獨立 CLI 執行命令。

710 711

711## 疑難排解712## 疑難排解

712 713

discover-plugins.md +3 −1

Details

138 </Step>138 </Step>

139 139

140 <Step title="安裝外掛程式">140 <Step title="安裝外掛程式">

141 選擇外掛程式以檢視其詳細資訊，然後選擇安裝範圍：141 選擇外掛程式以檢視其詳細資訊。{/* min-version: 2.1.143 */}在 Claude Code v2.1.143 及更新版本上，詳細資訊窗格包含 **Context cost** 估計，讓您可以在安裝外掛程式之前查看它每回合會為您的[內容視窗](/zh-TW/features-overview#understand-context-costs)新增多少個 token。

142

143 選擇安裝範圍：

142 144

143 * **User scope**：在所有專案中為自己安裝145 * **User scope**：在所有專案中為自己安裝

144 * **Project scope**：為此儲存庫上的所有協作者安裝146 * **Project scope**：為此儲存庫上的所有協作者安裝

env-vars.md +11 −8

Details

100| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設定為 `1` 以在 Anthropic 綁定的非必要流量被阻止時將「Claude 表現如何？」工作階段品質調查路由到您自己的 [OpenTelemetry collector](/zh-TW/monitoring-usage)。調查評分僅作為 OTEL 事件發出到您配置的收集器。在此模式下，沒有調查資料發送到 Anthropic。在設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 時適用，否則無效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和組織產品反饋政策優先 |100| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 設定為 `1` 以在 Anthropic 綁定的非必要流量被阻止時將「Claude 表現如何？」工作階段品質調查路由到您自己的 [OpenTelemetry collector](/zh-TW/monitoring-usage)。調查評分僅作為 OTEL 事件發出到您配置的收集器。在此模式下，沒有調查資料發送到 Anthropic。在設定 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 時適用，否則無效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和組織產品反饋政策優先 |

101| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 生成時從 API 串流。關閉此選項時，大型工具輸入（例如長檔案寫入）僅在 Claude 完成生成後才到達，這可能看起來像是掛起。在 Anthropic API 上預設啟用。在 Bedrock 和 Vertex 上，按模型啟用，其中已部署的容器支援它。設定為 `0` 以選擇退出。設定為 `1` 以在透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由時強制啟用。在 Foundry 和 [gateway](/zh-TW/llm-gateway) 連線上預設關閉 |101| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 生成時從 API 串流。關閉此選項時，大型工具輸入（例如長檔案寫入）僅在 Claude 完成生成後才到達，這可能看起來像是掛起。在 Anthropic API 上預設啟用。在 Bedrock 和 Vertex 上，按模型啟用，其中已部署的容器支援它。設定為 `0` 以選擇退出。設定為 `1` 以在透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由時強制啟用。在 Foundry 和 [gateway](/zh-TW/llm-gateway) 連線上預設關閉 |

102| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 相容閘道（例如 LiteLLM、Kong 或內部代理）時從您的閘道的 `/v1/models` 端點填充 `/model` 選擇器。預設關閉，因為由共享 API 金鑰支援的閘道會以其他方式向每個使用者顯示該金鑰可以存取的每個模型。探索的模型仍由 [`availableModels`](/zh-TW/settings#available-settings) 允許清單篩選 |102| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 相容閘道（例如 LiteLLM、Kong 或內部代理）時從您的閘道的 `/v1/models` 端點填充 `/model` 選擇器。預設關閉，因為由共享 API 金鑰支援的閘道會以其他方式向每個使用者顯示該金鑰可以存取的每個模型。探索的模型仍由 [`availableModels`](/zh-TW/settings#available-settings) 允許清單篩選 |

103| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | 設定為 `1` 以在 Claude Opus 4.7 上執行 [fast mode](/zh-TW/fast-mode) 而不是 Opus 4.6。設定此變數時，`/fast` 會切換到 Opus 4.7；沒有它，`/fast` 會繼續使用 Opus 4.6 |103| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | {/* max-version: 2.1.141 */}在 v2.1.142 中移除。[Fast mode](/zh-TW/fast-mode) 預設為 Opus 4.7。設定 `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1` 以改為保持 Opus 4.6 |

104| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設定為 `false` 以停用提示建議（`/config` 中的「提示建議」切換）。這些是在 Claude 回應後出現在您的提示輸入中的灰顯預測。請參閱 [Prompt suggestions](/zh-TW/interactive-mode#prompt-suggestions) |104| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設定為 `false` 以停用提示建議（`/config` 中的「提示建議」切換）。這些是在 Claude 回應後出現在您的提示輸入中的灰顯預測。請參閱 [Prompt suggestions](/zh-TW/interactive-mode#prompt-suggestions) |

105| `CLAUDE_CODE_ENABLE_TASKS` | 設定為 `1` 以在非互動式模式（`-p` 旗標）中啟用任務追蹤系統。任務在互動式模式中預設為開啟。請參閱 [Task list](/zh-TW/interactive-mode#task-list) |105| `CLAUDE_CODE_ENABLE_TASKS` | 控制工作階段是否使用結構化 Task 工具（`TaskCreate`、`TaskUpdate`、`TaskGet`、`TaskList`）或舊版 `TodoWrite` 工具。{/* min-version: 2.1.142 */}自 Claude Code v2.1.142 起，Task 工具是所有模式中的預設值。設定為 `0` 以還原為 `TodoWrite`。請參閱 [Task list](/zh-TW/interactive-mode#task-list) 和 [Migrate to Task tools](/zh-TW/agent-sdk/todo-tracking#migrate-to-task-tools) |

106| `CLAUDE_CODE_ENABLE_TELEMETRY` | 設定為 `1` 以啟用 OpenTelemetry 資料收集以進行指標和日誌記錄。在配置 OTel 匯出器之前需要。請參閱 [Monitoring](/zh-TW/monitoring-usage) |106| `CLAUDE_CODE_ENABLE_TELEMETRY` | 設定為 `1` 以啟用 OpenTelemetry 資料收集以進行指標和日誌記錄。在配置 OTel 匯出器之前需要。請參閱 [Monitoring](/zh-TW/monitoring-usage) |

141| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設定為 `1` 以在 `git pull` 失敗時保留現有的市場快取，而不是擦除並重新複製。在離線或隔離環境中很有用，其中重新複製會以相同方式失敗。請參閱 [Marketplace updates fail in offline environments](/zh-TW/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) |141| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 設定為 `1` 以在 `git pull` 失敗時保留現有的市場快取，而不是擦除並重新複製。在離線或隔離環境中很有用，其中重新複製會以相同方式失敗。請參閱 [Marketplace updates fail in offline environments](/zh-TW/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) |

142| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設定為 `1` 以透過 HTTPS 而不是 SSH 複製 GitHub `owner/repo` 外掛程式來源。在 CI 執行器、容器或任何沒有為 `github.com` 配置 SSH 金鑰的環境中很有用 |142| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 設定為 `1` 以透過 HTTPS 而不是 SSH 複製 GitHub `owner/repo` 外掛程式來源。在 CI 執行器、容器或任何沒有為 `github.com` 配置 SSH 金鑰的環境中很有用 |

143| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一個或多個唯讀外掛程式種子目錄的路徑，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。使用此選項可將預先填充的外掛程式目錄捆綁到容器映像中。Claude Code 在啟動時從這些目錄註冊市場，並使用預先快取的外掛程式而無需重新複製。請參閱 [Pre-populate plugins for containers](/zh-TW/plugin-marketplaces#pre-populate-plugins-for-containers) |143| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一個或多個唯讀外掛程式種子目錄的路徑，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。使用此選項可將預先填充的外掛程式目錄捆綁到容器映像中。Claude Code 在啟動時從這些目錄註冊市場，並使用預先快取的外掛程式而無需重新複製。請參閱 [Pre-populate plugins for containers](/zh-TW/plugin-marketplaces#pre-populate-plugins-for-containers) |

144| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 設定為 `1` 以停止 Claude Code 在生成 PowerShell 以進行工具呼叫、hooks 和狀態行命令時傳遞 `-ExecutionPolicy Bypass`，並改為尊重機器的有效執行政策。預設情況下，Claude Code 在程序範圍內繞過執行政策，以便 `.ps1` 指令碼和模組匯入在預設受限的 Windows 安裝上工作。無論此設定如何，程序範圍繞過永遠不會覆蓋群組原則 `MachinePolicy` 或 `UserPolicy` |

144| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 並代表其管理模型提供者路由的主機平台設定。設定時，提供者選擇、端點和驗證變數（例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`）在設定檔案中被忽略，以便使用者設定無法覆蓋主機的路由。Bedrock、Vertex 和 Foundry 的自動遙測選擇退出也會被跳過，因此遙測遵循標準 `DISABLE_TELEMETRY` 選擇退出。請參閱 [Default behaviors by API provider](/zh-TW/data-usage#default-behaviors-by-api-provider) |145| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 並代表其管理模型提供者路由的主機平台設定。設定時，提供者選擇、端點和驗證變數（例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`）在設定檔案中被忽略，以便使用者設定無法覆蓋主機的路由。Bedrock、Vertex 和 Foundry 的自動遙測選擇退出也會被跳過，因此遙測遵循標準 `DISABLE_TELEMETRY` 選擇退出。請參閱 [Default behaviors by API provider](/zh-TW/data-usage#default-behaviors-by-api-provider) |

146| `CLAUDE_CODE_REMOTE` | 當 Claude Code 作為 [cloud session](/zh-TW/claude-code-on-the-web) 執行時自動設定為 `true`。從 hook 或設定指令碼讀取此項以偵測您是否在雲端環境中 |147| `CLAUDE_CODE_REMOTE` | 當 Claude Code 作為 [cloud session](/zh-TW/claude-code-on-the-web) 執行時自動設定為 `true`。從 hook 或設定指令碼讀取此項以偵測您是否在雲端環境中 |

153| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子程序中自動設定為目前工作階段 ID。符合傳遞給 [hooks](/zh-TW/hooks) 的 `session_id` 欄位。在 `/clear` 時更新。用於將指令碼和外部工具與啟動它們的 Claude Code 工作階段相關聯 |154| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子程序中自動設定為目前工作階段 ID。符合傳遞給 [hooks](/zh-TW/hooks) 的 `session_id` 欄位。在 `/clear` 時更新。用於將指令碼和外部工具與啟動它們的 Claude Code 工作階段相關聯 |

155| `CLAUDE_CODE_SHELL_PREFIX` | 命令前綴以包裝 Claude Code 生成的 shell 命令：Bash 工具呼叫、[hook](/zh-TW/hooks) 命令和 stdio [MCP server](/zh-TW/mcp) 啟動命令。對於日誌記錄或稽核很有用。範例：設定 `/path/to/logger.sh` 會將每個命令執行為 `/path/to/logger.sh <command>` |156| `CLAUDE_CODE_SHELL_PREFIX` | 命令前綴以包裝 Claude Code 生成的 shell 命令：Bash 工具呼叫、[hook](/zh-TW/hooks) 命令和 stdio [MCP server](/zh-TW/mcp) 啟動命令。對於日誌記錄或稽核很有用。範例：設定 `/path/to/logger.sh` 會將每個命令執行為 `/path/to/logger.sh <command>` |

156| `CLAUDE_CODE_SIMPLE` | 設定為 `1` 以使用最小系統提示和僅 Bash、檔案讀取和檔案編輯工具執行。來自 `--mcp-config` 的 MCP 工具仍然可用。停用 hooks、skills、plugins、MCP 伺服器、自動記憶體和 CLAUDE.md 的自動探索。[`--bare`](/zh-TW/headless#start-faster-with-bare-mode) CLI 旗標設定此項 |157| `CLAUDE_CODE_SIMPLE` | 設定為 `1` 以使用最小系統提示和僅 Bash、檔案讀取和檔案編輯工具執行。來自 `--mcp-config` 的 MCP 工具仍然可用。停用 hooks、skills、plugins、MCP 伺服器、自動記憶體和 CLAUDE.md 的自動探索。OAuth 權杖和鑰匙圈認證不會被讀取，因此 Anthropic 驗證必須來自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。相當於傳遞 [`--bare`](/zh-TW/headless#start-faster-with-bare-mode) |

157| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 設定為 `1` 以在任何模型上使用較短的系統提示和縮寫工具描述。設定為 `0`、`false`、`no` 或 `off` 以選擇退出，即使實驗或伺服器配置會以其他方式啟用它。完整工具集、hooks、MCP 伺服器和 CLAUDE.md 探索保持啟用 |158| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 設定為 `1` 以在任何模型上使用較短的系統提示和縮寫工具描述。設定為 `0`、`false`、`no` 或 `off` 以選擇退出，即使實驗或伺服器配置會以其他方式啟用它。完整工具集、hooks、MCP 伺服器和 CLAUDE.md 探索保持啟用 |

162| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設定為 `1` 以跳過將提示歷史記錄和工作階段文字記錄寫入磁碟。使用此變數啟動的工作階段不會出現在 `--resume`、`--continue` 或向上箭頭歷史記錄中。對於臨時指令碼化工作階段很有用 |163| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 設定為 `1` 以跳過將提示歷史記錄和工作階段文字記錄寫入磁碟。使用此變數啟動的工作階段不會出現在 `--resume`、`--continue` 或向上箭頭歷史記錄中。對於臨時指令碼化工作階段很有用 |

165| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/zh-TW/hooks#stop) 或 [SubagentStop](/zh-TW/hooks#subagentstop) hook 可能連續阻止回合結束的最大次數，然後 Claude Code 覆蓋它並無論如何結束回合（預設值：8）。設定為 `0` 以停用上限。如果您的 hook 合法需要更多迭代來解決，請提高此值 |

165| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 設定為 `1` 以從子程序環境中移除 Anthropic 和雲端提供者認證（Bash 工具、hooks、MCP stdio 伺服器）。父 Claude 程序保留這些認證以進行 API 呼叫，但子程序無法讀取它們，減少了嘗試透過 shell 擴展來竊取機密的提示注入攻擊的暴露。在 Linux 上，這也會在隔離的 PID 命名空間中執行 Bash 子程序，以便它們無法透過 `/proc` 讀取主機程序環境；作為副作用，`ps`、`pgrep` 和 `kill` 無法看到或發信號給主機程序。配置 `allowed_non_write_users` 時，`claude-code-action` 會自動設定此項 |167| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 設定為 `1` 以從子程序環境中移除 Anthropic 和雲端提供者認證（Bash 工具、hooks、MCP stdio 伺服器）。父 Claude 程序保留這些認證以進行 API 呼叫，但子程序無法讀取它們，減少了嘗試透過 shell 擴展來竊取機密的提示注入攻擊的暴露。在 Linux 上，這也會在隔離的 PID 命名空間中執行 Bash 子程序，以便它們無法透過 `/proc` 讀取主機程序環境；作為副作用，`ps`、`pgrep` 和 `kill` 無法看到或發信號給主機程序。配置 `allowed_non_write_users` 時，`claude-code-action` 會自動設定此項 |

166| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非互動式模式（`-p` 旗標）中設定為 `1` 以等待外掛程式安裝完成，然後再進行第一個查詢。沒有此選項，外掛程式會在背景中安裝，可能在第一個回合時不可用。與 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 結合以限制等待時間 |168| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非互動式模式（`-p` 旗標）中設定為 `1` 以等待外掛程式安裝完成，然後再進行第一個查詢。沒有此選項，外掛程式會在背景中安裝，可能在第一個回合時不可用。與 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 結合以限制等待時間 |

180| `CLAUDE_CONFIG_DIR` | 覆蓋配置目錄（預設值：`~/.claude`）。所有設定、認證、工作階段歷史記錄和外掛程式都儲存在此路徑下。對於並排執行多個帳戶很有用：例如，`alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |182| `CLAUDE_CONFIG_DIR` | 覆蓋配置目錄（預設值：`~/.claude`）。所有設定、認證、工作階段歷史記錄和外掛程式都儲存在此路徑下。對於並排執行多個帳戶很有用：例如，`alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'` |

181| `CLAUDE_EFFORT` | 在 Bash 工具子程序和 hook 命令中自動設定為該回合的作用中 [effort level](/zh-TW/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。符合傳遞給 [hooks](/zh-TW/hooks) 的 `effort.level` 欄位。僅在目前模型支援努力參數時設定 |183| `CLAUDE_EFFORT` | 在 Bash 工具子程序和 hook 命令中自動設定為該回合的作用中 [effort level](/zh-TW/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。符合傳遞給 [hooks](/zh-TW/hooks) 的 `effort.level` 欄位。僅在目前模型支援努力參數時設定 |

182| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設定為 `1` 以強制啟用位元級串流閒置監視程式，或設定為 `0` 以強制停用它。未設定時，監視程式預設對 Anthropic API 連線啟用。位元監視程式會在 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定的持續時間內沒有位元到達線路時中止連線，最少 5 分鐘，獨立於事件級監視程式 |184| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設定為 `1` 以強制啟用位元級串流閒置監視程式，或設定為 `0` 以強制停用它。未設定時，監視程式預設對 Anthropic API 連線啟用。位元監視程式會在 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 設定的持續時間內沒有位元到達線路時中止連線，最少 5 分鐘，獨立於事件級監視程式 |

183| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設定為 `1` 以啟用事件級串流閒置監視程式。預設關閉。對於 Bedrock、Vertex 和 Foundry，這是唯一可用的閒置監視程式。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |185| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設定為 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元級串流閒置監視程式。預設關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |

186| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設定為 `1` 以啟用事件級串流閒置監視程式。預設關閉。對於 Bedrock、Vertex 和 Foundry，這是唯一可用的閒置監視程式。在 Bedrock 上，您也可以使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` 啟用獨立的位元級監視程式；當兩者都設定時，它們一起執行。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |

184| `CLAUDE_ENV_FILE` | Claude Code 在每個 Bash 命令之前在同一 shell 程序中執行的 shell 指令碼的路徑，因此檔案中的匯出對命令可見。用於在命令之間保持 virtualenv 或 conda 啟用。也由 [SessionStart](/zh-TW/hooks#persist-environment-variables)、[Setup](/zh-TW/hooks#setup)、[CwdChanged](/zh-TW/hooks#cwdchanged) 和 [FileChanged](/zh-TW/hooks#filechanged) hooks 動態填充 |187| `CLAUDE_ENV_FILE` | Claude Code 在每個 Bash 命令之前在同一 shell 程序中執行的 shell 指令碼的路徑，因此檔案中的匯出對命令可見。用於在命令之間保持 virtualenv 或 conda 啟用。也由 [SessionStart](/zh-TW/hooks#persist-environment-variables)、[Setup](/zh-TW/hooks#setup)、[CwdChanged](/zh-TW/hooks#cwdchanged) 和 [FileChanged](/zh-TW/hooks#filechanged) hooks 動態填充 |

185| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 當未提供明確名稱時，自動產生的 [Remote Control](/zh-TW/remote-control) 工作階段名稱的前綴。預設為您的機器主機名稱，產生名稱如 `myhost-graceful-unicorn`。`--remote-control-session-name-prefix` CLI 旗標為單一呼叫設定相同的值 |188| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 當未提供明確名稱時，自動產生的 [Remote Control](/zh-TW/remote-control) 工作階段名稱的前綴。預設為您的機器主機名稱，產生名稱如 `myhost-graceful-unicorn`。`--remote-control-session-name-prefix` CLI 旗標為單一呼叫設定相同的值 |

186| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 串流閒置監視程式在關閉停滯連線之前的逾時（以毫秒為單位）。預設和最小 `300000`（5 分鐘）用於位元級和事件級監視程式；較低的值會無聲地限制以吸收延伸思考暫停和代理緩衝。對於第三方提供者，需要 `CLAUDE_ENABLE_STREAM_WATCHDOG=1` |189| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 串流閒置監視程式在關閉停滯連線之前的逾時（以毫秒為單位）。預設和最小 `300000`（5 分鐘）用於位元級和事件級監視程式；較低的值會無聲地限制以吸收延伸思考暫停和代理緩衝。對於第三方提供者，需要 `CLAUDE_ENABLE_STREAM_WATCHDOG=1`。在 Bedrock 上，也適用於 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` |

187| `DEBUG` | 設定為 `1` 以啟用偵錯模式，相當於使用 [`--debug`](/zh-TW/cli-reference#cli-flags) 啟動。偵錯日誌會寫入 `~/.claude/debug/<session-id>.txt`，或寫入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 設定的路徑。僅真值 `1`、`true`、`yes` 和 `on` 啟用偵錯模式，因此為其他工具設定的命名空間模式（如 `DEBUG=express:*`）不會觸發它 |190| `DEBUG` | 設定為 `1` 以啟用偵錯模式，相當於使用 [`--debug`](/zh-TW/cli-reference#cli-flags) 啟動。偵錯日誌會寫入 `~/.claude/debug/<session-id>.txt`，或寫入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 設定的路徑。僅真值 `1`、`true`、`yes` 和 `on` 啟用偵錯模式，因此為其他工具設定的命名空間模式（如 `DEBUG=express:*`）不會觸發它 |

221| `MAX_STRUCTURED_OUTPUT_RETRIES` | 當模型的回應無法驗證非互動式模式（`-p` 旗標）中的 [`--json-schema`](/zh-TW/cli-reference#cli-flags) 時重試的次數。預設為 5 |224| `MAX_STRUCTURED_OUTPUT_RETRIES` | 當模型的回應無法驗證非互動式模式（`-p` 旗標）中的 [`--json-schema`](/zh-TW/cli-reference#cli-flags) 時重試的次數。預設為 5 |

222| `MAX_THINKING_TOKENS` | 覆蓋 [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) token 預算。上限是模型的 [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) 減一。設定為 `0` 以完全停用思考。在具有 [adaptive reasoning](/zh-TW/model-config#adjust-effort-level) 的模型上，預算會被忽略，除非透過 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 停用自適應推理 |225| `MAX_THINKING_TOKENS` | 覆蓋 [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) token 預算。上限是模型的 [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison) 減一。設定為 `0` 以完全停用思考。在具有 [adaptive reasoning](/zh-TW/model-config#adjust-effort-level) 的模型上，預算會被忽略，除非透過 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 停用自適應推理 |

223| `MCP_CLIENT_SECRET` | 需要 [pre-configured credentials](/zh-TW/mcp#use-pre-configured-oauth-credentials) 的 MCP 伺服器的 OAuth 用戶端密碼。在使用 `--client-secret` 新增伺服器時避免互動式提示 |226| `MCP_CLIENT_SECRET` | 需要 [pre-configured credentials](/zh-TW/mcp#use-pre-configured-oauth-credentials) 的 MCP 伺服器的 OAuth 用戶端密碼。在使用 `--client-secret` 新增伺服器時避免互動式提示 |

224| `MCP_CONNECTION_NONBLOCKING` | 在非互動式模式（`-p`）中設定為 `true` 以完全跳過 MCP 連線等待。對於不需要 MCP 工具的指令碼化管道很有用。沒有此變數，第一個查詢會等待最多 5 秒以進行 `--mcp-config` 伺服器連線。配置 [`alwaysLoad: true`](/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器始終會阻止啟動，無論此變數如何，因為其工具必須在建立第一個提示時存在 |227| `MCP_CONNECTION_NONBLOCKING` | 控制啟動是否在第一個查詢之前等待 MCP 伺服器連線。{/* min-version: 2.1.142 */}自 Claude Code v2.1.142 起，MCP 啟動預設為非阻止：伺服器在背景中連線，其工具在完成時變為可用。設定為 `0` 以還原阻止 5 秒連線等待。配置 [`alwaysLoad: true`](/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器仍會阻止啟動，無論如何，因為其工具必須在建立第一個提示時存在 |

225| `MCP_CONNECT_TIMEOUT_MS` | 第一個查詢在拍攝工具清單快照之前等待 MCP 連線批次的時間（以毫秒為單位）（預設值：5000）。在截止時間時仍待處理的伺服器會在背景中繼續連線，但在下一個查詢之前不會出現。與 `MCP_TIMEOUT` 不同，後者限制個別伺服器的連線嘗試。最相關於發出單一查詢且需要緩慢連線伺服器可見的非互動式工作階段 |228| `MCP_CONNECT_TIMEOUT_MS` | 阻止 MCP 啟動等待連線批次的時間（以毫秒為單位），然後拍攝工具清單快照（預設值：5000）。適用於 `MCP_CONNECTION_NONBLOCKING=0` 或標記為 [`alwaysLoad: true`](/zh-TW/mcp#exempt-a-server-from-deferral) 的伺服器。在截止時間時仍待處理的伺服器會在背景中繼續連線，但在下一個查詢之前不會出現。與 `MCP_TIMEOUT` 不同，後者限制個別伺服器的連線嘗試 |

226| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定連接埠，作為在使用 [pre-configured credentials](/zh-TW/mcp#use-pre-configured-oauth-credentials) 新增 MCP 伺服器時 `--callback-port` 的替代方案 |229| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重新導向回呼的固定連接埠，作為在使用 [pre-configured credentials](/zh-TW/mcp#use-pre-configured-oauth-credentials) 新增 MCP 伺服器時 `--callback-port` 的替代方案 |

errors.md +4 −2

Details

178 178

179* 等待錯誤中顯示的重設時間179* 等待錯誤中顯示的重設時間

180* 執行 `/usage` 以查看您的計畫限制及其重設時間180* 執行 `/usage` 以查看您的計畫限制及其重設時間

181* 執行 `/extra-usage` 以在 Pro 和 Max 上購買額外使用，或在 Team 和 Enterprise 上向您的管理員請求。請參閱 [Extra usage for paid plans](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 以了解如何計費。181* 執行 `/usage-credits` 以在 Pro 和 Max 上購買額外使用，或在 Team 和 Enterprise 上向您的管理員請求。請參閱 [usage credits for paid plans](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 以了解如何計費。

182* 若要升級您的計畫以獲得更高的基本限制，請參閱 [claude.com/pricing](https://claude.com/pricing)182* 若要升級您的計畫以獲得更高的基本限制，請參閱 [claude.com/pricing](https://claude.com/pricing)

183 183

184若要在達到限制之前監視您的剩餘額度，請將 `rate_limits` 欄位新增到 [custom status line](/zh-TW/statusline#rate-limit-usage)，或在 Desktop app 中按一下模型選擇器旁邊的 [usage ring](/zh-TW/desktop#check-usage)。184若要在達到限制之前監視您的剩餘額度，請將 `rate_limits` 欄位新增到 [custom status line](/zh-TW/statusline#rate-limit-usage)，或在 Desktop app 中按一下模型選擇器旁邊的 [usage ring](/zh-TW/desktop#check-usage)。

203您已達到為您的 API 金鑰、Amazon Bedrock 專案或 Google Vertex AI 專案配置的速率限制。203您已達到為您的 API 金鑰、Amazon Bedrock 專案或 Google Vertex AI 專案配置的速率限制。

204 204

205```text theme={null}205```text theme={null}

206API Error: Request rejected (429) · this may be a temporary capacity issue206API Error: Request rejected (429) · this may be a temporary capacity issue. If it persists, check status.claude.com.

207```207```

208 208

209尾部句子命名了檢查服務健康狀況的位置，並因提供者而異。Bedrock 和 Vertex AI 配置會命名該提供者的服務狀態，而不是 Anthropic 狀態頁面。

210

209**要做什麼：**211**要做什麼：**

210 212

211* 執行 `/status` 並確認活躍的認證是您期望的。環境中的流浪 `ANTHROPIC_API_KEY` 可能會透過低階金鑰而不是您的訂閱路由請求。213* 執行 `/status` 並確認活躍的認證是您期望的。環境中的流浪 `ANTHROPIC_API_KEY` 可能會透過低階金鑰而不是您的訂閱路由請求。

fast-mode.md +15 −49

Details

12 12

13快速模式是 Claude Opus 的高速配置，使模型速度提升 2.5 倍，但每個 token 的成本更高。當您需要速度進行互動式工作（如快速迭代或實時調試）時，使用 `/fast` 切換開啟，當成本比延遲更重要時，切換關閉。13快速模式是 Claude Opus 的高速配置，使模型速度提升 2.5 倍，但每個 token 的成本更高。當您需要速度進行互動式工作（如快速迭代或實時調試）時，使用 `/fast` 切換開啟，當成本比延遲更重要時，切換關閉。

14 14

15快速模式不是不同的模型。它使用 Claude Opus 搭配不同的 API 配置，優先考慮速度而非成本效率。您獲得相同的品質和功能，只是回應速度更快。快速模式在 Opus 4.6 和 Opus 4.7 上受支援。它在 Sonnet、Haiku 或其他模型上不可用。15快速模式不是不同的模型。它使用 Claude Opus 搭配不同的 API 配置，優先考慮速度而非成本效率。您獲得相同的品質和功能，只是回應速度更快。快速模式在 Opus 4.7 和 Opus 4.6 上受支援。它在 Sonnet、Haiku 或其他模型上不可用。

16 16

17<Note>17<Note>

18 快速模式需要 Claude Code v2.1.36 或更新版本。使用 `claude --version` 檢查您的版本。18 快速模式需要 Claude Code v2.1.36 或更新版本。使用 `claude --version` 檢查您的版本。

21需要了解的事項：21需要了解的事項：

22 22

23* 使用 `/fast` 在 Claude Code CLI 中切換快速模式。也可在 Claude Code VS Code 擴充功能中透過 `/fast` 使用。23* 使用 `/fast` 在 Claude Code CLI 中切換快速模式。也可在 Claude Code VS Code 擴充功能中透過 `/fast` 使用。

~~24* 預設情況下，`/fast` 在 Opus 4.6 上執行。要改為在 Opus 4.7 上執行快速模式，請設定 [`CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`](#use-fast-mode-on-opus-4-7) 環境變數。~~24* 快速模式定價在 Opus 4.7 和 Opus 4.6 上都是 $30/$150 MTok。

~~25* 快速模式定價在 Opus 4.6 和 Opus 4.7 上都是 \$30/150 MTok。~~

26* 適用於訂閱方案（Pro/Max/Team/Enterprise）上的所有 Claude Code 使用者和 Claude Console。25* 適用於訂閱方案（Pro/Max/Team/Enterprise）上的所有 Claude Code 使用者和 Claude Console。

~~27* 對於訂閱方案（Pro/Max/Team/Enterprise）上的 Claude Code 使用者，快速模式僅透過額外使用提供，不包含在訂閱速率限制中。~~26* 對於訂閱方案（Pro/Max/Team/Enterprise）上的 Claude Code 使用者，快速模式僅透過使用額度提供，不包含在訂閱速率限制中。

28 27

29本頁涵蓋如何[切換快速模式](#toggle-fast-mode)、[在 Opus 4.7 上使用快速模式](#use-fast-mode-on-opus-4-7)、[成本權衡](#understand-the-cost-tradeoff)、[何時使用](#decide-when-to-use-fast-mode)、[要求](#requirements)、[每個工作階段選擇加入](#require-per-session-opt-in)和[速率限制行為](#handle-rate-limits)。28本頁涵蓋如何[切換快速模式](#toggle-fast-mode)、其[成本權衡](#understand-the-cost-tradeoff)、[何時使用](#decide-when-to-use-fast-mode)、[要求](#requirements)、[每個工作階段選擇加入](#require-per-session-opt-in)和[速率限制行為](#handle-rate-limits)。

30 29

31## 切換快速模式30## 切換快速模式

32 31

41 40

42當您啟用快速模式時：41當您啟用快速模式時：

43 42

44* 如果您使用不同的模型，Claude Code 會自動切換到快速模式模型：預設為 Opus 4.6，或在設定 [`CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`](#use-fast-mode-on-opus-4-7) 時為 Opus 4.7。43* 如果您使用不同的模型，Claude Code 會自動切換到 Opus

~~45* 您會看到確認訊息："Fast mode ON"~~44* 您會看到確認訊息：「Fast mode ON」

46* 快速模式啟用時，提示旁會出現一個小的 `↯` 圖示45* 快速模式啟用時，提示旁會出現一個小的 `↯` 圖示

47* 隨時再次執行 `/fast` 以檢查快速模式是否開啟或關閉46* 隨時再次執行 `/fast` 以檢查快速模式是否開啟或關閉

48 47

49當您再次使用 `/fast` 關閉快速模式時，您仍保持在快速模式執行的相同 Opus 版本上。模型不會還原到您之前的模型。要切換到不同的模型，請使用 `/model`。48當您再次使用 `/fast` 關閉快速模式時，您仍保持在 Opus 上。模型不會還原到您之前的模型。要切換到不同的模型，請使用 `/model`。

50 49

~~51## 在 Opus 4.7 上使用快速模式~~50Opus 4.7 是 Claude Code v2.1.142 及更新版本中的快速模式預設值。要改為將快速模式固定到 Opus 4.6，請設定 `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1`。

~~53<Note>~~

~~54 Opus 4.7 上的快速模式需要 Claude Code v2.1.139 或更新版本。~~

~~55</Note>~~

~~57Claude Opus 4.7 的快速模式處於研究預覽階段。它以相同的 2.5 倍速度和與 Opus 4.6 快速模式相同的價格執行，沒有其他行為變更。~~

~~59<Note>~~

~~60 在 2026 年 5 月 14 日，Opus 4.7 成為預設快速模式模型。在此之前，透過設定 `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1` 選擇加入。~~

~~61</Note>~~

63要選擇加入，在啟動 Claude Code 之前設定 `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1`。設定該變數後，`/fast` 在 Opus 4.7 上執行。沒有它，`/fast` 繼續在 Opus 4.6 上執行。

~~65您可以將變數設定為 shell 匯出：~~

~~67```bash theme={null}~~

~~68export CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE=1~~

~~69```~~

~~71或在任何 Claude Code [設定檔案](/zh-TW/settings#settings-files)中，包括使用者、專案和受管設定，以限定選擇加入的範圍：~~

~~73```json theme={null}~~

~~74{~~

~~75 "env": {~~

~~76 "CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE": "1"~~

~~77 }~~

~~78}~~

~~79```~~

~~81Opus 4.6 的快速模式仍可與 Opus 4.7 並行使用。兩者共享相同的快速模式速率限制池：任一模型上的使用都會從相同的限制中扣除。~~

83若要明確將快速模式固定到 Opus 4.6，設定 `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1`。此變數優先，因此無論是否設定 `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE`，快速模式都會在 Opus 4.6 上執行。

84 51

85## 了解成本權衡52## 了解成本權衡

86 53

87快速模式的每個 token 定價高於標準 Opus：54快速模式的每個 token 定價高於標準 Opus：

88 55

89| 模式 | 輸入 (MTok) | 輸出 (MTok) |56| 模式 | 輸入 (MTok) | 輸出 (MTok) |

~~90| --------------- | --------- | --------- |~~57| ---- | --------- | --------- |

~~91| Opus 4.6 上的快速模式 | \$30 | \$150 |~~58| 快速模式 | \$30 | \$150 |

~~92| Opus 4.7 上的快速模式 | \$30 | \$150 |~~

93 59

94快速模式定價在整個 1M token 上下文視窗中是固定的。60快速模式定價在整個 1M token 上下文視窗中是固定的。

95 61

124 90

125快速模式需要以下所有條件：91快速模式需要以下所有條件：

126 92

127* **第三方雲端提供商上不可用**：快速模式在 Amazon Bedrock、Google Vertex AI 或 Microsoft Azure Foundry 上不可用。快速模式可透過 Anthropic Console API 和使用額外使用的 Claude 訂閱方案取得。93* **第三方雲端提供商上不可用**：快速模式在 Amazon Bedrock、Google Vertex AI 或 Microsoft Azure Foundry 上不可用。快速模式可透過 Anthropic Console API 和使用額度的 Claude 訂閱方案取得。

128* **啟用額外使用**：您的帳戶必須啟用額外使用，這允許超出您方案包含使用量的計費。對於個人帳戶，在您的 [Console 計費設定](https://platform.claude.com/settings/organization/billing)中啟用此功能。對於 Team 和 Enterprise，管理員必須為組織啟用額外使用。94* **啟用使用額度**：您的帳戶必須啟用使用額度，這允許超出您方案包含使用量的計費。對於個人帳戶，在您的 [Console 計費設定](https://platform.claude.com/settings/organization/billing)中啟用此功能。對於 Team 和 Enterprise，管理員必須為組織啟用使用額度。

129 95

130<Note>96<Note>

131 快速模式使用直接計費到額外使用，即使您的方案上還有剩餘使用量。這意味著快速模式 token 不計入您方案的包含使用量，並從第一個 token 開始按快速模式費率計費。97 快速模式使用直接計費到使用額度，即使您的方案上還有剩餘使用量。這意味著快速模式 token 不計入您方案的包含使用量，並從第一個 token 開始按快速模式費率計費。

132</Note>98</Note>

133 99

134* **Team 和 Enterprise 的管理員啟用**：快速模式預設對 Team 和 Enterprise 組織禁用。管理員必須明確[啟用快速模式](#enable-fast-mode-for-your-organization)，使用者才能存取它。100* **Team 和 Enterprise 的管理員啟用**：快速模式預設對 Team 和 Enterprise 組織禁用。管理員必須明確[啟用快速模式](#enable-fast-mode-for-your-organization)，使用者才能存取它。

160 126

161## 處理速率限制127## 處理速率限制

162 128

163快速模式與標準 Opus 有不同的速率限制。Opus 4.6 和 Opus 4.7 的快速模式共享相同的速率限制池：任一模型上的使用都會從相同的限制中扣除。當您達到快速模式速率限制或用完額外使用額度時：129快速模式與標準 Opus 有不同的速率限制。Opus 4.7 和 Opus 4.6 的快速模式共享相同的速率限制池：任一模型上的使用都會從相同的限制中扣除。當您達到快速模式速率限制或用完使用額度時：

164 130

1651. 快速模式自動回退到相同 Opus 版本上的標準速度1311. 快速模式自動回退到標準速度

1662. `↯` 圖示變灰以指示冷卻1322. `↯` 圖示變灰以指示冷卻

1673. 您以標準速度和定價繼續工作1333. 您以標準速度和定價繼續工作

1684. 冷卻期過期時，快速模式自動重新啟用1344. 冷卻期過期時，快速模式自動重新啟用

features-overview.md +2 −2

Details

271 271

272 **什麼載入：** 新鮮、隔離的上下文，包含：272 **什麼載入：** 新鮮、隔離的上下文，包含：

273 273

274 * 系統提示（與父級共享以提高快取效率）274 * 代理的自身系統提示，而不是完整的 Claude Code 系統提示

275 * 代理 `skills:` 欄位中列出的 skills 的完整內容275 * 代理 `skills:` 欄位中列出的 skills 的完整內容

276 * CLAUDE.md 和 git 狀態（從父級繼承）276 * CLAUDE.md 和 git 狀態，除了內置的 Explore 和 Plan 代理[省略兩者](/zh-TW/sub-agents#what-loads-at-startup)

277 * 主代理在提示中傳遞的任何上下文277 * 主代理在提示中傳遞的任何上下文

278 278

279 **上下文成本：** 與主會話隔離。Subagents 不繼承您的對話歷史或調用的 skills。279 **上下文成本：** 與主會話隔離。Subagents 不繼承您的對話歷史或調用的 skills。

hooks.md +1 −1

Details

732# Notification hook：當 Claude Code 需要注意時 ping 桌面。732# Notification hook：當 Claude Code 需要注意時 ping 桌面。

733input=$(cat)733input=$(cat)

734title="Claude Code'734title="Claude Code'

735body=$(jq -r '.message // 'Needs your attention"' <<<"$input")735body=$(jq -r '.message // 'Needs your attention'' <<<"$input")

736seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")736seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")

737jq -nc --arg seq "$seq" '{terminalSequence: $seq}'737jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

738```738```

hooks-guide.md +5 −3

Details

910* 驗證您的 JSON 有效（不允許尾隨逗號和註解）910* 驗證您的 JSON 有效（不允許尾隨逗號和註解）

911* 確認設定檔在正確的位置：`.claude/settings.json` 用於專案 hooks，`~/.claude/settings.json` 用於全域 hooks911* 確認設定檔在正確的位置：`.claude/settings.json` 用於專案 hooks，`~/.claude/settings.json` 用於全域 hooks

912 912

913### Stop hook 永遠執行913### Stop hook 觸發區塊上限

914 914

915Claude 在無限迴圈中繼續工作而不是停止。915Claude 繼續工作而不是停止，然後以警告結束回合，表示 Stop hook 連續阻止了太多次。

916 916

917您的 Stop hook 指令需要檢查它是否已經觸發了延續。從 JSON 輸入解析 `stop_hook_active` 欄位，如果為 `true` 則提前退出：917Claude Code 在 Stop hook 連續阻止 8 次而沒有進展後會覆寫它。您的 hook 指令需要檢查它是否已經觸發了延續。從 JSON 輸入解析 `stop_hook_active` 欄位，如果為 `true` 則提前退出：

918 918

919```bash theme={null}919```bash theme={null}

920#!/bin/bash920#!/bin/bash

925# ... 您的 hook 邏輯的其餘部分925# ... 您的 hook 邏輯的其餘部分

926```926```

927 927

928如果您的 hook 合理地需要超過八次迭代才能收斂，使用 [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/zh-TW/env-vars) 提高上限。

929

928### JSON 驗證失敗930### JSON 驗證失敗

929 931

930Claude Code 顯示 JSON 解析錯誤，即使您的 hook 指令輸出有效的 JSON。932Claude Code 顯示 JSON 解析錯誤，即使您的 hook 指令輸出有效的 JSON。

mcp.md +3 −1

Details

143 143

144`/mcp` 面板會在每個已連接的 server 旁邊顯示工具計數，並標記宣告工具功能但未公開任何工具的 servers。144`/mcp` 面板會在每個已連接的 server 旁邊顯示工具計數，並標記宣告工具功能但未公開任何工具的 servers。

145 145

146如果您的請求需要來自仍在背景連接的 server 的工具，Claude 會在繼續之前等待該 server。啟用 [tool search](#scale-with-mcp-tool-search)（預設啟用）後，等待會在 `ToolSearch` 呼叫內進行。在沒有工具搜尋的配置中，例如 Vertex AI、自訂 `ANTHROPIC_BASE_URL` 或 `ENABLE_TOOL_SEARCH=false`，Claude 會改用 `WaitForMcpServers` 工具。

147

146server 名稱 `workspace` 保留供內部使用。如果您的配置定義了具有該名稱的 server，Claude Code 會在載入時跳過它，並顯示警告要求您重新命名它。148server 名稱 `workspace` 保留供內部使用。如果您的配置定義了具有該名稱的 server，Claude Code 會在載入時跳過它，並顯示警告要求您重新命名它。

147 149

148### 動態工具更新150### 動態工具更新

1007 1009

1008`alwaysLoad` 欄位在所有伺服器類型上可用，需要 Claude Code v2.1.121 或更新版本。MCP 伺服器也可以透過在工具的 `_meta` 物件中包含 `"anthropic/alwaysLoad": true` 來標記個別工具為始終載入，這對該工具只有相同的效果。1010`alwaysLoad` 欄位在所有伺服器類型上可用，需要 Claude Code v2.1.121 或更新版本。MCP 伺服器也可以透過在工具的 `_meta` 物件中包含 `"anthropic/alwaysLoad": true` 來標記個別工具為始終載入，這對該工具只有相同的效果。

1009 1011

1010設定 `alwaysLoad: true` 也會阻止啟動直到伺服器連線，上限為標準 5 秒連線逾時。即使設定了 [`MCP_CONNECTION_NONBLOCKING=1`](/zh-TW/env-vars)，這也適用，因為工具必須在建立第一個提示時存在。當啟用非阻塞時，其他伺服器仍在背景中連線。1012設定 `alwaysLoad: true` 也會阻止啟動直到伺服器連線，上限為標準 5 秒連線逾時。即使 MCP 啟動在其他方面[預設為非阻塞](/zh-TW/env-vars)，這也適用，因為工具必須在建立第一個提示時存在。其他伺服器繼續在背景中連線。

1011 1013

1012## 使用 MCP 提示作為命令1014## 使用 MCP 提示作為命令

1013 1015

model-config.md +2 −2

Details

284您可以使用以下環境變數，這些變數必須是完整的**模型名稱**（或您的 API 提供者的等效項），以控制別名對應到的模型名稱。284您可以使用以下環境變數，這些變數必須是完整的**模型名稱**（或您的 API 提供者的等效項），以控制別名對應到的模型名稱。

285 285

286| 環境變數 | 描述 |286| 環境變數 | 描述 |

287| -------------------------------- | ----------------------------------------------------------- |287| -------------------------------- | ----------------------------------------------------------------------------------------------------------- |

292 292

293注意：`ANTHROPIC_SMALL_FAST_MODEL` 已棄用，改用 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。293注意：`ANTHROPIC_SMALL_FAST_MODEL` 已棄用，改用 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。

294 294

overview.md +1 −1

Details

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.

4 4

~~5# Claude Code 概述~~5# 概述

6 6

7> Claude Code 是一個代理編碼工具，可以讀取您的程式碼庫、編輯檔案、執行命令，並與您的開發工具整合。可在您的終端機、IDE、桌面應用程式和瀏覽器中使用。7> Claude Code 是一個代理編碼工具，可以讀取您的程式碼庫、編輯檔案、執行命令，並與您的開發工具整合。可在您的終端機、IDE、桌面應用程式和瀏覽器中使用。

8 8

permission-modes.md +4 −2

Details

73 | Auto mode | `auto` |73 | Auto mode | `auto` |

74 | 繞過權限 | `bypassPermissions` |74 | 繞過權限 | `bypassPermissions` |

75 75

76 Auto mode 在您在擴充設定中啟用**允許危險跳過權限**後出現在模式指示器中，但它保持不可用，直到您的帳戶符合 [auto 模式部分](#eliminate-prompts-with-auto-mode)中列出的每項要求。`claudeCode.initialPermissionMode` 設定不接受 `auto`；要預設啟動 auto mode，請改為在您的 Claude Code [`settings.json`](/zh-TW/settings#settings-files) 中設定 `defaultMode`。76 Auto mode 在您在擴充設定中啟用**允許危險跳過權限**後出現在模式指示器中，但它保持不可用，直到您的帳戶符合 [auto 模式部分](#eliminate-prompts-with-auto-mode)中列出的每項要求。`claudeCode.initialPermissionMode` 設定不接受 `auto`；要預設啟動 auto mode，請改為在您的[使用者設定](/zh-TW/settings#settings-files)中設定 `defaultMode`。Claude Code 忽略專案和本機設定中的 `defaultMode: "auto"`。

77 77

78 繞過權限也需要**允許危險跳過權限**切換，然後才會在模式指示器中出現。78 繞過權限也需要**允許危險跳過權限**切換，然後才會在模式指示器中出現。

79 79

92 在 [claude.ai/code](https://claude.ai/code) 或行動應用中使用提示框旁邊的模式下拉菜單。權限提示出現在 claude.ai 中以供批准。哪些模式出現取決於會話執行的位置：92 在 [claude.ai/code](https://claude.ai/code) 或行動應用中使用提示框旁邊的模式下拉菜單。權限提示出現在 claude.ai 中以供批准。哪些模式出現取決於會話執行的位置：

93 93

94 * **雲端會話**在 [Claude Code on the web](/zh-TW/claude-code-on-the-web)：Auto accept edits 和 Plan mode。Ask permissions、Auto 和 Bypass permissions 不可用。94 * **雲端會話**在 [Claude Code on the web](/zh-TW/claude-code-on-the-web)：Auto accept edits 和 Plan mode。Ask permissions、Auto 和 Bypass permissions 不可用。

~~95 * **[Remote Control](/zh-TW/remote-control) 會話**在您的本地機器上：Ask permissions、Auto accept edits 和 Plan mode。Auto 和 Bypass permissions 不可用。~~95 * **[Remote Control](/zh-TW/remote-control) 會話**在您的本機上：Ask permissions、Auto accept edits 和 Plan mode。Auto 和 Bypass permissions 不可用。

96 96

97 對於 Remote Control，您也可以在啟動主機時設定啟動模式：97 對於 Remote Control，您也可以在啟動主機時設定啟動模式：

98 98

179 179

180如果 Claude Code 報告 auto mode 不可用，其中一項要求未滿足；這不是暫時性中斷。單獨的訊息命名模型並說 auto mode「無法確定」操作的安全性是暫時性分類器中斷；請參閱[錯誤參考](/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action)。180如果 Claude Code 報告 auto mode 不可用，其中一項要求未滿足；這不是暫時性中斷。單獨的訊息命名模型並說 auto mode「無法確定」操作的安全性是暫時性分類器中斷；請參閱[錯誤參考](/zh-TW/errors#auto-mode-cannot-determine-the-safety-of-an-action)。

181 181

182如果您在[設定](/zh-TW/settings#available-settings)中設定 `defaultMode: "auto"` 並且會話以 `default` 模式啟動且沒有錯誤，該設定可能在 `.claude/settings.json` 或 `.claude/settings.local.json` 中。Claude Code 忽略來自這些檔案的 `auto`，因此倉庫無法授予自己 auto mode。將其移至 `~/.claude/settings.json`。

183

182### 分類器預設阻止的內容184### 分類器預設阻止的內容

183 185

184分類器信任您的工作目錄和您的倉庫配置的遠端。其他所有內容都被視為外部，直到您[配置受信任的基礎設施](/zh-TW/auto-mode-config)。186分類器信任您的工作目錄和您的倉庫配置的遠端。其他所有內容都被視為外部，直到您[配置受信任的基礎設施](/zh-TW/auto-mode-config)。

plugin-dependencies.md +24 −0

Details

114 114

115當您卸載最後一個限制依賴的 plugin 時，依賴不再被保持，並在下次更新時恢復追蹤其 marketplace 條目。115當您卸載最後一個限制依賴的 plugin 時，依賴不再被保持，並在下次更新時恢復追蹤其 marketplace 條目。

116 116

117## 啟用或禁用具有依賴的 plugin

118

119啟用 plugin 也會啟用它所依賴的 plugins，禁用 plugin 如果另一個已啟用的 plugin 仍然需要它則會被阻止。這兩種行為都需要 Claude Code v2.1.143 或更新版本。較早的版本只會啟用或禁用命名的 plugin，並在下次載入時出現 `dependency-unsatisfied` 錯誤。

120

121當您啟用 plugin 時，Claude Code 也會在相同的範圍內啟用其依賴。如果依賴有其自己的依賴，Claude Code 也會啟用那些。成功訊息會列出隨著您命名的 plugin 一起啟用的其他內容。如果依賴無法啟用，命令會拒絕並告訴您什麼在阻止以及如何修復：

122

123| 條件 | 結果 |

124| :-------------------------- | :------------------------------------------ |

125| 依賴未安裝 | 啟用失敗並為每個遺失的依賴列印 `claude plugin install` 命令。 |

126| 依賴被您組織的 plugin 政策阻止 | 啟用失敗並命名被阻止的依賴。 |

127| 依賴在優先級高於目標範圍的範圍內設置為 `false` | 啟用失敗。在該範圍內啟用依賴，或傳遞 `--scope` 以在那裡寫入。 |

128| 所有依賴都已安裝且被允許 | 啟用成功並為 plugin 和每個在目標範圍內尚未啟用的依賴寫入 `true`。 |

129

130當您禁用 plugin 時，Claude Code 拒絕如果另一個已啟用的 plugin 仍然依賴它。錯誤命名依賴它的 plugins 並給您一個鏈接命令，以正確的順序禁用它們，以您要求的那個結尾。

131

132例如，如果 `deploy-kit` 依賴 `secrets-vault`，單獨禁用 `secrets-vault` 失敗，輸出類似於以下內容：

133

134```text theme={null}

135secrets-vault is still required by deploy-kit. Disable that plugin first, or

136disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools

137```

138

139從錯誤複製鏈接命令以在一個步驟中禁用完整集合。

140

117## 移除孤立的自動安裝依賴141## 移除孤立的自動安裝依賴

118 142

119自動安裝的依賴在安裝它們的 plugins 被卸載後仍會保留在磁碟上，以防您重新安裝依賴 plugin 或想要直接繼續使用依賴。若要清理它們，請執行 `claude plugin prune` 以列出不再有任何已安裝 plugin 需要的自動安裝依賴，並在確認提示後移除它們。這需要 Claude Code v2.1.121 或更新版本。143自動安裝的依賴在安裝它們的 plugins 被卸載後仍會保留在磁碟上，以防您重新安裝依賴 plugin 或想要直接繼續使用依賴。若要清理它們，請執行 `claude plugin prune` 以列出不再有任何已安裝 plugin 需要的自動安裝依賴，並在確認提示後移除它們。這需要 Claude Code v2.1.121 或更新版本。

plugin-marketplaces.md +2 −1

Details

162 162

163<Note>163<Note>

164 **保留名稱**：以下 marketplace 名稱保留供 Anthropic 官方使用，第三方 marketplace 無法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`knowledge-work-plugins`、`life-sciences`。模仿官方 marketplace 的名稱（如 `official-claude-plugins` 或 `anthropic-tools-v2`）也被阻止。164 **保留名稱**：以下 marketplace 名稱保留供 Anthropic 官方使用，第三方 marketplace 無法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`knowledge-work-plugins`、`life-sciences`。模仿官方 marketplace 的名稱（如 `official-claude-plugins` 或 `anthropic-tools-v2`）也被阻止。

165</Note>165</Note>

166 166

167### 擁有者欄位167### 擁有者欄位

200 200

201| 欄位 | 類型 | 描述 |201| 欄位 | 類型 | 描述 |

202| :------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------- |202| :------------ | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------- |

203| `displayName` | string | {/* min-version: 2.1.143 */}在 UI 介面中顯示的人類可讀名稱。當省略時回退到 `name`。可以包含空格和任何大小寫。不用於命名空間或查詢。需要 Claude Code v2.1.143 或更新版本。 |

204| `version` | string | Plugin 版本。如果設定（在此處或在 `plugin.json` 中），plugin 會固定到此字串，使用者只有在版本變更時才會收到更新。省略以回退到 git commit SHA。請參閱 [版本解析](#version-resolution-and-release-channels)。 |205| `version` | string | Plugin 版本。如果設定（在此處或在 `plugin.json` 中），plugin 會固定到此字串，使用者只有在版本變更時才會收到更新。省略以回退到 git commit SHA。請參閱 [版本解析](#version-resolution-and-release-channels)。 |

plugins-reference.md +8 −3

Details

367```json theme={null}367```json theme={null}

368{368{

369 "name": "plugin-name",369 "name": "plugin-name",

370 "displayName": "Plugin Name",

370 "version": "1.2.0",371 "version": "1.2.0",

371 "description": "Brief plugin description",372 "description": "Brief plugin description",

372 "author": {373 "author": {

411| 欄位 | 類型 | 描述 | 範例 |412| 欄位 | 類型 | 描述 | 範例 |

412| :------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |413| :------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |

415| `displayName` | string | {/* min-version: 2.1.143 */}在 `/plugin` 選擇器和其他 UI 介面中顯示的人類可讀名稱。當省略時回退到 `name`。與 `name` 不同，可能包含空格和任何大小寫。不用於命名空間或查詢。需要 Claude Code v2.1.143 或更新版本。 | `"Deployment Tools"` |

414| `version` | string | 選用。語義版本。設定此項會將 plugin 固定到該版本字串，因此使用者只會在您提升版本時收到更新。如果省略，Claude Code 會回退到 git commit SHA，因此每個 commit 都被視為新版本。如果也在 marketplace 項目中設定，`plugin.json` 優先。請參閱[Version management](#version-management)。 | `"2.1.0"` |416| `version` | string | 選用。語義版本。設定此項會將 plugin 固定到該版本字串，因此使用者只會在您提升版本時收到更新。如果省略，Claude Code 會回退到 git commit SHA，因此每個 commit 都被視為新版本。如果也在 marketplace 項目中設定，`plugin.json` 優先。請參閱[Version management](#version-management)。 | `"2.1.0"` |

416| `author` | object | 作者資訊 | `{"name": "Dev Team", "email": "dev@company.com"}` |418| `author` | object | 作者資訊 | `{"name": "Dev Team", "email": "dev@company.com"}` |

525* 可以將多個路徑指定為陣列527* 可以將多個路徑指定為陣列

526* 當 skill 路徑指向直接包含 `SKILL.md` 的目錄時，例如 `"skills": ["./"]` 指向 plugin 根目錄，frontmatter 中的 `name` 欄位決定 skill 的叫用名稱。這提供了一個穩定的名稱，無論安裝目錄如何。如果 frontmatter 中未設定 `name`，目錄基名將用作後備。528* 當 skill 路徑指向直接包含 `SKILL.md` 的目錄時，例如 `"skills": ["./"]` 指向 plugin 根目錄，frontmatter 中的 `name` 欄位決定 skill 的叫用名稱。這提供了一個穩定的名稱，無論安裝目錄如何。如果 frontmatter 中未設定 `name`，目錄基名將用作後備。

527 529

530在其根目錄中具有 `SKILL.md`、沒有 `skills/` 子目錄且沒有 `skills` manifest 欄位的 plugin 在 Claude Code v2.1.142 及更新版本中會自動載入為單一 skill plugin。您不需要在 `plugin.json` 中設定 `"skills": ["./"]` 來進行此配置。skill 的叫用名稱遵循相同的規則：frontmatter `name` 欄位，或目錄基名作為後備。

531

528**路徑範例**：532**路徑範例**：

529 533

530```json theme={null}534```json theme={null}

814 818

815### plugin enable819### plugin enable

816 820

817啟用已停用的 plugin。821啟用已停用的 plugin。如果 plugin 宣告 [dependencies](/zh-TW/plugin-dependencies)，Claude Code 會在相同範圍內以傳遞方式啟用它們，當相依性未安裝時命令會失敗。

818 822

819```bash theme={null}823```bash theme={null}

820claude plugin enable <plugin> [options]824claude plugin enable <plugin> [options]

833 837

834### plugin disable838### plugin disable

835 839

836停用 plugin 而不卸載它。840停用 plugin 而不卸載它。當另一個已啟用的 plugin [depends on](/zh-TW/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) 目標時失敗。錯誤訊息包含一個鏈式命令，該命令會先停用每個相依項。

837 841

838```bash theme={null}842```bash theme={null}

839claude plugin disable <plugin> [options]843claude plugin disable <plugin> [options]

889 893

890### plugin details894### plugin details

891 895

892顯示 plugin 的元件清單和預計的 token 成本。輸出列出 plugin 貢獻的所有元件，分組為 Skills（技能和命令）、Agents、Hooks 和 MCP servers，以及它為每個工作階段新增多少 tokens 的估計。896顯示 plugin 的元件清單和預計的 token 成本。輸出列出 plugin 貢獻的所有元件，分組為 Skills、Agents、Hooks、MCP servers 和 LSP servers，以及它為每個工作階段新增多少 tokens 的估計。Skills 群組包括 `skills/` 和 `commands/` 項目。

893 897

894```bash theme={null}898```bash theme={null}

895claude plugin details <name>899claude plugin details <name>

922 Agents (0)926 Agents (0)

923 Hooks (1) (harness-only — no model context cost)927 Hooks (1) (harness-only — no model context cost)

924 MCP servers (0)928 MCP servers (0)

929 LSP servers (0)

925 930

926Projected token cost931Projected token cost

927 Always-on: ~180 tok added to every session932 Always-on: ~180 tok added to every session

remote-control.md +1 −1

Details

188* **本地程序必須保持執行**：Remote Control 作為本地程序執行。如果您關閉終端機、退出 VS Code 或以其他方式停止 `claude` 程序，會話結束。188* **本地程序必須保持執行**：Remote Control 作為本地程序執行。如果您關閉終端機、退出 VS Code 或以其他方式停止 `claude` 程序，會話結束。

189* **延長的網路中斷**：如果您的機器處於喚醒狀態但無法在大約 10 分鐘以上的時間內到達網路，會話會逾時並且程序退出。再次執行 `claude remote-control` 以啟動新會話。189* **延長的網路中斷**：如果您的機器處於喚醒狀態但無法在大約 10 分鐘以上的時間內到達網路，會話會逾時並且程序退出。再次執行 `claude remote-control` 以啟動新會話。

190* **Ultraplan 斷開 Remote Control**：啟動 [ultraplan](/zh-TW/ultraplan) 會話會斷開任何活動的 Remote Control 會話，因為兩個功能都佔據 claude.ai/code 介面，一次只能連接一個。190* **Ultraplan 斷開 Remote Control**：啟動 [ultraplan](/zh-TW/ultraplan) 會話會斷開任何活動的 Remote Control 會話，因為兩個功能都佔據 claude.ai/code 介面，一次只能連接一個。

191* **某些命令僅限本地**：在終端機中開啟互動式選擇器的命令，例如 `/mcp`、`/plugin` 或 `/resume`，只能從本地 CLI 使用。產生文字輸出的命令，包括 `/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/extra-usage`、`/recap` 和 `/reload-plugins`，可從行動和網頁使用。191* **某些命令僅限本地**：在終端機中開啟互動式選擇器的命令，例如 `/mcp`、`/plugin` 或 `/resume`，只能從本地 CLI 使用。產生文字輸出的命令，包括 `/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/usage-credits`、`/recap` 和 `/reload-plugins`，可從行動和網頁使用。

192 192

193## 疑難排解193## 疑難排解

194 194

routines.md +1 −1

Details

360 360

361例行程序以與互動式會話相同的方式消耗訂閱使用量。除了標準訂閱限制外，例行程序還有每個帳戶每天可以啟動多少次運行的每日上限。在 [claude.ai/code/routines](https://claude.ai/code/routines) 或 [claude.ai/settings/usage](https://claude.ai/settings/usage) 查看您目前的消耗和剩餘的每日例行程序運行。361例行程序以與互動式會話相同的方式消耗訂閱使用量。除了標準訂閱限制外，例行程序還有每個帳戶每天可以啟動多少次運行的每日上限。在 [claude.ai/code/routines](https://claude.ai/code/routines) 或 [claude.ai/settings/usage](https://claude.ai/settings/usage) 查看您目前的消耗和剩餘的每日例行程序運行。

362 362

363當例行程序達到每日上限或您的訂閱使用限制時，啟用了額外使用的組織可以繼續在計量超額上運行例行程序。沒有額外使用，額外運行會被拒絕，直到時間窗口重置。從 claude.ai 上的 **Settings > Billing** 啟用額外使用。363當例行程序達到每日上限或您的訂閱使用限制時，啟用了使用額度的組織可以繼續在計量超額上運行例行程序。沒有使用額度，額外運行會被拒絕，直到時間窗口重置。從 claude.ai 上的 **Settings > Billing** 啟用使用額度。

364 364

365一次性運行不計入每日例行程序運行上限。它們像任何其他會話一樣消耗您的常規訂閱使用量，但它們不受每個帳戶每日例行程序運行額度的限制。365一次性運行不計入每日例行程序運行上限。它們像任何其他會話一樣消耗您的常規訂閱使用量，但它們不受每個帳戶每日例行程序運行額度的限制。

366 366

scheduled-tasks.md +1 −1

Details

12 12

13排程任務讓 Claude 按間隔自動重新執行提示。使用它們來輪詢部署、監督 PR、檢查長時間執行的建置，或在工作階段稍後提醒自己執行某些操作。若要改為對事件發生時做出反應而不是輪詢，請參閱 [Channels](/zh-TW/channels)：您的 CI 可以直接將失敗推送到工作階段中。若要保持工作階段逐輪執行直到符合條件而不是按間隔執行，請參閱 [`/goal`](/zh-TW/goal)。13排程任務讓 Claude 按間隔自動重新執行提示。使用它們來輪詢部署、監督 PR、檢查長時間執行的建置，或在工作階段稍後提醒自己執行某些操作。若要改為對事件發生時做出反應而不是輪詢，請參閱 [Channels](/zh-TW/channels)：您的 CI 可以直接將失敗推送到工作階段中。若要保持工作階段逐輪執行直到符合條件而不是按間隔執行，請參閱 [`/goal`](/zh-TW/goal)。

14 14

15任務的範圍限於工作階段：它們存在於目前的對話中，當您啟動新的對話時就會停止。使用 `--resume` 或 `--continue` 繼續會恢復任何尚未[過期](#seven-day-expiry)的任務：在過去 7 天內建立的重複執行任務，或排程時間尚未到達的一次性任務。對於獨立於任何工作階段而存在的排程，請使用 [Routines](/zh-TW/routines)、[Desktop 排程任務](/zh-TW/desktop-scheduled-tasks) 或 [GitHub Actions](/zh-TW/github-actions)。15任務的範圍限於工作階段：它們存在於目前的對話中，當您啟動新的對話時就會停止。使用 `--resume` 或 `--continue` 繼續會恢復任何尚未[過期](#seven-day-expiry)的任務：在過去 7 天內建立的重複執行任務，或排程時間尚未到達的一次性任務。對於獨立於任何工作階段而存在的排程，請使用 [Routines](/zh-TW/routines) 在 Anthropic 管理的基礎設施上建立例行程序、設定 [Desktop 排程任務](/zh-TW/desktop-scheduled-tasks)，或使用 [GitHub Actions](/zh-TW/github-actions)。

16 16

17## 比較排程選項17## 比較排程選項

18 18

settings.md +5 −3

Details

265設定 `--worktree` 如何建立和管理 git worktrees。265設定 `--worktree` 如何建立和管理 git worktrees。

266 266

267| 金鑰 | 說明 | 範例 |267| 金鑰 | 說明 | 範例 |

268| :---------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |268| :---------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------ |

269| `worktree.baseRef` | 新 worktrees 分支的來源 ref。`"fresh"`（預設）從 `origin/<default-branch>` 分支以取得與遠端相符的乾淨樹。`"head"` 從您目前的本機 `HEAD` 分支，因此未推送的提交和功能分支狀態存在於 worktree 中。適用於 `--worktree`、`EnterWorktree` 工具和 subagent 隔離 | `"head"` |269| `worktree.baseRef` | 新 worktrees 分支的來源 ref。`"fresh"`（預設）從 `origin/<default-branch>` 分支以取得與遠端相符的乾淨樹。`"head"` 從您目前的本機 `HEAD` 分支，因此未推送的提交和功能分支狀態存在於 worktree 中。適用於 `--worktree`、`EnterWorktree` 工具和 subagent 隔離 | `"head"` |

272| `worktree.bgIsolation` | {/* min-version: 2.1.143 */}[背景工作階段](/zh-TW/agent-view#how-file-edits-are-isolated)的隔離模式。`"worktree"`（預設）在呼叫 `EnterWorktree` 之前阻止主簽出中的 `Edit`/`Write`。`"none"` 讓背景工作直接編輯工作副本。需要 Claude Code v2.1.143 或更新版本 | `"none"` |

272 273

273若要將 gitignored 檔案（如 `.env`）複製到新的 worktrees，請改用專案根目錄中的 [`.worktreeinclude` 檔案](/zh-TW/worktrees#copy-gitignored-files-into-worktrees)，而不是設定。274若要將 gitignored 檔案（如 `.env`）複製到新的 worktrees，請改用專案根目錄中的 [`.worktreeinclude` 檔案](/zh-TW/worktrees#copy-gitignored-files-into-worktrees)，而不是設定。

274 275

275### 權限設定276### 權限設定

276 277

277| 金鑰 | 說明 | 範例 |278| 金鑰 | 說明 | 範例 |

278| :---------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |279| :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------- |

280| `ask` | 要求在工具使用時確認的權限規則陣列。請參閱下面的[權限規則語法](#permission-rule-syntax) | `[ "Bash(git push *)" ]` |281| `ask` | 要求在工具使用時確認的權限規則陣列。請參閱下面的[權限規則語法](#permission-rule-syntax) | `[ "Bash(git push *)" ]` |

281| `deny` | 拒絕工具使用的權限規則陣列。使用此選項從 Claude Code 存取中排除敏感檔案。請參閱[權限規則語法](#permission-rule-syntax)和 [Bash 權限限制](/zh-TW/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |282| `deny` | 拒絕工具使用的權限規則陣列。使用此選項從 Claude Code 存取中排除敏感檔案。請參閱[權限規則語法](#permission-rule-syntax)和 [Bash 權限限制](/zh-TW/permissions#tool-specific-permission-rules) | `[ "WebFetch", "Bash(curl *)", "Read(./.env)", "Read(./secrets/**)" ]` |

282| `additionalDirectories` | Claude 有權存取的其他[工作目錄](/zh-TW/permissions#working-directories)。大多數 `.claude/` 設定[未從這些目錄發現](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |283| `additionalDirectories` | Claude 有權存取的其他[工作目錄](/zh-TW/permissions#working-directories)。大多數 `.claude/` 設定[未從這些目錄發現](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration) | `[ "../docs/" ]` |

283| `defaultMode` | 開啟 Claude Code 時的預設[權限模式](/zh-TW/permission-modes)。有效值：`default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions`。`--permission-mode` CLI 旗標會覆蓋此設定以進行單一工作階段 | `"acceptEdits"` |284| `defaultMode` | 開啟 Claude Code 時的預設[權限模式](/zh-TW/permission-modes)。有效值：`default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions`。{/* min-version: 2.1.142 */}自 Claude Code v2.1.142 起，當在專案或本機設定（`.claude/settings.json`、`.claude/settings.local.json`）中設定時，`auto` 會被忽略，因此儲存庫無法授予自己自動模式。改為在 `~/.claude/settings.json` 中設定它。`--permission-mode` CLI 旗標會覆蓋此設定以進行單一工作階段 | `"acceptEdits"` |

284| `disableBypassPermissionsMode` | 設定為 `"disable"` 以防止啟用 `bypassPermissions` 模式。這會停用 `--dangerously-skip-permissions` 旗標。在[managed 設定](/zh-TW/permissions#managed-settings)中最有用，使用者無法覆蓋它 | `"disable"` |285| `disableBypassPermissionsMode` | 設定為 `"disable"` 以防止啟用 `bypassPermissions` 模式。這會停用 `--dangerously-skip-permissions` 旗標。在[managed 設定](/zh-TW/permissions#managed-settings)中最有用，使用者無法覆蓋它 | `"disable"` |

285| `skipDangerousModePermissionPrompt` | 跳過透過 `--dangerously-skip-permissions` 或 `defaultMode: "bypassPermissions"` 進入 bypass permissions 模式之前顯示的確認提示。在專案設定（`.claude/settings.json`）中設定時被忽略，以防止不受信任的儲存庫自動繞過提示 | `true` |286| `skipDangerousModePermissionPrompt` | 跳過透過 `--dangerously-skip-permissions` 或 `defaultMode: "bypassPermissions"` 進入 bypass permissions 模式之前顯示的確認提示。在專案設定（`.claude/settings.json`）中設定時被忽略，以防止不受信任的儲存庫自動繞過提示 | `true` |

286 287

510 * 由 IT 透過伺服器傳遞、MDM 設定檔案、登錄政策或 managed 設定檔案部署的政策511 * 由 IT 透過伺服器傳遞、MDM 設定檔案、登錄政策或 managed 設定檔案部署的政策

511 * 無法被任何其他層級覆蓋，包括命令列引數512 * 無法被任何其他層級覆蓋，包括命令列引數

512 * 在 managed 層級內，優先順序為：伺服器管理 > MDM/OS 層級政策 > 檔案型（`managed-settings.d/*.json` + `managed-settings.json`）> HKCU 登錄（僅限 Windows）。僅使用一個 managed 來源；來源不合併跨層級。在檔案型層級內，放入檔案和基礎檔案會合併在一起。513 * 在 managed 層級內，優先順序為：伺服器管理 > MDM/OS 層級政策 > 檔案型（`managed-settings.d/*.json` + `managed-settings.json`）> HKCU 登錄（僅限 Windows）。僅使用一個 managed 來源；來源不合併跨層級。在檔案型層級內，放入檔案和基礎檔案會合併在一起。

514 * 嵌入主機（例如 Claude Desktop）可以透過 SDK `managedSettings` 選項提供政策。預設情況下，當任何 managed-settings 層級存在時，此會被忽略。管理員可以透過設定 [`parentSettingsBehavior`](#available-settings) 為 `"merge"` 來選擇加入。嵌入器的值會被篩選，以便它們可以收緊 managed 政策但不能放鬆政策。

513 515

5142. **命令列引數**5162. **命令列引數**

515 * 特定工作階段的臨時覆蓋。JSON 透過 `--settings <file-or-json>` 傳遞會與檔案型設定合併，使用與其他層級相同的規則：此處設定的金鑰會覆蓋本機、專案或使用者設定中的相同金鑰，省略金鑰會保留較低層級的值517 * 特定工作階段的臨時覆蓋。JSON 透過 `--settings <file-or-json>` 傳遞會與檔案型設定合併，使用與其他層級相同的規則：此處設定的金鑰會覆蓋本機、專案或使用者設定中的相同金鑰，省略金鑰會保留較低層級的值

skills.md +3 −3

Details

437Skills 和 [subagents](/zh-TW/sub-agents) 以兩個方向協同運作：437Skills 和 [subagents](/zh-TW/sub-agents) 以兩個方向協同運作：

438 438

439| 方法 | 系統提示 | 任務 | 也載入 |439| 方法 | 系統提示 | 任務 | 也載入 |

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

443 443

444使用 `context: fork`，您在 skill 中編寫任務並選擇代理類型來執行它。對於反向（定義使用 skills 作為參考資料的自訂 subagent），請參閱 [Subagents](/zh-TW/sub-agents#preload-skills-into-subagents)。444使用 `context: fork`，您在 skill 中編寫任務並選擇代理類型來執行它。內建的 Explore 和 Plan 代理[跳過 CLAUDE.md 和 git status](/zh-TW/sub-agents#what-loads-at-startup)以保持其上下文較小，因此使用 `agent: Explore` 的分叉 skill 只看到 SKILL.md 內容和代理自己的系統提示。對於反向情況，其中您定義使用 skills 作為參考資料的自訂 subagent，請參閱 [Subagents](/zh-TW/sub-agents#preload-skills-into-subagents)。

445 445

446#### 範例：使用 Explore 代理的研究 skill446#### 範例：使用 Explore 代理的研究 skill

447 447

statusline.md +2 −1

Details

916 916

917### Windows 設定917### Windows 設定

918 918

919在 Windows 上，Claude Code 透過 Git Bash 執行狀態列命令（如果已安裝 Git Bash），或在 Git Bash 不存在時透過 PowerShell 執行。若要執行 PowerShell 指令碼作為您的狀態列，請透過 `powershell` 呼叫它；這在任一 shell 中都有效：919在 Windows 上，Claude Code 透過 Git Bash 執行狀態列命令（如果已安裝 Git Bash），或在 Git Bash 不存在時透過 PowerShell 執行。若要執行 PowerShell 指令碼作為您的狀態列，請透過 `powershell` 呼叫它。這在任一 shell 中都有效：

920 920

921<CodeGroup>921<CodeGroup>

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

999* 驗證您的指令碼是否可執行：`chmod +x ~/.claude/statusline.sh`999* 驗證您的指令碼是否可執行：`chmod +x ~/.claude/statusline.sh`

1000* 檢查您的指令碼是否輸出到 stdout 而不是 stderr1000* 檢查您的指令碼是否輸出到 stdout 而不是 stderr

1001* 手動執行您的指令碼以驗證它產生輸出1001* 手動執行您的指令碼以驗證它產生輸出

1002* 在安裝了 Git Bash 的 Windows 上，`command` 路徑中的反斜線可能在指令碼執行前被當作逃逸字元消耗。在路徑中使用正斜線。請參閱 [Windows 設定](#windows-configuration)。

1002* 如果 `disableAllHooks` 在您的設定中設定為 `true`，狀態列也會被停用。移除此設定或將其設定為 `false` 以重新啟用。1003* 如果 `disableAllHooks` 在您的設定中設定為 `true`，狀態列也會被停用。移除此設定或將其設定為 `false` 以重新啟用。

1003* 執行 `claude --debug` 以記錄工作階段中第一次狀態列呼叫的結束代碼和 stderr1004* 執行 `claude --debug` 以記錄工作階段中第一次狀態列呼叫的結束代碼和 stderr

1004* 要求 Claude 讀取您的設定檔案並直接執行 `statusLine` 命令以顯示錯誤1005* 要求 Claude 讀取您的設定檔案並直接執行 `statusLine` 命令以顯示錯誤

sub-agents.md +31 −1

Details

37 37

38Claude Code 包括內建 subagents，Claude 在適當時會自動使用。每個都繼承父對話的權限，並有額外的工具限制。38Claude Code 包括內建 subagents，Claude 在適當時會自動使用。每個都繼承父對話的權限，並有額外的工具限制。

39 39

40Explore 和 Plan 會跳過您的 CLAUDE.md 檔案和父工作階段的 git status，以保持研究快速且經濟高效。其他所有內建和[自訂 subagent](#configure-subagents) 都會載入兩者。如需了解到達 subagent 的完整詳細資訊，請參閱[啟動時載入的內容](#what-loads-at-startup)。

40<Tabs>42<Tabs>

41 <Tab title="Explore">43 <Tab title="Explore">

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

652 654

653這適用於內建和自訂 subagents，選擇在您恢復工作階段時持續。655這適用於內建和自訂 subagents，選擇在您恢復工作階段時持續。

654 656

655對於外掛程式提供的 subagent，傳遞限定名稱：`claude --agent <plugin-name>:<agent-name>`。如果 plugin 將 agent 放在其 `agents/` 目錄的子資料夾中，請在限定名稱中包括子資料夾，例如 `claude --agent my-plugin:review:security`。657對於外掛程式提供的 subagent，您可以只傳遞代理名稱，Claude Code 會找到它：

658

659```bash theme={null}

660claude --agent security-reviewer

661```

662

663如果多個外掛程式提供具有相同名稱的代理，傳遞限定名稱以消除歧義：

664

665```bash theme={null}

666claude --agent my-plugin:security-reviewer

667```

668

669如果外掛程式將代理放在其 `agents/` 目錄的子資料夾中，請在限定名稱中包括子資料夾，例如 `claude --agent my-plugin:review:security`。

656 670

657若要使其成為專案中每個工作階段的預設值，請在 `.claude/settings.json` 中設定 `agent`：671若要使其成為專案中每個工作階段的預設值，請在 `.claude/settings.json` 中設定 `agent`：

658 672

741 755

742### 管理 subagent 上下文756### 管理 subagent 上下文

743 757

758#### 啟動時載入的內容

759

760每個 subagent 都以新鮮、隔離的上下文視窗開始。它看不到您的對話歷史記錄、您已經呼叫的技能或 Claude 已經讀取的檔案。Claude 撰寫一條委派訊息來總結任務，subagent 從那裡開始工作。例外是 [fork](#fork-the-current-conversation)，它繼承父對話而不是從頭開始。

761

762非 fork subagent 的初始上下文包含：

763

764* **系統提示**：代理自己的提示加上 Claude Code 附加的環境詳細資訊，而不是完整的 Claude Code 系統提示。自訂 subagents 在 [markdown 正文](#write-subagent-files) 或 `prompt` 欄位中定義它們。內建代理有預定義的提示。

765* **任務訊息**：Claude 在交接工作時編寫的委派提示。

766* **CLAUDE.md 和記憶**：主要對話載入的 [記憶層級](/zh-TW/memory#how-claude-md-files-load) 的每個級別，包括 `~/.claude/CLAUDE.md`、專案規則、`CLAUDE.local.md` 和受管理的政策檔案。內建的 Explore 和 Plan 代理跳過這個。

767* **Git 狀態**：在父工作階段開始時拍攝的快照。當工作目錄不是 Git 儲存庫或當 [`includeGitInstructions`](/zh-TW/settings#available-settings) 為 `false` 時不存在。Explore 和 Plan 無論如何都跳過它。

768* **預載入的技能**：代理的 [`skills` 欄位](#preload-skills-into-subagents) 中命名的任何技能的完整內容。內建代理不預載入技能。

769

770Explore 和 Plan 是唯一省略 CLAUDE.md 和 git 狀態的 subagents。沒有 frontmatter 欄位或每個代理設定來改變哪些代理跳過它們。

771

772主要對話使用完整 CLAUDE.md 上下文讀取 Explore 和 Plan 結果，所以大多數規則不需要到達 subagent 本身。如果規則必須，例如「忽略 `vendor/` 目錄」，在您委派時給 Claude 的提示中重新陳述它。

773

744#### 恢復 subagents774#### 恢復 subagents

745 775

746每個 subagent 呼叫都會建立一個具有新鮮上下文的新實例。若要繼續現有 subagent 的工作而不是重新開始，請要求 Claude 恢復它。776每個 subagent 呼叫都會建立一個具有新鮮上下文的新實例。若要繼續現有 subagent 的工作而不是重新開始，請要求 Claude 恢復它。

tools-reference.md +2 −1

Details

45| `TaskUpdate` | 更新任務狀態、依賴項、詳細資訊或刪除任務 | 否 |45| `TaskUpdate` | 更新任務狀態、依賴項、詳細資訊或刪除任務 | 否 |

46| `TeamCreate` | 建立具有多個隊友的 [agent team](/zh-TW/agent-teams)。僅在設定 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 時可用 | 否 |46| `TeamCreate` | 建立具有多個隊友的 [agent team](/zh-TW/agent-teams)。僅在設定 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 時可用 | 否 |

47| `TeamDelete` | 解散 agent team 並清理隊友程序。僅在設定 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 時可用 | 否 |47| `TeamDelete` | 解散 agent team 並清理隊友程序。僅在設定 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 時可用 | 否 |

48| `TodoWrite` | 管理工作階段任務檢查清單。在非互動模式和 [Agent SDK](/zh-TW/headless) 中可用；互動工作階段改用 TaskCreate、TaskGet、TaskList 和 TaskUpdate | 否 |48| `TodoWrite` | {/* min-version: 2.1.142 */}管理工作階段任務檢查清單。自 v2.1.142 起預設停用，改用 `TaskCreate`、`TaskGet`、`TaskList` 和 `TaskUpdate`。設定 `CLAUDE_CODE_ENABLE_TASKS=0` 以重新啟用 | 否 |

49| `ToolSearch` | 當啟用 [tool search](/zh-TW/mcp#scale-with-mcp-tool-search) 時，搜尋並載入延遲工具 | 否 |49| `ToolSearch` | 當啟用 [tool search](/zh-TW/mcp#scale-with-mcp-tool-search) 時，搜尋並載入延遲工具 | 否 |

50| `WaitForMcpServers` | {/* min-version: 2.1.142 */}等待一個或多個仍在背景連接的 [MCP servers](/zh-TW/mcp)，以便請求可以使用其工具而無需重新啟動工作階段。當所需的伺服器尚未連接時，Claude 會呼叫它。僅在停用 [tool search](/zh-TW/mcp#scale-with-mcp-tool-search) 時出現，因為啟用時 `ToolSearch` 會處理等待 | 否 |

50| `WebFetch` | 從指定 URL 擷取內容。請參閱 [WebFetch 工具行為](#webfetch-tool-behavior) | 是 |51| `WebFetch` | 從指定 URL 擷取內容。請參閱 [WebFetch 工具行為](#webfetch-tool-behavior) | 是 |

51| `WebSearch` | 執行網路搜尋。請參閱 [WebSearch 工具行為](#websearch-tool-behavior) | 是 |52| `WebSearch` | 執行網路搜尋。請參閱 [WebSearch 工具行為](#websearch-tool-behavior) | 是 |

52| `Write` | 建立或覆寫檔案。請參閱 [Write 工具行為](#write-tool-behavior) | 是 |53| `Write` | 建立或覆寫檔案。請參閱 [Write 工具行為](#write-tool-behavior) | 是 |

ultrareview.md +1 −1

Details

56 56

57Pro 和 Max 訂閱者獲得三次免費 ultrareview 執行以試用該功能。這三次執行是每個帳戶的一次性配額，不會刷新。使用完全部三次後，或在免費執行期結束後，每次審查都會計入額外使用量，通常成本為 $5 至 $20，具體取決於變更的大小。一次執行在遠端工作階段開始時計算，因此您提前停止或未能完成的審查仍會使用一次免費執行。對於付費審查，額外使用量僅針對執行的部分計費。57Pro 和 Max 訂閱者獲得三次免費 ultrareview 執行以試用該功能。這三次執行是每個帳戶的一次性配額，不會刷新。使用完全部三次後，或在免費執行期結束後，每次審查都會計入額外使用量，通常成本為 $5 至 $20，具體取決於變更的大小。一次執行在遠端工作階段開始時計算，因此您提前停止或未能完成的審查仍會使用一次免費執行。對於付費審查，額外使用量僅針對執行的部分計費。

58 58

59由於 ultrareview 在免費執行次數外始終按額外使用量計費，您的帳戶或組織必須在啟動付費審查前啟用額外使用量。如果未啟用額外使用量，Claude Code 會阻止啟動並將您連結到計費設定，您可以在那裡開啟它。您也可以執行 `/extra-usage` 來檢查或變更您目前的設定。59由於 ultrareview 在免費執行次數外始終按額外使用量計費，您的帳戶或組織必須在啟動付費審查前啟用額外使用量。如果未啟用額外使用量，Claude Code 會阻止啟動並將您連結到計費設定，您可以在那裡開啟它。您也可以執行 `/usage-credits` 來檢查或變更您目前的設定。

60 60

61## 追蹤執行中的審查61## 追蹤執行中的審查

62 62

Documentation 2026-05-17 01:01 UTC to 2026-05-18 23:59 UTC