Documentation — Spybara

accessibility.md +1 −1

Details

111 回答菜单和提示111 回答菜单和提示

112</h2>112</h2>

113 113

114在屏幕阅读器模式中，您通常使用箭头键导航的菜单（包括权限提示）会变成编号列表。Claude Code 将每个选项宣布为编号行，然后是一个 `Enter selection` 提示，该提示命名有效范围。输入您想要的选项的编号，然后按 Enter。114在屏幕阅读器模式中，您通常使用箭头键导航的菜单（包括权限提示）会变成编号列表。Claude Code 将每个选项宣布为编号行，然后是一个 `Select with numbers` 提示，该提示命名有效范围。输入您想要的选项的编号，然后按 Enter。

115 115

116* 按 Escape 键取消提示以 `or Escape to cancel` 结尾的菜单。116* 按 Escape 键取消提示以 `or Escape to cancel` 结尾的菜单。

117* 如果您输入的数字不在列表中，Claude Code 会宣布有效范围，让您重试。117* 如果您输入的数字不在列表中，Claude Code 会宣布有效范围，让您重试。

admin-setup.md +2 −2

Details

97| :- | :- | :- |97| :- | :- | :- |

99| [Permission lockdown](/docs/zh-CN/permissions#managed-only-settings) | 使托管设置成为[权限规则的唯一设置源](/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly)。禁用 `--dangerously-skip-permissions` | `allowManagedPermissionRulesOnly`、`permissions.disableBypassPermissionsMode` |99| [Permission lockdown](/docs/zh-CN/permissions#managed-only-settings) | 使托管设置成为[权限规则的唯一设置源](/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly)。禁用 `--dangerously-skip-permissions` | `allowManagedPermissionRulesOnly`、`permissions.disableBypassPermissionsMode` |

100| [Starting permission mode](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in) | 选择开发人员终端会话启动时的权限模式，而不是内置的启动权限模式，或删除自动模式。VS Code 扩展仅在 Pro、Max 和 Team 计划上读取您设置的 `defaultMode`；[Switch permission modes](/docs/zh-CN/permission-modes#switch-permission-modes) 列出扩展读取的内容 | `permissions.defaultMode`、`permissions.disableAutoMode` |100| [Starting permission mode](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in) | 选择开发人员终端会话启动时的权限模式，而不是内置的启动权限模式，或删除自动模式。[Switch permission modes](/docs/zh-CN/permission-modes#switch-permission-modes) 列出 VS Code 扩展何时读取您设置的 `defaultMode` | `permissions.defaultMode`、`permissions.disableAutoMode` |

103| [MCP server control](/docs/zh-CN/managed-mcp) | 限制用户可以添加或连接的 MCP 服务器、部署固定集合，或为每个用户提供远程服务器以及他们自己的服务器 | `allowedMcpServers`、`deniedMcpServers`、`allowManagedMcpServersOnly`、`managedMcpServers` 或已部署的 `managed-mcp.json` 文件 |103| [MCP server control](/docs/zh-CN/managed-mcp) | 限制用户可以添加或连接的 MCP 服务器、部署固定集合，或为每个用户提供远程服务器以及他们自己的服务器 | `allowedMcpServers`、`deniedMcpServers`、`allowManagedMcpServersOnly`、`managedMcpServers` 或已部署的 `managed-mcp.json` 文件 |

105| [Customization lockdown](/docs/zh-CN/settings-reference#strictpluginonlycustomization) | 阻止 skills、agents、hooks 和 MCP 服务器来自用户和项目源，使它们只能来自插件或托管设置。锁定 skills 也会停止[您的开发人员在 claude.ai 上启用的 skills](/docs/zh-CN/skills#where-synced-skills-load) 的同步 | `strictPluginOnlyCustomization` |105| [Customization lockdown](/docs/zh-CN/settings-reference#strictpluginonlycustomization) | 阻止 skills、agents、hooks 和 MCP 服务器来自用户和项目源，使它们只能来自插件或托管设置。锁定 skills 也会停止[您的开发人员在 claude.ai 上启用的 skills](/docs/zh-CN/skills#where-synced-skills-load) 的同步 | `strictPluginOnlyCustomization` |

106| [Disable claude.ai sync](/docs/zh-CN/settings-reference#syncclaudeaiskills) | 停止 Claude Code 加载[您的开发人员在 claude.ai 上启用的 skills](/docs/zh-CN/skills#how-synced-skills-behave) 和[插件](/docs/zh-CN/plugins/loading#synced-plugins)。如果您为组织关闭 claude.ai 上的 Skills，Claude Code 会停止同步两者，在 v2.1.273 或更高版本上，它也会删除已同步的那些。要在不关闭 Skills 的情况下停止其中任一个，在托管设置中将其键设置为 `false` | `syncClaudeAiSkills`、`syncClaudeAiPlugins` |106| [Disable claude.ai sync](/docs/zh-CN/settings-reference#syncclaudeaiskills) | 停止 Claude Code 加载[您的开发人员在 claude.ai 上启用的 skills](/docs/zh-CN/skills#how-synced-skills-behave) 和[插件](/docs/zh-CN/plugins/loading#synced-plugins)。如果您为组织关闭 claude.ai 上的 Skills，Claude Code 会停止同步两者，在 v2.1.273 或更高版本上，它也会删除已同步的那些。要在不关闭 Skills 的情况下停止其中任一个，在托管设置中将其键设置为 `false` | `syncClaudeAiSkills`、`syncClaudeAiPlugins` |

107| [Hook restrictions](/docs/zh-CN/settings-reference#allowmanagedhooksonly) | 限制哪些 hooks 运行并限制 HTTP hook URL；请参阅[`allowManagedHooksOnly` 下运行的内容](/docs/zh-CN/settings-reference#what-runs-under-allowmanagedhooksonly)了解完整的效果列表 | `allowManagedHooksOnly`、`allowedHttpHookUrls` |107| [Hook restrictions](/docs/zh-CN/settings-reference#allowmanagedhooksonly) | 限制哪些 hooks 运行并限制 HTTP hook URL；请参阅[`allowManagedHooksOnly` 下运行的内容](/docs/zh-CN/settings-reference#what-runs-under-allowmanagedhooksonly)了解完整的效果列表 | `allowManagedHooksOnly`、`allowedHttpHookUrls` |

108| [Login enforcement](/docs/zh-CN/settings-reference#forceloginmethod) | 限制登录到特定方法或 Anthropic 组织。方法限制适用于 VS Code 扩展、Agent SDK、`claude setup-token` 和 `/install-github-app`，以及终端的交互式登录屏幕（通过 `/login` 或首次运行入门到达），预先选择方法但不强制执行；Claude Code 在终端、VS Code 扩展和 Agent SDK 中验证 claude.ai 账户登录的组织，不检查 Claude Console 登录或[网关](/docs/zh-CN/claude-apps-gateway)登录。在 v2.1.212 之前，仅终端登录应用任一密钥。设置后，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 进行身份验证的会话在启动时被阻止；云提供商会话不受影响 | `forceLoginMethod`、`forceLoginOrgUUID` |108| [Login enforcement](/docs/zh-CN/settings-reference#forceloginmethod) | 限制登录到特定方法或 Anthropic 组织。方法限制适用于 VS Code 扩展、Agent SDK、`claude setup-token` 和 `/install-github-app`，以及终端的交互式登录屏幕（通过 `/login` 或首次运行入门到达），预先选择方法但不强制执行；Claude Code 在终端、VS Code 扩展和 Agent SDK 中验证 claude.ai 账户登录的组织，不检查 Claude Console 登录或[网关](/docs/zh-CN/claude-apps-gateway)登录。在 v2.1.212 之前，仅终端登录应用任一密钥。设置后，由 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 进行身份验证的会话在启动时被阻止；云提供商会话不受影响，除非这些凭证之一或由较早的 Claude Console 登录保存的 API 密钥也存在 | `forceLoginMethod`、`forceLoginOrgUUID` |

110| [Configure the corporate launcher](/docs/zh-CN/corporate-launcher) | 使用必需的企业启动器作为[后台代理监督程序](/docs/zh-CN/agent-view#how-background-sessions-are-hosted)、其工作程序和[其他涵盖的后台进程](/docs/zh-CN/corporate-launcher#what-the-launcher-covers)的前缀，而不是关闭代理视图 | `processWrapper` |110| [Configure the corporate launcher](/docs/zh-CN/corporate-launcher) | 使用必需的企业启动器作为[后台代理监督程序](/docs/zh-CN/agent-view#how-background-sessions-are-hosted)、其工作程序和[其他涵盖的后台进程](/docs/zh-CN/corporate-launcher#what-the-launcher-covers)的前缀，而不是关闭代理视图 | `processWrapper` |

111| [Model restrictions](/docs/zh-CN/model-config#restrict-model-selection) | `availableModels` 筛选模型选择器中显示的模型。添加 `enforceAvailableModels` 也会限制自动选择的默认模型。请参阅[表面覆盖](/docs/zh-CN/model-config#surface-coverage)了解此设置如何到达 CLI、web 和 IDE | `availableModels`、`enforceAvailableModels` |111| [Model restrictions](/docs/zh-CN/model-config#restrict-model-selection) | `availableModels` 筛选模型选择器中显示的模型。添加 `enforceAvailableModels` 也会限制自动选择的默认模型。请参阅[表面覆盖](/docs/zh-CN/model-config#surface-coverage)了解此设置如何到达 CLI、web 和 IDE | `availableModels`、`enforceAvailableModels` |

advisor.md +3 −2

Details

101| - | - | - |101| - | - | - |

103| Sonnet 4.6 | Fable、Opus、Sonnet | |103| Sonnet 4.6 | Fable、Opus、Sonnet | |

161 161

162* **Reviewed**：该行确认顾问已审查对话。当顾问返回可读的指导时，按 `Ctrl+O` 阅读。162* **Reviewed**：该行确认顾问已审查对话。当顾问返回可读的指导时，按 `Ctrl+O` 阅读。

163* **Declined**：该行显示 `Advisor declined to advise on this request`。如果顾问给出了原因，按 `Ctrl+O` 阅读。163* **Declined**：该行显示 `Advisor declined to advise on this request`。如果顾问给出了原因，按 `Ctrl+O` 阅读。

164* **Unavailable**：顾问调用失败，该行读取 `Advisor unavailable (<error_code>)`，其中 `<error_code>` 是调用返回的代码。

164 165

165Claude 通常遵循顾问的指导，但在其自己的证据与特定声明相矛盾时进行调整：如果推荐的步骤在尝试时失败，或文件内容与建议相矛盾，Claude 会显示冲突而不是无条件地遵循指导。166Claude 通常遵循顾问的指导，但在其自己的证据与特定声明相矛盾时进行调整：如果推荐的步骤在尝试时失败，或文件内容与建议相矛盾，Claude 会显示冲突而不是无条件地遵循指导。

166 167

agent-sdk/custom-tools.md +9 −8

Details

129有关完整的参数详细信息，包括 JSON Schema 输入格式和返回值结构，请参阅 [`tool()`](/docs/zh-CN/agent-sdk/typescript#tool) TypeScript 参考或 [`@tool`](/docs/zh-CN/agent-sdk/python#tool) Python 参考。129有关完整的参数详细信息，包括 JSON Schema 输入格式和返回值结构，请参阅 [`tool()`](/docs/zh-CN/agent-sdk/typescript#tool) TypeScript 参考或 [`@tool`](/docs/zh-CN/agent-sdk/python#tool) Python 参考。

130 130

131<Tip>131<Tip>

132 要使参数可选：在 TypeScript 中，向 Zod 字段添加 `.default()`。在 Python 中，字典模式将每个键视为必需的，因此将参数从模式中省略，在描述字符串中提及它，并在处理程序中使用 `args.get()` 读取它。下面的 [`get_precipitation_chance` 工具](#add-more-tools)展示了两种模式。132 要使参数可选：在 TypeScript 中，向 Zod 字段添加 `.optional()`，并在处理程序中应用默认值。在 Python 中，字典模式将每个键视为必需的，因此将参数从模式中省略，在描述字符串中提及它，并在处理程序中使用 `args.get()` 读取它。下面的 [`get_precipitation_chance` 工具](#add-more-tools)展示了两种模式。

133</Tip>133</Tip>

134 134

135<h3 id="call-a-custom-tool">135<h3 id="call-a-custom-tool">

248 .int()248 .int()

249 .min(1)249 .min(1)

250 .max(24)250 .max(24)

251 .default(12) // .default() makes the parameter optional251 .optional() // .optional() lets Claude omit the parameter

252 .describe("How many hours of forecast to return")252 .describe("How many hours of forecast to return")

253 },253 },

254 async (args) => {254 async (args) => {

255 const hours = args.hours ?? 12; // Apply the default in the handler

255 const response = await fetch(256 const response = await fetch(

256 `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&hourly=precipitation_probability&forecast_days=1`257 `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&hourly=precipitation_probability&forecast_days=1`

257 );258 );

258 const data: any = await response.json();259 const data: any = await response.json();

259 const chances = data.hourly.precipitation_probability.slice(0, args.hours);260 const chances = data.hourly.precipitation_probability.slice(0, hours);

260 261

261 return {262 return {

262 content: [{ type: "text", text: `Next ${args.hours} hours: ${chances.join("%, ")}%` }]263 content: [{ type: "text", text: `Next ${hours} hours: ${chances.join("%, ")}%` }]

263 };264 };

264 }265 }

265 );266 );

469 图像470 图像

470</h3>471</h3>

471 472

472图像块以 base64 编码的方式内联携带图像字节。没有 URL 字段。要返回位于 URL 的图像，请在处理程序中获取它，读取响应字节，并在返回之前对其进行 base64 编码。结果被处理为视觉输入。473图像块以 base64 编码的方式内联携带图像字节。没有 URL 字段。要返回位于 URL 的图像，请在处理程序中获取它，读取响应字节，并在返回之前对其进行 base64 编码。PNG、JPEG、GIF 或 WebP 图像作为视觉输入到达 Claude；任何其他类型的图像都被保存到磁盘，Claude 接收其文件路径作为文本。

473 474

474| 字段 | 类型 | 说明 |475| 字段 | 类型 | 说明 |

475| :- | :- | :- |476| :- | :- | :- |

538 资源539 资源

539</h3>540</h3>

540 541

541资源块嵌入由 URI 标识的内容片段。URI 是 Claude 引用的标签；实际内容位于块的 `text` 或 `blob` 字段中。当您的工具生成稍后按名称引用有意义的内容时，请使用此方法，例如生成的文件或来自外部系统的记录。542资源块嵌入由 URI 标识的内容片段。实际内容位于块的 `text` 或 `blob` 字段中。当您的工具生成文件或来自外部系统的记录时，请使用此方法。

542 543

543| 字段 | 类型 | 说明 |544| 字段 | 类型 | 说明 |

544| :- | :- | :- |545| :- | :- | :- |

549| `resource.mimeType` | `string` | 可选 |550| `resource.mimeType` | `string` | 可选 |

550 551

551此示例显示从工具处理程序内部返回的资源块。URI `file:///tmp/report.md` 是 Claude 稍后可以引用的标签；SDK 不会从该路径读取。552此示例显示从工具处理程序内部返回的资源块。SDK 不会从示例的 URI `file:///tmp/report.md` 读取。

552 553

553<CodeGroup>554<CodeGroup>

554 ```typescript TypeScript theme={null}555 ```typescript TypeScript theme={null}

572 {573 {

573 "type": "resource",574 "type": "resource",

574 "resource": {575 "resource": {

575 "uri": "file:///tmp/report.md", # Label for Claude to reference, not a path the SDK reads576 "uri": "file:///tmp/report.md", # Not a path the SDK reads

576 "mimeType": "text/markdown",577 "mimeType": "text/markdown",

577 "text": "# Report\n...", # The actual content, inline578 "text": "# Report\n...", # The actual content, inline

578 },579 },

agent-sdk/examples.md +4 −4

Details

6 6

7> 查找完整的、可运行的 Agent SDK 项目或 Claude Cookbook 中的指导食谱，以匹配您想要构建的内容。7> 查找完整的、可运行的 Agent SDK 项目或 Claude Cookbook 中的指导食谱，以匹配您想要构建的内容。

8 8

9本页面为您提供完整的、可运行的 Agent SDK 项目和指导性的 Claude Cookbook 食谱。TypeScript 应用程序位于 [`claude-agent-sdk-demos`](https://github.com/anthropics/claude-agent-sdk-demos) 仓库中，Python 食谱位于 [Claude Cookbook](https://platform.claude.com/cookbook) 中。9本页面为您提供完整的、可运行的 Agent SDK 项目和指导性的 Claude Cookbook 食谱。这些应用程序位于 [`claude-agent-sdk-demos`](https://github.com/anthropics/claude-agent-sdk-demos) 仓库中，Python 食谱位于 [Claude Cookbook](https://platform.claude.com/cookbook) 中。

10 10

11<h2 id="run-a-minimal-agent-first">11<h2 id="run-a-minimal-agent-first">

12 首先运行一个最小化的 agent12 首先运行一个最小化的 agent

18 18

19* [Hello World](https://github.com/anthropics/claude-agent-sdk-demos/tree/main/hello-world)：当您想从仓库代码开始时要克隆的最小 TypeScript 项目19* [Hello World](https://github.com/anthropics/claude-agent-sdk-demos/tree/main/hello-world)：当您想从仓库代码开始时要克隆的最小 TypeScript 项目

20 20

~~21<h2 id="explore-a-typescript-application">~~21<h2 id="explore-a-demo-application">

~~22 探索 TypeScript 应用程序~~22 探索演示应用程序

23</h2>23</h2>

24 24

25[`claude-agent-sdk-demos`](https://github.com/anthropics/claude-agent-sdk-demos) 中的 TypeScript 应用程序是本地开发的演示，从电子邮件客户端到多 agent 研究系统。克隆其形状与您正在构建的内容相匹配的演示。25[`claude-agent-sdk-demos`](https://github.com/anthropics/claude-agent-sdk-demos) 中的应用程序是本地开发的演示，从电子邮件客户端到多 agent 研究系统。克隆其形状与您正在构建的内容相匹配的演示。

26 26

27<h2 id="work-through-a-python-recipe">27<h2 id="work-through-a-python-recipe">

28 完成 Python 食谱28 完成 Python 食谱

agent-sdk/file-checkpointing.md +8 −127

Details

6 6

7> 在agent会话期间跟踪文件更改，并将文件恢复到任何之前的状态7> 在agent会话期间跟踪文件更改，并将文件恢复到任何之前的状态

8 8

9File checkpointing跟踪在agent会话期间通过Write、Edit和NotebookEdit工具进行的文件修改，允许您将文件回滚到任何之前的状态。想要尝试一下？跳转到[交互式示例](#try-it-out)。9File checkpointing跟踪在agent会话期间通过[Write](/docs/zh-CN/tools-reference#write-tool-behavior)、[Edit](/docs/zh-CN/tools-reference#edit-tool-behavior)和[NotebookEdit](/docs/zh-CN/tools-reference#notebookedit-tool-behavior)工具进行的文件修改，允许您将文件回滚到任何之前的状态。想要观看回滚恢复文件的过程，请跳转到[交互式示例](#try-it-out)。

~~11使用checkpointing，您可以：~~

~~13* **撤销不需要的更改**，通过将文件恢复到已知的良好状态~~

~~14* **探索替代方案**，通过恢复到checkpoint并尝试不同的方法~~

~~15* **从错误中恢复**，当agent进行不正确的修改时~~

16 10

17<Warning>11<Warning>

18 只有通过Write、Edit和NotebookEdit工具进行的更改才会被跟踪。通过Bash命令进行的更改（如`echo > file.txt`或`sed -i`）不会被checkpoint系统捕获，[subagent](/docs/zh-CN/agent-sdk/subagents)应用的编辑也不会被捕获，除了在前台运行的[具有`context: fork`的skill](/docs/zh-CN/skills#run-skills-in-a-subagent)。12 只有通过Write、Edit和NotebookEdit工具进行的更改才会被跟踪。通过Bash命令进行的更改（如`echo > file.txt`或`sed -i`）不会被checkpoint系统捕获，[subagent](/docs/zh-CN/agent-sdk/subagents)应用的编辑也不会被捕获，除了在前台运行的[具有`context: fork`的skill](/docs/zh-CN/skills#run-skills-in-a-subagent)。

36 30

37要使用文件checkpointing，在您的选项中启用它，从响应流中捕获checkpoint UUID，然后在需要恢复时调用`rewindFiles()`（TypeScript）或`rewind_files()`（Python）。31要使用文件checkpointing，在您的选项中启用它，从响应流中捕获checkpoint UUID，然后在需要恢复时调用`rewindFiles()`（TypeScript）或`rewind_files()`（Python）。

38 32

39以下示例显示完整流程：启用checkpointing，从响应流中捕获checkpoint UUID和会话ID，然后稍后恢复会话以回滚文件。下面详细解释了每个步骤。本部分中的示例使用提示"重构身份验证模块"。在包含身份验证模块的项目中运行它们，或更改提示以命名项目中存在的文件，以便您可以观看文件更改并查看回滚如何恢复它们。33本部分中的示例使用提示"重构身份验证模块"。在包含身份验证模块的项目中运行它们，或更改提示以命名项目中存在的文件，以便您可以观看文件更改并查看回滚如何恢复它们。

35此示例启用checkpointing，从响应流中捕获checkpoint UUID和会话ID，然后稍后恢复会话以回滚文件。示例中的编号注释与以下步骤相对应。

40 36

41<CodeGroup>37<CodeGroup>

42 ```python Python theme={null}38 ```python Python theme={null}

154 | 接收checkpoint UUID | `extra_args={"replay-user-messages": None}` | `extraArgs: { 'replay-user-messages': null }` | 需要在流中获取用户消息UUID |150 | 接收checkpoint UUID | `extra_args={"replay-user-messages": None}` | `extraArgs: { 'replay-user-messages': null }` | 需要在流中获取用户消息UUID |

155 151

156 <CodeGroup>152 [实现checkpointing](#implement-checkpointing)下的主要示例还将权限模式设置为`acceptEdits`，这会在没有提示的情况下批准代理的文件编辑。有关更多信息，请参阅[权限模式](/docs/zh-CN/agent-sdk/permissions#permission-modes)。

157 ```python Python theme={null}

158 options = ClaudeAgentOptions(

159 enable_file_checkpointing=True,

160 permission_mode="acceptEdits",

161 extra_args={"replay-user-messages": None},

162 )

~~163~~

164 async with ClaudeSDKClient(options) as client:

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

166 ```

~~167~~

168 ```typescript TypeScript theme={null}

169 const response = query({

170 prompt: "Refactor the authentication module",

171 options: {

172 enableFileCheckpointing: true,

173 permissionMode: "acceptEdits" as const,

174 extraArgs: { "replay-user-messages": null }

175 }

176 });

177 ```

178 </CodeGroup>

179 </Step>153 </Step>

180 154

181 <Step title="捕获checkpoint UUID和会话ID">155 <Step title="捕获checkpoint UUID和会话ID">

184 对于大多数用例，捕获第一个用户消息UUID（`message.uuid`）；回滚到它会将所有文件恢复到原始状态。要存储多个checkpoint并回滚到中间状态，请参阅[多个恢复点](#multiple-restore-points)。158 对于大多数用例，捕获第一个用户消息UUID（`message.uuid`）；回滚到它会将所有文件恢复到原始状态。要存储多个checkpoint并回滚到中间状态，请参阅[多个恢复点](#multiple-restore-points)。

185 159

186 捕获会话ID（`message.session_id`）是可选的；只有在您想在流完成后回滚时才需要它。如果您在处理消息时立即调用`rewindFiles()`（如[在危险操作之前创建checkpoint](#checkpoint-before-risky-operations)中的示例所做的那样），您可以跳过捕获会话ID。160 捕获会话ID（`message.session_id`）是可选的；只有在您想在流完成后回滚时才需要它。如果您在处理消息时立即调用`rewindFiles()`（如[在危险操作之前创建checkpoint](#checkpoint-before-risky-operations)中的示例所做的那样），您可以跳过捕获会话ID。

~~187~~

188 <CodeGroup>

189 ```python Python theme={null}

190 checkpoint_id = None

191 session_id = None

~~192~~

193 async for message in client.receive_response():

194 # Capture the first user message UUID as the checkpoint

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

196 checkpoint_id = message.uuid

197 # Capture session ID from the result message

198 if isinstance(message, ResultMessage):

199 session_id = message.session_id

200 ```

~~201~~

202 ```typescript TypeScript theme={null}

203 let checkpointId: string | undefined;

204 let sessionId: string | undefined;

~~205~~

206 for await (const message of response) {

207 // Capture the first user message UUID as the checkpoint

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

209 checkpointId = message.uuid;

210 }

211 // Capture session ID from any message that has it

212 if ("session_id" in message) {

213 sessionId = message.session_id;

214 }

215 }

216 ```

217 </CodeGroup>

218 </Step>161 </Step>

219 162

220 <Step title="回滚文件">163 <Step title="回滚文件">

221 要在流完成后回滚，使用空提示恢复会话，并使用您的checkpoint UUID调用`rewind_files()`（Python）或`rewindFiles()`（TypeScript）。您也可以在流期间回滚；有关该模式，请参阅[在危险操作之前创建checkpoint](#checkpoint-before-risky-operations)。164 要在流完成后回滚，使用空提示恢复会话，并使用您的checkpoint UUID调用`rewind_files()`（Python）或`rewindFiles()`（TypeScript）。在恢复会话的选项上也启用checkpointing，并从响应循环内调用rewind。您也可以在流期间回滚。有关该模式，请参阅[在危险操作之前创建checkpoint](#checkpoint-before-risky-operations)。

222 165

223 <CodeGroup>166 如果您捕获了会话ID和checkpoint ID，您也可以从CLI回滚。此命令需要`claude`可执行文件，该文件来自[安装Claude Code](/docs/zh-CN/setup)。SDK为您启用checkpointing，但当您直接运行`claude -p`时，您必须设置`CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING`环境变量：

224 ```python Python theme={null}

225 async with ClaudeSDKClient(

226 ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)

227 ) as client:

228 await client.query("") # Empty prompt to open the connection

229 async for message in client.receive_response():

230 if checkpoint_id:

231 await client.rewind_files(checkpoint_id)

232 break

233 ```

~~234~~

235 ```typescript TypeScript theme={null}

236 const rewindQuery = query({

237 prompt: "", // Empty prompt to open the connection

238 options: { ...opts, resume: sessionId }

239 });

~~240~~

241 for await (const msg of rewindQuery) {

242 if (checkpointId) {

243 await rewindQuery.rewindFiles(checkpointId);

244 }

245 break;

246 }

247 ```

248 </CodeGroup>

~~249~~

250 如果您捕获了会话ID和checkpoint ID，您也可以从CLI回滚。此命令需要`claude`可执行文件，该文件来自[安装Claude Code](/docs/zh-CN/setup)，不由SDK包安装。SDK为您启用checkpointing，但当您直接运行`claude -p`时，您必须设置`CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING`环境变量：

251 167

252 ```bash theme={null}168 ```bash theme={null}

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

783 699

784当您在完成响应迭代后调用`rewindFiles()`或`rewind_files()`时，会发生此错误。当循环完成时，与CLI进程的连接关闭。700当您在完成响应迭代后调用`rewindFiles()`或`rewind_files()`时，会发生此错误。当循环完成时，与CLI进程的连接关闭。

785 701

786**解决方案**：使用空提示恢复会话，然后在新查询上调用rewind：702**解决方案**：使用空提示恢复会话，然后在新查询上调用rewind。[Implement checkpointing](#implement-checkpointing)下的主要示例在标记为Step 3的注释处显示了两种语言的resume-and-rewind调用。

~~787~~

788<CodeGroup>

789 ```python Python theme={null}

790 # Resume session with empty prompt, then rewind

791 async with ClaudeSDKClient(

792 ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)

793 ) as client:

794 await client.query("")

795 async for message in client.receive_response():

796 if checkpoint_id:

797 await client.rewind_files(checkpoint_id)

798 break

799 ```

~~800~~

801 ```typescript TypeScript theme={null}

802 // Resume session with empty prompt, then rewind

803 const rewindQuery = query({

804 prompt: "",

805 options: { ...opts, resume: sessionId }

806 });

~~807~~

808 try {

809 for await (const msg of rewindQuery) {

810 if (checkpointId) {

811 await rewindQuery.rewindFiles(checkpointId);

812 }

813 break;

814 }

815 } catch (error) {

816 // An error here means the rewind didn't complete, for example the checkpoint

817 // wasn't found or the session couldn't be resumed.

818 console.error(`Rewind session ended with an error: ${error}`);

819 }

820 ```

821</CodeGroup>

822 703

823<h2 id="next-steps">704<h2 id="next-steps">

824 后续步骤705 后续步骤

agent-sdk/hosting.md +6 −1

Details

127 127

128示例工作负载包括对传入邮件进行分类和响应的电子邮件代理、通过容器端口托管每个用户可编辑站点的站点构建器，以及处理来自 Slack 等平台的连续流量的聊天机器人。128示例工作负载包括对传入邮件进行分类和响应的电子邮件代理、通过容器端口托管每个用户可编辑站点的站点构建器，以及处理来自 Slack 等平台的连续流量的聊天机器人。

129 129

130容器公开 HTTP 或 WebSocket 端点，并将每个活跃会话映射到一个长期查询及其后面的子进程。在 TypeScript 中，使用 [`streamInput()`](/docs/zh-CN/agent-sdk/typescript#query-object) 向活跃会话添加轮次，使用 [`startup()`](/docs/zh-CN/agent-sdk/typescript#startup) 在传入流量前预热子进程。在 Python 中，使用 [`ClaudeSDKClient`](/docs/zh-CN/agent-sdk/python#claudesdkclient) 在轮次间保持会话打开。调整容器大小，使其能够在内存中容纳最大并发会话数。130容器公开 HTTP 或 WebSocket 端点，并将每个活跃会话映射到一个长期查询及其后面的子进程。保持会话打开和预热的调用在 SDK 之间有所不同：

131

132* **TypeScript**：使用 [`streamInput()`](/docs/zh-CN/agent-sdk/typescript#query-object) 向活跃会话添加轮次。调用 [`startup()`](/docs/zh-CN/agent-sdk/typescript#startup) 在传入流量前预热子进程。如果您在第一个请求到达之前不知道会话的工作目录，请改用 [`prewarm()`](/docs/zh-CN/agent-sdk/typescript#prewarm) 进行预热。

133* **Python**：使用 [`ClaudeSDKClient`](/docs/zh-CN/agent-sdk/python#claudesdkclient) 在轮次间保持会话打开。

134

135调整容器大小，使其能够在内存中容纳最大并发会话数。

131 136

132<h3 id="hybrid-sessions">137<h3 id="hybrid-sessions">

133 Hybrid sessions138 Hybrid sessions

agent-sdk/mcp.md +1 −1

Details

162| :- | :- | :- |162| :- | :- | :- |

166 166

167从 [settings 文件](#from-a-config-file)（如 `.mcp.json`）或从插件加载的服务器通常在 init 消息中显示 `pending`。当 `options.mcpServers` 包含 stdio、HTTP 或 SSE 服务器时，第一轮等待这些待处理的服务器，最多等待 `MCP_TIMEOUT`。当 `options.mcpServers` 为空或仅包含 SDK 服务器时，第一轮改为最多等待 2 秒：167从 [settings 文件](#from-a-config-file)（如 `.mcp.json`）或从插件加载的服务器通常在 init 消息中显示 `pending`。当 `options.mcpServers` 包含 stdio、HTTP 或 SSE 服务器时，第一轮等待这些待处理的服务器，最多等待 `MCP_TIMEOUT`。当 `options.mcpServers` 为空或仅包含 SDK 服务器时，第一轮改为最多等待 2 秒：

168 168

agent-sdk/modifying-system-prompts.md +123 −8

Details

14 14

15系统提示词是初始指令集，它塑造了 Claude 在整个对话中的行为方式。Agent SDK 有三个起点：15系统提示词是初始指令集，它塑造了 Claude 在整个对话中的行为方式。Agent SDK 有三个起点：

16 16

17* **最小默认值**：当你在 TypeScript 中不设置 `systemPrompt` 或在 Python 中不设置 `system_prompt` 时，SDK 使用最小提示词，涵盖工具调用但省略了 `claude_code` 预设的其余内容，包括其安全和安全指令以及关于工作目录和环境的上下文。这与 `claude -p` 不同，后者默认使用 Claude Code 系统提示词。如果你从 CLI 迁移并想要匹配的行为，请设置 `claude_code` 预设。17* **最小默认值**：当你在 TypeScript 中不设置 `systemPrompt` 或在 Python 中不设置 `system_prompt` 时，SDK 使用最小提示词，涵盖工具调用但省略了 `claude_code` 预设的其余内容，包括其安全和安全指令。这与 `claude -p` 不同，后者默认使用 Claude Code 系统提示词。如果你从 CLI 迁移并想要匹配的行为，请设置 `claude_code` 预设。

18* **`claude_code` 预设**：Claude Code CLI 使用的系统提示词，包含工具使用说明、安全和安全指令，以及关于工作目录和环境的上下文。在 TypeScript 中设置 `systemPrompt: { type: "preset", preset: "claude_code" }`，或在 Python 中设置 `system_prompt={"type": "preset", "preset": "claude_code"}`，可选择使用 `append` 在末尾添加你自己的指令。18* **`claude_code` 预设**：Claude Code CLI 使用的系统提示词，包含工具使用说明和安全和安全指令。在 TypeScript 中设置 `systemPrompt: { type: "preset", preset: "claude_code" }`，或在 Python 中设置 `system_prompt={"type": "preset", "preset": "claude_code"}`，可选择使用 `append` 在末尾添加你自己的指令。

19* **自定义字符串**：你自己编写的提示词。SDK 仅发送你提供的内容。19* **自定义字符串**：你自己编写的提示词。SDK 仅发送你提供的内容。

20 20

21<h3 id="decide-on-a-starting-point">21<h3 id="decide-on-a-starting-point">

26 26

27| 你正在构建 | 使用 | 你获得的内容 |27| 你正在构建 | 使用 | 你获得的内容 |

28| :- | :- | :- |28| :- | :- | :- |

225 改进跨用户和机器的提示缓存225 改进跨用户和机器的提示缓存

226</h4>226</h4>

227 227

228默认情况下，两个使用相同 `claude_code` 预设和 `append` 文本的会话，如果从不同的工作目录运行，仍然无法共享提示缓存条目。这是因为预设在你的 `append` 文本之前在系统提示中嵌入了每个会话的上下文：工作目录、它是否是 git 存储库、平台、活跃的 shell、OS 版本和自动内存路径。该上下文中的任何差异都会产生不同的系统提示和缓存未命中。CLAUDE.md 内容不影响系统提示缓存，因为 SDK 将其注入到对话中，而不是系统提示。228默认情况下，两个使用相同 `claude_code` 预设和 `append` 文本的会话仍然无法共享提示缓存条目，当它们的自动内存位置不同时。预设在你的 `append` 文本之前在系统提示中嵌入了该位置。该位置默认为 `~/.claude/projects/` 下的绝对路径，以存储库在磁盘上的路径命名，因此在用户、机器和检出之间不同。

229 229

230要使系统提示在会话中相同，请在 TypeScript 中设置 `excludeDynamicSections: true` 或在 Python 中设置 `"exclude_dynamic_sections": True`。每个会话的上下文移动到第一条用户消息中，仅在系统提示中保留静态预设和你的 `append` 文本，因此相同的配置在用户和机器之间共享缓存条目。230CLAUDE.md 内容和环境详情（如工作目录、平台、shell 和 OS 版本）不影响系统提示缓存，因为 Claude Code 在对话中而不是系统提示中传递它们。

231

232要使系统提示在会话中相同，请在 TypeScript 中设置 `excludeDynamicSections: true` 或在 Python 中设置 `"exclude_dynamic_sections": True`。每个用户的上下文移动到第一条用户消息中，仅在系统提示中保留静态预设和你的 `append` 文本，因此相同的配置在用户和机器之间共享缓存条目。

231 233

232<Note>234<Note>

233 `excludeDynamicSections` 需要 `@anthropic-ai/claude-agent-sdk` v0.2.98 或更高版本，或 Python 的 `claude-agent-sdk` v0.1.58 或更高版本。仅在预设对象形式上设置它。当你传递自定义提示而不是预设时，SDK 会忽略它；要在 TypeScript SDK 中保持自定义提示的指令缓存，请参阅 [Cache the static part of a custom prompt](#cache-the-static-part-of-a-custom-prompt)。235 `excludeDynamicSections` 需要 `@anthropic-ai/claude-agent-sdk` v0.2.98 或更高版本，或 Python 的 `claude-agent-sdk` v0.1.58 或更高版本。仅在预设对象形式上设置它。当你传递自定义提示而不是预设时，SDK 会忽略它；要在 TypeScript SDK 中保持自定义提示的指令缓存，请参阅 [Cache the static part of a custom prompt](#cache-the-static-part-of-a-custom-prompt)。

234</Note>236</Note>

235 237

236以下示例将共享的 `append` 块与 `excludeDynamicSections` 配对，以便从不同目录运行的代理队列可以重复使用相同的缓存系统提示：238以下示例将共享的 `append` 块与 `excludeDynamicSections` 配对，以便代理队列可以重复使用相同的缓存系统提示：

237 239

238<CodeGroup>240<CodeGroup>

239 ```typescript TypeScript theme={null}241 ```typescript TypeScript theme={null}

279 ```281 ```

280</CodeGroup>282</CodeGroup>

281 283

282**权衡：** 工作目录、git 存储库标志、平台、活跃的 shell、OS 版本和自动内存路径仍然到达 Claude，但作为第一条用户消息的一部分，而不是系统提示。用户消息中的指令比系统提示中的相同文本的权重略低，因此 Claude 在推理当前目录或自动内存路径时可能会更少依赖它们。当跨会话缓存重复使用比最大化权威环境上下文更重要时，启用此选项。284**权衡：** 移出系统提示的文本仍然到达 Claude，但在用户消息中。该文本至少是自动内存目录的位置，通常是整个自动内存部分。用户消息中的指令比系统提示中的相同文本的权重略低，因此 Claude 可能会更少一致地遵循其自动内存指导。当跨会话缓存重复使用比最大化权威环境上下文更重要时，启用此选项。

283 285

284对于非交互式 CLI 模式中的等效标志，请参阅 [`--exclude-dynamic-system-prompt-sections`](/docs/zh-CN/cli-reference)。286对于非交互式 CLI 模式中的等效标志，请参阅 [`--exclude-dynamic-system-prompt-sections`](/docs/zh-CN/cli-reference)。

285 287

418 420

419默认记录 `append` 或自定义提示需要 Claude Code v2.1.265 或更高版本，TypeScript Agent SDK 从 v0.3.265 捆绑，Python Agent SDK 从 v0.2.153 捆绑。在 Claude Code v2.1.268 之前，不 [fetch feature flags](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) 的会话，包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的会话，在每个请求上重建提示，`snapshot` 无效。421默认记录 `append` 或自定义提示需要 Claude Code v2.1.265 或更高版本，TypeScript Agent SDK 从 v0.3.265 捆绑，Python Agent SDK 从 v0.2.153 捆绑。在 Claude Code v2.1.268 之前，不 [fetch feature flags](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) 的会话，包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的会话，在每个请求上重建提示，`snapshot` 无效。

420 422

423<h2 id="context-claude-code-adds-outside-the-system-prompt">

424 Claude Code 在系统提示之外添加的上下文

425</h2>

426

427系统提醒是 Claude Code 在会话期间添加到对话中的消息，用于为 Claude 提供上下文，例如 CLAUDE.md 文件的内容或文件在磁盘上已更改的说明。Claude Code 在对话中发送这些消息，而不是在系统提示中发送，因此无论您使用 `claude_code` 预设还是传递自己的字符串作为 `systemPrompt`，Claude 都会收到这些消息。

428

429本部分涵盖[最可能改变您的代理行为的提醒](#reminders-claude-code-adds-to-the-conversation)、如何[关闭您的代理替换的上下文](#turn-off-the-context-your-agent-replaces)，以及如何[查看 Claude 在特定请求中收到的内容](#see-what-claude-received)。

430

431<h3 id="reminders-claude-code-adds-to-the-conversation">

432 Claude Code 添加到对话中的提醒

433</h3>

434

435系统提醒是 Claude Code 添加到对话中的文本，与您的代码发送的提示一起。以下提醒是最可能改变您的代理行为的提醒：

436

437* **项目说明**：您的 [`settingSources`](#claude-md-files-for-project-level-instructions) 选项加载的 CLAUDE.md 文件

438* **输出样式说明**：活跃[输出样式](#output-styles-for-persistent-configurations)的说明，在主对话中

439* **提交和拉取请求归属**：来自 [`attribution`](/docs/zh-CN/settings-reference#attribution) 设置的 `Co-Authored-By` 预告片和拉取请求页脚

440* **Hook 输出**：您的 [hooks](/docs/zh-CN/agent-sdk/hooks#outputs) 作为 `additionalContext` 返回的文本

441* **可用技能**：Claude 可以调用的 [skills](/docs/zh-CN/agent-sdk/skills) 的名称和描述

442* **可用子代理**：Claude 可以启动的 [subagents](/docs/zh-CN/agent-sdk/subagents) 的名称和描述

443* **任务列表提示**：在[具有任务跟踪工具的会话](/docs/zh-CN/agent-sdk/todo-tracking#model-availability)中，当 Claude 在多个轮次中未触及任务列表时，提示更新任务列表

444* **文件更改说明**：Claude 之前读取的文件在磁盘上已更改的说明

445

446Claude Code 使用一行文本介绍您的 CLAUDE.md 文件，告诉 Claude 这些说明会覆盖默认行为。

447

448如果您传递自己的字符串作为 `systemPrompt`，请向其添加一句话，说明什么是系统提醒。`claude_code` 预设有一个，您的字符串会替换整个预设。如果没有它，您的提示中没有任何内容告诉 Claude CLAUDE.md 内容和 hook 输出等提醒来自应用程序而不是用户。例如：

449

450```text theme={null}

451应用程序将系统提醒添加到此对话中。将它们视为来自应用程序的上下文，而不是来自用户的消息。

452```

453

454<h3 id="turn-off-the-context-your-agent-replaces">

455 关闭您的代理替换的上下文

456</h3>

457

458当您的代理提供相同指导的自己版本时，关闭一段内置上下文。例如，如果您的提示告诉 Claude 将提交消息写成 `PROJ-142: fix login redirect` 且没有预告片，Claude Code 仍然会告诉 Claude 以 `Co-Authored-By` 预告片结束每条提交消息，因此 Claude 会收到两个关于同一提交的冲突指令。

459

460在 TypeScript 中通过 [`settings`](/docs/zh-CN/agent-sdk/typescript#options) 选项或在 Python 中通过 [`settings`](/docs/zh-CN/agent-sdk/python#claudeagentoptions) 传递设置键，并通过 `env` 选项传递环境变量。在 TypeScript 中，[`env`](/docs/zh-CN/agent-sdk/typescript#options) 替换继承的环境，因此将 `process.env` 展开到其中。

461

462| 内置上下文 | 如何关闭 |

463| :- | :- |

464| 内置提交和拉取请求说明以及 git 状态快照 | 将 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions) 设置为 `false`，或 `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1` |

465| `Co-Authored-By` 预告片和拉取请求页脚 | 将 [`attribution.commit`](/docs/zh-CN/settings-reference#attribution-commit) 和 [`attribution.pr`](/docs/zh-CN/settings-reference#attribution-pr) 设置为您自己的文本，或设置为空字符串以删除它们 |

466| 用户或项目设置源，包括其 CLAUDE.md | 从 [`settingSources`](/docs/zh-CN/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) 中省略 `'user'` 或 `'project'` |

467| 每个 CLAUDE.md 文件 | 设置 `CLAUDE_CODE_DISABLE_CLAUDE_MDS=1` |

468| 任务列表提示、文件更改说明和技能列表 | 设置 `CLAUDE_CODE_DISABLE_ATTACHMENTS=1` |

469

470Claude Code 的内置提交和拉取请求说明不是提醒。它们是 Bash 工具描述的一部分，因此当您传递自定义 `systemPrompt` 时，Claude 也会收到它们。

471

472如果您设置 `CLAUDE_CODE_DISABLE_ATTACHMENTS`，Claude Code 也会将 `@` 文件提及作为纯文本发送，而不是将其展开为文件内容。可用子代理列表和后台任务通知仍然会到达。

473

474以下示例适用于在 `append` 中携带自己提交规则的代理。它将两个 `attribution` 键都设置为空字符串以删除预告片和页脚，并关闭 `includeGitInstructions`，以便 Claude Code 自己的提交工作流说明不会与您的说明竞争：

475

476<CodeGroup>

477 ```typescript TypeScript theme={null}

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

479

480 for await (const message of query({

481 prompt: "Commit the staged changes for ticket PROJ-142",

482 options: {

483 systemPrompt: {

484 type: "preset",

485 preset: "claude_code",

486 append: "Write commit messages as: <ticket id>: <summary>. Add no trailers."

487 },

488 settings: {

489 includeGitInstructions: false,

490 attribution: { commit: "", pr: "" }

491 },

492 allowedTools: ["Bash(git *)"]

493 }

494 })) {

495 if (message.type === "result") console.log(message.subtype);

496 }

497 ```

498

499 ```python Python theme={null}

500 import asyncio

501 from claude_agent_sdk import query, ClaudeAgentOptions

502

503

504 async def main():

505 async for message in query(

506 prompt="Commit the staged changes for ticket PROJ-142",

507 options=ClaudeAgentOptions(

508 system_prompt={

509 "type": "preset",

510 "preset": "claude_code",

511 "append": "Write commit messages as: <ticket id>: <summary>. Add no trailers.",

512 },

513 settings='{"includeGitInstructions": false, "attribution": {"commit": "", "pr": ""}}',

514 allowed_tools=["Bash(git *)"],

515 ),

516 ):

517 print(message)

518

519

520 asyncio.run(main())

521 ```

522</CodeGroup>

523

524要确认更改，请在具有暂存更改的存储库中运行示例，并使用 `git log -1` 检查新提交。消息以没有 `Co-Authored-By` 预告片结尾。

525

526<h3 id="see-what-claude-received">

527 查看 Claude 收到的内容

528</h3>

529

530SDK 消息流不包括系统提醒，因此读取您的代码接收的消息不会显示 Claude 看到的内容。要查看它们，请记录 Claude Code 发送的请求：

531

532* **原始请求日志记录**：将 [`OTEL_LOG_RAW_API_BODIES`](/docs/zh-CN/monitoring-usage#api-request-body-event) 设置为 `file:<dir>`。Claude Code 将每个请求体写入该目录。

533* **您控制的网关**：将 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/llm-gateway) 指向记录请求体的代理。

534

535在记录的请求中，查看 `messages` 数组。提醒出现在用 `<system-reminder>` 标签包装的用户消息内，或在某些模型上，作为具有 `system` 角色的单独消息。

536

421<h2 id="compare-the-four-approaches">537<h2 id="compare-the-four-approaches">

422 比较四种方法538 比较四种方法

423</h2>539</h2>

432| **默认工具** | 保留 | 保留 | 保留 | 丢失（除非包含） |548| **默认工具** | 保留 | 保留 | 保留 | 丢失（除非包含） |

433| **内置安全** | 维护 | 维护 | 维护 | 必须添加 |549| **内置安全** | 维护 | 维护 | 维护 | 必须添加 |

434| **环境上下文** | 自动 | 自动 | 自动 | 必须提供 |

435| **自定义级别** | 仅添加 | 替换或扩展默认 | 仅添加 | 完全控制 |550| **自定义级别** | 仅添加 | 替换或扩展默认 | 仅添加 | 完全控制 |

agent-sdk/observability.md +2 −2

Details

246| 变量 | 添加 |246| 变量 | 添加 |

247| - | - |247| - | - |

249| `OTEL_LOG_TOOL_DETAILS=1` | `claude_code.tool_result` 事件上的工具输入参数（文件路径、shell 命令、搜索模式） |249| `OTEL_LOG_TOOL_DETAILS=1` | `claude_code.tool_result` 事件上的工具输入参数（文件路径、shell 命令、搜索模式），以及[成本和令牌指标](/docs/zh-CN/monitoring-usage#cost-counter)上的真实代理、skill、plugin 和 MCP 服务器名称 |

250| `OTEL_LOG_TOOL_CONTENT=1` | `claude_code.tool` 上的[`tool.output` 跨度事件](/docs/zh-CN/monitoring-usage#tool-output-span-event)，包含文件内容和 Bash 输出，默认在 60 KB 处截断，可通过 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 配置，需要 Claude Code v2.1.214 或更高版本。需要启用[跟踪](#read-agent-traces)。跨度属性在[其自己的门控](/docs/zh-CN/monitoring-usage#new-context-gates)下携带工具内容 |250| `OTEL_LOG_TOOL_CONTENT=1` | `claude_code.tool` 上的[`tool.output` 跨度事件](/docs/zh-CN/monitoring-usage#tool-output-span-event)，包含文件内容、Bash 输出以及 MCP 工具、WebFetch 和 WebSearch 返回的内容，默认在 60 KB 处截断，可通过 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 配置，需要 Claude Code v2.1.214 或更高版本。来自 MCP 工具、WebFetch 和 WebSearch 的结果需要 Claude Code v2.1.283 或更高版本。需要启用[跟踪](#read-agent-traces)。跨度属性在[其自己的门控](/docs/zh-CN/monitoring-usage#new-context-gates)下携带工具内容 |

251| `OTEL_LOG_RAW_API_BODIES` | 完整的 Anthropic Messages API 请求和响应 JSON 作为 `claude_code.api_request_body` 和 `claude_code.api_response_body` 日志事件。设置为 `1` 表示在 60 KB 处截断的内联体，或 `file:<dir>` 表示磁盘上的未截断体，事件中有 `body_ref` 路径。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 配置内联截断限制，需要 Claude Code v2.1.214 或更高版本。体包括整个对话历史记录，扩展思考内容被编辑。启用此项意味着同意上述三个变量将揭示的所有内容 |251| `OTEL_LOG_RAW_API_BODIES` | 完整的 Anthropic Messages API 请求和响应 JSON 作为 `claude_code.api_request_body` 和 `claude_code.api_response_body` 日志事件。设置为 `1` 表示在 60 KB 处截断的内联体，或 `file:<dir>` 表示磁盘上的未截断体，事件中有 `body_ref` 路径。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 配置内联截断限制，需要 Claude Code v2.1.214 或更高版本。体包括整个对话历史记录，扩展思考内容被编辑。启用此项意味着同意上述三个变量将揭示的所有内容 |

252 252

253除非您的可观测性管道被批准存储您的代理处理的数据，否则请不要设置这些。有关完整的属性列表和编辑行为，请参阅监控参考中的[安全和隐私](/docs/zh-CN/monitoring-usage#security-and-privacy)。253除非您的可观测性管道被批准存储您的代理处理的数据，否则请不要设置这些。有关完整的属性列表和编辑行为，请参阅监控参考中的[安全和隐私](/docs/zh-CN/monitoring-usage#security-and-privacy)。

agent-sdk/permissions.md +7 −3

Details

41 </Step>41 </Step>

42 42

43 <Step title="允许规则">43 <Step title="允许规则">

44 检查 `allow` 规则（来自 `allowed_tools` 和 settings.json）。如果规则匹配，工具被批准。工具自己批准的调用也在此步骤被解决，无需规则：例如在您的工作目录内的文件读取或 [只读 Bash 命令](/docs/zh-CN/permissions#read-only-commands)。针对 [关键路径](/docs/zh-CN/permission-modes#critical-paths) 的 `rm` 和 `rmdir` 删除永远不会被允许规则批准：它们在提示的模式下到达您的回调，在 Claude Code v2.1.218 或更高版本的 `auto` 模式下转到 [分类器](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)，并在 `dontAsk` 模式下被拒绝。44 检查 `allow` 规则（来自 `allowed_tools` 和 settings.json）。如果规则匹配，工具被批准。工具自己批准的调用也在此步骤被解决，无需规则：例如在您的工作目录内的文件读取或 [只读 Bash 命令](/docs/zh-CN/permissions#read-only-commands)。

46 针对 [关键路径](/docs/zh-CN/permission-modes#critical-paths) 的 `rm` 和 `rmdir` 删除永远不会被允许规则批准。它们是否随后到达您的回调取决于权限模式：例如在 `auto` 模式的 Agent SDK 会话中，Claude Code 默认拒绝它们而不调用它。[关键路径](/docs/zh-CN/permission-modes#critical-paths) 模式表列出了每种模式对它们的处理方式。

45 </Step>47 </Step>

46 48

47 <Step title="canUseTool 回调">49 <Step title="canUseTool 回调">

89使用 `//path` 表示绝对文件系统路径：`Edit(//secrets/**)` 的拒绝规则会阻止在磁盘上 `/secrets` 下任何位置的写入。使用单个前导斜杠时，`Edit(/secrets/**)` 在规则的源处锚定。对于通过 `allowed_tools` 或 `disallowed_tools` 传递的规则，这意味着会话的工作目录，因此规则不会阻止磁盘上的 `/secrets`。请参阅 [Read 和 Edit 规则](/docs/zh-CN/permissions#read-and-edit) 了解四种锚定形式以及来自设置文件的规则如何解析。91使用 `//path` 表示绝对文件系统路径：`Edit(//secrets/**)` 的拒绝规则会阻止在磁盘上 `/secrets` 下任何位置的写入。使用单个前导斜杠时，`Edit(/secrets/**)` 在规则的源处锚定。对于通过 `allowed_tools` 或 `disallowed_tools` 传递的规则，这意味着会话的工作目录，因此规则不会阻止磁盘上的 `/secrets`。请参阅 [Read 和 Edit 规则](/docs/zh-CN/permissions#read-and-edit) 了解四种锚定形式以及来自设置文件的规则如何解析。

90 92

91<Warning>93<Warning>

92 **自动批准的工具永远不会到达 `canUseTool`。** 在任何早期步骤中被批准的工具调用，通过 `acceptEdits` 或 `bypassPermissions`，或通过允许规则，会跳过你的 `canUseTool` 回调，因此你在那里放置的权限检查会被该工具无声地绕过。`AskUserQuestion`、标记为 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具、连接器工具[你的组织设置为 `ask`](/docs/zh-CN/mcp#organization-controls-on-connector-tools)，以及针对[关键路径](/docs/zh-CN/permission-modes#critical-paths)的 `rm` 和 `rmdir` 移除仍然会到达回调，即使允许规则匹配。在 `auto` 模式中，关键路径移除会进入[分类器](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)而不是回调，而上面列出的其他调用仍然会到达它；分类器路由需要 Claude Code v2.1.218 或更高版本。在 `dontAsk` 模式中，这些调用会被拒绝，不会调用回调。94 **自动批准的工具永远不会到达 `canUseTool`。** 在任何早期步骤中被批准的工具调用，通过 `acceptEdits` 或 `bypassPermissions`，或通过允许规则，会跳过你的 `canUseTool` 回调，因此你在那里放置的权限检查会被该工具无声地绕过。

96 允许规则永远不会自动批准 `AskUserQuestion`、标记为 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具、连接器工具[你的组织设置为 `ask`](/docs/zh-CN/mcp#organization-controls-on-connector-tools)，或针对[关键路径](/docs/zh-CN/permission-modes#critical-paths)的 `rm` 和 `rmdir` 移除。在 `dontAsk` 模式中，Claude Code 拒绝这些调用而不调用回调。在其他模式中，前三个会到达回调。根据[权限模式](/docs/zh-CN/permission-modes#critical-paths)，关键路径移除要么到达回调，要么 Claude Code 拒绝它而不调用它，就像它在 `auto` 模式中对 Agent SDK 会话默认做的那样。

93 97

94 覆盖范围取决于条目的形式：像 `Read` 或 `mcp__github__get_issue` 这样的裸名称会自动批准对该工具的每个调用，除了上面列出的例外，而像 `Bash(npm test *)` 这样的限定规则仅自动批准匹配的调用，其他需要批准的 `Bash` 调用仍然会进入回调。对于必须在每个工具调用上运行的检查，使用 [`PreToolUse` hook](/docs/zh-CN/agent-sdk/hooks)：hooks 在每个其他步骤之前运行，hook 拒绝即使在 `bypassPermissions` 模式中也适用。98 覆盖范围取决于条目的形式：像 `Read` 或 `mcp__github__get_issue` 这样的裸名称会自动批准对该工具的每个调用，除了上面列出的例外，而像 `Bash(npm test *)` 这样的限定规则仅自动批准匹配的调用，其他需要批准的 `Bash` 调用仍然会进入回调。对于必须在每个工具调用上运行的检查，使用 [`PreToolUse` hook](/docs/zh-CN/agent-sdk/hooks)：hooks 在每个其他步骤之前运行，hook 拒绝即使在 `bypassPermissions` 模式中也适用。

95</Warning>99</Warning>

301 305

302在规划模式下，文件编辑永远不会自动批准，即使允许规则匹配。它们会通过您的 `canUseTool` 回调提示。在 Claude Code v2.1.212 或更高版本上，修改文件的 shell 命令（如 `touch` 和 `rm`）会以相同方式到达您的 `canUseTool` 回调。306在规划模式下，文件编辑永远不会自动批准，即使允许规则匹配。它们会通过您的 `canUseTool` 回调提示。在 Claude Code v2.1.212 或更高版本上，修改文件的 shell 命令（如 `touch` 和 `rm`）会以相同方式到达您的 `canUseTool` 回调。

303 307

304如果您在 `permissionMode: 'plan'` 旁边设置 `allowDangerouslySkipPermissions: true`，文件编辑和修改文件的 shell 命令仍然会到达您的 `canUseTool` 回调。该选项让您稍后可以使用 `setPermissionMode()` 切换到 `bypassPermissions`。308在 TypeScript SDK 中，如果您在 `permissionMode: 'plan'` 旁边设置 `allowDangerouslySkipPermissions: true`，文件编辑和修改文件的 shell 命令仍然会到达您的 `canUseTool` 回调。该选项让您稍后可以使用 `setPermissionMode()` 切换到 `bypassPermissions`。

305 309

306Claude 可能会使用 `AskUserQuestion` 在最终确定计划之前澄清需求。有关处理这些提示的信息，请参阅[处理批准和用户输入](/docs/zh-CN/agent-sdk/user-input#handle-clarifying-questions)。310Claude 可能会使用 `AskUserQuestion` 在最终确定计划之前澄清需求。有关处理这些提示的信息，请参阅[处理批准和用户输入](/docs/zh-CN/agent-sdk/user-input#handle-clarifying-questions)。

307 311

agent-sdk/plugins.md +1 −1

Details

331 Plugin 未加载331 Plugin 未加载

332</h3>332</h3>

333 333

334如果你的 plugin 未出现在初始化消息中：334如果你的 plugin 未出现在初始化消息的 `plugins` 列表中，请检查其 [`plugin_errors`](/docs/zh-CN/agent-sdk/typescript#sdksystemmessage) 字段以了解原因，然后按照以下检查步骤进行：

335 335

3361. **检查路径**：确保路径指向 plugin 根目录，即 `skills/`、`agents/`、`hooks/`、`commands/` 或 `.claude-plugin/` 的父目录3361. **检查路径**：确保路径指向 plugin 根目录，即 `skills/`、`agents/`、`hooks/`、`commands/` 或 `.claude-plugin/` 的父目录

3372. **验证 plugin.json**：如果你的 plugin 包含清单文件，确保它具有有效的 JSON 语法3372. **验证 plugin.json**：如果你的 plugin 包含清单文件，确保它具有有效的 JSON 语法

agent-sdk/python.md +37 −35

Details

44 函数44 函数

45</h2>45</h2>

46 46

~~47<Note>此页面上的签名块和裸 `async for` / `async with` 片段仅供说明。要运行它们，请将主体包装在 `async def main(): ...` 中并调用 `asyncio.run(main())`。</Note>~~47<Note>此页面上的签名块和裸 `async for` / `async with` 片段仅供说明之用。要运行它们，请将主体包装在 `async def main(): ...` 中并调用 `asyncio.run(main())`。</Note>

48 48

49<h3 id="query">49<h3 id="query">

50 `query()`50 `query()`

51</h3>51</h3>

52 52

53为每次与 Claude Code 的交互创建一个新会话。默认情况下返回一个异步迭代器，当消息到达时产生消息。每次调用 `query()` 都会重新开始，不记得之前的交互，除非你传递 `continue_conversation=True` 或在 [`ClaudeAgentOptions`](#claudeagentoptions) 中传递 `resume`。参见 [Sessions](/docs/zh-CN/agent-sdk/sessions)。53默认情况下，为与 Claude Code 的每次交互创建一个新会话。返回一个异步迭代器，在消息到达时产生消息。每次调用 `query()` 都会重新开始，除非您在 [`ClaudeAgentOptions`](#claudeagentoptions) 中传递 `continue_conversation=True` 或 `resume`，否则不会记住之前的交互。请参阅 [Sessions](/docs/zh-CN/agent-sdk/sessions)。

54 54

55```python theme={null}55```python theme={null}

56async def query(56async def query(

73 73

74<h4 id="returns">74<h4 id="returns">

~~75 返回~~75 返回值

76</h4>76</h4>

77 77

78返回一个 `AsyncIterator[Message]`，从对话中产生消息。78返回一个 `AsyncIterator[Message]`，从对话中产生消息。

122| :- | :- | :- |122| :- | :- | :- |

123| `name` | `str` | 工具的唯一标识符 |123| `name` | `str` | 工具的唯一标识符 |

124| `description` | `str` | 工具功能的人类可读描述 |124| `description` | `str` | 工具功能的人类可读描述 |

127 127

128<h4 id="input-schema-options">128<h4 id="input-schema-options">

129 输入模式选项129 输入架构选项

130</h4>130</h4>

131 131

1321. **简单类型映射**（推荐）：1321. **简单类型映射**（推荐）：

148 ```148 ```

149 149

150<h4 id="returns-2">150<h4 id="returns-2">

151 返回151 返回值

152</h4>152</h4>

153 153

154一个装饰器函数，包装工具实现并返回一个 `SdkMcpTool` 实例。154一个装饰器函数，包装工具实现并返回一个 `SdkMcpTool` 实例。

171 `ToolAnnotations`171 `ToolAnnotations`

172</h4>172</h4>

173 173

174工具的行为提示，作为 [`tool()`](#tool) 的 `annotations` 参数传递。`ToolAnnotations` 扩展了 MCP SDK 的 `mcp.types.ToolAnnotations`，添加了 `maxResultSizeChars` 字段，你可以用 camelCase 或 snake\_case 编写每个提示：`ToolAnnotations(readOnlyHint=True)` 和 `ToolAnnotations(read_only_hint=True)` 是等价的。你也可以在 SDK 接受注解的任何地方传递普通的 `mcp.types.ToolAnnotations`。174工具的行为提示，作为 [`tool()`](#tool) 的 `annotations` 参数传递。`ToolAnnotations` 扩展了 MCP SDK 的 `mcp.types.ToolAnnotations`，添加了 `maxResultSizeChars` 字段，您可以用 camelCase 或 snake\_case 编写每个提示：`ToolAnnotations(readOnlyHint=True)` 和 `ToolAnnotations(read_only_hint=True)` 是等效的。您也可以在 SDK 接受注解的任何地方传递普通的 `mcp.types.ToolAnnotations`。

175 175

176snake\_case 名称和类型化的 `maxResultSizeChars` 字段需要 Python Agent SDK 0.2.140 或更高版本。版本 0.1.31 到 0.2.139 重新导出 `mcp.types.ToolAnnotations` 不变。在版本 0.1.55 到 0.2.139 上，你仍然可以将 `maxResultSizeChars` 作为关键字参数传递：MCP 类接受额外字段，SDK 将值转发给 Claude Code。176snake\_case 名称和类型化的 `maxResultSizeChars` 字段需要 Python Agent SDK 0.2.140 或更高版本。版本 0.1.31 到 0.2.139 重新导出 `mcp.types.ToolAnnotations` 不变。在版本 0.1.55 到 0.2.139 上，您仍然可以将 `maxResultSizeChars` 作为关键字参数传递：MCP 类接受额外字段，SDK 将值转发给 Claude Code。

177 177

178所有字段都是可选的。客户端不应依赖这些提示做出安全决策。178所有字段都是可选的。客户端不应依赖这些提示来做出安全决策。

179 179

180| 字段 | 类型 | 默认值 | 描述 |180| 字段 | 类型 | 默认值 | 描述 |

181| :- | :- | :- | :- |181| :- | :- | :- | :- |

187| `maxResultSizeChars` | `int \| None` | `None` | Claude Code 将此工具的文本结果保持内联在对话中而不是保存到文件的字符数，最多 500,000。包含图像的结果不受影响。Claude Code 设置而不是 MCP 提示：SDK 在工具的 `_meta` 中以 `anthropic/maxResultSizeChars` 形式发送它。参见 [为特定工具提高限制](/docs/zh-CN/mcp#raise-the-limit-for-a-specific-tool) |187| `maxResultSizeChars` | `int \| None` | `None` | Claude Code 将此工具的文本结果保持内联在对话中而不是保存到文件的字符数，最多 500,000。包含图像的结果不受影响。Claude Code 设置而不是 MCP 提示：SDK 在工具的 `_meta` 中以 `anthropic/maxResultSizeChars` 的形式发送它。请参阅 [提高特定工具的限制](/docs/zh-CN/mcp#raise-the-limit-for-a-specific-tool) |

188 188

189```python theme={null}189```python theme={null}

190from claude_agent_sdk import tool, ToolAnnotations190from claude_agent_sdk import tool, ToolAnnotations

227 227

228<h4 id="returns-3">228<h4 id="returns-3">

229 返回229 返回值

230</h4>230</h4>

231 231

232返回一个 `McpSdkServerConfig` 对象，可以传递给 `ClaudeAgentOptions.mcp_servers`。232返回一个 `McpSdkServerConfig` 对象，可以传递给 `ClaudeAgentOptions.mcp_servers`。

266 `list_sessions()`266 `list_sessions()`

267</h3>267</h3>

268 268

269列出带有元数据的过去会话。按项目目录过滤或列出所有项目中的会话。同步；立即返回。269列出过去的会话及其元数据。按项目目录筛选或列出所有项目中的会话。同步；立即返回。

270 270

271```python theme={null}271```python theme={null}

272def list_sessions(272def list_sessions(

283 283

284| 参数 | 类型 | 默认值 | 描述 |284| 参数 | 类型 | 默认值 | 描述 |

285| :- | :- | :- | :- |285| :- | :- | :- | :- |

288| `offset` | `int` | `0` | 从排序结果开始跳过的会话数。与 `limit` 一起用于分页 |288| `offset` | `int` | `0` | 从排序结果开始跳过的会话数。与 `limit` 一起用于分页 |

290 290

291<h4 id="return-type-sdksessioninfo">291<h4 id="return-type-sdksessioninfo">

292 返回类型：`SDKSessionInfo`292 返回类型：`SDKSessionInfo`

295| 属性 | 类型 | 描述 |295| 属性 | 类型 | 描述 |

296| :- | :- | :- |296| :- | :- | :- |

297| `session_id` | `str` | 唯一会话标识符 |297| `session_id` | `str` | 唯一会话标识符 |

298| `summary` | `str` | 显示标题：自定义标题、自动生成的摘要或第一个提示 |298| `summary` | `str` | 显示标题：自定义标题、最近的提示、自动生成的摘要或第一个提示 |

299| `last_modified` | `int` | 上次修改时间（自纪元以来的毫秒数） |299| `last_modified` | `int` | 上次修改时间，以自纪元以来的毫秒为单位 |

304| `cwd` | `str \| None` | 会话的工作目录 |304| `cwd` | `str \| None` | 会话的工作目录 |

305| `tag` | `str \| None` | 用户设置的会话标签（见 [`tag_session()`](#tag_session)） |305| `tag` | `str \| None` | 用户设置的会话标签（请参阅 [`tag_session()`](#tag_session)） |

307 307

308<h4 id="example-3">308<h4 id="example-3">

309 示例309 示例

310</h4>310</h4>

311 311

312打印项目的 10 个最近会话。结果按 `last_modified` 降序排序，所以第一项是最新的。省略 `directory` 以搜索所有项目。312打印项目的 10 个最近会话。结果按 `last_modified` 降序排序，因此第一项是最新的。省略 `directory` 以搜索所有项目。

313 313

314```python theme={null}314```python theme={null}

315from claude_agent_sdk import list_sessions315from claude_agent_sdk import list_sessions

340| 参数 | 类型 | 默认值 | 描述 |340| 参数 | 类型 | 默认值 | 描述 |

341| :- | :- | :- | :- |341| :- | :- | :- | :- |

342| `session_id` | `str` | 必需 | 要检索消息的会话 ID |342| `session_id` | `str` | 必需 | 要检索消息的会话 ID |

345| `offset` | `int` | `0` | 从开始跳过的消息数 |345| `offset` | `int` | `0` | 从开始跳过的消息数 |

346 346

347<h4 id="return-type-sessionmessage">347<h4 id="return-type-sessionmessage">

355| `session_id` | `str` | 会话标识符 |355| `session_id` | `str` | 会话标识符 |

356| `message` | `Any` | 原始消息内容 |356| `message` | `Any` | 原始消息内容 |

359 359

360<h4 id="example-4">360<h4 id="example-4">

361 示例361 示例

399 示例399 示例

400</h4>400</h4>

401 401

402查找单个会话的元数据，无需扫描项目目录。当你已经从之前的运行中获得会话 ID 时很有用。402查找单个会话的元数据，无需扫描项目目录。当您已经从之前的运行中获得会话 ID 时很有用。

403 403

404```python theme={null}404```python theme={null}

405from claude_agent_sdk import get_session_info405from claude_agent_sdk import get_session_info

413 `rename_session()`413 `rename_session()`

414</h3>414</h3>

415 415

416通过追加自定义标题条目来重命名会话。重复调用是安全的；最新的标题获胜。同步。416通过附加自定义标题条目来重命名会话。重复调用是安全的；最新的标题获胜。同步。

417 417

418```python theme={null}418```python theme={null}

419def rename_session(419def rename_session(

439 示例439 示例

440</h4>440</h4>

441 441

442重命名最近的会话，使其更容易找到。新标题在后续读取时出现在 [`SDKSessionInfo.custom_title`](#return-type-sdksessioninfo) 中。442重命名最近的会话，以便稍后更容易找到。新标题在后续读取时出现在 [`SDKSessionInfo.custom_title`](#return-type-sdksessioninfo) 中。

443 443

444```python theme={null}444```python theme={null}

445from claude_agent_sdk import list_sessions, rename_session445from claude_agent_sdk import list_sessions, rename_session

479 示例479 示例

480</h4>480</h4>

481 481

482标记会话，然后在稍后的读取中按该标签过滤。传递 `None` 以清除现有标签。482标记会话，然后在稍后的读取中按该标签筛选。传递 `None` 以清除现有标签。

483 483

484```python theme={null}484```python theme={null}

485from claude_agent_sdk import list_sessions, tag_session485from claude_agent_sdk import list_sessions, tag_session

875 include_partial_messages: bool = False875 include_partial_messages: bool = False

876 include_hook_events: bool = False876 include_hook_events: bool = False

877 forward_subagent_text: bool = False877 forward_subagent_text: bool = False

878 verbatim_prompts: bool = False

878 fork_session: bool = False879 fork_session: bool = False

879 resume_session_at: str | None = None880 resume_session_at: str | None = None

880 resume_drops_turn: str | None = None881 resume_drops_turn: str | None = None

932| `verbatim_prompts` | `bool` | `False` | 按照书写方式传递每个提示。SDK 使用 `client_composed` 设置为 `True` 发送每条用户消息。见 [`client_composed`](/docs/zh-CN/agent-sdk/typescript#sdkusermessage) 了解 Claude Code 在这些消息上跳过的内容。当你的提示文本包含最终用户未输入的内容时使用此选项。对于每轮控制，将其关闭并改为在单个流式消息上设置 `"client_composed": True`。启用此选项时，SDK 会覆盖你设置的任何 `client_composed` 值。需要 Python Agent SDK 0.2.158 或更高版本以及 Claude Code v2.1.248 或更高版本；这些 SDK 版本附带的 CLI 满足 Claude Code 要求 |

1010| `type` | 是 | 必须是 `"preset"` 以使用预设系统提示 |1012| `type` | 是 | 必须是 `"preset"` 以使用预设系统提示 |

1011| `preset` | 是 | 必须是 `"claude_code"` 以使用 Claude Code 的系统提示 |1013| `preset` | 是 | 必须是 `"claude_code"` 以使用 Claude Code 的系统提示 |

1012| `append` | 否 | 要追加到预设系统提示的其他说明 |1014| `append` | 否 | 要追加到预设系统提示的其他说明 |

1013| `exclude_dynamic_sections` | 否 | 将每个会话的上下文（如工作目录、git 状态和自动内存路径）从系统提示移到第一条用户消息。改进跨用户和机器的提示缓存重用。见 [修改系统提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |1015| `exclude_dynamic_sections` | 否 | 将每个会话的上下文（如自动内存位置）从系统提示移到第一条用户消息。改进跨用户和机器的提示缓存重用。见 [修改系统提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

1014| `snapshot` | 否 | 设置为 `False` 以在每个请求上重建系统提示，而不是[重用会话在其第一个请求上记录的提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)。需要 `claude-agent-sdk` v0.2.153 或更高版本 |1016| `snapshot` | 否 | 设置为 `False` 以在每个请求上重建系统提示，而不是[重用会话在其第一个请求上记录的提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)。需要 `claude-agent-sdk` v0.2.153 或更高版本 |

1015 1017

1016<h3 id="systempromptcustom">1018<h3 id="systempromptcustom">

1221 "plan", # Planning mode - explore without editing1223 "plan", # Planning mode - explore without editing

1222 "dontAsk", # Deny anything not pre-approved instead of prompting1224 "dontAsk", # Deny anything not pre-approved instead of prompting

1223 "bypassPermissions", # Bypass permission checks; explicit ask rules still prompt (use with caution)1225 "bypassPermissions", # Bypass permission checks; explicit ask rules still prompt (use with caution)

1224 "auto", # Model classifier approves or denies permission prompts1226 "auto", # A model classifier reviews actions such as shell commands and network requests

1225]1227]

1226```1228```

1227 1229

3791<Warning>3793<Warning>

3792 使用 `dangerouslyDisableSandbox: True` 运行的命令具有完整的系统访问权限。确保你的 `can_use_tool` 处理程序仔细验证这些请求。3794 使用 `dangerouslyDisableSandbox: True` 运行的命令具有完整的系统访问权限。确保你的 `can_use_tool` 处理程序仔细验证这些请求。

3793 3795

3794 如果 `permission_mode` 设置为 `bypassPermissions` 且 `allow_unsandboxed_commands` 启用，模型可以自主执行沙箱外的命令，无需批准提示，除了 [操作无模式自动批准](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves) 之外。此组合实际上允许模型无声地逃离沙箱隔离。3796 如果 `permission_mode` 设置为 `bypassPermissions` 且 `allowUnsandboxedCommands` 启用，模型可以自主执行沙箱外的命令，无需批准提示，除了 [操作无模式自动批准](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves) 之外。此组合实际上允许模型无声地逃离沙箱隔离。

3795</Warning>3797</Warning>

3796 3798

3797<h2 id="see-also">3799<h2 id="see-also">

agent-sdk/streaming-output.md +1 −1

Details

330 已知限制330 已知限制

331</h2>331</h2>

332 332

333* **结构化输出**：JSON 结果仅出现在最终 `ResultMessage.structured_output` 中，而不是作为流式增量。有关详细信息，请参阅[结构化输出](/docs/zh-CN/agent-sdk/structured-outputs)。333* **结构化输出**：启用部分消息时，JSON 作为工具调用的未验证 `input_json_delta` 块进行流式传输，只有验证后的结果才会到达最终的 `ResultMessage.structured_output`。有关详细信息，请参阅[结构化输出](/docs/zh-CN/agent-sdk/structured-outputs)。

334 334

335<h2 id="next-steps">335<h2 id="next-steps">

336 后续步骤336 后续步骤

agent-sdk/troubleshooting.md +1 −1

Details

162 structured\_output is None but the result says success162 structured\_output is None but the result says success

163</h3>163</h3>

164 164

165结果消息可以以 `subtype: "success"` 结尾，而在 Python 中 `structured_output` 是 `None` 或在 TypeScript 中是 `undefined`。运行完成，但不存在经过验证的输出。一种方式是模式无法满足任何输出，例如冲突的长度约束。运行结束时没有验证错误，唯一的信号是缺失的 `structured_output`。165结果消息可以以 `subtype: "success"` 结尾，而在 Python 中 `structured_output` 是 `None` 或在 TypeScript 中是 `undefined`。运行完成，但不存在经过验证的输出。一种方式是模式无法满足任何输出，例如冲突的长度约束。

166 166

167在应用程序代码中将此结果视为失败。在使用 `structured_output` 之前，检查 `subtype` 是否为 `success` 以及 `structured_output` 是否存在。[错误处理](/docs/zh-CN/agent-sdk/structured-outputs#error-handling) 部分为两个 SDK 显示了此模式。167在应用程序代码中将此结果视为失败。在使用 `structured_output` 之前，检查 `subtype` 是否为 `success` 以及 `structured_output` 是否存在。[错误处理](/docs/zh-CN/agent-sdk/structured-outputs#error-handling) 部分为两个 SDK 显示了此模式。

168 168

agent-sdk/typescript.md +245 −22

Details

54* 要进行交叉编译，请安装不匹配的平台包，例如 `npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force`。54* 要进行交叉编译，请安装不匹配的平台包，例如 `npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force`。

55* 在 Windows 上，二进制文件子路径是 `claude.exe`，例如 `@anthropic-ai/claude-agent-sdk-win32-x64/claude.exe`。55* 在 Windows 上，二进制文件子路径是 `claude.exe`，例如 `@anthropic-ai/claude-agent-sdk-win32-x64/claude.exe`。

56 56

57<h3 id="import-the-/core-entry-when-you-bundle-the-agent-sdk">

58 在捆绑 Agent SDK 时导入 `/core` 入口

59</h3>

61如果您的应用程序将 Agent SDK 与其自己的依赖项一起捆绑，请从 `@anthropic-ai/claude-agent-sdk/core` 而不是包根目录导入。`/core` 入口需要 TypeScript Agent SDK v0.3.282 或更高版本，其类型需要 TypeScript 5.0 或更高版本。

63`/core` 入口导出与根入口相同的 `query()`、`startup()`、`tool()`、`createSdkMcpServer()` 和 `resolveSettings()`，以及重命名、标记和删除会话的函数、`AbortError`、运行时常量和每种类型。它不添加自己的名称。为了保持应用程序加载的代码较小，`/core` 省略了一些根导出，包括 `prewarm()`、`InMemorySessionStore` 类以及列出、读取、分叉、导入和总结会话的辅助函数。如果您需要其中之一，请改用根入口。

65根入口内联了自己的 `zod` 和 `@modelcontextprotocol/sdk` 副本。`/core` 入口从您的 `node_modules` 按照 Agent SDK 的 `peerDependencies` 声明的范围导入它们，因此已经包含它们的捆绑包不会携带第二个副本。在给定的进程中从根或 `/core` 导入，而不是两者：它们是单独的捆绑包，加载两者会给您两个 Agent SDK 类和状态的副本。

57<h2 id="functions">67<h2 id="functions">

58 函数68 函数

59</h2>69</h2>

93 `startup()`103 `startup()`

94</h3>104</h3>

95 105

96通过生成 CLI 子进程并在提示可用之前完成初始化握手来预热 CLI 子进程。返回的 [`WarmQuery`](#warmquery) 句柄稍后接受提示并将其写入已准备好的进程，因此第一个 `query()` 调用解析时无需支付子进程生成和初始化成本。106通过生成 CLI 子进程并在提示可用之前完成初始化握手来预热 CLI 子进程。返回的 [`WarmQuery`](#warmquery) 句柄稍后接受提示并将其写入已准备好的进程，因此第一个 `query()` 调用解析时无需支付子进程生成和初始化成本。如果您还不知道会话的工作目录，请改用 [`prewarm()`](#prewarm)。

97 107

98```typescript theme={null}108```typescript theme={null}

99function startup(params?: {109function startup(params?: {

135}145}

136```146```

137 147

148<h3 id="prewarm">

149 `prewarm()`

150</h3>

151

152*Alpha。* 在您知道它将服务哪个会话之前启动 Claude Code 进程作为备用，以便您稍后可以使用 [`claim()`](#spareprocess) 将其绑定到会话。在应用程序启动之前用户选择文件夹的应用程序中使用它。需要 TypeScript Agent SDK v0.3.282 或更高版本。

153

154`prewarm()` 完成与 [`startup()`](#startup) 相同的初始化握手，当您设置 `options.cwd` 时进程在其中等待，否则在 Claude Code 配置目录下的私有临时目录中等待。会话的工作目录、其 `SessionStart` hooks、其 stdio MCP 服务器以及其 CLAUDE.md 和 git 上下文等待声明。备用进程在等待时占用大约 230 到 260 MB 的内存。如果您的 [`spawnClaudeCodeProcess`](#options) 在另一台机器或容器中运行 Claude Code，请将 `options.cwd` 设置为存在于那里的目录，以便备用进程在其中等待。

155

156```typescript theme={null}

157function prewarm(params?: {

158 options?: Options;

159 initializeTimeoutMs?: number;

160}): Promise<SpareProcess>;

161```

162

163`options` 和 `initializeTimeoutMs` 的含义与 `startup()` 相同，除了 `options.cwd` 仅设置备用进程等待的目录。promise 在进程完成其初始化握手后使用 [`SpareProcess`](#spareprocess) 解析。如果 `options` 设置 `resume`、`continue` 或 `forkSession`，`prewarm()` 会抛出错误，因为备用进程还没有会话。声明无法设置的所有内容，例如 `mcpServers`、`hooks`、`canUseTool`、`settingSources`、`systemPrompt` 和 `plugins`，在备用进程的生命周期内是固定的，因此为每个不同的选项集保留一个备用进程，并在它们更改时再次预热。

164

165<h4 id="example-2">

166 示例

167</h4>

168

169在应用程序启动时预热，然后在用户启动会话时声明备用进程：

170

171```typescript theme={null}

172import { prewarm } from "@anthropic-ai/claude-agent-sdk";

173

174// 在应用程序启动时，在会话的文件夹已知之前

175const spare = await prewarm({ options: { maxTurns: 3 } });

176

177// 稍后，当用户在文件夹中启动会话时

178const claimedQuery = spare.claim({

179 prompt: "What files are here?",

180 options: { cwd: "/path/to/project" },

181});

182

183spare.claimed.catch((error: Error) => {

184 // 除非消息以 "option_not_applied" 开头，否则提示未运行：

185 // 改为使用 query() 启动此会话

186 console.error("Claim failed:", error.message);

187});

188

189for await (const message of claimedQuery) {

190 console.log(message);

191}

192```

193

138<h3 id="tool">194<h3 id="tool">

139 `tool()`195 `tool()`

140</h3>196</h3>

249| 属性 | 类型 | 描述 |305| 属性 | 类型 | 描述 |

250| :- | :- | :- |306| :- | :- | :- |

261 317

262<h4 id="example-2">318<h4 id="example-3">

263 示例319 示例

264</h4>320</h4>

265 321

314 370

315<h4 id="example-3">371<h4 id="example-4">

316 示例372 示例

317</h4>373</h4>

318 374

453| `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | 每个源的原始设置，按从最低到最高优先级排序 |509| `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | 每个源的原始设置，按从最低到最高优先级排序 |

454 510

455<h4 id="example-4">511<h4 id="example-5">

456 示例512 示例

457</h4>513</h4>

458 514

547| `toolAliases` | `Record<string, string>` | `undefined` | 将内置工具名称映射到 MCP 工具名称，以便 Claude 调用您的 MCP 实现而不是内置工具。例如，`{ Bash: 'mcp__workspace__bash' }` |603| `toolAliases` | `Record<string, string>` | `undefined` | 将内置工具名称映射到 MCP 工具名称，以便 Claude 调用您的 MCP 实现而不是内置工具。例如，`{ Bash: 'mcp__workspace__bash' }` |

549| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | 工具配置。传递工具名称数组或使用预设获取 Claude Code 的默认工具 |605| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | 工具配置。传递工具名称数组或使用预设获取 Claude Code 的默认工具 |

606| `verbatimPrompts` | `boolean` | `false` | 按照书写方式传递每个提示。SDK 使用 `client_composed: true` 发送每条用户消息。请参阅 [`client_composed`](#sdkusermessage) 了解 Claude Code 在这些消息上跳过的内容。当您的提示文本包含最终用户未输入的内容时使用此选项。对于每轮控制，请将其关闭并改为在各个流式消息上设置 `client_composed`。需要 TypeScript Agent SDK v0.3.280 或更高版本和 Claude Code v2.1.248 或更高版本；这些 SDK 版本捆绑的 Claude Code 版本满足 Claude Code 要求 |

550 607

551<h4 id="handle-slow-or-stalled-api-responses">608<h4 id="handle-slow-or-stalled-api-responses">

552 处理缓慢或停滞的 API 响应609 处理缓慢或停滞的 API 响应

617 path: string,674 path: string,

618 options?: { maxBytes?: number; encoding?: 'utf-8' | 'base64' }675 options?: { maxBytes?: number; encoding?: 'utf-8' | 'base64' }

619 ): Promise<SDKControlReadFileResponse | null>;676 ): Promise<SDKControlReadFileResponse | null>;

677 reloadPlugins(options?: {

678 holdOnCacheImpact?: boolean;

679 }): Promise<SDKControlReloadPluginsResponse>;

620 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;680 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;

681 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;

621 accountInfo(): Promise<AccountInfo>;682 accountInfo(): Promise<AccountInfo>;

622 reconnectMcpServer(serverName: string): Promise<void>;683 reconnectMcpServer(serverName: string): Promise<void>;

623 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;684 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;

651| `getContextUsage(opts?)` | 返回 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)，按类别、skill 和工具分解会话的上下文窗口使用情况。使用默认 `detail`，它与 `/context` 在交互式会话中显示的数据相同。[`detail` 选项](#sdkcontrolgetcontextusageresponse)需要 Agent SDK v0.3.257 或更高版本 |712| `getContextUsage(opts?)` | 返回 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)，按类别、skill 和工具分解会话的上下文窗口使用情况。使用默认 `detail`，它与 `/context` 在交互式会话中显示的数据相同。[`detail` 选项](#sdkcontrolgetcontextusageresponse)需要 Agent SDK v0.3.257 或更高版本 |

652| `readFile(path, options?)` | 从会话的文件系统读取文件。Claude Code 根据 `cwd` 解析路径；[`readFile()` 可以读取什么](#what-readfile-can-read)列出它提供的文件。传递 `{ maxBytes }` 以更改读取上限（默认 1 MB，上限 10 MB）和 `{ encoding: 'base64' }` 用于二进制文件，如图像。使用 [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) 进行解决，或在权限拒绝、文件丢失或传输错误时使用 `null`。需要 TypeScript SDK v0.2.121 或更高版本 |713| `readFile(path, options?)` | 从会话的文件系统读取文件。Claude Code 根据 `cwd` 解析路径；[`readFile()` 可以读取什么](#what-readfile-can-read)列出它提供的文件。传递 `{ maxBytes }` 以更改读取上限（默认 1 MB，上限 10 MB）和 `{ encoding: 'base64' }` 用于二进制文件，如图像。使用 [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) 进行解决，或在权限拒绝、文件丢失或传输错误时使用 `null`。需要 TypeScript SDK v0.2.121 或更高版本 |

714| `reloadPlugins(options?)` | 从磁盘重新加载 plugins，以便您在会话中期安装或编辑的 plugins 到达运行的会话。使用 [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) 进行解决，列出会话的 commands、subagents、plugins 和 MCP 服务器状态。需要 Agent SDK v0.2.85 或更高版本。[`holdOnCacheImpact` 选项](#sdkcontrolreloadpluginsresponse)需要 Agent SDK v0.3.268 或更高版本 |

653| `reloadSkills()` | 从磁盘重新加载 skills，以便您在会话中期添加或编辑的 skills 对运行的会话可用。使用 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) 进行解决，列出重新加载后可用的 skills。需要 Agent SDK v0.3.163 或更高版本 |715| `reloadSkills()` | 从磁盘重新加载 skills，以便您在会话中期添加或编辑的 skills 对运行的会话可用。使用 [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) 进行解决，列出重新加载后可用的 skills。需要 Agent SDK v0.3.163 或更高版本 |

716| `reloadOutputStyles()` | 重新读取[输出样式](/docs/zh-CN/output-styles)从磁盘，以便您在会话中期添加或编辑的样式文件对运行的会话可用。使用 [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) 进行解决，列出重新加载后可用的样式名称。需要 Agent SDK v0.3.261 或更高版本 |

655| `reconnectMcpServer(serverName)` | 按名称重新连接 MCP 服务器。如果名称也匹配设置文件（如 `.mcp.json` 或 `~/.claude.json`）中的条目，Claude Code 会重新连接您通过 [`mcpServers`](#options) 或 `setMcpServers()` 配置的服务器，而不是设置文件条目。该解析顺序需要 Claude Code v2.1.257 或更高版本 |718| `reconnectMcpServer(serverName)` | 按名称重新连接 MCP 服务器。如果名称也匹配设置文件（如 `.mcp.json` 或 `~/.claude.json`）中的条目，Claude Code 会重新连接您通过 [`mcpServers`](#options) 或 `setMcpServers()` 配置的服务器，而不是设置文件条目。该解析顺序需要 Claude Code v2.1.257 或更高版本 |

672* **在当前轮次应用**：`model`。如果您在 Claude 处理轮次时切换 `model`，Claude 已在生成的响应在旧模型上完成，轮次的其余部分（从 Claude Code 对模型进行的下一个调用开始）使用新模型。Subagents 保持自己的模型。在 v2.1.212 之前，中期切换等待下一个轮次。735* **在当前轮次应用**：`model`。如果您在 Claude 处理轮次时切换 `model`，Claude 已在生成的响应在旧模型上完成，轮次的其余部分（从 Claude Code 对模型进行的下一个调用开始）使用新模型。Subagents 保持自己的模型。在 v2.1.212 之前，中期切换等待下一个轮次。

673* **会话中期无效**：系统提示选项。这些在启动时解决一次，因此运行的会话保持原始值，即使调用成功。要更改它们，请启动新会话。736* **会话中期无效**：系统提示选项。这些在启动时解决一次，因此运行的会话保持原始值，即使调用成功。要更改它们，请启动新会话。

674 737

675`effortLevel` 接受一个[努力级别](/docs/zh-CN/model-config#adjust-effort-level)名称。它也接受 `"ultracode"`，它请求 `xhigh` 努力与[ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)打开。`applyFlagSettings()` 声明 `effortLevel` 不包含该值，因此在 TypeScript 中传递等效的 `{ ultracode: true }`。`ultracode` 值需要 Claude Code v2.1.203 或更高版本，仅由 `applyFlagSettings()` 接受，不由设置文件中的 `effortLevel` 键接受。738`effortLevel` 接受一个[努力级别](/docs/zh-CN/model-config#adjust-effort-level)名称。它也接受 `"ultracode"`，它请求 `xhigh` 努力与[ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)打开。`applyFlagSettings()` 声明 `effortLevel` 不包含该值，因此在 TypeScript 中传递 `{ ultracode: true, effortLevel: "xhigh" }` 以获得相同的结果，或仅 [`ultracode`](/docs/zh-CN/settings-reference#ultracode) 键以在会话的当前努力级别打开 ultracode。`ultracode` 值需要 Claude Code v2.1.203 或更高版本，仅由 `applyFlagSettings()` 接受，不由设置文件中的 `effortLevel` 键接受。在 v2.1.284 之前，仅 `ultracode` 键也将级别设置为 `xhigh`。

676 739

677这些值被写入标志设置层，这是内联 `query()` 的 `settings` 选项在启动时填充的同一层。这与[优先级部分](#settings-precedence)称为编程选项的层相同。740这些值被写入标志设置层，这是内联 `query()` 的 `settings` 选项在启动时填充的同一层。这与[优先级部分](#settings-precedence)称为编程选项的层相同。

678 741

741 804

742`WarmQuery` 实现 `AsyncDisposable`，因此可以与 `await using` 一起使用以进行自动清理。805`WarmQuery` 实现 `AsyncDisposable`，因此可以与 `await using` 一起使用以进行自动清理。

743 806

807<h3 id="spareprocess">

808 `SpareProcess`

809</h3>

810

811*Alpha.* 由 [`prewarm()`](#prewarm) 返回的句柄：一个已启动的 Claude Code 进程，尚未绑定到会话，可以声明一次。需要 TypeScript Agent SDK v0.3.282 或更高版本。

812

813```typescript theme={null}

814interface SpareProcess extends AsyncDisposable {

815 claim(params: {

816 prompt: string | AsyncIterable<SDKUserMessage>;

817 options: ClaimOptions;

818 }): Query;

819 readonly claimed: Promise<{ cwd: string; sessionId: string; parkedMs?: number; sdkMcpSettled: boolean }>;

820 readonly exited: Promise<void>;

821 close(): void;

822}

823```

824

825<h4 id="members">

826 成员

827</h4>

828

829| 成员 | 描述 |

830| :- | :- |

831| `claim({ prompt, options })` | 将备用进程绑定到 `options.cwd` 中的会话并发送其第一条消息。同步返回 [`Query`](#query-object)，如 `query()` 一样。每个 `SpareProcess` 只能调用一次 |

832| `claimed` | 一旦 Claude Code 接受声明，就使用会话的工作目录和 ID 进行解决。当 Claude Code 拒绝声明、进程在声明前退出或关闭，以及当会话运行时不带您请求的 `model` 或 `maxThinkingTokens` 时拒绝，消息以 `option_not_applied` 开头。 |

833| `exited` | 当进程退出时解决，无论是否声明。替换在您声明前退出的备用进程 |

834| `close()` | 终止进程。在声明前，这会丢弃备用进程并拒绝 `claimed` |

835

836`options.cwd` 是必需的。声明也可以设置 `additionalDirectories`、`model`、`permissionMode`、`maxThinkingTokens`、`settings` 中的标志设置覆盖、`appendSystemPrompt`、`title`、`agents` 和 `env` 中的每个会话令牌。

837

838Claude Code 可以拒绝声明，例如对于不存在的文件夹或其项目设置设置 `env`、`agent` 或 `model` 的文件夹。当 `claimed` 拒绝消息以 `option_not_applied` 开头时，会话运行时不带您请求的 `model` 或 `maxThinkingTokens`。在任何其他拒绝后，您的提示尚未运行，因此改用 `query()` 启动会话。

839

744<h3 id="sdkcontrolinitializeresponse">840<h3 id="sdkcontrolinitializeresponse">

745 `SDKControlInitializeResponse`841 `SDKControlInitializeResponse`

746</h3>842</h3>

824 tokens: number;920 tokens: number;

825 color: string;921 color: string;

826 isDeferred?: boolean;922 isDeferred?: boolean;

923 kind: "used" | "free" | "buffer" | "deferred";

827 }[];924 }[];

828 totalTokens: number;925 totalTokens: number;

829 maxTokens: number;926 maxTokens: number;

913 1010

914从集合字段读取令牌归属：1011从集合字段读取令牌归属：

915 1012

916* `categories` 保存每个类别的总计。1013* `categories` 保存每个类别的总计。每个条目的 `kind` 使用与 [`SDKContextUsageCategory`](#sdkcontextusagecategory) 相同的值对行进行分类。在其上对行进行分类，而不是在显示 `name` 上。该字段需要 Agent SDK v0.3.268 或更高版本。

917* `mcpTools` 和 `agents` 将令牌归属于各个 MCP 工具和 subagents。1014* `mcpTools` 和 `agents` 将令牌归属于各个 MCP 工具和 subagents。

918* `memoryFiles` 列出每个加载的内存文件及其成本。1015* `memoryFiles` 列出每个加载的内存文件及其成本。

919* `skills.skillFrontmatter` 将 skill 列表的令牌归属于每个包含的 skill。每个 skill 的计数测量每个 skill 的列表条目，因为 Claude Code 实际发送它，这可能比 skill 的完整 frontmatter 更短。比较 `skills.totalSkills` 与 `skills.includedSkills` 以查看每个发现的 skill 是否进入列表。1016* `skills.skillFrontmatter` 将 skill 列表的令牌归属于每个包含的 skill。每个 skill 的计数测量每个 skill 的列表条目，因为 Claude Code 实际发送它，这可能比 skill 的完整 frontmatter 更短。比较 `skills.totalSkills` 与 `skills.includedSkills` 以查看每个发现的 skill 是否进入列表。

950 1047

951Read deny 和 ask 规则仍然阻止匹配的路径，广泛的 Read allow 规则不会向 `readFile()` 打开文件系统的其余部分。对于任何其他内容，调用使用 `null` 进行解决。1048Read deny 和 ask 规则仍然阻止匹配的路径，广泛的 Read allow 规则不会向 `readFile()` 打开文件系统的其余部分。对于任何其他内容，调用使用 `null` 进行解决。

952 1049

1050<h3 id="sdkcontrolreloadpluginsresponse">

1051 `SDKControlReloadPluginsResponse`

1052</h3>

1053

1054[`reloadPlugins()`](#query-object) 的返回类型。

1055

1056```typescript theme={null}

1057type SDKControlReloadPluginsResponse = {

1058 commands: SlashCommand[];

1059 agents: AgentInfo[];

1060 plugins: {

1061 name: string;

1062 path: string;

1063 source?: string;

1064 version?: string;

1065 }[];

1066 mcpServers: McpServerStatus[];

1067 error_count: number;

1068 held?: boolean;

1069 cache_impact?: {

1070 mcp_servers_added: string[];

1071 mcp_servers_removed: string[];

1072 lsp_tool_change: ("adds" | "may-add" | "removes" | "may-remove") | null;

1073 };

1074};

1075```

1076

1077集合字段描述调用后的会话：

1078

1079* `commands`、`agents` 和 `mcpServers`：会话的 commands、subagents 和 MCP 服务器状态，采用 `supportedCommands()`、`supportedAgents()` 和 `mcpServerStatus()` 返回的相同形状。`supportedAgents()` 继续返回在初始化时捕获的列表，因此在此处读取 `agents` 以获取重新加载后的集合

1080* `plugins`：每个加载的 plugin，其 `name` 和安装 `path`。`version` 重复 plugin 的 manifest 声明的内容，是 plugin 作者控制的，因此在信任之前验证它。当 manifest 未声明任何内容时省略

1081* `error_count`：加载 plugins 的错误数

1082

1083将 `{ holdOnCacheImpact: true }` 传递给 `reloadPlugins()` 以保持会使对话的提示缓存失效的重新加载，而不是应用它。Claude Code 运行交互式 `/reload-plugins` 命令在[警告缓存成本](/docs/zh-CN/prompt-caching#enabling-or-disabling-a-plugin)之前进行的检查。该选项需要 Agent SDK v0.3.268 或更高版本。比 v2.1.268 更旧的 Claude Code 可执行文件（例如您通过 `pathToClaudeCodeExecutable` 指向的）会忽略该选项并应用重新加载。

1084

1085当您传递该选项时，读取 `held` 以了解发生了什么：

1086

1087* `true`：重新加载未被应用，集合字段描述会话仍然是什么样子。`cache_impact` 说明应用会改变什么。要应用，请再次调用 `reloadPlugins()` 而不使用该选项。

1088* `false`：检查未发现缓存影响，重新加载已被应用。

1089* 不存在：您未传递该选项，或 Claude Code 可执行文件比 v2.1.268 更旧并应用了重新加载。

1090

1091`cache_impact` 仅在 `held: true` 旁边存在。`mcp_servers_added` 和 `mcp_servers_removed` 命名重新加载会注册或删除的 plugin MCP 服务器，作为作用域 `plugin:<plugin>:<server>` 名称。名称是 plugin 作者编写的，因此在显示之前验证它们。`lsp_tool_change` 说明应用是否会添加或删除 LSP 工具，或 `null` 当它都不做时。`may-` 形式意味着检查无法完全看到待处理的 plugin 集。

1092

953<h3 id="sdkcontrolreloadskillsresponse">1093<h3 id="sdkcontrolreloadskillsresponse">

954 `SDKControlReloadSkillsResponse`1094 `SDKControlReloadSkillsResponse`

955</h3>1095</h3>

964 1104

965`skills` 列出重新加载后可用的 skills，采用 `supportedCommands()` 返回的相同 [`SlashCommand`](#slashcommand) 形状。1105`skills` 列出重新加载后可用的 skills，采用 `supportedCommands()` 返回的相同 [`SlashCommand`](#slashcommand) 形状。

966 1106

1107<h3 id="sdkcontrolreloadoutputstylesresponse">

1108 `SDKControlReloadOutputStylesResponse`

1109</h3>

1110

1111[`reloadOutputStyles()`](#query-object) 的返回类型。

1112

1113```typescript theme={null}

1114type SDKControlReloadOutputStylesResponse = {

1115 available_output_styles: string[];

1116};

1117```

1118

1119`available_output_styles` 列出重新加载后可用的内置和自定义输出样式的名称。

1120

967<h3 id="sdkcontrolmcpreadresourceresponse">1121<h3 id="sdkcontrolmcpreadresourceresponse">

968 `SDKControlMcpReadResourceResponse`1122 `SDKControlMcpReadResourceResponse`

969</h3>1123</h3>

1142 blockedPath?: string;1296 blockedPath?: string;

1143 mcpServer?: { name: string; source: string };1297 mcpServer?: { name: string; source: string };

1144 decisionReason?: string;1298 decisionReason?: string;

1299 defaultToNo?: boolean;

1300 suppressAlwaysAllowRule?: boolean;

1145 toolUseID: string;1301 toolUseID: string;

1146 agentID?: string;1302 agentID?: string;

1147 requestId: string;1303 requestId: string;

1157| `mcpServer` | `{ name: string; source: string }` | 对于 `mcp__*` 工具，提供该工具的 MCP 服务器及其定义来源，具有 [`McpServerProvenance`](#mcpserverprovenance) 的字段。对于其他工具不存在。需要 Agent SDK v0.3.274 或更高版本 |1313| `mcpServer` | `{ name: string; source: string }` | 对于 `mcp__*` 工具，提供该工具的 MCP 服务器及其定义来源，具有 [`McpServerProvenance`](#mcpserverprovenance) 的字段。对于其他工具不存在。需要 Agent SDK v0.3.274 或更高版本 |

1315| `defaultToNo` | `boolean` | 当 `true` 时，单个杂散按键不得批准此请求：在其拒绝选项上打开您的提示，不要预先选择批准，并且不提供单键批准快捷方式。需要 Agent SDK v0.3.268 或更高版本 |

1316| `suppressAlwaysAllowRule` | `boolean` | 当 `true` 时，不为此请求提供持久的始终允许选择，因为它会写入的规则授予超过请求自身操作的权限。需要 Agent SDK v0.3.268 或更高版本 |

1380 context_usage?: SDKContextUsage;1538 context_usage?: SDKContextUsage;

1381 user_message_uuid?: string;1539 user_message_uuid?: string;

1382 user_message_uuids?: string[];1540 user_message_uuids?: string[];

1541 resume_reason?: string;

1383};1542};

1384```1543```

1385 1544

1394 1553

1395当中断或中止在流完成前截断助手消息时，`aborted` 为 `true`：消息没有 `stop_reason`，内容可能在单词中间结束。该字段在正常完成的消息上不存在。它需要 Agent SDK v0.3.214 或更高版本。1554当中断或中止在流完成前截断助手消息时，`aborted` 为 `true`：消息没有 `stop_reason`，内容可能在单词中间结束。该字段在正常完成的消息上不存在。它需要 Agent SDK v0.3.214 或更高版本。

1396 1555

1397Claude Code 在该轮的第一条助手消息上设置 `user_message_uuid` 和 `user_message_uuids`，条件在 [`user_message_uuid`](#user_message_uuid) 中。1556Claude Code 在该轮的第一条助手消息上设置 `user_message_uuid` 和 `user_message_uuids`，条件在 [`user_message_uuid`](#user_message_uuid) 中。当 Claude Code 重新运行被重启中断的轮时，重新运行的携带这些字段的助手消息也携带 [`resume_reason`](#resume_reason)。

1398 1557

1399`timestamp` 是消息内容在生成它的进程上完成生成的 ISO 8601 时间。该值来自该机器的时钟，因此仅用于显示，不要按它排序消息。一个 API 轮可以产生多条共享 `message.id` 的助手消息，每条都有自己的 `timestamp`。当字段不存在时，回退到您收到消息的时间。1558`timestamp` 是消息内容在生成它的进程上完成生成的 ISO 8601 时间。该值来自该机器的时钟，因此仅用于显示，不要按它排序消息。一个 API 轮可以产生多条共享 `message.id` 的助手消息，每条都有自己的 `timestamp`。当字段不存在时，回退到您收到消息的时间。

1400 1559

1416 parent_tool_use_id: string | null;1575 parent_tool_use_id: string | null;

1417 isSynthetic?: boolean;1576 isSynthetic?: boolean;

1418 shouldQuery?: boolean;1577 shouldQuery?: boolean;

1578 client_composed?: true;

1419 tool_use_result?: unknown;1579 tool_use_result?: unknown;

1420 origin?: SDKMessageOrigin;1580 origin?: SDKMessageOrigin;

1421 inline_pastes?: string[];1581 inline_pastes?: string[];

1424 1584

1425设置 `pasted_content` 以发送用户粘贴到您的提示 UI 中而不是输入的内容，每个粘贴一个条目，每个条目是字符串或内容块数组。Claude Code 按顺序在输入的文本后追加每个条目的文本，并可能将每个粘贴包装在 `<pasted_content>` 标签中。除文本外的块被忽略，因此在 `message.content` 中发送图像和文档。需要 Agent SDK v0.3.277 或更高版本。1585设置 `pasted_content` 以发送用户粘贴到您的提示 UI 中而不是输入的内容，每个粘贴一个条目，每个条目是字符串或内容块数组。Claude Code 按顺序在输入的文本后追加每个条目的文本，并可能将每个粘贴包装在 `<pasted_content>` 标签中。除文本外的块被忽略，因此在 `message.content` 中发送图像和文档。需要 Agent SDK v0.3.277 或更高版本。

1426 1586

1427设置 `shouldQuery` 为 `false` 以将消息附加到记录中而不触发助手轮。消息被保留并合并到下一条触发轮的用户消息中。使用此方法注入上下文，例如您在带外运行的命令的输出，而无需在模型调用上花费。1587设置 `shouldQuery` 或 `client_composed` 以改变 Claude Code 处理您发送的消息的方式：

1588

1589* `shouldQuery`：设置为 `false` 以将消息附加到记录中而不触发助手轮。消息被保留并合并到下一条触发轮的用户消息中。使用此方法注入上下文，例如您在带外运行的命令的输出，而无需在模型调用上花费。

1590* `client_composed`：设置为 `true` 以让 Claude Code 按原样传递消息文本。Claude Code 然后不展开 `@path` 或 [`@server:resource`](/docs/zh-CN/mcp#use-mcp-resources) 提及，也不运行以 `/` 开头的文本作为命令。当 [`verbatimPrompts`](#options) 选项打开时，SDK 在每条消息上设置该字段。需要 TypeScript Agent SDK v0.3.280 或更高版本和 Claude Code v2.1.248 或更高版本。

1428 1591

1429在携带 `tool_result` 块的消息上，`tool_use_result` 是工具的结构化输出对象，而不是发送给模型的文本。其形状取决于匹配 `tool_use` 块命名的工具，因此该字段的类型为 `unknown`；内置形状列在[工具输出类型](#tool-output-types)下。1592在携带 `tool_result` 块的消息上，`tool_use_result` 是工具的结构化输出对象，而不是发送给模型的文本。其形状取决于匹配 `tool_use` 块命名的工具，因此该字段的类型为 `unknown`；内置形状列在[工具输出类型](#tool-output-types)下。

1430 1593

1448 message: MessageParam;1611 message: MessageParam;

1449 parent_tool_use_id: string | null;1612 parent_tool_use_id: string | null;

1450 isSynthetic?: boolean;1613 isSynthetic?: boolean;

1614 client_composed?: true;

1451 tool_use_result?: unknown;1615 tool_use_result?: unknown;

1452 origin?: SDKMessageOrigin;1616 origin?: SDKMessageOrigin;

1453 isReplay: true;1617 isReplay: true;

1480 ttft_stream_ms?: number;1644 ttft_stream_ms?: number;

1481 user_message_uuid?: string;1645 user_message_uuid?: string;

1482 user_message_uuids?: string[];1646 user_message_uuids?: string[];

1647 resume_reason?: string;

1648 local_command?: string;

1483 request_sent_wall_ms?: number;1649 request_sent_wall_ms?: number;

1484 first_content_frame_ms?: number;1650 first_content_frame_ms?: number;

1485 first_stream_post_ms?: number;1651 first_stream_post_ms?: number;

1493 structured_output?: unknown;1659 structured_output?: unknown;

1494 deferred_tool_use?: { id: string; name: string; input: Record<string, unknown> };1660 deferred_tool_use?: { id: string; name: string; input: Record<string, unknown> };

1495 terminal_reason?: TerminalReason;1661 terminal_reason?: TerminalReason;

1662 result_index?: number;

1496 fast_mode_state?: FastModeState;1663 fast_mode_state?: FastModeState;

1497 fast_mode_disabled_reason?: FastModeDisabledReason;1664 fast_mode_disabled_reason?: FastModeDisabledReason;

1498 origin?: SDKMessageOrigin;1665 origin?: SDKMessageOrigin;

1520 startup_failure_reason?: SDKStartupFailureReason;1687 startup_failure_reason?: SDKStartupFailureReason;

1521 user_message_uuid?: string;1688 user_message_uuid?: string;

1522 user_message_uuids?: string[];1689 user_message_uuids?: string[];

1690 resume_reason?: string;

1523 terminal_reason?: TerminalReason;1691 terminal_reason?: TerminalReason;

1692 result_index?: number;

1524 fast_mode_state?: FastModeState;1693 fast_mode_state?: FastModeState;

1525 fast_mode_disabled_reason?: FastModeDisabledReason;1694 fast_mode_disabled_reason?: FastModeDisabledReason;

1526 origin?: SDKMessageOrigin;1695 origin?: SDKMessageOrigin;

1534* `ttft_stream_ms`：直到第一个 `message_start` 流事件（响应流打开时）的时间（毫秒）。低于 `ttft_ms`；两者之间的差距是流传输第一条消息所花费的时间。仅在成功分支上存在。1703* `ttft_stream_ms`：直到第一个 `message_start` 流事件（响应流打开时）的时间（毫秒）。低于 `ttft_ms`；两者之间的差距是流传输第一条消息所花费的时间。仅在成功分支上存在。

1535* `user_message_uuid`：您发送的消息的 `uuid`，该轮回答了该消息。请参阅 [`user_message_uuid`](#user_message_uuid) 了解哪些结果携带它。1704* `user_message_uuid`：您发送的消息的 `uuid`，该轮回答了该消息。请参阅 [`user_message_uuid`](#user_message_uuid) 了解哪些结果携带它。

1536* `user_message_uuids`：您发送的每条消息的 `uuid`，Claude Code 在该轮中回答了这些消息。请参阅 [`user_message_uuids`](#user_message_uuids)。1705* `user_message_uuids`：您发送的每条消息的 `uuid`，Claude Code 在该轮中回答了这些消息。请参阅 [`user_message_uuids`](#user_message_uuids)。

1706* `resume_reason`：Claude Code 重新运行该轮的原因，在重启中断后。请参阅 [`resume_reason`](#resume_reason)。

1707* `local_command`：轮分派的命令的名称，在轮由命令完成而不进入代理循环的成功结果上，例如 `/compact`。名称折叠为小写字母和下划线，因此 `/reload-plugins` 报告 `reload_plugins`。MCP 服务器提供的命令和内置 `/mcp` 报告 `mcp`。您自己定义的命令报告 `custom`。参数从不包含。在进入代理循环的每个轮上不存在，在运行无命令的发送上不存在。需要 Agent SDK v0.3.268 或更高版本。

1537* `request_sent_wall_ms`：Claude Code 分派 API 请求的纪元毫秒，用于与服务器端时间戳的连接。仅与 [`user_message_uuid`](#user_message_uuid) 一起存在，在成功结果上，其中 `is_error` 为 false，且轮发送了 API 请求。1708* `request_sent_wall_ms`：Claude Code 分派 API 请求的纪元毫秒，用于与服务器端时间戳的连接。仅与 [`user_message_uuid`](#user_message_uuid) 一起存在，在成功结果上，其中 `is_error` 为 false，且轮发送了 API 请求。

1538* `first_content_frame_ms`：直到第一个 `content_block_start` 或 `content_block_delta` 流事件的时间（毫秒），计算思考块作为内容。仅在成功分支上存在，当 `is_error` 为 false 时。需要 Agent SDK v0.3.260 或更高版本。1709* `first_content_frame_ms`：直到第一个 `content_block_start` 或 `content_block_delta` 流事件的时间（毫秒），计算思考块作为内容。仅在成功分支上存在，当 `is_error` 为 false 时。需要 Agent SDK v0.3.260 或更高版本。

1539* `first_stream_post_ms`、`first_stream_post_ack_ms`、`first_stream_post_wall_ms`：上传轮的第一个流事件的时间。Claude Code 仅在它流传输到 claude.ai 的会话中记录它们，例如[云会话](/docs/zh-CN/claude-code-on-the-web)，`query()` 产生的结果不携带它们。需要 Agent SDK v0.3.260 或更高版本。1710* `first_stream_post_ms`、`first_stream_post_ack_ms`、`first_stream_post_wall_ms`：上传轮的第一个流事件的时间。Claude Code 仅在它流传输到 claude.ai 的会话中记录它们，例如[云会话](/docs/zh-CN/claude-code-on-the-web)，`query()` 产生的结果不携带它们。需要 Agent SDK v0.3.260 或更高版本。

1541* `modelUsage`：在此 `query()` 调用期间通过查询管道进行的每个模型调用的每模型总计，包括主循环、子代理和内部调用（如压缩和 Workflow 代理）。该管道外的辅助调用（如权限分类器和令牌计数请求）被排除。恢复会话的调用也计算[从会话早期调用恢复的每模型总计](/docs/zh-CN/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)。在流式输入会话中，总计在轮中是累积的，因此读取最新结果而不是跨结果求和。请参阅[在流式输入模式中跟踪成本](/docs/zh-CN/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode)了解重置，以及[在会话崩溃后恢复总计](/docs/zh-CN/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)了解零化结果。1712* `modelUsage`：在此 `query()` 调用期间通过查询管道进行的每个模型调用的每模型总计，包括主循环、子代理和内部调用（如压缩和 Workflow 代理）。该管道外的辅助调用（如权限分类器和令牌计数请求）被排除。恢复会话的调用也计算[从会话早期调用恢复的每模型总计](/docs/zh-CN/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)。在流式输入会话中，总计在轮中是累积的，因此读取最新结果而不是跨结果求和。请参阅[在流式输入模式中跟踪成本](/docs/zh-CN/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode)了解重置，以及[在会话崩溃后恢复总计](/docs/zh-CN/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)了解零化结果。

1542* `total_cost_usd`：累积估计成本（美元），涵盖与 `modelUsage` 相同的调用并在相同点重置。恢复会话的调用也计算[从会话早期调用恢复的总计](/docs/zh-CN/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)。这是一个估计值，不是账单声明。请参阅[跟踪成本和使用情况](/docs/zh-CN/agent-sdk/cost-tracking)了解准确性注意事项。1713* `total_cost_usd`：累积估计成本（美元），涵盖与 `modelUsage` 相同的调用并在相同点重置。恢复会话的调用也计算[从会话早期调用恢复的总计](/docs/zh-CN/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls)。这是一个估计值，不是账单声明。请参阅[跟踪成本和使用情况](/docs/zh-CN/agent-sdk/cost-tracking)了解准确性注意事项。

1543* `queued_turn_count`：您发送的带有 `origin: { kind: "human" }` 的消息数，在 Claude Code 产生结果时仍在等待。请参阅 [`queued_turn_count`](#queued_turn_count) 了解 `0` 和缺失字段告诉您什么。1714* `queued_turn_count`：您发送的带有 `origin: { kind: "human" }` 的消息数，在 Claude Code 产生结果时仍在等待。请参阅 [`queued_turn_count`](#queued_turn_count) 了解 `0` 和缺失字段告诉您什么。

1715* `result_index`：此结果在运行的传递顺序中的位置，从 0 开始计算，跨越进程写入的每个结果。在两个分支上存在。写入失败的结果仍然消耗其编号，因此序列中的间隙意味着结果丢失。需要 Agent SDK v0.3.268 或更高版本。

1544* `startup_failure_reason`：Claude Code 拒绝启动的原因，在它在已知启动失败时退出前写入的 `error_during_execution` 结果上。请参阅 [`startup_failure_reason`](#startup_failure_reason) 了解值以及哪些失败携带它。需要 Agent SDK v0.3.274 或更高版本。1716* `startup_failure_reason`：Claude Code 拒绝启动的原因，在它在已知启动失败时退出前写入的 `error_during_execution` 结果上。请参阅 [`startup_failure_reason`](#startup_failure_reason) 了解值以及哪些失败携带它。需要 Agent SDK v0.3.274 或更高版本。

1545* `terminal_reason`：循环结束的原因。`"completed"`、`"max_turns"`、`"tool_deferred"`、`"aborted_streaming"`、`"aborted_tools"`、`"hook_stopped"`、`"stop_hook_prevented"`、`"background_requested"`、`"blocking_limit"`、`"rapid_refill_breaker"`、`"prompt_too_long"`、`"image_error"`、`"model_error"`、`"api_error"`、`"malformed_tool_use_exhausted"`、`"budget_exhausted"`、`"structured_output_retry_exhausted"`、`"tool_deferred_unavailable"` 或 `"turn_setup_failed"` 之一。1717* `terminal_reason`：循环结束的原因。`"completed"`、`"max_turns"`、`"tool_deferred"`、`"aborted_streaming"`、`"aborted_tools"`、`"hook_stopped"`、`"stop_hook_prevented"`、`"background_requested"`、`"blocking_limit"`、`"rapid_refill_breaker"`、`"prompt_too_long"`、`"image_error"`、`"model_error"`、`"api_error"`、`"malformed_tool_use_exhausted"`、`"budget_exhausted"`、`"structured_output_retry_exhausted"`、`"tool_deferred_unavailable"` 或 `"turn_setup_failed"` 之一。

1546* `fast_mode_state`：`"on"`、`"off"` 或 `"cooldown"` 之一。1718* `fast_mode_state`：`"on"`、`"off"` 或 `"cooldown"` 之一。

1581 1753

1582* **您发送的常规消息**，意思是没有 `isSynthetic: true` 的消息：轮在其整个运行中回答该消息。当您一起发送多条消息时，Claude Code 可以将它们合并为一轮，该字段然后仅携带最后一条消息的 `uuid`。要将回复与任何合并的消息匹配，请使用 [`user_message_uuids`](#user_message_uuids)。1754* **您发送的常规消息**，意思是没有 `isSynthetic: true` 的消息：轮在其整个运行中回答该消息。当您一起发送多条消息时，Claude Code 可以将它们合并为一轮，该字段然后仅携带最后一条消息的 `uuid`。要将回复与任何合并的消息匹配，请使用 [`user_message_uuids`](#user_message_uuids)。

1583* **您发送的带有 `isSynthetic: true` 的消息**：轮最初回答该消息。如果 Claude Code 在工具调用之间拾取您的常规消息，轮从那时起回答拾取的消息。回显合成消息的 `uuid` 需要 Agent SDK v0.3.265 或更高版本；早期版本在合成轮上不回显任何内容。1755* **您发送的带有 `isSynthetic: true` 的消息**：轮最初回答该消息。如果 Claude Code 在工具调用之间拾取您的常规消息，轮从那时起回答拾取的消息。回显合成消息的 `uuid` 需要 Agent SDK v0.3.265 或更高版本；早期版本在合成轮上不回显任何内容。

1584* **Claude Code 自己生成的提示**，例如在会话重启后继续中断工作的轮：轮最初不回答您的任何消息，其帧不携带回显。如果 Claude Code 在工具调用之间拾取您的常规消息，轮从那时起回答该消息。拾取回显需要 Agent SDK v0.3.265 或更高版本；早期版本在这些轮上不回显任何内容。1756* **Claude Code 生成的提示以重新运行被重启中断的轮**（在 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/zh-CN/env-vars) 下）：当被中断轮的最后一个提示是您发送的常规消息时，无论它是打开轮还是 Claude Code 在轮期间拾取它，重新运行最初回答该消息。[`resume_reason`](#resume_reason) 告诉重新运行的帧来自被中断尝试的。当最后一个提示不是您的常规消息时，重新运行最初不回答您的任何消息。如果 Claude Code 在工具调用之间拾取您的常规消息，轮从那时起回答拾取的消息。回显被中断轮的提示需要 Agent SDK v0.3.268 或更高版本。

1757* **Claude Code 自己生成的任何其他提示**：轮最初不回答您的任何消息，其帧不携带回显。如果 Claude Code 在工具调用之间拾取您的常规消息，轮从那时起回答该消息。拾取回显需要 Agent SDK v0.3.265 或更高版本；早期版本在这些轮上不回显任何内容。

1585 1758

1586Claude Code 在三种帧上回显回答的消息的 `uuid`：1759Claude Code 在三种帧上回显回答的消息的 `uuid`：

1587 1760

1593 1766

1594* 除了那些第一个回复之外的回复帧1767* 除了那些第一个回复之外的回复帧

1595* 子代理帧1768* 子代理帧

1596* 回答没有 `uuid` 的消息的轮：轮回答了您发送的没有 uuid 的消息，或 Claude Code 启动了轮本身并拾取了没有 uuid 的常规消息1769* 回答没有消息的轮，或回答您发送的没有 `uuid` 的消息的轮

1597* 回答您未发送的消息的结果，例如崩溃的工作进程后的零化结果1770* 回答您未发送的消息的结果，例如崩溃的工作进程后的零化结果

1598 1771

1599<h4 id="user_message_uuids">1772<h4 id="user_message_uuids">

1608 1781

1609当第一个回复或结果携带 `user_message_uuid` 而没有列表时，它来自早期的 Claude Code 版本，因此回退到单个字段。1782当第一个回复或结果携带 `user_message_uuid` 而没有列表时，它来自早期的 Claude Code 版本，因此回退到单个字段。

1610 1783

1784<h4 id="resume_reason">

1785 `resume_reason`

1786</h4>

1787

1788Claude Code 重新运行该轮的原因，在重启后。Claude Code 在它在 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/zh-CN/env-vars) 下重新运行的轮上设置此字段，以便您可以将重新运行的回复和结果与被中断尝试的区分开。需要 Agent SDK v0.3.268 或更高版本。

1789

1790Claude Code 在两种帧上设置该字段：

1791

1792* **重新运行的结果**：在成功和错误分支上，无论结果是否携带 `user_message_uuid`。

1793* **重新运行的回复帧**：那些携带 [`user_message_uuid`](#user_message_uuid) 的帧。

1794

1795该值是一个短小写令牌，命名轮被重新运行的原因，例如 `interrupted_turn`。该字段在所有其他轮上不存在。

1796

1611<h4 id="queued_turn_count">1797<h4 id="queued_turn_count">

1612 `queued_turn_count`1798 `queued_turn_count`

1613</h4>1799</h4>

1657| `org_pin_api_key_conflict` | 托管设置[需要第一方或 Cloud 网关登录](/docs/zh-CN/authentication#restrict-login-to-your-organization)，并配置了 Anthropic API 密钥、身份验证令牌或 `apiKeyHelper` |1843| `org_pin_api_key_conflict` | 托管设置[需要第一方或 Cloud 网关登录](/docs/zh-CN/authentication#restrict-login-to-your-organization)，并配置了 Anthropic API 密钥、身份验证令牌或 `apiKeyHelper` |

1663| `gateway_access_denied` | 对 Cloud 网关的托管设置请求返回 403，网关的[故障排除表](/docs/zh-CN/claude-apps-gateway-deploy#troubleshooting)涵盖了这一点 |1849| `gateway_access_denied` | 对 Cloud 网关的托管设置请求返回 403，网关的[故障排除表](/docs/zh-CN/claude-apps-gateway-deploy#troubleshooting)涵盖了这一点 |

1701 output_style: string;1887 output_style: string;

1702 skills: string[];1888 skills: string[];

1703 plugins: { name: string; path: string }[];1889 plugins: { name: string; path: string }[];

1890 plugin_errors?: {

1891 plugin: string;

1892 type: string;

1893 message: string;

1894 path?: string;

1895 }[];

1704 fast_mode_state?: FastModeState;1896 fast_mode_state?: FastModeState;

1705 fast_mode_disabled_reason?: FastModeDisabledReason;1897 fast_mode_disabled_reason?: FastModeDisabledReason;

1720| 功能 | 含义 |1912| 功能 | 含义 |

1721| - | - |1913| - | - |

1722| `interrupt_receipt_v1` | [`interrupt()`](#query-object) 使用 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 收据解析，列出中断到达时待处理的消息 |1914| `interrupt_receipt_v1` | [`interrupt()`](#query-object) 使用 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 收据解析，列出中断到达时待处理的消息 |

1723| `interrupt_cancel_queued_v1` | ` interrupt` 控制请求尊重 `cancel_queued: true`，取消收据在 `still_queued` 下列出的消息，并改为在 `cancelled` 下列出它们。请参阅 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)。需要 Claude Code v2.1.219 或更高版本 |1915| `interrupt_cancel_queued_v1` | `interrupt` 控制请求尊重 `cancel_queued: true`，取消收据在 `still_queued` 下列出的消息，并改为在 `cancelled` 下列出它们。请参阅 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse)。需要 Claude Code v2.1.219 或更高版本 |

1916

1917`plugin_errors` 数组列出插件加载失败。一个条目描述要么是未加载的插件且在 `plugins` 中不存在，要么是加载但没有其部分之一（例如其 hooks 文件）的插件。当没有任何东西失败时，该键被省略。`SDKSystemMessage` 在 Agent SDK v0.3.283 或更高版本中声明 `plugin_errors`。

1918

1919当您的 [`plugins` 选项](#options)中的目录或存档本身无法加载时，条目的 `plugin` 字段保存位置标签（例如 `inline[0]`）而不是插件名称。例如，当路径不存在或清单无效时会发生这种情况。通过其 `path` 字段将这样的条目与您的选项匹配。

1920

1921下表列出了每个 `plugin_errors` 条目的字段。

1922

1923| 字段 | 类型 | 描述 |

1924| - | - | - |

1925| `plugin` | `string` | 失败插件的 ID，或位置标签（例如 `inline[0]`），当插件目录或存档本身无法加载时 |

1926| `type` | `string` | 来自开放集的错误类别，例如 `path-not-found` 或 `manifest-validation-error`。将您不认识的值视为通用失败 |

1927| `message` | `string` | 描述失败的显示文本 |

1928| `path` | `string` | 仅当插件目录或存档本身无法加载时存在。其绝对路径，相对路径从您的 `plugins` 选项针对 [`cwd`](#options) 选项解析 |

1724 1929

1725<h3 id="sdkpartialassistantmessage">1930<h3 id="sdkpartialassistantmessage">

1726 `SDKPartialAssistantMessage`1931 `SDKPartialAssistantMessage`

1738 ttft_ms?: number; // Time to first token in ms, present only on message_start events1943 ttft_ms?: number; // Time to first token in ms, present only on message_start events

1739 user_message_uuid?: string;1944 user_message_uuid?: string;

1740 user_message_uuids?: string[];1945 user_message_uuids?: string[];

1946 resume_reason?: string;

1741};1947};

1742```1948```

1743 1949

1744Claude Code 在轮的第一个非 ping 流事件上设置 `user_message_uuid` 和 `user_message_uuids`，并在轮回答的消息改变时再次设置，条件在 [`user_message_uuid`](#user_message_uuid) 中。1950Claude Code 在轮的第一个非 ping 流事件上设置 `user_message_uuid` 和 `user_message_uuids`，并在轮回答的消息改变时再次设置，条件在 [`user_message_uuid`](#user_message_uuid) 中。当 Claude Code 重新运行被重启中断的轮时，重新运行的携带这些字段的流事件也携带 [`resume_reason`](#resume_reason)。

1745 1951

1746<h3 id="sdkcompactboundarymessage">1952<h3 id="sdkcompactboundarymessage">

1747 `SDKCompactBoundaryMessage`1953 `SDKCompactBoundaryMessage`

1766 `SDKInformationalMessage`1972 `SDKInformationalMessage`

1767</h3>1973</h3>

1768 1974

1769循环发出的通用文本横幅。携带非错误状态行、钩子反馈（例如 `UserPromptSubmit` 钩子的阻止原因）和命令输出。在 Claude Code v2.1.227 或更高版本上，钩子的 [`systemMessage`](/docs/zh-CN/hooks#json-output) 可以作为此消息到达，每行以钩子的名称为前缀，例如 `PostToolUse:Bash says:`。钩子的 `systemMessage` 是否作为此消息到达取决于事件。每个[事件的部分](/docs/zh-CN/hooks#hook-events)在钩子页面上说明输出如何显示。将 `content` 呈现为给定 `level` 的纯文本。1975循环发出的通用文本横幅。携带警告、通知和其他非错误状态行 Claude Code 引发，以及钩子反馈，例如 `UserPromptSubmit` 钩子的阻止原因。

1976

1977在 Claude Code v2.1.227 或更高版本上，钩子的 [`systemMessage`](/docs/zh-CN/hooks#json-output) 可以作为此消息到达，每行以钩子的名称为前缀，例如 `PostToolUse:Bash says:`。每个[事件的部分](/docs/zh-CN/hooks#hook-events)在钩子页面上说明输出如何显示。

1978

1979将 `content` 呈现为给定 `level` 的纯文本。

1770 1980

1771```typescript theme={null}1981```typescript theme={null}

1772type SDKInformationalMessage = {1982type SDKInformationalMessage = {

2857 工具输入类型3067 工具输入类型

2858</h2>3068</h2>

2859 3069

2860所有内置 Claude Code 工具的输入架构文档。这些类型从 `@anthropic-ai/claude-agent-sdk` 导出，可用于类型安全的工具交互。3070所有内置 Claude Code 工具的输入架构文档。这些类型从 `@anthropic-ai/claude-agent-sdk/sdk-tools` 导出，可用于类型安全的工具交互。

2861 3071

2862<h3 id="toolinputschemas">3072<h3 id="toolinputschemas">

2863 `ToolInputSchemas`3073 `ToolInputSchemas`

2864</h3>3074</h3>

2865 3075

2866从 `@anthropic-ai/claude-agent-sdk` 导出的工具输入类型的联合；成员包括：3076从 `@anthropic-ai/claude-agent-sdk/sdk-tools` 导出的工具输入类型的联合；成员包括：

2867 3077

2868```typescript theme={null}3078```typescript theme={null}

2869type ToolInputSchemas =3079type ToolInputSchemas =

3665 工具输出类型3875 工具输出类型

3666</h2>3876</h2>

3667 3877

3668所有内置 Claude Code 工具的输出架构文档。这些类型从 `@anthropic-ai/claude-agent-sdk` 导出，代表每个工具返回的实际响应数据。3878所有内置 Claude Code 工具的输出架构文档。这些类型从 `@anthropic-ai/claude-agent-sdk/sdk-tools` 导出，代表每个工具返回的实际响应数据。

3669 3879

3670<h3 id="tooloutputschemas">3880<h3 id="tooloutputschemas">

3671 `ToolOutputSchemas`3881 `ToolOutputSchemas`

3672</h3>3882</h3>

3673 3883

3674从 `@anthropic-ai/claude-agent-sdk` 导出的工具输出类型的联合；成员包括：3884从 `@anthropic-ai/claude-agent-sdk/sdk-tools` 导出的工具输出类型的联合；成员包括：

3675 3885

3676```typescript theme={null}3886```typescript theme={null}

3677type ToolOutputSchemas =3887type ToolOutputSchemas =

4892};5102};

4893```5103```

4894 5104

4895当命令是 Claude Code 自己的命令且输入 `/name` 运行它时，`builtin` 为 `true`。对于由用户、项目、plugin 或 MCP 服务器定义的命令，以及由这些命令之一 [按名称替换](/docs/zh-CN/skills#resolve-skills-that-share-a-name) 的捆绑命令，它不存在。需要 Agent SDK v0.3.277 或更高版本。5105`builtin` 在命令是 Claude Code 自己的命令且输入 `/name` 运行它时为 `true`。对于由用户、项目、plugin 或 MCP 服务器定义的命令，以及由这些命令之一 [按名称替换](/docs/zh-CN/skills#resolve-skills-that-share-a-name) 的捆绑命令，它不存在。需要 Agent SDK v0.3.277 或更高版本。

4896 5106

4897<h3 id="modelinfo">5107<h3 id="modelinfo">

4898 `ModelInfo`5108 `ModelInfo`

5510 `SDKTaskProgressMessage`5720 `SDKTaskProgressMessage`

5511</h3>5721</h3>

5512 5722

5513在子代理或后台任务运行时定期发出。`summary` 字段仅在启用 [`agentProgressSummaries`](#options) 时填充。5723在子代理或后台任务运行时定期发出。对于子代理任务，`summary` 字段仅在启用 [`agentProgressSummaries`](#options) 时填充。对于 [backgrounded MCP tool call](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls)，`summary` 携带 MCP 服务器的最新报告进度，不依赖于该选项。

5514 5724

5515```typescript theme={null}5725```typescript theme={null}

5516type SDKTaskProgressMessage = {5726type SDKTaskProgressMessage = {

5673 5883

5674当可用命令集在会话中期更改时发出，例如当 Claude Code 在代理进入子目录时发现技能时。`commands` 数组是完整的更新列表，因此用此有效负载替换任何缓存的命令列表。在此消息后调用 [`supportedCommands()`](#query-object) 返回相同的更新列表，因为该方法跟踪最新推送；这需要 Agent SDK v0.3.216 或更高版本。在早期 SDK 版本中，`supportedCommands()` 返回在初始化时捕获的快照，永远不会反映会话中期的更改。5884当可用命令集在会话中期更改时发出，例如当 Claude Code 在代理进入子目录时发现技能时。`commands` 数组是完整的更新列表，因此用此有效负载替换任何缓存的命令列表。在此消息后调用 [`supportedCommands()`](#query-object) 返回相同的更新列表，因为该方法跟踪最新推送；这需要 Agent SDK v0.3.216 或更高版本。在早期 SDK 版本中，`supportedCommands()` 返回在初始化时捕获的快照，永远不会反映会话中期的更改。

5675 5885

5886Claude Code 也在 MCP 服务器的 [prompts](/docs/zh-CN/mcp#use-mcp-prompts-as-commands) 加入或离开列表时发出此消息，例如当服务器在会话启动后完成连接时。这需要 Claude Code v2.1.281 或更高版本。

5887

5676```typescript theme={null}5888```typescript theme={null}

5677type SDKCommandsChangedMessage = {5889type SDKCommandsChangedMessage = {

5678 type: "system";5890 type: "system";

5710 new_conversation_id: UUID;5922 new_conversation_id: UUID;

5711 uuid: UUID;5923 uuid: UUID;

5712 session_id: string;5924 session_id: string;

5925 trigger?: "clear" | "plan_mode_exit" | "fresh_session" | "onboarding";

5926 user_message_uuid?: string;

5927 timestamp?: string;

5713};5928};

5714```5929```

5715 5930

5931可选字段描述重置：

5932

5933* `trigger`：什么丢弃了对话。在每个 `conversation_reset` 消息上重置您的成绩单，包括此字段不存在或携带您不认识的值的消息。

5934* `user_message_uuid`：携带 `/clear` 的用户消息的 `uuid`。使用它将重置与该消息匹配。

5935* `timestamp`：重置发生的时间，作为 UTC 中的 ISO 8601 字符串。使用它进行显示，而不是用于排序消息。

5936

5937`trigger`、`user_message_uuid` 和 `timestamp` 字段需要 Claude Code v2.1.281 或更高版本。

5938

5716SDK 的已发布类型在 Claude Code v2.1.203 及更高版本中声明 `SDKConversationResetMessage`。在 v2.1.203 之前，`SDKMessage` 引用了该类型而不声明它，因此当 `skipLibCheck` 被禁用时，在 `type === "conversation_reset"` 上缩小范围失败类型检查。5939SDK 的已发布类型在 Claude Code v2.1.203 及更高版本中声明 `SDKConversationResetMessage`。在 v2.1.203 之前，`SDKMessage` 引用了该类型而不声明它，因此当 `skipLibCheck` 被禁用时，在 `type === "conversation_reset"` 上缩小范围失败类型检查。

5717 5940

5718<h3 id="aborterror">5941<h3 id="aborterror">

5831| `strictAllowlist` | `boolean` | `false` | 拒绝沙箱化命令访问[网络允许列表](/docs/zh-CN/sandboxing#network-isolation)之外的主机，而不是提示。仅对沙箱化命令强制执行；WebFetch 等进程内工具不受其限制。仅从用户、托管或 CLI `--settings` 设置中遵守；项目设置被忽略。需要 Claude Code v2.1.219 或更高版本 |6054| `strictAllowlist` | `boolean` | `false` | 拒绝沙箱化命令访问[网络允许列表](/docs/zh-CN/sandboxing#network-isolation)之外的主机，而不是提示。仅对沙箱化命令强制执行；WebFetch 等进程内工具不受其限制。仅从用户、托管或 CLI `--settings` 设置中遵守；项目设置被忽略。需要 Claude Code v2.1.219 或更高版本 |

5832| `allowManagedDomainsOnly` | `boolean` | `false` | 仅限管理设置。在[管理设置](/docs/zh-CN/managed-settings)中设置时，仅遵守来自管理设置的 `allowedDomains` 条目和来自管理设置的 `WebFetch(domain:...)` 允许规则，来自用户、项目或本地设置的允许条目被忽略。通过 SDK 选项设置时无效 |6055| `allowManagedDomainsOnly` | `boolean` | `false` | 仅限管理设置。在[管理设置](/docs/zh-CN/managed-settings)中设置时，仅遵守来自管理设置的 `allowedDomains` 条目和来自管理设置的 `WebFetch(domain:...)` 允许规则，来自用户、项目或本地设置的允许条目被忽略。从 SDK 中，通过 [`managedSettings`](#options) 选项传递它 |

agent-sdk/user-input.md +2 −0

Details

296 <Tab title="批准并记住">296 <Tab title="批准并记住">

297 用户批准并且不想再被询问此类调用。第三个回调参数携带 `suggestions`，一个现成的 [`PermissionUpdate`](/docs/zh-CN/agent-sdk/typescript#permissionupdate) 条目数组。在 `updatedPermissions` 中回显其中一个以应用它。带有 `localSettings` 目标的建议会将规则写入 `.claude/settings.local.json`，以便将来的会话跳过匹配调用的提示。297 用户批准并且不想再被询问此类调用。第三个回调参数携带 `suggestions`，一个现成的 [`PermissionUpdate`](/docs/zh-CN/agent-sdk/typescript#permissionupdate) 条目数组。在 `updatedPermissions` 中回显其中一个以应用它。带有 `localSettings` 目标的建议会将规则写入 `.claude/settings.local.json`，以便将来的会话跳过匹配调用的提示。

298 298

299 在 TypeScript 中，跳过选项携带 [`suppressAlwaysAllowRule: true`](/docs/zh-CN/agent-sdk/typescript#canusetool) 的请求的始终允许选择。该提示需要 Agent SDK v0.3.268 或更高版本，Python `context` 不携带它。

300

299 Python 示例需要 `claude-agent-sdk` 0.1.80 或更高版本。301 Python 示例需要 `claude-agent-sdk` 0.1.80 或更高版本。

300 302

301 <CodeGroup>303 <CodeGroup>

agent-teams.md +3 −1

Details

333 Context 和通信333 Context 和通信

334</h3>334</h3>

335 335

336每个队友都有自己的 context window。生成时，队友加载与常规会话相同的项目 context：CLAUDE.md、MCP servers 和 skills。它还接收来自负责人的生成提示。负责人的对话历史不会继承。336每个队友都有自己的 context window。生成时，队友加载与常规会话相同的项目 context：CLAUDE.md、MCP servers 和 skills。如果你使用 [`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 启动负责人，队友会从相同的受限源列表加载。在 v2.1.281 之前，[split-pane](#choose-a-display-mode) 队友加载每个设置源。

337

338队友也接收来自负责人的生成提示。负责人的对话历史不会继承。

337 339

338**队友如何共享信息：**340**队友如何共享信息：**

339 341

agent-view.md +166 −150

Details

260 260

261按 `←` 创建会话的行，即使对话还没有消息，所以 `→` 仍然返回到它。261按 `←` 创建会话的行，即使对话还没有消息，所以 `→` 仍然返回到它。

262 262

263你可以在 `/config` 中用 `leftArrowOpensAgents` 设置关闭此快捷键。263你可以在 `/config` 中用 [`leftArrowOpensAgents`](/docs/zh-CN/settings-reference#leftarrowopensagents) 设置关闭此快捷键。

264 264

265<h3 id="organize-the-list">265<h3 id="organize-the-list">

266 组织列表266 组织列表

337`Ctrl+S`、`Ctrl+T` 和 `Ctrl+G` 遵循你的 [`keybindings.json`](/docs/zh-CN/keybindings)。在 [`Agents` 上下文](/docs/zh-CN/keybindings#agents-actions)中用 `agents:switchView` 和 `agents:togglePin` 操作重新绑定或取消绑定 `Ctrl+S` 和 `Ctrl+T`，以及通过 `Chat` 上下文的 `chat:externalEditor` 绑定的 `Ctrl+G`。表中的其他快捷键无法重新绑定。337`Ctrl+S`、`Ctrl+T` 和 `Ctrl+G` 遵循你的 [`keybindings.json`](/docs/zh-CN/keybindings)。在 [`Agents` 上下文](/docs/zh-CN/keybindings#agents-actions)中用 `agents:switchView` 和 `agents:togglePin` 操作重新绑定或取消绑定 `Ctrl+S` 和 `Ctrl+T`，以及通过 `Chat` 上下文的 `chat:externalEditor` 绑定的 `Ctrl+G`。表中的其他快捷键无法重新绑定。

338 338

339<h2 id="dispatch-new-agents">339<h2 id="dispatch-new-agents">

340 调度新代理340 分派新的 agents

341</h2>341</h2>

342 342

343你可以从 agent view 调度新的后台会话、将现有的交互式会话发送到后台，或直接从 shell 启动一个。343您可以从 agent 视图分派新的后台会话，将现有的交互式会话发送或复制到后台，或直接从 shell 启动一个。

344 344

345<h3 id="from-agent-view">345<h3 id="from-agent-view">

346 从 agent view346 从 agent 视图

347</h3>347</h3>

348 348

349在 agent view 底部的输入框中输入提示并按 `Enter` 启动新的后台会话。会话从提示自动命名；稍后可以用 `Ctrl+R` 重命名它。349在 agent 视图底部的输入框中输入提示，然后按 `Enter` 启动新的后台会话。会话会根据提示自动命名；稍后可以使用 `Ctrl+R` 重命名。

350 350

351自动名称是由 [Haiku-class model](/docs/zh-CN/model-config) 编写的简短标签。会话稍后获得的名称也会出现在其行上，包括当你在该会话中 [接受计划](/docs/zh-CN/permission-modes#review-and-approve-a-plan) 时会话获得的 [生成的标题](/docs/zh-CN/sessions#name-your-sessions)。351自动名称是由 [Haiku-class model](/docs/zh-CN/model-config) 生成的简短标签。会话稍后获得的名称也会显示在其行上，包括当您在该会话中 [接受计划](/docs/zh-CN/permission-modes#review-and-approve-a-plan) 时会话获得的 [生成的标题](/docs/zh-CN/sessions#name-your-sessions)。

352 352

353将图像粘贴到提示中以包含任务的屏幕截图或图表。353将图像粘贴到提示中以包含屏幕截图或图表与任务。

354 354

355粘贴的文本长度超过 800 个字符或超过三行会折叠为 `[Pasted text #N]` 占位符，以便输入保持在一行；完整文本在你调度时发送。要在调度前查看或编辑折叠的文本，再次粘贴相同的文本，占位符会展开回输入。355粘贴的文本超过 800 个字符或超过三行时会折叠为 `[Pasted text #N]` 占位符，以便输入保持在一行；完整文本在您分派时发送。要在分派前查看或编辑折叠的文本，请再次粘贴相同的文本，占位符会展开回输入框。

356 356

357前缀或提及提示的部分以控制会话如何启动：357在提示的前缀或提及部分来控制会话如何启动：

358 358

359| 输入 | 效果 |359| 输入 | 效果 |

360| :- | :- |360| :- | :- |

361| `<agent-name> <prompt>` | 如果第一个单词匹配自定义 [subagent](/docs/zh-CN/sub-agents) 名称，该 subagent 作为会话的主代理运行，使用其 frontmatter 中的配置 |361| `<agent-name> <prompt>` | 如果第一个单词与自定义 [subagent](/docs/zh-CN/sub-agents) 名称匹配，该 subagent 将作为会话的主 agent 运行，使用其 frontmatter 中的配置 |

~~367~~ 367

368一小组命令在 agent view 本身中运行而不是调度：368一小组命令在 agent 视图本身中运行，而不是分派：

~~369~~ 369

370* `/exit` 和 `/quit` 关闭 agent view370* `/exit` 和 `/quit` 关闭 agent 视图

371* `/logout` 将你登出371* `/logout` 将您登出

372* `/model` 设置 [调度模型](#set-the-model)372* `/model` 设置 [分派模型](#set-the-model)

373* `/login` 打开登录对话框，以便你可以在不附加到会话的情况下再次登录373* `/login` 打开登录对话框，以便您可以重新登录而无需附加到会话

374* 裸 `/resume` 或其 `/continue` 别名打开存储库过去会话的选择器，以 [恢复一个](#organize-the-list) 作为后台会话。需要 Claude Code v2.1.212 或更高版本374* 裸 `/resume` 或其 `/continue` 别名打开存储库过去会话的选择器，以 [恢复一个](#organize-the-list) 作为后台会话。需要 Claude Code v2.1.212 或更高版本

375 375

376Skills、你自己的命令和提示扩展内置命令如 `/init` 作为其第一个提示发送到新的后台会话。其他内置命令显示 `attach to a session to run it` 提示。你输入的所有内容都保留在提示旁边的输入中，以便你可以编辑它。376Skills、您自己的命令和提示扩展内置命令（如 `/init`）作为其第一个提示发送到新的后台会话。其他内置命令显示 `attach to a session to run it` 提示。您输入的所有内容都保留在提示旁边的输入中，以便您可以编辑。

377 377

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

379 379

380当相同的 `@name` 同时匹配 subagent 和同级存储库时，subagent 优先。不带 `@` 的首字形式也适用，所以以匹配你的某个 subagent 名称的单词开头的提示会调度该 subagent 而不是将该单词视为纯文本。当你想要明确指定时，使用 `@` 形式，或以不同的单词开头提示以避免匹配。380当相同的 `@name` 同时匹配 subagent 和同级存储库时，subagent 优先。裸第一个单词匹配也适用，因此恰好以您的 subagent 名称之一开头的提示会分派该 subagent，而不是将该单词视为纯文本。当您想要明确时使用 `@` 形式，或以不同的单词开头提示以避免匹配。

381 381

382<h4 id="dispatch-to-a-specific-directory">382<h4 id="dispatch-to-a-specific-directory">

383 调度到特定目录383 分派到特定目录

384</h4>384</h4>

385 385

386新会话在你打开 agent view 的目录中运行。要针对不同的目录，使用以下任何一种：386新会话在您打开 agent 视图的目录中运行。要针对不同的目录，请使用以下任何一种：

387 387

388* 在该目录中打开 `claude agents`。388* 在该目录中打开 `claude agents`。

389* 在父目录中打开 `claude agents` 并在提示中用 `@<repo>` 提及一个子存储库。输入 `@` 会列出这些目标：389* 在父目录中打开 `claude agents` 并在提示中使用 `@<repo>` 提及子存储库。输入 `@` 列出这些目标：

390 390

391 * 启动目录下一级的 Git 存储库391 * 启动目录下一级的 Git 存储库

392 * 你启动的存储库的已注册 [git worktrees](/docs/zh-CN/worktrees)，这些 worktrees 位于其目录树内，例如 Claude 在 `.claude/worktrees/` 下创建的那些，标记有其检出的分支。在存储库外添加的 worktrees，例如用 `git worktree add ../feature` 添加的，不会被列出392 * 您启动的存储库的已注册 [git worktrees](/docs/zh-CN/worktrees)，位于其目录树内，例如 Claude 在 `.claude/worktrees/` 下创建的，标记有其检出的分支。在存储库外添加的 Worktrees，例如使用 `git worktree add ../feature`，不会列出

393 * 任何已在列表中有会话的目录393 * 列表中已有会话的任何目录

394 394

395 名称包含空格的目录不会被列出。395 名称包含空格的目录不会列出。

396* 从 shell，`cd` 进入目录并运行 `claude --bg "<prompt>"`。396* 从 shell，`cd` 进入目录并运行 `claude --bg "<prompt>"`。

397 397

398当 agent view 按目录分组时，调度会将提示发送到选定行的目录，所以你可以选择一个组并在不重新输入路径的情况下调度到它。398当 agent 视图按目录分组时，分派会将提示发送到所选行的目录，因此您可以选择一个组并分派到其中，而无需重新输入路径。

399 399

400<h3 id="from-inside-a-session">400<h3 id="from-inside-a-session">

401 从会话内部401 从会话内部

402</h3>402</h3>

403 403

404两个命令将工作从你所在的会话移动到后台：`/background` 将当前对话发送到那里并释放你的终端，`/fork` 在你继续工作的地方发送一个副本。404两个命令将工作从您所在的会话移到后台：`/background` 将当前对话发送到那里并释放您的终端，`/fork` 发送一个副本，同时您继续在原处工作。

405 405

406<h4 id="send-the-session-to-the-background">406<h4 id="send-the-session-to-the-background">

407 将会话发送到后台407 将会话发送到后台

408</h4>408</h4>

409 409

410运行 `/background` 或其别名 `/bg` 将当前对话移动到后台会话。传递提示如 `/bg run the test suite and fix any failures` 以在后台化前先给出一个更多指令。如果 Claude 在你运行 `/bg` 时正在响应，响应会在后台会话中继续。410运行 `/background` 或其别名 `/bg` 将当前对话移到后台会话。传递一个提示，例如 `/bg run the test suite and fix any failures` 以首先给出一个更多指令。如果您运行 `/bg` 时 Claude 正在响应，响应会在后台会话中继续。

411 411

412退出仍有后台工作运行的会话，例如 subagents、后台 shell 命令、工作流或 [monitors](/docs/zh-CN/tools-reference#monitor-tool)，会显示 `Background work is running` 对话而不是立即退出。选择 `Move to background and exit` 以与 `/background` 相同的方式将会话移动到后台并返回你的 shell。当 agent view 被 [关闭](#turn-off-agent-view) 时，不显示该选项。412退出仍有后台工作运行的会话（例如 subagents、后台 shell 命令、工作流或 [monitors](/docs/zh-CN/tools-reference#monitor-tool)）会显示 `Background work is running` 对话框，而不是立即退出。选择 `Move to background and exit` 以与 `/background` 相同的方式将会话移到后台并返回到您的 shell。当 agent 视图 [关闭](#turn-off-agent-view) 时不显示该选项。

413 413

414如果后台会话列表上已有一个会话具有对话的名称，Claude Code 会对新行的名称进行编号，例如 `my-session (2)`，并保持现有行的名称不变。要重命名新行，在 agent view 中选择它并按 `Ctrl+R`。414如果列表上的后台会话已具有对话的名称，Claude Code 会对新行的名称进行编号，例如 `my-session (2)`，并保持现有行的名称不变。要重命名新行，在 agent 视图中选择它并按 `Ctrl+R`。

415 415

416<h4 id="copy-the-session-with-/fork">416<h4 id="copy-the-session-with-/fork">

417 使用 /fork 复制会话417 使用 /fork 复制会话

418</h4>418</h4>

419 419

420运行 `/fork` 将当前对话复制到新的后台会话中，同时原始会话继续运行。副本从对话中到该点的所有内容开始；参见下面的项目符号了解副本运行的位置。它还会继承模型、权限模式、工作量以及你在会话期间添加的任何目录或"不再询问"权限授予。副本在 agent view 中显示为其自己的行。420运行 `/fork` 将当前对话复制到新的后台会话，同时原始会话继续运行。副本从对话中到该点的所有内容开始；请参阅下面的项目符号了解副本运行的位置。它还继承模型、权限模式、努力级别以及您在会话期间添加的任何目录或"不再询问"权限授予。副本在 agent 视图中显示为其自己的行。

421 421

422在 fork 之后，两个对话是独立的：副本所做的任何事情都不会自动进入原始对话，尽管在启用了 [cross-session messaging](/docs/zh-CN/cross-session-messaging) 的会话中，任一会话的 Claude 都可以显式地向另一个会话发送消息。422在 fork 之后，两个对话是独立的：副本所做的任何事情都不会自动进入原始对话，尽管在启用 [cross-session messaging](/docs/zh-CN/cross-session-messaging) 的会话中，任一会话的 Claude 都可以显式地向另一个发送消息。

423 423

424复制会话需要 Claude Code v2.1.212 或更高版本；在 v2.1.161 到 v2.1.211 上，`/fork` 启动一个 [forked subagent](/docs/zh-CN/sub-agents#fork-the-current-conversation)，现在是 `/subtask`。当 [agent view 被关闭](#turn-off-agent-view) 时，`/fork` 保持 forked-subagent 行为，`/subtask` 不可用。424复制会话需要 Claude Code v2.1.212 或更高版本；在 v2.1.161 到 v2.1.211 上，`/fork` 启动 [forked subagent](/docs/zh-CN/sub-agents#fork-the-current-conversation)，现在是 `/subtask`。当 [agent 视图关闭](#turn-off-agent-view) 时，`/fork` 保持 forked-subagent 行为，`/subtask` 不可用。

425 425

426传递提示如 `/fork open a draft pull request with the work so far`，副本立即开始处理它。没有提示的情况下，副本等待其第一个指令：在 `claude agents` 中选择其行并按 `Space` 发送一个，或运行 `claude attach <id>`。选定的行在等待时显示 `space to send it a prompt`。426传递一个提示，例如 `/fork open a draft pull request with the work so far`，副本立即开始处理它。没有提示的情况下，副本等待其第一个指令：在 `claude agents` 中选择其行并按 `Space` 发送一个，或运行 `claude attach <id>`。所选行在等待时显示 `space to send it a prompt`。

427 427

428`/fork` 确认是一行，显示副本的状态，例如 `session running`、其 agent-view 行的名称和其会话 ID 用于 `claude attach`。点击名称以切换到副本：此会话移动到后台，与按 `←` 相同，agent view 打开副本的会话。428`/fork` 确认是一行，显示副本的状态，例如 `session running`、其 agent-view 行的名称和其会话 ID（用于 `claude attach`）。单击名称以切换到副本：此会话移到后台，与按 `←` 相同，agent 视图打开副本的会话。

429 429

430除了副本 [就地编辑](#how-file-edits-are-isolated) 的情况外，Claude Code 指示它在进行代码更改前创建自己的 worktree。在 git 存储库外，只有从 hook 创建的 worktree 移出的副本才会获得该指令；没有 [`WorktreeCreate` hook](/docs/zh-CN/hooks#worktreecreate)，副本就地编辑。从你的 worktree 移出的副本也被告知永远不要编辑、在其中运行命令或进入该 worktree，无论隔离设置如何。430除非副本 [就地编辑](#how-file-edits-are-isolated)，Claude Code 会指示它在进行代码更改前创建自己的 worktree。在 git 存储库外，只有从 hook 创建的 worktree 移出的副本才会获得该指令；没有 [`WorktreeCreate` hook](/docs/zh-CN/hooks#worktreecreate)，副本就地编辑。从您的 worktree 移出的副本也被告知永远不要编辑、在其中运行命令或进入该 worktree，无论隔离设置如何。

431 431

432副本开始的位置取决于当前会话运行的位置：432副本启动的位置取决于当前会话运行的位置：

433 433

434* 像任何调度的会话一样，副本 [在编辑文件前移动到其自己的 worktree](#how-file-edits-are-isolated)。在这种情况下，确认不会提及副本运行的位置。434* 像任何分派的会话一样，副本 [在编辑文件前移到自己的 worktree](#how-file-edits-are-isolated)。在这种情况下，确认不会提及副本运行的位置。

435* 当你的会话在启动后移动到其链接的 [worktree](/docs/zh-CN/worktrees) 时，副本从会话移动前的位置开始，除非它 [就地编辑](#how-file-edits-are-isolated)，在那里的自己的 worktree 中进行代码更改。当你的 worktree 在分支上检出时，该指令也告诉一个副本，其任务建立在你的工作基础上，以你的分支为基础创建其新分支，因为你的分支在你的 worktree 中保持检出。确认以 `runs in the origin tree` 结尾。435* 当您的会话在启动后移到其链接的 [worktree](/docs/zh-CN/worktrees) 时，副本从会话移动前的位置开始，除非它 [就地编辑](#how-file-edits-are-isolated)，在那里进行其代码更改到自己的 worktree。当您的 worktree 在分支上检出时，该指令也告诉副本（其任务建立在您的工作基础上）将其新分支基于您的分支，因为您的分支在您的 worktree 中保持检出。确认以 `runs in the origin tree` 结尾。

436* 当你在具有主工作树的存储库的链接 worktree 内启动会话时，副本在该主工作树中启动，具有相同的 worktree-of-its-own 规则但没有分支指令。确认也以 `runs in the origin tree` 结尾。436* 当您在具有主工作树的存储库的链接 worktree 内启动会话时，副本从该主工作树开始，具有相同的 worktree-of-its-own 规则但没有分支指令。确认也以 `runs in the origin tree` 结尾。

437* 在裸存储库布局的 worktree 内启动的会话没有主工作树可返回，所以副本保持在原地，确认以 `edits this checkout` 结尾。当 worktree 隔离在不在链接 worktree 内的会话中被 [关闭](#how-file-edits-are-isolated) 时，也会出现相同的注释，因为副本随后编辑你打开的文件。437* 在裸存储库布局的 worktree 内启动的会话没有主工作树可返回，因此副本保持原位，确认以 `edits this checkout` 结尾。当 worktree 隔离在不在链接 worktree 内的会话中 [关闭](#how-file-edits-are-isolated) 时，也会出现相同的注释，因为副本随后编辑您打开的文件。

438 438

439使用启动标志启动的会话，副本不会继承，例如替换的系统提示或 `--tools` 允许列表，无法被 fork；Claude Code 会说明这一点而不是进行部分副本。从 agent view 调度的会话正常 fork：副本使用与其来自的会话相同的 [agent definition](/docs/zh-CN/sub-agents) 和附加指令启动。439使用启动标志启动的会话副本不会继承，例如替换的系统提示或 `--tools` 允许列表，无法 fork；Claude Code 会说明这一点，而不是进行部分副本。从 agent 视图分派的会话正常 fork：副本使用与其来自的会话相同的 [agent 定义](/docs/zh-CN/sub-agents) 和附加指令启动。

440 440

441<h4 id="what-carries-over-when-you-background">441<h4 id="what-carries-over-when-you-background">

442 后台化时会继承什么442 后台处理时的继承内容

443</h4>443</h4>

444 444

445后台化启动一个新进程，从保存的对话恢复，进行中的工作会转移到它：运行后台 shell 命令、后台 subagents、动态工作流、你用 [`/loop`](/docs/zh-CN/scheduled-tasks) 创建的计划任务，以及 Claude 对 [artifact comments 的自动回复](/docs/zh-CN/artifacts#let-claude-reply-to-comments-on-its-own) 都会继承并在那里继续运行。一个 subagent 与它启动的所有内容一起移动，所以它仅在所有工作都能转移时才转移。要停止进行中的工作而不是转移它，设置 [`CLAUDE_DISABLE_ADOPT=1`](/docs/zh-CN/env-vars#variables) 环境变量；Claude Code 随后会要求你在后台化前确认。445后台处理启动一个新进程，从保存的对话恢复，进行中的工作移到其中：运行后台 shell 命令、后台 subagents、动态工作流、使用 [`/loop`](/docs/zh-CN/scheduled-tasks) 创建的计划任务以及 Claude 对 [artifact 注释的自动回复](/docs/zh-CN/artifacts#let-claude-reply-to-comments-on-its-own) 都会继承并继续在那里运行。Subagent 与它启动的所有内容一起移动，因此仅当所有该工作也能移动时才会继承。要停止进行中的工作而不是继承它，请设置 [`CLAUDE_DISABLE_ADOPT=1`](/docs/zh-CN/env-vars#variables) 环境变量；Claude Code 随后会在后台处理前要求您确认。

446 446

447当 [dynamic workflow](/docs/zh-CN/workflows) 仍有 subagents 运行时，Claude Code 在后台化前用 `Background this session?` 对话询问，该对话说明有多少 subagents 会重新启动。选择 `Stay` 让它们先完成。如果你确认，Claude Code 在后台会话中重放运行：仍在运行的 subagents 从头开始，所以它们迄今为止使用的令牌会再次花费。参见 [Resume after a pause](/docs/zh-CN/workflows#resume-after-a-pause) 了解哪些已完成的 subagents 返回其保存的结果，哪些再次运行。447当 [dynamic workflow](/docs/zh-CN/workflows) 仍有 subagents 运行时，Claude Code 在后台处理前询问 `Background this session?` 对话框，其中说明有多少 subagents 会重新启动。选择 `Stay` 让它们先完成。如果您确认，Claude Code 会在后台会话中重放运行：仍在运行的 subagents 从头开始，因此它们迄今为止使用的令牌会再次花费。请参阅 [Resume after a pause](/docs/zh-CN/workflows#resume-after-a-pause) 了解哪些已完成的 subagents 返回其保存的结果，哪些再次运行。

448 448

449Claude Code 停止无法转移的工作，例如运行中的 [monitor](/docs/zh-CN/tools-reference#monitor-tool)，并停止拥有监视器的后台 subagent 以及它。当任何此类工作正在运行时，Claude Code 显示 `Background this session?` 对话，以便你可以在它停止工作前确认。449Claude Code 停止无法继承的工作，例如运行的 [monitor](/docs/zh-CN/tools-reference#monitor-tool)，并停止拥有 monitor 的后台 subagent 及其一起。当任何此类工作运行时，Claude Code 显示 `Background this session?` 对话框，以便您可以在停止工作前确认。

450 450

451一旦在后台，会话可以启动新的 subagents、monitors 和后台命令，这些会在后续的分离和重新附加中保持运行。451一旦在后台，会话可以启动新的 subagents、monitors 和后台命令，这些在稍后分离和重新附加时继续运行。

452 452

453来自原始启动的配置标志会传递到后台化的会话，所以其 MCP servers、settings 和备用模型保持有效：453来自原始启动的配置标志通过到后台会话，因此其 MCP 服务器、设置和回退模型保持有效：

454 454

455* `--mcp-config` 和 `--strict-mcp-config`455* `--mcp-config` 和 `--strict-mcp-config`

456* `--settings`456* `--settings`

457* `--setting-sources`

457* `--add-dir`458* `--add-dir`

458* `--plugin-dir`459* `--plugin-dir`

459* `--fallback-model`460* `--fallback-model`

460* `--allow-dangerously-skip-permissions`461* `--allow-dangerously-skip-permissions`

461 462

462你在会话期间用 [`/add-dir`](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) 添加的目录也会传递。传递 `--allow-dangerously-skip-permissions` 会在后台化的会话中保持 `bypassPermissions` 可访问，但它不会授予任何新权限：该模式仍然需要 [Permission mode, model, and effort](#permission-mode-model-and-effort) 中描述的一次性交互式接受。463您在会话期间使用 [`/add-dir`](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) 添加的目录也会继承。继承 `--allow-dangerously-skip-permissions` 使 `bypassPermissions` 在后台会话中可访问，但它不授予任何新内容：该模式仍需要 [Permission mode, model, and effort](#permission-mode-model-and-effort) 中描述的一次性交互式接受。

463 464

464<h3 id="from-your-shell">465<h3 id="from-your-shell">

465 从你的 shell466 从您的 shell

466</h3>467</h3>

467 468

468传递 `--bg` 或其长形式 `--background` 启动直接进入后台的会话：469传递 `--bg` 或其长形式 `--background` 启动直接进入后台的会话：

471claude --bg "investigate the flaky SettingsChangeDetector test"472claude --bg "investigate the flaky SettingsChangeDetector test"

472```473```

473 474

474提示是位置参数，不是 `-p` 值。Claude Code 拒绝 `--bg` 与 `-p` 或 `--print` 结合在任何会话创建前，因为 `--print` 永远不会启动 `claude agents` 附加到的交互式会话。475提示是位置参数，不是 `-p` 值。Claude Code 拒绝 `--bg` 与 `-p` 或 `--print` 组合在任何会话创建前，因为 `--print` 永远不会启动 `claude agents` 附加到的交互式会话。

475 476

476要运行特定的 [subagent](/docs/zh-CN/sub-agents)（你已定义的，例如 `code-reviewer`）作为会话的主代理，结合 `--bg` 和 `--agent`：477如果您从您未 [信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust) 的目录中的终端运行 `claude --bg`，工作区信任对话框会首先出现，会话在您接受后启动。如果您拒绝，Claude Code 会退出而不启动会话。在没有对话框可以出现的地方，例如在脚本中，命令会以 [`Workspace not trusted`](/docs/zh-CN/errors#workspace-not-trusted-when-dispatching-a-background-session) 错误退出。

478

479要运行您定义的特定 [subagent](/docs/zh-CN/sub-agents)（例如 `code-reviewer`）作为会话的主 agent，将 `--bg` 与 `--agent` 组合：

477 480

478```bash theme={null}481```bash theme={null}

479claude --agent code-reviewer --bg "address review comments on PR 1234"482claude --agent code-reviewer --bg "address review comments on PR 1234"

480```483```

481 484

482如果名称不匹配你的任何 subagents，启动失败：Claude Code 打印 `no agent named` 警告，仍然报告会话为后台化，但会话立即以 `--agent '<name>' not found` 错误退出。485如果名称与您的任何 subagents 不匹配，启动失败：Claude Code 打印 `no agent named` 警告，仍然报告会话为后台，但会话立即以 `--agent '<name>' not found` 错误退出。

483 486

484当后台化的会话稍后恢复或重新启动时，Claude Code 恢复代理及其工具限制；对于其系统提示，参见 [System prompt flags in resumed conversations](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。它首先在会话自己的目录中搜索代理，前提是你已 [信任该工作区](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)，所以项目范围的代理在会话从另一个目录恢复时仍然加载。如果代理不再存在，会话继续使用默认工具，其记录以 [warning naming the agent](/docs/zh-CN/errors#session-agent-no-longer-available) 打开。487当后台会话稍后恢复或重新启动时，Claude Code 恢复 agent 及其工具限制；对于其系统提示，请参阅 [System prompt flags in resumed conversations](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。它首先在会话自己的目录中搜索 agent，前提是您已 [信任该工作区](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)，因此项目范围的 agent 在从另一个目录恢复会话时仍会加载。如果 agent 不再存在，会话继续使用默认工具，其记录打开时带有 [warning naming the agent](/docs/zh-CN/errors#session-agent-no-longer-available)。

485 488

486要在后台继续现有对话，用 `--resume` 传递其完整会话 ID：489要在后台继续现有对话，使用 `--resume` 传递其完整会话 ID：

487 490

488```bash theme={null}491```bash theme={null}

489claude --resume 1f0e2c9a-6d0b-4c11-9f39-2a77c1d4e8b5 --bg "pick up where you left off and finish the migration"492claude --resume 1f0e2c9a-6d0b-4c11-9f39-2a77c1d4e8b5 --bg "pick up where you left off and finish the migration"

491 494

492在 Claude Code v2.1.257 或更高版本上，Claude Code 要么在相同 ID 下继续该会话，要么在新 ID 下启动副本并打印 `note:` 行解释为什么它无法就地继续。当会话就地继续时，`claude agents` 为其显示一行。495在 Claude Code v2.1.257 或更高版本上，Claude Code 要么在相同 ID 下继续该会话，要么在新 ID 下启动副本并打印 `note:` 行解释为什么它无法就地继续。当会话就地继续时，`claude agents` 为其显示一行。

493 496

494当你将 `--bg` 与 `--continue`、裸 `--resume` 或 `--resume` 与名称或文件路径结合时，Claude Code 总是启动这样的副本。添加 `--fork-session` 以有意启动副本，不带注释。497当您将 `--bg` 与 `--continue`、裸 `--resume` 或 `--resume` 与名称或文件路径组合时，Claude Code 总是启动这样的副本。添加 `--fork-session` 以有目的地启动副本，不带注释。

495 498

496传递 `--name` 以在 agent view 中设置会话的显示名称而不是自动生成的名称：499传递 `--name` 以在 agent 视图中设置会话的显示名称，而不是自动生成的名称：

497 500

498```bash theme={null}501```bash theme={null}

499claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"502claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"

500```503```

501 504

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

503 506

504```text theme={null}507```text theme={null}

505backgrounded · 7c5dcf5d · flaky-test-fix508backgrounded · 7c5dcf5d · flaky-test-fix

513 运行 shell 命令516 运行 shell 命令

514</h4>517</h4>

515 518

516要运行 shell 命令作为后台作业而不是 Claude 会话，传递 `--exec`。以下示例将 `pytest -x` 作为后台作业运行：519要运行 shell 命令作为后台作业而不是 Claude 会话，传递 `--exec`。以下示例运行 `pytest -x` 作为后台作业：

517 520

518```bash theme={null}521```bash theme={null}

519claude --bg --exec 'pytest -x'522claude --bg --exec 'pytest -x'

520```523```

521 524

522从 agent view，通过在调度输入的第一个字符处输入 `!` 调度相同类型的作业：`!` 显示为前缀，其后的所有内容都是命令，`Enter` 启动作业。525从 agent 视图，通过在分派输入的第一个字符中输入 `!` 分派相同类型的作业：`!` 显示为前缀，其后的所有内容是命令，`Enter` 启动作业。

523 526

524该命令作为 PTY 支持的作业运行，并在 agent view 中显示为一行，最近的输出行作为其状态。shell 作业运行命令代替 Claude，所以不调用任何模型，输出也不发送到任何会话。527命令作为 PTY 支持的作业运行，在 agent 视图中显示为一行，最近的输出行作为其状态。Shell 作业运行命令代替 Claude，因此不调用任何模型，输出不发送到任何会话。

525 528

526要查看输出，附加到该行，按 `Space` 以在不附加的情况下查看，或从你的 shell 运行 `claude logs <id>`。捕获的输出保留在内存中，不写入磁盘。该行及其输出在命令退出后约五分钟自动清理，所以如果你需要结果，请在那之前读取它。529要查看输出，附加到行，按 `Space` 在不附加的情况下查看，或从您的 shell 运行 `claude logs <id>`。捕获的输出保留在内存中，不写入磁盘。行及其输出在命令退出后约五分钟自动清理，因此如果您需要结果，请在那之前读取。

527 530

528<h3 id="how-file-edits-are-isolated">531<h3 id="how-file-edits-are-isolated">

529 文件编辑如何隔离532 文件编辑如何隔离

530</h3>533</h3>

531 534

532每个后台会话，无论是从 agent view、`/bg` 还是 `claude --bg` 启动，都在你的工作目录中启动。在编辑文件前，Claude 将会话移动到 `.claude/worktrees/` 下的隔离 [git worktree](/docs/zh-CN/worktrees) 中，所以并行会话可以读取相同的检出但每个都写入自己的。一旦会话在其 worktree 中，Claude Code [enforces worktree isolation](/docs/zh-CN/worktrees#how-claude-code-enforces-isolation) 对会话和它生成的任何 subagents。535每个后台会话，无论是从 agent 视图、`/bg` 还是 `claude --bg` 启动，都在您打开的工作目录中启动。在编辑文件前，Claude 将会话移到 `.claude/worktrees/` 下的隔离 [git worktree](/docs/zh-CN/worktrees) 中，因此并行会话可以读取相同的检出，但每个写入自己的。一旦会话在其 worktree 中，Claude Code [为会话和它生成的任何 subagents 强制 worktree 隔离](/docs/zh-CN/worktrees#how-claude-code-enforces-isolation)。

533 536

534Claude 在以下情况下跳过 worktree：537Claude 在以下情况下跳过 worktree：

535 538

536* 会话已经在链接的 git worktree 内，无论 Claude 是在 `.claude/worktrees/` 下创建的还是你用 `git worktree add` 在其他地方创建的539* 会话已在链接的 git worktree 内，无论 Claude 在 `.claude/worktrees/` 下创建它还是您使用 `git worktree add` 在其他地方创建它

537* Claude 正在编辑的文件在链接的 git worktree 内，例如会话或其 subagent 用 `git worktree add` 创建的540* Claude 编辑的文件在链接的 git worktree 内，例如会话或其 subagent 使用 `git worktree add` 创建的

538* 工作目录不是 git 存储库且没有配置 [`WorktreeCreate` hook](/docs/zh-CN/hooks#worktreecreate)541* 工作目录不是 git 存储库，且没有配置 [`WorktreeCreate` hook](/docs/zh-CN/hooks#worktreecreate)

539* 写入在工作目录外542* 写入在工作目录外

540 543

541要为 git worktrees 不实用的存储库关闭 worktree 隔离，将 [`worktree.bgIsolation`](/docs/zh-CN/settings-reference#worktree-bgisolation) 设置为 `"none"`。后台会话随后直接编辑你的工作副本而不先移动到 worktree。将设置添加到项目的 `.claude/settings.json`：544要为 git worktrees 不实用的存储库关闭 worktree 隔离，将 [`worktree.bgIsolation`](/docs/zh-CN/settings-reference#worktree-bgisolation) 设置为 `"none"`。后台会话随后直接编辑您的工作副本，而无需先移到 worktree。将设置添加到项目的 `.claude/settings.json`：

542 545

543```json theme={null}546```json theme={null}

544{547{

548}551}

549```552```

550 553

551在 git 存储库外，会话直接写入工作目录且彼此不隔离，所以避免调度编辑相同文件的并行会话。如果你使用不同的版本控制系统，配置一个 [`WorktreeCreate` hook](/docs/zh-CN/worktrees#non-git-version-control)，Claude 会以与 git 相同的方式隔离编辑。554在 git 存储库外，会话直接写入工作目录，彼此之间不隔离，因此避免分派编辑相同文件的并行会话。如果您使用不同的版本控制系统，配置 [`WorktreeCreate` hook](/docs/zh-CN/worktrees#non-git-version-control)，Claude 以与 git 相同的方式隔离编辑。

552 555

553当 hook 在不是 git 存储库的目录中失败时，Claude 跳过该目录的隔离并就地编辑工作目录。在 git 存储库内，Claude Code 阻止对共享检出的写入，直到 Claude 将会话移动到 worktree。556当 hook 在不是 git 存储库的目录中失败时，Claude 跳过该目录的隔离，就地编辑工作目录。在 git 存储库内，Claude Code 阻止对共享检出的写入，直到 Claude 将会话移到 worktree。

554 557

555要找到会话的 worktree 路径，查看会话或附加并检查其工作目录。558要找到会话的 worktree 路径，查看会话或附加并检查其工作目录。

556 559

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

558 561

559当后台会话在 Claude 进入的 worktree 中进行了代码更改时，Claude Code 指示 Claude 在完成前保留工作，所以如果你删除会话及其 worktree，它会存活：562当后台会话在 Claude 进入的 worktree 中进行了代码更改时，Claude Code 指示 Claude 在完成前保留工作，因此如果您删除会话及其 worktree，它会存活：

560 563

561* **提交并推送**：Claude 无需询问即可提交，当存储库有远程时推送分支。564* **提交并推送**：Claude 无需询问即可提交，当存储库有远程时推送分支。

562* **草稿拉取请求**：当任务要求时 Claude 打开一个，[`#N` label](#pull-request-status) 出现在行上。565* **草稿 pull request**：Claude 在任务要求时打开一个，[`#N` 标签](#pull-request-status) 出现在行上。

563* **永不**：推送到 `main` 或 `master`、强制推送和合并。566* **永不**：推送到 `main` 或 `master`、强制推送和合并。

564* **你的 git 指令优先**：如果任务、`CLAUDE.md` 或 [memory](/docs/zh-CN/memory) 说你自己处理提交或推送，Claude 将 git 留给你。567* **您的 git 指令优先**：如果任务、`CLAUDE.md` 或 [memory](/docs/zh-CN/memory) 说您自己处理提交或推送，Claude 将 git 留给您。

565 568

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

567 570

568无论任务如何，Claude 以报告结束作业，说明它做了什么以及工作在哪里：路径、分支、拉取请求或答案本身。571无论任务如何，Claude 以报告结束作业，说明它做了什么以及工作在哪里：路径、分支、pull request 或答案本身。

569 572

570<h4 id="what-deleting-a-session-removes">573<h4 id="what-deleting-a-session-removes">

571 删除会话会移除什么574 删除会话会移除什么

572</h4>575</h4>

573 576

574在 [agent view](#organize-the-list) 中用 `Ctrl+X` 两次或用 [`claude rm`](#manage-sessions-from-the-shell) 删除会话。除了下面保留的情况外，会话离开列表。其记录通过 `claude --resume` 保留在你的机器上，移除在监督者重新启动后存活。577在 [agent 视图](#organize-the-list) 中使用 `Ctrl+X` 两次或使用 [`claude rm`](#manage-sessions-from-the-shell) 删除会话。除了下面保留的情况外，会话离开列表。其记录通过 `claude --resume` 保留在您的机器上，移除在主管重新启动后存活。

575 578

576Claude 为会话创建的 worktree 会发生什么：579Claude 为会话创建的 worktree 会发生什么：

577 580

578* Agent view 删除它，包括未提交的更改，所以先提交你想保留的内容。581* Agent 视图移除它，包括未提交的更改，因此首先提交您想保留的内容。

579* `claude rm` 当它有未提交的更改时保留它，以及会话行。582* `claude rm` 在它有未提交的更改时保留它，以及会话行。

580* 当另一个运行中的会话正在使用或已锁定 worktree 时，agent view 和 `claude rm` 都不会删除它，再次删除不会改变这一点。Claude Code 保留 worktree 和会话，并命名保留的目录和原因；在 agent view 中，会话的行显示 `not deleted`。关闭另一个会话，然后再次删除。583* Agent 视图和 `claude rm` 都不会移除另一个运行中的会话正在使用或已锁定的 worktree，再次删除不会改变这一点。Claude Code 保留 worktree 和会话，并命名保留的目录和原因；在 agent 视图中，会话的行显示 `not deleted`。关闭另一个会话，然后再次删除。

581* 当你删除一个 worktree 有 Claude Code 无法确认保存在其他地方的提交的会话时，Claude Code 保留 worktree 和会话，消息命名 worktree 的分支和有多少未推送的提交。消息还提供两种前进方式：推送提交，或再次删除以丢弃它们。584* 当您删除其 worktree 有 Claude Code 无法确认保存在其他地方的提交的会话时，Claude Code 保留 worktree 和会话，消息命名 worktree 的分支和有多少未推送的提交。消息还提供两种前进方式：推送提交或再次删除以丢弃它们。

582 585

583 远程上的提交不会阻止删除。本地副本上的提交也不会，只要该分支在你的主检出（存储库目录本身而不是 worktree）中检出。586 远程上的提交不会阻止删除。本地副本上的提交也不会，您的 `origin` 远程的默认分支，只要该分支在您的主检出中检出，存储库目录本身而不是 worktree。

584 587

585 在该拒绝后，你选择：588 在该拒绝后，您选择：

586 589

587 * 要保留提交，推送它们或将它们合并到该默认分支，然后再次删除会话。590 * 要保留提交，推送它们或将它们合并到该默认分支，然后再次删除会话。

588 * 要丢弃它们，再次删除会话而不推送：在 agent view 中的其行上按 `Ctrl+X` 两次，或运行拒绝打印的 `claude rm <id> --discard-unpushed` 命令。这会删除会话和 worktree 以及其分支，丢弃未推送的提交和任何未提交的更改。591 * 要丢弃它们，再次删除会话而不推送：在 agent 视图中的其行上按 `Ctrl+X` 两次，或运行拒绝打印的 `claude rm <id> --discard-unpushed` 命令。这移除会话和 worktree 及其分支，丢弃未推送的提交和任何未提交的更改。

592

593 当您再次删除时，Claude Code 仅丢弃拒绝显示的内容：如果 worktree 自那以后获得了提交，Claude Code 再次保留它并显示更新的状态。

594

595 当另一个已完成的会话的记录也命名 worktree 时，它在您再次删除时保留；推送提交，然后再次删除。

596* git 不再识别的 worktree，例如在 `git worktree prune` 后，不会阻止删除。Claude Code 删除会话并将目录留在磁盘上。

597* 当 git 或您的 [`WorktreeRemove` hook](/docs/zh-CN/hooks#worktreeremove) 无法移除 worktree 时，Claude Code 保留 worktree 和会话，消息命名原因。对于 hook，消息说它如何结束，例如 `exited 1`，并引用其 stderr 的开始。消息还告诉您接下来要做以下哪一个：

598

599 * 再次删除会话以无论如何移除目录，通过在 agent 视图中的其行上按 `Ctrl+X` 两次或运行 `claude rm` 拒绝打印的 `claude rm <id> --force-remove-worktree <worktree-id>` 命令。Worktree 的分支保留在存储库中。

589 600

590 当你再次删除时，Claude Code 仅丢弃拒绝显示的内容：如果 worktree 自那以后获得了提交，Claude Code 再次保留它并显示更新的状态。601 Claude Code 仅在可以确认以下所有内容时提供此选项：

591 602

592 当另一个已完成会话的记录也命名 worktree 时，当你再次删除时它保留；推送提交，然后再次删除。603 * 目录是存储库在 `.claude/worktrees/` 下的链接 worktrees 之一

593* git 不再识别的 worktree，例如在 `git worktree prune` 后，不会阻止删除。Claude Code 删除会话并在磁盘上留下目录。604 * Worktree 和检出的子模块都没有对跟踪文件的未提交更改

594* 当 git 或你的 [`WorktreeRemove` hook](/docs/zh-CN/hooks#worktreeremove) 无法删除 worktree 时，Claude Code 保留 worktree 和会话，消息命名原因。对于 hook，消息说它如何结束，例如 `exited 1`，并引用其 stderr 的开始。消息还告诉你接下来要做以下哪一个：605 * 没有其他会话的记录命名它

595 606

596 * 再次删除会话以无论如何删除目录，在 agent view 中的其行上按 `Ctrl+X` 两次或运行 `claude rm` 拒绝打印的 `claude rm <id> --force-remove-worktree <worktree-id>` 命令。Claude Code 仅在它可以确认目录是存储库在 `.claude/worktrees/` 下的链接 worktrees 之一，没有对跟踪文件的未提交更改、其内没有嵌套存储库，没有其他会话的记录命名它时才提供此选项。worktree 的分支保留在存储库中。607 当 Claude Code 无法验证子模块检出的状态时，例如被单独的 git 存储库替换的，它也不提供此选项。

597 * 修复阻碍的东西，例如提交或隐藏未提交的更改、关闭使用目录的任何东西或修复 hook，然后再次删除会话。608 * 修复阻碍的内容，例如提交或隐藏未提交的更改、将单独的 git 存储库移出 worktree、关闭使用目录的任何内容或修复 hook，然后再次删除会话。

598 * 自己删除目录，然后再次删除会话。609 * 自己移除目录，然后再次删除会话。

599 610

600你自己创建的 worktree 并在其中启动会话的，无论哪种方式都会保留在原地。611您自己创建并在其内启动会话的 worktree 无论如何都会保留。

601 612

602一个 worktree 目录不属于任何 git 存储库的会话，因为存储库被删除或 [`WorktreeCreate` hook](/docs/zh-CN/hooks#worktreecreate) 在其他地方创建了目录，仍然可以被删除。当文件保留在目录中时：613其 worktree 目录不属于任何 git 存储库的会话，因为存储库被删除或 [`WorktreeCreate` hook](/docs/zh-CN/hooks#worktreecreate) 在其他地方创建了目录，仍然可以删除。当目录中仍有文件时：

603 614

604* Agent view 在丢弃它们前要求相同的 `Ctrl+X` 双按。对于 hook 创建的目录，它运行你的 [`WorktreeRemove` hook](/docs/zh-CN/hooks#worktreeremove)，没有一个它拒绝删除并保留会话。615* Agent 视图在丢弃它们前要求相同的 `Ctrl+X` 双按。对于 hook 创建的目录，它运行您的 [`WorktreeRemove` hook](/docs/zh-CN/hooks#worktreeremove)，没有一个它拒绝删除并保留会话。

605* `claude rm` 保留会话和 worktree，并命名原因。616* `claude rm` 保留会话和 worktree，并命名原因。

606 617

607任一路径都保留另一个已完成会话的记录命名的目录。618任一路径保留另一个已完成的会话的记录命名的目录。

608 619

609<h3 id="set-the-model">620<h3 id="set-the-model">

610 设置模型621 设置模型

611</h3>622</h3>

612 623

613agent view 标题中显示的模型名称是调度默认值。你从输入启动的新会话使用此模型，这来自你的用户设置中的 [`model` 设置](/docs/zh-CN/settings-reference#model)。通过在 [`/model` 选择器](/docs/zh-CN/model-config) 中选择模型来设置它，或直接编辑设置。624agent 视图标题中显示的模型名称是分派默认值。您从输入启动的新会话使用此模型，它来自您的用户设置中的 [`model` 设置](/docs/zh-CN/settings-reference#model)。通过在 [`/model` 选择器](/docs/zh-CN/model-config) 中选择模型或直接编辑设置来设置它。

614 625

615要为整个 agent view 会话覆盖调度默认值，在打开 agent view 时传递 `--model`。参见 [Permission mode, model, and effort](#permission-mode-model-and-effort)。626要为整个 agent 视图会话覆盖分派默认值，在打开 agent 视图时传递 `--model`。请参阅 [Permission mode, model, and effort](#permission-mode-model-and-effort)。

616 627

617要从 agent view 内部更改调度默认值，在调度输入中输入 `/model` 后跟模型名称并按 `Enter`。标题更新以显示该模型，带有 `(session)` 标记，之后调度的会话使用它。输入 `/model default` 以清除覆盖并返回调度默认值。此覆盖持续当前 `claude agents` 运行的其余部分，不写入你的设置文件。以下示例在 Opus 上调度一个会话，在 Sonnet 上调度下一个：628要从 agent 视图内更改分派默认值，在分派输入中输入 `/model` 后跟模型名称并按 `Enter`。标题更新以显示该模型，带有 `(session)` 标记，您之后分派的会话使用它。输入 `/model default` 清除覆盖并返回分派默认值。此覆盖持续当前 `claude agents` 运行的其余部分，不写入您的设置文件。以下示例在 Opus 上分派一个会话，在 Sonnet 上分派下一个：

618 629

619```text theme={null}630```text theme={null}

620/model opus631/model opus

625 636

626每个后台会话可以在不同的模型上运行。要为一个会话覆盖它：637每个后台会话可以在不同的模型上运行。要为一个会话覆盖它：

627 638

628* 从 shell，用 `claude --bg` 传递 `--model`。639* 从 shell，使用 `claude --bg` 传递 `--model`。

629* 附加到运行中的会话并运行 `/model` 以切换：从选择器中选择，或输入 `/model <name>`，保存为你的新会话默认值，除非你在选择器中按 `s` 进行仅会话切换。如果会话被重新生成，仅会话切换会持续。640* 附加到运行中的会话并运行 `/model` 以切换：从选择器中选择或输入 `/model <name>` 保存为您的新会话默认值，除非您在选择器中按 `s` 进行仅会话切换。仅会话切换在会话重新生成时持续。

630* 调度一个 [subagent](/docs/zh-CN/sub-agents)，其 frontmatter 设置 `model` 字段。641* 分派其 frontmatter 设置 `model` 字段的 [subagent](/docs/zh-CN/sub-agents)。

631 642

632<h3 id="permission-mode-model-and-effort">643<h3 id="permission-mode-model-and-effort">

633 权限模式、模型和工作量644 权限模式、模型和努力

634</h3>645</h3>

635 646

636后台会话从它运行的位置和方式获取其设置、提供商、权限模式、模型和工作量。下面的小节涵盖每个来源，以及当监督者重新启动会话时什么持续。647后台会话从您分派它的位置和方式获取其设置、提供者、权限模式、模型和努力。下面的小节涵盖每个来源，以及主管重新启动会话时持续的内容。

637 648

638<h4 id="settings-and-provider">649<h4 id="settings-and-provider">

639 设置和提供商650 设置和提供者

640</h4>651</h4>

641 652

642后台会话从它运行的目录读取其 [settings](/docs/zh-CN/settings)，就像你在那里启动了 `claude` 一样。这包括项目设置中的 [`env` 值](/docs/zh-CN/settings-reference#env)，所以在那里设置的 `ANTHROPIC_MODEL` 或提供商变量适用于该目录中的每个后台会话。653后台会话从它运行的目录读取其 [settings](/docs/zh-CN/settings)，与您在该目录启动 `claude` 时相同，使用 [它继承的配置标志](#what-carries-over-when-you-background)。这包括项目设置中的 [`env` 值](/docs/zh-CN/settings-reference#env)，因此在那里设置的 `ANTHROPIC_MODEL` 或提供者变量适用于该目录中的每个后台会话。

643 654

644后台会话也用你调度它的 shell 的 `PATH` 运行，所以它运行的命令找到与你的终端相同的工具。它也保留该 shell 的云提供商选择，例如 `CLAUDE_CODE_USE_BEDROCK` 或 `CLAUDE_CODE_USE_VERTEX`，以及其 `ANTHROPIC_DEFAULT_*_MODEL` 别名和任何 [`CLAUDE_CODE_EXTRA_BODY`](/docs/zh-CN/env-vars) 覆盖你在那里导出的。655后台会话也使用您分派它的 shell 的 `PATH` 运行，因此它运行的命令找到与您的终端相同的工具。它也保留该 shell 的云提供者选择，例如 `CLAUDE_CODE_USE_BEDROCK` 或 `CLAUDE_CODE_USE_VERTEX`，以及其 `ANTHROPIC_DEFAULT_*_MODEL` 别名和您在那里导出的任何 [`CLAUDE_CODE_EXTRA_BODY`](/docs/zh-CN/env-vars) 覆盖。

645 656

646<h4 id="llm-gateway">657<h4 id="llm-gateway">

647 LLM gateway658 LLM gateway

648</h4>659</h4>

649 660

650如果你通过 [LLM gateway](/docs/zh-CN/llm-gateway) 路由 Claude Code，将网关变量放在设置文件的 `env` 块中而不是在你的 shell 中导出它们，后台会话用其余设置读取它们。[Set in a settings file](/docs/zh-CN/llm-gateway-connect#set-in-a-settings-file) 显示块和要使用哪个设置文件用于凭证。661如果您通过 [LLM gateway](/docs/zh-CN/llm-gateway) 路由 Claude Code，将 gateway 变量放在设置文件的 `env` 块中，而不是在您的 shell 中导出它们，后台会话与其余设置一起读取它们。[Set in a settings file](/docs/zh-CN/llm-gateway-connect#set-in-a-settings-file) 显示块和要使用哪个设置文件作为凭证。

651 662

652如果你仅在你的 shell 中导出网关 `ANTHROPIC_BASE_URL`，它到达后台会话，以及 `ANTHROPIC_CUSTOM_HEADERS` 和你与它导出的凭证，仅当 [supervisor](#the-supervisor-process) 本身从导出相同网关的 shell 启动时，仅在这些情况下：663如果您仅在 shell 中导出 gateway `ANTHROPIC_BASE_URL`，它到达后台会话，以及您与它导出的 `ANTHROPIC_CUSTOM_HEADERS` 和凭证，仅当 [supervisor](#the-supervisor-process) 本身从导出相同 gateway 的 shell 启动时，仅在这些情况下：

653 664

654* 你用 `←` 或 `/background` 后台化你自己的会话665* 您使用 `←` 或 `/background` 后台处理您自己的会话

655* 你调度一个会话到你所在的目录666* 您分派会话到您所在的目录

656* 你通过附加或回复它唤醒你所在目录中的停止会话667* 您通过附加或回复来唤醒您所在目录中的停止会话

657 668

658Claude Code 在云提供商前转发网关。如果你调度的 shell 选择提供商并用其 auth-bypass 标志导出其网关端点，Claude Code 在适用于 `ANTHROPIC_BASE_URL` 的条件下将端点和标志对转发到会话，以及 `ANTHROPIC_CUSTOM_HEADERS`。例如，导出 `CLAUDE_CODE_USE_VERTEX=1` 与 `ANTHROPIC_VERTEX_BASE_URL` 和 `CLAUDE_CODE_SKIP_VERTEX_AUTH=1`，Claude Code 转发该端点和标志。669Claude Code 在云提供者前转发 gateway。如果您分派的 shell 选择提供者并使用其 auth-bypass 标志导出其 gateway 端点，Claude Code 在适用于 `ANTHROPIC_BASE_URL` 的条件下转发端点和标志对，以及 `ANTHROPIC_CUSTOM_HEADERS`。例如，导出 `CLAUDE_CODE_USE_VERTEX=1` 与 `ANTHROPIC_VERTEX_BASE_URL` 和 `CLAUDE_CODE_SKIP_VERTEX_AUTH=1`，Claude Code 转发该端点和标志。

659 670

660Claude Code 仅将转发的网关应用于该会话的运行进程，永远不会将其写入磁盘。671Claude Code 仅将转发的 gateway 应用于该会话的运行进程，永远不写入磁盘。

661 672

662<h4 id="permission-mode">673<h4 id="permission-mode">

663 权限模式674 权限模式

664</h4>675</h4>

665 676

666[permission mode](/docs/zh-CN/permissions) 取决于你如何启动会话：677[permission mode](/docs/zh-CN/permissions) 取决于您如何启动会话：

667 678

668* **用 `/bg` 或 `←` 后台化**：Claude Code 保留会话所在的权限模式，所以你切换到 `acceptEdits` 或 `auto` 的会话在分离后仍保持该模式679* **使用 `/bg` 或 `←` 后台处理**：Claude Code 保留会话所在的权限模式，因此您切换到 `acceptEdits` 或 `auto` 的模式在分离后保留在那里

669* **从你用 `←` 打开的 agent view 调度**：目标自己的配置优先，你来自的会话的权限模式在没有其他设置一个时适用680* **从使用 `←` 打开的 agent 视图分派**：目标自己的配置优先，您来自的会话的权限模式在没有其他设置时适用

670* **从 shell 中启动的 `claude agents` 或用 `claude --bg` 调度**：新会话以新 `claude` 会话在该目录中的方式启动，除非你从用 [dispatch defaults](#dispatch-defaults) 打开的 agent view 调度它。[Which permission mode a session starts in](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in) 列出顺序681* **从 shell 中启动的 `claude agents` 或使用 `claude --bg` 分派**：新会话以新 `claude` 会话在该目录中的方式启动，除非您从使用 [dispatch defaults](#dispatch-defaults) 打开的 agent 视图分派。[Which permission mode a session starts in](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in) 列出顺序

671 682

672对于你从用 `←` 打开的 agent view 调度的会话，Claude Code 从适用的第一个中获取权限模式：683对于您从使用 `←` 打开的 agent 视图分派的会话，Claude Code 从适用的第一个中获取权限模式：

673 684

6741. 目标目录的 [`permissions.defaultMode`](/docs/zh-CN/settings-reference#permissions-defaultmode)。两个来源规则适用：6851. 目标目录的 [`permissions.defaultMode`](/docs/zh-CN/settings-reference#permissions-defaultmode)。两个源规则适用：

675 * `auto` 和 `bypassPermissions` [仅从托管设置、`--settings` 文件或 `~/.claude/settings.json` 生效](/docs/zh-CN/settings-reference#permissions-defaultmode)。686 * `auto` 和 `bypassPermissions` [仅从托管设置、`--settings` 文件或 `~/.claude/settings.json` 生效](/docs/zh-CN/settings-reference#permissions-defaultmode)。

676 * Claude Code 拒绝来自项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 的 `defaultMode`，该模式选择比你来自的会话所在的更宽松的模式。687 * Claude Code 拒绝来自项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 的 `defaultMode`，选择比您来自的会话所在的权限模式更宽松的模式。

6772. 你来自的会话的权限模式6882. 您来自的会话的权限模式

678 689

679当 Claude Code 拒绝来源的模式太宽松时，列表中的下一个来源决定。例如，如果你从 plan-mode 会话调度到一个检入的设置要求 `acceptEdits` 的目录，新会话在 plan mode 中启动。如果你将该 `defaultMode` 移动到 `~/.claude/settings.json`，它无论你来自的会话的权限模式如何都适用。690当 Claude Code 拒绝源的模式为过于宽松时，列表中的下一个源决定。例如，如果您从计划模式会话分派到其检入的设置要求 `acceptEdits` 的目录，新会话在计划模式中启动。如果您将该 `defaultMode` 移到 `~/.claude/settings.json`，它无论您来自的会话的权限模式如何都适用。

680 691

681宽松性运行 plan，然后 Manual 和 `dontAsk`，然后 `acceptEdits` 和 auto，它们彼此计为更宽松，然后 `bypassPermissions`。692宽松性运行计划，然后手动和 `dontAsk`，然后 `acceptEdits` 和 auto，每个计为比另一个更宽松，然后 `bypassPermissions`。

682 693

683<h4 id="dispatch-defaults">694<h4 id="dispatch-defaults">

684 调度默认值695 分派默认值

685</h4>696</h4>

686 697

687要为从 agent view 调度的每个会话设置默认值，在打开它时传递 `--permission-mode`、`--model`、`--effort` 或 `--agent` 中的任何一个：698要为您从 agent 视图分派的每个会话设置默认值，在打开它时传递 `--permission-mode`、`--model`、`--effort` 或 `--agent` 中的任何一个：

688 699

689```bash theme={null}700```bash theme={null}

690claude agents --permission-mode plan --model opus --effort high701claude agents --permission-mode plan --model opus --effort high

691```702```

692 703

693`--effort` 这里接受与 [top-level `--effort` flag](/docs/zh-CN/cli-reference#cli-flags) 相同的值，包括 `ultracode`。704`--effort` 这里接受与 [top-level `--effort` 标志](/docs/zh-CN/cli-reference#cli-flags) 相同的值，包括 `ultracode`。

694 705

695`--agent` 设置当调度提示未命名一个时使用的 [subagent](/docs/zh-CN/sub-agents)，无论是用 `@name` 还是作为第一个单词。如果设置了一个，它默认为 [`agent` 设置](/docs/zh-CN/settings-reference#agent)，否则为内置的全能 `claude` 代理。在调度输入中命名 subagent 会覆盖两者。706`--agent` 设置当分派提示不命名一个时使用的 [subagent](/docs/zh-CN/sub-agents)，要么使用 `@name` 要么作为第一个单词。它默认为 [`agent` 设置](/docs/zh-CN/settings-reference#agent)（如果设置了），否则为内置的 catch-all `claude` agent。在分派输入中命名 subagent 覆盖两者。

696 707

697`claude agents` 也接受 `--dangerously-skip-permissions` 作为 `--permission-mode bypassPermissions` 的简写，以及 `--allow-dangerously-skip-permissions` 以在每个调度会话的 `Shift+Tab` 循环中使 `bypassPermissions` 可用而不带权限模式启动。两者都匹配 [top-level CLI flags](/docs/zh-CN/cli-reference)。708`claude agents` 也接受 `--dangerously-skip-permissions` 作为 `--permission-mode bypassPermissions` 的简写，和 `--allow-dangerously-skip-permissions` 使 `bypassPermissions` 在每个分派会话的 `Shift+Tab` 循环中可用，而不在该模式中启动。两者都匹配 [top-level CLI flags](/docs/zh-CN/cli-reference)。

698 709

699传递 `--restricted` 以在 [restricted mode](/docs/zh-CN/cli-reference#cli-flags) 中启动你从视图调度的每个会话，就像每个都用顶级 `--restricted` 标志启动一样。需要 Claude Code v2.1.248 或更高版本。710传递 `--restricted` 以在 [restricted mode](/docs/zh-CN/cli-reference#cli-flags) 中启动您从视图分派的每个会话，就像每个都使用 top-level `--restricted` 标志启动一样。需要 Claude Code v2.1.248 或更高版本。

700 711

701活跃的默认值出现在调度输入下方的页脚中。712活跃的默认值出现在分派输入下方的页脚中。

702 713

703Claude Code 拒绝 `claude --bg --permission-mode bypassPermissions` 直到你通过交互式运行 `claude --dangerously-skip-permissions` 一次接受了绕过免责声明，因为该模式让你没有看到的会话无需批准就能行动。传递 `--dangerously-skip-permissions` 或 `--permission-mode bypassPermissions` 到 `claude agents` 在你之前没有接受它时显示相同的免责声明，接受会将 `bypassPermissions` 应用到你从视图启动的会话。传递 `--allow-dangerously-skip-permissions` 也显示相同的免责声明，接受会在这些会话的 `Shift+Tab` 循环中使 `bypassPermissions` 可用而不在其中启动它们。714Claude Code 拒绝 `claude --bg --permission-mode bypassPermissions` 直到您通过运行 `claude --dangerously-skip-permissions` 一次交互式接受 bypass 免责声明，因为该模式让您不观看的会话无需批准即可行动。将 `--dangerously-skip-permissions` 或 `--permission-mode bypassPermissions` 传递给 `claude agents` 在您之前未接受时显示相同的免责声明，接受将 `bypassPermissions` 应用于您从视图启动的会话。传递 `--allow-dangerously-skip-permissions` 也显示相同的免责声明，接受使 `bypassPermissions` 在这些会话的 `Shift+Tab` 循环中可用，而不在其中启动它们。

704 715

705<h4 id="what-persists-across-restarts">716<h4 id="what-persists-across-restarts">

706 重新启动时持续什么717 跨重新启动持续的内容

707</h4>718</h4>

708 719

709你为后台会话选择的权限模式、模型和工作量，以及 [configuration flags it carries](#what-carries-over-when-you-background)，在监督者稍后 [stops and restarts](#the-supervisor-process) 其进程时都会持续。你用 `claude --bg --dangerously-skip-permissions` 或 `claude --bg --permission-mode bypassPermissions` 启动的会话在该重新启动后仍保持 `bypassPermissions`。你在会话中期用 `/model` 或 `/effort` 更改的模型或工作量也被保留。720您为后台会话选择的权限模式、模型和努力，以及 [它继承的配置标志](#what-carries-over-when-you-background)，在主管稍后 [停止并重新启动](#the-supervisor-process) 其进程时都持续。您使用 `claude --bg --dangerously-skip-permissions` 或 `claude --bg --permission-mode bypassPermissions` 启动的会话在该重新启动后保留在 `bypassPermissions` 中。您在会话中期使用 `/model` 或 `/effort` 更改的模型或努力也保留。

710 721

711如果会话从你的设置而不是从 `--effort` 或 `/effort` 获取工作量，Claude Code 每次为会话启动进程时都会再次读取你的设置。所以当你在 `settings.json` 中编辑保存的工作量时，更改到达你用 `←` 或 `/bg` 后台化的会话及其后续重新启动。保存的工作量是 [`effortLevel`](/docs/zh-CN/settings-reference#effortlevel) 键或 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 条目。722如果会话从您的设置而不是从 `--effort` 或 `/effort` 获取其努力，Claude Code 每次为会话启动进程时都会再次读取您的设置。在您编辑 `settings.json` 中保存的努力后，更改到达您使用 `←` 或 `/bg` 后台处理的会话，及其稍后的重新启动。保存的努力是 [`effortLevel`](/docs/zh-CN/settings-reference#effortlevel) 键或 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 条目。

712 723

713Claude Code 也保留你用 [`/rename`](/docs/zh-CN/commands) 或 `Ctrl+R` 设置的名称在该重新启动中，所以你仍然可以运行 [`claude --resume <name>`](/docs/zh-CN/sessions#name-your-sessions) 以到达会话。724Claude Code 也保留您使用 [`/rename`](/docs/zh-CN/commands) 或 `Ctrl+R` 设置的名称跨该重新启动，因此您仍然可以运行 [`claude --resume <name>`](/docs/zh-CN/sessions#name-your-sessions) 到达会话。

714 725

715你在附加时用 [`Ctrl+S`](/docs/zh-CN/interactive-mode#general-controls) 隐藏的提示也与会话一起保留。在其进程被停止或重新启动后重新打开会话，`Ctrl+S` 恢复隐藏的文本。隐藏中的粘贴内容不会在重新启动中存活。726您使用 [`Ctrl+S`](/docs/zh-CN/interactive-mode#general-controls) 在附加时隐藏的提示与会话一起保留。在其进程停止或重新启动后重新打开会话，`Ctrl+S` 恢复隐藏的文本。隐藏内容中的粘贴内容不会在重新启动中存活。

716 727

717<h3 id="settings-plugins-and-mcp-servers">728<h3 id="settings-plugins-and-mcp-servers">

718 Settings、plugins 和 MCP servers729 设置、plugins 和 MCP 服务器

719</h3>730</h3>

720 731

721Agent view 接受与 `claude` 相同的配置标志以加载 settings、plugins、MCP servers 和额外目录。Agent view 将 `--settings` 和 `--plugin-dir` 应用于自己，并将每个配置标志传递给你从它调度的会话，所以以这种方式加载的 plugin 或 MCP server 在这些会话中也可用。732Agent 视图接受与 `claude` 相同的配置标志以加载设置、plugins、MCP 服务器和其他目录。Agent 视图将 `--settings`、`--setting-sources` 和 `--plugin-dir` 应用于自己，并将每个配置标志传递给您从它分派的会话，因此您以这种方式加载的 plugin 或 MCP 服务器在这些会话中可用。

722 733

723| 标志 | 效果 |734| 标志 | 效果 |

724| :- | :- |735| :- | :- |

738| [`--add-dir <path>`](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) | 授予对其他目录的文件访问权限 |

729| `--strict-mcp-config` | 仅使用来自 `--mcp-config` 的 MCP servers，忽略其他 MCP 配置。参见 [Exclusive control with managed-mcp.json](/docs/zh-CN/managed-mcp#exclusive-control-with-managed-mcp-json) 了解该标志在托管 MCP 文件下做什么 |741| `--strict-mcp-config` | 仅使用来自 `--mcp-config` 的 MCP 服务器，忽略其他 MCP 配置。请参阅 [Exclusive control with managed-mcp.json](/docs/zh-CN/managed-mcp#exclusive-control-with-managed-mcp-json) 了解标志在托管 MCP 文件下的作用 |

730 742

731对每个值重复 `--add-dir`、`--plugin-dir` 或 `--mcp-config`。`claude agents` 不支持空格分隔的形式，例如 `--add-dir a b c`。743每个值重复 `--add-dir`、`--plugin-dir` 或 `--mcp-config` 一次。`claude agents` 不支持空格分隔的形式，例如 `--add-dir a b c`。

732 744

733你可以将 `--settings` 和 `--plugin-dir` 放在 `agents` 之前或之后。将 `--add-dir` 和 `--mcp-config` 放在 `agents` 之后：如果你将其中任何一个放在 `agents` 之前，[`claude agents --json`](#manage-sessions-from-the-shell) 失败并显示 `unknown option` 错误。745您可以在 `agents` 前或后放置 `--settings`、`--setting-sources` 和 `--plugin-dir`。将 `--add-dir` 和 `--mcp-config` 保留在 `agents` 后：如果您在 `agents` 前放置任何一个，[`claude agents --json`](#manage-sessions-from-the-shell) 失败，出现 `unknown option` 错误。

734 746

735以下示例使用 settings 覆盖和一个额外目录打开 agent view：747以下示例使用设置覆盖和一个额外目录打开 agent 视图：

736 748

737```bash theme={null}749```bash theme={null}

738claude agents --settings ./ci-settings.json --add-dir ../shared-lib750claude agents --settings ./ci-settings.json --add-dir ../shared-lib

1048 1060

1049| 版本 | 更改 |1061| 版本 | 更改 |

1050| - | - |1062| - | - |

1063| v2.1.281 | [`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 限制[转移](#what-carries-over-when-you-background)到你使用 `←` 或 `/bg` 后台的会话，以及你从 agent view 调度的会话。在此版本之前，生成的会话加载每个设置源。 |

1064| v2.1.281 | `claude --bg` 和重启会话的命令首先检查会话目录的工作区信任。从该目录中的终端，如果你尚未接受，[信任对话框出现](#from-your-shell)；在无法出现对话框的地方，例如在脚本中，命令以 [`Workspace not trusted`](/docs/zh-CN/errors#workspace-not-trusted-when-dispatching-a-background-session) 错误退出。 |

1065| v2.1.274 | 自动更新后，你离开约一小时的 agent view 可以将自己重新启动到新的构建上。当它这样做时，它保留你打开它时的[调度默认值](#dispatch-defaults)：`--model`、`--effort`、`--permission-mode`、`--allow-dangerously-skip-permissions` 和 `--agent`。在此版本之前，重新启动的 view 仅保留 `--cwd` 和配置标志，例如 `--settings` 和 `--mcp-config`，所以你之后调度的会话启动时没有这些默认值。 |

1066| v2.1.274 | 当[删除被拒绝](#what-deleting-a-session-removes)因为 git 或你的 `WorktreeRemove` hook 无法删除 worktree 时，Claude Code 验证的已检出子模块没有对跟踪文件的未提交更改不会阻止再次删除的提议，并删除目录。已检出子模块内的未提交工作计为未提交更改，消息会命名子模块。在此版本之前，worktree 中的任何子模块检出都会阻止提议，消息说 worktree 包含嵌套存储库。 |

1051| v2.1.268 | 当[删除被拒绝](#what-deleting-a-session-removes)因为 git 或你的 `WorktreeRemove` hook 无法删除 worktree 时，消息会说明原因，包括 hook 如何结束以及其 stderr 的开始。对于位于存储库的 `.claude/worktrees/` 下的链接 worktree，没有对跟踪文件的未提交更改，其中没有嵌套存储库，也没有其他会话的记录命名它，再次删除会话会从 agent view 或使用 `claude rm <id> --force-remove-worktree <worktree-id>` 删除目录。在此版本之前，该行仅显示 `worktree could not be removed (WorktreeRemove hook failed)` 或 git 的错误，hook 的 stderr 仅进入调试日志，再次删除被以相同方式拒绝。 |1067| v2.1.268 | 当[删除被拒绝](#what-deleting-a-session-removes)因为 git 或你的 `WorktreeRemove` hook 无法删除 worktree 时，消息会说明原因，包括 hook 如何结束以及其 stderr 的开始。对于位于存储库的 `.claude/worktrees/` 下的链接 worktree，没有对跟踪文件的未提交更改，其中没有嵌套存储库，也没有其他会话的记录命名它，再次删除会话会从 agent view 或使用 `claude rm <id> --force-remove-worktree <worktree-id>` 删除目录。在此版本之前，该行仅显示 `worktree could not be removed (WorktreeRemove hook failed)` 或 git 的错误，hook 的 stderr 仅进入调试日志，再次删除被以相同方式拒绝。 |

1052| v2.1.268 | 在第一个 `←` 显示 `Press ← again to open agents` 或在附加的会话中 `Press ← again to go back to agents` 后，[至少一秒后到达的第一次按压会切换](#switch-sessions-without-leaving-the-terminal)，即使中间更快的按压被忽略。在此版本之前，每次被忽略的按压都会重新启动等待，所以以稳定的速度再次按 `←` 直到你暂停超过一秒才会切换。 |1068| v2.1.268 | 在第一个 `←` 显示 `Press ← again to open agents` 或在附加的会话中 `Press ← again to go back to agents` 后，[至少一秒后到达的第一次按压会切换](#switch-sessions-without-leaving-the-terminal)，即使中间更快的按压被忽略。在此版本之前，每次被忽略的按压都会重新启动等待，所以以稳定的速度再次按 `←` 直到你暂停超过一秒才会切换。 |

1053| v2.1.260 | 当你[后台会话](#from-inside-a-session)时，你的其他会话的[代理列表](/docs/zh-CN/cross-session-messaging#see-which-sessions-claude-can-reach)显示对话一次，作为其后台会话，它们对它的消息不再到达你移动它的终端。在此版本之前，该终端可能在 `claude agents --json` 中显示为对话名称下的第二个交互式会话，在移动前已向对话发送消息的会话继续传递到该终端。 |1069| v2.1.260 | 当你[后台会话](#from-inside-a-session)时，你的其他会话的[代理列表](/docs/zh-CN/cross-session-messaging#see-which-sessions-claude-can-reach)显示对话一次，作为其后台会话，它们对它的消息不再到达你移动它的终端。在此版本之前，该终端可能在 `claude agents --json` 中显示为对话名称下的第二个交互式会话，在移动前已向对话发送消息的会话继续传递到该终端。 |

agents.md +1 −1

Details

16| [项目](/docs/zh-CN/claude-projects) | 在 claude.ai/code 或桌面应用中进行的一个持续对话。Claude 启动称为线程的并行云会话，为每个会话提供项目的存储库、说明和内存，并向您显示哪些需要您。Pro 和 Max 上的公开测试版 | 工作跨越多个任务，持续数天或数周，应在您的机器关闭时继续运行，并且您宁愿描述一次而不是分派和跟踪每个会话 |16| [项目](/docs/zh-CN/claude-projects) | 在 claude.ai/code 或桌面应用中进行的一个持续对话。Claude 启动称为线程的并行会话，在云中或当您要求时通过远程控制在您的计算机上运行，为每个会话提供项目的说明，并向您显示哪些需要您。Pro 和 Max 上的公开测试版 | 工作跨越多个任务，持续数天或数周，应在您的机器关闭时继续运行，并且您宁愿描述一次而不是分派和跟踪每个会话 |

18 18

19在每种方法中，工作人员都是 Claude 会话。要涉及不同的工具，请将其作为 [MCP server](/docs/zh-CN/mcp) 公开给 Claude。19在每种方法中，工作人员都是 Claude 会话。要涉及不同的工具，请将其作为 [MCP server](/docs/zh-CN/mcp) 公开给 Claude。

artifacts.md +44 −17

Details

41 创建工件41 创建工件

42</h2>42</h2>

43 43

44Claude 可能会在输出适合作为页面时自动发布工件，或者你可以直接请求创建一个。要请求创建，请命名该功能或用简洁的语言描述你想要的视觉输出。任何比以文本形式阅读更容易看到的内容都是很好的候选，例如带注释的 diff、图表或一组选项进行比较。下面的提示是两个示例；有关更多模式，请参阅[你可以构建的内容](#what-you-can-build)。44Claude 可能会在输出适合作为页面时自动发布工件，或者你可以直接请求创建一个。要请求创建，请用简洁的语言命名该功能或描述你想要的视觉输出。任何比以文本形式阅读更容易看到的内容都是很好的候选，例如带有内联注释的 diff、图表或一组选项的比较。下面的提示是两个示例；有关更多模式，请参阅[你可以构建的内容](#what-you-can-build)。

45 45

46```text wrap theme={null}46```text wrap theme={null}

47Make an artifact that walks through this PR with the diff annotated inline.47Make an artifact that walks through this PR with the diff annotated inline.

51Build a dashboard artifact of last week's deploy failures by service and keep it updated as you investigate.51Build a dashboard artifact of last week's deploy failures by service and keep it updated as you investigate.

52```52```

53 53

54除非你指定位置，否则 Claude 会将页面写入项目外的临时目录中的 HTML 或 Markdown 文件，然后发布它。发布新工件会通过你的会话的[权限模式](/docs/zh-CN/permission-modes)进行：54除非你指定位置，否则 Claude 会将页面写入项目外的临时目录中的 HTML 或 Markdown 文件，然后发布它。在[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)之外，Claude 发布的响应你输入的提示的新工件会直接通过，无需权限提示或分类器审查，除非该发布声明了页面的运行时功能，例如[连接器调用](#pull-live-data-with-mcp-connectors)或[文件下载](#offer-a-file-download)。在计划模式下，Claude Code 会在每个工件的首次发布前询问你。

55 55

56* **自动模式**：分类器审查发布而不是提示你，因此 Claude 可以在你看不到提示的情况下发布页面。你的会话启动时所处的模式取决于你的计划；请参阅[起始权限模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)。56工件对你保持私密，直到你[共享它](#share-an-artifact)。在你公开共享后，Claude Code 会在每次对话中要求你的批准一次后再更改它，或在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)下让分类器审查更改。

57* **手动和接受编辑模式**：Claude Code 会请求权限；它可能会说类似 `Claude wants to publish deploy-failures.html, uploading it to claude.ai (Anthropic's servers) to host as the page "Deploy failures by service", private to you until you share it` 的内容。选择**是**以发布。

58 57

~~59在你批准工件一次后，Claude Code 会重新发布它而不再询问，并在某些情况下再次询问，包括：~~58如果你关闭了[功能标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)，Claude Code 会在每个工件的首次发布前询问，或在自动模式下让分类器审查它。

60 59

~~61* Claude 为页面声明运行时功能，例如[连接器调用](#pull-live-data-with-mcp-connectors)或[文件下载](#offer-a-file-download)~~60首次发布后，Claude 会打印 URL，你的浏览器会打开到新页面。如果你通过[远程控制](/docs/zh-CN/remote-control)从 claude.ai、Claude Desktop 或 Claude 移动应用发送提示，运行会话的机器上不会打开标签页。下次 Claude 从你在终端输入的提示发布工件时，浏览器会在那里打开。随时按 `Ctrl+]` 可以重新打开会话的最近工件。

~~62* 你之后[公开共享了它](#share-an-artifact)~~

~~63* 你之后与特定人员或你的组织共享了它，最新版本被选为查看者看到的版本~~

64 61

65在首次发布后，Claude 会打印 URL，你的浏览器会打开到新页面。如果你从 claude.ai、Claude Desktop 或 Claude 移动应用通过[远程控制](/docs/zh-CN/remote-control)发送了提示，运行会话的机器上不会打开任何标签页。下次你在终端输入提示时 Claude 从该提示发布工件时，浏览器会在那里打开。随时按 `Ctrl+]` 可重新打开会话的最近工件。62Claude 会选择工件的标题和一个表情符号，两者都会出现在你在 claude.ai 上的[工件库](#share-an-artifact)和共享链接中。Claude 还可以选择与页面内容相匹配的浏览器标签页图标，例如图表或日历。如果你想要特定的标题、表情符号或标签页图标，请告诉 Claude。

66 63

67Claude 为工件的标题和浏览器标签图标选择一个表情符号。两者都会出现在你在 claude.ai 上的[工件库](#share-an-artifact)和共享链接中，因此如果你想要特定的标题或图标，请要求 Claude 使用它。64要停止在发布新工件时自动打开浏览器，请在你的环境中设置 `CLAUDE_CODE_ARTIFACT_AUTO_OPEN=0`。

68 65

~~69要停止浏览器在发布新工件时自动打开，请在你的环境中设置 `CLAUDE_CODE_ARTIFACT_AUTO_OPEN=0`。~~66如果 Claude 回复说无法发布，或写入本地 HTML 文件而没有链接，则该工具未为你的会话启用。检查[可用性](#availability)要求。

~~71如果 Claude 回应说它无法发布，或写入本地 HTML 文件而没有链接，则该工具未为你的会话启用。检查[可用性](#availability)要求。~~

72 67

73<h2 id="update-an-artifact">68<h2 id="update-an-artifact">

74 更新一个 artifact69 更新一个 artifact

305 300

306对于排版，Claude 可以从 Google Fonts 加载字体，这是工件页面可以加载的唯一外部字体源。Claude 将任何其他字体内联为 `@font-face` 数据 URI，并为每个字体提供后备堆栈，因此即使字体未加载，页面仍会呈现。要使用特定字体，请在提示或设计系统中命名它。301对于排版，Claude 可以从 Google Fonts 加载字体，这是工件页面可以加载的唯一外部字体源。Claude 将任何其他字体内联为 `@font-face` 数据 URI，并为每个字体提供后备堆栈，因此即使字体未加载，页面仍会呈现。要使用特定字体，请在提示或设计系统中命名它。

307 302

308<h2 id="draft-a-design-canvas">303<h2 id="start-from-a-slides-design-or-docs-template">

309 草拟设计画布304 从幻灯片、设计或文档模板开始

310</h2>305</h2>

311 306

312要模拟 UI、屏幕流、登陆页面或海报，而不是构建页面，请运行 `/design` 并提供简要说明。Claude 将设计作为一个画布上的画板草拟，并将画布发布为一个设计工件。简要说明命名您想要绘制的内容：307Claude 可以从您的 claude.ai 账户上的模板开始创建工件，而不是从头开始构建页面：[Claude Slides](https://support.claude.com/en/articles/17153992-what-are-artifacts-and-how-do-i-use-them#h_11d5a9a5fa) 用于演示文稿，[Claude Design](https://support.claude.com/en/articles/14604416-get-started-with-claude-design) 用于视觉设计，或 [Claude Docs](https://support.claude.com/en/articles/16923645-get-started-with-claude-docs) 用于其他人将阅读和编辑的文档。每个都在 claude.ai 上的自己的编辑器中打开，您和您的团队成员可以直接更改它或要求 Claude 更改，并将其导出为 PowerPoint、PDF 或 Word 等格式。

308

309要从模板开始，请描述您想要的内容，例如"将迁移说明转换为周四审查的演示文稿"或"将此计划作为文档写给团队"。Claude 选择匹配的模板，从您的请求和会话已有的内容填充它，并给您链接。对于演示文稿或设计，您也可以运行 `/slides` 或 `/design` 并提供简要说明。

310

311<Note>

312 模板处于测试阶段。它们在 Pro、Max 和 Team 计划上默认启用。在 Enterprise 计划上，所有者在**组织设置 > 工件**下[启用每个模板](https://support.claude.com/en/articles/16994751-artifacts-admin-guide-for-team-and-enterprise-plans)。如果您的组织关闭了 Slides 模板，`/slides` 不会出现；如果关闭了 Design 模板，`/design` 不会草拟设计。两个命令都需要 Claude Code v2.1.265 或更高版本以及一个[工件可用](#availability)的会话。

313</Note>

314

315<h3 id="make-a-slide-deck">

316 制作幻灯片演示文稿

317</h3>

318

319运行 `/slides` 并提供简要说明，说明演示文稿涵盖的内容以及针对的对象：

320

321```text wrap theme={null}

322/slides a quarterly review of the platform team's reliability work, for the engineering all-hands

323```

324

325Claude 创建一个 Claude Slides 工件并给您链接。在桌面浏览器中打开它以编辑或演示演示文稿。如果您运行 `/slides` 而不提供简要说明，Claude 会在创建任何内容之前询问演示文稿应该是关于什么的。

326

327<h3 id="draft-a-design-canvas">

328 草拟设计画布

329</h3>

330

331要模拟 UI、屏幕流、登陆页面或海报，而不是构建页面，请运行 `/design` 并提供简要说明。Claude 将设计作为一个画布上的画板草拟，并将画布发布为一个 Claude Design 工件。简要说明命名您想要绘制的内容：

313 332

314```text wrap theme={null}333```text wrap theme={null}

315/design a settings screen for a mobile banking app334/design a settings screen for a mobile banking app

317 336

318在桌面浏览器中打开已发布的工件以查看画板。在画板上选择一个元素并更改它，您的编辑会自动保存。您可以将每个画板导出为 PNG 或 PDF。337在桌面浏览器中打开已发布的工件以查看画板。在画板上选择一个元素并更改它，您的编辑会自动保存。您可以将每个画板导出为 PNG 或 PDF。

319 338

320`/design` 需要一个会话，其中 [artifacts 可用](#availability)，且 Claude Code v2.1.265 或更高版本。339<h3 id="write-a-document-with-claude-docs">

340 使用 Claude Docs 编写文档

341</h3>

342

343Claude Docs 作为 claude.ai [连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)而不是命令到达 Claude Code。连接后，`/mcp` 将其列为 `claude.ai Claude Docs`。针对供其他人使用的文档的请求随后转到 Claude Docs 而不是工件页面：规范、提案或您在会话中完成的计划的写入。Claude 在草拟文档时给您文档的链接。

344

345属于代码库的文档（例如 README）保持为文件。要为 Claude 否则会放在 Claude Docs 中的内容获取文件，请命名格式，例如 `.docx` 或存储库中的 Markdown 文件。

346

347要关闭连接器，请将 `claude.ai Claude Docs` 添加到 `deniedMcpServers` 或使用 `/mcp` 切换，两者都在[禁用 claude.ai 连接器](/docs/zh-CN/mcp#disable-claude-ai-connectors)中描述。

321 348

322<h2 id="page-constraints">349<h2 id="page-constraints">

323 页面约束350 页面约束

authentication.md +47 −21

Details

32 32

33要登出并重新身份验证，请在 Claude Code 提示符处输入 `/logout`。登出还会重置您的首次启动设置状态，因此下次运行 `claude` 时，它会再次引导您完成登录和设置。33要登出并重新身份验证，请在 Claude Code 提示符处输入 `/logout`。登出还会重置您的首次启动设置状态，因此下次运行 `claude` 时，它会再次引导您完成登录和设置。

34 34

35要同时保持登录多个账户（例如工作和个人账户），请为每个账户提供自己的配置目录。启动 `claude` 时，将 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars#variables) 环境变量设置为您要使用的账户的目录。每个目录都有自己的设置、会话历史记录和 claude.ai 登录或 API 密钥。例如，在 Bash 或 Zsh 中，将此别名添加到 `~/.bashrc` 或 `~/.zshrc`，以便 `claude-work` 使用您的工作账户，而 `claude` 保持您的个人账户：

37```bash theme={null}

38alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

39```

41首次打开新终端并运行 `claude-work` 后，Claude Code 会引导您完成新目录的登录和设置。单独的目录不会将两个 Claude Console 登录 [不带 API 密钥](#sign-in-without-an-api-key) 分开，因为 Claude Code 将这种类型的登录存储在配置目录之外。

35如果您在登录时遇到问题，请参阅 [身份验证故障排除](/docs/zh-CN/troubleshoot-install#login-and-authentication)。43如果您在登录时遇到问题，请参阅 [身份验证故障排除](/docs/zh-CN/troubleshoot-install#login-and-authentication)。

36 44

37<h2 id="set-up-team-authentication">45<h2 id="set-up-team-authentication">

122* 任何设置文件设置 [`forceLoginOrgUUID`](#restrict-login-to-your-organization)，或将 `forceLoginMethod` 设置为 `"claudeai"` 或 `"console"`130* 任何设置文件设置 [`forceLoginOrgUUID`](#restrict-login-to-your-organization)，或将 `forceLoginMethod` 设置为 `"claudeai"` 或 `"console"`

123* 您机器上存在托管设置源（例如托管设置文件、MDM 配置文件或缓存的服务器托管设置），但 Claude Code [无法读取它](/docs/zh-CN/managed-settings#invalid-entries-in-managed-settings)，且没有其他托管源提供策略131* 您机器上存在托管设置源（例如托管设置文件、MDM 配置文件或缓存的服务器托管设置），但 Claude Code [无法读取它](/docs/zh-CN/managed-settings#invalid-entries-in-managed-settings)，且没有其他托管源提供策略

124 132

125在无密钥登录之前取消设置 `ANTHROPIC_API_KEY`。由 Claude Code 自己的 Console 登录或由 Claude Platform CLI 的 `ant auth login` 编写的配置文件是相同类型的凭证，因此再次登录会替换它。133在无密钥登录之前取消设置 `ANTHROPIC_API_KEY`。

126 134

127无密钥登录后，您拥有配置文件而不是存储的 API 密钥：135无密钥登录后，您拥有配置文件而不是存储的 API 密钥：

128 136

160 168

161要求开发人员的 claude.ai 登录属于特定的 Anthropic 组织，请在 [托管设置](/docs/zh-CN/managed-settings) 中设置 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 和 [`forceLoginOrgUUID`](/docs/zh-CN/settings-reference#forceloginorguuid)。将 `forceLoginOrgUUID` 设置为您的组织 ID，该 ID 显示在 [claude.ai 管理员设置](https://claude.ai/admin-settings/organization) 中，适用于 Claude for Teams 或 Enterprise 组织。Claude Code 会为任何其他组织的 claude.ai 登录报告错误，如果使用中的 claude.ai 凭证属于未列出的组织，则在启动时退出。169要求开发人员的 claude.ai 登录属于特定的 Anthropic 组织，请在 [托管设置](/docs/zh-CN/managed-settings) 中设置 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 和 [`forceLoginOrgUUID`](/docs/zh-CN/settings-reference#forceloginorguuid)。将 `forceLoginOrgUUID` 设置为您的组织 ID，该 ID 显示在 [claude.ai 管理员设置](https://claude.ai/admin-settings/organization) 中，适用于 Claude for Teams 或 Enterprise 组织。Claude Code 会为任何其他组织的 claude.ai 登录报告错误，如果使用中的 claude.ai 凭证属于未列出的组织，则在启动时退出。

162 170

163对于 Claude Console 登录，当您将其设置为单个 Console 组织 ID（显示在 [platform.claude.com/settings/organization](https://platform.claude.com/settings/organization)）时，Claude Code 使用 `forceLoginOrgUUID` 在 Console 登录页面上预选组织。它不检查生成的 Console 凭证属于哪个组织，无论是在登录时还是在启动时，在您部署密钥之前使用 Console 账户登录的开发人员会保持登录状态。171对于 Claude Console 登录，当您将其设置为单个 Console 组织 ID（显示在 [platform.claude.com/settings/organization](https://platform.claude.com/settings/organization)）时，Claude Code 使用 `forceLoginOrgUUID` 在 Console 登录页面上预选组织。它不检查生成的 Console 凭证属于哪个组织，无论是在登录时还是在启动时。在您部署密钥之前使用 Console 账户登录的开发人员会保持登录状态，该保存的密钥在同时需要 [网关](/docs/zh-CN/claude-apps-gateway) 登录的机器上被阻止，或在选择云提供商的会话中被阻止。

164 172

165如果您在任何设置文件中设置 `forceLoginOrgUUID`，Claude Code 会停止在该文件适用的会话中提供 [无密钥 Console 登录](#sign-in-without-an-api-key)，而是创建 API 密钥。要将开发人员定向到 claude.ai 登录，请将 `forceLoginMethod` 设置为 `"claudeai"`。173如果您在任何设置文件中设置 `forceLoginOrgUUID`，Claude Code 会停止在该文件适用的会话中提供 [无密钥 Console 登录](#sign-in-without-an-api-key)，而是创建 API 密钥。要将开发人员定向到 claude.ai 登录，请将 `forceLoginMethod` 设置为 `"claudeai"`。

166 174

167开发人员可以从多个路径登录：终端 `/login` 流程、[VS Code 扩展](/docs/zh-CN/vs-code)、Agent SDK、`claude setup-token`、`/install-github-app` 和 [网关](/docs/zh-CN/claude-apps-gateway) 登录，适用于通过云网关路由的组织。在 Claude Code v2.1.212 或更高版本上，每个路径都应用 `forceLoginMethod`；在 v2.1.212 之前，只有终端登录应用任一密钥。在终端的交互式登录屏幕上，通过 `/login` 或首次运行入门到达，Claude Code 预选 `claudeai` 或 `console` 方法而不强制执行，因此即使设置了 `forceLoginMethod` 为 `"claudeai"`，开发人员仍然可以在那里完成 Console 登录。这些路径在 `forceLoginOrgUUID` 上有所不同：175在 Claude Code v2.1.212 或更高版本上，此处列出的每个登录路径都应用 `forceLoginMethod`。在终端的交互式登录屏幕上，通过 `/login` 或首次运行入门到达，Claude Code 预选 `claudeai` 或 `console` 方法而不强制执行，因此即使设置了 `forceLoginMethod` 为 `"claudeai"`，开发人员仍然可以在那里完成 Console 登录。

168 176

169* **终端、VS Code 扩展和 Agent SDK 登录**：验证 claude.ai 账户登录的 `forceLoginOrgUUID`177这些路径在 `forceLoginOrgUUID` 上有所不同：

178

179* **终端、[VS Code 扩展](/docs/zh-CN/vs-code) 和 Agent SDK 登录**：验证 claude.ai 账户登录的 `forceLoginOrgUUID`

170* **`claude setup-token` 和 `/install-github-app`**：仅强制执行 `forceLoginMethod`，因此它们可以在不同的组织中铸造令牌180* **`claude setup-token` 和 `/install-github-app`**：仅强制执行 `forceLoginMethod`，因此它们可以在不同的组织中铸造令牌

171* **[网关](/docs/zh-CN/claude-apps-gateway) 登录**：由 `forceLoginMethod: "gateway"` 选择而不是受其限制，并且不针对 Anthropic 组织进行身份验证，因此 `forceLoginOrgUUID` 不适用；使用您的网关身份提供商来限制访问181* **[网关](/docs/zh-CN/claude-apps-gateway) 登录**：由 `forceLoginMethod: "gateway"` 选择而不是受其限制，并且不针对 Anthropic 组织进行身份验证，因此 `forceLoginOrgUUID` 不适用；使用您的网关身份提供商来限制访问

172 182

173通过您的设备管理工具部署密钥。[服务器托管设置](/docs/zh-CN/server-managed-settings) 仅到达已经通过您的组织身份验证的账户，因此它们无法重定向开发人员的首次登录。如果您的组织也分发服务器托管设置，请在两个地方设置密钥：托管设置源 [不合并](/docs/zh-CN/server-managed-settings#settings-precedence)，缓存的服务器托管设置替换设备托管文件，除了几个 [按密钥例外](/docs/zh-CN/server-managed-settings#per-key-exceptions-across-managed-sources)。`forceLoginOrgUUID` 和 `forceLoginMethod` 的 `"claudeai"` 和 `"console"` 值不在这些例外中，因此在两个地方都保留它们。183通过您的设备管理工具部署密钥。[服务器托管设置](/docs/zh-CN/server-managed-settings) 仅到达已经通过您的组织身份验证的账户，因此它们无法重定向开发人员的首次登录。如果您的组织也分发服务器托管设置，请在两个地方设置密钥：托管设置源 [不合并](/docs/zh-CN/server-managed-settings#settings-precedence)，缓存的服务器托管设置替换设备托管文件，除了几个 [按密钥例外](/docs/zh-CN/server-managed-settings#per-key-exceptions-across-managed-sources)。`forceLoginOrgUUID` 和 `forceLoginMethod` 的 `"claudeai"` 和 `"console"` 值不在这些例外中，因此在两个地方都保留它们。

174 184

185在 [网关](/docs/zh-CN/claude-apps-gateway) 部署中，也要将 `forceLoginMethod` 和 `forceLoginOrgUUID` 保留在 [网关提供的设置](/docs/zh-CN/claude-apps-gateway-config#managed) 之外。

186

175这些密钥还决定不使用登录凭证的会话是否可以启动。有关完整行为，请参阅设置参考中的 [`forceLoginOrgUUID`](/docs/zh-CN/settings-reference#forceloginorguuid)。187这些密钥还决定不使用登录凭证的会话是否可以启动。有关完整行为，请参阅设置参考中的 [`forceLoginOrgUUID`](/docs/zh-CN/settings-reference#forceloginorguuid)。

176 188

177* **`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper`**：在启动时被阻止，因为无法验证环境凭证的组织成员身份189* **`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper`**：在启动时被阻止。在 `forceLoginOrgUUID` 下，无法验证环境凭证的组织成员身份，在 `forceLoginMethod` 下，凭证会代替所需的登录。当托管设置也需要 [网关](/docs/zh-CN/claude-apps-gateway) 登录时，Claude Code 以相同方式阻止由早期 Claude Console 登录保存的 API 密钥。请参阅 [管理员策略需要云网关登录](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)

178* **云提供商会话，例如 Amazon Bedrock**：不被阻止，因为它们针对您的云提供商进行身份验证。通过您的云 IAM 策略限制这些190* **云提供商会话，例如 Amazon Bedrock**：仅在 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 凭证，或由早期 Claude Console 登录保存的 API 密钥仍然存在于机器上时被阻止。删除它，会话就会启动。这些会话针对您的云提供商进行身份验证，其访问策略管理它们

179* **[Anthropic 配置文件或联合凭证](#anthropic-profiles-and-federation-credentials)**：不被阻止，密钥不检查配置文件属于哪个组织191* **[Anthropic 配置文件或联合凭证](#anthropic-profiles-and-federation-credentials)**：不被阻止，除非 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 凭证，或由早期 Claude Console 登录保存的 API 密钥也存在于机器上。这些密钥不检查配置文件属于哪个组织

180 192

181<h2 id="credential-management">193<h2 id="credential-management">

182 凭证管理194 凭证管理

192 * Claude Code 通过 `/login` 和 `/logout` 管理 `.credentials.json`。要通过自定义 API 端点路由请求，请改为设置 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 环境变量。204 * Claude Code 通过 `/login` 和 `/logout` 管理 `.credentials.json`。要通过自定义 API 端点路由请求，请改为设置 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 环境变量。

193* **支持的身份验证类型**：claude.ai 凭证、Claude API 凭证、Microsoft Foundry Auth、Bedrock Auth、Vertex Auth、Anthropic 配置文件和 [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 凭证，以及 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话令牌。205* **支持的身份验证类型**：claude.ai 凭证、Claude API 凭证、Microsoft Foundry Auth、Bedrock Auth、Vertex Auth、Anthropic 配置文件和 [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 凭证，以及 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话令牌。

194* **自定义凭证脚本**：配置 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 设置以运行返回 API 密钥的 shell 脚本。206* **自定义凭证脚本**：配置 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 设置以运行返回 API 密钥的 shell 脚本。

195* **刷新间隔**：Claude Code 默认在五分钟后重新运行 `apiKeyHelper`。设置 `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` 环境变量以获得自定义刷新间隔。有关 Claude Code 重新运行助手的其他情况，请参阅 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper)。207* **刷新间隔**：请参阅 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 了解 Claude Code 重新运行助手的情况。

196* **缓慢助手通知**：如果 `apiKeyHelper` 返回密钥需要超过 10 秒，Claude Code 会在提示栏中显示警告通知，显示经过的时间。如果您经常看到此通知，请检查您的凭证脚本是否可以优化。208* **缓慢助手通知**：如果 `apiKeyHelper` 返回密钥需要超过 10 秒，Claude Code 会在提示栏中显示警告通知，显示经过的时间。如果您经常看到此通知，请检查您的凭证脚本是否可以优化。

197* **助手失败**：当脚本以错误退出、超时或不输出任何内容时，请求在三次尝试内失败，显示 [`Your apiKeyHelper script is failing`](/docs/zh-CN/errors#your-apikeyhelper-script-is-failing)。在 v2.1.208 之前，助手失败显示为通用 401，经过大约十次无声重试。209* **助手失败**：当脚本以错误退出、超时或不输出任何内容时，请求在三次尝试内失败，显示 [`Your apiKeyHelper script is failing`](/docs/zh-CN/errors#your-apikeyhelper-script-is-failing)。

198 210

199`apiKeyHelper`、`ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN` 适用于 CLI 和包装它的表面，包括 VS Code 扩展、Agent SDK 和 GitHub Actions。Claude Desktop 和云会话不会调用 `apiKeyHelper` 或读取这些环境变量：它们使用 OAuth，除了运行[第三方推理配置](/docs/zh-CN/llm-gateway-connect#desktop-app)的桌面会话外，这些会话使用该配置的凭证进行身份验证。211`apiKeyHelper`、`ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN` 适用于 CLI 和包装它的表面，包括 VS Code 扩展、Agent SDK 和 GitHub Actions。Claude Desktop 和云会话不会调用 `apiKeyHelper` 或读取这些环境变量：它们使用 OAuth，除了运行[第三方推理配置](/docs/zh-CN/llm-gateway-connect#desktop-app)的桌面会话外，这些会话使用该配置的凭证进行身份验证。

200 212

202 续期即将过期的登录214 续期即将过期的登录

203</h3>215</h3>

204 216

205当您使用 `/login` 创建的登录在过期前三天内时，Claude Code 会在启动时显示警告：`Your login expires in 3 days · run /login to renew`。需要 Claude Code v2.1.203 或更高版本。在 v2.1.217 之前，警告在五天前出现。217当您使用 `/login` 创建的登录在过期前三天内时，Claude Code 会在启动时显示警告：`Your login expires in 3 days · run /login to renew`。

206 218

207运行 `/login` 以续期。该警告仅供参考，永远不会阻止请求：身份验证将继续工作，直到登录实际过期。登录生命周期本身不变；提前警告是 v2.1.203 添加的功能。219运行 `/login` 以续期。该警告仅供参考，永远不会阻止请求：身份验证将继续工作，直到登录实际过期。

208 220

209一旦存储的登录过期且无法刷新，每个模型请求都会失败，显示 [`Login expired · Please run /login`](/docs/zh-CN/errors#login-expired)，直到您再次登录。在 v2.1.206 之前，Claude Code 将过期的登录报告为模型错误。221一旦存储的登录过期且无法刷新，每个模型请求都会失败，显示 [`Login expired · Please run /login`](/docs/zh-CN/errors#login-expired)，直到您再次登录。

210 222

211您可以在请求失败之前检查此状态：[`/status`](/docs/zh-CN/commands) 显示 `Login` 行，读取 `Expired — log in again`，加上它为过期登录保存的组织和电子邮件。该行仅在保存的 claude.ai 或 Claude Console 登录是活跃凭证时出现。该行需要 Claude Code v2.1.210 或更高版本。223您可以在请求失败之前检查此状态：[`/status`](/docs/zh-CN/commands) 显示 `Login` 行，读取 `Expired — log in again`，加上它为过期登录保存的组织和电子邮件。该行仅在保存的 claude.ai 登录是活跃凭证时出现。该行需要 Claude Code v2.1.210 或更高版本。

212 224

213该警告仅在 claude.ai 或 Claude Console 登录是活跃凭证时出现，而不是在云提供商、`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 提供凭证时出现。225该警告仅在 claude.ai 登录是活跃凭证时出现，而不是在云提供商、`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 提供凭证时出现。

214 226

215对于运行无人值守的会话，提前续期最为重要。在 [agent view 中的后台会话](/docs/zh-CN/agent-view)或 [Remote Control](/docs/zh-CN/remote-control) 会话一旦凭证过期，就会停止进行，并且在您再次登录之前无法恢复。227对于运行无人值守的会话，提前续期最为重要。在 [agent view 中的后台会话](/docs/zh-CN/agent-view)或 [Remote Control](/docs/zh-CN/remote-control) 会话一旦凭证过期，就会停止进行，并且在您再次登录之前无法恢复。

216 228

230 242

231一个已签名的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话位于此列表之外：它是一个提供商选择，如 Amazon Bedrock 或 Google Cloud 的 Agent Platform，并且它优先于它们。当网关会话存在时，即使设置了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY`，CLI 也会使用网关令牌进行身份验证，上面的持有者令牌、API 密钥、`apiKeyHelper` 和配置文件等凭证源不会被使用。243一个已签名的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话位于此列表之外：它是一个提供商选择，如 Amazon Bedrock 或 Google Cloud 的 Agent Platform，并且它优先于它们。当网关会话存在时，即使设置了 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_VERTEX` 或 `CLAUDE_CODE_USE_FOUNDRY`，CLI 也会使用网关令牌进行身份验证，上面的持有者令牌、API 密钥、`apiKeyHelper` 和配置文件等凭证源不会被使用。

232 244

233如果您的机器的[托管设置](/docs/zh-CN/managed-settings)将 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 设置为 `"gateway"` 或设置 [`forceLoginGatewayUrl`](/docs/zh-CN/settings-reference#forcelogingatewayurl)，并且您没有通过 `CLAUDE_CODE_USE_BEDROCK` 或 `CLAUDE_CODE_USE_VERTEX` 等变量选择云提供商，您的会话仅使用网关登录。Claude Code 跳过其他凭证源并要求您使用 `/login` 登录。有关每个剩余凭证的情况，请参阅[管理员策略需要云网关登录](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。在 v2.1.261 之前，或在仅设置 `forceLoginGatewayUrl` 的机器上在 v2.1.265 之前，Claude Code 在这些机器上使用剩余的保存登录，直到您登录到网关。245如果您的机器的[托管设置](/docs/zh-CN/managed-settings)将 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 设置为 `"gateway"` 或设置 [`forceLoginGatewayUrl`](/docs/zh-CN/settings-reference#forcelogingatewayurl)，并且您没有通过 `CLAUDE_CODE_USE_BEDROCK` 或 `CLAUDE_CODE_USE_VERTEX` 等变量选择云提供商，您的会话仅使用网关登录。Claude Code 跳过其他凭证源并要求您使用 `/login` 登录。有关每个剩余凭证的情况，请参阅[管理员策略需要云网关登录](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。需要 Claude Code v2.1.261 或更高版本，或在仅设置 `forceLoginGatewayUrl` 的机器上需要 v2.1.265 或更高版本。

234 246

235如果您有活跃的 Claude 订阅，但环境中也设置了 `ANTHROPIC_API_KEY`，Claude Code 会在您批准后使用 API 密钥。如果密钥属于已禁用或过期的组织，这可能会导致身份验证失败。247如果您有活跃的 Claude 订阅，但环境中也设置了 `ANTHROPIC_API_KEY`，Claude Code 会在您批准后使用 API 密钥。如果密钥属于已禁用或过期的组织，这可能会导致身份验证失败。

236 248

254| 联合变量 | `ANTHROPIC_FEDERATION_RULE_ID` 和 `ANTHROPIC_ORGANIZATION_ID`，两者都设置 | 上方 |266| 联合变量 | `ANTHROPIC_FEDERATION_RULE_ID` 和 `ANTHROPIC_ORGANIZATION_ID`，两者都设置 | 上方 |

255| 活跃配置文件 | 您的配置目录中的 [`active_config` 文件](https://platform.claude.com/docs/en/manage-claude/wif-reference#active-profile)，或名为 `default` 的配置文件 | 当其身份验证模式为 `oidc_federation` 时上方；当其身份验证模式为 `user_oauth` 时在工作的 `/login` 凭证下方 |267| 活跃配置文件 | 您的配置目录中的 [`active_config` 文件](https://platform.claude.com/docs/en/manage-claude/wif-reference#active-profile)，或名为 `default` 的配置文件 | 当其身份验证模式为 `oidc_federation` 时上方；当其身份验证模式为 `user_oauth` 时在工作的 `/login` 凭证下方 |

256 268

257`user_oauth` 规则防止剩余的 `ant auth login` 配置文件将您的请求移出您使用 `/login` 登录的帐户。对于联合变量，Claude Code 还会在交换您的身份令牌时读取 [WIF 参考](https://platform.claude.com/docs/en/manage-claude/wif-reference#environment-variables)中的其他变量，例如 `ANTHROPIC_IDENTITY_TOKEN_FILE`。对于配置文件格式，请参阅 [WIF 参考](https://platform.claude.com/docs/en/manage-claude/wif-reference#profile-configuration-file)。269对于联合变量，Claude Code 还会在交换您的身份令牌时读取 [WIF 参考](https://platform.claude.com/docs/en/manage-claude/wif-reference#environment-variables)中的其他变量，例如 `ANTHROPIC_IDENTITY_TOKEN_FILE`。对于配置文件格式，请参阅 [WIF 参考](https://platform.claude.com/docs/en/manage-claude/wif-reference#profile-configuration-file)。

258 270

259要确认 Claude Code 选择了哪个源，请运行 `/status`。`Profile` 行用源名称代替 `Login method` 行。当配置文件是正在使用的凭证时，`Organization` 和 `Email` 行显示其帐户。271要确认 Claude Code 选择了哪个源，请运行 `/status`。`Profile` 行用源名称代替 `Login method` 行。当配置文件是正在使用的凭证时，`Organization` 和 `Email` 行显示其帐户。

260 272

261如果您使用 `--debug` 启动 Claude Code，它还会在 `~/.claude/debug/<session-id>.txt` 的调试日志中写入 `Using Anthropic profile auth` 行，其中包含源名称。当 Claude Code 因为您有工作的 `/login` 凭证而跳过 `user_oauth` 活跃配置文件时，它会向调试日志写入警告，说它改为使用 claude.ai 登录。

~~262~~

263当 `user_oauth` 配置文件的登录已过期且 Claude Code 无法续期时，请求会失败，显示 [Anthropic 配置文件登录已过期](/docs/zh-CN/errors#anthropic-profile-login-expired)。273当 `user_oauth` 配置文件的登录已过期且 Claude Code 无法续期时，请求会失败，显示 [Anthropic 配置文件登录已过期](/docs/zh-CN/errors#anthropic-profile-login-expired)。

264 274

265需要您的 claude.ai 登录的功能，例如 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)和 [`/schedule`](/docs/zh-CN/routines)，在选择这些源之一时不可用。要停止 Claude Code 选择源：275需要您的 claude.ai 登录的功能，例如 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)和 [`/schedule`](/docs/zh-CN/routines)，在选择这些源之一时不可用。要停止 Claude Code 选择源：

279 289

280该命令会打开与 `/login` 相同的浏览器授权流程，在您在浏览器中批准访问后，令牌会打印到终端。它不会将令牌保存在任何地方；复制它并将其设置为 `CLAUDE_CODE_OAUTH_TOKEN` 环境变量，无论您想在何处进行身份验证：290该命令会打开与 `/login` 相同的浏览器授权流程，在您在浏览器中批准访问后，令牌会打印到终端。它不会将令牌保存在任何地方；复制它并将其设置为 `CLAUDE_CODE_OAUTH_TOKEN` 环境变量，无论您想在何处进行身份验证：

281 291

282```bash theme={null}292<Tabs>

283export CLAUDE_CODE_OAUTH_TOKEN=your-token293 <Tab title="macOS, Linux, WSL">

284```294 ```bash theme={null}

295 export CLAUDE_CODE_OAUTH_TOKEN=your-token

296 ```

297 </Tab>

298

299 <Tab title="Windows PowerShell">

300 ```powershell theme={null}

301 $env:CLAUDE_CODE_OAUTH_TOKEN = "your-token"

302 ```

303 </Tab>

304

305 <Tab title="Windows CMD">

306 ```batch theme={null}

307 set CLAUDE_CODE_OAUTH_TOKEN=your-token

308 ```

309 </Tab>

310</Tabs>

285 311

286此令牌使用您的 Claude 订阅进行身份验证，需要 Pro、Max、Team 或 Enterprise 计划。它只能进行模型请求，因此无法建立 [Remote Control](/docs/zh-CN/remote-control) 会话或获取 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)。您在本地配置的 MCP 服务器仍然有效。312此令牌使用您的 Claude 订阅进行身份验证，需要 Pro、Max、Team 或 Enterprise 计划。它只能进行模型请求，因此无法建立 [Remote Control](/docs/zh-CN/remote-control) 会话或获取 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)。您在本地配置的 MCP 服务器仍然有效。

287 313

auto-mode-config.md +19 −35

Details

9[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)让 Claude Code 无需常规权限提示即可运行，通过将工具调用路由到一个分类器，该分类器会阻止任何不可逆、破坏性或针对您环境外的操作。拒绝和显式询问规则在分类器之前进行评估，仍然会阻止或提示。使用 `autoMode` 设置块告诉该分类器您的组织信任哪些代码库、存储桶和域，以便它停止阻止常规内部操作。9[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)让 Claude Code 无需常规权限提示即可运行，通过将工具调用路由到一个分类器，该分类器会阻止任何不可逆、破坏性或针对您环境外的操作。拒绝和显式询问规则在分类器之前进行评估，仍然会阻止或提示。使用 `autoMode` 设置块告诉该分类器您的组织信任哪些代码库、存储桶和域，以便它停止阻止常规内部操作。

10 10

11<Note>11<Note>

12 自动模式可供所有提供商上的所有用户使用，包括 Anthropic API、[AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws)、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的 [Claude 应用网关](/docs/zh-CN/claude-apps-gateway)会话。如果 Claude Code 报告您的账户无法使用自动模式，请检查[完整要求](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)，其中还涵盖了支持的模型和 Team 和 Enterprise 计划上的组织级控制。在 v2.1.158 到 v2.1.206 中，Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Claude 应用网关会话上的自动模式需要设置 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`；v2.1.207 移除了该要求。12 本页是配置参考。打开和关闭自动模式在权限模式页面上有介绍：

14 * **在会话中期切换到自动模式，或退出自动模式**：请参阅[切换权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)

15 * **在自动模式下启动会话**：请参阅[以不同的权限模式启动](/docs/zh-CN/permission-modes#start-in-a-different-mode)

13</Note>16</Note>

14 17

15默认情况下，分类器仅信任工作目录和当前代码库的已配置远程。推送到您公司的源代码控制组织或写入团队云存储桶等操作会被阻止，直到您将它们添加到 `autoMode.environment`。18自动模式可供所有提供商上的所有用户使用，包括 Anthropic API、[AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws)、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的 [Claude 应用网关](/docs/zh-CN/claude-apps-gateway)会话。如果 Claude Code 报告您的账户无法使用自动模式，请检查[完整要求](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)，其中还涵盖了支持的模型和 Team 和 Enterprise 计划上的组织级控制。

16 19

17有关会话如何进入自动模式以及分类器默认阻止的内容，请参阅[权限模式页面上的自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)。本页是配置参考。20默认情况下，分类器仅信任工作目录和当前代码库的已配置远程。推送到您公司的源代码控制组织或写入团队云存储桶等操作会被阻止，直到您将它们添加到 `autoMode.environment`。

18 21

19本页涵盖如何：22本页涵盖如何：

20 23

21* [为推送和拉取请求添加人工检查点](#add-a-human-checkpoint)，使用 `permissions.ask`24* [为推送和拉取请求添加人工检查点](#add-a-human-checkpoint)，使用 `permissions.ask`

~~22* [选择在何处设置规则](#where-the-classifier-reads-configuration)，跨越 CLAUDE.md、用户设置和托管设置~~

23* [定义受信任的基础设施](#define-trusted-infrastructure)，使用 `autoMode.environment`25* [定义受信任的基础设施](#define-trusted-infrastructure)，使用 `autoMode.environment`

24* [生成环境条目](#generate-environment-entries)，使用 `/auto-mode-setup`26* [生成环境条目](#generate-environment-entries)，使用 `/auto-mode-setup`

~~25* [覆盖阻止和允许规则](#override-the-block-and-allow-rules)，当默认值不适合您的管道时~~

~~26* [从 `/permissions` 编辑规则](#edit-rules-from-permissions)，无需打开设置文件~~

~~27* [将所有 shell 命令路由通过分类器](#route-all-shell-commands-through-the-classifier)，使用 `autoMode.classifyAllShell`~~

~~28* [检查您的有效配置](#inspect-the-defaults-and-your-effective-config)，使用 `claude auto-mode` 子命令~~

29* [查看拒绝](#review-denials)，以便您知道接下来要添加什么27* [查看拒绝](#review-denials)，以便您知道接下来要添加什么

30 28

31<h2 id="common-boundaries">29<h2 id="common-boundaries">

34 32

35自动模式允许推送到您正在处理的存储库的任何分支（包括默认分支），并默认创建拉取请求。标记为部署或发布目标的非默认分支（例如 `production`、`release` 或 `gh-pages`）不受该默认值的约束：分类器会根据其自身条件判断对该分支的推送，包括作为生产部署。推送的内容仍然会被检查，因此强制推送、提交中出现的密钥或在 CI 或部署管道运行时会将密钥发送到存储库外的更改仍然会被阻止。33自动模式允许推送到您正在处理的存储库的任何分支（包括默认分支），并默认创建拉取请求。标记为部署或发布目标的非默认分支（例如 `production`、`release` 或 `gh-pages`）不受该默认值的约束：分类器会根据其自身条件判断对该分支的推送，包括作为生产部署。推送的内容仍然会被检查，因此强制推送、提交中出现的密钥或在 CI 或部署管道运行时会将密钥发送到存储库外的更改仍然会被阻止。

36 34

~~37<Info>在 v2.1.211 之前，分类器仅允许推送到您的工作分支、Claude 创建的分支以及对默认分支的例行推送。</Info>~~

39如果您想在 Claude 的推送和拉取请求命令之前进行人工检查点，请添加权限规则：下面的[配方](#add-a-human-checkpoint)为其他所有操作保持自动模式开启。35如果您想在 Claude 的推送和拉取请求命令之前进行人工检查点，请添加权限规则：下面的[配方](#add-a-human-checkpoint)为其他所有操作保持自动模式开启。

40 36

41<h3 id="add-a-human-checkpoint">37<h3 id="add-a-human-checkpoint">

81 77

82分类器不从 `.claude/settings.json` 或 `.claude/settings.local.json` 中的项目设置读取 `autoMode`。两个文件都位于仓库目录中，因此已检入的仓库或构建步骤可能会注入自己的允许规则。在 v2.1.207 之前，分类器也读取 `.claude/settings.local.json`；将该文件中的任何 `autoMode` 块移动到 `~/.claude/settings.json`。排除 `.claude/settings.local.json` 也解决了仓库提交该文件或本地工具或构建步骤写入该文件的情况。78分类器不从 `.claude/settings.json` 或 `.claude/settings.local.json` 中的项目设置读取 `autoMode`。两个文件都位于仓库目录中，因此已检入的仓库或构建步骤可能会注入自己的允许规则。将 `.claude/settings.local.json` 中的任何 `autoMode` 块移动到 `~/.claude/settings.json`。

83 79

84来自每个范围的条目被合并。开发者可以使用个人条目扩展 `environment`、`allow`、`soft_deny` 和 `hard_deny`，但不能删除托管设置提供的条目。由于允许规则在分类器内充当软块规则的例外，开发者添加的 `allow` 条目可以覆盖组织的 `soft_deny` 条目：组合是累加的，而不是硬策略边界。80来自每个范围的条目被合并。开发者可以使用个人条目扩展 `environment`、`allow`、`soft_deny` 和 `hard_deny`，但不能删除托管设置提供的条目。由于允许规则在分类器内充当软块规则的例外，开发者添加的 `allow` 条目可以覆盖组织的 `soft_deny` 条目：组合是累加的，而不是硬策略边界。

85 81

93 89

94对于大多数组织，`autoMode.environment` 是您唯一需要设置的字段。它告诉分类器哪些仓库、存储桶和域是受信的：分类器使用它来决定"外部"的含义，因此任何未列出的目标都是潜在的数据泄露目标。90对于大多数组织，`autoMode.environment` 是您唯一需要设置的字段。它告诉分类器哪些仓库、存储桶和域是受信的：分类器使用它来决定"外部"的含义，因此任何未列出的目标都是潜在的数据泄露目标。

95 91

~~96从 Claude Code v2.1.198 开始，`claude auto-mode defaults` 打印三种环境条目。v2.1.195 之前的版本仅打印前五个信任槽。~~92`claude auto-mode defaults` 打印三种环境条目。

97 93

~~98* **Context slots**：描述您的组织、技术栈和安全态势，以便分类器读取上下文中的其他规则。每个默认为 `None configured` 或保守假设（如下所示）：~~94* **Context slots**：描述您的组织、技术栈和安全态势，以便分类器读取您上下文中的其他规则。每个默认为 `None configured` 或保守假设（如下所示）：

99 * **Organization**95 * **Organization**

100 * **Claude Code 的主要用途**：默认为软件开发96 * **Claude Code 的主要用途**：默认为软件开发

101 * **云提供商**97 * **云提供商**

102 * **Repository visibility**：除非其远程主机和名称另有说明，或分类器在对话中较早读取了显示其为公开的可见性检查，否则假定仓库为私有。98 * **Repository visibility**：除非其远程主机和名称另有说明，或分类器在对话中较早读取了显示其为公开的可见性检查，否则假定仓库为私有。

103 99

104 在 Claude Code 本身发送的分类器请求中，分类器读取您的消息和 Claude 运行的命令，而不是它们的输出。证据必须是分类器能够读取的内容，例如您自己的消息将仓库命名为公开；`gh repo view` 的输出本身无法到达它。转录证据检查需要 Claude Code v2.1.200 或更高版本100 在 Claude Code 本身发送的分类器请求中，分类器读取您的消息和 Claude 运行的命令，而不是它们的输出。证据必须是分类器能够读取的内容，例如您自己的消息将仓库命名为公开；单独的 `gh repo view` 输出无法到达它。

105 * **Internal sharing / snippet hosting**：公开粘贴和 gist 服务被视为在信任边界之外，直到您命名其中一个101 * **Internal sharing / snippet hosting**：公开粘贴和 gist 服务被视为在信任边界之外，直到您命名其中一个

106 * **Org-specific CLIs**102 * **Org-specific CLIs**

107 * **Secrets management**103 * **Secrets management**

108 * **CI/CD deploy targets**104 * **CI/CD deploy targets**

109 * **Network posture**105 * **Network posture**

110 * **Host containment**：默认为具有开放互联网的普通开发者机器或 CI 运行器。如果 Claude Code 在具有出口允许列表或不能接触的邻居的容器、VM 或 pod 中运行，请命名允许的主机、云元数据端点是否应该可达，以及任务使用的云项目、集群或注册表以及使用什么身份。在此条目命名该身份之前，分类器[阻止](/docs/zh-CN/permission-modes#what-the-classifier-blocks-by-default)对主机自身凭证的请求。需要 Claude Code v2.1.257 或更高版本106 * **Host containment**：默认为具有开放互联网的普通开发者机器或 CI 运行器。如果 Claude Code 在具有出站允许列表或不能接触的邻居的容器、VM 或 pod 中运行，请命名允许的主机、云元数据端点是否应该可达，以及任务使用的云项目、集群或注册表以及使用什么身份。在此条目命名该身份之前，分类器[阻止](/docs/zh-CN/permission-modes#what-the-classifier-blocks-by-default)对主机自身凭证的请求。需要 Claude Code v2.1.257 或更高版本

111 * **Protected deployment namespaces / environments**：回退到 Sensitive remote targets 启发式方法，直到您命名它们107 * **Protected deployment namespaces / environments**：在您命名它们之前回退到 Sensitive remote targets 启发式

112 * **Data retention / declassification**108 * **Data retention / declassification**

113* **Trust slots**：命名分类器视为在您边界内的内容。槽位为 Trusted repo、Source control、Trusted internal domains、Trusted cloud buckets、Key internal services 和 Internal package registry。repo 和 source-control 条目默认为工作仓库及其配置的远程。所有其他信任槽默认为 `None configured`，因此在您添加之前没有其他内容是受信的。仓库的可见性仅限于机密材料：私有仓库是机密材料的可接受目标，但将仓库设为私有永远不会将秘密或个人或受信数据清除到其中，分类器将从工作仓库外部移植、重新指向或首次读取的内容视为不是该仓库自己的工作。此范围界定需要 Claude Code v2.1.203 或更高版本。109* **Trust slots**：命名分类器视为在您边界内的内容。这些 slots 是 Trusted repo、Source control、Trusted internal domains、Trusted cloud buckets、Key internal services 和 Internal package registry。repo 和 source-control 条目默认为工作仓库及其配置的远程。所有其他信任 slot 默认为 `None configured`，因此在您添加之前没有其他内容是受信的。仓库的可见性仅限制机密材料：私有仓库是机密材料的可接受目标，但将仓库设为私有永远不会授权将秘密、个人或受信数据放入其中，分类器将从工作仓库外部移植、重新指向或首次读取的内容视为不是该仓库自身的工作。

114* **Sensitivity slots**：命名保护规则视为高风险的内容。槽位为 Sensitive data locations & audiences、Sensitive remote targets 和 Protected IaC scopes。每个默认为广泛的启发式方法，例如将任何名称中包含 `prod` 或 `production` 的主机或命名空间视为敏感远程目标，因此保护规则在您配置任何内容之前就处于活动状态。在敏感性槽中命名具体目标会使这些规则应用于命名的目标而不是启发式方法。110* **Sensitivity slots**：命名保护规则视为高风险的内容。这些 slots 是 Sensitive data locations & audiences、Sensitive remote targets 和 Protected IaC scopes。每个默认为广泛的启发式，例如将任何名称中包含 `prod` 或 `production` 的主机或命名空间视为敏感远程目标，因此保护规则在您配置任何内容之前就处于活跃状态。在敏感 slot 中命名具体目标会使这些规则应用于命名的目标而不是启发式。

~~115~~

116<Info>在 v2.1.211 之前，context slots 还包括一个 Default / protected branches 条目，该条目将 `main` 和 `master` 视为受保护，直到您命名其他分支。v2.1.211 删除了它：[推送到您正在处理的仓库的任何分支](#common-boundaries)默认是允许的，因此没有受保护分支默认值需要配置。</Info>

117 111

118要在默认值旁边添加您自己的条目，请在数组中包含字面字符串 `"$defaults"`。默认条目在该位置被拼接，因此您的自定义条目可以在它们之前或之后。112要在默认值旁边添加您自己的条目，请在数组中包含字面字符串 `"$defaults"`。默认条目在该位置被拼接，因此您的自定义条目可以在它们之前或之后。

119 113

133}127}

134```128```

135 129

136保存设置后，运行 `claude auto-mode config` 以[确认有效规则](#inspect-the-defaults-and-your-effective-config)包括您的条目。130保存设置后，运行 `claude auto-mode config` 以[确认有效规则](#inspect-the-defaults-and-your-effective-config)包含您的条目。

137 131

138条目是散文，不是正则表达式或工具模式。分类器将它们读取为自然语言规则。按照您向新工程师描述基础设施的方式编写它们。彻底的环境部分涵盖：132条目是散文，不是正则表达式或工具模式。分类器将它们读取为自然语言规则。按照您向新工程师描述基础设施的方式编写它们。彻底的环境部分涵盖：

139 133

143* **Trusted internal domains**：网络内 API、仪表板和服务的主机名，例如 `*.internal.example.com`137* **Trusted internal domains**：网络内 API、仪表板和服务的主机名，例如 `*.internal.example.com`

144* **Key internal services**：CI、工件注册表、内部包索引、事件工具138* **Key internal services**：CI、工件注册表、内部包索引、事件工具

145* **Internal package registry**：安装应该通过的私有 npm、PyPI 或其他注册表，因此绕过它安装到公开注册表的安装会被阻止139* **Internal package registry**：安装应该通过的私有 npm、PyPI 或其他注册表，因此绕过它安装到公开注册表的安装会被阻止

146* **Sensitive data locations & audiences**：保存个人数据、机密业务数据、凭证、受管制数据或类似敏感材料的存储桶、数据库或路径，以及每个位置中的数据可能与之共享的受众，以便分类器保护这些位置而不是从内容猜测。Claude Code v2.1.195 到 v2.1.197 将此条目命名为 PII / regulated-data locations，仅涵盖保存个人或受管制数据的位置，不包括受众维度140* **Sensitive data locations & audiences**：包含个人数据、机密业务数据、凭证、受管制数据或类似敏感材料的存储桶、数据库或路径，以及每个位置中的数据可能与之共享的受众，以便分类器保护这些位置而不是从内容猜测

147* **Sensitive remote targets**：计为生产的命名空间、主机或容器，因此远程 shell 和端口转发到它们需要您的明确批准141* **Sensitive remote targets**：计为生产的命名空间、主机或容器，因此远程 shell 和端口转发到它们需要您的明确批准

148* **Protected IaC scopes**：应用或销毁应始终需要您命名更改的基础设施资源142* **Protected IaC scopes**：应用或销毁应始终需要您命名更改的基础设施资源

149* **Additional context**：受管制行业约束、多租户基础设施或影响分类器应视为风险的合规要求143* **Additional context**：受管制行业约束、多租户基础设施或影响分类器应视为风险的合规要求

150 144

151Internal package registry、Sensitive data locations & audiences、Sensitive remote targets 和 Protected IaC scopes 条目需要 Claude Code v2.1.195 或更高版本。早期版本仍将它们读取为纯上下文，但没有针对它们的内置规则。

~~152~~

153一个有用的起始模板：填写括号中的字段并删除任何不适用的行。145一个有用的起始模板：填写括号中的字段并删除任何不适用的行。

154 146

155```json theme={null}147```json theme={null}

169}161}

170```162```

171 163

172您提供的上下文越具体，分类器就越能区分常规内部操作和数据泄露尝试。

~~173~~

174您不需要一次性填写所有内容。合理的推出方式：从默认值开始，添加您的源代码控制组织和关键内部服务，这解决了最常见的误报，例如推送到您自己的仓库。接下来添加受信域和云存储桶。当出现阻止时填写其余部分。164您不需要一次性填写所有内容。合理的推出方式：从默认值开始，添加您的源代码控制组织和关键内部服务，这解决了最常见的误报，例如推送到您自己的仓库。接下来添加受信域和云存储桶。当出现阻止时填写其余部分。

175 165

176<h2 id="generate-environment-entries">166<h2 id="generate-environment-entries">

305 295

306默认情况下，narrow Bash 和 PowerShell 允许规则（如 `Bash(npm test)`）在自动模式下保持有效。Claude Code 在分类器运行之前解析它们，除非命令携带[按命令允许的域](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)。Claude Code 仅暂停授予任意代码执行权限的广泛规则，例如 `Bash(*)` 或通配符解释器，以及每个命名 [`Monitor`](/docs/zh-CN/tools-reference#monitor-tool) 的规则，因为 Monitor 命令通过 shell 运行。这意味着 narrow 规则仍然可以让分类器看不到的破坏性参数通过，例如规则前缀未预期的脚本路径或标志。296默认情况下，narrow Bash 和 PowerShell 允许规则（如 `Bash(npm test)`）在自动模式下保持有效。Claude Code 在分类器运行之前解析它们，除非命令携带[按命令允许的域](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)。Claude Code 仅暂停授予任意代码执行权限的广泛规则，例如 `Bash(*)` 或通配符解释器，以及每个命名 [`Monitor`](/docs/zh-CN/tools-reference#monitor-tool) 的规则，因为 Monitor 命令通过 shell 运行。这意味着 narrow 规则仍然可以让分类器看不到的破坏性参数通过，例如规则前缀未预期的脚本路径或标志。

307 297

308将 `autoMode.classifyAllShell` 设置为 `true`，以在自动模式处于活动状态时暂停每个 Bash 和 PowerShell 允许规则，使分类器评估每个 shell 命令，无论您的允许列表如何。298将 `autoMode.classifyAllShell` 设置为 `true`，以在自动模式处于活动状态时暂停每个 Bash 和 PowerShell 允许规则，使分类器评估每个 shell 命令，无论您的允许列表如何，除了[关键路径移除](/docs/zh-CN/permission-modes#critical-paths)。

309 299

310```json theme={null}300```json theme={null}

311{301{

319 309

320该设置仅在自动模式处于活动状态时适用，您的允许规则在其他权限模式中表现正常。310该设置仅在自动模式处于活动状态时适用，您的允许规则在其他权限模式中表现正常。

321 311

322<Note>

323 `autoMode.classifyAllShell` 需要 Claude Code v2.1.193 或更高版本。早期版本忽略该键并继续将 narrow shell 允许规则带入自动模式。

324</Note>

~~325~~

326<h2 id="inspect-the-defaults-and-your-effective-config">312<h2 id="inspect-the-defaults-and-your-effective-config">

327 检查默认值和有效配置313 检查默认值和有效配置

328</h2>314</h2>

371claude auto-mode critique357claude auto-mode critique

372```358```

373 359

374保存设置后运行 `claude auto-mode config` 以确认有效规则符合您的预期，其中 `"$defaults"` 已展开。如果您编写了自定义规则，`claude auto-mode critique` 会审查它们并标记模糊、冗余或可能导致误报的条目。360如果您编写了自定义规则，`claude auto-mode critique` 会审查它们并标记模糊、冗余或可能导致误报的条目。

375 361

376要放弃您的自定义设置并返回内置默认值，请运行 reset 子命令。它需要 Claude Code v2.1.212 或更高版本，并从您的用户设置文件中删除 `autoMode` 部分：362要放弃您的自定义设置并返回内置默认值，请运行 reset 子命令。它需要 Claude Code v2.1.212 或更高版本，并从您的用户设置文件中删除 `autoMode` 部分：

377 363

405 391

406您可以从 `/permissions` 对话框的 [**Auto mode** 选项卡](#edit-rules-from-permissions)添加环境条目或 `allow` 规则。392您可以从 `/permissions` 对话框的 [**Auto mode** 选项卡](#edit-rules-from-permissions)添加环境条目或 `allow` 规则。

407 393

408在大多数会话中，原因名称分类器匹配的规则，在方括号中，例如 `[Data Exfiltration]` 或 `[Production Deploy]`，某些会话运行一个分类器模型，该模型添加简短解释。Claude Code 选择分类器模型，因此您看到的原因不是您可以配置的。394方括号中的文本，例如 `[Data Exfiltration]`，是分类器匹配的规则的名称。要阅读该规则的完整措辞，请参阅[检查默认值和您的有效配置](#inspect-the-defaults-and-your-effective-config)。

409 395

410<h3 id="fix-repeated-denials">396<h3 id="fix-repeated-denials">

411 修复重复拒绝397 修复重复拒绝

413 399

414对同一目标的重复拒绝通常意味着分类器缺少上下文。将该目标添加到 `autoMode.environment`，或[运行 `/auto-mode-setup`](#generate-environment-entries) 让 Claude Code 起草条目，然后运行 `claude auto-mode config` 以确认更改已生效。400对同一目标的重复拒绝通常意味着分类器缺少上下文。将该目标添加到 `autoMode.environment`，或[运行 `/auto-mode-setup`](#generate-environment-entries) 让 Claude Code 起草条目，然后运行 `claude auto-mode config` 以确认更改已生效。

415 401

416要以编程方式对拒绝做出反应，请使用 [`PermissionDenied` hook](/docs/zh-CN/hooks#permissiondenied)。

~~417~~

418<h2 id="see-also">402<h2 id="see-also">

419 另请参阅403 另请参阅

420</h2>404</h2>

best-practices.md +3 −3

Details

46 46

47* **在一个提示中**：要求 Claude 运行检查并在同一消息中迭代，如上表所示。47* **在一个提示中**：要求 Claude 运行检查并在同一消息中迭代，如上表所示。

48* **在整个会话中**：将检查设置为 [`/goal` 条件](/docs/zh-CN/goal)。单独的评估器在每次转换后重新检查它，Claude 继续工作直到目标解决。如果 Claude 停滞，Claude Code 最终会在目标仍然设置的情况下停止运行 — 请参阅 [/goal 评估如何工作](/docs/zh-CN/goal#how-evaluation-works)。48* **在整个会话中**：将检查设置为 [`/goal` 条件](/docs/zh-CN/goal)。单独的评估器在每次转换后重新检查它，Claude 继续工作直到目标解决。如果 Claude 停滞，Claude Code 最终会在目标仍然设置的情况下停止运行 — 请参阅 [/goal 评估如何工作](/docs/zh-CN/goal#how-evaluation-works)。

49* **作为确定性门**：[Stop hook](/docs/zh-CN/hooks#stop) 作为脚本运行你的检查，并阻止转换结束直到它通过。Claude Code 覆盖 hook 并在 8 次连续阻止后结束转换。49* **作为确定性门**：[Stop hook](/docs/zh-CN/hooks#stop) 作为脚本运行你的检查，并阻止转换结束直到它通过。[Stop input](/docs/zh-CN/hooks#stop-input) 涵盖连续阻止的上限。

50* **通过第二意见**：[验证子代理](/docs/zh-CN/sub-agents)或[动态工作流](/docs/zh-CN/workflows)检查自己的发现，有一个新鲜的模型尝试反驳结果，所以做工作的代理不是给它评分的。50* **通过第二意见**：[验证子代理](/docs/zh-CN/sub-agents)或[动态工作流](/docs/zh-CN/workflows)检查自己的发现，有一个新鲜的模型尝试反驳结果，所以做工作的代理不是给它评分的。

51 51

52每一步都用设置换取关注。提示版本适用于今天的任何任务。`/goal` 和 Stop hook 版本是让无人值守运行正确完成而无需你的东西。52每一步都用设置换取关注。提示版本适用于今天的任何任务。`/goal` 和 Stop hook 版本是让无人值守运行正确完成而无需你的东西。

209 要获得更少的提示而不放弃控制，使用 `/permissions` 预先批准你信任的工具，并使用 `/sandbox` 让沙箱命令无需询问即可运行。当你想自己批准编辑和命令时，切换到手动模式。209 要获得更少的提示而不放弃控制，使用 `/permissions` 预先批准你信任的工具，并使用 `/sandbox` 让沙箱命令无需询问即可运行。当你想自己批准编辑和命令时，切换到手动模式。

210</Tip>210</Tip>

211 211

212在 Pro、Max 和 Team 计划上，auto mode 是交互式终端和 VS Code 会话的 [内置起始权限模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)：一个单独的分类器模型审查大多数操作，而不是你，仅阻止看起来有风险的东西，如范围升级、未知基础设施或由敌对内容驱动的操作。212在 Claude Code v2.1.283 或更高版本中，auto mode 是交互式终端和 VS Code 会话的 [内置起始权限模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)：一个单独的分类器模型审查大多数操作，而不是你，仅阻止看起来有风险的东西，如范围升级、未知基础设施或由敌对内容驱动的操作。在早期版本中，auto mode 仅在 Pro、Max 和 Team 计划上是交互式终端和 VS Code 会话的内置起始权限模式。

213 213

214在手动模式中，其他计划上的内置起始权限模式，Claude Code 在可能修改你的系统的操作之前询问：文件写入、Bash 命令、MCP 工具。这是安全的但繁琐。在第十次批准后，你在点击通过而不是审查。两个工具在手动模式中减少这些中断，也适用于 auto mode：214在手动模式中，Claude Code 在可能修改你的系统的操作之前询问：文件写入、Bash 命令、MCP 工具。这是安全的但繁琐。在第十次批准后，你在点击通过而不是审查。两个工具在手动模式中减少这些中断，也适用于 auto mode：

215 215

216* **权限允许列表**：允许你知道是安全的特定工具，如 `npm run lint` 或 `git commit`216* **权限允许列表**：允许你知道是安全的特定工具，如 `npm run lint` 或 `git commit`

217* **沙箱**：启用操作系统级隔离，限制文件系统和网络访问，允许 Claude 在定义的边界内更自由地工作217* **沙箱**：启用操作系统级隔离，限制文件系统和网络访问，允许 Claude 在定义的边界内更自由地工作

channels.md +1 −1

Details

359 359

360在预览期间，`--channels` 仅接受来自 Anthropic 维护的允许列表的插件，或来自您组织的允许列表（如果管理员已设置 [`allowedChannelPlugins`](#restrict-which-channel-plugins-can-run)）。[claude-plugins-official](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins) 中的 channel 插件是默认批准的集合。如果您传递不在有效允许列表中的内容，Claude Code 会正常启动，但 channel 不会注册，启动通知会告诉您原因。360在预览期间，`--channels` 仅接受来自 Anthropic 维护的允许列表的插件，或来自您组织的允许列表（如果管理员已设置 [`allowedChannelPlugins`](#restrict-which-channel-plugins-can-run)）。[claude-plugins-official](https://github.com/anthropics/claude-plugins-official/tree/main/external_plugins) 中的 channel 插件是默认批准的集合。如果您传递不在有效允许列表中的内容，Claude Code 会正常启动，但 channel 不会注册，启动通知会告诉您原因。

361 361

362要测试您正在构建的 channel，请使用 `--dangerously-load-development-channels`。有关测试您构建的自定义 channels 的信息，请参阅[在研究预览期间测试](/docs/zh-CN/channels-reference#test-during-the-research-preview)。362要测试您正在构建的 channel，请将其以 `plugin:<name>@<marketplace>` 或 `server:<name>` 的形式传递给 `--dangerously-load-development-channels`。有关测试您构建的自定义 channels 的信息，请参阅[在研究预览期间测试](/docs/zh-CN/channels-reference#test-during-the-research-preview)。

363 363

364在 [Claude Code GitHub 存储库](https://github.com/anthropics/claude-code/issues)上报告问题或反馈。364在 [Claude Code GitHub 存储库](https://github.com/anthropics/claude-code/issues)上报告问题或反馈。

365 365

channels-reference.md +1 −1

Details

803 803

804要使您的频道可安装和可共享，请将其包装在[插件](/docs/zh-CN/plugins/overview)中并将其发布到[市场](/docs/zh-CN/plugins/overview)。用户使用 `/plugin install` 安装它，然后使用 `--channels plugin:<name>@<marketplace>` 按会话启用它。804要使您的频道可安装和可共享，请将其包装在[插件](/docs/zh-CN/plugins/overview)中并将其发布到[市场](/docs/zh-CN/plugins/overview)。用户使用 `/plugin install` 安装它，然后使用 `--channels plugin:<name>@<marketplace>` 按会话启用它。

805 805

806发布到您自己的市场的频道仍然需要 `--dangerously-load-development-channels` 来运行，因为它不在[批准的允许列表](/docs/zh-CN/channels#supported-channels)上。默认允许列表是 `claude-plugins-official` 中的频道插件。[应用内提交表单](/docs/zh-CN/plugins/publish#submit-to-the-community-marketplace)将插件添加到社区市场，该市场不在频道允许列表上。806发布到您自己的市场的频道仍然需要 `--dangerously-load-development-channels` 来运行，因为它不在[批准的允许列表](/docs/zh-CN/channels#supported-channels)上。默认允许列表是 `claude-plugins-official` 中的频道插件。社区市场不在频道允许列表上。

807 807

808如果您正在与 Anthropic 合作伙伴联系合作，请与他们联系以协调官方市场列表。在 Team 和 Enterprise 计划上，管理员可以改为将您的插件包含在组织自己的 [`allowedChannelPlugins`](/docs/zh-CN/channels#restrict-which-channel-plugins-can-run) 列表中，该列表替换默认的 Anthropic 允许列表。808如果您正在与 Anthropic 合作伙伴联系合作，请与他们联系以协调官方市场列表。在 Team 和 Enterprise 计划上，管理员可以改为将您的插件包含在组织自己的 [`allowedChannelPlugins`](/docs/zh-CN/channels#restrict-which-channel-plugins-can-run) 列表中，该列表替换默认的 Anthropic 允许列表。

809 809

checkpointing.md +1 −1

Details

114 中途发送的消息未检查点114 中途发送的消息未检查点

115</h3>115</h3>

116 116

117当您在 Claude 工作时[排队的消息](/docs/zh-CN/interactive-mode#queue-messages-while-claude-works)在运行的回合中到达 Claude 时，它会加入该回合而不是开始新的回合。该消息会出现在对话中，但 Claude Code 不会为其创建检查点，回溯菜单也不会列出它。Claude Code 作为其自己的回合发送的排队消息会照常获得检查点。117当您在 Claude 工作时[排队的消息](/docs/zh-CN/interactive-mode#queue-messages-while-claude-works)在运行的回合中到达 Claude 时，它会加入该回合而不是开始新的回合。该消息会出现在对话中，但 Claude Code 不会为其创建检查点，回溯菜单也不会列出它。Claude Code 作为其自己的回合发送的排队消息会照常获得检查点，包括当多个排队消息[共享该回合](/docs/zh-CN/interactive-mode#when-claude-code-sends-what-you-queued)时。

118 118

119要删除此类消息或撤销 Claude 在其后所做的编辑，请回溯到启动该回合的提示。这会回溯整个回合，包括 Claude 在您的消息到达之前所做的工作。119要删除此类消息或撤销 Claude 在其后所做的编辑，请回溯到启动该回合的提示。这会回溯整个回合，包括 Claude 在您的消息到达之前所做的工作。

120 120

claude-apps-gateway.md +2 −2

Details

448 448

449即使设置了所有五个锁，六个父提供的设置也会通过过滤器。在默认的先赢设置下，阻止父设置的管理员值是最高优先级管理员源中的值，除了 `allowedMcpServers` 当[MCP 服务器锁](#lock-behavior-across-sources)打开时。在 `managedSourcesBehavior` 合并选择加入下，[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明哪个源的值改为适用。449即使设置了所有五个锁，六个父提供的设置也会通过过滤器。在默认的先赢设置下，阻止父设置的管理员值是最高优先级管理员源中的值，除了 `allowedMcpServers` 当[MCP 服务器锁](#lock-behavior-across-sources)打开时。在 `managedSourcesBehavior` 合并选择加入下，[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明哪个源的值改为适用。

450 450

451* **`forceLoginOrgUUID`**：当最高优先级管理员源未设置组织 UUID 时，Claude Code 尊重父提供的值。网关登录不检查此密钥，因此它仅对也使用第一方 Anthropic 登录的舰队重要。最高优先级管理员源中的组织 UUID 阻止父的值，是 Claude Code 强制执行的值，因此在那里设置 `forceLoginOrgUUID`。451* **`forceLoginOrgUUID`**：当最高优先级管理员源未设置组织 UUID 时，Claude Code 尊重父提供的值。网关登录不检查此密钥。最高优先级管理员源中的组织 UUID 阻止父的值，是 Claude Code 强制执行的值。

452* **`allowedMcpServers`**：当最高优先级管理员源未设置允许列表时，Claude Code 尊重父提供的允许列表，`allowManagedMcpServersOnly` 不阻止它，因为锁强制执行任何赢家列表作为托管值，包括当最高优先级管理员源未设置时的父提供列表。最高优先级管理员源中的列表阻止父的并是 Claude Code 强制执行的列表，因此在那里设置 `allowedMcpServers`，在锁旁边。在 v2.1.223 之前，任何管理员源中任一密钥的值都阻止父的。452* **`allowedMcpServers`**：当最高优先级管理员源未设置允许列表时，Claude Code 尊重父提供的允许列表，`allowManagedMcpServersOnly` 不阻止它，因为锁强制执行任何赢家列表作为托管值，包括当最高优先级管理员源未设置时的父提供列表。最高优先级管理员源中的列表阻止父的并是 Claude Code 强制执行的列表，因此在那里设置 `allowedMcpServers`，在锁旁边。在 v2.1.223 之前，任何管理员源中任一密钥的值都阻止父的。

453* **`availableModels`**：当赢家托管源未设置模型列表时，Claude Code 尊重父提供的模型列表。如果您的舰队限制模型，在赢家源中设置 `availableModels`。453* **`availableModels`**：当赢家托管源未设置模型列表时，Claude Code 尊重父提供的模型列表。如果您的舰队限制模型，在赢家源中设置 `availableModels`。

454* **`strictKnownMarketplaces`**：当赢家托管源未设置一个时，Claude Code 尊重父提供的插件市场允许列表。如果您的舰队限制市场，在赢家源中设置 `strictKnownMarketplaces`。需要 Claude Code v2.1.282 或更高版本。454* **`strictKnownMarketplaces`**：当赢家托管源未设置一个时，Claude Code 尊重父提供的插件市场允许列表。如果您的舰队限制市场，在赢家源中设置 `strictKnownMarketplaces`。需要 Claude Code v2.1.282 或更高版本。

486 * 在[Claude Desktop 启动](#connect-claude-desktop)的嵌入式会话中，CLI 将其导出发送到配置的 `OTEL_EXPORTER_OTLP_ENDPOINT`。CLI 仅当该端点指向网关本身时才将网关会话令牌附加到这些导出。486 * 在[Claude Desktop 启动](#connect-claude-desktop)的嵌入式会话中，CLI 将其导出发送到配置的 `OTEL_EXPORTER_OTLP_ENDPOINT`。CLI 仅当该端点指向网关本身时才将网关会话令牌附加到这些导出。

487 * 没有为信号配置目标时，网关接受并丢弃它。487 * 没有为信号配置目标时，网关接受并丢弃它。

488 * 如果您已直接收集 Claude Code 遥测，将您的收集器添加为 `forward_to` 目标，或在策略中命名它以跳过中继。488 * 如果您已直接收集 Claude Code 遥测，将您的收集器添加为 `forward_to` 目标，或在策略中命名它以跳过中继。

489* **凭证**：网关令牌是会话的唯一凭证。[Anthropic 配置文件](/docs/zh-CN/authentication#anthropic-profiles-and-federation-credentials)和任何早期的 claude.ai 登录在登录时被忽略，因此开发人员不需要首先从 claude.ai 注销。对于配置的 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 凭证，请参阅[管理员策略需要 Cloud 网关登录](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。489* **凭证**：网关令牌是会话的唯一凭证。[Anthropic 配置文件](/docs/zh-CN/authentication#anthropic-profiles-and-federation-credentials)和任何早期的 claude.ai 登录在登录时被忽略，因此开发人员不需要首先从 claude.ai 注销。对于配置的 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 凭证，或早期 Claude Console 登录保存的 API 密钥，请参阅[管理员策略需要 Cloud 网关登录](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。

490* **托管设置**：锁定的密钥无法在本地覆盖。CLI 在启动时应用策略，并在每个小时轮询时应用更改，除了[仅在下一次启动时应用的更改](/docs/zh-CN/server-managed-settings#fetch-and-caching-behavior)。490* **托管设置**：锁定的密钥无法在本地覆盖。CLI 在启动时应用策略，并在每个小时轮询时应用更改，除了[仅在下一次启动时应用的更改](/docs/zh-CN/server-managed-settings#fetch-and-caching-behavior)。

491* **启动时网关无法访问**：已登录的会话在启动时约 10 秒后以错误退出，而不是在没有其设置的情况下启动。491* **启动时网关无法访问**：已登录的会话在启动时约 10 秒后以错误退出，而不是在没有其设置的情况下启动。

492* **启动后网关结束会话**：请参阅[强制执行故障关闭启动](/docs/zh-CN/server-managed-settings#enforce-fail-closed-startup)，了解哪些启动从网关登出打开，哪些在网关以 `401` 应答时退出。492* **启动后网关结束会话**：请参阅[强制执行故障关闭启动](/docs/zh-CN/server-managed-settings#enforce-fail-closed-startup)，了解哪些启动从网关登出打开，哪些在网关以 `401` 应答时退出。

claude-apps-gateway-config.md +52 −4

Details

170| `password` | 否 | 数据库凭证。在此处设置而不是在 `postgres_url` 中，以便凭证保持在 URL 之外。接受任何字符并优先于 URL 凭证。 |170| `password` | 否 | 数据库凭证。在此处设置而不是在 `postgres_url` 中，以便凭证保持在 URL 之外。接受任何字符并优先于 URL 凭证。 |

171| `max_connections` | 否 | 每个副本的 Postgres 连接池大小。默认 `5`，这是保守的，对共享数据库友好。启用[支出限制](#admin)后，热路径在每个推理请求中执行几个操作，因此在负载下为专用数据库提高它，并保持副本 × 这个值低于数据库的 `max_connections`。 |171| `max_connections` | 否 | 每个副本的 Postgres 连接池大小。默认 `5`，这是保守的，对共享数据库友好。启用[支出限制](#admin)后，热路径在每个推理请求中执行几个操作，因此在负载下为专用数据库提高它，并保持副本 × 这个值低于数据库的 `max_connections`。 |

172| `connect_timeout_seconds` | 否 | 网关打开 Postgres 连接时等待的秒数。从 `1` 到 `60` 的整数，默认 `5`。如果当新网关实例启动时连接尝试超时，请提高它。需要网关服务器上的 Claude Code v2.1.274 或更高版本。早期版本在设置该键时拒绝启动。 |172| `connect_timeout_seconds` | 否 | 网关打开 Postgres 连接时等待的秒数。从 `1` 到 `60` 的整数，默认 `5`。如果当新网关实例启动时连接尝试超时，请提高它。需要网关服务器上的 Claude Code v2.1.274 或更高版本。早期版本在设置该键时拒绝启动。 |

173| `readiness_grace_seconds` | 否 | 在 Postgres 停止应答后 `/readyz` 继续报告就绪的秒数。从 `0` 到 `3600` 的整数，默认 `0`。请参阅[中断行为](/docs/zh-CN/claude-apps-gateway-deploy#outage-behavior)以了解如何选择值。需要网关服务器上的 Claude Code v2.1.282 或更高版本。早期版本在设置该键时拒绝启动。 |

173 174

174对于本地开发，将 `postgres_url` 指向一个一次性 Postgres 容器，例如 `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。175对于本地开发，将 `postgres_url` 指向一个一次性 Postgres 容器，例如 `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。

175 176

947* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`948* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`

948* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`949* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`

949 950

951当您[添加您自己的标签](#add-your-own-labels)时，网关也推送 `OTEL_RESOURCE_ATTRIBUTES`。

952

950在网关服务器上的 Claude Code v2.1.265 之前，网关将所有三个导出器选择器推送为 `otlp`，包括没有目的地选择加入的信号。953在网关服务器上的 Claude Code v2.1.265 之前，网关将所有三个导出器选择器推送为 `otlp`，包括没有目的地选择加入的信号。

951 954

952推送的端点是从公共 URL 构建的，因此指标和日志不需要来自开发者或策略的 OTEL 配置。955推送的端点是从公共 URL 构建的，因此指标和日志不需要来自开发者或策略的 OTEL 配置。

964 967

965Protobuf 和 JSON OTLP 编码都被中继，任何 OpenTelemetry 兼容的后端都可以作为目的地。968Protobuf 和 JSON OTLP 编码都被中继，任何 OpenTelemetry 兼容的后端都可以作为目的地。

966 969

970<h4 id="add-your-own-labels">

971 添加您自己的标签

972</h4>

973

974要在通过网关登录的会话的遥测上放置固定标签（如 `service.namespace` 或 `deployment.environment.name`），设置 `telemetry.resource_attributes`。每个标签是一个 OpenTelemetry 资源属性，每个目的地接收相同的标签。

975

976会话仅在您也设置 `telemetry.forward_to` 和 `listen.public_url` 时获得标签。此示例添加两个标签：

977

978```yaml theme={null}

979telemetry:

980 forward_to:

981 - url: https://otel-collector.internal.example.com

982 resource_attributes:

983 service.namespace: claude

984 deployment.environment.name: prod

985```

986

987当标签违反这些规则之一时，网关拒绝启动，启动错误命名标签：

988

989* 名称仅使用字母、数字、`.`、`_` 和 `-`

990* 名称不是保留的。以任何字母大小写比较，保留名称是以 `user.`、`enduser.` 或 `identity.` 开头的所有内容，加上 `service.name`、`service.version`、`claude.deployment_mode`、`host.arch`、`os.type`、`os.version` 和 `wsl.version`

991* 值是非空可打印 ASCII，没有空格和 `, ; = \ " %` 中的任何一个

992* 值最多 255 个字符，网关在百分比编码后计数，因此 `/`、`:` 和 `@` 各计为三个

993* 值是文本，因此引用数字、`true` 或 `false`

994

995您需要网关服务器上的 Claude Code v2.1.281 或更高版本才能设置 `telemetry.resource_attributes`。早期网关在找到该键时拒绝启动。在添加该键之前升级每个副本，并在回滚到早期版本之前删除该键。

996

997通过 `/login` 登录的终端会话接收标签作为 `OTEL_RESOURCE_ATTRIBUTES`，与其他[遥测变量](#telemetry)一起推送。如果您在策略的 `env` 块中设置 `OTEL_RESOURCE_ATTRIBUTES`，与该策略匹配的终端会话获得该值而不是标签。Claude Desktop 从网关接收标签以及 `user.email` 和其他身份属性。

998

999Claude Code 也将每个标签复制到每个指标数据点，因此您可以在不索引资源属性的后端中按它过滤指标。要关闭该复制，请参阅[指标基数控制](/docs/zh-CN/monitoring-usage#metrics-cardinality-control)。

1000

967<h4 id="export-directly-to-your-collector">1001<h4 id="export-directly-to-your-collector">

968 直接导出到您的收集器1002 直接导出到您的收集器

969</h4>1003</h4>

1034 1068

1035`load_test_mode` 块让您在不调用模型提供商的情况下对网关进行负载测试。启用它时，网关像往常一样构建和签署每个提供商请求，丢弃它而不是发送它，并通过其正常响应路径流式传输罐装回复。回复是填充文本，以说明它是罐装的句子开头。1069`load_test_mode` 块让您在不调用模型提供商的情况下对网关进行负载测试。启用它时，网关像往常一样构建和签署每个提供商请求，丢弃它而不是发送它，并通过其正常响应路径流式传输罐装回复。回复是填充文本，以说明它是罐装的句子开头。

1036 1070

1037需要 v2.1.283 或更高版本。早期版本在设置键时拒绝启动，因此在添加块之前升级每个副本，并在回滚之前删除它。1071需要网关服务器上的 Claude Code v2.1.282 或更高版本。早期版本在找到该键时拒绝启动。在添加块之前升级每个副本，并在回滚之前删除块。

1038 1072

1039下面的示例以默认值打开模式，回复为 750 个输出令牌，在大约 10 秒内流式传输：1073下面的示例以默认值打开模式，回复为大约 750 个令牌的文本，在大约 10 秒内流式传输：

1040 1074

1041```yaml theme={null}1075```yaml theme={null}

1042load_test_mode:1076load_test_mode:

1053 1087

1054此模式下的负载测试涵盖网关、您的 Postgres 和网关前面的所有内容。它不涵盖提供商的限制、速度或网络路径。1088此模式下的负载测试涵盖网关、您的 Postgres 和网关前面的所有内容。它不涵盖提供商的限制、速度或网络路径。

1055 1089

1056启用模式时，请求可以携带 `x-load-test-user` 标头，保存最多七位数的整数，网关将每个数字计为具有请求附带的令牌的开发者的电子邮件和组的单独开发者。为负载测试部署提供自己的空数据库，因为网关拒绝在任何开发者已经花费任何东西的数据库中启动模式。1090没有模型请求发送到提供商，因此副本的每个请求的 CPU 是估计值，读取低于生产，生产也加密其到提供商的流量。使用小试点对真实提供商确认副本计数。在 v2.1.283 之前，估计读取低得多。

1091

1092启用模式时，请求可以携带 `x-load-test-user` 标头，保存最多七位数的整数。网关将每个数字计为具有请求附带的令牌的开发者的电子邮件和组的单独开发者。

1093

1094为负载测试部署提供自己的空数据库，因为网关拒绝在任何开发者已经花费任何东西的数据库中启动模式。

1057 1095

1058<Warning>1096<Warning>

1059 永远不要为开发者使用的网关打开此功能。每个请求都获得罐装回复，没有模型被调用。网关在启动时记录 `load_test_mode is on` 警告，并在模式启用时使用 `load_test: true` 标记每个 `inference` [审计事件](/docs/zh-CN/claude-apps-gateway-deploy#logs)。1097 永远不要为开发者使用的网关打开此功能。每个请求都获得罐装回复，没有模型被调用。网关在启动时记录 `load_test_mode is on` 警告，并在模式启用时使用 `load_test: true` 标记每个 `inference` [审计事件](/docs/zh-CN/claude-apps-gateway-deploy#logs)。

1111 postgres_url: ${GATEWAY_POSTGRES_URL}1149 postgres_url: ${GATEWAY_POSTGRES_URL}

1112 # max_connections: 51150 # max_connections: 5

1113 # connect_timeout_seconds: 51151 # connect_timeout_seconds: 5

1152 # readiness_grace_seconds: 300 # 在数据库故障转移期间保持通过就绪检查

1114 1153

1115# 启用 /v1/organizations/spend_limits（镜像 Anthropic Admin API）1154# 启用 /v1/organizations/spend_limits（镜像 Anthropic Admin API）

1116# 和 /v1/messages 上的每开发者支出强制。省略以禁用。1155# 和 /v1/messages 上的每开发者支出强制。省略以禁用。

1130# enforcement:1169# enforcement:

1131# fail_closed_on_error: false1170# fail_closed_on_error: false

1132 1171

1172# 在不调用模型提供商的情况下对此部署进行负载测试。永远不要在

1173# 开发人员使用的网关上：每个请求都会获得一个预设回复。

1174# load_test_mode:

1175# enabled: true

1176# # reply_tokens: 750

1177# # reply_seconds: 9.5

1178

1133# 按合同费率而不是美元列表价格计费。需要 admin: 或1179# 按合同费率而不是美元列表价格计费。需要 admin: 或

1134# managed: 策略。使用 managed:，相同的费率也会发送到已登录的客户端。1180# managed: 策略。使用 managed:，相同的费率也会发送到已登录的客户端。

1135# 下面的费率是占位符，不是真实合同价格。1181# 下面的费率是占位符，不是真实合同价格。

1231 1277

1232对于 Claude Desktop，在 Claude Desktop 自己的[托管配置](https://claude.com/docs/third-party/claude-desktop/configuration)中设置 `bootstrapUrl` 密钥为 `<listen.public_url>/user/bootstrap`。登录流程和每组策略随后与 CLI 的匹配，一旦策略通过 `desktop` 密钥在服务器端选择加入；没有选择加入，`/user/bootstrap` 返回 404。有关服务器端部分，请参阅 [Claude Desktop 覆盖层](#claude-desktop-overlay)。1278对于 Claude Desktop，在 Claude Desktop 自己的[托管配置](https://claude.com/docs/third-party/claude-desktop/configuration)中设置 `bootstrapUrl` 密钥为 `<listen.public_url>/user/bootstrap`。登录流程和每组策略随后与 CLI 的匹配，一旦策略通过 `desktop` 密钥在服务器端选择加入；没有选择加入，`/user/bootstrap` 返回 404。有关服务器端部分，请参阅 [Claude Desktop 覆盖层](#claude-desktop-overlay)。

1233 1279

1234Claude Code 仅从机器上的托管源尊重 [`forceLoginGatewayUrl`](/docs/zh-CN/settings-reference#forcelogingatewayurl)、[`gatewayInternalNetworks`](/docs/zh-CN/settings-reference#gatewayinternalnetworks) 和 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 的 `"gateway"` 值：`managed-settings.json`、macOS plist 或 Windows HKLM 注册表，或策略助手。开发者在自己的 `~/.claude/settings.json` 中设置它们无效，在网关有效负载中设置它们也无效。1280Claude Code 仅从机器上的托管源尊重 [`forceLoginGatewayUrl`](/docs/zh-CN/settings-reference#forcelogingatewayurl)、[`gatewayInternalNetworks`](/docs/zh-CN/settings-reference#gatewayinternalnetworks) 和 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 的 `"gateway"` 值：`managed-settings.json`、macOS plist 或 Windows HKLM 注册表，或策略助手。在开发者自己的 `~/.claude/settings.json` 中设置它们或在网关有效负载中设置它们不会配置网关登录。

1281

1282不要在有效负载中包含 `forceLoginMethod` 和 `forceLoginOrgUUID`。Claude Code 仍然从有效负载中读取这两个密钥以进行启动凭证检查，因此在机器上保留 Anthropic 颁发的凭证的开发者会获得[管理员策略需要云网关登录](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)下描述的启动退出，即使他们已经登录。

1235 1283

1236<h2 id="related">1284<h2 id="related">

1237 相关1285 相关

claude-apps-gateway-deploy.md +15 −3

Details

181 健康181 健康

182</h3>182</h3>

183 183

184网关提供 `GET /healthz` 作为活跃探针，`GET /readyz` 作为就绪探针；`/readyz` 验证存储是否可达。两者都免除 `access_control.allow_cidrs`，因此探针在锁定的监听器上继续工作。184网关提供 `GET /healthz` 作为活跃探针和 `GET /readyz` 作为就绪探针。`/readyz` 验证存储是否可达。如果您设置了 [`store.readiness_grace_seconds`](/docs/zh-CN/claude-apps-gateway-config#store)，`/readyz` 在存储停止应答后最多继续报告就绪达到那么多秒。

185

186两个端点都免除 `access_control.allow_cidrs`，因此探针在锁定的监听器上继续工作。

185 187

186`/.well-known/oauth-authorization-server` 处的 OAuth 发现文档也仅在配置加载、OIDC 发现、上游客户端构造和 Postgres 迁移全部成功后才返回 `200`，因此它也充当端到端启动检查。188`/.well-known/oauth-authorization-server` 处的 OAuth 发现文档也仅在配置加载、OIDC 发现、上游客户端构造和 Postgres 迁移全部成功后才返回 `200`，因此它也充当端到端启动检查。

187 189

217* **现有会话**：持有者令牌使用 JWT 密钥在本地验证，会话刷新不接触存储，网关进程仍然可以提供推理219* **现有会话**：持有者令牌使用 JWT 密钥在本地验证，会话刷新不接触存储，网关进程仍然可以提供推理

218* **新登录**：失败直到 Postgres 恢复，因为设备流及其速率限制计数器存在于 Postgres 中220* **新登录**：失败直到 Postgres 恢复，因为设备流及其速率限制计数器存在于 Postgres 中

219* **[支出限制执行](/docs/zh-CN/claude-apps-gateway-spend-limits#postgres-availability)**：在中断期间默认失败开放，因此推理仍然流动；如果您宁愿阻止而不是无计量运行，将其翻转为失败关闭221* **[支出限制执行](/docs/zh-CN/claude-apps-gateway-spend-limits#postgres-availability)**：在中断期间默认失败开放，因此推理仍然流动；如果您宁愿阻止而不是无计量运行，将其翻转为失败关闭

220* **就绪**：`/readyz` 在中断期间报告未就绪，因此在就绪上门控流量的编排器一次从轮换中移除每个副本。在该拓扑中，所有流量，包括网关仍然可以提供的推理，在负载均衡器处失败，直到 Postgres 恢复。`/healthz` 上的活跃探针继续通过，因此副本不会重新启动。如果您宁愿已登录的开发者在存储中断期间继续工作，将就绪探针指向 `/healthz`；成本是新登录失败，反对仍然报告就绪的副本。222* **就绪**：默认情况下，`/readyz` 在 Postgres 无法访问时立即报告未就绪，因此每个副本一次失败其就绪检查。在流量仅到达通过检查的副本的地方，所有流量，包括网关仍然可以提供的推理，在 Postgres 恢复前失败。`/healthz` 上的活跃探针在整个过程中继续通过。

223

224如果您的 IdP 宕机，现有会话工作直到 `ttl_hours`，新登录失败。会话刷新获得重试答案并在 IdP 恢复后成功。如果您的 IdP 有频繁的维护窗口，设置更长的 `ttl_hours`。

225

226<h4 id="readiness-grace-period">

227 就绪宽限期

228</h4>

229

230要让已登录的开发者在短 Postgres 中断（如数据库故障转移）期间继续工作，将 [`store.readiness_grace_seconds`](/docs/zh-CN/claude-apps-gateway-config#store) 设置为比故障转移花费的时间更长，例如 `300`。启用支出限制并使用默认失败开放行为，通过保持就绪的副本的请求在 Postgres 恢复前无计量，因此将值保持为低至覆盖您的故障转移。如果您设置了 [`enforcement.fail_closed_on_error: true`](/docs/zh-CN/claude-apps-gateway-config#enforcement)，网关拒绝已登录开发者的推理，带有 `429` `spend limit unavailable` 消息，直到 Postgres 恢复，即使副本仍然通过其就绪检查。

231

232该设置需要网关服务器上的 Claude Code v2.1.282 或更高版本。较早的网关在找到密钥时拒绝启动，因此在添加它之前升级每个副本。[升级](#upgrades) 涵盖回滚。

221 233

222如果您的 IdP 宕机，现有会话工作直到 `ttl_hours`，新登录失败，会话刷新获得重试答案并在 IdP 恢复后进行一次。如果您的 IdP 有频繁的维护窗口，设置更长的 `ttl_hours`。234如果您将就绪探针指向 `/healthz` 而不是，副本也在中断期间继续通过它，但 `/healthz` 永远不报告未就绪，因此 Postgres 连接未恢复的副本继续通过。

223 235

224<h3 id="jwt-secret-rotation">236<h3 id="jwt-secret-rotation">

225 JWT 密钥轮换237 JWT 密钥轮换

claude-apps-gateway-on-aws.md +2 −1

Details

255 255

256 store:256 store:

257 postgres_url: ${GATEWAY_POSTGRES_URL} # EKS: ${file:/secrets/postgres-url}257 postgres_url: ${GATEWAY_POSTGRES_URL} # EKS: ${file:/secrets/postgres-url}

258 # readiness_grace_seconds: 300 # 通过 RDS 故障转移保持通过健康检查

258 259

259 upstreams:260 upstreams:

260 - provider: bedrock261 - provider: bedrock

423 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"424 --load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"

424 ```425 ```

425 426

426 60 秒的宽限期给冷任务时间拉取镜像、连接到存储并在 ECS 开始计算针对部署的失败之前回答其第一个健康检查。目标组对 `GET /readyz` 的健康检查验证存储是否可达，因此无法到达 Postgres 的任务永远不会进入轮换；有关权衡和 `/healthz` 替代方案，请参阅[中断行为](/docs/zh-CN/claude-apps-gateway-deploy#outage-behavior)。427 60 秒的宽限期给冷任务时间拉取镜像、连接到存储并在 ECS 开始计算针对部署的失败之前回答其第一个健康检查。目标组对 `GET /readyz` 的健康检查验证存储是否可达，因此无法到达 Postgres 的任务永远不会进入轮换。要通过短数据库中断（例如 RDS 故障转移）保持任务通过检查，请按照[中断行为](/docs/zh-CN/claude-apps-gateway-deploy#outage-behavior)中所述设置 `store.readiness_grace_seconds`，其中也涵盖了 `/healthz` 替代方案。

427 428

428 任务在私有子网中运行，没有公共 IP，因此所有出站（到 Bedrock、您的 IdP、Secrets Manager、ECR 和 CloudWatch Logs）都通过 NAT 网关。要将 Bedrock 流量保持在公共路径之外，创建一个 `bedrock-runtime` 接口 VPC 端点并将上游的 `base_url` 指向它，如 [Bedrock 上游参考](/docs/zh-CN/claude-apps-gateway-config#amazon-bedrock)所示；IdP 仍然需要互联网出站。429 任务在私有子网中运行，没有公共 IP，因此所有出站（到 Bedrock、您的 IdP、Secrets Manager、ECR 和 CloudWatch Logs）都通过 NAT 网关。要将 Bedrock 流量保持在公共路径之外，创建一个 `bedrock-runtime` 接口 VPC 端点并将上游的 `base_url` 指向它，如 [Bedrock 上游参考](/docs/zh-CN/claude-apps-gateway-config#amazon-bedrock)所示；IdP 仍然需要互联网出站。

429 430

claude-apps-gateway-on-gcp.md +2 −0

Details

179 179

180 store:180 store:

181 postgres_url: ${GATEWAY_POSTGRES_URL} # GKE: ${file:/secrets/postgres-url}181 postgres_url: ${GATEWAY_POSTGRES_URL} # GKE: ${file:/secrets/postgres-url}

182 # readiness_grace_seconds: 300 # 在 Cloud SQL 故障转移期间

183 # 保持通过就绪探针

182 184

183 upstreams:185 upstreams:

184 - provider: vertex186 - provider: vertex

claude-apps-gateway-spend-limits.md +2 −0

Details

86 86

87预检查使用两秒超时查询 Postgres。如果存储无法访问或超时，执行默认情况下失败打开：请求继续，网关记录警告，响应不包含 `anthropic-ratelimit-unified-*` 标头。设置 [`enforcement.fail_closed_on_error: true`](/docs/zh-CN/claude-apps-gateway-config#enforcement) 改为失败关闭，它返回相同的 `429 billing_error`，但消息为 `spend limit unavailable`，没有期间、重置时间或 `retry-after` 标头。失败打开防止存储中断成为推理中断；失败关闭保证没有无计量支出。87预检查使用两秒超时查询 Postgres。如果存储无法访问或超时，执行默认情况下失败打开：请求继续，网关记录警告，响应不包含 `anthropic-ratelimit-unified-*` 标头。设置 [`enforcement.fail_closed_on_error: true`](/docs/zh-CN/claude-apps-gateway-config#enforcement) 改为失败关闭，它返回相同的 `429 billing_error`，但消息为 `spend limit unavailable`，没有期间、重置时间或 `retry-after` 标头。失败打开防止存储中断成为推理中断；失败关闭保证没有无计量支出。

88 88

89失败打开仅在你的负载均衡器或编排器仍然将流量路由到网关时有帮助。有关 `store.readiness_grace_seconds` 的信息，请参阅 [Outage behavior](/docs/zh-CN/claude-apps-gateway-deploy#outage-behavior)，它使副本在短暂中断期间通过其就绪检查。

89<h3 id="usage-warnings-in-claude-code">91<h3 id="usage-warnings-in-claude-code">

90 Claude Code 中的使用警告92 Claude Code 中的使用警告

91</h3>93</h3>

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

Details

4 4

5# 在云端使用 Claude Code5# 在云端使用 Claude Code

6 6

~~7> 从浏览器、手机、桌面应用或终端在云端运行 Claude Code 会话，使用 --cloud 和 --teleport 移动会话，以及自动修复拉取请求。~~7> 从浏览器、手机、桌面应用或终端在云端运行 Claude Code 会话，使用 `--cloud` 和 `--teleport` 移动会话，以及自动修复拉取请求。

8 8

9<Note>9<Note>

10 云会话在 Pro、Max 和 Team 计划上可用，以及拥有高级席位或 Chat + Claude Code 席位的 Enterprise 用户。10 云会话在 Pro、Max 和 Team 计划上可用，以及拥有高级席位或 Chat + Claude Code 席位的 Enterprise 用户。

61 61

62[项目](/docs/zh-CN/claude-projects)中的线程需要在每个克隆的存储库上安装 Claude GitHub App，无论你使用哪种连接方法。请参阅[设置 GitHub 访问权限](/docs/zh-CN/claude-projects#set-up-github-access)。62[项目](/docs/zh-CN/claude-projects)中的线程需要在每个克隆的存储库上安装 Claude GitHub App，无论你使用哪种连接方法。请参阅[设置 GitHub 访问权限](/docs/zh-CN/claude-projects#set-up-github-access)。

63 63

64在 Anthropic 托管的环境中，你的 GitHub 凭证在 Anthropic 的服务器上保持加密状态，永远不会进入会话的虚拟机。来自虚拟机的 GitHub 操作通过 [GitHub 代理](/docs/zh-CN/cloud-environments#github-proxy)进行，它在服务器端附加凭证。

64有关 `/schedule` 如何在创建 routine 之前检查存储库访问权限，请参阅[存储库和分支权限](/docs/zh-CN/routines#repositories-and-branch-permissions)。有关 `/web-setup` 演练（包括 `/web-setup` 存储的内容以及如何删除它），请参阅[从终端连接](/docs/zh-CN/web-quickstart#connect-from-your-terminal)。66有关 `/schedule` 如何在创建 routine 之前检查存储库访问权限，请参阅[存储库和分支权限](/docs/zh-CN/routines#repositories-and-branch-permissions)。有关 `/web-setup` 演练（包括 `/web-setup` 存储的内容以及如何删除它），请参阅[从终端连接](/docs/zh-CN/web-quickstart#connect-from-your-terminal)。

65 67

66快速网络设置是一个组织设置，允许成员使用 `/web-setup` 连接 GitHub，在浏览器入门期间跳过 Claude GitHub App 安装提示，并让浏览器入门为他们创建[**默认**环境](/docs/zh-CN/cloud-environments#the-default-environment)，而不是显示环境表单。在 Team 和 Enterprise 计划上，默认情况下它是关闭的，这会隐藏 `/web-setup`。[所有者](/docs/zh-CN/server-managed-settings#access-control)可以在 [**Admin settings > Claude Code**](https://claude.ai/admin-settings/claude-code) 处使用**快速网络设置**切换来打开它。68快速网络设置是一个组织设置，允许成员使用 `/web-setup` 连接 GitHub，在浏览器入门期间跳过 Claude GitHub App 安装提示，并让浏览器入门为他们创建[**默认**环境](/docs/zh-CN/cloud-environments#the-default-environment)，而不是显示环境表单。在 Team 和 Enterprise 计划上，默认情况下它是关闭的，这会隐藏 `/web-setup`。[所有者](/docs/zh-CN/server-managed-settings#access-control)可以在 [**Admin settings > Claude Code**](https://claude.ai/admin-settings/claude-code) 处使用**快速网络设置**切换来打开它。

135 137

136当您从没有 git 远程的存储库运行 `claude --cloud` 时，或从 Claude GitHub App 未安装的 github.com 存储库运行时，Claude Code 会捆绑您的本地存储库并直接上传到云会话。即使您使用 `/web-setup` 连接了 GitHub，这也适用。该捆绑包包括您在所有分支上的完整存储库历史记录，加上对跟踪文件的未提交更改。138当您从没有 git 远程的存储库运行 `claude --cloud` 时，或从 Claude GitHub App 未安装的 github.com 存储库运行时，Claude Code 会捆绑您的本地存储库并直接上传到云会话。即使您使用 `/web-setup` 连接了 GitHub，这也适用。该捆绑包包括您在所有分支上的完整存储库历史记录，加上对跟踪文件的未提交更改。

137 139

138在 macOS、Linux 和 WSL 上，Claude Code 将未提交的更改排除在上传之外，这些更改涉及名称类似于凭据或密钥的文件，并命名它排除的文件。这涵盖 `.env` 文件、Terraform `*.tfvars` 文件和密钥文件，例如 `id_rsa` 和 `*.pem`。会话以每个文件的已提交版本启动，或如果未提交任何内容，则不包含该文件。在链接的 worktree、子模块或类似布局中，Claude Code 会与其余部分一起上传这些更改并命名它上传的文件。140在 macOS、Linux 和 WSL 上，Claude Code 将未提交的更改排除在上传之外，这些更改涉及名称类似于凭据或密钥的文件，并命名它排除的文件。这涵盖 `.env` 文件、Terraform `*.tfvars` 文件和密钥文件，例如 `id_rsa` 和 `*.pem`。会话以每个文件的已提交版本启动，或如果未提交任何内容，则不包含该文件。

139 141

140要在 Claude Code 会克隆远程时上传捆绑包，请设置 `CCR_FORCE_BUNDLE=1`：142要在 Claude Code 会克隆远程时上传捆绑包，请设置 `CCR_FORCE_BUNDLE=1`：

141 143

429在依赖云会话进行工作流之前，请考虑这些约束：431在依赖云会话进行工作流之前，请考虑这些约束：

430 432

431* **速率限制**：云会话与你账户内所有其他 Claude 和 Claude Code 使用共享速率限制。并行运行多个任务会按比例消耗更多速率限制。云 VM 没有单独的计算费用。433* **速率限制**：云会话与你账户内所有其他 Claude 和 Claude Code 使用共享速率限制。并行运行多个任务会按比例消耗更多速率限制。云 VM 没有单独的计算费用。

434* **时间限制**：Claude 运行的命令和 SessionStart hooks 有你可以更改的默认超时，设置脚本仅在大约五分钟内完成时才被缓存。请参阅[时间限制](/docs/zh-CN/cloud-environments#time-limits)

432* **存储库身份验证**：你只能在认证到相同账户时将云会话拉入你的终端435* **存储库身份验证**：你只能在认证到相同账户时将云会话拉入你的终端

433* **平台限制**：存储库克隆和拉取请求创建需要 GitHub。自托管[GitHub Enterprise Server](/docs/zh-CN/github-enterprise-server) 实例支持 Team 和 Enterprise 计划。你可以通过设置 `CCR_FORCE_BUNDLE=1` 将 GitLab、Bitbucket 或其他非 GitHub 存储库作为[本地捆绑](#send-local-repositories-without-github)发送到云会话，但会话无法将结果推送回该远程436* **平台限制**：存储库克隆和拉取请求创建需要 GitHub。自托管[GitHub Enterprise Server](/docs/zh-CN/github-enterprise-server) 实例支持 Team 和 Enterprise 计划。你可以通过设置 `CCR_FORCE_BUNDLE=1` 将 GitLab、Bitbucket 或其他非 GitHub 存储库作为[本地捆绑](#send-local-repositories-without-github)发送到云会话，但会话无法将结果推送回该远程

434* **组织 IP 允许列表**：云会话从 Anthropic 管理的基础设施而不是你的网络调用 Anthropic API，而[自托管环境](/docs/zh-CN/self-hosted-environments)中的会话从你自己的网络调用它。如果你的组织启用了 [IP 允许列表](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting)，每个 Anthropic 托管的云会话都会失败，显示身份验证错误。这同样适用于[代码审查](/docs/zh-CN/code-review)和在 Anthropic 托管的环境中运行的[routines](/docs/zh-CN/routines)；路由到自托管环境的 routine 从你自己的网络调用 API。联系 [Anthropic 支持](https://support.claude.com/)以从你的组织的 IP 允许列表中豁免 Anthropic 托管的服务。437* **组织 IP 允许列表**：云会话从 Anthropic 管理的基础设施而不是你的网络调用 Anthropic API，而[自托管环境](/docs/zh-CN/self-hosted-environments)中的会话从你自己的网络调用它。如果你的组织启用了 [IP 允许列表](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting)，每个 Anthropic 托管的云会话都会失败，显示身份验证错误。这同样适用于[代码审查](/docs/zh-CN/code-review)和在 Anthropic 托管的环境中运行的[routines](/docs/zh-CN/routines)；路由到自托管环境的 routine 从你自己的网络调用 API。联系 [Anthropic 支持](https://support.claude.com/)以从你的组织的 IP 允许列表中豁免 Anthropic 托管的服务。

claude-directory.md +24 −2

Details

1555| `projects/<project>/<session>.orphaned-<timestamp>-<suffix>.jsonl`、`projects/<project>/<session>.jsonl.superseded-<timestamp>` | 会话的先前记录，Claude Code 将其搁置而不是覆盖或删除它。它不会出现在会话选择器中 |1555| `projects/<project>/<session>.orphaned-<timestamp>-<suffix>.jsonl`、`projects/<project>/<session>.jsonl.superseded-<timestamp>` | 会话的先前记录，Claude Code 将其搁置而不是覆盖或删除它。它不会出现在会话选择器中 |

1558| `file-history/<session>/` | Claude 更改的文件的编辑前快照，用于 [checkpoint 恢复](/docs/zh-CN/checkpointing)。保存最近 100 个 checkpoint 的快照；没有保留 checkpoint 引用的快照文件被删除，除了每个文件的第一个快照 |1558| `file-history/<session>/` | Claude 更改的文件的编辑前快照，用于 [checkpoint 恢复](/docs/zh-CN/checkpointing)。保存最近 100 个 checkpoint 的快照；没有保留 checkpoint 引用的快照文件被删除，除了每个文件的第一个快照 |

1582* **Bare mode**：当您使用 [`--bare`](/docs/zh-CN/headless#start-faster-with-bare-mode) 运行 `claude -p` 时，Claude Code 不会在该会话中运行扫描。1582* **Bare mode**：当您使用 [`--bare`](/docs/zh-CN/headless#start-faster-with-bare-mode) 运行 `claude -p` 时，Claude Code 不会在该会话中运行扫描。

1583* **暂停扫描**：如果 Claude Code 无法安全地确定保留期，它会暂停保留清理扫描；[`retention_sweep` 事件](/docs/zh-CN/monitoring-usage#retention-sweep-event)列出每个暂停它的配置。当原因是无法读取或解析的设置文件，或 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 明确设置的设置错误时，Claude Code 也会在 `/status` 中显示警告，直到您修复设置错误。当 [managed settings](/docs/zh-CN/server-managed-settings) 提供 `cleanupPeriodDays` 时，Claude Code 在任何情况下都以 managed 值运行扫描。1583* **暂停扫描**：如果 Claude Code 无法安全地确定保留期，它会暂停保留清理扫描；[`retention_sweep` 事件](/docs/zh-CN/monitoring-usage#retention-sweep-event)列出每个暂停它的配置。当原因是无法读取或解析的设置文件，或 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 明确设置的设置错误时，Claude Code 也会在 `/status` 中显示警告，直到您修复设置错误。当 [managed settings](/docs/zh-CN/server-managed-settings) 提供 `cleanupPeriodDays` 时，Claude Code 在任何情况下都以 managed 值运行扫描。

1584 1584

1585<h3 id="session-scratchpad-directory">

1586 会话暂存目录

1587</h3>

1588

1589暂存是 Claude Code 为 Claude 提供的每个会话目录，用于临时文件：中间结果、辅助脚本和不属于您的项目的草稿。当 Claude 说它将某些内容保存"到暂存"时，该文件就在那里。Claude 使用它而不是 `/tmp`，可以在其中创建、编辑和读取文件而无需权限提示。

1590

1591暂存位于 Claude Code 的临时目录下，而不是 `~/.claude`。找到您的平台的当前会话路径：

1592

1593* **macOS**：`/private/tmp/claude-<uid>/<project>/<session-id>/scratchpad/`

1594* **Linux**：`/tmp/claude-<uid>/<project>/<session-id>/scratchpad/`，或当您的系统设置 `$TMPDIR` 时在其下的相同形状

1595* **Windows**：`%TEMP%\claude\<project>\<session-id>\scratchpad\`

1596

1597`<project>` 是您的工作目录路径，其中除字母和数字外的每个字符都被替换为 `-`，例如 `-Users-you-my-project`。如果您设置了 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars)，树会改为移动到该目录下。Hooks 接收当前会话的路径作为 [`scratchpad_dir`](/docs/zh-CN/hooks#common-input-fields)。

1598

1599暂存文件的生命周期与会话的记录相同：[保留扫描](#cleaned-up-automatically)在删除记录时删除目录，[`claude project purge`](#clear-local-data) 不会触及临时目录。因为目录位于系统临时位置下，您的操作系统也可以清除它，例如在重启时。要保留 Claude 在那里写入的内容，请要求 Claude 将其移动到您的项目中。

1600

1601会话仅在以下所有条件成立时才有暂存：

1602

1603* 您使用 claude.ai 账户而不是 API 密钥登录

1604* 会话使用 Anthropic API，而不是 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry

1605* [`enableArtifact`](/docs/zh-CN/settings-reference#enableartifact) 未设置为 `false`

1606

1585<h3 id="kept-until-you-delete-them">1607<h3 id="kept-until-you-delete-them">

1586 保留直到您删除它们1608 保留直到您删除它们

1587</h3>1609</h3>

1626* `history.jsonl` 中的匹配提示行1648* `history.jsonl` 中的匹配提示行

1627* `~/.claude.json` 中的项目条目1649* `~/.claude.json` 中的项目条目

1628 1650

1629您在项目会话中粘贴或附加的图像存储在 Claude Code 的临时目录下，而不是 `~/.claude`，因此清除不会删除它们。[保留扫描](#cleaned-up-automatically)会在它们的年龄超过 `cleanupPeriodDays` 时删除它们。1651您在项目会话中粘贴或附加的图像以及每个会话的 [暂存](#session-scratchpad-directory) 存储在 Claude Code 的临时目录下，而不是 `~/.claude`，因此清除不会删除它们。[保留扫描](#cleaned-up-automatically) 仍会在它们的年龄超过 `cleanupPeriodDays` 时删除图像；清除的会话的暂存会保留，直到您删除它或您的操作系统清除临时目录。

1630 1652

1631该命令打印完整的删除计划，并在删除任何内容之前要求确认。1653该命令打印完整的删除计划，并在删除任何内容之前要求确认。

1632 1654

claude-projects.md +46 −4

Details

12 12

13项目是一个持续进行的对话，Claude 在其中为您协调一系列相关工作。您告诉它需要做什么，它为每个任务启动一个线程。13项目是一个持续进行的对话，Claude 在其中为您协调一系列相关工作。您告诉它需要做什么，它为每个任务启动一个线程。

14 14

15每个线程通常是一个[云会话](/docs/zh-CN/claude-code-on-the-web)：Claude Code 在云中运行，而不是在您的机器上运行。当任务需要只有您的计算机才有的东西时，您可以要求 Claude 通过[远程控制](/docs/zh-CN/remote-control)在您的计算机上运行该线程。线程并行运行，您可以从手机上检查它们并引导它们。云线程在您关闭笔记本电脑后会继续进行。15每个线程通常是一个[云会话](/docs/zh-CN/claude-code-on-the-web)：Claude Code 在云中运行，而不是在您的机器上运行。当任务需要只有您的计算机才有的东西时，您可以要求 Claude 通过[远程控制](/docs/zh-CN/remote-control)在您的计算机上[运行该线程](#run-a-thread-on-your-own-computer)。线程并行运行，您可以从手机上检查它们并引导它们。云线程在您关闭笔记本电脑后会继续进行，而您计算机上的线程仅在该计算机处于唤醒状态时运行。

16 16

17没有项目的情况下，运行多个会话意味着您自己进行协调：您决定每个会话处理什么，在每个会话的开始重复相同的背景信息，并检查哪个已完成或需要您的回答。使用项目，您可以：17没有项目的情况下，运行多个会话意味着您自己进行协调：您决定每个会话处理什么，在每个会话的开始重复相同的背景信息，并检查哪个已完成或需要您的回答。使用项目，您可以：

18 18

39 何时其他方式更合适39 何时其他方式更合适

40</h3>40</h3>

41 41

42Cloud 线程在 GitHub 代码库以及您上传到项目的文件、文件夹和 Google Drive 文件夹上工作，而不是仅存在于您机器上的文件或工具。如果任务需要您的机器，请通过 [Remote Control](/docs/zh-CN/remote-control) 要求 Claude 在那里运行其线程。[限制](#limitations)列出了这需要什么。在这些情况下，其他方式更合适：42项目仍然适用于仅某些任务需要您的机器的情况。Cloud 线程在 GitHub 代码库以及您上传到项目的文件、文件夹和 Google Drive 文件夹上工作，对于偶尔需要本地数据库或您计算机上的工具的任务，您可以要求 Claude [在您自己的计算机上运行该任务的线程](#run-a-thread-on-your-own-computer)。在这些情况下，项目以外的方式更合适：

43 43

44* **一个适合在一个会话中完成的任务**："修复不稳定的登录测试。"自己启动一个[云会话](/docs/zh-CN/claude-code-on-the-web)。44* **一个适合在一个会话中完成的任务**："修复不稳定的登录测试。"自己启动一个[云会话](/docs/zh-CN/claude-code-on-the-web)。

45* **每个任务都需要您的机器的工作**：本地数据库、设备模拟器或 VPN 后面的 API。使用本地会话，或[代理视图](/docs/zh-CN/agent-view)同时运行多个。如果工作只需要本地文件，请将它们上传到项目。45* **每个任务都需要您的机器的工作**：本地数据库、设备模拟器或 VPN 后面的 API。使用本地会话，或[代理视图](/docs/zh-CN/agent-view)同时运行多个。如果工作只需要本地文件，请将它们上传到项目。

277 277

278每个批准涵盖该提示，或如果你选择更广泛的选项，则涵盖该线程的其余部分。要让每个线程运行某些命令而不询问，或阻止某些命令，请将[权限规则](/docs/zh-CN/permissions)添加到存储库的`.claude/settings.json`。云线程仅在具有一个存储库的项目中应用它们；请参阅[线程从你的存储库中获取什么](#what-threads-pick-up-from-your-repositories)。278每个批准涵盖该提示，或如果你选择更广泛的选项，则涵盖该线程的其余部分。要让每个线程运行某些命令而不询问，或阻止某些命令，请将[权限规则](/docs/zh-CN/permissions)添加到存储库的`.claude/settings.json`。云线程仅在具有一个存储库的项目中应用它们；请参阅[线程从你的存储库中获取什么](#what-threads-pick-up-from-your-repositories)。

279 279

280<h3 id="run-a-thread-on-your-own-computer">

281 在你自己的计算机上运行线程

282</h3>

283

284当任务需要只有你的计算机才有的东西，例如本地数据库、设备模拟器或 VPN 后面的 API 时，要求 Claude 在你的计算机上而不是在云中运行该任务的线程。当你在项目对话中要求时，线程是你机器上文件夹中的 Claude Code 会话，通过[远程控制](/docs/zh-CN/remote-control)连接。项目的其他线程继续在云中运行。与云线程相比，在你的计算机上运行的线程：

285

286* 使用该机器上的文件、工具、MCP 服务器和 Claude Code 设置，而不是项目的云环境

287* 从项目的说明开始，但不加载其内存文件

288* 仅在该计算机处于唤醒状态且远程控制打开时运行

289

290<Steps>

291 <Step title="连接文件夹">

292 在具有任务需要的文件夹的计算机上，通过以下两种方式之一通过远程控制使其可用。两者都需要该计算机上的 Claude Code v2.1.280 或更高版本。

293

294 * **在 Claude 桌面应用中**：打开**设置 > Claude Code**，打开**从你的手机和 claude.ai 使用此计算机**，并将文件夹添加到该开关下的列表中。当应用打开时，线程可以在此计算机上运行。

295 * **在终端中**：在文件夹中运行`claude remote-control`并让其保持运行。

296 </Step>

297

298 <Step title="使用本地工作要求任务">

299 在项目对话中，从消息框旁边的\*\*+**菜单中选择**本地工作\*\*，它会标记你的消息为**本地**，并写下你想要完成的内容。在消息中说任务应该在你的计算机上运行也可以。

300 </Step>

301

302 <Step title="在卡片上允许它">

303 Claude 会回答一张**允许 Claude 在你的设备上的文件夹中工作**卡片。如果你连接了多个，请选择文件夹。然后点击**允许一次**。

304 </Step>

305</Steps>

306

307线程在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中运行，因此 Claude 在该文件夹中运行命令和编辑文件而不每次都询问你。如果自动模式在该计算机的 Claude Code 中不可用或已关闭，线程在没有它的情况下运行，它引发的任何权限提示都会在线程中等待你的答案，如[解除等待批准的线程](#unblock-a-thread-waiting-on-approval)所述。

308

309当线程运行时，其标题中的笔记本电脑图标显示你的计算机是否已连接。点击它可以查看线程使用的文件夹或关闭连接。当该计算机处于睡眠状态时线程暂停，如果桌面应用或`claude remote-control`退出则停止。[失去与你的文件夹的联系](#lost-contact-with-your-folder)涵盖了让它再次运行。在桌面应用中，在**设置 > Claude Code**下打开**为远程控制保持此计算机唤醒**以阻止计算机自动睡眠。

310

311当[**需要受信任的设备**](/docs/zh-CN/remote-control#trusted-devices)对你的账户打开时，项目无法在你的计算机上运行线程。

312

280<h2 id="give-a-project-standing-context">313<h2 id="give-a-project-standing-context">

281 给项目提供常规上下文314 给项目提供常规上下文

282</h2>315</h2>

441* **Claude Tag**：[Claude Tag](https://claude.com/docs/claude-tag/overview) 是您团队 Slack 频道中的 Claude，在 Team 和 Enterprise 计划上。频道中的任何人都可以给它工作，频道中的每个人都看到并引导它，它使用管理员为该频道设置的连接。项目是您的：您是唯一给它工作或看到其线程的人，它使用您自己的 GitHub 访问和连接器，它在 Pro 和 Max 上。[Claude Tag 与 Cowork 和 Claude Code 的不同之处](https://claude.com/docs/claude-tag/concepts/how-it-works#how-claude-tag-differs-from-cowork-and-claude-code)有并排比较。474* **Claude Tag**：[Claude Tag](https://claude.com/docs/claude-tag/overview) 是您团队 Slack 频道中的 Claude，在 Team 和 Enterprise 计划上。频道中的任何人都可以给它工作，频道中的每个人都看到并引导它，它使用管理员为该频道设置的连接。项目是您的：您是唯一给它工作或看到其线程的人，它使用您自己的 GitHub 访问和连接器，它在 Pro 和 Max 上。[Claude Tag 与 Cowork 和 Claude Code 的不同之处](https://claude.com/docs/claude-tag/concepts/how-it-works#how-claude-tag-differs-from-cowork-and-claude-code)有并排比较。

442* **云会话**：每个线程都是一个[云会话](/docs/zh-CN/claude-code-on-the-web)，除非您要求 Claude 在您的机器上运行它。无论哪种方式，Claude 启动和跟踪它而不是您。您自己启动的云会话可以通过[**Continue as a project** 或 **Move to project**](#start-from-an-existing-cloud-session)成为项目或提供一个。475* **云会话**：每个线程都是一个[云会话](/docs/zh-CN/claude-code-on-the-web)，除非您要求 Claude 在您的机器上运行它。无论哪种方式，Claude 启动和跟踪它而不是您。您自己启动的云会话可以通过[**Continue as a project** 或 **Move to project**](#start-from-an-existing-cloud-session)成为项目或提供一个。

443* **例程**：当您在项目中要求计划工作时，Claude 创建一个[例程](/docs/zh-CN/routines)，作为该项目中的线程运行，并出现在其 **Routines** 标签页上。您在项目外创建的例程继续自己工作。476* **例程**：当您在项目中要求计划工作时，Claude 创建一个[例程](/docs/zh-CN/routines)，作为该项目中的线程运行，并出现在其 **Routines** 标签页上。您在项目外创建的例程继续自己工作。

444* **本地会话和代理视图**：您在终端、IDE 或桌面应用的本地环境中启动的会话不能添加到项目中。项目通过[Remote Control](/docs/zh-CN/remote-control)运行线程到达您的机器。[代理视图](/docs/zh-CN/agent-view)是用于跟踪您自己启动的多个本地会话的屏幕；它没有协调员。477* **Remote Control**：[Remote Control](/docs/zh-CN/remote-control) 连接 claude.ai 到在您的机器上运行的 Claude Code 会话。当您在项目中要求 Claude 在您的计算机上运行线程时，项目[使用 Remote Control 来执行](#run-a-thread-on-your-own-computer)。

478* **本地会话和代理视图**：您在终端、IDE 或桌面应用的本地环境中启动的会话不能添加到项目中。[代理视图](/docs/zh-CN/agent-view)是用于跟踪多个本地会话并排的屏幕，您仍然启动每个会话并自己给它分配任务。

445* **Worktrees**：一个[worktree](/docs/zh-CN/worktrees)为每个本地会话提供其自己的代码库工作副本，因此您机器上的并行会话不会相互覆盖。云线程不需要它们：每个线程将其代码库克隆到其自己的云沙箱中，并在其自己的分支上工作。479* **Worktrees**：一个[worktree](/docs/zh-CN/worktrees)为每个本地会话提供其自己的代码库工作副本，因此您机器上的并行会话不会相互覆盖。云线程不需要它们：每个线程将其代码库克隆到其自己的云沙箱中，并在其自己的分支上工作。

446* **代理团队**：一个[代理团队](/docs/zh-CN/agent-teams)是一个会话，为单个任务启动队友会话，在您的机器上或在云会话内，并以该任务结束。480* **代理团队**：一个[代理团队](/docs/zh-CN/agent-teams)是一个会话，为单个任务启动队友会话，在您的机器上或在云会话内，并以该任务结束。

447* **claude.ai 聊天和 Cowork 中的 Projects**：[早期的 Projects 体验](https://support.claude.com/en/articles/9517075-what-are-projects)，对对话和参考文件进行分组，没有线程或协调员。这些项目继续按照今天的方式工作，直到重新设计的体验到达它们。481* **claude.ai 聊天和 Cowork 中的 Projects**：[早期的 Projects 体验](https://support.claude.com/en/articles/9517075-what-are-projects)，对对话和参考文件进行分组，没有线程或协调员。这些项目继续按照今天的方式工作，直到重新设计的体验到达它们。

454 488

455* Projects 在 claude.ai/code、桌面应用和 Claude 移动应用中可用，不在终端 CLI 或通过 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 中。CLI 的 [`claude project`](/docs/zh-CN/cli-reference) 命令（它管理目录的本地 Claude Code 状态）是无关的。489* Projects 在 claude.ai/code、桌面应用和 Claude 移动应用中可用，不在终端 CLI 或通过 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 中。CLI 的 [`claude project`](/docs/zh-CN/cli-reference) 命令（它管理目录的本地 Claude Code 状态）是无关的。

456* 项目线程是[云会话](/docs/zh-CN/claude-code-on-the-web)，或通过[远程控制](/docs/zh-CN/remote-control)在您自己的机器上的会话，两种情况下 Anthropic 都是模型提供者。[安全](/docs/zh-CN/security)和[数据使用](/docs/zh-CN/data-usage)涵盖了云会话如何隔离以及保留什么，[连接和安全](/docs/zh-CN/remote-control#connection-and-security)涵盖了您机器上的线程如何连接以及存储什么。490* 项目线程是[云会话](/docs/zh-CN/claude-code-on-the-web)，或通过[远程控制](/docs/zh-CN/remote-control)在您自己的机器上的会话，两种情况下 Anthropic 都是模型提供者。[安全](/docs/zh-CN/security)和[数据使用](/docs/zh-CN/data-usage)涵盖了云会话如何隔离以及保留什么，[连接和安全](/docs/zh-CN/remote-control#connection-and-security)涵盖了您机器上的线程如何连接以及存储什么。

457* 您不能将自己在机器上启动的会话添加到项目中。要让项目在您的机器上运行线程，请通过[远程控制](/docs/zh-CN/remote-control#requirements)连接它应该工作的文件夹：在 Claude 桌面应用中的 **Settings > Claude Code** 下打开远程控制，或在文件夹中运行 `claude remote-control` 并让其保持运行。该机器需要 Claude Code v2.1.280 或更高版本。当您的 claude.ai 设置中的 **Require trusted devices** 打开时，项目也不能在您的机器上运行线程。491* 您不能将自己在机器上启动的会话添加到项目中。项目仅通过[在您自己的计算机上通过远程控制运行线程](#run-a-thread-on-your-own-computer)到达您的机器，该部分列出了它需要什么。

458* 云线程的沙箱在轮之间暂停，并在线程继续时恢复。如果沙箱无法恢复，线程从新克隆继续，因此未提交的更改可能会丢失。在长任务上，要求 Claude 提交和推送进行中的工作。492* 云线程的沙箱在轮之间暂停，并在线程继续时恢复。如果沙箱无法恢复，线程从新克隆继续，因此未提交的更改可能会丢失。在长任务上，要求 Claude 提交和推送进行中的工作。

459* 项目属于一个用户。您不能与另一个用户共享项目或其线程，线程记录没有其他云会话具有的共享选项。在测试版期间没有项目的组织级控制。493* 项目属于一个用户。您不能与另一个用户共享项目或其线程，线程记录没有其他云会话具有的共享选项。在测试版期间没有项目的组织级控制。

460* 线程属于启动它的一个项目。您不能将线程移动或复制到另一个项目，或将其移出以独立存在。[**Move to project**](#start-from-an-existing-cloud-session)仅以另一种方式进行：它将云会话的工作带入项目。494* 线程属于启动它的一个项目。您不能将线程移动或复制到另一个项目，或将其移出以独立存在。[**Move to project**](#start-from-an-existing-cloud-session)仅以另一种方式进行：它将云会话的工作带入项目。

513 547

514线程或项目对话发出了您的计划仅用使用信用覆盖的请求，例如对您的计划不包括的模型或上下文大小的请求，并且使用信用未为您的账户打开。[将使用信用添加到您的订阅](/docs/zh-CN/costs#add-usage-credits-to-your-subscription)涵盖了谁可以在每个计划上打开或购买它们。一旦信用可用，发送另一条消息重试。548线程或项目对话发出了您的计划仅用使用信用覆盖的请求，例如对您的计划不包括的模型或上下文大小的请求，并且使用信用未为您的账户打开。[将使用信用添加到您的订阅](/docs/zh-CN/costs#add-usage-credits-to-your-subscription)涵盖了谁可以在每个计划上打开或购买它们。一旦信用可用，发送另一条消息重试。

515 549

550<h3 id="lost-contact-with-your-folder">

551 与您的文件夹失去联系

552</h3>

553

554在您的计算机上运行的线程在 Claude Code 会话停止响应时显示此消息，通常是因为计算机进入睡眠状态或桌面应用或 `claude remote-control` 退出。唤醒计算机，如果桌面应用或 `claude remote-control` 不再在那里运行，请重新启动它：重新打开应用并确认 **Use this computer from your phone and claude.ai** 仍在 **Settings > Claude Code** 下打开，或在同一文件夹中再次运行 `claude remote-control`。

555

516<h3 id="context-limit">556<h3 id="context-limit">

517 其他消息557 其他消息

518</h3>558</h3>

527| "The project's environment was removed" | 在 **Project settings > Environment** 中选择不同的环境；更改适用于新线程 |567| "The project's environment was removed" | 在 **Project settings > Environment** 中选择不同的环境；更改适用于新线程 |

528| "Setup script failed" | 点击错误上的 **Edit setup script**，在环境中修复脚本，然后发送另一条消息。[设置脚本失败](/docs/zh-CN/web-quickstart#setup-script-failed)列出常见原因 |568| "Setup script failed" | 点击错误上的 **Edit setup script**，在环境中修复脚本，然后发送另一条消息。[设置脚本失败](/docs/zh-CN/web-quickstart#setup-script-failed)列出常见原因 |

529| "Claude ran out of context on this turn" | 线程填满了其上下文窗口。如果消息说线程在新会话中继续，它自己继续；否则在项目对话中要求 Claude 为剩余工作启动新线程 |569| "Claude ran out of context on this turn" | 线程填满了其上下文窗口。如果消息说线程在新会话中继续，它自己继续；否则在项目对话中要求 Claude 为剩余工作启动新线程 |

570| "Couldn't start in" 后跟您的文件夹名称 | 您允许线程在您的计算机上运行，但会话无法在那里启动。当消息下的一行给出原因时，修复它，然后要求 Claude 再次运行任务 |

571| "Claude is out of date on your device" | 您选择运行线程的计算机具有比 v2.1.280 更旧的 Claude Code 版本。在那里更新 Claude Code，或如果这是连接文件夹的内容，则更新桌面应用，然后要求 Claude 再次运行任务 |

531 573

532<h2 id="related-resources">574<h2 id="related-resources">

cli-reference.md +5 −5

Details

27| `claude auth login` | 登录您的 Anthropic 账户。使用 `--email` 预填充您的电子邮件地址，使用 `--sso` 强制 SSO 身份验证，使用 `--console` 使用 Anthropic Console 登录以进行 API 使用计费而不是 Claude 订阅 | `claude auth login --console` |27| `claude auth login` | 登录您的 Anthropic 账户。使用 `--email` 预填充您的电子邮件地址，使用 `--sso` 强制 SSO 身份验证，使用 `--console` 使用 Anthropic Console 登录以进行 API 使用计费而不是 Claude 订阅 | `claude auth login --console` |

29| `claude auth status` | 以 JSON 格式显示身份验证状态。使用 `--text` 获取人类可读的输出。如果已登录，则以代码 0 退出，如果未登录，则以代码 1 退出 | `claude auth status` |29| `claude auth status` | 以 JSON 格式显示身份验证状态。使用 `--text` 获取人类可读的输出。如果已登录，则以代码 0 退出，如果未登录，则以代码 1 退出。JSON 包含一个 `configDirectory` 字段，命名 CLI 使用的 [配置目录](/docs/zh-CN/claude-directory)。该字段需要 Claude Code v2.1.268 或更高版本 | `claude auth status` |

30| `claude agents` | 打开 [agent view](/docs/zh-CN/agent-view) 以监控和分派并行后台会话。使用 `--cwd <path>` 仅显示在该目录下启动的会话，或使用 `--json` 将实时会话打印为 JSON 数组以供脚本使用（`--json --all` 也包括已完成的后台会话）。传递 `--permission-mode`、`--model`、`--effort` 或 `--agent` 以设置 [分派会话的默认值](/docs/zh-CN/agent-view#permission-mode-model-and-effort)。接受 `--settings`、`--add-dir`、`--plugin-dir` 和 `--mcp-config`，如顶级 `claude` 命令。打开 agent view 需要交互式终端 | `claude agents --json` |30| `claude agents` | 打开 [agent view](/docs/zh-CN/agent-view) 以监控和分派并行后台会话。使用 `--cwd <path>` 仅显示在该目录下启动的会话，或使用 `--json` 将实时会话打印为 JSON 数组以供脚本使用（`--json --all` 也包括已完成的后台会话）。传递 `--permission-mode`、`--model`、`--effort` 或 `--agent` 以设置 [分派会话的默认值](/docs/zh-CN/agent-view#permission-mode-model-and-effort)。接受 `--settings`、`--add-dir`、`--plugin-dir` 和 `--mcp-config`，如顶级 `claude` 命令。打开 agent view 需要交互式终端 | `claude agents --json` |

32| `claude auto-mode defaults` | 以 JSON 格式打印内置 [auto mode](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器规则。使用 `claude auto-mode config` 查看应用了设置的有效配置。`--label <prefix>` 仅打印标签以该前缀开头的规则，不区分大小写匹配。需要 Claude Code v2.1.208 或更高版本 | `claude auto-mode defaults --label 'Git Destructive'` |32| `claude auto-mode defaults` | 以 JSON 格式打印内置 [auto mode](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器规则。使用 `claude auto-mode config` 查看应用了设置的有效配置。`--label <prefix>` 仅打印标签以该前缀开头的规则，不区分大小写匹配。需要 Claude Code v2.1.208 或更高版本 | `claude auto-mode defaults --label 'Git Destructive'` |

64| `--add-dir` | 添加额外的工作目录供 Claude 读取和编辑文件。授予文件访问权限；Claude Code [不会发现](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)这些目录中的大多数 `.claude/` 配置。验证每个路径是否作为目录存在。您不能添加大多数[网络路径](/docs/zh-CN/errors#working-directory-is-a-network-path)，例如 `\\server\share`。要在会话之间保持这些目录，请在设置中设置 [`permissions.additionalDirectories`](/docs/zh-CN/settings-reference#permissions-additionaldirectories) | `claude --add-dir ../apps ../lib` |64| `--add-dir` | 添加额外的工作目录供 Claude 读取和编辑文件。授予文件访问权限；Claude Code [不会发现](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)这些目录中的大多数 `.claude/` 配置。验证每个路径是否作为目录存在。您不能添加大多数[网络路径](/docs/zh-CN/errors#working-directory-is-a-network-path)，例如 `\\server\share`。要在会话之间保持这些目录，请在设置中设置 [`permissions.additionalDirectories`](/docs/zh-CN/settings-reference#permissions-additionaldirectories) | `claude --add-dir ../apps ../lib` |

65| `--advisor <model>` | 使用模型别名 `fable`、`opus` 或 `sonnet`，或完整模型 ID 为此会话启用服务器端[顾问工具](/docs/zh-CN/advisor)。优先于会话的 `advisorModel` 设置。`fable` 需要[Fable 访问权限](/docs/zh-CN/advisor#choose-an-advisor-model) | `claude --advisor opus` |65| `--advisor <model>` | 使用模型别名 `fable`、`opus` 或 `sonnet`，或完整模型 ID 为此会话启用服务器端[顾问工具](/docs/zh-CN/advisor)。优先于会话的 `advisorModel` 设置。`fable` 需要[Fable 访问权限](/docs/zh-CN/advisor#choose-an-advisor-model) | `claude --advisor opus` |

67| `--agents` | 通过 JSON 动态定义自定义子代理。接受[为 CLI 定义的子代理列出的字段](/docs/zh-CN/sub-agents#choose-the-subagent-scope)。Claude Code 在启动时验证 JSON 并在值无效时退出；有关消息以及跳过验证的标志和环境变量，请参阅 [`Invalid --agents configuration`](/docs/zh-CN/errors#invalid-agents-configuration)。验证需要 Claude Code v2.1.242 或更高版本 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |67| `--agents` | 通过 JSON 动态定义自定义子代理。接受[为 CLI 定义的子代理列出的字段](/docs/zh-CN/sub-agents#choose-the-subagent-scope)。使用 `--print` 时，该值可以是包含该对象的 JSON 文件的路径；文件形式需要 Claude Code v2.1.281 或更高版本。Claude Code 在启动时验证该值并在值无效时退出；有关消息以及跳过验证的标志和环境变量，请参阅 [`Invalid --agents configuration`](/docs/zh-CN/errors#invalid-agents-configuration)。验证需要 Claude Code v2.1.242 或更高版本 | `claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You are a code reviewer"}}'` |

68| `--allow-dangerously-skip-permissions` | 将 `bypassPermissions` 添加到 `Shift+Tab` 模式循环中而不启动它。让您可以从不同的模式（如 `plan`）开始，稍后切换到 `bypassPermissions`。请参阅[权限模式](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |68| `--allow-dangerously-skip-permissions` | 将 `bypassPermissions` 添加到 `Shift+Tab` 模式循环中而不启动它。让您可以从不同的模式（如 `plan`）开始，稍后切换到 `bypassPermissions`。请参阅[权限模式](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode) | `claude --permission-mode plan --allow-dangerously-skip-permissions` |

69| `--allowedTools`, `--allowed-tools` | 无需提示权限即可执行的工具。有关模式匹配，请参阅[权限规则语法](/docs/zh-CN/settings-reference#permission-rule-syntax)。要限制哪些工具可用，请改用 `--tools`。如果您在此处命名[任务跟踪工具](/docs/zh-CN/tools-reference#task-tool-availability)之一，Claude Code 也会选择加入会话 | `"Bash(git log *)" "Bash(git diff *)" "Read"` |69| `--allowedTools`, `--allowed-tools` | 无需提示权限即可执行的工具。有关模式匹配，请参阅[权限规则语法](/docs/zh-CN/settings-reference#permission-rule-syntax)。要限制哪些工具可用，请改用 `--tools`。如果您在此处命名[任务跟踪工具](/docs/zh-CN/tools-reference#task-tool-availability)之一，Claude Code 也会选择加入会话 | `"Bash(git log *)" "Bash(git diff *)" "Read"` |

70| `--append-subagent-system-prompt` | 将自定义文本附加到每个[子代理](/docs/zh-CN/sub-agents)的系统提示末尾，包括嵌套子代理，除了[分叉的子代理](/docs/zh-CN/sub-agents#fork-the-current-conversation)，它重用对话自己的提示。仅在使用 `-p` 的非交互模式下应用。需要 Claude Code v2.1.205 或更高版本 | `claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"` |70| `--append-subagent-system-prompt` | 将自定义文本附加到每个[子代理](/docs/zh-CN/sub-agents)的系统提示末尾，包括嵌套子代理，除了[分叉的子代理](/docs/zh-CN/sub-agents#fork-the-current-conversation)，它重用对话自己的提示。仅在使用 `-p` 的非交互模式下应用。需要 Claude Code v2.1.205 或更高版本 | `claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"` |

75| `--ax-screen-reader` | 呈现屏幕阅读器友好的输出：没有装饰性边框或动画的平面文本。强制使用经典渲染器，因此 [`tui`](/docs/zh-CN/settings-reference#tui) 设置无效；附加的[后台会话](/docs/zh-CN/agent-view)仍然全屏呈现。优先于 [`CLAUDE_AX_SCREEN_READER`](/docs/zh-CN/env-vars) 和 [`axScreenReader`](/docs/zh-CN/settings-reference#axscreenreader) 设置。需要 Claude Code v2.1.181 或更高版本 | `claude --ax-screen-reader` |75| `--ax-screen-reader` | 呈现屏幕阅读器友好的输出：没有装饰性边框或动画的平面文本。强制使用经典渲染器，因此 [`tui`](/docs/zh-CN/settings-reference#tui) 设置无效；附加的[后台会话](/docs/zh-CN/agent-view)仍然全屏呈现。优先于 [`CLAUDE_AX_SCREEN_READER`](/docs/zh-CN/env-vars) 和 [`axScreenReader`](/docs/zh-CN/settings-reference#axscreenreader) 设置。需要 Claude Code v2.1.181 或更高版本 | `claude --ax-screen-reader` |

76| `--bare` | 最小模式：跳过 hooks、skills、自定义命令、子代理、plugins、MCP 服务器、自动内存和 CLAUDE.md 的自动发现，以便脚本化调用启动更快。使用 `--add-dir` 传递的目录中的 Skills 仍然加载。Claude 可以访问 Bash、文件读取和文件编辑工具。设置 [`CLAUDE_CODE_SIMPLE`](/docs/zh-CN/env-vars)。请参阅[裸模式](/docs/zh-CN/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |76| `--bare` | 最小模式：跳过 hooks、skills、自定义命令、子代理、plugins、MCP 服务器、自动内存和 CLAUDE.md 的自动发现，以便脚本化调用启动更快。使用 `--add-dir` 传递的目录中的 Skills 仍然加载。Claude 可以访问 Bash、文件读取和文件编辑工具。设置 [`CLAUDE_CODE_SIMPLE`](/docs/zh-CN/env-vars)。请参阅[裸模式](/docs/zh-CN/headless#start-faster-with-bare-mode) | `claude --bare -p "query"` |

78| `--bg`, `--background` | 将会话作为[后台代理](/docs/zh-CN/agent-view)启动并立即返回。打印会话 ID 和管理命令。与 `--exec` 结合以将 shell 命令作为后台作业运行，而不是启动 Claude 会话，或与 `--agent` 结合以运行特定的子代理。不能与 `-p`/`--print` 结合；请参阅[错误参考](/docs/zh-CN/errors#command-line-errors) | `claude --bg "investigate the flaky test"` |78| `--bg`, `--background` | 将会话作为[后台代理](/docs/zh-CN/agent-view)启动并立即返回。打印会话 ID 和管理命令。与 `--exec` 结合以将 shell 命令作为后台作业运行，而不是启动 Claude 会话，或与 `--agent` 结合以运行特定的子代理。检查[工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)以在启动前检查目录。不能与 `-p`/`--print` 结合；请参阅[错误参考](/docs/zh-CN/errors#command-line-errors) | `claude --bg "investigate the flaky test"` |

79| `--channels` | （研究预览）Claude 应在此会话中侦听其[频道](/docs/zh-CN/channels)通知的 MCP 服务器。空格分隔的 `plugin:<name>@<marketplace>` 条目列表。需要通过 claude.ai 或 Console API 密钥进行 Anthropic 身份验证 | `claude --channels plugin:my-notifier@my-marketplace` |79| `--channels` | （研究预览）Claude 应在此会话中侦听其[频道](/docs/zh-CN/channels)通知的 MCP 服务器。空格分隔的 `plugin:<name>@<marketplace>` 条目列表。需要通过 claude.ai 或 Console API 密钥进行 Anthropic 身份验证 | `claude --channels plugin:my-notifier@my-marketplace` |

81| `--cloud` | 使用任务描述创建新的[云会话](/docs/zh-CN/claude-code-on-the-web)。使用会话 ID（`session_...` 或 `cse_...`）或 claude.ai/code URL，使用 `-p` 将消息排队到该现有会话。请参阅[发送后续消息](/docs/zh-CN/claude-code-on-the-web#send-follow-ups-from-the-cli)。 | `claude --cloud "Fix the login bug"` |81| `--cloud` | 使用任务描述创建新的[云会话](/docs/zh-CN/claude-code-on-the-web)。使用会话 ID（`session_...` 或 `cse_...`）或 claude.ai/code URL，使用 `-p` 将消息排队到该现有会话。请参阅[发送后续消息](/docs/zh-CN/claude-code-on-the-web#send-follow-ups-from-the-cli)。 | `claude --cloud "Fix the login bug"` |

89| `--effort` | 为当前会话设置[努力级别](/docs/zh-CN/model-config#adjust-effort-level)。选项：`low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`。可用级别取决于模型。`ultracode` 请求 `xhigh` 努力，[ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode) 打开，需要 Claude Code v2.1.203 或更高版本。覆盖此会话的 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 和 [`effortLevel`](/docs/zh-CN/settings-reference#effortlevel) 设置，不持续 | `claude --effort high` |89| `--effort` | 为当前会话设置[努力级别](/docs/zh-CN/model-config#adjust-effort-level)。选项：`low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`。可用级别取决于模型。`ultracode` 请求 `xhigh` 努力，[ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode) 打开，需要 Claude Code v2.1.203 或更高版本。覆盖此会话的 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 和 [`effortLevel`](/docs/zh-CN/settings-reference#effortlevel) 设置，不持续 | `claude --effort high` |

91| `--environment <environment-id>` | 创建在具有给定 ID 的[自托管环境](/docs/zh-CN/self-hosted-environments)上运行的新云会话。环境 ID 以 `ccpool_` 开头。有关调度行为和它拒绝的标志组合，请参阅 [`--environment` 调度行为](/docs/zh-CN/self-hosted-environments-testing#environment-dispatch-behavior)。需要 Claude Code v2.1.224 或更高版本 | `claude -p "Fix the login bug" --environment ccpool_abc123` |91| `--environment <environment-id>` | 创建在具有给定 ID 的[自托管环境](/docs/zh-CN/self-hosted-environments)上运行的新云会话。环境 ID 以 `ccpool_` 开头。有关调度行为和它拒绝的标志组合，请参阅 [`--environment` 调度行为](/docs/zh-CN/self-hosted-environments-testing#environment-dispatch-behavior)。需要 Claude Code v2.1.224 或更高版本 | `claude -p "Fix the login bug" --environment ccpool_abc123` |

92| `--exclude-dynamic-system-prompt-sections` | 将系统提示的每台机器部分（工作目录、环境信息、内存路径、git-repo 标志）移到第一条用户消息中。改进跨不同用户和运行相同任务的机器的提示缓存重用。仅适用于默认系统提示；当设置 `--system-prompt` 或 `--system-prompt-file` 时忽略。与 `-p` 一起用于脚本化的多用户工作负载 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |92| `--exclude-dynamic-system-prompt-sections` | 将每用户上下文（如自动内存位置）从系统提示移到第一条用户消息中。改进跨不同用户和运行相同任务的机器的提示缓存重用。仅适用于默认系统提示；当设置 `--system-prompt` 或 `--system-prompt-file` 时忽略。与 `-p` 一起用于脚本化的多用户工作负载 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

94| `--fallback-model` | 启用当主模型过载或不可用时自动回退到指定的模型，例如已停用的模型。接受按顺序尝试的逗号分隔列表。请参阅[回退模型链](/docs/zh-CN/model-config#fallback-model-chains)。要在会话之间保持链，请使用此标志覆盖的 [`fallbackModel` 设置](/docs/zh-CN/settings-reference#fallbackmodel) | `claude --fallback-model sonnet,haiku` |94| `--fallback-model` | 启用当主模型过载或不可用时自动回退到指定的模型，例如已停用的模型。接受按顺序尝试的逗号分隔列表。请参阅[回退模型链](/docs/zh-CN/model-config#fallback-model-chains)。要在会话之间保持链，请使用此标志覆盖的 [`fallbackModel` 设置](/docs/zh-CN/settings-reference#fallbackmodel) | `claude --fallback-model sonnet,haiku` |

127| `--resume`, `-r` | 按 ID 或名称恢复特定会话，或显示交互式选择器以选择会话。代替 ID，您可以传递会话的 `.jsonl` [记录文件](/docs/zh-CN/sessions#where-transcripts-are-stored)的绝对路径。选择器和名称搜索包括使用 `/add-dir` 添加此目录的会话。当您传递会话 ID 时，Claude Code 搜索当前项目目录及其 git worktrees，然后搜索此机器上的所有其他项目。在 v2.1.223 之前，ID 搜索仅涵盖当前项目目录及其 git worktrees。[后台会话](/docs/zh-CN/agent-view)在选择器中显示，标记为 `bg` | `claude --resume auth-refactor` |127| `--resume`, `-r` | 按 ID 或名称恢复特定会话，或显示交互式选择器以选择会话。代替 ID，您可以传递会话的 `.jsonl` [记录文件](/docs/zh-CN/sessions#where-transcripts-are-stored)的绝对路径。选择器和名称搜索包括使用 `/add-dir` 添加此目录的会话。当您传递会话 ID 时，Claude Code 搜索当前项目目录及其 git worktrees，然后搜索此机器上的所有其他项目。在 v2.1.223 之前，ID 搜索仅涵盖当前项目目录及其 git worktrees。[后台会话](/docs/zh-CN/agent-view)在选择器中显示，标记为 `bg` | `claude --resume auth-refactor` |

128| `--safe-mode` | 禁用所有自定义以排除故障的损坏配置：CLAUDE.md、skills、plugins、hooks、MCP 服务器、自定义命令和代理、输出样式、工作流、自定义主题、自定义快捷键、状态行和文件建议命令、LSP 服务器和自动内存不加载。身份验证、模型选择、内置工具和权限正常工作，这与 [`--bare`](/docs/zh-CN/headless#start-faster-with-bare-mode) 不同。托管设置策略仍然适用，包括策略配置的 hooks、状态行和文件建议命令；托管 plugins、托管 skills、托管 CLAUDE.md 和策略配置的 MCP 服务器不适用。用于检查自定义是否触发[自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)。设置 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-CN/env-vars) | `claude --safe-mode` |128| `--safe-mode` | 禁用所有自定义以排除故障的损坏配置：CLAUDE.md、skills、plugins、hooks、MCP 服务器、自定义命令和代理、输出样式、工作流、自定义主题、自定义快捷键、状态行和文件建议命令、LSP 服务器和自动内存不加载。身份验证、模型选择、内置工具和权限正常工作，这与 [`--bare`](/docs/zh-CN/headless#start-faster-with-bare-mode) 不同。托管设置策略仍然适用，包括策略配置的 hooks、状态行和文件建议命令；托管 plugins、托管 skills、托管 CLAUDE.md 和策略配置的 MCP 服务器不适用。用于检查自定义是否触发[自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)。设置 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-CN/env-vars) | `claude --safe-mode` |

130| `--setting-sources` | 要加载的设置源的逗号分隔列表（`user`、`project`、`local`） | `claude --setting-sources user,project` |130| `--setting-sources` | 要加载的设置源的逗号分隔列表（`user`、`project`、`local`）。请参阅[代理视图](/docs/zh-CN/agent-view#what-carries-over-when-you-background)和[代理团队](/docs/zh-CN/agent-teams#context-and-communication)以了解从此会话启动的会话继承列表 | `claude --setting-sources user,project` |

131| `--settings` | 设置 JSON 文件的路径或内联 JSON 字符串。您在此处设置的值覆盖此会话的 `settings.json` 文件中的相同键。您省略的键保持其基于文件的值。文件必须是不超过 2 MiB 的常规文件。请参阅[设置优先级](/docs/zh-CN/settings#settings-precedence) | `claude --settings ./settings.json` |131| `--settings` | 设置 JSON 文件的路径或内联 JSON 字符串。您在此处设置的值覆盖此会话的 `settings.json` 文件中的相同键。您省略的键保持其基于文件的值。文件必须是不超过 2 MiB 的常规文件。请参阅[设置优先级](/docs/zh-CN/settings#settings-precedence) | `claude --settings ./settings.json` |

132| `--strict-mcp-config` | 仅使用 `--mcp-config` 中的 MCP 服务器，忽略所有其他 MCP 配置。有关标志在托管 MCP 文件下执行的操作，请参阅[使用 managed-mcp.json 的独占控制](/docs/zh-CN/managed-mcp#exclusive-control-with-managed-mcp-json) | `claude --strict-mcp-config --mcp-config ./mcp.json` |132| `--strict-mcp-config` | 仅使用 `--mcp-config` 中的 MCP 服务器，忽略所有其他 MCP 配置。有关标志在托管 MCP 文件下执行的操作，请参阅[使用 managed-mcp.json 的独占控制](/docs/zh-CN/managed-mcp#exclusive-control-with-managed-mcp-json) | `claude --strict-mcp-config --mcp-config ./mcp.json` |

cloud-environments.md +22 −8

Details

78DATABASE_URL=postgres://localhost:5432/myapp78DATABASE_URL=postgres://localhost:5432/myapp

79```79```

80 80

81每个会话在启动时将环境的值复制一次到普通环境变量中，Claude运行的任何命令都可以读取这些变量。因为运行中的会话不会重新读取配置，编辑或添加变量会影响你之后启动的会话；已经运行的会话保持它们启动时的值。81每个会话在启动时将环境的值复制一次到普通环境变量中，Claude运行的任何命令都可以读取这些变量，除了`OTEL_*`变量。Claude Code使用这些变量进行自己的[遥测导出](/docs/zh-CN/monitoring-usage#telemetry-from-cloud-sessions-and-claude-tag)，不会将它们传递给它运行的命令。因为运行中的会话不会重新读取配置，编辑或添加变量会影响你之后启动的会话；已经运行的会话保持它们启动时的值。

82 82

83云会话在启动时也会自己设置一些变量。对于[`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/zh-CN/claude-code-on-the-web#manage-context)，会话设置的值会覆盖你在这里添加的值，所以在这里添加该键没有效果。83云会话在启动时也会自己设置一些变量。对于[`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/zh-CN/claude-code-on-the-web#manage-context)，会话设置的值会覆盖你在这里添加的值，所以在这里添加该键没有效果。

84 84

149* **GitHub**：[GitHub代理](#github-proxy)改为对GitHub的请求进行身份验证，所以你不需要为它提供API凭证149* **GitHub**：[GitHub代理](#github-proxy)改为对GitHub的请求进行身份验证，所以你不需要为它提供API凭证

150* **Anthropic API和公共包注册表**：`api.anthropic.com`、`registry.npmjs.org`、`jsr.io`、`npm.jsr.io`、`pypi.org`、`files.pythonhosted.org`、`index.crates.io`和`proxy.golang.org`150* **Anthropic API和公共包注册表**：`api.anthropic.com`、`registry.npmjs.org`、`jsr.io`、`npm.jsr.io`、`pypi.org`、`files.pythonhosted.org`、`index.crates.io`和`proxy.golang.org`

151* **Setup script请求**：Claude Code在启动时连接到代理，在[setup script](#setup-scripts)运行后151* **Setup script请求**：Claude Code在启动时连接到代理，在[setup script](#setup-scripts)运行后

152* **Claude Code的遥测导出**：Claude Code自己发送其[遥测导出](/docs/zh-CN/monitoring-usage#telemetry-from-cloud-sessions-and-claude-tag)，而不是通过它运行的命令，该请求不会通过代理

152 153

153<h3 id="select-an-environment-from-the-cli">154<h3 id="select-an-environment-from-the-cli">

154 从CLI选择环境155 从CLI选择环境

250* **此环境中的会话打开另一个组织的公开工件**：Claude Code 直接从主机获取这些工件，因此将其添加到此列表。251* **此环境中的会话打开另一个组织的公开工件**：Claude Code 直接从主机获取这些工件，因此将其添加到此列表。

251* **您正在配置本地 CLI 或自托管运行器**：在该允许列表中保留主机。请参阅[网络访问要求](/docs/zh-CN/network-config#network-access-requirements)和自托管[网络要求](/docs/zh-CN/self-hosted-environments-deploy#network-requirements)。252* **您正在配置本地 CLI 或自托管运行器**：在该允许列表中保留主机。请参阅[网络访问要求](/docs/zh-CN/network-config#network-access-requirements)和自托管[网络要求](/docs/zh-CN/self-hosted-environments-deploy#network-requirements)。

252 253

253每个环境都有自己的允许域列表；没有组织级别的允许列表可供管理员推送到每个成员的环境。[服务器管理的设置](/docs/zh-CN/server-managed-settings)在云会话内仍然适用，但其中没有任何设置会将域添加到环境的网络允许列表。要为团队提供一个标准列表，Owner 可以创建一个具有 **Custom** 网络访问和该列表的[组织共享环境](#organization-shared-environments)。254每个环境都有自己的允许域列表；没有组织级别的允许列表可供管理员推送到每个成员的环境。[服务器管理的设置](/docs/zh-CN/server-managed-settings)也不会将域添加到环境的网络允许列表。要为团队提供一个标准列表，Owner 可以创建一个具有 **Custom** 网络访问和该列表的[组织共享环境](#organization-shared-environments)。

254 255

255<h3 id="github-proxy">256<h3 id="github-proxy">

256 GitHub 代理257 GitHub 代理

281 云会话中可用的内容282 云会话中可用的内容

282</h2>283</h2>

283 284

284在 Anthropic 托管的环境中，每个会话都会获得一台运行 Ubuntu 24.04 的全新虚拟机 (VM)（x86\_64 架构），无论您自己的操作系统和 CPU 架构是什么，您的存储库已克隆，常见的工具链已预安装。当依赖项提供预编译的二进制文件（例如具有本机扩展的 Ruby gem 或预构建的 Python wheel）时，请使用其 x86\_64 Linux 构建以匹配 VM。本节涵盖 Anthropic 托管的默认值、内置 GitHub 工具、如何[运行测试和服务](#run-tests-start-services-and-add-packages)，以及每台 VM 获得的[资源限制](#resource-limits)。285在 Anthropic 托管的环境中，每个会话都会获得一台运行 Ubuntu 24.04 的全新虚拟机 (VM)（x86\_64 架构），无论您自己的操作系统和 CPU 架构是什么，您的存储库已克隆，常见的工具链已预安装。当依赖项提供预编译的二进制文件（例如具有本机扩展的 Ruby gem 或预构建的 Python wheel）时，请使用其 x86\_64 Linux 构建以匹配 VM。本节涵盖 Anthropic 托管的默认值、内置 GitHub 工具、如何[运行测试和服务](#run-tests-start-services-and-add-packages)、每台 VM 获得的[资源限制](#resource-limits)，以及[时间限制](#time-limits)对长时间运行的工作的限制。

285 286

286<Note>287<Note>

287 您的组织路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话在您自己的运行器上运行，使用您的运行器镜像提供的工具。288 您的组织路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话在您自己的运行器上运行，使用您的运行器镜像提供的工具。

301| 您的存储库的 `.claude/rules/` | 是 | 克隆的一部分 |302| 您的存储库的 `.claude/rules/` | 是 | 克隆的一部分 |

302| 您的存储库的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 克隆的一部分 |303| 您的存储库的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 克隆的一部分 |

303| 在您的存储库的 `.claude/settings.json` 中声明的 plugins 和 marketplaces | 否 | 云会话不会安装存储库在 [`enabledPlugins`](/docs/zh-CN/settings-reference#enabledplugins) 下启用的 plugins，包括来自它在 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces) 下列出的 marketplaces 的 plugins |304| 在您的存储库的 `.claude/settings.json` 中声明的 plugins 和 marketplaces | 否 | 云会话不会安装存储库在 [`enabledPlugins`](/docs/zh-CN/settings-reference#enabledplugins) 下启用的 plugins，包括来自它在 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces) 下列出的 marketplaces 的 plugins |

304| 您组织的[服务器管理的设置](/docs/zh-CN/server-managed-settings) | 是 | 在会话启动时从 Anthropic 的服务器获取。请参阅 [Surface coverage](/docs/zh-CN/model-config#surface-coverage) 了解 `availableModels` 在云会话中如何强制执行。通过 MDM 或管理配置文件部署到您设备的设置不适用，因为会话在 Anthropic 管理的 VM 上运行；在[自托管环境](/docs/zh-CN/self-hosted-environments)中，会话也会读取运行器镜像中的管理设置文件，根据 [Claude Code 如何组合管理来源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources) |305| 您组织的[服务器管理的设置](/docs/zh-CN/server-managed-settings) | 是，除了在 [Claude Tag](https://claude.com/docs/claude-tag/overview) 会话中 | 在会话启动时从 Anthropic 的服务器获取。请参阅 [Surface coverage](/docs/zh-CN/model-config#surface-coverage) 了解 `availableModels` 在云会话中如何强制执行。通过 MDM 或管理配置文件部署到您设备的设置不适用，因为会话在 Anthropic 管理的 VM 上运行；在[自托管环境](/docs/zh-CN/self-hosted-environments)中，会话也会读取运行器镜像中的管理设置文件，根据 [Claude Code 如何组合管理来源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources) |

305| 您的用户 `~/.claude/CLAUDE.md` | 否 | 位于您的机器上，不在存储库中 |306| 您的用户 `~/.claude/CLAUDE.md` | 否 | 位于您的机器上，不在存储库中 |

306| 您的用户 `~/.claude/skills/`、`~/.claude/agents/`、`~/.claude/commands/` | 否 | 位于您的机器上，不在存储库中。请改为将它们提交到存储库的 `.claude/` 目录。云会话会自动加载您在 claude.ai 上启用的技能 |307| 您的用户 `~/.claude/skills/`、`~/.claude/agents/`、`~/.claude/commands/` | 否 | 位于您的机器上，不在存储库中。请改为将它们提交到存储库的 `.claude/` 目录。云会话会自动加载您在 claude.ai 上启用的技能 |

307| 仅在您的用户设置中启用的 plugins | 否 | 用户范围的 `enabledPlugins` 位于您机器上的 `~/.claude/settings.json` |308| 仅在您的用户设置中启用的 plugins | 否 | 用户范围的 `enabledPlugins` 位于您机器上的 `~/.claude/settings.json` |

421 422

422VM 可能会停止需要明显更多内存的工作，例如大型构建工作或内存密集型测试。对于超出这些限制的工作负载，请使用 [Remote Control](/docs/zh-CN/remote-control) 在您自己的硬件上运行 Claude Code，或在[自托管环境](/docs/zh-CN/self-hosted-environments)中运行云会话，该环境在您的组织运营的计算上。423VM 可能会停止需要明显更多内存的工作，例如大型构建工作或内存密集型测试。对于超出这些限制的工作负载，请使用 [Remote Control](/docs/zh-CN/remote-control) 在您自己的硬件上运行 Claude Code，或在[自托管环境](/docs/zh-CN/self-hosted-environments)中运行云会话，该环境在您的组织运营的计算上。

423 424

425<h3 id="time-limits">

426 时间限制

427</h3>

428

429在 Anthropic 托管的环境中，这些时间限制适用于云会话中的长时间运行的工作，例如构建、安装或测试运行。每个条目链接到定义该限制的部分。

430

431* **Claude 运行的命令**：云环境不设置自己的命令超时，因此 Bash 工具的默认值适用。Claude 默认等待 2 分钟的命令，最多可以要求 10 分钟。当命令达到其[超时](/docs/zh-CN/tools-reference#timeout-and-output-limits)时，Claude Code [将其移到后台](/docs/zh-CN/tools-reference#background-commands)，而不是停止它，除非命令以 `sleep` 开头。

432* **SessionStart hooks**：Claude Code 在 600 秒后取消 `command` hook，除非您在 hook 条目上设置 [`timeout`](/docs/zh-CN/hooks#common-fields)（以秒为单位）。Claude Code 不会对您使用 [`async: true`](/docs/zh-CN/hooks#run-hooks-in-the-background) 运行的 hook 强制执行超时。

433* **设置脚本**：花费超过大约五分钟的脚本不会被缓存。[脚本要求](#script-requirements)涵盖如何保持在该时间以下。

434* **空闲会话**：会话在一段时间不活动后停止，其 VM 被回收。[环境已过期](/docs/zh-CN/claude-code-on-the-web#environment-expired)涵盖什么算作不活动以及如何重新打开会话。

435

436要为环境的会话提高命令超时，请将 [`BASH_DEFAULT_TIMEOUT_MS` 和 `BASH_MAX_TIMEOUT_MS`](/docs/zh-CN/env-vars#variables) 添加到其[环境变量](#set-environment-variables)。两者都采用毫秒。例如，`BASH_DEFAULT_TIMEOUT_MS=600000` 使 10 分钟成为默认值。

437

424<h2 id="setup-scripts">438<h2 id="setup-scripts">

425 设置脚本439 设置脚本

426</h2>440</h2>

445设置脚本有三个需要考虑的约束：459设置脚本有三个需要考虑的约束：

446 460

447* **以零退出**：如果脚本以非零状态结束，会话将无法启动。在非关键命令后附加 `|| true`，以便间歇性安装失败不会阻止会话。461* **以零退出**：如果脚本以非零状态结束，会话将无法启动。在非关键命令后附加 `|| true`，以便间歇性安装失败不会阻止会话。

448* **在五分钟内完成**：将脚本的总运行时间保持在大约五分钟以内，以便[环境缓存](#environment-caching)可以建立。使用 `&` 和 `wait` 并行运行独立的安装，并将任何无法容纳的单个下载移至 [SessionStart hook](#setup-scripts-vs-sessionstart-hooks)，在后台启动它。462* **在五分钟内完成**：将脚本的总运行时间保持在大约五分钟以内，以便[环境缓存](#environment-caching)可以建立。当设置耗时超过五分钟时，环境不会被缓存。使用 `&` 和 `wait` 并行运行独立的安装，并将任何无法容纳的单个下载移至 [SessionStart hook](#setup-scripts-vs-sessionstart-hooks)，在后台启动它。如果新会话在设置期间停滞或失败，请参阅[新会话在设置期间挂起或超时](/docs/zh-CN/web-quickstart#new-sessions-hang-or-time-out-during-setup)。

449* **安装需要网络访问**：包安装需要连接到注册表。默认的 **Trusted** 级别涵盖[常见包注册表](#default-allowed-domains)，包括 npm、PyPI、RubyGems 和 crates.io；使用 **None** 网络访问时，安装会失败。463* **安装需要网络访问**：包安装需要连接到注册表。默认的 **Trusted** 级别涵盖[常见包注册表](#default-allowed-domains)，包括 npm、PyPI、RubyGems 和 crates.io；使用 **None** 网络访问时，安装会失败。

450 464

451<h3 id="environment-caching">465<h3 id="environment-caching">

452 环境缓存466 环境缓存

453</h3>467</h3>

454 468

455设置脚本在您第一次在环境中启动会话时运行。完成后，Anthropic 会对文件系统进行快照，并将该快照重用作后续会话的起点。新会话以您的依赖项、工具和 Docker 镜像已在磁盘上的状态开始，并跳过设置脚本步骤。即使脚本安装大型工具链或拉取容器镜像，这也能保持启动速度快。469设置脚本在您第一次在环境中启动会话时运行。当设置在[大约五分钟](#script-requirements)内完成时，Anthropic 会对文件系统进行快照，并将该快照重用作后续会话的起点。新会话以您的依赖项、工具和 Docker 镜像已在磁盘上的状态开始，并跳过设置脚本步骤。即使脚本安装大型工具链或拉取容器镜像，这也能保持启动速度快。如果设置耗时超过大约五分钟，环境不会被缓存。

456 470

457缓存是文件系统快照，因此它会保留设置脚本写入磁盘的内容，并丢失任何仅在运行中的内容。您安装的包、您拉取的 Docker 镜像和您写入的文件都会保留。脚本启动的数据库、`docker compose up` 堆栈或任何其他后台进程不会保留；请通过询问 Claude 或使用 [SessionStart hook](#setup-scripts-vs-sessionstart-hooks) 在每个会话中启动这些。471缓存是文件系统快照，因此它会保留设置脚本写入磁盘的内容，并丢失任何仅在运行中的内容。您安装的包、您拉取的 Docker 镜像和您写入的文件都会保留。脚本启动的数据库、`docker compose up` 堆栈或任何其他后台进程不会保留；请通过询问 Claude 或使用 [SessionStart hook](#setup-scripts-vs-sessionstart-hooks) 在每个会话中启动这些。

458 472

476 490

477如果您在用户级 `~/.claude/settings.json` 中有 SessionStart hooks，不要期望它们在云端生效。用户级设置保留在您的机器上。其他 hooks 运行的位置取决于会话运行的位置：491如果您在用户级 `~/.claude/settings.json` 中有 SessionStart hooks，不要期望它们在云端生效。用户级设置保留在您的机器上。其他 hooks 运行的位置取决于会话运行的位置：

478 492

479* **Anthropic 托管环境**：Claude Code 运行来自存储库和您组织的[服务器管理的设置](/docs/zh-CN/server-managed-settings)的 hooks。493* **Anthropic 托管环境**：Claude Code 运行来自存储库和您组织的[服务器管理的设置](/docs/zh-CN/server-managed-settings)的 hooks。[Claude Tag](https://claude.com/docs/claude-tag/overview) 会话不会接收服务器管理的设置，因此来自服务器管理的设置的 hooks 不会在那里运行。

480* **[自托管环境](/docs/zh-CN/self-hosted-environments-configuration#permissions-and-tool-approval)**：Claude Code 还运行运行程序主机的 `~/.claude/` 中的运行程序操作员播种的 hooks，以及运行程序镜像的托管设置文件中的 hooks，当该文件是 [Claude Code 应用的托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)之一时。494* **[自托管环境](/docs/zh-CN/self-hosted-environments-configuration#permissions-and-tool-approval)**：Claude Code 还运行运行程序主机的 `~/.claude/` 中的运行程序操作员播种的 hooks，以及运行程序镜像的托管设置文件中的 hooks，当该文件是 [Claude Code 应用的托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)之一时。

481 495

482<h3 id="install-dependencies-with-a-sessionstart-hook">496<h3 id="install-dependencies-with-a-sessionstart-hook">

808* [Remote Control](/docs/zh-CN/remote-control)：改为在您自己的机器的网络和文件上运行会话822* [Remote Control](/docs/zh-CN/remote-control)：改为在您自己的机器的网络和文件上运行会话

809* [Self-hosted environments](/docs/zh-CN/self-hosted-environments)：在您的组织自己的基础设施上运行云会话823* [Self-hosted environments](/docs/zh-CN/self-hosted-environments)：在您的组织自己的基础设施上运行云会话

810* [SessionStart hooks](/docs/zh-CN/hooks#sessionstart)：存储库提交的设置，在本地和云会话中运行824* [SessionStart hooks](/docs/zh-CN/hooks#sessionstart)：存储库提交的设置，在本地和云会话中运行

811* [Server-managed settings](/docs/zh-CN/server-managed-settings)：到达云会话的组织策略825* [Server-managed settings](/docs/zh-CN/server-managed-settings)：从管理控制台交付的组织策略

code-review.md +3 −3

Details

48| 🟡 | 小问题 | 轻微问题，值得修复但不阻止 |48| 🟡 | 小问题 | 轻微问题，值得修复但不阻止 |

49| 🟣 | 预先存在 | 代码库中存在但不是由此 PR 引入的错误 |49| 🟣 | 预先存在 | 代码库中存在但不是由此 PR 引入的错误 |

50 50

~~51发现包括可折叠的扩展推理部分，您可以展开以了解 Claude 为什么标记该问题以及它如何验证问题。~~51发现包括可折叠的**为什么被标记**部分，您可以展开以了解 Claude 为什么标记该问题以及它如何验证问题。

52 52

53<h3 id="rate-and-reply-to-findings">53<h3 id="rate-and-reply-to-findings">

54 对发现进行评分和回复54 对发现进行评分和回复

292 故障排除292 故障排除

293</h2>293</h2>

294 294

295审查运行是尽力而为的。失败的运行永远不会阻止您的 PR，但它也不会自动重试。本部分介绍如何从失败的运行中恢复，以及当检查运行报告您找不到的问题时在哪里查看。295审查运行是尽力而为的，失败的运行永远不会阻止您的 PR。Code Review 会自动重试一些中断的审查。本部分介绍如何自己再次运行审查，以及当检查运行报告您找不到的问题时在哪里查看。

296 296

297<h3 id="retrigger-a-failed-or-timed-out-review">297<h3 id="retrigger-a-failed-or-timed-out-review">

298 重新触发失败或超时的审查298 重新触发失败或超时的审查

299</h3>299</h3>

300 300

301当审查基础设施遇到内部错误或超过时间限制时，检查运行完成，标题为 **Code review encountered an error** 或 **Code review timed out**。结论仍然是中立的，因此没有任何东西阻止您的合并，但没有发现被发布。301当审查失败或超过时间限制时，检查运行完成，标题为 **Code review failed** 或 **Code review timed out**。结论仍然是中立的，因此没有任何东西阻止您的合并。除非检查运行的摘要说新的提交审查已自动排队，否则请自己再次运行审查。

302 302

303要再次运行审查，在 PR 上注释 `@claude review`。这启动一个新的审查，不订阅 PR 到未来推送。如果 PR 不是[来自 fork](#review-pull-requests-from-forks)，您可以改为在 GitHub 的 Checks 选项卡中的 **Claude Code Review** 检查上点击 **Re-run**。重新运行也会启动一个新的审查，不订阅 PR。303要再次运行审查，在 PR 上注释 `@claude review`。这启动一个新的审查，不订阅 PR 到未来推送。如果 PR 不是[来自 fork](#review-pull-requests-from-forks)，您可以改为在 GitHub 的 Checks 选项卡中的 **Claude Code Review** 检查上点击 **Re-run**。重新运行也会启动一个新的审查，不订阅 PR。

304 304

commands.md +4 −3

Details

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

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

81| `/deep-research <question>` | **[Workflow](/docs/zh-CN/workflows#bundled-workflows)。** 在问题上扇出网络搜索，获取和交叉检查来源，并综合一个引用的报告 |81| `/deep-research <question>` | **[Workflow](/docs/zh-CN/workflows#bundled-workflows)。** 在问题上扇出网络搜索，获取和交叉检查来源，并综合一个引用的报告 |

82| `/design [brief]` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 在一个画布上起草 UI 模型、屏幕流、登陆页面或海报作为画板，发布为一个 Design [工件](/docs/zh-CN/artifacts#draft-a-design-canvas)，例如 `/design a settings screen for a mobile banking app`。你在桌面浏览器中编辑画板，你的编辑会自动保存。你可以将每个画板导出为 PNG 或 PDF。需要一个[工件可用](/docs/zh-CN/artifacts#availability)的会话和 Claude Code v2.1.265 或更高版本。在 Anthropic API 上可用。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Claude Platform on AWS 上，工件不可用，所以命令在那里不可用 |82| `/design [brief]` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 在一个画布上起草 UI 模型、屏幕流、登陆页面或海报作为画板，发布为一个 Claude Design [工件](/docs/zh-CN/artifacts#draft-a-design-canvas)，例如 `/design a settings screen for a mobile banking app`。你在桌面浏览器中编辑画板，你的编辑会自动保存。你可以将每个画板导出为 PNG 或 PDF。需要 Claude Code v2.1.265 或更高版本、一个[工件可用](/docs/zh-CN/artifacts#availability)的会话，以及一个[设计模板可用](/docs/zh-CN/artifacts#start-from-a-slides-design-or-docs-template)的账户；如果你的组织已关闭该模板，`/design` 不会起草设计。在 Anthropic API 上可用。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Claude Platform on AWS 上，工件不可用，所以命令在那里不可用 |

83| `/design-login` | 使用你的 claude.ai 账户授权 `/design-sync` 的设计系统访问 |83| `/design-login` | 使用你的 claude.ai 账户授权 `/design-sync` 的设计系统访问 |

84| `/design-sync [hint]` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 转换你的 repo 的 React 设计系统并将其上传到 [Claude Design](https://claude.ai/design)，以便它生成的设计使用你的真实组件。可选地命名设计系统，例如 `/design-sync Acme DS`。首次同步验证每个组件，在大型 repo 上可能需要几个小时。在 Anthropic API 上可用。它需要 claude.ai，CLI 在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 上不联系，或通过 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway#availability-and-limitations)，所以命令在那里不可用 |84| `/design-sync [hint]` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 转换你的 repo 的 React 设计系统并将其上传到 [Claude Design](https://claude.ai/design)，以便它生成的设计使用你的真实组件。可选地命名设计系统，例如 `/design-sync Acme DS`。首次同步验证每个组件，在大型 repo 上可能需要几个小时。在 Anthropic API 上可用。它需要 claude.ai，CLI 在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 上不联系，或通过 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway#availability-and-limitations)，所以命令在那里不可用 |

85| `/desktop` | 在 Claude Code Desktop 应用中继续当前会话。需要 macOS 或 x64 Windows 和 Claude 订阅。别名：`/app` |85| `/desktop` | 在 Claude Code Desktop 应用中继续当前会话。需要 macOS 或 x64 Windows 和 Claude 订阅。别名：`/app` |

86| `/diff` | 审查你的工作树中的更改，包括 Claude 到目前为止所做的编辑。请参阅[使用 /diff 审查更改](/docs/zh-CN/interactive-mode#review-changes-with-%2Fdiff) |86| `/diff` | 审查你的工作树中的更改，包括 Claude 到目前为止所做的编辑。请参阅[使用 /diff 审查更改](/docs/zh-CN/interactive-mode#review-changes-with-%2Fdiff) |

87| `/doctor` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 运行一个设置检查，诊断问题并可以修复它们。检查安装健康状况，包括重复或遗留安装、`PATH` 问题和无法解析的设置文件。查找未使用的 skill、MCP 服务器和插件与其上下文成本，标记缓慢的 [hooks](/docs/zh-CN/hooks)，并检查你的[发布频道](/docs/zh-CN/setup#configure-release-channel)上是否有更新版本。根据检入的本地 `CLAUDE.md` 文件进行重复数据删除，通过削减 Claude 可以从代码库派生的内容来修剪检入的 [`CLAUDE.md`](/docs/zh-CN/memory#my-claude-md-is-too-large) 文件，并将保留的始终加载的指导迁移到[skill](/docs/zh-CN/skills) 和按需加载的嵌套 `CLAUDE.md` 文件中。还提供使[自动模式](/docs/zh-CN/permissions#permission-modes)成为你的默认值和[预先批准](/docs/zh-CN/permissions)经常被拒绝的只读命令。首先报告发现并在更改任何内容之前要求确认。从终端，`claude doctor` 打印只读安装诊断而不启动会话。别名：`/checkup`。`CLAUDE.md` 修剪检查需要 Claude Code v2.1.206 或更高版本。在 v2.1.205 之前，`/doctor` 打开一个只读诊断屏幕，按 `f` 将报告发送给 Claude |87| `/doctor [prompt-audit [path]]` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 运行一个设置检查，诊断问题并可以修复它们。检查安装健康状况，包括重复或遗留安装、`PATH` 问题和无法解析的设置文件。查找未使用的 skill、MCP 服务器和插件与其上下文成本，标记缓慢的 [hooks](/docs/zh-CN/hooks)，并检查你的[发布频道](/docs/zh-CN/setup#configure-release-channel)上是否有更新版本。根据检入的本地 `CLAUDE.md` 文件进行重复数据删除，通过削减 Claude 可以从代码库派生的内容来修剪检入的 [`CLAUDE.md`](/docs/zh-CN/memory#my-claude-md-is-too-large) 文件，并将保留的始终加载的指导迁移到[skill](/docs/zh-CN/skills) 和按需加载的嵌套 `CLAUDE.md` 文件中。还提供使[自动模式](/docs/zh-CN/permissions#permission-modes)成为你的默认值和[预先批准](/docs/zh-CN/permissions)经常被拒绝的只读命令。首先报告发现并在更改任何内容之前要求确认。从终端，`claude doctor` 打印只读安装诊断而不启动会话。别名：`/checkup`。运行 `/doctor prompt-audit` 以让 Claude [审计你的 `CLAUDE.md` 文件、skill 和其他配置](/docs/zh-CN/memory#write-effective-instructions)以查找过时或冲突的指令，而不是运行检查。`prompt-audit` 子命令需要 Claude Code v2.1.283 或更高版本。`CLAUDE.md` 修剪检查需要 Claude Code v2.1.206 或更高版本。在 v2.1.205 之前，`/doctor` 打开一个只读诊断屏幕，按 `f` 将报告发送给 Claude |

88| `/effort [level\|auto\|status]` | 设置[工作量级别](/docs/zh-CN/model-config#adjust-effort-level)：`low` 到 `xhigh`、`max`、[`ultracode`](/docs/zh-CN/workflows#let-claude-decide-with-ultracode) 或 `auto`；`status` 打印它。`max` 和 `ultracode` 仅限会话；[`ultracode`](/docs/zh-CN/settings-reference#ultracode) 键持久化。在 Claude 响应时运行它，一旦你确认[缓存警告](/docs/zh-CN/prompt-caching#changing-effort-level)（如果 Claude Code 显示一个），Claude Code 会将新级别应用于该轮中的下一个请求。在 v2.1.242 之前，Claude Code 从它从 Anthropic 获取的功能标志决定是在轮中期运行命令还是将其排队直到轮次完成，并始终在不[获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话中排队它，例如在[第三方提供商](/docs/zh-CN/third-party-integrations)上。在 `-p` 中工作 |88| `/effort [level\|auto\|status\|ultracode [on\|off]]` | 设置[工作量级别](/docs/zh-CN/model-config#adjust-effort-level)：`low` 到 `xhigh`、`max` 或 `auto`；`status` 打印它。`ultracode` 或 `ultracode on` 在当前级别为会话打开 [ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)，`ultracode off` 关闭它；[`ultracode`](/docs/zh-CN/settings-reference#ultracode) 键持久化。`max` 仅限会话。使用 `on` 和 `off` 参数以及保持当前级别需要 Claude Code v2.1.284 或更高版本。在 v2.1.284 之前，`/effort ultracode` 将会话设置为 `xhigh`，`/effort ultracode off` 失败并显示 `Invalid argument`。在 Claude 响应时运行它，一旦你确认[缓存警告](/docs/zh-CN/prompt-caching#changing-effort-level)（如果 Claude Code 显示一个），Claude Code 会将新级别应用于该轮中的下一个请求。在 v2.1.242 之前，Claude Code 从它从 Anthropic 获取的功能标志决定是在轮中期运行命令还是将其排队直到轮次完成，并始终在不[获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话中排队它，例如在[第三方提供商](/docs/zh-CN/third-party-integrations)上。在 `-p` 中工作 |

89| `/exit` | 退出 CLI。在附加的[后台会话](/docs/zh-CN/agent-view#attach-to-a-session)中，这会分离，会话继续运行。别名：`/quit` |89| `/exit` | 退出 CLI。在附加的[后台会话](/docs/zh-CN/agent-view#attach-to-a-session)中，这会分离，会话继续运行。别名：`/quit` |

90| `/export [filename]` | 将当前对话导出为纯文本。使用文件名，直接写入该文件。没有，打开一个对话框以复制到剪贴板或保存到文件 |90| `/export [filename]` | 将当前对话导出为纯文本。使用文件名，直接写入该文件。没有，打开一个对话框以复制到剪贴板或保存到文件 |

91| `/fast [on\|off]` | 切换[快速模式](/docs/zh-CN/fast-mode)打开或关闭。在 Claude 响应时运行它，Claude Code 切换快速模式而不等待轮次结束，尽管运行的轮次以其原始速度完成。在 v2.1.242 之前，Claude Code 从它从 Anthropic 获取的功能标志决定是在轮中期运行命令还是将其排队直到轮次完成，并始终在不[获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话中排队它。非交互模式中的可用性受限于 `-p`；请参阅[切换快速模式](/docs/zh-CN/fast-mode#toggle-fast-mode)。需要 Claude Code v2.1.205 或更高版本 |91| `/fast [on\|off]` | 切换[快速模式](/docs/zh-CN/fast-mode)打开或关闭。在 Claude 响应时运行它，Claude Code 切换快速模式而不等待轮次结束，尽管运行的轮次以其原始速度完成。在 v2.1.242 之前，Claude Code 从它从 Anthropic 获取的功能标志决定是在轮中期运行命令还是将其排队直到轮次完成，并始终在不[获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话中排队它。非交互模式中的可用性受限于 `-p`；请参阅[切换快速模式](/docs/zh-CN/fast-mode#toggle-fast-mode)。需要 Claude Code v2.1.205 或更高版本 |

143| `/simplify [target]` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 审查更改的代码以查找清理机会并应用修复。四个审查[代理](/docs/zh-CN/sub-agents)并行运行，涵盖现有帮助程序的重用、简化、效率以及更改是否处于正确的抽象级别。审查不查找正确性错误。使用 `/code-review` 查找错误。传递路径或 PR 参考以审查特定目标 |143| `/simplify [target]` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 审查更改的代码以查找清理机会并应用修复。四个审查[代理](/docs/zh-CN/sub-agents)并行运行，涵盖现有帮助程序的重用、简化、效率以及更改是否处于正确的抽象级别。审查不查找正确性错误。使用 `/code-review` 查找错误。传递路径或 PR 参考以审查特定目标 |

144| `/skill-doctor` | 显示你的每个 [skill](/docs/zh-CN/skills) 在上下文中的成本以及它被使用的频率，以便你可以[找到要关闭的 skill](/docs/zh-CN/skills#find-unused-skills)。需要 Claude Code v2.1.252 或更高版本和[功能标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) |144| `/skill-doctor` | 显示你的每个 [skill](/docs/zh-CN/skills) 在上下文中的成本以及它被使用的频率，以便你可以[找到要关闭的 skill](/docs/zh-CN/skills#find-unused-skills)。需要 Claude Code v2.1.252 或更高版本和[功能标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) |

145| `/skills` | 列出可用的 [skill](/docs/zh-CN/skills)。输入以按名称、描述或来源过滤列表。按 `t` 按令牌计数排序，`Space` 或 `Enter` 以[循环 skill 对 Claude 和 `/` 菜单的可见性](/docs/zh-CN/skills#override-skill-visibility-from-settings)，`Esc` 保存并关闭。你无法循环插件 skill、frontmatter 设置 `disable-model-invocation: true` 的 skill 或在托管设置或 `--settings` 标志中有 `skillOverrides` 条目的 skill |145| `/skills` | 列出可用的 [skill](/docs/zh-CN/skills)。输入以按名称、描述或来源过滤列表。按 `t` 按令牌计数排序，`Space` 或 `Enter` 以[循环 skill 对 Claude 和 `/` 菜单的可见性](/docs/zh-CN/skills#override-skill-visibility-from-settings)，`Esc` 保存并关闭。你无法循环插件 skill、frontmatter 设置 `disable-model-invocation: true` 的 skill 或在托管设置或 `--settings` 标志中有 `skillOverrides` 条目的 skill |

146| `/slides [brief]` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 制作一个新的演示文稿作为 Claude Slides [工件](/docs/zh-CN/artifacts#make-a-slide-deck)，从你的简介中填充，例如 `/slides a quarterly review of the platform team`。需要 Claude Code v2.1.265 或更高版本、一个[工件可用](/docs/zh-CN/artifacts#availability)的会话，以及一个[Slides 模板可用](/docs/zh-CN/artifacts#start-from-a-slides-design-or-docs-template)的账户；否则命令不会出现。在 Anthropic API 上可用。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Claude Platform on AWS 上，工件不可用，所以命令在那里不可用 |

147| `/status` | 在 Status 选项卡上打开设置界面，显示版本、模型、账户和连接性。一个 `Session kind` 行在[后台会话](/docs/zh-CN/agent-view)中读取 `background job · attached` 或 `background job · unattended`，取决于是否附加了终端，在任何其他会话中读取 `interactive`。在 v2.1.221 之前，`/status` 没有显示此行。在 Claude 响应时工作 |148| `/status` | 在 Status 选项卡上打开设置界面，显示版本、模型、账户和连接性。一个 `Session kind` 行在[后台会话](/docs/zh-CN/agent-view)中读取 `background job · attached` 或 `background job · unattended`，取决于是否附加了终端，在任何其他会话中读取 `interactive`。在 v2.1.221 之前，`/status` 没有显示此行。在 Claude 响应时工作 |

communications-kit.md +4 −4

Details

196使用 Opus 修复打字错误会浪费计算。使用 Haiku 进行 12 文件重构196使用 Opus 修复打字错误会浪费计算。使用 Haiku 进行 12 文件重构

197是在要求重做。197是在要求重做。

198 198

199Claude Code 在与 Claude 应用相同的模型上运行，您可以在会话中间切换。*Sonnet* 是日常功能工作、错误、测试和审查的主力默认值。在大型重构、复杂调试或任何高风险的事情上使用 *Opus*。对于快速问题、格式化和速度获胜的机械编辑，降低到 *Haiku*。*Fable* 是您最困难、最长时间运行任务的最强大模型；它不是默认值，所以使用 `/model fable` 选择它，请注意网络安全和生物学内容会自动回退到 Opus。Opus 5.5 和 Opus 5 运行自己的检查：标记的内容会切换到较早的 Opus，除了 Opus 5 上标记的生物学内容被拒绝。199Claude Code 在与 Claude 应用相同的模型上运行，您可以在会话中间切换。*Sonnet* 是日常功能工作、错误、测试和审查的主力默认值。在大型重构、复杂调试或任何高风险的事情上使用 *Opus*。对于快速问题、格式化和速度获胜的机械编辑，降低到 *Haiku*。*Fable* 是您最困难、最长时间运行任务的最强大模型；它不是默认值，所以使用 `/model fable` 选择它，请注意网络安全和生物学内容会自动回退到 Opus。Opus 5.5、Sonnet 5.5 和 Opus 5 运行自己的检查：标记的内容会切换到同一系列中的较早模型，除了 Opus 5 或 Sonnet 5.5 上标记的生物学内容被拒绝。

200 200

201*现在尝试：* 输入 `/model` 并选择 Sonnet（如果您还没有的话）。它是大多数任务的正确默认值。201*现在尝试：* 输入 `/model` 并选择 Sonnet（如果您还没有的话）。它是大多数任务的正确默认值。

202 202

207| - | - |207| - | - |

208| Fable | 最困难、最长时间运行的任务。仅选择加入：使用 `/model fable` 选择它。网络安全或生物学内容触发[自动模型回退到 Opus](/docs/zh-CN/model-config#automatic-model-fallback) |208| Fable | 最困难、最长时间运行的任务。仅选择加入：使用 `/model fable` 选择它。网络安全或生物学内容触发[自动模型回退到 Opus](/docs/zh-CN/model-config#automatic-model-fallback) |

209| Opus | 大规模重构、复杂调试、架构决策、高风险更改。在 Opus 5.5 和 Opus 5 上，网络安全或生物学内容触发[自动模型回退或拒绝](/docs/zh-CN/model-config#automatic-model-fallback) |209| Opus | 大规模重构、复杂调试、架构决策、高风险更改。在 Opus 5.5 和 Opus 5 上，网络安全或生物学内容触发[自动模型回退或拒绝](/docs/zh-CN/model-config#automatic-model-fallback) |

210| Sonnet | 日常功能工作、错误修复、测试、文档、代码审查。推荐默认值。 |210| Sonnet | 日常功能工作、错误修复、测试、文档、代码审查。推荐默认值。在 Sonnet 5.5 上，网络安全或生物学内容触发[自动模型回退或拒绝](/docs/zh-CN/model-config#automatic-model-fallback) |

211| Haiku | 快速问题、格式化、机械编辑、快速迭代 |211| Haiku | 快速问题、格式化、机械编辑、快速迭代 |

212 212

213**快速赢得尝试首先**213**快速赢得尝试首先**

406您团队中的某个人会问"等等，我的代码去哪里了？"406您团队中的某个人会问"等等，我的代码去哪里了？"

407这是您可以粘贴的简短版本。407这是您可以粘贴的简短版本。

408 408

409权限优先设计。每个文件编辑、shell 命令和外部调用都由您的批准门控。CLI 在您的终端中运行，直接与 Anthropic 的 API 通信，没有第三方服务器，并支持 shell 命令的可选操作系统级沙箱。根据我们的企业计划，Anthropic 不使用您的代码或提示来训练其模型。409权限优先设计。每个文件编辑、shell 命令和外部调用都由您的批准门控。CLI 在您的终端中运行，直接与 Anthropic 的 API 通信，没有第三方服务器，并支持 shell 命令的可选操作系统级沙箱。在 Team 或 Enterprise 计划上，Anthropic 不使用您的代码或提示来训练其模型。

410 410

411*现在尝试：* 保存这两个链接以备下次问题出现。它们回答了大多数安全审查问题。411*现在尝试：* 保存这两个链接以备下次问题出现。它们回答了大多数安全审查问题。

412 412

445| - | - |445| - | - |

446| "它在 VS Code 中工作吗？" | 是的。有一个 VS Code 扩展和一个 JetBrains 插件，具有相同的功能，嵌入在您的编辑器中。[VS Code →](/docs/zh-CN/vs-code) |446| "它在 VS Code 中工作吗？" | 是的。有一个 VS Code 扩展和一个 JetBrains 插件，具有相同的功能，嵌入在您的编辑器中。[VS Code →](/docs/zh-CN/vs-code) |

448| "我的代码去哪里了？" | CLI 在您的终端中运行，并将上下文发送到 Anthropic 的 API 进行推理，没有第三方服务器。根据您的企业计划，您的代码和提示不用于训练模型。[数据使用 →](/docs/zh-CN/data-usage) |448| "我的代码去哪里了？" | CLI 在您的终端中运行，并将上下文发送到 Anthropic 的 API 进行推理，没有第三方服务器。在 Team 或 Enterprise 计划上，您的代码和提示不用于训练模型。[数据使用 →](/docs/zh-CN/data-usage) |

449| "它能看到我的整个仓库吗？" | 它读取您给它访问权限的内容。您工作目录内的文件读取不提示；权限提示门控编辑、非只读 shell 命令和该目录外的文件工具读取。一组内置的只读 shell 命令（如 `ls` 和 `cat`）无需提示即可运行；使用[沙箱 `denyRead` 规则](/docs/zh-CN/sandboxing#filesystem-isolation)限制它。[权限 →](/docs/zh-CN/permissions) |449| "它能看到我的整个仓库吗？" | 它读取您给它访问权限的内容。您工作目录内的文件读取不提示；权限提示门控编辑、非只读 shell 命令和该目录外的文件工具读取。一组内置的只读 shell 命令（如 `ls` 和 `cat`）无需提示即可运行；使用[沙箱 `denyRead` 规则](/docs/zh-CN/sandboxing#filesystem-isolation)限制它。[权限 →](/docs/zh-CN/permissions) |

450| "这与 Copilot 有什么不同？" | Copilot 自动完成行。Claude Code 是一个读取文件、运行命令和进行多文件编辑的代理。[概述 →](/docs/zh-CN/overview) |450| "这与 Copilot 有什么不同？" | Copilot 自动完成行。Claude Code 是一个读取文件、运行命令和进行多文件编辑的代理。[概述 →](/docs/zh-CN/overview) |

451| "我应该首先尝试什么？" | 您一直在推迟的错误，因为它很乏味。"文件 \[file] 中的测试不稳定，找出原因。" [快速入门 →](/docs/zh-CN/quickstart) |451| "我应该首先尝试什么？" | 您一直在推迟的错误，因为它很乏味。"文件 \[file] 中的测试不稳定，找出原因。" [快速入门 →](/docs/zh-CN/quickstart) |

context-window.md +2 −2

Details

1632* **在任务之间清除**：切换到不相关的工作时运行 `/clear`。旧对话会挤出您接下来需要的文件，并在每条消息上花费令牌。1632* **在任务之间清除**：切换到不相关的工作时运行 `/clear`。旧对话会挤出您接下来需要的文件，并在每条消息上花费令牌。

1633* **委托大型读取**：将研究发送给[子代理](/docs/zh-CN/sub-agents)，以便文件内容保留在其上下文窗口中，而不是您的。1633* **委托大型读取**：将研究发送给[子代理](/docs/zh-CN/sub-agents)，以便文件内容保留在其上下文窗口中，而不是您的。

1634 1634

1635如果您需要更大的窗口而不是更小的对话，Fable 模型、Sonnet 5、Opus 4.6 及更高版本以及 Sonnet 4.6 支持 100 万令牌的上下文窗口。有关按计划的可用性以及如何选择 `[1m]` 模型变体，请参阅[扩展上下文](/docs/zh-CN/model-config#extended-context)。压缩在更大的限制下以相同的方式工作。1635如果您需要更大的窗口而不是更小的对话，Fable 模型、Sonnet 5 及更高版本、Opus 4.6 及更高版本以及 Sonnet 4.6 支持 100 万令牌的上下文窗口。有关按计划的可用性以及如何选择 `[1m]` 模型变体，请参阅[扩展上下文](/docs/zh-CN/model-config#extended-context)。压缩在更大的限制下以相同的方式工作。

1636 1636

1637Sonnet 5 以 1M 上下文窗口运行，没有 `[1m]` 变体可选择。有关其自动压缩阈值和 LLM 网关异常，请参阅[Sonnet 5 上下文窗口](/docs/zh-CN/model-config#sonnet-5-context-window)。1637Sonnet 5.5 和 Sonnet 5 以 1M 上下文窗口运行，没有 `[1m]` 变体可选择。有关其自动压缩阈值和 LLM 网关异常，请参阅[Sonnet 5.5 和 Sonnet 5 上下文窗口](/docs/zh-CN/model-config#sonnet-5-5-and-sonnet-5-context-window)。

1638 1638

1639自动压缩运行的位置取决于您的模型和配置。有关每个模型的边界，请参阅[默认自动压缩阈值](/docs/zh-CN/model-config#default-auto-compact-thresholds)，如果 Claude Code 为您的模型 ID（例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名）假设了错误的窗口，请参阅[更正网关或自定义模型 ID 的窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。1639自动压缩运行的位置取决于您的模型和配置。有关每个模型的边界，请参阅[默认自动压缩阈值](/docs/zh-CN/model-config#default-auto-compact-thresholds)，如果 Claude Code 为您的模型 ID（例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名）假设了错误的窗口，请参阅[更正网关或自定义模型 ID 的窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。

1640 1640

costs.md +4 −1

Details

359 359

360扩展思考默认启用，因为它显著改进了复杂规划和推理任务的性能。思考令牌作为输出令牌计费，默认预算可能是每个请求数万个令牌，具体取决于模型。360扩展思考默认启用，因为它显著改进了复杂规划和推理任务的性能。思考令牌作为输出令牌计费，默认预算可能是每个请求数万个令牌，具体取决于模型。

361 361

362对于不需要深度推理的更简单任务，您可以通过在 `/effort` 中或在 `/model` 中降低 [effort level](/docs/zh-CN/model-config#adjust-effort-level)、或在 `/config` 中禁用思考来降低成本。您无法在 Opus 5.5 或 Fable 模型上关闭思考，它们始终使用扩展思考。362对于不需要深度推理的更简单任务，您可以通过在 `/effort` 中或在 `/model` 中降低 [effort level](/docs/zh-CN/model-config#adjust-effort-level)、或在 `/config` 中禁用思考来降低成本。您无法在 Opus 5.5、Sonnet 5.5 或 Fable 模型上关闭思考，它们始终使用扩展思考。

363 363

364在具有[固定思考预算](/docs/zh-CN/model-config#adaptive-reasoning-and-fixed-thinking-budgets)的模型上，您也可以通过设置 `MAX_THINKING_TOKENS` [环境变量](/docs/zh-CN/env-vars)（例如 `MAX_THINKING_TOKENS=8000`）来降低预算。自适应推理模型忽略非零预算，因此请改用 effort levels。364在具有[固定思考预算](/docs/zh-CN/model-config#adaptive-reasoning-and-fixed-thinking-budgets)的模型上，您也可以通过设置 `MAX_THINKING_TOKENS` [环境变量](/docs/zh-CN/env-vars)（例如 `MAX_THINKING_TOKENS=8000`）来降低预算。自适应推理模型忽略非零预算，因此请改用 effort levels。

365 365

369 369

370运行测试、获取文档或处理日志文件可能会消耗大量上下文。将这些委托给 [subagents](/docs/zh-CN/sub-agents#isolate-high-volume-operations)，以便冗长的输出保留在 subagent 的上下文中，而只有摘要返回到您的主对话。370运行测试、获取文档或处理日志文件可能会消耗大量上下文。将这些委托给 [subagents](/docs/zh-CN/sub-agents#isolate-high-volume-operations)，以便冗长的输出保留在 subagent 的上下文中，而只有摘要返回到您的主对话。

371 371

372subagent 自己的请求仍然会消耗您的使用量。为了在这些请求上花费更少，[为 subagent 选择更小的模型](/docs/zh-CN/sub-agents#choose-a-model)或[在一个模型上运行每个 subagent](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model)。

373

372<h3 id="manage-agent-team-costs">374<h3 id="manage-agent-team-costs">

373 管理 agent 团队成本375 管理 agent 团队成本

374</h3>376</h3>

416* **计划任务**：[计划任务](/docs/zh-CN/scheduled-tasks) 按其间隔触发，即使会话处于空闲状态，每次都发送你的完整上下文418* **计划任务**：[计划任务](/docs/zh-CN/scheduled-tasks) 按其间隔触发，即使会话处于空闲状态，每次都发送你的完整上下文

417* **跨会话消息**：当此会话处于空闲状态时，Claude Code 将 [来自你另一个会话的消息](/docs/zh-CN/cross-session-messaging) 作为新轮次传递，每次都发送你的完整上下文。要保留入站消息而不是传递它们，请将 [`crossSessionInbound`](/docs/zh-CN/settings-reference#crosssessioninbound) 设置为 `hold`419* **跨会话消息**：当此会话处于空闲状态时，Claude Code 将 [来自你另一个会话的消息](/docs/zh-CN/cross-session-messaging) 作为新轮次传递，每次都发送你的完整上下文。要保留入站消息而不是传递它们，请将 [`crossSessionInbound`](/docs/zh-CN/settings-reference#crosssessioninbound) 设置为 `hold`

418* **目标检查**：当后台工作使活跃的 [目标](/docs/zh-CN/goal) 保持等待时，Claude Code [要求 Claude 检查该工作](/docs/zh-CN/goal#background-work-defers-evaluation)，即使会话处于空闲状态，启动发送你完整上下文的新轮次。Claude Code 在你的提示之间每个目标最多启动三个空闲检查。在 v2.1.246 之前，空闲检查是无限制的。要关闭检查，请将 [`CLAUDE_CODE_GOAL_CHECKIN_MINUTES`](/docs/zh-CN/env-vars) 设置为 `0`。空闲检查需要 Claude Code v2.1.236 或更高版本420* **目标检查**：当后台工作使活跃的 [目标](/docs/zh-CN/goal) 保持等待时，Claude Code [要求 Claude 检查该工作](/docs/zh-CN/goal#background-work-defers-evaluation)，即使会话处于空闲状态，启动发送你完整上下文的新轮次。Claude Code 在你的提示之间每个目标最多启动三个空闲检查。在 v2.1.246 之前，空闲检查是无限制的。要关闭检查，请将 [`CLAUDE_CODE_GOAL_CHECKIN_MINUTES`](/docs/zh-CN/env-vars) 设置为 `0`。空闲检查需要 Claude Code v2.1.236 或更高版本

421* **子代理和工作流**：每个子代理，以及每个 [动态工作流](/docs/zh-CN/workflows#cost) 生成的代理，都会在主对话的基础上发送自己的请求。[属性分解](#plan-usage-breakdown) 显示子代理份额

419* **代理队友**：每个活跃的 [队友](#agent-team-token-costs) 会继续消耗令牌，直到它退出422* **代理队友**：每个活跃的 [队友](#agent-team-token-costs) 会继续消耗令牌，直到它退出

420* **压缩**：`/compact` 读取它总结的对话，因此 [压缩大型上下文](/docs/zh-CN/prompt-caching#compacting-the-conversation) 本身就是一个大型请求。当你想要全新开始而不是连续性时，`/clear` 不消耗任何成本423* **压缩**：`/compact` 读取它总结的对话，因此 [压缩大型上下文](/docs/zh-CN/prompt-caching#compacting-the-conversation) 本身就是一个大型请求。当你想要全新开始而不是连续性时，`/clear` 不消耗任何成本

421 424

cross-session-messaging.md +49 −86

Details

14 14

15消息是一个 Claude 写给另一个 Claude 的文本片段，永远不包括发送者的对话历史或文件。要移动整个对话或其上下文，请[恢复会话](/docs/zh-CN/sessions#resume-a-session)。15消息是一个 Claude 写给另一个 Claude 的文本片段，永远不包括发送者的对话历史或文件。要移动整个对话或其上下文，请[恢复会话](/docs/zh-CN/sessions#resume-a-session)。

16 16

17Claude 为此使用两个工具：`ListAgents` 用于发现它可以到达的代理，`SendMessage` 用于按名称将消息传递给其中一个。使用相同的 `SendMessage` 工具，Claude 也可以在单个会话或团队内消息传递到[子代理](/docs/zh-CN/sub-agents#resume-subagents)和[代理团队](/docs/zh-CN/agent-teams)队友。本页涵盖您独立会话之间的消息。

19<h2 id="when-to-use-cross-session-messaging">17<h2 id="when-to-use-cross-session-messaging">

20 何时使用跨会话消息传递18 何时使用跨会话消息传递

21</h2>19</h2>

27* **获取长期运行工作的状态**：让迁移或测试运行报告回您正在观看的会话，或从那里自己询问。如果该会话在此机器上，Claude 还可以[在它下次空闲或退出时要求一条通知](#get-a-notice-when-another-session-goes-idle)。25* **获取长期运行工作的状态**：让迁移或测试运行报告回您正在观看的会话，或从那里自己询问。如果该会话在此机器上，Claude 还可以[在它下次空闲或退出时要求一条通知](#get-a-notice-when-another-session-goes-idle)。

28* **跨机器发送消息**：到达您在另一台机器或网络上的一个会话。26* **跨机器发送消息**：到达您在另一台机器或网络上的一个会话。

29 27

30在您自己启动和指导的独立会话之间使用消息传递。Claude Code 为运行或到达多个会话的其他每种方式都有专门的功能，因此请使用为您正在做的事情构建的功能：

~~32* 要在另一个终端继续一个对话，或与新会话共享其上下文，请[恢复会话](/docs/zh-CN/sessions#resume-a-session)~~

~~33* 对于 Claude 生成和监督的协调团队会话，使用[代理团队](/docs/zh-CN/agent-teams)~~

~~34* 要从一个地方观看和指导许多会话，使用[代理视图](/docs/zh-CN/agent-view)~~

~~35* 要从您的手机或另一台设备自己指导会话，而不是让会话相互发送消息，使用[远程控制](/docs/zh-CN/remote-control)~~

~~36* 要将外部事件（如 CI 结果或聊天消息）推送到会话中，使用[频道](/docs/zh-CN/channels)~~

38<h2 id="message-another-session">28<h2 id="message-another-session">

39 向另一个会话发送消息29 向另一个会话发送消息

40</h2>30</h2>

44要自己提示一条消息，告诉 Claude 你想让另一个会话知道或做什么。这个例子是你输入的提示，而不是 Claude 发送的消息：34要自己提示一条消息，告诉 Claude 你想让另一个会话知道或做什么。这个例子是你输入的提示，而不是 Claude 发送的消息：

45 35

46```text wrap theme={null}36```text wrap theme={null}

~~47Ask the session running in my other terminal whether the migration finished~~37询问在我的另一个终端中运行的会话迁移是否完成

48```38```

49 39

~~50Claude 会自己写出实际的消息，所以你的提示可以将内容留给 Claude。这个提示要求一个摘要而不指定其措辞，Claude 发送的内容会有所不同：~~40Claude 会自己编写实际的消息，所以你的提示可以将内容留给 Claude。这个提示要求一个摘要而不指定其措辞，Claude 发送的内容会有所不同：

51 41

52```text wrap theme={null}42```text wrap theme={null}

~~53Explain what we just did to the session working on the payments API~~43向处理支付 API 的会话解释我们刚刚做了什么

54```44```

55 45

56要自己命名目标，在你的提示中提及会话：输入 `@` 后跟会话名称的首字母，然后从类型提示中选择会话，就像你 [@-提及一个子代理](/docs/zh-CN/sub-agents#invoke-subagents-explicitly) 一样。需要 Claude Code v2.1.232 或更高版本。Claude Code 会插入提及，例如 `@api-worker`，并告诉 Claude 它命名的是哪个会话，所以 Claude 可以向该会话发送消息而无需先列出你的会话。这个提示用提及来命名目标：46要自己命名目标，在你的提示中提及会话：输入 `@` 后跟会话名称的首字母，然后从类型提示中选择会话，方式与 [@-提及子代理](/docs/zh-CN/sub-agents#invoke-subagents-explicitly) 相同。需要 Claude Code v2.1.232 或更高版本。Claude Code 会插入提及，例如 `@api-worker`，并告诉 Claude 它命名的是哪个会话，这样 Claude 可以向该会话发送消息而无需先列出你的会话。这个提示用提及命名目标：

57 47

58```text wrap theme={null}48```text wrap theme={null}

~~59Let @api-worker know the schema migration finished~~49让 @api-worker 知道架构迁移已完成

60```50```

61 51

~~62类型提示列出了你在这台机器上的其他活跃会话。两种情况需要超过名称的首字母：~~52类型提示列出你在这台机器上的其他活跃会话。两种情况需要超过名称的首字母：

63 53

64* **这台机器之外的会话**：云会话或远程控制会话仅在 Claude 列出或向你这台机器之外的会话发送消息后才会出现在类型提示中，所以先要求 Claude 列出它们。54* **这台机器之外的会话**：云会话或远程控制会话仅在 Claude 列出或向你这台机器之外的会话发送消息后才会出现在类型提示中，所以请先要求 Claude 列出它们。

65* **名称中有空格或字母、数字、连字符和下划线之外的其他字符**：在双引号中输入，例如 `@"release notes"`。当你从类型提示中选择会话时，Claude Code 会为你插入引号。55* **包含空格或字母、数字、连字符和下划线以外字符的名称**：用双引号输入，例如 `@"release notes"`。当你从类型提示中选择会话时，Claude Code 会为你插入引号。

66 56

~~67你也可以在没有选择器的情况下输入提及。当多个活跃会话响应提及的名称时，Claude 会在发送前询问你指的是哪一个。~~57你也可以不使用选择器直接输入提及。当多个活跃会话响应提及的名称时，Claude 会在发送前询问你指的是哪一个。

68 58

~~69关于 Claude 写的消息到达时的样子，包括一个例子，请参见 [消息看起来像什么](#what-a-message-looks-like)。~~59关于 Claude 编写的消息到达时的样子，包括一个例子，请参见 [消息看起来像什么](#what-a-message-looks-like)。

70 60

71<h3 id="message-delivery">61<h3 id="message-delivery">

72 消息传递62 消息传递

73</h3>63</h3>

74 64

75接收 Claude 在活跃轮次中的工具调用之间读取消息，所以运行的工具永远不会被中断。当接收会话处于空闲状态时，Claude Code 会用消息启动一个新轮次。65接收 Claude 在活跃轮次中的工具调用之间读取消息，所以运行中的工具永远不会被中断。当接收会话处于空闲状态时，Claude Code 会用消息启动新的轮次。

76 66

77来自另一个会话的消息以纯文本形式到达。如果它用 `@` 提及文件或 [MCP 资源](/docs/zh-CN/mcp#use-mcp-resources)，Claude 会看到如写入的提及，Claude Code 不会附加任何内容，无论消息是启动新轮次还是在轮次中到达。Claude 仍然可以用自己的工具在接收机器上打开提及的路径，受该会话的权限限制。在 v2.1.251 之前，启动新轮次的消息中的 `@` 提及会在接收端附加文件或 MCP 资源。67来自另一个会话的消息以纯文本形式到达。如果它用 `@` 提及文件或 [MCP 资源](/docs/zh-CN/mcp#use-mcp-resources)，Claude 会看到按原样写的提及，Claude Code 不会附加任何内容，无论消息是启动新轮次还是在现有轮次中到达。Claude 仍然可以用自己的工具在接收机器上打开提及的路径，受该会话的权限限制。

78 68

79Claude Code 在以下情况下拒绝消息：69Claude Code 在以下情况下拒绝消息：

80 70

81* 消息 [超过大小限制](#limitations)。Claude Code 在发送会话中拒绝它，在它离开之前。71* 消息 [超过大小限制](#limitations)。Claude Code 在发送会话中拒绝它，在它离开之前。

82* 对这台机器上的会话的快速突发已达到 [该会话的收件箱接受的内容](#limitations)。Claude Code 拒绝向该会话发送进一步的消息。72* 对这台机器上的会话的快速突发已达到 [该会话的收件箱接受的内容](#limitations)。Claude Code 拒绝向该会话发送进一步的消息。

83* 这台机器上的回复目标未通过安全检查，例如符号链接目标或不是预期进程的端点。[拒绝发送跨会话消息](/docs/zh-CN/errors#refusing-to-send-a-cross-session-message) 列出了这些检查。73* 这台机器上的回复目标未通过安全检查，例如符号链接目标。[拒绝发送跨会话消息](/docs/zh-CN/errors#refusing-to-send-a-cross-session-message) 列出了这些检查。

~~84* Claude 将消息寻址到此会话自己的名称，如 [查看 Claude 可以到达的会话](#see-which-sessions-claude-can-reach) 下所述。~~

85 74

~~86接收会话根据自己的 [入站控制](#control-inbound-messages) 检查每条到达的消息，检查以三种结果之一结束：~~75接收会话根据其自己的 [入站控制](#control-inbound-messages) 检查每条到达的消息，检查以三种结果之一结束：

87 76

88* **已传递**：Claude Code 将消息传递给接收 Claude。77* **已传递**：Claude Code 将消息传递给接收 Claude。

89* **已保留**：Claude Code 将消息搁置未传递。保留的消息仅在你批准它或稍后的模式或设置更改允许它时才到达 Claude。78* **已保留**：Claude Code 将消息搁置未传递。保留的消息仅在你批准它或稍后的模式或设置更改允许它时才到达 Claude。

~~90* **已拒绝**：Claude Code 在不传递的情况下丢弃消息。~~79* **已拒绝**：Claude Code 丢弃消息而不传递它。

91 80

92一旦传递，消息就像你输入的提示一样计入 [使用情况](/docs/zh-CN/costs)，接收 Claude 可以以相同的方式回复发送者，除了 [单向跨机器情况](#message-sessions-on-other-machines)。81一旦传递，消息计入 [使用情况](/docs/zh-CN/costs)，就像你输入的提示一样，接收 Claude 可以以相同的方式回复发送者，除了 [单向跨机器情况](#message-sessions-on-other-machines)。

93 82

94权限边界保持每个会话。Claude 被指示永远不要要求另一个会话执行在其自己的会话中被拒绝或阻止的操作，或其自己的权限设置会阻止的操作，而是将该工作路由回你。在接收端，[接收会话自己的权限提示和规则仍然适用](#how-a-session-treats-an-incoming-message) 于消息要求的任何内容。83权限边界保持按会话。Claude 被指示永远不要要求另一个会话执行在其自己的会话中被拒绝或阻止的操作，或其自己的权限设置会阻止的操作，而是将该工作路由回你。在接收端，[接收会话自己的权限提示和规则仍然适用](#how-a-session-treats-an-incoming-message) 于消息要求的任何内容。

95 84

96<h3 id="get-a-notice-when-another-session-goes-idle">85<h3 id="get-a-notice-when-another-session-goes-idle">

97 当另一个会话变为空闲时获得通知86 当另一个会话变为空闲时获得通知

98</h3>87</h3>

99 88

100Claude 可以要求你在这台机器上的一个会话在该会话下一次变为空闲或退出时发回一个通知。空闲在这里意味着会话完成了一个轮次，没有任何排队。当你在另一个会话中等待长任务并想听到它完成时而不是检查时使用它。需要两个会话中的 Claude Code v2.1.236 或更高版本。89Claude 可以要求你在这台机器上的一个会话在该会话下一次变为空闲或退出时发回一条通知。这里的空闲意味着会话完成了一个轮次，没有任何排队的内容。当你在另一个会话中等待长任务并想听到它完成时而不是检查时使用它。需要两个会话中都有 Claude Code v2.1.236 或更高版本。

101 90

102<h4 id="ask-for-a-notice">91<h4 id="ask-for-a-notice">

103 请求通知92 请求通知

106告诉 Claude 你在等什么。这个提示要求来自迁移会话的通知：95告诉 Claude 你在等什么。这个提示要求来自迁移会话的通知：

107 96

108```text wrap theme={null}97```text wrap theme={null}

109Tell me when the migration session finishes what it's working on98告诉我迁移会话何时完成它正在处理的工作

110```99```

111 100

112Claude 使用 `SendMessage` 工具的 `notify_when_idle` 输入进行订阅，要么附加到它正在发送的消息，要么单独进行。单独进行时，Claude Code 订阅而不在被监视的会话中启动轮次或花费令牌，如果该会话已经空闲，则立即发送通知。附加到消息时，Claude Code 首先传递消息，然后稍后发送通知。101Claude 使用 `SendMessage` 工具的 `notify_when_idle` 输入订阅，要么附加到它正在发送的消息，要么单独订阅。单独订阅时，Claude Code 订阅而不在被监视的会话中启动轮次或花费令牌，如果该会话已经空闲，会立即发送通知。附加到消息时，Claude Code 先传递消息，然后稍后发送通知。

113 102

114<h4 id="what-each-session-shows">103<h4 id="what-each-session-shows">

115 每个会话显示什么104 每个会话显示什么

116</h4>105</h4>

117 106

118被监视的会话显示一行，说另一个进程要求在会话下一次空闲时被告知。要求的会话将通知显示为命名被监视会话的一行。该行可以包括该会话轮次完成的时间和该轮次的单行状态。如果要求的会话处于空闲状态，Claude Code 会用通知启动一个新轮次。107被监视的会话显示一行说另一个进程要求在会话下一次空闲时被告知。要求会话显示通知为一行命名被监视的会话。该行可以包括该会话轮次完成的时间和该轮次的单行状态。如果要求会话处于空闲状态，Claude Code 会用通知启动新的轮次。

119 108

120<h4 id="limits">109<h4 id="limits">

121 限制110 限制

122</h4>111</h4>

123 112

124通知是一次性的：Claude Code 从被监视的会话发送一次，两个会话都不会相互轮询。如果在 12 小时内没有通知到达，Claude Code 会删除订阅并告诉 Claude，所以它不会继续等待。113如果在 12 小时内没有通知到达，Claude Code 会删除订阅并告诉 Claude，所以它不会继续等待。

125 114

126每一方的 [入站控制](#control-inbound-messages) 适用于像消息一样的通知：115每一方的 [入站控制](#control-inbound-messages) 适用于像消息一样的通知：

127 116

128* **任一方的 `refuse`**：什么都不会到达。被监视的会话在不记录或回答的情况下删除请求，所以订阅在 12 小时后无答复过期，具有 `refuse` 的要求会话永远不会订阅。117* **任一方的 `refuse`**：什么都不会到达。被监视的会话删除请求而不记录或回答它，所以订阅在 12 小时后无答复过期，具有 `refuse` 的要求会话永远不会订阅。

129* **任一方的 `hold`**：通知到达时内容较少。被监视的会话省略单行状态，要求的会话在你的记录中显示通知而不将其传递给 Claude。118* **任一方的 `hold`**：通知到达时内容较少。被监视的会话省略单行状态，要求会话在你的记录中显示通知而不将其传递给 Claude。

130 119

131只有你主要对话中的 Claude 可以订阅，并且仅限于你在这台机器上的会话。当子代理或代理团队队友设置 `notify_when_idle` 时，Claude Code 不会进行订阅并告诉它这样做。当 Claude 要求来自任何其他代理的通知时，例如队友、子代理或这台机器之外的会话，Claude Code 拒绝整个调用，包括附加到它的任何消息，并向 Claude 报告拒绝，以便它可以在没有请求的情况下重新发送消息。120只有你主要对话中的 Claude 可以订阅，并且仅订阅你在这台机器上的会话。当 Claude 要求来自任何其他目标的通知时，例如队友、子代理或这台机器之外的会话，Claude Code 拒绝整个调用，包括附加到它的任何消息。

132 121

133<h3 id="see-which-sessions-claude-can-reach">122<h3 id="see-which-sessions-claude-can-reach">

134 查看 Claude 可以到达的会话123 查看 Claude 可以到达的会话

135</h3>124</h3>

136 125

137Claude 自己找到消息的目标，所以你不需要在要求它发送之前运行任何东西。要自己查看 Claude 可以到达的会话，运行 `/list-agents` 命令。第一行（如果存在）是此会话自己的名称，你的其他会话用来向它发送消息的名称。下面的行是 Claude 可以到达的会话：126Claude 自己找到消息的目标，所以你不需要在要求它发送之前运行任何东西。要自己查看 Claude 可以到达的会话，运行 `/list-agents` 命令。第一行（如果存在）是这个会话自己的名称，你的其他会话用来向它发送消息的名称。下面的行是 Claude 可以到达的会话：

138 127

139* **子代理**：在当前会话内运行的代理。128* **子代理**：在当前会话内运行的代理。

140* **队友**：此会话自己的 [代理团队](/docs/zh-CN/agent-teams) 队友。在 v2.1.239 之前，队友没有出现在列表中，尽管 Claude 已经可以按名称向他们发送消息。129* **队友**：这个会话自己的 [代理团队](/docs/zh-CN/agent-teams) 队友。

141* **你的其他本地会话**：在同一台机器上运行的 Claude Code 会话，包括 [后台会话](/docs/zh-CN/agent-view)。会话仅在绑定 [收件箱套接字](#the-sessions-inbox-socket) 时出现。130* **你的其他本地会话**：在同一台机器上运行的 Claude Code 会话，包括 [后台会话](/docs/zh-CN/agent-view)。会话仅在绑定 [收件箱套接字](#the-sessions-inbox-socket) 时出现。

142* **你的 [云会话](/docs/zh-CN/claude-code-on-the-web)**：在此会话连接到 [远程控制](/docs/zh-CN/remote-control) 时显示。Claude Code 在列表中将它们标记为 `cloud`。131* **你的 [云会话](/docs/zh-CN/claude-code-on-the-web)**：在此会话连接到 [远程控制](/docs/zh-CN/remote-control) 时显示。

143* **你在其他机器上的远程控制会话**：在此会话连接到 [远程控制](/docs/zh-CN/remote-control) 时显示，并标记为 `Remote Control`。Claude Code 显示 `offline` 作为远程控制连接已断开的会话的状态。132* **你在其他机器上的远程控制会话**：在此会话连接到 [远程控制](/docs/zh-CN/remote-control) 时显示，并标记为 `Remote Control`。Claude Code 显示 `offline` 作为远程控制连接已断开的会话的状态。

144 133

145此会话不是行之一。如果 Claude 将消息寻址到此会话自己的名称，Claude Code 会拒绝它并告诉 Claude 目标是当前会话。在 v2.1.239 之前，列表没有显示此会话的名称，Claude Code 报告发送给它的消息为它找不到的代理。134当此会话连接到 [远程控制](/docs/zh-CN/remote-control) 时，Claude Code 从 `/list-agents` 输出中隐瞒你的本地会话的一些详细信息，而不改变 Claude 本身在寻找要向其发送消息的会话时看到的内容：

~~146~~

147当此会话连接到 [远程控制](/docs/zh-CN/remote-control) 时，Claude Code 从 `/list-agents` 输出中隐瞒你的本地会话的一些详细信息，而不改变 Claude 本身在寻找会话发送消息时看到的内容：

148 135

149* **工作目录**：它省略了每个本地会话的工作目录。136* **工作目录**：它省略每个本地会话的工作目录。

150* **会话名称**：它省略了任何它无法归因于某个人的会话名称，所以没有名称的行读作 `(unnamed session)`。137* **会话名称**：它省略任何它不能归属于某个人的会话名称，所以没有名称的行读作 `(unnamed session)`。

151* **第一行**：它省略了此会话自己的名称行，除非你在此终端输入了该名称，使用 `--name` 或使用 `/rename` 和名称，因为你启动或最后恢复了会话。138* **第一行**：它省略包含此会话自己名称的行，除非你在此终端用 `--name` 或 `/rename` 和名称输入了该名称，自从你启动或最后恢复会话以来。

152 139

153当输出列出任何内容时，它以一个说明详细信息被隐瞒的注释结束。在会话自己的键盘上运行 `/rename` 后跟未使用的名称会给该会话一个出现在输出中的名称。140当输出列出任何内容时，它以一条说明详细信息被隐瞒的注释结束。在会话自己的键盘上运行 `/rename` 后跟未使用的名称会给该会话一个出现在输出中的名称。

154 141

155Claude Code 首先读取你的云和远程控制会话列表最新的，并在每个会话后停止有限数量的页面。如果你的账户有超过适合的那些会话，Claude Code 不会列出较旧的会话，Claude 无法按名称向它们发送消息。当这种情况发生时，Claude Code 在列表中说明这一点，Claude 在发送消息时看到相同的注释。142会话响应你用 [`/rename`](/docs/zh-CN/commands) 命令或 [`--name`](/docs/zh-CN/cli-reference#cli-flags) 标志设置的名称。当你不设置一个时，Claude Code 自己命名会话。对于交互式会话，这是在 [运行会话的列表](/docs/zh-CN/sessions#name-your-sessions) 中显示的名称。

156 143

157Claude 按名称寻址这台机器之外的会话，就像本地会话一样。有关这些消息如何传播，请参见 [向其他机器上的会话发送消息](#message-sessions-on-other-machines)。144当你重命名会话，或用另一个活跃会话在这台机器上已经使用的名称启动或恢复交互式会话时，Claude Code 将名称留给已经拥有它的会话，并 [将你的重命名为变体](/docs/zh-CN/sessions#name-your-sessions)。会话仍然可以共享名称，例如当其中一个运行早期版本的 Claude Code 或共享名称是 Claude Code 生成的名称时。除非此会话连接到远程控制，Claude Code 在 `/list-agents` 输出中显示每个本地会话的工作目录，所以当它们在不同目录中运行时，你可以区分同名会话。Claude 根据有多少活跃会话响应该名称，以两种方式之一寻址消息：

~~158~~

159会话响应你使用 [`/rename`](/docs/zh-CN/commands) 命令或 [`--name`](/docs/zh-CN/cli-reference#cli-flags) 标志设置的名称。当你不设置一个时，Claude Code 自己命名会话。对于交互式会话，这是 [运行会话的列表](/docs/zh-CN/sessions#name-your-sessions) 中显示的名称。

~~160~~

161当你重命名会话时，Claude Code 也会更新你的其他会话用来查找会话名称的共享记录。如果它无法更新该记录，它会在 `/rename` 输出中警告你其他会话可能仍然显示旧名称。使用 [`--debug`](/docs/zh-CN/cli-reference#cli-flags) 运行会话，Claude Code 会记录失败更新的原因。

~~162~~

163当你重命名会话或启动或恢复交互式会话时，使用这台机器上另一个活跃会话已经使用的名称，Claude Code 将名称留给已经拥有它的会话，并 [将你的重命名为变体](/docs/zh-CN/sessions#name-your-sessions)。会话仍然可以共享名称，例如当其中一个运行早期版本的 Claude Code 或共享名称是 Claude Code 生成的名称时。除非此会话连接到远程控制，Claude Code 在 `/list-agents` 输出中显示每个本地会话的工作目录，所以当它们在不同目录中运行时，你可以区分同名会话。Claude 以两种方式之一寻址消息，取决于有多少活跃会话响应该名称：

164 145

165* **一个会话响应该名称**：Claude Code 仅在名称上传递消息。146* **一个会话响应该名称**：Claude Code 仅在名称上传递消息。

166* **多个会话共享该名称，或 Claude Code 无法检查你的会话运行的所有地方**：Claude 为其列表的每一行添加一个短标识符，并在地址中使用标识符。147* **多个会话共享该名称，或 Claude Code 无法检查你的会话运行的所有地方**：Claude 为其列表的每一行添加一个短标识符，并在地址中使用该标识符。

167 148

168<h3 id="message-sessions-on-other-machines">149<h3 id="message-sessions-on-other-machines">

169 向其他机器上的会话发送消息150 向其他机器上的会话发送消息

175| :- | :- |156| :- | :- |

176| 在这台机器上 | 在 macOS 和 Linux 上通过每个会话的套接字，或在本机 Windows 上通过每个会话的命名管道，永远不通过 Anthropic 服务器 |157| 在这台机器上 | 在 macOS 和 Linux 上通过每个会话的套接字，或在本机 Windows 上通过每个会话的命名管道，永远不通过 Anthropic 服务器 |

177| 在你的另一台机器上 | 通过 Anthropic 服务器，通过该机器的 [远程控制](/docs/zh-CN/remote-control) 连接到达 |158| 在你的另一台机器上 | 通过 Anthropic 服务器，通过该机器的 [远程控制](/docs/zh-CN/remote-control) 连接到达 |

178| 在 [云](/docs/zh-CN/claude-code-on-the-web) 中 | 通过 Anthropic 服务器，直接到云会话 |159| 在 [云中](/docs/zh-CN/claude-code-on-the-web) | 通过 Anthropic 服务器，直接到云会话 |

~~179~~

180与你另一台机器上的会话开始对话需要 Claude Code v2.1.225 或更高版本和一个 [出现在列表中](#see-which-sessions-claude-can-reach) 的目标。在 v2.1.225 之前，Claude 只能回复从一个到达的消息。

181 160

182你可以向显示为 [列表](#see-which-sessions-claude-can-reach) 中 `offline` 的会话发送消息，其远程控制连接已断开的会话。发送通过，但消息仅在该会话的机器重新连接后到达。Claude 在发送时被告知这一点。161启动与你另一台机器上的会话的对话需要 Claude Code v2.1.225 或更高版本和一个 [出现在列表中](#see-which-sessions-claude-can-reach) 的目标。

183 162

184同机器传递在启用该功能的任何地方都有效。每个会话在磁盘上的文件中注册自己。当 Claude 列出或向你的本地会话发送消息时，Claude Code 读取这些文件以找到会话，所以两个会话只有在能看到相同文件时才能相互到达。163你可以向显示为 [列表](#see-which-sessions-claude-can-reach) 中 `offline` 的会话发送消息，其远程控制连接已断开的会话。发送通过，但消息仅在该会话的机器重新连接后到达。

185 164

186容器有自己的文件系统，所以容器内的会话和主机上的会话无法相互到达。同一容器内的两个会话仍然可以相互发送消息，包括在 [自托管运行器](/docs/zh-CN/self-hosted-environments) 上。WSL 2 内的会话和同一计算机上的本机 Windows 会话也无法相互到达，因为它们在不同的主目录下注册并在不同的套接字类型上侦听。165容器内的会话和主机上的会话无法相互到达。同一容器内的两个会话仍然可以相互发送消息，包括在 [自托管运行器](/docs/zh-CN/self-hosted-environments) 上。WSL 2 内的会话和同一计算机上的本机 Windows 会话也无法相互到达。

187 166

188当此会话连接到远程控制时，当你向你另一台机器上的会话发送消息时，Claude Code 在该会话的对话中显示消息，使用此会话的远程控制名称。该机器上的 Claude 可以回复该名称。例如，当此会话作为 `laptop-graceful-unicorn` 连接到远程控制并且你向你的桌面发送消息时，你在桌面会话中看到消息在 `laptop-graceful-unicorn` 下。167如果此会话在 Claude 发送到这台机器之外的会话时未连接到远程控制，消息仍然通过，但没有 [回复地址](#what-a-message-looks-like)，所以接收 Claude 无法回答它。

189 168

190如果此会话在 Claude 发送到这台机器之外的会话时未连接到远程控制，消息仍然通过，但没有 [回复地址](#what-a-message-looks-like)，所以接收 Claude 无法回答它。Claude 在发送时被告知这一点。169要在任何消息超出这台机器之前要求你的批准，设置 [`isolatePeerMachines`](#require-approval-for-cross-machine-messages)。

~~191~~

192要在任何消息超出此机器之前要求你的批准，设置 [`isolatePeerMachines`](#require-approval-for-cross-machine-messages)。

193 170

194<h2 id="how-a-session-treats-an-incoming-message">171<h2 id="how-a-session-treats-an-incoming-message">

195 会话如何处理传入消息172 会话如何处理传入消息

206 消息的样子183 消息的样子

207</h3>184</h3>

208 185

209当消息到达时，Claude Code 在对话中将其显示为暗淡的单行预览，预览行之后保留在对话中。预览包含发送者的名称和消息的第一行，当它很长时用 `…` 切割，如 `› Message from @api-worker: Schema migration finished (ctrl+o to expand)`。在 v2.1.247 之前，Claude Code 显示到达的消息的完整内容而不是预览。186当消息到达时，Claude Code 在对话中将其显示为暗淡的单行预览，预览行之后保留在对话中。预览包含发送者的名称和消息的第一行，当它很长时用 `…` 切割，如 `› Message from @api-worker: Schema migration finished (ctrl+o to expand)`。

210 187

211这两个中的任何一个都显示您完整的文本：188这两个中的任何一个都显示您完整的文本：

212 189

215 192

216预览仅缩短您看到的内容。无论您是否展开它，Claude 都读取完整消息。193预览仅缩短您看到的内容。无论您是否展开它，Claude 都读取完整消息。

217 194

218Claude 接收消息时带有发送者的名称和回复地址，除了[单向跨机器消息](#message-sessions-on-other-machines)，它不携带回复地址。除了名称和回复地址，接收 Claude 获得消息的文本，永远不是发送者的对话历史或文件。[消息传递](#message-delivery)涵盖文本中的 `@` 提及。195Claude 接收消息时带有发送者的名称和回复地址，除了[单向跨机器消息](#message-sessions-on-other-machines)，它不携带回复地址。

~~219~~

220[子代理](/docs/zh-CN/sub-agents)编写的消息在发送会话的名称下到达，消息文本中标识了子代理。对它的回复到达该会话的主要对话，而不是子代理。

221 196

222这个例子是一个 Claude 写给另一个的消息，当您展开它时其完整文本读作：197这个例子是一个 Claude 写给另一个的消息，当您展开它时其完整文本读作：

223 198

252* 当对话在 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 截止日期后保持无答案时，Claude Code 关闭它并删除消息。截止日期默认为五分钟。227* 当对话在 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 截止日期后保持无答案时，Claude Code 关闭它并删除消息。截止日期默认为五分钟。

253* 当没有终端附加到[后台会话](/docs/zh-CN/agent-view)时，Claude Code 将对话保留在截止日期之后。在您附加后，如果对话在完整截止日期期间保持无答案，Claude Code 关闭它并删除消息。228* 当没有终端附加到[后台会话](/docs/zh-CN/agent-view)时，Claude Code 将对话保留在截止日期之后。在您附加后，如果对话在完整截止日期期间保持无答案，Claude Code 关闭它并删除消息。

254* 如果此会话的权限模式类在消息被保留时改变，Claude Code 重新应用入站规则，传递它们现在接受的消息，并显示通知。229* 如果此会话的权限模式类在消息被保留时改变，Claude Code 重新应用入站规则，传递它们现在接受的消息，并显示通知。

255* 如果设置更改在消息被保留时使 `refuse` 适用，Claude Code 删除每条保留的消息并向它可以到达的每个发送者报告拒绝。

~~256~~

257当发送者是同一机器上的会话时，Claude Code 在接收者保留消息时向它发送通知，以及当接收者稍后传递、拒绝或过期它时的后续通知。通知到达发送 Claude，因此它知道不要继续等待另一个会话尚未读取的消息。

~~258~~

259在交互式发送会话中，通知出现在成绩单中。[`claude -p`](/docs/zh-CN/headless) 发送者在[流式输出](/docs/zh-CN/headless#stream-responses)中作为[信息性 `system` 消息](/docs/zh-CN/agent-sdk/typescript#sdkinformationalmessage)接收它。发送给 `claude -p` 发送者的通知需要 Claude Code v2.1.271 或更高版本。

260 230

261如果接收者拒绝消息，发送者的通知说接收者不接受跨会话消息，并告诉发送者的 Claude 不要等待或重新发送。231Claude Code 最多保留 100 条消息，超过那个删除最旧的。

~~262~~

263Claude Code 最多保留 100 条消息，与传递队列分开，超过那个删除最旧的。

264 232

265<h3 id="non-interactive-sessions">233<h3 id="non-interactive-sessions">

266 非交互式会话234 非交互式会话

275 243

276设置 `dialogExpiry` 为 `"never"` 以保留默认保留的消息直到会话结束。由显式 `hold` 设置保留的消息不过期；Claude Code 仅当稍后应用 `accept` 时才传递它。244设置 `dialogExpiry` 为 `"never"` 以保留默认保留的消息直到会话结束。由显式 `hold` 设置保留的消息不过期；Claude Code 仅当稍后应用 `accept` 时才传递它。

277 245

278当会话以仍然保留的消息结束时，Claude Code 向它可以到达的每个发送者报告它们已过期。在 v2.1.225 之前，`-p` 会话中没有截止日期适用：保留的消息保持保留，除非运行期间的权限模式更改传递它，以及以保留的消息结束的会话不向其发送者报告任何内容。

~~279~~

280要让 `-p` 工作者无人值守地接收消息，使用 `crossSessionInbound` 设置为 `accept` 在其 `--settings` 值中启动它。您的用户设置中的 `accept` 也有效，但适用于您运行的每个会话。246要让 `-p` 工作者无人值守地接收消息，使用 `crossSessionInbound` 设置为 `accept` 在其 `--settings` 值中启动它。您的用户设置中的 `accept` 也有效，但适用于您运行的每个会话。

281 247

282<h3 id="the-sessions-inbox-socket">248<h3 id="the-sessions-inbox-socket">

292* `/status` 在 `Peer address` 行中显示它。路径以 `uds:` 为前缀。258* `/status` 在 `Peer address` 行中显示它。路径以 `uds:` 为前缀。

293* Claude Code 将其导出到[钩子](/docs/zh-CN/hooks)和 Bash 命令作为 [`CLAUDE_CODE_MESSAGING_SOCKET`](/docs/zh-CN/env-vars#variables) 环境变量：259* Claude Code 将其导出到[钩子](/docs/zh-CN/hooks)和 Bash 命令作为 [`CLAUDE_CODE_MESSAGING_SOCKET`](/docs/zh-CN/env-vars#variables) 环境变量：

294 * 在以消息传递启动的会话中，Claude Code 在任何钩子运行之前导出变量，包括 `SessionStart`。260 * 在以消息传递启动的会话中，Claude Code 在任何钩子运行之前导出变量，包括 `SessionStart`。

295 * 每个会话导出自己的套接字，永远不是从父会话继承的。

296 261

297在 macOS 和 Linux 上，Claude Code 将套接字限制为您的操作系统用户。在原生 Windows 上，它改为要求每个连接首先使用只有您的操作系统用户可以读取的密钥进行身份验证。无论哪种方式，在共享机器上，另一个用户的会话无法传递给它。262在 macOS 和 Linux 上，Claude Code 将套接字限制为您的操作系统用户。在原生 Windows 上，它改为要求每个连接首先使用只有您的操作系统用户可以读取的密钥进行身份验证。无论哪种方式，在共享机器上，另一个用户的会话无法传递给它。

298 263

305 270

306仅在您发布的消息准备好时打开连接。Claude Code 关闭在 30 秒内未发送完整行的连接，因此首先捕获慢速命令的输出，然后打开连接以发送它。271仅在您发布的消息准备好时打开连接。Claude Code 关闭在 30 秒内未发送完整行的连接，因此首先捕获慢速命令的输出，然后打开连接以发送它。

307 272

308下面的[自己的子消息规则](#own-child-messages)说明 Claude Code 何时查询令牌以及它如何处理它无法验证的消息。

~~309~~

310<span id="own-child-messages" />Claude Code 通过套接字上到达的消息运行与任何其他对等消息相同的[入站控制](#control-inbound-messages)，有一个例外和一个先决条件：273<span id="own-child-messages" />Claude Code 通过套接字上到达的消息运行与任何其他对等消息相同的[入站控制](#control-inbound-messages)，有一个例外和一个先决条件：

311 274

312* **自己的子消息**：当没有 `crossSessionInbound` 值适用时，Claude Code 传递它验证来自会话自己的子进程的消息，如钩子或 Bash 命令发布回自己会话的套接字。275* **自己的子消息**：当没有 `crossSessionInbound` 值适用时，Claude Code 传递它验证来自会话自己的子进程的消息，如钩子或 Bash 命令发布回自己会话的套接字。

380 * **云会话缺失**：云会话仅在此会话连接到[远程控制](/docs/zh-CN/remote-control)时出现。343 * **云会话缺失**：云会话仅在此会话连接到[远程控制](/docs/zh-CN/remote-control)时出现。

381 * **其他机器会话缺失**：您另一台机器上的会话仅在它使用[远程控制](/docs/zh-CN/remote-control)运行且此会话也连接时出现。344 * **其他机器会话缺失**：您另一台机器上的会话仅在它使用[远程控制](/docs/zh-CN/remote-control)运行且此会话也连接时出现。

382 * **其他机器会话 `offline`**：向列为 `offline` 的会话发送消息通过，但[仅在该会话的机器重新连接后到达](#message-sessions-on-other-machines)。345 * **其他机器会话 `offline`**：向列为 `offline` 的会话发送消息通过，但[仅在该会话的机器重新连接后到达](#message-sessions-on-other-machines)。

383 * **较旧的云或其他机器会话缺失**：Claude Code [首先读取这些会话列表最新的并在有限数量的页面后停止](#see-which-sessions-claude-can-reach)，因此 Claude 无法按名称向超过它们的会话发送消息。346 * **较旧的云或其他机器会话缺失**：Claude Code 首先读取这些会话列表最新的并在有限数量的页面后停止，因此 Claude 无法按名称向超过它们的会话发送消息。

384 * **启动对话**：[向其他机器上的会话发送消息](#message-sessions-on-other-machines)涵盖与超出此机器的会话启动对话。

385 347

386在具有消息传递的会话中，`/status` 也显示 `Peer address` 行，带有会话自己的收件箱地址，或 `unavailable` 和原因，当 Claude Code [无法设置收件箱](#the-sessions-inbox-socket)时。348在具有消息传递的会话中，`/status` 也显示 `Peer address` 行，带有会话自己的收件箱地址，或 `unavailable` 和原因，当 Claude Code [无法设置收件箱](#the-sessions-inbox-socket)时。

387 349

393 355

394* **仅纯文本**：Claude 仅在会话之间发送纯文本。结构化[代理团队](/docs/zh-CN/agent-teams)协议消息保留在团队内。356* **仅纯文本**：Claude 仅在会话之间发送纯文本。结构化[代理团队](/docs/zh-CN/agent-teams)协议消息保留在团队内。

395* **同机器消息大小有上限**：Claude Code 拒绝到此机器上的会话的消息，一旦其序列化形式超过约一百万个字符。拒绝[命名确切大小](/docs/zh-CN/errors#message-too-large-for-cross-session-delivery)。什么都不到达接收会话。357* **同机器消息大小有上限**：Claude Code 拒绝到此机器上的会话的消息，一旦其序列化形式超过约一百万个字符。拒绝[命名确切大小](/docs/zh-CN/errors#message-too-large-for-cross-session-delivery)。什么都不到达接收会话。

396* **对一个会话的快速突发在发送者处被拒绝**：一旦对此机器上的会话的快速突发消息达到该会话的收件箱接受的内容，Claude Code 拒绝发送会话中的进一步发送。[拒绝命名突发](/docs/zh-CN/errors#too-many-messages-to-this-session-just-now)并告诉 Claude 将其余的批处理为一条消息或等待。在 v2.1.236 之前，Claude Code 报告这些发送为已发送，而接收会话删除它们。358* **对一个会话的快速突发在发送者处被拒绝**：一旦对此机器上的会话的快速突发消息达到该会话的收件箱接受的内容，Claude Code 拒绝发送会话中的进一步发送。[拒绝命名突发](/docs/zh-CN/errors#too-many-messages-to-this-session-just-now)并告诉 Claude 将其余的批处理为一条消息或等待。

397* **消息循环被限制**：在接收会话中，Claude Code 对每个发送者的重复消息进行速率限制，删除在短窗口内到达的相同重复，并最多为 Claude 读取排队 50 条接受的消息。因此两个会话之间的消息循环自己停止。当速率限制、重复检查或队列上限从此机器上的交互式会话删除消息时，Claude Code 告诉该会话哪个删除了它，并告诉其 Claude 不要立即重新发送。359* **消息循环被限制**：在接收会话中，Claude Code 对每个发送者的重复消息进行速率限制，删除在短窗口内到达的相同重复，并最多为 Claude 读取排队 50 条接受的消息。因此两个会话之间的消息循环自己停止。

398 360

399<h2 id="related-resources">361<h2 id="related-resources">

400 相关资源362 相关资源

403* [子代理](/docs/zh-CN/sub-agents#resume-subagents)和[代理团队](/docs/zh-CN/agent-teams#messages-between-agents)：单个会话或团队内的消息传递365* [子代理](/docs/zh-CN/sub-agents#resume-subagents)和[代理团队](/docs/zh-CN/agent-teams#messages-between-agents)：单个会话或团队内的消息传递

404* [后台代理](/docs/zh-CN/agent-view)：分派和监控您可能向其发送消息的并行会话366* [后台代理](/docs/zh-CN/agent-view)：分派和监控您可能向其发送消息的并行会话

405* [远程控制](/docs/zh-CN/remote-control)：连接此会话以到达您在其他机器上的会话367* [远程控制](/docs/zh-CN/remote-control)：连接此会话以到达您在其他机器上的会话

368* [频道](/docs/zh-CN/channels)：将外部事件（如 CI 结果或聊天消息）推送到会话中

406* [设置](/docs/zh-CN/settings-reference#all-settings)：`crossSessionInbound`、`isolatePeerMachines` 和 `dialogExpiry`369* [设置](/docs/zh-CN/settings-reference#all-settings)：`crossSessionInbound`、`isolatePeerMachines` 和 `dialogExpiry`

407* [权限模式](/docs/zh-CN/permission-modes)：入站默认的两个类背后的模式370* [权限模式](/docs/zh-CN/permission-modes)：入站默认的两个类背后的模式

408* [工具参考](/docs/zh-CN/tools-reference)：工具表中的 `ListAgents` 和 `SendMessage` 行371* [工具参考](/docs/zh-CN/tools-reference)：工具表中的 `ListAgents` 和 `SendMessage` 行

data-usage.md +2 −2

Details

110 110

111使用[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)时，会话默认在 Anthropic 管理的虚拟机中运行，而不是在本地运行。您的组织路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话在您控制的基础设施上运行；有关哪些内容保留在您的机器上以及哪些内容仍然流向 Anthropic，请参阅[哪些内容保留在您的基础设施上](/docs/zh-CN/self-hosted-environments#what-stays-on-your-infrastructure)。在 Anthropic 托管的云会话中：111使用[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)时，会话默认在 Anthropic 管理的虚拟机中运行，而不是在本地运行。您的组织路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话在您控制的基础设施上运行；有关哪些内容保留在您的机器上以及哪些内容仍然流向 Anthropic，请参阅[哪些内容保留在您的基础设施上](/docs/zh-CN/self-hosted-environments#what-stays-on-your-infrastructure)。在 Anthropic 托管的云会话中：

112 112

113* \*\*代码和数据存储：\*\*您的存储库被克隆到隔离的 VM。代码和会话数据受您的账户类型的保留和使用政策约束（请参阅上面的数据保留部分）113* \*\*代码和数据存储：\*\*您的存储库被克隆到隔离的 VM。Anthropic 存储会话记录，以便您稍后可以返回该会话。代码和会话数据受您的账户类型的[数据保留](#data-retention)和使用政策约束

114* \*\*凭证：\*\*GitHub 身份验证通过安全代理处理；您的 GitHub 凭证永远不会进入沙箱114* \*\*凭证：\*\*GitHub 凭证在 Anthropic 的服务器上加密存储，永远不会进入 VM。来自 VM 的 GitHub 流量通过 Anthropic 代理，该代理在服务器端附加凭证

115* \*\*网络流量：\*\*所有出站流量都通过安全代理进行审计日志记录和滥用防止115* \*\*网络流量：\*\*所有出站流量都通过安全代理进行审计日志记录和滥用防止

116* \*\*会话数据：\*\*提示、代码更改和输出遵循与本地 Claude Code 使用相同的数据政策116* \*\*会话数据：\*\*提示、代码更改和输出遵循与本地 Claude Code 使用相同的数据政策

117 117

desktop.md +12 −4

Details

735 735

736要在任何平台上为本地会话和开发服务器设置环境变量，在提示框中打开环境下拉菜单，将鼠标悬停在 **Local** 上，然后点击齿轮图标来打开本地环境编辑器。你在此处保存的变量在你的机器上加密存储，并适用于你启动的每个本地会话和预览服务器。你也可以将变量添加到你的 `~/.claude/settings.json` 文件中的 `env` 键，尽管这些仅到达 Claude 会话而不是开发服务器。有关支持的变量的完整列表，请参阅[环境变量](/docs/zh-CN/env-vars)。736要在任何平台上为本地会话和开发服务器设置环境变量，在提示框中打开环境下拉菜单，将鼠标悬停在 **Local** 上，然后点击齿轮图标来打开本地环境编辑器。你在此处保存的变量在你的机器上加密存储，并适用于你启动的每个本地会话和预览服务器。你也可以将变量添加到你的 `~/.claude/settings.json` 文件中的 `env` 键，尽管这些仅到达 Claude 会话而不是开发服务器。有关支持的变量的完整列表，请参阅[环境变量](/docs/zh-CN/env-vars)。

737 737

738[Extended thinking](/docs/zh-CN/model-config#extended-thinking)默认启用，这改进了复杂推理任务的性能，但使用额外的令牌。在 Anthropic API 上，在本地环境编辑器中将 `MAX_THINKING_TOKENS` 设置为 `0` 来关闭思考；这对 Opus 5.5 或 Fable 模型没有影响，它们始终使用 extended thinking。在 Anthropic API 上关闭思考后，Claude Code 发送努力级别 `high` 而不是更高级别给它知道的[不接受该组合](/docs/zh-CN/errors#effort-isnt-available-with-thinking-turned-off)的模型，例如 Opus 5。738[Extended thinking](/docs/zh-CN/model-config#extended-thinking)默认启用，这改进了复杂推理任务的性能，但使用额外的令牌。在 Anthropic API 上，在本地环境编辑器中将 `MAX_THINKING_TOKENS` 设置为 `0` 来关闭思考；这对 Opus 5.5、Sonnet 5.5 或 Fable 模型没有影响，它们始终使用 extended thinking。在 Anthropic API 上关闭思考后，Claude Code 发送努力级别 `high` 而不是更高级别给它知道的[不接受该组合](/docs/zh-CN/errors#effort-isnt-available-with-thinking-turned-off)的模型，例如 Opus 5。

739 739

740在具有[自适应推理](/docs/zh-CN/model-config#adjust-effort-level)的模型上，除 `0` 外的 `MAX_THINKING_TOKENS` 值被忽略，因为自适应推理控制思考深度。在 Opus 4.6 和 Sonnet 4.6 上，设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 为 `1` 来使用固定思考预算；Fable 模型、Sonnet 5 和 Opus 4.7 及更高版本始终使用自适应推理，没有固定预算模式。740在具有[自适应推理](/docs/zh-CN/model-config#adjust-effort-level)的模型上，除 `0` 外的 `MAX_THINKING_TOKENS` 值被忽略，因为自适应推理控制思考深度。在 Opus 4.6 和 Sonnet 4.6 上，设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 为 `1` 来使用固定思考预算；Fable 模型、Sonnet 5 及更高版本和 Opus 4.7 及更高版本始终使用自适应推理，没有固定预算模式。

741 741

742<h4 id="local-sessions-on-managed-devices">742<h4 id="local-sessions-on-managed-devices">

743 托管设备上的本地会话743 托管设备上的本地会话

932 身份验证和 SSO932 身份验证和 SSO

933</h3>933</h3>

934 934

935企业组织可以要求所有用户使用 SSO。有关计划级别的详细信息，请参阅[身份验证](/docs/zh-CN/authentication)，有关 SAML 配置，请参阅[设置 SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso)；OIDC 设置在 [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide) 中介绍。935Team 和 Enterprise 组织可以要求所有用户使用 SSO。有关计划级别的详细信息，请参阅[身份验证](/docs/zh-CN/authentication)，有关 SAML 配置，请参阅[设置 SSO](https://support.claude.com/en/articles/13132885-setting-up-single-sign-on-sso)；OIDC 设置在 [Claude Enterprise Administrator Guide](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide) 中介绍。

936 936

937<h3 id="data-handling">937<h3 id="data-handling">

938 数据处理938 数据处理

961 961

962要将 CLI 会话移动到 Desktop，在终端中运行 `/desktop`。Claude 保存你的会话并在桌面应用中打开它，然后退出 CLI。此命令在 macOS 和 x64 Windows 上可用，当你使用 Claude 订阅登录时。它不适用于 API 密钥身份验证或 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。962要将 CLI 会话移动到 Desktop，在终端中运行 `/desktop`。Claude 保存你的会话并在桌面应用中打开它，然后退出 CLI。此命令在 macOS 和 x64 Windows 上可用，当你使用 Claude 订阅登录时。它不适用于 API 密钥身份验证或 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。

963 963

964要从 Desktop 内部选择 CLI 会话，在提示框中输入 `/resume`。Desktop 列出你从 CLI 启动的会话，你可以按标题、文件夹或分支搜索它们，并预览每个会话的停止位置。选择一个会话，它将在应用中继续，具有完整的对话和上下文。964你也可以从 Desktop 内部使用 `/resume` 选择 CLI 会话。此命令在本地会话中可用，不在 SSH、WSL 或云会话中可用。

965

966要在 Desktop 中继续终端会话：

967

9681. 在终端中关闭会话。

9692. 在 Desktop 提示框中，输入 `/resume`。Desktop 列出你从 CLI 在此计算机上启动的会话。按标题、文件夹或分支搜索，并预览每个会话的停止位置。

9703. 选择会话。它在应用中继续，具有完整的对话和上下文。

971

972Desktop 继续相同的会话而不是副本，所以之后在终端中 `claude --resume` 仍然可以找到它。

965 973

966<Tip>974<Tip>

967 何时使用 Desktop vs CLI：当你想要管理一个窗口中的并行会话、并排排列窗格或可视化审查更改时，使用 Desktop。当你需要脚本、自动化或更喜欢终端工作流时，使用 CLI。975 何时使用 Desktop vs CLI：当你想要管理一个窗口中的并行会话、并排排列窗格或可视化审查更改时，使用 Desktop。当你需要脚本、自动化或更喜欢终端工作流时，使用 CLI。

desktop-ios-simulator.md +21 −19

Details

23* Claude Desktop v1.24012.0 或更高版本23* Claude Desktop v1.24012.0 或更高版本

24* 一台 Mac，因为 Apple 的 iOS Simulator 仅在 macOS 上运行24* 一台 Mac，因为 Apple 的 iOS Simulator 仅在 macOS 上运行

25* [Xcode](https://developer.apple.com/xcode/)，其中安装了 iOS 平台，它提供模拟器设备。如果 Xcode 还没有列出任何模拟器，请参阅[模拟器窗格显示未找到模拟器](#the-simulator-pane-says-no-simulators-were-found)25* [Xcode](https://developer.apple.com/xcode/)，其中安装了 iOS 平台，它提供模拟器设备。如果 Xcode 还没有列出任何模拟器，请参阅[模拟器窗格显示未找到模拟器](#the-simulator-pane-says-no-simulators-were-found)

26 * 使用 Xcode 26.x。该窗格还不能与 Xcode 27 一起使用，Xcode 27 用 Device Hub 替换了 Simulator 应用。如果 `xcode-select` 在你的 Mac 上指向 Xcode 27，请参阅[模拟器窗格在 Xcode 27 中失败](#the-simulator-pane-fails-with-xcode-27)26 * 推荐使用 Xcode 26.x 或 Xcode 27，该窗格可与两者一起使用。如果你安装了多个 Xcode，请参阅[选择模拟器窗格使用的 Xcode](#choose-which-xcode-the-simulator-pane-uses)

27 27

28<Note>28<Note>

29 在本页上，"设备"指的是模拟的 iPhone 或 iPad，是你在 Xcode 中的**Window → Devices and Simulators** 下管理的相同模拟器设备之一，而不是物理硬件。29 在本页上，"设备"指的是模拟的 iPhone 或 iPad，是你在 Xcode 中的**Window → Devices and Simulators** 下管理的相同模拟器设备之一，而不是物理硬件。

31 31

32模拟器窗格仅在本地会话中可用。在[云](/docs/zh-CN/desktop#run-long-running-tasks-in-the-cloud)和 [SSH](/docs/zh-CN/desktop#ssh-sessions) 会话中，Claude 在无法访问 Mac 上模拟器的机器上运行。32模拟器窗格仅在本地会话中可用。在[云](/docs/zh-CN/desktop#run-long-running-tasks-in-the-cloud)和 [SSH](/docs/zh-CN/desktop#ssh-sessions) 会话中，Claude 在无法访问 Mac 上模拟器的机器上运行。

33 33

34<h3 id="choose-which-xcode-the-simulator-pane-uses">

35 选择模拟器窗格使用的 Xcode

36</h3>

38如果你安装了多个 Xcode，例如 Xcode 26.x 与 Xcode 27 并行安装，该窗格使用 `xcode-select` 指向的任何一个。要使用不同的安装，请按其路径选择它。

40例如，如果你想要的 Xcode 安装为 `/Applications/Xcode-26.4.app`，请在终端中运行以下命令：

42```bash theme={null}

43sudo xcode-select -s /Applications/Xcode-26.4.app

44```

46然后退出并重新打开 Claude Desktop，以便该窗格使用新选择的 Xcode。

48要检查选择了哪个安装，请运行 `xcode-select -p`。它会打印所选安装的 Developer 文件夹，例如 `/Applications/Xcode-26.4.app/Contents/Developer`。

34<h2 id="run-your-app-in-the-simulator">50<h2 id="run-your-app-in-the-simulator">

35 在模拟器中运行你的应用51 在模拟器中运行你的应用

36</h2>52</h2>

59 75

60模拟器窗格显示应用实际启动的任何设备。要在特定设备上测试，在你的请求中命名它，例如"在 iPhone SE 模拟器上运行它"，Claude 在构建和启动时会针对该设备。76模拟器窗格显示应用实际启动的任何设备。要在特定设备上测试，在你的请求中命名它，例如"在 iPhone SE 模拟器上运行它"，Claude 在构建和启动时会针对该设备。

61 77

~~62Claude 启动的设备也会出现在 Apple 的 Simulator 应用中，Claude 可以在你已经启动的设备上安装应用。~~78Claude 启动的设备也会出现在 Apple 的 Simulator 应用中，或在 Xcode 27 的 Device Hub 中。Claude 可以在你已经启动的设备上安装应用。

63 79

64你也可以自己打开模拟器窗格。一旦会话有模拟器连接或已编辑 Swift 文件，会话工具栏中的**Views** 菜单会显示 **iOS Simulator** 条目。如果窗格还没有显示设备，请单击**Attach simulator**，或从它旁边的设备菜单中选择特定设备；选择关闭的设备会启动它。如果 Xcode 或其模拟器缺失，窗格会显示设置步骤，并在你完成每个步骤时检查它们。80你也可以自己打开模拟器窗格。一旦会话有模拟器连接或已编辑 Swift 文件，会话工具栏中的**Views** 菜单会显示 **iOS Simulator** 条目。如果窗格还没有显示设备，请单击**Attach simulator**，或从它旁边的设备菜单中选择特定设备；选择关闭的设备会启动它。如果 Xcode 或其模拟器缺失，窗格会显示设置步骤，并在你完成每个步骤时检查它们。

65 81

84 会话如何管理设备100 会话如何管理设备

85</h2>101</h2>

86 102

87每个设备属于启动它的会话，因此[并行会话](/docs/zh-CN/desktop#work-in-parallel-with-sessions)不共享设备：你在一个会话的窗格中看到的内容反映该会话的工作，而不是另一个的。在侧栏中切换会话会切换模拟器视图以及对话，切换回来会在它停止的地方恢复同一设备。如果 Claude 使用多个设备，每个都会打开自己的窗格，每个会话最多 4 个。103每个设备属于启动它的会话，因此[并行会话](/docs/zh-CN/desktop#work-in-parallel-with-sessions)不共享设备：你在一个会话的窗格中看到的内容反映的是该会话的工作，而不是另一个会话的工作。在侧边栏中切换会话会同时切换模拟器视图和对话，切换回来会恢复同一设备停止的地方。如果 Claude 使用多个设备，每个设备都会打开自己的窗格，每个会话最多 4 个。

88 104

89Claude Code Desktop 在模拟器不再使用时关闭它启动的模拟器：当你退出应用时、当你存档会话时，或在你从其窗格分离设备后 10 分钟。你自己启动的设备，无论是从窗格还是在 Apple 的 Simulator 应用中，永远不会自动关闭。要立即关闭连接的设备，请使用窗格中的关闭按钮。105Claude Code Desktop 会在模拟器不再使用时关闭它启动的模拟器：当你退出应用时、当你归档会话时，或在你从窗格中分离设备后 10 分钟。你在 Claude Code Desktop 外启动的设备，例如在 Apple 的 Simulator 应用或 Device Hub 中启动的设备，永远不会自动关闭。要立即关闭附加的设备，请使用窗格中的关闭按钮。

90 106

91<h2 id="grant-claude-access-to-a-device">107<h2 id="grant-claude-access-to-a-device">

92 授予 Claude 对设备的访问权限108 授予 Claude 对设备的访问权限

150 模拟器窗格显示未找到模拟器166 模拟器窗格显示未找到模拟器

151</h3>167</h3>

152 168

153如果 `xcode-select` 指向 Xcode 27，窗格可能报告未找到模拟器，即使设备存在；请参阅[模拟器窗格在 Xcode 27 中失败](#the-simulator-pane-fails-with-xcode-27)。否则，Xcode 已安装但没有 iOS 模拟器可列出。模拟器窗格显示要遵循的设置步骤，并在每个步骤完成时检查它们。要手动安装缺失的部分，从 Xcode 的设置中下载 iOS 模拟器运行时，或运行 `xcodebuild -downloadPlatform iOS`。169Xcode 已安装但没有 iOS 模拟器可列出。模拟器窗格显示要遵循的设置步骤，并在每个步骤完成时检查它们。要手动安装缺失的部分，从 Xcode 的设置中下载 iOS 模拟器运行时，或运行 `xcodebuild -downloadPlatform iOS`。

~~154~~

155<h3 id="the-simulator-pane-fails-with-xcode-27">

156 模拟器窗格在 Xcode 27 中失败

157</h3>

~~158~~

159窗格还不能与 Xcode 27 一起使用，Xcode 27 用 Device Hub 替换了 Simulator 应用。选择 Xcode 27 后，连接设备失败，或窗格报告未找到模拟器，即使设备存在。

~~160~~

161窗格使用 `xcode-select` 指向的任何 Xcode。如果 Xcode 27 是你唯一的安装，首先在其旁边安装 Xcode 26.x。然后通过其路径选择 26.x 安装。例如，如果它安装为 `/Applications/Xcode-26.4.app`：

~~162~~

163```bash theme={null}

164sudo xcode-select -s /Applications/Xcode-26.4.app

165```

~~166~~

167运行 `xcode-select -p` 以检查选择了哪个安装。

168 170

169<h2 id="see-also">171<h2 id="see-also">

170 另请参阅172 另请参阅

desktop-linux.md +1 −1

Details

158* 所有缺失的依赖关系都显示 `not installable`，带有 `:amd64` 或 `:arm64` 后缀：您下载的 `.deb` 与您的机器架构不同。运行 `dpkg --print-architecture` 并下载匹配的 `.deb`，或[从 apt 存储库安装](#install)，它会为您的架构选择软件包。158* 所有缺失的依赖关系都显示 `not installable`，带有 `:amd64` 或 `:arm64` 后缀：您下载的 `.deb` 与您的机器架构不同。运行 `dpkg --print-architecture` 并下载匹配的 `.deb`，或[从 apt 存储库安装](#install)，它会为您的架构选择软件包。

159 159

160<h3 id="running-as-root-without-no-sandbox-is-not-supported">160<h3 id="running-as-root-without-no-sandbox-is-not-supported">

161 以 root 身份运行而不使用 --no-sandbox 不受支持161 以 root 身份运行而不使用 `--no-sandbox` 不受支持

162</h3>162</h3>

163 163

164如果 `claude-desktop` 以此消息退出，说明您以 root 身份启动了它。以普通用户身份登录并从那里启动它。164如果 `claude-desktop` 以此消息退出，说明您以 root 身份启动了它。以普通用户身份登录并从那里启动它。

desktop-quickstart.md +8 −7

Details

4 4

5# 开始使用桌面应用5# 开始使用桌面应用

6 6

~~7> 在桌面上安装 Claude Code 并开始您的第一个编码会话~~7> 安装 Claude 桌面应用，打开 Code 选项卡，并在您计算机上的项目文件夹中开始您的第一个 Claude Code 会话。

8 8

9桌面应用为您提供具有图形界面的 Claude Code，专为并行运行多个会话而构建：用于管理并行工作的侧边栏、带有集成终端和文件编辑器的拖放布局、可视化差异审查、实时应用预览、GitHub PR 监控和自动合并以及计划任务。无需终端。9桌面应用为您提供具有图形界面的 Claude Code，因此您可以要求 Claude 处理计算机上文件夹中的代码，并查看其更改，而无需使用终端。本页面将指导您安装应用并在 **Code** 选项卡中开始您的第一个会话。Claude Code 需要 [Pro、Max、Team 或 Enterprise 订阅](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=desktop_quickstart_pricing)。

10 10

11<CardGroup cols={3}>11<CardGroup cols={3}>

12 <Card title="下载 macOS 版本" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">12 <Card title="下载 macOS 版本" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">

25对于 Windows ARM64，请下载 [ARM64 安装程序](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs)。在 Linux 上，使用 apt 安装；请参阅 [Claude Desktop on Linux](/docs/zh-CN/desktop-linux)。25对于 Windows ARM64，请下载 [ARM64 安装程序](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs)。在 Linux 上，使用 apt 安装；请参阅 [Claude Desktop on Linux](/docs/zh-CN/desktop-linux)。

26 26

27<Note>27<Note>

~~28 Claude Code 需要 [Pro、Max、Team 或 Enterprise 订阅](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=desktop_quickstart_pricing)。~~28 这些情况在其他页面中有介绍：

~~29</Note>~~

30 29

~~31本页面将指导您安装应用并开始您的第一个会话。如果您已经设置完成，请参阅[使用 Claude Code Desktop](/docs/zh-CN/desktop)了解完整参考。~~30 * **已经设置完成**：请参阅[使用 Claude Code Desktop](/docs/zh-CN/desktop)了解 Code 选项卡可以执行的所有操作

31 * **想在您的终端中使用 `claude`**：[单独安装 CLI](/docs/zh-CN/quickstart)

32</Note>

32 33

33桌面应用有三个选项卡：34桌面应用有三个选项卡：

34 35

35* **Chat**：无文件访问权限的常规对话，类似于 claude.ai。36* **Chat**：无文件访问权限的常规对话，类似于 claude.ai。

36* **Cowork**：一个自主后台代理，在沙箱虚拟机中处理任务，拥有自己的环境，可以独立运行，而您可以进行其他工作。本地 Cowork 会话在您的计算机上运行虚拟机；远程 Cowork 会话改为在 Anthropic 管理的虚拟机上运行。37* **Cowork**：一个自主后台代理，在您进行其他工作时独立处理任务。

37* **Code**：一个交互式编码助手，可直接访问您的本地文件。根据权限模式，您可以在 Claude 提出更改时批准每项更改，或在 Claude 进行更改后审查这些更改。38* **Code**：一个交互式编码助手，可直接访问您的本地文件。根据权限模式，您可以在 Claude 提出更改时批准每项更改，或在 Claude 进行更改后审查这些更改。

38 39

39Chat 和 Cowork 在 [Claude 帮助中心](https://support.claude.com/)中有介绍；安装和部署桌面应用在 [Claude Desktop 支持文章](https://support.claude.com/en/collections/16163169-claude-desktop)中有介绍。本页面重点关注 **Code** 选项卡。40Chat 和 Cowork 在 [Claude 帮助中心](https://support.claude.com/)中有介绍；安装和部署桌面应用在 [Claude Desktop 支持文章](https://support.claude.com/en/collections/16163169-claude-desktop)中有介绍。本页面重点关注 **Code** 选项卡。

52 </Step>53 </Step>

53</Steps>54</Steps>

54 55

~~55桌面应用包含 Claude Code。您无需单独安装 Node.js 或 CLI。要从终端使用 `claude`，请单独安装 CLI。请参阅[开始使用 CLI](/docs/zh-CN/quickstart)。~~56桌面应用包含 Claude Code，因此您无需安装 Node.js 或 CLI 即可使用 Code 选项卡。

56 57

57<h2 id="start-your-first-session">58<h2 id="start-your-first-session">

58 开始您的第一个会话59 开始您的第一个会话

desktop-scheduled-tasks.md +1 −1

Details

61 61

62* **Manual**：无调度，仅在您单击 **Run now** 时运行。适用于保存您按需触发的提示62* **Manual**：无调度，仅在您单击 **Run now** 时运行。适用于保存您按需触发的提示

63* **Hourly**：每小时运行一次63* **Hourly**：每小时运行一次

~~64* **Daily**：显示时间选择器，默认为本地时间上午 9:00~~64* **Daily**：每天在您选择的本地时间运行

65* **Weekdays**：与 Daily 相同，但跳过星期六和星期日65* **Weekdays**：与 Daily 相同，但跳过星期六和星期日

66* **Weekly**：显示时间选择器和日期选择器66* **Weekly**：显示时间选择器和日期选择器

67 67

env-vars.md +12 −10

Details

237| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 在 v2.1.186 中删除，现在是无操作。以前为流式 API 请求的连接、TLS 和响应标头阶段设置单独的超时。使用 `API_TIMEOUT_MS` 获取每个请求的超时。对于流式请求的响应标头阶段，请参阅 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |237| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 在 v2.1.186 中删除，现在是无操作。以前为流式 API 请求的连接、TLS 和响应标头阶段设置单独的超时。使用 `API_TIMEOUT_MS` 获取每个请求的超时。对于流式请求的响应标头阶段，请参阅 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |

238| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆盖调试日志文件路径。尽管名称如此，这是文件路径，而不是目录。需要通过 `--debug`、`/debug` 或 `DEBUG` 环境变量单独启用调试模式：仅设置此变量不会启用日志记录。[`--debug-file`](/docs/zh-CN/cli-reference#cli-flags) 标志同时执行两者。默认为 `~/.claude/debug/<session-id>.txt` |238| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆盖调试日志文件路径。尽管名称如此，这是文件路径，而不是目录。需要通过 `--debug`、`/debug` 或 `DEBUG` 环境变量单独启用调试模式：仅设置此变量不会启用日志记录。[`--debug-file`](/docs/zh-CN/cli-reference#cli-flags) 标志同时执行两者。默认为 `~/.claude/debug/<session-id>.txt` |

239| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 写入调试日志文件的最小日志级别。值：`verbose`、`debug`（默认）、`info`、`warn`、`error`。设置为 `verbose` 以包含高容量诊断（如完整状态行命令输出），或提高到 `error` 以减少噪音 |239| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 写入调试日志文件的最小日志级别。值：`verbose`、`debug`（默认）、`info`、`warn`、`error`。设置为 `verbose` 以包含高容量诊断（如完整状态行命令输出），或提高到 `error` 以减少噪音 |

240| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 设置为 `1` 以禁用 [1M 上下文窗口](/docs/zh-CN/model-config#extended-context) 支持。设置时，1M 模型变体在模型选择器中不可用，Claude Code 将具有本机 1M 窗口的模型上的会话保持在 200K 窗口，例如 [Sonnet 5](/docs/zh-CN/model-config#sonnet-5-context-window) 和 Fable 模型；请参阅 [扩展上下文](/docs/zh-CN/model-config#extended-context) 了解如何强制执行保持。对于具有合规要求的企业环境很有用。对于其在为无法识别的 `[1m]` 模型 ID 纠正窗口中的作用，请参阅 [为网关或自定义模型 ID 纠正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |240| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 设置为 `1` 以禁用 [1M 上下文窗口](/docs/zh-CN/model-config#extended-context) 支持。设置时，1M 模型变体在模型选择器中不可用，Claude Code 将具有本机 1M 窗口的模型上的会话保持在 200K 窗口，例如 [Sonnet 5.5](/docs/zh-CN/model-config#sonnet-5-5-and-sonnet-5-context-window) 和 Fable 模型；请参阅 [扩展上下文](/docs/zh-CN/model-config#extended-context) 了解如何强制执行保持。对于具有合规要求的企业环境很有用。对于其在为无法识别的 `[1m]` 模型 ID 纠正窗口中的作用，请参阅 [为网关或自定义模型 ID 纠正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |

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

242| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | 设置为 `1` 以停止 Claude Code 在管理员源之间按键合并 [托管设置](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier) `env` 块，因此仅应用最高优先级源的整个 `env` 块，如 v2.1.223 之前的情况。在启动 Claude Code 的环境中设置它，因为 Claude Code 忽略通过设置 `env` 块传递的副本。需要 Claude Code v2.1.223 或更高版本 |242| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | 设置为 `1` 以停止 Claude Code 在管理员源之间按键合并 [托管设置](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier) `env` 块，因此仅应用最高优先级源的整个 `env` 块，如 v2.1.223 之前的情况。在启动 Claude Code 的环境中设置它，因为 Claude Code 忽略通过设置 `env` 块传递的副本。需要 Claude Code v2.1.223 或更高版本 |

243| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 设置为 `1` 以禁用 [advisor 工具](/docs/zh-CN/advisor)。`/advisor` 命令变为不可用，任何配置的 `advisorModel` 被忽略，`--advisor` 标志被接受但无效，因此传递它的现有脚本继续工作而不出错 |243| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 设置为 `1` 以禁用 [advisor 工具](/docs/zh-CN/advisor)。`/advisor` 命令变为不可用，任何配置的 `advisorModel` 被忽略，`--advisor` 标志被接受但无效，因此传递它的现有脚本继续工作而不出错 |

255| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 设置为 `1` 以保持 [Claude in Chrome](/docs/zh-CN/chrome) 浏览器工具可用，同时省略系统提示的 Chrome 部分和 `/claude-in-chrome` [捆绑 skill](/docs/zh-CN/skills#bundled-skills)。对于嵌入 Claude Code 并提供自己的浏览器指导的主机。需要 Claude Code v2.1.257 或更高版本 |255| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 设置为 `1` 以保持 [Claude in Chrome](/docs/zh-CN/chrome) 浏览器工具可用，同时省略系统提示的 Chrome 部分和 `/claude-in-chrome` [捆绑 skill](/docs/zh-CN/skills#bundled-skills)。对于嵌入 Claude Code 并提供自己的浏览器指导的主机。需要 Claude Code v2.1.257 或更高版本 |

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

258| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | 设置为 `1` 以关闭 [关键路径删除](/docs/zh-CN/permission-modes#critical-paths) 提示上的时间限制。在 `auto` 模式中 Claude Code 随后将这些删除发送到分类器，在 `bypassPermissions` 模式中提示等待您的答案。在启动 Claude Code 的环境中设置它，因为 Claude Code 忽略通过设置 `env` 块传递的副本。需要 Claude Code v2.1.281 或更高版本 |

258| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 设置为 `1` 以从 API 请求中删除 Anthropic 特定的 `anthropic-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`）被保留。[MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search) 被禁用，所有 MCP 工具预先加载，即使您设置 `ENABLE_TOOL_SEARCH`。在 Claude Code v2.1.227 或更高版本上，[托管设置](/docs/zh-CN/managed-settings) 可以保持工具搜索打开。[禁用预发布功能](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities) 涵盖覆盖应用的位置 |259| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 设置为 `1` 以从 API 请求中删除 Anthropic 特定的 `anthropic-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`）被保留。[MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search) 被禁用，所有 MCP 工具预先加载，即使您设置 `ENABLE_TOOL_SEARCH`。在 Claude Code v2.1.227 或更高版本上，[托管设置](/docs/zh-CN/managed-settings) 可以保持工具搜索打开。[禁用预发布功能](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities) 涵盖覆盖应用的位置 |

259| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 设置为 `1` 以禁用内置 [Explore 和 Plan 子代理](/docs/zh-CN/sub-agents#built-in-subagents)。Claude 使用其搜索工具或通用子代理进行探索，[plan mode](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode) 直接读取文件而不是启动 Explore 和 Plan 代理。名为 `Explore` 或 `Plan` 的自定义子代理不受影响。要在 Agent SDK 或非交互模式中删除每个内置子代理类型，请改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更高版本 |260| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 设置为 `1` 以禁用内置 [Explore 和 Plan 子代理](/docs/zh-CN/sub-agents#built-in-subagents)。Claude 使用其搜索工具或通用子代理进行探索，[plan mode](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode) 直接读取文件而不是启动 Explore 和 Plan 代理。名为 `Explore` 或 `Plan` 的自定义子代理不受影响。要在 Agent SDK 或非交互模式中删除每个内置子代理类型，请改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更高版本 |

271| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 设置为 `1` 以禁用官方插件市场的自动注册。Claude Code 在即将注册市场时读取变量，通常在机器的第一次交互启动期间。如果变量在该点设置，Claude Code 永久跳过注册。稍后取消设置变量不会撤销跳过。随时运行 `claude plugin marketplace add anthropics/claude-plugins-official` 以注册市场 |272| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 设置为 `1` 以禁用官方插件市场的自动注册。Claude Code 在即将注册市场时读取变量，通常在机器的第一次交互启动期间。如果变量在该点设置，Claude Code 永久跳过注册。稍后取消设置变量不会撤销跳过。随时运行 `claude plugin marketplace add anthropics/claude-plugins-official` 以注册市场 |

272| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 设置为 `1` 以停止 Claude Code 在 Claude Code 将它们发送到 Agent SDK 的 `canUseTool` 回调的会话中运行您的 [`Notification` 未回答权限请求的 hooks](/docs/zh-CN/hooks#notification)，这是 Claude Desktop 和 VS Code 扩展如何托管 Claude Code 的方式。在终端会话中无效。需要 Claude Code v2.1.233 或更高版本 |273| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 设置为 `1` 以停止 Claude Code 在 Claude Code 将它们发送到 Agent SDK 的 `canUseTool` 回调的会话中运行您的 [`Notification` 未回答权限请求的 hooks](/docs/zh-CN/hooks#notification)，这是 Claude Desktop 和 VS Code 扩展如何托管 Claude Code 的方式。在终端会话中无效。需要 Claude Code v2.1.233 或更高版本 |

275| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | 设置为 `1` 以关闭 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool) 检查，该检查在 [系统路径](/docs/zh-CN/permission-modes#remove-item-in-powershell)（如驱动器根目录或您的主目录）上拒绝 `cmd` 内置命令 `rd`、`rmdir`、`del` 和 `erase`。Claude Code 在设置文件的 `env` 块中忽略此变量。需要 Claude Code v2.1.283 或更高版本 |

276| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | 设置为 `1` 以关闭 [关键路径](/docs/zh-CN/permission-modes#critical-paths) 检查，用于递归 `rm`，其目标完全是命令替换的输出，例如 `rm -rf "$(pwd)"`。其他关键路径检查保持运行。在启动 Claude Code 的环境中设置它，因为 Claude Code 忽略通过设置 `env` 块传递的副本。需要 Claude Code v2.1.281 或更高版本 |

274| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 设置为 `1` 以禁用基于对话上下文的自动终端标题更新。这也跳过生成 [会话标题](/docs/zh-CN/sessions#name-your-sessions) 的后台小/快速模型请求 |277| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 设置为 `1` 以禁用基于对话上下文的自动终端标题更新。这也跳过生成 [会话标题](/docs/zh-CN/sessions#name-your-sessions) 的后台小/快速模型请求 |

275| `CLAUDE_CODE_DISABLE_THINKING` | 设置为 `1` 以从 API 请求中完全省略 `thinking` 参数。这是代理和网关拒绝该参数的兼容性选项。在默认思考的模型上，省略参数意味着模型仍可能思考。要在 Anthropic API 上明确禁用 [扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，请改用 `MAX_THINKING_TOKENS=0`。两个变量都不会在 Opus 5.5 或 Fable 模型上关闭思考，这些模型无法关闭思考。在 [第三方提供商](/docs/zh-CN/third-party-integrations) 上，`MAX_THINKING_TOKENS=0` 同样省略参数，因此两个变量在那里的行为相同 |278| `CLAUDE_CODE_DISABLE_THINKING` | 设置为 `1` 以从 API 请求中完全省略 `thinking` 参数。这是代理和网关拒绝该参数的兼容性选项。在默认思考的模型上，省略参数意味着模型仍可能思考。要在 Anthropic API 上明确禁用 [扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，请改用 `MAX_THINKING_TOKENS=0`。两个变量都不会在 Opus 5.5、Sonnet 5.5 或 Fable 模型上关闭思考，这些模型无法关闭思考。在 [第三方提供商](/docs/zh-CN/third-party-integrations) 上，`MAX_THINKING_TOKENS=0` 同样省略参数，因此两个变量在那里的行为相同 |

276| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 设置为 `1` 以在 Claude Code 不识别模型 ID 时跳过主动 [自动压缩](/docs/zh-CN/costs#reduce-token-usage)，例如 [LLM 网关](/docs/zh-CN/llm-gateway) 别名。没有此变量，Claude Code 在它为 ID 假设的上下文窗口处压缩。`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 可以改为纠正假设的窗口；请参阅 [为网关或自定义模型 ID 纠正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id) 了解何时应用每个变量。需要 Claude Code v2.1.223 或更高版本 |279| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 设置为 `1` 以在 Claude Code 不识别模型 ID 时跳过主动 [自动压缩](/docs/zh-CN/costs#reduce-token-usage)，例如 [LLM 网关](/docs/zh-CN/llm-gateway) 别名。没有此变量，Claude Code 在它为 ID 假设的上下文窗口处压缩。`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 可以改为纠正假设的窗口；请参阅 [为网关或自定义模型 ID 纠正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id) 了解何时应用每个变量。需要 Claude Code v2.1.223 或更高版本 |

277| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 设置为 `1` 以在 [全屏呈现](/docs/zh-CN/fullscreen) 中禁用虚拟滚动并呈现转录中的每条消息。如果全屏模式中的滚动显示应显示消息的空白区域，请使用此选项 |280| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 设置为 `1` 以在 [全屏呈现](/docs/zh-CN/fullscreen) 中禁用虚拟滚动并呈现转录中的每条消息。如果全屏模式中的滚动显示应显示消息的空白区域，请使用此选项 |

278| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | 设置为 `1` 以在 Windows 上直接启动 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool) 命令，而不是通过 `cmd.exe` 启动器。默认情况下，启动器让在后台 [运行的 PowerShell 命令](/docs/zh-CN/tools-reference#background-commands) [转移到会话的下一个进程](/docs/zh-CN/agent-view#the-supervisor-process)，例如当您 [后台处理会话](/docs/zh-CN/agent-view#from-inside-a-session) 时。如果您设置变量，后台处理的 PowerShell 命令在会话的进程退出时停止。Bash 命令不受影响。需要 Claude Code v2.1.269 或更高版本 |281| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | 设置为 `1` 以在 Windows 上直接启动 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool) 命令，而不是通过 `cmd.exe` 启动器。默认情况下，启动器让在后台 [运行的 PowerShell 命令](/docs/zh-CN/tools-reference#background-commands) [转移到会话的下一个进程](/docs/zh-CN/agent-view#the-supervisor-process)，例如当您 [后台处理会话](/docs/zh-CN/agent-view#from-inside-a-session) 时。如果您设置变量，后台处理的 PowerShell 命令在会话的进程退出时停止。Bash 命令不受影响。需要 Claude Code v2.1.269 或更高版本 |

412| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流](/docs/zh-CN/workflows) 代理等待相同前缀兄弟的第一个响应开始的上限（以毫秒为单位），然后发送自己的第一个请求。当扇出启动共享 [提示缓存前缀](/docs/zh-CN/workflows#prompt-caching-in-a-fan-out) 的多个代理时，Claude Code 将除第一个代理外的所有代理保持最多这么长时间，以便其余代理读取缓存的前缀而不是每个未缓存处理它。默认 `5000`。设置为 `0` 以禁用等待。当设置 `DISABLE_PROMPT_CACHING` 时，代理从不等待。需要 Claude Code v2.1.229 或更高版本 |415| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流](/docs/zh-CN/workflows) 代理等待相同前缀兄弟的第一个响应开始的上限（以毫秒为单位），然后发送自己的第一个请求。当扇出启动共享 [提示缓存前缀](/docs/zh-CN/workflows#prompt-caching-in-a-fan-out) 的多个代理时，Claude Code 将除第一个代理外的所有代理保持最多这么长时间，以便其余代理读取缓存的前缀而不是每个未缓存处理它。默认 `5000`。设置为 `0` 以禁用等待。当设置 `DISABLE_PROMPT_CACHING` 时，代理从不等待。需要 Claude Code v2.1.229 或更高版本 |

413| `CLAUDE_CONFIG_DIR` | 覆盖配置目录（默认值：`~/.claude`）。所有设置、会话历史和插件存储在此路径下。对于凭证，请参阅 [Claude Code 存储凭证的位置](/docs/zh-CN/authentication#credential-management)。对于并排运行多个帐户很有用：例如，`alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。在您的 shell、用户设置或托管设置中设置它。在 [项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env) 中被忽略 |416| `CLAUDE_CONFIG_DIR` | 覆盖配置目录（默认值：`~/.claude`）。所有设置、会话历史和插件存储在此路径下。对于凭证，请参阅 [Claude Code 存储凭证的位置](/docs/zh-CN/authentication#credential-management)。对于并排运行多个帐户很有用：例如，`alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。在您的 shell、用户设置或托管设置中设置它。在 [项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env) 中被忽略 |

414| `CLAUDE_DISABLE_ADOPT` | 设置为 `1` 以在通过按 `←` 或使用 [`/background`](/docs/zh-CN/agent-view#from-inside-a-session) 后台处理会话时停止进行中的后台工作，而不是进行中的工作。Claude Code 要求您在后台处理前确认，然后停止否则会进行的任务。需要 Claude Code v2.1.195 或更高版本 |417| `CLAUDE_DISABLE_ADOPT` | 设置为 `1` 以在通过按 `←` 或使用 [`/background`](/docs/zh-CN/agent-view#from-inside-a-session) 后台处理会话时停止进行中的后台工作，而不是进行中的工作。Claude Code 要求您在后台处理前确认，然后停止否则会进行的任务。需要 Claude Code v2.1.195 或更高版本 |

415| `CLAUDE_EFFORT` | 在 Bash 工具子进程和 hook 命令中自动设置为启动子进程时生效的 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是不同的级别，报告为 `xhigh`。与传递给 [hooks](/docs/zh-CN/hooks) 的 `effort.level` 字段匹配。仅在当前模型支持 effort 参数时设置 |418| `CLAUDE_EFFORT` | 在 Bash 工具子进程和 hook 命令中自动设置为启动子进程时生效的 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。与传递给 [hooks](/docs/zh-CN/hooks) 的 `effort.level` 字段匹配。仅在当前模型支持 effort 参数时设置 |

416| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 设置为 `1` 以强制启用字节级流式空闲监视程序，或设置为 `0` 以强制禁用它。`0` 也关闭运行该截止时间的连接上的 [第一字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs)。未设置时，监视程序在直接 Anthropic API 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 连接上默认启用，以及通过 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 到达的 [网关](/docs/zh-CN/gateways) 连接上的流式响应；在 v2.1.222 之前，它在这些网关连接上不运行，因此事件级监视程序可能在那里报告停滞，即使保活 ping 正在到达。对于超时以及计时器如何交互，请参阅 [流式空闲监视程序](/docs/zh-CN/network-config#streaming-idle-watchdogs) |419| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 设置为 `1` 以强制启用字节级流式空闲监视程序，或设置为 `0` 以强制禁用它。`0` 也关闭运行该截止时间的连接上的 [第一字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs)。未设置时，监视程序在直接 Anthropic API 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 连接上默认启用，以及通过 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 到达的 [网关](/docs/zh-CN/gateways) 连接上的流式响应；在 v2.1.222 之前，它在这些网关连接上不运行，因此事件级监视程序可能在那里报告停滞，即使保活 ping 正在到达。对于超时以及计时器如何交互，请参阅 [流式空闲监视程序](/docs/zh-CN/network-config#streaming-idle-watchdogs) |

417| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 设置为 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 响应上启用字节级流式空闲监视程序，这也启用 [第一字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs) 在 Bedrock 流式请求上。默认关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时 |420| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 设置为 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 响应上启用字节级流式空闲监视程序，这也启用 [第一字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs) 在 Bedrock 流式请求上。默认关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时 |

418| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 设置为 `0` 以强制禁用事件级流式空闲监视程序，或设置为 `1` 以强制启用它。未设置时，监视程序在所有提供商上默认打开。在 v2.1.196 之前，未设置默认值在直接 Anthropic API 上由服务器控制，在其他提供商上关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时；对于与此一起运行的其他停滞计时器，请参阅 [流式空闲监视程序](/docs/zh-CN/network-config#streaming-idle-watchdogs) |421| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 设置为 `0` 以强制禁用事件级流式空闲监视程序，或设置为 `1` 以强制启用它。未设置时，监视程序在所有提供商上默认打开。在 v2.1.196 之前，未设置默认值在直接 Anthropic API 上由服务器控制，在其他提供商上关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时；对于与此一起运行的其他停滞计时器，请参阅 [流式空闲监视程序](/docs/zh-CN/network-config#streaming-idle-watchdogs) |

446| `DISABLE_TELEMETRY` | 设置为任何非空值（如 `1`）以选择退出遥测。**将其设置为 `0` 或 `false` 仍会选择退出**，与大多数打开/关闭变量不同；取消设置变量以重新打开遥测。遥测事件不包括用户数据，如代码、文件路径或 bash 命令。也禁用功能标志获取，效果与 `DISABLE_GROWTHBOOK` 相同，这使 [Remote Control](/docs/zh-CN/remote-control#requirements) 和其他 [需要功能标志获取的功能](#features-that-need-feature-flag-fetching) 不可用。请参阅 [为您的组织关闭遥测](/docs/zh-CN/managed-settings#turn-telemetry-off-for-your-organization) |449| `DISABLE_TELEMETRY` | 设置为任何非空值（如 `1`）以选择退出遥测。**将其设置为 `0` 或 `false` 仍会选择退出**，与大多数打开/关闭变量不同；取消设置变量以重新打开遥测。遥测事件不包括用户数据，如代码、文件路径或 bash 命令。也禁用功能标志获取，这使 [Remote Control](/docs/zh-CN/remote-control#requirements) 和其他 [需要功能标志获取的功能](#features-that-need-feature-flag-fetching) 不可用。请参阅 [为您的组织关闭遥测](/docs/zh-CN/managed-settings#turn-telemetry-off-for-your-organization) |

447| `DISABLE_UPDATES` | 设置为 `1` 以阻止所有更新，包括手动 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更严格。在通过您自己的渠道分发 Claude Code 且用户不应自我更新时使用 |450| `DISABLE_UPDATES` | 设置为 `1` 以阻止所有更新，包括手动 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更严格。在通过您自己的渠道分发 Claude Code 且用户不应自我更新时使用 |

449| `DO_NOT_TRACK` | 设置为 `1` 以选择退出遥测，效果与 `DISABLE_TELEMETRY` 相同，包括使 [Remote Control](/docs/zh-CN/remote-control#requirements) 和其他 [需要功能标志获取的功能](#features-that-need-feature-flag-fetching) 不可用。Claude Code 将此变量读作标准布尔值，因此 `0` 保持遥测打开，并将其视为许多开发者 CLI 识别的跨工具约定 |452| `DO_NOT_TRACK` | 设置为 `1` 以选择退出遥测，效果与 `DISABLE_TELEMETRY` 相同，包括使 [Remote Control](/docs/zh-CN/remote-control#requirements) 和其他 [需要功能标志获取的功能](#features-that-need-feature-flag-fetching) 不可用。Claude Code 将此变量读作标准布尔值，因此 `0` 保持遥测打开，并将其视为许多开发者 CLI 识别的跨工具约定 |

461| `IS_DEMO` | 设置为任何非空值（如 `1`）以启用演示模式：从标头和 `/status` 输出隐藏您的电子邮件和组织名称，并跳过入职。**将其设置为 `0` 或 `false` 仍会启用演示模式**，与大多数打开/关闭变量不同；取消设置变量以关闭它。在流式传输或录制会话时很有用 |464| `IS_DEMO` | 设置为任何非空值（如 `1`）以启用演示模式：从标头和 `/status` 输出隐藏您的电子邮件和组织名称，并跳过入职。**将其设置为 `0` 或 `false` 仍会启用演示模式**，与大多数打开/关闭变量不同；取消设置变量以关闭它。在流式传输或录制会话时很有用 |

462| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具响应中允许的最大令牌数。Claude Code 在输出超过 10,000 令牌时显示警告。声明 [`anthropic/maxResultSizeChars`](/docs/zh-CN/mcp#raise-the-limit-for-a-specific-tool) 的工具对文本内容使用该字符限制，但来自这些工具的图像内容仍受此变量约束（默认值：25000） |465| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具响应中允许的最大令牌数。Claude Code 在输出超过 10,000 令牌时显示警告。声明 [`anthropic/maxResultSizeChars`](/docs/zh-CN/mcp#raise-the-limit-for-a-specific-tool) 的工具对文本内容使用该字符限制，但来自这些工具的图像内容仍受此变量约束（默认值：25000） |

463| `MAX_STRUCTURED_OUTPUT_RETRIES` | 当模型的响应在非交互模式下使用 `-p` 标志的 [`--json-schema`](/docs/zh-CN/cli-reference#cli-flags) 验证失败时，Claude Code 允许的尝试次数；在那么多失败的尝试后没有有效输出，运行失败。当 [工作流](/docs/zh-CN/workflows) 子代理的结构化输出验证失败时，相同的上限适用。默认为 5，第一次尝试加四次重试 |466| `MAX_STRUCTURED_OUTPUT_RETRIES` | 当模型的响应在非交互模式下使用 `-p` 标志的 [`--json-schema`](/docs/zh-CN/cli-reference#cli-flags) 验证失败时，Claude Code 允许的尝试次数；在那么多失败的尝试后没有有效输出，运行失败。当 [工作流](/docs/zh-CN/workflows) 子代理的结构化输出验证失败时，相同的上限适用。默认为 5，第一次尝试加四次重试 |

464| `MAX_THINKING_TOKENS` | [扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 的固定令牌预算。Claude Code 将其上限设置为请求的最大输出令牌下方一个令牌，从不低于 1,024。请参阅 `CLAUDE_CODE_MAX_OUTPUT_TOKENS` 了解如何设置该限制。未设置且启用思考时，具有 [自适应推理](/docs/zh-CN/model-config#adjust-effort-level) 的模型选择自己的思考深度，其他模型使用上限。设置为 `0` 以在 Anthropic API 上禁用思考，但 Opus 5.5 和 Fable 模型除外，这些模型无法关闭思考。在 [第三方提供商](/docs/zh-CN/third-party-integrations) 上，`0` 改为省略 `thinking` 参数。在 Anthropic API 上关闭思考时，Claude Code 向它知道 [不接受该组合](/docs/zh-CN/errors#effort-isnt-available-with-thinking-turned-off) 的模型（如 Opus 5）发送 effort `high` 而不是更高级别。Claude Code 忽略自适应推理模型上的非零值，除了 Claude Code 关闭自适应推理的模型（使用 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`） |467| `MAX_THINKING_TOKENS` | [扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 的固定令牌预算。Claude Code 将其上限设置为请求的最大输出令牌下方一个令牌，从不低于 1,024。请参阅 `CLAUDE_CODE_MAX_OUTPUT_TOKENS` 了解如何设置该限制。未设置且启用思考时，具有 [自适应推理](/docs/zh-CN/model-config#adjust-effort-level) 的模型选择自己的思考深度，其他模型使用上限。设置为 `0` 以在 Anthropic API 上禁用思考，但 Opus 5.5、Sonnet 5.5 和 Fable 模型除外，这些模型无法关闭思考。在 [第三方提供商](/docs/zh-CN/third-party-integrations) 上，`0` 改为省略 `thinking` 参数。在 Anthropic API 上关闭思考时，Claude Code 向它知道 [不接受该组合](/docs/zh-CN/errors#effort-isnt-available-with-thinking-turned-off) 的模型（如 Opus 5）发送 effort `high` 而不是更高级别。Claude Code 忽略自适应推理模型上的非零值，除了 Claude Code 关闭自适应推理的模型（使用 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING`） |

465| `MCP_CLIENT_SECRET` | 需要 [预配置凭证](/docs/zh-CN/mcp#use-pre-configured-oauth-credentials) 的 MCP 服务器的 OAuth 客户端密钥。在使用 `--client-secret` 添加服务器时避免交互式提示 |468| `MCP_CLIENT_SECRET` | 需要 [预配置凭证](/docs/zh-CN/mcp#use-pre-configured-oauth-credentials) 的 MCP 服务器的 OAuth 客户端密钥。在使用 `--client-secret` 添加服务器时避免交互式提示 |

466| `MCP_CONNECTION_NONBLOCKING` | 控制启动是否在第一个查询之前等待 MCP 服务器连接。MCP 启动默认非阻塞：服务器在后台连接，它们的工具在完成时变为可用。设置为 `0` 以使 Claude Code 在第一个查询之前等待服务器连接。配置为 [`alwaysLoad: true`](/docs/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器仍然使启动等待，除非从 [发现缓存](/docs/zh-CN/mcp#server-status-detail) 提供，因为它们的工具必须在构建第一个提示时存在。在非交互模式（`-p`）中没有 `--input-format stream-json`，Claude Code 也在第一个转弯之前等待仍然待处理的服务器，无论此变量如何。当您明确传递 [`--mcp-config`](/docs/zh-CN/cli-reference#cli-flags) 时，等待有更长的截止时间；请参阅该标志的条目了解缓存服务器异常 |469| `MCP_CONNECTION_NONBLOCKING` | 控制启动是否在第一个查询之前等待 MCP 服务器连接。MCP 启动默认非阻塞：服务器在后台连接，它们的工具在完成时变为可用。设置为 `0` 以使 Claude Code 在第一个查询之前等待服务器连接。配置为 [`alwaysLoad: true`](/docs/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器仍然使启动等待，除非从 [发现缓存](/docs/zh-CN/mcp#server-status-detail) 提供，因为它们的工具必须在构建第一个提示时存在。在非交互模式（`-p`）中没有 `--input-format stream-json`，Claude Code 也在第一个转弯之前等待仍然待处理的服务器，无论此变量如何。当您明确传递 [`--mcp-config`](/docs/zh-CN/cli-reference#cli-flags) 时，等待有更长的截止时间；请参阅该标志的条目了解缓存服务器异常 |

467| `MCP_CONNECT_TIMEOUT_MS` | 阻塞 MCP 启动在快照工具列表之前等待连接批次的时间（以毫秒为单位）（默认值：5000）。当 `MCP_CONNECTION_NONBLOCKING=0` 或对于标记为 [`alwaysLoad: true`](/docs/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器时应用。仍然待处理的服务器在截止时间处继续在后台连接。与 `MCP_TIMEOUT` 不同，后者界限单个服务器的连接尝试 |470| `MCP_CONNECT_TIMEOUT_MS` | 阻塞 MCP 启动在快照工具列表之前等待连接批次的时间（以毫秒为单位）（默认值：5000）。当 `MCP_CONNECTION_NONBLOCKING=0` 或对于标记为 [`alwaysLoad: true`](/docs/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器时应用。仍然待处理的服务器在截止时间处继续在后台连接。与 `MCP_TIMEOUT` 不同，后者界限单个服务器的连接尝试 |

512| `VERTEX_REGION_CLAUDE_5_5_SONNET` | 使用 Google Cloud's Agent Platform 时覆盖 Claude Sonnet 5.5 的区域。在 v2.1.284 中添加 |

528 532

529关闭获取后，你无法：533关闭获取后，你无法：

530 534

531* [在 Pro、Max 和 Team 计划上默认以自动模式启动会话](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)

532* 让 VS Code 扩展[读取设置文件以获取起始权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)

533* 运行 [`/auto-mode-setup`](/docs/zh-CN/auto-mode-config#generate-environment-entries) 来草拟 `autoMode.environment` 条目535* 运行 [`/auto-mode-setup`](/docs/zh-CN/auto-mode-config#generate-environment-entries) 来草拟 `autoMode.environment` 条目

534* 使用 [Remote Control](/docs/zh-CN/remote-control#requirements)536* 使用 [Remote Control](/docs/zh-CN/remote-control)，其中设置了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 或 `DISABLE_GROWTHBOOK`。对于 `DISABLE_TELEMETRY` 和 `DO_NOT_TRACK`，请参阅 [Remote Control 要求](/docs/zh-CN/remote-control#requirements)

535* [消息会话超出此机器](/docs/zh-CN/cross-session-messaging#message-sessions-on-other-machines)；此机器上会话之间的消息传递在关闭获取的情况下也能工作537* [消息会话超出此机器](/docs/zh-CN/cross-session-messaging#message-sessions-on-other-machines)，当 [Remote Control](/docs/zh-CN/remote-control#requirements) 不可用时。此机器上会话之间的消息传递在关闭获取的情况下也能工作

536* 运行 [`claude import` 或 `/import` 命令](/docs/zh-CN/cli-reference#cli-commands)538* 运行 [`claude import` 或 `/import` 命令](/docs/zh-CN/cli-reference#cli-commands)

537* 运行 [`/skill-doctor`](/docs/zh-CN/skills#find-unused-skills) 或在 `/plugin` **Stats** 标签中打开其报告539* 运行 [`/skill-doctor`](/docs/zh-CN/skills#find-unused-skills) 或在 `/plugin` **Stats** 标签中打开其报告

538* 同步为你的 claude.ai 账户启用的[技能](/docs/zh-CN/skills#where-synced-skills-load)和[插件](/docs/zh-CN/plugins/loading#synced-plugins)到你的终端会话中540* 同步为你的 claude.ai 账户启用的[技能](/docs/zh-CN/skills#where-synced-skills-load)和[插件](/docs/zh-CN/plugins/loading#synced-plugins)到你的终端会话中

548 安装或升级后的第一个会话550 安装或升级后的第一个会话

549</h3>551</h3>

550 552

551在你安装 Claude Code 后的第一个会话中，或升级到添加功能的版本后，[特性标志门控功能](#features-that-need-feature-flag-fetching)可能会丢失，会话可能在原本会以自动模式启动的计划上以手动模式启动。Claude Code 在该会话期间获取标志，所以两者都会在你的下一个会话中出现。553在你安装 Claude Code 后的第一个会话中，或升级到添加功能的版本后，[特性标志门控功能](#features-that-need-feature-flag-fetching)可能会丢失。该会话也可能以不同的[权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)启动，而不是你后来的会话所做的那样。Claude Code 在该会话期间获取标志，所以你的下一个会话具有该功能和通常的起始权限模式。

552 554

553在全新安装后，在非交互式会话中（例如 `claude -p`、Agent SDK 或 VS Code 扩展），Claude Code 仍然可以在[选择起始权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)之前获取标志。555在全新安装后，在非交互式会话中（例如 `claude -p`、Agent SDK 或 VS Code 扩展），Claude Code 仍然可以在[选择起始权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)之前获取标志。

554 556

errors.md +551 −158

Details

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

27| `Opus is experiencing high load` / `Fable is experiencing high load` | [服务器错误](#api-error-repeated-529-overloaded-errors) |

27| `Request timed out` | [服务器错误](#request-timed-out)，或如果消息提到您的互联网连接，则为[网络](#unable-to-connect-to-api) |28| `Request timed out` | [服务器错误](#request-timed-out)，或如果消息提到您的互联网连接，则为[网络](#unable-to-connect-to-api) |

28| `API Error: No response from API` | [服务器错误](#no-response-from-api) |29| `API Error: No response from API` | [服务器错误](#no-response-from-api) |

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

30| `Connection lost mid-response` / `Your computer went to sleep mid-response` / `The response stopped arriving` | [服务器错误](#the-response-above-may-be-incomplete) |31| `Connection lost mid-response` / `Your computer went to sleep mid-response` / `The response stopped arriving` | [服务器错误](#the-response-above-may-be-incomplete) |

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

33| `Part of the response never arrived` / `The response stream was malformed` | [服务器错误](#the-response-above-may-be-incomplete) |

34| `API Error: Content block not found` / `API Error: Content block already closed` / `API Error: Stream event unreadable` | [服务器错误](#the-response-above-may-be-incomplete) |

32| `Connection lost before a response was produced` / `Your computer went to sleep before a response was produced` / `The response stalled before a response was produced` | [自动重试](#automatic-retries) |35| `Connection lost before a response was produced` / `Your computer went to sleep before a response was produced` / `The response stalled before a response was produced` | [自动重试](#automatic-retries) |

33| `Connection closed while thinking` / `Response stalled while thinking` | [自动重试](#automatic-retries) |36| `Connection closed while thinking` / `Response stalled while thinking` | [自动重试](#automatic-retries) |

34| `Connection lost while your computer was asleep` | [自动重试](#automatic-retries) |37| `Connection lost while your computer was asleep` | [自动重试](#automatic-retries) |

49| `Could not update your spend limit` | [使用限制](#could-not-update-your-spend-limit) |52| `Could not update your spend limit` | [使用限制](#could-not-update-your-spend-limit) |

50| `spend limit reached` / `spend limit unavailable` | [使用限制](#spend-limit-reached) |53| `spend limit reached` / `spend limit unavailable` | [使用限制](#spend-limit-reached) |

51| `Not logged in · Please run /login` | [身份验证](#not-logged-in) |54| `Not logged in · Please run /login` | [身份验证](#not-logged-in) |

55| `Couldn't save your login` | [身份验证](#couldnt-save-your-login) |

56| `Authentication required · Sign in again to continue` | [身份验证](#not-logged-in) |

52| `Could not resolve authentication method` | [身份验证](#could-not-resolve-authentication-method) |57| `Could not resolve authentication method` | [身份验证](#could-not-resolve-authentication-method) |

53| `Invalid API key` | [身份验证](#invalid-api-key) |58| `Invalid API key` | [身份验证](#invalid-api-key) |

54| `Your apiKeyHelper script is failing` | [身份验证](#your-apikeyhelper-script-is-failing) |59| `Your apiKeyHelper script is failing` | [身份验证](#your-apikeyhelper-script-is-failing) |

69| `signed-in claude.ai account or organization changed on this machine` | [身份验证](#remote-control-stopped-because-the-signed-in-account-changed) |74| `signed-in claude.ai account or organization changed on this machine` | [身份验证](#remote-control-stopped-because-the-signed-in-account-changed) |

70| `Remote Control stopped — the app running this session is now signed in to a different Claude account` | [身份验证](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |75| `Remote Control stopped — the app running this session is now signed in to a different Claude account` | [身份验证](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |

71| `Remote Control stopped — the app running this session is signed out of Claude` | [身份验证](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |76| `Remote Control stopped — the app running this session is signed out of Claude` | [身份验证](#remote-control-stopped-because-the-app-running-the-session-signed-out-or-switched-accounts) |

77| `Couldn't verify your organization's policy for remote control` | [Troubleshoot Remote Control](/docs/zh-CN/remote-control#couldnt-verify-your-organizations-policy-for-remote-control) |

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

73| `API Error: 401 Invalid authentication credentials` | [身份验证](#api-error-401-invalid-authentication-credentials) |79| `API Error: 401 Invalid authentication credentials` | [身份验证](#api-error-401-invalid-authentication-credentials) |

74| `Login expired · Please run /login` | [身份验证](#login-expired) |80| `Login expired · Please run /login` | [身份验证](#login-expired) |

81| `Failed to start OAuth callback server` | [身份验证](#failed-to-start-oauth-callback-server) |

75| `Claude login not accepted · Run /login, then try again` | [身份验证](#claude-login-not-accepted) |82| `Claude login not accepted · Run /login, then try again` | [身份验证](#claude-login-not-accepted) |

76| `Artifacts need a claude.ai login` | [身份验证](#artifacts-need-a-claude-ai-login) |83| `Artifacts need a claude.ai login` | [身份验证](#artifacts-need-a-claude-ai-login) |

77| `Not signed in to the Cloud gateway — run /login.` | [身份验证](#administrator-policy-requires-a-cloud-gateway-sign-in) |84| `Not signed in to the Cloud gateway — run /login.` | [身份验证](#administrator-policy-requires-a-cloud-gateway-sign-in) |

78| `Administrator policy requires a Cloud gateway sign-in on this machine` | [身份验证](#administrator-policy-requires-a-cloud-gateway-sign-in) |85| `Administrator policy requires a Cloud gateway sign-in on this machine` | [身份验证](#administrator-policy-requires-a-cloud-gateway-sign-in) |

79| `Failed to authenticate: OAuth session expired and could not be refreshed` | [身份验证](#login-expired) |86| `Failed to authenticate: OAuth session expired and could not be refreshed` | [身份验证](#login-expired) |

87| `Could not refresh your login because another Claude Code process is refreshing it` | [身份验证](#could-not-refresh-your-login) |

88| `Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh` | [身份验证](#could-not-refresh-your-login) |

80| `Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted` | [身份验证](#your-account-is-on-hold) |89| `Your account is on hold and can't use Claude Code. View details or appeal: https://claude.ai/restricted` | [身份验证](#your-account-is-on-hold) |

81| `Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted` | [身份验证](#your-account-is-on-hold) |90| `Your account is on hold and can't sign in to Claude Code. View details or appeal: https://claude.ai/restricted` | [身份验证](#your-account-is-on-hold) |

82| `Anthropic profile login expired · Re-authenticate your Anthropic profile` | [身份验证](#anthropic-profile-login-expired) |91| `Anthropic profile login expired · Re-authenticate your Anthropic profile` | [身份验证](#anthropic-profile-login-expired) |

121| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [网络](#sessions-ended-while-this-machine-was-offline) |130| `N sessions ended while this machine was offline — the environment was cleaned up on the server and can't be resumed.` | [网络](#sessions-ended-while-this-machine-was-offline) |

132| `Couldn't send feedback` | [网络](#couldnt-send-feedback) |

125| `Prompt is too long · this conversation is a single exchange` / `A single-exchange conversation cannot be compacted` | [请求错误](#prompt-is-too-long) |135| `Prompt is too long · this conversation is a single exchange` / `A single-exchange conversation cannot be compacted` | [请求错误](#prompt-is-too-long) |

131| `all upstreams failed (N attempted)` on a Claude apps gateway session | [上游错误消息](/docs/zh-CN/claude-apps-gateway-config#upstream-error-messages) |141| `all upstreams failed (N attempted)` on a Claude apps gateway session | [上游错误消息](/docs/zh-CN/claude-apps-gateway-config#upstream-error-messages) |

132| `Claude Code may not be enabled for your organization` after a Claude apps gateway sign-in | [Claude apps gateway 故障排除](/docs/zh-CN/claude-apps-gateway-deploy#troubleshooting) |142| `Claude Code may not be enabled for your organization` after a Claude apps gateway sign-in | [Claude apps gateway 故障排除](/docs/zh-CN/claude-apps-gateway-deploy#troubleshooting) |

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

141| `API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid` / `Property keys should match pattern` | [请求错误](#tool-input-schema-is-invalid) |150| `API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid` / `Property keys should match pattern` | [请求错误](#tool-input-schema-is-invalid) |

151| `tool_use.name: String should have at most 200 characters` | [请求错误](#tool-use-name-over-200-characters) |

155| `API error: ... · model not changed` | [请求错误](#api-error-model-not-changed) |

145| `Claude Opus is not available with the Claude Pro plan` | [请求错误](#claude-opus-is-not-available-with-the-claude-pro-plan) |156| `Claude Opus is not available with the Claude Pro plan` | [请求错误](#claude-opus-is-not-available-with-the-claude-pro-plan) |

146| `Claude Code ... does not support this model; version ... or newer is required` | [请求错误](#claude-code-does-not-support-this-model) |157| `Claude Code ... does not support this model; version ... or newer is required` | [请求错误](#claude-code-does-not-support-this-model) |

147| `Claude Code ... is older than the minimum version required by your organization's policy` | [请求错误](#claude-code-does-not-support-this-model) |158| `Claude Code ... is older than the minimum version required by your organization's policy` | [请求错误](#claude-code-does-not-support-this-model) |

148| `Model ... is restricted by your organization's settings` | [请求错误](#model-is-restricted-by-your-organizations-settings) |159| `Model ... is restricted by your organization's settings` | [请求错误](#model-is-restricted-by-your-organizations-settings) |

160| `Model ... is not available. Your organization restricts model selection.` | [请求错误](#model-is-restricted-by-your-organizations-settings) |

150| `couldn't save it as your default` / `couldn't confirm it was saved as your default` | [请求错误](#couldnt-save-it-as-your-default) |162| `couldn't save it as your default` / `couldn't confirm it was saved as your default` | [请求错误](#couldnt-save-it-as-your-default) |

151| `thinking.type.enabled is not supported for this model` | [请求错误](#thinking-type-enabled-is-not-supported-for-this-model) |163| `thinking.type.enabled is not supported for this model` | [请求错误](#thinking-type-enabled-is-not-supported-for-this-model) |

170| `Invalid data in redacted_thinking block` | [请求错误](#invalid-data-in-redacted-thinking-block) |

160| `Invalid encrypted_content in search_result block` / `Invalid encrypted_index in text block` / `Failed to decrypt web search result content` | [请求错误](#invalid-encrypted-content-in-search-result-block) |173| `Invalid encrypted_content in search_result block` / `Invalid encrypted_index in text block` / `Failed to decrypt web search result content` | [请求错误](#invalid-encrypted-content-in-search-result-block) |

174| `Invalid encrypted_stdout in encrypted_code_execution_result block` | [请求错误](#invalid-encrypted-content-in-search-result-block) |

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

166| `<model> has safety measures that flagged this message for a cybersecurity topic` | [请求错误](#safety-measures-flagged-a-cybersecurity-topic) |180| `<model> has safety measures that flagged this message for a cybersecurity topic` | [请求错误](#safety-measures-flagged-a-cybersecurity-topic) |

167| `Installation was killed before it could finish (exit code 137)` | [安装错误](#installation-was-killed-before-it-could-finish) |181| `Installation was killed before it could finish (exit code 137)` | [安装错误](#installation-was-killed-before-it-could-finish) |

171| `Cloud sessions cannot be created from a --restricted session` | [命令行错误](#cloud-sessions-cannot-be-created-from-a-restricted-session) |185| `Cloud sessions cannot be created from a --restricted session` | [命令行错误](#cloud-sessions-cannot-be-created-from-a-restricted-session) |

172| `Cloud sessions are disabled by your organization's policy` | [命令行错误](#cloud-sessions-are-disabled-by-your-organizations-policy) |186| `Cloud sessions are disabled by your organization's policy` | [命令行错误](#cloud-sessions-are-disabled-by-your-organizations-policy) |

173| `Couldn't verify your organization's policy for cloud sessions` | [命令行错误](#cloud-sessions-are-disabled-by-your-organizations-policy) |187| `Couldn't verify your organization's policy for cloud sessions` | [命令行错误](#cloud-sessions-are-disabled-by-your-organizations-policy) |

190| `Error: --agents takes a JSON object, or a file path only with --print (-p)` | [命令行错误](#invalid-agents-configuration) |

191| `Error: --agents file not found` | [命令行错误](#invalid-agents-configuration) |

177| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [命令行错误](#the-current-directory-no-longer-exists) |193| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [命令行错误](#the-current-directory-no-longer-exists) |

178| `Temp directory <dir> ... Refusing to use it` / `ENOSPC: no space left on device, mkdir '<dir>'` | [命令行错误](#temp-directory-refused-or-cannot-be-created) |194| `Temp directory <dir> ... Refusing to use it` / `ENOSPC: no space left on device, mkdir '<dir>'` | [命令行错误](#temp-directory-refused-or-cannot-be-created) |

226| `Windows reported an error (EBADF) when Claude Code read this session's transcript file` | [命令行错误](#windows-reported-an-error-ebadf) |

218| `Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load` | [命令行错误](#output-styles-are-saved-to-local-settings-which-this-session-doesnt-load) |235| `Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load` | [命令行错误](#output-styles-are-saved-to-local-settings-which-this-session-doesnt-load) |

219| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [Plugin 错误](#plugin-eval-is-currently-in-early-access) |236| `` `plugin eval` is currently in early access `` / `` `plugin eval` is currently unavailable `` | [Plugin 错误](#plugin-eval-is-currently-in-early-access) |

220| `Marketplace "<name>" is registered from an untrusted source` | [Plugin 错误](#marketplace-is-registered-from-an-untrusted-source) |237| `Marketplace "<name>" is registered from an untrusted source` | [Plugin 错误](#marketplace-is-registered-from-an-untrusted-source) |

238| `Claude Code refuses the marketplace name "<name>"` | [Plugin 错误](#claude-code-refuses-the-marketplace-name) |

239| `Marketplace name impersonates an official Anthropic/Claude marketplace` | [Plugin 错误](#claude-code-refuses-the-marketplace-name) |

221| `Marketplace "<name>" is already added from a different source` | [Plugin 错误](#marketplace-is-already-added-from-a-different-source) |240| `Marketplace "<name>" is already added from a different source` | [Plugin 错误](#marketplace-is-already-added-from-a-different-source) |

222| `"<name>" is another spelling of "<reserved>", a reserved marketplace name` | [Plugin 错误](#marketplace-name-is-another-spelling-of-a-reserved-name) |241| `"<name>" is another spelling of "<reserved>", a reserved marketplace name` | [Plugin 错误](#marketplace-name-is-another-spelling-of-a-reserved-name) |

223| `references ${user_config.*} in a shell-form command` | [Plugin 错误](#plugin-command-references-user-config) |242| `references ${user_config.*} in a shell-form command` | [Plugin 错误](#plugin-command-references-user-config) |

233| `Plugin "<name>@synced" is required by your organization and can't be disabled here` | [Plugin 错误](#plugin-is-required-by-your-organization) |252| `Plugin "<name>@synced" is required by your organization and can't be disabled here` | [Plugin 错误](#plugin-is-required-by-your-organization) |

253| `"<plugin>" was not uninstalled: it is still switched on in <file>` | [Plugin 错误](#plugin-was-not-uninstalled) |

254| `"<plugin>" was not uninstalled: <file> is there and could not be read` | [Plugin 错误](#plugin-was-not-uninstalled) |

257| `cannot contain null bytes (\0)` | [工具错误](#path-cannot-contain-null-bytes) |

258| `Path contains null bytes` | [工具错误](#path-cannot-contain-null-bytes) |

236| `subagent_type is required: the general-purpose agent is not available in this session` | [工具错误](#subagent-type-is-required) |259| `subagent_type is required: the general-purpose agent is not available in this session` | [工具错误](#subagent-type-is-required) |

237| `Error: this write left the memory index at MEMORY.md at ..., over its ... read limit` | [工具错误](#memory-index-is-over-its-read-limit) |260| `Error: this write left the memory index at MEMORY.md at ..., over its ... read limit` | [工具错误](#memory-index-is-over-its-read-limit) |

241| `Its agent definition was not restored: the folder its definition file came from is not trusted` | [工具错误](#teammate-agent-definition-not-restored) |264| `Its agent definition was not restored: the folder its definition file came from is not trusted` | [工具错误](#teammate-agent-definition-not-restored) |

267| `Cross-session message was dropped at the recipient session's inbox` | [工具错误](#cross-session-message-dropped-at-the-inbox) |

244| `Refusing to send: reply target is a symlink` / `Refusing to send: cannot vet reply target` | [工具错误](#refusing-to-send-a-cross-session-message) |268| `Refusing to send: reply target is a symlink` / `Refusing to send: cannot vet reply target` | [工具错误](#refusing-to-send-a-cross-session-message) |

245| `Refusing to send: connected endpoint is not the expected process` / `Refusing to send: connected endpoint identity could not be read` | [工具错误](#refusing-to-send-a-cross-session-message) |

246| `Refusing to send: connected endpoint is not owned by this user` / `Refusing to send: connected endpoint owner could not be read` | [工具错误](#refusing-to-send-a-cross-session-message) |

247| `Refusing to send: connected endpoint is a different process with the expected pid` | [工具错误](#refusing-to-send-a-cross-session-message) |

248| `Refusing to read <path>: its symlink resolution changed after permission was checked (<reason>)` / `Refusing to search <path>: its symlink resolution changed after permission was checked` | [工具错误](#refusing-after-a-symlink-changed) |269| `Refusing to read <path>: its symlink resolution changed after permission was checked (<reason>)` / `Refusing to search <path>: its symlink resolution changed after permission was checked` | [工具错误](#refusing-after-a-symlink-changed) |

249| `Refusing to write <path>: its parent-directory symlink resolution changed after permission was checked` / `Refusing to write <path>: it is a symbolic link. Write to the link's target path instead` | [工具错误](#refusing-after-a-symlink-changed) |270| `Refusing to write <path>: its parent-directory symlink resolution changed after permission was checked` / `Refusing to write <path>: it is a symbolic link. Write to the link's target path instead` | [工具错误](#refusing-after-a-symlink-changed) |

250| `Refusing to write through symlink: <path>` / `Refusing to write into symlinked directory: <path>` | [工具错误](#refusing-after-a-symlink-changed) |271| `Refusing to write through symlink: <path>` / `Refusing to write into symlinked directory: <path>` | [工具错误](#refusing-after-a-symlink-changed) |

272| `Refusing to write <path>: where it leads on disk could not be determined` / `Refusing to read <path>: where it leads on disk could not be determined` | [工具错误](#refusing-after-a-symlink-changed) |

251| `Refusing to search <path>: a path one of its Read deny rules is written through changed while the search was being prepared` / `Refusing to search <path>: it could not be opened` | [工具错误](#refusing-after-a-symlink-changed) |273| `Refusing to search <path>: a path one of its Read deny rules is written through changed while the search was being prepared` / `Refusing to search <path>: it could not be opened` | [工具错误](#refusing-after-a-symlink-changed) |

252| `its permission check expired before it ran (too many concurrent file operations)` / `ripgrep was found only by name on PATH` | [工具错误](#refusing-after-a-symlink-changed) |274| `its permission check expired before it ran (too many concurrent file operations)` / `ripgrep was found only by name on PATH` | [工具错误](#refusing-after-a-symlink-changed) |

277| `Your disk quota is full on the filesystem with Claude Code's temp directory <dir> (EDQUOT)` | [工具错误](#disk-quota-or-temp-filesystem-is-full) |

278| `The filesystem with Claude Code's temp directory <dir>, or your disk quota on it, is full (ENOSPC)` | [工具错误](#disk-quota-or-temp-filesystem-is-full) |

279| `Command output was lost: the temp filesystem at <dir> is full` / `is out of inodes` | [工具错误](#disk-quota-or-temp-filesystem-is-full) |

255| `the source file is not valid UTF-8 text` / `the source file is not valid UTF-16 text` | [工具错误](#the-source-file-is-not-valid-utf-8-text) |280| `the source file is not valid UTF-8 text` / `the source file is not valid UTF-16 text` | [工具错误](#the-source-file-is-not-valid-utf-8-text) |

257| `Reading a local file from outside this session's connected folders, or through a link, needs the approval card` | [工具错误](#reading-a-local-file-from-outside-the-connected-folders) |282| `Reading a local file from outside this session's connected folders, or through a link, needs the approval card` | [工具错误](#reading-a-local-file-from-outside-the-connected-folders) |

281| `Couldn't start a background session (working directory no longer exists or is not accessible: ...)` | [后台会话错误](#working-directory-no-longer-exists-when-starting-a-background-session) |306| `Couldn't start a background session (working directory no longer exists or is not accessible: ...)` | [后台会话错误](#working-directory-no-longer-exists-when-starting-a-background-session) |

307| `Workspace not trusted.` when starting or restarting a background session | [后台会话错误](#workspace-not-trusted-when-dispatching-a-background-session) |

282| `Claude Code is being updated by npm on this machine (still not runnable after 2 min, ...)` | [后台会话错误](#eacces-when-starting-a-background-session) |308| `Claude Code is being updated by npm on this machine (still not runnable after 2 min, ...)` | [后台会话错误](#eacces-when-starting-a-background-session) |

284| `The connection to Claude Code ended before this message completed` | [包装器和 IDE 错误](#the-connection-to-claude-code-ended-before-this-message-completed) |310| `The connection to Claude Code ended before this message completed` | [包装器和 IDE 错误](#the-connection-to-claude-code-ended-before-this-message-completed) |

291| `Claude Code's fullscreen renderer didn't finish starting last time on this machine` / `Claude Code's fullscreen renderer has repeatedly failed to start on this machine` | [配置警告](#fullscreen-failed-start-notice) |317| `Claude Code's fullscreen renderer didn't finish starting last time on this machine` / `Claude Code's fullscreen renderer has repeatedly failed to start on this machine` | [配置警告](#fullscreen-failed-start-notice) |

292| `Claude Code exited after an unrecoverable interface error (...)` | [配置警告](#exited-after-an-unrecoverable-interface-error) |318| `Claude Code exited after an unrecoverable interface error (...)` | [配置警告](#exited-after-an-unrecoverable-interface-error) |

320| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [配置警告](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |

294| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [配置警告](#workspace-has-not-been-trusted) |321| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [配置警告](#workspace-has-not-been-trusted) |

325| `Claude Code can't start: your organization's managed settings block the default model` / `Claude Code can't start: your organization allows only the models listed in "availableModels"` | [配置警告](#managed-settings-block-the-default-model) |

298| `MCP server <name> is blocked by enterprise managed policy` | [配置警告](#mcp-server-is-blocked-by-enterprise-managed-policy) |326| `MCP server <name> is blocked by enterprise managed policy` | [配置警告](#mcp-server-is-blocked-by-enterprise-managed-policy) |

299| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [配置警告](#managed-settings-document-could-not-be-parsed) |327| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [配置警告](#managed-settings-document-could-not-be-parsed) |

313 自动重试341 自动重试

314</h2>342</h2>

315 343

316Claude Code 在显示错误之前，会以指数退避方式重试瞬时故障最多 10 次。它并不总是重试在 Claude 响应过程中途出现的故障。当您看到本页面上的错误之一时，Claude Code 已经对该故障进行了适用的重试；下面的列表说明哪些故障获得完整预算、哪些获得较小预算，以及哪些不获得预算。344Claude Code 在显示错误之前，会以指数退避方式重试瞬时故障最多 10 次。它并不总是重试在 Claude 响应过程中途出现的故障。当您看到本页面上的错误之一时，Claude Code 已经对该故障进行了适用的重试。

317 345

318Claude Code 重试这些故障：346Claude Code 重试这些故障：

319 347

390 418

391尾部句子指出了检查服务健康状况的位置，因提供商而异。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置会指出该提供商的服务状态。自定义 `ANTHROPIC_BASE_URL` 会指出网关主机。419尾部句子指出了检查服务健康状况的位置，因提供商而异。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置会指出该提供商的服务状态。自定义 `ANTHROPIC_BASE_URL` 会指出网关主机。

392 420

393这表示 API 内部出现了意外故障。它不是由您的提示、设置或账户引起的。421API 本身的 5xx 表示 API 内部出现了意外故障。它不是由您的提示、设置或账户引起的。

422

423当代理、负载均衡器或网关用 HTML 错误页面回复时，消息显示状态代码和页面的标题，例如 `API Error: 502 Bad Gateway`。对于没有标题的页面，消息显示状态代码及其标准名称。在 v2.1.281 之前，当页面有标题时状态代码被丢弃，当页面没有标题时打印页面的原始标记。

394 424

395**应该做什么：**425**应该做什么：**

396 426

416 446

417* 检查 [status.claude.com](https://status.claude.com) 或消息中指出的提供商状态页面，查看容量通知447* 检查 [status.claude.com](https://status.claude.com) 或消息中指出的提供商状态页面，查看容量通知

418* 几分钟后重试448* 几分钟后重试

419* 运行 `/model` 并切换到不同的模型以继续工作，因为容量是按模型跟踪的。当一个模型处于特别高的负载下时，Claude Code 会提示您这样做，例如 `Opus is experiencing high load, please use /model to switch to Sonnet`。449* 运行 `/model` 并切换到不同的模型以继续工作，因为容量是按模型跟踪的。当一个模型处于特别高的负载下时，Claude Code 会提示您这样做，例如 `Opus is experiencing high load, please use /model to switch to Sonnet`。在 Fable 模型上，消息指出 Fable。

450

451 在 Claude Desktop 应用运行的会话中，例如 Code 标签页或 Cowork，消息读作 `Opus is experiencing high load. Switch to Sonnet.`，您可以使用应用的模型选择器切换模型。

420 452

421<h3 id="request-timed-out">453<h3 id="request-timed-out">

422 Request timed out454 Request timed out

433**应该做什么：**465**应该做什么：**

434 466

435* 重试请求467* 重试请求

436* 对于长时间运行的任务，将工作分解为较小的提示

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

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

439 470

457**应该做什么：**488**应该做什么：**

458 489

459* 再次发送您的消息。您的原始消息仍在对话中，因此对于较长的提示，您可以输入 `try again` 而不是粘贴整个内容。490* 再次发送您的消息。您的原始消息仍在对话中，因此对于较长的提示，您可以输入 `try again` 而不是粘贴整个内容。

460* 如果重复出现，将其视为[网络或代理问题](#unable-to-connect-to-api)。接受连接但从不转发请求的代理会在每次尝试时产生此错误。491* 如果重复出现，将其视为[网络或代理问题](#unable-to-connect-to-api)。

461* 如果您网络上的代理或网关保持响应直到完成，请提高 `API_TIMEOUT_MS` 以便重试等待更长时间。在 Amazon Bedrock 上，也提高 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`。492* 如果您网络上的代理或网关保持响应直到完成，请提高 `API_TIMEOUT_MS` 以便重试等待更长时间。在 Amazon Bedrock 上，也提高 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`。

462* 如果第一次尝试持续超时，然后重试成功，请提高 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` 以便第一次尝试也等待足够长的时间。493* 如果第一次尝试持续超时，然后重试成功，请提高 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` 以便第一次尝试也等待足够长的时间。

463 494

474API Error: Connection lost mid-response. The response above may be incomplete.505API Error: Connection lost mid-response. The response above may be incomplete.

475API Error: Your computer went to sleep mid-response. The response above may be incomplete.506API Error: Your computer went to sleep mid-response. The response above may be incomplete.

476API Error: The response stopped arriving. The response above may be incomplete.507API Error: The response stopped arriving. The response above may be incomplete.

508API Error: Part of the response never arrived. The response above may be incomplete.

509API Error: The response stream was malformed. The response above may be incomplete.

477```510```

478 511

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

480* `Connection lost mid-response`：连接断开。513* `Connection lost mid-response`：连接断开。您也会在代理或网关在响应完成之前干净地结束响应体时看到此变体。

481* `Your computer went to sleep mid-response`：Claude Code 检测到您的计算机在响应流式传输时进入睡眠状态。一旦您的计算机唤醒，Claude Code 会将连接视为断开并停止从中读取。514* `Your computer went to sleep mid-response`：Claude Code 检测到您的计算机在响应流式传输时进入睡眠状态。一旦您的计算机唤醒，Claude Code 会将连接视为断开并停止从中读取。

515* `Part of the response never arrived`：流事件在 API 和 Claude Code 之间被丢弃，因此后来的事件引用了从未到达的内容。在 v2.1.281 之前，此情况以 `API Error: Content block not found` 结束轮次。

516* `The response stream was malformed`：为已完成的内容块到达了事件，或事件到达时已损坏。损坏的事件是指其数据不是有效 JSON、其内容缺失或其内容与事件类型不匹配的事件。在 v2.1.284 之前，当具有无效 JSON 的事件在 Claude 完成其思考、文本块或工具调用后到达时，解析器的原始错误（例如以 `API Error: JSON Parse error` 开头的错误）出现。

482* `The response stopped arriving`：连接保持打开但停止传递数据，因此流式空闲监视程序中止了它。在 v2.1.222 之前，Claude Code 也可能在通过 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 到达的[网关](/docs/zh-CN/gateways)连接上报告此故障，同时服务器的保活 ping 仍在到达，因为它只在那里计算已解析的响应事件；升级会停止这些虚假超时。通过提供商基础 URL（如 `ANTHROPIC_BEDROCK_BASE_URL`）到达的网关不被字节监视程序包装；请参阅[流式空闲监视程序](/docs/zh-CN/network-config#streaming-idle-watchdogs)。517* `The response stopped arriving`：连接保持打开但停止传递数据，因此流式空闲监视程序中止了它。在 v2.1.222 之前，Claude Code 也可能在通过 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 到达的[网关](/docs/zh-CN/gateways)连接上报告此故障，同时服务器的保活 ping 仍在到达，因为它只在那里计算已解析的响应事件；升级会停止这些虚假超时。通过提供商基础 URL（如 `ANTHROPIC_BEDROCK_BASE_URL`）到达的网关不被字节监视程序包装；请参阅[流式空闲监视程序](/docs/zh-CN/network-config#streaming-idle-watchdogs)。

483 518

484在 v2.1.227 之前，`Connection lost mid-response` 读作 `Connection closed mid-response`，`The response stopped arriving` 读作 `Response stalled mid-stream`。519在 v2.1.227 之前，`Connection lost mid-response` 读作 `Connection closed mid-response`，`The response stopped arriving` 读作 `Response stalled mid-stream`。

485 520

521当丢弃、重复或损坏的流事件在 Claude 开始任何文本或工具调用之前到达时，您看不到此通知：

522

523* 如果 Claude 仅完成了其思考，Claude Code 会重新发出请求。当重新发出的流以相同方式中断时，轮次以 `Part of the response never arrived and no response was produced. Try again.` 或 `The response stream was malformed and no response was produced. Try again.` 结束。

524* 如果没有完成任何内容，Claude Code 会改为重新发送请求而不流式传输。如果您使用 [`CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK`](/docs/zh-CN/env-vars) 关闭了该回退，轮次以 `API Error: Content block not found`（对于丢弃的事件）或 `API Error: Content block already closed`（对于重复的事件）结束。对于损坏的事件且回退关闭，轮次以 `API Error: Stream event unreadable` 或解析器的原始错误结束。

525

486在四种情况下，Claude Code 处理故障而不立即显示此通知：526在四种情况下，Claude Code 处理故障而不立即显示此通知：

487 527

488* 在响应的早期，Claude Code 要么重试故障，要么以不同的错误结束轮次。请参阅[自动重试](#automatic-retries)。528* 在响应的早期，Claude Code 要么重试故障，要么以不同的错误结束轮次。请参阅[自动重试](#automatic-retries)。

512<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait a moment and then try this action again.552<model> is temporarily unavailable, so auto mode cannot determine the safety of <tool> right now. Wait a moment and then try this action again.

513```553```

514 554

515当 Claude Code 可以确定故障类别时，它在 `temporarily unavailable` 后的括号中指出该类别，例如 `<model> is temporarily unavailable (rate-limited), so auto mode cannot determine the safety of <tool> right now`。类别为 `(rate-limited)`、`(overloaded)`、`(server error)`、`(timed out)` 和 `(connection failed)`。速率限制、过载和服务器错误是暂时的，重试有效。如果 `(timed out)` 或 `(connection failed)` 重复出现，请检查您的连接；请参阅[无法连接到 API](#unable-to-connect-to-api)。在 v2.1.229 之前，消息从不指出类别，读作 `Wait briefly and then try this action again`。555当 Claude Code 可以确定故障类别时，它在 `temporarily unavailable` 后的括号中指出该类别，例如 `<model> is temporarily unavailable (rate-limited), so auto mode cannot determine the safety of <tool> right now`。类别为 `(rate-limited)`、`(overloaded)`、`(server error)`、`(timed out)` 和 `(connection failed)`。如果 `(timed out)` 或 `(connection failed)` 重复出现，请检查您的连接；请参阅[无法连接到 API](#unable-to-connect-to-api)。在 v2.1.229 之前，消息从不指出类别，读作 `Wait briefly and then try this action again`。

516 556

517当没有类别适用时，消息出现时括号中没有类别；多个故障会产生该形式。在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 上，包括 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)，当您的 AWS 账户无法调用消息中指出的模型时，它也会出现，该故障在每次重试时重复，直到您的账户被授予访问该模型的权限。557当没有类别适用时，消息出现时括号中没有类别；多个故障会产生该形式。在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 上，包括 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)，当您的 AWS 账户无法调用消息中指出的模型时，它也会出现，该故障在每次重试时重复，直到您的账户被授予访问该模型的权限。

518 558

533**应该做什么：**573**应该做什么：**

534 574

535* 重试该操作；这通常在下一次尝试时成功575* 重试该操作；这通常在下一次尝试时成功

536* 运行 `claude --debug` 并重复该操作以在调试日志中查看底层分类器响应576* 运行 `claude --debug` 并重复该操作以在调试日志中查看详情

537 577

538当单独的 API 安全检查因早期对话内容而阻止分类器请求时：578当单独的 API 安全检查因早期对话内容而阻止分类器请求时：

539 579

668API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context708API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context

669```709```

670 710

671这是权限检查，而非配额耗尽。即使您的会话和周额度有剩余容量，它也会触发。有关哪些计划直接包含 1M 上下文以及哪些需要使用额度的信息，请参阅 [Extended context](/docs/zh-CN/model-config#extended-context)。Claude Code 在您使用 `/model` 选择模型时运行此检查，仅在直接连接到 Anthropic API 时；如果您将 `ANTHROPIC_BASE_URL` 指向 [LLM gateway](/docs/zh-CN/llm-gateway)，`/model` 允许 `[1m]` 选择，网关决定请求是否成功。711在 Claude Desktop app 运行的会话中，提示不命名任何命令：它指向 claude.ai 使用设置页面，或在 Team 和 Enterprise 计划上说在 claude.ai/admin-settings/usage 启用使用额度或向您的管理员请求。

712

713这是权限检查，而非配额耗尽。即使您的会话和周额度有剩余容量，它也会触发。有关哪些计划直接包含 1M 上下文以及哪些需要使用额度的信息，请参阅 [Extended context](/docs/zh-CN/model-config#extended-context)。

672 714

673当此错误在对话中期出现，因为上下文增长超过 200K 令牌时，Claude Code 会自动将对话压缩回标准上下文限制以下，并之后将会话保持在该限制，因此无需采取任何操作。在 v2.1.172 之前的版本中，错误会在每个后续请求（包括 `/compact`）上重复；在这些版本上运行 `/clear` 以恢复。以下步骤适用于您明确选择 `[1m]` 模型的情况。715当此错误在对话中期出现，因为上下文增长超过 200K 令牌时，Claude Code 会自动将对话压缩回标准上下文限制以下，并之后将会话保持在该限制，因此无需采取任何操作。在 v2.1.172 之前的版本中，错误会在每个后续请求（包括 `/compact`）上重复；在这些版本上运行 `/clear` 以恢复。以下步骤适用于您明确选择 `[1m]` 模型的情况。

674 716

733 775

734尾部句子命名检查服务健康的位置，并因提供商而异。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置命名该提供商的服务状态，而不是 Anthropic 状态页面。自定义 `ANTHROPIC_BASE_URL` 命名网关主机。776尾部句子命名检查服务健康的位置，并因提供商而异。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 配置命名该提供商的服务状态，而不是 Anthropic 状态页面。自定义 `ANTHROPIC_BASE_URL` 命名网关主机。

735 777

778当代理、负载均衡器或 Claude Code 和 API 之间的网关用其自己的 HTML 429 页面回答时，`·` 后的文本是该页面的标题（如果有的话），例如 `Too Many Requests`。在 v2.1.281 之前，整个页面的标记被打印在 `·` 后。

779

736**要做什么：**780**要做什么：**

737 781

738* 运行 `/status` 并确认活跃凭证是您期望的。环境中的流浪 `ANTHROPIC_API_KEY` 可能会通过低层密钥而不是您的订阅路由请求。782* 运行 `/status` 并确认活跃凭证是您期望的。环境中的流浪 `ANTHROPIC_API_KEY` 可能会通过低层密钥而不是您的订阅路由请求。

839Not logged in · Please run /login883Not logged in · Please run /login

840```884```

841 885

886在 Claude Desktop 应用运行的会话中，例如 Code 标签页或 Cowork，消息读作 `Authentication required · Sign in again to continue`，您从应用中再次登录。

887

842**应该做什么：**888**应该做什么：**

843 889

844* 运行 `/login` 以使用您的 Claude 订阅或 Console 账户进行身份验证890* 运行 `/login` 以使用您的 Claude 订阅或 Console 账户进行身份验证

972* 在当前 shell 中取消设置 `ANTHROPIC_API_KEY` 并从您的 shell 配置文件中删除它，然后重新启动 `claude`1018* 在当前 shell 中取消设置 `ANTHROPIC_API_KEY` 并从您的 shell 配置文件中删除它，然后重新启动 `claude`

973* 如果消息说 `Update or unset`，您没有保存的登录可以回退。取消设置密钥并运行 `/login`，或将密钥替换为来自活跃 Console 组织的密钥。1019* 如果消息说 `Update or unset`，您没有保存的登录可以回退。取消设置密钥并运行 `/login`，或将密钥替换为来自活跃 Console 组织的密钥。

974* 之后运行 `/status` 以确认活跃凭证是您的订阅1020* 之后运行 `/status` 以确认活跃凭证是您的订阅

975* 如果未设置环境变量且错误仍然存在，则禁用的组织是与您的 `/login` 关联的组织。联系支持或使用不同账户登录。1021* 如果未设置环境变量且错误仍然存在，请联系支持或使用不同账户登录。

976 1022

977<h3 id="your-organization-has-disabled-api-key-authentication">1023<h3 id="your-organization-has-disabled-api-key-authentication">

978 您的组织已禁用 API 密钥身份验证1024 您的组织已禁用 API 密钥身份验证

985Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY to use your claude.ai account instead1031Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY to use your claude.ai account instead

986Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY and run /login to sign in with your claude.ai account1032Your organization has disabled API key authentication · Unset ANTHROPIC_API_KEY and run /login to sign in with your claude.ai account

987Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account1033Your organization has disabled API key authentication · Unset the apiKeyHelper setting and run /login to sign in with your claude.ai account

1034Your organization has disabled API key authentication · Sign in again with your claude.ai account

988```1035```

989 1036

1037最后一种形式出现在 Claude Desktop 应用运行的会话中，例如 Code 标签页或 Cowork，您从应用中再次登录。

1038

990环境变量和 `apiKeyHelper` 优先于 `/login`，因此仅运行 `/login` 在任一仍在提供密钥时没有帮助。请参阅 [身份验证优先级](/docs/zh-CN/authentication#authentication-precedence)。1039环境变量和 `apiKeyHelper` 优先于 `/login`，因此仅运行 `/login` 在任一仍在提供密钥时没有帮助。请参阅 [身份验证优先级](/docs/zh-CN/authentication#authentication-precedence)。

991 1040

992**应该做什么：**1041**应该做什么：**

1021 例程被您的组织的策略禁用1070 例程被您的组织的策略禁用

1022</h3>1071</h3>

1023 1072

1024您的 Team 或 Enterprise 组织中的所有者已在组织级别关闭例程。当您尝试创建或运行例程时会出现错误，例如从 claude.ai/code 上的 [例程](/docs/zh-CN/routines) UI。在 Claude Code v2.1.227 或更高版本上，相同的设置也 [隐藏 CLI 中的 `/schedule`](/docs/zh-CN/routines#troubleshooting)。1073您的 Team 或 Enterprise 组织中的所有者已在组织级别关闭例程。当您尝试创建或运行例程时会出现错误，例如从 [Routines](/docs/zh-CN/routines) UI on claude.ai/code。在 Claude Code v2.1.227 或更高版本上，相同的设置也 [隐藏 `/schedule`](/docs/zh-CN/routines#troubleshooting) 在 CLI 中。

1025 1074

1026```text theme={null}1075```text theme={null}

1027Routines are disabled by your organization's policy.1076Routines are disabled by your organization's policy.

1038 Remote Control 需要 Anthropic API1087 Remote Control 需要 Anthropic API

1039</h3>1088</h3>

1040 1089

1041会话不是直接与 Anthropic API 通信，因此没有 claude.ai 后端供 [Remote Control](/docs/zh-CN/remote-control) 配对。1090会话不是直接与 Anthropic API 通信，因此 [Remote Control](/docs/zh-CN/remote-control) 需要。

1042 1091

1043```text theme={null}1092```text theme={null}

1044Remote Control is only available when using Claude via api.anthropic.com. CLAUDE_CODE_USE_BEDROCK is set, so this session is using Amazon Bedrock — unset it (or run in a shell without it) to use Remote Control.1093Remote Control is only available when using Claude via api.anthropic.com. CLAUDE_CODE_USE_BEDROCK is set, so this session is using Amazon Bedrock — unset it (or run in a shell without it) to use Remote Control.

1151**应该做什么：**1200**应该做什么：**

1152 1201

1153* 运行 `/login` 再次登录1202* 运行 `/login` 再次登录

1154* 如果重新身份验证后错误在同一会话中返回，首先运行 `/logout` 以完全清除存储的令牌，然后运行 `/login`

1155* 如果您使用 `CLAUDE_CODE_OAUTH_TOKEN` 环境变量进行身份验证，Claude Code 在请求失败并显示 401 后会继续发送您设置的值，而不是切换到保存的登录的令牌。[`/status`](/docs/zh-CN/commands) 将此凭证显示为读取 `CLAUDE_CODE_OAUTH_TOKEN` 的 `Auth token` 行。使用 [`claude setup-token`](/docs/zh-CN/authentication#generate-a-long-lived-token) 生成新令牌并使用它重新启动，或取消设置变量并运行 `/login`。在 v2.1.225 之前，Claude Code 可以在会话中用保存的登录的短期访问令牌替换变量的值，一旦该令牌过期，会话再次失败并显示 401 错误。1203* 如果您使用 `CLAUDE_CODE_OAUTH_TOKEN` 环境变量进行身份验证，Claude Code 在请求失败并显示 401 后会继续发送您设置的值，而不是切换到保存的登录的令牌。[`/status`](/docs/zh-CN/commands) 将此凭证显示为读取 `CLAUDE_CODE_OAUTH_TOKEN` 的 `Auth token` 行。使用 [`claude setup-token`](/docs/zh-CN/authentication#generate-a-long-lived-token) 生成新令牌并使用它重新启动，或取消设置变量并运行 `/login`。在 v2.1.225 之前，Claude Code 可以在会话中用保存的登录的短期访问令牌替换变量的值，一旦该令牌过期，会话再次失败并显示 401 错误。

1156* 对于跨启动的重复登录提示，请参阅 [故障排除](/docs/zh-CN/troubleshoot-install#not-logged-in-or-token-expired) 中的系统时钟检查和 macOS 凭证存储恢复步骤1204* 对于跨启动的重复登录提示，请参阅 [故障排除](/docs/zh-CN/troubleshoot-install#not-logged-in-or-token-expired) 中的系统时钟检查和 macOS 凭证存储恢复步骤

1157* 对于其他故障，包括 `403 Forbidden` 和 OAuth 浏览器问题，请参阅 [登录和身份验证](/docs/zh-CN/troubleshoot-install#login-and-authentication)1205* 对于其他故障，包括 `403 Forbidden` 和 OAuth 浏览器问题，请参阅 [登录和身份验证](/docs/zh-CN/troubleshoot-install#login-and-authentication)

1177 登录过期1225 登录过期

1178</h3>1226</h3>

1179 1227

1180Claude Code 尝试更新您保存的 claude.ai 或 Claude Console 登录，OAuth 服务拒绝了存储的刷新令牌，因此 Claude Code 清除了保存的凭证。之后，每个模型请求在到达 API 之前都会在本地停止，显示此消息，因为只有 `/login` 可以创建新凭证。1228Claude Code 尝试更新您保存的 claude.ai 登录，OAuth 服务拒绝了存储的刷新令牌，因此 Claude Code 清除了保存的凭证。之后，每个模型请求在到达 API 之前都会在本地停止，显示此消息，因为只有 `/login` 可以创建新凭证。

1181 1229

1182在 v2.1.206 之前，Claude Code 无论如何都会发送模型请求，使用环境中剩余的任何凭证，每个模型都会失败，显示 [所选模型有问题](#theres-an-issue-with-the-selected-model) 或 401，而不是登录提示。1230在 v2.1.206 之前，Claude Code 无论如何都会发送模型请求，使用环境中剩余的任何凭证，每个模型都会失败，显示 [所选模型有问题](#theres-an-issue-with-the-selected-model) 或 401，而不是登录提示。

1183 1231

1203* 在非交互式模式中，在同一环境中运行 `claude`，完成 `/login`，然后重新运行您的命令。对于无法交互式登录的自动化，使用 `ANTHROPIC_API_KEY` 进行身份验证或 [使用 `claude setup-token` 生成长期令牌](/docs/zh-CN/authentication#generate-a-long-lived-token)。1251* 在非交互式模式中，在同一环境中运行 `claude`，完成 `/login`，然后重新运行您的命令。对于无法交互式登录的自动化，使用 `ANTHROPIC_API_KEY` 进行身份验证或 [使用 `claude setup-token` 生成长期令牌](/docs/zh-CN/authentication#generate-a-long-lived-token)。

1204* 如果登录持续失败，请参阅 [登录和身份验证](/docs/zh-CN/troubleshoot-install#login-and-authentication)1252* 如果登录持续失败，请参阅 [登录和身份验证](/docs/zh-CN/troubleshoot-install#login-and-authentication)

1205 1253

1254<h3 id="could-not-refresh-your-login">

1255 无法刷新您的登录，因为另一个 Claude Code 进程正在刷新它

1256</h3>

1257

1258此消息不意味着您的登录被拒绝。您保存的 claude.ai 登录已过期，需要更新。另一个 Claude Code 进程在同一机器上持有共享刷新锁，或退出并留下它，刷新在此会话等待时没有进展。Claude Code 在发送前停止请求：

1259

1260```text theme={null}

1261Could not refresh your login because another Claude Code process is refreshing it (or exited mid-refresh) · Try again in a minute; if it keeps happening, close other Claude Code windows or sign in again with /login

1262```

1263

1264在 [非交互式模式](/docs/zh-CN/headless) (`-p`) 和 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 中，消息如下所示，结构化错误代码为 `server_error`：

1265

1266```text theme={null}

1267Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh. This is usually transient; retry in a minute, and if it persists close other Claude Code processes or sign in again

1268```

1269

1270使用 API 密钥、[`CLAUDE_CODE_OAUTH_TOKEN`](/docs/zh-CN/env-vars) 或第三方提供商进行身份验证的会话不使用保存的登录，永远不会看到此消息。

1271

1272**应该做什么：**

1273

1274* 一分钟后重试。如果另一个进程首先完成刷新，此会话使用更新的登录。

1275* 如果消息持续返回，关闭其他 Claude Code 窗口和进程，然后重试。

1276* 如果在没有其他 Claude Code 进程运行的情况下返回，运行 `/login`。再次登录不会等待刷新锁。

1277

1278<h3 id="couldnt-save-your-login">

1279 无法保存您的登录

1280</h3>

1281

1282您使用 claude.ai 登录，但 Claude Code 无法将登录保存到其凭证存储，因此登录未完成。在 macOS 上，当登录钥匙链锁定时（例如在睡眠或空闲时），在 Claude Code 已在同一会话中读取或保存凭证之后，可能会发生这种情况。

1283

1284```text theme={null}

1285Couldn't save your login. If your Mac's keychain is locked, unlock it and log in again.

1286Couldn't save your login. Try logging in again.

1287```

1288

1289第一种形式出现在 macOS 上，第二种形式出现在其他地方。临时凭证存储故障（例如超时或不可读的存储）会产生相同的消息。

1290

1291**应该做什么：**

1292

1293* 在 macOS 上，解锁登录钥匙链，然后再次运行 `/login`

1294* 在其他平台上，再次运行 `/login`

1295* 如果登录仍然不保存，请参阅 [未登录或令牌过期](/docs/zh-CN/troubleshoot-install#not-logged-in-or-token-expired) 了解钥匙链解锁命令和其他凭证存储恢复步骤

1296

1297<h3 id="failed-to-start-oauth-callback-server">

1298 Failed to start OAuth callback server

1299</h3>

1300

1301当 `/login`、`claude auth login` 或 `claude setup-token` 通过浏览器登录您时，Claude Code 在 `127.0.0.1` 上打开一个监听端口，以便您的浏览器可以将登录结果返回给它。此消息意味着 Claude Code 无法打开该端口，登录在浏览器窗口或登录 URL 出现之前停止：

1302

1303```text theme={null}

1304Failed to start OAuth callback server: Failed to start server. Is port 0 in use?

1305```

1306

1307如果您的消息以 `Is port 0 in use?` 结尾，尝试在 IPv4 环回地址 `127.0.0.1` 上监听的尝试完全失败。因为故障发生在登录 URL 存在之前，`Paste code here if prompted` 流不可用作解决方法。

1308

1309**应该做什么：**

1310

1311* 要立即登录而不需要本地监听器：如果您使用 claude.ai 订阅，在登录有效的机器上运行 [`claude setup-token`](/docs/zh-CN/authentication#generate-a-long-lived-token) 并将其打印的令牌设置为此机器上的 `CLAUDE_CODE_OAUTH_TOKEN`。否则将 `ANTHROPIC_API_KEY` 设置为来自 [Claude Console](https://platform.claude.com/settings/keys) 的密钥。[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) 解释了 Claude Code 在存在多个凭证时如何选择。

1312* 要在此机器上改用浏览器登录，Claude Code 必须能够在 `127.0.0.1` 上监听。如果它在沙箱内运行，检查沙箱的策略是否允许在本地端口上监听，然后再次运行 `/login`。如果它应该能够但仍然失败，运行 `/feedback` 以便报告包含您的环境详细信息。

1313

1206<h3 id="claude-login-not-accepted">1314<h3 id="claude-login-not-accepted">

1207 Claude 登录未被接受1315 Claude login not accepted

1208</h3>1316</h3>

1209 1317

1210您尝试启动 [云会话](/docs/zh-CN/claude-code-on-the-web)，服务器拒绝使用 401 创建它：它不接受此机器发送的 Claude 登录，通常是因为登录过期或被撤销。1318您尝试启动 [云会话](/docs/zh-CN/claude-code-on-the-web)，服务器拒绝使用 401 创建它：它不接受此机器发送的 Claude 登录，通常是因为登录过期或被撤销。

1251 1359

1252当会话没有网关登录时，模型请求失败，显示此消息，例如因为您自策略到达机器后未运行 `/login`。1360当会话没有网关登录时，模型请求失败，显示此消息，例如因为您自策略到达机器后未运行 `/login`。

1253 1361

1254如果您还配置了 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 凭证，且托管设置设置了 `forceLoginMethod`，Claude Code 在启动时改为以以下消息退出：1362如果机器还持有 Anthropic 颁发的凭证且托管设置设置了 `forceLoginMethod` 或 `forceLoginOrgUUID`，Claude Code 在启动时改为以此消息退出：

1255 1363

1256```text theme={null}1364```text theme={null}

1257Administrator policy requires a Cloud gateway sign-in on this machine; the1365Administrator policy requires a Cloud gateway sign-in on this machine; the

1262**应该做什么：**1370**应该做什么：**

1263 1371

1264* 运行 `/login` 并在 **Cloud gateway** 屏幕上完成登录1372* 运行 `/login` 并在 **Cloud gateway** 屏幕上完成登录

1265* 对于启动消息，删除您配置的 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 设置，然后启动 `claude` 并运行 `/login`1373* 对于启动消息，删除您配置的 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 设置。要删除保存的 Console API 密钥，运行 `claude auth logout`，这也会删除保存的 claude.ai 登录。如果您使用 `CLAUDE_CODE_USE_*` 选择云提供商，会话然后以无登录启动。否则启动 `claude` 并运行 `/login`

1266* 如果您认为机器不应该需要网关，请要求管理该机器的管理员从其托管设置中删除 `forceLoginMethod` 和 `forceLoginGatewayUrl`1374* 如果您认为机器不应该需要网关，请要求管理该机器的管理员从其托管设置中删除 `forceLoginMethod` 和 `forceLoginGatewayUrl`

1267 1375

1268在 v2.1.265 上，回归也在某些 LLM 网关和代理配置中显示第一条消息，这些配置使用 API 密钥、`apiKeyHelper` 或自定义标头进行身份验证，即使机器上没有管理员要求。更新到 v2.1.266 或更高版本。您不需要更改您的配置。1376在 v2.1.265 上，回归也在某些 LLM 网关和代理配置中显示第一条消息，这些配置使用 API 密钥、`apiKeyHelper` 或自定义标头进行身份验证，即使机器上没有管理员要求。更新到 v2.1.266 或更高版本。您不需要更改您的配置。

1316 OAuth 范围要求1424 OAuth 范围要求

1317</h3>1425</h3>

1318 1426

1319存储的令牌早于较新功能需要的权限范围。您最常从 `/usage` 和状态行使用指示器看到这种情况：1427存储的令牌早于较新功能需要的权限范围：

1320 1428

1321```text theme={null}1429```text theme={null}

1322OAuth token does not meet scope requirement: user:profile1430OAuth token does not meet scope requirement: user:profile

1330 claude.ai 拒绝了会话令牌1438 claude.ai 拒绝了会话令牌

1331</h3>1439</h3>

1332 1440

1333[claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) 请求失败，因为 claude.ai 拒绝了您的 Claude Code 登录中的令牌，通常是已过期且无法刷新的登录。被拒绝的令牌是您的登录，而不是连接器在 claude.ai 中的自己的授权，因此再次授权连接器不会解决它。在 `/mcp` 中，连接器显示为 `connected · session token rejected`，其详细视图读作：1441[claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) 请求失败，因为 claude.ai 拒绝了您的 Claude Code 登录中的令牌。被拒绝的令牌是您的登录，而不是连接器在 claude.ai 中的自己的授权，因此再次授权连接器不会解决它。在 `/mcp` 中，连接器显示为 `session token rejected`，其详细视图读作：

1334 1442

1335```text theme={null}1443```text theme={null}

1336claude.ai rejected the session token. Run /login, then reconnect.1444claude.ai rejected the session token. Run /login, then reconnect.

1455* 如果提示说凭证由此环境管理，启动 Claude Code 的应用拥有凭证，此处的其他步骤不适用：重试或联系您的管理员1563* 如果提示说凭证由此环境管理，启动 Claude Code 的应用拥有凭证，此处的其他步骤不适用：重试或联系您的管理员

1456* 刷新您的 AWS 凭证以防过期凭证是原因：运行消息中命名的 [`awsAuthRefresh`](/docs/zh-CN/amazon-bedrock#advanced-credential-configuration) 命令（当设置时），或自己刷新您的 SSO 登录、访问密钥、API 密钥或代理令牌1564* 刷新您的 AWS 凭证以防过期凭证是原因：运行消息中命名的 [`awsAuthRefresh`](/docs/zh-CN/amazon-bedrock#advanced-credential-configuration) 命令（当设置时），或自己刷新您的 SSO 登录、访问密钥、API 密钥或代理令牌

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

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

1459 1567

1460<h3 id="google-cloud-credentials-expired-or-invalid">1568<h3 id="google-cloud-credentials-expired-or-invalid">

1461 Google Cloud 凭证已过期或无效1569 Google Cloud 凭证已过期或无效

1657No internet route — check your connection or VPN (EHOSTUNREACH)1765No internet route — check your connection or VPN (EHOSTUNREACH)

1658Couldn't connect through your proxy (ERR_PROXY_TUNNEL) — the proxy refused the tunnel: check its credentials and that it allows this host1766Couldn't connect through your proxy (ERR_PROXY_TUNNEL) — the proxy refused the tunnel: check its credentials and that it allows this host

1659Connection dropped (ECONNRESET)1767Connection dropped (ECONNRESET)

1660fetch failed

1661Request timed out. Check your internet connection and proxy settings1768Request timed out. Check your internet connection and proxy settings

1662```1769```

1663 1770

1677 1784

1678如果 `curl` 成功但 Claude Code 仍然失败，原因通常是运行时和网络之间的某些东西，而不是网络本身：1785如果 `curl` 成功但 Claude Code 仍然失败，原因通常是运行时和网络之间的某些东西，而不是网络本身：

1679 1786

1787* 通过运行 `echo $ANTHROPIC_BASE_URL` 检查 `ANTHROPIC_BASE_URL` 是否已设置，或在 PowerShell 中运行 `echo $env:ANTHROPIC_BASE_URL`，并在您的[设置文件](/docs/zh-CN/settings)的 `env` 块中查找它。当它被设置时，Claude Code 将模型请求发送到该地址而不是 `api.anthropic.com`，因此指向不再运行的本地代理或网关的遗留值会产生 `Connection refused`，即使 `curl` 到达 API。从您的 shell 配置文件或设置中删除它，并从新终端启动 Claude Code。

1680* 在 Linux 和 WSL 上，检查 `/etc/resolv.conf` 是否有无法到达的名称服务器。WSL 特别可以从主机继承损坏的解析器。1788* 在 Linux 和 WSL 上，检查 `/etc/resolv.conf` 是否有无法到达的名称服务器。WSL 特别可以从主机继承损坏的解析器。

1681* 在 macOS 上，已断开连接或卸载的 VPN 客户端可能会留下隧道接口或路由规则。检查 `ifconfig` 是否有陈旧的 `utun` 接口，并在系统设置中删除 VPN 的网络扩展。1789* 在 macOS 上，已断开连接或卸载的 VPN 客户端可能会留下隧道接口或路由规则。检查 `ifconfig` 是否有陈旧的 `utun` 接口，并在系统设置中删除 VPN 的网络扩展。

1682* Docker Desktop 和类似的容器运行时可以拦截出站流量。退出它们并重试以排除这种可能性。1790* Docker Desktop 和类似的容器运行时可以拦截出站流量。退出它们并重试以排除这种可能性。

1702 1810

1703* 如果消息名称代理变量，检查其值是否指向正确的代理，并要求您的网络团队允许通过它进行 HTTPS 连接到消息中的主机。请参阅[网络配置](/docs/zh-CN/network-config)。1811* 如果消息名称代理变量，检查其值是否指向正确的代理，并要求您的网络团队允许通过它进行 HTTPS 连接到消息中的主机。请参阅[网络配置](/docs/zh-CN/network-config)。

1704* 完成[无法连接到 API](#unable-to-connect-to-api) 中的检查。那里的 `curl` 测试和防火墙指导也适用于此检查。1812* 完成[无法连接到 API](#unable-to-connect-to-api) 中的检查。那里的 `curl` 测试和防火墙指导也适用于此检查。

1705* 如果您的组织通过[云网关](/docs/zh-CN/claude-apps-gateway)登录，并且此错误出现在首次运行时，请更新到 Claude Code v2.1.247 或更高版本。

1706* 如果您的网络是开放的，故障仍然存在，Claude Code 可能在您的国家[不可用](https://www.anthropic.com/supported-countries)1813* 如果您的网络是开放的，故障仍然存在，Claude Code 可能在您的国家[不可用](https://www.anthropic.com/supported-countries)

1707 1814

1708<h3 id="socket-is-closed">1815<h3 id="socket-is-closed">

1744* 阅读 `Response:` 子句以查看哪个系统回答。HTML 正文、没有 Anthropic 请求 id 或名称服务器（例如 `nginx` 或 `cloudflare`）意味着 Claude Code 和 API 之间的某些东西代替回答1851* 阅读 `Response:` 子句以查看哪个系统回答。HTML 正文、没有 Anthropic 请求 id 或名称服务器（例如 `nginx` 或 `cloudflare`）意味着 Claude Code 和 API 之间的某些东西代替回答

1745* 如果您通过[LLM 网关](/docs/zh-CN/llm-gateway-connect#troubleshoot-gateway-errors)路由，使用直接请求测试路由，并修复返回非 API 响应的跳跃1852* 如果您通过[LLM 网关](/docs/zh-CN/llm-gateway-connect#troubleshoot-gateway-errors)路由，使用直接请求测试路由，并修复返回非 API 响应的跳跃

1746* 在具有登录页面的网络上（例如访客 Wi-Fi），在浏览器中完成登录，然后重试1853* 在具有登录页面的网络上（例如访客 Wi-Fi），在浏览器中完成登录，然后重试

1747* 如果只有通过您的网关的非流式路由被破坏，设置 [`CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1`](/docs/zh-CN/env-vars#variables) 以便在流中失败的请求转到正常重试路径而不是此回退，除非流式端点本身返回 `404`，Claude Code 仍然会回退1854* 如果只有通过您的网关的非流式路由被破坏，设置 [`CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1`](/docs/zh-CN/env-vars#variables) 以关闭此回退，除非流式端点本身返回 `404`，Claude Code 仍然会回退

1748 1855

1749<h3 id="streaming-response-ended-before-any-complete-data-was-received">1856<h3 id="streaming-response-ended-before-any-complete-data-was-received">

1750 流式响应在接收任何完整数据之前结束1857 流式响应在接收任何完整数据之前结束

1897* 使用 `claude --remote-control` 启动新会话以创建新的 Remote Control 会话2004* 使用 `claude --remote-control` 启动新会话以创建新的 Remote Control 会话

1898* 对于其他 Remote Control 启动消息，请参阅[Remote Control 故障排除](/docs/zh-CN/remote-control#troubleshooting)2005* 对于其他 Remote Control 启动消息，请参阅[Remote Control 故障排除](/docs/zh-CN/remote-control#troubleshooting)

1899 2006

1900如果服务器报告之前的会话已消失，您不会看到此消息。Claude Code 在其位置启动新会话或显示 [`Previous session is unavailable — run /remote-control to start a new one`](/docs/zh-CN/remote-control#previous-session-is-unavailable)，取决于[对话的重新连接记录](/docs/zh-CN/remote-control#resume-outcomes)。从 v2.1.227 到 v2.1.231，Claude Code 显示了以 `Remote Control could not resume the previous session under the current login` 开头的消息，[早期版本的行为也不同](/docs/zh-CN/remote-control#reconnect-history)。2007如果服务器报告之前的会话已消失，您不会看到此消息。Claude Code 在其位置启动新会话或显示 [`Previous session is unavailable — run /remote-control to start a new one`](/docs/zh-CN/remote-control#previous-session-is-unavailable)。

1901 2008

1902<h3 id="sessions-ended-while-this-machine-was-offline">2009<h3 id="sessions-ended-while-this-machine-was-offline">

1903 此机器离线时会话已结束2010 此机器离线时会话已结束

1931* 运行 `/feedback` 发送成绩单并描述发生了什么。如果 `/feedback` 在您的环境中不可用，请参阅[报告错误](#report-an-error)2038* 运行 `/feedback` 发送成绩单并描述发生了什么。如果 `/feedback` 在您的环境中不可用，请参阅[报告错误](#report-an-error)

1932* 如果其他请求也失败，检查您的网络连接并查看[无法连接到 API](#unable-to-connect-to-api)2039* 如果其他请求也失败，检查您的网络连接并查看[无法连接到 API](#unable-to-connect-to-api)

1933 2040

2041<h3 id="couldnt-send-feedback">

2042 无法发送反馈

2043</h3>

2044

2045您从 [`/feedback`、`/bug` 或 `/share` 对话框](/docs/zh-CN/commands#all-commands)发送了报告，上传到 Anthropic 失败。对话框保留您的文本，以便您可以重试。

2046

2047```text theme={null}

2048Couldn't send feedback (couldn't reach the service). If it keeps failing, you can file at https://github.com/anthropics/claude-code/issues instead.

2049```

2050

2051前缀后的文本名称失败的内容：

2052

2053* **`: not signed in. Run /login, then retry.`**：对话框仅在 Claude Code 打开时找到 Anthropic 凭证且到您发送时没有可用的凭证时上传。例如，您在此期间在此机器上注销，或您的登录不再可以刷新。

2054* **括号内容**：`(server returned <status>)` 是服务的响应代码；`(request timed out)` 和 `(couldn't reach the service)` 是网络故障。当 Claude Code 无法命名原因时，括号内容不存在。

2055

2056在[反馈草稿队列](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)中，相同的故障以 `The draft is still queued. Try again later.` 结束，草稿保留在队列中以供另一次尝试。

2057

2058**要做什么：**

2059

2060* 对于未登录的措辞，运行 `/login` 并再次发送

2061* 否则，再次发送；如果其他请求也失败，检查您的网络连接并查看[无法连接到 API](#unable-to-connect-to-api)

2062* 如果它继续失败，在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 提交报告，如消息所说

2063

2064在 v2.1.281 之前，每次发送在 Remote Control **Stop** 或紧急跨会话消息在对话框打开时到达后都失败并显示此消息。在这些版本上，关闭对话框，重新打开它，然后再次发送。

2065

1934<h2 id="request-errors">2066<h2 id="request-errors">

1935 请求错误2067 请求错误

1936</h2>2068</h2>

2008* 运行 `/context` 以查看窗口消耗内容的分解：系统提示、工具、内存文件和消息2140* 运行 `/context` 以查看窗口消耗内容的分解：系统提示、工具、内存文件和消息

2009* 使用 `/mcp disable <name>` 禁用您未使用的 MCP 服务器，以从上下文中删除其工具定义2141* 使用 `/mcp disable <name>` 禁用您未使用的 MCP 服务器，以从上下文中删除其工具定义

2010* 修剪大型 `CLAUDE.md` 内存文件，或将说明移到仅在相关时加载的[路径范围规则](/docs/zh-CN/memory#path-specific-rules)中2142* 修剪大型 `CLAUDE.md` 内存文件，或将说明移到仅在相关时加载的[路径范围规则](/docs/zh-CN/memory#path-specific-rules)中

2011* 子代理从父会话继承每个 MCP 工具定义，这可能在第一轮之前填满其上下文窗口。在生成子代理之前，禁用您未使用的 MCP 服务器。

2012* 自动压缩默认开启，通常可防止此错误。如果您在 `/config` 中或使用 [`DISABLE_AUTO_COMPACT`](/docs/zh-CN/env-vars) 关闭了它，请将其重新打开。如果您保持关闭，请在窗口填满之前自己运行 `/compact`。2143* 自动压缩默认开启，通常可防止此错误。如果您在 `/config` 中或使用 [`DISABLE_AUTO_COMPACT`](/docs/zh-CN/env-vars) 关闭了它，请将其重新打开。如果您保持关闭，请在窗口填满之前自己运行 `/compact`。

2013 2144

2014有关上下文如何填满的交互式视图，请参阅[探索上下文窗口](/docs/zh-CN/context-window)。2145有关上下文如何填满的交互式视图，请参阅[探索上下文窗口](/docs/zh-CN/context-window)。

2017 上下文超过令牌限制2148 上下文超过令牌限制

2018</h3>2149</h3>

2019 2150

2020当对话超过模型的上下文窗口时，`/context` 在其输出顶部显示此警告。请求失败，显示 [`Prompt is too long`](#prompt-is-too-long)，直到您释放空间。交互式会话将该错误显示为 `Context limit reached` 行。2151`/context` 在其输出顶部显示此警告，当对话超过模型的上下文窗口时。请求失败，显示 [`Prompt is too long`](#prompt-is-too-long)，直到您释放空间。交互式会话将该错误显示为 `Context limit reached` 行。

2021 2152

2022```text theme={null}2153```text theme={null}

2023Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.2154Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.

2038 2169

2039在 v2.1.216 之前，`/context` 显示超过 100% 的使用情况，没有警告行解释这意味着什么或如何恢复。2170在 v2.1.216 之前，`/context` 显示超过 100% 的使用情况，没有警告行解释这意味着什么或如何恢复。

2040 2171

2041<h3 id="error-during-compaction-conversation-too-long">

2042 压缩期间出错：对话过长

2043</h3>

~~2044~~

2045`/compact` 本身失败，因为没有足够的可用上下文来保存它生成的摘要。

~~2046~~

2047```text theme={null}

2048Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.

2049```

~~2050~~

2051当窗口在自动压缩触发时已满，或当您在看到 [`Prompt is too long`](#prompt-is-too-long) 后运行 `/compact` 时，可能会发生这种情况。在交互式会话中，该错误是 `Context limit reached` 行。

~~2052~~

2053**要做什么：**

~~2054~~

2055* 按 Esc 两次打开消息列表并回退几轮。这会从上下文中删除最近的消息。然后再次运行 `/compact`。

2056* 如果回退没有释放足够的空间，运行 `/clear` 以启动新的会话。您之前的对话被保留，可以使用 `/resume` 重新打开。

~~2057~~

2058此消息和其他 `/compact` 失败以错误样式显示。在 v2.1.216 之前，它们以与成功命令输出相同的暗淡样式呈现，因此您可能会将失败的压缩读取为成功。

~~2059~~

2060<h3 id="request-too-large">2172<h3 id="request-too-large">

2061 请求过大2173 请求过大

2062</h3>2174</h3>

2140* 对于超大 PDF，要求 Claude 使用 Read 工具读取页面范围，而不是附加整个文件，或使用 `pdftotext` 等工具提取文本并按路径引用输出文件2252* 对于超大 PDF，要求 Claude 使用 Read 工具读取页面范围，而不是附加整个文件，或使用 `pdftotext` 等工具提取文本并按路径引用输出文件

2141* 对于受保护或无效的 PDF，删除密码或从其源应用程序重新导出文件，然后重试2253* 对于受保护或无效的 PDF，删除密码或从其源应用程序重新导出文件，然后重试

2142 2254

2255当 Claude 使用 Read 工具从 PDF 读取页面范围时，读取可能失败，显示不同的消息：

2256

2257```text theme={null}

2258pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to enable PDF page rendering.

2259```

2260

2261页面范围读取使用 `pdftoppm` 呈现页面。使用消息提供的命令安装 poppler-utils，或在其他平台上安装将 `pdftoppm` 放在您的 `PATH` 上的 poppler 构建。请参阅[Read 工具行为](/docs/zh-CN/tools-reference#read-tool-behavior)以了解哪些 PDF 按页面范围读取。

2262

2143<h3 id="extra-inputs-are-not-permitted">2263<h3 id="extra-inputs-are-not-permitted">

2144 不允许额外输入2264 不允许额外输入

2145</h3>2265</h3>

2148 2268

2149```text theme={null}2269```text theme={null}

2150API Error: 400 ... Extra inputs are not permitted ... context_management2270API Error: 400 ... Extra inputs are not permitted ... context_management

2151API Error: 400 ... Unexpected value(s) for the `anthropic-beta` header

2152```2271```

2153 2272

2154Claude Code 发送 `context_management` 和 `effort` 等仅限测试版的字段，以及启用它们的 `anthropic-beta` 头。当网关转发正文但删除头时，API 会看到它不识别的字段。2273Claude Code 发送 `context_management` 和 `effort` 等仅限测试版的字段，以及启用它们的 `anthropic-beta` 头。当网关转发正文但删除头时，API 会看到它不识别的字段。

2185* 删除或[禁用](/docs/zh-CN/mcp#disable-a-server-without-removing-it)声明无效架构的 MCP 服务器。该错误仅按位置命名工具。在 v2.1.216 或更高版本上，检查每个服务器的日志，查找命名其输入架构会被拒绝的工具的行。如果没有日志命名一个，一次禁用一个服务器。2304* 删除或[禁用](/docs/zh-CN/mcp#disable-a-server-without-removing-it)声明无效架构的 MCP 服务器。该错误仅按位置命名工具。在 v2.1.216 或更高版本上，检查每个服务器的日志，查找命名其输入架构会被拒绝的工具的行。如果没有日志命名一个，一次禁用一个服务器。

2186* 如果您维护服务器，请修复工具的 `input_schema`。架构必须是有效的 JSON Schema，顶级属性名称必须为 1 到 64 个字符长，并仅使用 ASCII 字母和数字、`_`、`.` 和 `-`。请参阅[具有无效输入架构的工具](/docs/zh-CN/mcp#tools-with-invalid-input-schemas)。2305* 如果您维护服务器，请修复工具的 `input_schema`。架构必须是有效的 JSON Schema，顶级属性名称必须为 1 到 64 个字符长，并仅使用 ASCII 字母和数字、`_`、`.` 和 `-`。请参阅[具有无效输入架构的工具](/docs/zh-CN/mcp#tools-with-invalid-input-schemas)。

2187 2306

2307<h3 id="tool-use-name-over-200-characters">

2308 tool\_use.name 超过 200 个字符

2309</h3>

2310

2311对话历史中的工具调用携带的名称长度超过 API 在请求中接受的 200 个字符：

2312

2313```text theme={null}

2314API Error: 400 ... tool_use.name: String should have at most 200 characters

2315```

2316

2317Claude Code 在响应到达时以及加载保存的对话时将这样的名称切割为 200 个字符，因此调用失败，显示普通的 `No such tool available` 工具错误，对话继续而不显示此 API 错误。

2318

2319**要做什么：**

2320

2321* 运行 `claude update`，然后恢复对话。更新的版本在加载记录时修复过长的名称，因此卡住的对话再次工作。

2322

2323在 v2.1.281 之前，过长的名称保留在历史中，API 拒绝了重新发送对话的每个请求，包括 `/compact` 和 `--resume`，因此此错误重复，对话被卡住。

2324

2188<h3 id="theres-an-issue-with-the-selected-model">2325<h3 id="theres-an-issue-with-the-selected-model">

2189 所选模型存在问题2326 所选模型存在问题

2190</h3>2327</h3>

2202* **Agent SDK**：错误文本省略提示，因为模型是以编程方式设置的。在 TypeScript 中的 [`Options` 上设置 `model`](/docs/zh-CN/agent-sdk/typescript#options)，或在 Python 中设置 [`ClaudeAgentOptions(model=...)`](/docs/zh-CN/agent-sdk/python#claudeagentoptions)，并处理结构化的 `model_not_found` 错误以显示您自己的重试或模型选择器。2339* **Agent SDK**：错误文本省略提示，因为模型是以编程方式设置的。在 TypeScript 中的 [`Options` 上设置 `model`](/docs/zh-CN/agent-sdk/typescript#options)，或在 Python 中设置 [`ClaudeAgentOptions(model=...)`](/docs/zh-CN/agent-sdk/python#claudeagentoptions)，并处理结构化的 `model_not_found` 错误以显示您自己的重试或模型选择器。

2203* 使用别名（如 `sonnet` 或 `opus`）而不是完整的版本化 ID。别名解析为维护的默认值，因此它们不会过时。请参阅[模型配置](/docs/zh-CN/model-config)。2340* 使用别名（如 `sonnet` 或 `opus`）而不是完整的版本化 ID。别名解析为维护的默认值，因此它们不会过时。请参阅[模型配置](/docs/zh-CN/model-config)。

2204* 如果错误的模型在 CLI 中不断返回，则某处设置了过时的 ID。按[优先级顺序](/docs/zh-CN/model-config#setting-your-model)检查您可以设置模型的位置，并删除过时的值。2341* 如果错误的模型在 CLI 中不断返回，则某处设置了过时的 ID。按[优先级顺序](/docs/zh-CN/model-config#setting-your-model)检查您可以设置模型的位置，并删除过时的值。

2205* 新推出的模型可能在 Anthropic API 上可用，但在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上可用之前。如果您在这些提供商之一上固定了新模型 ID 并看到此错误，请检查您提供商的模型目录以了解您所在地区的可用性，并保持固定前一个版本，直到新版本出现。

2206* Claude Code 将过期的 claude.ai 登录报告为[登录过期](#login-expired)，而不是此错误。在 v2.1.206 之前，无法再刷新的过期登录对每个模型都失败，显示此错误；如果您在较旧版本上看到这种情况，请运行 `/login`。2342* Claude Code 将过期的 claude.ai 登录报告为[登录过期](#login-expired)，而不是此错误。在 v2.1.206 之前，无法再刷新的过期登录对每个模型都失败，显示此错误；如果您在较旧版本上看到这种情况，请运行 `/login`。

2207* 对于 Google Cloud 的 Agent Platform 部署，请参阅 [Google Cloud 的 Agent Platform 故障排除](/docs/zh-CN/google-vertex-ai#troubleshooting)。2343* 对于 Google Cloud 的 Agent Platform 部署，请参阅 [Google Cloud 的 Agent Platform 故障排除](/docs/zh-CN/google-vertex-ai#troubleshooting)。

2208 2344

2216Model "claud-sonnet-5" is not a recognized model id. Did you mean 'claude-sonnet-5'?2352Model "claud-sonnet-5" is not a recognized model id. Did you mean 'claude-sonnet-5'?

2217```2353```

2218 2354

2219尾部提示命名最接近的匹配别名或模型 ID。当没有足够接近的内容时，它读取 `Run /model to see available models.`。2355尾部提示命名最接近的匹配别名或模型 ID。当没有足够接近的内容时，它读取 `Run /model to see available models.`。在 [Desktop app](/docs/zh-CN/desktop) 启动的会话中，无匹配提示读取 `Switch to a different model.`

2220 2356

2221Claude Code 在请求切换时在本地生成此错误，在发送任何 API 请求之前。它适用于通过 [Agent SDK](/docs/zh-CN/agent-sdk/typescript) `setModel()` 方法设置模型的情况，通过运行 Claude Code CLI 的应用程序（如 [Desktop app](/docs/zh-CN/desktop)），或当您从通过 [Remote Control](/docs/zh-CN/remote-control) 连接的设备选择模型时。在 v2.1.260 之前，检查不涵盖 Remote Control 选择，因此 Claude Code 应用了选择，下一个请求失败，显示[所选模型存在问题](#theres-an-issue-with-the-selected-model)。2357Claude Code 在请求切换时在本地生成此错误，在发送任何 API 请求之前。它适用于通过 [Agent SDK](/docs/zh-CN/agent-sdk/typescript) `setModel()` 方法设置模型的情况，通过运行 Claude Code CLI 的应用程序（如 [Desktop app](/docs/zh-CN/desktop)），或当您从通过 [Remote Control](/docs/zh-CN/remote-control) 连接的设备选择模型时。在 v2.1.260 之前，检查不涵盖 Remote Control 选择，因此 Claude Code 应用了选择，下一个请求失败，显示[所选模型存在问题](#theres-an-issue-with-the-selected-model)。

2222 2358

2245* 如果您输入了完整 ID，请根据您提供商的模型目录检查它。新推出的模型可能在 Anthropic API 上可用，但您的提供商或地区尚未提供。2381* 如果您输入了完整 ID，请根据您提供商的模型目录检查它。新推出的模型可能在 Anthropic API 上可用，但您的提供商或地区尚未提供。

2246* 在 v2.1.265 之前，`/model` 也以此错误拒绝了 `opusplan[1m]` 别名拼写。在这些版本上，更新 Claude Code，或在[设置](/docs/zh-CN/model-config#setting-your-model)中或使用 `--model` 设置模型。2382* 在 v2.1.265 之前，`/model` 也以此错误拒绝了 `opusplan[1m]` 别名拼写。在这些版本上，更新 Claude Code，或在[设置](/docs/zh-CN/model-config#setting-your-model)中或使用 `--model` 设置模型。

2247 2383

2384<h3 id="api-error-model-not-changed">

2385 检查选择的模型时出现 API 错误

2386</h3>

2387

2388您使用 `/model <name>` 选择了模型，或连接到会话的应用程序请求了切换。API 拒绝了 Claude Code 发送以验证模型的最小请求，原因没有自己的条目，例如速率限制或服务器错误。会话保持其当前模型，消息以说明这一点结尾：

2389

2390```text theme={null}

2391API error: 429 <the server's explanation> · model not changed

2392```

2393

2394消息的中间是 HTTP 状态和服务器自己的解释。

2395

2396**要做什么：**

2397

2398* 根据服务器的解释采取行动；对于速率限制或 5xx 状态，等待并再次选择模型

2399* 具有自己措辞的拒绝由周围条目涵盖，例如[模型未找到](#model-not-found)和[模型受您的组织设置限制](#model-is-restricted-by-your-organizations-settings)

2400

2248<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">2401<h3 id="claude-opus-is-not-available-with-the-claude-pro-plan">

2249 Claude Opus 在 Claude Pro 计划中不可用2402 Claude Opus 在 Claude Pro 计划中不可用

2250</h3>2403</h3>

2255Claude Opus is not available with the Claude Pro plan. If you have updated your subscription plan recently, run /logout and /login for the plan to take effect.2408Claude Opus is not available with the Claude Pro plan. If you have updated your subscription plan recently, run /logout and /login for the plan to take effect.

2256```2409```

2257 2410

2411在 Claude Desktop app 运行的会话中，消息说改为`登出并登入`而不是命名命令。

2412

2258**要做什么：**2413**要做什么：**

2259 2414

2260* 运行 `/model` 并选择您的计划包括的模型2415* 运行 `/model` 并选择您的计划包括的模型

2287 模型受您的组织设置限制2442 模型受您的组织设置限制

2288</h3>2443</h3>

2289 2444

2290您的组织管理员在 claude.ai 管理控制台中禁用了此模型，或它被托管设置中的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表排除。当受限制的模型使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 设置设置时，Claude Code 替换允许的模型并继续。为受限制的模型键入 `/model <name>` 被拒绝，显示 `Run /model to choose a different model.`，会话保持其当前模型。替换通知也可能在会话中期出现，在组织管理员在 claude.ai 管理控制台中禁用会话正在运行的模型之后。2445您的组织管理员在 claude.ai 管理控制台中禁用了此模型，或托管设置中的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表或 [`deniedModels`](/docs/zh-CN/model-config#block-specific-models-or-versions) 列表排除了它。当受限制的模型使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 设置设置时，通知在启动时出现，并命名会话使用的模型。如果托管设置没有为会话留下允许的模型，请参阅[托管设置阻止默认模型](#managed-settings-block-the-default-model)。替换通知也可能在会话中期出现，在组织管理员在 claude.ai 管理控制台中禁用会话正在运行的模型之后。

2291 2446

2292```text theme={null}2447```text theme={null}

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

2294```2449```

2295 2450

2451为受限制的模型键入 `/model <name>` 被拒绝，会话保持其当前模型。对于在管理控制台中禁用的模型，拒绝读取 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`。对于托管设置排除的模型，它读取 `Model '<name>' is not available. Your organization restricts model selection.`

2452

2296以代理、技能或命令名称为前缀的通知意味着限制适用于该[子代理的请求模型](/docs/zh-CN/sub-agents#choose-a-model)：子代理在替换模型上运行，您的会话模型保持不变。在 v2.1.223 之前，Claude Code 仅为使用 Agent 工具启动的子代理显示通知。2453以代理、技能或命令名称为前缀的通知意味着限制适用于该[子代理的请求模型](/docs/zh-CN/sub-agents#choose-a-model)：子代理在替换模型上运行，您的会话模型保持不变。在 v2.1.223 之前，Claude Code 仅为使用 Agent 工具启动的子代理显示通知。

2297 2454

2298Claude Code 将模型族别名（`opus`、`sonnet`、`haiku` 或 `fable` 之一）视为对该族的请求，而不是对其最新版本的请求。在 Anthropic API 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 上，受限制的族别名解析为您的组织和 `availableModels` 允许列表允许的族的最新版本，替换通知命名该版本。Claude Code 仅当族的每个版本都受限制时才拒绝 `/model <alias>`。在 v2.1.205 之前，族别名基于其最新版本单独被替换或拒绝，即使同一族的较旧版本被允许。2455Claude Code 将模型族别名（`opus`、`sonnet`、`haiku` 或 `fable` 之一）视为对该族的请求，而不是对其最新版本的请求。在 Anthropic API 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 上，受限制的族别名解析为您的组织的设置允许的族的最新版本，替换通知命名该版本。Claude Code 仅当族的每个版本都受限制时才拒绝 `/model <alias>`。在 v2.1.205 之前，族别名基于其最新版本单独被替换或拒绝，即使同一族的较旧版本被允许。

2299 2456

2300**要做什么：**2457**要做什么：**

2301 2458

2354 2511

2355**要做什么：**2512**要做什么：**

2356 2513

2357* 运行 `claude update` 并重启 Claude Code。Opus 4.7 需要 v2.1.111 或更高版本。Opus 4.8 需要 v2.1.154 或更高版本。Sonnet 5 需要 v2.1.197 或更高版本。Opus 5 需要 v2.1.219 或更高版本。Opus 5.5 需要 v2.1.280 或更高版本2514* 运行 `claude update` 并重启 Claude Code。Opus 4.7 需要 v2.1.111 或更高版本。Opus 4.8 需要 v2.1.154 或更高版本。Sonnet 5 需要 v2.1.197 或更高版本。Opus 5 需要 v2.1.219 或更高版本。Opus 5.5 需要 v2.1.280 或更高版本。Sonnet 5.5 需要 v2.1.284 或更高版本

2358* 如果您无法升级，运行 `/model` 并选择 Opus 4.6 或 Sonnet 4.62515* 如果您无法升级，运行 `/model` 并选择 Opus 4.6 或 Sonnet 4.6

2359* 如果您在 [Agent SDK](/docs/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 或更高版本。Opus 5 需要 TypeScript SDK v0.3.219 或更高版本。Opus 5.5 需要 TypeScript SDK v0.3.280 或更高版本2516* 如果您在 [Agent SDK](/docs/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 或更高版本。Opus 5 需要 TypeScript SDK v0.3.219 或更高版本。Opus 5.5 需要 TypeScript SDK v0.3.280 或更高版本。Sonnet 5.5 需要 TypeScript SDK v0.3.284 或更高版本

2360 2517

2361<h3 id="effort-isnt-available-with-thinking-turned-off">2518<h3 id="effort-isnt-available-with-thinking-turned-off">

2362 关闭思考时努力不可用2519 关闭思考时努力不可用

2368API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0)2525API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0)

2369```2526```

2370 2527

2528`·` 后的提示因会话而异：在非交互式会话中，它读取 `use --effort high (or the effortLevel setting)`，在 Claude Desktop app 运行的会话中，它读取 `you can lower effort to High`。

2529

2371**要做什么：**2530**要做什么：**

2372 2531

2373* [降低努力级别](/docs/zh-CN/model-config#set-the-effort-level)到 `high` 或以下。2532* [降低努力级别](/docs/zh-CN/model-config#set-the-effort-level)到 `high` 或以下。

2374* 打开思考，例如通过取消设置 [`MAX_THINKING_TOKENS`](/docs/zh-CN/env-vars) 或从您的设置中删除 [`"alwaysThinkingEnabled": false`](/docs/zh-CN/settings-reference#alwaysthinkingenabled)。2533* 打开思考，例如通过取消设置 [`MAX_THINKING_TOKENS`](/docs/zh-CN/env-vars) 或从您的设置中删除 [`"alwaysThinkingEnabled": false`](/docs/zh-CN/settings-reference#alwaysthinkingenabled)。

2375 2534

2376在 v2.1.242 之前，Claude Code 显示了 API 自己的消息：`API Error: 400 output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.` 在 v2.1.251 之前，Claude Code 以您设置的努力级别发送请求，因此 Opus 5 拒绝了关闭思考时高于 `high` 的每个请求。Claude Code 现在向它知道拒绝该组合的模型（如 Opus 5）发送努力 `high`，因此在 v2.1.251 或更高版本上，此错误仅从 Claude Code 不知道拒绝它的模型到达您。2535在 v2.1.242 之前，Claude Code 显示了 API 自己的消息：`API Error: 400 output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.` 在 v2.1.251 之前，Claude Code 以您设置的努力级别发送请求，因此 Opus 5 拒绝了关闭思考时高于 `high` 的每个请求。Claude Code 现在向它知道拒绝该组合的模型（如 Opus 5）发送努力 `high`。

2377 2536

2378<h3 id="thinking-budget-exceeds-output-limit">2537<h3 id="thinking-budget-exceeds-output-limit">

2379 思考预算超过输出限制2538 思考预算超过输出限制

2385API Error: 400 ... max_tokens must be greater than thinking.budget_tokens2544API Error: 400 ... max_tokens must be greater than thinking.budget_tokens

2386```2545```

2387 2546

2388Claude Code 在 Anthropic API 上自动调整这些值。当 [`MAX_THINKING_TOKENS`](/docs/zh-CN/env-vars) 设置高于提供商的输出限制时，或当计划模式提高思考预算时，您通常在 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上看到此错误。

~~2389~~

2390**要做什么：**2547**要做什么：**

2391 2548

2392* 降低 `MAX_THINKING_TOKENS`，或提高 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/zh-CN/env-vars) 高于思考预算2549* 提高 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/zh-CN/env-vars) 高于思考预算

2393* 请参阅[扩展思考](/docs/zh-CN/model-config#extended-thinking)以了解预算如何与输出长度交互2550* 请参阅[扩展思考](/docs/zh-CN/model-config#extended-thinking)以了解预算如何与输出长度交互

2394 2551

2395<h3 id="tool-use-or-thinking-block-mismatch">2552<h3 id="tool-use-or-thinking-block-mismatch">

2396 工具使用或思考块不匹配2553 工具使用或思考块不匹配

2397</h3>2554</h3>

2398 2555

2399对话历史以不一致的状态到达 API，通常在工具调用被中断或轮次在流中期被编辑后。2556对话历史以不一致的状态到达 API。

2400 2557

2401```text theme={null}2558```text theme={null}

2402API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.2559API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.

2413* 如果您使用 Opus 4.7 或 Opus 4.8，首先运行 `claude update`。v2.1.156 之前的版本可以在正常工具使用期间触发此错误，`/rewind` 不会清除它。2570* 如果您使用 Opus 4.7 或 Opus 4.8，首先运行 `claude update`。v2.1.156 之前的版本可以在正常工具使用期间触发此错误，`/rewind` 不会清除它。

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

2415 2572

2573<h3 id="invalid-data-in-redacted-thinking-block">

2574 redacted\_thinking 块中的数据无效

2575</h3>

2576

2577API 拒绝了请求，返回 400，因为它无法接受对话历史中较早轮次携带的 `redacted_thinking` 块。

2578

2579```text theme={null}

2580API Error: 400 ... Invalid `data` in `redacted_thinking` block

2581```

2582

2583Claude Code 将对话的较早思考排除在请求之外并重试一次，因此会话继续而不显示错误。在 v2.1.282 之前，Claude Code 保留被拒绝的块，每个后来的轮次都以相同错误失败。

2584

2585**要做什么：**

2586

2587* 如果您在 v2.1.281 或更早版本上，每一轮都失败，显示此错误，运行 `claude update` 并恢复会话

2588* 如果错误持续，运行 `/clear` 以启动不携带该块的对话

2589

2416<h3 id="unsupported-tool-content-removed">2590<h3 id="unsupported-tool-content-removed">

2417 删除了不支持的工具内容2591 删除了不支持的工具内容

2418</h3>2592</h3>

2446 2620

2447**要做什么：**2621**要做什么：**

2448 2622

2449* 运行 `/clear` 以启动新对话。如果错误也在那里返回，原因在请求路径上，而不在保存的对话中。

2450* 如果错误在通过 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 配置的代理或网关后的每一轮上重复，连接而不使用代理以确认源，并向操作它的人报告错误2623* 如果错误在通过 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 配置的代理或网关后的每一轮上重复，连接而不使用代理以确认源，并向操作它的人报告错误

2624* 运行 `/clear` 以启动新对话。如果错误也在那里返回，原因在请求路径上，而不在保存的对话中。

2451 2625

2452在 v2.1.280 之前，Claude Code 不识别此措辞，因此当被拒绝的系统消息是 Claude Code 本身发送的时，错误也出现，对话的每个后来轮次都以相同方式失败。2626在 v2.1.280 之前，Claude Code 不识别此措辞，因此当被拒绝的系统消息是 Claude Code 本身发送的时，错误也出现，对话的每个后来轮次都以相同方式失败。

2453 2627

2458API 拒绝了请求，返回 400，因为对话历史包含它无法解密的托管网络搜索内容。措辞命名它无法读取的字段：2632API 拒绝了请求，返回 400，因为对话历史包含它无法解密的托管网络搜索内容。措辞命名它无法读取的字段：

2459 2633

2460```text theme={null}2634```text theme={null}

2461API Error: 400 messages.21.content.0: Invalid `encrypted_content` in `search_result` block2635API Error: 400 ... Invalid `encrypted_content` in `search_result` block

2462API Error: 400 messages.21.content.3.citations.0: Invalid `encrypted_index` in `text` block2636API Error: 400 ... Invalid `encrypted_index` in `text` block

2463API Error: 400 Failed to decrypt web search result content2637API Error: 400 ... Failed to decrypt web search result content

2638API Error: 400 ... Invalid `encrypted_stdout` in `encrypted_code_execution_result` block

2464```2639```

2465 2640

2466来自 API 的托管[网络搜索工具](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)的结果携带只有 API 可以读取的加密字段。API 拒绝重放它无法解密的内容的请求，如为不同组织生成的内容。2641来自 API 的托管[网络搜索工具](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)的结果携带只有 API 可以读取的加密字段。`encrypted_stdout` 措辞命名读取这样的结果的托管代码执行程序的输出，API 也加密。API 拒绝重放它无法解密的内容的请求，如为不同组织生成的内容。

2467 2642

2468Claude Code 自己的 [WebSearch 工具](/docs/zh-CN/tools-reference#websearch-tool-behavior)将搜索结果记录为纯文本，因此这些块通常通过代理或 [LLM gateway](/docs/zh-CN/llm-gateway) 到达对话，该网关自己运行了托管网络搜索。2643Claude Code 自己的 [WebSearch 工具](/docs/zh-CN/tools-reference#websearch-tool-behavior)将搜索结果记录为纯文本，因此这些块通常通过代理或 [LLM gateway](/docs/zh-CN/llm-gateway) 到达对话，该网关自己运行了托管网络搜索。

2469 2644

2470被拒绝的块保留在对话历史中，因此每个后来的轮次和 `/compact` 都以相同方式失败。2645对于三个网络搜索措辞，Claude Code 将搜索调用、结果和引用排除在它发送的内容之外并重试请求一次，因此会话继续而不显示错误。`encrypted_stdout` 措辞没有这样的恢复，因此该消息仍然到达您。在 v2.1.282 之前，Claude Code 也保留了被拒绝的网络搜索块，每个后来的轮次和 `/compact` 都以相同方式失败。

2471 2646

2472**要做什么：**2647**要做什么：**

2473 2648

2474* 运行 `/clear` 或启动新会话；新对话不携带被拒绝的块2649* 如果您在 v2.1.281 或更早版本上，每一轮都失败，显示网络搜索措辞之一，运行 `claude update` 并恢复会话

2650* 如果错误持续，或消息命名 `encrypted_stdout`，运行 `/rewind` 回退到添加内容的轮次之前的检查点，或运行 `/clear` 启动不携带它的对话

2475* 如果您在代理或网关后运行 Claude Code，向操作它的人报告错误2651* 如果您在代理或网关后运行 Claude Code，向操作它的人报告错误

2476 2652

2477<h3 id="usage-policy-refusal">2653<h3 id="usage-policy-refusal">

2478 使用政策拒绝2654 使用政策拒绝

2479</h3>2655</h3>

2480 2656

2481API 拒绝了响应，因为对话中的内容触发了[使用政策](https://www.anthropic.com/legal/aup)检查。消息包括您可以引用给支持的请求 ID，如果您认为拒绝不正确。2657API 拒绝了响应，因为对话中的内容触发了[使用政策](https://www.anthropic.com/legal/aup)检查。

2658

2659消息包括请求 ID 和消息 ID，您可以引用给支持，如果您认为拒绝不正确。

2482 2660

2483```text theme={null}2661```text theme={null}

2484API Error: Opus 4.6 can't help with this. Start a new session to continue.2662API Error: Opus 4.6 can't help with this. Start a new session to continue.

2508API Error: Opus 4.8's safeguards flagged this message. Our intentionally broad safeguards allow us to deliver more capabilities faster, but can sometimes flag legitimate cybersecurity work. Apply to the Cyber Verification Program to reduce these interruptions. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude2686API Error: Opus 4.8's safeguards flagged this message. Our intentionally broad safeguards allow us to deliver more capabilities faster, but can sometimes flag legitimate cybersecurity work. Apply to the Cyber Verification Program to reduce these interruptions. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude

2509```2687```

2510 2688

2511消息链接到[网络安全验证计划](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)，该计划为合法网络安全工作授予访问权限。在 Opus 5.5 上（需要 v2.1.280 或更高版本），消息以 `Opus 5.5's safeguards flagged this session` 开头。当标记的类别有可用的后备模型时，Claude Code [切换模型](/docs/zh-CN/model-config#automatic-model-fallback) 而不是显示此错误。2689消息链接到[网络安全验证计划](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)，该计划为合法网络安全工作授予访问权限。在 Opus 5.5 和 Sonnet 5.5 上，消息以 `<model>'s safeguards flagged this session` 开头。当标记的类别有可用的后备模型时，Claude Code [切换模型](/docs/zh-CN/model-config#automatic-model-fallback) 而不是显示此错误。

2512 2690

2513在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上，网络安全标记会产生[使用政策拒绝](#usage-policy-refusal)消息。2691在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上，网络安全标记会产生[使用政策拒绝](#usage-policy-refusal)消息。

2514 2692

2550 下载更新时连接断开2728 下载更新时连接断开

2551</h3>2729</h3>

2552 2730

2553在 `claude install`、`claude update` 或 [自动更新程序](/docs/zh-CN/setup#auto-updates) 获取 Claude Code 二进制文件时，与下载服务器的连接关闭，重试也没有恢复。当连接断开、传输停滞或下载的文件校验和失败时，Claude Code 会重试下载，总共最多尝试三次。已完成的 HTTP 错误（例如 404）不会重试，因为服务器已经响应。在 v2.1.202 之前，单个断开的连接会立即导致下载失败，并显示裸错误 `aborted`，而不是重试。2731与下载服务器的连接在 `claude install` 或 `claude update` 获取 Claude Code 二进制文件时关闭，重试也没有恢复。当连接断开、传输停滞或下载的文件校验和失败时，Claude Code 会重试下载，总共最多尝试三次。已完成的 HTTP 错误（例如 404）不会重试，因为服务器已经响应。在 v2.1.202 之前，单个断开的连接会立即导致下载失败，并显示裸错误 `aborted`，而不是重试。

2554 2732

2555```text theme={null}2733```text theme={null}

2556The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.2734The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

2560 2738

2561保持连接但在 10 分钟内未完成的下载失败，显示 `Download timed out: exceeded the total deadline`。Claude Code 不会重试超时的下载，因为连接速度太慢而无法在截止时间内完成，在立即重试时也不会完成。以下步骤适用于两条消息。2739保持连接但在 10 分钟内未完成的下载失败，显示 `Download timed out: exceeded the total deadline`。Claude Code 不会重试超时的下载，因为连接速度太慢而无法在截止时间内完成，在立即重试时也不会完成。以下步骤适用于两条消息。

2562 2740

2563通常的原因是代理或网关在长传输完成前关闭它。Claude Code 二进制文件是一个大型下载，因此永远不会影响正常 API 流量的代理连接限制仍然可能中断它。2741代理或网关可以在长传输完成前关闭它，而 Claude Code 二进制文件是一个大型下载。

2564 2742

2565**应该做什么：**2743**应该做什么：**

2566 2744

2594 无效的 --agents 配置2772 无效的 --agents 配置

2595</h3>2773</h3>

2596 2774

2597您传递给 `--agents` 的值无效，因此 `claude` 以代码 1 退出，而不是启动会话。当您传递 `--safe-mode`、`--resume` 或 `--continue`，或设置 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-CN/env-vars#variables) 时，Claude Code 不会检查该值并启动会话。在 v2.1.242 之前，Claude Code 无论如何都会启动会话，并遗漏它无法加载的定义。2775您传递给 `--agents` 的值无效，因此 `claude` 以代码 1 退出，而不是启动会话。当您传递 `--safe-mode` 或设置 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-CN/env-vars#variables) 时，Claude Code 忽略 `--agents` 完全。使用 `--resume` 或 `--continue` 时，内联 JSON 值不被检查，会话启动；从文件读取的值在每次启动时被检查。在 v2.1.242 之前，Claude Code 无论如何都会启动会话。

2598 2776

2599```text theme={null}2777```text theme={null}

2600Error: Invalid --agents configuration:2778Error: Invalid --agents configuration:

2603 2781

2604第一行之后的内容取决于值如何失败。Claude Code 按顺序运行这些检查，并在第一个失败的检查处停止。如果您的值有两种问题，您只有在修复第一个问题后才会看到第二个问题：2782第一行之后的内容取决于值如何失败。Claude Code 按顺序运行这些检查，并在第一个失败的检查处停止。如果您的值有两种问题，您只有在修复第一个问题后才会看到第二个问题：

2605 2783

26061. 当值不能解析为 JSON 时，Claude Code 打印一行 `invalid JSON:` 行，其中包含 JSON 解析器自己的消息27841. 当值以 `{` 开头但不能解析为 JSON 时，或 `--agents` 文件的内容不能解析时，Claude Code 打印一行 `invalid JSON:` 行，其中包含 JSON 解析器自己的消息

26072. 当它解析但代理定义与 [CLI 定义的子代理](/docs/zh-CN/sub-agents#choose-the-subagent-scope) 的架构不匹配时，Claude Code 为每个问题打印一行27852. 当它解析但代理定义与 [CLI 定义的子代理](/docs/zh-CN/sub-agents#choose-the-subagent-scope) 的架构不匹配时，Claude Code 为每个问题打印一行

26083. 当代理名称以 `-` 开头时，Claude Code 打印 `<name>: agent names must not start with '-'`27863. 当代理名称以 `-` 开头时，Claude Code 打印 `<name>: agent names must not start with '-'`

2609 2787

2610当有超过 20 个问题行时，Claude Code 打印前 20 个，并用 `…and N more` 替换其余的。2788当有超过 20 个问题行时，Claude Code 打印前 20 个，并用 `…and N more` 替换其余的。

2611 2789

2790使用 `--print` 时，`--agents` 也接受[JSON 文件的路径](/docs/zh-CN/sub-agents#choose-the-subagent-scope)代替内联对象。在 v2.1.281 之前，`--agents` 仅接受内联 JSON，并将文件路径视为无效 JSON。文件形式有其自己的拒绝，打印在此消息的位置，包括这些：

2791

2792* **`Error: --agents takes a JSON object, or a file path only with --print (-p)`**：Claude Code 在交互式会话中将值读取为文件路径。将定义作为内联 JSON 传递，或添加 `-p` 从文件读取它们。

2793* **`Error: --agents file not found: <path>`**：该路径处不存在文件。不以 `{` 开头且不是有效 JSON 的值被读取为路径，因此您的 shell 损坏的内联 JSON 也可能以这种方式失败。检查路径或引用，然后再次运行命令。

2794

2612**要做什么：**2795**要做什么：**

2613 2796

2614* 修复消息列出的每个问题，然后再次运行命令。请参阅 [CLI 定义的子代理采用的字段](/docs/zh-CN/sub-agents#choose-the-subagent-scope)。2797* 修复消息列出的每个问题，然后再次运行命令。请参阅 [CLI 定义的子代理采用的字段](/docs/zh-CN/sub-agents#choose-the-subagent-scope)。

2668**要做什么：**2851**要做什么：**

2669 2852

2670* 修复诊断命名的架构部分，然后重新运行命令2853* 修复诊断命名的架构部分，然后重新运行命令

2671* 如果诊断是 `schema too large`，请减少架构的嵌套和 `$ref` 重用

2672* 请参阅[获取结构化输出](/docs/zh-CN/headless#get-structured-output)以获取工作架构和命令2854* 请参阅[获取结构化输出](/docs/zh-CN/headless#get-structured-output)以获取工作架构和命令

2673 2855

2674<h3 id="settings-file-exceeds-the-2mib-limit">2856<h3 id="settings-file-exceeds-the-2mib-limit">

2675 设置文件超过 2MiB 限制2857 设置文件超过 2MiB 限制

2676</h3>2858</h3>

2677 2859

2678您传递给 [`--settings`](/docs/zh-CN/cli-reference#cli-flags) 的文件大于 2 MiB，因此 `claude` 在启动时以代码 1 退出，而不是加载它。设置文件是一个小的 JSON 文档，所以这么大的文件通常意味着路径指向错误的文件。在 v2.1.214 之前，Claude Code 读取文件时没有大小检查，多 GB 的文件或诸如 `/dev/zero` 之类的设备文件会无限增长内存。2860您传递给 [`--settings`](/docs/zh-CN/cli-reference#cli-flags) 的文件大于 2 MiB，因此 `claude` 在启动时以代码 1 退出，而不是加载它。在 v2.1.214 之前，Claude Code 读取文件时没有大小检查，多 GB 的文件或诸如 `/dev/zero` 之类的设备文件会无限增长内存。

2679 2861

2680```text theme={null}2862```text theme={null}

2681Error: Settings file exceeds the 2MiB limit: /path/to/settings.json2863Error: Settings file exceeds the 2MiB limit: /path/to/settings.json

2756 启动远程控制时工作区不受信任2938 启动远程控制时工作区不受信任

2757</h3>2939</h3>

2758 2940

2759您在未信任的目录中使用 `claude remote-control` 或其 `claude rc` 别名启动了[远程控制](/docs/zh-CN/remote-control)服务器模式。该命令本身不显示工作区信任对话框，因此它以代码 1 退出并命名修复：2941您在未信任的目录中使用 `claude remote-control` 或其 `claude rc` 别名启动了[远程控制](/docs/zh-CN/remote-control)服务器模式，命令无法询问您是否信任它。当命令的标准输入或标准输出不是终端时，此消息会出现，例如因为其中之一被重定向或管道化。命令以代码 1 退出：

2760 2942

2761```text theme={null}2943```text theme={null}

2762Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.2944Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.

2763```2945```

2764 2946

2947两个也以 `Error: Workspace not trusted.` 开头的变体也出现在足够小的终端中，无法显示信任目录打开的内容，或一个没有报告其大小的终端。扩大窗口或切换到正常终端窗口，然后再次运行 `claude rc`。

2948

2765在您的主目录中，消息是不同的，因为工作区信任对话框永远不会保存主目录的信任，因此在那里接受它无法满足此检查。在 v2.1.214 之前，主目录显示上述消息，其建议无法在那里成功。2949在您的主目录中，消息是不同的，因为工作区信任对话框永远不会保存主目录的信任，因此在那里接受它无法满足此检查。在 v2.1.214 之前，主目录显示上述消息，其建议无法在那里成功。

2766 2950

2767```text theme={null}2951```text theme={null}

2768Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).2952Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).

2769```2953```

2770 2954

2955如果您在 [`Trust <directory>?` 问题](/docs/zh-CN/remote-control#requirements)处回答 `n` 或按 Enter，命令会打印一条 `Remote Control did not start` 消息，命名目录并以代码 1 退出。再次运行 `claude rc` 以回答 `y`。

2956

2771**要做什么：**2957**要做什么：**

2772 2958

2773* 在目录中运行 `claude`，接受[工作区信任对话框](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)，然后再次运行 `claude remote-control`2959* 首先从终端信任目录：在那里运行 `claude rc` 并回答 `y`，或运行 `claude` 并接受[工作区信任对话框](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)，然后再次运行您的原始命令

2774* 在您的主目录中，更改为项目目录并在那里启动远程控制2960* 在您的主目录中，更改为项目目录并在那里启动远程控制

2775 2961

2962在 v2.1.284 之前，命令从不询问，即使在终端中。

2963

2776<h3 id="not-carried-over-to-the-sessions-remote-control-starts">2964<h3 id="not-carried-over-to-the-sessions-remote-control-starts">

2777 未被远程控制启动的会话继承2965 未被远程控制启动的会话继承

2778</h3>2966</h3>

2834 无法从 Claude Desktop 导入服务器3022 无法从 Claude Desktop 导入服务器

2835</h3>3023</h3>

2836 3024

2837Claude Code 无法添加您在 `claude mcp add-from-claude-desktop` 中选择的其中一个服务器。该命令仍然导入其他选定的服务器，并为每个无法添加的服务器打印一行。在 v2.1.205 之前，第一个失败的服务器会停止导入，所有选定的服务器都不会被添加。3025Claude Code 无法添加您在 `claude mcp add-from-claude-desktop` 中选择的其中一个服务器。该命令仍然导入其他选定的服务器，并为每个无法添加的服务器打印一行。在 v2.1.205 之前，第一个失败的服务器会停止导入。

2838 3026

2839```text theme={null}3027```text theme={null}

2840Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.3028Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.

3083 Diff 对于 ultrareview 来说太大3271 Diff 对于 ultrareview 来说太大

3084</h3>3272</h3>

3085 3273

3274Diff 对于 ultrareview 来说太大：812 个文件，96,410 行更改（限制：500 个文件，8,000 行）。最大的文件：package-lock.json（41,904 行），dist/bundle.js（18,210 行），src/generated/api.ts（9,876 行）。传递更接近的基础分支（`/code-review ultra <branch>`）以缩小范围，或拆分更改。

3275

3086您的分支与基础分支之间的差异，包括未提交和暂存的更改，超过了 [ultrareview](/docs/zh-CN/ultrareview) 的大小限制，因此 `/code-review ultra` 和 `claude ultrareview` 子命令在云会话启动前拒绝审查。被拒绝的审查不使用免费运行，也不计费使用信用。消息命名生效的限制、您的差异大小以及贡献最多更改行的文件。在 v2.1.216 之前，消息仅显示原始差异统计。3276您的分支与基础分支之间的差异，包括未提交和暂存的更改，超过了 [ultrareview](/docs/zh-CN/ultrareview) 的大小限制，因此 `/code-review ultra` 和 `claude ultrareview` 子命令在云会话启动前拒绝审查。被拒绝的审查不使用免费运行，也不计费使用信用。消息命名生效的限制、您的差异大小以及贡献最多更改行的文件。在 v2.1.216 之前，消息仅显示原始差异统计。

3087 3277

3088```text theme={null}3278```text theme={null}

3269* 对于交互式会话，使用 `claude --resume` 打开[会话选择器](/docs/zh-CN/sessions#use-the-session-picker)，按 `Ctrl+A` 将其扩展到此机器上的每个项目，然后选择会话3459* 对于交互式会话，使用 `claude --resume` 打开[会话选择器](/docs/zh-CN/sessions#use-the-session-picker)，按 `Ctrl+A` 将其扩展到此机器上的每个项目，然后选择会话

3270* 使用 `claude -p` 或 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 创建的会话不会出现在选择器中，因此重新检查 ID 与您的原始运行打印的 `session_id`3460* 使用 `claude -p` 或 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 创建的会话不会出现在选择器中，因此重新检查 ID 与您的原始运行打印的 `session_id`

3271 3461

3462<h3 id="windows-reported-an-error-ebadf">

3463 Windows 报告了读取此会话的成绩单文件时的错误 (EBADF)

3464</h3>

3465

3466您在 Windows 上恢复了一个会话，其保存的[成绩单文件](/docs/zh-CN/sessions#where-transcripts-are-stored)正常打开，读取它然后失败，错误为 EBADF。系统错误没有说为什么读取失败，因此消息建议可能的原因和要尝试的内容：

3467

3468```text theme={null}

3469Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again.

3470```

3471

3472消息遵循命令自己的失败行，例如 `Failed to resume session <session-id>`。`claude --resume` 或 [`claude -p`](/docs/zh-CN/headless) 命令在显示它后以代码 1 退出。在会话内的 `/resume` 后，您当前的会话保持运行。

3473

3474**要做什么：**

3475

3476* 从扫描或拦截文件读取的软件（如安全、加密或端点管理工具）中排除保存会话成绩单的文件夹。成绩单默认位于 `%USERPROFILE%\.claude\projects` 下，或位于 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars) 命名的目录下

3477* 如果您无法添加排除项，改为将 Claude Code 添加到该软件的允许应用程序中

3478* 再次恢复会话

3479

3480在 v2.1.282 之前，失败没有解释：`claude --resume <session-id>` 在 `Failed to resume session <session-id>` 处结束，`-p` 运行仅打印系统错误文本，例如 `Failed to resume session: EBADF: bad file descriptor, read`。

3481

3272<h3 id="cannot-switch-renderers-in-this-session">3482<h3 id="cannot-switch-renderers-in-this-session">

3273 无法在此会话中切换渲染器3483 无法在此会话中切换渲染器

3274</h3>3484</h3>

3452* 将 marketplace 重命名为不拼写保留名称的名称并重新添加它3662* 将 marketplace 重命名为不拼写保留名称的名称并重新添加它

3453* 对于被忽略的条目警告，运行它给出的 `claude plugin marketplace remove` 命令，或从 `~/.claude/plugins/known_marketplaces.json` 中删除该条目3663* 对于被忽略的条目警告，运行它给出的 `claude plugin marketplace remove` 命令，或从 `~/.claude/plugins/known_marketplaces.json` 中删除该条目

3454 3664

3665<h3 id="claude-code-refuses-the-marketplace-name">

3666 Claude Code 拒绝 marketplace 名称

3667</h3>

3668

3669已注册的 marketplace 的名称 [冒充官方 Anthropic marketplace](/docs/zh-CN/plugins/marketplace-reference#reserved-names)，根据该部分列出的规则。

3670

3671如果 marketplace 在这样的名称下注册时检查阻止了它，marketplace 和从中安装的 plugin 停止加载，因为 Claude Code 每次读取 marketplace 的目录时都会检查名称。当名称模仿官方名称时，`claude plugin list` 和 `/plugin` **Errors** 选项卡报告每个受影响的 plugin，消息开头为：

3672

3673```text theme={null}

3674Claude Code refuses the marketplace name "anthropic-plugins-v2"

3675```

3676

3677对于模仿名称，marketplace 自己的错误读作 `Claude Code refuses this marketplace's name: it looks like one of Anthropic's own`。`claude plugin marketplace add` 拒绝任何冒充名称，消息为 `Marketplace name impersonates an official Anthropic/Claude marketplace`。

3678

3679在 v2.1.282 之前，`claude plugin list` 和 `/plugin` 报告模仿名称的 plugin 也加载失败，没有将 marketplace 的名称命名为原因。

3680

3681**要做什么：**

3682

3683* 运行 `claude plugin marketplace remove <name>`。这也会卸载从 marketplace 安装的 plugin 并删除其保存的数据

3684* 要保留 marketplace，请等待其维护者重命名它，然后运行 `claude plugin marketplace update <name>`

3685* 如果您发布 marketplace，在您的 `marketplace.json` 中重命名它；用户随后更新 marketplace 而不是删除它

3686

3455<h3 id="marketplace-is-already-added-from-a-different-source">3687<h3 id="marketplace-is-already-added-from-a-different-source">

3456 Marketplace 已从不同的源添加3688 Marketplace 已从不同的源添加

3457</h3>3689</h3>

3654 3886

3655* 要求您的 claude.ai 组织的管理员在 claude.ai 上更改 plugin 的必需状态3887* 要求您的 claude.ai 组织的管理员在 claude.ai 上更改 plugin 的必需状态

3656 3888

3889<h3 id="plugin-was-not-uninstalled">

3890 Plugin 未被卸载

3891</h3>

3892

3893您运行了 [`claude plugin uninstall`](/docs/zh-CN/plugins/cli-reference#plugin-uninstall)，或在 `/plugin` **Installed** 选项卡中选择了 **Uninstall**，卸载停止，消息开头为 `"<plugin>" was not uninstalled:`。

3894

3895当 Claude Code 从 `enabledPlugins` 中删除 plugin 的条目并读回该范围的设置文件时，要么 plugin 仍在那里被打开，要么可以打开它的文件无法读取或检查。在设置条目可以将其重新打开时删除 plugin 的保存选项、机密和数据会丢失它们，因此卸载停止：plugin 保持安装，它保存的任何内容都不会被删除。

3896

3897```text theme={null}

3898✘ Failed to uninstall plugin "formatter": "formatter" was not uninstalled: it is still switched on in /home/user/project/.claude/settings.local.json, although the settings change reported no error. It is still installed. Take it out of "enabledPlugins" in that file yourself, then uninstall it again.

3899```

3900

3901消息的中间部分命名文件和原因：

3902

3903* `it is still switched on in <file>, although the settings change reported no error`：设置写入报告成功但条目在读回文件时仍然存在

3904* `it is still switched on in <file>, and the settings change failed (<error>)`：文件无法保存，原因在括号中

3905* `<file> is there and could not be read`：文件存在但无法作为设置读取，例如因为它不是有效的 JSON，所以它可能仍然启用 plugin

3906* `<file> (not read: it is on a network path or is a link to one, or could not be checked)`：Claude Code 没有读取项目或本地设置文件，因为文件或保存它的 `.claude` 文件夹是指向网络位置的链接，或因为它无法检查该路径

3907

3908`claude plugin uninstall` 退出 1，使用 `--json` 时结果包含 `failureCode: "settings_still_on"`。`/plugin` 显示相同的消息。

3909

3910**要做什么：**

3911

3912* 遵循消息的最后一句：修复或替换它命名的设置文件，或自己从该文件中的 `enabledPlugins` 中删除 plugin 的条目，然后再次运行卸载

3913

3657<h2 id="tool-errors">3914<h2 id="tool-errors">

3658 工具错误3915 工具错误

3659</h2>3916</h2>

3703* 如果 Claude 应该能够更改文件，请在 `/permissions` 或[设置](/docs/zh-CN/settings-reference#permission-settings)中删除或缩小 `Read` 拒绝规则3960* 如果 Claude 应该能够更改文件，请在 `/permissions` 或[设置](/docs/zh-CN/settings-reference#permission-settings)中删除或缩小 `Read` 拒绝规则

3704* 如果文件必须保持不变，请保留该规则并为相同路径添加 `Edit` 拒绝规则以同时阻止 NotebookEdit 工具3961* 如果文件必须保持不变，请保留该规则并为相同路径添加 `Edit` 拒绝规则以同时阻止 NotebookEdit 工具

3705 3962

3963<h3 id="path-cannot-contain-null-bytes">

3964 路径不能包含空字节

3965</h3>

3966

3967文件工具调用的路径或模式参数包含空字节，文件系统和搜索工具无法接受。Read、Write、Edit、NotebookEdit、Glob 和 Grep 检查此项，消息命名工具和参数：

3968

3969```text theme={null}

3970Read file_path cannot contain null bytes (\0). Remove the null byte and try again.

3971```

3972

3973工具调用失败，Claude 看到错误，轮次继续。

3974

3975**应该做什么：**

3976

3977* 你这边不需要做任何事：错误作为工具的结果返回给 Claude，消息本身告诉 Claude 删除空字节并重试

3978

3979在 v2.1.281 之前，Read、Write、Edit 或 NotebookEdit 路径中的空字节会以命名 `Path contains null bytes` 的错误结束整个轮次，工具从不运行。

3980

3706<h3 id="subagent-type-is-required">3981<h3 id="subagent-type-is-required">

3707 subagent\_type 是必需的3982 subagent\_type 是必需的

3708</h3>3983</h3>

3839 4114

3840在 v2.1.236 之前，Claude Code 报告这些发送已发送。接收会话未读地丢弃了它们。4115在 v2.1.236 之前，Claude Code 报告这些发送已发送。接收会话未读地丢弃了它们。

3841 4116

4117<h3 id="cross-session-message-dropped-at-the-inbox">

4118 跨会话消息在收件人会话的收件箱处被丢弃

4119</h3>

4120

4121Claude 发送了[跨会话消息](/docs/zh-CN/cross-session-messaging)到此机器上你的另一个会话，该会话的收件箱在 Claude 在该会话中读取之前丢弃了它。该行命名收件人的地址，当收件人给出原因时，在破折号后添加原因：

4122

4123```text wrap theme={null}

4124Cross-session message was dropped at the recipient session's inbox (recipient: uds:/tmp/cc-socks/13605.sock) and not delivered — its queue of undelivered peer messages was full. Claude was told not to resend right away.

4125```

4126

4127一行可以覆盖多条丢弃的消息。然后它以复数形式开始，例如 `Cross-session messages (12) were dropped`。要找到地址属于哪个会话，请将其与 `/status` 在每个会话中显示的 [`Peer address` 行](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket)进行比较。

4128

4129在破折号后，该行给出以下一个或多个原因：

4130

4131* `its queue of undelivered peer messages was full`：收件人已经持有尽可能多的来自其他会话的未送达消息，其队列允许

4132* `you sent faster than that session accepts`：发送会话的消息到达速度比收件人从一个发送者接受的速度快

4133* `it repeated your previous message`：该消息与发送会话不久前发送给该收件人的消息相同

4134* `a relay loop between sessions was cut`：该消息继续了会话相互发送消息的链，链已通过收件人太多次或增长太长

4135

4136**应该做什么：**

4137

4138* 假设收件人从未看到丢弃的消息。Claude Code 告诉 Claude 相同的内容，并告诉它改为在一条稍后的消息中包含仍然重要的任何内容，而不是立即重新发送

4139* 如果你的会话相互发送频繁更新，要求 Claude 发送更少、更大的消息，例如会话完成其工作时的一份报告

4140* 对于 `a relay loop between sessions was cut`，在其中一个会话中自己输入下一条指令。Claude 发送以响应你自己的提示的消息开始一条新链

4141

4142在 v2.1.238 之前，当收件人的收件箱丢弃消息时，发送会话没有收到报告。

4143

3842<h3 id="refusing-to-send-a-cross-session-message">4144<h3 id="refusing-to-send-a-cross-session-message">

3843 拒绝发送跨会话消息4145 拒绝发送跨会话消息

3844</h3>4146</h3>

3853 4155

3854* `reply target is a symlink`：符号链接位于目标会话的套接字路径。Claude Code 不通过它传递，因为那里的链接可能会将消息重定向到目标会话未创建的端点。4156* `reply target is a symlink`：符号链接位于目标会话的套接字路径。Claude Code 不通过它传递，因为那里的链接可能会将消息重定向到目标会话未创建的端点。

3855* `cannot vet reply target`：Claude Code 根本无法检查目标路径，例如因为读取失败并出现权限错误。4157* `cannot vet reply target`：Claude Code 根本无法检查目标路径，例如因为读取失败并出现权限错误。

3856* `connected endpoint is not the expected process`：持有套接字的进程不是消息寻址到的会话，因此地址已过时或另一个进程替换了套接字。

3857* `connected endpoint identity could not be read`：Claude Code 已连接但无法读取哪个进程持有另一端，因此无法确认目标。这可能是暂时的。

3858* `connected endpoint is not owned by this user`：持有套接字的进程以不同的用户帐户运行，因此它不是你的会话之一。

3859* `connected endpoint owner could not be read`：Claude Code 已连接但无法读取哪个用户帐户拥有另一端，因此无法确认端点是你的。

3860* `connected endpoint is a different process with the expected pid`：进程 id 与消息寻址到的进程 id 匹配，但 Claude Code 无法确认它是同一进程。通常该会话已退出，操作系统重用了其进程 id，因此地址已过时。

3861 4158

3862**应该做什么：**4159**应该做什么：**

3863 4160

3864* 通常不需要做任何事：检查防止消息到达除了它寻址到的会话之外的端点，什么都没有发送4161* 通常不需要做任何事：检查防止消息到达除了它寻址到的会话之外的端点，什么都没有发送

3865* 要求 Claude 再次列出你的会话并重新发送；由过时地址引起的拒绝在 Claude 发送到当前会话后清除

3866* 如果 `reply target is a symlink` 对一个会话重复，检查在该会话的套接字路径处创建了什么链接，显示在其 `/status` 下的 `Peer address`4162* 如果 `reply target is a symlink` 对一个会话重复，检查在该会话的套接字路径处创建了什么链接，显示在其 `/status` 下的 `Peer address`

3867* 对于 `connected endpoint identity could not be read`，重新发送；该条件可能是暂时的

3868* 如果 `connected endpoint is not owned by this user` 出现在共享机器上，该地址处的会话以另一个用户的帐户运行，因此 Claude 无法从你的帐户给它发消息

~~3869~~

3870在 v2.1.248 之前，Claude Code 没有检查端点的拥有用户或进程启动时间，因此命名这些检查的拒绝不会出现在早期版本上。

3871 4163

3872<h3 id="refusing-after-a-symlink-changed">4164<h3 id="refusing-after-a-symlink-changed">

3873 拒绝读取、写入或搜索路径4165 拒绝读取、写入或搜索路径

3883 4175

3884* `its symlink resolution changed after permission was checked`：路径上的符号链接或 Grep 或 Glob 搜索根在权限检查和操作之间被替换。在读取拒绝中，括号中的短语命名哪个比较失败。4176* `its symlink resolution changed after permission was checked`：路径上的符号链接或 Grep 或 Glob 搜索根在权限检查和操作之间被替换。在读取拒绝中，括号中的短语命名哪个比较失败。

3885* `its parent-directory symlink resolution changed after permission was checked`：写入路径通过的目录不再解析到批准的位置4177* `its parent-directory symlink resolution changed after permission was checked`：写入路径通过的目录不再解析到批准的位置

4178* `where it leads on disk could not be determined (a link on the way could not be examined, or the links do not resolve)`：Claude Code 无法跟随路径到磁盘上的最终位置，例如因为其上的符号链接形成循环

3886* `it is a symbolic link. Write to the link's target path instead`：符号链接位于批准的写入位置本身，例如 `CLAUDE.md` 是 `AGENTS.md` 的符号链接；消息指导 Claude 到链接的目标4179* `it is a symbolic link. Write to the link's target path instead`：符号链接位于批准的写入位置本身，例如 `CLAUDE.md` 是 `AGENTS.md` 的符号链接；消息指导 Claude 到链接的目标

3887* `Refusing to write through symlink: <path>. Resolve the symlink and pass the real target path explicitly.`：当另一个写入器打开文件时捕获的相同条件，例如写入符号链接的 `.mcp.json`4180* `Refusing to write through symlink: <path>. Resolve the symlink and pass the real target path explicitly.`：当另一个写入器打开文件时捕获的相同条件，例如写入符号链接的 `.mcp.json`

3888* `Refusing to write into symlinked directory: <path>`：持有文件的目录本身是符号链接，例如项目的 `.claude/` 目录链接到另一个位置4181* `Refusing to write into symlinked directory: <path>`：持有文件的目录本身是符号链接，例如项目的 `.claude/` 目录链接到另一个位置

3901 4194

3902在 v2.1.251 之前，Claude Code 仅对文件写入重新检查路径的解析，因此在权限检查后替换的链接可能会将读取或搜索重定向到不同的位置而没有消息。其中，仅父目录、通过符号链接和符号链接目录写入拒绝出现在早期版本上。4195在 v2.1.251 之前，Claude Code 仅对文件写入重新检查路径的解析，因此在权限检查后替换的链接可能会将读取或搜索重定向到不同的位置而没有消息。其中，仅父目录、通过符号链接和符号链接目录写入拒绝出现在早期版本上。

3903 4196

4197在 v2.1.280 之前，`where it leads on disk could not be determined` 拒绝没有出现。

4198

3904<h3 id="task-output-swap-refused">4199<h3 id="task-output-swap-refused">

3905 任务输出交换被拒绝4200 任务输出交换被拒绝

3906</h3>4201</h3>

3926* 或检查你的项目在 Claude Code 临时目录下的目录，示例消息中的 `/private/tmp/claude-501/-Users-you-my-project`。如果该路径是符号链接或不应该存在的目录，删除链接或目录本身而不是链接的目标，然后重启 Claude Code4221* 或检查你的项目在 Claude Code 临时目录下的目录，示例消息中的 `/private/tmp/claude-501/-Users-you-my-project`。如果该路径是符号链接或不应该存在的目录，删除链接或目录本身而不是链接的目标，然后重启 Claude Code

3927* 如果拒绝重复，进程在会话运行时替换、链接或删除 Claude Code 临时目录下的条目。将 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars) 设置为没有其他东西管理的目录并重启4222* 如果拒绝重复，进程在会话运行时替换、链接或删除 Claude Code 临时目录下的条目。将 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars) 设置为没有其他东西管理的目录并重启

3928 4223

4224<h3 id="disk-quota-or-temp-filesystem-is-full">

4225 磁盘配额或临时文件系统已满

4226</h3>

4227

4228Claude Code 将每个 Bash 和 PowerShell 命令的输出保存到其临时目录下的文件。当命令以非零代码退出且完全没有输出时，Claude Code 检查持有该文件的文件系统是否空间不足或 inode 不足，或你在其上的磁盘配额是否已用完。如果是这样，诊断出现在命令的结果中，代替空输出：

4229

4230```text wrap theme={null}

4231Your disk quota is full on the filesystem with Claude Code's temp directory /private/tmp/claude-501/-Users-you-my-project/1f0e62dc-4b0a-4f5e-9c2d-8a7b6c5d4e3f/tasks (EDQUOT), so any output this command printed was lost, and it may have failed because it could not write. Delete files you no longer need there, or restart Claude Code with CLAUDE_CODE_TMPDIR set to a directory on another filesystem.

4232```

4233

4234该消息命名什么用完了：

4235

4236* `Your disk quota is full ... (EDQUOT)`：你在该文件系统上的配额已用完。配额可以在文件系统仍显示可用空间时已满

4237* `The filesystem with Claude Code's temp directory ..., or your disk quota on it, is full (ENOSPC)`：文件系统或你在其上的配额没有剩余空间

4238* `Command output was lost: the temp filesystem at ... is full` 或 `... is out of inodes`：文件系统几乎没有剩余空间，或 inode 即将用完

4239

4240**应该做什么：**

4241

4242* 删除你在持有 Claude Code 临时目录的文件系统上不再需要的文件。对于 `EDQUOT`，删除计入你自己配额的文件。对于 `out of inodes`，删除许多文件而不是几个大文件，因为每个文件占用一个 inode，无论其大小如何

4243* 或使用设置为具有空间的文件系统上的目录的 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars)重启 Claude Code

4244* 然后让 Claude 再次运行该命令。它打印的输出已丢失，未被截断

4245

3929<h3 id="the-source-file-is-not-valid-utf-8-text">4246<h3 id="the-source-file-is-not-valid-utf-8-text">

3930 源文件不是有效的 UTF-8 文本4247 源文件不是有效的 UTF-8 文本

3931</h3>4248</h3>

3993 后台会话中拒绝的命令4310 后台会话中拒绝的命令

3994</h3>4311</h3>

3995 4312

3996打开交互式对话框的命令在没有终端附加到后台会话时无法执行。`/install-github-app`、`/mcp` 设置列表和 MCP 服务器菜单中的身份验证操作会响应一条消息，该会话在[代理视图](/docs/zh-CN/agent-view)中的**需要输入**下显示，以便您可以找到它、附加并再次运行该命令。附加终端时，这些命令正常工作。4313打开交互式对话框的命令在没有终端附加到后台会话时无法执行。`/install-github-app`、`/mcp` 设置列表和 MCP 服务器菜单中的身份验证操作会响应一条消息。对于 `/install-github-app` 和 `/mcp` 设置列表，该会话也在[代理视图](/docs/zh-CN/agent-view)中的**需要输入**下显示，以便您可以找到它、附加并再次运行该命令。附加终端时，这些命令正常工作。

3997 4314

3998在 v2.1.216 之前，会话在其中一次拒绝后不会在**需要输入**下显示。在 v2.1.213 到 v2.1.215 中，附加终端时命令仍然有效，拒绝消息告诉您附加并再次运行该命令。从 v2.1.208 到 v2.1.212，Claude Code 即使附加了终端也拒绝了它们，消息如 `Can't open MCP settings in a background session`；在这些版本上，从常规 `claude` 会话运行该命令，或升级。在 v2.1.208 之前，它们在后台会话内打开了对话框。在仅 v2.1.208 中，Claude Code 也拒绝了后台会话中的 `/model` 选择器，`/upgrade` 打印了升级 URL 而不是打开浏览器。4315在 v2.1.216 之前，会话在拒绝 `/install-github-app` 或 `/mcp` 设置列表后不会在**需要输入**下显示。在 v2.1.213 到 v2.1.215 中，附加终端时命令仍然有效，拒绝消息告诉您附加并再次运行该命令。从 v2.1.208 到 v2.1.212，Claude Code 即使附加了终端也拒绝了它们，消息如 `Can't open MCP settings in a background session`；在这些版本上，从常规 `claude` 会话运行该命令，或升级。在 v2.1.208 之前，它们在后台会话内打开了对话框。在仅 v2.1.208 中，Claude Code 也拒绝了后台会话中的 `/model` 选择器，`/upgrade` 打印了升级 URL 而不是打开浏览器。

3999 4316

4000措辞命名该命令。`/mcp` 设置列表报告：4317措辞命名该命令。`/mcp` 设置列表报告：

4001 4318

4005 4322

4006**要做什么：**4323**要做什么：**

4007 4324

4008* 从代理视图附加到会话，其中它在**需要输入**下列出，然后再次运行该命令4325* 从代理视图附加到会话并再次运行该命令

4009* 或使用消息命名的形式，例如 `/mcp reconnect <server>`、`/mcp enable` 或 `/mcp disable`，这些不需要附加即可工作4326* 或使用消息命名的形式，例如 `/mcp reconnect <server>`、`/mcp enable` 或 `/mcp disable`，这些不需要附加即可工作

4010 4327

4011<h3 id="write-or-command-blocked-because-the-path-cannot-be-safely-resolved">4328<h3 id="write-or-command-blocked-because-the-path-cannot-be-safely-resolved">

4040**要做什么：**4357**要做什么：**

4041 4358

4042* 通常什么都不做：Claude 使用消息要求的本地拼写重试4359* 通常什么都不做：Claude 使用消息要求的本地拼写重试

4043* 如果文件在网络共享上而不是用网络路径拼写的本地文件，它在会话的本地工作区之外；改为从常规交互式会话编辑它

4044 4360

4045<h3 id="command-blocked-by-the-worktree-isolation-checks">4361<h3 id="command-blocked-by-the-worktree-isolation-checks">

4046 命令被 worktree 隔离检查阻止4362 命令被 worktree 隔离检查阻止

4277 4593

4278在 npm 安装上，在 `npm install -g @anthropic-ai/claude-code` 替换二进制文件时出现的 `EUNKNOWN` 与[重新安装期间的 `EACCES`](#eacces-when-starting-a-background-session) 有相同的原因，并在您在安装完成后重试时清除。4594在 npm 安装上，在 `npm install -g @anthropic-ai/claude-code` 替换二进制文件时出现的 `EUNKNOWN` 与[重新安装期间的 `EACCES`](#eacces-when-starting-a-background-session) 有相同的原因，并在您在安装完成后重试时清除。

4279 4595

4280Claude Code 通过 PowerShell 启动后台服务，以便服务在关闭终端后存活，在安装时使用 PowerShell 7，否则使用 Windows PowerShell 5.1。当两个 PowerShell 都无法运行时，Claude Code 直接启动服务，因此仅阻止 PowerShell 的策略不会导致此错误。如果您在没有 npm 安装运行时看到它，策略正在阻止 Claude Code 可执行文件本身。4596Claude Code 通过 PowerShell 启动后台服务，以便服务在关闭终端后存活，在安装时使用 PowerShell 7，否则使用 Windows PowerShell 5.1。当两个 PowerShell 都无法运行时，Claude Code 直接启动服务，因此仅阻止 PowerShell 的策略不会导致此错误。

4281 4597

4282在 v2.1.212 之前，Claude Code 仅使用 Windows PowerShell 5.1 启动服务，因此任何组策略阻止 PowerShell 5.1 的机器失败，出现 `Couldn't start the session — EUNKNOWN: unknown error, uv_spawn`，即使安装了 PowerShell 7。4598在 v2.1.212 之前，Claude Code 仅使用 Windows PowerShell 5.1 启动服务，因此任何组策略阻止 PowerShell 5.1 的机器失败，出现 `Couldn't start the session — EUNKNOWN: unknown error, uv_spawn`，即使安装了 PowerShell 7。

4283 4599

4341 启动后台会话时工作目录不再存在4657 启动后台会话时工作目录不再存在

4342</h3>4658</h3>

4343 4659

4344您尝试在不再存在的目录中启动[后台会话](/docs/zh-CN/agent-view)。当您从代理视图分派或在删除或移动您正在工作的目录后运行 `/background` 时，会发生这种情况。当您附加到或重启一个进程已退出且目录已消失的会话时，也会发生这种情况，因为新进程会在相同的目录中启动。Claude Code 不启动会话，消息命名缺失的目录：4660您尝试在不再存在的目录中启动[后台会话](/docs/zh-CN/agent-view)。Claude Code 不启动会话，消息命名缺失的目录：

4345 4661

4346```text theme={null}4662```text theme={null}

4347Couldn't start a background session (working directory no longer exists or is not accessible: /tmp/demo)4663Couldn't start a background session (working directory no longer exists or is not accessible: /tmp/demo)

4349 4665

4350在 v2.1.257 之前，会话似乎启动，然后在代理视图中显示为具有相同原因的失败行。4666在 v2.1.257 之前，会话似乎启动，然后在代理视图中显示为具有相同原因的失败行。

4351 4667

4668在 v2.1.281 之前，当您启动会话之前目录已经消失时，此消息也出现。该情况报告[`could not be resolved on disk`](#workspace-not-trusted-when-dispatching-a-background-session)。

4669

4352**要做什么：**4670**要做什么：**

4353 4671

4354* 重新创建消息命名的目录，或从存在的目录分派，然后重试4672* 重新创建消息命名的目录，或从存在的目录分派，然后重试

4355 4673

4674<h3 id="workspace-not-trusted-when-dispatching-a-background-session">

4675 分派后台会话时工作区不受信任

4676</h3>

4677

4678您在未[信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)的目录中启动或重启[后台会话](/docs/zh-CN/agent-view)，工作区信任对话无法出现以询问您。Claude Code 不启动会话：

4679

4680```text theme={null}

4681Workspace not trusted. Run `claude` in /path/to/project once and accept the trust prompt, then retry.

4682```

4683

4684从会话自己的目录中的终端，相同的命令显示信任对话，并在您接受后启动会话。此消息出现在无法显示对话的地方，例如在脚本中，或当您从不同于其自己的目录重启会话时。

4685

4686两个变体命名不同的原因：

4687

4688* **`The home directory is trusted one session at a time`**：会话的目录是您的主目录。Claude Code 从不保存主目录的信任，因此在早期会话中接受那里的对话不计数。

4689* **`<path> could not be resolved on disk`**：Claude Code 无法在磁盘上找到会话的目录。

4690

4691**要做什么：**

4692

4693* 在消息命名的目录中运行 `claude` 并接受信任对话，然后再次运行该命令

4694* 对于主目录消息，从您的主目录中的终端运行该命令，以便对话可以出现，或改为从项目目录启动会话

4695* 对于 `could not be resolved on disk` 消息，重新创建目录，或从存在的目录启动新会话

4696

4356<h2 id="wrapper-and-ide-errors">4697<h2 id="wrapper-and-ide-errors">

4357 包装器和 IDE 错误4698 包装器和 IDE 错误

4358</h2>4699</h2>

4437 4778

4438* 确定哪些文件被跳过，以便您可以使用下面的步骤处理每个文件。该消息仅给出计数；`~/.claude/debug/<session-id>.txt` 中的调试日志在恢复运行时命名每个跳过的路径，因此在下次恢复之前使用 `/debug` 打开调试日志。在 macOS 或 Linux 上，您可以直接找到链接：`find . -type l` 用于符号链接，`find . -type f -links +1` 用于硬链接文件。4779* 确定哪些文件被跳过，以便您可以使用下面的步骤处理每个文件。该消息仅给出计数；`~/.claude/debug/<session-id>.txt` 中的调试日志在恢复运行时命名每个跳过的路径，因此在下次恢复之前使用 `/debug` 打开调试日志。在 macOS 或 Linux 上，您可以直接找到链接：`find . -type l` 用于符号链接，`find . -type f -links +1` 用于硬链接文件。

4439* 如果跳过的文件是您有意创建的链接，例如由点文件管理器管理的配置文件或由 pnpm 等工具硬链接的文件，rewind 保持其内容不变。要撤销会话对其所做的更改，请要求 Claude 反转编辑或自己编辑文件4780* 如果跳过的文件是您有意创建的链接，例如由点文件管理器管理的配置文件或由 pnpm 等工具硬链接的文件，rewind 保持其内容不变。要撤销会话对其所做的更改，请要求 Claude 反转编辑或自己编辑文件

4440* 如果您没有创建该链接，请在信任其内容之前检查该路径：某些内容在检查点后替换了该文件4781* 如果您没有创建该链接，请在信任其内容之前检查该路径

4441 4782

4442<h3 id="no-files-were-restored">4783<h3 id="no-files-were-restored">

4443 No files were restored4784 No files were restored

4528* 如果这是顶级会话，请退出并使用设置的 [`CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1`](/docs/zh-CN/env-vars) 重新启动。保存从重新启动时开始应用，因此在此之前发送的消息不会被保存。4869* 如果这是顶级会话，请退出并使用设置的 [`CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1`](/docs/zh-CN/env-vars) 重新启动。保存从重新启动时开始应用，因此在此之前发送的消息不会被保存。

4529* 要修复从同一终端或启动器的未来启动，请从其环境中删除 `CLAUDE_CODE_CHILD_SESSION`4870* 要修复从同一终端或启动器的未来启动，请从其环境中删除 `CLAUDE_CODE_CHILD_SESSION`

4530 4871

4872***

4873

4874title: "配置警告"

4875description: "了解 Claude Code 配置警告、其含义以及如何解决它们。"

4876-----------------------------------------------

4877

4531<h2 id="configuration-warnings">4878<h2 id="configuration-warnings">

4532 配置警告4879 配置警告

4533</h2>4880</h2>

4548 4895

4549**要做什么：**4896**要做什么：**

4550 4897

4551* 按照[全屏渲染](/docs/zh-CN/fullscreen#fullscreen-renderer-didnt-finish-starting)进行操作。它说明您获得哪个通知、Claude Code 在后续会话中执行的操作，以及如何再次尝试全屏或保持经典渲染器。4898* 按照[全屏渲染](/docs/zh-CN/fullscreen#fullscreen-renderer-didnt-finish-starting)进行操作。它说明您获得哪个通知、Claude Code 在后续会话中的操作，以及如何再次尝试全屏或保持经典渲染器。

4552* 如果已退出的会话打印了退出消息，请参阅 [Claude Code 在无法恢复的界面错误后退出](#exited-after-an-unrecoverable-interface-error)了解其名称。4899* 如果已死亡的会话打印了退出消息，请参阅[Claude Code 因无法恢复的界面错误而退出](#exited-after-an-unrecoverable-interface-error)了解其名称。

4553 4900

4554在 v2.1.236 之前，Claude Code 在启动失败后不打印通知，并继续在全屏渲染中启动会话。4901在 v2.1.236 之前，Claude Code 未打印通知，并在失败启动后继续在全屏渲染中启动会话。

4555 4902

4556<h3 id="exited-after-an-unrecoverable-interface-error">4903<h3 id="exited-after-an-unrecoverable-interface-error">

4557 Claude Code 在无法恢复的界面错误后退出4904 Claude Code 因无法恢复的界面错误而退出

4558</h3>4905</h3>

4559 4906

4560当 Claude Code 退出时会打印此消息，因为其终端界面遇到了无法恢复的错误，在任一渲染器中都可能发生。第二句仅在[全屏](/docs/zh-CN/fullscreen)渲染器启动时发生错误时出现：4907当 Claude Code 退出时，它会打印此消息，因为其终端界面在任一渲染器中遇到了无法恢复的错误。第二句仅在[全屏](/docs/zh-CN/fullscreen)渲染器启动时发生错误时出现：

4561 4908

4562```text theme={null}4909```text theme={null}

4563Claude Code exited after an unrecoverable interface error (<error>). It happened while the fullscreen renderer was starting, so the next launch will use the classic renderer (CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 forces that any time).4910Claude Code exited after an unrecoverable interface error (<error>). It happened while the fullscreen renderer was starting, so the next launch will use the classic renderer (CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN=1 forces that any time).

4566**要做什么：**4913**要做什么：**

4567 4914

4568* 再次启动 Claude Code。要继续该对话，请在同一目录中运行 `claude --resume`。4915* 再次启动 Claude Code。要继续该对话，请在同一目录中运行 `claude --resume`。

4569* 如果消息提到全屏渲染器，[全屏渲染](/docs/zh-CN/fullscreen#fullscreen-renderer-didnt-finish-starting)说明下一次启动执行的操作，这取决于您如何打开全屏，以及如何再次尝试全屏或保持经典渲染器。4916* 如果消息命名全屏渲染器，[全屏渲染](/docs/zh-CN/fullscreen#fullscreen-renderer-didnt-finish-starting)说明下一次启动的操作，这取决于您如何打开全屏，以及如何再次尝试全屏或保持经典渲染器。

4570 4917

4571在 v2.1.236 之前，Claude Code 在此类错误后退出而不打印消息。4918在 v2.1.236 之前，Claude Code 在此类错误后退出而不打印消息。

4572 4919

4573<h3 id="agent-descriptions-are-over-the-15000-token-limit">4920<h3 id="agent-descriptions-are-over-the-15000-token-limit">

4574 Agent 描述超过 15.0k 令牌限制4921 代理描述超过 15.0k 令牌限制

4575</h3>4922</h3>

4576 4923

4577Claude Code 将此警告显示为对话视图中的启动通知，而不是在 stderr 上。您的[子代理](/docs/zh-CN/sub-agents)（除了内置代理）的组合描述超过 15,000 个令牌，按 Claude Code 的估计。每个代理计算其名称加上其 `description` frontmatter。Claude Code 加载每个代理，无论总数是否超过限制，因此警告不会改变加载的内容。4924Claude Code 将此警告显示为对话视图中的启动通知，而不是在 stderr 上。您的[子代理](/docs/zh-CN/sub-agents)（除了内置代理）的组合描述超过 Claude Code 估计的 15,000 个令牌。每个代理计算其名称加上其 `description` frontmatter。Claude Code 加载每个代理，无论总数是否超过限制，因此警告不会改变加载的内容。

4578 4925

4579```text theme={null}4926```text theme={null}

4580Agent descriptions are over the 15.0k-token limit (~16.2k tokens) · ask Claude to trim agent descriptions in .claude/agents/4927Agent descriptions are over the 15.0k-token limit (~16.2k tokens) · ask Claude to trim agent descriptions in .claude/agents/

4585* 缩短您的代理文件的 `description` frontmatter，或要求 Claude 为您修剪它们。4932* 缩短您的代理文件的 `description` frontmatter，或要求 Claude 为您修剪它们。

4586* 删除您不再使用的代理文件。4933* 删除您不再使用的代理文件。

4587 4934

4935<h3 id="a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved">

4936 技能、命令或工作流未被加载，因为其名称是保留的

4937</h3>

4938

4939技能文件夹、frontmatter `name`、`.claude/commands/` 中的文件或子文件夹，或[保存的工作流](/docs/zh-CN/workflows#save-the-workflow-for-reuse)使用名称 `anthropic-skills` 或以 `anthropic-skills:` 开头的名称。Claude Code [为从 claude.ai 同步的技能保留该名称](/docs/zh-CN/skills#names-reserved-for-synced-skills)，不加载该项。

4940

4941Claude Code 将此警告显示为对话视图中的启动通知，而不是在 stderr 上：

4942

4943```text theme={null}

4944Not loaded: rename .claude/skills/anthropic-skills, then restart — its name uses "anthropic-skills", a name reserved for the skills synced from your claude.ai account

4945```

4946

4947通知命名它拒绝的第一项：要重命名的文件夹或文件、要编辑的 `name:` 行，或要重命名的工作流。当拒绝多个项时，通知以计数结尾，例如 `· 2 more`，[调试日志](/docs/zh-CN/debug-your-config)命名每一个。

4948

4949**要做什么：**

4950

4951* 重命名通知命名的项，或编辑它指向的 `name:` 行，然后重启会话。

4952

4953在 v2.1.282 之前，Claude Code 加载具有这些名称的技能和命令。

4954

4588<h3 id="workspace-has-not-been-trusted">4955<h3 id="workspace-has-not-been-trusted">

4589 工作区尚未被信任4956 工作区尚未被信任

4590</h3>4957</h3>

4591 4958

4592Claude Code 在项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中找到了 `permissions.allow` 规则或 `permissions.additionalDirectories` 条目，但没有应用它们，因为[项目设置中的允许规则需要工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)。计数、设置名称和消息中命名的文件因您的配置而异。`deny` 和 `ask` 规则不受影响。4959Claude Code 在项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中找到了 `permissions.allow` 规则或 `permissions.additionalDirectories` 条目，但未应用它们，因为[来自项目设置的允许规则需要工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)。计数、设置名称和消息中命名的文件因您的配置而异。`deny` 和 `ask` 规则不受影响。

4593 4960

4594```text theme={null}4961```text theme={null}

4595Ignoring 2 permissions.allow entries from .claude/settings.local.json: this workspace has not been trusted. Run Claude Code interactively here once and accept the trust dialog, or set projects["/Users/you/project"].hasTrustDialogAccepted: true in /Users/you/.claude.json.4962Ignoring 2 permissions.allow entries from .claude/settings.local.json: this workspace has not been trusted. Run Claude Code interactively here once and accept the trust dialog, or set projects["/Users/you/project"].hasTrustDialogAccepted: true in /Users/you/.claude.json.

4597 4964

4598**要做什么：**4965**要做什么：**

4599 4966

4600* 在目录中运行 `claude` 并接受信任对话框。[项目允许规则和工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)说明该接受涵盖哪个文件夹。4967* 在目录中运行 `claude` 并接受信任对话框。[项目允许规则和工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)说明该接受涵盖的文件夹。

4601* 在[非交互模式](/docs/zh-CN/headless)中使用 `-p` 时不显示对话框。使用消息打印的确切 `projects` 键在 `~/.claude.json` 中设置 `hasTrustDialogAccepted` 条目。4968* 在[非交互模式](/docs/zh-CN/headless)中使用 `-p` 不显示对话框。使用消息打印的确切 `projects` 键在 `~/.claude.json` 中设置 `hasTrustDialogAccepted` 条目。

4602* 如果消息提到 `.claude/settings.local.json` 并且您在 git 存储库外或主目录中启动了 Claude Code，请更新到 v2.1.200 或更高版本。版本 2.1.196 到 2.1.199 在这些工作区中将您自己的 `.claude/settings.local.json` 视为存储库提供的。在 v2.1.207 及更高版本上，如果您尚未信任该文件夹，在 git 存储库外更新是不够的：确定文件夹不在存储库内会运行 git，Claude Code 仅在您接受信任对话框后才运行该检查，因此请使用第一步。您的主目录和任何其他[配置主目录](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)是豁免的，不需要等待对话框。请参阅[项目允许规则和工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)。4969* 如果消息命名 `.claude/settings.local.json` 并且您在 git 存储库外或主目录中启动了 Claude Code，请更新到 v2.1.200 或更高版本。版本 2.1.196 至 2.1.199 在这些工作区中将您自己的 `.claude/settings.local.json` 视为存储库提供的。在 v2.1.207 及更高版本上，如果您尚未信任该文件夹，在 git 存储库外更新是不够的：确定文件夹不在存储库内会运行 git，Claude Code 仅在您接受信任对话框后才运行该检查，因此请使用第一步。您的主目录和任何其他[配置主目录](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)是豁免的，不等待对话框。请参阅[项目允许规则和工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)。

4603 4970

4604<h3 id="working-directory-is-a-network-path">4971<h3 id="working-directory-is-a-network-path">

4605 工作目录是网络路径4972 工作目录是网络路径

4606</h3>4973</h3>

4607 4974

4608Claude Code 不会将网络路径添加为工作目录。查找网络路径可能会联系它命名的主机，在 Windows 上该联系可能会向主机发送您的凭据，因此 Claude Code 拒绝该路径而不查找它。当您使用此类路径运行 `/add-dir` 时，或作为启动时的警告，您会看到此消息。当它在启动时出现时，Claude Code 启动时不包含该目录。4975Claude Code 不将网络路径添加为工作目录。查找网络路径可以联系它命名的主机，在 Windows 上该联系可以向主机发送您的凭据，因此 Claude Code 拒绝该路径而不查找它。当您使用此类路径运行 `/add-dir` 时，或作为启动时的警告，您会看到此消息。当它在启动时出现时，Claude Code 启动时不包含该目录。

4609 4976

4610```text theme={null}4977```text theme={null}

4611\\server\share is a network path, which cannot be added as a working directory. On Windows, map the share to a drive letter and pass it at launch with --add-dir (a drive letter added mid-session does not yet carry remote-read trust).4978\\server\share is a network path, which cannot be added as a working directory. On Windows, map the share to a drive letter and pass it at launch with --add-dir (a drive letter added mid-session does not yet carry remote-read trust).

4631 远程托管设置加载失败4998 远程托管设置加载失败

4632</h3>4999</h3>

4633 5000

4634您的会话符合[服务器托管设置](/docs/zh-CN/server-managed-settings)的条件，但 Claude Code 无法获取它们，因此在交互式会话中显示此警告。括号中的原因命名失败的内容，例如 `network error`、`request timed out` 或 `authentication rejected (401)`，行的其余部分说明会话运行的策略：5001您的会话符合[服务器托管设置](/docs/zh-CN/server-managed-settings)的条件，但 Claude Code 无法获取它们或无法应用服务器返回的内容，因此在交互式会话中显示此警告。

5002

5003括号中的原因命名失败的内容，例如 `network error`、`request timed out` 或 `authentication rejected (401)`。原因 `no setting in the server response could be applied as written` 意味着服务器已应答，但它返回的设置都没有通过[验证](/docs/zh-CN/server-managed-settings#invalid-entries-in-delivered-settings)。在 v2.1.282 之前，此原因读取 `server returned invalid settings`。

4635 5004

4636* **从较早的成功获取缓存的设置**：Claude Code 在该缓存策略上运行会话，除了[扣留的环境变量](/docs/zh-CN/server-managed-settings#fetch-and-caching-behavior)，该行读作 `using cached policy`。5005该行的其余部分说明会话运行的策略：

4637* **无缓存**：Claude Code 在没有服务器托管设置的情况下运行会话，该行读作 `no remote policy applied`。5006

5007* **从较早的成功获取缓存的设置**：Claude Code 在该缓存策略上运行会话，除了[扣留的环境变量](/docs/zh-CN/server-managed-settings#fetch-and-caching-behavior)，行读取 `using cached policy`。

5008* **无缓存**：Claude Code 在没有服务器托管设置的情况下运行会话，行读取 `no remote policy applied`。

4638 5009

4639**要做什么：**5010**要做什么：**

4640 5011

4641* 对消息命名的原因采取行动：对于网络原因，检查此计算机是否可以到达 `api.anthropic.com`；对于身份验证原因，使用 `/status` 检查您的登录5012* 对消息命名的原因采取行动：对于网络原因，检查此计算机是否可以到达 `api.anthropic.com`；对于身份验证原因，使用 `/status` 检查您的登录

5013* 对于 `no setting in the server response could be applied as written`，要求您的管理员更正服务器上的设置

4642* 运行 `/status` 或 `claude doctor` 以获取完整诊断5014* 运行 `/status` 或 `claude doctor` 以获取完整诊断

4643 5015

4644在 v2.1.248 之前，Claude Code 仅在调试日志中报告失败的设置获取。5016在 v2.1.248 之前，Claude Code 仅在调试日志中报告失败的设置获取。

4647 托管设置未被批准5019 托管设置未被批准

4648</h3>5020</h3>

4649 5021

4650您的组织的[服务器托管设置](/docs/zh-CN/server-managed-settings)包括需要您批准的设置，而您拒绝了[安全批准对话框](/docs/zh-CN/server-managed-settings#security-approval-dialogs)，因此 Claude Code 退出而不应用它们：5022您的组织的[服务器托管设置](/docs/zh-CN/server-managed-settings)包括需要您批准的设置，您拒绝了[安全批准对话框](/docs/zh-CN/server-managed-settings#security-approval-dialogs)，因此 Claude Code 退出而不应用它们：

4651 5023

4652```text theme={null}5024```text theme={null}

4653Managed settings were not approved; exiting without applying them.5025Managed settings were not approved; exiting without applying them.

4656**要做什么：**5028**要做什么：**

4657 5029

4658* 再次启动 Claude Code 并批准对话框以在您的组织设置下继续。拒绝的对话框不被记住，因此在下一次启动时再次出现。5030* 再次启动 Claude Code 并批准对话框以在您的组织设置下继续。拒绝的对话框不被记住，因此在下一次启动时再次出现。

4659* 如果您对对话框列出的设置不确定，在批准前询问维护您的组织托管设置的人5031* 如果您对对话框列出的设置不确定，请在批准前询问维护您的组织托管设置的人

5032

5033<h3 id="managed-settings-block-the-default-model">

5034 托管设置阻止默认模型

5035</h3>

5036

5037您的组织的[托管设置](/docs/zh-CN/managed-settings)阻止默认选项解析到的模型以及它可以降级到的每个模型。将在默认选项上启动的会话在启动时退出，而不是运行被阻止的模型。您看到的消息取决于阻止它的设置。当 [`deniedModels`](/docs/zh-CN/model-config#block-specific-models-or-versions) 列表阻止它时，消息读取：

5038

5039```text theme={null}

5040Claude Code can't start: your organization's managed settings block the default model (claude-opus-5-5) in "deniedModels", and none of the models they allow can be used as the default instead. Ask your administrator to update "deniedModels" or "availableModels".

5041```

5042

5043当 `availableModels` 列表与 [`availableModelsMatch`](/docs/zh-CN/settings-reference#availablemodelsmatch) 设置为 `"exact"` 省略它时，消息读取：

5044

5045```text theme={null}

5046Claude Code can't start: your organization allows only the models listed in "availableModels", and none of them can be used as the default model (claude-opus-5-5 isn't listed). Ask your administrator to update "availableModels".

5047```

5048

5049**要做什么：**

5050

5051* 如果您管理设置，请将您的用户可以运行的模型添加到 `availableModels`，或缩小阻止每个回退的 `deniedModels` 条目。[阻止特定模型或版本](/docs/zh-CN/model-config#block-specific-models-or-versions)描述默认选项如何降级

5052* 如果您不管理它们，请将消息发送给您的管理员。您自己的设置文件无法扩大托管的 `availableModels` 或 `deniedModels` 列表

4660 5053

4661<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">5054<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">

4662 MCP 服务器被企业托管策略阻止5055 MCP 服务器被企业托管策略阻止

4663</h3>5056</h3>

4664 5057

4665您在 `/mcp` 中的服务器上选择了**重新连接**，或在那里重新打开了禁用的服务器，而[限制 MCP 服务器](/docs/zh-CN/managed-mcp)的设置阻止了该服务器。Claude Code 拒绝连接它并显示：5058您在 `/mcp` 中的服务器上选择了**重新连接**，或在那里重新打开了禁用的服务器，[限制 MCP 服务器](/docs/zh-CN/managed-mcp)的设置阻止了该服务器。Claude Code 拒绝连接它并显示：

4666 5059

4667```text theme={null}5060```text theme={null}

4668MCP server <name> is blocked by enterprise managed policy5061MCP server <name> is blocked by enterprise managed policy

4669```5062```

4670 5063

4671以下任何设置都可能产生该消息：5064这些设置中的任何一个都可以产生消息：

4672 5065

4673* 与服务器匹配的 [`deniedMcpServers`](/docs/zh-CN/managed-mcp#policy-based-control-with-allowlists-and-denylists) 条目，包括您自己的 `~/.claude/settings.json` 或项目的 `.claude/settings.json` 中的条目5066* 与服务器匹配的 [`deniedMcpServers`](/docs/zh-CN/managed-mcp#policy-based-control-with-allowlists-and-denylists) 条目，包括您自己的 `~/.claude/settings.json` 或项目的 `.claude/settings.json` 中的条目

4674* 服务器不匹配的 [`allowedMcpServers`](/docs/zh-CN/managed-mcp#policy-based-control-with-allowlists-and-denylists) 列表5067* 服务器不匹配的 [`allowedMcpServers`](/docs/zh-CN/managed-mcp#policy-based-control-with-allowlists-and-denylists) 列表

4675* [`strictPluginOnlyCustomization`](/docs/zh-CN/settings-reference#strictpluginonlycustomization) 且 `mcp` 被锁定，这阻止了在 `~/.claude.json` 和 `.mcp.json` 中配置的服务器5068* [`strictPluginOnlyCustomization`](/docs/zh-CN/settings-reference#strictpluginonlycustomization) 与 `mcp` 锁定，这阻止在 `~/.claude.json` 和 `.mcp.json` 中配置的服务器

4676* [`disableClaudeAiConnectors`](/docs/zh-CN/mcp#disable-claude-ai-connectors)，当服务器是 claude.ai 连接器时5069* [`disableClaudeAiConnectors`](/docs/zh-CN/mcp#disable-claude-ai-connectors)，当服务器是 claude.ai 连接器时

4677 5070

4678**要做什么：**5071**要做什么：**

4679 5072

4680* 检查您自己的用户和项目设置文件中的这些设置之一，并更改或删除它5073* 检查您自己的用户和项目设置文件中的这些设置之一，并更改或删除它

4681* 如果您自己的设置都不能解释该阻止，请询问您的管理员哪个托管设置阻止了该服务器5074* 如果您自己的设置都不能解释该阻止，请询问您的管理员哪个托管设置阻止了服务器

4682 5075

4683在 v2.1.257 之前，`/mcp` 中的**重新连接**和重新启用可能会连接一个中途策略更新阻止的服务器。5076在 v2.1.257 之前，`/mcp` 中的**重新连接**和重新启用可以连接中途策略更新阻止的服务器。

4684 5077

4685<h3 id="managed-settings-document-could-not-be-parsed">5078<h3 id="managed-settings-document-could-not-be-parsed">

4686 托管设置文档无法解析5079 托管设置文档无法解析

4687</h3>5080</h3>

4688 5081

4689您的组织部署了[托管设置](/docs/zh-CN/managed-settings)，其中一个部署的文档存在但无法解析为 JSON 对象，因此 Claude Code 在启动时以代码 1 退出，而不是在没有文档携带的策略的情况下运行。该行在消息前命名失败的源：5082您的组织部署[托管设置](/docs/zh-CN/managed-settings)，其中一个部署的文档存在但无法解析为 JSON 对象，因此 Claude Code 在启动时以代码 1 退出，而不是在没有文档携带的策略的情况下运行。该行在消息前命名失败的源：

4690 5083

4691```text theme={null}5084```text theme={null}

4692/Library/Application Support/ClaudeCode/managed-settings.json: Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.5085/Library/Application Support/ClaudeCode/managed-settings.json: Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.

4700 5093

4701[查找 Claude Code 删除的条目](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)列出了使每个源无法解析的原因。5094[查找 Claude Code 删除的条目](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)列出了使每个源无法解析的原因。

4702 5095

4703Claude Code 拒绝启动，即使另一个管理员源提供了有效的策略。您在交互式会话、`claude -p`、Agent SDK 会话、[后台会话](/docs/zh-CN/agent-view)和大多数子命令（包括 `claude doctor`）中看到此错误。拒绝故意失败关闭：Claude Code 无法解析的文档中的设置无法被强制执行，启动时不应用组织的控制会运行会话。5096Claude Code 拒绝启动，即使另一个管理员源提供有效策略。您在交互式会话、`claude -p`、Agent SDK 会话、[后台会话](/docs/zh-CN/agent-view)和大多数子命令（包括 `claude doctor`）中看到此错误。拒绝故意失败关闭：Claude Code 无法解析的文档中的设置无法被强制执行，启动时不运行会话会在没有组织控制的情况下运行。

4704 5097

4705可解析文档中的架构问题不会产生此错误。[查找 Claude Code 删除的条目](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)涵盖 Claude Code 对其所做的操作。5098可解析文档中的架构问题不会产生此错误。[查找 Claude Code 删除的条目](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)涵盖 Claude Code 对其所做的操作。

4706 5099

4707当 `managed-settings.d/` 目录存在但无法列出时，Claude Code 报告 `Managed settings drop-in directory could not be read:` 后跟基础错误。[查找 Claude Code 删除的条目](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)涵盖读取失败在启动时退出的情况。5100当 `managed-settings.d/` 目录存在但无法列出时，Claude Code 报告 `Managed settings drop-in directory could not be read:` 后跟基础错误。[查找 Claude Code 删除的条目](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)涵盖读取失败在启动时退出的时间。

4708 5101

4709**要做什么：**5102**要做什么：**

4710 5103

4715 otelHeadersHelper 失败5108 otelHeadersHelper 失败

4716</h3>5109</h3>

4717 5110

4718当 [`otelHeadersHelper`](/docs/zh-CN/settings-reference#otelheadershelper) 脚本失败或打印不符合[脚本要求](/docs/zh-CN/monitoring-usage#script-requirements)的输出时，Claude Code 在交互式会话中显示此警告作为终端界面中的通知，每个会话一次。5111当 [`otelHeadersHelper`](/docs/zh-CN/settings-reference#otelheadershelper) 脚本失败或打印不符合[脚本要求](/docs/zh-CN/monitoring-usage#script-requirements)的输出时，Claude Code 将此警告显示为终端界面中的通知，每个交互式会话一次。

4719 5112

4720当脚本继续失败时，导出失败，您的遥测后端从会话中接收不到任何内容。5113当脚本继续失败时，导出失败，您的遥测后端从会话中接收不到任何内容。

4721 5114

4731* 修复脚本使其在 30 秒内退出 0 并在 stdout 上打印字符串标头值的 JSON 对象。请参阅[脚本要求](/docs/zh-CN/monitoring-usage#script-requirements)。5124* 修复脚本使其在 30 秒内退出 0 并在 stdout 上打印字符串标头值的 JSON 对象。请参阅[脚本要求](/docs/zh-CN/monitoring-usage#script-requirements)。

4732* 如果您的组织通过[托管设置](/docs/zh-CN/managed-settings)部署脚本，请要求维护它们的人修复它。5125* 如果您的组织通过[托管设置](/docs/zh-CN/managed-settings)部署脚本，请要求维护它们的人修复它。

4733 5126

4734在[非交互模式](/docs/zh-CN/headless)中使用 `-p` 时，相同的失败在 stderr 上显示为 `otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error>`。5127在[非交互模式](/docs/zh-CN/headless)中使用 `-p`，相同的失败在 stderr 上显示为 `otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error>`。

4735 5128

4736<h3 id="headershelper-not-run">5129<h3 id="headershelper-not-run">

4737 headersHelper 未运行5130 headersHelper 未运行

4750**要做什么：**5143**要做什么：**

4751 5144

4752* 在消息命名的文件夹中运行 `claude`，接受信任对话框，然后再次运行您的 `-p` 或 SDK 命令5145* 在消息命名的文件夹中运行 `claude`，接受信任对话框，然后再次运行您的 `-p` 或 SDK 命令

4753* 自己在 `~/.claude.json` 中设置 `hasTrustDialogAccepted` 条目，使用消息打印的确切 `projects` 键5146* 在 `~/.claude.json` 中自己设置 `hasTrustDialogAccepted` 条目，使用消息打印的确切 `projects` 键

4754* 如果您在主目录中启动了会话，请从您已信任的项目目录工作。当您在主目录中接受信任对话框时，Claude Code 仅为当前会话保持该信任。5147* 如果您在主目录中启动了会话，请从您已信任的项目目录工作。当您在主目录中接受信任对话框时，Claude Code 仅为当前会话保持该信任。

4755 5148

4756<h3 id="malformed-tool-content-rule">5149<h3 id="malformed-tool-content-rule">

4757 格式错误的 Tool(content) 规则5150 格式错误的 Tool(content) 规则

4758</h3>5151</h3>

4759 5152

4760您的一个设置文件中的[权限规则](/docs/zh-CN/permissions#permission-rule-syntax)没有 `Tool` 或 `Tool(content)` 的形状，例如因为文本跟在右括号后或其中一个括号缺失。Claude Code 跳过该规则，并在交互式会话启动时在无效设置对话框中列出它，以及在 [`claude doctor`](/docs/zh-CN/debug-your-config#check-resolved-settings) 输出中：5153您的一个设置文件中的[权限规则](/docs/zh-CN/permissions#permission-rule-syntax)没有 `Tool` 或 `Tool(content)` 的形状，例如因为文本跟在右括号后或其中一个括号缺失。Claude Code 跳过规则，当交互式会话启动时在无效设置对话框中列出它，以及在 [`claude doctor`](/docs/zh-CN/debug-your-config#check-resolved-settings) 输出中：

4761 5154

4762```text theme={null}5155```text theme={null}

4763Invalid permission rule "Bash(ls) x" was skipped: Malformed Tool(content) rule. Rules take the form Tool or Tool(content) and must end at the closing ")"; parentheses inside the content are literal5156Invalid permission rule "Bash(ls) x" was skipped: Malformed Tool(content) rule. Rules take the form Tool or Tool(content) and must end at the closing ")"; parentheses inside the content are literal

4766**要做什么：**5159**要做什么：**

4767 5160

4768* 在消息列出的设置文件中，重写规则使其在其右括号处结束，例如用 `Bash(ls *)` 代替 `Bash(ls) x`5161* 在消息列出的设置文件中，重写规则使其在其右括号处结束，例如用 `Bash(ls *)` 代替 `Bash(ls) x`

4769* 将内容内的括号保留原样。它们是字面的，因此诸如 `Edit(./Finance (2024)/**)` 之类的规则在不转义的情况下是有效的5162* 将内容内的括号保留原样。它们是字面的，因此诸如 `Edit(./Finance (2024)/**)` 的规则在没有转义的情况下是有效的

4770 5163

4771在 v2.1.260 之前，Claude Code 将具有不匹配括号的规则报告为 `Mismatched parentheses`。5164在 v2.1.260 之前，Claude Code 将具有不匹配括号的规则报告为 `Mismatched parentheses`。

4772 5165

4773<h3 id="is-not-matched-by-file-permission-checks">5166<h3 id="is-not-matched-by-file-permission-checks">

4774 不被文件权限检查匹配5167 不匹配文件权限检查

4775</h3>5168</h3>

4776 5169

4777Claude Code 在您的[设置文件](/docs/zh-CN/settings#where-settings-live)、[托管设置](/docs/zh-CN/managed-settings)或 `--allowedTools`、`--disallowedTools` 或 `--settings` 标志值中找到了带有路径的 `Write`、`NotebookEdit`、`MultiEdit` 或 `Glob`[权限规则](/docs/zh-CN/permissions#read-and-edit)。它仅针对 `Edit` 和 `Read` 规则检查文件权限，因此它从不查询命名其他文件工具之一的路径规则。它保留规则并不改变其他任何内容；警告命名规则、其在括号中的源和要写入的替换：5170Claude Code 在您的[设置文件](/docs/zh-CN/settings#where-settings-live)、[托管设置](/docs/zh-CN/managed-settings)或 `--allowedTools`、`--disallowedTools` 或 `--settings` 标志值中找到了 `Write`、`NotebookEdit`、`MultiEdit` 或 `Glob` [权限规则](/docs/zh-CN/permissions#read-and-edit)，其中包含路径。它仅针对 `Edit` 和 `Read` 规则检查文件权限，因此它从不查询命名其他文件工具之一的路径规则。它保留规则并不改变其他任何内容；警告命名规则、其括号中的源和要写入的替换：

4778 5171

4779```text theme={null}5172```text theme={null}

4780Permission deny rule (.claude/settings.json): Write(docs/**) is not matched by file permission checks — only Edit(path) rules are. Use Edit(docs/**) instead (Edit rules cover all file-editing tools).5173Permission deny rule (.claude/settings.json): Write(docs/**) is not matched by file permission checks — only Edit(path) rules are. Use Edit(docs/**) instead (Edit rules cover all file-editing tools).

4784 5177

4785* 将 `Write(path)`、`NotebookEdit(path)` 和旧版 `MultiEdit(path)` 规则替换为 `Edit(path)`。`Edit` 规则涵盖所有文件编辑工具。5178* 将 `Write(path)`、`NotebookEdit(path)` 和旧版 `MultiEdit(path)` 规则替换为 `Edit(path)`。`Edit` 规则涵盖所有文件编辑工具。

4786* 除了在 `--allowedTools` 中，Claude Code 接受 `Glob` 规则而不警告，将 `Glob(path)` 规则替换为 `Read(path)`。5179* 除了在 `--allowedTools` 中，Claude Code 接受 `Glob` 规则而不警告，将 `Glob(path)` 规则替换为 `Read(path)`。

4787* 在警告在括号中命名的源处修复规则：设置文件路径，或 `--allowed-tools` 和 `--disallowed-tools` 的标志本身。不存在于磁盘上的 `claude-settings-<hash>.json` 路径代表内联 `--settings` 值。修复您传递给该标志的 JSON。5180* 在警告括号中命名的源处修复规则：设置文件路径，或 `--allowed-tools` 和 `--disallowed-tools` 的标志本身。不存在于磁盘上的 `claude-settings-<hash>.json` 路径代表内联 `--settings` 值。修复您传递给该标志的 JSON。

4788* 将裸工具名称规则（例如 `Write` 或 `Glob`）保留原样。Claude Code 在[工具级别](/docs/zh-CN/permissions#match-all-uses-of-a-tool)匹配它们，不对它们警告。5181* 将诸如 `Write` 或 `Glob` 的裸工具名称规则保留原样。Claude Code 在[工具级别](/docs/zh-CN/permissions#match-all-uses-of-a-tool)匹配它们，不对它们发出警告。

4789* 如果源读作 `managed policy settings`，将警告转发给维护您的托管设置的人，因为您无法自己清除它。5182* 如果源读取 `managed policy settings`，将警告转发给维护您的托管设置的人，因为您无法自己清除它。

4790 5183

4791在[后台会话](/docs/zh-CN/agent-view)中或使用 `--output-format json` 或 `stream-json` 时，Claude Code 将警告写入调试日志而不是 stderr，因此机器读取的输出保持干净。使用 `--debug` 运行以在 `~/.claude/debug/<session-id>.txt` 处捕获它。在 v2.1.210 之前，Claude Code 接受这些规则而不警告。5184在[后台会话](/docs/zh-CN/agent-view)中或使用 `--output-format json` 或 `stream-json`，Claude Code 将警告写入调试日志而不是 stderr，因此机器读取输出保持干净。使用 `--debug` 运行以在 `~/.claude/debug/<session-id>.txt` 处捕获它。在 v2.1.210 之前，Claude Code 接受这些规则而不警告。

4792 5185

4793<h3 id="has-a-wildcard-before-the-rest-of-the-command">5186<h3 id="has-a-wildcard-before-the-rest-of-the-command">

4794 在命令的其余部分之前有通配符5187 在命令的其余部分之前有通配符

4795</h3>5188</h3>

4796 5189

4797Claude Code 在您的[设置文件](/docs/zh-CN/settings#where-settings-live)、[托管设置](/docs/zh-CN/managed-settings)或 `--allowedTools` 或 `--settings` 标志值中找到了一个 `Bash` 允许规则，其 `*` 在确定它是哪个命令的后续单词之前，例如 `Bash(git * main)` 或 `Bash(git -C * status *)`。`*` 匹配任何文本，包括在该位置插入的选项：`Bash(git * main)` 也批准 `git -c core.fsmonitor=<script> diff main`，其中 `-c` 使 git 运行命令命名的程序。[通配符模式](/docs/zh-CN/permissions#wildcard-patterns)显示匹配规则。5190Claude Code 找到了一个 `Bash` 允许规则，其 `*` 在后来的单词之前，该单词确定它是哪个命令，例如 `Bash(git * main)` 或 `Bash(git -C * status *)`，在您的[设置文件](/docs/zh-CN/settings#where-settings-live)、[托管设置](/docs/zh-CN/managed-settings)或 `--allowedTools` 或 `--settings` 标志值中。`*` 匹配任何文本，包括在该位置插入的选项：`Bash(git * main)` 也批准 `git -c core.fsmonitor=<script> diff main`，其中 `-c` 使 git 运行命令命名的程序。[通配符模式](/docs/zh-CN/permissions#wildcard-patterns)显示匹配规则。

4798 5191

4799警告存在是为了让您可以缩小通配符比您打算的更宽的规则。Claude Code 保留规则并不改变它的匹配方式；警告命名规则及其在括号中的源：5192警告存在是为了让您缩小通配符比您打算的更宽的规则。Claude Code 保留规则并不改变它如何匹配；警告命名规则及其括号中的源：

4800 5193

4801```text theme={null}5194```text theme={null}

4802Permission allow rule (.claude/settings.json): Bash(git -C * status *) has a wildcard before the rest of the command, so it also matches any options inserted at that position and approves them without a prompt. For git, options such as -c and --exec-path can run arbitrary commands. Replace that * with the exact value you mean, or only use * after the subcommand (for example Bash(git status *)).5195Permission allow rule (.claude/settings.json): Bash(git -C * status *) has a wildcard before the rest of the command, so it also matches any options inserted at that position and approves them without a prompt. For git, options such as -c and --exec-path can run arbitrary commands. Replace that * with the exact value you mean, or only use * after the subcommand (for example Bash(git status *)).

4806 5199

4807* 将子命令前的 `*` 替换为您的确切值：用 `Bash(git checkout main)` 代替 `Bash(git * main)`。5200* 将子命令前的 `*` 替换为您的确切值：用 `Bash(git checkout main)` 代替 `Bash(git * main)`。

4808* 将每个 `*` 移到子命令后：用 `Bash(git status *)` 代替 `Bash(git -C * status *)`。为您想允许的每个子命令写一个规则。5201* 将每个 `*` 移到子命令后：用 `Bash(git status *)` 代替 `Bash(git -C * status *)`。为您想允许的每个子命令写一个规则。

4809* 在警告在括号中命名的源处修复规则：设置文件路径或 `--allowed-tools` 标志本身。不存在于磁盘上的 `claude-settings-<hash>.json` 路径代表内联 `--settings` 值。修复您传递给该标志的 JSON。5202* 在警告括号中命名的源处修复规则：设置文件路径，或 `--allowed-tools` 标志本身。不存在于磁盘上的 `claude-settings-<hash>.json` 路径代表内联 `--settings` 值。修复您传递给该标志的 JSON。

4810* 如果源读作 `managed policy settings`，将警告转发给维护您的托管设置的人，因为您无法自己清除它。5203* 如果源读取 `managed policy settings`，将警告转发给维护您的托管设置的人，因为您无法自己清除它。

4811 5204

4812Claude Code 不对具有相同形状的拒绝和询问规则警告：它拒绝或提示它们匹配的额外命令，而不是批准它们。它也不对子命令在第一个 `*` 之前的规则警告，例如 `Bash(git commit *)`，或规则中除了选项外没有其他单词跟在 `*` 后的规则，例如 `Bash(git *)`，或关于 `:*` 前缀规则，例如 `Bash(git:*)`。5205Claude Code 不对具有相同形状的拒绝和询问规则发出警告：它拒绝或提示它们匹配的额外命令，而不是批准它们。它也不对子命令在第一个 `*` 之前的规则发出警告，例如 `Bash(git commit *)`，或规则中除了选项之外没有其他单词跟在 `*` 后的规则，例如 `Bash(git *)`，或关于 `:*` 前缀规则的规则，例如 `Bash(git:*)`。

4813 5206

4814在[后台会话](/docs/zh-CN/agent-view)中或使用 `--output-format json` 或 `stream-json` 时，Claude Code 将警告写入调试日志而不是 stderr，因此机器读取的输出保持干净。使用 `--debug` 运行以在 `~/.claude/debug/<session-id>.txt` 处捕获它。在 v2.1.246 之前，Claude Code 接受这些规则而不警告。5207在[后台会话](/docs/zh-CN/agent-view)中或使用 `--output-format json` 或 `stream-json`，Claude Code 将警告写入调试日志而不是 stderr，因此机器读取输出保持干净。使用 `--debug` 运行以在 `~/.claude/debug/<session-id>.txt` 处捕获它。在 v2.1.246 之前，Claude Code 接受这些规则而不警告。

4815 5208

4816<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">5209<h3 id="crosssessioninbound-must-be-one-of-accept-hold-refuse">

4817 crossSessionInbound 必须是 accept、hold、refuse 之一5210 crossSessionInbound 必须是 accept、hold 或 refuse 之一

4818</h3>5211</h3>

4819 5212

4820设置文件将 [`crossSessionInbound`](/docs/zh-CN/settings-reference#crosssessioninbound) 设置为 Claude Code 不识别的值，例如拼写错误 `"reject"`。警告的第二句取决于哪个文件保存该值；在用户、项目、本地或 `--settings` 文件中，它读作：5213设置文件将 [`crossSessionInbound`](/docs/zh-CN/settings-reference#crosssessioninbound) 设置为 Claude Code 不识别的值，例如拼写错误 `"reject"`。警告的第二句取决于哪个文件保存该值；在用户、项目、本地或 `--settings` 文件中，它读取：

4821 5214

4822```text theme={null}5215```text theme={null}

4823"crossSessionInbound" must be one of "accept", "hold", "refuse"; received "reject". This value was ignored; while it is present, cross-session messages are held for your approval instead of being delivered. Set it to one of the values above.5216"crossSessionInbound" must be one of "accept", "hold", "refuse"; received "reject". This value was ignored; while it is present, cross-session messages are held for your approval instead of being delivered. Set it to one of the values above.

4842CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced for <model>, so this session can grow past it. To enforce it, set CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 (or the autoCompactWindow setting).5235CLAUDE_CODE_DISABLE_1M_CONTEXT is set, but the 200K limit isn't enforced for <model>, so this session can grow past it. To enforce it, set CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000 (or the autoCompactWindow setting).

4843```5236```

4844 5237

4845Claude Code 为它识别为具有本地 1M 窗口的每个模型自己强制执行 200K 限制，对于它不识别的模型 ID，它在它假设的窗口处压缩。当其他配置击败该强制执行时出现警告：5238Claude Code 为它识别为具有本机 1M 窗口的每个模型自己强制执行 200K 限制，对于它不识别的模型 ID，它在它假设的窗口处压缩。当其他配置击败该强制执行时出现警告：

4846 5239

4847* 模型 ID 不是 Claude Code 识别的，例如[LLM 网关](/docs/zh-CN/llm-gateway)别名，并且您设置了 [`CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1`](/docs/zh-CN/env-vars) 或使用 [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](/docs/zh-CN/env-vars) 将假设的窗口提高到 200K 以上。在这种情况下，消息也提供 `or update to a Claude Code version that recognizes <model>` 作为补救。5240* 模型 ID 不是 Claude Code 识别的，例如[LLM 网关](/docs/zh-CN/llm-gateway)别名，并且您设置了 [`CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1`](/docs/zh-CN/env-vars) 或使用 [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](/docs/zh-CN/env-vars) 将假设的窗口提高到 200K 以上。在这种情况下，消息也提供 `or update to a Claude Code version that recognizes <model>` 作为补救。

4848* 通过 [`ANTHROPIC_BETAS`](/docs/zh-CN/env-vars) 或 [`--betas`](/docs/zh-CN/cli-reference#cli-flags) 标志请求的 `context-1m` 测试版仍然在接受该测试版的模型上向 API 请求 1M 窗口，而没有任何东西在 200K 处压缩会话5241* 通过 [`ANTHROPIC_BETAS`](/docs/zh-CN/env-vars) 或 [`--betas`](/docs/zh-CN/cli-reference#cli-flags) 标志请求的 `context-1m` 测试版仍然要求 API 在接受该测试版的模型上使用 1M 窗口，而没有任何东西在 200K 处压缩会话

4849 5242

4850**要做什么：**5243**要做什么：**

4851 5244

4852* 设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/zh-CN/env-vars) 或 [`autoCompactWindow`](/docs/zh-CN/settings-reference#autocompactwindow) 设置为 `200000`，以便自动压缩在 200K 边界处压缩5245* 设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](/docs/zh-CN/env-vars)，或 [`autoCompactWindow`](/docs/zh-CN/settings-reference#autocompactwindow) 设置为 `200000`，以便自动压缩在 200K 边界处压缩

4853* 如果消息命名此版本不识别的模型 ID，运行 `claude update`。识别 ID 为 1M 上下文模型的版本在没有进一步配置的情况下强制执行限制。5246* 如果消息命名此版本不识别的模型 ID，运行 `claude update`。识别 ID 为 1M 上下文模型的版本在没有进一步配置的情况下强制执行限制。

4854* 如果您希望会话使用模型的完整窗口，请取消设置 `CLAUDE_CODE_DISABLE_1M_CONTEXT`；警告仅报告 200K 限制未被强制执行5247* 如果您希望会话使用模型的完整窗口，请取消设置 `CLAUDE_CODE_DISABLE_1M_CONTEXT`；警告仅报告 200K 限制未被强制执行

4855 5248

4856在[后台会话](/docs/zh-CN/agent-view)中或使用 `--output-format json` 或 `stream-json` 时，Claude Code 将警告写入调试日志而不是 stderr。5249在[后台会话](/docs/zh-CN/agent-view)中或使用 `--output-format json` 或 `stream-json`，Claude Code 将警告写入调试日志而不是 stderr。

4857 5250

4858<h3 id="unrecognized-model-id-on-a-request">5251<h3 id="unrecognized-model-id-on-a-request">

4859 请求上无法识别的模型 ID5252 请求上无法识别的模型 ID

4865[claude-code:unrecognized_model] {"model":"my-proxy-model","query_source":"sdk"}5258[claude-code:unrecognized_model] {"model":"my-proxy-model","query_source":"sdk"}

4866```5259```

4867 5260

4868在读取 stderr 的脚本或工具中，匹配 `[claude-code:unrecognized_model]` 前缀。在前缀和一个空格之后，Claude Code 写入一行 JSON 对象。Claude Code 可能在后续版本中向其添加字段，因此忽略您不期望的任何字段。它至少写入这两个：5261在读取 stderr 的脚本或工具中，匹配 `[claude-code:unrecognized_model]` 前缀。在前缀和一个空格之后，Claude Code 写入一行 JSON 对象。Claude Code 可以在更高版本中向其添加字段，因此忽略您不期望的任何字段。它至少写入这两个：

4869 5262

4870* `model`：您配置的模型字符串5263* `model`：您配置的模型字符串

4871* `query_source`：使用模型的请求路径。Claude Code 为 `-p` 运行报告 `sdk`，为子代理报告以 `agent:` 开头的值。5264* `query_source`：使用模型的请求路径。Claude Code 为 `-p` 运行报告 `sdk`，为以 `agent:` 开头的值报告子代理。

4872 5265

4873Claude Code 根据您运行它的方式将行写入两个位置之一：5266Claude Code 根据您运行它的方式将行写入两个位置之一：

4874 5267

4875* 在[非交互模式](/docs/zh-CN/headless)中使用 `-p` 时，Claude Code 在每个 `--output-format` 下将其写入 stderr，因此您可以解析 stdout 而不过滤该行5268* 在[非交互模式](/docs/zh-CN/headless)中使用 `-p`，Claude Code 在每个 `--output-format` 下将其写入 stderr，因此您可以解析 stdout 而不过滤该行

4876* 在交互式会话或[后台会话](/docs/zh-CN/agent-view)中，Claude Code 将其写入调试日志；使用 `--debug` 运行以在 `~/.claude/debug/<session-id>.txt` 处捕获它5269* 在交互式会话或[后台会话](/docs/zh-CN/agent-view)中，Claude Code 将其写入调试日志；使用 `--debug` 运行以在 `~/.claude/debug/<session-id>.txt` 处捕获它

4877 5270

4878Claude Code 每个模型字符串每个进程写入该行一次。它为每个进一步的无法识别的 ID 写入单独的行，例如[子代理](/docs/zh-CN/sub-agents#choose-a-model)或[后台功能](/docs/zh-CN/costs#background-token-usage)使用的 ID。5271Claude Code 每个模型字符串每个进程写入该行一次。它为每个进一步的无法识别的 ID 写入单独的行，例如[子代理](/docs/zh-CN/sub-agents#choose-a-model)或[后台功能](/docs/zh-CN/costs#background-token-usage)使用的 ID。

4881 5274

4882**要做什么：**5275**要做什么：**

4883 5276

4884* 如果您故意设置了 ID，例如[LLM 网关](/docs/zh-CN/llm-gateway)别名，请向您的[设置文件](/docs/zh-CN/settings#where-settings-live)添加 [`modelOverrides`](/docs/zh-CN/model-config#override-model-ids-per-version) 条目，以 ID 作为其值。使用 Anthropic 模型 ID 作为键，而不是家族别名，例如 `opus`。对于示例行中的 `my-proxy-model`，添加此条目：5277* 如果您故意设置了 ID，例如[LLM 网关](/docs/zh-CN/llm-gateway)别名，请在您的[设置文件](/docs/zh-CN/settings#where-settings-live)中添加 [`modelOverrides`](/docs/zh-CN/model-config#override-model-ids-per-version) 条目，其中 ID 作为其值。使用 Anthropic 模型 ID 作为键，而不是系列别名，例如 `opus`。对于示例行中的 `my-proxy-model`，添加此条目：

4885 5278

4886 ```json theme={null}5279 ```json theme={null}

4887 {5280 {

4895 5288

4896* 如果 ID 命名比您的 Claude Code 版本更新的模型，运行 `claude update`5289* 如果 ID 命名比您的 Claude Code 版本更新的模型，运行 `claude update`

4897 5290

4898* 如果 ID 是拼写错误，在您可以[设置模型](/docs/zh-CN/model-config#setting-your-model)或[别名变量](/docs/zh-CN/model-config#environment-variables)的地方之一修复它。如果 `query_source` 以 `agent:` 开头，改为在您设置[子代理模型](/docs/zh-CN/sub-agents#choose-a-model)的地方修复它。5291* 如果 ID 是拼写错误，在您可以设置模型的[位置](/docs/zh-CN/model-config#setting-your-model)或[别名变量](/docs/zh-CN/model-config#environment-variables)中修复它。如果 `query_source` 以 `agent:` 开头，改为在您设置[子代理模型](/docs/zh-CN/sub-agents#choose-a-model)的地方修复它。

4899 5292

4900在 v2.1.233 之前，Claude Code 在为它不识别的模型 ID 发送请求时不写入行。5293在 v2.1.233 之前，Claude Code 在为它不识别的模型 ID 发送请求时不写入行。

4901 5294

4905 5298

4906`claude doctor` 在其诊断中打印此警告，`/status` 列出相同的行。当[沙箱](/docs/zh-CN/sandboxing)在文件系统隔离打开的情况下启用时，它在 Linux 和 WSL2 上出现。5299`claude doctor` 在其诊断中打印此警告，`/status` 列出相同的行。当[沙箱](/docs/zh-CN/sandboxing)在文件系统隔离打开的情况下启用时，它在 Linux 和 WSL2 上出现。

4907 5300

4908当沙箱命令运行时，沙箱通过在那里创建 0 字节只读占位符来保持对尚不存在的文件的写入拒绝，并在之后删除它。在该清理运行前被杀死的会话（例如通过 SIGKILL）留下占位符。后续会话在每次启动时再次只读绑定它们，因此设置写入（例如保存"是，不要再问"）在其中一个所在的地方失败。5301当沙箱命令运行时，沙箱通过在那里创建 0 字节只读占位符来保持对尚不存在的文件的写入拒绝，并在之后删除它。在该清理运行前被杀死的会话，例如通过 SIGKILL，会留下占位符。后来的会话在每次启动时再次只读绑定它们，因此诸如保存"是，不要再问"之类的设置写入失败。

4909 5302

4910```text theme={null}5303```text theme={null}

4911- Stale sandbox mask files left by a killed session: /home/you/project/.claude/settings.local.json5304- Stale sandbox mask files left by a killed session: /home/you/project/.claude/settings.local.json

4915**要做什么：**5308**要做什么：**

4916 5309

4917* 退出在该项目中运行的任何其他 Claude Code 会话，然后使用 `rm` 删除每个列出的文件。警告列出最多三个文件并计数其余的，因此在删除后重新运行 `claude doctor` 直到警告不再出现。另一个会话的沙箱仍在使用的占位符是该会话写入保护的活跃部分5310* 退出在该项目中运行的任何其他 Claude Code 会话，然后使用 `rm` 删除每个列出的文件。警告列出最多三个文件并计数其余的，因此在删除后重新运行 `claude doctor` 直到警告不再出现。另一个会话的沙箱仍在使用的占位符是该会话写入保护的活跃部分

4918* 如果您使用"是，不要再问"保存的权限选择没有坚持，在删除占位符后再次保存它5311* 如果您使用"是，不要再问"保存的权限选择没有坚持，请在删除占位符后再次保存

4919 5312

4920在 v2.1.257 之前，`claude doctor` 没有标记这些文件；早期版本在会话被杀死时留下相同的占位符。5313在 v2.1.257 之前，`claude doctor` 没有标记这些文件；较早的版本在会话被杀死时留下相同的占位符。

4921 5314

4922<h2 id="responses-seem-lower-quality-than-usual">5315<h2 id="responses-seem-lower-quality-than-usual">

4923 回复质量似乎低于预期5316 回复质量似乎低于预期

4927 5320

4928* 配置的 [`--fallback-model`](/docs/zh-CN/cli-reference#cli-flags) 在可用性错误后接管该轮，并在记录中显示通知5321* 配置的 [`--fallback-model`](/docs/zh-CN/cli-reference#cli-flags) 在可用性错误后接管该轮，并在记录中显示通知

4929* Amazon Bedrock 或 Google Cloud 的 Agent Platform 启动检查发现你的默认模型不可用5322* Amazon Bedrock 或 Google Cloud 的 Agent Platform 启动检查发现你的默认模型不可用

4930* [自动模型备用](/docs/zh-CN/model-config#automatic-model-fallback) 在 Fable 5.1、Fable 5、Opus 5.5 和 Opus 5 上，当该类别有备用模型时，将会话移动到标记类别的备用模型，并在记录中显示通知5323* [自动模型备用](/docs/zh-CN/model-config#automatic-model-fallback) 在 Fable 5.1、Fable 5、Opus 5.5、Sonnet 5.5 和 Opus 5 上，当该类别有备用模型时，将会话移动到标记类别的备用模型，并在记录中显示通知

4931 5324

4932下面的模型选择检查捕获第二和第三种情况；第一种情况显示为记录通知而不是 `/model` 更改。[模型配置](/docs/zh-CN/model-config) 解释了每个备用何时适用。5325下面的模型选择检查捕获第二和第三种情况；第一种情况显示为记录通知而不是 `/model` 更改。[模型配置](/docs/zh-CN/model-config) 解释了每个备用何时适用。

4933 5326

feature-availability.md +2 −2

Details

219</table>219</table>

220 220

221<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> 在 Google Cloud's Agent Platform 上，web search 适用于 Claude 4 及更高版本的模型。<br />221<span id="fn1" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>1</sup> 在 Google Cloud's Agent Platform 上，web search 适用于 Claude 4 及更高版本的模型。<br />

222<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> 在这些提供商上，auto mode 仅支持 Claude Sonnet 5、Opus 4.7 或更高版本以及 Fable 模型。请参阅 [Auto mode 配置](/docs/zh-CN/auto-mode-config)。这些提供商上的内置起始权限模式是 Manual。请参阅[会话启动时的模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)。在 v2.1.158 到 v2.1.206 中，这些提供商上的 auto mode 还需要设置 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`；v2.1.207 移除了该要求。<br />222<span id="fn2" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>2</sup> 在这些提供商上，auto mode 仅支持 Claude Sonnet 5、Opus 4.7 或更高版本以及 Fable 模型。请参阅 [Auto mode 配置](/docs/zh-CN/auto-mode-config)。有关会话在这些提供商上启动时所处的权限模式，请参阅[会话启动时的模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)。在 v2.1.158 到 v2.1.206 中，这些提供商上的 auto mode 还需要设置 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`；v2.1.207 移除了该要求。<br />

223<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> 受您与云提供商的协议约束。<br />223<span id="fn3" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>3</sup> 受您与云提供商的协议约束。<br />

224<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> 仅限仪表板和 API。[贡献指标](/docs/zh-CN/analytics#enable-contribution-metrics)需要 claude.ai Team 或 Enterprise 组织。<br />224<span id="fn4" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>4</sup> 仅限仪表板和 API。[贡献指标](/docs/zh-CN/analytics#enable-contribution-metrics)需要 claude.ai Team 或 Enterprise 组织。<br />

225<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> 在 macOS 和 Linux 上需要 Claude Code v2.1.224 或更高版本，包括 WSL 2 内的 Linux。在原生 Windows 上，需要 Claude Code v2.1.234 或更高版本。使用 API 密钥身份验证时，消息传递仅限同一台机器。在 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 和 Microsoft Foundry 上，消息传递仅限同一台机器，需要 Claude Code v2.1.248 或更高版本。Claude 只能从连接到 [Remote Control](/docs/zh-CN/remote-control) 的会话中找到您的 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 会话和其他机器上的会话。要连接，您需要 claude.ai 登录和其他 [Remote Control 要求](/docs/zh-CN/remote-control#requirements)。请参阅[在其他机器上发送消息](/docs/zh-CN/cross-session-messaging#message-sessions-on-other-machines)。225<span id="fn5" style={{display: 'block', position: 'relative', top: '-120px'}} /><sup>5</sup> 在 macOS 和 Linux 上需要 Claude Code v2.1.224 或更高版本，包括 WSL 2 内的 Linux。在原生 Windows 上，需要 Claude Code v2.1.234 或更高版本。使用 API 密钥身份验证时，消息传递仅限同一台机器。在 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 和 Microsoft Foundry 上，消息传递仅限同一台机器，需要 Claude Code v2.1.248 或更高版本。Claude 只能从连接到 [Remote Control](/docs/zh-CN/remote-control) 的会话中找到您的 [cloud sessions](/docs/zh-CN/claude-code-on-the-web) 和其他机器上的会话。要连接，您需要 claude.ai 登录和其他 [Remote Control 要求](/docs/zh-CN/remote-control#requirements)。请参阅[在其他机器上发送消息](/docs/zh-CN/cross-session-messaging#message-sessions-on-other-machines)。

226 226

227<Note>227<Note>

228 如果您通过 [LLM gateway](/docs/zh-CN/llm-gateway) 进行身份验证，功能可用性与网关转发到的基础提供商相匹配，除了 Claude Code 本身关闭的功能。每当 `ANTHROPIC_BASE_URL` 指向 `api.anthropic.com` 以外的主机时，Claude Code 会关闭功能，例如 [Remote Control](/docs/zh-CN/remote-control#requirements) 和 [server-managed settings](/docs/zh-CN/server-managed-settings#platform-availability)，无论网关转发什么。某些仅限 Anthropic 的功能，例如 [Advisor](/docs/zh-CN/advisor)，仅在网关将请求完整转发到 Anthropic API 时才有效。228 如果您通过 [LLM gateway](/docs/zh-CN/llm-gateway) 进行身份验证，功能可用性与网关转发到的基础提供商相匹配，除了 Claude Code 本身关闭的功能。每当 `ANTHROPIC_BASE_URL` 指向 `api.anthropic.com` 以外的主机时，Claude Code 会关闭功能，例如 [Remote Control](/docs/zh-CN/remote-control#requirements) 和 [server-managed settings](/docs/zh-CN/server-managed-settings#platform-availability)，无论网关转发什么。某些仅限 Anthropic 的功能，例如 [Advisor](/docs/zh-CN/advisor)，仅在网关将请求完整转发到 Anthropic API 时才有效。

fullscreen.md +2 −0

Details

104* **在多选菜单中单击选项**以切换它，然后单击提交按钮以确认您的选择。单击自由文本行（例如多选题中的 `Other` 行）会聚焦其输入字段，以便您可以输入答案。需要 Claude Code v2.1.208 或更高版本。104* **在多选菜单中单击选项**以切换它，然后单击提交按钮以确认您的选择。单击自由文本行（例如多选题中的 `Other` 行）会聚焦其输入字段，以便您可以输入答案。需要 Claude Code v2.1.208 或更高版本。

105* **单击 `/config` 面板中的设置值**以更改它，并使用鼠标滚轮滚动设置列表。需要 Claude Code v2.1.271 或更高版本。105* **单击 `/config` 面板中的设置值**以更改它，并使用鼠标滚轮滚动设置列表。需要 Claude Code v2.1.271 或更高版本。

106* **用鼠标滚轮滚动选择或多选菜单**当它显示的选项多于一次显示的选项时，例如短终端窗口中的 `/model` 列表。当指针悬停在其选项上时，滚轮会滚动列表。需要 Claude Code v2.1.280 或更高版本。106* **用鼠标滚轮滚动选择或多选菜单**当它显示的选项多于一次显示的选项时，例如短终端窗口中的 `/model` 列表。当指针悬停在其选项上时，滚轮会滚动列表。需要 Claude Code v2.1.280 或更高版本。

107* **用其滚动条滚动溢出的列表。** 在列表面板（例如 `/skills`、`/mcp` 和 `/plugin` 的已安装列表）中，当指针悬停在列表上时，滚动条会出现在有超过适应行数的列表旁边。单击轨道以跳转到该点，或拖动滑块。需要 Claude Code v2.1.281 或更高版本。

107* **单击折叠的工具结果**以展开它并查看完整输出。再次单击以折叠。工具调用及其结果一起展开。只有有更多内容要显示的消息才可点击。108* **单击折叠的工具结果**以展开它并查看完整输出。再次单击以折叠。工具调用及其结果一起展开。只有有更多内容要显示的消息才可点击。

108 * 单击也会展开 `!` shell 命令的输出，无论是较旧的截断结果还是命令运行时的实时进度行。需要 Claude Code v2.1.257 或更高版本。109 * 单击也会展开 `!` shell 命令的输出，无论是较旧的截断结果还是命令运行时的实时进度行。需要 Claude Code v2.1.257 或更高版本。

110 * 单击也会展开一条暗淡的 `Message from @<sender>` 行，当发送者是[队友](/docs/zh-CN/agent-teams)或在您的会话中运行的另一个代理时。来自[您的其他会话之一](/docs/zh-CN/cross-session-messaging#what-a-message-looks-like)的消息行也会显示消息的第一行，并且不可点击，因此按 `Ctrl+o` 来阅读那一条。

109* **在 macOS 上按住 `Cmd`，或在 Linux 和 Windows 上按住 `Ctrl`，然后单击 URL 或文件路径**以打开它。纯 `http://` 和 `https://` URL 在您的浏览器中打开，工具输出中的文件路径（如 Edit 或 Write 后打印的路径）在您的默认应用程序中打开。不带修饰符的纯单击不会打开链接，与本机终端行为相匹配。111* **在 macOS 上按住 `Cmd`，或在 Linux 和 Windows 上按住 `Ctrl`，然后单击 URL 或文件路径**以打开它。纯 `http://` 和 `https://` URL 在您的浏览器中打开，工具输出中的文件路径（如 Edit 或 Write 后打印的路径）在您的默认应用程序中打开。不带修饰符的纯单击不会打开链接，与本机终端行为相匹配。

110 * Claude Code 将网络 (UNC) 路径（例如 `\\server\share\file.ts`）呈现为纯文本，没有链接，因为打开网络路径可能会将您的 Windows 凭据发送到它命名的主机。112 * Claude Code 将网络 (UNC) 路径（例如 `\\server\share\file.ts`）呈现为纯文本，没有链接，因为打开网络路径可能会将您的 Windows 凭据发送到它命名的主机。

111 * 某些 macOS 终端会将 `Cmd`+单击转发给正在运行的应用程序，而不是自己打开链接，终端鼠标协议无法编码 `Cmd` 键，因此 Claude Code 收到纯单击。在 Ghostty 中，以及在 macOS 上的 Warp 中，Claude Code 检测到这一点，并让纯单击链接打开它，按住 `Cmd` 仍然有效。113 * 某些 macOS 终端会将 `Cmd`+单击转发给正在运行的应用程序，而不是自己打开链接，终端鼠标协议无法编码 `Cmd` 键，因此 Claude Code 收到纯单击。在 Ghostty 中，以及在 macOS 上的 Warp 中，Claude Code 检测到这一点，并让纯单击链接打开它，按住 `Cmd` 仍然有效。

github-enterprise-server.md +1 −1

Details

252 会话启动失败，显示 `Unable to get organization UUID`252 会话启动失败，显示 `Unable to get organization UUID`

253</h3>253</h3>

254 254

255云会话需要 Team 或 Enterprise 组织。使用 `/login` 和您的组织账户登录。如果您改用 API 密钥进行身份验证，云会话会更早失败，并显示一条消息要求您运行 `/login`。255Claude Code 无法从您的凭据中读取 claude.ai 组织。使用 `/login` 登录，使用您的 Team 或 Enterprise 组织中的账户，因为 GitHub Enterprise Server 支持仅限于这些计划。有关原因和此状态产生的其他消息，请参阅 [Unable to get organization UUID](/docs/zh-CN/claude-code-on-the-web#unable-to-get-organization-uuid)。

256 256

257<h2 id="related-resources">257<h2 id="related-resources">

258 相关资源258 相关资源

glossary.md +28 −1

Details

72 Auto mode72 Auto mode

73</h3>73</h3>

74 74

75一种[权限模式](#permission-mode)，其中单独的分类器模型审查操作而不是您，因此 Claude Code 可以在不询问您的情况下运行大多数操作。Claude Code 仍然会在您的显式 ask 规则匹配的操作之前询问您。在 Pro、Max 和 Team 计划上，auto mode 是交互式终端和 VS Code 会话的[内置起始权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)。分类器阻止范围升级、不受信任的基础设施和[提示注入](#prompt-injection)。工具结果从它看到的内容中被剥离，因此文件或网页中的恶意内容无法直接操纵它。75一种[权限模式](#permission-mode)，其中单独的分类器模型审查操作而不是您，因此 Claude Code 可以在不询问您的情况下运行大多数操作。Claude Code 仍然会在您的显式 ask 规则匹配的操作之前询问您。在 Claude Code v2.1.283 或更高版本中，auto mode 是交互式终端和 VS Code 会话的[内置起始权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)，在早期版本中仅在 Pro、Max 和 Team 计划上可用。分类器阻止范围升级、不受信任的基础设施和[提示注入](#prompt-injection)。工具结果从它看到的内容中被剥离，因此文件或网页中的恶意内容无法直接操纵它。

76 76

77了解更多：[使用 auto mode 消除提示](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)77了解更多：[使用 auto mode 消除提示](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)

78 78

428 428

429了解更多：[平台和集成](/docs/zh-CN/platforms)429了解更多：[平台和集成](/docs/zh-CN/platforms)

430 430

431<h3 id="system-prompt">

432 System prompt

433</h3>

434

435Claude Code 在每个请求之前发送给您的对话的指令，涵盖 Claude 如何使用工具、安全行为和格式化响应。您可以使用 `--append-system-prompt` 添加到系统提示或使用 `--system-prompt` 替换它。系统提示是 [prompt cache](/docs/zh-CN/prompt-caching#how-the-cache-is-organized) 的第一层。

436

437您的 [CLAUDE.md](#claude-md) 文件和您的 [output style](#output-style) 的指令不是系统提示的一部分。Claude Code 在对话中将它们作为 [system reminders](#system-reminder) 传递。

438

439了解更多：[System prompt flags](/docs/zh-CN/cli-reference#system-prompt-flags)

440

441<h3 id="system-reminder">

442 System reminder

443</h3>

444

445Claude Code 作为 [harness](#agentic-harness) 添加到对话中的消息，为 Claude 提供上下文。您不会自己发送系统提醒。Claude Code 在会话运行时插入它们，例如当会话启动时、当 hook 返回文本时或当文件在磁盘上更改时。Claude 与您的消息一起读取它们。以下所有内容都作为系统提醒到达 Claude：

446

447* 您的 [CLAUDE.md](#claude-md) 文件

448* 您的 [output style](#output-style) 的指令

449* [hook](#hook) 作为 `additionalContext` 返回的文本

450* 可用 [skills](#skill) 的列表

451* Claude 之前读取的文件已在磁盘上更改的注记

452* 提交和拉取请求的归属行

453

454在记录的 API 请求中，系统提醒出现在用户消息内的 `<system-reminder>` 标签中，或在某些模型上作为具有 `system` 角色的单独消息。

455

456了解更多：[Claude Code 在系统提示之外添加的上下文](/docs/zh-CN/agent-sdk/modifying-system-prompts#context-claude-code-adds-outside-the-system-prompt)

457

431<h2 id="t">458<h2 id="t">

432 T459 T

433</h2>460</h2>

goal.md +1 −1

Details

155 155

156如果一个回合因为一个在你修复之前不会清除的错误而失败，Claude Code 会清除目标并打印一个警告，说明原因。警告以 `Goal cleared after an unrecoverable error` 开头，以 `Run /goal again to continue` 结尾。修复原因，然后使用 `/goal <condition>` [再次设置目标](#set-a-goal)。四种失败会清除目标：156如果一个回合因为一个在你修复之前不会清除的错误而失败，Claude Code 会清除目标并打印一个警告，说明原因。警告以 `Goal cleared after an unrecoverable error` 开头，以 `Run /goal again to continue` 结尾。修复原因，然后使用 `/goal <condition>` [再次设置目标](#set-a-goal)。四种失败会清除目标：

157 157

158* 身份验证失败，当 Claude Code 管理自己的凭证时。当主机为你管理凭证时，例如桌面应用、VS Code 扩展或[云会话](/docs/zh-CN/claude-code-on-the-web)，Claude Code 会保持目标活跃，因为主机会自动恢复访问权限。158* 身份验证失败，当 Claude Code 管理自己的凭证时。当主机为你管理凭证时，例如桌面应用或[云会话](/docs/zh-CN/claude-code-on-the-web)，Claude Code 会保持目标活跃，因为主机会自动恢复访问权限。

159* 信用余额耗尽159* 信用余额耗尽

160* 一个[自动压缩](/docs/zh-CN/model-config#set-the-auto-compact-window)无法清除的上下文溢出160* 一个[自动压缩](/docs/zh-CN/model-config#set-the-auto-compact-window)无法清除的上下文溢出

161* 一个不可用的模型161* 一个不可用的模型

headless.md +26 −18

Details

20 基本用法20 基本用法

21</h2>21</h2>

22 22

23将 `-p`（或 `--print`）标志添加到任何 `claude` 命令以非交互方式运行它。并非所有 [CLI 选项](/docs/zh-CN/cli-reference) 都与 `-p` 结合使用。Claude Code 拒绝 `--bg`，并在有任务描述时拒绝 `--cloud`，会出现命名冲突的错误；`--cloud` 与会话 ID 和 `-p` 结合时，会 [将消息排队到该云会话](/docs/zh-CN/claude-code-on-the-web#send-follow-ups-from-the-cli) 并退出。您经常会与 `-p` 结合使用的选项包括：23在任何 `claude` 命令中添加 `-p`（或 `--print`）标志以非交互方式运行它。并非每个 [CLI 选项](/docs/zh-CN/cli-reference) 都与 `-p` 兼容。Claude Code 拒绝 `--bg`，并在任务描述中拒绝 `--cloud`，会报错说明冲突；`--cloud` 与会话 ID 和 `-p` 一起使用时，会 [将消息排队到该云会话](/docs/zh-CN/claude-code-on-the-web#send-follow-ups-from-the-cli) 并退出。你通常会与 `-p` 结合使用的选项包括：

24 24

25* `--continue` 用于 [继续对话](#continue-conversations)25* `--continue` 用于 [继续对话](#continue-conversations)

26* `--allowedTools` 用于 [自动批准工具](#auto-approve-tools)26* `--allowedTools` 用于 [自动批准工具](#auto-approve-tools)

27* `--output-format` 用于 [获取结构化输出](#get-structured-output)27* `--output-format` 用于 [获取结构化输出](#get-structured-output)

28 28

~~29此示例询问 Claude 关于您的代码库的问题并打印响应：~~29此示例向 Claude 询问有关你的代码库的问题并打印响应：

30 30

31```bash theme={null}31```bash theme={null}

32claude -p "What does the auth module do?"32claude -p "What does the auth module do?"

33```33```

34 34

35Claude Code 在成功时以代码 0 退出，在运行失败时以非零代码退出，因此您的脚本可以根据退出状态进行分支。如果您传递无效标志，Claude Code 会在运行开始前向 stderr 报告错误。当运行内部发生故障时，例如缺少身份验证，Claude Code 会将故障作为结果打印到 stdout。35Claude Code 在成功时以代码 0 退出，在运行失败时以非零代码退出，因此你的脚本可以根据退出状态进行分支。如果你传递无效标志，Claude Code 会在运行开始前向 stderr 报告错误。当运行内部发生故障（例如缺少身份验证）时，Claude Code 会将故障作为结果打印到 stdout。

36 36

37<h3 id="start-faster-with-bare-mode">37<h3 id="start-faster-with-bare-mode">

38 使用裸模式更快启动38 使用裸模式更快启动

39</h3>39</h3>

40 40

41添加 `--bare` 以通过跳过 hooks、skills、自定义命令、[subagents](/docs/zh-CN/sub-agents)、installed plugins、MCP 服务器、auto memory 和 CLAUDE.md 的自动发现来减少启动时间。没有它，`claude -p` 会加载交互式会话相同的 [上下文](/docs/zh-CN/how-claude-code-works#the-context-window)，包括在工作目录或 `~/.claude` 中配置的任何内容。41添加 `--bare` 以通过跳过 hooks、skills、自定义命令、[subagents](/docs/zh-CN/sub-agents)、已安装的插件、MCP 服务器、自动内存和 CLAUDE.md 的自动发现来减少启动时间。没有它，`claude -p` 会加载交互式会话相同的 [context](/docs/zh-CN/how-claude-code-works#the-context-window)，包括在工作目录或 `~/.claude` 中配置的任何内容。

42 42

43裸模式对于 CI 和脚本很有用，您需要在每台机器上获得相同的结果。队友的 `~/.claude` 中的 hook 或项目的 `.mcp.json` 中的 MCP 服务器不会运行，因为裸模式从不读取它们。您使用 `--add-dir` 命名的目录是部分例外：裸模式从其 `.claude/skills/` 文件夹加载 skills，但仍然跳过其 `.claude/commands/` 和 `.claude/agents/` 文件夹。[来自其他目录的 Skills](/docs/zh-CN/skills#skills-from-additional-directories) 涵盖了加载和不加载的内容。43裸模式对于 CI 和脚本很有用，你需要在每台机器上获得相同的结果。队友的 `~/.claude` 中的 hook 或项目的 `.mcp.json` 中的 MCP 服务器不会运行，因为裸模式永远不会读取它们。你用 `--add-dir` 命名的目录是一个部分例外：裸模式从其 `.claude/skills/` 文件夹加载 skills，但仍然跳过其 `.claude/commands/` 和 `.claude/agents/` 文件夹。[来自其他目录的 Skills](/docs/zh-CN/skills#skills-from-additional-directories) 涵盖了加载和不加载的内容。

44 44

45没有 `--bare`，`-p` 会话会运行项目的 `.claude/settings.json` 中的 hooks 并连接其 `.mcp.json` 中的服务器，即使在您从未信任的文件夹中也是如此。`-p` 会话不显示工作区信任对话框和每个服务器的批准提示。[在您信任文件夹之前运行的内容](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 涵盖了 `-p` 下每种存储库内容以及如何将其排除在外。45没有 `--bare`，`-p` 会话会运行项目的 `.claude/settings.json` 中的 hooks 并连接其 `.mcp.json` 中的服务器，即使在你从未信任的文件夹中也是如此。`-p` 会话不显示工作区信任对话框和每个服务器的批准提示。[在你信任文件夹之前运行的内容](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 涵盖了 `-p` 下每种类型的存储库内容以及如何将其排除在外。

46 46

47此示例在裸模式下运行一次性摘要任务，并预先批准 Read 工具，以便调用完成而无需权限提示。在运行之前设置 `ANTHROPIC_API_KEY`，因为裸模式不使用您的订阅登录：47此示例在裸模式下运行一次性摘要任务，并预先批准 Read 工具，以便调用完成而无需权限提示。运行前设置 `ANTHROPIC_API_KEY`，因为裸模式不使用你的订阅登录：

48 48

49```bash theme={null}49```bash theme={null}

50claude --bare -p "Summarize README.md" --allowedTools "Read"50claude --bare -p "Summarize README.md" --allowedTools "Read"

51```51```

52 52

53在裸模式下，Claude Code 从不读取 OAuth 凭证或系统钥匙链。对于 Anthropic API，在环境中设置 `ANTHROPIC_API_KEY`，使用在 [Claude Console](https://platform.claude.com) 中创建的密钥，或在 `--settings` JSON 中提供 `apiKeyHelper`。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 继续照常读取其自己的提供商凭证。53在裸模式下，Claude Code 永远不会读取 OAuth 凭证或系统密钥链。对于 Anthropic API，在环境中设置 `ANTHROPIC_API_KEY`，使用在 [Claude Console](https://platform.claude.com) 中创建的密钥，或在 `--settings` JSON 中提供 `apiKeyHelper`。Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 继续照常读取它们自己的提供商凭证。

54 54

~~55在裸模式下，Claude 可以访问 Bash、文件读取和文件编辑工具。使用标志传递您需要的任何上下文：~~55在裸模式下，Claude 可以访问 Bash、文件读取和文件编辑工具。使用标志传递你需要的任何 context：

56 56

57| 要加载 | 使用 |57| 要加载 | 使用 |

58| - | - |58| - | - |

60| 设置 | `--settings <file-or-json>` |60| 设置 | `--settings <file-or-json>` |

61| MCP 服务器 | `--mcp-config <file-or-json>` |61| MCP 服务器 | `--mcp-config <file-or-json>` |

62| 自定义 agents | `--agents <json>` |62| 自定义 agents | `--agents <json>` |

~~63| 插件 | `--plugin-dir <path>`, `--plugin-url <url>` |~~63| 一个插件 | `--plugin-dir <path>`, `--plugin-url <url>` |

64 64

65<Note>65<Note>

66 `--bare` 是脚本和 SDK 调用的推荐模式，将在未来版本中成为 `-p` 的默认值。66 `--bare` 是脚本和 SDK 调用的推荐模式，将在未来版本中成为 `-p` 的默认值。

70 退出时的后台任务70 退出时的后台任务

71</h3>71</h3>

72 72

73如果 Claude 在 `claude -p` 运行期间启动 [后台 Bash 任务](/docs/zh-CN/tools-reference#bash-tool-behavior)，例如开发服务器或监视构建，该 shell 会在 Claude 返回其最终结果并关闭 stdin 后约五秒钟被终止。宽限期允许在结果之后立即完成的任务仍然能够传递其输出。73如果 Claude 在 `claude -p` 运行期间启动 [后台 Bash 任务](/docs/zh-CN/tools-reference#bash-tool-behavior)（例如开发服务器或监视构建），该 shell 将在 Claude 返回其最终结果并关闭 stdin 后约五秒钟被终止。宽限期允许在结果之后立即完成的任务仍然传递其输出。

74 74

75如果 Claude 启动后台 [subagent](/docs/zh-CN/sub-agents) 或工作流，`claude -p` 会改为保持打开状态，直到该工作完成，因为其结果是最终输出的一部分。75如果 Claude 启动后台 [subagent](/docs/zh-CN/sub-agents) 或工作流，`claude -p` 会改为保持打开状态，直到该工作完成，因为其结果是最终输出的一部分。

76 76

77默认情况下，等待在连续空闲等待 10 分钟后结束，因此卡住的 subagent 或工作流无法无限期地保持进程打开。此时，Claude Code 停止仍在运行的任何内容并丢弃其部分结果。要更改限制，请设置 [`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`](/docs/zh-CN/env-vars)，或将其设置为 `0` 以无限制地等待。77默认情况下，等待在连续空闲等待 10 分钟后结束，因此卡住的 subagent 或工作流无法无限期地保持进程打开。此时 Claude Code 停止仍在运行的任何内容并丢弃其部分结果。要更改限制，请设置 [`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`](/docs/zh-CN/env-vars)，或将其设置为 `0` 以无限期等待。

78 78

79如果 Claude 在 `claude -p` 运行期间启动 [Monitor](/docs/zh-CN/tools-reference#monitor-tool) 监视，Claude Code 会等待该监视，直到它超时或十分钟上限结束等待，以先发生者为准。在等待期间，Claude 继续响应监视报告的内容。默认情况下，监视在 Claude 启动它后五分钟超时。79如果 Claude 在 `claude -p` 运行期间启动 [Monitor](/docs/zh-CN/tools-reference#monitor-tool) 监视，Claude Code 会等待监视直到它超时或十分钟的上限结束等待，以先发生者为准。在等待期间，Claude 继续响应监视报告的内容。默认情况下，监视在 Claude 启动后五分钟超时。

80 80

81<h3 id="stop-a-run-with-sigterm">81<h3 id="stop-a-run-with-sigterm">

82 使用 SIGTERM 停止运行82 使用 SIGTERM 停止运行

83</h3>83</h3>

84 84

85如果您使用 SIGTERM 停止 `claude -p` 运行，例如使用 `kill` 或从进程监督程序，Claude Code 以代码 143 退出。Claude Code 将正在进行的转向保持未完成状态，并为其记录无结果。要改为结束转向，请发送 SIGINT，或在停止进程之前调用 Agent SDK 的 `interrupt()`。85如果你使用 SIGTERM 停止 `claude -p` 运行，例如使用 `kill` 或从进程监督程序，Claude Code 以代码 143 退出。Claude Code 将正在进行的转向保持未完成状态，并且不为其记录任何结果。要改为结束转向，请发送 SIGINT，或在停止进程之前调用 Agent SDK 的 `interrupt()`。

86 86

87在 SIGTERM 上，Claude Code 终止仍在运行的任何 Bash 命令的进程树。Claude Code 然后运行 [`SessionEnd` hooks](/docs/zh-CN/hooks#sessionend) 并退出。在退出时，Claude Code 不启动新的工具调用，不发送新的模型请求，也不运行除 `SessionEnd` 之外的任何 hook。如果运行在信号到达时处于命令中间或等待权限提示的答案，Claude Code 按如下方式处理该步骤：87在 SIGTERM 上，Claude Code 终止仍在运行的任何 Bash 命令的进程树。Claude Code 然后运行 [`SessionEnd` hooks](/docs/zh-CN/hooks#sessionend) 并退出。退出时，Claude Code 不启动新的工具调用，不发送新的模型请求，也不运行除 `SessionEnd` 之外的任何 hook。如果运行在信号到达时处于命令中间或等待权限提示的答案，Claude Code 按如下方式处理该步骤：

88 88

89* **运行命令**：Claude Code 在会话中将命令记录为已杀死。89* **运行命令**：Claude Code 在会话中将命令记录为已杀死。

90* **等待权限提示的答案**：如果您向进程发送 SIGTERM，Claude Code 会将提示保持未回答状态。如果您的程序通过 Agent SDK 关闭会话，SDK 会在发送任何信号之前结束 Claude Code 的输入，Claude Code 会在输入结束后立即取消提示。90* **等待权限提示的答案**：如果你向进程发送 SIGTERM，Claude Code 会将提示保持未回答状态。如果你的程序通过 Agent SDK 关闭会话，SDK 会在发送任何信号之前结束 Claude Code 的输入，Claude Code 会在输入结束后立即取消提示。

91 91

~~92当您 [恢复会话](#continue-conversations) 时，Claude Code 继续 SIGTERM 留下的未完成转向。~~92当你 [恢复会话](#continue-conversations) 时，Claude Code 将中断的转向保持原样，你的下一个提示驱动对话。要让 Claude Code 在恢复时继续中断的转向，请设置 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN=1`](/docs/zh-CN/env-vars)。

94<h3 id="if-the-working-directory-is-deleted">

95 如果工作目录被删除

96</h3>

98如果 `claude -p` 或 Agent SDK 会话的工作目录在会话中间被删除，会话继续运行。当转向在目录缺失时启动时，Claude Code 在 `stream-json` 输出中发出 [警告消息](/docs/zh-CN/agent-sdk/typescript#sdkinformationalmessage)，shell 命令失败，直到目录再次存在。

93 99

94<h2 id="examples">100<h2 id="examples">

95 示例101 示例

255| 字段 | 类型 | 描述 |261| 字段 | 类型 | 描述 |

256| - | - | - |262| - | - | - |

257| `plugins` | 数组 | 成功加载的 plugins，每个都有 `name` 和 `path` |263| `plugins` | 数组 | 成功加载的 plugins，每个都有 `name` 和 `path` |

258| `plugin_errors` | 数组 | plugin 加载时错误，每个都有 `plugin`、`type` 和 `message`。包括不满足的依赖版本和 `--plugin-dir` 加载失败，例如缺失路径或无效存档。受影响的 plugins 被降级并从 `plugins` 中缺失。当没有错误时，该键被省略 |264| `plugin_errors` | 数组 | plugin 加载时错误，每个都有 `plugin`、`type` 和 `message`。包括不满足的依赖版本和 `--plugin-dir` 加载失败，例如缺失路径或无效存档。未加载的 plugin 从 `plugins` 中缺失。当没有错误时，该键被省略 |

265

266当 `--plugin-dir` 目录或存档本身加载失败时，其 `plugin_errors` 条目包括解析的绝对路径作为 `path`。使用它来判断哪个 `--plugin-dir` 值失败。`path` 字段需要 Claude Code v2.1.283 或更高版本。

259 267

260以相同的方式使用 MCP 服务器字段。当您使用 `-p` 传递 [`--mcp-config`](/docs/zh-CN/cli-reference#cli-flags) 时，Claude Code 在运行第一轮之前等待仍然待处理的服务器，最多等待 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 启动超时，默认为 30 秒。具有 [缓存工具列表](/docs/zh-CN/agent-sdk/mcp#connection-timing) 的远程服务器跳过等待，在 `system/init` 中显示 `pending`，并在其第一次工具调用时连接。等待需要 Claude Code v2.1.221 或更高版本。268以相同的方式使用 MCP 服务器字段。当您使用 `-p` 传递 [`--mcp-config`](/docs/zh-CN/cli-reference#cli-flags) 时，Claude Code 在运行第一轮之前等待仍然待处理的服务器，最多等待 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 启动超时，默认为 30 秒。具有 [缓存工具列表](/docs/zh-CN/agent-sdk/mcp#connection-timing) 的远程服务器跳过等待，在 `system/init` 中显示 `pending`，并在其第一次工具调用时连接。等待需要 Claude Code v2.1.221 或更高版本。

261 269

hooks.md +272 −274

Details

474| `command` | 是 | 要执行的 shell 命令。使用 `args` 时，直接生成的可执行文件。请参阅 [Exec 形式和 shell 形式](#exec-form-and-shell-form) |474| `command` | 是 | 要执行的 shell 命令。使用 `args` 时，直接生成的可执行文件。请参阅 [Exec 形式和 shell 形式](#exec-form-and-shell-form) |

475| `args` | 否 | 参数列表。存在时，`command` 被解析为可执行文件并直接使用 `args` 作为参数向量生成，不涉及 shell。请参阅 [Exec 形式和 shell 形式](#exec-form-and-shell-form) |475| `args` | 否 | 参数列表。存在时，`command` 被解析为可执行文件并直接使用 `args` 作为参数向量生成，不涉及 shell。请参阅 [Exec 形式和 shell 形式](#exec-form-and-shell-form) |

476| `async` | 否 | 如果为 `true`，在后台运行而不阻止。请参阅 [在后台运行 hooks](#run-hooks-in-the-background) |476| `async` | 否 | 如果为 `true`，在后台运行而不阻止。请参阅 [在后台运行 hooks](#run-hooks-in-the-background) |

477| `asyncRewake` | 否 | 如果为 `true`，在后台运行并在退出代码 2 时唤醒 Claude。hook 的 stderr 或 stdout（如果 stderr 为空）显示给 Claude 作为系统提醒，以便它可以对长时间运行的后台失败做出反应 |477| `asyncRewake` | 否 | 如果为 `true`，在后台运行并在退出代码 2 时唤醒 Claude。hook 的 stderr 或 stdout（如果 stderr 为空）显示给 Claude 作为 [系统提醒](/docs/zh-CN/glossary#system-reminder)，以便它可以对长时间运行的后台失败做出反应 |

478| `shell` | 否 | 用于此 hook 的 shell。接受 `"bash"` 或 `"powershell"`。默认为 `"bash"`，或在未安装 Git Bash 时在 Windows 上默认为 `"powershell"`。设置 `"powershell"` 在 Windows 上通过 PowerShell 运行命令。不需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL`，因为 hooks 直接生成 PowerShell。设置 `args` 时被忽略 |478| `shell` | 否 | 用于此 hook 的 shell。接受 `"bash"` 或 `"powershell"`。默认为 `"bash"`，或在未安装 Git Bash 时在 Windows 上默认为 `"powershell"`。设置 `"powershell"` 在 Windows 上通过 PowerShell 运行命令。不需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL`，因为 hooks 直接生成 PowerShell。设置 `args` 时被忽略 |

479 479

480<a id="exec-form-and-shell-form" />480<a id="exec-form-and-shell-form" />

571 571

572| 字段 | 必需 | 描述 |572| 字段 | 必需 | 描述 |

573| :- | :- | :- |573| :- | :- | :- |

574| `server` | 是 | 配置的 MCP 服务器的名称。对于 [插件捆绑的服务器](/docs/zh-CN/mcp#plugin-provided-mcp-servers)，这是范围名称 `plugin:<plugin-name>:<server-name>`，如 `plugin:my-plugin:db`，不是裸服务器密钥。服务器必须已连接；hook 永远不会触发 OAuth 或连接流 |574| `server` | 是 | 配置的 MCP 服务器的名称。对于 [插件捆绑的服务器](/docs/zh-CN/mcp#plugin-provided-mcp-servers)，这是范围名称 `plugin:<plugin-name>:<server-name>`，如 `plugin:my-plugin:db`，不是裸服务器密钥 |

575| `tool` | 是 | 在该服务器上调用的工具的名称 |575| `tool` | 是 | 在该服务器上调用的工具的名称 |

576| `input` | 否 | 传递给工具的参数。字符串值支持来自 hook 的 [JSON 输入](#hook-input-and-output) 的 `${path}` 替换，如 `"${tool_input.file_path}"` |576| `input` | 否 | 传递给工具的参数。字符串值支持来自 hook 的 [JSON 输入](#hook-input-and-output) 的 `${path}` 替换，如 `"${tool_input.file_path}"` |

577 577

578Claude Code 读取工具的文本内容的方式与读取命令 hook stdout 相同，遵循 [退出代码 0 下的解析规则](#exit-code-0)。如果命名的服务器未连接，或工具返回 `isError: true`，hook 产生非阻止错误，执行继续。

~~579~~

580此示例在每个 `Write` 或 `Edit` 后在 `my_server` MCP 服务器上调用 `security_scan` 工具，传递编辑文件的路径：578此示例在每个 `Write` 或 `Edit` 后在 `my_server` MCP 服务器上调用 `security_scan` 工具，传递编辑文件的路径：

581 579

582```json theme={null}580```json theme={null}

599}597}

600```598```

601 599

602`mcp_tool` hook 仅在 Claude Code 使会话的 MCP 服务器对 hooks 可用后才能运行。`SessionStart` 和 `Setup` 可能在该点之前触发：600<h5 id="how-the-tool’s-result-is-read">

601 工具结果如何被读取

602</h5>

603 603

604* **在启动时**：`SessionStart` 在服务器可用之前触发，包括当使用 `--continue` 或 `--resume` 启动时。Claude Code 跳过事件的 `mcp_tool` hooks 而不调用其工具，[调试日志](#debug-hooks) 记录 `mcp_tool hooks are not available for the 'SessionStart' hook event (no MCP client context)`。604Claude Code 读取工具的文本内容的方式与读取命令 hook stdout 相同，遵循 [退出代码 0 下的解析规则](#exit-code-0)。如果工具返回 `isError: true`，hook 产生非阻止错误，执行继续。

605* **稍后在运行会话中**：在 `/clear` 或压缩后，`SessionStart` 再次触发，服务器已可用，其 `mcp_tool` hooks 运行。

606* **在 `Setup` 上**：`Setup` 总是在服务器可用之前触发，因此 Claude Code 每次都跳过其 `mcp_tool` hooks 并记录相同的消息，命名 `Setup`。

607 605

608例如，此配置从 `SessionStart` hook 在 `my_server` MCP 服务器上调用 `load_context` 工具，没有匹配器，因此它适用于每个 `SessionStart` 源：606<h5 id="when-the-server-is-still-connecting">

607 当服务器仍在连接时

608</h5>

609 609

610```json theme={null}610在 hook 可以阻止或改变结果的事件上，如 `PreToolUse` 或 `Stop`，Claude Code 在调用工具之前等待连接的服务器，最多 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 和在 hook 自己的 [`timeout`](#common-fields) 内。在观察事件上，如 `Notification` 或 `SessionEnd`，它不等待。

611{

612 "hooks": {

613 "SessionStart": [

614 {

615 "hooks": [

616 {

617 "type": "mcp_tool",

618 "server": "my_server",

619 "tool": "load_context"

620 }

621 ]

622 }

623 ]

624 }

625}

626```

627 611

628当运行 `claude` 时，Claude Code 跳过此 hook，永远不调用 `load_context`，并将 `no MCP client context` 消息写入调试日志。在同一会话中运行 `/clear`，hook 运行并调用 `load_context`。`type: "command"` hook 在 `SessionStart` 上运行，因此对会话从第一轮需要的任何东西使用一个。612显示 [`cached` 状态](/docs/zh-CN/mcp#server-status-detail) 的服务器在 hook 调用其工具时连接。如果服务器在该点未连接，hook 产生非阻止错误，执行继续。hook 永远不会启动 OAuth 流，因此 [从 `/mcp` 先验证服务器](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers)。

613

614<h5 id="events-that-fire-before-mcp-servers-are-available">

615 MCP 服务器可用之前触发的事件

616</h5>

617

618`SessionStart` 在启动时（包括使用 `--continue` 或 `--resume`）和每个 `Setup` 事件在会话的 MCP 服务器对 hooks 可用之前触发。Claude Code 跳过其 `mcp_tool` hooks 而不调用工具，[调试日志](#debug-hooks) 记录 `mcp_tool hooks are not available for the 'SessionStart' hook event (no MCP client context)`，或相同的消息命名 `Setup`。当 `SessionStart` 稍后在会话中再次触发时，在 `/clear` 或压缩后，其 `mcp_tool` hooks 运行。对于会话在启动时需要的任何东西，改用 `SessionStart` 上的 `type: "command"` hook。

629 619

630<h4 id="prompt-and-agent-hook-fields">620<h4 id="prompt-and-agent-hook-fields">

631 提示和代理 hook 字段621 提示和代理 hook 字段

636| 字段 | 必需 | 描述 |626| 字段 | 必需 | 描述 |

637| :- | :- | :- |627| :- | :- | :- |

638| `prompt` | 是 | 发送给模型的提示文本。使用 `$ARGUMENTS` 作为 hook 输入 JSON 的占位符。用反斜杠转义以包含文字文本：`\$1.00` 呈现为 `$1.00` |628| `prompt` | 是 | 发送给模型的提示文本。使用 `$ARGUMENTS` 作为 hook 输入 JSON 的占位符。用反斜杠转义以包含文字文本：`\$1.00` 呈现为 `$1.00` |

639| `model` | 否 | 用于评估的模型。默认为快速模型 |629| `model` | 否 | 用于评估的模型。默认为 Claude Code 用于 [后台功能](/docs/zh-CN/costs#background-token-usage) 的模型 |

640 630

641<h3 id="reference-scripts-by-path">631<h3 id="reference-scripts-by-path">

642 按路径引用脚本632 按路径引用脚本

791| `prompt_id` | 标识当前正在处理的用户提示的 UUID。与 [OpenTelemetry 事件上的 `prompt.id` 属性](/docs/zh-CN/monitoring-usage#event-correlation-attributes)匹配，因此您可以将 hook 输出与单个提示的遥测关联起来。在第一个用户输入之前不存在。需要 Claude Code v2.1.196 或更高版本 |781| `prompt_id` | 标识当前正在处理的用户提示的 UUID。与 [OpenTelemetry 事件上的 `prompt.id` 属性](/docs/zh-CN/monitoring-usage#event-correlation-attributes)匹配，因此您可以将 hook 输出与单个提示的遥测关联起来。在第一个用户输入之前不存在。需要 Claude Code v2.1.196 或更高版本 |

792| `transcript_path` | 对话 JSON 的路径。转录文件异步写入，可能滞后于内存中的对话，因此当 hook 触发时，它可能还不包括当前轮次的最新消息。需要当前轮次最终助手文本的 hook 应在 [Stop](#stop) 和 [SubagentStop](#subagentstop) 上使用 `last_assistant_message`，而不是读取转录 |782| `transcript_path` | 对话 JSON 的路径。转录文件异步写入，可能滞后于内存中的对话，因此当 hook 触发时，它可能还不包括当前轮次的最新消息。需要当前轮次最终助手文本的 hook 应在 [Stop](#stop) 和 [SubagentStop](#subagentstop) 上使用 `last_assistant_message`，而不是读取转录 |

793| `cwd` | 调用 hook 时的当前工作目录 |783| `cwd` | 调用 hook 时的当前工作目录 |

794| `scratchpad_dir` | 会话的 scratchpad 目录的路径，Claude 在其中保存临时工作文件。当会话没有 scratchpad 或 temp 目录不可用时不存在。需要 Claude Code v2.1.257 或更高版本 |784| `scratchpad_dir` | 会话的 [scratchpad 目录](/docs/zh-CN/claude-directory#session-scratchpad-directory)的路径，Claude 在其中保存临时工作文件。当会话没有 scratchpad 或 temp 目录不可用时不存在。需要 Claude Code v2.1.257 或更高版本 |

795| `permission_mode` | 当前[权限模式](/docs/zh-CN/permissions#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。标记为**手动**的模式作为 `"default"` 到达，从不作为 `"manual"`，因此匹配 `"default"` 的脚本继续工作。并非所有事件都接收此字段。检查每个 [hook 事件](#hook-events)部分中的 JSON 示例 |785| `permission_mode` | 当前[权限模式](/docs/zh-CN/permissions#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。标记为**手动**的模式作为 `"default"` 到达，从不作为 `"manual"`，因此匹配 `"default"` 的脚本继续工作。并非所有事件都接收此字段。检查每个 [hook 事件](#hook-events)部分中的 JSON 示例 |

796| `effort` | 对象，其 `level` 字段保存 hook 运行时生效的[工作量级别](/docs/zh-CN/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。如果您设置了活跃模型不支持的级别，`level` 会报告 Claude Code 运行的级别；[调整工作量级别](/docs/zh-CN/model-config#adjust-effort-level)说明它如何选择该级别。Ultracode 不是一个不同的级别，报告为 `"xhigh"`。该对象与[状态行](/docs/zh-CN/statusline#available-data) `effort` 字段匹配。对于在工具使用上下文中触发的事件（如 `PreToolUse`、`PostToolUse`、`Stop` 和 `SubagentStop`），当当前模型支持工作量参数时存在。该级别也可作为 `$CLAUDE_EFFORT` 环境变量供 hook 命令和 Bash 工具使用。 |786| `effort` | 对象，其 `level` 字段保存 hook 运行时生效的[工作量级别](/docs/zh-CN/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。如果您设置了活跃模型不支持的级别，`level` 会报告 Claude Code 运行的级别；[调整工作量级别](/docs/zh-CN/model-config#adjust-effort-level)说明它如何选择该级别。该对象与[状态行](/docs/zh-CN/statusline#available-data) `effort` 字段匹配。对于在工具使用上下文中触发的事件（如 `PreToolUse`、`PostToolUse`、`Stop` 和 `SubagentStop`），当当前模型支持工作量参数时存在。该级别也可作为 `$CLAUDE_EFFORT` 环境变量供 hook 命令和 Bash 工具使用。 |

798 788

799使用 `--agent` 运行或在 subagent 内部时，包括两个额外字段：789使用 `--agent` 运行或在 subagent 内部时，包括两个额外字段：

1057 为 Claude 添加上下文1047 为 Claude 添加上下文

1058</h4>1048</h4>

1059 1049

1060`additionalContext` 字段将字符串从您的 hook 传递到 Claude 的上下文窗口。Claude Code 将字符串包装在系统提醒中，并在 hook 触发的点将其插入对话。Claude 在下一个模型请求时读取提醒，但它不作为聊天消息出现在界面中。1050`additionalContext` 字段将字符串从您的 hook 传递到 Claude 的上下文窗口。Claude Code 将字符串包装在[系统提醒](/docs/zh-CN/glossary#system-reminder)中，并在 hook 触发的点将其插入对话。Claude 在下一个模型请求时读取提醒，但它不作为聊天消息出现在界面中。

1061 1051

1062在 `hookSpecificOutput` 中返回 `additionalContext` 以及事件名称：1052在 `hookSpecificOutput` 中返回 `additionalContext` 以及事件名称：

1063 1053

1179 Hook 事件1169 Hook 事件

1180</h2>1170</h2>

1181 1171

1182每个事件对应于 Claude Code 生命周期中的一个点，hooks 可以在该点运行。下面的部分按照生命周期顺序排列：从会话设置到 agentic 循环再到会话结束。每个部分描述事件何时触发、它支持哪些匹配器、它接收的 JSON 输入，以及如何通过输出控制行为。1172每个事件对应于 Claude Code 生命周期中的一个点，hooks 可以在该点运行。下面的部分按照生命周期顺序排列：从会话设置到 agentic 循环再到会话结束。每个部分描述事件何时触发、它支持哪些匹配器、它接收的 JSON 输入以及如何通过输出控制行为。

1183 1173

1184<h3 id="sessionstart">1174<h3 id="sessionstart">

1185 SessionStart1175 SessionStart

1201 1191

1202在 v2.1.214 之前，分叉的会话报告源为 `"resume"`。1192在 v2.1.214 之前，分叉的会话报告源为 `"resume"`。

1203 1193

1204当您启动交互式会话、使用 `--continue` 或 `--resume` 在启动时恢复对话、或运行 `/clear` 时，SessionStart hooks 在后台运行。您可以立即输入，恢复的对话显示时无需等待 hooks。Claude 的第一个响应仍然等待 hooks 完成，因此它们的上下文到达 Claude。1194当您启动交互式会话、使用 `--continue` 或 `--resume` 在启动时恢复对话或运行 `/clear` 时，SessionStart hooks 在后台运行。您可以立即输入，恢复的对话显示时无需等待 hooks。Claude 的第一个响应仍然等待 hooks 完成，因此它们的上下文到达 Claude。

1205 1195

1206当您在会话内使用 `/resume` 切换对话时，切换等待 hooks 完成。如果您在后台 hooks 仍在运行时运行 `/clear` 或切换到另一个对话，它们返回的任何内容都不适用于会话。1196当您在会话内使用 `/resume` 切换对话时，切换等待 hooks 完成。如果您在后台 hooks 仍在运行时运行 `/clear` 或切换到另一个对话，它们返回的任何内容都不适用于该会话。

1207 1197

1208在启动时也适用相同的等待，包括恢复的会话：您在 SessionStart hooks 仍在运行时发送的提示不会到达 Claude，直到它们完成。1198在启动时也适用相同的等待，包括恢复的会话：您在 SessionStart hooks 仍在运行时发送的提示不会到达 Claude，直到它们完成。

1209 1199

1217 1207

1218| 字段 | 描述 |1208| 字段 | 描述 |

1219| :- | :- |1209| :- | :- |

1223| `session_title` | 当前会话标题（如果已设置），例如通过 `--name` 或 `/rename`。一个发出 `sessionTitle` 的 hook 可以先检查 `session_title` 以避免覆盖用户明确设置的标题 |1213| `session_title` | 当前会话标题（如果已设置），例如通过 `--name` 或 `/rename`。发出 `sessionTitle` 的 hook 可以先检查 `session_title` 以避免覆盖用户明确设置的标题 |

1224 1214

1225当 `source` 为 `"resume"` 或 `"fork"` 且成绩单包含至少一个来自 Claude 的响应时，SessionStart hooks 还接收下面的四个字段。您的 hook 可以使用它们在第一个请求之前报告恢复陈旧对话的成本，例如在 [`systemMessage`](#json-output) 中。这些字段需要 Claude Code v2.1.251 或更高版本。1215当 `source` 为 `"resume"` 或 `"fork"` 且成绩单包含至少一个来自 Claude 的响应时，SessionStart hooks 也会接收下面的四个字段。您的 hook 可以使用它们在第一个请求之前报告恢复陈旧对话的成本，例如在 [`systemMessage`](#json-output) 中。这些字段需要 Claude Code v2.1.251 或更高版本。

1226 1216

1227| 字段 | 描述 |1217| 字段 | 描述 |

1228| :- | :- |1218| :- | :- |

1258| :- | :- |1248| :- | :- |

1259| `additionalContext` | 在对话开始时添加到 Claude 上下文的字符串，在第一个提示之前。有关文本如何传递以及放入其中的内容，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |1249| `additionalContext` | 在对话开始时添加到 Claude 上下文的字符串，在第一个提示之前。有关文本如何传递以及放入其中的内容，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |

1260| `initialUserMessage` | 用作会话第一个用户消息的字符串。适用于 [非交互模式](/docs/zh-CN/headless)，带有 `-p` 标志，即使未提供提示，它也成为第一个回合。如果提供了提示，它作为下一个回合跟随。与 `additionalContext` 不同，后者附加到现有回合，这会创建回合 |1250| `initialUserMessage` | 用作会话第一个用户消息的字符串。适用于 [非交互模式](/docs/zh-CN/headless)，带有 `-p` 标志，即使未提供提示，它也成为第一个回合。如果提供了提示，它作为下一个回合跟随。与 `additionalContext` 不同，后者附加到现有回合，这会创建回合 |

1261| `sessionTitle` | 设置会话标题，与 `/rename` 效果相同。用于从启动文件夹、git 分支或 worktree 名称自动命名会话。当 `source` 为 `"startup"`、`"resume"` 或 `"fork"` 时适用；在 `"clear"` 和 `"compact"` 上被忽略 |1251| `sessionTitle` | 设置会话标题，效果与 `/rename` 相同。用于从启动文件夹、git 分支或 worktree 名称自动命名会话。当 `source` 为 `"startup"`、`"resume"` 或 `"fork"` 时适用；在 `"clear"` 和 `"compact"` 上被忽略 |

1263| `reloadSkills` | 布尔值。当为 `true` 时，Claude Code 在 SessionStart hooks 完成后重新扫描 [skill](/docs/zh-CN/skills) 和命令目录，因此 hook 安装的 skills 在同一会话中可用，从第一个提示开始 |1253| `reloadSkills` | 布尔值。当为 `true` 时，Claude Code 在 SessionStart hooks 完成后重新扫描 [skill](/docs/zh-CN/skills) 和命令目录，因此 hook 安装的 skills 在同一会话中可用，从第一个提示开始 |

1264 1254

1265```json theme={null}1255```json theme={null}

1272}1262}

1273```1263```

1274 1264

1275由于纯 stdout 已经为此事件到达 Claude，仅加载上下文的 hook 可以直接打印到 stdout，而无需构建 JSON。当您需要将上下文与其他字段（如 `sessionTitle`）结合时，使用 JSON 形式。1265由于纯 stdout 已经为此事件到达 Claude，仅加载上下文的 hook 可以直接打印到 stdout 而无需构建 JSON。当您需要将上下文与其他字段（如 `sessionTitle`）结合时，使用 JSON 形式。

1276 1266

1277当 SessionStart hook 安装或更新 skills 时使用 `reloadSkills`。Skill 发现通常在 SessionStart hooks 完成之前运行，因此 hook 写入 `~/.claude/skills/` 或 `.claude/skills/` 的文件否则只会在下一个会话中出现。此示例同步共享 skills 存储库并请求重新扫描：1267当 SessionStart hook 安装或更新 skills 时使用 `reloadSkills`。Skill 发现通常在 SessionStart hooks 完成之前运行，因此 hook 写入 `~/.claude/skills/` 或 `.claude/skills/` 的文件否则只会在下一个会话中出现。此示例同步共享 skills 存储库并请求重新扫描：

1278 1268

1345 1335

1346当您运行 `claude --init-only` 时，Claude Code 运行 Setup hooks 和带有 `startup` 匹配器的 `SessionStart` hooks，然后退出而不启动对话。1336当您运行 `claude --init-only` 时，Claude Code 运行 Setup hooks 和带有 `startup` 匹配器的 `SessionStart` hooks，然后退出而不启动对话。

1347 1337

1348当您使用 `-p` 启动或继续对话时，您还需要提供提示，作为参数或通过 stdin 管道传输。当 `SessionStart` hook 提供 [`initialUserMessage`](#sessionstart-decision-control) 或当您使用 [延迟工具调用](#defer-a-tool-call-for-later) 恢复会话时，您可以跳过提示。1338当您使用 `-p` 启动或继续对话时，您还需要提供提示，作为参数或通过 stdin 管道传输。当 `SessionStart` hook 提供 [`initialUserMessage`](#sessionstart-decision-control) 或当您恢复带有 [延迟工具调用](#defer-a-tool-call-for-later) 的会话时，您可以跳过提示。

1349 1339

1350成功时，`--init-only` 不向终端打印任何内容。要确认 hooks 运行，请使用 `claude --debug-file <path> --init-only` 启动，将 `<path>` 替换为日志文件位置，并检查日志中的 Setup 和 SessionStart hook 条目。1340成功时，`--init-only` 不向终端打印任何内容。要确认 hooks 运行，请使用 `claude --debug-file <path> --init-only` 启动，将 `<path>` 替换为日志文件位置，并检查日志中的 Setup 和 SessionStart hook 条目。

1351 1341

1352由于 Setup 不会在每次启动时触发，需要安装依赖的插件不能仅依赖 Setup。实际的模式是在首次使用时检查依赖，如果缺失则安装，例如测试 `${CLAUDE_PLUGIN_DATA}/node_modules` 的 hook 或 skill，如果不存在则运行 `npm install`。有关在何处存储已安装的依赖，请参阅 [持久数据目录](/docs/zh-CN/plugins/components#path-variables-and-persistent-data)。如果您通过市场分发插件，您可能不需要此模式：Claude Code [在缓存插件时自动安装符合条件的 Node.js 包依赖](/docs/zh-CN/plugins/loading#node-js-package-dependencies)。1342由于 Setup 不会在每次启动时触发，需要安装依赖的插件不能仅依赖 Setup。实际的模式是在首次使用时检查依赖并在缺失时安装，例如测试 `${CLAUDE_PLUGIN_DATA}/node_modules` 的 hook 或 skill，如果不存在则运行 `npm install`。有关存储已安装依赖的位置，请参阅 [持久数据目录](/docs/zh-CN/plugins/components#path-variables-and-persistent-data)。如果您通过市场分发插件，您可能不需要此模式：Claude Code [在缓存插件时自动安装符合条件的 Node.js 包依赖](/docs/zh-CN/plugins/loading#node-js-package-dependencies)。

1353 1343

1354<h4 id="setup-input">1344<h4 id="setup-input">

1355 Setup 输入1345 Setup 输入

1371 Setup 决策控制1361 Setup 决策控制

1372</h4>1362</h4>

1373 1363

1374Setup hooks 无法阻止；执行在任何退出代码上继续。在每个退出代码上，Claude Code 丢弃 Setup hook 的 [JSON 输出字段](#json-output)，如 `systemMessage`、`continue` 和 `hookSpecificOutput.additionalContext`。使用 `-p` 时，Setup hook 的 stdout、stderr 和退出代码仅在您使用 `--output-format stream-json --verbose` 启动时作为 [`hook_response` 事件](/docs/zh-CN/headless#read-session-metadata) 出现在运行的输出中。1364Setup hooks 无法阻止；执行在任何退出代码上继续。在每个退出代码上，Claude Code 丢弃 Setup hook 的 [JSON 输出字段](#json-output)，如 `systemMessage`、`continue` 和 `hookSpecificOutput.additionalContext`。使用 `-p`，Setup hook 的 stdout、stderr 和退出代码仅在您使用 `--output-format stream-json --verbose` 启动时作为 [`hook_response` 事件](/docs/zh-CN/headless#read-session-metadata) 出现在运行的输出中。

1375 1365

1376Setup hooks 可以访问 `CLAUDE_ENV_FILE`。写入该文件的变量持久化到会话的后续 Bash 命令中，就像在 [SessionStart hooks](#persist-environment-variables) 中一样。仅 `type: "command"` hooks 在 `Setup` 上运行。`type: "mcp_tool"` hook 在 `Setup` 上总是被跳过，如 [MCP tool hook 字段](#mcp-tool-hook-fields) 下所述。1366Setup hooks 可以访问 `CLAUDE_ENV_FILE`。写入该文件的变量持久化到会话的后续 Bash 命令中，就像在 [SessionStart hooks](#persist-environment-variables) 中一样。仅 `type: "command"` hooks 在 `Setup` 上运行。`type: "mcp_tool"` hook 在 `Setup` 上总是被跳过，如 [MCP tool hook 字段](#mcp-tool-hook-fields) 下所述。

1377 1367

1379 InstructionsLoaded1369 InstructionsLoaded

1380</h3>1370</h3>

1381 1371

1382在加载 `CLAUDE.md` 或 `.claude/rules/*.md` 文件到上下文时触发。此事件在会话启动时为急切加载的文件触发，稍后当文件被懒加载时再次触发，例如当 Claude 访问包含嵌套 `CLAUDE.md` 的子目录或当带有 `paths:` frontmatter 的条件规则匹配时。hook 不支持阻止或决策控制。它异步运行以用于可观测性目的。1372当 `CLAUDE.md` 或 `.claude/rules/*.md` 文件加载到上下文中时触发。此事件在会话启动时对于急切加载的文件触发，稍后当文件被懒加载时再次触发，例如当 Claude 访问包含嵌套 `CLAUDE.md` 的子目录或当带有 `paths:` frontmatter 的条件规则匹配时。hook 不支持阻止或决策控制。它异步运行以用于可观测性目的。

1383 1373

1384当 Claude [直接通过 **Project instructions** 设置读取 `AGENTS.md`](/docs/zh-CN/memory#agents-md) 时，此事件不触发。当 `CLAUDE.md` 导入您的 `AGENTS.md` 时，它会触发，`load_reason` 设置为 `include`（与任何其他导入文件一样），以及当 `CLAUDE.md` 是它的符号链接时，作为正常的 `CLAUDE.md` 加载。1374当 Claude [直接通过 **Project instructions** 设置读取 `AGENTS.md`](/docs/zh-CN/memory#agents-md) 时，此事件不触发。当 `CLAUDE.md` 导入您的 `AGENTS.md` 时它会触发，`load_reason` 设置为 `include`（与任何其他导入文件一样），以及当 `CLAUDE.md` 是它的符号链接时，作为正常的 `CLAUDE.md` 加载。

1385 1375

1386匹配器针对 `load_reason` 运行。例如，使用 `"matcher": "session_start"` 仅为在会话启动时加载的文件触发，或 `"matcher": "path_glob_match|nested_traversal"` 仅为懒加载触发。1376匹配器针对 `load_reason` 运行。例如，使用 `"matcher": "session_start"` 仅对在会话启动时加载的文件触发，或 `"matcher": "path_glob_match|nested_traversal"` 仅对懒加载触发。

1387 1377

1388<h4 id="instructionsloaded-input">1378<h4 id="instructionsloaded-input">

1389 InstructionsLoaded 输入1379 InstructionsLoaded 输入

1398| `load_reason` | 文件加载的原因：`"session_start"`、`"nested_traversal"`、`"path_glob_match"`、`"include"` 或 `"compact"`。`"compact"` 值在压缩事件后重新加载指令文件时触发 |1388| `load_reason` | 文件加载的原因：`"session_start"`、`"nested_traversal"`、`"path_glob_match"`、`"include"` 或 `"compact"`。`"compact"` 值在压缩事件后重新加载指令文件时触发 |

1402 1392

1403```json theme={null}1393```json theme={null}

1424 1414

1425在用户提交提示时运行，在 Claude 处理它之前。这允许您根据提示/对话添加额外上下文、验证提示或阻止某些类型的提示。1415在用户提交提示时运行，在 Claude 处理它之前。这允许您根据提示/对话添加额外上下文、验证提示或阻止某些类型的提示。

1426 1416

1427`UserPromptSubmit` hooks 对 `command`、`http` 和 `mcp_tool` 类型的默认超时为 30 秒，比大多数其他事件上这些类型的 600 秒默认值更短。因为此 hook 在每个提示之前运行并阻止模型处理直到它完成，卡住的 hook 会停滞会话。如果您的 hook 需要更多时间，请在 hook 条目中设置 `timeout` 字段。1417`UserPromptSubmit` hooks 对 `command`、`http` 和 `mcp_tool` 类型的默认超时为 30 秒，比大多数其他事件的 600 秒默认值更短。因为此 hook 在每个提示之前运行并阻止模型处理直到它完成，卡住的 hook 会停滞会话。如果您的 hook 需要更多时间，请在 hook 条目中设置 `timeout` 字段。

1428 1418

1429除了您使用 [`async: true`](#run-hooks-in-the-background) 运行的命令 hook 外，达到其超时的 `UserPromptSubmit` 命令、HTTP 或 MCP tool hook 被取消，其输出（包括任何 `additionalContext`）被丢弃。提示仍然到达 Claude 而没有该上下文。成绩单显示一个通知，命名 hook、触发的超时以及输出被丢弃。1419除了您使用 [`async: true`](#run-hooks-in-the-background) 运行的命令 hook，达到超时的 `UserPromptSubmit` 命令、HTTP 或 MCP tool hook 被取消，其输出（包括任何 `additionalContext`）被丢弃。提示仍然到达 Claude 而没有该上下文。成绩单显示一个通知，命名 hook、触发的超时以及输出被丢弃。

1430 1420

1431在 `UserPromptSubmit` 上达到其超时的 [Agent SDK 回调 hook](/docs/zh-CN/agent-sdk/hooks) 用命名 hook 和超时的消息阻止提示，因为那里的回调可以充当不能失败开放的策略门。会话继续。在 v2.1.208 之前，该事件上的回调超时以执行错误结束回合。1421在 `UserPromptSubmit` 上达到超时的 [Agent SDK 回调 hook](/docs/zh-CN/agent-sdk/hooks) 用命名 hook 和超时的消息阻止提示，因为那里的回调可能充当必须不能失败打开的策略门。会话继续。在 v2.1.208 之前，该事件上的回调超时以执行错误结束回合。

1432 1422

1433<h4 id="userpromptsubmit-input">1423<h4 id="userpromptsubmit-input">

1434 UserPromptSubmit 输入1424 UserPromptSubmit 输入

1435</h4>1425</h4>

1436 1426

1437除了 [常见输入字段](#common-input-fields) 外，UserPromptSubmit hooks 接收包含用户提交的文本的 `prompt` 字段。粘贴的内容折叠到 `[Pasted text #N]` 占位符会在原位展开到达。在 Claude Code [为 Claude 标记粘贴文本](/docs/zh-CN/terminal-config#how-claude-treats-pasted-text) 的会话中，该展开的内容位于 `<pasted_content id="…">` 行和 `</pasted_content id="…">` 行之间，因此如果您的 hook 解析提示，请考虑这些行。1427除了 [常见输入字段](#common-input-fields) 外，UserPromptSubmit hooks 接收包含用户提交的文本的 `prompt` 字段。折叠为 `[Pasted text #N]` 占位符的粘贴内容在原位展开到达。在 Claude Code [为 Claude 标记粘贴文本](/docs/zh-CN/terminal-config#how-claude-treats-pasted-text) 的会话中，该展开的内容位于 `<pasted_content id="…">` 行和 `</pasted_content id="…">` 行之间，因此如果您的 hook 解析提示，请考虑这些行。

1438 1428

1439```json theme={null}1429```json theme={null}

1440{1430{

1455 1445

1456有两种方式在退出代码 0 上向对话添加上下文：1446有两种方式在退出代码 0 上向对话添加上下文：

1457 1447

1458* **纯文本 stdout**：Claude Code 将它 [视为纯文本](#exit-code-0) 的 stdout 添加到 Claude 的上下文1448* **纯文本 stdout**：Claude Code 添加它 [视为纯文本](#exit-code-0) 的 stdout 到 Claude 的上下文

1459* **带有 `additionalContext` 的 JSON**：使用下面的 JSON 格式以获得更多控制。`additionalContext` 字段作为上下文添加1449* **带有 `additionalContext` 的 JSON**：使用下面的 JSON 格式以获得更多控制。`additionalContext` 字段作为上下文添加

1460 1450

1461两个通道都不产生可见的成绩单条目。纯 stdout 和 `additionalContext` 值各自作为以 hook 名称开头的系统提醒注入；Claude 读取两者。要确认传递，请检查 [调试日志](#debug-hooks)。1451两个通道都不产生可见的成绩单条目。纯 stdout 和 `additionalContext` 值各自作为以 hook 名称开头的系统提醒注入；Claude 读取两者。要确认传递，请检查 [调试日志](#debug-hooks)。

1462 1452

1463要阻止提示，返回一个 `decision` 设置为 `"block"` 的 JSON 对象：1453要阻止提示，返回一个 JSON 对象，其中 `decision` 设置为 `"block"`：

1464 1454

1465| 字段 | 描述 |1455| 字段 | 描述 |

1466| :- | :- |1456| :- | :- |

1472 1462

1488 UserPromptExpansion1478 UserPromptExpansion

1489</h3>1479</h3>

1490 1480

1491当用户输入的命令在到达 Claude 之前扩展为提示时运行。使用此来阻止特定命令的直接调用、为特定 skill 注入上下文或记录用户调用哪些命令。例如，匹配 `deploy` 的 hook 可以阻止 `/deploy`，除非存在批准文件，或匹配审查 skill 的 hook 可以将团队的审查清单附加为 `additionalContext`。1481当用户输入的命令在到达 Claude 之前展开为提示时运行。使用此来阻止特定命令的直接调用、为特定 skill 注入上下文或记录用户调用哪些命令。例如，匹配 `deploy` 的 hook 可以阻止 `/deploy`，除非存在批准文件，或匹配审查 skill 的 hook 可以将团队的审查清单附加为 `additionalContext`。

1492 1482

1493此事件涵盖 `PreToolUse` 不涵盖的路径：匹配 `Skill` 工具的 `PreToolUse` hook 仅在 Claude 调用工具时触发，但直接输入 `/skillname` 绕过 `PreToolUse`。`UserPromptExpansion` 在该直接路径上触发。1483此事件涵盖 `PreToolUse` 不涵盖的路径：匹配 `Skill` 工具的 `PreToolUse` hook 仅在 Claude 调用工具时触发，但直接输入 `/skillname` 绕过 `PreToolUse`。`UserPromptExpansion` 在该直接路径上触发。

1494 1484

1495匹配 `command_name`。将匹配器留空以在每个提示类型命令上触发。1485在 `command_name` 上匹配。将匹配器留空以对每个提示类型命令触发。

1496 1486

1497<h4 id="userpromptexpansion-input">1487<h4 id="userpromptexpansion-input">

1498 UserPromptExpansion 输入1488 UserPromptExpansion 输入

1519 UserPromptExpansion 决策控制1509 UserPromptExpansion 决策控制

1520</h4>1510</h4>

1521 1511

1522`UserPromptExpansion` hooks 可以阻止扩展或添加上下文。所有 [JSON 输出字段](#json-output) 都可用。1512`UserPromptExpansion` hooks 可以阻止展开或添加上下文。所有 [JSON 输出字段](#json-output) 都可用。

1523 1513

1524| 字段 | 描述 |1514| 字段 | 描述 |

1525| :- | :- |1515| :- | :- |

1529 1519

1530通过退出 2 阻止的 hook 路由方式与 `reason` 相同：阻止消息向用户显示 stderr 文本。1520通过退出 2 阻止的 hook 路由方式与 `reason` 相同：阻止消息向用户显示 stderr 文本。

1531 1521

1544 MessageDisplay1534 MessageDisplay

1545</h3>1535</h3>

1546 1536

1547在助手消息流向屏幕时运行。Claude Code 分批显示消息：每次一批新完成的行准备好渲染时，hook 运行一次，这些行，Claude Code 用 hook 的替换文本替换它们。长消息产生多个调用；短消息可能只产生一个。1537在助手消息流向屏幕时运行。Claude Code 分批显示消息：每次一批新完成的行准备好渲染时，hook 运行一次，这些行和 Claude Code 渲染 hook 的替换文本代替它们。长消息产生多个调用；短消息可能只产生一个。

1548 1538

1549使用 MessageDisplay 来：1539使用 MessageDisplay 来：

1550 1540

1554 1544

1555Claude Code 保持每个批次直到您的 hook 返回，因此保持 hook 快速。如果 hook 失败或超时，Claude Code 显示原始文本。此事件的默认超时为 10 秒；如果您的 hook 需要更多时间，请在 hook 条目中设置 `timeout` 字段。1545Claude Code 保持每个批次直到您的 hook 返回，因此保持 hook 快速。如果 hook 失败或超时，Claude Code 显示原始文本。此事件的默认超时为 10 秒；如果您的 hook 需要更多时间，请在 hook 条目中设置 `timeout` 字段。

1556 1546

1557MessageDisplay 仅用于显示：替换文本仅更改屏幕上呈现的内容。成绩单和 Claude 看到的内容保持原始文本，因此 Claude 永远看不到替换，详细模式显示原始文本。hook 仅接收助手消息文本，因此工具结果和您输入的文本呈现不变。1547MessageDisplay 仅用于显示：替换文本仅更改屏幕上呈现的内容。成绩单和 Claude 看到的内容保持原始文本，因此 Claude 永远看不到替换，详细模式显示原始。hook 仅接收助手消息文本，因此工具结果和您输入的文本呈现不变。

1558 1548

1559MessageDisplay 不支持匹配器，对每个流式传输文本的助手消息触发；没有文本的消息（如仅工具调用响应）不触发它。1549MessageDisplay 不支持匹配器，对每个流文本的助手消息触发；没有文本的消息（如仅工具调用响应）不触发它。

1560 1550

1561在非交互式运行中，包括 Agent SDK 查询和 `claude -p`，MessageDisplay 每个助手消息运行一次，而不是每批行运行一次。单个调用在消息完成后到达，并携带完整消息文本：`index` 为 `0`，`final` 为 `true`，`delta` 保持整个消息。为每个消息收集 `delta` 文本的 hook 在两种模式中接收相同的总文本。1551在非交互式运行中，包括 Agent SDK 查询和 `claude -p`，MessageDisplay 每个助手消息运行一次而不是每批行运行一次。单个调用在消息完成后到达并携带完整消息文本：`index` 为 `0`，`final` 为 `true`，`delta` 保持整个消息。为每个消息收集 `delta` 文本的 hook 在两种模式中接收相同的总文本。

1562 1552

1563<h4 id="messagedisplay-input">1553<h4 id="messagedisplay-input">

1564 MessageDisplay 输入1554 MessageDisplay 输入

1565</h4>1555</h4>

1566 1556

1567除了 [常见输入字段](#common-input-fields) 外，MessageDisplay hooks 接收回合和消息的标识符、此调用在消息中的位置以及 `delta` 中的新文本。批次边界取决于文本如何流式传输，因此使用 `index` 和 `final` 来跟踪通过消息的进度，而不是期望行以特定方式分组。1557除了 [常见输入字段](#common-input-fields) 外，MessageDisplay hooks 接收回合和消息的标识符、此调用在消息中的位置以及 `delta` 中的新文本。批次边界取决于文本如何流，因此使用 `index` 和 `final` 来跟踪通过消息的进度，而不是期望行以特定方式分组。

1568 1558

1569| 字段 | 描述 |1559| 字段 | 描述 |

1570| :- | :- |1560| :- | :- |

1575| `delta` | 自上一个批次以来新完成的行，包括终止换行符。始终是完整行，除了最终批次可能在行中间结束。在交互式运行中，当消息以换行符结束时，最终批次的 delta 为空，因此将 `final` 而不是非空 delta 视为消息结束信号。在 Agent SDK 和 `claude -p` 运行中，单个调用携带整个消息 |1565| `delta` | 自上一个批次以来新完成的行，包括终止换行符。始终是完整行，除了可能以行中间结束的最终批次。在交互式运行中，当消息以换行符结束时最终批次的 delta 为空，因此将 `final` 而不是非空 delta 视为消息结束信号。在 Agent SDK 和 `claude -p` 运行中，单个调用携带整个消息 |

1576 1566

1577```json theme={null}1567```json theme={null}

1578{1568{

1596 1586

1597| 字段 | 描述 |1587| 字段 | 描述 |

1598| :- | :- |1588| :- | :- |

1600 1590

1601MessageDisplay hooks 没有决策控制。它们无法阻止消息或更改成绩单中存储或发送给 Claude 的内容。Claude Code 从其 JSON 输出中作用于 `displayContent` 并丢弃 `systemMessage` 和 `continue`。1591MessageDisplay hooks 没有决策控制。它们无法阻止消息或更改存储在成绩单中或发送给 Claude 的内容。Claude Code 作用于它们的 JSON 输出中的 `displayContent` 并丢弃 `systemMessage` 和 `continue`。

1602 1592

1603此示例从 Claude 的响应中剥离 markdown 格式以获得纯文本显示。脚本从 stdin 读取每个批次，从 `delta` 中删除粗体标记和内联代码反引号，并将结果作为 `displayContent` 返回。1593此示例从 Claude 的响应中剥离 markdown 格式以获得纯文本显示。脚本从 stdin 读取每个批次，从 `delta` 中删除粗体标记和内联代码反引号，并将结果作为 `displayContent` 返回。

1604 1594

1633 </Tab>1623 </Tab>

1634 1624

1635 <Tab title="Windows (PowerShell)">1625 <Tab title="Windows (PowerShell)">

1636 注册一个通过 PowerShell 运行脚本的命令 hook：1626 注册一个命令 hook，通过 PowerShell 运行脚本：

1637 1627

1638 ```json theme={null}1628 ```json theme={null}

1639 {1629 {

1682 PreToolUse1672 PreToolUse

1683</h3>1673</h3>

1684 1674

1685在 Claude 创建工具参数之后和处理工具调用之前运行。匹配除 `EndConversation` 外的任何工具名称：内置工具，如 Bash、PowerShell、Edit、Write、Read、Glob、Grep、Agent、Workflow、WebFetch、WebSearch、AskUserQuestion 和 ExitPlanMode，以及任何 [MCP 工具名称](#match-mcp-tools)。1675在 Claude 创建工具参数之后和处理工具调用之前运行。在除 `EndConversation` 之外的任何工具名称上匹配：内置工具如 `Bash`、`PowerShell`、`Edit`、`Write`、`Read`、`Glob`、`Grep`、`Agent`、`Workflow`、`WebFetch`、`WebSearch`、`AskUserQuestion` 和 `ExitPlanMode`，以及任何 [MCP 工具名称](#match-mcp-tools)。

1686 1676

1687要在特定文件在磁盘上更改时运行 hook，无论什么写入它，请改用 [FileChanged](#filechanged) 而不是按名称匹配文件编辑工具。与 PreToolUse 不同，Claude Code 在更改后运行 FileChanged hooks，它们没有决策控制，因此无法阻止写入。1677要在特定文件在磁盘上更改时运行 hook，无论什么写入它，请使用 [FileChanged](#filechanged) 而不是按名称匹配文件编辑工具。与 PreToolUse 不同，Claude Code 在更改后运行 FileChanged hooks，它们没有决策控制，因此它们无法阻止写入。

1688 1678

1689<Warning>1679<Warning>

1690 PreToolUse 仅在 Claude 调用工具时运行。您 [在提示中使用 `@` 引用的文件](/docs/zh-CN/common-workflows#reference-files-and-directories) 添加时没有任何工具调用：Claude Code 在构建提示时插入其内容，因此没有 PreToolUse hook 为它们触发，包括匹配 `Read` 的 hooks。要阻止特定路径的 `@` 引用，请改用 [`Read` 拒绝规则](/docs/zh-CN/permissions#read-and-edit)。1680 PreToolUse 仅在 Claude 调用工具时运行。您 [在提示中使用 `@` 引用的文件](/docs/zh-CN/common-workflows#reference-files-and-directories) 添加时没有任何工具调用：Claude Code 在构建提示时插入它们的内容，因此没有 PreToolUse hook 为它们触发，包括匹配 `Read` 的 hooks。要阻止特定路径的 `@` 引用，请改用 [`Read` 拒绝规则](/docs/zh-CN/permissions#read-and-edit)。

1691 1681

1692 PreToolUse 也不为 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 触发。1682 PreToolUse 也不为 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 触发。

1693</Warning>1683</Warning>

1702 1692

1703除了 [常见输入字段](#common-input-fields) 外，PreToolUse hooks 接收 `tool_name`、`tool_input` 和 `tool_use_id`。1693除了 [常见输入字段](#common-input-fields) 外，PreToolUse hooks 接收 `tool_name`、`tool_input` 和 `tool_use_id`。

1704 1694

1705对于 [MCP 工具](#match-mcp-tools)，输入还携带 `mcp_server`，一个包含服务器 `name` 和 `source` 的对象，说明服务器定义来自何处。`source` 值包括 `plugin`、`sdk` 和配置范围，如 `user` 和 `project`。[Agent SDK 参考](/docs/zh-CN/agent-sdk/typescript#mcpserverprovenance) 中的 [`McpServerProvenance`](/docs/zh-CN/agent-sdk/typescript#mcpserverprovenance) 列出了所有内容并说明如何处理您不认识的内容。基于 `source` 而不是 `name` 或 `mcp__<server>__` 工具名称前缀做出信任决定。`mcp_server` 字段需要 Claude Code v2.1.274 或更高版本。1695对于 [MCP 工具](#match-mcp-tools)，输入也携带 `mcp_server`，一个包含服务器 `name` 和 `source` 的对象，说明服务器定义来自何处。`source` 值包括 `plugin`、`sdk` 和配置范围如 `user` 和 `project`。Agent SDK 参考中的 [`McpServerProvenance`](/docs/zh-CN/agent-sdk/typescript#mcpserverprovenance) 列出了所有内容并说明如何处理您不认识的内容。基于 `source` 而不是 `name` 或 `mcp__<server>__` 工具名称前缀做出信任决定。`mcp_server` 字段需要 Claude Code v2.1.274 或更高版本。

1706 1696

1707对于文件工具 Write、Edit 和 Read，`tool_input.file_path` 始终是绝对的：1697对于文件工具 `Write`、`Edit` 和 `Read`，`tool_input.file_path` 始终是绝对的：

1708 1698

1709* Claude Code 在 hooks 运行之前扩展 `~` 和相对路径，因此匹配路径的 hook 无法通过 `~` 或相同路径的相对拼写绕过1699* Claude Code 在 hooks 运行之前展开 `~` 和相对路径，因此匹配路径的 hook 无法通过 `~` 或相同路径的相对拼写绕过

1710* 在 Windows 上，路径到达时带有反斜杠分隔符，即使您的 hook 在 Git Bash 下运行，其中 `$PWD` 看起来像 `/c/project`1700* 在 Windows 上，路径到达时带有反斜杠分隔符，即使您的 hook 在 Git Bash 下运行，其中 `$PWD` 看起来像 `/c/project`

1711* 使用正斜杠编写的比较（如 `/src/` 检查）永远不会匹配反斜杠路径，工具调用继续，就像 hook 没有什么要阻止的一样1701* 用正斜杠编写的比较（如 `/src/` 检查）永远不会匹配反斜杠路径，工具调用继续，就像 hook 没有什么要阻止的一样

1712* 在比较之前规范化分隔符：Bash 中的 `FILE_PATH="${FILE_PATH//\\//}"`，或 Python 中的 `file_path.replace("\\", "/")`，然后匹配路径段，如 `/src/`，而不是使用 `^` 锚定，因为路径是绝对的1702* 在比较前规范化分隔符：Bash 中的 `FILE_PATH="${FILE_PATH//\\//}"` 或 Python 中的 `file_path.replace("\\", "/")`，然后匹配路径段如 `/src/` 而不是用 `^` 锚定，因为路径是绝对的

1713 1703

1714Windows 上的 Write 调用传递：1704Windows 上的 `Write` 调用传递：

1715 1705

1716```json theme={null}1706```json theme={null}

1717{1707{

1738| 字段 | 类型 | 示例 | 描述 |1728| 字段 | 类型 | 示例 | 描述 |

1739| :- | :- | :- | :- |1729| :- | :- | :- | :- |

1744 1734

1745当 Bash 命令更改 Git 存储库中的文件时，Claude Code 可以记录更改的内容。当 [`bashEditDiffEnabled`](/docs/zh-CN/settings-reference#basheditdiffenabled) 设置打开记录时，它在每个权限模式中记录更改；该设置的条目说明哪些文件可以设置它。否则它仅在自动模式和 `bypassPermissions` 模式中记录它们，并且仅当 Claude Code 指导 Claude 通过 Bash 编辑文件时。设置 `bashEditDiffEnabled` 为 `false` 以关闭记录。后台命令和只读命令不携带 diff。1735当 Bash 命令更改 Git 存储库中的文件时，Claude Code 可以记录更改的内容。当 [`bashEditDiffEnabled`](/docs/zh-CN/settings-reference#basheditdiffenabled) 设置打开记录时，它在每个权限模式中记录；该设置的条目说明哪些文件可以设置它。否则它仅在自动模式和 `bypassPermissions` 模式中记录，并且仅当 Claude Code 指导 Claude 通过 Bash 编辑文件时。设置 `bashEditDiffEnabled` 为 `false` 以关闭记录。后台命令和只读命令不携带 diff。

1746 1736

1747您的 [PostToolUse hook](#posttooluse) 然后在 `tool_response.bashEditDiff` 中接收更改的文件。列表涵盖命令运行时在存储库下更改的内容。Git 忽略的文件和子模块中的文件不被列出。需要 Claude Code v2.1.269 或更高版本。1737您的 [PostToolUse hook](#posttooluse) 然后在 `tool_response.bashEditDiff` 中接收更改的文件。列表涵盖命令运行时存储库下更改的内容。Git 忽略的文件和子模块中的文件不列出。需要 Claude Code v2.1.269 或更高版本。

1748 1738

1749<Note>1739<Note>

1750 列表是尽力而为的，处于公开测试版。Claude Code 可能会错过更改、包含另一个进程同时更改的文件，或在其大小限制处停止。字段形状可能会改变。使用列表查找要审查的内容，而不是强制执行策略。1740 列表是尽力而为的，处于公开测试版。Claude Code 可能会错过更改、包含另一个进程同时更改的文件或在其大小限制处停止。字段形状可能会改变。使用列表查找要审查的内容，而不是强制执行策略。

1751</Note>1741</Note>

1752 1742

1753`changedFiles` 和 `files` 列出命令更改的内容；其余字段说明该列表的完整性和可靠性。1743`changedFiles` 和 `files` 列出命令更改的内容；其余字段说明该列表的完整性和可靠性。

1756| :- | :- | :- | :- |1746| :- | :- | :- | :- |

1758| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 最多 5 个更改文件的 diffs，用于显示。对于命令添加或删除的文件，`created` 或 `deleted` 为 `true` |1748| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 最多 5 个更改文件的 diffs，用于显示。对于命令添加或删除的文件，`created` 或 `deleted` 为 `true` |

1763 1753

1764<a id="powershell" />1754<a id="powershell" />

1765 1755

1774| 字段 | 类型 | 示例 | 描述 |1764| 字段 | 类型 | 示例 | 描述 |

1775| :- | :- | :- | :- |1765| :- | :- | :- | :- |

1780 1770

1781在检查 shell 命令的 hooks 中匹配 `Bash|PowerShell`，以便它们涵盖两个工具：1771在检查 shell 命令的 hooks 中匹配 `Bash|PowerShell`，以便它们涵盖两个工具：

1782 1772

1783* 在 Windows 上，无论 PowerShell 工具在何处启用，Claude 都将 PowerShell 视为主 shell 并通过它路由 shell 命令。1773* 在 Windows 上，无论 PowerShell 工具在何处启用，Claude 将 PowerShell 视为主 shell 并通过它路由 shell 命令。

1784* 在没有 Git Bash 的 Windows 上，工具自动启用，Claude Code 根本不注册 Bash 工具。1774* 在没有 Git Bash 的 Windows 上，工具自动启用，Claude Code 根本不注册 Bash 工具。

1785* 仅匹配 `Bash` 的 hook 永远不会在那里触发。1775* 仅匹配 `Bash` 的 hook 永远不会在那里触发。

1786 1776

1873 Agent1863 Agent

1874</h5>1864</h5>

1875 1865

1876生成 [子代理](/docs/zh-CN/sub-agents)。1866生成 [子 agent](/docs/zh-CN/sub-agents)。

1877 1867

1878| 字段 | 类型 | 示例 | 描述 |1868| 字段 | 类型 | 示例 | 描述 |

1879| :- | :- | :- | :- |1869| :- | :- | :- | :- |

1884 1874

1885当前台 Agent 调用完成时，您的 [PostToolUse hook](#posttooluse) 在 `tool_response` 中接收子代理的结果和运行遥测。读取这些字段以检查运行；对于跨子代理的令牌和成本汇总，使用 [令牌和成本计数器](/docs/zh-CN/monitoring-usage#token-counter) 过滤到 `query_source` `"subagent"`，因为 `totalTokens` 和 `usage` 仅涵盖最终请求：1875当前台 Agent 调用完成时，您的 [PostToolUse hook](#posttooluse) 在 `tool_response` 中接收子 agent 的结果和运行遥测。读取这些字段以检查运行；对于跨子 agents 的令牌和成本汇总，使用 [令牌和成本计数器](/docs/zh-CN/monitoring-usage#token-counter) 过滤到 `query_source` `"subagent"`，因为 `totalTokens` 和 `usage` 仅涵盖最终请求：

1886 1876

1887| 字段 | 类型 | 示例 | 描述 |1877| 字段 | 类型 | 示例 | 描述 |

1888| :- | :- | :- | :- |1878| :- | :- | :- | :- |

1891| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | 子代理的最终文本块，或对于其报告通过 `SubagentHandback` 的子代理，关于该交接的简短说明代替 |1881| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | 子 agent 的最终文本块，或对于其报告通过 `SubagentHandback` 的子 agent，关于该交接的简短说明代替 |

1897| `usage` | object | `{"input_tokens": 8320, ...}` | 最终 API 请求的每类型令牌分解：`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens` |1887| `usage` | object | `{"input_tokens": 8320, ...}` | 最终 API 请求的每类型令牌分解：`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens` |

1898 1888

1899在 Claude Code v2.1.271 或更高版本上，使用 [`SubagentHandback`](/docs/zh-CN/tools-reference) 工具运行的子代理（Claude Code 在 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 中提供）通过该工具而不是作为文本返回其报告。其 `completed` 结果的 `content` 字段然后携带关于该交接的简短说明，而不是报告本身。要读取报告，匹配 `PreToolUse` 或 `PostToolUse` hook 在 `SubagentHandback` 上并读取 `tool_input.message`。1889在 Claude Code v2.1.271 或更高版本上，使用 [`SubagentHandback`](/docs/zh-CN/tools-reference) 工具运行的子 agent（Claude Code 在 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 中提供）通过该工具而不是作为文本返回其报告。其 `completed` 结果的 `content` 字段然后携带关于该交接的简短说明而不是报告本身。要读取报告，匹配 `PreToolUse` 或 `PostToolUse` hook 在 `SubagentHandback` 上并读取 `tool_input.message`。

1900 1890

1901对于后台子代理，工具在任务移到后台时返回，因此 `tool_response` 不携带使用字段：后台启动立即返回，前台任务在运行中被后台化时返回。它有 `status: "async_launched"`、`agentId`、`description`、`prompt`、`outputFile` 和 `resolvedModel`。1891对于后台子 agents，工具在任务移到后台时返回，因此 `tool_response` 不携带使用字段：后台启动立即返回，前台任务在 Claude Code 在运行中将其后台化时返回。它有 `status: "async_launched"`、`agentId`、`description`、`prompt`、`outputFile` 和 `resolvedModel`。

1902 1892

1903在 `completed` 响应上，`resolvedModel` 命名子代理启动的模型，可能与 `tool_input` 中的 `model` 值不同，例如当 `availableModels` 或另一个覆盖适用时。在 `async_launched` 响应上，`resolvedModel` 命名代理移到后台时使用的模型，因此在该之前发生的交换反映在那里。`modelsUsed` 和后台化时间 `resolvedModel` 行为需要 Claude Code v2.1.212 或更高版本。1893在 `completed` 响应上，`resolvedModel` 命名子 agent 启动的模型，可能与 `tool_input` 中的 `model` 值不同，如当 `availableModels` 或另一个覆盖适用时。在 `async_launched` 响应上，`resolvedModel` 命名 agent 移到后台时使用的模型，因此在后台化之前发生的交换反映在那里。`modelsUsed` 和后台化时间 `resolvedModel` 行为需要 Claude Code v2.1.212 或更高版本。

1904 1894

1905<a id="askuserquestion" />1895<a id="askuserquestion" />

1906 1896

1908 AskUserQuestion1898 AskUserQuestion

1909</h5>1899</h5>

1910 1900

1911向用户提出一到四个多选题。1901向用户提出一到四个多选问题。

1912 1902

1913| 字段 | 类型 | 示例 | 描述 |1903| 字段 | 类型 | 示例 | 描述 |

1914| :- | :- | :- | :- |1904| :- | :- | :- | :- |

1919 ExitPlanMode1909 ExitPlanMode

1920</h5>1910</h5>

1921 1911

1922呈现计划并要求用户在 Claude 离开 [plan mode](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode) 之前批准它。Claude 在调用工具之前将计划写入磁盘上的文件，因此来自模型的文字 `tool_input` 通常为空。Claude Code 在将输入传递给 hooks 之前注入计划内容和文件路径。1912呈现计划并要求用户在 Claude 离开 [plan mode](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode) 之前批准它。Claude 在调用工具之前将计划写入磁盘上的文件，因此来自模型的字面 `tool_input` 通常为空。Claude Code 在将输入传递给 hooks 之前注入计划内容和文件路径。

1923 1913

1924| 字段 | 类型 | 示例 | 描述 |1914| 字段 | 类型 | 示例 | 描述 |

1925| :- | :- | :- | :- |1915| :- | :- | :- | :- |

1928| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | 已弃用。Claude Code 接受该字段但忽略它。在 v2.1.205 之前，它携带 Claude 请求实现计划的基于提示的权限 |1918| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | 已弃用。Claude Code 接受该字段但忽略它。在 v2.1.205 之前，它携带 Claude 请求以实现计划的基于提示的权限 |

1929 1919

1930在 `PostToolUse` 中，`tool_response` 是一个包含 `plan` 和 `filePath` 字段的对象，保持批准的计划，加上内部状态标志。读取 `tool_response.plan` 以获取计划内容，而不是从磁盘重新读取文件。1920在 `PostToolUse` 中，`tool_response` 是一个包含 `plan` 和 `filePath` 字段的对象，保持批准的计划，加上内部状态标志。读取 `tool_response.plan` 以获取计划内容，而不是从磁盘重新读取文件。

1931 1921

1937 1927

1938| 字段 | 描述 |1928| 字段 | 描述 |

1939| :- | :- |1929| :- | :- |

1940| `permissionDecision` | `"allow"` 跳过权限提示，除了 [任何模式自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves) 和对于 `AskUserQuestion` 和 `ExitPlanMode`，它们需要 [`updatedInput` 与其配对](#allow-with-updatedinput)。`"deny"` 防止工具调用。`"ask"` 提示用户确认。`"defer"` 优雅地退出，以便稍后可以恢复工具。[拒绝和询问规则](/docs/zh-CN/permissions#manage-permissions) 仍然被评估，无论 hook 返回什么 |1930| `permissionDecision` | `"allow"` 跳过权限提示，除了 [任何模式自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves) 和 `AskUserQuestion` 和 `ExitPlanMode`，它们需要 [`updatedInput` 与其配对](#allow-with-updatedinput)。`"deny"` 防止工具调用。`"ask"` 提示用户确认。`"defer"` 优雅地退出，以便稍后可以恢复工具。[拒绝和询问规则](/docs/zh-CN/permissions#manage-permissions) 仍然被评估，无论 hook 返回什么 |

1941| `permissionDecisionReason` | 对于 `"allow"` 和 `"ask"`，显示给用户但不显示给 Claude。对于 `"deny"`，显示给 Claude。对于 `"defer"`，被忽略 |1931| `permissionDecisionReason` | 对于 `"ask"`，显示给用户但不显示给 Claude。对于 `"deny"`，显示给 Claude。对于 `"allow"` 和 `"defer"`，仅写入 [调试日志](#debug-hooks) |

1942| `updatedInput` | 在执行前修改工具的输入参数。替换整个输入对象，因此在修改的字段旁边包含未更改的字段。Claude Code 根据您的 hook 返回的输入而不是 Claude 发送的输入评估权限规则和 Bash 命令的 [自动后台资格](/docs/zh-CN/tools-reference#background-commands)。与 `"allow"` 结合以自动批准，或与 `"ask"` 结合以向用户显示修改的输入。对于 `"defer"`，被忽略 |1932| `updatedInput` | 在执行前修改工具的输入参数。替换整个输入对象，因此在修改的输入旁边包含未更改的字段。Claude Code 根据您的 hook 返回的输入而不是 Claude 发送的输入评估权限规则和 Bash 命令的 [自动后台资格](/docs/zh-CN/tools-reference#background-commands)。与 `"allow"` 结合以自动批准，或与 `"ask"` 结合以向用户显示修改的输入。对于 `"defer"`，被忽略 |

1943| `additionalContext` | 与工具结果一起添加到 Claude 上下文的字符串。当 `permissionDecision` 为 `"defer"` 时被忽略。有关详细信息，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |1933| `additionalContext` | 与工具结果一起添加到 Claude 上下文的字符串。当 `permissionDecision` 为 `"defer"` 时被忽略。有关如何传递文本以及放入其中的内容，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |

1944 1934

1945当多个 PreToolUse hooks 返回不同的决策时，优先级为 `deny` > `defer` > `ask` > `allow`。1935当多个 PreToolUse hooks 返回不同的决策时，优先级为 `deny` > `defer` > `ask` > `allow`。

1946 1936

1947通过退出 2 阻止的 hook 路由方式与 `"deny"` 相同：Claude 看到 stderr 消息作为拒绝原因。1937通过退出 2 阻止的 hook 路由方式与 `"deny"` 相同：Claude 看到 stderr 消息作为拒绝原因。

1948 1938

1949当 hook 返回 `"ask"` 时，显示给用户的权限提示包括一个标签，标识 hook 来自何处：`[settings]` 对于来自任何设置文件或 agent frontmatter 的 hook，`[plugin:<name>]` 对于插件的 hook，或 `[skill]` 对于来自 skill frontmatter 的 hook。这帮助用户理解哪个配置源请求确认。1939当 hook 返回 `"ask"` 时，显示给用户的权限提示包含一个标签，标识 hook 来自何处：`[settings]` 对于来自任何设置文件或 agent frontmatter 的 hook，`[plugin:<name>]` 对于插件的 hook，或 `[skill]` 对于来自 skill frontmatter 的 hook。这帮助用户理解哪个配置源请求确认。

1950 1940

1951hook 的 `"ask"` 也在 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 中强制权限提示：分类器仍然可以拒绝工具调用，但它无法静默批准调用。在 v2.1.211 之前，分类器可以批准在 [沙箱](/docs/zh-CN/sandboxing) 外运行的 Bash 命令而不显示 hook 请求的提示；分类器仍然对该命令应用了自己的安全规则，hook `"deny"` 总是被尊重。1941hook 的 `"ask"` 也在 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 中强制权限提示：分类器仍然可以拒绝工具调用，但它无法静默批准调用。在 v2.1.211 之前，分类器可以批准在 [沙箱](/docs/zh-CN/sandboxing) 外运行的 Bash 命令而不显示 hook 请求的提示；分类器仍然对该命令应用了自己的安全规则，hook `"deny"` 总是被尊重。

1952 1942

1966 1956

1967<span id="allow-with-updatedinput" />1957<span id="allow-with-updatedinput" />

1968 1958

1969在 [非交互模式](/docs/zh-CN/headless) 中使用 `-p` 标志，Claude Code 仅在运行有 [权限主机](/docs/zh-CN/headless#turn-off-permission-prompts-in-unattended-runs) 来接收提示时提供 `AskUserQuestion` 和 `ExitPlanMode`，例如 Agent SDK `canUseTool` 回调。这些工具需要用户交互。返回 `permissionDecision: "allow"` 与 `updatedInput` 一起满足该要求：hook 从 stdin 读取工具的输入，通过您自己的 UI 收集答案，并在 `updatedInput` 中返回它，以便工具运行而不提示。仅返回 `"allow"` 对这些工具不充分。对于 `AskUserQuestion`，回显原始 `questions` 数组并添加一个 [`answers`](#askuserquestion) 对象，将每个问题的文本映射到选定的答案。1959在 [非交互模式](/docs/zh-CN/headless) 中使用 `-p` 标志，Claude Code 仅在运行有 [权限主机](/docs/zh-CN/headless#turn-off-permission-prompts-in-unattended-runs) 来接收提示时提供 `AskUserQuestion` 和 `ExitPlanMode`，如 Agent SDK `canUseTool` 回调。这些工具需要用户交互。返回 `permissionDecision: "allow"` 与 `updatedInput` 一起满足该要求：hook 从 stdin 读取工具的输入，通过您自己的 UI 收集答案，并在 `updatedInput` 中返回它，以便工具运行而不提示。仅返回 `"allow"` 对这些工具不充分。对于 `AskUserQuestion`，回显原始 `questions` 数组并添加一个 [`answers`](#askuserquestion) 对象，将每个问题的文本映射到选定的答案。

1970 1960

1971从 v2.1.199 起，一个 MCP 工具，其服务器用 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 标记它，更严格：hook 无法用 `"allow"` 跳过其批准提示，无论是否有 `updatedInput`，因为 Claude Code 无法确认 hook 收集了工具需要的交互。1961从 v2.1.199 起，一个 MCP 工具，其服务器用 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 标记它，更严格：hook 无法用 `"allow"` 跳过其批准提示，无论是否有 `updatedInput`，因为 Claude Code 无法确认 hook 收集了工具需要的交互。

1972 1962

1973<Note>1963<Note>

1974 PreToolUse 之前使用顶级 `decision` 和 `reason` 字段，但这些对此事件已弃用。改用 `hookSpecificOutput.permissionDecision` 和 `hookSpecificOutput.permissionDecisionReason`。已弃用的值 `"approve"` 和 `"block"` 映射到 `"allow"` 和 `"deny"`。PostToolUse 和 Stop 等其他事件继续使用顶级 `decision` 和 `reason` 作为其当前格式。1964 PreToolUse 以前使用顶级 `decision` 和 `reason` 字段，但这些对此事件已弃用。改用 `hookSpecificOutput.permissionDecision` 和 `hookSpecificOutput.permissionDecisionReason`。已弃用的值 `"approve"` 和 `"block"` 映射到 `"allow"` 和 `"deny"` 分别。PostToolUse 和 Stop 等其他事件继续使用顶级 `decision` 和 `reason` 作为其当前格式。

1975</Note>1965</Note>

1976 1966

1977<h4 id="defer-a-tool-call-for-later">1967<h4 id="defer-a-tool-call-for-later">

1978 延迟工具调用以供稍后使用1968 延迟工具调用以供稍后使用

1979</h4>1969</h4>

1980 1970

1981`"defer"` 用于运行 `claude -p` 作为子进程并读取其 JSON 输出的集成，例如 Agent SDK 应用或构建在 Claude Code 之上的自定义 UI。它让该调用进程在工具调用处暂停 Claude，通过其自己的界面收集输入，并从中断处恢复。Claude Code 仅在 [非交互模式](/docs/zh-CN/headless) 中使用 `-p` 标志时尊重此值。在交互式会话中，它记录警告并忽略 hook 结果。1971`"defer"` 用于运行 `claude -p` 作为子进程并读取其 JSON 输出的集成，如 Agent SDK 应用或构建在 Claude Code 之上的自定义 UI。它让该调用进程在工具调用处暂停 Claude，通过其自己的界面收集输入，并从中断处恢复。Claude Code 仅在 [非交互模式](/docs/zh-CN/headless) 中使用 `-p` 标志时尊重此值。在交互式会话中，它记录警告并忽略 hook 结果。

1982 1972

1983`AskUserQuestion` 工具是典型情况：Claude 想问用户什么，但没有终端来回答。`-p` 运行仅在有 [权限主机](/docs/zh-CN/headless#turn-off-permission-prompts-in-unattended-runs) 时提供 `AskUserQuestion`，例如您使用 `--permission-prompt-tool` 传递的 MCP 工具，因此使用一个启动运行。往返工作如下：1973`AskUserQuestion` 工具是典型情况：Claude 想问用户什么，但没有终端来回答。`-p` 运行仅当它有 [权限主机](/docs/zh-CN/headless#turn-off-permission-prompts-in-unattended-runs) 时提供 `AskUserQuestion`，如您使用 `--permission-prompt-tool` 传递的 MCP 工具，因此使用一个启动运行。往返工作如下：

1984 1974

19851. Claude 调用 `AskUserQuestion`。`PreToolUse` hook 触发。19751. Claude 调用 `AskUserQuestion`。`PreToolUse` hook 触发。

19862. hook 返回 `permissionDecision: "defer"`。工具不执行。进程以 `stop_reason: "tool_deferred"` 退出，待处理的工具调用保留在成绩单中。19762. hook 返回 `permissionDecision: "defer"`。工具不执行。进程以 `stop_reason: "tool_deferred"` 退出，待处理的工具调用保留在成绩单中。

2004}1994}

2005```1995```

2006 1996

2007没有超时或重试限制。会话保留在磁盘上，直到您恢复它，受 [`cleanupPeriodDays`](/docs/zh-CN/settings-reference#cleanupperioddays) 保留扫描的约束，默认情况下在 30 天后删除会话文件，遵循 [保留扫描规则](/docs/zh-CN/claude-directory#cleaned-up-automatically)。如果恢复时答案还没准备好，hook 可以再次返回 `"defer"`，进程以相同的方式退出。调用进程通过最终从 hook 返回 `"allow"` 或 `"deny"` 来控制何时打破循环。1997没有超时或重试限制。会话保留在磁盘上直到您恢复它，受 [`cleanupPeriodDays`](/docs/zh-CN/settings-reference#cleanupperioddays) 保留扫描的约束，默认情况下在 30 天后删除会话文件，遵循 [保留扫描规则](/docs/zh-CN/claude-directory#cleaned-up-automatically)。如果恢复时答案还没准备好，hook 可以再次返回 `"defer"`，进程以相同方式退出。调用进程通过最终从 hook 返回 `"allow"` 或 `"deny"` 来控制何时打破循环。

2008 1998

2009`"defer"` 仅在 Claude 在回合中进行单个工具调用时有效。如果 Claude 一次进行多个工具调用，`"defer"` 被忽略并显示警告，工具通过正常权限流程进行。约束存在是因为恢复只能重新运行一个工具：没有办法从批次中延迟一个调用而不留下其他未解决的。1999`"defer"` 仅在 Claude 在回合中进行单个工具调用时有效。如果 Claude 一次进行多个工具调用，`"defer"` 被忽略并带有警告，工具通过正常权限流程进行。约束存在是因为恢复只能重新运行一个工具：没有办法从批次中延迟一个调用而不留下其他未解决的。

2010 2000

2011如果恢复时延迟的工具不再可用，进程以 `stop_reason: "tool_deferred_unavailable"` 和 `is_error: true` 退出，hook 触发前。这发生在提供工具的 MCP 服务器对于恢复的会话未连接时。`deferred_tool_use` 有效负载仍然包含，以便您可以识别哪个工具丢失。2001如果恢复时延迟的工具不再可用，进程以 `stop_reason: "tool_deferred_unavailable"` 和 `is_error: true` 退出，hook 触发前。这发生在为恢复的会话未连接提供工具的 MCP 服务器时。`deferred_tool_use` 有效负载仍然包含，以便您可以识别哪个工具丢失。

2012 2002

2013<Note>2003<Note>

2014 要在 plan mode 中恢复延迟会话，请与 `--resume` 一起传递 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags)，以便 Claude Code 可以呈现计划以供批准。没有它，Claude Code 不会恢复 plan mode。需要 Claude Code v2.1.246 或更高版本。2004 要在 plan mode 中恢复延迟会话，请与 `--resume` 一起传递 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags)，以便 Claude Code 可以呈现计划以供批准。如果您传递某些其他启动标志，恢复的运行不会返回到 plan mode；请参阅 [使用 `-p` 在 plan mode 中恢复](/docs/zh-CN/sessions#resume-in-plan-mode-with-p)。需要 Claude Code v2.1.246 或更高版本。

2015 2005

2016 当您使用 `-p` 恢复时，Claude Code 不会恢复任何其他存储的权限模式。它在新 `claude -p` 运行会启动的权限模式中启动运行，因此如果延迟会话使用了一个，请再次传递 `--permission-mode` 或 `--dangerously-skip-permissions`。当您使用 `claude --resume <session-id>` 恢复而不使用 `-p` 时，Claude Code 恢复存储的权限模式，除了 [恢复时的权限模式](/docs/zh-CN/sessions#permission-mode-on-resume) 中列出的例外。2006 当您使用 `-p` 恢复时，Claude Code 不会恢复任何其他存储的权限模式。它在新 `claude -p` 运行会启动的权限模式中启动运行，因此如果延迟会话使用了一个，请再次传递 `--permission-mode` 或 `--dangerously-skip-permissions`。当您使用 `claude --resume <session-id>` 恢复而不使用 `-p` 时，Claude Code 恢复存储的权限模式，除了 [恢复时的权限模式](/docs/zh-CN/sessions#permission-mode-on-resume) 中列出的例外。

2017</Note>2007</Note>

2020 PermissionRequest2010 PermissionRequest

2021</h3>2011</h3>

2022 2012

2023在 Claude Code 即将要求您获得工具使用权限时运行。在无法显示提示的会话中，例如 [非交互模式](/docs/zh-CN/headless) 中的后台子代理，Claude Code 仍然运行这些 hooks，如果没有 hook 返回决策，它拒绝工具调用。2013在 Claude Code 即将要求您许可使用工具时运行。在无法显示提示的会话中，如 [非交互模式](/docs/zh-CN/headless) 中的后台子 agents，Claude Code 仍然运行这些 hooks，如果没有 hook 返回决策，它拒绝工具调用。

2024使用 [PermissionRequest 决策控制](#permissionrequest-decision-control) 代表用户允许或拒绝。2014使用 [PermissionRequest 决策控制](#permissionrequest-decision-control) 代表用户允许或拒绝。

2025 2015

2026当您需要 Claude 要求使用工具权限时的信号时使用此事件。Claude Code 仅在提示等待约六秒后运行带有 `permission_prompt` 类型的 [Notification](#notification) hook。2016当您需要 Claude 要求许可使用工具的时刻的信号时使用此事件。Claude Code 仅在提示等待约六秒后才运行 [Notification](#notification) hook，带有 `permission_prompt` 类型。

2027 2017

2028Claude Code 不为沙箱命令的 [网络请求](/docs/zh-CN/sandboxing#network-isolation) 运行 PermissionRequest hooks。要获得该提示的信号，请使用 `permission_prompt` 通知类型。2018Claude Code 不为沙箱命令的 [网络请求](/docs/zh-CN/sandboxing#network-isolation) 运行 PermissionRequest hooks。要获得该提示的信号，请使用 `permission_prompt` 通知类型。

2029 2019

2030匹配工具名称，与 PreToolUse 相同的值。2020在工具名称上匹配，与 PreToolUse 相同的值。

2031 2021

2032<h4 id="permissionrequest-input">2022<h4 id="permissionrequest-input">

2033 PermissionRequest 输入2023 PermissionRequest 输入

2034</h4>2024</h4>

2035 2025

2036PermissionRequest hooks 接收 `tool_name` 和 `tool_input` 字段，如 PreToolUse hooks，但没有 `tool_use_id`。对于 MCP 工具，它们也接收 [`mcp_server`](#pretooluse-input) 对象。可选的 `permission_suggestions` 数组包含 Claude Code 为此请求建议的 [权限更新](#permission-update-entries)，例如添加允许规则或更改权限模式。2026PermissionRequest hooks 接收 `tool_name` 和 `tool_input` 字段，如 PreToolUse hooks，但没有 `tool_use_id`。对于 MCP 工具，它们也接收 [`mcp_server`](#pretooluse-input) 对象。可选的 `permission_suggestions` 数组包含 Claude Code 为此请求建议的 [权限更新](#permission-update-entries)，如添加允许规则或更改权限模式。

2037 2027

2038`permission_suggestions` 数组不是您看到的选项的确切列表，因为每个权限对话都构建自己的选项。某些对话（例如文件编辑的对话）根本不读取数组，并从请求本身派生其选项。读取它的对话仍然可以保留一个选项，其建议保留在数组中，例如当 [`allowManagedPermissionRulesOnly`](/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly) 隐藏规则保存选项时。它也可以提供数组中没有建议条目的选项，例如 [**Yes, and switch to auto mode**](/docs/zh-CN/permission-modes#switch-permission-modes)，它直接更改权限模式而不是通过权限更新。2028`permission_suggestions` 数组不是您看到的选项的精确列表，因为每个权限对话构建自己的选项。某些对话（如文件编辑的对话）根本不读取数组，并从请求本身派生其选项。读取它的对话仍然可以保留一个选项，其建议保留在数组中，例如当 [`allowManagedPermissionRulesOnly`](/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly) 隐藏规则保存选项时。它也可以提供没有建议条目的选项，如 [**Yes, and switch to auto mode**](/docs/zh-CN/permission-modes#switch-permission-modes)，它直接更改权限模式而不是通过权限更新。

2039 2029

2040PreToolUse hooks 在每个工具调用之前运行，无论它是否需要权限。PermissionRequest hooks 仅在 Claude Code 即将要求您获得权限时运行，或当它否则会自动拒绝无法提示的调用时。两个事件都不为 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 触发。2030PreToolUse hooks 在每个工具调用之前运行，无论它是否需要权限。PermissionRequest hooks 仅在 Claude Code 即将要求您许可时运行，或当它会以其他方式自动拒绝无法提示的调用时。两个事件都不为 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 触发。

2041 2031

2042```json theme={null}2032```json theme={null}

2043{2033{

2066 PermissionRequest 决策控制2056 PermissionRequest 决策控制

2067</h4>2057</h4>

2068 2058

2069`PermissionRequest` hooks 可以允许或拒绝权限请求。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您的 hook 脚本可以返回一个带有这些事件特定字段的 `decision` 对象：2059`PermissionRequest` hooks 可以允许或拒绝权限请求。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您的 hook 脚本可以返回一个 `decision` 对象，带有这些事件特定的字段：

2070 2060

2071| 字段 | 描述 |2061| 字段 | 描述 |

2072| :- | :- |2062| :- | :- |

2073| `behavior` | `"allow"` 授予权限，`"deny"` 拒绝它。[拒绝和询问规则](/docs/zh-CN/permissions#manage-permissions) 仍然被评估，因此返回 `"allow"` 的 hook 不会覆盖匹配的拒绝规则 |2063| `behavior` | `"allow"` 授予权限，`"deny"` 拒绝它。[拒绝和询问规则](/docs/zh-CN/permissions#manage-permissions) 仍然被评估，因此返回 `"allow"` 的 hook 不会覆盖匹配的拒绝规则 |

2078 2068

2079不带 `decision` 对象退出 2 的 hook 保持权限流程不变，其 stderr 被丢弃。仅 `decision` 对象可以授予或拒绝请求。2069不带 `decision` 对象退出 2 的 hook 保持权限流程不变，其 stderr 被丢弃。仅 `decision` 对象可以授予或拒绝请求。

2080 2070

2096 权限更新条目2086 权限更新条目

2097</h4>2087</h4>

2098 2088

2099`updatedPermissions` 输出字段和 [`permission_suggestions` 输入字段](#permissionrequest-input) 都使用相同的条目对象数组。每个条目有一个 `type` 来确定其他字段，以及一个 `destination` 来控制更改的写入位置。2089`updatedPermissions` 输出字段和 [`permission_suggestions` 输入字段](#permissionrequest-input) 都使用相同的条目对象数组。每个条目有一个 `type` 来确定其他字段，以及一个 `destination` 来控制更改写入的位置。

2100 2090

2101| `type` | 字段 | 效果 |2091| `type` | 字段 | 效果 |

2102| :- | :- | :- |2092| :- | :- | :- |

2109 2099

2110<Note>2100<Note>

2111 `setMode` 与 `bypassPermissions` 仅在您使用已可用的 bypass mode 启动会话时生效：`--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions` 或 [用户、`--settings` 或托管设置](/docs/zh-CN/settings-reference#permissions-defaultmode) 中的 `permissions.defaultMode: "bypassPermissions"`。否则更新是无操作。当 [`permissions.disableBypassPermissionsMode`](/docs/zh-CN/permissions#managed-settings) 禁用模式或会话在 [受限模式](/docs/zh-CN/cli-reference#cli-flags) 中启动时，更新也是无操作。2101 `setMode` 与 `bypassPermissions` 仅在您使用已可用的绕过模式启动会话时生效：`--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions` 或 [用户、`--settings` 或托管设置](/docs/zh-CN/settings-reference#permissions-defaultmode) 中的 `permissions.defaultMode: "bypassPermissions"`。否则更新是无操作。当 [`permissions.disableBypassPermissionsMode`](/docs/zh-CN/permissions#managed-settings) 禁用模式或会话在 [受限模式](/docs/zh-CN/cli-reference#cli-flags) 中启动时，更新也是无操作。

2112 2102

2113 `bypassPermissions` 永远不会作为 `defaultMode` 持久化，无论 `destination` 如何。2103 `bypassPermissions` 永远不会作为 `defaultMode` 持久化，无论 `destination` 如何。

2114</Note>2104</Note>

2130 2120

2131在工具成功完成后立即运行。2121在工具成功完成后立即运行。

2132 2122

2133匹配工具名称，与 PreToolUse 相同的值。2123在工具名称上匹配，与 PreToolUse 相同的值。

2134 2124

2135当工具名称不是正确的过滤器时更广泛地匹配：2125当工具名称不是正确的过滤器时更广泛地匹配：

2136 2126

2137* 要在任何工具成功完成后运行 hook，省略 `matcher` 或将其设置为 `"*"`。您的 hook 然后可以自己发现更改了什么，例如通过运行 `git status --porcelain`，它也列出 `git diff` 错过的未跟踪文件。对于失败的工具调用，在 [PostToolUseFailure](#posttoolusefailure) 下添加相同的 hook。2127* 要在任何工具成功完成后运行 hook，省略 `matcher` 或将其设置为 `"*"`。您的 hook 然后可以自己发现更改了什么，例如通过运行 `git status --porcelain`，它也列出 `git diff` 错过的未跟踪文件。对于失败的工具调用，在 [PostToolUseFailure](#posttoolusefailure) 下添加相同的 hook。

2138* 要在特定文件在磁盘上更改时运行 hook，无论什么写入它，请使用 [FileChanged](#filechanged)。当 `Bash` 命令或 Claude Code 外的进程重写相同文件时，Claude Code 不运行匹配 `Edit|Write` 的 `PostToolUse` hook。2128* 要在特定文件更改时运行 hook，无论什么写入它，请使用 [FileChanged](#filechanged)。当 `Bash` 命令或 Claude Code 外的进程重写同一文件时，Claude Code 不运行匹配 `Edit|Write` 的 `PostToolUse` hook。

2139 2129

2140<h4 id="posttooluse-input">2130<h4 id="posttooluse-input">

2141 PostToolUse 输入2131 PostToolUse 输入

2176 2166

2177| 字段 | 描述 |2167| 字段 | 描述 |

2178| :- | :- |2168| :- | :- |

2182| `classifierContext` | 关于此调用结果的简短说明，用于 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器而不是 Claude。有关详细信息，请参阅 [为自动模式分类器注释结果](#annotate-a-result-for-the-auto-mode-classifier)。需要 Claude Code v2.1.236 或更高版本 |2172| `classifierContext` | 关于此调用结果的简短说明，用于 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器而不是 Claude。有关如何传递文本以及放入其中的内容，请参阅 [为自动模式分类器注释结果](#annotate-a-result-for-the-auto-mode-classifier)。需要 Claude Code v2.1.236 或更高版本 |

2185 2175

2201```2191```

2202 2192

2203<Warning>2193<Warning>

2204 `updatedToolOutput` 仅更改 Claude 看到的内容。工具已经在 hook 触发时运行，因此任何写入的文件、执行的命令或发送的网络请求已经生效。遥测（如 OpenTelemetry 工具跨度和分析事件）也在 hook 运行之前捕获原始输出。要在运行前防止或修改工具调用，请改用 [PreToolUse](#pretooluse) hook。2194 `updatedToolOutput` 仅更改 Claude 看到的内容。工具已经在 hook 触发时运行，因此任何写入的文件、执行的命令或发送的网络请求已经生效。遥测如 OpenTelemetry 工具跨度和分析事件也在 hook 运行之前捕获原始输出。要在运行前防止或修改工具调用，请改用 [PreToolUse](#pretooluse) hook。

2205 2195

2206 替换值必须与工具的输出形状匹配。内置工具返回结构化对象而不是纯字符串。例如，`Bash` 返回一个带有 `stdout`、`stderr`、`interrupted` 和 `isImage` 字段的对象。对于内置工具，与工具的输出模式不匹配的值被忽略，使用原始输出。MCP 工具输出通过而不进行模式验证。剥离 Claude 需要的错误详细信息可能导致它在错误的假设下继续。2196 替换值必须与工具的输出形状匹配。内置工具返回结构化对象而不是纯字符串。例如，`Bash` 返回一个带有 `stdout`、`stderr`、`interrupted` 和 `isImage` 字段的对象。对于内置工具，不与工具的输出模式匹配的值被忽略，使用原始输出。MCP 工具输出通过而不进行模式验证。剥离 Claude 需要的错误详情可能导致它在错误的假设下继续。

2207</Warning>2197</Warning>

2208 2198

2209<h4 id="annotate-a-result-for-the-auto-mode-classifier">2199<h4 id="annotate-a-result-for-the-auto-mode-classifier">

2210 为自动模式分类器注释结果2200 为自动模式分类器注释结果

2211</h4>2201</h4>

2212 2202

2213返回 `classifierContext` 以向 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器而不是 Claude 发送关于工具调用结果的简短说明。分类器 [永远不会接收工具结果本身](/docs/zh-CN/permission-modes#how-the-classifier-evaluates-actions)，因此此字段是告诉它在审查后续操作之前关于调用返回的内容的支持方式。该字段需要 Claude Code v2.1.236 或更高版本。2203返回 `classifierContext` 以向 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器发送关于工具调用结果的简短说明，而不是向 Claude。分类器 [永远不接收工具结果本身](/docs/zh-CN/permission-modes#how-the-classifier-evaluates-actions)，因此此字段是告诉它在审查后续操作之前关于调用返回的内容的支持方式。该字段需要 Claude Code v2.1.236 或更高版本。

2214 2204

2215下面的示例告诉分类器查询的输出来自何处：2205下面的示例告诉分类器查询的输出来自何处：

2216 2206

2226分类器给予说明的权重取决于您配置 hook 的位置：2216分类器给予说明的权重取决于您配置 hook 的位置：

2227 2217

2228* **在 Claude Code 中配置的 Hooks**：对于来自设置文件、插件、skills 和 agent frontmatter 的 hooks，分类器将说明视为未验证的、应用程序提供的上下文。说明永远不会建立用户意图，如果它声称您批准或请求了什么，分类器会根据您在对话中的自己的消息检查该声明2218* **在 Claude Code 中配置的 Hooks**：对于来自设置文件、插件、skills 和 agent frontmatter 的 hooks，分类器将说明视为未验证的、应用程序提供的上下文。说明永远不会建立用户意图，如果它声称您批准或请求了什么，分类器会根据您在对话中的自己的消息检查该声明

2229* **进程内 Agent SDK 回调**：当应用程序嵌入 Claude Code 并将 hook 注册为 [TypeScript SDK 回调](/docs/zh-CN/agent-sdk/hooks) 并在实时会话期间返回说明时，分类器可能会将用户声明中继的说明视为用户意图。这样的声明可以满足分类器会从您发送的消息接受的同意要求，但它永远不会解除您自己的消息也无法解除的阻止。会话恢复后，Claude Code 将恢复的说明视为未验证的上下文。当两个组的 hooks 注释相同的调用时，分类器将组合说明视为未验证2219* **进程内 Agent SDK 回调**：当应用程序嵌入 Claude Code 将 hook 注册为 [TypeScript SDK 回调](/docs/zh-CN/agent-sdk/hooks) 并在实时会话期间返回说明时，分类器可能会将用户语句（在说明中中继）视为用户意图。这样的语句可以满足分类器会接受来自您发送的消息的同意要求，但它永远不会解除您自己的消息也无法解除的阻止。会话恢复后，Claude Code 将恢复的说明视为未验证的上下文。当两个组的 hooks 注释同一调用时，分类器将组合说明视为未验证

2230 2220

2231Claude Code 在传递说明时应用这些限制：2221Claude Code 在传递说明时应用这些限制：

2232 2222

2233* **长度**：Claude Code 将一个工具调用的说明上限为 2,000 个字符，并截断其余部分。上限在响应该调用的每个 hook 中共享2223* **长度**：Claude Code 将一个工具调用的说明上限为 2,000 个字符，并截断其余部分。上限在响应该调用的每个 hook 中共享

2234* **仅同步响应**：Claude Code 忽略 [在后台运行](#run-hooks-in-the-background) 的 hook 响应中的字段，因为该响应在 Claude Code 记录工具结果后到达2224* **仅同步响应**：Claude Code 忽略 [在后台运行](#run-hooks-in-the-background) 的 hook 响应中的字段，因为该响应在 Claude Code 记录工具结果后到达

2235* **分类器不记录的调用**：分类器的成绩单省略只读查找，例如文件读取和搜索。Claude Code 丢弃附加到其中一个调用的说明2225* **分类器不记录的调用**：分类器的成绩单省略只读查找，如文件读取和搜索。Claude Code 丢弃附加到其中一个调用的说明

2236* **与重写的交互**：当说明描述您用 `updatedToolOutput` 替换的输出时，在同一 hook 响应中返回两个字段。如果该重写被拒绝或另一个 hook 的重写替换它，Claude Code 丢弃说明。Claude Code 传递您返回的说明而不重写，即使另一个 hook 重写输出2226* **与重写的交互**：当说明描述您用 `updatedToolOutput` 替换的输出时，在同一 hook 响应中返回两个字段。如果该重写被拒绝或另一个 hook 的重写替换它，Claude Code 丢弃说明。Claude Code 传递您返回的说明而不重写，即使另一个 hook 重写输出

2237 2227

2238<Warning>2228<Warning>

2239 分类器将您放在 `classifierContext` 中的内容读取为来自托管会话的应用程序的信息，因此不要将不受信任的工具输出或第三方文本复制到其中。将说明保持为关于此一个调用的简短断言，例如关于其来源的事实或用户关于它的声明；不要使用该字段传递不相关的消息或事件流。2229 分类器读取您放入 `classifierContext` 的内容作为来自托管会话的应用程序的信息，因此不要将不受信任的工具输出或第三方文本复制到其中。将说明保持为关于此一个调用的简短断言，如关于其来源的事实或关于它的用户语句；不要使用该字段传递不相关的消息或事件流。

2240</Warning>2230</Warning>

2241 2231

2242<h3 id="posttoolusefailure">2232<h3 id="posttoolusefailure">

2243 PostToolUseFailure2233 PostToolUseFailure

2244</h3>2234</h3>

2245 2235

2246在启动执行的工具失败时运行：工具抛出错误，或 MCP 工具返回错误结果。使用此来记录失败、发送警报或向 Claude 提供纠正反馈。2236在启动执行的工具失败时运行：工具抛出错误或 MCP 工具返回错误结果。使用此来记录失败、发送警报或向 Claude 提供纠正反馈。

2247 2237

2248匹配工具名称，与 PreToolUse 相同的值。2238在工具名称上匹配，与 PreToolUse 相同的值。

2249 2239

2250<Note>2240<Note>

2251 此事件不为执行前被拒绝的工具调用触发：未知工具名称、失败模式或工具特定验证的输入，或权限拒绝。验证拒绝作为 `tool_use_error` 结果返回，发生在 hooks 运行之前，因此它们既不触发 `PreToolUse` 也不触发此事件。权限拒绝触发 `PreToolUse` 但不触发此事件；请参阅 [PermissionDenied](#permissiondenied)。2241 此事件不为执行前被拒绝的工具调用触发：未知工具名称、失败模式或工具特定验证的输入，或权限拒绝。验证拒绝作为 `tool_use_error` 结果返回，发生在 hooks 运行之前，因此它们既不触发 `PreToolUse` 也不触发此事件。权限拒绝触发 `PreToolUse` 但不触发此事件；请参阅 [PermissionDenied](#permissiondenied)。

2278 2268

2279| 字段 | 描述 |2269| 字段 | 描述 |

2280| :- | :- |2270| :- | :- |

2284 2274

2285`error` 字符串通常与 Claude 接收的失败工具结果相同的文本。其格式因工具和失败而异。在 `tool_name`、`is_interrupt` 和第一行 `Exit code N` 上键入您的 hook；将字符串的其余部分视为显示文本，而不是稳定格式。2275`error` 字符串通常与 Claude 接收的失败工具结果相同的文本。其格式因工具和失败而异。在 `tool_name`、`is_interrupt` 和第一行 `Exit code N` 上键入您的 hook；将字符串的其余部分视为显示文本，而不是稳定格式。

2286 2276

2287* 对于 Bash 和 PowerShell，运行并退出的命令产生第一行 `Exit code N`，然后是命令产生的任何输出作为一个块，stdout 和 stderr 交错2277* 对于 Bash 和 PowerShell，运行并退出的命令产生第一行 `Exit code N`，然后是命令产生的任何输出作为一个块，stdout 和 stderr 交错

2288* 有效负载也可能携带裸失败消息，没有退出代码行，当 Claude Code 无法启动 shell 进程本身时2278* 有效负载也可能携带裸失败消息，没有退出代码行，当 Claude Code 无法启动 shell 进程本身时

2289* Claude Code 中间截断长字符串，围绕 `... [N characters truncated] ...` 标记，并可以插入自己的行，例如 `Command timed out after 2m 0s`2279* Claude Code 中间截断长字符串，围绕 `... [N characters truncated] ...` 标记，并可以插入自己的行，如 `Command timed out after 2m 0s`

2290 2280

2291<h4 id="posttoolusefailure-decision-control">2281<h4 id="posttoolusefailure-decision-control">

2292 PostToolUseFailure 决策控制2282 PostToolUseFailure 决策控制

2296 2286

2297| 字段 | 描述 |2287| 字段 | 描述 |

2298| :- | :- |2288| :- | :- |

2300 2290

2301```json theme={null}2291```json theme={null}

2302{2292{

2311 PostToolBatch2301 PostToolBatch

2312</h3>2302</h3>

2313 2303

2314在批次中的每个工具调用都已解决后运行一次，在 Claude Code 向模型发送下一个请求之前。`PostToolUse` 每个工具运行一次，这意味着当 Claude 进行并行工具调用时它并发运行。`PostToolBatch` 恰好运行一次，带有完整批次，因此它是注入取决于运行的工具集而不是任何单个工具的上下文的正确位置。此事件没有匹配器。2304在批次中的每个工具调用都已解决后运行一次，在 Claude Code 向模型发送下一个请求之前。`PostToolUse` 每个工具触发一次，这意味着当 Claude 进行并行工具调用时它并发触发。`PostToolBatch` 恰好触发一次，带有完整批次，因此它是注入取决于运行的工具集而不是任何单个工具的上下文的正确位置。此事件没有匹配器。

2315 2305

2316<h4 id="posttoolbatch-input">2306<h4 id="posttoolbatch-input">

2317 PostToolBatch 输入2307 PostToolBatch 输入

2331 "tool_name": "Read",2321 "tool_name": "Read",

2332 "tool_input": {"file_path": "/.../ledger/accounts.py"},2322 "tool_input": {"file_path": "/.../ledger/accounts.py"},

2333 "tool_use_id": "toolu_01...",2323 "tool_use_id": "toolu_01...",

2334 "tool_response": " 1\tfrom __future__ import annotations\n 2\t..."2324 "tool_response": "1\tfrom __future__ import annotations\n2\t..."

2335 },2325 },

2336 {2326 {

2337 "tool_name": "Read",2327 "tool_name": "Read",

2338 "tool_input": {"file_path": "/.../ledger/transactions.py"},2328 "tool_input": {"file_path": "/.../ledger/transactions.py"},

2339 "tool_use_id": "toolu_02...",2329 "tool_use_id": "toolu_02...",

2340 "tool_response": " 1\tfrom __future__ import annotations\n 2\t..."2330 "tool_response": "1\tfrom __future__ import annotations\n2\t..."

2341 }2331 }

2342 ]2332 ]

2343}2333}

2346`tool_response` 包含模型在相应 `tool_result` 块中接收的相同内容。该值是序列化字符串或内容块数组，完全如工具发出的那样。对于 `Read`，这意味着行号前缀文本而不是原始文件内容。响应可能很大，因此仅解析您需要的字段。2336`tool_response` 包含模型在相应 `tool_result` 块中接收的相同内容。该值是序列化字符串或内容块数组，完全如工具发出的那样。对于 `Read`，这意味着行号前缀文本而不是原始文件内容。响应可能很大，因此仅解析您需要的字段。

2347 2337

2348<Note>2338<Note>

2349 `tool_response` 形状与 `PostToolUse` 的不同。`PostToolUse` 传递工具的结构化 `Output` 对象，例如 `Write` 的 `{filePath: "...", type: "create"}`；`PostToolBatch` 传递序列化 `tool_result` 内容模型看到的。2339 `tool_response` 形状与 `PostToolUse` 的不同。`PostToolUse` 传递工具的结构化 `Output` 对象，如 `Write` 的 `{filePath: "...", type: "create"}`；`PostToolBatch` 传递模型看到的序列化 `tool_result` 内容。

2350</Note>2340</Note>

2351 2341

2352<h4 id="posttoolbatch-decision-control">2342<h4 id="posttoolbatch-decision-control">

2357 2347

2358| 字段 | 描述 |2348| 字段 | 描述 |

2359| :- | :- |2349| :- | :- |

2360| `additionalContext` | 在下一个模型调用之前注入一次的上下文字符串。有关传递详细信息、放入其中的内容以及恢复的会话如何处理过去的值，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |2350| `additionalContext` | 在下一个模型调用之前注入一次的上下文字符串。有关传递详情、放入其中的内容以及恢复的会话如何处理过去的值，请参阅 [为 Claude 添加上下文](#add-context-for-claude) |

2361 2351

2362```json theme={null}2352```json theme={null}

2363{2353{

2374 PermissionDenied2364 PermissionDenied

2375</h3>2365</h3>

2376 2366

2377在 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 拒绝工具调用时运行，包括当它拒绝而没有分类器判决时，因为 [独立于自动模式的安全检查拒绝了分类器自己的请求](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action) 或其响应没有解析。此 hook 仅在自动模式中触发：当您手动拒绝权限对话、`PreToolUse` hook 阻止调用或 `deny` 规则匹配时，它不运行。使用它来记录拒绝、调整配置或告诉模型它可能重试工具调用。2367在 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 拒绝工具调用时运行，包括当它拒绝而没有分类器判决时，因为 [与自动模式分开的安全检查拒绝了分类器自己的请求](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action) 或其响应没有解析。此 hook 仅在自动模式中触发：当您手动拒绝权限对话、`PreToolUse` hook 阻止调用或 `deny` 规则匹配时不运行。使用它来记录拒绝、调整配置或告诉模型它可能重试工具调用。

2378 2368

2379匹配工具名称，与 PreToolUse 相同的值。2369在工具名称上匹配，与 PreToolUse 相同的值。

2380 2370

2381<h4 id="permissiondenied-input">2371<h4 id="permissiondenied-input">

2382 PermissionDenied 输入2372 PermissionDenied 输入

2403 2393

2404| 字段 | 描述 |2394| 字段 | 描述 |

2405| :- | :- |2395| :- | :- |

2406| `reason` | 拒绝原因。对于分类器判决，在大多数会话中它命名方括号中的匹配规则，例如 `[Data Exfiltration]`；有关其他形式，请参阅 [审查拒绝](/docs/zh-CN/auto-mode-config#review-denials)。对于 [无判决拒绝](#permissiondenied-decision-control)，它以 `Auto mode could not evaluate this action and is blocking it for safety` 开头。对于拒绝因为分类器模型不可用，它是固定文本 `Classifier unavailable` |2396| `reason` | 拒绝原因。对于分类器判决，在大多数会话中它命名方括号中的匹配规则，如 `[Data Exfiltration]`；有关其他形式，请参阅 [审查拒绝](/docs/zh-CN/auto-mode-config#review-denials)。对于 [无判决拒绝](#permissiondenied-decision-control)，它以 `Auto mode could not evaluate this action and is blocking it for safety` 开头。对于拒绝因为分类器模型不可用，它是固定文本 `Classifier unavailable` |

2407 2397

2408<h4 id="permissiondenied-decision-control">2398<h4 id="permissiondenied-decision-control">

2409 PermissionDenied 决策控制2399 PermissionDenied 决策控制

2410</h4>2400</h4>

2411 2401

2412PermissionDenied hooks 可以告诉模型它可能重试被拒绝的工具调用。返回一个 `hookSpecificOutput.retry` 设置为 `true` 的 JSON 对象：2402PermissionDenied hooks 可以告诉模型它可能重试被拒绝的工具调用。返回一个 JSON 对象，其中 `hookSpecificOutput.retry` 设置为 `true`：

2413 2403

2414```json theme={null}2404```json theme={null}

2415{2405{

2420}2410}

2421```2411```

2422 2412

2423当 `retry` 为 `true` 时，Claude Code 向对话添加一条消息，告诉模型它可能重试工具调用。Claude Code 不反转拒绝本身。如果您的 hook 不返回 JSON，或返回 `retry: false`，拒绝成立，模型接收原始拒绝消息。2413当 `retry` 为 `true` 时，Claude Code 向对话添加一条消息，告诉模型它可能重试工具调用。Claude Code 不反转拒绝本身。如果您的 hook 不返回 JSON 或返回 `retry: false`，拒绝成立，模型接收原始拒绝消息。

2424 2414

2425当分类器对操作 [产生无判决](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action) 时，Claude Code 忽略 `retry: true`：其响应没有解析，或独立于自动模式的安全检查拒绝了分类器自己的请求。对于这些拒绝，Claude Code 已经在拒绝消息中告诉模型是否稍后重试或继续。2415当分类器对操作产生 [无判决](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action) 时，Claude Code 忽略 `retry: true`：其响应没有解析，或与自动模式分开的安全检查拒绝了分类器自己的请求。对于这些拒绝，Claude Code 已经在拒绝消息中告诉模型是否稍后重试或继续。

2426 2416

2427<h3 id="notification">2417<h3 id="notification">

2428 Notification2418 Notification

2429</h3>2419</h3>

2430 2420

2431在 Claude Code 发送通知时运行。匹配通知类型。省略匹配器以为所有通知类型运行 hooks。2421在 Claude Code 发送通知时运行。在通知类型上匹配。省略匹配器以对所有通知类型运行 hooks。

2432 2422

2433即使关闭了桌面通知，您也会接收这些 hook 事件：`preferredNotifChannel` 设置（包括 `notifications_disabled`）仅更改您如何被警告，而不是您的 hook 是否运行。2423您即使关闭桌面通知也接收这些 hook 事件：`preferredNotifChannel` 设置，包括 `notifications_disabled`，仅更改您如何被警报，而不是您的 hook 是否运行。

2434 2424

2435| 匹配器 | 何时触发 |2425| 匹配器 | 何时触发 |

2436| :- | :- |2426| :- | :- |

2444| `agent_needs_input` | 后台会话在 [agent view](/docs/zh-CN/agent-view) 在终端中打开时开始等待您的输入，或当前会话询问您 [agent team](/docs/zh-CN/agent-teams) 队友的终端设置问题，您约六秒没有输入 |2434| `agent_needs_input` | 后台会话在 [agent view](/docs/zh-CN/agent-view) 在终端中打开时开始等待您的输入，或当前会话要求您一个 [agent team](/docs/zh-CN/agent-teams) 队友的终端设置问题，您约六秒没有输入 |

2446| `quota_auto_resume_fired` | Claude Code 在 claude.ai 使用限制暂停它后继续您的任务：在重置时，或更早当您在 Claude Code 中做的事情（例如添加使用额度、升级您的计划或切换模型）使使用可用时，带有 [模型设置异常](/docs/zh-CN/interactive-mode#wait-for-a-usage-limit-to-reset) |2436| `quota_auto_resume_fired` | Claude Code 在 claude.ai 使用限制暂停它后继续您的任务：在重置时，或更早当您在 Claude Code 中做的某事（如添加使用信用、升级您的计划或切换模型）在等待期间使使用可用时，带有 [模型设置异常](/docs/zh-CN/interactive-mode#wait-for-a-usage-limit-to-reset) |

2447| `quota_auto_resume_stale` | claude.ai 使用限制在您的计算机睡眠超过约 30 分钟时重置。Claude Code 等待您按 `Enter` 而不是继续。在更短的睡眠后它继续并改为触发 `quota_auto_resume_fired` |2437| `quota_auto_resume_stale` | claude.ai 使用限制在您的计算机睡眠超过约 30 分钟时重置。Claude Code 等待您按 `Enter` 而不是继续。在更短的睡眠后它继续并改为触发 `quota_auto_resume_fired` |

2448| `quota_auto_resume_disabled` | Claude Code 结束其对 claude.ai 使用限制的等待而不继续您的任务：[`autoContinueAtUsageLimit`](/docs/zh-CN/settings-reference#autocontinueatusagelimit) 关闭或重置在 Claude Code 自己启动的等待期间移动超过 24 小时，继续的任务继续命中限制，或继续在到达模型之前被阻止。当您按 `Esc` 或 `Ctrl+C` 或选择 **Don't continue automatically** 时不触发 |2438| `quota_auto_resume_disabled` | Claude Code 结束其对 claude.ai 使用限制的等待而不继续您的任务：[`autoContinueAtUsageLimit`](/docs/zh-CN/settings-reference#autocontinueatusagelimit) 关闭或重置在 Claude Code 自己启动的等待期间移动超过 24 小时，继续的任务继续命中限制，或继续在到达模型之前被阻止。当您按 `Esc` 或 `Ctrl+C` 或选择 **Don't continue automatically** 时不触发 |

2449 2439

2458<Note>2448<Note>

2459 `permission_prompt`、`idle_prompt`、`elicitation_dialog` 和 `elicitation_url_dialog` 类型与桌面通知共享其时序，因此在终端会话中您仅在您似乎远离终端时看到它们：2449 `permission_prompt`、`idle_prompt`、`elicitation_dialog` 和 `elicitation_url_dialog` 类型与桌面通知共享其时序，因此在终端会话中您仅在您似乎远离终端时看到它们：

2460 2450

2461 * 期望 `permission_prompt` 一旦您约六秒没有输入。计时器在权限提示出现时启动，每次按键推迟它。要在 Claude 要求使用工具权限时立即运行 hook，请改用 [PermissionRequest](#permissionrequest)。2451 * 期望 `permission_prompt` 一旦您约六秒没有输入。计时器在权限提示出现时启动，每次按键推迟它。要在 Claude 要求许可使用工具时立即运行 hook，请改用 [PermissionRequest](#permissionrequest)。

2462 * 期望 `idle_prompt` 约 60 秒后 Claude 完成响应，仅当您自那以后没有输入时。Claude Code 在等待 claude.ai 使用限制重置时不发送 `idle_prompt`。当等待自己结束时，其中一个 `quota_auto_resume_*` 类型触发。2452 * 期望 `idle_prompt` 约 60 秒后 Claude 完成响应，仅当您自那以后没有输入时。Claude Code 在等待 claude.ai 使用限制重置时不发送 `idle_prompt`。当等待自己结束时，其中一个 `quota_auto_resume_*` 类型触发。

2463 * 期望 `elicitation_dialog` 用于引出表单，或 `elicitation_url_dialog` 用于浏览器 URL 请求，一旦您约六秒没有输入。两者共享与 `permission_prompt` 相同的六秒门：计时器在对话出现时启动，每次按键推迟它。2453 * 期望 `elicitation_dialog` 对于引出表单或 `elicitation_url_dialog` 对于浏览器 URL 请求，一旦您约六秒没有输入。两者共享与 `permission_prompt` 相同的六秒门：计时器在对话出现时启动，每次按键推迟它。

2464 2454

2465 权限请求或引出在另一个对话在屏幕上时到达保持相同的六秒门，从请求到达时计时。其通知可以在请求仍然等待打开的对话后面时到达您。2455 权限请求或引出在另一个对话在屏幕上时到达保持相同的六秒门，从请求到达时计时。其通知可以在请求仍在等待打开的对话后面时到达您。

2466</Note>2456</Note>

2467 2457

2468Claude Code 在发送权限请求给 Agent SDK 的 [`canUseTool` 回调](/docs/zh-CN/agent-sdk/user-input) 的会话中以不同方式计时 `permission_prompt`，这是 Claude Desktop 和 VS Code 扩展如何托管 Claude Code 的方式：2458Claude Code 在会话中以不同方式计时 `permission_prompt`，其中它向 Agent SDK 的 [`canUseTool` 回调](/docs/zh-CN/agent-sdk/user-input) 发送权限请求，这是 Claude Desktop 和 VS Code 扩展如何托管 Claude Code 的方式：

2469 2459

2470* 期望 `permission_prompt` 约六秒后 Claude 要求权限。Claude Code 在您输入时不推迟它。2460* 期望 `permission_prompt` 约六秒后 Claude 要求权限。Claude Code 在您输入时不推迟它。

2471* 如果您或 [PermissionRequest](#permissionrequest) hook 更早回答，Claude Code 不运行 `permission_prompt`。2461* 如果您或 [PermissionRequest](#permissionrequest) hook 更早回答，Claude Code 不运行 `permission_prompt`。

2473 2463

2474在 v2.1.233 之前，`permission_prompt` 在这些会话中不触发。2464在 v2.1.233 之前，`permission_prompt` 在这些会话中不触发。

2475 2465

2476使用单独的匹配器根据通知类型运行不同的处理程序。此配置在 Claude 需要权限批准时触发权限特定的警报脚本，以及当 Claude 空闲时触发不同的通知：2466使用单独的匹配器根据通知类型运行不同的处理程序。此配置在 Claude 需要权限批准时触发权限特定的警报脚本，在 Claude 空闲时触发不同的通知：

2477 2467

2478```json theme={null}2468```json theme={null}

2479{2469{

2520}2510}

2521```2511```

2522 2512

2523Notification hooks 无法阻止或修改通知。Claude Code 丢弃它们的 `systemMessage` 和 `continue` 字段，但仍然发出 [`terminalSequence`](#emit-terminal-notifications)，这是桌面通知示例所依赖的。Notification hooks 用于副作用，例如将通知转发到外部服务。2513Notification hooks 无法阻止或修改通知。Claude Code 丢弃它们的 `systemMessage` 和 `continue` 字段，但仍然发出 [`terminalSequence`](#emit-terminal-notifications)，这是桌面通知示例所依赖的。Notification hooks 用于副作用，如将通知转发到外部服务。

2524 2514

2525<h3 id="subagentstart">2515<h3 id="subagentstart">

2526 SubagentStart2516 SubagentStart

2527</h3>2517</h3>

2528 2518

2529在 Claude 使用 Agent 工具生成子代理时运行，当 Claude [恢复子代理](/docs/zh-CN/sub-agents#resume-subagents) 时，以及每次进程内 [agent team](/docs/zh-CN/agent-teams) 队友处理新消息时。支持匹配器以按 agent 类型名称过滤。对于内置 agents，这是 agent 名称，如 `general-purpose`、`Explore` 或 `Plan`。对于 [自定义子代理](/docs/zh-CN/sub-agents)，这是 agent 的 frontmatter 中的 `name` 字段，而不是文件名。2519在 Claude 使用 Agent 工具生成子 agent 时运行，当 Claude [恢复子 agent](/docs/zh-CN/sub-agents#resume-subagents) 时，以及每次进程内 [agent team](/docs/zh-CN/agent-teams) 队友处理新消息时。支持匹配器以按 agent 类型名称过滤。对于内置 agents，这是 agent 名称如 `general-purpose`、`Explore` 或 `Plan`。对于 [自定义子 agents](/docs/zh-CN/sub-agents)，这是 agent 的 frontmatter 中的 `name` 字段，而不是文件名。

2530 2520

2531对于由 [插件](/docs/zh-CN/plugins) 提供的子代理，agent 类型是插件范围的标识符，例如 `my-plugin:reviewer`，而不是裸 frontmatter 名称。冒号将插件范围的名称放在正则表达式路径上，因此用 `^` 和 `$` 锚定匹配器以获得精确匹配：`^my-plugin:reviewer$`。2521对于由 [插件](/docs/zh-CN/plugins/overview) 提供的子 agents，agent 类型是插件范围的标识符，如 `my-plugin:reviewer`，而不是裸 frontmatter 名称。冒号将插件范围的名称放在正则表达式路径上，因此用 `^` 和 `$` 锚定匹配器以获得精确匹配：`^my-plugin:reviewer$`。

2532 2522

2533<h4 id="subagentstart-input">2523<h4 id="subagentstart-input">

2534 SubagentStart 输入2524 SubagentStart 输入

2535</h4>2525</h4>

2536 2526

2537除了 [常见输入字段](#common-input-fields) 外，SubagentStart hooks 接收 `agent_id` 与子代理的唯一标识符和 `agent_type` 与匹配器过滤的 agent 名称。2527除了 [常见输入字段](#common-input-fields) 外，SubagentStart hooks 接收 `agent_id` 与子 agent 的唯一标识符和 `agent_type` 与匹配器过滤的 agent 名称。

2538 2528

2539```json theme={null}2529```json theme={null}

2540{2530{

2547}2537}

2548```2538```

2549 2539

2550SubagentStart hooks 无法阻止子代理创建，但它们可以向子代理注入上下文。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您可以返回：2540SubagentStart hooks 无法阻止子 agent 创建，但它们可以向子 agent 注入上下文。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您可以返回：

2551 2541

2552| 字段 | 描述 |2542| 字段 | 描述 |

2553| :- | :- |2543| :- | :- |

2555 2545

2556```json theme={null}2546```json theme={null}

2557{2547{

2562}2552}

2563```2553```

2564 2554

2565当 hook 再次为同一子代理运行时，Claude Code 仅在子代理的上下文还不包含早期运行副本时注入返回的上下文。在启动时注入的副本保留在位置，保持子代理的 [prompt cache](/docs/zh-CN/prompt-caching#subagents-and-the-cache) 完整。在 [自动压缩](/docs/zh-CN/sub-agents#auto-compaction) 丢弃该副本后，Claude Code 再次注入下一个运行的上下文。2555当 hook 再次为同一子 agent 运行时，Claude Code 仅在子 agent 的上下文还不包含来自早期运行的副本时注入返回的上下文。在启动时注入的副本保留在原位，保持子 agent 的 [prompt cache](/docs/zh-CN/prompt-caching#subagents-and-the-cache) 完整。在 [自动压缩](/docs/zh-CN/sub-agents#auto-compaction) 丢弃该副本后，Claude Code 再次注入下一个运行的上下文。

2566 2556

2567<h3 id="subagentstop">2557<h3 id="subagentstop">

2568 SubagentStop2558 SubagentStop

2569</h3>2559</h3>

2570 2560

2571在 Claude Code 子代理完成响应时运行。匹配 agent 类型，与 SubagentStart 相同的值。2561在 Claude Code 子 agent 完成响应时运行。在 agent 类型上匹配，与 SubagentStart 相同的值。

2572 2562

2573<h4 id="subagentstop-input">2563<h4 id="subagentstop-input">

2574 SubagentStop 输入2564 SubagentStop 输入

2575</h4>2565</h4>

2576 2566

2577除了 [常见输入字段](#common-input-fields) 外，SubagentStop hooks 接收 `stop_hook_active`、`agent_id`、`agent_type`、`agent_transcript_path` 和 `last_assistant_message`。`agent_type` 字段是用于匹配器过滤的值。`transcript_path` 是主会话的成绩单，而 `agent_transcript_path` 是子代理自己的成绩单，存储在嵌套 `subagents/` 文件夹中。`last_assistant_message` 字段包含子代理最终响应的文本内容，因此 hooks 可以访问它而无需解析成绩单文件。2567除了 [常见输入字段](#common-input-fields) 外，SubagentStop hooks 接收 `stop_hook_active`、`agent_id`、`agent_type`、`agent_transcript_path` 和 `last_assistant_message`。`agent_type` 字段是用于匹配器过滤的值。`transcript_path` 是主会话的成绩单，而 `agent_transcript_path` 是子 agent 自己的成绩单，存储在嵌套 `subagents/` 文件夹中。`last_assistant_message` 字段包含子 agent 最终响应的文本内容，因此 hooks 可以访问它而不解析成绩单文件。

2578 2568

2579不是每个 SubagentStop 事件都来自 Claude 生成的子代理。Claude Code 也为其某些自己的功能运行内部 agents，例如 [prompt suggestions](/docs/zh-CN/interactive-mode#prompt-suggestions) 和 [`/btw` side questions](/docs/zh-CN/interactive-mode#side-questions-with-%2Fbtw)，当其中一个完成时 SubagentStop 触发。对于这些事件，`agent_type` 是会话本身运行的 agent 名称，例如使用 [`--agent`](/docs/zh-CN/cli-reference#cli-flags) 或 [`agent` 设置](/docs/zh-CN/settings-reference#agent) 设置的，以及当会话运行时没有一个时的空字符串。2569不是每个 SubagentStop 事件都来自 Claude 生成的子 agent。Claude Code 也为其自己的某些功能运行内部 agents，如 [提示建议](/docs/zh-CN/interactive-mode#prompt-suggestions) 和 [`/btw` 侧问题](/docs/zh-CN/interactive-mode#side-questions-with-%2Fbtw)，当其中一个完成时 SubagentStop 触发。对于这些事件，`agent_type` 是会话本身运行的 agent 名称，如用 [`--agent`](/docs/zh-CN/cli-reference#cli-flags) 或 [`agent` 设置](/docs/zh-CN/settings-reference#agent) 设置的，当会话运行而不带一个时为空字符串。

2580 2570

2581不匹配空 `agent_type` 的命名 agent 类型的 `matcher`。一个其匹配器被省略、`""`、`"*"` 或是匹配空字符串的正则表达式的 hook 也为带有空 `agent_type` 的事件运行。2571命名 agent 类型的 `matcher` 不匹配空 `agent_type`。一个 matcher 被省略、`""`、`"*"` 或是匹配空字符串的正则表达式的 hook 也为带有空 `agent_type` 的事件运行。

2582 2572

2583在 Claude Code v2.1.271 或更高版本上，使用 [`SubagentHandback`](/docs/zh-CN/tools-reference) 工具运行的子代理在停止之前通过该工具传递其报告。`last_assistant_message` 字段然后保持子代理的结束文本（如果有），这不是传递的报告。报告是该调用的 `message` 输入，`PreToolUse` 或 `PostToolUse` hook 匹配 `SubagentHandback` 接收作为 `tool_input.message`。2573在 Claude Code v2.1.271 或更高版本上，使用 [`SubagentHandback`](/docs/zh-CN/tools-reference) 工具运行的子 agent 在它停止之前通过该工具传递其报告。`last_assistant_message` 字段然后保持子 agent 的结束文本（如果有），这不是传递的报告。报告是该调用的 `message` 输入，`PreToolUse` 或 `PostToolUse` hook 匹配 `SubagentHandback` 接收作为 `tool_input.message`。

2584 2574

2585SubagentStop hooks 也接收 [Stop input](#stop-input) 下描述的 `background_tasks` 和 `session_crons` 数组。两个数组都限定于父会话，而不是子代理。2575SubagentStop hooks 也接收 [Stop 输入](#stop-input) 下描述的 `background_tasks` 和 `session_crons` 数组。两个数组都限定于父会话，而不是子 agent。

2586 2576

2587```json theme={null}2577```json theme={null}

2588{2578{

2601}2591}

2602```2592```

2603 2593

2604SubagentStop hooks 使用与 [Stop hooks](#stop-decision-control) 相同的决策控制格式，包括 `hookSpecificOutput.additionalContext`，`hookEventName` 设置为 `"SubagentStop"`，用于保持子代理运行的非错误反馈。返回 `decision: "block"` 与 `reason` 保持子代理运行并将 `reason` 作为其下一个指令传递给子代理。通过退出 2 阻止的 hook 以相同方式传递其 stderr 消息。要在子代理返回后向父会话注入上下文，请改用 [`PostToolUse`](#posttooluse) hook 在 `Agent` 工具上。2594SubagentStop hooks 使用与 [Stop hooks](#stop-decision-control) 相同的决策控制格式，包括 `hookSpecificOutput.additionalContext`，`hookEventName` 设置为 `"SubagentStop"`，用于保持子 agent 运行的非错误反馈。返回 `decision: "block"` 与 `reason` 保持子 agent 运行并将 `reason` 作为其下一个指令传递给子 agent。通过退出 2 阻止的 hook 以相同方式传递其 stderr 消息。要在子 agent 返回后向父会话注入上下文，请改用 `Agent` 工具上的 [`PostToolUse`](#posttooluse) hook。

2605 2595

2606<h3 id="taskcreated">2596<h3 id="taskcreated">

2607 TaskCreated2597 TaskCreated

2609 2599

2610在通过 `TaskCreate` 工具创建任务时运行。使用此来强制命名约定、要求任务描述或防止某些任务被创建。在 [没有 Task 工具的会话](/docs/zh-CN/tools-reference#task-tool-availability) 中，此事件不触发。2600在通过 `TaskCreate` 工具创建任务时运行。使用此来强制命名约定、要求任务描述或防止某些任务被创建。在 [没有 Task 工具的会话](/docs/zh-CN/tools-reference#task-tool-availability) 中，此事件不触发。

2611 2601

2612TaskCreated hooks 不支持匹配器，在每个出现时触发。2602TaskCreated hooks 不支持匹配器，对每个出现触发。

2613 2603

2614<h4 id="taskcreated-input">2604<h4 id="taskcreated-input">

2615 TaskCreated 输入2605 TaskCreated 输入

2643 TaskCreated 决策控制2633 TaskCreated 决策控制

2644</h4>2634</h4>

2645 2635

2646TaskCreated hook 可以通过两种方式阻止创建。无论哪种方式，Claude Code 删除任务并将您的消息作为工具的错误返回给 Claude。Claude Code 忽略此事件的 `continue: false`，Claude 继续工作。2636TaskCreated hook 可以以两种方式阻止创建。任一方式，Claude Code 删除任务并将您的消息返回给 Claude 作为工具的错误。Claude Code 忽略此事件的 `continue: false`，Claude 继续工作。

2647 2637

2648* **退出代码 2**：Claude Code 将 stderr 文本作为消息返回。2638* **退出代码 2**：Claude Code 将 stderr 文本作为消息返回。

2649* **JSON `{"decision": "block", "reason": "..."}`**：Claude Code 将 `reason` 作为消息返回。2639* **JSON `{"decision": "block", "reason": "..."}`**：Claude Code 将 `reason` 作为消息返回。

2669 2659

2670在任务被标记为完成时运行。这在两种情况下触发：当任何 agent 通过 TaskUpdate 工具显式标记任务为完成时，或当 [agent team](/docs/zh-CN/agent-teams) 队友完成其回合与进行中的任务时。使用此来强制完成标准，如通过测试或 lint 检查，然后任务才能关闭。2660在任务被标记为完成时运行。这在两种情况下触发：当任何 agent 通过 TaskUpdate 工具显式标记任务为完成时，或当 [agent team](/docs/zh-CN/agent-teams) 队友完成其回合与进行中的任务时。使用此来强制完成标准，如通过测试或 lint 检查，然后任务才能关闭。

2671 2661

2672TaskCompleted hooks 不支持匹配器，在每个出现时触发。2662TaskCompleted hooks 不支持匹配器，对每个出现触发。

2673 2663

2674<h4 id="taskcompleted-input">2664<h4 id="taskcompleted-input">

2675 TaskCompleted 输入2665 TaskCompleted 输入

2706 2696

2707TaskCompleted hooks 支持两种方式来控制任务完成：2697TaskCompleted hooks 支持两种方式来控制任务完成：

2708 2698

2709* **退出代码 2**：任务未被标记为完成，stderr 消息被反馈给模型作为反馈。2699* **退出代码 2**：任务不被标记为完成，stderr 消息被反馈给模型作为反馈。

2710* **JSON `{"continue": false, "stopReason": "..."}`**：当队友完成其回合触发事件时，完全停止队友，匹配 `Stop` hook 行为。`stopReason` 显示给用户。当 `TaskUpdate` 工具触发事件时，Claude Code 忽略 `continue: false`；退出代码 2 仍然阻止完成。2700* **JSON `{"continue": false, "stopReason": "..."}`**：当队友完成其回合触发事件时，完全停止队友，匹配 `Stop` hook 行为。`stopReason` 显示给用户。当 `TaskUpdate` 工具触发事件时，Claude Code 忽略 `continue: false`；退出代码 2 仍然阻止完成。

2711 2701

2712此示例运行测试并在它们失败时阻止任务完成：2702此示例运行测试并在它们失败时阻止任务完成：

2729 Stop2719 Stop

2730</h3>2720</h3>

2731 2721

2732在主 Claude Code agent 完成响应时运行。如果停止由于用户中断而发生，则不运行。API 错误触发 [StopFailure](#stopfailure)。2722在主 Claude Code agent 完成响应时运行。如果停止由于用户中断而发生，不运行。API 错误触发 [StopFailure](#stopfailure)。

2733 2723

2734<Tip>2724<Tip>

2735 [`/goal`](/docs/zh-CN/goal) 命令是会话范围的基于提示的 Stop hook 的内置快捷方式。当您想让 Claude 继续朝着条件工作而不编写 hook 配置时使用它。2725 [`/goal`](/docs/zh-CN/goal) 命令是会话范围的基于提示的 Stop hook 的内置快捷方式。当您想让 Claude 在不编写 hook 配置的情况下继续朝着条件工作时使用它。

2736</Tip>2726</Tip>

2737 2727

2738<h4 id="stop-input">2728<h4 id="stop-input">

2739 Stop 输入2729 Stop 输入

2740</h4>2730</h4>

2741 2731

2742除了 [常见输入字段](#common-input-fields) 外，Stop hooks 接收 `stop_hook_active`、`last_assistant_message`、`background_tasks` 和 `session_crons`。`stop_hook_active` 字段在 Claude Code 已经作为 stop hook 的结果继续时为 `true`。检查此值或处理成绩单以避免在永远不会解决的条件上阻止。Claude Code 在 8 个连续阻止后覆盖 hook 并结束回合。2732除了 [常见输入字段](#common-input-fields) 外，Stop hooks 接收 `stop_hook_active`、`last_assistant_message`、`background_tasks` 和 `session_crons`。`stop_hook_active` 字段在 Claude Code 已经作为 stop hook 的结果继续时为 `true`。检查此值或处理成绩单以避免在永远不会解决的条件上阻止。Claude Code 应用 8 连续继续上限：在 stop hooks 连续继续回合 8 次后，Claude Code 覆盖下一个阻止并结束回合。要提高上限，设置 [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/zh-CN/env-vars)。

2743 2733

2744`last_assistant_message` 字段包含 Claude 最终响应的文本内容，因此 hooks 可以访问它而无需解析成绩单文件。对于作用于刚完成的回合的 hooks，例如朗读或通知 hooks，使用此字段而不是读取 `transcript_path`：成绩单文件不保证在所有版本的 Stop 时包含最终消息。2734`last_assistant_message` 字段包含 Claude 最终响应的文本内容，因此 hooks 可以访问它而不解析成绩单文件。对于作用于刚完成的回合的 hooks，如朗读或通知 hooks，使用此字段而不是读取 `transcript_path`：成绩单文件不保证在所有版本的 Stop 时包含最终消息。

2745 2735

2746`background_tasks` 和 `session_crons` 数组让 hooks 区分"会话完成"与"会话暂停等待后台工作唤醒它"。当任务注册表可达时两个数组都出现，当没有任何东西在飞行或计划时为空。2736`background_tasks` 和 `session_crons` 数组让 hooks 区分"会话完成"与"会话暂停等待后台工作唤醒它"。当任务注册表可达时两个数组都出现，当没有任何东西在飞行或计划时为空。

2747 2737

2750| 字段 | 描述 |2740| 字段 | 描述 |

2751| :- | :- |2741| :- | :- |

2752| `id` | 任务标识符 |2742| `id` | 任务标识符 |

2753| `type` | 友好的任务类型标签，例如 `shell`、`subagent`、`monitor`、`workflow`、`teammate`、`cloud session` 或 `MCP task`。每个标签标识哪个 Claude Code 功能创建了任务。对于无法识别的类型回退到原始判别式 |2743| `type` | 友好的任务类型标签，如 `shell`、`subagent`、`monitor`、`workflow`、`teammate`、`cloud session` 或 `MCP task`。每个标签标识哪个 Claude Code 功能创建了任务。对于无法识别的类型回退到原始判别式 |

2770 2760

2771此示例显示了一个进行中的 shell 任务和一个循环 cron 的 Stop 输入：2761此示例显示了一个 Stop 输入，带有一个进行中的 shell 任务和一个循环 cron：

2772 2762

2773```json theme={null}2763```json theme={null}

2774{2764{

2809| :- | :- |2799| :- | :- |

2812| `hookSpecificOutput.additionalContext` | 对 Claude 的非错误反馈。对话继续，以便 Claude 可以对其采取行动，但与 `decision: "block"` 不同，它在成绩单中显示为 hook 反馈而不是 hook 错误 |2802| `hookSpecificOutput.additionalContext` | Claude 的非错误反馈。对话继续，以便 Claude 可以作用于它，但与 `decision: "block"` 不同，它在成绩单中显示为 hook 反馈而不是 hook 错误 |

2813 2803

2814通过退出 2 阻止的 hook 路由方式与 `reason` 相同：Claude 接收 stderr 消息作为为什么它应该继续的解释。2804通过退出 2 阻止的 hook 路由方式与 `reason` 相同：Claude 接收 stderr 消息作为为什么它应该继续的解释。

2815 2805

2820}2810}

2821```2811```

2822 2812

2823当 hook 按设计工作并给 Claude 指导时使用 `additionalContext`，例如"在完成前运行测试套件"。它通过与 `decision: "block"` 相同的循环保护保持对话进行，即 `stop_hook_active` 输入和 8 个连续继续上限，但成绩单将其标记为 `Stop hook feedback`，不显示 hook 错误通知：2813当 hook 按设计工作并给 Claude 指导时使用 `additionalContext`，如"在完成前运行测试套件"。它通过与 `decision: "block"` 相同的循环保护保持对话进行，即 `stop_hook_active` 输入和 8 连续继续上限，但成绩单将其标记为 `Stop hook feedback`，不显示 hook 错误通知：

2824 2814

2825```json theme={null}2815```json theme={null}

2826{2816{

2835 StopFailure2825 StopFailure

2836</h3>2826</h3>

2837 2827

2838在回合由于 API 错误而结束时运行，而不是 [Stop](#stop)。Claude Code 忽略 hook 的输出和退出代码，除了 [`terminalSequence`](#emit-terminal-notifications)。使用此来记录失败、发送警报或在 Claude 由于速率限制、身份验证问题或其他 API 错误而无法完成响应时采取恢复操作。2828在回合由于 API 错误而结束时运行，而不是 [Stop](#stop)。Claude Code 忽略 hook 的输出和退出代码，除了 [`terminalSequence`](#emit-terminal-notifications)。使用此来记录失败、发送警报或当 Claude 由于速率限制、身份验证问题或其他 API 错误无法完成响应时采取恢复操作。

2839 2829

2840<h4 id="stopfailure-input">2830<h4 id="stopfailure-input">

2841 StopFailure 输入2831 StopFailure 输入

2846| 字段 | 描述 |2836| 字段 | 描述 |

2847| :- | :- |2837| :- | :- |

2848| `error` | 错误类型：`rate_limit`、`overloaded`、`authentication_failed`、`oauth_org_not_allowed`、`account_on_hold`、`billing_error`、`invalid_request`、`model_not_found`、`server_error`、`max_output_tokens`、`cloud_credential_error` 或 `unknown` |2838| `error` | 错误类型：`rate_limit`、`overloaded`、`authentication_failed`、`oauth_org_not_allowed`、`account_on_hold`、`billing_error`、`invalid_request`、`model_not_found`、`server_error`、`max_output_tokens`、`cloud_credential_error` 或 `unknown` |

2850| `last_assistant_message` | 在对话中显示的呈现错误文本。与 `Stop` 和 `SubagentStop` 不同，其中此字段保持 Claude 的对话输出，对于 `StopFailure` 它包含 API 错误字符串本身，例如 `"API Error: Rate limit reached"` |2840| `last_assistant_message` | 在对话中显示的渲染错误文本。与 `Stop` 和 `SubagentStop` 不同，其中此字段保持 Claude 的对话输出，对于 `StopFailure` 它包含 API 错误字符串本身，如 `"API Error: Rate limit reached"` |

2851 2841

2852```json theme={null}2842```json theme={null}

2853{2843{

2861}2851}

2862```2852```

2863 2853

2864StopFailure hooks 没有决策控制。它们仅为通知和日志记录目的运行。2854StopFailure hooks 没有决策控制。它们仅为通知和日志目的运行。

2865 2855

2866<h3 id="teammateidle">2856<h3 id="teammateidle">

2867 TeammateIdle2857 TeammateIdle

2868</h3>2858</h3>

2869 2859

2870在 [agent team](/docs/zh-CN/agent-teams) 队友完成其回合后即将空闲时运行。使用此来强制质量门，如要求通过 lint 检查或验证输出文件存在。2860在 [agent team](/docs/zh-CN/agent-teams) 队友在完成其回合后即将空闲时运行。使用此来强制质量门，如在队友停止工作前要求通过 lint 检查或验证输出文件存在。

2871 2861

2872TeammateIdle hooks 不支持匹配器，在每个出现时触发。2862TeammateIdle hooks 不支持匹配器，对每个出现触发。

2873 2863

2874<h4 id="teammateidle-input">2864<h4 id="teammateidle-input">

2875 TeammateIdle 输入2865 TeammateIdle 输入

2903* **退出代码 2**：队友接收 stderr 消息作为反馈并继续工作而不是空闲。2893* **退出代码 2**：队友接收 stderr 消息作为反馈并继续工作而不是空闲。

2904* **JSON `{"continue": false, "stopReason": "..."}`**：完全停止队友，匹配 `Stop` hook 行为。`stopReason` 显示给用户。2894* **JSON `{"continue": false, "stopReason": "..."}`**：完全停止队友，匹配 `Stop` hook 行为。`stopReason` 显示给用户。

2905 2895

2906此示例检查构建工件是否存在，然后允许队友空闲：2896此示例检查构建工件存在，然后允许队友空闲：

2907 2897

2908```bash theme={null}2898```bash theme={null}

2909#!/bin/bash2899#!/bin/bash

2922 2912

2923在会话期间配置文件更改时运行。使用此来审计设置更改、强制安全策略或阻止对配置文件的未授权修改。2913在会话期间配置文件更改时运行。使用此来审计设置更改、强制安全策略或阻止对配置文件的未授权修改。

2924 2914

2925Claude Code 在设置文件、托管策略文件或 skill 文件更改时运行 ConfigChange hooks。对于托管策略，它仅在 `managed-settings.json` 或 `managed-settings.d/` 中的文件更改时运行它们。它应用 [服务器托管设置](/docs/zh-CN/server-managed-settings) 和对 macOS 托管首选项或 Windows 注册表策略的更改而不运行它们。在 WSL 上使用 [`wslInheritsWindowsSettings`](/docs/zh-CN/settings-reference#wslinheritswindowssettings)，它也在其策略轮询上应用更改的 Windows 端托管设置文件而不运行它们。2915Claude Code 在设置文件、托管策略文件或 skill 文件更改时运行 ConfigChange hooks。对于托管策略，它仅在 `managed-settings.json` 或 `managed-settings.d/` 中的文件更改时运行它们。它应用 [服务器托管设置](/docs/zh-CN/server-managed-settings) 和对 macOS 托管首选项或 Windows 注册表策略的更改而不运行它们。在带有 [`wslInheritsWindowsSettings`](/docs/zh-CN/settings-reference#wslinheritswindowssettings) 的 WSL 上，它也在其策略轮询上应用更改的 Windows 端托管设置文件而不运行它们。

2926 2916

2927匹配器过滤配置源：2917匹配器在配置源上过滤：

2928 2918

2929| 匹配器 | 何时触发 |2919| 匹配器 | 何时触发 |

2930| :- | :- |2920| :- | :- |

2958 ConfigChange 输入2948 ConfigChange 输入

2959</h4>2949</h4>

2960 2950

2961除了 [常见输入字段](#common-input-fields) 外，ConfigChange hooks 接收 `source` 和可选的 `file_path`。`source` 字段指示哪个配置类型更改，`file_path` 提供修改的特定文件的路径。2951除了 [常见输入字段](#common-input-fields) 外，ConfigChange hooks 接收 `source` 和可选的 `file_path`。`source` 字段指示哪个配置类型更改，`file_path` 提供被修改的特定文件的路径。

2962 2952

2963```json theme={null}2953```json theme={null}

2964{2954{

2980| 字段 | 描述 |2970| 字段 | 描述 |

2981| :- | :- |2971| :- | :- |

2984 2974

2985```json theme={null}2975```json theme={null}

2986{2976{

2989}2979}

2990```2980```

2991 2981

2992`policy_settings` 更改无法被阻止。当机器上的托管设置文件更改时，Hooks 仍然为 `policy_settings` 源触发，因此您可以使用它们来记录这些编辑，但任何阻止决策都被忽略。这确保企业托管设置始终生效。当 [服务器托管设置](/docs/zh-CN/server-managed-settings) 到达或刷新时，Claude Code 不运行 `ConfigChange` hooks。2982`policy_settings` 更改无法被阻止。当机器上的托管设置文件更改时，hooks 仍然为 `policy_settings` 源触发，因此您可以使用它们来记录这些编辑，但任何阻止决策都被忽略。这确保企业托管设置始终生效。当 [服务器托管设置](/docs/zh-CN/server-managed-settings) 到达或刷新时，Claude Code 不运行 `ConfigChange` hooks。

2993 2983

2994Claude Code 从 ConfigChange hook 的 JSON 输出中作用于阻止决策，并丢弃 `systemMessage` 和 `continue`。被阻止的更改不向您或 Claude 显示任何消息，无论您是用 `reason` 还是退出 2 的 stderr 阻止。Claude Code 仅向调试日志写入一行。2984Claude Code 作用于 ConfigChange hook 的 JSON 输出中的阻止决策，并丢弃 `systemMessage` 和 `continue`。被阻止的更改不向您或 Claude 呈现任何消息，无论您是用 `reason` 还是退出 2 的 stderr 阻止。Claude Code 仅向调试日志写入一行。

2995 2985

2996<h3 id="cwdchanged">2986<h3 id="cwdchanged">

2997 CwdChanged2987 CwdChanged

2998</h3>2988</h3>

2999 2989

3000在主对话中的 shell 命令更改工作目录时运行，例如当 Claude 执行 `cd` 命令时。使用此来对目录更改做出反应：重新加载环境变量、激活项目特定的工具链或自动运行设置脚本。与 [FileChanged](#filechanged) 配对，用于 [direnv](https://direnv.net/) 等管理每个目录环境的工具。2990在主对话中的 shell 命令更改工作目录时运行，例如当 Claude 执行 `cd` 命令时。使用此来对目录更改做出反应：重新加载环境变量、激活项目特定的工具链或自动运行设置脚本。与 [FileChanged](#filechanged) 配对，用于像 [direnv](https://direnv.net/) 这样管理每个目录环境的工具。

3001 2991

3002CwdChanged hooks 可以访问 [`CLAUDE_ENV_FILE`](#persist-environment-variables)。写入该文件的变量持久化到后续 Bash 命令，直到下一个 CwdChanged 事件，当 Claude Code 清除它们时。2992CwdChanged hooks 可以访问 [`CLAUDE_ENV_FILE`](#persist-environment-variables)。写入该文件的变量持久化到后续 Bash 命令，直到下一个 CwdChanged 事件，当 Claude Code 清除它们时。

3003 2993

3004CwdChanged 不支持匹配器，在每个出现时触发。2994CwdChanged 不支持匹配器，对每个出现触发。

3005 2995

3006<h4 id="cwdchanged-input">2996<h4 id="cwdchanged-input">

3007 CwdChanged 输入2997 CwdChanged 输入

3024 CwdChanged 输出3014 CwdChanged 输出

3025</h4>3015</h4>

3026 3016

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

3028 3018

3029| 字段 | 描述 |3019| 字段 | 描述 |

3030| :- | :- |3020| :- | :- |

3032 3022

3033CwdChanged hooks 没有决策控制。它们无法阻止目录更改。3023CwdChanged hooks 没有决策控制。它们无法阻止目录更改。

3034 3024

3035Claude Code 从其 JSON 输出读取 `watchPaths` 和 `systemMessage`，并丢弃 `continue`。在交互式会话中，它显示 `systemMessage` 作为简短的终端通知。消息不到达 SDK 消息流。3025Claude Code 从它们的 JSON 输出读取 `watchPaths` 和 `systemMessage`，并丢弃 `continue`。在交互式会话中，它显示 `systemMessage` 作为简短的终端通知。消息不到达 SDK 消息流。

3036 3026

3037<h3 id="directoryadded">3027<h3 id="directoryadded">

3038 DirectoryAdded3028 DirectoryAdded

3039</h3>3029</h3>

3040 3030

3041在您使用 `/add-dir` 命令或 SDK 客户端使用 `register_repo_root` 控制请求在会话中添加工作目录后运行。使用此来准备新添加的存储库，例如安装其依赖。3031在您使用 `/add-dir` 命令在会话中添加工作目录后运行，或在 SDK 客户端使用 `register_repo_root` 控制请求添加一个后运行。使用此来准备新添加的存储库，例如安装其依赖。

3042 3032

3043Claude Code 在以下情况下不触发此事件：3033Claude Code 在以下情况下不触发此事件：

3044 3034

3045* 您使用 `--add-dir` 启动标志传递目录；[SessionStart](#sessionstart) 涵盖这些目录3035* 您使用 `--add-dir` 启动标志传递目录；[SessionStart](#sessionstart) 涵盖这些目录

3046* 您在 `/permissions` Workspace 选项卡上添加目录3036* 您在 `/permissions` Workspace 标签上添加目录

3047* 您添加已经是工作目录或在其中的目录3037* 您添加已经是工作目录或在一个内部的目录

3048 3038

3049Claude Code 在刷新沙箱和权限状态后触发 DirectoryAdded，因此沙箱工具已经在您的 hook 运行时看到新目录。Hook 命令本身运行未沙箱化。3039Claude Code 在刷新沙箱和权限状态后触发 DirectoryAdded，因此沙箱工具已经在您的 hook 运行时看到新目录。Hook 命令本身运行未沙箱化。

3050 3040

3051Claude Code 不等待 hook：添加立即完成，hook 在后台以 600 秒默认超时运行。3041Claude Code 不等待 hook：添加立即完成，hook 在后台以 600 秒默认超时运行。

3052 3042

3053匹配器过滤目录的添加方式：3043匹配器在目录添加方式上过滤：

3054 3044

3055| 匹配器 | 何时触发 |3045| 匹配器 | 何时触发 |

3056| :- | :- |3046| :- | :- |

3066| 字段 | 描述 |3056| 字段 | 描述 |

3067| :- | :- |3057| :- | :- |

3070 3060

3071```json theme={null}3061```json theme={null}

3072{3062{

3079}3069}

3080```3070```

3081 3071

3082DirectoryAdded hooks 没有决策控制。它们无法阻止添加，这在 hook 运行时已经完成。Claude Code 根据源以不同方式处理其 JSON 输出中的 `systemMessage` 和失败输出：3072DirectoryAdded hooks 没有决策控制。它们无法阻止添加，这在 hook 运行时已经完成。Claude Code 从它们的 JSON 输出丢弃 `continue` 字段，并根据源以不同方式呈现其余部分：

3083 3073

3084* `slash_command`：Claude Code 将 hook 的 `systemMessage` 传递给 Claude 作为下一个对话回合的上下文，而不是向您显示它。失败 hooks 的计数出现在成绩单中。完整失败输出进入调试日志3074* `slash_command`：Claude Code 将 hook 的 `systemMessage` 作为上下文传递给 Claude，在下一个对话回合上，而不是向您显示。失败 hooks 的计数出现在成绩单中。完整失败输出进入调试日志

3085* `register_repo_root`：Claude Code 仅将 `systemMessage` 输出和失败输出写入调试日志3075* `register_repo_root`：Claude Code 仅将 `systemMessage` 输出和失败输出写入调试日志

3086 3076

3087<h3 id="filechanged">3077<h3 id="filechanged">

3088 FileChanged3078 FileChanged

3089</h3>3079</h3>

3090 3080

3091在监视的文件在磁盘上更改时运行。Claude Code 使用文件系统监视器检测更改，而不是通过检查工具调用，因此无论什么更改文件，它都运行 hook：Write 或 Edit 工具调用、Claude 使用 Bash 运行的脚本或 Claude Code 外的进程。常见用途是在项目配置文件更改时重新加载环境变量。3081在监视的文件在磁盘上更改时运行。Claude Code 使用文件系统监视器检测更改，而不是通过检查工具调用，因此它运行 hook，无论什么更改了文件：`Edit` 或 `Write` 工具调用、Claude 使用 `Bash` 运行的脚本或 Claude Code 外的进程。常见用途是在项目配置文件更改时重新加载环境变量。

3092 3082

3093此事件的 `matcher` 有两个角色：3083此事件的 `matcher` 有两个角色：

3094 3084

3095* **构建监视列表**：值在 `|` 上分割，每个段注册为工作目录中的文字文件名，因此 `".envrc|.env"` 恰好监视这两个文件。正则表达式模式在这里不有用：像 `^\.env` 这样的值会监视一个字面上命名为 `^\.env` 的文件。3085* **构建监视列表**：值在 `|` 上分割，每个段注册为工作目录中的字面文件名，因此 `".envrc|.env"` 恰好监视这两个文件。正则表达式模式在这里不有用：像 `^\.env` 这样的值会监视字面名为 `^\.env` 的文件。

3096* **过滤哪些 hooks 运行**：当监视的文件更改时，相同的值使用标准 [匹配器规则](#matcher-patterns) 针对更改文件的基名过滤哪些 hook 组运行。3086* **过滤哪些 hooks 运行**：当监视的文件更改时，相同的值使用标准 [匹配器规则](#matcher-patterns) 针对更改文件的基名过滤哪个 hook 组运行。

3097 3087

3098此示例在任何更改后规范化 `data.csv` 中的行结尾，包括 Bash 命令或外部脚本重写文件：3088此示例在任何更改后规范化 `data.csv` 中的行结尾，包括 `Bash` 命令或外部脚本重写文件：

3099 3089

3100```json theme={null}3090```json theme={null}

3101{3091{

3125fi3115fi

3126```3116```

3127 3117

3128要确认 hook 有效，要求 Claude 使用 Bash 命令将 CRLF 行附加到 `data.csv`。Claude Code 运行 hook，文件最终以 LF 结尾。3118要确认 hook 有效，要求 Claude 使用 `Bash` 命令将 CRLF 行附加到 `data.csv`。Claude Code 运行 hook，文件最终以 LF 结尾。

3129 3119

3130要监视您无法提前命名的文件，从 hook 返回 [`watchPaths`](#filechanged-output) 来动态更新监视列表。Claude Code 仅在某些东西命名要监视的文件时启动监视器，因此使用至少命名一个文件的 FileChanged 组为列表播种，或使用 [SessionStart](#sessionstart-decision-control) 或 [CwdChanged](#cwdchanged) hook 返回 `watchPaths`。匹配器仍然过滤当监视的文件更改时哪些 hook 组运行，因此给处理动态路径的组一个省略的匹配器，它匹配每个监视的文件并不向监视列表添加任何内容。`"*"` 匹配器也匹配每个文件，但 Claude Code 像任何其他值一样在监视列表中注册它，作为一个字面上命名为 `*` 的文件。3120要监视您无法提前命名的文件，从 hook 返回 [`watchPaths`](#filechanged-output) 来动态更新监视列表。Claude Code 仅在某个东西命名要监视的文件时启动监视器，因此使用命名至少一个文件的 FileChanged 组为列表播种，或使用 [SessionStart](#sessionstart-decision-control) 或 [CwdChanged](#cwdchanged) hook 返回 `watchPaths`。匹配器仍然过滤当监视的文件更改时哪个 hook 组运行，因此给处理动态路径的组一个省略的匹配器，它匹配每个监视的文件并不向监视列表添加任何内容。`"*"` 匹配器也匹配每个文件，但 Claude Code 像任何其他值一样在监视列表中注册它，作为字面名为 `*` 的文件。

3131 3121

3132FileChanged hooks 可以访问 [`CLAUDE_ENV_FILE`](#persist-environment-variables)。写入该文件的变量持久化到后续 Bash 命令，直到下一个 [CwdChanged](#cwdchanged) 事件，当 Claude Code 清除它们时。3122FileChanged hooks 可以访问 [`CLAUDE_ENV_FILE`](#persist-environment-variables)。写入该文件的变量持久化到后续 Bash 命令，直到下一个 [CwdChanged](#cwdchanged) 事件，当 Claude Code 清除它们时。

3133 3123

3157 FileChanged 输出3147 FileChanged 输出

3158</h4>3148</h4>

3159 3149

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

3161 3151

3162| 字段 | 描述 |3152| 字段 | 描述 |

3163| :- | :- |3153| :- | :- |

3165 3155

3166FileChanged hooks 没有决策控制。它们无法阻止文件更改发生。3156FileChanged hooks 没有决策控制。它们无法阻止文件更改发生。

3167 3157

3168Claude Code 从其 JSON 输出读取 `watchPaths` 和 `systemMessage`，并丢弃 `continue`。在交互式会话中，它显示 `systemMessage` 作为简短的终端通知。消息不到达 SDK 消息流。3158Claude Code 从它们的 JSON 输出读取 `watchPaths` 和 `systemMessage`，并丢弃 `continue`。在交互式会话中，它显示 `systemMessage` 作为简短的终端通知。消息不到达 SDK 消息流。

3169 3159

3170<h3 id="worktreecreate">3160<h3 id="worktreecreate">

3171 WorktreeCreate3161 WorktreeCreate

3172</h3>3162</h3>

3173 3163

3174在创建 worktree 时运行，无论是从 `claude --worktree`、从 [使用 `isolation: "worktree"` 的子代理](/docs/zh-CN/sub-agents#choose-the-subagent-scope)，还是为 Claude Code 在其自己的 worktree 中隔离的 [后台会话](/docs/zh-CN/agent-view#how-file-edits-are-isolated)。默认情况下，Claude Code 使用 `git worktree` 创建隔离的工作副本。配置 WorktreeCreate hook 替换该默认 git 行为，让您使用不同的版本控制系统，如 SVN、Perforce 或 Mercurial。3164在创建 worktree 时运行，无论是从 `claude --worktree`、从 [使用 `isolation: "worktree"` 的子 agent](/docs/zh-CN/sub-agents#choose-the-subagent-scope) 还是为 Claude Code 在其自己的 worktree 中隔离的 [后台会话](/docs/zh-CN/agent-view#how-file-edits-are-isolated)。默认情况下 Claude Code 使用 `git worktree` 创建隔离的工作副本。配置 WorktreeCreate hook 替换该默认 git 行为，让您使用不同的版本控制系统，如 SVN、Perforce 或 Mercurial。

3175 3165

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

3177 3167

3178hook 必须返回创建的 worktree 目录的路径。Claude Code 使用此路径作为隔离会话的工作目录。有关每个 hook 类型如何返回路径，请参阅 [WorktreeCreate 输出](#worktreecreate-output)。3168hook 必须返回创建的 worktree 目录的路径。Claude Code 使用此路径作为隔离会话的工作目录。有关每个 hook 类型如何返回路径，请参阅 [WorktreeCreate 输出](#worktreecreate-output)。

3179 3169

3198}3188}

3199```3189```

3200 3190

3201hook 从 stdin 上的 JSON 输入读取 worktree `name`，检出一个新副本到新目录，并打印目录路径。最后一行的 `echo` 是 Claude Code 读取为 worktree 路径的内容。将任何其他输出重定向到 stderr，以便它不会干扰路径。3191hook 从 stdin 上的 JSON 输入读取 worktree `name`，检出一个新副本到新目录，并打印目录路径。最后一行的 `echo` 是 Claude Code 读取为 worktree 路径的内容。将任何其他输出重定向到 stderr，以便它不干扰路径。

3202 3192

3203<h4 id="worktreecreate-input">3193<h4 id="worktreecreate-input">

3204 WorktreeCreate 输入3194 WorktreeCreate 输入

3229 3219

3230Claude Code 根据 hook 运行的目录解析相对路径，折叠其中的任何 `.` 或 `..` 段。如果结果路径不是 Claude Code 可以进入的目录，会话打印命名路径的错误并以代码 1 退出。3220Claude Code 根据 hook 运行的目录解析相对路径，折叠其中的任何 `.` 或 `..` 段。如果结果路径不是 Claude Code 可以进入的目录，会话打印命名路径的错误并以代码 1 退出。

3231 3221

3232Claude Code 拒绝包含 `.` 或 `..` 段的绝对路径，以及通过存储库根下的符号链接的任何路径，因为提交到存储库的符号链接可能会将 worktree 重定向到其外。错误命名被拒绝的组件。返回不通过存储库内符号链接的规范化路径。在 v2.1.216 之前，worktree 创建遵循 hook 的路径而不进行此筛选。3222Claude Code 拒绝包含 `.` 或 `..` 段的绝对路径，以及通过存储库根下的符号链接的任何路径，因为提交到存储库的符号链接可能将 worktree 重定向到其外。错误命名被拒绝的组件。返回不通过存储库内符号链接的规范化路径。在 v2.1.216 之前，worktree 创建遵循 hook 的路径而不进行此筛选。

3233 3223

3234<h3 id="worktreeremove">3224<h3 id="worktreeremove">

3235 WorktreeRemove3225 WorktreeRemove

3238在删除 worktree 时运行。这是 [WorktreeCreate](#worktreecreate) 的清理对应物。事件在以下情况下触发：3228在删除 worktree 时运行。这是 [WorktreeCreate](#worktreecreate) 的清理对应物。事件在以下情况下触发：

3239 3229

3240* 您退出 `--worktree` 会话并选择删除它3230* 您退出 `--worktree` 会话并选择删除它

3241* 带有 `isolation: "worktree"` 的子代理完成3231* 带有 `isolation: "worktree"` 的子 agent 完成

3242* 您删除 [后台会话](/docs/zh-CN/agent-view#what-deleting-a-session-removes)，其 worktree hook 创建3232* 您删除 [后台会话](/docs/zh-CN/agent-view#what-deleting-a-session-removes)，其 worktree hook 创建

3243 3233

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

3235

3236* **无 WorktreeRemove hook**：当您退出 `--worktree` 会话并选择删除时，Claude Code 回退到您的 WorktreeCreate hook 返回的路径上的 `git worktree remove --force`，因此 git 识别的 worktree 被删除。git 不识别的 worktree，例如您的 hook 使用非 git 版本控制系统创建的，保留在磁盘上。对于删除 [后台会话](/docs/zh-CN/agent-view#what-deleting-a-session-removes) 对 hook 创建的 worktree 做什么，请参阅 agent view 的删除规则。

3237* **Hook 退出 0**：worktree 计为已删除。Claude Code 从 hook 读取其他任何内容，因此确保您的 hook 删除了目录。

3238* **Hook 退出非零**：如果 `worktree_path` 处的目录在之后仍然存在，删除失败，worktree 保留在磁盘上，没有 git 回退。在退出非零前删除目录的 hook 计为已删除。对于失败如何报告，请参阅 [WorktreeRemove 输入](#worktreeremove-input)。

3239

3240Claude Code 永远不删除属于 hook 创建的 worktree 的分支，因为它仅知道您的 WorktreeCreate hook 返回的路径。如果您的 WorktreeCreate hook 创建分支，在您的 WorktreeRemove hook 中删除它。

3241

3242Claude Code 丢弃 WorktreeRemove hook 的 [JSON 输出字段](#json-output)，如 `systemMessage` 和 `continue`。

3245 3243

3246对于后台会话删除，Claude Code 在运行 hook 之前验证存储的 worktree 路径，并拒绝是符号链接或通过存储库根下的符号链接的路径。hook 仅对仍包含文件的 worktree 运行，当您在 [agent view](/docs/zh-CN/agent-view#what-deleting-a-session-removes) 中确认删除时；对于这样的 worktree，[`claude rm`](/docs/zh-CN/agent-view#manage-sessions-from-the-shell) 保持会话和 worktree。在 v2.1.216 之前，hook 在存储的路径上运行而不进行这些检查。3244对于后台会话删除，Claude Code 在运行 hook 之前验证存储的 worktree 路径，并拒绝是符号链接或通过存储库根下的符号链接的路径。hook 仅对仍包含文件的 worktree 运行，当您在 [agent view](/docs/zh-CN/agent-view#what-deleting-a-session-removes) 中确认删除时；对于这样的 worktree，[`claude rm`](/docs/zh-CN/agent-view#manage-sessions-from-the-shell) 保持会话和 worktree。在 v2.1.216 之前，hook 在存储的路径上运行而不进行这些检查。

3247 3245

3280}3278}

3281```3279```

3282 3280

3283WorktreeRemove hook 的退出代码决定结果。当 hook 退出非零且 `worktree_path` 处的目录仍然存在时，删除失败：3281WorktreeRemove hook 的退出代码决定结果。当 hook 退出非零且 `worktree_path` 处的目录在之后仍然存在时，删除失败：

3284 3282

3285* worktree 保留在磁盘上，hook 的命令和 stderr 进入 [调试日志](#debug-hooks)。3283* worktree 保留在磁盘上，hook 的命令和 stderr 进入 [调试日志](#debug-hooks)。

3286* 如果您删除后台会话，会话也保留。[agent view](/docs/zh-CN/agent-view#what-deleting-a-session-removes) 中的拒绝消息报告 hook 如何结束，例如 `exited 1`，引用其 stderr 的开头，并说是否再次删除会话无论如何删除目录。3284* 如果您删除后台会话，会话也保留。[agent view](/docs/zh-CN/agent-view#what-deleting-a-session-removes) 中的拒绝消息报告 hook 如何结束，如 `exited 1`，引用其 stderr 的开头，并说删除会话是否再次删除目录。

3287 3285

3288<h3 id="precompact">3286<h3 id="precompact">

3289 PreCompact3287 PreCompact

3296| 匹配器 | 何时触发 |3294| 匹配器 | 何时触发 |

3297| :- | :- |3295| :- | :- |

3300 3298

3301使用代码 2 退出以阻止压缩。对于手动 `/compact`，stderr 消息显示给用户。您也可以通过返回带有 `"decision": "block"` 的 JSON 来阻止。3299使用代码 2 退出以阻止压缩。对于手动 `/compact`，stderr 消息显示给用户。您也可以通过返回带有 `"decision": "block"` 的 JSON 来阻止。

3302 3300

3303阻止自动压缩根据何时触发有不同的效果。如果压缩在上下文限制之前主动触发，Claude Code 跳过它，对话继续未压缩。如果压缩被触发以从 API 已返回的上下文限制错误恢复，基础错误浮出并且当前请求失败。3301阻止自动压缩有不同的效果，取决于它何时触发。如果压缩在上下文限制之前主动触发，Claude Code 跳过它，对话继续未压缩。如果压缩被触发以从 API 已经返回的上下文限制错误恢复，底层错误浮出并且当前请求失败。

3304 3302

3305Claude Code 丢弃 PreCompact hook 的 `systemMessage` 和 `continue` 字段。3303Claude Code 丢弃 PreCompact hook 的 `systemMessage` 和 `continue` 字段。

3306 3304

3308 PreCompact 输入3306 PreCompact 输入

3309</h4>3307</h4>

3310 3308

3311除了 [常见输入字段](#common-input-fields) 外，PreCompact hooks 接收 `trigger` 和 `custom_instructions`。对于 `manual`，`custom_instructions` 包含用户传递到 `/compact` 的内容，当他们传递什么都不传递时为 `null`。对于 `auto`，`custom_instructions` 为 `null`。3309除了 [常见输入字段](#common-input-fields) 外，PreCompact hooks 接收 `trigger` 和 `custom_instructions`。对于 `manual`，`custom_instructions` 包含用户传递到 `/compact` 的内容，当他们不传递任何内容时为 `null`。对于 `auto`，`custom_instructions` 为 `null`。

3312 3310

3313```json theme={null}3311```json theme={null}

3314{3312{

3332| 匹配器 | 何时触发 |3330| 匹配器 | 何时触发 |

3333| :- | :- |3331| :- | :- |

3336 3334

3337<h4 id="postcompact-input">3335<h4 id="postcompact-input">

3338 PostCompact 输入3336 PostCompact 输入

3357 PreModelSwitch3355 PreModelSwitch

3358</h3>3356</h3>

3359 3357

3360在 Claude Code 应用您或客户端请求的模型切换之前运行。使用它来阻止切换、要求确认或在切换发生之前显示成本。3358在 Claude Code 应用您或客户端请求的模型切换之前运行。使用它来阻止切换、要求确认或在切换发生前显示成本。

3361 3359

3362PreModelSwitch 需要 Claude Code v2.1.251 或更高版本。Claude Code 为这些请求运行它：3360PreModelSwitch 需要 Claude Code v2.1.251 或更高版本。Claude Code 为这些请求运行它：

3363 3361

3367* 当那改变会话的模型时打开 [fast mode](/docs/zh-CN/fast-mode)3365* 当那改变会话的模型时打开 [fast mode](/docs/zh-CN/fast-mode)

3368* 来自 [Agent SDK](/docs/zh-CN/agent-sdk/typescript#query-object) 主机或 [Remote Control](/docs/zh-CN/remote-control) 的 `set_model` 请求，或 `apply_flag_settings` 请求中的模型更改3366* 来自 [Agent SDK](/docs/zh-CN/agent-sdk/typescript#query-object) 主机或 [Remote Control](/docs/zh-CN/remote-control) 的 `set_model` 请求，或 `apply_flag_settings` 请求中的模型更改

3369 3367

3370Claude Code 不为它自己进行的切换运行 PreModelSwitch hooks，例如 [自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback) 或恢复会话时恢复模型。这些更改仅到达 [PostModelSwitch](#postmodelswitch)。3368Claude Code 不为它自己进行的切换运行 PreModelSwitch hooks，如 [自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback) 或恢复会话时恢复模型。这些更改仅到达 [PostModelSwitch](#postmodelswitch)。

3371 3369

3372Claude Code 将匹配器与会话切换到的模型的规范名称进行比较，忽略任何 `[1m]` 后缀。别名（如 `opus`）、日期模型 ID 和提供商特定 ID（如 Amazon Bedrock 模型 ID）都匹配它们解析到的一个规范名称，因此 `claude-opus-5` 涵盖 Opus 5 的每个拼写。3370Claude Code 根据会话切换到的模型的规范名称比较匹配器，忽略任何 `[1m]` 后缀。别名如 `opus`、日期模型 ID 和提供商特定 ID（如 Amazon Bedrock 模型 ID）都匹配它们解析到的一个规范名称，因此 `claude-opus-5` 涵盖 Opus 5 的每个拼写。

3373 3371

3374当 Claude Code 无法确定目标的规范名称时，例如仅您的 [LLM gateway](/docs/zh-CN/llm-gateway) 知道的自定义模型 ID，它运行每个 PreModelSwitch hook，无论匹配器如何。阻止的 hook 应该从其输入检查 `to_model` 而不是仅依赖匹配器。3372当 Claude Code 无法确定目标的规范名称时，例如仅您的 [LLM gateway](/docs/zh-CN/llm-gateway) 知道的自定义模型 ID，它运行每个 PreModelSwitch hook，无论匹配器如何。阻止的 hook 应该从其输入检查 `to_model` 而不是仅依赖匹配器。

3375 3373

3376将匹配器写为精确名称、`|` 分隔列表（如 `claude-opus-4-6|claude-opus-5`）或正则表达式（如 `.*opus.*`）。此示例使用精确名称匹配器，也从 hook 输入检查 `to_model`，因此它拒绝切换到 Opus 4.6，通过退出代码 2，并让任何其他目标通过：3374将匹配器写为精确名称、`|` 分隔列表如 `claude-opus-4-6|claude-opus-5` 或正则表达式如 `.*opus.*`。此示例使用精确名称匹配器并也从 hook 输入检查 `to_model`，因此它拒绝切换到 Opus 4.6，通过退出代码 2，并让任何其他目标通过：

3377 3375

3378<Tabs>3376<Tabs>

3379 <Tab title="macOS/Linux">3377 <Tab title="macOS/Linux">

3399 </Tab>3397 </Tab>

3400 3398

3401 <Tab title="Windows (PowerShell)">3399 <Tab title="Windows (PowerShell)">

3402 注册一个通过 PowerShell 运行脚本的命令 hook：3400 注册一个命令 hook，通过 PowerShell 运行脚本：

3403 3401

3404 ```json theme={null}3402 ```json theme={null}

3405 {3403 {

3445 PreModelSwitch 输入3443 PreModelSwitch 输入

3446</h4>3444</h4>

3447 3445

3448除了 [常见输入字段](#common-input-fields) 外，PreModelSwitch hooks 接收此表中的字段。最后五个描述重新发送对话到新模型的成本，因此 hook 可以在切换发生之前显示该数字。3446除了 [常见输入字段](#common-input-fields) 外，PreModelSwitch hooks 接收此表中的字段。最后五个描述重新发送对话到新模型的成本，因此 hook 可以在切换发生前显示该数字。

3449 3447

3450| 字段 | 类型 | 描述 |3448| 字段 | 类型 | 描述 |

3451| :- | :- | :- |3449| :- | :- | :- |

3455| `source` | string | 请求来自何处：`"command"` 用于 `/model <name>`、`/config` 中的 Model 设置或打开 fast mode；`"picker"` 用于模型选择器；`"sdk"` 用于 `set_model` 请求，或来自 Agent SDK 主机或 Remote Control 的 `apply_flag_settings` 请求中的模型更改 |3453| `source` | string | 请求来自何处：`/model <name>`、`/config` 中的 Model 设置或打开 fast mode 的 `"command"`；模型选择器的 `"picker"`；来自 Agent SDK 主机或 Remote Control 的 `set_model` 请求或 `apply_flag_settings` 请求中的模型更改的 `"sdk"` |

3460| `pricing` | string | Claude Code 如何定价 `estimated_cache_write_usd`：当您的组织配置了它们时在您的组织自己的速率处为 `"configured"`，在列表价格处为 `"catalog"`，或当 `to_model` 没有已知价格且 Claude Code 假设默认速率时为 `"default"` |3458| `pricing` | string | Claude Code 如何定价 `estimated_cache_write_usd`：当您的组织配置了自己的速率时为 `"configured"`，列表价格为 `"catalog"`，或当 `to_model` 没有已知价格且 Claude Code 假设默认速率时为 `"default"` |

3461 3459

3462此示例显示了在运行 Sonnet 5 的会话中 `/model opus` 的输入：3460此示例显示了在运行 Sonnet 5 的会话中 `/model opus` 的输入：

3463 3461

3485 3483

3486`PreModelSwitch` hooks 可以取消切换、要求用户确认或让它继续。退出代码 2 或顶级 `decision: "block"` 取消切换。3484`PreModelSwitch` hooks 可以取消切换、要求用户确认或让它继续。退出代码 2 或顶级 `decision: "block"` 取消切换。

3487 3485

3488为了更精细的控制，在 `hookSpecificOutput` 对象中返回 `permissionDecision` 和 `permissionDecisionReason`，如 [PreToolUse](#pretooluse-decision-control) 上。`PreModelSwitch` 接受 `"allow"`、`"deny"` 和 `"ask"`。它不接受 `"defer"`、`updatedInput` 或 `additionalContext`。下表描述两个字段：3486为了更精细的控制，在 `hookSpecificOutput` 对象中返回 `permissionDecision` 和 `permissionDecisionReason`，如 [PreToolUse](#pretooluse-decision-control)。`PreModelSwitch` 接受 `"allow"`、`"deny"` 和 `"ask"`。它不接受 `"defer"`、`updatedInput` 或 `additionalContext`。下表描述两个字段：

3489 3487

3490| 字段 | 描述 |3488| 字段 | 描述 |

3491| :- | :- |3489| :- | :- |

3492| `permissionDecision` | `"allow"` 继续并跳过 [Claude Code 在 prompt cache 温暖时显示的确认](/docs/zh-CN/prompt-caching#switching-models)。`"deny"` 取消切换。`"ask"` 提示用户确认它 |3490| `permissionDecision` | `"allow"` 继续并跳过 [Claude Code 在 prompt cache 温暖时显示的确认](/docs/zh-CN/prompt-caching#switching-models)。`"deny"` 取消切换。`"ask"` 提示用户确认它 |

3494 3492

3495仅交互式会话中的 `/model` 可以显示 `"ask"` 提示。在每个其他表面，包括带 `-p` 标志的非交互模式、`/config` 和 `set_model` 请求，Claude Code 将 `"ask"` 视为拒绝。3493仅交互式会话中的 `/model` 可以显示 `"ask"` 提示。在每个其他表面，包括带有 `-p` 标志的非交互模式、`/config` 和 `set_model` 请求，Claude Code 将 `"ask"` 视为拒绝。

3496 3494

3497此示例要求用户确认并引用来自 `context_tokens` 的令牌计数：3495此示例要求用户确认并引用来自 `context_tokens` 的令牌计数：

3498 3496

3508 3506

3509当多个 PreModelSwitch hooks 返回不同的决策时，优先级为 `deny` > `ask` > `allow`。3507当多个 PreModelSwitch hooks 返回不同的决策时，优先级为 `deny` > `ask` > `allow`。

3510 3508

3511Claude Code 显示您的 hook 返回的任何 `systemMessage` 给用户，无论决策如何，因此成本报告 hook 可以返回 `{"systemMessage": "..."}` 并退出 0。3509Claude Code 显示用户您的 hook 返回的任何 `systemMessage`，无论决策如何，因此成本报告 hook 可以返回 `{"systemMessage": "..."}` 并退出 0。

3512 3510

3513在其超时前不响应的 PreModelSwitch hook 阻止切换。在 [PreToolUse](#timeouts) 上，相比之下，超时的命令 hook 让工具调用继续。此事件的默认超时为 30 秒。`PreModelSwitch` 仅运行 `command`、`http` 和 `mcp_tool` hooks，因此 `prompt` 和 `agent` 默认不适用。3511在其超时前不响应的 PreModelSwitch hook 阻止切换。在 [PreToolUse](#timeouts) 上，相比之下，超时的命令 hook 让工具调用继续。此事件的默认超时为 30 秒。`PreModelSwitch` 仅运行 `command`、`http` 和 `mcp_tool` hooks，因此 `prompt` 和 `agent` 默认不适用。

3514 3512

3515退出代码不是 0 或 2 且不打印 JSON 决策的 hook 不阻止：Claude Code 显示其 stderr 并应用切换，如 [其他退出代码](#other-exit-codes) 下所述。3513退出代码不是 0 或 2 且打印无 JSON 决策的 hook 不阻止：Claude Code 显示其 stderr 并应用切换，如 [其他退出代码](#other-exit-codes) 下所述。

3516 3514

3517<h3 id="postmodelswitch">3515<h3 id="postmodelswitch">

3518 PostModelSwitch3516 PostModelSwitch

3524 3522

3525* 您或客户端请求的切换3523* 您或客户端请求的切换

3526* [自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)，改变会话的模型3524* [自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)，改变会话的模型

3527* 设置（如 [`opusplan`](/docs/zh-CN/model-config#opusplan-model-setting)）进入或离开 plan mode3525* 设置如 [`opusplan`](/docs/zh-CN/model-config#opusplan-model-setting) 进入或离开 plan mode

3528* Claude Code 恢复会话时恢复模型3526* Claude Code 恢复会话时恢复模型

3529 3527

3530当 [回退模型链](/docs/zh-CN/model-config#fallback-model-chains) 中的模型服务回合时，Claude Code 不运行 PostModelSwitch hooks，因为该替换持续一个回合并保持会话的模型不变。3528当 [回退模型链](/docs/zh-CN/model-config#fallback-model-chains) 中的模型服务回合时，Claude Code 不运行 PostModelSwitch hooks，因为该替换持续一个回合并保持会话的模型不变。

3531 3529

3532匹配器遵循与 [PreModelSwitch](#premodelswitch) 相同的规则：Claude Code 将其与会话切换到的模型的规范名称进行比较。3530匹配器遵循与 [PreModelSwitch](#premodelswitch) 相同的规则：Claude Code 根据会话切换到的模型的规范名称比较它。

3533 3531

3534此示例在会话的模型更改为任何 Opus 模型时添加指导：3532此示例在会话的模型更改为任何 Opus 模型时添加指导：

3535 3533

3551}3549}

3552```3550```

3553 3551

3554要确认 hook 有效，从运行不同模型的会话切换到 Opus 模型，例如从 Sonnet 会话运行 `/model opus`，然后询问 Claude 它对当前模型有什么指导。3552要确认 hook 有效，从运行不同模型的会话切换到 Opus 模型，例如从 Sonnet 会话运行 `/model opus`，然后要求 Claude 关于当前模型的指导。

3555 3553

3556<h4 id="postmodelswitch-input">3554<h4 id="postmodelswitch-input">

3557 PostModelSwitch 输入3555 PostModelSwitch 输入

3558</h4>3556</h4>

3559 3557

3560PostModelSwitch hooks 接收与 [PreModelSwitch](#premodelswitch-input) 相同的字段，`hook_event_name` 设置为 `"PostModelSwitch"` 和两个更多 `source` 值：`"auto"` 用于自动回退或 Claude Code 自己进行的其他更改，以及 `"resume"` 用于恢复会话时恢复的模型。3558PostModelSwitch hooks 接收与 [PreModelSwitch](#premodelswitch-input) 相同的字段，`hook_event_name` 设置为 `"PostModelSwitch"` 和两个更多 `source` 值：`"auto"` 对于自动回退或 Claude Code 自己进行的其他更改，`"resume"` 对于恢复会话时恢复的模型。

3561 3559

3562当 `source` 为 `"auto"` 时，`requested_model` 为 `null`。当 `source` 为 `"resume"` 时，它是 Claude Code 恢复的保存模型设置。3560当 `source` 为 `"auto"` 时，`requested_model` 为 `null`。当 `source` 为 `"resume"` 时，它是 Claude Code 恢复的保存模型设置。

3563 3561

3565 PostModelSwitch 决策控制3563 PostModelSwitch 决策控制

3566</h4>3564</h4>

3567 3565

3568Claude Code 在切换后的下一个请求中获取您的 hook 的 [纯文本 stdout](#exit-code-0) 退出 0，或 JSON 输出中的 `additionalContext`，并将其传递给 Claude。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您可以返回：3566Claude Code 获取您的 hook 在退出 0 时的 [纯文本 stdout](#exit-code-0)，或来自 JSON 输出的 `additionalContext`，并在切换后的下一个请求中将其传递给 Claude。除了所有 hooks 可用的 [JSON 输出字段](#json-output) 外，您可以返回：

3569 3567

3570| 字段 | 描述 |3568| 字段 | 描述 |

3571| :- | :- |3569| :- | :- |

3573 3571

3574如果 hook 在您发送下一个提示后五秒内未完成，Claude Code 发送该请求而不输出，并将其附加到以下请求。如果模型在下一个请求之前更改多次，Claude Code 仅传递最后一个切换目标模型的输出。3572如果 hook 在您发送下一个提示后五秒内未完成，Claude Code 发送该请求而不输出，并将其附加到以下请求。如果模型在下一个请求之前更改多次，Claude Code 仅传递最后一个切换目标模型的输出。

3575 3573

3608 3606

3609SessionEnd hooks 没有决策控制。它们无法阻止会话终止，但可以执行清理任务。Claude Code 丢弃它们的 [JSON 输出字段](#json-output)，如 `systemMessage`。3607SessionEnd hooks 没有决策控制。它们无法阻止会话终止，但可以执行清理任务。Claude Code 丢弃它们的 [JSON 输出字段](#json-output)，如 `systemMessage`。

3610 3608

3611SessionEnd hooks 的默认超时为 1.5 秒。当您退出、运行 `/clear` 或使用交互式 `/resume` 切换会话时适用。您可以通过两种方式给 hook 更多时间：3609SessionEnd hooks 的默认超时为 1.5 秒。它在您退出、运行 `/clear` 或使用交互式 `/resume` 切换会话时适用。您可以通过两种方式给 hook 更多时间：

3612 3610

3613* **每个 hook `timeout`**：在该 hook 的配置中设置 `timeout`。整体预算自动上升以匹配您设置文件中最高的每个 hook `timeout`，最多 60 秒。如果您以这种方式提高预算，没有自己的 `timeout` 的 hook 仍然保持默认值。在插件提供的 hooks 上设置的超时不提高预算。3611* **每个 hook `timeout`**：在该 hook 的配置中设置 `timeout`。总体预算自动上升以匹配您的设置文件中最高的每个 hook `timeout`，最多 60 秒。如果您以这种方式提高预算，没有自己的 `timeout` 的 hook 仍然保持默认。在插件提供的 hooks 上设置的超时不提高预算。

3614* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**：以毫秒为单位设置此环境变量以显式覆盖预算。您设置的值也成为每个没有自己的 `timeout` 的 hook 的超时。3612* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**：设置此环境变量（毫秒）以显式覆盖预算。您设置的值也成为每个没有自己的 `timeout` 的 hook 的超时。

3615 3613

3616此示例将预算设置为 5 秒：3614此示例将预算设置为 5 秒：

3617 3615

3619CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude3617CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

3620```3618```

3621 3619

3622在 v2.1.268 之前，`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` 仅提高整体预算，没有自己的 `timeout` 的 hook 在 1.5 秒后仍然被取消。3620在 v2.1.268 之前，`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` 仅提高总体预算，没有自己的 `timeout` 的 hook 仍然在 1.5 秒后被取消。

3623 3621

3624<h3 id="elicitation">3622<h3 id="elicitation">

3625 Elicitation3623 Elicitation

3627 3625

3628在 MCP 服务器请求用户输入中任务时运行。默认情况下，Claude Code 显示交互式对话供用户响应。Hooks 可以拦截此请求并以编程方式响应，完全跳过对话。3626在 MCP 服务器请求用户输入中任务时运行。默认情况下，Claude Code 显示交互式对话供用户响应。Hooks 可以拦截此请求并以编程方式响应，完全跳过对话。

3629 3627

3630匹配器字段与 MCP 服务器名称匹配。3628匹配器字段根据 MCP 服务器名称匹配。

3631 3629

3632<h4 id="elicitation-input">3630<h4 id="elicitation-input">

3633 Elicitation 输入3631 Elicitation 输入

3695 3693

3696退出代码 2 拒绝引出。Claude Code 不在任何地方显示您的 stderr 消息。3694退出代码 2 拒绝引出。Claude Code 不在任何地方显示您的 stderr 消息。

3697 3695

3698Claude Code 从 Elicitation hook 的 JSON 输出中作用于 `hookSpecificOutput`，并丢弃 `systemMessage` 和 `continue`。3696Claude Code 作用于 Elicitation hook 的 JSON 输出中的 `hookSpecificOutput` 并丢弃 `systemMessage` 和 `continue`。

3699 3697

3700<h3 id="elicitationresult">3698<h3 id="elicitationresult">

3701 ElicitationResult3699 ElicitationResult

3703 3701

3704在用户响应 MCP 引出后运行。Hooks 可以观察、修改或阻止响应，然后将其发送回 MCP 服务器。3702在用户响应 MCP 引出后运行。Hooks 可以观察、修改或阻止响应，然后将其发送回 MCP 服务器。

3705 3703

3706匹配器字段与 MCP 服务器名称匹配。3704匹配器字段根据 MCP 服务器名称匹配。

3707 3705

3708<h4 id="elicitationresult-input">3706<h4 id="elicitationresult-input">

3709 ElicitationResult 输入3707 ElicitationResult 输入

3748 3746

3749退出代码 2 阻止响应，将有效操作更改为 `decline`。Claude Code 不在任何地方显示您的 stderr 消息。3747退出代码 2 阻止响应，将有效操作更改为 `decline`。Claude Code 不在任何地方显示您的 stderr 消息。

3750 3748

3751Claude Code 从 ElicitationResult hook 的 JSON 输出中作用于 `hookSpecificOutput`，并丢弃 `systemMessage` 和 `continue`。3749Claude Code 作用于 ElicitationResult hook 的 JSON 输出中的 `hookSpecificOutput` 并丢弃 `systemMessage` 和 `continue`。

3752 3750

3753<h2 id="prompt-based-hooks">3751<h2 id="prompt-based-hooks">

3754 基于提示的 hooks3752 基于提示的 hooks

3802 3800

3803基于提示的 hooks 不执行 Bash 命令，而是：3801基于提示的 hooks 不执行 Bash 命令，而是：

3804 3802

38051. 将 hook 输入和您的提示发送到 Claude 模型，默认为 Haiku38031. 将 hook 输入和您的提示发送到 Claude 模型，默认为 Claude Code 用于[后台功能](/docs/zh-CN/costs#background-token-usage)的模型

38062. LLM 使用包含决定的结构化 JSON 响应38042. LLM 使用包含决定的结构化 JSON 响应

38073. Claude Code 自动处理决定38053. Claude Code 自动处理决定

3808 3806

3835| :- | :- | :- |3833| :- | :- | :- |

3836| `type` | 是 | 必须是 `"prompt"` |3834| `type` | 是 | 必须是 `"prompt"` |

3837| `prompt` | 是 | 要发送给 LLM 的提示文本。使用 `$ARGUMENTS` 作为 hook 输入 JSON 的占位符。如果 `$ARGUMENTS` 不存在，输入 JSON 被追加到提示 |3835| `prompt` | 是 | 要发送给 LLM 的提示文本。使用 `$ARGUMENTS` 作为 hook 输入 JSON 的占位符。如果 `$ARGUMENTS` 不存在，输入 JSON 被追加到提示 |

3838| `model` | 否 | 用于评估的模型。默认为快速模型 |3836| `model` | 否 | 用于评估的模型。默认为 Claude Code 用于[后台功能](/docs/zh-CN/costs#background-token-usage)的模型 |

3839| `timeout` | 否 | 超时（秒）。默认值：30 |3837| `timeout` | 否 | 超时（秒）。默认值：30 |

3840| `continueOnBlock` | 否 | 在适用的事件上，`true` 将 `ok: false` 原因反馈给 Claude 并继续而不是结束转轮。默认值：`false`。有关每个事件的行为，请参阅[响应架构](#response-schema) |3838| `continueOnBlock` | 否 | 在适用的事件上，`true` 将 `ok: false` 原因反馈给 Claude 并继续而不是结束转轮。默认值：`false`。有关每个事件的行为，请参阅[响应架构](#response-schema) |

3841 3839

hooks-guide.md +3 −3

Details

538每个 hook 都有一个 `type` 来确定它如何运行。大多数 hooks 使用 `"type": "command"`，它运行 shell 命令。还有四种其他类型可用：538每个 hook 都有一个 `type` 来确定它如何运行。大多数 hooks 使用 `"type": "command"`，它运行 shell 命令。还有四种其他类型可用：

539 539

540* `"type": "http"`：将事件数据 POST 到 URL。请参阅 [HTTP hooks](#http-hooks)。540* `"type": "http"`：将事件数据 POST 到 URL。请参阅 [HTTP hooks](#http-hooks)。

541* `"type": "mcp_tool"`：在已连接的 MCP 服务器上调用工具。请参阅 [MCP tool hooks](/docs/zh-CN/hooks#mcp-tool-hook-fields)。541* `"type": "mcp_tool"`：在已配置的 MCP 服务器上调用工具。请参阅 [MCP tool hooks](/docs/zh-CN/hooks#mcp-tool-hook-fields)。

542* `"type": "prompt"`：单轮 LLM 评估。请参阅 [Prompt-based hooks](#prompt-based-hooks)。542* `"type": "prompt"`：单轮 LLM 评估。请参阅 [Prompt-based hooks](#prompt-based-hooks)。

543* `"type": "agent"`：具有工具访问权限的多轮验证。Agent hooks 是实验性的，可能会改变。请参阅 [Agent-based hooks](#agent-based-hooks)。543* `"type": "agent"`：具有工具访问权限的多轮验证。Agent hooks 是实验性的，可能会改变。请参阅 [Agent-based hooks](#agent-based-hooks)。

544 544

880 基于提示的 hooks880 基于提示的 hooks

881</h2>881</h2>

882 882

883对于需要判断而不是确定性规则的决策，使用 `type: "prompt"` hooks。Claude Code 不运行 shell 命令，而是将你的提示和 hook 的输入数据发送到 Claude 模型（默认为 Haiku）来做出决策。如果你需要更多功能，可以使用 `model` 字段指定不同的模型。883对于需要判断而不是确定性规则的决策，使用 `type: "prompt"` hooks。Claude Code 不运行 shell 命令，而是将你的提示和 hook 的输入数据发送到 Claude 模型来做出决策。如果你需要更多功能，可以使用 `model` 字段指定不同的模型。

884 884

885模型的唯一工作是返回其决策作为 JSON：885模型的唯一工作是返回其决策作为 JSON：

886 886

995 995

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

997 997

998* 命令 hooks 仅通过 stdout、stderr 和退出代码通信。它们无法触发 `/` 命令或工具调用。通过 `additionalContext` 返回的文本被注入为 Claude 作为纯文本读取的系统提醒。HTTP hooks 改为通过响应体通信。998* 命令 hooks 仅通过 stdout、stderr 和退出代码通信。它们无法触发 `/` 命令或工具调用。通过 `additionalContext` 返回的文本被注入为 Claude 作为纯文本读取的[系统提醒](/docs/zh-CN/glossary#system-reminder)。HTTP hooks 改为通过响应体通信。

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

1000 * `command`、`http`、`mcp_tool`：10 分钟。Claude Code 对 `UserPromptSubmit`、`PreModelSwitch` 和 `PostModelSwitch` hooks 将此默认值降低到 30 秒，对 `MessageDisplay` 降低到 10 秒。1000 * `command`、`http`、`mcp_tool`：10 分钟。Claude Code 对 `UserPromptSubmit`、`PreModelSwitch` 和 `PostModelSwitch` hooks 将此默认值降低到 30 秒，对 `MessageDisplay` 降低到 10 秒。

1001 * `prompt`：30 秒。1001 * `prompt`：30 秒。

how-claude-code-works.md +15 −2

Details

144 144

145有关交互式演练，了解什么加载以及何时加载，请参阅[探索上下文窗口](/docs/zh-CN/context-window)。145有关交互式演练，了解什么加载以及何时加载，请参阅[探索上下文窗口](/docs/zh-CN/context-window)。

146 146

147<h4 id="context-claude-code-adds-on-its-own">

148 Claude Code 自己添加的上下文

149</h4>

150

151如果 Claude 遵循您没有编写的规则，例如向提交添加 `Co-Authored-By` 预告片，该规则可能来自[系统提醒](/docs/zh-CN/glossary#system-reminder)。当您工作时，Claude Code 会在您的消息旁边向对话添加自己的上下文：

152

153* 您的 CLAUDE.md 文件

154* 您的[输出样式](/docs/zh-CN/output-styles)的说明

155* 当 Claude 之前读取的文件在磁盘上更改时的注记

156* 提交和拉取请求的归属行

157

158要更改或删除归属行，请设置 [`attribution`](/docs/zh-CN/settings-reference#attribution)。要删除 Claude Code 的内置提交和拉取请求说明，请将 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions) 设置为 `false`。有关其他开关，请参阅[关闭您的代理替换的上下文](/docs/zh-CN/agent-sdk/modifying-system-prompts#turn-off-the-context-your-agent-replaces)。

159

147<h4 id="when-context-fills-up">160<h4 id="when-context-fills-up">

148 当上下文填满时161 当上下文填满时

149</h4>162</h4>

188 201

189选择一个权限模式来设置 Claude 可以在不询问您的情况下做什么。按 `Shift+Tab` 循环通过权限模式：202选择一个权限模式来设置 Claude 可以在不询问您的情况下做什么。按 `Shift+Tab` 循环通过权限模式：

190 203

191* **Auto**：分类器在后台审查大多数操作，并阻止风险操作而不是询问您。在 Pro、Max 和 Team 计划上，它是[交互式终端和 VS Code 会话的内置起始权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)204* **Auto**：分类器在后台审查大多数操作，并阻止风险操作而不是询问您。在 Claude Code v2.1.283 或更高版本中，它是[交互式终端和 VS Code 会话的内置起始权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)，在早期版本中仅在 Pro、Max 和 Team 计划上可用

192* **Manual**：Claude 在文件编辑和 shell 命令之前询问205* **Manual**：Claude 在文件编辑和 shell 命令之前询问

193* **Accept edits**：Claude 编辑文件并运行常见的文件系统命令（如 `mkdir` 和 `mv`）而不询问，仍然询问其他命令206* **Accept edits**：Claude 编辑文件并运行常见的文件系统命令（如 `mkdir` 和 `mv`）而不询问，仍然询问其他命令

194* **Plan**：Claude 探索并提出计划而不编辑您的源文件207* **Plan**：Claude 探索并提出计划而不编辑您的源文件

241您可以在任何时刻重定向 Claude，无需重新开始。执行以下任一操作：254您可以在任何时刻重定向 Claude，无需重新开始。执行以下任一操作：

242 255

243* **按 `Esc`** 立即停止 Claude。正在运行的工具调用被取消，Claude 等待您的下一条指令。如果您有排队的消息，Claude Code [会接下来发送它们](/docs/zh-CN/interactive-mode#queue-messages-while-claude-works)。256* **按 `Esc`** 立即停止 Claude。正在运行的工具调用被取消，Claude 等待您的下一条指令。如果您有排队的消息，Claude Code [会接下来发送它们](/docs/zh-CN/interactive-mode#queue-messages-while-claude-works)。

244* **输入更正并按 `Enter`** 在不停止 Claude 的情况下。消息显示为在输入框上方排队。如果 Claude 正在运行工具调用，它会在这些调用完成后立即读取消息，在同一轮内，并在下一步之前进行调整。[在 Claude 工作时排队消息](/docs/zh-CN/interactive-mode#queue-messages-while-claude-works)涵盖何时发送其他排队条目。257* **输入更正并按 `Enter`** 在不停止 Claude 的情况下。消息显示为在对话中排队。如果 Claude 正在运行工具调用，它会在这些调用完成后立即读取消息，在同一轮内，并在下一步之前进行调整。[在 Claude 工作时排队消息](/docs/zh-CN/interactive-mode#queue-messages-while-claude-works)涵盖何时发送其他排队条目。

245 258

246<h3 id="delegate-don’t-dictate">259<h3 id="delegate-don’t-dictate">

247 委派，不要指示260 委派，不要指示

interactive-mode.md +12 −4

Details

38| `Tab` | 接受自动完成建议，或向权限答案添加注释 | 当自动完成建议在提示输入中显示时，接受选定的建议。在大多数权限提示上，当**是**或**否**获得焦点时，在该选项上打开注释字段，再次按下会关闭该字段。请参阅[在回答权限提示时添加注释](/docs/zh-CN/permissions#add-a-comment-when-you-answer-a-permission-prompt) |38| `Tab` | 接受自动完成建议，或向权限答案添加注释 | 当自动完成建议在提示输入中显示时，接受选定的建议。在大多数权限提示上，当**是**或**否**获得焦点时，在该选项上打开注释字段，再次按下会关闭该字段。请参阅[在回答权限提示时添加注释](/docs/zh-CN/permissions#add-a-comment-when-you-answer-a-permission-prompt) |

39| `Up/Down arrows` 或 `Ctrl+P`/`Ctrl+N` | 移动光标或导航命令历史 | 当输入跨越多个可视行时，无论是换行还是多行，首先在提示中移动光标。一旦光标在第一行或最后一行，再次按下会导航命令历史。当您有排队的消息时，从第一行按 `Up` 会[取回它们](#take-back-what-you-queued) |39| `Up/Down arrows` 或 `Ctrl+P`/`Ctrl+N` | 移动光标或导航命令历史 | 当输入跨越多个可视行时，无论是换行还是多行，首先在提示中移动光标。一旦光标在第一行或最后一行，再次按下会导航命令历史。当您有排队的消息时，从第一行按 `Up` 会[取回它们](#take-back-what-you-queued) |

40| `Esc` | 中断 Claude 或关闭对话框 | 停止当前响应或工具调用中途，以便您可以重定向。Claude 保留迄今为止所做的工作。如果您有[排队的消息](#queue-messages-while-claude-works)，Claude Code 会在下一步发送它们。当对话框打开时，`Esc` 会关闭对话框。在权限提示上，`Esc` 会拒绝该操作，与[**否**不带注释](/docs/zh-CN/permissions#add-a-comment-when-you-answer-a-permission-prompt)相同 |40| `Esc` | 中断 Claude 或关闭对话框 | 停止当前响应或工具调用中途，以便您可以重定向。Claude 保留迄今为止所做的工作。如果您有[排队的消息](#queue-messages-while-claude-works)，Claude Code 会在下一步发送它们。当对话框打开时，`Esc` 会关闭对话框。当选中页脚项目时，例如提示下方的[子代理面板](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)中的一行，`Esc` 会[取消选择它](/docs/zh-CN/keybindings#footer-actions)而不是中断。在权限提示上，`Esc` 会拒绝该操作，与[**否**不带注释](/docs/zh-CN/permissions#add-a-comment-when-you-answer-a-permission-prompt)相同 |

42| `Ctrl+Enter` 或 `Ctrl+X Ctrl+S` | 立即发送排队的消息 | 发送您的[排队的消息](#queue-messages-while-claude-works)和您的草稿与它们一起立即发出。[Claude Code 何时发送您排队的内容](#when-claude-code-sends-what-you-queued)涵盖了 Claude 正在处理的轮次会发生什么。在[shell 模式](#shell-mode-with-prefix)中，该键仅排队您的命令。在不报告扩展键的终端中，`Ctrl+Enter` 作为普通 `Enter` 到达；`Ctrl+X Ctrl+S` 在任何终端中都有效。需要 Claude Code v2.1.275 或更高版本 |42| `Ctrl+Enter` 或 `Ctrl+X Ctrl+S` | 立即发送排队的消息 | 发送您的[排队的消息](#queue-messages-while-claude-works)和您的草稿与它们一起立即发出。[Claude Code 何时发送您排队的内容](#when-claude-code-sends-what-you-queued)涵盖了 Claude 正在处理的轮次会发生什么。在[shell 模式](#shell-mode-with-prefix)中，该键仅排队您的命令。在不报告扩展键的终端中，`Ctrl+Enter` 作为普通 `Enter` 到达；`Ctrl+X Ctrl+S` 在任何终端中都有效。需要 Claude Code v2.1.275 或更高版本 |

43| `Shift+Tab` 或在 Node 或 Bun 运行时不启用 VT 输入模式时在 Windows 上使用 `Alt+M` | 循环权限模式 | 循环通过 `default`（在模式指示器中标记为 Manual）、`acceptEdits`、`plan` 和（如果可用）`bypassPermissions` 然后 `auto`。从 `auto`，第一次按下切换到 `default`。请参阅[权限模式](/docs/zh-CN/permission-modes)。在文件权限提示上，相同的键会关闭打开的[注释字段](/docs/zh-CN/permissions#add-a-comment-when-you-answer-a-permission-prompt)。如果没有字段打开，它会选择允许该操作在会话其余部分的选项，当提示提供该选项时 |43| `Shift+Tab` 或在 Node 或 Bun 运行时不启用 VT 输入模式时在 Windows 上使用 `Alt+M` | 循环权限模式 | 循环通过 `default`（在模式指示器中标记为 Manual）、`acceptEdits`、`plan` 和（如果可用）`bypassPermissions` 然后 `auto`。从 `auto`，第一次按下切换到 `default`。请参阅[权限模式](/docs/zh-CN/permission-modes)。在文件权限提示上，相同的键会关闭打开的[注释字段](/docs/zh-CN/permissions#add-a-comment-when-you-answer-a-permission-prompt)。如果没有字段打开，它会选择允许该操作在会话其余部分的选项，当提示提供该选项时 |

47 47

48<h3 id="text-editing">48<h3 id="text-editing">

235| 命令 | 操作 |235| 命令 | 操作 |

236| :- | :- |236| :- | :- |

237| `x` | 删除字符 |237| `x` | 删除字符 |

238| `r{char}` | 用 `{char}` 替换光标下的字符 |

238| `dd` | 删除行 |239| `dd` | 删除行 |

239| `D` | 删除到行尾 |240| `D` | 删除到行尾 |

241| `df{char}`/`dt{char}` | 删除到并包括，或删除到下一个字符出现位置 |242| `df{char}`/`dt{char}` | 删除到并包括，或删除到下一个字符出现位置 |

243| `dj`/`dk` | 删除当前行和下方或上方的行 |

244| `dgg`/`dG` | 从当前行删除到第一行或最后一行 |

245| `d0`/`c0`/`y0` | 从光标删除、更改或复制回行首。需要 Claude Code v2.1.281 或更高版本 |

242| `cc` | 更改行 |246| `cc` | 更改行 |

243| `C` | 更改到行尾 |247| `C` | 更改到行尾 |

342* 提示 Claude Code 在后台运行命令346* 提示 Claude Code 在后台运行命令

343* 按 `Ctrl+B` 将常规 Bash 工具调用移到后台。Tmux 用户必须按两次 `Ctrl+B`，因为 tmux 有前缀键。347* 按 `Ctrl+B` 将常规 Bash 工具调用移到后台。Tmux 用户必须按两次 `Ctrl+B`，因为 tmux 有前缀键。

344 348

349当命令在完成前达到超时时，Claude Code 会自动[将其移到后台](/docs/zh-CN/tools-reference#background-commands)而不是停止它，除非命令以 `sleep` 开头。要更改命令在此之前运行多长时间，请设置 [Bash 超时环境变量](/docs/zh-CN/tools-reference#timeout-and-output-limits)。

350

345**主要功能：**351**主要功能：**

346 352

347* 输出被写入文件，Claude 可以使用 Read 工具检索它353* 输出被写入文件，Claude 可以使用 Read 工具检索它

395 在 Claude 工作时排队消息401 在 Claude 工作时排队消息

396</h2>402</h2>

397 403

398在 Claude 工作时输入消息并按 `Enter`。Claude Code 会将消息排队而不是中断当前轮次，并在输入框上方列出排队的条目，直到发送它们。您可以以相同的方式排队 `!` [shell 命令](#shell-mode-with-prefix)和大多数[命令](/docs/zh-CN/commands)，除了 `/status` 等 Claude Code 在您发送时立即运行的命令。404在 Claude 工作时输入消息并按 `Enter`。Claude Code 会将消息排队而不是中断当前轮次，并在对话中列出排队的条目，直到发送它们。您可以以相同的方式排队 `!` [shell 命令](#shell-mode-with-prefix)和大多数[命令](/docs/zh-CN/commands)，除了 `/status` 等 Claude Code 在您发送时立即运行的命令。

399 405

400已发送和排队的消息在 Claude 开始响应之前以灰色显示，因此您可以看出 Claude 还没有开始处理哪些消息。406已发送和排队的消息在 Claude 开始响应之前以灰色显示，因此您可以看出 Claude 还没有开始处理哪些消息。

401 407

408如果您从[连接的 IDE](/docs/zh-CN/vs-code#the-built-in-ide-mcp-server)或[差异面板](#diff-panel)排队带有选择的消息，它会保留您按 `Enter` 时的选择，无论您之后选择什么。

409

402<h3 id="when-claude-code-sends-what-you-queued">410<h3 id="when-claude-code-sends-what-you-queued">

403 Claude Code 何时发送您排队的内容411 Claude Code 何时发送您排队的内容

404</h3>412</h3>

jetbrains.md +3 −1

Details

249 249

250服务器名为 `ide`，从 `/mcp` 中隐藏，因为没有什么需要配置。但是，如果您的组织使用 [`PreToolUse` hook](/docs/zh-CN/hooks#pretooluse) 来允许列表 MCP 工具，您需要知道它的存在。250服务器名为 `ide`，从 `/mcp` 中隐藏，因为没有什么需要配置。但是，如果您的组织使用 [`PreToolUse` hook](/docs/zh-CN/hooks#pretooluse) 来允许列表 MCP 工具，您需要知道它的存在。

251 251

252**选择和打开文件上下文。** 连接时，CLI 会在您发送的每个提示中包含您当前的编辑器选择和活动文件的路径作为上下文。当发生这种情况时，记录会显示一行 `⧉ Selected N lines from <file>`。要排除敏感文件（如 `.env`），请为其路径添加 [`Read` 拒绝规则](/docs/zh-CN/permissions#read-and-edit)。匹配的拒绝规则可防止该文件的选定文本和打开文件通知都到达 Claude。252**选择和打开文件上下文。** 连接时，CLI 会在您发送的每个提示中包含您当前的编辑器选择和活动文件的路径作为上下文。当发生这种情况时，记录会显示一行 `⧉ Selected N lines from <file>`。如果您[在 Claude 工作时排队消息](/docs/zh-CN/interactive-mode#queue-messages-while-claude-works)，它会保留您按下 `Enter` 时的选择，无论您之后选择什么。

253

254要排除敏感文件（如 `.env`），请为其路径添加 [`Read` 拒绝规则](/docs/zh-CN/permissions#read-and-edit)。匹配的拒绝规则可防止该文件的选定文本和打开文件通知都到达 Claude。

253 255

254**传输和身份验证。** 服务器侦听 OS 分配的临时端口，该端口不可配置。传输是未加密的 `ws://`；在环回上，任何可以捕获流量的进程也可以从锁文件中读取令牌，因此 TLS 不会对本地攻击者增加保护。每次 IDE 启动都会生成一个新的随机身份验证令牌，将其写入 `~/.claude/ide/<port>.lock` 处的锁文件，CLI 必须将其作为 `X-Claude-Code-Ide-Authorization` 标头呈现才能连接。如果设置了 `CLAUDE_CONFIG_DIR`，锁文件将改为写入 `$CLAUDE_CONFIG_DIR/ide/`。256**传输和身份验证。** 服务器侦听 OS 分配的临时端口，该端口不可配置。传输是未加密的 `ws://`；在环回上，任何可以捕获流量的进程也可以从锁文件中读取令牌，因此 TLS 不会对本地攻击者增加保护。每次 IDE 启动都会生成一个新的随机身份验证令牌，将其写入 `~/.claude/ide/<port>.lock` 处的锁文件，CLI 必须将其作为 `X-Claude-Code-Ide-Authorization` 标头呈现才能连接。如果设置了 `CLAUDE_CONFIG_DIR`，锁文件将改为写入 `$CLAUDE_CONFIG_DIR/ide/`。

255 257

keybindings.md +46 −25

Details

22| `$docs` | 可选的文档 URL |22| `$docs` | 可选的文档 URL |

23| `bindings` | 按上下文分组的绑定块数组 |23| `bindings` | 按上下文分组的绑定块数组 |

24 24

~~25此示例将 `Ctrl+E` 绑定到在聊天上下文中打开外部编辑器，并取消绑定 `Ctrl+U`：~~25此示例将 `Ctrl+E` 绑定到在聊天上下文中打开外部编辑器，并取消绑定 `Ctrl+S`：

26 26

27```json theme={null}27```json theme={null}

28{28{

29 "$schema": "https://www.schemastore.org/claude-code-keybindings.json",29 "$schema": "https://www.schemastore.org/claude-code-keybindings.json",

~~30 "$docs": "https://code.claude.com/docs/zh-CN/keybindings",~~30 "$docs": "https://code.claude.com/docs/en/keybindings",

31 "bindings": [31 "bindings": [

32 {32 {

33 "context": "Chat",33 "context": "Chat",

34 "bindings": {34 "bindings": {

35 "ctrl+e": "chat:externalEditor",35 "ctrl+e": "chat:externalEditor",

~~36 "ctrl+u": null~~36 "ctrl+s": null

37 }37 }

38 }38 }

39 ]39 ]

50| :- | :- |50| :- | :- |

51| `Global` | 在应用程序的任何地方应用 |51| `Global` | 在应用程序的任何地方应用 |

52| `Chat` | 主聊天输入区域 |52| `Chat` | 主聊天输入区域 |

54| `Settings` | 设置菜单 |54| `Settings` | 设置菜单 |

55| `Confirmation` | 权限和确认对话框 |55| `Confirmation` | 权限和确认对话框 |

56| `Tabs` | 选项卡导航组件 |56| `Tabs` | 选项卡导航组件 |

57| `Help` | 帮助菜单可见 |57| `Help` | 帮助菜单可见 |

58| `Transcript` | 记录查看器 |58| `Transcript` | 记录查看器 |

61| `ThemePicker` | 主题选择器对话框 |61| `ThemePicker` | 主题选择器对话框 |

63| `Footer` | 页脚指示器导航（任务、团队、差异、工件） |63| `Footer` | 页脚指示器导航（任务、团队、差异、工件） |

65| `DiffDialog` | 差异查看器导航 |65| `DiffDialog` | 差异查看器导航 |

67| `ModelPicker` | 模型选择器工作量级别 |67| `ModelPicker` | 模型选择器工作量级别 |

68| `EffortSlider` | 由 `/effort` 打开的工作量滑块 |68| `EffortSlider` | 由 `/effort` 打开的工作量滑块 |

69| `Select` | 通用选择/列表组件 |69| `Select` | 通用选择/列表组件 |

71| `Agents` | [Agent 视图](/docs/zh-CN/agent-view)（`claude agents`） |71| `Agents` | [Agent 视图](/docs/zh-CN/agent-view)（`claude agents`） |

72| `Scroll` | 对话滚动和全屏模式下的文本选择 |72| `Scroll` | 对话滚动和全屏模式下的文本选择 |

73 73

168 168

169对话框使用 `confirm:yes` 和 `confirm:no` 来接受和取消，即使它们不提出是或否的问题。如果您在此上下文中绑定裸字母（例如 `y` 或 `n`），该字母也会作用于从不将其显示为键的对话框。显示 `y` 和 `n` 作为其键的对话框会自己读取这些字母，不需要绑定。169对话框使用 `confirm:yes` 和 `confirm:no` 来接受和取消，即使它们不提出是或否的问题。如果您在此上下文中绑定裸字母（例如 `y` 或 `n`），该字母也会作用于从不将其显示为键的对话框。显示 `y` 和 `n` 作为其键的对话框会自己读取这些字母，不需要绑定。

170 170

171在大多数对话框中，按 `Ctrl+C` 或 `Ctrl+D` 两次会关闭对话框而不是退出 Claude Code。第一次按下后的提示会说明第二次按下是关闭对话框还是退出。两个键都是 [保留的](#reserved-shortcuts)，无法重新绑定。

172

171此示例将 `y` 绑定到 `confirm:yes`，将 `n` 绑定到 `confirm:no`：173此示例将 `y` 绑定到 `confirm:yes`，将 `n` 绑定到 `confirm:no`：

172 174

173```json theme={null}175```json theme={null}

270 272

273在选项卡式对话框中，当选项卡行有焦点时，`tabs:next` 和 `tabs:previous` 会切换选项卡。在某些对话框中，例如 `/help` 和 `/sandbox`，选项卡切换键也可以从选项卡的内容中工作。

274

275`Up` 和 `Down` 在选项卡行和选项卡的内容之间移动焦点，内容中的列表仅在有焦点时才响应键。

276

271<h3 id="attachments-actions">277<h3 id="attachments-actions">

272 Attachments 操作278 Attachments 操作

273</h3>279</h3>

299 305

300选定页脚项时（例如提示下方的代理面板中的一行），即使您在 `Chat` 上下文中将 `Enter` 重新绑定到 `chat:queueSubmit` 或 `chat:newline`，`Enter` 也会打开它。306选定页脚项时（例如提示下方的代理面板中的一行），即使您在 `Chat` 上下文中将 `Enter` 重新绑定到 `chat:queueSubmit` 或 `chat:newline`，`Enter` 也会打开它。

301 307

305 Message selector 操作311 Message selector 操作

306</h3>312</h3>

307 313

308在 `MessageSelector` 上下文中可用的操作：314在 [rewind 菜单](/docs/zh-CN/checkpointing) 的消息列表中，您可以通过 [Select 操作](#select-actions) 及其默认键在消息中移动并选择一条。您的 `Select` 绑定对这些操作也适用于那里。`MessageSelector` 上下文没有自己的操作或默认绑定。使用它通过在 `MessageSelector` 块中绑定 Select 操作（例如 `select:accept`）来仅为此列表更改键。

309 315

310| 操作 | 默认 | 描述 |316此示例将 `o` 绑定到在 rewind 菜单中选择突出显示的消息，而不更改任何其他列表：

311| :- | :- | :- |317

312| `messageSelector:up` | Up, K, Ctrl+P | 在列表中向上移动 |318```json theme={null}

313| `messageSelector:down` | Down, J, Ctrl+N | 在列表中向下移动 |319{

314| `messageSelector:top` | Ctrl+Up, Shift+Up, Meta+Up, Shift+K | 跳到顶部 |320 "bindings": [

315| `messageSelector:bottom` | Ctrl+Down, Shift+Down, Meta+Down, Shift+J | 跳到底部 |321 {

316| `messageSelector:select` | Enter | 选择消息 |322 "context": "MessageSelector",

323 "bindings": {

324 "o": "select:accept"

325 }

326 }

327 ]

328}

329```

330

331在 v2.1.283 之前，此列表忽略 `Select` 绑定，并有自己的操作：`messageSelector:up`、`messageSelector:down`、`messageSelector:top`、`messageSelector:bottom` 和 `messageSelector:select`。如果您的 `keybindings.json` 绑定了其中一个名称，绑定在此列表中继续工作作为执行相同操作的 Select 操作。`Home` 和 `End` 跳到列表的任一端；在 v2.1.283 之前，`Shift+K` 和 `Shift+J` 等键默认执行此操作。

317 332

318<h3 id="diff-actions">333<h3 id="diff-actions">

319 Diff 操作334 Diff 操作

329| `diff:previousFile` | Up, K | 文件列表中的上一个文件；在详细视图中向上滚动一行 |344| `diff:previousFile` | Up, K | 文件列表中的上一个文件；在详细视图中向上滚动一行 |

331| `diff:viewDetails` | Enter | 查看 diff 详情 |

332| `diff:back` | (未绑定) | 在 diff 查看器中返回。Escape 通过 `diff:dismiss` 执行返回操作。之前在详细视图中的 Left 默认值在 v2.1.203 中被移除 |346| `diff:back` | (未绑定) | 在 diff 查看器中返回。Escape 通过 `diff:dismiss` 执行返回操作。之前在详细视图中的 Left 默认值在 v2.1.203 中被移除 |

333 347

334diff 详细视图还将寻呼机样式的键绑定到标准 [滚动操作](#scroll-actions)。这些绑定是 `DiffDialog` 上下文的一部分，仅在详细视图中应用；[滚动操作](#scroll-actions) 下列出的 `Scroll` 上下文默认值保持不变。348文件列表也响应 [Select 操作](#select-actions)，通过它们的默认键和您的 `Select` 绑定。`select:previous` 和 `select:next` 移动到上一个和下一个文件，`Enter` 通过 `select:accept` 打开选定文件的 diff。要仅为文件列表更改其中一个键，在 `DiffDialog` 块中绑定 Select 操作。

349

350在 v2.1.283 之前，文件列表忽略 `Select` 绑定，`Enter` 通过单独的 `diff:viewDetails` 操作打开选定文件的 diff。如果您的 `keybindings.json` 绑定了 `diff:viewDetails`，绑定在文件列表中继续工作作为 `select:accept`。

351

352diff 详细视图也将寻呼机样式的键绑定到标准 [滚动操作](#scroll-actions)。这些绑定是 `DiffDialog` 上下文的一部分，仅在详细视图中应用；[滚动操作](#scroll-actions) 下列出的 `Scroll` 上下文默认值保持不变。

335 353

336| 操作 | 默认 | 描述 |354| 操作 | 默认 | 描述 |

337| :- | :- | :- |355| :- | :- | :- |

373 Effort slider 操作391 Effort slider 操作

374</h3>392</h3>

375 393

376在 `EffortSlider` 上下文中可用的操作，当您运行不带参数的 `/effort` 时打开的滑块。滑块的 Left、Right、Enter 和 Escape 键无法重新绑定。394在 `EffortSlider` 上下文中可用的操作，当您运行不带参数的 `/effort` 时打开的滑块。滑块的 Enter 和 Escape 键无法重新绑定。

377 395

378| 操作 | 默认 | 描述 |396| 操作 | 默认 | 描述 |

379| :- | :- | :- |397| :- | :- | :- |

398| `effortSlider:decreaseEffort` | Left | 将滑块移动到下一个较低的努力级别。需要 v2.1.284 或更高版本 |

399| `effortSlider:increaseEffort` | Right | 将滑块移动到下一个较高的努力级别。需要 v2.1.284 或更高版本 |

400| `effortSlider:toggleUltracode` | Tab | 为此会话打开或关闭 [ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)，当滑块 [提供它](/docs/zh-CN/model-config#when-ultracode-is-available) 时。需要 v2.1.284 或更高版本 |

380| `effortSlider:thisSessionOnly` | s | 仅将焦点 [努力级别](/docs/zh-CN/model-config#adjust-effort-level) 应用于此会话。需要 v2.1.257 或更高版本 |401| `effortSlider:thisSessionOnly` | s | 仅将焦点 [努力级别](/docs/zh-CN/model-config#adjust-effort-level) 应用于此会话。需要 v2.1.257 或更高版本 |

381 402

382<h3 id="select-actions">403<h3 id="select-actions">

398 419

399Claude Code 在 `/skills` 菜单中应用您的 `select:pageUp`、`select:pageDown`、`select:first` 和 `select:last` 绑定。在大多数其他列表中，例如 `/model` 选择器，您的 `select:first` 和 `select:last` 绑定适用。PageUp 和 PageDown 在这些列表中进行分页，无论您的绑定如何。420在列表面板中，例如 `/skills` 和 `/mcp`，Claude Code 应用您的 `select:pageUp`、`select:pageDown`、`select:first` 和 `select:last` 绑定。在大多数其他列表中，例如 `/model` 选择器，您的 `select:first` 和 `select:last` 绑定适用。PageUp 和 PageDown 在这些列表中进行分页，无论您的绑定如何。

400 421

401在 v2.1.280 之前，这些其他列表忽略 Home、End 和您的 `select:first` 和 `select:last` 绑定。422在 v2.1.280 之前，这些其他列表忽略 Home、End 和您的 `select:first` 和 `select:last` 绑定。

402 423

668 验证689 验证

669</h2>690</h2>

670 691

671Claude Code 验证您的快捷键并显示以下警告：692Claude Code 验证您的快捷键并向调试日志写入以下警告：

672 693

673* 解析错误（无效的 JSON 或结构）694* 解析错误（无效的 JSON 或结构）

674* 无效的上下文名称695* 无效的上下文名称

677* 保留快捷键冲突698* 保留快捷键冲突

678* 同一上下文中的重复绑定699* 同一上下文中的重复绑定

679 700

680Claude Code 在文件加载时报告警告，并将每个警告写入调试日志。使用 [`--debug`](/docs/zh-CN/cli-reference#cli-flags) 启动 Claude Code 以查看详细信息。701使用 [`--debug`](/docs/zh-CN/cli-reference#cli-flags) 启动 Claude Code 以查看详细信息。

llm-gateway.md +1 −1

Details

49 订阅和网关49 订阅和网关

50</h2>50</h2>

51 51

52当[网关凭证变量](/docs/zh-CN/llm-gateway-connect#set-the-credential-variable)或 `apiKeyHelper` 处于活动状态时，开发人员的 claude.ai 订阅不被使用：凭证替换该会话的订阅登录，订阅的使用限制不适用。该流量按令牌计费给拥有网关转发的凭证的人，例如您的组织的 Anthropic Console 账户，或当网关路由到那里时您的 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 账户。52当[网关凭证变量](/docs/zh-CN/llm-gateway-connect#set-the-credential-variable)或 `apiKeyHelper` 处于活动状态时，请求会使用该凭证代替开发人员的 claude.ai 订阅登录，订阅的使用限制不适用于这些请求。Claude Code 在机器上保存了 claude.ai 登录信息，但不会在这些请求中发送它。该流量按令牌计费给拥有网关转发的凭证的人，例如您的组织的 Anthropic Console 账户，或当网关路由到那里时您的 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 账户。

53 53

54[`ANTHROPIC_BASE_URL`](/docs/zh-CN/llm-gateway-connect#set-the-base-url-and-credential)是指向 Claude Code 网关的变量。仅设置该变量，不设置网关凭证，不会替换订阅。请求仍然通过网关路由，但保存的 claude.ai 登录保持活动凭证，因此其使用限制和计费适用。将此流量转发给 Anthropic 的网关必须转发 `anthropic-beta` 中的 OAuth 功能；请参阅[请求头参考](/docs/zh-CN/llm-gateway-protocol#request-headers)。54[`ANTHROPIC_BASE_URL`](/docs/zh-CN/llm-gateway-connect#set-the-base-url-and-credential)是指向 Claude Code 网关的变量。仅设置该变量，不设置网关凭证，不会替换订阅。请求仍然通过网关路由，但保存的 claude.ai 登录保持活动凭证，因此其使用限制和计费适用。将此流量转发给 Anthropic 的网关必须转发 `anthropic-beta` 中的 OAuth 功能；请参阅[请求头参考](/docs/zh-CN/llm-gateway-protocol#request-headers)。

55 55

llm-gateway-connect.md +2 −2

Details

140<Tabs>140<Tabs>

141 <Tab title="Bash or Zsh">141 <Tab title="Bash or Zsh">

142 ```bash theme={null}142 ```bash theme={null}

143 curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \143 curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \

144 -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \144 -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \

145 -H "anthropic-version: 2023-06-01" \145 -H "anthropic-version: 2023-06-01" \

146 -H "content-type: application/json" \146 -H "content-type: application/json" \

594| `/fast` 在使用 `ANTHROPIC_AUTH_TOKEN` 进行身份验证的会话中报告 `Fast mode has been disabled by your organization`，即使组织已启用快速模式 | 可用性检查需要 claude.ai 登录或 Anthropic API 密钥；仅使用持有者令牌，Claude Code 会将快速模式视为已禁用，而不发送检查 | 设置 `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1`；请参阅[在代理和 LLM 网关后面使用快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) |594| `/fast` 在使用 `ANTHROPIC_AUTH_TOKEN` 进行身份验证的会话中报告 `Fast mode has been disabled by your organization`，即使组织已启用快速模式 | 可用性检查需要 claude.ai 登录或 Anthropic API 密钥；仅使用持有者令牌，Claude Code 会将快速模式视为已禁用，而不发送检查 | 设置 `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1`；请参阅[在代理和 LLM 网关后面使用快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) |

595| Claude Code 要求您登录，即使 [curl 测试](#verify-the-connection)成功 | CLI 没有自己的凭证：可达的基础 URL 不是一个，在交互会话中，项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的 `env` 块仅在首次运行向导和[信任提示](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder)之后应用 | 在 Claude Code 在首次运行设置之前读取的某处设置 `ANTHROPIC_AUTH_TOKEN`：shell 导出、`~/.claude/settings.json` 中的 `env` 块或托管设置 |595| Claude Code 要求您登录，即使 [curl 测试](#verify-the-connection)成功 | CLI 没有自己的凭证：可达的基础 URL 不是一个，在交互会话中，项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的 `env` 块仅在首次运行向导和[信任提示](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder)之后应用 | 在 Claude Code 在首次运行设置之前读取的某处设置 `ANTHROPIC_AUTH_TOKEN`：shell 导出、`~/.claude/settings.json` 中的 `env` 块或托管设置 |

597| `This machine's managed settings require a first-party login` | 托管设置包括 `forceLoginMethod` 或 `forceLoginOrgUUID`，不能与 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 共存 | 您的管理员必须从托管设置中删除 `forceLoginMethod` 和 `forceLoginOrgUUID` 以使用网关凭证，或删除网关凭证以使用第一方登录。两者不能组合 |597| `This machine's managed settings require a first-party login`，或当托管设置将 `forceLoginMethod` 设置为 `"gateway"` 或也设置 `forceLoginGatewayUrl` 时 [`Administrator policy requires a Cloud gateway sign-in`](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in) | 托管设置包括 `forceLoginMethod` 或 `forceLoginOrgUUID`，不能与 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 共存 | 您的管理员必须从托管设置中删除 `forceLoginMethod`、`forceLoginOrgUUID` 和 `forceLoginGatewayUrl` 以使用网关凭证，或删除网关凭证以使用托管设置要求的登录。两者不能组合 |

598| `403` 带有 HTML 正文，例如 `403 Forbidden`，当网关自己的日志显示没有收到请求时 | 网关前面的 Web 应用防火墙或反向代理在请求到达网关之前阻止了请求正文。Claude Code 提示包括 XML 样式标签和与跨站脚本正文规则匹配的源代码，因此短 curl 测试通过而实际会话不通过 | 从请求正文检查中豁免网关的 `/v1/messages` 路径。在 AWS WAF 上这是 `CrossSiteScripting_Body` 托管规则；在带有 ModSecurity 的 nginx 上它是等效的 OWASP CRS 正文规则 |598| `403` 带有 HTML 正文，例如 `403 Forbidden`，当网关自己的日志显示没有收到请求时 | 网关前面的 Web 应用防火墙或反向代理在请求到达网关之前阻止了请求正文。Claude Code 提示包括 XML 样式标签和与跨站脚本正文规则匹配的源代码，因此短 curl 测试通过而实际会话不通过 | 从请求正文检查中豁免网关的 `/v1/messages` 路径。在 AWS WAF 上这是 `CrossSiteScripting_Body` 托管规则；在带有 ModSecurity 的 nginx 上它是等效的 OWASP CRS 正文规则 |

599| 证书或 TLS 错误，例如 `SSL certificate verification failed` 或 `Self-signed certificate detected`，当 [curl 测试](#verify-the-connection)成功时 | Claude Code 的运行时不信任 `curl` 使用的相同证书颁发机构。常见于企业 TLS 检查代理后面 | 将 `NODE_EXTRA_CA_CERTS` 设置为 CA 包路径；请参阅 [CA 证书存储](/docs/zh-CN/network-config#ca-certificate-store) |599| 证书或 TLS 错误，例如 `SSL certificate verification failed` 或 `Self-signed certificate detected`，当 [curl 测试](#verify-the-connection)成功时 | Claude Code 的运行时不信任 `curl` 使用的相同证书颁发机构。常见于企业 TLS 检查代理后面 | 将 `NODE_EXTRA_CA_CERTS` 设置为 CA 包路径；请参阅 [CA 证书存储](/docs/zh-CN/network-config#ca-certificate-store) |

600 600

llm-gateway-protocol.md +34 −27

Details

73 73

74流式传输推理响应。Claude Code 在流到达时读取流，因此如果您的网关在中继之前缓冲完整响应，Claude Code 会停滞。74流式传输推理响应。Claude Code 在流到达时读取流，因此如果您的网关在中继之前缓冲完整响应，Claude Code 会停滞。

75 75

76传递每个响应的完整事件序列，不要丢弃、重复或重新排序事件。当事件引用的内容块的 `content_block_start` 从未到达，或块的 `content_block_stop` 已经到达时，Claude Code 会在该事件处停止读取流，而不是应用它，因此重复的 `content_block_stop` 不能运行相同的工具调用两次。[上述响应可能不完整](/docs/zh-CN/errors#the-response-above-may-be-incomplete)描述了用户看到的内容，在 `部分响应从未到达` 和 `响应流格式错误` 变体下。

78在结束正文之前，通过每个响应的最终 `message_delta` 和 `message_stop` 事件中继每个响应。在 `message_delta` 携带 `stop_reason` 之后结束的正文，没有内容块仍然打开，该帧之后没有内容块事件，即使 `message_stop` 缺失，也计为完整。您的网关更早结束的正文，一旦内容块已启动，就被视为与断开连接相同：[自动重试](/docs/zh-CN/errors#automatic-retries)说明 Claude Code 何时重新发出请求，[上述响应可能不完整](/docs/zh-CN/errors#the-response-above-may-be-incomplete)涵盖了一旦可见内容到达它保留的内容。Claude Code 保留 `message_delta` 传递的 `stop_reason`，因此稍后仅使用情况的 `message_delta`，其 `delta` 具有 `stop_reason: null` 或没有 `stop_reason` 键，不会清除它。

76当客户端使用 Amazon Bedrock 格式时，原样中继 `InvokeModelWithResponseStream` 响应体及其 `Content-Type: application/vnd.amazon.eventstream` 头，不要将流转换为服务器发送事件。请参阅[网关或代理后面的流式传输错误](/docs/zh-CN/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。80当客户端使用 Amazon Bedrock 格式时，原样中继 `InvokeModelWithResponseStream` 响应体及其 `Content-Type: application/vnd.amazon.eventstream` 头，不要将流转换为服务器发送事件。请参阅[网关或代理后面的流式传输错误](/docs/zh-CN/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。

77 81

78也转发保活 ping。在通过 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 的连接上，Claude Code 计算网关中继的每个字节，包括 SSE `ping` 事件和注释行，并默认在 300 秒内中止无声流。上游的 ping 是长思考暂停期间的唯一流量，因此如果您的网关剥离或缓冲它们，Claude Code 会在这些暂停期间中止流；[自动重试](/docs/zh-CN/errors#automatic-retries)涵盖了根据响应进度如何报告中止的流。完全不发送 ping 的上游（如 Amazon Bedrock 的二进制事件流）在这些暂停中没有任何东西可转发。从这样的上游转换时，在无声间隙期间发出您自己的 `ping` 事件。通过 `ANTHROPIC_BEDROCK_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_FOUNDRY_BASE_URL` 到达的网关不受此字节级监视程序的包装，即使它们中继 Anthropic Messages 格式；在那里，[5 分钟空闲超时](/docs/zh-CN/env-vars)会中止无声流，在 `ANTHROPIC_BEDROCK_BASE_URL` 连接上，您可以使用 [`CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK`](/docs/zh-CN/env-vars) 添加字节监视程序。82也转发保活 ping。在通过 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 的连接上，Claude Code 计算网关中继的每个字节，包括 SSE `ping` 事件和注释行，并默认在 300 秒内中止无声流。上游的 ping 是长思考暂停期间的唯一流量，因此如果您的网关剥离或缓冲它们，Claude Code 会在这些暂停期间中止流；[自动重试](/docs/zh-CN/errors#automatic-retries)涵盖了根据响应进度如何报告中止的流。完全不发送 ping 的上游（如 Amazon Bedrock 的二进制事件流）在这些暂停中没有任何东西可转发。从这样的上游转换时，在无声间隙期间发出您自己的 `ping` 事件。通过 `ANTHROPIC_BEDROCK_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_FOUNDRY_BASE_URL` 到达的网关不受此字节级监视程序的包装，即使它们中继 Anthropic Messages 格式；在那里，[5 分钟空闲超时](/docs/zh-CN/env-vars)会中止无声流，在 `ANTHROPIC_BEDROCK_BASE_URL` 连接上，您可以使用 [`CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK`](/docs/zh-CN/env-vars) 添加字节监视程序。

129 请求头133 请求头

130</h2>134</h2>

131 135

132Claude Code 在 API 请求上包含这些请求头。请求头名称在网络上不区分大小写。转发 `anthropic-version` 和 `anthropic-beta` 不变，加上当上游是 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 时的 `anthropic-workspace-id`；其余的 gateway 可能会使用它们进行路由、归属和跟踪，不需要转发。136Claude Code 在 API 请求中包含这些头。头名称在网络上不区分大小写。转发 `anthropic-version` 和 `anthropic-beta` 不变，以及当上游是 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 时的 `anthropic-workspace-id`；其余的网关可能会用于路由、归属和追踪，不需要转发。

133 137

134| 请求头 | 描述 |138| 头 | 描述 |

135| :- | :- |139| :- | :- |

136| `Authorization`、`x-api-key` | 开发者的 gateway 凭证，根据他们设置的[凭证变量](/docs/zh-CN/llm-gateway-connect#set-the-credential-variable)在一个或两个请求头中 |140| `Authorization`, `x-api-key` | 开发者的网关凭证，根据他们设置的 [凭证变量](/docs/zh-CN/llm-gateway-connect#set-the-credential-variable) 在一个或两个头中 |

137| `anthropic-version` | API 版本，目前为 `2023-06-01`。Amazon Bedrock 和 Google Cloud 的 Agent Platform 格式请求也携带 `anthropic_version` 请求体字段，其值是提供商方言字符串，而不是此请求头的值 |141| `anthropic-version` | API 版本，目前为 `2023-06-01`。Amazon Bedrock 和 Google Cloud 的 Agent Platform 格式请求也在 `anthropic_version` 请求体字段中携带，其值是提供商方言字符串，而不是此头的值 |

138| `anthropic-beta` | 请求的逗号分隔功能值。逐字转发请求头；不要将单个值列入白名单，因为该集合随 Claude Code 版本而变化。当开发者使用 claude.ai 登录进行身份验证时（当设置 `ANTHROPIC_BASE_URL` 而不设置 gateway 凭证变量时可能），此请求头还携带上游需要的 OAuth 功能，删除它会导致这些请求失败，返回 `401` |142| `anthropic-beta` | 请求的逗号分隔的能力值。逐字转发该头；不要对单个值进行白名单，因为该集合随 Claude Code 版本而变化。当开发者使用 claude.ai 登录进行身份验证时（当设置 `ANTHROPIC_BASE_URL` 而没有网关凭证变量时可能），此头也会携带上游所需的 OAuth 能力，删除它会导致这些请求失败并返回 `401` |

140| `x-claude-code-agent-id` | 发出请求的[子代理](/docs/zh-CN/sub-agents)的标识符，仅在来自 Claude Code 在会话内生成的代理的请求上存在。将其与会话 ID 一起使用以将成本归属于并行代理 |144| `x-claude-code-agent-id` | 发出请求的 [子代理](/docs/zh-CN/sub-agents) 的标识符，仅在来自代理在会话内生成的 Claude Code 的请求上存在。将其与会话 ID 一起使用以将成本归属于并行代理 |

142 146

143子代理 ID 在每次生成时都会生成新的。队友代理，[代理团队](/docs/zh-CN/agent-teams)的命名成员，在重新连接时重用基于名称的稳定 ID。在两种情况下，ID 都标识一个代理，而不是一个人或设备，因此不要将代理 ID 请求头视为用户标识符。147子代理 ID 在每次 Claude Code 生成子代理时都会生成新的。队友代理是 [代理团队](/docs/zh-CN/agent-teams) 的命名成员，在重新连接时重用基于名称的稳定 ID。在两种情况下，ID 都标识一个代理，而不是一个人或设备，因此不要将代理 ID 头视为用户标识符。

144 148

145如果您的开发者设置了 `ANTHROPIC_CUSTOM_HEADERS`，这些请求头也会出现在请求上。149如果您的开发者设置了 `ANTHROPIC_CUSTOM_HEADERS`，这些头也会出现在请求上。

146 150

147<h3 id="gateway-hint-headers">151<h3 id="gateway-hint-headers">

148 Gateway 提示请求头152 网关提示头

149</h3>153</h3>

150 154

151Claude Code 还可以发送路由提示：gateway 或路由器可以用来调度、缓存或归属请求的每个请求事实。需要 Claude Code v2.1.273 或更高版本。155Claude Code 也可以发送路由提示：网关或路由器可以用来调度、缓存或归属请求的每个请求事实。需要 Claude Code v2.1.273 或更高版本。

152 156

153请求是否携带它们取决于 Claude Code 将其发送到何处：157请求是否携带它们取决于 Claude Code 将其发送到何处：

154 158

155* 直接连接到 Anthropic API：默认发送159* 直接连接到 Anthropic API：默认发送

156* 自定义基础 URL：默认关闭，因为拒绝未知请求头的代理会导致请求失败。要接收它们，请为您的开发者设置 [`CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`](/docs/zh-CN/env-vars)，例如在[托管设置](/docs/zh-CN/managed-settings)的 `env` 块中160* 自定义基础 URL：默认关闭，因为拒绝未知头的代理会导致请求失败。要接收它们，请为您的开发者设置 [`CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`](/docs/zh-CN/env-vars)，例如在 [托管设置](/docs/zh-CN/managed-settings) 的 `env` 块中

157* 任何其他后端，包括 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 AWS 上的 Claude Platform：仅当设置 `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1` 时发送161* 任何其他后端，包括 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 AWS 上的 Claude Platform：仅当设置 `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1` 时发送

158 162

159将 `CLAUDE_CODE_GATEWAY_HINT_HEADERS` 设置为 `0` 会在每个连接上停止这些请求头。163将 `CLAUDE_CODE_GATEWAY_HINT_HEADERS` 设置为 `0` 会在每个连接上停止这些头。

160 164

161这些请求头仅携带下面行列出的内容：固定词汇、工具名称和持续时间，从不包含提示文本或文件内容。每个值都是可打印的 ASCII。165这些头仅携带下面行列出的内容：固定词汇、工具名称、持续时间和随机提示标识符，从不携带提示文本或文件内容。每个值都是可打印的 ASCII。

162 166

163| 请求头 | 描述 |167| 头 | 描述 |

164| :- | :- |168| :- | :- |

165| `x-claude-code-request-class` | 这是什么类型的请求：`main` 表示主对话的一个回合，`subagent` 表示[子代理](/docs/zh-CN/sub-agents)的一个回合，`workflow` 表示在工作流内运行的代理，`compaction` 表示压缩对话的总结请求，或 `auxiliary` 表示会话标题、分类器和摘要等辅助请求。在每个请求上发送 |169| `x-claude-code-request-class` | 这是什么类型的请求：`main` 用于主对话的一个回合，`subagent` 用于 [子代理](/docs/zh-CN/sub-agents) 的一个回合，`workflow` 用于在工作流内运行的代理，`compaction` 用于压缩对话的总结请求，或 `auxiliary` 用于侧面请求，如会话标题、分类器和摘要。在每个请求上发送 |

166| `x-claude-code-agent-type` | 发出请求的子代理的类型：内置代理类型名称，如 `Explore`、`Plan` 或 `general-purpose`，或 `custom` 表示用户定义的代理，`teammate` 表示在主导的进程中运行的[代理团队](/docs/zh-CN/agent-teams)成员，或 `fork` 表示[分叉](/docs/zh-CN/sub-agents#fork-the-current-conversation)。仅在子代理自己的回合上存在；子代理的压缩或辅助请求保留代理 ID 但不携带类型。用户选择的代理名称永远不会被发送 |170| `x-claude-code-agent-type` | 发出请求的子代理的类型：内置代理类型名称，如 `Explore`、`Plan` 或 `general-purpose`，或 `custom` 用于用户定义的代理，`teammate` 用于在主导的进程中运行的 [代理团队](/docs/zh-CN/agent-teams) 成员，或 `fork` 用于 [分叉](/docs/zh-CN/sub-agents#fork-the-current-conversation)。仅在子代理自己的回合上存在；子代理的压缩或侧面请求保留代理 ID 但不携带类型。用户选择的代理名称永远不会被发送 |

167| `x-claude-code-compaction` | 在[压缩](/docs/zh-CN/prompt-caching#compacting-the-conversation)期间总结对话的请求上存在。该值说明触发了什么：`auto` 表示上下文窗口接近容量，`manual` 表示 `/compact`，或 `reactive` 表示 API 拒绝请求过长。在所有其他请求上不存在 |171| `x-claude-code-compaction` | 在 [压缩](/docs/zh-CN/prompt-caching#compacting-the-conversation) 期间总结对话的请求上存在。该值说明触发了什么：`auto` 当上下文窗口接近容量时，`manual` 用于 `/compact`，或 `reactive` 当 API 拒绝请求过长时。在所有其他请求上不存在 |

169| `x-claude-code-prev-tool-durations` | 此请求携带的结果的工具调用的测量运行时间，格式为 `<name>=<ms>;<name>=<ms>`，例如 `Bash=742;Read=9`。在同一对话的下一个请求中发送，来自主会话或子代理，在一批工具调用之后 |173| `x-claude-code-prev-tool-durations` | 此请求携带其结果的工具调用的测量运行时间，格式为 `<name>=<ms>;<name>=<ms>`，例如 `Bash=742;Read=9`。在同一对话的下一个请求之后发送，来自主会话或子代理的一批工具调用 |

174| `x-claude-code-prompt-id` | 标识请求所服务的用户提示的随机 UUID。服务一个提示的请求共享该值，包括提示启动的子代理的回合。未归属于提示的请求省略它。使用它按提示对会话的请求进行分组。需要 Claude Code v2.1.283 或更高版本 |

170 175

171在解析 `x-claude-code-prev-tool-durations` 之前，检查 Claude Code 如何构建该值以及它遗漏了什么：176在解析 `x-claude-code-prev-tool-durations` 之前，检查 Claude Code 如何构建该值以及它遗漏了什么：

172 177

174* 上限：Claude Code 最多发送 32 个条目和 4 KB，保留第一个条目179* 上限：Claude Code 最多发送 32 个条目和 4 KB，保留第一个条目

175* 编码：工具名称是百分比编码的，涵盖 `%`、`;`、`=`、逗号、空格和任何可打印 ASCII 之外的字符180* 编码：工具名称是百分比编码的，涵盖 `%`、`;`、`=`、逗号、空格和任何可打印 ASCII 之外的字符

176* 解析：在 `;` 上分割，然后在 `=` 上分割，并解码每个名称181* 解析：在 `;` 上分割，然后在 `=` 上分割，并解码每个名称

177* 缺失：压缩调用、辅助请求和新提示的第一个请求不携带它。不要将缺失的请求头读作运行无工具的回合182* 缺失：压缩调用、侧面请求和新提示的第一个请求永远不会携带它。不要将缺失的头读作运行无工具的回合

178* 时间：每个时间都排除权限提示和 hooks，并行工具调用各自报告自己的时间，因此条目不会加起来等于请求之间的间隔183* 时间：每个都排除权限提示和钩子，并行工具调用各自报告自己的时间，因此条目不会加起来等于请求之间的间隙

179 184

180<h3 id="forward-as-open-lists">185<h3 id="forward-as-open-lists">

181 作为开放列表转发186 作为开放列表转发

182</h3>187</h3>

183 188

184将请求头和请求体字段视为开放列表，而不是封闭列表。Claude Code 在版本中获得功能，它们作为新的 `anthropic-beta` 值、新的请求体字段以及偶尔新的 `anthropic-*` 或 `x-claude-code-*` 请求头到达。189将头和请求体字段视为开放列表，而不是封闭列表。Claude Code 在版本中获得能力，它们作为新的 `anthropic-beta` 值、新的请求体字段，以及偶尔新的 `anthropic-*` 或 `x-claude-code-*` 头到达。

185 190

186转发到 Anthropic 格式上游时，将 `anthropic-*` 请求头和请求体字段原封不动地传递，而不是将您今天看到的列入白名单。固定到观察列表的 gateway 会删除下一个功能的请求头或字段，并在引入它的版本上破坏它。191转发到 Anthropic 格式上游时，通过 `anthropic-*` 请求头和请求体字段不变，而不是对您今天看到的进行白名单。固定在观察列表上的网关会删除下一个能力的头或字段，并在引入它的版本上破坏它。

187 192

188例外是非 Anthropic 上游，如 Amazon Bedrock 或 Google Cloud 的 Agent Platform，其中弥合架构差异是 gateway 的工作；请参阅[功能传递](#feature-pass-through)。193例外是非 Anthropic 上游，如 Amazon Bedrock 或 Google Cloud 的 Agent Platform，其中桥接模式差异是网关的工作；请参阅 [功能传递](#feature-pass-through)。

189 194

190<h2 id="response-headers">195<h2 id="response-headers">

191 响应头196 响应头

265 禁用预发布功能270 禁用预发布功能

266</h3>271</h3>

267 272

268`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` 阻止 Claude Code 在每个提供商上发送预发布功能及其请求体字段，包括上下文管理和 beta 工具字段。该变量不影响自适应推理，后者由模型而不是 beta 选择。它永远不会抑制订阅身份验证所需的 OAuth 功能。273`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` 阻止 Claude Code 发送预发布功能及其请求体字段，包括上下文管理和 beta 工具字段。该变量不影响自适应推理，后者由模型而不是 beta 选择。它永远不会抑制订阅身份验证所需的 OAuth 功能。

274

275当嵌入 Claude Code 的主机平台设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 时，`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 不会阻止 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 上的自动模式会话向服务器请求[分类器审查](/docs/zh-CN/permission-modes#server-side-classifier-review)。该审查添加了 `anthropic-beta` 值和 `safeguards` 请求字段。设置 `CLAUDE_CODE_AUTO_MODE_SERVER=0` 以在那里停止它。

269 276

270在 Claude Code v2.1.227 或更高版本上，您的组织可以通过[托管设置](/docs/zh-CN/managed-settings)在此变量下保持 [MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)打开。Claude Code 在该覆盖生效时发送的内容取决于您如何连接：277在 Claude Code v2.1.227 或更高版本上，您的组织可以通过[托管设置](/docs/zh-CN/managed-settings)在此变量下保持 [MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)打开。Claude Code 在该覆盖生效时发送的内容取决于您如何连接：

271 278

340当发现的 ID 与选择器中已有的行匹配时，它不会获得自己的行：347当发现的 ID 与选择器中已有的行匹配时，它不会获得自己的行：

341 348

342* 相同 ID：发现的 ID 完全匹配现有行的 ID，或两个 ID 是同一 [Fable](/docs/zh-CN/model-config#work-with-fable) 版本的拼写。349* 相同 ID：发现的 ID 完全匹配现有行的 ID，或两个 ID 是同一 [Fable](/docs/zh-CN/model-config#work-with-fable) 版本的拼写。

343* 与内置别名相同的模型：当发现的显式 ID 命名内置别名当前解析到的模型时，选择器仅显示别名行。例如，当 `sonnet` 解析为 `claude-sonnet-5` 时，发现的 `claude-sonnet-5` 会折叠到 `sonnet` 行中，而发现的 `claude-sonnet-4-6` 仍会获得自己的行。在 v2.1.197 之前，Claude Code 不会将这些 ID 折叠到内置行中，因此 `claude-sonnet-5` 也会获得自己的"From gateway"行。350* 与内置别名相同的模型：当发现的显式 ID 命名内置别名当前解析到的模型时，选择器仅显示别名行。例如，当 `sonnet` 解析为 `claude-sonnet-5-5` 时，发现的 `claude-sonnet-5-5` 会折叠到 `sonnet` 行中，而发现的 `claude-sonnet-5` 仍会获得自己的行。在 v2.1.197 之前，Claude Code 不会将这些 ID 折叠到内置行中，因此别名解析到的 ID 也会获得自己的"From gateway"行。

344 351

345结果被缓存到 `~/.claude/cache/gateway-models.json`，或在 Windows 上 `%USERPROFILE%\.claude\cache\gateway-models.json`，并在每次启动时刷新。如果您设置了 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars)，缓存会改为位于该目录下。如果请求失败或 gateway 未实现 `/v1/models`，选择器会回退到上次启动的缓存列表或内置模型列表。如果您的 gateway 在不匹配发现过滤器的别名下提供 Claude 模型，开发者可以使用[模型配置](/docs/zh-CN/model-config)变量手动添加这些别名。352结果被缓存到 `~/.claude/cache/gateway-models.json`，或在 Windows 上 `%USERPROFILE%\.claude\cache\gateway-models.json`，并在每次启动时刷新。如果您设置了 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars)，缓存会改为位于该目录下。如果请求失败或 gateway 未实现 `/v1/models`，选择器会回退到上次启动的缓存列表或内置模型列表。如果您的 gateway 在不匹配发现过滤器的别名下提供 Claude 模型，开发者可以使用[模型配置](/docs/zh-CN/model-config)变量手动添加这些别名。

346 353

llm-gateway-rollout.md +1 −1

Details

208 208

209将表中的条件变量添加到相同的 `env` 块。托管的 `ANTHROPIC_BASE_URL` 被强制执行，不能被开发者的 shell 导出覆盖，因为 Claude Code 在进程环境和较低优先级设置上应用它。209将表中的条件变量添加到相同的 `env` 块。托管的 `ANTHROPIC_BASE_URL` 被强制执行，不能被开发者的 shell 导出覆盖，因为 Claude Code 在进程环境和较低优先级设置上应用它。

210 210

211不要在托管设置中与网关凭证一起包括 `forceLoginMethod` 或 `forceLoginOrgUUID`。任一密钥，具有任何值，在启动时阻止 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 和 `apiKeyHelper`，开发者无法继续。他们看到 `This machine's managed settings require a first-party login`，或在 `"gateway"` 值下看到 [`Administrator policy requires a Cloud gateway sign-in`](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。211不要在托管设置中与网关凭证一起包括 `forceLoginMethod`、`forceLoginOrgUUID` 或 `forceLoginGatewayUrl`。`forceLoginMethod` 或 `forceLoginOrgUUID`，具有任何值，在启动时阻止 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 和 `apiKeyHelper`，开发者无法继续。他们看到 `This machine's managed settings require a first-party login`，或当文件将 `forceLoginMethod` 设置为 `"gateway"` 或设置 `forceLoginGatewayUrl` 时看到 [`Administrator policy requires a Cloud gateway sign-in`](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。

212 212

213[服务器管理的设置](/docs/zh-CN/server-managed-settings#platform-availability)交付需要直接连接到 `api.anthropic.com`，因此它不会到达网关路由的会话。网关部署使用这个基于文件的托管设置路径，它强制执行相同的密钥。213[服务器管理的设置](/docs/zh-CN/server-managed-settings#platform-availability)交付需要直接连接到 `api.anthropic.com`，因此它不会到达网关路由的会话。网关部署使用这个基于文件的托管设置路径，它强制执行相同的密钥。

214 214

managed-mcp.md +1 −1

Details

526 监控 MCP 使用情况526 监控 MCP 使用情况

527</h2>527</h2>

528 528

529当[配置 OpenTelemetry 导出](/docs/zh-CN/monitoring-usage)时，Claude Code 可以记录用户调用的 MCP 服务器和工具。设置 `OTEL_LOG_TOOL_DETAILS=1` 以在工具事件中包含 MCP 服务器和工具名称，然后在您的收集器中聚合它们以查看用户实际连接的服务器。请参阅[监控](/docs/zh-CN/monitoring-usage)以设置导出器和完整的事件架构。529当[配置 OpenTelemetry 导出](/docs/zh-CN/monitoring-usage)时，Claude Code 可以记录用户调用的 MCP 服务器和工具。设置 `OTEL_LOG_TOOL_DETAILS=1` 以在工具事件和[成本和令牌计数器](/docs/zh-CN/monitoring-usage#cost-counter)中包含 MCP 服务器和工具名称，然后在您的收集器中聚合它们以查看用户实际连接的服务器。请参阅[监控](/docs/zh-CN/monitoring-usage)以设置导出器和完整的事件架构。

530 530

531<h2 id="configuration-summary">531<h2 id="configuration-summary">

532 配置摘要532 配置摘要

managed-settings.md +55 −19

Details

78| HKCU 注册表，Windows 和 WSL | 作为 Windows `HKCU` 注册表值；请参阅[每个机制存储策略的位置](#where-each-mechanism-stores-the-policy) | 在启动时读取并每 30 分钟检查一次更改；Claude Code 仅在没有其他托管源交付策略密钥且没有[主机提供的父设置](#let-an-embedding-host-add-policy)提供限制性密钥时使用它 | 您无法写入机器级 `HKLM` 密钥 |78| HKCU 注册表，Windows 和 WSL | 作为 Windows `HKCU` 注册表值；请参阅[每个机制存储策略的位置](#where-each-mechanism-stores-the-policy) | 在启动时读取并每 30 分钟检查一次更改；Claude Code 仅在没有[上面存在的管理文档](#present-admin-documents)且没有[主机提供的父设置](#let-an-embedding-host-add-policy)提供限制性密钥时使用它 | 您无法写入机器级 `HKLM` 密钥 |

79 79

80Jamf、Iru、Intune 和组策略的入门模板在[MDM 示例存储库](https://github.com/anthropics/claude-code/tree/main/examples/mdm)中。80Jamf、Iru、Intune 和组策略的入门模板在[MDM 示例存储库](https://github.com/anthropics/claude-code/tree/main/examples/mdm)中。

81 81

89 89

90* **表面**：在开发者的机器上，终端、VS Code 和 JetBrains 扩展、桌面应用的 Code 选项卡和[Agent SDK](/docs/zh-CN/agent-sdk/typescript)会话读取所有这些源。Agent SDK 会话即使在 `settingSources` 排除用户、项目和本地文件时也加载托管设置。90* **表面**：在开发者的机器上，终端、VS Code 和 JetBrains 扩展、桌面应用的 Code 选项卡和[Agent SDK](/docs/zh-CN/agent-sdk/typescript)会话读取所有这些源。Agent SDK 会话即使在 `settingSources` 排除用户、项目和本地文件时也加载托管设置。

91* **云会话**：Anthropic 托管环境中的会话不读取设备的 MDM 配置文件或文件，因此其策略必须来自服务器托管设置。[自托管环境](/docs/zh-CN/self-hosted-environments)中的会话也读取其运行器镜像中的托管设置文件，默认情况下仅当服务器托管设置不交付策略密钥时，除了[Claude Code 从每个管理源读取的密钥](#keys-read-from-every-admin-source)。[Claude Code 如何组合托管源](#how-claude-code-combines-managed-sources)涵盖了适用于两者的选择加入。91* **云会话**：Anthropic 托管环境中的会话不读取设备的 MDM 配置文件或文件，因此其策略必须来自服务器托管设置。[自托管环境](/docs/zh-CN/self-hosted-environments)中的会话也读取其运行器镜像中的托管设置文件，默认情况下仅当服务器托管设置不交付策略密钥时，除了[Claude Code 从每个管理源读取的密钥](#keys-read-from-every-admin-source)。[Claude Code 如何组合托管源](#how-claude-code-combines-managed-sources)涵盖了适用于两者的选择加入。

92* **Claude Tag 会话**：[Claude Tag](https://claude.com/docs/claude-tag/overview)会话在云环境中运行，但不接收服务器托管设置。在[自托管环境](/docs/zh-CN/self-hosted-environments)中，它们仍然读取运行器镜像中的托管设置文件。在[Claude Tag 管理员设置](https://claude.com/docs/claude-tag/admins/customize)中配置 Claude Tag 本身。

92* **协作会话**：Claude Desktop 应用中的[协作](https://claude.com/docs/cowork/overview)在 Claude Code 上运行其会话。在协作会话中，Claude Code 永远不会从 claude.ai 管理控制台获取服务器托管设置，即使用户使用 Team 或 Enterprise 帐户登录，因此应用的策略取决于会话运行的位置：93* **协作会话**：Claude Desktop 应用中的[协作](https://claude.com/docs/cowork/overview)在 Claude Code 上运行其会话。在协作会话中，Claude Code 永远不会从 claude.ai 管理控制台获取服务器托管设置，即使用户使用 Team 或 Enterprise 帐户登录，因此应用的策略取决于会话运行的位置：

93 94

94 * **在用户的机器上**：默认情况下，协作会话中的 Claude Code 读取该设备上的 MDM 或操作系统级策略和托管设置文件，因此在那里部署策略。95 * **在用户的机器上**：默认情况下，协作会话中的 Claude Code 读取该设备上的 MDM 或操作系统级策略和托管设置文件，因此在那里部署策略。

1561. 远程设置，从 claude.ai 作为 [服务器管理的设置](/docs/zh-CN/server-managed-settings) 或通过 [Claude 应用网关](/docs/zh-CN/claude-apps-gateway) 交付。Claude Code 仅在会话使用 [符合条件的登录或密钥](/docs/zh-CN/server-managed-settings#platform-availability) 直接向 Anthropic 的 API 进行身份验证，或使用 `/login` 登录网关时才获取此源。在其他提供商上，或当 `ANTHROPIC_BASE_URL` 指向 Anthropic 的 API 以外的地方时，它从下一个源开始1571. 远程设置，从 claude.ai 作为 [服务器管理的设置](/docs/zh-CN/server-managed-settings) 或通过 [Claude 应用网关](/docs/zh-CN/claude-apps-gateway) 交付。Claude Code 仅在会话使用 [符合条件的登录或密钥](/docs/zh-CN/server-managed-settings#platform-availability) 直接向 Anthropic 的 API 进行身份验证，或使用 `/login` 登录网关时才获取此源。在其他提供商上，或当 `ANTHROPIC_BASE_URL` 指向 Anthropic 的 API 以外的地方时，它从下一个源开始

1572. MDM 或操作系统级策略：macOS plist 或 HKLM 注册表键1582. MDM 或操作系统级策略：macOS plist 或 HKLM 注册表键

1583. 托管设置文件，`managed-settings.d/*.json` 和 `managed-settings.json` 合并在一起1593. 托管设置文件，`managed-settings.d/*.json` 和 `managed-settings.json` 合并在一起

1594. HKCU 注册表，在 Windows 上，以及在 WSL 上一旦 HKLM 注册表或 Windows 托管设置文件打开 [`wslInheritsWindowsSettings`](/docs/zh-CN/settings-reference#wslinheritswindowssettings) 并且 HKCU 值也设置它时。Claude Code 仅在上面没有源提供策略键且没有 [主机提供的父设置](#let-an-embedding-host-add-policy) 提供限制性键时才读取它1604. HKCU 注册表，在 Windows 上，以及在 WSL 上一旦 HKLM 注册表或 Windows 托管设置文件打开 [`wslInheritsWindowsSettings`](/docs/zh-CN/settings-reference#wslinheritswindowssettings) 并且 HKCU 值也设置它时。Claude Code 仅在上面没有管理员源存在且没有 [主机提供的父设置](#let-an-embedding-host-add-policy) 提供限制性键时才读取它

161

162<span id="present-admin-documents" />

163

164Claude Code 永远不会在存在的管理员源下应用用户可写的 HKCU 注册表。当源设置任何策略键为非 `null` 值时，该源是存在的，即使是 Claude Code 无法读取的值。无法读取的 HKLM 值、托管设置文件或 `managed-settings.d` 目录也是存在的。在 WSL 上，`/etc/claude-code` 也是用户可写的，[`wslInheritsWindowsSettings`](/docs/zh-CN/settings-reference#wslinheritswindowssettings) 条目说明 Windows 源何时位于其上方。

160 165

161此图显示排名，以及 Claude Code 在任一设置下从前三个源读取的跨源键的示例：166此图显示排名，以及 Claude Code 在任一设置下从前三个源读取的跨源键的示例：

162 167

208 213

209| 键的类型 | Claude Code 如何组合它 | 示例 |214| 键的类型 | Claude Code 如何组合它 | 示例 |

210| :- | :- | :- |215| :- | :- | :- |

211| 列表 | 组合来自每个源的条目 | `permissions.allow`、`hooks`、`sandbox.network.allowedDomains`、`deniedMcpServers` |216| 列表 | 组合来自每个源的条目 | `permissions.allow`、`hooks`、`sandbox.network.allowedDomains`、`deniedMcpServers`、`deniedModels` |

212| 锁 | 应用任何源设置的最严格值；较宽松的值仅从最高排名源适用 | `allowManagedHooksOnly`、`permissions.disableBypassPermissionsMode`、`crossSessionInbound` |217| 锁 | 应用任何源设置的最严格值；较宽松的值仅从最高排名源适用 | `allowManagedHooksOnly`、`permissions.disableBypassPermissionsMode`、`crossSessionInbound`、`availableModelsMatch` |

332 查找 Claude Code 丢弃的条目337 查找 Claude Code 丢弃的条目

333</h3>338</h3>

334 339

335当托管设置文件、MDM 配置文件、注册表值或服务器管理的有效负载未通过架构验证时，Claude Code 首先跳过它可以修复的单个条目（例如一个无效的权限规则），每个都带有警告，然后丢弃其值仍然失败的任何顶级密钥，并继续强制执行每个剩余的有效密钥。340当托管设置文件、MDM 配置文件、注册表值或服务器管理的有效负载未通过架构验证时，Claude Code 首先跳过它可以修复的单个条目（例如一个无效的权限规则），每个都带有警告，然后丢弃其值仍然失败的任何值，除非该值属于[失败关闭](#keys-that-fail-closed)的密钥之一。

336 341

337Claude Code 对 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 发出的 `managedSettings` 更严格：它进行相同的条目修复，但任何幸存的架构违规都会导致整个 helper 运行失败，在启动时 Claude Code 拒绝启动，与 helper 以非零状态退出相同。342Claude Code 对 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 发出的 `managedSettings` 更严格：它进行相同的条目修复，但任何幸存的架构违规都会导致整个 helper 运行失败，在启动时 Claude Code 拒绝启动，与 helper 以非零状态退出相同。

338 343

360 失败关闭的密钥365 失败关闭的密钥

361</h4>366</h4>

362 367

363少数强制密钥在无效时不会被丢弃。Claude Code 强制执行更严格的回退，直到修复该值；该表显示了对每个密钥强制执行的内容：368当托管源设置具有单个限制性值的顶级密钥（例如 `allowManagedPermissionRulesOnly`、`disableAutoMode` 或 `skipDangerousModePermissionPrompt`）为 Claude Code 无法读取的内容时，该密钥读取为该值，直到您修复它。报告说该密钥 `was present but invalid`，并命名 Claude Code 将其视为的值。对于 `sandbox` 内的密钥，请参阅[`sandbox` 内的无效值](#invalid-values-inside-sandbox)。

369

370这些情况不会失败关闭：

371

372* `null` 删除该密钥。

373* 无效的 `disableAllHooks`，即使是带引号的布尔值，也会被丢弃并带有警告，因为强制执行 `true` 也会卸载您自己的托管设置部署的 hooks。

374* 对于规则涵盖的每个其他布尔密钥，字符串 `"true"` 或 `"false"` 读取为该布尔值，在 `/status` 中带有通知，要求您删除引号。

375

376Claude Code 按字段而不是整体修复 `permissions`、`autoMode`、`worktree` 和 `attribution` 块：

377

378* 其中的锁（例如 `permissions.disableBypassPermissionsMode`）读取为其限制性值。

379* 无效的 `permissions.defaultMode` 读取为 `default`。

380* 当 `permissions` 中的 `deny` 或 `ask` 列表根本无法读取时，Claude Code 扣留 `allow` 和 `additionalDirectories`，因此授予永远不会应用而没有写在旁边的限制。报告命名每个扣留的授予和无法读取的列表。

381* 在 `autoMode` 中，无法读取的 `soft_deny` 或 `hard_deny` 列表，或丢失无效条目的列表，以相同方式扣留 `allow` 和 `environment`。

382

383具有单个限制性值的密钥的失败关闭规则和按字段修复需要 Claude Code v2.1.282 或更高版本。

384

385这些密钥有自己的回退：

364 386

365| 字段 | 存在但无效时的行为 |387| 字段 | 存在但无效时的行为 |

366| :- | :- |388| :- | :- |

367| `allowedMcpServers` | 强制执行为空的允许列表，直到修复该值，因此用户添加的 MCP 服务器都不被允许。您的组织通过 [`managedMcpServers`](/docs/zh-CN/settings-reference#managedmcpservers) 传递的服务器仍然加载，`managed-mcp.json` 服务器根据[如何评估服务器](/docs/zh-CN/managed-mcp#how-a-server-is-evaluated)加载。单个无效条目被剥离，有效子集被强制执行。 |389| `allowedMcpServers` | 强制执行为空的允许列表，直到修复该值，因此用户添加的 MCP 服务器都不被允许。您的组织通过 [`managedMcpServers`](/docs/zh-CN/settings-reference#managedmcpservers) 传递的服务器仍然加载，`managed-mcp.json` 服务器根据[如何评估服务器](/docs/zh-CN/managed-mcp#how-a-server-is-evaluated)加载。单个无效条目被剥离，有效子集被强制执行。 |

368| `allowedHttpHookUrls` | Claude Code 强制执行空的[允许列表](/docs/zh-CN/settings-reference#allowedhttphookurls)，直到您修复该值，因此 HTTP hook 仅在另一个设置文件列出其 URL 时运行。如果只有单个条目无效，Claude Code 会剥离该条目并强制执行其余的。 |390| `allowedHttpHookUrls` | Claude Code 强制执行空的托管[允许列表](/docs/zh-CN/settings-reference#allowedhttphookurls)，直到您修复该值，因此 HTTP hook 仅在另一个设置文件列出其 URL 时运行。如果只有单个条目无效，Claude Code 会剥离该条目并强制执行其余的。 |

369| `httpHookAllowedEnvVars` | Claude Code 强制执行空的[允许列表](/docs/zh-CN/settings-reference#httphookallowedenvvars)，直到您修复该值，因此仅当另一个设置文件命名标头变量时才会插值。如果只有单个条目无效，Claude Code 会剥离该条目并强制执行其余的。 |391| `httpHookAllowedEnvVars` | Claude Code 强制执行空的托管[允许列表](/docs/zh-CN/settings-reference#httphookallowedenvvars)，直到您修复该值，因此仅当另一个设置文件命名标头变量时才会插值。如果只有单个条目无效，Claude Code 会剥离该条目并强制执行其余的。 |

371| `strictKnownMarketplaces` | 强制执行为空的允许列表，直到修复该值，因此不允许任何[市场源](/docs/zh-CN/plugins/org#restrict-what-users-can-install)。无效或无法强制执行的单个条目（例如无法编译的 `hostPattern` 正则表达式）被剥离，有效子集被强制执行。 |393| `strictKnownMarketplaces` | 强制执行为空的允许列表，直到修复该值，因此不允许任何[市场源](/docs/zh-CN/plugins/org#restrict-what-users-can-install)。无效或无法强制执行的单个条目（例如无法编译的 `hostPattern` 正则表达式）被剥离，有效子集被强制执行。 |

372| `allowManagedHooksOnly` | 视为 `true`，直到修复：[hook 限制](/docs/zh-CN/settings-reference#allowmanagedhooksonly)适用，除非 `disableCommandPluginSources` 明确为 `false`，否则命令源插件被禁用。 |

373| `allowManagedMcpServersOnly` | 视为 `true`。 |

374| `disableCommandPluginSources` | 视为 `true`，因此命令源插件保持禁用，直到修复该值。 |

375| `disableSideloadFlags` | 视为 `true`，直到修复该值，具有为 [`disableSideloadFlags`](/docs/zh-CN/settings-reference#disablesideloadflags) 列出的效果。 |

378| `syncClaudeAiPlugins` | 视为 `false`，因此[claude.ai 插件](/docs/zh-CN/settings-reference#syncclaudeaiplugins)的同步关闭，直到修复该值。 |

380| `gatewayInternalNetworks` | 当无效值来自机器上最高的托管源时，`/login` 拒绝该机器上的每个新[云网关](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)登录，直到修复该值。 |397| `gatewayInternalNetworks` | 当无效值来自机器上最高的托管源时，`/login` 拒绝该机器上的每个新[云网关](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)登录，直到修复该值。 |

381| `crossSessionInbound` | 视为 `refuse`，最严格的值，因此入站[跨会话消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)被拒绝，直到修复该值。开发人员看到[警告](/docs/zh-CN/errors#crosssessioninbound-must-be-one-of-accept-hold-refuse)。 |398| `crossSessionInbound` | 视为 `refuse`，最严格的值，因此入站[跨会话消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)被拒绝，直到修复该值。开发人员看到[警告](/docs/zh-CN/errors#crosssessioninbound-must-be-one-of-accept-hold-refuse)。 |

400| [`deniedModels`](/docs/zh-CN/settings-reference#deniedmodels) | 非字符串条目被剥离，列表的其余部分被强制执行。完全无效的值被丢弃并带有警告，在修复之前不会阻止任何模型。 |

383| `blockedMarketplaces` | 单个无效条目被剥离，有效子集被强制执行。解析但永远无法匹配的条目（例如无法编译的 `hostPattern` 正则表达式）被保留并带有警告。在修复之前它不会阻止任何内容，但[市场限制](/docs/zh-CN/plugins/org#restrict-what-users-can-install)保持活跃。完全无效的值被丢弃并带有警告，因为阻止每个市场会阻止策略从未命名的源。 |401| `blockedMarketplaces` | 单个无效条目被剥离，有效子集被强制执行。解析但永远无法匹配的条目（例如无法编译的 `hostPattern` 正则表达式）被保留并带有警告。在修复之前它不会阻止任何内容，但[市场限制](/docs/zh-CN/plugins/org#restrict-what-users-can-install)保持活跃。完全无效的值被丢弃并带有警告，因为阻止每个市场会阻止策略从未命名的源。 |

384| `sandbox.credentials` | 可恢复的无效条目降级为 `mode: "deny"` 并带有警告；不可恢复的条目被剥离；有效条目保持强制执行。请参阅[托管设置中的无效凭据条目](/docs/zh-CN/settings-reference#invalid-credential-entries-in-managed-settings) |402| `sandbox` | 当块内的一个值无效时，Claude Code 不会丢弃整个块。对于每种无效字段发生的情况，请参阅[`sandbox` 内的无效值](#invalid-values-inside-sandbox)。 |

403| `sandbox.credentials` | 可恢复的无效条目降级为 `mode: "deny"` 并带有警告；不可恢复的条目被剥离；有效条目保持强制执行。请参阅[托管设置中的无效凭据条目](/docs/zh-CN/settings-reference#invalid-credential-entries-in-managed-settings)。 |

404| `strictPluginOnlyCustomization` | 视为 `true`，锁定所有四个表面，当该值既不是布尔值也不是数组时。此版本不识别为表面的数组条目不锁定任何内容；状态注释计算此类条目，以便您可以检查它们是否有拼写错误。 |

405| `enabledPlugins` | 无效条目被丢弃并带有警告，其他条目保持强制执行。不是插件 ID 映射的值，或其每个条目都无效的值，被整体丢弃并带有警告。 |

385 406

386`allowedHttpHookUrls` 和 `httpHookAllowedEnvVars` 跨设置文件合并，因此您的用户、项目或本地设置中的条目在托管列表为空时仍然适用。407`allowedHttpHookUrls` 和 `httpHookAllowedEnvVars` 跨设置文件合并，因此您的用户、项目或本地设置中的条目在托管列表为空时仍然适用。

387 408

388这两个密钥和 `allowedChannelPlugins` 的回退需要 Claude Code v2.1.267 或更高版本；早期版本在其值或任何条目无效时整体丢弃该密钥。`strictKnownMarketplaces`、`blockedMarketplaces` 和 `disableSideloadFlags` 的回退需要 Claude Code v2.1.277 或更高版本；早期版本在其值或任何条目无效时整体丢弃该密钥。409这两个密钥和 `allowedChannelPlugins` 的回退需要 Claude Code v2.1.267 或更高版本；早期版本在其值或任何条目无效时整体丢弃该密钥。`strictKnownMarketplaces` 和 `blockedMarketplaces` 的回退需要 Claude Code v2.1.277 或更高版本；早期版本在其值或任何条目无效时整体丢弃该密钥。`strictPluginOnlyCustomization` 和 `enabledPlugins` 的回退需要 Claude Code v2.1.282 或更高版本。

389 410

390`requiredMinimumVersion` 和 `requiredMaximumVersion` 按设计失败开放：无效值被丢弃而不是强制执行。411`requiredMinimumVersion` 和 `requiredMaximumVersion` 按设计失败开放：无效值被丢弃而不是强制执行。

391 412

392此容限仅适用于托管设置。用户、项目和本地设置文件保持严格：JSON 或顶级形状验证失败的文件被整体拒绝并报告，失败的单个条目（例如格式错误的权限规则）被跳过并带有警告，而文件的其余部分适用。413此容限仅适用于托管设置。用户、项目和本地设置文件保持严格：JSON 或顶级形状验证失败的文件被整体拒绝并报告，失败的单个条目（例如格式错误的权限规则）被跳过并带有警告，而文件的其余部分适用。

393 414

415<h4 id="invalid-values-inside-sandbox">

416 `sandbox` 内的无效值

417</h4>

418

419当托管 `sandbox` 块中的一个值无效时，Claude Code 不会丢弃整个块，因为它独立验证每个字段。这种按字段处理需要 Claude Code v2.1.283 或更高版本。在 v2.1.283 之前的版本上，当 `credentials` 外的值无效时，Claude Code 会丢弃除 [`credentials`](/docs/zh-CN/settings-reference#invalid-credential-entries-in-managed-settings) 外的每个 `sandbox` 字段。

420

421您为无效字段获得的警告会命名该字段并告诉您它发生了什么。发生的情况取决于该字段控制的内容：

422

423* 如果您将布尔密钥设置为带引号的 `"true"` 或 `"false"`，该值计为该布尔值。而不是警告，`/status` 显示一个通知，要求您删除引号。

424* 如果 `failIfUnavailable` 无效，Claude Code 会丢弃该值而不是将其视为 `true`，因此无法读取的值永远不会停止整个设备群中的会话启动。

425* Claude Code 将每个其他无效布尔值视为保持沙箱最严格的值，直到您修复它。打开沙箱或其限制之一的密钥（例如 `enabled` 或 `network.allowManagedDomainsOnly`）计为 `true`。放松它的密钥（例如 `allowUnsandboxedCommands`）计为 `false`。

426* 在 `credentials` 外的列表中，例如 `excludedCommands` 或 `network.allowedDomains`，Claude Code 会丢弃无效条目并保留列表的其余部分。不是数组的列表或没有有效条目的列表根本不适用。

427* 当 `network.deniedDomains` 或其中任何条目无效时，Claude Code 也会扣留 `network.allowedDomains`，因此托管允许列表在您修复拒绝列表之前不会授予任何内容。

428* 当 `filesystem.denyRead`、`filesystem.denyWrite` 或其中任何条目无效时，Claude Code 也会扣留 `filesystem.allowRead` 和 `filesystem.allowWrite`，直到您修复拒绝列表。

429

394<span id="managed-only-settings" />430<span id="managed-only-settings" />

395 431

396<h2 id="keys-only-a-managed-source-can-set">432<h2 id="keys-only-a-managed-source-can-set">

401 437

402大多数是锁：锁管理的值，例如权限规则或 `sandbox.network.allowedDomains`，是任何级别都可以设置的普通密钥，锁告诉 Claude Code 仅尊重托管值。438大多数是锁：锁管理的值，例如权限规则或 `sandbox.network.allowedDomains`，是任何级别都可以设置的普通密钥，锁告诉 Claude Code 仅尊重托管值。

403 439

404表涵盖权限、插件和交付控制。对于此处未列出的任何密钥，[设置参考](/docs/zh-CN/settings-reference#all-settings)索引的 Scope 列说明它是否仅托管；那里的剩余仅托管密钥包括网关登录 URL、版本、浏览器、移动模拟器、SSH 主机、Desktop 本地会话、沙箱二进制路径、模型定价和 CLAUDE.md 控制。440表涵盖权限、插件和交付控制。对于此处未列出的任何密钥，[设置参考](/docs/zh-CN/settings-reference#all-settings)索引的 Scope 列说明它是否仅托管；那里的剩余仅托管密钥包括网关登录 URL、版本、浏览器、移动模拟器、SSH 主机、Desktop 本地会话、沙箱二进制路径、模型定价、模型限制和 CLAUDE.md 控制。

405 441

406| 设置 | 描述 |442| 设置 | 描述 |

407| :- | :- |443| :- | :- |

425| [`sandbox.network.allowManagedDomainsOnly`](/docs/zh-CN/settings-reference#sandbox-network-allowmanageddomainsonly) | 仅尊重托管 `allowedDomains` 和 `WebFetch(domain:...)` 允许规则；阻止其他域而不提示 |461| [`sandbox.network.allowManagedDomainsOnly`](/docs/zh-CN/settings-reference#sandbox-network-allowmanageddomainsonly) | 仅尊重托管 `allowedDomains` 和 `WebFetch(domain:...)` 允许规则；阻止其他域而不提示 |

426| [`strictKnownMarketplaces`](/docs/zh-CN/settings-reference#strictknownmarketplaces) | 控制用户可以添加和安装插件的插件市场源。请参阅[托管市场限制](/docs/zh-CN/plugins/org#restrict-what-users-can-install) |462| [`strictKnownMarketplaces`](/docs/zh-CN/settings-reference#strictknownmarketplaces) | 控制用户可以添加和安装插件的插件市场源。请参阅[托管市场限制](/docs/zh-CN/plugins/org#restrict-what-users-can-install) |

427| [`strictPluginOnlyCustomization`](/docs/zh-CN/settings-reference#strictpluginonlycustomization) | 阻止来自用户和项目源的 skills、agents、hooks 和 MCP 服务器；`true` 锁定所有四个，数组命名哪些 |463| [`strictPluginOnlyCustomization`](/docs/zh-CN/settings-reference#strictpluginonlycustomization) | 阻止来自用户和项目源的 skills、agents、hooks 和 MCP 服务器；`true` 锁定所有四个，数组命名哪些 |

428| [`wslInheritsWindowsSettings`](/docs/zh-CN/settings-reference#wslinheritswindowssettings) | 当在 HKLM 注册表或 `C:\Program Files\ClaudeCode` 下的文件中设置时，让 WSL 读取 Windows 策略链，仅当该目录下的托管设置文件或 drop-in 都不交付[策略密钥](#how-claude-code-combines-managed-sources)时读取 `/etc/claude-code`；条目给出顺序 |464| [`wslInheritsWindowsSettings`](/docs/zh-CN/settings-reference#wslinheritswindowssettings) | 当在 HKLM 注册表或 `C:\Program Files\ClaudeCode` 下的文件中设置时，让 WSL 读取 Windows 策略链，仅当[没有 Windows 管理文档存在](#present-admin-documents)时读取 `/etc/claude-code`；条目给出顺序 |

429 465

430<Note>466<Note>

431 在 Team 和 Enterprise 计划上，Owner 在[Claude Code 管理设置](https://claude.ai/admin-settings/claude-code)中为组织启用或禁用[远程控制](/docs/zh-CN/remote-control)和[云会话](/docs/zh-CN/claude-code-on-the-web)。远程控制可以另外通过 [`disableRemoteControl`](/docs/zh-CN/settings-reference#disableremotecontrol) 设置按设备禁用。云会话没有按设备托管设置密钥。467 在 Team 和 Enterprise 计划上，Owner 在[Claude Code 管理设置](https://claude.ai/admin-settings/claude-code)中为组织启用或禁用[远程控制](/docs/zh-CN/remote-control)和[云会话](/docs/zh-CN/claude-code-on-the-web)。远程控制可以另外通过 [`disableRemoteControl`](/docs/zh-CN/settings-reference#disableremotecontrol) 设置按设备禁用。云会话没有按设备托管设置密钥。

449 485

450Claude Code 应用 `1` 的值而不向用户显示[批准对话](/docs/zh-CN/server-managed-settings#environment-variables-and-the-approval-dialog)。486Claude Code 应用 `1` 的值而不向用户显示[批准对话](/docs/zh-CN/server-managed-settings#environment-variables-and-the-approval-dialog)。

451 487

452如果您关闭遥测，Claude Code 停止发送为您的组织[分析仪表板](/docs/zh-CN/analytics)提供的使用数据，用于策略到达的开发者。变量也关闭功能标志获取，这使得远程控制、默认自动模式和其他[需要功能标志获取的功能](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)对这些开发者不可用。488如果您关闭遥测，Claude Code 停止发送为您的组织[分析仪表板](/docs/zh-CN/analytics)提供的使用数据，用于策略到达的开发者。该变量也关闭[需要功能标志获取的功能](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的功能标志获取。对于远程控制，请参阅[远程控制要求](/docs/zh-CN/remote-control#requirements)。

453 489

454[策略应用的位置和时间](#where-and-when-a-policy-applies)说明哪个交付机制到达每个表面，[平台可用性](/docs/zh-CN/server-managed-settings#platform-availability)说明哪些会话跳过服务器托管设置获取。490[策略应用的位置和时间](#where-and-when-a-policy-applies)说明哪个交付机制到达每个表面，[平台可用性](/docs/zh-CN/server-managed-settings#platform-availability)说明哪些会话跳过服务器托管设置获取。

455 491

mcp.md +152 −135

Details

92 92

93具有 `url` 但没有 `type` 的 JSON 条目是配置错误，因为 Claude Code 将没有 `type` 的条目读取为 stdio 服务器。Claude Code 跳过该服务器并报告 `MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry`。在 v2.1.202 之前，Claude Code 将此配置错误报告为 `command: expected string, received undefined`。93具有 `url` 但没有 `type` 的 JSON 条目是配置错误，因为 Claude Code 将没有 `type` 的条目读取为 stdio 服务器。Claude Code 跳过该服务器并报告 `MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry`。在 v2.1.202 之前，Claude Code 将此配置错误报告为 `command: expected string, received undefined`。

94 94

95只有 SDK 主机应用程序（例如 [Agent SDK](/docs/zh-CN/agent-sdk/mcp) 应用程序或 [桌面应用](/docs/zh-CN/desktop)）可以注册进程内 `"type": "sdk"` 服务器。Claude Code 跳过 `.mcp.json`、`~/.claude.json` 或设置中的 `"type": "sdk"` 条目，并报告 `Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register`。

95在 `--output-format stream-json` 运行中，Claude Code 还在 `system/init` 事件的 [`mcp_server_errors` 字段](/docs/zh-CN/headless#stream-responses) 中报告跳过的 `--mcp-config` 条目，以便脚本可以检测到服务器从未加载。这需要 Claude Code v2.1.219 或更高版本。97在 `--output-format stream-json` 运行中，Claude Code 还在 `system/init` 事件的 [`mcp_server_errors` 字段](/docs/zh-CN/headless#stream-responses) 中报告跳过的 `--mcp-config` 条目，以便脚本可以检测到服务器从未加载。这需要 Claude Code v2.1.219 或更高版本。

96 98

97<h3 id="option-2-add-a-remote-sse-server">99<h3 id="option-2-add-a-remote-sse-server">

99</h3>101</h3>

100 102

101<Warning>103<Warning>

102 SSE（Server-Sent Events）传输已弃用。请改用 HTTP 服务器（如果可用）。104 SSE（Server-Sent Events）传输已弃用。请在可用的地方使用 HTTP 服务器。

103</Warning>105</Warning>

104 106

105某些服务仍然仅公开 SSE 端点。使用与 [HTTP 服务器](#option-1-add-a-remote-http-server) 相同的 `claude mcp add --transport http <name> <url>` 命令添加这些。Claude Code 首先尝试 HTTP 传输，当服务器不接受时切换到 SSE。自动切换需要 Claude Code v2.1.265 或更高版本。107某些服务仍然仅公开 SSE 端点。使用与 [HTTP 服务器](#option-1-add-a-remote-http-server) 相同的 `claude mcp add --transport http <name> <url>` 命令添加这些。Claude Code 首先尝试 HTTP 传输，当服务器不接受时切换到 SSE。自动切换需要 Claude Code v2.1.265 或更高版本。

124 126

125Stdio 服务器作为本地进程在您的机器上运行。它们非常适合需要直接系统访问或自定义脚本的工具。127Stdio 服务器作为本地进程在您的机器上运行。它们非常适合需要直接系统访问或自定义脚本的工具。

126 128

127Claude Code 在生成的服务器的环境中设置 `CLAUDE_PROJECT_DIR` 为项目根目录，因此您的服务器可以解析项目相对路径，而无需依赖工作目录。这与 hooks 在其 `CLAUDE_PROJECT_DIR` 变量中接收的目录相同。从服务器进程内部读取它，例如 Node 中的 `process.env.CLAUDE_PROJECT_DIR` 或 Python 中的 `os.environ["CLAUDE_PROJECT_DIR"]`。129Claude Code 在生成的服务器的环境中设置 `CLAUDE_PROJECT_DIR` 为项目根目录，以便您的服务器可以解析项目相对路径，而不依赖于工作目录。这与 hooks 在其 `CLAUDE_PROJECT_DIR` 变量中接收的目录相同。从服务器进程内读取它，例如 Node 中的 `process.env.CLAUDE_PROJECT_DIR` 或 Python 中的 `os.environ["CLAUDE_PROJECT_DIR"]`。

128 130

129`CLAUDE_PROJECT_DIR` 是稳定的项目根目录，在会话中添加或删除工作目录时不会更改。限制自己的文件系统访问到一组允许目录的服务器应该实现 MCP `roots/list` 请求。Claude Code 使用会话的启动目录加上您使用 `--add-dir`、`/add-dir` 或 `additionalDirectories` 设置授予的每个 [额外工作目录](/docs/zh-CN/permissions#working-directories) 来回答 `roots/list`。当该集合更改时，Claude Code 发送 `notifications/roots/list_changed`。在 v2.1.203 之前，`roots/list` 仅返回启动目录，Claude Code 不发送 `notifications/roots/list_changed`。131`CLAUDE_PROJECT_DIR` 是稳定的项目根目录，在会话中添加或删除工作目录时不会更改。限制自己的文件系统访问到一组允许目录的服务器应该改为实现 MCP `roots/list` 请求。Claude Code 使用会话的启动目录加上您使用 `--add-dir`、`/add-dir` 或 `additionalDirectories` 设置授予的每个 [额外工作目录](/docs/zh-CN/permissions#working-directories) 来回答 `roots/list`。当该集合更改时，Claude Code 发送 `notifications/roots/list_changed`。在 v2.1.203 之前，`roots/list` 仅返回启动目录，Claude Code 不发送 `notifications/roots/list_changed`。

130 132

131此变量在服务器的环境中设置，而不是在 Claude Code 自己的环境中，因此通过项目范围的 `.mcp.json` 条目或本地或用户范围的 `~/.claude.json` 中的服务器条目中的 `command` 或 `args` 中的 `${VAR}` 扩展来引用它需要默认值，例如 `${CLAUDE_PROJECT_DIR:-.}`。插件提供的 MCP 配置直接替换 `${CLAUDE_PROJECT_DIR}` 并且不需要默认值。133此变量在服务器的环境中设置，而不是在 Claude Code 自己的环境中，因此通过项目范围的 `.mcp.json` 条目或 `~/.claude.json` 中的本地或用户范围服务器条目中的 `command` 或 `args` 中的 `${VAR}` 扩展来引用它需要默认值，例如 `${CLAUDE_PROJECT_DIR:-.}`。插件提供的 MCP 配置直接替换 `${CLAUDE_PROJECT_DIR}` 并且不需要默认值。

132 134

133```bash theme={null}135```bash theme={null}

134# 基本语法136# 基本语法

142<Note>144<Note>

143 **重要：用 `--` 分隔服务器参数**145 **重要：用 `--` 分隔服务器参数**

144 146

145 对于 stdio 服务器，`--`（双破折号）将 Claude 自己的选项（如 `--transport`、`--env` 和 `--scope`）与运行服务器的命令和参数分开。`--` 之后的所有内容都原封不动地传递给服务器。147 对于 stdio 服务器，`--`（双破折号）将 Claude 自己的选项（例如 `--transport`、`--env` 和 `--scope`）与运行服务器的命令和参数分开。`--` 之后的所有内容都原封不动地传递给服务器。

146 148

147 例如：149 例如：

148 150

149 * `claude mcp add --transport stdio myserver -- npx server` → 运行 `npx server`151 * `claude mcp add --transport stdio myserver -- npx server` → 运行 `npx server`

150 * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → 运行 `python server.py --port 8080`，环境中有 `KEY=value`152 * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → 使用环境中的 `KEY=value` 运行 `python server.py --port 8080`

151 153

152 没有 `--`，Claude Code 会尝试将服务器的标志（如上面的 `--port`）解析为自己的选项。154 没有 `--`，Claude Code 会尝试将服务器的标志（如上面的 `--port`）解析为自己的选项。

153 155

154 `--env` 接受多个 `KEY=value` 对。如果服务器名称直接跟在 `--env` 之后，CLI 会将名称读取为另一对并拒绝它，因此在 `--env` 和服务器名称之间至少放置一个其他选项，如 `--transport stdio`。156 `--env` 接受多个 `KEY=value` 对。如果服务器名称直接跟在 `--env` 之后，CLI 会将该名称读取为另一对并拒绝它，因此在 `--env` 和服务器名称之间至少放置一个其他选项，例如 `--transport stdio`。

155</Note>157</Note>

156 158

157<h3 id="option-4-add-a-remote-websocket-server">159<h3 id="option-4-add-a-remote-websocket-server">

158 选项 4：添加远程 WebSocket 服务器160 选项 4：添加远程 WebSocket 服务器

159</h3>161</h3>

160 162

161WebSocket 服务器保持持久的双向连接，适合推送事件给 Claude 的远程 MCP 服务器。当您的服务器仅响应请求时，请改用 HTTP，因为 HTTP 支持 OAuth 和 `claude mcp add --transport` 标志，而 WebSocket 都不支持。163WebSocket 服务器保持持久的双向连接，适合主动向 Claude 推送事件的远程 MCP 服务器。当您的服务器仅响应请求时，请改用 HTTP，因为 HTTP 支持 OAuth 和 `claude mcp add --transport` 标志，而 WebSocket 都不支持。

162 164

163在 `.mcp.json` 中或使用 `claude mcp add-json` 配置 WebSocket 服务器：165在 `.mcp.json` 中或使用 `claude mcp add-json` 配置 WebSocket 服务器：

164 166

167 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'169 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

168```170```

169 171

170`type: "ws"` 条目接受与 `http` 相同的 `url`、`headers`、`headersHelper`、`timeout` 和 `alwaysLoad` 字段。身份验证仅限于标头，因此在 `headers` 中传递静态令牌或在连接时使用 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 生成一个。`claude mcp add --transport` 标志不接受 `ws`。172`type: "ws"` 条目接受与 `http` 相同的 `url`、`headers`、`headersHelper`、`timeout` 和 `alwaysLoad` 字段。身份验证仅限于标头，因此在 `headers` 中传递静态令牌或使用 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 在连接时生成一个。`claude mcp add --transport` 标志不接受 `ws`。

171 173

172<h3 id="add-a-server-from-setup-instructions-written-for-another-client">174<h3 id="add-a-server-from-setup-instructions-written-for-another-client">

173 从为另一个客户端编写的设置说明添加服务器175 从为另一个客户端编写的设置说明添加服务器

174</h3>176</h3>

175 177

176MCP 服务器不特定于 Claude Code，因此服务器的设置说明可能是为 Claude Desktop、Cursor 或另一个 MCP 客户端编写的，并且不提供 `claude mcp add` 命令。要添加服务器，请在这些说明中查找以下三项之一：178MCP 服务器不特定于 Claude Code，因此服务器的设置说明可能是为 Claude Desktop、Cursor 或另一个 MCP 客户端编写的，并且不提供 `claude mcp add` 命令。要添加服务器，请在这些说明中查找 URL、启动命令或 JSON 块：

177 179

178* **URL**，例如 `https://mcp.example.com/mcp`：服务器是远程的。180* **URL**，例如 `https://mcp.example.com/mcp`：服务器是远程的。

179* **启动命令**，例如 `npx -y @example/mcp-server`：服务器在您的机器上运行。181* **启动命令**，例如 `npx -y @example/mcp-server`：服务器在您的机器上运行。

180* **`mcpServers` JSON 块**：为另一个客户端的设置文件编写的配置。182* **`mcpServers` JSON 块**：为另一个客户端的设置文件编写的配置。

181 183

182每一项都是 [安装 MCP 服务器](#installing-mcp-servers) 中四个选项之一接受的输入。找到您下面拥有的形状，将其转换为 Claude Code 接受的命令。除非您添加 `--scope project` 或 `--scope user`，否则每个命令都写入 [本地范围](#local-scope)。184每一个都是 [安装 MCP 服务器](#installing-mcp-servers) 中四个选项之一接受的输入。找到您下面拥有的形状，将其转换为 Claude Code 接受的命令。除非您添加 `--scope project` 或 `--scope user`，否则每个命令都写入 [本地范围](#local-scope)。

183 185

184<h4 id="from-a-url">186<h4 id="from-a-url">

185 从 URL187 从 URL

186</h4>188</h4>

187 189

188URL 表示服务器是远程的。对于 `https://` 端点，使用 `--transport http` 添加它，或在说明说端点使用 SSE 时遵循 [选项 2](#option-2-add-a-remote-sse-server)。对于 `wss://` 端点，改用 [选项 4](#option-4-add-a-remote-websocket-server)，因为 `--transport` 不接受 `ws`：190URL 表示服务器是远程的。对于 `https://` 端点，使用 `--transport http` 添加它，或在说明说端点使用 SSE 时遵循 [选项 2](#option-2-add-a-remote-sse-server)。对于 `wss://` 端点，改为使用 [选项 4](#option-4-add-a-remote-websocket-server)，因为 `--transport` 不接受 `ws`：

189 191

190```bash theme={null}192```bash theme={null}

191claude mcp add --transport http example https://mcp.example.com/mcp193claude mcp add --transport http example https://mcp.example.com/mcp

197 从 `npx`、`uvx` 或二进制命令199 从 `npx`、`uvx` 或二进制命令

198</h4>200</h4>

199 201

200启动命令表示服务器作为本地 stdio 进程运行。将整个命令放在 `--` 之后，以便 Claude Code 将标志（如 `-y`）传递给启动服务器的命令，而不是将它们读取为自己的选项。使用 `--env` 传递说明要求的任何环境变量，在服务器名称之后和 `--` 之前：202启动命令表示服务器作为本地 stdio 进程运行。将整个命令放在 `--` 之后，以便 Claude Code 将标志（例如 `-y`）传递给启动服务器的命令，而不是将其读取为自己的选项。使用 `--env` 传递说明要求的任何环境变量，在服务器名称之后和 `--` 之前：

201 203

202```bash theme={null}204```bash theme={null}

203claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server205claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

209 从 `mcpServers` JSON 块211 从 `mcpServers` JSON 块

210</h4>212</h4>

211 213

212为另一个 MCP 客户端（如 Claude Desktop）编写的 `mcpServers` 块使用 Claude Code 读取的包装键和条目形状。将 `mcpServers` 内的对象传递给 `claude mcp add-json`，而不是包装器。两个条目需要先修复：214为另一个 MCP 客户端（例如 Claude Desktop）编写的 `mcpServers` 块使用 Claude Code 读取的包装器密钥和条目形状。将 `claude mcp add-json` 传递给 `mcpServers` 内的对象，而不是包装器。两个条目需要先修复：

213 215

214* **没有 `type` 的 `url`**：添加 `"type": "http"`、`"type": "sse"` 或 `"type": "ws"` 以匹配端点。Claude Code 将没有 `type` 的条目读取为 stdio 服务器，因此没有 `type` 的 `url` 条目会失败。216* **没有 `type` 的 `url`**：添加 `"type": "http"`、`"type": "sse"` 或 `"type": "ws"` 以匹配端点。Claude Code 将没有 `type` 的条目读取为 stdio 服务器，因此没有 `type` 的 `url` 条目会失败。

215* **具有字母、数字、连字符和下划线以外的字符的键**：选择仅使用这些字符的服务器名称。否则键是服务器名称。217* **具有除字母、数字、连字符和下划线以外的字符的密钥**：选择仅使用这些字符的服务器名称。否则密钥是服务器名称。

216 218

217例如，此块：219例如，此块：

218 220

233claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'235claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

234```236```

235 237

236[从 JSON 配置添加 MCP 服务器](#add-mcp-servers-from-json-configuration) 涵盖 `add-json` 的 shell 转义和 `--scope` 标志。要改为与您的团队共享服务器，请添加 `--scope project`，或在项目根目录的 `.mcp.json` 下的 `mcpServers` 中添加条目并提交它。[项目范围](#project-scope) 涵盖 Claude Code 如何加载和批准该文件。238[从 JSON 配置添加 MCP 服务器](#add-mcp-servers-from-json-configuration) 涵盖 `add-json` 的 shell 转义和 `--scope` 标志。要与您的团队共享服务器，请改为添加 `--scope project`，或在项目根目录的 `.mcp.json` 下的 `mcpServers` 中添加条目并提交它。[项目范围](#project-scope) 涵盖 Claude Code 如何加载和批准该文件。

237 239

238每个 `claude mcp add` 和 `claude mcp add-json` 命令都会打印一个 `Added ...` 行。要检查 Claude Code 是否已连接，请运行 `claude mcp get <name>`；[服务器状态](#server-status) 涵盖它显示的状态和 `.mcp.json` 服务器的批准步骤。240每个 `claude mcp add` 和 `claude mcp add-json` 命令都会打印一行 `Added ...`。要检查 Claude Code 是否已连接，请运行 `claude mcp get <name>`；[服务器状态](#server-status) 涵盖它显示的状态和 `.mcp.json` 服务器的批准步骤。

239 241

240<h3 id="managing-your-servers">242<h3 id="managing-your-servers">

241 管理您的服务器243 管理您的服务器

267 269

268此列表中的状态报告配置决策而不是连接尝试，因此 Claude Code 在不连接到服务器的情况下打印它们：270此列表中的状态报告配置决策而不是连接尝试，因此 Claude Code 在不连接到服务器的情况下打印它们：

269 271

270* ``⏸ Pending approval (run `claude` to approve)``：来自 `.mcp.json` 的项目范围服务器，您尚未批准。Claude Code 在 `claude mcp list` 和 `claude mcp get <name>` 中都显示它。运行 `claude` 交互式地审查和批准它。272* ``⏸ Pending approval (run `claude` to approve)``：来自 `.mcp.json` 的项目范围服务器，您尚未批准。Claude Code 在 `claude mcp list` 和 `claude mcp get <name>` 中都显示它。以交互方式运行 `claude` 来审查和批准它。

271* `✘ Rejected (see disabledMcpjsonServers in settings)`：由 [`disabledMcpjsonServers`](/docs/zh-CN/settings-reference#disabledmcpjsonservers) 条目拒绝的 `.mcp.json` 服务器。Claude Code 仅在 `claude mcp get <name>` 中显示它。273* `✘ Rejected (see disabledMcpjsonServers in settings)`：由 [`disabledMcpjsonServers`](/docs/zh-CN/settings-reference#disabledmcpjsonservers) 条目拒绝的 `.mcp.json` 服务器。Claude Code 仅在 `claude mcp get <name>` 中显示它。

272* `⊘ Disabled for this project (re-enable via /mcp)`：项目的 [`disabledMcpServers`](#disable-a-server-without-removing-it) 列表命名的服务器。Claude Code 在 `claude mcp list` 和 `claude mcp get <name>` 中都显示它。从 `/mcp` 面板打开服务器。在 v2.1.238 之前，两个命令都连接到禁用的服务器以进行健康检查并报告连接结果。274* `⊘ Disabled for this project (re-enable via /mcp)`：项目的 [`disabledMcpServers`](#disable-a-server-without-removing-it) 列表命名的服务器。Claude Code 在 `claude mcp list` 和 `claude mcp get <name>` 中都显示它。从 `/mcp` 面板打开服务器。在 v2.1.238 之前，两个命令都连接到禁用的服务器以进行健康检查并报告连接结果。

273 275

274WebSocket 服务器不会出现在 `claude mcp list` 输出中。使用 `claude mcp get <name>` 或 `/mcp` 面板检查它们。276WebSocket 服务器不会出现在 `claude mcp list` 输出中。使用 `claude mcp get <name>` 或 `/mcp` 面板来检查它们。

275 277

276<h4 id="project-server-approvals-and-workspace-trust">278<h4 id="project-server-approvals-and-workspace-trust">

277 项目服务器批准和工作区信任279 项目服务器批准和工作区信任

285* 托管设置287* 托管设置

286* 使用 `--settings` 传递的设置288* 使用 `--settings` 传递的设置

287 289

288Claude Code 也应用来自未跟踪的 `.claude/settings.local.json` 的批准，但它运行 git 来检查文件是否被跟踪，并且仅在 [受信任的文件夹](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust) 中运行该检查。在您从未信任的文件夹中，Claude Code 等待信任对话后才应用文件的批准，除非文件夹是您自己的配置主目录：您的主目录，或一个您已设置为 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars) 的 `.claude` 的目录。在 v2.1.207 之前，Claude Code 即使在您从未信任的文件夹中也应用来自未跟踪的 `.claude/settings.local.json` 的批准。290Claude Code 也应用来自未跟踪的 `.claude/settings.local.json` 的批准，但它运行 git 来检查文件是否被跟踪，并且仅在 [受信任的文件夹](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust) 中运行该检查。在您从未信任的文件夹中，Claude Code 等待信任对话后才应用文件的批准，除非该文件夹是您自己的配置主目录：您的主目录，或一个您已设置为 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars) 的 `.claude` 的目录。在 v2.1.207 之前，Claude Code 即使在您从未信任的文件夹中也应用来自未跟踪的 `.claude/settings.local.json` 的批准。

289 291

290任何设置文件中的 `disabledMcpjsonServers` 条目仍然拒绝服务器。292任何设置文件中的 `disabledMcpjsonServers` 条目仍然拒绝服务器。

291 293

297 299

298发现缓存默认关闭，除非逐步推出已为您的帐户启用它。设置 [`MCP_DISCOVERY_CACHE=1`](/docs/zh-CN/env-vars) 以打开它，或设置为 `0` 以在推出启用它时保持关闭。在 v2.1.238 之前，缓存默认打开。300发现缓存默认关闭，除非逐步推出已为您的帐户启用它。设置 [`MCP_DISCOVERY_CACHE=1`](/docs/zh-CN/env-vars) 以打开它，或设置为 `0` 以在推出启用它时保持关闭。在 v2.1.238 之前，缓存默认打开。

299 301

300`/mcp` 中服务器菜单中的两个操作也会影响该服务器的缓存条目：302当您从 `/mcp` 中的服务器菜单中选择 **Disable** 或 **Clear authentication** 时，Claude Code 也会丢弃该服务器的缓存条目。**Reconnect** 在已连接或失败的服务器上也会丢弃它；在 `cached` 服务器上，**Reconnect** 现在连接服务器并保留条目。丢弃条目后，Claude Code 从服务器而不是从缓存获取服务器的工具列表。

~~301~~

302* **重新连接**：在 `cached` 服务器上，Claude Code 现在连接它而不是在其第一个工具调用时连接，并保留条目。在连接或失败的服务器上，Claude Code 重新连接它并也丢弃条目。

303* **清除身份验证**：Claude Code 撤销服务器的身份验证并也丢弃条目。

304 303

305丢弃条目后，Claude Code 从服务器而不是从缓存获取服务器的工具列表。304当服务器的状态为 `✘ Failed to connect` 时，`claude mcp list` 将失败详情附加到该状态行，`claude mcp get <name>` 在 `Issue:` 行上显示它：HTTP 状态或错误代码，加上服务器返回的任何错误文本。`/mcp` 中的服务器详情视图在其 `Issue:` 行中包含相同的服务器报告的文本。Claude Code 从此详情中编辑类似凭证的文本，并且永远不包括扩展的服务器 URL，它可能携带机密。Claude Code 不向 `✘ Connection error` 状态附加详情，因为它会打印的异常文本可以嵌入该 URL。在 v2.1.219 之前，两个命令仅显示裸失败状态，没有状态代码或服务器的错误文本。

306 305

307当服务器的状态为 `✘ Failed to connect` 时，`claude mcp list` 将失败详情附加到该状态行，`claude mcp get <name>` 在 `Issue:` 行上显示它：HTTP 状态或错误代码，加上服务器返回的任何错误文本。`/mcp` 中服务器的详情视图在其 `Issue:` 行中包含相同的服务器报告的文本。Claude Code 从此详情中编辑类似凭证的文本，并且从不包含扩展的服务器 URL，它可能携带机密。Claude Code 不向 `✘ Connection error` 状态附加详情，因为它会打印的异常文本可以嵌入该 URL。在 v2.1.219 之前，两个命令仅显示裸失败状态，没有状态代码或服务器的错误文本。306当您从 `/mcp` 完成身份验证且连接仍然因 HTTP 状态或传输错误代码失败时，Claude Code 在尝试后打印的消息中添加该代码和服务器 URL 的来源。来源是方案和主机，加上 URL 命名的端口（如果有），例如 `https://mcp.example.com`。

308 307

309当您从 `/mcp` 完成身份验证且连接仍然因 HTTP 状态或传输错误代码而失败时，Claude Code 在尝试后打印的消息中添加该代码和服务器 URL 的来源。来源是方案和主机，加上 URL 命名的端口（如 `https://mcp.example.com`）。308* 路径和查询永远不会出现在该消息中。

309* 对于本地、项目或用户 [范围](#mcp-installation-scopes) 中的服务器或托管 MCP 配置中的服务器，来源显示在该配置中写入的主机，因此主机中的 `${VAR}` 引用在消息中不会展开。

310* 对于没有状态或错误代码的失败，Claude Code 显示没有来源的错误文本。

310 311

311* 路径和查询从不出现在该消息中。312配置为空 `url` 的远程服务器在 `/mcp`、`claude mcp list` 和 [`/plugin`](/docs/zh-CN/plugins/install) 管理器中显示为 `not configured`，Claude Code 不尝试连接到它。插件可以包含这样的占位符条目，用于您稍后配置的连接器，因此 Claude Code 不会将其报告为错误或设置问题。`/mcp` 中的服务器详情视图读取 `No URL configured for this server`；设置条目的 `url` 以连接它。在 v2.1.208 之前，Claude Code 将空 `url` 报告为配置问题，并提示重新连接。

312* 对于本地、项目、用户 [范围](#mcp-installation-scopes) 中的服务器或托管 MCP 配置中的服务器，来源显示该配置中写入的主机，因此主机中的 `${VAR}` 引用在消息中不会展开。

313* 对于没有状态或错误代码的失败，Claude Code 显示错误文本而不显示来源。

~~314~~

315配置为空 `url` 的远程服务器在 `/mcp`、`claude mcp list` 和 [`/plugin`](/docs/zh-CN/plugins/install) 管理器中显示为 `not configured`，Claude Code 不尝试连接到它。插件可以包含这样的占位符条目，用于您稍后配置的连接器，因此 Claude Code 不将其报告为错误或设置问题。`/mcp` 中服务器的详情视图读取 `No URL configured for this server`；设置条目的 `url` 以连接它。在 v2.1.208 之前，Claude Code 将空 `url` 报告为配置问题，并提示重新连接。

316 313

317<h4 id="configuration-warnings">314<h4 id="configuration-warnings">

318 配置警告315 配置警告

320 317

321Claude Code 警告以下配置问题。每个条目说明 Claude Code 检查什么以及如何清除警告：318Claude Code 警告以下配置问题。每个条目说明 Claude Code 检查什么以及如何清除警告：

322 319

323* **隐藏的空格**：当 MCP 配置值携带隐藏的前导或尾随空格时，Claude Code 发出警告，这通常来自粘贴带有尾随换行符的令牌。Claude Code 检查 `command`、`url`、每个 `args` 条目以及 `env` 和 `headers` 下的值和键名。Claude Code 在 `claude mcp list` 输出和 `/mcp` 中显示警告，命名受影响的字段而不回显其值，例如 `Leading or trailing whitespace in: headers.Authorization`。Claude Code 不修剪空格并完全按照写入的方式使用值，因此编辑配置以删除它。320* **隐藏的空白**：当 MCP 配置值携带隐藏的前导或尾随空白时，Claude Code 发出警告，这通常来自粘贴带有尾随换行符的令牌。Claude Code 检查 `command`、`url`、每个 `args` 条目以及 `env` 和 `headers` 下的值和密钥名称。Claude Code 在 `claude mcp list` 输出和 `/mcp` 中显示警告，命名受影响的字段而不回显其值，例如 `Leading or trailing whitespace in: headers.Authorization`。Claude Code 不修剪空白并完全按照写入的方式使用值，因此编辑配置以删除它。

324* **在多个范围中具有相同名称**：如果您在多个 [范围](#mcp-installation-scopes) 中定义相同的服务器名称，具有不同的端点，Claude Code 在 `claude mcp list` 输出和 `/mcp` 中警告冲突。Claude Code 按端点存储 OAuth 登录，因此当您对在一个项目中加载的定义进行身份验证时，您仍然需要在另一个项目中单独登录，其中不同的定义加载。保留您想要的端点并使用 `claude mcp remove <name> --scope <scope>` 删除其他端点。在警告中，Claude Code 引用每个范围的端点，如您的配置中写入的那样，带有 [`${VAR}` 引用](#environment-variable-expansion-in-mcp-json) 未展开，因此它从不显示已解析的值，例如 API 密钥。321* **在多个范围中具有相同名称**：如果您在多个 [范围](#mcp-installation-scopes) 中定义相同的服务器名称，具有不同的端点，Claude Code 在 `claude mcp list` 输出和 `/mcp` 中警告冲突。Claude Code 按端点存储 OAuth 登录，因此当您对在一个项目中加载的定义进行身份验证时，您仍然需要在另一个项目中单独登录，其中不同的定义加载。保留您想要的端点并使用 `claude mcp remove <name> --scope <scope>` 删除其他端点。在警告中，Claude Code 引用每个范围的端点，如您的配置中所写，带有 [`${VAR}` 引用](#environment-variable-expansion-in-mcp-json) 未展开，因此它永远不会显示已解析的值，例如 API 密钥。

325* **保留名称**：Claude Code 保留其内置服务器的名称，包括 `workspace`、`claude-in-chrome`、`computer-use`、`Claude Preview` 和 `Claude Browser`。如果您的配置定义了具有保留名称的服务器，Claude Code 在加载时跳过它并显示警告，要求您重命名它。`claude mcp add` 拒绝带有错误的保留名称。`Claude Preview` 和 `Claude Browser` 都命名 [Claude Code 桌面应用的预览窗格](/docs/zh-CN/desktop#preview-your-app) 使用的内置服务器。在 v2.1.205 之前，`Claude Browser` 未被保留，因此用户配置的服务器可以在该名称下注册。322* **保留名称**：Claude Code 保留其内置服务器的名称，包括 `workspace`、`claude-in-chrome`、`computer-use`、`Claude Preview` 和 `Claude Browser`。如果您的配置定义具有保留名称的服务器，Claude Code 在加载时跳过它并显示警告，要求您重命名它。`claude mcp add` 拒绝保留名称并出现错误。`Claude Preview` 和 `Claude Browser` 都命名 [Claude Code 桌面应用的预览窗格](/docs/zh-CN/desktop#preview-your-app) 使用的内置服务器。在 v2.1.205 之前，`Claude Browser` 未被保留，因此用户配置的服务器可以在该名称下注册。

326* **缺少环境变量**：如果 [`${VAR}` 引用](#environment-variable-expansion-in-mcp-json) 在服务器的配置中命名一个未设置且没有 `:-default` 的变量，Claude Code 在 `claude mcp list` 输出和 `/mcp` 中警告，命名变量，并仍然加载服务器，`${VAR}` 文本未展开。设置变量或添加 `${VAR:-default}` 回退。在远程服务器的 `url` 和 `headers` 中，某些凭证变量 [读取为空](#credential-variables-that-read-as-empty) 而不是，没有警告。323* **缺少环境变量**：如果服务器配置中的 [`${VAR}` 引用](#environment-variable-expansion-in-mcp-json) 命名未设置且没有 `:-default` 的变量，Claude Code 在 `claude mcp list` 输出和 `/mcp` 中警告，命名变量，并仍然使用 `${VAR}` 文本未展开加载服务器。设置变量或添加 `${VAR:-default}` 回退。在远程服务器的 `url` 和 `headers` 中，某些凭证变量 [读取为空](#credential-variables-that-read-as-empty) 而不是警告。

327 324

328<h4 id="tool-availability">325<h4 id="tool-availability">

329 工具可用性326 工具可用性

330</h4>327</h4>

331 328

332`/mcp` 面板在每个连接的服务器旁边显示工具计数，并标记声称工具功能但不公开工具的服务器。329`/mcp` 面板在每个已连接的服务器旁边显示工具计数，并标记声称工具功能但不公开工具的服务器。

333 330

334如果您的请求需要来自仍在后台连接的服务器的工具，Claude 会在继续之前等待该服务器。等待的方式取决于您的配置：331如果您的请求需要来自仍在后台连接的服务器的工具，Claude 会在继续之前等待该服务器。等待的方式取决于您的配置：

335 332

336* **使用 [工具搜索](#scale-with-mcp-tool-search)（默认）**：等待发生在 `ToolSearch` 调用内。333* **使用 [工具搜索](#scale-with-mcp-tool-search)（默认）**：等待发生在 `ToolSearch` 调用内。

337* **不使用工具搜索**：Claude 改用 `WaitForMcpServers` 工具。不使用工具搜索的配置包括自定义 `ANTHROPIC_BASE_URL`、`ENABLE_TOOL_SEARCH=false` 和 Google Cloud 的 Agent Platform 上早于 Claude 4.5 代的模型。334* **不使用工具搜索**：Claude 改为使用 `WaitForMcpServers` 工具。不使用工具搜索的配置包括自定义 `ANTHROPIC_BASE_URL`、`ENABLE_TOOL_SEARCH=false` 和 Google Cloud 的 Agent Platform 上早于 Claude 4.5 代的模型。

338* **在 Microsoft Foundry [部署托管在 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)**：Claude 开始使用工具搜索路径而不是 `WaitForMcpServers`，因为 Claude Code 仅从 API 发现部署的服务器端拒绝。在 Claude Code 将该部署切换到 [前期加载](#scale-with-mcp-tool-search) 后，来自完成连接的服务器的工具在 Claude 的下一个请求中变为可用。335* **在 Microsoft Foundry [部署在 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)**：Claude 在工具搜索路径上启动而不是使用 `WaitForMcpServers`，因为 Claude Code 仅从 API 发现部署的服务器端拒绝。Claude Code 将该部署切换到 [前期加载](#scale-with-mcp-tool-search) 后，来自完成连接的服务器的工具在 Claude 的下一个请求中变为可用。

339 336

340启用工具搜索后，当服务器在 Claude 工作时完成连接时，Claude Code 在同一轮的下一个请求中将服务器的工具名称列出给 Claude。Claude 然后可以搜索和调用这些工具，而无需等待您的下一条消息。337启用工具搜索后，当服务器在 Claude 工作时完成连接时，Claude Code 在同一轮的下一个请求中将服务器的工具名称列出给 Claude。Claude 然后可以搜索和调用这些工具，而无需等待您的下一条消息。

341 338

347 344

348切换服务器时，Claude Code 在 `~/.claude.json` 中按项目记录您的选择，在两个涵盖不相交服务器集的列表之一中：345切换服务器时，Claude Code 在 `~/.claude.json` 中按项目记录您的选择，在两个涵盖不相交服务器集的列表之一中：

349 346

350* `disabledMcpServers`：用户配置的服务器、插件服务器、您的组织 [通过托管设置提供](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings) 的服务器、Claude Code [自己获取](#how-connectors-reach-claude-code) 的 claude.ai 连接器以及默认打开的内置服务器的选择退出列表。Claude Code 不连接您在此处列出的服务器。当您使用 [禁用 claude.ai 连接器](#disable-claude-ai-connectors) 中描述的按项目 `/mcp` 切换禁用 claude.ai 连接器时，Claude Code 在此列表下使用其显示名称（例如 `claude.ai Slack`）写入它。347* `disabledMcpServers`：用户配置的服务器、插件服务器、您的组织 [通过托管设置提供](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings) 的服务器、Claude Code [自己获取](#how-connectors-reach-claude-code) 的 claude.ai 连接器以及默认打开的内置服务器的选择退出列表。Claude Code 不连接到您在此处列出的服务器。当您使用 [禁用 claude.ai 连接器](#disable-claude-ai-connectors) 中描述的按项目 `/mcp` 切换禁用 claude.ai 连接器时，Claude Code 在此列表下使用其显示名称（例如 `claude.ai Slack`）写入它。

351* `enabledMcpServers`：默认关闭的内置服务器（如 `computer-use`）的选择加入列表。Claude Code 仅当您在此处列出时才连接默认关闭的服务器。348* `enabledMcpServers`：默认关闭的内置服务器（例如 `computer-use`）的选择加入列表。Claude Code 仅当您在此处列出它时才连接到默认关闭的服务器。

352 349

353Claude Code 为每个服务器查询恰好两个列表之一，因此两个列表都不会覆盖另一个。如果您将常规服务器添加到 `enabledMcpServers`，或将默认关闭的内置服务器添加到 `disabledMcpServers`，Claude Code 会忽略该条目。350Claude Code 为每个服务器查询恰好两个列表之一，因此两个列表都不会覆盖另一个。如果您将常规服务器添加到 `enabledMcpServers`，或将默认关闭的内置服务器添加到 `disabledMcpServers`，Claude Code 会忽略该条目。

354 351

360 357

361Claude Code 通过两个客户端运行时之一连接到 MCP 服务器。v1 运行时基于 MCP TypeScript SDK 1.x。v2 运行时是 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 上的相同代码，它添加了 MCP 协议修订版 2026-07-28。本页的其余部分适用于两个运行时，除非某个部分命名 v2 运行时。358Claude Code 通过两个客户端运行时之一连接到 MCP 服务器。v1 运行时基于 MCP TypeScript SDK 1.x。v2 运行时是 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 上的相同代码，它添加了 MCP 协议修订版 2026-07-28。本页的其余部分适用于两个运行时，除非某个部分命名 v2 运行时。

362 359

363Claude Code 在每次启动时选择一个运行时，并保持到您退出。在 Claude Code v2.1.232 或更高版本上，在 [获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) 的会话中，它使用 v2 运行时。360Claude Code 每次启动时选择一个运行时，并在您退出前保持它。在 [获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) 的会话中，它在 Claude Code v2.1.232 或更高版本上使用 v2 运行时。

364 361

365在不获取功能标志的会话中，Claude Code 在 Claude Code v2.1.274 或更高版本上默认使用 v2 运行时：362在不获取功能标志的会话中，Claude Code 在 Claude Code v2.1.274 或更高版本上默认使用 v2 运行时：

366 363

370 367

371在 v2 上，Claude Code 也：368在 v2 上，Claude Code 也：

372 369

373* 询问 HTTP 服务器是否支持较新的修订版，并与支持的服务器一起使用它。它也询问在获取功能标志的会话中的 claude.ai 连接器服务器。要让它询问 stdio 服务器或在每个会话中询问连接器服务器，请设置 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 为 `auto`。它像 v1 一样连接到每个其他服务器。370* 询问 HTTP 服务器是否支持较新的修订版，并与支持的服务器一起使用它。它也在获取功能标志的会话中询问 claude.ai 连接器服务器。要让它询问 stdio 服务器或每个会话中的连接器服务器，请设置 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 为 `auto`。它连接到每个其他服务器，如 v1 所做的那样。

374* 从 [它保持打开的流](#notification-streams-on-the-v2-runtime) 上的较新修订版的服务器接收 `list_changed` 通知。371* 从 [它保持打开的流](#notification-streams-on-the-v2-runtime) 上的较新修订版的服务器接收 `list_changed` 通知。

375* 不注册在较新修订版上连接的 [通道](#push-messages-with-channels) 服务器，因为该修订版无法携带通道消息。372* 不注册在较新修订版上连接的 [通道](#push-messages-with-channels) 服务器，因为该修订版无法携带通道消息。

376* 失败 [MCP OAuth 登录](#authenticate-with-remote-mcp-servers)，其授权响应命名意外的发行者。373* 失败 [MCP OAuth 登录](#authenticate-with-remote-mcp-servers)，其授权响应命名意外的发行者。

377 374

378Anthropic 可以使用 Claude Code 获取的功能标志将特定服务器保持在较早的协议上，或将其从该流中移除。375Anthropic 可以使用 Claude Code 获取的功能标志将特定服务器保持在较早的协议上，或关闭该流。

379 376

380要自己选择运行时，请设置 [`MCP_SDK_GENERATION`](/docs/zh-CN/env-vars) 为 `v1` 或 `v2`。要决定 Claude Code 是否询问，请设置 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 为 `auto` 或 `legacy`。377要自己选择运行时，请设置 [`MCP_SDK_GENERATION`](/docs/zh-CN/env-vars) 为 `v1` 或 `v2`。要决定 Claude Code 是否询问，请设置 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 为 `auto` 或 `legacy`。

381 378

393 390

394在 [v2 运行时](#mcp-client-runtimes) 上，Claude Code 从 [它保持打开的流](#notification-streams-on-the-v2-runtime) 上的较新协议修订版的服务器接收 `list_changed` 通知。当流关闭时，Claude Code 重新打开它，有两个限制：391在 [v2 运行时](#mcp-client-runtimes) 上，Claude Code 从 [它保持打开的流](#notification-streams-on-the-v2-runtime) 上的较新协议修订版的服务器接收 `list_changed` 通知。当流关闭时，Claude Code 重新打开它，有两个限制：

395 392

396* **流在 10 秒内再次关闭**：Claude Code 重新打开它最多三次，然后停止该连接。393* **流在 10 秒内再次关闭**：Claude Code 最多重新打开三次，然后停止该连接。

397* **流保持打开超过 10 秒，然后关闭**，如无服务器主机的流通常所做的那样：在一小时内五次重新打开后，Claude Code 等待大约六小时才能进行下一次。394* **流保持打开超过 10 秒，然后关闭**，如流到无服务器主机通常所做的那样：在一小时内五次重新打开后，Claude Code 在下一次之前等待约六小时。

398 395

399在流重新打开之前，您保留服务器的最后获取的工具、提示和资源。要更快地获取其更改，请从 `/mcp` 重新连接服务器。396在流重新打开之前，您保留服务器的最后获取的工具、提示和资源。要更快地获取其更改，请从 `/mcp` 重新连接服务器。

400 397

410 407

411Claude Code 使用指数退避重新连接断开的远程服务器：最多五次尝试，从一秒延迟开始，每次加倍。您看到的内容取决于您如何运行 Claude Code：408Claude Code 使用指数退避重新连接断开的远程服务器：最多五次尝试，从一秒延迟开始，每次加倍。您看到的内容取决于您如何运行 Claude Code：

412 409

413* **在交互式会话中**：`/mcp` 在 Claude Code 重新连接时显示服务器为待处理。在五次失败尝试后，Claude Code 将服务器标记为失败，或在服务器需要再次授权时标记为需要身份验证。您可以从 `/mcp` 手动重试。410* **在交互式会话中**：`/mcp` 在 Claude Code 重新连接时显示服务器为待处理。在五次失败尝试后，Claude Code 将服务器标记为失败，或在服务器需要再次授权时标记为需要身份验证。当它将服务器标记为失败时，您会看到 `MCP server "<name>" disconnected · open /mcp to reconnect` 通知。您可以从 `/mcp` 手动重试。

414* **在 [`claude -p`](/docs/zh-CN/headless) 运行和 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 会话中**：Claude Code 按相同的计划重新连接，没有 `/mcp` 面板显示尝试。411* **在 [`claude -p`](/docs/zh-CN/headless) 运行和 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 会话中**：Claude Code 按相同的计划重新连接，没有 `/mcp` 面板显示尝试。

415 412

416<h4 id="failed-first-connections">413<h4 id="failed-first-connections">

417 失败的首次连接414 失败的首次连接

418</h4>415</h4>

419 416

420当 HTTP 或 SSE 服务器的首次连接因瞬时错误（如 5xx 响应、连接被拒绝或超时）而失败时，Claude Code 最多重试三次。如果连接仍然失败，Claude Code 将服务器标记为失败。Claude Code 在启动时和在会话中期添加服务器时以这种方式重试。这包括 Claude Code 从其配置添加到 [云会话](/docs/zh-CN/claude-code-on-the-web) 的服务器和您使用 Agent SDK 的 [`setMcpServers()`](/docs/zh-CN/agent-sdk/typescript) 添加的服务器。417当 HTTP 或 SSE 服务器的首次连接因瞬时错误（例如 5xx 响应、连接被拒绝或超时）失败时，Claude Code 最多重试三次。如果连接仍然失败，Claude Code 将服务器标记为失败。Claude Code 在启动时和在会话中期添加服务器时以这种方式重试。这包括 Claude Code 从其配置添加到 [云会话](/docs/zh-CN/claude-code-on-the-web) 的服务器和您使用 Agent SDK 的 [`setMcpServers()`](/docs/zh-CN/agent-sdk/typescript) 添加的服务器。

421 418

422Claude Code 在这些情况下不重试：419Claude Code 在这些情况下不重试：

423 420

462 * 使用 `/mcp` 对需要 OAuth 2.0 身份验证的远程服务器进行身份验证459 * 使用 `/mcp` 对需要 OAuth 2.0 身份验证的远程服务器进行身份验证

463</Tip>460</Tip>

464 461

465每个服务器的 `timeout` 是每个工具调用的硬墙钟限制，来自服务器的进度通知不会延长它。低于 1000 的值被忽略并回退到 `MCP_TOOL_TIMEOUT`，或在该变量未设置时回退到其约 28 小时的默认值。对于 HTTP、SSE 或 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) 服务器，还有第二个每请求计时器，涵盖从服务器的第一个响应字节的每个请求。Claude Code 将该计时器设置为三个值中最大的：60 秒、适用于服务器的工具超时和 `MCP_TIMEOUT`。未设置的 `MCP_TOOL_TIMEOUT` 的 28 小时默认值不进入该比较，低于 60 秒的值不会缩短计时器。Stdio 和 WebSocket 服务器没有每请求计时器。462每个服务器的 `timeout` 是每个工具调用的硬墙钟限制，来自服务器的进度通知不会延长它。低于 1000 的值被忽略并回退到 `MCP_TOOL_TIMEOUT`，或在该变量未设置时回退到其约 28 小时的默认值。对于 HTTP、SSE 或 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) 服务器，还有第二个按请求计时器，涵盖从服务器的第一个响应字节的每个请求。Claude Code 将该计时器设置为三个值中最大的：60 秒、适用于服务器的工具超时和 `MCP_TIMEOUT`。未设置的 `MCP_TOOL_TIMEOUT` 的 28 小时默认值不进入该比较，低于 60 秒的值不会缩短计时器。Stdio 和 WebSocket 服务器没有按请求计时器。

466 463

467至少 1000 的每个服务器 `timeout` 也充当下面描述的空闲超时的下限：Claude Code 从不因空闲而中止该服务器的工具调用早于每个服务器的 `timeout`。需要 Claude Code v2.1.203 或更高版本。464至少 1000 的每个服务器 `timeout` 也充当下面描述的空闲超时的下限：Claude Code 永远不会因空闲而中止该服务器的工具调用早于每个服务器的 `timeout`。需要 Claude Code v2.1.203 或更高版本。

468 465

469对在空闲窗口中不发送响应和不发送进度通知的 MCP 服务器的工具调用因错误而中止，而不是等待墙钟限制。空闲超时需要 Claude Code v2.1.187 或更高版本。它适用于除 IDE 服务器和 SDK 进程内服务器外的每个服务器类型。对于 HTTP、SSE、WebSocket 和 [claude.ai 连接器](#use-mcp-servers-from-claude-ai) 服务器，空闲窗口默认为五分钟，对于 stdio 服务器默认为 30 分钟。在 v2.1.203 之前，stdio 服务器免除空闲超时。466对 MCP 服务器的工具调用，在空闲窗口内不发送响应和不发送进度通知，会因错误而中止，而不是等待墙钟限制。空闲超时适用于除 IDE 服务器和 SDK 进程内服务器外的每个服务器类型。空闲窗口对于 HTTP、SSE、WebSocket 和 [claude.ai 连接器](#use-mcp-servers-from-claude-ai) 服务器默认为五分钟，对于 stdio 服务器默认为 30 分钟。在 v2.1.203 之前，stdio 服务器免除空闲超时。

470 467

471在 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/zh-CN/env-vars) 环境变量中以毫秒为单位设置以更改空闲窗口，或将其设置为 `0` 以禁用检查。468在 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/zh-CN/env-vars) 环境变量中设置毫秒以更改空闲窗口，或将其设置为 `0` 以禁用检查。

472 469

473这些超时限制调用可以运行多长时间，不总是它阻止会话多长时间：在主对话中运行超过两分钟的主对话调用首先移动到后台任务。请参阅 [长工具调用的自动后台处理](#automatic-backgrounding-of-long-tool-calls)。470这些超时限制调用可以运行多长时间，不总是它阻止会话多长时间：在两分钟后仍在运行的主对话调用首先移动到后台任务。请参阅 [长工具调用的自动后台处理](#automatic-backgrounding-of-long-tool-calls)。

474 471

475<h3 id="automatic-backgrounding-of-long-tool-calls">472<h3 id="automatic-backgrounding-of-long-tool-calls">

476 长工具调用的自动后台处理473 长工具调用的自动后台处理

477</h3>474</h3>

478 475

479在主对话中仍在运行两分钟后的 MCP 工具调用移动到后台任务，而不是阻止会话。Claude 立即接收任务 ID 并继续工作，结果在调用解决时作为任务通知到达。自动后台处理需要 Claude Code v2.1.212 或更高版本。476主对话中的 MCP 工具调用在两分钟后仍在运行时移动到后台任务，而不是阻止会话。Claude 立即接收任务 ID 并继续工作，结果在调用解决时作为任务通知到达。自动后台处理需要 Claude Code v2.1.212 或更高版本。

480 477

481任务出现在 [`/tasks`](/docs/zh-CN/commands#all-commands) 中，您也可以在其中停止它，它在退出会话时不会保留。每个调用的限制仍然适用于调用在后台运行时：由每个服务器 `timeout` 或 [`MCP_TOOL_TIMEOUT`](/docs/zh-CN/env-vars) 设置的墙钟限制，以及由 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/zh-CN/env-vars) 设置的空闲超时。478任务出现在 [`/tasks`](/docs/zh-CN/commands#all-commands) 中，您也可以在其中停止它，并且在退出会话时不会保留。每个调用的限制仍然适用于在后台运行的调用：由每个服务器 `timeout` 或 [`MCP_TOOL_TIMEOUT`](/docs/zh-CN/env-vars) 设置的墙钟限制，以及由 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/zh-CN/env-vars) 设置的空闲超时。

482 479

483在 [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](/docs/zh-CN/env-vars) 环境变量中以毫秒为单位设置以更改阈值，或将其设置为 `0` 以关闭自动后台处理。将 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 设置为 `1` 也会关闭它，以及所有其他后台任务功能。480设置 [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](/docs/zh-CN/env-vars) 环境变量（以毫秒为单位）以更改阈值，或将其设置为 `0` 以关闭自动后台处理。将 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 设置为 `1` 也会关闭它，以及所有其他后台任务功能。

484 481

485某些调用从不移动到后台：482某些调用永远不会移动到后台：

486 483

487* 来自 [子代理](/docs/zh-CN/sub-agents) 的调用；Claude Code 仅后台处理主对话调用484* 来自 [子代理](/docs/zh-CN/sub-agents) 的调用；Claude Code 仅后台处理主对话调用

488* 对 IDE 服务器的调用485* 对 IDE 服务器的调用

489* 在 [非交互模式](/docs/zh-CN/headless) 中的调用，除非 `CLAUDE_AUTO_BACKGROUND_TASKS` 设置为 `1`，因为一次性运行可能在结果到达之前结束486* [非交互模式](/docs/zh-CN/headless) 中的调用，除非 `CLAUDE_AUTO_BACKGROUND_TASKS` 设置为 `1`，因为一次性运行可能在结果到达前结束

490 487

491等待打开的 [引出对话](#respond-to-mcp-elicitation-requests) 的调用在对话打开时不会后台处理；服务器被阻止在您的输入上，而不是缓慢，因此 Claude Code 将移动推迟到对话关闭。488等待打开的 [引出对话](#respond-to-mcp-elicitation-requests) 的调用在对话打开时不会后台处理；服务器被阻止在您的输入上，而不是缓慢，因此 Claude Code 将移动推迟到对话关闭。

492 489

498 495

499**插件 MCP 服务器如何工作**：496**插件 MCP 服务器如何工作**：

500 497

501* 插件在插件根目录或 `plugin.json` 中内联的 `.mcp.json` 中定义 MCP 服务器498* 插件在插件根目录的 `.mcp.json` 中或在 `plugin.json` 中内联定义 MCP 服务器

502* 当您启用插件时，Claude Code 自动启动其 MCP 服务器499* 启用插件时，Claude Code 自动启动其 MCP 服务器

503* Claude Code 将插件 MCP 工具与手动配置的 MCP 工具一起提供500* Claude Code 将插件 MCP 工具与手动配置的 MCP 工具一起提供

504* 您通过安装或卸载插件添加和删除插件服务器，而不是使用 `/mcp` 命令。您仍然可以在 `/mcp` 中 [切换已安装的插件服务器关闭](#disable-a-server-without-removing-it)，这会停止 Claude Code 连接到它而不删除插件501* 您通过安装或卸载插件来添加和删除插件服务器，而不是使用 `/mcp` 命令。您仍然可以在 `/mcp` 中 [切换已安装的插件服务器关闭](#disable-a-server-without-removing-it)，这会停止 Claude Code 连接到它，而不删除插件

505 502

506**示例插件 MCP 配置**：503**示例插件 MCP 配置**：

507 504

539 536

540* **自动生命周期**：服务器在这些点连接和断开连接：537* **自动生命周期**：服务器在这些点连接和断开连接：

541 * 在会话启动时，Claude Code 自动连接启用的插件的服务器。在 `/mcp` 中，您之前使用过的远程（HTTP 或 SSE）插件服务器可以显示 [`cached` 状态](#server-status-detail) 而不是；Claude Code 在 Claude 首次调用其工具之一时连接它538 * 在会话启动时，Claude Code 自动连接启用的插件的服务器。在 `/mcp` 中，您之前使用过的远程（HTTP 或 SSE）插件服务器可以显示 [`cached` 状态](#server-status-detail) 而不是；Claude Code 在 Claude 首次调用其工具之一时连接它

542 * 如果您在会话期间启用或禁用插件，Claude Code 在更改应用时连接或断开其 MCP 服务器。[在不重新启动的情况下应用插件更改](/docs/zh-CN/plugins/cli-reference#reload-plugins) 描述何时应用。在没有交互式终端的会话中，`/reload-plugins` 不连接或断开插件 MCP 服务器；这些更改在您的下一个会话中生效539 * 如果您在会话期间启用或禁用插件，Claude Code 在更改应用时连接或断开其 MCP 服务器。[在不重启的情况下应用插件更改](/docs/zh-CN/plugins/cli-reference#reload-plugins) 描述何时应用。在没有交互式终端的会话中，`/reload-plugins` 不连接或断开插件 MCP 服务器；这些更改在您的下一个会话中生效

543 * 当您重新加载时，Claude Code 保留配置未更改的插件服务器的实时连接，并在您从 Agent SDK 中 [替换会话的 MCP 服务器列表](/docs/zh-CN/agent-sdk/typescript#mcpsetserversresult) 而不命名它们时执行相同操作540 * 重新加载时，Claude Code 保留配置未更改的插件服务器的实时连接，并在您从 Agent SDK [替换会话的 MCP 服务器列表](/docs/zh-CN/agent-sdk/typescript#mcpsetserversresult) 而不命名它们时执行相同操作

544 * 当您在 v2.1.246 或更高版本上使用 `/cd` [移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory) 时，Claude Code 连接新目录的设置启用的插件的服务器，并断开不再启用的插件的服务器，因此您不需要在移动后运行 `/reload-plugins`541 * 当您在 v2.1.246 或更高版本上使用 `/cd` [移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory) 时，Claude Code 连接新目录的设置启用的插件的服务器，并断开不再启用的插件的服务器，因此您不需要在移动后运行 `/reload-plugins`

545 * 在 [网络会话](/docs/zh-CN/claude-code-on-the-web) 中，对尚未连接的插件服务器的 MCP 调用（例如在空闲会话唤醒后）按需启动服务器并等待其连接542 * 在 [云会话](/docs/zh-CN/claude-code-on-the-web) 中，对尚未连接的插件服务器的 MCP 调用（例如在空闲会话唤醒后），按需启动服务器并等待它连接

546* **路径占位符**：`${CLAUDE_PLUGIN_ROOT}` 解析为插件的安装目录，`${CLAUDE_PLUGIN_DATA}` 解析为其 [持久状态](/docs/zh-CN/plugins/components#path-variables-and-persistent-data) 目录，`${CLAUDE_PROJECT_DIR}` 解析为稳定的项目根目录。替换适用于：543* **路径占位符**：`${CLAUDE_PLUGIN_ROOT}` 解析为插件的安装目录，`${CLAUDE_PLUGIN_DATA}` 解析为其 [持久状态](/docs/zh-CN/plugins/components#path-variables-and-persistent-data) 目录，`${CLAUDE_PROJECT_DIR}` 解析为稳定的项目根目录。替换适用于：

547 * `stdio` 服务器：`command`、`args`、`env`544 * `stdio` 服务器：`command`、`args`、`env`

548 * `http`、`sse` 和 `ws` 服务器：`url`、`headers` 和 `headersHelper`。在 v2.1.195 之前，`headersHelper` 将占位符作为文字字符串传递545 * `http`、`sse` 和 `ws` 服务器：`url`、`headers` 和 `headersHelper`。在 v2.1.195 之前，`headersHelper` 将占位符作为文字字符串传递

553 550

554**插件 MCP 工具名称**：551**插件 MCP 工具名称**：

555 552

556来自插件捆绑的 MCP 服务器的工具在其可调用名称中包含插件名称和服务器键。完整形式是 `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`，其中 `A-Z`、`a-z`、`0-9`、`_` 和 `-` 之外的任何字符都被替换为 `_`。对于名为 `my-plugin` 的插件中捆绑的 `database-tools` 服务器，`query` 工具可调用为：553来自插件捆绑的 MCP 服务器的工具在其可调用名称中包含插件名称和服务器密钥。完整形式是 `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`，其中 `A-Z`、`a-z`、`0-9`、`_` 和 `-` 之外的任何字符都被替换为 `_`。对于名为 `my-plugin` 的插件中捆绑的 `database-tools` 服务器，`query` 工具可调用为：

557 554

558```555```

559mcp__plugin_my-plugin_database-tools__query556mcp__plugin_my-plugin_database-tools__query

560```557```

561 558

562在 [权限规则](/docs/zh-CN/permissions) 中、技能的 `allowed-tools` 列表中、[子代理的 `tools` 字段](/docs/zh-CN/sub-agents#available-tools) 中或 [hook 匹配器](/docs/zh-CN/hooks#match-mcp-tools) 中引用工具时使用此完整名称。针对裸服务器键编写的 hook 匹配器（如 `mcp__database-tools__.*`）从不为插件捆绑的服务器触发。559在 [权限规则](/docs/zh-CN/permissions)、技能的 `allowed-tools` 列表、[子代理的 `tools` 字段](/docs/zh-CN/sub-agents#available-tools) 或 [hook 匹配器](/docs/zh-CN/hooks#match-mcp-tools) 中引用工具时使用此完整名称。针对裸服务器密钥编写的 hook 匹配器（例如 `mcp__database-tools__.*`）永远不会对插件捆绑的服务器触发。

563 560

564服务器本身在作用域名称 `plugin:<plugin-name>:<server-name>` 下注册，例如 `plugin:my-plugin:database-tools`。在需要配置的服务器名称的地方使用该名称，例如 [`mcp_tool` hook 的 `server` 字段](/docs/zh-CN/hooks#mcp-tool-hook-fields)。561服务器本身在作用域名称 `plugin:<plugin-name>:<server-name>` 下注册，例如 `plugin:my-plugin:database-tools`。在需要配置的服务器名称的地方使用该名称，例如 [`mcp_tool` hook 的 `server` 字段](/docs/zh-CN/hooks#mcp-tool-hook-fields)。

565 562

6694. [插件提供的服务器](/docs/zh-CN/plugins/components#mcp-servers)6664. [插件提供的服务器](/docs/zh-CN/plugins/components#mcp-servers)

6705. [claude.ai 连接器](#use-mcp-servers-from-claude-ai)6675. [claude.ai 连接器](#use-mcp-servers-from-claude-ai)

671 668

672三个范围按名称匹配重复项。插件和连接器按端点匹配，因此指向与上述服务器相同的 URL 或命令的连接器被视为重复项。669Claude Code 按名称匹配三个范围中的重复项。插件和连接器按端点匹配，因此指向与上述服务器相同的 URL 或命令的连接器被视为重复项。

670

671当两个 URL 拼写仅在方案或主机的字母大小写、方案的默认端口（例如 `https` 上的 `:443`）或尾部斜杠方面不同时，它们被视为相同的端点。不同的路径、查询字符串、用户信息或非默认端口会使两个服务器不同。

673 672

674您的组织通过 [`managedMcpServers`](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings) 托管设置提供的服务器排名高于所有这些，因此当其中一个重复它时，Claude Code 连接组织的定义。需要 Claude Code v2.1.259 或更高版本。673您的组织通过 [`managedMcpServers`](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings) 托管设置提供的服务器排名高于所有这些，因此当其中一个重复它时，Claude Code 连接组织的定义。需要 Claude Code v2.1.259 或更高版本。

675 674

821 820

822许多基于云的 MCP 服务器需要身份验证。Claude Code 支持 OAuth 2.0 以实现安全连接。821许多基于云的 MCP 服务器需要身份验证。Claude Code 支持 OAuth 2.0 以实现安全连接。

823 822

824Claude Code 将远程服务器标记为需要身份验证，当服务器响应 `401 Unauthorized` 或 `403 Forbidden` 时。Claude Code 显示的内容取决于服务器：823当服务器响应 `401 Unauthorized` 或 `403 Forbidden` 时，Claude Code 会将远程服务器标记为需要身份验证。Claude Code 显示的内容取决于服务器：

825 824

826* 对于您尚未登录的服务器，任一状态代码都会在 `/mcp` 中标记它，以便您可以完成 OAuth 流程。825* 对于您尚未登录的服务器，任一状态代码都会在 `/mcp` 中标记它，以便您可以完成 OAuth 流程。

827* 对于 [claude.ai 连接器](#use-mcp-servers-from-claude-ai)，由 claude.ai 拒绝您的会话令牌导致的 `401` 不会标记连接器，因为重新授权连接器无法修复您的登录。Claude Code 改为显示 [会话令牌被拒绝状态](/docs/zh-CN/errors#claude-ai-rejected-the-session-token)。826* 对于 [claude.ai 连接器](#use-mcp-servers-from-claude-ai)，由 claude.ai 拒绝您的会话令牌导致的 `401` 不会标记连接器，因为重新授权连接器无法修复您的登录。Claude Code 改为显示 [会话令牌被拒绝状态](/docs/zh-CN/errors#claude-ai-rejected-the-session-token)。

828* 对于您在 `headers` 中配置了 `Authorization` 标头的服务器，或通过 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 配置的服务器，连接时的 `401` 或 `403` 不会标记服务器，因为要修复的凭据是您配置的凭据。Claude Code 改为报告连接失败。如果您从 `${VAR}` 引用设置该标头，请检查该变量是否是 Claude Code [读取为空](#credential-variables-that-read-as-empty) 的变量之一。827* 对于您在 `headers` 中配置了 `Authorization` 标头的服务器，或通过 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 配置的服务器，连接时的 `401` 或 `403` 不会标记服务器，因为要修复的凭证是您配置的凭证。Claude Code 改为报告连接失败。如果您从 `${VAR}` 引用设置该标头，请检查该变量是否是 Claude Code [读取为空](#credential-variables-that-read-as-empty) 的变量之一。

829* 对于 [传递到云会话的连接器](#how-connectors-reach-claude-code)，Claude Code 不运行登录流程，因为会话的代理使用您在 claude.ai 中授予的授权向连接器进行身份验证。当那里的连接器需要再次授权时，请在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 重新连接它，而不是从会话中重新连接。828* 对于 [传递到云会话的连接器](#how-connectors-reach-claude-code)，Claude Code 不运行登录流程，因为会话的代理使用您在 claude.ai 中授予的授权向连接器进行身份验证。当那里的连接器需要再次授权时，请在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 重新连接它，而不是从会话中连接。

830 829

831当对您已登录的 OAuth 服务器的请求返回 `401 Unauthorized` 时，Claude Code 会刷新存储的令牌、重新连接并重试请求一次。只有在该重试也失败时，它才会在 `/mcp` 中标记服务器。在 v2.1.206 之前，由于网络错误等暂时性原因导致的令牌刷新失败会将 OAuth 服务器标记为在会话的其余时间需要身份验证，即使其刷新令牌仍然有效。830当对您已登录的 OAuth 服务器的请求返回 `401 Unauthorized` 时，Claude Code 会刷新存储的令牌、重新连接并重试请求一次。只有在该重试也失败时，它才会在 `/mcp` 中标记服务器。在 v2.1.206 之前，由于网络错误等暂时原因导致的令牌刷新失败会将 OAuth 服务器标记为在会话的其余时间内需要身份验证，即使其刷新令牌仍然有效。

832 831

833当服务器拒绝存储的刷新令牌时，Claude Code 会立即显示一个指向 `/mcp` 的通知。打开 `/mcp` 并在服务器上选择 **Re-authenticate** 以在下一个工具调用失败之前重新登录。832当服务器拒绝存储的刷新令牌时，Claude Code 会立即显示一条指向 `/mcp` 的通知。打开 `/mcp` 并在服务器上选择 **Re-authenticate** 以在下一个工具调用失败之前再次登录。

834 833

835返回指向其授权服务器的 `WWW-Authenticate` 标头的自定义服务器获得与任何其他远程服务器相同的自动发现。834返回指向其授权服务器的 `WWW-Authenticate` 标头的自定义服务器会获得与任何其他远程服务器相同的自动发现。

836 835

837Claude Code 也会在启动时显示通知，当一个或多个配置的服务器需要身份验证时，这样您就不必打开 `/mcp` 来发现哪些服务器需要登录。该通知需要 Claude Code v2.1.193 或更高版本。它仅计算您可以从 Claude Code 登录的服务器。在 v2.1.218 之前，它还计算 [claude.ai 连接器](#use-mcp-servers-from-claude-ai)，这些连接器在 claude.ai 中未连接，您只能从 claude.ai 设置中连接。836当一个或多个配置的服务器需要身份验证时，Claude Code 也会显示启动通知，因此您不必打开 `/mcp` 来发现哪些服务器需要登录。该通知需要 Claude Code v2.1.193 或更高版本。它仅计算您可以从 Claude Code 登录的服务器。在 v2.1.218 之前，它还计算了在 claude.ai 中未连接的 [claude.ai 连接器](#use-mcp-servers-from-claude-ai)，您只能从 claude.ai 设置中连接这些连接器。

838 837

839该通知每次启动时宣布每个服务器一次，并将其从计数中排除，直到该服务器已连接并再次需要登录。`/mcp` 仍然列出每个需要登录的服务器。838该通知每次宣布每个服务器一次，并在后续启动时将其排除在计数之外，直到该服务器已连接并再次需要登录。`/mcp` 仍然列出每个需要登录的服务器。

840 839

841在非交互模式下，没有 `/mcp` 面板，因此 Claude Code 无法为您运行 OAuth 流程。从 v2.1.196 开始，当配置的服务器在 `claude -p` 或启用了 [工具搜索](#scale-with-mcp-tool-search)（这是默认设置）的 Agent SDK 运行期间需要身份验证时，Claude Code 会告诉 Claude 该服务器的工具不可用，直到您授权它。Claude 可以命名需要登录的服务器，而不是响应就像服务器未配置一样。从与 `/mcp` 的交互式会话或 `claude mcp login <name>` 完成登录。840在非交互模式下，没有 `/mcp` 面板，因此 Claude Code 无法为您运行 OAuth 流程。从 v2.1.196 开始，当配置的服务器在启用了 [工具搜索](#scale-with-mcp-tool-search)（这是默认设置）的 `claude -p` 或 Agent SDK 运行期间需要身份验证时，Claude Code 会告诉 Claude 该服务器的工具不可用，直到您授权它。Claude 然后可以命名需要登录的服务器，而不是响应就像服务器未配置一样。从使用 `/mcp` 或 `claude mcp login <name>` 的交互式会话完成登录。

842 841

843如果您为服务器配置了 `headers.Authorization`，而服务器拒绝了该标头，Claude Code 会将连接报告为失败，而不是回退到 OAuth。检查令牌对于 MCP 端点是否有效，或删除标头以使用 OAuth 流程。842如果您为服务器配置了 `headers.Authorization`，而服务器拒绝了该标头，Claude Code 会报告连接失败，而不是回退到 OAuth。检查令牌对 MCP 端点是否有效，或删除标头以使用 OAuth 流程。

844 843

845<Steps>844<Steps>

846 <Step title="添加需要身份验证的服务器">845 <Step title="添加需要身份验证的服务器">

847 如果您已在 [MCP 快速入门](/docs/zh-CN/mcp-quickstart#connect-a-server-that-requires-sign-in) 中添加了 `sentry` 服务器，请跳过此步骤：使用相同的服务器名称在相同的范围再次运行 `claude mcp add` 会失败，出现 `MCP server sentry already exists in local config`。否则，运行：846 如果您已在 [MCP 快速入门](/docs/zh-CN/mcp-quickstart#connect-a-server-that-requires-sign-in) 中添加了 `sentry` 服务器，请跳过此步骤：使用相同的服务器名称在相同的范围内再次运行 `claude mcp add` 会失败，并显示 `MCP server sentry already exists in local config`。否则，运行：

848 847

849 ```bash theme={null}848 ```bash theme={null}

850 claude mcp add --transport http sentry https://mcp.sentry.dev/mcp849 claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

865<Tip>864<Tip>

866 提示：865 提示：

867 866

868 * 身份验证令牌安全存储并自动刷新867 * 身份验证令牌存储安全且自动刷新

869 * 使用 `/mcp` 菜单中的"清除身份验证"撤销访问权限868 * 使用 `/mcp` 菜单中的"Clear authentication"撤销访问权限

870 * 如果您的浏览器没有自动打开，请复制提供的 URL 并手动打开869 * 如果浏览器未自动打开，请复制提供的 URL 并手动打开

871 * 如果浏览器重定向在身份验证后失败并出现连接错误，请将浏览器地址栏中的完整回调 URL 粘贴到 Claude Code 中出现的 URL 提示中870 * 如果浏览器重定向在身份验证后失败并出现连接错误，请将浏览器地址栏中的完整回调 URL 粘贴到 Claude Code 中出现的 URL 提示中

872 * OAuth 身份验证适用于 HTTP 服务器871 * OAuth 身份验证适用于 HTTP 服务器

873</Tip>872</Tip>

876 从命令行进行身份验证875 从命令行进行身份验证

877</h3>876</h3>

878 877

879从 v2.1.186 开始，`claude mcp login <name>` 直接从您的 shell 运行配置的服务器的 OAuth 流程，因此您无需在会话内打开 `/mcp` 面板。878`claude mcp login <name>` 命令直接从您的 shell 运行配置的服务器的 OAuth 流程，因此您不需要在会话内打开 `/mcp` 面板。

880 879

881```bash theme={null}880```bash theme={null}

882claude mcp login sentry881claude mcp login sentry

883```882```

884 883

885要稍后清除存储的凭据，请运行 `claude mcp logout <name>`。884要稍后清除存储的凭证，请运行 `claude mcp logout <name>`。

886 885

887从 v2.1.191 开始，该命令检测何时没有本地浏览器可用，例如在 SSH 会话期间或在没有显示服务器的 Linux 上，并打印授权 URL 而不是尝试打开浏览器。在您的本地计算机上打开 URL，然后将浏览器地址栏中的完整重定向 URL 粘贴回提示符。该命令需要交互式终端来执行粘贴步骤，因此请使用 `ssh -t` 连接。传递 `--no-browser` 以强制 URL 提示，即使检测到本地浏览器。886`claude mcp login` 检测何时没有本地浏览器可用，例如在 SSH 会话期间或在没有显示服务器的 Linux 上，并打印授权 URL 而不是尝试打开浏览器。在您的本地计算机上打开 URL，然后将浏览器地址栏中的完整重定向 URL 粘贴回提示符。该命令需要交互式终端来执行粘贴步骤，因此请使用 `ssh -t` 连接。传递 `--no-browser` 以强制 URL 提示，即使检测到本地浏览器。

888 887

889```bash theme={null}888```bash theme={null}

890claude mcp login sentry --no-browser889claude mcp login sentry --no-browser

894 使用固定的 OAuth 回调端口893 使用固定的 OAuth 回调端口

895</h3>894</h3>

896 895

897某些 MCP 服务器需要预先注册的特定重定向 URI。默认情况下，Claude Code 为 OAuth 回调选择随机可用端口。使用 `--callback-port` 固定端口，使其与 `http://localhost:PORT/callback` 形式的预注册重定向 URI 匹配。如果 Claude Code v2.1.229 上的登录失败并出现重定向 URI 不匹配，请参阅 [使用预配置的 OAuth 凭据](#use-pre-configured-oauth-credentials) 下的版本说明。896某些 MCP 服务器需要预先注册的特定重定向 URI。默认情况下，Claude Code 为 OAuth 回调选择随机可用端口。使用 `--callback-port` 固定端口，使其与 `http://localhost:PORT/callback` 形式的预注册重定向 URI 匹配。如果在 Claude Code v2.1.229 上登录失败并出现重定向 URI 不匹配，请参阅 [使用预配置的 OAuth 凭证](#use-pre-configured-oauth-credentials) 下的版本说明。

898 897

899您可以单独使用 `--callback-port`（使用动态客户端注册）或与 `--client-id` 一起使用（使用预配置的凭据）。898您可以单独使用 `--callback-port`（使用动态客户端注册）或与 `--client-id` 一起使用（使用预配置的凭证）。

900 899

901```bash theme={null}900```bash theme={null}

902# 使用动态客户端注册的固定回调端口901# 使用动态客户端注册的固定回调端口

906```905```

907 906

908<h3 id="use-pre-configured-oauth-credentials">907<h3 id="use-pre-configured-oauth-credentials">

909 使用预配置的 OAuth 凭据908 使用预配置的 OAuth 凭证

910</h3>909</h3>

911 910

912某些 MCP 服务器不支持通过动态客户端注册进行自动 OAuth 设置。如果您看到类似"不兼容的身份验证服务器：不支持动态客户端注册"的错误，服务器需要预配置的凭据。Claude Code 也支持使用客户端 ID 元数据文档 (CIMD) 而不是动态客户端注册的服务器，并自动发现这些服务器。如果自动发现失败，请首先通过服务器的开发者门户注册 OAuth 应用，然后在添加服务器时提供凭据。911某些 MCP 服务器不支持通过动态客户端注册进行自动 OAuth 设置。如果您看到类似"Incompatible auth server: does not support dynamic client registration"的错误，服务器需要预配置的凭证。Claude Code 也支持使用客户端 ID 元数据文档 (CIMD) 而不是动态客户端注册的服务器，并自动发现这些服务器。如果自动发现失败，请先通过服务器的开发者门户注册 OAuth 应用，然后在添加服务器时提供凭证。

913 912

914<Steps>913<Steps>

915 <Step title="使用服务器注册 OAuth 应用">914 <Step title="向服务器注册 OAuth 应用">

916 通过服务器的开发者门户创建应用，并记下您的客户端 ID 和客户端密钥。915 通过服务器的开发者门户创建应用并记下您的客户端 ID 和客户端密钥。

917 916

918 许多服务器还需要重定向 URI。如果是这样，请选择一个端口并以 `http://localhost:PORT/callback` 的格式注册重定向 URI。在下一步中使用该相同的端口与 `--callback-port`。917 如果注册表单要求重定向 URI，请选择任何可用端口并输入 `http://localhost:PORT/callback`，其中包含该端口。您将在下一步中使用相同的端口。

919 918

920 在 v2.1.229 中，Claude Code 发送了 `http://127.0.0.1:PORT/callback`，而精确匹配注册重定向 URI 的服务器拒绝了登录，出现重定向 URI 不匹配。Claude Code v2.1.231 恢复了 `localhost` 形式。要在 v2.1.229 上恢复，请升级 Claude Code，或临时将 `http://127.0.0.1:PORT/callback` 形式添加到服务器的注册重定向 URI。919 在 v2.1.229 中，Claude Code 改为发送 `http://127.0.0.1:PORT/callback`，而精确匹配注册重定向 URI 的服务器会以重定向 URI 不匹配拒绝登录。Claude Code v2.1.231 恢复了 `localhost` 形式。要在 v2.1.229 上恢复，请升级 Claude Code，或临时将 `http://127.0.0.1:PORT/callback` 形式添加到服务器的注册重定向 URI。

921 </Step>920 </Step>

922 921

923 <Step title="使用您的凭据添加服务器">922 <Step title="使用您的凭证添加服务器">

924 选择以下方法之一。用于 `--callback-port` 的端口可以是任何可用的端口。它需要与您在上一步中注册的重定向 URI 匹配。923 这些选项卡涵盖两个命令：`claude mcp add` 将您的客户端 ID 和回调端口作为标志，`claude mcp add-json` 在 `oauth` 对象中获取它们。如果您注册了重定向 URI，请将回调端口设置为该 URI 中的端口。

925 924

926 <Tabs>925 <Tabs>

927 <Tab title="claude mcp add">926 <Tab title="claude mcp add">

928 使用 `--client-id` 传递您的应用的客户端 ID。`--client-secret` 标志使用掩盖的输入提示输入密钥：927 使用 `--client-id` 传递您的应用的客户端 ID。`--client-secret` 标志使用掩码输入提示输入密钥：

929 928

930 ```bash theme={null}929 ```bash theme={null}

931 claude mcp add --transport http \930 claude mcp add --transport http \

944 ```943 ```

945 </Tab>944 </Tab>

946 945

947 <Tab title="claude mcp add-json（仅回调端口）">946 <Tab title="claude mcp add-json (仅回调端口)">

948 使用 `--callback-port` 而不使用客户端 ID 来固定端口，同时使用动态客户端注册：947 要仅固定回调端口并让 Claude Code 自动注册客户端，请单独设置 `callbackPort`：

949 948

950 ```bash theme={null}949 ```bash theme={null}

951 claude mcp add-json my-server \950 claude mcp add-json my-server \

973<Tip>972<Tip>

974 提示：973 提示：

975 974

976 * 客户端密钥安全地存储在您的系统钥匙链（macOS）或凭据文件中，而不是在您的配置中975 * 客户端密钥安全地存储在您的系统钥匙链 (macOS) 或凭证文件中，而不是在您的配置中

977 * 您只能在添加服务器时设置客户端密钥。当您使用 `claude mcp login` 或从 `/mcp` 进行身份验证时，Claude Code 使用存储的密钥，不会提示输入或读取 `MCP_CLIENT_SECRET`976 * 您只能在添加服务器时设置客户端密钥。当您使用 `claude mcp login` 或从 `/mcp` 进行身份验证时，Claude Code 使用存储的密钥，不会提示输入密钥或读取 `MCP_CLIENT_SECRET`

978 * 要稍后添加或更改密钥，请使用 `claude mcp remove <name>` 删除服务器，然后使用 `--client-secret` 和相同的 `--scope` 再次添加它977 * 要稍后添加或更改密钥，请使用 `claude mcp remove <name>` 删除服务器，然后使用 `--client-secret` 和相同的 `--scope` 再次添加它

979 * 如果服务器使用没有密钥的公共 OAuth 客户端，仅使用 `--client-id` 而不使用 `--client-secret`978 * 如果服务器使用没有密钥的公共 OAuth 客户端，请仅使用 `--client-id` 而不使用 `--client-secret`

980 * 这些标志仅适用于 HTTP 和 SSE 传输。它们对 stdio 服务器没有影响979 * 这些标志仅适用于 HTTP 和 SSE 传输。它们对 stdio 服务器没有影响

981 * 使用 `claude mcp get <name>` 验证为服务器配置了 OAuth 凭据980 * 使用 `claude mcp get <name>` 验证为服务器配置了 OAuth 凭证

982</Tip>981</Tip>

983 982

984<h3 id="override-oauth-metadata-discovery">983<h3 id="override-oauth-metadata-discovery">

985 覆盖 OAuth 元数据发现984 覆盖 OAuth 元数据发现

986</h3>985</h3>

987 986

988指向 Claude Code 一个特定的 OAuth 授权服务器元数据 URL 以绕过默认发现链。当 MCP 服务器的标准端点出错时，或当您想通过内部代理路由发现时，设置 `authServerMetadataUrl`。默认情况下，Claude Code 首先检查 RFC 9728 受保护资源元数据（位于 `/.well-known/oauth-protected-resource`），然后回退到 RFC 8414 授权服务器元数据（位于 `/.well-known/oauth-authorization-server`）。987指向 Claude Code 特定的 OAuth 授权服务器元数据 URL 以绕过默认发现链。当 MCP 服务器的标准端点出错时，或当您想通过内部代理路由发现时，设置 `authServerMetadataUrl`。默认情况下，Claude Code 首先检查 `/.well-known/oauth-protected-resource` 处的 RFC 9728 受保护资源元数据，然后回退到 `/.well-known/oauth-authorization-server` 处的 RFC 8414 授权服务器元数据。

989 988

990在您的服务器配置中的 `.mcp.json` 的 `oauth` 对象中设置 `authServerMetadataUrl`：989在 `.mcp.json` 中您的服务器配置的 `oauth` 对象中设置 `authServerMetadataUrl`：

991 990

992```json theme={null}991```json theme={null}

993{992{

1003}1002}

1004```1003```

1005 1004

1006URL 必须使用 `https://`。元数据 URL 的 `scopes_supported` 覆盖上游服务器公开的范围。1005URL 必须使用 `https://`。元数据 URL 的 `scopes_supported` 覆盖上游服务器宣传的范围。

1007 1006

1008<h3 id="restrict-oauth-scopes">1007<h3 id="restrict-oauth-scopes">

1009 限制 OAuth 范围1008 限制 OAuth 范围

1010</h3>1009</h3>

1011 1010

1012设置 `oauth.scopes` 以固定 Claude Code 在授权流程中请求的范围。这是限制 MCP 服务器到安全团队批准的子集的支持方式，当上游授权服务器公开的范围超过您想要授予的范围时。该值是单个空格分隔的字符串，与 RFC 6749 §3.3 中的 `scope` 参数格式匹配。1011设置 `oauth.scopes` 以固定 Claude Code 在授权流程期间请求的范围。这是当上游授权服务器宣传的范围超过您想要授予的范围时，将 MCP 服务器限制为安全团队批准的子集的受支持方式。该值是单个空格分隔的字符串，与 RFC 6749 §3.3 中的 `scope` 参数格式匹配。

1013 1012

1014```json theme={null}1013```json theme={null}

1015{1014{

1025}1024}

1026```1025```

1027 1026

1028`oauth.scopes` 优先于 `authServerMetadataUrl` 和服务器在 `/.well-known` 发现的范围。将其保留未设置以让 MCP 服务器确定请求的范围集。1027`oauth.scopes` 优先于 `authServerMetadataUrl` 和服务器在 `/.well-known` 处发现的范围。将其保留为未设置以让 MCP 服务器确定请求的范围集。

1029 1028

1030从 v2.1.196 开始，当未设置 `oauth.scopes` 时，Claude Code 请求服务器的 `WWW-Authenticate` 标头或其受保护资源元数据提供的范围，当两者都未提供时不发送 `scope` 参数。它不再从自动发现的授权服务器元数据请求完整的 `scopes_supported` 目录。请求该目录导致公开仅限管理员或模板范围的身份提供者拒绝授权请求，出现 `invalid_scope` 错误。从配置的 `authServerMetadataUrl` 获取的元数据仍然将其 `scopes_supported` 作为请求的范围提供。1029从 v2.1.196 开始，当未设置 `oauth.scopes` 时，Claude Code 请求服务器的 `WWW-Authenticate` 标头或其受保护资源元数据提供的范围，当两者都不提供时不发送 `scope` 参数。它不再从自动发现的授权服务器元数据请求完整的 `scopes_supported` 目录。请求该目录导致宣传仅限管理员或模板范围的身份提供者以 `invalid_scope` 错误拒绝授权请求。从配置的 `authServerMetadataUrl` 获取的元数据仍然将其 `scopes_supported` 作为请求的范围提供。

1031 1030

1032如果授权服务器在 `scopes_supported` 中公开 `offline_access`，Claude Code 会将其附加到固定范围，以便可以在没有新浏览器登录的情况下刷新访问令牌。1031如果授权服务器在 `scopes_supported` 中宣传 `offline_access`，Claude Code 会将其附加到固定范围，以便可以在没有新浏览器登录的情况下刷新访问令牌。

1033 1032

1034如果服务器稍后为工具调用返回 403 `insufficient_scope`，调用会失败，并显示 [`需要额外权限`](/docs/zh-CN/errors#mcp-server-needs-you-to-sign-in-again) 消息，该消息命名服务器请求的范围。服务器在 `/mcp` 中显示为需要身份验证。1033如果服务器稍后为工具调用返回 403 `insufficient_scope`，调用会失败并显示 [`needs additional permissions`](/docs/zh-CN/errors#mcp-server-needs-you-to-sign-in-again) 消息，该消息命名服务器要求的范围。该服务器在 `/mcp` 中显示为需要身份验证。

1035 1034

1036如果该范围不在您的固定 `oauth.scopes` 中，请添加它，然后运行 `/mcp` 并再次对服务器进行身份验证。Claude Code 请求固定范围而不是服务器命名的范围，因此如果您在不添加它的情况下再次进行身份验证，您获得的令牌仍然缺少它。1035如果该范围不在您的固定 `oauth.scopes` 中，请添加它，然后运行 `/mcp` 并再次对服务器进行身份验证。Claude Code 请求固定范围而不是服务器命名的范围，因此如果您在不添加它的情况下再次进行身份验证，您获得的令牌仍然缺少它。

1037 1036

1039 使用动态标头进行自定义身份验证1038 使用动态标头进行自定义身份验证

1040</h3>1039</h3>

1041 1040

1042如果您的 MCP 服务器使用 OAuth 以外的身份验证方案（例如 Kerberos、短期令牌或内部 SSO），请使用 `headersHelper` 在连接时生成请求标头。Claude Code 运行命令并将其输出合并到连接标头中。1041如果您的 MCP 服务器使用 OAuth 以外的身份验证方案，例如 Kerberos、短期令牌或内部 SSO，请使用 `headersHelper` 在连接时生成请求标头。Claude Code 运行命令并将其输出合并到连接标头中。

1043 1042

1044```json theme={null}1043```json theme={null}

1045{1044{

1053}1052}

1054```1053```

1055 1054

1056命令也可以是内联的：1055该命令也可以是内联的：

1057 1056

1058```json theme={null}1057```json theme={null}

1059{1058{

1069 1068

1070**要求：**1069**要求：**

1071 1070

1072* 命令必须将字符串键值对的 JSON 对象写入标准输出1071* 该命令必须将字符串键值对的 JSON 对象写入 stdout

1073* Claude Code 在 shell 中运行命令，并在 10 秒后放弃1072* Claude Code 在 shell 中运行该命令，并在 10 秒后放弃

1074* Claude Code 根据 [您配置服务器的位置](#where-the-helper-runs) 选择命令的工作目录，因此请将脚本作为绝对路径或放在 `PATH` 上1073* Claude Code 通过 [您配置服务器的位置](#where-the-helper-runs) 选择命令的工作目录，因此将脚本作为绝对路径给出或将其放在 `PATH` 上

1075* 动态标头覆盖任何具有相同名称的静态 `headers`1074* 动态标头覆盖任何具有相同名称的静态 `headers`

1076 1075

1077Claude Code 在每次连接时运行助手，在会话启动和重新连接时，一旦 [项目和本地范围服务器的信任规则](#trust-a-folder-before-its-headershelper-runs) 允许它运行。它不缓存结果，因此您的脚本负责任何令牌重用。1076Claude Code 在每次连接时运行助手，在会话启动和重新连接时，一旦 [项目和本地范围服务器的信任规则](#trust-a-folder-before-its-headershelper-runs) 允许它运行。它不缓存结果，因此您的脚本负责任何令牌重用。

1078 1077

1079如果工具调用返回 `401 Unauthorized` 或 `403 Forbidden`，Claude Code 会自动在相同规则下重新运行助手，使用新标头重新连接，并重试调用一次。只有在该重试也失败时，Claude Code 才会在 `/mcp` 中将服务器标记为需要身份验证。1078如果工具调用返回 `401 Unauthorized` 或 `403 Forbidden`，Claude Code 会自动在相同规则下重新运行助手，使用新标头重新连接，并重试调用一次。Claude Code 仅在该重试也失败时才在 `/mcp` 中将服务器标记为需要身份验证。

1080 1079

1081当助手的输出包含 `Authorization` 标头时，Claude Code 使用该凭据作为服务器的身份验证，不会回退到 OAuth。1080当助手的输出包含 `Authorization` 标头时，Claude Code 使用该凭证作为服务器的身份验证，不会回退到服务器的 OAuth。

1082 1081

1083如果服务器在连接时拒绝助手的凭据，Claude Code 会报告连接失败，而不是将服务器标记为需要身份验证。修复您的助手返回的凭据，然后从 `/mcp` 重新连接以重新运行助手。1082如果服务器在连接时拒绝助手的凭证，Claude Code 会报告连接失败，而不是将服务器标记为需要身份验证。修复您的助手返回的凭证，然后从 `/mcp` 重新连接以重新运行助手。

1084 1083

1085Claude Code 在执行助手时设置这些环境变量：1084Claude Code 在执行助手时设置这些环境变量：

1086 1085

1092 1091

1093使用这些来编写一个为多个 MCP 服务器服务的单个助手脚本。1092使用这些来编写为多个 MCP 服务器服务的单个助手脚本。

1094 1093

1095插件提供的 `headersHelper` 无法引用插件的 [`${user_config.*}`](/docs/zh-CN/plugins/manifest-reference#user-configuration) 值，因为命令通过 shell 运行。Claude Code 报告服务器配置错误，并显示 [错误](/docs/zh-CN/errors#plugin-command-references-user-config)，不替换该值。将 `${user_config.KEY}` 放在服务器的 `headers` 字段中，该字段不会被 shell 解析，或让助手脚本从配置文件中读取该值。在 v2.1.207 之前，`headersHelper` 替换了 `${user_config.*}` 值。1094插件提供的 `headersHelper` 无法引用插件的 [`${user_config.*}`](/docs/zh-CN/plugins/manifest-reference#user-configuration) 值，因为该命令通过 shell 运行。Claude Code 报告服务器配置错误并显示 [错误](/docs/zh-CN/errors#plugin-command-references-user-config)，不替换该值。将 `${user_config.KEY}` 放在服务器的 `headers` 字段中，该字段不是 shell 解析的，或让助手脚本从配置文件读取该值。在 v2.1.207 之前，`headersHelper` 替换了 `${user_config.*}` 值。

1096 1095

1097<h4 id="where-the-helper-runs">1096<h4 id="where-the-helper-runs">

1098 助手运行的位置1097 助手运行的位置

1099</h4>1098</h4>

1100 1099

1101Claude Code 根据声明服务器的配置选择 `headersHelper` 命令的工作目录。Claude Code 在 Bash 中运行的 `cd` 不会移动它，[`/cd`](/docs/zh-CN/permissions#move-the-session-to-another-directory) 仅对从会话主工作目录运行的服务器移动它。下表给出了相对路径在您的 `headersHelper` 命令中解析的目录。1100Claude Code 从声明服务器的配置中选择 `headersHelper` 命令的工作目录。Claude 在 Bash 中运行的 `cd` 不会移动它，[`/cd`](/docs/zh-CN/permissions#move-the-session-to-another-directory) 仅对从会话主工作目录运行的服务器移动它。下面的每一行给出您的 `headersHelper` 命令中相对路径解析的目录。

1102 1101

1103| 您配置服务器的位置 | 工作目录 |1102| 您配置服务器的位置 | 工作目录 |

1104| :- | :- |1103| :- | :- |

1105| [插件](/docs/zh-CN/plugins/components#mcp-servers) | 插件的根目录。需要 Claude Code v2.1.195 或更高版本 |1104| [插件](/docs/zh-CN/plugins/components#mcp-servers) | 插件的根目录。需要 Claude Code v2.1.195 或更高版本 |

1107| 项目中的代理文件、来自 SDK 的 `mcpServers` 选项或 `setMcpServers()` 方法的服务器，或 [`--mcp-config`](/docs/zh-CN/cli-reference) | 会话的 [主工作目录](/docs/zh-CN/permissions#working-directories) |1106| 您项目中的代理文件、来自 SDK 的 `mcpServers` 选项或 `setMcpServers()` 方法的服务器，或 [`--mcp-config`](/docs/zh-CN/cli-reference) | 会话的 [主工作目录](/docs/zh-CN/permissions#working-directories) |

1108| [用户范围](#user-scope)、[托管 MCP](/docs/zh-CN/managed-mcp)、[claude.ai 连接器](#use-mcp-servers-from-claude-ai)，或项目外的代理文件，包括来自 `--add-dir` 目录的代理文件 | 您的配置目录，`~/.claude` 除非您设置了 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars) |1107| [用户范围](#user-scope)、[托管 MCP](/docs/zh-CN/managed-mcp)、[claude.ai 连接器](#use-mcp-servers-from-claude-ai)，或来自您项目外的代理文件，包括来自 `--add-dir` 目录的代理文件 | 您的配置目录，`~/.claude` 除非您设置 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars) |

1109 1108

1110在 v2.1.238 之前，Claude Code 也从您启动它的目录运行用户范围、托管和 claude.ai 连接器服务器的助手，以及来自项目外的代理文件。1109在 v2.1.238 之前，Claude Code 也从您启动它的目录运行用户范围、托管和 claude.ai 连接器服务器的助手，以及来自您项目外的代理文件。

1111 1110

1112<h4 id="which-variables-a-helper-can-read">1111<h4 id="which-variables-a-helper-can-read">

1113 助手可以读取哪些变量1112 助手可以读取哪些变量

1114</h4>1113</h4>

1115 1114

1116存储库或插件提供的 `headersHelper` 是您没有编写的命令，因此 Claude Code 运行它时不会从您的环境中提供凭据变量，例如 `ANTHROPIC_API_KEY`。您配置服务器的位置决定了这是否适用：1115存储库或插件提供的 `headersHelper` 是您没有编写的命令，因此 Claude Code 运行它时不使用来自您环境的凭证变量，例如 `ANTHROPIC_API_KEY`。您配置服务器的位置决定这是否适用：

1117 1116

1118* **已删除**：项目 `.mcp.json` 中的服务器或在插件中，以及来自您的项目或 `--add-dir` 目录的代理文件中的内联服务器1117* **已删除**：项目 `.mcp.json` 中的服务器或在插件中，以及来自您项目或 `--add-dir` 目录的代理文件中的内联服务器

1119* **未删除**：[用户](#user-scope) 或 [本地范围](#local-scope) 的服务器、[托管 MCP](/docs/zh-CN/managed-mcp) 中的服务器、来自 [claude.ai 连接器](#use-mcp-servers-from-claude-ai) 的服务器、由 SDK 或 [`--mcp-config`](/docs/zh-CN/cli-reference) 提供的服务器，以及来自 `~/.claude/agents/`、托管设置或通过 `--agents` 传递的代理文件中的内联服务器1118* **未删除**：[用户](#user-scope) 或 [本地范围](#local-scope) 的服务器、[托管 MCP](/docs/zh-CN/managed-mcp) 中的服务器、来自 [claude.ai 连接器](#use-mcp-servers-from-claude-ai) 的服务器、由 SDK 或 [`--mcp-config`](/docs/zh-CN/cli-reference) 提供的服务器，以及来自 `~/.claude/agents/` 的代理文件中的内联服务器、来自托管设置的服务器或使用 `--agents` 传递的服务器

1120 1119

1121除了 Git 的 `GIT_CONFIG_KEY_<n>` 变量外，Claude Code 从您的环境中删除每个名称看起来像凭据的变量，例如名称中包含 `TOKEN`、`SECRET`、`PASSWORD`、`KEY` 或 `AUTH` 的变量（无论大小写），因此 `ANTHROPIC_API_KEY` 和 `MY_REGISTRY_TOKEN` 都被删除。Claude Code 也删除一个固定的凭据变量列表，其名称不遵循该模式，例如 `ANTHROPIC_CUSTOM_HEADERS`。1120除了 Git 的 `GIT_CONFIG_KEY_<n>` 变量外，Claude Code 会从您的环境中删除每个名称看起来像凭证的变量，例如名称中包含 `TOKEN`、`SECRET`、`PASSWORD`、`KEY` 或 `AUTH` 的名称（无论大小写），因此 `ANTHROPIC_API_KEY` 和 `MY_REGISTRY_TOKEN` 都被删除。Claude Code 也删除了一个固定的凭证变量列表，其名称不遵循该模式，例如 `ANTHROPIC_CUSTOM_HEADERS`。

1122 1121

1123当这适用于您的助手时，让脚本从文件或凭据存储中读取其凭据。如果服务器的 `url` [展开这些变量之一](#environment-variable-expansion-in-mcp-json)，助手接收的 `CLAUDE_CODE_MCP_SERVER_URL` 值也会将该部分替换为 `REDACTED`。1122当这适用于您的助手时，让脚本从文件或凭证存储读取其凭证。如果服务器的 `url` [携带这些变量之一的实时值](#environment-variable-expansion-in-mcp-json)，例如 `MY_REGISTRY_TOKEN`，助手接收的 `CLAUDE_CODE_MCP_SERVER_URL` 值也将该部分替换为 `REDACTED`。

1124 1123

1125<h4 id="trust-a-folder-before-its-headershelper-runs">1124<h4 id="trust-a-folder-before-its-headershelper-runs">

1126 在 headersHelper 运行之前信任文件夹1125 在其 headersHelper 运行之前信任文件夹

1127</h4>1126</h4>

1128 1127

1129Claude Code 执行 `headersHelper` 作为任意 shell 命令。对于项目 `.mcp.json` 中的服务器或 [本地范围](#local-scope) 的服务器，它仅在您接受声明服务器的项目目录的 [信任对话框](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust) 后运行助手。在 v2.1.238 之前，`claude -p` 或 SDK 会话运行这些助手而不检查信任，交互式会话在您信任父文件夹后运行它们。1128Claude Code 将 `headersHelper` 作为任意 shell 命令执行。对于项目 `.mcp.json` 中的服务器或 [本地范围](#local-scope) 的服务器，它仅在您接受声明服务器的项目目录的 [信任对话](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust) 后运行助手。在 v2.1.238 之前，`claude -p` 或 SDK 会话运行这些助手而不检查信任，交互式会话在您信任父文件夹后运行它们。

1130 1129

1131* **不计入的信任**：父文件夹的信任，以及 `claude -p` 或 SDK 会话为 [设置文件中的 hooks](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 获得的自动信任1130* **不计算的信任**：父文件夹的信任，以及 `claude -p` 或 SDK 会话为 [设置文件中的钩子](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 获得的自动信任

1132* **直到您信任文件夹**：Claude Code 仅使用其静态 `headers` 连接服务器。在 `claude -p` 或 SDK 会话中，它也会向 stderr 打印每个服务器一行 [`headersHelper not run`](/docs/zh-CN/errors#headershelper-not-run)，告诉您如何授予信任。1131* **直到您信任文件夹**：Claude Code 仅使用其静态 `headers` 连接服务器。在 `claude -p` 或 SDK 会话中，它也会向 stderr 打印每个服务器一行 [`headersHelper not run`](/docs/zh-CN/errors#headershelper-not-run)，告诉您如何授予信任。

1133* **无对话框的信任**：在 `~/.claude.json` 中设置 `projects["<path>"].hasTrustDialogAccepted` 为 `true`。`<path>` 是文件夹 [项目允许规则和工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust) 说 Claude Code 将信任键入的位置。1132* **无对话的信任**：在 `~/.claude.json` 中设置 `projects["<path>"].hasTrustDialogAccepted` 为 `true`。`<path>` 是文件夹 [项目允许规则和工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust) 说 Claude Code 将信任键入的文件夹。

1134 1133

1135Claude Code 对在 [代理文件](/docs/zh-CN/sub-agents#scope-mcp-servers-to-a-subagent) 中声明的服务器应用相同的规则，检查该代理文件来自何处：您的项目（对于其 `.claude/agents/` 目录中的文件）或 `--add-dir` 目录。直到您 [信任该项目或目录本身](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder)，Claude Code 不会加载服务器，因此其助手也永远不会运行。1134Claude Code 对声明为内联的服务器应用相同的规则，在 [代理文件](/docs/zh-CN/sub-agents#scope-mcp-servers-to-a-subagent) 中，检查该代理文件来自何处：您的项目，对于其 `.claude/agents/` 目录中的文件，或 `--add-dir` 目录。直到您 [信任该项目或目录本身](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder)，Claude Code 不加载服务器，因此其助手也永远不会运行。

1136 1135

1137<h2 id="add-mcp-servers-from-json-configuration">1136<h2 id="add-mcp-servers-from-json-configuration">

1138 从 JSON 配置添加 MCP 服务器1137 从 JSON 配置添加 MCP 服务器

1235 </Step>1234 </Step>

1236</Steps>1235</Steps>

1237 1236

1237Anthropic 还自己提供一些连接器，无需您或管理员添加它们。在 [Claude Docs](/docs/zh-CN/artifacts#write-a-document-with-claude-docs) 可用的账户上，`/mcp` 列出 `claude.ai Claude Docs`，无需设置，当您要求创建供他人使用的文档时，Claude 会使用它。要关闭它，请将 `serverName` 条目 `"claude.ai Claude Docs"` 添加到 `deniedMcpServers`，或使用 `/mcp` 切换，两者都在 [禁用 claude.ai 连接器](#disable-claude-ai-connectors) 中描述。

1238

1238当您的组织在 claude.ai 中管理其身份验证时，Claude Code 在 `/mcp` 和 [`/plugin`](/docs/zh-CN/plugins/install) 管理器中将连接器标记为 `managed`。托管状态不会改变 Claude Code 连接到连接器的方式或应用您的组织的 [工具控制](#organization-controls-on-connector-tools)。1239当您的组织在 claude.ai 中管理其身份验证时，Claude Code 在 `/mcp` 和 [`/plugin`](/docs/zh-CN/plugins/install) 管理器中将连接器标记为 `managed`。托管状态不会改变 Claude Code 连接到连接器的方式或应用您的组织的 [工具控制](#organization-controls-on-connector-tools)。

1239 1240

1240您从未登录过的连接器会在 claude.ai 部分末尾的 `Show unused connectors` 行后面折叠，因此组织预配的列表不会填满面板。选择该行以展开它们。您之前登录过的连接器即使当前需要重新身份验证，也会保持可见。1241您从未登录过的连接器会在 claude.ai 部分末尾的 `Show unused connectors` 行后面折叠，因此组织预配的列表不会填满面板。选择该行以展开它们。您之前登录过的连接器即使当前需要重新身份验证，也会保持可见。

1250 1251

1251如果临时网络问题导致连接器列表在会话启动时无法加载，Claude Code 会在后台重试最多三次，连接器会在重试成功后出现。如果它们仍未出现，请重启 Claude Code 以再次获取列表。1252如果临时网络问题导致连接器列表在会话启动时无法加载，Claude Code 会在后台重试最多三次，连接器会在重试成功后出现。如果它们仍未出现，请重启 Claude Code 以再次获取列表。

1252 1253

1253如果 `/mcp` 显示连接器为 `connected · session token rejected`，或其详细视图显示 [`claude.ai rejected the session token`](/docs/zh-CN/errors#claude-ai-rejected-the-session-token)，则 claude.ai 拒绝了来自您的 Claude Code 登录的令牌，通常是因为登录已过期且无法刷新。再次授权连接器不会清除此状态，因为被拒绝的不是连接器在 claude.ai 中的自身授权。要清除它：1254如果 `/mcp` 显示连接器为 `session token rejected`，或其详细视图显示 [`claude.ai rejected the session token`](/docs/zh-CN/errors#claude-ai-rejected-the-session-token)，则 claude.ai 拒绝了来自您的 Claude Code 登录的令牌。再次授权连接器不会清除此状态，因为被拒绝的不是连接器在 claude.ai 中的自身授权。要清除它：

1254 1255

12551. 运行 `/login` 以重新登录。12561. 运行 `/login` 以重新登录。

12562. 从 `/mcp` 重新连接连接器。12572. 从 `/mcp` 重新连接连接器。

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

1417</Warning>1418</Warning>

1418 1419

1420<h3 id="images-in-tool-results">

1421 工具结果中的图像

1422</h3>

1423

1424当 MCP 工具返回 PNG、JPEG、GIF 或 WebP 图像时，Claude 会在对话中内联看到该图像。内联副本可能会缩小或压缩以适应模型的图像大小限制。Claude Code 还会将原始字节保存到会话的 `tool-results` 目录中的文件中，该目录位于 [`~/.claude/projects/`](/docs/zh-CN/claude-directory#cleaned-up-automatically) 下，并向 Claude 提供路径。Claude 随后可以使用 Bash 等工具裁剪、转换或重新使用完整分辨率的文件。

1425

1426如果您使用 [`--no-session-persistence`](/docs/zh-CN/cli-reference#cli-flags) 或 [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/docs/zh-CN/env-vars) 禁用会话持久化，Claude Code 将不会写入图像文件，Claude 仅接收内联副本。

1427

1428将 MCP 图像结果保存到文件需要 Claude Code v2.1.283 或更高版本。

1429

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

1420 具有根级组合器的工具输入模式1431 具有根级组合器的工具输入模式

1421</h2>1432</h2>

1487服务器可以通过两种方式请求输入：1498服务器可以通过两种方式请求输入：

1488 1499

1489* **表单模式**：Claude Code 显示一个对话框，其中包含由服务器定义的表单字段（例如，用户名和密码提示）。填写字段并提交。1500* **表单模式**：Claude Code 显示一个对话框，其中包含由服务器定义的表单字段（例如，用户名和密码提示）。填写字段并提交。

1490* **URL 模式**：Claude Code 打开浏览器 URL 进行身份验证或批准。在浏览器中完成流程，然后在 CLI 中确认。1501* **URL 模式**：Claude Code 询问是否在浏览器中打开链接，当你接受时打开该链接。服务器使用此模式处理在终端外完成的流程，例如登录。

1491 1502

1492在 URL 模式中，Claude Code 将 URL 作为命令行参数传递给系统的 URL 处理程序，并限制该参数的长度。当 URL 在为命令行转义后超过该限制时，你只能拒绝该请求。每个需要转义的字符，例如 `%` 或 `&`，都会计为上限的四倍：其自身字符加上三个转义字符。没有这些字符的 URL 在大约 8,000 个字符处达到上限。主要由百分比转义组成的 URL，其中每三个字符中有一个是 `%`，在大约 4,000 处达到上限。1503在 URL 模式中，Claude Code 将 URL 作为命令行参数传递给系统的 URL 处理程序，并限制该参数的长度。当 URL 在为命令行转义后超过该限制时，你只能拒绝该请求。每个需要转义的字符，例如 `%` 或 `&`，都会计为上限的四倍：其自身字符加上三个转义字符。没有这些字符的 URL 在大约 8,000 个字符处达到上限。主要由百分比转义组成的 URL，其中每三个字符中有一个是 `%`，在大约 4,000 处达到上限。

1493 1504

1495 1506

1496如果你正在构建使用引出功能的 MCP 服务器，请参阅 [MCP 引出规范](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation) 了解协议详情和架构示例。1507如果你正在构建使用引出功能的 MCP 服务器，请参阅 [MCP 引出规范](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation) 了解协议详情和架构示例。

1497 1508

1509在使用 [protocol revision 2026-07-28](#mcp-client-runtimes) 的连接上，Claude Code 在其客户端功能中声明 `elicitation: {form: {}, url: {}}`，因此该处的服务器可以通过协议的标准引出请求来请求任一模式。

1510

1498<h2 id="use-mcp-resources">1511<h2 id="use-mcp-resources">

1499 使用 MCP 资源1512 使用 MCP 资源

1500</h2>1513</h2>

1540 * 资源可以包含 MCP 服务器提供的任何类型的内容（文本、JSON、结构化数据等）1553 * 资源可以包含 MCP 服务器提供的任何类型的内容（文本、JSON、结构化数据等）

1541</Tip>1554</Tip>

1542 1555

1556MCP Apps UI 资源是具有 `ui://` URI 或 `text/html;profile=mcp-app` 媒体类型的条目：这些是供主机应用程序呈现的页面，而不是供 Claude 读取的内容。它们不会出现在 `@` 建议中或资源列表工具的结果中，仅提供 UI 资源的服务器会显示空资源列表。通过其 URI 读取 UI 资源仍然有效。

1557

1543<h2 id="scale-with-mcp-tool-search">1558<h2 id="scale-with-mcp-tool-search">

1544 使用 MCP 工具搜索进行扩展1559 使用 MCP 工具搜索进行扩展

1545</h2>1560</h2>

1643 1658

1644MCP 服务器可以公开提示，这些提示在 Claude Code 中作为命令可用。1659MCP 服务器可以公开提示，这些提示在 Claude Code 中作为命令可用。

1645 1660

1661来自名为 `anthropic-skills` 的服务器的提示不会出现，因为 Claude Code [保留该名称](/docs/zh-CN/skills#names-reserved-for-synced-skills)用于从 claude.ai 同步的 skills。该服务器的工具仍然有效。在您的 MCP 配置中重命名服务器以列出其提示。

1662

1646<h3 id="execute-mcp-prompts">1663<h3 id="execute-mcp-prompts">

1647 执行 MCP 提示1664 执行 MCP 提示

1648</h3>1665</h3>

memory.md +12 −3

Details

103 103

104**一致性**：如果两条规则相互矛盾，Claude 可能会任意选择一条。定期审查您的 CLAUDE.md 文件、子目录中的嵌套 CLAUDE.md 文件和 [`.claude/rules/`](#organize-rules-with-claude/rules/)，以删除过时或冲突的指令。在 monorepos 中，使用 [`claudeMdExcludes`](#exclude-specific-claude-md-files) 跳过来自与您的工作无关的其他团队的 CLAUDE.md 文件。104**一致性**：如果两条规则相互矛盾，Claude 可能会任意选择一条。定期审查您的 CLAUDE.md 文件、子目录中的嵌套 CLAUDE.md 文件和 [`.claude/rules/`](#organize-rules-with-claude/rules/)，以删除过时或冲突的指令。在 monorepos 中，使用 [`claudeMdExcludes`](#exclude-specific-claude-md-files) 跳过来自与您的工作无关的其他团队的 CLAUDE.md 文件。

105 105

106要让 Claude 检查这些文件是否有过时或冲突的指令，请在会话中运行 `/doctor prompt-audit`。Claude 读取您的 CLAUDE.md、CLAUDE.local.md 和 AGENTS.md 文件，以及 `.claude/` 和 `~/.claude/` 下的规则、skills、命令、子代理和输出样式。它查找问题，例如为旧模型编写的指令、对不存在的文件或命令的引用，以及相互矛盾的文件。您会获得一份发现报告和一组建议的编辑，在您要求 Claude 应用它们之前，您的文件中不会有任何更改。

107

108要审计一个文件或目录，请改为传递其路径，例如 `/doctor prompt-audit .claude/skills/deploy`。审计通过捆绑的 `/claude-api` skill 运行，因此在该 skill 在 [`skillOverrides`](/docs/zh-CN/skills#override-skill-visibility-from-settings) 中关闭或使用 [`disableBundledSkills`](/docs/zh-CN/settings-reference#disablebundledskills) 时不可用。`/doctor prompt-audit` 需要 Claude Code v2.1.283 或更高版本。

109

106<h3 id="import-additional-files">110<h3 id="import-additional-files">

107 导入其他文件111 导入其他文件

108</h3>112</h3>

273ln -s ~/company-standards/security.md .claude/rules/security.md277ln -s ~/company-standards/security.md .claude/rules/security.md

274```278```

275 279

280如果您指向网络路径（如 UNC 共享 `\\server\share` 或 `/net` 或 `/Network` 下的路径）的 `.claude/rules/` 或 `CLAUDE.md` 符号链接，链接的指令不加载。Claude Code 不跟随链接，因为查找此类路径可能会联系它命名的主机。`\\wsl$` 路径不计为网络路径。

281

276<h4 id="user-level-rules">282<h4 id="user-level-rules">

277 用户级规则283 用户级规则

278</h4>284</h4>

620* 检查相关 CLAUDE.md 是否在为你的会话加载的位置（参见 [选择 CLAUDE.md 文件的位置](#choose-where-to-put-claude-md-files)）。626* 检查相关 CLAUDE.md 是否在为你的会话加载的位置（参见 [选择 CLAUDE.md 文件的位置](#choose-where-to-put-claude-md-files)）。

621* 使指令更具体。"使用 2 空格缩进"比"格式化代码很好"效果更好。627* 使指令更具体。"使用 2 空格缩进"比"格式化代码很好"效果更好。

622* 查找跨 CLAUDE.md 文件的冲突指令。如果两个文件为相同行为提供不同的指导，Claude 可能会任意选择一个。628* 查找跨 CLAUDE.md 文件的冲突指令。如果两个文件为相同行为提供不同的指导，Claude 可能会任意选择一个。

629* 检查你的指令是否与 Claude Code 自身添加的指导相竞争。如果你的 CLAUDE.md 设置了提交或拉取请求规则，请使用 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions) 关闭内置规则，并使用 [`attribution`](/docs/zh-CN/settings-reference#attribution) 设置归属文本。

623 630

624如果指令是必须在特定点运行的内容，例如在每次提交之前或每次文件编辑之后，请将其写成 [hook](/docs/zh-CN/hooks-guide) 代替。Hooks 在固定的生命周期事件处作为 shell 命令执行，并且无论 Claude 决定做什么都适用。631如果指令是必须在特定点运行的内容，例如在每次提交之前或每次文件编辑之后，请将其写成 [hook](/docs/zh-CN/hooks-guide) 代替。Hooks 在固定的生命周期事件处作为 shell 命令执行，并且无论 Claude 决定做什么都适用。

625 632

626对于你想要在系统提示级别的指令，使用 [`--append-system-prompt`](/docs/zh-CN/cli-reference#system-prompt-flags)。你在启动时传递它，因此它更适合脚本和自动化而不是交互式使用。有关它在恢复对话时的行为，请参见 [System prompt flags in resumed conversations](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。633对于你想要在系统提示级别的指令，使用 [`--append-system-prompt`](/docs/zh-CN/cli-reference#system-prompt-flags)。你在启动时传递它，因此它更适合脚本和自动化而不是交互式使用。有关它在恢复对话时的行为，请参见 [恢复对话中的系统提示标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。

627 634

628<Tip>635<Tip>

629 使用 [`InstructionsLoaded` hook](/docs/zh-CN/hooks#instructionsloaded) 记录确切加载了哪些 `CLAUDE.md` 和规则文件、何时加载以及为什么。这对于调试特定路径规则或子目录中的延迟加载文件很有用。636 使用 [`InstructionsLoaded` hook](/docs/zh-CN/hooks#instructionsloaded) 记录确切加载了哪些 `CLAUDE.md` 和规则文件、何时加载以及为什么。这对于调试特定路径规则或子目录中的延迟加载文件很有用。

657 664

658超过 200 行的文件消耗更多上下文并可能降低遵守度。Claude Code 跳过超过 4 MiB 的文件。使用 [path-scoped rules](#path-specific-rules) 仅在 Claude 处理匹配文件时加载指令，或修剪不是每个会话都需要的内容。分割到 [`@path` imports](#import-additional-files) 有助于组织，但不会减少上下文，因为导入的文件在启动时加载。665超过 200 行的文件消耗更多上下文并可能降低遵守度。Claude Code 跳过超过 4 MiB 的文件。使用 [path-scoped rules](#path-specific-rules) 仅在 Claude 处理匹配文件时加载指令，或修剪不是每个会话都需要的内容。分割到 [`@path` imports](#import-additional-files) 有助于组织，但不会减少上下文，因为导入的文件在启动时加载。

659 666

667如果你的一个指令文件超过推荐长度，你会在启动时和运行 `/status` 时看到警告。当每个都在该长度内的文件在会话开始时加起来超过组合限制时，你也会看到警告。每个 CLAUDE.md、规则文件和 `@path` 导入都计为单独的文件。

668

660[`/doctor`](/docs/zh-CN/commands#all-commands) 检查为已检入的 CLAUDE.md 提议修剪：它删除 Claude 可以从代码库派生的内容，例如目录布局、依赖项列表和架构概览，并保留与工具默认值不同的陷阱、基本原理和约定。修剪检查需要 Claude Code v2.1.206 或更高版本。669[`/doctor`](/docs/zh-CN/commands#all-commands) 检查为已检入的 CLAUDE.md 提议修剪：它删除 Claude 可以从代码库派生的内容，例如目录布局、依赖项列表和架构概览，并保留与工具默认值不同的陷阱、基本原理和约定。修剪检查需要 Claude Code v2.1.206 或更高版本。

661 670

662<h3 id="instructions-seem-lost-after-/compact">671<h3 id="instructions-seem-lost-after-/compact">

665 674

666项目根 CLAUDE.md 在压缩中存活：在 `/compact` 之后，Claude 从磁盘重新读取它并将其重新注入到会话中。子目录中的嵌套 CLAUDE.md 文件和具有 [`paths:` frontmatter](#path-specific-rules) 的规则在 Claude 读取它们适用的文件时重新加载。675项目根 CLAUDE.md 在压缩中存活：在 `/compact` 之后，Claude 从磁盘重新读取它并将其重新注入到会话中。子目录中的嵌套 CLAUDE.md 文件和具有 [`paths:` frontmatter](#path-specific-rules) 的规则在 Claude 读取它们适用的文件时重新加载。

667 676

668如果指令在压缩后消失，它要么仅在对话中给出，要么位于尚未重新加载的嵌套 CLAUDE.md 中，或者是尚未匹配文件的路径范围规则。将仅对话的指令添加到 CLAUDE.md 以使其持久化。有关完整的细分，请参阅 [What survives compaction](/docs/zh-CN/context-window#what-survives-compaction)。677如果指令在压缩后消失，它要么仅在对话中给出，要么位于尚未重新加载的嵌套 CLAUDE.md 中，或者是尚未匹配文件的路径范围规则。将仅对话的指令添加到 CLAUDE.md 以使其持久化。有关完整的细分，请参阅 [压缩后存活的内容](/docs/zh-CN/context-window#what-survives-compaction)。

669 678

670有关大小、结构和具体性的指导，请参阅 [Write effective instructions](#write-effective-instructions)。679有关大小、结构和具体性的指导，请参阅 [编写有效的指令](#write-effective-instructions)。

671 680

672<h2 id="related-resources">681<h2 id="related-resources">

673 相关资源682 相关资源

mobile.md +1 −1

Details

43| 功能 | 您连接到的内容 | 何时使用 |43| 功能 | 您连接到的内容 | 何时使用 |

44| :- | :- | :- |44| :- | :- | :- |

49 49

model-config.md +201 −127

Details

7> 配置 Claude Code 使用的模型、工作量级别、扩展上下文和自动压缩窗口7> 配置 Claude Code 使用的模型、工作量级别、扩展上下文和自动压缩窗口

8 8

9<h2 id="available-models">9<h2 id="available-models">

~~10 可用的模型~~10 可用模型

11</h2>11</h2>

12 12

13对于 Claude Code 中的 `model` 设置，你可以配置以下任一项：13对于 Claude Code 中的 `model` 设置，你可以配置以下任一项：

14 14

15* 一个**模型别名**15* 一个**模型别名**

16* 一个**模型名称**16* 一个**模型名称**

~~17 * Anthropic API：一个完整的\*\*[模型名称](https://platform.claude.com/docs/en/about-claude/models/overview)\*\*~~17 * Anthropic API：完整的\*\*[模型名称](https://platform.claude.com/docs/en/about-claude/models/overview)\*\*

~~18 * Amazon Bedrock：一个推理配置文件 ARN~~18 * Amazon Bedrock：推理配置文件 ARN

~~19 * Microsoft Foundry：一个部署名称~~19 * Microsoft Foundry：部署名称

~~20 * Google Cloud 的 Agent Platform：一个版本名称~~20 * Google Cloud 的 Agent Platform：版本名称

21 21

22有关哪种模型和工作量级别适合不同类型工作的指导，请参阅博客上的 [Choosing a Claude model and effort level in Claude Code](https://claude.com/blog/claude-model-and-effort-level-in-claude-code)。22有关哪种模型和工作量级别适合不同类型工作的指导，请参阅博客上的 [Choosing a Claude model and effort level in Claude Code](https://claude.com/blog/claude-model-and-effort-level-in-claude-code)。

23 23

33 33

34| 模型别名 | 行为 |34| 模型别名 | 行为 |

35| - | - |35| - | - |

38| **`fable`** | 为你最困难和运行时间最长的任务使用[你的提供商的 Fable 模型](#fable-alias-resolution) |38| **`fable`** | 为你最困难和运行时间最长的任务使用[你的提供商的 Fable 模型](#fable-alias-resolution) |

39| **`sonnet`** | 为日常编码任务使用最新的 Sonnet 模型 |39| **`sonnet`** | 为日常编码任务使用最新的 Sonnet 模型 |

40| **`opus`** | 为复杂推理任务使用最新的 Opus 模型 |40| **`opus`** | 为复杂推理任务使用最新的 Opus 模型 |

41| **`haiku`** | 为简单任务使用快速高效的 Haiku 模型 |41| **`haiku`** | 为简单任务使用快速高效的 Haiku 模型 |

42| **`sonnet[1m]`** | 为长会话使用具有 [100 万令牌上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) 的 Sonnet。当 `sonnet` 已经解析到具有其原生 1M 窗口的 Sonnet 5 时无效；在 [LLM 网关](/docs/zh-CN/llm-gateway) 后面，为 Sonnet 5 选择 1M 窗口 |42| **`sonnet[1m]`** | 为长会话使用具有 [100 万令牌上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) 的 Sonnet。当 `sonnet` 已解析到具有原生 1M 窗口的 Sonnet 5.5 或 Sonnet 5 时无效；在 [LLM 网关](/docs/zh-CN/llm-gateway) 后面，为该模型选择 1M 窗口 |

43| **`opus[1m]`** | 为长会话使用具有 [100 万令牌上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) 的 Opus |43| **`opus[1m]`** | 为长会话使用具有 [100 万令牌上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) 的 Opus |

44| **`opusplan`** | 特殊模式，在 Plan Mode 期间使用 `opus`，然后在执行期间切换到 `sonnet` |44| **`opusplan`** | 特殊模式，在 Plan Mode 期间使用 `opus`，然后在执行期间切换到 `sonnet` |

45 45

47 47

48| 提供商 | `opus` | `sonnet` |48| 提供商 | `opus` | `sonnet` |

49| :- | :- | :- |49| :- | :- | :- |

54 54

55<span id="fable-alias-resolution" />55<span id="fable-alias-resolution" />

56 56

57除非你设置 `ANTHROPIC_DEFAULT_FABLE_MODEL`，否则 `fable` 别名解析到 Fable 5.1，除了在 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话中，其中 `fable` 和 `best` 解析到 Fable 5。在 v2.1.257 之前，`fable` 在每个提供商上都解析到 Fable 5。57除非你设置 `ANTHROPIC_DEFAULT_FABLE_MODEL`，否则 `fable` 别名解析到 Fable 5.1，除了在 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话中，其中 `fable` 和 `best` 解析到 Fable 5。

58 58

59未配置为提供 `claude-fable-5-1` 的网关会拒绝对该模型的请求。要通过提供它的网关使用 Fable 5.1，请使用 `/model claude-fable-5-1` 选择它。59未配置为提供 `claude-fable-5-1` 的网关会拒绝对该模型的请求。要通过提供它的网关使用 Fable 5.1，请使用 `/model claude-fable-5-1` 选择它。

60 60

61当别名解析到较旧的模型时，可以通过显式选择完整模型名称或设置 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 来获得较新的模型。61当别名解析到较旧的模型时，可以通过显式选择完整模型名称或设置 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 来获得较新的模型。

62 62

63在 v2.1.280 之前，`opus` 在 Anthropic API、Claude Platform on AWS、Amazon Bedrock 和 Google Cloud 的 Agent Platform 上从 v2.1.219 开始解析到 Opus 5。在 v2.1.219 之前，`opus` 在 Anthropic API 上从 v2.1.154 开始解析到 Opus 4.8，在 Claude Platform on AWS、Amazon Bedrock 和 Google Cloud 的 Agent Platform 上从 v2.1.207 开始解析到 Opus 4.8。在 v2.1.207 之前，`opus` 在 Claude Platform on AWS 上解析到 Opus 4.7，在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上解析到 Opus 4.6。63较早的版本将这些别名解析到较旧的模型。有关每个别名更改的版本，请参阅[版本历史](#version-history)。

64 64

65别名指向你的提供商的推荐版本，并随时间更新。要固定到特定版本，请使用完整模型名称，例如 `claude-opus-5-5`，或设置相应的环境变量，如 `ANTHROPIC_DEFAULT_OPUS_MODEL`。65别名指向你的提供商的推荐版本，并随时间更新。要固定到特定版本，请使用完整模型名称，例如 `claude-opus-5-5`，或设置相应的环境变量，如 `ANTHROPIC_DEFAULT_OPUS_MODEL`。

66 66

67<Note>67<Note>

~~68 Opus 5.5 需要 Claude Code v2.1.280 或更高版本。Opus 5 需要 v2.1.219 或更高版本。Sonnet 5 需要 v2.1.197 或更高版本。运行 `claude update` 进行升级。~~68 Sonnet 5.5 需要 Claude Code v2.1.284 或更高版本，Opus 5.5 需要 v2.1.280 或更高版本。运行 `claude update` 进行升级。

69</Note>69</Note>

70 70

71<h3 id="work-with-fable">71<h3 id="work-with-fable">

72 使用 Fable72 使用 Fable

73</h3>73</h3>

74 74

75[Claude Fable 5.1](https://platform.claude.com/docs/en/about-claude/models/overview) 和 Claude Fable 5 是 Claude Code 中最强大的模型，适合于比单次会话更大的任务。它们能够维持长时间的自主会话，在行动前进行调查，并比较小的模型更频繁地验证其工作。Fable 5.1 是较新的版本。75[Claude Fable 5.1](https://platform.claude.com/docs/en/about-claude/models/overview) 和 Claude Fable 5 是 Claude Code 中最强大的模型，适合大于单次会话的任务。它们能够维持长时间的自主会话，在行动前进行调查，并比较小的模型更频繁地验证其工作。Fable 5.1 是较新的版本。

76 76

77这两个 Fable 模型都不是任何计划或提供商上的账户类型默认值。显式选择一个：77这两个 Fable 模型都不是任何计划或提供商上的账户类型默认值。显式选择一个：

78 78

79* **Fable 5.1**：运行 `/model fable`，或使用 `claude --model fable` 启动。在 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话中，别名解析到 Fable 5，改为运行 `/model claude-fable-5-1`。79* **Fable 5.1**：运行 `/model fable`，或使用 `claude --model fable` 启动。在 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话中，别名解析到 Fable 5，改为运行 `/model claude-fable-5-1`。

80* **Fable 5**：按模型 ID 选择它。在 Anthropic API 上，运行 `/model claude-fable-5` 或使用 `claude --model claude-fable-5` 启动。在其他提供商上，使用你的提供商的 Fable 5 模型 ID 或使用 `ANTHROPIC_DEFAULT_FABLE_MODEL` [固定它](#pin-models-for-third-party-deployments)。80* **Fable 5**：按模型 ID 选择它。在 Anthropic API 上，运行 `/model claude-fable-5` 或使用 `claude --model claude-fable-5` 启动。在其他提供商上，使用你的提供商的 Fable 5 模型 ID 或使用 `ANTHROPIC_DEFAULT_FABLE_MODEL` [固定它](#pin-models-for-third-party-deployments)。

81 81

82如果你直接连接到 Anthropic API，并且你的用户设置将 `claude-fable-5` 或 `claude-fable-5[1m]` 作为模型，例如因为你在 v2.1.257 之前在 `/model` 选择器中选择了 Fable，Claude Code 会在你第一次运行 v2.1.257 或更高版本时将该保存的值更改为 `fable` 或 `fable[1m]` 别名。启动模型行显示 `(auto-updated)` 一次。项目、本地或托管设置中的 `claude-fable-5` 值保持原样。82如果你直接连接到 Anthropic API，并且你的用户设置将 `claude-fable-5` 或 `claude-fable-5[1m]` 作为模型，例如因为你在 v2.1.257 之前在 `/model` 选择器中选择了 Fable，Claude Code 会在你首次运行 v2.1.257 或更高版本时将该保存的值更改为 `fable` 或 `fable[1m]` 别名。启动模型行显示 `(auto-updated)` 一次。项目、本地或托管设置中的 `claude-fable-5` 值保持原样。

83 83

84Fable 模型的安全分类器标记的请求，最常见于网络安全和生物学领域，会触发[自动模型回退](#automatic-model-fallback)。84Fable 模型的安全分类器标记的请求，最常见于网络安全和生物学领域，会触发[自动模型回退](#automatic-model-fallback)。

85 85

94 Fable 5.1 需要 Claude Code v2.1.257 或更高版本。如果来自较旧版本的请求失败，请参阅 [Claude Code does not support this model](/docs/zh-CN/errors#claude-code-does-not-support-this-model)。运行 `claude update` 进行升级。有关零数据保留下的可用性，请参阅 [Model availability under ZDR](/docs/zh-CN/zero-data-retention#model-availability-under-zdr)。94 Fable 5.1 需要 Claude Code v2.1.257 或更高版本。如果来自较旧版本的请求失败，请参阅 [Claude Code does not support this model](/docs/zh-CN/errors#claude-code-does-not-support-this-model)。运行 `claude update` 进行升级。有关零数据保留下的可用性，请参阅 [Model availability under ZDR](/docs/zh-CN/zero-data-retention#model-availability-under-zdr)。

95</Note>95</Note>

96 96

97在 Anthropic API 上，Fable 模型仅在 `/model` 选择器中列出，除非 [`availableModels`](#restrict-model-selection) 或[组织模型限制](#organization-model-restrictions)排除它。当你的组织根本无法使用 Fable 时，例如在[零数据保留](/docs/zh-CN/zero-data-retention#model-availability-under-zdr)下，该行在选择器中保持灰显，并附有说明原因的注释。97在 Anthropic API 上，Fable 模型出现在 `/model` 选择器中，除非 [`availableModels`](#restrict-model-selection) 或[组织模型限制](#organization-model-restrictions)排除它。当你的组织根本无法使用 Fable 时，例如在[零数据保留](/docs/zh-CN/zero-data-retention#model-availability-under-zdr)下，该行在选择器中保持灰显，并附有说明原因的注释。

98 98

99<h4 id="fable-and-usage-credits">99<h4 id="fable-and-usage-credits">

100 Fable 和使用额度100 Fable 和使用额度

101</h4>101</h4>

102 102

103根据你的计划和座位等级，Fable 使用可以计入[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，而不是从你的计划的包含限额中扣除。当这样做时，`/model` 选择器在 Fable 行上显示"需要使用额度"。要管理使用额度，请参阅 [Add usage credits to your subscription](/docs/zh-CN/costs#add-usage-credits-to-your-subscription)。103根据你的计划和座位等级，Fable 使用可以计入[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，而不是从你的计划的包含限制中扣除。当它这样做时，`/model` 选择器在 Fable 行上显示"需要使用额度"。要管理使用额度，请参阅 [Add usage credits to your subscription](/docs/zh-CN/costs#add-usage-credits-to-your-subscription)。

104 104

105在交互式会话中，Claude Code 在 Fable 请求计入使用额度之前显示同意提示。企业计划的成员（具有组织计费）不会看到该提示。你可以继续使用 Fable 并使用使用额度，或切换到你的默认模型。你也可以关闭提示：105在交互式会话中，Claude Code 在 Fable 请求计入使用额度之前显示同意提示。企业计划的成员（具有组织计费）不会看到该提示。你可以继续使用 Fable 使用额度或切换到你的默认模型。你也可以关闭提示：

106 106

107* 在 `/model` 选择器中，你保持当前模型。107* 在 `/model` 选择器中，你保持当前模型。

108* 在会话中途，Claude Code 继续在你的默认模型上进行该轮。108* 在会话中途，Claude Code 继续在你的默认模型上进行该轮。

109 109

110在你选择继续使用 Fable 并使用使用额度后，Claude Code 不会再显示该提示。110在你选择继续使用 Fable 使用额度后，Claude Code 不会再显示该提示。

111 111

112在与 [Remote Control](/docs/zh-CN/remote-control) 连接的会话中、[后台会话](/docs/zh-CN/agent-view)中或 [agent team](/docs/zh-CN/agent-teams) 队友的会话中，可能没有人在终端，所以 Claude Code 会将中途同意提示保持到 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 截止时间，默认为五分钟。如果到截止时间没有人回答，Claude Code 会结束该轮而不发送请求，并在记录中添加通知，Remote Control 客户端也会显示该通知。你的模型选择保持不变，Claude Code 会在你的下一条消息上再次请求同意。112在与 [Remote Control](/docs/zh-CN/remote-control) 连接的会话中、[后台会话](/docs/zh-CN/agent-view)中或[代理团队](/docs/zh-CN/agent-teams)队友的会话中，可能没有人在终端，所以 Claude Code 会将中途同意提示保持到 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 截止时间，默认为五分钟。如果到截止时间没有人回答，Claude Code 会结束该轮而不发送请求，并在记录中添加通知，Remote Control 客户端也会显示该通知。你的模型选择保持不变，Claude Code 会在你的下一条消息上再次请求同意。

113 113

114提示等待时你可以做什么取决于会话：114提示等待时你能做什么取决于会话：

115 115

116* 在 Remote Control 连接或队友的会话中，在终端按任意键取消截止时间，Claude Code 会等待你的答案。116* 连接了 Remote Control 或在队友的会话中，在终端按任意键取消截止时间，Claude Code 会等待你的答案。

117* 在后台会话中，在截止时间前回答。117* 在后台会话中，在截止时间前回答。

118* 如果你在任何人在终端输入之前从远程客户端发送新消息，Claude Code 会以相同的方式结束该轮，你的新消息开始下一轮。在有人在终端输入后，Claude Code 继续等待答案并将你的新消息排队在其后面。118* 如果你在远程客户端发送新消息之前没有人在终端输入，Claude Code 会以相同的方式结束该轮，你的新消息开始下一轮。在有人在终端输入后，Claude Code 继续等待答案并将你的新消息排队在其后面。

119 119

120在带有 `-p` 标志的[非交互模式](/docs/zh-CN/headless)中以及通过 Agent SDK，Claude Code 永远不会显示同意提示。当 Fable 请求在那里会计入使用额度时，Claude Code 会在不询问的情况下计入它。120在带有 `-p` 标志的[非交互模式](/docs/zh-CN/headless)中以及通过 Agent SDK，Claude Code 永远不会显示同意提示。当 Fable 请求在那里会计入使用额度时，Claude Code 会在不询问的情况下计入。

121 121

122<h3 id="setting-your-model">122<h3 id="setting-your-model">

123 设置你的模型123 设置你的模型

125 125

126你可以通过多种方式配置你的模型，按优先级顺序列出：126你可以通过多种方式配置你的模型，按优先级顺序列出：

127 127

1281. **在会话期间**：使用 `/model <alias|name>` 立即切换，或运行不带参数的 `/model` 打开选择器。请参阅 [when Claude Code asks you to confirm the switch](/docs/zh-CN/prompt-caching#switching-models)1281. **在会话期间**：使用 `/model <alias|name>` 立即切换，或运行不带参数的 `/model` 打开选择器。参阅 [when Claude Code asks you to confirm the switch](/docs/zh-CN/prompt-caching#switching-models)

1292. **在启动时**：使用 `claude --model <alias|name>` 启动1292. **在启动时**：使用 `claude --model <alias|name>` 启动

1303. **环境变量**：设置 `ANTHROPIC_MODEL=<alias|name>`1303. **环境变量**：设置 `ANTHROPIC_MODEL=<alias|name>`

1314. **设置**：使用 `model` 字段在你的设置文件中永久配置1314. **设置**：使用 `model` 字段在你的设置文件中永久配置

1325. **[新会话的默认值](#set-a-default-model-for-new-sessions)**：设置 `ANTHROPIC_DEFAULT_MODEL=<alias|name>`1325. **[新会话的默认值](#set-a-default-model-for-new-sessions)**：设置 `ANTHROPIC_DEFAULT_MODEL=<alias|name>`

133 133

134`/model` 通过在你的用户设置中写入 `model` 字段来保存你的选择作为新会话的默认值。在选择器中：134`/model` 通过在你的用户设置中写入 `model` 字段，将你的选择保存为新会话的默认值。在选择器中：

135 135

136* `Enter`：切换模型并保存为你的默认值136* `Enter`：切换模型并保存为你的默认值

137* `s`：仅为此会话切换模型并保持你的默认值不变。要使用不同的键，重新绑定 [`modelPicker:thisSessionOnly`](/docs/zh-CN/keybindings#model-picker-actions)137* `s`：仅为此会话切换模型，保持你的默认值不变。要使用不同的键，重新绑定 [`modelPicker:thisSessionOnly`](/docs/zh-CN/keybindings#model-picker-actions)

138 138

139直接输入 `/model <name>` 的行为类似于 `Enter`。要仅为此会话切换，请使用 `/model` 打开选择器，并在模型的行上按 `s`。139直接输入 `/model <name>` 的行为类似于 `Enter`。要仅为此会话切换，使用 `/model` 打开选择器，然后在模型的行上按 `s`。

140 140

141如果你使用 `/model` 切换模型，该切换也会到达[继承主对话模型的子代理](/docs/zh-CN/sub-agents#choose-a-model)，因为 Claude Code 在 Claude 启动它们时从你的会话使用的模型解析它们的模型。在 Claude 将研究或测试运行委托给其中一个之前切换到 Opus，该工作也会在 Opus 上运行。要保持自定义子代理在较小的模型上，在其定义中设置 `model`。141在企业计划上，当你使用你的 claude.ai 账户登录并使用 `/model` 保存默认值时，Claude Code 也会在该账户上记录该选择。这需要 Claude Code v2.1.280 或更高版本。

142 142

143如果你在[非交互模式](/docs/zh-CN/headless)中使用 `-p` 标志设置带有 `/model` 的模型，你的选择仅适用于当前会话，不会保存为你的默认值；该模式中的 `/model` 需要 Claude Code v2.1.205 或更高版本。项目和托管设置仍然优先，并在下次启动时重新应用。你的管理员配置的[组织默认模型](#organization-default-model)也会在下次启动时重新应用。143* 当你的管理员没有设置[组织默认模型](#organization-default-model)时，[Default 选项](#default-model-setting)可以解析为记录的模型，当它这样做时，选择器的 Default 行显示该模型的名称。

144* 如果[模型限制](#restrict-model-selection)排除记录的模型或它对你的账户不可用，并且你的管理员没有设置组织默认模型，Default 选项解析如同没有记录任何内容。

145* 如果你在 `/model` 中选择 Default 或 `opusplan`，记录的选择不会改变。

146

147如果你使用 `/model` 切换模型，该切换也会到达[继承主对话模型的子代理](/docs/zh-CN/sub-agents#choose-a-model)，因为 Claude Code 在 Claude 启动它们时从你的会话正在使用的模型解析它们的模型。在 Claude 将研究或测试运行委托给其中一个之前切换到 Opus，该工作也会在 Opus 上运行。要保持自定义子代理在较小的模型上，在其定义中设置 `model`。

148

149如果你在[非交互模式](/docs/zh-CN/headless)中使用 `-p` 标志在 `/model` 中设置模型，你的选择仅适用于当前会话，不会保存为你的默认值；该模式中的 `/model` 需要 Claude Code v2.1.205 或更高版本。项目和托管设置仍然优先，并在下次启动时重新应用。你的管理员配置的[组织默认模型](#organization-default-model)以覆盖用户选择也会在下次启动时重新应用。

144 150

145在 v2.1.144 到 v2.1.152 中，`/model` 仅适用于当前会话，选择器中的 `d` 保存默认值。151在 v2.1.144 到 v2.1.152 中，`/model` 仅适用于当前会话，选择器中的 `d` 保存默认值。

146 152

147`--model` 标志和 `ANTHROPIC_MODEL` 环境变量仅适用于你使用它们启动的会话。要同时在不同的终端中运行不同的模型，请使用自己的 `--model` 标志启动每个终端，而不是使用 `/model` 切换。153`--model` 标志和 `ANTHROPIC_MODEL` 环境变量仅适用于你使用它们启动的会话。要同时在不同的终端中运行不同的模型，使用各自的 `--model` 标志启动每个，而不是使用 `/model` 切换。

148 154

149当 Claude Code 与 Anthropic API 通话时，直接或通过代理它的 [LLM 网关](/docs/zh-CN/llm-gateway)，`/model` 选择器中的价格会出现，行上的价格是该行选择的模型的价格。在 [Amazon Bedrock 等第三方提供商](/docs/zh-CN/third-party-integrations)上以及在 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 上，你的提供商或网关决定你支付的费用，所以选择器行不显示价格。价格仅是显示标签；它不影响行选择的模型或你的提供商计费的内容。在 v2.1.206 之前，[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和网关会话显示 Anthropic 列表价格，一行可能显示与其选择的模型不同的模型的价格。155当 Claude Code 与 Anthropic API 通信时（直接或通过代理它的 [LLM 网关](/docs/zh-CN/llm-gateway)），`/model` 选择器中的价格会出现，行上的价格是该行选择的模型的价格。在[第三方提供商](/docs/zh-CN/third-party-integrations)（如 Amazon Bedrock）和 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 上，你的提供商或网关决定你支付的费用，所以选择器行不显示价格。价格仅是显示标签；它不影响行选择哪个模型或你的提供商计费的内容。在 v2.1.206 之前，[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和网关会话显示 Anthropic 列表价格，行可能显示与其选择的模型不同的模型的价格。

150 156

151使用 `claude --resume`、`--continue` 或 `/resume` 选择器启动的恢复会话保持它们保存记录时使用的模型，无论当前 `model` 设置如何。如果恢复的模型已被停用或被 [`availableModels`](#restrict-model-selection) 排除，会话会回退到正常的优先级顺序。这可以防止另一个会话的 `/model` 选择在恢复时改变模型。在使用提供商特定部署 ID 而不是 Anthropic 模型 ID 的提供商上，例如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry，根本不会恢复记录模型，会话通过正常的优先级顺序解析其模型。157使用 `claude --resume`、`--continue` 或 `/resume` 选择器启动的恢复会话保持它们保存记录时使用的模型，无论当前 `model` 设置如何。如果恢复的模型已被停用或被 [`availableModels`](#restrict-model-selection) 排除，会话会回退到正常的优先级顺序。这可以防止另一个会话的 `/model` 选择在恢复时改变模型。在使用提供商特定部署 ID 而不是 Anthropic 模型 ID 的提供商上，如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry，根本不会恢复记录模型，会话通过正常的优先级顺序解析其模型。

152 158

153你为新启动使用 `--model` 或 `ANTHROPIC_MODEL` 选择的模型仍然优先于恢复的模型。从 v2.1.195 开始，[`ANTHROPIC_DEFAULT_OPUS_MODEL`](#environment-variables) 系列变量也是如此。[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions) 也可以，在其部分中列出的条件下。159你为新启动使用 `--model` 或 `ANTHROPIC_MODEL` 选择的模型仍然优先于恢复的模型。从 v2.1.195 开始，[`ANTHROPIC_DEFAULT_OPUS_MODEL`](#environment-variables) 系列变量也是如此。[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions) 也可以，在其部分中列出的条件下。

154 160

155当启动时的活动模型来自项目或托管设置而不是你自己的选择时，启动标题显示哪个设置文件设置了它。运行 `/model` 进行覆盖；项目或托管设置在下次启动时重新应用。在嵌入 Claude Code 并设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 的平台上，主机的模型配置优先于托管模型设置，而托管 `availableModels` 允许列表保持有效，除非主机提供自己的；[Exceptions to managed settings precedence](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence) 说明主机覆盖的键和变量。161当启动时的活跃模型来自项目或托管设置而不是你自己的选择时，启动标题显示哪个设置文件设置了它。运行 `/model` 覆盖；项目或托管设置在下次启动时重新应用。在嵌入 Claude Code 并设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 的平台上，主机的模型配置优先于托管模型设置，而托管 `availableModels` 允许列表保持有效，除非主机提供自己的；[Exceptions to managed settings precedence](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence) 说明主机覆盖哪些键和变量。

156 162

157如果你或你的组织配置 [PreModelSwitch hooks](/docs/zh-CN/hooks#premodelswitch)，它们在请求的切换应用之前运行，可以阻止它或要求你确认。163如果你或你的组织配置 [PreModelSwitch hooks](/docs/zh-CN/hooks#premodelswitch)，它们在请求的切换应用之前运行，可以阻止它或要求你确认。

158 164

159当 Claude Code 无法判断你的组织的[托管插件](/docs/zh-CN/settings-reference#enabledplugins)提供哪些 PreModelSwitch hooks 时，例如因为托管插件加载失败，它会拒绝切换而不是未检查地应用它，并在每次新尝试时再次检查。请参阅 [Model switch was blocked by a PreModelSwitch hook](/docs/zh-CN/errors#model-switch-was-blocked-by-a-premodelswitch-hook) 了解消息和恢复。165当 Claude Code 无法判断你的组织的[托管插件](/docs/zh-CN/settings-reference#enabledplugins)提供哪些 PreModelSwitch hooks 时，例如因为托管插件加载失败，它拒绝切换而不是应用它，并在每次新尝试时再次检查。参阅 [Model switch was blocked by a PreModelSwitch hook](/docs/zh-CN/errors#model-switch-was-blocked-by-a-premodelswitch-hook) 了解消息和恢复。

160 166

161当你通过 [Agent SDK](/docs/zh-CN/agent-sdk/overview) `setModel()` 方法切换模型，或从通过 [Remote Control](/docs/zh-CN/remote-control) 连接的设备切换，或运行 Claude Code CLI 为你切换的应用（如 [Desktop app](/docs/zh-CN/desktop)）时，Claude Code 会检查该字符串是否是它识别的字符串，然后再保存它。此检查需要 Claude Code v2.1.200 或更高版本。检查 Remote Control 选择需要你的机器上的 Claude Code v2.1.260 或更高版本。在 Anthropic API 上，Claude Code 识别：167当你通过 [Agent SDK](/docs/zh-CN/agent-sdk/overview) `setModel()` 方法或从通过 [Remote Control](/docs/zh-CN/remote-control) 连接的设备切换模型，或运行 Claude Code CLI 的应用（如 [Desktop app](/docs/zh-CN/desktop)）为你切换时，Claude Code 会检查该字符串是否是它识别的。此检查需要 Claude Code v2.1.200 或更高版本。检查 Remote Control 选择需要你的机器上的 Claude Code v2.1.260 或更高版本。在 Anthropic API 上，Claude Code 识别：

162 168

163* 一个模型别名169* 一个模型别名

164* `/model` 选择器中的一个条目170* `/model` 选择器中的一个条目

165* 任何以 `claude-` 开头的名称171* 任何以 `claude-` 开头的名称

166* 你自己配置的值作为[自定义模型选项](#add-a-custom-model-option)或在 [`modelOverrides`](#override-model-ids-per-version) 中172* 你自己配置的值，作为[自定义模型选项](#add-a-custom-model-option)或在 [`modelOverrides`](#override-model-ids-per-version) 中

167 173

168Claude Code 使用 `Model "<name>" is not a recognized model id.` 拒绝无法识别的字符串，会话保持其当前模型，而不是保存字符串并在下一个请求时失败。请参阅[错误参考](/docs/zh-CN/errors#model-is-not-a-recognized-model-id)了解恢复步骤。174Claude Code 拒绝无法识别的字符串，显示 `Model "<name>" is not a recognized model id.`，会话保持其当前模型，而不是保存字符串并在下一个请求时失败。参阅[错误参考](/docs/zh-CN/errors#model-is-not-a-recognized-model-id)了解恢复步骤。

169 175

170检查仅在 Anthropic API 上运行。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 以及在 [LLM 网关](/docs/zh-CN/llm-gateway) 或自定义 `ANTHROPIC_BASE_URL` 后面，你的提供商或网关定义模型名称，所以 Claude Code 不检查地通过任何字符串。检查也不涵盖 `--model` 标志、`ANTHROPIC_MODEL` 环境变量或 `model` 设置；那里的拼写错误值会在第一个请求时产生 [There's an issue with the selected model](/docs/zh-CN/errors#theres-an-issue-with-the-selected-model)。Claude Code 仍然可以在请求时在每个提供商上写入[无法识别的模型诊断行](/docs/zh-CN/errors#unrecognized-model-id-on-a-request)。176检查仅在 Anthropic API 上运行。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和 [LLM 网关](/docs/zh-CN/llm-gateway) 后面或自定义 `ANTHROPIC_BASE_URL`，你的提供商或网关定义模型名称，所以 Claude Code 不检查地通过任何字符串。检查也不涵盖 `--model` 标志、`ANTHROPIC_MODEL` 环境变量或 `model` 设置；那里的拼写错误值会在第一个请求时产生 [There's an issue with the selected model](/docs/zh-CN/errors#theres-an-issue-with-the-selected-model)。Claude Code 仍然可以在请求时在每个提供商上写入[无法识别的模型诊断行](/docs/zh-CN/errors#unrecognized-model-id-on-a-request)。

171 177

172当请求的模型有计划的停用日期或自动重新映射到较新版本时，Claude Code 显示一个警告，命名请求的模型。交互式会话将其显示为启动通知。从 v2.1.182 开始，当使用默认文本输出格式在[非交互模式](/docs/zh-CN/headless)中时，相同的警告被写入 stderr。检查也涵盖在[子代理 frontmatter](/docs/zh-CN/sub-agents) 中设置的 `model`。对于 `--output-format json` 和 `stream-json`，stderr 警告被抑制；改为从[结果消息](/docs/zh-CN/headless#get-structured-output)的 `modelUsage` 字段读取实际模型。178当请求的模型有计划的停用日期或自动重新映射到较新版本时，Claude Code 显示一个警告，命名请求的模型。交互式会话将其显示为启动通知。从 v2.1.182 开始，在使用默认文本输出格式的[非交互模式](/docs/zh-CN/headless)中，相同的警告被写入 stderr。检查也涵盖在[子代理前言](/docs/zh-CN/sub-agents)中设置的 `model`。对于 `--output-format json` 和 `stream-json`，stderr 警告被抑制；从[结果消息](/docs/zh-CN/headless#get-structured-output)的 `modelUsage` 字段读取实际模型。

173 179

174例如，在 Opus 上启动会话：180例如，在 Opus 上启动会话：

175 181

200 206

201设置 `ANTHROPIC_DEFAULT_MODEL=<alias|name>` 来选择你的会话默认启动的模型。需要 Claude Code v2.1.236 或更高版本。207设置 `ANTHROPIC_DEFAULT_MODEL=<alias|name>` 来选择你的会话默认启动的模型。需要 Claude Code v2.1.236 或更高版本。

202 208

203Claude Code 仅在以下都未选择模型时才在变量的模型上启动新会话：209Claude Code 仅在以下都没有选择模型时在变量的模型上启动新会话：

204 210

205* `--model` 标志211* `--model` 标志

206* `ANTHROPIC_MODEL`212* `ANTHROPIC_MODEL`

207* 任何设置文件中的 `model` 值，包括你使用 `/model` 保存的选择213* 任何设置文件中的 `model` 值，包括你使用 `/model` 保存的选择

208* [组织默认模型](#organization-default-model)214* [组织默认模型](#organization-default-model)

209 215

210你使用 `/model` 保存的选择在后续启动时也优先于变量。设置 `ANTHROPIC_MODEL` 时，Claude Code 在下次启动时返回到该变量的模型，无论你使用 `/model` 保存了什么。216你使用 `/model` 保存的选择在后续启动时也优先于变量。设置 `ANTHROPIC_MODEL` 代替，Claude Code 在下次启动时返回到该变量的模型，无论你使用 `/model` 保存了什么。

211 217

212Claude Code 也将 Default 选项解析为变量的模型，除非应用了组织默认模型。当 Default 选项解析为变量的模型时，`/model` 选择器中的 Default 行显示标签"由 ANTHROPIC\_DEFAULT\_MODEL 设置"。218Claude Code 也将 Default 选项解析为变量的模型，除非应用了组织默认模型。当 Default 选项解析为变量的模型时，`/model` 选择器中的 Default 行显示标签 Set by ANTHROPIC\_DEFAULT\_MODEL。

213 219

214Claude Code 在这些情况下忽略变量，Default 选项解析如同你未设置它：220Claude Code 在这些情况下忽略变量，Default 选项解析如同你没有设置它：

215 221

216* 你将其设置为 `default`、`inherit`、`opusplan` 或 `haiku`222* 你将其设置为 `default`、`inherit`、`opusplan` 或 `haiku`

217* [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 已打开223* [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 已打开

218* [`availableModels`](#restrict-model-selection) 或[组织模型限制](#organization-model-restrictions)排除该模型224* 你的组织的[模型限制](#restrict-model-selection)排除该模型

219* 该模型对你的账户不可用225* 该模型对你的账户不可用

220 226

221当新会话将在变量的模型上启动时，你使用 `claude --resume`、`--continue` 或 `/resume` 选择器恢复的会话也会在其上启动。Claude Code 不会恢复该会话的记录中保存的模型。否则 Claude Code 在你[恢复会话](#setting-your-model)时不使用该变量。227当新会话将在变量的模型上启动时，你使用 `claude --resume`、`--continue` 或 `/resume` 选择器恢复的会话也会在其上启动。Claude Code 不会恢复该会话的记录中保存的模型。否则 Claude Code 在你[恢复会话](#setting-your-model)时不使用变量。

222 228

223<h4 id="a-new-session-starts-on-a-different-model-than-you-picked">229<h4 id="a-new-session-starts-on-a-different-model-than-you-picked">

224 新会话在与你选择的不同的模型上启动230 新会话在与你选择的不同的模型上启动

225</h4>231</h4>

226 232

227当你使用 `/model` 选择模型，而你的下一个会话在其他东西上启动时，这些是常见的原因：233当你使用 `/model` 选择模型，你的下一个会话在其他东西上启动时，这些是常见原因：

228 234

229* **你为一个会话选择了它。** 在选择器中按 `s`、使用 `--model` 启动以及在非交互模式中运行 `/model` 都仅适用于当前会话，并保持你保存的默认值不变。235* **你为一个会话选择了它。** 在选择器中按 `s`、使用 `--model` 启动和在非交互模式中运行 `/model` 都仅适用于当前会话，保持你的保存默认值不变。

230* **优先级更高的东西设置了模型。** 项目或托管设置中的 `model` 值、你的 shell 中的 `ANTHROPIC_MODEL` 或你的管理员设置为覆盖用户选择的[组织默认值](#organization-default-model)在每次启动时都适用。你的 `/model` 选择仍然被保存；它被超越。当项目或托管设置设置模型时，启动标题命名该文件。236* **优先级更高的东西设置了模型。** 项目或托管设置中的 `model` 值、你的 shell 中的 `ANTHROPIC_MODEL` 或你的管理员设置的[组织默认值](#organization-default-model)以覆盖用户选择在每次启动时再次应用。你的 `/model` 选择仍然被保存；它被超越。当项目或托管设置设置模型时，启动标题命名该文件。

231* **Claude Code 无法保存你的选择。** `/model` 写入 `~/.claude/settings.json`。如果你无法写入该文件，例如因为另一个工具生成它或将其链接到只读副本，你选择的模型持续该会话，下次启动读取旧值。在生成文件的工具中设置 `model`，或使文件可写。请参阅 [A change you made in Claude Code is lost in new sessions](/docs/zh-CN/settings#a-change-you-made-in-claude-code-is-lost-in-new-sessions)。237* **Claude Code 无法保存你的选择。** `/model` 写入 `~/.claude/settings.json`。如果你无法写入该文件，例如因为另一个工具生成它或将其链接到只读副本，你选择的模型持续该会话，下次启动读取旧值。在生成文件的工具中设置 `model`，或使文件可写。参阅 [A change you made in Claude Code is lost in new sessions](/docs/zh-CN/settings#a-change-you-made-in-claude-code-is-lost-in-new-sessions)。

232* **你恢复了一个会话。** 你使用 `claude --resume` 或 `--continue` 恢复的会话通常[保持它使用的模型](#setting-your-model)而不是你当前的默认值。238* **你恢复了一个会话。** 你使用 `claude --resume` 或 `--continue` 恢复的会话通常[保持它使用的模型](#setting-your-model)而不是你的当前默认值。

233 239

234<h2 id="restrict-model-selection">240<h2 id="restrict-model-selection">

235 限制模型选择241 限制模型选择

236</h2>242</h2>

237 243

238企业管理员可以在[托管或策略设置](/docs/zh-CN/managed-settings)中使用 `availableModels` 来限制用户可以选择的模型。条目可以匹配模型系列（如 `sonnet`）、版本前缀（如 `claude-sonnet-4-5`）或完整模型 ID（如 `claude-sonnet-4-5-20250929`）。版本前缀也会匹配扩展它的后续模型 ID，因此 `claude-fable-5` 允许 Fable 5 和 Fable 5.1，而 `claude-fable-5-1` 仅允许 Fable 5.1。244企业管理员可以在[托管或策略设置](/docs/zh-CN/managed-settings)中使用 `availableModels` 来限制用户可以选择的模型。条目可以匹配模型系列（如 `sonnet`）、版本前缀（如 `claude-sonnet-4-5`）或完整模型 ID（如 `claude-sonnet-4-5-20250929`）。版本前缀也会匹配扩展它的后续模型 ID，因此 `claude-fable-5` 允许 Fable 5 和 Fable 5.1，而 `claude-fable-5-1` 仅允许 Fable 5.1。要阻止列表允许的模型，或使每个模型 ID 条目仅允许它命名的版本，请参阅[阻止特定模型或版本](#block-specific-models-or-versions)。

239 245

240在嵌入 Claude Code 并设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 的平台上，主机的模型配置优先于托管模型设置，而托管的 `availableModels` 允许列表保持有效，除非主机提供自己的列表；[托管设置优先级的例外](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence)说明了主机覆盖的密钥和变量。246在嵌入 Claude Code 并设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 的平台上，主机的模型配置优先于托管模型设置，而托管的 `availableModels` 允许列表保持有效，除非主机提供自己的列表；[托管设置优先级的例外](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence)说明了主机覆盖的键和变量。

241 247

242当设置 `availableModels` 时，允许列表适用于用户可以指定模型的所有地方：248设置 `availableModels` 时，允许列表适用于用户可以指定模型的所有地方：

243 249

244* **主会话模型**：`/model`、`--model` 标志、`ANTHROPIC_MODEL` 环境变量、`model` 设置、[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions) 以及[恢复会话](#setting-your-model)时恢复的模型250* **主会话模型**：`/model`、`--model` 标志、`ANTHROPIC_MODEL` 环境变量、`model` 设置、[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions) 和[恢复会话](#setting-your-model)时恢复的模型

245* **别名解析**：环境变量 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` 和 `ANTHROPIC_DEFAULT_FABLE_MODEL` 不能将允许的别名重定向到列表外的模型251* **别名解析**：环境变量 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL` 和 `ANTHROPIC_DEFAULT_FABLE_MODEL` 无法将允许的别名重定向到列表外的模型

246* **快速模式**：当 `/fast` 会隐式切换到列表外的 Opus 模型时，它会拒绝切换，并显示消息"不在您组织的允许模型中"252* **快速模式**：当 `/fast` 会隐式切换到列表外的 Opus 模型时，它会拒绝切换，并显示消息"不在您组织的允许模型中"

247* **子代理和队友模型**：[子代理](/docs/zh-CN/sub-agents#choose-a-model)前置元数据中的 `model` 字段、Agent 工具的 `model` 参数、[代理团队](/docs/zh-CN/agent-teams#specify-teammates-and-models)队友模型、`CLAUDE_CODE_SUBAGENT_MODEL` 以及在 v2.1.197 及更早版本中，`/agents` 向导中的模型选择器 253* **子代理和队友模型**：[子代理](/docs/zh-CN/sub-agents#choose-a-model)前置元数据中的 `model` 字段、Agent 工具的 `model` 参数、[代理团队](/docs/zh-CN/agent-teams#specify-teammates-and-models)队友模型、`CLAUDE_CODE_SUBAGENT_MODEL`，以及在 v2.1.197 及更早版本中，`/agents` 向导中的模型选择器 

248* **技能和命令模型**：[技能和命令](/docs/zh-CN/skills)中的 `model` 前置元数据254* **技能和命令模型**：[技能和命令](/docs/zh-CN/skills)中的 `model` 前置元数据

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

250* **后台代理模型**：在[分派选择器](/docs/zh-CN/agent-view)中选择的模型256* **后台代理模型**：在[分派选择器](/docs/zh-CN/agent-view)中选择的模型

251 257

252在 Anthropic API 和 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 上，模型系列别名 `opus`、`sonnet`、`haiku` 或 `fable` 在允许列表允许该模型时解析为其通常的模型。当允许列表阻止该模型时，Claude Code 会替换允许列表允许的该系列的最新版本，并显示一条通知，命名请求的和替换的模型。例如，使用 `["sonnet", "claude-opus-4-6"]`，`/model opus` 和 `--model opus` 都会选择 Claude Opus 4.6，这是允许的最新 Opus。在 v2.1.205 之前，其最新发布版本在列表外的别名被拒绝或替换，就像任何其他被阻止的选择一样，即使列表允许较旧版本。258在 Anthropic API 和 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 上，当允许列表允许该模型时，模型系列别名 `opus`、`sonnet`、`haiku` 或 `fable` 解析为其通常的模型。当允许列表阻止该模型时，Claude Code 替换允许列表允许的该系列的最新版本，并显示一条通知，命名请求的和替换的模型。例如，使用 `["sonnet", "claude-opus-4-6"]`，`/model opus` 和 `--model opus` 都选择 Claude Opus 4.6，这是允许的最新 Opus。在 v2.1.205 之前，最新发布版本在列表外的别名被拒绝或替换，就像任何其他被阻止的选择一样，即使列表允许较旧版本。

253 259

254替换需要一个允许的版本来落地：当允许列表不允许别名系列的任何版本时，别名遵循下面的拒绝和替换行为，就像任何其他被阻止的值一样。260替换需要一个允许的版本来落地：当允许列表不允许别名系列的任何版本时，别名遵循下面的拒绝和替换行为，就像任何其他被阻止的值一样。

255 261

256Claude Code 根据模型的设置位置处理任何其他被阻止的选择：262Claude Code 根据模型的设置位置处理任何其他被阻止的选择：

257 263

258* **`/model`**：Claude Code 拒绝切换并显示错误264* **`/model`**：Claude Code 以错误拒绝切换

259* **`--model` 标志、`ANTHROPIC_MODEL` 或 `model` 设置**：Claude Code 在启动时用警告替换该值，命名请求的和替换的模型，会话在默认模型上启动265* **`--model` 标志、`ANTHROPIC_MODEL` 或 `model` 设置**：Claude Code 在启动时用警告替换该值，命名请求的和替换的模型，会话在默认模型上启动

260* **[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)**：Claude Code 忽略该变量266* **[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions)**：Claude Code 忽略该变量

261* **子代理或队友覆盖**：Claude Code 在后备模型上运行子代理或队友，而不是使请求失败。有关子代理后备，请参阅[选择模型](/docs/zh-CN/sub-agents#choose-a-model)，有关队友后备，请参阅[指定队友和模型](/docs/zh-CN/agent-teams#specify-teammates-and-models)。267* **子代理或队友覆盖**：Claude Code 在回退模型上运行子代理或队友，而不是使请求失败。有关子代理回退，请参阅[选择模型](/docs/zh-CN/sub-agents#choose-a-model)，有关队友回退，请参阅[指定队友和模型](/docs/zh-CN/agent-teams#specify-teammates-and-models)。

262 268

263 在交互式会话中，当 Claude Code 通过此后备或上面的最新允许版本替换来替换子代理的模型时，它会警告您，命名请求的和替换的模型；它不报告队友的后备。269 在交互式会话中，当 Claude Code 通过此回退或上面的最新允许版本替换来替换子代理的模型时，它会警告您，命名请求的和替换的模型；它不报告队友的回退。

264 270

265 在上面的最新允许版本替换操作的地方，被阻止的系列别名遵循它。在 v2.1.222 之前，别名在每个提供商上都像任何其他被阻止的值一样回退271 在上面的最新允许版本替换操作的地方，被阻止的系列别名遵循它。在 v2.1.222 之前，别名在每个提供商上像任何其他被阻止的值一样回退

266* **技能或命令覆盖**：Claude Code 忽略覆盖，包括被阻止的系列别名，技能或命令在会话模型上运行。[在子代理中运行](/docs/zh-CN/skills#run-skills-in-a-subagent)的技能或命令遵循上面的子代理行为272* **技能或命令覆盖**：Claude Code 忽略覆盖，包括被阻止的系列别名，技能或命令在会话模型上运行。[在子代理中运行](/docs/zh-CN/skills#run-skills-in-a-subagent)的技能或命令遵循上面的子代理行为

267* **`advisorModel` 设置**：顾问对会话被禁用273* **`advisorModel` 设置**：顾问对会话禁用

268* **`--advisor` 标志**：Claude Code 在启动时以错误退出。在[后台会话](/docs/zh-CN/agent-view)中，它在没有顾问的情况下启动会话，而不是退出274* **`--advisor` 标志**：Claude Code 在启动时以错误退出。在[后台会话](/docs/zh-CN/agent-view)中，它改为在没有顾问的情况下启动会话，而不是退出

269 275

270Claude Code 从 `/model` 选择器中隐藏排除的模型。列表中没有内置选择器行的完整模型 ID（如列表固定的较旧版本）在 `/model` 选择器中显示为其自己的标记行，除非 Claude Code 用 [`modelPicker`](/docs/zh-CN/settings-reference#modelpicker) 阵容替换内置选项。在 v2.1.199 之前，这样的 ID 只能通过键入 `/model <id>` 来选择。276Claude Code 从 `/model` 选择器中隐藏排除的模型。列表中没有内置选择器行的完整模型 ID（如列表固定的较旧版本）在 `/model` 选择器中显示为其自己的标记行，除非 Claude Code 用 [`modelPicker`](/docs/zh-CN/settings-reference#modelpicker) 阵容替换内置选项。在 v2.1.199 之前，这样的 ID 只能通过键入 `/model <id>` 来选择。

271 277

272Claude Code 代表您进行的模型更改以相同的方式进行检查：278Claude Code 代表您进行的模型更改以相同的方式检查：

273 279

274* **[后备模型链](#fallback-model-chains)**：允许列表外的条目被删除280* **[回退模型链](#fallback-model-chains)**：允许列表外的条目被删除

275* **Plan 模式升级**：在 Anthropic API 和 AWS 上的 Claude Platform 上，升级（如 [`opusplan`](#opusplan-model-setting)）到排除的模型使用升级系列允许的最新版本。在具有提供商特定模型 ID 的提供商上，以及当不允许任何版本时，升级被跳过，规划继续在会话的模型上进行281* **Plan 模式升级**：在 Anthropic API 和 AWS 上的 Claude Platform 上，升级（如 [`opusplan`](#opusplan-model-setting)）到排除的模型使用升级系列允许的最新版本。在具有提供商特定模型 ID 的提供商上，以及当不允许任何版本时，升级被跳过，规划继续在会话的模型上进行

276* **[自动模型后备](#automatic-model-fallback)**：目标被排除的后备不运行，因此标记的请求以拒绝结束282* **[自动模型回退](#automatic-model-fallback)**：目标被排除的回退不运行，因此标记的请求以拒绝结束

277* **[Auto 模式分类器](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)**：分类器的 Claude Sonnet 5 默认仅在允许列表允许 Sonnet 5 时适用。当它被排除时，分类器在会话的模型上运行，允许列表已经管理该模型，或在会话运行[Fable 模型](#work-with-fable)时在 Opus 模型上运行。在 Anthropic API 以外的提供商上，该 Opus 后备在提供商的默认 Opus 模型上运行，不咨询允许列表。需要 Claude Code v2.1.210 或更高版本283* **[自动模式分类器](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)**：分类器的 Claude Sonnet 5 默认值仅在允许列表允许 Sonnet 5 时适用。当它被排除时，分类器在会话的模型上运行，允许列表已经管理该模型，或在会话运行[Fable 模型](#work-with-fable)时在 Opus 模型上运行。在 Anthropic API 以外的提供商上，该 Opus 回退在提供商的默认 Opus 模型上运行，不咨询允许列表。需要 Claude Code v2.1.210 或更高版本

278* **[快速模式](/docs/zh-CN/fast-mode)**：当会话之后运行的模型在允许列表外时，启用快速模式被拒绝284* **[快速模式](/docs/zh-CN/fast-mode)**：当会话之后运行的模型在允许列表外时，启用快速模式被拒绝

279 285

280```json theme={null}286```json theme={null}

291 297

293| :- | :- | :- | :- | :- | :- |299| :- | :- | :- | :- | :- | :- |

296 302

297* 云会话在[Web 上的 Claude Code](/docs/zh-CN/claude-code-on-the-web) 或桌面应用中默认在 Anthropic 管理的 VM 上运行：部署到您的设备的设置不会到达它们，因此通过服务器管理设置交付允许列表。您的组织路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话在您自己的计算上运行，也读取运行器镜像中的托管设置文件。[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明了该文件何时适用。云会话中的中途模型切换在请求的模型被允许列表排除时被拒绝。当您的服务器管理设置中的 `availableModels` 列表非空时，服务器拒绝用户启动云会话的请求，该请求在列表排除的模型上。303* [云会话](/docs/zh-CN/claude-code-on-the-web)（包括您从桌面应用启动的会话）默认在 Anthropic 管理的 VM 上运行：部署到您的设备的设置不会到达它们，因此通过服务器管理设置交付允许列表。您的组织路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话在您自己的计算上运行，也读取运行器镜像中的托管设置文件。[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明了该文件何时适用。云会话中的中途模型切换在请求的模型被允许列表排除时被拒绝。当您的服务器管理设置中的 `availableModels` 列表非空时，服务器拒绝用户在列表排除的模型上启动云会话的请求。

298* Cowork 是 Claude 桌面应用中的代理工作选项卡，在 Claude Code 上运行其会话，但根据设计，不从 claude.ai 管理控制台接收服务器管理设置。托管设置文件在会话运行的地方存在时适用于 Cowork 会话；远程 Cowork 会话在 Anthropic 管理的 VM 上运行，其中不存在设备部署的文件。304* [Claude Tag](https://claude.com/docs/claude-tag/overview) 会话在云环境中运行，但不接收服务器管理设置；在[自托管环境](/docs/zh-CN/self-hosted-environments)中，它们仍然读取运行器镜像中的托管设置文件。要为这些会话设置模型，请参阅 Claude Tag 管理员指南中的[为范围选择模型](https://claude.com/docs/claude-tag/admins/customize#choose-the-model-for-a-scope)。

299* [第三方提供商](/docs/zh-CN/server-managed-settings#platform-availability)上的会话，如 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws)，不接收服务器管理设置，因此在那里通过 MDM 或托管设置文件交付允许列表。305* Cowork（Claude 桌面应用中的代理工作选项卡）在 Claude Code 上运行其会话，但按设计不从 claude.ai 管理控制台接收服务器管理设置。当托管设置文件存在于会话运行的地方时，它适用于 Cowork 会话；远程 Cowork 会话在 Anthropic 管理的 VM 上运行，其中不存在设备部署的文件。

306* [第三方提供商](/docs/zh-CN/server-managed-settings#platform-availability)（如 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws)）上的会话不接收服务器管理设置，因此通过 MDM 或托管设置文件在那里交付允许列表。

300* 服务器管理交付还需要会话使用[符合条件的登录或密钥](/docs/zh-CN/server-managed-settings#platform-availability)进行身份验证。仅通过 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本生成密钥的舰队应通过 MDM 或托管设置文件交付允许列表。307* 服务器管理交付还需要会话使用[符合条件的登录或密钥](/docs/zh-CN/server-managed-settings#platform-availability)进行身份验证。仅通过 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本生成密钥的舰队应通过 MDM 或托管设置文件交付允许列表。

301* 桌面 Code 选项卡也托管[SSH 会话](/docs/zh-CN/desktop#ssh-sessions)，它们从运行的远程主机读取托管设置文件。请参阅[桌面托管设置](/docs/zh-CN/desktop#managed-settings)。308* 桌面代码选项卡还托管 [SSH 会话](/docs/zh-CN/desktop#ssh-sessions)，它们从运行的远程主机读取托管设置文件。请参阅[桌面托管设置](/docs/zh-CN/desktop#managed-settings)。

302* claude.ai 和桌面应用中的模型选择器隐藏或灰显您的组织的允许列表排除的模型。选择器状态是用户的便利；它不强制执行允许列表。309* claude.ai 和桌面应用中的模型选择器隐藏或灰显您的组织的允许列表排除的模型。选择器状态是用户的便利；它不强制执行允许列表。

303 310

304<h3 id="default-model-behavior">311<h3 id="default-model-behavior">

305 默认模型行为312 默认模型行为

306</h3>313</h3>

307 314

308单独来说，`availableModels` 将默认选项保留在系统的[运行时默认](#default-model-setting)上，用于帐户，直到您也设置 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)。如果该默认值是您打算限制的模型，也设置 `enforceAvailableModels`。315使用默认前缀匹配，`availableModels` 本身将默认选项留在帐户的系统[运行时默认](#default-model-setting)上，直到您也设置 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)。如果该默认值是您打算限制的模型，也设置 `enforceAvailableModels`，或[阻止该模型](#block-specific-models-or-versions)。

309 316

310空的 `availableModels` 数组永远不会启用默认模型强制执行：使用 `availableModels: []`，命名的模型选择被阻止，但帐户类型的默认模型无论 `enforceAvailableModels` 如何都保持可用。317使用 `availableModels: []`，命名的模型选择被阻止，`enforceAvailableModels` 无效。

311 318

312<h3 id="enforce-the-allowlist-for-the-default-model">319<h3 id="enforce-the-allowlist-for-the-default-model">

313 为默认模型强制执行允许列表320 为默认模型强制执行允许列表

314</h3>321</h3>

315 322

316在托管设置中将 `enforceAvailableModels: true` 与非空的 `availableModels` 一起设置，以将允许列表扩展到默认选项。这需要 Claude Code v2.1.175 或更高版本。323在托管设置中将 `enforceAvailableModels: true` 与非空 `availableModels` 一起设置，以将允许列表扩展到默认选项。这需要 Claude Code v2.1.175 或更高版本。

317 324

318```json theme={null}325```json theme={null}

319{326{

322}329}

323```330```

324 331

325默认选项解析为帐户类型默认值，或当管理员设置了一个时解析为[组织默认模型](#organization-default-model)。当该模型不在允许列表中时，默认选项改为解析为命名允许的、可用模型的第一个 `availableModels` 条目，`/model` 选择器的默认行显示该模型。这适用于到达默认值的所有地方：会话启动、在 `/model` 中选择默认值、[后备模型链](#fallback-model-chains)中的 `"default"` 关键字以及排除选择被删除时使用的后备。332对于在其帐户上没有模型[记录](#setting-your-model)的成员，默认选项解析为帐户类型默认值，或当管理员设置了一个时解析为[组织默认模型](#organization-default-model)。当该模型不在允许列表中时，默认选项改为解析为命名允许的、可用模型的第一个 `availableModels` 条目，`/model` 选择器的默认行显示该模型。这适用于到达默认值的所有地方：会话启动、在 `/model` 中选择默认值、[回退模型链](#fallback-model-chains)中的 `"default"` 关键字，以及排除选择被删除时使用的回退。在成员帐户上记录的模型也针对 `availableModels` 进行检查；[设置您的模型](#setting-your-model)描述了默认选项如何处理它。

326 333

327`enforceAvailableModels` 仅在 `availableModels` 非空时重新映射默认选项。使用 `availableModels: []`，帐户类型的默认模型保持可用，因此设置不能将用户锁定在每个模型之外。当 `availableModels` 非空但没有条目解析为允许的和可用的模型时，强制执行被跳过，默认解析为帐户类型默认值，仅在 `--debug` 下可见警告。在列表中保留至少一个保证可用的条目以避免这种情况。334`enforceAvailableModels` 仅当 `availableModels` 非空时才重新映射默认选项。当 `availableModels` 非空但没有条目解析为允许的、可用的模型时，强制执行被跳过，并显示仅在 `--debug` 下可见的警告。在列表中保留至少一个保证可用的条目以避免这种情况。

328 335

329在您交付的最高排名托管源中部署两个密钥。默认情况下，Claude Code 仅读取该源，因此放在托管设置文件中的对在管理控制台交付任何设置时被忽略；在[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)中的选择加入合并下，Claude Code 仍然忽略来自排名低于设置 `availableModels` 的源的 `modelOverrides` 映射。336在您交付的最高排名的托管源中一起部署两个键。默认情况下，Claude Code 仅读取该源，因此放在托管设置文件中的对在管理控制台交付任何设置时被忽略；在[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)中的选择加入合并下，Claude Code 仍然忽略来自排名低于设置 `availableModels` 的源的 `modelOverrides` 映射。

330 337

331<h3 id="control-the-model-users-run-on">338<h3 id="control-the-model-users-run-on">

332 控制用户运行的模型339 控制用户运行的模型

333</h3>340</h3>

334 341

335`model` 设置是初始选择，不是强制执行。它设置会话启动时哪个模型处于活动状态，但用户仍然可以打开 `/model` 并选择默认值，无论 `model` 设置为什么，默认值都解析为系统的[运行时默认](#default-model-setting)，除非 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 重定向它。342`model` 设置是初始选择，不是强制执行。它设置会话启动时哪个模型处于活动状态，但用户仍然可以打开 `/model` 并选择默认值，该值解析为系统的[运行时默认](#default-model-setting)，无论 `model` 设置为什么，除非 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 或[阻止特定版本的键](#block-specific-models-or-versions)适用于它。

336 343

337要完全控制模型体验，请组合这些设置：344要完全控制模型体验，请组合这些设置：

338 345

339* **`availableModels`**：限制用户可以切换到的命名模型346* **`availableModels`**：限制用户可以切换到的命名模型

340* **`enforceAvailableModels`**：将 `availableModels` 允许列表扩展到默认选项，因此默认值不能解析到列表外的模型347* **`enforceAvailableModels`**：将 `availableModels` 允许列表扩展到默认选项，因此默认值无法解析到列表外的模型

341* **`model`**：设置会话启动时的初始模型选择348* **`deniedModels`** 和 **`availableModelsMatch`**：[阻止特定版本](#block-specific-models-or-versions)，`availableModels` 条目会允许这些版本

349* **`model`**：在会话启动时设置初始模型选择

342* **`ANTHROPIC_DEFAULT_SONNET_MODEL`** / **`ANTHROPIC_DEFAULT_OPUS_MODEL`** / **`ANTHROPIC_DEFAULT_HAIKU_MODEL`** / **`ANTHROPIC_DEFAULT_FABLE_MODEL`**：控制 `sonnet`、`opus`、`haiku` 和 `fable` 别名解析为什么，以及[帐户类型默认](#default-model-setting)使用哪个版本350* **`ANTHROPIC_DEFAULT_SONNET_MODEL`** / **`ANTHROPIC_DEFAULT_OPUS_MODEL`** / **`ANTHROPIC_DEFAULT_HAIKU_MODEL`** / **`ANTHROPIC_DEFAULT_FABLE_MODEL`**：控制 `sonnet`、`opus`、`haiku` 和 `fable` 别名解析为什么，以及[帐户类型默认](#default-model-setting)使用哪个版本

343 351

344此示例在 Sonnet 4.5 上启动用户，将选择器限制为 Sonnet 和 Haiku，并确保默认值解析为允许列表上的模型，而不是层级默认值：352此示例在 Sonnet 4.5 上启动用户，将选择器限制为 Sonnet 和 Haiku，并确保默认值解析为允许列表上的模型，而不是层级默认值：

354}362}

355```363```

356 364

357没有 `enforceAvailableModels` 或 `env` 块，在选择器中选择默认值的用户会获得[运行时默认](#default-model-setting)，而不是在 `model` 中固定的版本。这两个设置覆盖不同的范围：`enforceAvailableModels` 使默认值遵守允许列表，而 `env` 块固定允许的别名（如 `sonnet`）解析为哪个版本。当限制模型系列足够时单独使用 `enforceAvailableModels`；当您还需要固定特定版本时添加 `env` 块。365没有 `enforceAvailableModels` 或 `env` 块，在选择器中选择默认值的用户获得[运行时默认](#default-model-setting)，而不是 `model` 中固定的版本。这两个设置覆盖不同的范围：`enforceAvailableModels` 使默认值遵守允许列表，而 `env` 块固定允许的别名（如 `sonnet`）解析为哪个版本。当限制模型系列足够时单独使用 `enforceAvailableModels`；当您还需要固定特定版本时添加 `env` 块。

358 366

359<h3 id="merge-behavior">367<h3 id="merge-behavior">

360 合并行为368 合并行为

361</h3>369</h3>

362 370

363当 Claude Code 应用的托管设置定义 `availableModels` 时，该列表单独适用，除了[提供自己的主机平台](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence)：用户、项目或本地设置中的条目不能扩展它，Claude Code 也永远不会跨托管源合并 `availableModels`；[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明了哪个源的列表适用。否则，来自用户、项目和本地设置的列表像其他数组设置一样[连接和去重](/docs/zh-CN/settings#settings-precedence)。在 Claude Code v2.1.175 之前，来自较低优先级范围的条目合并到托管列表中，而不是被它替换。371当 Claude Code 应用的托管设置定义 `availableModels` 时，该列表单独适用，除了[提供自己的主机平台](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence)：用户、项目或本地设置中的条目无法扩展它，Claude Code 也永远不会跨托管源合并 `availableModels`；[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明了哪个源的列表适用。否则，来自用户、项目和本地设置的列表像其他数组设置一样[连接和去重](/docs/zh-CN/settings#settings-precedence)。在 Claude Code v2.1.175 之前，来自较低优先级范围的条目合并到托管列表中，而不是被它替换。

364 372

365在有效列表中，命名系列中特定模型的条目，无论是版本前缀还是完整模型 ID，都禁用该系列的通配符条目：`["sonnet", "claude-sonnet-4-5"]` 仅允许 Sonnet 4.5 版本，而不是每个 Sonnet 模型。373在有效列表中，命名系列中特定模型的条目（无论是版本前缀还是完整模型 ID）禁用该系列的通配符条目：`["sonnet", "claude-sonnet-4-5"]` 仅允许 Sonnet 4.5 版本，而不是每个 Sonnet 模型。

366 374

367<h3 id="mantle-model-ids">375<h3 id="mantle-model-ids">

368 Mantle 模型 ID376 Mantle 模型 ID

369</h3>377</h3>

370 378

371当启用[Amazon Bedrock Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)时，`availableModels` 中以 `anthropic.` 开头的条目被添加到 `/model` 选择器作为自定义选项，并路由到 Mantle 端点。这是对[为第三方部署固定模型](#pin-models-for-third-party-deployments)中描述的别名匹配的例外。该设置仍然将选择器限制为列出的条目，Mantle ID 嵌入系列名称，因此它计为特定条目并禁用该系列的通配符：在任何 Mantle ID 旁边，列出您想保持可选择的版本前缀或完整 ID。请参阅[合并行为](#merge-behavior)。379当启用 [Amazon Bedrock Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)时，`availableModels` 中以 `anthropic.` 开头的条目被添加到 `/model` 选择器作为自定义选项，并路由到 Mantle 端点。这是[为第三方部署固定模型](#pin-models-for-third-party-deployments)中描述的别名匹配的例外。该设置仍然将选择器限制为列出的条目，Mantle ID 嵌入系列名称，因此它计为特定条目并禁用该系列的通配符：在任何 Mantle ID 旁边，列出您想保持可选择的版本前缀或完整 ID。请参阅[合并行为](#merge-behavior)。

380

381<h3 id="block-specific-models-or-versions">

382 阻止特定模型或版本

383</h3>

384

385`availableModels` 条目（如 `claude-opus-5`）也允许扩展它的后续版本（如 Opus 5.5），一旦 Claude Code 支持它们。两个托管设置让您保留一个版本，两者都需要 Claude Code v2.1.283 或更高版本：

386

387* [`deniedModels`](/docs/zh-CN/settings-reference#deniedmodels)：列出要阻止的模型。即使 `availableModels` 允许，列出的模型也被阻止，该键也适用于根本没有允许列表的情况。没有条目阻止的版本保持允许

388* [`availableModelsMatch`](/docs/zh-CN/settings-reference#availablemodelsmatch)：将其设置为 `"exact"`，以便 `availableModels` 中的每个模型 ID 仅允许它命名的版本。列出的模型 ID 的较新版本然后保持被阻止，直到您将其添加到列表中

389

390较早的版本忽略两个键，因此也设置 [`requiredMinimumVersion`](/docs/zh-CN/settings-reference#requiredminimumversion) 以防止这些版本启动。

391

392此示例允许 Opus 和 Sonnet 模型，并在每种拼写中阻止 Opus 5.5，包括日期和提供商特定的 ID：

393

394```json theme={null}

395{

396 "availableModels": ["opus", "sonnet"],

397 "deniedModels": ["claude-opus-5-5"]

398}

399```

400

401被阻止的模型（无论 `deniedModels` 是否命名它或 `"exact"` 列表是否省略它）在[允许列表适用](#restrict-model-selection)的所有地方被视为被阻止的选择。它从 `/model` 选择器中隐藏，`/model <name>` 拒绝它。如果您用 `--model`、`ANTHROPIC_MODEL` 或 `model` 设置命名被阻止的模型 ID，Claude Code 在启动时删除它并解析默认选项。如果[钩子](/docs/zh-CN/hooks)或后台请求命名 `deniedModels` 阻止的模型（如代理钩子的 `model` 字段），该请求在会话的模型上运行。

402

403默认选项遵循两个键，无论您是否设置 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model)。如果您使用非空 `availableModels` 设置它，被阻止的默认值计为允许列表外的模型。否则，会解析为被阻止模型的默认选项按此顺序下降：

404

4051. 同一系列允许的最新版本

4062. 每个较低成本系列允许的最新模型：Sonnet，然后 Haiku

4073. 命名允许模型的第一个 `availableModels` 条目

408

409如果这些都不允许，在默认选项上启动的会话[拒绝启动](/docs/zh-CN/errors#managed-settings-block-the-default-model)，并显示命名要修复的键的错误。`"exact"` 列表仅当托管 `availableModels` 列表至少命名一个模型或系列时才影响默认选项。

410

411Claude Code 仅从托管设置读取两个键。如果您在用户、项目或本地设置中或使用 `--settings` 设置其中任何一个，Claude Code 会忽略它并显示警告。

372 412

373<h3 id="organization-model-restrictions">413<h3 id="organization-model-restrictions">

374 组织模型限制414 组织模型限制

376 416

377Claude Enterprise 计划上的组织管理员通过在 claude.ai 管理控制台中禁用单个模型来限制成员可以运行的模型。此限制在 Claude Code 进行身份验证时与帐户的权利一起交付，与设置中的任何 `availableModels` 列表分开，服务器在创建会话时独立强制执行相同的限制。需要 Claude Code v2.1.187 或更高版本。417Claude Enterprise 计划上的组织管理员通过在 claude.ai 管理控制台中禁用单个模型来限制成员可以运行的模型。此限制在 Claude Code 进行身份验证时与帐户的权利一起交付，与设置中的任何 `availableModels` 列表分开，服务器在创建会话时独立强制执行相同的限制。需要 Claude Code v2.1.187 或更高版本。

378 418

379当成员登录或使用自己的 API 密钥时，限制适用。组织范围的凭证，如组织服务密钥，不与用户绑定，因此限制不适用于它们。419当成员登录或使用自己的 API 密钥时，限制适用。组织范围的凭证（如组织服务密钥）不与用户绑定，因此限制不适用于它们。

380 420

381Claude Console 没有模型限制控制。没有 Claude Enterprise 计划的组织，包括其成员通过 Anthropic API 进行身份验证的组织，使用[托管设置](/docs/zh-CN/managed-settings)中的 [`availableModels`](#restrict-model-selection) 限制模型，添加 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 以覆盖默认选项。[表面覆盖](#surface-coverage)说明了每个表面如何接收和强制执行这些设置。421Claude Console 没有模型限制控制。没有 Claude Enterprise 计划的组织（包括其成员通过 Anthropic API 进行身份验证的组织）使用[托管设置](/docs/zh-CN/managed-settings)中的 [`availableModels`](#restrict-model-selection) 限制模型，添加 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 以覆盖默认选项。[表面覆盖](#surface-coverage)说明了每个表面如何接收和强制执行这些设置。

382 422

383受限模型从 `/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.` 并且会话保持其当前模型。423受限模型从 `/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.`，会话保持其当前模型。

384 424

385[模型系列别名](#restrict-model-selection)（如 `opus`）在组织允许时解析为其通常的模型。当组织限制该模型时，Claude Code 替换组织允许的该系列的最新版本，具有相同的替换通知。`/model <alias>` 仅在其系列的每个版本都被限制时被拒绝；使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 设置的别名在这种情况下仍在启动时被替换。在 v2.1.205 之前，系列别名基于其最新发布版本单独被替换或拒绝，即使允许较旧版本。425[模型系列别名](#restrict-model-selection)（如 `opus`）当组织允许它时解析为其通常的模型。当组织限制该模型时，Claude Code 替换组织允许的该系列的最新版本，显示相同的替换通知。`/model <alias>` 仅当其系列的每个版本都被限制时才被拒绝；用 `--model`、`ANTHROPIC_MODEL` 或 `model` 设置的别名在这种情况下仍在启动时被替换。在 v2.1.205 之前，系列别名基于其最新发布版本单独被替换或拒绝，即使允许较旧版本。

386 426

387限制适用于组织范围或按角色：427限制适用于组织范围或按角色：

388 428

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

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

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

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

393 433

394两个限制一起适用：仅当模型被 `availableModels` 允许且不被组织限制时，模型才可选择。组织限制仅到达 Anthropic API 和 [LLM 网关](/docs/zh-CN/llm-gateway)部署上的会话；在任何其他提供商上，改用 `availableModels`。434两个限制一起适用：仅当模型由 `availableModels` 允许且不受组织限制时，模型才可选择。组织限制仅到达 Anthropic API 和[LLM 网关](/docs/zh-CN/llm-gateway)部署上的会话；在任何其他提供商上，改为使用 `availableModels`。

395 435

396<h2 id="organization-default-model">436<h2 id="organization-default-model">

397 组织默认模型437 组织默认模型

417 457

418组织默认值在被采用之前会通过这些限制检查：458组织默认值在被采用之前会通过这些限制检查：

419 459

420* [`availableModels`](#restrict-model-selection) 本身不适用于组织默认值，因此允许列表外的组织默认值仍然适用。当同时设置了 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 时，允许列表外的组织默认值会被重新映射到第一个允许列表条目，就像任何其他默认值一样460* 使用默认前缀匹配时，[`availableModels`](#restrict-model-selection) 本身不适用于组织默认值，因此允许列表外的组织默认值仍然适用。当同时设置了 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 时，允许列表外的组织默认值会被重新映射到第一个允许列表条目

421* [组织模型限制](#organization-model-restrictions)拒绝的组织默认值会被替换为其系列中最新的允许模型，或当该系列的每个版本都被限制时被替换为成本较低的系列461* [组织模型限制](#organization-model-restrictions)拒绝的组织默认值会被替换为其系列中最新的允许模型，或当该系列的每个版本都被限制时被替换为成本较低的系列

462* 对于 `deniedModels` 或 `"exact"` 列表阻止的组织默认值，请参阅[阻止特定模型或版本](#block-specific-models-or-versions)

422* 您的账户完全无法使用的组织默认值会被跳过，"默认"选项的解析方式与[没有组织默认值](#default-model-setting)时相同463* 您的账户完全无法使用的组织默认值会被跳过，"默认"选项的解析方式与[没有组织默认值](#default-model-setting)时相同

423 464

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

451 492

452在 v2.1.280 之前，`default` 在 Pro 和 Team Standard 上解析为 Sonnet 5，在 Max、Team Premium、Enterprise、Anthropic API、Claude Platform on AWS、Amazon Bedrock 和 Google Cloud's Agent Platform 上从 v2.1.219 开始解析为 Opus 5。在 v2.1.219 之前，`default` 在 Anthropic API、Max、Team Premium 和 Enterprise 按量付费上从 v2.1.154 开始解析为 Opus 4.8，在 Claude Platform on AWS、Amazon Bedrock 和 Google Cloud's Agent Platform 上从 v2.1.207 开始解析为 Opus 4.8。在 v2.1.207 之前，`default` 在 Claude Platform on AWS 上解析为 Opus 4.7，在 Amazon Bedrock 和 Google Cloud's Agent Platform 上解析为 Sonnet 4.5。493在 v2.1.280 之前，`default` 在 Pro 和 Team Standard 上解析为 Sonnet 5，在 Max、Team Premium、Enterprise、Anthropic API、Claude Platform on AWS、Amazon Bedrock 和 Google Cloud's Agent Platform 上从 v2.1.219 开始解析为 Opus 5。在 v2.1.219 之前，`default` 在 Anthropic API、Max、Team Premium 和 Enterprise 按量付费上从 v2.1.154 开始解析为 Opus 4.8，在 Claude Platform on AWS、Amazon Bedrock 和 Google Cloud's Agent Platform 上从 v2.1.207 开始解析为 Opus 4.8。在 v2.1.207 之前，`default` 在 Claude Platform on AWS 上解析为 Opus 4.7，在 Amazon Bedrock 和 Google Cloud's Agent Platform 上解析为 Sonnet 4.5。

453 494

454当管理员设置了[组织默认模型](#organization-default-model)时，`default` 会解析为该模型，而不是上面的账户类型默认值。需要 Claude Code v2.1.196 或更高版本。`default` 也可以解析为您使用 [`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions) 设置的模型，具体条件见其部分说明。495当管理员设置了[组织默认模型](#organization-default-model)时，`default` 会解析为该模型，而不是上面的账户类型默认值。需要 Claude Code v2.1.196 或更高版本。`default` 也可以解析为您使用 [`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions) 设置的模型，具体条件见其部分说明，或解析为[记录在您账户上的](#setting-your-model)模型。

455 496

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

457 498

458Fable 模型在任何计划或提供商上都不是账户类型默认值。使用 `/model` 选择一个会将其保存为用户设置中的选定模型，以便后续会话从它开始。关于 Claude Code v2.1.257 对保存的 Fable 5 选择所做的一次性更改，请参阅[使用 Fable](#work-with-fable)。499Fable 模型在任何计划或提供商上都不是账户类型默认值。使用 `/model` 选择一个会将其保存为用户设置中的选定模型，以便后续会话从它开始。关于 Claude Code v2.1.257 对保存的 Fable 5 选择所做的一次性更改，请参阅[使用 Fable](#work-with-fable)。

459 500

513 自动模型回退554 自动模型回退

514</h3>555</h3>

515 556

516本部分涵盖来自 Fable 模型、Opus 5.5 和 Opus 5 的基于内容的回退。关于模型过载或不可用时的基于可用性的回退，请参阅[回退模型链](#fallback-model-chains)。557本部分涵盖来自 Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 的基于内容的回退。关于模型过载或不可用时的基于可用性的回退，请参阅[回退模型链](#fallback-model-chains)。

517 558

518Fable 模型、Opus 5.5 和 Opus 5 运行安全分类器，最常标记网络安全和生物学内容。当分类器标记请求且标记的类别有回退模型时，Claude Code 在该模型上重新运行请求并在记录中显示通知。对于这两个类别，回退模型取决于哪个模型拒绝：559Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 运行安全分类器，最常标记网络安全和生物学内容。当分类器标记请求且标记的类别有回退模型时，Claude Code 在该模型上重新运行请求并在记录中显示通知。对于这两个类别，回退模型取决于哪个模型拒绝：

519 560

520* **Fable 5.1、Fable 5 和 Opus 5.5**：生物学标记的请求在 Opus 5 上重新运行，网络安全标记的请求在 Opus 4.8 上重新运行。561* **Fable 5.1、Fable 5 和 Opus 5.5**：生物学标记的请求在 Opus 5 上重新运行，网络安全标记的请求在 Opus 4.8 上重新运行。

562* **Sonnet 5.5**：网络安全标记的请求在 Sonnet 5 上重新运行。生物学标记的请求以拒绝结束，因为 Sonnet 5.5 没有生物学回退模型。

521* **Opus 5**：网络安全标记的请求在 Opus 4.8 上重新运行。生物学标记的请求以拒绝结束，因为 Opus 5 运行自己的生物学分类器，没有回退模型。563* **Opus 5**：网络安全标记的请求在 Opus 4.8 上重新运行。生物学标记的请求以拒绝结束，因为 Opus 5 运行自己的生物学分类器，没有回退模型。

522 564

523在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，Claude Code 通过您的部署解析这些目标，如果您设置了 `ANTHROPIC_DEFAULT_OPUS_MODEL`，具有回退的类别会在固定模型上重新运行；请参阅[在 Bedrock、Agent Platform 和 Foundry 上启用回退](#enable-fallback-on-bedrock-agent-platform-and-foundry)。565在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，Claude Code 通过您的部署的模型 ID 解析这些目标。请参阅[在 Bedrock、Agent Platform 和 Foundry 上启用回退](#enable-fallback-on-bedrock-agent-platform-and-foundry)。

524 566

525回退后，会话继续在回退模型上。要返回到您的原始模型，运行 [`/model`](#setting-your-model)。567回退后，会话继续在回退模型上。要返回到您的原始模型，运行 [`/model`](#setting-your-model)。

526 568

544 586

545某些情况的行为不同：587某些情况的行为不同：

546 588

547* 当标记的类别没有回退模型时，例如 Opus 5 上的生物学标记，Claude Code 不显示提示，请求以拒绝结束。589* 当标记的类别没有回退模型时，例如 Opus 5 或 Sonnet 5.5 上的生物学标记，Claude Code 不显示提示，请求以拒绝结束。

548* 如果两个模型都标记相同的请求，您可以编辑提示并重试，或启动新会话。590* 如果两个模型都标记相同的请求，您可以编辑提示并重试，或启动新会话。

549* 在移动应用上的[云会话](/docs/zh-CN/claude-code-on-the-web)中，不支持编辑和重试。切换模型，或从桌面浏览器或桌面应用继续会话。591* 在移动应用上的[云会话](/docs/zh-CN/claude-code-on-the-web)中，不支持编辑和重试。切换模型，或从桌面浏览器或桌面应用继续会话。

550* 在[非交互模式](/docs/zh-CN/cli-reference#cli-flags)和无法显示提示的 SDK 集成中，标记的请求以拒绝结束轮次。592* 在[非交互模式](/docs/zh-CN/cli-reference#cli-flags)和无法显示提示的 SDK 集成中，标记的请求以拒绝结束轮次。

556 598

557在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上，模型 ID 是提供商特定的，因此自动回退仅在 Claude Code 可以识别两个涉及的模型时运行：599在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上，模型 ID 是提供商特定的，因此自动回退仅在 Claude Code 可以识别两个涉及的模型时运行：

558 600

559* Claude Code 必须将当前模型识别为回退源。当模型 ID 包含 `claude-fable-5`、匹配 `ANTHROPIC_DEFAULT_FABLE_MODEL` 的值或使用 [`modelOverrides`](#override-model-ids-per-version) 映射时，Fable 5.1 和 Fable 5 被识别。Opus 5.5 和 Opus 5 通过其提供商模型 ID 或 [`modelOverrides`](#override-model-ids-per-version) 映射被识别。601* Claude Code 必须将当前模型识别为回退源。当模型 ID 包含 `claude-fable-5`、匹配 `ANTHROPIC_DEFAULT_FABLE_MODEL` 的值或使用 [`modelOverrides`](#override-model-ids-per-version) 映射时，Fable 5.1 和 Fable 5 被识别。Opus 5.5、Sonnet 5.5 和 Opus 5 通过其提供商模型 ID 或 [`modelOverrides`](#override-model-ids-per-version) 映射被识别。

560* 回退模型必须在您的部署中解析。如果您设置了 `ANTHROPIC_DEFAULT_OPUS_MODEL`，标记的请求会在该模型上为每个具有回退的类别重新运行；Opus 5 上的生物学标记仍以拒绝结束。如果您没有设置它，网络安全标记的请求会在提供商模型列表中的 Opus 4.8 条目上重新运行，来自 Fable 模型或 Opus 5.5 的生物学标记请求会在 Opus 5 条目上重新运行。602* 一个 Opus 目标必须在您的部署中解析，无论哪个模型拒绝：设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`，或在提供商的模型列表中保留一个 Opus 4.8 条目。没有一个，回退对每个源模型都保持关闭，包括 Sonnet 5.5，标记的请求以拒绝结束。

603* 标记的类别的回退模型必须在您的部署中解析。从 Fable 模型、Opus 5.5 或 Opus 5，如果您设置了 `ANTHROPIC_DEFAULT_OPUS_MODEL`，标记的请求会在该模型上为每个具有回退的类别重新运行；Opus 5 上的生物学标记仍以拒绝结束。如果您没有设置它，网络安全标记的请求会在提供商模型列表中的 Opus 4.8 条目上重新运行，来自 Fable 模型或 Opus 5.5 的生物学标记请求会在 Opus 5 条目上重新运行。从 Sonnet 5.5，网络安全标记的请求会在您在 `ANTHROPIC_DEFAULT_SONNET_MODEL` 中设置的模型上重新运行，或在提供商模型列表中的 Sonnet 5 条目上（如果您没有设置它）。

604

605如果任一模型无法识别，Claude Code 不会自动切换。标记的请求以拒绝消息结束，您可以使用 [`/model`](#setting-your-model) 切换模型并重试。要使两个模型都可识别，为您的源模型设置固定值：

561 606

562如果任一模型无法识别，Claude Code 不会自动切换。标记的请求以拒绝消息结束，您可以使用 [`/model`](#setting-your-model) 切换模型并重试。将 `ANTHROPIC_DEFAULT_FABLE_MODEL` 设置为您的 Fable 模型 ID 可启用 Fable 识别。将 `ANTHROPIC_DEFAULT_OPUS_MODEL` 设置为 Opus 模型 ID 为标记的类别提供回退目标，除非固定值命名 Opus 系列外的模型或拒绝的模型；然后 Claude Code 不会切换，拒绝成立。607* **Fable 模型**：将 `ANTHROPIC_DEFAULT_FABLE_MODEL` 设置为您的 Fable 模型 ID，以便 Claude Code 将其识别为回退源。

608* **每个源模型**：将 `ANTHROPIC_DEFAULT_OPUS_MODEL` 设置为 Opus 模型 ID 以打开回退并为标记的类别提供目标。命名 Opus 系列外的模型或拒绝的模型的固定值会使拒绝成立。

609* **Sonnet 5.5**：除了 Opus 固定值外，设置 `ANTHROPIC_DEFAULT_SONNET_MODEL` 或在提供商的模型列表中保留 Sonnet 5 条目以提供请求重新运行的模型。命名 Sonnet 系列外的模型或 Sonnet 5.5 本身的 Sonnet 固定值会使拒绝成立。

563 610

564<h4 id="security-research-and-biology-workloads">611<h4 id="security-research-and-biology-workloads">

565 安全研究和生物学工作负载612 安全研究和生物学工作负载

566</h4>613</h4>

567 614

568进攻性安全或生物学中的工作负载，包括渗透测试、Capture the Flag (CTF) 练习和生物学相邻代码库，经常触发回退，通常在第一个请求上。对于 Fable 5.1、Fable 5 或 Opus 5.5 上的实质性生物学工作，Claude Code 在第一个标记的请求处将会话移动到 Opus 5，后来的生物学标记请求在那里以拒绝结束，因为 Opus 5 没有生物学回退。在 Opus 5 上，您从第一个标记的请求获得这些拒绝。615进攻性安全或生物学中的工作负载，包括渗透测试、Capture the Flag (CTF) 练习和生物学相邻代码库，经常触发回退，通常在第一个请求上。对于 Fable 5.1、Fable 5 或 Opus 5.5 上的实质性生物学工作，Claude Code 在第一个标记的请求处将会话移动到 Opus 5，后来的生物学标记请求在那里以拒绝结束，因为 Opus 5 没有生物学回退。在 Opus 5 和 Sonnet 5.5 上，您从第一个标记的请求获得这些拒绝。

569 616

570这是这些域的预期路由，不是账户标记。如果您的组织需要 Fable 级别的能力来完成这项工作，请向您的 Anthropic 账户团队询问受信任的访问计划。617这是这些域的预期路由，不是账户标记。如果您的组织需要 Fable 级别的能力来完成这项工作，请向您的 Anthropic 账户团队询问受信任的访问计划。

571 618

580| 模型 | 级别 |627| 模型 | 级别 |

581| :- | :- |628| :- | :- |

585 632

586如果您设置活动模型不支持的级别，Claude Code 会回退到该模型支持的最高级别或以下。例如，`xhigh` 在 Opus 4.6 上运行为 `high`。您的组织或您自己的设置也可以限制模型提供的级别；请参阅[组织努力限制](#organization-effort-limits)。633如果您设置活动模型不支持的级别，Claude Code 会回退到该模型支持的最高级别或以下。例如，`xhigh` 在 Opus 4.6 上运行为 `high`。您的组织或您自己的设置也可以限制模型提供的级别；请参阅[组织努力限制](#organization-effort-limits)。

587 634

588关闭 [`ultracode`](/docs/zh-CN/settings-reference#ultracode) 设置时，Claude Code 按此顺序解析会话的努力级别，采用首先适用的：635Claude Code 按此顺序解析会话的努力级别，采用首先适用的：

589 636

5901. 明确选择：[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars#variables) 环境变量、使用 `--effort` 启动或会话中的 `/effort`（[非交互式 `/effort` 的效果更窄](#non-interactive-effort)）6371. 明确选择：[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars#variables) 环境变量、使用 `--effort` 启动或会话中的 `/effort`（[非交互式 `/effort` 的效果更窄](#non-interactive-effort)）

5912. 您的设置：您为模型保存的级别或 [`effortLevel`](/docs/zh-CN/settings-reference#effortlevel) 键，在 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 中说明它们之间和跨设置文件的优先级6382. 您的设置：您为模型保存的级别或 [`effortLevel`](/docs/zh-CN/settings-reference#effortlevel) 键，在 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 中说明它们之间和跨设置文件的优先级

5923. 模型的默认努力：在支持努力的每个模型上为 `high`，除了 Opus 5.5 默认为 `medium`、Opus 4.7 默认为 `xhigh`，当您的组织为其[组织默认模型](#organization-default-model)设置默认努力级别时，当您运行该模型时该级别是默认值6393. 模型的默认努力：在支持努力的每个模型上为 `high`，除了 Opus 5.5 和 Sonnet 5.5 默认为 `medium`、Opus 4.7 默认为 `xhigh`，当您的组织为其[组织默认模型](#organization-default-model)设置默认努力级别时，当您运行该模型时该级别是默认值

593 640

594Opus 5.5 从 `medium` 开始，除非上面的源之一为其设置级别，您的用户设置文件中的顶级 `effortLevel` 不计入 Opus 5.5。该键是较旧的形式 `/effort` 在 Claude Code 按模型保存级别之前写入的：它继续在它之前应用的地方应用，在 Opus 5、Fable 5.1 和更早的模型上，而 Opus 5.5 和在它之后发布的模型从它们自己的默认开始，直到您使用 `/effort` 或 `/model` 选择器为它们选择级别。项目、本地或托管设置中的顶级 `effortLevel`，或使用 `--settings` 传递的，适用于每个模型。641Opus 5.5 从 `medium` 开始，除非上面的源之一为其设置级别，您的用户设置文件中的顶级 `effortLevel` 不计入 Opus 5.5。该键是较旧的形式 `/effort` 在 Claude Code 按模型保存级别之前写入的：它继续在它之前应用的地方应用，在 Opus 5、Fable 5.1 和更早的模型上，而 Opus 5.5 和在它之后发布的模型从它们自己的默认开始，直到您使用 `/effort` 或 `/model` 选择器为它们选择级别。项目、本地或托管设置中的顶级 `effortLevel`，或使用 `--settings` 传递的，适用于每个模型。

595 642

610 657

611当您在 [`-p` 运行](/docs/zh-CN/headless)中使用 `/effort` 设置级别时，Claude Code 仅将其应用于该会话，不将其保存为您的默认值。658当您在 [`-p` 运行](/docs/zh-CN/headless)中使用 `/effort` 设置级别时，Claude Code 仅将其应用于该会话，不将其保存为您的默认值。

612 659

613`/effort` 菜单也提供 `ultracode`。Ultracode 是 Claude Code 设置而不是模型努力级别：它向模型发送 `xhigh`，并另外让 Claude 为实质性任务编排[动态工作流](/docs/zh-CN/workflows)。关于它可以在哪里持久设置，请参阅 [`ultracode`](/docs/zh-CN/settings-reference#ultracode) 设置。660`/effort` 滑块也有一个 **Ultracode** 切换。Ultracode 是 Claude Code 设置而不是模型努力级别：启用它时，Claude 为实质性任务编排[动态工作流](/docs/zh-CN/workflows)，在会话运行的任何努力级别。关于它可以在哪里持久设置，请参阅 [`ultracode`](/docs/zh-CN/settings-reference#ultracode) 设置。

661

662使用 `/effort` 或 `ultracode` 设置打开或关闭 ultracode 会使努力级别保持不变。`--effort ultracode` 标志和 Agent SDK `effortLevel: "ultracode"` 值打开它，也将级别设置为 `xhigh`。在 `/effort` 滑块或 `/model` 选择器中选择级别会使 ultracode 保持原样。

614 663

615您可以通过以下任何方式打开 ultracode：664您可以通过以下任何方式打开 ultracode：

616 665

617* **`/effort`**：运行 `/effort ultracode`，或从菜单中选择它666* **`/effort`**：运行 `/effort ultracode` 为当前会话打开它或 `/effort ultracode off` 关闭它。在 `/effort` 滑块中，按 `Tab` 翻转 **Ultracode** 切换，然后 `Enter` 应用它

618* **`--effort` 标志**：使用 `claude --effort ultracode` 启动，这会在 `xhigh` 努力和 ultracode 打开的情况下启动会话667* **`--effort` 标志**：使用 `claude --effort ultracode` 启动，这会在 `xhigh` 努力和 ultracode 打开的情况下启动会话

619* **`ultracode` 设置**：在设置文件中、使用 `--settings` 或在 Agent SDK 控制请求中设置 [`"ultracode": true`](/docs/zh-CN/settings-reference#ultracode)。[`applyFlagSettings()`](/docs/zh-CN/agent-sdk/typescript#applyflagsettings) 请求也接受 `effortLevel: "ultracode"`668* **`ultracode` 设置**：在设置文件中、使用 `--settings` 或在 Agent SDK 控制请求中设置 [`"ultracode": true`](/docs/zh-CN/settings-reference#ultracode)。[`applyFlagSettings()`](/docs/zh-CN/agent-sdk/typescript#applyflagsettings) 请求也接受 `effortLevel: "ultracode"`，它打开它并将努力级别设置为 `xhigh`

620* **`/model` 选择器**：在选择模型时使用箭头键将努力滑块移动到 `ultracode`。Claude Code 为当前会话打开它，即使您将该模型保存为默认值669

670`/effort ultracode off` 形式、滑块切换和在 `xhigh` 以外的努力级别保持 ultracode 打开需要 Claude Code v2.1.284 或更高版本。在 v2.1.284 之前，打开 ultracode 将会话设置为 `xhigh` 努力，选择另一个级别关闭它，努力上限低于 `xhigh` 使其不可用。

621 671

622将 `ultracode` 传递给 `--effort` 标志或 Agent SDK `effortLevel` 值需要 Claude Code v2.1.203 或更高版本。在 v2.1.203 之前，`--effort ultracode` 打印 `Unknown --effort value 'ultracode'`，会话以默认努力开始。672将 `ultracode` 传递给 `--effort` 标志或 Agent SDK `effortLevel` 值需要 Claude Code v2.1.203 或更高版本。在 v2.1.203 之前，`--effort ultracode` 打印 `Unknown --effort value 'ultracode'`，会话以默认努力开始。

623 673

624持久化的 `effortLevel` 设置和 `CLAUDE_CODE_EFFORT_LEVEL` 环境变量不接受 `ultracode`。当 `CLAUDE_CODE_EFFORT_LEVEL` 设置为 `xhigh` 以外的级别时，请求以该级别运行，ultracode 的工作流编排保持不活跃。选择 ultracode 然后显示警告，环境变量覆盖会话的努力。674持久化的 `effortLevel` 设置和 `CLAUDE_CODE_EFFORT_LEVEL` 环境变量不接受 `ultracode`。如果 `CLAUDE_CODE_EFFORT_LEVEL` 或[努力上限](#organization-effort-limits)设置会话的级别，ultracode 在该级别保持打开。

625 675

626<span id="when-ultracode-is-available" />676<span id="when-ultracode-is-available" />

627 677

629 679

630* [工作流被关闭](/docs/zh-CN/workflows#turn-workflows-off)680* [工作流被关闭](/docs/zh-CN/workflows#turn-workflows-off)

631* 模型不支持 `xhigh` 努力681* 模型不支持 `xhigh` 努力

632* [努力上限](#organization-effort-limits)低于 `xhigh` 适用于模型

633 682

634在这些情况下，`--effort ultracode` 启动会话时 ultracode 关闭，努力级别为模型和任何上限允许的最高级别，最高为 `xhigh`。683在这些情况下，`--effort ultracode` 启动会话时 ultracode 关闭，努力级别为模型和任何上限允许的最高级别，最高为 `xhigh`。

635 684

641 690

642| 级别 | 何时使用 |691| 级别 | 何时使用 |

643| :- | :- |692| :- | :- |

644| `low` | 保留用于短的、范围有限的、延迟敏感的、不是智能敏感的任务 |693| `low` | 快速交换，您审查每个结果，例如头脑风暴、初稿或小改动如重命名 |

648| `max` | 可以改进要求任务的性能，但可能显示收益递减，容易过度思考。在广泛采用前测试 |697| `max` | 您想让 Claude 自己完成的难题，例如发现安全漏洞。`max` 可能显示收益递减，容易过度思考，所以在广泛采用前测试 |

699

700在 Opus 5.5 和 Fable 5.1 的测试中，Claude 在更高级别测试了更多边界情况，在回答前验证了更多工作。它也自己做了更多选择。在较低级别，Claude 更快地返回起点，适合您审查每个结果并指导下一步的工作。要查看在每个级别运行的相同任务，请阅读博客上的[使用 Claude Code：花费您的努力](https://claude.dev/blog/spending-your-effort/)。

650 701

651努力规模按模型校准，因此相同的级别名称在模型间不代表相同的基础值。702努力规模按模型校准，因此相同的级别名称在模型间不代表相同的基础值。

652 703

704Opus 5.5 [默认为 `medium`](#adjust-effort-level)，比 Opus 5 的默认值 `high` 低一个级别。在 Anthropic 的测试中，Opus 5.5 在 `medium` 时在编码和知识工作评估上匹配或超过 Opus 5 在 `high` 时的表现。在给定的级别，Opus 5.5 倾向于每轮比 Opus 5 思考更多。当您从 Opus 5 移动到 Opus 5.5 时，从 `medium` 开始，而不是携带您在 Opus 5 上使用的级别。要针对您自己的工作测试级别，请参阅 Opus 5.5 提示指南中的[校准努力](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#calibrate-effort)。

705

653<h4 id="use-ultrathink-for-one-off-deep-reasoning">706<h4 id="use-ultrathink-for-one-off-deep-reasoning">

654 使用 ultrathink 进行一次性深度推理707 使用 ultrathink 进行一次性深度推理

655</h4>708</h4>

682 735

683自适应推理使思考在每一步上可选，因此 Claude 可以更快地响应例行提示，并为受益于它的步骤保留更深入的思考。如果您想要 Claude 比当前级别产生的更频繁或更少地思考，您可以直接在您的提示或 `CLAUDE.md` 中说出来；模型在其努力设置内响应该指导。736自适应推理使思考在每一步上可选，因此 Claude 可以更快地响应例行提示，并为受益于它的步骤保留更深入的思考。如果您想要 Claude 比当前级别产生的更频繁或更少地思考，您可以直接在您的提示或 `CLAUDE.md` 中说出来；模型在其努力设置内响应该指导。

684 737

685Fable 模型、Sonnet 5 和 Opus 4.7 及更高版本始终使用自适应推理。固定思考预算模式和 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 不适用于它们。738Fable 模型、Sonnet 5 及更高版本和 Opus 4.7 及更高版本始终使用自适应推理。固定思考预算模式和 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 不适用于它们。

686 739

687在 Opus 4.6 和 Sonnet 4.6 上，您可以设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 以恢复到由 `MAX_THINKING_TOKENS` 控制的先前固定思考预算。请参阅[环境变量](/docs/zh-CN/env-vars)。740在 Opus 4.6 和 Sonnet 4.6 上，您可以设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 以恢复到由 `MAX_THINKING_TOKENS` 控制的先前固定思考预算。请参阅[环境变量](/docs/zh-CN/env-vars)。

688 741

696| :- | :- |749| :- | :- |

699| 通过环境变量禁用 | 设置 [`MAX_THINKING_TOKENS=0`](/docs/zh-CN/env-vars)，这在 Anthropic API 上关闭思考，除了 Opus 5.5 和 Fable 模型。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，Claude Code 改为省略 `thinking` 参数，自适应推理模型可能仍然思考。其他值仅适用于[固定思考预算](#adaptive-reasoning-and-fixed-thinking-budgets) |752| 通过环境变量禁用 | 设置 [`MAX_THINKING_TOKENS=0`](/docs/zh-CN/env-vars)，这在 Anthropic API 上关闭思考，除了 Opus 5.5、Sonnet 5.5 和 Fable 模型。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，Claude Code 改为省略 `thinking` 参数，自适应推理模型可能仍然思考。其他值仅适用于[固定思考预算](#adaptive-reasoning-and-fixed-thinking-budgets) |

700 753

701您不能在 Opus 5.5 或 Fable 模型上关闭思考。会话切换、`alwaysThinkingEnabled` 和 `MAX_THINKING_TOKENS=0` 在那里没有效果，模型根据努力级别按步骤决定思考多少。754您不能在 Opus 5.5、Sonnet 5.5 或 Fable 模型上关闭思考。会话切换、`alwaysThinkingEnabled` 和 `MAX_THINKING_TOKENS=0` 在那里没有效果，模型根据努力级别按步骤决定思考多少。

702 755

703Claude Code 默认折叠思考输出。按 `Ctrl+O` 切换详细模式并将推理视为灰色斜体文本。Anthropic API 上的交互式会话默认接收编辑的思考块，因此如果您想要完整摘要在展开时可用，在[设置](/docs/zh-CN/settings)中设置 `showThinkingSummaries: true`。您需要为所有生成的思考令牌付费，即使折叠或编辑。756Claude Code 默认折叠思考输出。按 `Ctrl+O` 切换详细模式并将推理视为灰色斜体文本。Anthropic API 上的交互式会话默认接收编辑的思考块，因此如果您想要完整摘要在展开时可用，在[设置](/docs/zh-CN/settings)中设置 `showThinkingSummaries: true`。您需要为所有生成的思考令牌付费，即使折叠或编辑。

704 757

758<a id="extended-context-with-1m" />

759

705<h3 id="extended-context">760<h3 id="extended-context">

706 扩展上下文761 扩展上下文

707</h3>762</h3>

708 763

709Fable 5.1、Fable 5、Sonnet 5、Opus 4.6 及更高版本和 Sonnet 4.6 支持[100 万令牌上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)，用于具有大型代码库的长会话。764Fable 5.1、Fable 5、Sonnet 5 及更高版本、Opus 4.6 及更高版本和 Sonnet 4.6 支持[100 万令牌上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)，用于具有大型代码库的长会话。

710 765

711在 Anthropic API 上，Fable 5.1、Fable 5、Sonnet 5 和 Opus 4.7 及更高版本在每个计划上运行 1M 窗口，包括 Pro。您不需要为这些模型上的 1M 窗口选择 `[1m]` 变体或打开使用额度。Fable 使用本身可以在某些计划上计费到使用额度；请参阅[Fable 和使用额度](#fable-and-usage-credits)。766在 Anthropic API 上，Fable 5.1、Fable 5、Sonnet 5 及更高版本和 Opus 4.7 及更高版本在每个计划上运行 1M 窗口，包括 Pro。您不需要为这些模型上的 1M 窗口选择 `[1m]` 变体或打开使用额度。Fable 使用本身可以在某些计划上计费到使用额度；请参阅[Fable 和使用额度](#fable-and-usage-credits)。

712 767

713Opus 4.6 和 Sonnet 4.6 仅通过其 `[1m]` 变体达到 1M，对该变体的访问取决于您的计划。在 Max、Team 和 Enterprise 计划上，包括 Team Standard 和 Team Premium 席位，Opus 4.6 与 1M 上下文包含在您的订阅中。Sonnet 4.6 与 1M 上下文在每个订阅计划上都需要[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，包括 Max。768Opus 4.6 和 Sonnet 4.6 仅通过其 `[1m]` 变体达到 1M，对该变体的访问取决于您的计划。在 Max、Team 和 Enterprise 计划上，包括 Team Standard 和 Team Premium 席位，Opus 4.6 与 1M 上下文包含在您的订阅中。Sonnet 4.6 与 1M 上下文在每个订阅计划上都需要[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，包括 Max。

714 769

742/model claude-opus-4-8[1m]797/model claude-opus-4-8[1m]

743```798```

744 799

745<h4 id="sonnet-5-context-window">800<h4 id="sonnet-5-5-and-sonnet-5-context-window">

746 Sonnet 5 上下文窗口801 Sonnet 5.5 和 Sonnet 5 上下文窗口

747</h4>802</h4>

748 803

749在 Anthropic API 上，Sonnet 5 始终运行 1M 上下文窗口。没有 200K 变体，没有 `[1m]` 后缀可选择，任何计划上都不需要使用额度。会话在窗口填满前自动压缩，默认约 967K 令牌；设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/zh-CN/env-vars) 以选择不同的阈值。804在 Anthropic API 上，Sonnet 5.5 和 Sonnet 5 始终运行 1M 上下文窗口。没有 200K 变体，没有 `[1m]` 后缀可选择，任何计划上都不需要使用额度。会话在窗口填满前自动压缩，默认约 967K 令牌；设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/zh-CN/env-vars) 以选择不同的阈值。

750 805

751两个配置将窗口预算为 200K：806两个配置将窗口预算为 200K：

752 807

753* **LLM 网关**：当 `ANTHROPIC_BASE_URL` 指向[网关](/docs/zh-CN/llm-gateway)时，Claude Code 无法验证 1M 支持。要使用完整窗口，在模型选择器中选择 Sonnet 5 (1M context)，它映射到 `sonnet[1m]`。808* **LLM 网关**：当 `ANTHROPIC_BASE_URL` 指向[网关](/docs/zh-CN/llm-gateway)时，Claude Code 无法验证 1M 支持。要使用完整窗口，在模型选择器中选择 Sonnet 5.5 (1M context) 或 Sonnet 5 (1M context)，它映射到 `sonnet[1m]`，或运行 `/model claude-sonnet-5[1m]` 用于 Sonnet 5。

754* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**：将具有本地 1M 窗口的每个模型上的会话保持在 200K 窗口；请参阅[扩展上下文](#extended-context)了解保持如何被强制执行。对于需要限制上下文的部署很有用。809* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**：将具有本地 1M 窗口的每个模型上的会话保持在 200K 窗口；请参阅[扩展上下文](#extended-context)了解保持如何被强制执行。对于需要限制上下文的部署很有用。

755 810

756<h2 id="context-window-and-auto-compaction">811<h2 id="context-window-and-auto-compaction">

786* [云会话](/docs/zh-CN/claude-code-on-the-web)在对话接近模型限制时进行压缩841* [云会话](/docs/zh-CN/claude-code-on-the-web)在对话接近模型限制时进行压缩

787* Sonnet 4.6 和 Opus 4.6（不带[扩展上下文](#extended-context)）在 200K 边界处进行压缩，Opus 4.8 和更高版本在使用 200K 上下文窗口运行时也是如此，例如在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上842* Sonnet 4.6 和 Opus 4.6（不带[扩展上下文](#extended-context)）在 200K 边界处进行压缩，Opus 4.8 和更高版本在使用 200K 上下文窗口运行时也是如此，例如在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上

788* 当您设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-CN/env-vars) 时，具有原生 1M 窗口的模型（例如 Sonnet 5 和 Fable 模型）在 200K 边界处进行压缩843* 当您设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-CN/env-vars) 时，具有原生 1M 窗口的模型（例如 Sonnet 5 和 Fable 模型）在 200K 边界处进行压缩

789* 使用原生 1M 窗口运行的模型（例如 Sonnet 5、Fable 模型以及 Anthropic API 上的 Opus 4.7 及更高版本）在窗口填满之前进行压缩，默认情况下约为 967K 令牌。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，[为第三方部署固定模型](#pin-models-for-third-party-deployments)说明了哪些模型使用该窗口；对于将 Sonnet 5 预算为 200K 的配置，请参阅 [Sonnet 5 上下文窗口](#sonnet-5-context-window)844* 使用原生 1M 窗口运行的模型（例如 Sonnet 5、Fable 模型以及 Anthropic API 上的 Opus 4.7 及更高版本）在窗口填满之前进行压缩，默认情况下约为 967K 令牌。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，[为第三方部署固定模型](#pin-models-for-third-party-deployments)说明了哪些模型使用该窗口；对于将 Sonnet 5.5 和 Sonnet 5 预算为 200K 的配置，请参阅 [Sonnet 5.5 和 Sonnet 5 上下文窗口](#sonnet-5-5-and-sonnet-5-context-window)

790* 在 Claude Code 不识别的模型 ID（例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名）上的会话在 Claude Code 为该 ID 假设的上下文窗口处进行压缩；请参阅[为网关或自定义模型 ID 更正窗口](#correct-the-window-for-a-gateway-or-custom-model-id)845* 在 Claude Code 不识别的模型 ID（例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名）上的会话在 Claude Code 为该 ID 假设的上下文窗口处进行压缩；请参阅[为网关或自定义模型 ID 更正窗口](#correct-the-window-for-a-gateway-or-custom-model-id)

791 846

792<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">847<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">

862| `CLAUDE_CODE_SUBAGENT_MODEL` | [subagents](/docs/zh-CN/sub-agents#choose-a-model)、[agent team](/docs/zh-CN/agent-teams#specify-teammates-and-models) 队友和[工作流](/docs/zh-CN/workflows)代理的默认模型，这些代理没有以其他方式分配模型。接受别名（如 `haiku`）或完整模型名称。每次调用的模型或定义的 `model` 字段（包括 `inherit`）优先。要更改该设置，请设置 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model) |917| `CLAUDE_CODE_SUBAGENT_MODEL` | [subagents](/docs/zh-CN/sub-agents#choose-a-model)、[agent team](/docs/zh-CN/agent-teams#specify-teammates-and-models) 队友和[工作流](/docs/zh-CN/workflows)代理的默认模型，这些代理没有以其他方式分配模型。接受别名（如 `haiku`）或完整模型名称。每次调用的模型或定义的 `model` 字段（包括 `inherit`）优先。要更改该设置，请设置 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model) |

863 918

919在第三方提供商上，[自定义固定模型显示和功能](#customize-pinned-model-display-and-capabilities)描述了固定模型在 `/model` 选择器中的行显示的内容。

920

864注意：`ANTHROPIC_SMALL_FAST_MODEL` 已弃用，改为使用 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。921注意：`ANTHROPIC_SMALL_FAST_MODEL` 已弃用，改为使用 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。

865 922

866<h3 id="pin-models-for-third-party-deployments">923<h3 id="pin-models-for-third-party-deployments">

995| 环境变量 | 描述 |1052| 环境变量 | 描述 |

996| - | - |1053| - | - |

1002 1059

1003要为主对话和 subagents 分别选择缓存 TTL，请参阅[自己选择 TTL](/docs/zh-CN/prompt-caching#choose-the-ttl-yourself)。有关什么会触发缓存未命中，请参阅 [Claude Code 如何使用 prompt caching](/docs/zh-CN/prompt-caching)。1060要为主对话和 subagents 分别选择缓存 TTL，请参阅[自己选择 TTL](/docs/zh-CN/prompt-caching#choose-the-ttl-yourself)。有关什么会触发缓存未命中，请参阅 [Claude Code 如何使用 prompt caching](/docs/zh-CN/prompt-caching)。

1061

1062<h2 id="version-history">

1063 版本历史

1064</h2>

1065

1066此表列出了每个模型别名更改其解析模型的 Claude Code 版本，最新版本在前。

1067

1068| 版本 | 更改 |

1069| :- | :- |

1070| v2.1.284 | `sonnet` 在 Anthropic API 上解析为 Sonnet 5.5 |

1071| v2.1.280 | `opus` 在 Anthropic API、AWS 上的 Claude Platform、Amazon Bedrock 和 Google Cloud 的 Agent Platform 上解析为 Opus 5.5 |

1072| v2.1.257 | `fable` 解析为 Fable 5.1，Claude 应用网关会话中除外 |

1073| v2.1.219 | `opus` 在 Anthropic API、AWS 上的 Claude Platform、Amazon Bedrock 和 Agent Platform 上解析为 Opus 5 |

1074| v2.1.207 | `opus` 在 AWS 上的 Claude Platform、Amazon Bedrock 和 Agent Platform 上解析为 Opus 4.8 |

1075| v2.1.197 | `sonnet` 在 Anthropic API 上解析为 Sonnet 5 |

1076| v2.1.154 | `opus` 在 Anthropic API 上解析为 Opus 4.8 |

1077| 更早版本 | `opus` 在 AWS 上的 Claude Platform 上解析为 Opus 4.7，在 Amazon Bedrock 和 Agent Platform 上解析为 Opus 4.6。`fable` 在每个提供商上解析为 Fable 5 |

monitoring-usage.md +422 −373

Details

39 39

40要验证导出指标的设置，请检查您的后端是否有 `claude_code.session.count` 指标，Claude Code 在会话启动时会发出该指标。要验证仅日志的设置，请提交提示并检查 `claude_code.user_prompt` 事件。40要验证导出指标的设置，请检查您的后端是否有 `claude_code.session.count` 指标，Claude Code 在会话启动时会发出该指标。要验证仅日志的设置，请提交提示并检查 `claude_code.user_prompt` 事件。

41 41

42如果没有任何内容到达，请运行 `claude --debug` 并检查调试日志。Claude Code 将您配置的导出器的失败报告为 `[3P telemetry]` 错误，其中 3P 表示第三方。以 `[Anthropic telemetry]` 为前缀的行描述 [Anthropic 的单独操作遥测](/docs/zh-CN/data-usage#telemetry-services)，不表示您的设置存在问题。42如果没有任何内容到达，请使用 `claude --debug-file <path>` 启动 Claude Code 并检查它写入该路径的日志。Claude Code 将您配置的导出器的失败报告为 `[3P telemetry]` 错误，其中 3P 表示第三方。以 `[Anthropic telemetry]` 为前缀的行描述 [Anthropic 的单独操作遥测](/docs/zh-CN/data-usage#telemetry-services)，不表示您的设置存在问题。

43 43

44有关完整配置选项，请参阅 [OpenTelemetry 规范](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options)。44有关完整配置选项，请参阅 [OpenTelemetry 规范](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options)。

45 45

72 托管设置如何锁定 OTLP 目标72 托管设置如何锁定 OTLP 目标

73</h3>73</h3>

74 74

75当您在托管设置中设置 `OTEL_EXPORTER_OTLP_*` 变量时，Claude Code 会在启动时删除冲突的开发者设置变量，并记录一条警告，您可以通过 `claude --debug` 查看。它删除的内容取决于您设置的变量：75当您在托管设置中设置 `OTEL_EXPORTER_OTLP_*` 变量时，Claude Code 会在启动时删除冲突的开发者设置变量，并在调试日志中记录一条警告。它删除的内容取决于您设置的变量：

76 76

77* **端点**：当您设置 `OTEL_EXPORTER_OTLP_ENDPOINT` 时，Claude Code 会删除每个开发者设置的每信号端点。开发者无法将一个信号指向不同的收集器，因此您不需要在托管设置中也设置每信号端点变量。77* **端点**：当您设置 `OTEL_EXPORTER_OTLP_ENDPOINT` 时，Claude Code 会删除每个开发者设置的每信号端点。开发者无法将一个信号指向不同的收集器，因此您不需要在托管设置中也设置每信号端点变量。

78* **协议**：当您设置 `OTEL_EXPORTER_OTLP_PROTOCOL` 时，Claude Code 会删除每个开发者设置的每信号协议。78* **协议**：当您设置 `OTEL_EXPORTER_OTLP_PROTOCOL` 时，Claude Code 会删除每个开发者设置的每信号协议。

103 常见配置变量103 常见配置变量

104</h3>104</h3>

105 105

106这些变量为所有部署配置导出器、端点和导出行为。如果您设置了按信号的端点或协议变量，例如 `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`，Claude Code 会使用它而不是该信号的通用变量。如果您设置了按信号的标头变量，例如 `OTEL_EXPORTER_OTLP_METRICS_HEADERS`，Claude Code 会将其与该信号的通用 `OTEL_EXPORTER_OTLP_HEADERS` 合并。在具有托管设置的机器上，请参阅[托管设置如何锁定 OTLP 目标](#how-managed-settings-lock-the-otlp-destination)以了解 Claude Code 删除的内容。106这些变量为所有部署配置导出器、端点和导出行为。

107

108如果您设置了按信号的端点或协议变量，例如 `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`，Claude Code 会使用它而不是该信号的通用变量。如果您设置了按信号的标头变量，例如 `OTEL_EXPORTER_OTLP_METRICS_HEADERS`，Claude Code 会将其与该信号的通用 `OTEL_EXPORTER_OTLP_HEADERS` 合并。

109

110在具有托管设置的机器上，请参阅[托管设置如何锁定 OTLP 目标](#how-managed-settings-lock-the-otlp-destination)了解 Claude Code 删除的内容。

107 111

108| 环境变量 | 描述 | 示例值 |112| 环境变量 | 描述 | 示例值 |

109| - | - | - |113| - | - | - |

110| `CLAUDE_CODE_ENABLE_TELEMETRY` | 启用遥测收集（必需） | `1` |114| `CLAUDE_CODE_ENABLE_TELEMETRY` | 启用遥测收集（必需） | `1` |

123| `OTEL_LOGS_EXPORT_INTERVAL` | 日志导出间隔（毫秒）（默认值：5000） | `1000`、`10000` |127| `OTEL_LOGS_EXPORT_INTERVAL` | 日志导出间隔（毫秒）（默认值：5000） | `1000`、`10000` |

124| `OTEL_LOG_USER_PROMPTS` | 启用用户提示内容的日志记录（默认值：禁用） | `1` 启用 |128| `OTEL_LOG_USER_PROMPTS` | 启用用户提示内容的日志记录（默认值：禁用） | `1` 启用 |

125| `OTEL_LOG_ASSISTANT_RESPONSES` | 在 `assistant_response` 事件上启用助手响应文本的日志记录（默认值：禁用）。未设置时，回退到 `OTEL_LOG_USER_PROMPTS` 的值。需要 Claude Code v2.1.193 或更高版本 | `1` 启用，`0` 保持编辑 |129| `OTEL_LOG_ASSISTANT_RESPONSES` | 在 `assistant_response` 事件上启用助手响应文本的日志记录（默认值：禁用）。未设置时，回退到 `OTEL_LOG_USER_PROMPTS` 的值。需要 Claude Code v2.1.193 或更高版本 | `1` 启用，`0` 保持编辑 |

126| `OTEL_LOG_TOOL_DETAILS` | 启用工具事件和跟踪跨度属性中的工具参数和输入参数的日志记录：Bash 命令、MCP 服务器和工具名称、技能名称、用户编写的工作流名称和工具输入。还在 `user_prompt` 事件上启用自定义、插件和 MCP 命令名称（默认值：禁用）。对于 Claude Desktop 的内置服务器，在 Claude Desktop 拥有的会话中，即使关闭该标志，`mcp_server_name`/`mcp_tool_name` 也会在 `tool_decision`/`tool_result` 上发出。该异常需要 Claude Code v2.1.214 或更高版本 | `1` 启用 |130| `OTEL_LOG_TOOL_DETAILS` | 在工具事件和跟踪跨度属性中启用工具参数和输入参数的日志记录：Bash 命令、MCP 服务器和工具名称、技能名称、用户编写的工作流名称和工具输入。还在 `user_prompt` 事件上启用自定义、插件和 MCP 命令名称，以及在[成本和令牌计数器](#cost-counter)上启用真实代理、技能、插件和 MCP 服务器和工具名称（默认值：禁用）。对于 Claude Desktop 的内置服务器，在 Claude Desktop 拥有的会话中，即使关闭标志，`mcp_server_name`/`mcp_tool_name` 也会在 `tool_decision`/`tool_result` 上发出。该异常需要 Claude Code v2.1.214 或更高版本 | `1` 启用 |

127| `OTEL_LOG_TOOL_CONTENT` | 启用 [`tool.output` 跨度事件](#tool-output-span-event)中工具内容的日志记录（默认值：禁用）。跨度属性在[其自己的门控](#new-context-gates)下携带工具内容。需要[跟踪](#traces-beta)。内容在内容限制处截断（默认值：60 KB） | `1` 启用 |131| `OTEL_LOG_TOOL_CONTENT` | 在 [`tool.output` 跨度事件](#tool-output-span-event)中启用工具内容的日志记录（默认值：禁用）。跨度属性在[其自己的门](#new-context-gates)下携带工具内容。需要[跟踪](#traces-beta)。内容在内容限制处截断（默认值 60 KB） | `1` 启用 |

128| `OTEL_LOG_MANAGED_SETTINGS` | 将编辑的托管设置和编辑前设置的 SHA-256 摘要添加到[托管设置已解决](#managed-settings-resolved-event)事件（默认值：禁用）。项目或本地设置中的值不会将其打开。需要 Claude Code v2.1.274 或更高版本 | `1` 启用 |132| `OTEL_LOG_MANAGED_SETTINGS` | 将编辑的托管设置和编辑前设置的 SHA-256 摘要添加到[托管设置已解决](#managed-settings-resolved-event)事件（默认值：禁用）。项目或本地设置中的值不会将其打开。需要 Claude Code v2.1.274 或更高版本 | `1` 启用 |

129| `OTEL_LOG_RAW_API_BODIES` | 将完整的 Anthropic Messages API 请求和响应 JSON 作为 `api_request_body` / `api_response_body` 日志事件发出（默认值：禁用）。正文包括整个对话历史记录。启用此选项意味着同意 `OTEL_LOG_USER_PROMPTS`、`OTEL_LOG_TOOL_DETAILS` 和 `OTEL_LOG_TOOL_CONTENT` 会透露的所有内容 | `1` 表示在内容限制处截断的内联正文（默认值：60 KB），或 `file:<dir>` 表示磁盘上未截断的正文，事件中带有 `body_ref` 指针 |133| `OTEL_LOG_RAW_API_BODIES` | 将完整的 Anthropic Messages API 请求和响应 JSON 作为 `api_request_body` / `api_response_body` 日志事件发出（默认值：禁用）。正文包括整个对话历史记录。启用此选项意味着同意 `OTEL_LOG_USER_PROMPTS`、`OTEL_LOG_TOOL_DETAILS` 和 `OTEL_LOG_TOOL_CONTENT` 会揭示的所有内容 | `1` 表示在内容限制处截断的内联正文（默认值 60 KB），或 `file:<dir>` 表示磁盘上的未截断正文，事件中有 `body_ref` 指针 |

130| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 内容限制：内容承载属性（如模型响应、工具内容、系统提示和原始 API 正文）的最大长度，包括截断标记，以 UTF-16 代码单位为单位（默认值：61440，即 60 KB）。默认值针对将属性值上限设为 64 KB 的后端进行了调整；仅当您的后端接受更大的值时才提高它，或降低它以减少遥测量。当设置了 OpenTelemetry SDK 属性限制 `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` 或其日志记录和跨度变体之一时，Claude Code 会在该较小的值处截断，以便 `[TRUNCATED ...]` 标记保持在 SDK 限制内。需要 Claude Code v2.1.214 或更高版本 | `262144` |134| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 内容限制：内容承载属性（如模型响应、工具内容、系统提示和原始 API 正文）的最大长度，包括截断标记，以 UTF-16 代码单位为单位（默认值：61440，即 60 KB）。默认值针对将属性值上限设为 64 KB 的后端进行了调整；仅当您的后端接受更大的值时才提高它，或降低它以减少遥测量。当设置了 OpenTelemetry SDK 属性限制 `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` 或其日志记录和跨度变体之一时，Claude Code 在该较小的值处截断，以便 `[TRUNCATED ...]` 标记保持在 SDK 限制内。需要 Claude Code v2.1.214 或更高版本 | `262144` |

132| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新动态标头的间隔（默认值：1740000ms / 29 分钟） | `900000` |136| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新动态标头的间隔（默认值：1740000ms / 29 分钟） | `900000` |

133 137

134对于 `http/protobuf` 和 `http/json` 协议，Claude Code 使用 `Content-Length` 标头发送每个导出请求。在 v2.1.212 之前，从 v2.1.191 开始的 Claude Code 版本使用分块传输编码发送这些请求；Azure Monitor 和其他需要声明长度的端点以 `411 Length Required` 或 `400` 错误拒绝它们。138对于 `http/protobuf` 和 `http/json` 协议，Claude Code 使用 `Content-Length` 标头发送每个导出请求。在 v2.1.212 之前，v2.1.191 及更高版本的 Claude Code 版本使用分块传输编码发送这些请求；Azure Monitor 和其他需要声明长度的端点以 `411 Length Required` 或 `400` 错误拒绝它们。

135 139

136<h3 id="mtls-authentication">140<h3 id="mtls-authentication">

137 mTLS 身份验证141 mTLS 身份验证

142| 协议 | 客户端证书变量 | 信任收集器的 CA 使用 |146| 协议 | 客户端证书变量 | 信任收集器的 CA 使用 |

143| :- | :- | :- |147| :- | :- | :- |

144| `http/protobuf`、`http/json` | `CLAUDE_CODE_CLIENT_CERT`、`CLAUDE_CODE_CLIENT_KEY` 和可选的 `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`。请参阅[网络配置](/docs/zh-CN/network-config#mtls-authentication) | `NODE_EXTRA_CA_CERTS` |148| `http/protobuf`、`http/json` | `CLAUDE_CODE_CLIENT_CERT`、`CLAUDE_CODE_CLIENT_KEY` 和可选的 `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE`。请参阅[网络配置](/docs/zh-CN/network-config#mtls-authentication) | `NODE_EXTRA_CA_CERTS` |

145| `grpc` | `OTEL_EXPORTER_OTLP_CLIENT_KEY` 和 `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`，或按信号的变体，例如 `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` 以为每个信号使用不同的证书 | `OTEL_EXPORTER_OTLP_CERTIFICATE` |149| `grpc` | `OTEL_EXPORTER_OTLP_CLIENT_KEY` 和 `OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`，或按信号的变体，例如 `OTEL_EXPORTER_OTLP_METRICS_CLIENT_KEY` 以对每个信号使用不同的证书 | `OTEL_EXPORTER_OTLP_CERTIFICATE` |

146 150

147对于 `grpc`，OpenTelemetry SDK 直接读取标准 OTLP 变量，因此设置按信号指标变量的现有配置继续有效。在具有托管设置的机器上，Claude Code [可能在启动时删除开发人员设置的按信号凭证和端点](#how-managed-settings-lock-the-otlp-destination)。151对于 `grpc`，OpenTelemetry SDK 直接读取标准 OTLP 变量，因此设置按信号指标变量的现有配置继续有效。在具有托管设置的机器上，Claude Code [可能在启动时删除开发人员设置的按信号凭证和端点](#how-managed-settings-lock-the-otlp-destination)。

148 152

154 158

155| 环境变量 | 描述 | 默认值 | 禁用示例 |159| 环境变量 | 描述 | 默认值 | 禁用示例 |

156| - | - | - | - |160| - | - | - | - |

163 167

164较低的基数通常意味着更好的性能和更低的存储成本，但数据分析的粒度较低。168较低的基数通常意味着更好的性能和更低的存储成本，但分析的数据粒度较低。

165 169

166<h3 id="traces-beta">170<h3 id="traces-beta">

167 Traces（测试版）171 Traces（测试版）

181| `OTEL_TRACES_EXPORT_INTERVAL` | 跨度批量导出间隔（毫秒）（默认值：5000） | `1000`、`10000` |185| `OTEL_TRACES_EXPORT_INTERVAL` | 跨度批导出间隔（毫秒）（默认值：5000） | `1000`、`10000` |

182 186

183跨度默认编辑用户提示文本、工具输入详情和工具内容。设置 `OTEL_LOG_USER_PROMPTS=1`、`OTEL_LOG_TOOL_DETAILS=1` 和 `OTEL_LOG_TOOL_CONTENT=1` 以包含它们。187跨度默认编辑用户提示文本、工具输入详情和工具内容。设置 `OTEL_LOG_USER_PROMPTS=1`、`OTEL_LOG_TOOL_DETAILS=1` 和 `OTEL_LOG_TOOL_CONTENT=1` 以包含它们。

184 188

185当跟踪处于活动状态时，Bash 和 PowerShell 子进程会自动继承包含活动工具执行跨度的 W3C 跟踪上下文的 `TRACEPARENT` 环境变量。这允许任何读取 `TRACEPARENT` 的子进程在同一跟踪下将其自己的跨度作为父级，从而通过 Claude 运行的脚本和命令实现端到端分布式跟踪。189当跟踪处于活动状态时，Bash 和 PowerShell 子进程会自动继承包含活动工具执行跨度的 W3C 跟踪上下文的 `TRACEPARENT` 环境变量。这允许任何读取 `TRACEPARENT` 的子进程在同一跟踪下将其自己的跨度作为父级，通过 Claude 运行的脚本和命令启用端到端分布式跟踪。

186 190

187当跟踪处于活动状态且 Claude Code 直接连接到 Anthropic API 时，每个模型请求都携带设置为 `claude_code.llm_request` 跨度上下文的 W3C `traceparent` 标头，API 的 `traceresponse` 标头被记录为跨度链接。这些共同通过任何兼容的中介将 Claude Code 的客户端跨度连接到服务器端跟踪。出站 HTTP MCP 请求以相同的方式携带 `traceparent`。该标头不会发送给第三方提供商。191当跟踪处于活动状态且 Claude Code 直接连接到 Anthropic API 时，每个模型请求都携带设置为 `claude_code.llm_request` 跨度上下文的 W3C `traceparent` 标头，API 的 `traceresponse` 标头被记录为跨度链接。这些一起通过任何兼容的中介将 Claude Code 的客户端跨度连接到服务器端跟踪。出站 HTTP MCP 请求以相同方式携带 `traceparent`。标头不会发送给第三方提供商。

188 192

189默认情况下，模型和 HTTP MCP 请求上的 `traceparent` 标头仅在 `ANTHROPIC_BASE_URL` 未设置或指向 Anthropic API 时发送，因为某些代理拒绝无法识别的标头。子进程 `TRACEPARENT` 变量由相同的开关控制以保持一致性。如果您通过自定义 `ANTHROPIC_BASE_URL` 代理运行 Claude Code 并希望传播跟踪上下文，请设置 `CLAUDE_CODE_PROPAGATE_TRACEPARENT=1`。193默认情况下，模型和 HTTP MCP 请求上的 `traceparent` 标头仅在 `ANTHROPIC_BASE_URL` 未设置或指向 Anthropic API 时发送，因为某些代理拒绝无法识别的标头。子进程 `TRACEPARENT` 变量由相同的开关控制以保持一致性。如果您通过自定义 `ANTHROPIC_BASE_URL` 代理运行 Claude Code 并希望传播跟踪上下文，请设置 `CLAUDE_CODE_PROPAGATE_TRACEPARENT=1`。

190 194

191在 Agent SDK 和使用 `-p` 启动的非交互式会话中，Claude Code 还会在启动每个交互跨度时从其自己的环境中读取 `TRACEPARENT` 和 `TRACESTATE`。这允许嵌入过程将其活动的 W3C 跟踪上下文传递到子进程中，以便 Claude Code 的跨度显示为调用者分布式跟踪的子级。交互式会话忽略入站 `TRACEPARENT` 以避免意外继承来自 CI 或容器环境的环境值。195在 Agent SDK 和使用 `-p` 启动的非交互式会话中，Claude Code 还在启动每个交互跨度时从其自己的环境中读取 `TRACEPARENT` 和 `TRACESTATE`。这允许嵌入过程将其活动 W3C 跟踪上下文传递到子进程中，以便 Claude Code 的跨度显示为调用者分布式跟踪的子级。交互式会话忽略入站 `TRACEPARENT` 以避免意外继承来自 CI 或容器环境的环境值。

192 196

193入站跟踪上下文也适用于[事件](#events)。在设置了 `TRACEPARENT` 的 Agent SDK 和 `-p` 会话中，每个 OTLP 事件日志记录都携带 `trace_id` 和 `span_id` 值，将其加入您的应用程序跟踪，即使未配置跟踪导出器，您的日志记录后端也可以将事件与跟踪的其余部分关联起来。197入站跟踪上下文也适用于[事件](#events)。在设置了 `TRACEPARENT` 的 Agent SDK 和 `-p` 会话中，每个 OTLP 事件日志记录都携带 `trace_id` 和 `span_id` 值，将其加入您的应用程序跟踪，即使未配置跟踪导出器，您的日志后端也可以将事件与跟踪的其余部分关联。

194 198

195在交互处于活动状态时发出的记录携带交互跨度的 ID，即使 Claude Code 在跨度的异步上下文之外发出它，例如在权限提示回调中或对于在启动期间缓冲并稍后导出的记录。在没有活动交互跨度的情况下发出的记录直接携带入站 `TRACEPARENT` ID。在 v2.1.214 之前，在跨度的异步上下文之外发出的记录携带入站 `TRACEPARENT` ID 而不是跨度的 ID。在 v2.1.212 之前，在活动跨度之外发出的事件记录不携带 `trace_id` 或 `span_id`。199在交互处于活动状态时发出的记录携带交互跨度的 ID，即使 Claude Code 在跨度的异步上下文之外发出它，例如在权限提示回调中或对在启动期间缓冲并稍后导出的记录。在没有活动交互跨度的情况下发出的记录直接携带入站 `TRACEPARENT` ID。在 v2.1.214 之前，在跨度的异步上下文之外发出的记录携带入站 `TRACEPARENT` ID 而不是跨度的 ID。在 v2.1.212 之前，在活动跨度之外发出的事件记录不携带 `trace_id` 或 `span_id`。

196 200

197<h4 id="span-hierarchy">201<h4 id="span-hierarchy">

198 跨度层次结构202 跨度层次结构

212 216

213在 Agent SDK 和 `claude -p` 会话中，当在环境中设置 `TRACEPARENT` 时，`claude_code.interaction` 本身成为调用者跨度的子级。217在 Agent SDK 和 `claude -p` 会话中，当在环境中设置 `TRACEPARENT` 时，`claude_code.interaction` 本身成为调用者跨度的子级。

214 218

215当 `PreToolUse` 钩子[延迟工具调用](/docs/zh-CN/hooks#defer-a-tool-call-for-later)时，Claude Code 保存延迟它的转向的跟踪上下文。当您恢复会话并且工具重新运行时，工具的跨度加入该较早转向的跟踪，作为转向的 `claude_code.interaction` 跨度的子级。219当 `PreToolUse` 钩子[延迟工具调用](/docs/zh-CN/hooks#defer-a-tool-call-for-later)时，Claude Code 保存延迟它的转向的跟踪上下文。当您恢复会话并且工具重新运行时，工具的跨度加入该较早转向的跟踪作为转向的 `claude_code.interaction` 跨度的子级。

216 220

217<h4 id="span-attributes">221<h4 id="span-attributes">

218 跨度属性222 跨度属性

222 226

223**`claude_code.interaction`**227**`claude_code.interaction`**

224 228

225| 属性 | 描述 | 由以下控制 |229| 属性 | 描述 | 门控 |

226| - | - | - |230| - | - | - |

232 236

233**`claude_code.llm_request`**237**`claude_code.llm_request`**

234 238

235| 属性 | 描述 | 由以下控制 |239| 属性 | 描述 | 门控 |

236| - | - | - |240| - | - | - |

241| `query_source_safe` | `query_source` 的有界形式，无论是否启用详细的测试版跟踪都会发出，具有 `repl_main_thread` 或 `agent.builtin.general-purpose` 等值。`:` 变为 `.`，用户命名的代理显示为 `agent.custom`。需要 Claude Code v2.1.268 或更高版本 | |245| `query_source_safe` | `query_source` 的有界形式，无论是否启用详细测试版跟踪都会发出，具有 `repl_main_thread` 或 `agent.builtin.general-purpose` 等值。`:` 变为 `.`，用户命名的代理显示为 `agent.custom`。需要 Claude Code v2.1.268 或更高版本 | |

247| `effort` | [应用于请求的工作量级别](/docs/zh-CN/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。当 Claude Code 不发送工作量级别时不存在，例如在不支持工作量的模型上。需要 Claude Code v2.1.274 或更高版本 | |251| `effort` | 应用于请求的[努力级别](/docs/zh-CN/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。当 Claude Code 不发送努力级别时不存在，例如在不支持努力的模型上。需要 Claude Code v2.1.274 或更高版本 | |

269 273

270**`claude_code.tool`**274**`claude_code.tool`**

271 275

272| 属性 | 描述 | 由以下控制 |276| 属性 | 描述 | 门控 |

273| - | - | - |277| - | - | - |

275| `tool_name_safe` | `tool_name` 的形式，不携带任何用户选择的名称。内置工具名称逐字通过。MCP 工具名称显示为 `mcp_other`，除了与几个固定形状匹配的工具名称，例如名为 `browser_*` 的 `playwright` 工具，这些工具逐字通过。需要 Claude Code v2.1.268 或更高版本 | |279| `tool_name_safe` | `tool_name` 的形式，不携带任何用户选择的名称。内置工具名称逐字通过。MCP 工具名称显示为 `mcp_other`，除了与几个固定形状匹配的工具名称，例如名为 `browser_*` 的 `playwright` 工具，它们逐字通过。需要 Claude Code v2.1.268 或更高版本 | |

276| `bash_command_class` | 对于 Bash 工具：命令的第一个程序的类别，来自固定列表，例如 `vcs` 或 `package_manager`。`other` 表示列表外的程序，`unparsed` 表示无法解析该行。需要 Claude Code v2.1.268 或更高版本 | |280| `bash_command_class` | 对于 Bash 工具：命令的第一个程序的类别，来自固定列表，例如 `vcs` 或 `package_manager`。`other` 表示列表外的程序，`unparsed` 表示无法解析该行。需要 Claude Code v2.1.268 或更高版本 | |

284| `tool_use_id` | 此调用的模型 `tool_use` 块 id。与[tool\_result](#tool-result-event)和[tool\_decision](#tool-decision-event)事件以及钩子有效负载上的 `tool_use_id` 匹配，因此您可以将跨度加入这些记录 | |288| `tool_use_id` | 此调用的模型 `tool_use` 块 id。与[tool\_result](#tool-result-event)和[tool\_decision](#tool-decision-event)事件上的 `tool_use_id` 以及钩子有效负载中的匹配，因此您可以将跨度加入这些记录 | |

290 294

~~291<span id="tool-output-span-event" />**`tool.output` 跨度事件在 `claude_code.tool` 上**~~295<span id="tool-output-span-event" />**`claude_code.tool` 上的 `tool.output` 跨度事件**

292 296

293如果您设置 `OTEL_LOG_TOOL_CONTENT=1`，Read 和 Bash 调用可以在 `claude_code.tool` 跨度上记录 `tool.output` 跨度事件。Edit 和 Write 调用仅在您也设置 `OTEL_LOG_TOOL_DETAILS=1` 时才记录一个。该变量不限于这两个工具，因此请检查其[配置表中的行](#common-configuration-variables)以了解它在其他地方添加的参数。297如果您设置 `OTEL_LOG_TOOL_CONTENT=1`，Read 和 Bash 调用可以在 `claude_code.tool` 跨度上记录 `tool.output` 跨度事件。Edit 和 Write 调用仅在您也设置 `OTEL_LOG_TOOL_DETAILS=1` 时才记录一个。该变量不限于这两个工具，因此请检查其[配置表中的行](#common-configuration-variables)以了解它在其他地方添加的参数。

294 298

299MCP 工具、WebFetch 和 WebSearch 也记录此事件，在 Claude Code v2.1.283 或更高版本上。

300

295Claude Code 从工具调用的成功返回时写入此事件，因此引发错误的调用不记录任何内容，无论工具如何。在确实返回的调用中，它不为以下内容记录 `tool.output` 事件：301Claude Code 从工具调用的成功返回时写入此事件，因此引发错误的调用不记录任何内容，无论工具如何。在确实返回的调用中，它不为以下内容记录 `tool.output` 事件：

296 302

297* 对除 Read、Edit、Write 和 Bash 之外的任何工具的调用，包括 MCP 工具和 WebFetch303* 对除 Read、Edit、Write、Bash、WebFetch、WebSearch 和 MCP 工具之外的任何工具的调用

298* 返回除文件文本之外的任何内容的 Read，例如图像、PDF 或重新读取内容未更改的文件304* 返回除文件文本之外的任何内容的 Read，例如图像、PDF 或重新读取内容未更改的文件

299* Edit 或 Write 调用，除非您也设置 `OTEL_LOG_TOOL_DETAILS=1`305* Edit 或 Write 调用，除非您也设置 `OTEL_LOG_TOOL_DETAILS=1`

306* Claude Code 移到后台的 WebFetch 或 WebSearch 调用，因为您中断了转向以[立即发送您排队的消息](/docs/zh-CN/interactive-mode#when-claude-code-sends-what-you-queued)，而调用运行。Claude 稍后在工具跨度结束后收到该结果

300 307

301该事件携带这些属性，每个属性在内容限制处截断（默认值：60 KB）。`由以下控制` 命名属性在 `OTEL_LOG_TOOL_CONTENT=1` 之上需要的变量，对于 Edit 和 Write，该变量控制事件本身而不是属性。308该事件携带这些属性，每个都在内容限制处截断（默认值 60 KB）。`门控` 命名变量一个属性需要在 `OTEL_LOG_TOOL_CONTENT=1` 之上，对于 Edit 和 Write，该变量门控事件本身而不是属性。

302 309

303| 属性 | 描述 | 由以下控制 |310| 属性 | 描述 | 门控 |

304| - | - | - |311| - | - | - |

310 317

311父跨度的 `tool_name` 属性告诉您事件来自哪个工具。在内容限制处切割的属性伴随 `<attribute>_truncated` 和 `<attribute>_original_length`。318父跨度的 `tool_name` 属性告诉您事件来自哪个工具。在内容限制处切割的属性伴随 `<attribute>_truncated` 和 `<attribute>_original_length`。

312 319

313**`claude_code.tool.blocked_on_user`**320**`claude_code.tool.blocked_on_user`**

314 321

315| 属性 | 描述 | 由以下控制 |322| 属性 | 描述 | 门控 |

316| - | - | - |323| - | - | - |

320 327

321**`claude_code.tool.execution`**328**`claude_code.tool.execution`**

322 329

323| 属性 | 描述 | 由以下控制 |330| 属性 | 描述 | 门控 |

324| - | - | - |331| - | - | - |

330| `error_class` | 标识符形式的错误类别，字母、数字和下划线以外的字符替换为 `_`，例如 `Error_ENOENT` 或 `ShellError`。即使 `error` 携带完整消息，也携带类别。需要 Claude Code v2.1.268 或更高版本 | |337| `error_class` | 标识符形式的错误类别，字母、数字和下划线之外的字符被替换为 `_`，例如 `Error_ENOENT` 或 `ShellError`。即使 `error` 携带完整消息也携带类别。需要 Claude Code v2.1.268 或更高版本 | |

331 338

332**`claude_code.hook`**339**`claude_code.hook`**

333 340

334此跨度仅在启用详细的测试版跟踪时出现，这需要 `ENABLE_BETA_TRACING_DETAILED=1` 和 `BETA_TRACING_ENDPOINT`，这对也[改变您的日志和跟踪的去向](/docs/zh-CN/env-vars#variables)。在您的 shell、用户设置或托管设置中设置该对；两个变量都在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中被忽略。仅 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` 不会产生它。341此跨度仅在启用详细测试版跟踪时出现，这需要 `ENABLE_BETA_TRACING_DETAILED=1` 和 `BETA_TRACING_ENDPOINT`，一对也[改变日志和跟踪的去向](/docs/zh-CN/env-vars#variables)。在您的 shell、用户设置或托管设置中设置该对；两个变量都在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中被忽略。`CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` 单独不会产生它。

335 342

336在交互式 CLI 会话中，详细的测试版跟踪还需要您的组织被列入该功能的白名单。Agent SDK 和非交互式 `-p` 会话不需要白名单。343在交互式 CLI 会话中，详细测试版跟踪还需要您的组织被列入该功能的白名单。Agent SDK 和非交互式 `-p` 会话不需要白名单。

337 344

338| 属性 | 描述 | 由以下控制 |345| 属性 | 描述 | 门控 |

339| - | - | - |346| - | - | - |

349 356

350<span id="new-context-gates" />357<span id="new-context-gates" />

351 358

352<Note>359<Note>

353 其他内容承载属性，例如 `new_context`、`system_prompt_preview`、`user_system_prompt`、`tool_input` 和 `response.model_output`，仅在启用详细的测试版跟踪时发出。它们不是稳定跨度架构的一部分。360 其他内容承载属性，例如 `new_context`、`system_prompt_preview`、`user_system_prompt`、`tool_input` 和 `response.model_output`，仅在启用详细测试版跟踪时发出。它们不是稳定跨度架构的一部分。

354 361

355 `new_context` 上的门控取决于哪个跨度携带它，每个副本在内容限制处截断（默认值：60 KB）。在 `claude_code.tool` 跨度上，它携带该工具调用的结果，无论工具如何，并需要 `OTEL_LOG_TOOL_CONTENT=1`。在 `claude_code.interaction` 跨度上，它携带用户提示，在 `claude_code.llm_request` 跨度上，它携带该请求的新用户消息和工具结果。这两者都需要 `OTEL_LOG_USER_PROMPTS=1`。362 `new_context` 上的门取决于哪个跨度携带它，每个副本都在内容限制处截断（默认值 60 KB）。在 `claude_code.tool` 跨度上，它携带该工具调用的结果，无论工具如何，并需要 `OTEL_LOG_TOOL_CONTENT=1`。在 `claude_code.interaction` 跨度上，它携带用户提示，在 `claude_code.llm_request` 跨度上，它携带该请求的新用户消息和工具结果。两者都需要 `OTEL_LOG_USER_PROMPTS=1`。

356 363

357 `user_system_prompt` 另外需要 `OTEL_LOG_USER_PROMPTS=1`。它仅携带您通过 `systemPrompt` SDK 选项或 `--system-prompt` 和 `--append-system-prompt` 标志提供的系统提示文本，在内容限制处截断（默认值：60 KB），并且每个会话发出一次而不是每个请求。364 `user_system_prompt` 另外需要 `OTEL_LOG_USER_PROMPTS=1`。它仅携带您通过 `systemPrompt` SDK 选项或 `--system-prompt` 和 `--append-system-prompt` 标志提供的系统提示文本，在内容限制处截断（默认值 60 KB），并且每个会话发出一次而不是每个请求。

358</Note>365</Note>

359 366

360<h3 id="dynamic-headers">367<h3 id="dynamic-headers">

385 392

386```bash theme={null}393```bash theme={null}

387#!/bin/bash394#!/bin/bash

388# Example: Multiple headers395# 示例：多个标头

389echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"396echo "{\"Authorization\": \"Bearer $(get-token.sh)\", \"X-API-Key\": \"$(get-api-key.sh)\"}"

390```397```

391 398

392如果助手失败或打印不符合这些要求的输出，导出会失败，您的遥测后端在助手再次工作之前不会从会话接收任何内容。Claude Code 在以下位置报告失败：399如果助手失败或打印不符合这些要求的输出，导出失败，您的遥测后端在会话中不会收到任何内容，直到助手再次工作。Claude Code 在以下位置报告失败：

393 400

394* 交互式会话中的警告通知，[`otelHeadersHelper failed; telemetry is not being exported`](/docs/zh-CN/errors#otelheadershelper-failed)，在助手首次失败时每个会话显示一次401* 交互式会话中的警告通知，[`otelHeadersHelper failed; telemetry is not being exported`](/docs/zh-CN/errors#otelheadershelper-failed)，在助手首次失败时每个会话显示一次

395* `/status` 输出402* `/status` 输出

400 刷新行为407 刷新行为

401</h4>408</h4>

402 409

403标头助手脚本在启动时运行，之后定期运行以支持令牌刷新。默认情况下，脚本每 29 分钟运行一次。使用 `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` 环境变量自定义间隔。410标头助手脚本在启动时运行，然后定期运行以支持令牌刷新。默认情况下，脚本每 29 分钟运行一次。使用 `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` 环境变量自定义间隔。

404 411

405<h3 id="multi-team-organization-support">412<h3 id="multi-team-organization-support">

406 多团队组织支持413 多团队组织支持

409具有多个团队或部门的组织可以使用 `OTEL_RESOURCE_ATTRIBUTES` 环境变量添加自定义属性以区分不同的组：416具有多个团队或部门的组织可以使用 `OTEL_RESOURCE_ATTRIBUTES` 环境变量添加自定义属性以区分不同的组：

410 417

411```bash theme={null}418```bash theme={null}

412# Add custom attributes for team identification419# 添加用于团队识别的自定义属性

413export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"420export OTEL_RESOURCE_ATTRIBUTES="department=engineering,team.id=platform,cost_center=eng-123"

414```421```

415 422

420* 创建特定于团队的仪表板427* 创建特定于团队的仪表板

421* 为特定团队设置警报428* 为特定团队设置警报

422 429

423Claude Code 将这些值作为属性附加到每个指标数据点和事件记录上，除了在 OTLP 资源块中发送它们。因为大多数指标后端将数据点属性公开为可查询的标签，您可以直接按自定义键对指标进行分组和过滤。除了 `vcs.*` [存储库属性](#repository-attributes)，自定义键永远不会覆盖[标准属性](#standard-attributes)，例如 `user.id` 或 `session.id`：当键冲突时，Claude Code 保留内置值。430Claude Code 将这些值作为属性附加到每个指标数据点和事件记录，除了在 OTLP 资源块中发送它们。因为大多数指标后端将数据点属性公开为可查询的标签，您可以直接按自定义键对指标进行分组和过滤。除了 `vcs.*` [存储库属性](#repository-attributes)，自定义键永远不会覆盖[标准属性](#standard-attributes)，例如 `user.id` 或 `session.id`：当键冲突时，Claude Code 保留内置值。

424 431

425每个自定义键都成为每个指标系列上的标签，因此高基数值会增加指标后端中的存储成本。要仅在资源块中发送自定义属性并从数据点标签中省略它们，请设置 `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false`。请参阅[指标基数控制](#metrics-cardinality-control)。432每个自定义键成为每个指标系列上的标签，因此高基数值会增加指标后端中的存储成本。要仅在资源块中发送自定义属性并从数据点标签中省略它们，请设置 `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false`。请参阅[指标基数控制](#metrics-cardinality-control)。

426 433

427<Warning>434<Warning>

428 `OTEL_RESOURCE_ATTRIBUTES` 环境变量使用逗号分隔的键=值对，具有严格的格式要求：435 `OTEL_RESOURCE_ATTRIBUTES` 环境变量使用逗号分隔的键=值对，具有严格的格式要求：

432 * **允许的字符**：仅限 US-ASCII 字符，不包括控制字符、空格、双引号、逗号、分号和反斜杠439 * **允许的字符**：仅限 US-ASCII 字符，不包括控制字符、空格、双引号、逗号、分号和反斜杠

433 * **特殊字符**：允许范围之外的字符必须进行百分比编码440 * **特殊字符**：允许范围之外的字符必须进行百分比编码

434 441

435 对于需要空格的值，请改用下划线或驼峰式大小写。以下示例使用每种形式设置 `org.name`：442 对于需要空格的值，请改用下划线或 camelCase。以下示例使用每种形式设置 `org.name`：

436 443

437 ```bash theme={null}444 ```bash theme={null}

438 export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"445 export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"

445 export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"452 export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"

446 ```453 ```

447 454

448 将值包装在引号中不会转义空格。例如，`org.name="My Company"` 导致文字值 `"My Company"`（包括引号），而不是 `My Company`。455 用引号包装值不会转义空格。例如，`org.name="My Company"` 导致文字值 `"My Company"`（包括引号），而不是 `My Company`。

449</Warning>456</Warning>

450 457

451<h3 id="example-configurations">458<h3 id="example-configurations">

452 示例配置459 示例配置

453</h3>460</h3>

454 461

455在运行 `claude` 之前设置这些环境变量。下面的每个场景都显示完整的配置，每个变量在[常见配置变量](#common-configuration-variables)下进行了描述。要确认配置生效，请在启动会话后检查后端中的 `claude_code.session.count` 指标；[快速入门](#quick-start)涵盖仅日志验证以及当没有任何内容到达时要检查的内容。462在运行 `claude` 之前设置这些环境变量。下面的每个场景显示完整的配置，每个变量在[常见配置变量](#common-configuration-variables)下进行了描述。要确认配置生效，请在启动会话后检查后端中的 `claude_code.session.count` 指标；[快速入门](#quick-start)涵盖仅日志验证以及当没有内容到达时要检查的内容。

456 463

457对于具有 1 秒导出间隔的控制台调试：464对于使用 1 秒导出间隔的控制台调试：

458 465

459```bash theme={null}466```bash theme={null}

460export CLAUDE_CODE_ENABLE_TELEMETRY=1467export CLAUDE_CODE_ENABLE_TELEMETRY=1

500export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317507export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://logs.example.com:4317

501```508```

502 509

503要仅导出指标，不导出事件或日志：510仅导出指标，不导出事件或日志：

504 511

505```bash theme={null}512```bash theme={null}

506export CLAUDE_CODE_ENABLE_TELEMETRY=1513export CLAUDE_CODE_ENABLE_TELEMETRY=1

509export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317516export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

510```517```

511 518

512要仅导出事件和日志，不导出指标：519仅导出事件和日志，不导出指标：

513 520

514```bash theme={null}521```bash theme={null}

515export CLAUDE_CODE_ENABLE_TELEMETRY=1522export CLAUDE_CODE_ENABLE_TELEMETRY=1

518export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317525export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

519```526```

520 527

528<h2 id="telemetry-from-cloud-sessions-and-claude-tag">

529 云会话和 Claude Tag 的遥测

530</h2>

531

532[云会话](/docs/zh-CN/claude-code-on-the-web)（包括 [Claude Tag](https://claude.com/docs/claude-tag/overview) 频道会话）在[云环境](/docs/zh-CN/cloud-environments)中运行，而不是在用户的设备上运行，因此设备上的托管设置文件或 shell 配置文件不会配置其遥测。对于在 Anthropic 托管环境中的会话，本部分介绍了在何处设置遥测变量、如何使收集器可从环境访问，以及如何在导出的数据中区分云会话和 Claude Tag 会话。

533

534要从这些会话导出遥测，请使用与[管理员配置](#administrator-configuration)示例相同的密钥，在以下两个位置之一中设置 `CLAUDE_CODE_ENABLE_TELEMETRY` 和 `OTEL_*` 变量：

535

536* **服务器管理的设置**：将它们添加到您组织的[服务器管理的设置](/docs/zh-CN/server-managed-settings)的 `env` 块中。Claude Code 在启动时会在[服务器管理的设置适用](/docs/zh-CN/model-config#surface-coverage)的任何地方获取这些设置，这包括您用户的机器和除 Claude Tag 频道会话外的云会话。Claude Tag 会话不会接收您的服务器管理的设置，因此此路由不会配置它们。

537* **环境的变量**：将它们添加到云环境的[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)中，以仅配置在该环境中运行的会话。这是到达 Claude Tag 会话的路由。

538

539任何使用环境的人都可以读取其变量，因此不要在其中放置凭证，例如 `OTEL_EXPORTER_OTLP_HEADERS` 中的收集器令牌。环境上的 [API 凭证](/docs/zh-CN/cloud-environments#add-api-credentials)也无法帮助，因为 Claude Code 自己的遥测导出是[从不获得凭证的请求](/docs/zh-CN/cloud-environments#requests-that-never-get-the-credential)之一。如果您的收集器需要凭证，请改为通过服务器管理的设置配置整个导出，因为当您在那里设置凭证时，[Claude Code 会删除在托管设置外设置的端点变量](#how-managed-settings-lock-the-otlp-destination)。

540

541在为云会话配置遥测时，请记住这些约束：

542

543* **让会话到达收集器**：Claude Code 通过会话的网络发送导出，因此它是否到达您的 `OTEL_EXPORTER_OTLP_ENDPOINT` 中的主机取决于环境的[网络访问级别](/docs/zh-CN/cloud-environments#access-levels)。如果会话无法在您选择的级别上到达收集器的域，请[将域添加到环境的允许列表](/docs/zh-CN/cloud-environments#allow-specific-domains)，因为没有服务器管理的设置会将域添加到环境的网络允许列表。

544* **Claude Tag 频道使用组织级别的环境**：频道会话在组织级别的环境中运行，而不是成员的个人环境中，因此请在[共享环境](/docs/zh-CN/cloud-environments#organization-shared-environments)上进行允许列表和任何环境变量更改，该环境设置为您组织的默认环境或固定到频道。

545* **Cowork 单独配置**：如[表面覆盖表](/docs/zh-CN/model-config#surface-coverage)所示，Cowork 会话不会接收服务器管理的设置，因此服务器管理的 `env` 块不会配置其遥测。

546

547<h3 id="attribute-telemetry-to-cloud-sessions">

548 将遥测属性分配给云会话

549</h3>

550

551默认情况下，来自云会话的指标和事件携带[标准属性](#standard-attributes)，包括 `session.id`、`ccr.session.id` 和 `organization.id`，因此您可以按会话或组织进行筛选，无需额外配置。`ccr.session.id` 值是会话的 `CLAUDE_CODE_REMOTE_SESSION_ID`。要将其转换为会话的成绩单 URL，请参阅[将输出链接回会话](/docs/zh-CN/cloud-environments#link-output-back-to-the-session)。

552

553要更详细地属性化遥测，请使用这些选项：

554

555* **识别 Claude Tag 会话**：设置 `OTEL_METRICS_INCLUDE_ENTRYPOINT=true`，如[指标基数控制](#metrics-cardinality-control)下所述。指标随后会携带 `app.entrypoint`，其值对于 Claude Tag 会话为 `claude-in-slack`。

556* **添加自定义属性**：在设置这些会话的其他 `OTEL_*` 变量的同一位置设置 [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support)。如果您改为在环境的[设置脚本](/docs/zh-CN/cloud-environments#setup-scripts)中 `export` 它，该值不会到达 Claude Code：设置脚本是在 Claude Code 启动前运行的单独 Bash 脚本，它导出的变量随之结束。

557

558在 Claude Tag 频道会话中，Claude 作为您组织的[共享身份](/docs/zh-CN/cloud-environments#set-the-environment-a-claude-tag-channel-uses)工作，而不是作为任何成员，因此不要依赖 `user.*` 属性来识别谁标记了 Claude。

559

521<h2 id="available-metrics-and-events">560<h2 id="available-metrics-and-events">

522 可用的指标和事件561 可用的指标和事件

523</h2>562</h2>

526 标准属性565 标准属性

527</h3>566</h3>

528 567

529所有指标和事件共享这些标准属性：568所有指标和事件都共享这些标准属性：

530 569

531| 属性 | 描述 | 控制方式 |570| 属性 | 描述 | 控制方式 |

532| - | - | - |571| - | - | - |

575| `app.entrypoint` | 会话的启动方式，例如 `cli`、`sdk-cli`、`sdk-ts`、`sdk-py`、`claude-vscode` 或 Claude Tag 会话的 `claude-in-slack` | `OTEL_METRICS_INCLUDE_ENTRYPOINT`（默认值：false） |

542| `OTEL_RESOURCE_ATTRIBUTES` 中的键 | 您设置的自定义属性，例如 `department` 或 `team.id`。请参阅 [多团队组织支持](#multi-team-organization-support) | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES`（默认：true） |582| `OTEL_RESOURCE_ATTRIBUTES` 中的键 | 您设置的自定义属性，例如 `department` 或 `team.id`。请参阅[多团队组织支持](#multi-team-organization-support) | `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES`（默认值：true） |

543| `vcs.repository.url.full`、`vcs.owner.name`、`vcs.repository.name`、`vcs.provider.name` | 会话存储库的身份，从其 `origin` 远程派生。请参阅 [存储库属性](#repository-attributes) | `OTEL_METRICS_INCLUDE_REPOSITORY`（默认：false）。需要 Claude Code v2.1.269 或更高版本 |583| `vcs.repository.url.full`、`vcs.owner.name`、`vcs.repository.name`、`vcs.provider.name` | 会话存储库的身份，从其 `origin` 远程派生。请参阅[存储库属性](#repository-attributes) | `OTEL_METRICS_INCLUDE_REPOSITORY`（默认值：false）。需要 Claude Code v2.1.269 或更高版本 |

544 584

545当 Claude Code 登录到 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 时，CLI 会使用来自网关会话的已认证身份标记导出：`user.id` 是 IdP 主体而不是匿名安装标识符，`user.email` 是已登录的电子邮件，`user.groups` 作为逗号分隔的字符串携带 IdP 组成员身份。每个导出还携带 `identity.source: gateway-oidc`。网关身份最后应用，因此通过 `OTEL_RESOURCE_ATTRIBUTES` 设置的 `user.*` 和 `identity.*` 键在网关会话上被忽略。585当 Claude Code 登录到[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)时，CLI 会使用来自网关会话的已认证身份标记导出：`user.id` 是 IdP 主体而不是匿名安装标识符，`user.email` 是已登录的电子邮件，`user.groups` 以逗号分隔的字符串形式携带 IdP 组成员身份。每个导出还携带 `identity.source: gateway-oidc`。网关身份最后应用，因此通过 `OTEL_RESOURCE_ATTRIBUTES` 设置的 `user.*` 和 `identity.*` 键在网关会话上被忽略。

546 586

547事件另外包含以下属性。这些永远不会附加到指标，因为它们会导致无限基数：587事件另外包括以下属性。这些永远不会附加到指标，因为它们会导致无限的基数：

548 588

549* `prompt.id`：UUID 将用户提示与所有后续事件关联到下一个提示。请参阅 [事件关联属性](#event-correlation-attributes)。589* `prompt.id`：UUID，将用户提示与所有后续事件关联到下一个提示。请参阅[事件关联属性](#event-correlation-attributes)。

550* `workspace.host_paths`：在桌面应用中选择的主机工作区目录，作为字符串数组590* `workspace.host_paths`：在桌面应用中选择的主机工作区目录，作为字符串数组

551* `workflow.run_id`：运行标识符，前缀为 `wf_`，在属于 [Workflow](/docs/zh-CN/workflows) 工具运行的代理发出的 API 和工具事件上。按一个 `workflow.run_id` 过滤事件可以重建该运行的 API 请求和工具结果。标识符涵盖工作流脚本生成的代理以及这些代理依次生成的任何代理，例如技能调用。它与 Workflow 工具结果中报告的运行标识符匹配。在所有其他事件上不存在。需要 Claude Code v2.1.202 或更高版本591* `workflow.run_id`：运行标识符，前缀为 `wf_`，在 API 和工具事件上，由属于[工作流](/docs/zh-CN/workflows)工具运行的代理发出。按一个 `workflow.run_id` 过滤事件可以重建该运行的 API 请求和工具结果。该标识符涵盖工作流脚本生成的代理以及这些代理依次生成的任何代理，例如技能调用。它与工作流工具结果中报告的运行标识符匹配。在所有其他事件上不存在。需要 Claude Code v2.1.202 或更高版本

552* `workflow.name`：工作流的名称，其脚本的 `meta.name`，与 `workflow.run_id` 一起发出。内置工作流名称在运行执行未修改的内置脚本时按原样出现。用户创作的名称（包括内置脚本的编辑副本）被替换为 `custom`，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`。需要 Claude Code v2.1.202 或更高版本592* `workflow.name`：工作流的名称，其脚本的 `meta.name`，与 `workflow.run_id` 一起发出。内置工作流名称在运行未修改的内置脚本时逐字显示。用户创作的名称（包括内置脚本的编辑副本）被替换为 `custom`，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`。需要 Claude Code v2.1.202 或更高版本

553 593

554<h4 id="repository-attributes">594<h4 id="repository-attributes">

555 存储库属性595 存储库属性

556</h4>596</h4>

557 597

558设置 `OTEL_METRICS_INCLUDE_REPOSITORY=true` 以使用会话存储库的身份标记指标和事件，以便共享收集器可以按存储库归属使用情况。需要 Claude Code v2.1.269 或更高版本。598设置 `OTEL_METRICS_INCLUDE_REPOSITORY=true` 以使用会话存储库的身份标记指标和事件，以便共享收集器可以按存储库属性使用情况。需要 Claude Code v2.1.269 或更高版本。

559 599

560Claude Code 从存储库的 `origin` 远程每个会话派生这些属性一次。一个存储库的 HTTPS 和 SSH 远程产生相同的值：600Claude Code 每个会话从存储库的 `origin` 远程派生这些属性一次。当存储库的 HTTPS 和 SSH 远程命名相同的主机和相同的路径时（如在 GitHub、GitLab 和 Bitbucket Cloud 上一样），两者都会产生相同的值：

561 601

562| 属性 | 值 |602| 属性 | 值 |

563| - | - |603| - | - |

568 608

569值被小写，远程 URL 中的凭证、查询字符串和片段永远不会出现在其中。当会话没有 `origin` 远程、远程不是 URL 形状或唯一的封闭存储库是您的主目录时，属性被省略。609值被小写，远程 URL 中的凭证、查询字符串和片段永远不会出现在其中。当会话没有 `origin` 远程、远程不是 URL 形状或唯一的封闭存储库是您的主目录时，属性被省略。

570 610

571您在 [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support) 中声明的 `vcs.*` 键替换该键的派生值。如果您声明 `vcs.repository.url.full`，Claude Code 永远不会读取远程，仅报告您声明的键。611要从[云会话](/docs/zh-CN/claude-code-on-the-web)获取这些属性，请在其[云环境](/docs/zh-CN/cloud-environments#set-environment-variables)上设置遥测变量，包括 `OTEL_METRICS_INCLUDE_REPOSITORY`。还要在环境的[网络访问](/docs/zh-CN/cloud-environments#network-access)中允许您的收集器域。

612

613您在 [`OTEL_RESOURCE_ATTRIBUTES`](#multi-team-organization-support) 中声明的 `vcs.*` 键会替换该键的派生值。如果您声明 `vcs.repository.url.full`，Claude Code 永远不会读取远程，只报告您声明的键。

572 614

573属性仅流向您自己的导出器；Anthropic 的遥测删除每个 `vcs.*` 键。615如果一个存储库的 HTTPS 和 SSH 克隆报告不同的值，例如在自托管安装中，其 HTTPS 克隆 URL 携带 SSH URL 缺少的路径前缀，请在 `OTEL_RESOURCE_ATTRIBUTES` 中声明 `vcs.repository.url.full` 以及您想要报告的所有其他 `vcs.*` 键。然后每个克隆都报告您声明的身份。

616

617属性仅流向您自己的导出器；Anthropic 的遥测会删除每个 `vcs.*` 键。

574 618

575<h3 id="metrics">619<h3 id="metrics">

576 指标620 指标

577</h3>621</h3>

578 622

579Claude Code 导出以下指标。"单位"列显示附加到每个指标的 OpenTelemetry 单位字符串；计数指标不携带任何单位。623Claude Code 导出以下指标。单位列显示附加到每个指标的 OpenTelemetry 单位字符串；计数指标不携带任何单位。

580 624

581| 指标名称 | 描述 | 单位 |625| 指标名称 | 描述 | 单位 |

582| - | - | - |626| - | - | - |

587| `claude_code.cost.usage` | Claude Code 会话的成本 | USD |631| `claude_code.cost.usage` | Claude Code 会话的成本 | USD |

590| `claude_code.active_time.total` | 总活跃时间 | s |634| `claude_code.active_time.total` | 总活跃时间 | s |

591 635

592当 `prometheus` 是 `OTEL_METRICS_EXPORTER` 中列出的唯一导出器时，Claude Code 会从导出的指标中省略 `USD`、`tokens` 和 `s` 单位，以便抓取保持有效的 Prometheus 文本格式。指标名称不会改变，组合导出器的配置（例如 `otlp,prometheus`）保留单位。在 v2.1.216 之前，Prometheus 抓取包含一些抓取器拒绝的仅 OpenMetrics `# UNIT` 行。636当 `prometheus` 是 `OTEL_METRICS_EXPORTER` 中列出的唯一导出器时，Claude Code 会从导出的指标中省略 `USD`、`tokens` 和 `s` 单位，以便抓取保持有效的 Prometheus 文本格式。指标名称不会改变，组合导出器的配置（例如 `otlp,prometheus`）保留单位。在 v2.1.216 之前，Prometheus 抓取包含一些抓取器拒绝的仅 OpenMetrics 的 `# UNIT` 行。

593 637

594<h3 id="metric-details">638<h3 id="metric-details">

595 指标详情639 指标详情

596</h3>640</h3>

597 641

598每个指标都包含上面列出的标准属性。具有额外上下文特定属性的指标如下所述。642每个指标都包括上面列出的标准属性。具有额外上下文特定属性的指标如下所述。

599 643

600<h4 id="session-counter">644<h4 id="session-counter">

601 会话计数器645 会话计数器

605 649

606**属性**：650**属性**：

607 651

608* 所有 [标准属性](#standard-attributes)652* 所有[标准属性](#standard-attributes)

609* `start_type`：会话的启动方式。`"fresh"`、`"resume"`、`"continue"` 或 `"agents_view"` 之一。`"agents_view"` 值标识 `claude agents` 仪表板进程，这是用户启动的本地 UI 而不是对话会话。在您的仪表板中过滤此值以将 UI 进程启动与对话会话分开。653* `start_type`：会话的启动方式。`"fresh"`、`"resume"`、`"continue"` 或 `"agents_view"` 之一。`"agents_view"` 值标识 `claude agents` 仪表板进程，这是用户启动的本地 UI 而不是对话会话。在此值上过滤以在您的仪表板中将 UI 进程启动与对话会话分开。

610 654

611<h4 id="lines-of-code-counter">655<h4 id="lines-of-code-counter">

612 代码行计数器656 代码行计数器

616 660

617**属性**：661**属性**：

618 662

619* 所有 [标准属性](#standard-attributes)663* 所有[标准属性](#standard-attributes)

620* `type`：（`"added"`、`"removed"`）664* `type`：（`"added"`、`"removed"`）

621* `model`：进行更改的模型的模型标识符（例如，"claude-sonnet-5"）665* `model`：进行更改的模型的模型标识符（例如，"claude-sonnet-5"）

622 666

624 拉取请求计数器668 拉取请求计数器

625</h4>669</h4>

626 670

627通过 shell 命令或 MCP 工具通过 Claude Code 创建拉取请求或合并请求时递增。671当 Claude Code 通过 shell 命令或 MCP 工具创建拉取请求或合并请求时递增。

628 672

629**属性**：673**属性**：

630 674

631* 所有 [标准属性](#standard-attributes)675* 所有[标准属性](#standard-attributes)

632 676

633<h4 id="commit-counter">677<h4 id="commit-counter">

634 提交计数器678 提交计数器

638 682

639**属性**：683**属性**：

640 684

641* 所有 [标准属性](#standard-attributes)685* 所有[标准属性](#standard-attributes)

642 686

643<h4 id="cost-counter">687<h4 id="cost-counter">

644 成本计数器688 成本计数器

646 690

647在每个 API 请求后递增。691在每个 API 请求后递增。

648 692

693`agent.name`、`skill.name`、`plugin.name`、`mcp_server.name` 和 `mcp_tool.name` 属性默认将某些名称编辑为 `"custom"` 或 `"third-party"` 占位符。如果您设置 `OTEL_LOG_TOOL_DETAILS=1`，它们会改为携带真实名称。在 v2.1.273 之前，成本和令牌计数器以及 `api_request`、`api_error` 和 `api_refusal` 事件即使设置了 `OTEL_LOG_TOOL_DETAILS=1` 也携带编辑后的值。

694

649**属性**：695**属性**：

650 696

651* 所有 [标准属性](#standard-attributes)697* 所有[标准属性](#standard-attributes)

652* `model`：模型标识符（例如，"claude-sonnet-5"）698* `model`：模型标识符（例如，"claude-sonnet-5"）

653* `query_source`：发出请求的子系统的类别。`"main"`、`"subagent"` 或 `"auxiliary"` 之一699* `query_source`：发出请求的子系统的类别。`"main"`、`"subagent"` 或 `"auxiliary"` 之一

654* `speed`：当请求使用快速模式时为 `"fast"`。否则不存在700* `speed`：当请求使用快速模式时为 `"fast"`。否则不存在

655* `effort`：应用于请求的 [努力级别](/docs/zh-CN/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。当模型不支持努力时不存在。701* `effort`：应用于请求的[努力级别](/docs/zh-CN/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。当 Claude Code 不发送努力级别时不存在，例如在不支持努力的模型上。

656* `agent.name`：发出请求的子代理类型。内置代理名称和来自官方市场插件的代理按原样出现。其他用户定义的代理名称被替换为 `"custom"`，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`。当请求不是由命名子代理类型发出时不存在。702* `agent.name`：发出请求的子代理类型。内置代理名称和来自官方市场插件的代理逐字显示。其他用户定义的代理名称被替换为 `"custom"`。当请求不是由命名的子代理类型发出时不存在。

657* `skill.name`：对请求活跃的技能，由 Skill 工具、`/` 命令设置或由生成的子代理继承。内置、捆绑、用户定义和官方市场插件技能名称按原样出现。第三方插件技能名称被替换为 `"third-party"`，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`。当没有技能活跃时不存在。703* `skill.name`：对请求活跃的技能，由技能工具或 `/` 命令设置，或由生成的子代理继承。内置、捆绑、用户定义和官方市场插件技能名称逐字显示。第三方插件技能名称被替换为 `"third-party"`。当没有技能活跃时不存在。

658* `plugin.name`：当活跃技能或子代理由插件提供时的拥有插件。官方市场插件名称按原样出现。第三方插件名称被替换为 `"third-party"`，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`。当技能和子代理都没有拥有插件时不存在。704* `plugin.name`：当活跃的技能或子代理由插件提供时的所有者插件。官方市场插件名称逐字显示。第三方插件名称被替换为 `"third-party"`。当技能和子代理都没有所有者插件时不存在。

659* `marketplace.name`：拥有插件安装来源的市场。仅为官方市场插件发出。否则不存在。705* `marketplace.name`：所有者插件安装的市场。仅对官方市场插件发出，即使设置了 `OTEL_LOG_TOOL_DETAILS=1`。否则不存在。

660* `mcp_server.name`：MCP 服务器，其工具结果此请求消耗。内置、claude.ai 代理和官方注册表服务器名称按原样出现。用户配置的服务器名称被替换为 `"custom"`，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`。当请求没有消耗 MCP 工具结果时不存在。在 v2.1.222 之前，Claude Code 在每个 MCP 工具调用后的请求上设置此属性，而不仅仅是消耗工具结果的请求，因此聚合它的仪表板在升级后显示下降。706* `mcp_server.name`：其工具结果此请求消耗的 MCP 服务器。内置、claude.ai 代理和官方注册表服务器名称逐字显示。用户配置的服务器名称被替换为 `"custom"`。当请求没有消耗 MCP 工具结果时不存在。在 v2.1.222 之前，Claude Code 在每个 MCP 工具调用后的请求上设置此属性，而不仅仅在消耗工具结果的请求上，因此聚合它的仪表板在升级后显示下降。

661* `mcp_tool.name`：MCP 工具，其结果此请求消耗，与 `mcp_server.name` 具有相同的编辑和版本行为。当请求没有消耗 MCP 工具结果时不存在。707* `mcp_tool.name`：其结果此请求消耗的 MCP 工具，具有与 `mcp_server.name` 相同的编辑和版本行为。当请求没有消耗 MCP 工具结果时不存在。

662 708

663<h4 id="token-counter">709<h4 id="token-counter">

664 令牌计数器710 令牌计数器

668 714

669**属性**：715**属性**：

670 716

671* 所有 [标准属性](#standard-attributes)717* 所有[标准属性](#standard-attributes)

672* `type`：（`"input"`、`"output"`、`"cacheRead"`、`"cacheCreation"`）718* `type`：（`"input"`、`"output"`、`"cacheRead"`、`"cacheCreation"`）

673* `model`：模型标识符（例如，"claude-sonnet-5"）719* `model`：模型标识符（例如，"claude-sonnet-5"）

674* `query_source`：发出请求的子系统的类别。`"main"`、`"subagent"` 或 `"auxiliary"` 之一720* `query_source`：发出请求的子系统的类别。`"main"`、`"subagent"` 或 `"auxiliary"` 之一

675* `speed`：当请求使用快速模式时为 `"fast"`。否则不存在721* `speed`：当请求使用快速模式时为 `"fast"`。否则不存在

676* `effort`：应用于请求的 [努力级别](/docs/zh-CN/model-config#adjust-effort-level)。有关详情，请参阅 [成本计数器](#cost-counter)。722* `effort`：应用于请求的[努力级别](/docs/zh-CN/model-config#adjust-effort-level)。有关详情，请参阅[成本计数器](#cost-counter)。

677* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：请求的技能、插件、代理和 MCP 归属。有关定义和编辑行为，请参阅 [成本计数器](#cost-counter)。723* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：请求的技能、插件、代理和 MCP 属性。有关定义和编辑行为，请参阅[成本计数器](#cost-counter)。

678 724

679<h4 id="code-edit-tool-decision-counter">725<h4 id="code-edit-tool-decision-counter">

680 代码编辑工具决策计数器726 代码编辑工具决策计数器

684 730

685**属性**：731**属性**：

686 732

687* 所有 [标准属性](#standard-attributes)733* 所有[标准属性](#standard-attributes)

688* `tool_name`：工具名称（`"Edit"`、`"Write"`、`"NotebookEdit"`）734* `tool_name`：工具名称（`"Edit"`、`"Write"`、`"NotebookEdit"`）

689* `decision`：用户决策（`"accept"`、`"reject"`）735* `decision`：用户决策（`"accept"`、`"reject"`）

690* `source`：决策来源。`"config"`、`"hook"`、`"user_permanent"`、`"user_temporary"`、`"user_abort"` 或 `"user_reject"` 之一。请参阅 [工具决策事件](#tool-decision-event) 了解每个值的含义。736* `source`：决策来自何处。`"config"`、`"hook"`、`"user_permanent"`、`"user_temporary"`、`"user_abort"` 或 `"user_reject"` 之一。请参阅[工具决策事件](#tool-decision-event)了解每个值的含义。

691* `language`：编辑文件的编程语言，例如 `"TypeScript"`、`"Python"`、`"JavaScript"` 或 `"Markdown"`。对于无法识别的文件扩展名，返回 `"unknown"`。737* `language`：编辑文件的编程语言，例如 `"TypeScript"`、`"Python"`、`"JavaScript"` 或 `"Markdown"`。对于无法识别的文件扩展名返回 `"unknown"`。

692 738

693<h4 id="active-time-counter">739<h4 id="active-time-counter">

694 活跃时间计数器740 活跃时间计数器

695</h4>741</h4>

696 742

697跟踪实际花费在积极使用 Claude Code 上的时间，不包括空闲时间。此指标在用户交互期间递增（输入、读取响应）以及在 CLI 处理期间（工具执行、AI 响应生成）。743跟踪实际花费在积极使用 Claude Code 上的时间，不包括空闲时间。此指标在用户交互期间递增，例如键入和阅读响应，以及在 CLI 处理期间，例如工具执行和 AI 响应生成。

698 744

699**属性**：745**属性**：

700 746

701* 所有 [标准属性](#standard-attributes)747* 所有[标准属性](#standard-attributes)

702* `type`：`"user"` 用于键盘交互，`"cli"` 用于工具执行和 AI 响应748* `type`：`"user"` 用于键盘交互，`"cli"` 用于工具执行和 AI 响应

703 749

704<h3 id="events">750<h3 id="events">

715 761

716| 属性 | 描述 |762| 属性 | 描述 |

717| - | - |763| - | - |

720| `message.uuid` | 消息的 UUID，如会话记录中保存的那样，`~/.claude/projects/*/*.jsonl` 文件。在 `assistant_response` 上存在，在 `api_response_body` 上存在，在 `user_prompt` 上存在，除了命令分派，它可以产生零个或多个消息。在 `assistant_response` 和 `api_response_body` 上，这是响应的最终记录条目，下一轮的 `parentUuid` 从其链接。需要 Claude Code v2.1.214 或更高版本，或在 `api_response_body` 上需要 v2.1.274 或更高版本 |766| `message.uuid` | 消息的 UUID，如会话记录中保存的，`~/.claude/projects/*/*.jsonl` 文件。存在于 `assistant_response`、`api_response_body` 和 `user_prompt` 上，除了命令调度，它可以产生零个或多个消息。在 `assistant_response` 和 `api_response_body` 上，这是响应的最终记录条目，下一轮的 `parentUuid` 从其链接。需要 Claude Code v2.1.214 或更高版本，或在 `api_response_body` 上需要 v2.1.274 或更高版本 |

721| `client_request_id` | 客户端生成的 UUID，作为 `x-client-request-id` 请求标头发送。在第一方 API 连接上的 `api_request` 和 `api_error` 上存在；在第三方提供商后端上不存在，当请求通过非流式回退重试时。将请求与其响应配对，并对于从未产生服务器 `request_id` 的超时等失败保持可用。与 `llm_request` 跟踪跨度上的相同属性匹配。需要 Claude Code v2.1.214 或更高版本 |767| `request_id` | 服务器分配的 API 请求 ID，从 `request-id` 响应头读取，例如 `req_011...`。在没有 `request-id` 头的响应上，如在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 上，值来自 `x-amzn-requestid` 头。存在于 `api_request`、`api_error`、`api_refusal`、`assistant_response` 和 `api_response_body` 上，当响应携带任一头时。与 `llm_request` 跟踪跨度上的相同属性匹配。`x-amzn-requestid` 源需要 Claude Code v2.1.282 或更高版本 |

768| `client_request_id` | 作为 `x-client-request-id` 请求头发送的客户端生成的 UUID。存在于第一方 API 连接上的 `api_request` 和 `api_error` 上；在第三方提供商后端上不存在，当请求通过非流式回退重试时。将请求与其响应配对，并对于超时等从未产生服务器 `request_id` 的失败保持可用。与 `llm_request` 跟踪跨度上的相同属性匹配。需要 Claude Code v2.1.214 或更高版本 |

722 769

723要跟踪由单个提示触发的所有活动，请按特定 `prompt.id` 值过滤您的事件。这会返回 user\_prompt 事件、任何 api\_request 事件以及处理该提示时发生的任何 tool\_result 事件。770要跟踪由单个提示触发的所有活动，请按特定 `prompt.id` 值过滤您的事件。这会返回 user\_prompt 事件、任何 api\_request 事件以及处理该提示时发生的任何 tool\_result 事件。

724 771

725`event.sequence` 在每次 Claude Code 进程启动时从 0 开始，并在该进程的生命周期内计数。它在 `/clear` 后继续计数，这会分配一个新的 `session.id`。如果您 [恢复会话而不分叉](/docs/zh-CN/how-claude-code-works#resume-or-fork-sessions)，会话保留其 `session.id` 但从恢复它的进程获取其 `event.sequence` 值，因此在一个会话内，后来的事件可以携带比早期事件更低的值，或重复一个。要排序会话的事件，按 `event.timestamp` 排序，使用 `event.sequence` 排序共享时间戳的事件。772`event.sequence` 在每次 Claude Code 进程启动时从 0 开始，并在该进程的生命周期内计数。它在 `/clear` 中继续计数，这会分配一个新的 `session.id`。如果您[恢复会话而不分叉](/docs/zh-CN/how-claude-code-works#resume-or-fork-sessions)，会话保留其 `session.id` 但从恢复它的进程获取其 `event.sequence` 值，因此在一个会话内，较晚的事件可以携带比较早的值更低的值，或重复一个。要排序会话的事件，按 `event.timestamp` 排序，并使用 `event.sequence` 排序共享时间戳的事件。

726 773

727对于消息级别的重建，每个事件类都携带与会话记录中的字段匹配的键。记录条目格式是 [Claude Code 内部的](/docs/zh-CN/sessions#where-transcripts-are-stored)，在版本之间变化，因此在这些字段上联接的管道可能在任何版本上中断；将联接视为版本特定的而不是稳定的合同：774对于消息级别的重建，每个事件类都携带一个与会话记录中的字段匹配的键。记录条目格式是[Claude Code 内部的](/docs/zh-CN/sessions#where-transcripts-are-stored)，在版本之间变化，因此在这些字段上联接的管道可能在任何版本上中断；将联接视为版本特定的而不是稳定的合同：

728 775

729* `message.uuid` 在 `user_prompt`、`assistant_response` 和 `api_response_body` 上776* `message.uuid` 在 `user_prompt`、`assistant_response` 和 `api_response_body` 上

730* `request_id` 在 API 事件上，在记录的助手条目上保存为 `requestId`777* `request_id` 在 API 事件上，在记录的助手条目上保存为 `requestId`

740 787

741**属性**：788**属性**：

742 789

743* 所有 [标准属性](#standard-attributes)790* 所有[标准属性](#standard-attributes)

744* `event.name`：`"user_prompt"`791* `event.name`：`"user_prompt"`

745* `event.timestamp`：ISO 8601 时间戳792* `event.timestamp`：ISO 8601 时间戳

746* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述793* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

747* `prompt_length`：提示的长度794* `prompt_length`：提示的长度

748* `prompt`：提示内容。默认为已编辑。设置 `OTEL_LOG_USER_PROMPTS=1` 以包含它795* `prompt`：提示内容。默认编辑。设置 `OTEL_LOG_USER_PROMPTS=1` 以包含它

749* `message.uuid`：生成的用户消息的 UUID，与保存的记录条目匹配。在命令分派上不存在，它可以产生零个或多个消息。需要 Claude Code v2.1.214 或更高版本796* `message.uuid`：生成的用户消息的 UUID，与保存的记录条目匹配。在命令调度上不存在，它可以产生零个或多个消息。需要 Claude Code v2.1.214 或更高版本

750* `command_name`：当提示调用命令时的命令名称。内置和捆绑的命令名称（例如 `compact` 或 `debug`）按原样发出；别名（例如 `reset`）按输入方式发出而不是规范名称。自定义、插件和 MCP 命令名称折叠为 `custom` 或 `mcp`，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`797* `command_name`：当提示调用一个时的命令名称。内置和捆绑命令名称如 `compact` 或 `debug` 按原样发出；别名如 `reset` 按键入的方式发出而不是规范名称。自定义、插件和 MCP 命令名称折叠为 `custom` 或 `mcp`，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`

751* `command_source`：命令存在时的来源：`builtin`、`custom` 或 `mcp`。插件提供的命令报告为 `custom`798* `command_source`：命令存在时的来源：`builtin`、`custom` 或 `mcp`。插件提供的命令报告为 `custom`

752 799

753<h4 id="assistant-response-event">800<h4 id="assistant-response-event">

754 助手响应事件801 助手响应事件

755</h4>802</h4>

756 803

757在每个返回来自模型的文本内容的 API 请求后记录。仅包含响应的文本块；思考块和工具使用块被排除。需要 Claude Code v2.1.193 或更高版本。804在返回来自模型的文本内容的每个 API 请求后记录。仅包括响应的文本块；思考块和工具使用块被排除。需要 Claude Code v2.1.193 或更高版本。

758 805

759**事件名称**：`claude_code.assistant_response`806**事件名称**：`claude_code.assistant_response`

760 807

761**属性**：808**属性**：

762 809

763* 所有 [标准属性](#standard-attributes)810* 所有[标准属性](#standard-attributes)

764* `event.name`：`"assistant_response"`811* `event.name`：`"assistant_response"`

765* `event.timestamp`：ISO 8601 时间戳812* `event.timestamp`：ISO 8601 时间戳

766* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述813* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

767* `response_length`：响应文本的长度（字符数）814* `response_length`：响应文本的长度（以字符为单位）

768* `response`：响应文本，在内容限制处截断（默认 60 KB）。默认为 `<REDACTED>` 编辑。设置 `OTEL_LOG_ASSISTANT_RESPONSES=1` 以包含它。当 `OTEL_LOG_ASSISTANT_RESPONSES` 未设置时，`OTEL_LOG_USER_PROMPTS` 控制它，因此设置 `OTEL_LOG_ASSISTANT_RESPONSES=0` 以在启用提示日志记录时保持响应编辑815* `response`：响应文本，在内容限制处截断（默认 60 KB）。默认编辑为 `<REDACTED>`。设置 `OTEL_LOG_ASSISTANT_RESPONSES=1` 以包含它。当 `OTEL_LOG_ASSISTANT_RESPONSES` 未设置时，`OTEL_LOG_USER_PROMPTS` 控制它，因此设置 `OTEL_LOG_ASSISTANT_RESPONSES=0` 以在启用提示日志记录时保持响应编辑

769* `model`：模型标识符（例如，"claude-sonnet-5"）816* `model`：模型标识符（例如，"claude-sonnet-5"）

770* `request_id`：来自响应的 `request-id` 标头的 Anthropic API 请求 ID。仅当 API 返回时存在817* `request_id`：API 请求 ID，在[事件关联属性](#event-correlation-attributes)下描述

771* `message.uuid`：响应的最终记录条目的 UUID。API 响应被保存为每个内容块一个记录条目；这是最后一个，下一轮的 `parentUuid` 从其链接。需要 Claude Code v2.1.214 或更高版本818* `message.uuid`：响应的最终记录条目的 UUID。API 响应作为每个内容块一个记录条目保存；这是最后一个，下一轮的 `parentUuid` 从其链接。需要 Claude Code v2.1.214 或更高版本

772* `query_source`：发出请求的子系统，例如 `"repl_main_thread"`、`"compact"` 或子代理名称819* `query_source`：发出请求的子系统，例如 `"repl_main_thread"`、`"compact"` 或子代理名称

773 820

774<h4 id="tool-result-event">821<h4 id="tool-result-event">

775 工具结果事件822 工具结果事件

776</h4>823</h4>

777 824

778当工具完成执行时记录。如果工具调用被拒绝，则不会发出；请参阅 [工具决策事件](#tool-decision-event) 了解拒绝。825当工具完成执行时记录。如果工具调用被拒绝，则不发出；请参阅[工具决策事件](#tool-decision-event)了解拒绝。

779 826

780**事件名称**：`claude_code.tool_result`827**事件名称**：`claude_code.tool_result`

781 828

782**属性**：829**属性**：

783 830

784* 所有 [标准属性](#standard-attributes)831* 所有[标准属性](#standard-attributes)

785* `event.name`：`"tool_result"`832* `event.name`：`"tool_result"`

786* `event.timestamp`：ISO 8601 时间戳833* `event.timestamp`：ISO 8601 时间戳

787* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述834* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

788* `tool_name`：工具的名称835* `tool_name`：工具的名称

789* `tool_use_id`：此工具调用的唯一标识符。与传递给 hooks 的 `tool_use_id` 匹配，允许在 OTel 事件和 hook 捕获的数据之间进行关联。836* `tool_use_id`：此工具调用的唯一标识符。与传递给钩子的 `tool_use_id` 匹配，允许 OTel 事件和钩子捕获数据之间的关联。

790* `success`：`"true"` 或 `"false"`837* `success`：`"true"` 或 `"false"`

791* `duration_ms`：执行时间（毫秒）838* `duration_ms`：执行时间（以毫秒为单位）

792* `error_type`：工具失败时的错误类别字符串，例如 `"Error:ENOENT"` 或 `"ShellError"`839* `error_type`：工具失败时的错误类别字符串，例如 `"Error:ENOENT"` 或 `"ShellError"`

793* `error`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：工具失败时的完整错误消息840* `error`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：工具失败时的完整错误消息

794* `decision_type`：始终为 `"accept"`，因为此事件仅在工具运行后发出。拒绝的调用不会产生工具结果841* `decision_type`：始终为 `"accept"`，因为此事件仅在工具运行后发出。拒绝的调用不产生工具结果

795* `decision_source`：权限决策来源。`"config"`、`"hook"`、`"user_permanent"` 或 `"user_temporary"` 之一。请参阅 [工具决策事件](#tool-decision-event) 了解每个值的含义。仅拒绝的来源 `"user_abort"` 和 `"user_reject"` 永远不会出现在此事件上。842* `decision_source`：权限决策来自何处。`"config"`、`"hook"`、`"user_permanent"` 或 `"user_temporary"` 之一。请参阅[工具决策事件](#tool-decision-event)了解每个值的含义。仅拒绝的源 `"user_abort"` 和 `"user_reject"` 永远不会出现在此事件上。

796* `tool_input_size_bytes`：JSON 序列化工具输入的大小（字节）843* `tool_input_size_bytes`：JSON 序列化工具输入的大小（以字节为单位）

797* `tool_result_size_bytes`：工具结果的大小（字节）844* `tool_result_size_bytes`：工具结果的大小（以字节为单位）

798* `mcp_server_scope`：MCP 服务器范围标识符（用于 MCP 工具）845* `mcp_server_scope`：MCP 服务器范围标识符（对于 MCP 工具）

799* `vcs.ref.head.revision`、`vcs.ref.head.name`、`vcs.ref.head.type`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：由 Bash 或 PowerShell 工具成功运行的 `git commit` 的提交身份。`vcs.ref.head.revision` 是提交 SHA，`vcs.ref.head.name` 是它被提交到的分支，`vcs.ref.head.type` 是 `branch`。当提交在分离的 HEAD 上进行时，名称和类型被省略。需要 Claude Code v2.1.269 或更高版本846* `vcs.ref.head.revision`、`vcs.ref.head.name`、`vcs.ref.head.type`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：由 Bash 或 PowerShell 工具成功运行的 `git commit` 的提交身份。`vcs.ref.head.revision` 是提交 SHA，`vcs.ref.head.name` 是提交的分支，`vcs.ref.head.type` 是 `branch`。当提交在分离的 HEAD 上进行时，名称和类型被省略。需要 Claude Code v2.1.269 或更高版本

800* `tool_parameters`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：包含工具特定参数的 JSON 字符串。对于 Claude Desktop 的内置服务器，在 Claude Desktop 拥有的会话中，即使标志关闭，`mcp_server_name`/`mcp_tool_name` 对也包含在内，与 [工具决策事件](#tool-decision-event) 相同的主机创作异常，需要 Claude Code v2.1.214 或更高版本。参数因工具而异：847* `tool_parameters`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：包含工具特定参数的 JSON 字符串。对于 Claude Desktop 的内置服务器，在 Claude Desktop 拥有的会话中，`mcp_server_name`/`mcp_tool_name` 对即使在标志关闭时也包含，与[工具决策事件](#tool-decision-event)相同的主机创作异常，需要 Claude Code v2.1.214 或更高版本。参数因工具而异：

801 * 对于 Bash 工具：包括 `bash_command`、`full_command`、`timeout`、`description`、`dangerouslyDisableSandbox`，以及 `git_commit_id` 和 `git_branch`（当 `git commit` 命令成功时）。`git_commit_id` 是完整的提交 SHA（当提交是会话工作目录的 HEAD 时），否则是 git 的缩写 SHA。`git_branch` 是它被提交到的分支，在分离的 HEAD 上省略。对于桌面应用的工作区 Bash 工具，它也将 `tool_name` 报告为 `Bash`：仅包括 `bash_command`、`full_command` 和 `timeout`848 * 对于 Bash 工具：包括 `bash_command`、`full_command`、`timeout`、`description` 和 `dangerouslyDisableSandbox`，加上 `git_commit_id` 和 `git_branch`（当 `git commit` 命令成功时）。`git_commit_id` 是完整的提交 SHA（当提交是会话工作目录的 HEAD 时），否则是 git 的缩写 SHA。`git_branch` 是提交的分支，在分离的 HEAD 上省略

849 * 对于桌面应用的工作区 Bash 工具，它也将 `tool_name` 报告为 `Bash`：仅包括 `bash_command`、`full_command` 和 `timeout`

802 * 对于 MCP 工具：包括 `mcp_server_name`、`mcp_tool_name`850 * 对于 MCP 工具：包括 `mcp_server_name`、`mcp_tool_name`

803 * 对于 Skill 工具：包括 `skill_name`851 * 对于技能工具：包括 `skill_name`

804 * 对于 Agent 工具或旧版 Task 工具：包括 `subagent_type`852 * 对于代理工具或旧版任务工具：包括 `subagent_type`

805* `tool_input`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：JSON 序列化的工具参数。超过 512 个字符的单个值被截断，完整有效负载限制为约 4 K 字符。适用于所有工具，包括 MCP 工具。853* `tool_input`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：JSON 序列化的工具参数。超过 512 个字符的单个值被截断，完整有效负载限制在约 4 K 字符。适用于所有工具，包括 MCP 工具。

806 854

807<h4 id="api-request-event">855<h4 id="api-request-event">

808 API 请求事件856 API 请求事件

814 862

815**属性**：863**属性**：

816 864

817* 所有 [标准属性](#standard-attributes)865* 所有[标准属性](#standard-attributes)

818* `event.name`：`"api_request"`866* `event.name`：`"api_request"`

819* `event.timestamp`：ISO 8601 时间戳867* `event.timestamp`：ISO 8601 时间戳

820* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述868* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

821* `model`：使用的模型（例如，"claude-sonnet-5"）869* `model`：使用的模型（例如，"claude-sonnet-5"）

822* `cost_usd`：USD 估计成本870* `cost_usd`：以美元为单位的估计成本

823* `cost_usd_micros`：USD 百万分之一的估计成本，作为整数发出871* `cost_usd_micros`：以美元百万分之一为单位的估计成本，作为整数发出

824* `duration_ms`：请求持续时间（毫秒）872* `duration_ms`：请求持续时间（以毫秒为单位）

825* `input_tokens`：输入令牌数873* `input_tokens`：输入令牌数

826* `output_tokens`：输出令牌数874* `output_tokens`：输出令牌数

827* `cache_read_tokens`：从缓存读取的令牌数875* `cache_read_tokens`：从缓存读取的令牌数

828* `cache_creation_tokens`：用于缓存创建的令牌数876* `cache_creation_tokens`：用于缓存创建的令牌数

829* `request_id`：来自响应的 `request-id` 标头的 Anthropic API 请求 ID，例如 `"req_011..."`。仅当 API 返回时存在。877* `request_id`：API 请求 ID，例如 `"req_011..."`，在[事件关联属性](#event-correlation-attributes)下描述。

830* `client_request_id`：客户端生成的 UUID，作为 `x-client-request-id` 请求标头发送；请参阅 [事件关联属性](#event-correlation-attributes) 表了解何时存在。需要 Claude Code v2.1.214 或更高版本878* `client_request_id`：作为 `x-client-request-id` 请求头发送的客户端生成的 UUID；请参阅[事件关联属性](#event-correlation-attributes)表了解何时存在。需要 Claude Code v2.1.214 或更高版本

831* `speed`：`"fast"` 或 `"normal"`，指示是否启用了快速模式879* `speed`：`"fast"` 或 `"normal"`，指示快速模式是否活跃

832* `query_source`：发出请求的子系统，例如 `"repl_main_thread"`、`"compact"` 或子代理名称880* `query_source`：发出请求的子系统，例如 `"repl_main_thread"`、`"compact"` 或子代理名称

833* `effort`：应用于请求的 [努力级别](/docs/zh-CN/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。当模型不支持努力时不存在。881* `effort`：应用于请求的[努力级别](/docs/zh-CN/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。当 Claude Code 不发送努力级别时不存在，例如在不支持努力的模型上。

834* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：请求的技能、插件、代理和 MCP 归属。有关定义和编辑行为，请参阅 [成本计数器](#cost-counter)。882* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：请求的技能、插件、代理和 MCP 属性。有关定义和编辑行为，请参阅[成本计数器](#cost-counter)。

835 883

836<h4 id="api-error-event">884<h4 id="api-error-event">

837 API 错误事件885 API 错误事件

843 891

844**属性**：892**属性**：

845 893

846* 所有 [标准属性](#standard-attributes)894* 所有[标准属性](#standard-attributes)

847* `event.name`：`"api_error"`895* `event.name`：`"api_error"`

848* `event.timestamp`：ISO 8601 时间戳896* `event.timestamp`：ISO 8601 时间戳

849* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述897* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

850* `model`：使用的模型（例如，"claude-sonnet-5"）898* `model`：使用的模型（例如，"claude-sonnet-5"）

851* `error`：错误消息899* `error`：错误消息

852* `status_code`：HTTP 状态代码（数字形式）。对于非 HTTP 错误（例如连接失败）不存在。900* `status_code`：HTTP 状态代码作为数字。对于非 HTTP 错误（如连接失败）不存在。

853* `duration_ms`：请求持续时间（毫秒）901* `duration_ms`：请求持续时间（以毫秒为单位）

854* `attempt`：进行的总尝试次数，包括初始请求（`1` 表示没有发生重试）902* `attempt`：进行的总尝试次数，包括初始请求（`1` 表示没有重试发生）

855* `request_id`：来自响应的 `request-id` 标头的 Anthropic API 请求 ID，例如 `"req_011..."`。仅当 API 返回时存在。903* `request_id`：API 请求 ID，例如 `"req_011..."`，在[事件关联属性](#event-correlation-attributes)下描述。

856* `client_request_id`：客户端生成的 UUID，作为 `x-client-request-id` 请求标头发送。即使失败（例如超时或连接错误）从未产生服务器 `request_id`，也可用；请参阅 [事件关联属性](#event-correlation-attributes) 表了解何时存在。需要 Claude Code v2.1.214 或更高版本904* `client_request_id`：作为 `x-client-request-id` 请求头发送的客户端生成的 UUID。即使在超时或连接错误等失败从未产生服务器 `request_id` 时也可用；请参阅[事件关联属性](#event-correlation-attributes)表了解何时存在。需要 Claude Code v2.1.214 或更高版本

857* `speed`：`"fast"` 或 `"normal"`，指示是否启用了快速模式905* `speed`：`"fast"` 或 `"normal"`，指示快速模式是否活跃

858* `query_source`：发出请求的子系统，例如 `"repl_main_thread"`、`"compact"` 或子代理名称906* `query_source`：发出请求的子系统，例如 `"repl_main_thread"`、`"compact"` 或子代理名称

859* `effort`：应用于请求的 [努力级别](/docs/zh-CN/model-config#adjust-effort-level)。当模型不支持努力时不存在。907* `effort`：应用于请求的[努力级别](/docs/zh-CN/model-config#adjust-effort-level)。当 Claude Code 不发送努力级别时不存在，例如在不支持努力的模型上。

860* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：请求的技能、插件、代理和 MCP 归属。有关定义和编辑行为，请参阅 [成本计数器](#cost-counter)。908* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：请求的技能、插件、代理和 MCP 属性。有关定义和编辑行为，请参阅[成本计数器](#cost-counter)。

861 909

862<h4 id="api-refusal-event">910<h4 id="api-refusal-event">

863 API 拒绝事件911 API 拒绝事件

864</h4>912</h4>

865 913

866当 API 请求返回 `stop_reason: "refusal"` 时记录。拒绝在成功响应流上到达，而不是作为 HTTP 错误，因此 `api_error` 事件不会为它们触发。此事件让您跟踪拒绝频率并按与 `api_request` 和 `api_error` 相同的属性对拒绝进行分组。914当 API 请求返回 `stop_reason: "refusal"` 时记录。拒绝到达成功响应流而不是作为 HTTP 错误，因此 `api_error` 事件不会为它们触发。此事件让您跟踪拒绝频率并按与 `api_request` 和 `api_error` 相同的属性对拒绝进行分组。

867 915

868**事件名称**：`claude_code.api_refusal`916**事件名称**：`claude_code.api_refusal`

869 917

870**属性**：918**属性**：

871 919

872* 所有 [标准属性](#standard-attributes)920* 所有[标准属性](#standard-attributes)

873* `event.name`：`"api_refusal"`921* `event.name`：`"api_refusal"`

874* `event.timestamp`：ISO 8601 时间戳922* `event.timestamp`：ISO 8601 时间戳

875* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述923* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

876* `model`：来自请求的模型标识符924* `model`：来自请求的模型标识符

877* `request_id`：来自响应的 `request-id` 标头的 Anthropic API 请求 ID，例如 `"req_011..."`。仅当 API 返回时存在。925* `request_id`：API 请求 ID，例如 `"req_011..."`，在[事件关联属性](#event-correlation-attributes)下描述。

878* `query_source`：发出请求的子系统，例如 `"repl_main_thread"`、`"compact"` 或子代理名称。有关定义，请参阅 [`api_request`](#api-request-event)。926* `query_source`：发出请求的子系统，例如 `"repl_main_thread"`、`"compact"` 或子代理名称。有关定义，请参阅 [`api_request`](#api-request-event)。

879* `speed`：当 [快速模式](/docs/zh-CN/fast-mode) 活跃时为 `"fast"`，或 `"normal"`927* `speed`：当[快速模式](/docs/zh-CN/fast-mode)活跃时为 `"fast"`，或 `"normal"`

880* `attempt`：重试尝试次数。第一次尝试是 `1`。928* `attempt`：重试尝试号。第一次尝试是 `1`。

881* `effort`：应用于请求的 [努力级别](/docs/zh-CN/model-config#adjust-effort-level)。当模型不支持努力时不存在。929* `effort`：应用于请求的[努力级别](/docs/zh-CN/model-config#adjust-effort-level)。当 Claude Code 不发送努力级别时不存在，例如在不支持努力的模型上。

882* `server_fallback_hop`：当 API 的服务器端模型回退已在不同模型上重试此拒绝时为 `true`，因此用户没有看到此特定拒绝。当请求以拒绝结束时为 `false`。单个轮次可以发出 `true` hop 事件和稍后的 `false` 最终事件，当回退模型也拒绝时。930* `server_fallback_hop`：当 API 的服务器端模型回退已经在不同的模型上重试此拒绝时为 `true`，因此用户没有看到此特定拒绝。当请求以拒绝结束时为 `false`。单个轮次可以发出一个 `true` 跳跃事件和稍后的 `false` 最终事件，当回退模型也拒绝时。

883* `has_category`：当 API 响应携带 `stop_details.category` 为 `"cyber"`、`"bio"`、`"frontier_llm"` 或 `"reasoning_extraction"` 时为 `true`。当响应没有类别或值在该集合之外时为 `false`。当 `server_fallback_hop` 为 `true` 时不存在，因为 hop 块不携带 `stop_details`。931* `has_category`：当 API 响应携带 `stop_details.category` 为 `"cyber"`、`"bio"`、`"frontier_llm"` 或 `"reasoning_extraction"` 时为 `true`。当响应没有类别或值在该集合之外时为 `false`。当 `server_fallback_hop` 为 `true` 时不存在，因为跳跃块不携带 `stop_details`。

884* `has_explanation`：当 API 响应携带 `stop_details.explanation` 时为 `true`，否则为 `false`。当 `server_fallback_hop` 为 `true` 时不存在。932* `has_explanation`：当 API 响应携带 `stop_details.explanation` 时为 `true`，否则为 `false`。当 `server_fallback_hop` 为 `true` 时不存在。

885* `category`：来自 API 响应的 `stop_details.category` 值。`"cyber"`、`"bio"`、`"frontier_llm"` 或 `"reasoning_extraction"` 之一。仅当设置了 `OTEL_LOG_TOOL_DETAILS=1` 且 `has_category` 为 `true` 时存在。933* `category`：来自 API 响应的 `stop_details.category` 值。`"cyber"`、`"bio"`、`"frontier_llm"` 或 `"reasoning_extraction"` 之一。仅当设置了 `OTEL_LOG_TOOL_DETAILS=1` 且 `has_category` 为 `true` 时存在。

886* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：请求的技能、插件、代理和 MCP 归属。有关定义和编辑行为，请参阅 [成本计数器](#cost-counter)。934* `agent.name`、`skill.name`、`plugin.name`、`marketplace.name`、`mcp_server.name`、`mcp_tool.name`：请求的技能、插件、代理和 MCP 属性。有关定义和编辑行为，请参阅[成本计数器](#cost-counter)。

887 935

888<h4 id="api-request-body-event">936<h4 id="api-request-body-event">

889 API 请求主体事件937 API 请求体事件

890</h4>938</h4>

891 939

892当设置了 `OTEL_LOG_RAW_API_BODIES` 时，为每个 API 请求尝试记录。每次尝试发出一个事件，因此使用调整参数的重试各自产生自己的事件。940当设置了 `OTEL_LOG_RAW_API_BODIES` 时，为每个 API 请求尝试记录。每个尝试发出一个事件，因此使用调整参数的重试各自产生自己的事件。

893 941

894**事件名称**：`claude_code.api_request_body`942**事件名称**：`claude_code.api_request_body`

895 943

896**属性**：944**属性**：

897 945

898* 所有 [标准属性](#standard-attributes)946* 所有[标准属性](#standard-attributes)

899* `event.name`：`"api_request_body"`947* `event.name`：`"api_request_body"`

900* `event.timestamp`：ISO 8601 时间戳948* `event.timestamp`：ISO 8601 时间戳

901* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述949* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

902* `body`：JSON 序列化的 Messages API 请求参数（系统提示、消息、工具等），在内容限制处截断（默认 60 KB）。先前助手轮次中的扩展思考内容被编辑。仅在内联模式下发出（`OTEL_LOG_RAW_API_BODIES=1`）。950* `body`：JSON 序列化的 Messages API 请求参数，例如系统提示、消息和工具，在内容限制处截断（默认 60 KB）。先前助手轮次中的扩展思考内容被编辑。仅在内联模式下发出（`OTEL_LOG_RAW_API_BODIES=1`）。

903* `body_ref`：包含未截断主体的 `<dir>/<uuid>.request.json` 文件的绝对路径。仅在文件模式下发出（`OTEL_LOG_RAW_API_BODIES=file:<dir>`）。951* `body_ref`：包含未截断体的 `<dir>/<uuid>.request.json` 文件的绝对路径。仅在文件模式下发出（`OTEL_LOG_RAW_API_BODIES=file:<dir>`）。

904* `body_length`：未截断的主体长度。当 `OTEL_LOG_RAW_API_BODIES=file:<dir>` 时为 UTF-8 字节，或当 `=1` 时为 UTF-16 代码单位952* `body_length`：未截断的体长度。当 `OTEL_LOG_RAW_API_BODIES=file:<dir>` 时为 UTF-8 字节，或当 `=1` 时为 UTF-16 代码单位

905* `body_truncated`：当发生内联截断时为 `"true"`。在文件模式下和未发生截断时不存在。953* `body_truncated`：当发生内联截断时为 `"true"`。在文件模式下不存在，当没有截断发生时不存在。

906* `model`：来自请求参数的模型标识符954* `model`：来自请求参数的模型标识符

907* `query_source`：发出请求的子系统（例如，`"compact"`）955* `query_source`：发出请求的子系统（例如，`"compact"`）

908* `request_body_id`：UUID，标识此尝试的请求主体。成功的 [`api_response_body` 事件](#api-response-body-event) 携带相同的值，因此您可以将响应与产生它的确切请求配对。需要 Claude Code v2.1.274 或更高版本956* `request_body_id`：标识此尝试的请求体的 UUID。成功的尝试的 [`api_response_body` 事件](#api-response-body-event)携带相同的值，因此您可以将响应与产生它的确切请求配对。需要 Claude Code v2.1.274 或更高版本

909 957

910<h4 id="api-response-body-event">958<h4 id="api-response-body-event">

911 API 响应主体事件959 API 响应体事件

912</h4>960</h4>

913 961

914当设置了 `OTEL_LOG_RAW_API_BODIES` 时，为每个成功的 API 响应记录。962当设置了 `OTEL_LOG_RAW_API_BODIES` 时，为每个成功的 API 响应记录。

915 963

916在文件模式下（`OTEL_LOG_RAW_API_BODIES=file:<dir>`），Claude Code 还为每个成功的响应追加一行 JSON 到 `<dir>/index.jsonl`，包含字段 `timestamp`、`session_id`、`query_source`、`model`、`request_id`、`message_id`、`message_uuid`、`request_file` 和 `response_file`。读取它以找到给定记录消息后面的请求和响应文件，而无需查询您的遥测后端。索引文件需要 Claude Code v2.1.274 或更高版本。964在文件模式下（`OTEL_LOG_RAW_API_BODIES=file:<dir>`），Claude Code 还为每个成功的响应向 `<dir>/index.jsonl` 追加一个 JSON 行，包含字段 `timestamp`、`session_id`、`query_source`、`model`、`request_id`、`message_id`、`message_uuid`、`request_file` 和 `response_file`。读取它以找到给定记录消息后面的请求和响应文件，而无需查询您的遥测后端。索引文件需要 Claude Code v2.1.274 或更高版本。

917 965

918**事件名称**：`claude_code.api_response_body`966**事件名称**：`claude_code.api_response_body`

919 967

920**属性**：968**属性**：

921 969

922* 所有 [标准属性](#standard-attributes)970* 所有[标准属性](#standard-attributes)

923* `event.name`：`"api_response_body"`971* `event.name`：`"api_response_body"`

924* `event.timestamp`：ISO 8601 时间戳972* `event.timestamp`：ISO 8601 时间戳

925* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述973* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

926* `body`：JSON 序列化的 Messages API 响应（id、内容块、使用情况、停止原因），在内容限制处截断（默认 60 KB）。扩展思考内容被编辑。仅在内联模式下发出（`OTEL_LOG_RAW_API_BODIES=1`）。974* `body`：JSON 序列化的 Messages API 响应，包括 id、内容块、使用情况和停止原因，在内容限制处截断（默认 60 KB）。扩展思考内容被编辑。仅在内联模式下发出（`OTEL_LOG_RAW_API_BODIES=1`）。

927* `body_ref`：包含未截断主体的 `<dir>/<request_id>.response.json` 文件的绝对路径。仅在文件模式下发出（`OTEL_LOG_RAW_API_BODIES=file:<dir>`）。975* `body_ref`：包含未截断体的 `<dir>/<request_id>.response.json` 文件的绝对路径。仅在文件模式下发出（`OTEL_LOG_RAW_API_BODIES=file:<dir>`）。

928* `body_length`：未截断的主体长度。当 `OTEL_LOG_RAW_API_BODIES=file:<dir>` 时为 UTF-8 字节，或当 `=1` 时为 UTF-16 代码单位976* `body_length`：未截断的体长度。当 `OTEL_LOG_RAW_API_BODIES=file:<dir>` 时为 UTF-8 字节，或当 `=1` 时为 UTF-16 代码单位

929* `body_truncated`：当发生内联截断时为 `"true"`。在文件模式下和未发生截断时不存在。977* `body_truncated`：当发生内联截断时为 `"true"`。在文件模式下不存在，当没有截断发生时不存在。

930* `model`：模型标识符978* `model`：模型标识符

931* `query_source`：发出请求的子系统979* `query_source`：发出请求的子系统

932* `request_id`：来自响应的 `request-id` 标头的 Anthropic API 请求 ID，例如 `"req_011..."`。仅当 API 返回时存在。980* `request_id`：API 请求 ID，例如 `"req_011..."`，在[事件关联属性](#event-correlation-attributes)下描述。

933* `request_body_id`：此响应回答的 [`api_request_body` 事件](#api-request-body-event) 的 `request_body_id`。需要 Claude Code v2.1.274 或更高版本981* `request_body_id`：此响应回答的 [`api_request_body` 事件](#api-request-body-event)的 `request_body_id`。需要 Claude Code v2.1.274 或更高版本

934* `message.id`：API 分配给响应的消息 ID，响应主体的 `id` 字段。需要 Claude Code v2.1.274 或更高版本982* `message.id`：API 分配给响应的消息 ID，响应体的 `id` 字段。需要 Claude Code v2.1.274 或更高版本

935* `message.uuid`：响应的最终记录条目的 UUID。与 `request_body_id` 一起，它将记录消息链接到其后面的请求和响应主体。需要 Claude Code v2.1.274 或更高版本983* `message.uuid`：响应的最终记录条目的 UUID。与 `request_body_id` 一起，它将记录消息链接到其后面的请求和响应体。需要 Claude Code v2.1.274 或更高版本

936 984

937<h4 id="tool-decision-event">985<h4 id="tool-decision-event">

938 工具决策事件986 工具决策事件

939</h4>987</h4>

940 988

941当做出工具权限决策（接受/拒绝）时记录。989当进行工具权限决策时记录（接受/拒绝）。

942 990

943**事件名称**：`claude_code.tool_decision`991**事件名称**：`claude_code.tool_decision`

944 992

945**属性**：993**属性**：

946 994

947* 所有 [标准属性](#standard-attributes)995* 所有[标准属性](#standard-attributes)

948* `event.name`：`"tool_decision"`996* `event.name`：`"tool_decision"`

949* `event.timestamp`：ISO 8601 时间戳997* `event.timestamp`：ISO 8601 时间戳

950* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述998* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

951* `tool_name`：工具的名称（例如，"Read"、"Edit"、"Write"、"NotebookEdit"）999* `tool_name`：工具的名称（例如，"Read"、"Edit"、"Write"、"NotebookEdit"）

952* `tool_use_id`：此工具调用的唯一标识符。与传递给 hooks 的 `tool_use_id` 匹配，允许在 OTel 事件和 hook 捕获的数据之间进行关联。1000* `tool_use_id`：此工具调用的唯一标识符。与传递给钩子的 `tool_use_id` 匹配，允许 OTel 事件和钩子捕获数据之间的关联。

953* `decision`：`"accept"` 或 `"reject"`1001* `decision`：`"accept"` 或 `"reject"`

954* `tool_source`：始终存在。工具的来源，作为 CLI 创作值的闭集。需要 Claude Code v2.1.214 或更高版本1002* `tool_source`：始终存在。工具的来源，作为 CLI 创作值的闭集。需要 Claude Code v2.1.214 或更高版本

955 * `"builtin"`：CLI 自己的工具1003 * `"builtin"`：CLI 自己的工具

956 * `"mcp"`：MCP 服务器通常1004 * `"mcp"`：MCP 服务器通常

957 * `"sdk_host_builtin_mcp"`：内置于 Claude Desktop 本身的进程内服务器，在 Claude Desktop 拥有的会话中。Claude Desktop 拥有它从自己的入口点之一启动的会话，`claude-desktop`、`claude-desktop-3p` 或 `local-agent`，当该会话不是嵌套子会话时；嵌套会话（包括 Claude Code 本身生成的会话）将这些服务器报告为 `"mcp"`1005 * `"sdk_host_builtin_mcp"`：内置于 Claude Desktop 本身的进程内服务器，在 Claude Desktop 拥有的会话中。Claude Desktop 拥有它从自己的入口点之一启动的会话，`claude-desktop`、`claude-desktop-3p` 或 `local-agent`，当该会话不是嵌套子时；嵌套会话，包括 Claude Code 本身生成的会话，将这些服务器报告为 `"mcp"`

958* `source`：决策来源：1006* `source`：决策来自何处：

959 * `"config"`：基于项目设置、用户个人设置中的允许或拒绝规则、企业托管策略、`--allowedTools` 或 `--disallowedTools` 标志、活跃权限模式、来自同一交互式 CLI 会话中较早提示的会话范围授予或因为工具本身是安全的，自动决策而不提示。事件不指示这些来源中的哪一个匹配。Claude Code 也在权限提示请求本身失败时报告 `"config"`，例如当 Agent SDK 的 [`canUseTool`](/docs/zh-CN/agent-sdk/typescript#canusetool) 回调或 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 工具返回无效结果时，或当输入流在请求待处理时关闭时。在 v2.1.216 之前，Claude Code 将这些失败报告为 `"user_reject"`。1007 * `"config"`：自动决定而不提示，基于项目设置、用户个人设置中的允许或拒绝规则、企业管理策略、`--allowedTools` 或 `--disallowedTools` 标志、活跃权限模式、来自同一交互式 CLI 会话中较早提示的会话范围授予，或因为工具本质上是安全的。事件不指示这些源中的哪一个匹配。Claude Code 还在权限提示请求本身失败时报告 `"config"`，例如当代理 SDK 的 [`canUseTool`](/docs/zh-CN/agent-sdk/typescript#canusetool) 回调或 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 工具返回无效结果时，或当输入流在请求待处理时关闭时。在 v2.1.216 之前，Claude Code 将这些失败报告为 `"user_reject"`。

960 * `"hook"`：`PreToolUse` 或 `PermissionRequest` hook 返回了决策。1008 * `"hook"`：`PreToolUse` 或 `PermissionRequest` 钩子返回了决策。

961 * `"user_permanent"`：当用户在权限提示时选择"是，并且不要再问..."时发出，将允许规则保存到其个人设置。在交互式 CLI 中，仅为该选择本身发出；与保存规则匹配的后续调用发出 `"config"`。在 Agent SDK 或非交互式 `-p` 会话中，初始选择和后续规则匹配都发出 `"user_permanent"`。视为接受。1009 * `"user_permanent"`：当用户在权限提示处选择"是，以后不要再问..."时发出，这会将允许规则保存到其个人设置。在交互式 CLI 中，这仅对该选择本身发出；稍后与保存的规则匹配的调用发出 `"config"`。在代理 SDK 或非交互式 `-p` 会话中，初始选择和稍后的规则匹配都发出 `"user_permanent"`。视为接受。

962 * `"user_temporary"`：当用户在权限提示时选择"是"，或在文件编辑或读取提示上选择授予会话其余部分访问权限的选项时发出。在交互式 CLI 中，仅为该选择本身发出；与该会话范围授予匹配的后续调用发出 `"config"`。在 Agent SDK 或非交互式 `-p` 会话中，选择和后续匹配都发出 `"user_temporary"`。视为接受。1010 * `"user_temporary"`：当用户在权限提示处选择"是"进行一次性批准时发出，或在文件编辑或读取提示处选择了为会话其余部分授予访问权限的选项时发出。在交互式 CLI 中，这仅对选择本身发出；稍后由该会话范围授予允许的调用发出 `"config"`。在代理 SDK 或非交互式 `-p` 会话中，选择和稍后的匹配都发出 `"user_temporary"`。视为接受。

963 * `"user_abort"`：当用户关闭权限提示而不回答时发出。在 Agent SDK 和非交互式 `-p` 会话中，这包括在 `canUseTool` 或 `--permission-prompt-tool` 权限请求待处理时中断轮次；在 v2.1.216 之前，Claude Code 将该中断报告为 `"user_reject"`。视为拒绝。1011 * `"user_abort"`：当用户在不回答的情况下关闭权限提示时发出。在代理 SDK 和非交互式 `-p` 会话中，这包括在 `canUseTool` 或 `--permission-prompt-tool` 权限请求待处理时中断轮次；在 v2.1.216 之前，Claude Code 将该中断报告为 `"user_reject"`。视为拒绝。

964 * `"user_reject"`：当用户选择"否"时发出。在交互式 CLI 中，仅为该选择本身发出；与用户个人设置中的拒绝规则匹配的调用发出 `"config"`。在 Agent SDK 或非交互式 `-p` 会话中，与个人设置中的拒绝规则匹配的调用发出 `"user_reject"`。视为拒绝。1012 * `"user_reject"`：当用户在提示时选择"否"时发出。在交互式 CLI 中，这仅对该选择本身发出；与用户个人设置中的拒绝规则匹配的调用发出 `"config"`。在代理 SDK 或非交互式 `-p` 会话中，与个人设置中的拒绝规则匹配的调用发出 `"user_reject"`。视为拒绝。

965* `tool_parameters`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：包含工具特定参数的 JSON 字符串。形状与 [工具结果事件](#tool-result-event) 相同，除了执行后字段（例如 `git_commit_id`）。对于接受的调用，如果权限决策通过 `updatedInput` 重写工具输入，值可能与 `tool_result` 不同。使用此属性查看当 `decision` 为 `"reject"` 时拒绝了哪个命令。1013* `tool_parameters`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：包含工具特定参数的 JSON 字符串。与[工具结果事件](#tool-result-event)相同的形状，减去执行后字段如 `git_commit_id`。对于接受的调用，如果权限决策通过 `updatedInput` 重写工具输入，值可能与 `tool_result` 不同。使用此属性查看当 `decision` 为 `"reject"` 时哪个命令被拒绝。

966 * 对于 `"sdk_host_builtin_mcp"` 工具：即使 `OTEL_LOG_TOOL_DETAILS` 关闭，`mcp_server_name` 和 `mcp_tool_name` 也包含在内，因为主机应用定义这些名称；没有它们，对这些内置服务器之一的拒绝调用在默认流上将无法归属。对于用户配置的 MCP 服务器，事件的 `tool_name` 始终是字面 `"mcp_tool"`，服务器和工具名称仅在 `tool_parameters` 中出现，标志打开时；参数内容在任何地方都需要标志。需要 Claude Code v2.1.214 或更高版本1014 * 对于 `"sdk_host_builtin_mcp"` 工具：`mcp_server_name` 和 `mcp_tool_name` 即使在 `OTEL_LOG_TOOL_DETAILS` 关闭时也包含，因为主机应用定义这些名称；没有它们，对这些内置服务器之一的拒绝调用在默认流上将无法属性。对于用户配置的 MCP 服务器，事件的 `tool_name` 始终是字面 `"mcp_tool"`，服务器和工具名称仅在标志打开时出现在 `tool_parameters` 中；参数内容在任何地方都需要标志。需要 Claude Code v2.1.214 或更高版本

967 * 对于 Bash 工具：包括 `bash_command`、`full_command`、`timeout`、`description`、`dangerouslyDisableSandbox`。桌面应用的工作区 bash 工具也将 `tool_name` 报告为 `Bash`，但仅包括 `bash_command`、`full_command` 和 `timeout`1015 * 对于 Bash 工具：包括 `bash_command`、`full_command`、`timeout`、`description`、`dangerouslyDisableSandbox`。桌面应用的工作区 bash 工具也将 `tool_name` 报告为 `Bash`，但仅包括 `bash_command`、`full_command` 和 `timeout`

968 * 对于 MCP 工具：包括 `mcp_server_name`、`mcp_tool_name`1016 * 对于 MCP 工具：包括 `mcp_server_name`、`mcp_tool_name`

969 * 对于 Skill 工具：包括 `skill_name`1017 * 对于技能工具：包括 `skill_name`

970 * 对于 Agent 工具或旧版 Task 工具：包括 `subagent_type`1018 * 对于代理工具或旧版任务工具：包括 `subagent_type`

971 1019

972<h4 id="permission-mode-changed-event">1020<h4 id="permission-mode-changed-event">

973 权限模式更改事件1021 权限模式更改事件

974</h4>1022</h4>

975 1023

976当权限模式更改时记录，例如从 `Shift+Tab` 循环、退出 Plan Mode 或自动模式门控检查。1024当权限模式更改时记录，例如从 `Shift+Tab` 循环、退出计划模式或自动模式门检查。

977 1025

978**事件名称**：`claude_code.permission_mode_changed`1026**事件名称**：`claude_code.permission_mode_changed`

979 1027

980**属性**：1028**属性**：

981 1029

982* 所有 [标准属性](#standard-attributes)1030* 所有[标准属性](#standard-attributes)

983* `event.name`：`"permission_mode_changed"`1031* `event.name`：`"permission_mode_changed"`

984* `event.timestamp`：ISO 8601 时间戳1032* `event.timestamp`：ISO 8601 时间戳

985* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1033* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

986* `from_mode`：前一个权限模式，例如 `"default"`、`"plan"`、`"acceptEdits"`、`"auto"` 或 `"bypassPermissions"`1034* `from_mode`：前一个权限模式，例如 `"default"`、`"plan"`、`"acceptEdits"`、`"auto"` 或 `"bypassPermissions"`

987* `to_mode`：新权限模式1035* `to_mode`：新权限模式

988* `trigger`：导致更改的原因。`"shift_tab"`、`"exit_plan_mode"`、`"auto_gate_denied"` 或 `"auto_opt_in"` 之一。当转换来自 SDK 或桥接时不存在1036* `trigger`：导致更改的原因。`"shift_tab"`、`"exit_plan_mode"`、`"auto_gate_denied"` 或 `"auto_opt_in"` 之一。当转换源自 SDK 或桥时不存在。

989 1037

990<h4 id="auth-event">1038<h4 id="auth-event">

991 身份验证事件1039 认证事件

992</h4>1040</h4>

993 1041

994当 `/login` 或 `/logout` 完成时记录。1042当 `/login` 或 `/logout` 完成时记录。

997 1045

998**属性**：1046**属性**：

999 1047

1000* 所有 [标准属性](#standard-attributes)1048* 所有[标准属性](#standard-attributes)

1001* `event.name`：`"auth"`1049* `event.name`：`"auth"`

1002* `event.timestamp`：ISO 8601 时间戳1050* `event.timestamp`：ISO 8601 时间戳

1003* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1051* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1004* `action`：`"login"` 或 `"logout"`1052* `action`：`"login"` 或 `"logout"`

1005* `success`：`"true"` 或 `"false"`1053* `success`：`"true"` 或 `"false"`

1006* `auth_method`：身份验证方法，例如 `"oauth"`1054* `auth_method`：认证方法，例如 `"oauth"`

1007* `error_category`：操作失败时的分类错误类型。永远不包括原始错误消息1055* `error_category`：操作失败时的分类错误类型。原始错误消息永远不会包含

1008* `status_code`：操作因 HTTP 错误而失败时的 HTTP 状态代码（字符串形式）1056* `status_code`：操作因 HTTP 错误失败时的 HTTP 状态代码作为字符串

1009 1057

1010<h4 id="mcp-server-connection-event">1058<h4 id="mcp-server-connection-event">

1011 MCP 服务器连接事件1059 MCP 服务器连接事件

1017 1065

1018**属性**：1066**属性**：

1019 1067

1020* 所有 [标准属性](#standard-attributes)1068* 所有[标准属性](#standard-attributes)

1021* `event.name`：`"mcp_server_connection"`1069* `event.name`：`"mcp_server_connection"`

1022* `event.timestamp`：ISO 8601 时间戳1070* `event.timestamp`：ISO 8601 时间戳

1023* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1071* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1024* `status`：`"connected"`、`"failed"` 或 `"disconnected"`1072* `status`：`"connected"`、`"failed"` 或 `"disconnected"`

1025* `transport_type`：服务器传输，例如 `"stdio"`、`"sse"` 或 `"http"`1073* `transport_type`：服务器传输，例如 `"stdio"`、`"sse"` 或 `"http"`

1026* `server_scope`：服务器配置的范围，例如 `"user"`、`"project"` 或 `"local"`1074* `server_scope`：服务器配置的范围，例如 `"user"`、`"project"` 或 `"local"`

1027* `duration_ms`：连接尝试持续时间（毫秒）1075* `duration_ms`：连接尝试持续时间（以毫秒为单位）

1028* `error_code`：连接失败时的错误代码1076* `error_code`：连接失败时的错误代码

1029* `is_plugin`：当服务器由插件提供时为 `true`，否则为 `false`1077* `is_plugin`：当服务器由插件提供时为 `true`，否则为 `false`

1030* `plugin_id_hash`（当 `is_plugin` 为 `true` 时）：插件名称和市场的稳定哈希，用于按插件分组事件而不暴露名称。Claude Code 按 [插件已加载事件](#plugin-loaded-event) 下所述计算它1078* `plugin_id_hash`（当 `is_plugin` 为 `true` 时）：插件名称和市场的稳定哈希，用于按插件对事件进行分组而不暴露名称。Claude Code 按[插件加载事件](#plugin-loaded-event)下描述的方式计算它

1031* `plugin.name`（当 `is_plugin` 为 `true` 时）：提供服务器的插件的名称。对于第三方插件，除非 `OTEL_LOG_TOOL_DETAILS=1`，否则这是字面字符串 `"third-party"`；这可以保护第三方插件名称默认不出现在日志中。来自官方 Anthropic 来源的插件始终按名称标识。`plugin_id_hash` 和 `plugin.name` 属性流向您自己的监控后端，不会发送给 Anthropic1079* `plugin.name`（当 `is_plugin` 为 `true` 时）：提供服务器的插件的名称。对于第三方插件，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`，否则值为字面字符串 `"third-party"`；这保护第三方插件名称默认不出现在日志中。来自官方 Anthropic 源的插件始终按名称标识。`plugin_id_hash` 和 `plugin.name` 属性流向您自己的监控后端，不会发送给 Anthropic

1032* `server_name`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：配置的服务器名称1080* `server_name`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：配置的服务器名称

1033* `error`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：连接失败时的完整错误消息1081* `error`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：连接失败时的完整错误消息

1034 1082

1036 内部错误事件1084 内部错误事件

1037</h4>1085</h4>

1038 1086

1039当 Claude Code 捕获意外的内部错误时记录。仅记录错误类名和 errno 风格的代码。永远不包括错误消息和堆栈跟踪。在针对 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 运行或设置了 `DISABLE_ERROR_REPORTING` 时不会发出此事件。1087当 Claude Code 捕获意外的内部错误时记录。仅记录错误类名和 errno 风格代码。错误消息和堆栈跟踪永远不会包含。在针对 Amazon Bedrock、Google Cloud 的代理平台或 Microsoft Foundry 运行时，或当设置了 `DISABLE_ERROR_REPORTING` 时，不发出此事件。

1040 1088

1041**事件名称**：`claude_code.internal_error`1089**事件名称**：`claude_code.internal_error`

1042 1090

1043**属性**：1091**属性**：

1044 1092

1045* 所有 [标准属性](#standard-attributes)1093* 所有[标准属性](#standard-attributes)

1046* `event.name`：`"internal_error"`1094* `event.name`：`"internal_error"`

1047* `event.timestamp`：ISO 8601 时间戳1095* `event.timestamp`：ISO 8601 时间戳

1048* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1096* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1049* `error_name`：错误类名，例如 `"TypeError"` 或 `"SyntaxError"`1097* `error_name`：错误类名，例如 `"TypeError"` 或 `"SyntaxError"`

1050* `error_code`：Node.js errno 代码，例如错误上存在时的 `"ENOENT"`1098* `error_code`：Node.js errno 代码，例如 `"ENOENT"`（当存在于错误上时）

1051 1099

1052<h4 id="plugin-installed-event">1100<h4 id="plugin-installed-event">

1053 插件已安装事件1101 插件已安装事件

1059 1107

1060**属性**：1108**属性**：

1061 1109

1062* 所有 [标准属性](#standard-attributes)1110* 所有[标准属性](#standard-attributes)

1063* `event.name`：`"plugin_installed"`1111* `event.name`：`"plugin_installed"`

1064* `event.timestamp`：ISO 8601 时间戳1112* `event.timestamp`：ISO 8601 时间戳

1065* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1113* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1066* `marketplace.is_official`：如果市场是官方 Anthropic 市场，则为 `"true"`，否则为 `"false"`1114* `marketplace.is_official`：如果市场是官方 Anthropic 市场则为 `"true"`，否则为 `"false"`

1067* `install.trigger`：`"cli"` 或 `"ui"`1115* `install.trigger`：`"cli"` 或 `"ui"`

1068* `plugin.name`：已安装插件的名称。对于第三方市场，仅当 `OTEL_LOG_TOOL_DETAILS=1` 时才包含1116* `plugin.name`：已安装插件的名称。对于第三方市场，仅当设置了 `OTEL_LOG_TOOL_DETAILS=1` 时才包含

1069* `plugin.version`：在市场条目中声明时的插件版本。对于第三方市场，仅当 `OTEL_LOG_TOOL_DETAILS=1` 时才包含1117* `plugin.version`：在市场条目中声明时的插件版本。对于第三方市场，仅当设置了 `OTEL_LOG_TOOL_DETAILS=1` 时才包含

1070* `marketplace.name`：插件安装来源的市场。对于第三方市场，仅当 `OTEL_LOG_TOOL_DETAILS=1` 时才包含1118* `marketplace.name`：插件安装的市场。对于第三方市场，仅当设置了 `OTEL_LOG_TOOL_DETAILS=1` 时才包含

1071 1119

1072<h4 id="plugin-loaded-event">1120<h4 id="plugin-loaded-event">

1073 插件已加载事件1121 插件加载事件

1074</h4>1122</h4>

1075 1123

1076在会话开始时为每个启用的插件记录一次。使用此事件来清点您的整个队伍中哪些插件处于活跃状态，作为记录安装操作本身的 `plugin_installed` 的补充。1124在会话开始时为每个启用的插件记录一次。使用此事件来清点您的整个舰队中哪些插件处于活跃状态，作为记录安装操作本身的 `plugin_installed` 的补充。

1077 1125

1078**事件名称**：`claude_code.plugin_loaded`1126**事件名称**：`claude_code.plugin_loaded`

1079 1127

1080**属性**：1128**属性**：

1081 1129

1082* 所有 [标准属性](#standard-attributes)1130* 所有[标准属性](#standard-attributes)

1083* `event.name`：`"plugin_loaded"`1131* `event.name`：`"plugin_loaded"`

1084* `event.timestamp`：ISO 8601 时间戳1132* `event.timestamp`：ISO 8601 时间戳

1085* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1133* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1086* `plugin.name`：插件的名称。对于官方市场外和内置捆绑的插件，除非 `OTEL_LOG_TOOL_DETAILS=1`，否则值为 `"third-party"`1134* `plugin.name`：插件的名称。对于官方市场和内置捆绑之外的插件，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`，否则值为 `"third-party"`

1087* `marketplace.name`：插件安装来源的市场（已知时）。在与 `plugin.name` 相同的条件下编辑为 `"third-party"`1135* `marketplace.name`：插件安装的市场（已知时）。在与 `plugin.name` 相同的条件下编辑为 `"third-party"`

1088* `plugin.version`：来自插件清单的版本。仅当名称未被编辑且清单声明版本时才包含1136* `plugin.version`：来自插件清单的版本。仅当名称未被编辑且清单声明版本时才包含

1089* `plugin.scope`：插件的来源类别：`"official"`、`"community"`、`"org"`、`"user-local"` 或 `"default-bundle"`1137* `plugin.scope`：插件的来源类别：`"official"`、`"community"`、`"org"`、`"user-local"` 或 `"default-bundle"`

1090* `enabled_via`：插件如何被启用的方式：`"default-enable"`、`"org-policy"`、`"admin-install"`、`"seed-mount"` 或 `"user-install"`。值 `"admin-install"` 表示插件在 [**组织设置 > 插件和技能**](https://claude.ai/admin-settings/skills?tab=inventory) 中为您的组织设置为必需或自动安装。在 v2.1.246 之前，Claude Code 将这些插件报告为 `"user-install"` 或 `"seed-mount"`1138* `enabled_via`：插件如何被启用的方式：`"default-enable"`、`"org-policy"`、`"admin-install"`、`"seed-mount"` 或 `"user-install"`。`"admin-install"` 值表示插件在[**组织设置 > 插件和技能**](https://claude.ai/admin-settings/skills?tab=inventory)中为您的组织设置为必需或自动安装。在 v2.1.246 之前，Claude Code 将这些插件报告为 `"user-install"` 或 `"seed-mount"`

1091* `plugin_id_hash`：插件名称和市场的确定性哈希，仅发送到您配置的导出器。让您计算整个队伍中加载了多少个不同的第三方插件，而无需记录其名称。对于 [从 claude.ai 同步的插件](/docs/zh-CN/plugins/loading#synced-plugins)，Claude Code 使用插件名称与 claude.ai 为插件报告的市场名称进行哈希，或在其他情况下使用 `synced`。在 v2.1.246 之前，Claude Code 在哈希中没有使用 claude.ai 报告的市场名称1139* `plugin_id_hash`：插件名称和市场的确定性哈希，仅发送到您配置的导出器。让您计算整个舰队中加载的不同第三方插件，而无需记录其名称。对于[从 claude.ai 同步的插件](/docs/zh-CN/plugins/loading#synced-plugins)，Claude Code 使用 claude.ai 为插件报告的市场名称或 `synced` 哈希插件名称。在 v2.1.246 之前，Claude Code 在哈希中没有使用 claude.ai 报告的市场名称

1092* `has_hooks`：插件是否贡献 hooks1140* `has_hooks`：插件是否贡献钩子

1093* `has_mcp`：插件是否贡献 MCP 服务器1141* `has_mcp`：插件是否贡献 MCP 服务器

1094* `host_owned_mcp`：当 SDK 主机管理此插件的 MCP 连接且 Claude Code 跳过读取插件的 MCP 服务器配置时为 `true`，否则为 `false`。需要 Claude Code v2.1.172 或更高版本1142* `host_owned_mcp`：当 SDK 主机管理此插件的 MCP 连接且 Claude Code 跳过读取插件的 MCP 服务器配置时为 `true`，否则为 `false`。需要 Claude Code v2.1.172 或更高版本

1095* `skill_path_count`：插件声明的技能目录数1143* `skill_path_count`：插件声明的技能目录数

1096* `command_path_count`：插件声明的命令目录数1144* `command_path_count`：插件声明的命令目录数

1097* `agent_path_count`：插件声明的代理目录数1145* `agent_path_count`：插件声明的代理目录数

1098* `safe_mode`：当会话使用 [`--safe-mode`](/docs/zh-CN/cli-reference) 启动时为 `"true"`，否则为 `"false"`。在安全模式下，此事件仅报告配置的清单；插件的命令、技能、hooks 和 MCP 服务器不加载。需要 Claude Code v2.1.169 或更高版本1146* `safe_mode`：当会话以 [`--safe-mode`](/docs/zh-CN/cli-reference) 启动时为 `"true"`，否则为 `"false"`。在安全模式下，此事件仅报告配置的清单；插件的命令、技能、钩子和 MCP 服务器不加载。需要 Claude Code v2.1.169 或更高版本

1099 1147

1100<h4 id="skill-activated-event">1148<h4 id="skill-activated-event">

1101 技能激活事件1149 技能激活事件

1102</h4>1150</h4>

1103 1151

1104当调用技能时记录，无论 Claude 是通过 Skill 工具调用它还是您将其作为 `/` 命令运行。1152当技能被调用时记录，无论 Claude 是通过技能工具调用它还是您将其作为 `/` 命令运行。

1105 1153

1106**事件名称**：`claude_code.skill_activated`1154**事件名称**：`claude_code.skill_activated`

1107 1155

1108**属性**：1156**属性**：

1109 1157

1110* 所有 [标准属性](#standard-attributes)1158* 所有[标准属性](#standard-attributes)

1111* `event.name`：`"skill_activated"`1159* `event.name`：`"skill_activated"`

1112* `event.timestamp`：ISO 8601 时间戳1160* `event.timestamp`：ISO 8601 时间戳

1113* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1161* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1114* `skill.name`：技能的名称。对于用户定义和第三方插件技能，除非 `OTEL_LOG_TOOL_DETAILS=1`，否则值为占位符 `"custom_skill"`1162* `skill.name`：技能的名称。对于用户定义和第三方插件技能，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`，否则值为占位符 `"custom_skill"`

1115* `invocation_trigger`：技能的触发方式（`"user-slash"`、`"claude-proactive"` 或 `"nested-skill"`）1163* `invocation_trigger`：技能如何被触发（`"user-slash"`、`"claude-proactive"` 或 `"nested-skill"`）

1116* `skill.source`：技能加载的位置（例如，`"bundled"`、`"userSettings"`、`"projectSettings"`、`"plugin"`）1164* `skill.source`：技能从何处加载（例如，`"bundled"`、`"userSettings"`、`"projectSettings"`、`"plugin"`）

1117* `skill.kind`：当技能是工作流技能时为 `"workflow"`。否则不存在1165* `skill.kind`：当技能是工作流技能时为 `"workflow"`。否则不存在

1118* `plugin.name`（当 `OTEL_LOG_TOOL_DETAILS=1` 或插件来自官方市场时）：当技能由插件提供时的拥有插件的名称1166* `plugin.name`（当 `OTEL_LOG_TOOL_DETAILS=1` 或插件来自官方市场时）：当技能由插件提供时的所有者插件的名称

1119* `marketplace.name`（当 `OTEL_LOG_TOOL_DETAILS=1` 或插件来自官方市场时）：当技能由插件提供时，拥有插件安装来源的市场1167* `marketplace.name`（当 `OTEL_LOG_TOOL_DETAILS=1` 或插件来自官方市场时）：当技能由插件提供时，所有者插件安装的市场

1120 1168

1121<h4 id="at-mention-event">1169<h4 id="at-mention-event">

1122 @提及事件1170 @提及事件

1123</h4>1171</h4>

1124 1172

1125当 Claude Code 在提示中解析 `@`-提及时记录。并非每个提及都会发出事件：早期退出路径（例如权限拒绝、超大文件、PDF 参考附件和目录列表失败）返回而不记录。1173当 Claude Code 解析提示中的 `@` 提及时记录。并非每个提及都发出事件：早期退出路径如权限拒绝、超大文件、PDF 参考附件和目录列表失败返回而不记录。

1126 1174

1127**事件名称**：`claude_code.at_mention`1175**事件名称**：`claude_code.at_mention`

1128 1176

1129**属性**：1177**属性**：

1130 1178

1131* 所有 [标准属性](#standard-attributes)1179* 所有[标准属性](#standard-attributes)

1132* `event.name`：`"at_mention"`1180* `event.name`：`"at_mention"`

1133* `event.timestamp`：ISO 8601 时间戳1181* `event.timestamp`：ISO 8601 时间戳

1134* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1182* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1135* `mention_type`：提及的类型（`"file"`、`"directory"`、`"agent"`、`"mcp_resource"`、`"peer"`）。值 `"peer"` 表示您提及了 [您的其他 Claude Code 会话之一](/docs/zh-CN/cross-session-messaging)。需要 Claude Code v2.1.232 或更高版本1183* `mention_type`：提及的类型（`"file"`、`"directory"`、`"agent"`、`"mcp_resource"`、`"peer"`）。`"peer"` 值表示您提及了[您的其他 Claude Code 会话之一](/docs/zh-CN/cross-session-messaging)。需要 Claude Code v2.1.232 或更高版本

1136* `success`：提及是否成功解析（`"true"` 或 `"false"`）1184* `success`：提及是否成功解析（`"true"` 或 `"false"`）

1137 1185

1138<h4 id="api-retries-exhausted-event">1186<h4 id="api-retries-exhausted-event">

1145 1193

1146**属性**：1194**属性**：

1147 1195

1148* 所有 [标准属性](#standard-attributes)1196* 所有[标准属性](#standard-attributes)

1149* `event.name`：`"api_retries_exhausted"`1197* `event.name`：`"api_retries_exhausted"`

1150* `event.timestamp`：ISO 8601 时间戳1198* `event.timestamp`：ISO 8601 时间戳

1151* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1199* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1152* `model`：使用的模型1200* `model`：使用的模型

1153* `error`：最终错误消息1201* `error`：最终错误消息

1154* `status_code`：HTTP 状态代码（数字形式）。对于非 HTTP 错误不存在。1202* `status_code`：HTTP 状态代码作为数字。对于非 HTTP 错误不存在。

1155* `total_attempts`：进行的总尝试次数1203* `total_attempts`：进行的总尝试次数

1156* `total_retry_duration_ms`：所有尝试的总实际时钟时间1204* `total_retry_duration_ms`：所有尝试中的总挂钟时间

1157* `speed`：`"fast"` 或 `"normal"`1205* `speed`：`"fast"` 或 `"normal"`

1158 1206

1159<h4 id="hook-registered-event">1207<h4 id="hook-registered-event">

1160 Hook 已注册事件1208 钩子已注册事件

1161</h4>1209</h4>

1162 1210

1163在会话开始时为每个配置的 hook 记录一次。使用此事件来清点您的整个队伍中哪些 hooks 处于活跃状态，作为每次执行 `hook_execution_start` 和 `hook_execution_complete` 事件的补充。1211在会话开始时为每个配置的钩子记录一次。使用此事件来清点您的整个舰队中哪些钩子处于活跃状态，作为每次执行 `hook_execution_start` 和 `hook_execution_complete` 事件的补充。

1164 1212

1165**事件名称**：`claude_code.hook_registered`1213**事件名称**：`claude_code.hook_registered`

1166 1214

1167**属性**：1215**属性**：

1168 1216

1169* 所有 [标准属性](#standard-attributes)1217* 所有[标准属性](#standard-attributes)

1170* `event.name`：`"hook_registered"`1218* `event.name`：`"hook_registered"`

1171* `event.timestamp`：ISO 8601 时间戳1219* `event.timestamp`：ISO 8601 时间戳

1172* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1220* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1173* `hook_event`：hook 事件类型，例如 `"PreToolUse"` 或 `"PostToolUse"`1221* `hook_event`：钩子事件类型，例如 `"PreToolUse"` 或 `"PostToolUse"`

1174* `hook_type`：hook 实现类型：`"command"`、`"prompt"`、`"mcp_tool"`、`"http"` 或 `"agent"`1222* `hook_type`：钩子实现类型：`"command"`、`"prompt"`、`"mcp_tool"`、`"http"` 或 `"agent"`

1175* `hook_source`：hook 定义的位置：`"userSettings"`、`"projectSettings"`、`"localSettings"`、`"flagSettings"`、`"policySettings"` 或 `"pluginHook"`1223* `hook_source`：钩子定义的位置：`"userSettings"`、`"projectSettings"`、`"localSettings"`、`"flagSettings"`、`"policySettings"` 或 `"pluginHook"`

1176* `safe_mode`：当会话使用 [`--safe-mode`](/docs/zh-CN/cli-reference) 启动时为 `"true"`，否则为 `"false"`。需要 Claude Code v2.1.169 或更高版本1224* `safe_mode`：当会话以 [`--safe-mode`](/docs/zh-CN/cli-reference) 启动时为 `"true"`，否则为 `"false"`。需要 Claude Code v2.1.169 或更高版本

1177* `hook_matcher`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：hook 配置中的匹配器字符串（设置时）1225* `hook_matcher`（当 `OTEL_LOG_TOOL_DETAILS=1` 时）：钩子配置中的匹配器字符串（当设置了一个时）

1178* `plugin.name`（当 `hook_source` 是 `"pluginHook"` 时）：贡献插件的名称。对于官方市场外和内置捆绑的插件，除非 `OTEL_LOG_TOOL_DETAILS=1`，否则值为 `"third-party"`1226* `plugin.name`（当 `hook_source` 为 `"pluginHook"` 时）：贡献插件的名称。对于官方市场和内置捆绑之外的插件，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`，否则值为 `"third-party"`

1179* `plugin_id_hash`（当 `hook_source` 是 `"pluginHook"` 时）：插件名称和市场的确定性哈希，仅发送到您配置的导出器。让您计算不同的贡献插件数而无需记录其名称。Claude Code 按 [插件已加载事件](#plugin-loaded-event) 下所述计算它1227* `plugin_id_hash`（当 `hook_source` 为 `"pluginHook"` 时）：插件名称和市场的确定性哈希，仅发送到您配置的导出器。让您计算不同的贡献插件而无需记录其名称。Claude Code 按[插件加载事件](#plugin-loaded-event)下描述的方式计算它

1180 1228

1181<h4 id="hook-execution-start-event">1229<h4 id="hook-execution-start-event">

1182 Hook 执行开始事件1230 钩子执行开始事件

1183</h4>1231</h4>

1184 1232

1185当一个或多个 hooks 开始为 hook 事件执行时记录。1233当一个或多个钩子开始为钩子事件执行时记录。

1186 1234

1187**事件名称**：`claude_code.hook_execution_start`1235**事件名称**：`claude_code.hook_execution_start`

1188 1236

1189**属性**：1237**属性**：

1190 1238

1191* 所有 [标准属性](#standard-attributes)1239* 所有[标准属性](#standard-attributes)

1192* `event.name`：`"hook_execution_start"`1240* `event.name`：`"hook_execution_start"`

1193* `event.timestamp`：ISO 8601 时间戳1241* `event.timestamp`：ISO 8601 时间戳

1194* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1242* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1195* `hook_event`：Hook 事件类型，例如 `"PreToolUse"` 或 `"PostToolUse"`1243* `hook_event`：钩子事件类型，例如 `"PreToolUse"` 或 `"PostToolUse"`

1196* `hook_name`：完整 hook 名称，包括匹配器，例如 `"PreToolUse:Write"`1244* `hook_name`：完整钩子名称包括匹配器，例如 `"PreToolUse:Write"`

1197* `num_hooks`：匹配 hook 命令的数量1245* `num_hooks`：匹配钩子命令的数量

1198* `managed_only`：当仅允许托管策略 hooks 时为 `"true"`1246* `managed_only`：当仅允许管理策略钩子时为 `"true"`

1199* `hook_source`：`"policySettings"` 或 `"merged"`1247* `hook_source`：`"policySettings"` 或 `"merged"`

1200* `safe_mode`：当会话使用 [`--safe-mode`](/docs/zh-CN/cli-reference) 启动时为 `"true"`，否则为 `"false"`。需要 Claude Code v2.1.169 或更高版本1248* `safe_mode`：当会话以 [`--safe-mode`](/docs/zh-CN/cli-reference) 启动时为 `"true"`，否则为 `"false"`。需要 Claude Code v2.1.169 或更高版本

1201* `hook_definitions`：JSON 序列化的 hook 配置。仅当启用了详细的测试版跟踪和 `OTEL_LOG_TOOL_DETAILS=1` 时才包含1249* `hook_definitions`：JSON 序列化的钩子配置。仅当启用了详细的 beta 跟踪和 `OTEL_LOG_TOOL_DETAILS=1` 时才包含

1202 1250

1203<h4 id="hook-execution-complete-event">1251<h4 id="hook-execution-complete-event">

1204 Hook 执行完成事件1252 钩子执行完成事件

1205</h4>1253</h4>

1206 1254

1207当 hook 事件的所有 hooks 完成时记录。1255当钩子事件的所有钩子完成时记录。

1208 1256

1209**事件名称**：`claude_code.hook_execution_complete`1257**事件名称**：`claude_code.hook_execution_complete`

1210 1258

1211**属性**：1259**属性**：

1212 1260

1213* 所有 [标准属性](#standard-attributes)1261* 所有[标准属性](#standard-attributes)

1214* `event.name`：`"hook_execution_complete"`1262* `event.name`：`"hook_execution_complete"`

1215* `event.timestamp`：ISO 8601 时间戳1263* `event.timestamp`：ISO 8601 时间戳

1216* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1264* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1217* `hook_event`：Hook 事件类型1265* `hook_event`：钩子事件类型

1218* `hook_name`：完整 hook 名称，包括匹配器1266* `hook_name`：完整钩子名称包括匹配器

1219* `num_hooks`：匹配 hook 命令的数量1267* `num_hooks`：匹配钩子命令的数量

1220* `num_success`：成功完成的计数1268* `num_success`：成功完成的计数

1221* `num_blocking`：返回阻止决策的计数1269* `num_blocking`：返回阻止决策的计数

1222* `num_non_blocking_error`：失败但未阻止的计数1270* `num_non_blocking_error`：失败而不阻止的计数

1223* `num_cancelled`：在完成前取消的计数1271* `num_cancelled`：在完成前取消的计数

1224* `total_duration_ms`：所有匹配 hooks 的实际时钟持续时间1272* `total_duration_ms`：所有匹配钩子的挂钟持续时间

1225* `stdout_chars`：成功的匹配 hooks 的 stdout 总字符数。需要 Claude Code v2.1.280 或更高版本1273* `stdout_chars`：成功的匹配钩子中的 stdout 总字符数。需要 Claude Code v2.1.280 或更高版本

1226* `additional_context_chars`：匹配 hooks 返回的 `additionalContext` 的总字符数。需要 Claude Code v2.1.280 或更高版本1274* `additional_context_chars`：匹配钩子返回的 `additionalContext` 的总字符数。需要 Claude Code v2.1.280 或更高版本

1227* `system_message_chars`：匹配 hooks 返回的 `systemMessage` 的总字符数。需要 Claude Code v2.1.280 或更高版本1275* `system_message_chars`：匹配钩子返回的 `systemMessage` 的总字符数。需要 Claude Code v2.1.280 或更高版本

1228* `initial_user_message_chars`：匹配 hooks 返回的 `initialUserMessage` 的总字符数。需要 Claude Code v2.1.280 或更高版本1276* `initial_user_message_chars`：匹配钩子返回的 `initialUserMessage` 的总字符数。需要 Claude Code v2.1.280 或更高版本

1229* `num_outputs_persisted`：超过 [10,000 字符上限](/docs/zh-CN/hooks#json-output) 的 hook 输出数，Claude Code 保存到文件。需要 Claude Code v2.1.280 或更高版本1277* `num_outputs_persisted`：超过[10,000 字符上限](/docs/zh-CN/hooks#json-output)的钩子输出数，Claude Code 保存到文件。需要 Claude Code v2.1.280 或更高版本

1230* `managed_only`：当仅允许托管策略 hooks 时为 `"true"`1278* `managed_only`：当仅允许管理策略钩子时为 `"true"`

1231* `hook_source`：`"policySettings"` 或 `"merged"`1279* `hook_source`：`"policySettings"` 或 `"merged"`

1232* `safe_mode`：当会话使用 [`--safe-mode`](/docs/zh-CN/cli-reference) 启动时为 `"true"`，否则为 `"false"`。需要 Claude Code v2.1.169 或更高版本1280* `safe_mode`：当会话以 [`--safe-mode`](/docs/zh-CN/cli-reference) 启动时为 `"true"`，否则为 `"false"`。需要 Claude Code v2.1.169 或更高版本

1233* `hook_definitions`：JSON 序列化的 hook 配置。仅当启用了详细的测试版跟踪和 `OTEL_LOG_TOOL_DETAILS=1` 时才包含1281* `hook_definitions`：JSON 序列化的钩子配置。仅当启用了详细的 beta 跟踪和 `OTEL_LOG_TOOL_DETAILS=1` 时才包含

1234 1282

1235<h4 id="hook-plugin-metrics-event">1283<h4 id="hook-plugin-metrics-event">

1236 Hook 插件指标事件1284 钩子插件指标事件

1237</h4>1285</h4>

1238 1286

1239当官方市场插件 hook 发出每次调用指标时记录。仅从官方 Anthropic 市场安装的插件可以发出这些。第三方市场插件和用户配置的 hooks 不会发出到此事件。使用此事件从您自己的可观测性堆栈监控插件行为，例如查找率、成本和持续时间。1287当官方市场插件钩子发出每次调用指标时记录。仅从官方 Anthropic 市场安装的插件可以发出这些。第三方市场插件和用户配置的钩子不发出到此事件。使用此事件从您自己的可观测性堆栈监控插件行为，例如查找率、成本和持续时间。

1240 1288

1241**事件名称**：`claude_code.hook_plugin_metrics`1289**事件名称**：`claude_code.hook_plugin_metrics`

1242 1290

1243**属性**：1291**属性**：

1244 1292

1245* 所有 [标准属性](#standard-attributes)1293* 所有[标准属性](#standard-attributes)

1246* `event.name`：`"hook_plugin_metrics"`1294* `event.name`：`"hook_plugin_metrics"`

1247* `event.timestamp`：ISO 8601 时间戳1295* `event.timestamp`：ISO 8601 时间戳

1248* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1296* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1249* `plugin_id`：`<name>@<marketplace>` 形式的插件标识符1297* `plugin_id`：`<name>@<marketplace>` 形式的插件标识符

1250* `hook_event`：发出指标的 hook 事件类型1298* `hook_event`：发出指标的钩子事件类型

1251* 最多 20 个插件发出的指标键。名称匹配 `^[a-z][a-z0-9_]{0,39}$`。值为布尔值或数字。1299* 最多 20 个插件发出的指标键。名称匹配 `^[a-z][a-z0-9_]{0,39}$`。值是布尔值或数字。

1252 1300

1253<h4 id="compaction-event">1301<h4 id="compaction-event">

1254 压缩事件1302 压缩事件

1260 1308

1261**属性**：1309**属性**：

1262 1310

1263* 所有 [标准属性](#standard-attributes)1311* 所有[标准属性](#standard-attributes)

1264* `event.name`：`"compaction"`1312* `event.name`：`"compaction"`

1265* `event.timestamp`：ISO 8601 时间戳1313* `event.timestamp`：ISO 8601 时间戳

1266* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1314* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1267* `trigger`：`"auto"` 或 `"manual"`1315* `trigger`：`"auto"` 或 `"manual"`

1268* `success`：`"true"` 或 `"false"`1316* `success`：`"true"` 或 `"false"`

1269* `duration_ms`：压缩持续时间1317* `duration_ms`：压缩持续时间

1270* `pre_tokens`：压缩前的近似令牌计数1318* `pre_tokens`：压缩前的近似令牌计数

1271* `post_tokens`：压缩后的近似令牌计数1319* `post_tokens`：压缩后的近似令牌计数

1272* `error`：压缩失败时的错误消息1320* `error`：压缩失败时的错误消息

1273* `precompute_reuse`：仅当 `trigger` 为 `"manual"` 时设置。自动压缩可以在上下文窗口填满之前在后台准备摘要，此属性记录 `/compact` 是否重用了该准备的摘要。`"hit"` 表示它被重用；`"miss_custom_instructions"`、`"miss_hook"` 和 `"miss_not_ready"` 给出了计算新摘要的原因。需要 Claude Code v2.1.153 或更高版本1321* `precompute_reuse`：仅当 `trigger` 为 `"manual"` 时设置。自动压缩可以在上下文窗口填满之前在后台准备摘要，此属性记录 `/compact` 是否重用了该准备的摘要。`"hit"` 表示它被重用；`"miss_custom_instructions"`、`"miss_hook"` 和 `"miss_not_ready"` 给出改为计算新摘要的原因。需要 Claude Code v2.1.153 或更高版本

1274 1322

1275<h4 id="subagent-completed-event">1323<h4 id="subagent-completed-event">

1276 子代理完成事件1324 子代理完成事件

1277</h4>1325</h4>

1278 1326

1279当 [子代理](/docs/zh-CN/sub-agents) 完成并将其结果返回到启动它的对话时记录。使用它按子代理类型汇总工具使用和运行时间；对于令牌或成本汇总，使用 [令牌计数器](#token-counter) 和 [成本计数器](#cost-counter) 过滤到 `query_source` `"subagent"`，因为此事件的 `total_tokens` 仅涵盖最终请求。`"subagent"` 类别也计算来自代理 hooks 的请求，这些不发出子代理事件。1327当[子代理](/docs/zh-CN/sub-agents)完成并将其结果返回到启动它的对话时记录。使用它按子代理类型汇总工具使用和运行时间；对于令牌或成本汇总，使用按 `query_source` `"subagent"` 过滤的[令牌计数器](#token-counter)和[成本计数器](#cost-counter)，因为此事件的 `total_tokens` 仅涵盖最终请求。`"subagent"` 类别也计算来自代理钩子的请求，它不发出子代理事件。

1280 1328

1281**事件名称**：`claude_code.subagent_completed`1329**事件名称**：`claude_code.subagent_completed`

1282 1330

1283**属性**：1331**属性**：

1284 1332

1285* 所有 [标准属性](#standard-attributes)1333* 所有[标准属性](#standard-attributes)

1286* `event.name`：`"subagent_completed"`1334* `event.name`：`"subagent_completed"`

1287* `event.timestamp`：ISO 8601 时间戳1335* `event.timestamp`：ISO 8601 时间戳

1288* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1336* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1289* `agent_type`：子代理类型。内置代理名称和来自官方市场插件的代理按原样出现；其他代理名称被替换为 `"custom"`，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`1337* `agent_type`：子代理类型。内置代理名称和来自官方市场插件的代理逐字显示；其他代理名称被替换为 `"custom"`，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`

1290* `agent.source`：代理定义来自的位置：`built-in`、`plugin` 或定义自定义代理的设置来源，例如 `userSettings` 或 `projectSettings`1338* `agent.source`：代理定义来自何处：`built-in`、`plugin` 或定义自定义代理的设置源，例如 `userSettings` 或 `projectSettings`

1291* `is_built_in`：子代理是否是内置代理类型1339* `is_built_in`：子代理是否是内置代理类型

1292* `is_async`：子代理是否在 [后台](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background) 运行1340* `is_async`：子代理是否在[后台](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)运行

1293* `total_tokens`：子代理最终 API 请求的令牌足迹：该单个请求的输入、缓存创建、缓存读取和输出令牌，大致是子代理在完成时的上下文大小。不是整个运行的总和1341* `total_tokens`：子代理最终 API 请求的令牌足迹：该一个请求的输入、缓存创建、缓存读取和输出令牌，大致是子代理在完成时的上下文大小。不是整个运行的总和

1294* `total_tool_uses`：子代理在整个运行中进行的工具调用数1342* `total_tool_uses`：子代理在整个运行中进行的工具调用数

1295* `duration_ms`：运行时间（毫秒）1343* `duration_ms`：运行时间（以毫秒为单位）

1296* `model`：子代理被解析为运行的模型1344* `model`：子代理被解析为运行的模型

1297* `final_model`：产生子代理最终响应的模型，在中途切换（例如回退）后与 `model` 不同。需要 Claude Code v2.1.212 或更高版本1345* `final_model`：产生子代理最终响应的模型，在中途切换（如回退）后与 `model` 不同。需要 Claude Code v2.1.212 或更高版本

1298* `model_swapped`：是否有多个模型为子代理的请求提供服务。需要 Claude Code v2.1.212 或更高版本1346* `model_swapped`：是否有多个模型为子代理的请求提供服务。需要 Claude Code v2.1.212 或更高版本

1299* `plugin_id_hash`、`plugin.name`：对于插件提供的代理存在。官方市场插件名称按原样出现；其他插件名称被替换为 `"third-party"`，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`1347* `plugin_id_hash`、`plugin.name`：对于插件提供的代理存在。官方市场插件名称逐字显示；其他插件名称被替换为 `"third-party"`，除非设置了 `OTEL_LOG_TOOL_DETAILS=1`

1300 1348

1301<h4 id="feedback-survey-event">1349<h4 id="feedback-survey-event">

1302 反馈调查事件1350 反馈调查事件

1303</h4>1351</h4>

1304 1352

1305当显示或回答会话质量调查时记录。请参阅 [会话质量调查](/docs/zh-CN/data-usage#session-quality-surveys) 了解调查收集的内容以及如何控制它们。1353当显示或回答会话质量调查时记录。请参阅[会话质量调查](/docs/zh-CN/data-usage#session-quality-surveys)了解调查收集的内容以及如何控制它们。

1306 1354

1307**事件名称**：`claude_code.feedback_survey`1355**事件名称**：`claude_code.feedback_survey`

1308 1356

1309**属性**：1357**属性**：

1310 1358

1311* 所有 [标准属性](#standard-attributes)1359* 所有[标准属性](#standard-attributes)

1312* `event.name`：`"feedback_survey"`1360* `event.name`：`"feedback_survey"`

1313* `event.timestamp`：ISO 8601 时间戳1361* `event.timestamp`：ISO 8601 时间戳

1314* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1362* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1315* `event_type`：调查生命周期事件，例如 `"appeared"`、`"responded"` 或 `"transcript_prompt_appeared"`1363* `event_type`：调查生命周期事件，例如 `"appeared"`、`"responded"` 或 `"transcript_prompt_appeared"`

1316* `appearance_id`：唯一 ID，链接为一个调查实例发出的事件1364* `appearance_id`：链接为一个调查实例发出的事件的唯一 ID

1317* `survey_type`：哪个调查产生了事件。`"session"` 是"Claude 做得怎么样？"评分提示1365* `survey_type`：哪个调查产生了事件。`"session"` 是"Claude 做得怎么样？"评分提示

1318* `response`：用户在 `responded` 事件上的选择1366* `response`：用户在 `responded` 事件上的选择

1319* `enabled_via_override`：当设置了 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/zh-CN/env-vars) 时为 `true`。作为布尔值而不是字符串发出。在 `session` 调查事件上存在。过滤此属性以确认覆盖在整个队伍中应用1367* `enabled_via_override`：当设置了 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/zh-CN/env-vars) 时为 `true`。作为布尔值而不是字符串发出。存在于 `session` 调查事件上。在此属性上过滤以确认覆盖在整个舰队中应用

1320 1368

1321<h4 id="retention-sweep-event">1369<h4 id="retention-sweep-event">

1322 保留扫描事件1370 保留扫描事件

1323</h4>1371</h4>

1324 1372

1325在保留清理扫描的每次运行时记录一次，该扫描删除 [会话记录和其他应用数据](/docs/zh-CN/claude-directory#cleaned-up-automatically)，其年龄超过 [`cleanupPeriodDays`](/docs/zh-CN/settings-reference#cleanupperioddays) 设置。Claude Code 在后台最多每个会话运行一次扫描，删除任何内容的运行仍会发出事件。如果 Claude Code 在过去 24 小时内在同一台机器上的任何会话中运行了扫描，它会将此会话的扫描延迟至少 10 分钟，因此更早退出的会话不会发出任何内容。当您使用 `--bare` 运行 `claude -p` 时，Claude Code 不运行扫描且不发出任何内容。1373每次运行保留清理扫描时记录一次，该扫描删除[会话记录和其他应用数据](/docs/zh-CN/claude-directory#cleaned-up-automatically)早于 [`cleanupPeriodDays`](/docs/zh-CN/settings-reference#cleanupperioddays) 设置的数据。Claude Code 在后台最多每个会话运行一次扫描，删除任何内容的运行仍会发出事件。如果 Claude Code 在过去 24 小时内在同一台机器的任何会话中运行了扫描，它会将此会话的扫描延迟至少 10 分钟，因此更早退出的会话不发出任何内容。当您使用 `--bare` 运行 `claude -p` 时，Claude Code 不运行扫描，不发出任何内容。

1326 1374

1327像此页面上的每个 OTel 事件一样，它仅发送到您配置的遥测后端。需要 Claude Code v2.1.227 或更高版本。1375像此页面上的每个 OTel 事件一样，它仅流向您配置的遥测后端。需要 Claude Code v2.1.227 或更高版本。

1328 1376

1329当 Claude Code 无法安全确定保留期时，它会暂停扫描并发出事件，`result` 设置为 `"skipped"` 和 `skip_reason`。当 [托管设置](/docs/zh-CN/server-managed-settings) 设置 `cleanupPeriodDays` 时，托管值固定保留期，扫描即使在较低优先级范围内的设置文件损坏或无效时也会运行。当 `managed-settings.json` 本身无法读取时，Claude Code 仍会暂停扫描，除非 [托管层](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources) 从其他地方（例如服务器托管设置或损坏文件旁边的 `managed-settings.d/` 放置）提供 `cleanupPeriodDays`。删除计数器属性仅在 `result` 为 `"complete"` 时存在。1377当 Claude Code 无法安全地确定保留期时，它暂停扫描并发出事件，`result` 设置为 `"skipped"` 和 `skip_reason`。当[管理设置](/docs/zh-CN/server-managed-settings)设置 `cleanupPeriodDays` 时，管理值固定保留期，扫描即使在较低优先级范围内的设置文件损坏或无效时也运行。当 `managed-settings.json` 本身无法读取时，Claude Code 仍暂停扫描，除非[管理层](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)从其他地方（如服务器管理设置或损坏文件旁的 `managed-settings.d/` 放入）提供 `cleanupPeriodDays`。删除计数器属性仅当 `result` 为 `"complete"` 时存在。

1330 1378

1331**事件名称**：`claude_code.retention_sweep`1379**事件名称**：`claude_code.retention_sweep`

1332 1380

1333**属性**：1381**属性**：

1334 1382

1335* 所有 [标准属性](#standard-attributes)1383* 所有[标准属性](#standard-attributes)

1336* `event.name`：`"retention_sweep"`1384* `event.name`：`"retention_sweep"`

1337* `event.timestamp`：ISO 8601 时间戳1385* `event.timestamp`：ISO 8601 时间戳

1338* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1386* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1339* `result`：当扫描运行时为 `"complete"`，当 Claude Code 暂停时为 `"skipped"`1387* `result`：当扫描运行时为 `"complete"`，当 Claude Code 暂停它时为 `"skipped"`

1340* `period_days`：来自合并设置的 `cleanupPeriodDays` 值（天数），或当没有来源设置时为 `30`。在跳过的事件上，扫描将使用的值，从 Claude Code 可以读取的设置来源计算1388* `period_days`：来自合并设置的 `cleanupPeriodDays` 值（以天为单位），或当没有源设置它时为 `30`。在跳过的事件上，扫描会使用的值，从 Claude Code 可以读取的设置源计算

1341* `used_default`：当没有可读的设置来源设置 `cleanupPeriodDays` 时为 `"true"`，否则为 `"false"`。在完成事件上，`"true"` 表示应用了 30 天默认值1389* `used_default`：当没有可读的设置源设置 `cleanupPeriodDays` 时为 `"true"`，否则为 `"false"`。在完成事件上，`"true"` 表示应用了 30 天默认值

1342* `skip_reason`：Claude Code 暂停扫描的原因。仅当 `result` 为 `"skipped"` 时存在：1390* `skip_reason`：Claude Code 暂停扫描的原因。仅当 `result` 为 `"skipped"` 时存在：

1343 * `"user_source_disabled"`：用户设置被排除，例如通过 [`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 标志或 SDK 的 [`settingSources`](/docs/zh-CN/agent-sdk/typescript#options) 选项，且没有启用的来源提供 `cleanupPeriodDays`1391 * `"user_source_disabled"`：用户设置被排除，例如通过 [`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 标志或 SDK 的 [`settingSources`](/docs/zh-CN/agent-sdk/typescript#options) 选项，且没有启用的源提供 `cleanupPeriodDays`

1344 * `"settings_unknowable"`：设置文件无法读取或解析，因此 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 可能设置为 Claude Code 无法看到的值1392 * `"settings_unknowable"`：设置文件无法读取或解析，因此 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 可能设置为 Claude Code 无法看到的值

1345 * `"settings_invalid_key_set"`：设置有验证错误且 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 被显式设置，因此回退到默认值可能会删除或保留与该设置相反的文件1393 * `"settings_invalid_key_set"`：设置有验证错误且 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 被显式设置，因此回退到默认值可能会删除或保留违反该设置的文件

1346* `transcripts_deleted`：扫描删除的会话记录数，顶级 `~/.claude/projects/*/*.jsonl` 文件1394* `transcripts_deleted`：扫描删除的会话记录数，顶级 `~/.claude/projects/*/*.jsonl` 文件

1347* `transcripts_exempted_desktop`：超过保留期的记录数，扫描在 [Claude Desktop 和 Cowork 规则](/docs/zh-CN/claude-directory#cleaned-up-automatically) 下保留。这些不计入 `files_past_cutoff`。需要 Claude Code v2.1.248 或更高版本1395* `transcripts_exempted_desktop`：超过保留期的记录数，扫描在[Claude Desktop 和 Cowork 规则](/docs/zh-CN/claude-directory#cleaned-up-automatically)下保留。这些不计入 `files_past_cutoff`。需要 Claude Code v2.1.248 或更高版本

1348* `session_files_deleted`：会话文件扫描删除的项目数：记录加上每个会话的伴随文件，例如侧边栏、录音和工具结果1396* `session_files_deleted`：会话文件扫描删除的工件数：记录加上每个会话的伴随文件，如侧边栏、录音和工具结果

1349* `artifacts_deleted`：扫描跨越其覆盖的数据目录删除的总项目数，包括会话文件。某些扫描将整个删除的目录树计为一项，少数清理通过不对计数器有贡献，因此将值视为下限而不是精确文件计数1397* `artifacts_deleted`：扫描删除的数据目录中的总项目数，包括会话文件。某些扫描将整个删除的目录树计为一项，少数清理通过不贡献计数器，因此将值视为下限而不是精确文件计数

1350* `files_retained_fresh`：检查并保留在原位的文件，因为它们仍在保留期内。仅每个文件扫描计算这些，因此值是下限；非零值是正常的稳定状态1398* `files_retained_fresh`：检查并保留在原地的文件，因为它们仍在保留期内。仅每个文件扫描计数这些，因此值是下限；非零值是正常稳定状态

1351* `files_past_cutoff`：超过保留期的文件，扫描未能删除，例如因为权限错误或文件被打开。值高于零表示文件超过了配置的保留期；零不是证明没有任何文件，因为整个目录删除失败计入 `error_count` 而不是1399* `files_past_cutoff`：早于保留期的文件，扫描无法删除，例如由于权限错误或文件被打开。值高于零表示文件超过了配置的保留期；零不是证明没有任何文件，因为整个目录的删除失败计入 `error_count`

1352* `error_count`：扫描在列出或删除文件时遇到的错误数1400* `error_count`：扫描在列出或删除文件时遇到的错误数

1353 1401

1354<h4 id="managed-settings-resolved-event">1402<h4 id="managed-settings-resolved-event">

1355 托管设置已解析事件1403 管理设置已解析事件

1356</h4>1404</h4>

1357 1405

1358在会话解析的 [托管设置](/docs/zh-CN/managed-settings) 时记录：在会话开始时一次，当托管设置或 [策略助手](/docs/zh-CN/managed-settings#compute-the-policy-with-a-helper-program) 的状态在会话期间更改时再次，以及当 Claude Code 拒绝启动或因 `error.type` 属性列出的原因之一而结束会话时。1406使用会话解析的[管理设置](/docs/zh-CN/managed-settings)记录：在会话开始时一次，当管理设置或[策略助手](/docs/zh-CN/managed-settings#compute-the-policy-with-a-helper-program)的状态在会话期间更改时再次，以及当 Claude Code 拒绝启动或因 `error.type` 属性列出的原因之一而结束会话时。

1359使用此事件查找在意外托管来源上运行的机器、策略助手失败的机器以及机器拒绝启动的原因。1407使用此事件查找在意外管理源上运行的机器、策略助手失败的机器以及机器拒绝启动的原因。

1360需要 Claude Code v2.1.274 或更高版本。1408需要 Claude Code v2.1.274 或更高版本。

1361 1409

1362默认情况下，事件携带托管来源和策略助手的状态，但不携带设置本身。要添加编辑的 `managed_settings.settings` 属性和 `managed_settings.resolved_sha256` 摘要，设置 `OTEL_LOG_MANAGED_SETTINGS=1`：1410默认情况下，事件携带管理源和策略助手的状态，但不携带设置本身。要添加编辑的 `managed_settings.settings` 属性和 `managed_settings.resolved_sha256` 摘要，请设置 `OTEL_LOG_MANAGED_SETTINGS=1`：

1363 1411

1364* 在托管设置、用户设置或 `--settings` 的 `env` 块中设置它，或在启动 Claude Code 的环境中。项目或本地设置中的值不会打开它，因为克隆的存储库可以写入它们。1412* 在管理设置、用户设置或 `--settings` 的 `env` 块中设置它，或在启动 Claude Code 的环境中。项目或本地设置中的值不会打开它，因为克隆的存储库可以写入它们。

1365* 服务器托管设置可以在不显示 [安全批准对话](/docs/zh-CN/server-managed-settings#security-approval-dialogs) 的情况下设置它，因为变量仅将您组织自己的编辑策略添加到您的组织已接收的事件。1413* 服务器管理设置可以在不显示[安全批准对话](/docs/zh-CN/server-managed-settings#security-approval-dialogs)的情况下设置它，因为变量仅将您组织自己的编辑策略添加到您的组织已接收的事件。

1366 1414

1367在您尚未 [信任](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 的文件夹中的交互式会话中，Claude Code 不会导出拒绝事件。1415在您尚未[信任](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder)的文件夹中的交互式会话中，Claude Code 不导出拒绝事件。

1368 1416

1369**事件名称**：`claude_code.managed_settings_resolved`1417**事件名称**：`claude_code.managed_settings_resolved`

1370 1418

1371**属性**：1419**属性**：

1372 1420

1373* 所有 [标准属性](#standard-attributes)1421* 所有[标准属性](#standard-attributes)

1374* `event.name`：`"managed_settings_resolved"`1422* `event.name`：`"managed_settings_resolved"`

1375* `event.timestamp`：ISO 8601 时间戳1423* `event.timestamp`：ISO 8601 时间戳

1376* `event.sequence`：用于排序事件的单调递增计数器，在 [事件关联属性](#event-correlation-attributes) 下描述1424* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1377* `managed_settings.trigger`：`"startup"` 用于会话启动事件，`"change"` 当托管设置或策略助手的状态在会话后期更改时，或 `"refused"` 当托管设置策略停止会话时。Claude Code 仅在属性与它发送的最后一个事件不同时发送 `change` 事件，更改的设置值计数即使 `OTEL_LOG_MANAGED_SETTINGS` 关闭时也计数1425* `managed_settings.trigger`：会话启动事件为 `"startup"`，当管理设置或策略助手的状态在会话后期更改时为 `"change"`，或当管理设置策略停止会话时为 `"refused"`。Claude Code 仅在属性与它发送的最后一个事件不同时发送 `change` 事件，更改的设置值即使 `OTEL_LOG_MANAGED_SETTINGS` 关闭也计数

1378* `error.type`：Claude Code 停止会话的原因。仅在 `refused` 事件上存在：1426* `error.type`：Claude Code 停止会话的原因。仅在 `refused` 事件上存在：

1379 * `"helper_failed"`：[策略助手运行失败](/docs/zh-CN/settings-reference#helper-failures)1427 * `"helper_failed"`：[策略助手运行失败](/docs/zh-CN/settings-reference#helper-failures)

1380 * `"policy_invalid"`：托管设置包含阻止 Claude Code 启动的错误，或管理员来源无法加载，因此 Claude Code 无法检查组织登录强制1428 * `"policy_invalid"`：管理设置包含停止 Claude Code 启动的错误，或管理源无法加载，因此 Claude Code 无法检查组织登录强制

1381 * `"consent_rejected"`：用户拒绝了 [安全批准对话](/docs/zh-CN/server-managed-settings#security-approval-dialogs) 用于服务器托管设置1429 * `"consent_rejected"`：用户拒绝了服务器管理设置的[安全批准对话](/docs/zh-CN/server-managed-settings#security-approval-dialogs)

1382 * `"force_refresh_failed"`：[`forceRemoteSettingsRefresh`](/docs/zh-CN/settings-reference#forceremotesettingsrefresh) 需要的设置获取失败1430 * `"force_refresh_failed"`：[`forceRemoteSettingsRefresh`](/docs/zh-CN/settings-reference#forceremotesettingsrefresh) 需要的设置获取失败

1383 * `"gateway_rejected"`：[Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 用 HTTP 403 回答托管设置加载1431 * `"gateway_rejected"`：[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)用 HTTP 403 回答了管理设置加载

1384 * `"version_below_minimum"`：此版本的 Claude Code 低于 [`requiredMinimumVersion`](/docs/zh-CN/settings-reference#requiredminimumversion) 或高于 [`requiredMaximumVersion`](/docs/zh-CN/settings-reference#requiredmaximumversion)1432 * `"version_below_minimum"`：此版本的 Claude Code 低于 [`requiredMinimumVersion`](/docs/zh-CN/settings-reference#requiredminimumversion) 或高于 [`requiredMaximumVersion`](/docs/zh-CN/settings-reference#requiredmaximumversion)

1385 * `"_OTHER"`：Claude apps gateway 托管设置加载因另一个原因失败1433 * `"_OTHER"`：Claude 应用网关管理设置加载因另一个原因失败

1386* `managed_settings.sources`：每个传递至少一个 [策略键](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources) 的托管来源，优先级最高的优先，包括其键在 `first-wins` 下不生效的来源。值为 `"remote"`、`"plist"` 或 `"hklm"` 用于 MDM 或 OS 级策略、`"file"` 用于托管设置文件和放置、`"parent"` 当 [嵌入主机](/docs/zh-CN/managed-settings#let-an-embedding-host-add-policy) 提供设置时，以及 `"hkcu"` 用于 [Windows HKCU 注册表值](/docs/zh-CN/managed-settings#where-each-mechanism-stores-the-policy) 当 Claude Code [读取它](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources) 时。仅携带控制键的来源或 Claude Code 无法读取的来源不被列出。作为字符串数组发出，当没有托管来源传递策略键时为空1434* `managed_settings.sources`：每个传递至少一个[策略键](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)的管理源，优先级最高的优先，包括其键在 `first-wins` 下不生效的源。值为 `"remote"`、`"plist"` 或 `"hklm"` 用于 MDM 或 OS 级策略、`"file"` 用于管理设置文件和放入、`"parent"` 当[嵌入主机](/docs/zh-CN/managed-settings#let-an-embedding-host-add-policy)提供设置时，以及 `"hkcu"` 用于 Claude Code [读取](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)时的 [Windows HKCU 注册表值](/docs/zh-CN/managed-settings#where-each-mechanism-stores-the-policy)。仅携带策略键或 Claude Code 无法读取的源不列出。作为字符串数组发出，当没有管理源传递策略键时为空

1387* `managed_settings.source_behavior`：Claude Code 读取的 [`managedSourcesBehavior`](/docs/zh-CN/settings-reference#managedsourcesbehavior) 值，`"first-wins"` 或 `"merge"`。当没有来源设置键时为 `"first-wins"`1435* `managed_settings.source_behavior`：Claude Code 读取的 [`managedSourcesBehavior`](/docs/zh-CN/settings-reference#managedsourcesbehavior) 值，`"first-wins"` 或 `"merge"`。当没有源设置键时为 `"first-wins"`

1388* `managed_settings.helper.state`：所选 MDM 或文件来源配置的策略助手的状态：1436* `managed_settings.helper.state`：所选 MDM 或文件源配置的策略助手的状态：

1389 * `"ok"`：助手的输出作为托管设置提供1437 * `"ok"`：助手的输出作为管理设置

1390 * `"bad_path"`、`"not_a_file"`、`"exit_nonzero"`、`"timed_out"`、`"oversize"`、`"parse_failed"`、`"envelope_invalid"` 或 `"schema_rejected"`：助手的最后一次运行失败。[助手失败](/docs/zh-CN/settings-reference#helper-failures) 描述了这些情况1438 * `"bad_path"`、`"not_a_file"`、`"exit_nonzero"`、`"timed_out"`、`"oversize"`、`"parse_failed"`、`"envelope_invalid"` 或 `"schema_rejected"`：助手的最后一次运行失败。[助手失败](/docs/zh-CN/settings-reference#helper-failures)描述了这些情况

1391 * `"none"`：没有配置助手，或配置它的来源不是 MDM 策略或托管设置文件1439 * `"none"`：没有配置助手，或配置它的源不是 MDM 策略或管理设置文件

1392* `managed_settings.helper.applied`：`"output"` 当助手自己的输出作为托管设置提供时，`"none"` 当它不提供时1440* `managed_settings.helper.applied`：当助手自己的输出作为管理设置时为 `"output"`，当它不时为 `"none"`

1393* `managed_settings.helper.entry`：当 Claude Code 选择了 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 时为 `"policyHelper"`。当它选择了没有助手时不存在1441* `managed_settings.helper.entry`：当 Claude Code 选择了 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 时为 `"policyHelper"`。当它选择了没有助手时不存在

1394* `managed_settings.helper.path`：助手的配置 [`path`](/docs/zh-CN/settings-reference#policyhelper-path)。每当 Claude Code 选择了助手时存在，无论 `OTEL_LOG_MANAGED_SETTINGS` 是否设置1442* `managed_settings.helper.path`：助手的配置 [`path`](/docs/zh-CN/settings-reference#policyhelper-path)。每当 Claude Code 选择了助手时存在，无论 `OTEL_LOG_MANAGED_SETTINGS` 是否设置

1395* `managed_settings.resolved_sha256`（当 `OTEL_LOG_MANAGED_SETTINGS=1` 时）：解析的托管设置在编辑前的 SHA-256，序列化为 JSON，键递归排序且无空格。具有相同摘要的机器运行相同的策略。Claude Code 仅使用选择加入发送摘要，因为短策略可以通过哈希猜测恢复。当没有托管设置解析时不存在，在 `refused` 事件上不存在1443* `managed_settings.resolved_sha256`（当 `OTEL_LOG_MANAGED_SETTINGS=1` 时）：编辑前解析的管理设置的 SHA-256，序列化为 JSON，键递归排序，无空格。具有相同摘要的机器运行相同的策略。Claude Code 仅使用选择加入发送摘要，因为短策略可以通过哈希猜测恢复。当没有管理设置解析时不存在，在 `refused` 事件上不存在

1396* `managed_settings.settings`（当 `OTEL_LOG_MANAGED_SETTINGS=1` 时）：解析的托管设置的名称和形状作为 JSON 字符串，值被编辑。在 `refused` 事件上不存在。Claude Code 从其设置架构构建它：1444* `managed_settings.settings`（当 `OTEL_LOG_MANAGED_SETTINGS=1` 时）：解析的管理设置的名称和形状作为 JSON 字符串，值被编辑。在 `refused` 事件上不存在。Claude Code 从其设置架构构建它：

1397 1445

1398 * 架构声明导出的设置名称，架构不声明的键被留出1446 * 架构声明导出的设置名称，架构不声明的键被留出

1399 * 布尔值、数字和字符串值，架构限制为固定选项集，例如 `permissions.defaultMode`，按原样导出。`sandbox.network.httpProxyPort` 和 `sandbox.network.socksProxyPort` 导出为 `"[REDACTED]"`1447 * 布尔值、数字和字符串值，架构限制为固定选项集，例如 `permissions.defaultMode`，按原样导出。`sandbox.network.httpProxyPort` 和 `sandbox.network.socksProxyPort` 导出为 `"[REDACTED]"`

1400 * 每个其他字符串，例如 `model`、`apiKeyHelper`、每个 `env` 值、每个 URL 和每个命令，导出为 `"[REDACTED]"`1448 * 每个其他字符串，例如 `model`、`apiKeyHelper`、每个 `env` 值、每个 URL 和每个命令，导出为 `"[REDACTED]"`

1401 * 地图的条目名称，例如 `env` 变量名称和插件 ID，按原样导出。架构不键入其条目的设置，例如 `vimInsertModeRemaps`，导出为单个 `"[REDACTED]"`，`sandbox.ignoreViolations` 导出为其路径列表的列表，不带命令模式1449 * 地图的条目名称，例如 `env` 变量名称和插件 ID，按原样导出。架构不键入其条目的设置，例如 `vimInsertModeRemaps`，导出为单个 `"[REDACTED]"`，`sandbox.ignoreViolations` 导出为其路径列表的列表，不带命令模式

1402 * 列表保留其长度，每个条目按相同规则编辑1450 * 列表保留其长度，每个条目按相同规则编辑

1403 * `permissions.allow`、`permissions.deny` 或 `permissions.ask` 规则导出为其工具名称，内容编辑，例如 `Read([REDACTED])`，当工具内置于此版本的 Claude Code 或是 `mcp__` 参考（例如 `mcp__jira__create_issue`）时。任何其他规则导出为 `"[REDACTED]"`1451 * `permissions.allow`、`permissions.deny` 或 `permissions.ask` 规则导出为其工具名称，内容编辑，例如 `Read([REDACTED])`，当工具内置于此版本的 Claude Code 或是 `mcp__` 参考（如 `mcp__jira__create_issue`）时。任何其他规则导出为 `"[REDACTED]"`

1404 * Hooks 遵循相同的规则，因此固定选项和数值字段（例如 `type` 和 `timeout`）显示，而每个命令、URL、`matcher` 和 `if` 条件导出为 `"[REDACTED]"`1452 * 钩子遵循相同的规则，因此固定选项和数字字段（如 `type` 和 `timeout`）显示，而每个命令、URL、`matcher` 和 `if` 条件导出为 `"[REDACTED]"`

1405 1453

1406 例如，具有 `apiKeyHelper`、两个 `env` 变量和拒绝规则的托管设置导出为 `{"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}`.1454 例如，具有 `apiKeyHelper`、两个 `env` 变量和拒绝规则的管理设置导出为 `{"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}`.

1407 1455

1408 Claude Code 在 8 KB UTF-8 处切割值，切割值不是有效的 JSON1456 Claude Code 在 8 KB UTF-8 处切割值，切割值不是有效的 JSON

1409* `managed_settings.settings_truncated`（当 `managed_settings.settings` 存在时）：当 Claude Code 在 8 KB 处切割 `managed_settings.settings` 时为 `true`，否则为 `false`。作为布尔值而不是字符串发出。1457* `managed_settings.settings_truncated`（当 `managed_settings.settings` 存在时）：当 Claude Code 在 8 KB 处切割 `managed_settings.settings` 时为 `true`，否则为 `false`。作为布尔值而不是字符串发出

1410 1458

1411<h2 id="interpret-metrics-and-events-data">1459<h2 id="interpret-metrics-and-events-data">

1412 解释指标和事件数据1460 解释指标和事件数据

1494 1542

1495每个事件上的 [标准属性](#standard-attributes) 包括已认证用户的身份：`user.email`、`user.account_uuid`、`user.account_id` 和 `organization.id`（使用 Claude 账户登录时或在 [云会话](/docs/zh-CN/claude-code-on-the-web) 中，当会话自己的凭证携带它们时），加上 `user.id` 和每会话的 `session.id`。`user.id` 是安装范围的标识符，除了在 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话上，其中它是来自网关颁发的令牌的 IdP 主体。1543每个事件上的 [标准属性](#standard-attributes) 包括已认证用户的身份：`user.email`、`user.account_uuid`、`user.account_id` 和 `organization.id`（使用 Claude 账户登录时或在 [云会话](/docs/zh-CN/claude-code-on-the-web) 中，当会话自己的凭证携带它们时），加上 `user.id` 和每会话的 `session.id`。`user.id` 是安装范围的标识符，除了在 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话上，其中它是来自网关颁发的令牌的 IdP 主体。

1496 1544

1497MCP 工具调用、Bash 命令和文件编辑因此归属于启动会话的开发人员。Claude Code 不在单独的服务账户下运行；每个事件上记录的身份是开发人员自己的 Claude 账户，或开发人员在 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话上的 IdP 身份。1545在开发人员启动的会话中，MCP 工具调用、Bash 命令和文件编辑因此归属于该开发人员。Claude Code 不在单独的服务账户下运行；每个事件上记录的身份是开发人员自己的 Claude 账户，或开发人员在 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话上的 IdP 身份。在 Claude Tag 频道会话中，Claude 改为作为您组织的 [共享身份](/docs/zh-CN/cloud-environments#set-the-environment-a-claude-tag-channel-uses) 工作。

1498 1546

1499当 Claude Code 使用直接 API 密钥进行身份验证，或针对 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 进行身份验证时，会话中没有 Claude 账户，仅填充 `user.id` 和 `session.id`。在这些部署中，使用 `OTEL_RESOURCE_ATTRIBUTES` 自己附加用户身份，通过 [托管设置](#administrator-configuration) 文件或启动包装器按用户设置。Claude apps gateway 会话不需要任何这些：CLI 自动标记 IdP 身份，如 [标准属性](#standard-attributes) 中所述。1547当 Claude Code 使用直接 API 密钥进行身份验证，或针对 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 进行身份验证时，会话中没有 Claude 账户，仅填充 `user.id` 和 `session.id`。在这些部署中，使用 `OTEL_RESOURCE_ATTRIBUTES` 自己附加用户身份，通过 [托管设置](#administrator-configuration) 文件或启动包装器按用户设置。Claude apps gateway 会话不需要任何这些：CLI 自动标记 IdP 身份，如 [标准属性](#standard-attributes) 中所述。

1500 1548

1558}1606}

1559```1607```

1560 1608

1561要确认事件到达，在运行此配置的会话中提交提示，并在您的 SIEM 中检查 `claude_code.user_prompt` 事件。如果没有任何内容到达，运行 `claude --debug` 并在调试日志中检查 `[3P telemetry]` 导出错误。1609要确认事件到达，在运行此配置的会话中提交提示，并在您的 SIEM 中检查 `claude_code.user_prompt` 事件。如果没有任何内容到达，使用 `claude --debug-file <path>` 启动 Claude Code 并在该日志中检查 `[3P telemetry]` 导出错误。

1562 1610

1563<h2 id="backend-considerations">1611<h2 id="backend-considerations">

1564 后端考虑事项1612 后端考虑事项

1628 * `tool_result` 和 `tool_decision` 事件包含 `tool_parameters` 属性，其中包含 Bash 命令、MCP 服务器和工具名称以及技能名称。`full_command` 等字段以未截断的形式发出1676 * `tool_result` 和 `tool_decision` 事件包含 `tool_parameters` 属性，其中包含 Bash 命令、MCP 服务器和工具名称以及技能名称。`full_command` 等字段以未截断的形式发出

1629 * `tool_result` 事件另外包含 `tool_input` 属性，其中包含文件路径、URL、搜索模式和其他参数。超过 512 个字符的单个值被截断，总数限制为约 4 K 字符1677 * `tool_result` 事件另外包含 `tool_input` 属性，其中包含文件路径、URL、搜索模式和其他参数。超过 512 个字符的单个值被截断，总数限制为约 4 K 字符

1630 * `user_prompt` 事件包含自定义、插件和 MCP 命令的逐字 `command_name`1678 * `user_prompt` 事件包含自定义、插件和 MCP 命令的逐字 `command_name`

1679 * [成本和令牌计数器](#cost-counter)以及 `api_request`、`api_error` 和 `api_refusal` 事件在其归属属性中携带真实的代理、技能、插件和 MCP 服务器以及工具名称

1631 * Trace spans 包含相同的 `tool_input` 属性和输入派生属性（如 `file_path`），与 `tool_input` 的截断方式相同1680 * Trace spans 包含相同的 `tool_input` 属性和输入派生属性（如 `file_path`），与 `tool_input` 的截断方式相同

1632* 默认情况下，trace spans 中不记录工具内容。要包含它，请设置 `OTEL_LOG_TOOL_CONTENT=1`。`claude_code.tool` span 随后携带一个 [`tool.output` span 事件](#tool-output-span-event)，其中包含原始文件内容和 Bash 命令输出，在内容限制处截断（默认为 60 KB）每个属性。工具内容也通过 [`new_context` 到达 spans，其门控因 span 而异](#new-context-gates)。根据需要配置您的遥测后端以过滤或编辑这些属性1681* 默认情况下，trace spans 中不记录工具内容。要包含它，请设置 `OTEL_LOG_TOOL_CONTENT=1`。`claude_code.tool` span 随后携带一个 [`tool.output` span 事件](#tool-output-span-event)，其中包含原始文件内容、Bash 命令输出以及 MCP 工具、WebFetch 和 WebSearch 返回的内容，在内容限制处截断（默认为 60 KB）每个属性。来自 MCP 工具、WebFetch 和 WebSearch 的结果需要 Claude Code v2.1.283 或更高版本。工具内容也通过 [`new_context` 到达 spans，其门控因 span 而异](#new-context-gates)。根据需要配置您的遥测后端以过滤或编辑这些属性

1633* 默认情况下不记录原始 Anthropic Messages API 请求和响应主体。要包含它们，请在您的 shell、用户设置或托管设置中设置 `OTEL_LOG_RAW_API_BODIES`。在 [项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env) 中被忽略。主体包含完整的对话历史，包括系统提示、每个先前的用户和助手轮次以及工具结果，因此启用此选项意味着同意其他 `OTEL_LOG_*` 内容标志会揭示的所有内容。Claude Code 始终从这些主体中编辑 Claude 的扩展思考内容，无论其他设置如何。您设置的值决定了 Claude Code 如何传递主体：1682* 默认情况下不记录原始 Anthropic Messages API 请求和响应主体。要包含它们，请在您的 shell、用户设置或托管设置中设置 `OTEL_LOG_RAW_API_BODIES`。在 [项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env) 中被忽略。主体包含完整的对话历史，包括系统提示、每个先前的用户和助手轮次以及工具结果，因此启用此选项意味着同意其他 `OTEL_LOG_*` 内容标志会揭示的所有内容。Claude Code 始终从这些主体中编辑 Claude 的扩展思考内容，无论其他设置如何。您设置的值决定了 Claude Code 如何传递主体：

1634 * 使用 `=1` 时，Claude Code 为每个 API 调用发出 `api_request_body` 和 `api_response_body` 日志事件。事件的 `body` 属性携带 JSON 序列化的有效负载，在内容限制处截断（默认为 60 KB）1683 * 使用 `=1` 时，Claude Code 为每个 API 调用发出 `api_request_body` 和 `api_response_body` 日志事件。事件的 `body` 属性携带 JSON 序列化的有效负载，在内容限制处截断（默认为 60 KB）

1635 * 使用 `=file:<dir>` 时，Claude Code 将未截断的主体写入该目录下的 `.request.json` 和 `.response.json` 文件，事件携带 `body_ref` 路径而不是内联主体。使用日志收集器或 sidecar 传输目录，而不是通过遥测流1684 * 使用 `=file:<dir>` 时，Claude Code 将未截断的主体写入该目录下的 `.request.json` 和 `.response.json` 文件，事件携带 `body_ref` 路径而不是内联主体。使用日志收集器或 sidecar 传输目录，而不是通过遥测流

overview.md +3 −1

Details

22 <Tab title="Terminal">22 <Tab title="Terminal">

23 功能完整的 CLI，用于直接在终端中使用 Claude Code。编辑文件、运行命令，并从命令行管理整个项目。23 功能完整的 CLI，用于直接在终端中使用 Claude Code。编辑文件、运行命令，并从命令行管理整个项目。

24 24

~~25 要安装 Claude Code，请使用以下方法之一：~~25 要安装 Claude Code，请打开终端并运行适用于您的系统的命令。如果您之前没有使用过终端，[终端指南](/docs/zh-CN/terminal-guide)会展示如何打开终端并粘贴命令。

26 26

27 <Tabs>27 <Tabs>

28 <Tab title="原生安装（推荐）">28 <Tab title="原生安装（推荐）">

44 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd44 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

45 ```45 ```

46 46

47 安装程序完成后，打开一个新的终端窗口并运行 `claude --version`。正常的安装会打印一个版本号。如果您的 shell 显示找不到 `claude` 或无法识别，说明安装目录还不在您的 PATH 中：请参阅[修复您的 PATH](/docs/zh-CN/troubleshoot-install#command-not-found-claude-after-installation)。

47 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。当您在 PowerShell 中时，您的提示符显示 `PS C:\`，当您在 CMD 中时显示 `C:\`（没有 `PS`）。49 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。当您在 PowerShell 中时，您的提示符显示 `PS C:\`，当您在 CMD 中时显示 `C:\`（没有 `PS`）。

48 50

49 如果安装命令失败并显示 `syntax error near unexpected token '<'`、`403` 或其他 curl 错误，请参阅 [Troubleshoot installation](/docs/zh-CN/troubleshoot-install#find-your-error) 以匹配错误并获得修复方案和替代安装方法。51 如果安装命令失败并显示 `syntax error near unexpected token '<'`、`403` 或其他 curl 错误，请参阅 [Troubleshoot installation](/docs/zh-CN/troubleshoot-install#find-your-error) 以匹配错误并获得修复方案和替代安装方法。

permission-modes.md +216 −119

Details

8 8

9权限模式设置 Claude 在会话中可以在不先询问您的情况下执行哪些操作。在 Manual 模式下，Claude Code 会在大多数编辑文件、运行 shell 命令或访问网络的操作前停止并询问您。在[自动模式](#eliminate-prompts-with-auto-mode)中，第二个模型（分类器）会审查操作而不是您；[分类器如何评估操作](#how-the-classifier-evaluates-actions)列出了它审查的操作以及哪些跳过它。9权限模式设置 Claude 在会话中可以在不先询问您的情况下执行哪些操作。在 Manual 模式下，Claude Code 会在大多数编辑文件、运行 shell 命令或访问网络的操作前停止并询问您。在[自动模式](#eliminate-prompts-with-auto-mode)中，第二个模型（分类器）会审查操作而不是您；[分类器如何评估操作](#how-the-classifier-evaluates-actions)列出了它审查的操作以及哪些跳过它。

10 10

11在 Pro、Max 和 Team 计划上，内置的起始权限模式是自动模式。[会话在哪个模式下启动](#which-mode-a-session-starts-in)涵盖了改变起始权限模式的表面和设置。您也可以随时更改正在运行的会话的权限模式。11在 Claude Code v2.1.283 或更高版本中，自动模式是交互式终端和 VS Code 会话的内置起始权限模式。在早期版本中，它仅在 Pro、Max 和 Team 计划上是内置的起始权限模式。[会话在哪个模式下启动](#which-mode-a-session-starts-in)涵盖了改变起始权限模式的表面和设置。您也可以随时更改正在运行的会话的权限模式。

12 12

13<h2 id="available-modes">13<h2 id="available-modes">

14 可用的模式14 可用的模式

57| 自己审查每个操作 | Manual 模式：`claude --permission-mode default` | 无 | 敏感工作、不熟悉的代码 |57| 自己审查每个操作 | Manual 模式：`claude --permission-mode default` | 无 | 敏感工作、不熟悉的代码 |

58| 在本地迭代，更少提示，无分类器 | Manual 模式加上 Bash 沙箱在[自动允许模式](/docs/zh-CN/sandboxing#sandbox-modes)：`claude --permission-mode default`，然后运行 `/sandbox` 并选择自动允许 | 内置 Bash 沙箱，在 macOS、Linux 和 WSL2 上 | 拒绝规则仍然适用，询问规则命名命令（如 `Bash(git push *)`）仍然会提示。要从设置文件启用沙箱，请改为将 [`sandbox.enabled`](/docs/zh-CN/settings-reference#sandbox-enabled) 设置为 `true` |58| 在本地迭代，更少提示，无分类器 | Manual 模式加上 Bash 沙箱在[自动允许模式](/docs/zh-CN/sandboxing#sandbox-modes)：`claude --permission-mode default`，然后运行 `/sandbox` 并选择自动允许 | 内置 Bash 沙箱，在 macOS、Linux 和 WSL2 上 | 拒绝规则仍然适用，询问规则命名命令（如 `Bash(git push *)`）仍然会提示。要从设置文件启用沙箱，请改为将 [`sandbox.enabled`](/docs/zh-CN/settings-reference#sandbox-enabled) 设置为 `true` |

59| 在更改任何内容前探索 | `claude --permission-mode plan` | 无 | Claude Code 阻止编辑，直到您[批准计划](#review-and-approve-a-plan) |59| 在更改任何内容前探索 | `claude --permission-mode plan` | 无 | Claude Code 阻止编辑，直到您[批准计划](#review-and-approve-a-plan) |

60| 在自动模式下无需干预工作 | `claude --permission-mode auto`，Pro、Max 和 Team 上的[内置起始权限模式](#which-mode-a-session-starts-in) | 无；沙箱或容器增加深度防御 | 需要[支持的模型](#eliminate-prompts-with-auto-mode)，您的组织可以[关闭自动模式](#eliminate-prompts-with-auto-mode) |60| 在自动模式下无需干预工作 | `claude --permission-mode auto`，v2.1.283 或更高版本的[内置起始权限模式](#which-mode-a-session-starts-in) | 无；沙箱或容器增加深度防御 | 需要[支持的模型](#eliminate-prompts-with-auto-mode)，您的组织可以[关闭自动模式](#eliminate-prompts-with-auto-mode) |

62| 在容器内完全无人值守运行 | `claude -p "<prompt>" --dangerously-skip-permissions` | 必需：容器、虚拟机或[沙箱运行时](/docs/zh-CN/sandbox-environments#sandbox-runtime)；在 Linux 和 macOS 上，以[非 root 用户](#skip-all-checks-with-bypasspermissions-mode)身份运行 | 网络上的 Claude Code 忽略设置文件中的此模式。在此 `-p` 运行中，[仍会提示的少数调用](#skip-all-checks-with-bypasspermissions-mode)被拒绝 |62| 在容器内完全无人值守运行 | `claude -p "<prompt>" --dangerously-skip-permissions` | 必需：容器、虚拟机或[沙箱运行时](/docs/zh-CN/sandbox-environments#sandbox-runtime)；在 Linux 和 macOS 上，以[非 root 用户](#skip-all-checks-with-bypasspermissions-mode)身份运行 | 云会话忽略设置文件中的此模式。在此 `-p` 运行中，[仍会提示的少数调用](#skip-all-checks-with-bypasspermissions-mode)被拒绝 |

63 63

64Bash 沙箱和自动模式独立工作并结合，除了在[沙箱模式](/docs/zh-CN/sandboxing#sandbox-modes)下列出的例外。有关完整交互，请参阅[沙箱化如何与权限和权限模式相关](/docs/zh-CN/sandboxing#how-sandboxing-relates-to-permissions-and-permission-modes)和[隔离如何与权限模式相关](/docs/zh-CN/sandbox-environments#how-isolation-relates-to-permission-modes)。64Bash 沙箱和自动模式独立工作并结合，除了在[沙箱模式](/docs/zh-CN/sandboxing#sandbox-modes)下列出的例外。有关完整交互，请参阅[沙箱化如何与权限和权限模式相关](/docs/zh-CN/sandboxing#how-sandboxing-relates-to-permissions-and-permission-modes)和[隔离如何与权限模式相关](/docs/zh-CN/sandbox-environments#how-isolation-relates-to-permission-modes)。

65 65

81 81

82内置 `auto` 默认值在 macOS、Linux 和 WSL 上需要 Claude Code v2.1.228 或更高版本，在本机 Windows 上需要 v2.1.233 或更高版本。在较早的版本上，内置默认值是 Manual。82内置 `auto` 默认值在 macOS、Linux 和 WSL 上需要 Claude Code v2.1.228 或更高版本，在本机 Windows 上需要 v2.1.233 或更高版本。在较早的版本上，内置默认值是 Manual。

83 83

84内置默认值取决于您如何运行 Claude Code、您的计划以及 Claude Code 是否可以获取其功能标志。匹配您会话的第一行适用。该表涵盖您在终端或通过 VS Code 扩展启动的会话；对于桌面应用和 claude.ai，请参阅[切换权限模式](#switch-permission-modes)中的 Desktop 和 Web 选项卡。84内置默认值取决于您如何运行 Claude Code。匹配您会话的第一行适用。该表涵盖您在终端或通过 VS Code 扩展启动的会话；对于桌面应用和 claude.ai，请参阅[切换权限模式](#switch-permission-modes)中的 Desktop 和 Web 选项卡。

85 85

86| 您如何运行 Claude Code | 内置起始权限模式 |86| 您如何运行 Claude Code | 内置起始权限模式 |

87| :- | :- |87| :- | :- |

88| 任何设置文件将 `disableAutoMode` 设置为 `"disable"` | `default` |88| 任何设置文件将 `disableAutoMode` 设置为 `"disable"` | `default` |

~~89| [功能标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)关闭 | `default` |~~

90| 您的[安装或升级后的第一个会话](/docs/zh-CN/env-vars#first-session-after-an-install-or-upgrade)到添加此默认值的版本，除非在全新安装后，Claude Code 及时获取标志 | `default` |

91| `claude -p` 或 [Agent SDK](/docs/zh-CN/agent-sdk/permissions) | `default` |89| `claude -p` 或 [Agent SDK](/docs/zh-CN/agent-sdk/permissions) | `default` |

92| Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、[AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 或已登录的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话 | `default` |90| 在终端或通过 [VS Code 扩展](/docs/zh-CN/vs-code) | `auto`（Claude Code v2.1.283 或更高版本）；在较早的版本上，在 Pro、Max 或 Team 计划中 `auto`（在[获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话中），否则为 `default` |

~~93| Pro、Max 或 Team 计划，在终端或通过 [VS Code 扩展](/docs/zh-CN/vs-code) | `auto` |~~

~~94| Enterprise 计划或 Claude Console API 密钥 | `default` |~~

95 91

96当功能标志获取关闭或在[安装或升级后的第一个会话](/docs/zh-CN/env-vars#first-session-after-an-install-or-upgrade)中标志尚未到达时，VS Code 扩展在选择起始权限模式时忽略每个设置文件。92在您[安装或升级后的第一个会话](/docs/zh-CN/env-vars#first-session-after-an-install-or-upgrade)中，Claude Code 可以在其功能标志到达之前选择起始权限模式。该会话可能以与表格不同的权限模式启动，您的下一个会话与表格匹配。

97 93

98当标志、设置文件或内置默认值选择 `auto` 但自动模式对会话不可用时，Claude Code 以 Manual 启动会话。自动模式在会话不满足[可用性要求](#eliminate-prompts-with-auto-mode)时不可用，例如设置文件关闭它或不支持它的模型，或当 Anthropic 已在服务器端临时关闭它时。94当标志、设置文件或内置默认值选择 `auto` 但自动模式对会话不可用时，Claude Code 以 Manual 启动会话。自动模式在会话不满足[可用性要求](#eliminate-prompts-with-auto-mode)时不可用，例如设置文件关闭它或不支持它的模型，或当 Anthropic 已在服务器端临时关闭它时。

99 95

177 173

178 1. `claudeCode.initialPermissionMode`174 1. `claudeCode.initialPermissionMode`

179 2. 您从模式指示器最后选择的模式，如果它是 Manual、Edit automatically 或 Auto。选择 Plan 或 Bypass permissions 仅适用于该对话175 2. 您从模式指示器最后选择的模式，如果它是 Manual、Edit automatically 或 Auto。选择 Plan 或 Bypass permissions 仅适用于该对话

180 3. 来自[托管设置](/docs/zh-CN/managed-settings)或 `~/.claude/settings.json` 的 `permissions.defaultMode`，在 Pro、Max 和 Team 计划上具有[功能标志获取](#which-mode-a-session-starts-in)可用176 3. 来自[托管设置](/docs/zh-CN/managed-settings)或 `~/.claude/settings.json` 的 `permissions.defaultMode`

181 4. 您的计划、提供商和组织设置的[内置默认值](#which-mode-a-session-starts-in)177 4. 您的计划、提供商和组织设置的[内置默认值](#which-mode-a-session-starts-in)

182 178

183 扩展永远不会从项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 读取起始权限模式，在不满足第 3 项条件的对话中根本不读取任何设置文件。当 `claudeCode.claudeProcessWrapper` 被设置时，第 3 和 4 项也不适用：这些对话以 Manual 启动，除非第 1 或第 2 项设置权限模式。179 扩展永远不会从项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 读取起始权限模式。当 `claudeCode.claudeProcessWrapper` 被设置时，第 3 和 4 项不适用：这些对话以 Manual 启动，除非第 1 或第 2 项设置权限模式。

180

181 在 v2.1.283 之前，第 3 项仅在 Pro、Max 和 Team 计划上应用，在[获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话中。

184 182

185 当[自动模式可用](#eliminate-prompts-with-auto-mode)时，Auto 出现在模式指示器中。183 当[自动模式可用](#eliminate-prompts-with-auto-mode)时，Auto 出现在模式指示器中。

186 184

213 <Tab title="Web and mobile">211 <Tab title="Web and mobile">

214 在 [claude.ai/code](https://claude.ai/code) 或移动应用中使用提示框旁边的模式下拉菜单。权限提示出现在 claude.ai 中以供批准。显示哪些模式取决于会话在何处运行：212 在 [claude.ai/code](https://claude.ai/code) 或移动应用中使用提示框旁边的模式下拉菜单。权限提示出现在 claude.ai 中以供批准。显示哪些模式取决于会话在何处运行：

215 213

216 * **Cloud sessions** 在 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 上：Accept edits、Plan 和 Auto。Accept edits 对应于 `default` 模式：云会话预先批准文件编辑，无论模式如何，因此下拉菜单显示 Accept edits 而不是 Manual。云会话仍然遵守设置中的 `defaultMode: "acceptEdits"`。Auto 模式仅在您的组织允许且所选模型支持时出现。Bypass permissions 不可用。214 * **[Cloud sessions](/docs/zh-CN/claude-code-on-the-web)**：Accept edits、Plan 和 Auto。Accept edits 对应于 `default` 模式：云会话预先批准文件编辑，无论模式如何，因此下拉菜单显示 Accept edits 而不是 Manual。云会话仍然遵守设置中的 `defaultMode: "acceptEdits"`。Auto 模式仅在您的组织允许且所选模型支持时出现。Bypass permissions 不可用。

217 * **[Remote Control](/docs/zh-CN/remote-control) sessions** 在您的本地机器上：Manual、Accept edits 和 Plan。您无法从应用中选择 Auto 或 Bypass permissions。215 * **[Remote Control](/docs/zh-CN/remote-control) sessions** 在您的本地机器上：Manual、Accept edits 和 Plan（对于您自己启动的会话），您无法从应用中选择 Auto 或 Bypass permissions。对于在您的计算机上运行的项目线程，请参阅[在您自己的计算机上运行线程](/docs/zh-CN/claude-projects#run-a-thread-on-your-own-computer)。

218 * 除了 Bypass permissions，下拉菜单显示本地会话所在的权限模式，包括从终端设置的模式。它在应用或终端中权限模式更改时更新。会话永远不会向 claude.ai 报告 Bypass permissions，因此从终端切换到它不会改变下拉菜单显示的内容。216 * 除了 Bypass permissions，下拉菜单显示本地会话所在的权限模式，包括从终端设置的模式。它在应用或终端中权限模式更改时更新。

219 * 由[桌面应用](/docs/zh-CN/desktop)或 [VS Code 扩展](/docs/zh-CN/vs-code)托管的会话在权限模式更改时向 claude.ai 报告，与在终端中托管的会话相同。217 * 由[桌面应用](/docs/zh-CN/desktop)或 [VS Code 扩展](/docs/zh-CN/vs-code)托管的会话在权限模式更改时向 claude.ai 报告，与在终端中托管的会话相同。

220 * 在 v2.1.202 之前，使用 `/remote-control` 或 `claude --remote-control` 连接的会话根本不报告其权限模式，因此 claude.ai 和移动应用可能显示会话不在的权限模式。不匹配仅影响标签。Claude Code 从会话的实际权限模式生成权限提示，它们仍然出现在应用中以供批准。218 * 在 v2.1.202 之前，使用 `/remote-control` 或 `claude --remote-control` 连接的会话根本不报告其权限模式，因此 claude.ai 和移动应用可能显示会话不在的权限模式。不匹配仅影响标签。Claude Code 从会话的实际权限模式生成权限提示，它们仍然出现在应用中以供批准。

221 219

233 231

234`acceptEdits` 模式让 Claude 在您的工作目录中创建和编辑文件而无需提示。当此模式处于活动状态时，状态栏显示 `⏵⏵ accept edits on`。232`acceptEdits` 模式让 Claude 在您的工作目录中创建和编辑文件而无需提示。当此模式处于活动状态时，状态栏显示 `⏵⏵ accept edits on`。

235 233

236除了文件编辑外，`acceptEdits` 模式还自动批准常见的文件系统 Bash 命令：`mkdir`、`touch`、`rm`、`rmdir`、`mv`、`cp` 和 `sed`。当这些命令带有安全环境变量（如 `LANG=C` 或 `NO_COLOR=1`）或进程包装器（如 `timeout`、`nice` 或 `nohup`）作为前缀时，也会自动批准。与文件编辑一样，自动批准仅适用于工作目录或 `additionalDirectories` 内的路径。超出该范围的路径、对[受保护路径](#protected-paths)的写入、`rm` 和 `rmdir` 移除针对[关键路径](#critical-paths)的操作以及所有其他 Bash 命令（除了[内置只读集合](/docs/zh-CN/permissions#read-only-commands)）仍然会提示。234除了文件编辑外，`acceptEdits` 模式还自动批准常见的文件系统 Bash 命令：`mkdir`、`touch`、`rm`、`rmdir`、`mv`、`cp` 和 `sed`。当这些命令带有安全环境变量（如 `LANG=C` 或 `NO_COLOR=1`）或进程包装器（如 `timeout`、`nice` 或 `nohup`）作为前缀时，也会自动批准。与文件编辑一样，自动批准仅适用于工作目录或 `additionalDirectories` 内的路径。

235

236每个路径也会经过[符号链接检查](/docs/zh-CN/permissions#symlinks)，因此解析到该范围之外的写入也不会自动批准。超出该范围的路径、对[受保护路径](#protected-paths)的写入、`rm` 和 `rmdir` 移除针对[关键路径](#critical-paths)的操作以及所有其他 Bash 命令（除了[内置只读集合](/docs/zh-CN/permissions#read-only-commands)）仍然会提示。

237 237

238当启用 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)时，`acceptEdits` 模式还会自动批准 `Set-Content`、`Add-Content`、`Clear-Content` 和 `Remove-Item` 在范围内路径上的操作，以及它们的常见别名。相同的范围和受保护路径规则适用，`Remove-Item` 获得[自己的检查](#remove-item-in-powershell)。包含引号字符的位置参数，如 `Set-Content .\notes.txt "It's done"` 中的撇号，即使在范围内路径上也仍然会提示，因为 Claude Code 无法静态验证其引用和未引用读数不同的参数。通过命名参数（如 `-Value`）传递内容以避免提示。238当启用 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)时，`acceptEdits` 模式还会自动批准 `Set-Content`、`Add-Content`、`Clear-Content` 和 `Remove-Item` 在范围内路径上的操作，以及它们的常见别名。相同的范围和受保护路径规则适用，`Remove-Item` 获得[自己的检查](#remove-item-in-powershell)。包含引号字符的位置参数，如 `Set-Content .\notes.txt "It's done"` 中的撇号，即使在范围内路径上也仍然会提示，因为 Claude Code 无法静态验证其引用和未引用读数不同的参数。通过命名参数（如 `-Value`）传递内容以避免提示。

239 239

251 251

252Plan mode 告诉 Claude 研究并提议更改而不进行编辑。Claude 读取文件、运行 shell 命令进行探索并编写计划，但不编辑您的源代码。除了在[绕过权限可用](#skip-all-checks-with-bypasspermissions-mode)的交互式终端会话中，编辑保持阻止状态，直到您批准计划。252Plan mode 告诉 Claude 研究并提议更改而不进行编辑。Claude 读取文件、运行 shell 命令进行探索并编写计划，但不编辑您的源代码。除了在[绕过权限可用](#skip-all-checks-with-bypasspermissions-mode)的交互式终端会话中，编辑保持阻止状态，直到您批准计划。

253 253

254当[自动模式](/docs/zh-CN/auto-mode-config)可用且 `useAutoModeDuringPlan` 设置打开（默认情况下是这样）时，分类器在规划期间审查 shell 命令而不是提示您。批准的命令运行，拒绝的命令被阻止。否则，[内置只读集合](/docs/zh-CN/permissions#read-only-commands)外的命令会提示批准，包括当沙箱的[自动允许模式](/docs/zh-CN/sandboxing#sandbox-modes)启用时。在绕过权限可用的交互式终端会话中，分类器和提示都不适用于规划命令；[使用 bypassPermissions 模式跳过所有检查](#skip-all-checks-with-bypasspermissions-mode)涵盖仍会在那里提示的少数事项。在 v2.1.212 到 v2.1.217 中，没有绕过权限的会话为只读集合外的每个命令提示，无论自动模式是否可用。254shell 命令在规划期间发生的情况取决于会话，以下第一个匹配的情况适用：

255

256* **具有可用绕过权限的交互式终端会话**：分类器和提示都不适用于规划命令。[使用 bypassPermissions 模式跳过所有检查](#skip-all-checks-with-bypasspermissions-mode)涵盖仍会在那里提示的少数事项。

257* **[Auto mode](/docs/zh-CN/auto-mode-config)可用且 `useAutoModeDuringPlan` 设置打开**，默认情况下是这样：分类器审查 shell 命令（除了[关键路径移除](#critical-paths)）而不是提示您。批准的命令运行，拒绝的命令被阻止。

258* **Auto mode 不可用，或 `useAutoModeDuringPlan` 关闭**：[内置只读集合](/docs/zh-CN/permissions#read-only-commands)外的命令会提示批准，包括当沙箱的[自动允许模式](/docs/zh-CN/sandboxing#sandbox-modes)启用时。

255 259

256通过按 `Shift+Tab` 或在单个提示前加上 `/plan` 进入 plan mode。您也可以从 CLI 启动 plan mode：260通过按 `Shift+Tab` 或在单个提示前加上 `/plan` 进入 plan mode。您也可以从 CLI 启动 plan mode：

257 261

287 使用自动模式消除权限提示291 使用自动模式消除权限提示

288</h2>292</h2>

289 293

290自动模式让 Claude 无需常规权限提示即可执行。一个独立的分类器模型在操作运行前审查这些操作，阻止任何超出您请求范围、针对无法识别的基础设施或看起来由 Claude 读取的恶意内容驱动的操作。显式的[询问规则](/docs/zh-CN/permissions#manage-permissions)仍然会强制显示提示。294自动模式让 Claude 无需常规权限提示即可执行。一个独立的分类器模型在操作运行前审查这些操作，阻止任何超出您请求范围、针对无法识别的基础设施或看起来由 Claude 读取的恶意内容驱动的操作。显式的[询问规则](/docs/zh-CN/permissions#manage-permissions)仍会强制显示提示。

291 295

292在 Pro、Max 和 Team 计划上，自动模式是[会话启动时的内置权限模式](#which-mode-a-session-starts-in)。296在 Claude Code v2.1.283 或更高版本中，自动模式是所有计划和提供商的交互式终端和 VS Code 会话的[内置起始权限模式](#which-mode-a-session-starts-in)。在早期版本中，它仅在 Pro、Max 和 Team 计划上是内置起始权限模式。

293 297

294分类器还会审查 Claude 使用 [`SendMessage`](/docs/zh-CN/tools-reference) 发送给另一个代理的每条消息，无论是纯文本还是结构化的[代理团队](/docs/zh-CN/agent-teams)消息，在 Claude Code 交付之前，无论是在自动模式还是在[计划模式中分类器审查命令](#analyze-before-you-edit-with-plan-mode)时；发送审查需要 Claude Code v2.1.222 或更高版本。298分类器还会审查 Claude 使用 [`SendMessage`](/docs/zh-CN/tools-reference) 发送给另一个代理的每条消息，无论是纯文本还是结构化的[代理团队](/docs/zh-CN/agent-teams)消息，在 Claude Code 传递之前，既在自动模式中也在[计划模式中分类器审查命令](#analyze-before-you-edit-with-plan-mode)时；发送审查需要 Claude Code v2.1.222 或更高版本。

295 299

296分类器还会审查并批准或阻止针对[关键路径](#critical-paths)的 `rm` 和 `rmdir` 删除，例如 `rm -rf /` 和 `rm -rf ~`，包括当删除位于命令或进程替换内部时。300默认情况下，分类器不审查针对关键路径的 `rm` 和 `rmdir` 删除，例如 `rm -rf /` 或 `rm -rf ~`。[关键路径](#critical-paths)涵盖在每种权限模式中对它们的处理。

297 301

298自动模式还会促使 Claude 继续工作而不停下来提出澄清问题，尽管当您的提示或技能明确依赖它时 Claude 仍然会提问。为了在仍然提示您的模式中获得更强的自主行为，请改为设置[主动输出风格](/docs/zh-CN/output-styles)。302自动模式还会促使 Claude 继续工作而不停下来提出澄清问题，尽管当您的提示或技能明确依赖它时 Claude 仍会询问。为了在仍会提示您的模式中获得更强的自主行为，请改为设置[主动输出风格](/docs/zh-CN/output-styles)。

299 303

300<Warning>304<Warning>

301 自动模式减少了权限提示，但不保证安全。将其用于您信任总体方向的任务，而不是作为敏感操作审查的替代品。305 自动模式减少了权限提示，但不保证安全。将其用于您信任总体方向的任务，而不是作为敏感操作审查的替代品。

305 309

306* **计划**：所有计划。310* **计划**：所有计划。

307* **组织**：在 Team 和 Enterprise 上，自动模式默认可用。管理员可以通过在[托管设置](/docs/zh-CN/managed-settings)中将 `permissions.disableAutoMode` 设置为 `"disable"` 来为组织关闭它。311* **组织**：在 Team 和 Enterprise 上，自动模式默认可用。管理员可以通过在[托管设置](/docs/zh-CN/managed-settings)中将 `permissions.disableAutoMode` 设置为 `"disable"` 来为组织关闭它。

308* **模型**：在 Anthropic API 和 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 上，Claude Opus 4.6 或更高版本、Sonnet 4.6 或更高版本，或[Fable 模型](/docs/zh-CN/model-config#work-with-fable)。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)会话上，仅支持 Claude Sonnet 5、Opus 4.7 或更高版本以及 Fable 模型。较旧的模型，包括 Sonnet 4.5、Opus 4.5、Haiku 和 claude-3 模型，在任何提供商上都不受支持。312* **模型**：在 Anthropic API 和 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 上，Claude Opus 4.6 或更高版本、Sonnet 4.6 或更高版本，或[Fable 模型](/docs/zh-CN/model-config#work-with-fable)。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)会话上，仅 Claude Sonnet 5、Opus 4.7 或更高版本和 Fable 模型。较旧的模型，包括 Sonnet 4.5、Opus 4.5、Haiku 和 claude-3 模型，在任何提供商上都不受支持。

309* **提供商**：在 Anthropic API、AWS 上的 Claude Platform、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的 Claude 应用网关会话上默认可用。313* **提供商**：在 Anthropic API、AWS 上的 Claude Platform、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的 Claude 应用网关会话上默认可用。

310 314

311如果 Claude Code 报告自动模式不可用，首先检查这些要求以及任何设置文件是否设置了 [`disableAutoMode`](/docs/zh-CN/settings-reference#disableautomode)。Anthropic 也可能已在服务器端关闭了自动模式，或者服务器可能为您的账户拒绝了自动模式。接收到任一答案的会话会保持自动模式关闭，直到会话结束，因此请稍后启动新会话。315如果 Claude Code 报告自动模式不可用，首先检查这些要求以及任何设置文件是否设置了 [`disableAutoMode`](/docs/zh-CN/settings-reference#disableautomode)。Anthropic 也可能已在服务器端关闭了自动模式，或服务器可能为您的账户拒绝了自动模式。收到任一答案的会话会保持自动模式关闭直到会话结束，因此稍后启动新会话。

312 316

313一条单独的消息，其中命名了一个模型并说自动模式"无法确定"操作的安全性，意味着分类器请求失败。该失败通常是暂时的，但在 Amazon Bedrock 上，它可能会重复，直到您的账户可以调用命名的模型。有关原因和处理方法，请参阅[错误参考](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)。317一条单独的消息命名一个模型并说自动模式"无法确定"操作的安全性意味着分类器请求失败。该失败通常是暂时的，但在 Amazon Bedrock 上，它可能会重复直到您的账户可以调用命名的模型。有关原因和处理方法，请参阅[错误参考](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)。

314 318

315如果您在[设置](/docs/zh-CN/settings-reference#all-settings)中设置了 `defaultMode: "auto"`，而终端会话在没有错误的情况下以手动模式启动，则该设置可能在 `.claude/settings.json` 或 `.claude/settings.local.json` 中。`auto` 不会从这些文件生效。将其移至 `~/.claude/settings.json`。对于 VS Code 扩展启动的对话，请改为检查扩展自己的列表[切换权限模式](#switch-permission-modes)。319如果您在[设置](/docs/zh-CN/settings-reference#all-settings)中设置 `defaultMode: "auto"` 并且终端会话在没有错误的情况下以手动模式启动，该设置可能在 `.claude/settings.json` 或 `.claude/settings.local.json` 中。`auto` 不会从这些文件生效。将其移至 `~/.claude/settings.json`。对于 VS Code 扩展启动的对话，请改为检查扩展自己的列表在[切换权限模式](#switch-permission-modes)中。

316 320

317<h3 id="enable-auto-mode-on-bedrock-agent-platform-or-foundry">321<h3 id="enable-auto-mode-on-bedrock-agent-platform-or-foundry">

318 Bedrock、Agent Platform 或 Foundry 上的自动模式322 Bedrock、Agent Platform 或 Foundry 上的自动模式

319</h3>323</h3>

320 324

321在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai)、[Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 和已登录的[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)会话上，自动模式默认出现在 `Shift+Tab` 循环中。出现在循环中不会改变会话启动时的权限模式：在这些提供商上，终端会话以您的 [`defaultMode`](/docs/zh-CN/settings-reference#permissions-defaultmode) 启动，除非您更改它，否则为手动模式，而[VS Code 扩展](/docs/zh-CN/vs-code)中的对话以手动模式启动，除非 `claudeCode.initialPermissionMode` 或您在扩展中选择的模式设置了一个。这些提供商上仅支持 Claude Sonnet 5、Opus 4.7 或更高版本以及 Fable 模型。325在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai)、[Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 和已登录的[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)会话上，自动模式默认可用。在 Claude Code v2.1.283 或更高版本中，它也是交互式终端和 [VS Code](/docs/zh-CN/vs-code) 会话的[内置起始权限模式](#which-mode-a-session-starts-in)。要自己选择起始权限模式，请按照[以不同权限模式启动](#start-in-a-different-mode)的描述设置 `permissions.defaultMode`，或从 VS Code 扩展的模式指示器中选择权限模式。

322 326

323要使自动模式成为默认启动权限模式，请在用户或托管设置中设置 `"permissions": {"defaultMode": "auto"}`。在 VS Code 扩展启动的会话中，改为从模式指示器中选择**自动**。[切换权限模式](#switch-permission-modes)涵盖了什么会优先于该选择。327这些提供商仅支持 Claude Sonnet 5、Opus 4.7 或更高版本和 Fable 模型。在任何其他模型上，会话以手动模式启动。

324 328

325[`/doctor`](/docs/zh-CN/commands#all-commands) 检查在这些提供商上提议此用户设置默认值，就像在 Anthropic API 上一样。329要防止开发人员使用自动模式，请在[托管设置](/docs/zh-CN/managed-settings)中将 `disableAutoMode` 设置为 `"disable"`。这会从 `Shift+Tab` 循环中移除 `auto`，并且使用 `--permission-mode auto` 启动的会话会改为以手动模式启动。已在自动模式中运行的会话在设置从[管理员部署的源](/docs/zh-CN/managed-settings#which-managed-source-claude-code-uses)到达该会话时会离开它，并显示 `auto mode disabled by settings`。在 v2.1.251 之前，运行中的会话会保持自动模式直到它结束。

326 330

327要防止开发人员使用自动模式，请在[托管设置](/docs/zh-CN/managed-settings)中将 `disableAutoMode` 设置为 `"disable"`。这会从 `Shift+Tab` 循环中删除 `auto`，并且使用 `--permission-mode auto` 启动的会话以手动模式启动。已在自动模式中运行的会话在设置从[管理员部署的源](/docs/zh-CN/managed-settings#which-managed-source-claude-code-uses)到达该会话时会离开它，并显示 `auto mode disabled by settings`。在 v2.1.251 之前，运行中的会话会保持自动模式直到结束。331在 v2.1.158 到 v2.1.206 中，这些提供商上的自动模式是关闭的，直到您设置 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`，并且 Claude Code 在这些提供商上忽略 `defaultMode: "auto"`，除非也设置了该变量。该变量仍被接受以保持兼容性，从 v2.1.207 开始无效。

~~328~~

329在 v2.1.158 到 v2.1.206 中，这些提供商上的自动模式处于关闭状态，直到您设置 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`，并且 Claude Code 在这些提供商上忽略 `defaultMode: "auto"`，除非也设置了该变量。该变量仍然被接受以保持兼容性，从 v2.1.207 开始无效。

330 332

331<h3 id="server-side-classifier-review">333<h3 id="server-side-classifier-review">

332 服务器端分类器审查334 服务器端分类器审查

333</h3>335</h3>

334 336

335在自动模式中，Claude Code 可以要求服务器检查[决策顺序](#how-the-classifier-evaluates-actions)发送的操作以供审查，作为会话模型请求的一部分，而不是发送自己的分类器请求。这些会话要求：337在自动模式中，Claude Code 可以要求服务器检查[决策顺序](#how-the-classifier-evaluates-actions)发送的操作以供审查，作为会话模型请求的一部分，而不是发送自己的分类器请求。这些会话询问：

336 338

337* **直接连接到 Anthropic API**：在交互式终端会话中，在每个 claude.ai 计划和使用 Claude API 的账户上，随着 Anthropic 推出。在 Pro、Max 和 Team 计划上需要 Claude Code v2.1.271 或更高版本，在 Enterprise 计划和 Claude API 账户上需要 v2.1.278 或更高版本。从 v2.1.282 开始，[不获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话，例如因为您关闭了遥测，在任何类型的会话中默认询问服务器。339* **直接连接到 Anthropic API**：在交互式终端会话中，在每个 claude.ai 计划和使用 Claude API 的账户上，随着 Anthropic 推出。在 Pro、Max 和 Team 计划上需要 Claude Code v2.1.271 或更高版本，在 Enterprise 计划和 Claude API 账户上需要 v2.1.278 或更高版本。从 v2.1.282 开始，[不获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话，例如因为您关闭了遥测，在任何类型的会话中默认询问服务器。

338* **云提供商、LLM 网关或代理**：在 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws)、Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，以及每当您将 `ANTHROPIC_BASE_URL` 指向[LLM 网关或代理](/docs/zh-CN/llm-gateway)时，无论您的计划如何。默认询问需要 Claude Code v2.1.278 或更高版本。340* **云提供商、LLM 网关或代理**：在 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws)、Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，以及每当您将 `ANTHROPIC_BASE_URL` 指向[LLM 网关或代理](/docs/zh-CN/llm-gateway)时，无论您的计划如何。默认询问需要 Claude Code v2.1.278 或更高版本。

339* **已登录的[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)会话**：需要 Claude Code v2.1.280 或更高版本341* **已登录的[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)会话**：需要 Claude Code v2.1.280 或更高版本

340 342

341服务器审查操作的地方，其判决决定这些操作。另外两种结果是可能的：343服务器审查操作的地方，其判决决定了它们。另外两种结果是可能的：

342 344

343* **服务器不审查会话**：响应完成时没有审查结果，或服务器回答它不审查此会话。最常见的原因是 LLM 网关或代理丢弃了审查请求或结果，以及平台、区域或凭证还没有服务器端检查。Claude Code 回退到自己的分类器请求。一旦该回退在会话的其余部分保持，它会在这些请求被计费的账户上显示[关于分类器请求费用的通知](/docs/zh-CN/auto-mode-classifier-billing)。345* **服务器不审查会话**：响应完成时没有审查结果，或服务器回答它不审查此会话。最常见的原因是 LLM 网关或代理丢弃审查请求或结果，以及平台、区域或凭证还没有服务器端检查。Claude Code 回退到自己的分类器请求。一旦该回退对会话的其余部分生效，它会在那些请求被计费的账户上显示[关于分类器请求费用的通知](/docs/zh-CN/auto-mode-classifier-billing)。

344* **服务器对操作没有判决**：Claude Code 拒绝该操作而不是运行它未审查。在任何连接上，当响应在审查结果到达之前结束或结果以 Claude Code 无法读取的形式到达时，会发生这种情况。LLM 网关或代理可能会导致响应被截断或结果被重写。在直接连接到 Anthropic API 时，当服务器对操作的检查失败时也会发生，例如超时。[服务器返回了没有安全判决](/docs/zh-CN/errors#the-server-returned-no-safety-verdict)涵盖拒绝消息、拒绝重复时会发生什么以及处理方法。346* **服务器对操作没有给出判决**：Claude Code 拒绝该操作而不是未审查地运行它。在任何连接上，当响应在审查结果到达之前结束或结果以 Claude Code 无法读取的形式到达时，这会发生。丢弃响应或重写结果的 LLM 网关或代理可能导致任一情况。在直接连接到 Anthropic API 时，当服务器对操作的检查失败时也会发生，例如超时。[服务器未返回安全判决](/docs/zh-CN/errors#the-server-returned-no-safety-verdict)涵盖拒绝消息、拒绝重复时发生的情况以及处理方法。

345 347

346要跳过询问服务器并始终使用 Claude Code 自己的分类器请求，请设置 [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](/docs/zh-CN/env-vars)。在直接连接到 Anthropic API 时，该变量需要 Claude Code v2.1.281 或更高版本。将其设置为 `1` 会在没有服务器审查的会话中打开服务器审查，例如 `-p` 或 Agent SDK 会话，除非您也设置了 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`。如果您设置了 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` 并保持 `CLAUDE_CODE_AUTO_MODE_SERVER` 未设置，Claude Code 也会停止询问服务器。348要跳过询问服务器并始终使用 Claude Code 自己的分类器请求，请设置 [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](/docs/zh-CN/env-vars)。在直接连接到 Anthropic API 时，该变量需要 Claude Code v2.1.281 或更高版本。将其设置为 `1` 会在没有它的会话中打开服务器审查，例如 `-p` 或 Agent SDK 会话，除非您也设置了 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`。如果您设置 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` 并保持 `CLAUDE_CODE_AUTO_MODE_SERVER` 未设置，Claude Code 也会停止询问服务器，除了[禁用预发布功能](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities)描述的情况。

347 349

348<h3 id="what-the-classifier-blocks-by-default">350<h3 id="what-the-classifier-blocks-by-default">

349 分类器默认阻止的内容351 分类器默认阻止的内容

350</h3>352</h3>

351 353

352分类器信任您的工作目录和在会话启动时为其配置的远程。在会话期间使用 `git remote add` 或 `git remote set-url` 添加或重新指向的远程不受信任，其他所有内容都被视为外部，直到您[配置受信任的基础设施](/docs/zh-CN/auto-mode-config)。在 v2.1.200 之前，会话中期添加的远程也受信任。354分类器信任您的工作目录和会话启动时为其配置的远程。在会话期间使用 `git remote add` 或 `git remote set-url` 添加或重新指向的远程不受信任，其他所有内容都被视为外部，直到您[配置受信任的基础设施](/docs/zh-CN/auto-mode-config)。在 v2.1.200 之前，会话中期添加的远程也受信任。

353 355

354**默认阻止**：356**默认阻止**：

355 357

361* 修改共享基础设施363* 修改共享基础设施

362* 不可逆地销毁会话前存在的文件364* 不可逆地销毁会话前存在的文件

363* 强制推送365* 强制推送

364* 提交或推送会在运行时向仓库外发送秘密或敏感数据的更改，或扩大部署公开的内容。这涵盖了将秘密交给不已接收它的目标的 CI 工作流或部署配置、读取秘密存储并发送数据的脚本或设置步骤，以及扩大部署发布内容的配置更改，例如注册表、可见性、工件或源映射设置。检查适用于任何分支，即使仓库是公开的也适用，并在更改落地时触发，无论该落地是否触发管道；清除它需要命名执行效果，而不仅仅是提交或推送。在 v2.1.211 之前，此检查的范围仅限于默认分支：推送到那里时，如果携带敏感内容、相对于您要求的隐藏或误描述的更改、从仓库外移植的内容或绕过您要求的审查的内容，则被阻止366* 提交或推送会在运行时向仓库外发送秘密或敏感数据的更改，或扩大部署公开的内容。这涵盖将秘密传递给不已接收它的目的地的 CI 工作流或部署配置、读取秘密存储并发送数据的脚本或设置步骤，以及扩大部署发布内容的配置更改，例如注册表、可见性、工件或源映射设置。检查适用于任何分支，即使仓库是公开的也适用，并在提交或推送时触发，无论该提交或推送是否触发管道；清除它需要命名执行效果，而不仅仅是提交或推送。在 v2.1.211 之前，此检查的范围仅限于默认分支：当它携带敏感内容、相对于您要求的隐藏或误描述的更改、从仓库外移植的内容或绕过您要求的审查的内容时，推送那里被阻止

365* `git reset --hard`、`git checkout -- .`、`git restore .`、`git clean -fd`、`git stash drop` 或 `git stash clear`，分类器假设这会丢弃未提交的更改367* `git reset --hard`、`git checkout -- .`、`git restore .`、`git clean -fd`、`git stash drop` 或 `git stash clear`，分类器假设会丢弃未提交的更改

366* 当 HEAD 处的提交不是在此会话中创建时的 `git commit --amend`368* `git commit --amend` 当 HEAD 处的提交不是在此会话中创建的

367* 从 v2.1.198 开始，当 HEAD 处的提交已被推送时的 `git commit --amend`。仅消息改写不被阻止：`--amend -m` 在没有新暂存内容的情况下，对于 Claude 在此会话期间创建的提交369* 从 v2.1.198 开始，`git commit --amend` 当 HEAD 处的提交已被推送时。仅消息重述不被阻止：`--amend -m` 在没有新暂存的情况下，对于 Claude 在此会话期间创建的提交

368* `terraform destroy`、`pulumi destroy`、`cdk destroy` 或 `terragrunt destroy`，以及应用销毁资源的计划370* `terraform destroy`、`pulumi destroy`、`cdk destroy` 或 `terragrunt destroy`，以及应用销毁资源的计划

369 371

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

373* 合并没有人类批准的拉取请求、批准 Claude 自己的拉取请求或禁用 CI 检查375* 合并没有人类批准的拉取请求、批准 Claude 自己的拉取请求或禁用 CI 检查

374* 发布本身是自动化命令的评论，例如 `atlantis apply` 或机器人的 `/deploy` 或 `/merge`376* 发布本身是自动化命令的评论，例如 `atlantis apply` 或机器人的 `/deploy` 或 `/merge`

375* 切换、调整或删除生产功能标志377* 切换、调整或删除生产功能标志

376* 将基础设施更改应用于受保护的 IaC 范围，或排空和删除集群节点378* 将基础设施更改应用于受保护的 IaC 范围，或排空和移除集群节点

377* 对共享计算集群的写入超出您命名的资源，例如标签选择器或 `--all` 捕获其他用户的作业379* 写入超出您命名的资源的共享计算集群，例如标签选择器或捕获其他用户作业的 `--all`

378* 创建在每个节点上运行或拦截集群流量的 Kubernetes 资源，例如 DaemonSets 和准入 webhooks380* 创建在每个节点上运行或拦截集群流量的 Kubernetes 资源，例如 DaemonSets 和准入 webhooks

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

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

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

382* 访问在您的[环境](/docs/zh-CN/auto-mode-config#define-trusted-infrastructure)中列为敏感数据位置的位置，或从其中复制数据。从 v2.1.198 开始，这也会阻止从一个位置向条目排除的受众发送数据384* 访问在您的[环境](/docs/zh-CN/auto-mode-config#define-trusted-infrastructure)中列为敏感数据位置的位置，或从其中复制数据。从 v2.1.198 开始，这也阻止从一个向条目排除的受众发送数据

383* 绕过您的内部包注册表路由包安装到公开注册表。从 v2.1.198 开始，这也适用于您在对话中告诉 Claude 存在内部注册表或镜像的情况，而不仅仅是在您的环境中列出的情况385* 绕过您的内部包注册表将包安装路由到公共注册表。从 v2.1.198 开始，这也适用于您在对话中告诉 Claude 内部注册表或镜像存在的情况，而不仅仅是在您的环境中列出的情况

384* 使用禁用安全防护的标志运行命令，如 `--insecure`386* 使用禁用安全防护的标志运行命令，如 `--insecure`

385* 启动在没有人类批准或沙箱的情况下运行的自主代理循环，例如使用 `--dangerously-skip-permissions` 或 `--no-sandbox` 启动的循环。从 v2.1.198 开始，这也涵盖运行禁用隔离和按操作批准的第三方代理或评估工具，例如使用 `--yes-always` 启动的运行器387* 启动在没有人类批准或沙箱的情况下运行的自主代理循环，例如使用 `--dangerously-skip-permissions` 或 `--no-sandbox` 启动的循环。从 v2.1.198 开始，这也涵盖运行禁用隔离和按操作批准的第三方代理或评估工具，例如使用 `--yes-always` 启动的运行器

386* [Chrome 中的 Claude](/docs/zh-CN/chrome)浏览器操作可能会向外源发送页面内容、cookie 或凭证388* [Chrome 中的 Claude](/docs/zh-CN/chrome)浏览器操作可能会向源外发送页面内容、cookie 或凭证

387 389

388Claude Code v2.1.198 及更高版本也默认阻止这些：390Claude Code v2.1.198 及更高版本也默认阻止这些：

389 391

390* 通过通配符、glob 或年龄过滤器而不是特定命名路径删除 `/tmp`、`$TMPDIR` 或其他共享暂存或缓存目录中的文件392* 通过通配符、glob 或年龄过滤器而不是特定命名路径删除 `/tmp`、`$TMPDIR` 或其他共享暂存或缓存目录中的文件

391* 在您自己的消息未授权这些详细信息给该收件人时，在发送、上传、发布或写入给其他人或共享系统的内容中包含敏感详细信息。当仓库在信任边界外或公开时，PR 和问题正文、提交消息和评论计为这种类型的出站内容，包括您组织自己的公开仓库；内部文件路径、代码名称、实时 API 响应数据（如电子邮件或账户标识符）和基础设施标识符计为敏感详细信息。PR、问题和提交消息范围需要 Claude Code v2.1.200 或更高版本。PR 或问题正文中的实时个人数据（如电子邮件地址、账户或组织标识符或使用指标）需要您命名这些详细信息和收件人，无论仓库的可见性或信任边界如何。该检查需要 Claude Code v2.1.203 或更高版本393* 在您自己的消息未授权这些详情给该收件人的情况下，将敏感详情包含在发送、上传、发布或写入其他人或共享系统的内容中。PR 和问题正文、提交消息和评论在仓库在信任边界外或公开时计为这种出站内容，包括您组织自己的公开仓库；内部文件路径、代码名称、实时 API 响应数据（如电子邮件或账户标识符）和基础设施标识符计为敏感详情。PR、问题和提交消息范围需要 Claude Code v2.1.200 或更高版本。PR 或问题正文中的实时个人数据（如电子邮件地址、账户或组织标识符或使用指标）需要您命名这些详情和收件人，无论仓库的可见性或信任边界如何。该检查需要 Claude Code v2.1.203 或更高版本

392* 向 Claude Code 自己的 tmux 窗格发送按键以驱动其自己的界面，分类器将其视为 Claude 更改自己的权限或监督394* 向 Claude Code 自己的 tmux 窗格发送按键以驱动其自己的界面，分类器将其视为 Claude 更改自己的权限或监督

393 395

394Claude Code v2.1.200 及更高版本也默认阻止这些：396Claude Code v2.1.200 及更高版本也默认阻止这些：

395 397

396* 注释掉、删除或强制通过保护安全行为的测试或断言，例如身份验证、访问控制、输入验证或沙箱398* 注释掉、删除或强制通过保护安全行为的测试或断言，例如身份验证、访问控制、输入验证或沙箱

397* 删除或拆除 Claude 在会话中未创建的有状态资源，当没有更具体的删除规则适用且您未命名该资源时399* 删除或拆除 Claude 在会话中未创建的有状态资源，当没有更具体的删除规则适用且您未命名该资源时

398* 在不适合任务的第三方主机处重新指向 API 基础 URL、代理端点、webhook 接收器或注册表镜像，包括在 `.env.example` 等示例文件中400* 将 API 基础 URL、代理端点、webhook 接收器或注册表镜像重新指向不适合任务的第三方主机，包括在 `.env.example` 等示例文件中

399* 使用 `git remote set-url` 或 `git remote add` 更改推送去向，除非您命名了新远程401* 使用 `git remote set-url` 或 `git remote add` 更改推送去向，除非您命名了新远程

400* 推送秘密或个人或受信任的数据到已知为公开的仓库，或推送不属于该仓库自己工作的机密材料。dotfiles 仓库自己的主题是个人或受信任数据的唯一例外，来自私有仓库到任何公开表面的内容以相同方式被阻止；两项改进都需要 Claude Code v2.1.203 或更高版本。在 v2.1.203 之前，个人数据与机密材料分组，仅当它不属于该仓库自己的工作时才被阻止。当仓库的可见性未确定时，分类器不会仅凭这一点就阻止；它改为根据其他规则判断内容402* 推送秘密或个人或受信任的数据到已知为公开的仓库，或推送不属于该仓库自己工作的机密材料。dotfiles 仓库自己的主题是个人或受信任数据的唯一例外，来自私有仓库到任何公开表面的内容以相同方式被阻止；两项改进都需要 Claude Code v2.1.203 或更高版本。在 v2.1.203 之前，个人数据与机密材料分组，仅当它不属于该仓库自己的工作时才被阻止。当仓库的可见性未确定时，分类器不仅基于此阻止；它改为根据其他规则判断内容

401* 针对不同的仓库或组织打开拉取请求、使用 `gh repo fork` 进行分叉或推送到第三方仓库，除非您命名了该外部目标403* 针对不同仓库或组织打开拉取请求、使用 `gh repo fork` 分叉或推送到第三方仓库，除非您命名了该外部目标

402 404

403Claude Code v2.1.203 及更高版本也默认阻止这些：405Claude Code v2.1.203 及更高版本也默认阻止这些：

404 406

405* 来自敏感本地存储或其名称、路径或类型将其标记为敏感的文件的内容进入提交、推送、PR 或问题文本、gist 或粘贴或包发布，除非您命名了源和目标。会话记录和对话日志、凭证和配置点文件夹（如 SSH 密钥、云凭证、浏览器配置文件和 shell 历史记录）以及用户数据导出都计为此，仓库是私有的不会清除它407* 来自敏感本地存储或其名称、路径或类型将其标记为敏感的文件的内容进入提交、推送、PR 或问题文本、gist 或粘贴或包发布，除非您命名了源和目的地。会话记录和对话日志、凭证和配置点文件夹（如 SSH 密钥、云凭证、浏览器配置文件和 shell 历史记录）以及用户数据导出都计为此，仓库是私有的不会清除它

406 408

407Claude Code v2.1.205 及更高版本也默认阻止这些：409Claude Code v2.1.205 及更高版本也默认阻止这些：

408 410

409* 写入 Claude Code 会话记录，即 `~/.claude/projects/` 或您配置的配置目录下的 `.jsonl` 历史文件，无论是直接还是通过 shell 命令。该规则也涵盖 Claude Code 为其自己的检查附加到每个记录条目的元数据行。读取记录不被阻止411* 写入 Claude Code 会话记录、`~/.claude/projects/` 下的 `.jsonl` 历史文件或您配置的配置目录，无论是直接还是通过 shell 命令。该规则也涵盖 Claude Code 为其自己的检查附加到每个记录条目的元数据行。读取记录不被阻止

410* 递归强制删除，例如 `rm -rf "$VAR"` 或 `Remove-Item -Recurse -Force $dir`，其目标是分类器看不到在对话中任何地方分配的 shell 变量，或以一个为根的 glob。该值仅来自较早的命令输出，分类器从不接收，因此分类器无法根据其他删除规则验证删除目标。当您命名被删除的确切路径或 Claude 使用解析的文字路径写入的命令重新运行删除时，该块会清除。目标分类器可以解析的删除不受影响。目标是裸 `*` 或以 `/*` 或 `\*` 结尾的 `Remove-Item` 目标永远不会到达分类器：Claude Code [直接拒绝它们](#remove-item-in-powershell)412* 递归强制删除，例如 `rm -rf "$VAR"` 或 `Remove-Item -Recurse -Force $dir`，其目标是在分类器看到的对话中任何地方都未分配的 shell 变量，或以这样的变量为根的 glob。该值仅来自较早的命令输出，分类器永远不会收到，因此分类器无法根据其他删除规则验证删除目标。当您命名被删除的确切路径或 Claude 使用解析的文字路径重新运行删除时，该块会清除。分类器可以解析其目标的删除不受影响。

413

414 直接在变量下的 glob，如 `rm -rf "$VAR"/*`，是[关键路径](#critical-paths)。`Remove-Item` 目标是裸 `*` 或以 `/*` 或 `\*` 结尾的永远不会到达分类器：Claude Code [直接拒绝它们](#remove-item-in-powershell)。

411 415

412Claude Code v2.1.257 及更高版本也默认阻止这些：416Claude Code v2.1.257 及更高版本也默认阻止这些：

413 417

428* 安装在您的锁定文件或清单中声明的依赖项432* 安装在您的锁定文件或清单中声明的依赖项

429* 读取 `.env` 并向其匹配的 API 发送凭证433* 读取 `.env` 并向其匹配的 API 发送凭证

430* 只读 HTTP 请求434* 只读 HTTP 请求

431* 推送到您正在处理的仓库的任何分支，包括默认分支。其名称将其标记为部署或发布目标的非默认分支，例如 `production` 或 `gh-pages`，不被涵盖：分类器根据其自己的条款判断推送到那里。推送的内容仍然根据其他规则进行检查，[`permissions.deny` 规则](/docs/zh-CN/permissions#manage-permissions)仍然可以在每种模式中[按书写](/docs/zh-CN/permissions#bash-rule-limits)阻止推送命令，远程自己的分支保护仍然适用。在 v2.1.211 之前，仅允许推送到您启动的分支、Claude 创建的分支和到默认分支的常规推送，在 v2.1.203 之前任何直接推送到默认分支都被阻止435* 推送到您正在处理的仓库的任何分支，包括默认分支。其名称将其标记为部署或发布目标的非默认分支，例如 `production` 或 `gh-pages`，不被涵盖：分类器根据其自己的条款判断推送。推送的内容仍根据其他规则进行检查，[`permissions.deny` 规则](/docs/zh-CN/permissions#manage-permissions)仍可以在每种模式中[按书写](/docs/zh-CN/permissions#bash-rule-limits)阻止推送命令，远程自己的分支保护仍适用。在 v2.1.211 之前，仅允许推送到您启动的分支、Claude 创建的分支和到默认分支的常规推送，在 v2.1.203 之前任何直接推送到默认分支都被阻止

432 436

433Claude Code v2.1.195 及更高版本也默认允许这些：437Claude Code v2.1.195 及更高版本也默认允许这些：

434 438

435* 删除 Claude 在同一会话中较早创建的确切作业439* 删除 Claude 在同一会话中较早创建的确切作业

436* 作为您的任务的一部分读取、审查或编写与安全相关的代码、配置和威胁模型440* 作为您的任务的一部分读取、审查或编写安全相关的代码、配置和威胁模型

437* 在同一多代理会话中一起工作的代理之间的消息441* 在同一多代理会话中一起工作的代理之间的消息

438* 向您在 [`environment`](/docs/zh-CN/auto-mode-config#define-trusted-infrastructure) 中列出的受信任域、存储桶和服务发送数据。这仅涵盖数据流，不涵盖同一基础设施上的破坏性或凭证操作442* 向您在 [`environment`](/docs/zh-CN/auto-mode-config#define-trusted-infrastructure) 中列出的受信任域、存储桶和服务发送数据。这仅涵盖数据流，不涵盖同一基础设施上的破坏性或凭证操作

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

440 444

441沙箱网络访问请求通过分类器路由，而不是默认允许。Claude 命名命令需要的主机，分类器与命令一起审查它们，批准的列表仅为该一个命令打开这些主机。[每个命令允许的域](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)涵盖列表可以和不能打开什么以及当命令到达未列出的主机时会发生什么。445沙箱命令默认不获得网络访问。Claude 在命令本身上命名命令需要的主机，分类器与命令一起审查它们，批准的列表仅为该一个命令打开这些主机。[按命令允许的域](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)涵盖列表可以和不能打开什么以及命令到达未列出的主机时发生的情况。

442 446

443运行 `claude auto-mode defaults` 以将完整规则列表打印为 JSON。如果常规操作被阻止，管理员可以通过 `autoMode.environment` 设置添加受信任的仓库、存储桶和服务：请参阅[配置自动模式](/docs/zh-CN/auto-mode-config)。447运行 `claude auto-mode defaults` 以将完整规则列表打印为 JSON。如果常规操作被阻止，管理员可以通过 `autoMode.environment` 设置添加受信任的仓库、存储桶和服务：请参阅[配置自动模式](/docs/zh-CN/auto-mode-config)。

444 448

448 工作目录外的第一次读取452 工作目录外的第一次读取

449</h3>453</h3>

450 454

451当 [`permissions.blockReadsOutsideWorkingDirectories`](/docs/zh-CN/settings-reference#permissions-blockreadsoutsideworkingdirectories) 关闭时，文件读取在自动模式中无需提示即可运行，包括在[工作目录](/docs/zh-CN/permissions#working-directories)外的读取。Claude 第一次在它们外的路径上使用 Read、Grep 或 Glob 工具时，Claude Code 会询问您是否继续允许这些读取。455当 [`permissions.blockReadsOutsideWorkingDirectories`](/docs/zh-CN/settings-reference#permissions-blockreadsoutsideworkingdirectories) 关闭时，文件读取在自动模式中无需提示即可运行，包括在[工作目录](/docs/zh-CN/permissions#working-directories)外的读取。Claude 第一次在它们外的路径上使用 Read、Grep 或 Glob 工具时，Claude Code 询问您是否继续允许这些读取。

452 456

453该提示不会出现在非交互式 `-p` 运行或后台会话中；那里的读取照常运行。457该提示不会出现在非交互式 `-p` 运行或后台会话中；那里的读取照常运行。

454 458

455无论您的答案如何，Claude 都会继续工作：459无论您的答案如何，Claude 继续工作：

456 460

457* **继续允许**：读取运行，工作目录外的后续读取照常运行，Claude Code 记录您的答案，以便提示不再出现461* **是，继续允许工作目录外的任何读取**：读取运行，工作目录外的后续读取照常运行，Claude Code 记录您的答案以便提示不再出现

458* **从现在开始阻止**：读取被拒绝，Claude Code 在您的用户设置中将 [`permissions.blockReadsOutsideWorkingDirectories`](/docs/zh-CN/settings-reference#permissions-blockreadsoutsideworkingdirectories) 设置为 `true`，这使文件工具在每个后续会话和每种权限模式中拒绝此类读取。要稍后让 Claude 读取此类路径，请使用 `/add-dir` 添加其目录或删除该设置。462* **否，从现在开始阻止工作目录外的读取**：读取被拒绝，Claude Code 在您的用户设置中将 [`permissions.blockReadsOutsideWorkingDirectories`](/docs/zh-CN/settings-reference#permissions-blockreadsoutsideworkingdirectories) 设置为 `true`，这使文件工具在每个后续会话和每种权限模式中拒绝此类读取。要稍后让 Claude 读取此类路径，请使用 `/add-dir` 添加其目录或移除该设置。

459* **下次再问**：读取被拒绝，工作目录外的下一次读取再次提示463* **否，下次再问**：读取被拒绝，工作目录外的下一次读取再次提示

464* **是，但下次再问**：读取运行，不保存任何内容，工作目录外的下一次读取再次提示

460 465

461<h3 id="boundaries-you-state-in-conversation">466<h3 id="boundaries-you-state-in-conversation">

462 您在对话中陈述的边界467 您在对话中陈述的边界

463</h3>468</h3>

464 469

465分类器将您在对话中陈述的边界视为阻止信号。如果您告诉 Claude"不要推送"或"在我审查后再部署"，分类器会阻止匹配的操作，即使默认规则会允许它们。边界保持有效，直到您在后续消息中解除它。Claude 自己的判断条件已满足不会解除它。470分类器将您在对话中陈述的边界视为阻止信号。如果您告诉 Claude"不要推送"或"在我审查后再部署"，分类器会阻止匹配的操作，即使默认规则会允许它们。边界保持有效直到您在后续消息中解除它。Claude 自己的条件已满足的判断不会解除它。

466 471

467边界不存储为规则。分类器在每次检查时从记录中重新读取它们，因此如果[上下文压缩](/docs/zh-CN/costs#reduce-token-usage)删除了陈述它的消息，边界可能会丢失。为了获得硬保证，请改为添加[拒绝规则](/docs/zh-CN/permissions#permission-rule-syntax)。472边界不作为规则存储。分类器在每次检查时从记录中重新读取它们，因此如果[上下文压缩](/docs/zh-CN/costs#reduce-token-usage)移除陈述边界的消息，边界可能会丢失。为了硬保证，请改为添加[拒绝规则](/docs/zh-CN/permissions#permission-rule-syntax)。

468 473

469<h3 id="approvals-you-state-in-conversation">474<h3 id="approvals-you-state-in-conversation">

470 您在对话中陈述的批准475 您在对话中陈述的批准

471</h3>476</h3>

472 477

473如果您告诉 Claude 被阻止的操作是允许的，分类器会将其读取为您的批准并可以清除阻止。您如何措辞决定了操作是否运行，以及批准的范围有多远：478如果您告诉 Claude 被阻止的操作是允许的，分类器将其读取为您的批准并可以清除阻止。您如何措辞决定了操作是否运行以及批准的范围有多远：

474 479

475* **命名操作及其具体情况**：您的消息必须命名操作和使其危险的具体事项，例如强制推送的分支。仅命名动词不会清除任何内容，因此"您可以强制推送"会使阻止保持原位。480* **命名操作及其具体情况**：您的消息必须命名操作和使其危险的具体事物，例如强制推送的分支。仅命名动词不会清除任何内容，因此"您可以强制推送"会使阻止保持原位。

476* **期望它涵盖一个操作**：批准涵盖您命名的破坏性操作，因此后续操作会再次被阻止，除非您将批准授予为常设。要停止一次一个地批准常规模式，请将其添加到 [`autoMode.allow`](/docs/zh-CN/auto-mode-config#override-the-block-and-allow-rules)。481* **期望它涵盖一个操作**：批准涵盖您命名的破坏性操作，因此后续操作再次被阻止，除非您授予批准为常设。要停止一次一个地批准常规模式，请将其添加到 [`autoMode.allow`](/docs/zh-CN/auto-mode-config#override-the-block-and-allow-rules)。

477* **某些阻止保持原位**：[分类器的优先级顺序](/docs/zh-CN/auto-mode-config#override-the-block-and-allow-rules)规定了您的批准可以到达哪些阻止。要运行它不会清除的步骤，[离开自动模式](#switch-permission-modes)并回答权限提示。482* **某些阻止保持原位**：[分类器的优先级顺序](/docs/zh-CN/auto-mode-config#override-the-block-and-allow-rules)规定了您的批准可以到达哪些阻止。要运行它不会清除的步骤，请[离开自动模式](#switch-permission-modes)并回答权限提示。

478 483

479<h3 id="when-auto-mode-falls-back">484<h3 id="when-auto-mode-falls-back">

480 自动模式何时回退485 当自动模式回退时

481</h3>486</h3>

482 487

483当自动模式无法批准您的会话操作时，会发生什么取决于情况：488当自动模式无法批准您的会话操作时，发生的情况取决于情况：

489

490* **被阻止的操作**：Claude Code 显示通知并在 `/permissions` 下的**最近拒绝**选项卡中列出操作，您可以按 `r` 使用手动批准重试它。

491* **重复阻止**：如果分类器连续 3 次或总共 20 次阻止操作，自动模式暂停，Claude Code 恢复提示。批准提示的操作恢复自动模式。请参阅[重复阻止阈值](#repeated-block-thresholds)了解如何计算阻止。

492* **来自分类器的无判决**：当自动模式之外的安全检查拒绝分类器自己的请求，或分类器的响应未解析时，Claude Code 拒绝该操作而不显示通知或**最近拒绝**条目。请参阅[自动模式无法确定操作的安全性](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)了解每种情况显示的消息以及处理方法。

493* **来自服务器的无判决**：在[服务器端分类器审查](#server-side-classifier-review)下，Claude Code 拒绝服务器给不出判决的操作，并在连续 10 个响应没有判决后停止轮次。请参阅[服务器未返回安全判决](/docs/zh-CN/errors#the-server-returned-no-safety-verdict)。

494* **检查期间的模式切换**：如果您在分类器检查待处理时切换权限模式，Claude Code 丢弃新模式不会请求的判决。您改为被提示批准，或在 [`dontAsk` 模式](#allow-only-pre-approved-tools-with-dontask-mode)中操作被自动拒绝。

484 495

485* **被阻止的操作**：Claude Code 显示通知并在 `/permissions` 下的**最近拒绝**选项卡中列出操作，您可以按 `r` 使用手动批准重试它。当分类器对操作[没有判决](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)时，因为分类器自己的请求的单独安全检查拒绝了它或其响应未解析，Claude Code 拒绝该操作而不显示通知或**最近拒绝**条目。496<h4 id="repeated-block-thresholds">

486* **重复阻止**：如果分类器连续阻止操作 3 次或总共 20 次，自动模式暂停，Claude Code 恢复提示。批准提示的操作会恢复自动模式。这些阈值不可配置。任何允许的操作重置连续计数器，而总计数器在会话中持续，仅在其自己的限制触发回退时重置。当[分类器自己的请求的单独安全检查拒绝](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)时，Claude Code 不计算拒绝到任一阈值；链接的条目涵盖 Claude Code 如何处理这些拒绝。497 重复阻止阈值

487* **无法提示的会话**：[非交互式](/docs/zh-CN/headless) `-p` 运行没有 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 没有回退提示。当重复阻止达到阈值时，操作不运行，Claude 继续工作。当[分类器自己的请求的单独安全检查拒绝](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)时也适用相同情况。Claude Code 在任一情况下都不停止运行。498</h4>

488* **服务器没有判决**：在[服务器端分类器审查](#server-side-classifier-review)下，Claude Code 拒绝服务器没有判决的操作，并在连续十个响应没有判决后停止该轮。请参阅[服务器返回了没有安全判决](/docs/zh-CN/errors#the-server-returned-no-safety-verdict)。

489* **检查期间的模式切换**：如果您在分类器检查待处理时切换权限模式，Claude Code 会丢弃新模式不会请求的判决，而不是应用它：您改为被提示批准，或在 [`dontAsk` 模式](#allow-only-pre-approved-tools-with-dontask-mode)中操作被自动拒绝。

490 499

491重复阻止通常意味着分类器缺少关于您的基础设施的上下文。使用 `/feedback` 报告误报，或让管理员[配置受信任的基础设施](/docs/zh-CN/auto-mode-config)。500连续 3 次阻止和总共 20 次阻止的阈值不可配置。总计数器对会话持续并仅在其自己的限制触发回退时重置。当自动模式之外的安全检查拒绝分类器自己的请求时，Claude Code 不计算拒绝向任一阈值。

501

502[非交互式](/docs/zh-CN/headless) `-p` 运行没有 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 没有回退提示。当重复阻止达到阈值时，操作不运行，Claude 继续工作。Claude Code 不停止运行。

503

504重复阻止通常意味着分类器缺少关于您的基础设施的上下文。使用 `/feedback` 报告假阳性，或让管理员[配置受信任的基础设施](/docs/zh-CN/auto-mode-config)。

505

506<h3 id="how-auto-mode-evaluates-actions">

507 分类器如何评估操作

508</h3>

509

510以下部分涵盖 Claude Code 评估操作的顺序、分类器如何审查子代理工作，以及分类器调用在成本和延迟中添加的内容。

492 511

493<span id="how-the-classifier-evaluates-actions" />512<span id="how-the-classifier-evaluates-actions" />

494 513

496 <Accordion title="分类器如何评估操作">515 <Accordion title="分类器如何评估操作">

497 每个操作都经过固定的决策顺序。第一个匹配的步骤获胜：516 每个操作都经过固定的决策顺序。第一个匹配的步骤获胜：

498 517

499 1. 与您的[允许、询问或拒绝规则](/docs/zh-CN/permissions#manage-permissions)匹配的操作立即解决，但有以下例外：518 1. 与您的[允许、询问或拒绝规则](/docs/zh-CN/permissions#manage-permissions)匹配的操作立即解决，但以下例外：

500 * 写入[受保护路径](#protected-paths)的操作即使允许规则匹配也会路由到分类器，Claude Code v2.1.218 及更高版本中针对[关键路径](#critical-paths)的 `rm` 和 `rmdir` 删除也是如此519 * 写入[受保护路径](#protected-paths)的操作路由到分类器，即使允许规则匹配

501 * 标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使允许规则匹配也会直接提示您，您的组织在会话中设置为 `ask` 的[连接器工具](/docs/zh-CN/mcp#organization-controls-on-connector-tools)也是如此，其中该设置到达 Claude Code520 * 没有允许规则批准针对[关键路径](#critical-paths)的 `rm` 和 `rmdir` 删除

502 * 携带[每个命令允许的域](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)的 shell 命令也会路由到分类器，即使允许规则匹配，因为规则批准命令，而不是其主机521 * 标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具直接提示您，即使允许规则匹配，连接器工具[您的组织在会话中设置为 `ask`](/docs/zh-CN/mcp#organization-controls-on-connector-tools)的也是，其中该设置到达 Claude Code

522 * 携带[按命令允许的域](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)的 shell 命令也路由到分类器，即使允许规则匹配，因为规则批准命令，而不是其主机

503 * 与命令内容匹配的询问规则，例如 `Bash(git push *)`，回退到权限提示523 * 与命令内容匹配的询问规则，例如 `Bash(git push *)`，回退到权限提示

524 * [符号链接检查](/docs/zh-CN/permissions#symlinks)解决为受保护路径的写入在 Claude 请求的路径本身不受保护时提示您

504 2. 只读操作和工作目录中的文件编辑被自动批准，除了写入[受保护路径](#protected-paths)和[工作目录外的第一次读取](#first-read-outside-the-working-directories)，这会提示您525 2. 只读操作和工作目录中的文件编辑被自动批准，除了写入[受保护路径](#protected-paths)和[工作目录外的第一次读取](#first-read-outside-the-working-directories)，这会提示您

505 * 在具有[服务器端分类器审查](#server-side-classifier-review)的会话中，只读和[沙箱](/docs/zh-CN/sandboxing#sandbox-modes) shell 命令等待该审查，如果它标记它们则被阻止526 * 在具有[服务器端分类器审查](#server-side-classifier-review)的会话中，只读和[沙箱](/docs/zh-CN/sandboxing#sandbox-modes) shell 命令等待该审查并在其标记时被阻止

506 3. 其他所有内容都转到分类器。在步骤 1 中直接提示您的连接器工具和` requiresUserInteraction` MCP 工具永远不会到达分类器，因此组织要求的批准或同意步骤都不会被自动批准527 * 工作目录内的写入，[符号链接检查](/docs/zh-CN/permissions#symlinks)解决为其外的位置，提示您

507 4. 如果分类器阻止，Claude 接收原因并尝试替代方案。在大多数会话中，原因名称分类器匹配的规则，例如 `[Data Exfiltration]`，而不是给出书面解释；请参阅[审查拒绝](/docs/zh-CN/auto-mode-config#review-denials)528 3. 其他所有内容都进入分类器，除了[关键路径删除](#critical-paths)在其默认处理下。在步骤 1 中直接提示您的连接器工具和`requiresUserInteraction` MCP 工具永远不会到达分类器，因此既不是组织要求的批准也不是同意步骤被自动批准

529 4. 如果分类器阻止，Claude 收到原因并尝试替代方案。在大多数会话中，原因命名分类器匹配的规则，例如 `[Data Exfiltration]`，而不是给出书面解释；请参阅[审查拒绝](/docs/zh-CN/auto-mode-config#review-denials)

508 530

509 进入自动模式时，授予任意代码执行的广泛允许规则被删除：531 进入自动模式时，授予任意代码执行的广泛允许规则被丢弃：

510 532

511 * 笼统的 `Bash(*)` 或 `PowerShell(*)`533 * 无条件 `Bash(*)` 或 `PowerShell(*)`

512 * 通配符解释器，如 `Bash(python*)`534 * 通配符解释器，如 `Bash(python*)`

513 * 包管理器运行命令535 * 包管理器运行命令

514 * `Agent` 允许规则536 * `Agent` 允许规则

515 * [`Monitor`](/docs/zh-CN/tools-reference#monitor-tool) 允许规则，因为 Claude Code 通过 shell 运行 Monitor 命令537 * [`Monitor`](/docs/zh-CN/tools-reference#monitor-tool) 允许规则，因为 Claude Code 通过 shell 运行 Monitor 命令

516 538

517 狭窄的规则，如 `Bash(npm test)` 保持有效。Claude Code 在您离开自动模式时恢复删除的规则。在 v2.1.236 之前，Claude Code 在自动模式中保持 `Monitor` 允许规则有效，因此与整个工具匹配的规则在没有分类器审查的情况下批准 Monitor 命令。539 窄规则如 `Bash(npm test)` 保持有效。Claude Code 在您离开自动模式时恢复丢弃的规则。在 v2.1.236 之前，Claude Code 在自动模式中保持 `Monitor` 允许规则有效，因此与整个工具匹配的规则在没有分类器审查的情况下批准 Monitor 命令。

540

541 Claude Code 也在会丢弃未提交工作的命令之前运行 `git status`，例如 `git reset --hard` 或 `rm -rf`，并向分类器显示是否存在暂存、修改或未跟踪的工作。Claude Code 在该检查中报告未跟踪的文件，即使仓库的 git 配置设置 `status.showUntrackedFiles=no`。

518 542

519 Claude Code 还在会丢弃未提交工作的命令之前运行 `git status`，例如 `git reset --hard` 或 `rm -rf`，并向分类器显示是否存在暂存、修改或未跟踪的工作。Claude Code 在该检查中报告未跟踪的文件，即使仓库的 git 配置设置了 `status.showUntrackedFiles=no`。543 在 Claude Code 本身发送的分类器请求中，分类器看到用户消息、除只读查找（如文件读取和搜索）之外的工具调用，以及您的 CLAUDE.md 内容。工具结果从这些请求中被剥离，因此文件或网页中的恶意内容无法直接操纵分类器。

520 544

521 分类器看到用户消息、除了只读查找（如文件读取和搜索）之外的工具调用，以及您的 CLAUDE.md 内容。工具结果被剥离，因此文件或网页中的恶意内容无法直接操纵它。您可以使用 [PostToolUse hook 的 `classifierContext` 字段](/docs/zh-CN/hooks#annotate-a-result-for-the-auto-mode-classifier)注释调用的结果，分类器将其读取为应用程序提供的上下文。该字段需要 Claude Code v2.1.236 或更高版本。545 您可以使用 [PostToolUse hook 的 `classifierContext` 字段](/docs/zh-CN/hooks#annotate-a-result-for-the-auto-mode-classifier)注释调用的结果，分类器将其读取为应用程序提供的上下文。该字段需要 Claude Code v2.1.236 或更高版本。

522 546

523 单独的服务器端探针扫描传入的工具结果并在 Claude 读取之前标记可疑内容。有关这些层如何协同工作的更多信息，请参阅[自动模式公告](https://claude.com/blog/auto-mode)和[工程深度潜水](https://www.anthropic.com/engineering/claude-code-auto-mode)。547 单独的服务器端探针扫描传入的工具结果并在 Claude 读取之前标记可疑内容。有关这些层如何协同工作的更多信息，请参阅[自动模式公告](https://claude.com/blog/auto-mode)和[工程深度潜水](https://www.anthropic.com/engineering/claude-code-auto-mode)。

524 </Accordion>548 </Accordion>

526 <Accordion title="自动模式如何处理子代理">550 <Accordion title="自动模式如何处理子代理">

527 分类器在三个点检查[子代理](/docs/zh-CN/sub-agents)工作：551 分类器在三个点检查[子代理](/docs/zh-CN/sub-agents)工作：

528 552

529 1. 在子代理启动之前，委托的任务描述被评估，因此危险看起来的任务在生成时被阻止。553 1. 在子代理启动之前，委托的任务描述被评估，因此看起来危险的任务在生成时被阻止。

530 2. 当子代理运行时，其每个操作都通过分类器，使用与父会话相同的规则，子代理 frontmatter 中的任何 `permissionMode` 都被忽略。554 2. 当子代理运行时，其每个操作都通过分类器，使用与父会话相同的规则，子代理前言中的任何 `permissionMode` 被忽略。

531 3. 当子代理完成时，分类器审查其工作和最终报告，然后父会话读取报告。当分类器标记子代理的工作或报告时，或单独的 API 安全检查拒绝审查时，报告仍然被交付，前面加上安全警告。当分类器不可用于审查时，报告到达时带有说明在对其采取行动之前验证子代理工作的说明。555 3. 当子代理完成时，分类器审查其工作和最终报告，然后父读取报告。当分类器标记子代理的工作或报告，或单独的 API 安全检查拒绝审查时，报告仍被传递，前面加上安全警告。当分类器对审查不可用时，报告到达时带有注意在根据其采取行动之前验证子代理的工作。

532 </Accordion>556 </Accordion>

533 557

534 <Accordion title="成本和延迟">558 <Accordion title="成本和延迟">

535 分类器默认在 Claude Sonnet 5 上运行，而不是在您的 `/model` 选择上。Anthropic 配置的服务器端分类器模型优先于该默认值。当您的会话模型是 Claude Sonnet 4.6 时，或当 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 排除 Sonnet 5 时，分类器改为在会话的模型上运行，或在会话在[Fable 模型](/docs/zh-CN/model-config#work-with-fable)上运行时在 Opus 模型上运行；在 Anthropic API 以外的提供商上，该 Opus 回退是提供商的默认 Opus 模型。559 分类器默认在 Claude Sonnet 5 上运行，而不是在您的 `/model` 选择上。Anthropic 配置的服务器端分类器模型优先于该默认值。当您的会话模型是 Claude Sonnet 4.6 时，或当 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 排除 Sonnet 5 时，分类器改为在会话的模型上运行，或在会话在[Fable 模型](/docs/zh-CN/model-config#work-with-fable)上运行时在 Opus 模型上运行；在 Anthropic API 以外的提供商上，该 Opus 回退是提供商的默认 Opus 模型。

536 560

537 会话的第一个自动模式请求验证 Sonnet 5 默认值：如果请求成功，Sonnet 5 保持会话的分类器模型，如果它因模型不可用而失败，会话改为使用回退。在该验证解决后，分类器的模型在会话中不会改变。561 会话的第一个自动模式请求验证 Sonnet 5 默认值：如果请求成功，Sonnet 5 保持会话的分类器模型，如果它失败是因为模型不可用，会话改为使用回退。在该验证解决后，分类器的模型对会话不再改变。

538 562

539 在 Enterprise 计划和使用 Claude API、[AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws)、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 的账户上，分类器调用计入您的令牌使用。每次检查发送记录的一部分加上待处理操作，在执行前添加往返。在受保护路径外的读取和工作目录编辑跳过分类器，因此开销主要来自 shell 命令和网络操作。服务器审查操作的地方，没有单独的分类器调用要计数；请参阅[服务器端分类器审查](#server-side-classifier-review)。563 在 Enterprise 计划和使用 Claude API 的账户、[AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws)、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上，分类器调用计入您的令牌使用。每次检查发送记录的一部分加上待处理操作，在执行前添加往返。在受保护路径外的读取和工作目录编辑跳过分类器，因此开销主要来自 shell 命令和网络操作。服务器审查操作作为会话模型请求的一部分的地方，没有单独的分类器调用要计数；请参阅[服务器端分类器审查](#server-side-classifier-review)。

540 564

541 沙箱网络访问不添加每个连接分类器请求。分类器与命令一起判断[命令命名的主机](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)在一次审查中，Claude Code 检查每个连接对照批准的列表而不再次调用分类器。565 沙箱网络访问不添加按连接分类器请求。分类器与命令一起判断[命令命名的主机](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)在一次审查中，Claude Code 检查每个连接对批准列表而不再次调用分类器。

542 </Accordion>566 </Accordion>

543</AccordionGroup>567</AccordionGroup>

544 568

566 590

567`bypassPermissions` 模式禁用权限提示和安全检查，以便工具调用立即执行，包括对[受保护路径](#protected-paths)的写入。591`bypassPermissions` 模式禁用权限提示和安全检查，以便工具调用立即执行，包括对[受保护路径](#protected-paths)的写入。

568 592

569[任何模式都不会自动批准的操作](#actions-no-mode-auto-approves)在此模式下仍会提示。593[任何模式都不会自动批准的操作](#actions-no-mode-auto-approves)在此模式下仍会提示。[PowerShell 中的 Remove-Item](#remove-item-in-powershell) 拒绝也适用于此模式。

570 594

571两个[跨会话消息传递](/docs/zh-CN/cross-session-messaging)保护措施在此模式下仍然适用，以及在具有可用绕过权限的计划模式会话中：595两个[跨会话消息传递](/docs/zh-CN/cross-session-messaging)保护措施在此模式下仍然适用，以及在具有可用绕过权限的交互式终端 Plan Mode 会话中：

572 596

573* [`isolatePeerMachines`](/docs/zh-CN/settings-reference#isolatepeermachines)批准提示用于发送到超出此机器的会话的消息仍然出现。597* [`isolatePeerMachines`](/docs/zh-CN/settings-reference#isolatepeermachines)批准提示用于发送到超出此机器的会话的消息仍然出现。

574* 当没有[`crossSessionInbound`](/docs/zh-CN/cross-session-messaging#control-inbound-messages)值适用时，Claude Code 会从您的另一个会话中的入站消息保留以供您批准，仅当发送会话将自己标识为也绕过权限提示时才无需询问即可传递。如果您在保留消息时离开权限模式，Claude Code 会重新应用入站规则，并传递任何现在接受的保留消息。598* 当没有[`crossSessionInbound`](/docs/zh-CN/cross-session-messaging#control-inbound-messages)值适用时，Claude Code 会从您的另一个会话中的入站消息保留以供您批准，仅当发送会话将自己标识为也绕过权限提示时才无需询问即可传递。如果您在保留消息时离开权限模式，Claude Code 会重新应用入站规则，并传递任何现在接受的保留消息。

575 599

576在具有可用绕过权限的交互式终端会话中，Claude Code 也不强制执行[计划模式的](#analyze-before-you-edit-with-plan-mode)块。Claude 仍然被指示在不编辑的情况下进行计划，但它在计划期间尝试的文件编辑或 shell 命令无需提示即可运行。显式[询问规则](/docs/zh-CN/permissions#manage-permissions)和针对[关键路径](#critical-paths)的 `rm` 和 `rmdir` 删除仍会提示。600在具有可用绕过权限的交互式终端会话中，Claude Code 也不强制执行 [Plan Mode 的](#analyze-before-you-edit-with-plan-mode)块。Claude 仍然被指示在不编辑的情况下进行计划，但它在计划期间尝试的文件编辑或 shell 命令无需提示即可运行。显式[询问规则](/docs/zh-CN/permissions#manage-permissions)和针对[关键路径](#critical-paths)的 `rm` 和 `rmdir` 删除仍会提示。

577 601

578计划模式在 Claude Code 运行时没有交互式终端的任何地方都保持其块，包括[非交互式运行](/docs/zh-CN/headless)（带 `-p`）、[Agent SDK](/docs/zh-CN/agent-sdk/permissions#plan-mode-plan) 会话和 [VS Code 扩展](/docs/zh-CN/vs-code)的聊天面板中的对话。在那里，`--allow-dangerously-skip-permissions` 使 `bypassPermissions` 稍后可选。602Plan Mode 在 Claude Code 运行时没有交互式终端的任何地方都保持其块，包括[非交互式运行](/docs/zh-CN/headless)（带 `-p`）、[Agent SDK](/docs/zh-CN/agent-sdk/permissions#plan-mode-plan) 会话和 [VS Code 扩展](/docs/zh-CN/vs-code)的聊天面板中的对话。在那里，`--allow-dangerously-skip-permissions` 使 `bypassPermissions` 稍后可选。

579 603

580<Warning>604<Warning>

581 仅在隔离环境（如容器、虚拟机或没有互联网访问的开发容器）中使用此模式，其中 Claude Code 无法损害您的主机系统。605 仅在隔离环境（如容器、虚拟机或没有互联网访问的开发容器）中使用此模式，其中 Claude Code 无法损害您的主机系统。

591 615

592Claude Code 在您使用[`--restricted`](/docs/zh-CN/cli-reference#cli-flags)启动的会话中拒绝 `bypassPermissions`。`--restricted` 需要 Claude Code v2.1.248 或更高版本。616Claude Code 在您使用[`--restricted`](/docs/zh-CN/cli-reference#cli-flags)启动的会话中拒绝 `bypassPermissions`。`--restricted` 需要 Claude Code v2.1.248 或更高版本。

593 617

594第一次使用此模式启动交互式会话时，Claude Code 会显示一个警告对话框，要求您接受对在没有权限检查的情况下执行的操作的责任。Claude Code 将您的接受保存到用户设置，因此该对话框仅出现一次。如果您拒绝，Claude Code 会退出。在[非交互模式](/docs/zh-CN/headless)中不显示对话框，使用 `--bg` 启动的[后台会话](/docs/zh-CN/agent-view)会被拒绝，直到您在交互式会话中接受对话框。618第一次使用此模式启动交互式会话时，Claude Code 会显示一个警告对话框，要求您接受对在没有权限检查的情况下执行的操作的责任：

619

620* **如果您接受**：Claude Code 在 `~/.claude/settings.json` 中将 `skipDangerousModePermissionPrompt` 设置为 `true`，因此后续会话会跳过对话框。要再次看到对话框，请从该文件中删除该键或将其设置为 `false`。[`skipDangerousModePermissionPrompt` 参考](/docs/zh-CN/settings-reference#skipdangerousmodepermissionprompt)列出了您或您的组织可以设置它的其他设置文件。

621* **如果您拒绝**：Claude Code 退出。

622

623在[非交互模式](/docs/zh-CN/headless)中不显示对话框，使用 `--bg` 启动的[后台会话](/docs/zh-CN/agent-view)会被拒绝，直到您在交互式会话中接受对话框。

595 624

596在 Linux 和 macOS 上，当以 root 身份或在 `sudo` 下运行时，Claude Code 拒绝以此模式启动：625在 Linux 和 macOS 上，当以 root 身份或在 `sudo` 下运行时，Claude Code 拒绝以此模式启动：

597 626

623 652

624在使用 [`--restricted`](/docs/zh-CN/cli-reference#cli-flags) 启动的会话中，需要 Claude Code v2.1.248 或更高版本，分类器无法批准受保护路径的写入。653在使用 [`--restricted`](/docs/zh-CN/cli-reference#cli-flags) 启动的会话中，需要 Claude Code v2.1.248 或更高版本，分类器无法批准受保护路径的写入。

625 654

626设置文件中的 [`permissions.allow`](/docs/zh-CN/permissions#manage-permissions) 规则不会预先批准受保护路径的写入。安全检查在 Claude Code 评估设置中的允许规则之前运行，因此 `~/.claude/settings.json` 或 `.claude/settings.json` 中的条目（如 `Edit(.claude/**)`）不会改变上表中的每个模式结果。在提示的模式中，`.claude/` 写入的提示提供**是的，允许 Claude 在此会话中编辑其自己的设置**，这会在该会话中批准后续的 `.claude/` 写入而无需再次提示。655在将受保护路径写入路由到分类器的模式中，当 Claude 请求的路径本身不受保护时，[符号链接检查](/docs/zh-CN/permissions#symlinks)解析为受保护路径的写入会提示你。

656

657设置文件中的 [`permissions.allow`](/docs/zh-CN/permissions#manage-permissions) 规则不会预先批准受保护路径的写入。安全检查在 Claude Code 评估设置中的允许规则之前运行，因此 `~/.claude/settings.json` 或 `.claude/settings.json` 中的条目（如 `Edit(.claude/**)`）不会改变上表中的每个模式结果。在提示的模式中，对项目的 `.claude/` 文件夹或 `~/.claude/` 的写入提示可以提供以下这些会话范围的选项之一：

658

659* 对于项目的 `.claude/` 文件夹：**是的，允许 Claude 在此会话中编辑此项目的 .claude 文件夹中的文件**

660* 对于 `~/.claude/`：**是的，允许 Claude 在此会话中编辑其 \~/.claude 文件夹中的文件**

627 661

628受保护的目录：662受保护的目录：

629 663

654 关键路径688 关键路径

655</h2>689</h2>

656 690

657Claude Code 永远不会让 [`permissions.allow`](/docs/zh-CN/permissions#manage-permissions) 规则或返回 `"allow"` 的 [`PreToolUse` hook](/docs/zh-CN/permissions#extend-permissions-with-hooks) 批准针对关键路径的 `rm` 或 `rmdir` 命令，即使在跳过其他提示的模式下。此断路器防止模型错误。匹配的拒绝规则仍然完全阻止命令。691关键路径是 Claude Code 保护的目录，防止 `rm` 和 `rmdir` 命令，例如文件系统根目录、您的主目录和您的工作目录。

658 692

659会发生什么取决于您的权限模式：693Claude Code 永远不会让 [`permissions.allow`](/docs/zh-CN/permissions#manage-permissions) 规则或返回 `"allow"` 的 [`PreToolUse` hook](/docs/zh-CN/permissions#extend-permissions-with-hooks) 批准针对关键路径的 `rm` 或 `rmdir` 命令，即使在跳过其他提示的模式下。此断路器防止模型错误。匹配的拒绝规则仍然完全阻止命令。

660 694

661| 模式 | Claude Code 对关键路径移除的处理 |695会发生什么取决于您的权限模式（[见下文](#critical-path-removals-in-each-permission-mode)）。`Remove-Item` 和 `cmd` 移除内置命令有自己的检查，详见 [PowerShell 中的 Remove-Item](#remove-item-in-powershell)。

662| :- | :- |

663| `default`、`acceptEdits` | 要求您批准它 |

664| `plan` | 要求您批准它。当[自动模式在规划期间可用](#analyze-before-you-edit-with-plan-mode)且没有绕过权限可用时，改为将其发送到分类器 |

665| `auto` | 将其发送到[分类器](#eliminate-prompts-with-auto-mode) |

666| `dontAsk` | 拒绝它 |

667| `bypassPermissions` | 要求您批准它 |

668 696

669如果显式[询问规则](/docs/zh-CN/permissions#manage-permissions)与命令匹配，Claude Code 即使在 `auto` 模式下也会询问您。在询问的模式中，[`PermissionRequest` hook](/docs/zh-CN/hooks#permissionrequest)可以像回答任何其他一样回答提示。697<h3 id="which-paths-are-critical">

698 哪些路径是关键路径

699</h3>

670 700

671Claude Code 将 `rm` 或 `rmdir` 目标视为关键路径，当它是以下任何一个时：701Claude Code 将 `rm` 或 `rmdir` 目标视为关键路径，当它是以下任何一个时：

672 702

677* 您的工作目录及其父目录707* 您的工作目录及其父目录

678* 您的额外工作目录及其父目录，但仅当移除是其下的 glob 时，如 `rm -rf <dir>/*`。`rm -rf <dir>` 在目录本身上不会触发此检查708* 您的额外工作目录及其父目录，但仅当移除是其下的 glob 时，如 `rm -rf <dir>/*`。`rm -rf <dir>` 在目录本身上不会触发此检查

679 709

680Claude Code 也将直接在 shell 变量下的 glob 或尾部斜杠视为关键路径移除，如 `rm -rf "$DIR"/*`，因为当变量为空时命令变成从文件系统根目录的移除。710<h3 id="other-targets-that-count-as-critical-paths">

711 计为关键路径的其他目标

712</h3>

681 713

682此变量情况的提示命名被标记的 `rm` 并说明如何重写它以便检查通过：714Claude Code 也将以下 `rm` 和 `rmdir` 目标视为关键路径。最后一列说明每个目标为什么计为关键路径。

683 715

684* 对于诸如 `$DIR` 之类的变量，保护每个扩展，以便当变量未设置或为空时 shell 停止出错，如 `rm -rf "${DIR:?}"/*`，或使用文字路径716| 目标 | 示例 | 为什么计为关键路径 |

685* 对于通常设置的变量，如 `$HOME`，使用文字路径717| :- | :- | :- |

718| shell 变量下的 glob 或尾部斜杠 | `rm -rf "$DIR"/*` | 当变量为空时，命令变成从文件系统根目录的移除 |

719| 位置参数下的相同形式，如 `$1` 或 `$@`，当命令中没有任何内容给它赋值时 | `rm -rf "$1"/*` | 命令扩展为从根目录的移除 |

720| shell 变量后跟一个常见的顶级目录名称，如 `mnt`、`tmp`、`usr` 或 `Users` | `rm -rf "$TMPDIR/mnt"` | 当变量扩展为空时，命令移除 `/mnt` |

721| 变量由同一命令从目录打印替换分配，如 `$(pwd)` 或 `$(git rev-parse --show-toplevel)` | `D=$(pwd); rm -rf "$D"` | 该值可以命名您的工作目录或存储库根目录 |

722| 仅命令替换的输出的目标，当 `rm` 是递归的时 | `rm -rf "$(pwd)"` | Claude Code 无法在命令运行前检查目标 |

723| 关键路径后的尾部命令替换 | `rm -rf ~/$(cmd)` | Claude Code 检查如果替换扩展为空将保留的路径，此处为您的主目录 |

724| 仅反斜杠的目标 | `rm -rf "\\"` | Windows 上的 Git Bash 将单个反斜杠读取为当前驱动器的根目录，因此检查适用于每个平台 |

725

726要关闭仅命令替换输出的目标上的检查，请在启动 Claude Code 的环境中设置 [`CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT=1`](/docs/zh-CN/env-vars#variables)。

727

728<h3 id="removals-inside-nested-commands-and-inline-scripts">

729 嵌套命令和内联脚本中的移除

730</h3>

731

732Claude Code 也查看这些构造内部：

733

734* **嵌套命令**：带有 `(...)` 的子 shell、带有 `{ ...; }` 的大括号组、带有 `$(...)` 或反引号的命令替换，或带有 `<(...)` 的进程替换。Claude Code 找到关键路径移除，无论它位于嵌套形式内部（如 `(rm -rf ~)` 或 `echo "$(rm -rf ~)"`），还是位于同一命令中的其他地方。

735* **内联脚本**：Claude Code 检查传递给 shell 的脚本（如 `sh -c` 或 `bash -c`）中的 shell 变量和位置参数[目标](#other-targets-that-count-as-critical-paths)。

736 * 当脚本是双引号时，调用 shell 在内部 shell 接收脚本之前扩展其变量。在 `find . -name '*.tmp' -exec sh -c "rm -rf \"$1\"/*" _ {} \;` 中，命令对每个匹配扩展为从文件系统根目录的移除，Claude Code 将其视为关键路径移除。

737 * 绑定 `$1` 到真实值的单引号脚本（如 `sh -c 'rm -rf "$1"/*' _ {}` 所做的）不被标记。

738

739<h3 id="rewrite-a-flagged-command">

740 重写被标记的命令

741</h3>

742

743如何重写命令以通过检查取决于它使用的[其他目标](#other-targets-that-count-as-critical-paths)：

686 744

687其扩展都以这种方式保护的移除不是关键路径移除，因此在 `bypassPermissions` 模式下它运行而不提示。745* **变量下的 glob 或尾部斜杠，如 `$DIR`**：保护每个扩展，以便当变量未设置或为空时 shell 停止出错，如 `rm -rf "${DIR:?}"/*`，或使用文字路径。其扩展都以这种方式保护的移除通过此检查，因此在 `bypassPermissions` 模式下它运行而不提示，除非另一个[关键路径](#critical-paths)检查标记它。

746* **通常设置的变量下的 glob 或尾部斜杠，如 `$HOME`**：使用文字路径。

747* **从目录打印替换分配的变量**：使用文字路径。`"${D:?}"` 保护不会清除此检查，因为变量不为空。

748* **仅命令替换输出的目标**：首先自己运行替换，然后移除它打印的文字路径。提示告诉 Claude 做同样的事情。

688 749

689使用 `(...)` 中的子 shell、`{ ...; }` 中的大括号组、`$(...)` 或反引号中的命令替换，或 `<(...)` 中的进程替换隐藏移除，不会跳过检查。Claude Code 找到关键路径移除，无论它位于嵌套形式内部（如 `(rm -rf ~)` 或 `echo "$(rm -rf ~)"`），还是位于同一命令中的其他地方。750对于变量下的 glob 或尾部斜杠，提示命名被标记的 `rm` 并说明如何重写它以便检查通过。

751

752<h3 id="critical-path-removals-in-each-permission-mode">

753 每个权限模式中的关键路径移除

754</h3>

755

756Claude Code 对关键路径移除的处理取决于您的权限模式：

757

758| 模式 | 结果 |

759| :- | :- |

760| `default`、`acceptEdits` | 要求您批准它 |

761| `plan` | 要求您批准它。当[分类器在规划期间审查命令](#analyze-before-you-edit-with-plan-mode)且没有可用的绕过权限时，按 `auto` 模式处理 |

762| `auto` | 在终端中要求您批准它，有[时间限制](#time-limits-and-denials-in-auto-and-bypasspermissions-modes)。在其他地方，拒绝它 |

763| `dontAsk` | 拒绝它 |

764| `bypassPermissions` | 要求您批准它，在终端中有时间限制 |

765

766如果显式[询问规则](/docs/zh-CN/permissions#manage-permissions)与命令匹配，Claude Code 即使在 `auto` 模式下也会询问您，且没有时间限制。在询问的模式中，[`PermissionRequest` hook](/docs/zh-CN/hooks#permissionrequest) 可以回答提示。

767

768<h3 id="time-limits-and-denials-in-auto-and-bypasspermissions-modes">

769 auto 和 bypassPermissions 模式中的时间限制和拒绝

770</h3>

771

772在 `auto` 和 `bypassPermissions` 模式下，关键路径移除的终端提示显示两分钟倒计时：

773

774* 如果倒计时在您回答之前用完，Claude Code 拒绝命令并告诉 Claude 改为做什么，以便无人值守的会话继续工作。

775* 在提示打开时按任何键停止倒计时并保持提示等待您的回答。

776* 在一个会话中这样的提示运行完三次后无人回答，Claude Code 停止显示它们并立即拒绝进一步的关键路径移除。发送新消息会重新开始计数。

777

778在 `auto` 模式下，无论 Claude Code 无法向您显示终端提示的地方，它都立即拒绝命令，例如在[非交互式运行](/docs/zh-CN/headless)中使用 `-p`、在 [Agent SDK](/docs/zh-CN/agent-sdk/permissions) 会话中，以及在 VS Code 扩展的聊天面板和桌面应用中。拒绝告诉 Claude 报告它想删除的内容并将移除留给您。

779

780`auto` 和 `bypassPermissions` 处理需要 Claude Code v2.1.281 或更高版本。要关闭它，请在启动 Claude Code 的环境中设置 [`CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT=1`](/docs/zh-CN/env-vars#variables)。在 `auto` 模式下，关键路径移除随后转到分类器，在 `bypassPermissions` 模式下提示没有时间限制。

690 781

691<h3 id="remove-item-in-powershell">782<h3 id="remove-item-in-powershell">

692 PowerShell 中的 Remove-Item783 PowerShell 中的 Remove-Item

693</h3>784</h3>

694 785

695当您启用 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)时，Claude Code 给 `Remove-Item` 自己的检查，与 `rm` 关键路径列表分开。结果取决于目标，第一个匹配的情况适用：786当您启用 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)时，Claude Code 给 `Remove-Item` 和 `cmd` 内置命令 `rd`、`rmdir`、`del` 和 `erase` 自己的检查，与 `rm` 关键路径列表分开。对于 `Remove-Item`，结果取决于目标，第一个匹配的情况适用：

696 787

697* **系统路径**：文件系统根目录及其顶级目录、驱动器根目录及其顶级目录和您的主目录。Claude Code 在每种模式下拒绝命令，不询问您。788* **系统路径**：文件系统根目录及其顶级目录、驱动器根目录及其顶级目录和您的主目录。Claude Code 在每种模式下拒绝命令，不询问您。

698* **通配符**：裸 `*` 或任何以 `/*` 或 `\*` 结尾的目标，包括 shell 变量下的 glob，如 `$dir/*`。Claude Code 在每种模式下拒绝命令，不询问您，在[分类器](#eliminate-prompts-with-auto-mode)看到它之前。789* **通配符**：裸 `*` 或任何以 `/*` 或 `\*` 结尾的目标，包括 shell 变量下的 glob，如 `$dir/*`。Claude Code 在每种模式下拒绝命令，不询问您，在[分类器](#eliminate-prompts-with-auto-mode)看到它之前。

699* **您的工作目录或其父目录之一，带有 `-Recurse`**：Claude Code 将命令视为任何其他需要在您的权限模式下批准的命令，因此它在询问的模式下询问您，在 `auto` 模式下将其发送到分类器，在 `dontAsk` 模式下拒绝它。`bypassPermissions` 模式跳过此检查。790* **您的工作目录或其父目录之一，带有 `-Recurse`**：Claude Code 将命令视为任何其他需要在您的权限模式下批准的命令，因此它在询问的模式下询问您，在 `auto` 模式下将其发送到分类器，在 `dontAsk` 模式下拒绝它。`bypassPermissions` 模式跳过此检查。

700 791

792系统路径情况也适用于 `rd`、`rmdir`、`del` 和 `erase`，当 Claude 通过 `cmd` 运行它们时，如 `cmd /c rd /s /q C:\Users`。默认情况下，Claude Code 在每种模式下拒绝此类命令，不询问您。此 `cmd` 检查需要 Claude Code v2.1.283 或更高版本。

793

794在判断 `cmd` 目标时，Claude Code 将跟随文字文本的 PowerShell 变量视为空。这使得 `cmd /c rd /s /q "C:\$name"` 成为 `C:\` 的移除，因此它也被拒绝。尾部通配符计为它清空的文件夹，因此 `cmd /c del /q C:\*` 被拒绝，而您项目中的 `cmd /c del /q dist\*` 不被拒绝。

795

796要关闭 `cmd` 检查，请在启动 Claude Code 的环境中设置 [`CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY=1`](/docs/zh-CN/env-vars#variables)。Claude Code 在设置文件的 `env` 块中忽略此变量。系统路径上的 `Remove-Item` 无论如何都保持被拒绝。

797

701<h2 id="see-also">798<h2 id="see-also">

702 另请参阅799 另请参阅

703</h2>800</h2>

permissions.md +34 −5

Details

457* Claude Code 读取 `!` 模式相对于当前目录，即使 `/`、`~/` 或 `//` 跟随 `!`，因此模式无法到达用其中一个前缀锚定的规则。`Read(!~/notes/public/**)` 从 `Read(~/notes/**)` 中切割不出任何内容。457* Claude Code 读取 `!` 模式相对于当前目录，即使 `/`、`~/` 或 `//` 跟随 `!`，因此模式无法到达用其中一个前缀锚定的规则。`Read(!~/notes/public/**)` 从 `Read(~/notes/**)` 中切割不出任何内容。

458* 切割不能重新打开规则作为整体阻止的目录内的文件。使用 `Read(secrets/**)` 和 `Read(!secrets/public/**)`，Claude Code 仍然阻止 `secrets/public` 以及 `secrets` 的其余部分。458* 切割不能重新打开规则作为整体阻止的目录内的文件。使用 `Read(secrets/**)` 和 `Read(!secrets/public/**)`，Claude Code 仍然阻止 `secrets/public` 以及 `secrets` 的其余部分。

459 459

460当 Claude 访问符号链接时，权限规则检查两个路径：符号链接本身和它解析到的文件。Allow 和 deny 规则对该对的处理方式不同：allow 规则回退到提示您，而 deny 规则直接阻止。460<h4 id="symlinks">

461 符号链接

462</h4>

461 463

462* **Allow 规则**：仅在符号链接路径及其目标都匹配时适用。允许目录内的符号链接指向其外部仍然会提示您。464当 Claude 访问的文件路径通过符号链接时，权限检查涵盖两个路径：Claude 请求的路径和它解析到的文件。这适用于 macOS、Linux 和 Windows 上的符号链接，以及 Windows 上的目录连接。

463* **Deny 规则**：当符号链接路径或其目标匹配时适用。指向被拒绝文件的符号链接本身被拒绝。例如，使用 `Read(./project/**)` 允许和 `Read(~/.ssh/**)` 拒绝，`./project/key` 处的符号链接指向 `~/.ssh/id_rsa` 被阻止：目标未通过 allow 规则，并匹配 deny 规则。

464 465

465在 macOS 和 Linux 上，通过带有 `//`、`~/` 或 `/` 模式的符号链接目录编写的 deny 或 ask 规则也适用于该目录的真实位置。例如，在 macOS 上，其中 `/etc` 解析为 `/private/etc`，`Read(//etc/**)` 也阻止 `/private/etc/hosts`。在 v2.1.268 之前，通过符号链接目录编写的 deny 或 ask 规则不适用于其真实位置给出的路径。466<h5 id="how-rules-match-a-symlinked-path">

467 规则如何匹配符号链接路径

468</h5>

466 469

467当工具打开已批准的文件时，Claude Code [确认路径仍然解析到权限检查批准的位置](/docs/zh-CN/errors#refusing-after-a-symlink-changed)。470Allow 和 deny 规则对请求的路径和它解析到的文件的处理方式不同：

471

472* **Allow 规则**：仅在请求的路径和它解析到的文件都匹配时适用。允许目录内的符号链接指向其外部仍然会提示您。

473* **Deny 规则**：当请求的路径或它解析到的文件匹配时适用。指向被拒绝文件的符号链接本身被拒绝。例如，使用 `Read(./project/**)` 允许和 `Read(~/.ssh/**)` 拒绝，`./project/key` 处的符号链接指向 `~/.ssh/id_rsa` 被阻止：目标未通过 allow 规则，并匹配 deny 规则。

474

475在 macOS 和 Linux 上，通过带有 `//`、`~/` 或 `/` 模式的符号链接目录编写的 deny 或 ask 规则也适用于该目录的真实位置。例如，在 macOS 上，其中 `/etc` 解析为 `/private/etc`，`Read(//etc/**)` 也阻止 `/private/etc/hosts`。在 v2.1.268 之前，通过符号链接目录编写的 deny 或 ask 规则不适用于其真实位置给出的路径。

468 476

469Grep 和 Glob 搜索 `path` 参数解析到的目录。Claude Code 将 `Read` deny 规则应用于该目录。477Grep 和 Glob 搜索 `path` 参数解析到的目录。Claude Code 将 `Read` deny 规则应用于该目录。

470 478

479<h5 id="writes-through-a-symlink">

480 通过符号链接的写入

481</h5>

482

483如果 Claude 要求编辑或写入的路径本身是符号链接，Edit 和 Write 工具[拒绝写入并指导 Claude 到链接的目标](/docs/zh-CN/errors#refusing-after-a-symlink-changed)。

484

485当目录在文件路径上是符号链接，或当 Bash 或 PowerShell 命令进行写入时，写入仍然可以通过符号链接进行。对于这些写入，发生的情况取决于写入解析到的文件相对于您的[工作目录](#working-directories)和[受保护的路径](/docs/zh-CN/permission-modes#protected-paths)的位置：

486

487* **解析到工作目录外**：当请求的路径在您的工作目录内，而它解析到的文件不在时，在[`acceptEdits` 模式](/docs/zh-CN/permission-modes#auto-approve-file-edits-with-acceptedits-mode)中写入不会自动批准。在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中，除非 allow 规则批准写入，否则您会被提示而不是分类器决定。提示命名写入解析到的路径。

488* **解析到请求的路径不命名的受保护路径**：[受保护的路径表](/docs/zh-CN/permission-modes#protected-paths)给出每个权限模式的结果，除了表将写入路由到分类器的地方，此写入改为提示您。

489

490<h5 id="paths-that-can’t-be-resolved-or-that-change">

491 无法解析或改变的路径

492</h5>

493

494当 Claude Code 无法确定路径在磁盘上的位置时，例如因为路径上的符号链接形成循环，Read、Edit 和 Write 工具[拒绝操作](/docs/zh-CN/errors#refusing-after-a-symlink-changed)。

495

496当工具随后打开已批准的文件时，它[确认路径仍然解析到权限检查批准的位置](/docs/zh-CN/errors#refusing-after-a-symlink-changed)。

497

471<h3 id="webfetch">498<h3 id="webfetch">

472 WebFetch499 WebFetch

473</h3>500</h3>

705 732

706Claude Code 仅在交互式会话中显示信任对话框。`claude -p` 运行或 SDK 会话永远不会显示它，信任父文件夹不计入这些规则，因此[在您信任文件夹之前运行什么](#what-runs-before-you-trust-a-folder)说明了在这两种情况下 Claude Code 仍然使用哪些存储库内容。733Claude Code 仅在交互式会话中显示信任对话框。`claude -p` 运行或 SDK 会话永远不会显示它，信任父文件夹不计入这些规则，因此[在您信任文件夹之前运行什么](#what-runs-before-you-trust-a-folder)说明了在这两种情况下 Claude Code 仍然使用哪些存储库内容。

707 734

735在启动或重启[后台会话](/docs/zh-CN/agent-view)之前，Claude Code 还会检查会话运行所在目录的工作区信任。如果您从您尚未信任的目录中的终端运行 `claude --bg`，信任对话框会首先出现，一旦您接受它，会话就会启动。在无法出现对话框的地方（如脚本中），命令会改为以[`Workspace not trusted`](/docs/zh-CN/errors#workspace-not-trusted-when-dispatching-a-background-session)错误退出。

736

708<h3 id="when-your-local-settings-file-needs-trust">737<h3 id="when-your-local-settings-file-needs-trust">

709 当您的本地设置文件需要信任时738 当您的本地设置文件需要信任时

710</h3>739</h3>

platforms.md +1 −1

Details

53| | 触发方式 | Claude 运行位置 | 设置 | 最适合 |53| | 触发方式 | Claude 运行位置 | 设置 | 最适合 |

54| :- | :- | :- | :- | :- |54| :- | :- | :- | :- | :- |

plugin-evals.md +17 −2

Details

16* 在您更改插件或发布新模型时捕捉回归16* 在您更改插件或发布新模型时捕捉回归

17* 查看与无插件相比插件的贡献17* 查看与无插件相比插件的贡献

18 18

19本页面适用于拥有可工作插件并想要测试其行为的插件和技能作者，以及在 CI 中对插件更改进行门控的团队。其用例格式与[技能创建者插件](/docs/zh-CN/skills#run-evals-with-skill-creator)使用的 `evals/evals.json` 文件分开。要创建插件，请参阅[创建插件](/docs/zh-CN/plugins/create)；要检查插件文件的语法和架构错误而不是其行为，请使用 [`claude plugin validate`](/docs/zh-CN/plugins/cli-reference#plugin-validate)。19本页面适用于拥有可工作插件并想要测试其行为的插件和技能作者，以及在 CI 中对插件更改进行门控的团队。对于在 Claude Code 对话中迭代单个技能，[技能创建者插件](/docs/zh-CN/skills#run-evals-with-skill-creator)使用其自己的 `evals/evals.json` 格式运行类似的比较，两个工具都不读取另一个的用例文件。要创建插件，请参阅[创建插件](/docs/zh-CN/plugins/create)；要检查插件文件的语法和架构错误而不是其行为，请使用 [`claude plugin validate`](/docs/zh-CN/plugins/cli-reference#plugin-validate)。

20 20

21<Note>21<Note>

22 每次 eval 运行和每个评分器都是对您账户的真实模型调用，计入您计划的使用量或您的 API 账单，因此请先检查[要求](#requirements)。然后[创建您的第一个 eval 套件](#create-your-first-eval-suite)，或者如果您已经有一个，请转到[在 CI 中运行 evals](#run-evals-in-ci)。22 每次 eval 运行和每个评分器都是对您账户的真实模型调用，计入您计划的使用量或您的 API 账单，因此请先检查[要求](#requirements)。然后[创建您的第一个 eval 套件](#create-your-first-eval-suite)，或者如果您已经有一个，请转到[在 CI 中运行 evals](#run-evals-in-ci)。

29要运行插件 evals，你需要：29要运行插件 evals，你需要：

30 30

31* Claude Code v2.1.269 或更高版本。运行 `claude --version` 检查，运行 `claude update` 升级。31* Claude Code v2.1.269 或更高版本。运行 `claude --version` 检查，运行 `claude update` 升级。

32* Git 2.31 或更高版本（如果已安装 git）。运行 `git --version` 检查。使用较旧的 git，`claude plugin eval` [在运行任何案例之前停止](#git-is-too-old-for-claude-plugin-eval)。没有 git，它正常运行。

32* 一个包含 `plugin.json` 或 `.claude-plugin/plugin.json` 清单的插件目录，或一个[技能目录插件](/docs/zh-CN/plugins/loading#plugins-shared-through-a-repository)。33* 一个包含 `plugin.json` 或 `.claude-plugin/plugin.json` 清单的插件目录，或一个[技能目录插件](/docs/zh-CN/plugins/loading#plugins-shared-through-a-repository)。

33* 与你的常规 Claude Code 会话相同的身份验证和模型提供商。Eval 运行、评判评分器和 `claude plugin eval init` 使用你的凭证调用模型，因此它们计入你的计划使用限制或 API 账单。当命令报告成本时，该数字是这些调用的[列表价格估计](/docs/zh-CN/costs)。34* 与你的常规 Claude Code 会话相同的身份验证和模型提供商。Eval 运行、评判评分器和 `claude plugin eval init` 使用你的凭证调用模型，因此它们计入你的计划使用限制或 API 账单。当命令报告成本时，该数字是这些调用的[列表价格估计](/docs/zh-CN/costs)。

34 35

666 667

667这是针对 Claude Code 尚未信任的目录的首次运行，由于 stdin 或 stdout 不是终端、你传递了 `--json`，或 `CI` 环境变量设置为 `true` 等真值，它无法询问你。在终端中运行一次 `claude plugin eval <dir>` 并回答提示，或者如果你信任插件的代码和套件，传递 `--trust-plugin`。请参阅[运行可以访问的内容](#security)。668这是针对 Claude Code 尚未信任的目录的首次运行，由于 stdin 或 stdout 不是终端、你传递了 `--json`，或 `CI` 环境变量设置为 `true` 等真值，它无法询问你。在终端中运行一次 `claude plugin eval <dir>` 并回答提示，或者如果你信任插件的代码和套件，传递 `--trust-plugin`。请参阅[运行可以访问的内容](#security)。

668 669

670<h3 id="git-is-too-old-for-claude-plugin-eval">

671 "is too old for claude plugin eval"

672</h3>

673

674你的 `PATH` 上的 `git` 版本早于 2.31，所以 `claude plugin eval` 在运行任何案例之前停止，并以命名你的版本的消息退出代码 1：

675

676```text theme={null}

677git 2.30 is too old for claude plugin eval: it ignores the environment configuration (GIT_CONFIG_COUNT, added in git 2.31) that switches off the repository's git hooks and helper programs for the run. Install git 2.31 or newer.

678```

679

680对于每次运行，Claude Code 会关闭 git hooks、凭证助手和其他程序，这些程序是存储库的 git 配置可以启动的。它通过 git 仅从版本 2.31 读取的环境配置来实现。较旧的 git 会忽略该配置，所以套件会停止，而不是对那些程序可能执行的运行进行评分。安装 git 2.31 或更高版本，然后再次运行套件。

681

682在 v2.1.283 之前，`claude plugin eval` 没有检查 git 版本，在较旧的 git 上，套件运行时这些程序保持打开状态。

683

669<h3 id="no-eval-cases-found">684<h3 id="no-eval-cases-found">

670 "No eval cases found"685 "No eval cases found"

671</h3>686</h3>

719默认 `--threshold` 是 1.0，所以当任何案例的评分低于完美时，命令退出代码为 1。设置与你需要的评分相匹配的阈值。退出代码 1 也涵盖了无法加载的案例文件，该文件在表格上方的 stderr 上报告。734默认 `--threshold` 是 1.0，所以当任何案例的评分低于完美时，命令退出代码为 1。设置与你需要的评分相匹配的阈值。退出代码 1 也涵盖了无法加载的案例文件，该文件在表格上方的 stderr 上报告。

720 735

721<h3 id="json-output-path-must-end-in-json">736<h3 id="json-output-path-must-end-in-json">

722 "--json output path must end in .json"737 `--json output path must end in .json`

723</h3>738</h3>

724 739

725你把目标放在 `--json` 之后，所以它被读作输出路径。把目标放在前面，如 `claude plugin eval . --json`，或给 `--json` 一个显式的 `.json` 路径。740你把目标放在 `--json` 之后，所以它被读作输出路径。把目标放在前面，如 `claude plugin eval . --json`，或给 `--json` 一个显式的 `.json` 路径。

plugins/anthropic-marketplaces.md +3 −1

Details

38| 获取方式 | Claude Code 在你首次启动交互式终端会话时添加它，除非[托管策略](/docs/zh-CN/plugins/org#allow-the-official-marketplace-and-your-own)或 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 阻止它。如果缺少，请参阅[市场 `claude-plugins-official` 未找到](/docs/zh-CN/plugins/troubleshooting#marketplace-claude-plugins-official-not-found) | 你在 Claude Code 会话中使用 `/plugin marketplace add anthropics/claude-plugins-community` 添加它 | 你在 Claude Code 会话中使用 `/plugin marketplace add anthropics/claude-code` 添加它 |38| 获取方式 | Claude Code 在你首次启动交互式终端会话时添加它，除非[托管策略](/docs/zh-CN/plugins/org#allow-the-official-marketplace-and-your-own)或 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 阻止它。如果缺少，请参阅[市场 `claude-plugins-official` 未找到](/docs/zh-CN/plugins/troubleshooting#marketplace-claude-plugins-official-not-found) | 你在 Claude Code 会话中使用 `/plugin marketplace add anthropics/claude-plugins-community` 添加它 | 你在 Claude Code 会话中使用 `/plugin marketplace add anthropics/claude-code` 添加它 |

39 39

~~40如果你编写了插件并希望其他人安装它，请参阅[发布插件](/docs/zh-CN/plugins/publish)，其中涵盖了你自己的市场和提交到社区市场。~~40如果你编写了插件并希望其他人安装它，请参阅[发布插件](/docs/zh-CN/plugins/publish)，其中涵盖了你自己的市场和提交到 Anthropic 的目录。

41 41

42<h3 id="the-demo-marketplace-in-anthropics/claude-code">42<h3 id="the-demo-marketplace-in-anthropics/claude-code">

43 `anthropics/claude-code` 中的演示市场43 `anthropics/claude-code` 中的演示市场

66* **在网络上**：在 [Claude Marketplace](https://claude.com/marketplace/plugins) 上搜索完整目录，它显示安装计数并标记一些插件为 **Anthropic verified**。66* **在网络上**：在 [Claude Marketplace](https://claude.com/marketplace/plugins) 上搜索完整目录，它显示安装计数并标记一些插件为 **Anthropic verified**。

67* **在 GitHub 上**：打开市场存储库中的 `.claude-plugin/marketplace.json`，例如 [`anthropics/claude-plugins-official`](https://github.com/anthropics/claude-plugins-official)。该文件就是目录本身。67* **在 GitHub 上**：打开市场存储库中的 `.claude-plugin/marketplace.json`，例如 [`anthropics/claude-plugins-official`](https://github.com/anthropics/claude-plugins-official)。该文件就是目录本身。

68 68

69Anthropic 的目录与这些市场分开。该目录是 claude.ai 上的目录，`/plugin` 不会列出它。你从 claude.ai 上的目录添加的插件通过[账户同步](/docs/zh-CN/plugins/loading#synced-plugins)到达 Claude Code。要在那里列出你自己的插件，请参阅[提交到 Anthropic 的目录](/docs/zh-CN/plugins/publish#submit-to-anthropics-directory)。

69要从桌面应用或脚本安装，或查看云会话加载的内容，请参阅[安装插件](/docs/zh-CN/plugins/install)。71要从桌面应用或脚本安装，或查看云会话加载的内容，请参阅[安装插件](/docs/zh-CN/plugins/install)。

70 72

71<h3 id="add-the-community-or-demo-marketplace">73<h3 id="add-the-community-or-demo-marketplace">

plugins/cli-reference.md +19 −1

Details

165 165

166Claude Code 打印 `Successfully uninstalled plugin: formatter (scope: project)`。当 plugin 未在该作用域安装时，命令打印以 `Failed to uninstall plugin "formatter@my-marketplace":` 开头的行，退出 `1`。166Claude Code 打印 `Successfully uninstalled plugin: formatter (scope: project)`。当 plugin 未在该作用域安装时，命令打印以 `Failed to uninstall plugin "formatter@my-marketplace":` 开头的行，退出 `1`。

167 167

168如果失败行继续显示 `"formatter" was not uninstalled:`，Claude Code 无法确认该作用域的设置不再打开 plugin，因此 plugin 保持安装状态，并保留其保存的所有内容。使用 `--json`，结果带有 `failureCode: "settings_still_on"`。此设置检查需要 Claude Code v2.1.282 或更高版本。

169

170<h4 id="what-an-uninstall-deletes-and-keeps">

171 卸载删除和保留的内容

172</h4>

173

174当您从最后一个安装 plugin 的作用域卸载它时，Claude Code 也删除 plugin 的存储 [options 和 secrets](/docs/zh-CN/plugins/manifest-reference#user-configuration) 及其数据目录 `~/.claude/plugins/data/<id>/`。有三个例外：

175

176* 使用 `--keep-data`，数据目录保留

177* 当另一个已安装的 plugin 使用相同的文件夹时，例如其 ID 仅在字母大小写上与此不同的 plugin，数据目录保留

178* 当 Claude Code 无法在从该作用域删除 plugin 后读回已安装 plugins 的列表时，options、secrets 和数据目录都保留，因为 plugin 可能仍在另一个作用域安装。卸载仍然成功。消息列出保留的内容及如何删除它，使用 `--json` 结果带有 `savedKept: "install_records_unreadable"`

179

180使用 `--json`，`keptData` 报告目录是否保留，`/plugin` 在保留时显示 `· data preserved`。对于在没有 `--keep-data` 的情况下保留的目录，此报告需要 Claude Code v2.1.281 或更高版本。`savedKept` 字段需要 Claude Code v2.1.282 或更高版本。

181

168<h3 id="plugin-enable">182<h3 id="plugin-enable">

169 plugin enable183 plugin enable

170</h3>184</h3>

248 262

249| 标志 | 描述 |263| 标志 | 描述 |

250| :- | :- |264| :- | :- |

252| `-y, --yes` | 接受来自 [command-source](/docs/zh-CN/plugins/host-marketplace) plugin 的更改的安装命令，无需提示。当 stdin 或 stdout 不是 TTY 时需要，除非您传递 `--accept-command`。需要 Claude Code v2.1.229 或更高版本 |266| `-y, --yes` | 接受来自 [command-source](/docs/zh-CN/plugins/host-marketplace) plugin 的更改的安装命令，无需提示。当 stdin 或 stdout 不是 TTY 时需要，除非您传递 `--accept-command`。需要 Claude Code v2.1.229 或更高版本 |

253| `--accept-command <sha256>` | 接受市场声明的命令，其 `sha256` 之前的 [`--json` 运行](#plugin-json-result) 在 `shownCommand` 中报告，代替 `-y`。不能与 `-y` 组合。需要 Claude Code v2.1.271 或更高版本 |267| `--accept-command <sha256>` | 接受市场声明的命令，其 `sha256` 之前的 [`--json` 运行](#plugin-json-result) 在 `shownCommand` 中报告，代替 `-y`。不能与 `-y` 组合。需要 Claude Code v2.1.271 或更高版本 |

254| `--json` | 将结果作为一个 JSON 对象打印在 stdout 的最后一行，格式与 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更高版本 |268| `--json` | 将结果作为一个 JSON 对象打印在 stdout 的最后一行，格式与 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更高版本 |

255 269

270如果您省略 `--scope`，命令在您当前项目安装的最具体作用域处更新 plugin，检查本地、项目、用户，然后托管。

271

272在 v2.1.281 之前，当您省略 `--scope` 时命令使用 `user`，因此更新仅在项目或本地作用域安装的 plugin 失败，显示 `Plugin "<name>" is not installed at scope user`。在这些版本上，传递 `--scope`。

273

256`managed` 是您可以更新但不能安装的唯一作用域。对于管理员安装的 plugins，请参阅 [为您的组织管理 plugins](/docs/zh-CN/plugins/org)。274`managed` 是您可以更新但不能安装的唯一作用域。对于管理员安装的 plugins，请参阅 [为您的组织管理 plugins](/docs/zh-CN/plugins/org)。

257 275

258更新 plugin：276更新 plugin：

plugins/components.md +93 −93

Details

413 413

414 * **构建您的第一个插件**：从[创建插件](/docs/zh-CN/plugins/create)开始414 * **构建您的第一个插件**：从[创建插件](/docs/zh-CN/plugins/create)开始

415 * **安装他人的插件**：请参阅[安装插件](/docs/zh-CN/plugins/install)415 * **安装他人的插件**：请参阅[安装插件](/docs/zh-CN/plugins/install)

416 * **您的插件用户在 claude.ai 或 Cowork 中**：那里加载的是不同的组件集。请参阅[claude.ai 和 Cowork 中的插件](https://claude.com/docs/plugins/overview)416 * **您的插件用户在 claude.ai 或 Cowork 中**：那里加载的是不同的组件集。请参阅[插件结构和测试](https://claude.com/docs/plugins/build)和[组件支持表](https://claude.com/docs/plugins/platform-support#compare-component-support-by-app)

417</Note>417</Note>

418 418

419<h2 id="explore-the-plugin-directory">419<h2 id="explore-the-plugin-directory">

436 436

437<PluginExplorer>437<PluginExplorer>

438 <Piece id="manifest">438 <Piece id="manifest">

439 [清单](/docs/zh-CN/plugins/manifest-reference)是插件 `.claude-plugin/` 目录中的 `plugin.json` 文件。它包含插件的元数据和 Claude Code 提示用户的 `userConfig` 值。只有 `name` 是必需的。在这个文件中，`description` 是用户在 `/plugin` 中看到的插件文本，`version` 使用户保持在该版本，直到您更改它：439 [清单](/docs/zh-CN/plugins/manifest-reference)是插件 `.claude-plugin/` 目录中的 `plugin.json` 文件。它包含插件的元数据和 Claude Code 提示用户的 `userConfig` 值。Claude Code 可以在没有清单的情况下加载插件，但 [Anthropic 的目录](/docs/zh-CN/plugins/publish#submit-to-anthropics-directory)需要它。在文件中，只有 `name` 是必需的。在这个文件中，`description` 是用户在 `/plugin` 中看到的插件文本，`version` 使用户保持在该版本，直到您更改它：

440 440

441 ```json theme={null}441 ```json theme={null}

442 {442 {

637 添加每种组件637 添加每种组件

638</h2>638</h2>

639 639

640下面的每个部分涵盖一种组件：其文件在插件中的位置、一个验证的示例、插件加载后用户看到的内容，以及改变默认位置的清单键。添加您的插件需要的那些；没有一个是必需的。640下面的每个部分涵盖一种组件：其文件在插件中的位置、一个验证示例、插件加载后用户看到的内容，以及更改默认位置的清单键。添加你的插件需要的组件；没有任何组件是必需的。

641 641

642<h3 id="skills">642<h3 id="skills">

643 Skills643 Skills

644</h3>644</h3>

645 645

646一个 [skill](/docs/zh-CN/skills) 是一个 `SKILL.md` 文件，当其描述与任务匹配时 Claude 可以加载它。用户也可以将其作为命令运行。将每个 skill 保存在 `skills/` 下的自己的目录中：646一个 [skill](/docs/zh-CN/skills) 是一个 `SKILL.md` 文件，当其描述与任务匹配时，Claude 可以加载它。用户也可以将其作为命令运行。将每个 skill 保存在 `skills/` 下的自己的目录中：

647 647

648```text theme={null}648```text theme={null}

649my-plugin/649my-plugin/

664Review the changed files. Report style problems first, then missing tests.664Review the changed files. Report style problems first, then missing tests.

665```665```

666 666

667加载插件后，`/my-plugin:review` 运行 skill。命令名称和谁可以调用它遵循这些规则：667加载插件后，`/my-plugin:review` 运行该 skill。命令名称和谁可以调用它遵循以下规则：

668 668

669* **命令名称**：`/<plugin>:<directory>`，所以 `my-plugin` 中的 `skills/review/SKILL.md` 是 `/my-plugin:review`。如果您在 frontmatter 中设置 `name`，它替换最后一段，插件前缀保持不变。请参阅[skill 如何获得其命令名称](/docs/zh-CN/skills#how-a-skill-gets-its-command-name)669* **命令名称**：`/<plugin>:<directory>`，所以 `my-plugin` 中的 `skills/review/SKILL.md` 是 `/my-plugin:review`。如果你在 frontmatter 中设置 `name`，它会替换最后一段，插件前缀保持不变。参见 [skill 如何获得其命令名称](/docs/zh-CN/skills#how-a-skill-gets-its-command-name)

670* **谁调用它**：Claude、用户或两者，由 frontmatter 控制。请参阅[控制谁调用 skill](/docs/zh-CN/skills#control-who-invokes-a-skill)670* **谁调用它**：Claude、用户或两者，由 frontmatter 控制。参见 [控制谁调用 skill](/docs/zh-CN/skills#control-who-invokes-a-skill)

671 671

672您也可以将 skills 放在默认 `skills/` 目录之外：672你也可以将 skills 放在默认 `skills/` 目录之外：

673 673

674* **其他目录**：在 `skills` 清单键中列出它们。它们添加到默认 `skills/` 扫描，而不是替换它，不像 `commands` 和 `agents`674* **其他目录**：在 `skills` 清单键中列出它们。它们添加到默认 `skills/` 扫描中，而不是替换它，不同于 `commands` 和 `agents`

675* **插件根目录中的单个 skill**：没有 `skills/` 目录且没有 `skills` 清单键，插件根目录中的 `SKILL.md` 加载为一个 skill。在其 frontmatter 中设置 `name`，因为否则市场安装会根据其[缓存目录](/docs/zh-CN/plugins/loading#find-plugins-on-disk)而不是您的插件命名 skill675* **插件根目录中的单个 skill**：没有 `skills/` 目录且没有 `skills` 清单键的情况下，插件根目录中的 `SKILL.md` 作为一个 skill 加载。在其 frontmatter 中设置 `name`，因为否则 marketplace 安装会根据其 [缓存目录](/docs/zh-CN/plugins/loading#find-plugins-on-disk) 而不是你的插件来命名该 skill

676 676

677要在插件中包含说明，请将其写成 skill。Claude Code 不加载插件根目录中的 `CLAUDE.md`，`claude plugin validate` 警告 `CLAUDE.md at the plugin root is not loaded as project context`。677要在插件中包含说明，将其写成 skill。Claude Code 不会在插件根目录加载 `CLAUDE.md`，`claude plugin validate` 会警告 `CLAUDE.md at the plugin root is not loaded as project context`。

678 678

679对于 frontmatter 字段和支持文件，请参阅 [Skills](/docs/zh-CN/skills)。679对于 frontmatter 字段和支持文件，参见 [Skills](/docs/zh-CN/skills)。

680 680

681<h3 id="commands">681<h3 id="commands">

682 命令682 Commands

683</h3>683</h3>

684 684

685命令是用户按名称运行的单个 Markdown 文件，例如 `/my-plugin:about`。685命令是用户按名称运行的单个 Markdown 文件，例如 `/my-plugin:about`。

686 686

687<Note>687<Note>

688 命令是较旧的格式，[skills](#skills) 对新工作已经取代它们。skill 以相同的方式按名称运行，它也可以在其目录中携带支持文件。为您从 `.claude/commands/` 移动的文件保留 `commands/`。688 Commands 是较旧的格式，[skills](#skills) 对新工作已经取代了它们。skill 以相同的方式按名称运行，它也可以在其目录中携带支持文件。对于你从 `.claude/commands/` 迁移过来的文件，保留 `commands/`。

689</Note>689</Note>

690 690

691将命令保存在 `commands/<file>.md`，它变成 `/<plugin>:<file>`。子目录添加一个段，所以 `commands/db/migrate.md` 是 `/my-plugin:db:migrate`。691在 `commands/<file>.md` 保存命令，它变成 `/<plugin>:<file>`。子目录添加一个段，所以 `commands/db/migrate.md` 是 `/my-plugin:db:migrate`。

692 692

693命令文件采用与 skills 相同的 frontmatter。693命令文件采用与 skills 相同的 frontmatter。

694 694

696 在清单中定义命令696 在清单中定义命令

697</h4>697</h4>

698 698

699只有当您想将命令文件保留在 `commands/` 之外的某个地方，或在 `plugin.json` 中定义一个短命令而不需要单独的 Markdown 文件时，您才需要这样做。设置 `commands` 清单键，Claude Code 读取它而不是扫描 `commands/`。该键采用路径、路径数组或将每个命令名称映射到 `source` 文件或内联 `content` 的对象。699只有当你想将命令文件保存在 `commands/` 之外的地方，或在 `plugin.json` 中定义一个短命令而不需要单独的 Markdown 文件时，你才需要这样做。设置 `commands` 清单键，Claude Code 会读取它而不是扫描 `commands/`。该键接受一个路径、路径数组或一个对象，该对象将每个命令名称映射到 `source` 文件或内联 `content`。

700 700

701此清单内联定义 `/my-plugin:about`，没有 Markdown 文件：701此清单内联定义 `/my-plugin:about`，没有 Markdown 文件：

702 702

714 714

715加载插件并在会话中运行 `/my-plugin:about` 以确认它已加载。715加载插件并在会话中运行 `/my-plugin:about` 以确认它已加载。

716 716

717对于完整的键语法，请参阅 [`commands`](/docs/zh-CN/plugins/manifest-reference#commands)。717对于完整的键语法，参见 [`commands`](/docs/zh-CN/plugins/manifest-reference#commands)。

718 718

719<h3 id="agents">719<h3 id="agents">

720 Agents720 Agents

721</h3>721</h3>

722 722

723一个[子代理](/docs/zh-CN/sub-agents)是一个单独的助手，拥有自己的说明和上下文窗口，Claude 可以将任务委托给它。`agents/` 下的每个 Markdown 文件定义一个：723一个 [subagent](/docs/zh-CN/sub-agents) 是一个单独的助手，有自己的说明和上下文窗口，Claude 可以将任务委托给它。`agents/` 下的每个 Markdown 文件定义一个：

724 724

725```markdown agents/security-reviewer.md theme={null}725```markdown agents/security-reviewer.md theme={null}

726---726---

732You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.732You are a security reviewer. Read the changed files and report injection, authentication, and secrets-handling risks.

733```733```

734 734

735此 agent 被命名为 `my-plugin:security-reviewer`，用户可以[显式调用它](/docs/zh-CN/sub-agents#invoke-subagents-explicitly)使用 `@agent-my-plugin:security-reviewer`。名称形式是 `<plugin>:<name>`，其中 `<name>` 来自 frontmatter，或当没有时来自文件名。735此代理名为 `my-plugin:security-reviewer`，用户可以使用 `@agent-my-plugin:security-reviewer` [显式调用它](/docs/zh-CN/sub-agents#invoke-subagents-explicitly)。名称形式是 `<plugin>:<name>`，其中 `<name>` 来自 frontmatter，或在没有时来自文件名。

736 736

737`agents` 清单键替换 `agents/` 扫描。737`agents` 清单键替换 `agents/` 扫描。

738 738

739<h4 id="organize-agents-in-subfolders">739<h4 id="organize-agents-in-subfolders">

740 在子文件夹中组织 agents740 在子文件夹中组织代理

741</h4>741</h4>

742 742

743您可以将插件 agent 文件放在 `agents/` 的子文件夹中。Claude Code [递归加载它们](/docs/zh-CN/sub-agents#choose-the-subagent-scope)并用冒号连接插件名称、每个子文件夹名称和文件名以形成 agent 的作用域名称。例如，`my-plugin` 中的 `agents/review/security.md` 加载为 `my-plugin:review:security`。两个设置改变该名称：743你可以将插件代理文件放在 `agents/` 的子文件夹中。Claude Code [递归加载它们](/docs/zh-CN/sub-agents#choose-the-subagent-scope)，并用冒号连接插件名称、每个子文件夹名称和文件名，以形成代理的作用域名称。例如，`my-plugin` 插件中的 `agents/review/security.md` 加载为 `my-plugin:review:security`。两个设置改变该名称：

744 744

745* Frontmatter `name`：它仅替换文件名，所以 `agents/review/security.md` 中的 `name: audit` 加载为 `my-plugin:review:audit`745* Frontmatter `name`：它仅替换文件名，所以 `agents/review/security.md` 中的 `name: audit` 加载为 `my-plugin:review:audit`

746* 清单 [`agents`](/docs/zh-CN/plugins/manifest-reference#fields) 字段：您在那里列出的文件加载时不带子文件夹名称，所以 `"agents": "./custom/review/security.md"` 加载为 `my-plugin:security`746* 清单 [`agents`](/docs/zh-CN/plugins/manifest-reference#fields) 字段：你在那里列出的文件加载时不带子文件夹名称，所以 `"agents": "./custom/review/security.md"` 加载为 `my-plugin:security`

747 747

748<h4 id="frontmatter-fields-in-plugin-agents">748<h4 id="frontmatter-fields-in-plugin-agents">

749 插件 agents 中的 Frontmatter 字段749 插件代理中的 Frontmatter 字段

750</h4>750</h4>

751 751

752插件 agent 的 frontmatter 遵循这些规则：752插件代理的 frontmatter 遵循以下规则：

753 753

754* **支持的字段**：`name`、`description`、`model`、`effort`、`maxTurns`、`tools`、`disallowedTools`、`skills`、`memory`、`background`、`omitClaudeMd`、`isolation`、`color` 和 `experimental` 的 `cacheTtl` 键。唯一有效的 `isolation` 值是 `"worktree"`。请参阅[支持的 frontmatter 字段](/docs/zh-CN/sub-agents#supported-frontmatter-fields)了解每个字段的作用754* **支持的字段**：`name`、`description`、`model`、`effort`、`maxTurns`、`tools`、`disallowedTools`、`skills`、`memory`、`background`、`omitClaudeMd`、`isolation`、`color` 和 `experimental` 的 `cacheTtl` 键。唯一有效的 `isolation` 值是 `"worktree"`。参见 [支持的 frontmatter 字段](/docs/zh-CN/sub-agents#supported-frontmatter-fields) 了解每个字段的作用

755* **忽略的字段**：`permissionMode`、`hooks`、`mcpServers` 和 `initialPrompt`。agent 文件不能自己添加 hooks 或 MCP 服务器，所以改为添加这些作为插件 [hooks](#hooks) 和 [MCP 服务器](#mcp-servers)755* **忽略的字段**：`permissionMode`、`hooks`、`mcpServers` 和 `initialPrompt`。代理文件不能自己添加 hooks 或 MCP 服务器，所以改为添加为插件 [hooks](#hooks) 和 [MCP 服务器](#mcp-servers)

756* **不解析的 Frontmatter**：agent 仍然加载，每个字段都被忽略。它根据文件命名，其描述读作 `Agent from my-plugin plugin`。在 shell 中运行 [`claude plugin validate`](/docs/zh-CN/plugins/cli-reference#plugin-validate) 来找到这些文件756* **不解析的 Frontmatter**：代理仍然加载，每个字段都被忽略。它以文件名命名，其描述读作 `Agent from my-plugin plugin`。在你的 shell 中运行 [`claude plugin validate`](/docs/zh-CN/plugins/cli-reference#plugin-validate) 来找到这些文件

757 757

758对于每个字段的作用和优先级规则，请参阅 [Subagents](/docs/zh-CN/sub-agents#supported-frontmatter-fields)。758对于每个字段的作用和优先级规则，参见 [Subagents](/docs/zh-CN/sub-agents#supported-frontmatter-fields)。

759 759

760<h3 id="hooks">760<h3 id="hooks">

761 Hooks761 Hooks

762</h3>762</h3>

763 763

764一个 [hook](/docs/zh-CN/hooks-guide) 在 Claude Code 生命周期中的某个点自动运行某些内容，例如在每次文件编辑后：shell 命令、HTTP 请求、MCP 工具调用、对模型的提示或子代理。将插件的 hooks 保存在插件根目录的 `hooks/hooks.json` 中，在顶级 `"hooks"` 键下，形状与 `settings.json` 中的 `hooks` 对象相同。这让您可以复制现有的设置 hook 而不改变。764一个 [hook](/docs/zh-CN/hooks-guide) 在 Claude Code 生命周期中的某个点自动运行某些东西，例如在每次文件编辑后：shell 命令、HTTP 请求、MCP 工具调用、对模型的提示或 subagent。在插件根目录的 `hooks/hooks.json` 中保存插件的 hooks，在顶级 `"hooks"` 键下，形状与 `settings.json` 中的 `hooks` 对象相同。这让你可以复制现有的设置 hook 而不做任何改变。

765 765

766此 hook 在每次 `Write` 或 `Edit` 后运行一个捆绑脚本：766此 hook 在每次 `Write` 或 `Edit` 后运行一个捆绑脚本：

767 767

783}783}

784```784```

785 785

786将脚本保存在 `scripts/format.sh` 并使其可执行。786在 `scripts/format.sh` 保存脚本并使其可执行。

787 787

788加载插件并要求 Claude 编辑文件。退出 0 的 `PostToolUse` hook 在记录中显示任何内容，所以用[调试日志](/docs/zh-CN/hooks#debug-hooks)或脚本本身改变的内容确认它运行。788加载插件并要求 Claude 编辑文件。退出 0 的 `PostToolUse` hook 在记录中不显示任何内容，所以用 [调试日志](/docs/zh-CN/hooks#debug-hooks) 或脚本本身所做的更改来确认它运行了。

789 789

790`hooks/hooks.json` 和 `hooks` 清单键中的 Hooks 都加载。对于每个事件及其有效负载，请参阅 [Hook 事件](/docs/zh-CN/hooks#hook-events)。790`hooks/hooks.json` 和 `hooks` 清单键中的 hooks 都会加载。对于每个事件及其有效负载，参见 [Hook 事件](/docs/zh-CN/hooks#hook-events)。

791 791

792<h4 id="when-plugin-hooks-fire">792<h4 id="when-plugin-hooks-fire">

793 插件 hooks 何时触发793 插件 hooks 何时触发

794</h4>794</h4>

795 795

796插件的 hooks 不等待使用插件的一个 skills 或命令。Claude Code 在会话加载插件时注册它们，从那时起它们在其事件上触发。要限制 hook 何时运行，缩小其 `matcher`。796插件的 hooks 不会等待使用插件的某个 skill 或命令。Claude Code 在会话加载插件时注册它们，从那时起它们在其事件上触发。要限制 hook 何时运行，缩小其 `matcher`。

797 797

798如果 hook 从不触发，请参阅[不触发的 hooks](/docs/zh-CN/plugins/troubleshooting#failed-to-load-hooks-from-and-hooks-that-dont-fire)。798如果 hook 从不触发，参见 [不触发的 hooks](/docs/zh-CN/plugins/troubleshooting#failed-to-load-hooks-from-and-hooks-that-dont-fire)。

799 799

800<h4 id="environment-quoting-and-matching-mcp-tools">800<h4 id="environment-quoting-and-matching-mcp-tools">

801 环境、引用和匹配 MCP 工具801 环境、引用和匹配 MCP 工具

803 803

804hook 的环境、`${CLAUDE_PLUGIN_ROOT}` 的引用和插件自己的 MCP 工具的匹配器工作如下：804hook 的环境、`${CLAUDE_PLUGIN_ROOT}` 的引用和插件自己的 MCP 工具的匹配器工作如下：

805 805

806* **环境**：每个 hook 进程在其环境中接收 `CLAUDE_PLUGIN_ROOT` 和 `CLAUDE_PLUGIN_DATA`，加上每个[用户配置](#user-configuration)值的 `CLAUDE_PLUGIN_OPTION_<KEY>`，所以您的脚本可以从那里读取它们806* **环境**：每个 hook 进程在其环境中接收 `CLAUDE_PLUGIN_ROOT` 和 `CLAUDE_PLUGIN_DATA`，加上每个 [用户配置](#user-configuration) 值的 `CLAUDE_PLUGIN_OPTION_<KEY>`，所以你的脚本可以从那里读取它们

807* **引用**：当 `command` 没有 `args` 时，它通过 shell 运行，所以用双引号包装 `${CLAUDE_PLUGIN_ROOT}` 路径，如 [Hooks](#hooks) 下的 `hooks/hooks.json` 示例所做的那样，以保持扩展的路径为一个 shell 单词。当您改为传递 `args` 时，每个元素作为一个参数传递，没有 shell，不需要引用。请参阅 [exec 形式和 shell 形式](/docs/zh-CN/hooks#exec-form-and-shell-form)807* **引用**：当 `command` 没有 `args` 时，它通过 shell 运行，所以用双引号包装 `${CLAUDE_PLUGIN_ROOT}` 路径，如 [Hooks](#hooks) 下的 `hooks/hooks.json` 示例所做的那样，以保持展开的路径为一个 shell 单词。当你改为传递 `args` 时，每个元素作为一个参数传递，没有 shell，不需要引用。参见 [exec 形式和 shell 形式](/docs/zh-CN/hooks#exec-form-and-shell-form)

808* **匹配插件自己的 MCP 工具**：来自此插件声明的 [MCP 服务器](#mcp-servers)的工具被命名为 `mcp__plugin_<plugin>_<server>__<tool>`，所以在匹配器中写那个完整名称。仅在服务器名称上的匹配器从不触发。请参阅[匹配 MCP 工具](/docs/zh-CN/hooks#match-mcp-tools)808* **匹配插件自己的 MCP 工具**：来自此插件声明的 [MCP 服务器](#mcp-servers) 的工具名为 `mcp__plugin_<plugin>_<server>__<tool>`，所以在匹配器中写入该完整名称。仅在服务器名称上的匹配器从不触发。参见 [匹配 MCP 工具](/docs/zh-CN/hooks#match-mcp-tools)

809 809

810<h3 id="mcp-servers">810<h3 id="mcp-servers">

811 MCP 服务器811 MCP servers

812</h3>812</h3>

813 813

814MCP 服务器从外部系统为 Claude 提供工具。在插件根目录的 `.mcp.json` 中声明它，形状与[项目 `.mcp.json`](/docs/zh-CN/mcp#project-scope) 相同。此 `.mcp.json` 声明一个名为 `db` 的服务器：814MCP 服务器从外部系统为 Claude 提供工具。在插件根目录的 `.mcp.json` 中声明它，形状与 [项目 `.mcp.json`](/docs/zh-CN/mcp#project-scope) 相同。此 `.mcp.json` 声明一个名为 `db` 的服务器：

815 815

816```json .mcp.json theme={null}816```json .mcp.json theme={null}

817{817{

824}824}

825```825```

826 826

827您也可以省略 `mcpServers` 包装器并将 `db` 放在文件的顶级。827你也可以省略 `mcpServers` 包装器，将 `db` 放在文件的顶级。

828 828

829加载插件并运行 `/mcp` 以确认服务器显示为 `plugin:my-plugin:db`。829加载插件并运行 `/mcp` 以确认服务器显示为 `plugin:my-plugin:db`。

830 830

831`claude plugin validate` 检查 `.mcp.json` 并报告 Claude Code 在加载时会丢弃的服务器条目为错误。需要 Claude Code v2.1.281 或更高版本。831`claude plugin validate` 检查 `.mcp.json` 并报告 Claude Code 在加载时会丢弃的服务器条目为错误。需要 Claude Code v2.1.281 或更高版本。

832 832

833对于坏条目在加载时显示的位置，请参阅[不启动的 MCP 服务器](/docs/zh-CN/plugins/troubleshooting#invalid-mcp-server-config-for-and-mcp-servers-that-dont-start)。833对于坏条目在加载时显示的位置，参见 [不启动的 MCP 服务器](/docs/zh-CN/plugins/troubleshooting#invalid-mcp-server-config-for-and-mcp-servers-that-dont-start)。

834 834

835`mcpServers` 清单键采用内联服务器映射、JSON 文件的路径或这些的数组。当清单服务器与 `.mcp.json` 中的一个同名时，清单服务器替换它。835`mcpServers` 清单键接受内联服务器映射、JSON 文件的路径或这些的数组。当清单服务器与 `.mcp.json` 中的服务器同名时，清单服务器替换它。

836 836

837<h4 id="reach-users-on-claude-ai-and-cowork">837<h4 id="reach-users-on-claude-ai-and-cowork">

838 到达 claude.ai 和 Cowork 中的用户838 到达 claude.ai 和 Cowork 上的用户

839</h4>839</h4>

840 840

841本地 stdio 服务器，例如 [MCP 服务器](#mcp-servers) 下的 `db` 服务器，在 Claude Code 和在 Claude Desktop 应用中在您的机器上运行的 Cowork 会话中运行，但不在 claude.ai 上。要到达那里的用户，通过其 `https://` URL 引用远程服务器，claude.ai 和 Cowork 作为连接器提供给用户。841本地 stdio 服务器，例如 [MCP 服务器](#mcp-servers) 下的 `db` 服务器，在 Claude Code 和在 Claude Desktop 应用中在你的机器上运行的 Cowork 会话中运行，但不在 claude.ai 上。要到达那里的用户，通过其 `https://` URL 引用远程服务器，claude.ai 和 Cowork 将其作为连接器提供给用户，如 [将 MCP 连接器与其 skill 捆绑](https://claude.com/docs/plugins/build#bundle-an-mcp-connector-with-its-skill) 所示。

842 842

843<h4 id="server-names-tool-names-and-reloads">843<h4 id="server-names-tool-names-and-reloads">

844 服务器名称、工具名称和重新加载844 服务器名称、工具名称和重新加载

845</h4>845</h4>

846 846

847服务器的名称、变量替换和重新加载行为遵循这些规则：847服务器的名称、变量替换和重新加载行为遵循以下规则：

848 848

849* **服务器名称**：`plugin:<plugin>:<server>`，所以 `my-plugin` 中的 `db` 服务器在 `/mcp` 中是 `plugin:my-plugin:db`。使用相同的形式在 [`mcp_tool` hook](/docs/zh-CN/hooks#mcp-tool-hook-fields) 中命名服务器849* **服务器名称**：`plugin:<plugin>:<server>`，所以 `my-plugin` 中的 `db` 服务器在 `/mcp` 中是 `plugin:my-plugin:db`。使用相同的形式在 [`mcp_tool` hook](/docs/zh-CN/hooks#mcp-tool-hook-fields) 中命名服务器

850* **工具名称**：`mcp__plugin_<plugin>_<server>__<tool>`，所以该 `db` 服务器上的 `query` 工具是 `mcp__plugin_my-plugin_db__query`。这是在[权限规则](/docs/zh-CN/permissions)和 [hook 匹配器](#hooks)中使用的名称850* **工具名称**：`mcp__plugin_<plugin>_<server>__<tool>`，所以该 `db` 服务器上的 `query` 工具是 `mcp__plugin_my-plugin_db__query`。这是在 [权限规则](/docs/zh-CN/permissions) 和 [hook 匹配器](#hooks) 中使用的名称

851* **替换**：`${CLAUDE_PLUGIN_ROOT}` 和其他[路径变量](#path-variables-and-persistent-data)在 `command`、`args` 和 `env` 中被替换。`args` 中不需要引用，因为每个元素作为一个参数传递851* **替换**：`${CLAUDE_PLUGIN_ROOT}` 和其他 [路径变量](#path-variables-and-persistent-data) 在 `command`、`args` 和 `env` 中被替换。`args` 中不需要引用，因为每个元素作为一个参数传递

852* **重新加载**：当用户运行 `/reload-plugins` 并且[重新加载应用](/docs/zh-CN/plugins/cli-reference#reloads-that-change-mcp-tools)时，配置未改变的服务器保持其连接。配置改变的服务器重新连接，您删除的服务器断开连接852* **重新加载**：当用户运行 `/reload-plugins` 且 [重新加载适用](/docs/zh-CN/plugins/cli-reference#reloads-that-change-mcp-tools) 时，配置未更改的服务器保持其连接。配置已更改的服务器重新连接，你删除的服务器断开连接

853 853

854<h4 id="include-a-packaged-mcpb-server">854<h4 id="include-a-packaged-mcpb-server">

855 包含打包的 MCPB 服务器855 包含打包的 MCPB 服务器

856</h4>856</h4>

857 857

858`mcpServers` 键也接受打包的服务器作为 [MCPB 文件](https://github.com/modelcontextprotocol/mcpb)，其扩展名是 `.mcpb` 或较旧的 `.dxt`。将键指向文件，作为插件内的路径或 `https://` URL：858`mcpServers` 键也接受打包的服务器作为 [MCPB 文件](https://github.com/modelcontextprotocol/mcpb)，其扩展名为 `.mcpb` 或较旧的 `.dxt`。将键指向文件，作为插件内的路径或 `https://` URL：

859 859

860```json .claude-plugin/plugin.json theme={null}860```json .claude-plugin/plugin.json theme={null}

861{861{

864}864}

865```865```

866 866

867服务器从包的清单中的 `name` 获取其名称。867服务器从捆绑清单中的 `name` 获取其名称。

868 868

869对于传输和身份验证，请参阅 [MCP](/docs/zh-CN/mcp#plugin-provided-mcp-servers)。869对于传输和身份验证，参见 [MCP](/docs/zh-CN/mcp#plugin-provided-mcp-servers)。

870 870

871<h3 id="lsp-servers">871<h3 id="lsp-servers">

872 LSP 服务器872 LSP servers

873</h3>873</h3>

874 874

875LSP 服务器为 Claude 提供诊断和代码导航。如果[官方代码智能插件](/docs/zh-CN/plugins/code-intelligence)已经涵盖您的语言，安装那个而不是写一个。否则在插件根目录的 `.lsp.json` 中声明服务器：875LSP 服务器为 Claude 提供诊断和代码导航。如果 [官方代码智能插件](/docs/zh-CN/plugins/code-intelligence) 已经涵盖你的语言，安装那个而不是写一个。否则在插件根目录的 `.lsp.json` 中声明服务器：

876 876

877```json .lsp.json theme={null}877```json .lsp.json theme={null}

878{878{

886}886}

887```887```

888 888

889文件直接将每个服务器名称映射到其配置，没有围绕映射的包装对象。`command` 是二进制的名称，其参数在 `args` 中。`extensionToLanguage` 需要至少一个扩展名，每个以 `.` 开头。889文件直接将每个服务器名称映射到其配置，映射周围没有包装对象。`command` 是二进制文件的名称，其参数在 `args` 中。`extensionToLanguage` 需要至少一个扩展名，每个都以 `.` 开头。

890 890

891`claude plugin validate` 不读取此文件。当任何条目无效时，整个文件在加载时被跳过，`Invalid LSP server config for ".lsp.json"` 出现在 `/plugin` **Errors** 标签中。891`claude plugin validate` 不读取此文件。当任何条目无效时，整个文件在加载时被跳过，`Invalid LSP server config for ".lsp.json"` 出现在 `/plugin` **Errors** 标签中。

892 892

893您的插件配置连接但不安装服务器二进制，每个文件扩展名获得一个服务器：893你的插件配置连接但不安装服务器二进制文件，每个文件扩展名获得一个服务器：

894 894

895* **缺少二进制**：Claude Code 从用户的 `PATH` 按名称启动 `command`。当二进制不存在时，服务器启动失败，`claude --debug` 记录 `LSP server <name> failed to start`895* **缺少二进制文件**：Claude Code 从用户的 `PATH` 按名称启动 `command`。当二进制文件不存在时，服务器启动失败，`claude --debug` 记录 `LSP server <name> failed to start`

896* **扩展冲突**：当两个启用的服务器声称相同的扩展名时，首先注册的处理这些文件，另一个不用于它们，无论服务器来自一个插件还是两个。`/plugin` **Errors** 标签显示警告 `LSP server "<name>" is not used for <ext> files`896* **扩展名冲突**：当两个启用的服务器声称相同的扩展名时，首先注册的处理这些文件，另一个不用于它们，无论服务器来自一个插件还是两个。`/plugin` **Errors** 标签显示警告 `LSP server "<name>" is not used for <ext> files`

897 897

898`lspServers` 清单键采用相同的映射内联、JSON 文件的路径或这些的数组，其服务器添加到 `.lsp.json` 中的那些。当清单服务器与 `.lsp.json` 中的一个同名时，清单服务器替换它。898`lspServers` 清单键接受相同的映射内联、JSON 文件的路径或这些的数组，其服务器添加到 `.lsp.json` 中的服务器。当清单服务器与 `.lsp.json` 中的服务器同名时，清单服务器替换它。

899 899

900对于 `transport`、超时、重启和其他字段，请参阅 [`lspServers`](/docs/zh-CN/plugins/manifest-reference#lspservers)。900对于 `transport`、超时、重启和其他字段，参见 [`lspServers`](/docs/zh-CN/plugins/manifest-reference#lspservers)。

901 901

902将日志输出发送到 stderr，而不是 stdout。Claude Code 仅将服务器的 stdout 读取为协议消息，并接受最多 64 KiB 的消息头和最多 32 MiB 的消息正文。902将日志输出发送到 stderr，而不是 stdout。Claude Code 仅将服务器的 stdout 读取为协议消息，并接受最多 64 KiB 的消息头和最多 32 MiB 的消息体。

903 903

904Claude Code 断开超过任一限制或向 stdout 写入非协议输出的服务器，并将断开连接计为 `restartOnCrash` 和 `maxRestarts` 的崩溃。当您使用 `--debug` 运行时，Claude Code 将命名原因的错误写入调试日志。904Claude Code 断开超过任一限制或向 stdout 写入非协议输出的服务器，并将断开连接计为 `restartOnCrash` 和 `maxRestarts` 的崩溃。当你使用 `--debug` 运行时，Claude Code 将命名原因的错误写入调试日志。

905 905

906<h3 id="executables">906<h3 id="executables">

907 可执行文件907 Executables

908</h3>908</h3>

909 909

910插件根目录中 `bin/` 中的文件在启用插件时位于 Bash 工具的 shell 的 `PATH` 上，所以 Claude 可以将它们作为裸命令运行。添加一个可执行脚本：910插件根目录中 `bin/` 中的文件在启用插件时位于 Bash 工具的 shell 的 `PATH` 上，所以 Claude 可以将它们作为裸命令运行。添加一个可执行脚本：

914echo "hello from my-plugin"914echo "hello from my-plugin"

915```915```

916 916

917使用 `chmod +x bin/hello-plugin` 使其可执行并加载插件。当您要求 Claude 运行 `hello-plugin` 时，Bash 工具结果显示脚本的输出。917用 `chmod +x bin/hello-plugin` 使其可执行并加载插件。当你要求 Claude 运行 `hello-plugin` 时，Bash 工具结果显示脚本的输出。

918 918

919插件 `bin/` 目录在用户自己的 `PATH` 条目之后，所以插件不能影响 `git`、`ls` 或另一个系统命令。919插件 `bin/` 目录位于用户自己的 `PATH` 条目之后，所以插件不能遮蔽 `git`、`ls` 或另一个系统命令。

920 920

921claude.ai 和 Cowork 不安装具有顶级 `bin/` 目录的插件，包括您[通过 claude.ai 组织设置分发](/docs/zh-CN/plugins/host-marketplace#distribute-through-organization-settings)的那个。921claude.ai 和 Cowork 不安装具有顶级 `bin/` 目录的插件，包括你 [通过 claude.ai 组织设置分发的](https://claude.com/docs/plugins/org-sync#keep-executables-out-of-the-top-level-bin-directory) 插件。

922 922

923<h3 id="default-settings">923<h3 id="default-settings">

924 默认设置924 Default settings

925</h3>925</h3>

926 926

927要设置在启用插件时应用的默认值，在插件根目录添加 `settings.json`，或将相同的对象内联放在 `settings` 清单键中。两个键生效，`agent` 和 `subagentStatusLine`，所有其他键都被丢弃。927要设置在启用插件时应用的默认值，在插件根目录添加 `settings.json`，或将相同的对象内联放在 `settings` 清单键中。两个键生效，`agent` 和 `subagentStatusLine`，每个其他键都被丢弃。

928 928

929设置 `agent` 以将插件自己的一个 agents 作为主线程运行：929设置 `agent` 以将插件自己的一个代理作为主线程运行：

930 930

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

932{932{

934}934}

935```935```

936 936

937加载插件并启动会话。Claude 然后在主对话中使用 `security-reviewer` agent 的系统提示和模型回答。937加载插件并启动会话。Claude 然后在主对话中用 `security-reviewer` 代理的系统提示和模型回答。

938 938

939对于键控制的所有内容，请参阅 [`agent` 设置](/docs/zh-CN/settings-reference#agent)。939对于该键控制的所有内容，参见 [`agent` 设置](/docs/zh-CN/settings-reference#agent)。

940 940

941当相同的键在多个地方设置时，这些规则决定哪个值应用：941当相同的键在多个地方设置时，这些规则决定哪个值适用：

942 942

943* **文件优于清单**：当两者都存在且 `settings.json` 设置至少一个支持的键时，`settings.json` 应用，清单的 `settings` 被忽略943* **文件优于清单**：当两者都存在且 `settings.json` 设置至少一个支持的键时，`settings.json` 适用，清单的 `settings` 被忽略

944* **用户设置优于插件默认值**：跨设置源，插件默认值是最低层，所以用户自己在 `~/.claude/settings.json` 中的 `agent` 覆盖您的944* **用户设置优于插件默认值**：跨设置源，插件默认值是最低层，所以用户自己在 `~/.claude/settings.json` 中的 `agent` 覆盖你的

945* **两个插件设置相同的键**：最后加载的插件的值应用，`claude --debug` 记录 `overrides setting`945* **两个插件设置相同的键**：来自最后加载的插件的值适用，`claude --debug` 记录 `overrides setting`

946 946

947对于 `subagentStatusLine` 形状，请参阅[子代理状态行](/docs/zh-CN/statusline#subagent-status-lines)。947对于 `subagentStatusLine` 形状，参见 [subagent 状态行](/docs/zh-CN/statusline#subagent-status-lines)。

948 948

949<h3 id="themes-and-output-styles">949<h3 id="themes-and-output-styles">

950 主题和输出样式950 Themes and output styles

951</h3>951</h3>

952 952

953插件可以包含颜色主题和输出样式。两者都显示在与用户自己相同的选择器中。对于任一个，设置清单键替换文件夹扫描。953插件可以包含颜色主题和输出样式。两者都出现在与用户自己相同的选择器中。对于任一个，设置清单键替换文件夹扫描。

954 954

955| 组件 | 保存为 | 格式 | 显示在 | 清单键 |955| 组件 | 保存为 | 格式 | 出现在 | 清单键 |

956| :- | :- | :- | :- | :- |956| :- | :- | :- | :- | :- |

959 959

960插件主题是只读的，所以当用户在 `/theme` 中编辑一个时，编辑被保存为他们自己的主题目录中的副本。960插件主题是只读的，所以当用户在 `/theme` 中编辑一个时，编辑被保存为其自己的主题目录中的副本。

961 961

962此主题在深色预设上重新着色提示符强调和错误文本：962此主题在深色预设上重新着色提示符强调和错误文本：

963 963

973```973```

974 974

975<h3 id="channels">975<h3 id="channels">

976 频道976 Channels

977</h3>977</h3>

978 978

979一个[频道](/docs/zh-CN/channels)让外部系统（例如聊天应用）将消息发送到会话中。在插件中，频道是 MCP 服务器之一加上一个 `channels` 条目，将其绑定并可以提示其自己的配置。此清单将频道绑定到 `telegram` 服务器并要求机器人令牌：979一个 [channel](/docs/zh-CN/channels) 让外部系统（如聊天应用）将消息发送到会话中。在插件中，channel 是 MCP 服务器之一加上一个 `channels` 条目，该条目绑定到它并可以提示其自己的配置。此清单将 channel 绑定到 `telegram` 服务器并要求机器人令牌：

980 980

981```json .claude-plugin/plugin.json theme={null}981```json .claude-plugin/plugin.json theme={null}

982{982{

1004}1004}

1005```1005```

1006 1006

1007`server` 必须匹配 `mcpServers` 中的键。每个频道的 `userConfig` 采用与[顶级 `userConfig` 键](#user-configuration)相同的形状。1007`server` 必须匹配 `mcpServers` 中的键。每个 channel 的 `userConfig` 采用与 [顶级 `userConfig` 键](#user-configuration) 相同的形状。

1008 1008

1009对于服务器必须实现的内容以及用户如何启用频道插件，请参阅频道参考中的[打包为插件](/docs/zh-CN/channels-reference#package-as-a-plugin)。对于字段表，请参阅 [`channels`](/docs/zh-CN/plugins/manifest-reference#channels)。1009对于服务器必须实现的内容以及用户如何启用 channel 插件，参见 channels 参考中的 [打包为插件](/docs/zh-CN/channels-reference#package-as-a-plugin)。对于字段表，参见 [`channels`](/docs/zh-CN/plugins/manifest-reference#channels)。

1010 1010

1011<h3 id="monitors">1011<h3 id="monitors">

1012 监视器1012 Monitors

1013</h3>1013</h3>

1014 1014

1015监视器是在整个会话中在后台运行的 shell 命令。它打印的内容作为通知到达 Claude，所以 Claude 可以对日志或状态更改做出反应，而无需被要求观看它。将条目保存在 `monitors/monitors.json` 中：1015monitor 是在整个会话中在后台运行的 shell 命令。它打印的内容作为通知到达 Claude，所以 Claude 可以对日志或状态更改做出反应，而无需被要求观看它。在 `monitors/monitors.json` 中保存条目：

1016 1016

1017```json monitors/monitors.json theme={null}1017```json monitors/monitors.json theme={null}

1018[1018[

1026 1026

1027命令在 shell 中运行，在会话启动的工作目录中。1027命令在 shell 中运行，在会话启动的工作目录中。

1028 1028

1029监视器的命令在它启动的位置和它可以引用的内容中受到限制：1029monitor 的命令在其启动位置和可以引用的内容方面受到限制：

1030 1030

1031* **仅交互式会话**：插件监视器在交互式会话中启动，从不在带 `-p` 标志的非交互式模式中。它们也仅在 [Monitor 工具](/docs/zh-CN/tools-reference#monitor-tool)可用的地方启动1031* **仅交互式会话**：插件 monitors 在交互式会话中启动，从不在带 `-p` 标志的非交互式模式中启动。它们也仅在 [Monitor 工具](/docs/zh-CN/tools-reference#monitor-tool) 可用的地方启动

1032* **无用户配置**：`command` 获取[路径变量](#path-variables-and-persistent-data)和环境中的 `${ENV_VAR}`，但从不获取 `${user_config.*}`。引用一个的监视器不启动，监视器进程也不接收 `CLAUDE_PLUGIN_OPTION_<KEY>`1032* **无用户配置**：`command` 从环境中获取 [路径变量](#path-variables-and-persistent-data) 和 `${ENV_VAR}`，但从不获取 `${user_config.*}`。引用一个的 monitor 不启动，monitor 进程也不接收 `CLAUDE_PLUGIN_OPTION_<KEY>`

1033* **中途禁用**：如果您在会话中途禁用插件，Claude Code 不停止已经运行的监视器。它们在会话结束时停止1033* **会话中期禁用**：如果你在会话中期禁用插件，Claude Code 不会停止已经运行的 monitors。它们在会话结束时停止

1034 1034

1035`experimental.monitors` 清单键采用相同的数组内联或 JSON 文件的路径，并代替 `monitors/monitors.json` 读取。1035`experimental.monitors` 清单键接受相同的数组内联或 JSON 文件的路径，并被读取而不是 `monitors/monitors.json`。

1036 1036

1037对于 `when` 触发器和其他字段，请参阅 [`monitors`](/docs/zh-CN/plugins/manifest-reference#monitors)。1037对于 `when` 触发器和其他字段，参见 [`monitors`](/docs/zh-CN/plugins/manifest-reference#monitors)。

1038 1038

1039<h2 id="user-configuration">1039<h2 id="user-configuration">

1040 要求用户提供配置值1040 要求用户提供配置值

plugins/create.md +8 −4

Details

15 15

16 * **安装他人的插件**：请参阅[安装插件](/docs/zh-CN/plugins/install)16 * **安装他人的插件**：请参阅[安装插件](/docs/zh-CN/plugins/install)

17 * **不确定是否需要插件**：请参阅概述中的[决定是否需要插件](/docs/zh-CN/plugins/overview#decide-whether-you-need-a-plugin)17 * **不确定是否需要插件**：请参阅概述中的[决定是否需要插件](/docs/zh-CN/plugins/overview#decide-whether-you-need-a-plugin)

18 * **您的插件用户在 claude.ai 或 Cowork 中**：同一文件夹在那里安装，但组件子集不同。请参阅[claude.ai 和 Cowork 中的插件](https://claude.com/docs/plugins/overview)18 * **您的插件用户在 claude.ai 或 Cowork 中**：同一文件夹在那里安装，但组件子集不同。请参阅[插件结构和测试](https://claude.com/docs/plugins/build)和[组件支持表](https://claude.com/docs/plugins/platform-support#compare-component-support-by-app)

19</Note>19</Note>

20 20

21从与您已有内容相匹配的部分开始：21从与您已有内容相匹配的部分开始：

132 132

133插件仅在您使用 `--plugin-dir` 启动的会话中加载。要继续处理它而不使用该标志，或测试 `.zip` 构建，请参阅[在没有市场的情况下开发](#develop-without-a-marketplace)。133插件仅在您使用 `--plugin-dir` 启动的会话中加载。要继续处理它而不使用该标志，或测试 `.zip` 构建，请参阅[在没有市场的情况下开发](#develop-without-a-marketplace)。

134 134

135要让 Claude 为您搭建和检查更大的插件，请从 `claude-plugins-official` 市场[安装](/docs/zh-CN/plugins/install#install-a-plugin) Anthropic 的 `plugin-dev` 插件，它添加了用于编写技能、hooks 和 MCP 服务器等组件的技能和代理，以及用于验证完成的插件的技能和代理。安装后，运行 `/plugin-dev:create-plugin` 后跟您想要的插件的描述，Claude 将引导您完成设计、创建和验证。

136

135<h3 id="share-the-plugin">137<h3 id="share-the-plugin">

136 共享您的插件138 共享您的插件

137</h3>139</h3>

140 142

141* **直接发送给少数人**：给他们插件的目录或其 `.zip`，无需发布任何内容。请参阅[在没有市场的情况下共享插件](/docs/zh-CN/plugins/publish#share-a-plugin-without-a-marketplace)。143* **直接发送给少数人**：给他们插件的目录或其 `.zip`，无需发布任何内容。请参阅[在没有市场的情况下共享插件](/docs/zh-CN/plugins/publish#share-a-plugin-without-a-marketplace)。

142* **在您自己的市场中列出它**：团队成员添加您的市场一次并按名称安装插件，他们会收到您的更新。请参阅[通过您自己的市场发布](/docs/zh-CN/plugins/publish#publish-through-your-own-marketplace)。144* **在您自己的市场中列出它**：团队成员添加您的市场一次并按名称安装插件，他们会收到您的更新。请参阅[通过您自己的市场发布](/docs/zh-CN/plugins/publish#publish-through-your-own-marketplace)。

143* **提交到 Anthropic 的社区市场**：一旦列出，任何添加该市场的人都可以安装它。请参阅[提交到社区市场](/docs/zh-CN/plugins/publish#submit-to-the-community-marketplace)。145* **提交到 Anthropic 的目录**：通过审查后，人们可以在 claude.ai 和 Cowork 中添加它，它通过他们的账户到达 Claude Code。请参阅[提交到 Anthropic 的目录](/docs/zh-CN/plugins/publish#submit-to-anthropics-directory)。

144 146

145<h3 id="plugin-layout">147<h3 id="plugin-layout">

146 插件布局148 插件布局

201 203

202如果文件夹没有 `.claude-plugin/` 目录且其顶级没有插件组件，Claude Code 会将其视为插件文件夹。然后，每个具有 `.claude-plugin/plugin.json` 清单的直接子文件夹都作为单独的插件加载。文件夹中的所有其他内容都被跳过而不出错，包括没有清单的子文件夹。如果文件夹中的插件不加载，请检查其子文件夹是否具有 `.claude-plugin/plugin.json`。204如果文件夹没有 `.claude-plugin/` 目录且其顶级没有插件组件，Claude Code 会将其视为插件文件夹。然后，每个具有 `.claude-plugin/plugin.json` 清单的直接子文件夹都作为单独的插件加载。文件夹中的所有其他内容都被跳过而不出错，包括没有清单的子文件夹。如果文件夹中的插件不加载，请检查其子文件夹是否具有 `.claude-plugin/plugin.json`。

203 205

206您还可以传递一个在其插件文件夹旁边保留 `.claude-plugin/marketplace.json` 的文件夹。只要该 `.claude-plugin/` 目录不包含 `plugin.json`，插件文件夹仍然会加载。不会从市场文件安装或启用任何内容，因为 Claude Code 不读取它。从这样的文件夹加载插件需要 Claude Code v2.1.281 或更高版本。

207

204在交互式会话中，您还可以在启动后在文件夹中添加和删除插件：208在交互式会话中，您还可以在启动后在文件夹中添加和删除插件：

205 209

206* 您添加的子文件夹一旦其清单存在就作为新插件加载。210* 您添加的子文件夹一旦其清单存在就作为新插件加载。

417 421

418* [插件组件](/docs/zh-CN/plugins/components)：向您的插件添加代理、hooks、MCP 服务器、LSP 服务器和用户配置422* [插件组件](/docs/zh-CN/plugins/components)：向您的插件添加代理、hooks、MCP 服务器、LSP 服务器和用户配置

419* [使用 evals 测试插件](/docs/zh-CN/plugin-evals)：编写 eval 用例并使用 `claude plugin eval` 运行它们以检查插件引导 Claude 行为的可靠性423* [使用 evals 测试插件](/docs/zh-CN/plugin-evals)：编写 eval 用例并使用 `claude plugin eval` 运行它们以检查插件引导 Claude 行为的可靠性

420* [发布插件](/docs/zh-CN/plugins/publish)：对其进行版本控制，将其放在市场中，并提交到社区市场424* [发布插件](/docs/zh-CN/plugins/publish)：对其进行版本控制，将其放在市场中，并提交以供审查

421* [claude.ai 和 Cowork 中的插件](https://claude.com/docs/plugins/overview)：同一插件文件夹在 claude.ai 和 Cowork 中安装。某些组件仅限 Claude Code425* [插件结构和测试](https://claude.com/docs/plugins/build)：同一插件文件夹在 claude.ai 和 Cowork 中安装。某些组件仅限 Claude Code，[组件支持表](https://claude.com/docs/plugins/platform-support#compare-component-support-by-app)列出了在每个平台上加载的组件

422* [插件清单参考](/docs/zh-CN/plugins/manifest-reference)：每个 `plugin.json` 字段、路径规则和目录426* [插件清单参考](/docs/zh-CN/plugins/manifest-reference)：每个 `plugin.json` 字段、路径规则和目录

423* [技能](/docs/zh-CN/skills)：编写您的插件提供的技能427* [技能](/docs/zh-CN/skills)：编写您的插件提供的技能

424* [Anthropic 在 claude-code 存储库中的插件](https://github.com/anthropics/claude-code/tree/main/plugins)：本页面布局的完整工作示例，例如 `feature-dev` 和 `code-review`428* [Anthropic 在 claude-code 存储库中的插件](https://github.com/anthropics/claude-code/tree/main/plugins)：本页面布局的完整工作示例，例如 `feature-dev` 和 `code-review`

plugins/create-marketplace.md +1 −1

Details

14 这些情况在其他页面上有介绍：14 这些情况在其他页面上有介绍：

15 15

16 * **与少数人共享一个 plugin**：将 plugin 的目录或其 `.zip` 文件发送给他们。请参阅[不使用 marketplace 共享 plugin](/docs/zh-CN/plugins/publish#share-a-plugin-without-a-marketplace)。16 * **与少数人共享一个 plugin**：将 plugin 的目录或其 `.zip` 文件发送给他们。请参阅[不使用 marketplace 共享 plugin](/docs/zh-CN/plugins/publish#share-a-plugin-without-a-marketplace)。

17 * **向所有人提供一个 plugin**：将其提交到 Anthropic 的社区 marketplace。请参阅[提交到社区 marketplace](/docs/zh-CN/plugins/publish#submit-to-the-community-marketplace)。17 * **向所有人提供一个 plugin**：将其提交到 Anthropic 的社区 marketplace。请参阅[提交到社区 marketplace](/docs/zh-CN/plugins/publish#submit-to-anthropics-directory)。

18 * **自己使用一个 plugin**：使用 `--plugin-dir` 加载它或将其保存在你的 skills 目录中。请参阅[不使用 marketplace 开发](/docs/zh-CN/plugins/create#develop-without-a-marketplace)。18 * **自己使用一个 plugin**：使用 `--plugin-dir` 加载它或将其保存在你的 skills 目录中。请参阅[不使用 marketplace 开发](/docs/zh-CN/plugins/create#develop-without-a-marketplace)。

19</Note>19</Note>

20 20

plugins/host-marketplace.md +3 −3

Details

89组织同步对仓库的要求比 `/plugin marketplace add` 更严格：89组织同步对仓库的要求比 `/plugin marketplace add` 更严格：

90 90

91* **Marketplace 仓库**：在 github.com 和 gitlab.com 上，它必须是私有或内部的91* **Marketplace 仓库**：在 github.com 和 gitlab.com 上，它必须是私有或内部的

~~92* **插件源**：每个插件源必须是 `github`、`url` 或 `git-subdir` 类型，或以 `./` 开头的 [相对路径](/docs/zh-CN/plugins/marketplace-reference#relative-path-plugin-source)~~92* **插件源**：组织同步仅接受某些 [源类型](/docs/zh-CN/plugins/marketplace-reference#plugin-sources)

93* **顶级 `bin/` 目录**：claude.ai 拒绝具有一个的插件并同步 marketplace 的其余部分。错误消息以 `Plugin contains a top-level bin/ directory` 开头。将可执行文件保留在另一个目录中，如 `scripts/`，并从你的 hooks 或 MCP 服务器配置中将它们引用为 `${CLAUDE_PLUGIN_ROOT}/scripts/<name>`93* **顶级 `bin/` 目录**：claude.ai 拒绝具有一个的插件并同步 marketplace 的其余部分。错误消息以 `Plugin contains a top-level bin/ directory` 开头。将可执行文件保留在另一个目录中，如 `scripts/`，并从你的 hooks 或 MCP 服务器配置中将它们引用为 `${CLAUDE_PLUGIN_ROOT}/scripts/<name>`

94 94

~~95有关管理员工作流程，请参阅 [为你的组织管理插件](https://support.claude.com/en/articles/13837433)。~~95[从仓库同步你的组织的插件](https://claude.com/docs/plugins/org-sync) 在 claude.com 上列出了接受的源、GitLab 设置和 `bin/` 错误，[为你的组织管理插件](https://claude.com/docs/plugins/admin) 涵盖了管理员工作流程。

96 96

97<h2 id="grant-access-to-a-private-marketplace">97<h2 id="grant-access-to-a-private-marketplace">

98 授予对私有 marketplace 的访问权限98 授予对私有 marketplace 的访问权限

113 113

114对于 GitHub Enterprise Server 主机，用户需要从他们的机器访问该主机的 git 访问权限。有关每个 Claude Code 表面需要到达 GHES 托管的 marketplace 的内容，请参阅 [GHES 上的插件 marketplace](/docs/zh-CN/github-enterprise-server#plugin-marketplaces-on-ghes)。114对于 GitHub Enterprise Server 主机，用户需要从他们的机器访问该主机的 git 访问权限。有关每个 Claude Code 表面需要到达 GHES 托管的 marketplace 的内容，请参阅 [GHES 上的插件 marketplace](/docs/zh-CN/github-enterprise-server#plugin-marketplaces-on-ghes)。

115 115

116如果你改为通过 claude.ai 上的 **组织设置 > 插件和技能** 分发，你的用户的 git 凭证不涉及。有关哪些插件源可以在那里是私有的，请参阅 [通过组织设置分发](#distribute-through-organization-settings)。116如果你改为通过 claude.ai 上的 **组织设置 > 插件和技能** 分发，你的用户的 git 凭证不涉及。请参阅 [通过组织设置分发](#distribute-through-organization-settings)。

117 117

118<h3 id="serve-users-who-have-no-git-host-account">118<h3 id="serve-users-who-have-no-git-host-account">

119 为没有 git 主机账户的用户提供服务119 为没有 git 主机账户的用户提供服务

plugins/install.md +1 −1

Details

143插件的安装范围决定了谁获得该插件以及哪个设置文件将其记录为已启用：143插件的安装范围决定了谁获得该插件以及哪个设置文件将其记录为已启用：

144 144

145* **User scope**：该插件在此机器上的每个项目中为您启用。条目进入 `~/.claude/settings.json` 中的 `enabledPlugins`。145* **User scope**：该插件在此机器上的每个项目中为您启用。条目进入 `~/.claude/settings.json` 中的 `enabledPlugins`。

146* **Project scope**：该插件为在此存储库中工作的每个人启用。条目进入 `.claude/settings.json`，您提交它。146* **Project scope**：该插件为在此存储库中工作的每个人启用。条目进入 `.claude/settings.json`，您提交它。提交该条目会为您的协作者打开插件，但不会将其下载到他们的机器上，因此每个协作者也需要运行一次 `claude plugin install <name>@<marketplace> --scope project`；请参阅 [在项目设置中启用但未安装](/docs/zh-CN/plugins/loading#enabled-in-project-settings-but-not-installed)。

147* **Local scope**：该插件仅在此存储库中为您启用。条目进入 `.claude/settings.local.json`。147* **Local scope**：该插件仅在此存储库中为您启用。条目进入 `.claude/settings.local.json`。

148 148

149某些插件由其作者通过 [`defaultEnabled`](/docs/zh-CN/plugins/manifest-reference#defaultenabled) 字段设置为默认关闭。这样的插件已安装但保持关闭，直到您在 shell 中使用 `claude plugin enable <name>` 或从会话中 `/plugin` 的 **Installed** 选项卡打开它。149某些插件由其作者通过 [`defaultEnabled`](/docs/zh-CN/plugins/manifest-reference#defaultenabled) 字段设置为默认关闭。这样的插件已安装但保持关闭，直到您在 shell 中使用 `claude plugin enable <name>` 或从会话中 `/plugin` 的 **Installed** 选项卡打开它。

plugins/loading.md +2 −2

Details

100 100

101在终端会话中，同步插件的技能、代理、hooks、MCP 服务器和 LSP 服务器都加载，具有与您安装的市场插件相同的信任。101在终端会话中，同步插件的技能、代理、hooks、MCP 服务器和 LSP 服务器都加载，具有与您安装的市场插件相同的信任。

102 102

103有关 Cowork 加载的组件，请参阅 claude.com 上的[claude.ai 和 Cowork 中的插件](https://claude.com/docs/plugins/overview)。103有关 Cowork 加载的组件，请参阅 claude.com 上的[组件支持表](https://claude.com/docs/plugins/platform-support#compare-component-support-by-app)。

104 104

105同步插件在 Cowork 会话和您使用 claude.ai 账户登录的终端会话中加载：105同步插件在 Cowork 会话和您使用 claude.ai 账户登录的终端会话中加载：

106 106

184| 路径 | 它保存什么 |184| 路径 | 它保存什么 |

185| :- | :- |185| :- | :- |

186| `cache/<marketplace>/<plugin>/<version>/` | 市场插件的每个已安装版本一个目录。`<plugin>` 是市场条目名称，`<version>` 是[已解析版本](#versions-and-updates)。`${CLAUDE_PLUGIN_ROOT}` 指向此目录 |186| `cache/<marketplace>/<plugin>/<version>/` | 市场插件的每个已安装版本一个目录。`<plugin>` 是市场条目名称，`<version>` 是[已解析版本](#versions-and-updates)。`${CLAUDE_PLUGIN_ROOT}` 指向此目录 |

187| `data/<plugin-id>/` | 插件的持久目录，公开为 `${CLAUDE_PLUGIN_DATA}`。有关如何形成 `<plugin-id>`，请参阅[路径变量和持久数据](/docs/zh-CN/plugins/components#path-variables-and-persistent-data)。Claude Code 在插件组件首次使用它时创建它，并在更新中保留它。当您从其最后一个范围卸载插件时，Claude Code 删除它，除非您传递 `--keep-data` |187| `data/<plugin-id>/` | 插件的持久目录，公开为 `${CLAUDE_PLUGIN_DATA}`。有关如何形成 `<plugin-id>`，请参阅[路径变量和持久数据](/docs/zh-CN/plugins/components#path-variables-and-persistent-data)。Claude Code 在插件组件首次使用它时创建它，并在更新中保留它。默认情况下，当您从其最后一个范围卸载插件时，Claude Code 会删除它。有关 `--keep-data` 和它保留的其他情况，请参阅[插件卸载](/docs/zh-CN/plugins/cli-reference#plugin-uninstall) |

188| `marketplaces/<name>/` | 从 GitHub、另一个 Git 主机或 URL 添加的市场的克隆或下载。从本地 `file` 或 `directory` 源添加的市场在此处没有副本，其 `installLocation` 在 `known_marketplaces.json` 中是您给定的路径 |188| `marketplaces/<name>/` | 从 GitHub、另一个 Git 主机或 URL 添加的市场的克隆或下载。从本地 `file` 或 `directory` 源添加的市场在此处没有副本，其 `installLocation` 在 `known_marketplaces.json` 中是您给定的路径 |

plugins/manifest-reference.md +12 −3

Details

116* **`Validation passed with warnings`**：manifest 加载，但验证器发现需要修复的内容，例如 Claude Code 剥离的未知顶级字段、不是 kebab-case 的 `name`，或缺少 `version`、`description` 或 `author`。传递 `--strict` 以在 CI 中将警告转换为失败116* **`Validation passed with warnings`**：manifest 加载，但验证器发现需要修复的内容，例如 Claude Code 剥离的未知顶级字段、不是 kebab-case 的 `name`，或缺少 `version`、`description` 或 `author`。传递 `--strict` 以在 CI 中将警告转换为失败

117* **`Validation failed`**：manifest 有类型不匹配、缺失或逃逸 plugin 根目录的路径，或 `userConfig` 选项、`channels` 条目、`lspServers` 配置或 `monitors` 条目内的未知键。Claude Code 在加载 plugin 时报告相同的问题117* **`Validation failed`**：manifest 有类型不匹配、缺失或逃逸 plugin 根目录的路径，或 `userConfig` 选项、`channels` 条目、`lspServers` 配置或 `monitors` 条目内的未知键。Claude Code 在加载 plugin 时报告相同的问题

118 118

119该命令还检查 plugin 在 `.mcp.json` 中声明的每个 MCP 服务器条目、在 [`mcpServers`](#mcpservers) 命名的 `.json` 文件中，或在 `plugin.json` 中内联声明的条目。这些 MCP 检查需要 Claude Code v2.1.281 或更高版本，包括：

120

121* **错误**：Claude Code 在加载 plugin 时会丢弃的条目、对 manifest 未声明的选项的 `${user_config.KEY}` 引用，以及不是有效绝对 URL 的远程 `url`

122* **警告**：到非环回主机的 `http://` 或 `ws://` URL，以及看起来像字面凭证的标头值

123

119<h2 id="fields">124<h2 id="fields">

120 字段125 字段

121</h2>126</h2>

387 包含和存在392 包含和存在

388</h3>393</h3>

389 394

390每个组件路径必须在 plugin 根目录内解析并且必须存在。`claude plugin validate` 不检查 `outputStyles`、`lspServers`、`monitors` 或 `themes` 路径，因此这些字段中的坏路径仅在 plugin 加载时失败：395每个组件路径必须在 plugin 根目录内解析并且必须存在。`claude plugin validate` 检查每个组件键下的路径：

391 396

392* **包含**：在 plugin 根目录外解析的路径不加载，`/plugin` **Errors** 选项卡显示 `<component> path escapes plugin directory: <path>`。包含 `..` 的路径是常见情况，`claude plugin validate` 将其报告为 `Path contains ".." which could be a path traversal attempt`397* **包含**：在 plugin 根目录外解析的路径不加载，`/plugin` **Errors** 选项卡显示 `<component> path escapes plugin directory: <path>`。包含 `..` 的路径是常见情况，`claude plugin validate` 将其报告为 `Path contains ".." which could be a path traversal attempt`

393* **存在**：不存在的路径不加载，`/plugin` **Errors** 选项卡显示 `<component> path not found: <path>`。`claude plugin validate` 将其报告为 `Path not found`398* **存在**：不存在的路径不加载，`/plugin` **Errors** 选项卡显示 `<component> path not found: <path>`。`claude plugin validate` 将其报告为 `Path not found`

394 399

400对于 `outputStyles`、`lspServers`、`monitors` 和 `themes` 路径，`claude plugin validate` 检查需要 Claude Code v2.1.283 或更高版本。

401

395<h3 id="how-each-key-combines-with-its-default-location">402<h3 id="how-each-key-combines-with-its-default-location">

396 每个键如何与其默认位置结合403 每个键如何与其默认位置结合

397</h3>404</h3>

561 568

562`${CLAUDE_PLUGIN_ROOT}` 在 plugin 更新时改变，因此不要在那里写入状态。有关根目录移动的位置和旧目录何时被清理，参见[加载页面](/docs/zh-CN/plugins/loading)。569`${CLAUDE_PLUGIN_ROOT}` 在 plugin 更新时改变，因此不要在那里写入状态。有关根目录移动的位置和旧目录何时被清理，参见[加载页面](/docs/zh-CN/plugins/loading)。

563 570

564当您从最后一个安装它的地方卸载 plugin 时，`${CLAUDE_PLUGIN_DATA}` 目录被删除，除非您传递 [`--keep-data`](/docs/zh-CN/plugins/cli-reference)。571默认情况下，当您从最后一个安装它的地方卸载 plugin 时，Claude Code 会删除 `${CLAUDE_PLUGIN_DATA}` 目录。有关 `--keep-data` 和其他保留它的情况，参见 [plugin 卸载](/docs/zh-CN/plugins/cli-reference#plugin-uninstall)。

565 572

566<h3 id="where-each-variable-resolves">573<h3 id="where-each-variable-resolves">

567 每个变量解析的位置574 每个变量解析的位置

589* **Hook 命令**：使用[exec 形式](/docs/zh-CN/hooks#exec-form-and-shell-form)与 `args` 以便每个路径是一个没有引用的参数596* **Hook 命令**：使用[exec 形式](/docs/zh-CN/hooks#exec-form-and-shell-form)与 `args` 以便每个路径是一个没有引用的参数

590* **Shell 形式 hooks 和 monitor 命令**：用双引号包装变量，以便带空格的路径保持为一个单词597* **Shell 形式 hooks 和 monitor 命令**：用双引号包装变量，以便带空格的路径保持为一个单词

591 598

599如果您在 hooks 文件中的 shell 形式命令中将这些变量之一留在引号外，`claude plugin validate` 会发出警告，除非 hook 将 [`shell`](/docs/zh-CN/hooks#command-hook-fields) 设置为 `"powershell"`。

600

592此 shell 形式 hook 运行与 plugin 捆绑的脚本：601此 shell 形式 hook 运行与 plugin 捆绑的脚本：

593 602

594```json theme={null}603```json theme={null}

630| 主题 | `themes/` | 主题 JSON 文件 |639| 主题 | `themes/` | 主题 JSON 文件 |

632| 可执行文件 | `bin/` | 此处的文件在 plugin 启用时位于 Bash 工具的 `PATH` 上，因此 Claude 将它们作为裸命令运行。claude.ai 和 Cowork 不安装具有此目录的 plugin，包括您[通过 claude.ai 组织设置分发](/docs/zh-CN/plugins/host-marketplace#distribute-through-organization-settings)的 plugin |641| 可执行文件 | `bin/` | 此处的文件在 plugin 启用时位于 Bash 工具的 `PATH` 上，因此 Claude 将它们作为裸命令运行。claude.ai 和 Cowork 不安装具有此目录的 plugin，包括您[通过 claude.ai 组织设置分发](https://claude.com/docs/plugins/org-sync#keep-executables-out-of-the-top-level-bin-directory)的 plugin |

633| 设置 | `settings.json` | 在 plugin 启用时应用的 `agent` 和 `subagentStatusLine` 默认值 |642| 设置 | `settings.json` | 在 plugin 启用时应用的 `agent` 和 `subagentStatusLine` 默认值 |

634 643

635使用每个默认位置的 plugin，加上其 hooks 调用的 `scripts/` 文件夹，布局如下：644使用每个默认位置的 plugin，加上其 hooks 调用的 `scripts/` 文件夹，布局如下：

plugins/marketplace-reference.md +5 −3

Details

47* **官方 marketplace 名称**：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`life-sciences`、`knowledge-work-plugins`、`claude-for-legal`、`claude-for-financial-services`、`financial-services-plugins`、`first-party-plugins` 和 `claude-tag-plugins`。除非 marketplace 来自 `github.com/anthropics/` 下的 `github` 或 `git` [marketplace 源](#marketplace-sources)，否则保留。47* **官方 marketplace 名称**：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`life-sciences`、`knowledge-work-plugins`、`claude-for-legal`、`claude-for-financial-services`、`financial-services-plugins`、`first-party-plugins` 和 `claude-tag-plugins`。除非 marketplace 来自 `github.com/anthropics/` 下的 `github` 或 `git` [marketplace 源](#marketplace-sources)，否则保留。

48* **社区 marketplace 名称**：`claude-community`、`claude-plugins-community` 和 `healthcare`。保留规则与官方名称相同。48* **社区 marketplace 名称**：`claude-community`、`claude-plugins-community` 和 `healthcare`。保留规则与官方名称相同。

49* **插件目录名称**：`anthropic-plugin-directory` 和 `claude-plugin-directory`。保留规则与官方名称相同。49* **插件目录名称**：`anthropic-plugin-directory` 和 `claude-plugin-directory`。保留规则与官方名称相同。

50* **冒充官方 marketplace 的名称**：名称如 `official-claude-plugins` 或 `claude-plugins-v2`，以及任何包含非 ASCII 字符的名称。错误是 `Marketplace name impersonates an official Anthropic/Claude marketplace`。名称中的控制或双向格式化字符也会报告 `Marketplace name cannot contain control or bidirectional-formatting characters`。50* **冒充官方 marketplace 的名称**：名称如 `official-claude-plugins` 或 `claude-plugins-v2`，以及任何包含非 ASCII 字符的名称。错误是 `Marketplace name impersonates an official Anthropic/Claude marketplace`。名称中的控制或双向格式化字符也会报告 `Marketplace name cannot contain control or bidirectional-formatting characters`。已在这样的名称下注册的 marketplace 停止加载，连同其插件。

51* <span id="reserved-name-spellings" />**保留名称的另一种拼写**：与保留名称仅在尾部点或用除下划线以外的符号代替连字符的名称，因此 `claude.code.plugins` 计为 `claude-code-plugins`。`claude plugin validate` 接受这样的名称；添加 marketplace 失败，错误为 [`is another spelling of "<reserved>", a reserved marketplace name`](/docs/zh-CN/errors#marketplace-name-is-another-spelling-of-a-reserved-name)，已在一个下注册的 marketplace 停止加载。此检查需要 Claude Code v2.1.280 或更高版本。51* <span id="reserved-name-spellings" />**保留名称的另一种拼写**：与保留名称仅在尾部点或用除下划线以外的符号代替连字符的名称，因此 `claude.code.plugins` 计为 `claude-code-plugins`。`claude plugin validate` 接受这样的名称；添加 marketplace 失败，错误为 [`is another spelling of "<reserved>", a reserved marketplace name`](/docs/zh-CN/errors#marketplace-name-is-another-spelling-of-a-reserved-name)，已在一个下注册的 marketplace 停止加载。此检查需要 Claude Code v2.1.280 或更高版本。

52* **Claude Code 用于不来自 marketplace 的插件的名称**：`inline` 用于使用 [`--plugin-dir`](/docs/zh-CN/cli-reference) 加载的插件，`builtin` 用于内置插件，`skills-dir` 用于从 [`.claude/skills/`](/docs/zh-CN/skills) 自动加载的插件，`synced` 用于从你的 claude.ai 账户同步的插件。`claude-plugin-test` 也被保留。`skills-dir` 也显示为 `{"source": "skills-dir"}`，在 `strictKnownMarketplaces` 和 `blockedMarketplaces` 中，如 [仅在策略列表中有效的源值](#source-values-valid-only-in-policy-lists) 下所述。52* **Claude Code 用于不来自 marketplace 的插件的名称**：`inline` 用于使用 [`--plugin-dir`](/docs/zh-CN/cli-reference) 加载的插件，`builtin` 用于内置插件，`skills-dir` 用于从 [`.claude/skills/`](/docs/zh-CN/skills) 自动加载的插件，`synced` 用于从你的 claude.ai 账户同步的插件。`claude-plugin-test` 也被保留。`skills-dir` 也显示为 `{"source": "skills-dir"}`，在 `strictKnownMarketplaces` 和 `blockedMarketplaces` 中，如 [仅在策略列表中有效的源值](#source-values-valid-only-in-policy-lists) 下所述。

53* **`npm`、`pip`、`uv`、`cargo`、`github` 和 `gh`**：以任何大小写保留。此检查需要 Claude Code v2.1.275 或更高版本。53* **`npm`、`pip`、`uv`、`cargo`、`github` 和 `gh`**：以任何大小写保留。此检查需要 Claude Code v2.1.275 或更高版本。

54* **以 `claudeai-` 开头的名称**：为托管在 claude.ai 上的 marketplace 保留。`claude plugin marketplace add` 拒绝任何其他使用一个的 marketplace，错误为 `Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai`。54* **以 `claudeai-` 开头的名称**：为托管在 claude.ai 上的 marketplace 保留。`claude plugin marketplace add` 拒绝任何其他使用一个的 marketplace，错误为 `Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai`。

55 55

56当已注册的 marketplace 因其名称模仿官方名称而停止加载时，`claude plugin list` 和 `/plugin` 报告 `Claude Code refuses the marketplace name "<name>"`。该消息告诉你删除该 marketplace。删除它也会卸载其插件并删除其保存的数据。此命名拒绝消息需要 Claude Code v2.1.282 或更高版本。

56<h2 id="top-level-fields">58<h2 id="top-level-fields">

57 顶级字段59 顶级字段

58</h2>60</h2>

149 151

150| 类型 | 字段 | 说明 |152| 类型 | 字段 | 说明 |

151| :- | :- | :- |153| :- | :- | :- |

154| `url` | `url`, `ref`, `sha` | 任何 git 仓库的 URL |156| `url` | `url`, `ref`, `sha` | 任何 git 仓库的 URL |

510 512

511`source` 上的 `Invalid input` 意味着该对象与任何源类型都不匹配。检查这些原因：513`source` 上的 `Invalid input` 意味着该对象与任何源类型都不匹配。检查这些原因：

512 514

513* 不以 `./` 开头的相对路径，除了 `"."` 或 `metadata.pluginRoot` 下的裸名称515* 不以 `./` 开头的相对路径，除了 `"."` 或 [`metadata.pluginRoot` 下的裸名称](#relative-path-plugin-source)

514* 包含 `..` 的 `npm` `package`516* 包含 `..` 的 `npm` `package`

515* 不是 [plugin sources](#plugin-sources) 之一的 `source` 类型517* 不是 [plugin sources](#plugin-sources) 之一的 `source` 类型

516* 已知类型缺少必需字段或字段类型错误，例如没有 `repo` 的 `github`518* 已知类型缺少必需字段或字段类型错误，例如没有 `repo` 的 `github`

plugins/measure.md +2 −0

Details

96* **他们是你可以询问的队友**：每个用户自己的 Claude Code 在四个地方向他们显示他们是否仍在使用插件：[`/plugin` 面板](#not-used-recently-in-/plugin)、[`/skill-doctor`](#find-skills-that-never-run)、[`/doctor`](#unused-plugins-in-/doctor)和[`/usage`](#usage-share-in-/usage)。所有四个都是用户在自己机器上的会话中在 Claude Code 提示符处运行的命令。96* **他们是你可以询问的队友**：每个用户自己的 Claude Code 在四个地方向他们显示他们是否仍在使用插件：[`/plugin` 面板](#not-used-recently-in-/plugin)、[`/skill-doctor`](#find-skills-that-never-run)、[`/doctor`](#unused-plugins-in-/doctor)和[`/usage`](#usage-share-in-/usage)。所有四个都是用户在自己机器上的会话中在 Claude Code 提示符处运行的命令。

97* **都不是**：你没有来自 Claude Code 的该插件的使用信号。97* **都不是**：你没有来自 Claude Code 的该插件的使用信号。

98 98

99有关 Anthropic 目录中列出的插件的使用情况，请参阅 claude.com 上的[跟踪已发布的插件使用情况](https://claude.com/docs/connectors/building/after-publishing#track-published-plugin-usage)。

100

99<h3 id="not-used-recently-in-/plugin">101<h3 id="not-used-recently-in-/plugin">

100 `/plugin` 中最近未使用102 `/plugin` 中最近未使用

101</h3>103</h3>

plugins/org.md +2 −1

Details

14 这些情况在其他页面上有介绍：14 这些情况在其他页面上有介绍：

15 15

16 * **为自己安装 plugins**：从[安装 plugins](/docs/zh-CN/plugins/install)开始16 * **为自己安装 plugins**：从[安装 plugins](/docs/zh-CN/plugins/install)开始

~~17 * **控制成员在 claude.ai 和 Cowork 中可以使用的 plugins**：请参阅帮助中心中的[为您的组织管理 plugins](https://support.claude.com/en/articles/13837433)~~17 * **控制成员在 claude.ai 和 Cowork 中可以使用的 plugins**：请参阅 claude.com 上的[为您的组织管理 plugins](https://claude.com/docs/plugins/admin)

18 * **将一个 plugin 同时推出到 claude.ai、Cowork 和 Claude Code**：请参阅 claude.com 上的[选择推出路线](https://claude.com/docs/plugins/org-rollout#choose-a-rollout-route)

18 * **claude.ai 管理员设置中的 plugins 页面**：[**组织设置 > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory)为成员的 claude.ai 账户启用 plugins，这些会作为[同步的 plugins](/docs/zh-CN/plugins/loading#synced-plugins)到达 Claude Code。它不设置此页面上的任何键19 * **claude.ai 管理员设置中的 plugins 页面**：[**组织设置 > Plugins & skills**](https://claude.ai/admin-settings/skills?tab=inventory)为成员的 claude.ai 账户启用 plugins，这些会作为[同步的 plugins](/docs/zh-CN/plugins/loading#synced-plugins)到达 Claude Code。它不设置此页面上的任何键

19</Note>20</Note>

20 21

plugins/overview.md +7 −4

Details

6 6

7> 了解什么是 Claude Code 插件，何时需要使用插件而不是独立的 skill 或 MCP 服务器，以及应该阅读哪个页面来安装或创建插件。7> 了解什么是 Claude Code 插件，何时需要使用插件而不是独立的 skill 或 MCP 服务器，以及应该阅读哪个页面来安装或创建插件。

8 8

9Claude Code 插件是一个目录，包含 skills、agents、hooks、MCP 服务器或其他组件，Claude Code 将其作为一个单元安装和加载。大多数插件来自市场，市场是一个列出插件及其获取位置的目录。您也可以从某人提供给您的文件夹加载插件，或者[构建您自己的插件](/docs/zh-CN/plugins/create)。9Claude Code 插件是一个目录，包含 skills、agents、hooks、MCP 服务器或其他组件，Claude Code 将其作为一个单元进行安装和加载。大多数插件来自市场，市场是一个目录，列出了插件及其获取位置。您也可以从某人提供给您的文件夹中加载插件，或者[构建您自己的插件](/docs/zh-CN/plugins/create)。

10 10

11<Note>11<Note>

~~12 如果您使用 claude.ai 聊天或 Cowork 而不是 Claude Code，请参阅 [claude.ai 和 Cowork 中的插件](https://claude.com/docs/plugins/overview)。~~12 如果以下任一情况适用于您，请改为在 claude.com 上开始：

14 * **您使用 claude.ai 聊天或 Cowork，而不是 Claude Code**：请参阅 [claude.ai 和 Cowork 中的插件](https://claude.com/docs/plugins/overview)

15 * **您构建了 MCP 服务器并希望将其添加到 Anthropic 的目录中**：请参阅[发布到目录](https://claude.com/docs/directory/publish)

13</Note>16</Note>

14 17

15要立即尝试插件，请在 Claude Code 终端会话中运行 `/plugin`，并从**发现**选项卡安装一个插件，该选项卡列出了来自 Anthropic 官方市场和您添加的任何市场的插件。从那里：18要立即尝试插件，请在 Claude Code 终端会话中运行 `/plugin`，并从**发现**选项卡安装一个插件，该选项卡列出了来自 Anthropic 官方市场和您添加的任何市场的插件。从那里：

122云会话（包括浏览器中 claude.ai/code 中的会话）不加载本地设置中的插件。有关终端、VS Code 和桌面应用中的安装步骤，以及云会话加载的内容，请参阅[安装插件](/docs/zh-CN/plugins/install#install-a-plugin)。125云会话（包括浏览器中 claude.ai/code 中的会话）不加载本地设置中的插件。有关终端、VS Code 和桌面应用中的安装步骤，以及云会话加载的内容，请参阅[安装插件](/docs/zh-CN/plugins/install#install-a-plugin)。

123 126

124<Note>127<Note>

125 相同的插件格式也在 claude.ai 和 Cowork 上安装，其中加载了不同的组件集。对于这些界面，请参阅 claude.com 上的 [claude.ai 和 Cowork 中的插件](https://claude.com/docs/plugins/overview)。128 相同的插件格式也在 claude.ai 和 Cowork 上安装，其中加载了不同的组件集。对于这些界面，请参阅 claude.com 上的 [claude.ai 和 Cowork 中的插件](https://claude.com/docs/plugins/overview) 及其[按应用比较组件支持表](https://claude.com/docs/plugins/platform-support#compare-component-support-by-app)。

126</Note>129</Note>

127 130

128<h2 id="next-steps">131<h2 id="next-steps">

135 138

136安装或构建插件后，这些页面涵盖接下来的内容：139安装或构建插件后，这些页面涵盖接下来的内容：

137 140

138* **分享您构建的内容**：[发布和分发插件](/docs/zh-CN/plugins/publish)141* **分享您构建的内容**：[发布和分发插件](/docs/zh-CN/plugins/publish)，通过您自己的市场或 [Anthropic 的目录](/docs/zh-CN/plugins/publish#submit-to-anthropics-directory)

139* **检查它是否有效和被使用**：[使用 evals 测试插件](/docs/zh-CN/plugin-evals)和[测量插件成本和使用情况](/docs/zh-CN/plugins/measure)142* **检查它是否有效和被使用**：[使用 evals 测试插件](/docs/zh-CN/plugin-evals)和[测量插件成本和使用情况](/docs/zh-CN/plugins/measure)

140* **为您的团队运行市场**：[创建市场](/docs/zh-CN/plugins/create-marketplace)，然后[托管和维护市场](/docs/zh-CN/plugins/host-marketplace)143* **为您的团队运行市场**：[创建市场](/docs/zh-CN/plugins/create-marketplace)，然后[托管和维护市场](/docs/zh-CN/plugins/host-marketplace)

141* **为组织设置插件策略**：[为您的组织管理插件](/docs/zh-CN/plugins/org)144* **为组织设置插件策略**：[为您的组织管理插件](/docs/zh-CN/plugins/org)

plugins/publish.md +21 −18

Details

4 4

5# 发布和分发插件5# 发布和分发插件

6 6

~~7> 通过您自己的市场或 Anthropic 的社区市场发布 Claude Code 插件，包括发布前检查清单以及用户如何获取更新。~~7> 通过您自己的市场或 Anthropic 的目录发布 Claude Code 插件，包括发布前检查清单以及用户如何获取更新。

8 8

9发布 Claude Code 插件意味着在市场中列出它，市场是一个 JSON 目录，列出插件及其获取位置，这样其他人可以按名称安装它并接收您的更新。您可以运行自己的市场或将您的插件提交到 Anthropic 的社区市场。要在不发布的情况下共享插件，请将插件的目录或其 `.zip` 发送给人们以供他们自己加载。9发布 Claude Code 插件意味着在市场中列出它，市场是一个 JSON 目录，列出插件及其获取位置，这样其他人可以按名称安装它并接收您的更新。您可以运行自己的市场或将您的插件提交到 Anthropic 的目录。要在不发布的情况下共享插件，请将插件的目录或其 `.zip` 发送给人们以供他们自己加载。

10 10

11本页面适用于已准备好共享的工作插件的作者。11本页面适用于已准备好共享的工作插件的作者。

12 12

29| :- | :- | :- | :- |29| :- | :- | :- | :- |

33 33

34自动更新是用户端的每个市场设置，在后台获取新版本。34自动更新是用户端的每个市场设置，在后台获取新版本。

35 35

141 141

142[安装插件](/docs/zh-CN/plugins/install)涵盖用户端命令，[自动更新何时运行](/docs/zh-CN/plugins/loading#when-auto-update-runs)涵盖时间。142[安装插件](/docs/zh-CN/plugins/install)涵盖用户端命令，[自动更新何时运行](/docs/zh-CN/plugins/loading#when-auto-update-runs)涵盖时间。

143 143

144<h2 id="submit-to-the-community-marketplace">144<h2 id="submit-to-anthropics-directory">

145 提交到社区市场145 提交到 Anthropic 的目录

146</h2>146</h2>

147 147

148Anthropic 的社区市场 `claude-community` 是列出通过插件目录提交表单提交的插件的公共市场。148Anthropic 的目录是人们在 claude.ai 和 Cowork 中浏览以添加插件和连接器的目录。在那里的一个列表可以覆盖 claude.ai、Cowork 和 Claude Code 上的用户。您可以从开发者门户 [claude.ai/directory/manage](https://claude.ai/directory/manage) 提交；claude.com 上的 [Prepare for review](https://claude.com/docs/directory/publish#prepare-for-review) 描述了每个版本在发布前会发生什么。

149 149

150用户在 Claude Code 会话中使用 `/plugin marketplace add anthropics/claude-plugins-community` 添加社区市场，并从中安装为 `@claude-community`。150提交需要付费的 claude.ai 计划。在 Pro 和 Max 上，您可以从自己的账户提交。在 Team 和 Enterprise 上，Owner 可以提交，在 Enterprise 上，Owner 还可以通过 **Organization settings > Roles** 下的自定义角色向其他成员授予 **Directory** 权限。请参阅 [Confirm you can submit to the directory](https://claude.com/docs/directory/publish#confirm-you-can-submit-to-the-directory)。

151 151

152关于社区市场与官方市场的区别，请参阅 [Anthropic 的市场](/docs/zh-CN/plugins/anthropic-marketplaces)。152提交步骤、每个版本必须通过的检查以及发布后会发生什么都记录在 claude.com 上，因为无论您的用户在哪个平台上，这些都是相同的：

153 153

154要将您的插件提交到社区市场，请使用以下应用内表单之一：154* [Publish to the directory](https://claude.com/docs/directory/publish#before-you-submit-to-the-directory)：您可以提交什么以及谁可以提交

155* [Submit a plugin](https://claude.com/docs/plugins/submit#submit-a-plugin)：门户步骤和 [updating a published plugin](https://claude.com/docs/plugins/submit#update-a-published-plugin)

156* [Plugin pre-submission checklist](https://claude.com/docs/plugins/pre-submission-checklist#run-the-checks-before-you-submit)：提交前要运行和修复的检查

157* [Move an earlier submission to the developer portal](https://claude.com/docs/directory/publish#move-an-earlier-submission-to-the-developer-portal)：如果您通过早期提交表单之一提交了插件（在门户存在之前），该怎么办

155 158

156* **claude.ai**：[claude.ai/admin-settings/directory/submissions/plugins/new](https://claude.ai/admin-settings/directory/submissions/plugins/new)159在打开门户之前，在本地验证并检查您的哪些组件在 Claude Code 之外加载：

157* **Console**：[platform.claude.com/plugins/submit](https://platform.claude.com/plugins/submit)

158 160

159claude.ai 表单需要 Team 或 Enterprise 组织以及目录权限，Owners 默认持有该权限。不属于 Team 或 Enterprise 组织的个人作者可以改用 Console 表单。161* **在您的 shell 中运行 `claude plugin validate ./your-plugin --strict`**：用您的插件目录的路径替换 `./your-plugin`。该命令在本地捕获清单错误；[plugin validate](/docs/zh-CN/plugins/cli-reference#plugin-validate) 列出了每次运行读取的文件。门户应用了 CLI 不检查的额外目录规则，因此本地运行清晰并不保证门户验证清晰。

162* **检查在哪里加载**：某些插件组件仅限 Claude Code，不在 claude.ai 或 Cowork 中加载。[component support table](https://claude.com/docs/plugins/platform-support#compare-component-support-by-app) 按应用列出了每个组件，因此您知道 Claude Code 之外的用户会获得什么。

160 163

161在您的 shell 中，在提交前本地运行 `claude plugin validate ./your-plugin`，用您的插件目录的路径替换 `./your-plugin`。当验证通过时，Claude Code 打印 `✔ Validation passed`，或如果有警告则打印 `✔ Validation passed with warnings`。警告不会使验证失败；添加 `--strict` 以将它们视为错误。164Anthropic 的官方市场 `claude-plugins-official` 不通过目录门户接受提交。如果您与 Anthropic 合作伙伴联系合作，请询问他们关于官方市场列表的信息。

162 165

163列出的插件出现在 [`anthropics/claude-plugins-community`](https://github.com/anthropics/claude-plugins-community) 目录中，在几乎所有情况下都固定到特定的提交 SHA。166<h3 id="how-a-listed-plugin-reaches-claude-code-users">

~~164~~ 167 列出的插件如何到达 Claude Code 用户

165提交和您的插件出现在 `marketplace.json` 中之间可能会有延迟。要检查您的插件是否可安装，请在[社区目录](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/marketplace.json)中搜索其名称。168</h3>

166 169

167官方市场 `claude-plugins-official` 不通过这些表单接受提交。如果您与 Anthropic 合作伙伴联系合作，请询问他们关于官方市场列表的信息。170在 claude.ai 上从目录安装您的插件的人在他们的账户上拥有它，Claude Code 将其加载为 `<name>@synced`。[Plugins synced from claude.ai](/docs/zh-CN/plugins/loading#synced-plugins) 涵盖了他们看到的内容以及他们如何关闭它。

168 171

169<h2 id="ship-updates-renames-and-removals">172<h2 id="ship-updates-renames-and-removals">

170 发布更新、重命名和删除173 发布更新、重命名和删除

174 发布新版本177 发布新版本

175</h3>178</h3>

176 179

177如果您通过您自己的市场发布，并且您的 `plugin.json` 设置了 `version`，请增加它并推送。运行 `claude plugin update` 或启用自动更新的用户然后接收新版本，如[向用户发布更新](#ship-updates-to-users)下所述。180如果您通过您自己的市场发布，并且您的 `plugin.json` 设置了 `version`，请增加它并推送。运行 `claude plugin update` 或启用自动更新的用户然后接收新版本，如[向用户发布更新](#ship-updates-to-users)下所述。对于目录列表，请参阅[更新已发布的插件](https://claude.com/docs/plugins/submit#update-a-published-plugin)。

178 181

179<h3 id="tag-a-release">182<h3 id="tag-a-release">

180 标记发布183 标记发布

plugins/security.md +1 −1

Details

118 118

119在您的 shell 中，使用您安装它的 `--scope` 运行 [`claude plugin uninstall <plugin>`](/docs/zh-CN/plugins/cli-reference#plugin-uninstall)。然后检查卸载删除了什么以及留下了什么：119在您的 shell 中，使用您安装它的 `--scope` 运行 [`claude plugin uninstall <plugin>`](/docs/zh-CN/plugins/cli-reference#plugin-uninstall)。然后检查卸载删除了什么以及留下了什么：

120 120

121* **持久数据**：当这是插件安装的最后一个范围时，卸载也会删除插件的持久数据目录，除非您传递 `--keep-data`。121* **持久数据**：默认情况下，当这是插件安装的最后一个范围时，卸载也会删除插件的持久数据目录。对于 `--keep-data` 和其他保留数据的情况，请参阅 [plugin uninstall](/docs/zh-CN/plugins/cli-reference#plugin-uninstall)。

122* **缓存文件**：插件的文件在 `~/.claude/plugins/cache/` 下保留在磁盘上 14 天，然后[后台扫描将其删除](/docs/zh-CN/plugins/loading#cleanup-of-previous-versions)。卸载最后一个插件后，孤立目录保留到您安装另一个。要立即删除文件，请自己删除 `~/.claude/plugins/cache/<marketplace>/<plugin>/` 下的插件目录。122* **缓存文件**：插件的文件在 `~/.claude/plugins/cache/` 下保留在磁盘上 14 天，然后[后台扫描将其删除](/docs/zh-CN/plugins/loading#cleanup-of-previous-versions)。卸载最后一个插件后，孤立目录保留到您安装另一个。要立即删除文件，请自己删除 `~/.claude/plugins/cache/<marketplace>/<plugin>/` 下的插件目录。

123* **市场**：如果您也不信任市场的所有者，[也删除市场](/docs/zh-CN/plugins/install#manage-marketplaces)，这会卸载您从它安装的每个插件。123* **市场**：如果您也不信任市场的所有者，[也删除市场](/docs/zh-CN/plugins/install#manage-marketplaces)，这会卸载您从它安装的每个插件。

124 124

plugins/troubleshooting.md +11 −1

Details

676 `Failed to load hooks from <path>` 和不触发的 hooks676 `Failed to load hooks from <path>` 和不触发的 hooks

677</h3>677</h3>

678 678

679插件的 hooks 不运行。要么 **Errors** 选项卡显示它们的加载失败，hooks 加载且您在成绩单中看到 `<Event> hook error` 通知，要么 hook 加载无错误且永远不触发。679插件的 hooks 不运行，或一个阻止了一个操作。要么 **Errors** 选项卡显示它们的加载失败，hooks 加载且您在成绩单中看到 `<Event> hook error` 通知或阻止错误，要么 hook 加载无错误且永远不触发。

680 680

681<h4 id="hooks-fail-to-load">681<h4 id="hooks-fail-to-load">

682 Hooks 无法加载682 Hooks 无法加载

693 693

694形式为 `... hook error: Failed with non-blocking status code: <stderr>` 的通知意味着 hook 运行且其命令失败。例如，`Stop hook error: Failed with non-blocking status code: /bin/sh: node: command not found` 意味着 Claude Code 生成的 shell 找不到 `node`。安装它，或确保它在您启动 `claude` 的终端的 `PATH` 上。694形式为 `... hook error: Failed with non-blocking status code: <stderr>` 的通知意味着 hook 运行且其命令失败。例如，`Stop hook error: Failed with non-blocking status code: /bin/sh: node: command not found` 意味着 Claude Code 生成的 shell 找不到 `node`。安装它，或确保它在您启动 `claude` 的终端的 `PATH` 上。

695 695

696如果 stderr 显示插件的路径在空格处被截断，hook 的 shell 形式命令在引号外使用 `${CLAUDE_PLUGIN_ROOT}`，安装路径包含空格。将变量用双引号包装或使用 [exec 形式](/docs/zh-CN/hooks#exec-form-and-shell-form)。要找到未引用的变量，请在插件的目录上运行 `claude plugin validate` 并查找其 [引用警告](/docs/zh-CN/plugins/manifest-reference#quoting-and-path-separators)。

697

696对于任何其他错误，从插件目录自己运行 hook 的命令以查看完整输出，或使用 [调试日志](/docs/zh-CN/hooks#debug-hooks) 捕获完整 stderr。698对于任何其他错误，从插件目录自己运行 hook 的命令以查看完整输出，或使用 [调试日志](/docs/zh-CN/hooks#debug-hooks) 捕获完整 stderr。

697 699

700<h4 id="a-plugin-hook-blocks-a-tool-call-or-prompt">

701 插件 hook 阻止工具调用或提示

702</h4>

703

704退出代码为 2 的 hook [阻止它运行的操作](/docs/zh-CN/hooks#exit-code-2)。当插件的 hook 以这种方式阻止且其 stderr 是阻止消息时，错误以 `This hook comes from the <plugin> plugin.` 结尾，以便您知道要禁用或修复哪个插件。在 v2.1.281 之前，错误没有命名插件。

705

706如果该消息显示插件的路径在空格处被截断，应用 [未引用的 `${CLAUDE_PLUGIN_ROOT}` 修复](#hook-error-notices-in-the-transcript)。

707

698<h4 id="hook-loads-but-never-fires">708<h4 id="hook-loads-but-never-fires">

699 Hook 加载但永远不触发709 Hook 加载但永远不触发

700</h4>710</h4>

prompt-caching.md +55 −43

Details

37两个设置不在层表中出现，但仍然影响缓存的内容：37两个设置不在层表中出现，但仍然影响缓存的内容：

38 38

39* **Model**：每个模型都有自己的缓存。切换模型会重新计算整个请求，即使内容相同。请参阅下面的 [Switching models](#switching-models)。39* **Model**：每个模型都有自己的缓存。切换模型会重新计算整个请求，即使内容相同。请参阅下面的 [Switching models](#switching-models)。

40* **Effort level**：在大多数模型上，每个努力级别都有自己的缓存，因此在会话中途更改努力级别会重新计算整个请求。在具有 API 密钥或 Claude 订阅的 Opus 5.5 和 Fable 5.1 上，缓存默认保持完整。请参阅下面的 [Changing effort level](#changing-effort-level)。40* **Effort level**：在大多数模型上，每个努力级别都有自己的缓存，因此在会话中途更改努力级别会重新计算整个请求。在具有 API 密钥或 Claude 订阅的 Opus 5.5、Sonnet 5.5 和 Fable 5.1 上，缓存默认保持完整。请参阅下面的 [Changing effort level](#changing-effort-level)。

41 41

42<Tip>42<Tip>

43 在会话顶部选择你的模型和努力级别，然后在任务之间的自然中断处保存 `/compact`。你在任务中途进行的更改越少，缓存命中率就越高。43 在会话顶部选择你的模型和努力级别，然后在任务之间的自然中断处保存 `/compact`。你在任务中途进行的更改越少，缓存命中率就越高。

70 使缓存失效的操作70 使缓存失效的操作

71</h2>71</h2>

72 72

73这些操作会导致下一个请求缓存未命中的部分或全部。您会看到一次速度较慢、成本更高的回合，之后新的前缀会被缓存。一旦您了解它们的成本，大多数操作都可以在任务中途避免。模型切换可能看起来没有成本，直到您注意到随后的速度较慢的回合。73这些操作可能导致下一个请求缓存未命中。您会看到一次速度较慢、成本更高的回合，之后新的前缀会被缓存。一旦您了解它们的成本，大多数操作都可以在任务中途避免。模型切换可能看起来没有成本，直到您注意到随后的速度较慢的回合。

74 74

75* [切换模型](#switching-models)75* [切换模型](#switching-models)

76* [更改工作量级别](#changing-effort-level)76* [更改工作量级别](#changing-effort-level)

77* [启用快速模式](#turning-on-fast-mode)77* [启用快速模式](#turning-on-fast-mode)

~~78* [连接或断开 MCP 服务器](#connecting-or-disconnecting-an-mcp-server)~~78* [连接或移除 MCP 服务器](#connecting-or-removing-an-mcp-server)

79* [启用或禁用插件](#enabling-or-disabling-a-plugin)79* [启用或禁用插件](#enabling-or-disabling-a-plugin)

80* [拒绝整个工具](#denying-an-entire-tool)80* [拒绝整个工具](#denying-an-entire-tool)

81* [压缩对话](#compacting-the-conversation)81* [压缩对话](#compacting-the-conversation)

88 88

89每个模型都有自己的缓存。使用 [`/model`](/docs/zh-CN/model-config#setting-your-model) 切换意味着下一个请求会读取整个对话历史记录而没有缓存命中，即使内容相同。89每个模型都有自己的缓存。使用 [`/model`](/docs/zh-CN/model-config#setting-your-model) 切换意味着下一个请求会读取整个对话历史记录而没有缓存命中，即使内容相同。

90 90

91当您在终端运行 `/model` 时，Claude Code 仅在缓存仍然温暖且新模型不是产生最后一个响应的模型时要求您确认切换。缓存在 Claude Code 在此对话中最后一次发送请求或 Claude 最后一次响应后的一个[缓存 TTL](#cache-lifetime) 内保持温暖。一旦该时间过去，缓存就会过期，因此 Claude Code 会在不询问的情况下进行切换。91当您在终端运行 `/model` 时，Claude Code 会要求您确认切换，但仅限于缓存仍然温暖且新模型不是产生最后一个响应的模型时。缓存在 Claude Code 在此对话中最后一次发送请求或 Claude 最后一次响应后的一个[缓存 TTL](#cache-lifetime) 内保持温暖。一旦该时间过去，缓存就会过期，因此 Claude Code 会在不询问的情况下进行切换。

92 92

~~93在 v2.1.238 之前，Claude Code 没有检查缓存 TTL，即使在缓存过期后也会询问。~~93在 v2.1.238 之前，Claude Code 不检查缓存 TTL，即使在缓存过期后也会询问。

94 94

~~95您也可以使用 [PreModelSwitch hook](/docs/zh-CN/hooks#premodelswitch-decision-control) 要求此确认或跳过它。~~95您也可以通过 [PreModelSwitch hook](/docs/zh-CN/hooks#premodelswitch-decision-control) 要求此确认或跳过它。

96 96

97[`opusplan` 模型设置](/docs/zh-CN/model-config#opusplan-model-setting)在计划模式下解析为 Opus，在执行期间解析为 Sonnet，因此每个计划模式切换都是一个模型切换并启动新的缓存。97[`opusplan` 模型设置](/docs/zh-CN/model-config#opusplan-model-setting)在计划模式下解析为 Opus，在执行期间解析为 Sonnet，因此每个计划模式切换都是一个模型切换并启动新的缓存。

98 98

99[自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)在 Fable 模型、Opus 5.5 和 Opus 5 上也是一个模型切换。当安全分类器在具有回退模型的类别中标记请求时，Claude Code 会在该模型上重新运行请求，会话会在那里继续。99[Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 上的自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)也是一个模型切换。当安全分类器在具有回退模型的类别中标记请求时，Claude Code 会在该模型上重新运行请求，会话继续进行。

100 100

101当技能或命令的 frontmatter 命名一个[`model`](/docs/zh-CN/skills#frontmatter-reference)不同于会话当前模型的模型时，该回合也是一个模型切换：下一个请求会读取整个对话历史记录而没有缓存命中。会话模型在您的下一个提示时恢复。`context: fork` 技能会设置[分叉子代理的模型](/docs/zh-CN/skills#run-skills-in-a-subagent)。101当技能或命令的 frontmatter 命名一个[`model`](/docs/zh-CN/skills#frontmatter-reference)不同于会话当前模型的模型时，该回合也是一个模型切换：下一个请求读取整个对话历史记录而没有缓存命中。会话模型在您的下一个提示时恢复。`context: fork` 技能设置[分叉子代理的模型](/docs/zh-CN/skills#run-skills-in-a-subagent)。

102 102

103<h3 id="changing-effort-level">103<h3 id="changing-effort-level">

104 更改工作量级别104 更改工作量级别

106 106

107在大多数模型上，在会话中途更改[工作量级别](/docs/zh-CN/model-config#adjust-effort-level)意味着下一个请求会读取整个对话历史记录而没有缓存命中。当缓存仍然温暖时，Claude Code 会要求您先确认更改。107在大多数模型上，在会话中途更改[工作量级别](/docs/zh-CN/model-config#adjust-effort-level)意味着下一个请求会读取整个对话历史记录而没有缓存命中。当缓存仍然温暖时，Claude Code 会要求您先确认更改。

108 108

109在具有 API 密钥或 Claude 订阅的 Opus 5.5 和 Fable 5.1 上，更改工作量会保持缓存，Claude Code 会在不询问的情况下应用新级别。这不适用于 Amazon Bedrock、Google Cloud 的 Agent Platform 或 [Claude 应用网关](/docs/zh-CN/claude-apps-gateway)，或当您设置 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities) 或您的组织具有 HIPAA 配置时。109在 Opus 5.5、Sonnet 5.5 和 Fable 5.1 上使用 API 密钥或 Claude 订阅时，更改工作量会保持缓存，Claude Code 会在不询问的情况下应用新级别。这不适用于 Amazon Bedrock、Google Cloud 的 Agent Platform 或[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)，或当您设置 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities) 或您的组织具有 HIPAA 配置时。

110 110

111在 v2.1.260 之前，在具有 API 密钥或 Claude 订阅的 Fable 5.1 上更改工作量也会使缓存失效。111在 v2.1.260 之前，在 Fable 5.1 上使用 API 密钥或 Claude 订阅更改工作量也会使缓存失效。

112 112

113<h3 id="turning-on-fast-mode">113<h3 id="turning-on-fast-mode">

114 启用快速模式114 启用快速模式

115</h3>115</h3>

116 116

117启用[快速模式](/docs/zh-CN/fast-mode)会添加一个请求标头，该标头是缓存键的一部分，因此 Claude Code 发送的启用快速模式的第一个请求会读取整个对话历史记录而没有缓存命中。Claude Code 在回合开始时设置该标头一次，并为整个回合保持它，因此当您在 Claude 工作时启用快速模式时，标头的缓存未命中会在您下一个回合的第一个请求时发生。这些未缓存的输入令牌按[快速模式费率](/docs/zh-CN/fast-mode#understand-the-cost-tradeoff)计费，这就是为什么在会话开始时启用它的成本比在长会话深处启用它的成本要低。如果您当前的模型不支持快速模式，启用快速模式也会[切换您的模型](#switching-models)，该切换从运行回合中的下一个请求开始启动新的缓存。117启用[快速模式](/docs/zh-CN/fast-mode)会添加一个请求标头，该标头是缓存键的一部分，因此 Claude Code 发送的启用快速模式的第一个请求会读取整个对话历史记录而没有缓存命中。Claude Code 在回合开始时设置该标头一次，并为整个回合保持它，因此当您在 Claude 工作时启用快速模式时，标头的缓存未命中发生在您下一个回合的第一个请求上。这些未缓存的输入令牌按[快速模式费率](/docs/zh-CN/fast-mode#understand-the-cost-tradeoff)计费，这就是为什么在会话开始时启用它的成本比在长会话深处启用它的成本要低。如果您当前的模型不支持快速模式，启用快速模式也会[切换您的模型](#switching-models)，该切换从运行回合中的下一个请求开始启动新的缓存。

118 118

119成本每个对话应用一次。在第一个快速模式回合之后，Claude Code 继续发送标头，仅改变请求的速度设置，这不是缓存键的一部分。关闭快速模式、[在速率限制后自动回退到标准速度](/docs/zh-CN/fast-mode#handle-rate-limits)以及稍后重新启用它都会保持缓存。如果您在会话中途[用完使用额度](/docs/zh-CN/fast-mode#handle-rate-limits)，Claude Code 会以相同的方式在标准速度下重试每个被拒绝的快速模式请求，因此此回退也会保持缓存。`/clear` 和 `/compact` 会重置此设置，因为它们无论如何都会在这些点重建缓存。119成本每个对话应用一次。在第一个快速模式回合之后，Claude Code 继续发送标头，仅改变请求的速度设置，这不是缓存键的一部分。关闭快速模式、[速率限制后自动回退到标准速度](/docs/zh-CN/fast-mode#handle-rate-limits)以及稍后重新启用它都会保持缓存。如果您在会话中途[用完使用额度](/docs/zh-CN/fast-mode#handle-rate-limits)，Claude Code 会以相同的方式在标准速度下重试每个被拒绝的快速模式请求，因此此回退也会保持缓存。`/clear` 和 `/compact` 会重置此设置，因为它们无论如何都会在这些点重建缓存。

120 120

121<h3 id="connecting-or-disconnecting-an-mcp-server">121<h3 id="connecting-or-removing-an-mcp-server">

122 连接或断开 MCP 服务器122 连接或移除 MCP 服务器

123</h3>123</h3>

124 124

125工具定义位于系统提示层，因此当请求中的工具定义集在回合之间发生变化时，缓存会失效。切换[顾问工具](/docs/zh-CN/advisor)是一个例外：其定义位于缓存断点之后，因此启用或禁用 `/advisor` 会保持缓存的前缀完整。[MCP 服务器](/docs/zh-CN/mcp)更改是否执行此操作取决于其工具是否由[工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)延迟或加载到前缀中：125工具定义位于系统提示层，因此当请求中的工具定义集在回合之间发生变化时，缓存会失效。切换[顾问工具](/docs/zh-CN/advisor)是一个例外：其定义位于缓存断点之后，因此启用或禁用 `/advisor` 会保持缓存的前缀完整。[MCP 服务器](/docs/zh-CN/mcp)更改是否执行此操作取决于是否[工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)延迟会话的 MCP 工具，这是支持的模型上的默认设置：

126 126

127* **延迟工具**，在支持的模型上是默认值：服务器连接、断开连接或更改其工具列表只会追加新内容，不会扰乱已缓存的任何内容。127* **工具延迟**：Claude Code 为整个对话保持来自对话第一个请求的工具列表，因此服务器在会话中途连接或断开连接不会干扰已缓存的任何内容。在第一个请求后完成连接的服务器提供其工具作为 Claude 按需加载的延迟定义。

128* **加载到前缀中的工具**：对它们的任何更改都会使缓存失效。这发生在[工具搜索不可用或被禁用](/docs/zh-CN/mcp#configure-tool-search)时，例如在早于 Claude 4.5 代的 Google Cloud Agent Platform 模型上、使用自定义 `ANTHROPIC_BASE_URL` 网关或在 Microsoft Foundry [部署在 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)一旦 Claude Code 检测到部署拒绝工具搜索时。它也发生在标记为 [`alwaysLoad`](/docs/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器或工具上，以及由[基于阈值的加载](/docs/zh-CN/mcp#configure-tool-search)保持在前面的定义上。128* **工具加载到前缀中**：添加定义会使缓存失效，移除定义也会。这适用于当[工具搜索低于其 `auto` 阈值、被禁用或不可用](/docs/zh-CN/mcp#configure-tool-search)时，例如在 Google Cloud 的 Agent Platform 模型早于 Claude 4.5 代、具有自定义 `ANTHROPIC_BASE_URL` 网关或在 Microsoft Foundry [部署在 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)一旦 Claude Code 检测到部署拒绝工具搜索时。

129 129

130当工具加载到前缀中时，失效的最常见原因是服务器在会话中途连接或断开连接，这可能在没有您采取任何操作的情况下发生：stdio 服务器的进程退出、HTTP 会话过期或服务器[在暂时故障后自动重新连接](/docs/zh-CN/mcp#automatic-reconnection)。连接的服务器也可以推送[动态工具更新](/docs/zh-CN/mcp#dynamic-tool-updates)来更改其工具列表。130没有工具搜索，中途服务器更改是否使缓存失效取决于更改的内容。对于每个更改，此表给出缓存是否保持以及下一个请求中工具定义发生的情况。

131

132| 中途更改 | 缓存 | 下一个请求中的工具定义 |

133| - | - | - |

134| 服务器连接，或[动态工具更新](/docs/zh-CN/mcp#dynamic-tool-updates)添加工具 | 失效 | 添加新定义 |

135| 服务器在您没有采取任何操作的情况下断开连接，例如 stdio 服务器的进程退出 | 保持 | 服务器的定义保持不变。对其工具之一的调用返回错误而不是运行 |

136| 远程服务器在连接断开后[自动重新连接](/docs/zh-CN/mcp#automatic-reconnection) | 保持，除非在服务器重新连接时发送的请求添加了 `WaitForMcpServers` 工具，这会使缓存失效一次 | 服务器的定义保持不变。在服务器重新连接时发送的请求可以在对话尚未列出时添加 `WaitForMcpServers`，然后该工具对对话的其余部分保持列出 |

137| 您故意移除工具，例如使用[拒绝规则](#denying-an-entire-tool)或通过在 `/mcp` 中禁用其服务器 | 失效 | 定义被移除 |

138

139当您恢复其工具加载到前缀中的对话时，其中一个 MCP 服务器仍然可以在第一个请求发出时连接。如果记录的对话记录了该服务器的工具定义，该请求会按记录包含它们，因此当服务器以相同的工具完成连接时它不会改变。

131 140

132编辑您的 MCP 配置本身不会改变缓存。新配置仅在重启后生效，这是服务器连接或断开连接的时候。141编辑您的 MCP 配置本身不会改变缓存。新配置仅在重启后生效，这是服务器连接或断开连接的时候。

133 142

135 启用或禁用插件144 启用或禁用插件

136</h3>145</h3>

137 146

138当您启用或禁用[插件](/docs/zh-CN/plugins/overview)时，更改的成本取决于插件提供的组件类型。下面的情况涵盖每个组件类型、Claude Code 何时应用更改以及在同一会话中再次禁用插件时会发生什么。147当您启用或禁用[插件](/docs/zh-CN/plugins/overview)时，更改的成本取决于插件提供的组件类型。下面的情况涵盖每个组件类型、Claude Code 何时应用更改以及在同一会话中再次禁用插件时发生的情况。

139 148

140<h4 id="plugin-components-that-keep-the-cache">149<h4 id="plugin-components-that-keep-the-cache">

141 保持缓存的插件组件150 保持缓存的插件组件

142</h4>151</h4>

143 152

144Claude Code 永远不会为插件的技能、命令、代理、hooks、监视器或主题使缓存失效。它在现有对话之后追加其内容，因此下一个请求为该内容付费，并仍然从缓存中读取其之前的所有内容。153Claude Code 永远不会为插件的技能、命令、代理、hooks、监视器或主题使缓存失效。它在现有对话之后附加其内容，因此下一个请求为该内容付费，并仍然从缓存中读取其之前的所有内容。

145 154

146<h4 id="plugins-that-provide-mcp-servers">155<h4 id="plugins-that-provide-mcp-servers">

147 提供 MCP 服务器的插件156 提供 MCP 服务器的插件

148</h4>157</h4>

149 158

150当您启用或禁用提供 [MCP 服务器](/docs/zh-CN/plugins/components#mcp-servers) 的插件时，Claude Code 遵循与[连接或断开 MCP 服务器](#connecting-or-disconnecting-an-mcp-server)相同的规则：159当您启用或禁用提供[MCP 服务器](/docs/zh-CN/plugins/components#mcp-servers)的插件时，Claude Code 遵循与[连接或移除 MCP 服务器](#connecting-or-removing-an-mcp-server)相同的规则。

~~151~~

152* 如果 Claude Code 延迟服务器的工具，它会保持缓存。

153* 如果 Claude Code 将它们加载到前缀中，下一个请求会重新读取整个对话。

154 160

155<h4 id="code-intelligence-plugins">161<h4 id="code-intelligence-plugins">

156 代码智能插件162 代码智能插件

162 插件更改何时应用168 插件更改何时应用

163</h4>169</h4>

164 170

165您在 `/plugin` 菜单中所做的更改会通过 [`/reload-plugins`](/docs/zh-CN/plugins/cli-reference#reload-plugins) 进行，Claude Code 在您关闭菜单时为您运行。您需要支付成本，无论是追加公告还是完整重新读取，都在更改应用后的第一个回合。Claude Code 也可以自行应用更改：171您在 `/plugin` 菜单中所做的更改会通过 [`/reload-plugins`](/docs/zh-CN/plugins/cli-reference#reload-plugins) 进行，Claude Code 在您关闭菜单时为您运行。您需要付费，无论是附加公告还是完整重新读取，都在更改应用后的第一个回合。Claude Code 也可以自行应用更改：

166 172

167* 对于具有 `command` 源的插件，Claude Code [可以自行重新加载插件](/docs/zh-CN/plugins/loading#when-a-command-source-re-runs)。173* 对于具有 `command` 源的插件，Claude Code [可以自行重新加载插件](/docs/zh-CN/plugins/loading#when-a-command-source-re-runs)。

168* 当您[从 `/plugin` 界面安装插件](/docs/zh-CN/plugins/install#install-a-plugin)时，Claude Code 可以在安装期间激活它。安装摘要会告诉您它是否这样做了。174* 当您[从 `/plugin` 界面安装插件](/docs/zh-CN/plugins/install#install-a-plugin)时，Claude Code 可以在安装期间激活它。安装摘要会告诉您它是否这样做了。

169* 当您在 v2.1.246 或更高版本上使用 `/cd` [移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory)时，Claude Code 会在移动过程中应用新目录的设置启用的插件，而不会出现保持 `/reload-plugins` 的完整重新读取警告。175* 当您在 v2.1.246 或更高版本上使用 `/cd` [移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory)时，Claude Code 会在移动过程中应用新目录的设置启用的插件，而不会出现保持 `/reload-plugins` 的完整重新读取警告。

170* 在交互式会话中，当您在使用 `--plugin-dir` 传递的[插件文件夹](/docs/zh-CN/plugins/create#load-a-directory-or-archive-for-one-session)中添加或删除插件时，更改会立即应用。如果应用它会触发完整重新读取，Claude Code 会保持更改并显示运行 `/reload-plugins` 的通知。需要 Claude Code v2.1.265 或更高版本。176* 在交互式会话中，当您在使用 `--plugin-dir` 传递的[插件文件夹](/docs/zh-CN/plugins/create#load-a-directory-or-archive-for-one-session)中添加或移除插件时，更改会立即应用。如果应用它会触发完整重新读取，Claude Code 会保持更改并显示通知以运行 `/reload-plugins`。需要 Claude Code v2.1.265 或更高版本。

171 177

172当 `/reload-plugins` 运行且重新加载会触发完整重新读取时，Claude Code 会显示警告并不应用重新加载。运行 `/reload-plugins --force` 以无论如何应用它。178当 `/reload-plugins` 运行且重新加载会触发完整重新读取时，Claude Code 会显示警告并不应用重新加载。运行 `/reload-plugins --force` 以无论如何应用它。

173 179

174`/reload-plugins` 也在没有交互式终端的会话中运行，例如桌面应用、Agent SDK 和[非交互式模式](/docs/zh-CN/headless)与 `-p`，当您直接将其输入到会话中时。需要 Claude Code v2.1.260 或更高版本。180`/reload-plugins` 也在没有交互式终端的会话中运行，例如桌面应用、Agent SDK 和[非交互式模式](/docs/zh-CN/headless)与 `-p`，当您直接将其输入到会话中时。需要 Claude Code v2.1.260 或更高版本。

175 181

176在这些会话中，重新加载应用除了插件 MCP 服务器更改之外的所有内容，这些[在您的下一个会话中生效](/docs/zh-CN/plugins/cli-reference#reload-plugins)，因此在会话中途永远不会成本完整重新读取。182在这些会话中，重新加载应用除了插件 MCP 服务器更改之外的所有内容，这些[在您的下一个会话中生效](/docs/zh-CN/plugins/cli-reference#reload-plugins)，因此永远不会在会话中途成本完整重新读取。

177 183

178<h4 id="plugins-you-enable-and-then-disable-in-one-session">184<h4 id="plugins-you-enable-and-then-disable-in-one-session">

179 您在一个会话中启用然后禁用的插件185 您在一个会话中启用然后禁用的插件

180</h4>186</h4>

181 187

182当您禁用您在会话中较早启用的插件时，Claude Code 会恢复之前的请求形状。如果该前缀仍在其[缓存生命周期](#cache-lifetime)内，下一个请求会读取较旧的缓存条目，而不是重建。188当您禁用您在会话中较早启用的插件时，Claude Code 会恢复之前的请求形状。如果该前缀仍在其[缓存生命周期](#cache-lifetime)内，下一个请求会读取较旧的缓存条目而不是重建。

183 189

184<h3 id="denying-an-entire-tool">190<h3 id="denying-an-entire-tool">

185 拒绝整个工具191 拒绝整个工具

186</h3>192</h3>

187 193

188如果您添加像 `Bash` 或 `WebFetch` 这样的裸工具名称作为[拒绝规则](/docs/zh-CN/permissions#manage-permissions)，Claude 无法从您的下一个请求开始调用该工具，无论您是通过 `/permissions` 添加规则还是通过[直接编辑设置文件](/docs/zh-CN/settings#when-edits-take-effect)。这包括您通过 `/permissions` 在回合中途添加的规则。194如果您添加一个裸工具名称如 `Bash` 或 `WebFetch` 作为[拒绝规则](/docs/zh-CN/permissions#manage-permissions)，Claude 无法从您的下一个请求开始调用该工具，无论您是通过 `/permissions` 添加规则还是通过[直接编辑设置文件](/docs/zh-CN/settings#when-edits-take-effect)。这包括您在回合中途通过 `/permissions` 添加的规则。

189 195

190当[工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)处于活动状态时（在支持的模型上是默认值），请求的工具定义不会改变，缓存的前缀会保留。当工具搜索不可用或被禁用时，Claude Code 会从下一个请求中删除定义，这会使缓存失效，稍后删除规则也会这样做。196当[工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)处于活动状态时，这是支持的模型上的默认设置，请求的工具定义不会改变，缓存的前缀会存活。当工具搜索不可用或被禁用时，Claude Code 会从下一个请求中移除定义，这会使缓存失效，稍后移除规则也会。

191 197

192只有在工具名称位置匹配的拒绝规则才会以这种方式阻止工具：裸工具名称、等效的 `Bash(*)` 形式或[工具名称 glob](/docs/zh-CN/permissions#tool-name-wildcards) 如 `"*"`。仅匹配 MCP 工具的 glob，例如 `"mcp__*"`，会以相同的方式阻止这些工具。作用域拒绝规则如 `Bash(rm *)`，以及所有允许和询问规则，不会改变 Claude 看到的工具。Claude Code 在 Claude 尝试调用时检查它们，保持前缀完整。198只有在工具名称位置匹配的拒绝规则才会以这种方式阻止工具：裸工具名称、等效的 `Bash(*)` 形式或[工具名称 glob](/docs/zh-CN/permissions#tool-name-wildcards) 如 `"*"`。匹配仅 MCP 工具的 glob，例如 `"mcp__*"`，以相同的方式阻止这些工具。作用域拒绝规则如 `Bash(rm *)`，以及所有允许和询问规则，不会改变 Claude 看到的工具。Claude Code 在 Claude 尝试调用时检查它们，保持前缀完整。

193 199

194<h3 id="compacting-the-conversation">200<h3 id="compacting-the-conversation">

195 压缩对话201 压缩对话

196</h3>202</h3>

197 203

198[压缩](/docs/zh-CN/context-window#what-survives-compaction)用摘要替换您的消息历史记录。根据设计，这会使对话层失效，因为下一个请求具有新的、更短的历史记录，不与旧历史记录共享前缀。Claude Code 重用系统提示层，除非对话是[在保持会话的同时恢复的，该会话会以其他方式改变](#resuming-a-session)；在这种情况下，第一次压缩会切换到当前提示，该层会重建一次。它从磁盘重新加载项目上下文，仅当 CLAUDE.md 和内存自会话开始以来未更改时才缓存命中。204[压缩](/docs/zh-CN/context-window#what-survives-compaction)用摘要替换您的消息历史记录。根据设计，这会使对话层失效，因为下一个请求有一个新的、更短的历史记录，不与旧的共享前缀。Claude Code 重用系统提示层，除非对话是[在保持会以其他方式改变的系统提示的同时恢复的](#resuming-a-session)；在这种情况下，第一次压缩会切换到当前提示，该层重建一次。它从磁盘重新加载项目上下文，仅当 CLAUDE.md 和内存自会话开始以来未改变时才缓存命中。

199 205

200为了生成摘要，Claude Code 会发送一个单独的请求，其系统提示、工具和历史记录与您的对话相同，加上作为最终用户消息追加的摘要指令。当缓存温暖时，该请求从缓存中读取您的前缀，因此中会话 `/compact` 的成本是上下文大小建议的一小部分，并花费大部分时间生成摘要。206为了生成摘要，Claude Code 发送一个单独的请求，其系统提示、工具和历史记录与您的对话相同，加上作为最终用户消息附加的摘要指令。当缓存温暖时，该请求从缓存中读取您的前缀，因此中途 `/compact` 的成本是上下文大小建议的一小部分，并花费大部分时间生成摘要。

201 207

202在长于[缓存生命周期](#cache-lifetime)的中断后，没有缓存可读，因此摘要请求会重新处理完整历史记录作为未缓存输入。这就是为什么当您[恢复旧会话](/docs/zh-CN/sessions#resume-from-a-summary)时 `/compact` 成本最高。在温暖和冷的情况下，压缩后的回合仅为更短的摘要重建对话缓存，因此该回合不是缓慢的部分。208在超过[缓存生命周期](#cache-lifetime)的中断后，没有缓存可读，因此摘要请求将重新处理完整历史记录作为未缓存的输入。这就是为什么当您[恢复旧会话](/docs/zh-CN/sessions#resume-from-a-summary)时 `/compact` 成本最高。在温暖和冷的情况下，压缩后的回合仅为更短的摘要重建对话缓存，因此该回合不是缓慢的部分。

203 209

204<Tip>210<Tip>

205 当您丢弃的上下文是您不再需要的内容时，压缩对您有利。要选择其开销何时发生，请在工作中的自然中断处（例如任务之间）运行 `/compact`，而不是等待自动压缩在任务中途触发。如果您走上了一条想要完全放弃的路径，请改为[`/rewind`](#rewinding-the-conversation)到较早的回合。重新绕过会截断回到已缓存的前缀，而不是像压缩那样构建新的前缀。211 当您丢弃的上下文是您不再需要的内容时，压缩对您有利。要选择其开销发生的时间，请在工作中的自然中断处（例如任务之间）运行 `/compact`，而不是等待自动压缩在任务中途触发。如果您走上了一条想要完全放弃的路径，[`/rewind`](#rewinding-the-conversation)到较早的回合。重新绕回截断回到已缓存的前缀，而不是像压缩那样构建新的。

206</Tip>212</Tip>

207 213

208<h3 id="accumulating-many-images">214<h3 id="accumulating-many-images">

209 积累许多图像215 积累许多图像

210</h3>216</h3>

211 217

212API 限制每个请求可以携带多少图像和 PDF。有关当前数字，请参阅 API 文档中的[请求限制](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits)。Claude Code 也限制了请求中图像和 PDF 的总大小，因此大型屏幕截图比小型屏幕截图更快达到限制。218API 限制每个请求可以携带多少图像和 PDF。有关当前数字，请参阅 API 文档中的[请求限制](https://platform.claude.com/docs/en/build-with-claude/vision#request-limits)。Claude Code 也限制请求中图像和 PDF 的总大小，因此大型屏幕截图比小型屏幕截图更快达到限制。

213 219

214当下一个请求会超过任一限制时，Claude Code 会从它发送的内容中删除一批最旧的图像和 PDF，这为更多内容腾出空间，然后才需要再次删除任何内容。Claude 不再能看到删除的图像。如果 Claude 再次需要其中一个，请再次共享它。220当下一个请求会超过任一限制时，Claude Code 会从它发送的内容中移除一批最旧的图像和 PDF，这为更多内容腾出空间，然后才需要再次移除任何内容。Claude 无法再看到移除的图像。如果 Claude 再次需要其中一个，请再次共享它。

215 221

216删除图像会改变保存它们的消息，因此下一个请求会从这些消息中最早的消息开始重新处理对话。因为 Claude Code 一次删除一批，您会看到每批一个较慢的回合，而不是每个新屏幕截图一个。222移除图像会改变保存它们的消息，因此下一个请求会从这些消息中最早的开始重新处理对话。因为 Claude Code 一次移除一批，您会看到每批一个较慢的回合，而不是每个新屏幕截图一个。

217 223

218<h3 id="upgrading-claude-code">224<h3 id="upgrading-claude-code">

219 升级 Claude Code225 升级 Claude Code

220</h3>226</h3>

221 227

222新的 Claude Code 版本通常会更新系统提示或工具定义，因此升级后启动的第一个对话会从顶部构建其缓存。[自动更新](/docs/zh-CN/setup#auto-updates)在后台下载新版本，但在下一次启动时应用它们，从不在会话中途，因此您会看到这是重启后的未缓存第一个回合，而不是会话期间的惊喜。设置 `DISABLE_AUTOUPDATER=1` 来控制何时应用升级。228新的 Claude Code 版本通常会更新系统提示或工具定义，因此升级后您启动的第一个对话从顶部构建其缓存。[自动更新](/docs/zh-CN/setup#auto-updates)在后台下载新版本，但在下一次启动时应用它们，从不在会话中途，因此您会看到这是重启后的未缓存第一个回合，而不是会话中的惊喜。设置 `DISABLE_AUTOUPDATER=1` 以控制何时应用升级。

223 229

224<Note>230<Note>

225 有关恢复您在升级前启动的对话的成本，请参阅[恢复会话](#resuming-a-session)。231 有关恢复您在升级前启动的对话的成本，请参阅[恢复会话](#resuming-a-session)。

244 编辑存储库中的文件250 编辑存储库中的文件

245</h3>251</h3>

246 252

247文件内容仅在 Claude 读取文件时进入上下文，而读取操作会追加到对话中。编辑 Claude 之前读过的文件不会追溯性地改变历史记录中的早期读取。相反，Claude Code 会追加一条 `<system-reminder>` 注明文件已更改，Claude 会在需要时重新读取该文件。253文件内容仅在 Claude 读取文件时进入上下文，而读取操作会追加到对话中。编辑 Claude 之前读过的文件不会追溯性地改变历史记录中的早期读取。相反，Claude Code 会追加一条 [`<system-reminder>`](/docs/zh-CN/glossary#system-reminder) 注明文件已更改，Claude 会在需要时重新读取该文件。

248 254

249<h3 id="editing-claude-md-mid-session">255<h3 id="editing-claude-md-mid-session">

250 在会话中编辑 CLAUDE.md256 在会话中编辑 CLAUDE.md

354 缓存范围360 缓存范围

355</h2>361</h2>

356 362

357在 Claude Code 中，缓存有效地限定在一台机器和目录。每个对话都携带工作目录、平台、shell 和 OS 版本，系统提示命名您的自动内存路径，所以两个不同目录中的会话构建不同的前缀并错过彼此的缓存。这包括同一存储库的 worktrees，因为每个 worktree 都有自己的工作目录。363在 Claude Code 中，缓存有效地限定在一台机器和目录。系统提示嵌入了您的自动内存路径，对话以工作目录、平台、shell 和 OS 版本的公告开始。因此，两个不同目录中的会话构建不同的前缀并错过彼此的缓存。

358 364

359您在同一目录中并行运行的会话构建匹配的前缀并读取彼此的缓存。顺序会话仅当启动时的 git 状态快照匹配时才共享前缀，因为每个对话也携带该快照中的分支和最近的提交。365您在同一目录中并行运行的会话构建匹配的前缀并读取彼此的缓存。顺序会话仅当启动时的 git 状态快照匹配时才共享前缀，因为每个对话也携带该快照中的分支和最近的提交。

360 366

361底层 API 缓存更广泛。缓存在组织之间隔离，在某些提供商上，[在组织内的工作区之间隔离](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-storage-and-sharing)。在这些边界内，任何两个具有相同模型和前缀的请求读取相同的缓存。对于运行自动化流程队列的 Agent SDK 调用者，请参阅[改进跨用户和机器的 prompt caching](/docs/zh-CN/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)以抑制系统提示的按机器部分并跨机器共享缓存。367底层 API 缓存更广泛。缓存在组织之间隔离，在某些提供商上，[在组织内的工作区之间隔离](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-storage-and-sharing)。在这些边界内，任何两个具有相同模型和前缀的请求读取相同的缓存。对于运行自动化流程队列的 Agent SDK 调用者，请参阅[改进跨用户和机器的 prompt caching](/docs/zh-CN/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)以将自动内存位置移出系统提示并跨用户和机器共享系统提示的缓存条目。

362 368

363<h2 id="check-cache-performance">369<h2 id="check-cache-performance">

364 检查缓存性能370 检查缓存性能

405| 变量 | 效果 |411| 变量 | 效果 |

406| - | - |412| - | - |

412 418

419`DISABLE_PROMPT_CACHING_HAIKU` 适用于默认 Haiku 模型，即 `haiku` 别名解析到的模型。它在该模型运行的任何地方禁用缓存，包括当它是您的主模型时的主对话。覆盖主对话需要 Claude Code v2.1.283 或更高版本。

420

421该变量还涵盖您使用已弃用的 `ANTHROPIC_SMALL_FAST_MODEL` 变量设置的后台模型，当该模型与您的主模型不同时。

422

423您固定为主模型的不同 Haiku 版本保持缓存；设置 `DISABLE_PROMPT_CACHING` 以禁用其缓存。

424

413要在整个组织中设置缓存策略，请将这些或[TTL 变量](#cache-lifetime)中的任何一个放在[托管设置](/docs/zh-CN/managed-settings)的 `env` 块中。对于正常使用，保持缓存启用。425要在整个组织中设置缓存策略，请将这些或[TTL 变量](#cache-lifetime)中的任何一个放在[托管设置](/docs/zh-CN/managed-settings)的 `env` 块中。对于正常使用，保持缓存启用。

414 426

415<h2 id="related-resources">427<h2 id="related-resources">

quickstart.md +4 −2

Details

31 步骤 1：安装 Claude Code31 步骤 1：安装 Claude Code

32</h2>32</h2>

33 33

~~34要安装 Claude Code，请使用以下方法之一：~~34要安装 Claude Code，请打开终端并运行适用于您的系统的命令。如果您之前没有使用过终端，[终端指南](/docs/zh-CN/terminal-guide)会展示如何打开终端并粘贴命令。

35 35

36<Tabs>36<Tabs>

37 <Tab title="原生安装（推荐）">37 <Tab title="原生安装（推荐）">

53 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd53 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

54 ```54 ```

55 55

56 安装程序完成后，打开一个新的终端窗口并运行 `claude --version`。正常的安装会打印一个版本号。如果您的 shell 显示找不到 `claude` 或无法识别，说明安装目录还不在您的 PATH 中：请参阅[修复您的 PATH](/docs/zh-CN/troubleshoot-install#command-not-found-claude-after-installation)。

56 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。当您在 PowerShell 中时，您的提示符显示 `PS C:\`，当您在 CMD 中时显示 `C:\`（没有 `PS`）。58 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。当您在 PowerShell 中时，您的提示符显示 `PS C:\`，当您在 CMD 中时显示 `C:\`（没有 `PS`）。

57 59

58 如果安装命令失败并显示 `syntax error near unexpected token '<'`、`403` 或其他 curl 错误，请参阅 [Troubleshoot installation](/docs/zh-CN/troubleshoot-install#find-your-error) 以匹配错误并获得修复方案和替代安装方法。60 如果安装命令失败并显示 `syntax error near unexpected token '<'`、`403` 或其他 curl 错误，请参阅 [Troubleshoot installation](/docs/zh-CN/troubleshoot-install#find-your-error) 以匹配错误并获得修复方案和替代安装方法。

191 193

192Claude Code 找到适当的文件并向您显示更改。如果它在进行更改前询问，请选择**是**以批准。194Claude Code 找到适当的文件并向您显示更改。如果它在进行更改前询问，请选择**是**以批准。

193 195

194Auto 模式是 Pro、Max 和 Team 计划上交互式终端会话的[内置起始权限模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)：分类器审查操作而不是您，Claude 在不询问的情况下编辑大多数文件并运行大多数命令。在其他计划上，Manual 模式是内置起始权限模式。对于安装后立即启动的会话，请参阅[安装或升级后的首个会话](/docs/zh-CN/env-vars#first-session-after-an-install-or-upgrade)。196使用 Claude Code v2.1.283 或更高版本，auto 模式是交互式终端会话的[内置起始权限模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)：分类器审查操作而不是您，Claude 在不询问的情况下编辑大多数文件并运行大多数命令。在早期版本上，auto 模式仅在 Pro、Max 和 Team 计划上是内置起始权限模式。对于安装后立即启动的会话，请参阅[安装或升级后的首个会话](/docs/zh-CN/env-vars#first-session-after-an-install-or-upgrade)。

195 197

196<Note>198<Note>

197 您的设置或您的组织可以设置不同的起始权限模式。[会话启动时的权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)列出了相关内容。随时按 `Shift+Tab` 切换您所在会话的权限模式。199 您的设置或您的组织可以设置不同的起始权限模式。[会话启动时的权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)列出了相关内容。随时按 `Shift+Tab` 切换您所在会话的权限模式。

remote-control.md +154 −161

Details

6 6

7> 使用 Remote Control 从您的手机、平板电脑或任何浏览器继续本地 Claude Code 会话。适用于 claude.ai/code 和 Claude 移动应用。7> 使用 Remote Control 从您的手机、平板电脑或任何浏览器继续本地 Claude Code 会话。适用于 claude.ai/code 和 Claude 移动应用。

8 8

~~9<Note>~~

10 Remote Control 在所有计划中都可用。在 Team 和 Enterprise 上，在所有者在 [Claude Code 管理员设置](https://claude.ai/admin-settings/claude-code)中启用 Remote Control 切换之前，它默认处于关闭状态。

~~11</Note>~~

13Remote Control 将 [claude.ai/code](https://claude.ai/code) 或 Claude 应用（[iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 和 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude)）连接到在您的机器上运行的 Claude Code 会话。在您的办公桌上启动一个任务，然后从沙发上的手机或另一台计算机上的浏览器继续。9Remote Control 将 [claude.ai/code](https://claude.ai/code) 或 Claude 应用（[iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 和 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude)）连接到在您的机器上运行的 Claude Code 会话。在您的办公桌上启动一个任务，然后从沙发上的手机或另一台计算机上的浏览器继续。

14 10

15当您在机器上启动 Remote Control 会话时，Claude 始终在本地运行，因此您的代码执行和文件系统访问保留在您的机器上。使用 Remote Control，您可以：11当您在机器上启动 Remote Control 会话时，Claude 始终在本地运行，因此您的代码执行和文件系统访问保留在您的机器上。使用 Remote Control，您可以：

17* **远程使用您的完整本地环境**：您的文件系统、[MCP servers](/docs/zh-CN/mcp)、工具和项目配置都保持可用，输入 `@` 会自动完成本地项目中的文件路径。13* **远程使用您的完整本地环境**：您的文件系统、[MCP servers](/docs/zh-CN/mcp)、工具和项目配置都保持可用，输入 `@` 会自动完成本地项目中的文件路径。

18* **同时从两个界面工作**：对话和 [subagents](/docs/zh-CN/sub-agents) 和 [dynamic workflows](/docs/zh-CN/workflows) 的进度在所有连接的设备上保持同步，因此您可以从终端、浏览器和手机交替发送消息。14* **同时从两个界面工作**：对话和 [subagents](/docs/zh-CN/sub-agents) 和 [dynamic workflows](/docs/zh-CN/workflows) 的进度在所有连接的设备上保持同步，因此您可以从终端、浏览器和手机交替发送消息。

19* **从您的手机或浏览器发送图像和文件**：在 Claude 应用或 claude.ai/code 中附加照片或文件，可以带有或不带有标题。Claude 直接将附加的照片视为您消息的一部分。Claude Code 将其他文件下载到您的机器，并将其作为 `@` 文件引用传递给 Claude。15* **从您的手机或浏览器发送图像和文件**：在 Claude 应用或 claude.ai/code 中附加照片或文件，可以带有或不带有标题。Claude 直接将附加的照片视为您消息的一部分。Claude Code 将其他文件下载到您的机器，并将其作为 `@` 文件引用传递给 Claude。

20* **在中断后恢复**：如果您的笔记本电脑进入睡眠状态或网络断开，当您的机器重新上线时，Claude Code 会自动重新连接。在连接重建时，Claude Code 会对来自 subagents 和工作流的消息、权限提示和状态更新进行排队，并在连接恢复后传递它们。16* **在中断后恢复**：如果您的笔记本电脑进入睡眠状态或网络断开，当您的机器重新上线时，Claude Code 会自动重新连接。

22与[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)（在云基础设施上运行）不同，Remote Control 会话直接在您的机器上运行并与您的本地文件系统交互。网络和移动界面只是该本地会话的一个窗口。

23 17

~~24本页涵盖设置、如何启动和连接到会话，以及 Remote Control 与网络上的 Claude Code 的比较。~~18与[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)（在云基础设施上运行）不同，Remote Control 会话直接在您的机器上运行并与您的本地文件系统交互。网络和移动界面只是该本地会话的一个窗口，因此您的计算机必须保持开启状态，`claude` 进程必须继续运行。

25 19

26<h2 id="requirements">20<h2 id="requirements">

27 要求21 要求

33* **身份验证**：运行 `claude` 并使用 `/login` 通过 claude.ai 登录（如果您还没有登录）。如果没有符合条件的登录，`claude remote-control` 会以错误退出，而 `claude --remote-control` 仍会启动交互式会话，并在启动后不久显示 Remote Control 失败通知。27* **身份验证**：运行 `claude` 并使用 `/login` 通过 claude.ai 登录（如果您还没有登录）。如果没有符合条件的登录，`claude remote-control` 会以错误退出，而 `claude --remote-control` 仍会启动交互式会话，并在启动后不久显示 Remote Control 失败通知。

34* **API 端点**：在以下任何配置中都不可用：28* **API 端点**：在以下任何配置中都不可用：

35 * 您使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。29 * 您使用 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。

36 * 您将 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 指向 `api.anthropic.com` 以外的主机，例如 [LLM gateway](/docs/zh-CN/llm-gateway) 或代理。取消设置该变量以使用 Remote Control。在 v2.1.196 之前，Claude Code 允许使用自定义 `ANTHROPIC_BASE_URL` 进行 Remote Control。30 * 您将 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 指向 `api.anthropic.com` 以外的主机，例如 [LLM gateway](/docs/zh-CN/llm-gateway) 或代理。取消设置该变量以使用 Remote Control。

37 * 您通过企业 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 登录。31 * 您通过企业 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 登录。

38* **功能标志评估**：[`DISABLE_TELEMETRY`、`DO_NOT_TRACK`、`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 和 `DISABLE_GROWTHBOOK`](/docs/zh-CN/env-vars) 各自禁用 Remote Control 可用性所依赖的功能标志评估。在您的 shell 环境或 [`settings.json` 文件](/docs/zh-CN/settings-reference#all-settings)的 `env` 块中取消设置该变量，以使用 Remote Control。32* **功能标志评估**：如果您设置了[关闭功能标志评估的环境变量](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)，Remote Control 是否可用取决于您设置的是哪一个：

39* **工作区信任**：在您的项目目录中至少运行一次 `claude` 以接受工作区信任对话框。启动信任对话框永远不会为您的主目录保存信任，因此请从项目目录启动 Remote Control。33 * 如果您设置了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 或 `DISABLE_GROWTHBOOK`，Remote Control 不可用。在您的 shell 环境或 [`settings.json` 文件](/docs/zh-CN/settings-reference#all-settings)的 `env` 块中取消设置该变量，以使用 Remote Control。

34 * 如果您仅设置了 `DISABLE_TELEMETRY` 或 `DO_NOT_TRACK`，Remote Control 保持可用，除非您的组织需要[受信任的设备](#trusted-devices)。如果需要，取消设置该变量以使用 Remote Control。使用设置了任一变量的 Remote Control 需要 Claude Code v2.1.283 或更高版本。

35* **工作区信任**：在您尚未信任的目录中，`claude remote-control` 会打印信任该目录会启用的功能，并在启动前询问 `Trust <directory>? [y/N]`。回答 `y` 会保存该选择，但在您的主目录中除外，在主目录中信任永远不会被保存，每次运行时都会返回该问题。当其标准输入或输出不是终端时，该命令无法询问并以 [`Workspace not trusted`](/docs/zh-CN/errors#workspace-not-trusted-when-starting-remote-control) 错误退出。

40 36

41<h2 id="start-a-remote-control-session">37<h2 id="start-a-remote-control-session">

~~42 启动 Remote Control 会话~~38 启动远程控制会话

43</h2>39</h2>

44 40

~~45您可以从 CLI 或 VS Code 扩展启动 Remote Control 会话。CLI 提供三种调用模式；VS Code 使用 `/remote-control` 命令。~~41您可以从 CLI、[Claude Desktop 应用](/docs/zh-CN/desktop)或 VS Code 扩展启动远程控制会话。CLI 提供三种调用模式；Desktop 应用和 VS Code 使用 `/remote-control` 命令。

46 42

47<Tabs>43<Tabs>

48 <Tab title="服务器模式">44 <Tab title="服务器模式">

52 claude remote-control48 claude remote-control

53 ```49 ```

54 50

55 在您接受 Remote Control 的一次性确认之前，`claude remote-control` 会解释它的作用并在启动服务器之前询问 `Enable Remote Control? (y/n)`。回答 `y` 以接受并启动服务器。如果您拒绝，Claude Code 会退出而不启动服务器，并在您下次运行该命令时再次询问。51 在您接受远程控制的一次性确认之前，`claude remote-control` 会解释它的作用并在启动服务器之前询问 `Enable Remote Control? (y/n)`。回答 `y` 以接受并启动服务器。如果您拒绝，Claude Code 将退出而不启动服务器，并在您下次运行该命令时再次询问。

56 52

57 该进程在您的终端中以服务器模式保持运行，等待远程连接。它显示一个会话 URL，您可以使用该 URL 从[另一个设备连接](#connect-from-another-device)，您可以按空格键显示 QR 码以从手机快速访问。当远程会话处于活动状态时，终端显示连接状态和工具活动。53 该进程在您的终端中以服务器模式保持运行，等待远程连接。它显示一个会话 URL，您可以使用该 URL 从[另一台设备连接](#connect-from-another-device)，您可以按空格键显示 QR 码以从您的手机快速访问。当远程会话处于活动状态时，终端显示连接状态和工具活动。

58 54

59 可用标志：55 可用标志：

60 56

61 | 标志 | 描述 |57 | 标志 | 描述 |

62 | - | - |58 | - | - |

63 | `--name "My Project"` | 设置自定义会话标题，在 claude.ai/code 的会话列表中可见。 |59 | `--name "My Project"` | 设置自定义会话标题，在 claude.ai/code 的会话列表中可见。 |

64 | `--remote-control-session-name-prefix <prefix>` | 未设置显式名称时自动生成的会话名称的前缀。默认为您的机器的主机名，生成类似 `myhost-graceful-unicorn` 的名称。设置 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以获得相同效果。 |60 | `--remote-control-session-name-prefix <prefix>` | 当未设置显式名称时，自动生成的会话名称的前缀。默认为您的机器主机名，生成类似 `myhost-graceful-unicorn` 的名称。设置 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以获得相同效果。 |

65 | `-c`, `--continue` | 恢复此目录中最后一个服务器启动的会话，而不是创建新会话。请参阅[停止服务器后恢复会话](#resume-sessions-after-stopping-the-server)。不能与 `--session-id`、`--spawn`、`--capacity` 或 `--create-session-in-dir` 结合使用。需要 Claude Code v2.1.200 或更高版本；早期版本会将该标志拒绝为未知参数。 |61 | `-c`, `--continue` | 恢复此目录中最后一个服务器启动的会话，而不是创建新会话。请参阅[停止服务器后恢复会话](#resume-sessions-after-stopping-the-server)。不能与 `--session-id`、`--spawn`、`--capacity` 或 `--create-session-in-dir` 结合使用。需要 Claude Code v2.1.200 或更高版本。 |

66 | `--session-id <id>` | 通过其 ID 恢复一个会话。请参阅[停止服务器后恢复会话](#resume-sessions-after-stopping-the-server)。不能与 `--continue`、`--spawn`、`--capacity` 或 `--create-session-in-dir` 结合使用。需要 Claude Code v2.1.200 或更高版本；早期版本会将该标志拒绝为未知参数。 |62 | `--session-id <id>` | 按其 ID 恢复一个会话。请参阅[停止服务器后恢复会话](#resume-sessions-after-stopping-the-server)。不能与 `--continue`、`--spawn`、`--capacity` 或 `--create-session-in-dir` 结合使用。需要 Claude Code v2.1.200 或更高版本。 |

67 | `--spawn <mode>` | 服务器如何创建会话。<br />• `same-dir`（默认）：所有会话共享当前工作目录，因此如果编辑相同的文件可能会冲突。<br />• `worktree`：每个按需会话都获得自己的 [git worktree](/docs/zh-CN/worktrees)。需要 git 存储库。<br />• `session`：单会话模式。恰好提供一个会话并拒绝其他连接。仅在启动时设置。<br />在运行时按 `w` 在 `same-dir` 和 `worktree` 之间切换。 |63 | `--spawn <mode>` | 服务器如何创建会话。<br />• `same-dir`（默认）：所有会话共享当前工作目录，因此如果编辑相同文件可能会冲突。<br />• `worktree`：每个按需会话获得自己的 [git worktree](/docs/zh-CN/worktrees)。需要 git 存储库。<br />• `session`：单会话模式。恰好服务一个会话并拒绝其他连接。仅在启动时设置。<br />在运行时按 `w` 在 `same-dir` 和 `worktree` 之间切换。 |

68 | `--capacity <N>` | 最大并发会话数。默认为 32。不能与 `--spawn=session` 一起使用。 |64 | `--capacity <N>` | 最大并发会话数。默认为 32。不能与 `--spawn=session` 一起使用。 |

69 | `--[no-]create-session-in-dir` | 在服务器启动时在当前目录中预创建一个会话，以便您有地方立即输入。在 `worktree` 模式下，此会话保留在当前目录中，而按需会话获得隔离的 worktrees。默认启用。如果您传递 `--no-create-session-in-dir` 以不创建任何会话启动，Claude Code 会在您停止服务器时存档服务器的会话，因此没有任何内容可以[恢复](#resume-sessions-after-stopping-the-server)。 |65 | `--[no-]create-session-in-dir` | 在服务器启动时在当前目录中预创建一个会话，以便您有地方立即输入。在 `worktree` 模式下，此会话保留在当前目录中，而按需会话获得隔离的 worktree。默认启用。如果您传递 `--no-create-session-in-dir` 以不启动任何会话，Claude Code 会在您停止服务器时存档服务器的会话，因此没有任何内容可[恢复](#resume-sessions-after-stopping-the-server)。 |

70 | `--permission-mode <mode>` | 为服务器的会话设置启动[权限模式](/docs/zh-CN/permission-modes)，例如 `acceptEdits`。接受 `manual` 作为 `default` 的别名；无法识别的模式会在启动时停止服务器并列出有效的模式。 |66 | `--permission-mode <mode>` | 为服务器的会话设置起始[权限模式](/docs/zh-CN/permission-modes)，例如 `acceptEdits`。接受 `manual` 作为 `default` 的别名；无法识别的模式会在启动时停止服务器并列出有效模式。 |

~~71 | `--debug-file <path>` | 将调试日志写入给定的文件。 |~~67 | `--chrome` / `--no-chrome` | 在服务器创建的会话中打开或关闭 [Chrome 集成](/docs/zh-CN/chrome)，以便 Claude 可以在您从另一台设备工作时在您的机器上使用 Chrome。没有任何标志，服务器预创建的会话和您从 claude.ai/code 或 Claude 应用启动的任何会话都以 Chrome 关闭开始，即使您[默认启用了 Chrome](/docs/zh-CN/chrome#enable-chrome-by-default)。服务器为您的[项目](/docs/zh-CN/claude-projects)线程之一启动的会话改为遵循该设置，除非在 `bypassPermissions` 模式下。需要 Claude Code v2.1.273 或更高版本。 |

68 | `-d`, `--debug[=<filter>]` | 为服务器打开调试日志记录，可选择按类别过滤。仅以 `=` 形式传递过滤器，例如 `--debug=api,hooks`。需要 Claude Code v2.1.282 或更高版本。 |

69 | `--debug-file <path>` | 将调试日志写入给定文件。 |

72 | `--verbose` | 显示详细的连接和会话日志。 |70 | `--verbose` | 显示详细的连接和会话日志。 |

73 | `--sandbox` / `--no-sandbox` | 启用或禁用[沙箱](/docs/zh-CN/sandboxing)以进行文件系统和网络隔离。默认关闭。 |71 | `--sandbox` / `--no-sandbox` | 启用或禁用[沙箱](/docs/zh-CN/sandboxing)以进行文件系统和网络隔离。默认关闭。 |

74 72

75 在 `remote-control` 之后给出这些标志。73 在 `remote-control` 之后给出这些标志。

76 74

77 如果您在 `remote-control` 之前传递全局 `claude` 标志，或包装脚本添加了一个，Claude Code 不会将该标志转移到服务器创建的会话。Claude Code 仅在丢弃该标志已知不会改变这些会话可以做什么时才允许该标志通过，例如 `--verbose` 或 `--model`。对于任何其他标志，例如 `--settings`，Claude Code [拒绝启动](/docs/zh-CN/errors#not-carried-over-to-the-sessions-remote-control-starts)并命名要删除的标志。在 v2.1.248 之前，`remote-control` 之前的任何选项都会导致 Claude Code 拒绝其后的标志，并出现 `unknown option` 错误。75 如果您在 `remote-control` 之前传递全局 `claude` 标志，或者包装脚本添加了一个，Claude Code 不会将该标志转移到服务器创建的会话。Claude Code 仅在已知删除该标志不会改变这些会话可以执行的操作时才允许该标志通过，例如 `--verbose` 或 `--model`。对于任何其他标志，例如 `--settings`，Claude Code [拒绝启动](/docs/zh-CN/errors#not-carried-over-to-the-sessions-remote-control-starts)并命名要删除的标志。

78 76

~~79 Claude Code 在打印帮助之前检查 Remote Control 资格，因此当您未使用符合条件的帐户登录时，`claude remote-control --help` 会返回错误而不是此标志列表。~~77 Claude Code 在打印帮助之前检查远程控制资格，因此当您未使用符合条件的帐户登录时，`claude remote-control --help` 返回错误而不是此标志列表。

80 </Tab>78 </Tab>

81 79

82 <Tab title="交互式会话">80 <Tab title="交互式会话">

~~83 要启动启用了 Remote Control 的普通交互式 Claude Code 会话，请使用 `--remote-control` 标志（或 `--rc`）：~~81 要启动启用了远程控制的普通交互式 Claude Code 会话，请使用 `--remote-control` 标志（或 `--rc`）：

84 82

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

86 claude --remote-control84 claude --remote-control

87 ```85 ```

88 86

~~89 可选地为会话传递一个名称：~~87 可选择为会话传递一个名称：

90 88

91 ```bash theme={null}89 ```bash theme={null}

92 claude --remote-control "My Project"90 claude --remote-control "My Project"

93 ```91 ```

94 92

95 这为您提供了一个完整的交互式会话在您的终端中，您也可以从 claude.ai 或 Claude 应用控制。与 `claude remote-control`（服务器模式）不同，您可以在会话也可远程使用时在本地输入消息。93 这为您提供了一个完整的交互式会话在您的终端中，您也可以从 claude.ai 或 Claude 应用远程控制。与 `claude remote-control`（服务器模式）不同，您可以在本地输入消息，同时会话也可以远程使用。

96 </Tab>94 </Tab>

97 95

98 <Tab title="从现有会话">96 <Tab title="从现有会话">

108 /remote-control My Project106 /remote-control My Project

109 ```107 ```

110 108

111 这启动一个 Remote Control 会话，该会话继承您当前的对话历史记录。109 这启动一个远程控制会话，该会话继承您当前的对话历史。

112 110

113 在您接受 Remote Control 的一次性确认之前，会出现一个对话框，然后 `/remote-control` 连接。选择**启用 Remote Control** 以接受并连接。如果您选择**算了** 或按 Esc，Claude Code 不会连接，并在您下次运行 `/remote-control` 时再次询问。111 在您接受远程控制的一次性确认之前，在 `/remote-control` 连接之前会出现一个对话框。选择**启用远程控制**以接受并连接。如果您选择**算了**或按 Esc，Claude Code 不会连接，并在您下次运行 `/remote-control` 时再次询问。

114 112

115 此命令不支持 `--verbose`、`--sandbox` 和 `--no-sandbox` 标志。113 此命令不支持 `--verbose`、`--sandbox` 和 `--no-sandbox` 标志。

116 </Tab>114 </Tab>

122 /remote-control120 /remote-control

123 ```121 ```

124 122

125 当 Remote Control 打开时，Claude Code 在提示框页脚中显示 **Remote Control** 指示器。会话连接后，单击指示器直接转到会话，或在 [claude.ai/code](https://claude.ai/code) 的会话列表中找到它。Claude Code 也会在对话中发布会话 URL。要断开连接，请再次运行 `/remote-control`。123 当远程控制打开时，Claude Code 在提示框页脚中显示**远程控制**指示器。会话连接后，单击指示器直接转到会话，或在 [claude.ai/code](https://claude.ai/code) 的会话列表中找到它。Claude Code 也会在对话中发布会话 URL。要断开连接，再次运行 `/remote-control`。

126 124

127 与 CLI 不同，VS Code 命令不接受名称参数或显示 QR 码。会话标题从您的对话历史记录或第一条提示派生。125 与 CLI 不同，VS Code 命令不接受名称参数或显示 QR 码。会话标题从您的对话历史或第一个提示派生。

128 </Tab>126 </Tab>

129</Tabs>

130 127

131<h3 id="check-connection-status">128 <Tab title="Desktop 应用">

132 检查连接状态129 在 [Claude Desktop 应用](/docs/zh-CN/desktop)的代码选项卡中的本地会话中，在提示框中输入 `/remote-control` 或 `/rc`。

133</h3>

134 130

135在交互式会话中，当 Remote Control 连接时，终端显示一个 `/rc active` 指示器，该指示器链接到 claude.ai 上的会话。当终端太窄无法容纳它时，指示器被隐藏。要查看会话 URL 和 QR 码以[从另一个设备连接](#connect-from-another-device)，请再次运行 `/remote-control` 以打开状态面板。该面板还允许您在本地会话继续运行时断开 Remote Control。131 ```text theme={null}

132 /remote-control

133 ```

136 134

137<span id="session-ended-elsewhere" />如果连接在交互式会话中失败，指示器会改变以显示失败，Claude Code 会在通知中显示原因并将其添加到对话中。运行 `/remote-control` 以重新连接，除非原因说会话在其他地方改变：135 会话连接后，在 [claude.ai/code](https://claude.ai/code) 的会话列表中找到它。要断开连接，再次运行 `/remote-control`。

138 136

139* **另一个连接接管了此会话**：另一个设备或 Claude Code 会话现在拥有它。仅当您想从它收回时才运行 `/remote-control`。137 要改为默认为每个会话打开远程控制，请参阅[为所有会话启用远程控制](#enable-remote-control-for-all-sessions)。

140* **此会话从另一个设备或应用被结束或存档**：仅当您想要它回来时才运行 `/remote-control`。Claude Code 会重新打开存档的会话。138 </Tab>

141* **服务器不再报告此会话**：它可能已从另一个设备或应用中删除。139</Tabs>

142 140

143<h3 id="session-url-reminders">141<h3 id="check-connection-status">

144 会话 URL 提醒142 检查连接状态

145</h3>143</h3>

146 144

147当 Remote Control 连接时，Claude Code 会在切换到您的手机或浏览器最有帮助时提醒您会话 URL，因此您不必在 `/remote-control` 中查找链接。提醒会在以下任一时刻出现在提示框上方：145在交互式会话中，当远程控制已连接时，终端显示一个 `/rc active` 指示器，该指示器链接到 claude.ai 上的会话。当终端太窄无法容纳它时，指示器被隐藏。要查看会话 URL 和 QR 码以[从另一台设备连接](#connect-from-another-device)，再次运行 `/remote-control` 以打开状态面板。该面板还允许您断开远程控制，同时您的本地会话继续运行。

148 146

149* **长回合**：当回合运行时间超过服务器调整的阈值时，Claude Code 会显示**仍在工作**通知，带有**从您的手机检查**链接，因此您可以从手机或浏览器跟踪回合，而不是在终端等待。Claude Code 在回合结束时删除它。147<span id="session-ended-elsewhere" />如果连接在交互式会话中失败，指示器会更改以显示失败，Claude Code 会在通知中显示原因并将其添加到对话中。运行 `/remote-control` 以重新连接，除非原因说会话在其他地方更改：

150* **重复的权限提示**：在您在会话中回答了多个[权限提示](/docs/zh-CN/permissions)后，**从您的手机批准工具调用**通知会显示会话 URL。Claude Code 在您的下一个回合开始时删除它。

151 148

152提醒可以出现在任何连接的会话中，包括 Remote Control [自动连接](#enable-remote-control-for-all-sessions)的会话。它们不会在每次这些条件发生时出现，每个提醒在所有会话中总共只出现几次。您无法配置或关闭它们；每个都会自动清除。149* **另一个连接接管了此会话**：另一台设备或 Claude Code 会话现在拥有它。仅当您想取回它时才运行 `/remote-control`。

150* **此会话从另一台设备或应用结束或存档**：仅当您想要会话返回时才运行 `/remote-control`。Claude Code 重新打开存档的会话。

151* **服务器不再报告此会话**：它可能已从另一台设备或应用中删除。

153 152

154<h3 id="connect-from-another-device">153<h3 id="connect-from-another-device">

155 从另一个设备连接154 从另一台设备连接

156</h3>155</h3>

157 156

158一旦 Remote Control 会话处于活动状态，您有几种方式从另一个设备连接：157一旦远程控制会话处于活动状态，您有几种方式从另一台设备连接：

159 158

160* **打开会话 URL** 在任何浏览器中直接转到 [claude.ai/code](https://claude.ai/code) 上的会话。159* **打开会话 URL** 在任何浏览器中直接转到 [claude.ai/code](https://claude.ai/code) 上的会话。

161* **扫描 QR 码** 显示在会话 URL 旁边，直接在 Claude 应用中打开它。使用 `claude remote-control` 时，按空格键切换 QR 码显示。160* **扫描 QR 码** 显示在会话 URL 旁边，以在 Claude 应用中直接打开它。使用 `claude remote-control`，按空格键切换 QR 码显示。

162* **打开 [claude.ai/code](https://claude.ai/code) 或 Claude 应用** 并在会话列表中按名称查找会话。在 Claude 移动应用中，点击导航中的**代码**以访问会话列表。Remote Control 会话在在线时显示带有绿色状态点的计算机图标。161* **打开 [claude.ai/code](https://claude.ai/code) 或 Claude 应用** 并在会话列表中按名称找到会话。在 Claude 移动应用中，点击导航中的**代码**以到达会话列表。远程控制会话在在线时显示带有绿色状态点的计算机图标。

163 162

164当您连接时，设备显示会话已在后台运行的任何子代理和工作流。从设备停止其中一个，Claude Code 会停止您机器上的该任务。163当您连接时，设备显示会话已在后台运行的任何子代理和工作流。从设备停止其中一个，Claude Code 会停止您的机器上的该任务。

165 164

166远程会话标题按以下顺序选择：165远程会话标题按以下顺序选择：

167 166

1681. 您传递给 `--name`、`--remote-control` 或 `/remote-control` 的名称1671. 您传递给 `--name`、`--remote-control` 或 `/remote-control` 的名称

1692. 您使用 `/rename` 设置的标题1682. 您使用 `/rename` 设置的标题

1703. 现有对话历史记录中的最后一条有意义的消息1693. 现有对话历史中最后一条有意义的消息

1714. 自动生成的名称，如 `myhost-graceful-unicorn`，其中 `myhost` 是您的机器的主机名或您使用 `--remote-control-session-name-prefix` 设置的前缀1704. 自动生成的名称，如 `myhost-graceful-unicorn`，其中 `myhost` 是您的机器主机名或您使用 `--remote-control-session-name-prefix` 设置的前缀

~~172~~

173如果您没有设置显式名称，一旦您发送提示，Claude Code 会更新标题以反映您的提示。Claude Code 将自动生成的标题与您的对话语言相匹配，或与配置的 [`language`](/docs/zh-CN/settings-reference#language) 设置相匹配。

174 171

175当您从 claude.ai 或 Claude 应用重命名会话时，Claude Code 也会更新在 `claude --resume` 中显示的本地标题。Claude Code 将相同的重命名应用于提示栏上显示的会话名称，以及当会话[在后台运行](/docs/zh-CN/agent-view)时 `claude agents` 列表中显示的会话名称。在 v2.1.221 之前，从 claude.ai 或 Claude 应用中的会话列表重命名仅更新标题，CLI 保留其以前的会话名称；`/rename`（在 CLI 本身中运行）在任何版本上设置名称。172如果您未设置显式名称，Claude Code 会在您发送提示后更新标题以反映您的提示。当您从 claude.ai 或 Claude 应用重命名会话时，Claude Code 也会更新 `claude --resume` 中显示的本地标题。

176 173

177如果您还没有 Claude 应用，请在 Claude Code 中运行 `/mobile` 以显示 QR 码以访问 [claude.ai/mobile](https://claude.ai/mobile)，这会打开您手机的正确应用商店。174如果您还没有 Claude 应用，请在 Claude Code 中运行 `/mobile` 以显示 QR 码以访问 [claude.ai/mobile](https://claude.ai/mobile)，它会打开您手机的正确应用商店。

178 175

179<h3 id="what-connected-devices-see">176<h3 id="what-connected-devices-see">

180 连接的设备看到什么177 连接的设备看到的内容

181</h3>178</h3>

182 179

183连接的设备会在您的终端中实时显示对话。这些情况超出了普通消息：180连接的设备显示您终端中的对话。这些情况超出了普通消息：

184 181

185* **压缩和 `/clear`**：当 Claude Code [压缩对话](/docs/zh-CN/context-window#what-survives-compaction)时，连接的设备显示进度，然后显示对话被压缩的位置。当您运行 `/clear` 时，对话也会在连接的设备上重置。182* **压缩和 `/clear`**：当 Claude Code [压缩对话](/docs/zh-CN/context-window#what-survives-compaction)时，连接的设备显示进度，然后显示对话被压缩的位置。当您运行 `/clear` 时，对话也会在连接的设备上重置。

186* **使用 `/resume` 切换对话**：连接的设备不会接收切换到的对话的标题或早期历史记录，但双向的新消息会进出您的终端中打开的任何对话。要再次从设备处理原始对话，请在您的终端中运行 `/resume` 并切换回它。183* **使用 `/resume` 切换对话**：连接的设备不会接收切换到的对话的标题或早期历史，但双向的新消息进出您的终端中打开的任何对话。要再次从设备处理原始对话，请在您的终端中运行 `/resume` 并切换回它。

187* **使用 `/teleport` 拉取会话**：当您使用 `/teleport` 将[云会话](/docs/zh-CN/claude-code-on-the-web#from-cloud-to-terminal)拉入您的终端时，连接的设备不会接收拉取的对话的早期历史记录。双向的新消息会进出拉取的对话，这现在是您的终端中打开的对话。184* **使用 `/teleport` 拉取会话**：当您使用 `/teleport` 将[云会话](/docs/zh-CN/claude-code-on-the-web#from-cloud-to-terminal)拉入您的终端时，连接的设备不会接收拉取的对话的早期历史。双向的新消息进出拉取的对话，该对话现在是您的终端中打开的对话。

188* **来自您其他会话的消息**：使用[跨会话消息传递](/docs/zh-CN/cross-session-messaging)，相同的连接在您不同机器上的自己的会话之间以及来自您的[云会话](/docs/zh-CN/claude-code-on-the-web)的消息，通过 Anthropic 服务器，就像其余 Remote Control 流量一样。[在其他机器上的消息会话](/docs/zh-CN/cross-session-messaging#message-sessions-on-other-machines)涵盖传递规则，[控制入站消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)涵盖入站控制。需要 Claude Code v2.1.224 或更高版本。185* **来自您其他会话的消息**：使用[跨会话消息传递](/docs/zh-CN/cross-session-messaging)，相同的连接在不同机器上的您自己的会话之间以及来自您的[云会话](/docs/zh-CN/claude-code-on-the-web)传递消息。

189* **您在回合中途发送的提示**：当您在当前回合结束之前从连接的设备发送提示时，Claude Code 会将其排队并在该回合完成后将其保留在设备的记录中。186* **您的更改的差异**：当会话的目录在 git 存储库中时，连接的设备的差异窗格显示您的更改。在具有超过存储库默认分支的提交的分支上，窗格显示自分支从它分离以来的更改，包括您未提交的编辑。在默认分支本身上，或在不超过它的分支上，窗格仅显示您未提交的更改。

190* **您的更改的差异**：当会话的目录在 git 存储库中时，连接的设备的差异窗格显示您的更改。设备通过连接请求差异，Claude Code 在您的机器上计算它。在分支上有提交领先于存储库的默认分支时，窗格显示自分支从它分叉以来的更改，包括您未提交的编辑。在默认分支本身上，或在不领先于它的分支上，窗格仅显示您未提交的更改。在 v2.1.247 之前，Claude Code 仅向由 `claude remote-control` 提供的会话中的连接设备报告差异。187* **模型**：当您从连接的设备选择[模型](/docs/zh-CN/model-config)时，Claude Code 在该模型上运行会话。需要 Claude Code v2.1.238 或更高版本。您从设备的模型控制中选择的模型仅适用于当前会话。当您从设备向交互式会话发送 `/model <name>` 时，Claude Code 也会为新会话设置您的默认值。

191* **模型**：当您从连接的设备选择[模型](/docs/zh-CN/model-config)时，Claude Code 在该模型上运行会话。终端的 `/model` 选择器、`/status` 和 `/config` 显示该模型。需要 Claude Code v2.1.238 或更高版本。188* **努力级别**：当您从连接的设备使用 `/effort` 或设备的努力控制设置[努力级别](/docs/zh-CN/model-config#adjust-effort-level)时，Claude Code 将其应用于您的机器上的会话。如果您使用 `CLAUDE_CODE_EFFORT_LEVEL` 固定了一个级别，会话保持该级别，Claude Code 拒绝从努力控制中选择不同的级别。从努力控制中选择一个级别需要您的机器上的 Claude Code v2.1.234 或更高版本。

192 * 您从设备的模型控制中选择的模型仅适用于当前会话。当您从设备向交互式会话发送 `/model <name>` 时，Claude Code 也会为新会话设置您的默认值。189* **连接失败后重新连接**：运行 `/remote-control` 以重新连接。如果压缩重写了对话或您在此期间使用 `/resume` 切换了对话，Claude Code 会存档它正在使用的服务器会话，而不是将其留在会话列表中。您仍然可以通过[过滤存档的会话](/docs/zh-CN/claude-code-on-the-web#archive-sessions)找到它。在设备仍然连接时切换对话不会存档会话。

193 * 如果您发送 Claude Code 无法识别的名称，例如预期模型 ID 的显示名称，Claude Code [拒绝选择](/docs/zh-CN/errors#model-is-not-a-recognized-model-id)，会话保留其当前模型。在 v2.1.260 之前，Claude Code 从设备的模型控制中保存无法识别的选择，您的下一条消息失败。

194* **努力级别**：当您从连接的设备使用 `/effort` 或设备的努力控制设置[努力级别](/docs/zh-CN/model-config#adjust-effort-level)时，Claude Code 将其应用于您机器上的会话，claude.ai/code 显示会话正在使用的级别。如果您使用 `CLAUDE_CODE_EFFORT_LEVEL` 固定了一个级别，会话保留该级别，Claude Code 拒绝从努力控制中选择不同的级别。从努力控制中选择级别需要您机器上的 Claude Code v2.1.234 或更高版本。

195* **连接失败后重新连接**：运行 `/remote-control` 以重新连接。如果压缩重写了对话或您在此期间使用 `/resume` 切换了对话，Claude Code 会存档它正在使用的服务器会话，而不是将其保留在会话列表中。您仍然可以通过[过滤存档的会话](/docs/zh-CN/claude-code-on-the-web#archive-sessions)找到它。在设备仍然连接时切换对话不会存档会话。

196 190

197<h3 id="enable-remote-control-for-all-sessions">191<h3 id="enable-remote-control-for-all-sessions">

198 为所有会话启用 Remote Control192 为所有会话启用远程控制

199</h3>193</h3>

200 194

201Remote Control 仅在您显式运行 `claude remote-control`、`claude --remote-control` 或 `/remote-control` 时激活，除非自动连接已打开。要为每个交互式会话打开自动连接，请在 Claude Code 中运行 `/config` 并设置**为所有会话启用 Remote Control**。切换有三个值：195远程控制仅在您显式运行 `claude remote-control`、`claude --remote-control` 或 `/remote-control` 时激活，除非打开了自动连接。要为每个交互式会话打开自动连接，请在 Claude Code 中运行 `/config` 并设置**为所有会话启用远程控制**。切换有三个值：

202 196

203* **`true`**：当交互式会话启动时自动连接。197* **`true`**：当交互式会话启动时自动连接。

204* **`false`**：关闭自动连接，尽管来自[托管设置](/docs/zh-CN/managed-settings)的 `true` 会优先，因为 Claude Code 将选择保存到您的用户设置。项目或本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中的 `false` 甚至会关闭自动连接，即使托管 `true` 也是如此。198* **`false`**：关闭自动连接，尽管来自[托管设置](/docs/zh-CN/managed-settings)的 `true` 会优先，因为 Claude Code 将选择保存到您的用户设置。项目或本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中的 `false` 甚至会关闭自动连接，即使托管 `true` 也是如此。

206 200

207相同的切换出现在 CLI 之外：201相同的切换出现在 CLI 之外：

208 202

209* **桌面应用**：**设置 > Claude Code > 默认启用远程控制**。203* **Desktop 应用**：**设置 > Claude Code > 默认启用远程控制**。

210* **VS Code 扩展**：[命令菜单](/docs/zh-CN/vs-code#use-the-prompt-box)的设置部分中的**为所有会话启用 Remote Control**。需要 Claude Code v2.1.203 或更高版本。204* **VS Code 扩展**：[命令菜单](/docs/zh-CN/vs-code#use-the-prompt-box)的设置部分中的**为所有会话启用远程控制**。

211 205

212要从设置文件改为打开自动连接，请在您的用户 `~/.claude/settings.json` 或[托管设置](/docs/zh-CN/managed-settings)中将 [`remoteControlAtStartup`](/docs/zh-CN/settings-reference#remotecontrolatstartup) 设置为 `true`。在项目或本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中，Claude Code 遵守 `false` 并为该存储库关闭自动连接，但忽略 `true`，因此签入的文件无法为打开存储库的每个人打开 Remote Control。206要改为从设置文件打开自动连接，请在您的用户 `~/.claude/settings.json` 或[托管设置](/docs/zh-CN/managed-settings)中将 [`remoteControlAtStartup`](/docs/zh-CN/settings-reference#remotecontrolatstartup) 设置为 `true`。在项目或本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中，Claude Code 遵守 `false` 并为该存储库关闭自动连接，但忽略 `true`，因此已检入的文件无法为打开存储库的每个人打开远程控制。

213 207

214自动连接使用您自己的 claude.ai 帐户登录，因此它启动的会话仅出现在您自己的帐户的 Claude 应用中，并且不向任何其他人授予访问权限。208自动连接使用您自己的 claude.ai 帐户登录，因此它启动的会话仅出现在您自己的帐户的 Claude 应用中，并且不向任何其他人授予访问权限。

215 209

219 停止服务器后恢复会话213 停止服务器后恢复会话

220</h3>214</h3>

221 215

222当您使用 Ctrl+C 停止 `claude remote-control` 时，它提供的会话停止从您的手机或浏览器响应。只要您没有在同一目录中运行另一个 `claude remote-control` 并且没有使用 `--no-create-session-in-dir` 启动此会话，Claude Code 就不会存档它们。要将它们恢复，请在同一目录中运行以下命令之一：216当您使用 Ctrl+C 停止 `claude remote-control` 时，它正在服务的会话停止从您的手机或浏览器响应。只要您没有在同一目录中运行另一个 `claude remote-control` 并且没有使用 `--no-create-session-in-dir` 启动此会话，Claude Code 就不会存档它们。要恢复它们，请在同一目录中运行以下命令之一：

223 217

224* **`claude remote-control`**：恢复服务器提供的每个会话。218* **`claude remote-control`**：恢复服务器正在服务的每个会话。

225* **`claude remote-control --continue`**：仅恢复服务器启动的会话，并在该会话结束时退出。如果此目录没有记录，Claude Code 会使用此存储库的其他 git worktrees 中最新的。219* **`claude remote-control --continue`**：仅恢复服务器启动的会话，并在该会话结束时退出。如果此目录没有记录，Claude Code 会使用此存储库的其他 git worktree 中最新的。

226* **`claude remote-control --session-id <id>`**：仅恢复您传递的 ID 的会话，并在该会话结束时退出。ID 是会话 URL 在 claude.ai/code 中 `/code/` 和任何 `?` 之间的部分。220* **`claude remote-control --session-id <id>`**：仅恢复您传递其 ID 的会话，并在该会话结束时退出。ID 是会话 URL 在 claude.ai/code 中 `/code/` 和任何 `?` 之间的部分。

227 221

228这些命令在服务器停止后约四小时内有效。之后，运行 `claude remote-control` 以启动新会话。如果您在此期间存档了会话，`--continue` 和 `--session-id` 会在 Claude Code v2.1.228 或更高版本上取消存档它。222这些命令在服务器停止后约四小时内有效。之后，运行 `claude remote-control` 以启动新会话。如果您在此期间存档了会话，`--continue` 和 `--session-id` 会在 Claude Code v2.1.228 或更高版本上取消存档。

229 223

230要恢复您使用 `claude --remote-control` 或 `/remote-control` 启动的会话，请使用 `claude --continue` 或 `claude --resume` 恢复对话。Claude Code 是否重新连接以及连接到哪个会话取决于对话的[重新连接记录](#resume-outcomes)。224要恢复您使用 `claude --remote-control` 或 `/remote-control` 启动的会话，请使用 `claude --continue` 或 `claude --resume` 恢复对话。如果远程控制不重新连接，请参阅[无法重新连接到您的远程控制会话](#couldnt-reconnect-to-your-remote-control-session)。

231 225

232如果您在第二个终端中恢复对话，而第一个终端仍然打开 Remote Control，Claude Code 会在第二个终端中打印通知，并改为在那里关闭 Remote Control，而不是从第一个终端接管会话。当 Remote Control 在那里保持关闭时，该终端中的 Claude 看不到[您在其他机器上的会话](/docs/zh-CN/cross-session-messaging#see-which-sessions-claude-can-reach)，它们也无法到达它。在第二个终端中运行 `/remote-control` 以将 Remote Control 移到它。226如果您在第一个终端仍然打开远程控制的情况下在第二个终端中恢复对话，Claude Code 会在第二个终端中打印 `Remote Control not started here` 通知，并改为在那里关闭远程控制。在第二个终端中运行 `/remote-control` 以将远程控制移动到它。

233 227

234当您在曾经打开 Remote Control 的 Claude Desktop 或 IDE 扩展中恢复对话时，Claude Code 会将其重新附加到现有的 claude.ai 会话，而不是向会话列表添加新会话。228当您在具有远程控制的 Claude Desktop 或 IDE 扩展中恢复对话时，Claude Code 会将其重新附加到现有的 claude.ai 会话，而不是向会话列表添加新会话。

235 229

236<h2 id="connection-and-security">230<h2 id="connection-and-security">

237 连接和安全231 连接和安全

239 233

240您的本地 Claude Code 会话仅发出出站 HTTPS 请求，从不在您的机器上打开入站端口。当您启动 Remote Control 时，它向 Anthropic API 注册并轮询工作。当您从另一个设备连接时，服务器通过流连接在网络或移动客户端和您的本地会话之间路由消息。234您的本地 Claude Code 会话仅发出出站 HTTPS 请求，从不在您的机器上打开入站端口。当您启动 Remote Control 时，它向 Anthropic API 注册并轮询工作。当您从另一个设备连接时，服务器通过流连接在网络或移动客户端和您的本地会话之间路由消息。

241 235

242所有流量都通过 Anthropic API 通过 TLS 传输，与任何 Claude Code 会话的传输安全相同。连接使用多个短期凭证，每个凭证的范围限定为单一目的并独立过期。当 `claude remote-control` 服务器的注册凭证过期时，服务器会再次向 Anthropic API 注册并继续为其会话提供服务。236所有流量都通过 Anthropic API 通过 TLS 传输，与任何 Claude Code 会话的传输安全相同。连接使用多个短期凭证，每个凭证的范围限定为单一目的并独立过期。

243 237

244Remote Control 连接时，会话记录（包括您的消息、Claude 的响应和工具活动）存储在 Anthropic 服务器上。存储的记录保持您的设备之间的对话同步，并让会话在网络中断后重新连接。执行和文件系统访问保留在您的机器上，存储的记录根据[数据使用](/docs/zh-CN/data-usage)政策保留。238Remote Control 连接时，会话记录（包括您的消息、Claude 的响应和工具活动）存储在 Anthropic 服务器上。存储的记录保持您的设备之间的对话同步，并让会话在网络中断后重新连接。执行和文件系统访问保留在您的机器上，存储的记录根据[数据使用](/docs/zh-CN/data-usage)政策保留。

245 239

309对于丢失或被盗的设备，成员从此页面删除它。如果成员无法登录，管理员可以在管理员控制台中使用**到处登出**为该成员撤销每个会话和已注册设备，之后成员重新注册他们仍然持有的设备。303对于丢失或被盗的设备，成员从此页面删除它。如果成员无法登录，管理员可以在管理员控制台中使用**到处登出**为该成员撤销每个会话和已注册设备，之后成员重新注册他们仍然持有的设备。

310 304

311<h2 id="remote-control-vs-cloud-sessions">305<h2 id="remote-control-vs-cloud-sessions">

312 Remote Control 与云会话的比较306 远程控制与云会话

313</h2>307</h2>

314 308

315Remote Control 和[云会话](/docs/zh-CN/claude-code-on-the-web)都使用 claude.ai/code 界面。关键区别在于会话运行的位置：Remote Control 在您的机器上执行，因此您的本地 MCP 服务器、工具和项目配置保持可用。云会话在云基础设施上执行，默认由 Anthropic 管理。309远程控制和[云会话](/docs/zh-CN/claude-code-on-the-web)都使用 claude.ai/code 界面。关键区别在于会话运行的位置：远程控制在您的机器上执行，因此您的本地 MCP 服务器、工具和项目配置保持可用。云会话在云基础设施上执行，默认由 Anthropic 管理。

316 310

317当您处于本地工作中间并想从另一个设备继续时，使用 Remote Control。当您想在没有任何本地设置的情况下启动任务、处理您没有克隆的存储库或并行运行多个任务时，使用云会话。311当您在进行本地工作中途，想要从另一台设备继续工作时，使用远程控制。当您想要在没有任何本地设置的情况下启动任务、处理您没有克隆的仓库，或并行运行多个任务时，使用云会话。[项目](/docs/zh-CN/claude-projects)结合了两者：其线程在云中运行，当您在那里请求时，它使用远程控制来[在您的计算机上运行线程](/docs/zh-CN/claude-projects#run-a-thread-on-your-own-computer)。

312

313Claude Code 提供了多种方式在您不在终端时进行工作。它们在触发工作的方式、Claude 运行的位置以及所需的设置量方面有所不同。

314

315| | 触发方式 | Claude 运行位置 | 设置 | 最适合 |

316| :- | :- | :- | :- | :- |

318| [Remote Control](/docs/zh-CN/remote-control) | 从 [claude.ai/code](https://claude.ai/code) 或 Claude 移动应用驱动正在运行的会话 | 您的机器（CLI、Desktop 或 VS Code） | 运行 [`claude remote-control` 或 `/remote-control`](/docs/zh-CN/remote-control#start-a-remote-control-session) | 从另一台设备控制进行中的工作 |

318 323

319<h2 id="mobile-push-notifications">324<h2 id="mobile-push-notifications">

320 移动推送通知325 移动推送通知

321</h2>326</h2>

322 327

323当 Remote Control 处于活动状态时，Claude 可以向您的手机发送推送通知。328当远程控制处于活跃状态时，Claude 可以向您的手机发送推送通知。

324 329

325Claude 决定何时推送。它通常在长时间运行的任务完成或需要您的决定来继续时发送一个。您也可以在提示中请求推送，例如 `notify me when the tests finish`。除了下面的两个开/关切换外，没有按事件配置。330Claude 决定何时推送。它通常在长时间运行的任务完成时或需要您做出决定以继续时发送一条通知。您也可以在提示中请求推送，例如 `notify me when the tests finish`。除了下面的两个开/关切换外，没有按事件配置。

326 331

327要设置移动推送通知：332要设置移动推送通知：

328 333

329<Steps>334<Steps>

330 <Step title="安装 Claude 移动应用">335 <Step title="安装 Claude 移动应用">

331 下载 Claude 应用（[iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 或 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude)）。336 下载 Claude 应用，适用于 [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 或 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude)。

332 </Step>337 </Step>

333 338

334 <Step title="使用您的 Claude Code 账户登录">339 <Step title="使用您的 Claude Code 账户登录">

340 </Step>345 </Step>

341 346

342 <Step title="在 Claude Code 中启用推送">347 <Step title="在 Claude Code 中启用推送">

343 在您的终端中，运行 `/config` 并启用**当 Claude 决定时推送**以获取主动通知，启用**当需要操作时推送**以获取权限提示和问题，或两者都启用。348 在您的终端中，运行 `/config` 并启用 **Push when Claude decides**（当 Claude 决定时推送）以获得主动通知，**Push when actions required**（当需要操作时推送）以获得权限提示和问题，或两者都启用。

344 </Step>349 </Step>

345</Steps>350</Steps>

346 351

347如果通知没有到达：352如果通知未送达：

348 353

349* 如果 `/config` 显示**未注册移动设备**，请在您的手机上打开 Claude 应用，以便它可以刷新其推送令牌。下次 Remote Control 连接时，警告会清除。354* 如果 `/config` 显示 **No mobile registered**（未注册移动设备），请在您的手机上打开 Claude 应用，以便它可以刷新其推送令牌。下次远程控制连接时，警告将清除。

350* 在 iOS 上，焦点模式和通知摘要可能会抑制或延迟推送。检查设置 → 通知 → Claude。355* 在 iOS 上，焦点模式和通知摘要可能会抑制或延迟推送。检查设置 → 通知 → Claude。

351* 在 Android 上，激进的电池优化可能会延迟传递。在系统设置中将 Claude 应用从电池优化中豁免。356* 在 Android 上，激进的电池优化可能会延迟传递。在系统设置中将 Claude 应用从电池优化中豁免。

352 357

353Claude Code 在您在连接的终端中输入或专注时会跳过移动推送通知。从 v2.1.181 开始，您可以将 [`CLAUDE_CLIENT_PRESENCE_FILE`](/docs/zh-CN/env-vars) 设置为标记文件路径，以将其扩展到您在机器上的任何时间，即使在另一个窗口中：当文件存在时，通知会被跳过。配置屏幕锁定侦听器或类似工具，以在屏幕解锁时创建文件，在屏幕锁定时删除文件。358当您在连接的终端中输入或专注时，Claude Code 会跳过移动推送通知。要将其扩展到您在机器上的任何时间，即使在另一个窗口中，请将 [`CLAUDE_CLIENT_PRESENCE_FILE`](/docs/zh-CN/env-vars) 设置为标记文件路径：当文件存在时，通知会被跳过。配置屏幕锁定侦听器或类似工具，以在屏幕解锁时创建文件，在屏幕锁定时删除文件。

354 359

355<h2 id="limitations">360<h2 id="limitations">

356 限制361 限制

357</h2>362</h2>

358 363

359* **每个交互式进程一个远程会话**：在服务器模式之外，每个 Claude Code 实例一次支持一个远程会话。使用[服务器模式](#start-a-remote-control-session)从单个进程运行多个并发会话。364* **每个交互式进程只能有一个远程会话**：在服务器模式之外，每个 Claude Code 实例一次只支持一个远程会话。使用[服务器模式](#start-a-remote-control-session)从单个进程运行多个并发会话。

360* **本地进程必须保持运行**：Remote Control 作为本地进程运行。如果您关闭终端、退出 VS Code 或以其他方式停止 `claude` 进程，会话将离线，直到您[恢复它](#resume-sessions-after-stopping-the-server)。除非 Claude 正在执行任务中，否则 claude.ai 和 Claude 应用会在进程退出后的几秒内显示会话离线。要在从 SSH 断开连接后保持远程机器上的会话运行，请在 `tmux` 或 `screen` 内启动它。365* **本地进程必须保持运行**：Remote Control 作为本地进程运行。如果你关闭终端、退出桌面应用或 VS Code，或以其他方式停止 `claude` 进程，会话将离线，直到你[恢复它](#resume-sessions-after-stopping-the-server)。要在断开 SSH 连接后保持远程机器上的会话运行，请在 `tmux` 或 `screen` 内启动它。

361* **服务器模式中的崩溃会话**：如果由 `claude remote-control` 提供的会话崩溃，请从连接的设备向其发送消息。Claude Code 将再次提供它。您不必重新启动服务器。需要 Claude Code v2.1.238 或更高版本。366* **服务器模式中的崩溃会话**：如果由 `claude remote-control` 提供的会话崩溃，请从连接的设备向其发送消息。Claude Code 会再次提供它。你不必重启服务器。需要 Claude Code v2.1.238 或更高版本。

362* **已连接会话上的 HTTP 403 拒绝**：一旦交互式会话连接，当您的机器和 Anthropic 服务器之间的某些内容以 HTTP 403 响应时（在 VPN 或网络更改后可能发生），Claude Code 会重试最多三分钟。如果拒绝持续更长时间，Claude Code 会断开连接，原因会说明是什么拒绝了：网络边缘，或您自己网络上的代理、VPN 或防火墙。367* **已连接会话上的 HTTP 403 拒绝**：一旦交互式会话连接，当你的机器和 Anthropic 服务器之间的某个地方返回 HTTP 403 时（在 VPN 或网络更改后可能发生），Claude Code 会重试最多三分钟。如果拒绝持续更长时间，Claude Code 会断开连接，原因会说明是什么拒绝了：网络边缘，或你自己网络上的代理、VPN 或防火墙。

363* **扩展网络中断**：如果您的机器处于唤醒状态但无法到达网络，接下来的操作取决于模式：368* **扩展网络中断**：如果你的机器处于唤醒状态但无法到达网络，接下来的操作取决于模式：

364 * **服务器模式**：Claude Code 在大约 10 分钟后放弃，`claude remote-control` 进程退出。再次运行 `claude remote-control` 以启动新会话。369 * **服务器模式**：Claude Code 在大约 10 分钟后放弃，`claude remote-control` 进程退出。再次运行 `claude remote-control` 以启动新会话。

365 * **交互式会话**：继续在本地工作。Claude Code 会在中断期间持续重试，并在网络恢复时自动重新连接。370 * **交互式会话**：继续在本地工作。Claude Code 会在中断期间持续重试，并在网络恢复时自动重新连接。

366* **存在心跳失败**：如果交互式会话断开连接并显示 `could not reach the Remote Control server for about 30 minutes`，运行 `/remote-control` 以重新连接。Claude Code 仅在会话的存在心跳失败而其余连接保持正常时显示此消息；它会在大约 30 分钟内持续重新注册会话，之后才断开连接。371* **存在心跳失败**：如果交互式会话断开连接并显示 `could not reach the Remote Control server for about 30 minutes`，运行 `/remote-control` 以重新连接。

367* **转发的对话过期**：Claude Code 会保持权限提示和 `AskUserQuestion` 问题打开，直到您回答。当 Claude Code 将另一种对话转发到远程会话时，例如安全拒绝后显示的模型选择提示，默认情况下它会等待五分钟，然后关闭对话并继续使用对话的无操作默认值。设置 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 以调整或禁用截止时间。需要 Claude Code v2.1.224 或更高版本。372* **转发的对话过期**：Claude Code 会保持权限提示和 `AskUserQuestion` 问题打开，直到你回答它们。当 Claude Code 将另一种对话转发到远程会话时，例如安全拒绝后显示的模型选择提示，默认情况下它会等待五分钟，然后关闭对话并继续使用对话的无操作默认值。设置 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 以调整或禁用截止时间。需要 Claude Code v2.1.224 或更高版本。

368* **Fable 使用额度同意提示未被转发**：Claude Code 仅在会话运行的位置显示中途[Fable 使用额度同意提示](/docs/zh-CN/model-config#fable-and-usage-credits)，而不是在您的设备上。当会话在终端中运行且那里没有人在 Claude Code 关闭提示之前回答时，该轮结束而不发送请求；请参阅[确认提示未被回答](/docs/zh-CN/errors#the-prompt-to-confirm-went-unanswered)。373* **Fable 使用额度同意提示未转发**：Claude Code 仅在会话运行的地方显示中途[Fable 使用额度同意提示](/docs/zh-CN/model-config#fable-and-usage-credits)，而不是在你的设备上。当会话在终端中运行且那里没有人在 Claude Code 关闭提示之前回答时，该轮结束而不发送请求；请参阅[确认提示未被回答](/docs/zh-CN/errors#the-prompt-to-confirm-went-unanswered)。

369* **某些命令仅限本地**：仅在终端界面中运行的命令，例如 `/plugin` 或 `/resume`，仅从本地 CLI 工作，无论您是否传递参数。以下命令可从移动和网络工作：374* **某些命令仅限本地**：仅在终端界面中运行的命令，例如 `/plugin` 或 `/resume`，仅从本地 CLI 工作，无论你是否传递参数。以下命令可从移动和网络使用：

370 * 文本输出命令：`/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/usage-credits`、`/recap` 和 `/reload-plugins`。`/usage-credits` 打印计费 URL 而不是打开浏览器。`/reload-plugins` 仅在会话在交互式终端中运行时工作；没有交互式终端的会话会拒绝它。375 * 文本输出命令：`/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/usage-credits`、`/recap` 和 `/reload-plugins`。`/usage-credits` 打印计费 URL 而不是打开浏览器。`/reload-plugins` 仅在会话在交互式终端中运行时工作；没有交互式终端的会话会拒绝它。

371 * `/model`、`/effort`、`/fast`、`/color` 和 `/rename`：将值作为参数传递，例如 `/model sonnet` 或 `/effort high`。从移动和网络，`/model` 和 `/effort` 在终端选择器或滑块的位置接受参数。376 * `/model`、`/effort`、`/fast`、`/color` 和 `/rename`：将值作为参数传递，例如 `/model sonnet` 或 `/effort high`。从移动和网络，`/model` 和 `/effort` 将参数用于代替终端选择器或滑块。

372 * `/mcp`：从移动应用，返回服务器状态的文本摘要而不是打开选择器。在网络上，`/mcp` 单独打开 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) 的目录而不是返回摘要。`reconnect`、`enable` 和 `disable` [子命令](/docs/zh-CN/commands#all-commands)可从两者工作。与本地 CLI 不同，不带服务器名称的 `/mcp reconnect` 会重新连接每个已失败或需要身份验证的服务器。377 * `/mcp`：从移动应用，返回服务器状态的文本摘要而不是打开选择器。在网络上，`/mcp` 单独打开 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) 的目录而不是返回摘要。`reconnect`、`enable` 和 `disable` [子命令](/docs/zh-CN/commands#all-commands)可从两者工作。与本地 CLI 不同，`/mcp reconnect` 不带服务器名称会重新连接每个已失败或需要身份验证的服务器。

373 * `/config`：从移动应用，传递 `key=value` 以设置一个设置，或不带参数运行它以列出您可以设置的键。在网络上，`/config` 打开您设置的 Claude Code 部分，并忽略命令后的文本。378 * `/config`：从移动应用，传递 `key=value` 以设置设置，或不带参数运行它以列出你可以设置的键。在网络上，`/config` 打开你的设置的 Claude Code 部分，并忽略命令后的文本。

374 * 在 Team 和 Enterprise 上，从移动或网络运行的 `/usage-credits` 不会向您的管理员发送[使用额度请求](/docs/zh-CN/costs#add-usage-credits-to-your-subscription)。发送需要仅在交互式 CLI 中出现的确认，因此命令告诉您改为在那里运行它。在 v2.1.211 之前，文本形式在没有确认的情况下发送请求。379 * 在 Team 和 Enterprise 上，从移动或网络的 `/usage-credits` 不会向你的管理员发送[使用额度请求](/docs/zh-CN/costs#add-usage-credits-to-your-subscription)。发送需要仅在交互式 CLI 中出现的确认，因此命令告诉你改为在那里运行它。

375 * `/autocompact`，从 v2.1.221 开始：将窗口大小作为参数传递，例如 `/autocompact 500k`。不带参数时，它将当前窗口大小打印为文本，而不是打开命令在终端会话中显示的对话框。380 * `/autocompact`，从 v2.1.221：将窗口大小作为参数传递，例如 `/autocompact 500k`。不带参数，它打印当前窗口大小作为文本，而不是打开命令在终端会话中显示的对话。

376 * `/advisor`，从 v2.1.260 开始：将模型作为参数传递，例如 `/advisor opus`，或传递 `off` 以关闭顾问。两种形式都仅适用于当前会话，并保持您保存的默认值不变。不带参数时，它将当前顾问打印为文本，而不是打开选择器。381 * `/advisor`，从 v2.1.260：将模型作为参数传递，例如 `/advisor opus`，或传递 `off` 以关闭顾问。两种形式仅适用于当前会话，并保持你保存的默认值不变。不带参数，它打印当前顾问作为文本，而不是打开选择器。

377 * `/output-style`，从 v2.1.269 开始：将样式名称作为参数传递，例如 `/output-style concise`，或不带参数运行它以列出样式。从移动和网络，您只能列出和选择[内置样式](/docs/zh-CN/output-styles#built-in-output-styles)。要使用[自定义样式](/docs/zh-CN/output-styles#create-a-custom-output-style)，请在会话本身中选择它。382 * `/output-style`，从 v2.1.269：将样式名称作为参数传递，例如 `/output-style concise`，或不带参数运行它以列出样式。从移动和网络，你只能列出和选择[内置样式](/docs/zh-CN/output-styles#built-in-output-styles)。要使用[自定义样式](/docs/zh-CN/output-styles#create-a-custom-output-style)，在会话本身中选择它。

383 * `/focus`，从 v2.1.281：将 `on` 或 `off` 作为参数传递，例如 `/focus on`，或不带参数运行它以切换[焦点视图](/docs/zh-CN/commands#all-commands)。两种形式仅适用于当前会话，并保持你保存的选择不变。

378 384

379<h2 id="troubleshooting">385<h2 id="troubleshooting">

380 故障排除386 故障排除

384 "Remote Control requires a claude.ai subscription"390 "Remote Control requires a claude.ai subscription"

385</h3>391</h3>

386 392

387您未使用 claude.ai 账户登录，或者另一个凭证优先于您的登录。该消息采用以下形式之一：393您未使用 claude.ai 账户登录，或者其他凭证优先于您的登录。该消息采用以下形式之一：

388 394

389* 已登出，来自 `/remote-control` 或 `--remote-control`：`Remote Control requires a claude.ai subscription.` 或 `/remote-control requires a claude.ai subscription.`395* 已登出，来自 `/remote-control` 或 `--remote-control`：`Remote Control requires a claude.ai subscription.` 或 `/remote-control requires a claude.ai subscription.`

390* 已登出，来自 `claude remote-control`：`You must be logged in to use Remote Control. Remote Control is only available with claude.ai subscriptions.`396* 已登出，来自 `claude remote-control`：`You must be logged in to use Remote Control. Remote Control is only available with claude.ai subscriptions.`

391* 已登入，但正在使用 API 密钥或令牌：`Remote Control requires claude.ai subscription auth.` 后跟正在使用的凭证，例如 `ANTHROPIC_API_KEY is set, so this session is using API-key auth`。`apiKeyHelper` 设置和 `ANTHROPIC_AUTH_TOKEN` 的命名方式相同。397* 已登入，但正在使用 API 密钥或令牌：`Remote Control requires claude.ai subscription auth.` 后跟正在使用的凭证，例如 `ANTHROPIC_API_KEY is set, so this session is using API-key auth`。`apiKeyHelper` 设置和 `ANTHROPIC_AUTH_TOKEN` 的命名方式相同。

392 398

393运行 `claude auth login` 并选择 claude.ai 选项。如果消息中提到 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，请在设置它的任何地方删除它：您的 shell 环境或[设置文件](/docs/zh-CN/settings-reference#env)的 `env` 块。如果消息中提到 `apiKeyHelper`，请删除该设置。399运行 `claude auth login` 并选择 claude.ai 选项。如果消息中提到 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，请在设置它的任何地方删除它：您的 shell 环境或[设置文件](/docs/zh-CN/settings-reference#env)的 `env` 块。如果提到 `apiKeyHelper`，请删除该设置。

~~394~~

395在 v2.1.206 之前，在已登出时运行 `/remote-control` 会报告 `Unknown command: /remote-control` 而不是此消息。

396 400

397<h3 id="remote-control-requires-a-full-scope-login-token">401<h3 id="remote-control-requires-a-full-scope-login-token">

398 "Remote Control requires a full-scope login token"402 "Remote Control requires a full-scope login token"

399</h3>403</h3>

400 404

401您使用的是来自 `claude setup-token` 或 `CLAUDE_CODE_OAUTH_TOKEN` 环境变量的长期令牌进行身份验证。这些令牌只能发出模型请求，因此无法建立 Remote Control 会话。运行 `claude auth login` 以改用完整范围的会话令牌进行身份验证。405您使用来自 `claude setup-token` 或 `CLAUDE_CODE_OAUTH_TOKEN` 环境变量的长期令牌进行了身份验证。这些令牌只能发出模型请求，因此无法建立 Remote Control 会话。运行 `claude auth login` 以改用完整范围的会话令牌进行身份验证。

402 406

403<h3 id="unable-to-determine-your-organization-for-remote-control-eligibility">407<h3 id="unable-to-determine-your-organization-for-remote-control-eligibility">

404 "Unable to determine your organization for Remote Control eligibility"408 "Unable to determine your organization for Remote Control eligibility"

414 418

415运行 `claude doctor` 以查看哪个单独的资格检查失败。环境变量冲突、无法访问的检查和您的组织的 Remote Control 设置各自产生自己的消息，因此此错误意味着账户级别的检查本身。419运行 `claude doctor` 以查看哪个单独的资格检查失败。环境变量冲突、无法访问的检查和您的组织的 Remote Control 设置各自产生自己的消息，因此此错误意味着账户级别的检查本身。

416 420

417在 v2.1.239 之前，此消息读作"Remote Control is not yet enabled for your account"。在 v2.1.154 之前，禁用功能标志评估的变量（例如 `DISABLE_TELEMETRY` 或 `DO_NOT_TRACK`）也会产生此消息；下面的"Remote Control requires feature-flag evaluation"条目涵盖该配置。421在 v2.1.239 之前，此消息读作"Remote Control is not yet enabled for your account"。

418 422

419<h3 id="couldn’t-verify-remote-control-eligibility">423<h3 id="couldn’t-verify-remote-control-eligibility">

420 "Couldn't verify Remote Control eligibility"424 "Couldn't verify Remote Control eligibility"

421</h3>425</h3>

422 426

423Claude Code 无法访问功能标志服务以检查您的账户是否启用了 Remote Control，通常是因为您离线或代理阻止了请求。一旦您有网络访问权限，请重试，或运行 `claude doctor` 以获取详细信息。相关消息"Couldn't verify your organization's Remote Control policy"意味着 Claude Code 无法读取该策略，具有相同的修复。这两条消息都在 v2.1.178 中添加。427Claude Code 无法访问功能标志服务来检查是否为您的账户启用了 Remote Control，通常是因为您离线或代理阻止了请求。一旦您有网络访问权限，请重试，或运行 `claude doctor` 以获取详细信息。相关消息"Couldn't verify your organization's Remote Control policy"意味着 Claude Code 在读取该策略时遇到错误，具有相同的修复方法。

424 428

425<h3 id="remote-control-requires-feature-flag-evaluation">429<h3 id="remote-control-requires-feature-flag-evaluation">

426 "Remote Control requires feature-flag evaluation"430 "Remote Control requires feature-flag evaluation"

427</h3>431</h3>

428 432

429设置了以下变量之一：[`DISABLE_TELEMETRY`、`DO_NOT_TRACK`、`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 或 `DISABLE_GROWTHBOOK`](/docs/zh-CN/env-vars)。每个变量都禁用 Remote Control 可用性所依赖的功能标志评估，完整消息会命名 Claude Code 找到的变量。在设置它的任何地方取消设置该变量，在您的 shell 环境中或在 [`settings.json` 文件](/docs/zh-CN/settings-reference#all-settings)的 `env` 块中。在 2.1.154 之前的版本上，相同的配置会产生"Remote Control is not yet enabled for your account"。433设置了[环境变量](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)来关闭功能标志评估，完整消息命名了 Claude Code 找到的变量。在 2.1.154 之前的版本上，相同的配置会产生"Remote Control is not yet enabled for your account"。要做什么取决于消息命名的变量：

434

435* **`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 或 `DISABLE_GROWTHBOOK`**：在设置它的任何地方取消设置变量，在您的 shell 环境或[`settings.json` 文件](/docs/zh-CN/settings-reference#all-settings)的 `env` 块中。

436* **`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK`**：在 Pro、Max、Team 或 Enterprise 计划上，且 `DISABLE_GROWTHBOOK` 未设置，这些变量会保留 Remote Control 可用，除非您的组织需要[可信设备](#trusted-devices)。如果需要，在设置它的任何地方取消设置变量以使用 Remote Control。从 v2.1.154 到 v2.1.282，任一变量都会产生此消息，因此请将 Claude Code 更新到 v2.1.283 或更高版本。

430 437

431<h3 id="remote-control-is-only-available-when-using-claude-via-api-anthropic-com">438<h3 id="remote-control-is-only-available-when-using-claude-via-api-anthropic-com">

432 "Remote Control is only available when using Claude via api.anthropic.com"439 "Remote Control is only available when using Claude via api.anthropic.com"

433</h3>440</h3>

434 441

435该会话不是直接与 Anthropic API 通信，因此没有 claude.ai 后端可配对。这发生在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上。当 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 指向 `api.anthropic.com` 以外的主机时，例如 [LLM 网关](/docs/zh-CN/llm-gateway)或代理，即使您使用 claude.ai 登录，也会发生这种情况。在 v2.1.196 之前，Claude Code 对于自定义 `ANTHROPIC_BASE_URL` 不显示此消息。有关完整原因列表，请参阅[错误参考](/docs/zh-CN/errors#remote-control-requires-the-anthropic-api)。442会话不是直接与 Anthropic API 通信，Remote Control 需要这样做。这发生在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上。当 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 指向 `api.anthropic.com` 以外的主机时，例如 [LLM 网关](/docs/zh-CN/llm-gateway)或代理，即使您使用 claude.ai 登录，也会发生这种情况。有关完整原因列表，请参阅[错误参考](/docs/zh-CN/errors#remote-control-requires-the-anthropic-api)。

436 443

437该消息命名了将会话路由离开 Anthropic API 的内容，例如 `CLAUDE_CODE_USE_BEDROCK` 或自定义 `ANTHROPIC_BASE_URL`。如果您有符合条件的 claude.ai 登录，请取消设置命名的变量，如果您在那里设置了它，请从[设置](/docs/zh-CN/settings)中的 `env` 键中删除它，然后重新启动会话。在 v2.1.219 之前，该消息仅是本节标题中的句子，因此在较旧的版本上，请自己检查环境中的提供商变量，例如 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_VERTEX`，以及 `ANTHROPIC_BASE_URL`。444消息命名了将会话路由离开 Anthropic API 的内容，例如 `CLAUDE_CODE_USE_BEDROCK` 或自定义 `ANTHROPIC_BASE_URL`。如果您有符合条件的 claude.ai 登录，请取消设置命名的变量，如果您在[设置](/docs/zh-CN/settings)中设置了它，请从 `env` 密钥中删除它，然后重新启动会话。

438 445

439<h3 id="remote-control-is-disabled-by-your-organization’s-policy">446<h3 id="remote-control-is-disabled-by-your-organization’s-policy">

440 "Remote Control is disabled by your organization's policy"447 "Remote Control is disabled by your organization's policy"

441</h3>448</h3>

442 449

443策略阻止了 Remote Control，或者 Claude Code 无法在此机器上加载您的组织策略，同时保持 Remote Control 关闭。按顺序检查这些原因：450策略阻止了 Remote Control。按顺序检查这些原因：

444 451

445* **错误提到 `disableRemoteControl`**：您的 IT 管理员已通过[托管设置](/docs/zh-CN/managed-settings)在此设备上禁用了 Remote Control，独立于组织范围的切换和您的登录方式。452* **错误提到 `disableRemoteControl`**：您的 IT 管理员已通过[托管设置](/docs/zh-CN/managed-settings)在此设备上禁用了 Remote Control，独立于组织范围的切换和您的登录方式。

446* **您的 claude.ai 计划是 Pro 或 Max**：Claude Code 仍然以来自较早登录的 Team 或 Enterprise 组织身份登录，因此它检查该组织的 Remote Control 策略。运行 `/status` 以查看您的登录使用的计划和组织。运行 `claude auth logout` 然后 `claude auth login` 以在您当前的计划下重新登录。453* **您的 claude.ai 计划是 Pro 或 Max**：Claude Code 仍然以来自较早登录的 Team 或 Enterprise 组织身份登录，因此它检查该组织的 Remote Control 策略。运行 `/status` 以查看您的登录使用的计划和组织。运行 `claude auth logout` 然后 `claude auth login` 以在您当前的计划下重新登录。

447* **组织策略未在此机器上加载**：运行 `claude doctor` 并读取 `Organization policy` 行。如果该行显示策略未加载，那就是保持 Remote Control 关闭的原因。在 v2.1.261 之前，`claude doctor` 不打印此行。454* **消息未说联系您的组织管理员**：您的组织具有与 Remote Control 不兼容的 HIPAA 配置，`/status` 在其 `Compliance` 行中列出 `HIPAA`。在此状态下，管理面板的 Remote Control 切换呈灰显状态，因此所有者无法在那里更改它。联系 Anthropic 支持以讨论选项。在 v2.1.267 之前，此情况显示"Remote Control isn't available for your organization due to its compliance policy"。

448* **消息未说联系您的组织管理员**：您的组织具有与 Remote Control 不兼容的 HIPAA 配置，`/status` 在其 `Compliance` 行中列出 `HIPAA`。在此状态下，管理面板的 Remote Control 切换呈灰显状态，因此 Owner 无法在那里更改它。联系 Anthropic 支持以讨论选项。在 v2.1.267 之前，此情况显示"Remote Control isn't available for your organization due to its compliance policy"。455* **否则，所有者尚未为您的组织启用它**：Remote Control 在 Team 和 Enterprise 计划上默认关闭。所有者可以在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 通过打开 **Remote Control** 切换来启用它。此切换是服务器端组织设置。

449* **否则，Owner 尚未为您的组织启用它**：Remote Control 在 Team 和 Enterprise 计划上默认关闭。Owner 可以在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 通过打开 **Remote Control** 切换来启用它。此切换是服务器端组织设置。456

457在 v2.1.281 之前，当 Claude Code 未在此计算机上加载您的组织策略时，此消息也会出现，例如在离线启动后。更高版本将该状态报告为[`Couldn't verify your organization's policy for remote control`](#couldnt-verify-your-organizations-policy-for-remote-control)。

458

459<h3 id="couldnt-verify-your-organizations-policy-for-remote-control">

460 "Couldn't verify your organization's policy for remote control"

461</h3>

462

463Claude Code 无法获取您的组织策略，并且此计算机上没有保存的副本可供使用，因此它会保持 Remote Control 关闭，直到它可以确认您的组织允许它。这通常发生在您离线启动 Claude Code 或在 VPN 连接之前，或当代理干扰请求时。在慢速连接上，当第一个请求仍在进行中时，它也可能出现。

464

465消息采用以下形式之一：

466

467* 来自 `/remote-control`、`claude remote-control` 或 `claude --remote-control`：`Couldn't verify your organization's policy for remote control. Check your network connection and try again.`

468* 来自[自动连接](#enable-remote-control-for-all-sessions)当会话启动时：`couldn't verify your organization's policy — check your network connection and try again`，在通知中以 `Remote Control failed` 为前缀，在对话中以 `Remote Control disconnected` 为前缀。会话随后保持 Remote Control 关闭。

469

470恢复您的网络连接，然后运行 `/remote-control` 或再次运行该命令。每次尝试都会再次检查策略，因此您无需重新启动 Claude Code。如果消息继续出现，请运行 `claude doctor` 并阅读其 `Organization policy` 行，该行说明策略未加载的原因。

471

472在 v2.1.281 之前，此状态显示 `Remote Control is disabled by your organization's policy`。

450 473

451<h3 id="remote-credentials-fetch-failed">474<h3 id="remote-credentials-fetch-failed">

452 "Remote credentials fetch failed"475 "Remote credentials fetch failed"

453</h3>476</h3>

454 477

455Claude Code 无法从 Anthropic API 获取短期凭证以建立连接。使用 `--verbose` 重新运行以查看完整错误：478Claude Code 无法从 Anthropic API 获取短期凭证来建立连接。使用 `--verbose` 重新运行以查看完整错误：

456 479

457```bash theme={null}480```bash theme={null}

458claude remote-control --verbose481claude remote-control --verbose

464* 网络或代理问题：防火墙或代理可能阻止了出站 HTTPS 请求。Remote Control 需要访问端口 443 上的 Anthropic API。487* 网络或代理问题：防火墙或代理可能阻止了出站 HTTPS 请求。Remote Control 需要访问端口 443 上的 Anthropic API。

465* 会话创建失败：如果您还看到 `Session creation failed — see debug log`，失败发生在设置的早期。检查您的订阅是否有效。488* 会话创建失败：如果您还看到 `Session creation failed — see debug log`，失败发生在设置的早期。检查您的订阅是否有效。

466 489

467过期的登录令牌不会导致此错误。当 Anthropic API 拒绝保存的令牌时，例如因为另一个 Claude Code 进程已经刷新了它，Claude Code 会刷新令牌并自动重试。在 v2.1.224 之前，过期的令牌会导致 Remote Control 启动失败并显示此消息，因此设置为[自动连接](#enable-remote-control-for-all-sessions)的会话可能在启动时间歇性失败。490<h3 id="couldnt-reconnect-to-your-remote-control-session">

~~468~~

469<h3 id="couldn’t-reconnect-to-your-remote-control-session">

470 "Couldn't reconnect to your Remote Control session"491 "Couldn't reconnect to your Remote Control session"

471</h3>492</h3>

472 493

473当您使用 `claude --resume` 或 `claude --continue` 恢复对话时，Claude Code 会重新连接到该对话中记录的 Remote Control 会话。此消息意味着重新连接因可能是临时的原因（例如网络中断或服务器错误）而失败，因此 Claude Code 无法确认远程会话是否仍然存在。494当您使用 `claude --resume` 或 `claude --continue` 恢复对话时，Claude Code 会重新连接到该对话中记录的 Remote Control 会话。此消息意味着重新连接因可能是临时的原因（例如网络中断或服务器错误）而失败，因此 Claude Code 无法确认远程会话是否仍然存在。

474 495

475运行 `/remote-control` 以重试连接，或使用 `claude --remote-control` 启动新会话以创建新的 Remote Control 会话。您的本地会话同时继续运行而不使用 Remote Control。496运行 `/remote-control` 以重试连接，或使用 `claude --remote-control` 启动新会话以创建新的 Remote Control 会话。您的本地会话在此期间继续运行而不使用 Remote Control。

~~476~~

477<span id="resume-outcomes" />恢复时，您也可以获得以下结果之一而不是此消息：

~~478~~

479* **服务器报告记录的会话已消失，或重新连接记录命名不同的账户**：Claude Code 遵循对话的重新连接记录所说的内容：

480 * **记录命名您登录的账户**：Claude Code 使用自动生成的名称启动替换会话，并将对话的早期消息排除在外。例如，在您从 claude.ai 或 Claude 应用中删除会话后，您会看到这种情况。

481 * **记录命名不同的账户**：Claude Code 启动新会话而不包含对话的早期消息，无论记录的会话是否仍然存在，都不显示消息。

482 * **记录未说明哪个账户拥有会话，或 Claude Code 无法读取您保存的登录**：Claude Code 显示 [`Previous session is unavailable — run /remote-control to start a new one`](#previous-session-is-unavailable) 而不是此消息，不启动任何内容，并从对话中删除记录。

483* **您在恢复前关闭了 Remote Control**：除非托管 Claude Code 的应用已告诉它该应用拥有 claude.ai 会话，否则当您从 CLI 的[状态面板](#check-connection-status)、VS Code 扩展或基于[Agent SDK](/docs/zh-CN/agent-sdk/overview)构建的主机关闭 Remote Control 时，Claude Code 删除了重新连接记录，因此它不会重新连接。当拥有的应用关闭它时，Claude Code 保留记录并重新连接。

484* **此机器上的另一个 Claude Code 仍然拥有该会话**：您会看到一条以 `Remote Control not started here` 开头的通知，Claude Code [在恢复的会话中保持 Remote Control 关闭](#resume-sessions-after-stopping-the-server)。在那里运行 `/remote-control` 以移动它。

~~485~~

486<span id="reconnect-history" />在 v2.1.232 之前，当服务器报告记录的会话已消失时，Claude Code 的响应不同。从 v2.1.227 到 v2.1.231，Claude Code 拒绝启动替换，即使记录与您的账户匹配。到 v2.1.226，Claude Code 启动替换，无论记录是否与您的账户匹配，在 v2.1.224 到 v2.1.226 中，它在该机器上登录的账户下创建它，从不是另一个账户的，不上传对话的早期消息到它。在 v2.1.200 之前，Claude Code 在任何重新连接失败后创建新会话。

487 497

488<h3 id="previous-session-is-unavailable">498<h3 id="previous-session-is-unavailable">

489 "Previous session is unavailable — run /remote-control to start a new one"499 "Previous session is unavailable — run /remote-control to start a new one"

490</h3>500</h3>

491 501

492Claude Code 无法恢复之前的 Remote Control 会话，而是停止而不是自动启动新会话。在使用 `claude --resume` 或 `claude --continue` 恢复对话后，或在 Claude Code [在断开连接后自动重新连接](/docs/zh-CN/errors#remote-control-couldnt-refresh-your-login)后，您可能会看到此消息。502Claude Code 无法恢复之前的 Remote Control 会话，而是停止了，而不是自动启动新会话。您可以在使用 `claude --resume` 或 `claude --continue` 恢复对话后看到此消息，或在 Claude Code [在断开连接后自动重新连接](/docs/zh-CN/errors#remote-control-couldnt-refresh-your-login)后看到此消息。

493 503

494运行 `/remote-control` 以在当前登录下启动新的 Remote Control 会话；您的本地会话同时继续运行而不使用 Remote Control。相关消息 `Remote Control could not verify the signed-in account — run /remote-control to reconnect` 具有相同的修复；当登录账户在验证和重新连接之间更改或无法读取时，Claude Code 显示它。如果您在不首先重新启动 Claude Code 的情况下在 `Previous session is unavailable` 后运行 `/remote-control`，Claude Code 会将对话的早期消息排除在新会话之外。504运行 `/remote-control` 以在当前登录下启动新的 Remote Control 会话；您的本地会话在此期间继续运行而不使用 Remote Control。相关消息 `Remote Control could not verify the signed-in account — run /remote-control to reconnect` 具有相同的修复方法。如果您在 `Previous session is unavailable` 之后运行 `/remote-control` 而不首先重新启动 Claude Code，Claude Code 会将对话的早期消息排除在新会话之外。

~~495~~

496在恢复时，Claude Code [仅在对话的重新连接记录命名拥有会话的账户时才启动替换会话](#resume-outcomes)，因为服务器以相同的方式报告您删除的会话和由另一个账户拥有的会话。v2.1.227 之前的 Claude Code 没有记录该账户，当 Claude Code 无法读取您保存的登录时，它无法检查记录。v2.1.232 之前的 Claude Code 显示 `Remote Control could not resume the previous session under the current login — run /remote-control to start fresh` 而不是，在[不同的情况集](#reconnect-history)中。

497 505

498<h3 id="remote-control-got-an-unexpected-server-response">506<h3 id="remote-control-got-an-unexpected-server-response">

499 "Remote Control got an unexpected server response"507 "Remote Control got an unexpected server response"

500</h3>508</h3>

501 509

502Remote Control 服务器接受了请求但以此版本的 Claude Code 无法读取的形式回复，同时创建远程会话或获取其凭证。在同一版本上重试会以相同方式失败。运行 `claude update`，然后运行 `/remote-control` 以重新连接。此消息在 v2.1.225 中添加。510Remote Control 服务器接受了请求但以此版本的 Claude Code 无法读取的形式回复，同时创建远程会话或获取其凭证。在同一版本上重试会以相同方式失败。运行 `claude update`，然后运行 `/remote-control` 以重新连接。

503 511

504<h3 id="your-organization-requires-trusted-devices-for-remote-control-but-this-device-is-not-enrolled">512<h3 id="your-organization-requires-trusted-devices-for-remote-control-but-this-device-is-not-enrolled">

505 "Your organization requires Trusted Devices for Remote Control, but this device is not enrolled"513 "Your organization requires Trusted Devices for Remote Control, but this device is not enrolled"

506</h3>514</h3>

507 515

508您的组织已启用[Trusted Devices](#trusted-devices)，此机器尚未注册。在 Claude Code 中运行 `/login`。注册作为登录的一部分进行，没有单独的注册命令。516您的组织已启用[可信设备](#trusted-devices)，此计算机尚未注册。在 Claude Code 中运行 `/login`。注册作为登录的一部分进行，没有单独的注册命令。

509 517

510<h3 id="session-expired-for-trusted-device-check">518<h3 id="session-expired-for-trusted-device-check">

511 "session expired for trusted-device check"519 "session expired for trusted-device check"

512</h3>520</h3>

513 521

514您的登录已超过 18 小时。在 Claude Code 中运行 `/login`，或当 claude.ai 或移动应用提示您时，使用 Face ID、Touch ID、Windows Hello 或通行密钥进行确认。请参阅 [Trusted Devices](#trusted-devices)。522您的登录已超过 18 小时。在 Claude Code 中运行 `/login`，或在 claude.ai 或移动应用提示您时使用 Face ID、Touch ID、Windows Hello 或通行密钥进行确认。请参阅[可信设备](#trusted-devices)。

~~515~~

516<h2 id="choose-the-right-approach">

517 选择正确的方法

518</h2>

~~519~~

520Claude Code 提供了多种方式在您不在终端时进行工作。它们在触发工作的方式、Claude 运行的位置以及所需的设置量方面有所不同。

~~521~~

522| | 触发方式 | Claude 运行位置 | 设置 | 最适合 |

523| :- | :- | :- | :- | :- |

530 523

531<h2 id="related-resources">524<h2 id="related-resources">

532 相关资源525 相关资源

routines.md +3 −2

Details

59当例程的计划或 **Run now** 启动运行时，Claude 仅在以下所有条件都成立时才会重新发布现有 artifact，无需询问：59当例程的计划或 **Run now** 启动运行时，Claude 仅在以下所有条件都成立时才会重新发布现有 artifact，无需询问：

60 60

61* 您可以编辑 artifact，它属于您自己的组织61* 您可以编辑 artifact，它属于您自己的组织

~~62* artifact 不是公开共享的，也不是与特定人员或您的组织共享的，最新版本被选为查看者看到的版本~~62* artifact 不是公开共享的

63* 如果 artifact 与特定人员或您的组织共享，其查看者不会自动看到每个新版本

63* 发布仅包含页面，没有支持文件或任何其他添加的内容，并且不会强制覆盖较新版本64* 发布仅包含页面，没有支持文件或任何其他添加的内容，并且不会强制覆盖较新版本

64* 页面不包含超出页面范围的授权，例如 [connector calls](/docs/zh-CN/artifacts#pull-live-data-with-mcp-connectors)65* 页面不包含超出页面范围的授权，例如 [connector calls](/docs/zh-CN/artifacts#pull-live-data-with-mcp-connectors)

65 66

151 152

152计划触发器按定期节奏运行例程，或在特定的未来时间运行一次。在 **Select a trigger** 部分中选择预设频率：每小时、每天、工作日或每周。时间以您的本地时区输入并自动转换，因此例程在该挂钟时间运行，无论云基础设施位于何处。153计划触发器按定期节奏运行例程，或在特定的未来时间运行一次。在 **Select a trigger** 部分中选择预设频率：每小时、每天、工作日或每周。时间以您的本地时区输入并自动转换，因此例程在该挂钟时间运行，无论云基础设施位于何处。

153 154

154运行可能在计划时间后几分钟开始，原因是交错。每个例程的偏移是一致的。155如果您在整点时刻（例如 9:00）安排运行，它可能会晚几分钟开始。要在接近计划时间时开始，请选择整点后的几分钟，例如 9:07。

155 156

156对于自定义间隔（如每两小时或每月的第一天），在表单中选择最接近的预设，然后在 CLI 中运行 `/schedule update` 以设置特定的 cron 表达式。最小间隔是一小时；运行频率更高的表达式被拒绝。157对于自定义间隔（如每两小时或每月的第一天），在表单中选择最接近的预设，然后在 CLI 中运行 `/schedule update` 以设置特定的 cron 表达式。最小间隔是一小时；运行频率更高的表达式被拒绝。

157 158

sandbox-environments.md +1 −1

Details

117在 Linux 和 WSL2 上，运行时仅对已存在的路径应用写入授权。在全新环境中，在首次启动前创建 Claude Code 的配置路径：117在 Linux 和 WSL2 上，运行时仅对已存在的路径应用写入授权。在全新环境中，在首次启动前创建 Claude Code 的配置路径：

118 118

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

120mkdir -p ~/.claude && echo '{}' > ~/.claude.json120mkdir -p ~/.claude && { [ -f ~/.claude.json ] || echo '{}' > ~/.claude.json; }

121```121```

122 122

123配置文件就位后，使用 `npx` 启动 Claude Code 并传递 `claude` 作为要包装的命令：123配置文件就位后，使用 `npx` 启动 Claude Code 并传递 `claude` 作为要包装的命令：

sandboxing.md +1 −1

Details

42 </Step>42 </Step>

43 43

44 <Step title="运行 Bash 命令">44 <Step title="运行 Bash 命令">

45 要求 Claude 运行一个命令，例如构建或测试套件。默认情况下，沙箱内的命令可以写入工作目录、会话临时目录以及任何你用 `--add-dir`、`/add-dir` 或 `permissions.additionalDirectories` [添加的目录](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)。45 要求 Claude 运行一个命令，例如构建或测试套件。默认情况下，沙箱内的命令可以写入工作目录、[每用户临时目录](/docs/zh-CN/env-vars) 以及任何你用 `--add-dir`、`/add-dir` 或 `permissions.additionalDirectories` [添加的目录](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)。

46 46

47 命令第一次需要新的网络域时，Claude Code 会提示批准；在 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 中，Claude 改为在 [命令本身上命名](#per-command-allowed-domains-in-auto-mode) 命令需要的主机供分类器与其一起审查。47 命令第一次需要新的网络域时，Claude Code 会提示批准；在 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 中，Claude 改为在 [命令本身上命名](#per-command-allowed-domains-in-auto-mode) 命令需要的主机供分类器与其一起审查。

48 48

security.md +2 −1

Details

126 126

127* **隔离的虚拟机**：每个云会话在隔离的、由 Anthropic 管理的 VM 中运行127* **隔离的虚拟机**：每个云会话在隔离的、由 Anthropic 管理的 VM 中运行

128* **网络访问控制**：网络访问默认受限，可以配置为禁用或仅允许特定域128* **网络访问控制**：网络访问默认受限，可以配置为禁用或仅允许特定域

129* **凭证保护**：身份验证通过安全代理处理，该代理在沙箱内使用作用域凭证，然后转换为您的实际 GitHub 身份验证令牌129* **凭证保护**：GitHub 凭证在 Anthropic 的服务器上以加密方式存储，永远不会进入会话 VM。VM 持有一个作用域限制于该会话的短期凭证，GitHub 流量通过 [Anthropic proxy](/docs/zh-CN/cloud-environments#github-proxy) 进行，该代理在服务器端附加 GitHub 凭证。有关如何授予访问权限，请参阅 [GitHub authentication options](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)

130* **分支限制**：Git push 操作限制在当前工作分支130* **分支限制**：Git push 操作限制在当前工作分支

131* **审计日志**：云会话中的所有操作都被记录以用于合规和审计目的131* **审计日志**：云会话中的所有操作都被记录以用于合规和审计目的

132* **自动清理**：会话 VM 在一段时间不活动后被回收132* **自动清理**：会话 VM 在一段时间不活动后被回收

133* **删除**：您可以随时 [delete a session](/docs/zh-CN/claude-code-on-the-web#delete-sessions)。有关 Anthropic 为云会话存储的内容，请参阅 [Cloud execution data flow](/docs/zh-CN/data-usage#cloud-execution-data-flow-and-dependencies)

133 134

134有关云执行的更多详情，请参阅 [Use Claude Code in the cloud](/docs/zh-CN/claude-code-on-the-web)；要为云会话配置网络访问，请参阅 [Configure cloud environments](/docs/zh-CN/cloud-environments#network-access)。135有关云执行的更多详情，请参阅 [Use Claude Code in the cloud](/docs/zh-CN/claude-code-on-the-web)；要为云会话配置网络访问，请参阅 [Configure cloud environments](/docs/zh-CN/cloud-environments#network-access)。

135 136

self-hosted-environments-deploy.md +6 −2

Details

220ENTRYPOINT ["claude"]220ENTRYPOINT ["claude"]

221```221```

222 222

223如果您的节点是 ARM，将 `linux-x64` 交换为 `linux-arm64`，或在 Alpine 等 musl 基础镜像上交换为 `linux-x64-musl` 或 `linux-arm64-musl`；请参阅 [Alpine Linux 设置](/docs/zh-CN/setup#alpine-linux-and-musl-based-distributions)了解 musl 镜像需要的额外包。URL 是标准 Claude Code 发布位置，因此您可以根据[二进制完整性和代码签名](/docs/zh-CN/setup#binary-integrity-and-code-signing)中描述的发布的已签名清单验证下载的二进制文件。使用 Claude Code 版本 2.1.224 或更高版本构建镜像，然后将其推送到您的注册表并在下面的配方中引用它：223如果您的节点是 ARM，将 `linux-x64` 交换为 `linux-arm64`，或在 Alpine 等 musl 基础镜像上交换为 `linux-x64-musl` 或 `linux-arm64-musl`；请参阅 [Alpine Linux 设置](/docs/zh-CN/setup#alpine-linux-and-musl-based-distributions)了解 musl 镜像需要的额外包。URL 是标准 Claude Code 发布位置，因此您可以根据[二进制完整性和代码签名](/docs/zh-CN/setup#binary-integrity-and-code-signing)中描述的发布的已签名清单验证下载的二进制文件。运行器需要 Claude Code 版本 2.1.224 或更高版本。构建镜像，然后将其推送到您的注册表并在下面的配方中引用它：

224 224

225```bash theme={null}225```bash theme={null}

226docker build --build-arg CLAUDE_CODE_VERSION=2.1.267 -t <your-registry>/claude-runner:latest .226docker build \

227 --build-arg CLAUDE_CODE_VERSION="$(curl -fsSL https://downloads.claude.ai/claude-code-releases/stable)" \

228 -t <your-registry>/claude-runner:latest .

227```229```

228 230

231命令替换查找当前 `stable` 发布号并将其作为构建参数传递，因此在新的稳定版本发布后运行相同的命令会使用较新的二进制文件重建下载层。要为可重现的构建固定特定版本，请直接将版本号作为 `CLAUDE_CODE_VERSION` 传递。当您需要比稳定通道更新的版本（例如[新推出的模型所需的版本](/docs/zh-CN/model-config)）时，在查找 URL 中将 `stable` 替换为 `latest`。

232

229<h2 id="size-cpu-and-memory-for-sessions">233<h2 id="size-cpu-and-memory-for-sessions">

230 为会话调整 CPU 和内存大小234 为会话调整 CPU 和内存大小

231</h2>235</h2>

server-managed-settings.md +11 −2

Details

220 220

221服务器管理的传递添加了这些行为：221服务器管理的传递添加了这些行为：

222 222

223* 位于 `~/.claude/remote-settings.json` 的缓存存储已删除无效条目的已保存有效负载，除了无效的 `cleanupPeriodDays` 和 `desktopSessionCleanupPeriodDays` 值，它们保留在缓存副本中，永远不会被应用。223* 位于 `~/.claude/remote-settings.json` 的缓存上的启动会按照写入缓存的获取处理无效条目的方式处理它们：

224* 当有效负载中没有字段可以被保存，且有效负载不仅仅是那些保留键时，Claude Code 拒绝有效负载，保留最后接受的缓存设置，并将 `Remote settings: Settings validation failed - no fields could be salvaged` 写入调试日志。设置了 `forceRemoteSettingsRefresh` 时，CLI 会退出。224 * 未通过验证的条目保持被删除。

225 * [故障关闭的键](/docs/zh-CN/managed-settings#keys-that-fail-closed)保持其更严格的值。

226 * 无效的 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 值保留在缓存副本中，永远不会被应用。

227* 当以下三个条件都为真时，Claude Code 不应用有效负载中的任何内容，并保持缓存不变：

228

229 * 有效负载中的每个设置都未通过验证。

230 * 它们都不回退到更严格的值。

231 * 有效负载包含除这两个保留键之外的键。

232

233 启动通知、`/status` 和 `claude doctor` 然后报告[失败的加载](/docs/zh-CN/errors#remote-managed-settings-failed-to-load)，原因为 `no setting in the server response could be applied as written`，该条目说明会话运行的策略。[强制执行故障关闭启动](#enforce-fail-closed-startup)的客户端在启动时退出。

225* [安全批准对话框](#security-approval-dialogs)评估已保存的有效负载，因此被删除的无效条目永远不会被呈现以供批准，也永远不会执行。234* [安全批准对话框](#security-approval-dialogs)评估已保存的有效负载，因此被删除的无效条目永远不会被呈现以供批准，也永远不会执行。

226 235

227要调试传递问题，请运行 `claude --debug-file <path>` 并在日志中搜索 `Remote settings`。在向组织推出有效负载更改之前，使用 `claude doctor` 在测试机器上验证有效负载更改。236要调试传递问题，请运行 `claude --debug-file <path>` 并在日志中搜索 `Remote settings`。在向组织推出有效负载更改之前，使用 `claude doctor` 在测试机器上验证有效负载更改。

sessions.md +5 −4

Details

8 8

9会话是与项目目录关联的已保存对话。Claude Code 在您工作时将其本地存储，因此您可以从中断处恢复、分支以尝试不同的方法，或在任务之间切换。9会话是与项目目录关联的已保存对话。Claude Code 在您工作时将其本地存储，因此您可以从中断处恢复、分支以尝试不同的方法，或在任务之间切换。

10 10

11[桌面应用](/docs/zh-CN/desktop#work-in-parallel-with-sessions)、[网页版 Claude Code](/docs/zh-CN/claude-code-on-the-web) 和 [VS Code 扩展](/docs/zh-CN/vs-code#resume-past-conversations)各自维护自己的会话历史记录。本页涵盖 CLI。11[桌面应用](/docs/zh-CN/desktop#work-in-parallel-with-sessions)、[claude.ai/code](/docs/zh-CN/claude-code-on-the-web) 和 [VS Code 扩展](/docs/zh-CN/vs-code#resume-past-conversations)各自维护自己的会话列表，桌面应用还可以[恢复 CLI 会话](/docs/zh-CN/desktop#coming-from-the-cli)。本页涵盖 CLI。

12 12

13<h2 id="resume-a-session">13<h2 id="resume-a-session">

14 恢复会话14 恢复会话

43* 权限模式：如果您从终端使用 `claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（当名称与一个会话匹配时）恢复，不带 `-p`，Claude Code 会恢复会话所在的权限模式，除了[恢复时的权限模式](#permission-mode-on-resume)中的情况，这也涵盖会话选择器、`/resume` 和使用 `claude -p` 恢复。传递 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆盖恢复的模式。43* 权限模式：如果您从终端使用 `claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（当名称与一个会话匹配时）恢复，不带 `-p`，Claude Code 会恢复会话所在的权限模式，除了[恢复时的权限模式](#permission-mode-on-resume)中的情况，这也涵盖会话选择器、`/resume` 和使用 `claude -p` 恢复。传递 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆盖恢复的模式。

44* 活跃目标：会话结束时仍然活跃的[目标](/docs/zh-CN/goal#resume-with-an-active-goal)会继续；其轮次计数、计时器和令牌支出基线重置。44* 活跃目标：会话结束时仍然活跃的[目标](/docs/zh-CN/goal#resume-with-an-active-goal)会继续；其轮次计数、计时器和令牌支出基线重置。

45* 计划任务：[未过期的任务](/docs/zh-CN/scheduled-tasks#limitations)会被恢复。后台 Bash 和监视任务不会。45* 计划任务：[未过期的任务](/docs/zh-CN/scheduled-tasks#limitations)会被恢复。后台 Bash 和监视任务不会。

46* 后台工作：[后台子 agent](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)、后台 Bash 命令或[工作流](/docs/zh-CN/workflows)在上一个进程结束时未完成，会在恢复的文本记录中显示为未完成的注记。Claude Code 不会从这些注记启动轮次；Claude 会在您的下一个提示中读取它们。

46 47

47并非原始启动的每个配置标志都会被恢复。如果会话依赖于 `--mcp-config`、`--settings`、`--plugin-dir`、`--fallback-model` 或使用 `--add-dir` 添加的目录，在恢复时再次传递它们；使用 `/add-dir` 在会话中期添加的目录也不会被恢复，尽管会话选择器仍然使用它们来定位会话。标准设置文件（如 `settings.json` 和 `settings.local.json`）在启动时重新读取，因此驻留在其中的配置不需要再次传递。对于 `--system-prompt` 和 `--append-system-prompt`，请参阅[恢复对话中的系统提示标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。48并非原始启动的每个配置标志都会被恢复。如果会话依赖于 `--mcp-config`、`--settings`、`--plugin-dir`、`--fallback-model` 或使用 `--add-dir` 添加的目录，在恢复时再次传递它们；使用 `/add-dir` 在会话中期添加的目录也不会被恢复，尽管会话选择器仍然使用它们来定位会话。标准设置文件（如 `settings.json` 和 `settings.local.json`）在启动时重新读取，因此驻留在其中的配置不需要再次传递。对于 `--system-prompt` 和 `--append-system-prompt`，请参阅[恢复对话中的系统提示标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。

48 49

74 使用 `-p` 在计划模式中恢复75 使用 `-p` 在计划模式中恢复

75</h5>76</h5>

76 77

~~77`claude -p --resume` 或 `claude -p --continue` 运行仅在所有四个条件都成立时才在计划模式中恢复：~~78`claude -p --resume` 或 `claude -p --continue` 运行仅在所有这些条件都成立时才在计划模式中恢复：

78 79

~~79* 您传递 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags)，以便 Claude Code 可以呈现计划以供批准~~80* 您传递 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags)，不传递 [`--permission-prompts none`](/docs/zh-CN/headless#turn-off-permission-prompts-in-unattended-runs)，以便 Claude Code 可以呈现计划以供批准

80* 您不传递 `--permission-mode` 或 `--dangerously-skip-permissions`81* 您不传递 `--permission-mode` 或 `--dangerously-skip-permissions`

81* 您不传递 `--fork-session`82* 您不传递 `--fork-session`

82* 运行不是通过[频道](/docs/zh-CN/channels)启动的83* 运行不是通过[频道](/docs/zh-CN/channels)启动的

134| 从 claude.ai 或 Claude 应用 | 重命名 [Remote Control 会话](/docs/zh-CN/remote-control#connect-from-another-device)；Claude Code 在 CLI 中应用相同的名称。需要 Claude Code v2.1.221 或更高版本 |135| 从 claude.ai 或 Claude 应用 | 重命名 [Remote Control 会话](/docs/zh-CN/remote-control#connect-from-another-device)；Claude Code 在 CLI 中应用相同的名称。需要 Claude Code v2.1.221 或更高版本 |

135| 从桌面应用 | 在 [桌面应用](/docs/zh-CN/desktop#work-in-parallel-with-sessions) 中重命名会话 |136| 从桌面应用 | 在 [桌面应用](/docs/zh-CN/desktop#work-in-parallel-with-sessions) 中重命名会话 |

136 137

137通过 CLI 路由或从 claude.ai 命名会话后，使用 `claude --resume <name>` 或 `/resume <name>` 返回到它；桌面应用会话在应用中恢复，该应用保持自己的会话历史记录。有关名称解析如何跨 worktrees 工作的信息，请参阅[恢复会话](#resume-a-session)。138通过 CLI 路由或从 claude.ai 命名会话后，使用 `claude --resume <name>` 或 `/resume <name>` 返回到它；桌面应用会话在 [桌面应用](/docs/zh-CN/desktop#work-in-parallel-with-sessions) 中恢复。有关名称解析如何跨 worktrees 工作的信息，请参阅[恢复会话](#resume-a-session)。

138 139

139当您使用此计算机上另一个活跃会话已经使用的名称启动或恢复交互式会话，或将会话重命名为这样的名称时，Claude Code 会将该名称保留给已经拥有它的会话，将您的会话重命名为带有两个单词后缀的变体，例如 `auth-refactor-graceful-unicorn`，并告知您。如果您想自己选择一个名称，请使用新名称运行 `/rename`。在 v2.1.232 之前，两个会话都保留该名称。140当您使用此计算机上另一个活跃会话已经使用的名称启动或恢复交互式会话，或将会话重命名为这样的名称时，Claude Code 会将该名称保留给已经拥有它的会话，将您的会话重命名为带有两个单词后缀的变体，例如 `auth-refactor-graceful-unicorn`，并告知您。如果您想自己选择一个名称，请使用新名称运行 `/rename`。在 v2.1.232 之前，两个会话都保留该名称。

140 141

settings.md +1 −1

Details

809 809

810* **共享项目设置** (`.claude/settings.json`)：在一个存储库的会话中读取，因为该文件是克隆的一部分，会话在其中启动。在那里提交设置以在这些会话中应用它。具有多个存储库的会话在克隆上方启动，因此从每个存储库的 `.claude/settings.json` 仅读取 `enabledPlugins` 和 `extraKnownMarketplaces` 键，而不是权限规则、hooks、`env` 或其他键。这些两个键声明的市场和插件仍然[不在云会话中加载](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)。810* **共享项目设置** (`.claude/settings.json`)：在一个存储库的会话中读取，因为该文件是克隆的一部分，会话在其中启动。在那里提交设置以在这些会话中应用它。具有多个存储库的会话在克隆上方启动，因此从每个存储库的 `.claude/settings.json` 仅读取 `enabledPlugins` 和 `extraKnownMarketplaces` 键，而不是权限规则、hooks、`env` 或其他键。这些两个键声明的市场和插件仍然[不在云会话中加载](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)。

811* **用户和项目本地设置** (`~/.claude/settings.json` 和 `.claude/settings.local.json`)：不读取。两者都保持在您的机器上，本地文件不在克隆中。811* **用户和项目本地设置** (`~/.claude/settings.json` 和 `.claude/settings.local.json`)：不读取。两者都保持在您的机器上，本地文件不在克隆中。

812* **托管设置**：仅[服务器管理设置](/docs/zh-CN/server-managed-settings)到达云会话；您设备上的 `managed-settings.json` 文件或 MDM 配置文件不会。[自托管环境](/docs/zh-CN/self-hosted-environments)也读取其运行器镜像中的托管设置文件。[Claude Code 如何组合托管来源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说该文件何时适用。812* **托管设置**：您设备上的 `managed-settings.json` 文件或 MDM 配置文件不会到达云会话。您组织的[服务器管理设置](/docs/zh-CN/server-managed-settings)会；[表面覆盖](/docs/zh-CN/model-config#surface-coverage)列出哪些云会话接收它们。[自托管环境](/docs/zh-CN/self-hosted-environments)也读取其运行器镜像中的托管设置文件。[Claude Code 如何组合托管来源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说该文件何时适用。

813* **`/config`**：在您的浏览器中的 claude.ai/code，打开您的 claude.ai 设置的 Claude Code 部分而不是更改值。要为云会话更改设置，在环境上设置[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)，或在具有一个存储库的会话中，将键提交到该存储库的 `.claude/settings.json`。813* **`/config`**：在您的浏览器中的 claude.ai/code，打开您的 claude.ai 设置的 Claude Code 部分而不是更改值。要为云会话更改设置，在环境上设置[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)，或在具有一个存储库的会话中，将键提交到该存储库的 `.claude/settings.json`。

814 814

815[从您的设置中携带什么](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)列出其余的：`CLAUDE.md`、skills、MCP 服务器、plugins 和凭证。815[从您的设置中携带什么](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)列出其余的：`CLAUDE.md`、skills、MCP 服务器、plugins 和凭证。

settings-reference.md +349 −142

Details

835 843

836选择当 Claude 调用服务器端[顾问工具](/docs/zh-CN/advisor)时哪个模型来回答。取消设置它以关闭顾问。顾问的能力必须至少与您的主模型一样强。请参阅[选择顾问模型](/docs/zh-CN/advisor#choose-an-advisor-model)了解接受的配对以及选择未被接受的配对时会发生什么。844选择当 Claude 调用服务器端[顾问工具](/docs/zh-CN/advisor)时哪个模型来回答。取消设置它以关闭顾问。顾问的能力必须至少与您的主模型一样强。请参阅[选择顾问模型](/docs/zh-CN/advisor#choose-an-advisor-model)了解接受的配对以及选择未被接受的配对时会发生什么。

837 845

838您通常不会手动编辑此键。运行 `/advisor` 打开一个选择器，显示当前选择、可以提供建议的模型和**无顾问**。Claude Code 将您的选择保存到 `~/.claude/settings.json` 中的此键。如果您从[远程控制](/docs/zh-CN/remote-control)客户端或附加到远程工作者的会话中选择，该选择仅适用于该会话，不会更改此键。846您通常不会手动编辑此键。运行 `/advisor` 打开一个选择器，显示当前选择、可以提供建议的模型和**无顾问**。Claude Code 将您的选择保存到 `~/.claude/settings.json` 中的此键。如果您从[远程控制](/docs/zh-CN/remote-control)客户端或在附加到远程工作者的会话中选择，该选择仅适用于该会话，不会更改此键。

839 847

840如果您的账户需要[使用额度同意](/docs/zh-CN/advisor#fable-advisor-and-usage-credits)，请先通过运行 `/model fable` 来接受。在您这样做之前，在 `/advisor` 中选择 Fable 不会保存任何内容，Claude Code 会告诉您先运行 `/model fable`。848如果您的账户需要[使用额度同意](/docs/zh-CN/advisor#fable-advisor-and-usage-credits)，请先通过运行 `/model fable` 来接受它。在您这样做之前，在 `/advisor` 中选择 Fable 不会保存任何内容，Claude Code 会告诉您先运行 `/model fable`。

841 849

842* **Scope**: [`Any file`](#scopes)850* **Scope**: [`Any file`](#scopes)

843* **Type**: string，别名之一 `"fable"`、`"opus"` 或 `"sonnet"`，它们解析为 Claude Code 当前该模型系列的默认版本，或完整模型 ID，如 `"claude-opus-5-5"`851* **Type**: string，其中一个别名 `"fable"`、`"opus"` 或 `"sonnet"`，它们解析为 Claude Code 当前默认版本的该模型系列，或完整模型 ID，如 `"claude-opus-5-5"`

844* **Default**: 未设置，因此顾问已关闭852* **Default**: 未设置，因此顾问已关闭

845* **Per-session overrides**: `--advisor` 对此键优先一个会话。[`CLAUDE_CODE_DISABLE_ADVISOR_TOOL`](/docs/zh-CN/env-vars)关闭顾问，此键无法将其重新打开853* **Per-session overrides**: `--advisor` 对此键优先一个会话。[`CLAUDE_CODE_DISABLE_ADVISOR_TOOL`](/docs/zh-CN/env-vars)关闭顾问，此键无法将其重新打开

846 854

850}858}

851```859```

852 860

853该键对顾问[不可用](/docs/zh-CN/advisor#requirements)的提供商没有影响，例如 Amazon Bedrock 和 AWS 上的 Claude Platform。`"fable"` 需要[Fable 访问权限](/docs/zh-CN/advisor#choose-an-advisor-model)。861该键对顾问[不可用](/docs/zh-CN/advisor#requirements)的提供商（如 Amazon Bedrock 和 AWS 上的 Claude Platform）没有影响。`"fable"` 需要[Fable 访问权限](/docs/zh-CN/advisor#choose-an-advisor-model)。

854 862

855<h3 id="alwaysthinkingenabled">863<h3 id="alwaysthinkingenabled">

856 `alwaysThinkingEnabled`864 `alwaysThinkingEnabled`

858 866

859通过将其设置为 `false` 来为每个会话关闭[扩展思考](/docs/zh-CN/model-config#extended-thinking)。默认情况下思考是打开的，所以 `true` 不会改变任何内容。大多数人通过 `/config` 而不是编辑文件来设置这个。867通过将其设置为 `false` 来为每个会话关闭[扩展思考](/docs/zh-CN/model-config#extended-thinking)。默认情况下思考是打开的，所以 `true` 不会改变任何内容。大多数人通过 `/config` 而不是编辑文件来设置这个。

860 868

861在始终思考的模型上，例如 Opus 5.5 和 Fable 模型，`false` 没有效果。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，Claude Code 省略 `thinking` 参数而不是关闭思考，因此自适应推理模型可能仍然会思考。在 Anthropic API 上关闭思考时，Claude Code 向它知道[不接受该组合](/docs/zh-CN/errors#effort-isnt-available-with-thinking-turned-off)的模型（例如 Opus 5）发送努力 `high` 而不是更高级别。869在总是思考的模型上，如 Opus 5.5、Sonnet 5.5 和 Fable 模型，`false` 没有效果。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，Claude Code 省略 `thinking` 参数而不是关闭思考，因此自适应推理模型可能仍然会思考。在 Anthropic API 上关闭思考时，Claude Code 会发送努力 `high` 而不是更高级别给它知道[不接受该组合](/docs/zh-CN/errors#effort-isnt-available-with-thinking-turned-off)的模型，如 Opus 5。

862 870

863* **Scope**: [`Any file`](#scopes)871* **Scope**: [`Any file`](#scopes)

864* **Type**: Boolean872* **Type**: Boolean

865 * `true`: 无效果；思考已经打开873 * `true`: 无效果；思考已经打开

866 * `false`: Claude Code 为每个会话关闭扩展思考874 * `false`: Claude Code 为每个会话关闭扩展思考

867* **Default**: 未设置，因此对支持它的模型思考是打开的875* **Default**: 未设置，因此对于支持它的模型，思考是打开的

868* **Per-session overrides**: [`MAX_THINKING_TOKENS`](/docs/zh-CN/env-vars)对此键优先一个会话：`0` 关闭思考，在与 `false` 相同的模型和提供商限制下，正值打开思考，即使此键是 `false`。在自适应推理模型上，数字本身被忽略876* **Per-session overrides**: [`MAX_THINKING_TOKENS`](/docs/zh-CN/env-vars)对此键优先一个会话：`0` 关闭思考，在与 `false` 相同的模型和提供商限制下，正值打开思考，即使此键是 `false`。在自适应推理模型上，数字本身被忽略

869 877

870```json settings.json theme={null}878```json settings.json theme={null}

877 `availableModels`885 `availableModels`

878</h3>886</h3>

879 887

880限制人们可以为主会话、[子代理](/docs/zh-CN/sub-agents)、[skills](/docs/zh-CN/skills) 和[顾问](/docs/zh-CN/advisor)选择的模型。托管列表限制 `/model`、`--model` 和开发人员自己文件中的 `model` 键；列表外的模型无法选择。单独来说，这不会触及默认选项；将其与[`enforceAvailableModels`](#enforceavailablemodels)配对以实现该目的。888限制人们可以为主会话、[subagents](/docs/zh-CN/sub-agents)、[skills](/docs/zh-CN/skills) 和[顾问](/docs/zh-CN/advisor)选择的模型。托管列表限制 `/model`、`--model` 和开发人员自己文件中的 `model` 键；列表外的模型无法选择。使用默认前缀匹配，这不会单独触及默认选项；将其与[`enforceAvailableModels`](#enforceavailablemodels)配对以实现这一点。

881 889

882* **Scope**: [`Any file`](#scopes)。在托管设置中部署它以为组织强制执行。890* **Scope**: [`Any file`](#scopes)。在托管设置中部署它以为组织强制执行。

883* **Type**: 模型别名或 ID 的数组891* **Type**: 模型别名或 ID 的数组

891}899}

892```900```

893 901

894请参阅[限制模型选择](/docs/zh-CN/model-config#restrict-model-selection)。902模型 ID 条目（如 `"claude-opus-5"`）也允许扩展它的更高版本，如 Opus 5.5。要阻止其中一个版本，请使用[`deniedModels`](#deniedmodels)。要使每个模型 ID 条目仅允许它命名的版本，请使用[`availableModelsMatch`](#availablemodelsmatch)。请参阅[限制模型选择](/docs/zh-CN/model-config#restrict-model-selection)。

903

904<h3 id="availablemodelsmatch">

905 `availableModelsMatch`

906</h3>

907

908选择[`availableModels`](#availablemodels)条目如何匹配模型 ID。默认情况下，模型 ID 条目也允许扩展它的更高版本，因此 `"claude-opus-5"` 允许 Opus 5.5。使用 `"exact"`，每个模型 ID 条目仅允许它命名的版本，因此该模型的更高版本保持阻止状态，直到您列出它。需要 Claude Code v2.1.283 或更高版本。

909

910* **Scope**: [`Managed`](#scopes)。Claude Code 在用户、项目和本地设置以及 `--settings` 中忽略该键，并显示警告

911* **Type**: string，其中一个：

912 * `"prefix"`: 模型 ID 条目允许其版本和任何用另一个段扩展它的模型 ID

913 * `"exact"`: 模型 ID 条目仅允许它命名的版本，包括该版本的日期 ID，因此 `"claude-opus-5"` 允许 Opus 5 但不允许 `claude-opus-5-5`。系列别名如 `"opus"` 仍然允许整个系列，`best`、`opusplan` 和 `default` 条目被忽略

914* **Default**: `"prefix"`

915

916此示例允许 Opus 5 和 Sonnet 5，不允许任何更高版本：

917

918```json managed-settings.json theme={null}

919{

920 "availableModels": ["claude-opus-5", "claude-sonnet-5"],

921 "availableModelsMatch": "exact"

922}

923```

924

925使用 `"exact"`，当列表至少命名一个模型或系列时，默认选项也限制为列出的模型。请参阅[阻止特定模型或版本](/docs/zh-CN/model-config#block-specific-models-or-versions)。

926

927<h3 id="deniedmodels">

928 `deniedModels`

929</h3>

930

931阻止特定模型，无论是否有[`availableModels`](#availablemodels)允许列表，即使该列表允许它们。Claude Code 从 `/model` 选择器中隐藏被阻止的模型，该模型无法在强制执行 `availableModels` 的任何地方选择。默认选项上的会话也不会运行被阻止的模型，如[阻止特定模型或版本](/docs/zh-CN/model-config#block-specific-models-or-versions)所述。需要 Claude Code v2.1.283 或更高版本。

932

933* **Scope**: [`Managed`](#scopes)。Claude Code 在用户、项目和本地设置以及 `--settings` 中忽略该键，并显示警告

934* **Type**: 模型别名或 ID 的数组

935 * 系列别名如 `"opus"` 阻止该系列中的每个模型

936 * 模型 ID 如 `"claude-opus-5-5"` 在每种拼写中阻止该版本，包括日期和提供商特定 ID

937 * 没有次要版本的模型 ID，如 `"claude-opus-5"`，也阻止更高的次要版本，如 Opus 5.5。写 `"claude-opus-5-0"` 仅阻止 Opus 5

938 * `best`、`opusplan` 和 `default` 条目被忽略

939* **Default**: 未设置，因此没有模型被阻止

940

941此示例允许 Opus 和 Sonnet 模型并阻止 Opus 5.5：

942

943```json managed-settings.json theme={null}

944{

945 "availableModels": ["opus", "sonnet"],

946 "deniedModels": ["claude-opus-5-5"]

947}

948```

949

950请参阅[阻止特定模型或版本](/docs/zh-CN/model-config#block-specific-models-or-versions)。

895 951

896<h3 id="effortlevel">952<h3 id="effortlevel">

897 `effortLevel`953 `effortLevel`

899 955

900为您尚未保存级别的模型设置默认[努力级别](/docs/zh-CN/model-config#adjust-effort-level)。较低的级别在直接任务上更快且更便宜，较高的级别在复杂问题上推理更深入。956为您尚未保存级别的模型设置默认[努力级别](/docs/zh-CN/model-config#adjust-effort-level)。较低的级别在直接任务上更快且更便宜，较高的级别在复杂问题上推理更深入。

901 957

902当您在您的机器上的交互式会话中运行 `/effort low`、`medium`、`high` 或 `xhigh` 时，Claude Code 将该级别保存到[`modelSettings`](#modelsettings)下的活动模型，而不是写入此键。在 v2.1.251 之前，`/effort` 写入此键。958当您在您的机器上的交互式会话中运行 `/effort low`、`medium`、`high` 或 `xhigh` 时，Claude Code 将该级别保存在[`modelSettings`](#modelsettings)下的活动模型下，而不是写入此键。在 v2.1.251 之前，`/effort` 写入此键。

903 959

904在同一设置文件中，Claude Code 使用模型的保存级别而不是此键。[`modelSettings`](#modelsettings)说明跨文件优先级。960在同一设置文件中，Claude Code 使用模型的保存级别而不是此键。[`modelSettings`](#modelsettings)说明跨文件优先级。

905 961

906在附加到远程工作者的会话中、在 `-p` 运行中以及在 Agent SDK 中，`/effort` 仅适用于该会话。[调整努力级别](/docs/zh-CN/model-config#adjust-effort-level)列出也仅适用于该会话的交互式选择。`/effort` 打印的消息说明发生了什么。962在附加到远程工作者的会话中、在 `-p` 运行中以及在 Agent SDK 中，`/effort` 仅适用于该会话。[调整努力级别](/docs/zh-CN/model-config#adjust-effort-level)列出也仅适用于该会话的交互式选择。`/effort` 打印的消息说明发生了什么。

907 963

908* **Scope**: [`Any file`](#scopes)964* **Scope**: [`Any file`](#scopes)

909* **Type**: string，其中之一：965* **Type**: string，其中一个：

910 * `"low"`: 最少推理，用于短的、范围内的、延迟敏感的、不是智能敏感的任务966 * `"low"`: 最少推理，用于短的、范围内的、延迟敏感的、不是智能敏感的任务

911 * `"medium"`: 减少成本敏感工作的令牌使用，可以权衡一些智能967 * `"medium"`: 减少成本敏感工作的令牌使用，可以权衡一些智能

912 * `"high"`: 平衡令牌使用和智能968 * `"high"`: 平衡令牌使用和智能

920}976}

921```977```

922 978

923在您的用户设置文件 `~/.claude/settings.json` 中，此键是 `/effort` 在按模型保存级别之前写入的较旧形式，它继续在之前应用的地方应用，在 Opus 5、Fable 5.1 和更早的模型上。Opus 5.5 和之后发布的模型忽略它，并从它们自己的默认值开始，直到您为它们保存一个级别，`/effort` 在[`modelSettings`](#modelsettings)下写入。在项目、本地和托管设置中，以及使用 `--settings` 时，此键适用于每个模型。979在您的用户设置文件 `~/.claude/settings.json` 中，此键是 `/effort` 在保存每个模型的级别之前写入的较旧形式，它继续在之前应用的地方应用，在 Opus 5、Fable 5.1 和更早的模型上。Opus 5.5 和之后发布的模型忽略它，并从它们自己的默认值开始，直到您为它们保存一个级别，`/effort` 在[`modelSettings`](#modelsettings)下写入。在项目、本地和托管设置中，以及使用 `--settings` 时，此键适用于每个模型。

924 980

925<h3 id="enforceavailablemodels">981<h3 id="enforceavailablemodels">

926 `enforceAvailableModels`982 `enforceAvailableModels`

927</h3>983</h3>

928 984

929`/model` 选择器有一个**默认**选项，当应用时解析为您的[组织默认模型](/docs/zh-CN/model-config#organization-default-model)，否则解析为您的账户类型的默认值。[`availableModels`](#availablemodels)允许列表限制您可以命名的模型，但单独来说它不会改变**默认**，因此**默认**仍然可以解析为列表外的模型。此键关闭了该间隙。需要 Claude Code v2.1.175 或更高版本。985`/model` 选择器有一个**默认**选项，[`default` 模型设置](/docs/zh-CN/model-config#default-model-setting)描述它解析为的模型。[`availableModels`](#availablemodels)允许列表限制您可以命名的模型，但使用默认[前缀匹配](#availablemodelsmatch)它不会单独重新映射您的账户类型的默认值，因此**默认**仍然可以解析为列表外的模型。此键关闭该间隙。需要 Claude Code v2.1.175 或更高版本。

930 986

931当您的组织部署任何托管设置时，Claude Code 仅从托管源读取此键，并在您的其他文件中忽略它。987当您的组织部署任何托管设置时，Claude Code 仅从托管源读取此键，并在您的其他文件中忽略它。

932 988

933* **Scope**: [`Any file`](#scopes)989* **Scope**: [`Any file`](#scopes)

934* **Type**: Boolean990* **Type**: Boolean

935 * `true`: 当**默认**将解析为 `availableModels` 外的模型时，Claude Code 将其解析为列表中第一个可用的模型991 * `true`: 当**默认**会解析为 `availableModels` 外的模型时，Claude Code 将其解析为列表中第一个可用的模型

936 * `false`: **默认**照常解析，即使是列表外的模型992 * `false`: 此键不改变**默认**的解析方式

937* **Default**: `false`993* **Default**: `false`

938 994

939此示例将命名选择限制为 Sonnet 和 Haiku 模型，并使**默认**解析为其中第一个可用的：995此示例将命名选择限制为 Sonnet 和 Haiku 模型，并使**默认**解析为其中第一个可用的：

945}1001}

946```1002```

947 1003

948当 `availableModels` 未设置或为空时，此键无效。请参阅[为默认模型强制执行允许列表](/docs/zh-CN/model-config#enforce-the-allowlist-for-the-default-model)。需要 Claude Code v2.1.175 或更高版本。1004当 `availableModels` 未设置或为空时，此键没有效果。请参阅[为默认模型强制执行允许列表](/docs/zh-CN/model-config#enforce-the-allowlist-for-the-default-model)。需要 Claude Code v2.1.175 或更高版本。

949 1005

950<h3 id="fallbackmodel">1006<h3 id="fallbackmodel">

951 `fallbackModel`1007 `fallbackModel`

952</h3>1008</h3>

953 1009

954命名备份模型供 Claude Code 在您的主模型过载或不可用时按顺序尝试。Claude Code 在链中的下一个可用模型上切换以完成该轮，并显示通知。没有链的情况下，Claude Code 重试同一模型，然后显示服务器的错误，您重试或自己切换模型。1010命名备用模型供 Claude Code 在您的主模型过载或不可用时按顺序尝试。Claude Code 为该轮的其余部分切换到链中下一个可用的模型，并显示通知。没有链的情况下，Claude Code 重试同一模型，然后显示服务器的错误，您重试或自己切换模型。

955 1011

956切换意味着在备用模型上进行一轮冷[提示缓存](/docs/zh-CN/prompt-caching#switching-models)；您的下一条消息首先再次尝试主模型。1012切换意味着在备用模型上进行一轮冷[提示缓存](/docs/zh-CN/prompt-caching#switching-models)；您的下一条消息首先再次尝试主模型。

957 1013

968}1024}

969```1025```

970 1026

971与大多数数组设置不同，此键不会跨设置文件合并：最高优先级的定义它的文件提供整个链。如果您的项目文件设置 `["claude-sonnet-5"]` 而您的用户文件设置 `["claude-haiku-4-5"]`，链是 `["claude-sonnet-5"]` 仅。Claude Code 从列表中最多保留三个不同的允许模型，忽略其余的。请参阅[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)。1027与大多数数组设置不同，此键不跨设置文件合并：最高优先级文件定义它提供整个链。如果您的项目文件设置 `["claude-sonnet-5"]` 而您的用户文件设置 `["claude-haiku-4-5"]`，链是 `["claude-sonnet-5"]` 仅。Claude Code 从列表中最多保留三个不同的允许模型，忽略其余的。请参阅[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)。

972 1028

973<h3 id="fastmode">1029<h3 id="fastmode">

974 `fastMode`1030 `fastMode`

975</h3>1031</h3>

976 1032

977为可用的会话打开[快速模式](/docs/zh-CN/fast-mode)，用于交互式工作，如快速迭代或实时调试，您希望以更高的每令牌成本获得速度。您通常不会手动编辑此键：运行 `/fast` 将 `fastMode: true` 写入 `~/.claude/settings.json`，再次运行它以关闭快速模式会删除该键。快速模式仅在 Opus 5.5、Opus 5 和 Opus 4.8 上运行：从另一个模型打开它会将您切换到 Opus，切换到不支持的模型会关闭它。请参阅[在快速模式打开时切换模型](/docs/zh-CN/fast-mode#switch-models-while-fast-mode-is-on)。1033为可用的会话打开[快速模式](/docs/zh-CN/fast-mode)，用于交互式工作，如快速迭代或实时调试，您希望以更高的每令牌成本获得速度。您通常不会手动编辑此键：运行 `/fast` 将 `fastMode: true` 写入 `~/.claude/settings.json`，再次运行它以关闭快速模式会删除该键。快速模式仅在 Opus 5.5、Opus 5 和 Opus 4.8 上运行：从另一个模型打开它会切换您到 Opus，切换到不支持的模型会关闭它。请参阅[在快速模式打开时切换模型](/docs/zh-CN/fast-mode#switch-models-while-fast-mode-is-on)。

978 1034

979* **Scope**: [`Any file`](#scopes)1035* **Scope**: [`Any file`](#scopes)

980* **Type**: Boolean1036* **Type**: Boolean

1009}1065}

1010```1066```

1011 1067

1012请参阅[需要按会话选择加入](/docs/zh-CN/fast-mode#require-per-session-opt-in)。1068请参阅[需要每个会话的选择加入](/docs/zh-CN/fast-mode#require-per-session-opt-in)。

1013 1069

1014<h3 id="language">1070<h3 id="language">

1015 `language`1071 `language`

1018默认情况下让 Claude 用英语以外的语言响应。响应没有固定列表：Claude Code 将值逐字传递给 Claude 作为始终用该语言响应的指令，因此任何 Claude 可以读取的语言名称都有效。Claude Code 不检查该值，因此拼写错误的名称按原样到达 Claude，而不是产生错误。相同的值为[语音听写](/docs/zh-CN/voice-dictation#change-the-dictation-language)设置语言，它有一个固定的[支持的听写语言](/docs/zh-CN/voice-dictation#change-the-dictation-language)列表，以及自动生成的会话标题。1074默认情况下让 Claude 用英语以外的语言响应。响应没有固定列表：Claude Code 将值逐字传递给 Claude 作为始终用该语言响应的指令，因此任何 Claude 可以读取的语言名称都有效。Claude Code 不检查该值，因此拼写错误的名称按原样到达 Claude，而不是产生错误。相同的值为[语音听写](/docs/zh-CN/voice-dictation#change-the-dictation-language)设置语言，它有一个固定的[支持的听写语言](/docs/zh-CN/voice-dictation#change-the-dictation-language)列表，以及自动生成的会话标题。

1019 1075

1020* **Scope**: [`Any file`](#scopes)1076* **Scope**: [`Any file`](#scopes)

1021* **Type**: string，任何语言名称，例如 `"japanese"`、`"spanish"` 或 `"french"`；Claude Code 不验证它1077* **Type**: string，任何语言名称，如 `"japanese"`、`"spanish"` 或 `"french"`；Claude Code 不验证它

1022* **Default**: 未设置；会话标题然后匹配您的对话语言1078* **Default**: 未设置；会话标题然后匹配您的对话语言

1023 1079

1024```json settings.json theme={null}1080```json settings.json theme={null}

1031 `maxEffortLevel`1087 `maxEffortLevel`

1032</h3>1088</h3>

1033 1089

1034限制会话可以使用的[努力级别](/docs/zh-CN/model-config#adjust-effort-level)，保留较低的级别可用。任何更高的级别都在上限处运行，包括来自 `/effort`、`/model` 选择器、`--effort`、[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars)、skill 或 subagent 的 `effort` frontmatter 或模型自己的默认值。Claude Code 在每个请求之前应用上限本身，因此它在每个提供商上都有效，包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry。需要 Claude Code v2.1.267 或更高版本。1090限制会话可以使用的[努力级别](/docs/zh-CN/model-config#adjust-effort-level)，保留较低的级别可用。任何更高的级别都在上限处运行，包括来自 `/effort`、`/model` 选择器、`--effort`、[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars)、skill 或 subagent 的 `effort` frontmatter 或模型自己的默认值。Claude Code 在每个请求之前自己应用上限，因此它在每个提供商上保持，包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry。需要 Claude Code v2.1.267 或更高版本。

1035 1091

1036* **Scope**: [`Any file`](#scopes)。在托管设置中部署它以为组织强制执行。当多个范围设置上限时，最低的适用，因此在一个范围中设置的上限无法从另一个范围提高1092* **Scope**: [`Any file`](#scopes)。在托管设置中部署它以为组织强制执行。当多个范围设置上限时，最低的适用，因此在一个范围中设置的上限无法从另一个范围提高

1037* **Type**: string，其中之一 `"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。`"max"` 值不设置上限1093* **Type**: string，其中一个 `"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。`"max"` 值设置无上限

1038* **Default**: 未设置，因此不适用上限1094* **Default**: 未设置，因此无上限适用

1039* **Effect on ultracode**: 低于 `xhigh` 的上限使[ultracode](#ultracode)在上限适用的模型上不可用1095* **Per-model caps**: 将 `maxEffortLevel` 添加到模型的[`modelSettings`](#modelsettings)条目。该条目在设置两者的设置源（如您的用户设置或一个[托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)）中仅替换该模型的此键。在那里设置 `"max"` 以豁免该模型免受该源的上限；Claude Code 仍然应用来自其他源的上限

1040* **Per-model caps**: 将 `maxEffortLevel` 添加到模型的[`modelSettings`](#modelsettings)条目。该条目仅在设置源中替换此键，该源同时设置两者，例如您的用户设置或一个[托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)。在那里设置 `"max"` 以豁免该模型不受该源的上限；Claude Code 仍然应用来自其他源的上限

1041 1096

1042此示例将每个模型限制在 `medium`，并豁免 Sonnet 4.6：1097此示例将每个模型限制在 `medium`，并豁免 Sonnet 4.6：

1043 1098

1058 `model`1113 `model`

1059</h3>1114</h3>

1060 1115

1061设置每个新会话使用的模型，因此您不必每次都使用 `/model` 选择一个。在此处设置它不会阻止您在会话中期切换。如果您的管理员设置了[组织默认模型](/docs/zh-CN/model-config#organization-default-model)以覆盖用户选择，即使您在用户、项目或本地设置中设置此键，您也会获得该模型。1116设置每个新会话使用的模型，因此您不必每次都用 `/model` 选择一个。在此处设置它不会阻止您在会话中期切换。如果您的管理员设置了[组织默认模型](/docs/zh-CN/model-config#organization-default-model)以覆盖用户选择，即使您在用户、项目或本地设置中设置此键，您也会获得该模型。

1062 1117

1063* **Scope**: [`Any file`](#scopes)1118* **Scope**: [`Any file`](#scopes)

1064* **Type**: string，模型别名或完整模型 ID1119* **Type**: string，模型别名或完整模型 ID

1077 `modelOverrides`1132 `modelOverrides`

1078</h3>1133</h3>

1079 1134

1080将 Anthropic 模型 ID 映射到提供商特定的模型 ID，例如 Amazon Bedrock 推理配置文件 ARN。然后每个模型选择器条目在调用提供商 API 时使用其映射值。管理员在[Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-CN/model-config#override-model-ids-per-version)上使用这个来将每个模型版本路由到特定的推理配置文件、版本名称或部署，以实现治理、成本分配或区域路由。1135将 Anthropic 模型 ID 映射到提供商特定的模型 ID，如 Amazon Bedrock 推理配置文件 ARN。每个模型选择器条目然后在调用提供商 API 时使用其映射值。管理员在[Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-CN/model-config#override-model-ids-per-version)上使用这个来将每个模型版本路由到特定的推理配置文件、版本名称或部署，以实现治理、成本分配或区域路由。

1081 1136

1082* **Scope**: [`Any file`](#scopes)1137* **Scope**: [`Any file`](#scopes)

1083* **Type**: 将模型 ID 映射到提供商模型 ID 的对象1138* **Type**: 将模型 ID 映射到提供商模型 ID 的对象

1099 `modelPicker`1154 `modelPicker`

1100</h3>1155</h3>

1101 1156

1102列出 `/model` 选择器提供的模型，按您写入它们的顺序和您选择的标签下，因此选择器列出您的组织运行的模型，在内置阵容之后或代替它。每行的 `model` 按字面意思取用，因此它接受 `--model` 接受的任何内容：别名如 `opus`、Anthropic 模型 ID 或 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 LLM 网关的提供商格式 ID。需要 Claude Code v2.1.242 或更高版本。1157列出 `/model` 选择器提供的模型，按您写入它们的顺序和您选择的标签下，因此选择器列出您的组织运行的模型，在内置阵容之后或代替它。每行的 `model` 逐字获取，因此它接受 `--model` 接受的任何内容：别名如 `opus`、Anthropic 模型 ID 或 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 LLM 网关的提供商格式 ID。需要 Claude Code v2.1.242 或更高版本。

1103 1158

1104* **Scope**: [`User or managed`](#scopes)。Claude Code 从托管设置、`--settings` 和用户设置读取该键，并在项目和本地设置中忽略它，因此您克隆的存储库无法重新标记选择器。这三个中最高的设置该键的提供整个阵容，Claude Code 从不合并来自两个源的阵容。1159* **Scope**: [`User or managed`](#scopes)。Claude Code 从托管设置、`--settings` 和用户设置读取该键，并在项目和本地设置中忽略它，因此您克隆的存储库无法重新标记选择器。这三个中最高的设置该键提供整个阵容，Claude Code 从不合并来自两个源的阵容。

1105* **Type**: 具有 `options` 数组和可选 `replaceBuiltInOptions` Boolean 的对象1160* **Type**: 带有 `options` 数组的对象和可选的 `replaceBuiltInOptions` Boolean

1106* **Default**: 未设置，因此选择器显示内置阵容1161* **Default**: 未设置，因此选择器显示内置阵容

1107 1162

1108此示例在内置阵容之后添加两个 Bedrock 部署，在您的团队识别的名称下：1163此示例在内置阵容之后添加两个 Bedrock 部署，在您的团队识别的名称下：

1130 `modelPicker` 的字段1185 `modelPicker` 的字段

1131</h4>1186</h4>

1132 1187

1133该键采用两个字段，一个用于行本身，一个用于它们是替换内置阵容还是添加到它。1188该键有两个字段，一个用于行本身，一个用于它们是替换内置阵容还是添加到它。

1134 1189

1136| :- | :- | :- |1191| :- | :- | :- |

1137| `options` | 行的数组，每个都有必需的 `model` 和可选的 `label` 和 `description` | 选择器显示的行，按此顺序，除了灰显的行移到底部。没有 `label`，Claude Code 用它知道的模型的内置名称标记行，或模型 ID 否则，没有 `description` 它写一个通用的第二行 |1192| `options` | 行的数组，每个都有必需的 `model` 和可选的 `label`、`description` 和 `behavesAs` | 选择器显示的行，按此顺序，除了灰显的行移到底部。没有 `label`，Claude Code 用它知道的模型的内置名称标记行，或模型 ID 否则，没有 `description` 它写一个通用的第二行 |

1139 1194

1140启用 `replaceBuiltInOptions` 时，Claude Code 隐藏每个其他行：内置阵容、它为[`availableModels`](#availablemodels)条目添加的行、[网关发现](/docs/zh-CN/llm-gateway-protocol#model-discovery)找到的模型和[`ANTHROPIC_CUSTOM_MODEL_OPTION`](/docs/zh-CN/model-config#add-a-custom-model-option)。关闭时，Claude Code 跳过内置阵容已覆盖的列出的模型。标签改变选择器显示的内容，而不是 Claude Code 运行的模型。1195`options` 中的条目也可以在其 `model` 旁边携带可选的 `behavesAs` 字符串，需要 v2.1.257 或更高版本。将其设置为您的 Claude Code 版本已知的模型的 ID，如 `claude-opus-4-8`，在其 `model` 比您的版本更新的条目上。Claude Code 然后将该已知模型的能力和努力默认值应用于条目，而不是将其模型视为未知。条目的标签和 Claude Code 在请求中发送的模型 ID 不改变。

1141 1196

1142[`availableModels`](#availablemodels)允许列表仍然适用于这些行。在将列出的模型添加到允许列表之前，请阅读[合并行为](/docs/zh-CN/model-config#merge-behavior)：特定模型 ID 缩小其系列的通配符条目。Claude Code 还在显示选择器之前检查每行与会话：1197使用 `replaceBuiltInOptions` 打开时，Claude Code 隐藏每个其他行：内置阵容、它为[`availableModels`](#availablemodels)条目添加的行、[网关发现](/docs/zh-CN/llm-gateway-protocol#model-discovery)找到的模型和[`ANTHROPIC_CUSTOM_MODEL_OPTION`](/docs/zh-CN/model-config#add-a-custom-model-option)。关闭时，Claude Code 跳过内置阵容已覆盖的列出的模型。标签改变选择器显示的内容，而不是 Claude Code 运行的模型。

1143 1198

1144* **Dropped**: Claude Code 无法提供的行，例如已停用的模型或您的组织无权访问的模型1199[`availableModels`](#availablemodels)允许列表仍然适用于这些行。在将列出的模型添加到允许列表之前，请阅读[合并行为](/docs/zh-CN/model-config#merge-behavior)：特定模型 ID 缩小其系列的通配符条目。Claude Code 也在显示选择器之前检查每行与会话：

1200

1201* **Dropped**: Claude Code 无法提供的行，如已退休的模型或您的组织无权访问的模型

1145* **Grayed out**: 您还无法选择的行，显示原因1202* **Grayed out**: 您还无法选择的行，显示原因

1146* **No row survives**: Claude Code 保留内置阵容，按允许列表过滤如常1203* **No row survives**: Claude Code 保留内置阵容，按允许列表过滤如常

1147 1204

1148Claude Code 删除它无法解析的行并保留其余的。请参阅[修复损坏的设置文件](/docs/zh-CN/settings#fix-a-broken-settings-file)。1205Claude Code 删除它无法解析的行，保留其余的。请参阅[修复损坏的设置文件](/docs/zh-CN/settings#fix-a-broken-settings-file)。

1149 1206

1150<h3 id="modelpricing">1207<h3 id="modelpricing">

1151 `modelPricing`1208 `modelPricing`

1152</h3>1209</h3>

1153 1210

1154以您的组织支付的费率而不是列表价格报告支出。当您的组织有合同费率时设置它，因此开发人员看到的美元数字与您的账单相匹配。Claude Code 在 `/usage`、[状态行](/docs/zh-CN/statusline)、Agent SDK 的 `total_cost_usd`、[`--max-budget-usd`](/docs/zh-CN/cli-reference)限制和[OpenTelemetry](/docs/zh-CN/monitoring-usage)成本指标和事件中应用费率。您提供费率：Claude Code 不从您的合同或 Claude Console 读取它们。需要 Claude Code v2.1.242 或更高版本。1211按您的组织支付的费率而不是列表价格报告支出。当您的组织有合同费率时设置它，因此开发人员看到的美元数字与您的账单匹配。Claude Code 在 `/usage`、[状态行](/docs/zh-CN/statusline)、Agent SDK 的 `total_cost_usd`、[`--max-budget-usd`](/docs/zh-CN/cli-reference)限制和[OpenTelemetry](/docs/zh-CN/monitoring-usage)成本指标和事件中应用费率。您提供费率：Claude Code 不从您的合同或 Claude Console 读取它们。需要 Claude Code v2.1.242 或更高版本。

1155 1212

1156* **Scope**: [`Managed`](#scopes)。通过服务器托管设置、MDM 策略、`managed-settings.json` 文件或[策略助手](/docs/zh-CN/managed-settings#compute-the-policy-with-a-helper-program)部署该键。Claude Code 在用户、项目和本地设置中、在 `--settings` 中以及在 Windows 中的用户可写[HKCU 注册表](/docs/zh-CN/managed-settings#where-each-mechanism-stores-the-policy)中忽略它。使用服务器托管设置，每个会话以列表价格报告成本，直到该会话的[设置获取](/docs/zh-CN/server-managed-settings#fetch-and-caching-behavior)已确认该设置。嵌入 Claude Code 的主机应用程序，设置[`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars)可以通过 SDK [`managedSettings`](/docs/zh-CN/agent-sdk/typescript#options)选项提供自己的表，Claude Code 仅在没有托管源设置该键时使用，仅在 Claude Code v2.1.246 或更高版本中。1213* **Scope**: [`Managed`](#scopes)。通过服务器托管设置、MDM 策略、`managed-settings.json` 文件或[策略助手](/docs/zh-CN/managed-settings#compute-the-policy-with-a-helper-program)部署该键。Claude Code 在用户、项目和本地设置、`--settings` 中忽略它，在 Windows 中的用户可写[HKCU 注册表](/docs/zh-CN/managed-settings#where-each-mechanism-stores-the-policy)中忽略它。使用服务器托管设置，每个会话以列表价格报告成本，直到该会话的[设置获取](/docs/zh-CN/server-managed-settings#fetch-and-caching-behavior)已确认该设置。嵌入 Claude Code 并设置[`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars)的主机应用可以通过 SDK [`managedSettings`](/docs/zh-CN/agent-sdk/typescript#options)选项提供自己的表，Claude Code 仅在没有托管源设置该键时使用，仅在 Claude Code v2.1.246 或更高版本中。

1157* **Type**: 具有可选 `multiplier` 和可选 `overrides` 映射的对象1214* **Type**: 带有可选 `multiplier` 和可选 `overrides` 映射的对象

1158* **Default**: 未设置，因此 Claude Code 报告列表价格，除非主机应用程序提供表1215* **Default**: 未设置，因此 Claude Code 报告列表价格，除非主机应用提供表

1159 1216

1160单独设置 `multiplier` 以获得固定折扣或加价，单独设置 `overrides` 以获得按模型费率，或两者都设置。1217单独设置 `multiplier` 以获得统一折扣或加价，单独设置 `overrides` 以获得每个模型费率，或两者都设置。

1161 1218

1162此示例为 Sonnet 4.6 设置合同费率，然后将每个数字（包括 Sonnet 行）减少 15%：1219此示例为 Sonnet 4.6 设置合同费率，然后将每个数字（包括 Sonnet 行）减少 15%：

1163 1220

1177}1234}

1178```1235```

1179 1236

1180将 `multiplier` 设置为 1 以上，最多 10，以标记每个数字。加价需要 Claude Code v2.1.271 或更高版本。较早的版本忽略 `multiplier` 大于 1 的警告并保留设置的其余部分。1237将 `multiplier` 设置为 1 以上，最多 10，以标记每个数字。加价需要 Claude Code v2.1.271 或更高版本。更早的版本忽略 `multiplier` 高于 1 的警告，保留设置的其余部分。

1181 1238

1182有关步骤，包括如何确认费率有效，请参阅[以您的合同费率报告支出](/docs/zh-CN/costs#report-spend-at-your-contracted-rates)。1239有关步骤，包括如何确认费率有效，请参阅[按您的合同费率报告支出](/docs/zh-CN/costs#report-spend-at-your-contracted-rates)。

1183 1240

1184<span id="modelpricing-multiplier" />1241<span id="modelpricing-multiplier" />

1185 1242

1195| `overrides` | 模型 ID 到具有 `input`、`output`、`cacheRead` 和 `cacheWrite` 的费率对象的映射，每个 0 到 10000 | 该模型的美元每百万令牌费率，全部四个必需。`cacheWrite` 涵盖五分钟和一小时缓存写入。请参阅[`modelPricing` 行适用于哪些模型](#which-models-a-modelpricing-row-applies-to) |1252| `overrides` | 模型 ID 到具有 `input`、`output`、`cacheRead` 和 `cacheWrite` 的费率对象的映射，每个 0 到 10000 | 该模型的美元每百万令牌费率，全部四个必需。`cacheWrite` 涵盖五分钟和一小时缓存写入。请参阅[`modelPricing` 行适用于哪些模型](#which-models-a-modelpricing-row-applies-to) |

1196 1253

1197Claude Code 完全按照您写入的方式使用行的费率，不添加快速模式附加费或[仅限美国推理费率](https://platform.claude.com/docs/en/about-claude/pricing)。如果您也设置 `multiplier`，Claude Code 在行的费率之上应用它。Claude Code 删除具有它无法解析的费率或 `multiplier` 的行，并保留其余的；请参阅[修复损坏的设置文件](/docs/zh-CN/settings#fix-a-broken-settings-file)。1254Claude Code 完全按照您写入的方式使用行的费率，不添加快速模式附加费或[仅限美国推理费率](https://platform.claude.com/docs/en/about-claude/pricing)。如果您也设置 `multiplier`，Claude Code 在行的费率之上应用它。Claude Code 删除具有它无法解析的费率或 `multiplier` 的行，保留其余的；请参阅[修复损坏的设置文件](/docs/zh-CN/settings#fix-a-broken-settings-file)。

1198 1255

1199<h4 id="which-models-a-modelpricing-row-applies-to">1256<h4 id="which-models-a-modelpricing-row-applies-to">

1200 `modelPricing` 行适用于哪些模型1257 `modelPricing` 行适用于哪些模型

1202 1259

1203Claude Code 从行的键决定行适用于哪些模型：1260Claude Code 从行的键决定行适用于哪些模型：

1204 1261

1205* **内置模型的 ID**: Claude Code 本身为内置模型使用的键，无论该键是模型自己的 ID（如 `claude-sonnet-4-6`）还是其 Bedrock、Agent Platform 或 Foundry ID。Claude Code 将行应用于该模型的每个日期快照 ID 和提供商特定 ID。1262* **内置模型的 ID**: Claude Code 本身为内置模型使用的键，无论该键是模型自己的 ID，如 `claude-sonnet-4-6`，还是其 Bedrock、Agent Platform 或 Foundry ID。Claude Code 将行应用于该模型的每个日期快照 ID 和提供商特定 ID。

1206* **任何其他键**: 不是内置模型 ID 的键，例如网关模型别名。Claude Code 仅将行应用于该一个 ID。当模型 ID 与您的一个键完全匹配，也属于由内置模型 ID 键入的行时，Claude Code 使用精确匹配。1263* **任何其他键**: 不是内置模型 ID 的键，如网关模型别名。Claude Code 仅将行应用于该一个 ID。当模型 ID 完全匹配您的一个键，也落在由内置模型 ID 键的行下时，Claude Code 使用精确匹配。

1207* **Bedrock 应用推理配置文件**: 一旦 Claude Code 通过您的[`modelOverrides`](#modeloverrides)映射或[`bedrock:GetInferenceProfile` 查找](/docs/zh-CN/amazon-bedrock#iam-configuration)将配置文件解析为它路由到的模型，Claude Code 将该模型的行应用于配置文件。1264* **Bedrock 应用推理配置文件**: 一旦 Claude Code 通过您的[`modelOverrides`](#modeloverrides)映射或[`bedrock:GetInferenceProfile` 查找](/docs/zh-CN/amazon-bedrock#iam-configuration)将配置文件解析为它路由到的模型，Claude Code 将该模型的行应用于配置文件。

1208 1265

1209<h3 id="modelsettings">1266<h3 id="modelsettings">

1212 1269

1213为您使用的每个模型保存[努力级别](/docs/zh-CN/model-config#adjust-effort-level)。需要 Claude Code v2.1.251 或更高版本。1270为您使用的每个模型保存[努力级别](/docs/zh-CN/model-config#adjust-effort-level)。需要 Claude Code v2.1.251 或更高版本。

1214 1271

1215在您的机器上的交互式会话中，当您使用 `/effort` 或 `/model` 选择器的努力滑块将 `low`、`medium`、`high` 或 `xhigh` 保存为您的默认值时，Claude Code 在您使用的模型下在此处写入该级别，因此您很少自己编辑此键。当您在[VS Code 扩展的模型选择器](/docs/zh-CN/vs-code#use-the-prompt-box)中选择这些级别之一时，Claude Code 以相同的方式在此处保存它。[`effortLevel`](#effortlevel)条目列出 `/effort` 仅适用于该会话的会话。1272在您机器上的交互式会话中，当您使用 `/effort` 或 `/model` 选择器的努力滑块将 `low`、`medium`、`high` 或 `xhigh` 保存为您的默认值时，Claude Code 在您使用的模型下在此处写入该级别，因此您很少自己编辑此键。当您在[VS Code 扩展的模型选择器](/docs/zh-CN/vs-code#use-the-prompt-box)中选择其中一个级别时，Claude Code 以相同的方式在此处保存它。[`effortLevel`](#effortlevel)条目列出 `/effort` 仅适用于该会话的会话。

1216 1273

1217手动编辑该键以更改或删除您保存的级别。1274手动编辑该键以更改或删除您保存的级别。

1218 1275

1219此处模型的 `effortLevel` 优先于同一设置文件中的顶级[`effortLevel`](#effortlevel)。跨文件，Claude Code 分别解析每个模型：最高优先级[设置文件](/docs/zh-CN/settings#settings-precedence)，为该模型设置 `effortLevel` 或[适用于该模型](#effortlevel)的顶级 `effortLevel` 决定，因此托管设置中的 `effortLevel` 优先于您在用户设置中保存的级别。[调整努力级别](/docs/zh-CN/model-config#adjust-effort-level)列出还可以覆盖保存级别的内容，例如启动时的 `--effort`。1276此处模型的 `effortLevel` 优先于同一设置文件中的顶级[`effortLevel`](#effortlevel)。跨文件，Claude Code 分别解析每个模型：最高优先级[设置文件](/docs/zh-CN/settings#settings-precedence)设置该模型的 `effortLevel` 或[适用于该模型](#effortlevel)的顶级 `effortLevel` 决定，因此托管设置中的 `effortLevel` 优先于您在用户设置中保存的级别。[调整努力级别](/docs/zh-CN/model-config#adjust-effort-level)列出还可以覆盖保存级别的内容，如启动时的 `--effort`。

1220 1277

1221要限制一个模型的努力而不是设置其级别，请将[`maxEffortLevel`](#maxeffortlevel)字段添加到该模型的条目。该字段需要 Claude Code v2.1.267 或更高版本。1278要限制一个模型的努力而不是设置其级别，将[`maxEffortLevel`](#maxeffortlevel)字段添加到该模型的条目。该字段需要 Claude Code v2.1.267 或更高版本。

1222 1279

1223* **Scope**: [`Any file`](#scopes)1280* **Scope**: [`Any file`](#scopes)

1224* **Type**: 将模型名称映射到具有 `effortLevel` 字段的对象的对象，其中之一 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`、[`maxEffortLevel`](#maxeffortlevel)字段或两者1281* **Type**: 将模型名称映射到具有 `effortLevel` 字段的对象，其中一个 `"low"`、`"medium"`、`"high"` 或 `"xhigh"`、[`maxEffortLevel`](#maxeffortlevel)字段或两者

1225* **Default**: 未设置1282* **Default**: 未设置

1226 1283

1227Claude Code 在模型的规范名称下写入每个条目，例如 `claude-opus-5-5`，并将该模型的别名、日期后缀、`[1m]` 和识别的提供商特定 ID 匹配到同一条目。1284Claude Code 在模型的规范名称下写入每个条目，如 `claude-opus-5-5`，并将该模型的别名、日期后缀、`[1m]` 和识别的提供商特定 ID 匹配到同一条目。

1228 1285

1229此示例将 Opus 5.5 保持在 `high`，而其他模型使用它们自己的保存或默认级别：1286此示例将 Opus 5.5 保持在 `high`，而其他模型使用它们自己的保存或默认级别：

1230 1287

1244 `outputStyle`1301 `outputStyle`

1245</h3>1302</h3>

1246 1303

1247按名称选择[输出样式](/docs/zh-CN/output-styles)。输出样式是一组保存的指令，改变 Claude 的角色、语气和输出格式，例如内置的 Explanatory 和 Learning 样式或您自己写的。1304按名称选择[输出样式](/docs/zh-CN/output-styles)。输出样式是一组保存的指令，改变 Claude 的角色、语气和输出格式，如内置的 Explanatory 和 Learning 样式或您自己写的。

1248 1305

1249如果您在会话期间更改此键，Claude 从您的下一条消息开始使用新样式。有关该消息在提示缓存中的成本，请参阅[更改输出样式](/docs/zh-CN/prompt-caching#changing-output-style)。在 v2.1.251 之前，编辑仅在您运行 `/clear` 或启动新会话后应用。1306如果您在会话期间更改此键，Claude 从您的下一条消息开始使用新样式。关于该消息在提示缓存中的成本，请参阅[更改输出样式](/docs/zh-CN/prompt-caching#changing-output-style)。在 v2.1.251 之前，编辑仅在您运行 `/clear` 或启动新会话后应用。

1250 1307

1251* **Scope**: [`Any file`](#scopes)1308* **Scope**: [`Any file`](#scopes)

1252* **Type**: string，[内置](/docs/zh-CN/output-styles#built-in-output-styles)或[自定义](/docs/zh-CN/output-styles#create-a-custom-output-style)输出样式的名称1309* **Type**: string，[内置](/docs/zh-CN/output-styles#built-in-output-styles)或[自定义](/docs/zh-CN/output-styles#create-a-custom-output-style)输出样式的名称

1264 `promptCacheTtl`1321 `promptCacheTtl`

1265</h3>1322</h3>

1266 1323

1267选择[提示缓存](/docs/zh-CN/prompt-caching)保持主对话的时间长度。此键适用于您的交互式、`-p` 和 Agent SDK 轮，以及 Claude Code 与它们内联运行的助手。一小时的生命周期在较长的中断中保持缓存温暖，API [以比五分钟生命周期更高的费率为每个缓存写入计费](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)。需要 Claude Code v2.1.242 或更高版本。1324选择[提示缓存](/docs/zh-CN/prompt-caching)保持主对话的时间长度。此键适用于您的交互式、`-p` 和 Agent SDK 轮，以及 Claude Code 与它们内联运行的助手。一小时的生命周期在较长的中断中保持缓存温暖，API [在五分钟生命周期的更高费率下计费每个缓存写入](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)。需要 Claude Code v2.1.242 或更高版本。

1268 1325

1269* **Scope**: [`Any file`](#scopes)1326* **Scope**: [`Any file`](#scopes)

1270* **Type**: string，其中之一：1327* **Type**: string，其中一个：

1271 * `"5m"`: 缓存保持五分钟1328 * `"5m"`: 缓存保持五分钟

1272 * `"1h"`: 缓存保持一小时1329 * `"1h"`: 缓存保持一小时

1273* **Default**: 未设置，因此每个主对话请求获得[其默认生命周期](/docs/zh-CN/prompt-caching#which-ttl-each-request-gets)1330* **Default**: 未设置，因此每个主对话请求获得[其默认生命周期](/docs/zh-CN/prompt-caching#which-ttl-each-request-gets)

1274* **Per-session overrides**: [`FORCE_PROMPT_CACHING_5M`](/docs/zh-CN/env-vars)优先于所有其他，然后[`CLAUDE_CODE_PROMPT_CACHE_TTL`](/docs/zh-CN/env-vars)，然后此键，最后[`ENABLE_PROMPT_CACHING_1H`](/docs/zh-CN/env-vars)1331* **Per-session overrides**: [`FORCE_PROMPT_CACHING_5M`](/docs/zh-CN/env-vars)优先于所有其他，然后[`CLAUDE_CODE_PROMPT_CACHE_TTL`](/docs/zh-CN/env-vars)，然后此键，最后[`ENABLE_PROMPT_CACHING_1H`](/docs/zh-CN/env-vars)

1275 1332

1276此示例将主对话保持在一小时生命周期，并将 subagent 保留在五分钟：1333此示例将主对话保持在一小时生命周期，并将 subagents 保留在五分钟：

1277 1334

1278```json settings.json theme={null}1335```json settings.json theme={null}

1279{1336{

1282}1339}

1283```1340```

1284 1341

1285有关每个生命周期的成本，请参阅[缓存生命周期](/docs/zh-CN/prompt-caching#cache-lifetime)。1342关于每个生命周期的成本，请参阅[缓存生命周期](/docs/zh-CN/prompt-caching#cache-lifetime)。

1286 1343

1287<h3 id="showthinkingsummaries">1344<h3 id="showthinkingsummaries">

1288 `showThinkingSummaries`1345 `showThinkingSummaries`

1308 `subagentPromptCacheTtl`1365 `subagentPromptCacheTtl`

1309</h3>1366</h3>

1310 1367

1311选择[提示缓存](/docs/zh-CN/prompt-caching)保持 Claude Code 在主对话外进行的请求的时间长度。此键适用于[subagent](/docs/zh-CN/sub-agents)、[工作流](/docs/zh-CN/workflows)和 Claude Code 自己的后台和助手请求，例如压缩和会话标题。一小时的生命周期在较长的中断中保持缓存温暖，API [以比五分钟生命周期更高的费率为每个缓存写入计费](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)。需要 Claude Code v2.1.242 或更高版本。1368选择[提示缓存](/docs/zh-CN/prompt-caching)保持 Claude Code 在主对话外进行的请求的时间长度。此键适用于[subagents](/docs/zh-CN/sub-agents)、[workflows](/docs/zh-CN/workflows) 和 Claude Code 自己的后台和助手请求，如压缩和会话标题。一小时的生命周期在较长的中断中保持缓存温暖，API [在五分钟生命周期的更高费率下计费每个缓存写入](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pricing)。需要 Claude Code v2.1.242 或更高版本。

1312 1369

1313* **Scope**: [`Any file`](#scopes)1370* **Scope**: [`Any file`](#scopes)

1314* **Type**: string，其中之一：1371* **Type**: string，其中一个：

1315 * `"5m"`: 缓存保持五分钟1372 * `"5m"`: 缓存保持五分钟

1316 * `"1h"`: 缓存保持一小时1373 * `"1h"`: 缓存保持一小时

1317* **Default**: 未设置，因此这些请求中的每一个都获得[其默认生命周期](/docs/zh-CN/prompt-caching#which-ttl-each-request-gets)1374* **Default**: 未设置，因此这些请求中的每一个获得[其默认生命周期](/docs/zh-CN/prompt-caching#which-ttl-each-request-gets)

1318* **Per-session overrides**: [`FORCE_PROMPT_CACHING_5M`](/docs/zh-CN/env-vars)优先于所有其他，然后[`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`](/docs/zh-CN/env-vars)，然后此键，然后[`ENABLE_PROMPT_CACHING_1H`](/docs/zh-CN/env-vars)，它要求每个请求的一小时生命周期。有关 subagent 自己的 frontmatter 值的排名，请参阅[自己选择 TTL](/docs/zh-CN/prompt-caching#choose-the-ttl-yourself)1375* **Per-session overrides**: [`FORCE_PROMPT_CACHING_5M`](/docs/zh-CN/env-vars)优先于所有其他，然后[`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`](/docs/zh-CN/env-vars)，然后此键，然后[`ENABLE_PROMPT_CACHING_1H`](/docs/zh-CN/env-vars)，它要求每个请求的一小时生命周期。关于 subagent 自己的 frontmatter 值的排名，请参阅[自己选择 TTL](/docs/zh-CN/prompt-caching#choose-the-ttl-yourself)

1319 1376

1320此示例为 subagent 和主对话外的其他请求提供一小时生命周期：1377此示例为 subagents 和主对话外的其他请求提供一小时生命周期：

1321 1378

1322```json settings.json theme={null}1379```json settings.json theme={null}

1323{1380{

1325}1382}

1326```1383```

1327 1384

1328此键涵盖[`promptCacheTtl`](#promptcachettl)不涵盖的请求，因此设置两者以为 Claude Code 进行的每个请求选择生命周期。有关 subagent 的缓存与主对话的缓存的不同之处，请参阅[Subagent 和缓存](/docs/zh-CN/prompt-caching#subagents-and-the-cache)。1385此键涵盖[`promptCacheTtl`](#promptcachettl)不涵盖的请求，因此设置两者以为 Claude Code 进行的每个请求选择生命周期。关于 subagent 的缓存与主对话的缓存的不同之处，请参阅[Subagents 和缓存](/docs/zh-CN/prompt-caching#subagents-and-the-cache)。

1329 1386

1330<h3 id="switchmodelsonflag">1387<h3 id="switchmodelsonflag">

1331 `switchModelsOnFlag`1388 `switchModelsOnFlag`

1336* **Scope**: [`Any file`](#scopes)。在 `/config` 中显示为**消息被标记时切换模型**。1393* **Scope**: [`Any file`](#scopes)。在 `/config` 中显示为**消息被标记时切换模型**。

1337* **Type**: Boolean1394* **Type**: Boolean

1338 * `true`: Claude Code 切换到备用模型并继续1395 * `true`: Claude Code 切换到备用模型并继续

1339 * `false`: 在交互式会话中，Claude Code 暂停以便您可以在切换和编辑提示之间选择；在无法显示对话的地方，例如 `-p` 运行，标记的请求以错误结束1396 * `false`: 在交互式会话中，Claude Code 暂停以便您可以在切换和编辑提示之间选择；在无法显示对话框的地方，如 `-p` 运行，标记的请求以错误结束

1340* **Default**: `true`，自动切换1397* **Default**: `true`，自动切换

1341 1398

1342```json settings.json theme={null}1399```json settings.json theme={null}

1345}1402}

1346```1403```

1347 1404

1348请参阅[切换前询问](/docs/zh-CN/model-config#ask-before-switching)。1405请参阅[在切换前询问](/docs/zh-CN/model-config#ask-before-switching)。

1349 1406

1350<h3 id="ultracode">1407<h3 id="ultracode">

1351 `ultracode`1408 `ultracode`

1352</h3>1409</h3>

1353 1410

1354使用[ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)启动会话。启用它后，Claude 为每个实质性任务规划工作流，而不是等待您要求。Claude 仅在为您启用[动态工作流](/docs/zh-CN/workflows)、您的模型支持 `xhigh` 努力且没有[努力上限](/docs/zh-CN/model-config#organization-effort-limits)低于 `xhigh` 时规划工作流。无论如何，`ultracode: true` 在 `xhigh` 努力或当努力上限较低时在上限处运行会话。Claude Code 读取此键但从不写入它：`/effort ultracode` 仅为当前会话打开 ultracode。1411使用[ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)启动会话。打开时，Claude 为每个实质性任务规划工作流，而不是等待您要求。Claude 仅在为您启用[动态工作流](/docs/zh-CN/workflows)且您的模型支持 `xhigh` 努力时规划工作流。该键不改变会话的努力级别：ultracode 在会话使用的任何级别处运行。Claude Code 读取此键但从不写入它：`/effort ultracode` 仅为当前会话打开 ultracode。

1355 1412

1356* **Scope**: [`Any file`](#scopes)1413* **Scope**: [`Any file`](#scopes)

1357* **Type**: Boolean1414* **Type**: Boolean

1358 * `true`: 会话以 `xhigh` 努力启动，当为您启用动态工作流、您的模型支持 `xhigh` 且没有努力上限低于 `xhigh` 时，ultracode 打开1415 * `true`: 当为您启用动态工作流且您的模型支持 `xhigh` 时，会话以 ultracode 打开启动

1359 * `false`: 会话以 ultracode 关闭启动1416 * `false`: 会话以 ultracode 关闭启动

1360* **Default**: 未设置，因此 ultracode 已关闭1417* **Default**: 未设置，因此 ultracode 已关闭

1361* **Per-session overrides**: `/effort ultracode` 在没有此键的情况下为一个会话打开 ultracode。`--effort ultracode` 标志也为一个会话打开它，需要 Claude Code v2.1.203 或更高版本1418* **Per-session overrides**: `/effort ultracode` 为一个会话打开 ultracode，不需要此键。`--effort ultracode` 标志也为一个会话打开它，在 `xhigh` 努力处，需要 Claude Code v2.1.203 或更高版本

1362 1419

1363```json settings.json theme={null}1420```json settings.json theme={null}

1364{1421{

1366}1423}

1367```1424```

1368 1425

1369Ultracode 在 `xhigh` 努力处运行会话，优先于 `effortLevel` 和[`modelSettings`](#modelsettings)条目。如果[努力上限](/docs/zh-CN/model-config#organization-effort-limits)低于 `xhigh` 适用于模型，例如[`maxEffortLevel`](#maxeffortlevel)设置，会话改为在上限处运行，ultracode 保持关闭。Claude 然后不会自己规划工作流，`/effort` 不提供 `ultracode`。Agent SDK `apply_flag_settings` 控制请求也接受该键。1426会话的努力级别来自[`effortLevel`](#effortlevel)、[`modelSettings`](#modelsettings) 和其他[努力源](/docs/zh-CN/model-config#adjust-effort-level)，[努力上限](/docs/zh-CN/model-config#organization-effort-limits)如[`maxEffortLevel`](#maxeffortlevel)降低该级别而不关闭 ultracode。这和 `/effort ultracode off` 形式需要 Claude Code v2.1.284 或更高版本。在 v2.1.284 之前，`ultracode: true` 在 `xhigh` 努力处运行会话，低于 `xhigh` 的努力上限使 ultracode 在上限适用的模型上不可用。Agent SDK `apply_flag_settings` 控制请求也接受该键。

1370 1427

1371<h2 id="permission-settings">1428<h2 id="permission-settings">

1372 权限设置1429 权限设置

1426 `autoMode.classifyAllShell`1483 `autoMode.classifyAllShell`

1427</h3>1484</h3>

1428 1485

1429在自动模式处于活动状态时，通过自动模式分类器发送每个 Bash 和 PowerShell 命令。默认情况下，自动模式仅暂停可能运行任意代码的允许规则：工具范围和通配符规则（如 `Bash(*)`）以及解释器或 shell 包装器前缀（如 `Bash(python *)`）。任何其他允许规则匹配的命令（如 `Bash(npm test)`）会跳过分类器，除非它携带[每命令允许的域](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)，规则的前缀未预期的破坏性参数可能会被看不见地通过。设置此键会为会话暂停每个 shell 允许规则，以便分类器看到每个命令。需要 Claude Code v2.1.193 或更高版本。1486在自动模式处于活动状态时，通过自动模式分类器发送每个 Bash 和 PowerShell 命令。默认情况下，自动模式仅暂停可能运行任意代码的允许规则：工具范围和通配符规则（如 `Bash(*)`）以及解释器或 shell 包装器前缀（如 `Bash(python *)`）。任何其他允许规则匹配的命令（如 `Bash(npm test)`）会跳过分类器，除非它携带[每命令允许的域](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)。当它跳过时，规则的前缀未预期的破坏性参数可能会被看不见地通过。设置此键会为会话暂停每个 shell 允许规则，以便分类器看到每个命令。需要 Claude Code v2.1.193 或更高版本。

1430 1487

1431* **作用域**: [`User or managed`](#scopes)。在读取 [`autoMode`](#automode) 的任何地方读取。1488* **作用域**: [`User or managed`](#scopes)。在读取 [`autoMode`](#automode) 的任何地方读取。

1432* **类型**: 布尔值1489* **类型**: 布尔值

1489 `useAutoModeDuringPlan`1546 `useAutoModeDuringPlan`

1490</h3>1547</h3>

1491 1548

1492选择 Claude Code 是否使用自动模式分类器在计划模式下审查 shell 命令。使用默认值 `true`，分类器在规划期间审查每个命令，当自动模式可用且您看不到提示时。设置 `false` 以获得内置只读集之外的每个命令的权限提示。在 `/config` 中显示为**在计划期间使用自动模式**。1549选择 Claude Code 是否使用自动模式分类器在计划模式下审查 shell 命令。使用默认值 `true`，分类器在规划期间审查每个命令，当自动模式可用且您看不到提示时，除了[关键路径移除](/docs/zh-CN/permission-modes#critical-paths)。设置 `false` 以获得内置只读集之外的每个命令的权限提示。在 `/config` 中显示为**在计划期间使用自动模式**。

1493 1550

1494* **作用域**: [`User, local, or managed`](#scopes)。存储库无法为您关闭它。1551* **作用域**: [`User, local, or managed`](#scopes)。存储库无法为您关闭它。

1495* **类型**: 布尔值1552* **类型**: 布尔值

1496 * `true`：与未设置相同；当自动模式可用时，分类器在规划期间审查每个 shell 命令，而不是提示您。任何这些文件中的 `false` 仍然会关闭它1553 * `true`：与未设置相同；当自动模式可用时，分类器在规划期间审查每个 shell 命令，而不是提示您，除了[关键路径移除](/docs/zh-CN/permission-modes#critical-paths)。任何这些文件中的 `false` 仍然会关闭它

1497 * `false`：您会获得内置只读集之外的每个命令的权限提示1554 * `false`：您会获得内置只读集之外的每个命令的权限提示

1498* **默认值**: `true`1555* **默认值**: `true`

1499 1556

1617 `permissions.blockReadsOutsideWorkingDirectories`1674 `permissions.blockReadsOutsideWorkingDirectories`

1618</h3>1675</h3>

1619 1676

1620阻止 Claude 在每个权限模式（包括 `bypassPermissions`）中使用 Read、Grep、Glob 和 LSP 工具读取会话[工作目录](/docs/zh-CN/permissions#working-directories)之外的路径。通过 Claude Code 识别的文件命令（如 `cat`）读取匹配路径的 Bash 命令会在自动模式和 `bypassPermissions` 模式中提示您。需要 Claude Code v2.1.257 或更高版本。1677在每个权限模式（包括 `bypassPermissions`）中，使 Claude 的文件工具拒绝在您的[工作目录](/docs/zh-CN/permissions#working-directories)之外的读取。Claude Code 拒绝这些路径上的 `Read`、`Grep`、`Glob` 和 `LSP` 调用，并告诉 Claude 要求您使用 `/add-dir` 添加目录。Claude Code 本身需要的文件保持可读，如您的技能、插件、规则、代理、命令以及 `~/.claude/` 下的 `CLAUDE.md` 内存文件。需要 Claude Code v2.1.257 或更高版本。

1678

1679Claude Code 不会以相同的方式拒绝 shell 命令：

1680

1681* [没有模式自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)涵盖了读取此类路径的 shell 命令何时提示您

1682* [块下的沙箱命令](#sandboxed-commands-under-the-block)涵盖了沙箱命令可以读取的内容

1621 1683

1622shell 解析器无法追踪的 Bash 命令（如多次更改目录或运行子 shell 的命令）会在自动模式和 `bypassPermissions` 模式中提示您。即使命令未命名工作目录之外的任何路径，提示也会出现。当命令在[沙箱](/docs/zh-CN/sandboxing)中运行且沙箱强制执行该块时，此提示不适用。1684shell 解析器无法追踪的 Bash 命令（如多次更改目录或运行子 shell 的命令）会在自动模式和 `bypassPermissions` 模式中提示您。即使命令未命名工作目录之外的任何路径，提示也会出现。当命令在[沙箱](/docs/zh-CN/sandboxing)中运行且沙箱强制执行该块时，此提示不适用。

1623 1685

1624Claude Code 也会在此处写入 `true`，当您选择在[自动模式的提示中阻止此类读取（在第一次读取工作目录之外之前）](/docs/zh-CN/permission-modes#first-read-outside-the-working-directories)时。1686Claude Code 也会在此处写入 `true`，当您选择在[自动模式的提示中阻止此类读取（在第一次读取工作目录之外之前）](/docs/zh-CN/permission-modes#first-read-outside-the-working-directories)时。

1625 1687

1626* **作用域**: [`Any file`](#scopes)。如果任何设置源设置 `true`，则应用该块，因此存储库的签入文件可以为项目打开该块，但无法解除您设置的块。1688* **作用域**: [`Any file`](#scopes)。任何文件中的 `true` 都会应用，因此存储库可以为自己打开该块，但无法解除您设置的块。

1627* **类型**: 布尔值1689* **类型**: 布尔值

1628 * `true`：阻止工作目录之外的文件读取1690 * `true`：Claude 的文件工具拒绝在工作目录之外的读取

1629 * `false`：与未设置相同；任何其他设置文件中的 `true` 仍然会阻止1691 * `false`：与未设置相同；另一个文件中的块仍然适用如果它设置 `true`

1630* **默认值**: 未设置，因此工作目录之外的读取遵循您的权限模式和规则1692* **默认值**: 未设置，因此工作目录之外的读取遵循您的[权限模式](/docs/zh-CN/permission-modes)

1631 1693

1632```json settings.json theme={null}1694```json settings.json theme={null}

1633{1695{

1637}1699}

1638```1700```

1639 1701

1640如果仅存储库的签入设置文件添加目录，该块仍然适用于那里的读取。当 [`autoMemoryDirectory`](#automemorydirectory) 来自项目的 `.claude/settings.json`，或来自被[视为存储库提供的](/docs/zh-CN/permissions#when-your-local-settings-file-needs-trust) `.claude/settings.local.json` 时，Claude Code 不会从该目录加载任何[自动内存](/docs/zh-CN/memory#storage-location)，也不会保存任何到其中。Claude Code 本身需要的文件保持可读，如您的技能、插件、规则、代理、命令以及 `~/.claude/` 下的 `CLAUDE.md` 内存文件。1702您使用 `--add-dir`、`/add-dir` 或用户或托管设置中的 `additionalDirectories` 添加的目录计为该块的工作目录。仅在存储库设置中添加的目录不计：那些在 `.claude/settings.json` 中的，以及在 `.claude/settings.local.json` 中的，除非 git 报告该文件为未跟踪。在不是 git 存储库的目录中，或当 git 跟踪该文件时，Claude Code 将 `.claude/settings.local.json` 视为存储库设置，因此改为在用户设置中放置您想保持可读的目录。

1703

1704当 [`autoMemoryDirectory`](#automemorydirectory) 来自项目的 `.claude/settings.json`，或来自被[视为存储库提供的](/docs/zh-CN/permissions#when-your-local-settings-file-needs-trust) `.claude/settings.local.json` 时，Claude Code 不会从该目录加载任何[自动内存](/docs/zh-CN/memory#storage-location)，也不会保存任何到其中。

1705

1706要解除该块，从设置它的每个设置文件中删除该键，然后启动新会话。

1707

1708<h4 id="sandboxed-commands-under-the-block">

1709 块下的沙箱命令

1710</h4>

1641 1711

1642当[沙箱](/docs/zh-CN/sandboxing)打开时，该块也会拒绝沙箱命令对工作目录之外的主目录和挂载卷根的读取访问。需要批准以[在沙箱外运行](/docs/zh-CN/sandboxing#the-unsandboxed-retry-escape-hatch)的重试会在 `bypassPermissions` 模式中提示您。工具从您的主目录读取的文件（如 `~/.gitconfig`）与其余文件一起被拒绝；当工具需要它时，使用 [`sandbox.filesystem.allowRead`](#sandbox-filesystem-allowread) 重新打开特定路径。1712当[沙箱](/docs/zh-CN/sandboxing)打开时，该块也涵盖沙箱命令。Claude Code 拒绝它们对您的主目录和保存用户文件的其他根的读取访问：`/Users`、`/home`、`/root`、`/Volumes`、`/mnt`、`/media`、`/run/media` 和 `/srv`。然后它重新打开工作目录、[worktrees](/docs/zh-CN/worktrees) Claude Code 在会话中创建的、会话临时目录以及 `~/.claude` 的命令需要的部分，如技能和插件。当该块生效时，来自存储库设置的 `allowRead` 和 `allowWrite` 条目不计。

1643 1713

1644当会话的工作目录是链接的 [git worktree](/docs/zh-CN/worktrees)（包括 Claude Code 在会话中途进入的）时，存储库的公共 `.git` 目录对沙箱命令保持可读和可写，因此 git 在那里继续工作。1714当会话的工作目录是链接的 [git worktree](/docs/zh-CN/worktrees)（包括 Claude Code 在会话中途进入的）时，存储库的公共 `.git` 目录对沙箱命令保持可读和可写，因此 git 在那里继续工作。

1645 1715

1716在这些情况下，该块不会到达沙箱命令，而 Claude 的文件工具继续强制执行它：

1717

1718* 文件系统隔离通过 [`sandbox.filesystem.disabled`](#sandbox-filesystem-disabled) 关闭

1719* [`allowManagedReadPathsOnly`](#sandbox-filesystem-allowmanagedreadpathsonly) 已设置

1720* 您启动 Claude Code 的目录的路径包含 glob 字符，如 `*`、`?` 或 `[`

1721

1722在该块下，Claude Code 重新打开您的全局 git 配置文件到沙箱命令，以便 `git` 保持您的身份和设置：

1723

1724* `~/.gitconfig`

1725* `$XDG_CONFIG_HOME/git` 下的 `config`、`ignore` 和 `attributes` 文件，默认为 `~/.config/git`

1726* 您的全局 git 配置通过 `[include]`、`[includeIf]`、`core.excludesFile` 或 `core.attributesFile` 命名的文件

1727

1728Claude Code 单独判断每个文件。当文件位于沙箱命令可以写入的地方（直接或通过符号链接）时，Claude Code 不会重新打开它命名的文件。

1729

1730在 Linux 和 WSL2 上，作为符号链接的配置文件可以在其自己的路径处保持不可读，然后 `git` 在没有它的情况下运行。`~/.git-credentials` 和 `$XDG_CONFIG_HOME/git/credentials` 保持被阻止。

1731

1732如果重新打开的文件保存机密，如 `http.extraHeader` 令牌，将其路径添加到 [`sandbox.filesystem.denyRead`](#sandbox-filesystem-denyread)。覆盖此重新打开的 `denyRead` 条目始终优先。

1733

1646<h3 id="permissions-defaultmode">1734<h3 id="permissions-defaultmode">

1647 `permissions.defaultMode`1735 `permissions.defaultMode`

1648</h3>1736</h3>

1649 1737

1650设置新会话启动的[权限模式](/docs/zh-CN/permission-modes)。当您将其留空时，会话会以您的计划和表面的[内置默认值](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)启动。1738设置新会话启动的[权限模式](/docs/zh-CN/permission-modes)。当您将其留空时，会话会以您的表面的[内置默认值](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)启动。

1651 1739

1652* **作用域**: [`Any file`](#scopes)。`auto` 和 `bypassPermissions` 不会从项目或本地设置生效，因此改为在 `~/.claude/settings.json` 中设置它们。在 v2.1.257 之前，`bypassPermissions` 从任何文件生效。对于 VS Code 扩展启动的对话，Claude Code 仅读取用户、托管和 `--settings` 值。1740* **作用域**: [`Any file`](#scopes)。`auto` 和 `bypassPermissions` 不会从项目或本地设置生效，因此改为在 `~/.claude/settings.json` 中设置它们。在 v2.1.257 之前，`bypassPermissions` 从任何文件生效。对于 VS Code 扩展启动的对话，Claude Code 仅读取用户、托管和 `--settings` 值。

1653* **类型**: 字符串，以下之一：1741* **类型**: 字符串，以下之一：

1968}2056}

1969```2057```

1970 2058

1971Claude Code 在会话加载的每个设置范围中合并条目：用户、项目、本地和托管路径组合而不是替换彼此，Claude Code 添加您的 `Edit(...)` 允许权限规则中的路径。`allowWrite` 条目不能提升 [protected path](/docs/zh-CN/sandboxing#protected-paths)。2059Claude Code 在会话加载的每个设置范围中合并 `allowWrite` 条目和您的 `Edit(...)` 允许权限规则中的路径，在 [`permissions.blockReadsOutsideWorkingDirectories`](#sandboxed-commands-under-the-block) 打开时留出存储库设置中的条目。`allowWrite` 条目不能提升 [protected path](/docs/zh-CN/sandboxing#protected-paths)。

1972 2060

1973<h3 id="sandbox-filesystem-denywrite">2061<h3 id="sandbox-filesystem-denywrite">

1974 `sandbox.filesystem.denyWrite`2062 `sandbox.filesystem.denyWrite`

2039}2127}

2040```2128```

2041 2129

2042Claude Code 在项目设置中将 `.` 条目解析为项目根目录，在用户设置中解析为 `~/.claude`。Claude Code 在会话加载的每个设置文件中合并条目，除非设置了 [`allowManagedReadPathsOnly`](#sandbox-filesystem-allowmanagedreadpathsonly)。2130Claude Code 在项目设置中将 `.` 条目解析为项目根目录，在用户设置中解析为 `~/.claude`。Claude Code 在会话加载的每个设置文件中合并条目，除非设置了 [`allowManagedReadPathsOnly`](#sandbox-filesystem-allowmanagedreadpathsonly)，并在 [`permissions.blockReadsOutsideWorkingDirectories`](#sandboxed-commands-under-the-block) 打开时留出存储库设置中的条目。

2043 2131

2044<h3 id="sandbox-filesystem-allowmanagedreadpathsonly">2132<h3 id="sandbox-filesystem-allowmanagedreadpathsonly">

2045 `sandbox.filesystem.allowManagedReadPathsOnly`2133 `sandbox.filesystem.allowManagedReadPathsOnly`

2254 `sandbox.credentials`2342 `sandbox.credentials`

2255</h3>2343</h3>

2256 2344

2257声明凭证文件和环境变量以 [protect from sandboxed commands](/docs/zh-CN/sandboxing#protect-credentials)。每个条目命名文件 `path` 或变量 `name` 和 `mode`：`deny` 在沙箱内隐藏凭证，`mask` 向沙箱化命令显示占位符，同时 [sandbox proxy](/docs/zh-CN/sandboxing#mask-credentials) 在出站请求上替换真实值。Claude Code 仅保护您列出的条目；没有内置凭证拒绝列表。需要 Claude Code v2.1.187 或更高版本。2345声明凭证文件和环境变量以 [protect from sandboxed commands](/docs/zh-CN/sandboxing#protect-credentials)。每个条目命名文件 `path` 或变量 `name` 和 `mode`：`deny` 在沙箱内隐藏凭证，`mask` 向沙箱化命令显示占位符，同时 [sandbox proxy](/docs/zh-CN/sandboxing#mask-credentials) 在出站请求上替换真实值。Claude Code 仅保护您列出的条目；没有内置凭证拒绝列表。

2258 2346

2259* **Scope**: [`Any file`](#scopes)。Claude Code 仅从用户设置、托管设置和 `--settings` 标志遵守 `mask` 条目、`allowPlaintextInject`、`awsPairs` 和 `sigv4`。2347* **Scope**: [`Any file`](#scopes)。Claude Code 仅从用户设置、托管设置和 `--settings` 标志遵守 `mask` 条目、`allowPlaintextInject`、`awsPairs` 和 `sigv4`。

2260* **Type**: 对象，包含 `files`、`envVars`、`allowPlaintextInject`、`awsPairs` 和 `sigv4`2348* **Type**: 对象，包含 `files`、`envVars`、`allowPlaintextInject`、`awsPairs` 和 `sigv4`

2273}2361}

2274```2362```

2275 2363

2276`deny` 文件保护是文件系统层的一部分，因此当您 [disable filesystem isolation](/docs/zh-CN/sandboxing#disable-filesystem-isolation) 时不适用；环境变量保护仍然适用。需要 Claude Code v2.1.187 或更高版本。2364`deny` 文件保护是文件系统层的一部分，因此当您 [disable filesystem isolation](/docs/zh-CN/sandboxing#disable-filesystem-isolation) 时不适用；环境变量保护仍然适用。

2277 2365

2278<h4 id="invalid-credential-entries-in-managed-settings">2366<h4 id="invalid-credential-entries-in-managed-settings">

2279 托管设置中的无效凭证条目2367 托管设置中的无效凭证条目

2291 `sandbox.credentials.files`2379 `sandbox.credentials.files`

2292</h3>2380</h3>

2293 2381

2294保护凭证文件或目录免受沙箱化命令。使用 `"mode": "deny"`，Claude Code 阻止在沙箱内读取路径，与 [`sandbox.filesystem.denyRead`](#sandbox-filesystem-denyread) 相同的读取块。使用 `"mode": "mask"`，Linux 和 WSL2 上的沙箱化命令读取文件的哨兵副本，沙箱代理在对该条目的 `injectHosts` 的出站请求上替换真实值；在 macOS 上，文件在沙箱内不可读。需要 Claude Code v2.1.187 或更高版本，`"mode": "mask"` 需要 v2.1.221 或更高版本。2382保护凭证文件或目录免受沙箱化命令。使用 `"mode": "deny"`，Claude Code 阻止在沙箱内读取路径，与 [`sandbox.filesystem.denyRead`](#sandbox-filesystem-denyread) 相同的读取块。使用 `"mode": "mask"`，Linux 和 WSL2 上的沙箱化命令读取文件的哨兵副本，沙箱代理在对该条目的 `injectHosts` 的出站请求上替换真实值；在 macOS 上，文件在沙箱内不可读。`"mode": "mask"` 需要 Claude Code v2.1.221 或更高版本。

2295 2383

2296* **Scope**: [`Any file`](#scopes)。Claude Code 从项目 `.claude/settings.json` 和本地 `.claude/settings.local.json` 删除 `mask` 条目。2384* **Scope**: [`Any file`](#scopes)。Claude Code 从项目 `.claude/settings.json` 和本地 `.claude/settings.local.json` 删除 `mask` 条目。

2297* **Type**: 对象数组，每个包含 `path` 和 `"deny"` 或 `"mask"` 的 `mode`，加上可选的 [mask fields for files](#mask-fields-for-files)2385* **Type**: 对象数组，每个包含 `path` 和 `"deny"` 或 `"mask"` 的 `mode`，加上可选的 [mask fields for files](#mask-fields-for-files)

2312}2400}

2313```2401```

2314 2402

2315路径使用与 `sandbox.filesystem.*` 设置相同的 [prefixes](#sandbox-path-prefixes)，Claude Code 在会话加载的每个设置范围中合并数组。[Protect credentials](/docs/zh-CN/sandboxing#protect-credentials) 涵盖您使用 `--setting-sources` 排除的源仍然适用的内容。需要 Claude Code v2.1.187 或更高版本；`mask` 条目需要 v2.1.221 或更高版本。2403路径使用与 `sandbox.filesystem.*` 设置相同的 [prefixes](#sandbox-path-prefixes)，Claude Code 在会话加载的每个设置范围中合并数组。[Protect credentials](/docs/zh-CN/sandboxing#protect-credentials) 涵盖您使用 `--setting-sources` 排除的源仍然适用的内容。`mask` 条目需要 Claude Code v2.1.221 或更高版本。

2316 2404

2317`mask` 替换仅通过沙箱代理运行，因此设置 [`sandbox.network.tlsTerminate`](#sandbox-network-tlsterminate) 或 [`allowPlaintextInject`](#sandbox-credentials-allowplaintextinject) 用于纯 HTTP 测试网络。`mask` 适用于单个文件，因此单独列出每个凭证文件。Claude Code 接受但忽略 `deny` 条目上的 `mask` 字段。[Mask credential files](/docs/zh-CN/sandboxing#mask-credential-files) 涵盖遵守哪些设置源以及条目何时回退到 `deny`。2405`mask` 替换仅通过沙箱代理运行，因此设置 [`sandbox.network.tlsTerminate`](#sandbox-network-tlsterminate) 或 [`allowPlaintextInject`](#sandbox-credentials-allowplaintextinject) 用于纯 HTTP 测试网络。`mask` 适用于单个文件，因此单独列出每个凭证文件。Claude Code 接受但忽略 `deny` 条目上的 `mask` 字段。[Mask credential files](/docs/zh-CN/sandboxing#mask-credential-files) 涵盖遵守哪些设置源以及条目何时回退到 `deny`。

2318 2406

2368 `sandbox.credentials.envVars`2456 `sandbox.credentials.envVars`

2369</h3>2457</h3>

2370 2458

2371保护环境变量免受沙箱化命令。使用 `"mode": "deny"`，Claude Code 从沙箱化命令的环境中删除变量。使用 `"mode": "mask"`，沙箱化命令看到每个会话的哨兵值，沙箱代理在对该条目的 `injectHosts` 的出站请求上替换真实值，因此 `gh` 和 `npm` 等工具保持认证而无需持有真实凭证。需要 Claude Code v2.1.187 或更高版本，`"mode": "mask"` 需要 v2.1.199 或更高版本。2459保护环境变量免受沙箱化命令。使用 `"mode": "deny"`，Claude Code 从沙箱化命令的环境中删除变量。使用 `"mode": "mask"`，沙箱化命令看到每个会话的哨兵值，沙箱代理在对该条目的 `injectHosts` 的出站请求上替换真实值，因此 `gh` 和 `npm` 等工具保持认证而无需持有真实凭证。`"mode": "mask"` 需要 Claude Code v2.1.199 或更高版本。

2372 2460

2373* **Scope**: [`Any file`](#scopes)。Claude Code 从项目 `.claude/settings.json` 和本地 `.claude/settings.local.json` 删除 `mask` 条目。2461* **Scope**: [`Any file`](#scopes)。Claude Code 从项目 `.claude/settings.json` 和本地 `.claude/settings.local.json` 删除 `mask` 条目。

2374* **Type**: 对象数组，每个包含 `name` 和 `"deny"` 或 `"mask"` 的 `mode`，加上可选的 [mask fields for environment variables](#mask-fields-for-environment-variables)2462* **Type**: 对象数组，每个包含 `name` 和 `"deny"` 或 `"mask"` 的 `mode`，加上可选的 [mask fields for environment variables](#mask-fields-for-environment-variables)

2389}2477}

2390```2478```

2391 2479

2392`name` 必须以字母或下划线开头，仅包含字母、数字和下划线。Claude Code 在会话加载的每个设置范围中合并数组，当同一变量同时出现两种模式时应用 `deny`。[Protect credentials](/docs/zh-CN/sandboxing#protect-credentials) 涵盖您使用 `--setting-sources` 排除的源仍然适用的内容。需要 Claude Code v2.1.187 或更高版本；`mask` 条目需要 v2.1.199 或更高版本。2480`name` 必须以字母或下划线开头，仅包含字母、数字和下划线。Claude Code 在会话加载的每个设置范围中合并数组，当同一变量同时出现两种模式时应用 `deny`。[Protect credentials](/docs/zh-CN/sandboxing#protect-credentials) 涵盖您使用 `--setting-sources` 排除的源仍然适用的内容。`mask` 条目需要 Claude Code v2.1.199 或更高版本。

2393 2481

2394`mask` 替换仅通过沙箱代理运行，因此设置 [`sandbox.network.tlsTerminate`](#sandbox-network-tlsterminate) 或 [`allowPlaintextInject`](#sandbox-credentials-allowplaintextinject) 用于纯 HTTP 测试网络；请参阅 [Mask environment variables](/docs/zh-CN/sandboxing#mask-environment-variables)。Claude Code 接受但忽略 `deny` 条目上的 `mask` 字段。2482`mask` 替换仅通过沙箱代理运行，因此设置 [`sandbox.network.tlsTerminate`](#sandbox-network-tlsterminate) 或 [`allowPlaintextInject`](#sandbox-credentials-allowplaintextinject) 用于纯 HTTP 测试网络；请参阅 [Mask environment variables](/docs/zh-CN/sandboxing#mask-environment-variables)。Claude Code 接受但忽略 `deny` 条目上的 `mask` 字段。

2395 2483

3015* [`CLAUDE_CODE_MESSAGING_SOCKET` 和 `CLAUDE_CODE_MESSAGING_TOKEN`](/docs/zh-CN/env-vars#variables)，Claude Code 自己导出的，从每个文件中被忽略。忽略套接字变量需要 Claude Code v2.1.224 或更高版本，忽略令牌需要 v2.1.228 或更高版本。3103* [`CLAUDE_CODE_MESSAGING_SOCKET` 和 `CLAUDE_CODE_MESSAGING_TOKEN`](/docs/zh-CN/env-vars#variables)，Claude Code 自己导出的，从每个文件中被忽略。忽略套接字变量需要 Claude Code v2.1.224 或更高版本，忽略令牌需要 v2.1.228 或更高版本。

3016* [`CLAUDE_CODE_PROJECT_DIR_NAME`](/docs/zh-CN/sessions#name-the-project-directory-yourself)，Claude Code 仅从启动环境读取，从每个文件中被忽略；需要 v2.1.234 或更高版本。3104* [`CLAUDE_CODE_PROJECT_DIR_NAME`](/docs/zh-CN/sessions#name-the-project-directory-yourself)，Claude Code 仅从启动环境读取，从每个文件中被忽略；需要 v2.1.234 或更高版本。

3017* [`CLAUDE_CODE_RESTRICTED`](/docs/zh-CN/env-vars#variables)，Claude Code 仅从启动环境读取，从每个文件中被忽略。3105* [`CLAUDE_CODE_RESTRICTED`](/docs/zh-CN/env-vars#variables)，Claude Code 仅从启动环境读取，从每个文件中被忽略。

3106* [`CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY`](/docs/zh-CN/env-vars#variables)，Claude Code 仅从启动环境读取，从每个文件中被忽略。该变量需要 Claude Code v2.1.283 或更高版本。

3107* [`CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` 和 `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT`](/docs/zh-CN/env-vars#variables)，Claude Code 仅从启动环境读取，从每个文件中被忽略。

3018 3108

3019<h3 id="filecheckpointingenabled">3109<h3 id="filecheckpointingenabled">

3020 `fileCheckpointingEnabled`3110 `fileCheckpointingEnabled`

3414* **Type**: string，`"classic"` 或 `"readline"`3504* **Type**: string，`"classic"` 或 `"readline"`

3415* **Default**: unset3505* **Default**: unset

3416 3506

3507<h3 id="maxprosewidth">

3508 `maxProseWidth`

3509</h3>

3510

3511限制 Claude 响应中散文的宽度，使行在宽终端中保持可读性。段落、标题、列表和块引用在此列数内换行，而表格和代码块保持完整的终端宽度。需要 Claude Code v2.1.282 或更高版本。

3512

3513* **Scope**: [`Any file`](#scopes)

3514* **Type**: 终端列数，整数，最小 `40`。Claude Code 忽略任何其他值

3515* **Default**: unset，所以散文在终端边缘换行

3516

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

3518{

3519 "maxProseWidth": 80

3520}

3521```

3522

3417<h3 id="prefersreducedmotion">3523<h3 id="prefersreducedmotion">

3418 `prefersReducedMotion`3524 `prefersReducedMotion`

3419</h3>3525</h3>

3475 `respondToBashCommands`3581 `respondToBashCommands`

3476</h3>3582</h3>

3477 3583

3478选择在您使用输入框中的 [`!` 前缀](/docs/zh-CN/interactive-mode#shell-mode-with-prefix)运行 shell 命令后 Claude 是否响应。默认情况下，Claude Code 将命令的输出添加到对话中，Claude 对其进行回复。将此键设置为 `false` 以将输出添加到上下文而不进行回复，以便您可以运行多个命令并一起询问它们。需要 Claude Code v2.1.186 或更高版本。3584选择在您使用输入框中的 [`!` 前缀](/docs/zh-CN/interactive-mode#shell-mode-with-prefix)运行 shell 命令后 Claude 是否响应。默认情况下，Claude Code 将命令的输出添加到对话中，Claude 对其进行回复。将此键设置为 `false` 以将输出添加到上下文而不进行回复，以便您可以运行多个命令并一起询问它们。

3479 3585

3480* **Scope**: [`Any file`](#scopes)3586* **Scope**: [`Any file`](#scopes)

3481* **Type**: Boolean3587* **Type**: Boolean

3489}3595}

3490```3596```

3491 3597

3492请参阅[使用 `!` 前缀的 Shell 模式](/docs/zh-CN/interactive-mode#shell-mode-with-prefix)。需要 Claude Code v2.1.186 或更高版本。3598请参阅[使用 `!` 前缀的 Shell 模式](/docs/zh-CN/interactive-mode#shell-mode-with-prefix)。

3493 3599

3494<h3 id="showclearcontextonplanaccept">3600<h3 id="showclearcontextonplanaccept">

3495 `showClearContextOnPlanAccept`3601 `showClearContextOnPlanAccept`

4088 4194

4089* **Scope**: [`Any file`](#scopes)4195* **Scope**: [`Any file`](#scopes)

4090* **Type**: 字符串4196* **Type**: 字符串

4091* **Default**: 未设置，因此 Claude Code 添加 `Co-Authored-By: <name> <noreply@anthropic.com>`。名称是会话的活跃模型，例如 `Claude Sonnet 5`。4197* **Default**: 未设置，因此 Claude Code 添加 `Co-Authored-By: <name> <noreply@anthropic.com>`。名称是进行提交时使用的模型，例如 `Claude Sonnet 5`。当 [subagent](/docs/zh-CN/sub-agents) 进行提交时，trailer 命名 subagent 的模型。

4092 * 当 Claude Code 识别模型为 Claude 模型但无法确认其确切版本时，它单独写入 `Claude`。4198 * 当 Claude Code 识别模型为 Claude 模型但无法确认其确切版本时，它单独写入 `Claude`。

4093 * 当它无法将模型 ID 匹配到任何 Claude 模型（例如通过自定义 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 提供的第三方模型）时，它写入 `Claude Code`。4199 * 当它无法将模型 ID 匹配到任何 Claude 模型（例如通过自定义 [`ANTHROPIC_BASE_URL`](/docs/zh-CN/env-vars) 提供的第三方模型）时，它写入 `Claude Code`。

4094 4200

4796 `strictPluginOnlyCustomization.skills`4902 `strictPluginOnlyCustomization.skills`

4797</h3>4903</h3>

4798 4904

4799锁定 `skills` 表面。Claude Code 停止从 `~/.claude/skills/` 和 `.claude/skills/` 加载 skills，从 `~/.claude/commands/` 和 `.claude/commands/` 加载自定义命令，从 `--add-dir` 目录加载 skills，从您的 claude.ai 账户同步的 skills，并继续加载 plugin skills、捆绑的 skills 和托管策略目录中的 skills。4905锁定 `skills` 表面。Claude Code 停止从 `~/.claude/skills/` 和 `.claude/skills/` 加载 skills，从 `~/.claude/commands/` 和 `.claude/commands/` 加载自定义命令，从 `--add-dir` 目录加载 skills 和命令，从您的 claude.ai 账户同步的 skills。它继续加载 plugin skills、捆绑的 skills 和托管策略目录中的 skills。

4800 4906

4801* **Scope**: [`Managed`](#scopes)4907* **Scope**: [`Managed`](#scopes)

4802* **Type**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 数组中的字符串 `"skills"`4908* **Type**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 数组中的字符串 `"skills"`

4812 `strictPluginOnlyCustomization.agents`4918 `strictPluginOnlyCustomization.agents`

4813</h3>4919</h3>

4814 4920

4815锁定 `agents` 表面。Claude Code 停止从 `~/.claude/agents/` 和 `.claude/agents/` 加载 agents，并继续加载 plugin agents、内置 agents 和托管策略目录中的 agents。4921锁定 `agents` 表面。Claude Code 停止从 `~/.claude/agents/`、`.claude/agents/` 和 `--add-dir` 目录加载 agents。它继续加载 plugin agents、内置 agents 和托管策略目录中的 agents。

4816 4922

4817* **Scope**: [`Managed`](#scopes)4923* **Scope**: [`Managed`](#scopes)

4818* **Type**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 数组中的字符串 `"agents"`4924* **Type**: [`strictPluginOnlyCustomization`](#strictpluginonlycustomization) 数组中的字符串 `"agents"`

5343 * `"in-process"`: 队友在您的主终端窗格内运行5449 * `"in-process"`: 队友在您的主终端窗格内运行

5344 * `"auto"`: 当您在 tmux 内运行时分割窗格，或在 iTerm2 内运行且 `it2` 在您的 `PATH` 上或安装了 tmux；否则为进程内5450 * `"auto"`: 当您在 tmux 内运行时分割窗格，或在 iTerm2 内运行且 `it2` 在您的 `PATH` 上或安装了 tmux；否则为进程内

5345 * `"tmux"`: 使用 tmux 或 iTerm2 分割窗格，从您的终端检测5451 * `"tmux"`: 使用 tmux 或 iTerm2 分割窗格，从您的终端检测

5346 * `"iterm2"`: iTerm2 本机分割窗格通过 `it2` CLI，在 Claude Code v2.1.186 或更高版本中5452 * `"iterm2"`: iTerm2 本机分割窗格通过 `it2` CLI

5347* **Default**: `"in-process"`5453* **Default**: `"in-process"`

5348* **Per-session overrides**: `--teammate-mode` 对此密钥的一个会话优先级更高5454* **Per-session overrides**: `--teammate-mode` 对此密钥的一个会话优先级更高

5349 5455

5353}5459}

5354```5460```

5355 5461

5356`iterm2` 值需要 Claude Code v2.1.186 或更高版本。

~~5357~~

5358<span id="worktree-settings" />5462<span id="worktree-settings" />

5359 5463

5360<h3 id="worktree">5464<h3 id="worktree">

5690* **类型**: 布尔值5794* **类型**: 布尔值

5691 * `true`: Claude Code 在每个交互式会话启动时自动连接远程控制5795 * `true`: Claude Code 在每个交互式会话启动时自动连接远程控制

5692 * `false`: Claude Code 等待 `/remote-control`5796 * `false`: Claude Code 等待 `/remote-control`

5693* **默认值**: 未设置，因此自动连接遵循你的组织的管理员默认值（如果已设置），否则遵循 Claude Code 的当前默认值5797* **默认值**: 未设置，因此[自动连接默认值](/docs/zh-CN/remote-control#enable-remote-control-for-all-sessions)适用

5694* **每个会话的覆盖**: `--remote-control` 即使此键为 `false` 也会为一个会话打开远程控制，没有标志会为一个会话关闭它5798* **每个会话的覆盖**: `--remote-control` 即使此键为 `false` 也会为一个会话打开远程控制，没有标志会为一个会话关闭它

5695 5799

5696```json settings.json theme={null}5800```json settings.json theme={null}

5842 5946

5843设置 `/login` Cloud gateway 屏幕连接到的网关 URL，以便人们可以到达您的 [cloud gateway](/docs/zh-CN/claude-apps-gateway) 而无需输入其地址。该屏幕没有 URL 字段：设置此密钥后，它显示您的网关 URL 并在人们按 Enter 时连接；不设置时，它告诉他们联系其 IT 管理员。5947设置 `/login` Cloud gateway 屏幕连接到的网关 URL，以便人们可以到达您的 [cloud gateway](/docs/zh-CN/claude-apps-gateway) 而无需输入其地址。该屏幕没有 URL 字段：设置此密钥后，它显示您的网关 URL 并在人们按 Enter 时连接；不设置时，它告诉他们联系其 IT 管理员。

5844 5948

5845此密钥或 `forceLoginMethod: "gateway"` 使机器仅限网关，因此 `/login` 在 Cloud gateway 屏幕上打开，没有登录方法选择器。请参阅[管理员策略需要 Cloud gateway 登录](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)，了解剩余第一方登录或 API 密钥会发生什么。设置两个密钥，以便屏幕连接而不是显示错误。5949此密钥或 `forceLoginMethod: "gateway"` 使机器仅限网关，除了使用 `CLAUDE_CODE_USE_*` 选择云提供商的会话外。`/login` 然后在 Cloud gateway 屏幕上打开，没有登录方法选择器。请参阅[管理员策略需要 Cloud gateway 登录](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)，了解剩余第一方登录或 API 密钥会发生什么。设置两个密钥，以便屏幕连接而不是显示错误。

5846 5950

5847* **Scope**: [`Managed`](#scopes)。仅从机器上的源读取：`managed-settings.json`、macOS plist 或 Windows HKLM 注册表或策略辅助程序。Claude Code 在 HKCU 和服务器托管设置中忽略它。5951* **Scope**: [`Managed`](#scopes)。仅从机器上的源读取：`managed-settings.json`、macOS plist 或 Windows HKLM 注册表或策略辅助程序。Claude Code 在 HKCU 和服务器托管设置中忽略它。

5848* **Type**: string，包括方案的完整 URL5952* **Type**: string，包括方案的完整 URL

6095 `cleanupPeriodDays`6199 `cleanupPeriodDays`

6096</h3>6200</h3>

6097 6201

6098设置 Claude Code 在删除之前保留[会话记录和其他应用程序数据](/docs/zh-CN/claude-directory#cleaned-up-automatically)的天数。Claude Code 在会话开始后作为后台扫描运行删除，只要它能够安全地确定保留期。6202设置 Claude Code 在删除之前保留[会话记录和其他应用程序数据](/docs/zh-CN/claude-directory#cleaned-up-automatically)的天数。Claude Code 在会话开始后作为后台扫描运行删除，只要它能够安全地确定保留期。扫描删除记录时不显示消息，因此您未使用超过保留期的会话不再出现在 [`/resume`](/docs/zh-CN/sessions#resume-a-session) 选择器中。

6099 6203

6100* **范围**: [`任何文件`](#scopes)6204* **范围**: [`任何文件`](#scopes)

6101* **类型**: 天数，整数，最小值 `1`6205* **类型**: 天数，整数，最小值 `1`

6198 `disableSideloadFlags`6302 `disableSideloadFlags`

6199</h3>6303</h3>

6200 6304

6201在启动时拒绝 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` CLI 标志，用户可能会通过这些标志来绕过 [`strictKnownMarketplaces`](#strictknownmarketplaces) 进行单次运行。Claude Code 会以错误退出并命名被拒绝的标志，并对在内部使用这些标志启动 CLI 的表面应用相同的检查，目前在桌面应用中的 [Cowork](/docs/zh-CN/desktop) 本地会话。在[云会话](/docs/zh-CN/claude-code-on-the-web)中，Claude Code 会删除服务器通过 `--mcp-config` 传递的 MCP 服务器，除了进程内 `type: "sdk"` 条目，并启动会话。需要 Claude Code v2.1.193 或更高版本。6305在启动时拒绝 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config` CLI 标志，用户可能会传递这些标志来绕过 [`strictKnownMarketplaces`](#strictknownmarketplaces) 进行单次运行。Claude Code 会以错误退出并命名被拒绝的标志，并对在内部使用这些标志启动 CLI 的表面应用相同的检查，目前在桌面应用中的 [Cowork](/docs/zh-CN/desktop) 本地会话。在[云会话](/docs/zh-CN/claude-code-on-the-web)中，Claude Code 会删除服务器通过 `--mcp-config` 传递的 MCP 服务器，除了进程内 `type: "sdk"` 条目，并启动会话。需要 Claude Code v2.1.193 或更高版本。

6202 6306

6203* **Scope**: [`Managed`](#scopes)6307* **Scope**: [`Managed`](#scopes)

6204* **Type**: Boolean6308* **Type**: Boolean

6205 * `true`: Claude Code 在启动时拒绝 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config`，并以错误退出并命名它们，除了在云会话中它会删除服务器通过 `--mcp-config` 传递的 MCP 服务器，除了进程内 `type: "sdk"` 条目，并启动会话6309 * `true`: Claude Code 在启动时拒绝 `--plugin-dir`、`--plugin-url`、`--agents` 和 `--mcp-config`，并以错误退出并命名它们，除了在云会话中它删除服务器通过 `--mcp-config` 传递的 MCP 服务器，除了进程内 `type: "sdk"` 条目，并启动会话

6206 * `false`: Claude Code 接受这些标志6310 * `false`: Claude Code 接受这些标志

6207* **Default**: `false`6311* **Default**: `false`

6208 6312

6212}6316}

6213```6317```

6214 6318

6215Claude Code 仍然接受其服务器都是进程内 `type: "sdk"` 条目的 `--mcp-config`，因此 Agent SDK 和 VS Code 扩展继续工作。用户仍然可以使用 `claude mcp add` 或 `.mcp.json` 文件添加服务器；为了进行每个服务器的控制，也可以设置 [`allowedMcpServers`](/docs/zh-CN/managed-mcp)。需要 Claude Code v2.1.193 或更高版本。6319Claude Code 仍然接受其服务器都是进程内 `type: "sdk"` 条目的 `--mcp-config`，因此 Agent SDK 和 VS Code 扩展继续工作。用户仍然可以使用 `claude mcp add` 或 `.mcp.json` 文件添加服务器；对于按服务器控制，也设置 [`allowedMcpServers`](/docs/zh-CN/managed-mcp)。需要 Claude Code v2.1.193 或更高版本。

6216 6320

6217相同的检查涵盖在 [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/zh-CN/env-vars#variables) 环境变量中命名的插件文件夹，这需要 Claude Code v2.1.280 或更高版本。当变量命名一个文件夹时，Claude Code 以相同的错误退出，错误说要取消设置该变量。6321相同的检查涵盖在 [`CLAUDE_CODE_PLUGIN_DIRS`](/docs/zh-CN/env-vars#variables) 环境变量中命名的插件文件夹，这需要 Claude Code v2.1.280 或更高版本。当变量命名一个文件夹时，Claude Code 以相同的错误退出，错误说要取消设置该变量。

6218 6322

6219在云会话中，Claude Code 也会忽略服务器传递的中途 MCP 更新，这是云会话配置和 SDK `setMcpServers()` 调用背后的路径，这些调用到达这些会话。进程内 `type: "sdk"` 条目在那里仍然豁免。在 v2.1.239 之前，服务器传递的 `--mcp-config` 会阻止云会话启动。6323在云会话中，Claude Code 也忽略服务器传递的中途 MCP 更新，云会话配置和 SDK `setMcpServers()` 调用背后的路径到达这些会话。进程内 `type: "sdk"` 条目在那里也保持豁免。在 v2.1.239 之前，服务器传递的 `--mcp-config` 阻止云会话启动。

6220 6324

6221<h3 id="forceremotesettingsrefresh">6325<h3 id="forceremotesettingsrefresh">

6222 `forceRemoteSettingsRefresh`6326 `forceRemoteSettingsRefresh`

6223</h3>6327</h3>

6224 6328

6225阻止 CLI 启动，直到 Claude Code 已经新鲜获取[服务器管理的设置](/docs/zh-CN/server-managed-settings)。如果获取失败，Claude Code 会退出而不是继续使用缓存或无设置。当您的环境无法接受即使是短暂的窗口（在该窗口中会话在没有其托管策略的情况下运行）时，请设置它。6329阻止 CLI 启动，直到 Claude Code 已经新鲜获取[服务器管理的设置](/docs/zh-CN/server-managed-settings)。如果获取失败，Claude Code 会退出而不是继续使用缓存或无设置。当您的环境无法接受即使是短暂的窗口（在该窗口中会话运行而没有其托管策略）时，设置它。

6226 6330

6227当密钥未设置时，Claude Code 不会在获取时阻止启动，尽管当开发者在启动时登录时，它会等待最多五秒钟以进行获取。Cloud 网关会话总是等待，如果无法到达网关则退出。6331当密钥未设置时，Claude Code 不会在获取时阻止启动，尽管当开发人员在启动时登录时，它会等待最多五秒钟以进行获取。Cloud 网关会话总是等待，如果无法到达网关则退出。

6228 6332

6229* **Scope**: [`Managed`](#scopes)。Claude Code 从任何管理员控制的托管源（即使不是最高优先级源）中接受 `true`。6333* **Scope**: [`Managed`](#scopes)。Claude Code 从任何管理员控制的托管源（即使不是最高优先级源）中接受 `true`。

6230* **Type**: Boolean6334* **Type**: Boolean

6238}6342}

6239```6343```

6240 6344

6241在 MDM 配置文件或托管设置文件中设置它以在第一个服务器有效负载到达之前强制执行故障关闭启动。Claude Code 仅在获取服务器管理的设置的会话中应用检查，因此[不获取它们](/docs/zh-CN/server-managed-settings#platform-availability)的会话启动时不会等待。`claude auth` 子命令豁免，因此用户可以在过期凭证是获取失败原因时重新身份验证。请参阅[强制执行故障关闭启动](/docs/zh-CN/server-managed-settings#enforce-fail-closed-startup)。6345在 MDM 配置文件或托管设置文件中设置它以在第一个服务器有效负载到达之前强制执行故障关闭启动。Claude Code 仅在获取服务器管理的设置的会话中应用检查，因此[不获取它们](/docs/zh-CN/server-managed-settings#platform-availability)的会话启动时不会等待。`claude auth` 子命令是豁免的，因此用户可以在过期凭证是获取失败原因时重新身份验证。请参阅[强制执行故障关闭启动](/docs/zh-CN/server-managed-settings#enforce-fail-closed-startup)。

6242 6346

6243<h3 id="managedsourcesbehavior">6347<h3 id="managedsourcesbehavior">

6244 `managedSourcesBehavior`6348 `managedSourcesBehavior`

6245</h3>6349</h3>

6246 6350

6247选择 Claude Code 是仅应用您的组织提供的最高优先级[托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)，还是合并它提供的每个管理员源。默认情况下，Claude Code 采用携带[策略密钥](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)的最高优先级源并忽略其余的。策略密钥是除了这个密钥和 `wslInheritsWindowsSettings` 之外的任何设置密钥。因此，一旦服务器管理的设置或 MDM 策略提供策略密钥，`managed-settings.json` 文件仅贡献 [Claude Code 从每个管理员源读取的密钥](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)。使用 `"merge"`，您提供的每个管理员源都会将其密钥贡献给一个合并的策略。需要 Claude Code v2.1.242 或更高版本。6351选择 Claude Code 是仅应用您的组织提供的最高优先级[托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)，还是合并它提供的每个管理员源。默认情况下，Claude Code 采用携带[策略密钥](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)的最高优先级源并忽略其余的。策略密钥是除了这个和 `wslInheritsWindowsSettings` 之外的任何设置密钥。在该默认值下，一旦服务器管理的设置或 MDM 策略传递策略密钥，`managed-settings.json` 文件仅贡献 [Claude Code 从每个管理员源读取的密钥](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)。使用 `"merge"`，您提供的每个管理员源都将其密钥贡献给一个合并的策略。需要 Claude Code v2.1.242 或更高版本。

6248 6352

6249仅在您[排名](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)在最高优先级源下方的每个源都在管理员的控制下时设置 `"merge"`，因为 Claude Code 然后从较低源（例如 `permissions.allow` 规则）添加条目到策略。6353仅在您[排名](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)低于最高优先级的每个源都在管理员的控制下时设置 `"merge"`，因为 Claude Code 然后从较低源（例如 `permissions.allow` 规则）添加条目到策略。

6250 6354

6251* **Scope**: [`Managed`](#scopes)。Claude Code 从携带此密钥或策略密钥的最高优先级源读取此密钥，并忽略排名较低的每个源中的此密钥，因此较低源无法选择自己合并到上面的源。Windows HKCU 注册表和[来自嵌入主机的父设置](/docs/zh-CN/managed-settings#let-an-embedding-host-add-policy)都不参与合并。6355* **Scope**: [`Managed`](#scopes)。Claude Code 从携带此密钥或策略密钥的最高优先级源读取此密钥，并忽略排名较低的每个源中的此密钥，因此较低源无法选择自己合并到上面的源。Windows HKCU 注册表和[来自嵌入主机的父设置](/docs/zh-CN/managed-settings#let-an-embedding-host-add-policy)都不参与合并。

6252* **Type**: string，其中之一：6356* **Type**: string, one of:

6253 * `"first-wins"`: 携带策略密钥的最高优先级源提供策略，较低源仅贡献 [Claude Code 从每个管理员源读取的密钥](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)6357 * `"first-wins"`: 携带策略密钥的最高优先级源提供策略，较低源仅贡献 [Claude Code 从每个管理员源读取的密钥](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)

6254 * `"merge"`: 您提供的每个管理员源都贡献其密钥，按以下规则合并6358 * `"merge"`: 您提供的每个管理员源都贡献其密钥，按以下规则合并

6255* **Default**: `"first-wins"`6359* **Default**: `"first-wins"`

6256 6360

6257在您部署的最高优先级源中提供密钥。从不接收服务器管理的设置的机器也需要在其 MDM 配置文件中使用该密钥，因为 Claude Code 从携带它或策略密钥的最高优先级源读取该密钥。`managed-settings.json` 文件是最低排名的管理员源，因此在那里设置的 `"merge"` 没有下面的源可以合并。在服务器管理的设置中，密钥看起来像这样：6361在您部署的最高优先级源中传递密钥。从不接收服务器管理的设置的机器也需要在其 MDM 配置文件中使用该密钥，因为 Claude Code 从携带它或策略密钥的最高优先级源读取该密钥。`managed-settings.json` 文件是最低排名的管理员源，因此在那里设置的 `"merge"` 没有下面的源来合并。在服务器管理的设置中，密钥看起来像这样：

6258 6362

6259```json theme={null}6363```json theme={null}

6260{6364{

6268| :- | :- | :- |6372| :- | :- | :- |

6270| Locks | 应用任何源设置的最严格值。当没有源设置严格值时，仅从最高源应用较宽松的值 | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly)、[`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) 和其他布尔值或枚举锁 |6374| Locks | 应用任何源设置的最严格值。当没有源设置严格值时，仅从最高源应用较宽松的值 | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly)、[`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) 和其他布尔值或枚举锁 |

6271| Restriction allowlists | 从设置它的最高源整体取值，不从较低源添加条目。当最高源未设置时，从下一个源整体取值 | [`availableModels`](#availablemodels)、[`allowedMcpServers`](#allowedmcpservers)、[`strictKnownMarketplaces`](#strictknownmarketplaces)、[`allowedChannelPlugins`](#allowedchannelplugins) 和 [`fallbackModel`](#fallbackmodel) 链 |6375| Restriction allowlists | 从设置它的最高源整体取值，不从较低源添加条目。当最高源未设置时，从下一个较低源整体取值 | [`availableModels`](#availablemodels)、[`allowedMcpServers`](#allowedmcpservers)、[`strictKnownMarketplaces`](#strictknownmarketplaces)、[`allowedChannelPlugins`](#allowedchannelplugins) 和 [`fallbackModel`](#fallbackmodel) 链 |

6272| Values taken whole | 从设置它的最高源整体取值，不合并来自较低源的条目或字段。当最高源未设置时，从下一个源整体取值 | [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs)、[`sandbox.ripgrep`](#sandbox-ripgrep) |6376| Values taken whole | 从设置它的最高源整体取值，不合并来自较低源的条目或字段。当最高源未设置时，从下一个较低源整体取值 | [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs)、[`sandbox.ripgrep`](#sandbox-ripgrep) |

6274| Read from the highest-priority source only | 仅从携带策略密钥的最高优先级源读取密钥，因此即使最高源未设置，较低源的值也会被忽略 | [`apiKeyHelper`](#apikeyhelper)、[`awsAuthRefresh`](#awsauthrefresh)、[`awsCredentialExport`](#awscredentialexport)、[`gcpAuthRefresh`](#gcpauthrefresh)、[`otelHeadersHelper`](#otelheadershelper)、`proxyAuthHelper`、[`forceLoginOrgUUID`](#forceloginorguuid)、[`forceLoginMethod`](#forceloginmethod) 的 `"claudeai"` 和 `"console"` 值、[`parentSettingsBehavior`](#parentsettingsbehavior)、[`modelPicker`](#modelpicker)、[`policyHelper`](#policyhelper)、[`permissions.defaultMode`](#permissions-defaultmode) |6378| Read from the highest-priority source only | 仅从携带策略密钥的最高优先级源读取密钥，因此即使最高源未设置任何值，较低源的值也会被忽略 | [`apiKeyHelper`](#apikeyhelper)、[`awsAuthRefresh`](#awsauthrefresh)、[`awsCredentialExport`](#awscredentialexport)、[`gcpAuthRefresh`](#gcpauthrefresh)、[`otelHeadersHelper`](#otelheadershelper)、`proxyAuthHelper`、[`forceLoginOrgUUID`](#forceloginorguuid)、[`forceLoginMethod`](#forceloginmethod) 的 `"claudeai"` 和 `"console"` 值、[`parentSettingsBehavior`](#parentsettingsbehavior)、[`modelPicker`](#modelpicker)、[`policyHelper`](#policyhelper)、[`permissions.defaultMode`](#permissions-defaultmode) |

6275| `env` | [在管理员源之间按变量合并](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)，在 `"first-wins"` 和 `"merge"` 下都是如此 | [`env`](#env) |6379| `env` | [在管理员源之间按变量合并](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)，在 `"first-wins"` 和 `"merge"` 下都是 | [`env`](#env) |

6277 6381

6278整体取值 `sandbox.credentials.awsPairs` 和 `sandbox.ripgrep` 需要 Claude Code v2.1.257 或更高版本。6382整体取值 `sandbox.credentials.awsPairs` 和 `sandbox.ripgrep` 需要 Claude Code v2.1.257 或更高版本。

6279 6383

6280几个密钥添加了表格未显示的条件：6384一些密钥添加了表格不显示的条件：

6281 6385

6282* **[`policyHelper`](#policyhelper)**: Claude Code 仅在携带策略密钥的最高源是 MDM 策略或托管设置文件时才接受它，因此在服务器管理的设置下它不适用。6386* **[`policyHelper`](#policyhelper)**: Claude Code 仅在携带策略密钥的最高源是 MDM 策略或托管设置文件时才接受它，因此在服务器管理的设置下它不适用。

6283* **[`modelOverrides`](#modeloverrides)**: 与 `availableModels` 配对。Claude Code 从设置它的最高源取值 `modelOverrides`，除非较高源设置 `availableModels` 而不设置 `modelOverrides`。在这种情况下，它忽略来自每个源的 `modelOverrides`。6387* **[`modelOverrides`](#modeloverrides)**: 与 `availableModels` 配对。Claude Code 从设置它的最高源取值 `modelOverrides`，除非较高源设置 `availableModels` 而不设置 `modelOverrides`。在这种情况下，它忽略来自每个源的 `modelOverrides`。

6284* **[`forceLoginGatewayUrl`](#forcelogingatewayurl)、[`gatewayInternalNetworks`](#gatewayinternalnetworks) 和 [`forceLoginMethod`](#forceloginmethod) 的 `"gateway"` 值**: Claude Code 从不从服务器管理的设置读取它们，因此那里的值既不适用也不隐藏在 MDM 策略或托管设置文件中设置的值。在机器上的管理员源中，仅携带策略密钥的最高排名源提供它们，无论服务器管理的设置是否也存在。6388* **[`forceLoginGatewayUrl`](#forcelogingatewayurl)、[`gatewayInternalNetworks`](#gatewayinternalnetworks) 和 [`forceLoginMethod`](#forceloginmethod) 的 `"gateway"` 值**: Claude Code 从不从服务器管理的设置读取它们中的任何一个，因此那里的值既不适用也不隐藏在 MDM 策略或托管设置文件中设置的值。在机器上的管理员源中，仅携带策略密钥的最高排名源提供它们，无论是否也存在服务器管理的设置。

6285 6389

6286要确认机器上合并了哪些源，请运行 `/status` 并[读取 `Setting sources` 行](/docs/zh-CN/managed-settings#read-the-source-in-/status)。6390要确认机器上合并了哪些源，请运行 `/status` 并[读取 `Setting sources` 行](/docs/zh-CN/managed-settings#read-the-source-in-/status)。

6287 6391

6289 `parentSettingsBehavior`6393 `parentSettingsBehavior`

6290</h3>6394</h3>

6291 6395

6292选择 Claude Code 是否应用由嵌入主机进程（例如 Agent SDK 或 IDE 扩展）提供的托管设置，当管理员部署的托管层也存在时。使用 `"first-wins"`，Claude Code 会删除主机提供的设置；使用 `"merge"`，它通过限制性过滤器在管理员层下应用它们。当主机需要将其自己的限制传递给它启动的会话时，设置 `"merge"`，例如 Claude Desktop 传递网关的出口允许列表。6396选择 Claude Code 是否应用由嵌入主机进程（例如 Agent SDK 或 IDE 扩展）提供的托管设置，当管理员部署的托管层也存在时。使用 `"first-wins"`，Claude Code 删除主机提供的设置；使用 `"merge"`，它通过限制性过滤器在管理员层下应用它们。当主机需要将其自己的限制传递给它启动的会话时，设置 `"merge"`，例如 Claude Desktop 传递网关的出口允许列表。

6293 6397

6294* **Scope**: [`Managed`](#scopes)。Claude Code 从最高优先级管理员控制的托管源读取它。6398* **Scope**: [`Managed`](#scopes)。Claude Code 从最高优先级管理员控制的托管源读取它。

6295* **Type**: string，其中之一：6399* **Type**: string, one of:

6296 * `"first-wins"`: 当管理员部署的托管层存在时，Claude Code 会删除主机提供的设置6400 * `"first-wins"`: 当管理员部署的托管层存在时，Claude Code 删除主机提供的设置

6297 * `"merge"`: Claude Code 通过限制性过滤器在管理员层下应用主机提供的设置6401 * `"merge"`: Claude Code 通过限制性过滤器在管理员层下应用主机提供的设置

6298* **Default**: `"first-wins"`6402* **Default**: `"first-wins"`

6299 6403

6303}6407}

6304```6408```

6305 6409

6306当不存在管理员部署的托管层时，此密钥无效：主机的设置然后应用为唯一的托管层，仍然过滤为限制性值。有关过滤器的限制以及托管源如何交互，请参阅[来自嵌入主机的父设置](/docs/zh-CN/managed-settings#parent-settings-from-embedding-hosts)和[限制父设置](/docs/zh-CN/claude-apps-gateway#restrict-parent-settings)。6410当不存在管理员部署的托管层时，此密钥无效：主机的设置然后应用为唯一的托管层，仍然被过滤为限制性值。对于过滤器的限制以及托管源如何交互，请参阅[来自嵌入主机的父设置](/docs/zh-CN/managed-settings#parent-settings-from-embedding-hosts)和[限制父设置](/docs/zh-CN/claude-apps-gateway#restrict-parent-settings)。

6307 6411

6308<span id="compute-managed-settings-with-a-policy-helper" />6412<span id="compute-managed-settings-with-a-policy-helper" />

6309 6413

6311 `policyHelper`6415 `policyHelper`

6312</h3>6416</h3>

6313 6417

6314运行您部署的可执行文件，在启动时计算托管设置，因此您可以从设备状态、身份或远程服务而不是静态文件派生策略。Claude Code 在接受第一个提示之前运行帮助程序，并将其发出的设置视为会话的托管设置。6418运行您部署的可执行文件，在启动时计算托管设置，以便您可以从设备状态、身份或远程服务而不是静态文件派生策略。Claude Code 在接受第一个提示之前运行帮助程序，并将其发出的设置视为会话的托管设置。

6315 6419

6316* **Scope**: [`Managed`](#scopes)。从 macOS plist、Windows HKLM 注册表或托管设置文件读取。Claude Code 从携带[策略密钥](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)的最高优先级托管源读取密钥，并仅当该源是这三个之一时才运行帮助程序；它忽略服务器管理的设置、HKCU 注册表和主机提供的父设置中的密钥。6420* **Scope**: [`Managed`](#scopes)。从 macOS plist、Windows HKLM 注册表或托管设置文件读取。Claude Code 从携带[策略密钥](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)的最高优先级托管源读取密钥，仅当该源是这三个之一时才运行帮助程序；它忽略服务器管理的设置、HKCU 注册表和主机提供的父设置中的密钥。

6317* **Type**: 具有 `path`、`timeoutMs` 和 `refreshIntervalMs` 的对象6421* **Type**: object with `path`, `timeoutMs`, and `refreshIntervalMs`

6318* **Default**: 未设置，因此不运行帮助程序6422* **Default**: unset, so no helper runs

6319 6423

6320当服务器管理的设置在启动时提供策略时，它们优先于帮助程序的源，帮助程序不运行。6424当服务器管理的设置在启动时传递策略时，它们优先于帮助程序的源，帮助程序不运行。

6321 6425

6322如果稍后的设置获取报告服务器管理的设置已删除，Claude Code 此时运行帮助程序，而不是等待下一次启动。其输出管理会话的其余部分，失败的运行以与[失败的启动运行](#helper-failures)相同的消息结束会话。6426如果稍后的设置获取报告服务器管理的设置已删除，Claude Code 在该点运行帮助程序，而不是等待下一次启动。其输出管理会话的其余部分，失败的运行以与[失败的启动运行](#helper-failures)相同的消息结束会话。

6323 6427

6324此示例使用 5 秒超时运行帮助程序，并每五分钟重新运行一次：6428此示例以 5 秒超时运行帮助程序，并每五分钟重新运行一次：

6325 6429

6326```json managed-settings.json theme={null}6430```json managed-settings.json theme={null}

6327{6431{

6334```6438```

6335 6439

6336<h4 id="write-the-helper-output">6440<h4 id="write-the-helper-output">

6337 写入帮助程序输出6441 Write the helper output

6338</h4>6442</h4>

6339 6443

6340Claude Code 不带参数运行帮助程序，在其环境中设置 `CLAUDE_CODE_VERSION`，并从 stdout 读取 JSON 信封，上限为 1 MiB。6444Claude Code 不带参数运行帮助程序，在其环境中设置 `CLAUDE_CODE_VERSION`，并从 stdout 读取 JSON 信封，上限为 1 MiB。

6341 6445

6342将设置放在 `managedSettings` 密钥下。没有 `managedSettings` 密钥的裸设置对象使用 `managedSettings` 未定义进行解析并不应用任何内容，Claude Code 报告无错误：6446将设置放在 `managedSettings` 密钥下。没有 `managedSettings` 密钥的裸设置对象解析为 `managedSettings` 未定义并应用任何内容，Claude Code 报告无错误：

6343 6447

6344```json theme={null}6448```json theme={null}

6345{6449{

6349}6453}

6350```6454```

6351 6455

6352当帮助程序发出 `managedSettings` 时，该对象成为运行的唯一托管设置源：Claude Code 忽略 MDM、文件和 HKCU 源，仅从帮助程序的输出读取[跨源密钥](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)，并且从不合并[父设置](/docs/zh-CN/managed-settings#parent-settings-from-embedding-hosts)。6456当帮助程序发出 `managedSettings` 时，该对象成为运行的唯一托管设置源：Claude Code 忽略 MDM、文件和 HKCU 源，仅从帮助程序的输出读取[跨源密钥](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)，并从不合并[父设置](/docs/zh-CN/managed-settings#parent-settings-from-embedding-hosts)。

6353 6457

6354启动 `forceRemoteSettingsRefresh` 检查在帮助程序之前运行并读取任何管理员源。以 0 退出且信封省略 `managedSettings` 的帮助程序不贡献托管设置，其他源照常应用。6458启动 `forceRemoteSettingsRefresh` 检查在帮助程序之前运行并读取任何管理员源。以 0 退出且信封省略 `managedSettings` 的帮助程序不贡献托管设置，其他源照常应用。

6355 6459

6356<h4 id="helper-failures">6460<h4 id="helper-failures">

6357 帮助程序失败6461 Helper failures

6358</h4>6462</h4>

6359 6463

6360帮助程序运行在以下情况下失败：6464帮助程序运行失败时：

6361 6465

6362* `path` 违反 [`policyHelper.path`](#policyhelper-path) 中的规则。6466* `path` 违反 [`policyHelper.path`](#policyhelper-path) 中的规则。

6363* `path` 处没有常规文件。Claude Code 在启动帮助程序之前检查文件，在相同的 `timeoutMs` 预算内，因此无响应的网络挂载可能导致运行失败。6467* `path` 处没有常规文件。Claude Code 在启动帮助程序之前检查文件，在相同的 `timeoutMs` 预算内，因此无响应的网络挂载可能导致运行失败。

6367 6471

6368当启动运行失败时，Claude Code 打印原因并拒绝启动。非零退出后，原因包括帮助程序的 stderr，或当 stderr 为空时的 stdout。超时后，原因命名 `timeoutMs` 限制，不包括帮助程序的任何输出。拒绝涵盖交互式会话、`claude -p`、Agent SDK 会话、[后台会话](/docs/zh-CN/agent-view) 和大多数子命令。6472当启动运行失败时，Claude Code 打印原因并拒绝启动。非零退出后，原因包括帮助程序的 stderr，或当 stderr 为空时的 stdout。超时后，原因命名 `timeoutMs` 限制，不包括帮助程序的任何输出。拒绝涵盖交互式会话、`claude -p`、Agent SDK 会话、[后台会话](/docs/zh-CN/agent-view) 和大多数子命令。

6369 6473

6370拒绝是故意的，因此需要中断恢复能力的帮助程序应该从自己的缓存提供并以 0 退出。6474拒绝是故意的，因此需要中断恢复能力的帮助程序应该从其自己的缓存提供并以 0 退出。

6371 6475

6372当后台刷新失败时，Claude Code 保持最后成功的策略有效，`/status` 显示失败的刷新及其原因，直到刷新成功。每次刷新在与启动运行相同的 `timeoutMs` 和失败规则下运行。6476当后台刷新失败时，Claude Code 保持最后成功的策略有效，`/status` 显示失败的刷新及其原因，直到刷新成功。每次刷新在与启动运行相同的 `timeoutMs` 和失败规则下运行。

6373 6477

6384命名 Claude Code 运行的帮助程序可执行文件。有关路径违反以下规则时发生的情况，请参阅[帮助程序失败](#helper-failures)。6488命名 Claude Code 运行的帮助程序可执行文件。有关路径违反以下规则时发生的情况，请参阅[帮助程序失败](#helper-failures)。

6385 6489

6386* **Scope**: [`Managed`](#scopes)。从 macOS plist、Windows HKLM 注册表或托管设置文件读取，无论 [`policyHelper`](#policyhelper) 在哪里读取。6490* **Scope**: [`Managed`](#scopes)。从 macOS plist、Windows HKLM 注册表或托管设置文件读取，无论 [`policyHelper`](#policyhelper) 在哪里读取。

6387* **Type**: string，规范化形式的绝对路径，没有 `.` 或 `..` 段；在 Windows 上，以 `.exe` 结尾的驱动器字母或 UNC 路径6491* **Type**: string, an absolute path in normalized form, without `.` or `..` segments; on Windows, a drive-letter or UNC path that ends in `.exe`

6388* **Default**: 无；当设置 `policyHelper` 时需要6492* **Default**: none; required when `policyHelper` is set

6389 6493

6390```json managed-settings.json theme={null}6494```json managed-settings.json theme={null}

6391{6495{

6402设置 Claude Code 在将运行视为失败之前等待帮助程序的时间。超时的运行失败方式与非零退出相同，因此在启动时 Claude Code 拒绝启动。6506设置 Claude Code 在将运行视为失败之前等待帮助程序的时间。超时的运行失败方式与非零退出相同，因此在启动时 Claude Code 拒绝启动。

6403 6507

6404* **Scope**: [`Managed`](#scopes)。从 macOS plist、Windows HKLM 注册表或托管设置文件读取，无论 [`policyHelper`](#policyhelper) 在哪里读取。6508* **Scope**: [`Managed`](#scopes)。从 macOS plist、Windows HKLM 注册表或托管设置文件读取，无论 [`policyHelper`](#policyhelper) 在哪里读取。

6405* **Type**: integer，毫秒，最小 `1000`6509* **Type**: integer, milliseconds, minimum `1000`

6406* **Default**: `10000`6510* **Default**: `10000`

6407 6511

6408```json managed-settings.json theme={null}6512```json managed-settings.json theme={null}

6421让 Claude Code 在后台按间隔重新运行帮助程序，以便策略更改到达运行中的会话。当刷新成功时，其输出替换之前的托管设置而不重启；当刷新失败时，Claude Code 保持它已有的策略。6525让 Claude Code 在后台按间隔重新运行帮助程序，以便策略更改到达运行中的会话。当刷新成功时，其输出替换之前的托管设置而不重启；当刷新失败时，Claude Code 保持它已有的策略。

6422 6526

6423* **Scope**: [`Managed`](#scopes)。从 macOS plist、Windows HKLM 注册表或托管设置文件读取，无论 [`policyHelper`](#policyhelper) 在哪里读取。6527* **Scope**: [`Managed`](#scopes)。从 macOS plist、Windows HKLM 注册表或托管设置文件读取，无论 [`policyHelper`](#policyhelper) 在哪里读取。

6424* **Type**: integer，毫秒：`0` 禁用刷新，否则至少 `60000`6528* **Type**: integer, milliseconds: `0` to disable refresh, otherwise at least `60000`

6425* **Default**: 未设置，因此 Claude Code 仅在启动时运行帮助程序一次6529* **Default**: unset, so Claude Code runs the helper once at startup

6426 6530

6427此示例每五分钟重新运行帮助程序：6531此示例每五分钟重新运行帮助程序：

6428 6532

6439 `wslInheritsWindowsSettings`6543 `wslInheritsWindowsSettings`

6440</h3>6544</h3>

6441 6545

6442让 WSL 上的 Claude Code 从 Windows 策略链读取托管设置，HKLM 和 Windows 托管设置文件优先于 `/etc/claude-code` 和下面的 HKCU。当链打开时，Claude Code 仅在 `C:\Program Files\ClaudeCode\` 下没有托管设置文件或删除项提供[策略密钥](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)时才读取 `/etc/claude-code`。设置它以将您已在 Windows 上部署的策略扩展到同一机器上的 WSL 会话，以便它们遵循与主机会话相同的规则。Claude Code 仅在 HKLM 注册表密钥或 `C:\Program Files\ClaudeCode\` 下的托管设置文件或删除项中设置时才接受它，两者都需要 Windows 管理员写入。6546让 WSL 上的 Claude Code 从 Windows 策略链读取托管设置，HKLM 和 Windows 托管设置文件优先于下面的 `/etc/claude-code` 和 HKCU。当链打开时，Claude Code 仅在 [HKLM 注册表值或 `C:\Program Files\ClaudeCode\` 文件夹中不存在 Windows 管理员文档](/docs/zh-CN/managed-settings#present-admin-documents)时才读取 `/etc/claude-code`。设置它以将您已在 Windows 上部署的策略扩展到同一机器上的 WSL 会话，以便它们遵循与主机会话相同的规则。Claude Code 仅在 HKLM 注册表密钥或托管设置文件或 `C:\Program Files\ClaudeCode\` 下的放入中设置时才接受它，两者都需要 Windows 管理员才能写入。

6443 6547

6444* **Scope**: [`Managed`](#scopes)。在管理员控制的 Windows 源中。6548* **Scope**: [`Managed`](#scopes)。在管理员控制的 Windows 源中。

6445* **Type**: Boolean6549* **Type**: Boolean

6446 * `true`: WSL 上的 Claude Code 从 Windows 策略链读取托管设置，并仅在 `C:\Program Files\ClaudeCode\` 下没有托管设置文件或删除项提供[策略密钥](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)时才读取 `/etc/claude-code`6550 * `true`: WSL 上的 Claude Code 从 Windows 策略链读取托管设置，仅在不存在 Windows 管理员文档时读取 `/etc/claude-code`

6447 * `false`: WSL 仅读取 `/etc/claude-code`6551 * `false`: WSL 仅读取 `/etc/claude-code`

6448* **Default**: `false`，因此 WSL 仅读取 `/etc/claude-code`6552* **Default**: `false`, so WSL reads only `/etc/claude-code`

6449 6553

6450```json managed-settings.json theme={null}6554```json managed-settings.json theme={null}

6451{6555{

6453}6557}

6454```6558```

6455 6559

6456一旦管理员源打开链，HKCU 策略仅在 HKCU 也将密钥设置为 `true` 时才加入 WSL 上的链。该副本不会自行打开链。仅包含此密钥的 Windows 源不计为策略源，因此较低优先级源仍然提供策略。此密钥对本机 Windows 无效。6560一旦管理员源打开链，HKCU 策略仅在 HKCU 也将密钥设置为 `true` 时才加入 WSL 上的链。该副本不会自行打开链。仅包含此密钥的 Windows 源（设置为 `true` 或 `false`）不计为策略源，因此较低优先级源仍然提供策略。此密钥对本机 Windows 无效。

6561

6562Claude Code 读取带或不带引号的 `true` 和 `false`，并将 `null` 读取为删除密钥。包含任何其他值的管理员控制的 Windows 源计为[存在的管理员文档](/docs/zh-CN/managed-settings#present-admin-documents)，链打开：既不应用 `/etc/claude-code` 也不应用 HKCU，启动警告命名密钥。无法读取的 HKLM 值或 Windows 文件夹文件也会阻止 `/etc/claude-code` 应用，无论链是否打开。需要 Claude Code v2.1.282 或更高版本。

6457 6563

6458<h2 id="global-config-settings">6564<h2 id="global-config-settings">

6459 全局配置设置6565 全局配置设置

6503 6609

6504Claude Code 在 `settings.json` 中忽略此键。6610Claude Code 在 `settings.json` 中忽略此键。

6505 6611

6612<h3 id="claudeinchromedefaultenabled">

6613 `claudeInChromeDefaultEnabled`

6614</h3>

6615

6616启动每个交互式 CLI 会话时，[Chrome 集成](/docs/zh-CN/chrome)默认打开，无需每次都传递 `--chrome`。如果你运行 [`claude remote-control`](/docs/zh-CN/remote-control)，它为你的某个[项目](/docs/zh-CN/claude-projects)线程启动的会话也遵循此键，除非在 `bypassPermissions` 模式下。运行 `/chrome` 并选择**默认启用**会为你设置此键，如[启用 Chrome 默认设置](/docs/zh-CN/chrome#enable-chrome-by-default)中所述。在 `/config` 中显示为**默认启用 Chrome 中的 Claude**。

6617

6618* **作用域**: [`全局配置`](#scopes)

6619* **类型**: 布尔值

6620 * `true`: 当交互式 CLI 会话启动时，Claude Code 打开 Chrome 集成，就像你传递 `--chrome` 时一样

6621 * `false`: 交互式 CLI 会话启动时 Chrome 集成关闭，Claude Code 停止[提供设置它](/docs/zh-CN/chrome#install-the-extension-when-claude-asks)。传递 `--chrome` 为一个交互式会话打开它

6622* **默认值**: 未设置，因此 Chrome 集成关闭，Claude Code 仍然可以提供设置它

6623* **每个会话的覆盖**: `--chrome` 和 [`--no-chrome`](/docs/zh-CN/cli-reference) 在一个交互式会话中优先于此键

6624

6625```json ~/.claude.json theme={null}

6626{

6627 "claudeInChromeDefaultEnabled": true

6628}

6629```

6630

6631Claude Code 在 `settings.json` 中忽略此键。

6632

6633<h3 id="copyfullresponse">

6634 `copyFullResponse`

6635</h3>

6636

6637使 [`/copy`](/docs/zh-CN/commands) 每次都复制完整响应，而不显示当响应包含代码块时通常显示的选择器。在该选择器中选择**始终复制完整响应**会将此键设置为 `true`。在 `/config` 中显示为**跳过 /copy 选择器**。

6638

6639* **作用域**: [`全局配置`](#scopes)

6640* **类型**: 布尔值

6641 * `true`: `/copy` 复制完整响应而不显示选择器

6642 * `false`: 当响应包含代码块时，`/copy` 显示一个选择器，你可以在其中选择一个代码块或完整响应

6643* **默认值**: `false`

6644

6645```json ~/.claude.json theme={null}

6646{

6647 "copyFullResponse": true

6648}

6649```

6650

6651Claude Code 在 `settings.json` 中忽略此键。

6652

6506<h3 id="copyonselect">6653<h3 id="copyonselect">

6507 `copyOnSelect`6654 `copyOnSelect`

6508</h3>6655</h3>

6523 6670

6524Claude Code 在 `settings.json` 中忽略此键。6671Claude Code 在 `settings.json` 中忽略此键。

6525 6672

6673<h3 id="defaulttoagentsview">

6674 `defaultToAgentsView`

6675</h3>

6676

6677当你运行不带参数的 `claude` 时，打开[代理视图](/docs/zh-CN/agent-view)而不是新对话。在 `/config` 中显示为**默认打开代理视图**，除非代理视图被[关闭](#disableagentview)。

6678

6679* **作用域**: [`全局配置`](#scopes)

6680* **类型**: 布尔值

6681 * `true`: 不带参数的 `claude` 打开代理视图，除非代理视图被[关闭](#disableagentview)

6682 * `false`: 不带参数的 `claude` 启动新对话

6683* **默认值**: `false`

6684

6685```json ~/.claude.json theme={null}

6686{

6687 "defaultToAgentsView": true

6688}

6689```

6690

6691Claude Code 在 `settings.json` 中忽略此键。

6692

6526<h3 id="difftool">6693<h3 id="difftool">

6527 `diffTool`6694 `diffTool`

6528</h3>6695</h3>

6577 6744

6578Claude Code 在 `settings.json` 中忽略此键。6745Claude Code 在 `settings.json` 中忽略此键。

6579 6746

6747<h3 id="leftarrowopensagents">

6748 `leftArrowOpensAgents`

6749</h3>

6750

6751在空提示上按 `←` 以[后台会话并打开代理视图](/docs/zh-CN/agent-view#switch-sessions-without-leaving-the-terminal)。将此键设置为 `false` 以关闭快捷键。当代理视图可用时，在 `/config` 中显示为\*\*← 打开代理\*\*。

6752

6753* **作用域**: [`全局配置`](#scopes)

6754* **类型**: 布尔值

6755 * `true`: 在你在终端中启动的会话中的空提示上按 `←` 会后台该会话并打开代理视图

6756 * `false`: Claude Code 关闭快捷键；在你[从代理视图附加到的会话](/docs/zh-CN/agent-view#attach-to-a-session)中，空提示上的 `←` 仍然会分离

6757* **默认值**: `true`

6758

6759```json ~/.claude.json theme={null}

6760{

6761 "leftArrowOpensAgents": false

6762}

6763```

6764

6765Claude Code 在 `settings.json` 中忽略此键。

6766

6580<h3 id="permissionexplainerenabled">6767<h3 id="permissionexplainerenabled">

6581 `permissionExplainerEnabled`6768 `permissionExplainerEnabled`

6582</h3>6769</h3>

6591* **类型**: 布尔值6778* **类型**: 布尔值

6592* **默认值**: `true`6779* **默认值**: `true`

6593 6780

6781<h3 id="prstatusfooterenabled">

6782 `prStatusFooterEnabled`

6783</h3>

6784

6785在提示页脚中显示当前分支的开放拉取请求或合并请求的徽章，带有显示其[状态](/docs/zh-CN/interactive-mode#pr-review-status)的彩色下划线。在 `/config` 中显示为**显示 PR 状态页脚**。

6786

6787* **作用域**: [`全局配置`](#scopes)

6788* **类型**: 布尔值

6789 * `true`: 页脚在[PR 审查状态](/docs/zh-CN/interactive-mode#pr-review-status)中的条件下显示徽章

6790 * `false`: Claude Code 跳过页脚的拉取请求和合并请求检查，不显示该徽章。你[从代理视图附加到的会话](/docs/zh-CN/agent-view#attach-to-a-session)仍然可以显示指向[链接到它的](/docs/zh-CN/agent-view#pull-request-status)拉取请求的纯链接

6791* **默认值**: `true`

6792

6793```json ~/.claude.json theme={null}

6794{

6795 "prStatusFooterEnabled": false

6796}

6797```

6798

6799Claude Code 在 `settings.json` 中忽略此键。

6800

6594<h3 id="teammatedefaultmodel">6801<h3 id="teammatedefaultmodel">

6595 `teammateDefaultModel`6802 `teammateDefaultModel`

6596</h3>6803</h3>

setup.md +3 −3

Details

37 37

38<Tip>38<Tip>

39 更喜欢图形界面？[桌面应用](/docs/zh-CN/desktop-quickstart)让您无需使用终端即可使用 Claude Code。下载适用于 [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs)、[Windows](https://claude.com/download?utm_source=claude_code\&utm_medium=docs) 或 [Linux](/docs/zh-CN/desktop-linux) 的版本。39 更喜欢图形界面？[桌面应用](/docs/zh-CN/desktop-quickstart)让您无需使用终端即可使用 Claude Code。下载适用于 [macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs)、[Windows](https://claude.com/download?utm_source=claude_code\&utm_medium=docs) 或 [Linux](/docs/zh-CN/desktop-linux) 的版本。

~~41 初次使用终端？请参阅[终端指南](/docs/zh-CN/terminal-guide)获取分步说明。~~

42</Tip>40</Tip>

43 41

~~44要安装 Claude Code，请使用以下方法之一：~~42要安装 Claude Code，请打开终端并运行适用于您的系统的命令。如果您之前没有使用过终端，[终端指南](/docs/zh-CN/terminal-guide)会展示如何打开终端并粘贴命令。

45 43

46<Tabs>44<Tabs>

47 <Tab title="原生安装（推荐）">45 <Tab title="原生安装（推荐）">

63 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd61 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

64 ```62 ```

65 63

64 安装程序完成后，打开一个新的终端窗口并运行 `claude --version`。正常的安装会打印一个版本号。如果您的 shell 显示找不到 `claude` 或无法识别，说明安装目录还不在您的 PATH 中：请参阅[修复您的 PATH](/docs/zh-CN/troubleshoot-install#command-not-found-claude-after-installation)。

66 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。当您在 PowerShell 中时，您的提示符显示 `PS C:\`，当您在 CMD 中时显示 `C:\`（没有 `PS`）。66 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。当您在 PowerShell 中时，您的提示符显示 `PS C:\`，当您在 CMD 中时显示 `C:\`（没有 `PS`）。

67 67

68 如果安装命令失败并显示 `syntax error near unexpected token '<'`、`403` 或其他 curl 错误，请参阅 [Troubleshoot installation](/docs/zh-CN/troubleshoot-install#find-your-error) 以匹配错误并获得修复方案和替代安装方法。68 如果安装命令失败并显示 `syntax error near unexpected token '<'`、`403` 或其他 curl 错误，请参阅 [Troubleshoot installation](/docs/zh-CN/troubleshoot-install#find-your-error) 以匹配错误并获得修复方案和替代安装方法。

skills.md +79 −60

Details

76 </Step>76 </Step>

77 77

78 <Step title="编写 SKILL.md">78 <Step title="编写 SKILL.md">

79 每个 skill 都需要一个 `SKILL.md` 文件，包含两部分：`---` 标记之间的 YAML frontmatter，告诉 Claude 何时使用该 skill，以及包含 Claude 在 skill 运行时遵循的说明的 markdown 内容。目录名称成为你输入的命令，`description` 帮助 Claude 决定何时自动加载该 skill。79 每个 skill 都需要一个 `SKILL.md` 文件，包含两部分：`---` 标记之间的 YAML frontmatter，告诉 Claude 何时使用该 skill，以及包含 Claude 在 skill 运行时遵循的说明的 markdown 内容。目录名称或你设置的 frontmatter `name` 会成为你输入的命令，`description` 帮助 Claude 决定何时自动加载该 skill。

80 80

81 将其保存到 `~/.claude/skills/summarize-changes/SKILL.md`：81 将其保存到 `~/.claude/skills/summarize-changes/SKILL.md`：

82 82

120 选择 skills 的加载位置120 选择 skills 的加载位置

121</h2>121</h2>

122 122

123保存 skill 的位置决定了哪些会话会加载它。将其保存在主目录下可以在每个项目中使用，将其提交到存储库可以与在那里工作的所有人共享，或通过 plugin 或托管设置分发以覆盖整个团队。123skills 的保存位置决定了哪些会话会加载它。将其保存在主目录下可在每个项目中使用，将其提交到存储库可与该处的所有人共享，或通过插件或托管设置分发以覆盖整个团队。

124 124

125| 位置 | 路径 | 加载位置 |125| 位置 | 路径 | 加载位置 |

126| :- | :- | :- |126| :- | :- | :- |

130| Nested | `<subdir>/.claude/skills/<skill-name>/SKILL.md` | 在 `<subdir>` 中或其下方启动的会话。在其上方启动的会话在 Claude 处理那里的文件时加载该 skill。请参阅 [monorepos 和子目录](#discovery-from-parent-and-nested-directories) |130| Nested | `<subdir>/.claude/skills/<skill-name>/SKILL.md` | 在 `<subdir>` 中或其下方启动的会话。在其上方启动的会话在 Claude 处理该处的文件时加载该 skill。请参阅 [monorepos 和子目录](#discovery-from-parent-and-nested-directories) |

134 134

135Skill 文件夹还遵循以下规则：135Skill 文件夹还遵循以下规则：

136 136

137* **符号链接文件夹**：enterprise、personal 或 project 位置中的 `<skill-name>` 条目可以是指向磁盘上其他位置的目录的符号链接。Claude Code 从目标读取 `SKILL.md` 并加载 skill，即使多个位置指向同一目标也只加载一次。Plugin skills [以不同方式处理符号链接](/docs/zh-CN/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks)。137* **符号链接文件夹**：enterprise、personal 或 project 位置中的 `<skill-name>` 条目可以是指向磁盘上其他位置的目录的符号链接。Claude Code 从目标读取 `SKILL.md` 并加载 skill，即使多个位置指向同一目标也只加载一次。插件 skills [以不同方式处理符号链接](/docs/zh-CN/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks)。

138* **保留名称**：不要将 skill 文件夹命名为 `synced`，无论大小写如何。Claude Code 使用 `~/.claude/skills/synced/` 来存放 [从 claude.ai 下载的 skills](#where-synced-skills-load)，并跳过您在 enterprise、personal 和 project 位置中以该名称创建的 skill。138* **保留名称 `synced`**：不要将 skill 文件夹命名为 `synced`，无论大小写如何。Claude Code 使用 `~/.claude/skills/synced/` 来存放 [从 claude.ai 下载的 skills](#where-synced-skills-load)，并跳过您在 enterprise、personal 和 project 位置中以该名称创作的 skill。

139* **命令文件**：`.claude/commands/` 中的 Markdown 文件是较旧的格式，仍然有效。它支持相同的 [frontmatter](#frontmatter-reference)，除了 `name` 和 `paths`。要找到您输入以调用它的名称，请参阅 [Skill 如何获得其命令名称](#how-a-skill-gets-its-command-name)。对于新工作，更倾向于使用 skill，因为 skills 还支持 [支持文件](#add-supporting-files)。139* **保留名称 `anthropic-skills`**：在插件外，名称为 `anthropic-skills` 或以 `anthropic-skills:` 开头的 skill 文件夹或命令文件不会加载。请参阅 [为同步 skills 保留的名称](#names-reserved-for-synced-skills)。

140* **Skill 文件夹作为 plugin**：将 `.claude-plugin/plugin.json` 添加到 skill 文件夹，它将作为 [plugin](/docs/zh-CN/plugins/loading#plugins-shared-through-a-repository) 加载，名称为 `<name>@skills-dir`，因此它可以捆绑 agents、hooks 和 MCP 服务器。在项目的 `.claude/skills/` 中，这需要首先接受工作区信任对话框。140* **命令文件**：`.claude/commands/` 中的 Markdown 文件是较旧的格式，仍然有效。它支持相同的 [frontmatter](#frontmatter-reference)，除了 `name` 和 `paths`。要找到您输入以调用它的名称，请参阅 [skill 如何获得其命令名称](#how-a-skill-gets-its-command-name)。对于新工作，更倾向于使用 skill，因为 skills 还支持 [支持文件](#add-supporting-files)。

141* **Skill 文件夹作为插件**：将 `.claude-plugin/plugin.json` 添加到 skill 文件夹，它将作为 [插件](/docs/zh-CN/plugins/loading#plugins-shared-through-a-repository) 加载，名称为 `<name>@skills-dir`，因此它可以捆绑代理、hooks 和 MCP 服务器。在项目的 `.claude/skills/` 中，这需要首先接受工作区信任对话框。

141 142

142<h3 id="discovery-from-parent-and-nested-directories">143<h3 id="discovery-from-parent-and-nested-directories">

143 在 monorepos 和子目录中加载 skills144 在 monorepos 和子目录中加载 skills

144</h3>145</h3>

145 146

146Claude Code 从启动它的目录中的 `.claude/skills/` 以及直到存储库根目录的每个父目录中加载项目 skills，因此在 `packages/frontend/` 中启动仍然会获取在根目录中定义的 skills。当您在 v2.1.246 或更高版本上 [使用 `/cd` 移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory) 时，Claude Code 会添加新目录的项目 skills。147Claude Code 从启动它的目录和每个父目录（直到存储库根目录）中的 `.claude/skills/` 加载项目 skills，因此在 `packages/frontend/` 中启动仍会获取在根目录定义的 skills。当您在 v2.1.246 或更高版本上 [使用 `/cd` 移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory) 时，Claude Code 会添加新目录的项目 skills。

147 148

148在链接的 [git worktree](/docs/zh-CN/worktrees) 中运行的会话中，Claude Code 仅在 worktree 根目录之前搜索父目录。在 Claude Code v2.1.277 或更高版本上，当 worktree 检出在其根目录处没有 `.claude/skills` 目录时，Claude Code 会改为加载主检出的项目 skills。请参阅 [Worktrees 与主检出共享的内容](/docs/zh-CN/worktrees#what-worktrees-share-with-the-main-checkout)。149在链接的 [git worktree](/docs/zh-CN/worktrees) 中运行的会话中，Claude Code 仅在 worktree 根目录之前搜索父目录。在 Claude Code v2.1.277 或更高版本上，当 worktree 检出在其根目录没有 `.claude/skills` 目录时，Claude Code 会改为加载主检出的项目 skills。请参阅 [worktrees 与主检出共享的内容](/docs/zh-CN/worktrees#what-worktrees-share-with-the-main-checkout)。

149 150

150`.claude/skills/` 目录中启动位置下方的 Skills 在启动时不会加载。它们在 Claude 首次读取或编辑该子目录中的文件时加载，并在会话的其余时间保持可用。在此之前，它们不会出现在 `/` 菜单中，您也无法按名称调用它们。要更早加载它们，请使用子目录的路径运行 `/add-dir`，这需要 Claude Code v2.1.257 或更高版本。151`.claude/skills/` 目录中启动位置下方的 skills 在启动时不会加载。它们在 Claude 首次读取或编辑该子目录中的文件时加载，并在会话的其余时间保持可用。在此之前，它们不会出现在 `/` 菜单中，您也无法按名称调用它们。要更早加载它们，请使用子目录的路径运行 `/add-dir`，这需要 Claude Code v2.1.257 或更高版本。

151 152

152当嵌套 skill 与另一个 skill 共享名称时，两者都保持可用。在存储库根目录和 `apps/web/.claude/skills/` 中都有一个 `deploy` skill 的情况下：153当嵌套 skill 的目录名称与另一个 skill 的名称匹配时，两者都保持可用。在存储库根目录有一个 `deploy` skill，在 `apps/web/.claude/skills/` 中有另一个：

153 154

154* `/deploy` 运行根 skill。Claude Code 还为 Claude 列出目录限定的变体，并提供说明以调用其目录包含它正在处理的文件的那个，因此嵌套 skill 仍然适用于 `apps/web/` 中的工作。155* `/deploy` 运行根 skill。Claude Code 还为 Claude 列出目录限定的变体，并指示调用其目录包含它正在处理的文件的那个，因此嵌套 skill 仍然适用于 `apps/web/` 中的工作。

155* `/apps/web:deploy` 单独运行嵌套 skill。其描述命名了它适用的目录。156* `/apps/web:deploy` 单独运行嵌套 skill。其描述命名了它适用的目录。

156 157

157<h3 id="skills-from-additional-directories">158<h3 id="skills-from-additional-directories">

160 161

161当您使用 `--add-dir` 或 `/add-dir` 添加目录时，Claude Code 会加载该目录的 `.claude/skills/` 中的 skills，以及其 `.claude/commands/` 和 `.claude/agents/`。Agent SDK 通过 TypeScript 中的 [`additionalDirectories`](/docs/zh-CN/agent-sdk/typescript#options) 或 Python 中的 [`add_dirs`](/docs/zh-CN/agent-sdk/python#claudeagentoptions) 添加的目录以相同方式加载，因为 SDK 将它们作为 `--add-dir` 传递。`settings.json` 中的 `permissions.additionalDirectories` 设置仅授予文件访问权限，不加载这些中的任何一个。162当您使用 `--add-dir` 或 `/add-dir` 添加目录时，Claude Code 会加载该目录的 `.claude/skills/` 中的 skills，以及其 `.claude/commands/` 和 `.claude/agents/`。Agent SDK 通过 TypeScript 中的 [`additionalDirectories`](/docs/zh-CN/agent-sdk/typescript#options) 或 Python 中的 [`add_dirs`](/docs/zh-CN/agent-sdk/python#claudeagentoptions) 添加的目录以相同方式加载，因为 SDK 将它们作为 `--add-dir` 传递。`settings.json` 中的 `permissions.additionalDirectories` 设置仅授予文件访问权限，不加载这些中的任何一个。

162 163

163Claude Code 监视您在启动时使用 `--add-dir` 传递的目录中的 `.claude/skills/`，如 [在会话期间编辑 skill](#live-change-detection) 所述。它不监视添加目录的 `.claude/commands/` 或 `.claude/agents/`，因此在更改那里的文件后重新启动会话。164Claude Code 在启动时使用 `--add-dir` 传递的目录中监视 `.claude/skills/`，如 [在会话期间编辑 skill](#live-change-detection) 所述。它不监视添加目录的 `.claude/commands/` 或 `.claude/agents/`，因此在更改该处的文件后重新启动会话。

164 165

165这些加载取决于 `project` [设置源](/docs/zh-CN/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources)，默认情况下处于启用状态。[`strictPluginOnlyCustomization`](/docs/zh-CN/settings-reference#strictpluginonlycustomization) 策略、[bare mode](/docs/zh-CN/headless#start-faster-with-bare-mode) 和 [`--safe-mode`](/docs/zh-CN/cli-reference#cli-flags) 各自进一步限制它们，如这些页面所述。请参阅 [额外目录授予文件访问权限，而不是配置](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) 以获取添加目录加载的完整表格，包括 `CLAUDE.md` 和 plugin 设置。166这些加载取决于 `project` [设置源](/docs/zh-CN/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources)，默认情况下处于启用状态。[`strictPluginOnlyCustomization`](/docs/zh-CN/settings-reference#strictpluginonlycustomization) 策略、[bare mode](/docs/zh-CN/headless#start-faster-with-bare-mode) 和 [`--safe-mode`](/docs/zh-CN/cli-reference#cli-flags) 各自进一步限制它们，如这些页面所述。请参阅 [其他目录授予文件访问权限，而不是配置](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) 以获取添加目录加载的完整表格，包括 `CLAUDE.md` 和插件设置。

166 167

167<h3 id="resolve-skills-that-share-a-name">168<h3 id="resolve-skills-that-share-a-name">

168 解决共享名称的 skills169 解决共享名称的 skills

169</h3>170</h3>

170 171

171当两个 skills 共享名称时，每个来自的位置决定了 `/name` 运行哪一个。该表涵盖 enterprise、personal、project、nested、plugin 和 claude.ai 位置、捆绑的 skills 和命令文件：172当两个 skills 共享目录或文件名称时，每个来自的位置决定了 `/name` 运行哪一个。对于由 frontmatter `name` 字段设置的名称，请参阅 [skill 如何获得其命令名称](#how-a-skill-gets-its-command-name)。该表涵盖 enterprise、personal、project、nested、plugin 和 claude.ai 位置、捆绑 skills 和命令文件：

172 173

173| 相同名称在 | 运行哪一个 |174| 相同名称在 | 运行哪一个 |

174| :- | :- |175| :- | :- |

175| Enterprise、personal 和 project 中的两个 | Enterprise 优于 personal，personal 优于 project。在 `~/.claude/skills/` 和项目的 `.claude/skills/` 中都有 `deploy` 时，`/deploy` 运行 personal 的 |176| Enterprise、personal 和 project 中的两个 | Enterprise 优先于 personal，personal 优先于 project。在 `~/.claude/skills/` 和项目的 `.claude/skills/` 中都有 `deploy` 时，`/deploy` 运行 personal 的 |

176| 这些位置中的任何一个和 [捆绑 skill](#bundled-skills) | 您的 skill 替换捆绑的命令，但不替换其别名。项目 `code-review` skill 替换 `/code-review`，捆绑的别名 `/review` 永远不会运行您的 skill |177| 这些位置中的任何一个和 [捆绑 skill](#bundled-skills) | 您的 skill 替换捆绑命令，但不替换其别名。项目 `code-review` skill 替换 `/code-review`，捆绑别名 `/review` 永远不会运行您的 skill |

178| 项目根 skill 和嵌套 skill | 两者都加载。请参阅 [monorepos 和子目录](#discovery-from-parent-and-nested-directories) |179| 项目根 skill 和嵌套 skill | 两者都加载。请参阅 [monorepos 和子目录](#discovery-from-parent-and-nested-directories) |

180| 上述任何一个和 [从您的 claude.ai 账户同步的 skill](#how-synced-skills-behave) | 另一个 skill 或命令。同步的 skill 仍然作为 `/anthropic-skills:<name>` 运行。请参阅 [当同步的 skill 名称与另一个命令匹配时](#when-a-synced-skill-name-matches-another-command) |181| 上述任何一个和 [从您的 claude.ai 账户同步的 skill](#how-synced-skills-behave) 的短名称 | 其他 skill 或命令。同步 skill 随后被列出并仅在其完整名称下运行。请参阅 [当同步 skill 名称与另一个命令匹配时](#when-a-synced-skill-name-matches-another-command) |

181 182

182<h3 id="skills-in-cowork-and-cloud-sessions">183<h3 id="skills-in-cowork-and-cloud-sessions">

183 在 Cowork 和云会话中使用 skills184 在 Cowork 和云会话中使用 skills

184</h3>185</h3>

185 186

186[Cowork](https://claude.com/product/cowork) 会话和 [云会话](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)，包括 [routines](/docs/zh-CN/routines)，不会读取您机器上的 `~/.claude/skills/`。交互式和计划的 Cowork 会话都加载为您的 claude.ai 账户启用的 skills，在会话启动时同步；从 Desktop 应用侧边栏中的 **Customize** 或从 claude.ai 上的 skills 设置管理它们。云会话还加载提交到克隆存储库的 `.claude/skills/` 的项目 skills。187[Cowork](https://claude.com/product/cowork) 会话和 [云会话](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)（包括 [routines](/docs/zh-CN/routines)）不会读取您机器上的 `~/.claude/skills/`。交互式和计划的 Cowork 会话都加载为您的 claude.ai 账户启用的 skills，在会话启动时同步；从 Desktop 应用侧边栏中的 **Customize** 或从 claude.ai 上的 skills 设置管理它们。云会话另外加载提交到克隆存储库的 `.claude/skills/` 的项目 skills。

187 188

188如果 skill 仅存在于您机器上的 `~/.claude/skills/` 中，当 [routine](/docs/zh-CN/routines) 调用它时，Claude Code 会报告找不到该 skill，因为每个 routine 运行都作为新的云会话启动。要在这些会话中使用个人 skill：189如果 skill 仅存在于您机器上的 `~/.claude/skills/` 中，当 [routine](/docs/zh-CN/routines) 调用它时，Claude Code 会报告找不到该 skill，因为每个 routine 运行都作为新的云会话启动。要在这些会话中使用个人 skill：

189 190

190* 对于 Cowork 和云会话，为您的 claude.ai 账户启用该 skill。191* 对于 Cowork 和云会话，为您的 claude.ai 账户启用该 skill。

191* 对于云会话，您可以改为将 skill 提交到存储库的 `.claude/skills/`。在存储库的 `.claude/settings.json` 中声明的 plugins 和仅在您的用户设置中启用的 plugins [不会在云会话中加载](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)。192* 对于云会话，您可以改为将 skill 提交到存储库的 `.claude/skills/`。在存储库的 `.claude/settings.json` 中声明的插件和仅在您的用户设置中启用的插件 [不会在云会话中加载](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)。

192 193

193[Desktop 计划任务](/docs/zh-CN/desktop-scheduled-tasks) 在您的机器上本地运行，因此它们确实加载 `~/.claude/skills/`。194[Desktop 计划任务](/docs/zh-CN/desktop-scheduled-tasks) 在您的机器上本地运行，因此它们确实加载 `~/.claude/skills/`。

194 195

196 从 claude.ai 同步的 Skills197 从 claude.ai 同步的 Skills

197</h3>198</h3>

198 199

199如果您使用 Cowork 或云会话，或在终端中使用 claude.ai 账户登录 Claude Code，本部分适用于您。在这些会话中，Claude Code 加载为您的 claude.ai 账户启用的 skills，无需您进行任何设置，如 [同步的 skills 加载位置](#where-synced-skills-load) 所述。这些 skills 包括您在 claude.ai 设置中创建或打开的 skills、您的组织在那里提供的 skills 以及 Anthropic 的内置 skills，如 `pdf` 和 `xlsx`。200如果您使用 Cowork 或云会话，或使用 claude.ai 账户在终端中登录 Claude Code，本部分适用于您。在这些会话中，Claude Code 加载为您的 claude.ai 账户启用的 skills，无需您进行任何设置，如 [同步 skills 加载的位置](#where-synced-skills-load) 所述。这些 skills 包括您在 claude.ai 设置中创建或打开的 skills、您的组织在那里提供的 skills 以及 Anthropic 的内置 skills，例如 `pdf` 和 `xlsx`。

200 201

201Claude Code 从您的账户下载同步的 skill，而不是读取您在会话运行的机器上编写的文件，因此它对同步的 skills 应用不适用于您存储在 [skills 位置](#where-skills-live) 中的 skills 的规则。202Claude Code 从您的账户下载同步 skill，而不是读取您在会话运行的机器上编写的文件，因此它对同步 skills 应用不适用于您存储在 [skills 位置](#where-skills-live) 中的 skills 的规则。

202 203

203<h4 id="where-synced-skills-load">204<h4 id="where-synced-skills-load">

204 同步的 skills 加载位置205 同步 skills 加载的位置

205</h4>206</h4>

206 207

207在 Cowork 或云会话中，Claude Code 加载为您的 claude.ai 账户启用的 skills，[Cowork 和云会话中的 Skills](#skills-in-cowork-and-cloud-sessions) 说明了如何选择这些会话获得哪些 skills。208在 Cowork 或云会话中，Claude Code 加载为您的 claude.ai 账户启用的 skills，[Cowork 和云会话中的 Skills](#skills-in-cowork-and-cloud-sessions) 说明了如何选择这些会话获得哪些 skills。

208 209

209在您的终端中，Claude Code 在您使用 claude.ai 账户登录的会话中同步这些 skills。当会话启动时，Claude Code 在后台将您账户的 skills 下载到 `~/.claude/skills/synced/` 中，然后在会话运行时大约每 10 分钟检查一次 claude.ai 的更改。当检查发现 skill 在 claude.ai 上被添加、编辑或关闭时，Claude Code 在运行的会话中添加、更新或删除它，无需重新启动。终端会话中的同步需要 Claude Code v2.1.273 或更高版本。210在您的终端中，Claude Code 在您使用 claude.ai 账户登录的会话中同步这些 skills。会话启动时，Claude Code 在后台将您账户的 skills 下载到 `~/.claude/skills/synced/` 中，然后在会话运行时大约每 10 分钟检查一次 claude.ai 是否有更改。当检查发现 skill 在 claude.ai 上被添加、编辑或关闭时，Claude Code 在运行的会话中添加、更新或删除它，无需重新启动。终端会话中的同步需要 Claude Code v2.1.273 或更高版本。

210 211

211同步永远不会延迟启动，因为 Claude 仅在调用 skill 时等待其下载。因此，短的 [非交互式](/docs/zh-CN/headless) 运行可以在新添加的 skill 下载之前完成，在这种情况下，稍后的会话会下载它。要使非交互式运行下载您的 skills 并在回答提示之前等待列表，请将 [`CLAUDE_CODE_SYNC_SKILLS`](/docs/zh-CN/env-vars#variables) 设置为 `1`。212同步永远不会延迟启动，因为 Claude 仅在调用 skill 时等待其下载。因此，短 [非交互式](/docs/zh-CN/headless) 运行可能在新添加的 skill 下载之前完成，在这种情况下，稍后的会话会下载它。要使非交互式运行下载您的 skills 并在回答提示之前等待列表，请将 [`CLAUDE_CODE_SYNC_SKILLS`](/docs/zh-CN/env-vars#variables) 设置为 `1`。

212 213

213Claude Code 仅在使用您的 claude.ai 账户登录并 [从 Anthropic 获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) 的会话中同步。它不在这些会话中同步：214Claude Code 仅在使用您的 claude.ai 账户登录的会话中同步，并 [从 Anthropic 获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)。它不在这些会话中同步：

214 215

215* 不使用 `/login` 存储的登录的会话，例如使用 API 密钥进行身份验证的会话，或 `ANTHROPIC_AUTH_TOKEN`、`CLAUDE_CODE_OAUTH_TOKEN` 或 `apiKeyHelper` 脚本提供凭证的会话216* 不使用由 `/login` 存储的登录的会话，例如使用 API 密钥进行身份验证的会话，或 `ANTHROPIC_AUTH_TOKEN`、`CLAUDE_CODE_OAUTH_TOKEN` 或 `apiKeyHelper` 脚本提供凭证的会话

216* 不获取功能标志的会话，例如 Amazon Bedrock 上的会话或您设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 的会话217* 不获取功能标志的会话，例如 Amazon Bedrock 上的会话或您设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 的会话

217* [bare mode](/docs/zh-CN/headless#start-faster-with-bare-mode) 中的会话或您使用 `--safe-mode` 启动的会话218* [bare mode](/docs/zh-CN/headless#start-faster-with-bare-mode) 中的会话或您使用 `--safe-mode` 启动的会话

218* 您的组织的托管设置 [将 skills 锁定到 plugin 源](/docs/zh-CN/settings-reference#strictpluginonlycustomization-skills) 的会话，或您使用 [`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 列表启动的会话，该列表省略了 `user`219* 您的组织的托管设置 [将 skills 锁定到插件源](/docs/zh-CN/settings-reference#strictpluginonlycustomization-skills) 的会话，或您使用 [`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 列表启动的会话，该列表省略了 `user`

219 220

220如果您在会话期间使用 `/login` 登录，重新启动 Claude Code 以开始同步。221如果您在会话期间使用 `/login` 登录，请重新启动 Claude Code 以开始同步。

221 222

222较早会话同步的 Skills 保留在磁盘上。Claude Code 在登录到同一账户的后续会话中加载它们，即使它无法到达 claude.ai。223较早会话同步的 skills 保留在磁盘上。Claude Code 在稍后登录到同一账户的会话中加载它们，即使它无法到达 claude.ai。

223 224

224Claude Code 下载同步的 skills，从不上传它们。如果您或 Claude 编辑 `~/.claude/skills/synced/` 下的文件，更改不会保存到您的 claude.ai 账户，稍后的同步可能会覆盖或删除它。要更改同步的 skill，在 claude.ai 上更新它；下一次同步会下载新版本。225Claude Code 下载同步 skills，从不上传它们。如果您或 Claude 编辑 `~/.claude/skills/synced/` 下的文件，更改不会保存到您的 claude.ai 账户，稍后的同步可能会覆盖或删除它。要更改同步 skill，请在 claude.ai 上更新它；下一次同步会下载新版本。

225 226

226要查看哪些 skills 已同步，请运行 `/skills`。菜单在 `claude.ai sync` 下列出它们。227要查看哪些 skills 已同步，请运行 `/skills`。菜单在 `claude.ai sync` 下列出它们。

227 228

228Anthropic 的某些 skills，如 `pdf` 和 `xlsx`，总是同步。对于其余的，在 claude.ai 上的 skills 设置中打开或关闭 skill 以更改它是否同步。229Anthropic 的某些 skills，例如 `pdf` 和 `xlsx`，总是同步。对于其余的，在 claude.ai 上的 skills 设置中打开或关闭 skill 以更改是否同步。

229 230

230要停止在机器上同步，请在您的用户设置中将 [`syncClaudeAiSkills`](/docs/zh-CN/settings-reference#syncclaudeaiskills) 设置为 `false`。Claude Code 停止下载，下次启动时它会将已同步的 skills 移动到 `~/.claude/skills/.trash/`，不再加载它们。您的组织可以通过在 claude.ai 上关闭 Skills 来为所有人关闭同步。要在保持 Skills 打开的情况下停止同步，它可以在 [托管设置](/docs/zh-CN/managed-settings) 中设置相同的密钥。231要停止在机器上同步，请在您的用户设置中将 [`syncClaudeAiSkills`](/docs/zh-CN/settings-reference#syncclaudeaiskills) 设置为 `false`。Claude Code 停止下载，下次启动时它会将已同步的 skills 移动到 `~/.claude/skills/.trash/`，不再加载它们。您的组织可以通过在 claude.ai 上关闭 Skills 来为所有人关闭同步。要在保持 Skills 打开的情况下停止同步，它可以在 [托管设置](/docs/zh-CN/managed-settings) 中设置相同的密钥。

231 232

232如果您的组织在 claude.ai 上关闭 Skills，Claude Code 会删除下载的 skills，它们停止加载。删除的 skills 移动到 `~/.claude/skills/.trash/`，您可以在 [保留扫描](/docs/zh-CN/claude-directory#cleaned-up-automatically) 删除它们之前恢复文件。一旦您的组织重新打开 Skills，Claude Code 会在下一次同步时下载您启用的 skills。233如果您的组织在 claude.ai 上关闭 Skills，Claude Code 会删除下载的 skills，它们停止加载。删除的 skills 移动到 `~/.claude/skills/.trash/`，您可以在 [保留扫描](/docs/zh-CN/claude-directory#cleaned-up-automatically) 删除它们之前恢复文件。一旦您的组织重新打开 Skills，Claude Code 会在下一次同步时下载您启用的 skills。

233 234

234<h4 id="when-a-synced-skill-name-matches-another-command">235<h4 id="when-a-synced-skill-name-matches-another-command">

235 当同步的 skill 名称与另一个命令匹配时236 当同步 skill 名称与另一个命令匹配时

236</h4>237</h4>

237 238

238您可以通过其完整名称 `/anthropic-skills:<name>` 或其短名称 `/<name>` 调用同步的 skill。当另一个命令使用该短名称时，`/<name>` 运行另一个命令，同步的 skill 仅作为 `/anthropic-skills:<name>` 运行。使用本地 `deploy` skill 和同步的 `deploy` 时，`/deploy` 运行本地 skill，`/anthropic-skills:deploy` 运行同步的。在 v2.1.269 之前，同步的 skill 仅有其短名称。239您可以通过其短名称 `/<name>` 或完整名称 `/anthropic-skills:<name>` 调用同步 skill。当另一个命令使用短名称时，`/<name>` 运行另一个命令，同步 skill 仅作为 `/anthropic-skills:<name>` 运行。使用本地 `deploy` skill 和同步 `deploy` 时，`/deploy` 运行本地 skill，`/anthropic-skills:deploy` 运行同步的。在 v2.1.269 之前，同步 skill 仅有其短名称。

239 240

240另一个命令可以是以下任何一个：241在 `/` 菜单、`/skills` 和 `/context` 中，同步 skill 出现在其短名称下，或在另一个命令使用短名称时出现在其完整名称下。在您的会话中运行 `/skills`。列表下的注释解释了每个失去其短名称的同步 skill。如果您在 `~/.claude/` 中的个人 skills 或命令文件之一使用该名称，注释还会说明要重命名或删除什么以释放它。

242

243从 v2.1.269 到 v2.1.280，这些列表在其完整名称下显示每个同步 skill，`/skills` 没有这样的注释；两者都在 v2.1.281 中更改。

244

245使用短名称的命令可以是以下任何一个：

241 246

242* 内置命令或 [捆绑 skill](#bundled-skills)，包括在您的会话中不可用的，例如在您关闭捆绑 skills 后247* 内置命令或 [捆绑 skill](#bundled-skills)，包括在您的会话中不可用的，例如在您关闭捆绑 skills 后

243* 任何 [本地级别](#where-skills-live) 的 skill 或 `.claude/commands/` 中的文件248* 任何 [本地级别](#where-skills-live) 的 skill 或 `.claude/commands/` 中的文件

244* Plugin skill249* 插件 skill

245* [MCP prompt](/docs/zh-CN/mcp#use-mcp-prompts-as-commands)250* [MCP 提示](/docs/zh-CN/mcp#use-mcp-prompts-as-commands)

246 251

247Claude Code 标记同步的 skills，以便您可以看出它们来自何处。`/skills` 菜单和 `/context` 在 `claude.ai sync` 下分组同步的 skills，`/` 命令菜单将它们标记为来自 claude.ai。252Claude Code 标记同步 skills，以便您可以看出它们来自何处。`/skills` 菜单和 `/context` 在 `claude.ai sync` 下分组同步 skills，`/` 命令菜单将它们标记为来自 claude.ai。

248 253

249比较名称时，Claude Code 忽略大小写、间距和不可见字符，并将兼容性形式（如全宽字母和破折号变体）视为其纯等效形式。例如，名为 `Commit` 的同步 skill 和名为 `commit` 的本地 skill 计为相同名称，因此 `/commit` 继续运行您的本地 skill。254比较名称时，Claude Code 忽略大小写、间距和不可见字符，并将兼容性形式（如全宽字母和破折号变体）视为其纯等效形式。例如，名为 `Commit` 的同步 skill 和名为 `commit` 的本地 skill 计为相同名称，因此 `/commit` 继续运行您的本地 skill。

250 255

251仅因来自另一个字母表的相似字母而不同的名称计为不同名称，`claude.ai sync` 标签是您区分两者的方式。这些检查和标签需要 Claude Code v2.1.228 或更高版本。256仅因另一个字母表中的相似字母而不同的名称计为不同名称，`claude.ai sync` 标签是您区分两者的方式。这些检查和标签需要 Claude Code v2.1.228 或更高版本。

257

258<h4 id="names-reserved-for-synced-skills">

259 为同步 skills 保留的名称

260</h4>

261

262Claude Code 保留名称 `anthropic-skills` 和该命名空间内的每个名称（例如 `anthropic-skills:pdf`）用于从 claude.ai 同步的 skills，因此同步 skill 的完整名称永远不会运行其他任何东西。该名称在每个会话中保留，无论您是否使用 claude.ai 账户登录。

263

264* **Skill 文件夹、frontmatter `name`、`.claude/commands/` 中的文件或子文件夹，或 [保存的工作流](/docs/zh-CN/workflows#save-the-workflow-for-reuse)**：它不加载。[启动通知](/docs/zh-CN/errors#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) 命名要重命名或编辑的第一项。

265* **名为 `anthropic-skills` 的插件**：它加载。当其 skills 之一和同步 skill 都命名为 `<name>` 时，`/anthropic-skills:<name>` 运行同步 skill。

266* **名为 `anthropic-skills` 的 MCP 服务器**：它连接并且其工具有效，但 [其提示不显示为命令](/docs/zh-CN/mcp#use-mcp-prompts-as-commands)。在您的 MCP 配置中重命名服务器以列出它们。

252 267

253<h4 id="how-claude-code-handles-the-frontmatter-of-a-synced-skill">268<h4 id="how-claude-code-handles-the-frontmatter-of-a-synced-skill">

254 Claude Code 如何处理同步 skill 的 frontmatter269 Claude Code 如何处理同步 skill 的 frontmatter

256 271

257Claude Code 对同步 skill 的 frontmatter 应用两条规则：272Claude Code 对同步 skill 的 frontmatter 应用两条规则：

258 273

259* Claude Code 在每种会话中都遵守 frontmatter，因此 `allowed-tools` 授权通过正常的 [权限流](/docs/zh-CN/permissions) 进行。274* Claude Code 在每种会话中都遵守 frontmatter，因此 `allowed-tools` 授予通过正常 [权限流](/docs/zh-CN/permissions) 进行。

260* Claude Code 清理 skill 提供的显示文本，如其描述。它删除控制字符，在到达 Claude 的文本（如描述）中，它还转义尖括号，以便文本无法模仿 Claude Code 的内部格式。此清理需要 Claude Code v2.1.228 或更高版本。275* Claude Code 清理 skill 提供的显示文本，例如其描述。它删除控制字符，在到达 Claude 的文本（例如描述）中，它还转义尖括号，以便文本无法模仿 Claude Code 的内部格式。此清理需要 Claude Code v2.1.228 或更高版本。

261 276

262<h4 id="how-claude-code-handles-the-body-of-a-synced-skill">277<h4 id="how-claude-code-handles-the-body-of-a-synced-skill">

263 Claude Code 如何处理同步 skill 的正文278 Claude Code 如何处理同步 skill 的正文

265 280

266Claude Code 对同步 skill 的正文的处理取决于会话运行的位置：281Claude Code 对同步 skill 的正文的处理取决于会话运行的位置：

267 282

268* 在云会话中，正文保持本地 skill 具有的行为，因为会话在隔离的容器中运行。283* 在云会话中，正文保持本地 skill 具有的行为，因为会话在隔离容器中运行。

269* 在您桌面上的 Cowork 会话中，正文保持本地 skill 具有的行为，除了 Claude Code 将每个 `!` 命令行替换为 [`disableSkillShellExecution` 占位符](#inject-dynamic-context)，就像它对您在那里提供的每个 skill 所做的那样。284* 在您桌面上的 Cowork 会话中，正文保持本地 skill 具有的行为，除了 Claude Code 将每个 `!` 命令行替换为 [`disableSkillShellExecution` 占位符](#inject-dynamic-context)，就像它对您在那里提供的每个 skill 所做的那样。

270* 在您机器上的任何其他会话中，Claude Code 不运行 [`!` 命令](#inject-dynamic-context)，不附加 `@` 引用命名的文件（就像它对本地 skill 所做的那样），不替换 `${CLAUDE_PROJECT_DIR}` 和 `${CLAUDE_SESSION_ID}` 占位符，因此 `@` 引用和两个占位符都作为文字文本到达 Claude。`!` 命令行也作为文字文本到达 Claude，或当 `disableSkillShellExecution` 打开时作为该占位符。此处理需要 Claude Code v2.1.228 或更高版本。285* 在您机器上的任何其他会话中，Claude Code 不运行 [`!` 命令](#inject-dynamic-context)，不附加 `@` 引用命名的文件（就像它对本地 skill 所做的那样），不替换 `${CLAUDE_PROJECT_DIR}` 和 `${CLAUDE_SESSION_ID}` 占位符，因此 `@` 引用和两个占位符都作为文字文本到达 Claude。`!` 命令行也作为文字文本到达 Claude，或当 `disableSkillShellExecution` 打开时作为该占位符。此处理需要 Claude Code v2.1.228 或更高版本。

271 286

273 在会话期间编辑 skill288 在会话期间编辑 skill

274</h3>289</h3>

275 290

276Claude Code 监视 skill 目录的文件更改，除了在 [bare mode](/docs/zh-CN/headless#start-faster-with-bare-mode) 中。当您在 `~/.claude/skills/`、项目 `.claude/skills/` 或 `--add-dir` 目录内的 `.claude/skills/` 中添加、编辑或删除 skill 时，Claude Code 在当前会话中获取更改，无需重新启动。如果您创建会话启动时不存在的顶级 skills 目录，重新启动 Claude Code 以便它可以监视新目录。291Claude Code 监视 skill 目录的文件更改，除了在 [bare mode](/docs/zh-CN/headless#start-faster-with-bare-mode) 中。当您在 `~/.claude/skills/`、项目 `.claude/skills/` 或 `--add-dir` 目录内的 `.claude/skills/` 中添加、编辑或删除 skill 时，Claude Code 在当前会话中获取更改，无需重新启动。

277 292

278实时更改检测仅涵盖 `SKILL.md` 文本。对于也是 [plugin](/docs/zh-CN/plugins/loading#plugins-shared-through-a-repository) 的 skill 文件夹，对 `hooks/`、`.mcp.json`、`agents/` 和 `output-styles/` 的更改需要 `/reload-plugins` 才能生效。293如果您创建了会话启动时不存在的顶级 skills 目录，请运行 [`/reload-skills`](/docs/zh-CN/commands#all-commands) 以获取您放在那里的 skills。Claude Code 还没有监视该目录，因此在稍后每次更改后再次运行 `/reload-skills`。

294

295实时更改检测仅涵盖 `SKILL.md` 文本。对于也是 [插件](/docs/zh-CN/plugins/loading#plugins-shared-through-a-repository) 的 skill 文件夹，对 `hooks/`、`.mcp.json`、`agents/` 和 `output-styles/` 的更改需要 `/reload-plugins` 才能生效。

279 296

280<h3 id="remove-a-skill">297<h3 id="remove-a-skill">

281 删除 skill298 删除 skill

284删除 skill 的方式取决于它来自何处：301删除 skill 的方式取决于它来自何处：

285 302

286* **Personal 或 project skill**：删除 skill 的目录，`~/.claude/skills/<skill-name>/` 或 `.claude/skills/<skill-name>/`。Claude Code [在当前会话中从 `/skills` 中删除它](#live-change-detection)；Claude Code 已从中加载的内容遵循 [skill 内容生命周期](#skill-content-lifecycle)。303* **Personal 或 project skill**：删除 skill 的目录，`~/.claude/skills/<skill-name>/` 或 `.claude/skills/<skill-name>/`。Claude Code [在当前会话中从 `/skills` 中删除它](#live-change-detection)；Claude Code 已从中加载的内容遵循 [skill 内容生命周期](#skill-content-lifecycle)。

287* **Enterprise skill**：管理员从 [托管设置目录](/docs/zh-CN/managed-settings#delivery-mechanisms) 内的 `.claude/skills/` 中删除 skill 的目录，例如 Linux 上的 `/etc/claude-code/.claude/skills/<skill-name>/`。304* **Enterprise skill**：管理员从 [托管设置目录](/docs/zh-CN/managed-settings#delivery-mechanisms) 内的 `.claude/skills/` 删除 skill 的目录，例如 Linux 上的 `/etc/claude-code/.claude/skills/<skill-name>/`。

288* **Plugin skill**：从 `/plugin` 菜单禁用或卸载提供它的 plugin，或使用 `/plugin uninstall <plugin-name>@<marketplace-name>`。Claude Code 在 [更改应用](/docs/zh-CN/plugins/cli-reference#reload-plugins) 时或重新启动时卸载 plugin 的 skills。305* **Plugin skill**：从 `/plugin` 菜单禁用或卸载提供它的插件，或使用 `/plugin uninstall <plugin-name>@<marketplace-name>`。Claude Code 在 [更改应用](/docs/zh-CN/plugins/cli-reference#reload-plugins) 时或重新启动时卸载插件的 skills。

289* **从 claude.ai 同步的 Skill**：在您 [启用它](#skills-in-cowork-and-cloud-sessions) 的同一位置为您的 claude.ai 账户关闭该 skill。Claude Code 在下一次 [同步您的 skills](#where-synced-skills-load) 时从 `~/.claude/skills/synced/` 中删除它。如果您改为手动删除目录，下一次同步会在 skill 在 claude.ai 上保持启用的情况下再次下载它。306* **从 claude.ai 同步的 Skill**：在您 [启用它](#skills-in-cowork-and-cloud-sessions) 的同一位置为您的 claude.ai 账户关闭该 skill。Claude Code 在下一次 [同步您的 skills](#where-synced-skills-load) 时从 `~/.claude/skills/synced/` 中删除它。如果您改为手动删除目录，下一次同步会在 skill 在 claude.ai 上保持启用时再次下载它。

290* **捆绑 skill**：将 [`disableBundledSkills`](#bundled-skills) 设置为 `true` 以关闭捆绑 skills，或在 [`skillOverrides`](#override-skill-visibility-from-settings) 中将一个 skill 设置为 `"off"` 以隐藏它。307* **Bundled skill**：将 [`disableBundledSkills`](#bundled-skills) 设置为 `true` 以关闭捆绑 skills，或在 [`skillOverrides`](#override-skill-visibility-from-settings) 中将一个 skill 设置为 `"off"` 以隐藏它。

291 308

292要保留 personal 或 project skill 但阻止 Claude 自动调用它，请在其 frontmatter 中设置 [`disable-model-invocation: true`](#control-who-invokes-a-skill)，或在 [`skillOverrides`](#override-skill-visibility-from-settings) 中设置 `"user-invocable-only"`（当您不想编辑文件时）。309要保留 personal 或 project skill 但阻止 Claude 自动调用它，请在其 frontmatter 中设置 [`disable-model-invocation: true`](#control-who-invokes-a-skill)，或在不想编辑文件时在 [`skillOverrides`](#override-skill-visibility-from-settings) 中设置 `"user-invocable-only"`。

293 310

294<h2 id="configure-skills">311<h2 id="configure-skills">

295 配置 skills312 配置 skills

360 377

361| 字段 | 必需 | 描述 |378| 字段 | 必需 | 描述 |

362| :- | :- | :- |379| :- | :- | :- |

363| `name` | 否 | 在 skill 列表中显示的显示名称。默认为目录名称。请参阅[skill 如何获得其命令名称](#how-a-skill-gets-its-command-name)以了解该字段如何与你键入以调用 skill 的名称交互。 |380| `name` | 否 | 在 `/` 菜单中显示的命令名称。默认为目录名称。请参阅[skill 如何获得其命令名称](#how-a-skill-gets-its-command-name)以了解该字段如何与你键入以调用 skill 的名称交互。 |

364| `description` | 推荐 | skill 的功能以及何时使用它。Claude 使用此信息来决定何时应用该 skill。如果省略，则使用 markdown 内容的第一个非空行。首先放置关键用例：组合的 `description` 和 `when_to_use` 文本在 skill 列表中被截断为 1,536 个字符以减少上下文使用。 |381| `description` | 推荐 | skill 的功能以及何时使用它。Claude 使用此信息来决定何时应用该 skill。如果省略，则使用 markdown 内容的第一个非空行。首先放置关键用例：组合的 `description` 和 `when_to_use` 文本在 skill 列表中被截断为 1,536 个字符以减少上下文使用。 |

365| `when_to_use` | 否 | 关于 Claude 何时应调用该 skill 的其他上下文，例如触发短语或示例请求。附加到 skill 列表中的 `description`，并计入 1,536 字符的上限。 |382| `when_to_use` | 否 | 关于 Claude 何时应调用该 skill 的其他上下文，例如触发短语或示例请求。附加到 skill 列表中的 `description`，并计入 1,536 字符的上限。 |

366| `argument-hint` | 否 | 在自动完成期间显示的提示，以指示预期的参数。示例：`[issue-number]` 或 `[filename] [format]`。 |383| `argument-hint` | 否 | 在自动完成期间显示的提示，以指示预期的参数。示例：`[issue-number]` 或 `[filename] [format]`。 |

406 skill 如何获得其命令名称423 skill 如何获得其命令名称

407</h4>424</h4>

408 425

409你键入以调用 skill 的命令来自 skill 文件的位置，对于插件 skills，还来自 frontmatter `name` 字段。在个人或项目 skill 中，`name` 仅设置在 skill 列表中显示的显示标签，命令仍来自目录名称。在插件 skill 中，`name` 设置命令的最后一段，插件前缀保持不变。426你键入以调用 skill 的命令来自 skill 文件的位置，对于 skill 目录和插件 skills，还来自 frontmatter `name` 字段。在个人或项目 skill 目录中，`name` 设置 `/` 菜单显示的命令以及你键入的命令，除非另一个命令已使用该名称。目录名称也调用该 skill。在插件 skill 中，`name` 设置命令的最后一段，插件前缀保持不变。

410 427

411下表显示了每个布局的命令名称来自何处：428下表显示了每个布局的命令名称来自何处：

412 429

413| Skill 位置 | 命令名称来源 | 示例 |430| Skill 位置 | 命令名称来源 | 示例 |

414| :- | :- | :- |431| :- | :- | :- |

439| `$N` | `$ARGUMENTS[N]` 的简写，例如 `$0` 表示第一个参数或 `$1` 表示第二个参数。 |456| `$N` | `$ARGUMENTS[N]` 的简写，例如 `$0` 表示第一个参数或 `$1` 表示第二个参数。 |

440| `$name` | 在[`arguments`](#frontmatter-reference) frontmatter 列表中声明的命名参数。名称按顺序映射到位置，因此使用 `arguments: [issue, branch]`，占位符 `$issue` 扩展到第一个参数，`$branch` 扩展到第二个参数。 |457| `$name` | 在[`arguments`](#frontmatter-reference) frontmatter 列表中声明的命名参数。名称按顺序映射到位置，因此使用 `arguments: [issue, branch]`，占位符 `$issue` 扩展到第一个参数，`$branch` 扩展到第二个参数。 |

441| `${CLAUDE_SESSION_ID}` | 当前会话 ID。用于日志记录、创建会话特定文件或将 skill 输出与会话关联。 |458| `${CLAUDE_SESSION_ID}` | 当前会话 ID。用于日志记录、创建会话特定文件或将 skill 输出与会话关联。 |

442| `${CLAUDE_EFFORT}` | 当前工作量级别：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是一个不同的级别，报告为 `xhigh`。使用此来根据活动工作量设置调整 skill 说明。 |459| `${CLAUDE_EFFORT}` | 当前工作量级别：`low`、`medium`、`high`、`xhigh` 或 `max`。使用此来根据活动工作量设置调整 skill 说明。 |

443| `${CLAUDE_SKILL_DIR}` | 包含 skill 的 `SKILL.md` 文件的目录。对于插件 skills，这是插件内 skill 的子目录，而不是插件根。在 bash 注入命令中使用此来引用与 skill 捆绑的脚本或文件，无论当前工作目录如何。 |460| `${CLAUDE_SKILL_DIR}` | 包含 skill 的 `SKILL.md` 文件的目录。对于插件 skills，这是插件内 skill 的子目录，而不是插件根。在 bash 注入命令中使用此来引用与 skill 捆绑的脚本或文件，无论当前工作目录如何。 |

444| `${CLAUDE_PROJECT_DIR}` | 项目根目录。这是与[hooks](/docs/zh-CN/hooks#reference-scripts-by-path)和 MCP 服务器相同的路径，作为 `CLAUDE_PROJECT_DIR` 接收。使用此来引用项目本地脚本或文件，例如 `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`，独立于 skill 的安装位置。 |461| `${CLAUDE_PROJECT_DIR}` | 项目根目录。这是与[hooks](/docs/zh-CN/hooks#reference-scripts-by-path)和 MCP 服务器相同的路径，作为 `CLAUDE_PROJECT_DIR` 接收。使用此来引用项目本地脚本或文件，例如 `${CLAUDE_PROJECT_DIR}/.claude/hooks/helper.sh`，独立于 skill 的安装位置。 |

445| `${CLAUDE_PLUGIN_ROOT}` | 插件的安装目录。仅在插件 skills 中替换。使用此来引用插件中任何位置的脚本或文件，包括插件 skills 之间共享的资源。请参阅[插件环境变量](/docs/zh-CN/plugins/manifest-reference#environment-variables)。 |462| `${CLAUDE_PLUGIN_ROOT}` | 插件的安装目录。仅在插件 skills 中替换。使用此来引用插件中任何位置的脚本或文件，包括插件 skills 之间共享的资源。请参阅[插件环境变量](/docs/zh-CN/plugins/manifest-reference#environment-variables)。 |

826Skill(deploy *)843Skill(deploy *)

827```844```

828 845

829权限语法：`Skill(name)` 用于精确匹配，`Skill(name *)` 用于带任何参数的前缀匹配。846权限语法：`Skill(name)` 用于精确匹配，`Skill(name *)` 用于带任何参数的前缀匹配。在 `allow` 规则中，[为同步技能保留的命名空间](#names-reserved-for-synced-skills)之外的前缀不匹配其中的名称：`Skill(anthropic *)` 不涵盖 `anthropic-skills:pdf`。

830 847

831如果你的 `deny` 规则命名别名或不合格的名称而不是技能自己的名称，Claude Code 仍然会阻止该技能：使用 `Skill(review)` 它通过其 `/review` 别名阻止捆绑的 `/code-review`，使用 `Skill(deploy)` 它通过其不合格的名称阻止列为 `apps/web:deploy` 的[嵌套技能](#where-skills-live)。在 v2.1.260 之前，当拒绝规则仅命名不合格的名称时，Claude Code 不会阻止列在其合格名称下的嵌套技能。848如果你的 `deny` 规则命名别名或不合格的名称而不是技能自己的名称，Claude Code 仍然会阻止该技能：使用 `Skill(review)` 它通过其 `/review` 别名阻止捆绑的 `/code-review`，使用 `Skill(deploy)` 它通过其不合格的名称阻止列为 `apps/web:deploy` 的[嵌套技能](#where-skills-live)。在 v2.1.260 之前，当拒绝规则仅命名不合格的名称时，Claude Code 不会阻止列在其合格名称下的嵌套技能。

832 849

833Claude Code 仅针对技能自己的名称和 Claude 调用中的名称匹配 `allow` 规则。850Claude Code 仅针对技能自己的名称和 Claude 调用中的名称匹配 `allow` 规则。

834 851

852要在不提示的情况下批准[同步技能](#how-synced-skills-behave)，请在其[保留命名空间](#names-reserved-for-synced-skills)内命名它：`Skill(anthropic-skills:pdf)` 批准同步的 `pdf` 技能，`Skill(anthropic-skills *)` 批准每个同步的技能。

853

835**通过向其 frontmatter 添加 `disable-model-invocation: true` 来隐藏单个技能**。这将技能从 Claude 的上下文中完全删除。854**通过向其 frontmatter 添加 `disable-model-invocation: true` 来隐藏单个技能**。这将技能从 Claude 的上下文中完全删除。

836 855

837<Note>856<Note>

statusline.md +3 −3

Details

175 175

176Claude Code 捕获你的脚本输出而不是直接将其连接到终端，因此 `tput cols` 和语言级宽度检测无法从脚本内部读取终端大小。改为读取 `COLUMNS` 和 `LINES` 环境变量。Claude Code 在运行你的脚本之前将这些设置为当前终端尺寸。176Claude Code 捕获你的脚本输出而不是直接将其连接到终端，因此 `tput cols` 和语言级宽度检测无法从脚本内部读取终端大小。改为读取 `COLUMNS` 和 `LINES` 环境变量。Claude Code 在运行你的脚本之前将这些设置为当前终端尺寸。

177 177

178<Note>状态行在本地运行，不消耗 API 令牌。在某些 UI 交互期间，它会临时隐藏，包括自动完成建议、帮助菜单和权限提示。</Note>178<Note>状态行在本地运行，不消耗 API 令牌。在某些 UI 交互期间，它会临时隐藏，包括帮助菜单和权限提示。</Note>

179 179

180<h2 id="available-data">180<h2 id="available-data">

181 可用数据181 可用数据

205| `effort.level` | 当前推理工作量（`low`、`medium`、`high`、`xhigh` 或 `max`）。反映实时会话值，包括中途 `/effort` 更改。Ultracode 不是一个独立的级别，报告为 `xhigh`。当当前模型不支持工作量参数时不存在 |205| `effort.level` | 当前推理工作量（`low`、`medium`、`high`、`xhigh` 或 `max`）。反映实时会话值，包括中途 `/effort` 更改。当当前模型不支持工作量参数时不存在 |

1166* 在安装了 Git Bash 的 Windows 上，`command` 路径中的反斜杠可能在脚本运行前被当作转义字符消耗。在路径中使用正斜杠。参见 [Windows 配置](#windows-configuration)。1166* 在安装了 Git Bash 的 Windows 上，`command` 路径中的反斜杠可能在脚本运行前被当作转义字符消耗。在路径中使用正斜杠。参见 [Windows 配置](#windows-configuration)。

1167* 如果在应用 [设置优先级](/docs/zh-CN/hooks#disable-or-remove-hooks) 后 `disableAllHooks` 在托管设置之外为 `true`，Claude Code 仅运行来自托管设置的 `statusLine`，如果没有托管 `statusLine`，状态行将被禁用。删除该设置，或在设置它的文件中将其设置为 `false` 以重新启用。参见 [`disableAllHooks`](/docs/zh-CN/settings-reference#disableallhooks)。1167* 如果在应用 [设置优先级](/docs/zh-CN/hooks#disable-or-remove-hooks) 后 `disableAllHooks` 在托管设置之外为 `true`，Claude Code 仅运行来自托管设置的 `statusLine`，如果没有托管 `statusLine`，状态行将被禁用。删除该设置，或在设置它的文件中将其设置为 `false` 以重新启用。参见 [`disableAllHooks`](/docs/zh-CN/settings-reference#disableallhooks)。

1168* 如果你的组织在托管设置中设置了 `allowManagedHooksOnly`，你的自定义状态行会无警告地消失：你只能从那些托管设置中的 `statusLine` 值获得状态行。参见 [在 `allowManagedHooksOnly` 下运行的内容](/docs/zh-CN/settings-reference#what-runs-under-allowmanagedhooksonly) 了解完整行为，并询问你的管理员此设置是否适用于你。1168* 如果你的组织在托管设置中设置了 `allowManagedHooksOnly`，你的自定义状态行会无警告地消失：你只能从那些托管设置中的 `statusLine` 值获得状态行。参见 [在 `allowManagedHooksOnly` 下运行的内容](/docs/zh-CN/settings-reference#what-runs-under-allowmanagedhooksonly) 了解完整行为，并询问你的管理员此设置是否适用于你。

1169* 运行 `claude --debug` 以记录会话中第一次状态行调用的退出代码和 stderr1169* 运行 `claude --debug` 以在每次状态行调用时记录你的脚本的 stderr，以及在会话中第一次调用时的退出代码

1170* 要求 Claude 读取你的设置文件并直接执行 `statusLine` 命令以显示错误1170* 要求 Claude 读取你的设置文件并直接执行 `statusLine` 命令以显示错误

1171 1171

1172**状态行显示 `--` 或空值**1172**状态行显示 `--` 或空值**

sub-agents.md +11 −7

Details

8 8

9Subagents 是处理特定类型任务的专门 AI 助手。当一个辅助任务会用搜索结果、日志或文件内容充斥您的主对话，而您不会再次引用这些内容时，请使用一个 subagent：该 subagent 在自己的上下文中完成这项工作，仅返回摘要。当您不断生成相同类型的工作者并使用相同的指令时，定义一个自定义 subagent。9Subagents 是处理特定类型任务的专门 AI 助手。当一个辅助任务会用搜索结果、日志或文件内容充斥您的主对话，而您不会再次引用这些内容时，请使用一个 subagent：该 subagent 在自己的上下文中完成这项工作，仅返回摘要。当您不断生成相同类型的工作者并使用相同的指令时，定义一个自定义 subagent。

10 10

11每个 subagent 在自己的 context window 中运行，具有自定义系统提示、特定的工具访问权限和独立的权限。当 Claude 遇到与 subagent 描述相匹配的任务时，它会委托给该 subagent，该 subagent 独立工作并返回结果。要在实践中看到上下文节省，[context window 可视化](/docs/zh-CN/context-window) 演示了一个 subagent 在自己的独立窗口中处理研究的会话。11每个 subagent 在自己的 context window 中运行，具有自定义系统提示、特定的工具访问权限和独立的权限。它还发送自己的请求，这些请求计入与您的主对话相同的[使用限制](/docs/zh-CN/costs#plan-usage-breakdown)。当 Claude 遇到与 subagent 描述相匹配的任务时，它会委托给该 subagent，该 subagent 独立工作并返回结果。要在实践中看到上下文节省，[context window 可视化](/docs/zh-CN/context-window)演示了一个 subagent 在自己的独立窗口中处理研究的会话。

12 12

13<Note>13<Note>

14 Subagents 在单个会话中工作。要在并行运行许多独立会话并从一个地方监控它们，请参阅 [background agents](/docs/zh-CN/agent-view)。对于相互传递消息的单独会话，请参阅 [cross-session messaging](/docs/zh-CN/cross-session-messaging)。对于 Claude 生成和监督的协调团队会话，请参阅 [agent teams](/docs/zh-CN/agent-teams)。14 Subagents 在单个会话中工作。要在并行运行许多独立会话并从一个地方监控它们，请参阅 [background agents](/docs/zh-CN/agent-view)。对于相互传递消息的单独会话，请参阅 [cross-session messaging](/docs/zh-CN/cross-session-messaging)。对于 Claude 生成和监督的协调团队会话，请参阅 [agent teams](/docs/zh-CN/agent-teams)。

230 </Tab>230 </Tab>

231</Tabs>231</Tabs>

232 232

233`--agents` 标志接受 JSON，具有 `prompt` 字段加上这些 [frontmatter](#supported-frontmatter-fields) 字段：`description`、`tools`、`disallowedTools`、`model`、`permissionMode`、`mcpServers`、`hooks`、`maxTurns`、`skills`、`initialPrompt`、`memory`、`effort`、`background`、`omitClaudeMd` 和 `isolation`。对系统提示使用 `prompt`，等同于基于文件的 subagents 中的 markdown 正文。`color` 和 `experimental` 在此处不被接受，被忽略而不是拒绝。233在 [non-interactive mode](/docs/zh-CN/headless) 中，`--agents` 也接受保存相同对象的 JSON 文件的路径，用于定义太大而无法在命令行上传递的情况。例如，`claude -p --agents ./agents.json "Review my changes"` 从该文件读取定义。在交互式会话中，Claude Code 拒绝文件路径。文件形式需要 Claude Code v2.1.281 或更高版本。

234 234

235JSON 中的每个顶级键是代理的名称。不要以 `-` 开头的名称。235JSON 中的每个顶级键是代理的名称，其值是该代理的定义。不要以 `-` 开头的名称。定义采用这些字段：

236

237* **`prompt`**：代理的系统提示，等同于基于文件的 subagents 中的 markdown 正文。`prompt` 可能为空。如果您选择一个具有空 `prompt` 且没有 `memory` 字段的代理作为会话的代理，使用 `--agent`，会话的系统提示保持不变。空 `prompt` 需要 Claude Code v2.1.281 或更高版本。

238* **[Frontmatter 字段](#supported-frontmatter-fields)**：`description`、`tools`、`disallowedTools`、`model`、`permissionMode`、`mcpServers`、`hooks`、`maxTurns`、`skills`、`initialPrompt`、`memory`、`effort`、`background`、`omitClaudeMd` 和 `isolation`。

239* **忽略的字段**：`color` 和 `experimental` 在此处不被接受，被忽略而不是拒绝。

236 240

237有关 Claude Code 对无法加载的值的处理，以及跳过该检查的标志和环境变量，请参阅 [`Invalid --agents configuration`](/docs/zh-CN/errors#invalid-agents-configuration)。241有关 Claude Code 对无法加载的值的处理，以及跳过该检查的标志和环境变量，请参阅 [`Invalid --agents configuration`](/docs/zh-CN/errors#invalid-agents-configuration)。

238 242

587 权限模式591 权限模式

588</h4>592</h4>

589 593

590设置 `permissionMode` 以选择 subagent 运行的权限模式。使用模式的配置值，因此手动模式是 `default`。如果您不设置它，subagent 继承主对话的模式，该模式在 Pro、Max 和 Team 计划上一开始是 [auto mode](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)，除非您的设置或您的组织更改了它。594设置 `permissionMode` 以选择 subagent 运行的权限模式。使用模式的配置值，因此手动模式是 `default`。如果您不设置它，subagent 继承主对话的 [permission mode](/docs/zh-CN/permission-modes)。

591 595

592主对话的权限模式决定 Claude Code 是否使用您设置的值：596主对话的权限模式决定 Claude Code 是否使用您设置的值：

593 597

899claude --agent code-reviewer903claude --agent code-reviewer

900```904```

901 905

902Subagent 的系统提示完全替换默认 Claude Code 系统提示，就像 [`--system-prompt`](/docs/zh-CN/cli-reference) 一样。`CLAUDE.md` 文件和项目内存仍然通过正常消息流加载，即使代理的定义设置了 [`omitClaudeMd`](#supported-frontmatter-fields)。代理名称在启动标题中显示为 `@<name>`，以便您可以确认它是活跃的。906除非代理的 [提示为空](#choose-the-subagent-scope)，subagent 的系统提示完全替换默认 Claude Code 系统提示，就像 [`--system-prompt`](/docs/zh-CN/cli-reference) 一样。`CLAUDE.md` 文件和项目内存仍然通过正常消息流加载，即使代理的定义设置了 [`omitClaudeMd`](#supported-frontmatter-fields)。代理名称在启动标题中显示为 `@<name>`，以便您可以确认它是活跃的。

903 907

904这适用于内置和自定义 subagents，当您恢复会话时选择会持续：Claude Code 恢复代理的工具限制和模型以及对话。如果代理在您恢复时不再存在，会话继续使用默认工具并显示 [警告命名代理](/docs/zh-CN/errors#session-agent-no-longer-available)。对于任一情况下的系统提示，请参阅 [已恢复对话中的系统提示标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。908这适用于内置和自定义 subagents，当您恢复会话时选择会持续：Claude Code 恢复代理的工具限制和模型以及对话。如果代理在您恢复时不再存在，会话继续使用默认工具并显示 [警告命名代理](/docs/zh-CN/errors#session-agent-no-longer-available)。对于任一情况下的系统提示，请参阅 [已恢复对话中的系统提示标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。

905 909

1034每个 subagent 独立探索其区域，然后 Claude 综合这些发现。当研究路径彼此不依赖时，这效果最好。1038每个 subagent 独立探索其区域，然后 Claude 综合这些发现。当研究路径彼此不依赖时，这效果最好。

1035 1039

1036<Warning>1040<Warning>

1037 当 subagents 完成时，它们的结果返回到您的主对话。运行许多 subagents，每个都返回详细结果，可能会消耗大量上下文。1041 当 subagents 完成时，它们的结果返回到您的主对话。运行许多 subagents，每个都返回详细结果，可能会消耗大量上下文，每个 subagent 在运行时花费自己的令牌。

1038</Warning>1042</Warning>

1039 1043

1040对于需要持续并行运行或不适合一个上下文窗口的工作，在 [单独的会话](/docs/zh-CN/agents) 中运行它，让 Claude [在它们之间传递发现](/docs/zh-CN/cross-session-messaging)。1044对于需要持续并行运行或不适合一个上下文窗口的工作，在 [单独的会话](/docs/zh-CN/agents) 中运行它，让 Claude [在它们之间传递发现](/docs/zh-CN/cross-session-messaging)。

1133* **CLAUDE.md 文件**：主对话加载的 [CLAUDE.md 层次结构](/docs/zh-CN/memory#how-claude-md-files-load) 的每个级别，包括 `~/.claude/CLAUDE.md`、项目规则、`CLAUDE.local.md`、托管策略文件和任何 [`AGENTS.md` 文件](/docs/zh-CN/memory#agents-md) 作为项目指令加载。内置的 Explore 和 Plan 代理跳过这个。Subagent 的定义设置 [`omitClaudeMd`](#supported-frontmatter-fields) 时仅加载托管策略文件，或当定义来自 [托管设置](#choose-the-subagent-scope) 时不加载任何文件。1137* **CLAUDE.md 文件**：主对话加载的 [CLAUDE.md 层次结构](/docs/zh-CN/memory#how-claude-md-files-load) 的每个级别，包括 `~/.claude/CLAUDE.md`、项目规则、`CLAUDE.local.md`、托管策略文件和任何 [`AGENTS.md` 文件](/docs/zh-CN/memory#agents-md) 作为项目指令加载。内置的 Explore 和 Plan 代理跳过这个。Subagent 的定义设置 [`omitClaudeMd`](#supported-frontmatter-fields) 时仅加载托管策略文件，或当定义来自 [托管设置](#choose-the-subagent-scope) 时不加载任何文件。

1134* **Git 状态**：在 subagent 启动时从您的存储库读取的快照。在 Git 存储库外或每当快照关闭时不存在；请参阅 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions)。Explore 和 Plan 无论如何都跳过它。1138* **Git 状态**：在 subagent 启动时从您的存储库读取的快照。在 Git 存储库外或每当快照关闭时不存在；请参阅 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions)。Explore 和 Plan 无论如何都跳过它。

1135* **预加载的技能**：代理的 [`skills` 字段](#preload-skills-into-subagents) 中命名的任何技能的完整内容。内置代理不预加载技能。1139* **预加载的技能**：代理的 [`skills` 字段](#preload-skills-into-subagents) 中命名的任何技能的完整内容。内置代理不预加载技能。

1136* **兄弟名单**：系统提醒，列出 `main` 和会话中的每个其他命名代理，每个都是 [`SendMessage`](#resume-subagents) 的有效 `to` 值。需要 Claude Code v2.1.206 或更高版本。名单仅在 subagent 的工具包括 `SendMessage` 且至少有一个其他代理有名称时出现，无论 Claude 在生成时命名它还是它作为 [agent team](/docs/zh-CN/agent-teams) 队友运行。它是 subagent 启动时拍摄的快照，所以稍后命名的代理不会出现。1140* **兄弟名单**：[系统提醒](/docs/zh-CN/glossary#system-reminder)，列出 `main` 和会话中的每个其他命名代理，每个都是 [`SendMessage`](#resume-subagents) 的有效 `to` 值。需要 Claude Code v2.1.206 或更高版本。名单仅在 subagent 的工具包括 `SendMessage` 且至少有一个其他代理有名称时出现，无论 Claude 在生成时命名它还是它作为 [agent team](/docs/zh-CN/agent-teams) 队友运行。它是 subagent 启动时拍摄的快照，所以稍后命名的代理不会出现。

1137 1141

1138要启动您自己的 subagents 而不使用用户、项目和本地 CLAUDE.md 文件，在其 frontmatter 中设置 [`omitClaudeMd: true`](#supported-frontmatter-fields) 或 `--agents` JSON。1142要启动您自己的 subagents 而不使用用户、项目和本地 CLAUDE.md 文件，在其 frontmatter 中设置 [`omitClaudeMd: true`](#supported-frontmatter-fields) 或 `--agents` JSON。

1139 1143

terminal-config.md +6 −0

Details

339 ```339 ```

340</CodeGroup>340</CodeGroup>

341 341

342<h2 id="cap-response-width-in-wide-terminals">

343 在宽终端中限制响应宽度

344</h2>

345

346在宽终端中，Claude 响应中的每一行文本都会占据窗口的全部宽度。要改为在设定的列数处换行，请在您的设置中设置 [`maxProseWidth`](/docs/zh-CN/settings-reference#maxprosewidth)。

347

342<h2 id="paste-large-content">348<h2 id="paste-large-content">

343 粘贴大型内容349 粘贴大型内容

344</h2>350</h2>

tools-reference.md +3 −3

Details

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

14 14

15<Info>15<Info>

16 在 Pro、Max 和 Team 计划上，Claude Code 在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中启动会话，其中分类器决定大多数这些提示，而不是您。`Permission required` 列显示工具是否在[手动模式](/docs/zh-CN/permission-modes)中为工作目录内的路径提示。标记为"否"的文件访问工具，包括 `Read`、`Grep` 和 `Glob`，仍然会为[工作目录和其他目录](/docs/zh-CN/permissions#working-directories)之外的路径提示。`Bash` 标记为"是"，但运行内置的[只读命令](/docs/zh-CN/permissions#read-only-commands)而不提示。16 在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中，分类器决定大多数权限提示，而不是您。`Permission required` 列显示工具是否在[手动模式](/docs/zh-CN/permission-modes)中为工作目录内的路径提示。标记为"否"的文件访问工具，包括 `Read`、`Grep` 和 `Glob`，仍然会为[工作目录和其他目录](/docs/zh-CN/permissions#working-directories)之外的路径提示。`Bash` 标记为"是"，但运行内置的[只读命令](/docs/zh-CN/permissions#read-only-commands)而不提示。

17</Info>17</Info>

18 18

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

34| `Glob` | 基于模式匹配查找文件。在 macOS、Linux 和 WSL 上默认不存在。请参阅 [Glob 工具行为](#glob-tool-behavior) | 否 |34| `Glob` | 基于模式匹配查找文件。在 macOS、Linux 和 WSL 上默认不存在。请参阅 [Glob 工具行为](#glob-tool-behavior) | 否 |

35| `Grep` | 在文件内容中搜索模式。在 macOS、Linux 和 WSL 上默认不存在。请参阅 [Grep 工具行为](#grep-tool-behavior) | 否 |35| `Grep` | 在文件内容中搜索模式。在 macOS、Linux 和 WSL 上默认不存在。请参阅 [Grep 工具行为](#grep-tool-behavior) | 否 |

36| `ListAgents` | 列出 Claude 可以使用 `SendMessage` 消息的代理：会话中的子代理、[代理团队](/docs/zh-CN/agent-teams)队友、您的其他本地 Claude Code 会话，以及当此会话连接到[远程控制](/docs/zh-CN/remote-control)时，您的[网络版 Claude Code](/docs/zh-CN/claude-code-on-the-web) 会话和您在其他机器上的远程控制会话。支持 `/list-agents` 命令。请参阅[跨会话消息传递](/docs/zh-CN/cross-session-messaging)。需要 Claude Code v2.1.224 或更高版本，仅在[启用跨会话消息传递](/docs/zh-CN/cross-session-messaging#availability)的会话中出现。队友行和显示此会话自己名称的第一行需要 v2.1.239 或更高版本 | 否 |36| `ListAgents` | 列出 Claude 可以使用 `SendMessage` 消息的代理：会话中的子代理、[代理团队](/docs/zh-CN/agent-teams)队友、您的其他本地 Claude Code 会话，以及当此会话连接到[远程控制](/docs/zh-CN/remote-control)时，您的[网络版 Claude Code](/docs/zh-CN/claude-code-on-the-web) 会话和您在其他机器上的远程控制会话。支持 `/list-agents` 命令。请参阅[跨会话消息传递](/docs/zh-CN/cross-session-messaging)。需要 Claude Code v2.1.224 或更高版本，仅在[启用跨会话消息传递](/docs/zh-CN/cross-session-messaging#availability)的会话中出现。队友行和显示此会话自己名称的第一行需要 v2.1.239 或更高版本 | 否 |

~~37| `ListMcpResourcesTool` | 列出连接的 [MCP 服务器](/docs/zh-CN/mcp)公开的资源 | 否 |~~37| `ListMcpResourcesTool` | 列出连接的 [MCP 服务器](/docs/zh-CN/mcp)公开的资源，不包括 [MCP Apps UI 资源](/docs/zh-CN/mcp#reference-mcp-resources)，这些是主机应用程序要呈现的页面 | 否 |

38| `LSP` | 通过语言服务器的代码智能：跳转到定义、查找引用、报告类型错误和警告。请参阅 [LSP 工具行为](#lsp-tool-behavior) | 否 |38| `LSP` | 通过语言服务器的代码智能：跳转到定义、查找引用、报告类型错误和警告。请参阅 [LSP 工具行为](#lsp-tool-behavior) | 否 |

39| `Monitor` | 在后台运行命令并将每个输出行反馈给 Claude，以便它可以对日志条目、文件更改或轮询状态做出反应。还可以打开 WebSocket 并将每条传入消息视为事件。请参阅 [Monitor 工具](#monitor-tool) | 是 |39| `Monitor` | 在后台运行命令并将每个输出行反馈给 Claude，以便它可以对日志条目、文件更改或轮询状态做出反应。还可以打开 WebSocket 并将每条传入消息视为事件。请参阅 [Monitor 工具](#monitor-tool) | 是 |

40| `NotebookEdit` | 修改 Jupyter notebook 单元格。请参阅 [NotebookEdit 工具行为](#notebookedit-tool-behavior) | 是 |40| `NotebookEdit` | 修改 Jupyter notebook 单元格。请参阅 [NotebookEdit 工具行为](#notebookedit-tool-behavior) | 是 |

506Read 处理多种文件类型，不仅仅是纯文本：506Read 处理多种文件类型，不仅仅是纯文本：

507 507

508* **图像**：PNG、JPG 和其他图像格式作为 Claude 可以看到的视觉内容返回，而不是原始字节。Claude Code 在发送大型图像之前会调整大小并重新压缩，以适应模型的图像大小限制，因此 Claude 可能会看到大型屏幕截图的缩小版本。从 v2.1.196 开始，在调整大小后仍然大于 500KB 的图像会被重新编码为质量降低的 JPEG，其像素尺寸保持不变。如果 Claude 在大型图像中遗漏了细微的像素级细节，请要求它先裁剪感兴趣的区域，例如通过 Bash 使用 ImageMagick。508* **图像**：PNG、JPG 和其他图像格式作为 Claude 可以看到的视觉内容返回，而不是原始字节。Claude Code 在发送大型图像之前会调整大小并重新压缩，以适应模型的图像大小限制，因此 Claude 可能会看到大型屏幕截图的缩小版本。从 v2.1.196 开始，在调整大小后仍然大于 500KB 的图像会被重新编码为质量降低的 JPEG，其像素尺寸保持不变。如果 Claude 在大型图像中遗漏了细微的像素级细节，请要求它先裁剪感兴趣的区域，例如通过 Bash 使用 ImageMagick。

509* **PDF**：Claude 完整读取短 `.pdf` 文件。对于超过 10 页的 PDF，它使用 `pages` 参数按范围读取，例如 `"1-5"`，一次最多 20 页。509* **PDF**：Claude 完整读取短 `.pdf` 文件。对于超过 10 页的 PDF，它使用 `pages` 参数按范围读取，例如 `"1-5"`，一次最多 20 页。页面范围读取使用 poppler-utils 中的 `pdftoppm` 呈现页面，因此在 macOS 上使用 `brew install poppler` 安装，在 Debian 和 Ubuntu 上使用 `apt-get install poppler-utils` 安装。在 Windows 和其他平台上，安装一个将 `pdftoppm` 放在 `PATH` 上的 poppler 构建。没有它，页面范围读取会失败并显示 `pdftoppm is not installed`。

510* **Jupyter 笔记本**：`.ipynb` 文件返回所有单元格及其输出，包括代码、markdown 和可视化。Claude Code 拒绝读取超过 100 MB 的笔记本文件；错误会告诉 Claude 如何改为读取笔记本的一部分，例如使用 shell 命令读取单元格的一个切片。510* **Jupyter 笔记本**：`.ipynb` 文件返回所有单元格及其输出，包括代码、markdown 和可视化。Claude Code 拒绝读取超过 100 MB 的笔记本文件；错误会告诉 Claude 如何改为读取笔记本的一部分，例如使用 shell 命令读取单元格的一个切片。

511 511

512Read 仅读取文件，不读取目录。Claude 使用 shell 命令（如 `ls`）列出目录内容。512Read 仅读取文件，不读取目录。Claude 使用 shell 命令（如 `ls`）列出目录内容。

troubleshoot-install.md +43 −1

Details

41| `running scripts is disabled on this system` 或 `PSSecurityException` | [允许 npm shims 运行](#running-scripts-is-disabled-on-this-system) |41| `running scripts is disabled on this system` 或 `PSSecurityException` | [允许 npm shims 运行](#running-scripts-is-disabled-on-this-system) |

42| `Error: claude native binary not installed` | [完成 npm 安装](#native-binary-not-found-after-npm-install) |42| `Error: claude native binary not installed` | [完成 npm 安装](#native-binary-not-found-after-npm-install) |

43| 更新或重新安装期间 `npm error code ENOTEMPTY` | [删除剩余的包目录](#npm-enotempty-during-update-or-reinstall) |43| 更新或重新安装期间 `npm error code ENOTEMPTY` | [删除剩余的包目录](#npm-enotempty-during-update-or-reinstall) |

44| 在 Windows 上更新后 `'claude' is not recognized` | [从其备份恢复 `claude.exe`](#claude-exe-missing-after-an-update-on-windows) |

44| 在 Windows 上，安装命令打印脚本文本，但没有任何内容安装 | [运行完整的安装命令](#wrong-install-command-on-windows) |45| 在 Windows 上，安装命令打印脚本文本，但没有任何内容安装 | [运行完整的安装命令](#wrong-install-command-on-windows) |

45| `App unavailable in region` | Claude Code 在您的国家/地区不可用。请参阅[支持的国家/地区](https://www.anthropic.com/supported-countries)。 |46| `App unavailable in region` | Claude Code 在您的国家/地区不可用。请参阅[支持的国家/地区](https://www.anthropic.com/supported-countries)。 |

46| `unable to get local issuer certificate` | [配置企业 CA 证书](#tls-or-ssl-connection-errors) |47| `unable to get local issuer certificate` | [配置企业 CA 证书](#tls-or-ssl-connection-errors) |

47| `OAuth error` 或 `403 Forbidden` | [修复身份验证](#login-and-authentication) |48| `OAuth error` 或 `403 Forbidden` | [修复身份验证](#login-and-authentication) |

~~48| 设置期间 `Unable to connect to Anthropic services` | 请参阅错误参考中的 [Unable to connect to Anthropic services](/docs/zh-CN/errors#unable-to-connect-to-anthropic-services) |~~49| `Claude Code access has not been granted for this account` | [获取包含 Claude Code 的角色](#claude-code-access-has-not-been-granted-for-this-account) |

50| 设置期间 `Unable to connect to Anthropic services` | 请参阅[错误参考](/docs/zh-CN/errors#unable-to-connect-to-anthropic-services)中的 Unable to connect to Anthropic services |

49| `Could not load the default credentials` 或 `Could not load credentials from any providers` | [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 凭证](#bedrock-agent-platform-or-foundry-credentials-not-loading) |51| `Could not load the default credentials` 或 `Could not load credentials from any providers` | [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 凭证](#bedrock-agent-platform-or-foundry-credentials-not-loading) |

50| `ChainedTokenCredential authentication failed` 或 `CredentialUnavailableError` | [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 凭证](#bedrock-agent-platform-or-foundry-credentials-not-loading) |52| `ChainedTokenCredential authentication failed` 或 `CredentialUnavailableError` | [Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 凭证](#bedrock-agent-platform-or-foundry-credentials-not-loading) |

51| `API Error: 500`、`529 Overloaded`、`429` 或上面未列出的其他 4xx 和 5xx 错误 | 请参阅[错误参考](/docs/zh-CN/errors) |53| `API Error: 500`、`529 Overloaded`、`429` 或上面未列出的其他 4xx 和 5xx 错误 | 请参阅[错误参考](/docs/zh-CN/errors) |

149 source ~/.bashrc151 source ~/.bashrc

150 ```152 ```

151 153

154 对于 macOS 上的 Bash，请改为将该行添加到 `~/.bash_profile`。macOS 上的终端将 Bash 作为登录 shell 启动，它忽略 `~/.bashrc` 并仅读取存在的 `~/.bash_profile`、`~/.bash_login` 或 `~/.profile` 中的第一个。如果您已经有 `~/.bash_login` 或 `~/.profile` 且没有 `~/.bash_profile`，请将该行放在该文件中，而不是创建 `~/.bash_profile`：

155

156 ```bash theme={null}

157 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile

158 source ~/.bash_profile

159 ```

160

152 或者，关闭并重新打开您的终端。161 或者，关闭并重新打开您的终端。

153 162

154 对于其他 shell（如 fish 或 Nushell），使用您的 shell 自己的配置语法将 `~/.local/bin` 添加到您的 PATH，然后重启您的终端。163 对于其他 shell（如 fish 或 Nushell），使用您的 shell 自己的配置语法将 `~/.local/bin` 添加到您的 PATH，然后重启您的终端。

593irm https://claude.ai/install.ps1 | iex602irm https://claude.ai/install.ps1 | iex

594```603```

595 604

605<h3 id="claude-exe-missing-after-an-update-on-windows">

606 `claude.exe` 在 Windows 更新后丢失

607</h3>

608

609如果您的终端在 Claude Code 在 Windows 上更新后报告 `'claude' is not recognized`，请检查 `%USERPROFILE%\.local\bin` 是否仍然包含 `claude.exe`。如果该目录根本不在您的 PATH 上，请改为参阅[修复您的 PATH](#command-not-found-claude-after-installation)。要在 Windows 上更新，Claude Code 将现有的 `claude.exe` 重命名为备份，并将新版本移动到其位置。如果将新版本移动到位失败，Claude Code 也无法重命名备份，则该目录保留备份但没有 `claude.exe`。

610

611备份是同一目录中的一个文件，其名称以 `claude.exe.old.` 开头，后跟数字时间戳。在 PowerShell 中运行以下命令以将最新的备份重命名回 `claude.exe`：

612

613```powershell theme={null}

614Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe

615```

616

617然后运行 `claude --version` 确认修复。恢复的 `claude.exe` 打印版本号。

618

619如果没有 `claude.exe.old.*` 文件，或重命名后 `claude` 仍然失败，请改为重新安装：

620

621```powershell theme={null}

622irm https://claude.ai/install.ps1 | iex

623```

624

625在 v2.1.281 之前，Claude Code 可能在 `claude.exe` 仍然丢失时删除备份。

626

596<h3 id="install-killed-on-low-memory-linux-servers">627<h3 id="install-killed-on-low-memory-linux-servers">

597 在低内存 Linux 服务器上安装被杀死628 在低内存 Linux 服务器上安装被杀死

598</h3>629</h3>

992* **Anthropic Console 用户**：确认您的账户具有"Claude Code"或"Developer"角色。管理员在 Anthropic Console 的"Settings → Members"中分配此角色。1023* **Anthropic Console 用户**：确认您的账户具有"Claude Code"或"Developer"角色。管理员在 Anthropic Console 的"Settings → Members"中分配此角色。

993* **在代理后面**：企业代理可能干扰 API 请求。有关代理设置，请参阅 [network configuration](/docs/zh-CN/network-config)。1024* **在代理后面**：企业代理可能干扰 API 请求。有关代理设置，请参阅 [network configuration](/docs/zh-CN/network-config)。

994 1025

1026<h3 id="claude-code-access-has-not-been-granted-for-this-account">

1027 Claude Code 访问权限尚未为此账户授予

1028</h3>

1029

1030如果登录页面显示 `Authorization failed`，并显示消息 `Claude Code access has not been granted for this account. Contact your administrator.`，在您从 Claude Code 登录后，您的 Claude Enterprise 组织已将您的角色设置为"Custom"，并且分配给您的组的任何[自定义角色](https://support.claude.com/en/articles/13930452)都不授予 Claude Code 访问权限。在"Custom"角色上，您只能从这些自定义角色获得访问权限，因此您在 Claude Code 中所做的任何更改都无法解决此错误。

1031

1032要获得访问权限：

1033

10341. 请您的 Claude 组织的所有者将授予 Claude Code 访问权限的自定义角色分配给您的某个组，或将您的角色从"Custom"更改为标准角色（如"User"）。所有者在组织的[角色设置](https://claude.ai/admin-settings/roles)中管理角色。

10352. 所有者进行更改后，运行 `claude` 并再次登录。

1036

995<h3 id="this-organization-has-been-disabled-with-an-active-subscription">1037<h3 id="this-organization-has-been-disabled-with-an-active-subscription">

996 此组织已被禁用，但有活跃订阅1038 此组织已被禁用，但有活跃订阅

997</h3>1039</h3>

troubleshooting.md +1 −0

Details

17| 会话以自动模式启动，或 Claude 编辑文件并运行命令而不询问 | [会话启动的模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in) |17| 会话以自动模式启动，或 Claude 编辑文件并运行命令而不询问 | [会话启动的模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in) |

18| `API Error: 5xx`、`529 Overloaded`、`429`、请求验证错误 | [错误参考](/docs/zh-CN/errors) |18| `API Error: 5xx`、`529 Overloaded`、`429`、请求验证错误 | [错误参考](/docs/zh-CN/errors) |

19| `model not found` 或 `you may not have access to it` | [错误参考](/docs/zh-CN/errors#theres-an-issue-with-the-selected-model) |19| `model not found` 或 `you may not have access to it` | [错误参考](/docs/zh-CN/errors#theres-an-issue-with-the-selected-model) |

20| Claude 运行的命令失败，显示 `Your disk quota is full`、`is full (ENOSPC)` 或 `Command output was lost` | [错误参考](/docs/zh-CN/errors#disk-quota-or-temp-filesystem-is-full) |

20| VS Code 扩展未连接或未检测到 Claude | [VS Code 集成](/docs/zh-CN/vs-code#fix-common-issues) |21| VS Code 扩展未连接或未检测到 Claude | [VS Code 集成](/docs/zh-CN/vs-code#fix-common-issues) |

21| VS Code 或 SDK 应用中出现 `Claude Code process exited with code 1` | [错误参考](/docs/zh-CN/errors#claude-code-process-exited-with-code-n) |22| VS Code 或 SDK 应用中出现 `Claude Code process exited with code 1` | [错误参考](/docs/zh-CN/errors#claude-code-process-exited-with-code-n) |

22| JetBrains 插件或 IDE 未检测到 | [JetBrains 集成](/docs/zh-CN/jetbrains#troubleshooting) |23| JetBrains 插件或 IDE 未检测到 | [JetBrains 集成](/docs/zh-CN/jetbrains#troubleshooting) |

voice-dictation.md +2 −2

Details

30 启用语音听写30 启用语音听写

31</h2>31</h2>

32 32

~~33运行 `/voice` 启用听写。第一次启用时，Claude Code 会运行麦克风检查。在 macOS 上，这会触发系统麦克风权限提示，如果之前从未授予过权限。~~33运行 `/voice` 启用听写。启用时，Claude Code 会运行麦克风检查。在 macOS 上，如果之前从未授予过权限，这会触发终端的系统麦克风权限提示。

34 34

35```35```

36/voice36/voice

190* **`Voice mode requires SoX for audio recording` on Linux**：本机音频模块无法加载，没有安装回退。使用错误消息中显示的命令安装 SoX，例如 `sudo apt-get install sox`。190* **`Voice mode requires SoX for audio recording` on Linux**：本机音频模块无法加载，没有安装回退。使用错误消息中显示的命令安装 SoX，例如 `sudo apt-get install sox`。

191* **`Voice mode requires a microphone, but SoX could not open an audio capture device`**：SoX 已安装，但主机没有音频捕获设备，例如无头服务器或容器。在有麦克风的机器上运行 Claude Code。从 v2.1.195 开始，Linux 上的 Claude Code 在这种情况下报告此消息；早期版本即使已安装 SoX 也会要求你安装 SoX。191* **`Voice mode requires a microphone, but SoX could not open an audio capture device`**：SoX 已安装，但主机没有音频捕获设备，例如无头服务器或容器。在有麦克风的机器上运行 Claude Code。从 v2.1.195 开始，Linux 上的 Claude Code 在这种情况下报告此消息；早期版本即使已安装 SoX 也会要求你安装 SoX。

192* **`Voice mode could not find a working audio recorder in WSL`**：WSLg 通过 PulseAudio 而不是 ALSA 设备路由音频，因此 SoX 需要显式安装其 PulseAudio 后端。运行 `sudo apt install sox libsox-fmt-pulse`。单独安装 `sox` 会拉入 ALSA 后端，它无法在 WSL 上录制，因为没有 `/dev/snd` 设备。192* **`Voice mode could not find a working audio recorder in WSL`**：WSLg 通过 PulseAudio 而不是 ALSA 设备路由音频，因此 SoX 需要显式安装其 PulseAudio 后端。运行 `sudo apt install sox libsox-fmt-pulse`。单独安装 `sox` 会拉入 ALSA 后端，它无法在 WSL 上录制，因为没有 `/dev/snd` 设备。

193* **`Voice input is failing repeatedly and has been paused`**：语音听写在 10 秒内遇到三次捕获失败。Claude Code 暂停听写，直到自第一次失败以来已经过了 10 秒。无论麦克风无法启动还是录音机启动然后停止而不产生任何音频，失败都会被计数。这通常意味着此主机上的麦克风或音频堆栈无法捕获音频，例如无头服务器、没有音频直通的远程 shell 或被拒绝的麦克风权限。确认工作输入设备，从上面的条目中修复根本原因，然后再次触发语音。在 v2.1.202 之前，只有启动失败计入暂停。193* **`Voice input is failing repeatedly and has been paused`**：语音听写在 10 秒内遇到三次失败。Claude Code 暂停听写，直到自第一次失败以来已经过了 10 秒。这通常意味着此主机上的麦克风或音频堆栈无法捕获音频，例如无头服务器、没有音频直通的远程 shell 或被拒绝的麦克风权限。确认工作输入设备，从上面的条目中修复根本原因，然后再次触发语音。在 v2.1.202 之前，只有启动失败计入暂停。

194* **在按住模式中按住 `Space` 时没有任何反应**：在按住时观察提示词输入。如果空格不断累积，语音听写可能已关闭；运行 `/voice hold` 启用它。如果只出现一两个空格然后没有任何反应，语音听写已打开但按住检测未触发。按住检测需要你的终端发送按键重复事件，所以如果在操作系统级别禁用了按键重复，它无法检测按住的键。使用 `/voice tap` 切换到点击模式以避免按键重复要求。194* **在按住模式中按住 `Space` 时没有任何反应**：在按住时观察提示词输入。如果空格不断累积，语音听写可能已关闭；运行 `/voice hold` 启用它。如果只出现一两个空格然后没有任何反应，语音听写已打开但按住检测未触发。按住检测需要你的终端发送按键重复事件，所以如果在操作系统级别禁用了按键重复，它无法检测按住的键。使用 `/voice tap` 切换到点击模式以避免按键重复要求。

195* **在点击模式中点击 `Space` 输入空格而不是录制**：第一次点击仅在提示词输入为空时开始录制。先清除输入，或通过运行 `/voice tap` 检查你是否处于点击模式。195* **在点击模式中点击 `Space` 输入空格而不是录制**：第一次点击仅在提示词输入为空时开始录制。先清除输入，或通过运行 `/voice tap` 检查你是否处于点击模式。

196* **`No audio detected from microphone`**：录制开始但捕获了静音。确认正确的输入设备设置为系统默认值，其输入级别未静音或接近零。在 Windows 上，打开设置 → 系统 → 声音 → 输入并选择你的麦克风。在 macOS 上，打开系统设置 → 声音 → 输入。196* **`No audio detected from microphone`**：录制开始但捕获了静音。确认正确的输入设备设置为系统默认值，其输入级别未静音或接近零。在 Windows 上，打开设置 → 系统 → 声音 → 输入并选择你的麦克风。在 macOS 上，打开系统设置 → 声音 → 输入。

vs-code.md +34 −9

Details

109 109

110提示框支持多项功能：110提示框支持多项功能：

111 111

112* **权限模式**：点击提示框底部的模式指示器来切换权限模式。在 Pro、Max 和 Team 计划上，Auto 是内置的起始权限模式。请参阅[扩展程序如何选择起始权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)了解会改变这一点的因素，以及指示器提供的每种权限模式。112* **权限模式**：点击提示框底部的模式指示器来切换权限模式。在 Claude Code v2.1.283 或更高版本中，Auto 是内置的起始权限模式，在较早版本中仅在 Pro、Max 和 Team 计划上可用。请参阅[扩展程序如何选择起始权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)了解会改变这一点的因素，以及指示器提供的每种权限模式。

113 * **Auto**：分类器审查大多数操作，而不是询问您。请参阅 [auto 模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)了解它审查和阻止的内容。113 * **Auto**：分类器审查大多数操作，而不是询问您。请参阅 [auto 模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)了解它审查和阻止的内容。

114 * **Manual**：Claude 在文件编辑和大多数 shell 命令之前请求权限。114 * **Manual**：Claude 在文件编辑和大多数 shell 命令之前请求权限。

115 * **Plan**：Claude 描述它将做什么，并在进行更改之前等待批准。VS Code 自动将计划作为完整的 Markdown 文档打开，您可以在其中添加内联注释以在 Claude 开始之前提供反馈。115 * **Plan**：Claude 描述它将做什么，并在进行更改之前等待批准。VS Code 自动将计划作为完整的 Markdown 文档打开，您可以在其中添加内联注释以在 Claude 开始之前提供反馈。

123* **Model**：从命令菜单中选择 **Switch model…** 以在会话中途更改模型。您也可以点击提示框底部的模型名称来打开相同的选择器。123* **Model**：从命令菜单中选择 **Switch model…** 以在会话中途更改模型。您也可以点击提示框底部的模型名称来打开相同的选择器。

124 124

125 当当前模型支持[工作量级别](/docs/zh-CN/model-config#adjust-effort-level)时，选择器还会显示 **Effort** 行和模型名称按钮显示选定的级别。当您选择除 `max` 之外的级别时，Claude Code 会在 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 下的用户设置中将其保存为当前模型的默认值；`max` 仅适用于当前会话。模型名称按钮和 **Effort** 行需要 Claude Code v2.1.257 或更高版本。125 当当前模型支持[工作量级别](/docs/zh-CN/model-config#adjust-effort-level)时，选择器还会显示 **Effort** 行和模型名称按钮显示选定的级别。当您选择除 `max` 之外的级别时，Claude Code 会在 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 下的用户设置中将其保存为当前模型的默认值；`max` 仅适用于当前会话。模型名称按钮和 **Effort** 行需要 Claude Code v2.1.257 或更高版本。

126

127 当[动态工作流](/docs/zh-CN/workflows)启用且当前模型支持时，**Effort** 行下会出现 **Ultracode** 开关。打开它以让 Claude 为此会话中的每个实质性任务规划[工作流](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)，在选定的工作量级别。当它打开时，模型名称按钮在级别后显示 `· Ultracode`。该开关需要 Claude Code v2.1.284 或更高版本。

126* **Command menu**：点击 `/` 或输入 `/` 来打开命令菜单。选项包括附加文件、切换模型和切换扩展思考。128* **Command menu**：点击 `/` 或输入 `/` 来打开命令菜单。选项包括附加文件、切换模型和切换扩展思考。

127 129

128 Customize 部分提供对 MCP 服务器、slash commands、输出样式、hooks、memory、instructions、permissions 和 plugins 的访问。带有终端图标的项目在集成终端中打开。130 Customize 部分提供对 MCP 服务器、slash commands、输出样式、hooks、memory、instructions、permissions 和 plugins 的访问。带有终端图标的项目在集成终端中打开。

150 152

151 Claude 的最新待办事项列表保持可见，Claude 提出的待处理问题的文本也保持可见；这需要 Claude Code v2.1.225 或更高版本。当 Claude 运行[子代理](/docs/zh-CN/sub-agents)时，带有其最新活动的实时进度行出现在启动它们的工具调用组下。这需要 Claude Code v2.1.269 或更高版本。153 Claude 的最新待办事项列表保持可见，Claude 提出的待处理问题的文本也保持可见；这需要 Claude Code v2.1.225 或更高版本。当 Claude 运行[子代理](/docs/zh-CN/sub-agents)时，带有其最新活动的实时进度行出现在启动它们的工具调用组下。这需要 Claude Code v2.1.269 或更高版本。

152 * 要登出您的 Anthropic 账户，请在 Settings 部分中选择 **Sign out**，或输入 `/logout`。在[第三方提供商](#use-third-party-providers)上，菜单不提供任何一个。需要 Claude Code v2.1.277 或更高版本。154 * 要登出您的 Anthropic 账户，请在 Settings 部分中选择 **Sign out**，或输入 `/logout`。在[第三方提供商](#use-third-party-providers)上，菜单不提供任何一个。需要 Claude Code v2.1.277 或更高版本。

153 * 要报告错误，请点击菜单底部的 **Report a problem**，或输入 `/bug` 或 `/feedback` 以及可选的描述来预填充报告。当您提交报告并且您在第一方连接上登录到 Anthropic 时，Claude Code 会将其发送给 Anthropic。在第三方提供商上，或没有 Anthropic 凭证的情况下，对话框仍会打开，但提交会显示错误并不发送任何内容：与 CLI 的 `/bug` 不同，扩展程序不会写入本地存档。需要 Claude Code v2.1.229 或更高版本。155 * 要报告错误，请点击菜单底部的 **Report a problem**，或输入 `/bug` 或 `/feedback` 以及可选的描述来预填充报告。当您提交报告并且您在第一方连接上登录到 Anthropic 时，Claude Code 会将其发送给 Anthropic。需要 Claude Code v2.1.229 或更高版本。

156

157 在第三方提供商上，或没有 Anthropic 凭证的情况下，不会发送任何内容。对话框在您写入之前会说明这一点。提交会将报告保存为[本地存档在 `~/.claude/feedback-bundles/`](/docs/zh-CN/data-usage#telemetry-services)，其中已知的 API 密钥和令牌模式被编辑。将该文件发送给您的 Anthropic 账户代表或将其附加到支持请求。确认会命名该文件并包括一个 **Show folder** 按钮。在您的计算机上保存报告需要 Claude Code v2.1.284 或更高版本。

154 158

155 如果您的组织的策略关闭了产品反馈，**Report a problem** 不会出现在菜单中，`/bug` 和 `/feedback` 会显示 `Feedback is turned off by your organization's policy or this environment's settings.` 通知，而不是打开报告。159 如果您的组织的策略关闭了产品反馈，**Report a problem** 不会出现在菜单中，`/bug` 和 `/feedback` 会显示 `Feedback is turned off by your organization's policy or this environment's settings.` 通知，而不是打开报告。使用 Claude Code v2.1.284 或更高版本，如果您设置了 `DISABLE_FEEDBACK_COMMAND` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 环境变量，反馈也会被关闭，打开报告会显示该通知。

156* **Side questions**：输入 `/btw` 后跟一个问题来提问您的会话[而不添加到对话](/docs/zh-CN/interactive-mode#side-questions-with-%2Fbtw)。答案在聊天旁边的面板中打开，您可以在其中提出后续问题。线程在窗口重新加载后仍然存在。Claude Code 保留最新的 20 个交换，并根据 [`cleanupPeriodDays`](/docs/zh-CN/settings-reference#cleanupperioddays) 计划过期存储的线程，只要 Claude Code 可以[安全地确定保留期](/docs/zh-CN/claude-directory#cleaned-up-automatically)。要清除线程，请点击面板中的垃圾箱图标。需要 Claude Code v2.1.227 或更高版本。160* **Side questions**：输入 `/btw` 后跟一个问题来提问您的会话[而不添加到对话](/docs/zh-CN/interactive-mode#side-questions-with-%2Fbtw)。答案在聊天旁边的面板中打开，您可以在其中提出后续问题。线程在窗口重新加载后仍然存在。Claude Code 保留最新的 20 个交换，并根据 [`cleanupPeriodDays`](/docs/zh-CN/settings-reference#cleanupperioddays) 计划过期存储的线程，只要 Claude Code 可以[安全地确定保留期](/docs/zh-CN/claude-directory#cleaned-up-automatically)。要清除线程，请点击面板中的垃圾箱图标。需要 Claude Code v2.1.227 或更高版本。

157* **Copy a response**：将鼠标悬停在响应上并点击 **Copy response** 来将其复制到您的剪贴板，或输入 `/copy` 来复制最新的响应。`/copy 2` 复制倒数第二个。需要 Claude Code v2.1.277 或更高版本。161* **Copy a response**：将鼠标悬停在响应上并点击 **Copy response** 来将其复制到您的剪贴板，或输入 `/copy` 来复制最新的响应。`/copy 2` 复制倒数第二个。需要 Claude Code v2.1.277 或更高版本。

158* **Context indicator**：提示框显示您使用了多少 Claude 的上下文窗口。Claude 在需要时自动压缩，或者您可以手动运行 `/compact`。162* **Context indicator**：提示框显示您使用了多少 Claude 的上下文窗口。Claude 在需要时自动压缩，或者您可以手动运行 `/compact`。

181What's in @src/components/ (include a trailing slash for folders)185What's in @src/components/ (include a trailing slash for folders)

182```186```

183 187

184对于大型 PDF，您可以要求 Claude 读取特定页面而不是整个文件：单个页面、范围如第 1-10 页，或开放式范围如第 3 页及以后。188对于大型 PDF，您可以要求 Claude 读取特定页面而不是整个文件：单个页面、范围如第 1-10 页，或开放式范围如第 3 页及以后。读取特定页面需要在 Claude Code 运行的机器上安装 [poppler-utils](/docs/zh-CN/tools-reference#read-tool-behavior)。

185 189

186当您在编辑器中选择文本时，Claude 可以自动看到您突出显示的代码。提示框页脚显示选择了多少行。按 `Option+K`（Mac）/ `Alt+K`（Windows/Linux）来插入带有文件路径和行号的 @-mention（例如 `@app.ts#5-10`）。点击选择指示器上的 **X** 来删除它，这样 Claude 就不会收到选择。当您选择其他文本时，指示器会重新出现。190当您在编辑器中选择文本时，Claude 可以自动看到您突出显示的代码。提示框页脚显示选择了多少行。按 `Option+K`（Mac）/ `Alt+K`（Windows/Linux）来插入带有文件路径和行号的 @-mention（例如 `@app.ts#5-10`）。点击选择指示器上的 **X** 来删除它，这样 Claude 就不会收到选择。当您选择其他文本时，指示器会重新出现。

187 191

242 </Step>246 </Step>

243 247

244 <Step title="选择要恢复的会话">248 <Step title="选择要恢复的会话">

245 浏览或搜索您的云会话。点击任何会话来下载它并在本地继续对话。249 浏览或搜索会话。点击一个来继续本地对话。

246 </Step>250 </Step>

247</Steps>251</Steps>

248 252

249<Note>253<Note>

250 只有使用 GitHub 存储库启动的网络会话才会出现在 Web 选项卡中。恢复会在本地加载对话历史；更改不会同步回 claude.ai。254 当您打开的文件夹是 GitHub 存储库时，Web 选项卡仅显示来自该存储库的会话。

255

256 当您恢复云会话时，扩展程序会下载对话历史的副本；更改不会同步回 claude.ai。

251</Note>257</Note>

252 258

259Web 选项卡还列出您的 [Remote Control](/docs/zh-CN/remote-control) 会话。如果您点击在您打开的文件夹中运行的会话，扩展程序会打开该本地对话，而不是下载副本，如果有的话，会聚焦已显示它的选项卡。如果扩展程序无法排除另一个 Claude 进程已打开对话，您会获得下载的副本。

260

261如果对话的任何部分下载失败，会出现错误，不会保存副本。再次选择会话以重试。如果您选择还没有对话可下载的会话，错误会告诉您在哪里继续它。

262

253<h3 id="check-account-and-usage">263<h3 id="check-account-and-usage">

254 检查账户和使用情况264 检查账户和使用情况

255</h3>265</h3>

269 自定义您的工作流279 自定义您的工作流

270</h2>280</h2>

271 281

272您可以重新定位 Claude 面板、运行多个对话、将会话列表组织成组，或切换到终端模式。282您可以重新定位 Claude 面板、运行多个对话、将会话列表组织成组或筛选会话列表，或切换到终端模式。

273 283

274<h3 id="choose-where-claude-lives">284<h3 id="choose-where-claude-lives">

275 选择 Claude 的位置285 选择 Claude 的位置

319 329

320该扩展按工作区文件夹保存组，因此它们在窗口重新加载后仍然存在，并在您打开相同文件夹的每个窗口中出现。当您搜索列表时，该扩展在所有组中的一个平面列表中显示匹配项。330该扩展按工作区文件夹保存组，因此它们在窗口重新加载后仍然存在，并在您打开相同文件夹的每个窗口中出现。当您搜索列表时，该扩展在所有组中的一个平面列表中显示匹配项。

321 331

332<h3 id="filter-the-sessions-list">

333 筛选会话列表

334</h3>

335

336要缩小 Activity Bar 中的长会话列表，请使用列表顶部的两个筛选控件。需要 Claude Code v2.1.271 或更高版本。启用任一筛选器时，已归档的会话不会显示。

337

338* **Active**：打开此切换开关以仅显示需要您输入、正在工作或未读的会话，以及您最后关注的 Claude 选项卡中的会话。

339* **按状态筛选**：单击漏斗图标，然后勾选 **Needs input**、**Working** 或 **Completed** 以显示处于任何这些状态的会话。勾选 **Open** 或 **Closed** 以按会话是否打开来缩小范围。当会话在此窗口中有选项卡或在此计算机上的另一个 Claude Code 进程中运行（例如在终端中）时，会话计为打开。

340

341当 **Active** 打开且您勾选状态、**Open** 或 **Closed** 时，列表还会显示与您的检查匹配的每个会话。您设置的筛选器在窗口重新加载后保持不变。

342

322<h3 id="switch-to-terminal-mode">343<h3 id="switch-to-terminal-mode">

323 切换到终端模式344 切换到终端模式

324</h3>345</h3>

506该扩展有两种类型的设置：527该扩展有两种类型的设置：

507 528

508* **VS Code 中的扩展设置**：控制扩展在 VS Code 中的行为。使用 `Cmd+,`（Mac）或 `Ctrl+,`（Windows/Linux）打开，然后转到扩展 → Claude Code。您也可以输入 `/` 并选择 **General config…** 来打开设置。529* **VS Code 中的扩展设置**：控制扩展在 VS Code 中的行为。使用 `Cmd+,`（Mac）或 `Ctrl+,`（Windows/Linux）打开，然后转到扩展 → Claude Code。您也可以输入 `/` 并选择 **General config…** 来打开设置。

509* **`~/.claude/settings.json` 中的 Claude Code 设置**：在扩展和 CLI 之间共享。用于允许的命令、环境变量、hooks 和 MCP 服务器。在 Pro、Max 和 Team 计划上，它也是权限模式对话开始时的一个输入。[切换权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)列出了顺序。有关详细信息，请参阅[设置](/docs/zh-CN/settings)。530* **`~/.claude/settings.json` 中的 Claude Code 设置**：在扩展和 CLI 之间共享。用于允许的命令、环境变量、hooks 和 MCP 服务器。在 Claude Code v2.1.283 或更高版本中，它也是权限模式对话开始时的一个输入，在早期版本中仅在 Pro、Max 和 Team 计划上。[切换权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)列出了顺序。有关详细信息，请参阅[设置](/docs/zh-CN/settings)。

510 531

511<Tip>532<Tip>

512 将 `"$schema": "https://json.schemastore.org/claude-code-settings.json"` 添加到您的 `settings.json` 中，以在 VS Code 中直接获得所有可用设置的自动完成和内联验证。533 将 `"$schema": "https://json.schemastore.org/claude-code-settings.json"` 添加到您的 `settings.json` 中，以在 VS Code 中直接获得所有可用设置的自动完成和内联验证。

720 741

721服务器名为 `ide`，从 `/mcp` 中隐藏，因为没有什么需要配置的。但是，如果您的组织使用 `PreToolUse` hook 来允许列表 MCP 工具，您需要知道它的存在。742服务器名为 `ide`，从 `/mcp` 中隐藏，因为没有什么需要配置的。但是，如果您的组织使用 `PreToolUse` hook 来允许列表 MCP 工具，您需要知道它的存在。

722 743

723**选择和打开文件上下文。** 连接时，CLI 会在您发送的每个提示中包含您当前的编辑器选择和活动文件的路径作为上下文。当发生这种情况时，记录会显示一行 `⧉ Selected N lines from <file>`。要排除敏感文件（如 `.env`），请为其路径添加 [`Read` 拒绝规则](/docs/zh-CN/permissions#read-and-edit)。匹配的拒绝规则可防止该文件的选定文本和打开文件通知到达 Claude。744**选择和打开文件上下文。** 连接时，CLI 会在您发送的每个提示中包含您当前的编辑器选择和活动文件的路径作为上下文。当发生这种情况时，记录会显示一行 `⧉ Selected N lines from <file>`。

745

746如果您[在 Claude 工作时排队消息](/docs/zh-CN/interactive-mode#queue-messages-while-claude-works)，它会保留您按下 `Enter` 时的选择，无论您之后选择什么。

747

748要排除敏感文件（如 `.env`），请为其路径添加 [`Read` 拒绝规则](/docs/zh-CN/permissions#read-and-edit)。匹配的拒绝规则可防止该文件的选定文本和打开文件通知到达 Claude。

724 749

725如果您关闭[附加打开文件设置](#extension-settings)，CLI 仅在您在该文件中选择文本时接收活动文件的路径。750如果您关闭[附加打开文件设置](#extension-settings)，CLI 仅在您在该文件中选择文本时接收活动文件的路径。

726 751

web-quickstart.md +3 −3

Details

231 231

232云会话需要连接的 GitHub 账户。通过上面的浏览器流程连接，或如果您使用 GitHub CLI，从您的终端运行 `/web-setup`。如果您根本不想连接 GitHub，请参阅 [Remote Control](/docs/zh-CN/remote-control) 以在您自己的机器上运行 Claude Code 并从浏览器或手机监控它。232云会话需要连接的 GitHub 账户。通过上面的浏览器流程连接，或如果您使用 GitHub CLI，从您的终端运行 `/web-setup`。如果您根本不想连接 GitHub，请参阅 [Remote Control](/docs/zh-CN/remote-control) 以在您自己的机器上运行 Claude Code 并从浏览器或手机监控它。

233 233

234<h3 id="not-available-for-the-selected-organization">234<h3 id="claude-code-isn’t-available-on-your-account">

235 "Not available for the selected organization"235 "Claude Code isn't available on your account"

236</h3>236</h3>

237 237

238企业组织可能需要所有者启用云会话。联系您的 Anthropic 账户团队。238您在所选组织中的席位不包括 Claude Code。如果您属于另一个组织，请点击该页面上的**切换组织**。否则，请要求组织的所有者为您分配一个[包括 Claude Code 的席位](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan)。

239 239

240<h3 id="/web-setup-says-not-signed-in-to-claude">240<h3 id="/web-setup-says-not-signed-in-to-claude">

241 `/web-setup` 说 "Not signed in to Claude"241 `/web-setup` 说 "Not signed in to Claude"

whats-new/2026-w19.md +2 −2

Details

42 <p className="digest-wins-title">其他改进</p>42 <p className="digest-wins-title">其他改进</p>

43 43

44 <div className="digest-wins-grid">44 <div className="digest-wins-grid">

45 <div>新的 <code>worktree.baseRef</code> 设置（<code>fresh</code> | <code>head</code>）控制 <code>--worktree</code>、<code>EnterWorktree</code> 工具和agent-isolation worktrees是从远程默认分支还是本地 <code>HEAD</code> 创建分支；默认的 <code>fresh</code> 将未推送的提交排除在新worktrees之外</div>45 <div>新的 <code>worktree.baseRef</code> 设置（<code>fresh</code> | <code>head</code>）控制 `--worktree`、<code>EnterWorktree</code> 工具和agent-isolation worktrees是从远程默认分支还是本地 <code>HEAD</code> 创建分支；默认的 <code>fresh</code> 将未推送的提交排除在新worktrees之外</div>

46 <div>新的 <code>settings.autoMode.hard\_deny</code> 规则在自动模式下无条件阻止匹配的操作，无论allow例外如何，用于不应该自动运行的操作，即使应用了更广泛的allow规则</div>46 <div>新的 <code>settings.autoMode.hard\_deny</code> 规则在自动模式下无条件阻止匹配的操作，无论allow例外如何，用于不应该自动运行的操作，即使应用了更广泛的allow规则</div>

47 <div>Hooks现在通过 `effort.level` JSON输入字段和 `$CLAUDE_EFFORT` 环境变量接收活跃的effort level，Bash工具命令可以读取 <code>\$CLAUDE\_EFFORT</code></div>47 <div>Hooks现在通过 `effort.level` JSON输入字段和 `$CLAUDE_EFFORT` 环境变量接收活跃的effort level，Bash工具命令可以读取 <code>\$CLAUDE\_EFFORT</code></div>

48 <div><code>CLAUDE\_CODE\_DISABLE\_ALTERNATE\_SCREEN=1</code> 选择退出全屏alternate-screen渲染器，并将对话保留在终端的原生scrollback中</div>48 <div><code>CLAUDE\_CODE\_DISABLE\_ALTERNATE\_SCREEN=1</code> 选择退出全屏alternate-screen渲染器，并将对话保留在终端的原生scrollback中</div>

49 <div><code>CLAUDE\_CODE\_PACKAGE\_MANAGER\_AUTO\_UPDATE</code> 允许Homebrew或WinGet安装在后台运行升级并提示重启</div>49 <div><code>CLAUDE\_CODE\_PACKAGE\_MANAGER\_AUTO\_UPDATE</code> 允许Homebrew或WinGet安装在后台运行升级并提示重启</div>

50 <div><code>CLAUDE\_CODE\_SESSION\_ID</code> 现在在Bash工具子进程环境中，与传递给hooks的 <code>session\_id</code> 匹配</div>50 <div><code>CLAUDE\_CODE\_SESSION\_ID</code> 现在在Bash工具子进程环境中，与传递给hooks的 <code>session\_id</code> 匹配</div>

51 <div><code>/mcp</code> 现在显示已连接服务器的工具计数，并标记以0个工具连接的服务器</div>51 <div><code>/mcp</code> 现在显示已连接服务器的工具计数，并标记以0个工具连接的服务器</div>

~~52 <div><code>--channels</code> 现在适用于console（API key）身份验证</div>~~52 <div>`--channels` 现在适用于console（API key）身份验证</div>

53 <div>Bash、hooks、MCP和LSP等子进程不再继承 <code>OTEL\_\*</code> 环境变量，因此通过Bash工具运行的OTEL检测应用不再获取CLI自己的OTLP端点</div>53 <div>Bash、hooks、MCP和LSP等子进程不再继承 <code>OTEL\_\*</code> 环境变量，因此通过Bash工具运行的OTEL检测应用不再获取CLI自己的OTLP端点</div>

54 <div>Sub-agent进度摘要现在命中prompt cache，将 <code>cache\_creation</code> token成本降低约3倍</div>54 <div>Sub-agent进度摘要现在命中prompt cache，将 <code>cache\_creation</code> token成本降低约3倍</div>

55 <div>多个OAuth和凭证可靠性修复：并行会话在refresh-token竞争后不再在401处死亡，MCP OAuth刷新令牌在多个服务器并发刷新时不再丢失，并修复了来自并发凭证写入的罕见登录循环</div>55 <div>多个OAuth和凭证可靠性修复：并行会话在refresh-token竞争后不再在401处死亡，MCP OAuth刷新令牌在多个服务器并发刷新时不再丢失，并修复了来自并发凭证写入的罕见登录循环</div>

workflows.md +14 −6

Details

161 让 Claude 使用 ultracode 决定161 让 Claude 使用 ultracode 决定

162</h3>162</h3>

163 163

164Ultracode 是一个 Claude Code 设置，它结合了 `xhigh` [推理努力](/docs/zh-CN/model-config#adjust-effort-level)与自动工作流编排。启用它后，Claude 为每个实质性任务规划工作流，而不是等待您要求。164Ultracode 是一个 Claude Code 设置，它为会话启用自动工作流编排，在会话运行的任何[努力级别](/docs/zh-CN/model-config#adjust-effort-level)。启用它后，Claude 为每个实质性任务规划工作流，而不是等待您要求。在 Claude Code 提示处启用它：

165 165

166```text wrap theme={null}166```text wrap theme={null}

167/effort ultracode167/effort ultracode

168```168```

169 169

170要启动已启用 ultracode 的会话，请使用 `claude --effort ultracode` 启动。需要 Claude Code v2.1.203 或更高版本。170要启动已启用 ultracode 的会话，请使用 `claude --effort ultracode` 启动，这也会将努力级别设置为 `xhigh`。需要 Claude Code v2.1.203 或更高版本。

171 171

172要在您选择模型时启用它，将 `/model` 选择器的努力滑块移动到 `ultracode`，使用箭头键。[调整努力级别](/docs/zh-CN/model-config#adjust-effort-level)列出启用 ultracode 的路由。172要从 `/effort` 滑块启用它，按 `Tab` 翻转 **Ultracode** 切换，然后按 `Enter` 应用它。[调整努力级别](/docs/zh-CN/model-config#adjust-effort-level)列出启用 ultracode 的路由。

173 173

174启用 ultracode 后，Claude 决定任务何时值得工作流。单个请求可以变成一系列工作流：一个理解代码，一个进行更改，一个验证它。这适用于会话中的每个任务，所以每个请求使用更多令牌并花费比较低努力级别更长的时间。174启用 ultracode 后，Claude 决定任务何时值得工作流。单个请求可以变成一系列工作流：一个理解代码，一个进行更改，一个验证它。这适用于会话中的每个任务，所以每个请求使用更多令牌并花费比没有工作流的相同请求更长的时间。在订阅计划上，这些令牌会计入您的使用限制，所以启用 ultracode 的会话比关闭时进行相同工作更快达到会话或每周限制。

175 175

176`/effort ultracode` 持续当前会话；要让每个会话都以它开始，设置 [`ultracode`](/docs/zh-CN/settings-reference#ultracode) 设置。当您返回日常工作时，使用 `/effort high` 下降。`/effort` 菜单仅在 [ultracode 可用时](/docs/zh-CN/model-config#when-ultracode-is-available)提供它。176启用 ultracode 已经选择加入大型运行，所以启用它时这些检查不适用：

177

178* 工作流运行时不会出现 [`Large workflow` 警告](#cost)

179* 会话的[并发子代理限制](/docs/zh-CN/sub-agents#concurrent-subagent-limit)对 Claude 使用 Agent 工具生成的子代理不强制执行

180* 在自动权限模式下，您不会被要求[批准第一个工作流启动](#approve-the-plan-before-it-runs)

181

182`/effort ultracode` 持续当前会话；要让每个会话都以它开始，设置 [`ultracode`](/docs/zh-CN/settings-reference#ultracode) 设置。当您返回日常工作时，使用 `/effort ultracode off` 关闭它。`/effort` 滑块仅在 [ultracode 可用时](/docs/zh-CN/model-config#when-ultracode-is-available)提供切换。

177 183

178<h3 id="approve-the-plan-before-it-runs">184<h3 id="approve-the-plan-before-it-runs">

179 在运行前批准计划185 在运行前批准计划

516 522

517要为整个组织关闭工作流，在[托管设置](/docs/zh-CN/server-managed-settings)中设置 `"disableWorkflows": true`，或使用[Claude Code 管理员设置](https://claude.ai/admin-settings/claude-code)页面上的切换。523要为整个组织关闭工作流，在[托管设置](/docs/zh-CN/server-managed-settings)中设置 `"disableWorkflows": true`，或使用[Claude Code 管理员设置](https://claude.ai/admin-settings/claude-code)页面上的切换。

518 524

519当工作流被禁用时，捆绑工作流命令和 `/workflow-authoring` skill 不可用，`ultracode` 关键字不再触发运行，`ultracode` 从 `/effort` 菜单中移除。525当工作流被禁用时，捆绑工作流命令和 `/workflow-authoring` skill 不可用，`ultracode` 关键字不再触发运行，**Ultracode** 切换从 `/effort` 中移除。一个已在进行中的运行会继续进行。

526

527关闭工作流也会使[ultracode](#let-claude-decide-with-ultracode)不可用。没有托管设置单独排除 ultracode：无论它在哪里[可用](/docs/zh-CN/model-config#when-ultracode-is-available)，用户可以使用 `/effort ultracode` 打开它。[努力上限](/docs/zh-CN/model-config#organization-effort-limits)降低了启用 ultracode 的会话运行的努力级别，但不会关闭 ultracode。

520 528

521<h2 id="related-resources">529<h2 id="related-resources">

522 相关资源530 相关资源

worktrees.md +7 −7

Details

59 清理 worktrees59 清理 worktrees

60</h2>60</h2>

61 61

62当您退出交互式 worktree 会话时，Claude 会检查 worktree 中的工作，删除会丢失这些工作：已更改或未跟踪的文件、已检出子模块内的未提交工作以及新提交。62当你退出交互式 worktree 会话时，Claude 会检查 worktree 中是否有删除会丢失的工作：已更改或未跟踪的文件、已检出子模块内的未提交工作，以及新提交。这些规则适用于 Claude 使用 git 创建的 worktrees。对于你的 [WorktreeCreate hook](/docs/zh-CN/hooks#worktreecreate) 创建的 worktree，请改为参阅 [WorktreeRemove](/docs/zh-CN/hooks#worktreeremove)。

63 63

64* **worktree 是干净的**：对于未命名的会话，Claude 会自动删除 worktree 及其分支。[命名](/docs/zh-CN/sessions#name-your-sessions)的会话会提示您，以便您可以稍后保留 worktree64* **worktree 是干净的**：对于未命名的会话，Claude 会自动删除 worktree 及其分支。[已命名](/docs/zh-CN/sessions#name-your-sessions)的会话会先提示你，以便你可以保留 worktree 供以后使用

65* **worktree 中有工作**：Claude 提示您保留或删除 worktree。保留会保留目录和分支，以便您稍后可以返回。删除会删除 worktree 目录及其分支，以及其中的所有工作65* **worktree 中有工作**：Claude 会提示你保留或删除 worktree。保留会保留目录和分支。要稍后返回，请运行 Claude Code 在退出时打印的 `claude --worktree <name> --resume` 命令。删除会删除 worktree 目录及其分支，以及其中的所有工作

66* **worktree 的状态无法验证**：当 Claude Code 无法计算 worktree 的更改或无法检查其子模块检出时，它会提示您而不是自动删除 worktree。提示会说明它无法检查的内容66* **无法验证 worktree 的状态**：当 Claude Code 无法计算 worktree 的更改或无法检查其子模块检出时，它会提示你而不是自动删除 worktree。提示会说明它无法检查的内容

67 67

68使用 `-p` 的非交互式运行没有退出提示，因此 Claude 不会清理它们的 worktrees，Claude Code 会保留它在创建时对每个 worktree 所取的锁，直到稍后会话的[陈旧锁扫描](#clean-up-subagent-and-background-session-worktrees)释放它。要删除一个，请运行 `git worktree remove`；如果 git 拒绝因为 worktree 被锁定，请先在其上运行 `git worktree unlock`。68使用 `-p` 的非交互式运行没有退出提示，因此 Claude 不会清理它们的 worktrees，Claude Code 会保留它在创建时对每个 worktree 所取的锁，直到稍后会话的[陈旧锁扫描](#clean-up-subagent-and-background-session-worktrees)释放它。要删除一个，请运行 `git worktree remove`；如果 git 拒绝因为 worktree 被锁定，请先在其上运行 `git worktree unlock`。

69 69

70在 Windows 上，删除 worktree 不会删除其外部的文件。如果 worktree 内的文件夹是指向其他地方的链接，例如 NTFS 接合点或目录符号链接，Claude Code 只删除链接并保留它指向的文件夹。在 v2.1.205 之前，删除包含嵌套在子目录中的链接的 worktree 可能会删除它指向的文件夹。70在 Windows 上，删除 worktree 不会删除其外部的文件。如果 worktree 内的文件夹是指向其他地方的链接，例如 NTFS 接合点或目录符号链接，Claude Code 只删除链接并保留它指向的文件夹。在 v2.1.205 之前，删除嵌套在子目录中的链接的 worktree 可能会删除它指向的文件夹。

71 71

72<h2 id="resume-a-worktree-session">72<h2 id="resume-a-worktree-session">

73 恢复 worktree 会话73 恢复 worktree 会话

74</h2>74</h2>

75 75

76当您恢复在 worktree 内的会话时，Claude Code 会将会话返回到该 worktree。这适用于交互式恢复、[非交互式模式](/docs/zh-CN/headless)中带有 `-p` 的 `--continue` 和 `--resume`，以及 Agent SDK。回到 worktree 内，Claude 仍然可以使用 [`ExitWorktree`](/docs/zh-CN/tools-reference) 工具退出它。76当您恢复在 worktree 内结束的会话而未[退出它](#clean-up-worktrees)时，Claude Code 会将会话返回到该 worktree。这适用于交互式恢复、[非交互式模式](/docs/zh-CN/headless)中带有 `-p` 的 `--continue` 和 `--resume`，以及 Agent SDK。`--continue` 会选择从您启动的目录下记录的最近会话。回到 worktree 内，Claude 仍然可以使用 [`ExitWorktree`](/docs/zh-CN/tools-reference) 工具退出它。

77 77

78在将会话返回到其 worktree 之前，Claude Code 会验证 worktree 仍然是与主检出分开的检出，并拒绝重新进入未通过检查的 worktree。对于 git worktree，检查会读取其 git 元数据。没有 git 元数据的 worktree（例如 [`WorktreeCreate` hook](#non-git-version-control) 创建的）可以通过检查；Claude Code 仍然拒绝的情况列在[Claude Code 拒绝使用 worktree](#claude-code-refuses-to-use-a-worktree) 下及其恢复。有关消息和如何从每个消息恢复，请参阅[会话在其 worktree 外恢复](#the-session-resumes-outside-its-worktree)。78在将会话返回到其 worktree 之前，Claude Code 会验证 worktree 仍然是与主检出分开的检出，并拒绝重新进入未通过检查的 worktree。对于 git worktree，检查会读取其 git 元数据。没有 git 元数据的 worktree（例如 [`WorktreeCreate` hook](#non-git-version-control) 创建的）可以通过检查；Claude Code 仍然拒绝的情况列在[Claude Code 拒绝使用 worktree](#claude-code-refuses-to-use-a-worktree) 下及其恢复。有关消息和如何从每个消息恢复，请参阅[会话在其 worktree 外恢复](#the-session-resumes-outside-its-worktree)。

79 79

80您从哪里启动以及如何恢复会改变 Claude Code 重新进入的内容：80您从哪里启动以及如何恢复会改变 Claude Code 重新进入的内容：

81 81

82* **启动目录**：从主检出或存储库的另一个目录恢复。Claude Code 会重新进入它使用 git 在 `.claude/worktrees/` 下创建的 worktree，即使您从其内部启动。当您从任何其他 worktree 内启动时，Claude Code 只有在能够从那里为其担保时才会重新进入它：一个是其自己的存储库的 worktree、一个没有 git 元数据的 worktree，或从您使用 `git worktree add` 创建的 worktree 的子目录启动会拒绝，因此从主检出启动这些。82* **启动目录**：从主检出或存储库的另一个目录使用 `--resume` 恢复。Claude Code 会重新进入它使用 git 在 `.claude/worktrees/` 下创建的 worktree，即使您从其内部启动。当您从任何其他 worktree 内启动时，Claude Code 只有在能够从那里为其担保时才会重新进入它：一个是其自己的存储库的 worktree、一个没有 git 元数据的 worktree，或从您使用 `git worktree add` 创建的 worktree 的子目录启动会拒绝，因此从主检出启动这些。

83* **`--fork-session`**：分叉的会话在您启动 Claude 的目录中启动，Claude Code 会保持原始会话的 worktree 不变。83* **`--fork-session`**：分叉的会话在您启动 Claude 的目录中启动，Claude Code 会保持原始会话的 worktree 不变。

84* **已删除的 worktree**：如果 worktree 目录不再存在，Claude Code 会在您启动 Claude 的目录中恢复会话。它告诉您 worktree 已消失并清除会话的 worktree 绑定。84* **已删除的 worktree**：如果 worktree 目录不再存在，Claude Code 会在您启动 Claude 的目录中恢复会话。它告诉您 worktree 已消失并清除会话的 worktree 绑定。

85 85

Documentation 2026-09-28 22:59 UTC to 2026-09-29 21:59 UTC