Documentation — Spybara

admin-setup.md +2 −0

Details

92 92

93通过 claude.ai 或 Anthropic API 进行身份验证的组织成员也可以在不部署设置的情况下管理模型：[organization model restrictions](/zh-CN/model-config#organization-model-restrictions) 禁用单个模型，[organization default model](/zh-CN/model-config#organization-default-model) 设置新会话启动时使用的模型，[organization effort limits](/zh-CN/model-config#organization-effort-limits) 限制每个角色的工作量级别。这三个控制都需要 Claude Enterprise 计划。模型限制和工作量限制在服务器端强制执行；默认模型是一个起点，用户可以更改，除非组织强制执行。强制执行仅适用于有限的组织集合；请咨询您的 Anthropic 账户团队了解可用性。这些控制都不会到达 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 [Claude Platform on AWS](/zh-CN/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-CN/security)。97有关这些控制防御的威胁模型，请参阅 [Security](/zh-CN/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-CN/env-vars)。178要完全禁用顾问工具，设置 `CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1`。`/advisor` 命令变为不可用，任何配置的 `advisorModel` 都会被忽略。`--advisor` 标志被接受但没有效果；传递它的现有脚本继续工作而不会出现错误。请参阅[环境变量](/zh-CN/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`，因此在格式化它们之前进行保护。有关解释 `usage` 字段的详情，请参阅 [跟踪成本和使用](/zh-CN/agent-sdk/cost-tracking)。341`result` 字段（最终文本输出）仅在 `success` 变体上存在，因此在读取它之前始终检查子类型。所有结果子类型都包含 `total_cost_usd`、`usage`、`num_turns` 和 `session_id`，因此你可以跟踪成本并在错误后恢复。在 Python 中，`total_cost_usd` 和 `usage` 被类型化为可选的，在某些错误路径上可能是 `None`，因此在格式化它们之前进行保护。有关解释 `usage` 字段的详情，请参阅 [跟踪成本和使用](/zh-CN/agent-sdk/cost-tracking)。

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-CN/agent-sdk/typescript#sdkresultmessage)（TypeScript）或 [`ResultMessage`](/zh-CN/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-CN/agent-sdk/typescript#sdkresultmessage)（TypeScript）或 [`ResultMessage`](/zh-CN/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-CN/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，在每个agent轮次之前更新它。如果处理过程中出现问题，您可以立即回滚到最后的安全状态并跳出循环。273此模式仅保留最新的checkpoint UUID，在每个agent轮次之前更新它。如果处理过程中出现问题，您可以立即回滚到最后的安全状态并跳出循环。

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的情况下执行非交互式回滚时，会发生此错误：运行不带`--rewind-files`的裸`claude -p`，或运行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-CN/settings#permission-settings) 的 `ask` 规则。如果询问规则匹配，调用会传递到您的 [`canUseTool` 回调](/zh-CN/agent-sdk/user-input) 以获得确认，即使在 `bypassPermissions` 模式下也是如此。在 `dontAsk` 模式下，匹配的询问规则会被拒绝，因为该模式从不提示。31 检查来自 [settings.json](/zh-CN/settings#permission-settings) 的 `ask` 规则。如果询问规则匹配，调用会传递到您的 [`canUseTool` 回调](/zh-CN/agent-sdk/user-input) 以获得确认，即使在 `bypassPermissions` 模式下也是如此。

33 需要用户交互的工具行为相同：`AskUserQuestion` 和 MCP 工具，其服务器设置 [`_meta["anthropic/requiresUserInteraction"]`](/zh-CN/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-CN/agent-sdk/hooks)。

49本页面重点关注 **允许和拒绝规则** 以及 **权限模式**。对于其他步骤：60本页面重点关注 **允许和拒绝规则** 以及 **权限模式**。对于其他步骤：

50 61

51* **Hooks：** 运行自定义代码以允许、拒绝或修改工具请求。请参阅 [使用 hooks 控制执行](/zh-CN/agent-sdk/hooks)。62* **Hooks：** 运行自定义代码以允许、拒绝或修改工具请求。请参阅 [使用 hooks 控制执行](/zh-CN/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-CN/agent-sdk/hooks)：hooks 在每个其他步骤之前运行，hook 拒绝甚至在 `bypassPermissions` 模式中也适用。81 **自动批准的工具永远不会到达 `canUseTool`。** 在任何早期步骤中批准的工具调用，通过 `acceptEdits` 或 `bypassPermissions`，或通过允许规则，会跳过您的 `canUseTool` 回调，因此您在那里放置的权限检查对该工具被静默绕过。例外是需要用户交互的工具，`AskUserQuestion` 和 MCP 工具标记有 [`_meta["anthropic/requiresUserInteraction"]`](/zh-CN/mcp#require-approval-for-a-specific-tool)，即使允许规则匹配也会到达回调。覆盖范围取决于条目的形式：像 `Read` 或 `mcp__github__get_issue` 这样的裸名称自动批准对该工具的每个调用，而像 `Bash(ls *)` 这样的范围化规则仅自动批准匹配的调用，其他 `Bash` 调用仍然继续进行回调。对于必须在每个工具调用上运行的检查，请使用 [`PreToolUse` hook](/zh-CN/agent-sdk/hooks)：hooks 在每个其他步骤之前运行，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 +36 −20

Details

7> 定义和调用子代理以隔离上下文、并行运行任务，以及在 Claude Agent SDK 应用程序中应用专门的指令。7> 定义和调用子代理以隔离上下文、并行运行任务，以及在 Claude Agent SDK 应用程序中应用专门的指令。

8 8

9子代理是您的主代理可以生成的独立代理实例，用于处理专注的子任务。9子代理是您的主代理可以生成的独立代理实例，用于处理专注的子任务。

~~10使用子代理来隔离专注子任务的上下文、并行运行多个分析，以及应用专门的指令，而不会使主代理的提示词过于复杂。~~10使用子代理来隔离上下文、并行运行多个分析，以及应用专门的指令，而不会增加主代理的提示词。

11 11

12本指南说明如何使用 `agents` 参数在 SDK 中定义和使用子代理。12本指南说明如何使用 `agents` 参数在 SDK 中定义和使用子代理。

13 13

17 17

18您可以通过三种方式创建子代理：18您可以通过三种方式创建子代理：

19 19

~~20* **以编程方式**：在您的 `query()` 选项中使用 `agents` 参数（[TypeScript](/zh-CN/agent-sdk/typescript#agentdefinition)、[Python](/zh-CN/agent-sdk/python#agentdefinition)）~~20* **以编程方式**：在您的 `query()` 选项中使用 `agents` 参数。请参阅 [TypeScript](/zh-CN/agent-sdk/typescript#agentdefinition) 和 [Python](/zh-CN/agent-sdk/python#agentdefinition) 参考文档

~~21* **基于文件系统**：在 `.claude/agents/` 目录中将代理定义为 markdown 文件（请参阅[将子代理定义为文件](/zh-CN/sub-agents)）~~21* **基于文件系统**：在 `.claude/agents/` 目录中将代理定义为 markdown 文件。请参阅[将子代理定义为文件](/zh-CN/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-CN/agent-sdk/python#agentdefinition)。200在 Python SDK 中，多字词字段名称（如 `disallowedTools` 和 `mcpServers`）保持其 camelCase 拼写以匹配线路格式，而不是遵循 Python 的 snake\_case 约定。有关详细信息，请参阅 [`AgentDefinition` 参考](/zh-CN/agent-sdk/python#agentdefinition)。

199 201

202Claude Code v2.1.198 中的两个子代理行为发生了变化：

203

204* 子代理默认在后台运行。省略 [`run_in_background`](/zh-CN/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-CN/sub-agents#spawn-nested-subagents)。208 {/* min-version: 2.1.172 */}自 Claude Code v2.1.172 起，子代理可以生成自己的子代理。位于主代理下方五个级别的子代理无法生成进一步的子代理，无论其是在前台还是后台运行。要防止子代理生成其他子代理，请从其 `tools` 数组中省略 `Agent` 或将其添加到 `disallowedTools`。有关完整的深度规则，请参阅[嵌套子代理](/zh-CN/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 errors in subagents](/zh-CN/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-CN/sub-agents#built-in-subagents) 是一次性的，不返回 `agentId`，因此当您需要恢复时，请使用自定义代理或 `general-purpose`。要以编程方式恢复子代理：440当子代理完成时，Agent 工具结果包含一个包含 `agentId: <id>` 的文本块。内置的 [`Explore` 和 `Plan` 代理](/zh-CN/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-CN/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 +65 −5

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">

38 示例38 示例

39</h2>39</h2>

40 40

41在运行这些示例之前，请按照[快速入门](/zh-CN/agent-sdk/quickstart)安装 Claude Agent SDK。

43每个示例运行到代理完成并产生其最终结果消息为止。如果会话首先达到其轮次限制，该结果消息将具有 `error_max_turns` 子类型。检查 `subtype` 以检测该结束。

45这些示例使用单次 `query()` 调用。在产生 `error_max_turns` 结果后，`query()` 会抛出一个包含 `Reached maximum number of turns` 的错误。每个示例都将其循环包装在 try 块中，以便在发生这种情况时干净地退出。

47有关结果子类型，请参阅[处理结果](/zh-CN/agent-sdk/agent-loop#handle-the-result)。

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

42 监控待办事项变化50 监控待办事项变化

43</h3>51</h3>

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

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

48 56

57 try {

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

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

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

68 }77 }

69 }78 }

70 }79 }

80 } catch (error) {

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

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

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

84 }

71 ```85 ```

72 86

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

88 import asyncio

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

75 91

93 async def main():

94 try:

76 async for message in query(95 async for message in query(

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

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

95 else "❌"114 else "❌"

96 )115 )

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

117 except Exception as error:

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

119 # such as when the max_turns limit is hit.

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

121

122

123 asyncio.run(main())

98 ```124 ```

99</CodeGroup>125</CodeGroup>

100 126

128 }154 }

129 155

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

157 try {

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

132 prompt,159 prompt,

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

142 }169 }

143 }170 }

144 }171 }

172 } catch (error) {

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

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

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

176 }

145 }177 }

146 }178 }

147 179

151 ```183 ```

152 184

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

186 import asyncio

187

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

155 from typing import List, Dict189 from typing import List, Dict

156 190

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

187 221

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

223 try:

189 async for message in query(224 async for message in query(

190 prompt=prompt,225 prompt=prompt,

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

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

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

198 self.display_progress()233 self.display_progress()

234 except Exception as error:

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

236 # such as when the max_turns limit is hit.

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

199 238

200 239

201 # Usage240 # Usage

241 async def main():

202 tracker = TodoTracker()242 tracker = TodoTracker()

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

244

245

246 asyncio.run(main())

204 ```247 ```

205</CodeGroup>248</CodeGroup>

206 249

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"` 以删除 |260| 项目形状：`{ 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 262

220分配的任务 ID 不在 `TaskCreate` 输入中。它在匹配的 `tool_result` 中返回为 `{ task: { id, subject } }`，因此从结果块捕获它以键入您的映射。以下示例显示了对[监控待办事项变化](#monitoring-todo-changes)循环的最小更改。要渲染完整列表，请在流中监视 `TaskList` 工具结果或将 `TaskCreate` 结果和 `TaskUpdate` 输入累积到映射中。263分配的任务 ID 不在 `TaskCreate` 输入中。它在匹配的 `tool_result` 中返回为 `{ task: { id, subject } }`，因此从结果块捕获它以键入您的映射。以下示例显示了对[监控待办事项变化](#monitoring-todo-changes)循环的最小更改。它仅读取 `tool_use` 输入并跳过从 `tool_result` 块捕获 ID。要渲染完整列表，请在流中监视 `TaskList` 工具结果或将 `TaskCreate` 结果和 `TaskUpdate` 输入累积到映射中。

221 264

222流式传输的 `tool_use` 输入是模型发出的原始形状。Claude Code 在执行前修复一些接近但不正确的键名，将 `id` 或 `task_id` 映射到 `taskId`，将 `active_form` 映射到 `activeForm`，但该修复不会反映在流中。防御性地读取 `TaskUpdate` 输入字段，如下面的示例所示，而不是假设规范名称始终存在。265流式传输的 `tool_use` 输入是模型发出的原始形状。Claude Code 在执行前修复一些接近但不正确的键名，将 `id` 或 `task_id` 映射到 `taskId`，将 `active_form` 映射到 `activeForm`，但该修复不会反映在流中。防御性地读取 `TaskUpdate` 输入字段，如下面的示例所示，而不是假设规范名称始终存在。

223 266

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

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

227 270

271 try {

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

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

274 options: { maxTurns: 15 },

230 })) {275 })) {

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

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

246 }291 }

247 }292 }

248 }293 }

294 } catch (error) {

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

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

297 }

249 ```298 ```

250 299

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

252 from claude_agent_sdk import query, AssistantMessage, ToolUseBlock301 import asyncio

253 302

303 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

304

305 async def main():

306 try:

254 async for message in query(307 async for message in query(

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

309 options=ClaudeAgentOptions(max_turns=15),

256 ):310 ):

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

258 continue312 continue

269 )323 )

270 if task_id:324 if task_id:

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

326 except Exception as error:

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

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

329

330

331 asyncio.run(main())

272 ```332 ```

273</CodeGroup>333</CodeGroup>

274 334

agent-sdk/typescript.md +19 −7

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=0` 以禁用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默认为 `300000` 并被限制为该最小值。中止的请求通过正常重试路径进行。556* `CLAUDE_ENABLE_STREAM_WATCHDOG` 与 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：当标头已到达但响应正文停止流式传输时中止请求。监视程序对所有提供商默认启用；设置 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以禁用它。`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`。您的应用程序在其自己的通道上发送的 `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

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-CN/agent-sdk/agent-loop#handle-the-result)。

3792 3798

3793 要改为运行沙箱外的命令，请设置 `failIfUnavailable: false`。3799 要改为运行沙箱外的命令，请设置 `failIfUnavailable: false`。

3794</Note>3800</Note>

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

3929<Warning>3941<Warning>

3930 使用 `dangerouslyDisableSandbox: true` 运行的命令具有完整的系统访问权限。确保您的 `canUseTool` 处理程序仔细验证这些请求。3942 使用 `dangerouslyDisableSandbox: true` 运行的命令具有完整的系统访问权限。确保您的 `canUseTool` 处理程序仔细验证这些请求。

3931 3943

3932 如果 `permissionMode` 设置为 `bypassPermissions` 且 `allowUnsandboxedCommands` 启用，模型可以自主执行沙箱外的命令，无需任何批准提示。此组合实际上允许模型以静默方式逃离沙箱隔离。3944 如果 `permissionMode` 设置为 `bypassPermissions` 且 `allowUnsandboxedCommands` 启用，模型可以自主执行沙箱外的命令，无需任何批准提示（显式的 [`ask` 规则](/zh-CN/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-CN/skills) 会发送给该队友，但内置命令仍在负责人的会话中运行。

180

