Documentation — Spybara

admin-setup.md +2 −0

Details

92 92

93透過 claude.ai 或 Anthropic API 進行身份驗證的組織成員也可以在不部署設定的情況下管理模型：[組織模型限制](/zh-TW/model-config#organization-model-restrictions)停用個別模型、[組織預設模型](/zh-TW/model-config#organization-default-model)設定新會話啟動時使用的模型，以及[組織工作量限制](/zh-TW/model-config#organization-effort-limits)限制每個角色的工作量級別。所有三個控制都需要 Claude Enterprise 方案。模型限制和工作量限制在伺服器端執行；預設模型是一個起點，使用者可以變更，除非組織強制執行。強制執行適用於有限的組織集合；請向您的 Anthropic 帳戶團隊詢問可用性。這些控制都不會到達 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 上的會話；在這些提供者上，使用上面的 `availableModels` 進行限制，以及受管設定中的 `model` 鍵作為預設值。

93權限規則和沙箱涵蓋不同的層。拒絕 WebFetch 會阻止 Claude 的 fetch 工具，但如果允許 Bash，`curl` 和 `wget` 仍然可以到達任何 URL。沙箱透過在作業系統級別執行的網路網域允許清單來彌補這一差距。95權限規則和沙箱涵蓋不同的層。拒絕 WebFetch 會阻止 Claude 的 fetch 工具，但如果允許 Bash，`curl` 和 `wget` 仍然可以到達任何 URL。沙箱透過在作業系統級別執行的網路網域允許清單來彌補這一差距。

94 96

95有關這些控制防禦的威脅模型，請參閱 [Security](/zh-TW/security)。97有關這些控制防禦的威脅模型，請參閱 [Security](/zh-TW/security)。

advisor.md +4 −3

Details

85顧問的能力必須至少與主要模型相同。每個主要模型接受的顧問為：85顧問的能力必須至少與主要模型相同。每個主要模型接受的顧問為：

86 86

87| 主要模型 | 接受的顧問 | 備註 |87| 主要模型 | 接受的顧問 | 備註 |

~~88| ----------------------------------------------- | ------------------------ | ------------------------------------------------------------ |~~88| ----------------------------------------------- | ----------------------- | -------------------------------------------------------------------------------------- |

90| Sonnet 4.6 | Fable、Opus、Sonnet | |90| Sonnet 4.6 | Fable、Opus、Sonnet | |

93| Opus 4.7 或更新版本 | Fable、Opus 4.7、Opus 4.8 | Opus 4.7 和 Opus 4.8 的能力排名相同，因此任一個都接受另一個作為顧問。Opus 4.7 主要模型搭配 Opus 4.6 或 Sonnet 5 顧問會被拒絕 |

93| Fable 5 ({/* min-version: 2.1.170 */}v2.1.170+) | Fable | Opus 或 Sonnet 顧問會被拒絕 |94| Fable 5 ({/* min-version: 2.1.170 */}v2.1.170+) | Fable | Opus 或 Sonnet 顧問會被拒絕 |

94 95

95Fable 5 需要 Claude Code v2.1.170 或更新版本以及 Fable 5 存取權，無論它是充當主要模型還是顧問。96Fable 5 需要 Claude Code v2.1.170 或更新版本以及 Fable 5 存取權，無論它是充當主要模型還是顧問。

174/advisor off175/advisor off

175```176```

176 177

177若要完全停用顧問工具，包括 `/advisor` 命令和 `--advisor` 旗標，設定 `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`。請參閱[環境變數](/zh-TW/env-vars)。178若要完全停用顧問工具，設定 `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`。`/advisor` 命令變為無法使用，任何已設定的 `advisorModel` 都會被忽略。`--advisor` 旗標被接受但沒有效果；傳遞它的現有指令碼會繼續運作而不會出現錯誤。請參閱[環境變數](/zh-TW/env-vars)。

178 179

179<h2 id="compare-with-related-features">180<h2 id="compare-with-related-features">

180 與相關功能的比較181 與相關功能的比較

agent-sdk/agent-loop.md +41 −0

Details

86<Accordion title="範例：檢查訊息類型並處理結果">86<Accordion title="範例：檢查訊息類型並處理結果">

87 <CodeGroup>87 <CodeGroup>

88 ```python Python theme={null}88 ```python Python theme={null}

89 import asyncio

89 from claude_agent_sdk import query, AssistantMessage, ResultMessage90 from claude_agent_sdk import query, AssistantMessage, ResultMessage

90 91

93 async def main():

94 try:

91 async for message in query(prompt="Summarize this project"):95 async for message in query(prompt="Summarize this project"):

92 if isinstance(message, AssistantMessage):96 if isinstance(message, AssistantMessage):

93 print(f"Turn completed: {len(message.content)} content blocks")97 print(f"Turn completed: {len(message.content)} content blocks")

96 print(message.result)100 print(message.result)

97 else:101 else:

98 print(f"Stopped: {message.subtype}")102 print(f"Stopped: {message.subtype}")

103 except Exception as error:

104 # A single-shot query() raises after yielding an error result. If the

105 # failure was an error result, the error subtype branches above have

106 # already run; connection or process failures yield no result message.

107 print(f"Session ended with an error: {error}")

108

109

110 asyncio.run(main())

99 ```111 ```

100 112

101 ```typescript TypeScript theme={null}113 ```typescript TypeScript theme={null}

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

103 115

116 try {

104 for await (const message of query({ prompt: "Summarize this project" })) {117 for await (const message of query({ prompt: "Summarize this project" })) {

105 if (message.type === "assistant") {118 if (message.type === "assistant") {

106 console.log(`Turn completed: ${message.message.content.length} content blocks`);119 console.log(`Turn completed: ${message.message.content.length} content blocks`);

113 }126 }

114 }127 }

115 }128 }

129 } catch (error) {

130 // A single-shot query() throws after yielding an error result. If the

131 // failure was an error result, the error subtype branches above have

132 // already run; connection or process failures yield no result message.

133 console.log(`Session ended with an error: ${error}`);

134 }

116 ```135 ```

117 </CodeGroup>136 </CodeGroup>

118</Accordion>137</Accordion>

321 340

322`result` 欄位（最終文字輸出）僅在 `success` 變體上存在，因此在讀取它之前始終檢查子類型。所有結果子類型都帶有 `total_cost_usd`、`usage`、`num_turns` 和 `session_id`，因此您可以追蹤成本並在錯誤後恢復。在 Python 中，`total_cost_usd` 和 `usage` 被類型化為可選的，在某些錯誤路徑上可能是 `None`，因此在格式化它們之前進行保護。請參閱 [追蹤成本和使用量](/zh-TW/agent-sdk/cost-tracking) 以了解有關解釋 `usage` 欄位的詳細資訊。341`result` 欄位（最終文字輸出）僅在 `success` 變體上存在，因此在讀取它之前始終檢查子類型。所有結果子類型都帶有 `total_cost_usd`、`usage`、`num_turns` 和 `session_id`，因此您可以追蹤成本並在錯誤後恢復。在 Python 中，`total_cost_usd` 和 `usage` 被類型化為可選的，在某些錯誤路徑上可能是 `None`，因此在格式化它們之前進行保護。請參閱 [追蹤成本和使用量](/zh-TW/agent-sdk/cost-tracking) 以了解有關解釋 `usage` 欄位的詳細資訊。

323 342

343<Note>

344 當查詢以錯誤結果結束時：

345

346 * 單次 `query()` 呼叫會產生最終結果訊息，然後引發包含失敗文字的錯誤，例如 `Reached maximum number of turns`。引發是有意的 — 如果您的程式碼需要在其後繼續，請將迴圈包裝在 try 區塊中。底層 Claude Code 程序也會以非零代碼退出。

347 * 串流輸入工作階段保持活躍，您可以繼續傳送訊息。

348</Note>

349

324結果還包括一個 `stop_reason` 欄位（TypeScript 中的 `string | null`、Python 中的 `str | None`），指示模型為什麼在最後一個回合停止生成。常見值是 `end_turn`（模型正常完成）、`max_tokens`（達到輸出代幣限制）和 `refusal`（模型拒絕了請求）。在錯誤結果子類型上，`stop_reason` 帶有迴圈結束前最後一個助手回應的值。要檢測拒絕，請檢查 `stop_reason === "refusal"`（TypeScript）或 `stop_reason == "refusal"`（Python）。請參閱 [`SDKResultMessage`](/zh-TW/agent-sdk/typescript#sdkresultmessage)（TypeScript）或 [`ResultMessage`](/zh-TW/agent-sdk/python#resultmessage)（Python）以了解完整類型。350結果還包括一個 `stop_reason` 欄位（TypeScript 中的 `string | null`、Python 中的 `str | None`），指示模型為什麼在最後一個回合停止生成。常見值是 `end_turn`（模型正常完成）、`max_tokens`（達到輸出代幣限制）和 `refusal`（模型拒絕了請求）。在錯誤結果子類型上，`stop_reason` 帶有迴圈結束前最後一個助手回應的值。要檢測拒絕，請檢查 `stop_reason === "refusal"`（TypeScript）或 `stop_reason == "refusal"`（Python）。請參閱 [`SDKResultMessage`](/zh-TW/agent-sdk/typescript#sdkresultmessage)（TypeScript）或 [`ResultMessage`](/zh-TW/agent-sdk/python#resultmessage)（Python）以了解完整類型。

325 351

326<h2 id="hooks">352<h2 id="hooks">

348 374

349此範例將本頁的關鍵概念組合成一個修復失敗測試的單個代理程式。它使用允許的工具（自動批准，以便代理程式自主執行）、專案設定和回合和推理努力的安全限制來配置代理程式。當迴圈執行時，它捕獲工作階段 ID 以進行潛在恢復、處理最終結果並列印總成本。375此範例將本頁的關鍵概念組合成一個修復失敗測試的單個代理程式。它使用允許的工具（自動批准，以便代理程式自主執行）、專案設定和回合和推理努力的安全限制來配置代理程式。當迴圈執行時，它捕獲工作階段 ID 以進行潛在恢復、處理最終結果並列印總成本。

350 376

377因為單一的 `query()` 呼叫在產生錯誤結果後會引發異常，迴圈被包裝在 try 區塊中，以便在達到限制時指令碼能夠乾淨地退出。

378

351<CodeGroup>379<CodeGroup>

352 ```python Python theme={null}380 ```python Python theme={null}

353 import asyncio381 import asyncio

357 async def run_agent():385 async def run_agent():

358 session_id = None386 session_id = None

359 387

388 try:

360 async for message in query(389 async for message in query(

361 prompt="Find and fix the bug causing test failures in the auth module",390 prompt="Find and fix the bug causing test failures in the auth module",

362 options=ClaudeAgentOptions(391 options=ClaudeAgentOptions(

389 print(f"Stopped: {message.subtype}")418 print(f"Stopped: {message.subtype}")

390 if message.total_cost_usd is not None:419 if message.total_cost_usd is not None:

391 print(f"Cost: ${message.total_cost_usd:.4f}")420 print(f"Cost: ${message.total_cost_usd:.4f}")

421 except Exception as error:

422 # A single-shot query() raises after yielding an error result. If the

423 # failure was an error result, the error subtype branches above have

424 # already run; connection or process failures yield no result message.

425 print(f"Session ended with an error: {error}")

392 426

393 427

394 asyncio.run(run_agent())428 asyncio.run(run_agent())

399 433

400 let sessionId: string | undefined;434 let sessionId: string | undefined;

401 435

436 try {

402 for await (const message of query({437 for await (const message of query({

403 prompt: "Find and fix the bug causing test failures in the auth module",438 prompt: "Find and fix the bug causing test failures in the auth module",

404 options: {439 options: {

428 console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);463 console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);

429 }464 }

430 }465 }

466 } catch (error) {

467 // A single-shot query() throws after yielding an error result. If the

468 // failure was an error result, the error subtype branches above have

469 // already run; connection or process failures yield no result message.

470 console.log(`Session ended with an error: ${error}`);

471 }

431 ```472 ```

432</CodeGroup>473</CodeGroup>

433 474

agent-sdk/cost-tracking.md +45 −2

Details

63 ```typescript TypeScript theme={null}63 ```typescript TypeScript theme={null}

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

65 65

66 try {

66 for await (const message of query({ prompt: "Summarize this project" })) {67 for await (const message of query({ prompt: "Summarize this project" })) {

67 if (message.type === "result") {68 if (message.type === "result") {

68 console.log(`Total cost: $${message.total_cost_usd}`);69 console.log(`Total cost: $${message.total_cost_usd}`);

69 }70 }

70 }71 }

72 } catch (error) {

73 // A single-shot query() throws after yielding an error result. If the

74 // failure was an error result, it still carried total_cost_usd and the

75 // branch above has already run; connection or process failures yield

76 // no result message.

77 console.error(`Session ended with an error: ${error}`);

78 }

71 ```79 ```

72 80

73 ```python Python theme={null}81 ```python Python theme={null}

76 84

77 85

78 async def main():86 async def main():

87 try:

79 async for message in query(prompt="Summarize this project"):88 async for message in query(prompt="Summarize this project"):

80 if isinstance(message, ResultMessage):89 if isinstance(message, ResultMessage):

81 print(f"Total cost: ${message.total_cost_usd or 0}")90 print(f"Total cost: ${message.total_cost_usd or 0}")

91 except Exception as error:

92 # A single-shot query() raises after yielding an error result. If the

93 # failure was an error result, it still carried total_cost_usd and the

94 # branch above has already run; connection or process failures yield

95 # no result message.

96 print(f"Session ended with an error: {error}")

82 97

83 98

84 asyncio.run(main())99 asyncio.run(main())

110let totalInputTokens = 0;125let totalInputTokens = 0;

111let totalOutputTokens = 0;126let totalOutputTokens = 0;

112 127

113for await (const message of query({ prompt: "Summarize this project" })) {128try {

129 for await (const message of query({ prompt: "Summarize this project" })) {

114 if (message.type === "assistant") {130 if (message.type === "assistant") {

115 const msgId = message.message.id;131 const msgId = message.message.id;

116 132

121 totalOutputTokens += message.message.usage.output_tokens;137 totalOutputTokens += message.message.usage.output_tokens;

122 }138 }

123 }139 }

140 }

141} catch (error) {

142 // A single-shot query() throws after yielding an error result, so the

143 // totals below still reflect the steps that ran before the failure.

144 console.error(`Session ended with an error: ${error}`);

124}145}

125 146

126console.log(`Steps: ${seenIds.size}`);147console.log(`Steps: ${seenIds.size}`);

139```typescript theme={null}160```typescript theme={null}

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

141 162

142for await (const message of query({ prompt: "Summarize this project" })) {163try {

164 for await (const message of query({ prompt: "Summarize this project" })) {

143 if (message.type !== "result") continue;165 if (message.type !== "result") continue;

144 166

145 for (const [modelName, usage] of Object.entries(message.modelUsage)) {167 for (const [modelName, usage] of Object.entries(message.modelUsage)) {

149 console.log(` Cache read: ${usage.cacheReadInputTokens}`);171 console.log(` Cache read: ${usage.cacheReadInputTokens}`);

150 console.log(` Cache creation: ${usage.cacheCreationInputTokens}`);172 console.log(` Cache creation: ${usage.cacheCreationInputTokens}`);

151 }173 }

174 }

175} catch (error) {

176 // A single-shot query() throws after yielding an error result. If the

177 // failure was an error result, the per-model breakdown above has already

178 // printed; connection or process failures yield no result message.

179 console.error(`Session ended with an error: ${error}`);

152}180}

153```181```

154 182

173 ];201 ];

174 202

175 for (const prompt of prompts) {203 for (const prompt of prompts) {

204 try {

176 for await (const message of query({ prompt })) {205 for await (const message of query({ prompt })) {

177 if (message.type === "result") {206 if (message.type === "result") {

178 totalSpend += message.total_cost_usd;207 totalSpend += message.total_cost_usd;

179 console.log(`This call: $${message.total_cost_usd}`);208 console.log(`This call: $${message.total_cost_usd}`);

180 }209 }

181 }210 }

211 } catch (error) {

212 // A single-shot query() throws after yielding an error result. If the

213 // failure was an error result, this call's cost was already counted;

214 // connection or process failures yield no result message. Continue

215 // with the next prompt.

216 console.error(`Call failed: ${error}`);

217 }

182 }218 }

183 219

184 console.log(`Total spend: $${totalSpend.toFixed(4)}`);220 console.log(`Total spend: $${totalSpend.toFixed(4)}`);

199 ]235 ]

200 236

201 for prompt in prompts:237 for prompt in prompts:

238 try:

202 async for message in query(prompt=prompt):239 async for message in query(prompt=prompt):

203 if isinstance(message, ResultMessage):240 if isinstance(message, ResultMessage):

204 cost = message.total_cost_usd or 0241 cost = message.total_cost_usd or 0

205 total_spend += cost242 total_spend += cost

206 print(f"This call: ${cost}")243 print(f"This call: ${cost}")

244 except Exception as error:

245 # A single-shot query() raises after yielding an error result. If

246 # the failure was an error result, this call's cost was already

247 # counted; connection or process failures yield no result message.

248 # Continue with the next prompt.

249 print(f"Call failed: {error}")

207 250

208 print(f"Total spend: ${total_spend:.4f}")251 print(f"Total spend: ${total_spend:.4f}")

209 252

agent-sdk/file-checkpointing.md +25 −7

Details

50 50

51若要使用檔案 checkpointing，請在您的選項中啟用它，從回應串流中捕捉 checkpoint UUID，然後在需要還原時呼叫 `rewindFiles()`（TypeScript）或 `rewind_files()`（Python）。51若要使用檔案 checkpointing，請在您的選項中啟用它，從回應串流中捕捉 checkpoint UUID，然後在需要還原時呼叫 `rewindFiles()`（TypeScript）或 `rewind_files()`（Python）。

52 52

53以下範例顯示完整流程：啟用 checkpointing、從回應串流中捕捉 checkpoint UUID 和工作階段 ID，然後稍後恢復工作階段以回溯檔案。下面詳細說明每個步驟。53以下範例顯示完整流程：啟用 checkpointing、從回應串流中捕捉 checkpoint UUID 和工作階段 ID，然後稍後恢復工作階段以回溯檔案。下面詳細說明每個步驟。本節中的範例使用提示「重構驗證模組」。在包含驗證模組的專案中執行它們，或變更提示以命名您專案中存在的檔案，以便您可以觀看檔案變更並查看回溯如何還原它們。

54 54

55<CodeGroup>55<CodeGroup>

56 ```python Python theme={null}56 ```python Python theme={null}

197 session_id = None197 session_id = None

198 198

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

200 # Update checkpoint on each user message (keeps the latest)200 # Capture the first user message UUID as the checkpoint

201 if isinstance(message, UserMessage) and message.uuid:201 if isinstance(message, UserMessage) and message.uuid and checkpoint_id is None:

202 checkpoint_id = message.uuid202 checkpoint_id = message.uuid

203 # Capture session ID from the result message203 # Capture session ID from the result message

204 if isinstance(message, ResultMessage):204 if isinstance(message, ResultMessage):

210 let sessionId: string | undefined;210 let sessionId: string | undefined;

211 211

212 for await (const message of response) {212 for await (const message of response) {

213 // Update checkpoint on each user message (keeps the latest)213 // Capture the first user message UUID as the checkpoint

214 if (message.type === "user" && message.uuid) {214 if (message.type === "user" && message.uuid && !checkpointId) {

215 checkpointId = message.uuid;215 checkpointId = message.uuid;

216 }216 }

217 // Capture session ID from any message that has it217 // Capture session ID from any message that has it

250 ```250 ```

251 </CodeGroup>251 </CodeGroup>

252 252

253 如果您捕捉了工作階段 ID 和 checkpoint ID，您也可以從 CLI 回溯：253 如果您捕捉了工作階段 ID 和 checkpoint ID，您也可以從 CLI 回溯。此命令需要 `claude` 可執行檔，該檔案來自[安裝 Claude Code](/zh-TW/setup)，並且不是由 SDK 套件安裝的。SDK 為您啟用 checkpointing，但當您直接執行 `claude -p` 時，您必須設定 `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING` 環境變數：

254 254

255 ```bash theme={null}255 ```bash theme={null}

256 claude -p --resume <session-id> --rewind-files <checkpoint-uuid>256 CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>

257 ```257 ```

258

259 `--rewind-files` 旗標不會出現在 `claude --help` 輸出中，但 CLI 會如上所示接受它。

258 </Step>260 </Step>

259</Steps>261</Steps>

260 262

270 272

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

272 274

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

276

273<CodeGroup>277<CodeGroup>

274 ```python Python theme={null}278 ```python Python theme={null}

275 import asyncio279 import asyncio

752 756

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

754 758

759<h3 id="file-rewinding-is-not-enabled-error">

760 "File rewinding is not enabled" 錯誤

761</h3>

762

763當您嘗試在未啟用 checkpointing 的情況下執行非互動式回溯時，會發生此錯誤：執行裸露的 `claude -p` 搭配 `--rewind-files`，或執行 SDK 工作階段（包括已恢復的工作階段），其選項未啟用 checkpointing。SDK 僅在執行回溯的工作階段上啟用 `enable_file_checkpointing`（Python）或 `enableFileCheckpointing`（TypeScript）時，才會在內部設定 `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING` 環境變數；裸露 CLI 永遠不會設定它。

764

765**解決方案**：對於裸露 CLI，在執行命令時設定環境變數：

766

767```bash theme={null}

768CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>

769```

770

771對於 SDK，在已恢復的工作階段上設定 `enable_file_checkpointing=True`（Python）或 `enableFileCheckpointing: true`（TypeScript），如本頁面的範例所示。

772

755<h3 id="processtransport-is-not-ready-for-writing-error">773<h3 id="processtransport-is-not-ready-for-writing-error">

756 "ProcessTransport is not ready for writing" 錯誤774 "ProcessTransport is not ready for writing" 錯誤

757</h3>775</h3>

agent-sdk/permissions.md +13 −2

Details

28 </Step>28 </Step>

29 29

30 <Step title="詢問規則">30 <Step title="詢問規則">

31 檢查來自 [settings.json](/zh-TW/settings#permission-settings) 的 `ask` 規則。如果詢問規則符合，呼叫會傳遞到您的 [`canUseTool` 回呼](/zh-TW/agent-sdk/user-input) 以進行確認，即使在 `bypassPermissions` 模式下也是如此。在 `dontAsk` 模式下，符合的詢問規則會被拒絕，因為該模式永遠不會提示。31 檢查來自 [settings.json](/zh-TW/settings#permission-settings) 的 `ask` 規則。如果詢問規則符合，呼叫會傳遞到您的 [`canUseTool` 回呼](/zh-TW/agent-sdk/user-input) 以進行確認，即使在 `bypassPermissions` 模式下也是如此。

33 需要使用者互動的工具行為相同：`AskUserQuestion` 和 MCP 工具（其伺服器設定 [`_meta["anthropic/requiresUserInteraction"]`](/zh-TW/mcp#require-approval-for-a-specific-tool)）總是會傳遞到回呼，即使允許規則符合時也是如此。在 `dontAsk` 模式下，兩種情況都會被拒絕，因為該模式永遠不會提示。{/* min-version: 2.1.199 */}MCP 註解需要 Claude Code v2.1.199 或更新版本。

32 </Step>34 </Step>

33 35

34 <Step title="權限模式">36 <Step title="權限模式">

46 48

47<img src="https://mintcdn.com/claude-code/jYgs7qigNjO1Badj/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=jYgs7qigNjO1Badj&q=85&s=c771ad9085b1277d3708027a49c744bc" alt="六步驟權限評估流程圖，與上述步驟相符：工具請求通過 hooks、拒絕規則、詢問規則、權限模式、允許規則和 canUseTool。Hooks、拒絕規則和 canUseTool 可以路由到'已阻止'；權限模式繞過、允許規則和 canUseTool 可以路由到'執行'；詢問規則路由到 canUseTool。" width="1180" height="260" data-path="images/agent-sdk/permissions-flow.svg" />49<img src="https://mintcdn.com/claude-code/jYgs7qigNjO1Badj/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=jYgs7qigNjO1Badj&q=85&s=c771ad9085b1277d3708027a49c744bc" alt="六步驟權限評估流程圖，與上述步驟相符：工具請求通過 hooks、拒絕規則、詢問規則、權限模式、允許規則和 canUseTool。Hooks、拒絕規則和 canUseTool 可以路由到'已阻止'；權限模式繞過、允許規則和 canUseTool 可以路由到'執行'；詢問規則路由到 canUseTool。" width="1180" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

48 50

51自 v2.1.198 起，如果您傳遞一個 `canUseTool` 回呼，而此評估順序永遠無法到達，TypeScript SDK 會在建構查詢時發出一次 Node.js 程序警告。警告的代碼是 `CLAUDE_SDK_CAN_USE_TOOL_SHADOWED`。兩種配置會觸發它：

53* `permissionMode: 'bypassPermissions'`，它會自動批准到達權限模式步驟的每個呼叫

54* 每個裸 `allowedTools` 項目，例如 `"Read"`，它會在諮詢回呼之前自動批准整個工具

56具有指定符的項目（例如 `Bash(ls *)`）和 `acceptEdits` 模式不會觸發它，來自設定檔的允許規則對檢查不可見。

58使用 `process.on('warning', ...)` 進行監聽，並匹配代碼以記錄或抑制它。若要無論模式和規則如何都控制每個工具呼叫，請改用 [`PreToolUse` hook](/zh-TW/agent-sdk/hooks)。

49本頁重點關注 **允許和拒絕規則** 以及 **權限模式**。對於其他步驟：60本頁重點關注 **允許和拒絕規則** 以及 **權限模式**。對於其他步驟：

50 61

51* **Hooks：** 執行自訂程式碼以允許、拒絕或修改工具請求。請參閱 [使用 hooks 控制執行](/zh-TW/agent-sdk/hooks)。62* **Hooks：** 執行自訂程式碼以允許、拒絕或修改工具請求。請參閱 [使用 hooks 控制執行](/zh-TW/agent-sdk/hooks)。

67允許規則只在字面 `mcp__<server>__` 前綴之後接受工具名稱萬用字元。伺服器段必須不含萬用字元，以便規則命名您設定的特定伺服器：`mcp__puppeteer__*` 符合來自 `puppeteer` 伺服器的每個工具，`mcp__github__get_*` 符合其 `get_` 工具。未錨定的條目（如 `allowed_tools=["*"]` 或 `allowed_tools=["mcp__*"]`）會被忽略並顯示啟動警告，不會自動批准任何內容。78允許規則只在字面 `mcp__<server>__` 前綴之後接受工具名稱萬用字元。伺服器段必須不含萬用字元，以便規則命名您設定的特定伺服器：`mcp__puppeteer__*` 符合來自 `puppeteer` 伺服器的每個工具，`mcp__github__get_*` 符合其 `get_` 工具。未錨定的條目（如 `allowed_tools=["*"]` 或 `allowed_tools=["mcp__*"]`）會被忽略並顯示啟動警告，不會自動批准任何內容。

68 79

69<Warning>80<Warning>

70 **自動批准的工具永遠不會到達 `canUseTool`。** 在任何較早步驟中批准的工具呼叫，由 `acceptEdits` 或 `bypassPermissions` 或允許規則批准，會跳過您的 `canUseTool` 回呼，因此您在那裡放置的權限檢查會被該工具無聲地略過。涵蓋範圍取決於條目的形式：像 `Read` 或 `mcp__github__get_issue` 這樣的裸名稱會自動批准對該工具的每個呼叫，而像 `Bash(ls *)` 這樣的限定規則只會自動批准符合的呼叫，其他 `Bash` 呼叫仍會通過回呼。對於必須在每個工具呼叫上執行的檢查，請使用 [`PreToolUse` hook](/zh-TW/agent-sdk/hooks)：hook 在每個其他步驟之前執行，hook 拒絕甚至在 `bypassPermissions` 模式中也適用。81 **自動批准的工具永遠不會到達 `canUseTool`。** 在任何較早步驟中批准的工具呼叫，由 `acceptEdits` 或 `bypassPermissions` 或允許規則批准，會跳過您的 `canUseTool` 回呼，因此您在那裡放置的權限檢查會被該工具無聲地略過。例外是需要使用者互動的工具，`AskUserQuestion` 和 MCP 工具標記為 [`_meta["anthropic/requiresUserInteraction"]`](/zh-TW/mcp#require-approval-for-a-specific-tool)，即使允許規則符合時也會到達回呼。涵蓋範圍取決於條目的形式：像 `Read` 或 `mcp__github__get_issue` 這樣的裸名稱會自動批准對該工具的每個呼叫，而像 `Bash(ls *)` 這樣的限定規則只會自動批准符合的呼叫，其他 `Bash` 呼叫仍會通過回呼。對於必須在每個工具呼叫上執行的檢查，請使用 [`PreToolUse` hook](/zh-TW/agent-sdk/hooks)：hook 在每個其他步驟之前執行，hook 拒絕甚至在 `bypassPermissions` 模式中也適用。

71</Warning>82</Warning>

72 83

73對於鎖定的代理程式，將 `allowedTools` 與 `permissionMode: "dontAsk"` 配對。列出的工具會被批准；其他任何工具都會被直接拒絕，而不是提示：84對於鎖定的代理程式，將 `allowedTools` 與 `permissionMode: "dontAsk"` 配對。列出的工具會被批准；其他任何工具都會被直接拒絕，而不是提示：

agent-sdk/python.md +1 −1

Details

958```958```

959 959

960* `API_TIMEOUT_MS`：Anthropic 客戶端上的每個請求逾時，以毫秒為單位。預設 `600000`。適用於主迴圈和所有子代理。960* `API_TIMEOUT_MS`：Anthropic 客戶端上的每個請求逾時，以毫秒為單位。預設 `600000`。適用於主迴圈和所有子代理。

961* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重試次數。預設 `10`，上限為 `15`。每次重試都有自己的 `API_TIMEOUT_MS` 視窗，因此最壞情況下的牆時間大約是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。對於需要等待更長中斷的無人值守執行，設定 `CLAUDE_CODE_RETRY_WATCHDOG=1` 以無限期重試容量錯誤。961* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重試次數。預設 `10`，上限為 `15`。每次重試都有自己的 `API_TIMEOUT_MS` 視窗，因此最壞情況下的牆時間大約是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。對於需要等待更長中斷的無人值守執行，設定 `CLAUDE_CODE_RETRY_WATCHDOG=1`：它無限期重試容量錯誤，{/* min-version: 2.1.199 */}自 Claude Code v2.1.199 起，會將其他暫時性錯誤的預設值提高到 `300` 並移除此變數的上限。

962* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：使用 `run_in_background` 啟動的子代理的停滯監視程式。預設 `600000`。在每個串流事件上重置；停滯時中止子代理，將任務標記為失敗，並將錯誤呈現給父代理，包含任何部分結果。不適用於同步子代理。962* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：使用 `run_in_background` 啟動的子代理的停滯監視程式。預設 `600000`。在每個串流事件上重置；停滯時中止子代理，將任務標記為失敗，並將錯誤呈現給父代理，包含任何部分結果。不適用於同步子代理。

963* `CLAUDE_ENABLE_STREAM_WATCHDOG` 搭配 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：當標頭已到達但回應本體停止串流時中止請求。監視程式預設在所有提供者上啟用；設定 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以停用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 預設為 `300000` 並限制在該最小值。中止的請求會經過正常重試路徑。963* `CLAUDE_ENABLE_STREAM_WATCHDOG` 搭配 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：當標頭已到達但回應本體停止串流時中止請求。監視程式預設在所有提供者上啟用；設定 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以停用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 預設為 `300000` 並限制在該最小值。中止的請求會經過正常重試路徑。

964 964

agent-sdk/subagents.md +35 −19

Details

17 17

18您可以通過三種方式建立子代理：18您可以通過三種方式建立子代理：

19 19

~~20* **以程式方式**：在您的 `query()` 選項中使用 `agents` 參數（[TypeScript](/zh-TW/agent-sdk/typescript#agentdefinition)、[Python](/zh-TW/agent-sdk/python#agentdefinition)）~~20* **以程式方式**：在您的 `query()` 選項中使用 `agents` 參數。請參閱 [TypeScript](/zh-TW/agent-sdk/typescript#agentdefinition) 和 [Python](/zh-TW/agent-sdk/python#agentdefinition) 參考資料

~~21* **基於檔案系統**：在 `.claude/agents/` 目錄中將代理定義為 markdown 檔案（請參閱[將子代理定義為檔案](/zh-TW/sub-agents)）~~21* **基於檔案系統**：在 `.claude/agents/` 目錄中將代理定義為 markdown 檔案。請參閱[將子代理定義為檔案](/zh-TW/sub-agents)

22* **內置通用代理**：Claude 可以隨時通過 Agent 工具呼叫內置的 `general-purpose` 子代理，無需您定義任何內容22* **內置通用代理**：Claude 可以隨時通過 Agent 工具呼叫內置的 `general-purpose` 子代理，無需您定義任何內容

23 23

24本指南重點介紹程式化方法，這是 SDK 應用程式的推薦方法。24本指南重點介紹程式化方法，這是 SDK 應用程式的推薦方法。

25 25

26定義子代理時，Claude 根據每個子代理的 `description` 欄位確定是否呼叫它。編寫清晰的描述，說明何時應使用子代理，Claude 將自動委派適當的任務。您也可以在提示詞中按名稱明確請求子代理（例如，「使用代碼審查員代理來...」）。26定義子代理時，Claude 根據每個子代理的 `description` 欄位確定是否呼叫它。編寫清晰的描述，說明何時應使用子代理，Claude 將自動委派適當的任務。您也可以在提示詞中按名稱明確請求子代理，例如「使用代碼審查員代理來...」。

27 27

28<h2 id="benefits-of-using-subagents">28<h2 id="benefits-of-using-subagents">

29 使用子代理的好處29 使用子代理的好處

61 61

62**示例：** `doc-reviewer` 子代理可能只能訪問 Read 和 Grep 工具，確保它可以分析但永遠不會意外修改您的文檔檔案。62**示例：** `doc-reviewer` 子代理可能只能訪問 Read 和 Grep 工具，確保它可以分析但永遠不會意外修改您的文檔檔案。

63 63

~~64<h2 id="creating-subagents">~~64<h2 id="create-subagents">

65 創建子代理65 創建子代理

66</h2>66</h2>

67 67

69 程式化定義（推薦）69 程式化定義（推薦）

70</h3>70</h3>

71 71

72使用 `agents` 參數直接在代碼中定義子代理。此示例創建兩個子代理：一個具有唯讀訪問權限的代碼審查員和一個可以執行命令的測試運行器。Claude 通過 Agent 工具調用子代理，因此請在 `allowedTools` 中包含 `Agent` 以自動批准子代理調用，無需權限提示。72使用 `agents` 參數直接在代碼中定義子代理。Claude 通過 `Agent` 工具調用子代理，因此請在 `allowedTools` 中包含 `Agent` 以自動批准子代理調用，無需權限提示。

73 73

~~74本頁面上的大多數示例僅列印最終結果。若要確認 Claude 委派給子代理而不是直接回答，請參閱[檢測子代理調用](#detecting-subagent-invocation)。~~74本頁面上的大多數示例僅列印最終結果。若要確認 Claude 委派給子代理而不是直接回答，請參閱[檢測子代理調用](#detect-subagent-invocation)。

76此示例創建兩個子代理：一個具有唯讀訪問權限的代碼審查員和一個可以執行命令的測試運行器。

75 77

76<CodeGroup>78<CodeGroup>

77 ```python Python theme={null}79 ```python Python theme={null}

197 199

198在 Python SDK 中，多字欄位名稱（例如 `disallowedTools` 和 `mcpServers`）保持其 camelCase 拼寫以匹配線路格式，而不是遵循 Python 的 snake\_case 慣例。有關詳細信息，請參閱 [`AgentDefinition` 參考](/zh-TW/agent-sdk/python#agentdefinition)。200在 Python SDK 中，多字欄位名稱（例如 `disallowedTools` 和 `mcpServers`）保持其 camelCase 拼寫以匹配線路格式，而不是遵循 Python 的 snake\_case 慣例。有關詳細信息，請參閱 [`AgentDefinition` 參考](/zh-TW/agent-sdk/python#agentdefinition)。

199 201

202Claude Code v2.1.198 中的兩個子代理行為已更改：

203

204* 子代理預設在背景中運行。省略 [`run_in_background`](/zh-TW/agent-sdk/typescript) 輸入的 Agent 工具調用會啟動背景子代理，當 Claude 需要結果才能繼續時，它會設定 `run_in_background: false`。在 v2.1.198 之前，省略 `run_in_background` 會同步運行子代理。設定 `background` 欄位為 `true` 以強制特定代理進行背景執行，無論 Claude 請求什麼。

205* 子代理繼承主會話的擴展思考配置。在較早的版本中，無論主會話的設定如何，擴展思考在子代理內被禁用。

206

200<Note>207<Note>

201 {/* min-version: 2.1.172 */}自 Claude Code v2.1.172 起，子代理可以生成自己的子代理。位於主代理下方五個級別的子代理無法生成進一步的子代理，無論其是否在前景或背景中運行。若要防止子代理生成其他子代理，請從其 `tools` 陣列中省略 `Agent` 或將其添加到 `disallowedTools`。有關完整的深度規則，請參閱[嵌套子代理](/zh-TW/sub-agents#spawn-nested-subagents)。208 {/* min-version: 2.1.172 */}自 Claude Code v2.1.172 起，子代理可以生成自己的子代理。位於主代理下方五個級別的子代理無法生成進一步的子代理，無論其是否在前景或背景中運行。若要防止子代理生成其他子代理，請從其 `tools` 陣列中省略 `Agent` 或將其添加到 `disallowedTools`。有關完整的深度規則，請參閱[嵌套子代理](/zh-TW/sub-agents#spawn-nested-subagents)。

202</Note>209</Note>

225 232

226<Note>233<Note>

227 父代理逐字接收子代理的最終消息作為 Agent 工具結果，但可能在其自己的回應中進行摘要。要在面向用戶的回應中逐字保留子代理輸出，請在您傳遞給**主** `query()` 調用的提示詞或 `systemPrompt` 選項中包含執行此操作的指令。234 父代理逐字接收子代理的最終消息作為 Agent 工具結果，但可能在其自己的回應中進行摘要。要在面向用戶的回應中逐字保留子代理輸出，請在您傳遞給主 `query()` 調用的提示詞或 `systemPrompt` 選項中包含執行此操作的指令。

228</Note>235</Note>

229 236

230<h2 id="invoking-subagents">237{/* min-version: 2.1.199 */}自 Claude Code v2.1.199 起，結束子代理早期的 API 錯誤（例如速率限制）永遠不會作為其結果傳遞。如果子代理已經產生輸出，Agent 工具會返回該部分輸出並附註子代理未完成；否則工具結果是一條錯誤消息 `Agent terminated early due to an API error`，後跟錯誤詳情。請參閱[子代理中的 API 錯誤](/zh-TW/sub-agents#api-errors-in-subagents)以了解前景和背景行為。

238

239<h2 id="invoke-subagents">

231 調用子代理240 調用子代理

232</h2>241</h2>

233 242

329 ```338 ```

330</CodeGroup>339</CodeGroup>

331 340

332<h2 id="detecting-subagent-invocation">341<h2 id="detect-subagent-invocation">

333 檢測子代理調用342 檢測子代理調用

334</h2>343</h2>

335 344

336子代理通過 Agent 工具調用。要檢測何時調用子代理，請檢查 `tool_use` 塊，其中 `name` 是 `"Agent"`。來自子代理上下文內的訊息包括 `parent_tool_use_id` 欄位。345Claude 通過 Agent 工具調用子代理。要檢測何時調用子代理，請檢查 `tool_use` 塊，其中 `name` 是 `"Agent"`。來自子代理上下文內的訊息包括 `parent_tool_use_id` 欄位。

337 346

338<Note>347<Note>

339 工具名稱在 Claude Code v2.1.63 中從 `"Task"` 重新命名為 `"Agent"`。目前 SDK 版本在 `tool_use` 塊中發出 `"Agent"`，但在 `system:init` 工具清單和 `result.permission_denials[].tool_name` 中仍使用 `"Task"`。檢查 `block.name` 中的兩個值可確保跨 SDK 版本的相容性。348 工具名稱在 Claude Code v2.1.63 中從 `"Task"` 重新命名為 `"Agent"`。目前 SDK 版本在 `tool_use` 塊中發出 `"Agent"`，但在 `system:init` 工具清單和 `result.permission_denials[].tool_name` 中仍使用 `"Task"`。檢查 `block.name` 中的兩個值可確保跨 SDK 版本的相容性。

422 ```431 ```

423</CodeGroup>432</CodeGroup>

424 433

425<h2 id="resuming-subagents">434<h2 id="resume-subagents">

426 恢復子代理435 恢復子代理

427</h2>436</h2>

428 437

429子代理可以恢復以繼續中斷的地方。恢復的子代理保留其完整的對話歷史，包括所有先前的工具調用、結果和推理。子代理從停止的地方繼續，而不是從頭開始。438您可以恢復子代理以繼續中斷的地方，而不是從頭開始。恢復的子代理保留其完整的對話歷史，包括所有先前的工具調用、結果和推理。

430 439

431當子代理完成時，Agent 工具結果包含一個文字區塊，其中包含 `agentId: <id>`。內置的 [`Explore` 和 `Plan` 代理](/zh-TW/sub-agents#built-in-subagents) 是一次性的，不會返回 `agentId`，因此當您需要恢復時，請使用自訂代理或 `general-purpose`。要以程式方式恢復子代理：440當子代理完成時，Agent 工具結果包含一個文字區塊，其中包含 `agentId: <id>`。內置的 [`Explore` 和 `Plan` 代理](/zh-TW/sub-agents#built-in-subagents) 是一次性的，不會返回 `agentId`，因此當您需要恢復時，請使用自訂代理或 `general-purpose`。要以程式方式恢復子代理：

432 441

568 577

569* **主對話壓縮**：當主對話壓縮時，子代理記錄不受影響。它們存儲在單獨的檔案中。578* **主對話壓縮**：當主對話壓縮時，子代理記錄不受影響。它們存儲在單獨的檔案中。

570* **會話持久性**：子代理記錄在其會話內持續存在。您可以通過恢復相同會話在重新啟動 Claude Code 後恢復子代理。579* **會話持久性**：子代理記錄在其會話內持續存在。您可以通過恢復相同會話在重新啟動 Claude Code 後恢復子代理。

571* **自動清理**：記錄根據 `cleanupPeriodDays` 設定進行清理（預設：30 天）。580* **自動清理**：記錄根據 `cleanupPeriodDays` 設定進行清理，預設為 30 天。

572 581

573<h2 id="tool-restrictions-1">582<h2 id="tool-restrictions-1">

574 工具限制583 工具限制

662 671

663如果 Claude 直接完成任務而不是委派給您的子代理：672如果 Claude 直接完成任務而不是委派給您的子代理：

664 673

6651. **檢查 Agent 調用已獲批准**：在 `allowedTools` 中包含 `Agent` 以自動批准子代理調用。沒有它，Agent 調用會轉到您的 `canUseTool` 回調，或在 `dontAsk` 模式下被拒絕674* **檢查 Agent 調用已獲批准**：在 `allowedTools` 中包含 `Agent` 以自動批准子代理調用。沒有它，Agent 調用會轉到您的 `canUseTool` 回調，或在 `dontAsk` 模式下被拒絕

6662. **使用明確提示**：在您的提示詞中按名稱提及子代理（例如，「使用代碼審查員代理來...」）675* **使用明確提示**：在您的提示詞中按名稱提及子代理，例如「使用代碼審查員代理來...」

6673. **編寫清晰的描述**：準確解釋何時應使用子代理，以便 Claude 可以適當地匹配任務676* **編寫清晰的描述**：準確解釋何時應使用子代理，以便 Claude 可以適當地匹配任務

668 677

669<h3 id="filesystem-based-agents-not-loading">678<h3 id="filesystem-based-agents-not-loading">

670 基於檔案系統的代理未加載679 基於檔案系統的代理未加載

671</h3>680</h3>

672 681

673在 `.claude/agents/` 中定義的代理僅在啟動時加載。如果在 Claude Code 運行時創建新的代理檔案，請重新啟動會話以加載它。682Claude Code 監視 `~/.claude/agents/` 和 `.claude/agents/`，並在幾秒內拾取新的或編輯的代理檔案，無需重新啟動。如果定義從未出現，請檢查這些原因：

683

684* **新的 `agents` 目錄**：監視程式僅涵蓋會話啟動時存在的目錄，因此新目錄中的第一個檔案需要會話重新啟動。這是最常見的原因。

685* **無效的 frontmatter 或重複的 `name`**：檢查檔案的 YAML，以及現有代理是否已使用該 `name`。

686* **`--disable-slash-commands`**：使用此旗標啟動的會話不監視這些目錄，並且始終需要重新啟動以加載新檔案。

687* **具有相同名稱的程式化代理**：傳遞給 `query()` 的 `agents` 會覆蓋具有相同名稱的檔案系統代理。

688

689有關檔案格式，請參閱[如何編寫子代理檔案](/zh-TW/sub-agents#write-subagent-files)。

674 690

675<h3 id="windows-long-prompt-failures">691<h3 id="long-prompt-failures-on-windows">

676 Windows：長提示詞失敗692 Windows 上的長提示詞失敗

677</h3>693</h3>

678 694

679在 Windows 上，具有非常長提示詞的子代理可能因命令行長度限制（8191 個字符）而失敗。保持提示詞簡潔或使用基於檔案系統的代理來處理複雜指令。695在 Windows 上，具有非常長提示詞的子代理可能因命令行長度限制（8191 個字符）而失敗。保持提示詞簡潔或使用基於檔案系統的代理來處理複雜指令。

agent-sdk/todo-tracking.md +68 −6

Details

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

10 10

11<Note>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`。12 自 TypeScript Agent SDK 0.3.142 和 Claude Code v2.1.142 起，會話使用結構化的 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 和 `TaskList`，而不是 `TodoWrite`。Python SDK 從它啟動的 Claude Code CLI 獲得此變更，而不是從 Python 套件版本：一旦該 CLI（pip 套件內捆綁的副本，或您使用 `cli_path` 指向的副本）為 v2.1.142 或更新版本，此切換就會適用。請參閱[遷移到 Task 工具](#migrate-to-task-tools)以了解監控代碼如何變更。此頁面上的範例設置 `CLAUDE_CODE_ENABLE_TASKS=0` 以繼續為尚未遷移的會話顯示 `TodoWrite`。

13</Note>13</Note>

14 14

15<h3 id="todo-lifecycle">15<h3 id="todo-lifecycle">

27 何時使用待辦事項27 何時使用待辦事項

28</h3>28</h3>

29 29

~~30SDK 會自動為以下情況建立待辦事項：~~30SDK 會為大多數多步驟工作建立待辦事項，例如：

31 31

32* **複雜的多步驟任務**需要 3 個或更多不同的操作32* **複雜的多步驟任務**需要 3 個或更多不同的操作

33* **用戶提供的任務清單**當提及多個項目時33* **用戶提供的任務清單**當提及多個項目時

34* **非平凡的操作**受益於進度追蹤34* **非平凡的操作**受益於進度追蹤

35* **明確的請求**當用戶要求待辦事項組織時35* **明確的請求**當用戶要求待辦事項組織時

36 36

37它可能會跳過非常短或單步驟請求的待辦事項。

37<h2 id="examples">39<h2 id="examples">

38 範例40 範例

39</h2>41</h2>

40 42

43在執行這些範例之前，請按照[快速入門](/zh-TW/agent-sdk/quickstart)安裝 Claude Agent SDK。

45每個範例會執行到代理程式完成並產生其最終結果訊息為止。如果工作階段先達到其輪次限制，該結果訊息會有 `error_max_turns` 子類型。檢查 `subtype` 以偵測該結束。

47這些範例使用單次 `query()` 呼叫。在產生 `error_max_turns` 結果後，`query()` 會拋出包含 `Reached maximum number of turns` 的錯誤。每個範例都將其迴圈包裝在 try 區塊中，以便在發生這種情況時乾淨地退出。

49請參閱[處理結果](/zh-TW/agent-sdk/agent-loop#handle-the-result)以了解結果子類型。

41<h3 id="monitoring-todo-changes">51<h3 id="monitoring-todo-changes">

42 監控待辦事項變更52 監控待辦事項變更

43</h3>53</h3>

46 ```typescript TypeScript theme={null}56 ```typescript TypeScript theme={null}

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

48 58

59 try {

49 for await (const message of query({60 for await (const message of query({

50 prompt: "Optimize my React app performance and track progress with todos",61 prompt: "Optimize my React app performance and track progress with todos",

51 // Re-enable TodoWrite, which this example monitors. Without it, the SDK uses62 // Re-enable TodoWrite, which this example monitors. Without it, the SDK uses

68 }79 }

69 }80 }

70 }81 }

82 } catch (error) {

83 // A single-shot query() throws after yielding an error result,

84 // such as when the maxTurns limit is hit.

85 console.log(`Session ended with an error: ${error}`);

86 }

71 ```87 ```

72 88

73 ```python Python theme={null}89 ```python Python theme={null}

90 import asyncio

74 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock92 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

75 93

95 async def main():

96 try:

76 async for message in query(97 async for message in query(

77 prompt="Optimize my React app performance and track progress with todos",98 prompt="Optimize my React app performance and track progress with todos",

78 # Re-enable TodoWrite, which this example monitors. Without it, the SDK uses99 # Re-enable TodoWrite, which this example monitors. Without it, the SDK uses

95 else "❌"116 else "❌"

96 )117 )

97 print(f"{i + 1}. {status} {todo['content']}")118 print(f"{i + 1}. {status} {todo['content']}")

119 except Exception as error:

120 # A single-shot query() raises after yielding an error result,

121 # such as when the max_turns limit is hit.

122 print(f"Session ended with an error: {error}")

123

124

125 asyncio.run(main())

98 ```126 ```

99</CodeGroup>127</CodeGroup>

100 128

128 }156 }

129 157

130 async trackQuery(prompt: string) {158 async trackQuery(prompt: string) {

159 try {

131 for await (const message of query({160 for await (const message of query({

132 prompt,161 prompt,

133 // Re-enable TodoWrite, which this tracker watches for.162 // Re-enable TodoWrite, which this tracker watches for.

142 }171 }

143 }172 }

144 }173 }

174 } catch (error) {

175 // A single-shot query() throws after yielding an error result,

176 // such as when the maxTurns limit is hit.

177 console.log(`Session ended with an error: ${error}`);

178 }

145 }179 }

146 }180 }

147 181

151 ```185 ```

152 186

153 ```python Python theme={null}187 ```python Python theme={null}

188 import asyncio

189

154 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock190 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

155 from typing import List, Dict191 from typing import List, Dict

156 192

186 print(f"{i + 1}. {icon} {text}")222 print(f"{i + 1}. {icon} {text}")

187 223

188 async def track_query(self, prompt: str):224 async def track_query(self, prompt: str):

225 try:

189 async for message in query(226 async for message in query(

190 prompt=prompt,227 prompt=prompt,

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

196 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":233 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

197 self.todos = block.input["todos"]234 self.todos = block.input["todos"]

198 self.display_progress()235 self.display_progress()

236 except Exception as error:

237 # A single-shot query() raises after yielding an error result,

238 # such as when the max_turns limit is hit.

239 print(f"Session ended with an error: {error}")

199 240

200 241

201 # Usage242 # Usage

243 async def main():

202 tracker = TodoTracker()244 tracker = TodoTracker()

203 await tracker.track_query("Build a complete authentication system with todos")245 await tracker.track_query("Build a complete authentication system with todos")

246

247

248 asyncio.run(main())

204 ```249 ```

205</CodeGroup>250</CodeGroup>

206 251

217| 項目形狀：`{ 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"` 以刪除 |262| 項目形狀：`{ 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"` 以刪除 |

219 264

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

221 266

222串流的 `tool_use` 輸入是模型發出的原始形狀。Claude Code 在執行前修復一些接近但不正確的鍵名，將 `id` 或 `task_id` 映射到 `taskId` 和 `active_form` 映射到 `activeForm`，但該修復不會反映在流中。防禦性地讀取 `TaskUpdate` 輸入欄位，如下面的範例所示，而不是假設規範名稱始終存在。267串流的 `tool_use` 輸入是模型發出的原始形狀。Claude Code 在執行前修復一些接近但不正確的鍵名，將 `id` 或 `task_id` 映射到 `taskId` 和 `active_form` 映射到 `activeForm`，但該修復不會反映在流中。防禦性地讀取 `TaskUpdate` 輸入欄位，如下面的範例所示，而不是假設規範名稱始終存在。

223 268

225 ```typescript TypeScript theme={null}270 ```typescript TypeScript theme={null}

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

227 272

273 try {

228 for await (const message of query({274 for await (const message of query({

229 prompt: "Optimize my React app performance",275 prompt: "Optimize my React app performance and track progress with todos",

276 options: { maxTurns: 15 },

230 })) {277 })) {

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

232 for (const block of message.message.content) {279 for (const block of message.message.content) {

246 }293 }

247 }294 }

248 }295 }

296 } catch (error) {

297 // A single-shot query() throws after yielding an error result.

298 console.log(`Session ended with an error: ${error}`);

299 }

249 ```300 ```

250 301

251 ```python Python theme={null}302 ```python Python theme={null}

252 from claude_agent_sdk import query, AssistantMessage, ToolUseBlock303 import asyncio

253 304

305 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

306

307 async def main():

308 try:

254 async for message in query(309 async for message in query(

255 prompt="Optimize my React app performance",310 prompt="Optimize my React app performance and track progress with todos",

311 options=ClaudeAgentOptions(max_turns=15),

256 ):312 ):

257 if not isinstance(message, AssistantMessage):313 if not isinstance(message, AssistantMessage):

258 continue314 continue

269 )325 )

270 if task_id:326 if task_id:

271 print(f" {task_id} -> {block.input['status']}")327 print(f" {task_id} -> {block.input['status']}")

328 except Exception as error:

329 # A single-shot query() raises after yielding an error result.

330 print(f"Session ended with an error: {error}")

331

332

333 asyncio.run(main())

272 ```334 ```

273</CodeGroup>335</CodeGroup>

274 336

agent-sdk/typescript.md +45 −33

Details

551```551```

552 552

553* `API_TIMEOUT_MS`：Anthropic 客戶端上的每個請求超時，以毫秒為單位。默認 `600000`。適用於主循環和所有子代理。553* `API_TIMEOUT_MS`：Anthropic 客戶端上的每個請求超時，以毫秒為單位。默認 `600000`。適用於主循環和所有子代理。

554* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重試次數。默認 `10`，上限為 `15`。每次重試都有自己的 `API_TIMEOUT_MS` 窗口，因此最壞情況下的牆時間大約是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。對於需要等待更長時間中斷的無人值守運行，設置 `CLAUDE_CODE_RETRY_WATCHDOG=1` 以無限期重試容量錯誤。554* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重試次數。默認 `10`，上限為 `15`。每次重試都有自己的 `API_TIMEOUT_MS` 窗口，因此最壞情況下的牆時間大約是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。對於需要等待更長時間中斷的無人值守運行，設置 `CLAUDE_CODE_RETRY_WATCHDOG=1`：它無限期重試容量錯誤，{/* min-version: 2.1.199 */}自 Claude Code v2.1.199 起，為其他瞬時錯誤提高默認值至 `300` 並移除此變量的上限。

555* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：使用 `run_in_background` 啟動的子代理的停滯監視程序。默認 `600000`。在每個流事件上重置；在停滯時中止子代理，將任務標記為失敗，並將錯誤與任何部分結果一起呈現給父代理。不適用於同步子代理。555* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：使用 `run_in_background` 啟動的子代理的停滯監視程序。默認 `600000`。在每個流事件上重置；在停滯時中止子代理，將任務標記為失敗，並將錯誤與任何部分結果一起呈現給父代理。不適用於同步子代理。

556* `CLAUDE_ENABLE_STREAM_WATCHDOG` 與 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：當標頭已到達但響應正文停止流式傳輸時中止請求。當 `CLAUDE_ENABLE_STREAM_WATCHDOG` 未設置時，默認值在直接 Anthropic API 上由服務器控制，在其他提供商上關閉。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默認為 `300000` 並被限制為該最小值。中止的請求通過正常重試路徑進行。556* `CLAUDE_ENABLE_STREAM_WATCHDOG` 與 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：當標頭已到達但響應正文停止流式傳輸時中止請求。當 `CLAUDE_ENABLE_STREAM_WATCHDOG` 未設置時，默認值在直接 Anthropic API 上由服務器控制，在其他提供商上關閉。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默認為 `300000` 並被限制為該最小值。中止的請求通過正常重試路徑進行。

557 557

901 decisionReason?: string;901 decisionReason?: string;

902 toolUseID: string;902 toolUseID: string;

903 agentID?: string;903 agentID?: string;

904 requestId: string;

904 }905 }

905) => Promise<PermissionResult>;906) => Promise<PermissionResult | null>;

906```907```

907 908

908| 選項 | 類型 | 描述 |909| 選項 | 類型 | 描述 |

917| `requestId` | `string` | `control_request` 信封的 `request_id`。您的應用程序在 SDK 外發送的 `control_response`（例如簽名的 HTTP POST）必須回顯此值，以便 Claude Code 進程可以將回复與請求匹配 |

918

919回調通常通過返回 [`PermissionResult`](#permissionresult) 來解決請求，SDK 將其寫回其傳輸作為 `control_response`。僅當您的應用程序已通過其自己的通道為此請求發送 `control_response`（回顯 `requestId`）時才返回 `null`；SDK 然後跳過將響應寫入其傳輸。在任何其他情況下返回 `null` 會使工具調用無限期被阻止，因為永遠不會發送 `control_response` 且權限提示不會超時。

920

921`requestId` 選項和 `null` 返回值需要 Claude Code v2.1.199 或更高版本。

916 922

917<h3 id="permissionresult">923<h3 id="permissionresult">

918 `PermissionResult`924 `PermissionResult`

2179};2185};

2180```2186```

2181 2187

2182按 ID 停止運行的後台任務或 shell。2188按 ID 停止運行的後台任務或 shell。{/* min-version: 2.1.198 */}自 v2.1.198 起，`task_id` 也接受代理團隊隊友或按代理 ID 或名稱的命名後台代理。

2183 2189

2184<h3 id="notebookedit">2190<h3 id="notebookedit">

2185 NotebookEdit2191 NotebookEdit

3774};3780};

3775```3781```

3776 3782

3777| 屬性 | 類型 | 默認值 | 描述 |3783| 屬性 | 類型 | 預設值 | 描述 |

3778| :-------------------------- | :---------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------- |3784| :-------------------------- | :---------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------ |

3786| `ignoreViolations` | `Record<string, string[]>` | `undefined` | 違規類別到要忽略的模式的映射（例如，`{ file: ['/tmp/*'], network: ['localhost'] }`） |3792| `ignoreViolations` | `Record<string, string[]>` | `undefined` | 違規類別到要忽略的模式的映射（例如，`{ file: ['/tmp/*'], network: ['localhost'] }`） |

3788| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | 沙箱環境中的自定義 ripgrep 二進制配置 |3794| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | 沙箱環境中的自訂 ripgrep 二進制配置 |

3789 3795

3790<Note>3796<Note>

3791 沙箱取決於平台支持，在 Linux 上，還需要 `bubblewrap` 和 `socat` 等工具。當 `enabled` 為 `true` 且沙箱無法啟動時，`query()` 會報告一條 `result` 消息，其中 `subtype: "error_during_execution"`，並在 `errors` 中包含原因，然後停止。應監視該子類型，而不是期望 `query()` 在產生消息之前拋出異常。3797 沙箱取決於平台支援，在 Linux 上，還需要 `bubblewrap` 和 `socat` 等工具。當 `enabled` 為 `true` 且沙箱無法啟動時，`query()` 會報告一條 `result` 訊息，其中 `subtype: "error_during_execution"`，並在 `errors` 中包含原因。對於單一訊息 `query()` 呼叫，SDK 會在產生該錯誤結果後拋出異常，因此請將迴圈包裝在 try 區塊中以繼續執行。請參閱[處理結果](/zh-TW/agent-sdk/agent-loop#handle-the-result)以了解錯誤合約。

3792 3798

3793 要改為運行無沙箱，請設置 `failIfUnavailable: false`。3799 要改為運行無沙箱，請設置 `failIfUnavailable: false`。

3794</Note>3800</Note>

3795 3801

3796<h4 id="example-usage">3802<h4 id="example-usage">

3797 示例用法3803 範例用法

3798</h4>3804</h4>

3799 3805

3800```typescript theme={null}3806```typescript theme={null}

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

3802 3808

3803for await (const message of query({3809try {

3810 for await (const message of query({

3804 prompt: "Build and test my project",3811 prompt: "Build and test my project",

3805 options: {3812 options: {

3806 sandbox: {3813 sandbox: {

3811 }3818 }

3812 }3819 }

3813 }3820 }

3814})) {3821 })) {

3815 if ("result" in message) console.log(message.result);3822 if ("result" in message) console.log(message.result);

3823 }

3824} catch (error) {

3825 // 單一 query() 呼叫會在產生錯誤結果後拋出異常，

3826 // 例如當沙箱無法啟動時（failIfUnavailable 預設為 true）。

3827 console.log(`Session ended with an error: ${error}`);

3816}3828}

3817```3829```

3818 3830

3824 `SandboxNetworkConfig`3836 `SandboxNetworkConfig`

3825</h3>3837</h3>

3826 3838

3827沙箱模式的網絡特定配置。這些設置適用於當父級 [`SandboxSettings`](#sandboxsettings) 中的 `enabled` 為 `true` 時的沙箱化 Bash 命令。它們不限制 WebFetch 工具，該工具改用 [權限規則](/zh-TW/permissions#webfetch)。3839沙箱模式的網絡特定配置。這些設置適用於當父級 [`SandboxSettings`](#sandboxsettings) 中的 `enabled` 為 `true` 時的沙箱化 Bash 命令。它們不限制 WebFetch 工具，該工具改用[權限規則](/zh-TW/permissions#webfetch)。

3828 3840

3829```typescript theme={null}3841```typescript theme={null}

3830type SandboxNetworkConfig = {3842type SandboxNetworkConfig = {

3839};3851};

3840```3852```

3841 3853

3842| 屬性 | 類型 | 默認值 | 描述 |3854| 屬性 | 類型 | 預設值 | 描述 |

3843| :------------------------ | :--------- | :---------- | :------------------------------------------------------------------------------------------------------------------------ |3855| :------------------------ | :--------- | :---------- | :----------------------------------------------------------------------------------------------------------------------- |

3852 3864

3853<Note>3865<Note>

3854 內置沙箱代理根據請求的主機名強制執行 `allowedDomains`，並且不終止或檢查 TLS 流量，因此 [域前置](https://en.wikipedia.org/wiki/Domain_fronting) 等技術可能會繞過它。有關詳細信息，請參閱 [沙箱安全限制](/zh-TW/sandboxing#security-limitations)，以及 [安全部署](/zh-TW/agent-sdk/secure-deployment#traffic-forwarding) 以配置 TLS 終止代理。3866 內置沙箱代理根據請求的主機名強制執行 `allowedDomains`，並且不終止或檢查 TLS 流量，因此[網域前置](https://en.wikipedia.org/wiki/Domain_fronting)等技術可能會繞過它。有關詳細資訊，請參閱[沙箱安全限制](/zh-TW/sandboxing#security-limitations)，以及[安全部署](/zh-TW/agent-sdk/secure-deployment#traffic-forwarding)以配置 TLS 終止代理。

3855</Note>3867</Note>

3856 3868

3857<h3 id="sandboxfilesystemconfig">3869<h3 id="sandboxfilesystemconfig">

3858 `SandboxFilesystemConfig`3870 `SandboxFilesystemConfig`

3859</h3>3871</h3>

3860 3872

3861沙箱模式的文件系統特定配置。3873沙箱模式的檔案系統特定配置。

3862 3874

3863```typescript theme={null}3875```typescript theme={null}

3864type SandboxFilesystemConfig = {3876type SandboxFilesystemConfig = {

3868};3880};

3869```3881```

3870 3882

3871| 屬性 | 類型 | 默認值 | 描述 |3883| 屬性 | 類型 | 預設值 | 描述 |

3872| :----------- | :--------- | :--- | :------------ |3884| :----------- | :--------- | :--- | :------------ |

3876 3888

3877<h3 id="permissions-fallback-for-unsandboxed-commands">3889<h3 id="permissions-fallback-for-unsandboxed-commands">

3878 無沙箱命令的權限回退3890 無沙箱命令的權限回退

3879</h3>3891</h3>

3880 3892

3881啟用 `allowUnsandboxedCommands` 時，模型可以通過在工具輸入中設置 `dangerouslyDisableSandbox: true` 來請求在沙箱外運行命令。這些請求回退到現有的權限系統，意味著您的 `canUseTool` 處理程序被調用，允許您實現自定義授權邏輯。3893啟用 `allowUnsandboxedCommands` 時，模型可以通過在工具輸入中設置 `dangerouslyDisableSandbox: true` 來請求在沙箱外運行命令。這些請求回退到現有的權限系統，意味著您的 `canUseTool` 處理程序被調用，允許您實現自訂授權邏輯。

3882 3894

3883<Note>3895<Note>

3884 **`excludedCommands` vs `allowUnsandboxedCommands`：**3896 **`excludedCommands` vs `allowUnsandboxedCommands`：**

3885 3897

3886 * `excludedCommands`：始終自動繞過沙箱的命令的靜態列表（例如，`['docker']`）。模型對此無控制。3898 * `excludedCommands`：始終自動繞過沙箱的命令的靜態列表（例如，`['docker']`）。模型對此無控制。

3887 * `allowUnsandboxedCommands`：讓模型在運行時通過在工具輸入中設置 `dangerouslyDisableSandbox: true` 來決定是否請求無沙箱執行。3899 * `allowUnsandboxedCommands`：讓模型在執行時通過在工具輸入中設置 `dangerouslyDisableSandbox: true` 來決定是否請求無沙箱執行。

3888</Note>3900</Note>

3889 3901

3890```typescript theme={null}3902```typescript theme={null}

3923此模式使您能夠：3935此模式使您能夠：

3924 3936

3925* **審計模型請求：** 記錄模型何時請求無沙箱執行3937* **審計模型請求：** 記錄模型何時請求無沙箱執行

3926* **實現允許列表：** 僅允許特定命令在沙箱外運行3938* **實現允許清單：** 僅允許特定命令在沙箱外運行

3927* **添加批准工作流：** 需要對特權操作進行明確授權3939* **新增批准工作流程：** 需要對特權操作進行明確授權

3928 3940

3929<Warning>3941<Warning>

3930 使用 `dangerouslyDisableSandbox: true` 運行的命令具有完整的系統訪問權限。確保您的 `canUseTool` 處理程序仔細驗證這些請求。3942 使用 `dangerouslyDisableSandbox: true` 運行的命令具有完整的系統訪問權限。確保您的 `canUseTool` 處理程序仔細驗證這些請求。

3931 3943

3932 如果 `permissionMode` 設置為 `bypassPermissions` 且 `allowUnsandboxedCommands` 啟用，模型可以自主執行沙箱外的命令，無需任何批准提示。此組合實際上允許模型無聲地逃離沙箱隔離。3944 如果 `permissionMode` 設置為 `bypassPermissions` 且 `allowUnsandboxedCommands` 啟用，模型可以自主執行沙箱外的命令，無需任何批准提示（明確的[`ask` 規則](/zh-TW/agent-sdk/permissions#how-permissions-are-evaluated)仍會強制執行一個）。此組合實際上允許模型無聲地逃離沙箱隔離。

3933</Warning>3945</Warning>

3934 3946

3935<h2 id="see-also">3947<h2 id="see-also">

agent-teams.md +12 −3

Details

89* **Enter**：開啟所選隊友的記錄並直接向其傳送訊息89* **Enter**：開啟所選隊友的記錄並直接向其傳送訊息

90* **Escape**：中斷所選隊友的目前回合90* **Escape**：中斷所選隊友的目前回合

91 91

~~92{/* min-version: 2.1.181 */}自 v2.1.181 起，閒置隊友的列在 30 秒後會隱藏，並在其下一個回合時重新出現。隊友在隱藏時仍保持執行狀態且可定址。~~92{/* min-version: 2.1.199 */}自 v2.1.199 起，當任何隊友或子 agent 仍在工作時，閒置隊友的列會保留在面板中，因此您可以選擇它來檢視其記錄或向其分配更多工作。一旦面板中的每個 agent 都閒置，閒置列會在 30 秒後隱藏，並在隊友的下一個回合時重新出現；隊友在隱藏時仍保持執行狀態且可定址。在 v2.1.181 至 v2.1.198 中，閒置列在其自己的回合結束後 30 秒隱藏，即使其他隊友仍在工作；v2.1.181 之前的版本不會隱藏閒置列。

94當超過三個隊友同時閒置時，前三個之外的列會摺疊成單一列，計算摺疊的隊友，例如當五個閒置時顯示 `2 idle agents`。選擇它並按 Enter 以展開摺疊的列，或按 Esc 以再次摺疊它們。工作中的隊友、失敗的隊友和您正在檢視的隊友始終保持自己的列。

93 95

94如果您希望每個隊友都在自己的分割窗格中，請參閱[選擇顯示模式](#choose-a-display-mode)。96如果您希望每個隊友都在自己的分割窗格中，請參閱[選擇顯示模式](#choose-a-display-mode)。

95 97

174* **In-process 模式**：使用上下箭頭鍵在 agent 面板中選擇隊友，然後按 Enter 鍵查看其工作階段並輸入以傳送訊息。在選定的隊友上按 `x` 以停止它。按 Ctrl+T 切換任務列表。176* **In-process 模式**：使用上下箭頭鍵在 agent 面板中選擇隊友，然後按 Enter 鍵查看其工作階段並輸入以傳送訊息。在選定的隊友上按 `x` 以停止它。按 Ctrl+T 切換任務列表。

175* **Split-pane 模式**：點擊隊友的窗格以直接與其工作階段互動。每個隊友都有自己終端的完整檢視。177* **Split-pane 模式**：點擊隊友的窗格以直接與其工作階段互動。每個隊友都有自己終端的完整檢視。

176 178

179當您正在查看 in-process 隊友時，純文字和 [skills](/zh-TW/skills) 會傳送給該隊友，但內建命令仍在主管的工作階段中運行。

180

181隊友的模型和快速模式在它生成時是固定的，因此 `/model` 和 `/fast` 只會變更主管的設定。{/* min-version: 2.1.199 */}自 v2.1.199 起，在查看隊友時輸入任一命令會顯示通知，表示變更適用於主管；較早的版本會將其應用於主管而不提示。`/effort` 仍適用於所查看隊友的後續回合，因為隊友遵循主管的[努力程度](/zh-TW/model-config#adjust-effort-level)。

182

177<h3 id="assign-and-claim-tasks">183<h3 id="assign-and-claim-tasks">

178 分配和認領任務184 分配和認領任務

179</h3>185</h3>

295**隊友如何分享資訊：**301**隊友如何分享資訊：**

296 302

297* **自動訊息傳遞**：當隊友發送訊息時，它們會自動傳遞給收件人。主管不需要輪詢更新。303* **自動訊息傳遞**：當隊友發送訊息時，它們會自動傳遞給收件人。主管不需要輪詢更新。

298* **閒置通知**：當隊友完成並停止時，他們會自動通知主管。304* **閒置通知**：當隊友完成並停止時，他們會自動通知主管。{/* min-version: 2.1.198 */}自 v2.1.198 起，隊友的回合因 API 錯誤而結束時會通知主管它失敗並包含錯誤文本，而不是看起來正常完成。

299* **共享任務列表**：所有代理都可以看到任務狀態並認領可用工作。305* **共享任務列表**：所有代理都可以看到任務狀態並認領可用工作。

300* **隊友訊息傳遞**：按名稱向一個特定隊友發送訊息。若要聯繫所有人，請為每個收件人發送一條訊息。306* **隊友訊息傳遞**：按名稱向一個特定隊友發送訊息。若要聯繫所有人，請為每個收件人發送一條訊息。

301 307

430如果在您要求 Claude 建立隊友後隊友未出現：436如果在您要求 Claude 建立隊友後隊友未出現：

431 437

432* 在 in-process 模式中，隊友會出現在提示輸入下方的代理面板中。使用上下箭頭鍵選擇一個，然後按 Enter 鍵查看它。438* 在 in-process 模式中，隊友會出現在提示輸入下方的代理面板中。使用上下箭頭鍵選擇一個，然後按 Enter 鍵查看它。

433* 閒置後消失的隊友列已被隱藏，而非停止。閒置列在 30 秒後隱藏，並在隊友的下一輪時重新出現。按名稱向隊友發送訊息以將其恢復。439* 閒置後消失的隊友列已被隱藏，而非停止。閒置列在整個面板閒置 30 秒後隱藏，並在隊友的下一輪時重新出現。當超過三個隊友閒置時，其多餘列會摺疊成單一的 `N idle agents` 列，按 Enter 鍵可展開。按名稱向隊友發送訊息以將隱藏列恢復。

434* 檢查您給 Claude 的任務是否足夠複雜以保證建立團隊。Claude 根據任務決定是否生成隊友。440* 檢查您給 Claude 的任務是否足夠複雜以保證建立團隊。Claude 根據任務決定是否生成隊友。

435* 如果您明確要求分割窗格，請確保 tmux 已安裝並在您的 PATH 中可用：441* 如果您明確要求分割窗格，請確保 tmux 已安裝並在您的 PATH 中可用：

436 ```bash theme={null}442 ```bash theme={null}

453* 直接給他們額外的指示459* 直接給他們額外的指示

454* 生成替換隊友以繼續工作460* 生成替換隊友以繼續工作

455 461

462{/* min-version: 2.1.198 */}自 v2.1.198 起，來自主管或另一隊友的訊息會喚醒正在等待重試失敗 API 請求的 in-process 隊友，因此它會立即重試，而不是等待完整的重試延遲。

463

456<h3 id="lead-shuts-down-before-work-is-done">464<h3 id="lead-shuts-down-before-work-is-done">

457 主管在工作完成前關閉465 主管在工作完成前關閉

458</h3>466</h3>

481* **關閉可能很慢**：隊友在關閉前完成其目前請求或工具呼叫，這可能需要時間。489* **關閉可能很慢**：隊友在關閉前完成其目前請求或工具呼叫，這可能需要時間。

482* **每個工作階段一個團隊**：一個工作階段恰好有一個團隊，範圍限於該工作階段。您無法建立其他具名團隊或在工作階段之間共享團隊。490* **每個工作階段一個團隊**：一個工作階段恰好有一個團隊，範圍限於該工作階段。您無法建立其他具名團隊或在工作階段之間共享團隊。

483* **沒有嵌套團隊**：隊友無法生成自己的隊友。只有主管可以管理團隊。491* **沒有嵌套團隊**：隊友無法生成自己的隊友。只有主管可以管理團隊。

492* **沒有來自 in-process 隊友的背景子代理**：in-process 隊友自己的子代理在前景中執行。要求背景子代理，無論是使用 `run_in_background` 或設定 `background: true` 的子代理定義，都會傳回錯誤，因為隊友的背景工作無法超越主管的程序。從主要對話啟動的子代理遵循[背景預設](/zh-TW/sub-agents#run-subagents-in-foreground-or-background)。

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

485* **權限在生成時設定**：所有隊友開始時具有主管的權限模式。您可以在生成後更改個別隊友模式，但在生成時無法設定每個隊友的模式。494* **權限在生成時設定**：所有隊友開始時具有主管的權限模式。您可以在生成後更改個別隊友模式，但在生成時無法設定每個隊友的模式。

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

agent-view.md +65 −12

Details

27* [快速開始](#quick-start)：給 Claude 一個在背景中執行的任務，檢查它，並在需要時介入27* [快速開始](#quick-start)：給 Claude 一個在背景中執行的任務，檢查它，並在需要時介入

28* [使用 agent view 監控工作階段](#monitor-sessions-with-agent-view)，包括狀態圖示、查看和回覆、附加、組織和快捷鍵28* [使用 agent view 監控工作階段](#monitor-sessions-with-agent-view)，包括狀態圖示、查看和回覆、附加、組織和快捷鍵

29* [分派新代理](#dispatch-new-agents)，從 agent view、從工作階段內部或從 shell29* [分派新代理](#dispatch-new-agents)，從 agent view、從工作階段內部或從 shell

~~30* [從 shell 管理工作階段](#manage-sessions-from-the-shell)~~30* [從 shell 管理工作階段](#manage-sessions-from-the-shell)，使用 `claude agents`、`claude attach` 和相關命令

31* [背景工作階段如何被託管](#how-background-sessions-are-hosted)，由監督程序31* [背景工作階段如何被託管](#how-background-sessions-are-hosted)，由監督程序

32 32

33<h2 id="quick-start">33<h2 id="quick-start">

64 </Step>64 </Step>

65 65

66 <Step title="帶入現有工作階段">66 <Step title="帶入現有工作階段">

67 要將您已開啟的工作階段移入 agent view，在其中執行 `/bg`，或在空提示上按 `←` 以在一個步驟中背景化工作階段並開啟 agent view。工作階段繼續執行並顯示為一列，與您分派的工作階段並排。67 這個步驟需要一個執行中的工作階段。如果您遵循了之前的步驟，您在此終端中沒有開啟的工作階段，因此請在另一個終端中開啟一個常規 `claude` 工作階段並先向其發送訊息。要將您已開啟的工作階段移入 agent view，在其中執行 `/bg`，或在空提示上按 `←` 以在一個步驟中背景化工作階段並開啟 agent view。工作階段繼續執行並顯示為一列，與您分派的工作階段並排。

68 </Step>68 </Step>

69</Steps>69</Steps>

70 70

76 76

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

78 78

79名稱以該工作階段中由 [`/color`](/zh-TW/commands) 設定的顏色著色。{/* min-version: 2.1.199 */}自 v2.1.199 起，當您使用 `←` 或 `/background` [背景化工作階段](#from-inside-a-session)時，顏色會保留。

79根據預設，該列表顯示您啟動的每個背景工作階段，跨越所有您的專案。在一個儲存庫中工作的工作階段和在不同 worktree 中工作的另一個工作階段都會出現在這裡，無論您從哪個目錄開啟 agent view。要將檢視範圍限制在一個專案，請傳遞 `--cwd`：81根據預設，該列表顯示您啟動的每個背景工作階段，跨越所有您的專案。在一個儲存庫中工作的工作階段和在不同 worktree 中工作的另一個工作階段都會出現在這裡，無論您從哪個目錄開啟 agent view。要將檢視範圍限制在一個專案，請傳遞 `--cwd`：

80 82

81```bash theme={null}83```bash theme={null}

91 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m93 ✽ clawd walk cycle Write assets/sprites/clawd-walk.png 3m

92 94

93Ready for review95Ready for review

~~94 ∙ jump physics Opened PR with collision fix PR #2048 2h~~96 ∙ jump physics Opened PR with collision fix #2048 2h

95 97

96Needs input98Needs input

97 ✻ power-up design needs input: double jump or wall climb? 1m99 ✻ power-up design needs input: double jump or wall climb? 1m

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

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

131 133

132出現在行右邊緣的 `PR #N` 標籤是[工作階段開啟的拉取請求](#pull-request-status)，不是狀態圖示的一部分。當工作階段開啟了多個拉取請求時，標籤會顯示計數，例如 `3 PRs`。134出現在行右邊緣的 `#N` 標籤是[工作階段開啟的拉取請求](#pull-request-status)，不是狀態圖示的一部分。

133 135

134終端標籤標題在 agent view 開啟時顯示等待輸入計數：當工作階段需要輸入時為 `2 awaiting input · claude agents`，或當沒有工作階段需要輸入時為 `claude agents`。136終端標籤標題在 agent view 開啟時顯示等待輸入計數：當工作階段需要輸入時為 `2 awaiting input · claude agents`，或當沒有工作階段需要輸入時為 `claude agents`。

135 137

138自 v2.1.198 起，當 agent view 開啟時，Claude Code 也會通過您配置的[終端通知頻道](/zh-TW/terminal-config#get-a-terminal-bell-or-notification)發送通知，當本機背景工作階段開始需要您的輸入、完成或失敗時。在排程上執行的工作階段，例如 [`/loop`](/zh-TW/scheduled-tasks) 工作階段，只在需要您的輸入時通知。通知使用與 Claude Code 其餘部分相同的 [`preferredNotifChannel` 設定](/zh-TW/settings#available-settings)，並使用 `agent_needs_input` 或 `agent_completed` 類型觸發 [`Notification` hook](/zh-TW/hooks#notification)。

139

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

137 141

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

151 拉取請求狀態155 拉取請求狀態

152</h3>156</h3>

153 157

154當工作階段開啟拉取請求時，`PR #1234` 標籤會出現在該行的右邊緣，在支援超連結的終端中連結到拉取請求。當您向工作階段發送後續訊息時標籤會保留，因此拉取請求在該行恢復為即時進度時保持可見。158當工作階段開啟拉取請求時，`#1234` 標籤會出現在該行的右邊緣，在支援超連結的終端中連結到拉取請求。當您向工作階段發送後續訊息時標籤會保留，因此拉取請求在該行恢復為即時進度時保持可見。隔離其變更在 worktree 中的背景工作階段會自己開啟這些拉取請求；[檔案編輯如何隔離](#how-file-edits-are-isolated)涵蓋何時發生以及工作階段在未詢問的情況下永遠不會做什麼。

155 159

156當工作階段開啟了多個拉取請求時，標籤會顯示計數，例如 `3 PRs`，按最需要關注的開啟拉取請求著色。開啟[查看面板](#peek-and-reply)以查看它們全部。160當工作階段開啟了多個拉取請求時，標籤會顯示計數，例如 `3 PRs`，按最需要關注的開啟拉取請求著色。開啟[查看面板](#peek-and-reply)以查看它們全部。

157 161

190 194

191附加的工作階段始終以[全螢幕模式](/zh-TW/fullscreen)呈現，無論您的 `tui` 設定如何，因為背景工作階段沒有終端滾動回溯可附加。使用 `PgUp`、`PgDn` 或滑鼠滾輪滾動，並按 `Ctrl+O` 進入記錄模式。您終端的原生滾動和 tmux 複製模式只顯示當前視口，與執行任何全螢幕應用程式時相同。195附加的工作階段始終以[全螢幕模式](/zh-TW/fullscreen)呈現，無論您的 `tui` 設定如何，因為背景工作階段沒有終端滾動回溯可附加。使用 `PgUp`、`PgDn` 或滑鼠滾輪滾動，並按 `Ctrl+O` 進入記錄模式。您終端的原生滾動和 tmux 複製模式只顯示當前視口，與執行任何全螢幕應用程式時相同。

192 196

193在空提示上按 `←` 分離並返回 agent view。如果對話框有焦點且不響應 `←`，按 `Ctrl+Z` 立即分離。197在空提示上按 `←` 或執行 `/exit` 以分離並返回 agent view。自 v2.1.198 起，無論您是從 agent view 開啟工作階段還是從 shell 執行 `claude attach <id>`，這都以相同的方式工作。

198

199`Ctrl+Z` 也會分離但會回到您開始的地方：如果您從 agent view 附加則返回 agent view，或如果您執行 `claude attach` 則返回 shell。當對話框有焦點且不響應 `←` 時使用 `Ctrl+Z`。

194 200

195`Ctrl+C` 在附加時保持其標準中斷行為：它取消執行中的回應或 `!` shell 命令，而不是分離。在空提示上按 `Ctrl+C` 兩次會分離，與任何工作階段中相同。201`Ctrl+C` 在附加時保持其標準中斷行為：它取消執行中的回應或 `!` shell 命令，而不是分離。在空提示上按 `Ctrl+C` 兩次會分離，與任何工作階段中相同。

196 202

291 297

292一小組命令在 agent view 本身中執行，而不是分派：`/exit` 和 `/quit` 關閉 agent view，`/logout` 將您登出，以及 `/model` 設定[dispatch model](#set-the-model)。Skills、您自己的命令和提示擴展內建命令（例如 `/init`）會作為新背景工作階段的第一個提示發送。其他內建命令會顯示 `attach to a session to run it` 提示。298一小組命令在 agent view 本身中執行，而不是分派：

299

300* `/exit` 和 `/quit` 關閉 agent view

301* `/logout` 將您登出

302* `/model` 設定[分派模型](#set-the-model)

303* {/* min-version: 2.1.198 */}自 v2.1.198 起，`/login` 開啟登入對話框，讓您無需附加到工作階段即可再次登入

304

305Skills、您自己的命令和提示擴展內建命令（例如 `/init`）會作為新背景工作階段的第一個提示發送。其他內建命令會顯示 `attach to a session to run it` 提示。

293 306

294將重複任務打包為 [skill](/zh-TW/skills)可讓您從 agent view 多次啟動相同的工作流程，無需重新輸入提示。307將重複任務打包為 [skill](/zh-TW/skills)可讓您從 agent view 多次啟動相同的工作流程，無需重新輸入提示。

295 308

313 326

314執行 `/background` 或其別名 `/bg` 將當前對話移動到背景工作階段。傳遞提示，例如 `/bg run the test suite and fix any failures`，以在分派前發送一個額外的指令。如果 Claude 在您執行 `/bg` 時正在回應，回應會在背景工作階段中繼續。327執行 `/background` 或其別名 `/bg` 將當前對話移動到背景工作階段。傳遞提示，例如 `/bg run the test suite and fix any failures`，以在分派前發送一個額外的指令。如果 Claude 在您執行 `/bg` 時正在回應，回應會在背景工作階段中繼續。

315 328

329退出仍有背景工作執行的互動工作階段（例如 subagents、背景 shell 命令、工作流程或 [monitors](/zh-TW/tools-reference#monitor-tool)）會顯示 `Background work is running` 對話而不是立即退出。{/* min-version: 2.1.198 */}自 v2.1.198 起，對話框提供 `Move to background and exit` 以及 `Exit anyway` 和 `Stay`。選擇它會以與 `/background` 相同的方式將工作階段移動到背景，然後返回您的 shell，因此可以繼續的工作會保持執行，工作階段會出現在 agent view 中。當 agent view [關閉](#turn-off-agent-view)時，不會顯示此選項。

330

316從互動工作階段背景化會啟動一個新的進程，該進程從保存的對話恢復，進行中的工作會轉移到它：執行中的背景 shell 命令、背景化的 subagents、動態工作流程和您使用 [`/loop`](/zh-TW/scheduled-tasks)建立的排定任務會轉移到背景工作階段並在那裡繼續執行。Subagent 與它啟動的所有內容一起移動，因此只有當所有工作都能轉移時它才會轉移，包括在 Windows 上。要停止進行中的工作而不是轉移它，請設定 [`CLAUDE_DISABLE_ADOPT=1`](/zh-TW/env-vars#variables)環境變數；Claude Code 隨後會要求您在背景化前確認。331從互動工作階段背景化會啟動一個新的進程，該進程從保存的對話恢復，進行中的工作會轉移到它：執行中的背景 shell 命令、背景化的 subagents、動態工作流程和您使用 [`/loop`](/zh-TW/scheduled-tasks)建立的排定任務會轉移到背景工作階段並在那裡繼續執行。Subagent 與它啟動的所有內容一起移動，因此只有當所有工作都能轉移時它才會轉移，包括在 Windows 上。要停止進行中的工作而不是轉移它，請設定 [`CLAUDE_DISABLE_ADOPT=1`](/zh-TW/env-vars#variables)環境變數；Claude Code 隨後會要求您在背景化前確認。

317 332

318無法轉移的工作，例如執行中的 [monitor](/zh-TW/tools-reference#monitor-tool)，會被停止。擁有監視器的背景化 subagent 會與它一起被停止。當任何此類工作執行時，Claude Code 會顯示 `Background this session?` 對話，以便您可以在停止前確認。333無法轉移的工作，例如執行中的 [monitor](/zh-TW/tools-reference#monitor-tool)，會被停止。擁有監視器的背景化 subagent 會與它一起被停止。當任何此類工作執行時，Claude Code 會顯示 `Background this session?` 對話，以便您可以在停止前確認。

342claude --bg "investigate the flaky SettingsChangeDetector test"357claude --bg "investigate the flaky SettingsChangeDetector test"

343```358```

344 359

360提示是位置引數，不是 `-p` 值。{/* min-version: 2.1.198 */}自 v2.1.198 起，將 `--bg` 與 `-p` 或 `--print` 結合會在建立任何工作階段前被拒絕並出現錯誤，因為 `--print` 永遠不會啟動 `claude agents` 附加到的互動工作階段。

361

345要執行特定 subagent 作為工作階段的主代理，將 `--bg` 與 `--agent` 結合：362要執行特定 subagent 作為工作階段的主代理，將 `--bg` 與 `--agent` 結合：

346 363

347```bash theme={null}364```bash theme={null}

414 431

415[subagent](/zh-TW/sub-agents)背景工作階段生成的會繼承工作階段的工作目錄，因此其檔案編輯會進入工作階段的 worktree 而不是您的工作副本。要給 subagent 其自己的單獨 worktree，請在其 frontmatter 中設定 [`isolation: worktree`](/zh-TW/sub-agents#supported-frontmatter-fields)或在生成它時傳遞 `isolation: "worktree"`。432[subagent](/zh-TW/sub-agents)背景工作階段生成的會繼承工作階段的工作目錄，因此其檔案編輯會進入工作階段的 worktree 而不是您的工作副本。要給 subagent 其自己的單獨 worktree，請在其 frontmatter 中設定 [`isolation: worktree`](/zh-TW/sub-agents#supported-frontmatter-fields)或在生成它時傳遞 `isolation: "worktree"`。

416 433

434自 v2.1.198 起，在隔離 worktree 中隔離其程式碼更改的背景工作階段也會提交、推送其自己的分支，並開啟草稿拉取請求而無需停止詢問。當拉取請求開啟時，[`#N` 標籤](#pull-request-status)會出現在其行上。它永遠不會推送到 `main` 或 `master`，永遠不會強制推送或合併，並且當您告訴它不要開啟拉取請求或儲存庫沒有遠端時會跳過拉取請求。

435

436編輯未自行隔離的檢出的工作階段在提交或切換分支前仍會詢問。這適用於隔離設定為 `"none"` 時、worktree 移動失敗時，或工作階段在已存在的 worktree 內啟動時。

437

417<h3 id="set-the-model">438<h3 id="set-the-model">

418 設定模型439 設定模型

419</h3>440</h3>

529 550

530一旦工作階段完成並在未附加的情況下閒置約一小時，監督程序停止其程序以釋放資源。您使用 `Ctrl+T` [釘選](#organize-the-list)的工作階段不受此限制，在閒置時保持其程序執行。無論如何，文字記錄和狀態保留在磁碟上，下次您附加、查看或回覆已停止的工作階段時，監督程序從中斷的地方啟動新程序。當每個工作階段都完成且沒有終端連接時，監督程序本身退出，並在下次您需要它時再次啟動。551一旦工作階段完成並在未附加的情況下閒置約一小時，監督程序停止其程序以釋放資源。您使用 `Ctrl+T` [釘選](#organize-the-list)的工作階段不受此限制，在閒置時保持其程序執行。無論如何，文字記錄和狀態保留在磁碟上，下次您附加、查看或回覆已停止的工作階段時，監督程序從中斷的地方啟動新程序。當每個工作階段都完成且沒有終端連接時，監督程序本身退出，並在下次您需要它時再次啟動。

531 552

532背景 shell 命令和動態工作流程工作階段啟動的會在其程序被停止、重新啟動或更新時繼續執行，包括在 Windows 上。為該工作階段啟動的下一個程序會接收它們，已完成的 shell 命令會報告為已完成及其輸出，工作流程會從中斷的地方恢復。由 subagent 啟動的 shell 命令和執行中的 [monitors](/zh-TW/tools-reference#monitor-tool)仍會與程序一起停止，刪除工作階段會停止它交付的所有內容。要讓背景 shell 命令和工作流程與程序一起停止，請將 [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/zh-TW/env-vars#variables)環境變數設定為 `1`。553工作階段本身在頂層啟動的背景工作會在其程序被停止、重新啟動或更新時交付，包括在 Windows 上。為該工作階段啟動的下一個程序會接收它們：

554

555* 在此期間完成的背景 shell 命令會報告為已完成及其輸出

556* 動態工作流程會從中斷的地方恢復

557* [背景子代理](/zh-TW/sub-agents#run-subagents-in-foreground-or-background)會從其自己的文字記錄恢復

558

559{/* min-version: 2.1.198 */}自 v2.1.198 起，交付涵蓋所有三項。在 v2.1.198 之前，它只涵蓋 shell 命令和工作流程，因此背景子代理會與程序一起停止，並在下次喚醒時報告為失敗。

560

561其狀態僅存在於程序內部的工作會與它一起停止，而不是被交付。那是子代理啟動的 shell 命令，恢復的子代理可以再次啟動，以及執行中的[監視器](/zh-TW/tools-reference#monitor-tool)，其事件流無法移動到另一個程序。

533 562

534如果重新啟動的工作階段回來時只顯示其原始提示，因為 Claude Code 誤讀其記錄為空，對話記錄會被重命名為 `.orphaned-` 後綴，而不是被刪除，因此它會保留在您的機器上。563刪除工作階段會停止它交付的所有內容。要讓所有工作階段的背景工作與程序一起停止而不是被交付，請將 [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/zh-TW/env-vars#variables) 環境變數設定為 `1`。

564

565如果重新啟動的工作階段回來時只顯示其原始提示，因為 Claude Code 誤讀其文字記錄為空，對話文字記錄會被重命名為 `.orphaned-` 後綴，而不是被刪除，因此它會保留在您的機器上。

535 566

536按 `←` 留下的空白列，從未被給予提示，會在約五分鐘後被完全移除，以便列表自動清除。使用 `claude --bg` 啟動的工作階段和等待設定提示（例如信任對話）的工作階段不會以這種方式被移除。567按 `←` 留下的空白列，從未被給予提示，會在約五分鐘後被完全移除，以便列表自動清除。使用 `claude --bg` 啟動的工作階段和等待設定提示（例如信任對話）的工作階段不會以這種方式被移除。

537 568

554 585

555每個背景工作階段都設定了 `CLAUDE_JOB_DIR` 環境變數，指向其 `~/.claude/jobs/<id>` 目錄，因此工作階段執行的 shell 命令可以將臨時檔案寫入 `$CLAUDE_JOB_DIR/tmp`，而不會與平行工作階段衝突。586每個背景工作階段都設定了 `CLAUDE_JOB_DIR` 環境變數，指向其 `~/.claude/jobs/<id>` 目錄，因此工作階段執行的 shell 命令可以將臨時檔案寫入 `$CLAUDE_JOB_DIR/tmp`，而不會與平行工作階段衝突。

556 587

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

558 589

559該命令也會在執行中的監督程序版本與您叫用的 `claude` 版本不同時發出警告，這會在監督程序尚未重新啟動到新版本的更新後發生。警告會顯示兩個版本，並告訴您執行 `claude daemon stop --any` 以採用新版本。當 Claude Code 安裝為作業系統服務時，建議的命令是 `claude daemon stop`，不帶該旗標。590該命令也會在執行中的監督程序版本與您叫用的 `claude` 版本不同時發出警告，這會在監督程序尚未重新啟動到新版本的更新後發生。警告會顯示兩個版本，並告訴您執行 `claude daemon stop --any` 以採用新版本。當 Claude Code 安裝為作業系統服務時，建議的命令是 `claude daemon stop`，不帶該旗標。

560 591

561工作階段在該版本不匹配時保持完整：較舊的 Claude Code 版本更新工作階段的 `state.json` 時會保留它不識別的欄位，並保持工作階段列出。592工作階段在該版本不匹配時保持完整：較舊的 Claude Code 版本更新工作階段的 `state.json` 時會保留它不識別的欄位，並保持工作階段列出。

562 593

594在 Windows 上，當 daemon 的 pipe-key 檔案被鎖定或無法讀取時，`claude daemon status` 會顯示基礎檔案錯誤，而不是報告通用連接失敗。

595

563<h3 id="turn-off-agent-view">596<h3 id="turn-off-agent-view">

564 關閉 agent view597 關閉 agent view

565</h3>598</h3>

604 637

605睡眠單獨不會導致這種情況。工作階段在睡眠期間會被保留，監督程序在喚醒時會重新連接到它們。638睡眠單獨不會導致這種情況。工作階段在睡眠期間會被保留，監督程序在喚醒時會重新連接到它們。

606 639

640<h3 id="a-session-fails-before-starting-with-a-possibly-low-memory-note">

641 工作階段在啟動前失敗，並出現 `possibly low memory` 註記

642</h3>

643

644自 v2.1.199 起，當背景工作階段的程序在完成啟動前退出，且主機記憶體不足時，該列的狀態會命名退出並新增 `possibly low memory — free some up and retry`。較早的版本只顯示此失敗的裸退出原因。

645

646該註記是一個假設，而不是確認的原因。Claude Code 只在程序無聲退出時新增它，沒有寫入錯誤，也沒有被信號停止，且主機在該時刻報告記憶體不足。當程序在退出前確實寫入了錯誤時，該列會改為顯示該錯誤。

647

648釋放機器上的記憶體，然後附加、查看或回覆該列，監督程序會為工作階段啟動新的程序。當記憶體保持不足時，監督程序也會[停止閒置工作階段](#the-supervisor-process)以自行釋放資源。

649

607<h3 id="agent-view-says-the-background-service-did-not-respond">650<h3 id="agent-view-says-the-background-service-did-not-respond">

608 Agent view 表示背景服務未回應651 Agent view 表示背景服務未回應

609</h3>652</h3>

616 659

617新的監督程序會重新連接到執行中的工作階段。如果沒有 `--keep-workers`，該命令也會結束背景工作階段。`--any` 旗標確認您想要停止按需啟動的監督程序，而不是作為已安裝的服務啟動的程序，這是預設值。660新的監督程序會重新連接到執行中的工作階段。如果沒有 `--keep-workers`，該命令也會結束背景工作階段。`--any` 旗標確認您想要停止按需啟動的監督程序，而不是作為已安裝的服務啟動的程序，這是預設值。

618 661

662啟動但無法接受連接的監督程序會自行退出並釋放其鎖定，因此下一個 `claude agents` 會啟動新的程序，無需此手動停止。上述步驟適用於執行中的監督程序停止回應的情況。

663

619在 Windows 上，如果監督程序未回應停止請求，該命令會列印其程序 ID。使用 `taskkill /PID <pid>` 結束該程序以完成復原。當您傳遞 `--keep-workers` 時，背景工作階段仍會被保留。664在 Windows 上，如果監督程序未回應停止請求，該命令會列印其程序 ID。使用 `taskkill /PID <pid>` 結束該程序以完成復原。當您傳遞 `--keep-workers` 時，背景工作階段仍會被保留。

620 665

621<h3 id="dispatch-fails-with-could-not-resolve-authentication-method">666<h3 id="dispatch-fails-with-could-not-resolve-authentication-method">

632 677

633請參閱[錯誤參考](/zh-TW/errors#could-not-resolve-authentication-method)以取得完整的原因和修復清單。678請參閱[錯誤參考](/zh-TW/errors#could-not-resolve-authentication-method)以取得完整的原因和修復清單。

634 679

635<h3 id="background-sessions-cannot-read-desktop-documents-or-downloads-on-macos">680<h3 id="background-sessions-can’t-read-desktop-documents-or-downloads-on-macos">

636 背景工作階段無法在 macOS 上讀取 Desktop、Documents 或 Downloads681 背景工作階段無法在 macOS 上讀取 Desktop、Documents 或 Downloads

637</h3>682</h3>

638 683

640 685

641使用原生安裝程式，該項目會顯示為 Claude Code，授予的權限在更新後會保留。使用其他安裝方法（例如 Homebrew 或 npm），該項目會顯示二進位檔路徑，更新後可能需要再次授予。686使用原生安裝程式，該項目會顯示為 Claude Code，授予的權限在更新後會保留。使用其他安裝方法（例如 Homebrew 或 npm），該項目會顯示二進位檔路徑，更新後可能需要再次授予。

642 687

688<h3 id="background-sessions-can’t-reach-local-network-hosts-on-macos">

689 背景工作階段無法在 macOS 上連接到本機網路主機

690</h3>

691

692在 macOS 15 及更新版本上，系統會阻止程序連接到您本機網路上的裝置，直到您授予本機網路權限。在 v2.1.198 之前，背景工作階段主機從未請求該權限，因此針對 LAN 位址的命令失敗，出現 `connect: no route to host`，即使相同的命令在前景終端中有效。{/* min-version: 2.1.198 */}自 v2.1.198 起，背景工作階段中連接到本機網路位址的第一個命令會觸發 Claude Code 的 macOS 本機網路權限提示。授予一次，這些命令就能像在前景終端中一樣連接到 LAN 主機。

693

643<h3 id="a-session-is-slow-to-respond-after-attaching">694<h3 id="a-session-is-slow-to-respond-after-attaching">

644 工作階段在附加後響應緩慢695 工作階段在附加後響應緩慢

645</h3>696</h3>

679Agent view 在研究預覽期間發展迅速。如果您使用較舊的 Claude Code 版本，本頁上的某些行為可能會有所不同；特別是，`claude agents` 會以 `unknown option` 錯誤拒絕它尚不支援的旗標。下表列出了每個旗標和行為何時新增。730Agent view 在研究預覽期間發展迅速。如果您使用較舊的 Claude Code 版本，本頁上的某些行為可能會有所不同；特別是，`claude agents` 會以 `unknown option` 錯誤拒絕它尚不支援的旗標。下表列出了每個旗標和行為何時新增。

680 731

681| 版本 | 變更 |732| 版本 | 變更 |

682| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |733| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

734| v2.1.199 | {/* min-version: 2.1.199 */}背景工作階段的程序在低記憶體主機上完成啟動前退出時，其列狀態會顯示 `possibly low memory — free some up and retry`，而不是只顯示裸露的退出原因。使用 `←` 或 `/background` 背景化工作階段會將其 `/color` 帶到新列。 |

735| v2.1.198 | {/* min-version: 2.1.198 */}Agent view 在背景工作階段需要輸入、完成或失敗時透過 `preferredNotifChannel` 傳送通知，並使用 `agent_needs_input` 或 `agent_completed` 類型觸發 `Notification` hook。`←` 和 `/exit` 在 `claude attach <id>` 內返回 agent view 而不是退出到 shell；`Ctrl+Z` 返回到 shell。隔離其工作在 worktree 中的背景工作階段會提交、推送其自己的隔離分支（絕不是 `main` 或 `master`），並在完成時開啟草稿拉取請求，而不是先詢問。`/login` 在 agent view 中執行並開啟登入對話框。`Background work is running` 退出對話框提供 `Move to background and exit`。退出交付也涵蓋背景子代理，它們在下次喚醒時從其記錄恢復，而不是被報告為失敗。`claude --bg` 與 `-p` 或 `--print` 結合會被拒絕並出現錯誤。 |

683| v2.1.196 | {/* min-version: 2.1.196 */}單一 `←` 按下會背景化前景工作階段；較早的版本需要兩次按下，帶有頁尾提示和確認。傳遞給 `claude agents` 的 `--dangerously-skip-permissions` 會顯示繞過免責聲明，而不是被無聲地丟棄。您從未命名的互動工作階段在工作階段清單和 `claude agents --json` 中帶有預設名稱，例如 `my-app-3f`。背景 shell 命令和動態工作流程在工作階段的程序被停止、重新啟動或更新時存活，包括在 Windows 上；設定 `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` 以關閉交付。在重新啟動時誤讀為空的記錄會被重命名為 `.orphaned-` 後綴，而不是被刪除。 |736| v2.1.196 | {/* min-version: 2.1.196 */}單一 `←` 按下會背景化前景工作階段；較早的版本需要兩次按下，帶有頁尾提示和確認。傳遞給 `claude agents` 的 `--dangerously-skip-permissions` 會顯示繞過免責聲明，而不是被無聲地丟棄。您從未命名的互動工作階段在工作階段清單和 `claude agents --json` 中帶有預設名稱，例如 `my-app-3f`。背景 shell 命令和動態工作流程在工作階段的程序被停止、重新啟動或更新時存活，包括在 Windows 上；設定 `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` 以關閉交付。在重新啟動時誤讀為空的記錄會被重命名為 `.orphaned-` 後綴，而不是被刪除。 |

684| v2.1.195 | {/* min-version: 2.1.195 */}進行中的工作在您背景化 Windows 上的工作階段時也會轉移；設定 `CLAUDE_DISABLE_ADOPT=1` 以改為停止它。`Completed` 組填充剩餘的垂直空間，標題在短終端上壓縮。較舊的 Claude Code 版本不再丟棄較新工作階段的 `state.json` 欄位或隱藏這些工作階段。附加到已停止的工作階段會立即切換，而不是顯示空白螢幕最多五秒。無法接受連接的監督程序會自行退出並釋放其鎖定。 |737| v2.1.195 | {/* min-version: 2.1.195 */}進行中的工作在您背景化 Windows 上的工作階段時也會轉移；設定 `CLAUDE_DISABLE_ADOPT=1` 以改為停止它。`Completed` 組填充剩餘的垂直空間，標題在短終端上壓縮。較舊的 Claude Code 版本不再丟棄較新工作階段的 `state.json` 欄位或隱藏這些工作階段。附加到已停止的工作階段會立即切換，而不是顯示空白螢幕最多五秒。無法接受連接的監督程序會自行退出並釋放其鎖定。 |

685| v2.1.174 | {/* min-version: 2.1.174 */}背景工作階段不再繼承閘道端點變數，例如來自監督程序啟動 shell 的 `ANTHROPIC_BASE_URL`；監督程序向預先準備的工作程序提供新的認證快照，修復虛假的 `Could not resolve authentication method` 錯誤。 |738| v2.1.174 | {/* min-version: 2.1.174 */}背景工作階段不再繼承閘道端點變數，例如來自監督程序啟動 shell 的 `ANTHROPIC_BASE_URL`；監督程序向預先準備的工作程序提供新的認證快照，修復虛假的 `Could not resolve authentication method` 錯誤。 |

agents.md +1 −1

Details

53檢查運行中工作的命令取決於您使用的方法：53檢查運行中工作的命令取決於您使用的方法：

54 54

55* 對於後台會話，`claude agents` 打開 [代理視圖](/zh-TW/agent-view)：一個屏幕顯示每個會話、其狀態以及哪些需要您的輸入。55* 對於後台會話，`claude agents` 打開 [代理視圖](/zh-TW/agent-view)：一個屏幕顯示每個會話、其狀態以及哪些需要您的輸入。

56* 對於當前會話中的子代理，`/agents` 打開一個面板，其中 **Running** 選項卡列出實時子代理，**Library** 選項卡是您 [創建和編輯自定義子代理](/zh-TW/sub-agents#use-the-%2Fagents-command) 的地方。儘管名稱相似，但這與 `claude agents` 分開。56* 對於當前會話中的子代理，命名的後台子代理出現在 @-mention 類型提前中，並顯示其狀態。{/* min-version: 2.1.198 */}從 v2.1.198 開始，`/agents` 不再打開面板；它打印一個通知，指向子代理文件位置。要 [創建和編輯自定義子代理](/zh-TW/sub-agents#configure-subagents)，請詢問 Claude 或直接編輯文件。儘管名稱相似，但 `/agents` 與 `claude agents` 分開。

57* 對於當前會話後台運行的任何內容，`/tasks` 列出每個項目，並讓您檢查、附加到或停止它。57* 對於當前會話後台運行的任何內容，`/tasks` 列出每個項目，並讓您檢查、附加到或停止它。

58* 對於動態工作流程，`/workflows` 列出運行和已完成的運行、每個運行所處的階段，以及有多少代理已完成。58* 對於動態工作流程，`/workflows` 列出運行和已完成的運行、每個運行所處的階段，以及有多少代理已完成。

59 59

amazon-bedrock.md +1 −1

Details

184 184

185這兩個設定有不同的觸發條件：185這兩個設定有不同的觸發條件：

186 186

187* **`awsAuthRefresh`**：僅在 Claude Code 偵測到您的 AWS 認證已過期時執行，基於本機時間戳記或當 Bedrock 傳回認證錯誤時，然後使用重新整理的認證重試請求。187* **`awsAuthRefresh`**：僅在 Claude Code 偵測到您的 AWS 認證已過期時執行，基於本機時間戳記或當 API 傳回認證錯誤時，然後使用重新整理的認證重試請求。

188* **`awsCredentialExport`**：在工作階段開始時和每次認證重新載入時執行，即使您的 AWS 預設認證提供者鏈中的認證仍然有效。當您的 Bedrock 帳戶需要與預設提供者鏈會解析的認證不同的跨帳戶認證時，請使用此選項。188* **`awsCredentialExport`**：在工作階段開始時和每次認證重新載入時執行，即使您的 AWS 預設認證提供者鏈中的認證仍然有效。當您的 Bedrock 帳戶需要與預設提供者鏈會解析的認證不同的跨帳戶認證時，請使用此選項。

189 189

190<h5 id="example-configuration">190<h5 id="example-configuration">

auto-mode-config.md +18 −7

Details

54 54

55對於大多數組織，`autoMode.environment` 是您唯一需要設定的欄位。它告訴分類器哪些儲存庫、儲存桶和網域是受信任的：分類器使用它來決定「外部」的含義，因此任何未列出的目的地都是潛在的資料外洩目標。55對於大多數組織，`autoMode.environment` 是您唯一需要設定的欄位。它告訴分類器哪些儲存庫、儲存桶和網域是受信任的：分類器使用它來決定「外部」的含義，因此任何未列出的目的地都是潛在的資料外洩目標。

56 56

~~57自 Claude Code v2.1.195 起，`claude auto-mode defaults` 列印兩種環境項目。~~57自 Claude Code v2.1.198 起，`claude auto-mode defaults` 列印三種環境項目。v2.1.195 之前的版本只列印前五個信任槽位。

58 58

59* **上下文槽位**：描述您的組織、堆疊和安全態勢，以便分類器讀取您上下文中的其他規則。與其他兩種不同，上下文槽位沒有針對它們的規則。每個預設為 `None configured` 或預設為旁邊命名的保守假設：

60 * **組織**

61 * **Claude Code 的主要用途**：預設為軟體開發

62 * **雲端提供者**

63 * **儲存庫可見性**：除非其遠端主機和名稱另有指示，否則儲存庫被假定為私人

64 * **內部共享 / 程式碼片段託管**：公開貼上和 gist 服務被視為在信任邊界外，直到您命名一個

65 * **組織特定的 CLI**

66 * **祕密管理**

67 * **預設 / 受保護的分支**：`main` 和 `master` 被視為受保護，直到您命名其他分支

68 * **CI/CD 部署目標**

69 * **網路態勢**

70 * **受保護的部署命名空間 / 環境**：回退到敏感遠端目標啟發式方法，直到您命名它們

71 * **資料保留 / 解密**

59* **信任槽位**：命名分類器視為在您邊界內的內容。槽位是受信任儲存庫、原始碼控制、受信任內部網域、受信任雲端儲存桶、關鍵內部服務和內部套件登錄。儲存庫和原始碼控制項目預設為工作儲存庫及其設定的遠端。所有其他信任槽位預設為 `None configured`，因此在您新增之前沒有其他內容是受信任的。72* **信任槽位**：命名分類器視為在您邊界內的內容。槽位是受信任儲存庫、原始碼控制、受信任內部網域、受信任雲端儲存桶、關鍵內部服務和內部套件登錄。儲存庫和原始碼控制項目預設為工作儲存庫及其設定的遠端。所有其他信任槽位預設為 `None configured`，因此在您新增之前沒有其他內容是受信任的。

60* **敏感度槽位**：命名保護規則視為高風險的內容。槽位是 PII / 受管制資料位置、敏感遠端目標和受保護的 IaC 範圍。每個預設為廣泛的啟發式方法，例如將任何名稱包含 `prod` 或 `production` 的主機或命名空間視為敏感遠端目標，因此保護規則在您設定任何內容之前就處於活動狀態。在敏感度槽位中命名具體目標會使這些規則應用於命名的目標而不是啟發式方法。73* **敏感度槽位**：命名保護規則視為高風險的內容。槽位是敏感資料位置與受眾、敏感遠端目標和受保護的 IaC 範圍。每個預設為廣泛的啟發式方法，例如將任何名稱包含 `prod` 或 `production` 的主機或命名空間視為敏感遠端目標，因此保護規則在您設定任何內容之前就處於活動狀態。在敏感度槽位中命名具體目標會使這些規則應用於命名的目標而不是啟發式方法。

~~62v2.1.195 之前的版本只列印前五個信任槽位。~~

63 74

64要在預設值旁邊新增您自己的項目，請在陣列中包含字面字串 `"$defaults"`。預設項目會在該位置被插入，因此您的自訂項目可以在它們之前或之後。75要在預設值旁邊新增您自己的項目，請在陣列中包含字面字串 `"$defaults"`。預設項目會在該位置被插入，因此您的自訂項目可以在它們之前或之後。

65 76

87* **受信任的內部網域**：您網路內的 API、儀表板和服務的主機名稱，例如 `*.internal.example.com`98* **受信任的內部網域**：您網路內的 API、儀表板和服務的主機名稱，例如 `*.internal.example.com`

88* **關鍵內部服務**：CI、工件登錄、內部套件索引、事件工具99* **關鍵內部服務**：CI、工件登錄、內部套件索引、事件工具

89* **內部套件登錄**：私人 npm、PyPI 或其他登錄，安裝應該透過它路由，因此繞過它以使用公開登錄的安裝會被阻止100* **內部套件登錄**：私人 npm、PyPI 或其他登錄，安裝應該透過它路由，因此繞過它以使用公開登錄的安裝會被阻止

~~90* **PII / 受管制資料位置**：保存個人或受管制資料的儲存桶、資料庫或路徑，因此分類器保護這些位置而不是從內容猜測~~101* **敏感資料位置與受眾**：保存個人資料、機密業務資料、認證、受管制資料或類似敏感材料的儲存桶、資料庫或路徑，以及每個位置中的資料可能被共享的受眾，因此分類器保護這些位置而不是從內容猜測。{/* min-version: 2.1.195 */}{/* max-version: 2.1.197 */}Claude Code v2.1.195 至 v2.1.197 將此項目命名為 PII / 受管制資料位置，並且僅涵蓋保存個人或受管制資料的位置，不包括受眾維度

91* **敏感遠端目標**：計為生產的命名空間、主機或容器，因此遠端 shell 和連接埠轉發到它們需要您的明確批准102* **敏感遠端目標**：計為生產的命名空間、主機或容器，因此遠端 shell 和連接埠轉發到它們需要您的明確批准

92* **受保護的 IaC 範圍**：其應用或銷毀應始終要求您命名變更的基礎設施資源103* **受保護的 IaC 範圍**：其應用或銷毀應始終要求您命名變更的基礎設施資源

93* **其他上下文**：受管制行業的限制、多租戶基礎設施或影響分類器應將什麼視為風險的合規要求104* **其他上下文**：受管制行業的限制、多租戶基礎設施或影響分類器應將什麼視為風險的合規要求

94 105

95內部套件登錄、PII / 受管制資料位置、敏感遠端目標和受保護的 IaC 範圍項目需要 Claude Code v2.1.195 或更新版本。較早的版本仍將它們讀取為純上下文，但沒有針對它們的內建規則。106內部套件登錄、敏感資料位置與受眾、敏感遠端目標和受保護的 IaC 範圍項目需要 Claude Code v2.1.195 或更新版本。較早的版本仍將它們讀取為純上下文，但沒有針對它們的內建規則。

96 107

97一個有用的起始範本：填入括號中的欄位並移除任何不適用的行。108一個有用的起始範本：填入括號中的欄位並移除任何不適用的行。

98 109

chrome.md +15 −2

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# 在 Chrome 中使用 Claude Code（測試版）~~5# 在 Chrome 中使用 Claude Code

6 6

7> 將 Claude Code 連接到您的 Chrome 瀏覽器，以測試網頁應用程式、使用控制台日誌進行除錯、自動填充表單，以及從網頁中提取資料。7> 將 Claude Code 連接到您的 Chrome 瀏覽器，以測試網頁應用程式、使用控制台日誌進行除錯、自動填充表單，以及從網頁中提取資料。

8 8

11Claude 為瀏覽器任務開啟新標籤頁，並共享您瀏覽器的登入狀態，因此它可以存取您已登入的任何網站。瀏覽器操作在可見的 Chrome 視窗中即時執行。當 Claude 遇到登入頁面或 CAPTCHA 時，它會暫停並要求您手動處理。11Claude 為瀏覽器任務開啟新標籤頁，並共享您瀏覽器的登入狀態，因此它可以存取您已登入的任何網站。瀏覽器操作在可見的 Chrome 視窗中即時執行。當 Claude 遇到登入頁面或 CAPTCHA 時，它會暫停並要求您手動處理。

12 12

13<Note>13<Note>

14 Chrome 整合處於測試版，目前適用於 Google Chrome 和 Microsoft Edge。尚不支援 Brave、Arc 或其他基於 Chromium 的瀏覽器。也不支援 WSL（Windows Subsystem for Linux）。14 Chrome 整合適用於 Google Chrome 和 Microsoft Edge。尚不支援 Brave、Arc 或其他基於 Chromium 的瀏覽器。也不支援 Windows Subsystem for Linux (WSL)。

15</Note>15</Note>

16 16

17<h2 id="capabilities">17<h2 id="capabilities">

90 90

91網站級權限繼承自 Chrome 擴充功能。在 Chrome 擴充功能設定中管理權限，以控制 Claude 可以瀏覽、點擊和輸入的網站。91網站級權限繼承自 Chrome 擴充功能。在 Chrome 擴充功能設定中管理權限，以控制 Claude 可以瀏覽、點擊和輸入的網站。

92 92

93<h3 id="browser-tools-in-plan-mode">

94 計畫模式中的瀏覽器工具

95</h3>

97在 [計畫模式](/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 中，只讀取頁面或瀏覽器狀態的瀏覽器工具呼叫無需權限提示即可執行，而改變狀態的呼叫會提示批准。

99* **唯讀呼叫**：`read_page`、`get_page_text`、`find`、讀取主控台訊息或網路請求，以及擷取螢幕截圖

100* **改變狀態的呼叫**：點擊、輸入、導航、標籤和視窗管理，以及錄製 GIF

101

102自 v2.1.199 起，設定狀態改變輸入標誌的唯讀呼叫（例如 `tabs_context_mcp` 上的 `createIfEmpty`、主控台和網路讀取器上的 `clear`，或螢幕截圖上的 `save_to_disk`）也會提示批准。`browser_batch` 呼叫只有在其中的每個操作都是唯讀時，才會無提示執行。

103

93<h2 id="example-workflows">104<h2 id="example-workflows">

94 範例工作流程105 範例工作流程

95</h2>106</h2>

208 219

209第一次啟用 Chrome 整合時，Claude Code 會安裝原生訊息主機設定檔。Chrome 在啟動時讀取此檔案，因此如果擴充功能在您的第一次嘗試中未被偵測到，請重新啟動 Chrome 以取得新設定。220第一次啟用 Chrome 整合時，Claude Code 會安裝原生訊息主機設定檔。Chrome 在啟動時讀取此檔案，因此如果擴充功能在您的第一次嘗試中未被偵測到，請重新啟動 Chrome 以取得新設定。

210 221

222自 v2.1.199 起，Claude Code 會在第一次安裝時開啟瀏覽器標籤頁，提示您連接擴充功能。稍後重寫設定檔的工作階段（例如在切換 Claude Code 組建或設定目錄後）不會重新開啟它。

223

211如果連接仍然失敗，請驗證主機設定檔是否存在於：224如果連接仍然失敗，請驗證主機設定檔是否存在於：

212 225

213對於 Chrome：226對於 Chrome：

claude-apps-gateway-config.md +58 −7

Details

4 4

5# Claude 應用程式閘道設定5# Claude 應用程式閘道設定

6 6

~~7> 每個 gateway.yaml 選項的參考資料：監聽器和 TLS、OIDC、工作階段、Postgres 存放區、Bedrock/Agent Platform/Foundry 上游、模型路由、受管原則和遙測。~~7> 每個 gateway.yaml 選項的參考資料：監聽器和 TLS、OIDC、工作階段、Postgres 存放區、Bedrock/Claude Platform on AWS/Agent Platform/Foundry 上游、模型路由、受管原則和遙測。

8 8

9Claude 應用程式閘道部署由一個 YAML 檔案設定，按慣例稱為 `gateway.yaml`。該檔案定義閘道執行的所有操作：它在哪裡監聽、開發人員如何登入、推論去往何處，以及哪些原則和遙測適用。本頁是該檔案中每個選項的參考資料。若要撰寫您的第一個，請從[快速入門](/zh-TW/claude-apps-gateway#quickstart)開始，它會建立最小的工作設定並執行它；一旦您有了滿意的設定，[部署指南](/zh-TW/claude-apps-gateway-deploy)涵蓋將其容器化並在 Kubernetes、Cloud Run 或您自己的平台上託管。9Claude 應用程式閘道部署由一個 YAML 檔案設定，按慣例稱為 `gateway.yaml`。該檔案定義閘道執行的所有操作：它在哪裡監聽、開發人員如何登入、推論去往何處，以及哪些原則和遙測適用。本頁是該檔案中每個選項的參考資料。若要撰寫您的第一個，請從[快速入門](/zh-TW/claude-apps-gateway#quickstart)開始，它會建立最小的工作設定並執行它；一旦您有了滿意的設定，[部署指南](/zh-TW/claude-apps-gateway-deploy)涵蓋將其容器化並在 Kubernetes、Cloud Run 或您自己的平台上託管。

10 10

24* [`oidc`](#oidc)：您的身分識別提供者 (IdP)，包括簽發者、用戶端、宣告對應和誰可以登入24* [`oidc`](#oidc)：您的身分識別提供者 (IdP)，包括簽發者、用戶端、宣告對應和誰可以登入

25* [`session`](#session)：閘道鑄造的持有人令牌，包括祕密和生命週期25* [`session`](#session)：閘道鑄造的持有人令牌，包括祕密和生命週期

26* [`store`](#store)：PostgreSQL，用於裝置授權和速率限制計數器26* [`store`](#store)：PostgreSQL，用於裝置授權和速率限制計數器

~~27* [`upstreams`](#upstreams)：推論去往何處，無論是 Anthropic、Bedrock、Agent Platform 還是 Foundry~~27* [`upstreams`](#upstreams)：推論去往何處，無論是 Anthropic、Bedrock、Claude Platform on AWS、Agent Platform 還是 Foundry

28 28

29**選用部分：**29**選用部分：**

30 30

68 `oidc`68 `oidc`

69</h3>69</h3>

70 70

71OpenID Connect (OIDC) 是閘道與您的身分識別提供者一起使用的 SSO 協定；請參閱[身分識別提供者設定](/zh-TW/claude-apps-gateway-deploy#identity-provider-setup)以了解在 IdP 端註冊的內容。`oidc` 區塊將閘道連接到您的身分識別提供者，並決定誰可以登入。它命名簽發者和 OAuth 用戶端、對應攜帶電子郵件和群組的宣告，並按電子郵件網域或群組限制登入。71`oidc` 區塊將閘道連接到您的身分識別提供者，並決定誰可以登入。它命名簽發者和 OAuth 用戶端、對應攜帶電子郵件和群組的宣告，並按電子郵件網域或群組限制登入。

73OpenID Connect (OIDC) 是閘道與您的身分識別提供者一起使用的 SSO 協定；請參閱[身分識別提供者設定](/zh-TW/claude-apps-gateway-deploy#identity-provider-setup)以了解在 IdP 端註冊的內容。

72 74

73| 欄位 | 必需 | 說明 |75| 欄位 | 必需 | 說明 |

74| ------------------------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |76| ------------------------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

121 `upstreams`123 `upstreams`

122</h3>124</h3>

123 125

124`upstreams` 是一個有序清單。閘道將推論轉發到解析所請求模型的第一個上游。在 `5xx`、`429` 或逾時時，它會故障轉移到下一個；其他 `4xx` 不會，因為這些錯誤可歸因於請求而不是上游。相同提供者的多個上游必須設定不同的 `name:`。126`upstreams` 是一個有序清單。閘道將推論轉發到解析所請求模型的第一個上游。在 `5xx`、`429`、`401`、`403`、`404` 或逾時時，它會故障轉移到下一個；其他 `4xx` 不會，因為這些錯誤可歸因於請求而不是上游。`401` 或 `403` 表示閘道自己的認證對該上游失敗，`404` 表示該上游不服務所請求的模型，因此清單中稍後的上游仍然可以。

127

128相同提供者的多個上游必須設定不同的 `name:`。

125 129

126Bedrock、Agent Platform 和 Foundry 用戶端在啟動時建立一次，其 SDK 在內部重新整理認證，因此輪換雲認證不需要重新啟動。靜態 Anthropic API 金鑰和持有人在啟動時讀取；請參閱 [Anthropic API](#anthropic-api)。130Bedrock、Claude Platform on AWS、Agent Platform 和 Foundry 用戶端在啟動時建立一次，其 SDK 在內部重新整理認證，因此輪換雲認證不需要重新啟動。靜態 Anthropic API 金鑰和持有人在啟動時讀取；請參閱 [Anthropic API](#anthropic-api)。

127 131

128<h4 id="anthropic-api">132<h4 id="anthropic-api">

129 Anthropic API133 Anthropic API

193| 其他任何地方 | 透過 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_SESSION_TOKEN` 環境變數傳遞認證，或在 `auth:` 中使用 `${VAR}` 擴展明確設定它們 |197| 其他任何地方 | 透過 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY` 和 `AWS_SESSION_TOKEN` 環境變數傳遞認證，或在 `auth:` 中使用 `${VAR}` 擴展明確設定它們 |

194| 地區 | `region:` 是 API 端點地區。跨地區推論設定檔無論您選擇哪一個，都會跨地理位置 (US、EU、APAC) 路由。對於非美國地區或佈建輸送量 ARN，新增具有正確每上游 ID 的 [`models:`](#models) 區塊。 |198| 地區 | `region:` 是 API 端點地區。跨地區推論設定檔無論您選擇哪一個，都會跨地理位置 (US、EU、APAC) 路由。對於非美國地區或佈建輸送量 ARN，新增具有正確每上游 ID 的 [`models:`](#models) 區塊。 |

195 199

200<h4 id="claude-platform-on-aws">

201 Claude Platform on AWS

202</h4>

203

204Claude Platform on AWS 在 `aws-external-anthropic.<region>.api.aws` 的 AWS 基礎設施上服務第一方 Anthropic API。它使用第一方模型 ID，按原樣接受 `anthropic-beta` 標頭，並服務 `count_tokens`，因此 Bedrock 特定的轉譯都不適用。`anthropicAws` 提供者需要 Claude Code v2.1.198 或更新版本；較早的閘道版本在啟動時拒絕它。

205

206對於相同平台的用戶端部署，請參閱 [Claude Code on Claude Platform on AWS](/zh-TW/claude-platform-on-aws)。閘道端上游：

207

208```yaml theme={null}

209upstreams:

210 - provider: anthropicAws

211 region: us-east-1

212 workspace_id: wrkspc_...

213 auth:

214 api_key: ${ANTHROPIC_AWS_API_KEY} # 作為 x-api-key 傳送

215 # 或透過 AWS 預設認證鏈的 SigV4：

216 # auth: {}

217 # 或明確的 SigV4 認證：

218 # auth:

219 # aws_access_key_id: ${AWS_ACCESS_KEY_ID}

220 # aws_secret_access_key: ${AWS_SECRET_ACCESS_KEY}

221 # 覆蓋衍生的端點：

222 # base_url: https://aws-external-anthropic.us-east-1.api.aws

223```

224

225該平台在與 Amazon Bedrock 不同的 AWS 帳戶中執行，並為其自己的服務名稱 `aws-external-anthropic` 簽署 SigV4 請求，因此 Bedrock 範圍的 IAM 角色不授權它。`auth.api_key` 中的 API 金鑰在同時設定 SigV4 認證時優先。空的 `auth` 區塊使用 AWS SDK 的預設認證鏈，與 [Amazon Bedrock](#amazon-bedrock) 上游使用的相同鏈。

226

227| 欄位 | 必需 | 說明 |

228| ------------------------------------------------------- | -- | ------------------------------------------------------------------------------ |

229| `region` | 是 | AWS 地區，小寫字母、數字和連字號。閘道將端點衍生為 `https://aws-external-anthropic.<region>.api.aws`。 |

230| `workspace_id` | 是 | 在每個請求上傳送為標頭；平台需要它 |

231| `auth.api_key` | 否 | 平台的 API 金鑰，作為 `x-api-key` 傳送。不是持有人令牌：兩種驗證模式是 API 金鑰或 SigV4。 |

232| `auth.aws_access_key_id` / `auth.aws_secret_access_key` | 否 | 明確的 SigV4 認證。設定其中一個而不設定另一個在啟動時失敗。`auth.aws_session_token` 與它們一起被接受。 |

233| `base_url` | 否 | 覆蓋衍生的端點 |

234

235因為平台解析第一方模型 ID，內建目錄無需 [`models:`](#models) 區塊即可路由到它。當您策劃 `models:` 清單時，使用第一方 ID 鍵入 `anthropicAws:` 項目。

236

196<h4 id="google-cloud-agent-platform">237<h4 id="google-cloud-agent-platform">

197 Google Cloud Agent Platform238 Google Cloud Agent Platform

198</h4>239</h4>

255 296

256相同的提供者可以出現多次，具有不同的 `name:`。這涵蓋不同的地區、透過不同認證鏈的不同帳戶、佈建輸送量與隨需，以及跨提供者故障轉移。297相同的提供者可以出現多次，具有不同的 `name:`。這涵蓋不同的地區、透過不同認證鏈的不同帳戶、佈建輸送量與隨需，以及跨提供者故障轉移。

257 298

258閘道按順序嘗試上游。`5xx`、`429`、逾時和遺漏端點 (`501`) 故障轉移；其他 `4xx` 不會。`429` 是每個上游容量，因此佈建輸送量 (PT) 耗盡會故障轉移到隨需。無法解析所請求模型的上游會被跳過，無需網路往返。299閘道按順序嘗試上游。`5xx`、`429`、`401`、`403`、`404`、逾時和遺漏端點 (`501`) 故障轉移；其他 `4xx` 不會。

300

301`429` 是每個上游容量，因此佈建輸送量 (PT) 耗盡會故障轉移到隨需。`404` 是每個上游模型可用性，因此未啟用模型的上游不會阻止清單中稍後服務它的上游。無法解析所請求模型的上游會被跳過，無需網路往返。

259 302

260此範例首先路由佈建輸送量 Bedrock 配額，溢出到隨需和第二個帳戶，最後故障轉移到 Anthropic API：303此範例首先路由佈建輸送量 Bedrock 配額，溢出到隨需和第二個帳戶，最後故障轉移到 Anthropic API：

261 304

510* `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly`：當鎖定時，對應的允許清單跨來源聯合553* `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly`：當鎖定時，對應的允許清單跨來源聯合

511* [`allowAllClaudeAiMcps`](/zh-TW/settings#available-settings)：claude.ai MCP 伺服器允許清單的僅允許覆蓋554* [`allowAllClaudeAiMcps`](/zh-TW/settings#available-settings)：claude.ai MCP 伺服器允許清單的僅允許覆蓋

512* `sandbox.bwrapPath` 和 `sandbox.socatPath`：[沙箱](/zh-TW/sandboxing)幫助程式二進位檔的檔案系統路徑555* `sandbox.bwrapPath` 和 `sandbox.socatPath`：[沙箱](/zh-TW/sandboxing)幫助程式二進位檔的檔案系統路徑

556* [`forceRemoteSettingsRefresh`](/zh-TW/server-managed-settings)：阻止啟動直到遠端受管設定被新鮮擷取，因此設定它的 MDM 或檔案原則即使缺少該鍵的最高優先順序來源是快取遠端承載也被尊重

513 557

514`allowManagedPermissionRulesOnly` 和 `disableBypassPermissionsMode` 不是跨來源的，因此僅獲勝來源的值適用。558`allowManagedPermissionRulesOnly` 和 `disableBypassPermissionsMode` 不是跨來源的，因此僅獲勝來源的值適用。

515 559

581| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 未驗證裝置授權端點上的每 IP 速率限制。為在共享出口 IP 或 NAT 後面的大型組織提高。這些限制僅適用於裝置授權登入流程，不適用於 `/v1/messages` 推論。請參閱[使用者程式碼暴力破解抵抗](/zh-TW/claude-apps-gateway-deploy#user-code-brute-force-resistance)。 |625| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 未驗證裝置授權端點上的每 IP 速率限制。為在共享出口 IP 或 NAT 後面的大型組織提高。這些限制僅適用於裝置授權登入流程，不適用於 `/v1/messages` 推論。請參閱[使用者程式碼暴力破解抵抗](/zh-TW/claude-apps-gateway-deploy#user-code-brute-force-resistance)。 |

583 627

659 # region: us-east-1703 # region: us-east-1

660 # auth: {}704 # auth: {}

661 705

706 # - provider: anthropicAws

707 # region: us-east-1

708 # workspace_id: wrkspc_...

709 # auth:

710 # api_key: ${ANTHROPIC_AWS_API_KEY}

711

662 # - provider: vertex712 # - provider: vertex

663 # region: us-east5713 # region: us-east5

664 # project_id: example-prod714 # project_id: example-prod

675 upstream_model:725 upstream_model:

676 anthropic: claude-opus-4-8726 anthropic: claude-opus-4-8

677 # bedrock: us.anthropic.claude-opus-4-8727 # bedrock: us.anthropic.claude-opus-4-8

728 # anthropicAws: claude-opus-4-8

678 # vertex: claude-opus-4-8729 # vertex: claude-opus-4-8

679 # foundry: <your-opus-deployment-name>730 # foundry: <your-opus-deployment-name>

680 - id: claude-sonnet-4-6731 - id: claude-sonnet-4-6

claude-apps-gateway-deploy.md +1 −1

Details

97<Note>97<Note>

98 **工作負載身份**98 **工作負載身份**

99 99

100 優先選擇平台的工作負載身份而不是靜態金鑰：EKS 上的 IRSA 用於 Bedrock、GKE 上的工作負載身份用於 Agent Platform，以及 AKS 上的工作負載身份用於 Foundry。在上游區塊中設定 `auth: {}`，或對 Foundry 設定 `use_azure_ad: true`，閘道透過該提供者的預設認證鏈拾取 Pod 的身份。對於跨雲配對，例如 GKE 上的 Bedrock 上游，在上游的 `auth` 區塊中設定明確認證。[`upstreams` 參考](/zh-TW/claude-apps-gateway-config#upstreams) 有各平台設定詳情。100 優先選擇平台的工作負載身份而不是靜態金鑰：EKS 上的 IRSA 用於 Bedrock 和 AWS 上的 Claude Platform，GKE 上的工作負載身份用於 Agent Platform，以及 AKS 上的工作負載身份用於 Foundry。在上游區塊中設定 `auth: {}`，或對 Foundry 設定 `use_azure_ad: true`，閘道透過該提供者的預設認證鏈拾取 Pod 的身份。對於跨雲配對，例如 GKE 上的 Bedrock 上游，在上游的 `auth` 區塊中設定明確認證。[`upstreams` 參考](/zh-TW/claude-apps-gateway-config#upstreams) 有各平台設定詳情。

101</Note>101</Note>

102 102

103<h3 id="cloud-run">103<h3 id="cloud-run">

claude-code-on-the-web.md +2 −2

Details

723傳送在恢復工作階段之前檢查這些要求。如果任何要求未滿足，您會看到錯誤或被提示解決問題。723傳送在恢復工作階段之前檢查這些要求。如果任何要求未滿足，您會看到錯誤或被提示解決問題。

724 724

725| 要求 | 詳細資訊 |725| 要求 | 詳細資訊 |

726| ---------- | ---------------------------------- |726| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

727| 乾淨的 git 狀態 | 您的工作目錄必須沒有未提交的變更。如果需要，傳送會提示您隱藏變更。 |727| 乾淨的 git 狀態 | 您的工作目錄必須沒有未提交的變更。如果需要，傳送會提示您隱藏變更。 |

728| 正確的儲存庫 | 您必須從同一儲存庫的簽出執行 `--teleport`，而不是分支。 |728| 正確的儲存庫 | 您必須從同一儲存庫的簽出執行 `--teleport`，而不是分支。{/* min-version: 2.1.199 */}自 v2.1.199 起，Claude Code 接受簽出，即使它無法將遠端解析為主機名稱，例如 SSH 主機別名（如 `git@work:owner/repo.git`）或 `insteadOf` 重寫的短形式。它首先顯示確認提示，並且僅當遠端的擁有者和儲存庫名稱與工作階段的儲存庫相符時。 |

729| 分支可用 | 雲端工作階段中的分支必須已推送到遠端。傳送會自動取得並簽出它。 |729| 分支可用 | 雲端工作階段中的分支必須已推送到遠端。傳送會自動取得並簽出它。 |

730| 相同帳戶 | 您必須驗證到雲端工作階段中使用的相同 claude.ai 帳戶。 |730| 相同帳戶 | 您必須驗證到雲端工作階段中使用的相同 claude.ai 帳戶。 |

731 731

claude-platform-on-aws.md +1 −1

Details

230 230

231對於 CI 和自動化，給予執行器具有叫用 Anthropic 服務權限的 IAM 角色，並設定 `AWS_REGION`。認證鏈會自動選取該角色。231對於 CI 和自動化，給予執行器具有叫用 Anthropic 服務權限的 IAM 角色，並設定 `AWS_REGION`。認證鏈會自動選取該角色。

232 232

233如果您的 SSO 認證在工作階段中途過期，請設定 [`awsAuthRefresh`](/zh-TW/amazon-bedrock#advanced-credential-configuration)，以便 Claude Code 重新執行您的登入命令並重試，而不是失敗。將命令新增至您的 `settings.json`：233如果您的 SSO 認證在工作階段中途過期，請設定 [`awsAuthRefresh`](/zh-TW/amazon-bedrock#advanced-credential-configuration)，以便 Claude Code 重新執行您的登入命令並重試，而不是失敗。AWS 上的 Claude Platform 上的自動重新整理需要 Claude Code v2.1.198 或更新版本；較早的版本會停止並提示執行 `/login`，這無法重新整理 AWS 認證。將命令新增至您的 `settings.json`：

234 234

235```json theme={null}235```json theme={null}

236{236{

cli-reference.md +4 −2

Details

47 47

48如果您輸入錯誤的子命令，Claude Code 會建議最接近的匹配項並退出而不啟動工作階段。例如，`claude udpate` 會列印 `Did you mean claude update?`。48如果您輸入錯誤的子命令，Claude Code 會建議最接近的匹配項並退出而不啟動工作階段。例如，`claude udpate` 會列印 `Did you mean claude update?`。

49 49

50{/* min-version: 2.1.199 */}自 v2.1.199 起，`claude --dangerously-skip-permissions daemon <subcommand>` 執行 `daemon` 子命令。較早的版本將 `daemon <subcommand>` 視為新互動式工作階段的提示，因此當旗標在前面時子命令永遠不會執行，這是 `claude` 別名為包含該旗標時的常見設定。只有前導 `--dangerously-skip-permissions` 或 `--allow-dangerously-skip-permissions` 會以這種方式路由到 `daemon`；任何其他前導旗標仍會啟動互動式工作階段。

50<h2 id="cli-flags">52<h2 id="cli-flags">

51 CLI 旗標53 CLI 旗標

52</h2>54</h2>

66| `--ax-screen-reader` | {/* min-version: 2.1.181 */}呈現螢幕閱讀器友善的輸出：平面文字，無裝飾邊框或動畫。強制使用經典渲染器，因此 [`tui`](/zh-TW/settings#available-settings) 設定在工作階段中無效。優先於 [`CLAUDE_AX_SCREEN_READER`](/zh-TW/env-vars) 和 [`axScreenReader`](/zh-TW/settings#available-settings) 設定。需要 Claude Code v2.1.181 或更新版本 | `claude --ax-screen-reader` |68| `--ax-screen-reader` | {/* min-version: 2.1.181 */}呈現螢幕閱讀器友善的輸出：平面文字，無裝飾邊框或動畫。強制使用經典渲染器，因此 [`tui`](/zh-TW/settings#available-settings) 設定在工作階段中無效。優先於 [`CLAUDE_AX_SCREEN_READER`](/zh-TW/env-vars) 和 [`axScreenReader`](/zh-TW/settings#available-settings) 設定。需要 Claude Code v2.1.181 或更新版本 | `claude --ax-screen-reader` |

67| `--bare` | 最小模式：跳過 hooks、skills、plugins、MCP 伺服器、自動記憶體和 CLAUDE.md 的自動探索，以便指令碼呼叫啟動更快。Claude 可以存取 Bash、檔案讀取和檔案編輯工具。設定 [`CLAUDE_CODE_SIMPLE`](/zh-TW/env-vars)。請參閱 [bare mode](/zh-TW/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |69| `--bare` | 最小模式：跳過 hooks、skills、plugins、MCP 伺服器、自動記憶體和 CLAUDE.md 的自動探索，以便指令碼呼叫啟動更快。Claude 可以存取 Bash、檔案讀取和檔案編輯工具。設定 [`CLAUDE_CODE_SIMPLE`](/zh-TW/env-vars)。請參閱 [bare mode](/zh-TW/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |

69| `--bg`、`--background` | 以 [background agent](/zh-TW/agent-view) 身份啟動工作階段並立即返回。列印工作階段 ID 和管理命令。與 `--exec` 結合以執行 shell 命令作為背景工作而不是 Claude 工作階段，或與 `--agent` 結合以執行特定 subagent | `claude --bg "investigate the flaky test"` |71| `--bg`、`--background` | 以 [background agent](/zh-TW/agent-view) 身份啟動工作階段並立即返回。列印工作階段 ID 和管理命令。與 `--exec` 結合以執行 shell 命令作為背景工作而不是 Claude 工作階段，或與 `--agent` 結合以執行特定 subagent。{/* min-version: 2.1.198 */}無法與 `-p`/`--print` 結合；請參閱 [error reference](/zh-TW/errors#command-line-errors) | `claude --bg "investigate the flaky test"` |

70| `--channels` | （研究預覽）MCP 伺服器，其 [channel](/zh-TW/channels) 通知 Claude 應在此工作階段中監聽。以空格分隔的 `plugin:<name>@<marketplace>` 項目清單。需要 Claude.ai 驗證 | `claude --channels plugin:my-notifier@my-marketplace` |72| `--channels` | （研究預覽）MCP 伺服器，其 [channel](/zh-TW/channels) 通知 Claude 應在此工作階段中監聽。以空格分隔的 `plugin:<name>@<marketplace>` 項目清單。需要 Claude.ai 驗證 | `claude --channels plugin:my-notifier@my-marketplace` |

100| `--no-session-persistence` | 停用工作階段持久性，使工作階段不會儲存到磁碟且無法繼續。僅列印模式。[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-TW/env-vars) 環境變數在任何模式中執行相同操作 | `claude -p --no-session-persistence "query"` |102| `--no-session-persistence` | 停用工作階段持久性，使工作階段不會儲存到磁碟且無法繼續。僅列印模式。[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-TW/env-vars) 環境變數在任何模式中執行相同操作 | `claude -p --no-session-persistence "query"` |

102| `--permission-mode` | 以指定的 [permission mode](/zh-TW/permission-modes) 開始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk` 或 `bypassPermissions`。覆蓋設定檔案中的 `defaultMode` | `claude --permission-mode plan` |104| `--permission-mode` | 以指定的 [permission mode](/zh-TW/permission-modes) 開始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk` 或 `bypassPermissions`。覆蓋設定檔案中的 `defaultMode` | `claude --permission-mode plan` |

103| `--permission-prompt-tool` | 指定 MCP 工具以在非互動模式下處理權限提示 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |105| `--permission-prompt-tool` | 指定 MCP 工具以在非互動模式下處理權限提示。{/* min-version: 2.1.199 */}自 v2.1.199 起，提示工具無法核准標記為 [requiring user interaction](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具：一個的 `allow` 結果會轉換為拒絕 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

commands.md +10 −9

Details

10 10

11輸入 `/` 以查看所有可用命令，或輸入 `/` 後跟字母以篩選。11輸入 `/` 以查看所有可用命令，或輸入 `/` 後跟字母以篩選。

12 12

~~13命令只有在您的訊息開始時才會被識別。命令名稱後面的文字會作為引數傳遞給它。~~13命令只有在您的訊息開始時才會被識別。命令名稱後面的文字會作為引數傳遞給它。{/* min-version: 2.1.199 */}自 v2.1.199 起，[skills](/zh-TW/skills#pass-arguments-to-skills) 是例外：skill 調用後跟更多 skills，例如 `/skill-a /skill-b do XYZ`，會載入開始時命名的每個 skill，並將尾部文字作為引數傳遞給每個 skill。最多可以鏈接六個 skills。

14 14

15<h2 id="commands-across-a-typical-workflow">15<h2 id="commands-across-a-typical-workflow">

16 典型工作流程中的命令16 典型工作流程中的命令

18 18

19大多數命令在工作階段的特定時刻很有用，從設定專案到推送變更。19大多數命令在工作階段的特定時刻很有用，從設定專案到推送變更。

20 20

21**存放庫中的首次工作階段。** 執行 `/init` 以產生啟動程式 `CLAUDE.md`，然後執行 `/memory` 以精煉它。使用 `/mcp` 和 `/agents` 以設定專案需要的任何伺服器或子代理，並使用 `/permissions` 以設定您想要的批准規則。21**存放庫中的首次工作階段。** 執行 `/init` 以產生啟動程式 `CLAUDE.md`，然後執行 `/memory` 以精煉它。使用 `/mcp` 以設定專案需要的任何伺服器，要求 Claude 建立您想要的任何 [subagents](/zh-TW/sub-agents)，並執行 `/permissions` 以設定您的批准規則。

22 22

23**在工作期間。** `/plan` 在大型變更前切換到 Plan Mode。`/model` 和 `/effort` 調整您花費的推理量。當對話變得冗長時，`/context` 顯示視窗的去向，`/compact` 將其總結下來；使用 `/btw` 進行快速旁註，不應該膨脹歷史記錄。23**在工作期間。** `/plan` 在大型變更前切換到 Plan Mode。`/model` 和 `/effort` 調整您使用的模型以及它應用多少推理。當對話變得冗長時，`/context` 顯示視窗中填充的內容，`/compact` 將其總結以釋放空間。使用 `/btw` 進行快速旁註，不應該加入對話歷史記錄。

24 24

25**並行執行工作。** `/agents` 開啟管理員以管理 [subagents](/zh-TW/sub-agents) Claude 可以委派側邊任務，`/tasks` 列出目前工作階段背景中執行的內容。`/background` 分離整個工作階段以繼續作為 [background agent](/zh-TW/agent-view) 執行並釋放您的終端機。對於跨越程式碼庫的大型變更，`/batch` 將其分解為獨立單位，並在各自的 [worktree](/zh-TW/worktrees) 中執行每個單位。請參閱 [Run agents in parallel](/zh-TW/agents) 以了解這些方法如何相關。25**並行執行工作。** Claude 委派側邊任務給 [subagents](/zh-TW/sub-agents)，`/tasks` 列出目前工作階段背景中執行的內容。`/background` 分離整個工作階段以繼續作為 [background agent](/zh-TW/agent-view) 執行並釋放您的終端機。對於跨越程式碼庫的大型變更，`/batch` 將其分解為獨立單位，並在各自的 [worktree](/zh-TW/worktrees) 中執行每個單位。請參閱 [Run agents in parallel](/zh-TW/agents) 以了解這些方法如何相關。

26 26

27**在您推送前。** `/diff` 顯示變更的內容，`/code-review` 檢查差異以找出正確性錯誤和清理，並可以使用 `--fix` 應用發現的結果，`/review` 在 GitHub pull request 上執行相同的唯讀審查，`/security-review` 進行更深入的唯讀檢查。`/code-review ultra` 在雲端執行多代理審查。27**在您推送前。** `/diff` 顯示變更的內容，`/code-review` 檢查差異以找出正確性錯誤和清理，並可以使用 `--fix` 應用發現的結果，`/review` 在 GitHub pull request 上執行相同的唯讀審查，`/security-review` 進行更深入的唯讀檢查。`/code-review ultra` 在雲端執行多代理審查。

28 28

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

52| `/add-dir <path>` | 為目前工作階段期間的檔案存取添加工作目錄。大多數 `.claude/` 配置[未從添加的目錄發現](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍後使用 `--continue` 或 `--resume` 從添加的目錄繼續工作階段 |52| `/add-dir <path>` | 為目前工作階段期間的檔案存取添加工作目錄。大多數 `.claude/` 配置[未從添加的目錄發現](/zh-TW/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍後使用 `--continue` 或 `--resume` 從添加的目錄繼續工作階段 |

53| `/advisor [model\|off]` | {/* min-version: 2.1.98 */}啟用或停用[顧問工具](/zh-TW/advisor)，它在工作期間的關鍵時刻諮詢第二個模型以獲得指導。接受 `opus`、`sonnet`、`fable`（{/* min-version: 2.1.170 */}v2.1.170+）或完整的模型 ID。不帶引數時，開啟選擇器。需要 Claude Code v2.1.98 或更新版本 |53| `/advisor [model\|off]` | {/* min-version: 2.1.98 */}啟用或停用[顧問工具](/zh-TW/advisor)，它在工作期間的關鍵時刻諮詢第二個模型以獲得指導。接受 `opus`、`sonnet`、`fable`（{/* min-version: 2.1.170 */}v2.1.170+）或完整的模型 ID。不帶引數時，開啟選擇器。需要 Claude Code v2.1.98 或更新版本 |

54| `/agents` | 管理 [agent](/zh-TW/sub-agents) 配置 |54| `/agents` | {/* min-version: 2.1.198 */}自 v2.1.198 起，執行 `/agents` 會列印提醒，要求您詢問 Claude 以建立或管理 [subagents](/zh-TW/sub-agents)，或直接編輯 `.claude/agents/` 或 `~/.claude/agents/`。{/* max-version: 2.1.197 */}在 v2.1.197 及更早版本上，開啟互動式介面以建立和管理 subagent 配置 |

55| `/autofix-pr [prompt]` | 生成一個[網頁上的 Claude Code](/zh-TW/claude-code-on-the-web#auto-fix-pull-requests) 工作階段，監視目前分支的 PR 並在 CI 失敗或審閱者留下評論時推送修復。使用 `gh pr view` 檢測已簽出分支的開放 PR；若要監視不同的 PR，請先簽出其分支。預設情況下，遠端工作階段被告知修復每個 CI 失敗和審閱評論；傳遞提示以給予它不同的指示，例如 `/autofix-pr only fix lint and type errors`。需要 `gh` CLI 和訪問[網頁上的 Claude Code](/zh-TW/claude-code-on-the-web) |55| `/autofix-pr [prompt]` | 生成一個[網頁上的 Claude Code](/zh-TW/claude-code-on-the-web#auto-fix-pull-requests) 工作階段，監視目前分支的 PR 並在 CI 失敗或審閱者留下評論時推送修復。使用 `gh pr view` 檢測已簽出分支的開放 PR；若要監視不同的 PR，請先簽出其分支。預設情況下，遠端工作階段被告知修復每個 CI 失敗和審閱評論；傳遞提示以給予它不同的指示，例如 `/autofix-pr only fix lint and type errors`。需要 `gh` CLI 和訪問[網頁上的 Claude Code](/zh-TW/claude-code-on-the-web) |

56| `/background [prompt]` | 分離目前的工作階段以作為[背景 agent](/zh-TW/agent-view) 運行並釋放此終端機。傳遞提示以在分離前發送一個額外的指示。使用 `claude agents` 監視工作階段。別名：`/bg` |56| `/background [prompt]` | 分離目前的工作階段以作為[背景 agent](/zh-TW/agent-view) 運行並釋放此終端機。傳遞提示以在分離前發送一個額外的指示。使用 `claude agents` 監視工作階段。別名：`/bg` |

57| `/batch <instruction>` | **[Skill](/zh-TW/skills#bundled-skills).** 在整個程式碼庫中並行協調大規模變更。研究程式碼庫，將工作分解為 5 到 30 個獨立單位，並呈現計劃。獲得批准後，在隔離的 [git worktree](/zh-TW/worktrees) 中為每個單位生成一個背景 subagent。每個 subagent 實現其單位、運行測試並開啟 pull request。需要 git 存放庫。示例：`/batch migrate src/ from Solid to React` |57| `/batch <instruction>` | **[Skill](/zh-TW/skills#bundled-skills).** 在整個程式碼庫中並行協調大規模變更。研究程式碼庫，將工作分解為 5 到 30 個獨立單位，並呈現計劃。獲得批准後，在隔離的 [git worktree](/zh-TW/worktrees) 中為每個單位生成一個背景 subagent。每個 subagent 實現其單位、運行測試並開啟 pull request。需要 git 存放庫。示例：`/batch migrate src/ from Solid to React` |

68| `/context [all]` | 將目前的上下文使用情況視覺化為彩色網格。顯示上下文繁重工具、記憶體膨脹和容量警告的最佳化建議。在[全螢幕模式](/zh-TW/fullscreen)中，每個項目的分解會折疊以保持網格可見。傳遞 `all` 以展開它 |68| `/context [all]` | 將目前的上下文使用情況視覺化為彩色網格。顯示上下文繁重工具、記憶體膨脹和容量警告的最佳化建議。在[全螢幕模式](/zh-TW/fullscreen)中，每個項目的分解會折疊以保持網格可見。傳遞 `all` 以展開它 |

69| `/copy [N]` | 將最後一個助手回應複製到剪貼簿。傳遞數字 `N` 以複製第 N 個最新回應：`/copy 2` 複製倒數第二個。當存在程式碼區塊時，顯示互動式選擇器以選擇個別區塊或完整回應。在選擇器中按 `w` 以將選擇寫入檔案而不是剪貼簿，這在 SSH 上很有用 |69| `/copy [N]` | 將最後一個助手回應複製到剪貼簿。傳遞數字 `N` 以複製第 N 個最新回應：`/copy 2` 複製倒數第二個。當存在程式碼區塊時，顯示互動式選擇器以選擇個別區塊或完整回應。在選擇器中按 `w` 以將選擇寫入檔案而不是剪貼簿，這在 SSH 上很有用 |

71| `/dataviz [request]` | **[Skill](/zh-TW/skills#bundled-skills).** 圖表、圖形和儀表板的設計指導。Claude 為資料選擇圖表形式，按角色分配顏色，使用捆綁的指令碼驗證調色盤以確保色盲安全和對比度，並應用標記、互動和無障礙規則。使用品牌中立的佔位符調色盤，您可以用自己的調色盤替換。{/* min-version: 2.1.198 */}需要 Claude Code v2.1.198 或更新版本 |

71| `/debug [description]` | **[Skill](/zh-TW/skills#bundled-skills).** 為目前工作階段啟用偵錯日誌記錄並通過讀取工作階段偵錯日誌來排除故障。除非您使用 `claude --debug` 啟動，否則偵錯日誌記錄預設為關閉，因此在工作階段中期運行 `/debug` 會從該時刻開始捕獲日誌。可選擇性地描述問題以集中分析 |72| `/debug [description]` | **[Skill](/zh-TW/skills#bundled-skills).** 為目前工作階段啟用偵錯日誌記錄並通過讀取工作階段偵錯日誌來排除故障。除非您使用 `claude --debug` 啟動，否則偵錯日誌記錄預設為關閉，因此在工作階段中期運行 `/debug` 會從該時刻開始捕獲日誌。可選擇性地描述問題以集中分析 |

74| `/design-sync [hint]` | **[Skill](/zh-TW/skills#bundled-skills).** 轉換您的存放庫的 React 設計系統並將其上傳到 [Claude Design](https://claude.ai/design)，以便它產生的設計使用您的真實元件。可選擇性地命名設計系統，例如 `/design-sync Acme DS`。首次同步會驗證每個元件，在大型存放庫上可能需要幾個小時。在 Anthropic API 上可用；在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，基礎工具無法到達 claude.ai，因此命令不可用 |75| `/design-sync [hint]` | **[Skill](/zh-TW/skills#bundled-skills).** 轉換您的存放庫的 React 設計系統並將其上傳到 [Claude Design](https://claude.ai/design)，以便它產生的設計使用您的真實元件。可選擇性地命名設計系統，例如 `/design-sync Acme DS`。首次同步會驗證每個元件，在大型存放庫上可能需要幾個小時。在 Anthropic API 上可用；在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，基礎工具無法到達 claude.ai，因此命令不可用 |

76| `/diff` | 開啟互動式差異檢視器，顯示未提交的變更和每個回合的差異。使用左/右箭頭在目前的 git 差異和個別 Claude 回合之間切換，使用上/下箭頭瀏覽檔案 |77| `/diff` | 開啟互動式差異檢視器，顯示未提交的變更和每個回合的差異。使用左/右箭頭在目前的 git 差異和個別 Claude 回合之間切換，使用上/下箭頭瀏覽檔案。{/* min-version: 2.1.198 */}自 v2.1.198 起，開啟的檢視器也會在存放庫的 git 狀態在工作階段外變更時自動重新整理，例如在另一個終端機中進行分支切換或提交 |

78| `/effort [level\|auto]` | 設定模型[努力程度](/zh-TW/model-config#adjust-effort-level)。接受 `low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`；可用的程度取決於模型，`max` 和 `ultracode` 僅限工作階段。`ultracode` 是一個 Claude Code 設定，結合 `xhigh` 推理與自動[工作流](/zh-TW/workflows#let-claude-decide-with-ultracode)協調。`auto` 重設為模型預設值。不帶引數時，開啟互動式滑塊；使用左右箭頭選擇程度，按 `Enter` 應用。立即生效，無需等待目前回應完成 |79| `/effort [level\|auto]` | 設定模型[努力程度](/zh-TW/model-config#adjust-effort-level)。接受 `low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`；可用的程度取決於模型，`max` 和 `ultracode` 僅限工作階段。`ultracode` 是一個 Claude Code 設定，結合 `xhigh` 推理與自動[工作流](/zh-TW/workflows#let-claude-decide-with-ultracode)協調。`auto` 重設為模型預設值。不帶引數時，開啟互動式滑塊；使用左右箭頭選擇程度，按 `Enter` 應用。立即生效，無需等待目前回應完成 |

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

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

84| `/focus` | 切換焦點檢視，僅顯示您的最後一個提示、帶有編輯 diffstats 的單行工具呼叫摘要和最終回應。選擇在工作階段之間保持。僅在[全螢幕渲染](/zh-TW/fullscreen)中可用 |85| `/focus` | 切換焦點檢視，僅顯示您的最後一個提示、帶有編輯 diffstats 的單行工具呼叫摘要和最終回應。{/* min-version: 2.1.198 */}自 v2.1.198 起，工具呼叫摘要也會計算在回合中啟動的 subagents 數量，並將已完成的背景工作通知折疊為單一計數。選擇在工作階段之間保持；設定設定中的 [`viewMode`](/zh-TW/settings#available-settings) 以覆蓋它。僅在[全螢幕渲染](/zh-TW/fullscreen)中可用 |

85| `/fork <directive>` | {/* min-version: 2.1.161 */}生成一個[分叉的 subagent](/zh-TW/sub-agents#fork-the-current-conversation)：一個背景 subagent，繼承完整的對話並在指令上工作，同時您繼續進行。其結果在完成時返回到您的對話。若要自己切換到對話的副本，請使用 `/branch`。在 v2.1.161 之前，`/fork` 是 `/branch` 的別名 |86| `/fork <directive>` | {/* min-version: 2.1.161 */}生成一個[分叉的 subagent](/zh-TW/sub-agents#fork-the-current-conversation)：一個背景 subagent，繼承完整的對話並在指令上工作，同時您繼續進行。其結果在完成時返回到您的對話。若要自己切換到對話的副本，請使用 `/branch`。在 v2.1.161 之前，`/fork` 是 `/branch` 的別名 |

87| `/heapdump` | 將 JavaScript 堆快照和記憶體分解寫入 `~/Desktop`，或在沒有 Desktop 資料夾的 Linux 上寫入您的主目錄，以診斷高記憶體使用情況。請參閱[故障排除](/zh-TW/troubleshooting#high-cpu-or-memory-usage) |88| `/heapdump` | 將 JavaScript 堆快照和記憶體分解寫入 `~/Desktop`，或在沒有 Desktop 資料夾的 Linux 上寫入您的主目錄，以診斷高記憶體使用情況。請參閱[故障排除](/zh-TW/troubleshooting#high-cpu-or-memory-usage) |

127| `/setup-bedrock` | 通過互動式精靈配置 [Amazon Bedrock](/zh-TW/amazon-bedrock) 驗證、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_BEDROCK=1` 時可見。首次 Bedrock 使用者也可以從登入螢幕訪問此精靈 |128| `/setup-bedrock` | 通過互動式精靈配置 [Amazon Bedrock](/zh-TW/amazon-bedrock) 驗證、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_BEDROCK=1` 時可見。首次 Bedrock 使用者也可以從登入螢幕訪問此精靈 |

128| `/setup-vertex` | 通過互動式精靈配置 [Google Vertex AI](/zh-TW/google-vertex-ai) 驗證、專案、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_VERTEX=1` 時可見。首次 Vertex AI 使用者也可以從登入螢幕訪問此精靈 |129| `/setup-vertex` | 通過互動式精靈配置 [Google Vertex AI](/zh-TW/google-vertex-ai) 驗證、專案、區域和模型釘選。僅在設定 `CLAUDE_CODE_USE_VERTEX=1` 時可見。首次 Vertex AI 使用者也可以從登入螢幕訪問此精靈 |

129| `/simplify [target]` | {/* min-version: 2.1.154 */}**[Skill](/zh-TW/skills#bundled-skills).** 審閱變更的程式碼以查找清理機會並應用修復。四個審閱 [agents](/zh-TW/sub-agents) 並行運行，涵蓋現有幫助程式的重用、簡化、效率和變更是否位於正確的抽象層級。從 v2.1.154 開始，審閱不尋找正確性錯誤。使用 `/code-review` 查找錯誤。在較早的版本上，`/simplify` 等同於 `/code-review --fix`。傳遞路徑或 PR 參考以審閱特定目標 |130| `/simplify [target]` | {/* min-version: 2.1.154 */}**[Skill](/zh-TW/skills#bundled-skills).** 審閱變更的程式碼以查找清理機會並應用修復。四個審閱 [agents](/zh-TW/sub-agents) 並行運行，涵蓋現有幫助程式的重用、簡化、效率和變更是否位於正確的抽象層級。從 v2.1.154 開始，審閱不尋找正確性錯誤。使用 `/code-review` 查找錯誤。在較早的版本上，`/simplify` 等同於 `/code-review --fix`。傳遞路徑或 PR 參考以審閱特定目標 |

130| `/skills` | 列出可用的 [skills](/zh-TW/skills)。按 `t` 按 token 計數排序。按 `Space` 以[從 Claude 或 `/` 選單隱藏 skill](/zh-TW/skills#override-skill-visibility-from-settings)，然後按 `Enter` 以儲存 |131| `/skills` | 列出可用的 [skills](/zh-TW/skills)。{/* min-version: 2.1.121 */}自 v2.1.121 起，輸入以按名稱篩選清單。按 `t` 按 token 計數排序。按 `Space` 以[從 Claude 或 `/` 選單隱藏 skill](/zh-TW/skills#override-skill-visibility-from-settings)，然後按 `Enter` 以儲存 |

context-window.md +1 −1

Details

1587 壓縮後的存活內容1587 壓縮後的存活內容

1588</h2>1588</h2>

1589 1589

1590當長會話壓縮時，Claude Code 會總結對話歷史以適應上下文視窗。您的指令會發生什麼取決於它們的加載方式：1590當長會話壓縮時，Claude Code 會總結對話歷史以適應上下文視窗。{/* min-version: 2.1.198 */}自 v2.1.198 起，總結請求會繼承您的會話的[延伸思考](/zh-TW/model-config#extended-thinking)配置，因此當您的會話啟用思考時，它會在啟用思考的情況下進行推理，否則保持關閉。思考只會影響摘要的生成方式；您的會話設定在之後保持不變。您的指令會發生什麼取決於它們的加載方式：

1591 1591

1592| 機制 | 壓縮後 |1592| 機制 | 壓縮後 |

1593| :-------------------------- | :------------------------------------------- |1593| :-------------------------- | :------------------------------------------- |

costs.md +2 −2

Details

170 </Tab>170 </Tab>

171 171

172 <Tab title="filter-test-output.sh">172 <Tab title="filter-test-output.sh">

173 hook 呼叫此指令碼，該指令碼檢查命令是否為測試執行器並修改它以僅顯示失敗：173 hook 呼叫此指令碼。建立資料夾，使用 `mkdir -p ~/.claude/hooks`，將下面的指令碼儲存為 `~/.claude/hooks/filter-test-output.sh`，並使用 `chmod +x ~/.claude/hooks/filter-test-output.sh` 使其可執行。它檢查命令是否為測試執行器並修改它以僅顯示失敗：

174 174

175 ```bash theme={null}175 ```bash theme={null}

176 #!/bin/bash176 #!/bin/bash

198 調整延伸思考198 調整延伸思考

199</h3>199</h3>

200 200

201延伸思考預設為啟用，因為它可以顯著改善複雜規劃和推理任務的效能。思考 token 會作為輸出 token 計費，預設預算可能是每個請求數萬個 token，取決於模型。對於不需要深度推理的較簡單任務，您可以透過在 `/effort` 中降低[努力等級](/zh-TW/model-config#adjust-effort-level)或在 `/model` 中降低、在 `/config` 中停用思考，或在具有[固定思考預算](/zh-TW/model-config#adaptive-reasoning-and-fixed-thinking-budgets)的模型上，透過 `MAX_THINKING_TOKENS=8000` 降低預算來降低成本。自適應推理模型會忽略非零預算，因此請改用努力等級。Fable 5 上無法停用思考，它始終使用延伸思考。201延伸思考預設為啟用，因為它可以顯著改善複雜規劃和推理任務的效能。思考 token 會作為輸出 token 計費，預設預算可能是每個請求數萬個 token，取決於模型。對於不需要深度推理的較簡單任務，您可以透過在 `/effort` 中降低[努力等級](/zh-TW/model-config#adjust-effort-level)或在 `/model` 中降低、在 `/config` 中停用思考，或在具有[固定思考預算](/zh-TW/model-config#adaptive-reasoning-and-fixed-thinking-budgets)的模型上，透過設定 `MAX_THINKING_TOKENS` [環境變數](/zh-TW/env-vars)（例如 `MAX_THINKING_TOKENS=8000`）來降低預算，以降低成本。自適應推理模型會忽略非零預算，因此請改用努力等級。Fable 5 上無法停用思考，它始終使用延伸思考。

202 202

203<h3 id="delegate-verbose-operations-to-subagents">203<h3 id="delegate-verbose-operations-to-subagents">

204 將詳細操作委派給 subagents204 將詳細操作委派給 subagents

debug-your-config.md +1 −2

Details

14 查看載入到 context 的內容14 查看載入到 context 的內容

15</h2>15</h2>

16 16

17`/context` 命令顯示佔用目前工作階段 context 視窗的所有內容，按類別細分：系統提示、記憶檔案、skills、MCP tools 和對話訊息。首先執行它以確認您的 `CLAUDE.md`、規則或 skill 描述是否存在。17`/context` 命令顯示佔用目前工作階段 context 視窗的所有內容，按類別細分：系統提示、記憶檔案、skills、自訂子代理及其載入來源、MCP tools 和對話訊息。首先執行它以確認您的 `CLAUDE.md`、規則或 skill 描述是否存在。

18 18

19如需特定類別的詳細資訊，請使用專用命令進行後續操作：19如需特定類別的詳細資訊，請使用專用命令進行後續操作：

20 20

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

23| `/memory` | 載入了哪些 `CLAUDE.md` 和規則檔案，加上自動記憶項目 |23| `/memory` | 載入了哪些 `CLAUDE.md` 和規則檔案，加上自動記憶項目 |

24| `/skills` | 來自專案、使用者和外掛程式來源的可用 skills |24| `/skills` | 來自專案、使用者和外掛程式來源的可用 skills |

~~25| `/agents` | 已設定的子代理及其設定 |~~

26| `/hooks` | 作用中的 hook 設定 |25| `/hooks` | 作用中的 hook 設定 |

27| `/mcp` | 已連線的 MCP servers 及其狀態 |26| `/mcp` | 已連線的 MCP servers 及其狀態 |

28| `/permissions` | 目前生效的已解析允許和拒絕規則 |27| `/permissions` | 目前生效的已解析允許和拒絕規則 |

desktop.md +1 −1

Details

829* **Linux (beta)**：Linux 桌面應用程式中尚未提供電腦使用。請參閱 [Claude Desktop on Linux](/zh-TW/desktop-linux)。829* **Linux (beta)**：Linux 桌面應用程式中尚未提供電腦使用。請參閱 [Claude Desktop on Linux](/zh-TW/desktop-linux)。

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

831* **Agent teams**：平行 Claude Code 會話相互傳遞訊息，可在 [CLI](/zh-TW/agent-teams) 中使用，不在 Desktop 中。若要在一個會話內進行多代理工作，請使用 [dynamic workflows](/zh-TW/workflows)，它們在 Desktop 中執行。831* **Agent teams**：平行 Claude Code 會話相互傳遞訊息，可在 [CLI](/zh-TW/agent-teams) 中使用，不在 Desktop 中。若要在一個會話內進行多代理工作，請使用 [dynamic workflows](/zh-TW/workflows)，它們在 Desktop 中執行。

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

833 833

834<h2 id="troubleshooting">834<h2 id="troubleshooting">

835 疑難排解835 疑難排解

env-vars.md +32 −21

Details

102| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，在 AWS 主控台中產生。作為 `x-api-key` 發送，優先於 AWS SigV4 |102| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 的工作區 API 金鑰，在 AWS 主控台中產生。作為 `x-api-key` 發送，優先於 AWS SigV4 |

103| `ANTHROPIC_AWS_BASE_URL` | 覆蓋 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 端點 URL。用於自訂區域或透過 [LLM gateway](/zh-TW/llm-gateway) 路由。預設為 `https://aws-external-anthropic.{AWS_REGION}.api.aws` |103| `ANTHROPIC_AWS_BASE_URL` | 覆蓋 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 端點 URL。用於自訂區域或透過 [LLM gateway](/zh-TW/llm-gateway) 路由。預設為 `https://aws-external-anthropic.{AWS_REGION}.api.aws` |

104| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 所需。在每個請求上作為 `anthropic-workspace-id` 標頭發送 |104| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 所需。在每個請求上作為 `anthropic-workspace-id` 標頭發送 |

105| `ANTHROPIC_BASE_URL` | 覆蓋 API 端點以透過代理或閘道路由請求。設定為非第一方主機時，[MCP tool search](/zh-TW/mcp#scale-with-mcp-tool-search) 預設停用。如果您的代理轉發 `tool_reference` 區塊，請設定 `ENABLE_TOOL_SEARCH=true` |105| `ANTHROPIC_BASE_URL` | 覆蓋 API 端點以透過代理或閘道路由請求。設定為非第一方主機時，[MCP tool search](/zh-TW/mcp#scale-with-mcp-tool-search) 預設停用。如果您的代理轉發 `tool_reference` 區塊，請設定 `ENABLE_TOOL_SEARCH=true`。{/* min-version: 2.1.196 */}自 v2.1.196 起，當此項指向 `api.anthropic.com` 以外的主機時，[Remote Control](/zh-TW/remote-control#requirements) 會停用，符合其在 Bedrock、Vertex AI 和 Foundry 上的行為 |

106| `ANTHROPIC_BEDROCK_BASE_URL` | 覆蓋 Bedrock 端點 URL。用於自訂 Bedrock 端點或透過 [LLM gateway](/zh-TW/llm-gateway) 路由。請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock) |106| `ANTHROPIC_BEDROCK_BASE_URL` | 覆蓋 Bedrock 端點 URL。用於自訂 Bedrock 端點或透過 [LLM gateway](/zh-TW/llm-gateway) 路由。請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock) |

107| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆蓋 Bedrock Mantle 端點 URL。請參閱 [Mantle endpoint](/zh-TW/amazon-bedrock#use-the-mantle-endpoint) |107| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆蓋 Bedrock Mantle 端點 URL。請參閱 [Mantle endpoint](/zh-TW/amazon-bedrock#use-the-mantle-endpoint) |

108| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Bedrock [service tier](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作為 `X-Amzn-Bedrock-Service-Tier` 標頭發送。請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock#service-tiers) |108| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Bedrock [service tier](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作為 `X-Amzn-Bedrock-Service-Tier` 標頭發送。請參閱 [Amazon Bedrock](/zh-TW/amazon-bedrock#service-tiers) |

146| `CCR_FORCE_BUNDLE` | 設定為 `1` 以強制 [`claude --remote`](/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 在 GitHub 存取可用時也要捆綁並上傳您的本機儲存庫 |146| `CCR_FORCE_BUNDLE` | 設定為 `1` 以強制 [`claude --remote`](/zh-TW/claude-code-on-the-web#send-local-repositories-without-github) 在 GitHub 存取可用時也要捆綁並上傳您的本機儲存庫 |

147| `CLAUDECODE` | 在 Claude Code 生成的子程序中設定為 `1`（Bash 和 PowerShell 工具、tmux 工作階段、[hook](/zh-TW/hooks) 命令、[status line](/zh-TW/statusline) 命令、stdio [MCP server](/zh-TW/mcp) 子程序）。IDE 擴充功能也在其整合終端中設定此項。用於偵測指令碼何時在 Claude Code 生成的子程序內執行。若要檢查目前程序是否由工具呼叫或 hook 直接生成，而不是在 Claude Code 啟動的 stdio MCP 伺服器內，請改用 `CLAUDE_CODE_CHILD_SESSION` |147| `CLAUDECODE` | 在 Claude Code 生成的子程序中設定為 `1`（Bash 和 PowerShell 工具、tmux 工作階段、[hook](/zh-TW/hooks) 命令、[status line](/zh-TW/statusline) 命令、stdio [MCP server](/zh-TW/mcp) 子程序）。IDE 擴充功能也在其整合終端中設定此項。用於偵測指令碼何時在 Claude Code 生成的子程序內執行。若要檢查目前程序是否由工具呼叫或 hook 直接生成，而不是在 Claude Code 啟動的 stdio MCP 伺服器內，請改用 `CLAUDE_CODE_CHILD_SESSION` |

148| `CLAUDE_AFK_COUNTDOWN_MS` | {/* min-version: 2.1.198 */}在未回答的 `AskUserQuestion` 對話框上自動繼續前，螢幕上倒數計時出現前的毫秒數。預設 `20000`（20 秒）。請參閱 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更新版本 |

149| `CLAUDE_AFK_TIMEOUT_MS` | {/* min-version: 2.1.198 */}在未回答的 [`AskUserQuestion`](/zh-TW/tools-reference) 對話框自動繼續前的閒置時間（以毫秒為單位）。預設 `60000`（60 秒）。若要在您離開時保持問題開啟，請設定大值，例如 `86400000`（24 小時）。設定 `0` 不會關閉逾時；它會立即關閉對話框。需要 Claude Code v2.1.198 或更新版本 |

148| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設定為 `1` 以停用所有內建 [subagent](/zh-TW/sub-agents) 類型，例如 Explore 和 Plan。僅適用於非互動式模式（`-p` 旗標）。對於想要空白狀態的 SDK 使用者很有用 |150| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 設定為 `1` 以停用所有內建 [subagent](/zh-TW/sub-agents) 類型，例如 Explore 和 Plan。僅適用於非互動式模式（`-p` 旗標）。對於想要空白狀態的 SDK 使用者很有用 |

150| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 背景 subagents 的停滯逾時（以毫秒為單位）。預設 `600000`（10 分鐘）。計時器在每個串流進度事件時重設；如果在視窗內沒有進度到達，subagent 會被中止，任務會標記為失敗，將任何部分結果呈現給父級 |152| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 背景 subagents 的停滯逾時（以毫秒為單位）。預設 `600000`（10 分鐘）。計時器在每個串流進度事件時重設；如果在視窗內沒有進度到達，subagent 會被中止，任務會標記為失敗，將任何部分結果呈現給父級 |

151| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定自動壓縮觸發的上下文容量百分比 (1-100)。使用較低的值（如 `50`）以更早進行壓縮。此變數僅在 Claude Code 主動進行壓縮時導致更早壓縮：當設定 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 時、在 [cloud sessions](/zh-TW/claude-code-on-the-web) 中、在沒有 [extended context](/zh-TW/model-config#extended-context) 的 Sonnet 4.6 和 Opus 4.6 上，預設在 200K 邊界進行壓縮。在其他情況下，例如本機工作階段，當對話達到模型的上下文限制時，自動壓縮觸發。覆蓋只能降低閾值，因此高於預設值的值無效。適用於主要對話和 subagents |153| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 設定自動壓縮觸發的上下文容量百分比 (1-100)。使用較低的值（如 `50`）以更早進行壓縮。此變數僅在 Claude Code 主動進行壓縮時導致更早壓縮：當設定 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 時、在 [cloud sessions](/zh-TW/claude-code-on-the-web) 中、在沒有 [extended context](/zh-TW/model-config#extended-context) 的 Sonnet 4.6 和 Opus 4.6 上，預設在 200K 邊界進行壓縮。在 Sonnet 5 上，proactive compaction 在模型的 [default threshold](/zh-TW/model-config#sonnet-5-context-window) 處應用。在其他情況下，例如本機工作階段上的 Opus 4.8，當對話達到模型的上下文限制時，自動壓縮觸發。覆蓋只能降低閾值，因此高於預設值的值無效。適用於主要對話和 subagents |

153| `CLAUDE_AX_SCREEN_READER` | {/* min-version: 2.1.181 */}設定為 `1` 以呈現螢幕閱讀器友善的輸出：沒有裝飾邊框或動畫的平面文字。設定為 `0` 以強制關閉螢幕閱讀器模式，即使 [`axScreenReader`](/zh-TW/settings#available-settings) 為 `true`。[`--ax-screen-reader`](/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 |155| `CLAUDE_AX_SCREEN_READER` | {/* min-version: 2.1.181 */}設定為 `1` 以呈現螢幕閱讀器友善的輸出：沒有裝飾邊框或動畫的平面文字。設定為 `0` 以強制關閉螢幕閱讀器模式，即使 [`axScreenReader`](/zh-TW/settings#available-settings) 為 `true`。[`--ax-screen-reader`](/zh-TW/cli-reference#cli-flags) 旗標優先。需要 Claude Code v2.1.181 或更新版本 |

162| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設定為 `0` 以省略系統提示開始處的歸屬區塊（用戶端版本和提示指紋）。停用它會改善透過 [LLM gateway](/zh-TW/llm-gateway) 路由時的提示快取命中率。Anthropic API 快取不受影響 |164| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 設定為 `0` 以省略系統提示開始處的歸屬區塊（用戶端版本和提示指紋）。停用它會改善透過 [LLM gateway](/zh-TW/llm-gateway) 路由時的提示快取命中率。Anthropic API 快取不受影響 |

163| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 設定用於自動壓縮計算的上下文容量（以 token 為單位）。預設為模型的上下文視窗：標準模型為 200K 或 [extended context](/zh-TW/model-config#extended-context) 模型為 1M。在 1M 模型上使用較低的值（如 `500000`）以將視窗視為 500K 用於壓縮目的。該值上限為模型的實際上下文視窗。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 作為此值的百分比應用。設定此變數會將壓縮閾值與狀態行的 `used_percentage` 解耦，後者始終使用模型的完整上下文視窗 |165| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 設定用於自動壓縮計算的上下文容量（以 token 為單位）。預設為模型的上下文視窗：標準模型為 200K 或 [extended context](/zh-TW/model-config#extended-context) 模型為 1M。在 1M 模型上使用較低的值（如 `500000`）以將視窗視為 500K 用於壓縮目的。該值上限為模型的實際上下文視窗。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 作為此值的百分比應用。設定此變數會將壓縮閾值與狀態行的 `used_percentage` 解耦，後者始終使用模型的完整上下文視窗 |

164| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆蓋自動 [IDE connection](/zh-TW/vs-code)。預設情況下，在支援的 IDE 的整合終端內啟動時，Claude Code 會自動連線。設定為 `false` 以防止此情況。設定為 `true` 以在自動偵測失敗時強制連線嘗試，例如當 tmux 遮蔽父終端時。優先於 [`autoConnectIde`](/zh-TW/settings#global-config-settings) 全域配置設定 |166| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆蓋自動 [IDE connection](/zh-TW/vs-code)。預設情況下，在支援的 IDE 的整合終端內啟動時，Claude Code 會自動連線。設定為 `false` 以防止此情況。設定為 `true` 以在自動偵測失敗時強制連線嘗試，例如當 tmux 遮蔽父終端時。優先於 [`autoConnectIde`](/zh-TW/settings#global-config-settings) 全域配置設定 |

165| `CLAUDE_CODE_CERT_STORE` | TLS 連線的 CA 憑證來源逗號分隔清單。`bundled` 是隨 Claude Code 提供的 Mozilla CA 集。`system` 是作業系統信任存放區。預設為 `bundled,system` |167| `CLAUDE_CODE_BRIDGE_SESSION_ID` | {/* min-version: 2.1.199 */}在工作階段具有作用中 [Remote Control](/zh-TW/remote-control) 連線時在 Bash 工具和 [hook command](/zh-TW/hooks) 子程序中自動設定，並在連線結束時移除。該值是工作階段的 ID，格式為 `session_`，與出現在工作階段 `claude.ai/code` URL 中的識別碼相同，因此指令碼可以連結回執行它的工作階段。需要 Claude Code v2.1.199 或更新版本。在 [cloud sessions](/zh-TW/claude-code-on-the-web) 中，改為讀取 `CLAUDE_CODE_REMOTE_SESSION_ID` |

168| `CLAUDE_CODE_CERT_STORE` | TLS 連線的 CA 憑證來源逗號分隔清單。`bundled` 是隨 Claude Code 提供的 Mozilla CA 集。`system` 是作業系統信任存放區，在具有 `tls.getCACertificates` 的執行時上唯讀：原生二進位檔或 npm 安裝的 Node 22.15 或更新版本。請參閱 [CA certificate store](/zh-TW/network-config#ca-certificate-store)。預設為 `bundled,system` |

166| `CLAUDE_CODE_CHILD_SESSION` | {/* min-version: 2.1.172 */}在 Claude Code 透過 Bash、PowerShell 和 Monitor 工具、[hook](/zh-TW/hooks) 命令和 [status line](/zh-TW/statusline) 命令生成的子程序中設定為 `1`。不為 stdio [MCP server](/zh-TW/mcp) 子程序設定，這些是長期存在的，並且超過啟動它們的工作階段。與 `CLAUDECODE` 不同，這僅由 Claude Code 自己的生成路徑設定，而不是由 IDE 擴充功能設定，因此它可靠地區分嵌套工作階段與在 IDE 整合終端中啟動的頂層 `claude`。以這種方式啟動的嵌套互動式 `claude` TUI 會自動從 `--resume`、`--continue`、向上箭頭歷史記錄和 `claude agents` 清單中排除。非互動式 `claude -p` 工作階段仍然保留。設定 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 以覆蓋此排除。需要 Claude Code v2.1.172 或更新版本 |169| `CLAUDE_CODE_CHILD_SESSION` | {/* min-version: 2.1.172 */}在 Claude Code 透過 Bash、PowerShell 和 Monitor 工具、[hook](/zh-TW/hooks) 命令和 [status line](/zh-TW/statusline) 命令生成的子程序中設定為 `1`。不為 stdio [MCP server](/zh-TW/mcp) 子程序設定，這些是長期存在的，並且超過啟動它們的工作階段。與 `CLAUDECODE` 不同，這僅由 Claude Code 自己的生成路徑設定，而不是由 IDE 擴充功能設定，因此它可靠地區分嵌套工作階段與在 IDE 整合終端中啟動的頂層 `claude`。以這種方式啟動的嵌套互動式 `claude` TUI 會自動從 `--resume`、`--continue`、向上箭頭歷史記錄和 `claude agents` 清單中排除。非互動式 `claude -p` 工作階段仍然保留。設定 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 以覆蓋此排除。需要 Claude Code v2.1.172 或更新版本 |

170| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | {/* max-version: 2.1.185 */}在 v2.1.186 中移除，現在是無操作。先前設定串流 API 請求的連線、TLS 和回應標頭階段的逾時。使用 `API_TIMEOUT_MS` 進行每個請求的逾時 |173| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | {/* max-version: 2.1.185 */}在 v2.1.186 中移除，現在是無操作。先前設定串流 API 請求的連線、TLS 和回應標頭階段的逾時。使用 `API_TIMEOUT_MS` 進行每個請求的逾時 |

171| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆蓋偵錯日誌檔案路徑。儘管名稱如此，這是檔案路徑，而不是目錄。需要透過 `--debug`、`/debug` 或 `DEBUG` 環境變數單獨啟用偵錯模式：僅設定此變數不會啟用日誌記錄。[`--debug-file`](/zh-TW/cli-reference#cli-flags) 旗標同時執行兩者。預設為 `~/.claude/debug/<session-id>.txt` |174| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆蓋偵錯日誌檔案路徑。儘管名稱如此，這是檔案路徑，而不是目錄。需要透過 `--debug`、`/debug` 或 `DEBUG` 環境變數單獨啟用偵錯模式：僅設定此變數不會啟用日誌記錄。[`--debug-file`](/zh-TW/cli-reference#cli-flags) 旗標同時執行兩者。預設為 `~/.claude/debug/<session-id>.txt` |

172| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 寫入偵錯日誌檔案的最小日誌級別。值：`verbose`、`debug`（預設）、`info`、`warn`、`error`。設定為 `verbose` 以包含高容量診斷，例如完整狀態行命令輸出，或提高到 `error` 以減少雜訊 |175| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 寫入偵錯日誌檔案的最小日誌級別。值：`verbose`、`debug`（預設）、`info`、`warn`、`error`。設定為 `verbose` 以包含高容量診斷，例如完整狀態行命令輸出，或提高到 `error` 以減少雜訊 |

173| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 設定為 `1` 以停用 [1M context window](/zh-TW/model-config#extended-context) 支援。設定時，1M 模型變體在模型選擇器中不可用。對於具有合規性要求的企業環境很有用 |176| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 設定為 `1` 以停用 [1M context window](/zh-TW/model-config#extended-context) 支援。設定時，1M 模型變體在模型選擇器中不可用，[Sonnet 5](/zh-TW/model-config#sonnet-5-context-window) 工作階段被視為具有 200K 視窗。對於具有合規性要求的企業環境很有用 |

174| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 設定為 `1` 以停用 Opus 4.6 和 Sonnet 4.6 的 [adaptive reasoning](/zh-TW/model-config#adjust-effort-level)，並回退到由 `MAX_THINKING_TOKENS` 控制的固定思考預算。{/* min-version: 2.1.111 */}從 v2.1.111 起，對 Fable 5 無效，或對 Opus 4.7 及更新版本無效，其始終使用自適應推理 |177| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 設定為 `1` 以停用 Opus 4.6 和 Sonnet 4.6 的 [adaptive reasoning](/zh-TW/model-config#adjust-effort-level)，並回退到由 `MAX_THINKING_TOKENS` 控制的固定思考預算。{/* min-version: 2.1.111 */}從 v2.1.111 起，對 Fable 5、Sonnet 5 或 Opus 4.7 及更新版本無效，其始終使用自適應推理 |

175| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | {/* min-version: 2.1.98 */}設定為 `1` 以停用 [advisor tool](/zh-TW/advisor)。`/advisor` 命令和 `--advisor` 旗標變為不可用，任何配置的 `advisorModel` 都會被忽略。需要 Claude Code v2.1.98 或更新版本 |178| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | {/* min-version: 2.1.98 */}設定為 `1` 以停用 [advisor tool](/zh-TW/advisor)。`/advisor` 命令變為不可用，任何配置的 `advisorModel` 都會被忽略，`--advisor` 旗標被接受但無效，因此傳遞它的現有指令碼繼續工作而不出現錯誤。需要 Claude Code v2.1.98 或更新版本 |

176| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 設定為 `1` 以關閉 [background agents and agent view](/zh-TW/agent-view)：`claude agents`、`--bg`、`/background` 和隨選主管。相當於 [`disableAgentView`](/zh-TW/settings#available-settings) 設定 |179| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 設定為 `1` 以關閉 [background agents and agent view](/zh-TW/agent-view)：`claude agents`、`--bg`、`/background` 和隨選主管。相當於 [`disableAgentView`](/zh-TW/settings#available-settings) 設定 |

177| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 設定為 `1` 以停用 [fullscreen rendering](/zh-TW/fullscreen) 並使用經典主螢幕渲染器。對話保留在您終端的原生捲動回溯中，因此 `Cmd+f` 和 tmux 複製模式可以正常工作。優先於 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/zh-TW/settings#available-settings) 設定。您也可以使用 `/tui default` 切換。不適用於從 [agent view](/zh-TW/agent-view) 開啟的背景工作階段，其始終使用全螢幕渲染 |180| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 設定為 `1` 以停用 [fullscreen rendering](/zh-TW/fullscreen) 並使用經典主螢幕渲染器。對話保留在您終端的原生捲動回溯中，因此 `Cmd+f` 和 tmux 複製模式可以正常工作。優先於 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/zh-TW/settings#available-settings) 設定。您也可以使用 `/tui default` 切換。不適用於從 [agent view](/zh-TW/agent-view) 開啟的背景工作階段，其始終使用全螢幕渲染 |

178| `CLAUDE_CODE_DISABLE_ARTIFACT` | 設定為 `1` 以停用 [Artifact](/zh-TW/artifacts) 工具，該工具將工作階段輸出發佈為 claude.ai 上的私人網頁。相當於 [`disableArtifact`](/zh-TW/settings#available-settings) 設定 |181| `CLAUDE_CODE_DISABLE_ARTIFACT` | 設定為 `1` 以停用 [Artifact](/zh-TW/artifacts) 工具，該工具將工作階段輸出發佈為 claude.ai 上的私人網頁。相當於 [`disableArtifact`](/zh-TW/settings#available-settings) 設定 |

180| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設定為 `1` 以停用 [auto memory](/zh-TW/memory#auto-memory)。設定為 `0` 以在 `--bare` 模式或 [`autoMemoryEnabled: false`](/zh-TW/settings#available-settings) 會以其他方式停用時強制啟用自動記憶體。停用時，Claude 不會建立或載入自動記憶體檔案 |183| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 設定為 `1` 以停用 [auto memory](/zh-TW/memory#auto-memory)。設定為 `0` 以在 `--bare` 模式或 [`autoMemoryEnabled: false`](/zh-TW/settings#available-settings) 會以其他方式停用時強制啟用自動記憶體。停用時，Claude 不會建立或載入自動記憶體檔案 |

181| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 設定為 `1` 以停用所有背景任務功能，包括 Bash 和 subagent 工具上的 `run_in_background` 參數、自動背景執行和 Ctrl+B 快捷鍵 |184| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 設定為 `1` 以停用所有背景任務功能，包括 Bash 和 subagent 工具上的 `run_in_background` 參數、自動背景執行和 Ctrl+B 快捷鍵 |

185| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | {/* min-version: 2.1.196 */}設定為 `1` 以停止 [background session](/zh-TW/agent-view) 的執行中背景 shell 命令、動態工作流程，{/* min-version: 2.1.198 */}以及自 v2.1.198 起的背景 subagents，當 [supervisor](/zh-TW/agent-view#the-supervisor-process) 停止、重新啟動或更新該工作階段的程序時，而不是將它們交給工作階段的下一個程序。僅影響該交接：使用 `←` 或 [`/background`](/zh-TW/agent-view#from-inside-a-session) 將工作階段背景化仍會帶入進行中的工作，`CLAUDE_DISABLE_ADOPT` 會關閉兩者。需要 Claude Code v2.1.196 或更新版本 |

186| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | {/* min-version: 2.1.193 */}設定為 `1` 以停止 Claude Code 在作業系統報告記憶體壓力時終止 [background shell commands](/zh-TW/interactive-mode#background-bash-commands)。預設情況下，在 macOS 和 Linux 上，Claude Code 在主工作階段中啟動的背景 shell 在記憶體壓力信號上終止，一旦工作階段已閒置 30 分鐘且沒有回合或 subagent 執行。Windows 沒有記憶體壓力信號，因此此變數對其無效。需要 Claude Code v2.1.193 或更新版本 |

182| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 設定為 `1` 以停用隨 Claude Code 提供的 [skills](/zh-TW/skills) 和工作流程：捆綁的 skills 和工作流程會完全移除，而內建的斜線命令（如 `/init`）保持可輸入但對模型隱藏。來自外掛程式、`.claude/skills/` 和 `.claude/commands/` 的 skills 不受影響。相當於 [`disableBundledSkills`](/zh-TW/settings#available-settings) 設定；`0` 不會覆蓋它 |187| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 設定為 `1` 以停用隨 Claude Code 提供的 [skills](/zh-TW/skills) 和工作流程：捆綁的 skills 和工作流程會完全移除，而內建的斜線命令（如 `/init`）保持可輸入但對模型隱藏。來自外掛程式、`.claude/skills/` 和 `.claude/commands/` 的 skills 不受影響。相當於 [`disableBundledSkills`](/zh-TW/settings#available-settings) 設定；`0` 不會覆蓋它 |

184| `CLAUDE_CODE_DISABLE_CRON` | 設定為 `1` 以停用 [scheduled tasks](/zh-TW/scheduled-tasks)。`/loop` skill 和 cron 工具變為不可用，任何已排程的任務停止觸發，包括已在工作階段中執行的任務 |189| `CLAUDE_CODE_DISABLE_CRON` | 設定為 `1` 以停用 [scheduled tasks](/zh-TW/scheduled-tasks)。`/loop` skill 和 cron 工具變為不可用，任何已排程的任務停止觸發，包括已在工作階段中執行的任務 |

185| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 設定為 `1` 以從 API 請求中移除 Anthropic 特定的 `anthropic-beta` 請求標頭和 beta 工具架構欄位（例如 `defer_loading` 和 `eager_input_streaming`）。當代理閘道拒絕請求並出現「Unexpected value(s) for the `anthropic-beta` header」或「Extra inputs are not permitted」之類的錯誤時，請使用此選項。標準欄位（`name`、`description`、`input_schema`、`cache_control`）會保留。 |190| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 設定為 `1` 以從 API 請求中移除 Anthropic 特定的 `anthropic-beta` 請求標頭和 beta 工具架構欄位（例如 `defer_loading` 和 `eager_input_streaming`）。當代理閘道拒絕請求並出現「Unexpected value(s) for the `anthropic-beta` header」或「Extra inputs are not permitted」之類的錯誤時，請使用此選項。標準欄位（`name`、`description`、`input_schema`、`cache_control`）會保留 |

191| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | {/* min-version: 2.1.198 */}設定為 `1` 以停用內建的 [Explore and Plan subagents](/zh-TW/sub-agents#built-in-subagents)。Claude 改為使用其搜尋工具或通用 subagent 進行探索，[plan mode](/zh-TW/permission-modes#analyze-before-you-edit-with-plan-mode) 直接讀取檔案而不是啟動 Explore 和 Plan agents。名為 `Explore` 或 `Plan` 的自訂 subagents 不受影響。若要在 Agent SDK 或非互動式模式中移除每個內建 subagent 類型，請改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更新版本 |

187| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設定為 `1` 以停用「Claude 表現如何？」工作階段品質調查。在設定 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時也會停用調查，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 選擇加入。若要改為設定樣本速率，請使用 [`feedbackSurveyRate`](/zh-TW/settings#available-settings) 設定。請參閱 [Session quality surveys](/zh-TW/data-usage#session-quality-surveys) |193| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 設定為 `1` 以停用「Claude 表現如何？」工作階段品質調查。在設定 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 時也會停用調查，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 選擇加入。若要改為設定樣本速率，請使用 [`feedbackSurveyRate`](/zh-TW/settings#available-settings) 設定。請參閱 [Session quality surveys](/zh-TW/data-usage#session-quality-surveys) |

189| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設定為 `1` 以從 Claude 的系統提示中移除內建的提交和 PR 工作流程指令以及 git 狀態快照。在使用您自己的 git 工作流程 skills 時很有用。設定時優先於 [`includeGitInstructions`](/zh-TW/settings#available-settings) 設定 |195| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 設定為 `1` 以從 Claude 的系統提示中移除內建的提交和 PR 工作流程指令以及 git 狀態快照。在使用您自己的 git 工作流程 skills 時很有用。設定時優先於 [`includeGitInstructions`](/zh-TW/settings#available-settings) 設定 |

190| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設定為 `1` 以防止在 Anthropic API 上自動重新對應 Opus 4.0 和 4.1 至目前的 Opus 版本。在您想要刻意固定較舊模型時使用。重新對應不在 Bedrock、Vertex 或 Foundry 上執行 |196| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 設定為 `1` 以防止在 Anthropic API 上自動重新對應 Opus 4.0 和 4.1 至目前的 Opus 版本。在您想要刻意固定較舊模型時使用。重新對應不在 Bedrock、Vertex 或 Foundry 上執行 |

191| `CLAUDE_CODE_DISABLE_MOUSE` | 設定為 `1` 以停用 [fullscreen rendering](/zh-TW/fullscreen) 中的滑鼠追蹤。使用 `PgUp` 和 `PgDn` 的鍵盤捲動仍然有效。使用此選項可保留您終端的原生選擇複製行為 |197| `CLAUDE_CODE_DISABLE_MOUSE` | 設定為 `1` 以停用 [fullscreen rendering](/zh-TW/fullscreen) 中的滑鼠追蹤。使用 `PgUp` 和 `PgDn` 的鍵盤捲動仍然有效。使用此選項可保留您終端的原生選擇複製行為 |

198| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | {/* min-version: 2.1.195 */}設定為 `1` 以停用 [fullscreen rendering](/zh-TW/fullscreen) 中的點擊、拖曳和懸停處理，同時保留滑鼠滾輪捲動。當您想要滾輪捲動在 Claude Code 內工作但不想要點擊來定位游標、展開工具輸出或開啟連結時使用。當兩者都設定時，`CLAUDE_CODE_DISABLE_MOUSE` 優先。需要 Claude Code v2.1.195 或更新版本 |

192| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 相當於設定 `DISABLE_AUTOUPDATER`、`DISABLE_FEEDBACK_COMMAND`、`DISABLE_ERROR_REPORTING` 和 `DISABLE_TELEMETRY` |199| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 相當於設定 `DISABLE_AUTOUPDATER`、`DISABLE_FEEDBACK_COMMAND`、`DISABLE_ERROR_REPORTING` 和 `DISABLE_TELEMETRY` |

201| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | {/* min-version: 2.1.193 */}設定為 `1` 以在您在終端中輸入或聚焦時發送 `PushNotification` 工具的桌面通知。預設情況下，當工具偵測到最近的鍵盤活動或終端焦點時，工具會跳過桌面通知和 [mobile push](/zh-TW/remote-control#mobile-push-notifications)。此變數僅停用該本機檢查，因此伺服器仍可在偵測到您活躍時抑制行動推送。需要 Claude Code v2.1.193 或更新版本 |

196| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 設定為 `1` 以停用基於對話上下文的自動終端標題更新。在 Agent SDK 和 `claude -p` 工作階段中，這也會跳過產生工作階段標題的背景 Haiku 請求 |204| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 設定為 `1` 以停用基於對話上下文的自動終端標題更新。在 Agent SDK 和 `claude -p` 工作階段中，這也會跳過產生工作階段標題的背景 Haiku 請求 |

203| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設定為 `1` 以在 [non-interactive mode](/zh-TW/headless) 中背景安裝完成後在回合邊界處刷新外掛程式狀態。預設關閉，因為刷新會在工作階段中途更改系統提示，這會使該回合的 [prompt caching](/zh-TW/prompt-caching) 失效 |211| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 設定為 `1` 以在 [non-interactive mode](/zh-TW/headless) 中背景安裝完成後在回合邊界處刷新外掛程式狀態。預設關閉，因為刷新會在工作階段中途更改系統提示，這會使該回合的 [prompt caching](/zh-TW/prompt-caching) 失效 |

204| `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` 和組織產品反饋政策優先 |212| `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` 和組織產品反饋政策優先 |

205| `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) 連線上預設關閉 |213| `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) 連線上預設關閉 |

206| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 相容閘道（例如 LiteLLM、Kong 或內部代理）時從您的閘道的 `/v1/models` 端點填充 `/model` 選擇器。預設關閉，因為由共享 API 金鑰支援的閘道會以其他方式向每個使用者顯示該金鑰可以存取的每個模型。探索的模型仍由 [`availableModels`](/zh-TW/settings#available-settings) 允許清單篩選 |214| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 設定為 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 相容閘道（例如 LiteLLM、Kong 或內部代理）時從您的閘道的 `/v1/models` 端點填充 `/model` 選擇器。預設關閉，因為由共享 API 金鑰支援的閘道會以其他方式向每個使用者顯示該金鑰可以存取的每個模型。探索的模型仍由 [`availableModels`](/zh-TW/settings#available-settings) 允許清單篩選，工作階段接收；由於 [server-managed delivery is not available on gateway configurations](/zh-TW/server-managed-settings#platform-availability)，透過 MDM 或受管設定檔案傳遞清單 |

207| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | {/* max-version: 2.1.141 */}在 v2.1.142 中移除，當 [fast mode](/zh-TW/fast-mode) 預設從 Opus 4.6 移至 Opus 4.7 時 |215| `CLAUDE_CODE_ENABLE_OPUS_4_7_FAST_MODE` | {/* max-version: 2.1.141 */}在 v2.1.142 中移除，當 [fast mode](/zh-TW/fast-mode) 預設從 Opus 4.6 移至 Opus 4.7 時 |

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

209| `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) |217| `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) |

215| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | {/* min-version: 2.1.172 */}設定為 `1` 以強制文字記錄持久化、提示歷史記錄和 `claude agents` 註冊，即使此 `claude` 是從另一個 Claude Code 工作階段內啟動的。在繼承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如來自 Claude Code 的 Bash 工具首次啟動的 tmux 伺服器）導致真正的頂層工作階段被誤分類為嵌套時使用。{/* min-version: 2.1.178 */}自 v2.1.178 起，Claude Code 會自動偵測 tmux 情況並忽略繼承的標記，因此 tmux 不再需要此變數。也在 v2.1.169 及更早版本上受尊重；對 v2.1.170 和 v2.1.171 無效，其中它覆蓋的嵌套工作階段偵測被移除 |223| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | {/* min-version: 2.1.172 */}設定為 `1` 以強制文字記錄持久化、提示歷史記錄和 `claude agents` 註冊，即使此 `claude` 是從另一個 Claude Code 工作階段內啟動的。在繼承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如來自 Claude Code 的 Bash 工具首次啟動的 `screen` 工作階段）導致真正的頂層工作階段被誤分類為嵌套時使用。{/* min-version: 2.1.178 */}自 v2.1.178 起，Claude Code 會自動偵測 tmux 情況並忽略繼承的標記，因此 tmux 不再需要此變數。也在 v2.1.169 及更早版本上受尊重；對 v2.1.170 和 v2.1.171 無效，其中它覆蓋的嵌套工作階段偵測被移除 |

216| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | {/* min-version: 2.1.186 */}設定為 `1` 以在您的終端支援但未自動偵測時強制刪除線呈現 `~~text~~`，例如透過 SSH 而未轉發 `TERM_PROGRAM`。沒有此選項，未偵測的終端會顯示文字刪除線標記而不是呈現為刪除線。需要 Claude Code v2.1.186 或更新版本 |224| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | {/* min-version: 2.1.186 */}設定為 `1` 以在您的終端支援但未自動偵測時強制刪除線呈現 `~~text~~`，例如透過 SSH 而未轉發 `TERM_PROGRAM`。沒有此選項，未偵測的終端會顯示文字刪除線標記而不是呈現為刪除線。需要 Claude Code v2.1.186 或更新版本 |

217| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 設定為 `1` 以強制啟用 DEC 私有模式 2026 [synchronized output](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)（當您的終端支援但未自動偵測時）。對於實現 BSU/ESU 但不回覆功能探測的模擬器（例如 Emacs `eat`）很有用。在 tmux 下無效 |225| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 設定為 `1` 以強制啟用 DEC 私有模式 2026 [synchronized output](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)（當您的終端支援但未自動偵測時）。對於實現 BSU/ESU 但不回覆功能探測的模擬器（例如 Emacs `eat`）很有用。在 tmux 下無效 |

218| `CLAUDE_CODE_FORK_SUBAGENT` | 設定為 `1` 以啟用 Claude 生成 [forked subagents](/zh-TW/sub-agents#fork-the-current-conversation)，或 `0` 以停用它們，覆蓋任何伺服器端推出。啟用時，Claude 可以要求 `fork` subagent 類型以生成分叉，一個繼承完整對話上下文而不是從頭開始的 subagent。沒有 subagent 類型的生成仍使用通用 subagent，所有 subagent 生成都在背景中執行。明確的 [`/fork`](/zh-TW/commands) 命令無需此變數即可工作。在互動式模式和透過 SDK 或 `claude -p` 中工作 |226| `CLAUDE_CODE_FORK_SUBAGENT` | 設定為 `1` 以啟用 Claude 生成 [forked subagents](/zh-TW/sub-agents#fork-the-current-conversation)，或 `0` 以停用它們，覆蓋任何伺服器端推出。啟用時，Claude 可以要求 `fork` subagent 類型以生成分叉，一個繼承完整對話上下文而不是從頭開始的 subagent。沒有 subagent 類型的生成仍使用通用 subagent，所有 subagent 生成都在背景中執行。明確的 [`/fork`](/zh-TW/commands) 命令無需此變數即可工作。在互動式模式和透過 SDK 或 `claude -p` 中工作 |

225| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 跳過 IDE 擴充功能的自動安裝。相當於將 [`autoInstallIdeExtension`](/zh-TW/settings#global-config-settings) 設定為 `false` |233| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 設定為 `1` 以跳過 IDE 擴充功能的自動安裝。相當於將 [`autoInstallIdeExtension`](/zh-TW/settings#global-config-settings) 設定為 `false` |

227| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆蓋 Claude Code 假設用於作用中模型的上下文視窗大小。僅在同時設定 `DISABLE_COMPACT` 時生效。當透過 `ANTHROPIC_BASE_URL` 路由到模型時使用，其上下文視窗與其名稱的內建大小不符 |235| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆蓋 Claude Code 假設用於作用中模型的上下文視窗大小。{/* min-version: 2.1.193 */}自 v2.1.193 起，直接應用於 Claude Code 不識別為 Claude 模型的模型名稱；對於識別的 Claude 模型，僅當同時設定 `DISABLE_COMPACT` 時才生效。當透過 `ANTHROPIC_BASE_URL` 路由到模型時使用，其上下文視窗與其名稱的內建大小不符 |

228| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 設定大多數請求的最大輸出 token 數。預設值和上限因模型而異；請參閱 [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。增加此值會減少在 [auto-compaction](/zh-TW/costs#reduce-token-usage) 觸發之前可用的有效上下文視窗。 |236| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 設定大多數請求的最大輸出 token 數。預設值和上限因模型而異；請參閱 [max output tokens](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。增加此值會減少在 [auto-compaction](/zh-TW/costs#reduce-token-usage) 觸發之前可用的有效上下文視窗 |

229| `CLAUDE_CODE_MAX_RETRIES` | 覆蓋重試失敗 API 請求的次數（預設值：10）。{/* min-version: 2.1.186 */}自 v2.1.186 起上限為 15。對於需要等待較長中斷的無人值守工作階段，請改為設定 `CLAUDE_CODE_RETRY_WATCHDOG` |237| `CLAUDE_CODE_MAX_RETRIES` | 覆蓋重試失敗 API 請求的次數（預設值：10）。{/* min-version: 2.1.186 */}自 v2.1.186 起上限為 15；{/* min-version: 2.1.199 */}自 v2.1.199 起，`CLAUDE_CODE_RETRY_WATCHDOG` 會提高預設值並移除上限。對於需要等待較長中斷的無人值守工作階段，請改為設定 `CLAUDE_CODE_RETRY_WATCHDOG` |

231| `CLAUDE_CODE_MAX_TURNS` | 當未傳遞明確限制時，限制代理回合的數量。相當於傳遞 [`--max-turns`](/zh-TW/cli-reference#cli-flags)，當兩者都設定時優先。不是正整數的值在啟動時會被拒絕並出現錯誤，而不是被視為無限制 |239| `CLAUDE_CODE_MAX_TURNS` | 當未傳遞明確限制時，限制代理回合的數量。相當於傳遞 [`--max-turns`](/zh-TW/cli-reference#cli-flags)，當兩者都設定時優先。不是正整數的值在啟動時會被拒絕並出現錯誤，而不是被視為無限制 |

233| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | {/* min-version: 2.1.187 */}遠端 MCP 工具呼叫的閒置逾時（以毫秒為單位）（預設值：300000，或 5 分鐘）。當 HTTP、SSE、WebSocket 或 [claude.ai connector](/zh-TW/mcp#use-mcp-servers-from-claude-ai) MCP 伺服器在此期間內沒有發送回應和進度通知時，工具呼叫會中止並出現錯誤，而不是等待牆上時鐘 `MCP_TOOL_TIMEOUT`。設定為 `0` 以停用閒置檢查。低於 1000 的值會提高到 1 秒，該值上限為有效的 `MCP_TOOL_TIMEOUT`。不適用於 stdio 或 IDE 伺服器。需要 Claude Code v2.1.187 或更新版本 |241| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | {/* min-version: 2.1.187 */}遠端 MCP 工具呼叫的閒置逾時（以毫秒為單位）（預設值：300000，或 5 分鐘）。當 HTTP、SSE、WebSocket 或 [claude.ai connector](/zh-TW/mcp#use-mcp-servers-from-claude-ai) MCP 伺服器在此期間內沒有發送回應和進度通知時，工具呼叫會中止並出現錯誤，而不是等待牆上時鐘 `MCP_TOOL_TIMEOUT`。設定為 `0` 以停用閒置檢查。低於 1000 的值會提高到 1 秒，該值上限為有效的 `MCP_TOOL_TIMEOUT`。不適用於 stdio 或 IDE 伺服器。需要 Claude Code v2.1.187 或更新版本 |

235| `CLAUDE_CODE_NEW_INIT` | 設定為 `1` 以使 `/init` 執行互動式設定流程。流程會詢問要產生哪些檔案，包括 CLAUDE.md、skills 和 hooks，然後再探索程式碼庫並寫入它們。沒有此變數，`/init` 會自動產生 CLAUDE.md 而不提示。 |243| `CLAUDE_CODE_NEW_INIT` | 設定為 `1` 以使 `/init` 執行互動式設定流程。流程會詢問要產生哪些檔案，包括 CLAUDE.md、skills 和 hooks，然後再探索程式碼庫並寫入它們。沒有此變數，`/init` 會自動產生 CLAUDE.md 而不提示 |

236| `CLAUDE_CODE_NO_FLICKER` | 設定為 `1` 以啟用 [fullscreen rendering](/zh-TW/fullscreen)，一項研究預覽，可減少閃爍並在長對話中保持記憶體平坦。相當於 [`tui`](/zh-TW/settings#available-settings) 設定；您也可以使用 `/tui fullscreen` 切換 |244| `CLAUDE_CODE_NO_FLICKER` | 設定為 `1` 以啟用 [fullscreen rendering](/zh-TW/fullscreen)，一項研究預覽，可減少閃爍並在長對話中保持記憶體平坦。相當於 [`tui`](/zh-TW/settings#available-settings) 設定；您也可以使用 `/tui fullscreen` 切換 |

237| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 驗證的 OAuth 重新整理權杖。設定時，`claude auth login` 會直接交換此權杖，而不是開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。對於在自動化環境中佈建驗證很有用 |245| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 驗證的 OAuth 重新整理權杖。設定時，`claude auth login` 會直接交換此權杖，而不是開啟瀏覽器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。對於在自動化環境中佈建驗證很有用 |

238| `CLAUDE_CODE_OAUTH_SCOPES` | 重新整理權杖發出時所使用的空格分隔 OAuth 範圍，例如 `"user:profile user:inference user:sessions:claude_code"`。設定 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 時為必需 |246| `CLAUDE_CODE_OAUTH_SCOPES` | 重新整理權杖發出時所使用的空格分隔 OAuth 範圍，例如 `"user:profile user:inference user:sessions:claude_code"`。設定 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 時為必需 |

239| `CLAUDE_CODE_OAUTH_TOKEN` | Claude.ai 驗證的 OAuth 存取權杖。`/login` 對於 SDK 和自動化環境的替代方案。優先於鑰匙圈儲存的認證。使用 [`claude setup-token`](/zh-TW/authentication#generate-a-long-lived-token) 產生一個 |247| `CLAUDE_CODE_OAUTH_TOKEN` | Claude.ai 驗證的 OAuth 存取權杖。`/login` 對於 SDK 和自動化環境的替代方案。優先於鑰匙圈儲存的認證。使用 [`claude setup-token`](/zh-TW/authentication#generate-a-long-lived-token) 產生一個 |

240| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | {/* max-version: 2.1.159 */}在 v2.1.160 中移除，現在是無操作。先前將 [fast mode](/zh-TW/fast-mode) 固定到 Claude Opus 4.6，而不是目前的預設值 |248| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | {/* max-version: 2.1.159 */}在 v2.1.160 中移除，現在是無操作。先前將 [fast mode](/zh-TW/fast-mode) 固定到 Claude Opus 4.6，而不是目前的預設值。Opus 4.6 不再支援快速模式 |

241| `CLAUDE_CODE_OTEL_DIAG_STDERR` | {/* min-version: 2.1.179 */}設定為 `1` 以將 OpenTelemetry 匯出器診斷錯誤寫入 stderr。預設情況下，這些錯誤僅在 `--debug` 時出現，因此配置不當的匯出器（例如 Prometheus 連接埠衝突）會以其他方式無聲失敗。需要 Claude Code v2.1.179 或更新版本。請參閱 [Monitoring](/zh-TW/monitoring-usage) |249| `CLAUDE_CODE_OTEL_DIAG_STDERR` | {/* min-version: 2.1.179 */}設定為 `1` 以將 OpenTelemetry 匯出器診斷錯誤寫入 stderr。預設情況下，這些錯誤僅在 `--debug` 時出現，因此配置不當的匯出器（例如 Prometheus 連接埠衝突）會以其他方式無聲失敗。需要 Claude Code v2.1.179 或更新版本。請參閱 [Monitoring](/zh-TW/monitoring-usage) |

242| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 刷新待處理 OpenTelemetry spans 的逾時（以毫秒為單位）（預設值：5000）。請參閱 [Monitoring](/zh-TW/monitoring-usage) |250| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 刷新待處理 OpenTelemetry spans 的逾時（以毫秒為單位）（預設值：5000）。請參閱 [Monitoring](/zh-TW/monitoring-usage) |

243| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新動態 OpenTelemetry 標頭的間隔（以毫秒為單位）（預設值：1740000 / 29 分鐘）。請參閱 [Dynamic headers](/zh-TW/monitoring-usage#dynamic-headers) |251| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新動態 OpenTelemetry 標頭的間隔（以毫秒為單位）（預設值：1740000 / 29 分鐘）。請參閱 [Dynamic headers](/zh-TW/monitoring-usage#dynamic-headers) |

258| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在 [cloud sessions](/zh-TW/claude-code-on-the-web) 中自動設定為目前工作階段的 ID。讀取此項以構造回到工作階段文字記錄的連結。請參閱 [Link output back to the session](/zh-TW/claude-code-on-the-web#link-output-back-to-the-session) |266| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在 [cloud sessions](/zh-TW/claude-code-on-the-web) 中自動設定為目前工作階段的 ID。讀取此項以構造回到工作階段文字記錄的連結。請參閱 [Link output back to the session](/zh-TW/claude-code-on-the-web#link-output-back-to-the-session) |

260| `CLAUDE_CODE_RESUME_PROMPT` | 覆蓋在繼續在中途結束的工作階段時注入的延續訊息。預設為 `Continue from where you left off.`。長時間執行的代理的生成指令碼可以將此設定為更具指令性的啟動訊息。空字串使用預設值 |268| `CLAUDE_CODE_RESUME_PROMPT` | 覆蓋在繼續在中途結束的工作階段時注入的延續訊息。預設為 `Continue from where you left off.`。長時間執行的代理的生成指令碼可以將此設定為更具指令性的啟動訊息。空字串使用預設值 |

261| `CLAUDE_CODE_RETRY_WATCHDOG` | {/* min-version: 2.1.186 */}設定為 `1` 用於無人值守工作階段，例如評估工具、CI 工作或遠端工作者。無限期重試 `429` 和 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 嘗試後失敗。監視程式在嘗試之間退避最多 5 分鐘，或直到限制在回應帶有速率限制重設時間時重設，因此達到使用限制的工作階段會等待剩餘視窗。需要 Claude Code v2.1.186 或更新版本 |269| `CLAUDE_CODE_RETRY_WATCHDOG` | {/* min-version: 2.1.186 */}設定為 `1` 用於無人值守工作階段，例如評估工具、CI 工作或遠端工作者。無限期重試 `429` 和 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 嘗試後失敗。監視程式在嘗試之間退避最多 5 分鐘，或直到限制在回應帶有速率限制重設時間時重設，因此達到使用限制的工作階段會等待剩餘視窗。{/* min-version: 2.1.199 */}自 v2.1.199 起，它也會提高其他暫時性錯誤（例如伺服器錯誤、逾時和丟棄的連線）的預設重試計數至 300，大約三小時的退避，並在您明確設定該變數時移除 `CLAUDE_CODE_MAX_RETRIES` 的上限 15。需要 Claude Code v2.1.186 或更新版本 |

262| `CLAUDE_CODE_SAFE_MODE` | 設定為 `1` 以在安全模式下啟動：CLAUDE.md、skills、plugins、hooks、MCP 伺服器、自訂命令和代理、輸出樣式、工作流程、自訂主題、自訂快捷鍵、狀態行和檔案建議命令、LSP 伺服器和自動記憶體不載入，用於對損壞的配置進行故障排除。受管設定政策仍然適用，包括政策配置的 hooks、狀態行和檔案建議命令；受管外掛程式、受管 skills、受管 CLAUDE.md 和政策配置的 MCP 伺服器不適用。相當於傳遞 [`--safe-mode`](/zh-TW/cli-reference#cli-flags)。直接生成的子程序繼承該變數 |270| `CLAUDE_CODE_SAFE_MODE` | 設定為 `1` 以在安全模式下啟動：CLAUDE.md、skills、plugins、hooks、MCP 伺服器、自訂命令和代理、輸出樣式、工作流程、自訂主題、自訂快捷鍵、狀態行和檔案建議命令、LSP 伺服器和自動記憶體不載入，用於對損壞的配置進行故障排除。受管設定政策仍然適用，包括政策配置的 hooks、狀態行和檔案建議命令；受管外掛程式、受管 skills、受管 CLAUDE.md 和政策配置的 MCP 伺服器不適用。相當於傳遞 [`--safe-mode`](/zh-TW/cli-reference#cli-flags)。直接生成的子程序繼承該變數 |

263| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 物件，當設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時限制特定指令碼在每個工作階段中可被呼叫的次數。鍵是針對命令文字進行比對的子字串；值是整數呼叫限制。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對是基於子字串的，因此 shell 擴展技巧（如 `./scripts/deploy.sh $(evil)`）仍然計入上限。透過 `xargs` 或 `find -exec` 的執行時扇出未被偵測；這是深度防禦控制 |271| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 物件，當設定 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 時限制特定指令碼在每個工作階段中可被呼叫的次數。鍵是針對命令文字進行比對的子字串；值是整數呼叫限制。例如，`{"deploy.sh": 2}` 允許 `deploy.sh` 最多被呼叫兩次。比對是基於子字串的，因此 shell 擴展技巧（如 `./scripts/deploy.sh $(evil)`）仍然計入上限。透過 `xargs` 或 `find -exec` 的執行時扇出未被偵測；這是深度防禦控制 |

264| `CLAUDE_CODE_SCROLL_SPEED` | 在 [fullscreen rendering](/zh-TW/fullscreen#mouse-wheel-scrolling) 中設定滑鼠滾輪捲動乘數。接受 1 到 20 的值，以及低於 1 的分數值（例如 `0.5`）以減慢終端上原生捲動路徑中加速的觸控板和滾輪捲動。設定為 `3` 以符合 `vim`（如果您的終端在沒有放大的情況下每個刻度發送一個滾輪事件）。在 JetBrains IDE 終端中被忽略，Claude Code 使用其自己的捲動處理 |272| `CLAUDE_CODE_SCROLL_SPEED` | 在 [fullscreen rendering](/zh-TW/fullscreen#mouse-wheel-scrolling) 中設定滑鼠滾輪捲動乘數。接受 1 到 20 的值，以及低於 1 的分數值（例如 `0.5`）以減慢終端上原生捲動路徑中加速的觸控板和滾輪捲動。設定為 `3` 以符合 `vim`（如果您的終端在沒有放大的情況下每個刻度發送一個滾輪事件）。在 JetBrains IDE 終端中被忽略，Claude Code 使用其自己的捲動處理 |

265| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆蓋 [SessionEnd](/zh-TW/hooks#sessionend) hooks 的時間預算（以毫秒為單位）。適用於工作階段退出、`/clear` 和透過互動式 `/resume` 切換工作階段。預設情況下，預算為 1.5 秒，自動提高到設定檔案中配置的最高每個 hook `timeout`，最高 60 秒。外掛程式提供的 hooks 上的逾時不會提高預算 |273| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆蓋 [SessionEnd](/zh-TW/hooks#sessionend) hooks 的時間預算（以毫秒為單位）。適用於工作階段退出、`/clear` 和透過互動式 `/resume` 切換工作階段。預設情況下，預算為 1.5 秒，自動提高到設定檔案中配置的最高每個 hook `timeout`，最高 60 秒。外掛程式提供的 hooks 上的逾時不會提高預算 |

266| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子程序、[hook command](/zh-TW/hooks) 子程序和 stdio [MCP server](/zh-TW/mcp) 子程序中自動設定為目前工作階段 ID。對於 Bash、PowerShell 和 hooks，這符合傳遞給 hook JSON 輸入的 `session_id` 欄位，並在 `/clear` 時更新。MCP 伺服器子程序保留它生成時的 ID。在 `--resume <session-id>` 上，它接收繼續的 ID，符合 hooks 和 Bash。在 `--continue` 或 `--resume` 沒有明確 ID 時，它可能接收初始啟動 ID。用於將指令碼和外部工具與啟動它們的 Claude Code 工作階段相關聯 |274| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子程序、[hook command](/zh-TW/hooks) 子程序和 stdio [MCP server](/zh-TW/mcp) 子程序中自動設定為目前工作階段 ID。對於 Bash、PowerShell 和 hooks，這符合傳遞給 hook JSON 輸入的 `session_id` 欄位，並在 `/clear` 時更新。MCP 伺服器子程序保留它生成時的 ID。在 `--resume <session-id>` 上，它接收繼續的 ID，符合 hooks 和 Bash。在 `--continue` 或 `--resume` 沒有明確 ID 時，它可能接收初始啟動 ID。用於將指令碼和外部工具與啟動它們的 Claude Code 工作階段相關聯 |

267| `CLAUDE_CODE_SHELL` | 覆蓋自動 shell 偵測。當您的登入 shell 與您偏好的工作 shell 不同時很有用（例如，`bash` 與 `zsh`） |275| `CLAUDE_CODE_SHELL` | 設定 Claude Code 用來執行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二進位檔的路徑，例如 `/opt/homebrew/bin/bash`。不支援 `fish` 等其他 shells。如果該值不是有效的 `bash` 或 `zsh` 路徑，Claude Code 會忽略它並回退到自動偵測。自動偵測在您的 `$SHELL` 指向 `bash` 或 `zsh` 時使用它，否則它會在您的 `PATH` 和標準安裝位置上選擇第一個有效的 `zsh` 然後 `bash` |

268| `CLAUDE_CODE_SHELL_PREFIX` | 命令前綴以包裝 Claude Code 生成的 shell 命令：Bash 工具呼叫、[hook](/zh-TW/hooks) 命令、[status line](/zh-TW/statusline) 命令和 stdio [MCP server](/zh-TW/mcp) 啟動命令。PowerShell hooks 和 exec 形式的 hooks 無需前綴執行。對於日誌記錄或稽核很有用。設定裸可執行檔路徑（例如 `/path/to/logger.sh`）會將每個命令執行為 `/path/to/logger.sh '<command>'`。包裝器在 `$1` 中接收命令行作為單個 shell 引用的引數，因此包裝器必須使用 shell 重新評估 `$1`，例如 `exec bash -c "$1"`。將 `$1` 視為裸可執行檔路徑會破壞傳遞引數的 stdio MCP 伺服器，例如 `npx -y <package>`。對於 Bash 工具呼叫，`$1` 包含 Claude Code 組裝的完整 shell 呼叫，包括環境設定，而不僅僅是 Claude 執行的命令 |276| `CLAUDE_CODE_SHELL_PREFIX` | 命令前綴以包裝 Claude Code 生成的 shell 命令：Bash 工具呼叫、[hook](/zh-TW/hooks) 命令、[status line](/zh-TW/statusline) 命令和 stdio [MCP server](/zh-TW/mcp) 啟動命令。PowerShell hooks 和 exec 形式的 hooks 無需前綴執行。對於日誌記錄或稽核很有用。設定裸可執行檔路徑（例如 `/path/to/logger.sh`）會將每個命令執行為 `/path/to/logger.sh '<command>'`。包裝器在 `$1` 中接收命令行作為單個 shell 引用的引數，因此包裝器必須使用 shell 重新評估 `$1`，例如 `exec bash -c "$1"`。將 `$1` 視為裸可執行檔路徑會破壞傳遞引數的 stdio MCP 伺服器，例如 `npx -y <package>`。對於 Bash 工具呼叫，`$1` 包含 Claude Code 組裝的完整 shell 呼叫，包括環境設定，而不僅僅是 Claude 執行的命令 |

269| `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) |277| `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) |

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

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

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

278| `CLAUDE_CODE_SUBAGENT_MODEL` | 請參閱 [Model configuration](/zh-TW/model-config) |286| `CLAUDE_CODE_SUBAGENT_MODEL` | 請參閱 [Model configuration](/zh-TW/model-config)。{/* min-version: 2.1.196 */}自 v2.1.196 起，將其設定為 `inherit` 與不設定相同；較早版本將 `inherit` 視為覆蓋，強制每個 subagent 進入主對話的模型 |

279| `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` 會自動設定此項 |287| `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` 會自動設定此項 |

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

281| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步外掛程式安裝的逾時（以毫秒為單位）。超過時，Claude Code 會在沒有外掛程式的情況下繼續並記錄錯誤。無預設值：沒有此變數，同步安裝會等待直到完成 |289| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步外掛程式安裝的逾時（以毫秒為單位）。超過時，Claude Code 會在沒有外掛程式的情況下繼續並記錄錯誤。無預設值：沒有此變數，同步安裝會等待直到完成 |

295| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在沒有 Git Bash 的 Windows 上，工具會自動啟用；設定為 `0` 以停用它。在安裝了 Git Bash 的 Windows 上，工具正在逐步推出：設定為 `1` 以選擇加入或 `0` 以選擇退出。在 Linux、macOS 和 WSL 上，設定為 `1` 以啟用它，這需要您的 `PATH` 上有 `pwsh`。在 Windows 上啟用時，Claude 可以原生執行 PowerShell 命令，而不是透過 Git Bash 路由。請參閱 [PowerShell tool](/zh-TW/tools-reference#powershell-tool) |303| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在沒有 Git Bash 的 Windows 上，工具會自動啟用；設定為 `0` 以停用它。在安裝了 Git Bash 的 Windows 上，工具正在逐步推出：設定為 `1` 以選擇加入或 `0` 以選擇退出。在 Linux、macOS 和 WSL 上，設定為 `1` 以啟用它，這需要您的 `PATH` 上有 `pwsh`。在 Windows 上啟用時，Claude 可以原生執行 PowerShell 命令，而不是透過 Git Bash 路由。請參閱 [PowerShell tool](/zh-TW/tools-reference#powershell-tool) |

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

306| `CLAUDE_DISABLE_ADOPT` | {/* min-version: 2.1.195 */}設定為 `1` 以停止進行中的背景工作，而不是在您按 `←` 或使用 [`/background`](/zh-TW/agent-view#from-inside-a-session) 將工作階段背景化時帶入它。Claude Code 會要求您在背景化前確認，然後停止會以其他方式帶入的任務。需要 Claude Code v2.1.195 或更新版本 |

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

299| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設定為 `1` 以強制啟用位元級串流閒置監視程式，或設定為 `0` 以強制停用它。未設定時，監視程式預設對 Anthropic API 和 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 連線啟用。位元監視程式會在 180 秒內沒有位元組到達線路時中止連線（直接 Anthropic API 連線上預設為 180 秒，Claude Platform on AWS 和其他提供者上為 300 秒），或在設定 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 時為該值，該值被限制為最少 5 分鐘，獨立於事件級監視程式 |308| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 設定為 `1` 以強制啟用位元級串流閒置監視程式，或設定為 `0` 以強制停用它。未設定時，監視程式預設對 Anthropic API 和 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 連線啟用。位元監視程式會在 180 秒內沒有位元組到達線路時中止連線（直接 Anthropic API 連線上預設為 180 秒，Claude Platform on AWS 和其他提供者上為 300 秒），或在設定 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 時為該值，該值被限制為最少 5 分鐘，獨立於事件級監視程式 |

300| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設定為 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元級串流閒置監視程式。預設關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |309| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 設定為 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 回應上啟用位元級串流閒置監視程式。預設關閉。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |

301| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設定為 `1` 以強制啟用事件級串流閒置監視程式，或設定為 `0` 以強制停用它。未設定時，預設值由伺服器在直接 Anthropic API 上控制，在其他提供者上關閉。{/* min-version: 2.1.169 */}自 v2.1.169 起，直接 Anthropic API 和 Claude Platform on AWS 以外的提供者也有預設開啟的 5 分鐘主體閒置逾時，獨立於此變數；請參閱 `API_FORCE_IDLE_TIMEOUT`。在 Bedrock 上，您也可以使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` 啟用獨立的位元級監視程式；當兩者都設定時，它們一起執行。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |310| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 設定為 `1` 以強制啟用事件級串流閒置監視程式，或設定為 `0` 以強制停用它。{/* min-version: 2.1.196 */}未設定時，監視程式預設對所有提供者啟用。在 v2.1.196 之前，未設定的預設值由伺服器在直接 Anthropic API 上控制，在其他提供者上關閉。{/* min-version: 2.1.169 */}自 v2.1.169 起，直接 Anthropic API 和 Claude Platform on AWS 以外的提供者也有預設開啟的 5 分鐘主體閒置逾時，獨立於此變數；請參閱 `API_FORCE_IDLE_TIMEOUT`。在 Bedrock 上，您也可以使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` 啟用獨立的位元級監視程式；當兩者都設定時，它們一起執行。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置逾時 |

302| `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 動態填充 |311| `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 動態填充 |

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

304| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 串流閒置監視程式在關閉停滯連線之前的逾時（以毫秒為單位）。當您明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值會無聲地限制以吸收延伸思考暫停和代理緩衝。未設定時，事件級監視程式預設為 300 秒，位元級監視程式在直接 Anthropic API 連線上預設為 180 秒（Claude Platform on AWS 和其他提供者上為 300 秒）。未設定的 180 秒位元監視程式預設是一個單獨的值，不受 5 分鐘限制。對於第三方提供者上的事件級監視程式，需要 `CLAUDE_ENABLE_STREAM_WATCHDOG=1`；`API_FORCE_IDLE_TIMEOUT` 下描述的主體閒置逾時獨立適用。在 Bedrock 上，也適用於 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` |313| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 串流閒置監視程式在關閉停滯連線之前的逾時（以毫秒為單位）。當您明確設定此變數時，最小值為 `300000`（5 分鐘）；較低的值會無聲地限制以吸收延伸思考暫停和代理緩衝。未設定時，事件級監視程式預設為 300 秒，位元級監視程式在直接 Anthropic API 連線上預設為 180 秒（Claude Platform on AWS 和其他提供者上為 300 秒）。未設定的 180 秒位元監視程式預設是一個單獨的值，不受 5 分鐘限制。`API_FORCE_IDLE_TIMEOUT` 下描述的主體閒置逾時獨立適用。在 Bedrock 上，也適用於 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` |

305| `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:*`）不會觸發它 |314| `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:*`）不會觸發它 |

349| `MCP_TOOL_TIMEOUT` | MCP 工具執行的逾時（以毫秒為單位）（預設值：100000000，約 28 小時）。`.mcp.json` 中的每個伺服器 `timeout` 欄位會覆蓋該伺服器的此值。對於環境變數，低於 1000 的值會下限為 1 秒；對於每個伺服器欄位，低於 1000 的值會被忽略 |358| `MCP_TOOL_TIMEOUT` | MCP 工具執行的逾時（以毫秒為單位）（預設值：100000000，約 28 小時）。`.mcp.json` 中的每個伺服器 `timeout` 欄位會覆蓋該伺服器的此值。對於環境變數，低於 1000 的值會下限為 1 秒；對於每個伺服器欄位，低於 1000 的值會被忽略 |

360| `OTEL_LOG_ASSISTANT_RESPONSES` | {/* min-version: 2.1.193 */}設定為 `1` 以在 `assistant_response` OpenTelemetry 日誌事件上包含模型的回應文字。未設定時，使用 `OTEL_LOG_USER_PROMPTS` 的值。設定為 `0` 以保持回應編輯，即使設定 `OTEL_LOG_USER_PROMPTS`。需要 Claude Code v2.1.193 或更新版本。請參閱 [Monitoring](/zh-TW/monitoring-usage#assistant-response-event) |

351| `OTEL_LOG_RAW_API_BODIES` | 設定為 `1` 以將完整的 Anthropic Messages API 請求和回應 JSON 作為 `api_request_body` / `api_response_body` 日誌事件發出（在 60 KB 處截斷），或 `file:<dir>` 以將未截斷的主體寫入磁碟並發出 `body_ref` 路徑。預設停用；主體包括整個對話歷史記錄。請參閱 [Monitoring](/zh-TW/monitoring-usage#api-request-body-event) |361| `OTEL_LOG_RAW_API_BODIES` | 設定為 `1` 以將完整的 Anthropic Messages API 請求和回應 JSON 作為 `api_request_body` / `api_response_body` 日誌事件發出（在 60 KB 處截斷），或 `file:<dir>` 以將未截斷的主體寫入磁碟並發出 `body_ref` 路徑。預設停用；主體包括整個對話歷史記錄。請參閱 [Monitoring](/zh-TW/monitoring-usage#api-request-body-event) |

352| `OTEL_LOG_TOOL_CONTENT` | 設定為 `1` 以在 OpenTelemetry span 事件中包含工具輸入和輸出內容。預設停用以保護敏感資料。請參閱 [Monitoring](/zh-TW/monitoring-usage) |362| `OTEL_LOG_TOOL_CONTENT` | 設定為 `1` 以在 OpenTelemetry span 事件中包含工具輸入和輸出內容。預設停用以保護敏感資料。請參閱 [Monitoring](/zh-TW/monitoring-usage) |

353| `OTEL_LOG_TOOL_DETAILS` | 設定為 `1` 以在 OpenTelemetry 追蹤和日誌中包含工具輸入引數、MCP 伺服器名稱、工具失敗時的原始錯誤字串、`api_refusal` 事件上的拒絕 `category` 和其他工具詳細資訊。預設停用以保護個人識別資訊。請參閱 [Monitoring](/zh-TW/monitoring-usage) |363| `OTEL_LOG_TOOL_DETAILS` | 設定為 `1` 以在 OpenTelemetry 追蹤和日誌中包含工具輸入引數、MCP 伺服器名稱、工具失敗時的原始錯誤字串、`api_refusal` 事件上的拒絕 `category` 和其他工具詳細資訊。預設停用以保護個人識別資訊。請參閱 [Monitoring](/zh-TW/monitoring-usage) |

373| `VERTEX_REGION_CLAUDE_4_7_OPUS` | {/* min-version: 2.1.111 */}使用 Vertex AI 時覆蓋 Claude Opus 4.7 的區域。在 v2.1.111 中新增 |383| `VERTEX_REGION_CLAUDE_4_7_OPUS` | {/* min-version: 2.1.111 */}使用 Vertex AI 時覆蓋 Claude Opus 4.7 的區域。在 v2.1.111 中新增 |

374| `VERTEX_REGION_CLAUDE_4_8_OPUS` | {/* min-version: 2.1.154 */}使用 Vertex AI 時覆蓋 Claude Opus 4.8 的區域。在 v2.1.154 中新增 |384| `VERTEX_REGION_CLAUDE_4_8_OPUS` | {/* min-version: 2.1.154 */}使用 Vertex AI 時覆蓋 Claude Opus 4.8 的區域。在 v2.1.154 中新增 |

385| `VERTEX_REGION_CLAUDE_5_SONNET` | {/* min-version: 2.1.197 */}使用 Vertex AI 時覆蓋 Claude Sonnet 5 的區域。在 v2.1.197 中新增 |

375| `VERTEX_REGION_CLAUDE_FABLE_5` | {/* min-version: 2.1.170 */}使用 Vertex AI 時覆蓋 Claude Fable 5 的區域。在 v2.1.170 中新增 |386| `VERTEX_REGION_CLAUDE_FABLE_5` | {/* min-version: 2.1.170 */}使用 Vertex AI 時覆蓋 Claude Fable 5 的區域。在 v2.1.170 中新增 |

377 388

errors.md +138 −10

Details

25| `API Error: 500 Internal server error` | [Server errors](#api-error-500-internal-server-error) |25| `API Error: 500 Internal server error` | [Server errors](#api-error-500-internal-server-error) |

26| `API Error: Repeated 529 Overloaded errors` | [Server errors](#api-error-repeated-529-overloaded-errors) |26| `API Error: Repeated 529 Overloaded errors` | [Server errors](#api-error-repeated-529-overloaded-errors) |

28| `Server error mid-response. The response above may be incomplete.` | [Server errors](#the-response-above-may-be-incomplete) |

29| `Connection closed mid-response` / `Response stalled mid-stream` | [Server errors](#the-response-above-may-be-incomplete) |

28| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |30| `<model> is temporarily unavailable, so auto mode cannot determine the safety of...` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |

29| `Auto mode could not evaluate this action and is blocking it for safety` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |31| `Auto mode could not evaluate this action and is blocking it for safety` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |

30| `Auto mode classifier transcript exceeded context window` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |32| `Auto mode classifier transcript exceeded context window` | [Server errors](#auto-mode-cannot-determine-the-safety-of-an-action) |

33| `Agent terminated early due to an API error` | [Server errors](#agent-terminated-early-due-to-an-api-error) |

31| `You've hit your session limit` / `You've hit your weekly limit` | [Usage limits](#you%E2%80%99ve-hit-your-session-limit) |34| `You've hit your session limit` / `You've hit your weekly limit` | [Usage limits](#you%E2%80%99ve-hit-your-session-limit) |

32| `Usage credits required for 1M context` | [Usage limits](#usage-credits-required-for-1m-context) |35| `Usage credits required for 1M context` | [Usage limits](#usage-credits-required-for-1m-context) |

33| `Server is temporarily limiting requests` | [Usage limits](#server-is-temporarily-limiting-requests) |36| `Server is temporarily limiting requests` | [Usage limits](#server-is-temporarily-limiting-requests) |

43| `Remote Control is only available when using Claude via api.anthropic.com` | [Authentication](#remote-control-requires-the-anthropic-api) |46| `Remote Control is only available when using Claude via api.anthropic.com` | [Authentication](#remote-control-requires-the-anthropic-api) |

44| `OAuth token revoked` / `OAuth token has expired` | [Authentication](#oauth-token-revoked-or-expired) |47| `OAuth token revoked` / `OAuth token has expired` | [Authentication](#oauth-token-revoked-or-expired) |

45| `does not meet scope requirement user:profile` | [Authentication](#oauth-scope-requirement) |48| `does not meet scope requirement user:profile` | [Authentication](#oauth-scope-requirement) |

49| `AWS credentials expired or invalid` | [Authentication](#aws-credentials-expired-or-invalid) |

50| `AWS authentication failed` | [Authentication](#aws-authentication-failed) |

46| `Unable to connect to API` | [Network](#unable-to-connect-to-api) |51| `Unable to connect to API` | [Network](#unable-to-connect-to-api) |

47| `Waiting for API response · will retry in` | [Automatic retries](#automatic-retries)，或如果持續發生，則為 [Network](#unable-to-connect-to-api) |52| `Waiting for API response · will retry in` | [Automatic retries](#automatic-retries)，或如果持續發生，則為 [Network](#unable-to-connect-to-api) |

48| `SSL certificate verification failed` | [Network](#ssl-certificate-errors) |53| `SSL certificate verification failed` | [Network](#ssl-certificate-errors) |

54| `SSL certificate error (...)` during login or startup | [Network](#ssl-certificate-errors) |

49| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [Network](#host-not-allowed-in-a-cloud-session) |55| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [Network](#host-not-allowed-in-a-cloud-session) |

50| `Prompt is too long` | [Request errors](#prompt-is-too-long) |56| `Prompt is too long` | [Request errors](#prompt-is-too-long) |

51| `Error during compaction: Conversation too long` | [Request errors](#error-during-compaction-conversation-too-long) |57| `Error during compaction: Conversation too long` | [Request errors](#error-during-compaction-conversation-too-long) |

61| `max_tokens must be greater than thinking.budget_tokens` | [Request errors](#thinking-budget-exceeds-output-limit) |67| `max_tokens must be greater than thinking.budget_tokens` | [Request errors](#thinking-budget-exceeds-output-limit) |

62| `API Error: 400 due to tool use concurrency issues` | [Request errors](#tool-use-or-thinking-block-mismatch) |68| `API Error: 400 due to tool use concurrency issues` | [Request errors](#tool-use-or-thinking-block-mismatch) |

63| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [Request errors](#usage-policy-refusal) |69| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [Request errors](#usage-policy-refusal) |

70| `--bg and --print conflict` | [Command-line errors](#command-line-errors) |

64| 回應品質似乎低於平常 | [Response quality](#responses-seem-lower-quality-than-usual) |71| 回應品質似乎低於平常 | [Response quality](#responses-seem-lower-quality-than-usual) |

65 72

66<h2 id="automatic-retries">73<h2 id="automatic-retries">

67 自動重試74 自動重試

68</h2>75</h2>

69 76

70Claude Code 在向您顯示錯誤之前會重試暫時性失敗。伺服器錯誤、過載回應、請求逾時、臨時 429 節流和中斷的連線都會以指數退避方式重試最多 10 次。重試時，微調器會顯示 `Retrying in Ns · attempt x/y` 倒數計時。77Claude Code 在向您顯示錯誤之前會重試暫時性失敗。伺服器錯誤、過載回應、請求逾時、臨時 429 節流和中斷的連線都會以指數退避方式重試最多 10 次。{/* min-version: 2.1.198 */}自 v2.1.198 起，這涵蓋在任何可見輸出串流之前在回應中途中斷的連線：Claude Code 使用相同的退避重新發出請求，轉向繼續而不是停止並出現連線錯誤。{/* min-version: 2.1.199 */}自 v2.1.199 起，不帶您計畫配額標頭的臨時 429 節流在您使用 claude.ai 訂閱登入時也會重試；較早的版本僅針對 API 金鑰和 Enterprise 登入重試它們。

79有兩個失敗類別不會重試，因為重試無法成功：

81* {/* min-version: 2.1.199 */}自 v2.1.199 起，TLS 憑證驗證失敗（例如 TLS 檢查代理、遺失的 `NODE_EXTRA_CA_CERTS` 套件或過期的憑證）在第一次嘗試時失敗，因此修復會立即出現，而不是在完整重試預算之後。請參閱 [SSL certificate errors](#ssl-certificate-errors)。暫時性 TLS 條件（例如握手逾時）仍會重試。

82* {/* min-version: 2.1.199 */}自 v2.1.199 起，在 Claude 已經串流可見輸出後到達的伺服器錯誤會保留部分回應並附加 [incomplete-response notice](#the-response-above-may-be-incomplete)，而不是重試，因為重新執行請求可能會執行相同的工具兩次。較早的版本會捨棄部分輸出並將轉向報告為錯誤。

84重試時，微調器會在錯誤標籤後顯示 `Retrying in Ns · attempt x/y` 倒數計時。標籤命名第一次嘗試的特定原因，以便您可以立即採取行動的失敗：網路已關閉、TLS 握手失敗或您達到速率限制。對於其他錯誤，它最初讀取 `API error`。{/* min-version: 2.1.198 */}自 v2.1.198 起，它會切換到第三次嘗試的特定原因，或在 `CLAUDE_CODE_MAX_RETRIES` 允許少於三次時的最後一次嘗試；較早的版本僅在最後一次嘗試時切換。

86{/* min-version: 2.1.198 */}自 v2.1.198 起，通常的微調器提示在重試期間被抑制。一旦錯誤原因被揭示，如果失敗是 529 過載，倒數計時下方的行也會命名檢查服務狀態的位置：Anthropic API 上的 `status.claude.com`，或其他配置上提供者或閘道主機命名的位置。

71 87

72{/* min-version: 2.1.185 */}如果在請求仍待處理時，回應串流上 20 秒內沒有資料到達，微調器會在任何重試開始之前顯示 `Waiting for API response · will retry in … · check your network`。請求尚未失敗：倒數計時會執行到 Claude Code 中止停滯連線並重試的位置，因此一旦資料恢復或重試成功，橫幅就會自動清除。自 v2.1.185 起，閾值為 20 秒；較早的版本會在 10 秒後顯示橫幅，措辭不同。如果它在每次嘗試時都重新出現，請將其視為[網路問題](#unable-to-connect-to-api)。88{/* min-version: 2.1.185 */}如果在請求仍待處理時，回應串流上 20 秒內沒有資料到達，微調器會在任何重試開始之前顯示 `Waiting for API response · will retry in … · check your network`。請求尚未失敗：倒數計時會執行到 Claude Code 中止停滯連線並重試的位置，因此一旦資料恢復或重試成功，橫幅就會自動清除。自 v2.1.185 起，閾值為 20 秒；較早的版本會在 10 秒後顯示橫幅，措辭不同。如果它在每次嘗試時都重新出現，請將其視為[網路問題](#unable-to-connect-to-api)。

73 89

~~74當您看到本頁上的其中一個錯誤時，這些重試已經用盡。您可以使用這些環境變數調整行為：~~90當您看到本頁上的其中一個錯誤時，這些重試已經用盡，除非它屬於不會重試的類別，例如憑證驗證失敗。您可以使用這些環境變數調整行為：

75 91

76| 變數 | 預設值 | 效果 |92| 變數 | 預設值 | 效果 |

~~77| :---------------------------------------------- | :----- | :----------------------------------------------------------------------------------------- |~~93| :---------------------------------------------- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

78| [`CLAUDE_CODE_MAX_RETRIES`](/zh-TW/env-vars) | 10 | 重試次數。{/* min-version: 2.1.186 */}自 v2.1.186 起上限為 15。降低它以在指令碼中更快地顯示失敗。 |94| [`CLAUDE_CODE_MAX_RETRIES`](/zh-TW/env-vars) | 10 | 重試次數。{/* min-version: 2.1.186 */}自 v2.1.186 起上限為 15；{/* min-version: 2.1.199 */}自 v2.1.199 起 `CLAUDE_CODE_RETRY_WATCHDOG` 提高預設值並移除上限。降低它以在指令碼中更快地顯示失敗。 |

79| [`CLAUDE_CODE_RETRY_WATCHDOG`](/zh-TW/env-vars) | 未設定 | 在 CI 工作等無人值守的工作階段中設定為 `1`，以無限期重試 `429` 和 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次嘗試後失敗。 |95| [`CLAUDE_CODE_RETRY_WATCHDOG`](/zh-TW/env-vars) | 未設定 | 在 CI 工作等無人值守的工作階段中設定為 `1`，以無限期重試 `429` 和 `529` 容量錯誤，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次嘗試後失敗。{/* min-version: 2.1.199 */}自 v2.1.199 起，它也提高了其他暫時性錯誤（例如伺服器錯誤、逾時和中斷的連線）的預設重試計數至 300，大約三小時的退避，並在您明確設定該變數時移除 `CLAUDE_CODE_MAX_RETRIES` 的上限 15。 |

80| [`API_TIMEOUT_MS`](/zh-TW/env-vars) | 600000 | 每個請求的逾時（毫秒）。為慢速網路或代理提高它。 |96| [`API_TIMEOUT_MS`](/zh-TW/env-vars) | 600000 | 每個請求的逾時（毫秒）。為慢速網路或代理提高它。 |

81 97

82<h2 id="server-errors">98<h2 id="server-errors">

103 119

104* 檢查 [status.claude.com](https://status.claude.com) 或訊息中命名的提供者狀態頁面，以了解活躍的事件120* 檢查 [status.claude.com](https://status.claude.com) 或訊息中命名的提供者狀態頁面，以了解活躍的事件

105* 等待一分鐘，然後再次傳送您的訊息。您的原始訊息仍在對話中，因此對於長提示，您可以輸入 `try again` 而不是貼上整個內容。121* 等待一分鐘，然後再次傳送您的訊息。您的原始訊息仍在對話中，因此對於長提示，您可以輸入 `try again` 而不是貼上整個內容。

106* 如果錯誤持續存在且沒有發佈的事件，請執行 `/feedback` 以便 Anthropic 可以使用您的請求詳細資訊進行調查。如果您的環境中 `/feedback` 不可用，請參閱 [回報錯誤](#report-an-error)。122* 如果錯誤持續存在且沒有發佈的事件，請執行 `/feedback` 以便 Anthropic 可以使用您的請求詳細資訊進行調查。如果您的環境中 `/feedback` 不可用，請參閱 [Report an error](#report-an-error)。

107 123

108<h3 id="api-error-repeated-529-overloaded-errors">124<h3 id="api-error-repeated-529-overloaded-errors">

109 API Error: Repeated 529 Overloaded errors125 API Error: Repeated 529 Overloaded errors

142* 如果原因是慢速網路或代理，請按照 [Automatic retries](#automatic-retries) 中的說明提高 `API_TIMEOUT_MS`158* 如果原因是慢速網路或代理，請按照 [Automatic retries](#automatic-retries) 中的說明提高 `API_TIMEOUT_MS`

143* 如果逾時頻繁且您的網路在其他方面是健康的，請參閱下面的 [Network and connection errors](#network-and-connection-errors)159* 如果逾時頻繁且您的網路在其他方面是健康的，請參閱下面的 [Network and connection errors](#network-and-connection-errors)

144 160

161<h3 id="the-response-above-may-be-incomplete">

162 The response above may be incomplete

163</h3>

164

165串流回應在 Claude 已經產生可見輸出後失敗。重新傳送請求可能會執行相同的工具呼叫兩次，因此 Claude Code 會保留已經串流的內容並附加此通知，而不是捨棄轉向。您看到的變體命名原因：

166

167```text theme={null}

168API Error: Server error mid-response. The response above may be incomplete.

169API Error: Connection closed mid-response. The response above may be incomplete.

170API Error: Response stalled mid-stream. The response above may be incomplete.

171```

172

173* {/* min-version: 2.1.199 */}}`Server error mid-response`：中途過載或 5xx 伺服器錯誤。此變體需要 Claude Code v2.1.199 或更新版本；在此之前，該情況會捨棄部分輸出並將整個轉向報告為錯誤。

174* `Connection closed mid-response`：連線已中斷。

175* `Response stalled mid-stream`：串流停止傳送資料。

176

177**要做什麼：**

178

179* 閱讀串流的回應。沒有任何內容遺失，但最後的句子或工具呼叫可能會遺失。

180* 回覆 `continue` 以讓 Claude 從停止的地方繼續

181* 如果相同的錯誤在任何可見輸出之前出現，Claude Code 會重試請求，而不是完成它。請參閱 [Automatic retries](#automatic-retries)。

182

145<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">183<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">

146 Auto mode cannot determine the safety of an action184 Auto mode cannot determine the safety of an action

147</h3>185</h3>

186* 在出現的提示中批准或拒絕該動作224* 在出現的提示中批准或拒絕該動作

187* 執行 `/compact` 以減少對話大小，以便後續動作再次適應分類器視窗內225* 執行 `/compact` 以減少對話大小，以便後續動作再次適應分類器視窗內

188 226

227<h3 id="agent-terminated-early-due-to-an-api-error">

228 Agent terminated early due to an API error

229</h3>

230

231{/* min-version: 2.1.199 */}[subagent](/zh-TW/sub-agents) 的 API 請求終止失敗，例如因為達到使用限制或伺服器錯誤的重試用盡，因此子代理在完成其任務之前停止。此訊息需要 Claude Code v2.1.199 或更新版本；在此之前，API 錯誤文字被傳回給 Claude，就像它是子代理的結果一樣。

232

233```text theme={null}

234Agent terminated early due to an API error: <error detail>

235```

236

237**要做什麼：**

238

239* 將冒號後的錯誤詳細資訊與本頁上的其自己的部分相符，例如 [Usage limits](#usage-limits) 或 [Server errors](#server-errors)，並遵循該部分的步驟

240* 一旦基礎錯誤清除，要求 Claude 重試任務或 [resume the subagent](/zh-TW/sub-agents#resume-subagents)

241

242當速率限制、過載或伺服器錯誤中斷已經產生輸出的前景子代理時，Claude 會收到該部分輸出標記為不完整，而不是此錯誤。請參閱 [API errors in subagents](/zh-TW/sub-agents#api-errors-in-subagents)。

243

189<h2 id="usage-limits">244<h2 id="usage-limits">

190 使用限制245 使用限制

191</h2>246</h2>

246API Error: Server is temporarily limiting requests (not your usage limit)301API Error: Server is temporarily limiting requests (not your usage limit)

247```302```

248 303

249這在顯示之前會 [retried automatically](#automatic-retries)。304Claude Code 透過缺少真實限制回應所帶的統一配額標頭來區分這些。{/* min-version: 2.1.199 */}自 v2.1.199 起，這會 [自動重試](#automatic-retries)，無論您如何認證。在較早的版本上，使用 claude.ai 訂閱登入的工作階段在第一次出現時失敗轉向；只有 API 金鑰和 Enterprise 登入重試它。

250 305

251**要做什麼：**306**要做什麼：**

252 307

373 Your organization has disabled API key authentication428 Your organization has disabled API key authentication

374</h3>429</h3>

375 430

376您的 Console 組織管理員已關閉 API 金鑰認證，因此 API 拒絕了 Claude Code 正在傳送的金鑰。`·` 之後的復原提示會根據金鑰的來源而異：431此訊息需要 Claude Code v2.1.169 或更新版本。您的 Console 組織管理員已關閉 API 金鑰認證，因此 API 拒絕了 Claude Code 正在傳送的金鑰。`·` 之後的復原提示會根據金鑰的來源而異：

377 432

378```text theme={null}433```text theme={null}

379Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account434Your organization has disabled API key authentication · Run /login to sign in with your claude.ai account

437Remote Control is only available when using Claude via api.anthropic.com.492Remote Control is only available when using Claude via api.anthropic.com.

438```493```

439 494

440這會出現在 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 上。{/* min-version: 2.1.196 */}從 v2.1.196 開始，當 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 指向 `api.anthropic.com` 以外的主機時，例如 [LLM gateway](/zh-TW/llm-gateway) 或代理，即使您使用 claude.ai 登入，它也會出現。495這會出現在 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 上。{/* min-version: 2.1.196 */}自 v2.1.196 開始，當 [`ANTHROPIC_BASE_URL`](/zh-TW/env-vars) 指向 `api.anthropic.com` 以外的主機時，例如 [LLM gateway](/zh-TW/llm-gateway) 或代理，即使您使用 claude.ai 登入，它也會出現。

441 496

442**要做什麼：**497**要做什麼：**

443 498

477 532

478* 執行 `/login` 以使用目前的範圍鑄造新令牌。您不需要先登出。533* 執行 `/login` 以使用目前的範圍鑄造新令牌。您不需要先登出。

479 534

535<h3 id="aws-credentials-expired-or-invalid">

536 AWS credentials expired or invalid

537</h3>

538

539{/* min-version: 2.1.198 */}此訊息需要 Claude Code v2.1.198 或更新版本，且僅在 [`awsAuthRefresh`](/zh-TW/amazon-bedrock#advanced-credential-configuration) 在您的設定檔案中設定時出現。您的 AWS 工作階段令牌過期或被拒絕，而 Claude Code 已經執行的自動重新整理沒有產生 API 接受的認證。它出現在來自 [Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 或 [Mantle endpoint](/zh-TW/amazon-bedrock#use-the-mantle-endpoint) 的 401，這是這些提供者報告過期安全令牌的方式。

540

541中間的動作提示命名您設定中的 `awsAuthRefresh` 命令，因此它會有所不同。穩定的部分是前導 `AWS credentials expired or invalid`：

542

543```text theme={null}

544AWS credentials expired or invalid · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · API Error: 401 ...

545```

546

547如果未配置 `awsAuthRefresh`，相同的 401 會改為顯示通用 `Please run /login` 訊息，無法重新整理 AWS 認證。

548

549**要做什麼：**

550

551* 在另一個終端中執行訊息中命名的 `awsAuthRefresh` 命令（例如 `aws sso login --profile myprofile`）並完成瀏覽器登入，然後重試

552* 在互動式工作階段中，執行 `/login`，選擇 **3rd-party platform**，然後在 **Using 3rd-party platforms** 下選擇 **Claude Platform on AWS · refresh credentials** 以執行相同的命令而無需重新啟動 Claude Code。請參閱 [Configure AWS credentials](/zh-TW/claude-platform-on-aws#1-configure-aws-credentials)

553* 如果重新整理命令成功後錯誤重複出現，請在同一 shell 和設定檔中使用 `aws sts get-caller-identity` 確認身份在 Claude Code 外有效

554

555<h3 id="aws-authentication-failed">

556 AWS authentication failed

557</h3>

558

559{/* min-version: 2.1.198 */}此訊息需要 Claude Code v2.1.198 或更新版本，且僅在 [`awsAuthRefresh`](/zh-TW/amazon-bedrock#advanced-credential-configuration) 在您的設定檔案中設定時出現。您的 AWS 提供者傳回 403，或 [Amazon Bedrock](/zh-TW/amazon-bedrock) 傳回 401。

560

561Claude Code 無法判斷您遇到的是哪個原因。Amazon Bedrock 將過期的安全令牌報告為 403，但 403 也是它報告授權拒絕的方式，例如來自遺失 IAM 權限或未為您的帳戶啟用的模型的 `AccessDeniedException`。

562

563來自 Amazon Bedrock 的 401 也會落在這裡，而不是在 [AWS credentials expired or invalid](#aws-credentials-expired-or-invalid) 下，因為 Bedrock 不會將過期令牌報告為 401。來自該端點的 401 通常來自請求路徑中的其他內容，例如公司代理。

564

565認證重新整理可以修復過期令牌，無法修復其他原因，因此訊息提供兩者：

566

567```text theme={null}

568AWS authentication failed · run /login and select "Claude Platform on AWS · refresh credentials", or run `aws sso login --profile myprofile` in another terminal · if credentials are current, check AWS permissions and model access · API Error: 403 ...

569```

570

571中間的動作提示命名您設定中的 `awsAuthRefresh` 命令，因此它會有所不同。穩定的部分是前導 `AWS authentication failed`。

572

573**要做什麼：**

574

575* 執行訊息中命名的 `awsAuthRefresh` 命令或 `aws sso login`，以防過期認證是原因

576* 如果您的認證是最新的，請確認 [IAM configuration](/zh-TW/amazon-bedrock#iam-configuration) 中的 IAM 權限已附加到您使用的身份，並且所選模型已為您的帳戶和區域啟用

577* 執行 `aws sts get-caller-identity` 以確認您的請求使用哪個身份；過時的 `AWS_PROFILE` 或預設設定檔是權限不匹配的常見原因

578

480<h2 id="network-and-connection-errors">579<h2 id="network-and-connection-errors">

481 網路和連線錯誤580 網路和連線錯誤

482</h2>581</h2>

525Unable to connect to API: Self-signed certificate detected624Unable to connect to API: Self-signed certificate detected

526```625```

527 626

627{/* min-version: 2.1.199 */}自 v2.1.199 起，憑證驗證失敗不會重試，因此此錯誤會在第一次嘗試時出現，而不是在完整 [retry budget](#automatic-retries) 之後。較早的版本會在顯示之前重試幾分鐘。暫時性 TLS 條件（例如握手逾時）仍會重試。

628

629在 `/login` 和啟動連線檢查期間，相同的失敗會以 OpenSSL 代碼和內聯修復報告：

630

631```text theme={null}

632SSL certificate error (UNABLE_TO_GET_ISSUER_CERT_LOCALLY). If you are behind a corporate proxy or TLS-intercepting firewall, set NODE_EXTRA_CA_CERTS to your CA bundle path, or ask IT to allowlist *.anthropic.com. Run /doctor for details.

633```

634

528**要做什麼：**635**要做什麼：**

529 636

530* 匯出您組織的 CA 套件，並使用 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` 指向 Claude Code637* 匯出您組織的 CA 套件，並使用 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` 指向 Claude Code

811* 如果您無法識別哪個轉向導致了它，請執行 `/clear` 以在同一專案中啟動新的對話。您之前的對話已保留在磁碟上，並在 `/resume` 中保持可用。918* 如果您無法識別哪個轉向導致了它，請執行 `/clear` 以在同一專案中啟動新的對話。您之前的對話已保留在磁碟上，並在 `/resume` 中保持可用。

812* 在 [non-interactive mode](/zh-TW/headless)（`-p`）中，其中無法使用 rewind，請使用重新表述的提示重試或啟動新的工作階段而不使用 `--continue`。政策檢查因模型而異，因此使用 `--model` 切換到不同的模型也可能在某些情況下解決拒絕。919* 在 [non-interactive mode](/zh-TW/headless)（`-p`）中，其中無法使用 rewind，請使用重新表述的提示重試或啟動新的工作階段而不使用 `--continue`。政策檢查因模型而異，因此使用 `--model` 切換到不同的模型也可能在某些情況下解決拒絕。

813 920

921<h2 id="command-line-errors">

922 命令列錯誤

923</h2>

924

925這些錯誤來自 Claude Code 自己對 `claude` 命令列的驗證。Claude Code 會立即列印它們，在建立工作階段或傳送任何 API 請求之前。

926

927<h3 id="conflict-between-bg-and-print">

928 Conflict between --bg and --print

929</h3>

930

931此訊息需要 Claude Code v2.1.198 或更新版本。您在同一個 `claude` 呼叫中結合了 `--bg` 與 `-p` 或 `--print`。`--bg` 啟動 [background session](/zh-TW/agent-view#from-your-shell)，您稍後使用 `claude agents` 附加到，而 `--print` 執行 [non-interactively](/zh-TW/headless) 並從不啟動 `claude agents` 附加到的互動式工作階段。在 v2.1.198 之前，此組合無聲地建立了一個無法附加到的背景工作。

932

933```text theme={null}

934--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.

935```

936

937**要做什麼：**

938

939* 放棄 `-p` 或 `--print`。`--bg` 將提示作為其位置引數，因此 `claude --bg "<task>"` 是完整的命令。請參閱 [Dispatch new agents from your shell](/zh-TW/agent-view#from-your-shell)。

940* 若要非互動式執行提示並列印結果而不是建立背景工作階段，請放棄 `--bg` 並執行 `claude -p "<task>"`

941

814<h2 id="responses-seem-lower-quality-than-usual">942<h2 id="responses-seem-lower-quality-than-usual">

815 回應品質似乎低於平常943 回應品質似乎低於平常

816</h2>944</h2>

838 報告錯誤966 報告錯誤

839</h2>967</h2>

840 968

841本頁涵蓋來自 Claude API 的錯誤。對於來自其他 Claude Code 元件的錯誤，請參閱相關指南：969對於此頁面未涵蓋的元件的錯誤，請參閱相關指南：

842 970

843* MCP 伺服器無法連線或認證：[MCP](/zh-TW/mcp)971* MCP 伺服器無法連線或認證：[MCP](/zh-TW/mcp)

844* Hook 指令碼失敗或阻止工具：[Debug hooks](/zh-TW/hooks#debug-hooks)972* Hook 指令碼失敗或阻止工具：[Debug hooks](/zh-TW/hooks#debug-hooks)

fullscreen.md +5 −3

Details

58* **點擊 `/` 命令或 `@` 檔案清單中的建議**以接受它。懸停會突顯游標下的列。58* **點擊 `/` 命令或 `@` 檔案清單中的建議**以接受它。懸停會突顯游標下的列。

59* **點擊選擇功能表中的選項**以選擇它。這涵蓋權限提示、`/model`、`/config` 和其他顯示選項清單的對話框。懸停會在游標下的列上顯示指標。{/* min-version: 2.1.187 */}需要 Claude Code v2.1.187 或更新版本。59* **點擊選擇功能表中的選項**以選擇它。這涵蓋權限提示、`/model`、`/config` 和其他顯示選項清單的對話框。懸停會在游標下的列上顯示指標。{/* min-version: 2.1.187 */}需要 Claude Code v2.1.187 或更新版本。

60* **點擊摺疊的工具結果**以展開它並查看完整輸出。再次點擊以摺疊。工具呼叫及其結果一起展開。只有有更多內容要顯示的訊息才可點擊。60* **點擊摺疊的工具結果**以展開它並查看完整輸出。再次點擊以摺疊。工具呼叫及其結果一起展開。只有有更多內容要顯示的訊息才可點擊。

61* **在 macOS 上按住 `Cmd`，或在 Linux 和 Windows 上按住 `Ctrl`，然後點擊 URL 或檔案路徑**以開啟它。工具輸出中的檔案路徑（例如在 Edit 或 Write 後列印的路徑）在您的預設應用程式中開啟。純 `http://` 和 `https://` URL 在您的瀏覽器中開啟。{/* min-version: 2.1.181 */}自 v2.1.181 起，不按住 `Cmd` 或 `Ctrl` 的純點擊不再開啟連結，符合原生終端行為。在 VS Code 整合終端和類似的基於 xterm.js 的終端中，Claude Code 遵從終端自己的連結處理程式，該處理程式使用相同的手勢。61* **在 macOS 上按住 `Cmd`，或在 Linux 和 Windows 上按住 `Ctrl`，然後點擊 URL 或檔案路徑**以開啟它。工具輸出中的檔案路徑（例如在 Edit 或 Write 後列印的路徑）在您的預設應用程式中開啟。純 `http://` 和 `https://` URL 在您的瀏覽器中開啟。{/* min-version: 2.1.181 */}自 v2.1.181 起，不按住 `Cmd` 或 `Ctrl` 的純點擊不再開啟連結，符合原生終端行為。某些 macOS 終端會將 `Cmd`+點擊轉發給執行中的應用程式，而不是自己開啟連結，且終端滑鼠協議無法編碼 `Cmd` 鍵，所以 Claude Code 將其接收為純點擊。在 Ghostty 中，以及{/* min-version: 2.1.198 */}自 v2.1.198 起在 macOS 上的 Warp 中，Claude Code 偵測到這一點並讓純點擊連結開啟它，按住 `Cmd` 仍然有效。在 VS Code 整合終端和類似的基於 xterm.js 的終端中，Claude Code 遵從終端自己的連結處理程式，該處理程式使用相同的手勢。

~~62* **點擊並拖曳**以在對話中的任何位置選擇文字。雙擊選擇一個單詞，符合 iTerm2 的單詞邊界，因此檔案路徑選擇為一個單位。三擊選擇該行。~~62* **點擊並拖曳**以在對話中的任何位置選擇文字。雙擊選擇一個單詞，符合 iTerm2 的單詞邊界，因此檔案路徑選擇為一個單位。{/* min-version: 2.1.198 */}自 v2.1.198 起，雙擊 URL 會選擇整個 URL，包括配置。三擊選擇該行。

63* **使用滑鼠滾輪捲動**以在對話中移動。63* **使用滑鼠滾輪捲動**以在對話中移動。

64 64

65選定的文字在滑鼠釋放時自動複製到您的剪貼簿。若要關閉此功能，請在 `/config` 中切換「選擇時複製」。關閉後，按 `Ctrl+Shift+c` 手動複製。在支援 kitty 鍵盤協議的終端上，例如 kitty、WezTerm、Ghostty 和 iTerm2，`Cmd+c` 也可以運作。如果您有活動選擇，`Ctrl+c` 複製而不是取消。65選定的文字在滑鼠釋放時自動複製到您的剪貼簿。若要關閉此功能，請在 `/config` 中切換「選擇時複製」。

67關閉「選擇時複製」後，按 `Ctrl+Shift+c` 手動複製。在支援 kitty 鍵盤協議的終端上，例如 kitty、WezTerm、Ghostty 和 iTerm2，`Cmd+c` 也可以運作。如果您有活動選擇，`Ctrl+c` 複製而不是取消。

66 68

67有活動選擇時，按住 `Shift` 並按方向鍵以從鍵盤延伸它。`Shift+↑` 和 `Shift+↓` 在選擇到達頂部或底部邊緣時捲動檢視區。`Shift+Home` 和 `Shift+End` 延伸到目前行的開始或結束。69有活動選擇時，按住 `Shift` 並按方向鍵以從鍵盤延伸它。`Shift+↑` 和 `Shift+↓` 在選擇到達頂部或底部邊緣時捲動檢視區。`Shift+Home` 和 `Shift+End` 延伸到目前行的開始或結束。

68 70

gateways.md +1 −1

Details

44 Claude 應用程式閘道44 Claude 應用程式閘道

45</h3>45</h3>

46 46

47Claude 應用程式閘道是 Anthropic 的自託管閘道，包含在 `claude` 二進位檔案中。它路由到 Amazon Bedrock、Google Cloud、Microsoft Foundry 或 Anthropic API 作為上游。開發人員透過 `/login` 使用您的公司身份提供者登入，閘道按 IdP 群組強制執行模型存取和 [受管設定](/zh-TW/permissions#managed-settings)，並向您自己的可觀測性堆疊發出 [OpenTelemetry Protocol (OTLP)](/zh-TW/monitoring-usage) 使用情況指標。47Claude 應用程式閘道是 Anthropic 的自託管閘道，包含在 `claude` 二進位檔案中。它路由到 Amazon Bedrock、Claude Platform on AWS、Google Cloud、Microsoft Foundry 或 Anthropic API 作為上游。開發人員透過 `/login` 使用您的公司身份提供者登入，閘道按 IdP 群組強制執行模型存取和 [受管設定](/zh-TW/permissions#managed-settings)，並向您自己的可觀測性堆疊發出 [OpenTelemetry Protocol (OTLP)](/zh-TW/monitoring-usage) 使用情況指標。

48 48

49因為它與每個 Claude Code 版本一起構建和測試，所以它轉發 Claude Code 傳送的標頭和請求欄位。單獨維護的閘道需要其 [轉發規則隨著每個版本中這些標頭和欄位的變化而更新](/zh-TW/llm-gateway-protocol#forward-as-open-lists)；Claude 應用程式閘道與 CLI 一起發佈，因此沒有清單需要保持最新。有關在閘道工作階段上行為不同的小功能集，請參閱 [可用性和限制](/zh-TW/claude-apps-gateway#availability-and-limitations)。49因為它與每個 Claude Code 版本一起構建和測試，所以它轉發 Claude Code 傳送的標頭和請求欄位。單獨維護的閘道需要其 [轉發規則隨著每個版本中這些標頭和欄位的變化而更新](/zh-TW/llm-gateway-protocol#forward-as-open-lists)；Claude 應用程式閘道與 CLI 一起發佈，因此沒有清單需要保持最新。有關在閘道工作階段上行為不同的小功能集，請參閱 [可用性和限制](/zh-TW/claude-apps-gateway#availability-and-limitations)。

50 50

hooks.md +73 −39

Details

16 Hook 生命週期16 Hook 生命週期

17</h2>17</h2>

18 18

19Hooks 在 Claude Code 工作階段期間的特定時間點觸發。當事件觸發且匹配器匹配時，Claude Code 會將有關該事件的 JSON 上下文傳遞給您的 hook 處理程式。對於命令 hooks，輸入會到達 stdin。對於 HTTP hooks，它會作為 POST 請求正文到達。您的處理程式可以檢查輸入、採取行動，並可選擇性地返回決定。事件分為三種節奏：每個工作階段一次（`SessionStart`、`SessionEnd`）、每個轉向一次（`UserPromptSubmit`、`Stop`、`StopFailure`），以及代理迴圈內每個工具呼叫（`PreToolUse`、`PostToolUse`）：19Hooks 在 Claude Code 工作階段期間的特定時間點觸發。當事件觸發且匹配器匹配時，Claude Code 會將有關該事件的 JSON 上下文傳遞給您的 hook 處理程式。對於命令 hooks，輸入會到達 stdin。對於 HTTP hooks，它會作為 POST 請求正文到達。您的處理程式可以檢查輸入、採取行動，並可選擇性地返回決定。

21事件分為三種節奏：

23* 每個工作階段一次：`SessionStart` 和 `SessionEnd`

24* 每個轉向一次：`UserPromptSubmit`、`Stop` 和 `StopFailure`

25* 代理迴圈內每個工具呼叫：`PreToolUse` 和 `PostToolUse`

20 26

21<div style={{maxWidth: "500px", margin: "0 auto"}}>27<div style={{maxWidth: "500px", margin: "0 auto"}}>

22 <Frame>28 <Frame>

317 323

318所有匹配的 hooks 並行執行，相同的處理程式會自動去重。命令 hooks 按命令字串和 `args` 去重，HTTP hooks 按 URL 去重。324所有匹配的 hooks 並行執行，相同的處理程式會自動去重。命令 hooks 按命令字串和 `args` 去重，HTTP hooks 按 URL 去重。

319 325

320處理程式在目前目錄中執行，使用 Claude Code 的環境。在遠端網路環境中，`$CLAUDE_CODE_REMOTE` 環境變數設定為 `"true"`，在本機 CLI 中未設定。326處理程式在目前目錄中執行，使用 Claude Code 的環境。在遠端網路環境中，`$CLAUDE_CODE_REMOTE` 環境變數設定為 `"true"`，在本機 CLI 中未設定。{/* min-version: 2.1.199 */}自 v2.1.199 起，[`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/zh-TW/env-vars) 設定為 [Remote Control](/zh-TW/remote-control) 工作階段 ID，而本機工作階段具有活動的 Remote Control 連接。

321 327

322<h4 id="common-fields">328<h4 id="common-fields">

323 通用欄位329 通用欄位

704退出代碼 2 是 hook 發出「停止，不要這樣做」的方式。效果取決於事件，因為某些事件代表可以被阻止的操作（例如尚未發生的工具呼叫），而其他事件代表已經發生或無法防止的事情。710退出代碼 2 是 hook 發出「停止，不要這樣做」的方式。效果取決於事件，因為某些事件代表可以被阻止的操作（例如尚未發生的工具呼叫），而其他事件代表已經發生或無法防止的事情。

705 711

707| :-------------------- | :---- | :------------------------------------------------------------------------- |713| :-------------------- | :---- | :-------------------------------------------------------------------------- |

708| `PreToolUse` | 是 | 阻止工具呼叫 |714| `PreToolUse` | 是 | 阻止工具呼叫 |

709| `PermissionRequest` | 是 | 拒絕權限 |715| `PermissionRequest` | 是 | 拒絕權限 |

710| `UserPromptSubmit` | 是 | 阻止提示處理並清除提示 |716| `UserPromptSubmit` | 是 | 阻止提示處理並清除提示 |

711| `UserPromptExpansion` | 是 | 阻止擴展 |717| `UserPromptExpansion` | 是 | 阻止擴展 |

712| `Stop` | 是 | 防止 Claude 停止，繼續對話 |718| `Stop` | 是 | 防止 Claude 停止，繼續對話 |

713| `SubagentStop` | 是 | 防止 subagent 停止 |719| `SubagentStop` | 是 | 防止 subagent 停止 |

714| `TeammateIdle` | 是 | 防止隊友閒置（隊友繼續工作） |720| `TeammateIdle` | 是 | 防止隊友閒置，所以它繼續工作 |

715| `TaskCreated` | 是 | 回滾任務建立 |721| `TaskCreated` | 是 | 回滾任務建立 |

716| `TaskCompleted` | 是 | 防止任務被標記為已完成 |722| `TaskCompleted` | 是 | 防止任務被標記為已完成 |

717| `ConfigChange` | 是 | 阻止配置變更生效（除了 `policy_settings`） |723| `ConfigChange` | 是 | 阻止配置變更生效（除了 `policy_settings`） |

718| `StopFailure` | 否 | 輸出和退出代碼被忽略 |724| `StopFailure` | 否 | 輸出和退出代碼被忽略 |

719| `PostToolUse` | 否 | 向 Claude 顯示 stderr（工具已執行） |725| `PostToolUse` | 否 | 向 Claude 顯示 stderr；工具已執行 |

720| `PostToolUseFailure` | 否 | 向 Claude 顯示 stderr（工具已失敗） |726| `PostToolUseFailure` | 否 | 向 Claude 顯示 stderr；工具已失敗 |

721| `PostToolBatch` | 是 | 在下一個模型呼叫之前停止代理迴圈 |727| `PostToolBatch` | 是 | 在下一個模型呼叫之前停止代理迴圈 |

722| `PermissionDenied` | 否 | 退出代碼和 stderr 被忽略（拒絕已發生）。使用 JSON `hookSpecificOutput.retry: true` 告訴模型它可能重試 |728| `PermissionDenied` | 否 | 退出代碼和 stderr 被忽略，因為拒絕已發生。使用 JSON `hookSpecificOutput.retry: true` 告訴模型它可能重試 |

723| `Notification` | 否 | 僅向使用者顯示 stderr |729| `Notification` | 否 | 僅向使用者顯示 stderr |

724| `SubagentStart` | 否 | 僅向使用者顯示 stderr |730| `SubagentStart` | 否 | 僅向使用者顯示 stderr |

725| `SessionStart` | 否 | 僅向使用者顯示 stderr |731| `SessionStart` | 否 | 僅向使用者顯示 stderr |

736| `InstructionsLoaded` | 否 | 退出代碼被忽略 |742| `InstructionsLoaded` | 否 | 退出代碼被忽略 |

737| `MessageDisplay` | 否 | 原始文字被顯示 |743| `MessageDisplay` | 否 | 原始文字被顯示 |

738 744

745對於 `SessionStart`、`Setup` 和 `SubagentStart`，退出代碼 2 stderr 在成績單中呈現為 `<hook name> hook error` 通知，與 [非阻止性錯誤](#exit-code-output) 相同的方式。Claude 看不到它，工作階段或 subagent 繼續進行。對於 `SubagentStart`，通知出現在 subagent 自己的成績單中，而不是在父對話中。

746

747自 Claude Code v2.1.199 起，`SessionStart`、`Setup` 和 `SubagentStart` 在成績單中顯示退出代碼 2 stderr。較早的版本僅將其寫入詳細日誌。

748

739<h3 id="http-response-handling">749<h3 id="http-response-handling">

740 HTTP 回應處理750 HTTP 回應處理

741</h3>751</h3>

963 SessionStart 輸入973 SessionStart 輸入

964</h4>974</h4>

965 975

966除了 [通用輸入欄位](#common-input-fields) 外，SessionStart hooks 還接收 `source` 和可選的 `model`、`agent_type` 和 `session_title`。`source` 欄位指示工作階段如何啟動：新工作階段為 `"startup"`，恢復的工作階段為 `"resume"`，`/clear` 後為 `"clear"`，或壓縮後為 `"compact"`。`model` 欄位包含模型識別碼。它可以被省略，例如在 `/clear` 後或當工作階段通過對話恢復被恢復時，因此在讀取它之前檢查欄位。如果您使用 `claude --agent <name>` 啟動 Claude Code，`agent_type` 欄位包含代理名稱。`session_title` 欄位攜帶目前工作階段標題（如果已設定），例如通過 `--name` 或 `/rename`。發出 `sessionTitle` 的 hook 可以先檢查 `session_title` 以避免覆寫使用者明確設定的標題。976除了 [通用輸入欄位](#common-input-fields) 外，SessionStart hooks 還接收 `source` 和可選的 `model`、`agent_type` 和 `session_title`：

977

978| 欄位 | 描述 |

979| :-------------- | :------------------------------------------------------------------------------------------------------- |

980| `source` | 工作階段如何啟動：新工作階段為 `"startup"`，恢復的工作階段為 `"resume"`，`/clear` 後為 `"clear"`，或壓縮後為 `"compact"` |

981| `model` | 活動模型識別碼。它可以被省略，例如在 `/clear` 後或當工作階段通過對話恢復被恢復時，因此在讀取它之前檢查欄位 |

982| `agent_type` | 代理名稱，當您使用 `claude --agent <name>` 啟動 Claude Code 時出現 |

983| `session_title` | 目前工作階段標題（如果已設定），例如通過 `--name` 或 `/rename`。發出 `sessionTitle` 的 hook 可以先檢查 `session_title` 以避免覆寫使用者明確設定的標題 |

967 984

968```json theme={null}985```json theme={null}

969{986{

1095 Setup 決定控制1112 Setup 決定控制

1096</h4>1113</h4>

1097 1114

1098Setup hooks 無法阻止。在退出代碼 2 時，stderr 向使用者顯示；在任何其他非零退出代碼時，stderr 僅在您使用 `--verbose` 啟動時出現。在兩種情況下，執行都會繼續。要將資訊傳遞到 Claude 的上下文中，請在 JSON 輸出中返回 `additionalContext`；純 stdout 僅寫入偵錯日誌。除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，您還可以返回這些事件特定欄位：1115Setup hooks 無法阻止。任何非零退出代碼（包括 2）都會向使用者顯示 stderr 作為 `<hook name> hook error` 通知，執行繼續。在 [非互動模式](/zh-TW/headless) 中，hook 輸出僅在您使用 `--verbose` 啟動時出現。

1116

1117要將資訊傳遞到 Claude 的上下文中，請在 JSON 輸出中返回 `additionalContext`；純 stdout 僅寫入偵錯日誌。除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，您還可以返回這些事件特定欄位：

1099 1118

1100| 欄位 | 描述 |1119| 欄位 | 描述 |

1101| :------------------ | :------------------------------- |1120| :------------------ | :------------------------------- |

1191* **純文字 stdout**：寫入 stdout 的任何非 JSON 文字都被新增為上下文1210* **純文字 stdout**：寫入 stdout 的任何非 JSON 文字都被新增為上下文

1192* **帶有 `additionalContext` 的 JSON**：使用下面的 JSON 格式以獲得更多控制。`additionalContext` 欄位被新增為上下文1211* **帶有 `additionalContext` 的 JSON**：使用下面的 JSON 格式以獲得更多控制。`additionalContext` 欄位被新增為上下文

1193 1212

1194純 stdout 在成績單中顯示為 hook 輸出。`additionalContext` 欄位被更謹慎地新增。1213純 stdout 在成績單中顯示為 hook 輸出。`additionalContext` 值被注入為系統提醒，Claude 讀取時不會有可見的成績單項目。

1195 1214

1196要阻止提示，請返回一個 JSON 物件，其中 `decision` 設定為 `"block"`：1215要阻止提示，請返回一個 JSON 物件，其中 `decision` 設定為 `"block"`：

1197 1216

1215}1234}

1216```1235```

1217 1236

1218<Note>

1219 JSON 格式對於簡單用例不是必需的。要新增上下文，您可以使用退出代碼 0 將純文字列印到 stdout。當您需要阻止提示或想要更結構化的控制時，請使用 JSON。

1220</Note>

~~1221~~

1222<h3 id="userpromptexpansion">1237<h3 id="userpromptexpansion">

1223 UserPromptExpansion1238 UserPromptExpansion

1224</h3>1239</h3>

1545在 `PostToolUse` 中，已完成的 Agent 呼叫的 `tool_response` 攜帶 subagent 的最終文字以及使用量遙測。讀取這些欄位以從 hook 記錄每個 subagent 的成本：1560在 `PostToolUse` 中，已完成的 Agent 呼叫的 `tool_response` 攜帶 subagent 的最終文字以及使用量遙測。讀取這些欄位以從 hook 記錄每個 subagent 的成本：

1546 1561

1547| 欄位 | 類型 | 範例 | 描述 |1562| 欄位 | 類型 | 範例 | 描述 |

1548| :------------------ | :- | :---------------------------------------------------- | :---------------------------------------------------------------------------------------------- |1563| :------------------ | :- | :---------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1549| `status` | 字串 | `"completed"` | 同步呼叫為 `"completed"`，`run_in_background: true` 為 `"async_launched"` |1564| `status` | 字串 | `"completed"` | 前景 subagents 為 `"completed"`，背景 subagents 為 `"async_launched"`。{/* min-version: 2.1.198 */}從 v2.1.198 開始，subagents 預設在背景執行，因此省略的 `run_in_background` 也會產生 `"async_launched"` |

1551| `content` | 陣列 | `[{"type": "text", "text": "Found 12 endpoints..."}]` | subagent 的最終文字塊 |1566| `content` | 陣列 | `[{"type": "text", "text": "Found 12 endpoints..."}]` | subagent 的最終文字塊 |

1552| `resolvedModel` | 字串 | `"claude-sonnet-4-5"` | subagent 執行的模型，可能與請求的模型不同。{/* min-version: 2.1.174 */}需要 Claude Code v2.1.174 或更高版本 |1567| `resolvedModel` | 字串 | `"claude-sonnet-4-5"` | subagent 執行的模型，可能與請求的模型不同。{/* min-version: 2.1.174 */}需要 Claude Code v2.1.174 或更高版本 |

1555| `totalToolUseCount` | 數字 | `7` | subagent 進行的工具呼叫計數 |1570| `totalToolUseCount` | 數字 | `7` | subagent 進行的工具呼叫計數 |

1556| `usage` | 物件 | `{"input_tokens": 8320, ...}` | 按類型的令牌細分：`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens` |1571| `usage` | 物件 | `{"input_tokens": 8320, ...}` | 按類型的令牌細分：`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens` |

1557 1572

1558對於 `run_in_background: true` 呼叫，工具在啟動 subagent 後立即返回，因此 `tool_response` 不攜帶使用量欄位。它具有 `status: "async_launched"`、`agentId`、`description`、`prompt`、`outputFile` 和 `resolvedModel`。1573對於背景 subagents，工具在啟動 subagent 後立即返回，因此 `tool_response` 不攜帶使用量欄位。它具有 `status: "async_launched"`、`agentId`、`description`、`prompt`、`outputFile` 和 `resolvedModel`。

1559 1574

1560`resolvedModel` 欄位命名 subagent 實際執行的模型，可能與 `tool_input` 中的 `model` 值不同。它需要 Claude Code v2.1.174 或更高版本。1575`resolvedModel` 欄位命名 subagent 實際執行的模型，可能與 `tool_input` 中的 `model` 值不同，例如當 `availableModels` 或其他覆蓋適用時。它需要 Claude Code v2.1.174 或更高版本。

1561 1576

1562<a id="askuserquestion" />1577<a id="askuserquestion" />

1563 1578

1593`PreToolUse` hooks 可以控制工具呼叫是否進行。與使用頂層 `decision` 欄位的其他 hooks 不同，PreToolUse 在 `hookSpecificOutput` 物件內返回其決定。這提供了更豐富的控制：四個結果（允許、拒絕、詢問或延遲）加上在執行前修改工具輸入的能力。1608`PreToolUse` hooks 可以控制工具呼叫是否進行。與使用頂層 `decision` 欄位的其他 hooks 不同，PreToolUse 在 `hookSpecificOutput` 物件內返回其決定。這提供了更豐富的控制：四個結果（允許、拒絕、詢問或延遲）加上在執行前修改工具輸入的能力。

1594 1609

1595| 欄位 | 描述 |1610| 欄位 | 描述 |

1596| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |1611| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1597| `permissionDecision` | `"allow"` 跳過權限提示。`"deny"` 防止工具呼叫。`"ask"` 提示使用者確認。`"defer"` 優雅地退出，以便稍後可以恢復工具。[拒絕和詢問規則](/zh-TW/permissions#manage-permissions) 在 hook 返回 `"allow"` 時仍然適用 |1612| `permissionDecision` | `"allow"` 跳過權限提示，除了 [需要使用者互動的工具](#pretooluse-decision-control)。`"deny"` 防止工具呼叫。`"ask"` 提示使用者確認。`"defer"` 優雅地退出，以便稍後可以恢復工具。[拒絕和詢問規則](/zh-TW/permissions#manage-permissions) 仍然適用，無論 hook 返回什麼 |

1599| `updatedInput` | 在執行前修改工具的輸入參數。替換整個輸入物件，因此包括未修改的欄位以及修改後的欄位。與 `"allow"` 結合以自動批准，或與 `"ask"` 結合以向使用者顯示修改後的輸入。對於 `"defer"`，被忽略 |1614| `updatedInput` | 在執行前修改工具的輸入參數。替換整個輸入物件，因此包括未修改的欄位以及修改後的欄位。與 `"allow"` 結合以自動批准，或與 `"ask"` 結合以向使用者顯示修改後的輸入。對於 `"defer"`，被忽略 |

1619 1634

1620`AskUserQuestion` 和 `ExitPlanMode` 需要使用者互動，通常在 [非互動模式](/zh-TW/headless) 中使用 `-p` 標誌時阻止。返回 `permissionDecision: "allow"` 以及 `updatedInput` 滿足該要求：hook 從 stdin 讀取工具的輸入，通過您自己的 UI 收集答案，並在 `updatedInput` 中返回它，以便工具執行而不提示。僅返回 `"allow"` 對這些工具不夠。對於 `AskUserQuestion`，回顯原始 `questions` 陣列並新增一個 [`answers`](#askuserquestion) 物件，將每個問題的文字對應到選定的答案。1635`AskUserQuestion` 和 `ExitPlanMode` 需要使用者互動，通常在 [非互動模式](/zh-TW/headless) 中使用 `-p` 標誌時阻止。返回 `permissionDecision: "allow"` 以及 `updatedInput` 滿足該要求：hook 從 stdin 讀取工具的輸入，通過您自己的 UI 收集答案，並在 `updatedInput` 中返回它，以便工具執行而不提示。僅返回 `"allow"` 對這些工具不夠。對於 `AskUserQuestion`，回顯原始 `questions` 陣列並新增一個 [`answers`](#askuserquestion) 物件，將每個問題的文字對應到選定的答案。

1621 1636

1637從 v2.1.199 開始，一個 MCP 工具，其伺服器使用 [`_meta["anthropic/requiresUserInteraction"]`](/zh-TW/mcp#require-approval-for-a-specific-tool) 標記它，更嚴格：hook 無法使用 `"allow"` 跳過其批准提示，無論是否有 `updatedInput`，因為 Claude Code 無法確認 hook 收集了工具需要的互動。

1638

1622<Note>1639<Note>

1623 PreToolUse 之前使用頂層 `decision` 和 `reason` 欄位，但這些對此事件已棄用。改用 `hookSpecificOutput.permissionDecision` 和 `hookSpecificOutput.permissionDecisionReason`。棄用的值 `"approve"` 和 `"block"` 對應於 `"allow"` 和 `"deny"`。PostToolUse 和 Stop 等其他事件繼續使用頂層 `decision` 和 `reason` 作為其目前格式。1640 PreToolUse 之前使用頂層 `decision` 和 `reason` 欄位，但這些對此事件已棄用。改用 `hookSpecificOutput.permissionDecision` 和 `hookSpecificOutput.permissionDecisionReason`。棄用的值 `"approve"` 和 `"block"` 對應於 `"allow"` 和 `"deny"`。PostToolUse 和 Stop 等其他事件繼續使用頂層 `decision` 和 `reason` 作為其目前格式。

1624</Note>1641</Note>

2015 Notification2032 Notification

2016</h3>2033</h3>

2017 2034

2018當 Claude Code 發送通知時執行。匹配通知類型：`permission_prompt`、`idle_prompt`、`auth_success`、`elicitation_dialog`、`elicitation_complete`、`elicitation_response`。省略匹配器以針對所有通知類型執行 hooks。2035當 Claude Code 發送通知時執行。匹配通知類型。省略匹配器以針對所有通知類型執行 hooks。

2036

2037| 匹配器 | 何時觸發 |

2038| :--------------------- | :---------------------------------------------------------- |

2039| `permission_prompt` | Claude 需要您批准工具使用 |

2040| `idle_prompt` | Claude 完成並等待您的下一個提示 |

2041| `auth_success` | 驗證完成 |

2042| `elicitation_dialog` | MCP 伺服器開啟徵詢表單 |

2043| `elicitation_complete` | MCP 徵詢表單被提交或關閉 |

2044| `elicitation_response` | MCP 徵詢回應被發送回伺服器 |

2045| `agent_needs_input` | 背景工作階段開始等待您的輸入。僅在 [agent view](/zh-TW/agent-view) 在終端中開啟時觸發 |

2046| `agent_completed` | 背景工作階段完成或失敗。僅在 [agent view](/zh-TW/agent-view) 在終端中開啟時觸發 |

2047

2048`agent_needs_input` 和 `agent_completed` 類型需要 Claude Code v2.1.198 或更高版本。

2019 2049

2020使用單獨的匹配器根據通知類型執行不同的處理程式。此配置在 Claude 需要權限批准時觸發權限特定的警報指令碼，在 Claude 閒置時觸發不同的通知：2050使用單獨的匹配器根據通知類型執行不同的處理程式。此配置在 Claude 需要權限批准時觸發權限特定的警報指令碼，在 Claude 閒置時觸發不同的通知：

2021 2051

2078 SubagentStart 輸入2108 SubagentStart 輸入

2079</h4>2109</h4>

2080 2110

2081除了 [通用輸入欄位](#common-input-fields) 外，SubagentStart hooks 還接收 `agent_id`（subagent 的唯一識別碼）和 `agent_type`（代理名稱，內建代理，如 `"general-purpose"`、`"Explore"`、`"Plan"` 或自訂代理名稱）。2111除了 [通用輸入欄位](#common-input-fields) 外，SubagentStart hooks 還接收 `agent_id`（subagent 的唯一識別碼）和 `agent_type`（代理名稱，匹配器篩選的值）。

2082 2112

2083```json theme={null}2113```json theme={null}

2084{2114{

2276 Stop 輸入2306 Stop 輸入

2277</h4>2307</h4>

2278 2308

2279除了 [通用輸入欄位](#common-input-fields) 外，Stop hooks 還接收 `stop_hook_active`、`last_assistant_message`、`background_tasks` 和 `session_crons`。`stop_hook_active` 欄位在 Claude Code 已經作為 stop hook 的結果繼續時為 `true`。檢查此值或處理成績單以防止 Claude Code 無限執行。`last_assistant_message` 欄位包含 Claude 最終回應的文字內容，因此 hooks 可以存取它而無需解析成績單檔案。2309除了 [通用輸入欄位](#common-input-fields) 外，Stop hooks 還接收 `stop_hook_active`、`last_assistant_message`、`background_tasks` 和 `session_crons`。`stop_hook_active` 欄位在 Claude Code 已經作為 stop hook 的結果繼續時為 `true`。檢查此值或處理成績單以防止 Claude Code 無限執行。Claude Code 在 8 次連續阻止後覆蓋 hook 並結束轉向。`last_assistant_message` 欄位包含 Claude 最終回應的文字內容，因此 hooks 可以存取它而無需解析成績單檔案。

2280 2310

2281`background_tasks` 和 `session_crons` 陣列在 Claude Code v2.1.145 或更高版本中可用，讓 hooks 區分「工作階段完成」和「工作階段暫停等待背景工作喚醒它」。當任務登錄表可達時，兩個陣列都存在，當沒有任何內容在進行中或計劃時為空。2311`background_tasks` 和 `session_crons` 陣列在 Claude Code v2.1.145 或更高版本中可用，讓 hooks 區分「工作階段完成」和「工作階段暫停等待背景工作喚醒它」。當任務登錄表可達時，兩個陣列都存在，當沒有任何內容在進行中或計劃時為空。

2282 2312

2558除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，CwdChanged hooks 還可以返回 `watchPaths` 來動態設定 [FileChanged](#filechanged) 監視的檔案路徑：2588除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，CwdChanged hooks 還可以返回 `watchPaths` 來動態設定 [FileChanged](#filechanged) 監視的檔案路徑：

2559 2589

2560| 欄位 | 描述 |2590| 欄位 | 描述 |

2561| :----------- | :--------------------------------------------------------------------- |2591| :----------- | :-------------------------------------------------------------------- |

2563 2593

2564CwdChanged hooks 沒有決定控制。它們無法阻止目錄變更。2594CwdChanged hooks 沒有決定控制。它們無法阻止目錄變更。

2565 2595

2605除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，FileChanged hooks 還可以返回 `watchPaths` 來動態更新監視的檔案路徑：2635除了所有 hooks 可用的 [JSON 輸出欄位](#json-output) 外，FileChanged hooks 還可以返回 `watchPaths` 來動態更新監視的檔案路徑：

2606 2636

2607| 欄位 | 描述 |2637| 欄位 | 描述 |

2608| :----------- | :-------------------------------------------------------------------------------- |2638| :----------- | :------------------------------------------------------------------------------- |

2610 2640

2611FileChanged hooks 沒有決定控制。它們無法阻止檔案變更的發生。2641FileChanged hooks 沒有決定控制。它們無法阻止檔案變更的發生。

2612 2642

2645 WorktreeCreate 輸入2675 WorktreeCreate 輸入

2646</h4>2676</h4>

2647 2677

2648除了 [通用輸入欄位](#common-input-fields) 外，WorktreeCreate hooks 還接收 `name` 欄位。這是新 worktree 的 slug 識別碼，由使用者指定或自動生成（例如 `bold-oak-a3f2`）。2678除了 [通用輸入欄位](#common-input-fields) 外，WorktreeCreate hooks 還接收 `name` 欄位。這是新 worktree 的 slug 識別碼，由使用者指定或自動生成，例如 `bold-oak-a3f2`。

2649 2679

2650```json theme={null}2680```json theme={null}

2651{2681{

2672 WorktreeRemove2702 WorktreeRemove

2673</h3>2703</h3>

2674 2704

2675[WorktreeCreate](#worktreecreate) 的清理對應項。此 hook 在 worktree 被移除時觸發，要麼當您退出 `--worktree` 工作階段並選擇移除它時，要麼當具有 `isolation: "worktree"` 的 subagent 完成時。對於基於 git 的 worktrees，Claude 使用 `git worktree remove` 自動處理清理。如果您為非 git 版本控制系統配置了 WorktreeCreate hook，請將其與 WorktreeRemove hook 配對以處理清理。沒有它，worktree 目錄會留在磁碟上。2705當 worktree 被移除時執行，要麼當您退出 `--worktree` 工作階段並選擇移除它時，要麼當具有 `isolation: "worktree"` 的 subagent 完成時。這是 [WorktreeCreate](#worktreecreate) 的清理對應項。對於基於 git 的 worktrees，Claude Code 使用 `git worktree remove` 自動處理清理。如果您為非 git 版本控制系統配置了 WorktreeCreate hook，請將其與 WorktreeRemove hook 配對以處理清理。沒有它，worktree 目錄會留在磁碟上。

2676 2706

2677Claude Code 將 WorktreeCreate 返回的路徑作為 `worktree_path` 在 hook 輸入中傳遞。此範例讀取該路徑並移除目錄：2707Claude Code 將 WorktreeCreate 返回的路徑作為 `worktree_path` 在 hook 輸入中傳遞。此範例讀取該路徑並移除目錄：

2678 2708

3057* `PostToolUseFailure`、`TaskCreated` 和 `TaskCompleted`：原因作為工具錯誤返回給 Claude，類似於 `PreToolUse`3087* `PostToolUseFailure`、`TaskCreated` 和 `TaskCompleted`：原因作為工具錯誤返回給 Claude，類似於 `PreToolUse`

3058* `TeammateIdle`：預設情況下隊友停止，原因顯示為警告行。設定 `continueOnBlock: true` 以將原因反饋給隊友並保持其工作狀態3088* `TeammateIdle`：預設情況下隊友停止，原因顯示為警告行。設定 `continueOnBlock: true` 以將原因反饋給隊友並保持其工作狀態

3059* `PermissionRequest`：`ok: false` 沒有效果。要從 hook 拒絕批准，請使用[命令 hook](#command-hook-fields)返回 `hookSpecificOutput.decision.behavior: "deny"`3089* `PermissionRequest`：`ok: false` 沒有效果。要從 hook 拒絕批准，請使用[命令 hook](#command-hook-fields)返回 `hookSpecificOutput.decision.behavior: "deny"`

3060* `PermissionDenied`：`ok: false` 沒有效果，因為拒絕已經發生。此事件讀取的唯一輸出是 `hookSpecificOutput.retry`，提示和代理 hooks 無法設定 — 它們在此事件上執行，但其輸出被丟棄。使用[命令 hook](#command-hook-fields)返回 `retry`3090* `PermissionDenied`：`ok: false` 沒有效果，因為拒絕已經發生。此事件讀取的唯一輸出是 `hookSpecificOutput.retry`，提示和代理 hooks 無法設定。它們在此事件上執行，但其輸出被丟棄。使用[命令 hook](#command-hook-fields)返回 `retry`

3061 3091

3062如果您需要對任何事件進行更精細的控制，請使用[命令 hook](#command-hook-fields)，其中包含[決定控制](#decision-control)中描述的每個事件欄位。3092如果您需要對任何事件進行更精細的控制，請使用[命令 hook](#command-hook-fields)，其中包含[決定控制](#decision-control)中描述的每個事件欄位。

3063 3093

3064<h3 id="example-multi-criteria-stop-hook">3094<h3 id="check-multiple-conditions-before-stopping">

3065 範例：多條件 Stop hook3095 在停止前檢查多個條件

3066</h3>3096</h3>

3067 3097

3068此 `Stop` hook 使用詳細提示在允許 Claude 停止之前檢查三個條件。如果 `"ok"` 為 `false`，Claude 繼續工作，提供的原因作為其下一個指令。`SubagentStop` hooks 使用相同的格式來評估 [subagent](/zh-TW/sub-agents) 是否應該停止：3098此 `Stop` hook 使用詳細提示在允許 Claude 停止之前檢查三個條件。`SubagentStop` hooks 使用相同的格式來評估 [subagent](/zh-TW/sub-agents) 是否應該停止。如果 `"ok"` 為 `false`，Claude 繼續工作，提供的原因作為其下一個指令：

3069 3099

3070```json theme={null}3100```json theme={null}

3071{3101{

3189 3219

3190非同步 hook 完成通知預設被抑制。要查看它們，請使用 `Ctrl+O` 啟用詳細模式或使用 `--verbose` 啟動 Claude Code。3220非同步 hook 完成通知預設被抑制。要查看它們，請使用 `Ctrl+O` 啟用詳細模式或使用 `--verbose` 啟動 Claude Code。

3191 3221

3192<h3 id="example-run-tests-after-file-changes">3222<h3 id="run-tests-after-file-changes">

3193 範例：檔案變更後執行測試3223 檔案變更後執行測試

3194</h3>3224</h3>

3195 3225

3196此 hook 在 Claude 寫入檔案時在背景啟動測試套件，然後在測試完成時將結果報告回 Claude。將此指令碼儲存到專案中的 `.claude/hooks/run-tests-async.sh` 並使用 `chmod +x` 使其可執行：3226此 hook 在 Claude 寫入檔案時在背景啟動測試套件，然後在測試完成時將結果報告回 Claude。將此指令碼儲存到專案中的 `.claude/hooks/run-tests-async.sh` 並使用 `chmod +x` 使其可執行：

3284 Windows PowerShell 工具3314 Windows PowerShell 工具

3285</h2>3315</h2>

3286 3316

3287在 Windows 上，您可以通過在命令 hook 上設定 `"shell": "powershell"` 在 PowerShell 中執行個別 hooks。Hooks 直接生成 PowerShell，因此無論是否設定 `CLAUDE_CODE_USE_POWERSHELL_TOOL` 都有效。Claude Code 自動偵測 `pwsh.exe`（PowerShell 7+），回退到 `powershell.exe`（5.1）。3317在 Windows 上，您可以通過在命令 hook 上設定 `"shell": "powershell"` 在 PowerShell 中執行個別 hooks。Hooks 直接生成 PowerShell，因此無論是否設定 `CLAUDE_CODE_USE_POWERSHELL_TOOL` 都有效。Claude Code 自動偵測 `pwsh.exe`（PowerShell 7 及更新版本的可執行檔），並回退到 `powershell.exe`（Windows PowerShell 5.1）。

3288 3318

3289```json theme={null}3319```json theme={null}

3290{3320{

3305}3335}

3306```3336```

3307 3337

3308若要從 PowerShell shell 形式命令參考專案根目錄，請使用 `$env:CLAUDE_PROJECT_DIR` 將其讀取為環境變數。PowerShell 將裸露的 `${CLAUDE_PROJECT_DIR}` 形式視為本機變數，而非環境查詢，Claude Code 僅在 [plugin hooks](#reference-scripts-by-path) 的 shell 形式中替換該佔位符。對於在 `settings.json` 中定義的 hook，請使用 `$env:` 形式或切換到 [exec 形式](#exec-form-and-shell-form)，其中 `${CLAUDE_PROJECT_DIR}` 會在每個 `args` 元素中被替換，無論 hook 在何處定義。3338若要從 PowerShell shell 形式命令參考專案根目錄，請寫入 `${CLAUDE_PROJECT_DIR}` 或 `$env:CLAUDE_PROJECT_DIR`。自 v2.1.198 起，Claude Code 會在 PowerShell shell 形式命令中將 `${CLAUDE_PROJECT_DIR}`、`${CLAUDE_PLUGIN_ROOT}` 和 `${CLAUDE_PLUGIN_DATA}` 佔位符重寫為 PowerShell 的 `${env:NAME}` 形式，無論 hook 是在 `settings.json`、plugin 或 skill 中定義。PowerShell 會在解析後從匯出的環境中解析該值，因此佔位符在雙引號字串內有效，但在單引號字串內無效，因為 PowerShell 永遠不會在單引號字串中展開變數。

3339

3340在 v2.1.198 之前，此重寫僅適用於 plugin hooks。在較早的版本上，`settings.json` hook 需要 `$env:` 形式或 [exec 形式](#exec-form-and-shell-form)，其中 `${CLAUDE_PROJECT_DIR}` 會在每個 `args` 元素中被替換，無論 hook 在何處定義。

3341

3342不要在 PowerShell hook 中寫入裸露的 `$CLAUDE_PROJECT_DIR` 拼寫。PowerShell 會將其解析為未定義的本機變數，並將其解析為 `$null`，這會導致指令碼路徑沒有其專案根目錄前綴。Claude Code 不會重寫該形式；它會在 [debug log](#debug-hooks) 中記錄警告。

3309 3343

3310下面的範例顯示了一個 `settings.json` hook，它使用 `$env:` 形式執行專案指令碼：3344下面的範例顯示了一個 `settings.json` hook，它使用 `$env:` 形式執行專案指令碼，該形式在每個版本上都有效：

3311 3345

3312```json theme={null}3346```json theme={null}

3313{3347{

hooks-guide.md +27 −25

Details

87 87

88Hooks 讓您在 Claude Code 生命週期的關鍵點執行程式碼：編輯後格式化檔案、在執行前阻止命令、當 Claude 需要輸入時發送通知、在工作階段開始時注入上下文等。有關 hook 事件的完整列表，請參閱 [Hooks 參考](/zh-TW/hooks#hook-lifecycle)。88Hooks 讓您在 Claude Code 生命週期的關鍵點執行程式碼：編輯後格式化檔案、在執行前阻止命令、當 Claude 需要輸入時發送通知、在工作階段開始時注入上下文等。有關 hook 事件的完整列表，請參閱 [Hooks 參考](/zh-TW/hooks#hook-lifecycle)。

89 89

~~90每個範例都包含一個現成可用的配置區塊，您可以將其新增到[設定檔](#configure-hook-location)。最常見的模式：~~90每個範例都包含一個現成可用的配置區塊，您可以將其新增到[設定檔](#configure-hook-location)。

~~92* [當 Claude 需要輸入時收到通知](#get-notified-when-claude-needs-input)~~

~~93* [編輯後自動格式化程式碼](#auto-format-code-after-edits)~~

~~94* [阻止編輯受保護的檔案](#block-edits-to-protected-files)~~

~~95* [壓縮後重新注入上下文](#re-inject-context-after-compaction)~~

~~96* [審計配置變更](#audit-configuration-changes)~~

~~97* [當目錄或檔案變更時重新載入環境](#reload-environment-when-directory-or-files-change)~~

~~98* [自動批准特定權限提示](#auto-approve-specific-permission-prompts)~~

99 91

100有關 hooks 執行單獨模型審查並將發現結果反饋到工作階段中的生產範例，請參閱 [`security-guidance` plugin 如何與 Claude Code 整合](/zh-TW/security-guidance#how-the-plugin-integrates-with-claude-code)。92有關 hooks 執行單獨模型審查並將發現結果反饋到工作階段中的生產範例，請參閱 [`security-guidance` plugin 如何與 Claude Code 整合](/zh-TW/security-guidance#how-the-plugin-integrates-with-claude-code)。

101 93

182空的 `matcher` 會在所有通知類型上觸發。若要僅在特定事件上觸發，請將其設定為以下其中一個值：174空的 `matcher` 會在所有通知類型上觸發。若要僅在特定事件上觸發，請將其設定為以下其中一個值：

183 175

184| Matcher | 觸發時機 |176| Matcher | 觸發時機 |

185| :--------------------- | :------------------ |177| :--------------------- | :------------------------------------------------------ |

184| `agent_needs_input` | 背景工作階段開始等待您的輸入。僅在 [agent view](/zh-TW/agent-view) 開啟時觸發 |

185| `agent_completed` | 背景工作階段完成或失敗。僅在 [agent view](/zh-TW/agent-view) 開啟時觸發 |

186

187`agent_needs_input` 和 `agent_completed` 匹配器需要 Claude Code v2.1.198 或更新版本。

192 188

193輸入 `/hooks` 並選擇 `Notification` 以確認 hook 已註冊。有關完整的事件架構，請參閱 [Notification 參考](/zh-TW/hooks#notification)。189輸入 `/hooks` 並選擇 `Notification` 以確認 hook 已註冊。有關完整的事件架構，請參閱 [Notification 參考](/zh-TW/hooks#notification)。

194 190

198 194

199在 Claude 編輯的每個檔案上自動執行 [Prettier](https://prettier.io/)，以便格式保持一致而無需手動干預。195在 Claude 編輯的每個檔案上自動執行 [Prettier](https://prettier.io/)，以便格式保持一致而無需手動干預。

200 196

201此 hook 使用 `PostToolUse` 事件搭配 `Edit|Write` 匹配器，因此它只在檔案編輯工具之後執行。{/* min-version: 2.1.191 */}在 Claude Code v2.1.191 或更新版本上，您也可以將匹配器寫成 `Edit,Write`，因為在這些版本上 `|` 和 `,` 是工具名稱匹配器的可互換清單分隔符。該命令使用 [`jq`](https://jqlang.github.io/jq/) 提取編輯的檔案路徑並將其傳遞給 Prettier。將此新增到您的專案根目錄中的 `.claude/settings.json`：197此 hook 使用 `PostToolUse` 事件搭配 `Edit|Write` 匹配器，因此它只在檔案編輯工具之後執行。該命令使用 [`jq`](https://jqlang.github.io/jq/) 提取編輯的檔案路徑並將其傳遞給 Prettier。將此新增到您的專案根目錄中的 `.claude/settings.json`：

202 198

203```json theme={null}199```json theme={null}

204{200{

218}214}

219```215```

220 216

217在 Claude Code v2.1.191 或更新版本上，您也可以將匹配器寫成 `Edit,Write`，因為在這些版本上 `|` 和 `,` 是工具名稱匹配器的可互換清單分隔符。

218

221<Note>219<Note>

222 本頁上的 Bash 範例使用 `jq` 進行 JSON 解析。使用 `brew install jq`（macOS）、`apt-get install jq`（Debian/Ubuntu）安裝它，或參閱 [`jq` 下載](https://jqlang.github.io/jq/download/)。220 本頁上的 Bash 範例使用 `jq` 進行 JSON 解析。使用 `brew install jq`（macOS）、`apt-get install jq`（Debian 和 Ubuntu）安裝它，或參閱 [`jq` 下載](https://jqlang.github.io/jq/download/)。

223</Note>221</Note>

224 222

225<h3 id="block-edits-to-protected-files">223<h3 id="block-edits-to-protected-files">

254 ```252 ```

255 </Step>253 </Step>

256 254

257 <Step title="使指令可執行（macOS/Linux）">255 <Step title="在 macOS 和 Linux 上使指令可執行">

258 Hook 指令必須可執行，Claude Code 才能執行它們：256 Hook 指令必須可執行，Claude Code 才能執行它們：

259 257

260 ```bash theme={null}258 ```bash theme={null}

378 376

379在每個具有 `.envrc` 的目錄中執行一次 `direnv allow`，以便允許 direnv 載入它。如果您使用 devbox 或 nix 而不是 direnv，相同的模式適用於 `devbox shellenv` 或 `devbox global shellenv` 代替 `direnv export bash`。377在每個具有 `.envrc` 的目錄中執行一次 `direnv allow`，以便允許 direnv 載入它。如果您使用 devbox 或 nix 而不是 direnv，相同的模式適用於 `devbox shellenv` 或 `devbox global shellenv` 代替 `direnv export bash`。

380 378

381若要對特定檔案而不是每次目錄變更做出反應，請使用 `FileChanged` 搭配 `matcher` 列出要監視的檔案名稱（以 `|` 分隔）。若要建立監視清單，此值會分割為字面檔案名稱，而不是作為正規表達式進行評估。有關輸入架構、`watchPaths` 輸出和 `CLAUDE_ENV_FILE` 詳細資訊，請參閱 [FileChanged](/zh-TW/hooks#filechanged)。此範例監視工作目錄中 `.envrc` 和 `.env` 的變更：379若要對特定檔案而不是每次目錄變更做出反應，請使用 `FileChanged` 搭配 `matcher` 列出要監視的檔案名稱（以 `|` 分隔）。建立監視清單時，Claude Code 會將此值分割為字面檔案名稱，而不是作為正規表達式進行評估。有關輸入架構、`watchPaths` 輸出和 `CLAUDE_ENV_FILE` 詳細資訊，請參閱 [FileChanged](/zh-TW/hooks#filechanged)。此範例監視工作目錄中 `.envrc` 和 `.env` 的變更：

382 380

383```json theme={null}381```json theme={null}

384{382{

564 Hook 輸出562 Hook 輸出

565</h4>563</h4>

566 564

567您的指令透過寫入 stdout 或 stderr 並以特定代碼退出來告訴 Claude Code 接下來要做什麼。例如，想要阻止命令的 `PreToolUse` hook：565您的指令透過寫入 stdout 或 stderr 並以特定代碼退出來告訴 Claude Code 接下來要做什麼。以下 `PreToolUse` hook 阻止命令：

568 566

569```bash theme={null}567```bash theme={null}

570#!/bin/bash568#!/bin/bash

619 617

620其他事件使用不同的決策模式。例如，`PostToolUse` 和 `Stop` hooks 使用頂級 `decision: "block"` 欄位，而 `PermissionRequest` 使用 `hookSpecificOutput.decision.behavior`。有關按事件的完整分解，請參閱參考中的[摘要表](/zh-TW/hooks#decision-control)。618其他事件使用不同的決策模式。例如，`PostToolUse` 和 `Stop` hooks 使用頂級 `decision: "block"` 欄位，而 `PermissionRequest` 使用 `hookSpecificOutput.decision.behavior`。有關按事件的完整分解，請參閱參考中的[摘要表](/zh-TW/hooks#decision-control)。

621 619

622對於 `UserPromptSubmit` hooks，改用 `additionalContext` 將文字注入到 Claude 的上下文中。基於提示的 hooks（`type: "prompt"`）以不同方式處理輸出：請參閱[基於提示的 hooks](#prompt-based-hooks)。620對於 `UserPromptSubmit` hooks，改用 `additionalContext` 將文字注入到 Claude 的上下文中。

621

622基於提示的 hooks（`type: "prompt"`）以不同方式處理輸出：請參閱[基於提示的 hooks](#prompt-based-hooks)。

623 623

624<h3 id="filter-hooks-with-matchers">624<h3 id="filter-hooks-with-matchers">

625 使用匹配器篩選 hooks625 使用匹配器篩選 hooks

670| `UserPromptSubmit`、`PostToolBatch`、`Stop`、`TeammateIdle`、`TaskCreated`、`TaskCompleted`、`WorktreeCreate`、`WorktreeRemove`、`CwdChanged`、`MessageDisplay` | 不支援匹配器 | 始終在每次出現時觸發 |670| `UserPromptSubmit`、`PostToolBatch`、`Stop`、`TeammateIdle`、`TaskCreated`、`TaskCompleted`、`WorktreeCreate`、`WorktreeRemove`、`CwdChanged`、`MessageDisplay` | 不支援匹配器 | 始終在每次出現時觸發 |

671 671

672顯示不同事件類型上匹配器的更多範例：672下面的標籤頁顯示不同事件類型上匹配器的更多範例。

673 673

674<Tabs>674<Tabs>

675 <Tab title="記錄每個 Bash 命令">675 <Tab title="記錄每個 Bash 命令">

925 限制925 限制

926</h3>926</h3>

927 927

928設計 hooks 時請記住這些限制：

929

928* 命令 hooks 只透過 stdout、stderr 和退出代碼通訊。它們無法觸發 `/` 命令或工具呼叫。透過 `additionalContext` 傳回的文字會作為系統提醒注入，Claude 將其讀取為純文字。HTTP hooks 改為透過回應主體通訊。930* 命令 hooks 只透過 stdout、stderr 和退出代碼通訊。它們無法觸發 `/` 命令或工具呼叫。透過 `additionalContext` 傳回的文字會作為系統提醒注入，Claude 將其讀取為純文字。HTTP hooks 改為透過回應主體通訊。

929* Hook 超時因類型而異。透過 `timeout` 欄位（以秒為單位）按 hook 覆寫。931* Hook 超時因類型而異。透過 `timeout` 欄位（以秒為單位）按 hook 覆寫。

930 * `command`、`http`、`mcp_tool`：10 分鐘。`UserPromptSubmit` 將這些降低至 30 秒，`MessageDisplay` 將這些降低至 10 秒。932 * `command`、`http`、`mcp_tool`：10 分鐘。`UserPromptSubmit` 將這些降低至 30 秒，`MessageDisplay` 將這些降低至 10 秒。

931 * `prompt`：30 秒。933 * `prompt`：30 秒。

932 * `agent`：60 秒。934 * `agent`：60 秒。

933* `PostToolUse` hooks 無法撤銷操作，因為工具已經執行。935* `PostToolUse` hooks 無法撤銷操作，因為工具已經執行。

934* `PermissionRequest` hooks 在[非互動模式](/zh-TW/headless)（`-p`）中不觸發。對於自動化權限決策，使用 `PreToolUse` hooks。936* `PermissionRequest` hooks 在[非互動模式](/zh-TW/headless)（`-p` 旗標）中不觸發。對於自動化權限決策，使用 `PreToolUse` hooks。

935* `Stop` hooks 在 Claude 完成回應時觸發，而不僅在任務完成時。它們在使用者中斷時不觸發。API 錯誤觸發 [StopFailure](/zh-TW/hooks#stopfailure) 代替。937* `Stop` hooks 在 Claude 完成回應時觸發，而不僅在任務完成時。它們在使用者中斷時不觸發。API 錯誤觸發 [StopFailure](/zh-TW/hooks#stopfailure) 代替。

936* 當多個 PreToolUse hooks 傳回 [`updatedInput`](/zh-TW/hooks#pretooluse) 以重寫工具的引數時，最後完成的會獲勝。由於 hooks 並行執行，順序是非確定性的。避免有多個 hook 修改同一工具的輸入。938* 當多個 `PreToolUse` hooks 傳回 [`updatedInput`](/zh-TW/hooks#pretooluse) 以重寫工具的引數時，最後完成的會獲勝。由於 hooks 並行執行，順序是非確定性的。避免有多個 hook 修改同一工具的輸入。

937 939

938<h3 id="hooks-and-permission-modes">940<h3 id="hooks-and-permission-modes">

939 Hooks 和權限模式941 Hooks 和權限模式

940</h3>942</h3>

941 943

942PreToolUse hooks 在任何權限模式檢查之前觸發。傳回 `permissionDecision: "deny"` 的 hook 會阻止工具，即使在 `bypassPermissions` 模式或使用 `--dangerously-skip-permissions`。這讓您強制執行使用者無法透過變更其權限模式來繞過的原則。944`PreToolUse` hooks 在任何權限模式檢查之前觸發。傳回 `permissionDecision: "deny"` 的 hook 會阻止工具，即使在 `bypassPermissions` 模式或使用 `--dangerously-skip-permissions`。這讓您強制執行使用者無法透過變更其權限模式來繞過的原則。

943 945

944反面不成立：傳回 `"allow"` 的 hook 不會繞過來自設定的拒絕規則。Hooks 可以加強限制，但不能放寬超過權限規則允許的限制。946反面不成立：傳回 `"allow"` 的 hook 不會繞過來自設定的拒絕規則。Hooks 可以加強限制，但不能放寬超過權限規則允許的限制。

945 947

950Hook 已配置但從不執行。952Hook 已配置但從不執行。

951 953

952* 執行 `/hooks` 並確認 hook 出現在正確的事件下954* 執行 `/hooks` 並確認 hook 出現在正確的事件下

953* 檢查匹配器模式是否與工具名稱完全相符（匹配器區分大小寫）955* 檢查匹配器模式是否與工具名稱完全相符。匹配器區分大小寫

954* 驗證您觸發的是正確的事件類型（例如，`PreToolUse` 在工具執行前觸發，`PostToolUse` 在之後觸發）956* 驗證您觸發的是正確的事件類型：`PreToolUse` 在工具執行前觸發，`PostToolUse` 在之後觸發

955* 如果在非互動模式（`-p`）中使用 `PermissionRequest` hooks，改用 `PreToolUse`957* 如果在非互動模式（`-p` 旗標）中使用 `PermissionRequest` hooks，改用 `PreToolUse`

956 958

957<h3 id="hook-error-in-output">959<h3 id="hook-error-in-output">

958 Hook 輸出中的錯誤960 Hook 輸出中的錯誤

976您編輯了設定檔但 hooks 未出現在選單中。978您編輯了設定檔但 hooks 未出現在選單中。

977 979

978* 檔案編輯通常會自動選取。如果在幾秒鐘後仍未出現，檔案監視程式可能已錯過變更：重新啟動您的工作階段以強制重新載入。980* 檔案編輯通常會自動選取。如果在幾秒鐘後仍未出現，檔案監視程式可能已錯過變更：重新啟動您的工作階段以強制重新載入。

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

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

981 983

982<h3 id="stop-hook-hits-the-block-cap">984<h3 id="stop-hook-hits-the-block-cap">

how-claude-code-works.md +0 −1

Details

210內建命令也會引導您完成設定：210內建命令也會引導您完成設定：

211 211

212* `/init` 引導您為您的專案建立 CLAUDE.md212* `/init` 引導您為您的專案建立 CLAUDE.md

213* `/agents` 幫助您設定自訂 subagents

214* `/doctor` 診斷您的安裝的常見問題213* `/doctor` 診斷您的安裝的常見問題

215 214

216<h3 id="it’s-a-conversation">215<h3 id="it’s-a-conversation">

llm-gateway-protocol.md +9 −1

Details

106 系統提示歸屬區塊106 系統提示歸屬區塊

107</h2>107</h2>

108 108

109Claude Code 在系統提示前面加上一個簡短的歸屬區塊，其中包含用戶端版本和從對話衍生的指紋。`api.anthropic.com` 端點在處理前移除該區塊，因此它不會影響第一方提示快取；任何其他上游都會將其作為提示的一部分接收。Anthropic 和雲提供者的 Claude 端點讀取它以進行歸屬，因此要省略它，請設定 [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/zh-TW/env-vars) 而不是在 gateway 中移除它。109Claude Code 在系統提示前面加上一個簡短的歸屬區塊，其中包含用戶端版本和從對話衍生的指紋。`api.anthropic.com` 端點在處理前移除該區塊，因此它不會影響第一方提示快取；任何其他上游都會將其作為提示的一部分接收。

110

111該移除是位置性的，因此只有在 gateway 轉發 `system` 陣列保持不變時才有效。若要在不遺失其他系統內容的情況下將區塊排除在提示之外：

112

113* 完全按照接收的方式轉發 `system` 陣列，將區塊保持在最前面：在前面加上另一個系統區塊、重新排序陣列或將其轉換為單一字串會破壞移除，區塊隨後會到達模型和提示快取鍵。

114* 將區塊保持在自己的陣列項目中：端點將以歸屬標頭開頭的合併區塊視為完整的歸屬並刪除合併到其中的所有內容，包括系統提示的其餘部分。

115* 如果您的 gateway 必須重新塑造系統內容，請設定 [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/zh-TW/env-vars) 以便 Claude Code 省略該區塊。Anthropic 和雲提供者的 Claude 端點讀取該區塊以進行歸屬，因此要省略它，請在用戶端而不是在 gateway 中移除或移動它。

116

117未經修改到達端點的請求不受影響。

110 118

111{/* min-version: 2.1.181 */}從 Claude Code v2.1.181 開始，當請求通過自訂基礎 URL 路由時，該區塊在對話的生命週期內是穩定的，因此以完整請求體為鍵的 gateway 端提示快取可以在不禁用它的情況下工作。在 v2.1.181 之前，該區塊包含每個請求的令牌；在這些版本上，如果您的 gateway 實現了這樣的快取，請設定 `CLAUDE_CODE_ATTRIBUTION_HEADER=0`。119{/* min-version: 2.1.181 */}從 Claude Code v2.1.181 開始，當請求通過自訂基礎 URL 路由時，該區塊在對話的生命週期內是穩定的，因此以完整請求體為鍵的 gateway 端提示快取可以在不禁用它的情況下工作。在 v2.1.181 之前，該區塊包含每個請求的令牌；在這些版本上，如果您的 gateway 實現了這樣的快取，請設定 `CLAUDE_CODE_ATTRIBUTION_HEADER=0`。

112 120

mcp.md +44 −1

Details

16 使用 MCP 可以做什麼16 使用 MCP 可以做什麼

17</h2>17</h2>

18 18

~~19連接 MCP servers 後，您可以要求 Claude Code：~~19使用連接的 MCP servers，您可以要求 Claude Code：

20 20

21* **從問題追蹤器實現功能**："新增 JIRA 問題 ENG-4521 中描述的功能，並在 GitHub 上建立 PR。"21* **從問題追蹤器實現功能**："新增 JIRA 問題 ENG-4521 中描述的功能，並在 GitHub 上建立 PR。"

22* **分析監控資料**："檢查 Sentry 和 Statsig，以檢查 ENG-4521 中描述的功能使用情況。"22* **分析監控資料**："檢查 Sentry 和 Statsig，以檢查 ENG-4521 中描述的功能使用情況。"

1037 如果您經常遇到特定 MCP servers 的輸出警告，請考慮增加 `MAX_MCP_OUTPUT_TOKENS` 限制。您也可以要求 server 作者新增 `anthropic/maxResultSizeChars` 註解或分頁其回應。註解對傳回影像內容的工具沒有影響；對於這些，提高 `MAX_MCP_OUTPUT_TOKENS` 是唯一的選項。1037 如果您經常遇到特定 MCP servers 的輸出警告，請考慮增加 `MAX_MCP_OUTPUT_TOKENS` 限制。您也可以要求 server 作者新增 `anthropic/maxResultSizeChars` 註解或分頁其回應。註解對傳回影像內容的工具沒有影響；對於這些，提高 `MAX_MCP_OUTPUT_TOKENS` 是唯一的選項。

1038</Warning>1038</Warning>

1039 1039

1040<h2 id="tool-input-schemas-with-a-root-level-combinator">

1041 具有根層級組合器的工具輸入架構

1042</h2>

1043

1044某些 MCP servers 將工具的輸入架構宣告為 JSON Schema 聯合，在架構的頂層具有 `anyOf`、`oneOf` 或 `allOf`。Claude API 不接受這些關鍵字在架構根目錄。它接受在 `properties` 內嵌套的組合器，Claude Code 會原封不動地傳送。

1045

1046從 Claude Code v2.1.195 開始，具有根層級組合器的工具保持可用。在將工具傳送到 API 之前，Claude Code 會將架構平坦化為單個物件，並在工具的描述前面加上一句話，告訴 Claude 哪些參數組屬於一起：

1047

1048* `allOf`：來自每個分支的屬性被合併，每個分支的 `required` 列表仍然適用

1049* `anyOf` 和 `oneOf`：來自每個分支的屬性被合併，每個分支的 `required` 列表在工具描述中描述，而不是由架構強制執行

1050

1051您的 server 會接收 Claude 選擇的任何引數，因此請繼續在伺服器端驗證組合。

1052

1053當 Claude Code 無法產生 API 接受的架構，或在不接收啟用重寫的遠端配置的部署上時（例如離線機器），它會跳過該工具，在 server 的日誌中記錄原因，並保持 server 的其他工具可用。早於 v2.1.195 的版本會跳過輸入架構具有根層級 `anyOf`、`oneOf` 或 `allOf` 的每個工具。

1054

1055<h2 id="require-approval-for-a-specific-tool">

1056 要求特定工具的批准

1057</h2>

1058

1059如果您正在建立 MCP server，您可以透過在工具的 `tools/list` 回應項目中將 `_meta["anthropic/requiresUserInteraction"]` 設定為 `true` 來標記工具為在每次呼叫時需要明確批准。該值必須是 JSON 布林值 `true`；任何其他值都會被忽略。

1060

1061Claude Code 在每次呼叫時顯示該工具的權限提示，即使在 `acceptEdits`、`auto` 和 `bypassPermissions` [permission modes](/zh-TW/permissions#permission-modes) 中，並且不提供「不再詢問」選項。[Allow rules](/zh-TW/permissions#permission-rule-syntax) 符合該工具的也不會跳過提示。在 `dontAsk` 模式中（從不提示），Claude Code 會改為拒絕呼叫。

1062

1063提示必須到達一個人。在非互動模式下使用 [`--permission-prompt-tool`](/zh-TW/cli-reference#cli-flags)，來自提示工具的 `allow` 結果對於標記的工具會轉換為拒絕，訊息為 `MCP tool requires user interaction; not supported via --permission-prompt-tool`。Agent SDK 的 [`canUseTool` 回呼](/zh-TW/agent-sdk/permissions) 確實會接收這些呼叫並可以批准它們，因為 SDK 主機應該向使用者顯示它們。

1064

1065將此用於其權限提示本身就是重點的工具，例如同意或存取授予步驟，其中自動批准意味著沒有人類曾經同意。來自同一 server 的其他工具保持其正常權限行為。

1066

1067以下 `tools/list` 項目將一個工具標記為始終需要批准。

1068

1069```json theme={null}

1070{

1071 "name": "grant_access",

1072 "description": "Requests access to a protected resource",

1073 "_meta": {

1074 "anthropic/requiresUserInteraction": true

1075 }

1076}

1077```

1078

1079`anthropic/requiresUserInteraction` 註解需要 Claude Code v2.1.199 或更新版本。較早的版本會忽略它並應用標準權限流程。

1080

1081當 session 連接到 [Remote Control](/zh-TW/remote-control) 或 SDK 主機時，Claude Code 會將權限請求標記為需要使用者互動，因此用戶端會向您顯示工具的權限提示，而不是單點擊批准操作。

1082

1040<h2 id="respond-to-mcp-elicitation-requests">1083<h2 id="respond-to-mcp-elicitation-requests">

1041 回應 MCP 引發請求1084 回應 MCP 引發請求

1042</h2>1085</h2>

memory.md +1 −1

Details

235- 包括 OpenAPI 文件註解235- 包括 OpenAPI 文件註解

236```236```

237 237

238沒有 `paths` 欄位的規則無條件載入並適用於所有檔案。路徑範圍規則在 Claude 讀取與模式匹配的檔案時觸發，而不是在每次工具使用時觸發。238沒有 `paths` 欄位的規則無條件載入並適用於所有檔案。路徑範圍規則在 Claude 讀取與模式匹配的檔案時觸發，而不是在每次工具使用時觸發。{/* min-version: 2.1.198 */}截至 v2.1.198，匹配也適用於 Claude 透過專案目錄的符號連結路徑到達檔案時，例如在符號連結簽出中。

239 239

240在 `paths` 欄位中使用 glob 模式，按副檔名、目錄或任何組合匹配檔案：240在 `paths` 欄位中使用 glob 模式，按副檔名、目錄或任何組合匹配檔案：

241 241

model-config.md +64 −11

Details

31 31

32| 模型別名 | 行為 |32| 模型別名 | 行為 |

33| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |33| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

84* `Enter`：切換模型並儲存為您的預設值84* `Enter`：切換模型並儲存為您的預設值

85* `s`：僅針對此會話切換模型85* `s`：僅針對此會話切換模型

86 86

~~87直接輸入 `/model <name>` 的行為類似於 `Enter`。專案和受管設定仍然優先，並在下次啟動時重新應用。~~87直接輸入 `/model <name>` 的行為類似於 `Enter`。專案和受管設定仍然優先，並在下次啟動時重新應用。{/* min-version: 2.1.196 */}您的管理員配置的[組織預設模型](#organization-default-model)也會在下次啟動時重新應用。

88 88

89在 v2.1.144 至 v2.1.152 中，`/model` 僅適用於目前會話，選擇器中的 `d` 儲存預設值。89在 v2.1.144 至 v2.1.152 中，`/model` 僅適用於目前會話，選擇器中的 `d` 儲存預設值。

90 90

128* **主要會話模型**：`/model`、`--model` 旗標、`ANTHROPIC_MODEL` 環境變數、`model` 設定，以及[恢復會話](#setting-your-model)時還原的模型128* **主要會話模型**：`/model`、`--model` 旗標、`ANTHROPIC_MODEL` 環境變數、`model` 設定，以及[恢復會話](#setting-your-model)時還原的模型

129* **別名解析**：{/* min-version: 2.1.176 */}`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` 和 `ANTHROPIC_DEFAULT_FABLE_MODEL` 環境變數無法將允許的別名重新導向到清單外的模型129* **別名解析**：{/* min-version: 2.1.176 */}`ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` 和 `ANTHROPIC_DEFAULT_FABLE_MODEL` 環境變數無法將允許的別名重新導向到清單外的模型

130* **快速模式**：{/* min-version: 2.1.176 */}`/fast` 在隱含切換到清單外的 Opus 模型時拒絕切換，並顯示訊息「不在您組織的允許模型中」130* **快速模式**：{/* min-version: 2.1.176 */}`/fast` 在隱含切換到清單外的 Opus 模型時拒絕切換，並顯示訊息「不在您組織的允許模型中」

131* **子代理模型**：[子代理](/zh-TW/sub-agents#choose-a-model) frontmatter 中的 `model` 欄位、Agent 工具的 `model` 參數、`/agents` 中的模型選擇器，以及 `CLAUDE_CODE_SUBAGENT_MODEL`131* **子代理模型**：[子代理](/zh-TW/sub-agents#choose-a-model) frontmatter 中的 `model` 欄位、Agent 工具的 `model` 參數、`CLAUDE_CODE_SUBAGENT_MODEL`，以及在 v2.1.197 及更早版本上，`/agents` 精靈中的模型選擇器{/* max-version: 2.1.197 */}

132* **技能和命令模型**：[技能和命令](/zh-TW/skills)中的 `model` frontmatter132* **技能和命令模型**：[技能和命令](/zh-TW/skills)中的 `model` frontmatter

133* **顧問模型**：已設定的 [`advisorModel`](/zh-TW/advisor) 設定和 `--advisor` 旗標133* **顧問模型**：已設定的 [`advisorModel`](/zh-TW/advisor) 設定和 `--advisor` 旗標

134* **背景代理模型**：在[分派選擇器](/zh-TW/agent-view)中選擇的模型134* **背景代理模型**：在[分派選擇器](/zh-TW/agent-view)中選擇的模型

135 135

136使用 `/model` 切換到被阻止的模型會被拒絕並出現錯誤，而被阻止的 `--model` 旗標、`ANTHROPIC_MODEL` 或 `model` 設定值在啟動時會被替換為警告，命名所要求和替代的模型，會話會在預設模型上啟動。被阻止的子代理、技能或命令覆蓋會回退到繼承或預設模型，而不是使請求失敗；被阻止的 `advisorModel` 設定會停用該會話的顧問，而被阻止的 `--advisor` 旗標值會在啟動時以錯誤退出。排除的模型會從 `/model` 選擇器中隱藏。136使用 `/model` 切換到被阻止的模型會被拒絕並出現錯誤，而被阻止的 `--model` 旗標、`ANTHROPIC_MODEL` 或 `model` 設定值在啟動時會被替換為警告，命名所要求和替代的模型，會話會在預設模型上啟動。被阻止的子代理、技能或命令覆蓋會回退到繼承或預設模型，而不是使請求失敗；被阻止的 `advisorModel` 設定會停用該會話的顧問，而被阻止的 `--advisor` 旗標值會在啟動時以錯誤退出。排除的模型會從 `/model` 選擇器中隱藏。{/* min-version: 2.1.199 */}自 v2.1.199 起，清單中沒有內建選擇器列的完整模型 ID（例如清單固定的較舊版本）會在 `/model` 選擇器中顯示為其自己的標記列。在較早版本上，此類 ID 只能透過輸入 `/model <id>` 選擇。

137 137

138自動模型變更的檢查方式相同：[後備模型鏈](#fallback-model-chains)中清單外的元素會被捨棄，計畫模式升級（例如 [`opusplan`](#opusplan-model-setting)）到排除的模型會被跳過，以便計畫在會話的模型上繼續進行，而[自動模型後備](#automatic-model-fallback)的目標被排除時不會執行，因此標記的請求會以拒絕結束。當會話之後執行的模型在允許清單外時，啟用[快速模式](/zh-TW/fast-mode)會被拒絕。138自動模型變更的檢查方式相同：[後備模型鏈](#fallback-model-chains)中清單外的元素會被捨棄，計畫模式升級（例如 [`opusplan`](#opusplan-model-setting)）到排除的模型會被跳過，以便計畫在會話的模型上繼續進行，而[自動模型後備](#automatic-model-fallback)的目標被排除時不會執行，因此標記的請求會以拒絕結束。當會話之後執行的模型在允許清單外時，啟用[快速模式](/zh-TW/fast-mode)會被拒絕。

139 139

182}182}

183```183```

184 184

185當使用者帳戶類型的預設模型不在允許清單中時，「預設」選項會改為解析為第一個 `availableModels` 項目，該項目命名允許的、可用的模型，而 `/model` 選擇器的「預設」列會顯示該模型。這適用於到達預設值的每個位置：會話啟動、在 `/model` 中選擇「預設」、[後備模型鏈](#fallback-model-chains)中的 `"default"` 關鍵字，以及排除選擇被捨棄時使用的後備。185「預設」選項解析為帳戶類型預設值，或當管理員設定了[組織預設模型](#organization-default-model)時解析為該模型。當該模型不在允許清單中時，「預設」選項會改為解析為第一個 `availableModels` 項目，該項目命名允許的、可用的模型，而 `/model` 選擇器的「預設」列會顯示該模型。這適用於到達預設值的每個位置：會話啟動、在 `/model` 中選擇「預設」、[後備模型鏈](#fallback-model-chains)中的 `"default"` 關鍵字，以及排除選擇被捨棄時使用的後備。

186 186

187當 `availableModels` 未設定或為空時，`enforceAvailableModels` 無效：使用 `availableModels: []` 時，帳戶類型的「預設」模型保持可用，因此該設定無法將使用者鎖定在每個模型之外。當 `availableModels` 非空但沒有項目解析為允許的、可用的模型時，強制執行會降級，「預設」會回退到帳戶類型預設值，警告僅在 `--debug` 下可見。在清單中保留至少一個保證可用的項目以避免這種情況。187當 `availableModels` 未設定或為空時，`enforceAvailableModels` 無效：使用 `availableModels: []` 時，帳戶類型的「預設」模型保持可用，因此該設定無法將使用者鎖定在每個模型之外。當 `availableModels` 非空但沒有項目解析為允許的、可用的模型時，強制執行會降級，「預設」會回退到帳戶類型預設值，警告僅在 `--debug` 下可見。在清單中保留至少一個保證可用的項目以避免這種情況。

188 188

242 242

243受限制的模型會從 `/model` 選擇器中隱藏。使用 `--model`、`ANTHROPIC_MODEL` 環境變數或 `model` 設定按名稱選擇它會顯示通知 `Model "<name>" is restricted by your organization's settings. Using <model> instead.`，會話會在允許的模型上啟動。為受限制的模型輸入 `/model <name>` 會被拒絕，並顯示 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`，會話會保持其目前模型。243受限制的模型會從 `/model` 選擇器中隱藏。使用 `--model`、`ANTHROPIC_MODEL` 環境變數或 `model` 設定按名稱選擇它會顯示通知 `Model "<name>" is restricted by your organization's settings. Using <model> instead.`，會話會在允許的模型上啟動。為受限制的模型輸入 `/model <name>` 會被拒絕，並顯示 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`，會話會保持其目前模型。

244 244

245限制適用於組織範圍或按角色：

246

247* 在組織層級停用模型會將其移除給每個成員。

248* 角色級別存取為不同的自訂角色授予不同的模型，持有多個角色的成員可以使用其任何角色授予的模型。

249* Haiku 模型始終可用，無法停用，因此每個成員至少保留一個可用模型。

250* 存取變更在約一分鐘內對新請求生效；`/model` 選擇器在下次會話啟動時反映它。

251

245這兩個限制組合：只有當模型被 `availableModels` 允許且未被組織限制時，它才可選擇。組織限制會傳遞到 Anthropic API 和 [LLM 閘道](/zh-TW/llm-gateway)部署上的會話。Bedrock、Vertex AI、Foundry 和 AWS 上的 Claude Platform 上的會話不接收它們，因此請改為在這些提供者上使用 `availableModels`。252這兩個限制組合：只有當模型被 `availableModels` 允許且未被組織限制時，它才可選擇。組織限制會傳遞到 Anthropic API 和 [LLM 閘道](/zh-TW/llm-gateway)部署上的會話。Bedrock、Vertex AI、Foundry 和 AWS 上的 Claude Platform 上的會話不接收它們，因此請改為在這些提供者上使用 `availableModels`。

246 253

254<h2 id="organization-default-model">

255 組織預設模型

256</h2>

257

258{/* plan-availability: feature=org-default-model plans=enterprise */}

259

260Claude Enterprise 計畫上的組織管理員可以從 claude.ai 管理員主控台為 Claude Code 成員設定預設模型，適用於整個組織或按自訂角色。設定後，「預設」選項會解析為該模型，而不是[帳戶類型預設](#default-model-setting)。需要 Claude Code v2.1.196 或更新版本。

261

262`/model` 選擇器中的「預設」列會顯示組織預設值的名稱，標籤為「Org default」。無論管理員是為整個組織還是為您的角色設定預設值，標籤都會讀取「Org default」。角色預設值涵蓋該自訂角色的成員，並優先於組織範圍的預設值；當您的多個角色設定不同的預設值時，最強大的模型適用。

263

264組織預設值是起點，而非限制，任何其他模型選擇都優先於它：

265

266* `--model` 旗標和 `ANTHROPIC_MODEL` 環境變數

267* [受管理設定](/zh-TW/settings#settings-files)中的 `model` 值或透過 `--settings` 提供

268* 您的使用者、專案或本機設定中的 `model` 值，包括您使用 `/model` 儲存的模型

269

270管理員也可以配置組織預設值以覆蓋使用者選擇。啟用覆蓋後，它優先於使用者、專案和本機設定中的 `model` 值，因此您使用 `/model` 儲存的模型適用於目前會話，組織預設值在下次啟動時返回。當您的選擇不同時，`/model` 會顯示 `Your organization's default (<model>) applies on restart`。`--model` 旗標、`ANTHROPIC_MODEL`、受管理設定和 `--settings` 即使啟用覆蓋也仍然優先。覆蓋可用於有限的組織集合；詢問您的 Anthropic 帳戶團隊有關可用性。

271

272若要限制成員可以選擇的模型，請改用[組織模型限制](#organization-model-restrictions)或 [`availableModels`](#restrict-model-selection)。

273

274Claude Code 在啟動時讀取組織預設值一次，因此管理員在會話中途變更的預設值在下次啟動時生效。

275

276當組織預設值不覆蓋使用者選擇時，管理員變更後的第一次互動式啟動會從您的使用者設定中清除 `model` 鍵一次，以便新預設值適用。它不改變檔案中的任何其他內容，您在該啟動後使用 `/model` 儲存的模型會被保留。

277

278組織預設值在被採用前會通過與任何其他「預設」模型相同的限制檢查：

279

280* [`availableModels`](#restrict-model-selection) 本身永遠不會限制「預設」選項，因此允許清單外的組織預設值仍然適用。當也設定了 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 時，允許清單外的組織預設值會重新對應到第一個允許清單項目，就像任何其他「預設」一樣

281* [組織模型限制](#organization-model-restrictions)拒絕的組織預設值會被替換為其系列中最新的允許模型，或當該系列的每個版本都被限制時被替換為較低成本的系列

282* 對您的帳戶完全不可用的組織預設值，例如[零資料保留](/zh-TW/zero-data-retention)下的 Fable 5，會被跳過，「預設」選項會解析為帳戶類型預設值

283

284自 v2.1.199 起，當組織預設值是與您帳戶類型的常用預設值不同的模型系列時，`/model` 選擇器會為該常用系列保留一個單獨的列，因此您仍然可以為會話切換到它。在 v2.1.196 至 v2.1.198 中，該列在選擇器中缺失。

285

286組織預設值會傳遞到使用 Anthropic API 進行驗證的會話。[LLM 閘道](/zh-TW/llm-gateway)部署、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 上的會話不接收它。若要在這些部署上設定預設值，請改用[受管理設定](/zh-TW/settings#settings-files)中的 `model` 鍵。

287

288<h2 id="organization-effort-limits">

289 組織努力限制

290</h2>

291

292{/* plan-availability: feature=org-effort-limits plans=enterprise */}

293

294Claude Enterprise 計畫上的組織管理員可以為每個自訂角色設定每個模型的最大[努力等級](#adjust-effort-level)，以及角色級別[組織模型限制](#organization-model-restrictions)。超過上限的等級不會在 `/effort` 選擇器中提供，使用 `--effort` 或 `/effort` 命名更高等級會改為在上限處執行。在互動式會話和純文字 `--print` 執行中，警告會命名所要求和應用的等級；使用 `json` 或 `stream-json` 輸出或在背景代理中，限制會無聲地應用。上限是按模型的，因此切換模型可以改變哪些等級可用。當您的多個角色授予相同的模型時，最寬鬆的上限適用。需要 Claude Code v2.1.195 或更新版本。

295

296努力限制與[組織模型限制](#organization-model-restrictions)一起傳遞，並遵循相同的提供者可用性：Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [AWS 上的 Claude Platform](/zh-TW/claude-platform-on-aws) 上的會話不接收它們。

297

247<h2 id="special-model-behavior">298<h2 id="special-model-behavior">

248 特殊模型行為299 特殊模型行為

249</h2>300</h2>

261 312

262Enterprise 隨用隨付是指按使用量計費而非按訂閱席位計費的 Enterprise 組織。313Enterprise 隨用隨付是指按使用量計費而非按訂閱席位計費的 Enterprise 組織。

263 314

264當受管設定[強制執行 Default 模型的允許清單](#enforce-the-allowlist-for-the-default-model)且帳戶類型預設不在 `availableModels` 中時，`default` 會解析為強制執行的 Default，而不是上述帳戶類型預設。315當管理員設定了[組織預設模型](#organization-default-model)時，`default` 會解析為該模型，而不是上述帳戶類型預設值。需要 Claude Code v2.1.196 或更新版本。

316

317當受管設定[強制執行 Default 模型的允許清單](#enforce-the-allowlist-for-the-default-model)且帳戶類型預設不在 `availableModels` 中時，`default` 會解析為強制執行的 Default，而不是上述帳戶類型預設。當兩者都適用時，組織預設值首先取代帳戶類型預設值，然後強制執行適用於它：允許清單上的組織預設值會被保留，而清單外的會解析為強制執行的 Default。

265 318

266Fable 5 不是任何帳戶類型的預設模型。會話僅在您選擇 Fable 5 後才使用它，使用 `/model fable`、`model` 設定或 `best` 別名（其中 Fable 5 可用）。使用 `/model` 選擇它會將其儲存為您使用者設定中的選定模型，因此後續會話會在 Fable 5 上啟動，直到您變更模型。319Fable 5 不是任何帳戶類型的預設模型。會話僅在您選擇 Fable 5 後才使用它，使用 `/model fable`、`model` 設定或 `best` 別名（其中 Fable 5 可用）。使用 `/model` 選擇它會將其儲存為您使用者設定中的選定模型，因此後續會話會在 Fable 5 上啟動，直到您變更模型。

267 320

278 331

279Plan Mode Opus 階段使用與 `opus` 模型設定相同的 context window。在訂閱層級上，Opus 會[自動升級到 1M context](#extended-context)，`opusplan` 在 Plan Mode 中也會獲得升級。若要在您不在自動升級層級上時強制兩個階段都使用 1M context，請將模型設定為 `opusplan[1m]`。332Plan Mode Opus 階段使用與 `opus` 模型設定相同的 context window。在訂閱層級上，Opus 會[自動升級到 1M context](#extended-context)，`opusplan` 在 Plan Mode 中也會獲得升級。若要在您不在自動升級層級上時強制兩個階段都使用 1M context，請將模型設定為 `opusplan[1m]`。

280 333

281當 [`availableModels`](#restrict-model-selection) 排除 Opus 時，`opusplan` 在 Plan Mode 中保持在 Sonnet 上，而不是切換。當 Sonnet 被排除時，隱含的 Haiku 到 Sonnet Plan Mode 升級也適用相同情況。334當 [`availableModels`](#restrict-model-selection) 排除 Opus 時，`opusplan` 在 Plan Mode 中保持在 Sonnet 上，而不是切換。同樣地，隱含的 Haiku 到 Sonnet Plan Mode 升級在 Sonnet 被排除時也適用相同情況。

282 335

283如需混合方法，其中 Claude 在任務中途決定何時諮詢第二個模型，而不是在計畫邊界處切換，請參閱 [advisor tool](/zh-TW/advisor)。336如需混合方法，其中 Claude 在任務中途決定何時諮詢第二個模型，而不是在計畫邊界處切換，請參閱 [advisor tool](/zh-TW/advisor)。

284 337

379 432

380如果您設定活動模型不支援的等級，Claude Code 會回退到您設定的等級處或以下的最高支援等級。例如，`xhigh` 在 Opus 4.6 上執行為 `high`。433如果您設定活動模型不支援的等級，Claude Code 會回退到您設定的等級處或以下的最高支援等級。例如，`xhigh` 在 Opus 4.6 上執行為 `high`。您的組織也可以限制模型可用的等級；請參閱[組織努力限制](#organization-effort-limits)。

381 434

382Fable 5、Sonnet 5、Opus 4.8、Opus 4.6 和 Sonnet 4.6 上的預設努力為 `high`，Opus 4.7 上的預設努力為 `xhigh`。435Fable 5、Sonnet 5、Opus 4.8、Opus 4.6 和 Sonnet 4.6 上的預設努力為 `high`，Opus 4.7 上的預設努力為 `xhigh`。

383 436

471 524

4721M context window 使用標準模型定價，超過 200K 的 token 無需額外費用。對於訂閱中包含擴展 context 的計畫，使用量仍由您的訂閱涵蓋。對於透過使用額度存取擴展 context 的計畫，token 會計入使用額度。5251M context window 使用標準模型定價，超過 200K 的 token 無需額外費用。對於訂閱中包含擴展 context 的計畫，使用量仍由您的訂閱涵蓋。對於透過使用額度存取擴展 context 的計畫，token 會計入使用額度。

473 526

474如果您的帳戶支援 1M context，該選項會出現在最新版本 Claude Code 的模型選擇器（`/model`）中。如果您看不到它，請嘗試重新啟動您的會話。527如果您的帳戶支援 1M context，該選項會出現在最新版本 Claude Code 的 `/model` 選擇器中。如果您看不到它，請嘗試重新啟動您的會話。

475 528

476您也可以將 `[1m]` 後綴與模型別名或完整模型名稱一起使用：529您也可以將 `[1m]` 後綴與模型別名或完整模型名稱一起使用：

477 530

508 新增自訂模型選項561 新增自訂模型選項

509</h2>562</h2>

510 563

511使用 `ANTHROPIC_CUSTOM_MODEL_OPTION` 將單一自訂項目新增到 `/model` 選擇器，而無需取代內建別名。這對於測試 Claude Code 預設不列出的模型 ID 很有用。對於 LLM 閘道部署，當設定 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` 時，Claude Code 可以從閘道的 `/v1/models` 端點填入選擇器，因此只有在探索被停用或未傳回您想要的模型時，才需要此變數。請參閱 [閘道模型探索](/zh-TW/llm-gateway-protocol#model-discovery)。564使用 `ANTHROPIC_CUSTOM_MODEL_OPTION` 將單一自訂項目新增到 `/model` 選擇器，而無需取代內建別名。這對於測試 Claude Code 預設不列出的模型 ID 很有用。對於 LLM 閘道部署，當設定 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1` 時，Claude Code 可以從閘道的 `/v1/models` 端點填入選擇器，因此只有在探索被停用或未傳回您想要的模型時，才需要此變數。請參閱 [gateway model discovery](/zh-TW/llm-gateway-protocol#model-discovery)。

512 565

513此範例設定所有三個變數以使閘道路由的 Opus 部署可選擇：566此範例設定所有三個變數以使閘道路由的 Opus 部署可選擇：

514 567

520 573

521自訂項目出現在 `/model` 選擇器的底部。`ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` 和 `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` 是可選的。如果省略，模型 ID 會用作名稱，描述預設為 `Custom model (<model-id>)`。574自訂項目出現在 `/model` 選擇器的底部。`ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` 和 `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` 是可選的。如果省略，模型 ID 會用作名稱，描述預設為 `Custom model (<model-id>)`。

522 575

523Claude Code 會跳過在 `ANTHROPIC_CUSTOM_MODEL_OPTION` 中設定的模型 ID 的驗證，因此您可以使用您的 API 端點接受的任何字串。當設定 [`availableModels`](#restrict-model-selection) 時，也要在允許清單中包含自訂模型 ID：自訂項目會從選擇器中篩選出來，對其進行 `--model` 選擇會被拒絕，就像任何其他被排除的模型一樣。嵌入家族名稱的自訂 ID（例如 `my-gateway/claude-opus-4-8`）會計為該家族的特定項目，並停用其萬用字元，因此也要列出您打算保持可選擇的版本。請參閱 [合併行為](#merge-behavior)。576Claude Code 會跳過在 `ANTHROPIC_CUSTOM_MODEL_OPTION` 中設定的模型 ID 的驗證，因此您可以使用您的 API 端點接受的任何字串。當設定 [`availableModels`](#restrict-model-selection) 時，也要在允許清單中包含自訂模型 ID：自訂項目會從選擇器中篩選出來，對其進行 `--model` 選擇會被拒絕，就像任何其他被排除的模型一樣。嵌入家族名稱的自訂 ID（例如 `my-gateway/claude-opus-4-8`）會計為該家族的特定項目，並停用其萬用字元，因此也要列出您打算保持可選擇的版本。請參閱 [Merge behavior](#merge-behavior)。

524 577

525<h2 id="environment-variables">578<h2 id="environment-variables">

526 環境變數579 環境變數

monitoring-usage.md +1 −1

Details

1184 1184

1185Claude Code 在內部重試失敗的 API 請求，並僅在放棄後才發出單個 `claude_code.api_error` 事件，因此事件本身是該請求的終端訊號。中間重試嘗試不會作為單獨的事件記錄。1185Claude Code 在內部重試失敗的 API 請求，並僅在放棄後才發出單個 `claude_code.api_error` 事件，因此事件本身是該請求的終端訊號。中間重試嘗試不會作為單獨的事件記錄。

1186 1186

1187事件上的 `attempt` 屬性記錄進行的嘗試總次數。`CLAUDE_CODE_MAX_RETRIES` 預設為 10，上限為 15。當請求在暫時性錯誤上耗盡所有重試時，`attempt` 等於該有效限制加一：預設為 11，永遠不超過 16。較低的值表示不可重試的錯誤，例如 `400` 回應。1187事件上的 `attempt` 屬性記錄進行的嘗試總次數。`CLAUDE_CODE_MAX_RETRIES` 預設為 10，上限為 15；從 v2.1.199 開始，`CLAUDE_CODE_RETRY_WATCHDOG` 提高了預設值並移除了上限。當請求在暫時性錯誤上耗盡所有重試時，`attempt` 等於該有效限制加一：預設為 11，除非設定了看門狗，否則永遠不超過 16。較低的值表示不可重試的錯誤，例如 `400` 回應。

1188 1188

1189若要區分從一個恢復的工作階段與停滯的工作階段，請按 `session.id` 分組事件，並檢查錯誤後是否存在更晚的 `api_request` 事件。1189若要區分從一個恢復的工作階段與停滯的工作階段，請按 `session.id` 分組事件，並檢查錯誤後是否存在更晚的 `api_request` 事件。

1190 1190

permission-modes.md +22 −7

Details

237* 強制推送或直接推送到 `main`237* 強制推送或直接推送到 `main`

238* {/* min-version: 2.1.182 */}`git reset --hard`、`git checkout -- .`、`git restore .`、`git clean -fd`、`git stash drop` 或 `git stash clear`，分類器推測這些會捨棄未提交的變更238* {/* min-version: 2.1.182 */}`git reset --hard`、`git checkout -- .`、`git restore .`、`git clean -fd`、`git stash drop` 或 `git stash clear`，分類器推測這些會捨棄未提交的變更

239* `git commit --amend`，當 HEAD 的提交不是在此會話中建立的239* `git commit --amend`，當 HEAD 的提交不是在此會話中建立的

240* {/* min-version: 2.1.198 */}}從 v2.1.198 開始，`git commit --amend` 當 HEAD 的提交已經被推送時。僅訊息重新措辭不被阻止：`--amend -m` 沒有新暫存的內容，在 Claude 在此會話中建立的提交上

240* `terraform destroy`、`pulumi destroy`、`cdk destroy` 或 `terragrunt destroy`，以及應用會銷毀資源的計劃241* `terraform destroy`、`pulumi destroy`、`cdk destroy` 或 `terragrunt destroy`，以及應用會銷毀資源的計劃

241 242

242Claude Code v2.1.195 及更新版本預設阻止更多類別。有些取決於[環境](/zh-TW/auto-mode-config#define-trusted-infrastructure)項目，例如敏感遠端目標和受保護的 IaC 範圍，您可以將其縮小到具體名稱。243Claude Code v2.1.195 及更新版本預設阻止更多類別。有些取決於[環境](/zh-TW/auto-mode-config#define-trusted-infrastructure)項目，例如敏感遠端目標和受保護的 IaC 範圍，您可以將其縮小到具體名稱。

251* 互動式 shell 或連接埠轉發到敏感遠端目標252* 互動式 shell 或連接埠轉發到敏感遠端目標

252* 開啟隧道或反向 shell，使本地服務可從公開網際網路到達253* 開啟隧道或反向 shell，使本地服務可從公開網際網路到達

253* 將即時認證或令牌列印到記錄或檔案254* 將即時認證或令牌列印到記錄或檔案

254* 存取 PII 或受管制資料位置，或從其中複製資料255* 存取列為您[環境](/zh-TW/auto-mode-config#define-trusted-infrastructure)中敏感資料位置的位置，或從其中複製資料。{/* min-version: 2.1.198 */}從 v2.1.198 開始，這也會阻止將資料從一個發送到該項目排除的對象

255* 繞過您的內部套件登錄將套件安裝路由到公開登錄256* 繞過您的內部套件登錄將套件安裝路由到公開登錄。{/* min-version: 2.1.198 */}從 v2.1.198 開始，這也適用於您在對話中告訴 Claude 內部登錄或鏡像存在的情況，不僅當一個列在您的環境中時

256* 執行帶有標誌的命令，該標誌會解除安全防護，如 `--insecure`257* 執行帶有標誌的命令，該標誌會解除安全防護，如 `--insecure`

258* 啟動自主代理迴圈，在沒有人類批准或沙箱的情況下執行，例如使用 `--dangerously-skip-permissions` 或 `--no-sandbox` 啟動的迴圈。{/* min-version: 2.1.198 */}從 v2.1.198 開始，這也涵蓋執行第三方代理或評估工具，隔離和每個操作批准禁用，例如使用 `--yes-always` 啟動的執行器

257* [Chrome 中的 Claude](/zh-TW/chrome) 瀏覽器操作，可能會將頁面內容、Cookie 或認證發送到跨來源259* [Chrome 中的 Claude](/zh-TW/chrome) 瀏覽器操作，可能會將頁面內容、Cookie 或認證發送到跨來源

258 260

261Claude Code v2.1.198 及更新版本也預設阻止這些：

262

263* 通過通配符、glob 或年齡篩選器而不是特定命名路徑刪除 `/tmp`、`$TMPDIR` 或另一個共享暫存或快取目錄中的檔案

264* 在發送、上傳、發佈或寫入其他人或共享系統的內容中包含敏感詳細資訊，當您自己的訊息沒有授權這些詳細資訊給該收件人時

265* 將按鍵發送到 Claude Code 自己的 tmux 窗格以驅動其自己的介面，分類器將其視為 Claude 改變自己的權限或監督

266

259**預設允許**：267**預設允許**：

260 268

261* 工作目錄中的本地檔案操作269* 工作目錄中的本地檔案操作

272* 將資料發送到您在 [`environment`](/zh-TW/auto-mode-config#define-trusted-infrastructure) 中列出的受信任網域、儲存桶和服務。這僅涵蓋資料流，不涵蓋相同基礎設施上的破壞性或認證操作280* 將資料發送到您在 [`environment`](/zh-TW/auto-mode-config#define-trusted-infrastructure) 中列出的受信任網域、儲存桶和服務。這僅涵蓋資料流，不涵蓋相同基礎設施上的破壞性或認證操作

273* [Chrome 中的 Claude](/zh-TW/chrome) 導航到受信任的內部網域、localhost 或您命名的 URL281* [Chrome 中的 Claude](/zh-TW/chrome) 導航到受信任的內部網域、localhost 或您命名的 URL

274 282

275沙箱網路存取請求通過分類器路由，而不是預設允許。執行 `claude auto-mode defaults` 以查看完整規則列表。如果例行操作被阻止，管理員可以通過 `autoMode.environment` 設定添加受信任的倉庫、儲存桶和服務：請參閱[配置 auto mode](/zh-TW/auto-mode-config)。283沙箱網路存取請求通過分類器路由，而不是預設允許。{/* min-version: 2.1.198 */}從 v2.1.198 開始，分類器重複使用其對網路主機和連接埠的判決，而不是在每次連接時重新執行：

284

285* 允許被重複使用，直到新內容進入對話，此時該主機被再次檢查

286* 在互動式 CLI 中，拒絕在轉向結束時被丟棄

287* 在[非互動式模式](/zh-TW/headless)和 Agent SDK 會話中沒有轉向邊界，因此拒絕在執行的其餘部分被重複使用

288* 改變您的權限模式或規則會丟棄所有快取的判決

289

290執行 `claude auto-mode defaults` 以查看完整規則列表。如果例行操作被阻止，管理員可以通過 `autoMode.environment` 設定添加受信任的倉庫、儲存桶和服務：請參閱[配置 auto mode](/zh-TW/auto-mode-config)。

276 291

277<h3 id="boundaries-you-state-in-conversation">292<h3 id="boundaries-you-state-in-conversation">

278 您在對話中陳述的邊界293 您在對話中陳述的邊界

300 315

301 1. 與您的[允許或拒絕規則](/zh-TW/permissions#manage-permissions)相符的操作立即解決，除了寫入[受保護路徑](#protected-paths)，即使允許規則相符也會路由到分類器316 1. 與您的[允許或拒絕規則](/zh-TW/permissions#manage-permissions)相符的操作立即解決，除了寫入[受保護路徑](#protected-paths)，即使允許規則相符也會路由到分類器

302 2. 唯讀操作和工作目錄中的檔案編輯自動批准，除了寫入[受保護路徑](#protected-paths)317 2. 唯讀操作和工作目錄中的檔案編輯自動批准，除了寫入[受保護路徑](#protected-paths)

303 3. 其他所有內容都發送到分類器318 3. 其他所有內容都發送到分類器。{/* min-version: 2.1.199 */}從 v2.1.199 開始，標記有 [`_meta["anthropic/requiresUserInteraction"]`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具跳過分類器並直接提示您，因此同意步驟永遠不會代表工具作者自動批准

304 4. 如果分類器阻止，Claude 接收原因並嘗試替代方法319 4. 如果分類器阻止，Claude 接收原因並嘗試替代方法

305 320

306 進入 auto mode 時，授予任意程式碼執行的廣泛允許規則被刪除：321 進入 auto mode 時，授予任意程式碼執行的廣泛允許規則被刪除：

326 </Accordion>341 </Accordion>

327 342

328 <Accordion title="成本和延遲">343 <Accordion title="成本和延遲">

329 分類器在伺服器配置的模型上執行，獨立於您的 `/model` 選擇，因此切換模型不會改變分類器可用性。分類器呼叫計入您的令牌使用量。每次檢查發送記錄的一部分加上待處理操作，在執行前添加往返。工作目錄外受保護路徑的讀取和編輯跳過分類器，因此開銷主要來自 shell 命令和網路操作。344 分類器在伺服器配置的模型上執行，獨立於您的 `/model` 選擇，因此切換模型不會改變分類器可用性。分類器呼叫計入您的令牌使用量。每次檢查發送記錄的一部分加上待處理操作，在執行前添加往返。工作目錄外受保護路徑的讀取和編輯跳過分類器，因此開銷主要來自 shell 命令和網路操作。{/* min-version: 2.1.198 */}從 v2.1.198 開始，沙箱網路判決對於主機和連接埠被重複使用，而不是在每次連接時重新分類，因此重複連接到同一主機不會各自添加檢查。[分類器預設阻止的內容](#what-the-classifier-blocks-by-default)描述允許和拒絕持續多長時間。

330 </Accordion>345 </Accordion>

331</AccordionGroup>346</AccordionGroup>

332 347

334 使用 dontAsk 模式僅允許預先批准的工具349 使用 dontAsk 模式僅允許預先批准的工具

335</h2>350</h2>

336 351

337`dontAsk` 模式自動拒絕每個否則會提示的工具呼叫。僅與您的 `permissions.allow` 規則和[唯讀 Bash 命令](/zh-TW/permissions#read-only-commands)相符的操作可以執行；明確的 [`ask` 規則](/zh-TW/permissions#manage-permissions)被拒絕而不是提示。這使模式完全非互動式，適合 CI 管道或受限環境，您可以在其中預先定義 Claude 可能執行的操作。Cloud 工作階段在 [Claude Code on the web](/zh-TW/claude-code-on-the-web) 上忽略 `defaultMode: "dontAsk"`；詳見 [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode) 以了解詳情。352`dontAsk` 模式自動拒絕每個否則會提示的工具呼叫。狀態列顯示 `⏵⏵ don't ask on`，當此模式處於活動狀態時。只有符合您的 `permissions.allow` 規則和[唯讀 Bash 命令](/zh-TW/permissions#read-only-commands)的操作可以執行；明確的 [`ask` 規則](/zh-TW/permissions#manage-permissions)被拒絕而不是提示。{/* min-version: 2.1.199 */}自 v2.1.199 起，標記有 [`_meta["anthropic/requiresUserInteraction"]`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具在此模式中也會被拒絕，即使允許規則符合它，因為其批准卡需要此模式永遠不會收集的答案。這使模式完全非互動式，適合 CI 管道或受限環境，您可以在其中預先定義 Claude 可能執行的操作。[Claude Code on the web](/zh-TW/claude-code-on-the-web) 上的雲端工作階段忽略 `defaultMode: "dontAsk"`；詳見 [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode) 以了解詳情。

338 353

339在啟動時使用標誌設定它：354在啟動時使用標誌設定它：

340 355

346 使用 bypassPermissions 模式跳過所有檢查361 使用 bypassPermissions 模式跳過所有檢查

347</h2>362</h2>

348 363

349`bypassPermissions` 模式禁用權限提示和安全檢查，因此工具呼叫立即執行。自 v2.1.126 起，這包括寫入[受保護路徑](#protected-paths)，較早版本仍會提示。明確的[詢問規則](/zh-TW/permissions#manage-permissions)仍會在此模式中強制提示，針對檔案系統根目錄或主目錄的移除操作，例如 `rm -rf /` 和 `rm -rf ~`，仍會作為針對模型錯誤的斷路器而提示。僅在隔離環境（如容器、VM 或 dev container）中使用此模式，沒有網際網路存取，其中 Claude Code 無法損害您的主機系統。364`bypassPermissions` 模式禁用權限提示和安全檢查，因此工具呼叫立即執行。自 v2.1.126 起，這包括寫入[受保護路徑](#protected-paths)，較早版本仍會提示。明確的[詢問規則](/zh-TW/permissions#manage-permissions)仍會在此模式中強制提示，針對檔案系統根目錄或主目錄的移除操作，例如 `rm -rf /` 和 `rm -rf ~`，仍會作為針對模型錯誤的斷路器而提示。{/* min-version: 2.1.199 */}自 v2.1.199 起，標記有 [`_meta["anthropic/requiresUserInteraction"]`](/zh-TW/mcp#require-approval-for-a-specific-tool) 的 MCP 工具也仍會提示。僅在隔離環境（如容器、VM 或 dev container）中使用此模式，沒有網際網路存取，其中 Claude Code 無法損害您的主機系統。

350 365

351您無法從未使用啟用標誌啟動的會話進入 `bypassPermissions`；使用其中一個重新啟動以啟用它：366您無法從未使用啟用標誌啟動的會話進入 `bypassPermissions`；使用其中一個重新啟動以啟用它：

352 367

permissions.md +14 −3

Details

272Read 和 Edit 規則都遵循 [gitignore](https://git-scm.com/docs/gitignore) 規格，具有四種不同的模式類型：272Read 和 Edit 規則都遵循 [gitignore](https://git-scm.com/docs/gitignore) 規格，具有四種不同的模式類型：

273 273

274| 模式 | 意義 | 範例 | 符合 |274| 模式 | 意義 | 範例 | 符合 |

275| ----------------- | -------------- | -------------------------------- | ------------------------------ |275| ----------------- | -------------- | -------------------------------- | ----------------------------------- |

276| `//path` | 來自檔案系統根目錄的絕對路徑 | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**` |276| `//path` | 來自檔案系統根目錄的絕對路徑 | `Read(//Users/alice/secrets/**)` | `/Users/alice/secrets/**` |

277| `~/path` | 來自主目錄的路徑 | `Read(~/Documents/*.pdf)` | `/Users/alice/Documents/*.pdf` |277| `~/path` | 來自主目錄的路徑 | `Read(~/Documents/*.pdf)` | `/Users/alice/Documents/*.pdf` |

278| `/path` | 相對於專案根目錄的路徑 | `Edit(/src/**/*.ts)` | `<project root>/src/**/*.ts` |278| `/path` | 相對於設定來源的路徑 | `Edit(/src/**/*.ts)` | `<project root>/src/**/*.ts` 在專案設定中 |

279| `path` 或 `./path` | 相對於目前目錄的路徑 | `Read(*.env)` | `<cwd>/*.env` |279| `path` 或 `./path` | 相對於目前目錄的路徑 | `Read(*.env)` | `<cwd>/*.env` |

280 280

281<Warning>281<Warning>

282 像 `/Users/alice/file` 這樣的模式不是絕對路徑。它相對於專案根目錄。使用 `//Users/alice/file` 表示絕對路徑。282 像 `/Users/alice/file` 這樣的模式不是絕對路徑。單一前導斜線錨定在設定來源，而不是檔案系統根目錄。使用 `//Users/alice/file` 表示絕對路徑。

283</Warning>283</Warning>

284 284

285`/path` 模式錨定在與定義它的設定檔案相關聯的目錄，所以相同的規則根據您放置它的位置符合不同的位置：

286

287| 規則定義在 | `/path` 解析為 |

288| :-------------------------------- | :------------------------- |

289| 專案或本機設定，如 `.claude/settings.json` | `<project root>/path` |

290| 使用者設定在 `~/.claude/settings.json` | `~/.claude/path` |

291| 使用 `--settings <file>` 傳遞的檔案 | `<directory of file>/path` |

292| CLI 旗標、`/permissions` 或工作階段規則 | `<original cwd>/path` |

293

294像 `Read(/secrets/**)` 這樣的 deny 規則在使用者設定中會阻止 `~/.claude/secrets/**`，而不是您專案中的 `secrets` 目錄。若要在使用者設定中編寫適用於每個專案內部的規則，請改用 `//` 絕對路徑或 `~/` 主目錄相對路徑。

295

285在 Windows 上，路徑在符合前會被正規化為 POSIX 形式。`C:\Users\alice` 變成 `/c/Users/alice`，所以使用 `//c/**/.env` 來符合該磁碟上任何位置的 `.env` 檔案。若要符合所有磁碟，請使用 `//**/.env`。296在 Windows 上，路徑在符合前會被正規化為 POSIX 形式。`C:\Users\alice` 變成 `/c/Users/alice`，所以使用 `//c/**/.env` 來符合該磁碟上任何位置的 `.env` 檔案。若要符合所有磁碟，請使用 `//**/.env`。

286 297

287範例：298範例：

plugins.md +6 −4

Details

352當您對 plugin 進行變更時，執行 `/reload-plugins` 以取得更新，無需重新啟動。這會重新載入 plugins、skills、agents、hooks、plugin MCP servers 和 plugin LSP servers。測試您的 plugin 元件：352當您對 plugin 進行變更時，執行 `/reload-plugins` 以取得更新，無需重新啟動。這會重新載入 plugins、skills、agents、hooks、plugin MCP servers 和 plugin LSP servers。測試您的 plugin 元件：

353 353

354* 使用 `/plugin-name:skill-name` 嘗試您的 skills354* 使用 `/plugin-name:skill-name` 嘗試您的 skills

355* 檢查 agents 是否出現在 `/agents` 中355* 檢查 agents 是否出現在 `/context` 中的自訂 Agents 下，或透過其範圍名稱 @-提及其中一個

356* 驗證 hooks 是否按預期工作356* 驗證 hooks 是否按預期工作

357 357

358<Tip>358<Tip>

406 406

407Anthropic 為 Claude Code plugins 維護兩個公開市場：407Anthropic 為 Claude Code plugins 維護兩個公開市場：

408 408

409* **`claude-plugins-official`**：由 Anthropic 維護的精選 plugins 集合。在每個 Claude Code 安裝中自動可用。409* **`claude-plugins-official`**：由 Anthropic 維護的精選 plugins 集合。在您第一次以互動方式啟動 Claude Code 時自動註冊。在該首次啟動之前執行的非互動式指令碼必須使用 `claude plugin marketplace add anthropics/claude-plugins-official` 明確新增它。

410* **`claude-community`**：公開社群市場，第三方提交在審查後會進入此市場。使用者使用 `/plugin marketplace add anthropics/claude-plugins-community` 新增它，並將其作為 `@claude-community` 進行安裝。410* **`claude-community`**：公開社群市場，第三方提交在審查後會進入此市場。使用者使用 `/plugin marketplace add anthropics/claude-plugins-community` 新增它，並將其作為 `@claude-community` 進行安裝。

411 411

412若要提交您的 plugin 以進行官方市場審查，請使用其中一個應用內提交表單：412若要提交您的 plugin 以進行官方市場審查，請使用其中一個應用內提交表單：

413 413

414* **Claude.ai**：[claude.ai/settings/plugins/submit](https://claude.ai/settings/plugins/submit)414* **claude.ai**：[claude.ai/admin-settings/directory/submissions/plugins/new](https://claude.ai/admin-settings/directory/submissions/plugins/new)

415* **Console**：[platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)415* **Console**：[platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)

416 416

417claude.ai 表單需要 Team 或 Enterprise 組織和目錄管理存取權；組織擁有者預設具有此存取權。不屬於 Team 或 Enterprise 組織的個別作者可以改用 Console 表單。

418

417在提交前在本地執行 `claude plugin validate`。審查管道在每個提交上執行相同的檢查，以及自動安全篩選。419在提交前在本地執行 `claude plugin validate`。審查管道在每個提交上執行相同的檢查，以及自動安全篩選。

418 420

419已批准的 plugins 會固定到 [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) 目錄中的特定 commit SHA，當您將新 commits 推送到您的儲存庫時，CI 會自動更新該固定。公開目錄每晚從審查管道同步，因此批准和您的 plugin 出現在 `marketplace.json` 之間可能會有延遲。若要檢查您的 plugin 是否已可安裝，請在[官方目錄](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)中搜尋其名稱。421已批准的 plugins 會固定到 [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) 目錄中的特定 commit SHA，當您將新 commits 推送到您的儲存庫時，CI 會自動更新該固定。公開目錄每晚從審查管道同步，因此批准和您的 plugin 出現在 `marketplace.json` 之間可能會有延遲。若要檢查您的 plugin 是否已可安裝，請在[官方目錄](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)中搜尋其名稱。

500 claude --plugin-dir ./my-plugin502 claude --plugin-dir ./my-plugin

501 ```503 ```

502 504

503 測試每個元件：執行您的命令、檢查 agents 是否出現在 `/agents` 中，並驗證 hooks 是否正確觸發。505 測試每個元件：執行您的命令、檢查 agents 是否出現在 `/context` 中，並驗證 hooks 是否正確觸發。

504 </Step>506 </Step>

505</Steps>507</Steps>

506 508

plugins-reference.md +1 −1

Details

79 79

80**整合點**：80**整合點**：

81 81

~~82* Agents 出現在 `/agents` 介面中~~82* Agents 出現在 [@-mention 下拉式選單](/zh-TW/sub-agents#invoke-subagents-explicitly) 中，其範圍名稱為 `my-plugin:code-reviewer`，一旦啟用 plugin

83* Claude 可以根據任務上下文自動叫用 agents83* Claude 可以根據任務上下文自動叫用 agents

84* Users 可以手動叫用 agents84* Users 可以手動叫用 agents

85* Plugin agents 與內建 Claude agents 一起運作85* Plugin agents 與內建 Claude agents 一起運作

sandboxing.md +43 −5

Details

199 保護認證199 保護認證

200</h3>200</h3>

201 201

202`sandbox.credentials` 設定聲明沙箱化命令不得存取的認證檔案和環境變數。列出的檔案路徑在沙箱內被拒絕讀取，與 `filesystem.denyRead` 應用的區塊相同，列出的環境變數在每個沙箱化命令執行前被取消設定。專用的 `credentials` 區塊將認證規則與環境變數取消設定分組，並與一般檔案系統規則分開。需要 Claude Code v2.1.187 或更新版本。202`sandbox.credentials` 設定聲明認證檔案和環境變數以保護沙箱化命令。每個項目命名一個檔案路徑或環境變數和一個 `mode`。專用的 `credentials` 區塊將認證規則分組在一起，並與一般檔案系統規則分開。需要 Claude Code v2.1.187 或更新版本。

203

204對於 `"mode": "deny"` 的項目，檔案路徑在沙箱內被拒絕讀取，與 `filesystem.denyRead` 應用的限制相同，環境變數在每個沙箱化命令執行前被取消設定。

203 205

204下面的範例阻止讀取 AWS 認證檔案和 SSH 目錄，並從沙箱化命令的環境中移除 `GITHUB_TOKEN` 和 `NPM_TOKEN`：206下面的範例阻止讀取 AWS 認證檔案和 SSH 目錄，並從沙箱化命令的環境中移除 `GITHUB_TOKEN` 和 `NPM_TOKEN`：

205 207

221}223}

222```224```

223 225

224每個項目都帶有 `"mode": "deny"`，這是唯一支援的值。明確的 `mode` 欄位使架構與未來的模式向前相容。檔案路徑遵循與 `sandbox.filesystem.*` 設定相同的 [prefix rules](/zh-TW/settings#sandbox-path-prefixes)，來自每個 [settings scope](/zh-TW/settings#settings-precedence) 的項目被合併。因為唯一的模式是 `deny`，任何範圍都可以新增限制，但沒有任何範圍可以移除它們。226檔案項目僅支援 `"mode": "deny"`。環境變數項目也接受 `"mode": "mask"`，如下所述。

227

228檔案路徑遵循與 `sandbox.filesystem.*` 設定相同的 [prefix rules](/zh-TW/settings#sandbox-path-prefixes)，來自每個 [settings scope](/zh-TW/settings#settings-precedence) 的 `deny` 項目被合併。`deny` 項目只會縮小存取，因此任何範圍都可以新增一個，但沒有任何範圍可以移除另一個範圍新增的項目。

225 229

226沒有內建的認證拒絕清單，因此只有您列出的檔案和變數被限制。此設定僅影響沙箱化 Bash 命令。若要從所有子流程中移除 Anthropic 和雲端提供者認證，無論沙箱化如何，請設定 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/zh-TW/env-vars)。230沒有內建的認證拒絕清單，因此只有您列出的檔案和變數被限制。此設定僅影響沙箱化 Bash 命令。若要從所有子流程中移除 Anthropic 和雲端提供者認證，無論沙箱化如何，請設定 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/zh-TW/env-vars)。

227 231

232<h4 id="mask-environment-variables">

233 遮罩環境變數

234</h4>

235

236`"mode": "mask"` 保護認證同時保持使用它進行身份驗證的工具正常工作。`deny` 完全移除變數，這也會破壞需要它的工具，例如 `gh` 或 `npm`。需要 Claude Code v2.1.199 或更新版本。

237

238使用 `mask`，沙箱化命令看到的是每個工作階段的哨兵值而不是真實值。當請求離開沙箱前往認證的 `injectHosts` 之一時，[sandbox proxy](#network-isolation) 將哨兵值替換為真實值。命令和它記錄的任何內容都不會持有真實認證，但其請求仍然進行身份驗證。

239

240代理在請求內容中替換認證，因此它必須看到它們。設定 [`network.tlsTerminate`](/zh-TW/settings#sandbox-settings) 以便代理自己終止 HTTPS。沒有它，遮罩會失敗關閉：命令仍然只看到哨兵值，但哨兵值不變地到達伺服器，身份驗證失敗。Claude Code 在啟動時和 `/doctor` 中報告此配置錯誤。

241

242下面的範例遮罩兩個令牌。`GH_TOKEN` 僅在對 `api.github.com` 的請求上被替換，而 `NPM_TOKEN` 沒有 `injectHosts` 並在對 `network.allowedDomains` 中每個主機的請求上被替換。每個 `injectHosts` 項目本身必須被 `network.allowedDomains` 覆蓋。

243

244```json theme={null}

245{

246 "sandbox": {

247 "enabled": true,

248 "network": {

249 "tlsTerminate": {},

250 "allowedDomains": ["*.github.com", "registry.npmjs.org"]

251 },

252 "credentials": {

253 "envVars": [

254 { "name": "GH_TOKEN", "mode": "mask", "injectHosts": ["api.github.com"] },

255 { "name": "NPM_TOKEN", "mode": "mask" }

256 ]

257 }

258 }

259}

260```

261

262與 `deny` 不同，遮罩授權代理將您的真實認證發送到列出的主機，因此它僅從您或您的管理員控制的設定中被尊重：使用者設定、受管設定和 `--settings` CLI 旗標。`mask` 項目、`network.tlsTerminate` 和 [`credentials.allowPlaintextInject`](/zh-TW/settings#sandbox-settings) 在儲存庫的 `.claude/settings.json` 或 `.claude/settings.local.json` 中被忽略。

263

264當相同的變數在任何範圍中以 `deny` 列出時，`deny` 優先。

265

228<h2 id="how-sandboxing-works">266<h2 id="how-sandboxing-works">

229 沙箱化如何運作267 沙箱化如何運作

230</h2>268</h2>

255* **全面覆蓋**：限制適用於所有指令碼、程式和由命令產生的子流程293* **全面覆蓋**：限制適用於所有指令碼、程式和由命令產生的子流程

256 294

257<Note>295<Note>

258 內建代理根據請求的主機名強制執行允許清單，不終止或檢查 TLS 流量。請參閱 [Security limitations](#security-limitations) 了解此設計的含義，以及 [Custom proxy configuration](#custom-proxy-configuration) 如果您的威脅模型需要 TLS 檢查。296 內建代理根據請求的主機名強制執行允許清單，預設不終止或檢查 TLS 流量。{/* min-version: 2.1.199 */}實驗性的 [`network.tlsTerminate`](/zh-TW/settings#sandbox-settings) 設定在 Claude Code v2.1.199 及更新版本中可用，使內建代理自行終止 TLS，這是 [`mask` 認證項目](#protect-credentials)所需的。請參閱 [Security limitations](#security-limitations) 了解預設設計的含義，以及 [Custom proxy configuration](#custom-proxy-configuration) 如果您的威脅模型需要 TLS 檢查。

259</Note>297</Note>

260 298

261<h3 id="os-level-enforcement">299<h3 id="os-level-enforcement">

412 安全限制450 安全限制

413</h3>451</h3>

414 452

415* **網路過濾**：網路過濾系統通過限制流程允許連接的域名來運作。內建代理不終止或對出站流量執行 TLS 檢查，因此加密連接的內容不被檢查。您負責確保只有受信任的域名在您的策略中被允許。453* **網路過濾**：沙箱限制流程可以連接的域名。預設情況下，內建代理不終止或檢查出站流量上的 TLS，因此加密連接的內容不被檢查。實驗性的 [`network.tlsTerminate`](/zh-TW/settings#sandbox-settings) 設定在代理處終止 TLS 以進行 [`mask` 認證替換](#protect-credentials)，但不添加內容過濾。您負責確保只有受信任的域名在您的策略中被允許。

416 454

417<Warning>455<Warning>

418 允許廣泛域名（例如 `github.com`）可能會為資料洩露建立路徑。因為代理根據用戶端提供的主機名進行允許決定而不檢查 TLS，在沙箱內執行的程式碼可能可以使用 [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) 或類似技術到達允許清單外的主機。如果您的威脅模型需要更強的保證，請配置 [custom proxy](#custom-proxy-configuration)，它終止 TLS 並檢查流量，並在沙箱內安裝其 CA 憑證。更強的 TLS 感知網路隔離是一個活躍的開發領域。456 允許廣泛域名（例如 `github.com`）可能會為資料洩露建立路徑。因為代理根據用戶端提供的主機名進行允許決定而不檢查 TLS，在沙箱內執行的程式碼可能可以使用 [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) 或類似技術到達允許清單外的主機。如果您的威脅模型需要更強的保證，請配置 [custom proxy](#custom-proxy-configuration)，它終止 TLS 並檢查流量，並在沙箱內安裝其 CA 憑證。更強的 TLS 感知網路隔離是一個活躍的開發領域。

440 478

441* **內建檔案工具**：Read、Edit 和 Write 直接使用權限系統，而不是通過沙箱執行。請參閱 [permissions](/zh-TW/permissions)。479* **內建檔案工具**：Read、Edit 和 Write 直接使用權限系統，而不是通過沙箱執行。請參閱 [permissions](/zh-TW/permissions)。

442* **電腦使用**：當 Claude 打開應用程式並控制您的螢幕時，它在您的實際桌面上執行，而不是在隔離環境中。每個應用程式的權限提示控制每個應用程式。請參閱 [CLI 中的電腦使用](/zh-TW/computer-use) 或 [Desktop 中的電腦使用](/zh-TW/desktop#let-claude-use-your-computer)。480* **電腦使用**：當 Claude 打開應用程式並控制您的螢幕時，它在您的實際桌面上執行，而不是在隔離環境中。每個應用程式的權限提示控制每個應用程式。請參閱 [CLI 中的電腦使用](/zh-TW/computer-use) 或 [Desktop 中的電腦使用](/zh-TW/desktop#let-claude-use-your-computer)。

443* **環境變數**：沙箱化 Bash 命令預設繼承父流程環境，包括在那裡設定的任何認證。使用 [`sandbox.credentials`](#protect-credentials) 為沙箱化命令取消設定特定變數，或設定 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/zh-TW/env-vars) 以從所有子流程中去除 Anthropic 和雲端提供商認證。481* **環境變數**：沙箱化 Bash 命令預設繼承父流程環境，包括在那裡設定的任何認證。使用 [`sandbox.credentials`](#protect-credentials) 為沙箱化命令取消設定或遮罩特定變數，或設定 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/zh-TW/env-vars) 以從所有子流程中去除 Anthropic 和雲端提供商認證。

444* **子代理**：[subagents](/zh-TW/sub-agents) 在與父工作階段相同的流程中執行，並使用相同的沙箱配置。當在父工作階段中啟用沙箱化時，子代理內的 Bash 命令被沙箱化。482* **子代理**：[subagents](/zh-TW/sub-agents) 在與父工作階段相同的流程中執行，並使用相同的沙箱配置。當在父工作階段中啟用沙箱化時，子代理內的 Bash 命令被沙箱化。

445 483

446<Warning>484<Warning>

server-managed-settings.md +26 −8

Details

153 153

154伺服器管理的設定和[端點管理的設定](/zh-TW/settings#settings-files)都佔據 Claude Code [設定階層](/zh-TW/settings#settings-precedence)中的最高層級。沒有其他設定層級可以覆蓋它們，包括命令列引數。154伺服器管理的設定和[端點管理的設定](/zh-TW/settings#settings-files)都佔據 Claude Code [設定階層](/zh-TW/settings#settings-precedence)中的最高層級。沒有其他設定層級可以覆蓋它們，包括命令列引數。

155 155

156在受管層級內，已設定的 [`policyHelper`](/zh-TW/settings#compute-managed-settings-with-a-policy-helper) 會優先於其他所有受管來源，包括伺服器管理的設定：其輸出成為該執行的唯一受管設定。否則，第一個傳遞非空設定的來源會獲勝。伺服器管理的設定會先檢查，然後是端點管理的設定。來源不會合併：如果伺服器管理的設定傳遞任何金鑰，其他端點管理的設定會被完全忽略。有一個例外適用：當任何管理員控制的受管來源設定時，會遵守一小組[跨來源鎖定金鑰](/zh-TW/settings#settings-precedence)（例如沙箱允許清單鎖定）；使用者可寫入的 HKCU 登錄層級被排除。如果伺服器管理的設定不傳遞任何內容，端點管理的設定會套用。156在受管層級內，已設定的 [`policyHelper`](/zh-TW/settings#compute-managed-settings-with-a-policy-helper) 會優先於其他所有受管來源，包括伺服器管理的設定：其輸出成為該執行的唯一受管設定。

157

158否則，Claude Code 會使用第一個傳遞非空設定的來源。伺服器管理的設定會先檢查，然後是端點管理的設定。來源不會合併：如果伺服器管理的設定傳遞任何金鑰，其他端點管理的設定會被完全忽略。如果伺服器管理的設定不傳遞任何內容，端點管理的設定會套用。

159

160有一個例外適用：當任何管理員控制的受管來源設定時，會遵守一小組[跨來源鎖定金鑰](/zh-TW/settings#settings-precedence)（例如沙箱允許清單鎖定）；使用者可寫入的 HKCU 登錄層級被排除。

157 161

158如果您在管理員主控台中清除伺服器管理的設定，意圖回退到端點管理的 plist 或登錄原則，請注意[快取的設定](#fetch-and-caching-behavior)會在用戶端機器上持續存在，直到下次成功擷取。執行 `/status` 以查看哪個受管來源處於作用中。162如果您在管理員主控台中清除伺服器管理的設定，意圖回退到端點管理的 plist 或登錄原則，請注意[快取的設定](#fetch-and-caching-behavior)會在用戶端機器上持續存在，直到下次成功擷取。執行 `/status` 以查看哪個受管來源處於作用中。

159 163

171 175

172**後續啟動並有快取設定：**176**後續啟動並有快取設定：**

173 177

174* 快取設定在啟動時立即套用178* 快取設定在啟動時立即套用，除了下面描述的傳輸、路由和驗證環境變數外

175* Claude Code 在背景擷取新鮮設定179* Claude Code 在背景擷取新鮮設定

176* 快取設定透過網路故障持續存在180* 快取設定透過網路故障持續存在。被保留的環境變數會保持被保留，直到擷取成功

181

182自 v2.1.198 起，Claude Code 會在快取的 `env` 區塊中保留三個環境變數類別，直到伺服器確認該工作階段的承載。這可防止快取的 Proxy、憑證授權單位、端點或認證值重新導向、攔截或重新驗證確認承載的設定擷取。強化只適用於伺服器擷取的設定快取：透過 MDM 或 `managed-settings.json` 部署的[端點管理的設定](/zh-TW/settings#settings-files)不受影響。被保留的類別為：

183

184* Proxy 和 TLS 設定，例如 `HTTPS_PROXY`、`NODE_EXTRA_CA_CERTS` 和 mTLS 用戶端憑證變數 `CLAUDE_CODE_CLIENT_CERT` 和 `CLAUDE_CODE_CLIENT_KEY`

185* API 路由和提供者選擇，包括 `ANTHROPIC_BASE_URL`、提供者選擇變數（例如 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_VERTEX`）以及提供者端點 URL（例如 `ANTHROPIC_BEDROCK_BASE_URL`）

186* 驗證認證，例如 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 和 `CLAUDE_CODE_OAUTH_TOKEN`

187

188快取 `env` 區塊中的所有其他金鑰（例如遙測和 OpenTelemetry 設定）會如之前一樣在啟動時套用。擷取成功後，被保留的變數會在工作階段的其餘時間套用。

189

190如果您的組織需要 Proxy 才能到達 `api.anthropic.com`，請在殼層環境或[使用者設定](/zh-TW/settings#settings-files)中設定它，而不是只在受管 `env` 區塊中設定。首次啟動沒有快取，因此這些來源已經是初始擷取的必要條件。

177 191

178Claude Code 自動套用設定更新而無需重新啟動，除了進階設定（例如 OpenTelemetry 設定）需要完整重新啟動才能生效。192Claude Code 自動套用設定更新而無需重新啟動，除了進階設定（例如 OpenTelemetry 設定）需要完整重新啟動才能生效。

179 193

207}221}

208```222```

209 223

210您也可以在[端點管理的](/zh-TW/settings#settings-files) MDM 設定檔或系統 `managed-settings.json` 檔案中設定此金鑰，以在首次啟動時強制執行失敗關閉行為，在任何伺服器承載被傳遞之前。自 v2.1.191 起，此旗標是上述[優先順序規則](#settings-precedence)的例外：當在任何受管來源中設定時，即使快取的伺服器管理承載也存在，它也會被接受，因此當伺服器管理的設定存在時，MDM 傳遞的值不會被忽略。設定擷取也會傳送 `Cache-Control: no-cache` 標頭，以便中間 HTTP Proxy 不會提供過時的回應。224您也可以在[端點管理的](/zh-TW/settings#settings-files) MDM 設定檔或系統 `managed-settings.json` 檔案中設定此金鑰，以在首次啟動時強制執行失敗關閉行為，在任何伺服器承載被傳遞之前。自 v2.1.191 起，此旗標是上述[優先順序規則](#settings-precedence)的例外：當在任何受管來源中設定時，即使快取的伺服器管理承載也存在，它也會被接受，因此當伺服器管理的設定存在時，MDM 傳遞的值不會被忽略。

225

226設定擷取也會傳送 `Cache-Control: no-cache` 標頭，以便中間 HTTP Proxy 不會提供過時的回應。

211 227

212在啟用此設定之前，請確保您的網路原則允許連線到 `api.anthropic.com`。如果該端點無法到達，CLI 會在啟動時結束，使用者無法啟動 Claude Code。228在啟用此設定之前，請確保您的網路原則允許連線到 `api.anthropic.com`。如果該端點無法到達，CLI 會在啟動時結束，使用者無法啟動 Claude Code。

213 229

234 平台可用性250 平台可用性

235</h2>251</h2>

236 252

237伺服器管理的設定需要直接連線到 `api.anthropic.com`，並且傳遞需要工作階段使用組織 OAuth 登入或直接配置的 API 金鑰進行驗證：由 [`apiKeyHelper`](/zh-TW/settings#available-settings) 指令碼傳回的金鑰不會觸發設定擷取。在使用第三方模型提供者時，伺服器管理的設定無法使用：253伺服器管理的設定需要直接連線到 `api.anthropic.com`，並且傳遞需要工作階段使用組織 OAuth 登入或直接配置的 API 金鑰進行驗證。由 [`apiKeyHelper`](/zh-TW/settings#available-settings) 指令碼傳回的金鑰不會觸發設定擷取。

254

255在使用第三方模型提供者時，伺服器管理的設定無法使用：

238 256

239* Amazon Bedrock257* Amazon Bedrock

240* Google Vertex AI258* Google Vertex AI

259伺服器管理的設定提供集中式原則強制執行，但它們作為用戶端控制運作，而非安全邊界。在非受管裝置上，使用者不需要管理員或 sudo 存取權就能略過它們。277伺服器管理的設定提供集中式原則強制執行，但它們作為用戶端控制運作，而非安全邊界。在非受管裝置上，使用者不需要管理員或 sudo 存取權就能略過它們。

260 278

261| 情況 | 行為 |279| 情況 | 行為 |

262| :-------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |280| :-------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

263| 使用者編輯快取的設定檔 | 篡改的檔案在啟動時套用，但正確的設定會在下次伺服器擷取時還原 |281| 使用者編輯快取的設定檔 | 篡改的檔案在啟動時套用，但正確的設定會在下次伺服器擷取時還原。{/* min-version: 2.1.198 */}自 v2.1.198 起，`env` 區塊中的傳輸、API 路由和驗證環境變數會[在伺服器確認承載後才提供](#fetch-and-caching-behavior) |

264| 使用者刪除快取的設定檔 | 首次啟動行為發生：設定非同步擷取，有一個簡短的未強制執行視窗 |282| 使用者刪除快取的設定檔 | 首次啟動行為發生：設定非同步擷取，有一個簡短的未強制執行視窗 |

265| 使用者執行修改過的 Claude Code 二進位檔 | 能夠執行修改過用戶端的使用者可以略過任何用戶端控制 |283| 使用者執行修改過的 Claude Code 二進位檔 | 能夠執行修改過用戶端的使用者可以略過任何用戶端控制 |

266| 使用者執行較舊的 Claude Code 版本 | 早於伺服器管理設定的版本不會擷取或套用它們 |284| 使用者執行較舊的 Claude Code 版本 | 早於伺服器管理設定的版本不會擷取或套用它們 |

267| API 無法使用 | 如果可用，快取設定會套用，否則受管設定在下次成功擷取之前不會強制執行。使用 `forceRemoteSettingsRefresh: true` 時，CLI 會結束而不是繼續，除了 [`claude auth` 子命令](#enforce-fail-closed-startup) |285| API 無法使用 | 如果可用，快取設定會套用，否則受管設定在下次成功擷取之前不會強制執行。{/* min-version: 2.1.198 */}自 v2.1.198 起，快取 `env` 區塊中的傳輸、API 路由和驗證環境變數會[在擷取失敗時被保留](#fetch-and-caching-behavior)；快取的其餘部分仍然適用。使用 `forceRemoteSettingsRefresh: true` 時，CLI 會結束而不是繼續，除了 [`claude auth` 子命令](#enforce-fail-closed-startup) |

268| 使用者使用不同的組織進行身份驗證 | 不會為受管組織外的帳戶傳遞設定 |286| 使用者使用不同的組織進行身份驗證 | 不會為受管組織外的帳戶傳遞設定 |

269| 使用者設定[第三方模型提供者](#platform-availability) | 伺服器管理的設定會被略過。這包括設定 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_MANTLE`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY`、`CLAUDE_CODE_USE_ANTHROPIC_AWS` 或非預設的 `ANTHROPIC_BASE_URL` |287| 使用者設定[第三方模型提供者](#platform-availability) | 伺服器管理的設定會被略過。這包括設定 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_MANTLE`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY`、`CLAUDE_CODE_USE_ANTHROPIC_AWS` 或非預設的 `ANTHROPIC_BASE_URL` |

270| 網路流量被攔截或重新導向 | 停用的 TLS 驗證或攔截的流量可以改變用戶端接收的設定 |288| 網路流量被攔截或重新導向 | 停用的 TLS 驗證或攔截的流量可以改變用戶端接收的設定 |

sessions.md +2 −0

Details

97/branch try-streaming-approach97/branch try-streaming-approach

98```98```

99 99

100如果您省略名稱，Claude Code 會根據對話中的第一個提示為新分支命名。從 v2.1.198 開始，這也適用於 [壓縮](/zh-TW/how-claude-code-works#when-context-fills-up) 之後；較早的版本會回退到字面名稱 `Branched conversation`，而不是查看壓縮摘要之外的原始第一個提示。

101

100從命令列，將 `--continue` 或 `--resume` 與 `--fork-session` 結合：102從命令列，將 `--continue` 或 `--resume` 與 `--fork-session` 結合：

101 103

102```bash theme={null}104```bash theme={null}

settings.md +13 −10

Details

398設定進階 sandboxing 行為。Sandboxing 將 bash 命令與您的檔案系統和網路隔離。請參閱 [Sandboxing](/zh-TW/sandboxing) 以了解詳細資訊。398設定進階 sandboxing 行為。Sandboxing 將 bash 命令與您的檔案系統和網路隔離。請參閱 [Sandboxing](/zh-TW/sandboxing) 以了解詳細資訊。

399 399

400| 金鑰 | 說明 | 範例 |400| 金鑰 | 說明 | 範例 |

401| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |401| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

403| `failIfUnavailable` | 如果 `sandbox.enabled` 為 true 但 sandbox 無法啟動（遺失相依性、不支援的平台），則在啟動時以錯誤結束。當為 false（預設）時，會顯示警告，命令會以 unsandboxed 方式執行。適用於需要 sandboxing 作為硬閘門的 managed 設定部署 | `true` |403| `failIfUnavailable` | 如果 `sandbox.enabled` 為 true 但 sandbox 無法啟動（遺失相依性、不支援的平台），則在啟動時以錯誤結束。當為 false（預設）時，會顯示警告，命令會以 unsandboxed 方式執行。適用於需要 sandboxing 作為硬閘門的 managed 設定部署 | `true` |

410| `filesystem.allowRead` | 在 `denyRead` 區域內重新允許讀取的路徑。優先於 `denyRead`。陣列跨所有設定範圍合併。使用此選項建立僅工作區讀取存取模式。 | `["."]` |410| `filesystem.allowRead` | 在 `denyRead` 區域內重新允許讀取的路徑。優先於 `denyRead`。陣列跨所有設定範圍合併。使用此選項建立僅工作區讀取存取模式。 | `["."]` |

412| `credentials.files` | Sandboxed 命令無法讀取的認證檔案或目錄。應用與 `filesystem.denyRead` 相同的讀取區塊；單獨的金鑰將認證路徑與 `credentials.envVars` 分組，並與一般檔案系統規則分開。每個項目為 `{ "path": "...", "mode": "deny" }`。路徑使用與 `filesystem.*` 設定相同的[前綴](#sandbox-path-prefixes)。陣列跨所有設定範圍合併。僅支援 `deny`。需要 Claude Code v2.1.187 或更新版本。 | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |412| `credentials.files` | {/* min-version: 2.1.187 */}Sandboxed 命令無法讀取的認證檔案或目錄。應用與 `filesystem.denyRead` 相同的讀取區塊；單獨的金鑰將認證路徑與 `credentials.envVars` 分組，並與一般檔案系統規則分開。每個項目為 `{ "path": "...", "mode": "deny" }`，僅支援 `deny`。路徑使用與 `filesystem.*` 設定相同的[前綴](#sandbox-path-prefixes)。陣列跨所有設定範圍合併。需要 Claude Code v2.1.187 或更新版本。 | `[{ "path": "~/.aws/credentials", "mode": "deny" }]` |

413| `credentials.envVars` | 在執行 sandboxed 命令前要取消設定的環境變數。每個項目為 `{ "name": "...", "mode": "deny" }`。陣列跨所有設定範圍合併。僅支援 `deny`。需要 Claude Code v2.1.187 或更新版本。 | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |413| `credentials.envVars` | {/* min-version: 2.1.187 */}環境變數以[保護免受 sandboxed 命令](/zh-TW/sandboxing#protect-credentials)。每個項目有一個 `name` 和一個 `mode`；名稱必須以字母或底線開頭，並僅包含字母、數字和底線。`deny` 從 sandboxed 命令的環境中移除變數。需要 Claude Code v2.1.187 或更新版本。{/* min-version: 2.1.199 */}}`mask` 在 sandbox 內用每個工作階段的 sentinel 值替換變數，而 sandbox 代理在該項目的 `injectHosts` 的出站請求上替換真實值；它需要 `network.tlsTerminate` 和 Claude Code v2.1.199 或更新版本。`mask` 項目僅從使用者、managed 或 CLI `--settings` 設定受尊重，不從 `.claude/settings.json` 或 `.claude/settings.local.json`。陣列跨所有設定範圍合併，當相同變數同時出現兩種模式時 `deny` 優先。 | `[{ "name": "GITHUB_TOKEN", "mode": "deny" }]` |

414| `network.allowUnixSockets` | （僅限 macOS）sandbox 中可存取的 Unix socket 路徑。在 Linux 和 WSL2 上被忽略，其中 seccomp 篩選器無法檢查 socket 路徑；改用 `allowAllUnixSockets`。 | `["~/.ssh/agent-socket"]` |414| `credentials.envVars[].injectHosts` | {{/* min-version: 2.1.199 */}}Sandbox 代理替換 `mask` 項目真實值的主機。每個主機也必須由 `network.allowedDomains` 涵蓋，無論是精確還是通過萬用字元。未設定時，代理在 `network.allowedDomains` 中的每個主機上替換值。當 `mode` 為 `deny` 時被接受但忽略。需要 Claude Code v2.1.199 或更新版本。 | `["api.github.com"]` |

415| `credentials.allowPlaintextInject` | {{/* min-version: 2.1.199 */}}允許 `mask` 替換在純 HTTP 請求以及 TLS 終止的 HTTPS 上。在純 HTTP 上，上游身份未驗證，認證以明文形式傳輸，因此在受信任的測試網路外保持此設定關閉。僅從使用者、managed 或 CLI `--settings` 設定受尊重，不從 `.claude/settings.json` 或 `.claude/settings.local.json`。預設：false。需要 Claude Code v2.1.199 或更新版本。 | `true` |

416| `network.allowUnixSockets` | （macOS 僅限）sandbox 中可存取的 Unix socket 路徑。在 Linux 和 WSL2 上被忽略，其中 seccomp 篩選器無法檢查 socket 路徑；改用 `allowAllUnixSockets`。 | `["~/.ssh/agent-socket"]` |

415| `network.allowAllUnixSockets` | 允許 sandbox 中的所有 Unix socket 連線。在 Linux 和 WSL2 上，這是允許 Unix sockets 的唯一方式，因為它跳過了 seccomp 篩選器，否則會阻止 `socket(AF_UNIX, ...)` 呼叫。預設：false | `true` |417| `network.allowAllUnixSockets` | 允許 sandbox 中的所有 Unix socket 連線。在 Linux 和 WSL2 上，這是允許 Unix sockets 的唯一方式，因為它跳過了 seccomp 篩選器，否則會阻止 `socket(AF_UNIX, ...)` 呼叫。預設：false | `true` |

419| `network.deniedDomains` | 允許阻止出站網路流量的網域陣列。支援與 `allowedDomains` 相同的萬用字元語法。當兩者都符合時優先於 `allowedDomains`。無論 `allowManagedDomainsOnly` 如何，都從所有設定來源合併。 | `["sensitive.cloud.example.com"]` |421| `network.deniedDomains` | 允許阻止出站網路流量的網域陣列。支援與 `allowedDomains` 相同的萬用字元語法。當兩者都符合時優先於 `allowedDomains`。無論 `allowManagedDomainsOnly` 如何，都從所有設定來源合併。 | `["sensitive.cloud.example.com"]` |

420| `network.allowManagedDomainsOnly` | （Managed 設定僅限）僅尊重 managed 設定中的 `allowedDomains` 和 `WebFetch(domain:...)` 允許規則。來自使用者、專案和本機設定的網域會被忽略。非允許的網域會自動阻止，不會提示使用者。拒絕的網域仍從所有來源受尊重。預設：false | `true` |422| `network.allowManagedDomainsOnly` | （Managed 設定僅限）僅尊重 managed 設定中的 `allowedDomains` 和 `WebFetch(domain:...)` 允許規則。來自使用者、專案和本機設定的網域會被忽略。非允許的網域會自動阻止，不會提示使用者。拒絕的網域仍從所有來源受尊重。預設：false | `true` |

421| `network.httpProxyPort` | 如果您想帶上自己的代理，使用的 HTTP 代理連接埠。如果未指定，Claude 將執行自己的代理。 | `8080` |423| `network.httpProxyPort` | 如果您想帶上自己的代理，使用的 HTTP 代理連接埠。如果未指定，Claude 將執行自己的代理。 | `8080` |

422| `network.socksProxyPort` | 如果您想帶上自己的代理，使用的 SOCKS5 代理連接埠。如果未指定，Claude 將執行自己的代理。 | `8081` |424| `network.socksProxyPort` | 如果您想帶上自己的代理，使用的 SOCKS5 代理連接埠。如果未指定，Claude 將執行自己的代理。 | `8081` |

423| `enableWeakerNestedSandbox` | 為無特權 Docker 環境啟用較弱的 sandbox（僅限 Linux 和 WSL2）。**降低安全性。** 預設：false | `true` |425| `network.tlsTerminate` | {{/* min-version: 2.1.199 */}}實驗性。在 sandbox 代理內終止 TLS，以便它可以讀取 HTTPS 請求的內容。[credential substitution](/zh-TW/sandboxing#protect-credentials) 的 `mask` 需要。設定 `{}` 以為工作階段產生臨時憑證授權單位，或設定 `caCertPath` 和 `caKeyPath` 以使用您自己的。僅從使用者、managed 或 CLI `--settings` 設定受尊重，不從 `.claude/settings.json` 或 `.claude/settings.local.json`。需要 Claude Code v2.1.199 或更新版本。 | `{}` |

425| `allowAppleEvents` | （僅限 macOS）允許 sandboxed 命令傳送 Apple Events。`open`、`osascript` 和在瀏覽器中開啟 URL 的工具需要，否則會失敗並出現錯誤 `-600`。**移除程式碼執行隔離。** Sandboxed 命令可以啟動其他應用程式 unsandboxed，無需使用者提示；它們也可以傳送 AppleScript 命令到執行中的應用程式（例如終端機），受限於每個應用程式的 macOS 自動化同意提示 (TCC)。僅從使用者、managed 或 CLI 設定受尊重，不從專案設定。預設：false | `true` |427| `enableWeakerNetworkIsolation` | （macOS 僅限）允許在 sandbox 中存取系統 TLS 信任服務（`com.apple.trustd.agent`）。使用 `httpProxyPort` 和自訂 CA 的 MITM 代理時，Go 型工具（如 `gh`、`gcloud` 和 `terraform`）需要驗證 TLS 憑證。**透過開啟潛在的資料外洩路徑降低安全性**。預設：false | `true` |

428| `allowAppleEvents` | （macOS 僅限）允許 sandboxed 命令傳送 Apple Events。`open`、`osascript` 和在瀏覽器中開啟 URL 的工具需要，否則會失敗並出現錯誤 `-600`。**移除程式碼執行隔離。** Sandboxed 命令可以啟動其他應用程式 unsandboxed，無需使用者提示；它們也可以傳送 AppleScript 命令到執行中的應用程式（例如終端機），受限於每個應用程式的 macOS 自動化同意提示 (TCC)。僅從使用者、managed 或 CLI 設定受尊重，不從專案設定。預設：false | `true` |

426| `bwrapPath` | （Managed 設定僅限，Linux/WSL2）bubblewrap (`bwrap`) 二進位檔的絕對路徑。覆蓋透過 `PATH` 的自動偵測。僅從 [managed 設定](/zh-TW/settings#settings-files)受尊重，不從使用者或專案設定。在 managed 環境中 `bwrap` 安裝在非標準位置時很有用。 | `/opt/admin/bwrap` |429| `bwrapPath` | （Managed 設定僅限，Linux/WSL2）bubblewrap (`bwrap`) 二進位檔的絕對路徑。覆蓋透過 `PATH` 的自動偵測。僅從 [managed 設定](/zh-TW/settings#settings-files)受尊重，不從使用者或專案設定。在 managed 環境中 `bwrap` 安裝在非標準位置時很有用。 | `/opt/admin/bwrap` |

428 431

6601. **Managed 設定**（[伺服器管理](/zh-TW/server-managed-settings)、[MDM/OS 層級政策](#configuration-scopes)或 [managed 設定](/zh-TW/settings#settings-files)）6631. **Managed 設定**（[伺服器管理](/zh-TW/server-managed-settings)、[MDM/OS 層級政策](#configuration-scopes)或 [managed 設定](/zh-TW/settings#settings-files)）

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

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

663 * 在 managed 層級內，優先順序為：[`policyHelper`](#compute-managed-settings-with-a-policy-helper) 輸出（當設定時是唯一使用的 managed 來源）> 遠端（claude.ai [伺服器管理](/zh-TW/server-managed-settings)或 [Claude apps gateway](/zh-TW/claude-apps-gateway)傳遞）> MDM/OS 層級政策 > 檔案型（`managed-settings.d/*.json` + `managed-settings.json`）> HKCU 登錄（僅限 Windows）。僅使用一個 managed 來源；來源不合併跨層級，有一個例外：sandbox 鎖定金鑰 `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly`，以及其相關聯的白名單、`allowAllClaudeAiMcps` 和 sandbox 二進位路徑 `sandbox.bwrapPath` 和 `sandbox.socatPath` 在任何管理員控制的 managed 來源設定它們時受尊重；使用者可寫的 HKCU 層級被排除。在檔案型層級內，放入檔案和基礎檔案會合併在一起。666 * 在 managed 層級內，僅使用一個 managed 來源，優先順序為：[`policyHelper`](#compute-managed-settings-with-a-policy-helper) 輸出（當設定時是唯一使用的 managed 來源）> 遠端（claude.ai [伺服器管理](/zh-TW/server-managed-settings)或 [Claude apps gateway](/zh-TW/claude-apps-gateway)傳遞）> MDM/OS 層級政策 > 檔案型（`managed-settings.d/*.json` 和 `managed-settings.json` 合併在一起）> HKCU 登錄（僅限 Windows）。來源不跨層級合併，有一個例外：sandbox 鎖定金鑰 `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly` 及其相關聯的白名單、`allowAllClaudeAiMcps` 和 sandbox 二進位路徑 `sandbox.bwrapPath` 和 `sandbox.socatPath` 在任何管理員控制的 managed 來源設定它們時受尊重；使用者可寫的 HKCU 層級被排除。

664 * 嵌入主機（例如 Claude Desktop）可以透過 SDK `managedSettings` 選項提供政策。預設情況下，當任何 admin 部署的 managed 來源存在時，此會被忽略：伺服器管理的設定、MDM 或 OS 層級政策，或 managed 設定檔案。使用者可寫的 HKCU 登錄回退不計為 admin 部署的來源。管理員可以透過設定 [`parentSettingsBehavior`](#available-settings) 為 `"merge"` 來選擇加入。嵌入器的值會被篩選，以便它們可以收緊 managed 政策但不能放鬆政策。667 * 嵌入主機（例如 Claude Desktop）可以透過 SDK `managedSettings` 選項提供政策。預設情況下，當任何 admin 部署的 managed 來源存在時，此會被忽略：伺服器管理的設定、MDM 或 OS 層級政策，或 managed 設定檔案。使用者可寫的 HKCU 登錄回退不計為 admin 部署的來源。管理員可以透過設定 [`parentSettingsBehavior`](#available-settings) 為 `"merge"` 來選擇加入。嵌入器的值會被篩選，以便它們可以收緊 managed 政策但不能放鬆政策。

665 668

6662. **命令列引數**6692. **命令列引數**

setup.md +1 −1

Details

453 使用 npm 安裝453 使用 npm 安裝

454</h3>454</h3>

455 455

456您也可以將 Claude Code 安裝為全域 npm 套件。該套件需要 [Node.js 18 或更新版本](https://nodejs.org/en/download)。456您也可以將 Claude Code 安裝為全域 npm 套件。自 v2.1.198 起，npm 套件需要 [Node.js 22 或更新版本](https://nodejs.org/en/download)。在較舊的 Node.js 版本上，npm 在安裝期間列印 `EBADENGINE` 警告而不是失敗；安裝完成且 `claude` 仍然執行，因為該套件下載不使用您的 Node.js 的原生二進位檔案。

457 457

458```bash theme={null}458```bash theme={null}

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

skills.md +6 −0

Details

443 443

444如果您使用引數叫用 skill，但 skill 不包含 `$ARGUMENTS`，Claude Code 會將 `ARGUMENTS: <your input>` 附加到 skill 內容的末尾，以便 Claude 仍然看到您輸入的內容。444如果您使用引數叫用 skill，但 skill 不包含 `$ARGUMENTS`，Claude Code 會將 `ARGUMENTS: <your input>` 附加到 skill 內容的末尾，以便 Claude 仍然看到您輸入的內容。

445 445

446您也可以在一則訊息的開始堆疊多個 skills。自 v2.1.199 起，輸入 `/code-review /fix-issue 123` 會載入兩個 skills，並將尾部文字 `123` 作為 `$ARGUMENTS` 傳遞給每個 skills。在較早的版本中，只有第一個 skill 載入並接收 `/fix-issue 123` 作為字面引數文字。

447

448Claude Code 展開第一個 skill 加上最多五個堆疊在其後的 skills。展開在第一個不是內聯使用者可叫用 skill 的令牌處停止，因此作為[分叉 subagent](#run-skills-in-a-subagent) 執行的 skill 或其引數本身可能以斜線命令開始的 skill（例如 `/loop`）也在那裡結束；該令牌及其後的所有內容成為每個展開 skill 的引數文字。

449

446若要按位置存取個別引數，請使用 `$ARGUMENTS[N]` 或較短的 `$N`：450若要按位置存取個別引數，請使用 `$ARGUMENTS[N]` 或較短的 `$N`：

447 451

448```yaml theme={null}452```yaml theme={null}

624| `"user-invocable-only"` | 隱藏 | 是 |628| `"user-invocable-only"` | 隱藏 | 是 |

625| `"off"` | 隱藏 | 隱藏 |629| `"off"` | 隱藏 | 隱藏 |

626 630

631自 v2.1.199 起，`"off"` 也會從廣告給 [Remote Control](/zh-TW/remote-control) 用戶端和 [Agent SDK](/zh-TW/agent-sdk/slash-commands) 呼叫者的命令列表中隱藏 skill，而不僅僅是終端 `/` 功能表。透過其完整名稱叫用隱藏的 skill 仍會返回 `skillOverrides` 錯誤，而不是執行它。

632

627`skillOverrides` 中不存在的 skill 被視為 `"on"`。下面的範例將一個 skill 摺疊為其名稱，並完全關閉另一個：633`skillOverrides` 中不存在的 skill 被視為 `"on"`。下面的範例將一個 skill 摺疊為其名稱，並完全關閉另一個：

628 634

629```json theme={null}635```json theme={null}

sub-agents.md +90 −66

Details

24 24

25Claude 使用每個 subagent 的描述來決定何時委派任務。當您建立 subagent 時，請寫一個清晰的描述，以便 Claude 知道何時使用它。25Claude 使用每個 subagent 的描述來決定何時委派任務。當您建立 subagent 時，請寫一個清晰的描述，以便 Claude 知道何時使用它。

26 26

~~27Claude Code 包括幾個內建 subagents，如 **Explore**、**Plan** 和 **general-purpose**。您也可以建立自訂 subagents 來處理特定任務。~~27Claude Code 包括幾個內建 subagents，如 Explore、Plan 和 general-purpose。您也可以建立自訂 subagents 來處理特定任務。

28 28

29<h2 id="built-in-subagents">29<h2 id="built-in-subagents">

30 內建 subagents30 內建 subagents

38 <Tab title="Explore">38 <Tab title="Explore">

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

40 40

~~41 * **Model**：Haiku（快速、低延遲）~~41 * **Model**：繼承自主要對話，在 Claude API 上限制為 Opus，因此 Explore 永遠不會在比您已為工作階段選擇的模型更昂貴的模型上執行

~~42 * **Tools**：唯讀工具（拒絕存取 Write 和 Edit 工具）~~42 * **Tools**：唯讀工具；Write 和 Edit 被拒絕

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

44 44

45 {/* min-version: 2.1.198 */}自 v2.1.198 起，Explore 繼承主要對話的模型，而不是始終在 Haiku 上執行。在 Claude API 上，繼承的模型限制為 Opus：主要對話在更高層級上會在 Opus 上執行 Explore，而主要對話在 Sonnet 或 Haiku 上會在相同模型上執行 Explore。在任何其他提供者上，例如 [Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform](/zh-TW/third-party-integrations)，Explore 直接繼承主要對話的模型。

47 一個名為 `Explore` 的[使用者或專案 subagent](#choose-the-subagent-scope) 會覆蓋內建的，並保留其自己的 `model` 欄位，因此定義一個具有 `model: haiku` 的以保持探索在較低成本的模型上。

45 當 Claude 需要搜尋或理解程式碼庫而不進行更改時，它會委派給 Explore。這樣可以將探索結果保持在主要對話上下文之外。49 當 Claude 需要搜尋或理解程式碼庫而不進行更改時，它會委派給 Explore。這樣可以將探索結果保持在主要對話上下文之外。

46 50

47 當呼叫 Explore 時，Claude 指定一個徹底程度：**quick** 用於目標查詢，**medium** 用於平衡探索，或 **very thorough** 用於全面分析。51 當呼叫 Explore 時，Claude 指定一個徹底程度：**quick** 用於目標查詢，**medium** 用於平衡探索，或 **very thorough** 用於全面分析。

77 </Tab>81 </Tab>

78</Tabs>82</Tabs>

79 83

~~80內建 subagents 在互動式工作階段中始終會被註冊。若要限制它們：~~84內建 subagents 在互動式工作階段中預設會被註冊。若要限制它們：

81 85

82* 若要封鎖特定的內建類型，請將其新增至 `permissions.deny`，如[停用特定 subagents](#disable-specific-subagents) 中所示。86* 若要封鎖特定的內建類型，請將其新增至 `permissions.deny`，如[停用特定 subagents](#disable-specific-subagents) 中所示。

83* 若要防止 Claude 委派給任何 subagent，請使用 [`permissions.deny`](/zh-TW/permissions#tool-specific-permission-rules) 拒絕 `Agent` 工具本身。87* 若要防止 Claude 委派給任何 subagent，請使用 [`permissions.deny`](/zh-TW/permissions#tool-specific-permission-rules) 拒絕 `Agent` 工具本身。

88* {/* min-version: 2.1.198 */}若要僅移除內建的 `Explore` 和 `Plan` subagents，請設定 [`CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1`](/zh-TW/env-vars)。Claude 會直接讀取和探索檔案，而不是委派給它們。需要 Claude Code v2.1.198 或更新版本。

84* 在[非互動式模式](/zh-TW/headless)和 [Agent SDK](/zh-TW/agent-sdk/overview) 中，設定 [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/zh-TW/env-vars) 以移除所有內建類型，並僅提供您自己的。89* 在[非互動式模式](/zh-TW/headless)和 [Agent SDK](/zh-TW/agent-sdk/overview) 中，設定 [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/zh-TW/env-vars) 以移除所有內建類型，並僅提供您自己的。

85 90

86除了這些內建 subagents 之外，您可以建立自己的 subagents，具有自訂提示、工具限制、權限模式、hooks 和 skills。以下部分展示如何開始和自訂 subagents。91除了這些內建 subagents 之外，您可以建立自己的 subagents，具有自訂提示、工具限制、權限模式、hooks 和 skills。以下部分展示如何開始和自訂 subagents。

89 快速入門：建立您的第一個 subagent94 快速入門：建立您的第一個 subagent

90</h2>95</h2>

91 96

~~92Subagents 在 Markdown 檔案中定義，具有 YAML frontmatter。您可以 [手動建立它們](#write-subagent-files) 或使用 `/agents` 命令。~~97Subagents 是具有 YAML frontmatter 的 Markdown 檔案。若要建立一個，請要求 Claude 為您撰寫，或 [自行撰寫檔案](#write-subagent-files)。

93 98

~~94本逐步指南將引導您使用 `/agents` 命令建立使用者層級的 subagent。該 subagent 審查程式碼並為程式碼庫提出改進建議。~~99{/* min-version: 2.1.198 */}自 v2.1.198 起，`/agents` 命令不再開啟互動式建立精靈；執行它會列印提醒，要求您詢問 Claude 或直接編輯 `.claude/agents/`。Subagent 檔案、frontmatter 欄位以及 `.claude/agents/` 和 `~/.claude/agents/` 位置保持不變；只有終端精靈被移除。

100

101本逐步指南建立一個使用者層級的 subagent，用於審查程式碼並提出改進建議。

95 102

96<Steps>103<Steps>

~~97 <Step title="開啟 subagents 介面">~~104 <Step title="要求 Claude 建立 subagent">

~~98 在 Claude Code 中，執行：~~105 在 Claude Code 中，描述您想要的 subagent 及其儲存位置：

99 106

100 ```text wrap theme={null}107 ```text wrap theme={null}

101 /agents108 Create a personal code-improver subagent in ~/.claude/agents/ that scans

109 files and suggests improvements for readability, performance, and best

110 practices. It should explain each issue, show the current code, and

111 provide an improved version. Make it read-only and have it use Sonnet.

102 ```112 ```

103 </Step>

104 113

105 <Step title="選擇位置">114 Claude 會撰寫包含 `name`、`description`、`tools` 清單、`model` 和系統提示的檔案。

106 切換到 **Library** 標籤，選擇 **Create new agent**，然後選擇 **Personal**。這會將 subagent 儲存到 `~/.claude/agents/`，以便在所有專案中使用。

107 </Step>115 </Step>

108 116

109 <Step title="使用 Claude 生成">117 <Step title="檢查檔案">

110 選擇 **Generate with Claude**。出現提示時，描述 subagent：118 開啟 `~/.claude/agents/code-improver.md` 並確認 frontmatter 符合您的要求。結果如下所示：

111 119

112 ```text wrap theme={null}120 ```markdown theme={null}

113 A code improvement agent that scans files and suggests improvements121 ---

114 for readability, performance, and best practices. It should explain122 name: code-improver

115 each issue, show the current code, and provide an improved version.123 description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.

124 tools: Read, Grep, Glob

125 model: sonnet

126 ---

127

128 You are a code improvement specialist. For each issue you find, explain

129 the problem, show the current code, and provide an improved version.

116 ```130 ```

117 131

118 Claude 為您生成識別碼、描述和系統提示。132 因為檔案位於 `~/.claude/agents/`，所以 subagent 在您機器上的每個專案中都可用。若要改為將其範圍限制在一個專案，請將其移至該專案的 `.claude/agents/` 目錄。[選擇 subagent 範圍](#choose-the-subagent-scope) 比較了兩者。

119 </Step>133 </Step>

120 134

121 <Step title="選擇工具">135 <Step title="試試看">

122 對於唯讀審查者，取消選擇除 **Read-only tools** 之外的所有內容。如果您保持所有工具選中，subagent 將繼承主要對話可用的所有工具。136 要求 Claude 委派給新的 subagent：

123 </Step>

~~124~~

125 <Step title="選擇模型">

126 選擇 subagent 使用的模型。對於此範例代理，選擇 **Sonnet**，它在分析程式碼模式的能力和速度之間取得平衡。

127 </Step>

~~128~~

129 <Step title="選擇顏色">

130 為 subagent 選擇背景顏色。這可以幫助您在 UI 中識別哪個 subagent 正在執行。

131 </Step>

~~132~~

133 <Step title="配置記憶">

134 選擇 **User scope** 為 subagent 提供 [persistent memory directory](#enable-persistent-memory)，位於 `~/.claude/agent-memory/`。Subagent 使用此目錄在對話之間累積見解，例如程式碼庫模式和重複出現的問題。如果您不希望 subagent 保留學習，請選擇 **None**。

135 </Step>

~~136~~

137 <Step title="儲存並試用">

138 檢查配置摘要。按 `s` 或 `Enter` 儲存，或按 `e` 在編輯器中儲存並編輯檔案。Subagent 立即可用。試試看：

139 137

140 ```text wrap theme={null}138 ```text wrap theme={null}

141 Use the code-improver agent to suggest improvements in this project139 Use the code-improver agent to suggest improvements in this project

142 ```140 ```

143 141

144 Claude 委派給您的新 subagent，它掃描程式碼庫並返回改進建議。142 Claude 委派給您的新 subagent，它掃描程式碼庫並返回改進建議。

143

144 如果 Claude 找不到新的 subagent，請重新啟動 Claude Code 並再試一次。這只在 `~/.claude/agents/` 在工作階段開始前不存在時發生，因為執行中的工作階段不會偵測到新建立的 `agents` 目錄。

145 </Step>145 </Step>

146</Steps>146</Steps>

147 147

148現在您有一個 subagent，可以在機器上的任何專案中使用它來分析程式碼庫並提出改進建議。148現在您有一個 subagent，可以在機器上的任何專案中使用它來分析程式碼庫並提出改進建議。

149 149

150您也可以手動建立 subagents 作為 Markdown 檔案、透過 CLI 標誌定義它們，或透過外掛程式分發它們。以下部分涵蓋所有配置選項。150您也可以手動撰寫 subagent 檔案、透過 CLI 旗標定義它們，或透過外掛程式分發它們。以下部分涵蓋所有配置選項。

151

152<Note>

153 在 Claude Code v2.1.197 及更早版本上，`/agents` 開啟一個互動式精靈，其中包含列出即時 subagents 的 **Running** 標籤和用於建立、編輯和刪除它們的 **Library** 標籤。{/* max-version: 2.1.197 */}

154</Note>

151 155

152<h2 id="configure-subagents">156<h2 id="configure-subagents">

153 配置 subagents157 配置 subagents

154</h2>158</h2>

155 159

156<h3 id="use-the-/agents-command">160Subagent 的檔案位置決定了誰可以使用它，其 frontmatter 決定了它可以做什麼。本節涵蓋 subagent 檔案的位置以及它們支援的每個欄位。

157 使用 /agents 命令

158</h3>

~~159~~

160`/agents` 命令開啟用於管理 subagents 的分頁介面。**Running** 標籤列出即時和最近完成的 subagents，讓您開啟或停止它們。**Library** 標籤讓您：

~~161~~

162* 檢視所有可用的 subagents（內建、使用者、專案和外掛程式）

163* 使用引導式設定或 Claude 生成建立新的 subagents

164* 編輯現有 subagent 配置和工具存取

165* 刪除自訂 subagents

166* 查看當存在重複項時哪些 subagents 處於活動狀態

~~167~~

168這是建立和管理 subagents 的建議方式。對於手動建立或自動化，您也可以直接新增 subagent 檔案。

169 161

170<h3 id="choose-the-subagent-scope">162<h3 id="choose-the-subagent-scope">

171 選擇 subagent 範圍163 選擇 subagent 範圍

172</h3>164</h3>

173 165

174Subagents 是具有 YAML frontmatter 的 Markdown 檔案。根據範圍將它們儲存在不同位置。當多個 subagents 共享相同名稱時，Claude Code 使用來自優先級較高位置的那個。166根據範圍將 subagent 檔案儲存在不同位置。當多個 subagents 共享相同名稱時，Claude Code 使用來自優先級較高位置的那個。

175 167

177| :-------------------- | :-------- | :------- | :---------------------------------------- |169| :-------------------- | :-------- | :------- | :---------------------------------------- |

178| 受管設定 | 組織範圍 | 1（最高） | 透過 [managed settings](/zh-TW/settings) 部署 |170| 受管設定 | 組織範圍 | 1（最高） | 透過 [managed settings](/zh-TW/settings) 部署 |

183 175

184**專案 subagents**（`.claude/agents/`）非常適合特定於程式碼庫的 subagents。將它們簽入版本控制，以便您的團隊可以協作使用和改進它們。176**專案 subagents**（`.claude/agents/`）非常適合特定於程式碼庫的 subagents。將它們簽入版本控制，以便您的團隊可以協作使用和改進它們。

239 231

240**受管 subagents** 由組織管理員部署。將 markdown 檔案放在 [managed settings directory](/zh-TW/settings#settings-files) 內的 `.claude/agents/` 中，使用與專案和使用者 subagents 相同的 frontmatter 格式。受管定義優先於具有相同名稱的專案和使用者 subagents。232**受管 subagents** 由組織管理員部署。將 markdown 檔案放在 [managed settings directory](/zh-TW/settings#settings-files) 內的 `.claude/agents/` 中，使用與專案和使用者 subagents 相同的 frontmatter 格式。受管定義優先於具有相同名稱的專案和使用者 subagents。

241 233

242**外掛程式 subagents** 來自您已安裝的 [plugins](/zh-TW/plugins)。它們與您的自訂 subagents 一起出現在 `/agents` 中。請參閱 [plugin components reference](/zh-TW/plugins-reference#agents) 以了解建立外掛程式 subagents 的詳細資訊。234**外掛程式 subagents** 來自您已安裝的 [plugins](/zh-TW/plugins)。它們與您的自訂 subagents 一起載入，並在 @-mention 類型提前中以其範圍名稱出現。請參閱 [plugin components reference](/zh-TW/plugins-reference#agents) 以了解建立外掛程式 subagents 的詳細資訊。

243 235

244<Note>236<Note>

245 基於安全考慮，外掛程式 subagents 不支援 `hooks`、`mcpServers` 或 `permissionMode` frontmatter 欄位。從外掛程式載入代理時，這些欄位會被忽略。如果您需要它們，請將代理檔案複製到 `.claude/agents/` 或 `~/.claude/agents/`。您也可以在 `settings.json` 或 `settings.local.json` 中的 [`permissions.allow`](/zh-TW/settings#permission-settings) 新增規則，但這些規則適用於整個工作階段，而不僅僅是外掛程式 subagent。237 基於安全考慮，外掛程式 subagents 不支援 `hooks`、`mcpServers` 或 `permissionMode` frontmatter 欄位。從外掛程式載入代理時，這些欄位會被忽略。如果您需要它們，請將代理檔案複製到 `.claude/agents/` 或 `~/.claude/agents/`。您也可以在 `settings.json` 或 `settings.local.json` 中的 [`permissions.allow`](/zh-TW/settings#permission-settings) 新增規則，但這些規則適用於整個工作階段，而不僅僅是外掛程式 subagent。

254Subagent 檔案使用 YAML frontmatter 進行配置，後面跟著 Markdown 中的系統提示：246Subagent 檔案使用 YAML frontmatter 進行配置，後面跟著 Markdown 中的系統提示：

255 247

256<Note>248<Note>

257 Subagents 在工作階段開始時載入。如果您直接在磁碟上新增或編輯 subagent 檔案，請重新啟動您的工作階段以載入它。透過 `/agents` 介面建立的 Subagents 會立即生效，無需重新啟動。249 Claude Code 監視 `~/.claude/agents/` 和 `.claude/agents/`。當您在磁碟上新增或編輯 subagent 檔案，或要求 Claude 為您編寫一個時，Claude Code 會在幾秒內偵測到變更，下次委派會使用更新的定義，無需重新啟動。

250

251 仍有兩種情況需要重新啟動：

252

253 * 監視程式僅涵蓋工作階段開始時存在的目錄，因此在新的 `agents` 目錄中建立範圍的第一個代理檔案後，重新啟動以載入它。

254 * 使用 `--disable-slash-commands` 啟動的工作階段根本不監視這些目錄。

258</Note>255</Note>

259 256

260```markdown theme={null}257```markdown theme={null}

292| `mcpServers` | 否 | [MCP servers](/zh-TW/mcp) 可用於此 subagent。每個條目要麼是參考已配置伺服器的伺服器名稱（例如，`"slack"`），要麼是內聯定義，其中伺服器名稱為鍵，完整 [MCP server config](/zh-TW/mcp#installing-mcp-servers) 為值。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |289| `mcpServers` | 否 | [MCP servers](/zh-TW/mcp) 可用於此 subagent。每個條目要麼是參考已配置伺服器的伺服器名稱（例如，`"slack"`），要麼是內聯定義，其中伺服器名稱為鍵，完整 [MCP server config](/zh-TW/mcp#installing-mcp-servers) 為值。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |

293| `hooks` | 否 | [Lifecycle hooks](#define-hooks-for-subagents) 限定於此 subagent。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |290| `hooks` | 否 | [Lifecycle hooks](#define-hooks-for-subagents) 限定於此 subagent。針對 [plugin subagents](#choose-the-subagent-scope) 被忽略 |

294| `memory` | 否 | [Persistent memory scope](#enable-persistent-memory)：`user`、`project` 或 `local`。啟用跨工作階段學習 |291| `memory` | 否 | [Persistent memory scope](#enable-persistent-memory)：`user`、`project` 或 `local`。啟用跨工作階段學習 |

295| `background` | 否 | 設定為 `true` 以始終將此 subagent 作為 [background task](#run-subagents-in-foreground-or-background) 執行。預設：`false` |292| `background` | 否 | 設定為 `true` 以始終將此 subagent 作為 [background task](#run-subagents-in-foreground-or-background) 執行，即使 Claude 需要其結果。未設定時，Claude 選擇，{/* min-version: 2.1.198 */}自 v2.1.198 起，它預設在背景執行 subagents |

296| `effort` | 否 | 此 subagent 活動時的努力程度。覆蓋工作階段努力程度。預設：從工作階段繼承。選項：`low`、`medium`、`high`、`xhigh`、`max`；可用的層級取決於模型 |293| `effort` | 否 | 此 subagent 活動時的努力程度。覆蓋工作階段努力程度。預設：從工作階段繼承。選項：`low`、`medium`、`high`、`xhigh`、`max`；可用的層級取決於模型 |

297| `isolation` | 否 | 設定為 `worktree` 以在臨時 [git worktree](/zh-TW/worktrees) 中執行 subagent，為其提供儲存庫的隔離副本，預設從您的 [default branch](/zh-TW/worktrees#choose-the-base-branch) 分支，而不是父工作階段的 `HEAD`。如果 subagent 不進行任何更改，worktree 會自動清理 |294| `isolation` | 否 | 設定為 `worktree` 以在臨時 [git worktree](/zh-TW/worktrees) 中執行 subagent，為其提供儲存庫的隔離副本，預設從您的 [default branch](/zh-TW/worktrees#choose-the-base-branch) 分支，而不是父工作階段的 `HEAD`。如果 subagent 不進行任何更改，worktree 會自動清理 |

298| `color` | 否 | Subagent 在任務清單和文字中的顯示顏色。接受 `red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink` 或 `cyan` |295| `color` | 否 | Subagent 在任務清單和文字中的顯示顏色。接受 `red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink` 或 `cyan` |

320 317

321環境變數、每次呼叫的參數和 frontmatter 值會根據您組織的 [`availableModels`](/zh-TW/model-config#restrict-model-selection) 允許清單進行檢查。解析為排除模型的值不會被使用，subagent 會改為在繼承的模型上執行。318環境變數、每次呼叫的參數和 frontmatter 值會根據您組織的 [`availableModels`](/zh-TW/model-config#restrict-model-selection) 允許清單進行檢查。解析為排除模型的值不會被使用，subagent 會改為在繼承的模型上執行。

322 319

320{/* min-version: 2.1.198 */}自 v2.1.198 起，subagents 也繼承主要對話的 [extended thinking](/zh-TW/model-config#extended-thinking) 配置：如果思考在您的工作階段中開啟，它對 subagent 也開啟，如果關閉，它保持關閉。沒有每個 subagent 的思考設定。在 v2.1.198 之前，subagents 執行時禁用擴展思考，無論主要對話的設定如何。

321

323<h3 id="control-subagent-capabilities">322<h3 id="control-subagent-capabilities">

324 控制 subagent 功能323 控制 subagent 功能

325</h3>324</h3>

432Use the Playwright tools to navigate, screenshot, and interact with pages.431Use the Playwright tools to navigate, screenshot, and interact with pages.

433```432```

434 433

435內聯定義使用與 `.mcp.json` 伺服器條目相同的架構（`stdio`、`http`、`sse`、`ws`），由伺服器名稱鍵入。434內聯定義使用與 `.mcp.json` 伺服器條目相同的架構，由伺服器名稱鍵入，並支援 `stdio`、`http`、`sse` 和 `ws` 類型。

436 435

437若要將 MCP 伺服器保持在主要對話之外，並避免其工具描述在那裡消耗上下文，請在此處內聯定義它，而不是在 `.mcp.json` 中。Subagent 獲得工具；父對話不獲得。436若要將 MCP 伺服器保持在主要對話之外，並避免其工具描述在那裡消耗上下文，請在此處內聯定義它，而不是在 `.mcp.json` 中。Subagent 獲得工具；父對話不獲得。

438 437

528 持久記憶提示527 持久記憶提示

529</h5>528</h5>

530 529

531* `project` 是建議的預設範圍。它使 subagent 知識可透過版本控制共享。當 subagent 的知識在所有專案中廣泛適用時使用 `user`，或當知識不應簽入版本控制時使用 `local`。530* `project` 是建議的預設範圍。它使 subagent 知識可透過版本控制共享。

532* 要求 subagent 在開始工作前查閱其記憶："Review this PR, and check your memory for patterns you've seen before."531* 要求 subagent 在開始工作前查閱其記憶："Review this PR, and check your memory for patterns you've seen before."

533* 要求 subagent 在完成任務後更新其記憶："Now that you're done, save what you learned to your memory." 隨著時間的推移，這會建立一個知識庫，使 subagent 更有效。532* 要求 subagent 在完成任務後更新其記憶："Now that you're done, save what you learned to your memory." 隨著時間的推移，這會建立一個知識庫，使 subagent 更有效。

534* 直接在 subagent 的 markdown 檔案中包括記憶說明，以便它主動維護自己的知識庫：533* 直接在 subagent 的 markdown 檔案中包括記憶說明，以便它主動維護自己的知識庫：

729 728

730您的完整訊息仍然會傳送給 Claude，它根據您要求的內容為 subagent 編寫任務提示。@-mention 控制 Claude 呼叫哪個 subagent，而不是它接收什麼提示。729您的完整訊息仍然會傳送給 Claude，它根據您要求的內容為 subagent 編寫任務提示。@-mention 控制 Claude 呼叫哪個 subagent，而不是它接收什麼提示。

731 730

732由啟用的 [plugin](/zh-TW/plugins) 提供的 Subagents 在預輸入中顯示為其限定名稱，例如 `my-plugin:code-reviewer` 或 `my-plugin:review:security`（當 plugin [將 agents 組織到子資料夾](#choose-the-subagent-scope) 時）。名為背景 subagents 目前在工作階段中執行也出現在預輸入中，在名稱旁邊顯示其狀態。您也可以手動輸入提及而不使用選擇器：`@agent-<name>` 用於本地 subagents，或 `@agent-` 後跟外掛程式 subagents 的限定名稱，例如 `@agent-my-plugin:code-reviewer`。731由啟用的 [plugin](/zh-TW/plugins) 提供的 Subagents 在預輸入中顯示為其限定名稱，例如 `my-plugin:code-reviewer` 或 `my-plugin:review:security`（當 plugin [將 agents 組織到子資料夾](#choose-the-subagent-scope) 時）。名為背景 subagents 目前在工作階段中執行也出現在預輸入中，在名稱旁邊顯示其狀態。

732

733您也可以手動輸入提及而不使用選擇器：`@agent-<name>` 用於本地 subagents，或 `@agent-` 後跟外掛程式 subagents 的限定名稱，例如 `@agent-my-plugin:code-reviewer`。

733 734

734**將整個工作階段作為 subagent 執行。** 傳遞 [`--agent <name>`](/zh-TW/cli-reference) 以啟動一個工作階段，其中主執行緒本身採用該 subagent 的系統提示、工具限制和模型：735**將整個工作階段作為 subagent 執行。** 傳遞 [`--agent <name>`](/zh-TW/cli-reference) 以啟動一個工作階段，其中主執行緒本身採用該 subagent 的系統提示、工具限制和模型：

735 736

774* **前景 subagents** 阻止主要對話直到完成。權限提示會在出現時傳遞給您。775* **前景 subagents** 阻止主要對話直到完成。權限提示會在出現時傳遞給您。

775* **背景 subagents** 在您繼續工作時並行執行。{/* min-version: 2.1.186 */}自 v2.1.186 起，當背景 subagent 到達需要權限的工具呼叫時，提示會在您的主要工作階段中出現，並命名要求的 subagent。批准以讓 subagent 繼續，或按 Esc 拒絕該單一工具呼叫而不停止 subagent。在 v2.1.186 之前，背景 subagents 自動拒絕任何會提示的工具呼叫。776* **背景 subagents** 在您繼續工作時並行執行。{/* min-version: 2.1.186 */}自 v2.1.186 起，當背景 subagent 到達需要權限的工具呼叫時，提示會在您的主要工作階段中出現，並命名要求的 subagent。批准以讓 subagent 繼續，或按 Esc 拒絕該單一工具呼叫而不停止 subagent。在 v2.1.186 之前，背景 subagents 自動拒絕任何會提示的工具呼叫。

776 777

777Claude 根據任務決定是否在前景或背景中執行 subagents。您也可以：778{/* min-version: 2.1.198 */}自 v2.1.198 起，subagents 預設在背景中執行。Claude 在需要結果才能繼續時在前景中執行 subagent。預設值改變 subagent 執行的位置，而不是它被允許做什麼：背景 subagents 仍然在您的主要工作階段中出現每個權限提示。在 v2.1.198 之前，Claude 根據任務在前景和背景之間選擇。

778 779

779* 要求 Claude「run this in the background」780您也可以自己引導這個：

781

782* 要求 Claude 在背景或前景中執行任務

780* 按 **Ctrl+B** 將執行中的任務放在背景中783* 按 **Ctrl+B** 將執行中的任務放在背景中

781 784

782若要禁用所有背景任務功能，請將 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 環境變數設定為 `1`。請參閱 [Environment variables](/zh-TW/env-vars)。785若要禁用所有背景任務功能，請將 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 環境變數設定為 `1`。請參閱 [Environment variables](/zh-TW/env-vars)。

783 786

784當 [`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation) 設定為 `1` 時，每個 subagent 產生都在背景中執行，無論 `background` 欄位如何。權限提示來自這些背景 subagents 會在您的主要工作階段中出現，如上所述。787當 [`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation) 設定為 `1` 時，每個 subagent 產生都在背景中執行，frontmatter `background` 欄位沒有效果，因為 fork 模式從 `Agent` 工具中移除 `run_in_background` 參數。`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 優先於 fork 模式，並將 subagent 產生保持在前景中。

788

789<h3 id="api-errors-in-subagents">

790 Subagents 中的 API 錯誤

791</h3>

792

793{/* min-version: 2.1.199 */}自 v2.1.199 起，subagent 的執行因 API 錯誤（例如使用限制或重複的伺服器錯誤）而結束時，會將該失敗報告回 Claude，而不是將錯誤文字作為 subagent 的發現返回。Claude 接收的內容取決於 subagent 執行的位置：

794

795* **前景**：如果速率限制、過載或伺服器錯誤切斷已經產生輸出的 subagent，Agent 工具會返回該部分輸出，並附註 subagent 被切斷且未完成其任務。否則工具呼叫失敗，並顯示 [`Agent terminated early due to an API error`](/zh-TW/errors#agent-terminated-early-due-to-an-api-error)，後跟錯誤詳細資訊。

796* **背景**：subagent 被標記為失敗，Claude 在其結束時接收的訊息命名 API 錯誤並包括 subagent 的最後輸出，所以部分工作不會丟失。

797

798一旦基礎 API 錯誤清除，要求 Claude 重試任務或 [恢復 subagent](#resume-subagents)。

785 799

786<h3 id="common-patterns">800<h3 id="common-patterns">

787 常見模式801 常見模式

852 866

853{/* min-version: 2.1.172 */}自 Claude Code v2.1.172 起，subagent 可以產生自己的 subagents。當委派的任務本身分裂成並行子任務時使用此功能，例如審查者 subagent 為每個發現分派驗證者，所以中間輸出永遠不會到達您的主要對話。只有頂級 subagent 的摘要返回給您。867{/* min-version: 2.1.172 */}自 Claude Code v2.1.172 起，subagent 可以產生自己的 subagents。當委派的任務本身分裂成並行子任務時使用此功能，例如審查者 subagent 為每個發現分派驗證者，所以中間輸出永遠不會到達您的主要對話。只有頂級 subagent 的摘要返回給您。

854 868

855嵌套 subagent 的配置方式與頂級 subagent 相同，並從相同的 [scopes](#choose-the-subagent-scope) 解析。提示輸入下方的 subagent 面板顯示完整樹：每一行顯示後代的 `(+N)` 計數，{/* min-version: 2.1.193 */}自 v2.1.193 起，打開一行會顯示該 subagent 的同級和直接子代，以及返回到 `main` 的路徑。[`/agents`](#use-the-%2Fagents-command) 中的 Running 標籤將執行中的 subagents 列為平面列表。869嵌套 subagent 的配置方式與頂級 subagent 相同，並從相同的 [scopes](#choose-the-subagent-scope) 解析。

870

871提示輸入下方的 subagent 面板顯示完整樹：每一行顯示後代的 `(+N)` 計數，{/* min-version: 2.1.193 */}自 v2.1.193 起，打開一行會顯示該 subagent 的同級和直接子代，以及返回到 `main` 的路徑。

856 872

857深度計算為主要對話下方的 subagent 級別數，無論每個級別是否在 [前景或背景](#run-subagents-in-foreground-or-background) 中執行。深度為五的 subagent 不接收 Agent 工具，無法進一步產生。限制是固定的且不可配置。873深度計算為主要對話下方的 subagent 級別數，無論每個級別是否在 [前景或背景](#run-subagents-in-foreground-or-background) 中執行。深度為五的 subagent 不接收 Agent 工具，無法進一步產生。限制是固定的且不可配置。

858 874

892 908

893恢復的 subagents 保留其完整對話歷史記錄，包括所有先前的工具呼叫、結果和推理。Subagent 從停止的地方精確繼續，而不是從頭開始。909恢復的 subagents 保留其完整對話歷史記錄，包括所有先前的工具呼叫、結果和推理。Subagent 從停止的地方精確繼續，而不是從頭開始。

894 910

895當 subagent 完成時，Claude 接收其代理 ID。內建的 Explore 和 Plan 代理是一次性的，不返回代理 ID，所以它們無法被恢復；當您需要繼續工作時，請使用 `general-purpose` 或自訂 subagent。Claude 使用 `SendMessage` 工具，將代理的 ID 作為 `to` 欄位來恢復它。`SendMessage` 工具始終可用於透過代理 ID 或名稱恢復 subagents。結構化的團隊協議訊息，例如 `shutdown_request` 和 `plan_approval_response`，需要啟用 [agent teams](/zh-TW/agent-teams)。911當 subagent 完成時，Claude 接收其代理 ID。內建的 Explore 和 Plan 代理是一次性的，不返回代理 ID，所以它們無法被恢復；當您需要繼續工作時，請使用 `general-purpose` 或自訂 subagent。

912

913Claude 使用 `SendMessage` 工具，將代理的 ID 或名稱作為 `to` 欄位來恢復它。`SendMessage` 不需要啟用 [agent teams](/zh-TW/agent-teams)；只有結構化的團隊協議訊息，例如 `shutdown_request` 和 `plan_approval_response`，才需要啟用。

896 914

897若要恢復 subagent，請要求 Claude 繼續先前的工作：915若要恢復 subagent，請要求 Claude 繼續先前的工作：

898 916

906 924

907如果停止的 subagent 接收 `SendMessage`，它會自動在背景中恢復，無需新的 `Agent` 呼叫。925如果停止的 subagent 接收 `SendMessage`，它會自動在背景中恢復，無需新的 `Agent` 呼叫。

908 926

927{/* min-version: 2.1.199 */}自 v2.1.199 起，`SendMessage` 檢查名稱是否仍然指向它在對話中較早時到達的同一代理。如果較新的代理已取得該名稱，例如重新產生的背景代理重複使用了它，Claude Code 會拒絕發送，而不是將其傳遞給錯誤的代理，錯誤會報告該名稱現在到達的代理，以便 Claude 可以重新定位。若要在較早的代理仍在執行時到達它，Claude 會透過其產生結果中的代理 ID 來定址它。檢查的範圍是目前對話，並在 `/clear` 時重置。

928

929{/* min-version: 2.1.198 */}自 v2.1.198 起，subagent 將來自啟動它的代理的訊息視為正常任務方向，包括中途任務課程更正，並在其自己的權限設定內對其進行操作。無論誰發送訊息，兩個限制仍然成立：來自任何代理的任何訊息都不計為您對待處理權限提示的批准，任何代理訊息都無法改變 subagent 的權限設定、`CLAUDE.md` 或配置。只有權限系統或您自己的訊息可以授予批准。

930

909您也可以要求 Claude 提供代理 ID，如果您想明確參考它，或在 `~/.claude/projects/{project}/{sessionId}/subagents/` 的文字檔案中找到 ID。每個文字都儲存為 `agent-{agentId}.jsonl`。931您也可以要求 Claude 提供代理 ID，如果您想明確參考它，或在 `~/.claude/projects/{project}/{sessionId}/subagents/` 的文字檔案中找到 ID。每個文字都儲存為 `agent-{agentId}.jsonl`。

910 932

911Subagent 文字獨立於主要對話持續存在：933Subagent 文字獨立於主要對話持續存在：

912 934

913* **主要對話壓縮**：當主要對話壓縮時，subagent 文字不受影響。它們儲存在單獨的檔案中。935* **主要對話壓縮**：當主要對話壓縮時，subagent 文字不受影響。它們儲存在單獨的檔案中。

914* **工作階段持續性**：Subagent 文字在其工作階段內持續存在。您可以透過恢復相同工作階段在重新啟動 Claude Code 後 [恢復 subagent](#resume-subagents)。936* **工作階段持續性**：Subagent 文字在其工作階段內持續存在。您可以透過恢復相同工作階段在重新啟動 Claude Code 後 [恢復 subagent](#resume-subagents)。

915* **自動清理**：文字根據 `cleanupPeriodDays` 設定進行清理（預設：30 天）。937* **自動清理**：文字根據 `cleanupPeriodDays` 設定進行清理，預設為 30 天。

916 938

917<h4 id="auto-compaction">939<h4 id="auto-compaction">

918 自動壓縮940 自動壓縮

973| `x` | 關閉完成的 fork 或停止執行中的 fork |995| `x` | 關閉完成的 fork 或停止執行中的 fork |

974| `Esc` | 將焦點返回到提示輸入 |996| `Esc` | 將焦點返回到提示輸入 |

975 997

998使用 fork 或 subagent 的文字記錄開啟時，後續訊息和 [skills](/zh-TW/skills) 會傳送到該代理，但內建命令仍在您的主要對話中執行。{/* min-version: 2.1.199 */}從 v2.1.199 開始，在該檢視中輸入 `/model` 或 `/fast` 會顯示通知，表示它會變更主要對話的模型或快速模式，而不是檢視的代理，而不是以無聲方式執行。

999

976<h3 id="how-forks-differ-from-named-subagents">1000<h3 id="how-forks-differ-from-named-subagents">

977 Forks 與命名 subagents 的區別1001 Forks 與命名 subagents 的區別

978</h3>1002</h3>

third-party-integrations.md +1 −1

Details

196 196

197* [Claude for Teams 或 Enterprise](/zh-TW/authentication#claude-for-teams-or-enterprise)197* [Claude for Teams 或 Enterprise](/zh-TW/authentication#claude-for-teams-or-enterprise)

198* [Anthropic Console](/zh-TW/authentication#claude-console-authentication)198* [Anthropic Console](/zh-TW/authentication#claude-console-authentication)

199* [Claude 應用程式閘道](/zh-TW/claude-apps-gateway)，一個自託管閘道，在 Amazon Bedrock、Google Vertex AI、Microsoft Foundry 或 Anthropic API 前面添加 IdP 登入199* [Claude 應用程式閘道](/zh-TW/claude-apps-gateway)，一個自託管閘道，在 Amazon Bedrock、Claude Platform on AWS、Google Vertex AI、Microsoft Foundry 或 Anthropic API 前面添加 IdP 登入

200* [Amazon Bedrock](/zh-TW/amazon-bedrock)200* [Amazon Bedrock](/zh-TW/amazon-bedrock)

201* [Claude Platform on AWS](/zh-TW/claude-platform-on-aws)201* [Claude Platform on AWS](/zh-TW/claude-platform-on-aws)

202* [Google Vertex AI](/zh-TW/google-vertex-ai)202* [Google Vertex AI](/zh-TW/google-vertex-ai)

tools-reference.md +20 −12

Details

11若要新增自訂工具，請連接 [MCP server](/zh-TW/mcp)。若要使用可重複使用的提示型工作流程擴展 Claude，請撰寫 [skill](/zh-TW/skills)，它透過現有的 `Skill` 工具執行，而不是新增工具項目。11若要新增自訂工具，請連接 [MCP server](/zh-TW/mcp)。若要使用可重複使用的提示型工作流程擴展 Claude，請撰寫 [skill](/zh-TW/skills)，它透過現有的 `Skill` 工具執行，而不是新增工具項目。

12 12

13| 工具 | 描述 | 需要權限 |13| 工具 | 描述 | 需要權限 |

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

15| `Agent` | 生成一個具有自己 context window 的 [subagent](/zh-TW/sub-agents)，以處理任務。請參閱 [Agent 工具行為](#agent-tool-behavior) | 否 |15| `Agent` | 生成一個具有自己 context window 的 [subagent](/zh-TW/sub-agents)，以處理任務。請參閱 [Agent 工具行為](#agent-tool-behavior) | 否 |

16| `Artifact` | 將 HTML 或 Markdown 檔案發佈為 [artifact](/zh-TW/artifacts)：一個私人的互動式頁面，在 claude.ai 上。在 Team 和 Enterprise 計畫上，您可以在組織內部分享。{/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}需要 Pro、Max、Team 或 Enterprise 計畫和 `/login` 驗證；請參閱 [可用性](/zh-TW/artifacts#availability) | 是 |16| `Artifact` | 將 HTML 或 Markdown 檔案發佈為 [artifact](/zh-TW/artifacts)：一個私人的互動式頁面，在 claude.ai 上。在 Team 和 Enterprise 計畫上，您可以在組織內部分享。{/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}需要 Pro、Max、Team 或 Enterprise 計畫和 `/login` 驗證；請參閱 [可用性](/zh-TW/artifacts#availability) | 是 |

17| `AskUserQuestion` | 提出多選題以收集需求或澄清歧義 | 否 |17| `AskUserQuestion` | 提出多選題以收集需求或澄清歧義。{/* min-version: 2.1.198 */}自 v2.1.198 起，如果您在 60 秒內未回應，對話框會自動關閉：它會提交您已選擇的任何選項，並告訴 Claude 您可能離開了鍵盤，因此 Claude 會根據自己的判斷進行，稍後可以重新提問。最後 20 秒會出現倒數計時。任何按鍵都會保持對話框開啟，報告焦點的終端機上的焦點視窗也會。設定 [`CLAUDE_AFK_TIMEOUT_MS`](/zh-TW/env-vars#variables) 環境變數以變更 Claude Code 等待的時間，或設定為大值如 `86400000`（24 小時）以在您離開時保持問題開啟。此逾時僅適用於 `AskUserQuestion` 的多選題；權限提示（包括計畫批准）在閒置時永遠不會自動解決 | 否 |

18| `Bash` | 在您的環境中執行 shell 命令。請參閱 [Bash 工具行為](#bash-tool-behavior) | 是 |18| `Bash` | 在您的環境中執行 shell 命令。請參閱 [Bash 工具行為](#bash-tool-behavior) | 是 |

19| `CronCreate` | 在目前工作階段內排程定期或一次性提示。任務的範圍限於工作階段，並在 `--resume` 或 `--continue` 時恢復（如果未過期）。請參閱 [排程任務](/zh-TW/scheduled-tasks) | 否 |19| `CronCreate` | 在目前工作階段內排程定期或一次性提示。任務的範圍限於工作階段，並在 `--resume` 或 `--continue` 時恢復（如果未過期）。請參閱 [排程任務](/zh-TW/scheduled-tasks) | 否 |

20| `CronDelete` | 按 ID 取消排程任務 | 否 |20| `CronDelete` | 按 ID 取消排程任務 | 否 |

35| `Read` | 讀取檔案的內容。請參閱 [Read 工具行為](#read-tool-behavior) | 否 |35| `Read` | 讀取檔案的內容。請參閱 [Read 工具行為](#read-tool-behavior) | 否 |

36| `ReadMcpResourceTool` | 按 URI 讀取特定 MCP 資源 | 否 |36| `ReadMcpResourceTool` | 按 URI 讀取特定 MCP 資源 | 否 |

37| `RemoteTrigger` | 在 claude.ai 上建立、更新、執行和列出 [Routines](/zh-TW/routines)。支援 `/schedule` 命令。{/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Routines 位於 claude.ai 上，需要 Pro、Max、Team 或 Enterprise 計畫，因此此工具無法從 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 存取 | 否 |37| `RemoteTrigger` | 在 claude.ai 上建立、更新、執行和列出 [Routines](/zh-TW/routines)。支援 `/schedule` 命令。{/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Routines 位於 claude.ai 上，需要 Pro、Max、Team 或 Enterprise 計畫，因此此工具無法從 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 存取 | 否 |

38| `ReportFindings` | 將程式碼審查結果報告為結構化清單，每個結果包含檔案、摘要和失敗情景，以便 Claude Code 可以呈現它們而不是將其列印為文字。當有效的程式碼審查指示告訴它時，Claude 會呼叫它。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更新版本 | 否 |38| `ReportFindings` | 將程式碼審查結果報告為結構化清單，每個結果包含檔案、摘要和失敗情景，以便 Claude Code 可以呈現它們而不是將其列印為文字。當有效的程式碼審查指示告訴它時，Claude 會呼叫它。{/* min-version: 2.1.196 */}需要 Claude Code v2.1.196 或更新版本。{/* min-version: 2.1.199 */}自 v2.1.199 起，結果也可以攜帶選擇性的 `category` slug，例如 `correctness` 或 `test-coverage`，顯示在呈現清單中的檔案位置旁邊 | 否 |

39| `ScheduleWakeup` | 重新排程 [自主進行的 `/loop`](/zh-TW/scheduled-tasks#let-claude-choose-the-interval) 的下一次迭代。Claude 在每次迭代結束時呼叫此工具，以選擇下一次執行的時間，範圍在一分鐘到一小時之間；您不需要直接呼叫它。待處理的喚醒會出現在 [Stop hook input](/zh-TW/hooks#stop-input) 的 `session_crons` 中。{/* plan-availability: feature=loop-dynamic providers=anthropic */}在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用，其中沒有間隔的 `/loop` 提示會改為按固定時間表執行 | 否 |39| `ScheduleWakeup` | 重新排程 [自主進行的 `/loop`](/zh-TW/scheduled-tasks#let-claude-choose-the-interval) 的下一次迭代。Claude 在每次迭代結束時呼叫此工具，以選擇下一次執行的時間，範圍在一分鐘到一小時之間；您不需要直接呼叫它。待處理的喚醒會出現在 [Stop hook input](/zh-TW/hooks#stop-input) 的 `session_crons` 中。{/* plan-availability: feature=loop-dynamic providers=anthropic */}在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用，其中沒有間隔的 `/loop` 提示會改為按固定時間表執行 | 否 |

40| `SendMessage` | 傳送訊息給 [agent team](/zh-TW/agent-teams) 隊友，或按 agent ID [恢復 subagent](/zh-TW/sub-agents#resume-subagents)。已停止的 subagents 會在背景中自動恢復。結構化的團隊協議訊息需要 agent teams | 否 |40| `SendMessage` | 傳送訊息給 [agent team](/zh-TW/agent-teams) 隊友，或按 agent ID 或名稱 [恢復 subagent](/zh-TW/sub-agents#resume-subagents)。已停止的 subagents 會在背景中自動恢復。結構化的團隊協議訊息需要 agent teams。接收者永遠不會將來自另一個 agent 的訊息視為您的同意或批准。{/* min-version: 2.1.198 */}自 v2.1.198 起，subagent 將來自啟動它的 agent 的訊息視為正常任務指示，而不是對等請求。{/* min-version: 2.1.199 */}自 v2.1.199 起，傳送到現在解析為與對話中較早時間不同的 agent 的名稱會被拒絕而不是傳遞；請參閱 [恢復 subagents](/zh-TW/sub-agents#resume-subagents) | 否 |

41| `SendUserFile` | 將工作階段中的檔案傳送給您，並附上選擇性標題，以便生成的報告、圖表、螢幕擷取畫面或建置的成品可以到達您的裝置，而不是只在文字記錄中提及。{/* min-version: 2.1.196 */}自 v2.1.196 起，選擇性的 `display` 輸入控制呈現方式：`render` 在用戶端中內聯開啟檔案，`attach` 僅顯示下載卡片，未設定時用戶端會根據檔案類型決定。當連接了 [Remote Control](/zh-TW/remote-control) 用戶端或工作階段在受管雲端環境（例如 [Claude Code on the web](/zh-TW/claude-code-on-the-web)）中執行時可用。傳遞透過 Anthropic 託管的基礎設施執行，因此該工具在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用 | 否 |41| `SendUserFile` | 將工作階段中的檔案傳送給您，並附上選擇性標題，以便生成的報告、圖表、螢幕擷取畫面或建置的成品可以到達您的裝置，而不是只在文字記錄中提及。{/* min-version: 2.1.196 */}自 v2.1.196 起，選擇性的 `display` 輸入控制呈現方式：`render` 在用戶端中內聯開啟檔案，`attach` 僅顯示下載卡片，未設定時用戶端會根據檔案類型決定。當連接了 [Remote Control](/zh-TW/remote-control) 用戶端或工作階段在受管雲端環境（例如 [Claude Code on the web](/zh-TW/claude-code-on-the-web)）中執行時可用。傳遞透過 Anthropic 託管的基礎設施執行，因此該工具在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用 | 否 |

42| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}上傳 `ONBOARDING.md` 並傳回隊友可以在 Claude Code 中開啟的分享連結。在撰寫指南後從 `/team-onboarding` 呼叫。適用於 Pro、Max、Team 和 Enterprise 計畫上的 claude.ai 訂閱者 | 是 |42| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}上傳 `ONBOARDING.md` 並傳回隊友可以在 Claude Code 中開啟的分享連結。在撰寫指南後從 `/team-onboarding` 呼叫。適用於 Pro、Max、Team 和 Enterprise 計畫上的 claude.ai 訂閱者 | 是 |

43| `Skill` | 在主對話中執行 [skill](/zh-TW/skills#control-who-invokes-a-skill) | 是 |43| `Skill` | 在主對話中執行 [skill](/zh-TW/skills#control-who-invokes-a-skill) | 是 |

45| `TaskGet` | 檢索特定任務的完整詳細資訊 | 否 |45| `TaskGet` | 檢索特定任務的完整詳細資訊 | 否 |

46| `TaskList` | 列出所有任務及其目前狀態 | 否 |46| `TaskList` | 列出所有任務及其目前狀態 | 否 |

47| `TaskOutput` | （已棄用）檢索背景任務的輸出。建議在任務的輸出檔案路徑上使用 `Read` | 否 |47| `TaskOutput` | （已棄用）檢索背景任務的輸出。建議在任務的輸出檔案路徑上使用 `Read` | 否 |

48| `TaskStop` | 按 ID 終止執行中的背景任務 | 否 |48| `TaskStop` | 按 ID 終止執行中的背景任務。{/* min-version: 2.1.198 */}自 v2.1.198 起，也接受 [agent-team 隊友](/zh-TW/agent-teams) 或按 agent ID 或名稱的具名背景 agent | 否 |

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

50| `TodoWrite` | {/* min-version: 2.1.142 */}管理工作階段任務檢查清單。自 v2.1.142 起預設停用，改用 `TaskCreate`、`TaskGet`、`TaskList` 和 `TaskUpdate`。設定 `CLAUDE_CODE_ENABLE_TASKS=0` 以重新啟用 | 否 |50| `TodoWrite` | {/* min-version: 2.1.142 */}管理工作階段任務檢查清單。自 v2.1.142 起預設停用，改用 `TaskCreate`、`TaskGet`、`TaskList` 和 `TaskUpdate`。設定 `CLAUDE_CODE_ENABLE_TASKS=0` 以重新啟用 | 否 |

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

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

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

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

55| `Workflow` | 執行 [dynamic workflow](/zh-TW/workflows)：一個在背景協調許多 subagents 並傳回一個統一結果的指令碼 | 是 |55| `Workflow` | 執行 [dynamic workflow](/zh-TW/workflows)：一個在背景協調許多 subagents 並傳回一個統一結果的指令碼 | 是 |

91 Agent 工具行為91 Agent 工具行為

92</h2>92</h2>

93 93

94Agent 工具在單獨的 context window 中生成一個 subagent。subagent 自主地完成其任務，然後將單個文字結果傳回父對話。父對話看不到 subagent 的中間工具呼叫或輸出，只看到最終結果。若要限制 subagent 執行的轉數，請在 [subagent 定義](/zh-TW/sub-agents#supported-frontmatter-fields) 中設定 `maxTurns`。94Agent 工具在單獨的 context window 中生成一個 subagent。subagent 自主地完成其任務，然後將單個文字結果傳回父對話。父對話看不到 subagent 的中間工具呼叫或輸出，只看到最終結果。

96若要限制 subagent 執行的轉數，請在 [subagent 定義](/zh-TW/sub-agents#supported-frontmatter-fields) 中設定 `maxTurns`。

95 97

96相同的 Agent 工具也會在啟用 fork 模式時啟動 [forked subagents](/zh-TW/sub-agents#fork-the-current-conversation)。fork 繼承完整的父對話，而不是從頭開始，始終在背景執行，並仍在您的終端中顯示權限提示。本節的其餘部分描述命名的 subagents。98相同的 Agent 工具也會在啟用 fork 模式時啟動 [forked subagents](/zh-TW/sub-agents#fork-the-current-conversation)。fork 繼承完整的父對話，而不是從頭開始，始終在背景執行，並仍在您的終端中顯示權限提示。本節的其餘部分描述命名的 subagents。

97 99

102* **僅 `disallowedTools`**：subagent 獲得除列出的工具外的每個父工具。104* **僅 `disallowedTools`**：subagent 獲得除列出的工具外的每個父工具。

103* **兩者都設定**：`disallowedTools` 優先。同時列在兩者中的工具會被移除。105* **兩者都設定**：`disallowedTools` 優先。同時列在兩者中的工具會被移除。

104 106

105啟動 subagent 本身不會提示權限。subagent 自己的工具呼叫在執行時會根據您的權限規則進行檢查：107啟動 subagent 本身不會提示權限。Claude Code 在執行時會根據您的權限規則檢查 subagent 自己的工具呼叫。

108

109{/* min-version: 2.1.198 */}自 v2.1.198 起，subagents 預設在背景執行；當 Claude 需要結果才能繼續時，會在前景執行一個。

106 110

107* **前景 subagents** 顯示您在主對話中會看到的相同權限提示，在每個工具呼叫發生時。111* **前景 subagents** 顯示您在主對話中會看到的相同權限提示，在每個工具呼叫發生時。

108* **背景 subagents** {/* min-version: 2.1.186 */}自 v2.1.186 起在您的主要工作階段中顯示權限提示。提示會指出哪個 subagent 在要求，按下 Esc 會拒絕該單一工具呼叫，而不會停止 subagent。在 v2.1.186 之前，背景 subagents 會自動拒絕任何否則會提示的工具呼叫，並在沒有該工具的情況下繼續。112* **背景 subagents** {/* min-version: 2.1.186 */}自 v2.1.186 起在您的主要工作階段中顯示權限提示。提示會指出哪個 subagent 在要求，按下 Esc 會拒絕該單一工具呼叫，而不會停止 subagent。在 v2.1.186 之前，背景 subagents 會自動拒絕任何否則會提示的工具呼叫，並在沒有該工具的情況下繼續。

266 PowerShell 工具270 PowerShell 工具

267</h2>271</h2>

268 272

269PowerShell 工具讓 Claude 原生執行 PowerShell 命令。在 Windows 上，這表示命令在 PowerShell 中執行，而不是透過 Git Bash 路由。在沒有 Git Bash 的 Windows 上，該工具會自動啟用。在安裝了 Git Bash 的 Windows 上，該工具正在逐步推出。在 Linux、macOS 和 WSL 上，該工具是選擇加入的。273PowerShell 工具讓 Claude 原生執行 PowerShell 命令。在 Windows 上，這表示命令在 PowerShell 中執行，而不是透過 Git Bash 路由。該工具的可用方式取決於您的平台：

274

275* **沒有 Git Bash 的 Windows**：該工具會自動啟用。

276* **安裝了 Git Bash 的 Windows**：該工具正在逐步推出。

277* **Linux、macOS 和 WSL**：該工具是選擇加入的。

270 278

271<h3 id="enable-the-powershell-tool">279<h3 id="enable-the-powershell-tool">

272 啟用 PowerShell 工具280 啟用 PowerShell 工具

286 294

287在 Windows 上，Claude Code 自動偵測 `pwsh.exe`（PowerShell 7+），並回退到 `powershell.exe`（PowerShell 5.1）。啟用該工具時，Claude 將 PowerShell 視為主要 shell。當安裝了 Git Bash 時，Bash 工具仍可用於 POSIX 指令碼。295在 Windows 上，Claude Code 自動偵測 `pwsh.exe`（PowerShell 7+），並回退到 `powershell.exe`（PowerShell 5.1）。啟用該工具時，Claude 將 PowerShell 視為主要 shell。當安裝了 Git Bash 時，Bash 工具仍可用於 POSIX 指令碼。

288 296

289Claude Code 使用 `-ExecutionPolicy Bypass` 在程序範圍內生成 PowerShell，因此 `.ps1` 指令碼和模組匯入可在預設 Windows 安裝上運作，無需變更機器的原則。程序範圍的略過不會覆蓋群組原則 `MachinePolicy` 或 `UserPolicy`，因此企業鎖定仍然適用。若要改為尊重機器的有效執行原則，請設定 `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1`。297Claude Code 使用 `-ExecutionPolicy Bypass` 在程序範圍內生成 PowerShell，因此 `.ps1` 指令碼和模組匯入可在預設 Windows 安裝上運作，無需變更機器的原則。程序範圍的略過不會覆蓋群組原則 `MachinePolicy` 或 `UserPolicy`，因此企業原則仍然適用。若要改為尊重機器的有效執行原則，請設定 `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1`。

290 298

291<h3 id="shell-selection-in-settings-hooks-and-skills">299<h3 id="shell-selection-in-settings-hooks-and-skills">

292 設定、hooks 和 skills 中的 shell 選擇300 設定、hooks 和 skills 中的 shell 選擇

346 354

347`deny`、`ask` 或 `allow` 中的明確 `WebFetch(domain:...)` 規則優先於預先核准的集合，因此您可以封鎖預先核准的網域或要求提示。355`deny`、`ask` 或 `allow` 中的明確 `WebFetch(domain:...)` 規則優先於預先核准的集合，因此您可以封鎖預先核准的網域或要求提示。

348 356

349WebFetch 設定以 `Claude-User` 開頭的 `User-Agent` 標頭，以及偏好 Markdown 而不是 HTML 的 `Accept` 標頭，以便支援內容協商的伺服器可以直接傳回 Markdown。[Sandbox](/zh-TW/sandboxing) 網路規則是單獨設定的，因此您希望沙箱程序到達的網域仍需要明確的沙箱權限規則。357WebFetch 設定以 `Claude-User` 開頭的 `User-Agent` 標頭，以及偏好 Markdown 而不是 HTML 的 `Accept` 標頭，以便支援內容協商的伺服器可以直接傳回 Markdown。您可以單獨設定 [sandbox](/zh-TW/sandboxing) 網路規則，因此您希望沙箱程序到達的網域仍需要明確的沙箱權限規則。

350 358

351<h2 id="websearch-tool-behavior">359<h2 id="websearch-tool-behavior">

352 WebSearch 工具行為360 WebSearch 工具行為

361WebSearch 權限規則不採用 specifier。`allow` 或 `deny` 中的裸 `WebSearch` 項目是唯一的形式。369WebSearch 權限規則不採用 specifier。`allow` 或 `deny` 中的裸 `WebSearch` 項目是唯一的形式。

362 370

363<Note>371<Note>

364 WebSearch 在 Claude API 和 Microsoft Foundry 上可用。在 Google Cloud Vertex AI 上，它適用於 Claude 4 模型，包括 Opus、Sonnet 和 Haiku。Amazon Bedrock 不公開伺服器端 web search 工具。372 WebSearch 在 Claude API、[Claude Platform on AWS](/zh-TW/claude-platform-on-aws) 和 Microsoft Foundry 上可用。在 Google Cloud Vertex AI 上，它適用於 Claude 4 及更新版本的模型，包括 Opus、Sonnet 和 Haiku。Amazon Bedrock 不公開伺服器端 web search 工具。

365</Note>373</Note>

366 374

367<h2 id="write-tool-behavior">375<h2 id="write-tool-behavior">

worktrees.md +2 −0

Details

36 36

37您也可以在會話期間要求 Claude「在 worktree 中工作」，它將使用 [`EnterWorktree`](/zh-TW/tools-reference) 工具建立一個。進入 worktree 後，Claude 可以透過呼叫 `EnterWorktree` 並指定目標路徑，直接切換到 `.claude/worktrees/` 下的另一個 worktree。前一個 worktree 保持在磁碟上未被觸及。37您也可以在會話期間要求 Claude「在 worktree 中工作」，它將使用 [`EnterWorktree`](/zh-TW/tools-reference) 工具建立一個。進入 worktree 後，Claude 可以透過呼叫 `EnterWorktree` 並指定目標路徑，直接切換到 `.claude/worktrees/` 下的另一個 worktree。前一個 worktree 保持在磁碟上未被觸及。

38 38

39{/* min-version: 2.1.198 */}自 v2.1.198 起，進入或退出 worktree 也會將會話記錄重新定位到該目錄的專案儲存空間，與 [`/cd`](/zh-TW/commands) 的方式相同，因此 `/desktop` 和 `--resume` 之後會在該處找到會話。由 [`WorktreeCreate` hook](#non-git-version-control) 建立的 Worktrees 被排除在外，並將記錄保留在啟動目錄中。

39在第一次在目錄中使用 `--worktree` 之前，請透過在該目錄中執行一次 `claude` 來接受工作區信任對話。如果尚未接受信任，`--worktree` 將以錯誤退出並提示您先在目錄中執行 `claude`。非互動式執行搭配 `-p` 會跳過[信任檢查](/zh-TW/security)，因此 `claude -p --worktree` 會在沒有信任檢查的情況下進行。41在第一次在目錄中使用 `--worktree` 之前，請透過在該目錄中執行一次 `claude` 來接受工作區信任對話。如果尚未接受信任，`--worktree` 將以錯誤退出並提示您先在目錄中執行 `claude`。非互動式執行搭配 `-p` 會跳過[信任檢查](/zh-TW/security)，因此 `claude -p --worktree` 會在沒有信任檢查的情況下進行。

40 42

41<Tip>43<Tip>

Documentation 2026-07-02 23:59 UTC to 2026-07-03 23:00 UTC