309 </Tab>309 </Tab>
310</Tabs>310</Tabs>
311 311
312312對於 HTTP（非流式），請改用 `"type": "http"`。對於可流式傳輸的 HTTP 傳輸，請改用 `"type": "http"`。在 `.mcp.json` 和其他 JSON 配置文件中，`"streamable-http"` 被接受作為 `"http"` 的別名。程式化的 `mcpServers` 選項僅接受 `"http"`。
313 313
314### SDK MCP 伺服器314### SDK MCP 伺服器
315 315
2334 "multiSelect": bool, # Set to true to allow multiple selections2334 "multiSelect": bool, # Set to true to allow multiple selections
2335 }2335 }
2336 ],2336 ],
23372337 "answers": dict | None, # User answers populated by the permission system "answers": dict[str, str | list[str]] | None,
2338 # User answers populated by the permission system. Multi-select
2339 # answers may be a list of labels or a comma-joined string
2338}2340}
2339```2341```
2340 2342
2403```python theme={null}2405```python theme={null}
2404{2406{
2405 "taskId": str, # ID of the background monitor task2407 "taskId": str, # ID of the background monitor task
24062408 "timeoutMs": int, # Timeout deadline in milliseconds "timeoutMs": int, # Timeout deadline in milliseconds (0 when persistent)
2407 "persistent": bool | None, # True when running until TaskStop or session end2409 "persistent": bool | None, # True when running until TaskStop or session end
2408}2410}
2409```2411```
2766 2768
2767```python theme={null}2769```python theme={null}
2768{2770{
27692771 "server": str, #MCP 伺服器名稱 "server": str, # MCP 伺服器名稱
2770 "uri": str, # 要讀取的資源 URI2772 "uri": str, # 要讀取的資源 URI
2771}2773}
2772```2774```
308| `tag` | `string \| null` | 必需 | 標籤字符串，或 `null` 以清除 |308| `tag` | `string \| null` | 必需 | 標籤字符串，或 `null` 以清除 |
309| `options.dir` | `string` | `undefined` | 項目目錄路徑。省略時，搜索所有項目目錄 |309| `options.dir` | `string` | `undefined` | 項目目錄路徑。省略時，搜索所有項目目錄 |
310 310
311### `resolveSettings()`
312
313使用與 CLI 相同的合併引擎為給定目錄解析有效的 Claude Code 設置，無需生成 Claude CLI。在調用 `query()` 之前使用它來檢查 `query()` 調用將看到什麼配置。
314
315<Note>
316 此函數處於 alpha 階段，其 API 在穩定之前可能會更改。它讀取 MDM 源，包括 macOS plist 和 Windows HKLM/HKCU，以與 CLI 啟動保持一致，但不執行管理員配置的 `policyHelper` 子進程。`permissions.defaultMode` 字段從所有層級（包括項目設置）按原樣返回。CLI 在遵守升級權限模式之前應用的信任過濾器不被應用。
317</Note>
318
319```typescript theme={null}
320function resolveSettings(
321 options?: ResolveSettingsOptions
322): Promise<ResolvedSettings>;
323```
324
325#### 參數
326
327`resolveSettings()` 接受單個選項對象。所有字段都是可選的。
328
329| 參數 | 類型 | 默認值 | 描述 |
330| :------------------------------ | :------------------------------------ | :-------------- | :------------------------------------------------------ |
331| `options.cwd` | `string` | `process.cwd()` | 用於解析項目和本地設置的相對目錄 |
332| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | 所有源 | 要加載的文件系統源。傳遞 `[]` 以跳過用戶、項目和本地設置。託管策略設置在所有情況下都會加載 |
333| `options.managedSettings` | `Settings` | `undefined` | 在託管策略優先級別合併的限制性策略層設置。非限制性鍵（如 `model`）會被靜默丟棄 |
334| `options.serverManagedSettings` | `Settings` | `undefined` | 來自 `/api/claude_code/settings` 的服務器託管設置有效負載。非限制性鍵無過濾地通過 |
335
336#### 返回類型：`ResolvedSettings`
337
338`resolveSettings()` 返回一個對象，描述合併的設置和為每個鍵提供的源。
339
340| 屬性 | 類型 | 描述 |
341| :----------- | :-------------------------------------------------- | :------------------------------ |
342| `effective` | `Settings` | 在優先級順序中應用所有啟用源後的合併設置 |
343| `provenance` | `Partial<Record<keyof Settings, ProvenanceEntry>>` | 對於 `effective` 中的每個頂級鍵，哪個源提供了該值 |
344| `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | 每個源的原始設置，按從最低到最高優先級排序 |
345
346#### 示例
347
348下面的示例為項目目錄解析設置並打印控制清理期的源。
349
350```typescript theme={null}
351import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";
352
353const { effective, provenance } = await resolveSettings({
354 cwd: "/path/to/project",
355 settingSources: ["user", "project", "local"],
356});
357
358console.log(`Cleanup period: ${effective.cleanupPeriodDays} days`);
359console.log(`Set by: ${provenance.cleanupPeriodDays?.source}`);
360```
361
311## 類型362## 類型
312 363
313### `Options`364### `Options`
864 | SDKFilesPersistedEvent915 | SDKFilesPersistedEvent
865 | SDKToolUseSummaryMessage916 | SDKToolUseSummaryMessage
866 | SDKRateLimitEvent917 | SDKRateLimitEvent
918 | SDKPermissionDeniedMessage
867 | SDKPromptSuggestionMessage;919 | SDKPromptSuggestionMessage;
868```920```
869 921
1052};1104};
1053```1105```
1054 1106
1107### `SDKPermissionDeniedMessage`
1108
1109當權限系統自動拒絕工具調用而不進行互動式提示時發出的流事件。使用它在發生時在您的 UI 中呈現拒絕，而不是僅觀察隨後的 `is_error` 工具結果。互動式詢問路徑通過 [`canUseTool`](#canusetool) 回調單獨到達您的應用程序。由 `PreToolUse` hook 發出的拒絕不會通過此事件報告。
1110
1111此事件需要 Claude Code v2.1.136 或更高版本。
1112
1113```typescript theme={null}
1114type SDKPermissionDeniedMessage = {
1115 type: "system";
1116 subtype: "permission_denied";
1117 tool_name: string;
1118 tool_use_id: string;
1119 agent_id?: string;
1120 decision_reason_type?: string;
1121 decision_reason?: string;
1122 message: string;
1123 uuid: UUID;
1124 session_id: string;
1125};
1126```
1127
1128| 字段 | 類型 | 描述 |
1129| ---------------------- | -------- | ------------------------------------------------------------- |
1130| `tool_name` | `string` | 被拒絕的工具的名稱 |
1131| `tool_use_id` | `string` | 此拒絕回答的 `tool_use` 塊的 ID |
1132| `agent_id` | `string` | 當被拒絕的調用源自子代理內部時的子代理 ID。鏡像 `can_use_tool` 上的字段以進行主機端路由 |
1133| `decision_reason_type` | `string` | 決定組件的判別器，例如 `"rule"`、`"mode"`、`"classifier"` 或 `"asyncAgent"` |
1134| `decision_reason` | `string` | 來自決定組件的人類可讀原因（如果可用） |
1135| `message` | `string` | 在 `tool_result` 中返回給模型的拒絕消息 |
1136
1055### `SDKPermissionDenial`1137### `SDKPermissionDenial`
1056 1138
1057有關被拒絕的工具使用的信息。1139有關被拒絕的工具使用的信息。
1> ## Documentation Index
2> 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.
4
5# 處理批准和使用者輸入
6
7> 將 Claude 的批准請求和澄清問題呈現給使用者，然後將他們的決定返回給 SDK。
8
9在處理任務時，Claude 有時需要與使用者確認。它可能需要在刪除檔案前獲得許可，或需要詢問新專案應使用哪個資料庫。您的應用程式需要將這些請求呈現給使用者，以便 Claude 可以根據他們的輸入繼續進行。
10
11Claude 在兩種情況下請求使用者輸入：當它需要**使用工具的許可**（例如刪除檔案或執行命令）時，以及當它有**澄清問題**（透過 `AskUserQuestion` 工具）時。兩者都會觸發您的 `canUseTool` 回呼，該回呼會暫停執行，直到您返回回應。這與普通對話輪次不同，在普通對話輪次中 Claude 完成後會等待您的下一條訊息。
12
13對於澄清問題，Claude 會生成問題和選項。您的角色是將它們呈現給使用者並返回他們的選擇。您無法將自己的問題添加到此流程中；如果您需要自己詢問使用者某些事項，請在應用程式邏輯中單獨進行。
14
15回呼可以無限期地保持待處理狀態。執行保持暫停狀態，直到您的回呼返回，SDK 只在查詢本身被取消時才取消等待。如果使用者可能需要比您的流程合理保持運行的時間更長的時間來回應，TypeScript SDK 支援 [`defer` hook 決定](/zh-TW/hooks#defer-a-tool-call-for-later)，它允許流程退出並稍後從持久化會話恢復；此選項在 Python SDK 中不可用。
16
17本指南向您展示如何檢測每種類型的請求並做出適當的回應。
18
19## 檢測 Claude 何時需要輸入
20
21在您的查詢選項中傳遞 `canUseTool` 回呼。每當 Claude 需要使用者輸入時，回呼就會觸發，接收工具名稱和輸入作為參數：
22
23<CodeGroup>
24 ```python Python theme={null}
25 async def handle_tool_request(tool_name, input_data, context):
26 # 提示使用者並返回允許或拒絕
27 ...
28
29
30 options = ClaudeAgentOptions(can_use_tool=handle_tool_request)
31 ```
32
33 ```typescript TypeScript theme={null}
34 async function handleToolRequest(toolName, input, options) {
35 // options includes { signal: AbortSignal, suggestions?: PermissionUpdate[] }
36 // 提示使用者並返回允許或拒絕
37 }
38
39 const options = { canUseTool: handleToolRequest };
40 ```
41</CodeGroup>
42
43回呼在兩種情況下觸發：
44
451. **工具需要批准**：Claude 想要使用未被[權限規則](/zh-TW/agent-sdk/permissions)或模式自動批准的工具。檢查 `tool_name` 以查看工具（例如 `"Bash"`、`"Write"`）。
462. **Claude 提出問題**：Claude 呼叫 `AskUserQuestion` 工具。檢查 `tool_name == "AskUserQuestion"` 以不同方式處理它。如果您指定 `tools` 陣列，請包含 `AskUserQuestion` 以使其正常工作。有關詳細資訊，請參閱[處理澄清問題](#handle-clarifying-questions)。
47
48<Note>
49 要自動允許或拒絕工具而不提示使用者，請改用 [hooks](/zh-TW/agent-sdk/hooks)。Hooks 在 `canUseTool` 之前執行，可以根據您自己的邏輯允許、拒絕或修改請求。您也可以使用 [`PermissionRequest` hook](/zh-TW/agent-sdk/hooks#available-hooks) 在 Claude 等待批准時發送外部通知（Slack、電子郵件、推送）。
50</Note>
51
52## 處理工具批准請求
53
54一旦您在查詢選項中傳遞了 `canUseTool` 回呼，當 Claude 想要使用未自動批准的工具時，它就會觸發。您的回呼接收三個參數：
55
56| 參數 | 描述 |
57| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
58| `toolName` | Claude 想要使用的工具名稱（例如 `"Bash"`、`"Write"`、`"Edit"`） |
59| `input` | Claude 傳遞給工具的參數。內容因工具而異。 |
60| `options` (TS) / `context` (Python) | 其他上下文，包括可選的 `suggestions`（建議的 `PermissionUpdate` 條目以避免重新提示）和取消信號。在 TypeScript 中，`signal` 是 `AbortSignal`；在 Python 中，信號欄位保留供將來使用。有關 Python，請參閱 [`ToolPermissionContext`](/zh-TW/agent-sdk/python#toolpermissioncontext)。 |
61
62`input` 物件包含工具特定的參數。常見範例：
63
64| 工具 | 輸入欄位 |
65| ------- | ------------------------------------- |
66| `Bash` | `command`、`description`、`timeout` |
67| `Write` | `file_path`、`content` |
68| `Edit` | `file_path`、`old_string`、`new_string` |
69| `Read` | `file_path`、`offset`、`limit` |
70
71有關完整的輸入架構，請參閱 SDK 參考：[Python](/zh-TW/agent-sdk/python#tool-input%2Foutput-types) | [TypeScript](/zh-TW/agent-sdk/typescript#tool-input-types)。
72
73您可以向使用者顯示此資訊，以便他們可以決定是否允許或拒絕該操作，然後返回適當的回應。
74
75以下範例要求 Claude 建立和刪除測試檔案。當 Claude 嘗試每個操作時，回呼會將工具請求列印到終端機並提示進行 y/n 批准。
76
77<CodeGroup>
78 ```python Python theme={null}
79 import asyncio
80
81 from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
82 from claude_agent_sdk.types import (
83 HookMatcher,
84 PermissionResultAllow,
85 PermissionResultDeny,
86 ToolPermissionContext,
87 )
88
89
90 async def can_use_tool(
91 tool_name: str, input_data: dict, context: ToolPermissionContext
92 ) -> PermissionResultAllow | PermissionResultDeny:
93 # 顯示工具請求
94 print(f"\nTool: {tool_name}")
95 if tool_name == "Bash":
96 print(f"Command: {input_data.get('command')}")
97 if input_data.get("description"):
98 print(f"Description: {input_data.get('description')}")
99 else:
100 print(f"Input: {input_data}")
101
102 # 獲取使用者批准
103 response = input("Allow this action? (y/n): ")
104
105 # 根據使用者的回應返回允許或拒絕
106 if response.lower() == "y":
107 # 允許：工具使用原始（或修改的）輸入執行
108 return PermissionResultAllow(updated_input=input_data)
109 else:
110 # 拒絕：工具不執行，Claude 看到訊息
111 return PermissionResultDeny(message="User denied this action")
112
113
114 # 必需的解決方法：虛擬 hook 保持流開放以供 can_use_tool 使用
115 async def dummy_hook(input_data, tool_use_id, context):
116 return {"continue_": True}
117
118
119 async def prompt_stream():
120 yield {
121 "type": "user",
122 "message": {
123 "role": "user",
124 "content": "Create a test file in /tmp and then delete it",
125 },
126 }
127
128
129 async def main():
130 async for message in query(
131 prompt=prompt_stream(),
132 options=ClaudeAgentOptions(
133 can_use_tool=can_use_tool,
134 hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},
135 ),
136 ):
137 if isinstance(message, ResultMessage) and message.subtype == "success":
138 print(message.result)
139
140
141 asyncio.run(main())
142 ```
143
144 ```typescript TypeScript theme={null}
145 import { query } from "@anthropic-ai/claude-agent-sdk";
146 import * as readline from "readline";
147
148 // 幫助程式在終端機中提示使用者輸入
149 function prompt(question: string): Promise<string> {
150 const rl = readline.createInterface({
151 input: process.stdin,
152 output: process.stdout
153 });
154 return new Promise((resolve) =>
155 rl.question(question, (answer) => {
156 rl.close();
157 resolve(answer);
158 })
159 );
160 }
161
162 for await (const message of query({
163 prompt: "Create a test file in /tmp and then delete it",
164 options: {
165 canUseTool: async (toolName, input) => {
166 // 顯示工具請求
167 console.log(`\nTool: ${toolName}`);
168 if (toolName === "Bash") {
169 console.log(`Command: ${input.command}`);
170 if (input.description) console.log(`Description: ${input.description}`);
171 } else {
172 console.log(`Input: ${JSON.stringify(input, null, 2)}`);
173 }
174
175 // 獲取使用者批准
176 const response = await prompt("Allow this action? (y/n): ");
177
178 // 根據使用者的回應返回允許或拒絕
179 if (response.toLowerCase() === "y") {
180 // 允許：工具使用原始（或修改的）輸入執行
181 return { behavior: "allow", updatedInput: input };
182 } else {
183 // 拒絕：工具不執行，Claude 看到訊息
184 return { behavior: "deny", message: "User denied this action" };
185 }
186 }
187 }
188 })) {
189 if ("result" in message) console.log(message.result);
190 }
191 ```
192</CodeGroup>
193
194<Note>
195 在 Python 中，`can_use_tool` 需要[串流模式](/zh-TW/agent-sdk/streaming-vs-single-mode)和返回 `{"continue_": True}` 的 `PreToolUse` hook 以保持流開放。沒有此 hook，流會在權限回呼可以被調用之前關閉。
196</Note>
197
198此範例使用 y/n 流程，其中除 `y` 以外的任何輸入都被視為拒絕。在實踐中，您可能會構建一個更豐富的 UI，讓使用者修改請求、提供回饋或完全重定向 Claude。有關所有回應方式，請參閱[回應工具請求](#respond-to-tool-requests)。
199
200### 回應工具請求
201
202您的回呼返回以下兩種回應類型之一：
203
204| 回應 | Python | TypeScript |
205| ------ | ------------------------------------------ | ------------------------------------- |
206| **允許** | `PermissionResultAllow(updated_input=...)` | `{ behavior: "allow", updatedInput }` |
207| **拒絕** | `PermissionResultDeny(message=...)` | `{ behavior: "deny", message }` |
208
209允許時，傳遞工具輸入（原始或修改的）。拒絕時，提供說明原因的訊息。Claude 會看到此訊息並可能調整其方法。
210
211<CodeGroup>
212 ```python Python theme={null}
213 from claude_agent_sdk.types import PermissionResultAllow, PermissionResultDeny
214
215 # 允許工具執行
216 return PermissionResultAllow(updated_input=input_data)
217
218 # 阻止工具
219 return PermissionResultDeny(message="User rejected this action")
220 ```
221
222 ```typescript TypeScript theme={null}
223 // 允許工具執行
224 return { behavior: "allow", updatedInput: input };
225
226 // 阻止工具
227 return { behavior: "deny", message: "User rejected this action" };
228 ```
229</CodeGroup>
230
231除了允許或拒絕之外，您還可以修改工具的輸入或提供幫助 Claude 調整其方法的上下文：
232
233* **批准**：讓工具按 Claude 要求執行
234* **批准並進行更改**：在執行前修改輸入（例如清理路徑、添加約束）
235* **拒絕**：阻止工具並告訴 Claude 原因
236* **建議替代方案**：阻止但引導 Claude 朝著使用者想要的方向發展
237* **完全重定向**：使用[串流輸入](/zh-TW/agent-sdk/streaming-vs-single-mode)向 Claude 發送全新指令
238
239<Tabs>
240 <Tab title="批准">
241 使用者按原樣批准該操作。傳遞回呼中的 `input` 不變，工具完全按 Claude 要求執行。
242
243 <CodeGroup>
244 ```python Python theme={null}
245 async def can_use_tool(tool_name, input_data, context):
246 print(f"Claude wants to use {tool_name}")
247 approved = await ask_user("Allow this action?")
248
249 if approved:
250 return PermissionResultAllow(updated_input=input_data)
251 return PermissionResultDeny(message="User declined")
252 ```
253
254 ```typescript TypeScript theme={null}
255 canUseTool: async (toolName, input) => {
256 console.log(`Claude wants to use ${toolName}`);
257 const approved = await askUser("Allow this action?");
258
259 if (approved) {
260 return { behavior: "allow", updatedInput: input };
261 }
262 return { behavior: "deny", message: "User declined" };
263 };
264 ```
265 </CodeGroup>
266 </Tab>
267
268 <Tab title="批准並進行更改">
269 使用者批准但想先修改請求。您可以在工具執行前更改輸入。Claude 會看到結果，但不會被告知您更改了任何內容。適用於清理參數、添加約束或限制存取範圍。
270
271 <CodeGroup>
272 ```python Python theme={null}
273 async def can_use_tool(tool_name, input_data, context):
274 if tool_name == "Bash":
275 # 使用者批准，但將所有命令限制在沙箱中
276 sandboxed_input = {**input_data}
277 sandboxed_input["command"] = input_data["command"].replace(
278 "/tmp", "/tmp/sandbox"
279 )
280 return PermissionResultAllow(updated_input=sandboxed_input)
281 return PermissionResultAllow(updated_input=input_data)
282 ```
283
284 ```typescript TypeScript theme={null}
285 canUseTool: async (toolName, input) => {
286 if (toolName === "Bash") {
287 // 使用者批准，但將所有命令限制在沙箱中
288 const sandboxedInput = {
289 ...input,
290 command: input.command.replace("/tmp", "/tmp/sandbox")
291 };
292 return { behavior: "allow", updatedInput: sandboxedInput };
293 }
294 return { behavior: "allow", updatedInput: input };
295 };
296 ```
297 </CodeGroup>
298 </Tab>
299
300 <Tab title="拒絕">
301 使用者不希望發生此操作。阻止工具並提供說明原因的訊息。Claude 會看到此訊息並可能嘗試不同的方法。
302
303 <CodeGroup>
304 ```python Python theme={null}
305 async def can_use_tool(tool_name, input_data, context):
306 approved = await ask_user(f"Allow {tool_name}?")
307
308 if not approved:
309 return PermissionResultDeny(message="User rejected this action")
310 return PermissionResultAllow(updated_input=input_data)
311 ```
312
313 ```typescript TypeScript theme={null}
314 canUseTool: async (toolName, input) => {
315 const approved = await askUser(`Allow ${toolName}?`);
316
317 if (!approved) {
318 return {
319 behavior: "deny",
320 message: "User rejected this action"
321 };
322 }
323 return { behavior: "allow", updatedInput: input };
324 };
325 ```
326 </CodeGroup>
327 </Tab>
328
329 <Tab title="建議替代方案">
330 使用者不想要此特定操作，但有不同的想法。阻止工具並在您的訊息中包含指導。Claude 會閱讀此內容並根據您的回饋決定如何進行。
331
332 <CodeGroup>
333 ```python Python theme={null}
334 async def can_use_tool(tool_name, input_data, context):
335 if tool_name == "Bash" and "rm" in input_data.get("command", ""):
336 # 使用者不想刪除，建議改為存檔
337 return PermissionResultDeny(
338 message="User doesn't want to delete files. They asked if you could compress them into an archive instead."
339 )
340 return PermissionResultAllow(updated_input=input_data)
341 ```
342
343 ```typescript TypeScript theme={null}
344 canUseTool: async (toolName, input) => {
345 if (toolName === "Bash" && input.command.includes("rm")) {
346 // 使用者不想刪除，建議改為存檔
347 return {
348 behavior: "deny",
349 message:
350 "User doesn't want to delete files. They asked if you could compress them into an archive instead."
351 };
352 }
353 return { behavior: "allow", updatedInput: input };
354 };
355 ```
356 </CodeGroup>
357 </Tab>
358
359 <Tab title="完全重定向">
360 如需完全改變方向（不只是輕推），請使用[串流輸入](/zh-TW/agent-sdk/streaming-vs-single-mode)向 Claude 直接發送新指令。這會繞過目前的工具請求，並為 Claude 提供全新的指令來遵循。
361 </Tab>
362</Tabs>
363
364## 處理澄清問題
365
366當 Claude 需要在具有多個有效方法的任務上獲得更多方向時，它會呼叫 `AskUserQuestion` 工具。這會使用 `toolName` 設定為 `AskUserQuestion` 的方式觸發您的 `canUseTool` 回呼。輸入包含 Claude 的問題作為多選選項，您將其顯示給使用者並返回他們的選擇。
367
368<Tip>
369 澄清問題在 [`plan` 模式](/zh-TW/agent-sdk/permissions#plan-mode-plan)中特別常見，Claude 在其中探索程式碼庫並在提出計畫前提出問題。這使得計畫模式非常適合互動式工作流程，您希望 Claude 在進行更改前收集需求。
370</Tip>
371
372以下步驟顯示如何處理澄清問題：
373
374<Steps>
375 <Step title="傳遞 canUseTool 回呼">
376 在您的查詢選項中傳遞 `canUseTool` 回呼。預設情況下，`AskUserQuestion` 可用。如果您指定 `tools` 陣列來限制 Claude 的功能（例如，只有 `Read`、`Glob` 和 `Grep` 的唯讀代理），請在該陣列中包含 `AskUserQuestion`。否則，Claude 將無法提出澄清問題：
377
378 <CodeGroup>
379 ```python Python theme={null}
380 async for message in query(
381 prompt="Analyze this codebase",
382 options=ClaudeAgentOptions(
383 # 在您的工具清單中包含 AskUserQuestion
384 tools=["Read", "Glob", "Grep", "AskUserQuestion"],
385 can_use_tool=can_use_tool,
386 ),
387 ):
388 print(message)
389 ```
390
391 ```typescript TypeScript theme={null}
392 for await (const message of query({
393 prompt: "Analyze this codebase",
394 options: {
395 // 在您的工具清單中包含 AskUserQuestion
396 tools: ["Read", "Glob", "Grep", "AskUserQuestion"],
397 canUseTool: async (toolName, input) => {
398 // 在此處處理澄清問題
399 }
400 }
401 })) {
402 console.log(message);
403 }
404 ```
405 </CodeGroup>
406 </Step>
407
408 <Step title="檢測 AskUserQuestion">
409 在您的回呼中，檢查 `toolName` 是否等於 `AskUserQuestion` 以不同方式處理它與其他工具：
410
411 <CodeGroup>
412 ```python Python theme={null}
413 async def can_use_tool(tool_name: str, input_data: dict, context):
414 if tool_name == "AskUserQuestion":
415 # 您從使用者收集答案的實現
416 return await handle_clarifying_questions(input_data)
417 # 正常處理其他工具
418 return await prompt_for_approval(tool_name, input_data)
419 ```
420
421 ```typescript TypeScript theme={null}
422 canUseTool: async (toolName, input) => {
423 if (toolName === "AskUserQuestion") {
424 // 您從使用者收集答案的實現
425 return handleClarifyingQuestions(input);
426 }
427 // 正常處理其他工具
428 return promptForApproval(toolName, input);
429 };
430 ```
431 </CodeGroup>
432 </Step>
433
434 <Step title="解析問題輸入">
435 輸入在 `questions` 陣列中包含 Claude 的問題。每個問題都有 `question`（要顯示的文字）、`options`（選擇）和 `multiSelect`（是否允許多個選擇）：
436
437 ```json theme={null}
438 {
439 "questions": [
440 {
441 "question": "How should I format the output?",
442 "header": "Format",
443 "options": [
444 { "label": "Summary", "description": "Brief overview" },
445 { "label": "Detailed", "description": "Full explanation" }
446 ],
447 "multiSelect": false
448 },
449 {
450 "question": "Which sections should I include?",
451 "header": "Sections",
452 "options": [
453 { "label": "Introduction", "description": "Opening context" },
454 { "label": "Conclusion", "description": "Final summary" }
455 ],
456 "multiSelect": true
457 }
458 ]
459 }
460 ```
461
462 有關完整欄位描述，請參閱[問題格式](#question-format)。
463 </Step>
464
465 <Step title="從使用者收集答案">
466 向使用者呈現問題並收集他們的選擇。您如何執行此操作取決於您的應用程式：終端機提示、網路表單、行動對話框等。
467 </Step>
468
469 <Step title="將答案返回給 Claude">
470 將 `answers` 物件構建為記錄，其中每個鍵是 `question` 文字，每個值是所選選項的 `label`：
471
472 | 來自問題物件 | 用作 |
473 | ----------------------------------------------------- | -- |
474 | `question` 欄位（例如 `"How should I format the output?"`） | 鍵 |
475 | 所選選項的 `label` 欄位（例如 `"Summary"`） | 值 |
476
477 對於多選問題，傳遞標籤陣列或使用 `", "` 連接它們。如果您[支援自由文字輸入](#support-free-text-input)，請使用使用者的自訂文字作為值。
478
479 <CodeGroup>
480 ```python Python theme={null}
481 return PermissionResultAllow(
482 updated_input={
483 "questions": input_data.get("questions", []),
484 "answers": {
485 "How should I format the output?": "Summary",
486 "Which sections should I include?": ["Introduction", "Conclusion"],
487 },
488 }
489 )
490 ```
491
492 ```typescript TypeScript theme={null}
493 return {
494 behavior: "allow",
495 updatedInput: {
496 questions: input.questions,
497 answers: {
498 "How should I format the output?": "Summary",
499 "Which sections should I include?": "Introduction, Conclusion"
500 }
501 }
502 };
503 ```
504 </CodeGroup>
505 </Step>
506</Steps>
507
508### 問題格式
509
510輸入在 `questions` 陣列中包含 Claude 生成的問題。每個問題都有這些欄位：
511
512| 欄位 | 描述 |
513| ------------- | ------------------------------------------------------------------------------------------------------ |
514| `question` | 要顯示的完整問題文字 |
515| `header` | 問題的簡短標籤（最多 12 個字元） |
516| `options` | 2-4 個選擇的陣列，每個都有 `label` 和 `description`。TypeScript：可選 `preview`（請參閱[下方](#option-previews-type-script)） |
517| `multiSelect` | 如果為 `true`，使用者可以選擇多個選項 |
518
519您的回呼接收的結構：
520
521```json theme={null}
522{
523 "questions": [
524 {
525 "question": "How should I format the output?",
526 "header": "Format",
527 "options": [
528 { "label": "Summary", "description": "Brief overview of key points" },
529 { "label": "Detailed", "description": "Full explanation with examples" }
530 ],
531 "multiSelect": false
532 }
533 ]
534}
535```
536
537#### 選項預覽 (TypeScript)
538
539`toolConfig.askUserQuestion.previewFormat` 為每個選項添加 `preview` 欄位，以便您的應用程式可以在標籤旁邊顯示視覺模型。沒有此設定，Claude 不會生成預覽，該欄位不存在。
540
541| `previewFormat` | `preview` 包含 |
542| :-------------- | :----------------------------------------------------------------- |
543| 未設定（預設） | 欄位不存在。Claude 不會生成預覽。 |
544| `"markdown"` | ASCII 藝術和圍欄程式碼區塊 |
545| `"html"` | 樣式的 `<div>` 片段（SDK 在您的回呼執行前拒絕 `<script>`、`<style>` 和 `<!DOCTYPE>`） |
546
547該格式適用於會話中的所有問題。Claude 在視覺比較有幫助的選項上包含 `preview`（佈局選擇、配色方案），並在不會的地方省略它（是/否確認、純文字選擇）。在呈現前檢查 `undefined`。
548
549```typescript theme={null}
550import { query } from "@anthropic-ai/claude-agent-sdk";
551
552for await (const message of query({
553 prompt: "Help me choose a card layout",
554 options: {
555 toolConfig: {
556 askUserQuestion: { previewFormat: "html" }
557 },
558 canUseTool: async (toolName, input) => {
559 // input.questions[].options[].preview 是 HTML 字串或 undefined
560 return { behavior: "allow", updatedInput: input };
561 }
562 }
563})) {
564 // ...
565}
566```
567
568帶有 HTML 預覽的選項：
569
570```json theme={null}
571{
572 "label": "Compact",
573 "description": "Title and metric value only",
574 "preview": "<div style=\"padding:12px;border:1px solid #ddd;border-radius:8px\"><div style=\"font-size:12px;color:#666\">Active users</div><div style=\"font-size:28px;font-weight:600\">1,284</div></div>"
575}
576```
577
578### 回應格式
579
580返回 `answers` 物件，將每個問題的 `question` 欄位對應到所選選項的 `label`：
581
582| 欄位 | 描述 |
583| ----------- | ------------------ |
584| `questions` | 傳遞原始問題陣列（工具處理所需） |
585| `answers` | 物件，其中鍵是問題文字，值是所選標籤 |
586
587對於多選問題，傳遞標籤陣列或使用 `", "` 連接它們。對於自由文字輸入，直接使用使用者的自訂文字。
588
589```json theme={null}
590{
591 "questions": [
592 // ...
593 ],
594 "answers": {
595 "How should I format the output?": "Summary",
596 "Which sections should I include?": ["Introduction", "Conclusion"]
597 }
598}
599```
600
601#### 支援自由文字輸入
602
603Claude 的預定義選項不會總是涵蓋使用者想要的內容。要讓使用者輸入自己的答案：
604
605* 在 Claude 的選項後顯示額外的「其他」選擇，接受文字輸入
606* 使用使用者的自訂文字作為答案值（不是「其他」一詞）
607
608有關完整實現，請參閱下方的[完整範例](#complete-example)。
609
610### 完整範例
611
612當 Claude 需要使用者輸入以繼續時，它會提出澄清問題。例如，當被要求幫助決定行動應用程式的技術堆棧時，Claude 可能會詢問跨平台與原生、後端偏好或目標平台。這些問題幫助 Claude 做出與使用者偏好相符的決定，而不是猜測。
613
614此範例在終端機應用程式中處理這些問題。以下是每個步驟發生的情況：
615
6161. **路由請求**：`canUseTool` 回呼檢查工具名稱是否為 `"AskUserQuestion"` 並路由到專用處理程式
6172. **顯示問題**：處理程式循環遍歷 `questions` 陣列並列印每個問題及編號選項
6183. **收集輸入**：使用者可以輸入數字以選擇選項，或直接輸入自由文字（例如「jquery」、「i don't know」）
6194. **對應答案**：程式碼檢查輸入是否為數字（使用選項的標籤）或自由文字（直接使用文字）
6205. **返回給 Claude**：回應包括原始 `questions` 陣列和 `answers` 對應
621
622<CodeGroup>
623 ```python Python theme={null}
624 import asyncio
625
626 from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query
627 from claude_agent_sdk.types import HookMatcher, PermissionResultAllow
628
629
630 def parse_response(response: str, options: list) -> str:
631 """將使用者輸入解析為選項編號或自由文字。"""
632 try:
633 indices = [int(s.strip()) - 1 for s in response.split(",")]
634 labels = [options[i]["label"] for i in indices if 0 <= i < len(options)]
635 return ", ".join(labels) if labels else response
636 except ValueError:
637 return response
638
639
640 async def handle_ask_user_question(input_data: dict) -> PermissionResultAllow:
641 """顯示 Claude 的問題並收集使用者答案。"""
642 answers = {}
643
644 for q in input_data.get("questions", []):
645 print(f"\n{q['header']}: {q['question']}")
646
647 options = q["options"]
648 for i, opt in enumerate(options):
649 print(f" {i + 1}. {opt['label']} - {opt['description']}")
650 if q.get("multiSelect"):
651 print(" (Enter numbers separated by commas, or type your own answer)")
652 else:
653 print(" (Enter a number, or type your own answer)")
654
655 response = input("Your choice: ").strip()
656 answers[q["question"]] = parse_response(response, options)
657
658 return PermissionResultAllow(
659 updated_input={
660 "questions": input_data.get("questions", []),
661 "answers": answers,
662 }
663 )
664
665
666 async def can_use_tool(
667 tool_name: str, input_data: dict, context
668 ) -> PermissionResultAllow:
669 # 將 AskUserQuestion 路由到我們的問題處理程式
670 if tool_name == "AskUserQuestion":
671 return await handle_ask_user_question(input_data)
672 # 為此範例自動批准其他工具
673 return PermissionResultAllow(updated_input=input_data)
674
675
676 async def prompt_stream():
677 yield {
678 "type": "user",
679 "message": {
680 "role": "user",
681 "content": "Help me decide on the tech stack for a new mobile app",
682 },
683 }
684
685
686 # 必需的解決方法：虛擬 hook 保持流開放以供 can_use_tool 使用
687 async def dummy_hook(input_data, tool_use_id, context):
688 return {"continue_": True}
689
690
691 async def main():
692 async for message in query(
693 prompt=prompt_stream(),
694 options=ClaudeAgentOptions(
695 can_use_tool=can_use_tool,
696 hooks={"PreToolUse": [HookMatcher(matcher=None, hooks=[dummy_hook])]},
697 ),
698 ):
699 if isinstance(message, ResultMessage) and message.subtype == "success":
700 print(message.result)
701
702
703 asyncio.run(main())
704 ```
705
706 ```typescript TypeScript theme={null}
707 import { query } from "@anthropic-ai/claude-agent-sdk";
708 import * as readline from "readline/promises";
709
710 // 幫助程式在終端機中提示使用者輸入
711 async function prompt(question: string): Promise<string> {
712 const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
713 const answer = await rl.question(question);
714 rl.close();
715 return answer;
716 }
717
718 // 將使用者輸入解析為選項編號或自由文字
719 function parseResponse(response: string, options: any[]): string {
720 const indices = response.split(",").map((s) => parseInt(s.trim()) - 1);
721 const labels = indices
722 .filter((i) => !isNaN(i) && i >= 0 && i < options.length)
723 .map((i) => options[i].label);
724 return labels.length > 0 ? labels.join(", ") : response;
725 }
726
727 // 顯示 Claude 的問題並收集使用者答案
728 async function handleAskUserQuestion(input: any) {
729 const answers: Record<string, string> = {};
730
731 for (const q of input.questions) {
732 console.log(`\n${q.header}: ${q.question}`);
733
734 const options = q.options;
735 options.forEach((opt: any, i: number) => {
736 console.log(` ${i + 1}. ${opt.label} - ${opt.description}`);
737 });
738 if (q.multiSelect) {
739 console.log(" (Enter numbers separated by commas, or type your own answer)");
740 } else {
741 console.log(" (Enter a number, or type your own answer)");
742 }
743
744 const response = (await prompt("Your choice: ")).trim();
745 answers[q.question] = parseResponse(response, options);
746 }
747
748 // 將答案返回給 Claude（必須包括原始問題）
749 return {
750 behavior: "allow",
751 updatedInput: { questions: input.questions, answers }
752 };
753 }
754
755 async function main() {
756 for await (const message of query({
757 prompt: "Help me decide on the tech stack for a new mobile app",
758 options: {
759 canUseTool: async (toolName, input) => {
760 // 將 AskUserQuestion 路由到我們的問題處理程式
761 if (toolName === "AskUserQuestion") {
762 return handleAskUserQuestion(input);
763 }
764 // 為此範例自動批准其他工具
765 return { behavior: "allow", updatedInput: input };
766 }
767 }
768 })) {
769 if ("result" in message) console.log(message.result);
770 }
771 }
772
773 main();
774 ```
775</CodeGroup>
776
777## 限制
778
779* **子代理**：`AskUserQuestion` 目前在透過 Agent 工具生成的子代理中不可用
780* **問題限制**：每個 `AskUserQuestion` 呼叫支援 1-4 個問題，每個 2-4 個選項
781
782## 獲取使用者輸入的其他方式
783
784`canUseTool` 回呼和 `AskUserQuestion` 工具涵蓋大多數批准和澄清情況，但 SDK 提供其他方式來從使用者獲取輸入：
785
786### 串流輸入
787
788當您需要以下情況時，使用[串流輸入](/zh-TW/agent-sdk/streaming-vs-single-mode)：
789
790* **在任務中途中斷代理**：在 Claude 工作時發送取消信號或改變方向
791* **提供額外上下文**：添加 Claude 需要的資訊，無需等待它詢問
792* **構建聊天介面**：讓使用者在長時間運行的操作期間發送後續訊息
793
794串流輸入非常適合對話式 UI，使用者在整個執行過程中與代理互動，而不僅僅在批准檢查點。
795
796### 自訂工具
797
798當您需要以下情況時，使用[自訂工具](/zh-TW/agent-sdk/custom-tools)：
799
800* **收集結構化輸入**：構建超越 `AskUserQuestion` 多選格式的表單、精靈或多步驟工作流程
801* **整合外部批准系統**：連接到現有的票務、工作流程或批准平台
802* **實現特定領域的互動**：創建針對您應用程式需求的工具，例如程式碼審查介面或部署檢查清單
803
804自訂工具讓您完全控制互動，但需要比使用內建 `canUseTool` 回呼更多的實現工作。
805
806## 相關資源
807
808* [配置權限](/zh-TW/agent-sdk/permissions)：設定權限模式和規則
809* [使用 hooks 控制執行](/zh-TW/agent-sdk/hooks)：在代理生命週期的關鍵點執行自訂程式碼
810* [TypeScript SDK 參考](/zh-TW/agent-sdk/typescript#canusetool)：完整 canUseTool API 文件
39 39
40分類器不從 `.claude/settings.json` 中的共用專案設定讀取 `autoMode`，因此簽入的儲存庫無法注入其自己的允許規則。40分類器不從 `.claude/settings.json` 中的共用專案設定讀取 `autoMode`，因此簽入的儲存庫無法注入其自己的允許規則。
41 41
4242來自每個範圍的項目會被合併。開發人員可以使用個人項目擴展 `environment`、`allow` 和 `soft_deny`，但無法移除受管設定提供的項目。因為允許規則在分類器內充當阻止規則的例外，開發人員新增的 `allow` 項目可以覆蓋組織 `soft_deny` 項目：組合是加法的，而不是硬策略邊界。來自每個範圍的項目會被合併。開發人員可以使用個人項目擴展 `environment`、`allow`、`soft_deny` 和 `hard_deny`，但無法移除受管設定提供的項目。因為允許規則在分類器內充當軟阻止規則的例外，開發人員新增的 `allow` 項目可以覆蓋組織 `soft_deny` 項目：組合是加法的，而不是硬策略邊界。
43 43
44<Note>44<Note>
45 分類器是在[權限系統](/zh-TW/permissions)之後執行的第二道門。對於無論使用者意圖或分類器設定如何都必須永遠不執行的操作，請在受管設定中使用 `permissions.deny`，它在諮詢分類器之前阻止操作，無法被覆蓋。45 分類器是在[權限系統](/zh-TW/permissions)之後執行的第二道門。對於無論使用者意圖或分類器設定如何都必須永遠不執行的操作，請在受管設定中使用 `permissions.deny`，它在諮詢分類器之前阻止操作，無法被覆蓋。
99 99
100## 覆蓋阻止和允許規則100## 覆蓋阻止和允許規則
101 101
102102兩個額外的欄位讓您取代分類器的內建規則清單：`autoMode.soft_deny` 控制被阻止的內容，`autoMode.allow` 控制應用哪些例外。每個都是散文描述的陣列，讀取為自然語言規則。沒有 `autoMode.deny` 欄位；要硬阻止操作而不管意圖，請使用 [`permissions.deny`](/zh-TW/permissions)，它在分類器之前執行。三個額外的欄位讓您取代分類器的內建規則清單：`autoMode.hard_deny` 用於無條件安全邊界，`autoMode.soft_deny` 用於使用者意圖可以清除的破壞性操作，以及 `autoMode.allow` 用於例外。每個都是散文描述的陣列，讀取為自然語言規則。對於在分類器之前執行的工具模式型硬阻止，請使用 [`permissions.deny`](/zh-TW/permissions)。
103 103
104104在分類器內，優先順序分為三個層級：在分類器內，優先順序分為四個層級：
105 105
106106* `soft_deny` 規則首先阻止* `hard_deny` 規則無條件阻止。使用者意圖和 `allow` 例外不適用。
107107* `allow` 規則然後覆蓋匹配的阻止作為例外* `soft_deny` 規則接著阻止。使用者意圖和 `allow` 例外可以覆蓋這些。
108108* 明確的使用者意圖覆蓋兩者：如果使用者的訊息直接且具體地描述 Claude 即將採取的確切操作，分類器允許它，即使 `soft_deny` 規則匹配* `allow` 規則然後覆蓋匹配的 `soft_deny` 規則作為例外。
109* 明確的使用者意圖覆蓋剩餘的軟阻止：如果使用者的訊息直接且具體地描述 Claude 即將採取的確切操作，分類器允許它，即使 `soft_deny` 規則匹配。
109 110
110一般請求不算作明確意圖。要求 Claude「清理儲存庫」不授權強制推送，但要求 Claude「強制推送此分支」則授權。111一般請求不算作明確意圖。要求 Claude「清理儲存庫」不授權強制推送，但要求 Claude「強制推送此分支」則授權。
111 112
112113要放寬，當分類器重複標記預設例外不涵蓋的常規模式時，新增到 `allow`。要加強，對於預設值遺漏的特定於您環境的風險，新增到 `soft_deny`。要保留內建規則同時新增您自己的規則，請在陣列中包含字面字串 `"$defaults"`。預設規則會在該位置拼接，因此您的自訂規則可以在它們之前或之後，並且當內建清單在版本發佈中變更時，您繼續繼承更新。要放寬，當分類器重複標記預設例外不涵蓋的常規模式時，新增到 `allow`。要加強，對於預設值遺漏的特定於您環境的破壞性風險，新增到 `soft_deny`，或對於必須永遠不能跨越的安全邊界，新增到 `hard_deny`。要保留內建規則同時新增您自己的規則，請在陣列中包含字面字串 `"$defaults"`。預設規則會在該位置拼接，因此您的自訂規則可以在它們之前或之後，並且當內建清單在版本發佈中變更時，您繼續繼承更新。
113 114
114```json theme={null}115```json theme={null}
115{116{
127 "$defaults",128 "$defaults",
128 "Never run database migrations outside the migrations CLI, even against dev databases",129 "Never run database migrations outside the migrations CLI, even against dev databases",
129 "Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow"130 "Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow"
131 ],
132 "hard_deny": [
133 "$defaults",
134 "Never send repository contents to third-party code-review APIs"
130 ]135 ]
131 }136 }
132}137}
133```138```
134 139
135<Danger>140<Danger>
136141 設定 `environment`、`allow` 或 `soft_deny` 中的任何一個而不包含 `"$defaults"` 會取代該部分的整個預設清單。如果您設定 `soft_deny` 為單一項目並省略 `"$defaults"`，每個內建阻止規則都會被丟棄：強制推送、資料外洩、`curl | bash`、生產部署以及所有其他預設阻止規則都變成允許。只在您打算完全掌控清單時才省略 `"$defaults"`。在該情況下，執行 `claude auto-mode defaults` 列印內建規則，將它們複製到您的設定檔案中，然後根據您自己的管道和風險容限檢查每個規則。 設定 `environment`、`allow`、`soft_deny` 或 `hard_deny` 中的任何一個而不包含 `"$defaults"` 會取代該部分的整個預設清單。沒有 `"$defaults"` 的 `soft_deny` 陣列會丟棄每個內建軟阻止規則，包括強制推送、`curl | bash` 和生產部署。沒有 `"$defaults"` 的 `hard_deny` 陣列會丟棄內建資料外洩和安全檢查繞過規則。
137</Danger>142</Danger>
138 143
139144每個部分獨立評估，因此單獨設定 `environment` 會保持預設 `allow` 和 `soft_deny` 清單完整。每個部分獨立評估，因此單獨設定 `environment` 會保持預設 `allow`、`soft_deny` 和 `hard_deny` 清單完整。只在您打算完全掌控清單時才省略 `"$defaults"`。要安全地執行此操作，執行 `claude auto-mode defaults` 列印內建規則，將它們複製到您的設定檔案中，然後根據您自己的管道和風險容限檢查每個規則。
140 145
141## 檢查預設值和您的有效設定146## 檢查預設值和您的有效設定
142 147
143三個 CLI 子命令幫助您檢查和驗證您的設定。148三個 CLI 子命令幫助您檢查和驗證您的設定。
144 149
145150將內建 `environment`、`allow` 和 `soft_deny` 規則列印為 JSON：將內建 `environment`、`allow`、`soft_deny` 和 `hard_deny` 規則列印為 JSON：
146 151
147```bash theme={null}152```bash theme={null}
148claude auto-mode defaults153claude auto-mode defaults
154claude auto-mode config159claude auto-mode config
155```160```
156 161
157162獲得關於您的自訂 `allow` 和 `soft_deny` 規則的 AI 反饋：獲得關於您的自訂 `allow`、`soft_deny` 和 `hard_deny` 規則的 AI 反饋：
158 163
159```bash theme={null}164```bash theme={null}
160claude auto-mode critique165claude auto-mode critique
46| `/btw <question>` | 提出快速[側邊問題](/zh-TW/interactive-mode#side-questions-with-%2Fbtw)，無需添加到對話中 |46| `/btw <question>` | 提出快速[側邊問題](/zh-TW/interactive-mode#side-questions-with-%2Fbtw)，無需添加到對話中 |
47| `/chrome` | 配置 [Chrome 中的 Claude](/zh-TW/chrome) 設定 |47| `/chrome` | 配置 [Chrome 中的 Claude](/zh-TW/chrome) 設定 |
48| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/zh-TW/skills#bundled-skills).** 為您的專案語言（Python、TypeScript、Java、Go、Ruby、C#、PHP 或 cURL）和 Managed Agents 參考加載 Claude API 參考資料。涵蓋工具使用、串流、批次、結構化輸出和常見陷阱。當您的程式碼導入 `anthropic` 或 `@anthropic-ai/sdk` 時也會自動激活。執行 `/claude-api migrate` 以將現有 Claude API 程式碼升級到較新的模型：Claude 詢問要掃描哪些檔案以及要針對哪個模型，然後更新在版本之間變更的模型 ID、thinking 配置和其他參數。執行 `/claude-api managed-agents-onboard` 以進行互動式逐步解說，從頭開始建立新的 Managed Agent |48| `/claude-api [migrate\|managed-agents-onboard]` | **[Skill](/zh-TW/skills#bundled-skills).** 為您的專案語言（Python、TypeScript、Java、Go、Ruby、C#、PHP 或 cURL）和 Managed Agents 參考加載 Claude API 參考資料。涵蓋工具使用、串流、批次、結構化輸出和常見陷阱。當您的程式碼導入 `anthropic` 或 `@anthropic-ai/sdk` 時也會自動激活。執行 `/claude-api migrate` 以將現有 Claude API 程式碼升級到較新的模型：Claude 詢問要掃描哪些檔案以及要針對哪個模型，然後更新在版本之間變更的模型 ID、thinking 配置和其他參數。執行 `/claude-api managed-agents-onboard` 以進行互動式逐步解說，從頭開始建立新的 Managed Agent |
4949| `/clear` | 使用空上下文開始新對話。上一個對話在 `/resume` 中保持可用。若要在繼續同一對話時釋放上下文，請改用 `/compact`。別名：`/reset`、`/new` || `/clear [name]` | 使用空上下文開始新對話。上一個對話在 `/resume` 中保持可用。傳遞名稱以在 `/resume` 選擇器中標記上一個對話。若要在繼續同一對話時釋放上下文，請改用 `/compact`。別名：`/reset`、`/new` |
50| `/color [color\|default]` | 設定目前工作階段的提示列顏色。可用顏色：`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan`。使用 `default` 重設，或不帶引數執行以選擇隨機顏色。當[遠端控制](/zh-TW/remote-control)已連接時，顏色會同步到 claude.ai/code |50| `/color [color\|default]` | 設定目前工作階段的提示列顏色。可用顏色：`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan`。使用 `default` 重設，或不帶引數執行以選擇隨機顏色。當[遠端控制](/zh-TW/remote-control)已連接時，顏色會同步到 claude.ai/code |
51| `/compact [instructions]` | 通過總結到目前為止的對話來釋放上下文。可選擇性地傳遞焦點指示以進行摘要。請參閱[壓縮如何處理規則、skills 和記憶體檔案](/zh-TW/context-window#what-survives-compaction) |51| `/compact [instructions]` | 通過總結到目前為止的對話來釋放上下文。可選擇性地傳遞焦點指示以進行摘要。請參閱[壓縮如何處理規則、skills 和記憶體檔案](/zh-TW/context-window#what-survives-compaction) |
52| `/config` | 開啟[設定](/zh-TW/settings)介面以調整主題、模型、[輸出樣式](/zh-TW/output-styles)和其他偏好設定。別名：`/settings` |52| `/config` | 開啟[設定](/zh-TW/settings)介面以調整主題、模型、[輸出樣式](/zh-TW/output-styles)和其他偏好設定。別名：`/settings` |
5353| `/context` | 將目前的上下文使用情況視覺化為彩色網格。顯示上下文繁重工具、記憶體膨脹和容量警告的最佳化建議 || `/context [all]` | 將目前的上下文使用情況視覺化為彩色網格。顯示上下文繁重工具、記憶體膨脹和容量警告的最佳化建議。在[全螢幕模式](/zh-TW/fullscreen)中，每個項目的分解會折疊以保持網格可見。傳遞 `all` 以展開它 |
54| `/copy [N]` | 將最後一個助手回應複製到剪貼簿。傳遞數字 `N` 以複製第 N 個最新回應：`/copy 2` 複製倒數第二個。當存在程式碼區塊時，顯示互動式選擇器以選擇個別區塊或完整回應。在選擇器中按 `w` 以將選擇寫入檔案而不是剪貼簿，這在 SSH 上很有用 |54| `/copy [N]` | 將最後一個助手回應複製到剪貼簿。傳遞數字 `N` 以複製第 N 個最新回應：`/copy 2` 複製倒數第二個。當存在程式碼區塊時，顯示互動式選擇器以選擇個別區塊或完整回應。在選擇器中按 `w` 以將選擇寫入檔案而不是剪貼簿，這在 SSH 上很有用 |
55| `/cost` | `/usage` 的別名 |55| `/cost` | `/usage` 的別名 |
56| `/debug [description]` | **[Skill](/zh-TW/skills#bundled-skills).** 為目前工作階段啟用偵錯日誌記錄並通過讀取工作階段偵錯日誌來排除故障。除非您使用 `claude --debug` 啟動，否則偵錯日誌記錄預設為關閉，因此在工作階段中期運行 `/debug` 會從該時刻開始捕獲日誌。可選擇性地描述問題以集中分析 |56| `/debug [description]` | **[Skill](/zh-TW/skills#bundled-skills).** 為目前工作階段啟用偵錯日誌記錄並通過讀取工作階段偵錯日誌來排除故障。除非您使用 `claude --debug` 啟動，否則偵錯日誌記錄預設為關閉，因此在工作階段中期運行 `/debug` 會從該時刻開始捕獲日誌。可選擇性地描述問題以集中分析 |
88| `/powerup` | 通過具有動畫演示的快速互動式課程探索 Claude Code 功能 |88| `/powerup` | 通過具有動畫演示的快速互動式課程探索 Claude Code 功能 |
89| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}在 v2.1.91 中移除。直接詢問 Claude 以查看 pull request 評論。在較早的版本上，從 GitHub pull request 擷取並顯示評論；自動偵測目前分支的 PR，或傳遞 PR URL 或編號。需要 `gh` CLI |89| `/pr-comments [PR]` | {/* max-version: 2.1.90 */}在 v2.1.91 中移除。直接詢問 Claude 以查看 pull request 評論。在較早的版本上，從 GitHub pull request 擷取並顯示評論；自動偵測目前分支的 PR，或傳遞 PR URL 或編號。需要 `gh` CLI |
90| `/privacy-settings` | 檢視和更新您的隱私設定。僅適用於 Pro 和 Max 方案訂閱者 |90| `/privacy-settings` | 檢視和更新您的隱私設定。僅適用於 Pro 和 Max 方案訂閱者 |
91| `/radio` | 在您的瀏覽器中開啟 Claude FM lo-fi 廣播。當沒有瀏覽器可用時列印串流 URL。在 Bedrock、Vertex 或 Foundry 上不可用 |
91| `/recap` | 按需生成目前工作階段的單行摘要。請參閱[工作階段摘要](/zh-TW/interactive-mode#session-recap)以了解您離開後出現的自動摘要 |92| `/recap` | 按需生成目前工作階段的單行摘要。請參閱[工作階段摘要](/zh-TW/interactive-mode#session-recap)以了解您離開後出現的自動摘要 |
92| `/release-notes` | 在互動式版本選擇器中檢視變更日誌。選擇特定版本以查看其發行說明，或選擇顯示所有版本 |93| `/release-notes` | 在互動式版本選擇器中檢視變更日誌。選擇特定版本以查看其發行說明，或選擇顯示所有版本 |
93| `/reload-plugins` | 重新載入所有作用中的 [plugins](/zh-TW/plugins) 以套用待處理的變更，無需重新啟動。報告每個已重新載入的元件的計數，並標記任何載入錯誤 |94| `/reload-plugins` | 重新載入所有作用中的 [plugins](/zh-TW/plugins) 以套用待處理的變更，無需重新啟動。報告每個已重新載入的元件的計數，並標記任何載入錯誤 |
92| `CLAUDE_CODE_EFFORT_LEVEL` | 為支援的模型設定努力級別。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型預設值。可用級別取決於模型。優先於 `/effort` 和 `effortLevel` 設定。請參閱 [Adjust effort level](/zh-TW/model-config#adjust-effort-level) |92| `CLAUDE_CODE_EFFORT_LEVEL` | 為支援的模型設定努力級別。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型預設值。可用級別取決於模型。優先於 `/effort` 和 `effortLevel` 設定。請參閱 [Adjust effort level](/zh-TW/model-config#adjust-effort-level) |
93| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆蓋 [session recap](/zh-TW/interactive-mode#session-recap) 可用性。設定為 `0` 以強制關閉摘要，無論 `/config` 切換如何。設定為 `1` 以在 [`awaySummaryEnabled`](/zh-TW/settings#available-settings) 為 `false` 時強制啟用摘要。優先於設定和 `/config` 切換 |93| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆蓋 [session recap](/zh-TW/interactive-mode#session-recap) 可用性。設定為 `0` 以強制關閉摘要，無論 `/config` 切換如何。設定為 `1` 以在 [`awaySummaryEnabled`](/zh-TW/settings#available-settings) 為 `false` 時強制啟用摘要。優先於設定和 `/config` 切換 |
94| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設定為 `1` 以在 [non-interactive mode](/zh-TW/headless) 中背景安裝完成後在回合邊界處刷新外掛程式狀態。預設關閉，因為刷新會在工作階段中途更改系統提示，這會使該回合的 [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) 失效 |94| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設定為 `1` 以在 [non-interactive mode](/zh-TW/headless) 中背景安裝完成後在回合邊界處刷新外掛程式狀態。預設關閉，因為刷新會在工作階段中途更改系統提示，這會使該回合的 [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) 失效 |
9595| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具呼叫輸入是否在 Claude 生成時從 API 串流。關閉此選項時，大型工具輸入（例如長檔案寫入）僅在 Claude 完成生成後才到達，這可能看起來像是掛起。在 Anthropic API 上預設啟用。設定為 `0` 以選擇退出。設定為 `1` 以在透過 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 路由時強制啟用。在 Bedrock 和 Vertex 上，按模型啟用，其中已部署的容器支援它。在 Foundry 和 [gateway](/zh-TW/llm-gateway) 連線上預設關閉 || `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) 連線上預設關閉 |
96| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 相容閘道（例如 LiteLLM、Kong 或內部代理）時從您的閘道的 `/v1/models` 端點填充 `/model` 選擇器。預設關閉，因為由共享 API 金鑰支援的閘道會以其他方式向每個使用者顯示該金鑰可以存取的每個模型。探索的模型仍由 [`availableModels`](/zh-TW/settings#available-settings) 允許清單篩選 |96| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 相容閘道（例如 LiteLLM、Kong 或內部代理）時從您的閘道的 `/v1/models` 端點填充 `/model` 選擇器。預設關閉，因為由共享 API 金鑰支援的閘道會以其他方式向每個使用者顯示該金鑰可以存取的每個模型。探索的模型仍由 [`availableModels`](/zh-TW/settings#available-settings) 允許清單篩選 |
97| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設定為 `false` 以停用提示建議（`/config` 中的「提示建議」切換）。這些是在 Claude 回應後出現在您的提示輸入中的灰顯預測。請參閱 [Prompt suggestions](/zh-TW/interactive-mode#prompt-suggestions) |97| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 設定為 `false` 以停用提示建議（`/config` 中的「提示建議」切換）。這些是在 Claude 回應後出現在您的提示輸入中的灰顯預測。請參閱 [Prompt suggestions](/zh-TW/interactive-mode#prompt-suggestions) |
98| `CLAUDE_CODE_ENABLE_TASKS` | 設定為 `1` 以在非互動式模式（`-p` 旗標）中啟用任務追蹤系統。任務在互動式模式中預設為開啟。請參閱 [Task list](/zh-TW/interactive-mode#task-list) |98| `CLAUDE_CODE_ENABLE_TASKS` | 設定為 `1` 以在非互動式模式（`-p` 旗標）中啟用任務追蹤系統。任務在互動式模式中預設為開啟。請參閱 [Task list](/zh-TW/interactive-mode#task-list) |
116| `CLAUDE_CODE_MAX_RETRIES` | 覆蓋重試失敗 API 請求的次數（預設值：10） |116| `CLAUDE_CODE_MAX_RETRIES` | 覆蓋重試失敗 API 請求的次數（預設值：10） |
117| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 可以並行執行的唯讀工具和 subagents 的最大數量（預設值：10）。較高的值會增加並行性，但消耗更多資源 |117| `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` | 可以並行執行的唯讀工具和 subagents 的最大數量（預設值：10）。較高的值會增加並行性，但消耗更多資源 |
118| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | 設定為 `1` 以使用僅安全基線環境加上伺服器配置的 `env` 而不是繼承您的 shell 環境來生成 stdio MCP 伺服器 |118| `CLAUDE_CODE_MCP_ALLOWLIST_ENV` | 設定為 `1` 以使用僅安全基線環境加上伺服器配置的 `env` 而不是繼承您的 shell 環境來生成 stdio MCP 伺服器 |
119| `CLAUDE_CODE_NATIVE_CURSOR` | 設定為 `1` 以在輸入插入符號處顯示終端自己的游標，而不是繪製的區塊。游標尊重終端的閃爍、形狀和焦點設定 |
119| `CLAUDE_CODE_NEW_INIT` | 設定為 `1` 以使 `/init` 執行互動式設定流程。流程會詢問要產生哪些檔案，包括 CLAUDE.md、skills 和 hooks，然後再探索程式碼庫並寫入它們。沒有此變數，`/init` 會自動產生 CLAUDE.md 而不提示。 |120| `CLAUDE_CODE_NEW_INIT` | 設定為 `1` 以使 `/init` 執行互動式設定流程。流程會詢問要產生哪些檔案，包括 CLAUDE.md、skills 和 hooks，然後再探索程式碼庫並寫入它們。沒有此變數，`/init` 會自動產生 CLAUDE.md 而不提示。 |
120| `CLAUDE_CODE_NO_FLICKER` | 設定為 `1` 以啟用 [fullscreen rendering](/zh-TW/fullscreen)，一項研究預覽，可減少閃爍並在長對話中保持記憶體平坦。相當於 [`tui`](/zh-TW/settings#available-settings) 設定；您也可以使用 `/tui fullscreen` 切換 |121| `CLAUDE_CODE_NO_FLICKER` | 設定為 `1` 以啟用 [fullscreen rendering](/zh-TW/fullscreen)，一項研究預覽，可減少閃爍並在長對話中保持記憶體平坦。相當於 [`tui`](/zh-TW/settings#available-settings) 設定；您也可以使用 `/tui fullscreen` 切換 |
121| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 驗證的 OAuth 重新整理權杖。設定時，`claude auth login` 會直接交換此權杖，而不是開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。對於在自動化環境中佈建驗證很有用 |122| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 驗證的 OAuth 重新整理權杖。設定時，`claude auth login` 會直接交換此權杖，而不是開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。對於在自動化環境中佈建驗證很有用 |
191| `DISABLE_TELEMETRY` | 設定為 `1` 以選擇退出遙測。遙測事件不包括使用者資料，如程式碼、檔案路徑或 bash 命令 |192| `DISABLE_TELEMETRY` | 設定為 `1` 以選擇退出遙測。遙測事件不包括使用者資料，如程式碼、檔案路徑或 bash 命令 |
192| `DISABLE_UPDATES` | 設定為 `1` 以阻止所有更新，包括手動 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。在透過您自己的管道分發 Claude Code 且使用者不應自行更新時使用 |193| `DISABLE_UPDATES` | 設定為 `1` 以阻止所有更新，包括手動 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更嚴格。在透過您自己的管道分發 Claude Code 且使用者不應自行更新時使用 |
193| `DISABLE_UPGRADE_COMMAND` | 設定為 `1` 以隱藏 `/upgrade` 命令 |194| `DISABLE_UPGRADE_COMMAND` | 設定為 `1` 以隱藏 `/upgrade` 命令 |
195| `DO_NOT_TRACK` | 設定為 `1` 以選擇退出遙測。相當於設定 `DISABLE_TELEMETRY`。尊重 [standard cross-tool convention](https://consoledonottrack.com/) |
194| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設定為 `false` 以停用 Claude Code 中的 [claude.ai MCP servers](/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對於已登入的使用者預設啟用 |196| `ENABLE_CLAUDEAI_MCP_SERVERS` | 設定為 `false` 以停用 Claude Code 中的 [claude.ai MCP servers](/zh-TW/mcp#use-mcp-servers-from-claude-ai)。對於已登入的使用者預設啟用 |
195| `ENABLE_PROMPT_CACHING_1H` | 設定為 `1` 以要求 1 小時的提示快取 TTL，而不是預設的 5 分鐘。適用於 API 金鑰、[Bedrock](/zh-TW/amazon-bedrock)、[Vertex](/zh-TW/google-vertex-ai) 和 [Foundry](/zh-TW/microsoft-foundry) 使用者。訂閱使用者自動接收 1 小時 TTL。1 小時快取寫入以更高的速率計費 |197| `ENABLE_PROMPT_CACHING_1H` | 設定為 `1` 以要求 1 小時的提示快取 TTL，而不是預設的 5 分鐘。適用於 API 金鑰、[Bedrock](/zh-TW/amazon-bedrock)、[Vertex](/zh-TW/google-vertex-ai) 和 [Foundry](/zh-TW/microsoft-foundry) 使用者。訂閱使用者自動接收 1 小時 TTL。1 小時快取寫入以更高的速率計費 |
196| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | 已棄用。改用 `ENABLE_PROMPT_CACHING_1H` |198| `ENABLE_PROMPT_CACHING_1H_BEDROCK` | 已棄用。改用 `ENABLE_PROMPT_CACHING_1H` |
31| `Not logged in · Please run /login` | [Authentication](#not-logged-in) |31| `Not logged in · Please run /login` | [Authentication](#not-logged-in) |
32| `Invalid API key` | [Authentication](#invalid-api-key) |32| `Invalid API key` | [Authentication](#invalid-api-key) |
33| `This organization has been disabled` | [Authentication](#this-organization-has-been-disabled) |33| `This organization has been disabled` | [Authentication](#this-organization-has-been-disabled) |
34| `Routines are disabled by your organization's policy` | [Authentication](#routines-are-disabled-by-your-organizations-policy) |
34| `OAuth token revoked` / `OAuth token has expired` | [Authentication](#oauth-token-revoked-or-expired) |35| `OAuth token revoked` / `OAuth token has expired` | [Authentication](#oauth-token-revoked-or-expired) |
35| `does not meet scope requirement user:profile` | [Authentication](#oauth-scope-requirement) |36| `does not meet scope requirement user:profile` | [Authentication](#oauth-scope-requirement) |
36| `Unable to connect to API` | [Network](#unable-to-connect-to-api) |37| `Unable to connect to API` | [Network](#unable-to-connect-to-api) |
252* 之後執行 `/status` 以確認活躍的認證是您的訂閱253* 之後執行 `/status` 以確認活躍的認證是您的訂閱
253* 如果未設定環境變數且錯誤持續存在，則已停用的組織是與您的 `/login` 相關聯的組織。聯絡支援或使用不同的帳戶登入。254* 如果未設定環境變數且錯誤持續存在，則已停用的組織是與您的 `/login` 相關聯的組織。聯絡支援或使用不同的帳戶登入。
254 255
256### Routines are disabled by your organization's policy
257
258您的 Team 或 Enterprise 管理員已在組織層級關閉了例程。當您嘗試建立或執行例程時會出現此錯誤，包括從 `/schedule` 和 claude.ai/code 上的 [Routines](/zh-TW/routines) UI。
259
260```text theme={null}
261Routines are disabled by your organization's policy.
262```
263
264這是一個伺服器端設定，因此無法從本機設定、環境變數或 CLI 旗標覆蓋。
265
266**要做什麼：**
267
268* 要求您的管理員在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 啟用 **Routines** 切換
269* 對於不需要組織層級例程的一次性排程工作，請參閱 [scheduled tasks](/zh-TW/scheduled-tasks)
270
255### OAuth token revoked or expired271### OAuth token revoked or expired
256 272
257您的已儲存登入不再有效。撤銷的令牌表示您在任何地方登出或管理員移除了存取權；過期的令牌表示自動重新整理在工作階段中途失敗。273您的已儲存登入不再有效。撤銷的令牌表示您在任何地方登出或管理員移除了存取權；過期的令牌表示自動重新整理在工作階段中途失敗。
289 289
290Claude 回應後，建議會根據您的對話歷史繼續出現，例如多部分請求的後續步驟或工作流程的自然延續。290Claude 回應後，建議會根據您的對話歷史繼續出現，例如多部分請求的後續步驟或工作流程的自然延續。
291 291
292292* 按 **Tab** 或 **Right arrow** 以接受建議，或按 **Enter** 以接受並提交* 按 **Tab** 或 **Right arrow** 以將建議放入提示輸入中，然後按 **Enter** 以提交
293* 開始輸入以關閉它293* 開始輸入以關閉它
294 294
295建議作為背景請求執行，該請求重複使用父對話的提示快取，因此額外成本最少。當快取冷時，Claude Code 會跳過建議生成以避免不必要的成本。295建議作為背景請求執行，該請求重複使用父對話的提示快取，因此額外成本最少。當快取冷時，Claude Code 會跳過建議生成以避免不必要的成本。
265 --header "Authorization: Bearer your-token"265 --header "Authorization: Bearer your-token"
266```266```
267 267
268當透過 `.mcp.json`、`~/.claude.json` 或 `claude mcp add-json` 中的 JSON 配置 MCP servers 時，`type` 欄位接受 `streamable-http` 作為 `http` 的別名。MCP 規範使用名稱 `streamable-http` 作為此傳輸，因此從 server 文件複製的配置無需修改即可運作。
269
268### 選項 2：新增遠端 SSE server270### 選項 2：新增遠端 SSE server
269 271
270<Warning>272<Warning>
120 Claude Code 知道 shell 運算子，所以前綴符合規則如 `Bash(safe-cmd *)` 不會給它執行命令 `safe-cmd && other-cmd` 的權限。已識別的命令分隔符是 `&&`、`||`、`;`、`|`、`|&`、`&` 和換行符。規則必須獨立符合每個子命令。120 Claude Code 知道 shell 運算子，所以前綴符合規則如 `Bash(safe-cmd *)` 不會給它執行命令 `safe-cmd && other-cmd` 的權限。已識別的命令分隔符是 `&&`、`||`、`;`、`|`、`|&`、`&` 和換行符。規則必須獨立符合每個子命令。
121</Tip>121</Tip>
122 122
123123當您使用"是，不要再問"批准複合命令時，Claude Code 會為每個需要批准的子命令儲存一個單獨的規則，而不是為完整複合字串儲存單一規則。例如，批准 `git status && npm test` 會為 `npm test` 儲存一個規則，因此未來的 `npm test` 呼叫會被識別，無論 `&&` 前面是什麼。子命令如 `cd` 進入子目錄會為該路徑產生自己的 Read 規則。單一複合命令最多可能儲存 5 個規則。當您使用「是，不要再問」批准複合命令時，Claude Code 會為每個需要批准的子命令儲存一個單獨的規則，而不是為完整複合字串儲存單一規則。例如，批准 `git status && npm test` 會為 `npm test` 儲存一個規則，因此未來的 `npm test` 呼叫會被識別，無論 `&&` 前面是什麼。子命令如 `cd` 進入子目錄會為該路徑產生自己的 Read 規則。單一複合命令最多可能儲存 5 個規則。
124 124
125#### 程序包裝器125#### 程序包裝器
126 126
210* `Edit(//tmp/scratch.txt)`: 編輯絕對路徑 `/tmp/scratch.txt`210* `Edit(//tmp/scratch.txt)`: 編輯絕對路徑 `/tmp/scratch.txt`
211* `Read(src/**)`: 從 `<current-directory>/src/` 讀取211* `Read(src/**)`: 從 `<current-directory>/src/` 讀取
212 212
213一個規則只符合其錨點下的檔案，所以錨點決定了 deny 規則的範圍。裸檔案名稱遵循 gitignore 語義，並在任何深度符合，所以 `Read(.env)` 和 `Read(**/.env)` 是等價的：
214
215| Deny 規則 | 阻止 | 不阻止 |
216| ------------------------------ | ------------------- | ------------------ |
217| `Read(.env)` 或 `Read(**/.env)` | 目前目錄或其下的任何 `.env` | 父目錄或另一個專案中的 `.env` |
218| `Read(//**/.env)` | 檔案系統上任何位置的任何 `.env` | 無；規則錨定在檔案系統根目錄 |
219
213<Note>220<Note>
214 在 gitignore 模式中，`*` 符合單一目錄中的檔案，而 `**` 遞迴符合目錄。若要允許所有檔案存取，請使用不帶括號的工具名稱：`Read`、`Edit` 或 `Write`。221 在 gitignore 模式中，`*` 符合單一目錄中的檔案，而 `**` 遞迴符合目錄。若要允許所有檔案存取，請使用不帶括號的工具名稱：`Read`、`Edit` 或 `Write`。
215</Note>222</Note>
360 360
361`.claude-plugin/plugin.json` 檔案定義您的 plugin 的中繼資料和設定。本節記錄所有支援的欄位和選項。361`.claude-plugin/plugin.json` 檔案定義您的 plugin 的中繼資料和設定。本節記錄所有支援的欄位和選項。
362 362
363363manifest 是選用的。如果省略，Claude Code 會自動探索 [預設位置](#file-locations-reference) 中的元件，並從目錄名稱衍生 plugin 名稱。當您需要提供中繼資料或自訂元件路徑時，請使用 manifest。manifest 是選用的。如果省略，Claude Code 會自動探索[預設位置](#file-locations-reference)中的元件，並從目錄名稱衍生 plugin 名稱。當您需要提供中繼資料或自訂元件路徑時，請使用 manifest。
364 364
365### 完整架構365### 完整架構
366 366
409### 中繼資料欄位409### 中繼資料欄位
410 410
411| 欄位 | 類型 | 描述 | 範例 |411| 欄位 | 類型 | 描述 | 範例 |
412412| :------------ | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------- || :------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |
413| `$schema` | string | JSON Schema URL，用於編輯器自動完成和驗證。Claude Code 在載入時忽略此欄位。 | `"https://json.schemastore.org/claude-code-plugin-manifest.json"` |413| `$schema` | string | JSON Schema URL，用於編輯器自動完成和驗證。Claude Code 在載入時忽略此欄位。 | `"https://json.schemastore.org/claude-code-plugin-manifest.json"` |
414414| `version` | string | 選用。語義版本。設定此項會將 plugin 固定到該版本字串，因此使用者只會在您提升版本時收到更新。如果省略，Claude Code 會回退到 git commit SHA，因此每個 commit 都被視為新版本。如果也在 marketplace 項目中設定，`plugin.json` 優先。請參閱 [Version management](#version-management)。 | `"2.1.0"` || `version` | string | 選用。語義版本。設定此項會將 plugin 固定到該版本字串，因此使用者只會在您提升版本時收到更新。如果省略，Claude Code 會回退到 git commit SHA，因此每個 commit 都被視為新版本。如果也在 marketplace 項目中設定，`plugin.json` 優先。請參閱[Version management](#version-management)。 | `"2.1.0"` |
415| `description` | string | plugin 用途的簡短說明 | `"Deployment automation tools"` |415| `description` | string | plugin 用途的簡短說明 | `"Deployment automation tools"` |
416| `author` | object | 作者資訊 | `{"name": "Dev Team", "email": "dev@company.com"}` |416| `author` | object | 作者資訊 | `{"name": "Dev Team", "email": "dev@company.com"}` |
417| `homepage` | string | 文件 URL | `"https://docs.example.com"` |417| `homepage` | string | 文件 URL | `"https://docs.example.com"` |
422### 元件路徑欄位422### 元件路徑欄位
423 423
424| 欄位 | 類型 | 描述 | 範例 |424| 欄位 | 類型 | 描述 | 範例 |
425425| :---------------------- | :-------------------- | :-------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- || :---------------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |
426426| `skills` | string\|array | 包含 `<name>/SKILL.md` 的自訂 skill 目錄（取代預設 `skills/`） | `"./custom/skills/"` || `skills` | string\|array | 包含 `<name>/SKILL.md` 的自訂 skill 目錄（除了預設 `skills/`） | `"./custom/skills/"` |
427| `commands` | string\|array | 自訂平面 `.md` skill 檔案或目錄（取代預設 `commands/`） | `"./custom/cmd.md"` 或 `["./cmd1.md"]` |427| `commands` | string\|array | 自訂平面 `.md` skill 檔案或目錄（取代預設 `commands/`） | `"./custom/cmd.md"` 或 `["./cmd1.md"]` |
428| `agents` | string\|array | 自訂 agent 檔案（取代預設 `agents/`） | `"./custom/agents/reviewer.md"` |428| `agents` | string\|array | 自訂 agent 檔案（取代預設 `agents/`） | `"./custom/agents/reviewer.md"` |
429| `hooks` | string\|array\|object | Hook 設定路徑或內聯設定 | `"./my-extra-hooks.json"` |429| `hooks` | string\|array\|object | Hook 設定路徑或內聯設定 | `"./my-extra-hooks.json"` |
430| `mcpServers` | string\|array\|object | MCP 設定路徑或內聯設定 | `"./my-extra-mcp-config.json"` |430| `mcpServers` | string\|array\|object | MCP 設定路徑或內聯設定 | `"./my-extra-mcp-config.json"` |
431| `outputStyles` | string\|array | 自訂輸出樣式檔案/目錄（取代預設 `output-styles/`） | `"./styles/"` |431| `outputStyles` | string\|array | 自訂輸出樣式檔案/目錄（取代預設 `output-styles/`） | `"./styles/"` |
432| `lspServers` | string\|array\|object | [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) 設定，用於程式碼智慧（前往定義、尋找參考等） | `"./.lsp.json"` |432| `lspServers` | string\|array\|object | [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) 設定，用於程式碼智慧（前往定義、尋找參考等） | `"./.lsp.json"` |
433433| `experimental.themes` | string\|array | 色彩主題檔案/目錄（取代預設 `themes/`）。請參閱 [Themes](#themes) | `"./themes/"` || `experimental.themes` | string\|array | 色彩主題檔案/目錄（取代預設 `themes/`）。請參閱[Themes](#themes) | `"./themes/"` |
434434| `experimental.monitors` | string\|array | 背景 [Monitor](/zh-TW/tools-reference#monitor-tool) 設定，在 plugin 啟用時自動啟動。請參閱 [Monitors](#monitors) | `"./monitors.json"` || `experimental.monitors` | string\|array | 背景 [Monitor](/zh-TW/tools-reference#monitor-tool) 設定，在 plugin 啟用時自動啟動。請參閱[Monitors](#monitors) | `"./monitors.json"` |
435435| `userConfig` | object | 在啟用時提示使用者的使用者可設定值。請參閱 [User configuration](#user-configuration) | 請參閱下方 || `userConfig` | object | 在啟用時提示使用者的使用者可設定值。請參閱[User configuration](#user-configuration) | 請參閱下方 |
436436| `channels` | array | 訊息注入的頻道宣告（Telegram、Slack、Discord 風格）。請參閱 [Channels](#channels) | 請參閱下方 || `channels` | array | 訊息注入的頻道宣告（Telegram、Slack、Discord 風格）。請參閱[Channels](#channels) | 請參閱下方 |
437437| `dependencies` | array | 此 plugin 需要的其他 plugins，可選擇使用 semver 版本限制。請參閱 [Constrain plugin dependency versions](/zh-TW/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` || `dependencies` | array | 此 plugin 需要的其他 plugins，可選擇使用 semver 版本限制。請參閱[Constrain plugin dependency versions](/zh-TW/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |
438 438
439### 實驗性元件439### 實驗性元件
440 440
510 510
511### 路徑行為規則511### 路徑行為規則
512 512
513513對於 `skills`、`commands`、`agents`、`outputStyles`、`experimental.themes` 和 `experimental.monitors`，自訂路徑取代預設值。如果 manifest 指定 `skills`，預設 `skills/` 目錄不會被掃描；如果它指定 `experimental.monitors`，預設 `monitors/monitors.json` 不會被載入。[Hooks](#hooks)、[MCP servers](#mcp-servers) 和 [LSP servers](#lsp-servers) 有不同的語義來處理多個來源。自訂路徑是否取代或擴展 plugin 的預設目錄取決於欄位：
514
515* **取代預設值**：`commands`、`agents`、`outputStyles`、`experimental.themes`、`experimental.monitors`。例如，當 manifest 指定 `commands` 時，預設 `commands/` 目錄不會被掃描。若要保留預設值並新增更多，請明確列出：`"commands": ["./commands/", "./extras/"]`
516* **新增到預設值**：`skills`。預設 `skills/` 目錄始終被掃描，`skills` 中列出的目錄與其一起載入
517* **自有合併規則**：[hooks](#hooks)、[MCP servers](#mcp-servers) 和 [LSP servers](#lsp-servers)。請參閱每個部分以了解多個來源如何組合
518
519對於所有路徑欄位：
514 520
515* 所有路徑必須相對於 plugin 根目錄，並以 `./` 開頭521* 所有路徑必須相對於 plugin 根目錄，並以 `./` 開頭
516* 來自自訂路徑的元件使用相同的命名和命名空間規則522* 來自自訂路徑的元件使用相同的命名和命名空間規則
517* 可以將多個路徑指定為陣列523* 可以將多個路徑指定為陣列
518* 若要保留預設目錄並為 skills、commands、agents 或 output styles 新增更多路徑，請在陣列中包含預設值：`"skills": ["./skills/", "./extras/"]`
519* 當 skill 路徑指向直接包含 `SKILL.md` 的目錄時，例如 `"skills": ["./"]` 指向 plugin 根目錄，frontmatter 中的 `name` 欄位決定 skill 的叫用名稱。這提供了一個穩定的名稱，無論安裝目錄如何。如果 frontmatter 中未設定 `name`，目錄基名將用作後備。524* 當 skill 路徑指向直接包含 `SKILL.md` 的目錄時，例如 `"skills": ["./"]` 指向 plugin 根目錄，frontmatter 中的 `name` 欄位決定 skill 的叫用名稱。這提供了一個穩定的名稱，無論安裝目錄如何。如果 frontmatter 中未設定 `name`，目錄基名將用作後備。
520 525
521**路徑範例**：526**路徑範例**：
22 22
23例行程序在啟用了 [Claude Code on the web](/zh-TW/claude-code-on-the-web) 的 Pro、Max、Team 和 Enterprise 計劃上可用。在 [claude.ai/code/routines](https://claude.ai/code/routines) 創建和管理它們，或使用 CLI 中的 `/schedule` 命令。23例行程序在啟用了 [Claude Code on the web](/zh-TW/claude-code-on-the-web) 的 Pro、Max、Team 和 Enterprise 計劃上可用。在 [claude.ai/code/routines](https://claude.ai/code/routines) 創建和管理它們，或使用 CLI 中的 `/schedule` 命令。
24 24
25Team 和 Enterprise 管理員可以在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 的例行程序切換中為所有成員禁用例行程序。禁用後，現有例行程序停止運行，成員無法創建新的。
26
25本頁涵蓋創建例行程序、配置每種觸發器類型、管理運行以及使用限制如何應用。27本頁涵蓋創建例行程序、配置每種觸發器類型、管理運行以及使用限制如何應用。
26 28
27## 示例用例29## 示例用例
354 356
355## 使用和限制357## 使用和限制
356 358
357359例行程序以與互動式工作階段相同的方式消耗訂閱使用量。除了標準訂閱限制外，例行程序還有每個帳戶每天可以啟動多少次執行的每日上限。在 [claude.ai/code/routines](https://claude.ai/code/routines) 或 [claude.ai/settings/usage](https://claude.ai/settings/usage) 查看您目前的消耗和剩餘的每日例行程序執行。例行程序以與互動式會話相同的方式消耗訂閱使用量。除了標準訂閱限制外，例行程序還有每個帳戶每天可以啟動多少次運行的每日上限。在 [claude.ai/code/routines](https://claude.ai/code/routines) 或 [claude.ai/settings/usage](https://claude.ai/settings/usage) 查看您目前的消耗和剩餘的每日例行程序運行。
360
361當例行程序達到每日上限或您的訂閱使用限制時，啟用了額外使用的組織可以繼續在計量超額上運行例行程序。沒有額外使用，額外運行會被拒絕，直到時間窗口重置。從 claude.ai 上的 **Settings > Billing** 啟用額外使用。
362
363一次性運行不計入每日例行程序運行上限。它們像任何其他會話一樣消耗您的常規訂閱使用量，但它們不受每個帳戶每日例行程序運行額度的限制。
364
365## 故障排除
358 366
359367當例行程序達到每日上限或您的訂閱使用限制時，啟用了額外使用的組織可以繼續在計量超額上執行例行程序。沒有額外使用，額外執行會被拒絕，直到時間窗口重置。從 claude.ai 上的 **Settings > Billing** 啟用額外使用。### "例行程序已被您的組織政策禁用"
360 368
361369一次性執行不計入每日例行程序執行上限。它們像任何其他工作階段一樣消耗您的常規訂閱使用量，但它們不受每個帳戶每日例行程序執行額度的限制。您的 Team 或 Enterprise 管理員可能已在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 關閉了 **Routines** 切換。這是一個服務器端組織設置，因此無法從您的本地配置中覆蓋。聯繫您的管理員請求為您的組織啟用例行程序。
362 370
363## 相關資源371## 相關資源
364 372
59* **網路請求批准**：進行網路請求的工具預設需要使用者批准59* **網路請求批准**：進行網路請求的工具預設需要使用者批准
60* **隔離的上下文視窗**：Web fetch 使用單獨的上下文視窗以避免注入潛在的惡意提示60* **隔離的上下文視窗**：Web fetch 使用單獨的上下文視窗以避免注入潛在的惡意提示
61* **信任驗證**：首次程式碼庫執行和新的 MCP servers 需要信任驗證61* **信任驗證**：首次程式碼庫執行和新的 MCP servers 需要信任驗證
6262 * 注意：使用 `-p` 標誌以非互動方式執行時，信任驗證被禁用 * 注意：使用 `-p` 標誌以非互動方式執行時，信任驗證被禁用。例外情況是 [`--worktree`](/zh-TW/worktrees)，它仍然要求已接受該目錄的信任
63* **命令注入檢測**：即使之前已允許列表，可疑的 bash 命令也需要手動批准63* **命令注入檢測**：即使之前已允許列表，可疑的 bash 命令也需要手動批准
64* **故障關閉匹配**：不匹配的命令預設需要手動批准64* **故障關閉匹配**：不匹配的命令預設需要手動批准
65* **自然語言描述**：複雜的 bash 命令包括使用者理解的說明65* **自然語言描述**：複雜的 bash 命令包括使用者理解的說明
41 </Step>41 </Step>
42 42
43 <Step title="定義您的設定">43 <Step title="定義您的設定">
4444 將您的設定新增為 JSON。支援 [`settings.json` 中提供的所有設定](/zh-TW/settings#available-settings)，包括 [hooks](/zh-TW/hooks)、[環境變數](/zh-TW/env-vars) 和[僅限受管的設定](/zh-TW/permissions#managed-only-settings)，例如 `allowManagedPermissionRulesOnly`。 將您的設定新增為 JSON。支援 [`settings.json` 中提供的所有設定](/zh-TW/settings#available-settings)，除了限制於作業系統層級原則傳遞的設定外；請參閱[目前的限制](#current-limitations)以取得該簡短清單。這包括 [hooks](/zh-TW/hooks)、[環境變數](/zh-TW/env-vars) 和[僅限受管的設定](/zh-TW/permissions#managed-only-settings)，例如 `allowManagedPermissionRulesOnly`。
45 45
46 此範例強制執行權限拒絕清單，防止使用者繞過權限，並將權限規則限制為在受管設定中定義的規則：46 此範例強制執行權限拒絕清單，防止使用者繞過權限，並將權限規則限制為在受管設定中定義的規則：
47 47
93 }93 }
94 ```94 ```
95 95
9696 因為 hooks 執行 shell 命令，使用者在套用前會看到[安全核准對話方塊](#security-approval-dialogs)。請參閱[設定 auto mode](/zh-TW/auto-mode-config)，了解 `autoMode` 項目如何影響分類器阻止的內容，以及關於 `allow` 和 `soft_deny` 欄位的重要警告。 因為 hooks 執行 shell 命令，使用者在套用前會看到[安全核准對話方塊](#security-approval-dialogs)。請參閱[設定 auto mode](/zh-TW/auto-mode-config)，了解 `autoMode` 項目如何影響分類器阻止的內容，以及關於 `environment`、`allow`、`soft_deny` 和 `hard_deny` 欄位的重要警告。
97 </Step>97 </Step>
98 98
99 <Step title="儲存並部署">99 <Step title="儲存並部署">
124 124
125* 設定統一套用到組織中的所有使用者。尚不支援每個群組的設定。125* 設定統一套用到組織中的所有使用者。尚不支援每個群組的設定。
126* [MCP 伺服器設定](/zh-TW/mcp#managed-mcp-configuration) 無法透過伺服器管理的設定分發。126* [MCP 伺服器設定](/zh-TW/mcp#managed-mcp-configuration) 無法透過伺服器管理的設定分發。
127* 限制於作業系統層級原則來源的設定，例如 `policyHelper` 和 `wslInheritsWindowsSettings`，不會被接受。改為透過 MDM 或系統 `managed-settings.json` 檔案部署它們。
127 128
128## 設定傳遞129## 設定傳遞
129 130
169| `attribution` | 自訂 git 提交和拉取請求的歸屬。請參閱[歸屬設定](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |169| `attribution` | 自訂 git 提交和拉取請求的歸屬。請參閱[歸屬設定](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |
170| `autoMemoryDirectory` | [自動記憶](/zh-TW/memory#storage-location)儲存的自訂目錄。接受絕對路徑或 `~/` 前綴的路徑。從政策和使用者設定以及 `--settings` 旗標接受。不從專案或本機設定接受，因為複製的儲存庫可能提供任一檔案以將記憶寫入重定向到敏感位置 | `"~/my-memory-dir"` |170| `autoMemoryDirectory` | [自動記憶](/zh-TW/memory#storage-location)儲存的自訂目錄。接受絕對路徑或 `~/` 前綴的路徑。從政策和使用者設定以及 `--settings` 旗標接受。不從專案或本機設定接受，因為複製的儲存庫可能提供任一檔案以將記憶寫入重定向到敏感位置 | `"~/my-memory-dir"` |
171| `autoMemoryEnabled` | 啟用[自動記憶](/zh-TW/memory#enable-or-disable-auto-memory)。當為 `false` 時，Claude 不會從自動記憶目錄讀取或寫入。預設：`true`。您也可以在工作階段期間使用 `/memory` 切換此設定。若要透過環境變數停用，請在 `env` 中設定 [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/zh-TW/env-vars) | `false` |171| `autoMemoryEnabled` | 啟用[自動記憶](/zh-TW/memory#enable-or-disable-auto-memory)。當為 `false` 時，Claude 不會從自動記憶目錄讀取或寫入。預設：`true`。您也可以在工作階段期間使用 `/memory` 切換此設定。若要透過環境變數停用，請在 `env` 中設定 [`CLAUDE_CODE_DISABLE_AUTO_MEMORY`](/zh-TW/env-vars) | `false` |
172172| `autoMode` | 自訂[自動模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)分類器阻止和允許的內容。包含 `environment`、`allow` 和 `soft_deny` 陣列的散文規則。在陣列中包含字面字串 `"$defaults"` 以在該位置繼承內建規則。請參閱[設定自動模式](/zh-TW/auto-mode-config)。不從共享專案設定讀取 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` || `autoMode` | 自訂[自動模式](/zh-TW/permission-modes#eliminate-prompts-with-auto-mode)分類器阻止和允許的內容。包含 `environment`、`allow`、`soft_deny` 和 `hard_deny` 陣列的散文規則。在陣列中包含字面字串 `"$defaults"` 以在該位置繼承內建規則。請參閱[設定自動模式](/zh-TW/auto-mode-config)。不從共享專案設定讀取 | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |
173| `autoScrollEnabled` | 在[全螢幕渲染](/zh-TW/fullscreen)中，跟隨新輸出到對話的底部。預設：`true`。在 `/config` 中顯示為**自動捲軸**。當此設定關閉時，權限提示仍會捲軸進入檢視 | `false` |173| `autoScrollEnabled` | 在[全螢幕渲染](/zh-TW/fullscreen)中，跟隨新輸出到對話的底部。預設：`true`。在 `/config` 中顯示為**自動捲軸**。當此設定關閉時，權限提示仍會捲軸進入檢視 | `false` |
174| `autoUpdatesChannel` | 遵循更新的發行頻道。使用 `"stable"` 以取得通常約一週舊的版本並跳過有重大迴歸的版本，或 `"latest"`（預設）以取得最新版本。若要完全停用自動更新，請在 `env` 中設定 [`DISABLE_AUTOUPDATER`](/zh-TW/setup#disable-auto-updates) | `"stable"` |174| `autoUpdatesChannel` | 遵循更新的發行頻道。使用 `"stable"` 以取得通常約一週舊的版本並跳過有重大迴歸的版本，或 `"latest"`（預設）以取得最新版本。若要完全停用自動更新，請在 `env` 中設定 [`DISABLE_AUTOUPDATER`](/zh-TW/setup#disable-auto-updates) | `"stable"` |
175| `availableModels` | 限制使用者可透過 `/model`、`--model` 或 `ANTHROPIC_MODEL` 選擇的模型。不影響預設選項。請參閱[限制模型選擇](/zh-TW/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |175| `availableModels` | 限制使用者可透過 `/model`、`--model` 或 `ANTHROPIC_MODEL` 選擇的模型。不影響預設選項。請參閱[限制模型選擇](/zh-TW/model-config#restrict-model-selection) | `["sonnet", "haiku"]` |
215| `permissions` | 請參閱下表以了解權限的結構。 | |215| `permissions` | 請參閱下表以了解權限的結構。 | |
216| `plansDirectory` | 自訂計畫檔案的儲存位置。路徑相對於專案根目錄。預設：`~/.claude/plans` | `"./plans"` |216| `plansDirectory` | 自訂計畫檔案的儲存位置。路徑相對於專案根目錄。預設：`~/.claude/plans` | `"./plans"` |
217| `pluginTrustMessage` | （Managed 設定僅限）在安裝前顯示的 plugin 信任警告中附加的自訂訊息。使用此選項新增組織特定的內容，例如確認來自您內部 marketplace 的 plugins 已經過審查。 | `"All plugins from our marketplace are approved by IT"` |217| `pluginTrustMessage` | （Managed 設定僅限）在安裝前顯示的 plugin 信任警告中附加的自訂訊息。使用此選項新增組織特定的內容，例如確認來自您內部 marketplace 的 plugins 已經過審查。 | `"All plugins from our marketplace are approved by IT"` |
218| `policyHelper` | {/* min-version: 2.1.136 */}管理員部署的可執行檔，在啟動時動態計算 managed 設定。僅從 MDM 或系統 `managed-settings.json` 檔案受尊重。請參閱[使用政策協助程式計算 managed 設定](#compute-managed-settings-with-a-policy-helper)。需要 Claude Code v2.1.136 或更新版本 | `{"path": "/usr/local/bin/claude-policy"}` |
218| `preferredNotifChannel` | 工作完成和權限提示通知的方法：`"auto"`、`"terminal_bell"`、`"iterm2"`、`"iterm2_with_bell"`、`"kitty"`、`"ghostty"` 或 `"notifications_disabled"`。預設：`"auto"`，在 iTerm2、Ghostty 和 Kitty 中傳送桌面通知，在其他終端機中不執行任何操作。設定 `"terminal_bell"` 以在任何終端機中響鈴字元。在 `/config` 中顯示為**通知**。請參閱[取得終端機鈴聲或通知](/zh-TW/terminal-config#get-a-terminal-bell-or-notification) | `"terminal_bell"` |219| `preferredNotifChannel` | 工作完成和權限提示通知的方法：`"auto"`、`"terminal_bell"`、`"iterm2"`、`"iterm2_with_bell"`、`"kitty"`、`"ghostty"` 或 `"notifications_disabled"`。預設：`"auto"`，在 iTerm2、Ghostty 和 Kitty 中傳送桌面通知，在其他終端機中不執行任何操作。設定 `"terminal_bell"` 以在任何終端機中響鈴字元。在 `/config` 中顯示為**通知**。請參閱[取得終端機鈴聲或通知](/zh-TW/terminal-config#get-a-terminal-bell-or-notification) | `"terminal_bell"` |
219| `prefersReducedMotion` | 減少或停用 UI 動畫（微調器、閃爍、閃光效果）以提高可訪問性 | `true` |220| `prefersReducedMotion` | 減少或停用 UI 動畫（微調器、閃爍、閃光效果）以提高可訪問性 | `true` |
220| `prUrlTemplate` | PR 徽章的 URL 範本，顯示在頁尾和工具結果摘要中。替換 `gh` 報告的 PR URL 中的 `{host}`、`{owner}`、`{repo}`、`{number}` 和 `{url}`。使用以指向內部程式碼審查工具而不是 `github.com`。不影響 Claude 散文中的 `#123` 自動連結 | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |221| `prUrlTemplate` | PR 徽章的 URL 範本，顯示在頁尾和工具結果摘要中。替換 `gh` 報告的 PR URL 中的 `{host}`、`{owner}`、`{repo}`、`{number}` 和 `{url}`。使用以指向內部程式碼審查工具而不是 `github.com`。不影響 Claude 散文中的 `#123` 自動連結 | `"https://reviews.example.com/{owner}/{repo}/pull/{number}"` |
470}471}
471```472```
472 473
474### 使用政策協助程式計算 managed 設定
475
476`policyHelper` 設定指向在啟動時計算 managed 設定的可執行檔，因此管理員可以從裝置狀態、身份或遠端服務衍生政策，而不是靜態檔案。從 MDM 或系統 `managed-settings.json` 檔案設定它。Claude Code 在任何其他範圍中出現 `policyHelper` 時會忽略它，包括使用者設定、專案設定、HKCU 登錄 hive 和[伺服器管理的設定](/zh-TW/server-managed-settings)。
477
478該設定接受這些金鑰：
479
480| 金鑰 | 類型 | 說明 |
481| ------------------- | ------ | ------------------------------------------- |
482| `path` | string | 協助程式可執行檔的絕對路徑 |
483| `timeoutMs` | number | 在將執行視為失敗之前等待協助程式多長時間 |
484| `refreshIntervalMs` | number | 在背景中重新執行協助程式的頻率。設定為 `0` 以停用重新整理，或至少 `60000` |
485
486協助程式將 JSON 信封寫入 stdout。將設定放在 `managedSettings` 金鑰下，而不是在頂層，因為裸設定物件會以 `managedSettings` 未定義的方式解析並應用任何內容：
487
488```json theme={null}
489{
490 "managedSettings": {
491 "permissions": { "deny": ["Read(//etc/secrets/**)"] }
492 },
493 "claudeMd": "# Organization context\n...",
494 "appendSystemPrompt": "Always cite the internal style guide."
495}
496```
497
498當協助程式發出 `managedSettings` 時，該物件會替換該執行的檔案型 managed 設定。當協助程式在啟動時以非零狀態結束時，Claude Code 會列印錯誤並拒絕啟動，因此需要中斷恢復能力的協助程式應從自己的快取提供並以 `0` 結束。
499
473### 設定優先順序500### 設定優先順序
474 501
475設定按優先順序順序應用。從最高到最低：502設定按優先順序順序應用。從最高到最低：
8 8
9每週開發摘要重點介紹最有可能改變您工作方式的功能。每個條目都包含可執行的程式碼、簡短的示範和完整文件的連結。如需每個錯誤修復和次要改進，請參閱 [changelog](/zh-TW/changelog)。9每週開發摘要重點介紹最有可能改變您工作方式的功能。每個條目都包含可執行的程式碼、簡短的示範和完整文件的連結。如需每個錯誤修復和次要改進，請參閱 [changelog](/zh-TW/changelog)。
10 10
11<Update label="Week 19" description="May 4–8, 2026" tags={["v2.1.128–v2.1.136"]}>
12 **Plugins 從 `.zip` 檔案和 URL 載入**：`--plugin-dir` 現在接受 `.zip` 檔案，而 `--plugin-url` 會為目前的工作階段擷取外掛程式封存。
13
14 本週還有：**`worktree.baseRef`** 選擇新的 worktrees 是否從遠端預設或本機 `HEAD` 分支；**auto mode hard deny rules** 無條件地阻止操作，不論允許例外；以及 **hooks 看到作用中的努力等級**，透過 `effort.level` 和 `$CLAUDE_EFFORT`。
15
16 [閱讀 Week 19 摘要 →](/zh-TW/whats-new/2026-w19)
17</Update>
18
19<Update label="Week 18" description="April 27 – May 1, 2026" tags={["v2.1.120–v2.1.126"]}>
20 **沒有 Git Bash 的 Windows**：不再需要 Git for Windows，當 Bash 不存在時，Claude Code 會使用 PowerShell 作為 shell 工具。
21
22 本週還有：**`claude ultrareview`** 將雲端程式碼審查帶到 CI 和指令碼；**`claude project purge`** 清理專案的本機狀態；以及將 **PR URL 貼到 `/resume`** 中找到建立它的工作階段。
23
24 [閱讀 Week 18 摘要 →](/zh-TW/whats-new/2026-w18)
25</Update>
26
11<Update label="Week 17" description="April 20–24, 2026" tags={["v2.1.114–v2.1.119"]}>27<Update label="Week 17" description="April 20–24, 2026" tags={["v2.1.114–v2.1.119"]}>
12 **`/ultrareview`** 作為公開研究預覽版開放：一群除蟲代理在雲端執行，發現結果會自動回傳到您的 CLI 或桌面應用。28 **`/ultrareview`** 作為公開研究預覽版開放：一群除蟲代理在雲端執行，發現結果會自動回傳到您的 CLI 或桌面應用。
13 29
19<Update label="Week 16" description="April 13–17, 2026" tags={["v2.1.105–v2.1.113"]}>35<Update label="Week 16" description="April 13–17, 2026" tags={["v2.1.105–v2.1.113"]}>
20 **Claude Opus 4.7** 成為 Max 和 Team Premium 的新預設版本，具有新的 `xhigh` 努力等級（推薦用於大多數編碼工作）和互動式 `/effort` 滑桿來調整設定。36 **Claude Opus 4.7** 成為 Max 和 Team Premium 的新預設版本，具有新的 `xhigh` 努力等級（推薦用於大多數編碼工作）和互動式 `/effort` 滑桿來調整設定。
21 37
2238 本週還有：**Routines** 在 Claude Code on the web 上從排程、GitHub 事件或 API 呼叫觸發樣板化雲端代理；`/ultrareview` 在雲端執行平行多代理程式碼審查；`/usage` 顯示驅動您限制的因素；CLI 移至原生二進位檔。 本週還有：**Routines** 在 Claude Code on the web 上從排程、GitHub 事件或 API 呼叫觸發樣板化雲端代理；**mobile push notifications** 在長時間工作完成或 Claude 需要您時向您的手機發送通知；`/usage` 顯示驅動您限制的因素；CLI 移至原生二進位檔。
23 39
24 [閱讀 Week 16 摘要 →](/zh-TW/whats-new/2026-w16)40 [閱讀 Week 16 摘要 →](/zh-TW/whats-new/2026-w16)
25</Update>41</Update>
4 4
5# 第 16 週 · 2026 年 4 月 13–17 日5# 第 16 週 · 2026 年 4 月 13–17 日
6 6
77> Claude Opus 4.7 搭配新的 xhigh 努力等級、Claude Code 網頁版上的 Routines、/ultrareview 雲端程式碼審查、顯示限制驅動因素的 /usage 細目分析，以及取代捆綁 JavaScript 的原生二進位檔。> Claude Opus 4.7 搭配新的 xhigh 努力等級、Claude Code 網頁版上的 Routines、行動推播通知在 Claude 需要您時 ping 您的手機、顯示限制驅動因素的 /usage 細目分析，以及取代捆綁 JavaScript 的原生二進位檔。
8 8
9<div className="digest-meta">9<div className="digest-meta">
10 <span>版本 <a href="/zh-TW/docs/changelog#2-1-105">v2.1.105 → v2.1.113</a></span>10 <span>版本 <a href="/zh-TW/docs/changelog#2-1-105">v2.1.105 → v2.1.113</a></span>
73 73
74<div className="digest-feature">74<div className="digest-feature">
75 <div className="digest-feature-header">75 <div className="digest-feature-header">
7676 <span className="digest-feature-title">/ultrareview</span> <span className="digest-feature-title">行動推播通知</span>
7777 <span className="digest-feature-pill">v2.1.111</span> <span className="digest-feature-pill">mobile</span>
78 </div>78 </div>
79 79
8080 <p className="digest-feature-lede">雲端中的全面程式碼審查。Ultrareview 在 Claude Code 網頁版上將您的分支分散到平行審查者，對每個發現執行對抗性批評傳遞，並傳回已驗證的發現報告，同時您的終端機保持空閒。不帶引數呼叫以審查您目前的分支，或傳遞 PR 編號以擷取並審查該 PR。啟動對話框現在顯示 diffstat，讓您在確認前知道要上傳的內容。</p> <p className="digest-feature-lede">連接 <a href="/zh-TW/docs/remote-control">Remote Control</a> 後，Claude 可以在長任務完成或需要決定以繼續進行時傳送推播通知到您的手機。在 <code>/config</code> 中使用「Claude 決定時推播」開啟它，或在您的提示中要求一個。當您啟動長代理執行並想離開終端機時很有用。</p>
81 81
8282 <p className="digest-feature-try">審查您所在的分支：</p> <Frame>
8383 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/uII1TETOZxBUZ3lB/images/whats-new/push-notifications.mp4?fit=max&auto=format&n=uII1TETOZxBUZ3lB&q=85&s=c91a967139596500cbdb581a53822ac1" data-path="images/whats-new/push-notifications.mp4" />
8484 ```text Claude Code theme={null} </Frame>
85 > /ultrareview
86 ```
87 85
8886 <p className="digest-feature-try">或將其指向 PR：</p> <p className="digest-feature-try">要求 Claude 在完成時 ping 您：</p>
89 87
90 ```text Claude Code theme={null}88 ```text Claude Code theme={null}
9189 > /ultrareview 1234 > notify me when the tests pass
92 ```90 ```
93 91
9492 <a className="digest-feature-link" href="/zh-TW/docs/ultrareview">Ultrareview 指南</a> <a className="digest-feature-link" href="/zh-TW/docs/remote-control#mobile-push-notifications">Remote Control：行動推播通知</a>
95</div>93</div>
96 94
97<div className="digest-feature">95<div className="digest-feature">
116 <p className="digest-wins-title">其他成果</p>114 <p className="digest-wins-title">其他成果</p>
117 115
118 <div className="digest-wins-grid">116 <div className="digest-wins-grid">
117 <div>新的 <a href="/zh-TW/docs/ultrareview"><code>/ultrareview</code></a>：使用平行多代理分析和對抗性批評傳遞在雲端進行全面程式碼審查。不帶引數執行以審查您目前的分支，或 <code>/ultrareview \<PR#></code> 審查特定 PR</div>
119 <div><a href="/zh-TW/docs/permission-modes#eliminate-prompts-with-auto-mode">自動模式</a>現在可供 Max 訂閱者在 Opus 4.7 上使用，<code>--enable-auto-mode</code> 旗標不再需要</div>118 <div><a href="/zh-TW/docs/permission-modes#eliminate-prompts-with-auto-mode">自動模式</a>現在可供 Max 訂閱者在 Opus 4.7 上使用，<code>--enable-auto-mode</code> 旗標不再需要</div>
120 <div><a href="/zh-TW/docs/interactive-mode#session-recap">工作階段摘要</a>顯示您離開時發生的一行摘要；按需執行 <code>/recap</code> 或從 <code>/config</code> 關閉它</div>119 <div><a href="/zh-TW/docs/interactive-mode#session-recap">工作階段摘要</a>顯示您離開時發生的一行摘要；按需執行 <code>/recap</code> 或從 <code>/config</code> 關閉它</div>
121 <div>新的 <code>/tui</code> 命令和 <code>tui</code> 設定在對話中間切換經典和無閃爍渲染；焦點檢視從 <code>Ctrl+O</code> 移至其自己的 <code>/focus</code> 命令</div>120 <div>新的 <code>/tui</code> 命令和 <code>tui</code> 設定在對話中間切換經典和無閃爍渲染；焦點檢視從 <code>Ctrl+O</code> 移至其自己的 <code>/focus</code> 命令</div>
122 <div>推播通知工具：連接 <a href="/zh-TW/docs/remote-control">Remote Control</a> 並啟用「Claude 決定時推播」，Claude 可在需要您時 ping 您的手機</div>
123 <div>外掛程式可透過在工作階段開始或技能呼叫時自動啟用的頂層 <code>monitors</code> 資訊清單鍵來提供背景監視程式</div>121 <div>外掛程式可透過在工作階段開始或技能呼叫時自動啟用的頂層 <code>monitors</code> 資訊清單鍵來提供背景監視程式</div>
124 <div><code>/theme</code> 中的「自動（符合終端機）」選項遵循您終端機的深色/淺色模式</div>122 <div><code>/theme</code> 中的「自動（符合終端機）」選項遵循您終端機的深色/淺色模式</div>
125 <div><code>/fewer-permission-prompts</code> 掃描您的文字記錄以尋找常見的唯讀 Bash 和 MCP 呼叫，並為 <code>.claude/settings.json</code> 提議允許清單</div>123 <div><code>/fewer-permission-prompts</code> 掃描您的文字記錄以尋找常見的唯讀 Bash 和 MCP 呼叫，並為 <code>.claude/settings.json</code> 提議允許清單</div>
1> ## Documentation Index
2> 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.
4
5# 第 18 週 · 4 月 27 日 – 5 月 1 日，2026 年
6
7> Claude Code 在 Windows 上無需 Git Bash 即可運行，claude auth login 在瀏覽器回調無法到達 localhost 時接受貼上的 OAuth 代碼，claude project purge 清理每個專案的本地狀態，將 PR URL 貼到 /resume 中可找到建立該會話的會話。
8
9<div className="digest-meta">
10 <span>Releases <a href="/zh-TW/docs/changelog#2-1-120">v2.1.120 → v2.1.126</a></span>
11 <span>4 個功能 · 4 月 27 日 – 5 月 1 日</span>
12</div>
13
14<div className="digest-feature">
15 <div className="digest-feature-header">
16 <span className="digest-feature-title">無需瀏覽器回調即可登入</span>
17 <span className="digest-feature-pill">v2.1.126</span>
18 </div>
19
20 <p className="digest-feature-lede"><code>claude auth login</code> 現在在瀏覽器回調無法到達 localhost 時接受直接貼到終端機的 OAuth 代碼。這涵蓋了 WSL2、SSH 會話和容器，其中重新導向到本地連接埠不起作用。同一版本也修復了在緩慢或代理連接以及僅限 IPv6 的 devcontainers 上的登入逾時問題。</p>
21
22 <p className="digest-feature-try">登入，然後貼上來自瀏覽器的代碼：</p>
23
24 ```bash theme={null}
25 claude auth login
26 ```
27
28 <a className="digest-feature-link" href="/zh-TW/docs/cli-reference#cli-commands">CLI 參考</a>
29</div>
30
31<div className="digest-feature">
32 <div className="digest-feature-header">
33 <span className="digest-feature-title">claude project purge</span>
34 <span className="digest-feature-pill">v2.1.126</span>
35 </div>
36
37 <p className="digest-feature-lede">刪除專案的所有 Claude Code 狀態：文字記錄、任務、檔案歷史記錄和專案的設定項目。支援 `--dry-run` 預覽、`-y`/`--yes` 跳過確認、`-i`/`--interactive` 選擇，以及 `--all` 清理每個專案。</p>
38
39 <p className="digest-feature-try">預覽將移除的內容：</p>
40
41 ```bash theme={null}
42 claude project purge --dry-run
43 ```
44
45 <p className="digest-feature-try">然後真正執行：</p>
46
47 ```bash theme={null}
48 claude project purge
49 ```
50
51 <a className="digest-feature-link" href="/zh-TW/docs/cli-reference">CLI 參考</a>
52</div>
53
54<div className="digest-feature">
55 <div className="digest-feature-header">
56 <span className="digest-feature-title">按 PR URL 繼續</span>
57 <span className="digest-feature-pill">v2.1.122</span>
58 </div>
59
60 <p className="digest-feature-lede">當您使用 <code>gh pr create</code> 建立提取請求時，Claude Code 會將其連結到產生該請求的會話。現在您可以僅從 PR URL 返回該會話，無需記住其名稱。</p>
61
62 <p className="digest-feature-try">開啟會話選擇器：</p>
63
64 ```text Claude Code theme={null}
65 > /resume
66 ```
67
68 <p className="digest-feature-try">將 PR URL 貼到選擇器中。貼上的第一個字元會讓您進入搜尋模式，列表會篩選到建立該 PR 的會話。按 Enter 鍵繼續該會話。GitHub、GitHub Enterprise、GitLab 和 Bitbucket 提取和合併請求 URL 都可以使用。</p>
69
70 ```text Claude Code theme={null}
71 https://github.com/your-org/your-repo/pull/1234
72 ```
73
74 <p className="digest-feature-try">若要跳過選擇器，請改為在命令列上傳遞 PR 編號：</p>
75
76 ```bash theme={null}
77 claude --from-pr 1234
78 ```
79
80 <a className="digest-feature-link" href="/zh-TW/docs/sessions#use-the-session-picker">會話：使用會話選擇器</a>
81</div>
82
83<div className="digest-feature">
84 <div className="digest-feature-header">
85 <span className="digest-feature-title">Windows 無需 Git Bash</span>
86 <span className="digest-feature-pill">Windows</span>
87 </div>
88
89 <p className="digest-feature-lede">不再需要 Git for Windows。當 Bash 不存在時，Claude Code 使用 PowerShell 作為 shell 工具，當啟用 PowerShell 工具時，它被視為主要 shell。現在會自動偵測透過 Microsoft Store、MSI 不含 PATH 或 <code>.NET</code> 全域工具安裝的 PowerShell 7。</p>
90
91 <a className="digest-feature-link" href="/zh-TW/docs/setup">設定指南</a>
92</div>
93
94<div className="digest-wins">
95 <p className="digest-wins-title">其他成就</p>
96
97 <div className="digest-wins-grid">
98 <div>MCP 伺服器可以在其設定中使用 <code>alwaysLoad: true</code> 選擇退出工具搜尋延遲，以便該伺服器的所有工具始終可用</div>
99 <div>新的 <code>claude plugin prune</code> 移除孤立的自動安裝外掛程式相依性，<code>plugin uninstall --prune</code> 級聯</div>
100 <div><code>/skills</code> 現在有一個類型篩選搜尋框，因此您可以在長列表中找到技能而無需捲動</div>
101 <div><code>PostToolUse</code> hooks 可以透過 <code>hookSpecificOutput.updatedToolOutput</code> 替換任何工具的工具輸出，不僅限於 MCP 工具</div>
102 <div>新的 <a href="/zh-TW/docs/ultrareview"><code>claude ultrareview</code></a> 子命令從 CI 或指令碼非互動地執行 <code>/ultrareview</code>：將發現列印到 stdout（<code>--json</code> 用於原始輸出）並在完成時退出 0 或失敗時退出 1</div>
103 <div><code>--dangerously-skip-permissions</code> 現在繞過對 <code>.claude/</code>、<code>.git/</code>、<code>.vscode/</code>、shell 設定檔和其他先前受保護路徑的寫入提示，同時災難性移除命令仍會提示作為安全網</div>
104 <div>當 <code>ANTHROPIC\_BASE\_URL</code> 指向 Anthropic 相容閘道時，<code>/model</code> 選擇器可以列出來自您閘道的 <code>/v1/models</code> 端點的模型；自 v2.1.129 起使用 <code>CLAUDE\_CODE\_ENABLE\_GATEWAY\_MODEL\_DISCOVERY=1</code> 選擇加入</div>
105 <div>在啟動期間遇到暫時性錯誤的 MCP 伺服器現在會自動重試最多 3 次，而不是保持斷開連接</div>
106 <div><code>ANTHROPIC\_BEDROCK\_SERVICE\_TIER</code> 選擇 Bedrock 服務層：<code>default</code>、<code>flex</code> 或 <code>priority</code></div>
107 <div><code>/terminal-setup</code> 啟用 iTerm2 的剪貼簿存取設定，以便 <code>/copy</code> 可以運作，包括從 tmux</div>
108 <div>Vertex AI 現在支援 X.509 憑證型工作負載身分識別聯盟 (mTLS ADC)</div>
109 <div>重大記憶體洩漏修復：影像繁重的會話、大型文字記錄歷史上的 <code>/usage</code> 以及沒有進度事件的長時間執行工具</div>
110 </div>
111</div>
112
113[v2.1.120–v2.1.126 的完整變更日誌 →](/zh-TW/changelog#2-1-120)
1> ## Documentation Index
2> 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.
4
5# 第 19 週 · 2026 年 5 月 4–8 日
6
7> 從 .zip 檔案和 URL 載入 plugins，使用 Ctrl+R 搜尋所有專案的命令歷史記錄，從本機 HEAD 或遠端預設分支建立新 worktrees，以及使用 auto mode hard deny 規則無條件地阻止操作。
8
9<div className="digest-meta">
10 <span>Releases <a href="/zh-TW/changelog#2-1-128">v2.1.128 → v2.1.136</a></span>
11 <span>2 features · 5 月 4–8 日</span>
12</div>
13
14<div className="digest-feature">
15 <div className="digest-feature-header">
16 <span className="digest-feature-title">從 .zip 檔案和 URL 載入 Plugins</span>
17 </div>
18
19 <p className="digest-feature-lede">`--plugin-dir` 現在除了接受目錄外，還接受 <code>.zip</code> plugin 檔案，新的 `--plugin-url` 旗標可在目前工作階段從 URL 取得 plugin 檔案。適合在將 plugin 新增至 marketplace 之前試用，或從成品存放區發送內部 plugins。</p>
20
21 <p className="digest-feature-try">直接從 URL 載入 plugin：</p>
22
23 ```bash terminal theme={null}
24 claude --plugin-url https://example.com/my-plugin.zip
25 ```
26
27 <a className="digest-feature-link" href="/zh-TW/plugins">Plugins 指南</a>
28</div>
29
30<div className="digest-feature">
31 <div className="digest-feature-header">
32 <span className="digest-feature-title">在所有專案中搜尋歷史記錄</span>
33 <span className="digest-feature-pill">v2.1.129</span>
34 </div>
35
36 <p className="digest-feature-lede"><code>Ctrl+R</code> 反向搜尋現在預設搜尋所有專案中的所有提示，恢復了 v2.1.124 之前的行為。搜尋時按 <code>Ctrl+S</code> 可縮小範圍至目前專案或工作階段。當您記得上週在另一個 repo 中執行的命令，但不想費力尋找時，這非常方便。</p>
37
38 <a className="digest-feature-link" href="/zh-TW/interactive-mode#command-history">Interactive mode：命令歷史記錄</a>
39</div>
40
41<div className="digest-wins">
42 <p className="digest-wins-title">其他改進</p>
43
44 <div className="digest-wins-grid">
45 <div>新的 <code>worktree.baseRef</code> 設定（<code>fresh</code> | <code>head</code>）控制 <code>--worktree</code>、<code>EnterWorktree</code> tool 和 agent-isolation worktrees 是從遠端預設分支還是本機 <code>HEAD</code> 建立分支；預設的 <code>fresh</code> 會將未推送的提交排除在新 worktrees 之外</div>
46 <div>新的 <code>settings.autoMode.hard\_deny</code> 規則無條件地在 auto mode 中阻止符合條件的操作，無論允許例外如何，適用於即使套用更廣泛的允許規則也不應自動執行的操作</div>
47 <div>Hooks 現在透過 `effort.level` JSON 輸入欄位和 `$CLAUDE_EFFORT` 環境變數接收作用中的努力等級，Bash tool 命令可以讀取 <code>\$CLAUDE\_EFFORT</code></div>
48 <div><code>CLAUDE\_CODE\_DISABLE\_ALTERNATE\_SCREEN=1</code> 選擇退出全螢幕替代螢幕渲染器，並將對話保留在終端機的原生 scrollback 中</div>
49 <div><code>CLAUDE\_CODE\_PACKAGE\_MANAGER\_AUTO\_UPDATE</code> 允許 Homebrew 或 WinGet 安裝在背景中執行升級並提示重新啟動</div>
50 <div><code>CLAUDE\_CODE\_SESSION\_ID</code> 現在位於 Bash tool 子程序環境中，與傳遞給 hooks 的 <code>session\_id</code> 相符</div>
51 <div><code>/mcp</code> 現在顯示已連線伺服器的 tool 計數，並標記以 0 個 tools 連線的伺服器</div>
52 <div><code>--channels</code> 現在適用於 console（API 金鑰）驗證</div>
53 <div>Bash、hooks、MCP 和 LSP 等子程序不再繼承 <code>OTEL\_\*</code> 環境變數，因此透過 Bash tool 執行的 OTEL 檢測應用程式不再會採用 CLI 自身的 OTLP 端點</div>
54 <div>Sub-agent 進度摘要現在會命中 prompt cache，將 <code>cache\_creation</code> token 成本降低約 3 倍</div>
55 <div>多項 OAuth 和認證可靠性修正：平行工作階段不再在重新整理 token 競爭後卡在 401，MCP OAuth 重新整理 tokens 在多個伺服器並行重新整理時不再遺失，並修正了來自並行認證寫入的罕見登入迴圈</div>
56 <div>新的 <code>parentSettingsBehavior</code> 管理員金鑰讓管理員可以選擇將 SDK <code>managedSettings</code> 納入原則合併</div>
57 </div>
58</div>
59
60[v2.1.128–v2.1.136 的完整變更日誌 →](/zh-TW/changelog#2-1-128)