181队友的模型和快速模式在它生成时是固定的，所以 `/model` 和 `/fast` 只改变负责人的设置。{/* min-version: 2.1.199 */}从 v2.1.199 开始，在查看队友时输入任一命令会显示一个通知，表示更改适用于负责人；较早的版本会将其应用于负责人而没有任何指示。`/effort` 仍然适用于所查看队友的后续轮次，因为队友遵循负责人的[工作量级别](/zh-CN/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* **空闲通知**：当队友完成并停止时，他们会自动通知负责人。从 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-CN/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 +66 −13

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-CN/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-CN/scheduled-tasks) 会话在迭代之间休眠。该行显示其运行计数和倒计时 |132| `✢` | 一个 [`/loop`](/zh-CN/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-CN/terminal-config#get-a-terminal-bell-or-notification)发送通知，当本地后台会话开始需要你的输入、完成或失败时。在计划上运行的会话，例如 [`/loop`](/zh-CN/scheduled-tasks) 会话，仅在需要你的输入时通知。通知使用与 Claude Code 其余部分相同的 [`preferredNotifChannel` 设置](/zh-CN/settings#available-settings)，并使用 `agent_needs_input` 或 `agent_completed` 类型触发 [`Notification` hook](/zh-CN/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-CN/fullscreen)呈现，无论你的 `tui` 设置如何，因为后台会话没有终端滚动历史可追加。使用 `PgUp`、`PgDn` 或鼠标滚轮滚动，按 `Ctrl+O` 进入记录模式。你的终端的原生滚动和 tmux 复制模式仅显示当前视口，与运行任何全屏应用程序时相同。195附加的会话始终以[全屏模式](/zh-CN/fullscreen)呈现，无论你的 `tui` 设置如何，因为后台会话没有终端滚动历史可追加。使用 `PgUp`、`PgDn` 或鼠标滚轮滚动，按 `Ctrl+O` 进入记录模式。你的终端的原生滚动和 tmux 复制模式仅显示当前视口，与运行任何全屏应用程序时相同。

192 196

193在空提示上按 `←` 分离并返回 agent view。如果对话有焦点且不响应 `←`，按 `Ctrl+Z` 立即分离。197在空提示上按 `←` 分离并返回 agent view。从 v2.1.198 开始，这的工作方式与你从 agent view 打开会话或从 shell 用 `claude attach <id>` 运行相同。

198

199`Ctrl+Z` 也分离但返回到你开始的地方：如果你从那里附加则返回 agent view，或如果你运行了 `claude attach` 则返回你的 shell。当对话有焦点且不响应 `←` 时使用 `Ctrl+Z`。

194 200

195`Ctrl+C` 在附加时保持其标准中断行为：它取消运行中的响应或 `!` shell 命令，而不是分离。在空提示上按两次 `Ctrl+C` 分离，与任何会话中的相同。201`Ctrl+C` 在附加时保持其标准中断行为：它取消运行中的响应或 `!` shell 命令，而不是分离。在空提示上按两次 `Ctrl+C` 分离，与任何会话中的相同。

196 202

202 208

203该行即使从没有对话历史的新会话也会被创建，所以 `→` 会返回到它。当该行是唯一的行时，agent view 在它下方显示一个入门提示。209该行即使从没有对话历史的新会话也会被创建，所以 `→` 会返回到它。当该行是唯一的行时，agent view 在它下方显示一个入门提示。

204 210

205你可以在 `/config` 中关闭此快捷键（`leftArrowOpensAgents` 设置）。211你可以在 `/config` 中用 `leftArrowOpensAgents` 设置关闭此快捷键。

206 212

207<h3 id="organize-the-list">213<h3 id="organize-the-list">

208 组织列表214 组织列表

209</h3>215</h3>

210 216

211Agent view 按状态分组会话，需要输入的会话在顶部，`Ready for review` 和 `Needs input` 在 `Working` 和 `Completed` 上方。这些组名不与上面的[状态](#read-session-state)一一对应：当会话有打开的拉取请求时，它移动到 `Ready for review`，`Completed` 收集已完成、失败和已停止的会话。按 `Ctrl+S` 改为按目录分组。你的选择在运行中保存。217Agent view 按状态分组会话，需要输入的会话在顶部，`Ready for review` 和 `Needs input` 在 `Working` 和 `Completed` 上方。这些组名不与上面的[状态](#read-session-state)一一对应：当会话有打开的拉取请求时，它移动到 `Ready for review`，`Completed` 收集已完成、失败和已停止的会话。

218

219按 `Ctrl+S` 改为按目录分组。你的选择在运行中保存。

212 220

213在一个组内：221在一个组内：

214 222

289 297

290一小组命令在 agent view 本身中运行而不是调度：`/exit` 和 `/quit` 关闭 agent view，`/logout` 将你登出，`/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` 提示。

291 306

292将重复任务打包为 [skill](/zh-CN/skills) 让你从 agent view 多次启动相同的工作流而无需重新输入提示。307将重复任务打包为 [skill](/zh-CN/skills) 让你从 agent view 多次启动相同的工作流而无需重新输入提示。

293 308

340claude --bg "investigate the flaky SettingsChangeDetector test"355claude --bg "investigate the flaky SettingsChangeDetector test"

341```356```

342 357

358提示是位置参数，不是 `-p` 值。{/* min-version: 2.1.198 */}从 v2.1.198 开始，将 `--bg` 与 `-p` 或 `--print` 结合会在创建任何会话前被拒绝并显示错误，因为 `--print` 永远不会启动 `claude agents` 附加到的交互式会话。

359

343要运行特定的 subagent 作为会话的主代理，结合 `--bg` 和 `--agent`：360要运行特定的 subagent 作为会话的主代理，结合 `--bg` 和 `--agent`：

344 361

345```bash theme={null}362```bash theme={null}

352claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"369claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"

353```370```

354 371

355后台化后，Claude 打印会话的短 ID 和管理它的命令。当你传递 `--name` 时，名称出现在短 ID 之后：372后台化后，Claude 打印会话的短 ID 和管理它的命令。当托管后台会话的服务尚未运行时，`--bg` 可能首先在此输出上方打印 `Starting background service…`。当你传递 `--name` 时，名称出现在短 ID 之后：

356 373

357```text theme={null}374```text theme={null}

358backgrounded · 7c5dcf5d · flaky-test-fix375backgrounded · 7c5dcf5d · flaky-test-fix

412 429

413[subagent](/zh-CN/sub-agents) 后台会话生成的继承会话的工作目录，所以其文件编辑落在会话的 worktree 中而不是你的工作副本。要给 subagent 其自己的单独 worktree，在其 frontmatter 中设置 [`isolation: worktree`](/zh-CN/sub-agents#supported-frontmatter-fields) 或在生成它时传递 `isolation: "worktree"`。430[subagent](/zh-CN/sub-agents) 后台会话生成的继承会话的工作目录，所以其文件编辑落在会话的 worktree 中而不是你的工作副本。要给 subagent 其自己的单独 worktree，在其 frontmatter 中设置 [`isolation: worktree`](/zh-CN/sub-agents#supported-frontmatter-fields) 或在生成它时传递 `isolation: "worktree"`。

414 431

432从 v2.1.198 开始，隔离其代码更改在 worktree 中的后台会话也会提交、推送其自己的分支，并打开草稿拉取请求而不停止询问。当拉取请求打开时，[`#N` 标签](#pull-request-status) 出现在其行上。它永远不会推送到 `main` 或 `master`，永远不会强制推送或合并，当你告诉它不要打开拉取请求或存储库没有远程时，它会跳过拉取请求。

433

434编辑未自行隔离的检出的会话仍然会在提交或切换分支前询问。这适用于隔离设置为 `"none"` 时、worktree 移动失败时，或会话在已存在的 worktree 内启动时。

435

415<h3 id="set-the-model">436<h3 id="set-the-model">

416 设置模型437 设置模型

417</h3>438</h3>

527 548

528一旦会话完成并未连接地坐了大约一小时，监督进程停止其进程以释放资源。你用 `Ctrl+T` [固定](#organize-the-list)的会话是例外，在空闲时保持其进程运行。无论哪种方式，记录和状态都保留在磁盘上，下次你附加、窥视或回复停止的会话时，监督进程从中断处启动一个新进程。当每个会话都完成且没有终端连接时，监督进程本身退出，下次你需要它时再次启动。549一旦会话完成并未连接地坐了大约一小时，监督进程停止其进程以释放资源。你用 `Ctrl+T` [固定](#organize-the-list)的会话是例外，在空闲时保持其进程运行。无论哪种方式，记录和状态都保留在磁盘上，下次你附加、窥视或回复停止的会话时，监督进程从中断处启动一个新进程。当每个会话都完成且没有终端连接时，监督进程本身退出，下次你需要它时再次启动。

529 550

530后台 shell 命令和动态工作流会话启动的在会话的进程被停止、重新启动或更新时继续运行，包括在 Windows 上。下一个为该会话启动的进程会接管它们，在此期间完成的 shell 命令会报告为已完成及其输出，工作流会从中断处恢复。由 subagent 启动的 shell 命令和运行中的 [monitors](/zh-CN/tools-reference#monitor-tool) 仍然与进程一起停止，删除会话会停止它交付的所有内容。要让后台 shell 命令和工作流也与进程一起停止，设置 [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/zh-CN/env-vars#variables) 环境变量为 `1`。551会话在其进程被停止、重新启动或更新时启动的后台工作会被交付，包括在 Windows 上。为该会话启动的下一个进程会接管这项工作：

552

553* 在此期间完成的后台 shell 命令会报告为已完成及其输出

554* 动态工作流从中断处恢复

555* [后台子代理](/zh-CN/sub-agents#run-subagents-in-foreground-or-background)从其自己的记录恢复

556

557{/* min-version: 2.1.198 */}从 v2.1.198 起，交付涵盖所有三项。在 v2.1.198 之前，它仅涵盖 shell 命令和工作流，因此后台子代理会随进程停止，并在下次唤醒时报告为失败。

558

559其状态仅存在于进程内部的工作会随之停止而不是被交付。那是子代理启动的 shell 命令，恢复的子代理可以再次启动，以及运行中的[监视器](/zh-CN/tools-reference#monitor-tool)，其事件流无法移动到另一个进程。

560

561删除会话会停止它交付的所有内容。要让会话的所有后台工作随进程停止而不是被交付，将 [`CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF`](/zh-CN/env-vars#variables) 环境变量设置为 `1`。

531 562

532如果重新启动的会话回来时仅显示其原始提示，因为 Claude Code 误读了其记录为空，对话记录会被重命名为 `.orphaned-` 后缀而不是删除，所以它保留在你的机器上。563如果重新启动的会话回来时仅显示其原始提示，因为 Claude Code 误读了其记录为空，对话记录会被重命名为 `.orphaned-` 后缀而不是删除，所以它保留在你的机器上。

533 564

556 587

557该命令还会在运行的监督进程版本与你调用的 `claude` 版本不同时发出警告，这发生在监督进程尚未重新启动到新版本的更新之后。警告显示两个版本，并告诉你运行 `claude daemon stop --any` 以获取新版本。当 Claude Code 作为操作系统服务安装时，建议的命令是 `claude daemon stop` 不带该标志。588该命令还会在运行的监督进程版本与你调用的 `claude` 版本不同时发出警告，这发生在监督进程尚未重新启动到新版本的更新之后。警告显示两个版本，并告诉你运行 `claude daemon stop --any` 以获取新版本。当 Claude Code 作为操作系统服务安装时，建议的命令是 `claude daemon stop` 不带该标志。

558 589

590会话完整地保留该版本不匹配：更新会话 `state.json` 的较旧 Claude Code 版本会保留它不识别的字段并保持会话列出。

591

559在 Windows 上，当守护进程的管道密钥文件被锁定或无法读取时，`claude daemon status` 会显示底层文件错误，而不是报告通用连接失败。592在 Windows 上，当守护进程的管道密钥文件被锁定或无法读取时，`claude daemon status` 会显示底层文件错误，而不是报告通用连接失败。

560 593

561<h3 id="turn-off-agent-view">594<h3 id="turn-off-agent-view">

602 635

603睡眠单独不会导致这种情况。会话在睡眠期间被保留，监督进程在唤醒时重新连接到它们。636睡眠单独不会导致这种情况。会话在睡眠期间被保留，监督进程在唤醒时重新连接到它们。

604 637

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

639 会话在启动前失败，并显示 `possibly low memory` 注记

640</h3>

641

642从 v2.1.199 开始，当后台会话的进程在完成启动前退出，且主机内存不足时，该行的状态会命名退出并添加 `possibly low memory — free some up and retry`。早期版本仅显示此失败的原始退出原因。

643

644该注记是一个假设，而不是确认的原因。Claude Code 仅在进程无声退出（未写入错误且未被信号停止）且主机在该时刻报告内存不足时才添加它。当进程在退出前确实写入了错误时，该行显示该错误。

645

646释放机器上的内存，然后附加、窥视或回复该行，监督进程为会话启动一个新进程。当内存保持不足时，监督进程也会[停止空闲会话](#the-supervisor-process)来自行释放资源。

647

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

606 Agent view 说后台服务没有响应649 Agent view 说后台服务没有响应

607</h3>650</h3>

614 657

615新的监督进程重新连接到运行中的会话。没有 `--keep-workers`，该命令也会结束后台会话。`--any` 标志确认你想停止一个按需启动的监督进程，而不是作为已安装的服务启动的，这是默认的。658新的监督进程重新连接到运行中的会话。没有 `--keep-workers`，该命令也会结束后台会话。`--any` 标志确认你想停止一个按需启动的监督进程，而不是作为已安装的服务启动的，这是默认的。

616 659

660一个启动但无法接受连接的监督进程会自行退出并释放其锁，所以下一个 `claude agents` 会启动一个新的，无需此手动停止。上述步骤适用于运行中的监督进程停滞的情况。

661

617在 Windows 上，如果监督进程没有响应停止请求，该命令会打印其进程 ID。用 `taskkill /PID <pid>` 结束该进程以完成恢复。当你传递了 `--keep-workers` 时，后台会话仍然被保留。662在 Windows 上，如果监督进程没有响应停止请求，该命令会打印其进程 ID。用 `taskkill /PID <pid>` 结束该进程以完成恢复。当你传递了 `--keep-workers` 时，后台会话仍然被保留。

618 663

619<h3 id="dispatch-fails-with-could-not-resolve-authentication-method">664<h3 id="dispatch-fails-with-could-not-resolve-authentication-method">

630 675

631参见[错误参考](/zh-CN/errors#could-not-resolve-authentication-method)了解完整的原因和修复列表。676参见[错误参考](/zh-CN/errors#could-not-resolve-authentication-method)了解完整的原因和修复列表。

632 677

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

634 后台会话无法在 macOS 上读取 Desktop、Documents 或 Downloads679 后台会话无法在 macOS 上读取 Desktop、Documents 或 Downloads

635</h3>680</h3>

636 681

638 683

639使用原生安装程序，该条目显示为 Claude Code，授予在更新中持续。使用其他安装方法（如 Homebrew 或 npm），该条目显示二进制路径，在更新后可能需要再次授予。684使用原生安装程序，该条目显示为 Claude Code，授予在更新中持续。使用其他安装方法（如 Homebrew 或 npm），该条目显示二进制路径，在更新后可能需要再次授予。

640 685

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

687 后台会话无法在 macOS 上访问本地网络主机

688</h3>

689

690在 macOS 15 及更高版本上，系统会阻止进程访问你本地网络上的设备，直到你授予本地网络权限。在 v2.1.198 之前，后台会话主机从未请求该权限，所以针对 LAN 地址的命令失败，出现 `connect: no route to host`，即使相同的命令在前台终端中有效。{/* min-version: 2.1.198 */}从 v2.1.198 开始，后台会话中连接到本地网络地址的第一个命令会触发 Claude Code 的 macOS 本地网络权限提示。授予一次，这些命令就能像在前台终端中一样访问 LAN 主机。

691

641<h3 id="a-session-is-slow-to-respond-after-attaching">692<h3 id="a-session-is-slow-to-respond-after-attaching">

642 附加后会话响应缓慢693 附加后会话响应缓慢

643</h3>694</h3>

677Agent view 在研究预览期间发展迅速。如果你使用较旧的 Claude Code 版本，本页上的某些行为可能会有所不同；特别是，`claude agents` 拒绝它尚不支持的标志，出现 `unknown option` 错误。下表列出了何时添加每个标志和行为。728Agent view 在研究预览期间发展迅速。如果你使用较旧的 Claude Code 版本，本页上的某些行为可能会有所不同；特别是，`claude agents` 拒绝它尚不支持的标志，出现 `unknown option` 错误。下表列出了何时添加每个标志和行为。

678 729

679| 版本 | 更改 |730| 版本 | 更改 |

680| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |731| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

732| v2.1.199 | {/* min-version: 2.1.199 */}后台会话的进程在低内存主机上完成启动前退出时，其行状态显示 `possibly low memory — free some up and retry` 而不仅仅是裸退出原因。使用 `←` 或 `/background` 后台会话时将其 `/color` 转移到新行。 |

733| 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` 结合被拒绝并出现错误。 |

681| v2.1.196 | {/* min-version: 2.1.196 */}单次 `←` 按压后台前台会话；早期版本需要两次按压，带有页脚提示和确认。`--dangerously-skip-permissions` 传递给 `claude agents` 显示绕过免责声明而不是被默默丢弃。你从未命名的交互式会话在会话列表和 `claude agents --json` 中携带默认名称，例如 `my-app-3f`。后台 shell 命令和动态工作流在会话的进程被停止、重新启动或更新时存活，包括在 Windows 上；设置 `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` 关闭交付。在重新启动时误读为空的记录被重命名为 `.orphaned-` 后缀而不是删除。 |734| v2.1.196 | {/* min-version: 2.1.196 */}单次 `←` 按压后台前台会话；早期版本需要两次按压，带有页脚提示和确认。`--dangerously-skip-permissions` 传递给 `claude agents` 显示绕过免责声明而不是被默默丢弃。你从未命名的交互式会话在会话列表和 `claude agents --json` 中携带默认名称，例如 `my-app-3f`。后台 shell 命令和动态工作流在会话的进程被停止、重新启动或更新时存活，包括在 Windows 上；设置 `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF=1` 关闭交付。在重新启动时误读为空的记录被重命名为 `.orphaned-` 后缀而不是删除。 |

682| v2.1.195 | {/* min-version: 2.1.195 */}进行中的工作在 Windows 上后台会话时也转移；设置 `CLAUDE_DISABLE_ADOPT=1` 改为停止它。`Completed` 组填充剩余的垂直空间，标题在短终端上压缩。较旧的 Claude Code 版本不再丢弃较新会话的 `state.json` 字段或从 `claude agents` 隐藏这些会话。附加到停止的会话立即切换而不是显示空白屏幕长达五秒。无法接受连接的监督进程自行退出并释放其锁。 |735| v2.1.195 | {/* min-version: 2.1.195 */}进行中的工作在 Windows 上后台会话时也转移；设置 `CLAUDE_DISABLE_ADOPT=1` 改为停止它。`Completed` 组填充剩余的垂直空间，标题在短终端上压缩。较旧的 Claude Code 版本不再丢弃较新会话的 `state.json` 字段或从 `claude agents` 隐藏这些会话。附加到停止的会话立即切换而不是显示空白屏幕长达五秒。无法接受连接的监督进程自行退出并释放其锁。 |

683| v2.1.174 | {/* min-version: 2.1.174 */}后台会话不再从监督进程的启动 shell 继承网关端点变量如 `ANTHROPIC_BASE_URL`；监督进程向预热工作进程提供新的凭证快照，修复虚假的 `Could not resolve authentication method` 错误。 |736| 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-CN/agent-view)：一个屏幕显示每个会话、其状态以及哪些需要您的输入。55* 对于后台会话，`claude agents` 打开 [代理视图](/zh-CN/agent-view)：一个屏幕显示每个会话、其状态以及哪些需要您的输入。

56* 对于当前会话中的子代理，`/agents` 打开一个面板，其中 **Running** 选项卡列出实时子代理，**Library** 选项卡是您 [创建和编辑自定义子代理](/zh-CN/sub-agents#use-the-%2Fagents-command) 的地方。尽管名称相似，这与 `claude agents` 是分开的。56* 对于当前会话中的子代理，命名的后台子代理出现在 @-mention 类型提前中，显示其状态。{/* min-version: 2.1.198 */}从 v2.1.198 开始，`/agents` 不再打开面板；它打印一个通知，指向子代理文件位置。要 [创建和编辑自定义子代理](/zh-CN/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 子系统 for Linux）。14 Chrome 集成适用于 Google Chrome 和 Microsoft Edge。尚不支持 Brave、Arc 或其他基于 Chromium 的浏览器。也不支持 Windows 子系统 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 Plan Mode 中的浏览器工具

95</h3>

97在 [plan mode](/zh-CN/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-CN/claude-apps-gateway#quickstart)开始，它构建一个最小的工作配置并运行它；一旦你有了满意的配置，[部署指南](/zh-CN/claude-apps-gateway-deploy)涵盖了在 Kubernetes、Cloud Run 或你自己的平台上容器化和托管它。9Claude 应用网关部署由一个 YAML 文件配置，按惯例命名为 `gateway.yaml`。该文件定义网关所做的一切：它在哪里监听、开发者如何登录、推理去往何处，以及应用哪些策略和遥测。本页是该文件中每个选项的参考。要编写你的第一个配置，请从[快速入门](/zh-CN/claude-apps-gateway#quickstart)开始，它构建一个最小的工作配置并运行它；一旦你有了满意的配置，[部署指南](/zh-CN/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 协议；有关在 IdP 端注册的内容，请参阅[身份提供者设置](/zh-CN/claude-apps-gateway-deploy#identity-provider-setup)。`oidc` 块将网关连接到你的身份提供者，并决定谁可以登录。它命名发行者和 OAuth 客户端，映射携带电子邮件和组的声明，并按电子邮件域或组限制登录。71`oidc` 块将网关连接到你的身份提供者，并决定谁可以登录。它命名发行者和 OAuth 客户端，映射携带电子邮件和组的声明，并按电子邮件域或组限制登录。

73OpenID Connect (OIDC) 是网关与你的身份提供者一起使用的 SSO 协议；有关在 IdP 端注册的内容，请参阅[身份提供者设置](/zh-CN/claude-apps-gateway-deploy#identity-provider-setup)。

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` 意味着该上游不服务请求的模型，因此列表中的后续上游仍然可以。同一提供者的多个上游必须设置不同的 `name:`。

127

128在 `404` 上故障转移需要网关 v2.1.198 或更高版本。早期版本即使列表中的后续上游服务该模型，也会将第一个 `404` 返回给客户端。

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 端点地区。跨地区推理配置文件跨地理位置（美国、欧盟、亚太）路由，无论你选择哪一个。对于非美国地区或预配吞吐量 ARN，添加一个[`models:`](#models)块，其中包含正确的每上游 ID。 |198| 地区 | `region:` 是 API 端点地区。跨地区推理配置文件跨地理位置（美国、欧盟、亚太）路由，无论你选择哪一个。对于非美国地区或预配吞吐量 ARN，添加一个[`models:`](#models)块，其中包含正确的每上游 ID。 |

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 Platform on AWS 上的 Claude Code](/zh-CN/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-CN/settings#available-settings)：claude.ai MCP 服务器允许列表的仅允许覆盖554* [`allowAllClaudeAiMcps`](/zh-CN/settings#available-settings)：claude.ai MCP 服务器允许列表的仅允许覆盖

512* `sandbox.bwrapPath` 和 `sandbox.socatPath`：[沙箱](/zh-CN/sandboxing)助手二进制文件的文件系统路径555* `sandbox.bwrapPath` 和 `sandbox.socatPath`：[沙箱](/zh-CN/sandboxing)助手二进制文件的文件系统路径

556* [`forceRemoteSettingsRefresh`](/zh-CN/server-managed-settings)：阻止启动直到远程托管设置被新鲜获取，因此 MDM 或文件策略设置它被尊重，即使缺少该键的缓存远程有效负载是最高优先级来源

513 557

514每个其他键，包括 `allowManagedPermissionRulesOnly` 和 `disableBypassPermissionsMode`，来自最高优先级来源。请参阅[设置优先级](/zh-CN/settings#settings-precedence)了解设置页面上的相同规则。558每个其他键，包括 `allowManagedPermissionRulesOnly` 和 `disableBypassPermissionsMode`，来自最高优先级来源。请参阅[设置优先级](/zh-CN/settings#settings-precedence)了解设置页面上的相同规则。

515 559

581| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 未认证设备授权端点上的每 IP 速率限制。为共享出口 IP 或 NAT 后面的大型组织提高。这些限制仅适用于设备授权登录流，不适用于 `/v1/messages` 推理。请参阅[用户代码暴力破解抵抗](/zh-CN/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-CN/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-CN/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-CN/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

721传送在恢复会话之前检查这些要求。如果任何要求未满足，你会看到错误或被提示解决问题。721传送在恢复会话之前检查这些要求。如果任何要求未满足，你会看到错误或被提示解决问题。

722 722

723| 要求 | 详情 |723| 要求 | 详情 |

724| ---------- | ------------------------------------- |724| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

725| 干净的 git 状态 | 你的工作目录必须没有未提交的更改。如果需要，传送会提示你隐藏更改。 |725| 干净的 git 状态 | 你的工作目录必须没有未提交的更改。如果需要，传送会提示你隐藏更改。 |

726| 正确的存储库 | 你必须从同一存储库的检出运行 `--teleport`，而不是从分叉运行。 |726| 正确的存储库 | 你必须从同一存储库的检出运行 `--teleport`，而不是从分叉运行。{/* min-version: 2.1.199 */}从 v2.1.199 开始，Claude Code 接受检出，即使它无法将远程解析为主机名，例如 SSH 主机别名（如 `git@work:owner/repo.git`）或 `insteadOf` 重写的短形式。它首先显示确认提示，仅当远程的所有者和存储库名称与会话的存储库匹配时。 |

727| 分支可用 | 云会话中的分支必须已被推送到远程。传送会自动获取并检出它。 |727| 分支可用 | 云会话中的分支必须已被推送到远程。传送会自动获取并检出它。 |

728| 相同账户 | 你必须认证到云会话中使用的相同 claude.ai 账户。 |728| 相同账户 | 你必须认证到云会话中使用的相同 claude.ai 账户。 |

729 729

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-CN/amazon-bedrock#advanced-credential-configuration)，以便 Claude Code 重新运行您的登录命令并重试，而不是失败。将命令添加到您的 `settings.json`：233如果您的 SSO 凭证在会话中途过期，请配置 [`awsAuthRefresh`](/zh-CN/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-CN/settings#available-settings) 设置在会话期间无效。优先于 [`CLAUDE_AX_SCREEN_READER`](/zh-CN/env-vars) 和 [`axScreenReader`](/zh-CN/settings#available-settings) 设置。需要 Claude Code v2.1.181 或更高版本 | `claude --ax-screen-reader` |68| `--ax-screen-reader` | {/* min-version: 2.1.181 */}渲染屏幕阅读器友好的输出：没有装饰性边框或动画的平面文本。强制使用经典渲染器，因此 [`tui`](/zh-CN/settings#available-settings) 设置在会话期间无效。优先于 [`CLAUDE_AX_SCREEN_READER`](/zh-CN/env-vars) 和 [`axScreenReader`](/zh-CN/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-CN/env-vars)。请参阅 [bare mode](/zh-CN/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |69| `--bare` | 最小模式：跳过 hooks、skills、plugins、MCP 服务器、自动内存和 CLAUDE.md 的自动发现，以便脚本化调用启动更快。Claude 可以访问 Bash、文件读取和文件编辑工具。设置 [`CLAUDE_CODE_SIMPLE`](/zh-CN/env-vars)。请参阅 [bare mode](/zh-CN/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |

69| `--bg`, `--background` | 启动会话作为 [后台代理](/zh-CN/agent-view) 并立即返回。打印会话 ID 和管理命令。与 `--exec` 结合以作为后台作业运行 shell 命令而不是 Claude 会话，或与 `--agent` 结合以运行特定的 subagent | `claude --bg "investigate the flaky test"` |71| `--bg`, `--background` | 启动会话作为 [后台代理](/zh-CN/agent-view) 并立即返回。打印会话 ID 和管理命令。与 `--exec` 结合以作为后台作业运行 shell 命令而不是 Claude 会话，或与 `--agent` 结合以运行特定的 subagent。{/* min-version: 2.1.198 */}不能与 `-p`/`--print` 结合；请参阅 [错误参考](/zh-CN/errors#command-line-errors) | `claude --bg "investigate the flaky test"` |

70| `--channels` | （研究预览）MCP 服务器，其 [channel](/zh-CN/channels) 通知 Claude 应在此会话中侦听。以空格分隔的 `plugin:<name>@<marketplace>` 条目列表。需要 Claude.ai 身份验证 | `claude --channels plugin:my-notifier@my-marketplace` |72| `--channels` | （研究预览）MCP 服务器，其 [channel](/zh-CN/channels) 通知 Claude 应在此会话中侦听。以空格分隔的 `plugin:<name>@<marketplace>` 条目列表。需要 Claude.ai 身份验证 | `claude --channels plugin:my-notifier@my-marketplace` |

100| `--no-session-persistence` | 禁用会话持久化，以便会话不会保存到磁盘且无法恢复。仅打印模式。[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-CN/env-vars) 环境变量在任何模式下都做同样的事情 | `claude -p --no-session-persistence "query"` |102| `--no-session-persistence` | 禁用会话持久化，以便会话不会保存到磁盘且无法恢复。仅打印模式。[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/zh-CN/env-vars) 环境变量在任何模式下都做同样的事情 | `claude -p --no-session-persistence "query"` |

102| `--permission-mode` | 以指定的 [权限模式](/zh-CN/permission-modes) 开始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk` 或 `bypassPermissions`。覆盖设置文件中的 `defaultMode` | `claude --permission-mode plan` |104| `--permission-mode` | 以指定的 [权限模式](/zh-CN/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，提示工具无法批准标记为 [需要用户交互](/zh-CN/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-CN/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-CN/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` 打开管理器以处理 [子代理](/zh-CN/sub-agents)，Claude 可以将侧面任务委派给这些子代理，`/tasks` 列出当前会话后台运行的内容。`/background` 分离整个会话以继续作为 [后台代理](/zh-CN/agent-view) 运行，并释放您的终端。对于跨越代码库的大型更改，`/batch` 将其分解为独立单元，并在其自己的 [worktrees](/zh-CN/worktrees) 中运行每个单元。请参阅 [并行运行代理](/zh-CN/agents) 以了解这些方法如何相关联。25**并行运行工作。** Claude 将侧面任务委派给 [subagents](/zh-CN/sub-agents)，`/tasks` 列出当前会话后台运行的内容。`/background` 分离整个会话以继续作为 [background agent](/zh-CN/agent-view) 运行，并释放您的终端。对于跨越代码库的大型更改，`/batch` 将其分解为独立单元，并在其自己的 [worktree](/zh-CN/worktrees) 中运行每个单元。请参阅 [Run agents in parallel](/zh-CN/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-CN/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍后使用 `--continue` 或 `--resume` 从添加的目录恢复会话 |52| `/add-dir <path>` | 为当前会话期间的文件访问添加工作目录。大多数 `.claude/` 配置[不会从添加的目录中发现](/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)。您可以稍后使用 `--continue` 或 `--resume` 从添加的目录恢复会话 |

53| `/advisor [model\|off]` | {/* min-version: 2.1.98 */}启用或禁用[顾问工具](/zh-CN/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-CN/advisor)，它在任务期间的关键时刻咨询第二个模型以获取指导。接受 `opus`、`sonnet`、`fable`（{/* min-version: 2.1.170 */}v2.1.170+）或完整模型 ID。不带参数时，打开选择器。需要 Claude Code v2.1.98 或更高版本 |

54| `/agents` | 管理 [agent](/zh-CN/sub-agents) 配置 |54| `/agents` | {/* min-version: 2.1.198 */}从 v2.1.198 开始，运行 `/agents` 会打印一个提醒，要求您询问 Claude 创建或管理 [subagents](/zh-CN/sub-agents)，或直接编辑 `.claude/agents/` 或 `~/.claude/agents/`。{/* max-version: 2.1.197 */}在 v2.1.197 及更早版本中，打开用于创建和管理 subagent 配置的交互式界面 |

55| `/autofix-pr [prompt]` | 生成一个[网络版 Claude Code](/zh-CN/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-CN/claude-code-on-the-web) |55| `/autofix-pr [prompt]` | 生成一个[网络版 Claude Code](/zh-CN/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-CN/claude-code-on-the-web) |

56| `/background [prompt]` | 将当前会话分离以作为[后台 agent](/zh-CN/agent-view) 运行并释放此终端。传递一个提示以在分离前发送一条更多指令。使用 `claude agents` 监视会话。别名：`/bg` |56| `/background [prompt]` | 将当前会话分离以作为[后台 agent](/zh-CN/agent-view) 运行并释放此终端。传递一个提示以在分离前发送一条更多指令。使用 `claude agents` 监视会话。别名：`/bg` |

57| `/batch <instruction>` | **[Skill](/zh-CN/skills#bundled-skills).** 在整个代码库中并行编排大规模更改。研究代码库，将工作分解为 5 到 30 个独立单元，并呈现一个计划。获得批准后，在隔离的 [git worktree](/zh-CN/worktrees) 中为每个单元生成一个[后台 subagent](/zh-CN/sub-agents#run-subagents-in-foreground-or-background)。每个 subagent 实现其单元、运行测试并打开一个 pull request。需要一个 git 存储库。示例：`/batch migrate src/ from Solid to React` |57| `/batch <instruction>` | **[Skill](/zh-CN/skills#bundled-skills).** 在整个代码库中并行编排大规模更改。研究代码库，将工作分解为 5 到 30 个独立单元，并呈现一个计划。获得批准后，在隔离的 [git worktree](/zh-CN/worktrees) 中为每个单元生成一个[后台 subagent](/zh-CN/sub-agents#run-subagents-in-foreground-or-background)。每个 subagent 实现其单元、运行测试并打开一个 pull request。需要一个 git 存储库。示例：`/batch migrate src/ from Solid to React` |

69| `/copy [N]` | 将最后一个助手响应复制到剪贴板。传递数字 `N` 以复制第 N 个最新响应：`/copy 2` 复制倒数第二个。当存在代码块时，显示交互式选择器以选择单个块或完整响应。在选择器中按 `w` 将选择内容写入文件而不是剪贴板，这在 SSH 上很有用 |69| `/copy [N]` | 将最后一个助手响应复制到剪贴板。传递数字 `N` 以复制第 N 个最新响应：`/copy 2` 复制倒数第二个。当存在代码块时，显示交互式选择器以选择单个块或完整响应。在选择器中按 `w` 将选择内容写入文件而不是剪贴板，这在 SSH 上很有用 |

71| `/dataviz [request]` | **[Skill](/zh-CN/skills#bundled-skills).** 为图表、图形和仪表板提供设计指导。Claude 为数据选择图表形式，按角色分配颜色，使用捆绑脚本验证调色板的色盲安全性和对比度，并应用标记、交互和可访问性规则。使用品牌中立的占位符调色板，您可以用自己的调色板替换。{/* min-version: 2.1.198 */}需要 Claude Code v2.1.198 或更高版本 |

71| `/debug [description]` | **[Skill](/zh-CN/skills#bundled-skills).** 为当前会话启用调试日志记录并通过读取会话调试日志来排查问题。调试日志默认关闭，除非您使用 `claude --debug` 启动，因此在会话中途运行 `/debug` 会从该点开始捕获日志。可选择性地描述问题以集中分析 |72| `/debug [description]` | **[Skill](/zh-CN/skills#bundled-skills).** 为当前会话启用调试日志记录并通过读取会话调试日志来排查问题。调试日志默认关闭，除非您使用 `claude --debug` 启动，因此在会话中途运行 `/debug` 会从该点开始捕获日志。可选择性地描述问题以集中分析 |

74| `/design-sync [hint]` | **[Skill](/zh-CN/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-CN/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-CN/model-config#adjust-effort-level)。接受 `low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`；可用级别取决于模型，`max` 和 `ultracode` 仅限会话。`ultracode` 是一个 Claude Code 设置，它结合了 `xhigh` 推理和自动[工作流](/zh-CN/workflows#let-claude-decide-with-ultracode)编排。`auto` 重置为模型默认值。不带参数时，打开交互式滑块；使用左右箭头选择级别，按 `Enter` 应用。立即生效，无需等待当前响应完成 |79| `/effort [level\|auto]` | 设置模型[工作量级别](/zh-CN/model-config#adjust-effort-level)。接受 `low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`；可用级别取决于模型，`max` 和 `ultracode` 仅限会话。`ultracode` 是一个 Claude Code 设置，它结合了 `xhigh` 推理和自动[工作流](/zh-CN/workflows#let-claude-decide-with-ultracode)编排。`auto` 重置为模型默认值。不带参数时，打开交互式滑块；使用左右箭头选择级别，按 `Enter` 应用。立即生效，无需等待当前响应完成 |

81| `/fast [on\|off]` | 切换[快速模式](/zh-CN/fast-mode)开启或关闭 |82| `/fast [on\|off]` | 切换[快速模式](/zh-CN/fast-mode)开启或关闭 |

83| `/fewer-permission-prompts` | **[Skill](/zh-CN/skills#bundled-skills).** 扫描您的记录以查找常见的只读 Bash 和 MCP 工具调用，然后向项目 `.claude/settings.json` 添加优先级允许列表以减少权限提示 |84| `/fewer-permission-prompts` | **[Skill](/zh-CN/skills#bundled-skills).** 扫描您的记录以查找常见的只读 Bash 和 MCP 工具调用，然后向项目 `.claude/settings.json` 添加优先级允许列表以减少权限提示 |

84| `/focus` | 切换焦点视图，仅显示您的最后一个提示、带有编辑 diffstats 的单行工具调用摘要和最终响应。选择在会话间保持。仅在[全屏渲染](/zh-CN/fullscreen)中可用 |85| `/focus` | 切换焦点视图，仅显示您的最后一个提示、带有编辑 diffstats 的单行工具调用摘要和最终响应。{/* min-version: 2.1.198 */}从 v2.1.198 开始，工具调用摘要也计算在轮次中启动的 subagents 数量，并将已完成的后台任务通知折叠为单个计数。选择在会话间保持；设置 [`viewMode`](/zh-CN/settings#available-settings) 在设置中以覆盖它。仅在[全屏渲染](/zh-CN/fullscreen)中可用 |

85| `/fork <directive>` | {/* min-version: 2.1.161 */}生成一个[分叉的 subagent](/zh-CN/sub-agents#fork-the-current-conversation)：一个继承完整对话的后台 subagent，在您继续进行时处理该指令。其结果在完成时返回到您的对话。要自己切换到对话的副本，请使用 `/branch`。在 v2.1.161 之前，`/fork` 是 `/branch` 的别名 |86| `/fork <directive>` | {/* min-version: 2.1.161 */}生成一个[分叉的 subagent](/zh-CN/sub-agents#fork-the-current-conversation)：一个继承完整对话的后台 subagent，在您继续进行时处理该指令。其结果在完成时返回到您的对话。要自己切换到对话的副本，请使用 `/branch`。在 v2.1.161 之前，`/fork` 是 `/branch` 的别名 |

87| `/heapdump` | 将 JavaScript 堆快照和内存分解写入 `~/Desktop`，或在 Linux 上没有 Desktop 文件夹的情况下写入您的主目录，以诊断高内存使用情况。请参阅[故障排除](/zh-CN/troubleshooting#high-cpu-or-memory-usage) |88| `/heapdump` | 将 JavaScript 堆快照和内存分解写入 `~/Desktop`，或在 Linux 上没有 Desktop 文件夹的情况下写入您的主目录，以诊断高内存使用情况。请参阅[故障排除](/zh-CN/troubleshooting#high-cpu-or-memory-usage) |

127| `/setup-bedrock` | 通过交互式向导配置 [Amazon Bedrock](/zh-CN/amazon-bedrock) 身份验证、区域和模型固定。仅在设置 `CLAUDE_CODE_USE_BEDROCK=1` 时可见。首次 Bedrock 用户也可以从登录屏幕访问此向导 |128| `/setup-bedrock` | 通过交互式向导配置 [Amazon Bedrock](/zh-CN/amazon-bedrock) 身份验证、区域和模型固定。仅在设置 `CLAUDE_CODE_USE_BEDROCK=1` 时可见。首次 Bedrock 用户也可以从登录屏幕访问此向导 |

128| `/setup-vertex` | 通过交互式向导配置 [Google Vertex AI](/zh-CN/google-vertex-ai) 身份验证、项目、区域和模型固定。仅在设置 `CLAUDE_CODE_USE_VERTEX=1` 时可见。首次 Vertex AI 用户也可以从登录屏幕访问此向导 |129| `/setup-vertex` | 通过交互式向导配置 [Google Vertex AI](/zh-CN/google-vertex-ai) 身份验证、项目、区域和模型固定。仅在设置 `CLAUDE_CODE_USE_VERTEX=1` 时可见。首次 Vertex AI 用户也可以从登录屏幕访问此向导 |

129| `/simplify [target]` | {/* min-version: 2.1.154 */}**[Skill](/zh-CN/skills#bundled-skills).** 审阅更改的代码以查找清理机会并应用修复。四个审阅 [agents](/zh-CN/sub-agents) 并行运行，涵盖现有帮助程序的重用、简化、效率和更改是否处于正确的抽象级别。从 v2.1.154 开始，审阅不寻找正确性错误。使用 `/code-review` 查找错误。在早期版本中，`/simplify` 等同于 `/code-review --fix`。传递路径或 PR 参考以审阅特定目标 |130| `/simplify [target]` | {/* min-version: 2.1.154 */}**[Skill](/zh-CN/skills#bundled-skills).** 审阅更改的代码以查找清理机会并应用修复。四个审阅 [agents](/zh-CN/sub-agents) 并行运行，涵盖现有帮助程序的重用、简化、效率和更改是否处于正确的抽象级别。从 v2.1.154 开始，审阅不寻找正确性错误。使用 `/code-review` 查找错误。在早期版本中，`/simplify` 等同于 `/code-review --fix`。传递路径或 PR 参考以审阅特定目标 |

130| `/skills` | 列出可用的 [skills](/zh-CN/skills)。按 `t` 按令牌计数排序。按 `Space` 以[从 Claude 或 `/` 菜单中隐藏 skill](/zh-CN/skills#override-skill-visibility-from-settings)，然后按 `Enter` 保存 |131| `/skills` | 列出可用的 [skills](/zh-CN/skills)。{/* min-version: 2.1.121 */}从 v2.1.121 开始，输入以按名称过滤列表。按 `t` 按令牌计数排序。按 `Space` 以[从 Claude 或 `/` 菜单中隐藏 skill](/zh-CN/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-CN/model-config#extended-thinking)配置，因此当您的会话启用思考时，它会在启用思考的情况下进行推理，否则保持关闭。思考仅影响摘要的生成方式；您的会话设置之后保持不变。您的指令会发生什么取决于它们的加载方式：

1591 1591

1592| 机制 | 压缩后 |1592| 机制 | 压缩后 |

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

costs.md +3 −3

Details

107* **在任务之间清除**：使用 `/clear` 在切换到不相关的工作时重新开始。陈旧的上下文会在随后的每条消息上浪费令牌。在清除之前使用 `/rename` 以便您稍后可以轻松找到会话，然后使用 `/resume` 返回到它。107* **在任务之间清除**：使用 `/clear` 在切换到不相关的工作时重新开始。陈旧的上下文会在随后的每条消息上浪费令牌。在清除之前使用 `/rename` 以便您稍后可以轻松找到会话，然后使用 `/resume` 返回到它。

108* **添加自定义 compaction 指令**：`/compact Focus on code samples and API usage` 告诉 Claude 在总结期间保留什么。108* **添加自定义 compaction 指令**：`/compact Focus on code samples and API usage` 告诉 Claude 在总结期间保留什么。

109 109

110您还可以在 CLAUDE.md 中自定义 compaction 行为：110您还可以在项目根目录的 CLAUDE.md 文件中自定义 compaction 行为：

111 111

112```markdown theme={null}112```markdown theme={null}

113# Compact instructions113# Compact instructions

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扩展思考默认启用，因为它显著改进了复杂规划和推理任务的性能。思考令牌作为输出令牌计费，默认预算可能是每个请求数万个令牌，具体取决于模型。对于不需要深度推理的更简单任务，您可以通过在 `/effort` 中或在 `/model` 中降低 [effort level](/zh-CN/model-config#adjust-effort-level)、在 `/config` 中禁用思考或在具有[固定思考预算](/zh-CN/model-config#adaptive-reasoning-and-fixed-thinking-budgets)的模型上使用 `MAX_THINKING_TOKENS=8000` 降低预算来降低成本。自适应推理模型忽略非零预算，因此请改用 effort levels。Fable 5 上不提供禁用思考，它始终使用扩展思考。201扩展思考默认启用，因为它显著改进了复杂规划和推理任务的性能。思考令牌作为输出令牌计费，默认预算可能是每个请求数万个令牌，具体取决于模型。对于不需要深度推理的更简单任务，您可以通过在 `/effort` 中或在 `/model` 中降低 [effort level](/zh-CN/model-config#adjust-effort-level)、在 `/config` 中禁用思考或在具有[固定思考预算](/zh-CN/model-config#adaptive-reasoning-and-fixed-thinking-budgets)的模型上通过设置 `MAX_THINKING_TOKENS` [环境变量](/zh-CN/env-vars)（例如 `MAX_THINKING_TOKENS=8000`）来降低预算来降低成本。自适应推理模型忽略非零预算，因此请改用 effort levels。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 查看加载到上下文中的内容14 查看加载到上下文中的内容

15</h2>15</h2>

16 16

17`/context` 命令显示当前会话中占用上下文窗口的所有内容，按类别分解：系统提示、内存文件、skills、MCP 工具和对话消息。首先运行它来确认你的 `CLAUDE.md`、规则或 skill 描述是否存在。17`/context` 命令显示当前会话中占用上下文窗口的所有内容，按类别分解：系统提示、内存文件、skills、自定义子代理及其加载源、MCP 工具和对话消息。首先运行它来确认你的 `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 服务器及其状态 |26| `/mcp` | 连接的 MCP 服务器及其状态 |

28| `/permissions` | 当前生效的已解析允许和拒绝规则 |27| `/permissions` | 当前生效的已解析允许和拒绝规则 |

desktop.md +1 −1

Details

829* **Linux (beta)**：Linux 桌面应用中尚不提供计算机使用。请参阅 [Claude Desktop on Linux](/zh-CN/desktop-linux)。829* **Linux (beta)**：Linux 桌面应用中尚不提供计算机使用。请参阅 [Claude Desktop on Linux](/zh-CN/desktop-linux)。

830* **内联代码建议**：Desktop 不提供自动完成风格的建议。它通过对话提示和显式代码更改工作。830* **内联代码建议**：Desktop 不提供自动完成风格的建议。它通过对话提示和显式代码更改工作。

831* **Agent teams**：并行 Claude Code 会话相互通信在 [CLI](/zh-CN/agent-teams) 中可用，不在 Desktop 中。对于一个会话内的多 agent 工作，使用[动态工作流](/zh-CN/workflows)，它在 Desktop 中运行。831* **Agent teams**：并行 Claude Code 会话相互通信在 [CLI](/zh-CN/agent-teams) 中可用，不在 Desktop 中。对于一个会话内的多 agent 工作，使用[动态工作流](/zh-CN/workflows)，它在 Desktop 中运行。

832* **Terminal-dialog 命令**：在终端中打开交互式面板的内置命令，例如 `/permissions`、`/config`、`/agents` 和 `/doctor`，在 Code 选项卡中不可用，并回复 `isn't available in this environment`。直接编辑[设置文件](/zh-CN/settings)来管理权限规则和配置，或从独立 CLI 运行命令。832* **Terminal-dialog 命令**：在终端中打开交互式面板的内置命令，例如 `/permissions`、`/config` 和 `/doctor`，在 Code 选项卡中不可用，并回复 `isn't available in this environment`。直接编辑[设置文件](/zh-CN/settings)来管理权限规则和配置，或从独立 CLI 运行命令。

833 833

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

835 故障排除835 故障排除

env-vars.md +8 −4

Details

146| `CCR_FORCE_BUNDLE` | 设置为 `1` 以强制 [`claude --remote`](/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) 捆绑并上传您的本地存储库，即使 GitHub 访问可用 |146| `CCR_FORCE_BUNDLE` | 设置为 `1` 以强制 [`claude --remote`](/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) 捆绑并上传您的本地存储库，即使 GitHub 访问可用 |

147| `CLAUDECODE` | 在 Claude Code 生成的子进程中设置为 `1`（Bash 和 PowerShell 工具、tmux 会话、[hook](/zh-CN/hooks) 命令、[状态行](/zh-CN/statusline)命令、stdio [MCP server](/zh-CN/mcp) 子进程）。IDE 扩展也在其集成终端中设置此选项。用于检测脚本何时在 Claude Code 生成的子进程内运行。要检查当前进程是否由工具调用或 hook 直接生成，而不是在 Claude Code 启动的 stdio MCP 服务器内，请改用 `CLAUDE_CODE_CHILD_SESSION` |147| `CLAUDECODE` | 在 Claude Code 生成的子进程中设置为 `1`（Bash 和 PowerShell 工具、tmux 会话、[hook](/zh-CN/hooks) 命令、[状态行](/zh-CN/statusline)命令、stdio [MCP server](/zh-CN/mcp) 子进程）。IDE 扩展也在其集成终端中设置此选项。用于检测脚本何时在 Claude Code 生成的子进程内运行。要检查当前进程是否由工具调用或 hook 直接生成，而不是在 Claude Code 启动的 stdio MCP 服务器内，请改用 `CLAUDE_CODE_CHILD_SESSION` |

148| `CLAUDE_AFK_COUNTDOWN_MS` | 自动继续前屏幕倒计时出现在未回答的 `AskUserQuestion` 对话框上的毫秒数。默认 `20000`（20 秒）。请参阅 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更高版本 |

149| `CLAUDE_AFK_TIMEOUT_MS` | 未回答的 [`AskUserQuestion`](/zh-CN/tools-reference) 对话框自动继续前的空闲时间（以毫秒为单位）。默认 `60000`（60 秒）。要在您离开时保持问题打开，请设置大值如 `86400000`（24 小时）。设置 `0` 不会关闭超时；它会立即关闭对话框。需要 Claude Code v2.1.198 或更高版本 |

148| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 设置为 `1` 以禁用所有内置 [subagent](/zh-CN/sub-agents) 类型，如 Explore 和 Plan。仅适用于非交互模式（`-p` 标志）。对于想要空白状态的 SDK 用户很有用 |150| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 设置为 `1` 以禁用所有内置 [subagent](/zh-CN/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 会被中止，任务被标记为失败，将任何部分结果呈现给父级 |

162| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 设置为 `0` 以从系统提示的开头省略归属块（客户端版本和提示指纹）。禁用它会改善通过 [LLM 网关](/zh-CN/llm-gateway)路由时的 prompt caching 命中率。Anthropic API 缓存不受影响 |164| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 设置为 `0` 以从系统提示的开头省略归属块（客户端版本和提示指纹）。禁用它会改善通过 [LLM 网关](/zh-CN/llm-gateway)路由时的 prompt caching 命中率。Anthropic API 缓存不受影响 |

163| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 设置用于自动压缩计算的上下文容量（以令牌为单位）。默认为模型的上下文窗口，标准模型为 200K，或[扩展上下文](/zh-CN/model-config#extended-context)模型为 1M，除了 Sonnet 5，它有自己的[默认阈值](/zh-CN/model-config#sonnet-5-context-window)。在 1M 模型上使用较低的值（如 `500000`）可将窗口视为 500K 用于压缩目的。该值上限为模型的实际上下文窗口。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 作为此值的百分比应用。设置此变量会将压缩阈值与状态行的 `used_percentage` 解耦，后者始终使用模型的完整上下文窗口 |165| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 设置用于自动压缩计算的上下文容量（以令牌为单位）。默认为模型的上下文窗口，标准模型为 200K，或[扩展上下文](/zh-CN/model-config#extended-context)模型为 1M，除了 Sonnet 5，它有自己的[默认阈值](/zh-CN/model-config#sonnet-5-context-window)。在 1M 模型上使用较低的值（如 `500000`）可将窗口视为 500K 用于压缩目的。该值上限为模型的实际上下文窗口。`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` 作为此值的百分比应用。设置此变量会将压缩阈值与状态行的 `used_percentage` 解耦，后者始终使用模型的完整上下文窗口 |

164| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆盖自动 [IDE 连接](/zh-CN/vs-code)。默认情况下，在支持的 IDE 的集成终端内启动时，Claude Code 会自动连接。设置为 `false` 以防止这种情况。设置为 `true` 以在自动检测失败时强制连接尝试，例如当 tmux 遮挡父终端时。优先于 [`autoConnectIde`](/zh-CN/settings#global-config-settings) 全局配置设置 |166| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆盖自动 [IDE 连接](/zh-CN/vs-code)。默认情况下，在支持的 IDE 的集成终端内启动时，Claude Code 会自动连接。设置为 `false` 以防止这种情况。设置为 `true` 以在自动检测失败时强制连接尝试，例如当 tmux 遮挡父终端时。优先于 [`autoConnectIde`](/zh-CN/settings#global-config-settings) 全局配置设置 |

167| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 在会话具有活跃 [Remote Control](/zh-CN/remote-control) 连接时在 Bash 工具和 [hook 命令](/zh-CN/hooks)子进程中自动设置，并在连接结束时移除。该值是会话的 ID，格式为 `session_`，与出现在会话的 `claude.ai/code` URL 中的标识符相同，因此脚本可以链接回运行它的会话。需要 Claude Code v2.1.199 或更高版本。在[云会话](/zh-CN/claude-code-on-the-web)中，改为读取 `CLAUDE_CODE_REMOTE_SESSION_ID` |

165| `CLAUDE_CODE_CERT_STORE` | TLS 连接的 CA 证书源的逗号分隔列表。`bundled` 是 Claude Code 附带的 Mozilla CA 集。`system` 是操作系统信任存储，仅在具有 `tls.getCACertificates` 的运行时上读取：原生二进制文件或 npm 安装的 Node 22.15 或更高版本。请参阅 [CA 证书存储](/zh-CN/network-config#ca-certificate-store)。默认为 `bundled,system` |168| `CLAUDE_CODE_CERT_STORE` | TLS 连接的 CA 证书源的逗号分隔列表。`bundled` 是 Claude Code 附带的 Mozilla CA 集。`system` 是操作系统信任存储，仅在具有 `tls.getCACertificates` 的运行时上读取：原生二进制文件或 npm 安装的 Node 22.15 或更高版本。请参阅 [CA 证书存储](/zh-CN/network-config#ca-certificate-store)。默认为 `bundled,system` |

166| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 通过 Bash、PowerShell 和 Monitor 工具、[hook](/zh-CN/hooks) 命令和[状态行](/zh-CN/statusline)命令生成的子进程中设置为 `1`。不为 stdio [MCP server](/zh-CN/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` | 在 Claude Code 通过 Bash、PowerShell 和 Monitor 工具、[hook](/zh-CN/hooks) 命令和[状态行](/zh-CN/statusline)命令生成的子进程中设置为 `1`。不为 stdio [MCP server](/zh-CN/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 或更高版本 |

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 上下文窗口](/zh-CN/model-config#extended-context)支持。设置后，1M 模型变体在模型选择器中不可用，[Sonnet 5](/zh-CN/model-config#sonnet-5-context-window) 会话被视为具有 200K 窗口。对于具有合规要求的企业环境很有用 |176| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 设置为 `1` 以禁用[1M 上下文窗口](/zh-CN/model-config#extended-context)支持。设置后，1M 模型变体在模型选择器中不可用，[Sonnet 5](/zh-CN/model-config#sonnet-5-context-window) 会话被视为具有 200K 窗口。对于具有合规要求的企业环境很有用 |

174| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 设置为 `1` 以禁用 Opus 4.6 和 Sonnet 4.6 的[自适应推理](/zh-CN/model-config#adjust-effort-level)并回退到由 `MAX_THINKING_TOKENS` 控制的固定思考预算。从 v2.1.111 开始，对 Fable 5、Sonnet 5 或 Opus 4.7 及更高版本无效，它们始终使用自适应推理 |177| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 设置为 `1` 以禁用 Opus 4.6 和 Sonnet 4.6 的[自适应推理](/zh-CN/model-config#adjust-effort-level)并回退到由 `MAX_THINKING_TOKENS` 控制的固定思考预算。从 v2.1.111 开始，对 Fable 5、Sonnet 5 或 Opus 4.7 及更高版本无效，它们始终使用自适应推理 |

175| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 设置为 `1` 以禁用[顾问工具](/zh-CN/advisor)。`/advisor` 命令和 `--advisor` 标志变为不可用，任何配置的 `advisorModel` 被忽略。需要 Claude Code v2.1.98 或更高版本 |178| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 设置为 `1` 以禁用[顾问工具](/zh-CN/advisor)。`/advisor` 命令变为不可用，任何配置的 `advisorModel` 被忽略，`--advisor` 标志被接受但无效，因此传递它的现有脚本继续工作而不出错。需要 Claude Code v2.1.98 或更高版本 |

176| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 设置为 `1` 以关闭[后台代理和代理视图](/zh-CN/agent-view)：`claude agents`、`--bg`、`/background` 和按需监督员。等同于 [`disableAgentView`](/zh-CN/settings#available-settings) 设置 |179| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 设置为 `1` 以关闭[后台代理和代理视图](/zh-CN/agent-view)：`claude agents`、`--bg`、`/background` 和按需监督员。等同于 [`disableAgentView`](/zh-CN/settings#available-settings) 设置 |

177| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 设置为 `1` 以禁用[全屏渲染](/zh-CN/fullscreen)并使用经典主屏幕渲染器。对话保持在您的终端的原生滚动条中，因此 `Cmd+f` 和 tmux 复制模式可以正常工作。优先于 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/zh-CN/settings#available-settings) 设置。您也可以使用 `/tui default` 切换。不适用于从[代理视图](/zh-CN/agent-view)打开的后台会话，它们始终使用全屏渲染 |180| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 设置为 `1` 以禁用[全屏渲染](/zh-CN/fullscreen)并使用经典主屏幕渲染器。对话保持在您的终端的原生滚动条中，因此 `Cmd+f` 和 tmux 复制模式可以正常工作。优先于 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/zh-CN/settings#available-settings) 设置。您也可以使用 `/tui default` 切换。不适用于从[代理视图](/zh-CN/agent-view)打开的后台会话，它们始终使用全屏渲染 |

178| `CLAUDE_CODE_DISABLE_ARTIFACT` | 设置为 `1` 以禁用[工件](/zh-CN/artifacts)工具，该工具将会话输出发布为 claude.ai 上的私有网页。等同于 [`disableArtifact`](/zh-CN/settings#available-settings) 设置 |181| `CLAUDE_CODE_DISABLE_ARTIFACT` | 设置为 `1` 以禁用[工件](/zh-CN/artifacts)工具，该工具将会话输出发布为 claude.ai 上的私有网页。等同于 [`disableArtifact`](/zh-CN/settings#available-settings) 设置 |

180| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 设置为 `1` 以禁用[自动内存](/zh-CN/memory#auto-memory)。设置为 `0` 以在 `--bare` 模式或 [`autoMemoryEnabled: false`](/zh-CN/settings#available-settings) 会禁用它时强制启用自动内存。禁用后，Claude 不会创建或加载自动内存文件 |183| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 设置为 `1` 以禁用[自动内存](/zh-CN/memory#auto-memory)。设置为 `0` 以在 `--bare` 模式或 [`autoMemoryEnabled: false`](/zh-CN/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 快捷键 |

182| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 设置为 `1` 以在[监督员](/zh-CN/agent-view#the-supervisor-process)停止、重启或更新该会话的进程时停止[后台会话](/zh-CN/agent-view)的运行后台 shell 命令和动态工作流，而不是将它们交给会话的下一个进程。仅影响该交接：使用 `←` 或 [`/background`](/zh-CN/agent-view#from-inside-a-session) 后台处理会话仍会进行中的工作，`CLAUDE_DISABLE_ADOPT` 关闭两者。需要 Claude Code v2.1.196 或更高版本 |185| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 设置为 `1` 以在[监督员](/zh-CN/agent-view#the-supervisor-process)停止、重启或更新该会话的进程时停止[后台会话](/zh-CN/agent-view)的运行后台 shell 命令、动态工作流和（从 v2.1.198 开始）后台 subagents，而不是将它们交给会话的下一个进程。仅影响该交接：使用 `←` 或 [`/background`](/zh-CN/agent-view#from-inside-a-session) 后台处理会话仍会进行中的工作，`CLAUDE_DISABLE_ADOPT` 关闭两者。需要 Claude Code v2.1.196 或更高版本 |

183| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 设置为 `1` 以停止 Claude Code 在操作系统报告内存压力时终止[后台 shell 命令](/zh-CN/interactive-mode#background-bash-commands)。默认情况下，在 macOS 和 Linux 上，Claude Code 在会话空闲 30 分钟且没有转换或 subagent 运行后，在内存压力信号上终止在主会话中启动的后台 shell。Windows 没有内存压力信号，因此此变量对其无效。需要 Claude Code v2.1.193 或更高版本 |186| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 设置为 `1` 以停止 Claude Code 在操作系统报告内存压力时终止[后台 shell 命令](/zh-CN/interactive-mode#background-bash-commands)。默认情况下，在 macOS 和 Linux 上，Claude Code 在会话空闲 30 分钟且没有转换或 subagent 运行后，在内存压力信号上终止在主会话中启动的后台 shell。Windows 没有内存压力信号，因此此变量对其无效。需要 Claude Code v2.1.193 或更高版本 |

184| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 设置为 `1` 以禁用 Claude Code 附带的 [skills](/zh-CN/skills) 和工作流：捆绑的 skills 和工作流被完全删除，而内置的斜杠命令如 `/init` 保持可输入但对模型隐藏。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 skills 不受影响。等同于 [`disableBundledSkills`](/zh-CN/settings#available-settings) 设置；`0` 不会覆盖它 |187| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 设置为 `1` 以禁用 Claude Code 附带的 [skills](/zh-CN/skills) 和工作流：捆绑的 skills 和工作流被完全删除，而内置的斜杠命令如 `/init` 保持可输入但对模型隐藏。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 skills 不受影响。等同于 [`disableBundledSkills`](/zh-CN/settings#available-settings) 设置；`0` 不会覆盖它 |

186| `CLAUDE_CODE_DISABLE_CRON` | 设置为 `1` 以禁用[计划任务](/zh-CN/scheduled-tasks)。`/loop` skill 和 cron 工具变为不可用，任何已计划的任务停止触发，包括已在会话中运行的任务 |189| `CLAUDE_CODE_DISABLE_CRON` | 设置为 `1` 以禁用[计划任务](/zh-CN/scheduled-tasks)。`/loop` skill 和 cron 工具变为不可用，任何已计划的任务停止触发，包括已在会话中运行的任务 |

187| `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` | 设置为 `1` 以禁用内置 [Explore 和 Plan subagents](/zh-CN/sub-agents#built-in-subagents)。Claude 改为使用其搜索工具或通用 subagent 进行探索，[plan mode](/zh-CN/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 或更高版本 |

189| `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-CN/settings#available-settings) 设置。请参阅[会话质量调查](/zh-CN/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-CN/settings#available-settings) 设置。请参阅[会话质量调查](/zh-CN/data-usage#session-quality-surveys) |

231| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆盖 Claude Code 为活动模型假设的上下文窗口大小。从 v2.1.193 开始，对于 Claude Code 不识别为 Claude 模型的模型名称直接应用；对于识别的 Claude 模型，仅当同时设置 `DISABLE_COMPACT` 时才生效。当通过 `ANTHROPIC_BASE_URL` 路由到上下文窗口与其名称的内置大小不匹配的模型时使用 |235| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆盖 Claude Code 为活动模型假设的上下文窗口大小。从 v2.1.193 开始，对于 Claude Code 不识别为 Claude 模型的模型名称直接应用；对于识别的 Claude 模型，仅当同时设置 `DISABLE_COMPACT` 时才生效。当通过 `ANTHROPIC_BASE_URL` 路由到上下文窗口与其名称的内置大小不匹配的模型时使用 |

232| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 设置大多数请求的最大输出令牌数。默认值和上限因模型而异；请参阅[最大输出令牌](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。增加此值会减少在[自动压缩](/zh-CN/costs#reduce-token-usage)触发之前可用的有效上下文窗口 |236| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 设置大多数请求的最大输出令牌数。默认值和上限因模型而异；请参阅[最大输出令牌](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。增加此值会减少在[自动压缩](/zh-CN/costs#reduce-token-usage)触发之前可用的有效上下文窗口 |

233| `CLAUDE_CODE_MAX_RETRIES` | 覆盖重试失败 API 请求的次数（默认值：10）。从 v2.1.186 开始，上限为 15。对于需要等待更长中断的无人值守会话，请改用 `CLAUDE_CODE_RETRY_WATCHDOG` |237| `CLAUDE_CODE_MAX_RETRIES` | 覆盖重试失败 API 请求的次数（默认值：10）。从 v2.1.186 开始，上限为 15；从 v2.1.199 开始，`CLAUDE_CODE_RETRY_WATCHDOG` 提高默认值并移除上限。对于需要等待更长中断的无人值守会话，请改用 `CLAUDE_CODE_RETRY_WATCHDOG` |

235| `CLAUDE_CODE_MAX_TURNS` | 当未传递显式限制时，限制代理转换的数量。等同于传递 [`--max-turns`](/zh-CN/cli-reference#cli-flags)，当两者都设置时优先。不是正整数的值在启动时被拒绝并显示错误，而不是被视为无限制 |239| `CLAUDE_CODE_MAX_TURNS` | 当未传递显式限制时，限制代理转换的数量。等同于传递 [`--max-turns`](/zh-CN/cli-reference#cli-flags)，当两者都设置时优先。不是正整数的值在启动时被拒绝并显示错误，而不是被视为无限制 |

262| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[云会话](/zh-CN/claude-code-on-the-web)中自动设置为当前会话的 ID。读取此值以构造返回会话转录的链接。请参阅[将输出链接回会话](/zh-CN/claude-code-on-the-web#link-output-back-to-the-session) |266| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[云会话](/zh-CN/claude-code-on-the-web)中自动设置为当前会话的 ID。读取此值以构造返回会话转录的链接。请参阅[将输出链接回会话](/zh-CN/claude-code-on-the-web#link-output-back-to-the-session) |

264| `CLAUDE_CODE_RESUME_PROMPT` | 覆盖在恢复在中途结束的会话时注入的继续消息。默认为 `Continue from where you left off.`。长时间运行的代理的生成脚本可以将其设置为更具指导性的启动消息。空字符串使用默认值 |268| `CLAUDE_CODE_RESUME_PROMPT` | 覆盖在恢复在中途结束的会话时注入的继续消息。默认为 `Continue from where you left off.`。长时间运行的代理的生成脚本可以将其设置为更具指导性的启动消息。空字符串使用默认值 |

265| `CLAUDE_CODE_RETRY_WATCHDOG` | 设置为 `1` 用于无人值守会话，如评估工具、CI 作业或远程工作人员。无限期重试 `429` 和 `529` 容量错误，而不是在 `CLAUDE_CODE_MAX_RETRIES` 尝试后失败。监视程序在尝试之间退避最多 5 分钟，或直到限制在响应携带速率限制重置时间时重置，因此命中使用限制的会话会等待剩余窗口。需要 Claude Code v2.1.186 或更高版本 |269| `CLAUDE_CODE_RETRY_WATCHDOG` | 设置为 `1` 用于无人值守会话，如评估工具、CI 作业或远程工作人员。无限期重试 `429` 和 `529` 容量错误，而不是在 `CLAUDE_CODE_MAX_RETRIES` 尝试后失败。监视程序在尝试之间退避最多 5 分钟，或直到限制在响应携带速率限制重置时间时重置，因此命中使用限制的会话会等待剩余窗口。从 v2.1.199 开始，它也提高了其他瞬时错误（如服务器错误、超时和丢弃的连接）的默认重试计数至 300，大约三小时的退避，并在您明确设置该变量时移除 `CLAUDE_CODE_MAX_RETRIES` 的 15 上限。需要 Claude Code v2.1.186 或更高版本 |

266| `CLAUDE_CODE_SAFE_MODE` | 设置为 `1` 以在安全模式下启动：CLAUDE.md、skills、plugins、hooks、MCP 服务器、自定义命令和代理、输出样式、工作流、自定义主题、自定义快捷键、状态行和文件建议命令、LSP 服务器和自动内存不加载，用于排除故障的破损配置。托管设置策略仍然适用，包括策略配置的 hooks、状态行和文件建议命令；托管插件、托管 skills、托管 CLAUDE.md 和策略配置的 MCP 服务器不适用。等同于传递 [`--safe-mode`](/zh-CN/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-CN/cli-reference#cli-flags)。直接生成的子进程继承该变量 |

267| `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` 的运行时扇出不被检测；这是一个深度防御控制 |

268| `CLAUDE_CODE_SCROLL_SPEED` | 在[全屏渲染](/zh-CN/fullscreen#mouse-wheel-scrolling)中设置鼠标滚轮滚动倍数。接受 1 到 20 的值，以及低于 1 的分数值（如 `0.5`）以减慢终端上原生滚动路径中加速的触控板和滚轮滚动。设置为 `3` 以匹配 `vim`（如果您的终端每个刻度线发送一个滚轮事件而不进行放大）。在 JetBrains IDE 终端中被忽略，Claude Code 使用其自己的滚动处理 |272| `CLAUDE_CODE_SCROLL_SPEED` | 在[全屏渲染](/zh-CN/fullscreen#mouse-wheel-scrolling)中设置鼠标滚轮滚动倍数。接受 1 到 20 的值，以及低于 1 的分数值（如 `0.5`）以减慢终端上原生滚动路径中加速的触控板和滚轮滚动。设置为 `3` 以匹配 `vim`（如果您的终端每个刻度线发送一个滚轮事件而不进行放大）。在 JetBrains IDE 终端中被忽略，Claude Code 使用其自己的滚动处理 |

errors.md +159 −22

Details

21将您在终端中看到的消息与下面的部分相匹配。21将您在终端中看到的消息与下面的部分相匹配。

22 22

23| 消息 | 部分 |23| 消息 | 部分 |

~~24| :-------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- |~~24| :-------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------- |

25| `API Error: 500 Internal server error` | [服务器错误](#api-error-500-internal-server-error) |25| `API Error: 500 Internal server error` | [服务器错误](#api-error-500-internal-server-error) |

26| `API Error: Repeated 529 Overloaded errors` | [服务器错误](#api-error-repeated-529-overloaded-errors) |26| `API Error: Repeated 529 Overloaded errors` | [服务器错误](#api-error-repeated-529-overloaded-errors) |

28| `Server error mid-response. The response above may be incomplete.` | [服务器错误](#the-response-above-may-be-incomplete) |

29| `Connection closed mid-response` / `Response stalled mid-stream` | [服务器错误](#the-response-above-may-be-incomplete) |

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

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

30| `Auto mode classifier transcript exceeded context window` | [服务器错误](#auto-mode-cannot-determine-the-safety-of-an-action) |32| `Auto mode classifier transcript exceeded context window` | [服务器错误](#auto-mode-cannot-determine-the-safety-of-an-action) |

33| `Agent terminated early due to an API error` | [服务器错误](#agent-terminated-early-due-to-an-api-error) |

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

32| `Usage credits required for 1M context` | [使用限制](#usage-credits-required-for-1m-context) |35| `Usage credits required for 1M context` | [使用限制](#usage-credits-required-for-1m-context) |

33| `Server is temporarily limiting requests` | [使用限制](#server-is-temporarily-limiting-requests) |36| `Server is temporarily limiting requests` | [使用限制](#server-is-temporarily-limiting-requests) |

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

44| `OAuth token revoked` / `OAuth token has expired` | [身份验证](#oauth-token-revoked-or-expired) |47| `OAuth token revoked` / `OAuth token has expired` | [身份验证](#oauth-token-revoked-or-expired) |

45| `does not meet scope requirement user:profile` | [身份验证](#oauth-scope-requirement) |48| `does not meet scope requirement user:profile` | [身份验证](#oauth-scope-requirement) |

49| `AWS credentials expired or invalid` | [身份验证](#aws-credentials-expired-or-invalid) |

50| `AWS authentication failed` | [身份验证](#aws-authentication-failed) |

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

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

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

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

50| `Prompt is too long` | [请求错误](#prompt-is-too-long) |56| `Prompt is too long` | [请求错误](#prompt-is-too-long) |

51| `Error during compaction: Conversation too long` | [请求错误](#error-during-compaction-conversation-too-long) |57| `Error during compaction: Conversation too long` | [请求错误](#error-during-compaction-conversation-too-long) |

61| `max_tokens must be greater than thinking.budget_tokens` | [请求错误](#thinking-budget-exceeds-output-limit) |67| `max_tokens must be greater than thinking.budget_tokens` | [请求错误](#thinking-budget-exceeds-output-limit) |

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

63| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [请求错误](#usage-policy-refusal) |69| `Claude Code is unable to respond to this request, which appears to violate our Usage Policy` | [请求错误](#usage-policy-refusal) |

70| `--bg and --print conflict` | [命令行错误](#command-line-errors) |

64| 响应质量似乎低于平常 | [响应质量](#responses-seem-lower-quality-than-usual) |71| 响应质量似乎低于平常 | [响应质量](#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 密钥和企业登录重试它们。

79两个故障类别不会重试，因为重试无法成功：

81* {/* min-version: 2.1.199 */}从 v2.1.199 开始，TLS 证书验证失败（例如 TLS 检查代理、缺少 `NODE_EXTRA_CA_CERTS` 包或过期证书）在第一次尝试时失败，因此修复立即出现，而不是在完整重试预算之后。请参阅 [SSL 证书错误](#ssl-certificate-errors)。瞬时 TLS 条件（例如握手超时）仍然会重试。

82* {/* min-version: 2.1.199 */}从 v2.1.199 开始，在 Claude 已经流出可见输出后到达的服务器错误会保留部分响应并附加[不完整响应通知](#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-CN/env-vars) | 10 | 重试次数。{/* min-version: 2.1.186 */}从 v2.1.186 开始上限为 15。降低它以在脚本中更快地显示故障。 |94| [`CLAUDE_CODE_MAX_RETRIES`](/zh-CN/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-CN/env-vars) | 未设置 | 在 CI 作业等无人值守会话中设置为 `1`，以无限期重试 `429` 和 `529` 容量错误，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次尝试后失败。 |95| [`CLAUDE_CODE_RETRY_WATCHDOG`](/zh-CN/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-CN/env-vars) | 600000 | 每个请求的超时时间（毫秒）。为慢速网络或代理提高它。 |96| [`API_TIMEOUT_MS`](/zh-CN/env-vars) | 600000 | 每个请求的超时时间（毫秒）。为慢速网络或代理提高它。 |

81 97

82<h2 id="server-errors">98<h2 id="server-errors">

115API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.131API Error: Repeated 529 Overloaded errors. The API is at capacity — this is usually temporary. Try again in a moment. If it persists, check https://status.claude.com.

116```132```

117 133

118末尾的句子因提供商而异，方式与上面的 500 错误相同。529 不是您的使用限制，也不会计入您的配额。134末尾的句子因提供商而异，方式与上面的 500 错误相同。

135

136529 不是您的使用限制，也不会计入您的配额。

119 137

120**要做什么：**138**要做什么：**

121 139

142* 如果是慢速网络或代理导致的，请按照[自动重试](#automatic-retries)中的说明提高 `API_TIMEOUT_MS`160* 如果是慢速网络或代理导致的，请按照[自动重试](#automatic-retries)中的说明提高 `API_TIMEOUT_MS`

143* 如果超时频繁且您的网络状况良好，请参阅下面的[网络和连接错误](#network-and-connection-errors)161* 如果超时频繁且您的网络状况良好，请参阅下面的[网络和连接错误](#network-and-connection-errors)

144 162

163<h3 id="the-response-above-may-be-incomplete">

164 The response above may be incomplete

165</h3>

166

167流式响应在 Claude 已经产生可见输出后失败。重新发送请求可能会运行相同的工具调用两次，因此 Claude Code 保留已经流出的内容并附加此通知，而不是丢弃轮次。您看到的变体命名了原因：

168

169```text theme={null}

170API Error: Server error mid-response. The response above may be incomplete.

171API Error: Connection closed mid-response. The response above may be incomplete.

172API Error: Response stalled mid-stream. The response above may be incomplete.

173```

174

175* {/* min-version: 2.1.199 */}}`Server error mid-response`：流中途过载或 5xx 服务器错误。此变体需要 Claude Code v2.1.199 或更高版本；在此之前，该情况丢弃了部分输出并将整个轮次报告为错误。

176* `Connection closed mid-response`：连接断开。

177* `Response stalled mid-stream`：流停止发送数据。

178

179**要做什么：**

180

181* 阅读流出的响应。没有任何内容丢失，但最后的句子或工具调用可能缺失。

182* 回复 `continue` 以让 Claude 从停止的地方继续

183* 如果在任何可见输出之前出现相同的错误，Claude Code 会重试请求而不是完成它。请参阅[自动重试](#automatic-retries)。

184

145<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">185<h3 id="auto-mode-cannot-determine-the-safety-of-an-action">

146 Auto mode cannot determine the safety of an action186 Auto mode cannot determine the safety of an action

147</h3>187</h3>

186* 在出现的提示中批准或拒绝该操作226* 在出现的提示中批准或拒绝该操作

187* 运行 `/compact` 以减少对话大小，以便后续操作再次适应分类器窗口227* 运行 `/compact` 以减少对话大小，以便后续操作再次适应分类器窗口

188 228

229<h3 id="agent-terminated-early-due-to-an-api-error">

230 Agent terminated early due to an API error

231</h3>

232

233{/* min-version: 2.1.199 */}[subagent](/zh-CN/sub-agents) 的 API 请求终止失败，例如因为达到了使用限制或服务器错误的重试用尽，所以 subagent 在完成其任务之前停止。此消息需要 Claude Code v2.1.199 或更高版本；在此之前，API 错误文本被返回给 Claude，就像它是 subagent 的结果一样。

234

235```text theme={null}

236Agent terminated early due to an API error: <error detail>

237```

238

239**要做什么：**

240

241* 将冒号后的错误详情与本页上的其他部分相匹配，例如[使用限制](#usage-limits)或[服务器错误](#server-errors)，并按照该部分的步骤操作

242* 一旦底层错误清除，要求 Claude 重试任务或[恢复 subagent](/zh-CN/sub-agents#resume-subagents)

243

244当速率限制、过载或服务器错误中断已经产生输出的前台 subagent 时，Claude 会收到该部分输出标记为不完整，而不是此错误。请参阅 [subagent 中的 API 错误](/zh-CN/sub-agents#api-errors-in-subagents)。

245

189<h2 id="usage-limits">246<h2 id="usage-limits">

190 使用限制247 使用限制

191</h2>248</h2>

193这些错误意味着与您的帐户或计划相关的配额已达到。它们与影响所有人的[服务器错误](#server-errors)不同。250这些错误意味着与您的帐户或计划相关的配额已达到。它们与影响所有人的[服务器错误](#server-errors)不同。

194 251

195<h3 id="you’ve-hit-your-session-limit">252<h3 id="you’ve-hit-your-session-limit">

196 您已达到会话限制253 You've hit your session limit

197</h3>254</h3>

198 255

199订阅计划包括滚动使用额度。当它用完时，您会看到以下消息之一：256订阅计划包括滚动使用额度。当它用完时，您会看到以下消息之一：

216要在达到限制之前监视您的剩余额度，请将 `rate_limits` 字段添加到[自定义状态行](/zh-CN/statusline#rate-limit-usage)，或在桌面应用中单击模型选择器旁边的[使用环](/zh-CN/desktop#check-usage)。273要在达到限制之前监视您的剩余额度，请将 `rate_limits` 字段添加到[自定义状态行](/zh-CN/statusline#rate-limit-usage)，或在桌面应用中单击模型选择器旁边的[使用环](/zh-CN/desktop#check-usage)。

217 274

218<h3 id="usage-credits-required-for-1m-context">275<h3 id="usage-credits-required-for-1m-context">

219 1M 上下文所需的使用信用276 Usage credits required for 1M context

220</h3>277</h3>

221 278

222所选模型使用 1M 令牌扩展上下文窗口，而您的计划仅通过使用信用包含它。279所选模型使用 1M 令牌扩展上下文窗口，而您的计划仅通过使用信用包含它。

237* 要从模型选择器中完全删除 1M 变体，请设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/zh-CN/env-vars)294* 要从模型选择器中完全删除 1M 变体，请设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/zh-CN/env-vars)

238 295

239<h3 id="server-is-temporarily-limiting-requests">296<h3 id="server-is-temporarily-limiting-requests">

240 服务器暂时限制请求297 Server is temporarily limiting requests

241</h3>298</h3>

242 299

243API 应用了与您的计划配额无关的短期限流。300API 应用了与您的计划配额无关的短期限流。

246API Error: Server is temporarily limiting requests (not your usage limit)303API Error: Server is temporarily limiting requests (not your usage limit)

247```304```

248 305

249这在显示之前会[自动重试](#automatic-retries)。306Claude Code 通过缺少真实限制响应携带的统一配额标头来区分这些。{/* min-version: 2.1.199 */}从 v2.1.199 开始，这会在显示之前[自动重试](#automatic-retries)，无论您如何进行身份验证。在早期版本上，使用 claude.ai 订阅登录的会话在第一次出现时失败轮次；仅 API 密钥和企业登录重试它。

250 307

251**要做什么：**308**要做什么：**

252 309

254* 如果持续存在，请检查 [status.claude.com](https://status.claude.com)311* 如果持续存在，请检查 [status.claude.com](https://status.claude.com)

255 312

256<h3 id="request-rejected-429">313<h3 id="request-rejected-429">

257 请求被拒绝 (429)314 Request rejected (429)

258</h3>315</h3>

259 316

260您已达到为您的 API 密钥、Amazon Bedrock 项目或 Google Vertex AI 项目配置的速率限制。317您已达到为您的 API 密钥、Amazon Bedrock 项目或 Google Vertex AI 项目配置的速率限制。

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

264```321```

265 322

266尾部句子命名了检查服务健康的位置，并因提供商而异。Bedrock、Vertex AI 和 Foundry 配置命名该提供商的服务状态，而不是 Anthropic 状态页面。自定义 `ANTHROPIC_BASE_URL` 命名网关主机。323末尾的句子命名了检查服务健康的位置，并因提供商而异。Bedrock、Vertex AI 和 Foundry 配置命名该提供商的服务状态，而不是 Anthropic 状态页面。自定义 `ANTHROPIC_BASE_URL` 命名网关主机。

267 324

268**要做什么：**325**要做什么：**

269 326

273* 降低并发：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/zh-CN/env-vars)，避免运行许多并行子代理，或使用 `/model` 切换到较小的模型以进行高容量脚本运行330* 降低并发：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/zh-CN/env-vars)，避免运行许多并行子代理，或使用 `/model` 切换到较小的模型以进行高容量脚本运行

274 331

275<h3 id="credit-balance-is-too-low">332<h3 id="credit-balance-is-too-low">

276 信用余额过低333 Credit balance is too low

277</h3>334</h3>

278 335

279您的 Console 组织已用完预付信用。336您的 Console 组织已用完预付信用。

373 Your organization has disabled API key authentication430 Your organization has disabled API key authentication

374</h3>431</h3>

375 432

433{/* min-version: 2.1.169 */}}

376您的 Console 组织的管理员已关闭 API 密钥身份验证，因此 API 拒绝了 Claude Code 正在发送的密钥。`·` 之后的恢复提示因密钥的来源而异：434您的 Console 组织的管理员已关闭 API 密钥身份验证，因此 API 拒绝了 Claude Code 正在发送的密钥。`·` 之后的恢复提示因密钥的来源而异：

377 435

378```text theme={null}436```text theme={null}

402Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access460Your organization has disabled Claude subscription access for Claude Code · Use an Anthropic API key instead, or ask your admin to enable access

403```461```

404 462

405这是一个服务器端组织设置，因此无法从本地设置、环境变量或 CLI 标志覆盖。Agent SDK 和 `-p` 非交互模式将其显示为 `oauth_org_not_allowed` 错误代码。463这是一个服务器端组织设置，因此无法从本地设置、环境变量或 CLI 标志覆盖。

464

465Agent SDK 和 `-p` 非交互模式将其显示为 `oauth_org_not_allowed` 错误代码。

406 466

407**要做什么：**467**要做什么：**

408 468

477 537

478* 运行 `/login` 以使用当前范围铸造新令牌。您不需要先登出。538* 运行 `/login` 以使用当前范围铸造新令牌。您不需要先登出。

479 539

540<h3 id="aws-credentials-expired-or-invalid">

541 AWS credentials expired or invalid

542</h3>

543

544{/* min-version: 2.1.198 */}}此消息需要 Claude Code v2.1.198 或更高版本，仅当在您的设置文件中设置了 [`awsAuthRefresh`](/zh-CN/amazon-bedrock#advanced-credential-configuration) 时才出现。您的 AWS 会话令牌过期或被拒绝，Claude Code 已经运行的自动刷新没有产生 API 接受的凭证。它出现在来自 [Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 或 [Mantle 端点](/zh-CN/amazon-bedrock#use-the-mantle-endpoint) 的 401，这是这些提供商报告过期安全令牌的方式。

545

546中间的操作提示命名了您的设置中的 `awsAuthRefresh` 命令，因此它会有所不同。稳定的部分是前导 `AWS credentials expired or invalid`：

547

548```text theme={null}

549AWS 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 ...

550```

551

552如果未配置 `awsAuthRefresh`，相同的 401 会显示通用 `Please run /login` 消息，该消息无法刷新 AWS 凭证。

553

554**要做什么：**

555

556* 在另一个终端中运行消息中命名的 `awsAuthRefresh` 命令（例如 `aws sso login --profile myprofile`）并完成浏览器登录，然后重试

557* 在交互式会话中，运行 `/login`，选择 **3rd-party platform**，然后在 **Using 3rd-party platforms** 下选择 **Claude Platform on AWS · refresh credentials** 以运行相同的命令而无需重新启动 Claude Code。有关设置，请参阅[配置 AWS 凭证](/zh-CN/claude-platform-on-aws#1-configure-aws-credentials)

558* 如果刷新命令成功后错误重复，请在同一 shell 和配置文件中使用 `aws sts get-caller-identity` 确认身份在 Claude Code 外部有效

559

560<h3 id="aws-authentication-failed">

561 AWS authentication failed

562</h3>

563

564{/* min-version: 2.1.198 */}}此消息需要 Claude Code v2.1.198 或更高版本，仅当在您的设置文件中设置了 [`awsAuthRefresh`](/zh-CN/amazon-bedrock#advanced-credential-configuration) 时才出现。您的 AWS 提供商返回了 403，或 [Amazon Bedrock](/zh-CN/amazon-bedrock) 返回了 401。

565

566Claude Code 无法判断您遇到了哪个原因。Amazon Bedrock 将过期的安全令牌报告为 403，但 403 也是它报告授权拒绝的方式，例如来自缺少 IAM 权限或未为您的帐户启用的模型的 `AccessDeniedException`。

567

568来自 Amazon Bedrock 的 401 也会落在这里，而不是在 [AWS credentials expired or invalid](#aws-credentials-expired-or-invalid) 下，因为 Bedrock 不将过期令牌报告为 401。来自该端点的 401 通常来自请求路径中的其他内容，例如公司代理。

569

570凭证刷新可以修复过期令牌，无法修复其他原因，因此消息提供两者：

571

572```text theme={null}

573AWS 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 ...

574```

575

576中间的操作提示命名了您的设置中的 `awsAuthRefresh` 命令，因此它会有所不同。稳定的部分是前导 `AWS authentication failed`。

577

578**要做什么：**

579

580* 运行消息中命名的 `awsAuthRefresh` 命令或 `aws sso login`，以防过期凭证是原因

581* 如果您的凭证是最新的，请确认 [IAM 配置](/zh-CN/amazon-bedrock#iam-configuration) 中的 IAM 权限已附加到您使用的身份，并且所选模型已为您的帐户和区域启用

582* 运行 `aws sts get-caller-identity` 以确认您的请求使用哪个身份；过时的 `AWS_PROFILE` 或默认配置文件是权限不匹配的常见原因

583

480<h2 id="network-and-connection-errors">584<h2 id="network-and-connection-errors">

481 网络和连接错误585 网络和连接错误

482</h2>586</h2>

525Unable to connect to API: Self-signed certificate detected629Unable to connect to API: Self-signed certificate detected

526```630```

527 631

632{/* min-version: 2.1.199 */}}从 v2.1.199 开始，证书验证失败不会重试，因此此错误出现在第一次尝试而不是在完整[重试预算](#automatic-retries)之后。早期版本在显示之前花费几分钟重试。瞬时 TLS 条件（例如握手超时）仍然会重试。

633

634在 `/login` 和启动连接检查期间，相同的失败会报告为 OpenSSL 代码和内联修复：

635

636```text theme={null}

637SSL 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.

638```

639

528**要做什么：**640**要做什么：**

529 641

530* 导出您组织的 CA 包并使用 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` 指向 Claude Code642* 导出您组织的 CA 包并使用 `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` 指向 Claude Code

627API Error: 400 ... image dimensions exceed max allowed size739API Error: 400 ... image dimensions exceed max allowed size

628```740```

629 741

630{/* min-version: 2.1.142 */}Claude Code 将无法处理的图像替换为文本占位符并重试，因此后续消息成功。在 2.1.142 之前的版本上，粘贴的图像可能保留在对话中，并在每个后续消息上重复相同的错误。要在这些版本上恢复，请按 Esc 两次并回退到添加图像的轮次之前。742{/* min-version: 2.1.142 */}}Claude Code 将无法处理的图像替换为文本占位符并重试，因此后续消息成功。在 2.1.142 之前的版本上，粘贴的图像可能保留在对话中，并在每个后续消息上重复相同的错误。要在这些版本上恢复，请按 Esc 两次并回退到添加图像的轮次之前。

631 743

632**要做什么：**744**要做什么：**

633 745

694 There's an issue with the selected model806 There's an issue with the selected model

695</h3>807</h3>

696 808

809{/* min-version: 2.1.160 */}}

697配置的模型名称未被识别或您的帐户缺少对它的访问权限。从 v2.1.160 开始，尾部提示（此处以其交互式形式显示）因表面而异。810配置的模型名称未被识别或您的帐户缺少对它的访问权限。从 v2.1.160 开始，尾部提示（此处以其交互式形式显示）因表面而异。

698 811

699```text theme={null}812```text theme={null}

729 Model is restricted by your organization's settings842 Model is restricted by your organization's settings

730</h3>843</h3>

731 844

732{/* min-version: 2.1.187 */}您的组织管理员已在 Claude 控制台中禁用此模型，或者它被托管设置中的 [`availableModels`](/zh-CN/model-config#restrict-model-selection) 允许列表排除。当使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 设置设置受限制的模型时，Claude Code 会替换为允许的模型并继续。为受限制的模型键入 `/model <name>` 会被拒绝，显示 `Run /model to choose a different model.`，会话保持其当前模型。845{/* min-version: 2.1.187 */}}您的组织管理员已在 Claude 控制台中禁用此模型，或者它被托管设置中的 [`availableModels`](/zh-CN/model-config#restrict-model-selection) 允许列表排除。当使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 设置设置受限制的模型时，Claude Code 会替换为允许的模型并继续。为受限制的模型键入 `/model <name>` 会被拒绝，显示 `Run /model to choose a different model.`，会话保持其当前模型。

733 846

734```text theme={null}847```text theme={null}

735Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.848Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.

753 866

754**要做什么：**867**要做什么：**

755 868

869{/* min-version: 2.1.197 */}}

870

756* 运行 `claude update` 并重新启动 Claude Code。Opus 4.7 需要 v2.1.111 或更高版本。Opus 4.8 需要 v2.1.154 或更高版本。Sonnet 5 需要 v2.1.197 或更高版本871* 运行 `claude update` 并重新启动 Claude Code。Opus 4.7 需要 v2.1.111 或更高版本。Opus 4.8 需要 v2.1.154 或更高版本。Sonnet 5 需要 v2.1.197 或更高版本

757* 如果您无法升级，请运行 `/model` 并选择 Opus 4.6 或 Sonnet 4.6 代替872* 如果您无法升级，请运行 `/model` 并选择 Opus 4.6 或 Sonnet 4.6 代替

758* {/* min-version: agent-sdk@0.3.197 */}如果您在 [Agent SDK](/zh-CN/agent-sdk/overview) 中遇到这个，请升级 SDK 包。Opus 4.8 需要 TypeScript SDK v0.3.154 或更高版本和 Python SDK v0.2.88 或更高版本。Sonnet 5 需要 TypeScript SDK v0.3.197 或更高版本873* {/* min-version: agent-sdk@0.3.197 */}}如果您在 [Agent SDK](/zh-CN/agent-sdk/overview) 中遇到这个，请升级 SDK 包。Opus 4.8 需要 TypeScript SDK v0.3.154 或更高版本和 Python SDK v0.2.88 或更高版本。Sonnet 5 需要 TypeScript SDK v0.3.197 或更高版本

759 874

760<h3 id="thinking-budget-exceeds-output-limit">875<h3 id="thinking-budget-exceeds-output-limit">

761 Thinking budget exceeds output limit876 Thinking budget exceeds output limit

790 905

791**要做什么：**906**要做什么：**

792 907

793* {/* max-version: 2.1.155 */}如果您使用的是 Opus 4.7 或 Opus 4.8，请先运行 `claude update`。v2.1.156 之前的版本可能在正常工具使用期间触发此错误，并且 `/rewind` 无法清除它。908* {/* max-version: 2.1.155 */}}如果您使用的是 Opus 4.7 或 Opus 4.8，请先运行 `claude update`。v2.1.156 之前的版本可能在正常工具使用期间触发此错误，并且 `/rewind` 无法清除它。

794* 运行 `/rewind`，或按 Esc 两次，回退到损坏轮次之前的检查点并从那里继续。有关如何创建和恢复检查点的信息，请参阅[检查点](/zh-CN/checkpointing)。909* 运行 `/rewind`，或按 Esc 两次，回退到损坏轮次之前的检查点并从那里继续。有关如何创建和恢复检查点的信息，请参阅[检查点](/zh-CN/checkpointing)。

795 910

796<h3 id="usage-policy-refusal">911<h3 id="usage-policy-refusal">

811* 如果您无法识别哪个轮次导致了它，请运行 `/clear` 以在同一项目中启动新的对话。您之前的对话已保存在磁盘上，并且在 `/resume` 中仍然可用。926* 如果您无法识别哪个轮次导致了它，请运行 `/clear` 以在同一项目中启动新的对话。您之前的对话已保存在磁盘上，并且在 `/resume` 中仍然可用。

812* 在[非交互模式](/zh-CN/headless)（`-p`）中，其中 rewind 不可用，使用重新表述的提示重试或启动新会话而不使用 `--continue`。927* 在[非交互模式](/zh-CN/headless)（`-p`）中，其中 rewind 不可用，使用重新表述的提示重试或启动新会话而不使用 `--continue`。

813 928

929<h2 id="command-line-errors">

930 命令行错误

931</h2>

932

933这些错误来自 Claude Code 自己对 `claude` 命令行的验证。Claude Code 立即打印它们，然后再创建会话或发送任何 API 请求。

934

935<h3 id="conflict-between-bg-and-print">

936 Conflict between --bg and --print

937</h3>

938

939{/* min-version: 2.1.198 */}}

940此消息需要 Claude Code v2.1.198 或更高版本。您在同一 `claude` 调用中组合了 `--bg` 与 `-p` 或 `--print`。`--bg` 启动[后台会话](/zh-CN/agent-view#from-your-shell)，您稍后使用 `claude agents` 附加到，而 `--print` 运行[非交互式](/zh-CN/headless)并从不启动 `claude agents` 附加到的交互式会话。在 v2.1.198 之前，此组合默默创建了一个无法附加到的后台作业。

941

942```text theme={null}

943--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>'`.

944```

945

946**要做什么：**

947

948* 删除 `-p` 或 `--print`。`--bg` 将提示作为其位置参数，因此 `claude --bg "<task>"` 是完整的命令。请参阅[从您的 shell 分派新代理](/zh-CN/agent-view#from-your-shell)。

949* 要非交互式运行提示并打印结果而不是创建后台会话，请删除 `--bg` 并运行 `claude -p "<task>"`

950

814<h2 id="responses-seem-lower-quality-than-usual">951<h2 id="responses-seem-lower-quality-than-usual">

815 响应质量似乎低于平常952 响应质量似乎低于平常

816</h2>953</h2>

838 报告错误975 报告错误

839</h2>976</h2>

840 977

841本页涵盖来自 Claude API 的错误。对于来自其他 Claude Code 组件的错误，请参阅相关指南：978对于本页不涵盖的组件的错误，请参阅相关指南：

842 979

843* MCP 服务器无法连接或身份验证：[MCP](/zh-CN/mcp)980* MCP 服务器无法连接或身份验证：[MCP](/zh-CN/mcp)

844* Hook 脚本失败或阻止了工具：[调试 hooks](/zh-CN/hooks#debug-hooks)981* Hook 脚本失败或阻止了工具：[调试 hooks](/zh-CN/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 apps gateway44 Claude apps gateway

45</h3>45</h3>

46 46

47Claude 应用网关是 Anthropic 的自托管网关，包含在 `claude` 二进制文件中。它路由到 Amazon Bedrock、Google Cloud、Microsoft Foundry 或 Anthropic API 作为上游。开发人员通过 `/login` 使用您的企业身份提供商登录，网关按 IdP 组强制执行模型访问和 [托管设置](/zh-CN/permissions#managed-settings)，并向您自己的可观测性堆栈发出 [OpenTelemetry Protocol (OTLP)](/zh-CN/monitoring-usage) 使用指标。47Claude apps gateway 是 Anthropic 的自托管网关，包含在 `claude` 二进制文件中。它路由到 Amazon Bedrock、Claude Platform on AWS、Google Cloud、Microsoft Foundry 或 Anthropic API 作为上游。开发人员通过 `/login` 使用您的企业身份提供商登录，网关按 IdP 组强制执行模型访问和 [托管设置](/zh-CN/permissions#managed-settings)，并向您自己的可观测性堆栈发出 [OpenTelemetry Protocol (OTLP)](/zh-CN/monitoring-usage) 使用指标。

48 48

49因为它与每个 Claude Code 版本一起构建和测试，所以它转发 Claude Code 发送的标头和请求字段。单独维护的网关需要在每个版本中更改这些标头和字段时 [更新其转发规则](/zh-CN/llm-gateway-protocol#forward-as-open-lists)；Claude 应用网关与 CLI 一起发布，因此没有列表需要保持最新。有关在网关会话上行为不同的小功能集，请参阅 [可用性和限制](/zh-CN/claude-apps-gateway#availability-and-limitations)。49因为它与每个 Claude Code 版本一起构建和测试，所以它转发 Claude Code 发送的标头和请求字段。单独维护的网关需要在每个版本中更改这些标头和字段时 [更新其转发规则](/zh-CN/llm-gateway-protocol#forward-as-open-lists)；Claude 应用网关与 CLI 一起发布，因此没有列表需要保持最新。有关在网关会话上行为不同的小功能集，请参阅 [可用性和限制](/zh-CN/claude-apps-gateway#availability-and-limitations)。

50 50

hooks.md +70 −34

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 的环境。在远程 web 环境中，`$CLAUDE_CODE_REMOTE` 环境变量设置为 `"true"`，在本地 CLI 中未设置。326处理程序在当前目录中运行，使用 Claude Code 的环境。在远程 web 环境中，`$CLAUDE_CODE_REMOTE` 环境变量设置为 `"true"`，在本地 CLI 中未设置。{/* min-version: 2.1.199 */}从 v2.1.199 开始，[`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/zh-CN/env-vars)设置为[远程控制](/zh-CN/remote-control)会话 ID，而本地会话具有活跃的远程控制连接。

321 327

322<h4 id="common-fields">328<h4 id="common-fields">

323 通用字段329 通用字段

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{

1062 Setup1079 Setup

1063</h3>1080</h3>

1064 1081

1065仅当您使用 `--init-only` 启动 Claude Code，或在打印模式（`-p`）中使用 `--init` 或 `--maintenance` 时触发。它不在正常启动时触发。使用它进行一次性依赖安装或您从 CI 或脚本显式触发的计划清理，与正常会话启动分开。对于每个会话的初始化，请改用[SessionStart](#sessionstart)。1082仅当您使用 `--init-only` 启动 Claude Code，或在[非交互模式](/zh-CN/headless)中使用 `-p` 标志与 `--init` 或 `--maintenance` 结合时触发。它不在正常启动时触发。使用它进行一次性依赖安装或您从 CI 或脚本显式触发的计划清理，与正常会话启动分开。对于每个会话的初始化，请改用[SessionStart](#sessionstart)。

1066 1083

1067匹配器值对应于触发 hook 的 CLI 标志：1084匹配器值对应于触发 hook 的 CLI 标志：

1068 1085

1073 1090

1074`--init-only` 运行 Setup hooks 和 SessionStart hooks（带 `startup` 匹配器），然后退出而不启动对话。`--init` 和 `--maintenance` 仅在与 `-p`（打印模式）结合时触发 Setup hooks；在交互式会话中，这两个标志目前不触发 Setup hooks。1091`--init-only` 运行 Setup hooks 和 SessionStart hooks（带 `startup` 匹配器），然后退出而不启动对话。`--init` 和 `--maintenance` 仅在与 `-p` 结合时触发 Setup hooks；在交互式会话中，这两个标志目前不触发 Setup hooks。

1075 1092

1076因为 Setup 不在每次启动时触发，需要安装依赖的插件不能仅依赖 Setup。实际的模式是在首次使用时检查依赖，如果缺失则安装，例如测试 `${CLAUDE_PLUGIN_DATA}/node_modules` 的 hook 或 skill，如果不存在则运行 `npm install`。请参阅[持久数据目录](/zh-CN/plugins-reference#persistent-data-directory)了解在何处存储已安装的依赖。1093因为 Setup 不在每次启动时触发，需要安装依赖的插件不能仅依赖 Setup。实际的模式是在首次使用时检查依赖，如果缺失则安装，例如测试 `${CLAUDE_PLUGIN_DATA}/node_modules` 的 hook 或 skill，如果不存在则运行 `npm install`。请参阅[持久数据目录](/zh-CN/plugins-reference#persistent-data-directory)了解在何处存储已安装的依赖。

1077 1094

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-CN/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` | string | `"completed"` | 同步调用为 `"completed"`，`run_in_background: true` 为 `"async_launched"` |1564| `status` | string | `"completed"` | 前台 subagents 为 `"completed"`，后台 subagents 为 `"async_launched"`。{/* min-version: 2.1.198 */}从 v2.1.198 开始，subagents 默认在后台运行，因此省略的 `run_in_background` 也产生 `"async_launched"` |

1551| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | subagent 的最终文本块 |1566| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | subagent 的最终文本块 |

1552| `resolvedModel` | string | `"claude-sonnet-4-5"` | subagent 运行的模型，可能与请求的模型不同。{/* min-version: 2.1.174 */}需要 Claude Code v2.1.174 或更高版本 |1567| `resolvedModel` | string | `"claude-sonnet-4-5"` | subagent 运行的模型，可能与请求的模型不同。{/* min-version: 2.1.174 */}需要 Claude Code v2.1.174 或更高版本 |

1556| `usage` | object | `{"input_tokens": 8320, ...}` | 按类型的令牌分解：`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens` |1571| `usage` | object | `{"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` 值不同。它需要 Claude Code v2.1.174 或更高版本。

1561 1576

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-CN/permissions#manage-permissions)在 hook 返回什么时仍然被评估 |1612| `permissionDecision` | `"allow"` 绕过权限提示，除了[需要用户交互的工具](#pretooluse-decision-control)。`"deny"` 防止工具调用。`"ask"` 提示用户确认。`"defer"` 优雅地退出，以便工具稍后可以恢复。[拒绝和询问规则](/zh-CN/permissions#manage-permissions)在 hook 返回什么时仍然被评估 |

1599| `updatedInput` | 在执行前修改工具的输入参数。替换整个输入对象，因此包括未修改的字段以及修改后的字段。与 `"allow"` 结合以自动批准，或与 `"ask"` 结合以向用户显示修改后的输入。对于 `"defer"`，被忽略 |1614| `updatedInput` | 在执行前修改工具的输入参数。替换整个输入对象，因此包括未修改的字段以及修改后的字段。与 `"allow"` 结合以自动批准，或与 `"ask"` 结合以向用户显示修改后的输入。对于 `"defer"`，被忽略 |

1619 1634

1620`AskUserQuestion` 和 `ExitPlanMode` 需要用户交互，通常在[非交互模式](/zh-CN/headless)中使用 `-p` 标志时阻止。返回 `permissionDecision: "allow"` 以及 `updatedInput` 满足该要求：hook 从 stdin 读取工具的输入，通过您自己的 UI 收集答案，并在 `updatedInput` 中返回它，以便工具运行而不提示。仅返回 `"allow"` 对这些工具不足够。对于 `AskUserQuestion`，回显原始 `questions` 数组并添加一个[`answers`](#askuserquestion)对象，将每个问题的文本映射到选定的答案。1635`AskUserQuestion` 和 `ExitPlanMode` 需要用户交互，通常在[非交互模式](/zh-CN/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-CN/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` | 后台会话开始等待您的输入。仅在[代理视图](/zh-CN/agent-view)在终端中打开时触发 |

2046| `agent_completed` | 后台会话完成或失败。仅在[代理视图](/zh-CN/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{

2560除了所有 hooks 可用的[JSON 输出字段](#json-output)外，CwdChanged hooks 还可以返回 `watchPaths` 来动态设置[FileChanged](#filechanged)监视的文件路径：2590除了所有 hooks 可用的[JSON 输出字段](#json-output)外，CwdChanged hooks 还可以返回 `watchPaths` 来动态设置[FileChanged](#filechanged)监视的文件路径：

2561 2591

2562| 字段 | 描述 |2592| 字段 | 描述 |

2563| :----------- | :--------------------------------------------------------------------- |2593| :----------- | :-------------------------------------------------------------------- |

2565 2595

2566CwdChanged hooks 没有决定控制。它们无法阻止目录更改。2596CwdChanged hooks 没有决定控制。它们无法阻止目录更改。

2567 2597

2607除了所有 hooks 可用的[JSON 输出字段](#json-output)外，FileChanged hooks 还可以返回 `watchPaths` 来动态更新监视的文件路径：2637除了所有 hooks 可用的[JSON 输出字段](#json-output)外，FileChanged hooks 还可以返回 `watchPaths` 来动态更新监视的文件路径：

2608 2638

2609| 字段 | 描述 |2639| 字段 | 描述 |

2610| :----------- | :------------------------------------------------------------------------------ |2640| :----------- | :----------------------------------------------------------------------------- |

2612 2642

2613FileChanged hooks 没有决定控制。它们无法阻止文件更改的发生。2643FileChanged hooks 没有决定控制。它们无法阻止文件更改的发生。

2614 2644

2616 WorktreeCreate2646 WorktreeCreate

2617</h3>2647</h3>

2618 2648

2619当您运行 `claude --worktree` 或[subagent 使用 `isolation: "worktree"`](/zh-CN/sub-agents#choose-the-subagent-scope)时，Claude Code 使用 `git worktree` 创建隔离的工作副本。如果您配置 WorktreeCreate hook，它替换默认的 git 行为，让您使用不同的版本控制系统，如 SVN、Perforce 或 Mercurial。2649当您运行 `claude --worktree` 或[subagent 使用 `isolation: "worktree"`](/zh-CN/sub-agents#choose-the-subagent-scope)时运行。默认情况下，Claude Code 使用 `git worktree` 创建隔离的工作副本。配置 WorktreeCreate hook 替换该默认 git 行为，让您使用不同的版本控制系统，如 SVN、Perforce 或 Mercurial。

2620 2650

2621因为 hook 完全替换默认行为，[`.worktreeinclude`](/zh-CN/worktrees#copy-gitignored-files-into-worktrees)不被处理。如果您需要将本地配置文件（如 `.env`）复制到新 worktree，请在您的 hook 脚本内执行。2651因为 hook 完全替换默认行为，[`.worktreeinclude`](/zh-CN/worktrees#copy-gitignored-files-into-worktrees)不被处理。如果您需要将本地配置文件（如 `.env`）复制到新 worktree，请在您的 hook 脚本内执行。

2622 2652

2647 WorktreeCreate 输入2677 WorktreeCreate 输入

2648</h4>2678</h4>

2649 2679

2650除了[通用输入字段](#common-input-fields)外，WorktreeCreate hooks 还接收 `name` 字段。这是新 worktree 的 slug 标识符，由用户指定或自动生成（例如，`bold-oak-a3f2`）。2680除了[通用输入字段](#common-input-fields)外，WorktreeCreate hooks 还接收 `name` 字段。这是新 worktree 的 slug 标识符，由用户指定或自动生成，例如 `bold-oak-a3f2`。

2651 2681

2652```json theme={null}2682```json theme={null}

2653{2683{

2674 WorktreeRemove2704 WorktreeRemove

2675</h3>2705</h3>

2676 2706

2677[WorktreeCreate](#worktreecreate) 的清理对应物。此 hook 在 worktree 被移除时触发，要么当您退出 `--worktree` 会话并选择移除它时，要么当具有 `isolation: "worktree"` 的 subagent 完成时。对于基于 git 的 worktrees，Claude 使用 `git worktree remove` 自动处理清理。如果您为非 git 版本控制系统配置了 WorktreeCreate hook，将其与 WorktreeRemove hook 配对以处理清理。没有它，worktree 目录留在磁盘上。2707当 worktree 被移除时运行，要么当您退出 `--worktree` 会话并选择移除它时，要么当具有 `isolation: "worktree"` 的 subagent 完成时。这是[WorktreeCreate](#worktreecreate)的清理对应物。

2708

2709对于基于 git 的 worktrees，Claude Code 使用 `git worktree remove` 自动处理清理。如果您为非 git 版本控制系统配置了 WorktreeCreate hook，将其与 WorktreeRemove hook 配对以处理清理。没有它，worktree 目录留在磁盘上。

2678 2710

2679Claude Code 将 WorktreeCreate 返回的路径作为 `worktree_path` 在 hook 输入中传递。此示例读取该路径并移除目录：2711Claude Code 将 WorktreeCreate 返回的路径作为 `worktree_path` 在 hook 输入中传递。此示例读取该路径并移除目录：

2680 2712

3063 3095

3064如果您需要对任何事件进行更精细的控制，请使用[命令 hook](#command-hook-fields)，其中包含[决定控制](#decision-control)中描述的每个事件字段。3096如果您需要对任何事件进行更精细的控制，请使用[命令 hook](#command-hook-fields)，其中包含[决定控制](#decision-control)中描述的每个事件字段。

3065 3097

3066<h3 id="example-multi-criteria-stop-hook">3098<h3 id="check-multiple-conditions-before-stopping">

3067 示例：多条件 Stop hook3099 检查多个条件后再停止

3068</h3>3100</h3>

3069 3101

3070此 `Stop` hook 使用详细提示检查三个条件，然后允许 Claude 停止。如果 `"ok"` 为 `false`，Claude 继续工作，提供的原因作为其下一条指令。`SubagentStop` hooks 使用相同的格式来评估[子代理](/zh-CN/sub-agents)是否应该停止：3102此 `Stop` hook 使用详细提示检查三个条件，然后允许 Claude 停止。`SubagentStop` hooks 使用相同的格式来评估[子代理](/zh-CN/sub-agents)是否应该停止。如果 `"ok"` 为 `false`，Claude 继续工作，提供的原因作为其下一条指令：

3071 3103

3072```json theme={null}3104```json theme={null}

3073{3105{

3191 3223

3192异步 hook 完成通知默认被抑制。要查看它们，请使用 `Ctrl+O` 启用详细模式或使用 `--verbose` 启动 Claude Code。3224异步 hook 完成通知默认被抑制。要查看它们，请使用 `Ctrl+O` 启用详细模式或使用 `--verbose` 启动 Claude Code。

3193 3225

3194<h3 id="example-run-tests-after-file-changes">3226<h3 id="run-tests-after-file-changes">

3195 示例：文件更改后运行测试3227 文件更改后运行测试

3196</h3>3228</h3>

3197 3229

3198此 hook 在 Claude 写入文件时在后台启动测试套件，然后在测试完成时将结果报告回 Claude。将此脚本保存到项目中的 `.claude/hooks/run-tests-async.sh` 并使用 `chmod +x` 使其可执行：3230此 hook 在 Claude 写入文件时在后台启动测试套件，然后在测试完成时将结果报告回 Claude。将此脚本保存到项目中的 `.claude/hooks/run-tests-async.sh` 并使用 `chmod +x` 使其可执行：

3286 Windows PowerShell 工具3318 Windows PowerShell 工具

3287</h2>3319</h2>

3288 3320

3289在 Windows 上，您可以通过在命令 hook 上设置 `"shell": "powershell"` 在 PowerShell 中运行单个 hooks。Hooks 直接生成 PowerShell，因此这适用于是否设置了 `CLAUDE_CODE_USE_POWERSHELL_TOOL`。Claude Code 自动检测 `pwsh.exe`（PowerShell 7+），回退到 `powershell.exe`（5.1）。3321在 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）。

3290 3322

3291```json theme={null}3323```json theme={null}

3292{3324{

3307}3339}

3308```3340```

3309 3341

3310要从 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 在何处定义。3342要从 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`、插件还是技能中定义。PowerShell 在解析后从导出的环境中解析该值，因此占位符在双引号字符串内有效，但在单引号字符串内无效，PowerShell 在单引号字符串中永远不会展开变量。

3343

3344在 v2.1.198 之前，此重写仅适用于插件 hooks。在早期版本上，`settings.json` hook 需要 `$env:` 形式或 [exec 形式](#exec-form-and-shell-form)，其中 `${CLAUDE_PROJECT_DIR}` 在每个 `args` 元素中被替换，无论 hook 在何处定义。

3345

3346不要在 PowerShell hook 中写入裸 `$CLAUDE_PROJECT_DIR` 拼写。PowerShell 将其解析为未定义的本地变量，并将其解析为 `$null`，这会导致脚本路径没有其项目根前缀。Claude Code 不会重写该形式；它会在 [debug log](#debug-hooks) 中记录警告。

3311 3347

3312下面的示例显示了一个 `settings.json` hook，它使用 `$env:` 形式运行项目脚本：3348下面的示例显示了一个 `settings.json` hook，它使用 `$env:` 形式运行项目脚本，该形式在每个版本上都有效：

3313 3349

3314```json theme={null}3350```json theme={null}

3315{3351{

hooks-guide.md +31 −27

Details

87 87

88Hooks 让你在 Claude Code 生命周期中的关键点运行代码：编辑后格式化文件、在执行前阻止命令、在 Claude 需要输入时发送通知、在会话开始时注入上下文等。有关完整的 hook 事件列表，请参阅 [Hooks 参考](/zh-CN/hooks#hook-lifecycle)。88Hooks 让你在 Claude Code 生命周期中的关键点运行代码：编辑后格式化文件、在执行前阻止命令、在 Claude 需要输入时发送通知、在会话开始时注入上下文等。有关完整的 hook 事件列表，请参阅 [Hooks 参考](/zh-CN/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` 插件如何与 Claude Code 集成](/zh-CN/security-guidance#how-the-plugin-integrates-with-claude-code)。92有关运行单独模型审查并将发现反馈回会话的 hooks 的生产示例，请参阅 [`security-guidance` 插件如何与 Claude Code 集成](/zh-CN/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-CN/agent-view) 打开时触发 |

185| `agent_completed` | 后台会话完成或失败。仅在 [agent view](/zh-CN/agent-view) 打开时触发 |

186

187`agent_needs_input` 和 `agent_completed` 匹配器需要 Claude Code v2.1.198 或更高版本。

192 188

193输入 `/hooks` 并选择 `Notification` 以确认 hook 已注册。有关完整的事件架构，请参阅 [Notification 参考](/zh-CN/hooks#notification)。189输入 `/hooks` 并选择 `Notification` 以确认 hook 已注册。有关完整的事件架构，请参阅 [Notification 参考](/zh-CN/hooks#notification)。

194 190

198 194

199在 Claude 编辑的每个文件上自动运行 [Prettier](https://prettier.io/)，以便格式保持一致而无需手动干预。195在 Claude 编辑的每个文件上自动运行 [Prettier](https://prettier.io/)，以便格式保持一致而无需手动干预。

200 196

201此 hook 使用带有 `Edit|Write` 匹配器的 `PostToolUse` 事件，因此它仅在文件编辑工具之后运行。{/* min-version: 2.1.191 */}在 Claude Code v2.1.191 或更高版本上，你也可以将匹配器写为 `Edit,Write`，因为在这些版本上 `|` 和 `,` 是工具名称匹配器的可互换列表分隔符。该命令使用 [`jq`](https://jqlang.github.io/jq/) 提取编辑的文件路径并将其传递给 Prettier。将其添加到项目根目录中的 `.claude/settings.json`：197此 hook 使用带有 `Edit|Write` 匹配器的 `PostToolUse` 事件，因此它仅在文件编辑工具之后运行。该命令使用 [`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` 列出要监视的文件名，用 `|` 分隔。要构建监视列表，此值被分割为文字文件名而不是作为正则表达式进行评估。有关当文件更改时相同值如何也过滤哪些 hook 组运行，请参阅 [FileChanged](/zh-CN/hooks#filechanged)。此示例监视工作目录中 `.envrc` 和 `.env` 的更改：379要对特定文件而不是每个目录更改做出反应，请使用 `FileChanged` 和 `matcher` 列出要监视的文件名，用 `|` 分隔。要构建监视列表，Claude Code 将此值分割为文字文件名而不是作为正则表达式进行评估。有关当文件更改时相同值如何也过滤哪些 hook 组运行，请参阅 [FileChanged](/zh-CN/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-CN/hooks#decision-control)。618其他事件使用不同的决策模式。例如，`PostToolUse` 和 `Stop` hooks 使用顶级 `decision: "block"` 字段，而 `PermissionRequest` 使用 `hookSpecificOutput.decision.behavior`。有关按事件的完整分解，请参阅参考中的 [摘要表](/zh-CN/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 命令">

753 753

754`if` 字段使用 [权限规则语法](/zh-CN/permissions) 按工具名称和参数一起过滤 hooks，因此 hook 进程仅在工具调用匹配时生成。这超越了 `matcher`，它仅在工具名称级别按组过滤。754`if` 字段使用 [权限规则语法](/zh-CN/permissions) 按工具名称和参数一起过滤 hooks，因此 hook 进程仅在工具调用匹配时生成。这超越了 `matcher`，它仅在工具名称级别按组过滤。

755 755

756例如，要仅在 Claude 使用 `git` 命令而不是所有 Bash 命令时运行 hook：756例如，这个配置仅在 Claude 使用 `git` 命令而不是所有 Bash 命令时运行 hook：

757 757

758```json theme={null}758```json theme={null}

759{759{

807 807

808在 Claude Code 中运行 [`/hooks`](/zh-CN/hooks#the-%2Fhooks-menu) 以浏览所有按事件分组的配置 hooks。要禁用 hooks，在设置文件中设置 `"disableAllHooks": true`。托管设置中配置的 Hooks 仍然运行，除非 `disableAllHooks` 也在那里设置。808在 Claude Code 中运行 [`/hooks`](/zh-CN/hooks#the-%2Fhooks-menu) 以浏览所有按事件分组的配置 hooks。

809

810要禁用 hooks，在设置文件中设置 `"disableAllHooks": true`。托管设置中配置的 Hooks 仍然运行，除非 `disableAllHooks` 也在那里设置。

809 811

810如果你在 Claude Code 运行时直接编辑设置文件，文件监视器通常会自动拾取 hook 更改。812如果你在 Claude Code 运行时直接编辑设置文件，文件监视器通常会自动拾取 hook 更改。

811 813

925 限制927 限制

926</h3>928</h3>

927 929

930设计 hooks 时请记住这些约束：

931

928* 命令 hooks 仅通过 stdout、stderr 和退出代码通信。它们无法触发 `/` 命令或工具调用。通过 `additionalContext` 返回的文本被注入为 Claude 作为纯文本读取的系统提醒。HTTP hooks 改为通过响应体通信。932* 命令 hooks 仅通过 stdout、stderr 和退出代码通信。它们无法触发 `/` 命令或工具调用。通过 `additionalContext` 返回的文本被注入为 Claude 作为纯文本读取的系统提醒。HTTP hooks 改为通过响应体通信。

929* Hook 超时因类型而异。通过 `timeout` 字段（以秒为单位）按 hook 覆盖。933* Hook 超时因类型而异。通过 `timeout` 字段（以秒为单位）按 hook 覆盖。

930 * `command`、`http`、`mcp_tool`：10 分钟。`UserPromptSubmit` 将这些降低到 30 秒，`MessageDisplay` 将这些降低到 10 秒。934 * `command`、`http`、`mcp_tool`：10 分钟。`UserPromptSubmit` 将这些降低到 30 秒，`MessageDisplay` 将这些降低到 10 秒。

931 * `prompt`：30 秒。935 * `prompt`：30 秒。

932 * `agent`：60 秒。936 * `agent`：60 秒。

933* `PostToolUse` hooks 无法撤销操作，因为工具已经执行。937* `PostToolUse` hooks 无法撤销操作，因为工具已经执行。

934* `PermissionRequest` hooks 不在 [非交互模式](/zh-CN/headless)（`-p`）中触发。对于自动化权限决策，使用 `PreToolUse` hooks。938* `PermissionRequest` hooks 不在 [非交互模式](/zh-CN/headless)（带 `-p` 标志）中触发。对于自动化权限决策，使用 `PreToolUse` hooks。

935* `Stop` hooks 在 Claude 完成响应时触发，而不仅仅在任务完成时。它们不在用户中断时触发。API 错误触发 [StopFailure](/zh-CN/hooks#stopfailure) 代替。939* `Stop` hooks 在 Claude 完成响应时触发，而不仅仅在任务完成时。它们不在用户中断时触发。API 错误触发 [StopFailure](/zh-CN/hooks#stopfailure) 代替。

936* 当多个 PreToolUse hooks 返回 [`updatedInput`](/zh-CN/hooks#pretooluse) 来重写工具的参数时，最后完成的获胜。由于 hooks 并行运行，顺序是非确定性的。避免有多个 hook 修改同一工具的输入。940* 当多个 `PreToolUse` hooks 返回 [`updatedInput`](/zh-CN/hooks#pretooluse) 来重写工具的参数时，最后完成的获胜。由于 hooks 并行运行，顺序是非确定性的。避免有多个 hook 修改同一工具的输入。

937 941

938<h3 id="hooks-and-permission-modes">942<h3 id="hooks-and-permission-modes">

939 Hooks 和权限模式943 Hooks 和权限模式

940</h3>944</h3>

941 945

942PreToolUse hooks 在任何权限模式检查之前触发。返回 `permissionDecision: "deny"` 的 hook 会阻止工具，即使在 `bypassPermissions` 模式或使用 `--dangerously-skip-permissions` 时也是如此。这让你强制执行用户无法通过更改其权限模式来绕过的策略。946`PreToolUse` hooks 在任何权限模式检查之前触发。返回 `permissionDecision: "deny"` 的 hook 会阻止工具，即使在 `bypassPermissions` 模式或使用 `--dangerously-skip-permissions` 时也是如此。这让你强制执行用户无法通过更改其权限模式来绕过的策略。

943 947

944反面不成立：返回 `"allow"` 的 hook 不会绕过来自设置的拒绝规则。Hooks 可以收紧限制，但不能放松它们超过权限规则允许的范围。948反面不成立：返回 `"allow"` 的 hook 不会绕过来自设置的拒绝规则。Hooks 可以收紧限制，但不能放松它们超过权限规则允许的范围。

945 949

950Hook 已配置但从不执行。954Hook 已配置但从不执行。

951 955

952* 运行 `/hooks` 并确认 hook 出现在正确的事件下956* 运行 `/hooks` 并确认 hook 出现在正确的事件下

953* 检查匹配器模式是否与工具名称完全匹配（匹配器区分大小写）957* 检查匹配器模式是否与工具名称完全匹配。匹配器区分大小写

954* 验证你是否触发了正确的事件类型（例如，`PreToolUse` 在工具执行前触发，`PostToolUse` 在之后触发）958* 验证你是否触发了正确的事件类型：`PreToolUse` 在工具执行前触发，`PostToolUse` 在之后触发

955* 如果在非交互模式（`-p`）中使用 `PermissionRequest` hooks，改用 `PreToolUse`959* 如果在非交互模式（带 `-p` 标志）中使用 `PermissionRequest` hooks，改用 `PreToolUse`

956 960

957<h3 id="hook-error-in-output">961<h3 id="hook-error-in-output">

958 Hook 输出中的错误962 Hook 输出中的错误

976你编辑了设置文件但 hooks 不出现在菜单中。980你编辑了设置文件但 hooks 不出现在菜单中。

977 981

978* 文件编辑通常会自动拾取。如果几秒钟后它们还没有出现，文件监视器可能错过了更改：重新启动你的会话以强制重新加载。982* 文件编辑通常会自动拾取。如果几秒钟后它们还没有出现，文件监视器可能错过了更改：重新启动你的会话以强制重新加载。

979* 验证你的 JSON 有效（不允许尾随逗号和注释）983* 验证你的 JSON 有效：不允许尾随逗号和注释

980* 确认设置文件在正确的位置：`.claude/settings.json` 用于项目 hooks，`~/.claude/settings.json` 用于全局 hooks984* 确认设置文件在正确的位置：`.claude/settings.json` 用于项目 hooks，`~/.claude/settings.json` 用于全局 hooks

981 985

982<h3 id="stop-hook-hits-the-block-cap">986<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-CN/env-vars) 而不是在 gateway 中删除它。109Claude Code 在系统提示前面加上一个短的归属块，其中包含客户端版本和从对话派生的指纹。`api.anthropic.com` 端点在处理前删除该块，因此它不会影响第一方提示缓存。任何其他上游都会将其作为提示的一部分接收。

110

111该删除是位置相关的，因此只有在网关原样转发 `system` 数组时才有效。要在不丢失其他系统内容的情况下将该块排除在提示之外：

112

113* 完全按照接收的方式转发 `system` 数组，保持该块在最前面：在前面加上另一个系统块、重新排序数组或将其转换为单个字符串会破坏删除，该块随后会到达模型和提示缓存键。

114* 将该块保留在其自己的数组条目中：端点将以归属标头开头的合并块视为完整的归属，并删除合并到其中的所有内容，包括系统提示的其余部分。

115* 如果您的网关必须重新整形系统内容，请设置 [`CLAUDE_CODE_ATTRIBUTION_HEADER=0`](/zh-CN/env-vars) 以便 Claude Code 省略该块。Anthropic 和云提供商的 Claude 端点读取该块以进行归属，因此要在客户端省略它，而不是在网关中删除或移动它。

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 +43 −0

Details

1035 如果您经常遇到特定 MCP 服务器的输出警告，而您不控制这些服务器，请考虑增加 `MAX_MCP_OUTPUT_TOKENS` 限制。您也可以要求服务器作者添加 `anthropic/maxResultSizeChars` 注释或对其响应进行分页。注释对返回图像内容的工具没有影响；对于这些，提高 `MAX_MCP_OUTPUT_TOKENS` 是唯一的选择。1035 如果您经常遇到特定 MCP 服务器的输出警告，而您不控制这些服务器，请考虑增加 `MAX_MCP_OUTPUT_TOKENS` 限制。您也可以要求服务器作者添加 `anthropic/maxResultSizeChars` 注释或对其响应进行分页。注释对返回图像内容的工具没有影响；对于这些，提高 `MAX_MCP_OUTPUT_TOKENS` 是唯一的选择。

1036</Warning>1036</Warning>

1037 1037

1038<h2 id="tool-input-schemas-with-a-root-level-combinator">

1039 具有根级组合器的工具输入架构

1040</h2>

1041

1042某些 MCP 服务器将工具的输入架构声明为 JSON Schema 联合，在架构的顶级使用 `anyOf`、`oneOf` 或 `allOf`。Claude API 不接受这些关键字在架构根目录。它接受嵌套在 `properties` 内的组合器，Claude Code 原样发送。

1043

1044从 Claude Code v2.1.195 开始，具有根级组合器的工具保持可用。在将工具发送到 API 之前，Claude Code 将架构展平为单个对象，并在工具的描述前面添加一个句子，告诉 Claude 哪些参数组属于一起：

1045

1046* `allOf`：来自每个分支的属性被合并，每个分支的 `required` 列表仍然适用

1047* `anyOf` 和 `oneOf`：来自每个分支的属性被合并，每个分支的 `required` 列表在工具描述中描述，而不是由架构强制执行

1048

1049您的服务器接收 Claude 选择的任何参数，因此请继续在服务器端验证组合。

1050

1051当 Claude Code 无法生成 API 接受的架构，或在不接收启用重写的远程配置的部署上（例如离线机器）时，它会跳过该工具，在服务器的日志中记录原因，并保持服务器的其他工具可用。早于 v2.1.195 的版本会跳过其输入架构具有根级 `anyOf`、`oneOf` 或 `allOf` 的每个工具。

1052

1053<h2 id="require-approval-for-a-specific-tool">

1054 要求特定工具的批准

1055</h2>

1056

1057如果您正在构建 MCP 服务器，您可以通过在工具的 `tools/list` 响应条目中将 `_meta["anthropic/requiresUserInteraction"]` 设置为 `true` 来标记工具需要每次调用时的明确批准。该值必须是 JSON 布尔值 `true`；任何其他值都被忽略。

1058

1059Claude Code 在每次调用时显示该工具的权限提示，即使在 `acceptEdits`、`auto` 和 `bypassPermissions` [权限模式](/zh-CN/permissions#permission-modes) 中，并且不为其提供"不再询问"选项。[允许规则](/zh-CN/permissions#permission-rule-syntax)与工具匹配也不会跳过提示。在 `dontAsk` 模式中（从不提示），Claude Code 改为拒绝调用。

1060

1061提示必须到达一个人。在非交互模式下使用 [`--permission-prompt-tool`](/zh-CN/cli-reference#cli-flags)，标记工具的 `allow` 结果从提示工具转换为拒绝，消息为 `MCP tool requires user interaction; not supported via --permission-prompt-tool`。Agent SDK 的 [`canUseTool` 回调](/zh-CN/agent-sdk/permissions)确实接收这些调用并可以批准它们，因为 SDK 主机应该向用户显示它们。

1062

1063对于权限提示本身就是重点的工具，请使用此功能，例如同意或访问授予步骤，其中自动批准意味着没有人类曾经同意。来自同一服务器的其他工具保持其正常权限行为。

1064

1065以下 `tools/list` 条目标记一个工具始终需要批准。

1066

1067```json theme={null}

1068{

1069 "name": "grant_access",

1070 "description": "Requests access to a protected resource",

1071 "_meta": {

1072 "anthropic/requiresUserInteraction": true

1073 }

1074}

1075```

1076

1077`anthropic/requiresUserInteraction` 注释需要 Claude Code v2.1.199 或更高版本。较早的版本忽略它并应用标准权限流程。

1078

1079当会话连接到[远程控制](/zh-CN/remote-control)或 SDK 主机时，Claude Code 将权限请求标记为需要用户交互，因此客户端向您显示工具的权限提示，而不是一键批准操作。

1080

1038<h2 id="respond-to-mcp-elicitation-requests">1081<h2 id="respond-to-mcp-elicitation-requests">

1039 响应 MCP 引发请求1082 响应 MCP 引发请求

1040</h2>1083</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 +61 −8

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-CN/sub-agents#choose-a-model) frontmatter 中的 `model` 字段、Agent 工具的 `model` 参数、`/agents` 中的模型选择器和 `CLAUDE_CODE_SUBAGENT_MODEL`131* **子代理模型**：[子代理](/zh-CN/sub-agents#choose-a-model) frontmatter 中的 `model` 字段、Agent 工具的 `model` 参数、`CLAUDE_CODE_SUBAGENT_MODEL`，以及在 v2.1.197 及更早版本上，`/agents` 向导中的模型选择器{/* max-version: 2.1.197 */}

132* **技能和命令模型**：[技能和命令](/zh-CN/skills)中的 `model` frontmatter132* **技能和命令模型**：[技能和命令](/zh-CN/skills)中的 `model` frontmatter

133* **顾问模型**：配置的 [`advisorModel`](/zh-CN/advisor) 设置和 `--advisor` 标志133* **顾问模型**：配置的 [`advisorModel`](/zh-CN/advisor) 设置和 `--advisor` 标志

134* **后台代理模型**：[分派选择器](/zh-CN/agent-view)中选择的模型134* **后台代理模型**：[分派选择器](/zh-CN/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-CN/fast-mode)会被拒绝。138自动模型更改的检查方式相同：[回退模型链](#fallback-model-chains)中列表外的元素会被删除，计划模式升级（如 [`opusplan`](#opusplan-model-setting) 升级到被排除的模型）会被跳过，以便规划继续在会话的模型上进行，[自动模型回退](#automatic-model-fallback)的目标被排除时不会运行，因此标记的请求以拒绝结束。当会话之后运行的模型在允许列表外时，启用[快速模式](/zh-CN/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这两种机制组合：仅当模型被 `availableModels` 允许且不被组织限制时，它才可选择。组织限制被交付到 Anthropic API 和 [LLM 网关](/zh-CN/llm-gateway)部署上的会话。Bedrock、Vertex AI、Foundry 和 AWS 上的 Claude Platform 上的会话不接收它们，因此在那些提供商上改用 `availableModels`。245限制应用于组织范围或按角色：

246

247* 在组织级别禁用模型会为每个成员删除它。

248* 角色级别访问为不同的自定义角色授予不同的模型，持有多个角色的成员可以使用其任何角色授予的模型。

249* Haiku 模型始终可用，无法禁用，因此每个成员至少保持一个可用模型。

250* 访问更改在约一分钟内对新请求生效；`/model` 选择器在下次会话启动时反映它。

251

252两种限制一起适用：仅当模型被 `availableModels` 允许且不被组织限制时，它才可选择。组织限制被交付到 Anthropic API 和 [LLM 网关](/zh-CN/llm-gateway)部署上的会话。Bedrock、Vertex AI、Foundry 和 AWS 上的 Claude Platform 上的会话不接收它们，因此在那些提供商上改用 `availableModels`。

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-CN/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-CN/zero-data-retention)下的 Fable 5，会被跳过，"默认"选项解析为账户类型默认值

283

284从 v2.1.199 开始，当组织默认值是与您的账户类型通常默认值不同的模型系列时，`/model` 选择器为该通常系列保持一个单独的行，因此您仍然可以为会话切换到它。在 v2.1.196 到 v2.1.198 中，该行在选择器中缺失。

285

286组织默认值被交付到使用 Anthropic API 进行身份验证的会话。[LLM 网关](/zh-CN/llm-gateway)部署、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 AWS 上的 Claude Platform 上的会话不接收它。要在这些部署上设置默认值，改用[托管设置](/zh-CN/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 上的会话不接收它们。

246 297

247<h2 id="special-model-behavior">298<h2 id="special-model-behavior">

248 特殊模型行为299 特殊模型行为

261 312

262Enterprise 按使用量付费是指按使用量而非按订阅席位计费的 Enterprise 组织。313Enterprise 按使用量付费是指按使用量而非按订阅席位计费的 Enterprise 组织。

263 314

264当托管设置[对默认模型强制执行允许列表](#enforce-the-allowlist-for-the-default-model)且账户类型默认值不在 `availableModels` 中时，`default` 会解析为强制执行的默认值，而不是上面的账户类型默认值。315当管理员设置了[组织默认模型](#organization-default-model)时，`default` 解析为该模型，而不是上面的账户类型默认值。需要 Claude Code v2.1.196 或更高版本。

316

317当托管设置[对默认模型强制执行允许列表](#enforce-the-allowlist-for-the-default-model)且账户类型默认值不在 `availableModels` 中时，`default` 会解析为强制执行的默认值，而不是上面的账户类型默认值。当两者都适用时，组织默认值首先替换账户类型默认值，然后强制执行应用于它：允许列表中的组织默认值被保留，而列表外的则解析为强制执行的默认值。

265 318

266Fable 5 不是任何账户类型的默认模型。会话仅在您选择 Fable 5 后才使用它，通过 `/model fable`、`model` 设置或 Fable 5 可用的 `best` 别名。使用 `/model` 选择它会将其保存为用户设置中的选定模型，因此后续会话将从 Fable 5 开始，直到您更改模型。319Fable 5 不是任何账户类型的默认模型。会话仅在您选择 Fable 5 后才使用它，通过 `/model fable`、`model` 设置或 Fable 5 可用的 `best` 别名。使用 `/model` 选择它会将其保存为用户设置中的选定模型，因此后续会话将从 Fable 5 开始，直到您更改模型。

267 320

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

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-CN/auto-mode-config#define-trusted-infrastructure)条目，例如敏感的远程目标和受保护的 IaC 范围，您可以将其缩小到具体名称。243Claude Code v2.1.195 及更高版本默认阻止更多类别。其中几个取决于[环境](/zh-CN/auto-mode-config#define-trusted-infrastructure)条目，例如敏感的远程目标和受保护的 IaC 范围，您可以将其缩小到具体名称。

251* 交互式 shell 或端口转发到敏感的远程目标252* 交互式 shell 或端口转发到敏感的远程目标

252* 打开隧道或反向 shell，使本地服务可从公共互联网访问253* 打开隧道或反向 shell，使本地服务可从公共互联网访问

253* 将实时凭证或令牌打印到记录或文件中254* 将实时凭证或令牌打印到记录或文件中

254* 访问 PII 或受管制数据位置，或从其中复制数据255* 访问列为您[环境](/zh-CN/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-CN/chrome) 浏览器操作可能会发送页面内容、cookie 或凭证跨源259* [Chrome 中的 Claude](/zh-CN/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-CN/auto-mode-config#define-trusted-infrastructure) 中列出的受信任域、桶和服务发送数据。这仅涵盖数据流，不涵盖相同基础设施上的破坏性或凭证操作280* 向您在 [`environment`](/zh-CN/auto-mode-config#define-trusted-infrastructure) 中列出的受信任域、桶和服务发送数据。这仅涵盖数据流，不涵盖相同基础设施上的破坏性或凭证操作

273* [Chrome 中的 Claude](/zh-CN/chrome) 导航到受信任的内部域、localhost 或您命名的 URL281* [Chrome 中的 Claude](/zh-CN/chrome) 导航到受信任的内部域、localhost 或您命名的 URL

274 282

275Sandbox 网络访问请求通过分类器路由而不是默认允许。运行 `claude auto-mode defaults` 以查看完整的规则列表。如果常规操作被阻止，管理员可以通过 `autoMode.environment` 设置添加受信任的仓库、桶和服务：请参阅[配置 auto mode](/zh-CN/auto-mode-config)。283Sandbox 网络访问请求通过分类器路由而不是默认允许。{/* min-version: 2.1.198 */}从 v2.1.198 开始，分类器重用其对网络主机和端口的判决，而不是在每次连接时重新运行：

284

285* 允许被重用直到新内容进入对话，此时该主机被再次检查

286* 在交互式 CLI 中，拒绝在轮次结束时被丢弃

287* 在[非交互式模式](/zh-CN/headless)和 Agent SDK 会话中没有轮次边界，因此拒绝在运行的其余部分被重用

288* 改变您的权限模式或规则会丢弃所有缓存的判决

289

290运行 `claude auto-mode defaults` 以查看完整的规则列表。如果常规操作被阻止，管理员可以通过 `autoMode.environment` 设置添加受信任的仓库、桶和服务：请参阅[配置 auto mode](/zh-CN/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-CN/permissions#manage-permissions)匹配的操作立即解决，除了对[受保护路径](#protected-paths)的写入，即使允许规则匹配也会路由到分类器316 1. 与您的[允许或拒绝规则](/zh-CN/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-CN/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 开始，sandbox 网络判决对于主机和端口被重用，而不是在每次连接时重新分类，因此重复连接到同一主机不会各自添加检查。[分类器默认阻止的内容](#what-the-classifier-blocks-by-default)描述了允许和拒绝持续多长时间。

330 </Accordion>345 </Accordion>

331</AccordionGroup>346</AccordionGroup>

332 347

334 仅使用 dontAsk mode 允许预先批准的工具349 仅使用 dontAsk mode 允许预先批准的工具

335</h2>350</h2>

336 351

337`dontAsk` mode 自动拒绝每个会提示的工具调用。仅与您的 `permissions.allow` 规则和[只读 Bash 命令](/zh-CN/permissions#read-only-commands)匹配的操作可以执行；显式 [`ask` 规则](/zh-CN/permissions#manage-permissions)被拒绝而不是提示。这使模式完全非交互式，适合 CI 管道或受限环境，其中您预先定义 Claude 可能执行的确切操作。[Claude Code on the web](/zh-CN/claude-code-on-the-web) 上的云会话忽略 `defaultMode: "dontAsk"`；有关详细信息，请参阅 [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode)。352`dontAsk` mode 自动拒绝每个会提示的工具调用。状态栏在此模式处于活动状态时显示 `⏵⏵ don't ask on`。仅与您的 `permissions.allow` 规则和[只读 Bash 命令](/zh-CN/permissions#read-only-commands)匹配的操作可以执行；显式 [`ask` 规则](/zh-CN/permissions#manage-permissions)被拒绝而不是提示。{/* min-version: 2.1.199 */}从 v2.1.199 开始，标记有 [`_meta["anthropic/requiresUserInteraction"]`](/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具在此模式下也会被拒绝，即使允许规则匹配它，因为其批准卡需要此模式永远不会收集的答案。这使模式完全非交互式，适合 CI 管道或受限环境，其中您预先定义 Claude 可能执行的确切操作。[Claude Code on the web](/zh-CN/claude-code-on-the-web) 上的云会话忽略 `defaultMode: "dontAsk"`；有关详细信息，请参阅 [bypassPermissions](#skip-all-checks-with-bypasspermissions-mode)。

338 353

339在启动时使用标志设置它：354在启动时使用标志设置它：

340 355

346 使用 bypassPermissions mode 跳过所有检查361 使用 bypassPermissions mode 跳过所有检查

347</h2>362</h2>

348 363

349`bypassPermissions` mode 禁用权限提示和安全检查，因此工具调用立即执行。从 v2.1.126 开始，这包括对[受保护路径](#protected-paths)的写入，早期版本仍然会提示。显式[询问规则](/zh-CN/permissions#manage-permissions)仍然会在此模式下强制提示，针对文件系统根目录或主目录的删除操作，例如 `rm -rf /` 和 `rm -rf ~`，仍然会提示作为防止模型错误的断路器。仅在隔离环境（如容器、VM 或没有互联网访问的 dev containers）中使用此模式，其中 Claude Code 无法对您的主机系统造成损害。364`bypassPermissions` mode 禁用权限提示和安全检查，因此工具调用立即执行。从 v2.1.126 开始，这包括对[受保护路径](#protected-paths)的写入，早期版本仍然会提示。显式[询问规则](/zh-CN/permissions#manage-permissions)仍然会在此模式下强制提示，针对文件系统根目录或主目录的删除操作，例如 `rm -rf /` 和 `rm -rf ~`，仍然会提示作为防止模型错误的断路器。{/* min-version: 2.1.199 */}从 v2.1.199 开始，标记为 [`_meta["anthropic/requiresUserInteraction"]`](/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具也仍然会提示。仅在隔离环境（如容器、VM 或没有互联网访问的 dev containers）中使用此模式，其中 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 +2 −2

Details

352当你对插件进行更改时，运行 `/reload-plugins` 以获取更新，无需重新启动。这会重新加载 plugins、skills、agents、hooks、插件 MCP servers 和插件 LSP servers。测试你的插件组件：352当你对插件进行更改时，运行 `/reload-plugins` 以获取更新，无需重新启动。这会重新加载 plugins、skills、agents、hooks、插件 MCP servers 和插件 LSP servers。测试你的插件组件：

353 353

354* 使用 `/plugin-name:skill-name` 尝试你的 skills354* 使用 `/plugin-name:skill-name` 尝试你的 skills

355* 检查 agents 是否出现在 `/agents` 中355* 检查 agents 是否出现在 `/context` 中的 Custom Agents 下，或通过其作用域名称 @-mention 其中一个

356* 验证 hooks 是否按预期工作356* 验证 hooks 是否按预期工作

357 357

358<Tip>358<Tip>

502 claude --plugin-dir ./my-plugin502 claude --plugin-dir ./my-plugin

503 ```503 ```

504 504

505 测试每个组件：运行你的命令、检查 agents 是否出现在 `/agents` 中，并验证 hooks 是否正确触发。505 测试每个组件：运行你的命令、检查 agents 是否出现在 `/context` 中，并验证 hooks 是否正确触发。

506 </Step>506 </Step>

507</Steps>507</Steps>

508 508

plugins-reference.md +1 −1

Details

79 79

80**集成点**：80**集成点**：

81 81

~~82* Agents 出现在 `/agents` 界面中~~82* Agents 在 [@-mention 类型提前](/zh-CN/sub-agents#invoke-subagents-explicitly) 中显示，使用其作用域名称，例如 `my-plugin:code-reviewer`，一旦启用插件

83* Claude 可以根据任务上下文自动调用 agents83* Claude 可以根据任务上下文自动调用 agents

84* Agents 可以由用户手动调用84* 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-CN/settings#sandbox-path-prefixes)，来自每个 [settings scope](/zh-CN/settings#settings-precedence) 的条目被合并。因为唯一的模式是 `deny`，任何范围都可以添加限制，但没有任何范围可以删除它们。226文件条目仅支持 `"mode": "deny"`。环境变量条目也接受 `"mode": "mask"`，如下所述。

227

228文件路径遵循与 `sandbox.filesystem.*` 设置相同的 [prefix rules](/zh-CN/settings#sandbox-path-prefixes)，来自每个 [settings scope](/zh-CN/settings#settings-precedence) 的 `deny` 条目被合并。`deny` 条目只会缩小访问权限，因此任何范围都可以添加一个，但没有任何范围可以删除另一个范围添加的条目。

225 229

226没有内置的凭证拒绝列表，因此只有你列出的文件和变量被限制。该设置仅影响沙箱化的 Bash 命令。要从所有子进程中删除 Anthropic 和云提供商凭证，无论是否进行沙箱处理，请设置 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/zh-CN/env-vars)。230没有内置的凭证拒绝列表，因此只有你列出的文件和变量被限制。该设置仅影响沙箱化的 Bash 命令。要从所有子进程中删除 Anthropic 和云提供商凭证，无论是否进行沙箱处理，请设置 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/zh-CN/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-CN/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-CN/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)，如果你的威胁模型需要 TLS 检查，请参阅 [Custom proxy configuration](#custom-proxy-configuration)。296 内置代理基于请求的主机名强制执行允许列表，默认情况下不会终止或检查 TLS 流量。{/* min-version: 2.1.199 */}实验性的 [`network.tlsTerminate`](/zh-CN/settings#sandbox-settings) 设置在 Claude Code v2.1.199 及更高版本中可用，使内置代理自行终止 TLS，这是 [`mask` 凭证条目](#protect-credentials)所需的。有关默认设置的含义，请参阅 [Security limitations](#security-limitations)，如果你的威胁模型需要 TLS 检查，请参阅 [Custom proxy configuration](#custom-proxy-configuration)。

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-CN/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-CN/permissions)。479* **内置文件工具**：Read、Edit 和 Write 直接使用权限系统，而不是通过沙箱运行。请参阅 [permissions](/zh-CN/permissions)。

442* **计算机使用**：当 Claude 打开应用程序并控制你的屏幕时，它在你的实际桌面上运行，而不是在隔离的环境中。每个应用程序的权限提示控制每个应用程序。请参阅 [CLI 中的计算机使用](/zh-CN/computer-use) 或 [Desktop 中的计算机使用](/zh-CN/desktop#let-claude-use-your-computer)。480* **计算机使用**：当 Claude 打开应用程序并控制你的屏幕时，它在你的实际桌面上运行，而不是在隔离的环境中。每个应用程序的权限提示控制每个应用程序。请参阅 [CLI 中的计算机使用](/zh-CN/computer-use) 或 [Desktop 中的计算机使用](/zh-CN/desktop#let-claude-use-your-computer)。

443* **环境变量**：沙箱化 Bash 命令默认继承父进程环境，包括在那里设置的任何凭证。使用 [`sandbox.credentials`](#protect-credentials) 为沙箱化命令取消设置特定变量，或设置 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/zh-CN/env-vars) 以从所有子进程中删除 Anthropic 和云提供商凭证。481* **环境变量**：沙箱化 Bash 命令默认继承父进程环境，包括在那里设置的任何凭证。使用 [`sandbox.credentials`](#protect-credentials) 为沙箱化命令取消设置或掩盖特定变量，或设置 [`CLAUDE_CODE_SUBPROCESS_ENV_SCRUB`](/zh-CN/env-vars) 以从所有子进程中删除 Anthropic 和云提供商凭证。

444* **子代理**：[subagents](/zh-CN/sub-agents) 在与父会话相同的进程中运行，并使用相同的沙箱配置。当在父会话中启用沙箱时，子代理内的 Bash 命令被沙箱化。482* **子代理**：[subagents](/zh-CN/sub-agents) 在与父会话相同的进程中运行，并使用相同的沙箱配置。当在父会话中启用沙箱时，子代理内的 Bash 命令被沙箱化。

445 483

446<Warning>484<Warning>

server-managed-settings.md +26 −8

Details

153 153

154服务器管理的设置和[端点管理的设置](/zh-CN/settings#settings-files)都占据 Claude Code [设置层次结构](/zh-CN/settings#settings-precedence)中的最高层。没有其他设置级别可以覆盖它们，包括命令行参数。154服务器管理的设置和[端点管理的设置](/zh-CN/settings#settings-files)都占据 Claude Code [设置层次结构](/zh-CN/settings#settings-precedence)中的最高层。没有其他设置级别可以覆盖它们，包括命令行参数。

155 155

156在托管层内，配置的 [`policyHelper`](/zh-CN/settings#compute-managed-settings-with-a-policy-helper) 优先于所有其他托管源，包括服务器管理的设置：其输出成为该运行的唯一托管配置。否则，首先传递非空配置的源获胜。首先检查服务器管理的设置，然后检查端点管理的设置。源不合并：如果服务器管理的设置传递任何键，其他端点管理的设置将被完全忽略。有一个例外适用：当任何管理员控制的托管源设置一小组[跨源锁定键](/zh-CN/settings#settings-precedence)（例如沙箱允许列表锁）时，这些键会被遵守；用户可写的 HKCU 注册表层被排除。如果服务器管理的设置不传递任何内容，端点管理的设置将应用。156在托管层内，配置的 [`policyHelper`](/zh-CN/settings#compute-managed-settings-with-a-policy-helper) 优先于所有其他托管源，包括服务器管理的设置：其输出成为该运行的唯一托管配置。

157

158否则，Claude Code 使用首先传递非空配置的源。首先检查服务器管理的设置，然后检查端点管理的设置。源不合并：如果服务器管理的设置传递任何键，其他端点管理的设置将被完全忽略。如果服务器管理的设置不传递任何内容，端点管理的设置将应用。

159

160有一个例外适用：当任何管理员控制的托管源设置一小组[跨源锁定键](/zh-CN/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` 块中保留三类变量，直到服务器确认该会话的有效负载。这可以防止缓存的代理、证书颁发机构、端点或凭证值重定向、拦截或重新身份验证确认有效负载的设置获取。加固仅适用于服务器获取的设置缓存：通过 MDM 或 `managed-settings.json` 部署的[端点管理的设置](/zh-CN/settings#settings-files)不受影响。被保留的类别是：

183

184* 代理和 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如果您的组织需要代理来访问 `api.anthropic.com`，请在 shell 环境或[用户设置](/zh-CN/settings#settings-files)中设置它，而不仅仅在托管 `env` 块中。首次启动没有缓存，所以这些源已经是初始获取所必需的。

177 191

178Claude Code 自动应用设置更新而无需重新启动，除了高级设置（如 OpenTelemetry 配置）需要完全重新启动才能生效。192Claude Code 自动应用设置更新而无需重新启动，除了高级设置（如 OpenTelemetry 配置）需要完全重新启动才能生效。

179 193

207}221}

208```222```

209 223

210您也可以在[端点管理的](/zh-CN/settings#settings-files) MDM 配置文件或系统 `managed-settings.json` 文件中设置此键，以在首次启动时强制执行故障关闭行为，在任何服务器有效负载被传递之前。从 v2.1.191 开始，此标志是上述[优先级规则](#settings-precedence)的例外：当在任何托管源中设置时，即使也存在缓存的服务器管理有效负载，它也会被遵守，因此当服务器管理的设置存在时，MDM 传递的值不会被忽略。设置获取还发送 `Cache-Control: no-cache` 标头，以便中间 HTTP 代理不会提供陈旧的响应。224您也可以在[端点管理的](/zh-CN/settings#settings-files) MDM 配置文件或系统 `managed-settings.json` 文件中设置此键，以在首次启动时强制执行故障关闭行为，在任何服务器有效负载被传递之前。从 v2.1.191 开始，此标志是上述[优先级规则](#settings-precedence)的例外：当在任何托管源中设置时，即使也存在缓存的服务器管理有效负载，它也会被遵守，因此当服务器管理的设置存在时，MDM 传递的值不会被忽略。

225

226设置获取还发送 `Cache-Control: no-cache` 标头，以便中间 HTTP 代理不会提供陈旧的响应。

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-CN/settings#available-settings) 脚本返回的密钥不会触发设置获取。在使用第三方模型提供商时，服务器管理的设置不可用：253服务器管理的设置需要直接连接到 `api.anthropic.com`，并且交付需要会话使用组织 OAuth 登录或直接配置的 API 密钥进行身份验证。由 [`apiKeyHelper`](/zh-CN/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| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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 不可用 | 如果可用，缓存的设置应用，否则托管设置在下次成功获取前不被强制执行。从 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 开始，这也适用于 [compaction](/zh-CN/how-claude-code-works#when-context-fills-up) 之后；较早的版本会回退到字面名称 `Branched conversation`，而不是查看 compaction 摘要之外的原始第一个提示。

101

100从命令行，将 `--continue` 或 `--resume` 与 `--fork-session` 结合：102从命令行，将 `--continue` 或 `--resume` 与 `--fork-session` 结合：

101 103

102```bash theme={null}104```bash theme={null}

settings.md +18 −5

Details

262| `enableAllProjectMcpServers` | 自动批准项目 `.mcp.json` 文件中定义的所有 MCP servers。{/* min-version: 2.1.196 */}从 v2.1.196 开始，`claude mcp list` 和 `claude mcp get` 仅在[未检入存储库的设置文件](/zh-CN/mcp#managing-your-servers)中的不受信任的文件夹中尊重此键 | `true` |262| `enableAllProjectMcpServers` | 自动批准项目 `.mcp.json` 文件中定义的所有 MCP servers。{/* min-version: 2.1.196 */}从 v2.1.196 开始，`claude mcp list` 和 `claude mcp get` 仅在[未检入存储库的设置文件](/zh-CN/mcp#managing-your-servers)中的不受信任的文件夹中尊重此键 | `true` |

263| `enableArtifact` | {/* min-version: 2.1.196 */}为此用户启用或禁用 [Artifact](/zh-CN/artifacts) 工具。未设置时，默认遵循该功能对您账户的[可用性](/zh-CN/artifacts#availability)。`/config` 中的**Artifacts** 行写入此键。managed `disableArtifact` 和您的组织的[管理员设置](/zh-CN/artifacts#manage-artifacts-for-your-organization)优先，该键在项目和本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中被忽略，存储库可能会检入。需要 Claude Code v2.1.196 或更高版本 | `true` |263| `enableArtifact` | {/* min-version: 2.1.196 */}为此用户启用或禁用 [Artifact](/zh-CN/artifacts) 工具。未设置时，默认遵循该功能对您账户的[可用性](/zh-CN/artifacts#availability)。`/config` 中的**Artifacts** 行写入此键。managed `disableArtifact` 和您的组织的[管理员设置](/zh-CN/artifacts#manage-artifacts-for-your-organization)优先，该键在项目和本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中被忽略，存储库可能会检入。需要 Claude Code v2.1.196 或更高版本 | `true` |

264| `enabledMcpjsonServers` | 要批准的 `.mcp.json` 文件中特定 MCP servers 的列表。{/* min-version: 2.1.196 */}从 v2.1.196 开始，`claude mcp list` 和 `claude mcp get` 仅在[未检入存储库的设置文件](/zh-CN/mcp#managing-your-servers)中的不受信任的文件夹中尊重此键 | `["memory", "github"]` |264| `enabledMcpjsonServers` | 要批准的 `.mcp.json` 文件中特定 MCP servers 的列表。{/* min-version: 2.1.196 */}从 v2.1.196 开始，`claude mcp list` 和 `claude mcp get` 仅在[未检入存储库的设置文件](/zh-CN/mcp#managing-your-servers)中的不受信任的文件夹中尊重此键 | `["memory", "github"]` |

265| `enforceAvailableModels` | {/* min-version: 2.1.175 */}将 `availableModels` 允许列表扩展到默认模型。当在 managed 设置中为 `true` 且 `availableModels` 是非空数组时，默认选项回退到第一个可用的允许列表条目。当 `availableModels` 未设置或为空时无效。请参阅[为默认模型强制执行允许列表](/zh-CN/model-config#enforce-the-allowlist-for-the-default-model)。需要 Claude Code v2.1.175 或更高版本 | `true` |265| `enforceAvailableModels` | {/* min-version: 2.1.175 */}将 `availableModels` 允许列表扩展到默认模型。当在 managed 设置中为 `true` 且 `availableModels` 是非空数组时，默认选项回退到第一个可用的允许列表条目，但仅当默认模型会解析为的模型（当应用[组织默认](/zh-CN/model-config#organization-default-model)时，否则账户类型默认）不在允许列表中时；允许列表默认保持原样。当 `availableModels` 未设置或为空时无效。请参阅[为默认模型强制执行允许列表](/zh-CN/model-config#enforce-the-allowlist-for-the-default-model)。需要 Claude Code v2.1.175 或更高版本 | `true` |

266| `env` | 应用于每个会话和 Claude Code 从其生成的子进程的环境变量。{/* min-version: 2.1.143 */}从 v2.1.143 开始，此处设置的 `NO_COLOR` 和 `FORCE_COLOR` 被传递到子进程，但不改变 Claude Code 自己的界面颜色。在启动 `claude` 前在您的 shell 中设置这些以改变界面颜色。{/* min-version: 2.1.195 */}从 v2.1.195 开始，Claude Code 的托管环境设置的身份变量，例如 `CLAUDE_CODE_REMOTE` 和 `CLAUDE_CODE_ACCOUNT_UUID`，在此处设置时被忽略 | `{"FOO": "bar"}` |266| `env` | 应用于每个会话和 Claude Code 从其生成的子进程的环境变量。{/* min-version: 2.1.143 */}从 v2.1.143 开始，此处设置的 `NO_COLOR` 和 `FORCE_COLOR` 被传递到子进程，但不改变 Claude Code 自己的界面颜色。在启动 `claude` 前在您的 shell 中设置这些以改变界面颜色。{/* min-version: 2.1.195 */}从 v2.1.195 开始，Claude Code 的托管环境设置的身份变量，例如 `CLAUDE_CODE_REMOTE` 和 `CLAUDE_CODE_ACCOUNT_UUID`，在此处设置时被忽略 | `{"FOO": "bar"}` |

267| `fallbackModel` | 当主模型过载或不可用时按顺序尝试的备用模型。Claude Code 为该轮的其余部分切换到链中的下一个可用模型并显示通知。`"default"` 扩展为默认模型。链限制为三个模型；额外条目被忽略。与大多数数组设置不同，此键不跨设置文件合并：定义它的最高优先级文件提供整个链。[`--fallback-model`](/zh-CN/cli-reference#cli-flags) 标志覆盖此用于一个会话。请参阅[备用模型链](/zh-CN/model-config#fallback-model-chains) | `["claude-sonnet-5", "claude-haiku-4-5"]` |267| `fallbackModel` | 当主模型过载或不可用时按顺序尝试的备用模型。Claude Code 为该轮的其余部分切换到链中的下一个可用模型并显示通知。`"default"` 扩展为默认模型。链限制为三个模型；额外条目被忽略。与大多数数组设置不同，此键不跨设置文件合并：定义它的最高优先级文件提供整个链。[`--fallback-model`](/zh-CN/cli-reference#cli-flags) 标志覆盖此用于一个会话。请参阅[备用模型链](/zh-CN/model-config#fallback-model-chains) | `["claude-sonnet-5", "claude-haiku-4-5"]` |

268| `fastModePerSessionOptIn` | 当为 `true` 时，快速模式不会跨会话持久化。每个会话都以快速模式关闭开始，需要用户使用 `/fast` 启用它。用户的快速模式偏好仍被保存。请参阅[需要每个会话的选择加入](/zh-CN/fast-mode#require-per-session-opt-in) | `true` |268| `fastModePerSessionOptIn` | 当为 `true` 时，快速模式不会跨会话持久化。每个会话都以快速模式关闭开始，需要用户使用 `/fast` 启用它。用户的快速模式偏好仍被保存。请参阅[需要每个会话的选择加入](/zh-CN/fast-mode#require-per-session-opt-in) | `true` |

398配置高级 sandboxing 行为。Sandboxing 将 bash 命令与您的文件系统和网络隔离。请参阅 [Sandboxing](/zh-CN/sandboxing) 了解详情。398配置高级 sandboxing 行为。Sandboxing 将 bash 命令与您的文件系统和网络隔离。请参阅 [Sandboxing](/zh-CN/sandboxing) 了解详情。

399 399

400| 键 | 描述 | 示例 |400| 键 | 描述 | 示例 |

401| :------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |401| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |

403| `failIfUnavailable` | 如果 `sandbox.enabled` 为 true 但 sandbox 无法启动（缺少依赖项或不支持的平台），则在启动时以错误退出。当为 false（默认）时，显示警告，命令无 sandbox 运行。用于需要 sandboxing 作为硬门的 managed 设置部署 | `true` |403| `failIfUnavailable` | 如果 `sandbox.enabled` 为 true 但 sandbox 无法启动（缺少依赖项或不支持的平台），则在启动时以错误退出。当为 false（默认）时，显示警告，命令无 sandbox 运行。用于需要 sandboxing 作为硬门的 managed 设置部署 | `true` |

410| `filesystem.allowRead` | 在 `denyRead` 区域内重新允许读取的路径。优先于 `denyRead`。数组跨所有设置作用域合并。使用此创建仅工作区读取访问模式。 | `["."]` |410| `filesystem.allowRead` | 在 `denyRead` 区域内重新允许读取的路径。优先于 `denyRead`。数组跨所有设置作用域合并。使用此创建仅工作区读取访问模式。 | `["."]` |

412| `credentials.files` | Credential 文件或目录，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 */}Credential 文件或目录，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-CN/sandboxing#protect-credentials)的环境变量。每个条目有一个 `name` 和一个 `mode`；名称必须以字母或下划线开头，仅包含字母、数字和下划线。`deny` 从 sandboxed 命令的环境中删除变量。需要 Claude Code v2.1.187 或更高版本。{/* min-version: 2.1.199 */}}`mask` 在 sandbox 内用每个会话的哨兵值替换变量，同时 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| `credentials.envVars[].injectHosts` | sandbox 代理替换 `mask` 条目真实值的主机。每个主机也必须由 `network.allowedDomains` 覆盖，要么完全要么通过通配符。未设置时，代理在对 `network.allowedDomains` 中每个主机的请求上替换值。当 `mode` 为 `deny` 时被接受但忽略。需要 Claude Code v2.1.199 或更高版本。{/* min-version: 2.1.199 */}} | `["api.github.com"]` |

415| `credentials.allowPlaintextInject` | 允许 `mask` 替换在纯 HTTP 请求以及 TLS 终止的 HTTPS 上。在纯 HTTP 上上游身份未验证，凭证以明文形式传输，因此在受信任的测试网络外保持此关闭。仅从用户、managed 或 CLI `--settings` 设置受尊重，不从 `.claude/settings.json` 或 `.claude/settings.local.json`。默认：false。需要 Claude Code v2.1.199 或更高版本。{/* min-version: 2.1.199 */}} | `true` |

414| `network.allowUnixSockets` | （仅 macOS）sandbox 中可访问的 Unix socket 路径。在 Linux 和 WSL2 上被忽略，其中 seccomp 过滤器无法检查 socket 路径；改用 `allowAllUnixSockets`。 | `["~/.ssh/agent-socket"]` |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` |

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` |

425| `network.tlsTerminate` | 实验性。在 sandbox 代理内终止 TLS，以便它可以读取 HTTPS 请求的内容。[凭证替换](/zh-CN/sandboxing#protect-credentials)的 `mask` 需要。设置 `{}` 以为会话生成临时证书颁发机构，或设置 `caCertPath` 和 `caKeyPath` 以使用您自己的。仅从用户、managed 或 CLI `--settings` 设置受尊重，不从 `.claude/settings.json` 或 `.claude/settings.local.json`。需要 Claude Code v2.1.199 或更高版本。{/* min-version: 2.1.199 */}} | `{}` |

424| `enableWeakerNetworkIsolation` | （仅 macOS）允许在 sandbox 中访问系统 TLS 信任服务（`com.apple.trustd.agent`）。对于 Go 基础工具（如 `gh`、`gcloud` 和 `terraform`）在使用 `httpProxyPort` 与 MITM 代理和自定义 CA 时验证 TLS 证书是必需的。**通过打开潜在的数据泄露路径降低安全性**。默认：false | `true` |427| `enableWeakerNetworkIsolation` | （仅 macOS）允许在 sandbox 中访问系统 TLS 信任服务（`com.apple.trustd.agent`）。对于 Go 基础工具（如 `gh`、`gcloud` 和 `terraform`）在使用 `httpProxyPort` 与 MITM 代理和自定义 CA 时验证 TLS 证书是必需的。**通过打开潜在的数据泄露路径降低安全性**。默认：false | `true` |

425| `allowAppleEvents` | （仅 macOS）允许 sandboxed 命令发送 Apple Events。对于 `open`、`osascript` 和在浏览器中打开 URL 的工具是必需的，否则会失败并显示错误 `-600`。**删除代码执行隔离。** Sandboxed 命令可以无用户提示地启动其他应用程序无 sandbox；它们也可以向运行的应用程序（如 Terminal）发送 AppleScript 命令，受每个应用程序 macOS 自动化同意提示（TCC）的约束。仅从用户、managed 或 CLI 设置受尊重，不从项目设置。默认：false | `true` |428| `allowAppleEvents` | （仅 macOS）允许 sandboxed 命令发送 Apple Events。对于 `open`、`osascript` 和在浏览器中打开 URL 的工具是必需的，否则会失败并显示错误 `-600`。**删除代码执行隔离。** Sandboxed 命令可以无用户提示地启动其他应用程序无 sandbox；它们也可以向运行的应用程序（如 Terminal）发送 AppleScript 命令，受每个应用程序 macOS 自动化同意提示（TCC）的约束。仅从用户、managed 或 CLI 设置受尊重，不从项目设置。默认：false | `true` |

6601. **Managed 设置**（[服务器管理](/zh-CN/server-managed-settings)、[MDM/OS 级别策略](#configuration-scopes) 或 [managed 设置](#settings-files)）6631. **Managed 设置**（[服务器管理](/zh-CN/server-managed-settings)、[MDM/OS 级别策略](#configuration-scopes) 或 [managed 设置](#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-CN/server-managed-settings)或 [Claude apps gateway](/zh-CN/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 层内，仅使用一个源，其他源被忽略而不是合并。优先级，从最高到最低：

667 * [`policyHelper`](#compute-managed-settings-with-a-policy-helper) 输出：当配置时，这是唯一使用的 managed 源

668 * 远程（claude.ai [服务器管理](/zh-CN/server-managed-settings) 或 [Claude apps gateway](/zh-CN/claude-apps-gateway) 交付）

669 * MDM/OS 级别策略

670 * 基于文件（`managed-settings.d/*.json` 和 `managed-settings.json`，合并在一起）

671 * HKCU 注册表（仅 Windows）

672 * 少数几个键是例外，当任何管理员控制的 managed 源设置它们时被尊重，而不仅仅是获胜的源。用户可写的 HKCU 注册表源被排除。例外键是：

673 * sandbox 锁定键 `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly`，带有其关联的允许列表

674 * `allowAllClaudeAiMcps`

675 * sandbox 二进制路径 `sandbox.bwrapPath` 和 `sandbox.socatPath`

676 * [`forceRemoteSettingsRefresh`](/zh-CN/server-managed-settings)

664 * 嵌入主机（如 Claude Desktop）可以通过 SDK `managedSettings` 选项提供策略。默认情况下，当存在任何管理员部署的 managed 源时，这被忽略：服务器管理的设置、MDM 或 OS 级别策略或 managed 设置文件。用户可写的 HKCU 注册表回退不计为管理员部署的源。管理员可以通过将 [`parentSettingsBehavior`](#available-settings) 设置为 `"merge"` 来选择加入。嵌入器的值被筛选，以便它们可以收紧 managed 策略但不能放松它。677 * 嵌入主机（如 Claude Desktop）可以通过 SDK `managedSettings` 选项提供策略。默认情况下，当存在任何管理员部署的 managed 源时，这被忽略：服务器管理的设置、MDM 或 OS 级别策略或 managed 设置文件。用户可写的 HKCU 注册表回退不计为管理员部署的源。管理员可以通过将 [`parentSettingsBehavior`](#available-settings) 设置为 `"merge"` 来选择加入。嵌入器的值被筛选，以便它们可以收紧 managed 策略但不能放松它。

665 678

6662. **命令行参数**6792. **命令行参数**

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 +12 −0

Details

181 来自 `--add-dir` 目录的 CLAUDE.md 文件默认不加载。要加载它们，请设置 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`。请参阅[从其他目录加载](/zh-CN/memory#load-from-additional-directories)。181 来自 `--add-dir` 目录的 CLAUDE.md 文件默认不加载。要加载它们，请设置 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`。请参阅[从其他目录加载](/zh-CN/memory#load-from-additional-directories)。

182</Note>182</Note>

183 183

184***

185

186title: "配置 skills"

187description: "通过 YAML frontmatter 和 markdown 内容配置 skills，包括 frontmatter 参考、字符串替换和工具权限。"

188---------------------------------------------------------------------------------------

189

184<h2 id="configure-skills">190<h2 id="configure-skills">

185 配置 skills191 配置 skills

186</h2>192</h2>

443 449

444如果你使用参数调用 skill 但 skill 不包含 `$ARGUMENTS`，Claude Code 会将 `ARGUMENTS: <your input>` 追加到 skill 内容的末尾，以便 Claude 仍然看到你输入的内容。450如果你使用参数调用 skill 但 skill 不包含 `$ARGUMENTS`，Claude Code 会将 `ARGUMENTS: <your input>` 追加到 skill 内容的末尾，以便 Claude 仍然看到你输入的内容。

445 451

452你也可以在一条消息的开头堆叠多个 skills。从 v2.1.199 开始，输入 `/code-review /fix-issue 123` 会加载两个 skills 并将尾部文本 `123` 作为 `$ARGUMENTS` 传递给每个 skills。在早期版本中，只有第一个 skill 加载并接收 `/fix-issue 123` 作为文字参数文本。

453

454Claude Code 扩展第一个 skill 加上最多五个堆叠在其后的 skills。扩展在第一个不是内联用户可调用 skill 的令牌处停止，因此作为[分叉 subagent](#run-skills-in-a-subagent) 运行的 skill 或其参数本身可能以斜杠命令开头的 skill（如 `/loop`）也会在那里结束；该令牌及其后的所有内容成为每个扩展 skill 的参数文本。

455

446要按位置访问单个参数，使用 `$ARGUMENTS[N]` 或较短的 `$N`：456要按位置访问单个参数，使用 `$ARGUMENTS[N]` 或较短的 `$N`：

447 457

448```yaml theme={null}458```yaml theme={null}

624| `"user-invocable-only"` | 隐藏 | 是 |634| `"user-invocable-only"` | 隐藏 | 是 |

625| `"off"` | 隐藏 | 隐藏 |635| `"off"` | 隐藏 | 隐藏 |

626 636

637从 v2.1.199 开始，`"off"` 也会从广告给 [Remote Control](/zh-CN/remote-control) 客户端和 [Agent SDK](/zh-CN/agent-sdk/slash-commands) 调用者的命令列表中隐藏该 skill，而不仅仅是终端 `/` 菜单。按其全名调用隐藏的 skill 仍然返回 `skillOverrides` 错误而不是运行它。

638

627`skillOverrides` 中不存在的 skill 被视为 `"on"`。下面的示例将一个 skill 折叠为其名称，并完全关闭另一个：639`skillOverrides` 中不存在的 skill 被视为 `"on"`。下面的示例将一个 skill 折叠为其名称，并完全关闭另一个：

628 640

629```json theme={null}641```json theme={null}

sub-agents.md +84 −64

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 和 Edit42 * **Tools**: 只读工具；拒绝访问 Write 和 Edit

43 * **Purpose**: 文件发现、代码搜索、代码库探索43 * **Purpose**: 文件发现、代码搜索、代码库探索

44 44

45 {/* min-version: 2.1.198 */}从 v2.1.198 开始，Explore 继承主对话的模型，而不是始终在 Haiku 上运行。在 Claude API 上，继承的模型限制为 Opus：主对话在更高层级上运行 Explore 时使用 Opus，主对话在 Sonnet 或 Haiku 上运行 Explore 时使用相同的模型。在任何其他提供商上，例如 [Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform](/zh-CN/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-CN/permissions#tool-specific-permission-rules) 拒绝 `Agent` 工具本身。87* 要防止 Claude 委托给任何 subagent，请使用 [`permissions.deny`](/zh-CN/permissions#tool-specific-permission-rules) 拒绝 `Agent` 工具本身。

88* {/* min-version: 2.1.198 */}要仅移除内置的 `Explore` 和 `Plan` subagents，请设置 [`CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1`](/zh-CN/env-vars)。Claude 直接读取和探索文件，而不是委托给它们。需要 Claude Code v2.1.198 或更高版本。

84* 在[非交互模式](/zh-CN/headless) 和 [Agent SDK](/zh-CN/agent-sdk/overview) 中，设置 [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/zh-CN/env-vars) 以移除所有内置类型并仅提供您自己的。89* 在[非交互模式](/zh-CN/headless) 和 [Agent SDK](/zh-CN/agent-sdk/overview) 中，设置 [`CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1`](/zh-CN/env-vars) 以移除所有内置类型并仅提供您自己的。

85 90

86除了这些内置 subagents，您可以创建自己的，具有自定义提示、工具限制、权限模式、hooks 和 skills。以下部分展示了如何开始和自定义 subagents。91除了这些内置 subagents，您可以创建自己的，具有自定义提示、工具限制、权限模式、hooks 和 skills。以下部分展示了如何开始和自定义 subagents。

89 快速入门：创建您的第一个 subagent94 快速入门：创建您的第一个 subagent

90</h2>95</h2>

91 96

~~92Subagents 在带有 YAML frontmatter 的 Markdown 文件中定义。您可以 [手动创建它们](#write-subagent-files) 或使用 `/agents` 命令。~~97Subagents 是带有 YAML frontmatter 的 Markdown 文件。要创建一个，请要求 Claude 为您编写，或者 [自己编写文件](#write-subagent-files)。

99{/* min-version: 2.1.198 */}从 v2.1.198 开始，`/agents` 命令不再打开交互式创建向导；运行它会打印一个提醒，要求您询问 Claude 或直接编辑 `.claude/agents/`。Subagent 文件、frontmatter 字段以及 `.claude/agents/` 和 `~/.claude/agents/` 位置保持不变；仅删除了终端向导。

93 100

~~94本演练指导您使用 `/agents` 命令创建用户级 subagent。该 subagent 审查代码并为代码库建议改进。~~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>

~~120~~

121 <Step title="选择工具">

122 对于只读审查者，取消选择除 **Read-only tools** 之外的所有内容。如果您保持所有工具被选中，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>133 </Step>

136 134

137 <Step title="保存并尝试">135 <Step title="尝试一下">

138 查看配置摘要。按 `s` 或 `Enter` 保存，或按 `e` 在编辑器中保存并编辑文件。Subagent 立即可用。尝试它：136 要求 Claude 委托给新的 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 标志定义它们，或通过 plugins 分发它们。以下部分涵盖所有配置选项。150您也可以手动编写 subagent 文件、通过 CLI 标志定义它们，或通过 plugins 分发它们。以下部分涵盖所有配置选项。

151

152<Note>

153 在 Claude Code v2.1.197 及更早版本中，`/agents` 打开一个交互式向导，其中有一个 **Running** 选项卡列出实时 subagents，以及一个 **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">160一个 subagent 的文件位置决定了谁可以使用它，其 frontmatter 决定了它可以做什么。本节涵盖 subagent 文件的位置以及它们支持的每个字段。

157 使用 /agents 命令

158</h3>

~~159~~

160`/agents` 命令打开一个选项卡式界面来管理 subagents。**Running** 选项卡列出实时和最近完成的 subagents，让您打开或停止它们。**Library** 选项卡让您：

~~161~~

162* 查看所有可用的 subagents（内置、用户、项目和 plugin）

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-CN/settings) 部署 |170| 托管设置 | 组织范围 | 1（最高） | 通过 [managed settings](/zh-CN/settings) 部署 |

183 175

184**项目 subagents**（`.claude/agents/`）非常适合特定于代码库的 subagents。将它们检入版本控制，以便您的团队可以协作使用和改进它们。176**项目 subagents**（`.claude/agents/`）非常适合特定于代码库的 subagents。将它们检入版本控制，以便您的团队可以协作使用和改进它们。

239 231

240**托管 subagents** 由组织管理员部署。在 [managed settings directory](/zh-CN/settings#settings-files) 内的 `.claude/agents/` 中放置 markdown 文件，使用与项目和用户 subagents 相同的 frontmatter 格式。托管定义优先于具有相同名称的项目和用户 subagents。232**托管 subagents** 由组织管理员部署。在 [managed settings directory](/zh-CN/settings#settings-files) 内的 `.claude/agents/` 中放置 markdown 文件，使用与项目和用户 subagents 相同的 frontmatter 格式。托管定义优先于具有相同名称的项目和用户 subagents。

241 233

242**Plugin subagents** 来自您已安装的 [plugins](/zh-CN/plugins)。它们与您的自定义 subagents 一起出现在 `/agents` 中。有关创建 plugin subagents 的详细信息，请参阅 [plugin 组件参考](/zh-CN/plugins-reference#agents)。234**Plugin subagents** 来自您已安装的 [plugins](/zh-CN/plugins)。它们与您的自定义 subagents 一起加载，并在 @-mention 类型提前中以其范围名称出现。有关创建 plugin subagents 的详细信息，请参阅 [plugin 组件参考](/zh-CN/plugins-reference#agents)。

243 235

244<Note>236<Note>

245 出于安全原因，plugin subagents 不支持 `hooks`、`mcpServers` 或 `permissionMode` frontmatter 字段。加载来自 plugin 的代理时，这些字段被忽略。如果您需要它们，请将代理文件复制到 `.claude/agents/` 或 `~/.claude/agents/`。您也可以在 `settings.json` 或 `settings.local.json` 中向 [`permissions.allow`](/zh-CN/settings#permission-settings) 添加规则，但这些规则适用于整个会话，而不仅仅是 plugin subagent。237 出于安全原因，plugin subagents 不支持 `hooks`、`mcpServers` 或 `permissionMode` frontmatter 字段。加载来自 plugin 的代理时，这些字段被忽略。如果您需要它们，请将代理文件复制到 `.claude/agents/` 或 `~/.claude/agents/`。您也可以在 `settings.json` 或 `settings.local.json` 中向 [`permissions.allow`](/zh-CN/settings#permission-settings) 添加规则，但这些规则适用于整个会话，而不仅仅是 plugin 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-CN/mcp) 对此 subagent 可用。每个条目要么是引用已配置服务器的服务器名称（例如，`"slack"`），要么是内联定义，其中服务器名称为键，完整的 [MCP server config](/zh-CN/mcp#installing-mcp-servers) 为值。对于 [plugin subagents](#choose-the-subagent-scope) 被忽略 |289| `mcpServers` | 否 | [MCP servers](/zh-CN/mcp) 对此 subagent 可用。每个条目要么是引用已配置服务器的服务器名称（例如，`"slack"`），要么是内联定义，其中服务器名称为键，完整的 [MCP server config](/zh-CN/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-CN/worktrees) 中运行 subagent，为其提供存储库的隔离副本，默认从您的 [default branch](/zh-CN/worktrees#choose-the-base-branch) 分支，而不是父会话的 `HEAD`。如果 subagent 不进行任何更改，worktree 会自动清理 |294| `isolation` | 否 | 设置为 `worktree` 以在临时 [git worktree](/zh-CN/worktrees) 中运行 subagent，为其提供存储库的隔离副本，默认从您的 [default branch](/zh-CN/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-CN/model-config#restrict-model-selection) 允许列表进行检查。解析为排除模型的值不会被使用，subagent 会改为在继承的模型上运行。318环境变量、每次调用的参数和 frontmatter 值会根据您组织的 [`availableModels`](/zh-CN/model-config#restrict-model-selection) 允许列表进行检查。解析为排除模型的值不会被使用，subagent 会改为在继承的模型上运行。

322 319

320{/* min-version: 2.1.198 */}从 v2.1.198 开始，subagents 也继承主对话的 [extended thinking](/zh-CN/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 文件中包含内存说明，以便它主动维护自己的知识库：

774* **前台 subagents** 阻塞主对话直到完成。权限提示会在出现时传递给您。773* **前台 subagents** 阻塞主对话直到完成。权限提示会在出现时传递给您。

775* **后台 subagents** 在您继续工作时并发运行。{/* min-version: 2.1.186 */}从 v2.1.186 开始，当后台 subagent 到达需要权限的工具调用时，提示会在您的主会话中显示，并命名正在请求的 subagent。批准以让 subagent 继续，或按 Esc 拒绝该单个工具调用而不停止 subagent。在 v2.1.186 之前，后台 subagents 自动拒绝任何会提示的工具调用。774* **后台 subagents** 在您继续工作时并发运行。{/* min-version: 2.1.186 */}从 v2.1.186 开始，当后台 subagent 到达需要权限的工具调用时，提示会在您的主会话中显示，并命名正在请求的 subagent。批准以让 subagent 继续，或按 Esc 拒绝该单个工具调用而不停止 subagent。在 v2.1.186 之前，后台 subagents 自动拒绝任何会提示的工具调用。

776 775

777Claude 根据任务决定是否在前台或后台运行 subagents。您也可以：776{/* min-version: 2.1.198 */}从 v2.1.198 开始，subagents 默认在后台运行。Claude 在需要结果才能继续时在前台运行 subagent。默认值改变 subagent 运行的位置，而不是它被允许做什么：后台 subagents 仍然在您的主会话中显示每个权限提示。在 v2.1.198 之前，Claude 根据任务在前台和后台之间选择。

778 777

779* 要求 Claude "run this in the background"778您也可以自己控制这个：

779

780* 要求 Claude 在后台或前台运行任务

780* 按 **Ctrl+B** 将运行中的任务放在后台781* 按 **Ctrl+B** 将运行中的任务放在后台

781 782

782要禁用所有后台任务功能，请将 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 环境变量设置为 `1`。请参阅 [Environment variables](/zh-CN/env-vars)。783要禁用所有后台任务功能，请将 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 环境变量设置为 `1`。请参阅 [Environment variables](/zh-CN/env-vars)。

783 784

784当 [`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation) 设置为 `1` 时，每个 subagent 生成都在后台运行，无论 `background` 字段如何。这些后台 subagents 的权限提示会在您的主会话中显示，如上所述。785当 [`CLAUDE_CODE_FORK_SUBAGENT`](#fork-the-current-conversation) 设置为 `1` 时，每个 subagent 生成都在后台运行，frontmatter `background` 字段无效，因为 fork 模式从 `Agent` 工具中移除了 `run_in_background` 参数。`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 优先于 fork 模式，并将 subagent 生成保持在前台。

786

787<h3 id="api-errors-in-subagents">

788 Subagents 中的 API 错误

789</h3>

790

791{/* min-version: 2.1.199 */}从 v2.1.199 开始，subagent 的运行因 API 错误（例如使用限制或重复的服务器错误）而结束时，会向 Claude 报告该失败，而不是返回错误文本，就像它是 subagent 的发现一样。Claude 接收的内容取决于 subagent 运行的位置：

792

793* **前台**：如果速率限制、过载或服务器错误切断已经产生输出的 subagent，Agent 工具返回该部分输出，并注明 subagent 被切断且未完成其任务。否则工具调用失败，出现 [`Agent terminated early due to an API error`](/zh-CN/errors#agent-terminated-early-due-to-an-api-error)，后跟错误详情。

794* **后台**：subagent 被标记为失败，Claude 在其结束时接收的消息命名 API 错误并包括 subagent 的最后输出，所以部分工作不会丢失。

795

796一旦底层 API 错误清除，要求 Claude 重试任务或 [恢复 subagent](#resume-subagents)。

785 797

786<h3 id="common-patterns">798<h3 id="common-patterns">

787 常见模式799 常见模式

852 864

853{/* min-version: 2.1.172 */}从 Claude Code v2.1.172 开始，subagent 可以生成自己的 subagents。当委托的任务本身分裂成并行子任务时使用这个，例如审查者 subagent 为每个发现分派一个验证者，所以中间输出永远不会到达您的主对话。只有顶级 subagent 的摘要返回给您。865{/* min-version: 2.1.172 */}从 Claude Code v2.1.172 开始，subagent 可以生成自己的 subagents。当委托的任务本身分裂成并行子任务时使用这个，例如审查者 subagent 为每个发现分派一个验证者，所以中间输出永远不会到达您的主对话。只有顶级 subagent 的摘要返回给您。

854 866

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 列为平面列表。867嵌套 subagent 的配置方式与顶级 subagent 相同，并从相同的 [scopes](#choose-the-subagent-scope) 解析。

856 868

857深度计算为主对话下方的 subagent 级别数，无论每个级别是否在 [前台或后台](#run-subagents-in-foreground-or-background) 运行。深度为五的 subagent 不接收 Agent 工具，无法进一步生成。限制是固定的且不可配置。869深度计算为主对话下方的 subagent 级别数，无论每个级别是否在 [前台或后台](#run-subagents-in-foreground-or-background) 运行。深度为五的 subagent 不接收 Agent 工具，无法进一步生成。限制是固定的且不可配置。

858 870

892 904

893恢复的 subagents 保留其完整的对话历史，包括所有以前的工具调用、结果和推理。Subagent 从它停止的地方继续，而不是从头开始。905恢复的 subagents 保留其完整的对话历史，包括所有以前的工具调用、结果和推理。Subagent 从它停止的地方继续，而不是从头开始。

894 906

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-CN/agent-teams)。907当 subagent 完成时，Claude 接收其代理 ID。内置的 Explore 和 Plan 代理是一次性的，不返回代理 ID，所以它们无法恢复；当您需要继续工作时，使用 `general-purpose` 或自定义 subagent。

908

909Claude 使用 `SendMessage` 工具，将代理的 ID 或名称作为 `to` 字段来恢复它。`SendMessage` 不需要启用 [agent teams](/zh-CN/agent-teams)；只有结构化的团队协议消息，例如 `shutdown_request` 和 `plan_approval_response`，才需要启用。

896 910

897要恢复 subagent，要求 Claude 继续之前的工作：911要恢复 subagent，要求 Claude 继续之前的工作：

898 912

906 920

907如果停止的 subagent 接收 `SendMessage`，它会在后台自动恢复，无需新的 `Agent` 调用。921如果停止的 subagent 接收 `SendMessage`，它会在后台自动恢复，无需新的 `Agent` 调用。

908 922

923{/* min-version: 2.1.199 */}从 v2.1.199 开始，`SendMessage` 检查名称是否仍然指向它在对话中早期到达的同一代理。如果较新的代理已经采用了该名称，例如重新生成的后台代理重新使用了它，Claude Code 会拒绝发送，而不是将其传递给错误的代理，错误会报告该名称现在到达的代理，以便 Claude 可以重新定向。要在它仍在运行时到达早期的代理，Claude 通过其生成结果中的代理 ID 来寻址它。检查的范围是当前对话，并在 `/clear` 时重置。

924

925{/* min-version: 2.1.198 */}从 v2.1.198 开始，subagent 将来自启动它的代理的消息视为正常任务方向，包括中途任务方向更正，并在其自己的权限设置内对其进行操作。无论谁发送消息，两个限制仍然成立：来自任何代理的消息都不计为您对待处理权限提示的批准，任何代理消息都无法改变 subagent 的权限设置、`CLAUDE.md` 或配置。只有权限系统或您自己的消息可以授予批准。

926

909您也可以要求 Claude 提供代理 ID，如果您想明确引用它，或在 `~/.claude/projects/{project}/{sessionId}/subagents/` 的转录文件中找到 ID。每个转录存储为 `agent-{agentId}.jsonl`。927您也可以要求 Claude 提供代理 ID，如果您想明确引用它，或在 `~/.claude/projects/{project}/{sessionId}/subagents/` 的转录文件中找到 ID。每个转录存储为 `agent-{agentId}.jsonl`。

910 928

911Subagent 转录独立于主对话持久化：929Subagent 转录独立于主对话持久化：

912 930

913* **主对话压缩**：当主对话压缩时，subagent 转录不受影响。它们存储在单独的文件中。931* **主对话压缩**：当主对话压缩时，subagent 转录不受影响。它们存储在单独的文件中。

914* **会话持久性**：Subagent 转录在其会话中持久化。您可以通过恢复相同的会话在重启 Claude Code 后 [恢复 subagent](#resume-subagents)。932* **会话持久性**：Subagent 转录在其会话中持久化。您可以通过恢复相同的会话在重启 Claude Code 后 [恢复 subagent](#resume-subagents)。

915* **自动清理**：转录根据 `cleanupPeriodDays` 设置（默认：30 天）进行清理。933* **自动清理**：转录根据 `cleanupPeriodDays` 设置（默认为 30 天）进行清理。

916 934

917<h4 id="auto-compaction">935<h4 id="auto-compaction">

918 自动压缩936 自动压缩

973| `x` | 关闭完成的分叉或停止运行中的分叉 |991| `x` | 关闭完成的分叉或停止运行中的分叉 |

974| `Esc` | 将焦点返回到提示输入 |992| `Esc` | 将焦点返回到提示输入 |

975 993

994打开分叉或 subagent 的转录后，后续消息和 [skills](/zh-CN/skills) 会发送到该代理，但内置命令仍在您的主对话中运行。{/* min-version: 2.1.199 */}从 v2.1.199 开始，在该视图中键入 `/model` 或 `/fast` 会显示一条通知，说明它改变主对话的模型或快速模式，而不是所查看代理的，而不是静默运行它。

995

976<h3 id="how-forks-differ-from-named-subagents">996<h3 id="how-forks-differ-from-named-subagents">

977 分叉与命名 subagents 的区别997 分叉与命名 subagents 的区别

978</h3>998</h3>

third-party-integrations.md +1 −1

Details

196 196

197* [Claude for Teams 或 Enterprise](/zh-CN/authentication#claude-for-teams-or-enterprise)197* [Claude for Teams 或 Enterprise](/zh-CN/authentication#claude-for-teams-or-enterprise)

198* [Anthropic Console](/zh-CN/authentication#claude-console-authentication)198* [Anthropic Console](/zh-CN/authentication#claude-console-authentication)

199* [Claude 应用网关](/zh-CN/claude-apps-gateway)，一个自托管网关，在 Amazon Bedrock、Google Vertex AI、Microsoft Foundry 或 Anthropic API 前面添加 IdP 登录199* [Claude 应用网关](/zh-CN/claude-apps-gateway)，一个自托管网关，在 Amazon Bedrock、Claude Platform on AWS、Google Vertex AI、Microsoft Foundry 或 Anthropic API 前面添加 IdP 登录

200* [Amazon Bedrock](/zh-CN/amazon-bedrock)200* [Amazon Bedrock](/zh-CN/amazon-bedrock)

201* [Claude Platform on AWS](/zh-CN/claude-platform-on-aws)201* [Claude Platform on AWS](/zh-CN/claude-platform-on-aws)

202* [Google Vertex AI](/zh-CN/google-vertex-ai)202* [Google Vertex AI](/zh-CN/google-vertex-ai)

tools-reference.md +20 −12

Details

11要添加自定义工具，请连接一个 [MCP server](/zh-CN/mcp)。要使用可重用的基于提示的工作流扩展 Claude，请编写一个 [skill](/zh-CN/skills)，它通过现有的 `Skill` 工具运行，而不是添加新的工具条目。11要添加自定义工具，请连接一个 [MCP server](/zh-CN/mcp)。要使用可重用的基于提示的工作流扩展 Claude，请编写一个 [skill](/zh-CN/skills)，它通过现有的 `Skill` 工具运行，而不是添加新的工具条目。

12 12

13| 工具 | 描述 | 需要权限 |13| 工具 | 描述 | 需要权限 |

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

15| `Agent` | 生成一个具有自己 context window 的 [subagent](/zh-CN/sub-agents)，用于处理任务。请参阅 [Agent 工具行为](#agent-tool-behavior) | 否 |15| `Agent` | 生成一个具有自己 context window 的 [subagent](/zh-CN/sub-agents)，用于处理任务。请参阅 [Agent 工具行为](#agent-tool-behavior) | 否 |

16| `Artifact` | 将 HTML 或 Markdown 文件发布为 [artifact](/zh-CN/artifacts)：一个私有的、交互式的 claude.ai 页面。在 Team 和 Enterprise 计划上，您可以在组织内共享它。{/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}需要 Pro、Max、Team 或 Enterprise 计划和 `/login` 身份验证；请参阅[可用性](/zh-CN/artifacts#availability) | 是 |16| `Artifact` | 将 HTML 或 Markdown 文件发布为 [artifact](/zh-CN/artifacts)：一个私有的、交互式的 claude.ai 页面。在 Team 和 Enterprise 计划上，您可以在组织内共享它。{/* plan-availability: feature=artifacts plans=pro,max,team,enterprise providers=anthropic */}需要 Pro、Max、Team 或 Enterprise 计划和 `/login` 身份验证；请参阅[可用性](/zh-CN/artifacts#availability) | 是 |

17| `AskUserQuestion` | 提出多选问题以收集需求或澄清歧义 | 否 |17| `AskUserQuestion` | 提出多选问题以收集需求或澄清歧义。{/* min-version: 2.1.198 */}从 v2.1.198 起，如果您在 60 秒内没有响应，对话框会自动关闭：它会提交您已选择的任何选项，并告诉 Claude 您可能离开了键盘，因此 Claude 会根据自己的判断继续进行，稍后可以重新提问。最后 20 秒会出现倒计时。任何按键都会保持对话框打开，对于报告焦点的终端上的焦点窗口也是如此。设置 [`CLAUDE_AFK_TIMEOUT_MS`](/zh-CN/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-CN/scheduled-tasks) | 否 |19| `CronCreate` | 在当前会话中安排定期或一次性提示。任务是会话范围的，在 `--resume` 或 `--continue` 时如果未过期则会恢复。请参阅[计划任务](/zh-CN/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-CN/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-CN/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` 字段，例如 `correctness` 或 `test-coverage`，显示在呈现列表中的文件位置旁边 | 否 |

39| `ScheduleWakeup` | 重新安排 [self-paced `/loop`](/zh-CN/scheduled-tasks#let-claude-choose-the-interval) 的下一次迭代。Claude 在每次迭代结束时调用此工具以选择下一次运行的时间，范围在一分钟到一小时之间；您不需要直接调用它。待处理的唤醒显示在 [Stop hook input](/zh-CN/hooks#stop-input) 中的 `session_crons` 中。{/* plan-availability: feature=loop-dynamic providers=anthropic */}在 Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry 上不可用，其中没有间隔的 `/loop` 提示按固定时间表运行 | 否 |39| `ScheduleWakeup` | 重新安排 [self-paced `/loop`](/zh-CN/scheduled-tasks#let-claude-choose-the-interval) 的下一次迭代。Claude 在每次迭代结束时调用此工具以选择下一次运行的时间，范围在一分钟到一小时之间；您不需要直接调用它。待处理的唤醒显示在 [Stop hook input](/zh-CN/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-CN/agent-teams) 队友发送消息，或按 agent ID [恢复 subagent](/zh-CN/sub-agents#resume-subagents)。已停止的 subagents 在后台自动恢复。结构化的团队协议消息需要 agent teams | 否 |40| `SendMessage` | 向 [agent team](/zh-CN/agent-teams) 队友发送消息，或按 agent ID 或名称[恢复 subagent](/zh-CN/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-CN/sub-agents#resume-subagents) | 否 |

41| `SendUserFile` | 将会话中的文件发送给您，带有可选的标题，以便生成的报告、图表、屏幕截图或构建的工件到达您的设备，而不仅仅是在记录中提及。{/* min-version: 2.1.196 */}从 v2.1.196 起，可选的 `display` 输入控制呈现方式：`render` 在客户端中内联打开文件，`attach` 仅显示下载卡，未设置时客户端按文件类型决定。当连接了 [Remote Control](/zh-CN/remote-control) 客户端或会话在托管云环境（如 [Claude Code on the web](/zh-CN/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-CN/remote-control) 客户端或会话在托管云环境（如 [Claude Code on the web](/zh-CN/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-CN/skills#control-who-invokes-a-skill) | 是 |43| `Skill` | 在主对话中执行 [skill](/zh-CN/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-CN/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-CN/mcp#scale-with-mcp-tool-search) 时搜索并加载延迟工具 | 否 |51| `ToolSearch` | 当启用 [tool search](/zh-CN/mcp#scale-with-mcp-tool-search) 时搜索并加载延迟工具 | 否 |

52| `WaitForMcpServers` | {/* min-version: 2.1.142 */}等待一个或多个仍在后台连接的 [MCP servers](/zh-CN/mcp)，以便请求可以使用它们的工具而无需重启会话。当所需的服务器尚未连接时，Claude 会调用它。仅当禁用 [tool search](/zh-CN/mcp#scale-with-mcp-tool-search) 时出现，因为启用时 `ToolSearch` 会处理等待 | 否 |52| `WaitForMcpServers` | 等待一个或多个仍在后台连接的 [MCP servers](/zh-CN/mcp)，以便请求可以使用它们的工具而无需重启会话。Claude 会在所需的服务器尚未连接时调用它。仅当禁用 [tool search](/zh-CN/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-CN/workflows)：一个在后台协调许多 subagents 并返回一个统一结果的脚本 | 是 |55| `Workflow` | 运行一个 [dynamic workflow](/zh-CN/workflows)：一个在后台协调许多 subagents 并返回一个统一结果的脚本 | 是 |

91 Agent 工具行为91 Agent 工具行为

92</h2>92</h2>

93 93

94Agent 工具在单独的 context window 中生成一个 subagent。subagent 自主地完成其任务，然后向父对话返回单个文本结果。父对话看不到 subagent 的中间工具调用或输出，只看到最终结果。要限制 subagent 运行的轮数，请在 [subagent 定义](/zh-CN/sub-agents#supported-frontmatter-fields)中设置 `maxTurns`。94Agent 工具在单独的 context window 中生成一个 subagent。subagent 自主地完成其任务，然后向父对话返回单个文本结果。父对话看不到 subagent 的中间工具调用或输出，只看到最终结果。

96要限制 subagent 运行的轮数，请在 [subagent 定义](/zh-CN/sub-agents#supported-frontmatter-fields)中设置 `maxTurns`。

95 97

96同一个 Agent 工具也在启用 fork 模式时启动[分叉 subagents](/zh-CN/sub-agents#fork-the-current-conversation)。fork 继承完整的父对话，而不是从头开始，始终在后台运行，并且仍然在您的终端中显示权限提示。本节的其余部分描述命名的 subagents。98同一个 Agent 工具也在启用 fork 模式时启动[分叉 subagents](/zh-CN/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-CN/sandboxing) 网络规则单独配置，因此您希望沙箱进程到达的域仍然需要显式沙箱权限规则。357WebFetch 设置以 `Claude-User` 开头的 `User-Agent` 标头，以及优先 Markdown 而不是 HTML 的 `Accept` 标头，以便支持内容协商的服务器可以直接返回 Markdown。Sandbox [网络规则](/zh-CN/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 不公开服务器端网络搜索工具。372 WebSearch 在 Claude API、[Claude Platform on AWS](/zh-CN/claude-platform-on-aws) 和 Microsoft Foundry 上可用。在 Google Cloud Vertex AI 上，它适用于 Claude 4 及更高版本的模型，包括 Opus、Sonnet 和 Haiku。Amazon Bedrock 不公开服务器端网络搜索工具。

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-CN/tools-reference) 工具创建一个。一旦进入 worktree，Claude 可以通过调用 `EnterWorktree` 并指定目标路径，直接切换到 `.claude/worktrees/` 下的另一个 worktree。之前的 worktree 保留在磁盘上不变。37您也可以在会话期间要求 Claude "在 worktree 中工作"，它将使用 [`EnterWorktree`](/zh-CN/tools-reference) 工具创建一个。一旦进入 worktree，Claude 可以通过调用 `EnterWorktree` 并指定目标路径，直接切换到 `.claude/worktrees/` 下的另一个 worktree。之前的 worktree 保留在磁盘上不变。

38 38

39{/* min-version: 2.1.198 */}从 v2.1.198 开始，进入或退出 worktree 也会将会话记录重新定位到该目录的项目存储，与 [`/cd`](/zh-CN/commands) 的方式相同，因此 `/desktop` 和 `--resume` 之后会在那里找到会话。由 [`WorktreeCreate` hook](#non-git-version-control) 创建的 Worktrees 被排除在外，并将记录保留在启动目录中。

39在首次在目录中使用 `--worktree` 之前，请通过在该目录中运行一次 `claude` 来接受工作区信任对话框。如果尚未接受信任，`--worktree` 将以错误退出并提示您首先在目录中运行 `claude`。使用 `-p` 的非交互式运行会跳过[信任检查](/zh-CN/security)，因此 `claude -p --worktree` 会在没有信任检查的情况下进行。41在首次在目录中使用 `--worktree` 之前，请通过在该目录中运行一次 `claude` 来接受工作区信任对话框。如果尚未接受信任，`--worktree` 将以错误退出并提示您首先在目录中运行 `claude`。使用 `-p` 的非交互式运行会跳过[信任检查](/zh-CN/security)，因此 `claude -p --worktree` 会在没有信任检查的情况下进行。

40 42

41<Tip>43<Tip>

Documentation 2026-07-02 23:59 UTC to 2026-07-03 23:00 UTC