Documentation — Spybara

accessibility.md +0 −2

Details

10 10

11屏幕阅读器模式是可选的。如果您使用屏幕放大镜、减少动画或色盲友好主题而不是屏幕阅读器，请从[辅助功能设置](#accessibility-settings)表中设置 `CLAUDE_CODE_ACCESSIBILITY`、`prefersReducedMotion` 或 `theme`。屏幕阅读器模式仅调整终端界面，因此您不需要在 VS Code 扩展的聊天面板中使用它。在 Claude Code v2.1.236 或更高版本上，该扩展[在不需要任何设置的情况下向您的屏幕阅读器宣布对话活动](/docs/zh-CN/vs-code#use-a-screen-reader)。11屏幕阅读器模式是可选的。如果您使用屏幕放大镜、减少动画或色盲友好主题而不是屏幕阅读器，请从[辅助功能设置](#accessibility-settings)表中设置 `CLAUDE_CODE_ACCESSIBILITY`、`prefersReducedMotion` 或 `theme`。屏幕阅读器模式仅调整终端界面，因此您不需要在 VS Code 扩展的聊天面板中使用它。在 Claude Code v2.1.236 或更高版本上，该扩展[在不需要任何设置的情况下向您的屏幕阅读器宣布对话活动](/docs/zh-CN/vs-code#use-a-screen-reader)。

12 12

~~13屏幕阅读器模式需要 Claude Code v2.1.181 或更高版本。早期版本会拒绝 `--ax-screen-reader` 标志，并显示 `error: unknown option '--ax-screen-reader'`。~~

15<h2 id="turn-on-screen-reader-mode">13<h2 id="turn-on-screen-reader-mode">

16 打开屏幕阅读器模式14 打开屏幕阅读器模式

17</h2>15</h2>

admin-setup.md +4 −3

Details

36| Google Cloud's Agent Platform | 您希望继承现有的 GCP 合规控制和计费 |36| Google Cloud's Agent Platform | 您希望继承现有的 GCP 合规控制和计费 |

37| Microsoft Foundry | 您希望继承现有的 Azure 合规控制和计费 |37| Microsoft Foundry | 您希望继承现有的 Azure 合规控制和计费 |

38 38

39某些 Claude Code 功能需要 claude.ai 账户。[Claude Code on the web](/docs/zh-CN/claude-code-on-the-web)、[Routines](/docs/zh-CN/routines)、[Code Review](/docs/zh-CN/code-review)、[Remote Control](/docs/zh-CN/remote-control) 和 [Chrome extension](/docs/zh-CN/chrome) 不能仅通过 Console API 密钥或云提供商凭证使用。如果您通过 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 部署，请计划开发人员是否还需要 Claude for Teams 或 Enterprise 座位。每个功能页面都列出了其计划要求。39某些 Claude Code 功能需要 claude.ai 账户。[Cloud sessions](/docs/zh-CN/claude-code-on-the-web)、[Routines](/docs/zh-CN/routines)、[Code Review](/docs/zh-CN/code-review)、[Remote Control](/docs/zh-CN/remote-control) 和 [Chrome extension](/docs/zh-CN/chrome) 不能仅通过 Console API 密钥或云提供商凭证使用。如果您通过 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 部署，请计划开发人员是否还需要 Claude for Teams 或 Enterprise 座位。每个功能页面都列出了其计划要求。

40 40

41有关涵盖身份验证、区域和功能奇偶性的完整提供商比较，请参阅 [enterprise deployment overview](/docs/zh-CN/third-party-integrations)。每个提供商的身份验证设置在 [Authentication](/docs/zh-CN/authentication) 中。41有关涵盖身份验证、区域和功能奇偶性的完整提供商比较，请参阅 [enterprise deployment overview](/docs/zh-CN/third-party-integrations)。每个提供商的身份验证设置在 [Authentication](/docs/zh-CN/authentication) 中。

42 42

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

104| [Plugin marketplace control](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) | 限制用户可以添加和安装的市场来源，拒绝为单次运行侧加载插件、agents 和 MCP 服务器的 CLI 标志，阻止[`command` 插件源](/docs/zh-CN/plugin-marketplaces#command-sources)，并允许列出哪些市场的插件可以被建议 | `strictKnownMarketplaces`、`blockedMarketplaces`、`disableSideloadFlags`、`disableCommandPluginSources`、`pluginSuggestionMarketplaces` |104| [Plugin marketplace control](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) | 限制用户可以添加和安装的市场来源，拒绝为单次运行侧加载插件、agents 和 MCP 服务器的 CLI 标志，阻止[`command` 插件源](/docs/zh-CN/plugin-marketplaces#command-sources)，并允许列出哪些市场的插件可以被建议 | `strictKnownMarketplaces`、`blockedMarketplaces`、`disableSideloadFlags`、`disableCommandPluginSources`、`pluginSuggestionMarketplaces` |

105| [Customization lockdown](/docs/zh-CN/settings-reference#strictpluginonlycustomization) | 阻止 skills、agents、hooks 和 MCP 服务器来自用户和项目源，使它们只能来自插件或托管设置 | `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-reference#synced-plugins)。如果您为组织关闭 claude.ai 上的 Skills，Claude Code 会停止同步两者，在 v2.1.273 或更高版本上，它也会删除已同步的那些。要在不关闭 Skills 的情况下停止其中任一个，在托管设置中将其键设置为 `false` | `syncClaudeAiSkills`、`syncClaudeAiPlugins` |

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

107| [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` 进行身份验证的会话在启动时被阻止；云提供商会话不受影响 | `forceLoginMethod`、`forceLoginOrgUUID` |

121 122

122这些控制都不会到达 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 上的会话。在这些提供商上，使用托管设置代替：`availableModels` 用于限制，`model` 用于默认值，[`maxEffortLevel`](/docs/zh-CN/settings-reference#maxeffortlevel) 用于工作量限制。123这些控制都不会到达 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 上的会话。在这些提供商上，使用托管设置代替：`availableModels` 用于限制，`model` 用于默认值，[`maxEffortLevel`](/docs/zh-CN/settings-reference#maxeffortlevel) 用于工作量限制。

123 124

124[Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 有其自己的管理表面：在管理设置中的 Cloud environments 页面上，所有者创建[组织共享环境](/docs/zh-CN/cloud-environments#organization-shared-environments)，设置成员云会话的[网络访问级别](/docs/zh-CN/cloud-environments#network-access)、环境变量和设置脚本。所有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 单独选择组织的默认环境。125[Cloud sessions](/docs/zh-CN/claude-code-on-the-web) 有其自己的管理表面：在管理设置中的 Cloud environments 页面上，所有者创建[组织共享环境](/docs/zh-CN/cloud-environments#organization-shared-environments)，设置成员云会话的[网络访问级别](/docs/zh-CN/cloud-environments#network-access)、环境变量和设置脚本。所有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 单独选择组织的默认环境。

125 126

126权限规则和沙箱覆盖不同的层。拒绝 WebFetch 会阻止 Claude 的 fetch 工具，但如果允许 Bash，`curl` 和 `wget` 仍然可以到达任何 URL。沙箱通过在操作系统级别强制执行的网络域允许列表来弥补这一差距。127权限规则和沙箱覆盖不同的层。拒绝 WebFetch 会阻止 Claude 的 fetch 工具，但如果允许 Bash，`curl` 和 `wget` 仍然可以到达任何 URL。沙箱通过在操作系统级别强制执行的网络域允许列表来弥补这一差距。

127 128

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

Details

222 222

223预算上限涵盖 [子代理](/docs/zh-CN/agent-sdk/subagents)：它们的支出计入总额。一旦支出达到上限，生成另一个子代理会失败并显示 `Budget limit reached`，Claude Code 会停止任何仍在运行的后台子代理。上限执行行为需要 Claude Code v2.1.217 或更高版本。223预算上限涵盖 [子代理](/docs/zh-CN/agent-sdk/subagents)：它们的支出计入总额。一旦支出达到上限，生成另一个子代理会失败并显示 `Budget limit reached`，Claude Code 会停止任何仍在运行的后台子代理。上限执行行为需要 Claude Code v2.1.217 或更高版本。

224 224

225使用 [流式输入](/docs/zh-CN/agent-sdk/streaming-vs-single-mode)，当轮次在最大轮次限制处结束时，仍在队列中的消息保持排队。Claude Code 不会将其添加到该轮次的最后一次模型调用中。它为该消息启动新轮次，该轮次的最大轮次计数重新开始。225使用 [流式输入](/docs/zh-CN/agent-sdk/streaming-vs-single-mode)，当轮次在最大轮次限制处结束时，仍在队列中的消息保持排队。Claude Code 不会将其添加到该轮次的最后一次模型调用中。它为该消息启动新轮次，该轮次的最大轮次计数重新开始。预算总额继续在消息间累积，一旦支出达到 `maxBudgetUsd`，同一对话中的后续消息以 `error_max_budget_usd` 结果结束。[`/clear`](/docs/zh-CN/agent-sdk/cost-tracking) 会重新开始预算。

226 226

227<h3 id="effort-level">227<h3 id="effort-level">

228 努力级别228 努力级别

267 模型267 模型

268</h3>268</h3>

269 269

270如果你不设置 `model`，SDK 使用 Claude Code 的默认值，这取决于你的身份验证方法和订阅。显式设置它（例如，`model="claude-sonnet-5"`）以固定特定模型或使用较小的模型以获得更快、更便宜的代理。有关可用 ID，请参阅 [models](https://platform.claude.com/docs/en/about-claude/models)。270设置 `model` 选项以选择哪个模型运行会话。有关更多信息，请参阅 [选择模型](/docs/zh-CN/agent-sdk/configuration#choose-a-model)。

271 271

272<h2 id="the-context-window">272<h2 id="the-context-window">

273 上下文窗口273 上下文窗口

agent-sdk/claude-code-features.md +1 −1

Details

107 项目说明（CLAUDE.md 和规则）107 项目说明（CLAUDE.md 和规则）

108</h2>108</h2>

109 109

110`CLAUDE.md` 文件和 `.claude/rules/*.md` 文件为您的代理提供关于您的项目的持久上下文：编码约定、构建命令、架构决策和说明。当 `settingSources` 包含 `"project"`（如上面的示例）时，SDK 在会话开始时将这些文件加载到上下文中。然后代理遵循您的项目约定，而无需在每个提示中重复它们。110`CLAUDE.md` 文件和 `.claude/rules/*.md` 文件为您的代理提供关于您的项目的持久上下文：编码约定、构建命令、架构决策和说明。当 `settingSources` 包含 `"project"`（如 [`settingSources` 示例](#control-filesystem-settings-with-settingsources)中所示）时，SDK 在会话开始时将这些文件加载到上下文中。然后代理遵循您的项目约定，而无需在每个提示中重复它们。

111 111

112<h3 id="claude-md-load-locations">112<h3 id="claude-md-load-locations">

113 CLAUDE.md 加载位置113 CLAUDE.md 加载位置

agent-sdk/configuration.md +315 −0 created

Details

1> ## Documentation Index

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

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

5# 配置你的代理

7> 配置 Agent SDK 会话：组合选项对象、设置模型、环境和限制，并找到每个功能选项的页面。

9Agent SDK 会话从设置文件、环境变量和启动时传递的 `options` 对象读取配置。本页面展示如何组合 `options` 对象以及哪些设置文件和环境变量控制配置。

11有关每个选项的类型和默认值，请参阅 [`Options`](/docs/zh-CN/agent-sdk/typescript#options)（TypeScript）和 [`ClaudeAgentOptions`](/docs/zh-CN/agent-sdk/python#claudeagentoptions)（Python）参考。

13<h2 id="pass-options-to-a-session">

14 将选项传递给会话

15</h2>

17每个 `query()` 调用都接受一个选项对象：TypeScript 中的 `Options`，Python 中的 `ClaudeAgentOptions`。每个字段都是可选的，使用无选项启动的会话以 SDK 的默认值运行。下面的示例配置了一个只读会话，用于总结项目的开放 TODO。对中读作 TypeScript / Python，其中拼写不同：

19* **`model`**：选择模型

20* **`allowedTools` / `allowed_tools`**：预先批准只读工具列表

21* **`maxTurns` / `max_turns`**：限制轮次数

22* **`cwd`**：设置工作目录

24<CodeGroup>

25 ```typescript TypeScript theme={null}

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

28 for await (const message of query({

29 prompt: "Summarize the open TODOs in this repo",

30 options: {

31 model: "claude-sonnet-5",

32 allowedTools: ["Read", "Glob", "Grep"],

33 maxTurns: 8,

34 cwd: "/path/to/repo",

35 },

36 })) {

37 if (message.type === "result" && message.subtype === "success" && !message.is_error) {

38 console.log(message.result);

39 }

40 }

41 ```

43 ```python Python theme={null}

44 import asyncio

46 from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

48 async def main():

49 options = ClaudeAgentOptions(

50 model="claude-sonnet-5",

51 allowed_tools=["Read", "Glob", "Grep"],

52 max_turns=8,

53 cwd="/path/to/repo",

54 )

56 async for message in query(

57 prompt="Summarize the open TODOs in this repo",

58 options=options,

59 ):

60 if isinstance(message, ResultMessage) and not message.is_error:

61 print(message.result)

63 asyncio.run(main())

64 ```

65</CodeGroup>

67将 `cwd` 指向你自己的一个项目并运行示例。该项目的开放 TODO 的摘要在结果消息到达时打印。

69`allowedTools`（TypeScript）或 `allowed_tools`（Python）预先批准列出的工具，因此对它们的调用无需停止等待批准即可运行。列表外的工具保持可用。当 Claude 调用未列出的工具时，权限模式决定调用是否运行。有关更多信息，请参阅[允许和拒绝规则](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules)。

71<h2 id="load-settings-files">

72 加载设置文件

73</h2>

75设置文件提供超出选项对象的配置。两个选项控制它们的加载方式：

77* **`settingSources` / `setting_sources`**：控制加载哪些文件系统源：用户、项目和本地。设置文件和 CLAUDE.md 文件通过这些源到达。

78* **`settings`**：加载设置文件路径或任一语言的内联 JSON 字符串，TypeScript 也接受设置对象。无论你传递什么形式，都会覆盖用户、项目和本地文件系统设置；只有托管策略设置排名更高。参考文档在 TypeScript 的[设置优先级](/docs/zh-CN/agent-sdk/typescript#settings-precedence)和 Python 的[设置优先级](/docs/zh-CN/agent-sdk/python#settings-precedence)下记录了完整的优先级顺序。

80传递 `[]` 以禁用用户、项目和本地设置。有关更多信息，请参阅[在 SDK 中使用 Claude Code 功能](/docs/zh-CN/agent-sdk/claude-code-features)。

82<h2 id="choose-a-model">

83 选择模型

84</h2>

86除非 `model` 选项、你的设置或你的环境选择了模型，否则新会话在[Claude Code 的默认模型](/docs/zh-CN/model-config#default-model-setting)上启动。有关这些源的顺序，请参阅[设置你的模型](/docs/zh-CN/model-config#setting-your-model)。设置 `model` 以固定特定模型，或选择较小的模型以获得更快、更便宜的代理。该值采用模型别名或完整模型名称；别名及其解析到的版本列在[模型别名](/docs/zh-CN/model-config#model-aliases)下。

88设置 `fallbackModel`（TypeScript）或 `fallback_model`（Python）以命名备份模型。当主模型过载或不可用时，会话切换到备份。在每个用户轮次开始时重试主模型，因此一旦中断通过，会话就会返回到它。

90在任一语言中，该选项接受单个模型或逗号分隔的备份列表。有关顺序和链上限，请参阅[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)。在 TypeScript 中，等于 `model` 的备用模型在启动时会抛出错误。

92下面的示例显示 TypeScript 中的备用列表和 Python 中的单个备用：

94<CodeGroup>

95 ```typescript TypeScript theme={null}

96 const options = {

97 model: "claude-fable-5",

98 fallbackModel: "claude-opus-5,claude-sonnet-5",

99 };

100 ```

101

102 ```python Python theme={null}

103 options = ClaudeAgentOptions(

104 model="claude-fable-5",

105 fallback_model="claude-opus-5",

106 )

107 ```

108</CodeGroup>

109

110<span id="sampling-parameters" />

111

112<Note>

113 [Messages API](https://platform.claude.com/docs/en/api/messages) 请求参数 `temperature`、`top_p` 和 `max_tokens` 在任一语言的选项对象上都没有字段。改为设置[努力级别](/docs/zh-CN/agent-sdk/agent-loop#effort-level)或[支出上限](#limit-turns-and-spend)，或在需要这些参数时直接调用 Messages API。

114</Note>

115

116<h2 id="set-environment-variables">

117 设置环境变量

118</h2>

119

120`env` 选项为运行你的会话的 Claude Code 进程设置环境变量。你的值是替换继承的环境还是合并到它上面因语言而异：

121

122* **TypeScript**：`env` 替换子进程环境

123* **Python**：SDK 将你的值合并到继承的环境上，你的值覆盖继承的值

124

125在 TypeScript 中，将 `process.env` 展开到 `env` 中以保留继承的变量，如 `PATH`、`HOME` 和 `ANTHROPIC_API_KEY`。当你不设置 `env` 时，子进程在两种语言中都继承你的环境。

126

127该示例通过设置 `ANTHROPIC_BASE_URL` 将 API 流量路由通过网关。

128

129<CodeGroup>

130 ```typescript TypeScript theme={null}

131 const options = {

132 env: { ...process.env, ANTHROPIC_BASE_URL: "https://gateway.example.com" },

133 };

134 ```

135

136 ```python Python theme={null}

137 options = ClaudeAgentOptions(

138 env={"ANTHROPIC_BASE_URL": "https://gateway.example.com"},

139 )

140 ```

141</CodeGroup>

142

143你传递的变量也可以配置 Claude Code 本身。有关 Claude Code 进程读取的变量，请参阅[环境变量](/docs/zh-CN/env-vars)。要以这种方式调整 API 超时和停滞检测，请按照[TypeScript 参考](/docs/zh-CN/agent-sdk/typescript#handle-slow-or-stalled-api-responses)或[Python 参考](/docs/zh-CN/agent-sdk/python#handle-slow-or-stalled-api-responses)中的处理缓慢或停滞的 API 响应部分进行操作。

144

145<h2 id="set-the-working-directory">

146 设置工作目录

147</h2>

148

149设置 `cwd` 以在特定目录中运行会话。当你不设置 `cwd` 时，会话在你的进程的工作目录中运行。两个 SDK 都没有 `cwd` 的设置器。要在不同目录中运行，请使用该 `cwd` 启动另一个会话。

150

151Claude Code 读取工作目录以确定：

152

153* **项目设置和 hooks**：哪个项目的[设置和 hooks 加载](/docs/zh-CN/agent-sdk/claude-code-features)

154* **Skills**：[会话 skills 在哪里被发现](/docs/zh-CN/agent-sdk/skills)

155* **会话存储**：[存储的会话属于哪个项目](/docs/zh-CN/agent-sdk/session-storage)

156

157要让工具访问工作目录外的文件，请使用 `additionalDirectories`（TypeScript）或 `add_dirs`（Python）添加路径。有关该授予的范围，请参阅[其他目录授予文件访问权限，而不是配置](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)。

158

159<h2 id="limit-turns-and-spend">

160 限制轮次和支出

161</h2>

162

163使用 `maxTurns` / `max_turns` 和 `maxBudgetUsd` / `max_budget_usd` 限制轮次和支出。当未设置时，两个上限都关闭。当会话达到上限时，运行以结果消息结束，其子类型命名上限，`error_max_turns` 或 `error_max_budget_usd`。接下来发生的事情因输入模式而异：

164

165* **单次 `query()`**：SDK 产生上限结果，然后抛出，因此将循环包装在 try 块中以继续通过错误

166* **流式输入**：会话在上限结果之后保持活动，最大轮次计数对每个排队的消息重新开始。预算总额在消息中累积，一旦支出达到上限，同一对话中的后续消息以相同的预算结果结束。[`/clear`](/docs/zh-CN/agent-sdk/cost-tracking) 重新开始预算

167

168两个上限对 `0` 的处理方式不同：

169

170* **`maxTurns` / `max_turns`**：`0` 在没有轮次限制的情况下运行会话，与不设置选项相同

171* **`maxBudgetUsd` / `max_budget_usd`**：CLI 在启动时拒绝 `0` 作为无效金额，会话永远不会运行

172

173有关两个上限的更多信息，包括子代理支出，请参阅[轮次和预算](/docs/zh-CN/agent-sdk/agent-loop#turns-and-budget)。

174

175<h2 id="change-configuration-mid-session">

176 在会话中途更改配置

177</h2>

178

179当你使用[流式输入](/docs/zh-CN/agent-sdk/streaming-vs-single-mode)启动会话时，你可以在它运行时切换其模型和权限模式。你调用设置器的位置因语言而异：

180

181* **TypeScript**：`query()` 返回的对象上的方法

182* **Python**：[`ClaudeSDKClient`](/docs/zh-CN/agent-sdk/python#claudesdkclient) 上的方法，因为 `query()` 返回没有控制方法的普通迭代器

183

184两种语言都有相同的设置器：

185

186* **`setModel()` / `set_model()`**：切换模型。不带模型调用它以切换到[Claude Code 的默认模型](/docs/zh-CN/model-config#default-model-setting)，而不是你在选项中传递的 `model`。

187* **`setPermissionMode()` / `set_permission_mode()`**：切换权限模式

188

189TypeScript 还有 `applyFlagSettings()` 和 `updateSettings()`：

190

191* **`applyFlagSettings()`**：在运行时应用设置，如 `await session.applyFlagSettings({ effortLevel: "high" })`。该方法采用设置文件键而不是选项字段，因此检查[`applyFlagSettings()` 参考](/docs/zh-CN/agent-sdk/typescript#applyflagsettings)以了解架构以及哪些键在会话中途生效。

192* **`updateSettings()`**：将允许列表中的一组键写入项目的本地设置文件，如 `await session.updateSettings("localSettings", { outputStyle: "Explanatory" })`。写入的键在会话的下一个请求时生效，并为加载 `local` 设置的后续会话持久化。该方法在[方法表](/docs/zh-CN/agent-sdk/typescript#methods)中的行命名允许列表中的键和版本下限。

193

194下面的示例运行一个两轮会话，在轮次之间更改配置，并打印回答每轮的模型。在 TypeScript 中，提示流保持第二条消息，直到设置器运行，第二轮在新模型上运行。

195

196<CodeGroup>

197 ```typescript TypeScript theme={null}

198 import { query, type SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";

199

200 function userMessage(text: string): SDKUserMessage {

201 return { type: "user", message: { role: "user", content: text }, parent_tool_use_id: null };

202 }

203

204 // Hold the second prompt until the setters have run.

205 let startSecondTurn!: () => void;

206 const secondTurnReady = new Promise<void>((resolve) => {

207 startSecondTurn = resolve;

208 });

209

210 async function* turnPrompts(): AsyncGenerator<SDKUserMessage, void> {

211 yield userMessage("Reply with exactly: ready");

212 await secondTurnReady;

213 yield userMessage("Reply with exactly: done");

214 }

215

216 const session = query({

217 prompt: turnPrompts(),

218 options: {

219 model: "claude-sonnet-5",

220 },

221 });

222

223 let turnModel = "";

224 let completedTurns = 0;

225

226 for await (const message of session) {

227 if (message.type === "assistant") {

228 turnModel = message.message.model;

229 } else if (message.type === "result") {

230 completedTurns += 1;

231 if (completedTurns === 1) {

232 console.log(`First turn model: ${turnModel}`);

233 await session.setModel("claude-opus-5");

234 await session.setPermissionMode("acceptEdits");

235 startSecondTurn();

236 } else {

237 console.log(`Second turn model: ${turnModel}`);

238 break;

239 }

240 }

241 }

242 ```

243

244 ```python Python theme={null}

245 import asyncio

246

247 from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, ClaudeSDKClient

248

249 async def main():

250 options = ClaudeAgentOptions(model="claude-sonnet-5")

251

252 async with ClaudeSDKClient(options=options) as client:

253 await client.query("Reply with exactly: ready")

254 first_model = ""

255 async for message in client.receive_response():

256 if isinstance(message, AssistantMessage):

257 first_model = message.model

258

259 await client.set_model("claude-opus-5")

260 await client.set_permission_mode("acceptEdits")

261

262 await client.query("Reply with exactly: done")

263 second_model = ""

264 async for message in client.receive_response():

265 if isinstance(message, AssistantMessage):

266 second_model = message.model

267

268 print(f"First turn model: {first_model}")

269 print(f"Second turn model: {second_model}")

270

271 asyncio.run(main())

272 ```

273</CodeGroup>

274

275在 Claude API 上，程序打印 `First turn model: claude-sonnet-5`，然后在切换后打印 `Second turn model: claude-opus-5`。

276

277<Note>

278 每个模型都有自己的提示缓存，因此在会话中途切换后，下一个请求以新模型的费率重新计算完整对话而不缓存。有关更多信息，请参阅[切换模型](/docs/zh-CN/prompt-caching#switching-models)。

279</Note>

280

281<h2 id="configure-specific-features">

282 配置特定功能

283</h2>

284

285下表将每个选项映射到它配置的功能。有关本页面未涵盖的选项，请参阅[TypeScript](/docs/zh-CN/agent-sdk/typescript#options) 和 [Python](/docs/zh-CN/agent-sdk/python#claudeagentoptions) 参考。如果你知道你的目标但不知道哪个选项服务于它，请从[选择正确的功能](/docs/zh-CN/agent-sdk/claude-code-features#choose-the-right-feature)开始。

286

287| TypeScript | Python | 控制 | 涵盖在 |

288| ------------------------- | --------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

305| `sandbox` | `sandbox` | 工具执行的沙箱行为 | [TypeScript](/docs/zh-CN/agent-sdk/typescript#sandbox-configuration) 和 [Python](/docs/zh-CN/agent-sdk/python#sandbox-configuration) 参考，部署上下文在[安全部署](/docs/zh-CN/agent-sdk/secure-deployment)中 |

306

307<h2 id="next-steps">

308 后续步骤

309</h2>

310

311要查看配置组合成工作代理：

312

313* **[快速入门](/docs/zh-CN/agent-sdk/quickstart)**：端到端构建和运行第一个代理

314* **[示例](/docs/zh-CN/agent-sdk/examples)**：找到完整的、可运行的项目或与你想要构建的内容匹配的指导 Claude Cookbook 配方

315* **[多租户隔离](/docs/zh-CN/agent-sdk/hosting#multi-tenant-isolation)**：使用 `settingSources` / `setting_sources`、`env` 和 `cwd` 隔离每个租户的设置和内存

agent-sdk/cost-tracking.md +1 −1

Details

78 78

79在 TypeScript 中，SDK 还在每次重置时发出 [`SDKConversationResetMessage`](/docs/zh-CN/agent-sdk/typescript#sdkconversationresetmessage)，因此您可以从流中检测重置。在 Python 中，SDK 同样发出 `ConversationResetMessage`。在 Python SDK v0.2.137 之前，Python 迭代器丢弃了该消息，因此在这些版本上，从应用发送的 `/clear` 轮次中自己计数重置。79在 TypeScript 中，SDK 还在每次重置时发出 [`SDKConversationResetMessage`](/docs/zh-CN/agent-sdk/typescript#sdkconversationresetmessage)，因此您可以从流中检测重置。在 Python 中，SDK 同样发出 `ConversationResetMessage`。在 Python SDK v0.2.137 之前，Python 迭代器丢弃了该消息，因此在这些版本上，从应用发送的 `/clear` 轮次中自己计数重置。

80 80

~~81`maxBudgetUsd`，或 Python 中的 `max_budget_usd`，与相同的运行总计进行比较，因此 `/clear` 也会启动预算重新开始。~~81`maxBudgetUsd`（TypeScript）或 `max_budget_usd`（Python）与相同的运行总计进行比较，因此 `/clear` 也会启动预算重新开始。

82 82

83<h2 id="get-the-total-cost-of-a-query">83<h2 id="get-the-total-cost-of-a-query">

84 获取查询的总成本84 获取查询的总成本

agent-sdk/custom-tools.md +1 −1

Details

138 138

139通过 `mcpServers` 选项将您创建的 MCP 服务器传递给 `query`。`mcpServers` 中的键成为每个工具的完全限定名称中的 `{server_name}` 段：`mcp__{server_name}__{tool_name}`。在 `allowedTools` 中列出该名称，以便工具运行而无需权限提示。139通过 `mcpServers` 选项将您创建的 MCP 服务器传递给 `query`。`mcpServers` 中的键成为每个工具的完全限定名称中的 `{server_name}` 段：`mcp__{server_name}__{tool_name}`。在 `allowedTools` 中列出该名称，以便工具运行而无需权限提示。

140 140

141这些代码片段重用了[上面示例](#weather-tool-example)中的 `weatherServer`，以询问 Claude 特定位置的天气。141这些代码片段重用了[天气工具示例](#weather-tool-example)中的 `weatherServer`，以询问 Claude 特定位置的天气。

142 142

143<CodeGroup>143<CodeGroup>

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

agent-sdk/file-checkpointing.md +1 −1

Details

179 </Step>179 </Step>

180 180

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

182 设置`replay-user-messages`选项后（如上所示），响应流中的每个用户消息都有一个UUID，用作checkpoint。182 设置`replay-user-messages`选项后，响应流中的每个用户消息都有一个UUID，用作checkpoint。

183 183

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

185 185

agent-sdk/hooks.md +5 −2

Details

826 826

827Claude Code 运行每个回调时都有超时限制，您可以在其 `HookMatcher` 上使用 `timeout` 字段（以秒为单位）设置。当您未设置时，Claude Code 使用事件的默认值：大多数事件为 600 秒，`UserPromptSubmit`、`PreModelSwitch` 和 `PostModelSwitch` 为 30 秒，`MessageDisplay` 为 10 秒。Claude Code 在关闭期间运行 `SessionEnd` 回调时使用较短的 [SessionEnd 超时预算](/docs/zh-CN/hooks#sessionend-input)，默认为 1.5 秒。827Claude Code 运行每个回调时都有超时限制，您可以在其 `HookMatcher` 上使用 `timeout` 字段（以秒为单位）设置。当您未设置时，Claude Code 使用事件的默认值：大多数事件为 600 秒，`UserPromptSubmit`、`PreModelSwitch` 和 `PostModelSwitch` 为 30 秒，`MessageDisplay` 为 10 秒。Claude Code 在关闭期间运行 `SessionEnd` 回调时使用较短的 [SessionEnd 超时预算](/docs/zh-CN/hooks#sessionend-input)，默认为 1.5 秒。

828 828

829当回调超过其超时时间时，Claude Code 会取消它并将其视为失败的 hook：它丢弃回调的输出，会话继续而不是挂起。接下来发生的情况取决于事件：829当回调超过其超时时间时，Claude Code 会取消它并丢弃其输出，会话继续而不是挂起。接下来发生的情况取决于事件：

830 830

831* `PreToolUse`: Claude Code 不运行工具调用，Claude 收到一个工具结果，说明 hook 未在超时前响应，转轮继续。如果另一个 `PreToolUse` hook 返回了明确的拒绝，Claude 会收到该拒绝而不是超时错误。在 v2.1.210 之前，Claude Code 将超时报告给 Claude 作为用户拒绝，这使得无人值守会话停止并等待输入。831* `PreToolUse`: Claude Code 不运行工具调用，Claude 收到一个工具结果，说明 hook 未在超时前响应，转轮继续。如果另一个 `PreToolUse` hook 返回了明确的拒绝，Claude 会收到该拒绝而不是超时错误。在 v2.1.210 之前，Claude Code 将超时报告给 Claude 作为用户拒绝，这使得无人值守会话停止并等待输入。

832* `PostToolUse` 和 `PostToolUseFailure`：Claude Code 保留工具结果，转轮继续。832* `PostToolUse` 和 `PostToolUseFailure`：Claude Code 保留工具结果，转轮继续。

833* `UserPromptSubmit` 和 [`UserPromptExpansion`](/docs/zh-CN/hooks#userpromptexpansion)：Claude Code 使用命名 hook 和超时的消息阻止提示，会话继续。因为这些事件上的回调可以充当策略门，Claude Code 永远不会让超时的提示通过未筛选。在 v2.1.208 之前，当这些事件上的回调超时时，Claude Code 以 `error_during_execution` 结束查询。833* `UserPromptSubmit` 和 [`UserPromptExpansion`](/docs/zh-CN/hooks#userpromptexpansion)：Claude Code 使用命名 hook 和超时的消息阻止提示，会话继续。因为这些事件上的回调可以充当策略门，Claude Code 永远不会让超时的提示通过未筛选。在 v2.1.208 之前，当这些事件上的回调超时时，Claude Code 以 `error_during_execution` 结束查询。

834* `Stop` 和 `SubagentStop`：Claude Code 显示警告，代理正常停止。834* `Stop` 和 `SubagentStop`：超时的回调计为不返回任何决定。代理或子代理停止，就像该回调已允许它一样，您在该事件上的其他 hooks 的决定仍然适用。在 Claude Code v2.1.273 之前，超时的 `Stop` 或 `SubagentStop` 回调计为失败的 hook 运行，Claude Code 丢弃了您在该事件上的其他 hooks 的决定。

835* `SessionStart`：超时的回调计为不返回任何输出，会话继续使用您的其他 `SessionStart` hooks 的输出。

835* `PreModelSwitch`：Claude Code 阻止模型切换。未回答的 hook 尚未批准切换。836* `PreModelSwitch`：Claude Code 阻止模型切换。未回答的 hook 尚未批准切换。

836* 其他事件，如 `Notification`、`PreCompact` 和 `PostModelSwitch`：Claude Code 记录失败并继续。837* 其他事件，如 `Notification`、`PreCompact` 和 `PostModelSwitch`：Claude Code 记录失败并继续。

837 838

839主会话中 `Stop` 或 `SessionStart` 回调第一次超时时，Claude Code 还会向消息流添加一个 [`SDKInformationalMessage`](/docs/zh-CN/agent-sdk/typescript#sdkinformationalmessage)，说明驱动会话的应用未响应。当您的应用保持无响应时，后续超时不会重复该消息。

840

838如果您在回调待处理时中断查询，Claude Code 会取消待处理的工具调用。在 v2.1.208 之前，如果您在待处理的 `PreToolUse` 回调期间中断，工具调用仍可能继续。841如果您在回调待处理时中断查询，Claude Code 会取消待处理的工具调用。在 v2.1.208 之前，如果您在待处理的 `PreToolUse` 回调期间中断，工具调用仍可能继续。

839 842

840如果您的回调需要更多时间，请在其 `HookMatcher` 上设置更高的 `timeout`。在 TypeScript 中，使用第三个回调参数中的 `AbortSignal` 来在超时触发时优雅地处理取消。843如果您的回调需要更多时间，请在其 `HookMatcher` 上设置更高的 `timeout`。在 TypeScript 中，使用第三个回调参数中的 `AbortSignal` 来在超时触发时优雅地处理取消。

agent-sdk/hosting.md +3 −3

Details

147 147

148 declare const userInput: string;148 declare const userInput: string;

149 declare const sessionId: string; // looked up from your database by user149 declare const sessionId: string; // looked up from your database by user

150 declare const sessionStore: SessionStore; // S3, Redis, Postgres, or your own adapter150 declare const sessionStore: SessionStore; // an object store, key-value store, database, or your own adapter

151 151

152 for await (const message of query({152 for await (const message of query({

153 prompt: userInput,153 prompt: userInput,

163 163

164 user_input: str = ...164 user_input: str = ...

165 session_id: str = ... # looked up from your database by user165 session_id: str = ... # looked up from your database by user

166 session_store: SessionStore = ... # S3, Redis, Postgres, or your own adapter166 session_store: SessionStore = ... # an object store, key-value store, database, or your own adapter

167 167

168 168

169 async def main():169 async def main():

244 会话和状态持久化244 会话和状态持久化

245</h3>245</h3>

246 246

247默认本地磁盘在重启、缩减或移动到不同节点时会丢失。对于用户期望恢复的任何会话，使用 [`SessionStore` 适配器](/docs/zh-CN/agent-sdk/session-storage)将记录副本镜像到持久存储。查看[参考实现](/docs/zh-CN/agent-sdk/session-storage#reference-implementations)了解 S3、Redis 和 Postgres 适配器，以及用于您自己实现的一致性测试套件。247默认本地磁盘在重启、缩减或移动到不同节点时会丢失。对于用户期望恢复的任何会话，使用 [`SessionStore` 适配器](/docs/zh-CN/agent-sdk/session-storage)将记录副本镜像到持久存储。查看[参考实现](/docs/zh-CN/agent-sdk/session-storage#reference-implementations)了解对象存储、键值存储和数据库的示例适配器，以及用于您自己实现的一致性测试套件。

248 248

249关于 `SessionStore` 行为的三个要点：249关于 `SessionStore` 行为的三个要点：

250 250

agent-sdk/mcp.md +12 −1

Details

156 连接时序156 连接时序

157</h2>157</h2>

158 158

159Claude Code 在启动时注册你在 `options.mcpServers` 中传递的服务器，并在第一轮等待（如果有的话）解决后发出 [init 消息](#error-handling)。如果没有 `options.mcpServers`，Claude Code 会在第一轮之前等待 2 秒以等待待处理的服务器，因此从 [settings 文件](#from-a-config-file)（如 `.mcp.json`）加载的服务器通常在初始化时显示 `pending`。当每个 `options.mcpServers` 服务器连接时，以及它是否延迟第一轮，取决于其类型：159Claude Code 在启动时注册你在 `options.mcpServers` 中传递的服务器，并在第一轮等待（如果有的话）解决后发出 [init 消息](#error-handling)。每个 `options.mcpServers` 服务器是否延迟第一轮，以及何时连接，取决于其类型：

160 160

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 秒：

168

169* **使用 [tool search](/docs/zh-CN/agent-sdk/tool-search)（默认）**：等待涵盖仍待处理的服务器，这些服务器配置了 [`alwaysLoad: true`](/docs/zh-CN/mcp#exempt-a-server-from-deferral)，不包括其余的。其余的继续在后台连接。[Tool availability](/docs/zh-CN/mcp#tool-availability) 描述了 Claude 在它们连接后如何访问它们的工具。

170* **不使用 tool search**：等待涵盖每个待处理的服务器。[Configure tool search](/docs/zh-CN/agent-sdk/tool-search#configure-tool-search) 涵盖了关闭 tool search 的内容。例如，如果你通过 `disallowedTools` 从会话中排除 `ToolSearch` 工具，会话也会在没有 tool search 的情况下运行。

171

172如果你设置了 `permissionPromptToolName`，第一轮也会在所有情况下等待该工具的服务器，最多等待 `MCP_TIMEOUT`。

173

174要自己设置第一轮等待，请将 `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` 添加到 [`env` 选项](/docs/zh-CN/agent-sdk/configuration#set-environment-variables)，例如 `CLAUDE_CODE_MCP_STARTUP_WAIT_MS: "5000"`。第一轮然后等待最多那么多毫秒以等待每个待处理的服务器，无论 tool search 是否可用。此截止时间也替代了 `options.mcpServers` 中 stdio、HTTP 和 SSE 服务器的 `MCP_TIMEOUT` 第一轮等待。`CLAUDE_CODE_MCP_STARTUP_WAIT_MS` 需要 Claude Code v2.1.274 或更高版本。

175

176当等待结束时仍待处理的服务器继续在后台连接。将变量设置为 `0` 以跳过等待。`permissionPromptToolName` 服务器无论该值如何都保持其自己的 `MCP_TIMEOUT` 等待。

177

167要在发送 init 消息之前的单独的、更早的阶段阻止启动本身：178要在发送 init 消息之前的单独的、更早的阶段阻止启动本身：

168 179

169* 将 [`MCP_CONNECTION_NONBLOCKING`](/docs/zh-CN/env-vars) 设置为 `0` 以阻止整个连接批次。Claude Code 默认将该等待上限设为 5 秒。使用 [`MCP_CONNECT_TIMEOUT_MS`](/docs/zh-CN/env-vars) 环境变量调整上限，单位为毫秒。在该截止时间仍待处理的服务器继续在后台连接。180* 将 [`MCP_CONNECTION_NONBLOCKING`](/docs/zh-CN/env-vars) 设置为 `0` 以阻止整个连接批次。Claude Code 默认将该等待上限设为 5 秒。使用 [`MCP_CONNECT_TIMEOUT_MS`](/docs/zh-CN/env-vars) 环境变量调整上限，单位为毫秒。在该截止时间仍待处理的服务器继续在后台连接。

agent-sdk/modifying-system-prompts.md +22 −5

Details

152 152

153创建后，通过以下方式激活输出样式：153创建后，通过以下方式激活输出样式：

154 154

155* **CLI**：运行 `/config` 并选择输出样式155* **CLI**：运行 `/output-style <style>`，例如 `/output-style concise`，或运行 `/config` 并选择一个。`/output-style` 命令需要 Claude Code v2.1.269 或更高版本。

156* **设置**：在 `.claude/settings.local.json` 中设置 `outputStyle`156* **设置**：在 `.claude/settings.local.json` 中设置 `outputStyle`

157* **TypeScript SDK**：在传递给 `query()` 的内联 `settings` 对象内设置 `outputStyle`，或将 `settings` 指向设置它的设置文件。`outputStyle` 不是顶级 `Options` 字段：157* **TypeScript SDK**：在传递给 `query()` 的内联 `settings` 对象内设置 `outputStyle`，或将 `settings` 指向设置它的设置文件。`outputStyle` 不是顶级 `Options` 字段：

158 158

352 缓存自定义提示词的静态部分352 缓存自定义提示词的静态部分

353</h4>353</h4>

354 354

355在 TypeScript SDK 中，你可以将自定义提示词作为字符串数组而不是一个字符串传递，在静态部分和其余部分之间使用 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 标记。当你的提示词结合每个请求都相同的指令与每个请求都改变的上下文（例如 agent 处理的客户或工单）时，使用此方法。当你将两个部分作为一个字符串传递时，对每个请求部分的更改会改变整个系统提示词，因此静态指令也会错过缓存。此形式在 Python SDK 中不可用，其 `system_prompt` 选项接受字符串、预设或 [file](/docs/zh-CN/agent-sdk/python#systempromptfile)。355在 TypeScript SDK 中，你可以将自定义提示词作为字符串数组而不是一个字符串传递，在静态部分和其余部分之间使用 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 标记。当你的提示词结合每个请求都相同的指令与每个请求都改变的上下文（例如 agent 处理的客户或工单）时，使用此方法。当你将两个部分作为一个字符串传递时，对每个请求部分的更改会改变整个系统提示词，因此静态指令也会错过缓存。此形式在 Python SDK 中不可用；[`ClaudeAgentOptions`](/docs/zh-CN/agent-sdk/python#claudeagentoptions) 列出了 `system_prompt` 接受的形式。

356 356

357<Note>357<Note>

358 SDK 仅在直接调用 Claude API 或在 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 上运行时拆分提示词。在所有其他配置中，例如 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 [LLM gateway](/docs/zh-CN/llm-gateway-connect)，以及每当你设置 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities) 时，SDK 会将整个提示词作为一个块发送，与传递一个字符串相同。358 SDK 仅在直接调用 Claude API 或在 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 上运行时拆分提示词。在所有其他配置中，例如 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 [LLM gateway](/docs/zh-CN/llm-gateway-connect)，以及每当你设置 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities) 时，SDK 会将整个提示词作为一个块发送，与传递一个字符串相同。

391 改变现有会话的提示词391 改变现有会话的提示词

392</h3>392</h3>

393 393

394默认情况下，Claude Code 在会话的第一个请求时构建系统提示词一次，包括你的 `append` 文本或自定义提示词，并将其记录在会话中。在会话被压缩之前，每个后续请求都使用该记录的提示词，包括在你使用 `resume` 或 `continue` 返回会话后。如果你在该后续调用上传递不同的 `append` 或自定义提示词，它会在会话被压缩或在新会话中生效。394默认情况下，如果你在使用 `resume` 或 `continue` 返回会话时传递不同的 `append` 或自定义提示词，Claude 在下一个转折点不会看到它。Claude Code 在会话的第一个请求时记录系统提示词，并在会话被压缩之前重复使用该记录。新文本在压缩后或在新会话中生效。

395 395

396如果你通过 `extraArgs` 传递 `--bare` 或设置 `CLAUDE_CODE_SIMPLE=1` 在 [bare mode](/docs/zh-CN/headless#start-faster-with-bare-mode) 中启动 Claude Code，记录保持关闭，除非你在 `systemPrompt` 的对象形式上设置 `snapshot: true`。默认情况下记录 `append` 或自定义提示词需要 Claude Code v2.1.265 或更高版本，TypeScript Agent SDK 从 v0.3.265 捆绑。在 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` 无效。396<h4 id="update-claude’s-instructions-mid-session">

397 在会话中期更新 Claude 的指令

398</h4>

399

400如果你在系统提示词中放置的指令需要在会话运行时改变，例如因为你的用户将 agent 切换到只读模式或在你的应用中编辑其配置，请在对话中发送新指令，而不是改变 `systemPrompt`：

401

402* **在你的下一条消息中**：在你发送的下一条用户消息中包含新指令。

403* **从 hook 中**：从 `UserPromptSubmit` 或 `PostToolUse` [hook 回调](/docs/zh-CN/agent-sdk/hooks#outputs) 返回 [`additionalContext`](/docs/zh-CN/hooks#add-context-for-claude)，写成事实陈述，例如"工作区现在是只读的"。SDK 在 hook 触发的点将文本插入到对话中，因此记录的提示词保持不变。

404

405<h4 id="turn-recording-off-while-you-iterate-on-wording">

406 在迭代措辞时关闭记录

407</h4>

408

409当你迭代提示词措辞并希望每次编辑都到达你恢复的会话时，在系统提示词的对象形式上设置 `snapshot` 为 false。Claude Code 然后在每个请求上重建提示词。该字段在 TypeScript 中的 [`systemPrompt`](/docs/zh-CN/agent-sdk/typescript#options) 的预设和自定义形式上可用，在 Python 中的 [`system_prompt`](/docs/zh-CN/agent-sdk/python#systempromptpreset) 上可用，并需要 `@anthropic-ai/claude-agent-sdk` v0.3.257 或更高版本，或 `claude-agent-sdk` v0.2.153 或更高版本。

410

411在生产中保持记录打开。关闭记录时，恢复的会话上的不同 `append` 或自定义提示词在下一个转折点到达 Claude，该请求无法重复使用会话的 [prompt cache](/docs/zh-CN/prompt-caching#how-the-cache-is-organized)。在 API 强制执行 [preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking) 的地方，Claude 也会失去其早期转折点的思考。

412

413在 [cloud sessions](/docs/zh-CN/cloud-environments) 之外，如果你通过 `extraArgs` 传递 `--bare` 或设置 `CLAUDE_CODE_SIMPLE=1` 在 [bare mode](/docs/zh-CN/headless#start-faster-with-bare-mode) 中启动 Claude Code，记录保持关闭，除非你设置 `snapshot: true`。

397 414

398要改为在每个请求上重建提示词，请在 TypeScript SDK 中的 `systemPrompt` 的对象形式上设置 `snapshot: false`：`{ type: "preset", preset: "claude_code", append, snapshot: false }` 或 `{ type: "custom", prompt, snapshot: false }`。当你在迭代提示词措辞时或当你的应用程序在恢复相同会话的调用之间改变 `append` 时，使用此形式。`snapshot` 字段需要 `@anthropic-ai/claude-agent-sdk` v0.3.257 或更高版本。415默认情况下记录 `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` 无效。

399 416

400<h2 id="compare-the-four-approaches">417<h2 id="compare-the-four-approaches">

401 比较四种方法418 比较四种方法

agent-sdk/observability.md +1 −1

Details

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

250| `OTEL_LOG_TOOL_CONTENT=1` | `claude_code.tool` 上的完整工具输入和输出体作为跨度事件，默认在 60 KB 处截断，可通过 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 配置，需要 Claude Code v2.1.214 或更高版本。需要启用[跟踪](#read-agent-traces) |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)下携带工具内容 |

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/overview.md +1 −1

Details

78 78

79* "Claude Agent"，首选用于下拉菜单79* "Claude Agent"，首选用于下拉菜单

80* "Claude"，当已在标记为"Agents"的菜单中时80* "Claude"，当已在标记为"Agents"的菜单中时

~~81* "{YourAgentName} Powered by Claude"，如果您有现有的代理名称~~81* "\{YourAgentName} Powered by Claude"，如果您有现有的代理名称

82 82

83**不允许：**83**不允许：**

84 84

agent-sdk/permissions.md +2 −0

Details

301 301

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

303 303

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

305

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

305 307

306**使用场景：** 您希望 Claude 提议更改而不执行它们，例如在代码审查期间或当您需要在进行更改之前批准更改时。308**使用场景：** 您希望 Claude 提议更改而不执行它们，例如在代码审查期间或当您需要在进行更改之前批准更改时。

agent-sdk/python.md +34 −13

Details

119</h4>119</h4>

120 120

121| 参数 | 类型 | 描述 |121| 参数 | 类型 | 描述 |

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

541| `rewind_files(user_message_id)` | 将文件恢复到指定用户消息时的状态。需要 `enable_file_checkpointing=True`。见 [文件检查点](/docs/zh-CN/agent-sdk/file-checkpointing) |541| `rewind_files(user_message_id)` | 将文件恢复到指定用户消息时的状态。需要 `enable_file_checkpointing=True`。见 [文件检查点](/docs/zh-CN/agent-sdk/file-checkpointing) |

845class ClaudeAgentOptions:845class ClaudeAgentOptions:

846 tools: list[str] | ToolsPreset | None = None846 tools: list[str] | ToolsPreset | None = None

847 allowed_tools: list[str] = field(default_factory=list)847 allowed_tools: list[str] = field(default_factory=list)

849 mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)849 mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)

850 strict_mcp_config: bool = False850 strict_mcp_config: bool = False

851 permission_mode: PermissionMode | None = None851 permission_mode: PermissionMode | None = None

894```894```

895 895

896| 属性 | 类型 | 默认值 | 描述 |896| 属性 | 类型 | 默认值 | 描述 |

897| :---------------------------- | :--------------------------------------------------------------------------------------- | :------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |897| :---------------------------- | :--------------------------------------------------------------------------------------- | :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

898| `tools` | `list[str] \| ToolsPreset \| None` | `None` | 工具配置。使用 `{"type": "preset", "preset": "claude_code"}` 获取 Claude Code 的默认工具 |898| `tools` | `list[str] \| ToolsPreset \| None` | `None` | 工具配置。使用 `{"type": "preset", "preset": "claude_code"}` 获取 Claude Code 的默认工具 |

899| `allowed_tools` | `list[str]` | `[]` | 无需提示即可自动批准的工具。这不会限制 Claude 仅使用这些工具。如果你在此处命名[任务跟踪工具](/docs/zh-CN/agent-sdk/todo-tracking#model-availability)之一，Claude Code 也会选择该会话。其他未列出的工具会通过 `permission_mode` 和 `can_use_tool` 处理。使用 `disallowed_tools` 阻止工具。见 [权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |899| `allowed_tools` | `list[str]` | `[]` | 无需提示即可自动批准的工具。这不会限制 Claude 仅使用这些工具。如果你在此处命名[任务跟踪工具](/docs/zh-CN/agent-sdk/todo-tracking#model-availability)之一，Claude Code 也会选择该会话。其他未列出的工具会通过 `permission_mode` 和 `can_use_tool` 处理。使用 `disallowed_tools` 阻止工具。见 [权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |

900| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptFile \| None` | `None` | 系统提示配置。传递字符串以获取自定义提示，`{"type": "preset", "preset": "claude_code"}` 获取 Claude Code 的系统提示（带可选 `"append"`），或 `{"type": "file", "path": "..."}` 从磁盘加载大型提示。见 [`SystemPromptPreset`](#systempromptpreset) 和 [`SystemPromptFile`](#systempromptfile) |900| `system_prompt` | `str \| SystemPromptPreset \| SystemPromptCustom \| SystemPromptFile \| None` | `None` | 系统提示配置。传递字符串以获取自定义提示，`{"type": "preset", "preset": "claude_code"}` 获取 Claude Code 的系统提示（带可选 `"append"`），`{"type": "custom", "prompt": "..."}` 获取也可以设置 `"snapshot"` 的自定义提示，或 `{"type": "file", "path": "..."}` 从磁盘加载大型提示。见 [`SystemPromptPreset`](#systempromptpreset)、[`SystemPromptCustom`](#systempromptcustom) 和 [`SystemPromptFile`](#systempromptfile) |

901| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 服务器配置或配置文件路径 |901| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP 服务器配置或配置文件路径 |

902| `strict_mcp_config` | `bool` | `False` | 当为 `True` 时，仅使用在 `mcp_servers` 中传递的服务器，忽略项目 `.mcp.json`、用户设置、插件提供的 MCP 服务器和 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)。映射到 CLI `--strict-mcp-config` 标志 |902| `strict_mcp_config` | `bool` | `False` | 当为 `True` 时，仅使用在 `mcp_servers` 中传递的服务器，忽略项目 `.mcp.json`、用户设置、插件提供的 MCP 服务器和 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)。映射到 CLI `--strict-mcp-config` 标志 |

909| `disallowed_tools` | `list[str]` | `[]` | 要拒绝的工具。裸名称如 `"Bash"` 从 Claude 的上下文中移除工具。作用域规则如 `"Bash(rm *)"` 保持工具可用，并在每个权限模式（包括 `bypassPermissions`）中拒绝匹配的调用，对于[按照书写方式](/docs/zh-CN/permissions#bash-rule-limits)的命令。见 [权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |909| `disallowed_tools` | `list[str]` | `[]` | 要拒绝的工具。裸名称如 `"Bash"` 从 Claude 的上下文中移除工具。作用域规则如 `"Bash(rm *)"` 保持工具可用，并在每个权限模式（包括 `bypassPermissions`）中拒绝匹配的调用，对于[按照书写方式](/docs/zh-CN/permissions#bash-rule-limits)的命令。见 [权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |

914| `output_format` | `dict[str, Any] \| None` | `None` | 结构化响应的输出格式（例如 `{"type": "json_schema", "schema": {...}}`）。见 [结构化输出](/docs/zh-CN/agent-sdk/structured-outputs) 了解详情 |914| `output_format` | `dict[str, Any] \| None` | `None` | 结构化响应的输出格式（例如 `{"type": "json_schema", "schema": {...}}`）。见 [结构化输出](/docs/zh-CN/agent-sdk/structured-outputs) 了解详情 |

916| `cwd` | `str \| Path \| None` | `None` | 当前工作目录 |916| `cwd` | `str \| Path \| None` | `None` | 当前工作目录 |

920| `env` | `dict[str, str]` | `{}` | 环境变量合并到继承的进程环境之上。见 [环境变量](/docs/zh-CN/env-vars) 了解底层 CLI 读取的变量，以及 [处理缓慢或停滞的 API 响应](#handle-slow-or-stalled-api-responses) 了解超时相关变量 |920| `env` | `dict[str, str]` | `{}` | 环境变量合并到继承的进程环境之上。见 [环境变量](/docs/zh-CN/env-vars) 了解底层 CLI 读取的变量，以及 [处理缓慢或停滞的 API 响应](#handle-slow-or-stalled-api-responses) 了解超时相关变量 |

921| `extra_args` | `dict[str, str \| None]` | `{}` | 直接传递给 CLI 的其他 CLI 参数 |921| `extra_args` | `dict[str, str \| None]` | `{}` | 直接传递给 CLI 的其他 CLI 参数 |

937| `setting_sources` | `list[SettingSource] \| None` | `None`（CLI 默认值：所有源） | 控制加载哪些文件系统设置。传递 `[]` 以禁用用户、项目和本地设置。无论如何都会加载托管策略设置；当会话使用组织凭证在[符合条件的配置](/docs/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器管理的设置。见 [使用 Claude Code 功能](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) 了解无论此选项如何都会读取的输入，以及如何禁用它们 |937| `setting_sources` | `list[SettingSource] \| None` | `None`（CLI 默认值：所有源） | 控制加载哪些文件系统设置。传递 `[]` 以禁用用户、项目和本地设置。无论如何都会加载托管策略设置；当会话使用组织凭证在[符合条件的配置](/docs/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器管理的设置。有关无论此选项如何都会读取的输入，见 [settingSources 不控制什么](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

938| `skills` | `list[str] \| Literal["all"] \| None` | `None` | 会话可用的技能。传递 `"all"` 以启用每个发现的技能，或传递技能名称列表。仅传递精确名称。SDK 在启动 Claude Code 进程之前会以 `ValueError` 拒绝格式错误和通配符形式的名称；此检查需要 Python Agent SDK 0.2.129 或更高版本。设置时，SDK 会自动将 Skill 工具添加到 `allowed_tools`。如果你也传递 `tools`，在该列表中包含 `"Skill"`。见 [Skills](/docs/zh-CN/agent-sdk/skills) |938| `skills` | `list[str] \| Literal["all"] \| None` | `None` | 会话可用的技能。传递 `"all"` 以启用每个发现的技能，或传递技能名称列表。仅传递精确名称。SDK 在启动 Claude Code 进程之前会以 `ValueError` 拒绝格式错误和通配符形式的名称；此检查需要 Python Agent SDK 0.2.129 或更高版本。设置时，SDK 会自动将 Skill 工具添加到 `allowed_tools`。如果你也传递 `tools`，在该列表中包含 `"Skill"`。见 [Skills](/docs/zh-CN/agent-sdk/skills) |

1002 preset: Literal["claude_code"]1002 preset: Literal["claude_code"]

1003 append: NotRequired[str]1003 append: NotRequired[str]

1004 exclude_dynamic_sections: NotRequired[bool]1004 exclude_dynamic_sections: NotRequired[bool]

1005 snapshot: NotRequired[bool]

1005```1006```

1006 1007

1007| 字段 | 必需 | 描述 |1008| 字段 | 必需 | 描述 |

1008| :------------------------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1009| :------------------------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

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

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

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

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

1015

1016<h3 id="systempromptcustom">

1017 `SystemPromptCustom`

1018</h3>

1019

1020对象形式的自定义系统提示，等同于将字符串作为 `system_prompt` 传递，也可以设置 `snapshot`。需要 `claude-agent-sdk` v0.2.153 或更高版本。

1021

1022```python theme={null}

1023class SystemPromptCustom(TypedDict):

1024 type: Literal["custom"]

1025 prompt: str

1026 snapshot: NotRequired[bool]

1027```

1028

1029| 字段 | 必需 | 描述 |

1030| :--------- | :- | :--------------------------------------------------------------------- |

1031| `type` | 是 | 必须是 `"custom"` |

1032| `prompt` | 是 | 系统提示文本。作为命令行参数传递给 CLI，因此[命令行长度限制](#systempromptfile)适用 |

1033| `snapshot` | 否 | 与 [`SystemPromptPreset.snapshot`](#systempromptpreset) 相同，应用于 `prompt` |

1013 1034

1014<h3 id="systempromptfile">1035<h3 id="systempromptfile">

1015 `SystemPromptFile`1036 `SystemPromptFile`

1048 默认行为1069 默认行为

1049</h4>1070</h4>

1050 1071

1051当 `setting_sources` 被省略或为 `None` 时，`query()` 加载与 Claude Code CLI 相同的文件系统设置：用户、项目和本地。无论如何都会加载托管策略设置；当会话使用组织凭证在[符合条件的配置](/docs/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器管理的设置。见 [settingSources 不控制什么](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) 了解无论此选项如何都会读取的输入，以及如何禁用它们。1072当 `setting_sources` 被省略或为 `None` 且 `skills` 未设置时，`query()` 加载与 Claude Code CLI 相同的文件系统设置：用户、项目和本地。使用 `skills` 设置时，[`setting_sources`](#claudeagentoptions) 行描述当前默认值。无论如何都会加载托管策略设置；当会话使用组织凭证在[符合条件的配置](/docs/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器管理的设置。有关更多信息，见 [settingSources 不控制什么](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control)。

1052 1073

1053<h4 id="why-use-setting_sources">1074<h4 id="why-use-setting_sources">

1054 为什么使用 setting\_sources1075 为什么使用 setting\_sources

11412. 项目设置（`.claude/settings.json`）11622. 项目设置（`.claude/settings.json`）

11423. 用户设置（`~/.claude/settings.json`）11633. 用户设置（`~/.claude/settings.json`）

1143 1164

1144编程选项（如 `agents` 和 `allowed_tools`）覆盖用户、项目和本地文件系统设置。托管策略设置优先于编程选项。1165编程选项（如 `agents`、`allowed_tools` 和 `settings`）覆盖用户、项目和本地文件系统设置。托管策略设置优先于编程选项。

1145 1166

1146<h3 id="agentdefinition">1167<h3 id="agentdefinition">

1147 `AgentDefinition`1168 `AgentDefinition`

agent-sdk/quickstart.md +4 −1

Details

62 </Tab>62 </Tab>

63 63

64 <Tab title="Python（uv）">64 <Tab title="Python（uv）">

~~65 [uv](https://docs.astral.sh/uv/) 是一个快速的 Python 包管理器，可以自动处理虚拟环境：~~65 [安装 uv](https://docs.astral.sh/uv/)，一个快速的 Python 包管理器，可以自动处理虚拟环境。然后初始化一个项目并添加 SDK：

66 66

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

68 uv init68 uv init

356 356

357启用 `Bash` 后，尝试：`"Write unit tests for utils.py, run them, and fix any failures"`357启用 `Bash` 后，尝试：`"Write unit tests for utils.py, run them, and fix any failures"`

358 358

359这些代码片段中的每一个都在同一个选项对象上设置字段。有关更多信息，请参阅[配置你的代理](/docs/zh-CN/agent-sdk/configuration)。

360

359<h2 id="key-concepts">361<h2 id="key-concepts">

360 关键概念362 关键概念

361</h2>363</h2>

376 378

377现在你已经创建了你的第一个代理，学习如何扩展其功能并将其定制到你的用例：379现在你已经创建了你的第一个代理，学习如何扩展其功能并将其定制到你的用例：

378 380

381* **[配置你的代理](/docs/zh-CN/agent-sdk/configuration)**：组合选项对象并找到涵盖每个设置的页面

379* **[权限](/docs/zh-CN/agent-sdk/permissions)**：控制你的代理可以做什么以及何时需要批准382* **[权限](/docs/zh-CN/agent-sdk/permissions)**：控制你的代理可以做什么以及何时需要批准

380* **[Hooks](/docs/zh-CN/agent-sdk/hooks)**：在工具调用之前或之后运行自定义代码383* **[Hooks](/docs/zh-CN/agent-sdk/hooks)**：在工具调用之前或之后运行自定义代码

381* **[会话](/docs/zh-CN/agent-sdk/sessions)**：构建维护上下文的多轮代理384* **[会话](/docs/zh-CN/agent-sdk/sessions)**：构建维护上下文的多轮代理

agent-sdk/session-storage.md +12 −12

Details

4 4

5# 将会话持久化到外部存储5# 将会话持久化到外部存储

6 6

~~7> 将会话记录镜像到 S3、Redis 或您自己的后端，以便其他主机可以恢复您的会话。~~7> 将 Agent SDK 会话记录镜像到您自己的对象存储、键值存储或数据库，以便其他主机可以恢复您的会话。

8 8

9默认情况下，SDK 将会话记录写入本地文件系统上 `~/.claude/projects/` 下的 JSONL 文件。`SessionStore` 适配器让您可以将这些记录镜像到您自己的后端，例如 S3、Redis 或数据库，这样在一个主机上创建的会话可以在另一个主机上恢复，只要工作目录相同。9默认情况下，SDK 将会话记录写入本地文件系统上 `~/.claude/projects/` 下的 JSONL 文件。`SessionStore` 适配器让您可以将这些记录镜像到您自己的后端，例如对象存储、键值存储或数据库，这样在一个主机上创建的会话可以在另一个主机上恢复，只要工作目录相同。

10 10

11使用会话存储的常见原因：11使用会话存储的常见原因：

12 12

13* **多主机部署。** 无服务器函数、自动扩展的工作进程和 CI 运行器不共享文件系统。共享存储让副本可以恢复彼此的会话。13* **多主机部署。** 无服务器函数、自动扩展的工作进程和 CI 运行器不共享文件系统。共享存储让副本可以恢复彼此的会话。

~~14* **持久性。** 本地容器是临时的。由 S3 或数据库支持的存储可以在重启和重新部署后继续存在。~~14* **持久性。** 本地容器是临时的。外部存储可以在重启和重新部署后继续存在。

15* **合规性和审计。** 将记录保存在您已经管理的存储中，使用您自己的保留规则、加密和访问控制。15* **合规性和审计。** 将记录保存在您已经管理的存储中，使用您自己的保留规则、加密和访问控制。

16 16

17<h2 id="the-sessionstore-interface">17<h2 id="the-sessionstore-interface">

197 197

198针对您的后端实现 `append` 和 `load`。如果您希望 `listSessions()`、一次调用元数据读取、`deleteSession()` 和子代理恢复针对存储工作，请添加 `listSessions`、`listSessionSummaries`、`delete` 和 `listSubkeys`。198针对您的后端实现 `append` 和 `load`。如果您希望 `listSessions()`、一次调用元数据读取、`deleteSession()` 和子代理恢复针对存储工作，请添加 `listSessions`、`listSessionSummaries`、`delete` 和 `listSubkeys`。

199 199

200传递给 `append` 的条目类型为 `SessionStoreEntry`（一个 `{ type: string; ... }` 对象）。将它们视为不透明的 JSON 安全值：按顺序持久化它们，并从 `load` 以相同的顺序返回它们。`load` 必须返回与追加的条目深度相等的条目；不需要字节相等的序列化，因此像 Postgres `jsonb` 这样重新排序对象键的后端是可以的。200传递给 `append` 的条目类型为 `SessionStoreEntry`（一个 `{ type: string; ... }` 对象）。将它们视为不透明的 JSON 安全值：按顺序持久化它们，并从 `load` 以相同的顺序返回它们。`load` 必须返回与追加的条目深度相等的条目；不需要字节相等的序列化，因此像重新排序对象键的二进制 JSON 列类型这样的后端是可以的。

201 201

202<h2 id="reference-implementations">202<h2 id="reference-implementations">

203 参考实现203 参考实现

204</h2>204</h2>

205 205

206TypeScript SDK 存储库在 [`examples/session-stores/`](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores) 下包含 S3、Redis 和 Postgres 的可运行参考适配器。它们未发布到 npm；将您需要的 `src/` 文件复制到您的项目中并安装相应的后端客户端。206两个 SDK 存储库在 TypeScript 的 [`examples/session-stores/`](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores) 和 Python 的 [`examples/session_stores/`](https://github.com/anthropics/claude-agent-sdk-python/tree/main/examples/session_stores) 下都包含可运行的参考适配器。每种存储类型都有一个适配器，每个都展示了 `append` 和 `load` 如何映射到该类型的后端。它们不作为包发布；将最接近您后端的类型的适配器复制到您的项目中，安装您后端的客户端，并进行调整。

207 207

208| 适配器 | 后端客户端 | 存储模型 |208| 存储类型 | 存储模型 | 示例适配器 |

209| :----------------------------------------------------------------------------------------------------------------------------- | :------------------- | :--------------------------------------------- |209| :--------- | :--------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

210| [`S3SessionStore`](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores/s3) | `@aws-sdk/client-s3` | 每个 `append()` 一个 JSONL 部分文件；`load()` 列出、排序和连接。 |210| 对象存储 | 每个 `append()` 一个部分文件；`load()` 列出部分、排序并连接。 | S3 ([TypeScript](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores/s3), [Python](https://github.com/anthropics/claude-agent-sdk-python/blob/main/examples/session_stores/s3_session_store.py)) |

211| [`RedisSessionStore`](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores/redis) | `ioredis` | 每个记录的 `RPUSH`/`LRANGE` 列表，加上排序集会话索引。 |211| 键值存储 | 每个记录一个列表，`append()` 推送到该列表，`load()` 按范围读取，加上会话的排序索引。 | Redis ([TypeScript](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores/redis), [Python](https://github.com/anthropics/claude-agent-sdk-python/blob/main/examples/session_stores/redis_session_store.py)) |

212| [`PostgresSessionStore`](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores/postgres) | `pg` | `jsonb` 表中每个条目一行，按 `BIGSERIAL` 排序。 |212| 关系数据库或文档存储 | 每个条目一行或一个文档，存储为 JSON 并按插入时分配的键排序。 | Postgres ([TypeScript](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores/postgres), [Python](https://github.com/anthropics/claude-agent-sdk-python/blob/main/examples/session_stores/postgres_session_store.py)) |

213 213

214每个适配器都采用预配置的客户端实例，因此您可以控制凭证、TLS、区域和池。例如，使用 S3：214每个适配器都采用预配置的客户端实例，因此您可以控制凭证、TLS、区域和池。以下示例将对象存储适配器连接到 `query()` 中，然后在另一台主机上从中恢复：

215 215

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

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

371* [使用会话](/docs/zh-CN/agent-sdk/sessions)：在没有自定义存储的情况下继续、恢复和分叉371* [使用会话](/docs/zh-CN/agent-sdk/sessions)：在没有自定义存储的情况下继续、恢复和分叉

372* [托管 SDK](/docs/zh-CN/agent-sdk/hosting)：多主机环境的部署模式372* [托管 SDK](/docs/zh-CN/agent-sdk/hosting)：多主机环境的部署模式

373* [TypeScript `Options`](/docs/zh-CN/agent-sdk/typescript#options)：完整的选项参考373* [TypeScript `Options`](/docs/zh-CN/agent-sdk/typescript#options)：完整的选项参考

374* [`examples/session-stores/`](https://github.com/anthropics/claude-agent-sdk-typescript/tree/main/examples/session-stores)：可运行的 S3、Redis 和 Postgres 参考适配器374* [参考实现](#reference-implementations)：对象存储、键值存储和数据库的可运行示例适配器，在两个 SDK 存储库中

agent-sdk/skills.md +5 −1

Details

130* **你的 skills**：你编写的提示工件，每个都是一个包含 `SKILL.md` 文件的目录。用户可调用 skill 的名称自动加入表面，因此分派你自己的 `/security-check` 和运行内置的工作方式相同130* **你的 skills**：你编写的提示工件，每个都是一个包含 `SKILL.md` 文件的目录。用户可调用 skill 的名称自动加入表面，因此分派你自己的 `/security-check` 和运行内置的工作方式相同

131* **自定义命令文件**：一种较旧的工件形式，具有相同的行为，`.claude/commands/` 中的平面 Markdown 文件，其文件名成为命令名称。Skills 是它们推荐的后继者131* **自定义命令文件**：一种较旧的工件形式，具有相同的行为，`.claude/commands/` 中的平面 Markdown 文件，其文件名成为命令名称。Skills 是它们推荐的后继者

132 132

133默认情况下，你和 Claude 都可以调用任何 skill。你可以通过 skill 的 [frontmatter](/docs/zh-CN/skills#control-who-invokes-a-skill) 限制任一路径。有关这两个术语的定义，请参阅词汇表的 [Command](/docs/zh-CN/glossary#command) 和 [Skill](/docs/zh-CN/glossary#skill) 条目。请参阅 [Claude Code 中的命令](/docs/zh-CN/commands) 了解每个内置命令，以及 [使用 skills 扩展 Claude](/docs/zh-CN/skills) 了解两种工件形式的完整指南。133默认情况下，你和 Claude 都可以调用任何 skill。你可以通过 skill 的 [frontmatter](/docs/zh-CN/skills#control-who-invokes-a-skill) 限制任一路径。有关命令和 skill 的定义，请参阅词汇表的 [Command](/docs/zh-CN/glossary#command) 和 [Skill](/docs/zh-CN/glossary#skill) 条目。请参阅 [Claude Code 中的命令](/docs/zh-CN/commands) 了解每个内置命令，以及 [使用 skills 扩展 Claude](/docs/zh-CN/skills) 了解两种工件形式的完整指南。

134 134

135<h3 id="discover-available-commands">135<h3 id="discover-available-commands">

136 发现可用命令136 发现可用命令

181 181

182通过在提示字符串中包含命令来发送命令，就像发送常规文本一样。分派不依赖于 `skills` 选项。发送 `/<name>` 会运行用户可调用的 skill，即使你的 `skills` 列表省略了它。作用于对话历史的命令，例如 `/compact`，需要先前的消息才能工作。182通过在提示字符串中包含命令来发送命令，就像发送常规文本一样。分派不依赖于 `skills` 选项。发送 `/<name>` 会运行用户可调用的 skill，即使你的 `skills` 列表省略了它。作用于对话历史的命令，例如 `/compact`，需要先前的消息才能工作。

183 183

184一个 `/<name>` 既不匹配会话中的命令也不匹配内置 Claude Code 命令不会导致查询失败。Claude Code 将提示作为普通消息发送给 Claude，并附注该命令未运行，因此查询花费一个模型轮次并返回 Claude 的回复。在 v2.1.274 之前，匹配不到任何内容的 `/<name>` 返回 `Unknown command: /<name>` 作为结果，不花费模型轮次。

185

186一个 `/<name>` 匹配在会话中不可用的内置 Claude Code 命令，例如 `/theme`，返回 `/theme isn't available in this environment.` 作为结果，不花费模型轮次。

187

184<Note>188<Note>

185 命令可以像任何其他提示一样触及 `maxTurns` / `max_turns` 限制，以错误结果而不是 `success` 结束查询。有关错误结果合约，请参阅 [处理结果](/docs/zh-CN/agent-sdk/agent-loop#handle-the-result)。如果你的命令可能触及限制，请在 TypeScript 中用 `try`/`catch` 或在 Python 中用 `try`/`except` 包装循环，如 [单消息输入](/docs/zh-CN/agent-sdk/streaming-vs-single-mode#single-message-input) 中所示，或设置 `maxTurns` 足够高以完成工作。189 命令可以像任何其他提示一样触及 `maxTurns` / `max_turns` 限制，以错误结果而不是 `success` 结束查询。有关错误结果合约，请参阅 [处理结果](/docs/zh-CN/agent-sdk/agent-loop#handle-the-result)。如果你的命令可能触及限制，请在 TypeScript 中用 `try`/`catch` 或在 Python 中用 `try`/`except` 包装循环，如 [单消息输入](/docs/zh-CN/agent-sdk/streaming-vs-single-mode#single-message-input) 中所示，或设置 `maxTurns` 足够高以完成工作。

186</Note>190</Note>

agent-sdk/subagents.md +4 −3

Details

153</h3>153</h3>

154 154

155| 字段 | 类型 | 必需 | 描述 |155| 字段 | 类型 | 必需 | 描述 |

156| :---------------- | :---------------------------------------------------------- | :- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |156| :---------------- | :---------------------------------------------------------- | :- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

168| `omitClaudeMd` | `boolean` | 否 | 当此代理作为子代理运行时，在不使用用户、项目和本地 CLAUDE.md 文件的情况下运行此代理；托管策略文件仍然加载。当代理作为主线程代理运行时忽略。需要 TypeScript Agent SDK v0.3.271 或更高版本。Python SDK 的 [`AgentDefinition`](/docs/zh-CN/agent-sdk/python#agentdefinition) 没有此字段 |

170 171

197下表列出了非分叉子代理的上下文包含的内容以及它遗漏的内容。198下表列出了非分叉子代理的上下文包含的内容以及它遗漏的内容。

198 199

199| 子代理接收 | 子代理不接收 |200| 子代理接收 | 子代理不接收 |

200| :---------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------- |201| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------- |

202| 项目 CLAUDE.md（通过 [`settingSources`](/docs/zh-CN/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) 加载） | 预加载的技能内容，除非在 `AgentDefinition.skills` 中列出 |203| 项目 CLAUDE.md（通过 [`settingSources`](/docs/zh-CN/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) 加载），除非代理设置了 [`omitClaudeMd`](#agentdefinition-configuration) | 预加载的技能内容，除非在 `AgentDefinition.skills` 中列出 |

204 205

205<Note>206<Note>

agent-sdk/typescript.md +239 −106

Details

491| `allowedTools` | `string[]` | `[]` | 无需提示即可自动批准的工具。这不会将 Claude 限制为仅这些工具。如果您在此处命名[任务跟踪工具](/docs/zh-CN/agent-sdk/todo-tracking#model-availability)之一，Claude Code 也会选择加入会话。其他未列出的工具会通过 `permissionMode` 和 `canUseTool` 进行处理。使用 `disallowedTools` 阻止工具。请参阅[权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |491| `allowedTools` | `string[]` | `[]` | 无需提示即可自动批准的工具。这不会将 Claude 限制为仅这些工具。如果您在此处命名[任务跟踪工具](/docs/zh-CN/agent-sdk/todo-tracking#model-availability)之一，Claude Code 也会选择加入会话。其他未列出的工具会通过 `permissionMode` 和 `canUseTool` 进行处理。使用 `disallowedTools` 阻止工具。请参阅[权限](/docs/zh-CN/agent-sdk/permissions#allow-and-deny-rules) |

493| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自定义权限函数，仅在[权限流](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)落到提示时调用。不会为 `allowedTools`、allow 规则或 `permissionMode` 自动批准的调用调用。allow 规则不会预先批准[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)；请参阅[权限如何被评估](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)了解哪些到达回调以及在 `dontAsk` 和 `auto` 模式下会发生什么。请参阅 [`CanUseTool`](#canusetool) 了解详情 |493| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自定义权限函数，仅在[权限流](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)落到提示时调用。不会为 `allowedTools`、allow 规则或 `permissionMode` 自动批准的调用调用。allow 规则不会预先批准[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)；请参阅 [`CanUseTool`](#canusetool) 了解详情 |

504| `extraArgs` | `Record<string, string \| null>` | `{}` | 其他参数 |504| `extraArgs` | `Record<string, string \| null>` | `{}` | 其他参数 |

507| `forwardSubagentText` | `boolean` | `false` | 转发 subagent 文本和思考块作为助手和用户消息，并设置 `parent_tool_use_id`，以便消费者可以呈现嵌套记录。没有此选项，Claude Code 会发出 subagent `tool_use` 和 `tool_result` 块，但不会发出文本或思考。来自每个嵌套深度的 subagents 的消息在 Claude Code v2.1.219 及更高版本上转发；在 v2.1.219 之前，仅出现来自深度 1 subagents 的消息 |507| `forwardSubagentText` | `boolean` | `false` | 转发 subagent 文本和思考块作为助手和用户消息，并设置 `parent_tool_use_id`，以便消费者可以呈现嵌套记录。没有此选项，Claude Code 会发出 subagent `tool_use` 和 `tool_result` 块，但不会发出文本或思考。来自每个嵌套深度的 subagents 的消息在 Claude Code v2.1.219 及更高版本上转发；在 v2.1.219 之前，仅出现来自深度 1 subagents 的消息 |

508| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 事件的 Hook 回调 |508| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | 事件的 Hook 回调 |

512| `managedSettings` | `Settings` | `undefined` | 您的主机进程提供给生成的会话的策略层设置。在具有管理员部署的托管设置的机器上，Claude Code 会忽略这些，除非管理员的最高优先级托管源设置 `parentSettingsBehavior: 'merge'`，并且当 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 提供托管设置时永远不会合并它们。合并的值通过仅限制性过滤器；[限制父设置](/docs/zh-CN/claude-apps-gateway#restrict-parent-settings)涵盖过滤器允许的内容和 `allowManaged*Only` 锁。设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 的主机有三个键直接从此有效负载读取：其在 Claude Code v2.1.222 或更高版本上的[模型配置](/docs/zh-CN/model-config#restrict-model-selection)、当没有托管源在 v2.1.246 或更高版本上设置它时的 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing)，以及其在 v2.1.247 或更高版本上的 `ENABLE_TOOL_SEARCH` env 条目 |512| `managedSettings` | `Settings` | `undefined` | 您的主机进程提供给生成的会话的策略层设置。在具有管理员部署的托管设置的机器上，Claude Code 会忽略这些，除非管理员的最高优先级托管源设置 `parentSettingsBehavior: 'merge'`，并且当 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 提供托管设置时永远不会合并它们。合并的值通过仅限制性过滤器；[限制父设置](/docs/zh-CN/claude-apps-gateway#restrict-parent-settings)涵盖过滤器允许的内容和 `allowManaged*Only` 锁。设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 的主机有三个键直接从此有效负载读取：其在 Claude Code v2.1.222 或更高版本上的[模型配置](/docs/zh-CN/model-config#restrict-model-selection)、当没有托管源在 v2.1.246 或更高版本上设置它时的 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing)，以及其在 v2.1.247 或更高版本上的 `ENABLE_TOOL_SEARCH` env 条目 |

516| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 服务器配置 |516| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP 服务器配置 |

537| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 默认值（所有源） | 控制加载哪些文件系统设置。传递 `[]` 以禁用用户、项目和本地设置。[端点管理的策略](/docs/zh-CN/managed-settings#delivery-mechanisms)无论如何都会加载；当会话使用组织凭证在[符合条件的配置](/docs/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器管理的设置。请参阅[使用 Claude Code 功能](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) |537| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI 默认值（所有源） | 控制加载哪些文件系统设置。传递 `[]` 以禁用用户、项目和本地设置。[端点管理的策略](/docs/zh-CN/managed-settings#delivery-mechanisms)无论如何都会加载；当会话使用组织凭证在[符合条件的配置](/docs/zh-CN/server-managed-settings#platform-availability)上进行身份验证时，会获取服务器管理的设置。请参阅[使用 Claude Code 功能](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

538| `skills` | `string[] \| 'all'` | `undefined` | 会话可用的 skills。传递 `'all'` 以启用每个发现的 skill，或传递 skill 名称列表。仅传递确切名称。在 Agent SDK v0.3.221 或更高版本上，SDK 在启动 Claude Code 进程之前会以错误拒绝格式错误和通配符形式的名称。设置后，SDK 会自动将 Skill 工具添加到 `allowedTools`。如果您也传递 `tools`，请在该列表中包含 `'Skill'`。请参阅[Skills](/docs/zh-CN/agent-sdk/skills) |538| `skills` | `string[] \| 'all'` | `undefined` | 会话可用的 skills。传递 `'all'` 以启用每个发现的 skill，或传递 skill 名称列表。仅传递确切名称。在 Agent SDK v0.3.221 或更高版本上，SDK 在启动 Claude Code 进程之前会以错误拒绝格式错误和通配符形式的名称。设置后，SDK 会自动将 Skill 工具添加到 `allowedTools`。如果您也传递 `tools`，请在该列表中包含 `'Skill'`。请参阅[Skills](/docs/zh-CN/agent-sdk/skills) |

636| `interrupt()` | 中断查询。仅在流式输入模式下可用。当 CLI 在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中通告 `interrupt_receipt_v1` 功能时，使用列出中断时待处理的消息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 进行解决。在 v2.1.205 之前的 CLI 上解决为 `undefined` |636| `interrupt()` | 中断查询。仅在流式输入模式下可用。当 CLI 在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中通告 `interrupt_receipt_v1` 功能时，使用列出中断时待处理的消息的 [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) 进行解决。在 v2.1.205 之前的 CLI 上解决为 `undefined` |

637| `rewindFiles(userMessageId, options?)` | 将文件恢复到指定用户消息时的状态。传递 `{ dryRun: true }` 以预览更改。需要 `enableFileCheckpointing: true`。请参阅[文件 checkpointing](/docs/zh-CN/agent-sdk/file-checkpointing) |637| `rewindFiles(userMessageId, options?)` | 将文件恢复到指定用户消息时的状态。传递 `{ dryRun: true }` 以预览更改。需要 `enableFileCheckpointing: true`。请参阅[文件 checkpointing](/docs/zh-CN/agent-sdk/file-checkpointing) |

642| `updateSettings(source, settings)` | 将设置合并到项目的本地设置文件 `.claude/settings.local.json` 中；它们在下一个请求时生效。仅接受 `source: 'localSettings'` 和允许列表键集，目前为 `outputStyle`，带有字符串值；不支持删除键。在远程传输和 [`settingSources`](#options) 排除 `local` 的会话中拒绝。需要 TypeScript SDK v0.3.257 或更高版本，它捆绑 Claude Code v2.1.257 |642| `updateSettings(source, settings)` | 将设置合并到项目的本地设置文件 `.claude/settings.local.json` 中；它们在下一个请求时生效。仅接受 `source: 'localSettings'` 和允许列表键集，目前为 `outputStyle`，带有字符串值；不支持删除键。在远程传输和 [`settingSources`](#options) 排除 `local` 的会话中拒绝。需要 TypeScript SDK v0.3.257 或更高版本，它捆绑 Claude Code v2.1.257 |

673 673

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

675 675

676连续调用浅合并顶级键。第二次调用 `{ permissions: {...} }` 会替换先前调用中的整个 `permissions` 对象，而不是深度合并到其中。要从标志层清除键并回退到较低优先级源，请为该键传递 `null`。传递 `undefined` 无效，因为 JSON 序列化会将其删除。676连续调用浅合并顶级键。第二次调用 `{ permissions: {...} }` 会替换先前调用中的整个 `permissions` 对象，而不是深度合并到其中。要从标志层清除键并回退到较低优先级源，请为该键传递 `null`。大多数键然后回退到较低优先级源。清除的 `model` 重置为[Claude Code 的默认模型](/docs/zh-CN/model-config)，即使设置文件设置 `model`。传递 `undefined` 无效，因为 JSON 序列化会将其删除。

677 677

678仅在流式输入模式下可用，与 `setModel()` 和 `setPermissionMode()` 的约束相同。678仅在流式输入模式下可用，与 `setModel()` 和 `setPermissionMode()` 的约束相同。

679 679

680下面的示例在会话中期切换活动模型，然后清除覆盖，以便模型回退到用户或项目设置指定的任何内容。680下面的示例在会话中期切换活动模型，然后清除覆盖，以便模型重置为[Claude Code 的默认模型](/docs/zh-CN/model-config)。

681 681

682```typescript theme={null}682```typescript theme={null}

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

687// 覆盖会话其余部分的模型687// 覆盖会话其余部分的模型

688await q.applyFlagSettings({ model: "claude-opus-4-6" });688await q.applyFlagSettings({ model: "claude-opus-4-6" });

689 689

690// 稍后：清除覆盖并回退到较低优先级设置690// 稍后：清除覆盖；模型重置为 Claude Code 的默认模型

691await q.applyFlagSettings({ model: null });691await q.applyFlagSettings({ model: null });

692```692```

693 693

960 initialPrompt?: string;960 initialPrompt?: string;

961 maxTurns?: number;961 maxTurns?: number;

962 background?: boolean;962 background?: boolean;

963 omitClaudeMd?: boolean;

963 memory?: "user" | "project" | "local";964 memory?: "user" | "project" | "local";

965 permissionMode?: PermissionMode;966 permissionMode?: PermissionMode;

979| `initialPrompt` | 否 | 当此代理作为主线程代理运行时，自动提交为第一个用户轮次 |980| `initialPrompt` | 否 | 当此代理作为主线程代理运行时，自动提交为第一个用户轮次 |

980| `maxTurns` | 否 | 停止前的最大代理轮次数（API 往返） |981| `maxTurns` | 否 | 停止前的最大代理轮次数（API 往返） |

981| `background` | 否 | 调用时将此代理作为非阻塞后台任务运行 |982| `background` | 否 | 调用时将此代理作为非阻塞后台任务运行 |

983| `omitClaudeMd` | 否 | 当此代理作为 subagent 运行时，在没有用户、项目和本地 CLAUDE.md 文件的情况下运行此代理；托管策略文件仍然加载。将其用于从 Agent 工具提示中获取所需内容的代理。当此代理作为主线程代理运行时忽略。需要 TypeScript Agent SDK v0.3.271 或更高版本 |

982| `memory` | 否 | 此代理的内存源：`'user'`、`'project'` 或 `'local'` |984| `memory` | 否 | 此代理的内存源：`'user'`、`'project'` 或 `'local'` |

983| `effort` | 否 | 此代理的推理努力级别。接受命名级别或整数 |985| `effort` | 否 | 此代理的推理努力级别。接受命名级别或整数 |

984| `permissionMode` | 否 | 此代理内工具执行的权限模式。[subagent 继承规则](/docs/zh-CN/agent-sdk/permissions#available-modes)决定何时应用。请参阅 [`PermissionMode`](#permissionmode) |986| `permissionMode` | 否 | 此代理内工具执行的权限模式。[subagent 继承规则](/docs/zh-CN/agent-sdk/permissions#available-modes)决定何时应用。请参阅 [`PermissionMode`](#permissionmode) |

1094 signal: AbortSignal;1096 signal: AbortSignal;

1095 suggestions?: PermissionUpdate[];1097 suggestions?: PermissionUpdate[];

1096 blockedPath?: string;1098 blockedPath?: string;

1099 mcpServer?: { name: string; source: string };

1097 decisionReason?: string;1100 decisionReason?: string;

1098 toolUseID: string;1101 toolUseID: string;

1099 agentID?: string;1102 agentID?: string;

1108| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | 建议的权限更新，以便用户不会再次被提示此工具。Bash 提示包括一个建议，其中包含 `localSettings` [目标](#permissionupdatedestination)，因此在 `updatedPermissions` 中返回它会将规则写入 `.claude/settings.local.json` 并在会话中持久化。 |1111| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | 建议的权限更新，以便用户不会再次被提示此工具。Bash 提示包括一个建议，其中包含 `localSettings` [目标](#permissionupdatedestination)，因此在 `updatedPermissions` 中返回它会将规则写入 `.claude/settings.local.json` 并在会话中持久化。 |

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

1463 permission_denials: SDKPermissionDenial[];1467 permission_denials: SDKPermissionDenial[];

1464 queued_turn_count?: number;1468 queued_turn_count?: number;

1465 errors: string[];1469 errors: string[];

1470 startup_failure_reason?: SDKStartupFailureReason;

1466 user_message_uuid?: string;1471 user_message_uuid?: string;

1467 user_message_uuids?: string[];1472 user_message_uuids?: string[];

1468 terminal_reason?: TerminalReason;1473 terminal_reason?: TerminalReason;

1486* `modelUsage`：在此 `query()` 调用期间通过查询管道进行的每个模型调用的每模型总计，包括主循环、子代理和内部调用（如压缩和 Workflow 代理）。该管道外的辅助调用（如权限分类器和令牌计数请求）被排除。在流式输入会话中，总计在轮次间累积，因此读取最新结果而不是跨结果求和。请参阅[在流式输入模式中跟踪成本](/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)了解零化结果。1491* `modelUsage`：在此 `query()` 调用期间通过查询管道进行的每个模型调用的每模型总计，包括主循环、子代理和内部调用（如压缩和 Workflow 代理）。该管道外的辅助调用（如权限分类器和令牌计数请求）被排除。在流式输入会话中，总计在轮次间累积，因此读取最新结果而不是跨结果求和。请参阅[在流式输入模式中跟踪成本](/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)了解零化结果。

1487* `total_cost_usd`：此 `query()` 调用的累积估计成本（美元），涵盖与 `modelUsage` 相同的调用并在相同点重置。这是一个估计值，不是账单声明。请参阅[跟踪成本和使用情况](/docs/zh-CN/agent-sdk/cost-tracking)了解准确性注意事项。1492* `total_cost_usd`：此 `query()` 调用的累积估计成本（美元），涵盖与 `modelUsage` 相同的调用并在相同点重置。这是一个估计值，不是账单声明。请参阅[跟踪成本和使用情况](/docs/zh-CN/agent-sdk/cost-tracking)了解准确性注意事项。

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

1494*

1495

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

1497

1489* `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"` 之一。1498* `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"` 之一。

1490* `fast_mode_state`：为 `"on"`、`"off"` 或 `"cooldown"` 之一。1499* `fast_mode_state`：为 `"on"`、`"off"` 或 `"cooldown"` 之一。

1491* `fast_mode_disabled_reason`：为什么[快速模式](/docs/zh-CN/fast-mode)现在不可用。当没有任何东西阻止快速模式时不存在，尽管请求仍可能以标准速度运行。在快速模式速率限制后的冷却期间，Claude Code 报告 `fast_mode_state: "cooldown"` 且没有原因代码，并在冷却期过期时重新启用快速模式。需要 Claude Code v2.1.219 或更高版本。1500* `fast_mode_disabled_reason`：为什么[快速模式](/docs/zh-CN/fast-mode)现在不可用。当没有任何东西阻止快速模式时不存在，尽管请求仍可能以标准速度运行。在快速模式速率限制后的冷却期间，Claude Code 报告 `fast_mode_state: "cooldown"` 且没有原因代码，并在冷却期过期时重新启用快速模式。需要 Claude Code v2.1.219 或更高版本。

1561* **`0`**：Claude Code 不计算您发送的没有该 `origin` 的消息，也不计算任务通知，因此轮次仍可能跟随。1570* **`0`**：Claude Code 不计算您发送的没有该 `origin` 的消息，也不计算任务通知，因此轮次仍可能跟随。

1562* **缺失**：Claude Code 在崩溃或致命启动错误后发出的最终结果省略该字段，并且[可能携带零化总计](/docs/zh-CN/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)。1571* **缺失**：Claude Code 在崩溃或致命启动错误后发出的最终结果省略该字段，并且[可能携带零化总计](/docs/zh-CN/agent-sdk/cost-tracking#recover-totals-after-a-session-crash)。

1563 1572

1573<h4 id="startup_failure_reason">

1574 `startup_failure_reason`

1575</h4>

1576

1577Claude Code 拒绝启动的原因，以便您的应用程序可以提供修复而不是重试。Claude Code 在它在已知启动失败时写入的 `error_during_execution` 结果上设置它。该结果携带零化总计，其 `errors` 数组携带与 stderr 相同的文本。该字段在每个其他结果上不存在。需要 Agent SDK v0.3.274 或更高版本。

1578

1579在 [`env`](#options) 中设置 `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` 为 `1` 以接收每个 `SDKStartupFailureReason` 值的此结果。没有该变量，Claude Code 仅为这些失败写入结果，其余的以 stderr 输出、非零退出和无结果消息结束：

1580

1581* 一个恢复，Claude Code 停止因为它[无法将会话返回到其 worktree](/docs/zh-CN/worktrees#the-session-resumes-outside-its-worktree)，带有 `worktree_unverified` 或 `worktree_resume_refused`。该部分说明哪个错误携带哪个值。

1582* 一个被拒绝的[继续](#options)后台会话持有的对话，带有 `session_held_by_background`。对于被拒绝的这样对话的[恢复](#options)，Claude Code 仅在设置了变量时写入结果。

1583

1584```typescript theme={null}

1585type SDKStartupFailureReason =

1586 | "org_pin_api_key_conflict"

1587 | "org_verify_failed"

1588 | "org_pin_mismatch"

1589 | "managed_settings_invalid"

1590 | "remote_settings_required_unavailable"

1591 | "gateway_signin_required"

1592 | "gateway_access_denied"

1593 | "proxy_invalid"

1594 | "temp_dir_unusable"

1595 | "cwd_unavailable"

1596 | "shell_tool_missing"

1597 | "session_held_by_background"

1598 | "worktree_resume_refused"

1599 | "worktree_unverified"

1600 | "cli_version_too_old"

1601 | "bypass_root";

1602```

1603

1604每个值命名一个拒绝：

1605

1606| 值 | 什么停止了会话 |

1607| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |

1608| `org_pin_api_key_conflict` | 托管设置[需要第一方或 Cloud gateway 登录](/docs/zh-CN/authentication#restrict-login-to-your-organization)，并且配置了 Anthropic API 密钥、auth 令牌或 `apiKeyHelper` |

1609| `org_verify_failed` | 登录的组织无法针对 pin 进行验证，例如由于网络故障或已撤销的令牌 |

1610| `org_pin_mismatch` | 登录属于 pin 不允许的组织 |

1611| `managed_settings_invalid` | 托管策略设置无法读取，或 pin 未命名任何组织 |

1612| `remote_settings_required_unavailable` | 组织需要的托管设置无法加载 |

1613| `gateway_signin_required` | [Cloud gateway](/docs/zh-CN/claude-apps-gateway)结束了此登录 |

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

1615| `proxy_invalid` | 代理设置不是完整的 URL |

1616| `temp_dir_unusable` | 每用户临时目录不安全或无法创建 |

1617| `cwd_unavailable` | 工作目录被删除、移动或无法读取 |

1618| `shell_tool_missing` | 在 Windows 上，没有可用的 shell 工具：Git Bash 缺失，PowerShell 缺失或使用 `CLAUDE_CODE_USE_POWERSHELL_TOOL` 关闭 |

1619| `session_held_by_background` | 要恢复或继续的对话作为[后台会话](/docs/zh-CN/agent-view)运行 |

1620| `worktree_resume_refused` | 会话的 worktree 未通过其安全检查，或恢复是从其内部启动的。`errors` 说明运行相同恢复是否继续而不使用 worktree |

1621| `worktree_unverified` | 会话的 worktree 现在无法验证，重试可能成功 |

1622| `cli_version_too_old` | 此 Claude Code 版本低于 Anthropic 要求的最低版本 |

1623| `bypass_root` | 在以 root 身份运行时请求了绕过权限模式 |

1624

1564<h3 id="sdksystemmessage">1625<h3 id="sdksystemmessage">

1565 `SDKSystemMessage`1626 `SDKSystemMessage`

1566</h3>1627</h3>

1582 mcp_servers: {1643 mcp_servers: {

1583 name: string;1644 name: string;

1584 status: string;1645 status: string;

1646 source?: string;

1585 }[];1647 }[];

1586 model: string;1648 model: string;

1587 permissionMode: PermissionMode;1649 permissionMode: PermissionMode;

1601 1663

1602`terminal_slash_commands` 命名 `slash_commands` 中的条目，其接口绑定到本地终端，例如 `exit`。您可以像 `slash_commands` 中的任何其他条目一样发送它们；该字段存在以便远程或移动客户端可以从其命令菜单中隐藏它们。该字段仅在非空时存在，需要 Agent SDK v0.3.229 或更高版本。1664`terminal_slash_commands` 命名 `slash_commands` 中的条目，其接口绑定到本地终端，例如 `exit`。您可以像 `slash_commands` 中的任何其他条目一样发送它们；该字段存在以便远程或移动客户端可以从其命令菜单中隐藏它们。该字段仅在非空时存在，需要 Agent SDK v0.3.229 或更高版本。

1603 1665

1604* `effort`：[努力级别](/docs/zh-CN/model-config#adjust-effort-level) Claude Code 在会话的下一个请求上发送，或当它不发送任何内容时为 `null`。Claude Code 仅在它发送到[远程控制](/docs/zh-CN/remote-control)客户端的初始化消息上设置该字段，并从您的应用程序读取的初始化消息中省略它。需要 Agent SDK v0.3.234 或更高版本。1666*

1667

1668`source` 在每个 `mcp_servers` 条目上：服务器定义来自何处，与 [`McpServerStatus`](#mcpserverstatus) 的 `source` 值相同。需要 Agent SDK v0.3.274 或更高版本。

1669

1670*

1671

1672`effort`：[努力级别](/docs/zh-CN/model-config#adjust-effort-level) Claude Code 在会话的下一个请求上发送，或当它不发送任何内容时为 `null`。Claude Code 仅在它发送到[远程控制](/docs/zh-CN/remote-control)客户端的初始化消息上设置该字段，并从您的应用程序读取的初始化消息中省略它。需要 Agent SDK v0.3.234 或更高版本。

1605 1673

1606`capabilities` 数组命名此 CLI 实现的协议行为，因此您可以进行功能检测而不是比较 `claude_code_version` 字符串。这是一个开放集合：忽略您不认识的值，并检查您依赖其行为的特定功能。该字段需要 Claude Code v2.1.205 或更高版本，在较早的 CLI 上不存在。1674`capabilities` 数组命名此 CLI 实现的协议行为，因此您可以进行功能检测而不是比较 `claude_code_version` 字符串。这是一个开放集合：忽略您不认识的值，并检查您依赖其行为的特定功能。该字段需要 Claude Code v2.1.205 或更高版本，在较早的 CLI 上不存在。

1607 1675

1608| 功能 | 含义 |1676| 功能 | 含义 |

1609| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1677| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |

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

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

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

1612 1681

1613<h3 id="sdkpartialassistantmessage">1682<h3 id="sdkpartialassistantmessage">

1614 `SDKPartialAssistantMessage`1683 `SDKPartialAssistantMessage`

1710当权限系统拒绝工具调用而不显示交互式提示时发出的流事件。使用它在发生时在您的 UI 中呈现拒绝，而不仅仅观察随后的 `is_error` 工具结果。它报告哪些拒绝取决于运行如何处理权限提示：1779当权限系统拒绝工具调用而不显示交互式提示时发出的流事件。使用它在发生时在您的 UI 中呈现拒绝，而不仅仅观察随后的 `is_error` 工具结果。它报告哪些拒绝取决于运行如何处理权限提示：

1711 1780

1712* **使用 [`canUseTool`](#canusetool) 回调**和默认 [`permissionPrompts: 'host'`](#options)：权限提示转到您的回调，此事件报告 Claude Code 自己决定的拒绝，而不调用它。1781* **使用 [`canUseTool`](#canusetool) 回调**和默认 [`permissionPrompts: 'host'`](#options)：权限提示转到您的回调，此事件报告 Claude Code 自己决定的拒绝，而不调用它。

1713* **都没有**：裸 `-p` 运行，或 `query()` 既不设置 `canUseTool` 也不设置 `permissionPromptToolName`，拒绝任何会提示的工具调用，此事件报告这些拒绝以及 Claude Code 自己决定的拒绝。在 v2.1.223 之前，Claude Code 在没有回调的运行中不发出此事件。1782*

1783

1784**都没有**：裸 `-p` 运行，或 `query()` 既不设置 `canUseTool` 也不设置 `permissionPromptToolName`，拒绝任何会提示的工具调用，此事件报告这些拒绝以及 Claude Code 自己决定的拒绝。在 v2.1.223 之前，Claude Code 在没有回调的运行中不发出此事件。

1785

1714* **使用 MCP 提示工具**，使用 `permissionPromptToolName` 或 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 标志设置，以及默认 `permissionPrompts: 'host'`：Claude Code 根本不发出此事件，甚至不发出它自己决定的规则拒绝。1786* **使用 MCP 提示工具**，使用 `permissionPromptToolName` 或 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 标志设置，以及默认 `permissionPrompts: 'host'`：Claude Code 根本不发出此事件，甚至不发出它自己决定的规则拒绝。

1715* **使用 [`permissionPrompts: 'none'`](#options)**：Claude Code 拒绝会提示的调用，即使也设置了 `canUseTool` 或 MCP 提示工具，此事件报告这些拒绝以及 Claude Code 自己决定的拒绝。需要 Claude Code v2.1.259 或更高版本。1787*

1788

1789**使用 [`permissionPrompts: 'none'`](#options)**：Claude Code 拒绝会提示的调用，即使也设置了 `canUseTool` 或 MCP 提示工具，此事件报告这些拒绝以及 Claude Code 自己决定的拒绝。需要 Claude Code v2.1.259 或更高版本。

1716 1790

1717在每个配置中，此事件跳过在 `PreToolUse` hook 路径上决定的任何拒绝，无论 hook 本身拒绝了调用还是拒绝规则覆盖了 hook 的允许或询问决定。该事件也是尽力而为的：偶尔 Claude Code 记录拒绝而不发出此事件，因此[结果消息](#sdkresultmessage)上的 `permission_denials` 是权威记录。1791在每个配置中，此事件跳过在 `PreToolUse` hook 路径上决定的任何拒绝，无论 hook 本身拒绝了调用还是拒绝规则覆盖了 hook 的允许或询问决定。该事件也是尽力而为的：偶尔 Claude Code 记录拒绝而不发出此事件，因此[结果消息](#sdkresultmessage)上的 `permission_denials` 是权威记录。

1718 1792

1892当 Claude Code 将任务通知传递到会话中时，它仅在 Anthropic 服务器验证该通知来自何处时才在通知的 `origin` 上设置 `subkind`。`subkind` 需要 Claude Code v2.1.213 或更高版本，它采用两个值之一：1966当 Claude Code 将任务通知传递到会话中时，它仅在 Anthropic 服务器验证该通知来自何处时才在通知的 `origin` 上设置 `subkind`。`subkind` 需要 Claude Code v2.1.213 或更高版本，它采用两个值之一：

1893 1967

1894* `scheduled-trigger`：通知是[例程](/docs/zh-CN/routines)的存储提示，因为例程的触发器之一触发而传递：其计划、其 [API 触发器](/docs/zh-CN/routines#add-an-api-trigger)、其 [GitHub 触发器](/docs/zh-CN/routines#add-a-github-trigger) 或**立即运行**。Claude Code 将这些框架给模型作为会话的分配任务，带有与[其他任务通知携带的通知](#sdktasknotificationmessage)不同的通知。1968* `scheduled-trigger`：通知是[例程](/docs/zh-CN/routines)的存储提示，因为例程的触发器之一触发而传递：其计划、其 [API 触发器](/docs/zh-CN/routines#add-an-api-trigger)、其 [GitHub 触发器](/docs/zh-CN/routines#add-a-github-trigger) 或**立即运行**。Claude Code 将这些框架给模型作为会话的分配任务，带有与[其他任务通知携带的通知](#sdktasknotificationmessage)不同的通知。

1895* `peer-send-message`：通知是另一个您的会话使用服务器端 `send_message` 工具发送的消息，[Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 会话使用该工具相互消息，而不是[跨会话 `SendMessage` 工具](/docs/zh-CN/cross-session-messaging)，Anthropic 服务器验证了两个会话都属于同一私人会话组。需要 Claude Code v2.1.224 或更高版本。服务器未以这种方式验证的 `send_message` 交付没有 subkind。1969*

1970

1971`peer-send-message`：通知是另一个您的会话使用服务器端 `send_message` 工具发送的消息，[Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 会话使用该工具相互消息，而不是[跨会话 `SendMessage` 工具](/docs/zh-CN/cross-session-messaging)，Anthropic 服务器验证了两个会话都属于同一私人会话组。需要 Claude Code v2.1.224 或更高版本。服务器未以这种方式验证的 `send_message` 交付没有 subkind。

1896 1972

1897每个其他任务通知都没有 `subkind`。这包括在您自己的机器上触发的[计划任务](/docs/zh-CN/scheduled-tasks)、[PR 活动](/docs/zh-CN/claude-code-on-the-web#how-claude-responds-to-pr-activity)传递到会话中，以及后台事件，例如完成的任务。来自[跨会话 `SendMessage` 工具](/docs/zh-CN/cross-session-messaging)的消息根本不是任务通知：无论它们来自同一机器上的会话还是通过 Anthropic 服务器来自另一台机器，Claude Code 都给它们 `kind: "peer"` 和[对等体来源字段](#peer-origin-fields)。1973每个其他任务通知都没有 `subkind`。这包括在您自己的机器上触发的[计划任务](/docs/zh-CN/scheduled-tasks)、[PR 活动](/docs/zh-CN/claude-code-on-the-web#how-claude-responds-to-pr-activity)传递到会话中，以及后台事件，例如完成的任务。来自[跨会话 `SendMessage` 工具](/docs/zh-CN/cross-session-messaging)的消息根本不是任务通知：无论它们来自同一机器上的会话还是通过 Anthropic 服务器来自另一台机器，Claude Code 都给它们 `kind: "peer"` 和[对等体来源字段](#peer-origin-fields)。

1898 1974

1903`peer` 来源标识哪个代理发送了消息：进程内[队友](/docs/zh-CN/agent-teams)使用 `SendMessage` 发送到 `main`，或[跨会话对等体](/docs/zh-CN/cross-session-messaging)，您的另一个 Claude Code 会话。跨会话对等体需要 macOS 和 Linux 上的 Claude Code v2.1.224 或更高版本；请参阅[跨会话消息可用性](/docs/zh-CN/cross-session-messaging#availability)了解本机 Windows 要求。跨会话对等体可以在同一机器上运行，或在[您的另一台机器](/docs/zh-CN/cross-session-messaging#message-sessions-on-other-machines)或[Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 上，当其消息通过远程控制到达时。两种发送者类型填充字段的方式不同：1979`peer` 来源标识哪个代理发送了消息：进程内[队友](/docs/zh-CN/agent-teams)使用 `SendMessage` 发送到 `main`，或[跨会话对等体](/docs/zh-CN/cross-session-messaging)，您的另一个 Claude Code 会话。跨会话对等体需要 macOS 和 Linux 上的 Claude Code v2.1.224 或更高版本；请参阅[跨会话消息可用性](/docs/zh-CN/cross-session-messaging#availability)了解本机 Windows 要求。跨会话对等体可以在同一机器上运行，或在[您的另一台机器](/docs/zh-CN/cross-session-messaging#message-sessions-on-other-machines)或[Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 上，当其消息通过远程控制到达时。两种发送者类型填充字段的方式不同：

1904 1980

1905* `from`：队友的名称，或跨会话对等体的发送者地址。对于[单向跨机器消息](/docs/zh-CN/cross-session-messaging#message-sessions-on-other-machines)，发送者没有回复地址，`from` 是 `"unknown"`。该值由发送者创作；`verifiedPeerPid` 是验证的身份。1981* `from`：队友的名称，或跨会话对等体的发送者地址。对于[单向跨机器消息](/docs/zh-CN/cross-session-messaging#message-sessions-on-other-machines)，发送者没有回复地址，`from` 是 `"unknown"`。该值由发送者创作；`verifiedPeerPid` 是验证的身份。

1906* `fromMode`：发送会话的权限类别，`bypass` 或 `prompting`，由在您的会话之间中继对等消息的主机声明，例如[桌面应用](/docs/zh-CN/desktop#work-across-sessions)。Claude Code 在接收会话中应用[入站控制](/docs/zh-CN/cross-session-messaging#control-inbound-messages)时读取它。需要 Agent SDK v0.3.234 或更高版本。1982*

1983

1984`fromMode`：发送会话的权限类别，`bypass` 或 `prompting`，由在您的会话之间中继对等消息的主机声明，例如[桌面应用](/docs/zh-CN/desktop#work-across-sessions)。Claude Code 在接收会话中应用[入站控制](/docs/zh-CN/cross-session-messaging#control-inbound-messages)时读取它。需要 Agent SDK v0.3.234 或更高版本。

1985

1907* `senderTaskId`：队友的任务 ID。对于跨会话对等体不存在。1986* `senderTaskId`：队友的任务 ID。对于跨会话对等体不存在。

1908* `name`：发送者的显示名称，由 Claude Code 规范化：它删除 Unicode 控制、格式、代理和行或段落分隔符代码点，然后修剪结果并将其限制为 64 个代码点，带有省略号。需要 Claude Code v2.1.205 或更高版本。1987*

1909* `body`：解码的消息正文，去除对等信封，与模型看到的字节完全相同。对于队友消息始终存在；对于跨会话对等体，仅当轮次恰好是由 Claude Code 形成的一个对等信封时才存在。呈现 `name` 和 `body` 而不是重新解析消息文本。需要 Claude Code v2.1.205 或更高版本。1988

1910* `fromSession`：发送者的主机可打开会话 ID，由发送者的主机设置，以便您的 UI 可以链接回发送会话。像 `from` 一样，它是发送者声称的：仅将其用作导航目标，不要将其视为发送者身份的证明。需要 Claude Code v2.1.216 或更高版本。1989`name`：发送者的显示名称，由 Claude Code 规范化：它删除 Unicode 控制、格式、代理和行或段落分隔符代码点，然后修剪结果并将其限制为 64 个代码点，带有省略号。需要 Claude Code v2.1.205 或更高版本。

1911* `verifiedPeerPid`：连接到此会话的跨会话消息套接字的进程的进程 ID，由内核验证并从连接本身读取，从不从有效负载读取。使用它，而不是 `from`，来标识发送者：`from` 可由任何同用户进程伪造。当 Claude Code 无法验证它时，该字段不存在，例如在 Windows 或非套接字入口上，因此缺失值意味着发送者未验证。对于中继流量，它标识中继而不是消息的作者，进程 ID 是可回收的，因此将其视为来源而不是身份验证令牌。需要 Claude Code v2.1.216 或更高版本。1990

1991*

1992

1993`body`：解码的消息正文，去除对等信封，与模型看到的字节完全相同。对于队友消息始终存在；对于跨会话对等体，仅当轮次恰好是由 Claude Code 形成的一个对等信封时才存在。呈现 `name` 和 `body` 而不是重新解析消息文本。需要 Claude Code v2.1.205 或更高版本。

1994

1995*

1996

1997`fromSession`：发送者的主机可打开会话 ID，由发送者的主机设置，以便您的 UI 可以链接回发送会话。像 `from` 一样，它是发送者声称的：仅将其用作导航目标，不要将其视为发送者身份的证明。需要 Claude Code v2.1.216 或更高版本。

1998

1999*

2000

2001`verifiedPeerPid`：连接到此会话的跨会话消息套接字的进程的进程 ID，由内核验证并从连接本身读取，从不从有效负载读取。使用它，而不是 `from`，来标识发送者：`from` 可由任何同用户进程伪造。当 Claude Code 无法验证它时，该字段不存在，例如在 Windows 或非套接字入口上，因此缺失值意味着发送者未验证。对于中继流量，它标识中继而不是消息的作者，进程 ID 是可回收的，因此将其视为来源而不是身份验证令牌。需要 Claude Code v2.1.216 或更高版本。

1912 2002

1913<h2 id="hook-types">2003<h2 id="hook-types">

1914 Hook 类型2004 Hook 类型

2061 tool_name: string;2151 tool_name: string;

2062 tool_input: unknown;2152 tool_input: unknown;

2063 tool_use_id: string;2153 tool_use_id: string;

2154 mcp_server?: McpServerProvenance;

2064};2155};

2065```2156```

2066 2157

2158当工具来自 MCP 服务器时，`mcp_server` 存在；请参阅 [`McpServerProvenance`](#mcpserverprovenance)。`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 和 `PermissionDenied` 输入携带相同的字段。该字段需要 Agent SDK v0.3.274 或更高版本。

2159

2067<h4 id="posttoolusehookinput">2160<h4 id="posttoolusehookinput">

2068 `PostToolUseHookInput`2161 `PostToolUseHookInput`

2069</h4>2162</h4>

2076 tool_response: unknown;2169 tool_response: unknown;

2077 tool_use_id: string;2170 tool_use_id: string;

2078 duration_ms?: number;2171 duration_ms?: number;

2172 mcp_server?: McpServerProvenance;

2079};2173};

2080```2174```

2081 2175

2092 error: string;2186 error: string;

2093 is_interrupt?: boolean;2187 is_interrupt?: boolean;

2094 duration_ms?: number;2188 duration_ms?: number;

2189 mcp_server?: McpServerProvenance;

2095};2190};

2096```2191```

2097 2192

2126 tool_input: unknown;2221 tool_input: unknown;

2127 tool_use_id: string;2222 tool_use_id: string;

2128 reason: string;2223 reason: string;

2224 mcp_server?: McpServerProvenance;

2129};2225};

2130```2226```

2131 2227

2345 tool_name: string;2441 tool_name: string;

2346 tool_input: unknown;2442 tool_input: unknown;

2347 permission_suggestions?: PermissionUpdate[];2443 permission_suggestions?: PermissionUpdate[];

2444 mcp_server?: McpServerProvenance;

2348};2445};

2349```2446```

2350 2447

2855 2952

2856```typescript theme={null}2953```typescript theme={null}

2857type MonitorInput = {2954type MonitorInput = {

2955 description: string;

2956 timeout_ms: number;

2858 command?: string;2957 command?: string;

2859 ws?: {2958 ws?: {

2860 url: string;2959 url: string;

2861 protocols?: string[];2960 protocols?: string[];

2862 };2961 };

2863 description: string;

2864 timeout_ms: number;

2865 persistent: boolean;

2866};2962};

2867```2963```

2868 2964

2869运行后台源并将每个事件传递给 Claude，以便它可以做出反应而无需轮询：`command` 运行脚本并为每个 stdout 行发出一个事件，`ws` 打开 WebSocket 并为每个文本帧发出一个事件。恰好提供 `command` 或 `ws` 之一。`ws` 源需要 Claude Code v2.1.195 或更高版本。2965运行后台源并将每个事件传递给 Claude，以便它可以做出反应而无需轮询：`command` 运行脚本并为每个 stdout 行发出一个事件，`ws` 打开 WebSocket 并为每个文本帧发出一个事件。恰好提供 `command` 或 `ws` 之一。`ws` 源需要 Claude Code v2.1.195 或更高版本。

2870 2966

2871为会话长度的监视（如日志尾部）设置 `persistent: true`。当 Monitor 运行命令时，它遵循与 Bash 相同的权限规则；WebSocket 监视会单独提示批准。请参阅 [Monitor 工具参考](/docs/zh-CN/tools-reference#monitor-tool)了解行为和提供商可用性。导出的类型将 `timeout_ms` 和 `persistent` 标记为必需，因为架构填充了它们的默认值 300000 和 `false`；省略它们的调用会验证通过。2967`timeout_ms` 是监视的截止时间（以毫秒为单位）。它默认为 300000，有效截止时间最多为 1800000，即 30 分钟。在截止时间，监视结束，Claude 收到一个通知，以便在仍需要时可以启动新的监视。

2968

2969导出的类型将 `timeout_ms` 标记为必需，因为架构填充了默认值；省略它的调用会验证通过。

2970

2971当 Monitor 运行命令时，它遵循与 Bash 相同的权限规则；WebSocket 监视会单独提示批准。请参阅 [Monitor 工具参考](/docs/zh-CN/tools-reference#monitor-tool)了解行为和提供商可用性。

2872 2972

2873<h3 id="taskoutput">2973<h3 id="taskoutput">

2874 TaskOutput2974 TaskOutput

4085 summary?: string;4185 summary?: string;

4086 transcriptDir?: string;4186 transcriptDir?: string;

4087 scriptPath?: string;4187 scriptPath?: string;

4088 sessionUrl?: string; // set when the workflow launched as a remote session4188 sessionUrl?: string; // set when the workflow launched as a cloud session

4089 warning?: string;4189 warning?: string;

4090 error?: string;4190 error?: string;

4091};4191};

4095 4195

4096| 字段 | 类型 | 描述 |4196| 字段 | 类型 | 描述 |

4097| --------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |4197| --------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |

4770Claude Code 报告以下四个值之一：4870Claude Code 报告以下四个值之一：

4771 4871

4772| 值 | 使用中的密钥 |4872| 值 | 使用中的密钥 |

4773| -------------------- | --------------------------------------------------------------------------------------------------- |4873| -------------------- | -------------------------------------------------------------------------------------------------- |

4776| `/login managed key` | 当您使用 [Claude Console 账户](/docs/zh-CN/authentication#claude-console-authentication) 登录时 Claude Code 存储的密钥 |4876| `/login managed key` | Claude Code 在您使用 [Claude Console 账户](/docs/zh-CN/authentication#claude-console-authentication) 登录时存储的密钥 |

4778 4878

4779Agent SDK v0.3.234 及更高版本在类型中列出这四个值。该类型还保留 `user`、`project`、`org`、`temporary` 和 `oauth`，以便旧代码仍然可以编译，Claude Code 不报告它们。4879Agent SDK v0.3.234 及更高版本在类型中列出这四个值。该类型还保留 `user`、`project`、`org`、`temporary` 和 `oauth`，以便旧代码仍能编译，Claude Code 不报告它们。

4780 4880

4781<h3 id="sdkbeta">4881<h3 id="sdkbeta">

4782 `SdkBeta`4882 `SdkBeta`

4783</h3>4883</h3>

4784 4884

4785可通过 `betas` 选项启用的可用测试功能。请参阅 [Beta 标头](https://platform.claude.com/docs/en/api/beta-headers) 了解更多信息。4885可通过 `betas` 选项启用的可用 beta 功能。有关更多信息，请参阅 [Beta headers](https://platform.claude.com/docs/en/api/beta-headers)。

4786 4886

4787```typescript theme={null}4887```typescript theme={null}

4788type SdkBeta = "context-1m-2025-08-07";4888type SdkBeta = "context-1m-2025-08-07";

4789```4889```

4790 4890

4791<Warning>4891<Warning>

4792 `context-1m-2025-08-07` beta 自 2026 年 4 月 30 日起已停用。使用 Claude Sonnet 4.5 或 Sonnet 4 传递此值无效，超过标准 200k 令牌上下文窗口的请求返回错误。要使用 1M 令牌上下文窗口，请迁移到 [Claude Opus 5、Claude Sonnet 5、Claude Sonnet 4.6、Claude Opus 4.6、Claude Opus 4.7 或 Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview)，它们以标准定价包括 1M 上下文，无需 beta 标头。4892 `context-1m-2025-08-07` beta 自 2026 年 4 月 30 日起已停用。使用 Claude Sonnet 4.5 或 Sonnet 4 传递此值无效，超过标准 200k 令牌上下文窗口的请求将返回错误。要使用 1M 令牌上下文窗口，请迁移到 [Claude Opus 5、Claude Sonnet 5、Claude Sonnet 4.6、Claude Opus 4.6、Claude Opus 4.7 或 Claude Opus 4.8](https://platform.claude.com/docs/en/about-claude/models/overview)，这些模型在标准定价下包含 1M 上下文，无需 beta 标头。

4793</Warning>4893</Warning>

4794 4894

4795<h3 id="slashcommand">4895<h3 id="slashcommand">

4841 4941

4855 4955

4856| 字段 | 类型 | 描述 |4956| 字段 | 类型 | 描述 |

4857| :------------ | :-------------------- | :----------------------------------------------------------------------------------------------------------------------- |4957| :------------ | :-------------------- | :----------------------------------------------------------------------------------------------------------------------- |

4961

4962<h3 id="mcpserverprovenance">

4963 `McpServerProvenance`

4964</h3>

4965

4966提供 `mcp__*` 工具的 MCP 服务器，以及该服务器定义的来源。[`PreToolUse`](#pretoolusehookinput)、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 和 `PermissionDenied` 钩子输入将其作为 `mcp_server` 携带，[`CanUseTool`](#canusetool) 选项将其作为 `mcpServer` 携带。对于不来自 MCP 服务器的工具，两者都省略它。

4967

4968```typescript theme={null}

4969type McpServerProvenance = {

4970 name: string;

4971 source: string;

4972};

4973```

4974

4975| 字段 | 类型 | 描述 |

4976| :------- | :------- | :---------------------------------------------------------- |

4977| `name` | `string` | 服务器注册时使用的名称，与 [`mcpServerStatus()`](#query-object) 为其报告的值相同 |

4978| `source` | `string` | 服务器定义的来源：`sdk`、`plugin` 或配置范围 |

4979

4980`source` 采用以下值之一。该集合是开放的，因此将您不认识的值视为配置的来源，而不是 `sdk`：

4981

4982* **`sdk`**：您的应用程序注册的进程内服务器。只有 SDK 主机应用程序可以注册一个，因此配置的服务器永远不会报告 `sdk`，无论其名称如何。

4983* **`plugin`**：[plugin](/docs/zh-CN/agent-sdk/plugins) 提供的服务器。其 `name` 是 [plugin-provided MCP servers](/docs/zh-CN/mcp#plugin-provided-mcp-servers) 下描述的作用域 `plugin:<plugin-name>:<server-name>` 形式。

4984* **配置范围**：`user`、`project`、`local`、`dynamic`、`managed`、`enterprise`、`claudeai` 或 `agent`。`.mcp.json` 服务器报告 `project`，[MCP installation scopes](/docs/zh-CN/mcp#mcp-installation-scopes) 定义 `local`、`project` 和 `user`。您的应用程序在 [`mcpServers` 选项](#options) 中传递的服务器（除了进程内 SDK 服务器外）报告 `dynamic`。

4985

4986基于 `source` 做出信任决策，而不是基于 `name` 或 `mcp__<server>__` 工具名称前缀。对于除 `sdk` 之外的任何来源，`name` 是不受信任的文本：在显示前对其进行转义。

4987

4988`McpServerProvenance` 和携带它的字段需要 Agent SDK v0.3.274 或更高版本。

4861 4989

4862<h3 id="mcpserverstatus">4990<h3 id="mcpserverstatus">

4863 `McpServerStatus`4991 `McpServerStatus`

4876 error?: string;5004 error?: string;

4877 config?: McpServerStatusConfig;5005 config?: McpServerStatusConfig;

4878 scope?: string;5006 scope?: string;

5007 source?: string;

4879 tools?: {5008 tools?: {

4880 name: string;5009 name: string;

4881 description?: string;5010 description?: string;

4888};5017};

4889```5018```

4890 5019

5020`source` 说明服务器定义的来源，具有与 [`McpServerProvenance`](#mcpserverprovenance) 的 `source` 相同的值和信任规则。该字段需要 Agent SDK v0.3.274 或更高版本，在早期版本中不存在。

5021

4891<h3 id="mcpserverstatusconfig">5022<h3 id="mcpserverstatusconfig">

4892 `McpServerStatusConfig`5023 `McpServerStatusConfig`

4893</h3>5024</h3>

4894 5025

4895由 `mcpServerStatus()` 报告的 MCP 服务器的配置。这是所有 MCP 服务器传输类型的联合。5026MCP 服务器的配置，由 `mcpServerStatus()` 报告。这是所有 MCP 服务器传输类型的并集。

4896 5027

4897```typescript theme={null}5028```typescript theme={null}

4898type McpServerStatusConfig =5029type McpServerStatusConfig =

4903 | McpClaudeAIProxyServerConfig;5034 | McpClaudeAIProxyServerConfig;

4904```5035```

4905 5036

4906请参阅 [`McpServerConfig`](#mcpserverconfig) 了解每种传输类型的详情。5037有关每种传输类型的详细信息，请参阅 [`McpServerConfig`](#mcpserverconfig)。

4907 5038

4908<h3 id="accountinfo">5039<h3 id="accountinfo">

4909 `AccountInfo`5040 `AccountInfo`

4910</h3>5041</h3>

4911 5042

4912经过身份验证的用户的帐户信息。5043经过身份验证的用户的账户信息。

4913 5044

4914```typescript theme={null}5045```typescript theme={null}

4915type AccountInfo = {5046type AccountInfo = {

4925 `ModelUsage`5056 `ModelUsage`

4926</h3>5057</h3>

4927 5058

4928结果消息中返回的每个模型使用统计。`costUSD` 值是客户端估计。请参阅[跟踪成本和使用情况](/docs/zh-CN/agent-sdk/cost-tracking)了解计费注意事项。5059在结果消息中返回的每个模型的使用统计信息。`costUSD` 值是客户端估计。有关计费注意事项，请参阅 [Track cost and usage](/docs/zh-CN/agent-sdk/cost-tracking)。

4929 5060

4930```typescript theme={null}5061```typescript theme={null}

4931type ModelUsage = {5062type ModelUsage = {

4944};5075};

4945```5076```

4946 5077

4947`thinkingTokens` 计算此模型生成的思考令牌。`outputTokens` 已包括它们，因此不要将两者相加。该字段在运行在记录它的 Claude Code 版本上的轮次之前不存在，因此在早期版本上开始的已恢复会话报告部分计数。`thinkingTokens` 需要 Agent SDK v0.3.257 或更高版本。5078`thinkingTokens` 计算此模型生成的思考令牌。`outputTokens` 已包含它们，因此不要将两者相加。该字段在运行在记录它的 Claude Code 版本上的轮次之前不存在，因此在早期版本上开始的已恢复会话报告部分计数。`thinkingTokens` 需要 Agent SDK v0.3.257 或更高版本。

4948 5079

4949字段 `canonicalModel` 和 `provider` 需要 Claude Code v2.1.218 或更高版本。`canonicalModel` 是定价查询使用的规范模型 ID；它可能与键入条目的原始模型字符串不同，例如当该字符串是提供商特定的 ID 或别名时。5080`canonicalModel` 和 `provider` 字段需要 Claude Code v2.1.218 或更高版本。`canonicalModel` 是定价查询使用的规范模型 ID；它可能与键入条目的原始模型字符串不同，例如当该字符串是提供商特定的 ID 或别名时。

4950 5081

4951`provider` 命名为模型提供服务的 API 后端，例如 `firstParty`、`bedrock`、`vertex`、`foundry`、`anthropicAws`、`mantle` 或 `gateway`。5082`provider` 命名提供模型的 API 后端，例如 `firstParty`、`bedrock`、`vertex`、`foundry`、`anthropicAws`、`mantle` 或 `gateway`。

4952 5083

4953`costBasis` 命名为模型最新请求定价的价格表：`list` 表示列表价格，`managed` 表示 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing) 表，或 `unknown` 当两者都不匹配模型 ID 时。该字段需要 Claude Code v2.1.246 或更高版本。5084`costBasis` 命名为模型最新请求定价的价格表：`list` 表示列表价格，`managed` 表示 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing) 表，或 `unknown` 表示两者都不匹配模型 ID。该字段需要 Claude Code v2.1.246 或更高版本。

4954 5085

4955<h3 id="configscope">5086<h3 id="configscope">

4956 `ConfigScope`5087 `ConfigScope`

4964 `NonNullableUsage`5095 `NonNullableUsage`

4965</h3>5096</h3>

4966 5097

4967[`Usage`](#usage) 的版本，所有可空字段都变为非可空。5098[`Usage`](#usage) 的一个版本，所有可空字段都变为非可空。

4968 5099

4969```typescript theme={null}5100```typescript theme={null}

4970type NonNullableUsage = {5101type NonNullableUsage = {

4976 `Usage`5107 `Usage`

4977</h3>5108</h3>

4978 5109

4979令牌使用统计。这是来自 `@anthropic-ai/sdk` 的 `BetaUsage` 类型。5110令牌使用统计信息。这是来自 `@anthropic-ai/sdk` 的 `BetaUsage` 类型。

4980 5111

4981```typescript theme={null}5112```typescript theme={null}

4982type Usage = {5113type Usage = {

4999 5130

5000`BetaServerToolUsage`、`BetaIterationsUsage` 和 `BetaOutputTokensDetails` 在 `@anthropic-ai/sdk` 中定义。5131`BetaServerToolUsage`、`BetaIterationsUsage` 和 `BetaOutputTokensDetails` 在 `@anthropic-ai/sdk` 中定义。

5001 5132

5002`output_tokens_details` 按类别分解计费输出。它目前包含一个字段 `thinking_tokens: number`，计算模型生成的输出令牌作为内部推理，包括思考块分隔符。`output_tokens_details` 字段需要 TypeScript SDK v0.3.228 或更高版本，它捆绑了 Claude Code v2.1.228。5133`output_tokens_details` 按类别分解计费输出。它目前携带一个字段 `thinking_tokens: number`，计算模型生成的作为内部推理的输出令牌，包括思考块分隔符。`output_tokens_details` 字段需要 TypeScript SDK v0.3.228 或更高版本，它捆绑了 Claude Code v2.1.228。

5003 5134

5004* **计费**：读取分解以进行观察，而不是计费。`output_tokens` 保持权威总数，`output_tokens - thinking_tokens` 近似非推理输出。5135* **计费**：读取分解以进行观察，而不是用于计费。`output_tokens` 保持为权威总数，`output_tokens - thinking_tokens` 近似非推理输出。

5005* **计数涵盖的内容**：模型生成的原始推理，可能比响应体中返回的思考文本更长。API 通过重新标记化该原始文本来计算它，因此它可能与模型的精确生成计数相差几个令牌。5136* **计数涵盖的内容**：模型生成的原始推理，可能比响应体中返回的思考文本更长。API 通过重新标记该原始文本来计算它，因此它可能与模型的精确生成计数相差几个令牌。

5006* **流式传输**：在流式助手消息上，此分解与 `output_tokens` 一样是 `message_start` 占位符，不包含真实计数，因此从结果消息的 `usage` 读取它，如 [从结果消息读取输出令牌](/docs/zh-CN/agent-sdk/cost-tracking#read-output-tokens-from-the-result-message) 所述。在结果消息上，当模型或提供商不报告分解时，`thinking_tokens` 读取 `0`。5137* **流式传输**：在流式助手消息上，此分解与 `output_tokens` 一样是 `message_start` 占位符，不携带真实计数，因此从结果消息的 `usage` 读取它，如 [Read output tokens from the result message](/docs/zh-CN/agent-sdk/cost-tracking#read-output-tokens-from-the-result-message) 所述。在结果消息上，当模型或提供商不报告分解时，`thinking_tokens` 读取 `0`。

5007* **`null` 情况**：`output_tokens_details` 本身在 Claude Code 合成的助手消息上为 `null`，例如 API 错误消息。5138* **`null` 情况**：`output_tokens_details` 本身在 Claude Code 合成的助手消息上为 `null`，例如 API 错误消息。

5008 5139

5009<h3 id="calltoolresult">5140<h3 id="calltoolresult">

5010 `CallToolResult`5141 `CallToolResult`

5011</h3>5142</h3>

5012 5143

5013MCP 工具结果类型（来自 `@modelcontextprotocol/sdk/types.js`）。`structuredContent` 是一个 JSON 对象，可以与 `content` 一起返回，包括图像块。请参阅[返回结构化数据](/docs/zh-CN/agent-sdk/custom-tools#return-structured-data)。5144MCP 工具结果类型（来自 `@modelcontextprotocol/sdk/types.js`）。`structuredContent` 是可与 `content` 一起返回的 JSON 对象，包括图像块。请参阅 [Return structured data](/docs/zh-CN/agent-sdk/custom-tools#return-structured-data)。

5014 5145

5015```typescript theme={null}5146```typescript theme={null}

5016type CallToolResult = {5147type CallToolResult = {

5017 content: Array<{5148 content: Array<{

5019 // 其他字段因类型而异5150 // Additional fields vary by type

5020 }>;5151 }>;

5021 structuredContent?: Record<string, unknown>;5152 structuredContent?: Record<string, unknown>;

5022 isError?: boolean;5153 isError?: boolean;

5027 `SDKMcpResourceLink`5158 `SDKMcpResourceLink`

5028</h3>5159</h3>

5029 5160

5030MCP 工具按引用返回的一个文件。Claude Code 从工具结果中的 `resource_link` 块构建每个条目，并将列表作为 `resourceLinks` 在 [`SDKUserMessage.tool_use_result`](#sdkusermessage) 上传递，或在调用在后台完成时作为 `resource_links` 在 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 上传递。需要 Agent SDK v0.3.257 或更高版本。5161MCP 工具通过引用返回的一个文件。Claude Code 从工具结果中的 `resource_link` 块构建每个条目，并将列表作为 `resourceLinks` 在 [`SDKUserMessage.tool_use_result`](#sdkusermessage) 上传递，或在后台完成调用时作为 `resource_links` 在 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 上传递。需要 Agent SDK v0.3.257 或更高版本。

5031 5162

5032```typescript theme={null}5163```typescript theme={null}

5033type SDKMcpResourceLink = {5164type SDKMcpResourceLink = {

5041};5172};

5042```5173```

5043 5174

5044Claude Code 删除其 `uri` 或 `name` 不是字符串的块，并省略其值不是列出类型的可选字段。5175Claude Code 丢弃其 `uri` 或 `name` 不是字符串的块，并省略其值不是列出的类型的可选字段。

5045 5176

5046| 字段 | 类型 | 描述 |5177| 字段 | 类型 | 描述 |

5047| :------------ | :------------------------------------- | :------------------ |5178| :------------ | :------------------------------------- | :--------------------- |

5048| `uri` | `string` | 资源的 URI，如服务器返回的那样 |5179| `uri` | `string` | 资源的 URI，如服务器返回的那样 |

5055 5186

5056<h3 id="thinkingconfig">5187<h3 id="thinkingconfig">

5057 `ThinkingConfig`5188 `ThinkingConfig`

5063type ThinkingDisplay = "summarized" | "omitted";5194type ThinkingDisplay = "summarized" | "omitted";

5064 5195

5065type ThinkingConfig =5196type ThinkingConfig =

5066 | { type: "adaptive"; display?: ThinkingDisplay } // 模型确定何时以及多少推理（Opus 4.6+）5197 | { type: "adaptive"; display?: ThinkingDisplay } // The model determines when and how much to reason (Opus 4.6+)

5067 | { type: "enabled"; budgetTokens?: number; display?: ThinkingDisplay } // 固定思考令牌预算5198 | { type: "enabled"; budgetTokens?: number; display?: ThinkingDisplay } // Fixed thinking token budget

5068 | { type: "disabled" }; // 无扩展思考5199 | { type: "disabled" }; // No extended thinking

5069```5200```

5070 5201

5071可选的 `display` 字段控制思考文本是否以 `"summarized"` 或 `"omitted"` 形式返回。在 Claude Opus 4.7 及更高版本上，API 默认值为 `"omitted"`，因此设置 `"summarized"` 以在 `thinking` 块中接收思考内容。Claude Code 不会将 `display` 发送到 Amazon Bedrock 或 Google Cloud 的 Agent Platform，因此在这些提供商上，即使您将 `display` 设置为 `"summarized"`，Opus 4.7 及更高版本也会返回空 `thinking` 块。5202可选的 `display` 字段控制思考文本是否返回为 `"summarized"` 或 `"omitted"`。在 Claude Opus 4.7 及更高版本上，API 默认值为 `"omitted"`，因此设置 `"summarized"` 以在 `thinking` 块中接收思考内容。Claude Code 不向 Amazon Bedrock 或 Google Cloud 的 Agent Platform 发送 `display`，因此在这些提供商上，Opus 4.7 及更高版本即使在您将 `display` 设置为 `"summarized"` 时也返回空 `thinking` 块。

5072 5203

5073<h3 id="spawnedprocess">5204<h3 id="spawnedprocess">

5074 `SpawnedProcess`5205 `SpawnedProcess`

5120<Note>5251<Note>

5121 `signal` 字段告诉您的生成函数何时拆除进程。将其作为 `signal` 选项传递给 Node 的 `spawn()`，或将其传递给您的 VM 或容器拆除处理程序。5252 `signal` 字段告诉您的生成函数何时拆除进程。将其作为 `signal` 选项传递给 Node 的 `spawn()`，或将其传递给您的 VM 或容器拆除处理程序。

5122 5253

5123 此信号不会在 [`Options.abortController`](#options) 中止的瞬间触发。SDK 首先关闭进程的 stdin 并等待约两秒钟，以便 CLI 可以干净地关闭，然后中止此信号。要在调用者中止时立即做出反应，请侦听您自己的 `Options.abortController.signal`，您的生成函数可以从其封闭范围引用。5254 此信号不会在 [`Options.abortController`](#options) 中止时立即触发。SDK 首先关闭进程的 stdin 并等待约两秒，以便 CLI 可以干净地关闭，然后中止此信号。要在调用者中止时立即做出反应，请侦听您自己的 `Options.abortController.signal`，您的生成函数可以从其封闭范围引用。

5124</Note>5255</Note>

5125 5256

5126<h3 id="mcpsetserversresult">5257<h3 id="mcpsetserversresult">

5139 5270

5140当您调用 `setMcpServers()` 时，Claude Code 应用这些规则：5271当您调用 `setMcpServers()` 时，Claude Code 应用这些规则：

5141 5272

5142* **调用未命名的服务器**：Claude Code 保持插件提供的服务器运行。需要 Agent SDK v0.3.210 或更高版本。5273* **调用未命名的服务器**：Claude Code 保持 plugin 提供的服务器运行。需要 Agent SDK v0.3.210 或更高版本。

5143* **调用命名的服务器**：除了 CLI 在启动时启动的内置服务器外，Claude Code 仅当其配置与您传递的配置不同时才替换运行中的服务器。5274* **调用命名的服务器**：除了 CLI 在启动时启动的内置服务器外，Claude Code 仅在其配置与您传递的配置不同时才替换运行中的服务器。

5144* **CLI 在启动时启动的内置服务器**：如果调用命名了一个，Claude Code 删除该条目并在 `errors` 中报告它。5275* **CLI 在启动时启动的内置服务器**：如果调用命名了一个，Claude Code 会删除该条目并在 `errors` 中报告它。

5145 5276

5146承诺在新添加的 stdio、HTTP 和 SSE 服务器连接或失败后解决，因此来自已连接服务器的工具在下一轮可用。5277承诺在新添加的 stdio、HTTP 和 SSE 服务器连接或失败后解决，因此来自已连接服务器的工具在下一轮可用。

5147 5278

5148`added` 列出 Claude Code 添加或替换的服务器，无论它们是否连接。未能连接的服务器同时出现在 `added` 和 `errors` 中，失败文本在 `errors` 下，`failed` 行在 [`mcpServerStatus()`](#methods) 中。在 Claude Code v2.1.257 之前，其连接尝试抛出的服务器仅在 `errors` 下报告。5279`added` 列出 Claude Code 添加或替换的服务器，无论它们是否连接。连接失败的服务器同时出现在 `added` 和 `errors` 中，`errors` 下有失败文本，[`mcpServerStatus()`](#methods) 中有 `failed` 行。在 Claude Code v2.1.257 之前，连接尝试抛出的服务器仅在 `errors` 下报告。

5149 5280

5150<h3 id="rewindfilesresult">5281<h3 id="rewindfilesresult">

5151 `RewindFilesResult`5282 `RewindFilesResult`

5164};5295};

5165```5296```

5166 5297

5167`skippedLinks` 计算跟踪路径，倒带拒绝恢复或删除以确保链接安全：跟踪路径处的符号链接、硬链接或其他非常规文件，不再解析到检查点时指向的位置的父目录，或无法安全读取的备份。该字段需要 Claude Code v2.1.216 或更高版本。使用 `rewindFiles(userMessageId, { dryRun: true })` 的预览调用永远不会设置它。5298`skippedLinks` 计算倒带拒绝恢复或删除以确保链接安全的跟踪路径：跟踪路径处的符号链接、硬链接或其他非常规文件，不再解析为检查点时指向的位置的父目录，或无法安全读取的备份。该字段需要 Claude Code v2.1.216 或更高版本。使用 `rewindFiles(userMessageId, { dryRun: true })` 的预览调用永远不会设置它。

5168 5299

5169<h3 id="sdkstatusmessage">5300<h3 id="sdkstatusmessage">

5170 `SDKStatusMessage`5301 `SDKStatusMessage`

5171</h3>5302</h3>

5172 5303

5173状态更新消息（例如，压缩）。5304状态更新消息（例如压缩）。

5174 5305

5175```typescript theme={null}5306```typescript theme={null}

5176type SDKStatusMessage = {5307type SDKStatusMessage = {

5187 `SDKTaskNotificationMessage`5318 `SDKTaskNotificationMessage`

5188</h3>5319</h3>

5189 5320

5190后台任务完成、失败或停止时的通知。后台任务包括 `run_in_background` Bash 命令、[Monitor](#monitor) 监视和后台子代理。对于 `ambient` 字段，请参阅 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，它定义了它及其版本要求。5321后台任务完成、失败或停止时的通知。后台任务包括 `run_in_background` Bash 命令、[Monitor](#monitor) 监视和后台子代理。对于 `ambient` 字段，请参阅 [`SDKTaskStartedMessage`](#sdktaskstartedmessage)，它定义了它和它的版本要求。

5191 5322

5192```typescript theme={null}5323```typescript theme={null}

5193type SDKTaskNotificationMessage = {5324type SDKTaskNotificationMessage = {

5210};5341};

5211```5342```

5212 5343

5213当 Claude Code [将长 MCP 工具调用移到后台](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls) 时，该调用的 `tool_result` 块仅保存占位符，调用的真实结果在此通知中到达。使用 `tool_use_id` 将通知与调用匹配。在 `completed` 通知上，`resource_links` 列出工具按引用返回的文件作为 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 条目，具有与 [`tool_use_result.resourceLinks`](#sdkusermessage) 相同的 50 链接和 64 KiB 限制。Claude Code 在结果没有链接时省略 `resource_links`，以及在不是 MCP 工具调用的任务的通知上。`resource_links` 需要 Agent SDK v0.3.257 或更高版本。5344当 Claude Code [将长 MCP 工具调用移到后台](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls) 时，该调用的 `tool_result` 块仅保存占位符，调用的真实结果在此通知中到达。使用 `tool_use_id` 将通知与调用匹配。在 `completed` 通知上，`resource_links` 列出工具通过引用返回的文件，作为 [`SDKMcpResourceLink`](#sdkmcpresourcelink) 条目，具有与 [`tool_use_result.resourceLinks`](#sdkusermessage) 相同的 50 链接和 64 KiB 限制。Claude Code 在结果没有链接时省略 `resource_links`，以及在不是 MCP 工具调用的任务的通知上。`resource_links` 需要 Agent SDK v0.3.257 或更高版本。

5214 5345

5215Claude Code 在发送给模型的每个任务通知前面加上通知，除了带有 [`scheduled-trigger` 子类型](#task-notification-subkinds) 的传递外，它们改为携带分配任务框架。通知说明没有发生人类输入，因此模型不会将通知视为用户指令或批准。5346Claude Code 在发送给模型的每个任务通知前面加上通知，除了带有 [`scheduled-trigger` subkind](#task-notification-subkinds) 戳记的通知外，它们改为携带分配任务框架。通知说明没有发生人类输入，因此模型不会将通知视为用户指令或批准。

5216 5347

5217要检测任务通知轮次，请在 [`SDKUserMessage`](#sdkusermessage) 或 [`SDKResultMessage`](#sdkresultmessage) 上检查 `origin.kind === "task-notification"`，而不是匹配通知文本。如果您需要知道是什么引发了它，请从同一字段读取 `subkind`。在 v2.1.205 之前，Claude Code 在会话空闲时到达的通知上省略了通知。5348要检测任务通知轮次，请在 [`SDKUserMessage`](#sdkusermessage) 或 [`SDKResultMessage`](#sdkresultmessage) 上检查 `origin.kind === "task-notification"`，而不是匹配通知文本。如果您需要知道是什么引发了它，请从同一字段读取 `subkind`。在 v2.1.205 之前，Claude Code 在会话空闲时到达的通知上省略了通知。

5218 5349

5236 `SDKHookStartedMessage`5367 `SDKHookStartedMessage`

5237</h3>5368</h3>

5238 5369

5239当 hook 开始执行时发出。5370在钩子开始执行时发出。

5240 5371

5241Claude Code 将此消息、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage) 立即传递到消息流，包括在会话启动期间 `SessionStart` 或 `Setup` hook 仍在运行时。Claude Code v2.1.169 至 v2.1.203 在 `SessionStart` 或 `Setup` hook 完成后以一个批次传递这些消息；v2.1.204 恢复了实时传递。5372Claude Code 将此消息、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage) 立即传递到消息流，包括在会话启动期间 `SessionStart` 或 `Setup` 钩子仍在运行时。Claude Code v2.1.169 至 v2.1.203 在 `SessionStart` 或 `Setup` 钩子完成后分批传递这些消息；v2.1.204 恢复了实时传递。

5242 5373

5243```typescript theme={null}5374```typescript theme={null}

5244type SDKHookStartedMessage = {5375type SDKHookStartedMessage = {

5256 `SDKHookProgressMessage`5387 `SDKHookProgressMessage`

5257</h3>5388</h3>

5258 5389

5259在 hook 运行时发出，包含 stdout/stderr 输出。5390在钩子运行时发出，带有 stdout/stderr 输出。

5260 5391

5261```typescript theme={null}5392```typescript theme={null}

5262type SDKHookProgressMessage = {5393type SDKHookProgressMessage = {

5277 `SDKHookResponseMessage`5408 `SDKHookResponseMessage`

5278</h3>5409</h3>

5279 5410

5280当 hook 完成执行时发出。5411在钩子完成执行时发出。

5281 5412

5282```typescript theme={null}5413```typescript theme={null}

5283type SDKHookResponseMessage = {5414type SDKHookResponseMessage = {

5325};5456};

5326```5457```

5327 5458

5328当工具调用在主对话中运行时，Claude Code 每 30 秒发出一条 `tool_progress` 消息，其中 `heartbeat: true`。每个心跳都包含工具名称和经过的秒数，因此您可以区分长时间运行的调用和停滞的会话。Claude Code 不为子代理内的工具调用发出心跳。`heartbeat` 字段需要 Agent SDK v0.3.214 或更高版本。在 v2.1.257 之前，Claude Code 也不为前台 Agent 工具调用发出心跳。5459当工具调用在主对话中运行时，Claude Code 每 30 秒发出一条 `tool_progress` 消息，带有 `heartbeat: true`。每个心跳携带工具名称和经过的秒数，因此您可以区分长时间运行的调用和停滞的会话。Claude Code 不为子代理内的工具调用发出心跳。`heartbeat` 字段需要 Agent SDK v0.3.214 或更高版本。在 v2.1.257 之前，Claude Code 也不为前台 Agent 工具调用发出心跳。

5329 5460

5330在除心跳外的 Agent 工具的 `tool_progress` 消息上，`subagent_type` 命名运行中的子代理类型，例如 `general-purpose`。`subagent_retry` 在该子代理等待 API 错误退避（例如速率限制或过载）时出现，每个重试尝试一条消息。两个字段都需要 Agent SDK v0.3.214 或更高版本。5461在除心跳外的 Agent 工具的 `tool_progress` 消息上，`subagent_type` 命名运行中的子代理类型，例如 `general-purpose`。`subagent_retry` 在该子代理等待 API 错误退避（例如速率限制或过载）时出现，每次重试尝试一条消息。两个字段都需要 Agent SDK v0.3.214 或更高版本。

5331 5462

5332要从 `subagent_retry` 呈现重试指示器：5463要从 `subagent_retry` 呈现重试指示器：

5333 5464

5334* 按 `parent_tool_use_id` 跟踪指示器，这对每个子代理是唯一的。`tool_use_id` 由来自一个助手轮次的并行子代理共享，因此按它跟踪会让一个子代理的更新清除另一个的指示器。5465* 按 `parent_tool_use_id` 跟踪指示器，这对每个子代理是唯一的。`tool_use_id` 由来自一个助手轮次的并行子代理共享，因此按它跟踪会让一个子代理的更新清除另一个的指示器。

5335* 当同一 `parent_tool_use_id` 的后续 `tool_progress` 到达时清除指示器，既不包含 `subagent_retry` 也不包含 `heartbeat: true`，或当工具的结果消息到达时。带有 `heartbeat: true` 的帧仅报告活跃性，因此当一个到达时保持指示器。`attempt` 可能在持续重试下超过 `max_retries`，因此不要从计数器派生清除。5466* 当同一 `parent_tool_use_id` 的后续 `tool_progress` 到达时清除指示器，既不带 `subagent_retry` 也不带 `heartbeat: true`，或当工具的结果消息到达时。带 `heartbeat: true` 的帧仅报告活跃性，因此在一个到达时保持指示器。`attempt` 可能在持续重试下超过 `max_retries`，因此不要从计数器派生清除。

5336* 将 `error_category` 视为选择您自己的消息文本的令牌，而不是显示文本。值为 `rate_limit`、`overloaded`、`authentication_failed`、`server_error`、`cloud_credential_error` 和 `unknown`。处理您不识别的值的方式与处理 `unknown` 的方式相同，因为后续版本可以添加值。5467* 将 `error_category` 视为选择您自己的消息文本的令牌，而不是显示文本。值为 `rate_limit`、`overloaded`、`authentication_failed`、`server_error`、`cloud_credential_error` 和 `unknown`。处理您不认识的值的方式与处理 `unknown` 的方式相同，因为后续版本可以添加值。

5337 5468

5338<h3 id="sdkauthstatusmessage">5469<h3 id="sdkauthstatusmessage">

5339 `SDKAuthStatusMessage`5470 `SDKAuthStatusMessage`

5340</h3>5471</h3>

5341 5472

5342在身份验证流程中发出。5473在身份验证流期间发出。

5343 5474

5344```typescript theme={null}5475```typescript theme={null}

5345type SDKAuthStatusMessage = {5476type SDKAuthStatusMessage = {

5356 `SDKTaskStartedMessage`5487 `SDKTaskStartedMessage`

5357</h3>5488</h3>

5358 5489

5359当任务开始时发出。`task_type` 字段对于 Bash 命令和 [Monitor](#monitor) 监视为 `"local_bash"`，对于子代理为 `"local_agent"`，或 `"remote_agent"`。5490在任务开始时发出。`task_type` 字段对于 Bash 命令和 [Monitor](#monitor) 监视为 `"local_bash"`，对于子代理为 `"local_agent"`，或 `"remote_agent"`。

5360 5491

5361```typescript theme={null}5492```typescript theme={null}

5362type SDKTaskStartedMessage = {5493type SDKTaskStartedMessage = {

5374};5505};

5375```5506```

5376 5507

5377对于不是会话工作一部分的任务，`ambient` 为 `true`，例如 Claude Code 为其自身操作运行的任务。实时更新监视器也是环境的，包括用户要求的监视器。从活动指示器中排除环境任务。该字段需要 Agent SDK v0.3.247 或更高版本。5508`ambient` 对于不是会话工作一部分的任务为 `true`，例如 Claude Code 为其自己的操作运行的任务。实时更新监视器也是环境的，包括用户要求的监视器。从活动指示器中排除环境任务。该字段需要 Agent SDK v0.3.247 或更高版本。

5378 5509

5379`ambient` 也出现在 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 和 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 条目上。5510`ambient` 也出现在 [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) 和 [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) 条目上。

5380 5511

5389 `SDKTaskProgressMessage`5520 `SDKTaskProgressMessage`

5390</h3>5521</h3>

5391 5522

5392在子代理或后台任务运行时定期发出。仅当启用 [`agentProgressSummaries`](#options) 时，`summary` 字段才会被填充。5523在子代理或后台任务运行时定期发出。`summary` 字段仅在启用 [`agentProgressSummaries`](#options) 时填充。

5393 5524

5394```typescript theme={null}5525```typescript theme={null}

5395type SDKTaskProgressMessage = {5526type SDKTaskProgressMessage = {

5415 `SDKTaskUpdatedMessage`5546 `SDKTaskUpdatedMessage`

5416</h3>5547</h3>

5417 5548

5418当后台任务的状态发生变化时发出，例如当它从 `running` 转换为 `completed` 时。将 `patch` 合并到按 `task_id` 键入的本地任务映射中。`end_time` 字段是 Unix 纪元时间戳（以毫秒为单位），可与 `Date.now()` 比较。5549在后台任务的状态更改时发出，例如当它从 `running` 转换为 `completed` 时。将 `patch` 合并到由 `task_id` 键入的本地任务映射中。`end_time` 字段是 Unix 纪元时间戳（以毫秒为单位），可与 `Date.now()` 比较。

5419 5550

5420```typescript theme={null}5551```typescript theme={null}

5421type SDKTaskUpdatedMessage = {5552type SDKTaskUpdatedMessage = {

5439 `SDKBackgroundTasksChangedMessage`5570 `SDKBackgroundTasksChangedMessage`

5440</h3>5571</h3>

5441 5572

5442每当实时后台任务集发生变化时发出：任务启动、完成、被杀死，前台代理被后台化，或任务的 `description` 或 `ambient` 字段发生变化。5573每当实时后台任务集更改时发出：任务启动、完成、被杀死、前台代理被后台化，或任务的 `description` 或 `ambient` 字段更改。

5443 5574

5444`tasks` 数组是完整的实时集。用每个有效负载替换任何缓存的集，而不是配对 `task_started` 和 `task_notification` 事件，以便下一个成员资格变化纠正您错过的任何事件。5575`tasks` 数组是完整的实时集。用每个有效负载替换任何缓存的集，而不是配对 `task_started` 和 `task_notification` 事件，以便下一个成员资格更改纠正您错过的任何事件。

5445 5576

5446相对于这些每个任务事件的顺序是未指定的，因此不要关联这两个流。5577相对于这些每任务事件的顺序是未指定的，因此不要关联两个流。

5447 5578

5448启动时不发出任何内容。每当会话的 CLI 进程启动或重新启动时重置为空集，并让下一个成员资格变化重新填充它。5579启动时不发出任何内容。每当会话的 CLI 进程启动或重新启动时重置为空集，并让下一个成员资格更改重新填充它。

5449 5580

5450当您向运行中的会话发送重复的 `initialize` 控制请求时，例如在传输间隙后使用 [`reinitialize()`](#query-object)，Claude Code 在响应后跟随当前实时集的快照，即使它为空。因此，重新连接的主机可以了解正在运行的内容，而无需等待下一个成员资格变化。在 Agent SDK v0.3.239 之前，Claude Code 在重复 `initialize` 后没有发送快照。5581当您向运行中的会话发送重复的 `initialize` 控制请求时，例如在传输间隙后使用 [`reinitialize()`](#query-object)，Claude Code 在响应后跟随当前实时集的快照，即使它为空。因此，重新连接的主机可以了解正在运行的内容，而无需等待下一个成员资格更改。在 Agent SDK v0.3.239 之前，Claude Code 在重复的 `initialize` 后不发送快照。

5451 5582

5452需要 Claude Code v2.1.203 或更高版本。5583需要 Claude Code v2.1.203 或更高版本。

5453 5584

5470 `SDKThinkingTokensMessage`5601 `SDKThinkingTokensMessage`

5471</h3>5602</h3>

5472 5603

5473在 Claude 生成思考块（包括编辑过的块）时发出。`estimated_tokens` 是迄今为止在当前块中生成的思考令牌的运行估计，`estimated_tokens_delta` 是此帧携带的增量。将这些估计用于进度显示。5604在 Claude 生成思考块时发出，包括编辑过的块。`estimated_tokens` 是当前块中迄今为止生成的思考令牌的运行估计，`estimated_tokens_delta` 是此帧携带的增量。使用这些估计进行进度显示。

5474 5605

5475当模型或提供商报告分解时，顶级代理循环的最终计数是结果消息的 [`usage.output_tokens_details.thinking_tokens`](#usage)，它[不包括子代理令牌](/docs/zh-CN/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)。5606当模型或提供商报告分解时，顶级代理循环的最终计数是结果消息的 [`usage.output_tokens_details.thinking_tokens`](#usage)，它 [不包括子代理令牌](/docs/zh-CN/agent-sdk/cost-tracking#get-the-total-cost-of-a-query)。

5476 5607

5477需要 Claude Code v2.1.153 或更高版本。5608需要 Claude Code v2.1.153 或更高版本。

5478 5609

5492 `SDKFilesPersistedEvent`5623 `SDKFilesPersistedEvent`

5493</h3>5624</h3>

5494 5625

5495当文件检查点持久化到磁盘时发出。5626在文件检查点持久化到磁盘时发出。

5496 5627

5497```typescript theme={null}5628```typescript theme={null}

5498type SDKFilesPersistedEvent = {5629type SDKFilesPersistedEvent = {

5528};5659};

5529```5660```

5530 5661

5531当 `errorCode` 为 `"credits_required"` 时，拒绝来自 claude.ai 订阅，其包含的使用量已耗尽，会话在用户购买使用额度之前无法继续。`canUserPurchaseCredits` 指示经过身份验证的用户是否可以为帐户购买额度，`hasChargeableSavedPaymentMethod` 指示是否有保存的付款方式。所有三个字段在非信用额度必需拒绝的速率限制事件中不存在。需要 Claude Code v2.1.181 或更高版本。5662当 `errorCode` 为 `"credits_required"` 时，拒绝来自 claude.ai 订阅，其包含的使用已耗尽，会话在用户购买使用额度之前无法继续。`canUserPurchaseCredits` 指示经过身份验证的用户是否可以为账户购买额度，`hasChargeableSavedPaymentMethod` 指示是否有保存的付款方式在文件中。所有三个字段在不是额度必需拒绝的速率限制事件上不存在。需要 Claude Code v2.1.181 或更高版本。

5532 5663

5533<h3 id="sdklocalcommandoutputmessage">5664<h3 id="sdklocalcommandoutputmessage">

5534 `SDKLocalCommandOutputMessage`5665 `SDKLocalCommandOutputMessage`

5535</h3>5666</h3>

5536 5667

5537Claude Code 不发出此消息类型。当您发送命令（例如 `/context` 或 `/usage`）作为提示时，其输出作为 [`SDKAssistantMessage`](#sdkassistantmessage) 到达。5668Claude Code 不发出此消息类型。当您发送命令（如 `/context` 或 `/usage`）作为提示时，其输出作为 [`SDKAssistantMessage`](#sdkassistantmessage) 到达。

5538 5669

5539```typescript theme={null}5670```typescript theme={null}

5540type SDKLocalCommandOutputMessage = {5671type SDKLocalCommandOutputMessage = {

5550 `SDKCommandsChangedMessage`5681 `SDKCommandsChangedMessage`

5551</h3>5682</h3>

5552 5683

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

5554 5685

5555```typescript theme={null}5686```typescript theme={null}

5556type SDKCommandsChangedMessage = {5687type SDKCommandsChangedMessage = {

5566 `SDKPromptSuggestionMessage`5697 `SDKPromptSuggestionMessage`

5567</h3>5698</h3>

5568 5699

5569当启用 [`promptSuggestions`](#options) 且 Claude Code 为该轮次生成了建议时，在轮次后发出。包含预测的下一个用户提示。对于未获得任何建议的轮次，请参阅 [当 Claude Code 跳过建议时](/docs/zh-CN/interactive-mode#when-claude-code-skips-suggestions)。5700在启用 [`promptSuggestions`](#options) 且 Claude Code 为该轮生成建议时，在轮次后发出。包含预测的下一个用户提示。对于未获得任何建议的轮次，请参阅 [When Claude Code skips suggestions](/docs/zh-CN/interactive-mode#when-claude-code-skips-suggestions)。

5570 5701

5571```typescript theme={null}5702```typescript theme={null}

5572type SDKPromptSuggestionMessage = {5703type SDKPromptSuggestionMessage = {

5581 `SDKConversationResetMessage`5712 `SDKConversationResetMessage`

5582</h3>5713</h3>

5583 5714

5584当会话的对话被替换而不结束会话时发出。在 `query()` 调用中，仅 `/clear` 及其别名产生此消息。在 `new_conversation_id` 下挂载空记录，并丢弃任何缓存的会话标题。5715在会话的对话被替换而不结束会话时发出。在 `query()` 调用中，只有 `/clear` 及其别名产生此消息。在 `new_conversation_id` 下挂载空成绩单并丢弃任何缓存的会话标题。

5585 5716

5586```typescript theme={null}5717```typescript theme={null}

5587type SDKConversationResetMessage = {5718type SDKConversationResetMessage = {

5592};5723};

5593```5724```

5594 5725

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

5596 5727

5597<h3 id="aborterror">5728<h3 id="aborterror">

5598 `AbortError`5729 `AbortError`

5599</h3>5730</h3>

5600 5731

5601用于中止操作的自定义错误类。5732中止操作的自定义错误类。

5602 5733

5603```typescript theme={null}5734```typescript theme={null}

5604class AbortError extends Error {}5735class AbortError extends Error {}

5605```5736```

5606 5737

5607`AbortError` 是 SDK 的类型化 API 中唯一的错误类。其他失败，例如 Claude Code 进程退出或无法启动，使用没有 SDK 类可匹配的错误拒绝消息迭代。[故障排除](/docs/zh-CN/agent-sdk/troubleshooting) 按消息键入这些错误，每个都有原因和修复。5738`AbortError` 是 SDK 的类型化 API 中唯一的错误类。其他失败，例如 Claude Code 进程退出或启动失败，使用不携带 SDK 类以匹配的错误拒绝消息迭代。[Troubleshooting](/docs/zh-CN/agent-sdk/troubleshooting) 按消息键入这些错误，每个都有原因和修复。

5608 5739

5609<h2 id="sandbox-configuration">5740<h2 id="sandbox-configuration">

5610 沙箱配置5741 沙箱配置

5635| :-------------------------- | :---------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |5766| :-------------------------- | :---------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |

5743 沙箱外命令的权限回退5874 沙箱外命令的权限回退

5744</h3>5875</h3>

5745 5876

5746当 `allowUnsandboxedCommands` 启用时，模型可以通过在工具输入中设置 `dangerouslyDisableSandbox: true` 来请求在沙箱外运行命令。这些请求回退到现有权限系统，意味着您的 `canUseTool` 处理程序被调用，允许您实现自定义授权逻辑。在下面的示例中，`isCommandAuthorized` 代表您定义的授权检查。5877当 `allowUnsandboxedCommands` 启用时，模型可以通过在工具输入中设置 `dangerouslyDisableSandbox: true` 来请求在沙箱外运行命令。这些请求回退到现有权限系统，意味着您的 `canUseTool` 处理程序被调用，允许您实现自定义授权逻辑。在 `excludedCommands` 中列出的命令改为自动绕过沙箱，无需模型参与；请参阅 [`SandboxSettings`](#sandboxsettings)。

5878

5879在下面的示例中，`isCommandAuthorized` 代表您定义的授权检查。

5747 5880

5748```typescript theme={null}5881```typescript theme={null}

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

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

Details

555输入包含 Claude 在 `questions` 数组中生成的问题。每个问题都有这些字段：555输入包含 Claude 在 `questions` 数组中生成的问题。每个问题都有这些字段：

556 556

557| 字段 | 描述 |557| 字段 | 描述 |

558| ------------- | ----------------------------------------------------------------------------------------------------- |558| ------------- | ------------------------------------------------------------------------------------------------------- |

563 563

564您的回调接收的结构：564您的回调接收的结构：

agent-teams.md +5 −1

Details

120 `tmux` 在某些操作系统上有已知限制，传统上在 macOS 上效果最好。在 iTerm2 中使用 `tmux -CC` 是进入 `tmux` 的建议入口点。120 `tmux` 在某些操作系统上有已知限制，传统上在 macOS 上效果最好。在 iTerm2 中使用 `tmux -CC` 是进入 `tmux` 的建议入口点。

121</Note>121</Note>

122 122

123默认值是 `"in-process"`。在 v2.1.179 之前，默认值是 `"auto"`，所以升级的会话如果之前打开了分割窗格，现在会保持在一个终端中，除非你显式设置模式。设置 `"auto"` 以在你已经在 tmux 会话中运行，或你的终端是安装了 `it2` CLI 的 iTerm2 时启用分割窗格，否则回退到 in-process。`"tmux"` 设置启用分割窗格模式，并根据你的终端自动检测是使用 tmux 还是 iTerm2。123默认值是 `"in-process"`。设置 `"auto"` 以在你已经在 tmux 会话中运行，或你的终端是安装了 `it2` CLI 的 iTerm2 时启用分割窗格，否则回退到 in-process。`"tmux"` 设置启用分割窗格模式，并根据你的终端自动检测是使用 tmux 还是 iTerm2。

124 124

125从 v2.1.186 开始，设置 `"iterm2"` 以显式使用 iTerm2 原生分割窗格。此模式需要 [`it2` CLI](https://github.com/mkusaka/it2)，如果 `it2` 缺失，会显示带有安装命令的错误。当你的终端是 iTerm2 且 tmux 可用作备选方案时，在 `"auto"` 或 `"tmux"` 下会出现提供安装 `it2` 或切换到 tmux 的设置提示。125从 v2.1.186 开始，设置 `"iterm2"` 以显式使用 iTerm2 原生分割窗格。此模式需要 [`it2` CLI](https://github.com/mkusaka/it2)，如果 `it2` 缺失，会显示带有安装命令的错误。当你的终端是 iTerm2 且 tmux 可用作备选方案时，在 `"auto"` 或 `"tmux"` 下会出现提供安装 `it2` 或切换到 tmux 的设置提示。

126 126

310* **`skills`**：Claude Code 在任一显示模式中都不将定义的 `skills` 应用于队友。队友从你的项目和用户设置加载 skills。310* **`skills`**：Claude Code 在任一显示模式中都不将定义的 `skills` 应用于队友。队友从你的项目和用户设置加载 skills。

311* **`mcpServers`**：对于分割窗格队友，Claude Code 在 [该字段的规则](/docs/zh-CN/sub-agents#scope-mcp-servers-to-a-subagent) 下应用定义的 `mcpServers`，这些规则涵盖使用 `--agent` 启动的会话。进程内队友忽略该字段，从你的项目和用户设置加载 MCP servers。311* **`mcpServers`**：对于分割窗格队友，Claude Code 在 [该字段的规则](/docs/zh-CN/sub-agents#scope-mcp-servers-to-a-subagent) 下应用定义的 `mcpServers`，这些规则涵盖使用 `--agent` 启动的会话。进程内队友忽略该字段，从你的项目和用户设置加载 MCP servers。

312 312

313当 Claude 向一个不再运行的进程内队友发送消息时，Claude Code 会在同一会话中将其恢复，恢复为其保存的任何对话，并将消息作为其下一个提示给予它。在你恢复一个会话后，队友不会以这种方式被恢复，根据 [恢复限制](#limitations)。

314

315对于它恢复的队友，Claude Code 重新应用来自项目的 `.claude/agents/` 目录或 `--add-dir` 目录的定义，仅当你 [信任了代理文件所在的文件夹](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 时。信任父文件夹不算数。在那之前，队友会恢复时不带定义的任何工具或指示，仅保留 Claude Code 添加到每个进程内队友的工具。请参阅 [the teammate's agent definition was not restored](/docs/zh-CN/errors#teammate-agent-definition-not-restored) 了解通知文本。

316

313<h3 id="permissions">317<h3 id="permissions">

314 权限318 权限

315</h3>319</h3>

agent-view.md +4 −2

Details

16 16

17当你想在任何代理的会话中更直接地工作时，附加到该行以进入完整对话。17当你想在任何代理的会话中更直接地工作时，附加到该行以进入完整对话。

18 18

~~19要比较 agent view 与 subagents、agent teams 和 worktrees，请参阅 [并行运行代理](/docs/zh-CN/agents)。~~19要比较 agent view 与 subagents、agent teams 和 worktrees，请参阅 [并行运行代理](/docs/zh-CN/agents)。Agent view 在你的机器上运行会话，你调度每一个；要让 Claude 从一个对话中在云端启动和跟踪并行会话，请参阅 [Projects](/docs/zh-CN/claude-projects)。

20 20

21<Note>21<Note>

22 Agent view 处于研究预览阶段。随着功能的发展，界面和快捷键可能会改变。22 Agent view 处于研究预览阶段。随着功能的发展，界面和快捷键可能会改变。

1037* [并行运行代理](/docs/zh-CN/agents)：比较 agent view 与 subagents、agent teams 和 worktrees1037* [并行运行代理](/docs/zh-CN/agents)：比较 agent view 与 subagents、agent teams 和 worktrees

1038* [跨会话消息传递](/docs/zh-CN/cross-session-messaging)：让您的会话相互传递发现1038* [跨会话消息传递](/docs/zh-CN/cross-session-messaging)：让您的会话相互传递发现

1039* [Agent teams](/docs/zh-CN/agent-teams)：协调相互发送消息的多个会话1039* [Agent teams](/docs/zh-CN/agent-teams)：协调相互发送消息的多个会话

1040* [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web)：在托管的云环境中运行会话而不是本地1040* [在云端使用 Claude Code](/docs/zh-CN/claude-code-on-the-web)：在托管的云环境中运行会话而不是本地

1041* [Projects](/docs/zh-CN/claude-projects)：让 Claude 从一个对话中协调并行云会话，并告诉您哪些需要您

1041 1042

1042<h2 id="version-history">1043<h2 id="version-history">

1043 版本历史1044 版本历史

1048| 版本 | 更改 |1049| 版本 | 更改 |

1049| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1050| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1050| 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 仅进入调试日志，再次删除被以相同方式拒绝。 |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 仅进入调试日志，再次删除被以相同方式拒绝。 |

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

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

1052| v2.1.260 | 当[删除因未推送的提交被拒绝](#what-deleting-a-session-removes)时，消息会说明 worktree 的分支以及有多少提交未推送，再次删除会话会丢弃 worktree 及其提交。在此版本之前，拒绝仅说 `worktree has commits that are not pushed anywhere`，再次删除被以相同方式拒绝，删除会话需要推送提交或手动删除 worktree。 |1054| v2.1.260 | 当[删除因未推送的提交被拒绝](#what-deleting-a-session-removes)时，消息会说明 worktree 的分支以及有多少提交未推送，再次删除会话会丢弃 worktree 及其提交。在此版本之前，拒绝仅说 `worktree has commits that are not pushed anywhere`，再次删除被以相同方式拒绝，删除会话需要推送提交或手动删除 worktree。 |

1053| v2.1.257 | `←` [从附加的会话分离，即使 `/btw` 覆盖层打开](#attach-to-a-session)，甚至在回答中途，覆盖层在你下次附加时重新打开。在此版本之前，当覆盖层打开时 `←` 不分离。 |1055| v2.1.257 | `←` [从附加的会话分离，即使 `/btw` 覆盖层打开](#attach-to-a-session)，甚至在回答中途，覆盖层在你下次附加时重新打开。在此版本之前，当覆盖层打开时 `←` 不分离。 |

agents.md +5 −4

Details

4 4

5# 并行运行代理5# 并行运行代理

6 6

~~7> 比较 Claude Code 同时处理多个任务的方式：子代理、代理视图、代理团队和动态工作流。~~7> 比较 Claude Code 同时处理多个任务的方式：子代理、代理视图、代理团队、动态工作流和项目。

8 8

9[子代理](/docs/zh-CN/sub-agents)、[代理视图](/docs/zh-CN/agent-view)、[代理团队](/docs/zh-CN/agent-teams) 和 [动态工作流](/docs/zh-CN/workflows) 各自以不同的方式并行化工作。正确的选择取决于您是否想在每个对话中保持参与、交付任务并稍后检查，或让 Claude 为您协调一组工作人员。9Claude Code 有五种方式可以同时处理多个任务：[子代理](/docs/zh-CN/sub-agents)、[代理视图](/docs/zh-CN/agent-view)、[代理团队](/docs/zh-CN/agent-teams)、[动态工作流](/docs/zh-CN/workflows) 和 [项目](/docs/zh-CN/claude-projects)。它们在您保持参与的程度上有所不同，从自己指导每个对话到让 Claude 协调一组工作人员，以及工作是在您的机器上运行还是在云中运行。

10 10

11| 方法 | 它提供什么 | 何时使用 |11| 方法 | 它提供什么 | 何时使用 |

~~12| :------------------------- | :---------------------------------------------- | :----------------------------------------------------------------------- |~~12| :--------------------------- | :---------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------- |

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

17 18

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

20三个更多的工具支持这项工作，但它们本身不是运行代理的方式：21三个更多的工具支持这项工作，但它们本身不是运行代理的方式：

21 22

22* [Worktrees](/docs/zh-CN/worktrees) 为每个会话提供单独的 git 检出，因此并行会话永远不会编辑相同的文件。将它们用于您自己运行的会话。代理视图会 [在编辑文件之前将分派的会话移到自己的 worktree 中](/docs/zh-CN/agent-view#how-file-edits-are-isolated)，您生成的子代理也可以各自获得一个。23* [Worktrees](/docs/zh-CN/worktrees) 为每个会话提供单独的 git 检出，因此并行会话永远不会编辑相同的文件。将它们用于您自己运行的会话。代理视图会 [在编辑文件之前将分派的会话移到自己的 worktree 中](/docs/zh-CN/agent-view#how-file-edits-are-isolated)，您生成的子代理也可以各自获得一个。

23* [跨会话消息传递](/docs/zh-CN/cross-session-messaging) 让 Claude 列出并消息传递您在这台机器上、另一台机器上或 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 上的其他 Claude Code 会话，因此您自己运行的会话可以在彼此之间传递发现和状态。24* [跨会话消息传递](/docs/zh-CN/cross-session-messaging) 让 Claude 列出并消息传递您在这台机器上、另一台机器上或 [云中](/docs/zh-CN/claude-code-on-the-web) 的其他 Claude Code 会话，因此您自己运行的会话可以在彼此之间传递发现和状态。

24* [`/batch`](/docs/zh-CN/commands) 是一个 [skill](/docs/zh-CN/skills)，它让 Claude 将一个大型更改分成 5 到 30 个 worktree 隔离的子代理，每个都打开一个拉取请求。它是子代理和 worktrees 的打包使用，不是一个单独的协调风格。25* [`/batch`](/docs/zh-CN/commands) 是一个 [skill](/docs/zh-CN/skills)，它让 Claude 将一个大型更改分成 5 到 30 个 worktree 隔离的子代理，每个都打开一个拉取请求。它是子代理和 worktrees 的打包使用，不是一个单独的协调风格。

25 26

26还有一些其他功能在没有您驱动每一步的情况下运行 Claude，但它们解决的问题与在代理之间分割工作不同：27还有一些其他功能在没有您驱动每一步的情况下运行 Claude，但它们解决的问题与在代理之间分割工作不同：

amazon-bedrock.md +2 −2

Details

237}237}

238```238```

239 239

240从 Claude Code v2.1.181 开始，也接受来自 `aws configure export-credentials --format process` 的平面输出，在顶级而不是嵌套在 `Credentials` 下具有相同的密钥。240来自 `aws configure export-credentials --format process` 的平面输出也被接受，在顶级而不是嵌套在 `Credentials` 下具有相同的密钥。

241 241

242`Expiration` 是可选的。当命令返回有效的 ISO 8601 `Expiration` 时，Claude Code 会缓存凭证直到该时间前五分钟。没有它，凭证被缓存一小时。242`Expiration` 是可选的。当命令返回有效的 ISO 8601 `Expiration` 时，Claude Code 会缓存凭证直到该时间前五分钟。没有它，凭证被缓存一小时。

243 243

518 使用 Mantle 端点518 使用 Mantle 端点

519</h2>519</h2>

520 520

521Mantle 是一个 Amazon Bedrock 端点，通过原生 Anthropic API 形状而不是 Amazon Bedrock Invoke API 提供 Claude 模型。它使用相同的 AWS 凭证、IAM 权限和本页面前面描述的 `awsAuthRefresh` 配置。521Mantle 是一个 Amazon Bedrock 端点，通过原生 Anthropic API 形状而不是 Amazon Bedrock Invoke API 提供 Claude 模型。它使用相同的 [AWS 凭证](#2-configure-aws-credentials)、[IAM 权限](#iam-configuration) 和 [`awsAuthRefresh` 配置](#advanced-credential-configuration)。

522 522

523<h3 id="enable-mantle">523<h3 id="enable-mantle">

524 启用 Mantle524 启用 Mantle

artifacts.md +4 −4

Details

10 Artifacts 在 Pro、Max、Team 和 Enterprise 计划中可用，需要使用 [`/login`](/docs/zh-CN/setup#authenticate) 登录的会话。有关完整的要求集，请参阅 [可用性](#availability)。10 Artifacts 在 Pro、Max、Team 和 Enterprise 计划中可用，需要使用 [`/login`](/docs/zh-CN/setup#authenticate) 登录的会话。有关完整的要求集，请参阅 [可用性](#availability)。

11</Note>11</Note>

12 12

13Artifact 是一个实时交互式网页，Claude Code 从您的会话发布到 claude.ai 上的私密 URL。您在浏览器中打开它，随着会话的继续，它会实时更新。当您希望其他人也看到它时，可以从页面标题中共享它。13[Artifact](https://claude.com/features/artifacts) 是一个实时交互式网页，Claude Code 从您的会话发布到 claude.ai 上的私密 URL。您在浏览器中打开它，随着会话的继续，它会实时更新。当您希望其他人也看到它时，可以从页面标题中共享它。

14 14

15<Frame>15<Frame>

16 <img src="https://mintcdn.com/claude-code/kaHIYYMIYMYPxQg9/images/artifacts-viewer.png?fit=max&auto=format&n=kaHIYYMIYMYPxQg9&q=85&s=dbfd671cdb0d15f49f808b9e89778fe1" alt="一个 artifact 在浏览器中打开，位于 claude.ai/code/artifact。查看器标题显示 artifact 标题 acme-funnel-fix、一个共享按钮和作者头像。共享菜单已打开，显示"始终共享最新版本"切换、显示"共享版本 2"的版本选择器、"Acme 中的所有人"受众选择器和复制链接按钮。标题下方，artifact 页面显示两个并排的移动设备模型、一个漏斗图表和一行指标卡片。" width="2511" height="1890" data-path="images/artifacts-viewer.png" />16 <img src="https://mintcdn.com/claude-code/kaHIYYMIYMYPxQg9/images/artifacts-viewer.png?fit=max&auto=format&n=kaHIYYMIYMYPxQg9&q=85&s=dbfd671cdb0d15f49f808b9e89778fe1" alt="一个 artifact 在浏览器中打开，位于 claude.ai/code/artifact。查看器标题显示 artifact 标题 acme-funnel-fix、一个共享按钮和作者头像。共享菜单已打开，显示"始终共享最新版本"切换、显示"共享版本 2"的版本选择器、"Acme 中的所有人"受众选择器和复制链接按钮。标题下方，artifact 页面显示两个并排的移动设备模型、一个漏斗图表和一行指标卡片。" width="2511" height="1890" data-path="images/artifacts-viewer.png" />

142读取 https://claude.ai/code/artifact/5fbea6f3-... 上的评论，并进行评论者要求的更改。142读取 https://claude.ai/code/artifact/5fbea6f3-... 上的评论，并进行评论者要求的更改。

143```143```

144 144

145如果 Claude 告诉您它无法读取评论，请检查三件事：145如果 Claude 告诉您它无法读取评论，请确认您的版本、您的会话和您的功能标志设置：

146 146

147* 您运行的是 Claude Code v2.1.221 或更高版本。147* 您运行的是 Claude Code v2.1.221 或更高版本。

148* 您不在安装 Claude Code 或从 v2.1.221 之前的版本升级后的第一个会话中。在[安装或升级后的第一个会话](/docs/zh-CN/env-vars#first-session-after-an-install-or-upgrade)中，Claude 可能还无法读取评论；启动新会话并再次询问。148* 您不在安装 Claude Code 或从 v2.1.221 之前的版本升级后的第一个会话中。在[安装或升级后的第一个会话](/docs/zh-CN/env-vars#first-session-after-an-install-or-upgrade)中，Claude 可能还无法读取评论；启动新会话并再次询问。

291 改进视觉设计291 改进视觉设计

292</h2>292</h2>

293 293

294Claude 在构建工件时应用内置设计技能，因此页面获得精心设计的调色板、排版和布局，无需额外提示。需要 Claude Code v2.1.182 或更高版本。该技能还会在选择自己的设计之前查找项目中是否存在现有设计系统。设计令牌是设计系统重复使用的命名颜色、排版和间距值。为了保持工件与产品品牌的一致性，请将它们记录在 Claude 可以找到的地方，例如项目的 [CLAUDE.md](/docs/zh-CN/memory) 或存储库中的主题文件：294Claude 在构建工件时应用内置设计技能，因此页面获得精心设计的调色板、排版和布局，无需额外提示。该技能还会在选择自己的设计之前查找项目中是否存在现有设计系统。设计令牌是设计系统重复使用的命名颜色、排版和间距值。为了保持工件与产品品牌的一致性，请将它们记录在 Claude 可以找到的地方，例如项目的 [CLAUDE.md](/docs/zh-CN/memory) 或存储库中的主题文件：

295 295

296```markdown theme={null}296```markdown theme={null}

297## Design system297## Design system

331| 无后端 | 工件是一个静态页面。它无法自行对查看者进行身份验证。 |331| 无后端 | 工件是一个静态页面。它无法自行对查看者进行身份验证。 |

332| 下载 | 页面无法自行启动下载。为了让查看者保存页面生成的文件，Claude 声明下载功能。请参阅[提供文件下载](#offer-a-file-download)。 |332| 下载 | 页面无法自行启动下载。为了让查看者保存页面生成的文件，Claude 声明下载功能。请参阅[提供文件下载](#offer-a-file-download)。 |

333| 单页面 | 相对链接无法解析，因为页面旁边没有部署任何内容。对于多部分内容，Claude 使用页面内锚点而不是单独的文件。 |333| 单页面 | 相对链接无法解析，因为页面旁边没有部署任何内容。对于多部分内容，Claude 使用页面内锚点而不是单独的文件。 |

334| 源文件类型 | 发布的文件必须是 `.html`、`.htm` 或 `.md`，并且必须解码为 UTF-8，或通过其字节顺序标记解码为小端 UTF-16。Markdown 文件呈现为样式化的 HTML。无法解码或包含替换字符 `U+FFFD` 的文件会被[拒绝并显示要修复的行和列](/docs/zh-CN/errors#the-source-file-is-not-valid-utf-8-text)。 |334| 源文件类型 | 发布的文件必须是 `.html`、`.htm` 或 `.md`，并且必须解码为 UTF-8，或通过其字节顺序标记解码为小端 UTF-16。Markdown 文件呈现为样式化的文档页面，带有语法突出显示的代码。无法解码或包含替换字符 `U+FFFD` 的文件会被[拒绝并显示要修复的行和列](/docs/zh-CN/errors#the-source-file-is-not-valid-utf-8-text)。 |

335| 呈现大小 | 呈现的页面必须为 16 MiB 或更小。大型嵌入图像通常是发布因大小而失败的原因。 |335| 呈现大小 | 呈现的页面必须为 16 MiB 或更小。大型嵌入图像通常是发布因大小而失败的原因。 |

336 336

337生成工件使用输出令牌，就像任何其他响应一样，样式化页面比相同内容作为终端文本更耗费令牌。内联 CSS、用于交互控制的 JavaScript，尤其是嵌入为数据 URI 的图像是主要贡献者。要减少工件的令牌成本：337生成工件使用输出令牌，就像任何其他响应一样，样式化页面比相同内容作为终端文本更耗费令牌。内联 CSS、用于交互控制的 JavaScript，尤其是嵌入为数据 URI 的图像是主要贡献者。要减少工件的令牌成本：

authentication.md +6 −6

Details

6 6

7> 登录 Claude Code 并为个人、团队和组织配置身份验证。7> 登录 Claude Code 并为个人、团队和组织配置身份验证。

8 8

9Claude Code 支持多种身份验证方法，具体取决于您的设置。个人用户可以使用 Claude.ai 账户登录，而团队可以使用 Claude for Teams 或 Enterprise、Claude Console 或云提供商（如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry）。9Claude Code 支持多种身份验证方法，具体取决于您的设置。个人用户可以使用 claude.ai 账户登录，而团队可以使用 Claude for Teams 或 Enterprise、Claude Console 或云提供商（如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry）。

10 10

11<h2 id="log-in-to-claude-code">11<h2 id="log-in-to-claude-code">

12 登录 Claude Code12 登录 Claude Code

22 22

23您可以使用以下任何账户类型进行身份验证：23您可以使用以下任何账户类型进行身份验证：

24 24

25* **Claude Pro 或 Max 订阅**：使用您的 Claude.ai 账户登录。在 [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max) 订阅。25* **Claude Pro 或 Max 订阅**：使用您的 claude.ai 账户登录。在 [claude.com/pricing](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=authentication_pro_max) 订阅。

~~26* **Claude for Teams 或 Enterprise**：使用您的团队管理员邀请您的 Claude.ai 账户登录。~~26* **Claude for Teams 或 Enterprise**：使用您的团队管理员邀请您的 claude.ai 账户登录。

27* **Claude Console**：使用您的 Console 凭证登录。您的管理员必须先 [邀请您](#claude-console-authentication)。您可以在有或没有 [创建 API 密钥](#sign-in-without-an-api-key) 的情况下登录。27* **Claude Console**：使用您的 Console 凭证登录。您的管理员必须先 [邀请您](#claude-console-authentication)。您可以在有或没有 [创建 API 密钥](#sign-in-without-an-api-key) 的情况下登录。

28* **云提供商**：如果您的组织使用 [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)，请在运行 `claude` 之前设置所需的环境变量，或在登录提示符处选择 **3rd-party platform**，这将为 Bedrock 和 Vertex AI 启动交互式设置向导。不需要浏览器登录。28* **云提供商**：如果您的组织使用 [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)，请在运行 `claude` 之前设置所需的环境变量，或在登录提示符处选择 **3rd-party platform**，这将为 Bedrock 和 Vertex AI 启动交互式设置向导。不需要浏览器登录。

29* **云网关**：如果您的组织运行自托管的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway)，请通过 `/login` 使用企业 SSO 登录。网关颁发的令牌是会话的唯一凭证。29* **云网关**：如果您的组织运行自托管的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway)，请通过 `/login` 使用企业 SSO 登录。网关颁发的令牌是会话的唯一凭证。

66 </Step>66 </Step>

67 67

68 <Step title="安装并登录">68 <Step title="安装并登录">

~~69 团队成员安装 Claude Code 并使用其 Claude.ai 账户登录。~~69 团队成员安装 Claude Code 并使用其 claude.ai 账户登录。

70 </Step>70 </Step>

71</Steps>71</Steps>

72 72

190 * 在 Windows 上，凭证存储在 `%USERPROFILE%\.claude\.credentials.json` 中，并继承您的用户配置文件目录的访问控制，默认情况下将文件限制为您的用户帐户。190 * 在 Windows 上，凭证存储在 `%USERPROFILE%\.claude\.credentials.json` 中，并继承您的用户配置文件目录的访问控制，默认情况下将文件限制为您的用户帐户。

191 * 如果您设置了 `CLAUDE_CONFIG_DIR` 环境变量，Claude Code 会将 `.credentials.json` 文件保存在该目录下，包括 macOS 回退写入的文件，并且还会将 macOS Keychain 条目关键字设置为该目录，因此使用不同 `CLAUDE_CONFIG_DIR` 的会话会读取不同的条目。191 * 如果您设置了 `CLAUDE_CONFIG_DIR` 环境变量，Claude Code 会将 `.credentials.json` 文件保存在该目录下，包括 macOS 回退写入的文件，并且还会将 macOS Keychain 条目关键字设置为该目录，因此使用不同 `CLAUDE_CONFIG_DIR` 的会话会读取不同的条目。

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

194* **自定义凭证脚本**：配置 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 设置以运行返回 API 密钥的 shell 脚本。194* **自定义凭证脚本**：配置 [`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)。195* **刷新间隔**：Claude Code 默认在五分钟后重新运行 `apiKeyHelper`。设置 `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` 环境变量以获得自定义刷新间隔。有关 Claude Code 重新运行助手的其他情况，请参阅 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper)。

196* **缓慢助手通知**：如果 `apiKeyHelper` 返回密钥需要超过 10 秒，Claude Code 会在提示栏中显示警告通知，显示经过的时间。如果您经常看到此通知，请检查您的凭证脚本是否可以优化。196* **缓慢助手通知**：如果 `apiKeyHelper` 返回密钥需要超过 10 秒，Claude Code 会在提示栏中显示警告通知，显示经过的时间。如果您经常看到此通知，请检查您的凭证脚本是否可以优化。

236 236

237运行 `unset ANTHROPIC_API_KEY` 以回退到您的订阅，并检查 `/status` 以确认哪种方法处于活跃状态。当登录和 API 密钥都已配置时，`/status` 会标记未在使用的凭证。237运行 `unset ANTHROPIC_API_KEY` 以回退到您的订阅，并检查 `/status` 以确认哪种方法处于活跃状态。当登录和 API 密钥都已配置时，`/status` 会标记未在使用的凭证。

238 238

239[Claude Code on the Web](/docs/zh-CN/claude-code-on-the-web) 始终使用您的订阅凭证。如果您在沙箱环境中设置 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，它不会覆盖您的订阅凭证。239[Cloud sessions](/docs/zh-CN/claude-code-on-the-web) 始终使用您的订阅凭证。如果您在云环境中设置 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，它不会覆盖您的订阅凭证。

240 240

241<h4 id="anthropic-profiles-and-federation-credentials">241<h4 id="anthropic-profiles-and-federation-credentials">

242 Anthropic 配置文件和联合凭证242 Anthropic 配置文件和联合凭证

auto-mode-config.md +18 −16

Details

91 定义受信基础设施91 定义受信基础设施

92</h2>92</h2>

93 93

94对于大多数组织，`autoMode.environment` 是唯一需要设置的字段。它告诉分类器哪些仓库、存储桶和域名是受信的：分类器使用它来决定"外部"的含义，因此任何未列出的目标都是潜在的数据泄露目标。94对于大多数组织，`autoMode.environment` 是您唯一需要设置的字段。它告诉分类器哪些仓库、存储桶和域是受信的：分类器使用它来决定"外部"的含义，因此任何未列出的目标都是潜在的数据泄露目标。

95 95

96从 Claude Code v2.1.198 开始，`claude auto-mode defaults` 打印三种环境条目。v2.1.195 之前的版本仅打印前五个信任槽。96从 Claude Code v2.1.198 开始，`claude auto-mode defaults` 打印三种环境条目。v2.1.195 之前的版本仅打印前五个信任槽。

97 97

99 * **Organization**99 * **Organization**

100 * **Claude Code 的主要用途**：默认为软件开发100 * **Claude Code 的主要用途**：默认为软件开发

101 * **云提供商**101 * **云提供商**

102 * **Repository visibility**：除非其远程主机和名称另有说明，或分类器读取的对话中较早的可见性检查显示它是公开的，否则假定仓库是私有的。分类器读取您的消息和 Claude 运行的命令，而不是它们的输出，因此证据必须是它能读取的内容，例如您自己的消息将仓库命名为公开；单独运行 `gh repo view` 的输出无法到达它。转录证据检查需要 Claude Code v2.1.200 或更高版本102 * **Repository visibility**：除非其远程主机和名称另有说明，或分类器在对话中较早读取了显示其为公开的可见性检查，否则假定仓库为私有。

103 * **Internal sharing / snippet hosting**：公开粘贴和 gist 服务被视为信任边界外，直到您命名其中一个103

104 在 Claude Code 本身发送的分类器请求中，分类器读取您的消息和 Claude 运行的命令，而不是它们的输出。证据必须是分类器能够读取的内容，例如您自己的消息将仓库命名为公开；`gh repo view` 的输出本身无法到达它。转录证据检查需要 Claude Code v2.1.200 或更高版本

105 * **Internal sharing / snippet hosting**：公开粘贴和 gist 服务被视为在信任边界之外，直到您命名其中一个

104 * **Org-specific CLIs**106 * **Org-specific CLIs**

105 * **Secrets management**107 * **Secrets management**

106 * **CI/CD deploy targets**108 * **CI/CD deploy targets**

107 * **Network posture**109 * **Network posture**

108 * **Host containment**：默认为具有开放互联网的普通开发者机器或 CI 运行器。如果 Claude Code 在具有出站允许列表或不能接触的邻居的容器、VM 或 pod 中运行，请命名允许的主机、云元数据端点是否应该可达，以及任务使用的云项目、集群或注册表以及使用什么身份。在此条目命名该身份之前，分类器[阻止](/docs/zh-CN/permission-modes#what-the-classifier-blocks-by-default)对主机自身凭证的请求。需要 Claude Code v2.1.257 或更高版本110 * **Host containment**：默认为具有开放互联网的普通开发者机器或 CI 运行器。如果 Claude Code 在具有出口允许列表或不能接触的邻居的容器、VM 或 pod 中运行，请命名允许的主机、云元数据端点是否应该可达，以及任务使用的云项目、集群或注册表以及使用什么身份。在此条目命名该身份之前，分类器[阻止](/docs/zh-CN/permission-modes#what-the-classifier-blocks-by-default)对主机自身凭证的请求。需要 Claude Code v2.1.257 或更高版本

109 * **Protected deployment namespaces / environments**：回退到敏感远程目标启发式，直到您命名它们111 * **Protected deployment namespaces / environments**：回退到 Sensitive remote targets 启发式方法，直到您命名它们

110 * **Data retention / declassification**112 * **Data retention / declassification**

111* **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 或更高版本。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 或更高版本。

112* **Sensitivity slots**：命名保护规则视为高风险的内容。槽位为 Sensitive data locations & audiences、Sensitive remote targets 和 Protected IaC scopes。每个默认为广泛的启发式，例如将任何名称中包含 `prod` 或 `production` 的主机或命名空间视为敏感远程目标，因此保护规则在您配置任何内容之前就处于活动状态。在敏感槽中命名具体目标会使这些规则应用于命名的目标而不是启发式。114* **Sensitivity slots**：命名保护规则视为高风险的内容。槽位为 Sensitive data locations & audiences、Sensitive remote targets 和 Protected IaC scopes。每个默认为广泛的启发式方法，例如将任何名称中包含 `prod` 或 `production` 的主机或命名空间视为敏感远程目标，因此保护规则在您配置任何内容之前就处于活动状态。在敏感性槽中命名具体目标会使这些规则应用于命名的目标而不是启发式方法。

113 115

114<Info>在 v2.1.211 之前，context slots 还包括一个 Default / protected branches 条目，该条目将 `main` 和 `master` 视为受保护的，直到您命名其他分支。v2.1.211 移除了它：[推送到您正在处理的仓库的任何分支](#common-boundaries)默认是允许的，因此没有受保护分支默认值需要配置。</Info>116<Info>在 v2.1.211 之前，context slots 还包括一个 Default / protected branches 条目，该条目将 `main` 和 `master` 视为受保护，直到您命名其他分支。v2.1.211 删除了它：[推送到您正在处理的仓库的任何分支](#common-boundaries)默认是允许的，因此没有受保护分支默认值需要配置。</Info>

115 117

116要在默认值旁边添加您自己的条目，请在数组中包含字面字符串 `"$defaults"`。默认条目在该位置被拼接，因此您的自定义条目可以在它们之前或之后。118要在默认值旁边添加您自己的条目，请在数组中包含字面字符串 `"$defaults"`。默认条目在该位置被拼接，因此您的自定义条目可以在它们之前或之后。

117 119

118以下示例保留默认条目并添加组织的仓库、存储桶、域名和服务。120以下示例保留默认条目并添加组织的仓库、存储桶、域和服务。

119 121

120```json theme={null}122```json theme={null}

121{123{

133 135

134保存设置后，运行 `claude auto-mode config` 以[确认有效规则](#inspect-the-defaults-and-your-effective-config)包括您的条目。136保存设置后，运行 `claude auto-mode config` 以[确认有效规则](#inspect-the-defaults-and-your-effective-config)包括您的条目。

135 137

136条目是散文，不是正则表达式或工具模式。分类器将它们读取为自然语言规则。按照您向新工程师描述基础设施的方式编写它们。一个全面的环境部分涵盖：138条目是散文，不是正则表达式或工具模式。分类器将它们读取为自然语言规则。按照您向新工程师描述基础设施的方式编写它们。彻底的环境部分涵盖：

137 139

138* **Organization**：您的公司名称以及 Claude Code 主要用于什么，如软件开发、基础设施自动化或数据工程140* **Organization**：您的公司名称以及 Claude Code 主要用于什么，例如软件开发、基础设施自动化或数据工程

139* **Source control**：您的开发人员推送到的每个 GitHub、GitLab 或 Bitbucket 组织141* **Source control**：您的开发人员推送到的每个 GitHub、GitLab 或 Bitbucket 组织

140* **Cloud providers and trusted buckets**：Claude 应该能够读取和写入的存储桶名称或前缀142* **Cloud providers and trusted buckets**：Claude 应该能够读取和写入的存储桶名称或前缀

141* **Trusted internal domains**：网络内 API、仪表板和服务的主机名，如 `*.internal.example.com`143* **Trusted internal domains**：网络内 API、仪表板和服务的主机名，例如 `*.internal.example.com`

142* **Key internal services**：CI、工件注册表、内部包索引、事件工具144* **Key internal services**：CI、工件注册表、内部包索引、事件工具

143* **Internal package registry**：安装应该通过的私有 npm、PyPI 或其他注册表，因此绕过它安装公开注册表的安装会被阻止145* **Internal package registry**：安装应该通过的私有 npm、PyPI 或其他注册表，因此绕过它安装到公开注册表的安装会被阻止

144* **Sensitive data locations & audiences**：保存个人数据、机密业务数据、凭证、受管制数据或类似敏感材料的存储桶、数据库或路径，以及每个位置中的数据可能与之共享的受众，以便分类器保护这些位置而不是从内容猜测。Claude Code v2.1.195 至 v2.1.197 将此条目命名为 PII / regulated-data locations，仅涵盖保存个人或受管制数据的位置，不包括受众维度146* **Sensitive data locations & audiences**：保存个人数据、机密业务数据、凭证、受管制数据或类似敏感材料的存储桶、数据库或路径，以及每个位置中的数据可能与之共享的受众，以便分类器保护这些位置而不是从内容猜测。Claude Code v2.1.195 到 v2.1.197 将此条目命名为 PII / regulated-data locations，仅涵盖保存个人或受管制数据的位置，不包括受众维度

145* **Sensitive remote targets**：计为生产的命名空间、主机或容器，因此远程 shell 和端口转发到它们需要您的明确批准147* **Sensitive remote targets**：计为生产的命名空间、主机或容器，因此远程 shell 和端口转发到它们需要您的明确批准

146* **Protected IaC scopes**：应用或销毁应始终需要您命名更改的基础设施资源148* **Protected IaC scopes**：应用或销毁应始终需要您命名更改的基础设施资源

147* **Additional context**：受管制行业约束、多租户基础设施或影响分类器应视为风险的合规要求149* **Additional context**：受管制行业约束、多租户基础设施或影响分类器应视为风险的合规要求

169 171

170您提供的上下文越具体，分类器就越能区分常规内部操作和数据泄露尝试。172您提供的上下文越具体，分类器就越能区分常规内部操作和数据泄露尝试。

171 173

172您不需要一次性填写所有内容。合理的推出：从默认值开始，添加您的源代码控制组织和关键内部服务，这解决了最常见的误报，如推送到您自己的仓库。接下来添加受信域和云存储桶。当出现阻止时填写其余部分。174您不需要一次性填写所有内容。合理的推出方式：从默认值开始，添加您的源代码控制组织和关键内部服务，这解决了最常见的误报，例如推送到您自己的仓库。接下来添加受信域和云存储桶。当出现阻止时填写其余部分。

173 175

174<h2 id="generate-environment-entries">176<h2 id="generate-environment-entries">

175 使用 `/auto-mode-setup` 生成环境条目177 使用 `/auto-mode-setup` 生成环境条目

301 通过分类器路由所有 shell 命令303 通过分类器路由所有 shell 命令

302</h2>304</h2>

303 305

304默认情况下，narrow Bash 和 PowerShell 允许规则（如 `Bash(npm test)`）在自动模式下保持有效，Claude Code 在分类器运行之前解析它们。Claude Code 仅暂停授予任意代码执行权限的广泛规则，例如 `Bash(*)` 或通配符解释器，以及每个命名 [`Monitor`](/docs/zh-CN/tools-reference#monitor-tool) 的规则，因为 Monitor 命令通过 shell 运行。这意味着 narrow 规则仍然可以让分类器看不到的破坏性参数通过，例如规则前缀未预期的脚本路径或标志。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 规则仍然可以让分类器看不到的破坏性参数通过，例如规则前缀未预期的脚本路径或标志。

305 307

306将 `autoMode.classifyAllShell` 设置为 `true`，以在自动模式处于活动状态时暂停每个 Bash 和 PowerShell 允许规则，使分类器评估每个 shell 命令，无论您的允许列表如何。308将 `autoMode.classifyAllShell` 设置为 `true`，以在自动模式处于活动状态时暂停每个 Bash 和 PowerShell 允许规则，使分类器评估每个 shell 命令，无论您的允许列表如何。

307 309

channels-reference.md +3 −3

Details

66 66

67<Steps>67<Steps>

68 <Step title="创建项目">68 <Step title="创建项目">

~~69 后面此页面上的权限中继示例直接导入 `zod`，因此它与 MCP SDK 一起安装。创建一个新目录并安装两者：~~69 [permission relay](#relay-permission-prompts) 示例直接导入 `zod`，因此它与 MCP SDK 一起安装。创建一个新目录并安装两者：

70 70

71 ```bash theme={null}71 ```bash theme={null}

72 mkdir webhook-channel && cd webhook-channel72 mkdir webhook-channel && cd webhook-channel

116 })116 })

117 ```117 ```

118 118

119 该文件按顺序执行三项操作：119 该文件按顺序配置服务器、连接和启动 HTTP 侦听器：

120 120

121 * **服务器配置**：使用 `claude/channel` 在其能力中创建 MCP 服务器，这是告诉 Claude Code 这是一个频道的原因。Claude Code 在服务器连接时将 [`instructions`](#server-options) 字符串传递给 Claude 作为上下文：告诉 Claude 期望什么事件、是否回复以及如果应该回复，如何路由回复。121 * **服务器配置**：使用 `claude/channel` 在其能力中创建 MCP 服务器，这是告诉 Claude Code 这是一个频道的原因。Claude Code 在服务器连接时将 [`instructions`](#server-options) 字符串传递给 Claude 作为上下文：告诉 Claude 期望什么事件、是否回复以及如果应该回复，如何路由回复。

122 * **Stdio 连接**：通过 stdin/stdout 连接到 Claude Code。这对任何 [MCP 服务器](https://modelcontextprotocol.io/docs/concepts/transports#standard-io) 都是标准的。122 * **Stdio 连接**：通过 stdin/stdout 连接到 Claude Code。这对任何 [MCP 服务器](https://modelcontextprotocol.io/docs/concepts/transports#standard-io) 都是标准的。

509 509

510掩盖不改变谁接收字段。无论什么保持未掩盖都仅进入您使用 `--channels` 或开发标志选择加入的服务器。除非您控制客户端队列，否则将两个字段视为不受信任。510掩盖不改变谁接收字段。无论什么保持未掩盖都仅进入您使用 `--channels` 或开发标志选择加入的服务器。除非您控制客户端队列，否则将两个字段视为不受信任。

511 511

512您的服务器发送回的判决是 `notifications/claude/channel/permission`，有两个字段：`request_id` 回显上面的 ID，`behavior` 设置为 `'allow'` 或 `'deny'`。允许让工具调用继续；拒绝拒绝它，与在本地对话中回答"否"相同。两个判决都不影响未来的调用。512您的服务器发送回的判决是 `notifications/claude/channel/permission`，有两个字段：`request_id` 回显上面的 ID，`behavior` 设置为 `'allow'` 或 `'deny'`。允许让工具调用继续；拒绝拒绝它。两个判决都不影响未来的调用。

513 513

514<h3 id="add-relay-to-a-chat-bridge">514<h3 id="add-relay-to-a-chat-bridge">

515 向聊天桥接添加中继515 向聊天桥接添加中继

checkpointing.md +1 −1

Details

85 Bash 命令更改未跟踪85 Bash 命令更改未跟踪

86</h3>86</h3>

87 87

~~88Checkpointing 不跟踪由 bash 命令修改的文件。例如，如果 Claude Code 运行：~~88Checkpointing 不跟踪由 Bash 命令修改的文件。例如，如果 Claude Code 运行：

89 89

90```bash theme={null}90```bash theme={null}

91rm file.txt91rm file.txt

claude-apps-gateway.md +61 −6

Details

60本快速入门演示最小路径：在您的 IdP 中注册 OAuth 客户端，编写 `gateway.yaml`，使用 Docker Compose 运行网关和 Postgres，并端到端验证登录。它使用 Amazon Bedrock 上游；Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Anthropic API 同样受支持，只需交换[配置参考](/docs/zh-CN/claude-apps-gateway-config#upstreams)中所示的 `upstreams` 块。最后，您有一个开发人员可以 `/login` 的网关。60本快速入门演示最小路径：在您的 IdP 中注册 OAuth 客户端，编写 `gateway.yaml`，使用 Docker Compose 运行网关和 Postgres，并端到端验证登录。它使用 Amazon Bedrock 上游；Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry 和 Anthropic API 同样受支持，只需交换[配置参考](/docs/zh-CN/claude-apps-gateway-config#upstreams)中所示的 `upstreams` 块。最后，您有一个开发人员可以 `/login` 的网关。

61 61

62<Note>62<Note>

63 **在您的私有网络上部署。** Claude Code 仅连接到地址为私有的网关。这是一个安全防护，因为受信任的网关可以推送在开发人员机器上运行命令的设置。将网关放在内部负载均衡器或 VPN 后面，并给它一个仅解析为私有 IP 的主机名。63 **在您的私有网络上部署。** Claude Code 仅连接到地址为私有的网关。这是一个安全防护，因为受信任的网关可以推送在开发人员机器上运行命令的设置。将网关放在内部负载均衡器或 VPN 后面，并给它一个仅解析为私有 IP 的主机名。如果您的内部网络使用您的组织拥有的公共 IPv4 空间编号，请参阅[允许网关在您拥有的公共地址空间上](#allow-a-gateway-on-public-address-space-you-own)。

64</Note>64</Note>

65 65

66<h3 id="prerequisites">66<h3 id="prerequisites">

70在开始之前，请准备好以下内容：70在开始之前，请准备好以下内容：

71 71

72| 您需要 | 详情 |72| 您需要 | 详情 |

73| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |73| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

74| Claude Code v2.1.195 或更高版本 | `claude gateway` 子命令和网关登录流在 v2.1.195 中发布。早期的公开版本不包含它们。运行网关服务器的机器和每个开发人员的机器都必须是 v2.1.195 或更高版本；运行 `claude update` 获取最新版本。[Claude Platform on AWS 上游](/docs/zh-CN/claude-apps-gateway-config#claude-platform-on-aws)在网关服务器上需要 Claude Code v2.1.198 或更高版本。 |74| Claude Code v2.1.195 或更高版本 | `claude gateway` 子命令和网关登录流在 v2.1.195 中发布。早期的公开版本不包含它们。运行网关服务器的机器和每个开发人员的机器都必须是 v2.1.195 或更高版本；运行 `claude update` 获取最新版本。[Claude Platform on AWS 上游](/docs/zh-CN/claude-apps-gateway-config#claude-platform-on-aws)在网关服务器上需要 Claude Code v2.1.198 或更高版本。 |

75| OpenID Connect (OIDC) 身份提供商 | Okta、Microsoft Entra ID、Google Workspace、Keycloak 或 Dex，或任何其他符合 OIDC 的 IdP，如 PingFederate。网关针对它运行标准 OIDC 发现和授权代码流。不支持 SAML 和 LDAP。 |75| OpenID Connect (OIDC) 身份提供商 | Okta、Microsoft Entra ID、Google Workspace、Keycloak 或 Dex，或任何其他符合 OIDC 的 IdP，如 PingFederate。网关针对它运行标准 OIDC 发现和授权代码流。不支持 SAML 和 LDAP。 |

76| PostgreSQL 14 或更高版本 | 支持设备登录流，其中浏览器回调写入，轮询 CLI 读取，加上速率限制计数器。任何托管 Postgres 都可以，包括最小层级。在没有配置支出限制的情况下，网关存储几 KB 的短期身份验证状态；使用[支出限制](/docs/zh-CN/claude-apps-gateway-spend-limits)，它还保存应备份的持久支出、审计和身份表。建议通过 `?sslmode=require` 使用 TLS。 |76| PostgreSQL 14 或更高版本 | 支持设备登录流，其中浏览器回调写入，轮询 CLI 读取，加上速率限制计数器。任何托管 Postgres 都可以，包括最小层级。在没有配置支出限制的情况下，网关存储几 KB 的短期身份验证状态；使用[支出限制](/docs/zh-CN/claude-apps-gateway-spend-limits)，它还保存应备份的持久支出、审计和身份表。建议通过 `?sslmode=require` 使用 TLS。 |

77| 模型上游 | Amazon Bedrock 凭证、Claude Platform on AWS 凭证、Google Cloud 凭证、Microsoft Foundry 资源或 Anthropic API 密钥。支持多个上游和故障转移。 |77| 模型上游 | Amazon Bedrock 凭证、Claude Platform on AWS 凭证、Google Cloud 凭证、Microsoft Foundry 资源或 Anthropic API 密钥。支持多个上游和故障转移。 |

78| HTTPS | 网关必须可从开发人员笔记本电脑和用于登录的任何浏览器通过 `https://` 访问；网关在同一侦听器上提供设备验证页面。通过 `listen.tls` 提供 TLS 证书，或在 TLS 终止入口后运行并设置 `listen.public_url` 为外部源，两种情况都是如此。纯 `http://` 源仅在网关主机是环回时接受：`localhost`、`127.0.0.1` 或 `::1`。 |78| HTTPS | 网关必须可从开发人员笔记本电脑和用于登录的任何浏览器通过 `https://` 访问；网关在同一侦听器上提供设备验证页面。通过 `listen.tls` 提供 TLS 证书，或在 TLS 终止入口后运行并设置 `listen.public_url` 为外部源，两种情况都是如此。纯 `http://` 源仅在网关主机是环回时接受：`localhost`、`127.0.0.1` 或 `::1`。 |

79| 私有网络地址 | 在 `/login` 处，Claude Code 要求网关的主机名或 IP 地址仅解析为私有地址：RFC 1918、链路本地、CGNAT `100.64.0.0/10`、IPv6 ULA `fc00::/7` 或环回。对于您托管的网关，任何公共地址都被拒绝；请参阅部署指南中的[威胁模型](/docs/zh-CN/claude-apps-gateway-deploy#threat-model-summary)。检查在每个解析的 IP 上运行，因此如果名称解析到的任何地址是公共的，`/login` 会拒绝该 URL。如果开发人员机器通过公司代理路由 HTTPS，登录还要求代理主机解析为私有地址；如果不是，将网关主机添加到 `NO_PROXY`，以便 CLI 直接连接。 |79| 私有网络地址 | 在 `/login` 处，Claude Code 要求网关的主机名或 IP 地址仅解析为私有地址：RFC 1918、链路本地、CGNAT `100.64.0.0/10`、IPv6 ULA `fc00::/7` 或环回。对于您托管的网关，任何公共地址都被拒绝；请参阅部署指南中的[威胁模型](/docs/zh-CN/claude-apps-gateway-deploy#threat-model-summary)。如果开发人员机器通过公司代理路由 HTTPS，登录还要求代理主机解析为私有地址；如果不是，将网关主机添加到 `NO_PROXY`，以便 CLI 直接连接。如果您的内部网络使用您的组织拥有的公共 IPv4 空间编号，[声明这些块](#allow-a-gateway-on-public-address-space-you-own)，以便 `/login` 接受那里的网关。 |

80| Linux 运行时 | 网关服务器仅在本机 Linux 二进制文件上运行。macOS 适用于本地开发。Windows 不支持作为服务器平台。 |80| Linux 运行时 | 网关服务器仅在本机 Linux 二进制文件上运行。macOS 适用于本地开发。Windows 不支持作为服务器平台。 |

81 81

82<h3 id="steps">82<h3 id="steps">

183 [gateway] 2026-06-10T17:03:21.512Z info claude gateway listening on http://0.0.0.0:8080183 [gateway] 2026-06-10T17:03:21.512Z info claude gateway listening on http://0.0.0.0:8080

184 ```184 ```

185 185

186 网关还会记录一个警告，`access_control.allow_cidrs` 为空。这在这里是预期的，因为在您设置允许列表之前，没有任何东西限制网关提供的客户端地址。[`access_control` 参考](/docs/zh-CN/claude-apps-gateway-config#http-tuning)有推荐的范围。

187

186 如果启动在 `claude gateway listening on` 行之前退出，stderr 的最后一行命名问题：188 如果启动在 `claude gateway listening on` 行之前退出，stderr 的最后一行命名问题：

187 189

188 * 无法访问的 Postgres190 * 无法访问的 Postgres

289 291

290开发人员无法手动设置此项。登录选择器中没有网关选项，`forceLoginGatewayUrl` 在开发人员自己的设置文件中被忽略。单独的 `forceLoginMethod`，没有 URL，将开发人员留在"联系您的 IT 管理员"消息处。登录密钥属于您推送到机器的文件中，而不是网关的 `managed.policies[].cli` 块中，该块仅到达已连接的客户端。292开发人员无法手动设置此项。登录选择器中没有网关选项，`forceLoginGatewayUrl` 在开发人员自己的设置文件中被忽略。单独的 `forceLoginMethod`，没有 URL，将开发人员留在"联系您的 IT 管理员"消息处。登录密钥属于您推送到机器的文件中，而不是网关的 `managed.policies[].cli` 块中，该块仅到达已连接的客户端。

291 293

294<h3 id="allow-a-gateway-on-public-address-space-you-own">

295 在您拥有的公共地址空间上允许网关

296</h3>

297

298某些组织从他们拥有的公共 IPv4 块对其内部网络进行编号，例如运营商自己的地址空间或遗留的 `/8`，因此他们的网关不能有私有地址。在 `gatewayInternalNetworks` 托管设置中列出这些块。当开发人员的机器从同一块内的地址连接到它时，`/login` 然后接受列出块内的网关。这需要开发人员机器上的 Claude Code v2.1.268 或更高版本；早期版本忽略该密钥并应用私有地址规则。

299

300<Warning>

301 `gatewayInternalNetworks` 用于恰好从公共地址空间编号的内部网络。它不会使将网关暴露到互联网变得安全：受信任的网关可以推送在开发人员机器上运行命令的设置。

302

303 使用您的防火墙或负载均衡器规则将网关保持在网络外部无法访问。将网关的 [`access_control.allow_cidrs`](/docs/zh-CN/claude-apps-gateway-config#http-tuning) 设置为您在此处声明的相同块，以便网关本身拒绝来自其他任何地方的客户端。在负载均衡器或入口后面，也将 `listen.trusted_proxies` 设置为该前端，因为网关否则会针对前端自己的地址而不是开发人员的地址匹配 `allow_cidrs`。

304</Warning>

305

306将密钥添加到与登录密钥相同的托管设置源：托管设置文件、MDM 配置文件或注册表策略。Claude Code 在用户、项目和服务器托管设置中忽略它。

307

308此示例声明一个块。将 `203.0.113.0/24` 替换为您自己的块。它是文档范围，Claude Code 拒绝这些。

309

310```json theme={null}

311{

312 "gatewayInternalNetworks": ["203.0.113.0/24"]

313}

314```

315

316Claude Code 在 `/login` 处验证列表，然后再联系任何网关：

317

318* 每个条目是一个 IPv4 块，写成其第一个地址和从 `/8` 到 `/32` 的前缀。

319* 列表最多包含四个块，没有两个重叠。

320* 没有块与私有地址空间重叠：`10.0.0.0/8`、`172.16.0.0/12`、`192.168.0.0/16`、`127.0.0.0/8`、`169.254.0.0/16` 和 `100.64.0.0/10`。`/login` 已经在没有此密钥的情况下接受那里的网关。

321* 没有块与从不是组织网络的空间重叠：`198.18.0.0/15` 和 `192.0.0.0/24`，VPN 和 NAT64 客户端将其作为本地地址；文档范围 `192.0.2.0/24`、`198.51.100.0/24` 和 `203.0.113.0/24`；以及保留范围 `0.0.0.0/8`、`192.88.99.0/24` 和多播 `224.0.0.0/4`。您可以声明 `240.0.0.0/4` 内的块，某些大型网络将其用作内部单播空间。

322

323来自 `managed-settings.json` 及其 `managed-settings.d/` 插入文件的块合并为一个列表，这些限制适用于合并列表。要缩小块，请替换其条目而不是在插入中添加第二个重叠的；`/login` 拒绝重叠。

324

325如果条目违反规则，或值不是字符串列表，Claude Code 拒绝该机器上的每个新网关登录并在消息中命名问题。登录到私有地址上的网关也失败，现有登录继续工作。在部署前在一台机器上尝试该值。Claude Code 还在[它报告的无效托管设置](/docs/zh-CN/managed-settings#keys-that-fail-closed)中列出错误类型的值。

326

327使用有效列表，`/login` 对地址在列出块内的网关应用三个检查：

328

329* 网关主机名解析到的每个地址都在该块内。Claude Code 拒绝也在块外有记录的名称，包括私有和 IPv6 地址。

330* 开发人员的机器从同一块内连接。Claude Code 拒绝 NAT 后面、容器或 WSL2 内或 VPN 上的机器，其地址池位于块外，并命名机器连接的地址。

331* 连接是直接的。如果 `HTTPS_PROXY` 适用于网关主机，`/login` 拒绝并命名要添加的 `NO_PROXY` 条目。

332

333当所有三个通过时，[信任提示](#connect-developers)添加一行命名机器的地址、网关的地址和包含两者的声明块。

334

335该密钥对其他网关不改变任何内容：登录到私有地址上的网关像以前一样工作，登录到每个列出块外的公共地址上的网关像以前一样被拒绝。

336

337声明的块缩小了谁可以登录但不证明机器在哪里，因此仅声明您的组织控制的地址空间。与其他租户共享的块，例如云提供商的公共范围，让其中的任何人通过相同的检查。

338

292<h3 id="deliver-policy-to-claude-desktop-sessions">339<h3 id="deliver-policy-to-claude-desktop-sessions">

293 将策略传递给 Claude Desktop 会话340 将策略传递给 Claude Desktop 会话

294</h3>341</h3>

379 跨源的锁行为426 跨源的锁行为

380</h4>427</h4>

381 428

382设置一个锁不会限制其他锁；每个密钥都在[设置参考](/docs/zh-CN/settings-reference#all-settings)中记录。从赢家下方的管理员源，两个沙箱锁仍然适用，`allowManagedPermissionRulesOnly` 仍然阻止父提供的允许规则和 `additionalDirectories`。hooks 和 MCP 服务器锁，以及 `allowManagedPermissionRulesOnly` 对开发人员自己规则的影响，默认需要赢家源；在[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)中的 `managedSourcesBehavior` 合并选择加入下，Claude Code 应用任何源为每个锁设置的最严格值。在 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 舰队上，锁仅从助手的输出读取。429设置一个锁不会限制其他锁；每个密钥都在[设置参考](/docs/zh-CN/settings-reference#all-settings)中记录。

430

431从赢家下方的管理员源，两个沙箱锁仍然适用，`allowManagedPermissionRulesOnly` 仍然阻止父提供的允许规则和 `additionalDirectories`。在 Claude Code v2.1.273 或更高版本上，MCP 服务器锁也从赢家下方的源应用，当它打开时，托管 `allowedMcpServers` 列表来自设置一个的最高优先级管理员源。

432

433hooks 锁和 `allowManagedPermissionRulesOnly` 对开发人员自己规则的影响默认需要赢家源；在[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)中的 `managedSourcesBehavior` 合并选择加入下，Claude Code 应用任何源为每个锁设置的最严格值。在 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 舰队上，锁仅从助手的输出读取。

434

435每个锁使 Claude Code 忽略开发人员对该设置的自己条目，因此在锁旁边包含您组织的允许列表：

383 436

384每个锁使 Claude Code 忽略开发人员对该设置的自己条目，因此在锁旁边包含您组织的允许列表。使用空托管域列表锁定网络域会阻止所有沙箱出站流量，使用没有托管或父提供的 `allowedMcpServers` 的 MCP 服务器锁会加载 `deniedMcpServers` 不阻止的每个服务器。`allowRead` 条目仅重新允许 `denyRead` 区域内的路径，因此将它们与托管 `denyRead` 配对。437* **网络域**：使用空托管域列表锁定会阻止所有沙箱出站流量。

438* **MCP 服务器**：使用任何管理员源或父提供的设置中都没有 `allowedMcpServers` 的锁会加载 `deniedMcpServers` 不阻止的每个服务器。

439* **读取路径**：`allowRead` 条目仅重新允许 `denyRead` 区域内的路径，因此将它们与托管 `denyRead` 配对。

385 440

386<h4 id="settings-the-locks-don’t-cover">441<h4 id="settings-the-locks-don’t-cover">

387 锁不涵盖的设置442 锁不涵盖的设置

388</h4>443</h4>

389 444

390即使设置了所有五个锁，四个父提供的设置也会通过过滤器。在默认的先赢设置下，阻止父设置的管理员值是最高优先级管理员源中的值。在 `managedSourcesBehavior` 合并选择加入下，[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明哪个源的值改为适用。445即使设置了所有五个锁，四个父提供的设置也会通过过滤器。在默认的先赢设置下，阻止父设置的管理员值是最高优先级管理员源中的值，除了 `allowedMcpServers` 当[MCP 服务器锁](#lock-behavior-across-sources)打开时。在 `managedSourcesBehavior` 合并选择加入下，[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明哪个源的值改为适用。

391 446

392* **`forceLoginOrgUUID`**：当最高优先级管理员源未设置组织 UUID 时，Claude Code 尊重父提供的值。网关登录不检查此密钥，因此它仅对也使用第一方 Anthropic 登录的舰队重要。最高优先级管理员源中的组织 UUID 阻止父的值，是 Claude Code 强制执行的值，因此在那里设置 `forceLoginOrgUUID`。447* **`forceLoginOrgUUID`**：当最高优先级管理员源未设置组织 UUID 时，Claude Code 尊重父提供的值。网关登录不检查此密钥，因此它仅对也使用第一方 Anthropic 登录的舰队重要。最高优先级管理员源中的组织 UUID 阻止父的值，是 Claude Code 强制执行的值，因此在那里设置 `forceLoginOrgUUID`。

393* **`allowedMcpServers`**：当最高优先级管理员源未设置允许列表时，Claude Code 尊重父提供的允许列表，`allowManagedMcpServersOnly` 不阻止它，因为锁强制执行任何赢家列表作为托管值，包括当最高优先级管理员源未设置时的父提供列表。最高优先级管理员源中的列表阻止父的并是 Claude Code 强制执行的列表，因此在那里设置 `allowedMcpServers`，在锁旁边。在 v2.1.223 之前，任何管理员源中任一密钥的值都阻止父的。448* **`allowedMcpServers`**：当最高优先级管理员源未设置允许列表时，Claude Code 尊重父提供的允许列表，`allowManagedMcpServersOnly` 不阻止它，因为锁强制执行任何赢家列表作为托管值，包括当最高优先级管理员源未设置时的父提供列表。最高优先级管理员源中的列表阻止父的并是 Claude Code 强制执行的列表，因此在那里设置 `allowedMcpServers`，在锁旁边。在 v2.1.223 之前，任何管理员源中任一密钥的值都阻止父的。

claude-apps-gateway-config.md +174 −143

Details

435 `admin`435 `admin`

436</h3>436</h3>

437 437

438可选。启用 `/v1/organizations/spend_limits`，它镜像 Anthropic 的公共 Admin API，以及 `/v1/messages` 上的每开发者支出强制。有关如何设置和强制执行上限的信息，请参阅[支出限制](/docs/zh-CN/claude-apps-gateway-spend-limits)；本部分涵盖打开该功能和调整它的 `gateway.yaml` 键。438可选。启用 `/v1/organizations/spend_limits`，它镜像 Anthropic 的公共 Admin API，以及在 `/v1/messages` 上的每个开发者支出强制执行。请参阅[支出限制](/docs/zh-CN/claude-apps-gateway-spend-limits)了解如何设置和强制执行上限；本部分涵盖启用该功能并调整它的 `gateway.yaml` 键。

439 439

440```yaml theme={null}440```yaml theme={null}

441admin:441admin:

442 # 管理员端点的命名静态 API 密钥，作为 x-api-key 发送。442 # Named static API keys for the admin endpoints, sent as x-api-key.

443 # id 在审计日志中显示为 admin-key:<id>，因此每个密钥都是443 # The id appears in the audit log as admin-key:<id> so each key is

444 # 可归因的。用于轮换的数组：添加新密钥，滚动客户端，444 # attributable. Array for rotation: add the new key, roll clients,

445 # 删除旧密钥。445 # remove the old.

446 write_keys:446 write_keys:

447 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }447 - { id: terraform, key: "${GATEWAY_ADMIN_WRITE_KEY_TF}" }

448 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }448 - { id: ci, key: "${GATEWAY_ADMIN_WRITE_KEY_CI}" }

449 read_keys:449 read_keys:

450 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }450 - { id: reporting, key: "${GATEWAY_ADMIN_READ_KEY}" }

451 # 通过普通网关 JWT（无 API 密钥）授予完全管理员的 IdP 组。451 # IdP groups granted full admin via the normal gateway JWT (no API key).

452 admin_groups: [platform-finops]452 admin_groups: [platform-finops]

453 blocked_message: request an increase at https://go.example.com/claude-limits453 blocked_message: request an increase at https://go.example.com/claude-limits

454```454```

455 455

456| 字段 | 必需 | 描述 |456| 字段 | 必需 | 描述 |

457| ------------------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |457| ------------------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

458| `write_keys` | 否 | `{id, key}` 的数组。与这些之一匹配的 `x-api-key` 可以列出、设置和删除支出限制。密钥值必须至少 32 个字符；`id` 必须在 `read_keys` 和 `write_keys` 中唯一。 |458| `write_keys` | 否 | `{id, key}` 的数组。与其中一个匹配的 `x-api-key` 可以列出、设置和删除支出限制。键值必须至少 32 个字符；`id` 在 `read_keys` 和 `write_keys` 中必须唯一。 |

459| `read_keys` | 否 | `{id, key}` 的数组。只读：每个 `GET` 端点，包括列出上限、按 ID 获取一个，以及读取 [`/effective`](/docs/zh-CN/claude-apps-gateway-spend-limits#%2Feffective) 和 [`/audit`](/docs/zh-CN/claude-apps-gateway-spend-limits#%2Faudit)。 |459| `read_keys` | 否 | `{id, key}` 的数组。只读：每个 `GET` 端点，包括列出上限、按 ID 获取一个，以及读取 [`/effective`](/docs/zh-CN/claude-apps-gateway-spend-limits#%2Feffective) 和 [`/audit`](/docs/zh-CN/claude-apps-gateway-spend-limits#%2Faudit)。 |

460| `admin_groups` | 否 | IdP 组名称。其 `groups` 声明包括其中之一的网关 JWT 具有完全管理员访问权限，读和写，并审计为 `oidc:<sub>`。用于人类管理员；为机器使用 API 密钥。此列表中的空条目在启动时停止网关。请参阅[在启动时停止网关的匹配器值](#matcher-values-that-stop-the-gateway-at-boot)。 |460| `admin_groups` | 否 | IdP 组名称。网关 JWT 的 `groups` 声明包含其中之一的具有完全管理员访问权限（读和写），并审计为 `oidc:<sub>`。将此用于人类管理员；将 API 密钥用于机器。此列表中的空条目在启动时停止网关。请参阅[在启动时停止网关的匹配器值](#matcher-values-that-stop-the-gateway-at-boot)。 |

461| `blocked_message` | 否 | 逐字附加到被阻止的开发者看到的 `429 billing_error`。写出整个指令，如 URL 或 Slack 频道。未设置时，网关仅发送默认消息。请参阅[强制执行如何工作](/docs/zh-CN/claude-apps-gateway-spend-limits#how-enforcement-works)。 |461| `blocked_message` | 否 | 逐字附加到被阻止的开发者看到的 `429 billing_error`。写出完整的说明，例如 URL 或 Slack 频道。未设置时，网关仅发送默认消息。请参阅[强制执行如何工作](/docs/zh-CN/claude-apps-gateway-spend-limits#how-enforcement-works)。 |

462| `audit_retention_days` | 否 | 默认 `365`。较旧的 `admin_audit` 行被清除。 |462| `audit_retention_days` | 否 | 默认 `365`。较旧的 `admin_audit` 行被清除。 |

463| `spend_retention_months` | 否 | 默认 `13`。`spend` 计数器行早于此被清除。默认值保留完整年份加当前部分月份用于年度比较报告。 |463| `spend_retention_months` | 否 | 默认 `13`。早于此的 `spend` 计数器行被清除。默认值保留整整一年加当前部分月份以进行年度对比报告。 |

464| `identity_retention_days` | 否 | 默认 `90`。`principal_emails` 行的最后看到 TTL，其中保存每个开发者的电子邮件、显示名称和组 (PII)。故意比支出保留更短，因此取消配置的身份在其匿名支出计数器保留时老化。 |464| `identity_retention_days` | 否 | 默认 `90`。`principal_emails` 行的最后一次看到 TTL，其中包含每个开发者的电子邮件、显示名称和组（PII）。故意比支出保留期短，以便已取消配置的身份在其匿名支出计数器保留时过期。 |

465| `group_limit_mode` | 否 | `min`（默认）或 `max`。当开发者在具有上限的多个组中时，`min` 强制执行最严格的，`max` 强制执行最宽松的。由强制执行和 `/effective` 使用。 |465| `group_limit_mode` | 否 | `min`（默认）或 `max`。当开发者在多个具有上限的组中时，`min` 强制执行最严格的，`max` 强制执行最宽松的。由强制执行和 `/effective` 使用。 |

466 466

467<h3 id="enforcement">467<h3 id="enforcement">

468 `enforcement`468 `enforcement`

471`enforcement` 块控制当存储不可用时支出限制检查的行为。471`enforcement` 块控制当存储不可用时支出限制检查的行为。

472 472

473| 字段 | 必需 | 描述 |473| 字段 | 必需 | 描述 |

474| ---------------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |474| ---------------------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

475| `fail_closed_on_error` | 否 | 默认 `false`。支出强制在 Postgres 中断时故障开放，因此推理保持运行。设置 `true` 以故障关闭：超额开发者被阻止，但如果存储无法访问，每个人都被阻止。需要 [`admin:`](#admin) 块：支出强制仅在配置 `admin` 时运行，如果你在没有 `admin` 块的情况下设置此 `true`，网关拒绝启动。 |475| `fail_closed_on_error` | 否 | 默认 `false`。支出强制执行在 Postgres 中断时失败打开，因此推理保持运行。设置 `true` 以失败关闭：超出上限的开发者被阻止，但如果存储无法访问，所有人也被阻止。需要 [`admin:`](#admin) 块：支出强制执行仅在配置 `admin` 时运行，如果在没有 `admin` 块的情况下设置此 `true`，网关拒绝启动。 |

476 476

477<h3 id="pricing">477<h3 id="pricing">

478 `pricing`478 `pricing`

479</h3>479</h3>

480 480

481`pricing` 块告诉支出计量器要收费什么而不是美元列表价格，因此上限和 [`/effective`](/docs/zh-CN/claude-apps-gateway-spend-limits#%2Feffective) 反映你的合同费率。金额保持为美元并保持为估计值，而不是发票。两个先决条件：481`pricing` 块告诉支出计量器收费而不是美元列表价格，因此上限和 [`/effective`](/docs/zh-CN/claude-apps-gateway-spend-limits#%2Feffective) 反映您的合同费率。金额保持为美元并保持为估计值，而不是发票。两个先决条件：

482 482

483* 网关服务器上的 Claude Code v2.1.227 或更高版本。早期版本在启动时拒绝未知密钥。483* 网关服务器上的 Claude Code v2.1.227 或更高版本。早期版本在启动时拒绝未知键。

484* [`admin:`](#admin) 块或在 v2.1.268 或更高版本中，一个 [`managed:`](#managed) 块，至少有一个策略。网关拒绝在设置 `pricing` 且没有任何块的情况下启动，因为没有东西会读取它。484* [`admin:`](#admin) 块或在 v2.1.268 或更高版本中，至少有一个策略的 [`managed:`](#managed) 块。网关拒绝在设置 `pricing` 且没有任何块的情况下启动，因为没有任何东西会读取它。

485 485

486```yaml theme={null}486```yaml theme={null}

487pricing:487pricing:

496```496```

497 497

498| 字段 | 必需 | 描述 |498| 字段 | 必需 | 描述 |

499| ------------ | -- | ---------------------------------------------------------------------------------------------------------- |499| ------------ | -- | --------------------------------------------------------------------------------------------------------- |

500| `multiplier` | 否 | 默认 `1`。计量器将每个计量金额乘以此值，无论是列表价格还是覆盖，因此 `0.85` 按价格的 85% 计费。必须大于 0 且最多为 1。 |500| `multiplier` | 否 | 默认 `1`。计量器将每个计量金额乘以此值，无论是列表价格还是覆盖，因此 `0.85` 按价格的 85% 计费。必须大于 0 且最多 10，值大于 1 是[标记价格上升](#mark-prices-up)。 |

501| `overrides` | 否 | `{upstream, model, input, output, cache_read, cache_write}` 的行，单位为美元每百万令牌。所有四个费率都是必需的。每个必须大于 0 且最多为 10000。 |501| `overrides` | 否 | `{upstream, model, input, output, cache_read, cache_write}` 的行，单位为美元每百万令牌。所有四个费率都是必需的。每个必须大于 0 且最多 10000。 |

502 502

503计量器如何匹配覆盖行：503计量器如何匹配覆盖行：

504 504

505* 一行替换列表价格，用于 `upstream`（一个 [`upstreams[].name`](#upstreams)）为 `model` 提供的请求。这包括更高的[快速模式](/docs/zh-CN/fast-mode#understand-the-cost-tradeoff)费率，因此快速和标准请求按相同的四个费率计量。505* 一行替换 `upstream`（一个 [`upstreams[].name`](#upstreams)）为 `model` 提供的请求的列表价格。这包括更高的[快速模式](/docs/zh-CN/fast-mode#understand-the-cost-tradeoff)费率，因此快速和标准请求以相同的四个费率计量。

506* 内置 ID（如 `claude-sonnet-4-6`）（匹配方式如 [`models[].id`](#models)）涵盖计量器定价为该模型的每个日期形式、区域 Amazon Bedrock 形式或 Google Cloud 的 Agent Platform 形式。任何其他字符串（如别名或推理配置文件 ARN）匹配客户端发送的 ID 或上游发送的字符串，不区分大小写。506* 内置 ID（如 `claude-sonnet-4-6`）（匹配方式如 [`models[].id`](#models)）涵盖计量器定价为该模型的每个日期形式、区域 Amazon Bedrock 形式或 Google Cloud 的 Agent Platform 形式。任何其他字符串（如别名或推理配置文件 ARN）匹配客户端发送的 ID 或上游发送的字符串，不区分大小写。

507* 其中行重叠，计量器选择最具体的行而不是第一行：一行其 `model` 是上游发送的确切模型字符串，然后是匹配客户端发送的确切 ID 的行，然后是命名内置模型的行。507* 其中行重叠时，计量器选择最具体的行而不是第一行：一行其 `model` 是上游发送的确切模型字符串，然后是匹配客户端发送的确切 ID 的行，然后是命名内置模型的行。

508* 未知上游名称在启动时失败，一个上游的两行命名相同模型也是如此，包括一个内置模型的两个拼写。网关在启动时警告关于没有可请求模型可以使用的行。508* 未知的上游名称导致启动失败，一个上游的两行命名相同模型也是如此，包括一个内置模型的两个拼写。网关在启动时警告没有可请求模型可以使用的行。

509* Web 搜索请求保持在 \$0.01 列表价格；乘数仍然适用于它们。509* Web 搜索请求保持在 \$0.01 列表价格；乘数仍然适用于它们。

510 510

511对于按地区费率，为每个地区提供自己的命名上游和每个上游一行。511对于按地区费率，为每个地区提供自己的命名上游和每个上游一行。

512 512

513<h4 id="mark-prices-up">

514 标记价格上升

515</h4>

516

517使用网关服务器上的 v2.1.271 或更高版本，您可以将 `multiplier` 设置为 1 以上，最多 10，以计量超过提供商收费的金额，例如内部退款费率。此示例以价格的 120% 计量每个请求：

518

519```yaml theme={null}

520pricing:

521 multiplier: 1.2

522```

523

524使用 [`admin:`](#admin) 块，标记也适用于支出限制。计量器计算价格的 120%，因此开发者更快达到其上限。网关在启动时记录警告，说明这一点。

525

526乘数不改变上游提供商对请求的收费。

527

528如果网关也[将费率发送给已登录的客户端](#send-the-rates-to-signed-in-clients)，开发者需要 Claude Code v2.1.271 或更高版本才能看到标记。早期客户端忽略 `multiplier` 大于 1 并显示不带它的成本。

529

530早于 v2.1.271 的网关服务器拒绝在设置 `multiplier` 大于 1 时启动。

531

513<h4 id="send-the-rates-to-signed-in-clients">532<h4 id="send-the-rates-to-signed-in-clients">

514 将费率发送给已登录的客户端533 将费率发送给已登录的客户端

515</h4>534</h4>

516 535

517在网关服务器上使用 v2.1.268 或更高版本，网关还将 `pricing` 中的费率放入它提供的 [`managed`](#managed) 策略中，作为 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing) 托管设置。由策略匹配的开发者然后在 `/usage`、状态行和 OpenTelemetry 中看到第一个为每个模型 ID 提供服务的上游的 `pricing` 费率。与任何策略不匹配的开发者不接收托管设置，因此他们的数字保持在列表价格。客户端在 Claude Code v2.1.242 或更高版本中应用该设置。536使用网关服务器上的 v2.1.268 或更高版本，网关也将 `pricing` 中的费率放入它提供的 [`managed`](#managed) 策略中，作为 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing) 托管设置。由策略匹配的开发者然后在 `/usage`、状态行和 OpenTelemetry 中看到每个模型 ID 的第一个上游的 `pricing` 费率。与任何策略不匹配的开发者不接收托管设置，因此他们的数字保持在列表价格。客户端在 Claude Code v2.1.242 或更高版本中应用设置。

518 537

519* 网关添加的内容：除非策略的 `cli` 块已经设置 `modelPricing`，网关添加 `multiplier` 和，对于客户端可以请求的每个模型 ID，第一个为该 ID 提供服务的上游的覆盖行。仅故障转移上游收费的费率保持在网关上。538* 网关添加的内容：除非策略的 `cli` 块已经设置 `modelPricing`，网关添加 `multiplier` 和，对于客户端可以请求的每个模型 ID，提供该 ID 的第一个上游的覆盖行。仅故障转移上游收费的费率保留在网关上。

520* 选择一个策略退出：在该策略的 `cli` 块中将 `modelPricing` 设置为 `{}`，其开发者保持在列表价格。539* 选择一个策略退出：在该策略的 `cli` 块中将 `modelPricing` 设置为 `{}`，其开发者保持在列表价格。

521* 保持策略自己的费率：其 `cli` 块使用自己的 `multiplier` 或 `overrides` 设置 `modelPricing` 的策略保持该 `modelPricing` 完整，网关不添加自己的费率到它。540* 保留策略自己的费率：其 `cli` 块使用自己的 `multiplier` 或 `overrides` 设置 `modelPricing` 的策略保留该 `modelPricing` 完整，网关不向其添加自己的费率。

522 541

523<h3 id="models">542<h3 id="models">

524 `models`543 `models`

525</h3>544</h3>

526 545

527`models` 块是可选的管理员策划的模型列表，在 `/v1/models` 提供，用于按上游翻译模型 ID。对于非美国 Amazon Bedrock 地区、Amazon Bedrock 预配吞吐量 ARN 和 Microsoft Foundry 部署名称是必需的。546`models` 块是可选的管理员策划的模型列表，在 `/v1/models` 提供并用于按上游翻译模型 ID。它对于非美国 Amazon Bedrock 地区、Amazon Bedrock 预配置吞吐量 ARN 和 Microsoft Foundry 部署名称是必需的。

528 547

529```yaml theme={null}548```yaml theme={null}

530auto_include_builtin_models: true # false：仅公开下面的列表549auto_include_builtin_models: true # false: expose only the list below

531models:550models:

532 - id: claude-opus-4-8551 - id: claude-opus-4-8

533 label: Claude Opus 4.8552 label: Claude Opus 4.8

534 # description: 可选文本显示在表面它的客户端中553 # description: optional text shown in clients that surface it

535 upstream_model:554 upstream_model:

536 anthropic: claude-opus-4-8555 anthropic: claude-opus-4-8

537 bedrock: us.anthropic.claude-opus-4-8 # 或推理配置文件 ARN556 bedrock: us.anthropic.claude-opus-4-8 # or an inference-profile ARN

538 foundry: your-opus-deployment-name557 foundry: your-opus-deployment-name

539```558```

540 559

541`upstream_model` 下的每个键必须匹配配置的上游的 `name`，默认为提供者名称。与任何上游不匹配的键在启动时失败，因此省略你不使用的提供者的行。560`upstream_model` 下的每个键必须匹配配置的上游的 `name`，默认为提供商名称。与任何上游不匹配的键导致启动失败，因此省略您不使用的提供商的行。

542 561

543<h3 id="managed">562<h3 id="managed">

544 `managed`563 `managed`

545</h3>564</h3>

546 565

547`managed` 块定义基于 IdP 组或电子邮件域键入的基于角色的访问策略。策略按顺序评估；第一个匹配被选择，然后合并到下面描述的 `match: {}` 捕获所有基础。它们按用户在 `GET /managed/settings` 提供，具有 ETag/304 缓存。566`managed` 块定义基于 IdP 组或电子邮件域的基于角色的访问策略。策略按顺序评估；选择第一个匹配，然后合并到 `match: {}` 捕获所有基础。它们按用户在 `GET /managed/settings` 提供，带有 ETag/304 缓存。

548 567

549```yaml theme={null}568```yaml theme={null}

550managed:569managed:

551 policies:570 policies:

552 # 特定组首先。571 # Specific groups first.

553 - match: { groups: [eng-contractors] }572 - match: { groups: [eng-contractors] }

554 cli:573 cli:

555 availableModels: [claude-sonnet-4-6]574 availableModels: [claude-sonnet-4-6]

556 permissions: { deny: ["WebFetch", "WebSearch"] }575 permissions: { deny: ["WebFetch", "WebSearch"] }

557 # 默认捕获所有最后：匹配每个已认证的用户。576 # Default catch-all last: matches everyone who authenticated.

558 - match: {}577 - match: {}

559 cli:578 cli:

560 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]579 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

561```580```

562 581

563`match: {}` 捕获所有，按惯例列在最后，被视为基础层。每个其他策略从捕获所有继承它不设置的任何键，因此每角色条目只需列出与组织默认不同的内容。合并规则取决于键类型：582`match: {}` 捕获所有，按惯例列在最后，被视为基础层。每个其他策略从捕获所有继承它不设置的任何键，因此每个角色条目只需列出与组织默认值不同的内容。合并规则取决于键类型：

564 583

565* **允许列表**：`availableModels` 和 `permissions.allow`。特定策略的列表完全替换基础的。584* **允许列表**：`availableModels` 和 `permissions.allow`。特定策略的列表完全替换基础的。

566* **拒绝列表和钩子数组**：`permissions.deny`、`permissions.ask`、`disabledMcpjsonServers`、`deniedMcpServers`、`blockedMarketplaces` 和每个 `hooks` 事件类型数组。这些取基础和策略的并集，因此组织范围的拒绝或审计钩子不能被每角色覆盖意外删除。585* **拒绝列表和钩子数组**：`permissions.deny`、`permissions.ask`、`disabledMcpjsonServers`、`deniedMcpServers`、`blockedMarketplaces` 和每个 `hooks` 事件类型数组。这些取基础和策略的并集，因此组织范围的拒绝或审计钩子不能被每个角色覆盖意外删除。

567* **记录类型的键**：`env`、`modelOverrides` 和 `skillOverrides`。这些浅合并，因此每角色 `env` 块覆盖它设置的键并从基础继承其余的。586* **记录类型键**：`env`、`modelOverrides` 和 `skillOverrides`。这些浅合并，因此每个角色 `env` 块覆盖它设置的键并从基础继承其余的。

568 587

569`availableModels` 也在 `/v1/messages` 服务器端强制执行，因此被拒绝的模型返回 `400`，无论客户端发送什么。588`availableModels` 也在 `/v1/messages` 服务器端强制执行，因此被拒绝的模型返回 `400`，无论客户端发送什么。

570 589

574* 当值存在但不是字符串时，网关以消息 `model must be a string` 拒绝请求。需要运行 Claude Code v2.1.221 或更高版本的网关。593* 当值存在但不是字符串时，网关以消息 `model must be a string` 拒绝请求。需要运行 Claude Code v2.1.221 或更高版本的网关。

575 594

576| 匹配器 | 行为 |595| 匹配器 | 行为 |

577| --------------------------------------------------- | --------------------------------------------------------- |596| --------------------------------------------------- | -------------------------------------------------------- |

578| `match: {}` | 匹配每个已认证的用户。从其中一个开始，稍后添加组范围的策略。 |597| `match: {}` | 匹配每个已认证的用户。从其中一个开始，稍后在其上方添加组范围的策略。 |

579| `match: { groups: [a, b] }` | 如果 JWT 的 `groups` 声明包含任何列出的组，则匹配。区分大小写：组必须与 IdP 的确切大小写匹配。 |598| `match: { groups: [a, b] }` | 如果 JWT 的 `groups` 声明包含任何列出的组，则匹配。区分大小写：组必须匹配 IdP 的确切大小写。 |

580| `match: { email_domain: example.com }` | 匹配 JWT 的 `email` 声明中最后 `@` 后的部分，不区分大小写。每个策略接受一个域。 |599| `match: { email_domain: example.com }` | 匹配 JWT 的 `email` 声明中最后一个 `@` 之后的部分，不区分大小写。每个策略接受一个域。 |

581| `match: { groups: [a], email_domain: example.com }` | 两个条件都必须匹配 |600| `match: { groups: [a], email_domain: example.com }` | 两个条件都必须匹配 |

582 601

583与任何策略不匹配的已认证用户获得网关的默认值，这意味着目录中的每个模型和没有托管设置。如果你想要保证的默认策略，最后添加 `match: {}` 捕获所有。602与任何策略不匹配的已认证用户获得网关的默认值，这意味着目录中的每个模型和没有托管设置。如果您想要保证的默认策略，请在最后添加 `match: {}` 捕获所有。

584 603

585<Note>604<Note>

586 网关不维护自己的用户目录。它从用户的 IdP 令牌授权每个请求，从令牌的 `groups` 声明读取组成员身份，并根据它评估策略。没有要枚举的名册，没有要预创建的帐户，因此没有 SCIM 端点，因为没有东西可供 SCIM 同步到。605 网关不保留自己的用户目录。它从用户的 IdP 令牌授权每个请求，从令牌的 `groups` 声明读取组成员身份，并根据它评估策略。没有名册可以枚举，没有账户需要预先创建，因此没有 SCIM 端点，因为没有东西可以让 SCIM 同步到。

587 606

588 在真实来源处运行用户和组生命周期管理，这是你的 IdP 的本地 SCIM 配置或专用身份治理平台。那里管理的成员身份和取消配置通过令牌自动流入网关。如果你想要 Claude 帐户本身的 SCIM 配置，这是一个 [Claude for Enterprise](/docs/zh-CN/admin-setup) 功能。607 在真实来源（您的 IdP 的本地 SCIM 配置或专用身份治理平台）运行用户和组生命周期管理。那里管理的成员身份和取消配置通过令牌自动流入网关。如果您想要 Claude 账户本身的 SCIM 配置，那是一个[Claude for Enterprise](/docs/zh-CN/admin-setup) 功能。

589 608

590 两个传播时钟适用：609 两个传播时钟适用：

591 610

592 * **策略内容**：编辑策略并重新部署到连接的客户端在其下一个托管设置轮询，在一小时内，除了[仅在下一次启动时应用的更改](/docs/zh-CN/server-managed-settings#fetch-and-caching-behavior)611 * **策略内容**：编辑策略并重新部署在连接的客户端的下一个托管设置轮询时到达，在一小时内，除了[仅在下一次启动时应用的更改](/docs/zh-CN/server-managed-settings#fetch-and-caching-behavior)

593 * **组成员身份**：更改用户的组成员身份改变哪个策略匹配他们。这在下一个会话重新铸造时生效，意味着下一个静默刷新，由 `session.ttl_hours` 限制。612 * **组成员身份**：更改用户的组成员身份改变哪个策略匹配他们。这在下一个会话重新铸造时生效，意味着下一个静默刷新，由 `session.ttl_hours` 限制。

594</Note>613</Note>

595 614

597 在启动时停止网关的匹配器值616 在启动时停止网关的匹配器值

598</h4>617</h4>

599 618

600在启动时，网关检查每个策略的 `match` 块和 [`admin_groups`](#admin) 列表。这些值中的任何一个都会停止网关，并显示命名该字段的错误：619在启动时，网关检查每个策略的 `match` 块和 [`admin_groups`](#admin) 列表。这些值中的任何一个都以命名该字段的错误停止网关：

601 620

602* 空 `groups` 列表621* 空 `groups` 列表

603* `groups` 或 `admin_groups` 中的空条目622* `groups` 或 `admin_groups` 中的空条目

606 625

607在 v2.1.232 之前，网关以这些值启动。每个值有这个效果：626在 v2.1.232 之前，网关以这些值启动。每个值有这个效果：

608 627

609* 空 `email_domain`：网关跳过域检查，因此具有空 `email_domain` 和无 `groups` 列表的策略匹配每个已认证用户628* 空 `email_domain`：网关跳过域检查，因此具有空 `email_domain` 和没有 `groups` 列表的策略匹配每个已认证的用户

610* 空 `groups` 列表：策略不匹配任何人629* 空 `groups` 列表：策略与任何人都不匹配

611* 包含 `@`、空格或逗号的 `email_domain`：策略不匹配任何人630* 包含 `@`、空格或逗号的 `email_domain`：策略与任何人都不匹配

612* `groups` 或 `admin_groups` 中的空条目：条目仅当该用户的 IdP `groups` 声明也包含空条目时才匹配用户。在 `admin_groups` 中，该匹配授予管理员访问权限。如果你的 `admin_groups` 列表从不包含空条目，没有人以这种方式获得管理员访问权限。631* `groups` 或 `admin_groups` 中的空条目：条目仅当该用户的 IdP `groups` 声明也包含空条目时才匹配用户。在 `admin_groups` 中，该匹配授予管理员访问权限。如果您的 `admin_groups` 列表从不包含空条目，没有人以这种方式获得管理员访问权限。

613 632

614<h4 id="what-goes-in-cli">633<h4 id="what-goes-in-cli">

615 `cli` 中的内容634 `cli` 中的内容

616</h4>635</h4>

617 636

618每个 `cli` 值是完整的 Claude Code `managed-settings.json` 文档，与你通过 MDM 或 `/etc/claude-code/managed-settings.json` 部署的相同模式，在此表示为 YAML。CLI 在托管层应用交付的文档，在用户和项目设置之上，代替服务器托管设置。因此它忽略[限制于 OS 级策略来源的设置](/docs/zh-CN/server-managed-settings#current-limitations)，如 `policyHelper` 和 `wslInheritsWindowsSettings`。637每个 `cli` 值是一个完整的 Claude Code `managed-settings.json` 文档，与您通过 MDM 或 `/etc/claude-code/managed-settings.json` 部署的相同架构，在这里表示为 YAML。CLI 在托管层应用交付的文档，在用户和项目设置之上，代替服务器托管的设置。因此它忽略[限制为操作系统级策略源的设置](/docs/zh-CN/server-managed-settings#current-limitations)，如 `policyHelper` 和 `wslInheritsWindowsSettings`。

619 638

620网关在启动时根据 CLI 的设置模式验证每个文档，因此无法识别的顶级键在启动时失败，并显示命名每个违规键的错误。模式的故意开放部分仍然接受任意值，因为较新的客户端可能识别网关的模式不识别的条目。这些开放键是 `env`、`pluginConfigs` 和 `permissions` 下嵌套的键。639网关在启动时根据 CLI 的设置架构验证每个文档，因此无法识别的顶级键导致启动失败，错误命名每个违规键。架构的故意开放部分仍然接受任意值，因为较新的客户端可能识别网关的架构不识别的条目。这些开放键包括 `env`、`pluginConfigs` 和 `permissions` 下嵌套的键。

621 640

622因为验证使用与网关的已安装版本捆绑的模式，将较新 Claude Code 版本引入的顶级设置键放入托管配置需要首先升级网关。在一个客户端上烟雾测试新策略，然后再推出。641因为验证使用与网关的已安装版本捆绑的架构，将由较新 Claude Code 版本引入的顶级设置键放入托管配置需要首先升级网关。在将新策略推出到一个客户端之前对其进行烟雾测试。

623 642

624完整的键参考在 [Claude Code 设置](/docs/zh-CN/settings-reference#all-settings) 中。操作员首先到达的最常见的键：643完整的键参考在[Claude Code 设置](/docs/zh-CN/settings-reference#all-settings)中。操作员首先寻求的最常见键：

625 644

626```yaml theme={null}645```yaml theme={null}

627managed:646managed:

628 policies:647 policies:

629 - match: {}648 - match: {}

630 cli:649 cli:

631 # 模型访问（也在 /v1/messages 服务器端强制执行）650 # Model access (also enforced server-side at /v1/messages)

632 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]651 availableModels: [claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5]

633 652

634 # 权限策略653 # Permission policy

635 permissions:654 permissions:

636 deny:655 deny:

637 - "WebFetch"656 - "WebFetch"

638 - "Read(./.env)"657 - "Read(./.env)"

639 - "Read(./secrets/**)"658 - "Read(./secrets/**)"

640 disableBypassPermissionsMode: disable # 阻止 --dangerously-skip-permissions659 disableBypassPermissionsMode: disable # blocks --dangerously-skip-permissions

641 allowManagedPermissionRulesOnly: true # 忽略用户/项目权限规则660 allowManagedPermissionRulesOnly: true # ignore user/project permission rules

642 661

643 # 推送到 CLI 进程的环境。DISABLE_UPDATES 阻止662 # Environment pushed into the CLI process. DISABLE_UPDATES blocks

644 # 后台和手动更新；DISABLE_AUTOUPDATER 仅停止663 # background and manual updates; DISABLE_AUTOUPDATER stops only

645 # 后台更新。664 # background updates.

646 env:665 env:

647 DISABLE_UPDATES: "1" # 通过你自己的分发固定版本666 DISABLE_UPDATES: "1" # pin versions via your own distribution

648 667

649 # 组织范围的钩子。钩子命令在开发者机器上运行，而不是668 # Org-wide hooks. Hook commands run on developer machines, not the

650 # 网关，因此路径必须存在于策略中每个客户端 OS 上。669 # gateway, so the path must exist on every client OS in the policy.

651 hooks:670 hooks:

652 PostToolUse:671 PostToolUse:

653 - matcher: "Edit|Write"672 - matcher: "Edit|Write"

659| ------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |678| ------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

661| `permissions.allow` / `.deny` | CLI | 工具和命令规则。请参阅[权限](/docs/zh-CN/permissions)。 |680| `permissions.allow` / `.deny` | CLI | 工具和命令规则。请参阅[权限](/docs/zh-CN/permissions)。 |

662| `permissions.disableBypassPermissionsMode` | CLI | 设置为 `disable` 以阻止 [`bypassPermissions`](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)，自动批准每个工具调用的模式，以及 `--dangerously-skip-permissions` 标志 |681| `permissions.disableBypassPermissionsMode` | CLI | 设置为 `disable` 以阻止 [`bypassPermissions`](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)，跳过权限提示的模式，以及 `--dangerously-skip-permissions` 标志 |

663| `allowManagedPermissionRulesOnly` | CLI | 当 `true` 时，托管设置成为权限规则的唯一设置来源。[`allowManagedPermissionRulesOnly`](/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly) 条目列出 Claude Code 然后忽略的每个来源。 |682| `allowManagedPermissionRulesOnly` | CLI | 当 `true` 时，托管设置成为权限规则的唯一设置源。[`allowManagedPermissionRulesOnly`](/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly) 条目列出 Claude Code 然后忽略的每个源。 |

664| `env` | CLI | 合并到 CLI 进程的环境变量。用于遥测、自动更新和模型名称覆盖。 |683| `env` | CLI | 合并到 CLI 进程的环境变量。用于遥测、自动更新和模型名称覆盖。 |

665| `hooks` | CLI | 组织范围的[钩子](/docs/zh-CN/hooks) |684| `hooks` | CLI | 组织范围的[钩子](/docs/zh-CN/hooks) |

666| `managedMcpServers` | CLI | 远程 MCP 服务器[提供给每个匹配的开发者](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings)以及他们自己添加的服务器，仅 `http` 和 `sse`。请参阅[策略中的 MCP 服务器](#mcp-servers-in-a-policy)。需要网关服务器和客户端上的 Claude Code v2.1.259 或更高版本。早期客户端忽略该键。 |685| `managedMcpServers` | CLI | 远程 MCP 服务器[提供给每个匹配的开发者](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings)以及他们自己添加的服务器，仅 `http` 和 `sse`。请参阅[策略中的 MCP 服务器](#mcp-servers-in-a-policy)。需要网关服务器和客户端上的 Claude Code v2.1.259 或更高版本。早期客户端忽略该键。 |

667 686

668因为这些设置通过网络到达，CLI 在应用下面列出的设置之前向每个开发者显示安全批准对话：687因为这些设置通过网络到达，CLI 在应用下面列出的设置之前向每个开发者显示安全批准对话框：

669 688

670* `hooks`689* `hooks`

671* 需要开发者批准的 `env` 变量，如代理和基础 URL 变量690* 需要开发者批准的 `env` 变量，如代理和基础 URL 变量

672* shell 执行设置，如 `apiKeyHelper` 和 `statusLine`691* shell 执行设置，如 `apiKeyHelper` 和 `statusLine`

673* 沙箱二进制设置 `sandbox.bwrapPath`、`sandbox.socatPath` 和 `sandbox.ripgrep`692* 沙箱二进制设置 `sandbox.bwrapPath`、`sandbox.socatPath` 和 `sandbox.ripgrep`

674* 拦截流量、注入凭证或削弱隔离的沙箱设置，如 `sandbox.network.tlsTerminate` 和代理端口设置。[安全批准对话](/docs/zh-CN/server-managed-settings#security-approval-dialogs)列出它们全部。693* 拦截流量、注入凭证或削弱隔离的沙箱设置，如 `sandbox.network.tlsTerminate` 和代理端口设置。[安全批准对话框](/docs/zh-CN/server-managed-settings#security-approval-dialogs)列出所有这些。

675 694

676[批准记忆](/docs/zh-CN/server-managed-settings#approval-memory)涵盖批准持续多长时间以及对话何时再次出现。695[批准记忆](/docs/zh-CN/server-managed-settings#approval-memory)涵盖批准持续多长时间以及对话框何时再次出现。

677 696

678Claude Code 应用一些交付的 `env` 变量而不显示开发者批准对话，如模型选择设置和数值限制。其他交付的变量可能需要开发者的批准才能生效；非空代理、基础 URL 或 `OTEL_EXPORTER_OTLP_ENDPOINT` 值总是这样。当交付的变量需要批准时，对话会命名它。697Claude Code 应用一些交付的 `env` 变量而不向开发者显示批准对话框，如模型选择设置和数值限制。其他交付的变量可能需要开发者的批准才能生效；非空代理、基础 URL 或 `OTEL_EXPORTER_OTLP_ENDPOINT` 值总是这样。当交付的变量需要批准时，对话框命名它。

679 698

680[环境变量和批准对话](/docs/zh-CN/server-managed-settings#environment-variables-and-the-approval-dialog)有详细信息，包括四个隐私切换，其交付值决定它们是否需要批准。在 v2.1.218 之前，Claude Code 应用更少的变量而不询问开发者，因此更多交付的变量触发对话。699[环境变量和批准对话框](/docs/zh-CN/server-managed-settings#environment-variables-and-the-approval-dialog)有详细信息，包括四个隐私切换，其交付值决定它们是否需要批准。在 v2.1.218 之前，Claude Code 应用更少的变量而不询问开发者，因此更多交付的变量触发对话框。

681 700

682网关的[遥测](#telemetry)配置推送 `OTEL_EXPORTER_OTLP_ENDPOINT`，因此设置 `telemetry.forward_to` 在每个交互式客户端上触发对话。对话保护开发者的机器免受受损或敌对网关，而不是组织免受开发者。701网关的[遥测](#telemetry)配置推送 `OTEL_EXPORTER_OTLP_ENDPOINT`，因此设置 `telemetry.forward_to` 在每个交互式客户端上触发对话框。对话框保护开发者的机器免受受损或敌对网关的影响，而不是保护组织免受开发者的影响。

683 702

684使用 `-p` 标志的非交互式运行无法显示对话。它仅为该运行应用推送的设置，不将其记录为已批准，因此开发者的下一个交互式会话仍然显示对话。在 v2.1.207 之前，非交互式运行将设置保存为已批准，之后没有交互式会话为它们显示对话。703带有 `-p` 标志的非交互式运行无法显示对话框。它仅为该运行应用推送的设置，不将其记录为已批准，因此开发者的下一个交互式会话仍然显示对话框。在 v2.1.207 之前，非交互式运行将设置保存为已批准，没有后来的交互式会话为它们显示对话框。

685 704

686如果开发者拒绝，Claude Code 退出该会话而不是应用策略。当你推送新钩子或任何触发对话的 env 变量到广泛策略时，Claude Code 因此向每个匹配的开发者显示对话。它在运行会话中的下一个小时轮询显示对话，否则在开发者的下一次启动时显示。705如果开发者拒绝，Claude Code 退出该会话而不是应用策略。当您推送新钩子或任何触发对话框的 env 变量到广泛策略时，Claude Code 因此向每个匹配的开发者显示对话框。它在运行会话中的下一个小时轮询时显示对话框，否则在开发者的下一个启动时显示。

687 706

688`cli` 键在早期版本中被命名为 `settings`。该拼写仍然被接受为别名，但新部署应使用 `cli`。707`cli` 键在早期版本中被命名为 `settings`。该拼写仍然被接受为别名，但新部署应该使用 `cli`。

689 708

690<h4 id="mcp-servers-in-a-policy">709<h4 id="mcp-servers-in-a-policy">

691 策略中的 MCP 服务器710 策略中的 MCP 服务器

692</h4>711</h4>

693 712

694要向策略匹配的 Claude Code 客户端提供 MCP 服务器，在该策略的 `cli` 块中设置 [`managedMcpServers`](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings)。你需要网关服务器和客户端上的 Claude Code v2.1.259 或更高版本。713要向策略匹配的 Claude Code 客户端提供 MCP 服务器，在该策略的 `cli` 块中设置 [`managedMcpServers`](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings)。您需要网关服务器和客户端上的 Claude Code v2.1.259 或更高版本。

695 714

696网关在启动时使用[Claude Code 在客户端应用的相同规则](/docs/zh-CN/managed-mcp#what-an-entry-can-contain)检查每个条目，如果条目失败检查，网关拒绝启动并命名该条目。715网关在启动时使用[Claude Code 在客户端应用的相同规则](/docs/zh-CN/managed-mcp#what-an-entry-can-contain)检查每个条目，如果条目失败检查，网关拒绝启动并命名该条目。

697 716

698如果你在 `gateway.yaml` 中写入 `${VAR}` 引用，网关在启动时通过[秘密扩展](#secret-expansion)从其环境解析它，然后运行条目检查，因此每个匹配的客户端接收字面值并可以读取它。[提供的服务器的头部指导](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings)适用于扩展值。717如果您在 `gateway.yaml` 中写入 `${VAR}` 引用，网关在启动时通过[秘密扩展](#secret-expansion)从其环境解析它，然后运行条目检查，因此每个匹配的客户端接收文字值并可以读取它。[为提供的服务器的标头指导](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings)适用于扩展值。

699 718

700网关拒绝 `cli` 块中的 `.mcp.json` 拼写 `mcpServers`，其启动错误命名 `managedMcpServers` 作为要使用的键。在 v2.1.259 之前，网关拒绝 `cli` 块中的任何 MCP 服务器定义。719网关拒绝 `cli` 块中的 `.mcp.json` 拼写 `mcpServers`，其启动错误命名 `managedMcpServers` 作为要使用的键。在 v2.1.259 之前，网关拒绝 `cli` 块中的任何 MCP 服务器定义。

701 720

703 Claude Desktop 覆盖722 Claude Desktop 覆盖

704</h4>723</h4>

705 724

706如果你的组织也部署 [Claude Desktop](/docs/zh-CN/desktop)，同一网关为两个客户端提供服务。在 Claude Desktop 的[托管配置](https://claude.com/docs/third-party/claude-desktop/configuration)中指向 `bootstrapUrl` 到 `<listen.public_url>/user/bootstrap`。Claude Desktop 从该 URL 派生 OAuth 发行者，针对此网关运行相同的设备代码登录，并从响应中获取其配置。725如果您的组织也部署[Claude Desktop](/docs/zh-CN/desktop)，同一网关为两个客户端提供服务。在 Claude Desktop 的[托管配置](https://claude.com/docs/third-party/claude-desktop/configuration)中指向 `bootstrapUrl` 到 `<listen.public_url>/user/bootstrap`。Claude Desktop 从该 URL 派生 OAuth 发行者，针对此网关运行相同的设备代码登录，并从响应中获取其配置。

707 726

708<Note>727<Note>

709 需要网关服务器上的 Claude Code v2.1.203 或更高版本，以及显式选择加入：`/user/bootstrap` 返回 404，除非与用户匹配的策略携带 `desktop` 键。空 `desktop: {}` 选择策略加入，`match: {}` 基础层上的 `desktop` 键选择加入继承它的每个策略。审计日志将每个请求记录为 `desktop_bootstrap.serve` 或 `desktop_bootstrap.denied`。728 需要网关服务器上的 Claude Code v2.1.203 或更高版本，以及显式选择加入：除非与用户匹配的策略携带 `desktop` 键，否则 `/user/bootstrap` 返回 404。空 `desktop: {}` 选择策略加入，`match: {}` 基础层上的 `desktop` 键选择继承它的每个策略加入。审计日志将每个请求记录为 `desktop_bootstrap.serve` 或 `desktop_bootstrap.denied`。

710</Note>729</Note>

711 730

712网关从匹配策略的 `cli` 块和顶级网关配置派生响应的大部分：731网关从匹配策略的 `cli` 块和顶级网关配置派生响应的大部分：

713 732

714* 模型列表，来自 `availableModels`733* 模型列表，来自 `availableModels`

715* 禁用的工具，来自裸工具名称 `permissions.deny` 条目。如果你在策略的 `desktop` 块中设置 `disabledBuiltinTools`，网关提供你的值和派生列表的并集，因此你可以通过这种方式禁用更多工具，但不能重新启用你通过 `permissions.deny` 禁用的工具734* 禁用的工具，来自裸工具名称 `permissions.deny` 条目。如果您在策略的 `desktop` 块中设置 `disabledBuiltinTools`，网关提供您的值和派生列表的并集，因此您可以通过这种方式禁用更多工具，但无法重新启用您通过 `permissions.deny` 禁用的工具

716* 出口允许列表，来自 `sandbox.network.allowedDomains`。如果你在策略的 `desktop` 块中设置 `coworkEgressAllowedHosts`，网关使用该值而不是派生列表735* 出口允许列表，来自 `sandbox.network.allowedDomains`。如果您在策略的 `desktop` 块中设置 `coworkEgressAllowedHosts`，网关使用该值而不是派生列表

717* 指向网关本身的 OTLP 端点，以及已登录用户的身份属性。网关将它在该端点接收的导出中继到你的 `forward_to` 目标。当你同时设置 [`telemetry.forward_to`](#telemetry) 和 `listen.public_url` 时，它包括端点和属性。736* 指向网关本身的 OTLP 端点，以及已登录用户的身份属性。网关将它在该端点接收的导出中继到您的 `forward_to` 目的地。当您同时设置 [`telemetry.forward_to`](#telemetry) 和 `listen.public_url` 时，它包括端点和属性。

718 737

719 Claude Desktop 以一种编码导出每个信号：`http/protobuf`，或当你在策略的 `env` 中设置 `OTEL_EXPORTER_OTLP_PROTOCOL` 或其每信号变体为 `http/json` 时为 `http/json`。在网关服务器上的 Claude Code v2.1.261 之前，响应设置 `http/json` 无论如何，因此仅接受 protobuf 的收集器拒绝 Claude Desktop 的导出738 Claude Desktop 以一种编码导出每个信号：`http/protobuf`，或当您在策略的 `env` 中设置 `OTEL_EXPORTER_OTLP_PROTOCOL` 或其每个信号变体为 `http/json` 时为 `http/json`。在网关服务器上的 Claude Code v2.1.261 之前，响应设置 `http/json` 无论如何，因此仅接受 protobuf 的收集器拒绝了 Claude Desktop 的导出

720 739

721要在策略的 `desktop` 块中设置 `disabledBuiltinTools`、`coworkEgressAllowedHosts` 或 Claude Desktop 自己的 `managedMcpServers` 设置，你需要网关服务器上的 Claude Code v2.1.232 或更高版本。Claude Desktop 的 `managedMcpServers` 采用数组值而不是对象。740要在策略的 `desktop` 块中设置 `disabledBuiltinTools`、`coworkEgressAllowedHosts` 或 Claude Desktop 自己的 `managedMcpServers` 设置，您需要网关服务器上的 Claude Code v2.1.232 或更高版本。Claude Desktop 的 `managedMcpServers` 采用数组值而不是对象。

722 741

723网关省略没有 Claude Desktop 等效项的键，如 `hooks` 和作用域权限规则如 `Bash(npm *)`，来自引导响应。742网关省略没有 Claude Desktop 等效项的键，如 `hooks` 和范围权限规则如 `Bash(npm *)`，来自引导响应。

724 743

725添加可选的 `desktop` 块与 `cli` 一起直接设置 Claude Desktop 设置。从 Claude Desktop 的[托管配置参考](https://claude.com/docs/third-party/claude-desktop/configuration)写设置为平面键名。省略 Claude Desktop 仅从 MDM 或本地文件读取的键，如 `bootstrapUrl`；网关在启动时拒绝它们。在 v2.1.232 之前，网关接受固定的 11 个功能门键列表，如 `chatTabEnabled` 和 `disableAutoUpdates`，并在启动时拒绝每个其他键。在 v2.1.227 之前，网关也在启动时拒绝 `chatTabEnabled` 和 `chatAdvancedFileAnalysisEnabled`。744在 `cli` 旁边添加可选的 `desktop` 块以直接设置 Claude Desktop 设置。从 Claude Desktop 的[托管配置参考](https://claude.com/docs/third-party/claude-desktop/configuration)写入设置为平面键名。省略 Claude Desktop 仅从 MDM 或本地文件读取的键，如 `bootstrapUrl`；网关在启动时拒绝它们。在 v2.1.232 之前，网关接受 11 个固定的功能门键的列表，如 `chatTabEnabled` 和 `disableAutoUpdates`，并在启动时拒绝每个其他键。在 v2.1.227 之前，网关也在启动时拒绝 `chatTabEnabled` 和 `chatAdvancedFileAnalysisEnabled`。

726 745

727```yaml theme={null}746```yaml theme={null}

728managed:747managed:

736 banner: { text: "Contractor build: internal use only" }755 banner: { text: "Contractor build: internal use only" }

737```756```

738 757

739每个键都是可选的；Claude Desktop 为你省略的任何键应用自己的默认值。网关在启动时根据 Claude Desktop 本身使用的配置模式验证每个 `desktop` 块，因此错误在网关启动时显示为命名键的错误，而不是到达每个连接的桌面。网关在块包含以下内容时在启动时失败：758每个键都是可选的；Claude Desktop 为您省略的任何键应用自己的默认值。网关在启动时根据 Claude Desktop 本身使用的配置架构验证每个 `desktop` 块，因此错误在网关启动时显示为命名该键的错误，而不是到达每个连接的桌面。网关在块包含以下内容时在启动时失败：

740 759

741* 未知键760* 未知键

742* 识别的键，其值 Claude Desktop 会拒绝或静默删除，如空值或嵌套条目内的拼写错误的子键。在 v2.1.260 之前，网关静默删除 `managedMcpServers` 或 `orgPluginSettings` 条目的嵌套对象内的拼写错误字段，而不是在启动时失败。761* 识别的键，其值 Claude Desktop 会拒绝或静默删除，如空值或嵌套条目内的拼写错误的子键。在 v2.1.260 之前，网关静默删除 `managedMcpServers` 或 `orgPluginSettings` 条目内嵌套对象中的拼写错误字段，而不是在启动时失败。

743* 网关自己计算的键：推理连接、模型列表和 OTLP 中继。通过 [`upstreams`](#upstreams)、[`models`](#models) 和 [`telemetry`](#telemetry) 部分的 `forward_to` 配置这些。762* 网关自己计算的键：推理连接、模型列表和 OTLP 中继。通过 [`upstreams`](#upstreams)、[`models`](#models) 和 [`telemetry`](#telemetry) 部分的 `forward_to` 配置这些。

744* 当前键的遗留别名。在启动错误中，网关命名规范键来写。763* 当前键的遗留别名。在启动错误中，网关命名规范键来写。

745 764

746如果你使用已弃用的值或条目形状，如没有 `transport` 的 `managedMcpServers` 条目，网关启动并记录命名替换的警告。765如果您使用已弃用的值或条目形状，如没有 `transport` 的 `managedMcpServers` 条目，网关启动并记录命名替换的警告。

747 766

748网关根据与其已安装版本捆绑的模式验证 `desktop` 块，如它对 `cli` 块所做的那样。要交付较新 Claude Desktop 版本引入的设置，首先升级网关。例如，`userPluginMarketplacesEnabled` 和 `userPluginUploadsEnabled` 需要网关服务器上的 Claude Code v2.1.260 或更高版本以及成员机器上的 Claude Desktop 1.37937.0 或更高版本。767网关根据与其已安装版本捆绑的架构验证 `desktop` 块，就像它对 `cli` 块所做的那样。要交付由较新 Claude Desktop 版本引入的设置，首先升级网关。例如，`userPluginMarketplacesEnabled` 和 `userPluginUploadsEnabled` 需要网关服务器上的 Claude Code v2.1.260 或更高版本以及成员机器上的 Claude Desktop 1.37937.0 或更高版本。

749 768

750如果你在策略的 `desktop` 块中设置 `orgPluginSettings`，网关以 Claude Desktop 1.15200.0 及更高版本读取的数组形式提供它。较旧的桌面会忽略该数组，不强制执行任何插件工具策略，因此在依赖它之前将成员更新到 1.15200.0 或更高版本。769如果您在策略的 `desktop` 块中设置 `orgPluginSettings`，网关以 Claude Desktop 1.15200.0 及更高版本读取的数组形式提供它。较旧的桌面忽略数组并强制执行无插件工具策略，因此在依赖它之前将成员更新到 1.15200.0 或更高版本。

751 770

752网关从 `match: {}` 捕获所有的 `desktop` 块填充策略的 `desktop` 块不设置的键，与它填充策略的 `cli` 块的方式相同。如果你在基础和角色策略中都设置 `disabledBuiltinTools` 或 `builtinToolPolicy`，网关保持基础的限制：771网关从 `match: {}` 捕获所有的 `desktop` 块填充策略的 `desktop` 块不设置的键，与它填充策略的 `cli` 块的方式相同。如果您在基础和角色策略中都设置 `disabledBuiltinTools` 或 `builtinToolPolicy`，网关保留基础的限制：

753 772

754* `disabledBuiltinTools`：网关使用基础列表和策略列表的并集773* `disabledBuiltinTools`：网关使用基础列表和策略列表的并集

755* `builtinToolPolicy`：如果你在基础中为工具设置除 `allow` 之外的值，网关保持该值，即使你在角色策略中为同一工具设置 `allow`774* `builtinToolPolicy`：如果您在基础中为工具设置除 `allow` 之外的值，网关保留该值，即使您在角色策略中为同一工具设置 `allow`

756 775

757对于每个其他键，如果你在角色策略中设置它，网关使用角色策略的值。网关整体替换数组或嵌套对象如 `banner`，因此如果你在角色策略中设置 `banner.text`，网关删除基础的 `banner.backgroundColor`。776对于每个其他键，如果您在角色策略中设置它，网关使用角色策略的值。网关完整替换数组或嵌套对象如 `banner`，因此如果您在角色策略中设置 `banner.text`，网关删除基础的 `banner.backgroundColor`。

758 777

759如果你不部署 Claude Desktop，完全从你的策略中省略 `desktop`；网关然后为每个用户从 `/user/bootstrap` 返回 404。778如果您不部署 Claude Desktop，完全从您的策略中省略 `desktop`；网关然后从 `/user/bootstrap` 为每个用户返回 404。

760 779

761<h4 id="precedence-with-other-managed-sources">780<h4 id="precedence-with-other-managed-sources">

762 与其他托管来源的优先级781 与其他托管源的优先级

763</h4>782</h4>

764 783

765如果设备也有 MDM 交付的策略或本地 `managed-settings.json`，网关交付的设置排名第一。[托管层内的优先级](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)在托管设置页面上说明本地来源何时应用，并有[Claude Code 从每个管理来源读取的键](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)，无论它选择哪个来源，如沙箱锁键、`forceRemoteSettingsRefresh` 和每变量 `env` 合并。[`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 在 MDM 配置文件或托管设置文件中配置仅在网关交付无设置时运行；条目说明其输出替换什么。784如果设备也有 MDM 交付的策略或本地 `managed-settings.json`，网关交付的设置排名第一。[托管层内的优先级](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)在托管设置页面上说明本地源何时应用，并有[Claude Code 从每个管理源读取的键](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)，无论它选择哪个源，如沙箱锁键、`forceRemoteSettingsRefresh` 和每个变量 `env` 合并。在 MDM 配置文件或托管设置文件中配置的 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 仅在网关不交付设置时运行；条目说明其输出替换什么。

766 785

767嵌入主机如 [Claude Desktop](/docs/zh-CN/desktop) 可以通过 SDK `managedSettings` 选项提供策略。[来自嵌入主机的父设置](/docs/zh-CN/managed-settings#parent-settings-from-embedding-hosts)说明 Claude Code 何时应用它，以及[限制父设置](/docs/zh-CN/claude-apps-gateway#restrict-parent-settings)列出哪些允许方向设置仍然应用而不需要 `allowManaged*Only` 锁。786嵌入主机如[Claude Desktop](/docs/zh-CN/desktop)可以通过 SDK `managedSettings` 选项提供策略。[来自嵌入主机的父设置](/docs/zh-CN/managed-settings#parent-settings-from-embedding-hosts)说明 Claude Code 何时应用它，[限制父设置](/docs/zh-CN/claude-apps-gateway#restrict-parent-settings)列出哪些允许方向设置仍然适用而不需要 `allowManaged*Only` 锁。

768 787

769网关策略适用于机器上的每个 Claude Code 调用，包括非交互式 `claude -p` 运行和由 Agent SDK 生成的会话。如果网关在启动时无法访问，已登录的会话以错误退出，而不是在没有其策略的情况下运行。788网关策略适用于机器上的每个 Claude Code 调用，包括非交互式 `claude -p` 运行和由 Agent SDK 生成的会话。如果网关在启动时无法访问，已登录的会话以错误退出，而不是在没有其策略的情况下运行。

770 789

772 `telemetry`791 `telemetry`

773</h3>792</h3>

774 793

775CLI 通过 HTTP 指标、日志和（启用时）跟踪将 OpenTelemetry Protocol (OTLP) 发送到网关，网关逐字中继到每个配置的目标。导出使用 OpenTelemetry Protocol (OTLP) over HTTP。要跳过中继并让会话直接导出到你的收集器，[在策略中命名收集器](#export-directly-to-your-collector)。有关 CLI 发出的指标和事件，请参阅[监控使用](/docs/zh-CN/monitoring-usage)。794CLI 将指标、日志和（启用时）跟踪发送到网关，网关将它们逐字中继到每个配置的目的地。导出使用 OpenTelemetry Protocol (OTLP) over HTTP。要跳过中继并让会话直接导出到您的收集器，[在策略中命名收集器](#export-directly-to-your-collector)。请参阅[监控使用](/docs/zh-CN/monitoring-usage)了解 CLI 发出的指标和事件。

776 795

777CLI 使用从网关发出的 JWT 读取的已认证用户的身份戳记每个导出：`user.id`、`user.email` 和 `user.groups` 属性。每开发者成本和使用归因因此在没有开发者端配置的情况下工作。796CLI 使用从网关颁发的 JWT 读取的已认证用户的身份为每个导出加盖时间戳：`user.id`、`user.email` 和 `user.groups` 属性。每个开发者的成本和使用归属因此无需开发者端配置即可工作。

778 797

779[Claude Desktop](#claude-desktop-overlay) 和通过网关登录的 Cowork 会话使用 `user.email` 和 `user.groups` 以及 `enduser.id` 戳记其遥测，因此你可以使用一个关于 `user.email` 或 `user.groups` 的查询覆盖终端、Desktop 和 Cowork 使用。`user.groups` 是逗号分隔的 IdP 组列表。798[Claude Desktop](#claude-desktop-overlay) 和通过网关登录的 Cowork 会话使用 `user.email` 和 `user.groups` 以及 `enduser.id` 为其遥测加盖时间戳，因此您可以使用一个关于 `user.email` 或 `user.groups` 的查询覆盖终端、Desktop 和 Cowork 使用。`user.groups` 是逗号分隔的 IdP 组列表。

780 799

781像来自 Claude Code 的所有 OpenTelemetry 数据一样，这些属性仅去往你的组织配置的目标，从不去往 Anthropic。800与来自 Claude Code 的所有 OpenTelemetry 数据一样，这些属性仅转到您的组织配置的目的地，从不转到 Anthropic。

782 801

783如果用户的组列表在百分比编码后长于 255 个字符，或组名包含逗号或等号，网关从该用户的 Desktop 和 Cowork 遥测中省略 `user.groups`，而不是截断它。该用户的终端会话仍然携带完整列表。802如果用户的组列表在百分比编码后长于 255 个字符，或组名包含逗号或等号，网关从该用户的 Desktop 和 Cowork 遥测中省略 `user.groups`，而不是截断它。该用户的终端会话仍然携带完整列表。

784 803

785你需要网关服务器上的 Claude Code v2.1.265 或更高版本用于 Desktop 和 Cowork 遥测上的 `user.email` 和 `user.groups`，以及每个开发者机器上的 Claude Desktop 1.24012 或更高版本用于 `user.groups`。804您需要网关服务器上的 Claude Code v2.1.265 或更高版本才能在 Desktop 和 Cowork 遥测上获得 `user.email` 和 `user.groups`，以及每个开发者机器上的 Claude Desktop 1.24012 或更高版本才能获得 `user.groups`。

786 805

787```yaml theme={null}806```yaml theme={null}

788telemetry:807telemetry:

790 - url: https://otel-collector.internal.example.com809 - url: https://otel-collector.internal.example.com

791 headers:810 headers:

792 Authorization: ${OTLP_TOKEN}811 Authorization: ${OTLP_TOKEN}

793 # 每信号选择加入。默认：仅指标。812 # Per-signal opt-in. Default: metrics only.

794 metrics: true813 metrics: true

795 logs: false814 logs: false

796 traces: false815 traces: false

800```819```

801 820

802<Warning>821<Warning>

803 每个目标独立选择加入 `metrics`、`logs` 和 `traces`，默认值仅为指标。信号在敏感性上有所不同：822 每个目的地独立选择加入 `metrics`、`logs` 和 `traces`，默认仅为指标。信号的敏感性不同：

804 823

805 * **指标**：聚合计数器，如令牌计数、请求计数和延迟824 * **指标**：聚合计数器，如令牌计数、请求计数和延迟

806 * **日志和跟踪**：可以携带完整的 bash 命令、工具输入和文件路径，涵盖 Claude Code 在开发者机器上所做的任何事情825 * **日志和跟踪**：可以携带完整的 Bash 命令、工具输入和文件路径，涵盖 Claude Code 在开发者机器上所做的任何事情

807 826

808 仅在具有该数据保证的访问控制和保留策略的目标上启用日志和跟踪。827 仅在具有该数据保证的访问控制和保留策略的目的地启用日志和跟踪。

809</Warning>828</Warning>

810 829

811每个 `forward_to` URL 必须使用 `https://`，有一个例外，用于网关自己的环回接口上的收集器：830每个 `forward_to` URL 必须使用 `https://`，有一个例外是网关自己的环回接口上的收集器：

812 831

813* `http://localhost:<port>` 通过配置验证，但[SSRF 守卫](/docs/zh-CN/claude-apps-gateway-deploy#threat-model-summary)阻止每个导出，带有 `ECONNREFUSED_SSRF`，除非你在网关的环境中设置 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`832* `http://localhost:<port>` 通过配置验证，但[SSRF 防护](/docs/zh-CN/claude-apps-gateway-deploy#threat-model-summary)阻止每个导出带有 `ECONNREFUSED_SSRF`，除非您在网关的环境中设置 `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1`

814* `http://127.0.0.1:<port>` 或 `http://[::1]:<port>` 在未设置该变量的情况下启动失败833* `http://127.0.0.1:<port>` 或 `http://[::1]:<port>` 在启动时失败，除非设置了该变量

815 834

816对于集群内收集器，在其自己的内部地址上公开它通过 HTTPS，或将其作为设置变量的边车运行。835对于集群内收集器，在其自己的内部地址上通过 HTTPS 公开它，或将其作为侧车运行并设置变量。

817 836

818遥测在 CLI 中默认关闭。当你同时设置 `telemetry.forward_to` 和 `listen.public_url` 时，网关通过 `/managed/settings` 为连接的客户端打开它，推送六个环境变量：837遥测在 CLI 中默认关闭。当您同时设置 `telemetry.forward_to` 和 `listen.public_url` 时，网关通过 `/managed/settings` 推送六个环境变量为连接的客户端打开它：

819 838

820* `CLAUDE_CODE_ENABLE_TELEMETRY=1`839* `CLAUDE_CODE_ENABLE_TELEMETRY=1`

821* `OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER` 和 `OTEL_TRACES_EXPORTER`，如果至少一个 `forward_to` 目标启用该信号，每个设置为 `otlp`，否则设置为 `none`840* `OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER` 和 `OTEL_TRACES_EXPORTER`，如果至少一个 `forward_to` 目的地启用该信号，则每个设置为 `otlp`，否则设置为 `none`

822* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`841* `OTEL_EXPORTER_OTLP_ENDPOINT=<public_url>`

823* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`842* `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`

824 843

825在网关服务器上的 Claude Code v2.1.265 之前，网关将所有三个导出器选择器推送为 `otlp`，包括对于没有目标选择加入的信号。844在网关服务器上的 Claude Code v2.1.265 之前，网关将所有三个导出器选择器推送为 `otlp`，包括没有目的地选择加入的信号。

826 845

827推送的端点从公共 URL 构建，因此指标和日志不需要来自开发者或策略的 OTEL 配置。846推送的端点是从公共 URL 构建的，因此指标和日志不需要来自开发者或策略的 OTEL 配置。

828 847

829通过 `/login` 登录的开发者无法使用自己的 OTEL 配置重定向导出：848通过 `/login` 登录的开发者无法使用自己的 OTEL 配置重定向导出：

830 849

831* **本地设置的变量**：Claude Code 在托管层应用推送的变量，因此每个变量覆盖开发者为其本地设置的值。850* **本地设置的变量**：Claude Code 在托管层应用推送的变量，因此每个变量覆盖开发者为其本地设置的值。

832* **本地配置的端点**：启用了 OTLP/HTTP 导出，CLI 忽略任何本地配置的端点，无论网关是否推送遥测变量。其导出去往网关，除非策略[将你的收集器命名为端点](#export-directly-to-your-collector)。851* **本地配置的端点**：启用 OTLP/HTTP 导出后，CLI 忽略任何本地配置的端点，无论网关是否推送了遥测变量。其导出转到网关，除非策略[将您的收集器命名为端点](#export-directly-to-your-collector)。

833 852

834没有信号的 `forward_to` 目标，网关接受并丢弃它。如果开发者已经直接导出 Claude Code 遥测到你的一个收集器，将其添加为 `forward_to` 目标，如果他们导出那些，启用日志或跟踪，因此它在他们登录后继续接收他们的数据。要跳过中继，[在策略中命名收集器](#export-directly-to-your-collector)。853没有信号的 `forward_to` 目的地，网关接受并丢弃它。如果开发者已经将 Claude Code 遥测导出到您的一个收集器，将其添加为 `forward_to` 目的地，如果他们导出这些，启用日志或跟踪，以便在他们登录后继续接收他们的数据。要跳过中继，[在策略中命名收集器](#export-directly-to-your-collector)。

835 854

836[跟踪](/docs/zh-CN/monitoring-usage#traces-beta)另外需要每个客户端上的 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`。在托管策略的 `env` 块中设置它，因为网关不推送它。开发者在推送的端点已经触发的相同[安全批准对话](#managed)中批准它。855[跟踪](/docs/zh-CN/monitoring-usage#traces-beta)也需要每个客户端上的 `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1`。在托管策略的 `env` 块中设置它，因为网关不推送它。开发者在推送端点已经触发的相同[安全批准对话框](#managed)中批准它。

837 856

838仅在你想要跟踪的组的策略中将其设置为 `1`。不设置它的策略从你的 `match: {}` 捕获所有策略继承值，如果该策略设置一个，根据[合并规则](#managed)。要防止组的客户端发送跟踪，即使开发者在本地设置变量，在该组的策略中将其设置为 `0`。857仅在您想要跟踪的组的策略中将其设置为 `1`。不设置它的策略从您的 `match: {}` 捕获所有策略继承值（如果该策略设置一个），根据[合并规则](#managed)。要防止组的客户端发送跟踪，即使开发者在本地设置变量，在该组的策略中将其设置为 `0`。

839 858

840protobuf 和 JSON OTLP 编码都被中继，任何 OpenTelemetry 兼容的后端都可以作为目标。859Protobuf 和 JSON OTLP 编码都被中继，任何 OpenTelemetry 兼容的后端都可以作为目的地。

841 860

842<h4 id="export-directly-to-your-collector">861<h4 id="export-directly-to-your-collector">

843 直接导出到你的收集器862 直接导出到您的收集器

844</h4>863</h4>

845 864

846要让通过 `/login` 登录的会话直接将遥测发送到你的收集器而不是通过中继，在[托管策略](#managed)的 `env` 块中将 `OTEL_EXPORTER_OTLP_ENDPOINT` 设置为收集器的 `https://` 基础 URL。Claude Code 将 `/v1/metrics`、`/v1/logs` 或 `/v1/traces` 附加到你设置的 URL，如 `https://otel-collector.example.com:4318`，并在那里通过 OTLP/HTTP 导出每个信号。需要每个开发者机器上的 Claude Code v2.1.265 或更高版本。早期客户端通过中继导出。865要让通过 `/login` 登录的会话直接将遥测发送到您的收集器而不是通过中继，在[托管策略](#managed)的 `env` 块中将 `OTEL_EXPORTER_OTLP_ENDPOINT` 设置为收集器的 `https://` 基础 URL。Claude Code 将 `/v1/metrics`、`/v1/logs` 或 `/v1/traces` 附加到您设置的 URL，如 `https://otel-collector.example.com:4318`，并通过 OTLP/HTTP 在那里导出每个信号。需要每个开发者机器上的 Claude Code v2.1.265 或更高版本。早期客户端通过中继导出。

847 866

848要向收集器进行身份验证，在同一 `env` 块中设置 `OTEL_EXPORTER_OTLP_HEADERS`。会话从不将开发者的网关会话令牌发送到以这种方式命名的收集器。867要向收集器进行身份验证，在同一 `env` 块中设置 `OTEL_EXPORTER_OTLP_HEADERS`。会话从不将开发者的网关会话令牌发送到以这种方式命名的收集器。

849 868

850当你在策略中添加或更改此端点时，Claude Code 在[安全批准对话](#managed)中要求每个开发者批准它，然后在交互式会话中应用它。869当您在策略中添加或更改此端点时，Claude Code 在[安全批准对话框](#managed)中要求每个开发者批准它，然后在交互式会话中应用它。

851 870

852Claude Code 在直接导出信号之前检查端点，并在检查失败时将该信号保持在中继上。检查包括：871Claude Code 在导出信号之前检查端点，并在检查失败时将该信号保留在中继上。检查包括：

853 872

854* 端点来自网关本身。如果你在 MDM 配置文件或本地 `managed-settings.json` 中设置相同的变量，导出保持在中继上。873* 端点来自网关本身。如果您在 MDM 配置文件或本地 `managed-settings.json` 中设置相同的变量，导出保留在中继上。

855* URL 使用 `https://`，或 `http://` 到环回地址874* URL 使用 `https://`，或 `http://` 到环回地址

856* URL 解析为以 `/v1/<signal>` 结尾的路径，没有查询或片段。Claude Code 从通用变量本身构建该路径。它使用每信号变量如 `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 如写的那样，因此在那里包括完整路径。875* URL 解析为以 `/v1/<signal>` 结尾的路径，没有查询或片段。Claude Code 从通用变量本身构建该路径。它使用每个信号变量如 `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` 的写法，因此在那里包括完整路径。

857* URL 不是网关自己的主机。寻址到网关的端点保持中继路径和其会话令牌。876* URL 不是网关自己的主机。寻址到网关的端点保留中继路径及其会话令牌。

858* 你和开发者都没有在任何设置来源中配置 [`otelHeadersHelper`](/docs/zh-CN/settings-reference#otelheadershelper)。配置了助手，每个信号保持在中继上。877* 您和开发者都没有在任何设置源中配置 [`otelHeadersHelper`](/docs/zh-CN/settings-reference#otelheadershelper)。配置了助手，每个信号保留在中继上。

859 878

860你命名的端点仅改变导出去往何处。你仍然使用 `OTEL_*_EXPORTER` 选择器选择哪些信号导出。879您命名的端点仅改变导出的去向。您仍然使用 `OTEL_*_EXPORTER` 选择器选择哪些信号导出。

861 880

862端点单独不打开导出，因此也设置做的变量，除非网关已经推送它们：881端点本身不打开导出，因此也设置执行此操作的变量，除非网关已经推送它们：

863 882

864* 如果网关已经[推送遥测变量](#telemetry)，它们覆盖启用、选择器和协议，你的显式端点覆盖推送的 `<public_url>` 值。仅为没有 `forward_to` 目标启用的信号自己设置 `OTEL_*_EXPORTER` 选择器为 `otlp`。883* 如果网关已经[推送遥测变量](#telemetry)，它们涵盖启用、选择器和协议，您的显式端点覆盖推送的 `<public_url>` 值。仅对于没有 `forward_to` 目的地启用的信号，自己设置 `OTEL_*_EXPORTER` 选择器为 `otlp`。

865* 如果它没有，也设置 `CLAUDE_CODE_ENABLE_TELEMETRY=1`、`OTEL_*_EXPORTER` 选择器和 `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`。884* 如果它没有，也设置 `CLAUDE_CODE_ENABLE_TELEMETRY=1`、`OTEL_*_EXPORTER` 选择器和 `OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`。

866 885

867当开发者登出，或登入到不同的网关，导出到收集器停止，Claude Code 删除每个剩余批次而不是发送它。886当开发者登出或登入不同的网关时，对收集器的导出停止，Claude Code 删除每个剩余批次而不是发送它。

868 887

869<h4 id="when-a-destination-fails">888<h4 id="when-a-destination-fails">

870 当目标失败时889 当目的地失败时

871</h4>890</h4>

872 891

873网关不缓冲、重试或存储遥测，因此它删除不到达目标的导出而不是晚期交付它。每个目标独立成功或失败，导出客户端无论如何接收成功响应，因此失败的交付仅在网关的日志中出现。892网关不缓冲、重试或存储遥测，因此它删除未到达目的地的导出而不是晚期交付它。每个目的地独立成功或失败，导出客户端无论如何都收到成功响应，因此失败的交付仅在网关的日志中出现。

874 893

875在五次连续失败交付到目标后，网关在 30 秒的拉伸中暂停转发到它，记录每个暂停，直到交付成功。任何错误响应、超时或连接错误计为失败的交付，除了 `400`、`413`、`415`、`422` 和 `431`，这意味着收集器拒绝该导出的有效负载为格式错误或太大。894在对目的地的五次连续失败交付后，网关在 30 秒的拉伸中暂停转发到它，记录每个暂停，直到交付成功。任何错误响应、超时或连接错误都计为失败的交付，除了 `400`、`413`、`415`、`422` 和 `431`，这意味着收集器拒绝了该导出的有效负载为格式错误或太大。

876 895

877被拒绝的有效负载既不推进也不重置失败计数：网关继续转发到目标并记录警告，命名它和状态，在目标的第一次拒绝和之后每一百次。896被拒绝的有效负载既不推进也不重置失败计数：网关继续转发到目的地并记录命名它和状态的警告，在目的地的第一次拒绝和之后每一百次。

878 897

879<h3 id="http-tuning">898<h3 id="http-tuning">

880 HTTP 调整899 HTTP 调整

883四个可选的顶级块，`access_control`、`limits`、`timeouts` 和 `rate_limits`，调整 HTTP 表面。默认值适合大多数部署。902四个可选的顶级块，`access_control`、`limits`、`timeouts` 和 `rate_limits`，调整 HTTP 表面。默认值适合大多数部署。

884 903

885| 块 | 键 | 默认 | 描述 |904| 块 | 键 | 默认 | 描述 |

886| ---------------- | ---------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |905| ---------------- | ---------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

887| `access_control` | `allow_cidrs` / `deny_cidrs` | 空 | 按客户端地址的入站 IP 允许/拒绝，在 `trusted_proxies` 解析后。`deny_cidrs` 首先检查；与它匹配的客户端被拒绝，即使 `allow_cidrs` 也匹配。如果 `allow_cidrs` 非空，网关是默认拒绝。`/healthz` 和 `/readyz` 免除 `allow_cidrs`。当受信任的代理发送不是 IP 地址的 `X-Forwarded-For` 条目时，真实客户端未知，网关记录一次警告命名要检查什么。其中任一列表适用于请求的地方，它以 `403` 和审计原因 `xff_unparseable` 拒绝它。其中都不适用的地方，它提供请求并使用代理自己的地址作为客户端 IP 用于每 IP 速率限制和审计。 |906| `access_control` | `allow_cidrs` / `deny_cidrs` | 空 | 入站 IP 允许/拒绝按客户端地址，在 `trusted_proxies` 解析后。`deny_cidrs` 首先检查；与它匹配的客户端被拒绝，即使 `allow_cidrs` 也匹配。如果 `allow_cidrs` 非空，网关是默认拒绝。`/healthz` 和 `/readyz` 免除 `allow_cidrs`。当受信任的代理发送不是 IP 地址的 `X-Forwarded-For` 条目时，真实客户端未知，网关记录一次警告，命名要检查的内容。其中任一列表适用于请求的地方，它以 `403` 和审计原因 `xff_unparseable` 拒绝它。其中都不适用的地方，它提供请求并使用代理自己的地址作为每 IP 速率限制和审计的客户端 IP。 |

892| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 未认证设备授权端点上的每 IP 速率限制。为共享出口 IP 或 NAT 后面的大型组织提高。这些限制仅适用于设备授权登录流，不适用于 `/v1/messages` 推理。请参阅[用户代码暴力破解抵抗](/docs/zh-CN/claude-apps-gateway-deploy#user-code-brute-force-resistance)。 |911| `rate_limits` | `device_authorization.max` / `.window_seconds` | 30 / 600 | 未认证设备授权端点上的每 IP 速率限制。为共享出口 IP 或 NAT 后面的大型组织提高。这些限制仅适用于设备授权登录流，不适用于 `/v1/messages` 推理。请参阅[用户代码暴力破解抵抗](/docs/zh-CN/claude-apps-gateway-deploy#user-code-brute-force-resistance)。 |

894 913

914如果您将两个 `access_control` 列表都留空，这是默认值，网关为任何客户端地址提供服务，因此只有您的网络限制谁可以到达它。这很重要，因为网关可以推送[托管设置](#managed)，在开发者机器上运行命令。

915

916虽然 `allow_cidrs` 为空，网关在两个地方警告，不改变它如何回答任何请求：

917

918* **在启动时**：操作日志中的警告建议仅允许私有范围 `10.0.0.0/8`、`172.16.0.0/12`、`192.168.0.0/16`、`100.64.0.0/10`、`127.0.0.0/8`、`::1/128` 和 `fc00::/7`，加上您的开发者连接的任何其他内部范围。如果您将网关绑定到环回地址并既不设置 `trusted_proxies` 也不设置 `public_url`，如在本地开发中，警告不出现。

919* **在运行时**：第一次请求从这些私有范围之外的地址到达时，网关记录警告并发出携带客户端 IP 的 [`access.public_client` 审计事件](/docs/zh-CN/claude-apps-gateway-deploy#logs)。两者每个进程触发一次。链接本地地址，`169.254.0.0/16` 和 `fe80::/10`，不计为公共。网关在此检查运行之前回答 `/healthz` 和 `/readyz`，因此来自公共范围的健康探针不触发它。

920

921两个信号都使用网关解析的客户端地址。如果负载均衡器、端口转发或隧道中继流量且未列在 `listen.trusted_proxies` 中，网关看到中继的地址，通常是私有的，因此既不是运行时警告也不是私有允许列表捕获通过它中继的流量。

922

923在这样的前端后面，首先设置 [`listen.trusted_proxies`](#listen)，以便网关看到真实的客户端地址，并保持网关和它前面的所有东西从公共互联网无法访问，无论如何。

924

895<h2 id="complete-example">925<h2 id="complete-example">

896 完整示例926 完整示例

897</h2>927</h2>

962# enforcement:992# enforcement:

963# fail_closed_on_error: false993# fail_closed_on_error: false

964 994

965# 按合同费率而不是美元列表价格计费。需要 admin:。995# 按合同费率而不是美元列表价格计费。需要 admin: 或

996# managed: 策略。使用 managed:，相同的费率也会发送到已登录的客户端。

966# 下面的费率是占位符，不是真实合同价格。997# 下面的费率是占位符，不是真实合同价格。

967# pricing:998# pricing:

968# multiplier: 0.85999# multiplier: 0.85

1062 1093

1063对于 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)。1094对于 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)。

1064 1095

1065[`forceLoginGatewayUrl`](/docs/zh-CN/settings-reference#forcelogingatewayurl) 和 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 的 `"gateway"` 值仅从机器上的托管源被尊重：`managed-settings.json`、macOS plist 或 Windows HKLM 注册表，或策略助手。开发者在自己的 `~/.claude/settings.json` 中设置它们无效，在网关有效负载中设置它们也无效。1096Claude 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` 中设置它们无效，在网关有效负载中设置它们也无效。

1066 1097

1067<h2 id="related">1098<h2 id="related">

1068 相关1099 相关

claude-apps-gateway-deploy.md +52 −43

Details

18如果在此过程中登录或启动失败，请直接转到 [故障排除](#troubleshooting)，该部分按您看到的错误进行索引。18如果在此过程中登录或启动失败，请直接转到 [故障排除](#troubleshooting)，该部分按您看到的错误进行索引。

19 19

20<Note>20<Note>

21 **在您的私有网络上部署。** Claude Code 仅连接到地址为私有的网关。这是一个安全防护，因为受信任的网关可以推送在开发者机器上运行命令的设置。将网关放在内部负载均衡器或 VPN 后面，并为其分配一个仅解析为私有 IP 的主机名。21 **在您的私有网络上部署。** Claude Code 仅连接到地址为私有的网关。这是一个安全防护，因为受信任的网关可以推送在开发者机器上运行命令的设置。将网关放在内部负载均衡器或 VPN 后面，并为其分配一个仅解析为私有 IP 的主机名。如果您的内部网络是从您的组织拥有的公共 IPv4 空间编号的，请参阅 [允许网关在您拥有的公共地址空间上运行](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)。

22</Note>22</Note>

23 23

24<h2 id="identity-provider-setup">24<h2 id="identity-provider-setup">

138 138

139网关向 stderr 写入两个流，都是 JSON 友好的：139网关向 stderr 写入两个流，都是 JSON 友好的：

140 140

141* **审计事件**：每个安全相关事件一行 JSON。将 stderr 管道传输到您的日志聚合器。发出的事件包括 `config.load`、`session.mint`、`session.refresh`、`device.authorize`、`device.verify`、`device.callback`、`auth.denied`、`access.denied`、`inference`、`managed.serve`、`desktop_bootstrap.serve`、`desktop_bootstrap.denied`、`spend.blocked`、`admin.denied`、`admin.limit.upsert` 和 `admin.limit.delete`。字段因事件而异：141* **审计事件**：每个安全相关事件一行 JSON。将 stderr 管道传输到您的日志聚合器。

142

143 发出的事件包括 `config.load`、`session.mint`、`session.refresh`、`device.authorize`、`device.verify`、`device.callback`、`auth.denied`、`access.denied`、`access.public_client`、`inference`、`managed.serve`、`desktop_bootstrap.serve`、`desktop_bootstrap.denied`、`spend.blocked`、`admin.denied`、`admin.limit.upsert` 和 `admin.limit.delete`。字段因事件而异：

144

142 * 成功的 mint 和 refresh 事件携带 `sub`、`email`、`client_ip` 和结果145 * 成功的 mint 和 refresh 事件携带 `sub`、`email`、`client_ip` 和结果

143 * `auth.denied` 和 `access.denied` 携带原因和客户端 IP，加上 `auth.denied` 的请求路径，因为在这些拒绝时不存在用户身份。两个 `access.denied` 原因改变事件携带的内容：146 * `auth.denied` 和 `access.denied` 携带原因和客户端 IP，加上 `auth.denied` 的请求路径，因为在这些拒绝时不存在用户身份。两个 `access.denied` 原因改变事件携带的内容：

144 * `xff_unparseable`：事件也携带无法读取的 `X-Forwarded-For` 条目147 * `xff_unparseable`：事件也携带无法读取的 `X-Forwarded-For` 条目

145 * `client_ip_unknown`：事件不携带客户端 IP，因为连接没有对等地址，而设置了 `access_control` 列表148 * `client_ip_unknown`：事件不携带客户端 IP，因为连接没有对等地址，而设置了 `access_control` 列表

149 * `access.public_client` 携带每个进程从公共地址到达的第一个请求的客户端 IP，而 `access_control.allow_cidrs` 为空。网关照常提供请求；该事件表示网关可能可从公共互联网访问。请参阅 [`access_control` 参考](/docs/zh-CN/claude-apps-gateway-config#http-tuning) 了解什么被视为公共以及推荐的允许列表。

146 * `inference` 记录哪个上游提供了请求以及响应状态150 * `inference` 记录哪个上游提供了请求以及响应状态

147 * `desktop_bootstrap.denied` 记录被拒绝的 Claude Desktop bootstrap 获取，包含原因（`not_configured`、`policy_not_opted_in` 或 `no_policy_matched`）和用户的身份151 * `desktop_bootstrap.denied` 记录被拒绝的 Claude Desktop bootstrap 获取，包含原因（`not_configured`、`policy_not_opted_in` 或 `no_policy_matched`）和用户的身份

148 * `admin.denied` 记录被拒绝的管理员 API 身份验证尝试，包括客户端 IP、方法、路径和原因，不包括呈现的密钥材料：当呈现了 `x-api-key` 但与配置的密钥不匹配时为 `invalid_key`，当仅呈现了 `Authorization` 标头且其未验证为 `admin.admin_groups` 中的网关会话时为 `bearer_rejected`，或当两个标头都未呈现时为 `no_credentials`152 * `admin.denied` 记录被拒绝的管理员 API 身份验证尝试，包括客户端 IP、方法、路径和原因，不包括呈现的密钥材料：当呈现了 `x-api-key` 但与配置的密钥不匹配时为 `invalid_key`，当仅呈现了 `Authorization` 标头且其未验证为 `admin.admin_groups` 中的网关会话时为 `bearer_rejected`，或当两个标头都未呈现时为 `no_credentials`

271 故障排除275 故障排除

272</h2>276</h2>

273 277

274有关问题和反馈，使用 [Claude Code 支持](https://support.claude.com/en/collections/14445694-claude-code)，或在 [Claude Code GitHub 存储库](https://github.com/anthropics/claude-code/issues) 上打开问题。报告问题时，包括：278如有问题和反馈，请使用 [Claude Code 支持](https://support.claude.com/en/collections/14445694-claude-code)，或在 [Claude Code GitHub 仓库](https://github.com/anthropics/claude-code/issues)上提交问题。报告问题时，请包括：

~~275~~ 279

276* **网关问题**：相关窗口的网关 stderr、您的 `gateway.yaml`（密钥已编辑），网关版本，显示在 `/` 处的登陆页面和 `/managed/settings` 上的 `x-cc-gateway-version` 响应标头中，以及最近更改的内容280* **Gateway 问题**：相关窗口的 gateway stderr、你的 `gateway.yaml`（已隐藏密钥）、gateway 版本（显示在 `/` 的登陆页面和 `/managed/settings` 的 `x-cc-gateway-version` 响应头中），以及最近的更改

277* **登录问题**：开发者运行 `claude --debug-file ./claude-debug.txt`，重现，并发送该文件加上相同窗口的网关审计日志281* **登录问题**：开发者运行 `claude --debug-file ./claude-debug.txt`、重现问题，然后发送该文件以及同一窗口的 gateway 审计日志

278* **推理问题**：请求的模型、配置的上游和请求的网关审计日志，记录哪个上游提供了它和响应状态282* **推理问题**：请求的模型、配置的上游服务，以及请求的 gateway 审计日志，其中记录了哪个上游提供了服务以及响应状态

~~279~~ 283

280网关的 stderr 包含审计事件流，审计日志记录开发者身份，调试文件记录来自开发者机器的 hook 和 MCP 服务器输出。在发布到公开问题前，请审查并隐去这些信息。284gateway 的 stderr 包含审计事件流，审计日志记录开发者身份，调试文件记录来自开发者机器的 hook 和 MCP 服务器输出。在发布到公开问题前，请审查并隐藏这些内容。

~~281~~ 285

282| 症状 | 原因 | 修复 |286| 症状 | 原因 | 解决方案 |

283| ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |287| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

284| 开发者的 `/login` 显示标准账户选择器而不是 **Cloud gateway** 屏幕 | `forceLoginMethod` 或 `forceLoginGatewayUrl` 未在该机器的托管设置中设置 | 将 [托管设置文件](/docs/zh-CN/claude-apps-gateway#set-the-gateway-url) 部署到设备；`/login` 从那里读取网关 URL |288| 开发者的 `/login` 显示标准账户选择器而不是 **Cloud gateway** 屏幕 | 该机器的托管设置中未设置 `forceLoginMethod` 或 `forceLoginGatewayUrl` | 将[托管设置文件](/docs/zh-CN/claude-apps-gateway#set-the-gateway-url)部署到设备；`/login` 从那里读取 gateway URL |

285| 开发者的请求失败，显示 `Not signed in to the Cloud gateway — run /login.` | 机器的托管设置设置 `forceLoginMethod: "gateway"` 或 `forceLoginGatewayUrl`，会话没有网关登录。剩余的 claude.ai 登录不满足要求。 | 让开发者运行 `/login` 并完成网关登录。另请参阅 [管理员策略需要 Cloud gateway 登录](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。 |289| 开发者的请求失败，显示 `Not signed in to the Cloud gateway — run /login.` | 机器的托管设置设置了 `forceLoginMethod: "gateway"` 或 `forceLoginGatewayUrl`，且会话没有 gateway 登录。残留的 claude.ai 登录不满足要求。 | 让开发者运行 `/login` 并完成 gateway 登录。另请参阅[管理员策略需要 Cloud gateway 登录](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。 |

286| Claude Desktop 报告其引导配置无法获取 | `/user/bootstrap` 返回 404：与用户匹配的策略不包含 `desktop` 密钥，或没有策略匹配。网关的审计日志将每个拒绝记录为 `desktop_bootstrap.denied`，并说明原因。 | 将 `desktop` 块添加到与用户匹配的策略，或添加到 `match: {}` 基础层；空的 `desktop: {}` 就足够了。请参阅 [Claude Desktop 覆盖](/docs/zh-CN/claude-apps-gateway-config#claude-desktop-overlay)。 |290| Claude Desktop 报告其引导配置无法获取 | `/user/bootstrap` 返回 404：与用户匹配的策略不包含 `desktop` 密钥，或没有策略匹配。gateway 的审计日志将每次拒绝记录为 `desktop_bootstrap.denied` 并说明原因。 | 将 `desktop` 块添加到与用户匹配的策略，或添加到 `match: {}` 基础层；空的 `desktop: {}` 就足够了。请参阅 [Claude Desktop 覆盖](/docs/zh-CN/claude-apps-gateway-config#claude-desktop-overlay)。 |

287| 启动显示 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | 安装的 Claude Code 构建早于网关支持 | 让开发者更新 Claude Code 到包括 Cloud gateway 支持的版本 |291| 启动显示 `Gateway login is configured in managed settings, but this Claude Code build does not include Cloud gateway support.` | 已安装的 Claude Code 版本早于 gateway 支持 | 让开发者更新 Claude Code 到包含 Cloud gateway 支持的版本 |

288| 启动或 `/login` 在托管设置加载上返回 403 后报告 `Claude Code may not be enabled for your organization` | 网关或其前面的某些东西用 403 回答了 `/managed/settings` 请求。网关自己的设置路由从不回答 403。状态来自 [`access_control`](/docs/zh-CN/claude-apps-gateway-config#http-tuning) IP 检查或网关前面的代理或 WAF。审计日志将 IP 检查拒绝记录为 `access.denied`，并说明原因。开发者保持登录状态。 | 检查审计日志中失败时的 `access.denied`，修复 `access_control` 列表或前端，然后让开发者再次启动 `claude` |292| 启动退出，显示 `Administrator policy requires a Cloud gateway sign-in on this machine` | 开发者的环境设置了 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，其设置配置了 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper)，或来自早期 Claude Console 登录的 API 密钥仍然保存 | 让开发者清除每个适用的项：取消设置变量、删除 `apiKeyHelper` 条目，或运行 `claude auth logout` 删除保存的密钥。然后让他们启动 `claude` 并使用 `/login` 登录。另请参阅[管理员策略需要 Cloud gateway 登录](/docs/zh-CN/errors#administrator-policy-requires-a-cloud-gateway-sign-in)。 |

289| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | 网关主机名解析为至少一个公共 IP 地址。Claude Code 检查每个解析的地址，需要每一个都是私有的。常见原因是一个双栈名称，其中一个族解析为公共地址，包括 AWS 内部双栈负载均衡器，它们返回公共范围 AAAA 地址。 | 让网关名称在开发者机器上仅解析为私有地址。对于双栈名称，删除公共范围记录或提供单独的仅内部 DNS 名称。请参阅 [私有网络先决条件](/docs/zh-CN/claude-apps-gateway#prerequisites)。 |293| 启动或 `/login` 在托管设置加载时返回 403 后报告 `Claude Code may not be enabled for your organization` | gateway 或其前面的某个组件用 403 响应了 `/managed/settings` 请求。gateway 自身的设置路由从不返回 403。状态来自 [`access_control`](/docs/zh-CN/claude-apps-gateway-config#http-tuning) IP 检查或 gateway 前面的代理或 WAF。审计日志将 IP 检查拒绝记录为 `access.denied` 并说明原因。开发者保持登录状态。 | 检查审计日志中失败时的 `access.denied`，修复 `access_control` 列表或前端，然后让开发者再次启动 `claude` |

290| CLI `/login`：`Gateway login would go through proxy <proxy>, which is not on a private network` | `HTTPS_PROXY` 或 `HTTP_PROXY` 适用于网关主机，代理的主机名解析为公共地址。代理的主机解析为仅私有地址是允许的，不会触发此错误 | 在开发者的机器上将网关主机添加到 `NO_PROXY`，以便连接是直接的，或使用主机名解析为私有地址的代理。消息命名要添加的确切 `NO_PROXY` 条目 |294| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | gateway 主机名解析为至少一个公网 IP 地址。Claude Code 检查每个解析的地址，要求每个都是私网。常见原因是双栈名称，其中一个族解析为公网地址，包括 AWS 内部双栈负载均衡器，它们返回公网范围的 AAAA 地址。 | 让 gateway 名称在开发者机器上仅解析为私网地址。对于双栈名称，删除公网范围的记录或提供单独的仅内部 DNS 名称。请参阅[私网先决条件](/docs/zh-CN/claude-apps-gateway#prerequisites)。如果地址是你的组织拥有并在内部使用的公网空间，请[声明该块](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)。 |

291| CLI `/login`：`Could not resolve the configured HTTP proxy` | `HTTPS_PROXY` 或 `HTTP_PROXY` 中的主机名无法从开发者的机器解析，通常是因为它未连接到公司网络 | 让开发者连接到您的网络或 VPN 并重试，或修复代理 URL |295| CLI `/login`：`Gateway login would go through proxy <proxy>, which is not on a private network` | `HTTPS_PROXY` 或 `HTTP_PROXY` 适用于 gateway 主机，且代理的主机名解析为公网地址。主机名仅解析为私网地址的代理是允许的，不会触发此错误 | 在开发者的机器上将 gateway 主机添加到 `NO_PROXY`，以便连接是直接的，或使用主机名解析为私网地址的代理。消息会命名要添加的确切 `NO_PROXY` 条目 |

292| CLI `/login`：`Could not resolve gateway host <host>` | 机器无法解析网关的内部 DNS 名称，通常是因为它不在公司网络上 | 让开发者连接到您的网络或 VPN，然后重试 `/login` |296| CLI `/login`：`Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | gateway 在 [`gatewayInternalNetworks`](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) 中声明的块上，开发者的机器从该块外的地址到达它：VPN 地址池、容器或 WSL2 NAT 段，或不是你的网络 | 让开发者从你的网络上的主机 OS 运行 `/login`。如果显示的地址也是你的组织自己的公网空间，将 gateway 的条目替换为覆盖两者的块，最多 `/8`；第二个重叠条目会被拒绝 |

293| 启动退出，配置验证错误命名 `store.postgres_url` | 未配置 Postgres；网关需要 Postgres | 设置 `store.postgres_url`。对于本地开发，使用一次性容器：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |297| CLI `/login`：`Every address for gateway host <host> must be inside its declared network <block>, and it also resolves to <ip>` | gateway 的名称解析为 [`gatewayInternalNetworks`](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) 中声明的块外的地址：第二个站点，或双栈名称上的 IPv6 记录。在声明的块下，每条记录都必须在该单个 IPv4 块内，包括私网和 IPv6 地址 | 在开发者机器上仅为 gateway 名称发布块内的记录，或提供单独的仅内部名称 |

295| 启动退出，OIDC 发现错误在 `config.load` 之后 | `oidc.issuer` 无法到达，或 TLS 链不受信任 | 检查发行者是否可从 pod 到达并提供 `/.well-known/openid-configuration`。为私有 PKI 设置 `ca_cert_pem`。如果 pod 仅通过前向代理到达 IdP，设置 [`oidc.use_proxy: true`](/docs/zh-CN/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)；在 v2.1.227 之前的版本上，改为给 pod 一条到 IdP 每个端点的直接路由。 |299| CLI `/login`：消息以 `gatewayInternalNetworks in managed settings` 开头 | 该值违反了[验证规则](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)之一，消息会命名哪一个。在你修复它之前，Claude Code 拒绝机器上的每个新 gateway `/login`，包括私网上的 gateway；现有登录保持工作 | 在你部署的托管设置源中，更正消息命名的条目，然后重新运行 `/login` |

297| `/oauth/callback` 显示"Sign-in could not be completed" | 电子邮件域被拒绝，id\_token 验证失败，或 `email_verified` 明确为 `false`，网关总是拒绝，没有覆盖 | 检查 `allowed_email_domains` 和 IdP 返回验证的 `email` 声明。对于 `email_verified: false`，修复 IdP 端验证。如果您的 IdP 在不同的声明名称下发出电子邮件，设置 `oidc.email_claim`。 |301| CLI `/login`：`Could not resolve gateway host <host>` | 机器无法解析 gateway 的内部 DNS 名称，通常是因为它不在公司网络上 | 让开发者连接到你的网络或 VPN，然后重试 `/login` |

298| 日志：`token exchange failed request_id=<id>: id_token missing email claim` | IdP 默认不在 id\_token 中包含 `email`。此拒绝仅在设置 `allowed_email_domains` 时触发；没有它，缺失的电子邮件铸造没有电子邮件的会话 | 配置 IdP 在 id\_token 中发出 `email`。Okta：将 `email` 添加到自定义授权服务器的 ID 令牌声明。Entra：在应用注册上将 `email` 添加为可选声明。PingFederate：启用发出 `email` 的 OpenID Connect 策略。如果 IdP 从 userinfo 端点提供 `email` 但不会在 id\_token 中包含它，如 Okta 组织授权服务器，设置 `oidc.userinfo_fallback: true`。 |302| 启动退出，显示配置验证错误，命名 `store.postgres_url` | 未配置 Postgres；gateway 需要 Postgres | 设置 `store.postgres_url`。对于本地开发，使用一次性容器：`docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`。 |

299| 日志：`refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`，开发者每 `session.ttl_hours` 看到 `Cloud gateway session expired` | IdP 接受了刷新令牌但没有随之返回 id\_token，所以网关询问了 IdP 的 userinfo 端点以获取用户的声明。IdP 在那里拒绝了刷新的访问令牌。网关回答 `temporarily_unavailable`，所以 Claude Code 保留刷新令牌但无法续订会话。v2.1.260 之前的网关版本记录相同的行，但没有 `(at …)` 详情。 | 设置 [`oidc.scope_on_refresh: true`](/docs/zh-CN/claude-apps-gateway-config#oidc)，在网关 v2.1.260 或更高版本中可用，以便刷新请求再次请求 `openid`。某些 IdP（如 Okta）仅在被要求时在刷新时返回 id\_token。在 PingFederate 上，改为在 **Applications > OAuth > OpenID Connect Policy Management** 下启用 **Return ID Token On Refresh Grant**。该密钥不会改变 PingFederate 的行为。对于仍然省略它的其他 IdP，检查 userinfo 端点是否接受由刷新发行的访问令牌。作为临时措施，提高 [`session.ttl_hours`](/docs/zh-CN/claude-apps-gateway-config#session)。请参阅 [身份提供者设置](#identity-provider-setup) 了解取消配置权衡。 |303| 启动退出：`requires the native binary` | 在 Node 下运行而不是本地二进制 | 使用[独立安装方法](/docs/zh-CN/setup)之一安装 Claude Code |

300| 每个 Amazon Bedrock 请求返回 502；日志显示 `Could not load credentials from any providers` | 在 EC2 上，IMDSv2 的默认跳数限制为 1 阻止来自容器内的实例元数据请求。启动和 `/readyz` 通过，因为 AWS SDK 在第一个请求时解析实例凭证，而不是在客户端构造时 | 使用 `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2` 提高跳数限制，或在启动模板中设置它。更改适用于实例上的每个容器。在可用的地方优先使用 ECS 任务角色，它从 ECS 容器凭证端点读取凭证，完全避免更改，或在专用网关实例上应用更改以限制暴露。 |304| 启动退出，在 `config.load` 后显示 OIDC 发现错误 | `oidc.issuer` 无法访问，或 TLS 链不受信任 | 检查发行者是否可从 pod 访问并提供 `/.well-known/openid-configuration`。为私有 PKI 设置 `ca_cert_pem`。如果 pod 仅通过前向代理到达 IdP，设置 [`oidc.use_proxy: true`](/docs/zh-CN/claude-apps-gateway-config#idp-requests-through-a-forward-proxy)；在 v2.1.227 之前的版本上，改为给 pod 一条到 IdP 每个端点的直接路由。 |

302| 设置 `oidc.scopes` 后会话不无声续订 | `offline_access` 从覆盖中删除 | 如果您的 IdP 支持，添加 `offline_access` 回来。没有刷新令牌，开发者每 `session.ttl_hours` 重新运行浏览器登录。 |306| `/oauth/callback` 显示"Sign-in could not be completed" | 电子邮件域被拒绝、id\_token 验证失败，或 `email_verified` 显式为 `false`，gateway 总是拒绝且无覆盖 | 检查 `allowed_email_domains` 和 IdP 是否返回已验证的 `email` 声明。对于 `email_verified: false`，修复 IdP 端验证。如果你的 IdP 在不同的声明名称下发出电子邮件，设置 `oidc.email_claim`。 |

303| 浏览器显示"This request came from another site and was blocked" | 跨站点表单 POST，作为 CSRF 保护被阻止。对于嵌入或代理页面是预期的 | 直接打开验证链接 |307| 日志：`token exchange failed request_id=<id>: id_token missing email claim` | IdP 默认不在 id\_token 中包含 `email`。此拒绝仅在设置 `allowed_email_domains` 时触发；没有它，缺少的电子邮件会创建没有电子邮件的会话 | 配置 IdP 在 id\_token 中发出 `email`。Okta：将 `email` 添加到自定义授权服务器的 ID 令牌声明。Entra：在应用注册上添加 `email` 作为可选声明。PingFederate：启用发出 `email` 的 OpenID Connect 策略。如果 IdP 从 userinfo 端点提供 `email` 但不会在 id\_token 中包含它，例如 Okta 组织授权服务器，设置 `oidc.userinfo_fallback: true`。 |

304| Chrome 用"Refused to send form data … violates … Content Security Policy directive: form-action"阻止"批准"按钮，但相同页面在 Safari 或 Firefox 中工作 | Chrome 对整个重定向链强制执行 `form-action`。您的 IdP 重定向到第二个主机，该主机未被列入白名单。 | 在 `oidc.form_action_origins` 中添加重定向链中的每个额外源。在"批准"页面上打开 Chrome DevTools → 控制台以查看哪个源被阻止。 |308| 日志：`refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`，开发者每 `session.ttl_hours` 看到 `Cloud gateway session expired` | IdP 接受了刷新令牌但没有随之返回 id\_token，所以 gateway 询问了 IdP 的 userinfo 端点以获取用户的声明。IdP 在那里拒绝了刷新的访问令牌。gateway 回答 `temporarily_unavailable`，所以 Claude Code 保留刷新令牌但无法续订会话。v2.1.260 之前的 gateway 版本记录相同的行但没有 `(at …)` 详情。 | 设置 [`oidc.scope_on_refresh: true`](/docs/zh-CN/claude-apps-gateway-config#oidc)，在 gateway v2.1.260 或更高版本中可用，以便刷新请求再次请求 `openid`。某些 IdP（如 Okta）仅在被要求时在刷新时返回 id\_token。在 PingFederate 上，改为在 **Applications > OAuth > OpenID Connect Policy Management** 下启用 **Return ID Token On Refresh Grant**。该密钥不会改变 PingFederate 的行为。对于仍然省略它的其他 IdP，检查 userinfo 端点是否接受由刷新发出的访问令牌。作为临时措施，提高 [`session.ttl_hours`](/docs/zh-CN/claude-apps-gateway-config#session)。请参阅[身份提供者设置](#identity-provider-setup)了解取消配置权衡。 |

305| 登录在 IdP 处完成，但回调失败，Chrome 中出现 CSP 错误或 Safari 中出现"this sign-in link has expired" | IdP 通过 `response_mode=form_post` 返回代码，它通过 POST 自动提交到 `/oauth/callback`。Chrome 在严格 CSP 下阻止它；Safari 允许提交，但回调仅读取查询字符串。 | 确保您的 IdP 遵守 `response_mode=query`，网关明确请求它，以便回调是普通重定向 |309| 每个 Amazon Bedrock 请求都返回 502；日志显示 `Could not load credentials from any providers` | 在 EC2 上，IMDSv2 的默认跳数限制为 1，阻止了来自容器内的实例元数据请求。启动和 `/readyz` 仍然通过，因为 AWS SDK 在第一个请求时解析实例凭证，而不是在客户端构造时 | 使用 `aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2` 提高跳数限制，或在启动模板中设置它。更改适用于实例上的每个容器。在可用的地方优先使用 ECS 任务角色，它们从 ECS 容器凭证端点读取凭证并完全避免更改，或在专用 gateway 实例上应用更改以限制暴露。 |

308| CLI `/login`："Could not verify the gateway's TLS certificate" 或 `SELF_SIGNED_CERT_IN_CHAIN` | 网关的 TLS 链由 CLI 主机的信任存储中不存在的私有 CA 签署 | Claude Code 默认在本机二进制文件上读取 OS 信任存储，在 Node 22.15 或更高版本上；[`CLAUDE_CODE_CERT_STORE`](/docs/zh-CN/network-config#ca-certificate-store) 控制此行为。如果 CA 安装在 OS 信任存储中，确保开发者在当前运行时上。否则在启动前将 `NODE_EXTRA_CA_CERTS` 设置为 CA 证书 PEM。首次连接指纹提示仍然适用。 |312| 浏览器显示"This request came from another site and was blocked" | 跨站点表单 POST，作为 CSRF 保护被阻止。对于嵌入或代理的页面是预期的 | 直接打开验证链接 |

309| CLI `/login` 完成浏览器登录，然后会话以 `Cloud gateway sign-in was not completed` 和 TLS 证书不匹配结束 | 在登录后的第一个请求上，网关呈现了与 Claude Code 固定的指纹不匹配的证书，所以 Claude Code 没有保留网关凭证。常见原因是一个地址后面的副本提供不同的证书，或网络路径上的某些东西拦截 TLS。 | 为主机名提供一个证书，例如在入口处终止 TLS 一次，然后让开发者再次运行 `/login`。如果该证书与固定的不同，Claude Code 在 [信任提示](/docs/zh-CN/claude-apps-gateway#connect-developers) 处显示警告证书已更改。 |313| Chrome 用"Refused to send form data … violates … Content Security Policy directive: form-action"阻止"Approve"按钮，但相同的页面在 Safari 或 Firefox 中工作 | Chrome 对整个重定向链强制执行 `form-action`。你的 IdP 重定向到第二个主机，该主机未被列入白名单。 | 将重定向链中的每个额外来源添加到 `oidc.form_action_origins`。在"Approve"页面上打开 Chrome DevTools → Console 以查看哪个来源被阻止。 |

310| CLI `/login` 停止，显示 `The gateway's TLS certificate changed during sign-in: it no longer matches the one you trusted` | 登录请求到达了一个服务器，其证书与开发者在 `/login` 开始时接受的证书不匹配：一个地址后面的副本提供不同的证书，路径上的 TLS 拦截，或登录进行中的证书轮换。 | 为主机名提供一个证书，然后让开发者再次启动登录并在 [信任提示](/docs/zh-CN/claude-apps-gateway#connect-developers) 处审查新证书。 |314| 登录在 IdP 处完成但回调失败，Chrome 中出现 CSP 错误或 Safari 中出现"this sign-in link has expired" | IdP 通过 `response_mode=form_post` 返回了代码，它通过 POST 自动提交到 `/oauth/callback`。Chrome 在严格 CSP 下阻止了这个；Safari 允许提交但回调仅读取查询字符串。 | 确保你的 IdP 遵守 `response_mode=query`，gateway 明确请求它以便回调是普通重定向 |

~~311~~ 315| 登录在本地工作但在 ALB 后面失败 | `public_url` 仍然命名本地或内部 `http://` 来源，所以 IdP 获得了错误的 `redirect_uri` | 将 `listen.public_url` 设置为外部 `https://` 来源，并向 IdP 注册 `<public_url>/oauth/callback` |

312`Cloud gateway sign-in was not completed` 消息命名网关主机名。当 Claude Code 同时拥有固定指纹和呈现的指纹时，消息还显示每个的前 16 个字符。316| 开发者重复看到信任提示 | TLS 证书按副本或按请求轮换 | 在入口处使用稳定的证书，或终止 TLS 一次并在内部通过普通 HTTP 运行副本 |

~~313~~ 317| CLI `/login`："Could not verify the gateway's TLS certificate"或 `SELF_SIGNED_CERT_IN_CHAIN` | gateway 的 TLS 链由 CLI 主机的信任存储中不存在的私有 CA 签名 | Claude Code 在本地二进制上默认读取 OS 信任存储，在 Node 22.15 或更高版本上；[`CLAUDE_CODE_CERT_STORE`](/docs/zh-CN/network-config#ca-certificate-store) 控制此行为。如果 CA 安装在 OS 信任存储中，确保开发者使用当前运行时。否则在启动前将 `NODE_EXTRA_CA_CERTS` 设置为 CA 证书 PEM。首次连接指纹提示仍然适用。 |

314如果 Claude Code 在网关登录后报告 `couldn't load your organization's managed settings`，Claude Code 命名原因，就地重启，并恢复对话。如果 Claude Code 无法重启，例如在后台会话中，Claude Code 结束会话并保留登录。318| CLI `/login` 完成浏览器登录，然后会话以 `Cloud gateway sign-in was not completed` 和 TLS 证书不匹配结束 | 在登录后的第一个请求中，gateway 提供了与 Claude Code 固定的指纹不匹配的证书，所以 Claude Code 没有保留任何 gateway 凭证。常见原因是一个地址后面的副本提供不同的证书，或网络路径上的某个东西拦截了 TLS。 | 为主机名提供一个证书，例如在入口处终止 TLS 一次，然后让开发者再次运行 `/login`。如果该证书与固定的不同，Claude Code 会在[信任提示](/docs/zh-CN/claude-apps-gateway#connect-developers)处显示警告，说明证书已更改。 |

319| CLI `/login` 停止，显示 `The gateway's TLS certificate changed during sign-in: it no longer matches the one you trusted` | 登录请求到达了一个证书与开发者在 `/login` 启动时接受的证书不匹配的服务器：一个地址后面的副本提供不同的证书、路径上的 TLS 拦截，或登录进行中的证书轮换。 | 为主机名提供一个证书，然后让开发者再次启动登录并在[信任提示](/docs/zh-CN/claude-apps-gateway#connect-developers)处审查新证书。 |

320

321`Cloud gateway sign-in was not completed` 消息命名 gateway 主机名。当 Claude Code 同时拥有固定指纹和呈现的指纹时，消息还显示每个的前 16 个字符。

322

323如果 Claude Code 在 gateway 登录后报告 `couldn't load your organization's managed settings`，Claude Code 会命名原因、就地重启并恢复对话。如果 Claude Code 无法重启，例如在后台会话中，Claude Code 会结束会话并保留登录。

315 324

316<h2 id="related">325<h2 id="related">

317 相关326 相关

claude-apps-gateway-on-gcp.md +63 −62

Details

4 4

5# 在 Google Cloud 上部署 Claude apps gateway5# 在 Google Cloud 上部署 Claude apps gateway

6 6

~~7> 在 Google Cloud 上运行 Claude apps gateway 的实际示例：Cloud Run 或 GKE、Cloud SQL for PostgreSQL、Secret Manager 和 Agent Platform 的服务账户身份验证。~~7> 在 Google Cloud 上运行 Claude apps gateway 的实际示例：Cloud Run 或 GKE、Cloud SQL for PostgreSQL、Secret Manager 和 Google Cloud 的 Agent Platform 的服务账户身份验证。

8 8

9<Note>9<Note>

10 本页介绍在 Google Cloud 上运行 Claude apps gateway 的一种方式。该配置是客户管理基础设施的工作示例，而不是受支持的生产部署；使用它来了解各个部分如何组合在一起，然后再根据您自己的环境进行调整。有关平台无关的要求，请参阅[部署指南](/zh-CN/claude-apps-gateway-deploy)。10 本页介绍在 Google Cloud 上运行 Claude apps gateway 的一种方式。该配置是客户管理基础设施的工作示例，而不是受支持的生产部署；使用它来了解各个部分如何组合在一起，然后再根据您自己的环境进行调整。有关平台无关的要求，请参阅[部署指南](/docs/zh-CN/claude-apps-gateway-deploy)。

11</Note>11</Note>

12 12

13此示例在 Google Cloud 上配置 Claude apps gateway，使用 Google Cloud 的 Agent Platform 作为模型上游，使用 Cloud Run 或 GKE 进行计算。Google Workspace 是示例身份提供商 (IdP)，但任何符合 OpenID Connect (OIDC) 的 IdP 都可以工作；只有 `oidc` 块会改变。有关每个 IdP 的详细信息，请参阅[身份提供商设置](/zh-CN/claude-apps-gateway-deploy#identity-provider-setup)。13此示例在 Google Cloud 上配置 Claude apps gateway，使用 Google Cloud 的 Agent Platform 作为模型上游，使用 Cloud Run 或 GKE 进行计算。Google Workspace 是示例身份提供商 (IdP)，但任何符合 OpenID Connect (OIDC) 的 IdP 都可以工作；只有 `oidc` 块会改变。有关每个 IdP 的详细信息，请参阅[身份提供商设置](/docs/zh-CN/claude-apps-gateway-deploy#identity-provider-setup)。

14 14

15<h2 id="what-you’ll-build">15<h2 id="what-you’ll-build">

16 您将构建的内容16 您将构建的内容

20 <img src="https://mintcdn.com/claude-code/-uq-4JE0W_JO5Er5/images/claude-gateway-gcp-architecture.svg?fit=max&auto=format&n=-uq-4JE0W_JO5Er5&q=85&s=cb705151c69128ac0da235852d5600ab" alt="Google Cloud 上 Claude apps gateway 的图表：Claude Code 客户端通过 HTTPS 连接到网关（Cloud Run 或 GKE），网关在 VPC 内运行，旁边是用于会话状态的私有 IP Cloud SQL 数据库。网关通过 OIDC 针对 Google Workspace 对用户进行签名，从 Secret Manager 读取配置和机密，将模型请求转发到 Google Cloud 的 Agent Platform，并在部署时从 Artifact Registry 拉取其镜像。" width="760" height="400" data-path="images/claude-gateway-gcp-architecture.svg" />20 <img src="https://mintcdn.com/claude-code/-uq-4JE0W_JO5Er5/images/claude-gateway-gcp-architecture.svg?fit=max&auto=format&n=-uq-4JE0W_JO5Er5&q=85&s=cb705151c69128ac0da235852d5600ab" alt="Google Cloud 上 Claude apps gateway 的图表：Claude Code 客户端通过 HTTPS 连接到网关（Cloud Run 或 GKE），网关在 VPC 内运行，旁边是用于会话状态的私有 IP Cloud SQL 数据库。网关通过 OIDC 针对 Google Workspace 对用户进行签名，从 Secret Manager 读取配置和机密，将模型请求转发到 Google Cloud 的 Agent Platform，并在部署时从 Artifact Registry 拉取其镜像。" width="760" height="400" data-path="images/claude-gateway-gcp-architecture.svg" />

21</Frame>21</Frame>

22 22

~~23参考配置配置以下内容：~~23部署包括：

24 24

25* **Cloud Run** 服务或 **GKE** Deployment 运行网关容器25* **Cloud Run** 服务或 **GKE** Deployment 运行网关容器

26* **Artifact Registry** 存储库用于网关镜像26* **Artifact Registry** 存储库用于网关镜像

~~27* **Cloud SQL for PostgreSQL** 实例，仅限私有 IP，用于网关的[存储](/zh-CN/claude-apps-gateway-config#store)~~27* **Cloud SQL for PostgreSQL** 实例，仅限私有 IP，用于网关的[存储](/docs/zh-CN/claude-apps-gateway-config#store)

28* **Secret Manager** 机密用于 `gateway.yaml`、JWT 签名密钥、OIDC 客户端机密和 Postgres URL28* **Secret Manager** 机密用于 `gateway.yaml`、JWT 签名密钥、OIDC 客户端机密和 Postgres URL

29* **服务账户**，具有 `roles/aiplatform.user`，直接附加到 Cloud Run 或通过 Workload Identity 绑定到 GKE29* **服务账户**，具有 `roles/aiplatform.user`，直接附加到 Cloud Run 或通过 Workload Identity 绑定到 GKE

~~30* **内部应用负载均衡器**在 Cloud Run 上，或在 GKE 上的内部 **GKE Ingress**，类别为 `gce-internal`，用于 HTTPS~~30* **HTTPS 前端**，由您提供：Cloud Run 前面的内部应用负载均衡器，本演练为网关配置但不创建，或 GKE 上类别为 `gce-internal` 的内部 **GKE Ingress**

31 31

32<h2 id="prerequisites">32<h2 id="prerequisites">

33 前置条件33 前置条件

37* `gcloud` CLI，使用 `gcloud auth login` 进行身份验证，并在本地安装了 Docker37* `gcloud` CLI，使用 `gcloud auth login` 进行身份验证，并在本地安装了 Docker

38* 对于 GKE 路径：`kubectl` 和在下面演练中创建的 VPC 上的 GKE 集群38* 对于 GKE 路径：`kubectl` 和在下面演练中创建的 VPC 上的 GKE 集群

39* 在 Model Garden 中访问您需要的 Claude 模型，在发布这些模型的区域中39* 在 Model Garden 中访问您需要的 Claude 模型，在发布这些模型的区域中

40* Google Workspace OAuth 2.0 网络应用程序客户端，重定向 URI 为 `https://<gateway-host>/oauth/callback`；请参阅[身份提供商设置](/zh-CN/claude-apps-gateway-deploy#identity-provider-setup)40* Google Workspace OAuth 2.0 网络应用程序客户端，重定向 URI 为 `https://<gateway-host>/oauth/callback`；请参阅[身份提供商设置](/docs/zh-CN/claude-apps-gateway-deploy#identity-provider-setup)

41* 网关的 TLS 主机名，通常是指向负载均衡器的内部 DNS 名称41* 网关的 TLS 主机名，通常是指向负载均衡器的内部 DNS 名称

42 42

43设置项目和区域一次：43设置项目和区域一次：

52 部署网关52 部署网关

53</h2>53</h2>

54 54

~~55下面的步骤使用 `gcloud` 命令配置完整的部署。~~55以下步骤使用 `gcloud` 命令配置完整部署。

56 56

57<Steps>57<Steps>

58 <Step title="启用 API">58 <Step title="启用 API">

72 container.googleapis.com72 container.googleapis.com

73 ```73 ```

74 74

~~75 您需要的 API 取决于部署路径：~~75 所需的 API 取决于部署路径：

76 76

77 * `compute` 和 `servicenetworking`：私有 IP Cloud SQL 路径所需77 * `compute` 和 `servicenetworking`：私有 IP Cloud SQL 路径所需

78 * `run`：仅限 Cloud Run78 * `run`：仅限 Cloud Run

80 </Step>80 </Step>

81 81

82 <Step title="创建服务账户并授予 IAM">82 <Step title="创建服务账户并授予 IAM">

~~83 网关作为专用服务账户运行，具有调用 Google Cloud 的 Agent Platform 的权限。它通过 VPC 使用密码用户到达 Cloud SQL，因此不需要 Cloud SQL IAM 角色：~~83 网关作为专用服务账户运行，有权调用 Google Cloud 的 Agent Platform。它通过 VPC 使用密码用户访问 Cloud SQL，因此不需要 Cloud SQL IAM 角色：

84 84

85 ```bash theme={null}85 ```bash theme={null}

86 gcloud iam service-accounts create claude-gateway --display-name="Claude apps gateway"86 gcloud iam service-accounts create claude-gateway --display-name="Claude apps gateway"

94 </Step>94 </Step>

95 95

96 <Step title="构建镜像并将其推送到 Artifact Registry">96 <Step title="构建镜像并将其推送到 Artifact Registry">

~~97 根据[容器镜像要求](/zh-CN/claude-apps-gateway-deploy#container-image)构建镜像，使用 `linux-x64` glibc 二进制文件，并推送它：~~97 根据[容器镜像要求](/docs/zh-CN/claude-apps-gateway-deploy#container-image)构建镜像，使用 `linux-x64` glibc 二进制文件，然后推送：

98 98

99 ```bash theme={null}99 ```bash theme={null}

100 gcloud artifacts repositories create claude-gateway \100 gcloud artifacts repositories create claude-gateway \

101 --repository-format=docker --location="$REGION"101 --repository-format=docker --location="$REGION"

102 gcloud auth configure-docker "${REGION}-docker.pkg.dev" --quiet102 gcloud auth configure-docker "${REGION}-docker.pkg.dev" --quiet

103 103

104 # Cloud Run requires linux/amd64. --provenance=false avoids a buildx OCI104 # Cloud Run 需要 linux/amd64。--provenance=false 避免 buildx OCI

105 # image index that Cloud Run rejects.105 # 镜像索引被 Cloud Run 拒绝。

106 docker build --platform=linux/amd64 --provenance=false \106 docker build --platform=linux/amd64 --provenance=false \

107 -t "${REGION}-docker.pkg.dev/${PROJECT_ID}/claude-gateway/gateway:<version>" .107 -t "${REGION}-docker.pkg.dev/${PROJECT_ID}/claude-gateway/gateway:<version>" .

108 docker push "${REGION}-docker.pkg.dev/${PROJECT_ID}/claude-gateway/gateway:<version>"108 docker push "${REGION}-docker.pkg.dev/${PROJECT_ID}/claude-gateway/gateway:<version>"

109 ```109 ```

110 </Step>110 </Step>

111 111

112 <Step title="配置 Cloud SQL for PostgreSQL">112 <Step title="为 PostgreSQL 配置 Cloud SQL">

113 通过 Private Services Access 在 VPC 上创建实例，使其没有公共 IP；这也满足强制执行 `constraints/sql.restrictPublicIp` 的项目：113 通过私有服务访问在 VPC 上创建实例，使其没有公共 IP；这也满足强制执行 `constraints/sql.restrictPublicIp` 的项目：

114 114

115 ```bash theme={null}115 ```bash theme={null}

116 VPC=cc-gateway-vpc116 VPC=cc-gateway-vpc

118 gcloud compute networks subnets create cc-gateway-subnet \118 gcloud compute networks subnets create cc-gateway-subnet \

119 --network="$VPC" --region="$REGION" --range=10.0.0.0/24119 --network="$VPC" --region="$REGION" --range=10.0.0.0/24

120 120

121 # Private Services Access: one-time per VPC121 # 私有服务访问：每个 VPC 一次

122 gcloud compute addresses create "google-managed-services-${VPC}" \122 gcloud compute addresses create "google-managed-services-${VPC}" \

123 --global --purpose=VPC_PEERING --prefix-length=16 --network="$VPC"123 --global --purpose=VPC_PEERING --prefix-length=16 --network="$VPC"

124 gcloud services vpc-peerings connect \124 gcloud services vpc-peerings connect \

141 </Step>141 </Step>

142 142

143 <Step title="编写 gateway.yaml">143 <Step title="编写 gateway.yaml">

144 `upstreams` 块使用 `auth: {}` 指向 Google Cloud 的 Agent Platform，因此网关通过运行时服务账户的应用默认凭据进行身份验证。有关每个字段，请参阅[配置参考](/zh-CN/claude-apps-gateway-config)。144 `upstreams` 块使用 `auth: {}` 指向 Google Cloud 的 Agent Platform，因此网关通过运行时服务账户的应用默认凭证进行身份验证。有关每个字段，请参阅[配置参考](/docs/zh-CN/claude-apps-gateway-config)。

145 145

146 两个 `listen` 字段取决于什么在网关前面：146 两个 `listen` 字段描述网关的前端：

147 147

148 * `public_url`：在 Cloud Run 或 GKE Ingress 后面时需要。网关仅从此值构建 IdP `redirect_uri` 和其发现文档，从不从 `X-Forwarded-*` 标头构建。148 * `public_url`：外部 `https://` 源，对于任何非环回绑定都是必需的；请参阅 [`listen` 参考](/docs/zh-CN/claude-apps-gateway-config#listen)。网关仅从此值构建 IdP `redirect_uri` 和其发现文档，从不从 `X-Forwarded-*` 标头构建。

149 * `trusted_proxies`：前端的源范围。网关仅当 TCP 对等体在此列表中时才遵守 `X-Forwarded-For`，然后遍历链越过受信任的跳跃，因此按 IP 的登录速率限制和审计事件记录开发人员 IP 而不是负载均衡器的。149 * `trusted_proxies`：前端的源范围。网关仅在 TCP 对等体在此列表中时才遵守 `X-Forwarded-For`，然后遍历链越过受信任的跳跃，因此按 IP 登录速率限制和审计事件记录开发者 IP 而不是负载均衡器的 IP。

150 150

151 设置 `trusted_proxies` 以匹配您的前端。类别为 `gce` 的外部 GKE Ingress 未列出：它配置一个公共转发规则地址，`/login` [私有网络检查](/zh-CN/claude-apps-gateway#prerequisites)拒绝该地址。151 设置 `trusted_proxies` 以匹配您的前端。类 `gce` 的外部 GKE Ingress 未列出：它配置一个公共转发规则地址，`/login` [私有网络检查](/docs/zh-CN/claude-apps-gateway#prerequisites)拒绝该地址。

152 152

153 | 前端 | `trusted_proxies` |153 | 前端 | `trusted_proxies` |

154 | -------------------------------- | -------------------------------- |154 | ------------------------------- | -------------------------------- |

155 | 直接到达的 Cloud Run，无负载均衡器 | `[169.254.0.0/16]` |155 | 直接访问的 Cloud Run，无负载均衡器 | `[169.254.0.0/16]` |

158 158

159 下面的示例使用内部负载均衡器前面的 Cloud Run 值。159 下面的示例使用内部负载均衡器前置 Cloud Run 的值。

160 160

161 ```yaml gateway.yaml theme={null}161 ```yaml gateway.yaml theme={null}

162 listen:162 listen:

170 client_id: <your-oauth-client-id>170 client_id: <your-oauth-client-id>

171 client_secret: ${OIDC_CLIENT_SECRET} # GKE: ${file:/secrets/oidc-client-secret}171 client_secret: ${OIDC_CLIENT_SECRET} # GKE: ${file:/secrets/oidc-client-secret}

172 allowed_email_domains: [example.com]172 allowed_email_domains: [example.com]

173 # Google ignores offline_access; these yield refresh tokens:173 # Google 忽略 offline_access；这些产生刷新令牌：

174 scopes: [openid, profile, email]174 scopes: [openid, profile, email]

175 extra_auth_params: { access_type: offline, prompt: consent }175 extra_auth_params: { access_type: offline, prompt: consent }

176 176

182 182

183 upstreams:183 upstreams:

184 - provider: vertex184 - provider: vertex

185 region: <your-region> # must match $REGION185 region: <your-region> # 必须匹配 $REGION

186 project_id: <your-project>186 project_id: <your-project>

187 auth: {} # ADC via the runtime service account187 auth: {} # 通过运行时服务账户的 ADC

188 ```188 ```

189 189

190 <Note>190 <Note>

191 Google id\_tokens 不携带 `groups` 声明。要在 [`managed.policies`](/zh-CN/claude-apps-gateway-config#managed) 中使用基于组的策略，并将 Google Workspace 作为 IdP，请配置 [`oidc.google_groups`](/zh-CN/claude-apps-gateway-config#oidc)，它使用具有域范围委派的服务账户通过 Admin SDK Directory API 查找每个用户的组。没有它，改为匹配 `email_domain`。191 Google id\_tokens 不包含 `groups` 声明。要在 [`managed.policies`](/docs/zh-CN/claude-apps-gateway-config#managed) 中使用基于组的策略，以 Google Workspace 作为 IdP，请配置 [`oidc.google_groups`](/docs/zh-CN/claude-apps-gateway-config#oidc)，它使用具有域范围委派的服务账户通过 Admin SDK Directory API 查找每个用户的组。没有它，改为匹配 `email_domain`。

192 </Note>192 </Note>

193 </Step>193 </Step>

194 194

195 <Step title="在 Secret Manager 中存储机密">195 <Step title="在 Secret Manager 中存储密钥">

196 创建四个机密并授予 `roles/secretmanager.secretAccessor` 给 `claude-gateway` 服务账户：196 创建四个密钥并向 `claude-gateway` 服务账户授予 `roles/secretmanager.secretAccessor`：

197 197

198 | 机密 | 来源 |198 | 密钥 | 源 |

199 | ---------------------------- | -------------------------------------- |199 | ---------------------------- | -------------------------------------- |

204 204

205 机密到达容器的方式因路径而异：205 密钥到达容器的方式因路径而异：

206 206

207 * 在 GKE 上，它们通过 Secret Manager CSI 驱动程序作为文件挂载，`gateway.yaml` 引用 `${file:/secrets/...}`。207 * 在 GKE 上，它们通过 Secret Manager CSI 驱动程序作为文件挂载，`gateway.yaml` 引用 `${file:/secrets/...}`。

208 * 在 Cloud Run 上，它无法将多个机密挂载到一个目录中，`gateway.yaml` 作为文件挂载，其他三个作为环境变量注入，因此 `gateway.yaml` 改为引用 `${GATEWAY_JWT_SECRET}`、`${OIDC_CLIENT_SECRET}` 和 `${GATEWAY_POSTGRES_URL}`。208 * 在 Cloud Run 上，它无法将多个密钥挂载到一个目录中，`gateway.yaml` 作为文件挂载，其他三个作为环境变量注入，因此 `gateway.yaml` 改为引用 `${GATEWAY_JWT_SECRET}`、`${OIDC_CLIENT_SECRET}` 和 `${GATEWAY_POSTGRES_URL}`。

209 </Step>209 </Step>

210 210

211 <Step title="部署">211 <Step title="部署">

212 <Tabs>212 <Tabs>

213 <Tab title="Cloud Run">213 <Tab title="Cloud Run">

214 下面的命令在内部负载均衡器后面为生产部署。214 下面的命令在内部负载均衡器后面部署用于生产。

215 215

216 ```bash theme={null}216 ```bash theme={null}

217 gcloud run deploy claude-gateway \217 gcloud run deploy claude-gateway \

219 --region="$REGION" \219 --region="$REGION" \

220 --service-account="claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com" \220 --service-account="claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com" \

221 --min-instances=1 \221 --min-instances=1 \

222 --max-instances=8 \

222 --timeout=3600 \223 --timeout=3600 \

223 --ingress=internal-and-cloud-load-balancing \224 --ingress=internal \

224 --network="$VPC" --subnet=cc-gateway-subnet --vpc-egress=private-ranges-only \225 --network="$VPC" --subnet=cc-gateway-subnet --vpc-egress=private-ranges-only \

225 --set-secrets=/etc/claude/gateway.yaml=gateway-config:latest,GATEWAY_JWT_SECRET=gateway-jwt-secret:latest,OIDC_CLIENT_SECRET=gateway-oidc-client-secret:latest,GATEWAY_POSTGRES_URL=gateway-postgres-url:latest \226 --set-secrets=/etc/claude/gateway.yaml=gateway-config:latest,GATEWAY_JWT_SECRET=gateway-jwt-secret:latest,OIDC_CLIENT_SECRET=gateway-oidc-client-secret:latest,GATEWAY_POSTGRES_URL=gateway-postgres-url:latest \

226 --no-invoker-iam-check227 --no-invoker-iam-check

227 ```228 ```

228 229

229 直接 VPC 出口，通过 `--network`、`--subnet` 和 `--vpc-egress=private-ranges-only`，让服务直接到达 Cloud SQL 私有 IP。到 Google Cloud 的 Agent Platform 端点和 `accounts.google.com` 的公共出口直接进入互联网，而不是通过 VPC，因此不需要 Cloud NAT。230 直接 VPC 出口，通过 `--network`、`--subnet` 和 `--vpc-egress=private-ranges-only`，让服务直接到达 Cloud SQL 私有 IP。每个实例最多持有 [`store.max_connections`](/docs/zh-CN/claude-apps-gateway-config#store) 个 Postgres 连接，默认为 5 个，因此保持最大实例数 × `store.max_connections` 低于您的 Cloud SQL 层的连接限制；[参考资产](#terraform-reference)为 `db-g1-small` 层将实例上限设为 8 是出于这个原因。到 Google Cloud 的 Agent Platform 端点和 `accounts.google.com` 的公共出口直接进入互联网，而不是通过 VPC，因此不需要 Cloud NAT。

230 231

231 调用者 IAM 检查必须打开或禁用。网关运行自己的 OIDC，其客户端不携带 GCP 令牌，因此 Cloud Run 的调用者检查必须允许未经身份验证的请求。网关的 OIDC 登录在请求到达容器后对其进行身份验证，使用 `allowed_email_domains` 限制哪些域可以登录。232 调用者 IAM 检查必须打开或禁用。网关运行自己的 OIDC，其客户端不携带 GCP 令牌，因此 Cloud Run 的调用者检查必须允许未经身份验证的请求。网关的 OIDC 登录在请求到达容器后对其进行身份验证，`allowed_email_domains` 限制哪些域可以登录。

232 233

233 两个标志允许未经身份验证的请求：234 两个标志允许未经身份验证的请求：

234 235

235 * `--no-invoker-iam-check`：禁用检查，无需管理 `allUsers` 绑定，并在域受限共享下工作236 * `--no-invoker-iam-check`：禁用检查，无需管理 `allUsers` 绑定，并在域受限共享下工作

236 * `--allow-unauthenticated`：授予 `allUsers` `run.invoker` 角色；如果您的组织不允许 `--no-invoker-iam-check`，请使用它237 * `--allow-unauthenticated`：向 `allUsers` 授予 `run.invoker` 角色；如果您的组织不允许 `--no-invoker-iam-check`，请使用它

237 238

238 通过 `--ingress` 的入口限制是与调用者检查独立的单独层；保持设置以将服务限制在您的公司网络。239 通过 `--ingress` 的入口限制是与调用者检查分离的独立层；保持设置以将服务限制在您的公司网络。

239 240

240 默认情况下，Cloud Run `*.run.app` URL 解析为公共地址，`/login` [私有网络检查](/zh-CN/claude-apps-gateway#prerequisites)拒绝该地址。两种拓扑为开发人员提供私有可解析的主机名，Cloud Run 都不为您配置：241 默认情况下，Cloud Run `*.run.app` URL 解析为公共地址，`/login` [私有网络检查](/docs/zh-CN/claude-apps-gateway#prerequisites)拒绝该地址。两种拓扑为开发者提供私有可解析的主机名，Cloud Run 都不为您配置：

241 242

242 * **内部应用负载均衡器**，上面部署命令假设的拓扑：使用 `--ingress=internal-and-cloud-load-balancing` 部署，在服务前面配置内部应用负载均衡器，具有内部 DNS 名称和证书，并将 `listen.public_url` 设置为该主机名。243 * **内部应用负载均衡器**，此页面的 `gateway.yaml` 假设的拓扑：在服务前面配置一个内部应用负载均衡器，具有内部 DNS 名称和证书，并将 `listen.public_url` 设置为该主机名。`internal` 入口设置已允许来自内部应用负载均衡器的流量；`internal-and-cloud-load-balancing` 还允许外部应用负载均衡器，其公共地址 `/login` 私有网络检查拒绝，因此此页面上的任何拓扑都不需要它。

243 * **仅限内部入口，无负载均衡器**：使用 `--ingress=internal` 部署，并将 `listen.public_url` 保留为 `*.run.app` URL，下面[参考资产](#terraform-reference)中的默认值。为了让 `*.run.app` 私有解析，您的网络团队必须已经运营 Google API 的 Private Service Connect 端点、解析 `*.run.app` 到它的 Cloud DNS 私有区域，以及到该端点的本地路由。244 * **仅内部入口，无负载均衡器**：保持部署命令不变，将 `listen.public_url` 保留为 `*.run.app` URL，下面[参考资产](#terraform-reference)中的默认值。为了让 `*.run.app` 私有解析，您的网络团队必须已经运行 Google API 的私有服务连接端点、将 `*.run.app` 解析到它的 Cloud DNS 私有区域，以及到该端点的本地路由。

244 245

245 Google 的 [Cloud Run 私有网络指南](https://cloud.google.com/run/docs/securing/private-networking)涵盖了两个选项都需要的基础设施。在网关在私有主机名上提供服务后验证登录；在那之前，从 Cloud Run 中的日志确认容器启动。246 Google 的 [Cloud Run 私有网络指南](https://cloud.google.com/run/docs/securing/private-networking)涵盖了两个选项都需要的基础设施。一旦网关在私有主机名上提供服务，验证登录；在此之前，从 Cloud Run 中的日志确认容器已启动。

246 247

247 在第一次登录前更新 OAuth 客户端的授权重定向 URI 为 `<public_url>/oauth/callback`。更改 `public_url` 后重新部署，因为网关仅从该设置构建其公共源，忽略 `X-Forwarded-Host` 和 `X-Forwarded-Proto`。`X-Forwarded-For` 仅在设置 `listen.trusted_proxies` 时才被遵守用于客户端 IP。248 在首次登录前更新 OAuth 客户端的授权重定向 URI 为 `<public_url>/oauth/callback`。更改 `public_url` 后重新部署，因为网关仅从该设置构建其公共源，忽略 `X-Forwarded-Host` 和 `X-Forwarded-Proto`。仅当设置 `listen.trusted_proxies` 时，才会为客户端 IP 遵守 `X-Forwarded-For`。

248 </Tab>249 </Tab>

249 250

250 <Tab title="GKE">251 <Tab title="GKE">

251 集群必须在 Cloud SQL 步骤中创建的 `$VPC` 上，以便 pod 可以到达数据库的私有 IP；仅 VPC 对等不起作用，因为 Cloud SQL 私有 IP 本身是对等网络，对等是非传递的。要在该 VPC 上创建新集群，请将 `--network="$VPC" --subnetwork=cc-gateway-subnet` 传递给 `gcloud container clusters create`。252 集群必须在 Cloud SQL 步骤中创建的 `$VPC` 上，以便 Pod 可以到达数据库的私有 IP；仅 VPC 对等不起作用，因为 Cloud SQL 私有 IP 本身是对等网络，对等是非传递的。要在该 VPC 上创建新集群，请将 `--network="$VPC" --subnetwork=cc-gateway-subnet` 传递给 `gcloud container clusters create`。

252 253

253 在集群及其节点池上启用 Workload Identity，然后将 Google 服务账户绑定到 Kubernetes 服务账户，以便 pod 继承其凭据：254 在集群及其节点池上启用 Workload Identity，然后将 Google 服务账户绑定到 Kubernetes 服务账户，以便 Pod 继承其凭证：

254 255

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

256 gcloud container clusters update <cluster> --region="$REGION" \257 gcloud container clusters update <cluster> --region="$REGION" \

257 --workload-pool="${PROJECT_ID}.svc.id.goog"258 --workload-pool="${PROJECT_ID}.svc.id.goog"

258 # On a Standard cluster, existing node pools also need GKE_METADATA;259 # 在标准集群上，现有节点池也需要 GKE_METADATA；

259 # Autopilot enables this by default.260 # Autopilot 默认启用此功能。

260 gcloud container node-pools update <pool> --cluster=<cluster> \261 gcloud container node-pools update <pool> --cluster=<cluster> \

261 --region="$REGION" --workload-metadata=GKE_METADATA262 --region="$REGION" --workload-metadata=GKE_METADATA

262 263

272 iam.gke.io/gcp-service-account="claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com"273 iam.gke.io/gcp-service-account="claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com"

273 ```274 ```

274 275

275 将网关部署为标准 Deployment 加上 Service 和内部 Ingress，类别 `gce-internal`，如[Kubernetes 部署](/zh-CN/claude-apps-gateway-deploy#kubernetes)中所述，具有：276 将网关部署为标准 Deployment 加上 Service 和内部 Ingress，类 `gce-internal`，如 [Kubernetes 部署](/docs/zh-CN/claude-apps-gateway-deploy#kubernetes)中所述，具有：

276 277

277 * `serviceAccountName: gateway`278 * `serviceAccountName: gateway`

278 * Secret Manager CSI 驱动程序在 `/secrets` 处挂载机密279 * Secret Manager CSI 驱动程序在 `/secrets` 处挂载密钥

279 * 就绪探针指向 `GET /readyz`280 * 就绪探针指向 `GET /readyz`

280 281

281 将具有提高的 `timeoutSec` 的 BackendConfig 附加到网关 Service：GKE Ingress 后面的负载均衡器后端服务默认为 30 秒超时，这会切断长流式响应。282 将具有提高的 `timeoutSec` 的 BackendConfig 附加到网关 Service：GKE Ingress 后面的负载均衡器后端服务默认为 30 秒超时，这会切断长流式响应。

282 283

283 不要在 Workload Identity 集群上应用阻止 `169.254.169.254` 的出口 NetworkPolicy；pod 必须到达元数据服务器以获取凭据。网关的内置 [SSRF 防护](/zh-CN/claude-apps-gateway-deploy#threat-model-summary)是那里的防御。284 不要在 Workload Identity 集群上应用阻止 `169.254.169.254` 的出口 NetworkPolicy；Pod 必须到达元数据服务器以获取凭证。网关的内置 [SSRF 防护](/docs/zh-CN/claude-apps-gateway-deploy#threat-model-summary)是那里的防御。

284 285

285 网关记录启动警告，指出元数据端点可达，并建议应用出口 NetworkPolicy。在 Workload Identity 下，该警告是预期的，因为 pod 需要端点。286 网关记录一个启动警告，指出元数据端点可达，并建议应用出口 NetworkPolicy。在 Workload Identity 下，该警告是预期的，因为 Pod 需要端点。

286 </Tab>287 </Tab>

287 </Tabs>288 </Tabs>

288 </Step>289 </Step>

289 290

290 <Step title="将网关 URL 推送到开发人员机器">291 <Step title="将网关 URL 推送到开发者机器">

291 网关现在正在运行，但开发人员在网关 URL 在其机器上之前无法从 `/login` 到达它。在您通过 MDM 部署到每个设备的[托管设置文件](/zh-CN/claude-apps-gateway#set-the-gateway-url)中设置 `forceLoginMethod` 和 `forceLoginGatewayUrl`。登录选择器中没有网关选项供开发人员手动选择。292 网关现在正在运行，但开发者在网关 URL 在其机器上之前无法从 `/login` 到达它。通过 MDM 将完整的[托管设置片段](/docs/zh-CN/claude-apps-gateway#set-the-gateway-url)部署到每个设备，具有 `forceLoginMethod`、`forceLoginGatewayUrl` 和 `parentSettingsBehavior: "merge"` 选择加入。登录选择器中没有网关选项供开发者手动选择。

292 </Step>293 </Step>

293</Steps>294</Steps>

294 295

302* `terraform/`：相同的部署作为基础设施即代码，用于绿地部署：创建 Artifact Registry 存储库的目标应用，然后构建和推送镜像，然后完整应用303* `terraform/`：相同的部署作为基础设施即代码，用于绿地部署：创建 Artifact Registry 存储库的目标应用，然后构建和推送镜像，然后完整应用

303* `gateway.yaml.example` 和用于 distroless 运行时镜像的 `Dockerfile`304* `gateway.yaml.example` 和用于 distroless 运行时镜像的 `Dockerfile`

304 305

305工件默认 Cloud Run 入口为 `internal`，因此不需要负载均衡器。要匹配本页的生产后面 ALB 部署，使用 `INGRESS=internal-and-cloud-load-balancing` 运行 `setup.sh`，或将 Terraform 变量 `ingress` 设置为 `INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER`。工件还默认调用者层为 `allUsers` `run.invoker` 授予而不是 `--no-invoker-iam-check`，与本页演练相反；两者都有效，选择取决于您的组织的策略约束。306工件默认 Cloud Run 入口为 `internal`，与本页的部署命令相匹配；该设置适用于服务前面有或没有内部应用负载均衡器的情况，工件也不创建负载均衡器。工件还默认调用者层为 `allUsers` `run.invoker` 授予而不是 `--no-invoker-iam-check`，与本页演练相反；两者都有效，选择取决于您的组织的策略约束。

306 307

307资产作为工作示例提供，而不是受支持的生产工件；查看并根据您的环境调整它们。308资产作为工作示例提供，而不是受支持的生产工件；查看并根据您的环境调整它们。

308 309

310 故障排除311 故障排除

311</h2>312</h2>

312 313

313有关网关启动和登录错误，请参阅平台无关的[故障排除表](/zh-CN/claude-apps-gateway-deploy#troubleshooting)。下面的条目特定于 Google Cloud。314有关网关启动和登录错误，请参阅平台无关的[故障排除表](/docs/zh-CN/claude-apps-gateway-deploy#troubleshooting)。下面的条目特定于 Google Cloud。

314 315

315| 症状 | 原因 | 修复 |316| 症状 | 原因 | 修复 |

316| --------------------------------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |317| --------------------------------------------------------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |

325 后续步骤326 后续步骤

326</h2>327</h2>

327 328

328* [配置参考](/zh-CN/claude-apps-gateway-config)：每个 `gateway.yaml` 选项，包括 `managed.policies` 和 `telemetry`329* [配置参考](/docs/zh-CN/claude-apps-gateway-config)：每个 `gateway.yaml` 选项，包括 `managed.policies` 和 `telemetry`

329* [部署和操作](/zh-CN/claude-apps-gateway-deploy)：IdP 设置、健康检查、JWT 密钥轮换、升级和安全模型330* [部署和操作](/docs/zh-CN/claude-apps-gateway-deploy)：IdP 设置、健康检查、JWT 密钥轮换、升级和安全模型

330* [Claude apps gateway 概述](/zh-CN/claude-apps-gateway)：快速入门和连接开发人员331* [Claude apps gateway 概述](/docs/zh-CN/claude-apps-gateway)：快速入门和连接开发人员

claude-code-on-the-web.md +52 −30

Details

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

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

4 4

~~5# 在网络上使用 Claude Code~~5# 在云端使用 Claude Code

6 6

~~7> 使用 `--cloud` 和 `--teleport` 在网络和终端之间移动会话，管理和共享会话，以及从云端自动修复拉取请求。~~7> 从浏览器、手机、桌面应用或终端在云端运行 Claude Code 会话，使用 --cloud 和 --teleport 移动会话，以及自动修复拉取请求。

8 8

9<Note>9<Note>

~~10 Claude Code on the web 处于研究预览阶段，适用于 Pro、Max 和 Team 用户，以及拥有高级席位或 Chat + Claude Code 席位的 Enterprise 用户。~~10 云会话处于研究预览阶段，适用于 Pro、Max 和 Team 用户，以及拥有高级席位或 Chat + Claude Code 席位的 Enterprise 用户。

11</Note>11</Note>

12 12

13Claude Code on the web 在 [claude.ai/code](https://claude.ai/code) 的 Anthropic 管理的云基础设施上运行任务，或在路由到你的组织的[自托管环境](/docs/zh-CN/self-hosted-environments)时在那里运行。会话即使在关闭浏览器后也会持续，你可以从 Claude 移动应用监控它们。13云会话是在云基础设施上运行的 Claude Code 会话，而不是在你的机器上运行。默认情况下，它在 Anthropic 管理的基础设施上运行，或在路由到你的组织的[自托管环境](/docs/zh-CN/self-hosted-environments)时在那里运行。即使关闭笔记本电脑后，会话也会继续运行，你可以从任何设备检查或控制它。

15你可以从以下任何界面启动云会话：

17* **浏览器**：[claude.ai/code](https://claude.ai/code)，也称为网络上的 Claude Code

18* **移动设备**：[Claude 应用](/docs/zh-CN/mobile)中的 **Code** 标签页

19* **桌面应用**：当你[启动会话](/docs/zh-CN/desktop#run-long-running-tasks-in-the-cloud)时，选择 **Cloud** 而不是 **Local**

20* **终端**：[`claude --cloud`](#from-terminal-to-cloud)

21* **例程**：[计划和触发的运行](/docs/zh-CN/routines)每次都作为云会话运行

23要让 Claude 为一项工作启动并跟踪许多云会话，请使用[项目](/docs/zh-CN/claude-projects)。在你的终端、IDE 或选择了 **Local** 的桌面应用中的会话在你自己的机器上运行。要从手机或浏览器控制这些本地会话之一，请使用[远程控制](/docs/zh-CN/remote-control)。

14 24

15<Tip>25<Tip>

~~16 初次使用 Claude Code on the web？从[入门](/docs/zh-CN/web-quickstart)开始，连接你的 GitHub 账户并提交你的第一个任务。~~26 初次使用云会话？从[入门](/docs/zh-CN/web-quickstart)开始，连接你的 GitHub 账户并提交你的第一个任务。

17</Tip>27</Tip>

18 28

~~19本页涵盖网络产品本身：~~29本页涵盖：

20 30

21* [云环境](#cloud-environments)：会话运行的位置，以及在哪里配置31* [云环境](#cloud-environments)：会话运行的位置，以及在哪里配置

22* [GitHub 身份验证选项](#github-authentication-options)：两种连接 GitHub 的方式32* [GitHub 身份验证选项](#github-authentication-options)：两种连接 GitHub 的方式

~~23* [在网络和终端之间移动任务](#move-tasks-between-web-and-terminal)，使用 `--cloud` 和 `--teleport`~~33* [在终端和云之间移动任务](#move-tasks-between-terminal-and-cloud)，使用 `--cloud` 和 `--teleport`

24* [处理会话](#work-with-sessions)：权限模式、审查、共享、归档、删除34* [处理会话](#work-with-sessions)：权限模式、审查、共享、归档、删除

25* [自动修复拉取请求](#auto-fix-pull-requests)：自动响应 CI 失败和审查评论35* [自动修复拉取请求](#auto-fix-pull-requests)：自动响应 CI 失败和审查评论

26* [安全和隔离](#security-and-isolation)：会话如何隔离36* [安全和隔离](#security-and-isolation)：会话如何隔离

43云会话需要访问你的 GitHub 存储库来克隆代码和推送分支。你可以通过两种方式授予访问权限：53云会话需要访问你的 GitHub 存储库来克隆代码和推送分支。你可以通过两种方式授予访问权限：

44 54

45| 方法 | 如何连接 | 会话可以访问的存储库 | 最适合 |55| 方法 | 如何连接 | 会话可以访问的存储库 | 最适合 |

~~46| :--------------- | :----------------------------------------------------- | :------------------------------------- | :----------------------------------------- |~~56| :--------------- | :----------------------------------------------------- | :--------------------------------------------- | :----------------------------------------- |

49 59

50在存储库上安装 Claude GitHub App 也会为其中的拉取请求启用[自动修复](#auto-fix-pull-requests)。60在存储库上安装 Claude GitHub App 也会为其中的拉取请求启用[自动修复](#auto-fix-pull-requests)。

51 61

62[项目](/docs/zh-CN/claude-projects)中的线程需要在每个克隆的存储库上安装 Claude GitHub App，无论你使用哪种连接方法。请参阅[设置 GitHub 访问权限](/docs/zh-CN/claude-projects#set-up-github-access)。

52有关 `/schedule` 如何在创建 routine 之前检查存储库访问权限，请参阅[存储库和分支权限](/docs/zh-CN/routines#repositories-and-branch-permissions)。有关 `/web-setup` 演练（包括 `/web-setup` 存储的内容以及如何删除它），请参阅[从终端连接](/docs/zh-CN/web-quickstart#connect-from-your-terminal)。64有关 `/schedule` 如何在创建 routine 之前检查存储库访问权限，请参阅[存储库和分支权限](/docs/zh-CN/routines#repositories-and-branch-permissions)。有关 `/web-setup` 演练（包括 `/web-setup` 存储的内容以及如何删除它），请参阅[从终端连接](/docs/zh-CN/web-quickstart#connect-from-your-terminal)。

53 65

54快速网络设置是一个组织设置，允许成员使用 `/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) 处使用**快速网络设置**切换来打开它。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) 处使用**快速网络设置**切换来打开它。

57 启用了[零数据保留](/docs/zh-CN/zero-data-retention)的组织无法使用 `/web-setup` 或其他云会话功能。69 启用了[零数据保留](/docs/zh-CN/zero-data-retention)的组织无法使用 `/web-setup` 或其他云会话功能。

58</Note>70</Note>

59 71

~~60<h2 id="move-tasks-between-web-and-terminal">~~72<h2 id="move-tasks-between-terminal-and-cloud">

~~61 在网页和终端之间移动任务~~73 在终端和云之间移动任务

62</h2>74</h2>

63 75

64这些工作流需要 [Claude Code CLI](/docs/zh-CN/quickstart) 登录到同一个 claude.ai 账户。您可以从终端启动新的云会话，或将云会话拉入终端以继续本地工作。云会话即使在您关闭笔记本电脑后也会持续存在，您可以从任何地方（包括 Claude 移动应用）监控它们。76这些工作流需要 [Claude Code CLI](/docs/zh-CN/quickstart) 登录到同一个 claude.ai 账户。您可以从终端启动新的云会话，或将云会话拉入终端以继续本地工作。云会话即使在您关闭笔记本电脑后也会持续存在，您可以从任何地方（包括 Claude 移动应用）监控它们。

65 77

66<Note>78<Note>

67 从 CLI 来看，会话切换是单向的：您可以使用 `--teleport` 将云会话拉入终端，但无法将现有的终端会话推送到网页。带有任务描述的 `--cloud` 标志为您当前的存储库创建新的云会话；带有 `-p` 和会话 ID 或 claude.ai/code URL 时，它会改为 [将消息排队到该现有会话](/docs/zh-CN/claude-code-on-the-web#send-follow-ups-from-the-cli)。[Desktop 应用](/docs/zh-CN/desktop#continue-in-another-surface) 提供了一个"继续在"菜单，可以将本地会话发送到网页。79 从 CLI 来看，会话切换是单向的：您可以使用 `--teleport` 将云会话拉入终端，但无法将现有的终端会话推送到云。带有任务描述的 `--cloud` 标志为您当前的存储库创建新的云会话；带有 `-p` 和会话 ID 或 claude.ai/code URL 时，它会改为 [将消息排队到该现有会话](/docs/zh-CN/claude-code-on-the-web#send-follow-ups-from-the-cli)。[Desktop 应用](/docs/zh-CN/desktop#continue-in-another-surface) 提供了一个"继续在"菜单，可以将本地会话发送到云。

68</Note>80</Note>

69 81

~~70<h3 id="from-terminal-to-web">~~82<h3 id="from-terminal-to-cloud">

~~71 从终端到网页~~83 从终端到云

72</h3>84</h3>

73 85

74使用 `--cloud` 标志从命令行启动云会话：86使用 `--cloud` 标志从命令行启动云会话：

84当云容器启动时，CLI 显示设置步骤的实时清单，例如克隆存储库和运行您的 [设置脚本](/docs/zh-CN/cloud-environments#setup-scripts)。它会将您在配置期间键入的消息排队，并在会话准备好后发送它们。96当云容器启动时，CLI 显示设置步骤的实时清单，例如克隆存储库和运行您的 [设置脚本](/docs/zh-CN/cloud-environments#setup-scripts)。它会将您在配置期间键入的消息排队，并在会话准备好后发送它们。

85 97

86<Note>98<Note>

~~87 `--cloud` 创建云会话。`--remote-control` 无关：它公开本地 CLI 会话以便从网页进行监控。请参阅 [Remote Control](/docs/zh-CN/remote-control)。~~99 `--cloud` 创建云会话。`--remote-control` 无关：它让您能够从 claude.ai 或 Claude 应用监控和引导本地 CLI 会话。请参阅 [Remote Control](/docs/zh-CN/remote-control)。

88</Note>100</Note>

89 101

90在 claude.ai 或 Claude 移动应用上打开会话以检查进度或直接交互。从那里您可以引导 Claude、提供反馈或像在任何其他对话中一样回答问题。102在 claude.ai 或 Claude 移动应用上打开会话以检查进度或直接交互。从那里您可以引导 Claude、提供反馈或像在任何其他对话中一样回答问题。

95 云任务提示107 云任务提示

96</h4>108</h4>

97 109

~~98**在本地规划，远程执行**：对于复杂任务，启动 Claude 处于规划模式以协作制定方法，然后将工作发送到云：~~110**在本地规划，在云中执行**：对于复杂任务，启动 Claude 处于规划模式以协作制定方法，然后将工作发送到云：

99 111

100```bash theme={null}112```bash theme={null}

101claude --permission-mode plan113claude --permission-mode plan

115claude --cloud "Refactor the logger to use structured output"127claude --cloud "Refactor the logger to use structured output"

116```128```

117 129

118当会话完成时，您可以从网页界面创建 PR，或 [teleport](#from-web-to-terminal) 会话到您的终端以继续工作。130当会话完成时，您可以从 claude.ai/code 创建 PR，或 [teleport](#from-cloud-to-terminal) 会话到您的终端以继续工作。

119 131

120<h4 id="send-local-repositories-without-github">132<h4 id="send-local-repositories-without-github">

121 发送没有 GitHub 的本地存储库133 发送没有 GitHub 的本地存储库

185 197

186<h3 id="from-web-to-terminal">198<h3 id="from-cloud-to-terminal">

187 从网页到终端199 从云到终端

188</h3>200</h3>

189 201

190使用以下任何方法将云会话拉入您的终端：202使用以下任何方法将云会话拉入您的终端：

192* **使用 `--teleport`**：从命令行运行 `claude --teleport` 以获得交互式会话选择器，或 `claude --teleport <session-id>` 以直接恢复特定会话。如果您有未提交的更改，系统会提示您先隐藏它们。204* **使用 `--teleport`**：从命令行运行 `claude --teleport` 以获得交互式会话选择器，或 `claude --teleport <session-id>` 以直接恢复特定会话。如果您有未提交的更改，系统会提示您先隐藏它们。

193* **使用 `/teleport`**：在现有 CLI 会话内，运行 `/teleport` 或 `/tp` 以打开相同的会话选择器，无需重启 Claude Code。205* **使用 `/teleport`**：在现有 CLI 会话内，运行 `/teleport` 或 `/tp` 以打开相同的会话选择器，无需重启 Claude Code。

194* **从 `/tasks`**：运行 `/tasks` 以查看您的后台会话，然后按 `t` 以 teleport 到其中一个。206* **从 `/tasks`**：运行 `/tasks` 以查看您的后台会话，然后按 `t` 以 teleport 到其中一个。

195* **从网页界面**：从会话菜单中选择 **Open in > Terminal** 以复制可以粘贴到终端的命令。207* **从 claude.ai/code**：从会话菜单中选择 **Open in > Terminal** 以复制可以粘贴到终端的命令。

196* **从云会话内部**：键入 `/teleport`，Claude Code 会回复该会话的确切 `claude --teleport <session-id>` 命令，准备从存储库的检出运行。需要会话环境中的 Claude Code v2.1.223 或更高版本。208* **从云会话内部**：键入 `/teleport`，Claude Code 会回复该会话的确切 `claude --teleport <session-id>` 命令，准备从存储库的检出运行。需要会话环境中的 Claude Code v2.1.223 或更高版本。

197 209

198当您 teleport 会话时，Claude 验证您在正确的存储库中，从云会话获取并检出分支，并将完整的对话历史记录加载到您的终端。终端获得会话的自己的副本：那里的新工作保持本地，不会出现在 claude.ai 上的云会话或 Claude 移动应用中。在 teleport 后继续从您的手机引导，在本地会话中启动 [`/remote-control`](/docs/zh-CN/remote-control)。210当您 teleport 会话时，Claude 验证您在正确的存储库中，从云会话获取并检出分支，并将完整的对话历史记录加载到您的终端。终端获得会话的自己的副本：那里的新工作保持本地，不会出现在 claude.ai 上的云会话或 Claude 移动应用中。在 teleport 后继续从您的手机引导，在本地会话中启动 [`/remote-control`](/docs/zh-CN/remote-control)。

224 236

225会话出现在 claude.ai/code 的侧边栏中。从那里你可以审查更改、与队友共享、归档完成的工作或永久删除会话。237会话出现在 claude.ai/code 的侧边栏中。从那里你可以审查更改、与队友共享、归档完成的工作或永久删除会话。

226 238

239<h3 id="take-back-a-queued-message">

240 取回已排队的消息

241</h3>

242

243如果你在 Claude 工作时发送消息，该消息会排队直到 Claude 读取它。要取回已排队的消息，请点击它上面的 ✕。文本返回到消息框，以便你可以编辑它或发送其他内容。

244

245如果 Claude 已经读取了消息，它会保留在对话中。

246

227<h3 id="manage-context">247<h3 id="manage-context">

228 管理上下文248 管理上下文

229</h3>249</h3>

230 250

231云会话支持产生文本输出的[内置命令](/docs/zh-CN/commands)。仅在终端界面中运行的命令，如 `/plugin` 或 `/resume`，不可用。在云会话中打开选择器或面板的命令表现不同：251云会话支持产生文本输出的[内置命令](/docs/zh-CN/commands)。仅在终端界面中运行的命令，如 `/plugin` 或 `/resume`，不可用。在云会话中打开选择器或面板的命令表现不同：

232 252

233* **`/model`、`/effort`、`/fast`、`/color` 和 `/rename`**：将值作为参数传递，例如 `/model sonnet`，而不是打开终端选择器或滑块。参数形式需要会话环境中的 Claude Code v2.1.205 或更高版本，并遵循每个命令的[可用性说明](/docs/zh-CN/commands#all-commands)：当模型的[启动默认工作量保持](/docs/zh-CN/model-config#adjust-effort-level)生效时，`/effort` 报告 `Not applied`，而 `/fast` 仅在以快速模式启动的会话中工作。253* **`/model`、`/effort`、`/color` 和 `/rename`**：将值作为参数传递，例如 `/model sonnet`，而不是打开终端选择器或滑块。参数形式需要会话环境中的 Claude Code v2.1.205 或更高版本，并遵循每个命令的[可用性说明](/docs/zh-CN/commands#all-commands)：`/effort` 在模型的[启动默认工作量保持](/docs/zh-CN/model-config#adjust-effort-level)生效时报告 `Not applied`。

234* **`/config`**：在网络上，打开你的设置的 Claude Code 部分，而不是设置值，命令后的文本（包括 `key=value`）被忽略。要更改云会话的设置，请使用[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)或将[设置文件](/docs/zh-CN/settings)提交到存储库。254* **`/fast`**：当快速模式在[你的账户上可用](/docs/zh-CN/fast-mode#requirements)时，为会话切换[快速模式](/docs/zh-CN/fast-mode#use-fast-mode-in-cloud-sessions)。需要会话环境中的 Claude Code v2.1.271 或更高版本。

255* **`/config`**：在你的浏览器中的 claude.ai/code 上，打开你的设置的 Claude Code 部分，而不是设置值，命令后的文本（包括 `key=value`）被忽略。要更改云会话的设置，请设置[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)，或在具有一个存储库的会话中，将密钥提交到该存储库的 `.claude/settings.json`。[云会话中的设置](/docs/zh-CN/settings#settings-in-cloud-sessions)列出了每个会话读取的内容。

235 256

236对于上下文管理特别是：257对于上下文管理特别是：

237 258

241| `/context` | 是 | 显示当前在上下文窗口中的内容 |262| `/context` | 是 | 显示当前在上下文窗口中的内容 |

242| `/clear` | 否 | 从侧边栏启动新会话 |263| `/clear` | 否 | 从侧边栏启动新会话 |

243 264

244自动压缩在上下文窗口接近容量时自动运行。Claude Code on the web 在云会话中自己设置 [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/zh-CN/env-vars)，所以压缩在[自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window)的中途触发，而不是当窗口填满时。该值覆盖你在[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)中添加的值，所以在那里添加变量不会改变压缩何时触发。265自动压缩在上下文窗口接近容量时自动运行。云会话自己设置 [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/zh-CN/env-vars)，所以压缩在[自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window)的中途触发，而不是当窗口填满时。该值覆盖你在[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)中添加的值，所以在那里添加变量不会改变压缩何时触发。

245 266

246要改为更改自动压缩窗口，请在你的环境变量中设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/zh-CN/env-vars)，或在变量未设置的会话中运行带有令牌计数的 [`/autocompact`](/docs/zh-CN/commands#all-commands)。267要改为更改自动压缩窗口，请在你的环境变量中设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/zh-CN/env-vars)，或在变量未设置的会话中运行带有令牌计数的 [`/autocompact`](/docs/zh-CN/commands#all-commands)。

247 268

320 341

321根据 PR 来自何处以及你使用的设备，有几种方法可以打开自动修复：342根据 PR 来自何处以及你使用的设备，有几种方法可以打开自动修复：

322 343

323* **在 Claude Code on the web 中创建的 PR**：打开 CI 状态栏并选择**自动修复**344* **在云会话中创建的 PR**：打开 claude.ai/code 处的会话，打开 CI 状态栏，并选择**自动修复**

324* **从终端**：在 PR 的分支上运行 [`/autofix-pr`](/docs/zh-CN/commands)。Claude Code 使用 `gh` 检测打开的 PR，生成网络会话，并一步启用自动修复345* **从终端**：在 PR 的分支上运行 [`/autofix-pr`](/docs/zh-CN/commands)。Claude Code 使用 `gh` 检测打开的 PR，生成云会话，并一步启用自动修复

325* **从移动应用**：告诉 Claude 自动修复 PR，例如"watch this PR and fix any CI failures or review comments"346* **从移动应用**：告诉 Claude 自动修复 PR，例如"watch this PR and fix any CI failures or review comments"

326* **任何现有 PR**：将 PR URL 粘贴到会话中并告诉 Claude 自动修复它347* **任何现有 PR**：将 PR URL 粘贴到会话中并告诉 Claude 自动修复它

327 348

328自动修复是按 PR 的切换开关。要停止监视，请在网络会话中打开 CI 状态栏并清除**自动修复**切换，或告诉 Claude 停止监视 PR。349自动修复是按 PR 的切换开关。要停止监视，请在 claude.ai/code 处的会话中打开 CI 状态栏并清除**自动修复**切换，或告诉 Claude 停止监视 PR。

329 350

330<h3 id="how-claude-responds-to-pr-activity">351<h3 id="how-claude-responds-to-pr-activity">

331 Claude 如何响应 PR 活动352 Claude 如何响应 PR 活动

395 环境已过期416 环境已过期

396</h3>417</h3>

397 418

398云会话在不活动一段时间后停止，会话的 VM 被回收。会话在等待你批准[MCP 连接器](/docs/zh-CN/cloud-environments#network-access)工具调用或登录到 MCP 服务器时计为不活动，它可以在该等待期间过期。在网络上，会话在会话列表中标记为已过期。419云会话在不活动一段时间后停止，会话的 VM 被回收。会话在等待你批准 [MCP 连接器](/docs/zh-CN/cloud-environments#network-access)工具调用或登录到 MCP 服务器时计为不活动，它可以在该等待期间过期。

399 420

400从 [claude.ai/code](https://claude.ai/code) 重新打开会话以配置新 VM，并恢复你的对话历史。在 VM 被回收时仍在运行的后台工作，如 subagents 和 shell 命令，不会被恢复。421从 [claude.ai/code](https://claude.ai/code) 重新打开会话以配置新 VM，并恢复你的对话历史。在 VM 被回收时仍在运行的后台工作，如 subagents 和 shell 命令，不会被恢复。

401 422

405 426

406在依赖云会话进行工作流之前，请考虑这些约束：427在依赖云会话进行工作流之前，请考虑这些约束：

407 428

408* **速率限制**：Claude Code on the web 与你账户内所有其他 Claude 和 Claude Code 使用共享速率限制。并行运行多个任务会按比例消耗更多速率限制。云 VM 没有单独的计算费用。429* **速率限制**：云会话与你账户内所有其他 Claude 和 Claude Code 使用共享速率限制。并行运行多个任务会按比例消耗更多速率限制。云 VM 没有单独的计算费用。

409* **存储库身份验证**：你只能在认证到相同账户时将会话从网络移动到本地430* **存储库身份验证**：你只能在认证到相同账户时将云会话拉入你的终端

410* **平台限制**：存储库克隆和拉取请求创建需要 GitHub。自托管[GitHub Enterprise Server](/docs/zh-CN/github-enterprise-server) 实例支持 Team 和 Enterprise 计划。你可以通过设置 `CCR_FORCE_BUNDLE=1` 将 GitLab、Bitbucket 或其他非 GitHub 存储库作为[本地捆绑](#send-local-repositories-without-github)发送到云会话，但会话无法将结果推送回该远程431* **平台限制**：存储库克隆和拉取请求创建需要 GitHub。自托管[GitHub Enterprise Server](/docs/zh-CN/github-enterprise-server) 实例支持 Team 和 Enterprise 计划。你可以通过设置 `CCR_FORCE_BUNDLE=1` 将 GitLab、Bitbucket 或其他非 GitHub 存储库作为[本地捆绑](#send-local-repositories-without-github)发送到云会话，但会话无法将结果推送回该远程

411* **组织 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)和[routines](/docs/zh-CN/routines)在 Anthropic 托管的环境中运行；路由到自托管环境的 routine 从你自己的网络调用 API。联系 [Anthropic 支持](https://support.claude.com/)以从你的组织的 IP 允许列表中豁免 Anthropic 托管的服务。432* **组织 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 托管的服务。

412 433

413<h2 id="related-resources">434<h2 id="related-resources">

414 相关资源435 相关资源

415</h2>436</h2>

416 437

417* [云环境](/docs/zh-CN/cloud-environments)：为云会话配置网络访问、环境变量和设置脚本438* [云环境](/docs/zh-CN/cloud-environments)：为云会话配置网络访问、环境变量和设置脚本

439* [Projects](/docs/zh-CN/claude-projects)：一个对话，Claude 在其中协调您的存储库上的并行云会话并报告结果

418* [Ultrareview](/docs/zh-CN/ultrareview)：在云沙箱中运行深度多代理代码审查440* [Ultrareview](/docs/zh-CN/ultrareview)：在云沙箱中运行深度多代理代码审查

419* [Routines](/docs/zh-CN/routines)：按计划、通过 API 调用或响应 GitHub 事件自动化工作441* [Routines](/docs/zh-CN/routines)：按计划、通过 API 调用或响应 GitHub 事件自动化工作

420* [Hooks 配置](/docs/zh-CN/hooks)：在会话生命周期事件处运行脚本442* [Hooks 配置](/docs/zh-CN/hooks)：在会话生命周期事件处运行脚本

claude-directory.md +10 −7

Details

34 oneLiner: 'Project instructions Claude reads every session',34 oneLiner: 'Project instructions Claude reads every session',

35 when: 'Loaded into context at the start of every session',35 when: 'Loaded into context at the start of every session',

36 description: 'Project-specific instructions that shape how Claude works in this repository. Put your conventions, common commands, and architectural context here so Claude operates with the same assumptions your team does.',36 description: 'Project-specific instructions that shape how Claude works in this repository. Put your conventions, common commands, and architectural context here so Claude operates with the same assumptions your team does.',

37 tips: ['Target under 200 lines. Longer files still load in full but may reduce adherence', <>CLAUDE.md loads into every session. If something only matters for specific tasks, move it to a <A href="/docs/en/skills">skill</A> or a path-scoped <A href="/docs/en/memory#organize-rules-with-claude/rules/">rule</A> so it loads only when needed</>, 'List the commands you run most, like build, test, and format, so Claude knows them without you spelling them out each time', <>Run <C>/memory</C> to open and edit CLAUDE.md from within a session</>, <>Also works at <C>.claude/CLAUDE.md</C> if you prefer to keep the project root clean</>],37 tips: ['Target under 200 lines. Longer files still load in full but may reduce adherence', <>CLAUDE.md loads into every session. If something only matters for specific tasks, move it to a <A href="/docs/en/skills">skill</A> or a path-scoped <A href="/docs/en/memory#organize-rules-with-claude/rules/">rule</A> so it loads only when needed</>, 'List the commands you run most, like build, test, and format, so Claude knows them without you spelling them out each time', <>Run <C>/memory</C> to open and edit CLAUDE.md from within a session</>, <>Also works at <C>.claude/CLAUDE.md</C> if you prefer to keep the project root clean</>, <>If your repo already has an <C>AGENTS.md</C> for other coding agents, Claude Code <A href="/docs/en/memory#agents-md">can read that</A> on its own or alongside CLAUDE.md</>],

38 exampleIntro: 'This example is for a TypeScript and React project. It lists the build and test commands, the framework conventions Claude should follow, and project-specific rules like export style and file layout.',38 exampleIntro: 'This example is for a TypeScript and React project. It lists the build and test commands, the framework conventions Claude should follow, and project-specific rules like export style and file layout.',

39 example: `# Project conventions39 example: `# Project conventions

40 40

640 color: '#5AA7A7',640 color: '#5AA7A7',

641 oneLiner: 'Custom instruction sets that adjust how Claude works',641 oneLiner: 'Custom instruction sets that adjust how Claude works',

642 when: 'Files read at startup; the style you select with outputStyle applies to every response',642 when: 'Files read at startup; the style you select with outputStyle applies to every response',

643 description: [<>Each markdown file defines an output style: a set of instructions for Claude that, by default, also replaces the built-in software-engineering task instructions. Use this to adapt Claude Code for uses beyond coding, or to add teaching or review modes.</>, <>Select a built-in or custom style with <C>/config</C> or the <C>outputStyle</C> key in settings. Styles here are available in every project; project-level styles with the same name take precedence.</>],643 description: [<>Each markdown file defines an output style: a set of instructions for Claude that, by default, also replaces the built-in software-engineering task instructions. Use this to adapt Claude Code for uses beyond coding, or to add teaching or review modes.</>, <>Select a built-in or custom style with <C>/output-style</C>, <C>/config</C>, or the <C>outputStyle</C> key in settings. Styles here are available in every project; project-level styles with the same name take precedence.</>],

644 tips: ['Built-in styles Default, Proactive, Concise, Explanatory, and Learning are included with Claude Code; custom styles go here', <>Set <C>keep-coding-instructions: true</C> in frontmatter to keep the default task instructions alongside your additions</>, 'Switching styles mid-session applies from your next message; in the terminal, a style file you create or edit mid-session is picked up after a restart'],644 tips: ['Built-in styles Default, Proactive, Concise, Explanatory, and Learning are included with Claude Code; custom styles go here', <>Set <C>keep-coding-instructions: true</C> in frontmatter to keep the default task instructions alongside your additions</>, 'Switching styles mid-session applies from your next message; in the terminal, a style file you create or edit mid-session is picked up after a restart'],

645 docsLink: '/en/output-styles',645 docsLink: '/en/output-styles',

646 children: [{646 children: [{

1434 1434

1435在 Windows 上，`~/.claude` 解析为 `%USERPROFILE%\.claude`。如果您设置了 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars)，此页面上的每个 `~/.claude` 路径都将位于该目录下。1435在 Windows 上，`~/.claude` 解析为 `%USERPROFILE%\.claude`。如果您设置了 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars)，此页面上的每个 `~/.claude` 路径都将位于该目录下。

1436 1436

1437大多数用户只编辑 `CLAUDE.md` 和 `settings.json`。目录的其余部分是可选的：根据需要添加 skills、rules 或 subagents。1437大多数用户只编辑 `CLAUDE.md` 和 `settings.json`。如果您的存储库已经有一个 `AGENTS.md` 用于其他编码代理，Claude Code [可以自己读取它](/docs/zh-CN/memory#agents-md)或与 `CLAUDE.md` 一起读取。目录的其余部分是可选的：根据需要添加 skills、rules 或 subagents。

1438 1438

1439<h2 id="explore-the-directory">1439<h2 id="explore-the-directory">

1440 探索目录1440 探索目录

1451浏览器涵盖您创作和编辑的文件。一些相关文件位于其他位置：1451浏览器涵盖您创作和编辑的文件。一些相关文件位于其他位置：

1452 1452

1453| 文件 | 位置 | 用途 |1453| 文件 | 位置 | 用途 |

1454| ----------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1454| ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1455| `managed-settings.json` | 系统级别，因操作系统而异 | 企业强制执行的设置，您无法覆盖，除了[狭窄的例外](/docs/zh-CN/settings#security-keys-where-the-stricter-value-applies)。请参阅[保存文件的位置](/docs/zh-CN/managed-settings#deploy-a-managed-settings-file)和[Claude Code 使用的托管源](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)。 |1455| `managed-settings.json` | 系统级别，因操作系统而异 | 企业强制执行的设置，您无法覆盖，除了[狭窄的例外](/docs/zh-CN/settings#security-keys-where-the-stricter-value-applies)。请参阅[保存文件的位置](/docs/zh-CN/managed-settings#deploy-a-managed-settings-file)和[Claude Code 使用的托管源](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)。 |

1457| 已安装的 plugins | `~/.claude/plugins` | 克隆的市场、已安装的 plugin 版本和每个 plugin 的数据，由 `claude plugin` 命令管理。对于从市场[`command` 源](/docs/zh-CN/plugin-marketplaces#command-sources)以链接模式安装的 plugin，Claude Code 在此处存储链接而不是副本，plugin 的文件保留在命令打印的目录中。`command` 源需要 Claude Code v2.1.229 或更高版本。请参阅 [plugin 缓存](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution)了解孤立版本如何被清理。 |1457| `AGENTS.md` | 项目根目录、`.claude/` 或任何目录 | 您为 AI 编码代理编写的项目说明。Claude Code 可以[自行加载它](/docs/zh-CN/memory#agents-md)或与 `CLAUDE.md` 一起加载。 |

1458| 已安装的 plugins | `~/.claude/plugins` | 克隆的市场、已安装的 plugin 版本和每个 plugin 的数据，由 `claude plugin` 命令管理。对于从市场[`command` 源](/docs/zh-CN/plugin-marketplaces#command-sources)以链接模式安装的 plugin，Claude Code 在此处存储链接而不是副本，plugin 的文件保留在命令打印的目录中。`command` 源需要 Claude Code v2.1.229 或更高版本。本地目录市场中按相对路径列出的 plugin 也会[从其源目录就地加载](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution)，而不是从缓存副本加载。请参阅 [plugin 缓存](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution)了解孤立版本如何被清理。 |

1458 1459

1459`~/.claude` 还保存 Claude Code 在您工作时写入的数据：记录、提示历史、文件快照、缓存和日志。请参阅下面的[应用数据](#application-data)。1460`~/.claude` 还保存 Claude Code 在您工作时写入的数据：记录、提示历史、文件快照、缓存和日志。请参阅下面的[应用数据](#application-data)。

1460 1461

1552| `feedback/drafts/` | 排队的 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)，等待您在 `/feedback` 中审查。在 `cleanupPeriodDays` 或 30 天后扫除，以较短者为准。当队列达到其 10 个草稿的限制时，Claude Code 删除最旧的草稿以腾出空间。 |1553| `feedback/drafts/` | 排队的 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)，等待您在 `/feedback` 中审查。在 `cleanupPeriodDays` 或 30 天后扫除，以较短者为准。当队列达到其 10 个草稿的限制时，Claude Code 删除最旧的草稿以腾出空间。 |

1553| `usage-data/` | `report.html` 和由 [`/insights`](/docs/zh-CN/costs#analyze-your-usage-patterns) 写入的时间戳报告副本，加上用于构建它们的缓存的每个会话分析数据 |1554| `usage-data/` | `report.html` 和由 [`/insights`](/docs/zh-CN/costs#analyze-your-usage-patterns) 写入的时间戳报告副本，加上用于构建它们的缓存的每个会话分析数据 |

1555| `skills/.trash/`、`plugins/.trash/` | 从 claude.ai 同步的 [Skills](/docs/zh-CN/skills#how-synced-skills-behave) 和 [plugins](/docs/zh-CN/plugins-reference#synced-plugins)，Claude Code 已删除。移到此处而不是删除，以便您可以恢复文件 |

1555 1557

1556`sessions/` 中的会话文件、自动内存以及 Claude Desktop 和 Cowork 记录各自遵循自己的保留规则：1558`sessions/` 中的会话文件、自动内存以及 Claude Desktop 和 Cowork 记录各自遵循自己的保留规则：

1577| `remote-settings.json` | [server-managed settings](/docs/zh-CN/server-managed-settings) 的缓存副本，用于您的组织，或当您的组织未配置任何设置时为 `{}`。仅在会话 [获取它们](/docs/zh-CN/server-managed-settings#platform-availability) 时存在。Claude Code 在启动时和会话期间每小时检查更新。Claude Code 在您注销时删除它。 |1579| `remote-settings.json` | [server-managed settings](/docs/zh-CN/server-managed-settings) 的缓存副本，用于您的组织，或当您的组织未配置任何设置时为 `{}`。仅在会话 [获取它们](/docs/zh-CN/server-managed-settings#platform-availability) 时存在。Claude Code 在启动时和会话期间每小时检查更新。Claude Code 在您注销时删除它。 |

1580 1582

1581<span id="state-files-to-keep" />1583<span id="state-files-to-keep" />

1582 1584

1658您也可以手动删除上面的任何应用数据路径，除了 [state files to keep](#state-files-to-keep)。新会话不受影响。下表显示您对过去会话失去的内容。1660您也可以手动删除上面的任何应用数据路径，除了 [state files to keep](#state-files-to-keep)。新会话不受影响。下表显示您对过去会话失去的内容。

1659 1661

1660| 删除 | 您失去 |1662| 删除 | 您失去 |

1661| ----------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |1663| ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |

1677| `~/.claude/skills/.trash/`、`~/.claude/plugins/.trash/` | 恢复 [synced skills](/docs/zh-CN/skills#how-synced-skills-behave) 和 [synced plugins](/docs/zh-CN/plugins-reference#synced-plugins) 的机会，Claude Code 已删除 |

1675| `~/.claude/debug/`、`~/.claude/plans/`、`~/.claude/image-cache/`、`~/.claude/session-env/`、`~/.claude/shell-snapshots/`、`~/.claude/backups/` | 没有面向用户的内容 |1678| `~/.claude/debug/`、`~/.claude/plans/`、`~/.claude/image-cache/`、`~/.claude/session-env/`、`~/.claude/shell-snapshots/`、`~/.claude/backups/` | 没有面向用户的内容 |

1677 1680

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

Details

257像对待任何其他生产凭证一样对待工作区 API 密钥。[用户设置文件](/docs/zh-CN/settings) `env` 块是一种方便的方式，可以将密钥限定于您的机器，而无需全局导出。257像对待任何其他生产凭证一样对待工作区 API 密钥。[用户设置文件](/docs/zh-CN/settings) `env` 块是一种方便的方式，可以将密钥限定于您的机器，而无需全局导出。

258 258

259<Note>259<Note>

260 `/login` 和 `/logout` 命令不会将您登录到 Claude Platform on AWS 的 Claude.ai 订阅。身份验证通过您的 AWS 凭证或工作区 API 密钥运行。260 `/login` 和 `/logout` 命令不会将您登录到 Claude Platform on AWS 的 claude.ai 订阅。身份验证通过您的 AWS 凭证或工作区 API 密钥运行。

261</Note>261</Note>

262 262

263<h3 id="2-configure-claude-code">263<h3 id="2-configure-claude-code">

claude-projects.md +538 −0 created

Details

1> ## Documentation Index

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

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

5# 让 Claude 通过 Projects 协调持续进行的工作

7> 在一个对话中为 Claude 提供一组相关工作，让它协调共享存储库、说明和内存的并行云会话。

9<Note>

10 Projects 在 Pro 和 Max 计划上处于公开测试阶段，正在逐步推出，首先面向已使用[云会话](/docs/zh-CN/claude-code-on-the-web)且在 claude.ai 聊天或 Cowork 中没有现有项目的账户。它们在 Team 或 Enterprise 计划上还不可用。如果 **Projects** 没有出现在 [claude.ai/code](https://claude.ai/code) 的侧边栏中或[桌面应用](/docs/zh-CN/desktop)的代码选项卡中，说明推出还没有到达您的账户，您可以[加入等待列表](https://claude.com/form/projects)。[并行运行代理](/docs/zh-CN/agents)列出了您在此期间可以使用的内容。

11</Note>

13项目是一个持续进行的对话，Claude 在其中为您协调一系列相关工作。您告诉它需要做什么，它为每个任务启动一个线程。每个线程都是一个[云会话](/docs/zh-CN/claude-code-on-the-web)：Claude Code 在云中运行，而不是在您的机器上运行。线程并行运行，即使您关闭笔记本电脑后也会继续进行，您可以从手机上检查它们并引导它们。

15没有项目的情况下，运行多个会话意味着您自己进行协调：您决定每个会话处理什么，在每个会话的开始重复相同的背景信息，并检查哪个已完成或需要您的回答。使用项目，您可以：

17* **将工作发送到一个地方**：每当出现问题时，将错误报告、堆栈跟踪或任务列表粘贴到对话中。Claude 为每项工作启动一个线程，或将其传递给已在该区域工作的线程，并就地回答快速问题。

18* **设置一次上下文**：每个新线程都以项目的存储库、说明和内存开始，因此您陈述一次的规则（例如要针对哪个分支）会到达所有线程。

19* **离开并返回查看完成的工作**：当您一小时后或第二天早上回来时，**Overview** 窗格显示哪些线程已完成、哪些拉取请求已准备好供审查，以及哪个线程正在等待您的回答。

21如果您已经知道希望项目运行的工作，请直接转到[创建项目](#create-a-project)。

23<h2 id="when-to-use-a-project">

24 何时使用项目

25</h2>

27当工作有一个超越单个会话的目标并不断产生任务时，创建项目是值得的。这些类型的工作非常适合项目：

29* **跨多个代码库的一个目标**："将每个服务升级到新的 lint 配置。"Claude 可以为每个代码库运行一个线程，每个都有自己的拉取请求，[**Overview** 窗格](#see-what-needs-you-in-overview)显示哪些已准备好审查。

30* **您不断提供的一个领域**：一个服务的错误、堆栈跟踪和审查请求，当它们到达您时粘贴到对话中。您在一次修复后告诉 Claude 记住的陷阱在[项目记忆](#give-a-project-standing-context)中供下一次使用。

31* **比一个会话更大的构建或迁移**："构建 `docs/spec.md` 描述的内容"或"将应用从已弃用的 ORM 迁移出去。"工作分成线程，每个处理一部分，您要求 Claude 记住的早期决定会到达后续线程，您在构建期间发现的规范更改和错误进入同一对话。

32* **非代码工作**：一个合同文件夹或支持工单导出，您不断回来提出新问题，例如"在这些工单中找到十个最常见的集成错误。"上传文档而不是添加代码库，线程将每个写作作为文件提交到项目的[**Library** 标签页](#see-what-needs-you-in-overview)。

34在任何情况下，您都可以发送一批任务，告诉 Claude 开始而不要求您确认，离开，并在您回来时在[**Waiting on you**](#see-what-needs-you-in-overview)下找到需要您的线程，或要求 Claude 将部分工作放在[例程](/docs/zh-CN/routines)的时间表上。如果这是您的情况，[创建项目](#create-a-project)。

36<h3 id="when-something-else-fits-better">

37 何时其他方式更合适

38</h3>

40线程在 GitHub 代码库以及您上传到项目的文件、文件夹和 Google Drive 文件夹上工作，而不是仅存在于您机器上的文件或工具。在这些情况下，其他方式更合适：

42* **一个适合在一个会话中完成的任务**："修复不稳定的登录测试。"自己启动一个[云会话](/docs/zh-CN/claude-code-on-the-web)。

43* **需要仅您的机器可以访问的工具或服务的工作**：本地数据库、设备模拟器、VPN 后面的 API。使用本地会话，或[代理视图](/docs/zh-CN/agent-view)同时运行多个。如果工作只需要本地文件，请将它们上传到项目。

44* **一个按时间表重复的任务，周围没有对话**："每周一发布依赖报告。"在其自身上创建一个[例程](/docs/zh-CN/routines)。

45* **多个人在 Slack 频道中给 Claude 工作并一起引导它**：请参阅 [Claude Tag](https://claude.com/docs/claude-tag/overview)。

47项目使用与您其他 Claude Code 会话相同的计划限制，并更快地使用它们。[使用和成本](#usage-and-cost)涵盖了什么使用您的计划以及如何降低成本。

49<h2 id="how-a-project-is-organized">

50 项目如何组织

51</h2>

53项目是一个与 Claude 的协调对话加上它启动的线程来完成工作。这些是它的部分：

55* **项目对话**：一个长期运行的会话，Claude 充当协调员。它接收您发送的内容，决定什么成为线程，并跟踪它启动的每个线程。它看到线程报告回来的内容，而不是它们采取的每一步。

56* **线程**：工作者。每个都是一个单独的[云会话](/docs/zh-CN/claude-code-on-the-web)，有自己的上下文窗口，在自己的分支上完成一项工作，在工作需要时打开拉取请求，并在完成时报告回对话。

57* **每个线程开始时的内容**：

58 * 项目的代码库和文件，加上其[说明和记忆](#give-a-project-standing-context)

59 * `CLAUDE.md`、skills 和[项目每个代码库](#what-threads-pick-up-from-your-repositories)中的 plugins，以及在有一个代码库的项目中，该代码库的权限规则和 hooks

60 * 您 claude.ai 账户上的[连接器](#get-skills-plugins-connectors-and-tools-into-threads)

61 * 一个[云环境](#choose-an-environment-for-threads)，设置其网络访问、环境变量、API 凭证和已安装的工具

62* **Overview 窗格**：您在其中[一次看到所有线程](#see-what-needs-you-in-overview)以及哪些需要您。其他标签页是 **Library**（用于您添加的文件和线程生成的文件）、**Pull requests**（用于线程打开的文件）和 **Routines**（用于项目中的计划工作）。

64线程不会从您自己机器上的 Claude Code 设置中获取任何内容。[将 skills、plugins、连接器和工具放入线程](#get-skills-plugins-connectors-and-tools-into-threads)涵盖了如何为它们提供它们可能缺少的内容。

66以下是这些部分如何连接的方式，从您通过对话到执行工作的线程，**Overview** 跟踪它们的状态：

68<Frame>

69 <img src="https://mintcdn.com/claude-code/e8CLbxM17eD7cAiv/images/claude-projects-overview.svg?fit=max&auto=format&n=e8CLbxM17eD7cAiv&q=85&s=dbf446f69f0bbdb9961d21af207cb93b" className="dark:hidden" alt="项目的图表。您在项目对话中写入，Claude 回答或启动线程。每个线程是一个在自己的分支和拉取请求上工作的云会话。Overview 窗格按状态列出线程，例如准备好审查、等待您和工作中。" width="600" height="250" data-path="images/claude-projects-overview.svg" />

71 <img src="https://mintcdn.com/claude-code/e8CLbxM17eD7cAiv/images/claude-projects-overview-dark.svg?fit=max&auto=format&n=e8CLbxM17eD7cAiv&q=85&s=549a5ba9fea8433729babc37a1f6e9c8" className="hidden dark:block" alt="项目的图表。您在项目对话中写入，Claude 回答或启动线程。每个线程是一个在自己的分支和拉取请求上工作的云会话。Overview 窗格按状态列出线程，例如准备好审查、等待您和工作中。" width="600" height="250" data-path="images/claude-projects-overview-dark.svg" />

72</Frame>

74<h2 id="create-a-project">

75 创建项目

76</h2>

78您在 [claude.ai/code](https://claude.ai/code)、桌面应用的 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)。在浏览器和桌面应用中，有两种方式启动项目：

80* **从头开始**，当您知道希望 Claude 运行的工作流时：打开 **New project** 对话框并命名它。[从头开始启动新项目](#start-a-new-project-from-scratch)会逐步讲解对话框。

81* **从已经在进行工作的云会话**：从该会话的菜单中选择 **Continue as a project**，Claude 从会话正在做的事情中提议项目的设置。请参阅[从现有云会话启动](#start-from-an-existing-cloud-session)。

83无论哪种方式，首先[检查先决条件](#check-the-prerequisites)。

85<h3 id="check-the-prerequisites">

86 检查先决条件

87</h3>

89在创建项目之前，检查您的计划、GitHub 设置以及工作需要到达的内容：

91* **计划**：您在 Pro 或 Max 上，**Projects** 显示在您的侧边栏中。

92* **GitHub，如果项目将处理代码**：您的代码在 github.com 上而不是 GitHub Enterprise Server、GitLab 或 Bitbucket 上，您连接的 GitHub 账户对其有推送访问权限，Claude GitHub App 已安装在其上。如果您使用 [`/web-setup`](/docs/zh-CN/web-quickstart#connect-from-your-terminal) 连接了 GitHub，该令牌让您的其他云会话可以访问代码库，但对于项目线程来说还不够，项目线程需要 Claude GitHub App。[设置 GitHub 访问](#set-up-github-access)有相关步骤。

93* **网络、凭证和工具**：这些来自项目的[云环境](#choose-an-environment-for-threads)。默认环境已经可以访问[常见的包注册表](/docs/zh-CN/cloud-environments#default-allowed-domains)，因此仅在工作需要其他域、密钥或未预装的工具时检查此项。如果工作需要 MCP 服务器，检查它是否在您的 [claude.ai 连接器](https://claude.ai/customize/connectors)中显示为已连接。

95<h3 id="start-a-new-project-from-scratch">

96 从头开始启动新项目

97</h3>

99从头开始启动项目意味着打开 **New project** 对话框，命名工作流，并可选地为其提供目标以及它处理的代码库和文件。只有名称是必需的，因此您可以先创建项目，然后在工作进行时填入其余部分。

100

101<Steps>

102 <Step title="打开 Projects">

103 在 [claude.ai/code](https://claude.ai/code) 或桌面应用的 Code 标签页中，在左侧边栏中选择 **Projects**，然后选择 **New project**。在浏览器中，您也可以直接转到 [claude.ai/code/projects/browse](https://claude.ai/code/projects/browse)。

104 </Step>

105

106 <Step title="填写 New project 对话框">

107 将项目范围限定为一个您将继续添加的工作流，例如保持一个 API 在其延迟目标下所需的一切。[何时使用项目](#when-to-use-a-project)有更多示例。然后填写对话框的字段：

108

109 * **Name**：项目在 **Projects** 列表中的显示方式。

110 * **Goal**（可选）：您试图完成的一行内容，例如"将 p95 API 延迟保持在 200 毫秒以下"。对话中的 Claude 朝着它工作。没有目标的情况下，Claude 从您发送的任务工作，您可以稍后在 **Project settings > General** 中添加目标。

111 * **Context**（可选）：此项目处理的 GitHub 代码库，加上任何线程应该读取的文件、文件夹或 Google Drive 文件夹。为每个点击 **Add**。添加大多数任务需要的代码库而不是工作可能涉及的每一个；[决定要添加哪些代码库](#decide-which-repositories-to-add)涵盖了选择，您可以稍后在 **Project settings > Environment** 中添加更多。

112

113 关于线程应该如何工作的常规规则在[项目说明](#give-a-project-standing-context)中，您在项目存在后设置。

114 </Step>

115

116 <Step title="创建项目">

117 点击 **Create project**。项目的对话打开，底部有一个消息框，您可以在其中为 Claude 描述工作。

118

119 在您的第一个项目上，除非您先发送消息，否则 Claude 在项目创建后会自己进行一轮。该轮使用您的计划。在其中，Claude 可能会：

120

121 * 启动一个线程来探索代码库而不改变任何内容，并提议后续步骤，如果项目有它可以读取的代码库。

122 * 发布从您最近的云会话中提取的 **Setup recommendations**：要添加的代码库、要创建的例程和它可以启动的线程。每个推荐的代码库和例程都默认打开。关闭您不想要的，然后点击 **Update setup** 添加其余的，或忽略建议并自己描述工作。

123 </Step>

124</Steps>

125

126项目现在在侧边栏的 **Projects** 下列出，其对话已打开。[您的第一批](#your-first-batch)涵盖了在您向其发送工作之前要设置的内容。

127

128<h3 id="start-from-an-existing-cloud-session">

129 从现有云会话启动

130</h3>

131

132如果您已经有一个云会话在进行属于项目的工作，请打开侧边栏中会话的菜单并选择 **Continue as a project** 或 **Move to project**：

133

134* **Continue as a project** 创建一个以会话命名的新项目并打开它。Claude 读取会话并在对话中发布 **Setup recommendations** 供您确认。原始会话保留在您的会话列表中，如果它在轮的中间，它会继续运行，因此如果您不想两者同时工作，请自己停止它。如果您使用可能出现在云会话消息框上方的 **Set up project** 横幅，结果是相同的，除了会话的运行轮在项目打开后停止。

135* **Move to project** 将会话的工作带入现有项目。它在该项目的对话中发布一条消息，要求 Claude 读取会话并从中断的地方继续，新工作在项目自己的线程中继续。原始会话保留在您的会话列表中，未改变。

136

137<h3 id="set-up-github-access">

138 设置 GitHub 访问

139</h3>

140

141大多数 GitHub 设置每次发生一次，而不是每个项目。您一次将 GitHub 账户连接到 Claude，Claude GitHub App 每个代码库安装一次，或如果您给它所有代码库，则为整个 GitHub 组织安装一次。当您添加 Claude GitHub App 还不覆盖的代码库或在强制 SSO 的 GitHub 组织中的代码库时，您会回到这些步骤。

142

143<Steps>

144 <Step title="连接您的 GitHub 账户">

145 如果您之前没有使用过 claude.ai/code，您的第一次访问会引导您连接 GitHub；请参阅[连接 GitHub](/docs/zh-CN/web-quickstart#connect-github)。否则使用[GitHub 身份验证选项](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)之一。

146 </Step>

147

148 <Step title="在项目的代码库上安装 Claude GitHub App">

149 安装 [Claude GitHub App](https://github.com/apps/claude) 并授予它项目将使用的代码库。在由 GitHub 组织拥有的代码库上，只有组织所有者可以完成安装；如果您不是，GitHub 会向所有者发送安装请求，项目在他们批准之前无法使用该代码库。

150 </Step>

151

152 <Step title="为强制 SSO 的组织授权 SSO">

153 如果 GitHub 组织强制 SAML SSO，重新连接 GitHub 并为该组织授权 Claude 应用。在您这样做之前，该组织的私有代码库不会出现在 **New project** 对话框或 **Project settings > Environment** 中。

154 </Step>

155</Steps>

156

157当这些步骤之一不完整时，**New project** 对话框和项目页面会命名缺失的步骤并链接到您完成它的地方。在那里完成步骤，然后如果对话框提供，点击 **Check again**。如果代码库之后仍然缺失，请在 GitHub 上打开 Claude GitHub App 的安装，在 [github.com/settings/installations](https://github.com/settings/installations) 用于个人账户，并确认代码库在 **Repository access** 下列出。对于线程或项目在访问仍然错误时报告的错误消息，请参阅[代码库访问错误](#repository-access-errors)。

158

159<h2 id="work-in-a-project">

160 在项目中工作

161</h2>

162

163通过项目对话给 Claude 工作：一次一个任务或一次多个，加上更新和零散的想法。Claude 路由每条消息，线程完成工作并报告回来。

164

165<h3 id="your-first-batch">

166 您的第一批

167</h3>

168

169在您向新项目发送一批工作之前，设置它以便第一批线程以您想要的方式回来：

170

1711. [编写项目说明](#write-project-instructions)：每个线程开始的简报，例如要针对哪个分支、线程如何检查其工作以及什么需要您的批准。

1722. 发送一个真实工作的小部分，或启动 Claude 建议的线程之一（如果它提供了任何），并在它完成时打开线程以查看它如何报告回来以及它在分支上做了什么。如果它假设了错误的东西或无法到达它需要的东西，[线程猜测或停滞而不是询问](#threads-guessed-or-stalled-instead-of-asking)涵盖了在哪里修复。

1733. 检查 **Project settings > General** 中的 **Thread model** 和 **Thread effort**。新项目在高努力下在 Opus 上运行每个线程，这最快地使用您的计划；[选择模型并让 Claude 管理上下文](#choose-models-and-let-claude-manage-context)涵盖了替代方案。

1744. 要求 Claude [在启动线程之前提议线程并一次运行几个](#tune-how-claude-runs-a-project)，一旦几个线程以您想要的方式回来，就放弃这些限制。

175

176<h3 id="send-work-and-read-results">

177 发送工作并读取结果

178</h3>

179

180Claude 决定您在对话中发送的每条消息去哪里：

181

182* 快速问题通常在对话中得到答案。

183* 新工作进入新线程或已在该领域工作的线程，Claude 告诉您哪个。每个新线程显示为您消息下的卡片：一个带有线程标题和状态的框，您点击打开线程。

184* 一条消息中的多个不相关的任务成为单独的线程。

185

186如果 Claude 路由的方式与您想要的不同，请说出来。[调整 Claude 如何运行项目](#tune-how-claude-runs-a-project)列出了您可以告诉它的事情，例如为后续工作重用现有线程或就地回答而不是启动线程。

187

188线程的完整结果保留在线程中，您从对话中打开其卡片来读取它们。线程生成的文件也在 **Overview** 中的 **Library** 标签页上。

189

190有时 Claude 在 **Suggested threads** 列表中提议线程而不是启动它们。点击建议上的箭头启动该线程。当列出多个时，列表下的按钮启动所有这些。

191

192<h3 id="review-a-thread’s-pull-request">

193 审查线程的拉取请求

194</h3>

195

196当线程更改代码时，除非您另外告诉它，否则它会执行以下操作：

197

198* **分支**：在新分支上工作，从代码库的默认分支开始。

199* **拉取请求**：当您要求时打开一个，并可以为错误修复或其他具体更改自己打开一个。

200* **打开后**：使用[自动修复](/docs/zh-CN/claude-code-on-the-web#auto-fix-pull-requests)打开监视拉取请求，无论自动修复是否对您的其他云会话打开。它在 CI 失败时推送修复，处理审查评论，并在检查通过且拉取请求准备好供您审查时在线程中回复。

201

202当线程在对话中的卡片显示拉取请求下一步的按钮时：

203

204* **Resolve conflicts**、**Fix CI**、**Address comments** 和 **Merge it** 将该指令作为来自您的消息发送到线程，因此您可以自己提示线程而不是等待它对拉取请求做出反应。

205* **Review PR** 在 GitHub 上打开拉取请求。

206* **Create PR** 在空闲线程已推送分支但尚未打开拉取请求时出现。点击它直接从该分支创建拉取请求，而不是向线程发送打开拉取请求的指令。

207

208要更改线程何时打开拉取请求，例如仅在您要求时，或它们从哪个分支开始，请在任务中或在[项目说明](#write-project-instructions)中说出来。

209

210<h3 id="see-what-needs-you-in-overview">

211 在 Overview 中查看需要您的内容

212</h3>

213

214**Overview** 窗格在对话旁边跟踪项目的线程。它在您第一次打开新项目时已经打开。项目标题中的 **Overview** 按钮关闭并重新打开它，并在线程等待您时显示一个点。

215

216在桌面应用中，当 Claude 在对话中发布、线程遇到错误或线程需要您的输入时，您还会收到桌面通知，因此您不必保持项目打开来找出。要在每次线程完成一轮时也获得一个，或为项目关闭它们，请在项目的侧边栏菜单中选择 **Notifications**。这些通知仅限桌面：在浏览器中，检查 **Overview** 按钮上的点。

217

218窗格的 **Threads** 标签页按状态对线程进行分组：

219

220| 组 | 其中的内容 |

221| :------------------- | :------------------------------------------------------------------------------- |

222| **Ready for review** | 其拉取请求已打开并等待审查的线程 |

223| **Waiting on you** | 需要您的回复或批准的线程，或失败的线程 |

224| **Working** | 仍在运行的线程 |

225| **Landing** | 其拉取请求已批准或排队合并的线程 |

226| **Idle** | 完成且不等待任何东西的线程 |

227| **Resolved** | 标记为完成的线程：由您从线程的菜单中标记，由 Claude 在您采取最后一步（例如合并其拉取请求）后标记，或在一周无活动后自动标记。您可以从同一菜单重新打开一个 |

228

229窗格的其他标签页是 **Library**（用于您添加的文件和文件夹以及线程生成的文件）、**Pull requests**（一旦线程打开任何）和 **Routines**（用于此项目的[例程](/docs/zh-CN/routines)）。

230

231<h3 id="open-a-thread-when-you-need-control">

232 当您需要控制时打开线程

233</h3>

234

235点击对话中线程的卡片或 **Overview** 中的其行以在 Overview 窗格中打开其记录。从那里您可以：

236

237* 逐步阅读 Claude 做了什么。

238* 通过在线程自己的消息框中写入来引导任务。那里的消息直接进入该线程，而项目对话中的后续只有在 Claude 将后续匹配到该线程时才会到达它。

239* 回答线程等待的权限提示。

240* 使用 **Stop** 中断线程，它在线程工作时替换发送按钮，或按 Esc。

241

242<h3 id="choose-models-and-let-claude-manage-context">

243 选择模型并让 Claude 管理上下文

244</h3>

245

246在 **Project settings > General** 中设置模型和努力。新项目在高[努力](/docs/zh-CN/model-config#adjust-effort-level)下在 Opus 上运行所有地方，对话的努力较低：

247

248* **Thread model** 和 **Thread effort** 适用于线程。要为一个任务使用不同的模型，请在任务中要求它；对于已经运行的线程，使用该线程的模型选择器。

249* **Coordinator model** 和 **Coordinator effort** 适用于项目对话中的 Claude。

250

251您不在项目中管理上下文窗口。线程自动压缩，对话从最近的消息、最近的线程和项目记忆而不是其完整历史工作，因此它可以运行项目运行的时间。将任何必须永远不被丢弃的东西放在[项目记忆](#give-a-project-standing-context)中。如果一个线程超出其上下文，它显示[Claude 在此轮用完了上下文](#context-limit)。

252

253<h3 id="tune-how-claude-runs-a-project">

254 调整 Claude 如何运行项目

255</h3>

256

257在对话中告诉 Claude 一次运行多少个线程、何时发布更新以及何时打开拉取请求。如果 Claude 以您不想要的方式协调，请说出来。例如，您可以说：

258

259* "提议线程并等待我的批准后再启动它们"或"现在启动这些而不要求我确认"

260* "一次最多运行两个线程"或"为同一领域的后续工作重用现有线程"

261* "发布更短的更新"或"仅在某些完成或被阻止时发布"

262* "给我每个线程的状态更新"

263* "用更小的模型做这个任务"

264* "在我看到计划之前不要打开拉取请求"

265* "告诉我这些代码库中有什么问题，不要修复任何东西"，当您想在任何东西成为线程之前查看发现时

266* "在这里回答那个而不是启动线程"，当 Claude 为您打算作为快速问题的东西启动线程时

267

268Claude 自己将这些偏好保存到[项目记忆](#give-a-project-standing-context)并在后续线程中遵循它们。它们是 Claude 遵守的说明，而不是强制设置，因此您以这种方式给出的线程限制不是硬上限。当您想要它精确措辞并从一开始应用到每个线程时，将一个添加到项目说明。

269

270<h3 id="unblock-a-thread-waiting-on-approval">

271 解除等待批准的线程

272</h3>

273

274当线程的模型支持时，线程在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中运行，因此大多数工具调用无需询问您即可运行。当线程需要您的批准时，提示在该线程内，线程等待直到您在那里回答。在项目对话中告诉 Claude 继续不会到达它。

275

276每个批准涵盖该提示，或如果您选择更广泛的选项，则涵盖该线程的其余部分。要让每个线程运行某些命令而不询问，或阻止某些，请将[权限规则](/docs/zh-CN/permissions)添加到代码库的 `.claude/settings.json`。线程仅在有一个代码库的项目中应用它们；请参阅[线程从您的代码库中获取什么](#what-threads-pick-up-from-your-repositories)。

277

278<h2 id="give-a-project-standing-context">

279 给项目提供常规上下文

280</h2>

281

282项目记忆、项目说明和项目的代码库、文件和环境跨线程携带上下文。您设置每个一次，它适用于每个新线程。

283

284| 上下文 | 它携带什么 | 您如何设置它 |

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

286| 项目记忆 | Claude 关于项目的笔记，例如要求、决定和陷阱，存储为文件。每个线程在启动时读取索引文件 `MEMORY.md`，并在需要时打开其他文件 | 在项目对话或任何线程中要求 Claude 记住要求、决定或陷阱，或忘记一个。在 **Project settings > Memory** 中读取、编辑和删除文件 |

287| 项目说明 | 发送到每个新线程和项目对话中 Claude 的文本，最多 16,000 个字符。[编写项目说明](#write-project-instructions)涵盖了要放入其中的内容 | **Project settings > Memory > Project instructions**，或要求 Claude 更改说明 |

288| 代码库、文件和环境 | 每个线程克隆的代码库、每个线程可以在 `/mnt/project-files` 下读取的文件夹和文件，以及线程运行的云环境 | 代码库和环境在 **Project settings > Environment** 中，或在对话中要求 Claude 将代码库添加到项目。文件和文件夹来自 **Overview** 中 **Library** 标签页上的 **Add** |

289

290**Project settings > Memory** 在 **Auto memory** 下列出这些文件，因为 Claude 在项目中工作时自己写入它们。它们与 Claude Code 在您机器上保留的[自动记忆](/docs/zh-CN/memory)分开，即使两者都使用 `MEMORY.md` 索引。项目记忆也与项目代码库中的 `CLAUDE.md` 文件分开。每个线程在启动时仍然从其克隆中读取那些 `CLAUDE.md` 文件，因此将关于代码库的说明放在其 `CLAUDE.md` 中，将关于项目的笔记放在项目记忆中。

291

292<h3 id="write-project-instructions">

293 编写项目说明

294</h3>

295

296项目说明是每个新线程开始的简报。点击项目标题中的齿轮图标打开 **Project settings**，然后转到 **Memory > Project instructions**。有用的简报涵盖：

297

298* 项目的目的

299* 工作发生的地方：哪些代码库、从哪个分支开始、如何命名拉取请求

300* 线程在调用完成之前如何检查自己的工作

301* 当它需要的东西缺失时该做什么

302* 什么需要您的批准

303

304例如：

305

306```text theme={null}

307此项目将支付 API 的 p95 延迟保持在 200 毫秒以下：分析、查询和缓存修复，以及随之而来的依赖升级，在 payments-api 代码库中。

308

309- 从 main 分支并为每个线程打开一个草稿拉取请求。

310- 在您调用工作完成之前，运行 `make test` 和 `make lint` 并在您的最终消息中粘贴摘要行。

311- 如果您无法到达您需要的东西，例如代码库、密钥、API 或连接器，请在您的第一条消息中准确说出缺失的内容并停止。不要替代、模拟或猜测。

312- 不要在没有在线程中询问我的情况下合并、强制推送或更改 CI 配置。

313```

314

315关于一个代码库的规则，例如其构建命令，属于该代码库的 `CLAUDE.md`，每个线程在代码库是项目的一部分时启动时读取。一旦工作进行中，当您纠正线程时，也告诉 Claude 记住纠正：它进入[项目记忆](#give-a-project-standing-context)，后续线程从它开始。

316

317<h3 id="decide-which-repositories-to-add">

318 决定要添加哪些代码库

319</h3>

320

321您添加到项目的代码库在每个线程中都带有其中的所有内容、其代码、`CLAUDE.md` 和 skills。您不添加的代码库仍在范围内：当其任务需要时，线程可以将一个添加到自己。大多数项目同时使用两者：

322

323* **将其添加到项目**，在 **New project** 对话框中、**Project settings > Environment** 中，或通过在对话中要求 Claude 将其添加到项目。从那时起，每个线程克隆它并从其 `CLAUDE.md` 和 skills 加载开始，无论任务是否涉及它。从一个代码库转到多个也改变了线程从每个代码库的 `.claude/settings.json` 中获取什么；请参阅[线程从您的代码库中获取什么](#what-threads-pick-up-from-your-repositories)。

324* **将其留下，让线程在需要时添加它。** 其任务需要项目没有的代码库的线程可以将其添加到自己，线程中的注释说它仅被添加到此线程。克隆发生在任务的中途，因此该代码库的 `CLAUDE.md` 和 skills 在线程启动时不存在。下一个线程再次启动时没有它。线程添加的代码库需要与项目代码库相同的[先决条件](#check-the-prerequisites)：Claude GitHub App 安装在其上并从您的 GitHub 账户推送访问。

325

326项目根本不需要代码库。其线程仍然可以研究、编写文档和在自己的沙箱中编写和运行代码，并将文件提交到 **Library** 标签页。那里的线程也可以在任务需要时将代码库添加到自己。

327

328一旦项目有了代码库，Claude 只能从项目已经使用的 GitHub 所有者添加代码库，无论它是将一个添加到项目还是线程将一个添加到自己。要引入来自不同所有者的代码库，请自己在 **Project settings > Environment** 中将其添加到项目。

329

330对于跨越许多代码库的项目，例如一个具有服务器、网络、移动和桌面代码的功能，添加几乎每个任务涉及的一个或两个代码库，并在[项目说明](#write-project-instructions)中命名其他代码库，以便 Claude 知道其余代码在哪里。线程然后启动小，仅为需要它们的任务拉入其他代码库。

331

332<h3 id="what-threads-pick-up-from-your-repositories">

333 线程从您的代码库中获取什么

334</h3>

335

336每个线程克隆项目中的每个代码库并从所有代码库加载 `CLAUDE.md`、skills 和 plugins。权限规则、hooks 和 `env` 仅来自线程启动的目录中的 `.claude/settings.json`：在有一个代码库时在代码库内，在有多个时在克隆上方，其中没有代码库的文件被读取。

337

338| 在每个代码库中 | 一个代码库 | 多个代码库 |

339| :----------------------------------------------- | :-------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |

340| `CLAUDE.md` | 在线程启动时加载 | 在线程启动时从每个代码库加载 |

341| `.claude/` 下的 Skills、agents 和 commands | 加载 | 从每个代码库加载 |

342| 在 `.claude/settings.json` 中启用的 Plugins | 加载 | 从每个代码库加载。如果两个代码库对 plugin 不同意，请在 **Project settings > Plugins** 中设置它，这优先 |

343| 在 `.claude/settings.json` 中定义的权限规则、hooks 和 `env` | 适用于线程，除了[没有云会话遵守](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)的 `env` 键 | 不适用 |

344

345在有多个代码库的项目中，每个克隆作为[附加目录](/docs/zh-CN/memory#load-from-additional-directories)附加到线程，`CLAUDE.md` 加载打开，这就是为什么每个代码库的 `CLAUDE.md` 和 skills 在启动时加载，即使线程在它们上方启动。在任何情况下，启用的 plugin 提供的 hooks 仍然运行，因为 plugins 从每个代码库加载。在有多个代码库的项目中，将常规规则放在项目说明中，并通过[云环境](#choose-an-environment-for-threads)为线程提供环境变量。

346

347<h3 id="choose-an-environment-for-threads">

348 为线程选择环境

349</h3>

350

351每个新线程在项目的[云环境](/docs/zh-CN/cloud-environments)中启动。环境设置线程可以到达哪些域、它们有哪些环境变量、哪些 API 凭证被添加到它们的请求中，以及设置脚本在 Claude 启动之前安装什么。线程使用默认的 Anthropic 托管环境，直到您在 **Project settings > Environment** 中选择一个。

352

353如果线程需要到达内部 API 或私有包注册表，或需要您的机器通常持有的令牌，请更改环境而不是项目：请参阅[网络访问](/docs/zh-CN/cloud-environments#network-access)、[添加 API 凭证](/docs/zh-CN/cloud-environments#add-api-credentials)和[设置脚本](/docs/zh-CN/cloud-environments#setup-scripts)。

354

355<h3 id="get-skills-plugins-connectors-and-tools-into-threads">

356 将 skills、plugins、connectors 和工具放入线程

357</h3>

358

359线程是云会话，因此它们没有仅在您机器上安装的 skills、MCP 服务器、plugins 和工具。要使这些中的每一个对线程可用：

360

361* Skills、subagents 和 commands：将它们提交到您添加到项目的代码库，例如 `.claude/skills/<skill-name>/SKILL.md` 处的 skill。每个线程克隆项目中的每个代码库并从每个代码库加载 `.claude/skills/`、`.claude/agents/` 和 `.claude/commands/`，因此提交到一个代码库的 skill 在每个新线程中可用。线程也加载您为 claude.ai 账户启用的 skills。

362* Plugins：在 **Project settings > Plugins** 中添加它们；它们加载到每个新线程中。代码库在其 `.claude/settings.json` 中声明的 Plugins 也加载；请参阅[什么从您的设置中进行](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)。

363* MCP 服务器：线程从您 claude.ai 账户上的连接器获取其 MCP 工具，这些是您在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 一次连接的 MCP 服务器，或通过 **Project settings > Environment** 中的 **Manage connectors** 链接。每个线程可以使用所有这些而无需每个项目的设置。项目对话本身没有连接器，因此将需要一个的工作作为线程的任务发送。在有一个代码库的项目中，线程也从该代码库的[`.mcp.json`](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)加载 MCP 服务器。[连接器如何到达 Claude Code](/docs/zh-CN/mcp#how-connectors-reach-claude-code)列出了云会话的规则和关闭连接器的设置。

364* 命令行工具和包：在环境的[设置脚本](/docs/zh-CN/cloud-environments#setup-scripts)中安装它们。

365

366要查看运行线程在 claude.ai/code 有哪些连接器，请打开线程并从其消息框旁的 **+** 菜单中选择 **Connectors**。在那里关闭连接器会将其从该线程中移除，并且在您重新打开它之前，它对之后启动的线程保持关闭。线程在您向其发送下一条消息后获取您添加或重新连接的连接器。

367

368<h2 id="project-settings-reference">

369 项目设置参考

370</h2>

371

372您在 claude.ai/code 或桌面应用中更改项目设置，而不是在 `settings.json` 中。从项目侧边栏菜单中的 **Settings** 或项目标题中的齿轮图标打开 **Project settings**。

373

374设置在您更改时保存；您正在编辑的文本字段，例如目标或说明，显示 **Save changes** 和 **Discard**，直到您离开它。对说明、代码库、plugins 和 **Project settings** 中的环境的更改到达新线程，而不是已经运行的线程。

375

376| 设置 | 部分 | 它控制什么 |

377| :------------------------- | :---------- | :--------------------------------------------------------------- |

378| 名称、图标和目标 | General | 侧边栏中项目的名称和图标，以及其一行目标 |

379| Coordinator model 和 effort | General | 项目对话中 Claude 的模型和[努力级别](/docs/zh-CN/model-config#adjust-effort-level) |

380| Thread model 和 effort | General | 线程的模型和努力级别 |

381| 项目说明 | Memory | [常规规则](#give-a-project-standing-context)每个新线程接收 |

382| 项目代码库 | Environment | 新线程克隆的代码库 |

383| 云环境 | Environment | 新线程运行的[云环境](#choose-an-environment-for-threads) |

384| Connectors | Environment | 管理 claude.ai connectors 线程获取的链接 |

385| Plugins | Plugins | 加载到每个新线程的 plugins |

386| Usage | Usage | 按线程和按模型的[令牌使用](#usage-and-cost) |

387| Memory | Memory | 项目的[记忆文件](#give-a-project-standing-context) |

388| Restart Claude | General | 当[Claude 在那里停止响应](#claude-hasnt-responded)时重启项目对话 |

389| Pause、Archive、Delete | General | 停止、隐藏或删除项目；请参阅[暂停、存档或删除项目](#pause-archive-or-delete-a-project) |

390

391<h3 id="pause-archive-or-delete-a-project">

392 暂停、存档或删除项目

393</h3>

394

395所有三个控件都在 **Project settings > General** 的底部：

396

397* **Pause**：一次停止所有东西。每个运行的线程和对话都被中断，没有新线程启动，例程不运行，项目不接受消息，直到您恢复它。点击同一地方或项目消息框上方的横幅中的 **Resume**；暂停的线程在您之后向其发送消息时继续。

398* **Archive**：从侧边栏隐藏项目并存档其线程，这停止任何正在运行或监视拉取请求的线程。项目中的例程在存档时不运行。要恢复项目，请从 Projects 页面打开它并点击 **Unarchive**。其线程保持存档，直到您从会话列表中单独取消存档它们。

399* **Delete**：永久删除项目及其线程、其记忆和其文件，并关闭项目的例程。这无法撤销。线程推送到 GitHub 的分支和拉取请求不受影响。

400

401<h2 id="usage-and-cost">

402 使用和成本

403</h2>

404

405项目使用计入与您其他 Claude Code 会话相同的[计划限制](/docs/zh-CN/errors#youve-hit-your-session-limit)，项目本身无法超过这些限制。

406

407达到您计划限制的线程等待并在限制重置时自己继续，因此您留下运行的工作在您的下一个使用窗口中开始使用，无需来自您的消息。[线程达到使用限制](#usage-limit-reached)涵盖了您看到的内容、如何停止它，以及不等待的一种情况。

408

409工作仅在您为您的账户打开[使用信用](/docs/zh-CN/costs#add-usage-credits-to-your-subscription)时才超过您的计划限制。线程无法为您打开它们。

410

411<h3 id="what-draws-on-your-plan">

412 什么使用您的计划

413</h3>

414

415项目比单个会话更快地使用您的限制，特别是在 Pro 计划上，您应该期望在运行一个的日子里更快地达到您的限制。项目的这些部分使用您的计划：

416

417* **运行线程**：每个都是一个完整的会话，多个可以同时运行。没有固定数字；Claude 启动工作需要的尽可能多，您[要求](#tune-how-claude-runs-a-project)的限制是偏好而不是上限。强制限制是每天跨您的项目 200 个新线程。

418* **对话**：Claude 使用自己的令牌读取线程报告的内容并决定下一步做什么。

419* **线程监视拉取请求**：当 CI 失败或审查评论到达其拉取请求时，空闲线程唤醒并再次使用您的计划。要停止这个，请在线程中要求它停止监视拉取请求。

420

421没有运行线程、没有监视拉取请求和没有新消息的项目在闲置时不使用您的计划，存档的项目也不使用。

422

423<h3 id="see-and-reduce-a-project’s-usage">

424 查看和减少项目的使用

425</h3>

426

427在 **Project settings** 中打开 **Usage** 以按线程和按模型查看令牌使用，以及有多少进入项目对话。要降低它：

428

429* 路由到已闲置超过[缓存生命周期](/docs/zh-CN/prompt-caching#cache-lifetime)（Pro 和 Max 在您计划限制内为一小时）的线程的后续，在做任何事情之前重新读取该线程的整个对话。对于新工作，要求 Claude 启动新线程可以使用比恢复大的旧线程更少的。

430* 对于不需要最大模型的工作，为线程、对话或两者[选择更小的模型或更低的努力级别](#choose-models-and-let-claude-manage-context)。

431* 在项目对话中要求 Claude 一次运行更少的线程，或自己回答小问题而不是启动线程。

432

433<h2 id="how-projects-relate-to-other-claude-code-features">

434 项目与其他 Claude Code 功能的关系

435</h2>

436

437几个 Claude Code 功能让多个会话同时工作，因此并行运行工作本身不是项目的目的。在项目中，Claude 启动和跟踪会话而不是您，每个都从相同的代码库、说明和记忆开始，工作在云中生活，只要它持续。这是每个相邻功能如何连接到项目的方式：

438

439* **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)有并排比较。

440* **云会话**：每个线程都是一个[云会话](/docs/zh-CN/claude-code-on-the-web)，由 Claude 而不是您启动和跟踪。您自己启动的云会话可以通过[**Continue as a project** 或 **Move to project**](#start-from-an-existing-cloud-session)成为项目或提供一个。

441* **例程**：当您在项目中要求计划工作时，Claude 创建一个[例程](/docs/zh-CN/routines)，作为该项目中的线程运行，并出现在其 **Routines** 标签页上。您在项目外创建的例程继续自己工作。

442* **本地会话和代理视图**：您的终端、IDE 或桌面应用的本地环境中的会话在您的机器上运行，不能是项目的一部分。[代理视图](/docs/zh-CN/agent-view)是用于跟踪多个这些本地会话的屏幕；它没有协调员。

443* **Worktrees**：一个[worktree](/docs/zh-CN/worktrees)为每个本地会话提供其自己的代码库工作副本，因此您机器上的并行会话不会相互覆盖。线程不需要它们：每个线程将其代码库克隆到其自己的云沙箱中，并在其自己的分支上工作。

444* **代理团队**：一个[代理团队](/docs/zh-CN/agent-teams)是一个会话，为单个任务启动队友会话，在您的机器上或在云会话内，并以该任务结束。

445* **claude.ai 聊天和 Cowork 中的 Projects**：[早期的 Projects 体验](https://support.claude.com/en/articles/9517075-what-are-projects)，对对话和参考文件进行分组，没有线程或协调员。这些项目继续按照今天的方式工作，直到重新设计的体验到达它们。

446

447[并行运行代理](/docs/zh-CN/agents)并排比较这些选项。

448

449<h2 id="limitations">

450 限制

451</h2>

452

453* Projects 在 claude.ai/code、桌面应用和 Claude 移动应用中可用，不在终端 CLI 或通过 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 中。CLI 的 [`claude project`](/docs/zh-CN/cli-reference) 命令（它管理目录的本地 Claude Code 状态）是无关的。

454* 项目线程是[云会话](/docs/zh-CN/claude-code-on-the-web)，Anthropic 作为模型提供者。[安全](/docs/zh-CN/security)和[数据使用](/docs/zh-CN/data-usage)涵盖了云会话如何隔离以及保留什么。

455* 本地会话不能是项目的一部分。

456* 线程的沙箱在轮之间暂停，并在线程继续时恢复。如果沙箱无法恢复，线程从新克隆继续，因此未提交的更改可能会丢失。在长任务上，要求 Claude 提交和推送进行中的工作。

457* 项目属于一个用户。您不能与另一个用户共享项目或其线程，线程记录没有其他云会话具有的共享选项。在测试版期间没有项目的组织级控制。

458* 线程属于启动它的一个项目。您不能将线程移动或复制到另一个项目，或将其移出以独立存在。[**Move to project**](#start-from-an-existing-cloud-session)仅以另一种方式进行：它将云会话的工作带入项目。

459

460<h2 id="troubleshooting">

461 故障排除

462</h2>

463

464对于 **New project** 对话框中的 GitHub 设置提示，请参阅[设置 GitHub 访问](#set-up-github-access)。

465

466<h3 id="a-thread-looks-stuck">

467 线程看起来卡住了

468</h3>

469

470Claude 不发布线程采取的每一步，因此显示为运行且项目对话中没有新消息的线程通常仍在工作。新线程也在 Claude 开始之前配置其[云环境](/docs/zh-CN/cloud-environments)，因此其第一次更新需要一会儿。打开线程读取其记录。如果线程等待权限提示，请在那里回答。

471

472<h3 id="threads-guessed-or-stalled-instead-of-asking">

473 线程猜测或停滞而不是询问

474</h3>

475

476当多个线程回来时假设了错误的东西、解决了缺失的访问或停止了"被阻止"，原因通常是项目设置中的相同间隙，而不是每个任务的问题。在修复任何东西之前排序哪些线程是合理的：

477

4781. 在对话中要求 Claude："对于每个打开的线程，列出您要求它做什么、它假设或无法到达什么，以及它在等待什么。"Claude 读取每个线程并在对话中回答。

4792. 对于从错误假设开始的线程，从 **Overview** 打开线程并从其菜单标记为已解决，或在其消息框中告诉它做什么。其分支和任何拉取请求保留在 GitHub 上，直到您删除它们。

4803. 一次修复间隙，在[项目说明](#give-a-project-standing-context)或[环境](#choose-an-environment-for-threads)中，然后在再次发送其余工作作为新线程之前发送一个线程。

481

482<h3 id="claude-hasnt-responded">

483 Claude 没有响应

484</h3>

485

486当 Claude 运行但其回复没有到达项目时，项目对话显示"Claude hasn't responded"横幅。点击横幅上的 **Restart Claude**，或转到 **Project settings > General** 并在 **Restart Claude** 行中点击 **Restart**。Claude 重新连接到对话；它正在写的任何回复都丢失了，线程不受影响。

487

488<h3 id="repository-access-errors">

489 代码库访问错误

490</h3>

491

492三条消息意味着线程或项目无法到达其代码库之一。项目线程需要[GitHub 先决条件](#check-the-prerequisites)，即使您的其他云会话无故障地克隆相同的代码库。

493

494* **"Couldn't start the session — Claude doesn't have GitHub access to this project's repository"**，在线程启动之前报告，当 Claude GitHub App 未安装在该代码库上、已暂停或未链接到您连接的 GitHub 账户时。

495* **"Unable to access your repository"**，由线程报告，当其克隆失败时：GitHub 拒绝了克隆、在项目拥有的名称下找不到代码库，或线程被要求启动的分支不存在。

496* **"Claude can't access"** 一个代码库，在您在 **New project** 对话框或 **Project settings** 中保存代码库时显示。消息继续带有安装链接和重新连接链接。如果 Claude GitHub App 不在该代码库上，使用安装链接，如果它在，使用重新连接链接，因为 GitHub App 可以在 GitHub 上安装而不链接到您连接到 Claude 的账户。如果消息说 GitHub App 已暂停或不包括此代码库，请按照其链接到 GitHub 修复。

497

498要修复任何一个，点击消息提供的按钮，例如 **Install GitHub App** 或 **Select repositories on GitHub**，然后 **Check again**。当块在 GitHub 组织一侧时，例如尚未批准应用的所有者或排除 Claude 的 IP 允许列表，消息显示 **See how to fix** 链接。如果没有按钮，请按照[设置 GitHub 访问](#set-up-github-access)，然后发送另一条消息重试。

499

500<h3 id="usage-limit-reached">

501 线程达到使用限制

502</h3>

503

504当线程或项目对话达到您计划的五小时或每周限制时，它自己保持重试并在限制重置时继续。在它等待时，线程显示 **Service is busy**，带有"Claude is still retrying and will continue automatically."。您不需要做任何事情工作就能继续。如果您宁愿它不使用您的下一个使用窗口，请点击线程中的 **Stop**，或[暂停项目](#pause-archive-or-delete-a-project)以保持每个线程。例程启动的线程不等待：其轮停止，带有限制错误，您在限制重置后向其发送消息。

505

506[使用限制错误](/docs/zh-CN/errors#youve-hit-your-session-limit)解释了限制以及何时重置。

507

508<h3 id="additional-usage-credits-are-required">

509 需要额外的使用信用

510</h3>

511

512线程或项目对话发出了您的计划仅用使用信用覆盖的请求，例如对您的计划不包括的模型或上下文大小的请求，并且使用信用未为您的账户打开。[将使用信用添加到您的订阅](/docs/zh-CN/costs#add-usage-credits-to-your-subscription)涵盖了谁可以在每个计划上打开或购买它们。一旦信用可用，发送另一条消息重试。

513

514<h3 id="context-limit">

515 其他消息

516</h3>

517

518这些消息命名它们自己的原因。表格为每个提供下一步。

519

520| 消息 | 要做什么 |

521| :------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------- |

522| "Unable to connect to repository"，带有"Claude couldn't reach GitHub to fetch your repository" | 等一会儿，然后发送另一条消息重试 |

523| "Unable to connect to repository"，带有"Claude couldn't access your repository or environment" | 您的 GitHub 账户需要对代码库的推送访问，环境必须仍然存在。在 **Project settings > Environment** 中检查两者，然后重试 |

524| "Couldn't show the setup proposal" | 您打开的应用比 Claude 发送的 **Setup recommendations** 更旧。刷新页面或重启桌面应用，或要求 Claude 再次提议设置 |

525| "The project's environment was removed" | 在 **Project settings > Environment** 中选择不同的环境；更改适用于新线程 |

526| "Setup script failed" | 点击错误上的 **Edit setup script**，在环境中修复脚本，然后发送另一条消息。[设置脚本失败](/docs/zh-CN/web-quickstart#setup-script-failed)列出常见原因 |

527| "Claude ran out of context on this turn" | 线程填满了其上下文窗口。如果消息说线程在新会话中继续，它自己继续；否则在项目对话中要求 Claude 为剩余工作启动新线程 |

528| "Reached the turn limit" | 线程达到了 [`CLAUDE_CODE_MAX_TURNS`](/docs/zh-CN/env-vars) 设置的代理轮次上限。发送另一条消息继续，或在设置它的地方提高或删除该变量 |

529

530<h2 id="related-resources">

531 相关资源

532</h2>

533

534* [在云中使用 Claude Code](/docs/zh-CN/claude-code-on-the-web)：每个线程背后的云会话如何工作，包括 GitHub 访问选项和拉取请求上的自动修复

535* [配置云环境](/docs/zh-CN/cloud-environments)：更改线程可以在网络上到达什么，为它们提供环境变量和 API 凭证，并使用设置脚本安装工具

536* [使用例程自动化工作](/docs/zh-CN/routines)：例程的时间表、触发器和管理，包括 Claude 从项目创建的那些

537* [使用代理视图管理多个代理](/docs/zh-CN/agent-view)：当工作需要仅您的机器可以到达的工具或服务时，在您自己的机器上运行和跟踪多个会话

538* [Projects redesigned: from folder to conversation](https://claude.com/blog/projects-redesigned)：发布公告，带有使项目成为与 Claude 对话的思考

cli-reference.md +75 −75

Details

57 CLI 标志57 CLI 标志

58</h2>58</h2>

59 59

~~60使用这些命令行标志自定义 Claude Code 的行为。`claude --help` 不会列出每个标志，因此标志在 `--help` 中的缺失并不意味着它不可用。~~60使用这些命令行标志自定义 Claude Code 的行为。`claude --help` 不会列出每个标志，因此标志在 `--help` 中不出现并不意味着它不可用。

61 61

62| 标志 | 描述 | 示例 |62| 标志 | 描述 | 示例 |

63| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------- |63| :---------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------- |

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>` | 为此会话启用服务器端 [advisor tool](/docs/zh-CN/advisor)，使用模型别名 `fable`、`opus` 或 `sonnet`，或完整模型 ID。优先于会话的 `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 动态定义自定义 subagents。接受 [为 CLI 定义的 subagents 列出的字段](/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)。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"}}'` |

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` | 将自定义文本附加到每个 [subagent](/docs/zh-CN/sub-agents) 的系统提示末尾，包括嵌套的 subagents，除了 [forked subagent](/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"` |

71| `--append-subagent-system-prompt-file` | 从文件加载文本并将其附加到 [subagent](/docs/zh-CN/sub-agents) 系统提示。`--append-subagent-system-prompt` 的替代方案，用于文本太长而无法在命令行上传递。这两个标志无法组合。仅在非交互模式下与 `-p` 一起应用。需要 Claude Code v2.1.261 或更高版本 | `claude -p --append-subagent-system-prompt-file ./subagent-rules.txt "query"` |71| `--append-subagent-system-prompt-file` | 从文件加载文本并将其附加到[子代理](/docs/zh-CN/sub-agents)系统提示。`--append-subagent-system-prompt` 的替代方案，用于命令行上传递的文本过长。这两个标志不能组合。仅在使用 `-p` 的非交互模式下应用。需要 Claude Code v2.1.261 或更高版本 | `claude -p --append-subagent-system-prompt-file ./subagent-rules.txt "query"` |

74| `--autocompact <auto\|tokens>` | 为此会话设置 [auto-compact 窗口](/docs/zh-CN/model-config#set-the-auto-compact-window)，而不更改您保存的设置。接受与 `/autocompact` 相同的值；该部分涵盖值形式以及什么覆盖标志。需要 Claude Code v2.1.221 或更高版本 | `claude --autocompact 500k` |74| `--autocompact <auto\|tokens>` | 为此会话设置[自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window)而不更改您保存的设置。接受与 `/autocompact` 相同的值；该部分涵盖值形式以及什么覆盖标志。需要 Claude Code v2.1.221 或更高版本 | `claude --autocompact 500k` |

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、自定义命令、subagents、plugins、MCP 服务器、自动内存和 CLAUDE.md 的自动发现，以便脚本化调用启动更快。您使用 `--add-dir` 传递的目录中的 Skills 仍然加载。Claude 可以访问 Bash、文件读取和文件编辑工具。设置 [`CLAUDE_CODE_SIMPLE`](/docs/zh-CN/env-vars)。请参阅 [bare mode](/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` 结合以运行特定的 subagent。无法与 `-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` 结合以运行特定的子代理。不能与 `-p`/`--print` 结合；请参阅[错误参考](/docs/zh-CN/errors#command-line-errors) | `claude --bg "investigate the flaky test"` |

79| `--channels` | （研究预览）MCP 服务器，其 [channel](/docs/zh-CN/channels) 通知 Claude 应在此会话中侦听。以空格分隔的 `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` | 使用任务描述在 claude.ai 上创建新的 [网络会话](/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"` |

82| `--continue`, `-c` | 加载当前目录中最近的对话，包括 [已完成的后台会话](/docs/zh-CN/sessions#resume-a-session)；打开已完成的后台会话需要 Claude Code v2.1.257 或更高版本。跳过使用 `claude -p` 或 Agent SDK 创建的会话，以及其第一个提示为 `/loop` 的会话。`claude -p --continue` 包括 `-p`、SDK 和 `/loop` 会话。包括使用 `/add-dir` 添加此目录的会话 | `claude --continue` |82| `--continue`, `-c` | 加载当前目录中最近的对话，包括[已完成的后台会话](/docs/zh-CN/sessions#resume-a-session)；打开已完成的后台会话需要 Claude Code v2.1.257 或更高版本。跳过使用 `claude -p` 或 Agent SDK 创建的会话，以及第一个提示为 `/loop` 的会话。`claude -p --continue` 包括 `-p`、SDK 和 `/loop` 会话。包括使用 `/add-dir` 添加此目录的会话 | `claude --continue` |

83| `--dangerously-load-development-channels` | 启用不在批准的允许列表中的 [channels](/docs/zh-CN/channels-reference#test-during-the-research-preview)，用于本地开发。接受 `plugin:<name>@<marketplace>` 和 `server:<name>` 条目。提示确认 | `claude --dangerously-load-development-channels server:webhook` |83| `--dangerously-load-development-channels` | 启用不在批准的允许列表上的[频道](/docs/zh-CN/channels-reference#test-during-the-research-preview)，用于本地开发。接受 `plugin:<name>@<marketplace>` 和 `server:<name>` 条目。提示确认 | `claude --dangerously-load-development-channels server:webhook` |

84| `--dangerously-skip-permissions` | 跳过权限提示。等同于 `--permission-mode bypassPermissions`。请参阅 [权限模式](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode) 了解此操作跳过和不跳过的内容。对于使用 `--bg` 启动的会话，该模式 [在主管重启会话时持久化](/docs/zh-CN/agent-view#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` |84| `--dangerously-skip-permissions` | 跳过权限提示。等同于 `--permission-mode bypassPermissions`。请参阅[权限模式](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)了解此操作跳过和不跳过的内容。对于使用 `--bg` 启动的会话，当主管重新启动会话时，该模式[持续存在](/docs/zh-CN/agent-view#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` |

88| `--disallowedTools`, `--disallowed-tools` | 拒绝规则。裸工具名称从 Claude 的上下文中删除匹配的工具：`"Edit"` 删除 Edit，`"*"` 删除每个工具，`"mcp__*"` 删除每个 MCP 工具。作用域规则（如 `Bash(rm *)` ）使工具保持可用，仅拒绝 [如所写](/docs/zh-CN/permissions#bash-rule-limits) 匹配的调用。命名 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 的规则在任何其他工具保持时无法删除它 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |88| `--disallowedTools`, `--disallowed-tools` | 拒绝规则。裸工具名称从 Claude 的上下文中删除匹配的工具：`"Edit"` 删除 Edit，`"*"` 删除每个工具，`"mcp__*"` 删除每个 MCP 工具。作用域规则（如 `Bash(rm *)`）使工具保持可用，仅拒绝[如所写](/docs/zh-CN/permissions#bash-rule-limits)匹配的调用。命名 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 的规则在任何其他工具保持时无法删除它 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |

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>` | 创建在 [自托管环境](/docs/zh-CN/self-hosted-environments) 上运行的新云会话，使用给定的 ID。环境 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 状态标志）移到第一条用户消息中。改进在运行相同任务的不同用户和机器之间的提示缓存重用。仅适用于默认系统提示；当设置 `--system-prompt` 或 `--system-prompt-file` 时忽略。与 `-p` 一起用于脚本化的多用户工作负载 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |92| `--exclude-dynamic-system-prompt-sections` | 将系统提示的每台机器部分（工作目录、环境信息、内存路径、git-repo 标志）移到第一条用户消息中。改进跨不同用户和运行相同任务的机器的提示缓存重用。仅适用于默认系统提示；当设置 `--system-prompt` 或 `--system-prompt-file` 时忽略。与 `-p` 一起用于脚本化的多用户工作负载 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

94| `--fallback-model` | 当主模型过载或不可用时启用自动回退到指定的模型，例如已停用的模型。接受逗号分隔的列表，按顺序尝试。请参阅 [Fallback model chains](/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` |

96| `--forward-subagent-text` | 在输出流中发出 [subagent](/docs/zh-CN/sub-agents) 文本和思考块作为 `assistant` 和 `user` 消息，设置 `parent_tool_use_id`，以便您可以重建每个 subagent 的记录。没有此标志，Claude Code 会省略在 [前台](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background) 运行的 subagent 的文本和思考块。需要 `--print` 和 `--output-format stream-json`。Claude Code 也转发来自 [嵌套 subagents](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents) 的消息，将 `parent_tool_use_id` 设置为生成每个 subagent 的 Agent 工具调用的 ID；这需要 Claude Code v2.1.219 或更高版本。[`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/zh-CN/env-vars) 环境变量启用相同的行为。需要 Claude Code v2.1.211 或更高版本 | `claude -p --output-format stream-json --verbose --forward-subagent-text "query"` |96| `--forward-subagent-text` | 在输出流中发出[子代理](/docs/zh-CN/sub-agents)文本和思考块作为 `assistant` 和 `user` 消息，设置 `parent_tool_use_id`，以便您可以重建每个子代理的记录。没有此标志，Claude Code 会省略在[前台](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)运行的子代理的文本和思考块。需要 `--print` 和 `--output-format stream-json`。Claude Code 也转发来自[嵌套子代理](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents)的消息，将 `parent_tool_use_id` 设置为生成每个子代理的 Agent 工具调用的 ID；这需要 Claude Code v2.1.219 或更高版本。[`CLAUDE_CODE_FORWARD_SUBAGENT_TEXT`](/docs/zh-CN/env-vars) 环境变量启用相同的行为。需要 Claude Code v2.1.211 或更高版本 | `claude -p --output-format stream-json --verbose --forward-subagent-text "query"` |

98| `--ide` | 如果恰好有一个有效的 IDE 可用，则在启动时自动连接到 IDE | `claude --ide` |98| `--ide` | 如果恰好有一个有效的 IDE 可用，在启动时自动连接到 IDE | `claude --ide` |

101| `--include-hook-events` | 在输出流中包含 hook 生命周期事件。`SessionStart` 和 `Setup` hook 事件始终包含，不需要此标志。某些 hook 事件，例如 `Notification`、`SessionEnd`、`PreCompact` 和 `PostCompact`，即使使用此标志也永远不会产生 `hook_started` 事件。对于这些事件，Claude Code 仍然在命令 hook 运行超过一秒时发出 `hook_progress` 并输出，并仅在 [在后台运行的 hook](/docs/zh-CN/hooks#run-hooks-in-the-background) 完成时发出 `hook_response`。需要 `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-hook-events "query"` |101| `--include-hook-events` | 在输出流中包含 hook 生命周期事件。`SessionStart` 和 `Setup` hook 事件始终包含，不需要此标志。某些 hook 事件（如 `Notification`、`SessionEnd`、`PreCompact` 和 `PostCompact`）永远不会产生 `hook_started` 事件，即使使用此标志也是如此。对于这些事件，Claude Code 仍然在命令 hook 运行超过一秒时发出 `hook_progress` 并输出，并仅在[在后台运行的 hook](/docs/zh-CN/hooks#run-hooks-in-the-background) 完成时发出 `hook_response`。需要 `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-hook-events "query"` |

102| `--include-partial-messages` | 在输出中包含部分流事件。需要 `--print` 和 `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-partial-messages "query"` |102| `--include-partial-messages` | 在输出中包含部分流事件。需要 `--print` 和 `--output-format stream-json` | `claude -p --output-format stream-json --verbose --include-partial-messages "query"` |

104| `--json-schema` | 在代理完成其工作流后获得与 JSON Schema 匹配的验证 JSON 输出（仅打印模式）。请参阅 [结构化输出](/docs/zh-CN/agent-sdk/structured-outputs)。Claude Code 在无效的 schema 上以错误退出，并接受 `format` 关键字作为注释而无需客户端验证 | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |104| `--json-schema` | 在代理完成其工作流后获得与 JSON Schema 匹配的验证 JSON 输出（仅打印模式）。请参阅[结构化输出](/docs/zh-CN/agent-sdk/structured-outputs)。Claude Code 在无效架构上以错误退出，并接受 `format` 关键字作为注释而不进行客户端验证 | `claude -p --json-schema '{"type":"object","properties":{...}}' "query"` |

106| `--max-budget-usd` | API 调用前停止的最大美元金额（仅打印模式）。来自 [subagents](/docs/zh-CN/sub-agents) 的支出计入上限。一旦支出达到上限，生成另一个 subagent 失败，出现 `Budget limit reached`，Claude Code 停止仍在运行的后台 subagents；上限执行行为需要 Claude Code v2.1.217 或更高版本 | `claude -p --max-budget-usd 5.00 "query"` |106| `--max-budget-usd` | 在停止之前在 API 调用上花费的最大美元金额（仅打印模式）。来自[子代理](/docs/zh-CN/sub-agents)的支出计入上限。一旦支出达到上限，生成另一个子代理失败，出现 `Budget limit reached`，Claude Code 停止仍在运行的后台子代理；上限执行行为需要 Claude Code v2.1.217 或更高版本 | `claude -p --max-budget-usd 5.00 "query"` |

108| `--mcp-config` | 从 JSON 文件或字符串加载 MCP 服务器（以空格分隔）。当您使用 `-p` 传递此标志时，Claude Code 等待仍待连接的服务器连接后再运行第一轮，最多等待 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 启动超时 30 秒；具有 [缓存工具列表](/docs/zh-CN/mcp#managing-your-servers) 的服务器跳过等待并在首次使用时连接。等待需要 Claude Code v2.1.221 或更高版本 | `claude --mcp-config ./mcp.json` |108| `--mcp-config` | 从 JSON 文件或字符串加载 MCP 服务器（空格分隔）。当您使用 `-p` 传递此标志时，Claude Code 在运行第一个转之前等待仍待处理的服务器连接，最多 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 启动超时，默认 30 秒；具有[缓存工具列表](/docs/zh-CN/mcp#managing-your-servers)的服务器跳过等待并在首次使用时连接。等待需要 Claude Code v2.1.221 或更高版本 | `claude --mcp-config ./mcp.json` |

109| `--model` | 为当前会话设置模型，使用 [模型别名](/docs/zh-CN/model-config#model-aliases)（如 `sonnet`、`opus`、`haiku` 或 `fable`）或模型的完整名称。覆盖 [`model`](/docs/zh-CN/settings-reference#model) 设置和 [`ANTHROPIC_MODEL`](/docs/zh-CN/model-config#environment-variables) | `claude --model claude-sonnet-5` |109| `--model` | 使用[模型别名](/docs/zh-CN/model-config#model-aliases)（如 `sonnet`、`opus`、`haiku` 或 `fable`）或模型的完整名称为当前会话设置模型。覆盖 [`model`](/docs/zh-CN/settings-reference#model) 设置和 [`ANTHROPIC_MODEL`](/docs/zh-CN/model-config#environment-variables) | `claude --model claude-sonnet-5` |

110| `--name`, `-n` | 为会话设置显示名称，显示在 `/resume` 和终端标题中。您可以使用 `claude --resume <name>` 恢复命名会话。在交互式会话中，如果此机器上的另一个活跃会话已使用该名称，Claude Code 会应用 [它的变体](/docs/zh-CN/sessions#name-your-sessions)。<br /><br />[`/rename`](/docs/zh-CN/commands) 在会话中更改名称，也会在提示栏中显示 | `claude -n "my-feature-work"` |110| `--name`, `-n` | 为会话设置显示名称，显示在 `/resume` 和终端标题中。您可以使用 `claude --resume <name>` 恢复命名会话。在交互式会话中，如果此机器上的另一个实时会话已使用该名称，Claude Code 会应用[其变体](/docs/zh-CN/sessions#name-your-sessions)。<br /><br />[`/rename`](/docs/zh-CN/commands) 在会话中期更改名称，也在提示栏上显示它 | `claude -n "my-feature-work"` |

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

114| `--permission-mode` | 以指定的 [权限模式](/docs/zh-CN/permission-modes) 开始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 或 `manual` 作为 `default` 的别名。`manual` 别名选择 UI 标记为"手动"的权限模式，需要 Claude Code v2.1.200 或更高版本；`claude --help` 用它代替 `default` 列出它，两个值都有效。覆盖设置文件中的 `defaultMode`。没有此标志或 `--dangerously-skip-permissions`，新会话以 [会话启动的权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in) 中描述的权限模式启动。对于 `-p`，当未配置任何内容时为 `default` | `claude --permission-mode plan` |114| `--permission-mode` | 在指定的[权限模式](/docs/zh-CN/permission-modes)中开始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 或 `manual` 作为 `default` 的别名。`manual` 别名选择 UI 标记为 Manual 的权限模式，需要 Claude Code v2.1.200 或更高版本；`claude --help` 列出它代替 `default`，两个值都有效。覆盖设置文件中的 `defaultMode`。没有此标志或 `--dangerously-skip-permissions`，新会话在[会话启动的权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)中描述的权限模式中启动。对于 `-p`，当没有配置任何内容时为 `default` | `claude --permission-mode plan` |

115| `--permission-prompt-tool` | 指定 MCP 工具以在非交互模式下处理权限提示。Claude Code 等待该工具的 MCP 服务器连接后再运行第一轮，最多等待 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 启动超时 30 秒。<br /><br />提示工具无法批准标记为 [需要用户交互](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具：Claude Code 将其中一个的 `allow` 结果转换为拒绝。此限制需要 Claude Code v2.1.199 或更高版本 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |115| `--permission-prompt-tool` | 指定 MCP 工具以在非交互模式下处理权限提示。Claude Code 在运行第一个转之前等待该工具的 MCP 服务器连接，最多 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 启动超时，默认 30 秒。<br /><br />提示工具无法批准标记为[需要用户交互](/docs/zh-CN/mcp#require-approval-for-a-specific-tool)的 MCP 工具：Claude Code 将其 `allow` 结果转换为拒绝。此限制需要 Claude Code v2.1.199 或更高版本 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

116| `--permission-prompts` | 在打印模式下设置谁回答权限提示。使用默认的 `host`，Claude Code 将它们发送到 Agent SDK 主机或 `--permission-prompt-tool` 工具。当没有人可以回答时传递 `none`，Claude Code 改为拒绝它们。请参阅 [在无人值守运行中关闭权限提示](/docs/zh-CN/headless#turn-off-permission-prompts-in-unattended-runs)。需要 Claude Code v2.1.259 或更高版本 | `claude -p --permission-prompts none "query"` |116| `--permission-prompts` | 在打印模式下设置谁回答权限提示。使用默认 `host`，Claude Code 将它们发送到 Agent SDK 主机或 `--permission-prompt-tool` 工具。当没有人可以回答时传递 `none`，Claude Code 改为拒绝它们。请参阅[在无人值守运行中关闭权限提示](/docs/zh-CN/headless#turn-off-permission-prompts-in-unattended-runs)。需要 Claude Code v2.1.259 或更高版本 | `claude -p --permission-prompts none "query"` |

117| `--plugin-dir` | 从目录或 `.zip` 存档加载插件，或从 [插件文件夹](/docs/zh-CN/plugins#test-your-plugins-locally) 加载多个，仅用于此会话。每个标志采用一个路径。重复该标志以获取多个路径：`--plugin-dir A --plugin-dir B.zip`。传递插件文件夹需要 Claude Code v2.1.265 或更高版本 | `claude --plugin-dir ./my-plugin` |117| `--plugin-dir` | 从目录或 `.zip` 存档加载 plugin，或从[plugins 文件夹](/docs/zh-CN/plugins#test-your-plugins-locally)加载多个，仅用于此会话。每个标志采用一个路径。重复标志以获取更多路径：`--plugin-dir A --plugin-dir B.zip`。传递 plugins 文件夹需要 Claude Code v2.1.265 或更高版本 | `claude --plugin-dir ./my-plugin` |

120| `--prompt-suggestions` | 在生成预测下一个用户提示的每轮后发出 `prompt_suggestion` 消息；非常短的对话可能不会产生任何。需要 `--print`、`--output-format stream-json` 和 `--verbose`。请参阅 [提示建议](/docs/zh-CN/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |120| `--prompt-suggestions` | 在生成提示建议的每个转之后发出 `prompt_suggestion` 消息，其中包含预测的下一个用户提示；非常短的对话可能不会产生任何。需要 `--print`、`--output-format stream-json` 和 `--verbose`。请参阅[提示建议](/docs/zh-CN/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |

123| `--remote-control`, `--rc` | 启动启用了 [Remote Control](/docs/zh-CN/remote-control#start-a-remote-control-session) 的交互式会话，以便您也可以从 claude.ai 或 Claude 应用控制它。可选地为会话传递名称 | `claude --remote-control "My Project"` |123| `--remote-control`, `--rc` | 启动启用[远程控制](/docs/zh-CN/remote-control#start-a-remote-control-session)的交互式会话，以便您也可以从 claude.ai 或 Claude 应用控制它。可选地为会话传递名称 | `claude --remote-control "My Project"` |

124| `--remote-control-session-name-prefix <prefix>` | 当未设置显式名称时，[Remote Control](/docs/zh-CN/remote-control) 自动生成会话名称的前缀。默认为您的机器的主机名，生成名称如 `myhost-graceful-unicorn`。设置 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以获得相同效果 | `claude remote-control --remote-control-session-name-prefix dev-box` |124| `--remote-control-session-name-prefix <prefix>` | 当未设置显式名称时，[远程控制](/docs/zh-CN/remote-control)自动生成会话名称的前缀。默认为您的机器主机名，生成名称如 `myhost-graceful-unicorn`。设置 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以获得相同效果 | `claude remote-control --remote-control-session-name-prefix dev-box` |

125| `--replay-user-messages` | 从 stdin 重新发出用户消息到 stdout 以进行确认。需要 `--input-format stream-json` 和 `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |125| `--replay-user-messages` | 从 stdin 重新发出用户消息回到 stdout 以进行确认。需要 `--input-format stream-json` 和 `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |

126| `--restricted` | 以受限模式启动。当评估工具在共享机器上驱动 `claude` 且 Claude Code 不得运行命令或读取该机器的用户和项目设置时使用。Claude Code 删除运行命令或代码的内置工具和 WebFetch，除非您在 `--tools` 中单独命名它们，而不是通过 `default` 预设。它还将内置文件工具限制在 [工作目录](/docs/zh-CN/permissions#working-directories)，仅加载 [托管设置](/docs/zh-CN/managed-settings) 和 `--settings`，拒绝 [`bypassPermissions`](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)，并 [拒绝从受限会话创建云会话](/docs/zh-CN/errors#cloud-sessions-cannot-be-created-from-a-restricted-session)。需要 Claude Code v2.1.248 或更高版本 | `claude --restricted -p "query"` |126| `--restricted` | 在受限模式下启动。当评估工具在共享机器上驱动 `claude` 且 Claude Code 不得运行命令或读取该机器的用户和项目设置时使用。Claude Code 删除运行命令或代码的内置工具和 WebFetch，除非您在 `--tools` 中单独命名它们，而不是通过 `default` 预设。它还将内置文件工具限制在[工作目录](/docs/zh-CN/permissions#working-directories)，仅加载[托管设置](/docs/zh-CN/managed-settings)和 `--settings`，拒绝 [`bypassPermissions`](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)，并[拒绝从受限会话创建云会话](/docs/zh-CN/errors#cloud-sessions-cannot-be-created-from-a-restricted-session)。需要 Claude Code v2.1.248 或更高版本 | `claude --restricted -p "query"` |

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、状态行和文件建议命令；托管插件、托管 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` |

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 配置。请参阅 [使用 managed-mcp.json 的独占控制](/docs/zh-CN/managed-mcp#exclusive-control-with-managed-mcp-json) 了解标志在托管 MCP 文件下的作用 | `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` |

135| `--system-prompt-snapshot` | 传递 `off` 以在每个请求上重建系统提示，而不是重用 [在对话的第一个请求上记录的](#system-prompt-flags-in-resumed-conversations) 提示，例如在您跨 `--continue` 运行迭代 `--append-system-prompt` 文本时。需要 Claude Code v2.1.257 或更高版本 | `claude --system-prompt-snapshot off` |135| `--system-prompt-snapshot` | 传递 `off` 以在每个请求上重建系统提示，而不是重用在对话的第一个请求上[记录的提示](#system-prompt-flags-in-resumed-conversations)，例如在跨 `--continue` 运行迭代其措辞时。需要 Claude Code v2.1.257 或更高版本 | `claude --system-prompt-snapshot off` |

137| `--teammate-mode` | 设置 [agent team](/docs/zh-CN/agent-teams) 队友的显示方式：`in-process`（默认）、`auto`、`tmux` 或 `iterm2`（在 v2.1.186 中添加）。覆盖此会话的 [`teammateMode`](/docs/zh-CN/settings-reference#teammatemode) 设置。请参阅 [选择显示模式](/docs/zh-CN/agent-teams#choose-a-display-mode) | `claude --teammate-mode auto` |137| `--teammate-mode` | 设置[代理团队](/docs/zh-CN/agent-teams)队友的显示方式：`in-process`（默认）、`auto`、`tmux` 或 `iterm2`（在 v2.1.186 中添加）。覆盖此会话的 [`teammateMode`](/docs/zh-CN/settings-reference#teammatemode) 设置。请参阅[选择显示模式](/docs/zh-CN/agent-teams#choose-a-display-mode) | `claude --teammate-mode auto` |

139| `--tools` | 限制 Claude 可以使用的内置工具。使用 `""` 禁用所有，`"default"` 表示默认集合，或工具名称如 `"Bash,Edit,Read"`。在 macOS、Linux 和 WSL 上，默认集合排除 `Glob` 和 `Grep`，如 [Glob 工具行为](/docs/zh-CN/tools-reference#glob-tool-behavior) 中所述。如果您在此处命名 [任务跟踪工具](/docs/zh-CN/tools-reference#task-tool-availability) 之一，Claude Code 也会选择加入。标志不影响 MCP 工具；要拒绝这些工具，请改用 `--disallowedTools "mcp__*"`。省略 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 的列表不会删除它；`""` 仅在没有 MCP 工具保持时删除它 | `claude --tools "Bash,Edit,Read"` |139| `--tools` | 限制 Claude 可以使用的内置工具。使用 `""` 禁用所有，`"default"` 用于默认集，或工具名称如 `"Bash,Edit,Read"`。在 macOS、Linux 和 WSL 上，默认集省略 `Glob` 和 `Grep`，如[Glob 工具行为](/docs/zh-CN/tools-reference#glob-tool-behavior)下所述。如果您在此处命名[任务跟踪工具](/docs/zh-CN/tools-reference#task-tool-availability)之一，Claude Code 也会选择加入。标志不影响 MCP 工具；要拒绝这些工具，请使用 `--disallowedTools "mcp__*"`。省略 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 的列表不会删除它；`""` 仅在没有 MCP 工具保持时删除它 | `claude --tools "Bash,Edit,Read"` |

142| `--worktree`, `-w` | 在隔离的 [git worktree](/docs/zh-CN/worktrees) 中启动 Claude，位于 `<repo>/.claude/worktrees/<name>`。如果未给出名称，则自动生成一个。传递 `#<number>`、GitHub 拉取请求 URL 或 GitLab 合并请求 URL 以 [从 `origin` 获取该 PR 或 MR 并从其分支 worktree](/docs/zh-CN/worktrees#branch-from-a-pull-request)。从 GitLab 合并请求分支需要 Claude Code v2.1.233 或更高版本 | `claude -w feature-auth` |142| `--worktree`, `-w` | 在隔离的 [git worktree](/docs/zh-CN/worktrees) 中启动 Claude，位于 `<repo>/.claude/worktrees/<name>`。如果您不提供名称，Claude Code 会生成一个。传递 `#<number>`、GitHub 拉取请求 URL 或 GitLab 合并请求 URL 以[从 `origin` 获取该 PR 或 MR 并从其分支 worktree](/docs/zh-CN/worktrees#branch-from-a-pull-request)。从 GitLab 合并请求分支需要 Claude Code v2.1.233 或更高版本 | `claude -w feature-auth` |

143 143

144<h3 id="system-prompt-flags">144<h3 id="system-prompt-flags">

145 系统提示标志145 系统提示标志

146</h3>146</h3>

147 147

148Claude Code 提供五个标志用于自定义系统提示。四个设置其文本，使用 `--system-prompt-snapshot` 您可以控制对话是否保留它启动时的文本。所有五个都在交互和非交互模式下工作。148Claude Code 提供五个标志用于自定义系统提示。四个设置其文本，使用 `--system-prompt-snapshot` 您可以控制对话是否保持它启动时的文本。所有五个都在交互和非交互模式中工作。

149 149

150| 标志 | 行为 | 示例 |150| 标志 | 行为 | 示例 |

151| :---------------------------- | :------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- |151| :---------------------------- | :-------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------- |

156| `--system-prompt-snapshot` | 使用 `off`，在每个请求上重建提示。使用 `on`（默认），在[记录适用](#system-prompt-flags-in-resumed-conversations)的情况下重用已记录的提示 | `claude --append-system-prompt "Draft rules" --system-prompt-snapshot off` |156| `--system-prompt-snapshot` | 使用 `off`，在每个请求上重建提示。使用 `on`（默认），重用[记录应用的](#system-prompt-flags-in-resumed-conversations)记录的提示 | `claude --append-system-prompt "Draft rules" --system-prompt-snapshot off` |

157 157

158`--system-prompt` 和 `--system-prompt-file` 互斥。附加标志可以与任一替换标志组合。158`--system-prompt` 和 `--system-prompt-file` 互斥。附加标志可以与任一替换标志组合。

159 159

160根据 Claude Code 的默认身份是否仍然适合您的任务来选择。当 Claude 应该保持编码助手身份同时遵循您的额外规则时，使用附加标志：每次调用的指令、输出格式或 `-p` 脚本的域上下文。附加保留默认工具指导、安全指令和编码约定，因此您只需提供不同的部分。当表面、身份或权限模型与 Claude Code 的不同时，使用替换标志，例如管道中没有人监视的非编码代理。替换会删除整个默认提示，包括工具指导和安全指令，因此您需要对任务仍然需要的任何内容负责。160根据 Claude Code 的默认身份是否仍适合您的任务进行选择。当 Claude 应保持编码助手同时遵循您的额外规则时使用附加标志：每次调用指令、输出格式或 `-p` 脚本的域上下文。附加保留默认工具指导、安全指令和编码约定，因此您只需提供不同的内容。当表面、身份或权限模型与 Claude Code 的不同时使用替换标志，例如管道中没有人监视的非编码代理。替换删除整个默认提示，包括工具指导和安全指令，因此您对任务仍然需要的任何内容负责。

161 161

162对于可以在项目中切换和共享的持久化角色，请使用 [输出样式](/docs/zh-CN/output-styles)。对于 Claude 应该始终遵循的项目约定，请使用 [CLAUDE.md](/docs/zh-CN/memory)。[Agent SDK 系统提示指南](/docs/zh-CN/agent-sdk/modifying-system-prompts#decide-on-a-starting-point) 更深入地涵盖了相同的决策。162对于您可以在项目之间切换和共享的持久角色，请使用[输出样式](/docs/zh-CN/output-styles)。对于 Claude 应始终遵循的项目约定，请使用 [CLAUDE.md](/docs/zh-CN/memory)。[Agent SDK 关于系统提示的指南](/docs/zh-CN/agent-sdk/modifying-system-prompts#decide-on-a-starting-point)更深入地涵盖了相同的决定。

163 163

164<h4 id="system-prompt-flags-in-resumed-conversations">164<h4 id="system-prompt-flags-in-resumed-conversations">

165 恢复的对话中的系统提示标志165 恢复对话中的系统提示标志

166</h4>166</h4>

167 167

168默认情况下，Claude Code 在对话的第一个请求上构建系统提示一次，应用任何系统提示标志中的文本，并在会话中记录它。在对话被压缩之前，每个后续请求都使用该记录的提示，包括在您使用 `--resume` 或 `--continue` 返回对话后。如果您在该后续启动时传递不同的系统提示标志文本或无，它在对话被压缩或您启动新对话时生效。168默认情况下，Claude Code 在对话的第一个请求上构建系统提示一次，应用任何系统提示标志中的文本，并在会话中记录它。在对话被压缩之前，每个后续请求都使用该记录的提示，包括在您使用 `--resume` 或 `--continue` 返回对话后。如果您在该后续启动时传递不同的系统提示标志文本或无，它在对话被压缩或您启动新对话时生效。

169 169

170如果您通过传递 `--bare` 或设置 `CLAUDE_CODE_SIMPLE=1` 在 [bare mode](/docs/zh-CN/headless#start-faster-with-bare-mode) 中启动 Claude Code，记录保持关闭，除非您传递 `--system-prompt-snapshot on`。在 v2.1.268 之前，不 [获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) 的会话，包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的会话，在每个请求上重建提示，`--system-prompt-snapshot` 无效。170在[云会话](/docs/zh-CN/cloud-environments)之外，如果您通过传递 `--bare` 或设置 `CLAUDE_CODE_SIMPLE=1` 在[裸模式](/docs/zh-CN/headless#start-faster-with-bare-mode)中启动 Claude Code，记录保持关闭，除非您传递 `--system-prompt-snapshot on`。在 v2.1.268 之前，不[获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话，包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的会话，在每个请求上重建提示，`--system-prompt-snapshot` 无效。

171 171

172要改为在每个请求上重建提示，例如在您跨 `--continue` 运行迭代其措辞时，传递 `--system-prompt-snapshot off`。在 v2.1.265 之前，传递任何系统提示标志也会关闭记录，除非您传递 `--system-prompt-snapshot on`。172要在每个请求上重建提示，例如在跨 `--continue` 运行迭代其措辞时，传递 `--system-prompt-snapshot off`。在 v2.1.265 之前，传递任何系统提示标志也关闭记录，除非您传递 `--system-prompt-snapshot on`。

173 173

174<h2 id="see-also">174<h2 id="see-also">

175 另请参阅175 另请参阅

cloud-environments.md +17 −16

Details

7> 为 Claude Code 云会话配置云环境：网络访问级别、环境变量、设置脚本和环境缓存。7> 为 Claude Code 云会话配置云环境：网络访问级别、环境变量、设置脚本和环境缓存。

8 8

9<Note>9<Note>

10 云环境需要 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web)，该功能目前处于研究预览阶段，适用于 Pro、Max 和 Team 用户，以及具有 [premium seats 或 Chat + Claude Code seats](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan) 的 Enterprise 用户。10 云环境适用于[云会话](/docs/zh-CN/claude-code-on-the-web)，该功能目前处于研究预览阶段，适用于 Pro、Max 和 Team 用户，以及具有[高级席位或 Chat + Claude Code 席位](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan)的 Enterprise 用户。

11</Note>11</Note>

12 12

13每个[云会话](/docs/zh-CN/claude-code-on-the-web)都在云环境中运行。您可以配置环境以允许或拒绝[网络访问](#access-levels)、为会话[设置环境变量](#set-environment-variables)、在 Pro 和 Max 计划上存储会话使用的[API 凭证](#add-api-credentials)而不会看到它们，以及在 Claude 开始工作前运行[设置脚本](#setup-scripts)。13每个[云会话](/docs/zh-CN/claude-code-on-the-web)都在云环境中运行。您可以配置环境以允许或拒绝[网络访问](#access-levels)、为会话[设置环境变量](#set-environment-variables)、在 Pro 和 Max 计划上存储会话使用的[API 凭证](#add-api-credentials)而不会看到它们，以及在 Claude 开始工作前运行[设置脚本](#setup-scripts)。

14 14

15相同的环境适用于您启动云会话的任何地方：[Claude Code on the web](/docs/zh-CN/claude-code-on-the-web)、终端搭配 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-web)、[Claude Tag](https://claude.com/docs/claude-tag/overview)、[例程](/docs/zh-CN/routines)、[Claude 移动应用](/docs/zh-CN/mobile)和 [Desktop 应用](/docs/zh-CN/desktop)。这些界面中的每一个也可以路由到[自托管环境](/docs/zh-CN/self-hosted-environments)。[可用性和限制](/docs/zh-CN/self-hosted-environments#availability-and-limitations)涵盖了当 Claude Tag 会话在其中运行时 Claude 还不能使用的内容。15相同的环境适用于您启动云会话的任何地方：[Desktop 应用](/docs/zh-CN/desktop)、[Claude 移动应用](/docs/zh-CN/mobile)、浏览器中的 [claude.ai/code](https://claude.ai/code)、终端中搭配 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)、[例程](/docs/zh-CN/routines)和 [Claude Tag](https://claude.com/docs/claude-tag/overview)。这些界面中的每一个也可以路由到[自托管环境](/docs/zh-CN/self-hosted-environments)。[可用性和限制](/docs/zh-CN/self-hosted-environments#availability-and-limitations)涵盖了当 Claude Tag 会话在其中运行时 Claude 还不能使用的内容。

16 16

17<Info>17<Info>

18 [Remote Control](/docs/zh-CN/remote-control) 会话将网页和移动界面连接到您自己机器上的会话，该会话使用您机器的网络和文件，而不是云环境。Claude Tag 频道会话仅使用组织级别的环境，即[共享环境](#organization-shared-environments)或[自托管环境](/docs/zh-CN/self-hosted-environments)。18 [Remote Control](/docs/zh-CN/remote-control) 会话将网页和移动界面连接到您自己机器上的会话，该会话使用您机器的网络和文件，而不是云环境。Claude Tag 频道会话仅使用组织级别的环境，即[共享环境](#organization-shared-environments)或[自托管环境](/docs/zh-CN/self-hosted-environments)。

35 35

36只有 **Default** 可用时，每个会话都在其中运行。当您有多个环境时，会话会按界面选择一个：36只有 **Default** 可用时，每个会话都在其中运行。当您有多个环境时，会话会按界面选择一个：

37 37

38* 在网页、Desktop 应用和移动应用上，会话使用[选择器](#configure-your-environment)中显示的环境。当您尚未选择时，所有者设置的[组织默认值](#organization-shared-environments)会填入选择。38* 在网页、Desktop 应用和移动应用上，会话使用[选择器](#configure-your-environment)中显示的环境。当您尚未选择时，所有者设置的[组织默认值](#organization-shared-environments)会填入选择。线程在[项目](/docs/zh-CN/claude-projects#project-settings-reference)中使用项目设置中设置的环境。

39* 从 CLI，Claude Code 使用您的 [`/remote-env` 选择](#select-an-environment-from-the-cli)，或在您的列表中有一个 Anthropic 托管环境时回退到该环境，否则回退到您列表中第一个不是桥接环境的环境，即 [Remote Control](/docs/zh-CN/remote-control) 注册的条目，用于代表您自己的机器而不是云环境。对于[自托管环境](/docs/zh-CN/self-hosted-environments)，在[分派会话](/docs/zh-CN/self-hosted-environments-testing#run-the-test-loop)时使用其 `ccpool_` ID 传递 `--environment <environment-id>` 会覆盖该调用的 `/remote-env` 选择和回退。Claude Code 拒绝传递给该标志的 Anthropic 托管 `env_` ID，因此请使用 `/remote-env` 来定位这些。该标志需要 Claude Code v2.1.224 或更高版本。39* 从 CLI，Claude Code 使用您的 [`/remote-env` 选择](#select-an-environment-from-the-cli)，或在您的列表中有一个 Anthropic 托管环境时回退到该环境，否则回退到您列表中第一个不是桥接环境的环境，即 [Remote Control](/docs/zh-CN/remote-control) 注册的条目，用于代表您自己的机器而不是云环境。对于[自托管环境](/docs/zh-CN/self-hosted-environments)，在[分派会话](/docs/zh-CN/self-hosted-environments-testing#run-the-test-loop)时使用其 `ccpool_` ID 传递 `--environment <environment-id>` 会覆盖该调用的 `/remote-env` 选择和回退。Claude Code 拒绝传递给该标志的 Anthropic 托管 `env_` ID，因此请使用 `/remote-env` 来定位这些。该标志需要 Claude Code v2.1.224 或更高版本。

40 40

41当默认环境不够用时，请配置环境：当 Claude 需要访问[默认允许列表](#default-allowed-domains)之外的域、需要为其会话设置环境变量，或需要在开始工作前安装依赖项时。41当默认环境不够用时，请配置环境：当 Claude 需要访问[默认允许列表](#default-allowed-domains)之外的域、需要为其会话设置环境变量，或需要在开始工作前安装依赖项时。

80 80

81每个会话在启动时将环境的值复制一次到普通环境变量中，Claude运行的任何命令都可以读取这些变量。因为运行中的会话不会重新读取配置，编辑或添加变量会影响你之后启动的会话；已经运行的会话保持它们启动时的值。81每个会话在启动时将环境的值复制一次到普通环境变量中，Claude运行的任何命令都可以读取这些变量。因为运行中的会话不会重新读取配置，编辑或添加变量会影响你之后启动的会话；已经运行的会话保持它们启动时的值。

82 82

83Claude Code网页版在启动会话时也会自己设置一些变量。对于[`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/zh-CN/claude-code-on-the-web#manage-context)，Claude Code网页版设置的值会覆盖你在这里添加的值，所以在这里添加该键没有效果。83云会话在启动时也会自己设置一些变量。对于[`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/zh-CN/claude-code-on-the-web#manage-context)，会话设置的值会覆盖你在这里添加的值，所以在这里添加该键没有效果。

84 84

85使用该环境的任何人都可以读取这些值。在Pro和Max计划上，对于代理可以附加到请求的键，请改用[API凭证](#add-api-credentials)。[从不获得凭证的请求](#requests-that-never-get-the-credential)在那里列出。85使用该环境的任何人都可以读取这些值。在Pro和Max计划上，对于代理可以附加到请求的键，请改用[API凭证](#add-api-credentials)。[从不获得凭证的请求](#requests-that-never-get-the-credential)在那里列出。

86 86

154 从CLI选择环境154 从CLI选择环境

155</h3>155</h3>

156 156

157在你的终端中运行`/remote-env`来为你从CLI创建的云会话（例如[`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-web)）选择默认环境。该命令打开你现有环境的选择器并将你的选择保存到你的[用户设置](/docs/zh-CN/settings#where-settings-live)中的`remote.defaultEnvironmentId`键，所以它适用于你机器上的每个项目，直到你更改它，除非在更高优先级的[设置层](/docs/zh-CN/settings#settings-precedence)（例如仓库的项目设置）上设置了相同的键。157在你的终端中运行`/remote-env`来为你从CLI创建的云会话（例如[`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)）选择默认环境。该命令打开你现有环境的选择器并将你的选择保存到你的[用户设置](/docs/zh-CN/settings#where-settings-live)中的`remote.defaultEnvironmentId`键，所以它适用于你机器上的每个项目，直到你更改它，除非在更高优先级的[设置层](/docs/zh-CN/settings#settings-precedence)（例如仓库的项目设置）上设置了相同的键。

158 158

159[自托管环境](/docs/zh-CN/self-hosted-environments)ID的形式为`ccpool_...`，遵循更严格的源规则。查看[`remote.defaultEnvironmentId`](/docs/zh-CN/settings-reference#remote-defaultenvironmentid)了解Claude Code遵守它的设置层。159[自托管环境](/docs/zh-CN/self-hosted-environments)ID的形式为`ccpool_...`，遵循更严格的源规则。查看[`remote.defaultEnvironmentId`](/docs/zh-CN/settings-reference#remote-defaultenvironmentid)了解Claude Code遵守它的设置层。

160 160

201要更改环境的网络访问，[打开它进行编辑](#configure-your-environment)并在对话框中使用 **Network access** 选择器。打开选择器的云图标出现在[Default 环境](#the-default-environment)下列出的应用界面上，以及[例程编辑器](/docs/zh-CN/routines#environments-and-network-access)中；个人环境在您的 claude.ai 账户设置中没有单独的页面。201要更改环境的网络访问，[打开它进行编辑](#configure-your-environment)并在对话框中使用 **Network access** 选择器。打开选择器的云图标出现在[Default 环境](#the-default-environment)下列出的应用界面上，以及[例程编辑器](/docs/zh-CN/routines#environments-and-network-access)中；个人环境在您的 claude.ai 账户设置中没有单独的页面。

202 202

203<Note>203<Note>

204 您在会话或例程上启用的 MCP 连接器无需将其主机添加到 **Allowed domains**，因为连接器流量通过 Anthropic 的服务器而不是会话的网络传输。您可以按会话或按例程配置连接器；移除任何您不需要的连接器，以限制 Claude 可以访问的工具。这依赖于[安全性和隔离](/docs/zh-CN/claude-code-on-the-web#security-and-isolation)下提到的同一条通往 Anthropic 的通道。204 您在会话或例程上启用的 MCP 连接器无需将其主机添加到 **Allowed domains**，因为连接器流量通过 Anthropic 的服务器而不是会话的网络传输。这依赖于[安全性和隔离](/docs/zh-CN/claude-code-on-the-web#security-and-isolation)下提到的同一条通往 Anthropic 的通道。关闭任何您不需要的连接器，以限制 Claude 可以访问的工具。

205</Note>205</Note>

206 206

207<h3 id="access-levels">207<h3 id="access-levels">

243* **此环境中的会话打开另一个组织的公开工件**：Claude Code 直接从主机获取这些工件，因此将其添加到此列表。243* **此环境中的会话打开另一个组织的公开工件**：Claude Code 直接从主机获取这些工件，因此将其添加到此列表。

244* **您正在配置本地 CLI 或自托管运行器**：在该允许列表中保留主机。请参阅[网络访问要求](/docs/zh-CN/network-config#network-access-requirements)和自托管[网络要求](/docs/zh-CN/self-hosted-environments-deploy#network-requirements)。244* **您正在配置本地 CLI 或自托管运行器**：在该允许列表中保留主机。请参阅[网络访问要求](/docs/zh-CN/network-config#network-access-requirements)和自托管[网络要求](/docs/zh-CN/self-hosted-environments-deploy#network-requirements)。

245 245

246每个环境都有自己的允许域列表；没有组织级别的允许列表可供管理员推送到每个成员的环境。[服务器管理的设置](/docs/zh-CN/server-managed-settings)在云会话内仍然适用，但其中没有任何设置会将域添加到环境的网络允许列表。246每个环境都有自己的允许域列表；没有组织级别的允许列表可供管理员推送到每个成员的环境。[服务器管理的设置](/docs/zh-CN/server-managed-settings)在云会话内仍然适用，但其中没有任何设置会将域添加到环境的网络允许列表。要为团队提供一个标准列表，Owner 可以创建一个具有 **Custom** 网络访问和该列表的[组织共享环境](#organization-shared-environments)。

247 247

248<h3 id="github-proxy">248<h3 id="github-proxy">

249 GitHub 代理249 GitHub 代理

289| | 在云会话中可用 | 原因 |289| | 在云会话中可用 | 原因 |

290| :-------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |290| :-------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

291| 您的存储库的 `CLAUDE.md` | 是 | 克隆的一部分 |291| 您的存储库的 `CLAUDE.md` | 是 | 克隆的一部分 |

294| 您的存储库的 `.claude/rules/` | 是 | 克隆的一部分 |294| 您的存储库的 `.claude/rules/` | 是 | 克隆的一部分 |

295| 您的存储库的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 克隆的一部分 |295| 您的存储库的 `.claude/skills/`、`.claude/agents/`、`.claude/commands/` | 是 | 克隆的一部分 |

296| 在 `.claude/settings.json` 中声明的 Plugins | 是 | 在会话启动时从您声明的 [marketplace](/docs/zh-CN/plugin-marketplaces) 安装。需要网络访问以到达 marketplace 来源 |296| 在 `.claude/settings.json` 中声明的 Plugins | 是 | 在会话启动时从您声明的 [marketplace](/docs/zh-CN/plugin-marketplaces) 安装。需要网络访问以到达 marketplace 来源 |

298| 您的用户 `~/.claude/CLAUDE.md` | 否 | 位于您的机器上，不在存储库中 |298| 您的用户 `~/.claude/CLAUDE.md` | 否 | 位于您的机器上，不在存储库中 |

299| 您的用户 `~/.claude/skills/`、`~/.claude/agents/`、`~/.claude/commands/` | 否 | 位于您的机器上，不在存储库中。请改为将它们提交到存储库的 `.claude/` 目录。云会话会自动加载您在 claude.ai 上启用的技能 |299| 您的用户 `~/.claude/skills/`、`~/.claude/agents/`、`~/.claude/commands/` | 否 | 位于您的机器上，不在存储库中。请改为将它们提交到存储库的 `.claude/` 目录。云会话会自动加载您在 claude.ai 上启用的技能 |

300| 仅在您的用户设置中启用的 Plugins | 否 | 用户范围的 `enabledPlugins` 位于 `~/.claude/settings.json`。请改为在存储库的 `.claude/settings.json` 中声明它们，或在您的 claude.ai 账户中启用它们，以便 Claude Code 将它们作为[同步 Plugins](/docs/zh-CN/plugins-reference#synced-plugins)加载 |300| 仅在您的用户设置中启用的 Plugins | 否 | 用户范围的 `enabledPlugins` 位于 `~/.claude/settings.json`。请改为在存储库的 `.claude/settings.json` 中声明它们，或在您的 claude.ai 账户中启用它们，以便 Claude Code 将它们作为[同步 Plugins](/docs/zh-CN/plugins-reference#synced-plugins)加载 |

301| 您使用 `claude mcp add` 在默认本地范围或用户范围添加的 MCP 服务器 | 否 | 这些写入您机器上的 `~/.claude.json`，而不是存储库。请使用 `claude mcp add --scope project` 添加服务器，它会写入存储库的 [`.mcp.json`](/docs/zh-CN/mcp#project-scope)，并提交该文件 |301| 您使用 `claude mcp add` 在默认本地范围或用户范围添加的 MCP 服务器 | 否 | 这些写入您机器上的 `~/.claude.json`，而不是存储库。请使用 `claude mcp add --scope project` 添加服务器，它会写入存储库的 [`.mcp.json`](/docs/zh-CN/mcp#project-scope)，并提交该文件。具有一个存储库的会话会加载它 |

302| 您的存储库的 `.claude/settings.json` `env` 块中的传输变量，例如 `NODE_EXTRA_CA_CERTS` 和 [mTLS 客户端证书变量](/docs/zh-CN/network-config#mtls-authentication) | 否 | 托管环境管理会话的 API 连接，因此 Claude Code 忽略这些键，并在会话的调试日志中记录每个被忽略的键 |302| 您的存储库的 `.claude/settings.json` `env` 块中的传输变量，例如 `NODE_EXTRA_CA_CERTS` 和 [mTLS 客户端证书变量](/docs/zh-CN/network-config#mtls-authentication) | 否 | 托管环境管理会话的 API 连接，因此 Claude Code 忽略这些键，并在会话的调试日志中记录每个被忽略的键 |

303| Claude 调用的服务的 API 密钥和令牌 | 在 Pro 和 Max 计划中，作为 [API 凭证](#add-api-credentials) | 您在环境中添加一次密钥，代理会将其附加到您列出的主机的请求。代理[无法附加](#requests-that-never-get-the-credential)的密钥，或 Team 或 Enterprise 计划中的任何密钥，保留在环境变量中 |303| Claude 调用的服务的 API 密钥和令牌 | 在 Pro 和 Max 计划中，作为 [API 凭证](#add-api-credentials) | 您在环境中添加一次密钥，代理会将其附加到您列出的主机的请求。代理[无法附加](#requests-that-never-get-the-credential)的密钥，或 Team 或 Enterprise 计划中的任何密钥，保留在环境变量中 |

304| 交互式身份验证，例如 AWS SSO | 否 | 不支持。SSO 需要基于浏览器的登录，无法在云会话中执行 |304| 交互式身份验证，例如 AWS SSO | 否 | 不支持。SSO 需要基于浏览器的登录，无法在云会话中执行 |

341 341

342云会话包括内置 GitHub 工具，让 Claude 无需任何设置即可读取问题、列出拉取请求、获取差异和发布评论。这些工具通过 [GitHub 代理](#github-proxy)，使用您在 [GitHub 身份验证选项](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)下设置的任何方法进行身份验证，因此您的令牌永远不会进入容器。342云会话包括内置 GitHub 工具，让 Claude 无需任何设置即可读取问题、列出拉取请求、获取差异和发布评论。这些工具通过 [GitHub 代理](#github-proxy)，使用您在 [GitHub 身份验证选项](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)下设置的任何方法进行身份验证，因此您的令牌永远不会进入容器。

343 343

344您可以在[环境配置](#set-environment-variables)中自己设置 `GH_TOKEN` 或 `GITHUB_TOKEN`，或者两者都不设置，让 [GitHub 代理](#github-proxy)为您进行身份验证：344您可以在[环境设置](#set-environment-variables)中自己设置 `GH_TOKEN` 或 `GITHUB_TOKEN`，或者两者都不设置，让 [GitHub 代理](#github-proxy)为您进行身份验证：

345 345

346* 如果您设置了令牌，它会原封不动地传递到容器中，因此您的脚本和 GitHub 的 [`gh` CLI](https://cli.github.com) 会直接使用它。346* 如果您设置了令牌，它会原封不动地传递到容器中，因此您的脚本和 GitHub 的 [`gh` CLI](https://cli.github.com) 会直接使用它。

347* 如果您都不设置，则由 [GitHub 代理](#github-proxy)为您的会话处理身份验证，这两个变量在 Claude 运行的命令中读取为占位符字符串 `proxy-injected`，代理在出站 GitHub 请求上替换为您的真实凭证。`gh` 无需您自己的令牌即可工作，但直接读取 `GITHUB_TOKEN` 的脚本会得到占位符，而不是可用的令牌。347* 如果您都不设置，则由 [GitHub 代理](#github-proxy)为您的会话处理身份验证，这两个变量在 Claude 运行的命令中读取为占位符字符串 `proxy-injected`，代理在出站 GitHub 请求上替换为您的真实凭证。`gh` 无需您自己的令牌即可工作，但直接读取 `GITHUB_TOKEN` 的脚本会得到占位符，而不是可用的令牌。

358 358

359每个云会话在 claude.ai 上都有一个转录 URL，会话可以从 `CLAUDE_CODE_REMOTE_SESSION_ID` 环境变量读取自己的 ID。使用它在 PR 正文、提交消息、Slack 帖子或生成的报告中放置可追溯的链接，以便审阅者可以打开生成它们的运行。359每个云会话在 claude.ai 上都有一个转录 URL，会话可以从 `CLAUDE_CODE_REMOTE_SESSION_ID` 环境变量读取自己的 ID。使用它在 PR 正文、提交消息、Slack 帖子或生成的报告中放置可追溯的链接，以便审阅者可以打开生成它们的运行。

360 360

361Claude 在云会话中创建的提交包括 `Claude-Session: <url>` git 尾注，PR 正文在单独一行包括会话 URL。这需要 v2.1.179 或更新版本。要省略尾注和 PR 正文链接，请将 [`attribution.sessionUrl`](/docs/zh-CN/settings-reference#attribution-sessionurl) 设置为 `false`。此设置需要 v2.1.182 或更新版本。361Claude 在云会话中创建的提交包括 `Claude-Session: <url>` git 尾注，PR 正文在单独一行包括会话 URL。要省略尾注和 PR 正文链接，请将 [`attribution.sessionUrl`](/docs/zh-CN/settings-reference#attribution-sessionurl) 设置为 `false`。

362 362

363要在提交或 PR 以外的内容中包含会话链接，例如 Claude 发布的 Slack 消息或它编写的报告文件，请让 Claude 运行以下命令并使用其输出。该命令将环境变量值中的 `cse_` 前缀转换为转录 URL 预期的 `session_` 前缀：363要在提交或 PR 以外的内容中包含会话链接，例如 Claude 发布的 Slack 消息或它编写的报告文件，请让 Claude 运行以下命令并使用其输出。该命令将环境变量值中的 `cse_` 前缀转换为转录 URL 预期的 `session_` 前缀：

364 364

422 422

423脚本以 root 身份在 Ubuntu 24.04 上运行，因此 `apt install` 和大多数语言包管理器都能工作。423脚本以 root 身份在 Ubuntu 24.04 上运行，因此 `apt install` 和大多数语言包管理器都能工作。

424 424

425要添加设置脚本，请打开环境配置对话框，并在 **Setup script** 字段中输入您的脚本。425要添加设置脚本，请打开环境设置对话框，并在 **Setup script** 字段中输入您的脚本。

426 426

427此示例安装 [ShellCheck](https://www.shellcheck.net/)，它不是预安装的。427此示例安装 [ShellCheck](https://www.shellcheck.net/)，它不是预安装的。

428 428

524 524

525SessionStart hooks 在云端的行为与本地相同，但有以下注意事项：525SessionStart hooks 在云端的行为与本地相同，但有以下注意事项：

526 526

527* **没有仅云端的范围**：hooks 在本地和云会话中都运行。要跳过本地运行，请检查 `CLAUDE_CODE_REMOTE` 环境变量，如上所示。527* **每个会话一个存储库**：具有多个存储库的会话不会从任何存储库的 `.claude/settings.json` 加载 hooks，因此您在那里定义的 SessionStart hook 不会运行。请改为使用[设置脚本](#setup-scripts)为这些会话安装依赖项。

528* **没有仅云端的范围**：hooks 在本地和云会话中都运行。要跳过本地运行，请检查 `CLAUDE_CODE_REMOTE` 环境变量是否为 `true`，就像[依赖项安装脚本](#install-dependencies-with-a-sessionstart-hook)所做的那样。

528* **需要网络访问**：安装命令需要连接到包注册表。如果您的环境使用 **None** 网络访问，这些 hooks 会失败。**Trusted** 下的[默认允许列表](#default-allowed-domains)涵盖 npm、PyPI、RubyGems 和 crates.io。529* **需要网络访问**：安装命令需要连接到包注册表。如果您的环境使用 **None** 网络访问，这些 hooks 会失败。**Trusted** 下的[默认允许列表](#default-allowed-domains)涵盖 npm、PyPI、RubyGems 和 crates.io。

529* **代理兼容性**：在 Anthropic 托管环境中，所有出站流量都经过[安全代理](#security-proxy)，某些包管理器无法与此代理正确配合工作；Bun 是一个已知的例子。在[自托管环境](/docs/zh-CN/self-hosted-environments-deploy#default-deny-egress)中，出站流量改为经过您自己的网络边界。530* **代理兼容性**：在 Anthropic 托管环境中，所有出站流量都经过[安全代理](#security-proxy)，某些包管理器无法与此代理正确配合工作；Bun 是一个已知的例子。在[自托管环境](/docs/zh-CN/self-hosted-environments-deploy#default-deny-egress)中，出站流量改为经过您自己的网络边界。

530* **增加启动延迟**：hooks 在每次会话启动或恢复时运行，不同于受益于[环境缓存](#environment-caching)的设置脚本。请通过在重新安装之前检查依赖项是否已存在来保持安装脚本快速。531* **增加启动延迟**：hooks 在每次会话启动或恢复时运行，不同于受益于[环境缓存](#environment-caching)的设置脚本。请通过在重新安装之前检查依赖项是否已存在来保持安装脚本快速。

793 相关资源794 相关资源

794</h2>795</h2>

795 796

796* [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web)：启动、管理和共享云会话797* [Cloud sessions reference](/docs/zh-CN/claude-code-on-the-web)：启动、管理和共享云会话

797* [Web quickstart](/docs/zh-CN/web-quickstart)：连接 GitHub 并启动您的第一个云会话798* [Cloud sessions quickstart](/docs/zh-CN/web-quickstart)：连接 GitHub 并启动您的第一个云会话

798* [Claude Tag](https://claude.com/docs/claude-tag/overview)：Claude 从 Slack 启动的会话在相同的环境中运行799* [Claude Tag](https://claude.com/docs/claude-tag/overview)：Claude 从 Slack 启动的会话在相同的环境中运行

799* [Routines](/docs/zh-CN/routines)：计划运行使用相同的环境和网络访问级别800* [Routines](/docs/zh-CN/routines)：计划运行使用相同的环境和网络访问级别

800* [Remote Control](/docs/zh-CN/remote-control)：改为在您自己的机器的网络和文件上运行会话801* [Remote Control](/docs/zh-CN/remote-control)：改为在您自己的机器的网络和文件上运行会话

code-review.md +4 −2

Details

58 58

59回复内联评论不会提示 Claude 响应或更新 PR。要对发现采取行动，请修复代码并推送。如果 PR 订阅了推送触发的审查，下一次运行将在问题修复时解决线程。要请求新审查而不推送，请作为[顶级 PR 评论](#manually-trigger-reviews)注释 `@claude review`。59回复内联评论不会提示 Claude 响应或更新 PR。要对发现采取行动，请修复代码并推送。如果 PR 订阅了推送触发的审查，下一次运行将在问题修复时解决线程。要请求新审查而不推送，请作为[顶级 PR 评论](#manually-trigger-reviews)注释 `@claude review`。

60 60

61要在不更改代码的情况下关闭发现，请解决其线程；回复不会关闭它。

61<h3 id="check-run-output">63<h3 id="check-run-output">

62 检查运行输出64 检查运行输出

63</h3>65</h3>

195 197

196`REVIEW.md` 是位于您的存储库根目录的文件，它为您的存储库定制 Code Review。审查管道中查找和验证发现的代理接收其内容作为您的存储库的审查说明，以及 Code Review 的默认审查指导，排名和报告发现的代理在确定严重程度和编写审查之前咨询它。198`REVIEW.md` 是位于您的存储库根目录的文件，它为您的存储库定制 Code Review。审查管道中查找和验证发现的代理接收其内容作为您的存储库的审查说明，以及 Code Review 的默认审查指导，排名和报告发现的代理在确定严重程度和编写审查之前咨询它。

197 199

198代理按原样读取文件的文本，因此 `REVIEW.md` 是纯说明：[`@` 导入语法](/docs/zh-CN/memory#import-additional-files)不会展开，引用的文件不会随之读取。将您想要强制执行的规则直接放在文件中。200将您想要强制执行的规则直接放在 `REVIEW.md` 中。

199 201

200<h4 id="what-you-can-tune">202<h4 id="what-you-can-tune">

201 您可以调整的内容203 您可以调整的内容

354 </Step>356 </Step>

355</Steps>357</Steps>

356 358

357Claude 在这两个运行中都将发现作为文本报告在回复中，即使主机应用程序请求下面描述的发现列表：359Claude 在这两个运行中都将发现作为文本报告在回复中，即使主机应用程序请求发现列表：

358 360

359* 在终端会话中，其中 `/code-review` 作为[分叉子代理](/docs/zh-CN/skills#run-skills-in-a-subagent)运行审查361* 在终端会话中，其中 `/code-review` 作为[分叉子代理](/docs/zh-CN/skills#run-skills-in-a-subagent)运行审查

360* 在带有文本或 JSON 输出的 `-p` 运行中362* 在带有文本或 JSON 输出的 `-p` 运行中

commands.md +8 −7

Details

59| `/artifacts` | 列出你拥有或与你共享的[工件](/docs/zh-CN/artifacts#find-an-artifact-again)，然后将其附加到会话、在浏览器中打开或复制其链接。在[工件](/docs/zh-CN/artifacts#availability)可用的地方可用。需要 Claude Code v2.1.208 或更高版本；使用 `Enter` 附加需要 v2.1.216 |59| `/artifacts` | 列出你拥有或与你共享的[工件](/docs/zh-CN/artifacts#find-an-artifact-again)，然后将其附加到会话、在浏览器中打开或复制其链接。在[工件](/docs/zh-CN/artifacts#availability)可用的地方可用。需要 Claude Code v2.1.208 或更高版本；使用 `Enter` 附加需要 v2.1.216 |

60| `/auto-mode-setup` | [从你的项目和最近的会话中起草 `autoMode.environment` 条目](/docs/zh-CN/auto-mode-config#generate-environment-entries)，然后审查草稿并将其保存到你的用户设置。需要 Pro、Max 或 Team 计划以及 Claude Code v2.1.228 或更高版本。在原生 Windows 上，需要 v2.1.233 或更高版本 |60| `/auto-mode-setup` | [从你的项目和最近的会话中起草 `autoMode.environment` 条目](/docs/zh-CN/auto-mode-config#generate-environment-entries)，然后审查草稿并将其保存到你的用户设置。需要 Pro、Max 或 Team 计划以及 Claude Code v2.1.228 或更高版本。在原生 Windows 上，需要 v2.1.233 或更高版本 |

61| `/autocompact [auto\|<tokens>]` | 设置自动压缩窗口：在 Claude Code 自动压缩之前上下文窗口有多满。传递一个大小，例如 `500k`，或 `auto` 以返回为你的模型调整的窗口。Claude Code 将该值保存到用户设置并将其应用于当前会话。有关接受的值和覆盖它的内容，请参阅[设置自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window)。没有参数时，打开一个显示当前窗口的对话框。需要 Claude Code v2.1.221 或更高版本 |61| `/autocompact [auto\|<tokens>]` | 设置自动压缩窗口：在 Claude Code 自动压缩之前上下文窗口有多满。传递一个大小，例如 `500k`，或 `auto` 以返回为你的模型调整的窗口。Claude Code 将该值保存到用户设置并将其应用于当前会话。有关接受的值和覆盖它的内容，请参阅[设置自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window)。没有参数时，打开一个显示当前窗口的对话框。需要 Claude Code v2.1.221 或更高版本 |

62| `/autofix-pr [prompt]` | 生成一个 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web#auto-fix-pull-requests) 会话，监视当前分支的 PR 并在 CI 失败或审阅者留下评论时推送修复。使用 `gh pr view` 从你的检出分支检测打开的 PR；要监视不同的 PR，请先检出其分支。默认情况下，云会话被告知修复每个 CI 失败和审阅评论；传递一个提示词以给它不同的指令，例如 `/autofix-pr only fix lint and type errors`。需要 `gh` CLI 和访问 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) |62| `/autofix-pr [prompt]` | 生成一个 [cloud session](/docs/zh-CN/claude-code-on-the-web#auto-fix-pull-requests) 会话，监视当前分支的 PR 并在 CI 失败或审阅者留下评论时推送修复。使用 `gh pr view` 从你的检出分支检测打开的 PR；要监视不同的 PR，请先检出其分支。默认情况下，云会话被告知修复每个 CI 失败和审阅评论；传递一个提示词以给它不同的指令，例如 `/autofix-pr only fix lint and type errors`。需要 `gh` CLI 和访问 [cloud sessions](/docs/zh-CN/claude-code-on-the-web) |

63| `/background [prompt]` | 分离当前会话以作为[后台代理](/docs/zh-CN/agent-view)运行并释放此终端。传递一个提示词以在分离前发送一个更多指令。使用 `claude agents` 监视会话。要将对话复制到新的后台会话中，同时此会话继续运行，请使用 `/fork`。别名：`/bg` |63| `/background [prompt]` | 分离当前会话以作为[后台代理](/docs/zh-CN/agent-view)运行并释放此终端。传递一个提示词以在分离前发送一个更多指令。使用 `claude agents` 监视会话。要将对话复制到新的后台会话中，同时此会话继续运行，请使用 `/fork`。别名：`/bg` |

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

65| `/branch [name]` | 在此点创建当前对话的一个分支，以便你可以尝试不同的方向而不会丢失对话。切换到分支并保留原始分支，你可以使用 `/resume` 返回到它。要运行一个副本作为单独的[后台会话](/docs/zh-CN/agent-view)而不是切换到它，请使用 `/fork`；要将一个侧面任务交给一个[子代理](/docs/zh-CN/sub-agents)，它报告回这个对话，请使用 `/subtask` |65| `/branch [name]` | 在此点创建当前对话的一个分支，以便你可以尝试不同的方向而不会丢失对话。切换到分支并保留原始分支，你可以使用 `/resume` 返回到它。要运行一个副本作为单独的[后台会话](/docs/zh-CN/agent-view)而不是切换到它，请使用 `/fork`；要将一个侧面任务交给一个[子代理](/docs/zh-CN/sub-agents)，它报告回这个对话，请使用 `/subtask` |

72| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [pr#\|branch\|path]` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 审查当前差异，或你传递的 PR 号、分支或路径，以查找正确性错误和清理机会。传递 `--fix` 以应用发现，`--comment` 以在 GitHub PR 或 GitLab 合并请求上发布它们，或 `ultra` 以运行深度[云审查](/docs/zh-CN/ultrareview)。发布到 GitLab 合并请求需要 Claude Code v2.1.257 或更高版本。在 `github.com` PR 目标上使用 `ultra` 时，传递 `--post` 以在启动对话框中预选[将完成的发现发布到 PR](/docs/zh-CN/ultrareview#post-findings-to-the-pull-request)；`--post` 需要 Claude Code v2.1.227 或更高版本。有关工作量级别、目标和它与 `/simplify` 的关系，请参阅[本地审查差异](/docs/zh-CN/code-review#review-a-diff-locally)。别名：`/review` |72| `/code-review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [pr#\|branch\|path]` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 审查当前差异，或你传递的 PR 号、分支或路径，以查找正确性错误和清理机会。传递 `--fix` 以应用发现，`--comment` 以在 GitHub PR 或 GitLab 合并请求上发布它们，或 `ultra` 以运行深度[云审查](/docs/zh-CN/ultrareview)。发布到 GitLab 合并请求需要 Claude Code v2.1.257 或更高版本。在 `github.com` PR 目标上使用 `ultra` 时，传递 `--post` 以在启动对话框中预选[将完成的发现发布到 PR](/docs/zh-CN/ultrareview#post-findings-to-the-pull-request)；`--post` 需要 Claude Code v2.1.227 或更高版本。有关工作量级别、目标和它与 `/simplify` 的关系，请参阅[本地审查差异](/docs/zh-CN/code-review#review-a-diff-locally)。别名：`/review` |

73| `/color [color\|default]` | 为当前会话设置提示栏颜色。可用颜色：`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan`。使用 `default` 重置，或运行不带参数以选择随机颜色。当 [Remote Control](/docs/zh-CN/remote-control) 连接时，颜色同步到 claude.ai/code。也可在非交互模式 (`-p`) 中使用；需要 Claude Code v2.1.205 或更高版本 |73| `/color [color\|default]` | 为当前会话设置提示栏颜色。可用颜色：`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、`cyan`。使用 `default` 重置，或运行不带参数以选择随机颜色。当 [Remote Control](/docs/zh-CN/remote-control) 连接时，颜色同步到 claude.ai/code。也可在非交互模式 (`-p`) 中使用；需要 Claude Code v2.1.205 或更高版本 |

74| `/compact [instructions]` | 通过总结到目前为止的对话来释放上下文。可选地为摘要传递焦点指令。请参阅[压缩如何处理规则、skill 和内存文件](/docs/zh-CN/context-window#what-survives-compaction) |74| `/compact [instructions]` | 通过总结到目前为止的对话来释放上下文。可选地为摘要传递焦点指令。请参阅[压缩如何处理规则、skill 和内存文件](/docs/zh-CN/context-window#what-survives-compaction) |

75| `/config [key=value ...]` | 打开[设置](/docs/zh-CN/settings)界面以调整主题、模型、[输出样式](/docs/zh-CN/output-styles)和其他首选项。从 v2.1.181 开始，传递一个或多个 `key=value` 对以直接设置设置而不打开界面，例如 `/config thinking=false`。从 v2.1.182 开始，也接受命名的简写键，例如 `/config theme=dark` 或 `/config model=sonnet`。`key=value` 形式也适用于非交互模式 (`-p`) 和来自 Claude 移动应用的 [Remote Control](/docs/zh-CN/remote-control)。`key=value` 形式无法打开需要你在面板中确认的设置，例如 [`autoContinueAtUsageLimit`](/docs/zh-CN/interactive-mode#turn-automatic-continue-off)，尽管它可以关闭一个。运行 `/config --help` 以列出它接受的键。别名：`/settings` |75| `/config [key=value ...]` | 打开[设置](/docs/zh-CN/settings)界面以调整主题、模型、[输出样式](/docs/zh-CN/output-styles)和其他首选项。传递一个或多个 `key=value` 对以直接设置设置而不打开界面，例如 `/config thinking=false`、`/config theme=dark` 或 `/config model=sonnet`。`key=value` 形式也适用于非交互模式 (`-p`) 和来自 Claude 移动应用的 [Remote Control](/docs/zh-CN/remote-control)。`key=value` 形式无法打开需要你在面板中确认的设置，例如 [`autoContinueAtUsageLimit`](/docs/zh-CN/interactive-mode#turn-automatic-continue-off)，尽管它可以关闭一个。运行 `/config --help` 以列出它接受的键。别名：`/settings` |

76| `/context [all]` | 将当前上下文使用情况可视化为彩色网格。显示上下文繁重工具、内存膨胀和容量警告的优化建议。当对话超过上下文窗口时，输出包括一个[警告](/docs/zh-CN/errors#context-exceeds-the-token-limit)，显示你超过限制的距离以及哪个命令释放空间。在[全屏模式](/docs/zh-CN/fullscreen)中，`/context` 折叠每项细目以保持网格可见。传递 `all` 以展开它 |76| `/context [all]` | 将当前上下文使用情况可视化为彩色网格。显示上下文繁重工具、内存膨胀和容量警告的优化建议。当对话超过上下文窗口时，输出包括一个[警告](/docs/zh-CN/errors#context-exceeds-the-token-limit)，显示你超过限制的距离以及哪个命令释放空间。在[全屏模式](/docs/zh-CN/fullscreen)中，`/context` 折叠每项细目以保持网格可见。传递 `all` 以展开它 |

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

100| `/ide` | 管理 IDE 集成并显示状态 |100| `/ide` | 管理 IDE 集成并显示状态 |

101| `/import [codex\|gemini\|cursor] [--dry-run] [--yes]` | 将配置从你的机器上的 OpenAI Codex、Google Gemini CLI 或 Cursor 引入 Claude Code，包括指令文件、MCP 服务器、命令、子代理和 skill。在[非交互模式](/docs/zh-CN/headless)中使用 `-p`，`/import` 列出它找到的内容并给你确认导入的命令。添加 `--dry-run` 以预览而不写入任何内容，或 `--yes` 以跳过交互式选择器。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 上不可用，或通过 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway#availability-and-limitations)。当你关闭[功能标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)时也不可用。需要 Claude Code v2.1.213 或更高版本。从 Cursor 导入需要 v2.1.265 或更高版本 |101| `/import [codex\|gemini\|cursor] [--dry-run] [--yes]` | 将配置从你的机器上的 OpenAI Codex、Google Gemini CLI 或 Cursor 引入 Claude Code，包括指令文件、MCP 服务器、命令、子代理和 skill。在[非交互模式](/docs/zh-CN/headless)中使用 `-p`，`/import` 列出它找到的内容并给你确认导入的命令。添加 `--dry-run` 以预览而不写入任何内容，或 `--yes` 以跳过交互式选择器。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 上不可用，或通过 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway#availability-and-limitations)。当你关闭[功能标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)时也不可用。需要 Claude Code v2.1.213 或更高版本。从 Cursor 导入需要 v2.1.265 或更高版本 |

102| `/init` | 使用 `CLAUDE.md` 指南初始化项目。设置 `CLAUDE_CODE_NEW_INIT=1` 以获得交互式流程，也会引导你完成 skill、hook 和个人内存文件。如果 `/init` 找到 OpenAI Codex 或 Google Gemini CLI 配置，它提供使用 `/import` 进行转移 |102| `/init` | 使用 `CLAUDE.md` 指南初始化项目。设置 `CLAUDE_CODE_NEW_INIT=1` 以获得交互式流程，也会引导你完成 skill、hook 和个人内存文件。如果 `/init` 找到 OpenAI Codex 或 Google Gemini CLI 配置，它提供使用 `/import` 进行转移 |

103| `/insights` | 生成一个 HTML 报告，分析你在这台机器上的最近会话：你在哪些项目中工作、你如何使用 Claude Code、事情出错的地方以及要尝试的功能。在[云会话](/docs/zh-CN/claude-code-on-the-web)中不可用。有关报告位置、保留和成本，请参阅[分析你的使用模式](/docs/zh-CN/costs#analyze-your-usage-patterns) |103| `/insights` | 生成一个 HTML 报告，分析你在这台机器上的最近会话：你在哪些项目中工作、你如何使用 Claude Code、事情出错的地方以及要尝试的功能。在[cloud sessions](/docs/zh-CN/claude-code-on-the-web)中不可用。有关报告位置、保留和成本，请参阅[分析你的使用模式](/docs/zh-CN/costs#analyze-your-usage-patterns) |

104| `/install-github-app` | 为存储库安装 Claude GitHub App，可选步骤设置 [GitHub Actions](/docs/zh-CN/github-actions) 工作流和秘密。引导你完成选择 repo 和配置集成。仅适用于 github.com 存储库。当你的存储库的 git 远程在 gitlab.com 或 bitbucket.org 上时，命令打印通知并退出而不是启动设置。要从 GitLab 管道运行 Claude Code，请参阅 [GitLab CI/CD](/docs/zh-CN/gitlab-ci-cd) |104| `/install-github-app` | 为存储库安装 Claude GitHub App，可选步骤设置 [GitHub Actions](/docs/zh-CN/github-actions) 工作流和秘密。引导你完成选择 repo 和配置集成。仅适用于 github.com 存储库。当你的存储库的 git 远程在 gitlab.com 或 bitbucket.org 上时，命令打印通知并退出而不是启动设置。要从 GitLab 管道运行 Claude Code，请参阅 [GitLab CI/CD](/docs/zh-CN/gitlab-ci-cd) |

114| `/model [model]` | 切换 AI 模型并将其保存为新会话的默认值。对于支持它的模型，使用左/右箭头来[调整工作量级别](/docs/zh-CN/model-config#adjust-effort-level)。没有参数时，打开选择器；在行上按 `s` 仅为当前会话切换。请参阅[当 Claude Code 要求你确认切换时](/docs/zh-CN/prompt-caching#switching-models)。一旦你确认切换，如果 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`) 中使用模型参数而不是选择器，其中它仅应用于当前会话并不保存为你的默认值；需要 Claude Code v2.1.205 或更高版本 |114| `/model [model]` | 切换 AI 模型并将其保存为新会话的默认值。对于支持它的模型，使用左/右箭头来[调整工作量级别](/docs/zh-CN/model-config#adjust-effort-level)。没有参数时，打开选择器；在行上按 `s` 仅为当前会话切换。请参阅[当 Claude Code 要求你确认切换时](/docs/zh-CN/prompt-caching#switching-models)。一旦你确认切换，如果 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`) 中使用模型参数而不是选择器，其中它仅应用于当前会话并不保存为你的默认值；需要 Claude Code v2.1.205 或更高版本 |

115| `/output-style [style]` | 列出[输出样式](/docs/zh-CN/output-styles)或切换到一个，例如 `/output-style concise`。请参阅[更改你的输出样式](/docs/zh-CN/output-styles#change-your-output-style)。需要 Claude Code v2.1.269 或更高版本 |

116| `/permissions` | 管理工具权限的允许、询问和拒绝规则。打开一个交互式对话框，你可以按范围查看规则、添加或移除规则、管理工作目录，以及审查[最近的自动模式拒绝](/docs/zh-CN/auto-mode-config#review-denials)。你也可以从对话框的**自动模式**选项卡查看和编辑[自动模式分类器规则](/docs/zh-CN/auto-mode-config#edit-rules-from-permissions)。当你在 Claude 响应时运行它时，Claude Code 立即打开对话框并从 Claude 在同一轮中的下一个工具调用开始应用你的更改。在 v2.1.234 之前，Claude Code 会将命令排队直到轮次完成。别名：`/allowed-tools` |117| `/permissions` | 管理工具权限的允许、询问和拒绝规则。打开一个交互式对话框，你可以按范围查看规则、添加或移除规则、管理工作目录，以及审查[最近的自动模式拒绝](/docs/zh-CN/auto-mode-config#review-denials)。你也可以从对话框的**自动模式**选项卡查看和编辑[自动模式分类器规则](/docs/zh-CN/auto-mode-config#edit-rules-from-permissions)。当你在 Claude 响应时运行它时，Claude Code 立即打开对话框并从 Claude 在同一轮中的下一个工具调用开始应用你的更改。在 v2.1.234 之前，Claude Code 会将命令排队直到轮次完成。别名：`/allowed-tools` |

126| `/reload-plugins [--force]` | 重新加载所有活跃[插件](/docs/zh-CN/plugins)以应用待处理更改而不重新启动。报告每个重新加载组件的计数并标记任何加载错误。当重新加载会改变加载哪些 MCP 工具并使提示词缓存失效时，命令警告并跳过，除非你传递 `--force`。也可在非交互模式 (`-p`)、Agent SDK 和桌面应用中使用，其中它仅在直接输入到会话的输入上运行，不应用插件 MCP 服务器更改；需要 Claude Code v2.1.260 或更高版本。请参阅[应用插件更改而不重新启动](/docs/zh-CN/discover-plugins#apply-plugin-changes-without-restarting) |127| `/reload-plugins [--force]` | 重新加载所有活跃[插件](/docs/zh-CN/plugins)以应用待处理更改而不重新启动。报告每个重新加载组件的计数并标记任何加载错误。当重新加载会改变加载哪些 MCP 工具并使提示词缓存失效时，命令警告并跳过，除非你传递 `--force`。也可在非交互模式 (`-p`)、Agent SDK 和桌面应用中使用，其中它仅在直接输入到会话的输入上运行，不应用插件 MCP 服务器更改；需要 Claude Code v2.1.260 或更高版本。请参阅[应用插件更改而不重新启动](/docs/zh-CN/discover-plugins#apply-plugin-changes-without-restarting) |

128| `/remote-control` | 使此会话可从 claude.ai 进行 [Remote Control](/docs/zh-CN/remote-control)。在未登录时运行它会打印 Remote Control 需要 claude.ai 订阅并告诉你如何登录；在 v2.1.206 之前它报告 `Unknown command: /remote-control`。别名：`/rc` |129| `/remote-control` | 使此会话可从 claude.ai 进行 [Remote Control](/docs/zh-CN/remote-control)。在未登录时运行它会打印 Remote Control 需要 claude.ai 订阅并告诉你如何登录；在 v2.1.206 之前它报告 `Unknown command: /remote-control`。别名：`/rc` |

130| `/rename [name]` | 重命名当前会话并在提示栏上显示名称。没有名称，从对话历史自动生成一个。也可在非交互模式 (`-p`) 中使用；需要 Claude Code v2.1.205 或更高版本。从每个重命名表面，包括 claude.ai 和桌面应用，Claude Code 用空格替换新名称中的控制和不可见字符，并将名称限制在 200 个字符。如果名称在移除不可见字符后为空，Claude Code 拒绝它并显示 `That name is empty once invisible characters are removed. Usage: /rename <name>`。字符替换和长度限制需要 Claude Code v2.1.221 或更高版本。如果这台机器上的另一个活跃会话已经使用你传递的名称，Claude Code 应用[它的变体](/docs/zh-CN/sessions#name-your-sessions) |131| `/rename [name]` | 重命名当前会话并在提示栏上显示名称。没有名称，从对话历史自动生成一个。也可在非交互模式 (`-p`) 中使用；需要 Claude Code v2.1.205 或更高版本。从每个重命名表面，包括 claude.ai 和桌面应用，Claude Code 用空格替换新名称中的控制和不可见字符，并将名称限制在 200 个字符。如果名称在移除不可见字符后为空，Claude Code 拒绝它并显示 `That name is empty once invisible characters are removed. Usage: /rename <name>`。字符替换和长度限制需要 Claude Code v2.1.221 或更高版本。如果这台机器上的另一个活跃会话已经使用你传递的名称，Claude Code 应用[它的变体](/docs/zh-CN/sessions#name-your-sessions) |

131| `/resume [session]` | 按 ID 或名称恢复对话，或打开会话选择器。[后台会话](/docs/zh-CN/agent-view)在选择器中标记为 `bg` 出现；仍在运行的会话无法在此处恢复，所以从 `claude agents` 附加到它或先在那里停止它。别名：`/continue` |132| `/resume [session]` | 按 ID 或名称恢复对话，或打开会话选择器。[后台会话](/docs/zh-CN/agent-view)在选择器中标记为 `bg` 出现；仍在运行的会话无法在此处恢复，所以从 `claude agents` 附加到它或先在那里停止它。别名：`/continue` |

132| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [pr#\|branch\|path]` | [`/code-review`](/docs/zh-CN/code-review#review-a-diff-locally) 的别名：审查当前差异，或你传递的 PR 号、分支或路径，例如 `/review 1234`，并采用相同的工作量级别和标志。没有给定级别时，审查重用你输入的最后一个 `low` 到 `max` 级别；有关确切规则，请参阅[本地审查差异](/docs/zh-CN/code-review#review-a-diff-locally)。对于深度云审查，使用 [`/code-review ultra`](/docs/zh-CN/ultrareview)。在 v2.1.223 之前，`/review` 是一个单独的命令，运行 GitHub 拉取请求号的单遍、只读审查，在运行不带参数时列出打开的 PR 以选择；从 v2.1.186 到 v2.1.201，它运行与 `/code-review medium` 相同的多代理引擎 |133| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [pr#\|branch\|path]` | [`/code-review`](/docs/zh-CN/code-review#review-a-diff-locally) 的别名：审查当前差异，或你传递的 PR 号、分支或路径，例如 `/review 1234`，并采用相同的工作量级别和标志。没有给定级别时，审查重用你输入的最后一个 `low` 到 `max` 级别；有关确切规则，请参阅[本地审查差异](/docs/zh-CN/code-review#review-a-diff-locally)。对于深度云审查，使用 [`/code-review ultra`](/docs/zh-CN/ultrareview)。在 v2.1.223 之前，`/review` 是一个单独的命令，运行 GitHub 拉取请求号的单遍、只读审查，在运行不带参数时列出打开的 PR 以选择；从 v2.1.186 到 v2.1.201，它运行与 `/code-review medium` 相同的多代理引擎 |

150| `/subtask <task>` | 生成一个[分叉子代理](/docs/zh-CN/sub-agents#fork-the-current-conversation)：一个继承完整对话的后台子代理，在你继续工作时处理任务。其结果在完成时返回到这个对话。要将对话复制到单独的后台会话，请改用 `/fork`。需要 Claude Code v2.1.212 或更高版本；在 v2.1.161 到 v2.1.211，这个命令是 `/fork`。当[代理视图关闭](/docs/zh-CN/agent-view#turn-off-agent-view)时，`/subtask` 不可用，`/fork` 保持分叉子代理行为 |151| `/subtask <task>` | 生成一个[分叉子代理](/docs/zh-CN/sub-agents#fork-the-current-conversation)：一个继承完整对话的后台子代理，在你继续工作时处理任务。其结果在完成时返回到这个对话。要将对话复制到单独的后台会话，请改用 `/fork`。需要 Claude Code v2.1.212 或更高版本；在 v2.1.161 到 v2.1.211，这个命令是 `/fork`。当[代理视图关闭](/docs/zh-CN/agent-view#turn-off-agent-view)时，`/subtask` 不可用，`/fork` 保持分叉子代理行为 |

152| `/team-onboarding` | 从你的 Claude Code 使用历史生成团队入职指南。Claude 分析你过去 30 天的会话、命令和 MCP 服务器使用情况，并生成一个 markdown 指南，队友可以粘贴为第一条消息以快速设置。对于 Pro、Max、Team 和 Enterprise 计划上的 claude.ai 订阅者，也返回一个共享链接，队友可以直接在 Claude Code 中打开 |153| `/team-onboarding` | 从你的 Claude Code 使用历史生成团队入职指南。Claude 分析你过去 30 天的会话、命令和 MCP 服务器使用情况，并生成一个 markdown 指南，队友可以粘贴为第一条消息以快速设置。对于 Pro、Max、Team 和 Enterprise 计划上的 claude.ai 订阅者，也返回一个共享链接，队友可以直接在 Claude Code 中打开 |

153| `/teleport` | 将 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web#from-web-to-terminal) 会话拉入此终端。打开选择器，然后获取分支和对话。也可用作 `/tp`。需要 claude.ai 订阅 |154| `/teleport` | 将 [cloud session](/docs/zh-CN/claude-code-on-the-web#from-cloud-to-terminal) 拉入此终端。打开选择器，然后获取分支和对话。也可用作 `/tp`。需要 claude.ai 订阅 |

154| `/terminal-setup` | [在 VS Code、Cursor、Devin Desktop、Alacritty 或 Zed 中安装 Shift+Enter 快捷键以输入多行](/docs/zh-CN/terminal-config#enter-multiline-prompts)。在 Apple Terminal 中，[改为启用 Option+Enter 以输入多行并关闭可听铃声](/docs/zh-CN/terminal-config#enable-option-key-shortcuts-on-macos)。在 iTerm2 中，[打开剪贴板访问以便 `/copy` 工作](/docs/zh-CN/terminal-config#enable-option-key-shortcuts-on-macos) |155| `/terminal-setup` | [在 VS Code、Cursor、Devin Desktop、Alacritty 或 Zed 中安装 Shift+Enter 快捷键以输入多行](/docs/zh-CN/terminal-config#enter-multiline-prompts)。在 Apple Terminal 中，[改为启用 Option+Enter 以输入多行并关闭可听铃声](/docs/zh-CN/terminal-config#enable-option-key-shortcuts-on-macos)。在 iTerm2 中，[打开剪贴板访问以便 `/copy` 工作](/docs/zh-CN/terminal-config#enable-option-key-shortcuts-on-macos) |

155| `/theme` | 更改颜色主题。包括与你的终端的浅色或深色背景匹配的 `auto` 选项、浅色和深色变体、色盲无障碍（daltonized）主题、使用你的终端颜色调色板的 ANSI 主题，以及来自 `~/.claude/themes/` 或插件的任何[自定义主题](/docs/zh-CN/terminal-config#create-a-custom-theme)。选择\*\*新建自定义主题…\*\*以创建一个 |156| `/theme` | 更改颜色主题。包括与你的终端的浅色或深色背景匹配的 `auto` 选项、浅色和深色变体、色盲无障碍（daltonized）主题、使用你的终端颜色调色板的 ANSI 主题，以及来自 `~/.claude/themes/` 或插件的任何[自定义主题](/docs/zh-CN/terminal-config#create-a-custom-theme)。选择\*\*新建自定义主题…\*\*以创建一个 |

157| `/ultraplan <prompt>` | 已移除。改用[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)。以前将规划任务发送到 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 会话以在你的浏览器中审查 |158| `/ultraplan <prompt>` | 已移除。改用[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)。以前将规划任务发送到 [cloud session](/docs/zh-CN/claude-code-on-the-web) 以在你的浏览器中审查 |

158| `/ultrareview [PR or branch]` | 在云沙箱中运行深度、多代理代码审查，使用 [ultrareview](/docs/zh-CN/ultrareview)。传递 PR 参考以审查该拉取请求，或分支名称以更改比较基础。首选调用现在是 `/code-review ultra`，`/ultrareview` 保留为别名。在 Pro 和 Max 上包括 3 次免费运行，然后需要[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |159| `/ultrareview [PR or branch]` | 在云沙箱中运行深度、多代理代码审查，使用 [ultrareview](/docs/zh-CN/ultrareview)。传递 PR 参考以审查该拉取请求，或分支名称以更改比较基础。首选调用现在是 `/code-review ultra`，`/ultrareview` 保留为别名。在 Pro 和 Max 上包括 3 次免费运行，然后需要[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

160| `/usage` | 显示会话成本、计划使用限制和活动统计。在 Pro、Max、Team 或 Enterprise 计划上，包括[计入你的计划限制的内容的细目](/docs/zh-CN/costs#plan-usage-breakdown)。`/cost` 和 `/stats` 是别名 |161| `/usage` | 显示会话成本、计划使用限制和活动统计。在 Pro、Max、Team 或 Enterprise 计划上，包括[计入你的计划限制的内容的细目](/docs/zh-CN/costs#plan-usage-breakdown)。`/cost` 和 `/stats` 是别名 |

162| `/verify` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 通过构建你的项目应用、运行它并观察结果来确认代码更改做了它应该做的事，而不是依赖测试或类型检查。请参阅[运行和验证你的应用](/docs/zh-CN/skills#run-and-verify-your-app) |163| `/verify` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 通过构建你的项目应用、运行它并观察结果来确认代码更改做了它应该做的事，而不是依赖测试或类型检查。请参阅[运行和验证你的应用](/docs/zh-CN/skills#run-and-verify-your-app) |

163| `/vim` | 在 v2.1.92 中移除。要在 Vim 和 Normal 编辑模式之间切换，请使用 `/config` → 编辑器模式 |164| `/vim` | 在 v2.1.92 中移除。要在 Vim 和 Normal 编辑模式之间切换，请使用 `/config` → 编辑器模式 |

164| `/voice [hold\|tap\|off]` | 切换[语音听写](/docs/zh-CN/voice-dictation)，或在特定模式下启用它。需要 Claude.ai 账户 |165| `/voice [hold\|tap\|off]` | 切换[语音听写](/docs/zh-CN/voice-dictation)，或在特定模式下启用它。需要 Claude.ai 账户 |

165| `/web-setup` | 使用你的本地 `gh` CLI 凭证将你的 GitHub 账户连接到 [Claude Code on the web](/docs/zh-CN/web-quickstart#connect-from-your-terminal) |166| `/web-setup` | 使用你的本地 `gh` CLI 凭证将你的 GitHub 账户连接到 [cloud sessions](/docs/zh-CN/web-quickstart#connect-from-your-terminal) |

166| `/workflow-authoring` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 加载编写[动态 workflow](/docs/zh-CN/workflows) 脚本的参考：脚本 API、恢复行为、质量模式和工作示例。Claude 通常在编写脚本之前自己加载它；在[手动编辑保存的脚本](/docs/zh-CN/workflows#edit-a-saved-script)之前自己运行它。在启用动态 workflow 时可用，需要 Claude Code v2.1.248 或更高版本 |167| `/workflow-authoring` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 加载编写[动态 workflow](/docs/zh-CN/workflows) 脚本的参考：脚本 API、恢复行为、质量模式和工作示例。Claude 通常在编写脚本之前自己加载它；在[手动编辑保存的脚本](/docs/zh-CN/workflows#edit-a-saved-script)之前自己运行它。在启用动态 workflow 时可用，需要 Claude Code v2.1.248 或更高版本 |

168 169

context-window.md +6 −3

Details

1586 1586

1587该会话通过具有代表性的令牌计数演示了一个现实的流程：1587该会话通过具有代表性的令牌计数演示了一个现实的流程：

1588 1588

1589* **在您输入任何内容之前**：CLAUDE.md、自动内存、MCP 工具名称和技能描述都加载到上下文中。您自己的设置可能会在此处添加更多内容，例如[输出样式](/docs/zh-CN/output-styles)或来自 [`--append-system-prompt`](/docs/zh-CN/cli-reference) 的文本。1589* **在您输入任何内容之前**：CLAUDE.md、自动内存、MCP 工具名称和技能描述都加载到上下文中。[AGENTS.md 文件](/docs/zh-CN/memory#agents-md)也可以加载，无论是单独加载还是与 CLAUDE.md 一起加载。您自己的设置可能会在此处添加更多内容，例如[输出样式](/docs/zh-CN/output-styles)或来自 [`--append-system-prompt`](/docs/zh-CN/cli-reference) 的文本。

1590* **当 Claude 工作时**：每个文件读取都会添加到上下文中，[路径范围的规则](/docs/zh-CN/memory#path-specific-rules)会自动与匹配的文件一起加载，并且[PostToolUse hook](/docs/zh-CN/hooks-guide)在每次编辑后触发。1590* **当 Claude 工作时**：每个文件读取都会添加到上下文中，[路径范围的规则](/docs/zh-CN/memory#path-specific-rules)会自动与匹配的文件一起加载，并且[PostToolUse hook](/docs/zh-CN/hooks-guide)在每次编辑后触发。

1591* **后续提示**：[子代理](/docs/zh-CN/sub-agents)在其自己的单独上下文窗口中处理研究，因此大文件读取不会进入您的窗口。只有摘要和一个小的元数据预告片返回。1591* **后续提示**：[子代理](/docs/zh-CN/sub-agents)在其自己的单独上下文窗口中处理研究，因此大文件读取不会进入您的窗口。只有摘要和一个小的元数据预告片返回。

1592* **最后**：`/compact` 用结构化摘要替换对话。大多数启动内容会自动重新加载；下表显示了每个机制会发生什么。1592* **最后**：`/compact` 用结构化摘要替换对话。大多数启动内容会自动重新加载；下表显示了每个机制会发生什么。

1598当长会话压缩时，Claude Code 会总结对话历史以适应上下文窗口。从 v2.1.198 开始，总结请求继承您会话的[扩展思考](/docs/zh-CN/model-config#extended-thinking)配置，因此当您的会话启用思考时，它会在启用思考的情况下进行推理，否则保持关闭。思考仅影响摘要的生成方式；您的会话设置之后保持不变。每种内容的处理方式取决于其加载方式：1598当长会话压缩时，Claude Code 会总结对话历史以适应上下文窗口。从 v2.1.198 开始，总结请求继承您会话的[扩展思考](/docs/zh-CN/model-config#extended-thinking)配置，因此当您的会话启用思考时，它会在启用思考的情况下进行推理，否则保持关闭。思考仅影响摘要的生成方式；您的会话设置之后保持不变。每种内容的处理方式取决于其加载方式：

1599 1599

1600| 机制 | 压缩后 |1600| 机制 | 压缩后 |

1601| :------------------------------------------------------------------------------------------ | :------------------------------------------- |1601| :---------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------- |

1602| 系统提示和输出样式 | 两者仍然适用 |1602| 系统提示和输出样式 | 两者仍然适用 |

1603| 项目根目录 CLAUDE.md 和无范围规则 | 从磁盘重新注入 |1603| 项目根目录 CLAUDE.md 和无范围规则 | 从磁盘重新注入 |

1604| 自动内存 | 从磁盘重新注入 |1604| 自动内存 | 从磁盘重新注入 |

1607| 子目录中的嵌套 CLAUDE.md | Claude Code 在读取该子目录中的文件时重新加载它们 |1607| 子目录中的嵌套 CLAUDE.md | Claude Code 在读取该子目录中的文件时重新加载它们 |

1608| Claude 读取或编辑的文件 | Claude Code 重新读取最多五个，最近修改的优先 |1608| Claude 读取或编辑的文件 | Claude Code 重新读取最多五个，最近修改的优先 |

1609| 调用的技能主体 | 重新注入，每个技能上限为 5,000 个令牌，总计 25,000 个令牌；最旧的首先删除 |1609| 调用的技能主体 | 重新注入，每个技能上限为 5,000 个令牌，总计 25,000 个令牌；最旧的首先删除 |

1610| [后台命令](/docs/zh-CN/interactive-mode#background-bash-commands)和后台[子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background) | 继续运行。Claude Code 提醒 Claude 哪些仍在运行，以便它不会启动重复的 |

1610| Hooks 添加的上下文 | 与对话的其余部分一起总结 |1611| Hooks 添加的上下文 | 与对话的其余部分一起总结 |

1611| 匹配 `compact` 源的 [SessionStart hooks](/docs/zh-CN/hooks-guide#re-inject-context-after-compaction) | Claude Code 运行它们并将其输出添加到压缩的上下文中 |1612| 匹配 `compact` 源的 [SessionStart hooks](/docs/zh-CN/hooks-guide#re-inject-context-after-compaction) | Claude Code 运行它们并将其输出添加到压缩的上下文中 |

1612 1613

1613路径范围的规则和嵌套的 CLAUDE.md 文件在读取其触发文件时加载到消息历史中，因此压缩会将它们与其他所有内容一起总结。压缩后，Claude Code 重新读取最多五个 Claude 在会话中读取或编辑的文件，选择最近修改的文件，并重新加载适用于这些文件的规则和嵌套 CLAUDE.md 文件。超过 5,000 个令牌的文件作为路径引用返回，不包含其内容，显示为 `Referenced file` 而不是 `Read`。其规则仍然重新加载。如果规则必须在压缩过程中保持不变，请删除 `paths:` frontmatter 或将其移动到项目根目录 CLAUDE.md。1614压缩后立即，Claude Code 重新读取最多五个 Claude 在会话中读取或编辑的文件，选择最近修改的文件。超过 5,000 个令牌的文件作为路径引用返回，不包含其内容，显示为 `Referenced file` 而不是 `Read`。

1615

1616路径范围的规则和嵌套的 CLAUDE.md 文件在读取其触发文件时加载到消息历史中，因此压缩会将它们与其他所有内容一起总结。如果规则必须在压缩过程中保持不变，请删除 `paths:` frontmatter 或将其移动到项目根目录 CLAUDE.md。

1614 1617

1615技能主体在压缩后重新注入，但大型技能会被截断以适应每个技能的上限，一旦超过总预算，最旧的调用技能就会被删除。截断保留文件的开头，因此请将最重要的指令放在 `SKILL.md` 的顶部附近。1618技能主体在压缩后重新注入，但大型技能会被截断以适应每个技能的上限，一旦超过总预算，最旧的调用技能就会被删除。截断保留文件的开头，因此请将最重要的指令放在 `SKILL.md` 的顶部附近。

1616 1619

corporate-launcher.md +1 −1

Details

40以下进程不通过启动器启动：40以下进程不通过启动器启动：

41 41

42* [已安装的后台服务](/docs/zh-CN/agent-view#the-supervisor-process)，其单元在配置启动器之前编写：`launchd` 或 `systemd` 从其单元文件启动该进程。当运行的服务和配置的启动器不匹配时，`/status` 和 `claude daemon status` 会发出警告，一旦服务使用设置中的变量重新启动，服务生成的会话仍会通过启动器启动。42* [已安装的后台服务](/docs/zh-CN/agent-view#the-supervisor-process)，其单元在配置启动器之前编写：`launchd` 或 `systemd` 从其单元文件启动该进程。当运行的服务和配置的启动器不匹配时，`/status` 和 `claude daemon status` 会发出警告，一旦服务使用设置中的变量重新启动，服务生成的会话仍会通过启动器启动。

43* 您自己在终端中启动的会话，它运行的方式取决于您如何调用它。要覆盖这些会话，在 `PATH` 上较早的目录中放置一个名为 `claude` 的脚本，该脚本使用真实二进制文件运行您的启动器；不要替换托管符号链接。自生成不查询 `PATH`，所以两个启动器永远不会堆叠。43* 您自己在终端中启动的会话，它运行的方式取决于您如何调用它。要覆盖这些会话，在 `PATH` 上较早的目录中放置一个名为 `claude` 的脚本，该脚本使用真实二进制文件运行您的启动器；不要替换托管符号链接。后台服务及其会话启动时不进行 `PATH` 查询，所以两个启动器不会在那里堆叠。

44* `claude-cli://` 深层链接的第一个进程，操作系统的协议处理程序直接启动。该会话之后在后台启动的所有内容都通过启动器运行。要完全关闭此路径，请使用 `disableDeepLinkRegistration` 设置 [prevent handler registration](/docs/zh-CN/deep-links#registration-and-supported-platforms)。44* `claude-cli://` 深层链接的第一个进程，操作系统的协议处理程序直接启动。该会话之后在后台启动的所有内容都通过启动器运行。要完全关闭此路径，请使用 `disableDeepLinkRegistration` 设置 [prevent handler registration](/docs/zh-CN/deep-links#registration-and-supported-platforms)。

45* `--worktree` 与 `--tmux` 结合执行的重新启动：终端多路复用器启动该窗格，而不是 Claude Code 的二进制文件。45* `--worktree` 与 `--tmux` 结合执行的重新启动：终端多路复用器启动该窗格，而不是 Claude Code 的二进制文件。

46* [Claude in Chrome](/docs/zh-CN/chrome) 注册的本机消息主机：浏览器启动它，而不是 Claude Code 的二进制文件。46* [Claude in Chrome](/docs/zh-CN/chrome) 注册的本机消息主机：浏览器启动它，而不是 Claude Code 的二进制文件。

costs.md +1 −1

Details

146 </Step>146 </Step>

147 147

148 <Step title="编写设置">148 <Step title="编写设置">

149 为列表价格设置 `multiplier` 以获得固定百分比折扣，在 `overrides` 下列出每个模型的四个每令牌费率，或两者都做。[`modelPricing` 条目](/docs/zh-CN/settings-reference#modelpricing)具有形状和粘贴就用的示例。149 为列表价格设置 `multiplier` 以获得固定折扣或高于 1 以获得加价，在 `overrides` 下列出每个模型的四个每令牌费率，或两者都做。加价需要 Claude Code v2.1.271 或更高版本。[`modelPricing` 条目](/docs/zh-CN/settings-reference#modelpricing)具有形状和粘贴就用的示例。

150 </Step>150 </Step>

151 151

152 <Step title="通过托管设置部署它">152 <Step title="通过托管设置部署它">

cross-session-messaging.md +41 −37

Details

44要自己提示一条消息，告诉 Claude 你想让另一个会话知道或做什么。这个例子是你输入的提示，而不是 Claude 发送的消息：44要自己提示一条消息，告诉 Claude 你想让另一个会话知道或做什么。这个例子是你输入的提示，而不是 Claude 发送的消息：

45 45

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

~~47询问在我的另一个终端中运行的会话迁移是否完成~~47Ask the session running in my other terminal whether the migration finished

48```48```

49 49

~~50Claude 会自己编写实际的消息，所以你的提示可以将内容留给 Claude。这个提示要求一个摘要而不指定其措辞，Claude 发送的内容会有所不同：~~50Claude 会自己写出实际的消息，所以你的提示可以将内容留给 Claude。这个提示要求一个摘要而不指定其措辞，Claude 发送的内容会有所不同：

51 51

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

~~53向处理支付 API 的会话解释我们刚刚做了什么~~53Explain what we just did to the session working on the payments API

54```54```

55 55

56要自己命名目标，在你的提示中提及会话：输入 `@` 后跟会话名称的首字母，然后从类型提前中选择会话，就像你 [@-提及子代理](/docs/zh-CN/sub-agents#invoke-subagents-explicitly) 一样。需要 Claude Code v2.1.232 或更高版本。Claude Code 会插入提及，例如 `@api-worker`，并告诉 Claude 它命名的是哪个会话，所以 Claude 可以向该会话发送消息而无需先列出你的会话。这个提示用提及来命名目标：56要自己命名目标，在你的提示中提及会话：输入 `@` 后跟会话名称的首字母，然后从类型提示中选择会话，就像你 [@-提及一个子代理](/docs/zh-CN/sub-agents#invoke-subagents-explicitly) 一样。需要 Claude Code v2.1.232 或更高版本。Claude Code 会插入提及，例如 `@api-worker`，并告诉 Claude 它命名的是哪个会话，所以 Claude 可以向该会话发送消息而无需先列出你的会话。这个提示用提及来命名目标：

57 57

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

~~59让 @api-worker 知道架构迁移已完成~~59Let @api-worker know the schema migration finished

60```60```

61 61

~~62类型提前列出你在这台机器上的其他活跃会话。两种情况需要超过名称的首字母：~~62类型提示列出了你在这台机器上的其他活跃会话。两种情况需要超过名称的首字母：

63 63

64* **这台机器之外的会话**：云会话或远程控制会话仅在 Claude 列出或向这台机器之外的会话发送消息后才会出现在类型提前中，所以请先要求 Claude 列出它们。64* **这台机器之外的会话**：云会话或远程控制会话仅在 Claude 列出或向你这台机器之外的会话发送消息后才会出现在类型提示中，所以先要求 Claude 列出它们。

65* **名称中有空格或字母、数字、连字符和下划线之外的其他字符**：在双引号中输入，例如 `@"release notes"`。当你从类型提前中选择会话时，Claude Code 会为你插入引号。65* **名称中有空格或字母、数字、连字符和下划线之外的其他字符**：在双引号中输入，例如 `@"release notes"`。当你从类型提示中选择会话时，Claude Code 会为你插入引号。

66 66

67你也可以在没有选择器的情况下输入提及。当多个活跃会话响应提及的名称时，Claude 会在发送前询问你指的是哪一个。67你也可以在没有选择器的情况下输入提及。当多个活跃会话响应提及的名称时，Claude 会在发送前询问你指的是哪一个。

68 68

~~69关于 Claude 编写的消息到达时的样子，包括一个例子，请参见 [消息看起来像什么](#what-a-message-looks-like)。~~69关于 Claude 写的消息到达时的样子，包括一个例子，请参见 [消息看起来像什么](#what-a-message-looks-like)。

70 70

71<h3 id="message-delivery">71<h3 id="message-delivery">

72 消息传递72 消息传递

73</h3>73</h3>

74 74

75接收 Claude 在活跃轮次期间的工具调用之间读取消息，所以运行的工具永远不会被中断。当接收会话处于空闲状态时，Claude Code 会用消息启动一个新轮次。75接收 Claude 在活跃轮次中的工具调用之间读取消息，所以运行的工具永远不会被中断。当接收会话处于空闲状态时，Claude Code 会用消息启动一个新轮次。

76 76

77来自另一个会话的消息以纯文本形式到达。如果它用 `@` 提及文件或 [MCP 资源](/docs/zh-CN/mcp#use-mcp-resources)，Claude 会看到书写的提及，Claude Code 不会附加任何内容，无论消息是启动新轮次还是在轮次期间到达。Claude 仍然可以用自己的工具在接收机器上打开提及的路径，受该会话的权限限制。在 v2.1.251 之前，启动新轮次的消息中的 `@` 提及会在接收端附加文件或 MCP 资源。77来自另一个会话的消息以纯文本形式到达。如果它用 `@` 提及文件或 [MCP 资源](/docs/zh-CN/mcp#use-mcp-resources)，Claude 会看到如写入的提及，Claude Code 不会附加任何内容，无论消息是启动新轮次还是在轮次中到达。Claude 仍然可以用自己的工具在接收机器上打开提及的路径，受该会话的权限限制。在 v2.1.251 之前，启动新轮次的消息中的 `@` 提及会在接收端附加文件或 MCP 资源。

78 78

79Claude Code 在以下情况下拒绝消息：79Claude Code 在以下情况下拒绝消息：

80 80

97 当另一个会话变为空闲时获得通知97 当另一个会话变为空闲时获得通知

98</h3>98</h3>

99 99

100Claude 可以要求你在这台机器上的一个会话在该会话下一次变为空闲或退出时发回一个通知。空闲在这里意味着会话完成了一个轮次，没有任何排队。当你在另一个会话中等待长任务并想听到它完成时而不是检查时使用它。需要两个会话中都有 Claude Code v2.1.236 或更高版本。100Claude 可以要求你在这台机器上的一个会话在该会话下一次变为空闲或退出时发回一个通知。空闲在这里意味着会话完成了一个轮次，没有任何排队。当你在另一个会话中等待长任务并想听到它完成时而不是检查时使用它。需要两个会话中的 Claude Code v2.1.236 或更高版本。

101 101

102<h4 id="ask-for-a-notice">102<h4 id="ask-for-a-notice">

103 请求通知103 请求通知

104</h4>104</h4>

105 105

106告诉 Claude 你在等待什么。这个提示要求来自迁移会话的通知：106告诉 Claude 你在等什么。这个提示要求来自迁移会话的通知：

107 107

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

109告诉我迁移会话何时完成它正在处理的工作109Tell me when the migration session finishes what it's working on

110```110```

111 111

112Claude 使用 `SendMessage` 工具的 `notify_when_idle` 输入进行订阅，要么附加到它正在发送的消息，要么单独进行。单独进行时，Claude Code 订阅而不在被监视的会话中启动轮次或花费令牌，如果该会话已经空闲，则立即发送通知。附加到消息时，Claude Code 首先传递消息，然后稍后发送通知。112Claude 使用 `SendMessage` 工具的 `notify_when_idle` 输入进行订阅，要么附加到它正在发送的消息，要么单独进行。单独进行时，Claude Code 订阅而不在被监视的会话中启动轮次或花费令牌，如果该会话已经空闲，则立即发送通知。附加到消息时，Claude Code 首先传递消息，然后稍后发送通知。

115 每个会话显示什么115 每个会话显示什么

116</h4>116</h4>

117 117

118被监视的会话显示一行，说另一个进程要求在会话下一次空闲时被告知。要求会话显示通知为一行，命名被监视的会话。该行可以包括该会话轮次完成的时间和该轮次的单行状态。如果要求会话处于空闲状态，Claude Code 会用通知启动一个新轮次。118被监视的会话显示一行，说另一个进程要求在会话下一次空闲时被告知。要求的会话将通知显示为命名被监视会话的一行。该行可以包括该会话轮次完成的时间和该轮次的单行状态。如果要求的会话处于空闲状态，Claude Code 会用通知启动一个新轮次。

119 119

120<h4 id="limits">120<h4 id="limits">

121 限制121 限制

126每一方的 [入站控制](#control-inbound-messages) 适用于像消息一样的通知：126每一方的 [入站控制](#control-inbound-messages) 适用于像消息一样的通知：

127 127

128* **任一方的 `refuse`**：什么都不会到达。被监视的会话在不记录或回答的情况下删除请求，所以订阅在 12 小时后无答复过期，具有 `refuse` 的要求会话永远不会订阅。128* **任一方的 `refuse`**：什么都不会到达。被监视的会话在不记录或回答的情况下删除请求，所以订阅在 12 小时后无答复过期，具有 `refuse` 的要求会话永远不会订阅。

129* **任一方的 `hold`**：通知到达时内容较少。被监视的会话省略单行状态，要求会话在你的记录中显示通知而不将其传递给 Claude。129* **任一方的 `hold`**：通知到达时内容较少。被监视的会话省略单行状态，要求的会话在你的记录中显示通知而不将其传递给 Claude。

130 130

131只有你主要对话中的 Claude 可以订阅，并且仅限于你在这台机器上的会话。当子代理或代理团队队友设置 `notify_when_idle` 时，Claude Code 不会进行订阅并告诉它这样做。当 Claude 要求来自任何其他代理的通知时，例如队友、子代理或这台机器之外的会话，Claude Code 拒绝整个调用，包括附加到它的任何消息，并向 Claude 报告拒绝，以便它可以在没有请求的情况下重新发送消息。131只有你主要对话中的 Claude 可以订阅，并且仅限于你在这台机器上的会话。当子代理或代理团队队友设置 `notify_when_idle` 时，Claude Code 不会进行订阅并告诉它这样做。当 Claude 要求来自任何其他代理的通知时，例如队友、子代理或这台机器之外的会话，Claude Code 拒绝整个调用，包括附加到它的任何消息，并向 Claude 报告拒绝，以便它可以在没有请求的情况下重新发送消息。

132 132

134 查看 Claude 可以到达的会话134 查看 Claude 可以到达的会话

135</h3>135</h3>

136 136

137Claude 自己找到消息的目标，所以你不需要在要求它发送之前运行任何东西。要自己查看 Claude 可以到达的会话，请运行 `/list-agents` 命令。第一行（如果存在）是此会话自己的名称，你的其他会话用来向它发送消息的名称。下面的行是 Claude 可以到达的会话：137Claude 自己找到消息的目标，所以你不需要在要求它发送之前运行任何东西。要自己查看 Claude 可以到达的会话，运行 `/list-agents` 命令。第一行（如果存在）是此会话自己的名称，你的其他会话用来向它发送消息的名称。下面的行是 Claude 可以到达的会话：

138 138

139* **子代理**：在当前会话内运行的代理。139* **子代理**：在当前会话内运行的代理。

140* **队友**：此会话自己的 [代理团队](/docs/zh-CN/agent-teams) 队友。在 v2.1.239 之前，队友没有出现在列表中，尽管 Claude 已经可以按名称向他们发送消息。140* **队友**：此会话自己的 [代理团队](/docs/zh-CN/agent-teams) 队友。在 v2.1.239 之前，队友没有出现在列表中，尽管 Claude 已经可以按名称向他们发送消息。

141* **你的其他本地会话**：在同一台机器上运行的 Claude Code 会话，包括 [后台会话](/docs/zh-CN/agent-view)。会话仅在绑定 [收件箱套接字](#the-sessions-inbox-socket) 时才会出现。141* **你的其他本地会话**：在同一台机器上运行的 Claude Code 会话，包括 [后台会话](/docs/zh-CN/agent-view)。会话仅在绑定 [收件箱套接字](#the-sessions-inbox-socket) 时出现。

142* **你的云会话**：你的 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 会话，在此会话连接到 [Remote Control](/docs/zh-CN/remote-control) 时显示。Claude Code 在列表中将它们标记为 `cloud`。142* **你的 [云会话](/docs/zh-CN/claude-code-on-the-web)**：在此会话连接到 [远程控制](/docs/zh-CN/remote-control) 时显示。Claude Code 在列表中将它们标记为 `cloud`。

143* **你在其他机器上的 Remote Control 会话**：在此会话连接到 [Remote Control](/docs/zh-CN/remote-control) 时显示，并标记为 `Remote Control`。Claude Code 显示 `offline` 作为 Remote Control 连接已断开的会话的状态。143* **你在其他机器上的远程控制会话**：在此会话连接到 [远程控制](/docs/zh-CN/remote-control) 时显示，并标记为 `Remote Control`。Claude Code 显示 `offline` 作为远程控制连接已断开的会话的状态。

144 144

145此会话不是行之一。如果 Claude 将消息寻址到此会话自己的名称，Claude Code 会拒绝它并告诉 Claude 目标是当前会话。在 v2.1.239 之前，列表没有显示此会话的名称，Claude Code 将发送到它的消息报告为它找不到的代理。145此会话不是行之一。如果 Claude 将消息寻址到此会话自己的名称，Claude Code 会拒绝它并告诉 Claude 目标是当前会话。在 v2.1.239 之前，列表没有显示此会话的名称，Claude Code 报告发送给它的消息为它找不到的代理。

146 146

147当此会话连接到 [Remote Control](/docs/zh-CN/remote-control) 时，Claude Code 从 `/list-agents` 输出中隐瞒你的本地会话的一些详细信息，而不改变 Claude 本身在寻找会话以发送消息时看到的内容：147当此会话连接到 [远程控制](/docs/zh-CN/remote-control) 时，Claude Code 从 `/list-agents` 输出中隐瞒你的本地会话的一些详细信息，而不改变 Claude 本身在寻找会话发送消息时看到的内容：

148 148

149* **工作目录**：它省略每个本地会话的工作目录。149* **工作目录**：它省略了每个本地会话的工作目录。

150* **会话名称**：它省略任何它不能归因于一个人的会话名称，所以没有名称的行读作 `(unnamed session)`。150* **会话名称**：它省略了任何它无法归因于某个人的会话名称，所以没有名称的行读作 `(unnamed session)`。

151* **第一行**：它省略此会话自己的名称行，除非你在此终端输入了该名称，使用 `--name` 或使用 `/rename` 和名称，因为你启动或最后恢复了会话。151* **第一行**：它省略了此会话自己的名称行，除非你在此终端输入了该名称，使用 `--name` 或使用 `/rename` 和名称，因为你启动或最后恢复了会话。

152 152

153当输出列出任何内容时，它以一个说明详细信息被隐瞒的注释结束。在会话自己的键盘上运行 `/rename` 后跟未使用的名称会给该会话一个出现在输出中的名称。153当输出列出任何内容时，它以一个说明详细信息被隐瞒的注释结束。在会话自己的键盘上运行 `/rename` 后跟未使用的名称会给该会话一个出现在输出中的名称。

154 154

155Claude Code 首先读取你的云和 Remote Control 会话列表最新的，并在每个会话后停止有界数量的页面。如果你的账户有超过适合的那些会话，Claude Code 不会列出较旧的，Claude 无法按名称向它们发送消息。当这种情况发生时，Claude Code 在列表中说明，Claude 在发送消息时看到相同的注释。155Claude Code 首先读取你的云和远程控制会话列表最新的，并在每个会话后停止有限数量的页面。如果你的账户有超过适合的那些会话，Claude Code 不会列出较旧的会话，Claude 无法按名称向它们发送消息。当这种情况发生时，Claude Code 在列表中说明这一点，Claude 在发送消息时看到相同的注释。

156 156

157Claude 按名称寻址这台机器之外的会话，就像本地会话一样。有关这些消息如何传播，请参见 [向其他机器上的会话发送消息](#message-sessions-on-other-machines)。157Claude 按名称寻址这台机器之外的会话，就像本地会话一样。有关这些消息如何传播，请参见 [向其他机器上的会话发送消息](#message-sessions-on-other-machines)。

158 158

159会话响应你使用 [`/rename`](/docs/zh-CN/commands) 命令或 [`--name`](/docs/zh-CN/cli-reference#cli-flags) 标志设置的名称。当你不设置一个时，Claude Code 自己命名会话。对于交互式会话，这是 [运行会话列表](/docs/zh-CN/sessions#name-your-sessions) 中显示的名称。159会话响应你使用 [`/rename`](/docs/zh-CN/commands) 命令或 [`--name`](/docs/zh-CN/cli-reference#cli-flags) 标志设置的名称。当你不设置一个时，Claude Code 自己命名会话。对于交互式会话，这是 [运行会话的列表](/docs/zh-CN/sessions#name-your-sessions) 中显示的名称。

160 160

161当你重命名会话时，Claude Code 也会更新你的其他会话用来查找会话名称的共享记录。如果它无法更新该记录，它会在 `/rename` 输出中警告你其他会话可能仍然显示旧名称。使用 [`--debug`](/docs/zh-CN/cli-reference#cli-flags) 运行会话，Claude Code 会记录失败更新的原因。161当你重命名会话时，Claude Code 也会更新你的其他会话用来查找会话名称的共享记录。如果它无法更新该记录，它会在 `/rename` 输出中警告你其他会话可能仍然显示旧名称。使用 [`--debug`](/docs/zh-CN/cli-reference#cli-flags) 运行会话，Claude Code 会记录失败更新的原因。

162 162

163当你重命名会话或启动或恢复交互式会话时，使用这台机器上另一个活跃会话已经使用的名称，Claude Code 将名称留给已经拥有它的会话，并 [将你的重命名为变体](/docs/zh-CN/sessions#name-your-sessions)。会话仍然可以共享名称，例如当其中一个运行早期版本的 Claude Code 或共享名称是 Claude Code 生成的时。除非此会话连接到 Remote Control，Claude Code 在 `/list-agents` 输出中显示每个本地会话的工作目录，所以当它们在不同目录中运行时，你可以区分同名会话。Claude 以两种方式之一寻址消息，取决于有多少活跃会话响应该名称：163当你重命名会话或启动或恢复交互式会话时，使用这台机器上另一个活跃会话已经使用的名称，Claude Code 将名称留给已经拥有它的会话，并 [将你的重命名为变体](/docs/zh-CN/sessions#name-your-sessions)。会话仍然可以共享名称，例如当其中一个运行早期版本的 Claude Code 或共享名称是 Claude Code 生成的名称时。除非此会话连接到远程控制，Claude Code 在 `/list-agents` 输出中显示每个本地会话的工作目录，所以当它们在不同目录中运行时，你可以区分同名会话。Claude 以两种方式之一寻址消息，取决于有多少活跃会话响应该名称：

164 164

165* **一个会话响应该名称**：Claude Code 仅在名称上传递消息。165* **一个会话响应该名称**：Claude Code 仅在名称上传递消息。

166* **多个会话共享该名称，或 Claude Code 无法检查你的会话运行的所有地方**：Claude 为其列表的每一行添加一个短标识符，并在地址中使用标识符。166* **多个会话共享该名称，或 Claude Code 无法检查你的会话运行的所有地方**：Claude 为其列表的每一行添加一个短标识符，并在地址中使用标识符。

172消息如何传播，以及它是否通过 Anthropic 服务器，取决于目标会话运行的位置：172消息如何传播，以及它是否通过 Anthropic 服务器，取决于目标会话运行的位置：

173 173

174| 其他会话运行的位置 | 消息如何传播 |174| 其他会话运行的位置 | 消息如何传播 |

175| :---------------------------------------------------------- | :------------------------------------------------------------------------ |175| :------------------------------------- | :------------------------------------------------------------------------ |

176| 在这台机器上 | 在 macOS 和 Linux 上通过每个会话的套接字，或在本机 Windows 上通过每个会话的命名管道，永远不通过 Anthropic 服务器 |176| 在这台机器上 | 在 macOS 和 Linux 上通过每个会话的套接字，或在本机 Windows 上通过每个会话的命名管道，永远不通过 Anthropic 服务器 |

177| 在你的另一台机器上 | 通过 Anthropic 服务器，通过该机器的 [Remote Control](/docs/zh-CN/remote-control) 连接到达 |177| 在你的另一台机器上 | 通过 Anthropic 服务器，通过该机器的 [远程控制](/docs/zh-CN/remote-control) 连接到达 |

178| 在 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 上 | 通过 Anthropic 服务器，直接到云会话 |178| 在 [云](/docs/zh-CN/claude-code-on-the-web) 中 | 通过 Anthropic 服务器，直接到云会话 |

179 179

180与你另一台机器上的会话开始对话需要 Claude Code v2.1.225 或更高版本和一个 [出现在列表中](#see-which-sessions-claude-can-reach) 的目标。在 v2.1.225 之前，Claude 只能回复从一个到达的消息。180与你另一台机器上的会话开始对话需要 Claude Code v2.1.225 或更高版本和一个 [出现在列表中](#see-which-sessions-claude-can-reach) 的目标。在 v2.1.225 之前，Claude 只能回复从一个到达的消息。

181 181

182你可以向显示为 `offline` 的会话发送消息，其 [列表](#see-which-sessions-claude-can-reach) 中的一个，其 Remote Control 连接已断开。发送通过，但消息仅在该会话的机器重新连接后到达。Claude 在发送时被告知这一点。182你可以向显示为 [列表](#see-which-sessions-claude-can-reach) 中 `offline` 的会话发送消息，其远程控制连接已断开的会话。发送通过，但消息仅在该会话的机器重新连接后到达。Claude 在发送时被告知这一点。

183 183

184同机器传递在启用该功能的任何地方都有效。每个会话在磁盘上的文件中注册自己。当 Claude 列出或向你的本地会话发送消息时，Claude Code 读取这些文件以找到会话，所以两个会话只有在能看到相同文件时才能相互到达。184同机器传递在启用该功能的任何地方都有效。每个会话在磁盘上的文件中注册自己。当 Claude 列出或向你的本地会话发送消息时，Claude Code 读取这些文件以找到会话，所以两个会话只有在能看到相同文件时才能相互到达。

185 185

186容器有自己的文件系统，所以容器内的会话和主机上的会话无法相互到达。同一容器内的两个会话仍然可以相互发送消息，包括在 [自托管运行器](/docs/zh-CN/self-hosted-environments) 上。WSL 2 内的会话和同一计算机上的本机 Windows 会话也无法相互到达，因为它们在不同的主目录下注册并在不同的套接字类型上侦听。186容器有自己的文件系统，所以容器内的会话和主机上的会话无法相互到达。同一容器内的两个会话仍然可以相互发送消息，包括在 [自托管运行器](/docs/zh-CN/self-hosted-environments) 上。WSL 2 内的会话和同一计算机上的本机 Windows 会话也无法相互到达，因为它们在不同的主目录下注册并在不同的套接字类型上侦听。

187 187

188当此会话连接到 Remote Control 时，当你向你另一台机器上的会话发送消息时，Claude Code 在该会话的对话中显示消息，在此会话的 Remote Control 名称下。该机器上的 Claude 可以回复该名称。例如，当此会话作为 `laptop-graceful-unicorn` 连接到 Remote Control 并且你向你的桌面发送消息时，你在桌面会话中看到消息在 `laptop-graceful-unicorn` 下。188当此会话连接到远程控制时，当你向你另一台机器上的会话发送消息时，Claude Code 在该会话的对话中显示消息，使用此会话的远程控制名称。该机器上的 Claude 可以回复该名称。例如，当此会话作为 `laptop-graceful-unicorn` 连接到远程控制并且你向你的桌面发送消息时，你在桌面会话中看到消息在 `laptop-graceful-unicorn` 下。

189 189

190如果此会话在 Claude 发送到这台机器之外的会话时未连接到 Remote Control，消息仍然通过，但没有 [回复地址](#what-a-message-looks-like)，所以接收 Claude 无法回答它。Claude 在发送时被告知这一点。190如果此会话在 Claude 发送到这台机器之外的会话时未连接到远程控制，消息仍然通过，但没有 [回复地址](#what-a-message-looks-like)，所以接收 Claude 无法回答它。Claude 在发送时被告知这一点。

191 191

192要在任何消息超出此机器之前要求你的批准，请设置 [`isolatePeerMachines`](#require-approval-for-cross-machine-messages)。192要在任何消息超出此机器之前要求你的批准，设置 [`isolatePeerMachines`](#require-approval-for-cross-machine-messages)。

193 193

194<h2 id="how-a-session-treats-an-incoming-message">194<h2 id="how-a-session-treats-an-incoming-message">

195 会话如何处理传入消息195 会话如何处理传入消息

240 240

241除了编辑设置文件，您可以在 `/config` 行**来自您的其他会话的消息**中选择值。Claude Code 将您选择的值写入您的用户设置。该行需要 Claude Code v2.1.232 或更高版本，当托管设置或 `--settings` 标志设置密钥时不出现，因为用户设置值不会应用。Claude Code 拒绝此密钥的 `/config crossSessionInbound=value` 快捷方式。241除了编辑设置文件，您可以在 `/config` 行**来自您的其他会话的消息**中选择值。Claude Code 将您选择的值写入您的用户设置。该行需要 Claude Code v2.1.232 或更高版本，当托管设置或 `--settings` 标志设置密钥时不出现，因为用户设置值不会应用。Claude Code 拒绝此密钥的 `/config crossSessionInbound=value` 快捷方式。

242 242

243要查看哪个值适用，请遵循[设置参考](/docs/zh-CN/settings-reference#crosssessioninbound)中的 `crossSessionInbound` 优先级规则。当没有值适用时，Claude Code 根据两个会话的权限模式按消息决定。它将[绕过权限提示](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)的会话分组为一个类，每个其他会话分组为另一个。Plan Mode 在具有可用绕过权限的会话中计为绕过，[auto](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)、`acceptEdits` 和 `dontAsk` 计为提示：243要查看哪个值适用，请遵循[设置参考](/docs/zh-CN/settings-reference#crosssessioninbound)中的 `crossSessionInbound` 优先级规则。当没有值适用时，Claude Code 根据两个会话的权限模式按消息决定。它将[绕过权限提示](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)的会话分组为一个类，每个其他会话分组为另一个。Plan Mode 在具有可用绕过权限的交互式终端会话中计为绕过，[auto](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)、`acceptEdits` 和 `dontAsk` 计为提示：

244 244

245* **接收会话提示权限**：Claude Code 传递每条消息。它仅当发送会话将自己标识为绕过权限提示时才为您的批准保留一条。245* **接收会话提示权限**：Claude Code 传递每条消息。它仅当发送会话将自己标识为绕过权限提示时才为您的批准保留一条。

246* **接收会话绕过权限提示**：Claude Code 为您的批准保留每条消息。它仅当发送会话也标识为绕过时才传递一条。246* **接收会话绕过权限提示**：Claude Code 为您的批准保留每条消息。它仅当发送会话也标识为绕过时才传递一条。

254* 如果此会话的权限模式类在消息被保留时改变，Claude Code 重新应用入站规则，传递它们现在接受的消息，并显示通知。254* 如果此会话的权限模式类在消息被保留时改变，Claude Code 重新应用入站规则，传递它们现在接受的消息，并显示通知。

255* 如果设置更改在消息被保留时使 `refuse` 适用，Claude Code 删除每条保留的消息并向它可以到达的每个发送者报告拒绝。255* 如果设置更改在消息被保留时使 `refuse` 适用，Claude Code 删除每条保留的消息并向它可以到达的每个发送者报告拒绝。

256 256

257当发送者是同一机器上的交互式会话时，Claude Code 在接收者保留消息时在那里显示通知，以及当接收者稍后传递、拒绝或过期它时的后续通知。如果接收者拒绝它，Claude Code 在那里显示通知，接收者不接受跨会话消息，并告诉发送者的 Claude 不要等待或重新发送。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

261如果接收者拒绝消息，发送者的通知说接收者不接受跨会话消息，并告诉发送者的 Claude 不要等待或重新发送。

258 262

259Claude Code 最多保留 100 条消息，与传递队列分开，超过那个删除最旧的。263Claude Code 最多保留 100 条消息，与传递队列分开，超过那个删除最旧的。

260 264

data-usage.md +19 −19

Details

14 数据训练政策14 数据训练政策

15</h3>15</h3>

16 16

~~17**消费者用户（Free、Pro 和 Max 计划）**：~~17**消费者用户（免费、Pro 和 Max 计划）**：

18我们给您选择是否允许您的数据用于改进未来的 Claude 模型。当此设置打开时，我们将使用来自 Free、Pro 和 Max 账户的数据来训练新模型（包括当您从这些账户使用 Claude Code 时）。18我们让您可以选择是否允许您的数据用于改进未来的 Claude 模型。当此设置打开时，我们将使用来自免费、Pro 和 Max 账户的数据来训练新模型（包括当您从这些账户使用 Claude Code 时）。

19 19

20**商业用户**：（Team 和 Enterprise 计划、API、第三方平台和 Claude Gov）维持现有政策：除非客户选择向我们提供数据以改进模型（例如，[开发者合作伙伴计划](https://support.claude.com/en/articles/11174108-about-the-development-partner-program)），否则 Anthropic 不会使用商业条款下发送到 Claude Code 的代码或提示来训练生成模型。20**商业用户**：（Team 和 Enterprise 计划、API、第三方平台和 Claude Gov）维持现有政策：除非客户选择向我们提供数据以改进模型（例如，[开发者合作伙伴计划](https://support.claude.com/en/articles/11174108-about-the-development-partner-program)），否则 Anthropic 不会使用在商业条款下发送到 Claude Code 的代码或提示来训练生成模型。

21 21

22<h3 id="development-partner-program">22<h3 id="development-partner-program">

23 开发者合作伙伴计划23 开发者合作伙伴计划

24</h3>24</h3>

25 25

26如果您明确选择加入通过[开发者合作伙伴计划](https://support.claude.com/en/articles/11174108-about-the-development-partner-program)等方式向我们提供训练材料的方法，我们可能会使用这些提供的材料来训练我们的模型。组织管理员可以明确选择为其组织加入开发者合作伙伴计划。请注意，此计划仅适用于 Anthropic 第一方 API，不适用于 Amazon Bedrock 或 Google Cloud 的 Agent Platform 用户。26如果您明确选择加入向我们提供材料以进行训练的方法，例如通过[开发者合作伙伴计划](https://support.claude.com/en/articles/11174108-about-the-development-partner-program)，我们可能会使用这些提供的材料来训练我们的模型。组织管理员可以明确选择为其组织加入开发者合作伙伴计划。请注意，此计划仅适用于 Anthropic 第一方 API，不适用于 Amazon Bedrock 或 Google Cloud 的 Agent Platform 用户。

27 27

28<h3 id="feedback-using-the-/feedback-command">28<h3 id="feedback-using-the-/feedback-command">

29 使用 `/feedback` 命令的反馈29 使用 `/feedback` 命令的反馈

30</h3>30</h3>

31 31

32如果您选择使用 `/feedback` 命令向我们发送有关 Claude Code 的反馈，我们可能会使用您的反馈来改进我们的产品和服务。通过 `/feedback` 共享的记录保留 5 年。32如果您选择使用 `/feedback` 命令向我们发送有关 Claude Code 的反馈，我们可能会使用您的反馈来改进我们的产品和服务。通过 `/feedback` 共享的文稿，或通过 `/bug` 和 `/share` 共享的文稿（这些命令通过相同的路径报告），将保留 5 年。

33 33

34通过[Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)，Claude 也可以起草反馈报告并在您的计算机上将其排队供您审查。Claude Code 在您选择发送草稿之前不会发送任何内容，发送的草稿会通过与其他 `/feedback` 报告相同的提交路径和保留期。34使用[Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)，Claude 还可以起草反馈报告并在您的机器上将其排队供您审查。Claude Code 在您选择发送草稿之前不会发送任何内容，发送的草稿会通过与其他 `/feedback` 报告相同的提交路径和保留期。

35 35

36<h3 id="session-quality-surveys">36<h3 id="session-quality-surveys">

37 会话质量调查37 会话质量调查

38</h3>38</h3>

39 39

40当您在 Claude Code 中看到"Claude 在本次会话中表现如何？"提示时，对此调查的回应（包括选择"关闭"）仅记录您的评分。作为此评分提示本身的一部分，我们不收集或存储任何对话记录、输入、输出或其他会话数据。与竖起大拇指/竖起大拇指向下反馈或 `/feedback` 报告不同，此会话质量调查是一个简单的产品满意度指标。40当您在 Claude Code 中看到"Claude 在此会话中表现如何？"提示时，对此调查的响应（包括选择"关闭"）仅记录您的评分。作为评分提示本身的一部分，我们不收集或存储任何对话文稿、输入、输出或其他会话数据。与竖起大拇指/竖起大拇指向下反馈或 `/feedback` 报告不同，此会话质量调查是一个简单的产品满意度指标。

41 41

42在评分提示之后，您可能会看到一个单独的后续问题，询问"Anthropic 可以查看您的会话记录以帮助我们改进 Claude Code 吗？"。这是一个与评分不同的可选第二步：42在评分提示之后，您可能会看到一个单独的后续问题，询问"Anthropic 可以查看您的会话文稿以帮助我们改进 Claude Code 吗？"。这是与评分不同的可选第二步：

43 43

44* **是**：将您的对话记录、任何子代理记录和来自磁盘的原始会话日志文件上传到 Anthropic。已知的 API 密钥和令牌模式在上传前被编辑。源代码、文件内容和其他对话内容按原样上传。共享的记录保留最多 6 个月。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话上，"是"会将相同的有效负载写入 `~/.claude/feedback-bundles/` 下的本地存档，而不是上传；在您转发该文件之前，没有任何内容离开您的计算机。44* **是**：将您的对话文稿、任何子代理文稿和来自磁盘的原始会话日志文件上传到 Anthropic。已知的 API 密钥和令牌模式在上传前被编辑。源代码、文件内容和其他对话内容按原样上传。共享的文稿保留最多 6 个月。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话上，"是"会将相同的有效负载写入 `~/.claude/feedback-bundles/` 下的本地存档，而不是上传；在您转发该文件之前，没有任何内容离开您的机器。

45* **否**：拒绝而不发送任何内容45* **否**：拒绝而不发送任何内容

46* **不再询问**：拒绝并停止此后续在未来会话中出现46* **不再询问**：拒绝并停止此后续在未来会话中出现

47 47

48除非您明确选择**是**，否则不会上传任何内容。具有[零数据保留](/docs/zh-CN/zero-data-retention)的组织，或组织政策禁用产品反馈的组织，或设置了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 的组织，永远不会看到此后续。您对此调查的回应（包括评分提示后提交的会话记录）不会影响您的数据训练偏好，也不能用于训练我们的 AI 模型。48除非您明确选择**是**，否则不会上传任何内容。具有[零数据保留](/docs/zh-CN/zero-data-retention)的组织，或组织政策禁用产品反馈的组织，或设置了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 的组织，永远不会看到此后续。您对此调查的响应（包括评分提示后提交的会话文稿）不会影响您的数据训练偏好，也不能用于训练我们的 AI 模型。

49 49

50要禁用这些调查，请设置 `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1`。当设置 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时，调查也会被禁用。具有阻止非必要流量但通过其自己的 [OpenTelemetry 收集器](/docs/zh-CN/monitoring-usage)捕获调查响应的组织可以通过设置 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL=1` 来选择重新启用调查。然后调查仅将评分记录到配置的收集器。记录共享后续和所有其他 Anthropic 绑定的反馈流量保持禁用。要控制频率而不是禁用，请在您的设置文件中将 [`feedbackSurveyRate`](/docs/zh-CN/settings-reference#feedbacksurveyrate) 设置为 `0` 到 `1` 之间的概率。50要禁用这些调查，请设置 `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY=1`。当设置了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时，调查也会被禁用。通过自己的 [OpenTelemetry 收集器](/docs/zh-CN/monitoring-usage)阻止非必要流量但捕获调查响应的组织可以通过设置 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL=1` 来选择重新启用调查。然后调查仅将评分记录到配置的收集器。文稿共享后续和所有其他 Anthropic 绑定的反馈流量保持禁用。要控制频率而不是禁用，请在您的设置文件中将 [`feedbackSurveyRate`](/docs/zh-CN/settings-reference#feedbacksurveyrate) 设置为 `0` 到 `1` 之间的概率。

51 51

52<h3 id="data-retention">52<h3 id="data-retention">

53 数据保留53 数据保留

55 55

56Anthropic 根据您的账户类型和偏好保留 Claude Code 数据。56Anthropic 根据您的账户类型和偏好保留 Claude Code 数据。

57 57

~~58**消费者用户（Free、Pro 和 Max 计划）**：~~58**消费者用户（免费、Pro 和 Max 计划）**：

59 59

~~60* 允许数据用于模型改进的用户：5 年保留期，以支持模型开发和安全改进~~60* 允许数据用于模型改进的用户：5 年保留期以支持模型开发和安全改进

61* 不允许数据用于模型改进的用户：30 天保留期61* 不允许数据用于模型改进的用户：30 天保留期

62* 隐私设置可以随时在 [claude.ai/settings/data-privacy-controls](https://claude.ai/settings/data-privacy-controls) 更改。62* 隐私设置可以随时在 [claude.ai/settings/data-privacy-controls](https://claude.ai/settings/data-privacy-controls) 更改。

63 63

64**商业用户（Team、Enterprise 和 API）**：64**商业用户（Team、Enterprise 和 API）**：

65 65

66* 标准：30 天保留期66* 标准：30 天保留期

67* [零数据保留](/docs/zh-CN/zero-data-retention)：适用于 Claude for Enterprise 上的 Claude Code。ZDR 不包含在标准 Enterprise 计划中；在您的账户团队确认符合条件后，按组织启用67* [零数据保留](/docs/zh-CN/zero-data-retention)：适用于 Claude for Enterprise 上 Claude Code 的合格账户。ZDR 不包含在标准 Enterprise 计划中；它由您的账户团队在确认符合条件后按组织启用

68* 本地缓存：Claude Code 客户端在 `~/.claude/projects/` 下以纯文本形式本地存储会话记录，默认保留 30 天以启用会话恢复。使用 `cleanupPeriodDays` 调整期限。请参阅[应用程序数据](/docs/zh-CN/claude-directory#application-data)了解存储的内容以及如何清除它。68* 本地缓存：Claude Code 客户端默认在 `~/.claude/projects/` 下以纯文本形式本地存储会话文稿 30 天，以启用会话恢复。使用 `cleanupPeriodDays` 调整该期间。有关存储的内容以及如何清除的信息，请参阅[应用程序数据](/docs/zh-CN/claude-directory#application-data)。

69 69

~~70 在 Claude Desktop 或 Cowork 中启动或最近继续的会话的记录[默认情况下不受该限制](/docs/zh-CN/claude-directory#cleaned-up-automatically)。~~70 在 Claude Desktop 或 Cowork 中启动或最近继续的会话的文稿[默认情况下不受该限制](/docs/zh-CN/claude-directory#cleaned-up-automatically)。

71 71

72您可以随时删除网络上的单个 Claude Code 会话。删除会话会永久删除该会话的事件数据。有关如何删除会话的说明，请参阅[删除会话](/docs/zh-CN/claude-code-on-the-web#delete-sessions)。72您可以随时删除单个云会话。删除会话会永久删除该会话的事件数据。有关如何删除会话的说明，请参阅[删除会话](/docs/zh-CN/claude-code-on-the-web#delete-sessions)。

73 73

~~74在我们的[隐私中心](https://privacy.anthropic.com/)了解更多关于数据保留实践的信息。~~74在我们的[隐私中心](https://privacy.anthropic.com/)了解有关数据保留实践的更多信息。

75 75

76有关完整详情，请查看我们的[商业服务条款](https://www.anthropic.com/legal/commercial-terms)（适用于 Team、Enterprise 和 API 用户）或[消费者条款](https://www.anthropic.com/legal/consumer-terms)（适用于 Free、Pro 和 Max 用户）和[隐私政策](https://www.anthropic.com/legal/privacy)。76有关完整详情，请查看我们的[商业服务条款](https://www.anthropic.com/legal/commercial-terms)（适用于 Team、Enterprise 和 API 用户）或[消费者条款](https://www.anthropic.com/legal/consumer-terms)（适用于免费、Pro 和 Max 用户）和[隐私政策](https://www.anthropic.com/legal/privacy)。

77 77

78<h2 id="data-access">78<h2 id="data-access">

79 数据访问79 数据访问

debug-your-config.md +2 −2

Details

105大多数配置意外可以追溯到一小组位置和语法规则。在假设存在错误之前检查这些：105大多数配置意外可以追溯到一小组位置和语法规则。在假设存在错误之前检查这些：

106 106

107| 症状 | 原因 | 修复 |107| 症状 | 原因 | 修复 |

108| :-------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |108| :-------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |

116| Skill 出现在 `/skills` 中但 Claude 从不调用它 | Skill 在其 frontmatter 中有 `disable-model-invocation: true`，或其描述与你表述请求的方式不匹配 | 检查 `/skills` 中的徽章：一个"user-only"标签意味着 Claude 不会自动触发它。请参阅[skill 调用](/docs/zh-CN/skills)。 |116| Skill 出现在 `/skills` 中但 Claude 从不调用它 | Skill 在其 frontmatter 中有 `disable-model-invocation: true`，或其描述与你表述请求的方式不匹配 | 检查 `/skills` 中的徽章：一个"user-only"标签意味着 Claude 不会自动触发它。请参阅[skill 调用](/docs/zh-CN/skills)。 |

117| 子目录 `CLAUDE.md` 指令似乎被忽略 | 子目录文件按需加载，而不是在会话开始时加载 | 它们在 Claude 使用 Read 工具读取该目录中的文件时加载，而不是在启动时，也不是在写入或创建文件时。请参阅[CLAUDE.md 文件如何加载](/docs/zh-CN/memory#how-claude-md-files-load)。 |117| 子目录 `CLAUDE.md` 指令似乎被忽略 | 子目录文件按需加载，而不是在会话开始时加载 | 它们在 Claude 使用 Read 工具读取该目录中的文件时加载，而不是在启动时，也不是在写入或创建文件时。请参阅[CLAUDE.md 文件如何加载](/docs/zh-CN/memory#how-claude-md-files-load)。 |

118| 子代理忽略 `CLAUDE.md` 指令 | 内置的 Explore 和 Plan 代理跳过 `CLAUDE.md`。自定义子代理以与主对话相同的方式加载它 | 对于 Explore 或 Plan，在你的委派提示中重新陈述指令。对于自定义子代理，将关键指令放在代理文件体中，它成为代理的系统提示。请参阅[启动时加载的内容](/docs/zh-CN/sub-agents#what-loads-at-startup)。 |118| 子代理忽略 `CLAUDE.md` 指令 | 内置的 Explore 和 Plan 代理跳过 `CLAUDE.md`。自定义子代理以与主对话相同的方式加载它，除非其定义设置了 [`omitClaudeMd`](/docs/zh-CN/sub-agents#supported-frontmatter-fields) | 对于 Explore 或 Plan，在你的委派提示中重新陈述指令。对于设置 `omitClaudeMd` 的子代理，删除该字段。对于任何其他自定义子代理，将关键指令放在代理文件体中，它成为代理的系统提示。请参阅[启动时加载的内容](/docs/zh-CN/sub-agents#what-loads-at-startup)。 |

120| `.mcp.json` 中的 MCP 服务器永远不加载 | 文件在 `.claude/` 下，或其服务器位于顶级 `servers` 键下，如 VS Code 的 `mcp.json` 中那样，而不是 `mcpServers` | 项目 MCP 配置在存储库根目录下作为 `.mcp.json`，而不是在 `.claude/` 内，服务器位于 `mcpServers` 键下。请参阅[MCP 配置](/docs/zh-CN/mcp)。 |120| `.mcp.json` 中的 MCP 服务器永远不加载 | 文件在 `.claude/` 下，或其服务器位于顶级 `servers` 键下，如 VS Code 的 `mcp.json` 中那样，而不是 `mcpServers` | 项目 MCP 配置在存储库根目录下作为 `.mcp.json`，而不是在 `.claude/` 内，服务器位于 `mcpServers` 键下。请参阅[MCP 配置](/docs/zh-CN/mcp)。 |

121| 在 `settings.json` 中的 `mcpServers` 下添加的 MCP 服务器永远不出现 | `settings.json` 不读取 `mcpServers` 键 | 在存储库根目录的 `.mcp.json` 中定义项目服务器，或运行 `claude mcp add --scope user` 来添加用户范围的服务器。请参阅[MCP 配置](/docs/zh-CN/mcp)。 |121| 在 `settings.json` 中的 `mcpServers` 下添加的 MCP 服务器永远不出现 | `settings.json` 不读取 `mcpServers` 键 | 在存储库根目录的 `.mcp.json` 中定义项目服务器，或运行 `claude mcp add --scope user` 来添加用户范围的服务器。请参阅[MCP 配置](/docs/zh-CN/mcp)。 |

desktop.md +242 −118

Details

9Claude Desktop 应用有三个选项卡：**Chat** 用于对话，**Cowork** 用于 [Dispatch 和更长的代理工作](https://claude.com/product/cowork)，**Code** 用于软件开发。本页是 Code 选项卡的参考。9Claude Desktop 应用有三个选项卡：**Chat** 用于对话，**Cowork** 用于 [Dispatch 和更长的代理工作](https://claude.com/product/cowork)，**Code** 用于软件开发。本页是 Code 选项卡的参考。

10 10

11<CardGroup cols={3}>11<CardGroup cols={3}>

~~12 <Card title="Download for 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">

~~13 Universal build for Intel and Apple Silicon~~13 适用于 Intel 和 Apple Silicon 的通用版本

14 </Card>14 </Card>

15 15

~~16 <Card title="Download for Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code&utm_medium=docs">~~16 <Card title="下载 Windows 版本" icon="windows" href="https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code&utm_medium=docs">

~~17 For x64 processors~~17 适用于 x64 处理器

18 </Card>18 </Card>

19 19

~~20 <Card title="Get Claude for Linux (beta)" icon="linux" href="/docs/en/desktop-linux">~~20 <Card title="获取 Claude for Linux（测试版）" icon="linux" href="/docs/zh-CN/desktop-linux">

~~21 apt or .deb for Ubuntu and Debian~~21 Ubuntu 和 Debian 的 apt 或 .deb

22 </Card>22 </Card>

23</CardGroup>23</CardGroup>

24 24

25For Windows ARM64, download the [ARM64 installer](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs). On Linux, install with apt; see [Claude Desktop on Linux](/docs/en/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安装后，启动 Claude，登录，然后点击 **Code** 选项卡。第一次在 Windows 上打开它时，你需要安装 [Git for Windows](https://git-scm.com/downloads/win)；安装后重启应用。有关首次会话的演练，请参阅[快速开始指南](/docs/zh-CN/desktop-quickstart)。27安装后，启动 Claude，登录，然后点击 **Code** 选项卡。有关首次会话的演练，请参阅[快速开始指南](/docs/zh-CN/desktop-quickstart)。

28 28

29在 Code 选项卡中，每个对话都是一个**会话**：它有自己的聊天历史、项目文件夹和代码更改，独立于任何其他会话。侧边栏列出你的会话，让你可以并行运行多个会话。在一个会话中，你可以：29在 Code 选项卡中，每个对话都是一个**会话**：它有自己的聊天历史和项目文件夹，独立于任何其他会话。侧边栏列出你的会话，让你可以并行运行多个会话。在一个会话中，你可以：

30 30

31* [使用 diff 视图审查和评论更改](#review-changes-with-diff-view)，然后[通过 CI 监控生成的 PR](#monitor-pull-request-status)31* [使用 diff 视图审查和评论更改](#review-changes-with-diff-view)，然后[通过 CI 监控生成的 PR](#monitor-pull-request-status)

32* [在浏览器窗格中预览你的运行应用](#preview-your-app)，同时 Claude 验证自己的更改，并[在其旁边打开外部网站](#browse-external-sites)32* [在浏览器窗格中预览你的运行应用](#preview-your-app)，同时 Claude 验证自己的更改，并[在其旁边打开外部网站](#browse-external-sites)

33* 在 iOS Simulator 窗格中[观看 Claude 运行和测试你的 iOS 应用](/docs/zh-CN/desktop-ios-simulator)

33* [整理窗格](#arrange-your-workspace)，将聊天、diff、浏览器、终端和文件编辑器并排放置34* [整理窗格](#arrange-your-workspace)，将聊天、diff、浏览器、终端和文件编辑器并排放置

34* 提出[侧边问题](#ask-a-side-question-without-derailing-the-session)，使用会话的上下文而不偏离主线35* 提出[侧边问题](#ask-a-side-question-without-derailing-the-session)，使用会话的上下文而不偏离主线

36* 让 Claude [检查、消息或存档你的其他会话](#work-across-sessions)

35* [连接外部工具](#connect-external-tools)，如 GitHub、Slack 和 Linear37* [连接外部工具](#connect-external-tools)，如 GitHub、Slack 和 Linear

36* 让 Claude [打开应用和控制你的屏幕](#let-claude-use-your-computer)38* 让 Claude [打开应用和控制你的屏幕](#let-claude-use-your-computer)

~~37* 在你的机器上、[云中](#run-long-running-tasks-remotely)或通过 [SSH](#ssh-sessions) 运行~~39* 在你的机器上、[云中](#run-long-running-tasks-in-the-cloud)或通过 [SSH](#ssh-sessions) 运行

38 40

39有关[计划的定期工作](/docs/zh-CN/desktop-scheduled-tasks)、[快捷键](#keyboard-shortcuts)或[从手机发送任务](#sessions-from-dispatch)，请参阅链接的页面和部分。如果你已经使用基于终端的 CLI，请参阅 [CLI 比较](#coming-from-the-cli)了解哪些内容可以继续使用。41有关[计划的定期工作](/docs/zh-CN/desktop-scheduled-tasks)、[快捷键](#keyboard-shortcuts)或[从手机发送任务](#sessions-from-dispatch)，请参阅链接的页面和部分。如果你已经使用基于终端的 CLI，请参阅 [CLI 比较](#coming-from-the-cli)了解哪些内容可以继续使用。

40 42

44 46

45在发送第一条消息之前，在提示区域配置四件事：47在发送第一条消息之前，在提示区域配置四件事：

46 48

47* **环境**：选择 Claude 运行的位置。选择 **Local** 用于你的机器，**Remote** 用于 Anthropic 托管的云会话，[**SSH 连接**](#ssh-sessions)用于你管理的远程机器，或在 Windows 上选择 [**WSL 发行版**](/docs/zh-CN/desktop-wsl)。请参阅[环境配置](#environment-configuration)。49* **环境**：选择 Claude 运行的位置。选择 **Local** 用于你的机器，**Cloud** 用于[云会话](#cloud-sessions)，该会话在你关闭应用后继续运行，[**SSH 连接**](#ssh-sessions)用于你管理的远程机器，或在 Windows 上选择 [**WSL 发行版**](/docs/zh-CN/desktop-wsl)。请参阅[环境配置](#environment-configuration)。

~~48* **项目文件夹**：选择 Claude 工作的文件夹或存储库。对于远程会话，你可以添加[多个存储库](#run-long-running-tasks-remotely)。~~50* **项目文件夹**：选择 Claude 工作的文件夹或存储库。对于云会话，你可以添加[多个存储库](#run-long-running-tasks-in-the-cloud)。

49* **模型**：从发送按钮旁的下拉菜单中选择一个[模型](/docs/zh-CN/model-config#available-models)。你可以在会话期间更改此设置。51* **模型**：从发送按钮旁的下拉菜单中选择一个[模型](/docs/zh-CN/model-config#available-models)。你可以在会话期间更改此设置。

50* **权限模式**：从[模式选择器](#choose-a-permission-mode)中选择 Claude 拥有多少自主权。你可以在会话期间更改此设置。52* **权限模式**：从[模式选择器](#choose-a-permission-mode)中选择 Claude 拥有多少自主权。你可以在会话期间更改此设置。

51 53

55 使用代码57 使用代码

56</h2>58</h2>

57 59

~~58为 Claude 提供正确的上下文，控制它自己做多少工作，并审查它更改的内容。~~60为 Claude 提供正确的上下文，控制它自主执行的工作量，并审查它所做的更改。

59 61

60<h3 id="use-the-prompt-box">62<h3 id="use-the-prompt-box">

61 使用提示框63 使用提示框

62</h3>64</h3>

63 65

64输入你想让 Claude 做的事情并按 **Enter** 发送。Claude 读取你的项目文件，进行更改，并根据你的[权限模式](#choose-a-permission-mode)运行命令。你可以随时重定向 Claude：点击停止按钮立即中断，或输入更正并按 **Enter** 发送，无需停止正在运行的操作。Claude 在当前操作完成后立即读取更正，并在下一步之前进行调整。66输入你想让 Claude 做的事情，然后按 **Enter** 发送。Claude 会读取你的项目文件，进行更改，并根据你的[权限模式](#choose-a-permission-mode)运行命令。你可以随时重定向 Claude：点击停止按钮立即中断，或输入更正并按 **Enter** 发送，无需停止正在运行的操作。Claude 会在当前操作完成后立即读取更正，并在下一步之前进行调整。

65 67

~~66提示框旁的 **+** 按钮让你可以访问文件附件、[skills](#use-skills)、[连接器](#connect-external-tools) 和[插件](#install-plugins)。~~68提示框旁边的 **+** 按钮让你可以访问文件附件、[skills](#use-skills)、[connectors](#connect-external-tools) 和 [plugins](#install-plugins)。

67 69

68<h3 id="add-files-and-context-to-prompts">70<h3 id="add-files-and-context-to-prompts">

69 向提示添加文件和上下文71 向提示添加文件和上下文

71 73

72提示框支持两种方式来引入外部上下文：74提示框支持两种方式来引入外部上下文：

73 75

~~74* **@mention 文件**：输入 `@` 后跟文件名，将文件添加到对话上下文。Claude 然后可以读取和引用该文件。@mention 在云会话和 WSL 会话中不可用。~~76* **@mention 文件**：输入 `@` 后跟文件名，将文件添加到对话上下文。Claude 随后可以读取和引用该文件。@mention 在云或 WSL 会话中不可用。

75* **附加文件**：使用附件按钮将图像、PDF 和其他文件附加到你的提示，或直接将文件拖放到提示中。这对于共享错误的屏幕截图、设计模型或参考文档很有用。77* **附加文件**：使用附件按钮将图像、PDF 和其他文件附加到你的提示，或直接将文件拖放到提示中。这对于共享错误的屏幕截图、设计模型或参考文档很有用。

76 78

77<h3 id="choose-a-permission-mode">79<h3 id="choose-a-permission-mode">

78 选择权限模式80 选择权限模式

79</h3>81</h3>

80 82

81权限模式控制 Claude 在会话期间拥有多少自主权：它是否在编辑文件、运行命令或两者之前询问。你可以随时使用发送按钮旁的模式选择器切换模式。从 Manual 开始以准确查看 Claude 的操作，然后随着你变得更舒适，转移到 Accept edits 或 Plan。83权限模式控制 Claude 在会话期间的自主程度：它是否在编辑文件、运行命令或两者之前询问。你可以随时使用发送按钮旁边的模式选择器切换权限模式。要自己批准每项更改，请切换到 Manual。

82 84

83要为新的本地会话设置默认模式，请将 `permissions.defaultMode` 添加到你的[设置文件](/docs/zh-CN/settings#settings-files)。桌面应用读取与 CLI 相同的设置文件。你在选择器中选择的模式会被记住，每个文件夹都会优先于 `defaultMode`，除了 Plan，它仅适用于当前会话。85要为新的本地会话设置默认模式，请将 `permissions.defaultMode` 添加到你的[设置文件](/docs/zh-CN/settings#where-settings-live)。桌面应用读取与 CLI 相同的设置文件。你在选择器中选择的模式会被记住（按文件夹），并对该文件夹优先于 `defaultMode`，除了 Plan，它仅适用于当前会话。

84 86

85| 模式 | 设置键 | 行为 |87| 模式 | 设置键 | 行为 |

86| ---------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |88| ---------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

91| **Bypass permissions** | `bypassPermissions` | Claude 运行时没有权限提示，除了由显式[询问规则](/docs/zh-CN/permissions#manage-permissions)强制的权限提示、连接器工具[你的组织设置为 `ask`](/docs/zh-CN/mcp#organization-controls-on-connector-tools)、标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具，或当 Claude [在外部网站上操作](#browse-external-sites)时由安全分类器强制的权限提示；等同于 CLI 中的 `--dangerously-skip-permissions`。在 Pro 和 Max 计划上，在你的设置 → Claude Code 中的"允许绕过权限模式"下启用；在 Team 和 Enterprise 计划上没有设置切换，组织政策控制它。仅在沙箱容器或虚拟机中使用。 |93| **Bypass permissions** | `bypassPermissions` | Claude 运行时不需要权限提示，除了[任何模式都不会自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)、当 Claude [在外部网站上操作](#browse-external-sites)时的安全分类器，或桌面操作（Claude 总是首先询问），例如[归档会话](#work-across-sessions)。等同于 CLI 中的 `--dangerously-skip-permissions`。在 Pro 和 Max 计划上，在你的设置 → Claude Code 中启用它，在"允许绕过权限模式"下；在 Team 和 Enterprise 计划上没有设置切换，组织策略控制它。仅在沙箱容器或虚拟机中使用。 |

92 94

93代码选项卡的早期版本将这些模式标记为 Ask permissions、Auto accept edits 和 Plan mode。95代码选项卡的早期版本将这些模式标记为 Ask permissions、Auto accept edits 和 Plan mode。

94 96

96 98

97<span id="auto-mode-availability" />99<span id="auto-mode-availability" />

98 100

99Auto mode 在 Anthropic API 上对所有用户可用，需要 Claude Opus 4.6 或更高版本，或 Sonnet 4.6 或更高版本。在路由到 Google Cloud 的 Agent Platform 的企业部署中，auto mode [默认可用](/docs/zh-CN/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)，仅支持 Claude Sonnet 5、Opus 4.7 和 Opus 4.8。在 Claude Code v2.1.207 之前，Google Cloud 的 Agent Platform 上的企业部署必须设置 `CLAUDE_CODE_ENABLE_AUTO_MODE` 来启用 auto mode。101Auto mode 对 Anthropic API 上的所有用户可用，需要 Claude Opus 4.6 或更高版本、Sonnet 4.6 或更高版本，或 [Fable model](/docs/zh-CN/model-config#work-with-fable)。组织管理员可以使用[托管设置](#managed-settings)中的 `disableAutoMode` 键关闭 auto mode。

102

103在路由 Desktop 到 Google Cloud 的 Agent Platform 的 Enterprise 部署中，auto mode 也默认可用；有关支持的模型，请参阅 [Auto mode on Bedrock, Agent Platform, or Foundry](/docs/zh-CN/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)。

100 104

101<Tip title="最佳实践">105<Tip title="最佳实践">

102 在 Plan 中启动复杂任务，以便 Claude 在进行更改之前制定方法。一旦你批准计划，切换到 Accept edits 或 Manual 来执行它。有关此工作流的更多信息，请参阅[先探索，然后计划，然后编码](/docs/zh-CN/best-practices#explore-first-then-plan-then-code)。106 在 Plan 中开始复杂任务，以便 Claude 在进行更改之前制定方法。一旦你批准计划，切换到 Accept edits 或 Manual 来执行它。有关此工作流的更多信息，请参阅[先探索，然后计划，然后编码](/docs/zh-CN/best-practices#explore-first-then-plan-then-code)。

103</Tip>107</Tip>

104 108

105云会话支持 Accept edits、Plan 和 Auto。Accept edits 对应于 `default` 模式：云会话预先批准文件编辑，所以选择器显示 Accept edits 而不是 Manual。Bypass permissions 不可用，因为云环境已经是沙箱化的。109云会话支持 Accept edits、Plan 和 Auto。Accept edits 对应于 `default` 模式：云会话预先批准文件编辑，因此选择器显示 Accept edits 而不是 Manual。Bypass permissions 在云会话中不可用，包括[自托管环境](/docs/zh-CN/self-hosted-environments)中的会话。

106 110

107企业管理员可以限制哪些权限模式可用。有关详细信息，请参阅[企业配置](#enterprise-configuration)。111Enterprise 管理员可以限制哪些权限模式可用。有关详细信息，请参阅[企业配置](#enterprise-configuration)。

108 112

109<h3 id="preview-your-app">113<h3 id="preview-your-app">

110 预览你的应用114 预览你的应用

111</h3>115</h3>

112 116

113Claude 可以启动开发服务器并在浏览器窗格中打开它来验证其更改。这适用于前端 Web 应用以及后端服务器：Claude 可以测试 API 端点、查看服务器日志并迭代它发现的问题。在大多数情况下，Claude 在编辑项目文件后自动启动服务器。你也可以随时要求 Claude 预览。默认情况下，Claude [自动验证](#auto-verify-changes)每次编辑后的更改。117Claude 可以启动开发服务器并在浏览器窗格中打开它以验证其更改。这适用于前端 Web 应用以及后端服务器：Claude 可以测试 API 端点、查看服务器日志，并迭代它发现的问题。在大多数情况下，Claude 在编辑项目文件后自动启动服务器。你也可以随时要求 Claude 进行预览。默认情况下，Claude [自动验证](#auto-verify-changes)每次编辑后的更改。

114 118

115浏览器窗格也可以打开项目中的静态 HTML 文件、PDF、图像和视频。点击聊天中的 HTML、PDF、图像或视频路径在那里打开它。119浏览器窗格也可以打开项目中的静态 HTML 文件、PDF、图像和视频。在聊天中点击 HTML、PDF、图像或视频路径以在那里打开它。

116 120

117从浏览器窗格，你可以：121从浏览器窗格，你可以：

118 122

119* 在浏览器窗格中直接与你运行的应用交互123* 直接在浏览器窗格中与运行的应用交互

120* 观看 Claude 自动验证其自己的更改：它拍摄屏幕截图、检查 DOM、点击元素、填充表单并修复它发现的问题124* 观看 Claude 自动验证其自己的更改：它拍摄屏幕截图、检查 DOM、点击元素、填充表单，并修复它发现的问题

121* 从会话工具栏中的服务器下拉菜单启动或停止服务器125* 从会话工具栏中的服务器下拉菜单启动或停止服务器

122* 通过在下拉菜单中选择 **Persist sessions** 来在服务器重启时保持 cookie 和本地存储，这样你就不必在开发期间重新登录126* 通过在下拉菜单中选择**持久化会话**来在服务器重启后保持 cookie 和本地存储，这样你就不必在开发期间重新登录

123* 编辑服务器配置或一次停止所有服务器127* 编辑服务器配置或一次停止所有服务器

124 128

125Claude 根据你的项目创建初始服务器配置。如果你的应用使用自定义开发命令，编辑 `.claude/launch.json` 以匹配你的设置。有关完整参考，请参阅[配置预览服务器](#configure-preview-servers)。129Claude 根据你的项目创建初始服务器配置。如果你的应用使用自定义开发命令，编辑 `.claude/launch.json` 以匹配你的设置。有关完整参考，请参阅[配置预览服务器](#configure-preview-servers)。

126 130

127要清除保存的会话数据，或完全关闭浏览器，请使用设置 → Claude Code 中的切换开关。131要清除保存的会话数据，或完全关闭浏览器，请使用设置 → Claude Code 中的切换。

128 132

129<h3 id="browse-external-sites">133<h3 id="browse-external-sites">

130 浏览外部网站134 浏览外部网站

131</h3>135</h3>

132 136

133浏览器窗格是一个选项卡式浏览器，所以你可以在你运行的应用旁边打开文档、问题跟踪器或任何其他网站。要打开浏览器，在 macOS 上按 **Cmd+Shift+B** 或在 Windows 上按 **Ctrl+Shift+B**，或从 **Views** 菜单中选择它。当你点击聊天中的外部链接时，一个选择器提供 **Open in app** 来使用浏览器窗格或 **Default browser** 来使用你自己的；在 macOS 上 **Cmd** 点击或在 Windows 上 **Ctrl** 点击直接在你的系统浏览器中打开链接。你可以登录窗格中的网站，包括弹出式登录流程，如 Google OAuth。137浏览器窗格是一个选项卡式浏览器，因此你可以在运行应用旁边打开文档、问题跟踪器或任何其他网站。要打开浏览器，在 macOS 上按 **Cmd+Shift+B** 或在 Windows 上按 **Ctrl+Shift+B**，或从**视图**菜单中选择它。当你点击聊天中的外部链接时，选择器会提供**在应用中打开**以使用浏览器窗格或**默认浏览器**以使用你自己的；在 macOS 上 **Cmd** 点击或在 Windows 上 **Ctrl** 点击直接在你的系统浏览器中打开链接。你可以登录窗格中的网站，包括弹出式登录流，例如 Google OAuth。

134 138

135Claude 可以使用与[验证你的应用](#preview-your-app)相同的工具来读取和交互外部页面，并有两个额外的安全检查：139Claude 可以使用与[验证你的应用](#preview-your-app)相同的工具读取和交互外部页面，并进行两项额外的安全检查：

136 140

137* 安全分类器在每个权限模式中审查 Claude 在外部页面上的写入操作，如点击和输入。这些是与[自动模式](#choose-a-permission-mode)相同的分类器，当它们标记一个操作时，你会获得一个权限提示，无论模式如何。141* 安全分类器在每个权限模式中审查 Claude 在外部页面上的写入操作，例如点击和输入。这些与 [auto mode](#choose-a-permission-mode) 使用的分类器相同，当它们标记操作时，无论模式如何，你都会获得权限提示。

138* 在除 Auto 和 Bypass permissions 之外的权限模式中，在 Claude 导航到新网站之前，域名允许列表检查也适用。142* 在 Auto 和 Bypass permissions 以外的权限模式中，在 Claude 导航到新网站之前也会应用域名允许列表检查。

139 143

140<h4 id="approve-claude’s-actions-on-a-site">144<h4 id="approve-claude’s-actions-on-a-site">

141 批准 Claude 在网站上的操作145 批准 Claude 在网站上的操作

142</h4>146</h4>

143 147

144Claude 第一次在外部网站上操作时，会出现一个权限卡，Claude 等待你的选择：**Allow once**、**Always allow** 或 **Deny**。**Allow once** 批准操作而不保存任何内容。**Always allow** 在你的设备上保存该网站的批准，你可以在设置中撤销它。每个网站都需要自己的批准，包括子域。你的本地开发服务器和项目文件不需要批准，所以[自动验证](#auto-verify-changes)继续工作而不提示。148Claude 第一次在外部网站上操作时，会出现权限卡，Claude 等待你的选择：**允许一次**、**始终允许**或**拒绝**。**允许一次**批准操作而不保存任何内容。**始终允许**在你的设备上保存该网站的批准，你可以在设置中撤销它。每个网站都需要自己的批准，包括子域。你的本地开发服务器和项目文件不需要批准，因此[自动验证](#auto-verify-changes)继续工作而不需要提示。

145 149

146即使在批准的网站上，Claude 也不会在没有你的输入的情况下购买物品、创建账户或绕过 CAPTCHA。在浏览器窗格中浏览使用与 [Chrome 中的 Claude 扩展](/docs/zh-CN/chrome)相同的安全模型。有关 Claude 如何处理敏感网站和风险操作的信息，请参阅[安全使用 Chrome 中的 Claude](https://support.claude.com/en/articles/12902428-using-claude-in-chrome-safely)。150即使在批准的网站上，Claude 也不会在没有你的输入的情况下购买物品、创建账户或绕过 CAPTCHA。在浏览器窗格中浏览使用与 [Claude in Chrome extension](/docs/zh-CN/chrome) 相同的安全模型。有关 Claude 如何处理敏感网站和风险操作的信息，请参阅[安全使用 Chrome 中的 Claude](https://support.claude.com/en/articles/12902428-using-claude-in-chrome-safely)。

147 151

148<h4 id="choose-between-the-browser-and-the-chrome-extension">152<h4 id="choose-between-the-browser-and-the-chrome-extension">

149 在浏览器和 Chrome 扩展之间选择153 在浏览器和 Chrome 扩展之间选择

150</h4>154</h4>

151 155

152浏览器窗格使用干净的浏览器配置文件，与你的个人浏览器分开，没有你保存的登录或历史记录。使用它来构建和测试你的应用以及不需要你的身份的网站。当你想让 Claude 在你的登录会话中充当你时，改用 [Chrome 中的 Claude 扩展](/docs/zh-CN/chrome)，它共享你的浏览器的登录状态。156浏览器窗格使用干净的浏览器配置文件，与你的个人浏览器分开，没有你保存的登录或历史记录。将其用于构建和测试你的应用以及不需要你的身份的网站。当你想让 Claude 在你的登录会话中充当你时，请改用 [Claude in Chrome extension](/docs/zh-CN/chrome)，它共享你的浏览器的登录状态。

153 157

154<h4 id="restrict-external-browsing-for-your-organization">158<h4 id="restrict-external-browsing-for-your-organization">

155 限制你的组织的外部浏览159 为你的组织限制外部浏览

156</h4>160</h4>

157 161

158浏览器遵循与 [Chrome 中的 Claude 扩展](https://support.claude.com/en/articles/13065128-claude-in-chrome-admin-controls)相同的[网站允许列表和阻止列表控制](https://support.claude.com/en/articles/13065128-claude-in-chrome-admin-controls)。如果你的组织已经为扩展配置了这些列表，浏览器会自动尊重它们。管理员也可以使用 [`browserExternalPageTools` 托管设置](#managed-settings)关闭 Claude 在外部页面上的工具。禁用工具后，用户仍然可以导航到外部网站；Claude 的工具无法读取或对其进行操作。162浏览器遵循与 Claude in Chrome 扩展相同的[网站允许列表和阻止列表控制](https://support.claude.com/en/articles/13065128-claude-in-chrome-admin-controls)。如果你的组织已经为扩展配置了这些列表，浏览器会自动尊重它们。管理员也可以使用 [`browserExternalPageTools` 托管设置](#managed-settings)关闭 Claude 在外部页面上的工具。禁用工具后，用户仍然可以导航到外部网站；Claude 的工具无法读取或操作它们。

159 163

160要完全关闭外部浏览，请将 [`disableBrowserExternalNavigation` 托管设置](#managed-settings)设置为 `true`。这会阻止浏览器中的所有外部导航，包括你的组织允许列表上的网站；localhost 开发服务器和文件预览继续工作。使用 `browserExternalPageTools` 让用户继续浏览外部网站而不使用 Claude 的工具，使用 `disableBrowserExternalNavigation` 为用户和 Claude 阻止外部网站。164要完全关闭外部浏览，请将 [`disableBrowserExternalNavigation` 托管设置](#managed-settings)设置为 `true`。这会阻止浏览器中的所有外部导航，包括你的组织允许列表上的网站；localhost 开发服务器和文件预览继续工作。使用 `browserExternalPageTools` 让用户继续浏览外部网站而不使用 Claude 的工具，使用 `disableBrowserExternalNavigation` 为用户和 Claude 阻止外部网站。

161 165

162<h3 id="review-changes-with-diff-view">166<h3 id="review-changes-with-diff-view">

163 使用 diff 视图审查更改167 使用差异视图审查更改

164</h3>168</h3>

165 169

166Claude 对你的代码进行更改后，diff 视图让你在创建拉取请求之前逐个文件审查修改。170Claude 对你的代码进行更改后，差异视图让你在创建拉取请求之前逐个文件审查修改。

167 171

168当 Claude 更改文件时，会出现一个 diff 统计指示器，显示添加和删除的行数，例如 `+12 -1`。点击此指示器打开 diff 查看器，它在左侧显示文件列表，在右侧显示每个文件的更改。172当 Claude 更改文件时，会出现一个差异统计指示器，显示添加和删除的行数，例如 `+12 -1`。点击此指示器打开差异查看器，它在左侧显示文件列表，在右侧显示每个文件的更改。

169 173

170要对特定行进行注释，点击 diff 中的任何行以打开注释框。输入你的反馈并按 **Enter** 添加注释。在多行添加注释后，一次提交所有注释：174要对特定行进行评论，点击差异中的任何行以打开评论框。输入你的反馈并按 **Enter** 添加评论。在多行添加评论后，一次提交所有评论：

171 175

172* **macOS**：按 **Cmd+Enter**176* **macOS**：按 **Cmd+Enter**

173* **Windows**：按 **Ctrl+Enter**177* **Windows**：按 **Ctrl+Enter**

174 178

175Claude 读取你的注释并进行请求的更改，这些更改显示为你可以审查的新 diff。179Claude 读取你的评论并进行请求的更改，这些更改显示为你可以审查的新差异。

176 180

177<h3 id="review-your-code">181<h3 id="review-your-code">

178 审查你的代码182 审查你的代码

179</h3>183</h3>

180 184

181在 diff 视图中，点击右上角工具栏中的 **Review code** 来要求 Claude 在你提交之前评估更改。Claude 检查当前 diff 并直接在 diff 视图中留下注释。你可以回复任何注释或要求 Claude 修改。185在差异视图中，点击右上角工具栏中的**审查代码**以要求 Claude 在你提交之前评估更改。Claude 检查当前差异并直接在差异视图中留下评论。你可以回应任何评论或要求 Claude 修订。

182 186

183审查侧重于高信号问题：编译错误、明确的逻辑错误、安全漏洞和明显的错误。它不标记样式、格式、预先存在的问题或 linter 会捕获的任何内容。187审查侧重于高信号问题：编译错误、明确的逻辑错误、安全漏洞和明显的错误。它不会标记样式、格式、预先存在的问题或 linter 会捕获的任何内容。

184 188

185<h3 id="monitor-pull-request-status">189<h3 id="monitor-pull-request-status">

186 监控拉取请求状态190 监控拉取请求状态

187</h3>191</h3>

188 192

189打开拉取请求后，CI 状态栏出现在会话中。Claude Code 使用 GitHub CLI 轮询检查结果并显示失败。193打开拉取请求后，CI 状态栏会出现在会话中。Claude Code 使用 GitHub CLI 轮询检查结果并显示失败。

190 194

191* **Auto-fix**：启用后，Claude 通过读取失败输出并迭代来自动尝试修复失败的 CI 检查。195* **自动修复**：启用后，Claude 会通过读取失败输出并迭代来自动尝试修复失败的 CI 检查。

192* **Auto-merge**：启用后，Claude 在所有检查通过后合并 PR。合并方法是压缩。Auto-merge 必须在你的 GitHub 存储库设置中[启用](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository)才能工作。196* **自动合并**：启用后，Claude 在所有检查通过后合并 PR。合并方法是压缩。首先在你的 [GitHub 存储库设置](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository)中启用自动合并；没有它，Claude 无法合并 PR。

193 197

194使用 CI 状态栏中的 **Auto-fix** 和 **Auto-merge** 切换来启用任一选项。Claude Code 还在 CI 完成时发送桌面通知。要在 PR 合并或关闭后自动存档会话，在设置 → Claude Code 中打开[自动存档](#work-in-parallel-with-sessions)。198使用 CI 状态栏中的**自动修复**和**自动合并**切换来启用任一选项。Claude Code 也会在 CI 完成时发送桌面通知。要在 PR 合并或关闭后自动归档会话，请在设置 → Claude Code 中打开[自动归档](#work-in-parallel-with-sessions)。

195 199

196<Note>200<Note>

197 PR 监控需要在你的机器上安装并验证 [GitHub CLI (`gh`)](https://cli.github.com/)。如果未安装 `gh`，Desktop 会在你第一次尝试创建 PR 时提示你安装它。201 PR 监控需要在你的机器上安装并认证 [GitHub CLI (`gh`)](https://cli.github.com/)。如果未安装 `gh`，Desktop 会在你第一次尝试创建 PR 时提示你安装它。

198</Note>202</Note>

199 203

200<h2 id="arrange-your-workspace">204<h2 id="arrange-your-workspace">

201 整理工作区205 整理工作区

202</h2>206</h2>

203 207

204Code 选项卡围绕你可以以任何布局排列的窗格构建：聊天、diff、浏览器、终端、文件、plan、tasks 和 subagent。通过其标题拖动窗格来重新定位它，或拖动窗格边缘来调整大小。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 来关闭焦点窗格。从会话工具栏中的 **Views** 菜单打开其他窗格。208Code 选项卡围绕你可以以任何布局排列的窗格构建：聊天、diff、浏览器、终端、文件、plan、tasks 和 subagent，以及 macOS 上的 [iOS Simulator](/docs/zh-CN/desktop-ios-simulator)。通过其标题拖动窗格来重新定位它，或拖动窗格边缘来调整大小。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 来关闭焦点窗格。从会话工具栏中的 **Views** 菜单打开其他窗格。

209

210要在多个屏幕上工作，可以将 diff 或终端等窗格弹出到其自己的窗口中，完成后再停靠回来。Claude 继续在主窗口中工作。

205 211

206<Note>212<Note>

207 本部分中的窗格布局、终端、文件编辑器和视图模式需要 Claude Desktop v1.2581.0 或更高版本。在 macOS 上打开 **Claude → Check for Updates** 或在 Windows 上打开 **Help → Check for Updates** 来更新。213 本部分中的窗格布局、终端、文件编辑器和视图模式需要 Claude Desktop v1.2581.0 或更高版本。在 macOS 上打开 **Claude → Check for Updates** 或在 Windows 上打开 **Help → Check for Updates** 来更新。

236 切换视图模式242 切换视图模式

237</h3>243</h3>

238 244

239视图模式控制聊天记录中显示多少详细信息。从发送按钮旁的 **Transcript view** 下拉菜单切换模式，或在 macOS 或 Windows 上按 **Ctrl+O** 来循环浏览它们。245视图模式控制聊天记录中显示多少详细信息。从发送按钮旁的 **Transcript view** 下拉菜单切换模式，或在 macOS 或 Windows 上按 **Ctrl+O** 来循环浏览它们。Thinking 模式仅在 Claude 在你正在查看的会话中产生思考后才出现在下拉菜单中。

240 246

241| 模式 | 显示内容 |247| 模式 | 显示内容 |

242| ----------- | -------------------------- |248| ------------ | ---------------------------------------- |

243| **Normal** | 工具调用折叠成摘要，带有完整文本响应 |249| **Normal** | 工具调用折叠成摘要，带有完整文本响应 |

244| **Verbose** | Claude 采取的每个工具调用、文件读取和中间步骤 |250| **Thinking** | 工具调用折叠成摘要，加上 Claude 的思考 |

245| **Summary** | 仅 Claude 的最终响应和它所做的更改 |251| **Verbose** | Claude 采取的每个工具调用、文件读取和中间步骤，加上 Claude 的思考 |

246 252

247在调试 Claude 为什么采取特定操作时使用 Verbose。当你运行多个会话并想快速扫描结果时使用 Summary。253使用 Thinking 来跟踪 Claude 的推理，工具调用仍然折叠。在调试 Claude 为什么采取特定操作时使用 Verbose。Claude Desktop 1.46388.1 之前的版本也列出了 Summary 模式，仍然设置为 Summary 的会话在你更新后会以 Normal 打开。

248 254

249<h3 id="keyboard-shortcuts">255<h3 id="keyboard-shortcuts">

250 快捷键256 快捷键

273| `1`–`9` | 在打开的菜单中选择项目 |279| `1`–`9` | 在打开的菜单中选择项目 |

274 280

275这些快捷键仅适用于 Code 选项卡。基于终端的[交互模式快捷键](/docs/zh-CN/interactive-mode#keyboard-shortcuts)（如 `Shift+Tab` 来循环模式）在 Desktop 中不适用。281这些快捷键仅适用于 Code 选项卡。基于终端的[交互模式快捷键](/docs/zh-CN/interactive-mode#keyboard-shortcuts)（如 `Shift+Tab` 来循环权限模式）在 Desktop 中不适用。

276 282

277<h3 id="check-usage">283<h3 id="check-usage">

278 检查使用情况284 检查使用情况

284 让 Claude 使用你的计算机290 让 Claude 使用你的计算机

285</h2>291</h2>

286 292

287计算机使用让 Claude 打开你的应用、控制你的屏幕，并像你一样直接在你的机器上工作。要求 Claude 在移动模拟器中测试原生应用、与没有 CLI 的桌面工具交互，或自动化只能通过 GUI 工作的东西。293计算机使用让 Claude 打开你的应用、控制你的屏幕，并像你一样直接在你的机器上工作。要求 Claude 与没有 CLI 的桌面工具交互，或自动化只能通过 GUI 工作的东西。对于运行和测试 iOS 应用，Desktop 会打开专用的 [iOS Simulator 窗格](/docs/zh-CN/desktop-ios-simulator)，而不是控制你的屏幕；该窗格无需启用计算机使用即可工作。

288 294

289<Note>295<Note>

290 计算机使用是 macOS 和 Windows 上的研究预览版，需要 Pro 或 Max 计划。它在 Team 或 Enterprise 计划上不可用。Claude Desktop 应用必须运行。296 计算机使用是 macOS 和 Windows 上的研究预览版，需要 Pro 或 Max 计划。它在 Team 或 Enterprise 计划上不可用。Claude Desktop 应用必须运行。

292 298

293计算机使用默认关闭。[在设置中启用它](#enable-computer-use)，然后 Claude 才能控制你的屏幕。在 macOS 上，你还需要授予辅助功能和屏幕录制权限。299计算机使用默认关闭。[在设置中启用它](#enable-computer-use)，然后 Claude 才能控制你的屏幕。在 macOS 上，你还需要授予辅助功能和屏幕录制权限。

294 300

301在 macOS 上，计算机使用也可以在后台运行：Claude 在你批准的应用中工作，同时你继续工作。

302

295<Warning>303<Warning>

296 与[沙箱化 Bash 工具](/docs/zh-CN/sandboxing)不同，计算机使用在你的实际桌面上运行，可以访问你批准的任何内容。Claude 检查每个操作并标记来自屏幕内容的潜在提示注入，但信任边界不同。有关最佳实践，请参阅[计算机使用安全指南](https://support.claude.com/en/articles/14128542)。304 与[沙箱化 Bash 工具](/docs/zh-CN/sandboxing)不同，计算机使用在你的实际桌面上运行，可以访问你批准的任何内容。Claude 检查每个操作并标记来自屏幕内容的潜在提示注入，但信任边界不同。有关最佳实践，请参阅[计算机使用安全指南](https://support.claude.com/en/articles/14128542)。

297</Warning>305</Warning>

305* 如果你有一个服务的[连接器](#connect-external-tools)，Claude 使用连接器。313* 如果你有一个服务的[连接器](#connect-external-tools)，Claude 使用连接器。

306* 如果任务是 shell 命令，Claude 使用 Bash。314* 如果任务是 shell 命令，Claude 使用 Bash。

307* 如果任务是浏览器工作且你已设置[Chrome 中的 Claude](/docs/zh-CN/chrome)，Claude 使用那个。315* 如果任务是浏览器工作且你已设置[Chrome 中的 Claude](/docs/zh-CN/chrome)，Claude 使用那个。

316* 如果任务是运行或测试 iOS 应用，Claude 使用 [iOS Simulator 窗格](/docs/zh-CN/desktop-ios-simulator)，它不使用屏幕控制。

308* 如果以上都不适用，Claude 使用计算机使用。317* 如果以上都不适用，Claude 使用计算机使用。

309 318

310[按应用访问层](#app-permissions)强化了这一点：浏览器限制为仅查看，终端和 IDE 限制为仅点击，即使计算机使用处于活跃状态，也会引导 Claude 使用专用工具。屏幕控制保留给其他工具无法到达的东西，如原生应用、硬件控制面板、移动模拟器或没有 API 的专有工具。319[按应用访问层](#app-permissions)强化了这一点：浏览器限制为仅查看，终端和 IDE 限制为仅点击，即使计算机使用处于活跃状态，也会引导 Claude 使用专用工具。屏幕控制保留给其他工具无法到达的东西，如原生应用、硬件控制面板或没有 API 的专有工具。

311 320

312<h3 id="enable-computer-use">321<h3 id="enable-computer-use">

313 启用计算机使用322 启用计算机使用

355你可以在**设置 > 常规**（在**桌面应用**下）中配置两个设置：364你可以在**设置 > 常规**（在**桌面应用**下）中配置两个设置：

356 365

357* **拒绝的应用**：在此处添加应用以拒绝它们而不提示。Claude 可能仍然通过允许应用中的操作间接影响被拒绝的应用，但它无法直接与被拒绝的应用交互。366* **拒绝的应用**：在此处添加应用以拒绝它们而不提示。Claude 可能仍然通过允许应用中的操作间接影响被拒绝的应用，但它无法直接与被拒绝的应用交互。

358* **Claude 完成时取消隐藏应用**：当 Claude 工作时，你的其他窗口被隐藏，以便它仅与批准的应用交互。当 Claude 完成时，隐藏的窗口被恢复，除非你关闭此设置。367* **Claude 完成时取消隐藏应用**：当计算机使用不在后台运行时，Claude 隐藏你的其他窗口，以便它仅与批准的应用交互。当 Claude 完成时，隐藏的窗口被恢复，除非你关闭此设置。

359 368

360<h2 id="manage-sessions">369<h2 id="manage-sessions">

361 管理会话370 管理会话

362</h2>371</h2>

363 372

364每个会话是一个独立的对话，拥有自己的上下文和更改。你可以并行运行多个会话、分支侧边聊天、将工作发送到云，或让 Dispatch 从你的手机为你启动会话。373每个会话是一个独立的对话，拥有自己的上下文和更改。你可以并行运行多个会话、分支侧边聊天、让 Claude 检查并向你的其他会话发送消息、将工作发送到云，或让 Dispatch 从你的手机为你启动会话。

365 374

366<h3 id="work-in-parallel-with-sessions">375<h3 id="work-in-parallel-with-sessions">

367 使用会话并行工作376 使用会话并行工作

368</h3>377</h3>

369 378

370点击侧边栏中的 **+ New session**，或在 macOS 上按 **Cmd+N** 或在 Windows 上按 **Ctrl+N**，来并行处理多个任务。按 **Ctrl+Tab** 和 **Ctrl+Shift+Tab** 来循环侧边栏中的会话。对于 Git 存储库，每个会话使用 [Git worktrees](/docs/zh-CN/worktrees) 获得自己的项目隔离副本，因此一个会话中的更改不会影响其他会话，直到你提交它们。379点击侧边栏中的 **+ New session**，或在 macOS 上按 **Cmd+N** 或在 Windows 上按 **Ctrl+N**，来并行处理多个任务。按 **Ctrl+Tab** 和 **Ctrl+Shift+Tab** 来循环侧边栏中的会话。对于 Git 存储库，选择分支名称旁边的 **worktree** 选项，为会话提供使用 [Git worktrees](/docs/zh-CN/worktrees) 的项目隔离副本，因此一个会话中的更改不会影响其他会话，直到你提交它们。

371 380

372要同时查看两个会话，在 macOS 上按住 **Cmd** 或在 Windows 上按住 **Ctrl** 并点击侧边栏中的会话。会话在第二个窗格中打开，与你已经打开的窗格并排。当分割处于活跃状态时，点击另一个侧边栏会话会替换具有焦点的窗格。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 来关闭焦点窗格并返回到单个会话。381要同时查看两个会话，在 macOS 上按住 **Cmd** 或在 Windows 上按住 **Ctrl** 并点击侧边栏中的会话。会话在第二个窗格中打开，与你已经打开的窗格并排。当分割处于活跃状态时，点击另一个侧边栏会话会替换具有焦点的窗格。在 macOS 上按 **Cmd+\\** 或在 Windows 上按 **Ctrl+\\** 来关闭焦点窗格并返回到单个会话。

373 382

376要在新 worktrees 中包含 gitignored 文件（如 `.env`），在你的项目根目录中创建一个 [`.worktreeinclude` 文件](/docs/zh-CN/worktrees#copy-gitignored-files-into-worktrees)。385要在新 worktrees 中包含 gitignored 文件（如 `.env`），在你的项目根目录中创建一个 [`.worktreeinclude` 文件](/docs/zh-CN/worktrees#copy-gitignored-files-into-worktrees)。

377 386

378<Note>387<Note>

379 会话隔离需要 [Git](https://git-scm.com/downloads)。大多数 Mac 默认包含 Git。在终端中运行 `git --version` 来检查。在 Windows 上，Git 是 Code 选项卡工作所必需的：[下载 Git for Windows](https://git-scm.com/downloads/win)，安装它，然后重启应用。如果你遇到 Git 错误，请在 [Cowork 选项卡](https://claude.com/product/cowork) 中询问 Claude 来帮助排除你的设置。388 会话隔离需要 [Git](https://git-scm.com/downloads)。大多数 Mac 默认包含 Git。在终端中运行 `git --version` 来检查；如果它打印版本号，则 Git 已安装。如果你遇到 Git 错误，请在 [Cowork 选项卡](https://claude.com/product/cowork) 中询问 Claude 来帮助排除你的设置。

380</Note>389</Note>

381 390

382使用侧边栏顶部的控制来按状态、项目或环境过滤会话，并按项目分组会话。要重命名会话，点击活跃会话顶部工具栏中的会话标题。要检查上下文使用情况，请参阅[检查使用情况](#check-usage)。当上下文填满时，Claude 自动总结对话并继续工作。你也可以输入 `/compact` 来更早触发总结并释放上下文空间。有关压缩工作原理的详细信息，请参阅[上下文窗口](/docs/zh-CN/how-claude-code-works#the-context-window)。391使用侧边栏顶部的控制来按状态、项目或环境过滤会话，并按项目分组会话。要重命名会话，点击活跃会话顶部工具栏中的会话标题。

383 392

384桌面应用在 Code 会话完成任务且你当前未查看该会话时发送操作系统通知。393要检查上下文使用情况，请参阅[检查使用情况](#check-usage)。当上下文填满时，Claude 自动总结对话并继续工作。你也可以输入 `/compact` 来更早触发总结并释放上下文空间。有关压缩工作原理的详细信息，请参阅[上下文窗口](/docs/zh-CN/how-claude-code-works#the-context-window)。

394

395桌面应用在 Code 会话完成任务且你当前未查看该会话时发送操作系统通知。对于属于[项目](/docs/zh-CN/claude-projects#see-what-needs-you-in-overview)的会话，你会获得项目的通知。

385 396

386<h3 id="ask-a-side-question-without-derailing-the-session">397<h3 id="ask-a-side-question-without-derailing-the-session">

387 在不偏离会话的情况下提出侧边问题398 在不偏离会话的情况下提出侧边问题

389 400

390侧边聊天让你提出一个使用你的会话上下文的问题，但不会添加任何内容回到主对话。当你想要理解一段代码、检查一个假设或探索一个想法而不引导会话偏离时，使用它。401侧边聊天让你提出一个使用你的会话上下文的问题，但不会添加任何内容回到主对话。当你想要理解一段代码、检查一个假设或探索一个想法而不引导会话偏离时，使用它。

391 402

392在 macOS 上按 **Cmd+;** 或在 Windows 上按 **Ctrl+;** 来打开侧边聊天，或在提示框中输入 `/btw`。侧边聊天可以读取主线程中到该点为止的所有内容。完成后，关闭侧边聊天并在你离开的地方继续主会话。侧边聊天在本地、SSH 和 WSL 会话中可用。403在 macOS 上按 **Cmd+;** 或在 Windows 上按 **Ctrl+;** 来打开侧边聊天，或在提示框中输入 `/btw`。侧边聊天可以读取主线程中到该点为止的所有内容。完成后，关闭侧边聊天并在你离开的地方继续主会话。

404

405侧边聊天在本地、SSH 和 WSL 会话中可用。桌面应用不会将侧边聊天保存到磁盘，因此你在关闭应用后无法返回到一个。

393 406

394<h3 id="watch-background-tasks">407<h3 id="watch-background-tasks">

395 观看后台任务408 观看后台任务

397 410

398任务窗格显示在当前会话内运行的后台工作：子代理、后台 shell 命令和[动态工作流](/docs/zh-CN/workflows)。从 **Views** 菜单打开它或将其拖入你的布局。411任务窗格显示在当前会话内运行的后台工作：子代理、后台 shell 命令和[动态工作流](/docs/zh-CN/workflows)。从 **Views** 菜单打开它或将其拖入你的布局。

399 412

400点击任何条目来在子代理窗格中查看其输出或停止它。要查看其他会话在做什么，使用[侧边栏](#work-in-parallel-with-sessions)。413点击任何条目来在子代理窗格中查看其输出或停止它。要查看其他会话在做什么，使用[侧边栏](#work-in-parallel-with-sessions)，或要求 Claude [为你检查它们](#work-across-sessions)。

401 414

402<h3 id="run-long-running-tasks-remotely">415<h3 id="work-across-sessions">

403 远程运行长时间运行的任务416 跨会话工作

404</h3>417</h3>

405 418

406对于大型重构、测试套件、迁移或其他长时间运行的任务，在启动会话时选择 **Remote** 而不是 **Local**。远程会话在 Anthropic 的云基础设施上运行，即使你关闭应用或关闭计算机，也会继续运行。随时检查进度或引导 Claude 朝不同方向发展。你也可以从 [claude.ai/code](https://claude.ai/code) 或 Claude iOS 应用监控远程会话。419Claude 可以列出你的其他 Code 选项卡会话，读取每个会话一直在做什么，并在它们之间发送消息。用简单的语言提问："哪个会话涉及了身份验证重构？"、"API 会话得出了什么结论？"或"告诉支付会话模式已更改"。你也可以要求 Claude 重命名或存档会话。Claude 存档会话的方式与侧边栏的存档图标相同，因此要求它清理 PR 已合并的会话。

407 420

408远程会话也支持多个存储库。选择云环境后，点击存储库 pill 旁的 **+** 按钮向会话添加其他存储库。每个存储库都有自己的分支选择器。这对于跨越多个代码库的任务很有用，例如更新共享库及其使用者。421通过这个界面，Claude 只看到桌面应用本身运行的会话：本地、[SSH](#ssh-sessions) 和 [WSL](/docs/zh-CN/desktop-wsl) 会话在 Code 选项卡中。Claude 看不到云会话，或你从终端 CLI 或 VS Code 扩展启动的会话，即使在同一项目的 worktrees 中，所以有九个终端 worktrees 打开和两个桌面会话，Claude 在其中一个回答时报告另一个桌面会话。Claude 永远不会列出你提问的会话。默认情况下，它看到 20 个最近活跃的会话，并跳过存档的会话，除非你要求它们。[跨会话消息传递](/docs/zh-CN/cross-session-messaging) 单独让 Claude 向[你的其他 Claude Code 会话](/docs/zh-CN/cross-session-messaging#see-which-sessions-claude-can-reach)发送消息，包括终端会话。

409 422

410有关远程会话如何工作的更多信息，请参阅 [Web 上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)。423当 Claude 通过这个界面向另一个会话发送消息时，Claude Code 在那里将其显示为一张卡片，标记有发送会话的标题和返回链接，因此你总是可以看到消息来自哪里。如果接收会话正在执行任务中，Claude Code 会保留消息，Claude 在当前工作完成后读取它。接收的 Claude 可以回复，Claude Code 通过这个界面将回复传递回去。Claude 无法传递到存档的会话，并在消息未通过时告诉你。

424

425Claude Code 在会话间应用四个安全行为：

426

427* 在存档任何会话之前，Claude 首先询问你。你在每个权限模式中看到批准卡片，包括自动和绕过权限。

428* 通过这个界面，Claude 无法从没有人观看的会话（例如计划任务运行）发送跨会话消息，也无法将消息传递到一个。

429* Claude Code 根据接收会话的[入站控制](/docs/zh-CN/cross-session-messaging#control-inbound-messages)检查来自这个界面的每条消息，即使接收会话本身没有[跨会话消息传递](/docs/zh-CN/cross-session-messaging#availability)。如果你在接收会话中将 [`crossSessionInbound`](/docs/zh-CN/settings-reference#crosssessioninbound) 设置为 `refuse`，Claude Code 会丢弃来自这个界面的消息。Claude Code 向 Claude 桌面应用报告拒绝。在 v2.1.234 之前，Claude Code 丢弃来自这个界面到没有跨会话消息传递的接收会话的每条消息。

430* Claude Code 引用每条传入消息并将其归属于发送它的会话，Claude 在对其进行操作时仍然遵循接收会话自己的权限设置。

431

432Claude 也可以建议新会话。当它注意到值得修复但超出当前任务范围的东西时，它在聊天中将工作作为任务芯片提供。点击芯片来在具有自己 worktree 的新会话中启动该工作；Claude 继续你的当前会话而不中断。

433

434<h3 id="run-long-running-tasks-in-the-cloud">

435 在云中运行长时间运行的任务

436</h3>

437

438对于大型重构、测试套件、迁移或其他长时间运行的任务，在启动会话时选择 **Cloud** 而不是 **Local**。云会话默认在 Anthropic 管理的基础设施上运行，即使你关闭应用或关闭计算机，也会继续运行。随时检查进度或引导 Claude 朝不同方向发展。你也可以从 [claude.ai/code](https://claude.ai/code) 或 [Claude 移动应用](/docs/zh-CN/mobile)监控云会话。

439

440云会话也支持多个存储库。选择云环境后，点击所选存储库旁边的 **+** 按钮向会话添加更多存储库。每个存储库都有自己的分支选择器。这对于跨越多个代码库的任务很有用，例如更新共享库及其使用者。

441

442有关云会话如何工作的更多信息，请参阅 [Web 上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)。当一项工作需要许多云会话时，在侧边栏中选择 **Projects** 来创建一个[项目](/docs/zh-CN/claude-projects)，Claude 从一个对话中为你启动和跟踪会话。

411 443

412<h3 id="continue-in-another-surface">444<h3 id="continue-in-another-surface">

413 在另一个表面继续445 在另一个表面继续

415 447

416**Continue in** 菜单，可从会话工具栏右下角的 VS Code 图标访问，让你将会话移动到另一个表面：448**Continue in** 菜单，可从会话工具栏右下角的 VS Code 图标访问，让你将会话移动到另一个表面：

417 449

418* **Web 上的 Claude Code**：将你的本地会话发送到远程继续运行。Desktop 推送你的分支，生成对话摘要，并创建具有完整上下文的新远程会话。你可以然后选择存档本地会话或保留它。这需要干净的工作树，对于 SSH 会话不可用。450* **Web 上的 Claude Code**：将你的本地会话发送到云中继续运行。Desktop 推送你的分支，生成对话摘要，并创建具有完整上下文的新云会话。你可以然后选择存档本地会话或保留它。这需要干净的工作树，对于 SSH 会话不可用。

419* **你的 IDE**：在当前工作目录的支持的 IDE 中打开你的项目。451* **你的 IDE**：在当前工作目录的支持的 IDE 中打开你的项目。

420 452

421<h3 id="sessions-from-dispatch">453<h3 id="sessions-from-dispatch">

432 464

433有关设置、配对和 Dispatch 设置，请参阅 [Dispatch 帮助文章](https://support.claude.com/en/articles/13947068)。Dispatch 需要 Pro 或 Max 计划，在 Team 或 Enterprise 计划上不可用。465有关设置、配对和 Dispatch 设置，请参阅 [Dispatch 帮助文章](https://support.claude.com/en/articles/13947068)。Dispatch 需要 Pro 或 Max 计划，在 Team 或 Enterprise 计划上不可用。

434 466

435Dispatch 是远离终端时与 Claude 合作的几种方式之一。请参阅[平台和集成](/docs/zh-CN/platforms#work-when-you-are-away-from-your-terminal)来比较它与远程控制、Channels、Slack 和计划任务。467Dispatch 是远离终端时与 Claude 合作的几种方式之一。有关与其他选项的比较，请参阅[平台和集成](/docs/zh-CN/platforms#work-when-you-are-away-from-your-terminal)。

436 468

437<h2 id="extend-claude-code">469<h2 id="extend-claude-code">

438 扩展 Claude Code470 扩展 Claude Code

439</h2>471</h2>

440 472

441连接外部服务、添加可重用工作流、自定义 Claude 的行为并配置预览服务器。要在一个地方管理连接器、skills 和插件，请点击侧边栏中的**自定义**。473连接外部服务、添加可重用工作流、自定义 Claude 的行为并配置预览服务器。要在一个地方管理连接器、skills 和插件，请点击侧边栏中的**自定义**。[Cowork](https://claude.com/product/cowork) 标签页在桌面应用中从此自定义配置获取其 skills、插件和连接器，该配置通过你的 claude.ai 账户同步，而不是从 CLI 的 `~/.claude` 目录。

474

475Claude Code 还会在你使用同一账户登录的终端会话中加载为你的 claude.ai 账户启用的 skills 和插件。请参阅[从 claude.ai 同步的 Skills](/docs/zh-CN/skills#how-synced-skills-behave) 和[从 claude.ai 同步的插件](/docs/zh-CN/plugins-reference#synced-plugins)。

442 476

443<h3 id="connect-external-tools">477<h3 id="connect-external-tools">

444 连接外部工具478 连接外部工具

445</h3>479</h3>

446 480

447对于本地和 [SSH](#ssh-sessions) 会话，点击提示框旁的 **+** 按钮并选择 **Connectors** 来添加集成，如 Google Calendar、Slack、GitHub、Linear、Notion 等。你可以在会话之前或期间添加连接器。**+** 按钮在云会话中不可用，但 [routines](/docs/zh-CN/routines) 在 routine 创建时配置连接器。481对于本地和 [SSH](#ssh-sessions) 会话，点击提示框旁的 **+** 按钮并选择 **Connectors** 来添加集成，如 Google Calendar、Slack、GitHub、Linear、Notion 等。你可以在会话之前或期间添加连接器。**+** 按钮在云会话或 WSL 会话中不可用，但 [routines](/docs/zh-CN/routines) 在 routine 创建时配置连接器。

448 482

449要管理或断开连接器，请在桌面应用中转到设置 → Connectors，或从提示框中的 Connectors 菜单中选择 **Manage connectors**。483要管理或断开连接器，请在桌面应用中转到设置 → Connectors，或从提示框中的 Connectors 菜单中选择 **Manage connectors**。

450 484

460 494

461你可以在 Claude 工作时发送命令，就像任何其他消息一样，会话在轮次完成后返回空闲状态。在 v2.1.206 之前，在轮次中间发送的命令可能会导致会话显示为运行状态，你之后发送的消息未被传递。495你可以在 Claude 工作时发送命令，就像任何其他消息一样，会话在轮次完成后返回空闲状态。在 v2.1.206 之前，在轮次中间发送的命令可能会导致会话显示为运行状态，你之后发送的消息未被传递。

462 496

497本地会话从 `~/.claude/skills/` 加载你的个人 skills。[SSH](#ssh-sessions) 会话从远程主机的主目录读取 `~/.claude/skills/`，而不是从你的机器。

498

499本地和云会话也加载为你的 claude.ai 账户启用的 skills。云会话改为加载它们，而不是 `~/.claude/skills/`，如[Cowork 和云会话中的 Skills](/docs/zh-CN/skills#skills-in-cowork-and-cloud-sessions)所述。

500

463<h3 id="install-plugins">501<h3 id="install-plugins">

464 安装插件502 安装插件

465</h3>503</h3>

468 506

469对于本地和 [SSH](#ssh-sessions) 会话，点击提示框旁的 **+** 按钮并选择 **Plugins** 来查看你已安装的插件及其 skills。要添加插件，从子菜单中选择 **Add plugin** 来打开插件浏览器，它显示来自你配置的[市场](/docs/zh-CN/plugin-marketplaces)的可用插件，包括官方 Anthropic 市场。选择 **Manage plugins** 来启用、禁用或卸载插件。507对于本地和 [SSH](#ssh-sessions) 会话，点击提示框旁的 **+** 按钮并选择 **Plugins** 来查看你已安装的插件及其 skills。要添加插件，从子菜单中选择 **Add plugin** 来打开插件浏览器，它显示来自你配置的[市场](/docs/zh-CN/plugin-marketplaces)的可用插件，包括官方 Anthropic 市场。选择 **Manage plugins** 来启用、禁用或卸载插件。

470 508

471插件可以限定到你的用户账户、特定项目或仅本地。如果你的组织集中管理插件，这些插件在桌面会话中的可用方式与在 CLI 中相同。插件在云会话或 WSL 会话中不可用。有关完整的插件参考，包括创建你自己的插件，请参阅 [plugins](/docs/zh-CN/plugins)。509你可以将插件限定到你的用户账户、特定项目或仅本地。如果你的组织集中管理插件，这些插件在桌面会话中的可用方式与在 CLI 中相同。

510

511插件浏览器在云会话中不可用，从桌面应用安装的插件不可用于云会话。要在云会话中使用插件，要么在存储库的 `.claude/settings.json` 中的 [`enabledPlugins`](/docs/zh-CN/settings-reference#enabledplugins) 下声明它，以便 Claude Code [在会话启动时安装它](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)，要么为你的 claude.ai 账户启用它，以便 Claude Code 将其作为[同步插件](/docs/zh-CN/plugins-reference#synced-plugins)加载。插件在 WSL 会话中不可用。有关完整的插件参考，包括创建你自己的插件，请参阅 [plugins](/docs/zh-CN/plugins)。

472 512

473<h3 id="configure-preview-servers">513<h3 id="configure-preview-servers">

474 配置预览服务器514 配置预览服务器

506{546{

507 "version": "0.0.1",547 "version": "0.0.1",

508 "autoVerify": false,548 "autoVerify": false,

509 "configurations": [...]549 "configurations": [

550 {

551 "name": "my-app",

552 "runtimeExecutable": "npm",

553 "runtimeArgs": ["run", "dev"],

554 "port": 3000

555 }

556 ]

510}557}

511```558```

512 559

527| `cwd` | string | 相对于你的项目根目录的工作目录。默认为项目根目录。使用 `${workspaceFolder}` 显式引用项目根目录 |574| `cwd` | string | 相对于你的项目根目录的工作目录。默认为项目根目录。使用 `${workspaceFolder}` 显式引用项目根目录 |

528| `env` | object | 其他环境变量作为键值对，例如 `{ "NODE_ENV": "development" }`。不要在这里放置秘密，因为此文件被提交到你的存储库。要将秘密传递给你的开发服务器，在[本地环境编辑器](#local-sessions)中设置它们。 |575| `env` | object | 其他环境变量作为键值对，例如 `{ "NODE_ENV": "development" }`。不要在这里放置秘密，因为此文件被提交到你的存储库。要将秘密传递给你的开发服务器，在[本地环境编辑器](#local-sessions)中设置它们。 |

579| `url` | string | preview 打开的地址，而不是 `http://localhost:<port>`。请参阅[在特定 URL 打开 preview](#open-the-preview-at-a-specific-url) |

532 580

533<a id="when-to-use-program-vs-runtimeexecutable" />581<a id="when-to-use-program-vs-runtimeexecutable" />

534 582

540 588

541当你有一个想用 `node` 直接运行的独立脚本时，使用 `program`。例如，`"program": "server.js"` 运行 `node server.js`。使用 `args` 传递其他标志。589当你有一个想用 `node` 直接运行的独立脚本时，使用 `program`。例如，`"program": "server.js"` 运行 `node server.js`。使用 `args` 传递其他标志。

542 590

591<a id="open-the-preview-at-a-specific-url" />

592

593<h5 id="open-the-preview-at-a-specific-url">

594 在特定 URL 打开 preview

595</h5>

596

597默认情况下，preview 打开 `http://localhost:<port>`。当你的服务器需要不同的地址时，设置 `url`。常见情况是需要本地 HTTPS 的服务器、使用 `*.localhost` 子域的应用以及通过重定向登录你的应用。

598

599```json theme={null}

600{

601 "version": "0.0.1",

602 "configurations": [

603 {

604 "name": "my-app",

605 "runtimeExecutable": "npm",

606 "runtimeArgs": ["run", "dev"],

607 "port": 8443,

608 "url": "https://localhost:8443"

609 }

610 ]

611}

612```

613

614Localhost 地址直接打开，完全像默认端口地址一样。这包括 `localhost`、任何 `*.localhost` 子域、`127.0.0.1` 和 `::1`。出于安全考虑，localhost `url` 必须仅是你的服务器的源 — 没有路径或查询，端口必须与条目的端口匹配。要显示特定页面，在 preview 打开后要求 Claude 导航到那里。带有路径、查询或不匹配端口的 localhost `url` 被报告为配置错误，该错误命名 url 并显示修复。

615

616对于任何其他地址，Desktop 在 preview 首次打开它时要求你的许可，就像你在 preview 中浏览到新网站时一样。外部地址可能包括路径。选择**始终允许**以在将来跳过该网站的提示。限制 preview 中外部网站的组织策略仍然适用。

617

618要预览你已经自己运行的服务器，设置 `url` 而不设置命令。Claude 将 preview 附加到你的运行服务器，而不是启动一个：

619

620```json theme={null}

621{

622 "version": "0.0.1",

623 "configurations": [

624 {

625 "name": "my-app",

626 "url": "https://app.localhost:3000"

627 }

628 ]

629}

630```

631

632`url` 必须是 `http` 或 `https`，且不能包含用户名或密码。

633

543<h4 id="port-conflicts">634<h4 id="port-conflicts">

544 端口冲突635 端口冲突

545</h4>636</h4>

632你在[启动会话](#start-a-session)时选择的环境决定了 Claude 执行的位置以及你如何连接：723你在[启动会话](#start-a-session)时选择的环境决定了 Claude 执行的位置以及你如何连接：

633 724

634* **Local**：在你的机器上运行，直接访问你的文件725* **Local**：在你的机器上运行，直接访问你的文件

635* **Remote**：在 Anthropic 的云基础设施上运行。即使你关闭应用，会话也会继续。726* **Cloud**：在 Anthropic 管理的基础设施上运行。即使你关闭应用，会话也会继续。

636* **SSH**：在你通过 SSH 连接的远程机器上运行，例如你自己的服务器、云虚拟机或开发容器727* **SSH**：在你通过 SSH 连接的远程机器上运行，例如你自己的服务器、云虚拟机或开发容器

637* **WSL**（Windows）：在你的机器上的 [WSL 2 发行版](/docs/zh-CN/desktop-wsl)内运行，使用其 Linux 工具链和本地路径728* **WSL**（Windows）：在你的机器上的 [WSL 2 发行版](/docs/zh-CN/desktop-wsl)内运行，使用其 Linux 工具链和本地路径

638 729

644 735

645要在任何平台上为本地会话和开发服务器设置环境变量，在提示框中打开环境下拉菜单，将鼠标悬停在 **Local** 上，然后点击齿轮图标来打开本地环境编辑器。你在此处保存的变量在你的机器上加密存储，并适用于你启动的每个本地会话和预览服务器。你也可以将变量添加到你的 `~/.claude/settings.json` 文件中的 `env` 键，尽管这些仅到达 Claude 会话而不是开发服务器。有关支持的变量的完整列表，请参阅[环境变量](/docs/zh-CN/env-vars)。736要在任何平台上为本地会话和开发服务器设置环境变量，在提示框中打开环境下拉菜单，将鼠标悬停在 **Local** 上，然后点击齿轮图标来打开本地环境编辑器。你在此处保存的变量在你的机器上加密存储，并适用于你启动的每个本地会话和预览服务器。你也可以将变量添加到你的 `~/.claude/settings.json` 文件中的 `env` 键，尽管这些仅到达 Claude 会话而不是开发服务器。有关支持的变量的完整列表，请参阅[环境变量](/docs/zh-CN/env-vars)。

646 737

647[Extended thinking](/docs/zh-CN/model-config#extended-thinking)默认启用，这改进了复杂推理任务的性能，但使用额外的令牌。要禁用思考，在本地环境编辑器中将 `MAX_THINKING_TOKENS` 设置为 `0`；这对 Fable 5 没有影响，Fable 5 始终使用 extended thinking。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，`0` 会省略 `thinking` 参数，自适应推理模型可能仍然会思考。在具有[自适应推理](/docs/zh-CN/model-config#adjust-effort-level)的模型上，任何其他 `MAX_THINKING_TOKENS` 值都被忽略，因为自适应推理控制思考深度。在 Opus 4.6 和 Sonnet 4.6 上，设置 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 为 `1` 来使用固定思考预算；Fable 5、Sonnet 5 和 Opus 4.7 及更高版本始终使用自适应推理，没有固定预算模式。738[Extended thinking](/docs/zh-CN/model-config#extended-thinking)默认启用，这改进了复杂推理任务的性能，但使用额外的令牌。在 Anthropic API 上，在本地环境编辑器中将 `MAX_THINKING_TOKENS` 设置为 `0` 来关闭思考；这对 Fable 模型没有影响，Fable 模型始终使用 extended thinking。在 Anthropic API 上关闭思考后，Claude Code 发送努力级别 `high` 而不是更高级别给它知道的[不接受该组合](/docs/zh-CN/errors#effort-isnt-available-with-thinking-turned-off)的模型，例如 Opus 5。

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 及更高版本始终使用自适应推理，没有固定预算模式。

741

742<h4 id="local-sessions-on-managed-devices">

743 托管设备上的本地会话

744</h4>

745

746你的管理员可以使用 [`disableDesktopLocalSessions` 托管设置](#managed-settings)关闭本地会话。当他们这样做时，**Local** 保留在环境下拉菜单中但被灰显，无法选择，并显示一个工具提示说你的组织关闭了它，在 Windows 上 [WSL](/docs/zh-CN/desktop-wsl) 条目（其在托管设备上的可用性[单独管理](/docs/zh-CN/admin-setup#wsl-sessions-in-claude-code-desktop)）也以相同方式灰显。新会话默认为第一个 SSH 连接（如果已配置），如果你尝试继续现有会话，Desktop 会显示一条消息说此设备上不可用本地会话。选择 [SSH](#ssh-sessions) 或 [cloud](#cloud-sessions) 环境，或联系你的 IT 团队。

648 747

649<h3 id="cloud-sessions">748<h3 id="cloud-sessions">

650 云会话749 云会话

652 751

653云会话即使在你关闭应用后也会在后台继续。使用计入你的[订阅计划限制](/docs/zh-CN/costs)，没有单独的计算费用。752云会话即使在你关闭应用后也会在后台继续。使用计入你的[订阅计划限制](/docs/zh-CN/costs)，没有单独的计算费用。

654 753

655你可以创建具有不同网络访问级别和环境变量的自定义云环境。在启动云会话时选择环境下拉菜单并选择 **Add environment**。有关配置网络访问和环境变量的详细信息，请参阅[云环境](/docs/zh-CN/claude-code-on-the-web#the-cloud-environment)。754你可以创建具有不同网络访问级别和环境变量的自定义云环境。在启动云会话时，打开提示框中的环境下拉菜单来管理它们：

755

756* **添加环境**：选择 **Add cloud environment**

757* **编辑或存档你自己的环境之一**：将鼠标悬停在它上面并点击齿轮图标

758

759有关配置网络访问和环境变量的详细信息，请参阅[配置云环境](/docs/zh-CN/cloud-environments)。

656 760

657<h3 id="ssh-sessions">761<h3 id="ssh-sessions">

658 SSH 会话762 SSH 会话

669 773

670添加后，连接出现在环境下拉菜单中。选择它在该机器上启动会话。Claude 在远程机器上运行，可以访问其文件和工具。774添加后，连接出现在环境下拉菜单中。选择它在该机器上启动会话。Claude 在远程机器上运行，可以访问其文件和工具。

671 775

672远程机器必须运行 Linux 或 macOS。桌面应用在你第一次连接时会自动在远程机器上安装 Claude Code。连接后，SSH 会话支持权限模式、连接器、plugins 和 MCP servers。776远程机器必须运行 Linux 或 macOS。Desktop 在你第一次连接时会自动在远程机器上安装 Claude Code。连接后，SSH 会话支持权限模式、connectors、plugins 和 MCP servers。

673 777

674<h4 id="pre-configure-ssh-connections-for-your-team">778<h4 id="pre-configure-ssh-connections-for-your-team">

675 为你的团队预配置 SSH 连接779 为你的团队预配置 SSH 连接

676</h4>780</h4>

677 781

678管理员可以通过将 `sshConfigs` 添加到[托管设置](/docs/zh-CN/settings#settings-precedence)文件来向团队成员分发 SSH 连接。以这种方式定义的连接会自动出现在每个用户的环境下拉菜单中，并显示为托管的，因此用户可以选择它们，但不能在应用中编辑或删除它们。782管理员可以通过将 `sshConfigs` 添加到[托管设置](/docs/zh-CN/managed-settings)文件来向团队成员分发 SSH 连接。以这种方式定义的连接会自动出现在每个用户的环境下拉菜单中，并显示为托管的，因此用户可以选择它们，但不能在应用中编辑或删除它们。

679 783

680以下示例预配置了一个在远程主机上的 `~/projects` 中打开的单个连接：784以下示例预配置了一个单个连接：

681 785

682```json theme={null}786```json theme={null}

683{787{

687 "name": "Shared Dev VM",791 "name": "Shared Dev VM",

688 "sshHost": "user@dev.example.com",792 "sshHost": "user@dev.example.com",

689 "sshPort": 22,793 "sshPort": 22,

690 "sshIdentityFile": "~/.ssh/id_ed25519",794 "sshIdentityFile": "~/.ssh/id_ed25519"

691 "startDirectory": "~/projects"

692 }795 }

693 ]796 ]

694}797}

695```798```

696 799

697每个条目需要 `id`、`name` 和 `sshHost`。`sshPort`、`sshIdentityFile` 和 `startDirectory` 字段是可选的。用户也可以将 `sshConfigs` 添加到他们自己的 `~/.claude/settings.json`，这是通过对话框添加的连接存储的位置。800每个条目需要 `id`、`name` 和 `sshHost`。`sshPort` 和 `sshIdentityFile` 字段是可选的。用户也可以将 `sshConfigs` 添加到他们自己的 `~/.claude/settings.json`，这是通过对话框添加的连接存储的位置。

698 801

699<h4 id="restrict-which-ssh-hosts-users-can-connect-to">802<h4 id="restrict-which-ssh-hosts-users-can-connect-to">

700 限制用户可以连接的 SSH 主机803 限制用户可以连接的 SSH 主机

701</h4>804</h4>

702 805

703管理员可以通过将 `sshHostAllowlist` 添加到[托管设置](/docs/zh-CN/settings#settings-precedence)文件来限制 Desktop 的 SSH 会话到一组已批准的主机。设置后，用户只能连接到其解析的主机名与其中一个模式匹配的主机。将其设置为空数组以完全禁用 SSH 会话。806管理员可以通过将 `sshHostAllowlist` 添加到[托管设置](/docs/zh-CN/managed-settings)文件来限制 Desktop 的 SSH 会话到一组已批准的主机。设置后，用户只能连接到其解析的主机名与其中一个模式匹配的主机。将其设置为空数组以完全禁用 SSH 会话。

704 807

705以下示例允许连接到 `devboxes.example.com` 下的任何主机以及单个命名的堡垒主机：808以下示例允许连接到 `devboxes.example.com` 下的任何主机以及单个命名的堡垒主机：

706 809

727这些设置通过[管理员设置控制台](https://claude.ai/admin-settings/claude-code)配置：830这些设置通过[管理员设置控制台](https://claude.ai/admin-settings/claude-code)配置：

728 831

729* **Desktop 中的 Code**：控制你的组织中的用户是否可以在桌面应用中访问 Claude Code832* **Desktop 中的 Code**：控制你的组织中的用户是否可以在桌面应用中访问 Claude Code

730* **Web 中的 Code**：为你的组织启用或禁用[Web 会话](/docs/zh-CN/claude-code-on-the-web)833* **Web 中的 Code**：为你的组织启用或禁用[云会话](/docs/zh-CN/claude-code-on-the-web)

731* **Remote Control**：为你的组织启用或禁用[远程控制](/docs/zh-CN/remote-control)834* **Remote Control**：为你的组织启用或禁用[远程控制](/docs/zh-CN/remote-control)

732* **禁用绕过权限模式**：防止你的组织中的用户启用绕过权限模式835* **禁用绕过权限模式**：防止你的组织中的用户启用绕过权限模式

733 836

735 托管设置838 托管设置

736</h3>839</h3>

737 840

738托管设置覆盖项目和用户设置，并应用于 Desktop 中的 Claude Code 会话。你可以在你的组织的[托管设置](/docs/zh-CN/settings#settings-precedence)文件中设置这些键，或通过管理员控制台远程推送它们。841托管设置覆盖项目和用户设置，并应用于 Desktop 中的 Claude Code 会话。你可以在你的组织的[托管设置](/docs/zh-CN/managed-settings)文件中设置这些键，或通过管理员控制台远程推送它们。

739 842

740| 键 | 描述 |843| 键 | 描述 |

741| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |844| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

743| `disableAutoMode` | 设置为 `"disable"` 以防止用户启用 [Auto](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 模式。从模式选择器中删除 Auto。也在 `permissions` 下接受。 |846| `disableAutoMode` | 设置为 `"disable"` 以从模式选择器中删除 [Auto](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 模式。也在 `permissions` 下接受。 |

745| `browserExternalPageTools` | 设置为 `"disabled"` 以防止 Claude 使用工具在[浏览器窗格](#browse-external-sites)中读取或作用于外部页面。用户仍然可以自己导航到外部网站，本地开发服务器预览不受影响。 |848| `browserExternalPageTools` | 设置为 `"disabled"` 以防止 Claude 使用工具在[浏览器窗格](#browse-external-sites)中读取或作用于外部页面。用户仍然可以自己导航到外部网站，本地开发服务器预览不受影响。 |

849| `disableMobileSimulatorTools` | 设置为 `true` 以阻止 Claude 在 [iOS Simulator 窗格](/docs/zh-CN/desktop-ios-simulator#turn-off-simulator-access)中控制和捕获设备的工具。该窗格仍可用于用户自己的点击；仅删除 Claude 的访问权限。该值必须是 JSON 布尔值 `true`；字符串 `"true"` 被忽略。 |

746| `disableBrowserExternalNavigation` | 设置为 `true` 以完全关闭[浏览器窗格](#browse-external-sites)中的外部浏览。用户和 Claude 都无法导航到外部网站，localhost 开发服务器预览不受影响。该值必须是 JSON 布尔值 `true`；字符串 `"true"` 被忽略。 |850| `disableBrowserExternalNavigation` | 设置为 `true` 以完全关闭[浏览器窗格](#browse-external-sites)中的外部浏览。用户和 Claude 都无法导航到外部网站，localhost 开发服务器预览不受影响。该值必须是 JSON 布尔值 `true`；字符串 `"true"` 被忽略。 |

748| `sshHostAllowlist` | 限制 [SSH 会话](#restrict-which-ssh-hosts-users-can-connect-to)连接到已解析主机名与这些模式之一匹配的主机。空数组禁用 SSH 会话。仅从托管设置中读取。 |852| `sshHostAllowlist` | 限制 [SSH 会话](#restrict-which-ssh-hosts-users-can-connect-to)连接到已解析主机名与这些模式之一匹配的主机。空数组禁用 SSH 会话。仅从托管设置中读取。 |

749| `managedMcpServers` | 将 MCP 服务器配置推送到第三方部署中的所有用户。每个条目指定 `"http"`、`"sse"` 或 `"stdio"` 的传输、连接详细信息，以及可选的 `toolPolicy` 映射，该映射限制该服务器中用户可以调用的工具。仅在第三方 (3P) Desktop 部署中可用。通过托管设置文件或 MDM 提供此键，因为第三方部署不接收管理员控制台设置。 |853| `disableDesktopLocalSessions` | 设置为 `true` 以关闭[在设备上运行的 Code 会话](#local-sessions-on-managed-devices)，仅保留 SSH 会话到其他主机和云会话可用。该值必须是 JSON 布尔值 `true`。仅从托管设置中读取。需要 Claude Desktop v1.37937.0 或更高版本。 |

854| `managedMcpServers` | 将 MCP 服务器配置推送到所有用户。仅在第三方 (3P) Desktop 部署中可用。在每个条目中，设置 `"http"`、`"sse"` 或 `"stdio"` 的传输、连接详细信息，以及可选的 `toolPolicy` 映射，该映射限制该服务器中用户可以调用的工具。通过托管设置文件、MDM 或 Claude apps gateway 策略的 [`desktop` 块](/docs/zh-CN/claude-apps-gateway-config#claude-desktop-overlay)提供它，因为 3P 部署不接收管理员控制台设置。要通过网关提供它，你需要网关服务器上的 Claude Code v2.1.232 或更高版本。这是桌面应用自己的键；Claude Code 读取自己的[同名托管设置](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings)，具有不同的条目形状。 |

750 855

751哪些托管设置到达 Desktop 会话取决于该会话运行的位置。模型限制（如 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection)）在 Desktop 的 Claude Code 会话中的执行方式与在终端 CLI 中相同；请参阅[表面覆盖](/docs/zh-CN/model-config#surface-coverage)。856哪些托管设置到达 Desktop 会话取决于该会话运行的位置。模型限制（如 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection)）在 Desktop 的 Claude Code 会话中的执行方式与在终端 CLI 中相同；请参阅[表面覆盖](/docs/zh-CN/model-config#surface-coverage)。

752 857

753* **此机器上的本地会话**：部署到磁盘的托管设置文件适用。通过管理员控制台远程推送的托管设置也在会话使用组织登录或直接配置的 API 密钥向 Anthropic 的 API 进行身份验证时到达这些会话，遵循与终端 CLI 相同的[设置优先级](/docs/zh-CN/settings#settings-precedence)。858* **此机器上的本地会话**：部署到磁盘的托管设置文件适用。通过管理员控制台远程推送的托管设置也在会话使用[符合条件的登录或密钥](/docs/zh-CN/server-managed-settings#platform-availability)向 Anthropic 的 API 进行身份验证时到达这些会话，遵循与终端 CLI 相同的[设置优先级](/docs/zh-CN/settings#settings-precedence)。

754* **[云会话](#cloud-sessions)**：在 Anthropic 管理的虚拟机上运行，仅接收[服务器管理的设置](/docs/zh-CN/server-managed-settings)。859* **[云会话](#cloud-sessions)**：接收[服务器管理的设置](/docs/zh-CN/server-managed-settings)；设备部署的文件无法到达它们，因为它们在 Anthropic 管理的虚拟机上运行。路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话也读取运行程序镜像中的托管设置文件。[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明该文件何时适用。

755* **[SSH 会话](#ssh-sessions)**：会话从远程主机读取托管设置文件。Desktop 本身在创建连接时从本地机器的托管设置中读取 `sshConfigs` 和 `sshHostAllowlist`。860* **[SSH 会话](#ssh-sessions)**：会话从远程主机读取托管设置文件。Desktop 本身从本地机器的托管设置中读取 `sshConfigs`、`sshHostAllowlist` 和 `disableDesktopLocalSessions`。

861* **[Cowork](https://claude.com/docs/cowork/overview) 会话**：在此机器上的 Cowork 会话中，Claude Code 永远不会获取管理员控制台设置，即使用户使用 Team 或 Enterprise 帐户登录，并读取部署到机器的策略，除非你的 Claude Desktop 配置设置 `requireCoworkFullVmSandbox`。远程 Cowork 会话都不接收。请参阅[策略应用的位置和时间](/docs/zh-CN/managed-settings#where-and-when-a-policy-applies)了解哪些设备文件到达 Cowork，以及[MCP 权限规则](/docs/zh-CN/permissions#mcp)了解 `Bash` 和 `WebFetch` 规则如何应用于 Cowork 的工具。

756 862

757`permissions.disableBypassPermissionsMode` 和 `disableAutoMode` 也在用户和项目设置中工作，但将它们放在托管设置中可防止用户覆盖它们。863在本地和 SSH 会话中，桌面应用直接将每个用户连接的 claude.ai 连接器传递给 Claude Code。无论你使用哪个设置源或文件位置，都没有 MCP 设置或 `managed-mcp.json` 到达这些连接器。要在这些会话中阻止连接器的工具，请使用你的组织的[连接器工具控制](/docs/zh-CN/mcp#organization-controls-on-connector-tools)。[连接器如何到达 Claude Code](/docs/zh-CN/mcp#how-connectors-reach-claude-code)显示在每种会话中哪些设置管理连接器。

758 864

759Claude Code 从用户设置、`--settings` 标志和托管设置中读取 `autoMode`，但不从 `.claude/settings.json` 或 `.claude/settings.local.json` 中读取：两个文件都位于存储库目录中，因此克隆的存储库或构建步骤无法注入其自己的分类器规则。在 v2.1.207 之前，Claude Code 也读取 `.claude/settings.local.json`。865`permissions.disableBypassPermissionsMode` 和 `disableAutoMode` 也在用户和项目设置中工作，但将它们放在托管设置中可防止用户覆盖它们。

760 866

761有关托管专用设置的完整列表，包括 `allowManagedPermissionRulesOnly` 和 `allowManagedHooksOnly`，请参阅[托管专用设置](/docs/zh-CN/permissions#managed-only-settings)。867有关仅托管源可以设置的权限、插件和交付键，请参阅[仅托管设置可以设置的键](/docs/zh-CN/managed-settings#managed-only-settings)。

762 868

763<h3 id="device-management-policies">869<h3 id="device-management-policies">

764 设备管理策略870 设备管理策略

814*.claudemcpcontent.com920*.claudemcpcontent.com

815```921```

816 922

923如果你的组织启用了[IP 允许列表](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting)用于 Claude，请通过与 `claude.ai` 和 `api.anthropic.com` 相同的代理出口路由 `bridge.claudeusercontent.com`。如果你无法以这种方式路由它，请将你的代理用于该主机的出口地址添加到你的组织的 IP 允许列表，但仅当该地址专用于你的组织时：共享代理出口范围也允许代理供应商的其他客户。

924

925Anthropic 根据它们到达的地址检查与该主机的连接是否符合你的组织的 IP 允许列表。如果你的代理通过不在该允许列表上的地址为其发送流量，Chrome 中的 Claude 和通过网桥连接的其他功能将停止工作，而应用的其余部分继续工作。

926

927从 [Google Fonts](/docs/zh-CN/artifacts#improve-the-visual-design) 加载字体的[工件](/docs/zh-CN/artifacts)也请求 `fonts.googleapis.com` 和 `fonts.gstatic.com`。两个主机都是可选的。如果你阻止它们，工件将以备用字体呈现。使用快速拒绝而不是静默丢弃来阻止，以便字体请求立即失败，而不是延迟页面的首次呈现。

928

929工件还可以从 `cdnjs.cloudflare.com`、`cdn.jsdelivr.net`、`cdn.tailwindcss.com` 和 `code.jquery.com` 加载 JavaScript 库（如 React 或图表包），而不能从其他任何外部主机加载。如果你阻止这些主机，工件中依赖库的部分将无法工作，与阻止的字体不同，阻止的库没有备用。这里也使用快速拒绝，以便阻止的库请求立即失败，而不是挂起直到超时。

930

817<h3 id="authentication-and-sso">931<h3 id="authentication-and-sso">

818 身份验证和 SSO932 身份验证和 SSO

819</h3>933</h3>

824 数据处理938 数据处理

825</h3>939</h3>

826 940

827Claude Code 在本地会话中本地处理你的代码，或在云会话中在 Anthropic 的云基础设施上处理。对话和代码上下文被发送到 Anthropic 的 API 进行处理。有关数据保留、隐私和合规性的详细信息，请参阅[数据处理](/docs/zh-CN/data-usage)。941Claude Code 在本地会话中本地处理你的代码，或在云会话中在 Anthropic 管理的基础设施上处理，除非你的组织将它们路由到[自托管环境](/docs/zh-CN/self-hosted-environments)。云会话（包括在自托管环境中）将对话和代码上下文发送到 Anthropic 的 API 进行处理；本地和 SSH 会话将它们发送到你的部署配置的任何[模型提供商](#feature-comparison)，默认为 Anthropic 的 API。有关数据保留、隐私和合规性的详细信息，请参阅[数据处理](/docs/zh-CN/data-usage)。

828 942

829<h3 id="deployment">943<h3 id="deployment">

830 部署944 部署

843 来自 CLI？957 来自 CLI？

844</h2>958</h2>

845 959

846如果你已经使用 Claude Code CLI，Desktop 运行相同的底层引擎，具有图形界面。你可以在同一机器上同时运行两者，甚至在同一项目上。每个维护单独的会话历史，但它们通过 CLAUDE.md 文件共享配置和项目内存。960如果你已经使用 Claude Code CLI，Desktop 运行相同的底层引擎，具有图形界面。你可以在同一机器上同时运行两者，甚至在同一项目上。每个维护单独的会话列表，你可以将 CLI 会话带入 Desktop。它们通过 CLAUDE.md 文件共享配置和项目内存。

961

962要将 CLI 会话移动到 Desktop，在终端中运行 `/desktop`。Claude 保存你的会话并在桌面应用中打开它，然后退出 CLI。此命令在 macOS 和 x64 Windows 上可用，当你使用 Claude 订阅登录时。它不适用于 API 密钥身份验证或 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。

847 963

848要将 CLI 会话移动到 Desktop，在终端中运行 `/desktop`。Claude 保存你的会话并在桌面应用中打开它，然后退出 CLI。此命令在 macOS 和 Windows 上可用，当你使用 Claude 订阅登录时。它不适用于 API 密钥身份验证或 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。964要从 Desktop 内部选择 CLI 会话，在提示框中输入 `/resume`。Desktop 列出你从 CLI 启动的会话，你可以按标题、文件夹或分支搜索它们，并预览每个会话的停止位置。选择一个会话，它将在应用中继续，具有完整的对话和上下文。

849 965

850<Tip>966<Tip>

851 何时使用 Desktop vs CLI：当你想要管理一个窗口中的并行会话、并排排列窗格或可视化审查更改时，使用 Desktop。当你需要脚本、自动化或更喜欢终端工作流时，使用 CLI。967 何时使用 Desktop vs CLI：当你想要管理一个窗口中的并行会话、并排排列窗格或可视化审查更改时，使用 Desktop。当你需要脚本、自动化或更喜欢终端工作流时，使用 CLI。

860| CLI | Desktop 等效项 |976| CLI | Desktop 等效项 |

861| ------------------------------------- | ----------------------------------------------------------------------------------------- |977| ------------------------------------- | ----------------------------------------------------------------------------------------- |

865| `--dangerously-skip-permissions` | 绕过权限模式。在 Pro 和 Max 计划上，在设置 → Claude Code → "允许绕过权限模式"中启用它；在 Team 和 Enterprise 计划上，组织策略控制它 |981| `--dangerously-skip-permissions` | 绕过权限模式。在 Pro 和 Max 计划上，在设置 → Claude Code → "允许绕过权限模式"中启用它；在 Team 和 Enterprise 计划上，组织策略控制它 |

882* **[Settings](/docs/zh-CN/settings)** 在 `~/.claude.json` 和 `~/.claude/settings.json` 中是共享的。权限规则、允许的工具和 `settings.json` 中的其他设置适用于 Desktop 会话。998* **[Settings](/docs/zh-CN/settings)** 在 `~/.claude.json` 和 `~/.claude/settings.json` 中是共享的。权限规则、允许的工具和 `settings.json` 中的其他设置适用于 Desktop 会话。

883* **Models**：相同的[模型](/docs/zh-CN/model-config#available-models)在两者中都可用。在 Desktop 中，从发送按钮旁的下拉菜单中选择模型。你可以在会话期间从相同的下拉菜单更改模型。999* **Models**：相同的[模型](/docs/zh-CN/model-config#available-models)在两者中都可用。在 Desktop 中，从发送按钮旁的下拉菜单中选择模型。你可以在会话期间从相同的下拉菜单更改模型。

884 1000

885<Note>1001<h4 id="mcp-servers-from-the-claude-desktop-chat-app">

886 **来自 Claude Desktop 聊天应用的 MCP servers**：Desktop 应用从 `claude_desktop_config.json` 将 MCP servers 加载到 Code 选项卡会话中，以及来自 `~/.claude.json` 和 `.mcp.json` 的服务器。在 `claude_desktop_config.json` 中定义的服务器在 Desktop 聊天表面和 Code 选项卡中都可用。1002 来自 Claude Desktop 聊天应用的 MCP servers

1003</h4>

887 1004

1005Desktop 应用从 `claude_desktop_config.json` 将 MCP servers 加载到本地 Code 选项卡会话中，以及来自 `~/.claude.json` 和 `.mcp.json` 的服务器。在 `claude_desktop_config.json` 中定义的服务器在 Desktop 聊天表面和本地 Code 选项卡会话中都可用。

1006

1007如果你在 `claude_desktop_config.json` 和 `~/.claude.json` 或 `.mcp.json` 中定义相同的服务器名称，本地会话中的 Code 选项卡连接一次并使用 `claude_desktop_config.json` 定义。

1008

1009该应用还将来自 `~/.claude.json` 的 stdio 服务器重新传递到本地会话中的嵌入式 CLI。当 `~/.claude.json`（用户范围）和 `.mcp.json` 的顶级定义相同的 stdio 服务器名称时，Code 选项卡使用 `~/.claude.json` 定义，偏离 CLI [范围层次结构](/docs/zh-CN/mcp#scope-hierarchy-and-precedence)。

1010

1011<Note>

888 独立 CLI 不读取 `claude_desktop_config.json`。在 macOS 和 WSL 上，运行 `claude mcp add-from-claude-desktop` 将这些服务器复制到 `~/.claude.json`。请参阅[从 Claude Desktop 导入 MCP servers](/docs/zh-CN/mcp#import-mcp-servers-from-claude-desktop)了解导入流程和范围选项。1012 独立 CLI 不读取 `claude_desktop_config.json`。在 macOS 和 WSL 上，运行 `claude mcp add-from-claude-desktop` 将这些服务器复制到 `~/.claude.json`。请参阅[从 Claude Desktop 导入 MCP servers](/docs/zh-CN/mcp#import-mcp-servers-from-claude-desktop)了解导入流程和范围选项。

889</Note>1013</Note>

890 1014

897| 功能 | CLI | Desktop |1021| 功能 | CLI | Desktop |

898| ----------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1022| ----------------------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

900| `--dangerously-skip-permissions` | CLI 标志 | 绕过权限模式。在 Pro 和 Max 计划上，在设置 → Claude Code → "允许绕过权限模式"中启用它；在 Team 和 Enterprise 计划上，组织策略控制它 |

901| [第三方提供商](/docs/zh-CN/third-party-integrations) | Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry | Anthropic 的 API 默认。对于网关路由，请参阅[将桌面应用连接到网关](/docs/zh-CN/llm-gateway-connect#desktop-app)。要在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自托管 LLM 网关上运行 Code 选项卡，请参阅 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)。 |1024| [第三方提供商](/docs/zh-CN/third-party-integrations) | Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry | Anthropic 的 API 默认。对于网关路由，请参阅[将桌面应用连接到网关](/docs/zh-CN/llm-gateway-connect#desktop-app)。要在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自托管 LLM 网关上运行 Code 选项卡，请参阅 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)。 |

905| 文件附件 | 不可用 | 图像、PDF |1028| 文件附件 | 不可用 | 图像、PDF |

1033| iOS 模拟器 | 通过[计算机使用](/docs/zh-CN/computer-use#test-a-simulator-flow)驱动模拟器 | [iOS Simulator 窗格](/docs/zh-CN/desktop-ios-simulator)自动打开 |

910| Dispatch 集成 | 不可用 | [Dispatch 会话](#sessions-from-dispatch)在侧边栏中 |1034| Dispatch 集成 | 不可用 | [Dispatch 会话](#sessions-from-dispatch)在侧边栏中 |

911| 脚本和自动化 | [`--print`](/docs/zh-CN/cli-reference)、[Agent SDK](/docs/zh-CN/headless) | 不可用 |1035| 脚本和自动化 | [`--print`](/docs/zh-CN/cli-reference)、[Agent SDK](/docs/zh-CN/headless) | 不可用 |

912 1036

914 Desktop 中不可用的内容1038 Desktop 中不可用的内容

915</h3>1039</h3>

916 1040

917以下功能仅在 CLI 或 VS Code 扩展中可用，除非另有说明：1041以下功能在 Desktop 中不可用，除非另有说明：

918 1042

919* **第三方提供商**：Desktop 默认连接到 Anthropic 的 API。要通过网关路由 Desktop，请参阅[将桌面应用连接到网关](/docs/zh-CN/llm-gateway-connect#desktop-app)。企业部署可以通过[托管设置](https://claude.com/docs/third-party/claude-desktop/configuration)配置 Google Cloud 的 Agent Platform 和网关提供商。对于 CLI 中的 Amazon Bedrock 或 Microsoft Foundry，请参阅[快速入门](/docs/zh-CN/quickstart)。作为上述部分的例外，[Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自托管 LLM 网关上运行 Code 选项卡。1043* **第三方提供商**：Desktop 默认连接到 Anthropic 的 API。要通过网关路由 Desktop，或在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自托管 LLM 网关上运行 Code 选项卡，请按照[第三方提供商行](#feature-comparison)中的链接操作。

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

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

922* **Agent teams**：并行 Claude Code 会话相互通信在 [CLI](/docs/zh-CN/agent-teams) 中可用，不在 Desktop 中。对于一个会话内的多 agent 工作，使用[动态工作流](/docs/zh-CN/workflows)，它在 Desktop 中运行。1046* **Agent teams**：协调的团队，其中 Claude 作为团队负责人从共享任务列表中为队友分配任务，在 [CLI](/docs/zh-CN/agent-teams) 中可用，不在 Desktop 中。对于一个会话内的多 agent 工作，使用[动态工作流](/docs/zh-CN/workflows)，它在 Desktop 中运行；Claude 也可以[直接消息和管理你的其他会话](#work-across-sessions)。

923* **Terminal-dialog 命令**：在终端中打开交互式面板的内置命令，其行为在 Code 选项卡中有所不同。直接编辑[设置文件](/docs/zh-CN/settings)来管理权限规则和配置，或从独立 CLI 运行命令。1047* **Terminal-dialog 命令**：在终端中打开交互式面板的内置命令，其行为在 Code 选项卡中有所不同。直接编辑[设置文件](/docs/zh-CN/settings)来管理权限规则和配置，或从独立 CLI 运行命令。

924 * 没有参数形式的命令，例如 `/permissions`，回复 `isn't available in this environment`。1048 * 没有参数形式的命令，例如 `/permissions`，回复 `isn't available in this environment`。

925 * `/config` 打开设置 → Claude Code。命令后的文本被忽略，所以 `/config theme=dark` 不设置主题。1049 * `/config` 打开设置 → Claude Code。命令后的文本被忽略，所以 `/config theme=dark` 不设置主题。

979 Git 和 Git LFS 错误1103 Git 和 Git LFS 错误

980</h3>1104</h3>

981 1105

982在 Windows 上，Git 是启动本地会话的 Code 选项卡所必需的。如果你看到"Git is required"，安装 [Git for Windows](https://git-scm.com/downloads/win) 并重启应用。1106在其自己的 worktree 中运行的会话需要 Git。如果你看到"Git is required"，安装 [Git](https://git-scm.com/downloads)，或在 Windows 上安装 [Git for Windows](https://git-scm.com/downloads/win)，然后重试。在 Windows 上，1.49585.0 之前的 Claude Desktop 版本在启动任何本地会话之前要求 Git；如果你看到该提示且不使用 worktrees，请更新应用。

983 1107

984如果你看到"Git LFS is required by this repository but is not installed"，从 [git-lfs.com](https://git-lfs.com/) 安装 Git LFS，运行 `git lfs install`，并重启应用。1108如果你看到"Git LFS is required by this repository but is not installed"，从 [git-lfs.com](https://git-lfs.com/) 安装 Git LFS，运行 `git lfs install`，并重启应用。

985 1109

1021* 在桌面应用中打开 Help → Get Support，或直接访问 [Claude 支持中心](https://support.claude.com/)1145* 在桌面应用中打开 Help → Get Support，或直接访问 [Claude 支持中心](https://support.claude.com/)

1022* 对于在独立 `claude` CLI 中也能重现的问题，在 [GitHub Issues](https://github.com/anthropics/claude-code/issues) 上搜索或提交错误1146* 对于在独立 `claude` CLI 中也能重现的问题，在 [GitHub Issues](https://github.com/anthropics/claude-code/issues) 上搜索或提交错误

1023 1147

1024提交问题时，包括你的桌面应用版本、你的操作系统、确切的错误消息和相关日志。在 macOS 上，检查 Console.app。在 Windows 上，检查事件查看器 → Windows 日志 → 应用程序。1148提交问题时，包括你的桌面应用版本、你的操作系统、确切的错误消息和相关日志。在 macOS 上，检查 Console.app。在 Windows 上，检查事件查看器 → Windows 日志 → 应用程序。在将日志摘录发布到公开问题之前，请查看它们；它们可能包含来自你的环境的文件路径和其他详细信息。

desktop-ios-simulator.md +1 −1

Details

29 在本页上，"设备"指的是模拟的 iPhone 或 iPad，是你在 Xcode 中的**Window → Devices and Simulators** 下管理的相同模拟器设备之一，而不是物理硬件。29 在本页上，"设备"指的是模拟的 iPhone 或 iPad，是你在 Xcode 中的**Window → Devices and Simulators** 下管理的相同模拟器设备之一，而不是物理硬件。

30</Note>30</Note>

31 31

32模拟器窗格仅在本地会话中可用。在[云](/docs/zh-CN/desktop#run-long-running-tasks-remotely)和 [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<h2 id="run-your-app-in-the-simulator">34<h2 id="run-your-app-in-the-simulator">

35 在模拟器中运行你的应用35 在模拟器中运行你的应用

desktop-quickstart.md +2 −2

Details

70 70

71 您也可以选择：71 您也可以选择：

72 72

~~73 * **云**：在云中运行会话，即使关闭应用也能继续。云会话使用与 [网页版 Claude Code](/docs/zh-CN/claude-code-on-the-web) 相同的基础设施。~~73 * **云**：在云中运行会话，即使关闭应用也能继续。请参阅 [在云中使用 Claude Code](/docs/zh-CN/claude-code-on-the-web) 了解云会话的工作原理。

74 * **SSH**：通过 SSH 连接到远程机器，例如您自己的服务器、云虚拟机或开发容器。桌面版在您第一次连接时会自动在远程机器上安装 Claude Code。74 * **SSH**：通过 SSH 连接到远程机器，例如您自己的服务器、云虚拟机或开发容器。桌面版在您第一次连接时会自动在远程机器上安装 Claude Code。

75 * **WSL**（Windows）：在 [WSL 2 发行版](/docs/zh-CN/desktop-wsl) 内运行会话；Claude Code、工具和 git 在 Linux 端执行，使用本机路径。75 * **WSL**（Windows）：在 [WSL 2 发行版](/docs/zh-CN/desktop-wsl) 内运行会话；Claude Code、工具和 git 在 Linux 端执行，使用本机路径。

76 </Step>76 </Step>

134 134

135**将 Claude 放在日程上。** 设置 [scheduled tasks](/docs/zh-CN/desktop-scheduled-tasks) 以定期自动运行 Claude：每天早上进行代码审查、每周进行依赖项审计，或从您连接的工具中提取信息的简报。135**将 Claude 放在日程上。** 设置 [scheduled tasks](/docs/zh-CN/desktop-scheduled-tasks) 以定期自动运行 Claude：每天早上进行代码审查、每周进行依赖项审计，或从您连接的工具中提取信息的简报。

136 136

137**准备好时扩展。** 从侧边栏打开 [parallel sessions](/docs/zh-CN/desktop#work-in-parallel-with-sessions) 以同时处理多个任务，可选择每个任务都在其自己的 Git worktree 中，并打开 [tasks pane](/docs/zh-CN/desktop#watch-background-tasks) 以观看会话正在运行的子代理和后台命令。打开 [side chat](/docs/zh-CN/desktop#ask-a-side-question-without-derailing-the-session) 以提出问题而不偏离主线程。将 [long-running work 发送到云](/docs/zh-CN/desktop#run-long-running-tasks-remotely) 以便即使关闭应用也能继续，或 [在 web 或 IDE 中继续会话](/docs/zh-CN/desktop#continue-in-another-surface)（如果任务花费的时间比预期长）。[连接外部工具](/docs/zh-CN/desktop#extend-claude-code)（如 GitHub、Slack 和 Linear）以整合您的工作流。137**准备好时扩展。** 从侧边栏打开 [parallel sessions](/docs/zh-CN/desktop#work-in-parallel-with-sessions) 以同时处理多个任务，可选择每个任务都在其自己的 Git worktree 中，并打开 [tasks pane](/docs/zh-CN/desktop#watch-background-tasks) 以观看会话正在运行的子代理和后台命令。打开 [side chat](/docs/zh-CN/desktop#ask-a-side-question-without-derailing-the-session) 以提出问题而不偏离主线程。将 [long-running work 发送到云](/docs/zh-CN/desktop#run-long-running-tasks-in-the-cloud) 以便即使关闭应用也能继续，或 [在 web 或 IDE 中继续会话](/docs/zh-CN/desktop#continue-in-another-surface)（如果任务花费的时间比预期长）。[连接外部工具](/docs/zh-CN/desktop#extend-claude-code)（如 GitHub、Slack 和 Linear）以整合您的工作流。

138 138

139<h2 id="what’s-next">139<h2 id="what’s-next">

140 接下来140 接下来

desktop-wsl.md +1 −1

Details

52 受管设备52 受管设备

53</h2>53</h2>

54 54

55在由组织管理的设备上，WSL 会话可能不可用。如果会话启动失败并显示设备受管的消息，这由您的管理员控制。管理员：请参阅部署指南中的[设置如何到达设备](/zh-CN/admin-setup#decide-how-settings-reach-devices)。55在由组织管理的设备上，WSL 会话可能不可用。如果会话启动失败并显示设备受管的消息，这由您的管理员控制。管理员：请参阅部署指南中的[设置如何到达设备](/docs/zh-CN/admin-setup#decide-how-settings-reach-devices)。

devcontainer.md +2 −2

Details

138 138

139`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 也禁用了[远程控制](/docs/zh-CN/remote-control#requirements)和其他[需要功能标志获取的功能](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)所依赖的功能标志评估，因此容器中的会话无法使用它们。139`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 也禁用了[远程控制](/docs/zh-CN/remote-control#requirements)和其他[需要功能标志获取的功能](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)所依赖的功能标志评估，因此容器中的会话无法使用它们。

140 140

141Dev Container Feature 始终安装最新的 Claude Code 版本。要为可重现的构建固定特定的 Claude Code 版本，请从您的 Dockerfile 使用 `npm install -g @anthropic-ai/claude-code@X.Y.Z` 安装它，而不是使用该功能，并设置 `DISABLE_AUTOUPDATER`，如上所示。141Dev Container Feature 始终安装最新的 Claude Code 版本。要为可重现的构建固定特定的 Claude Code 版本，请从您的 Dockerfile 使用 `npm install -g @anthropic-ai/claude-code@X.Y.Z` 安装它，而不是使用该功能，并在 `containerEnv` 中将 `DISABLE_AUTOUPDATER` 设置为 `1`。

142 142

143有关完整的策略控制列表，包括权限规则、工具限制和 MCP 服务器允许列表，请参阅[为您的组织设置 Claude Code](/docs/zh-CN/admin-setup)。143有关完整的策略控制列表，包括权限规则、工具限制和 MCP 服务器允许列表，请参阅[为您的组织设置 Claude Code](/docs/zh-CN/admin-setup)。

144 144

203Claude Code 在您的开发容器中运行后，下面的页面涵盖了组织推出的其余部分：选择身份验证路径、在存储库外交付托管策略、监控使用情况以及了解 Claude Code 存储和发送的内容。203Claude Code 在您的开发容器中运行后，下面的页面涵盖了组织推出的其余部分：选择身份验证路径、在存储库外交付托管策略、监控使用情况以及了解 Claude Code 存储和发送的内容。

204 204

205* [为您的组织设置 Claude Code](/docs/zh-CN/admin-setup)：选择身份验证提供商、决定策略如何到达设备以及规划推出205* [为您的组织设置 Claude Code](/docs/zh-CN/admin-setup)：选择身份验证提供商、决定策略如何到达设备以及规划推出

206* [服务器管理的设置](/docs/zh-CN/server-managed-settings)：从 Claude.ai 管理控制台交付托管策略，以便工程师无法通过编辑存储库文件来绕过它206* [服务器管理的设置](/docs/zh-CN/server-managed-settings)：从 claude.ai 管理控制台交付托管策略，以便工程师无法通过编辑存储库文件来绕过它

207* [监控使用情况和审计活动](/docs/zh-CN/monitoring-usage)：导出 OpenTelemetry 指标并查看您的团队正在运行的内容207* [监控使用情况和审计活动](/docs/zh-CN/monitoring-usage)：导出 OpenTelemetry 指标并查看您的团队正在运行的内容

208* [网络访问要求](/docs/zh-CN/network-config#network-access-requirements)：代理和防火墙的完整域允许列表208* [网络访问要求](/docs/zh-CN/network-config#network-access-requirements)：代理和防火墙的完整域允许列表

209* [遥测服务和选择退出](/docs/zh-CN/data-usage#telemetry-services)：Claude Code 默认发送的内容以及禁用它的环境变量209* [遥测服务和选择退出](/docs/zh-CN/data-usage#telemetry-services)：Claude Code 默认发送的内容以及禁用它的环境变量

discover-plugins.md +43 −3

Details

8 8

9插件通过 skills、agents、hooks 和 MCP servers 扩展 Claude Code。插件市场是帮助您发现和安装这些扩展的目录，无需自己构建。9插件通过 skills、agents、hooks 和 MCP servers 扩展 Claude Code。插件市场是帮助您发现和安装这些扩展的目录，无需自己构建。

10 10

11您也可以在 claude.ai 上启用插件，供自己或通过您的组织使用。Claude Code 会将这些插件同步到您的会话中，无需市场安装，如[从 claude.ai 同步的插件](/docs/zh-CN/plugins-reference#synced-plugins)所述。

11想要创建和分发自己的市场？请参阅[创建和分发插件市场](/docs/zh-CN/plugin-marketplaces)。13想要创建和分发自己的市场？请参阅[创建和分发插件市场](/docs/zh-CN/plugin-marketplaces)。

12 14

13<h2 id="how-marketplaces-work">15<h2 id="how-marketplaces-work">

78您也可以[为其他语言创建自己的 LSP 插件](/docs/zh-CN/plugins-reference#lsp-servers)。80您也可以[为其他语言创建自己的 LSP 插件](/docs/zh-CN/plugins-reference#lsp-servers)。

79 81

80<Note>82<Note>

~~81 如果在安装插件后在 `/plugin` 错误选项卡中看到 `Executable not found in $PATH`，请从上表安装所需的二进制文件。~~83 如果在安装插件后在 `/plugin` 错误选项卡中看到 `Executable not found in $PATH`，请从[代码智能](#code-intelligence)表中安装该插件所需的二进制文件。

82</Note>84</Note>

83 85

84<h4 id="what-claude-gains-from-code-intelligence-plugins">86<h4 id="what-claude-gains-from-code-intelligence-plugins">

237* **Git URL**：任何 git 存储库 URL，包括 GitLab、Bitbucket 和自托管服务器239* **Git URL**：任何 git 存储库 URL，包括 GitLab、Bitbucket 和自托管服务器

238* **本地路径**：目录或 `marketplace.json` 文件的直接路径240* **本地路径**：目录或 `marketplace.json` 文件的直接路径

239* **远程 URL**：托管 `marketplace.json` 文件的直接 URL241* **远程 URL**：托管 `marketplace.json` 文件的直接 URL

242* **claude.ai**：托管在 claude.ai 上的市场，用于您的账户，例如您组织的插件库，您可以[从 **Marketplaces** 标签页或您的 shell 按名称添加](#add-from-claude-ai)，而不是按来源添加

240 243

241<h3 id="add-from-github">244<h3 id="add-from-github">

242 从 GitHub 添加245 从 GitHub 添加

314 与基于 Git 的市场相比，基于 URL 的市场有一些限制。如果从基于 URL 的市场安装插件失败，请参阅[故障排除](/docs/zh-CN/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)。317 与基于 Git 的市场相比，基于 URL 的市场有一些限制。如果从基于 URL 的市场安装插件失败，请参阅[故障排除](/docs/zh-CN/plugin-marketplaces#plugins-with-relative-paths-fail-in-url-based-marketplaces)。

315</Note>318</Note>

316 319

320<h3 id="add-from-claude-ai">

321 从 claude.ai 添加

322</h3>

323

324在[插件从您的 claude.ai 账户同步](/docs/zh-CN/plugins-reference#synced-plugins)的终端会话中，claude.ai 也可以为您列出市场，例如您组织的插件库和您自己的 claude.ai 上传。`claude plugin marketplace list` 在 `From claude.ai:` 部分中打印它们，`/plugin` **Marketplaces** 标签页也列出它们。在那里选择一个来添加它。从 claude.ai 添加市场需要 Claude Code v2.1.273 或更高版本。

325

326要从您的 shell 添加一个，请运行 `claude plugin marketplace add` 命令，使用 `--claudeai` 标志和列表中显示的名称：

327

328```bash theme={null}

329claude plugin marketplace add --claudeai claudeai-organization-library

330```

331

332Claude Code 在以 `claudeai-` 开头的本地名称下注册市场，该名称源自 claude.ai 列出的名称：列为"Organization library"的市场注册为 `claudeai-organization-library`。通过该名称安装其插件，例如使用 `claude plugin install <plugin>@claudeai-organization-library`。

333

334如果您注销或使用不同账户登录，市场保持配置但不显示任何插件，您已从中安装的插件继续加载。

335

336`From claude.ai:` 部分也可以列出通过 claude.ai 共享的基于 git 的市场。您可以使用普通的 `marketplace add` 命令添加这些，使用列表打印的来源。

337

317<h2 id="install-plugins">338<h2 id="install-plugins">

318 安装插件339 安装插件

319</h2>340</h2>

320 341

321添加市场后，您可以按名称安装插件：342添加市场后，您可以按名称安装插件。对于您尚未添加的市场，您可以改为[在一个命令中添加并安装](#add-a-marketplace-and-install-in-one-command)。

343

344要按名称安装：

322 345

323```shell theme={null}346```shell theme={null}

324/plugin install plugin-name@marketplace-name347/plugin install plugin-name@marketplace-name

360 在安装插件之前，请确保您信任该插件。Anthropic 不控制插件中包含的 MCP servers、文件或其他软件，也无法验证它们是否按预期工作。检查每个插件的主页以获取更多信息。383 在安装插件之前，请确保您信任该插件。Anthropic 不控制插件中包含的 MCP servers、文件或其他软件，也无法验证它们是否按预期工作。检查每个插件的主页以获取更多信息。

361</Warning>384</Warning>

362 385

386<h3 id="add-a-marketplace-and-install-in-one-command">

387 在一个命令中添加市场并安装

388</h3>

389

390要从您尚未添加的市场安装插件，请使用 `--marketplace` 命名市场源。需要 Claude Code v2.1.275 或更高版本。

391

392```shell theme={null}

393/plugin install quality-review-plugin --marketplace your-org/plugins

394```

395

396该源采用与 [`/plugin marketplace add`](#add-marketplaces) 相同的形式，例如 GitHub `owner/repo`、git URL 或本地路径，除了它不能包含空格。给出插件名称时不带 `@marketplace` 后缀。

397

398如果您尚未添加该市场，Claude Code 会显示它解析的源并要求您在添加前确认。拒绝会取消安装并且不添加任何内容。一旦添加了市场，插件的详情会打开，您可以选择[安装范围](/docs/zh-CN/settings#where-settings-live)。

399

363<h2 id="manage-installed-plugins">400<h2 id="manage-installed-plugins">

364 管理已安装的插件401 管理已安装的插件

365</h2>402</h2>

372* 输入以按插件名称或描述筛选409* 输入以按插件名称或描述筛选

373* 按 Enter 打开插件的详细视图并启用、禁用或卸载它410* 按 Enter 打开插件的详细视图并启用、禁用或卸载它

374 411

412Claude Code 还在**已安装**选项卡中列出[从您的 claude.ai 账户同步的插件](/docs/zh-CN/plugins-reference#synced-plugins)，其源为 `synced`。您可以在那里启用或禁用一个，除非您的组织将其标记为必需。要删除一个，请在 claude.ai 上将其关闭。同步的插件出现在 Claude Code v2.1.273 或更高版本的终端会话中。

413

375卸载项目的 `.claude/settings.json` 启用的插件时，Claude Code 会询问您指的是哪个范围：仅为您禁用它，这会将覆盖写入您的 `.claude/settings.local.json` 并为项目保留已安装的插件，或为所有人卸载它，这会将其从共享的 `.claude/settings.json` 中删除。414卸载项目的 `.claude/settings.json` 启用的插件时，Claude Code 会询问您指的是哪个范围：仅为您禁用它，这会将覆盖写入您的 `.claude/settings.local.json` 并为项目保留已安装的插件，或为所有人卸载它，这会将其从共享的 `.claude/settings.json` 中删除。

376 415

377详细视图显示插件贡献的组件：commands、skills、agents、hooks、MCP servers 和 LSP servers。相同的清单也可以从命令行通过 `claude plugin details` 获得。416详细视图显示插件贡献的组件：commands、skills、agents、hooks、MCP servers 和 LSP servers。相同的清单也可以从命令行通过 `claude plugin details` 获得。

444* 您在另一个终端中运行的 `claude plugin` 命令483* 您在另一个终端中运行的 `claude plugin` 命令

445* 编辑您使用 [`--plugin-dir`](/docs/zh-CN/plugins#test-your-plugins-locally) 加载的插件，同时您开发它484* 编辑您使用 [`--plugin-dir`](/docs/zh-CN/plugins#test-your-plugins-locally) 加载的插件，同时您开发它

446* 插件[自动更新](#configure-auto-updates)，其通知要求您重新加载485* 插件[自动更新](#configure-auto-updates)，其通知要求您重新加载

486* [从您的 claude.ai 账户同步](/docs/zh-CN/plugins-reference#synced-plugins)添加、更新或删除插件并显示要求您重新加载的通知

447* [`--plugin-dir` 文件夹](/docs/zh-CN/plugins#test-your-plugins-locally)中的更改，Claude Code 保留了该更改，因为应用它会使 prompt cache 失效487* [`--plugin-dir` 文件夹](/docs/zh-CN/plugins#test-your-plugins-locally)中的更改，Claude Code 保留了该更改，因为应用它会使 prompt cache 失效

448 488

449在 v2.1.268 之前，您在菜单中启用、禁用或卸载的插件，以及在安装期间未激活的安装，保持待处理状态，直到您运行 `/reload-plugins`。489在 v2.1.268 之前，您在菜单中启用、禁用或卸载的插件，以及在安装期间未激活的安装，保持待处理状态，直到您运行 `/reload-plugins`。

5213. 从列表中选择市场5613. 从列表中选择市场

5224. 选择**启用自动更新**或**禁用自动更新**5624. 选择**启用自动更新**或**禁用自动更新**

523 563

524`claude-plugins-official` 和大多数其他官方 Anthropic 市场默认启用自动更新。第三方和本地开发市场默认禁用自动更新。564`claude-plugins-official`、大多数其他官方 Anthropic 市场和[从 claude.ai 添加的市场](#add-from-claude-ai)默认启用自动更新。其他第三方市场和本地开发市场默认禁用自动更新。

525 565

526管理员还可以在托管设置中的每个 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces) 条目上设置 `"autoUpdate": true` 以为组织市场启用自动更新，而无需每个用户都切换它。566管理员还可以在托管设置中的每个 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces) 条目上设置 `"autoUpdate": true` 以为组织市场启用自动更新，而无需每个用户都切换它。

527 567

env-vars.md +264 −263

Details

129<Note>129<Note>

130 对于打开或关闭行为的变量，设置 `1` 或 `true` 以打开它，设置 `0` 或 `false` 以关闭它，不区分大小写。130 对于打开或关闭行为的变量，设置 `1` 或 `true` 以打开它，设置 `0` 或 `false` 以关闭它，不区分大小写。

131 131

132 某些变量仅读取您是否设置了它们，因此任何非空值（包括 `0`）都会打开该行为，而您通过取消设置变量或将其设置为空值来关闭该行为。这些变量的工作方式如下：132 某些变量仅读取您是否设置了它们，因此任何非空值（包括 `0`）都会打开该行为，而通过取消设置变量或将其设置为空值来关闭该行为。这些变量的工作方式如下：

133 133

134 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`134 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`

135 * `DISABLE_TELEMETRY`135 * `DISABLE_TELEMETRY`

143 143

144| 变量 | 目的 |144| 变量 | 目的 |

145| :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |145| :------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

146| `ANTHROPIC_API_KEY` | 作为 `X-Api-Key` 标头发送的 API 密钥。设置此密钥后，即使您已登录，也会使用此密钥而不是您的 Claude Pro、Max、Team 或 Enterprise 订阅。在非交互模式（`-p`）中，存在密钥时始终使用该密钥。在交互模式中，系统会提示您在密钥覆盖您的订阅之前批准一次。要改用您的订阅，请运行 `unset ANTHROPIC_API_KEY` |146| `ANTHROPIC_API_KEY` | 作为 `X-Api-Key` 标头发送的 API 密钥。设置后，即使您已登录，此密钥也会被用来代替您的 Claude Pro、Max、Team 或 Enterprise 订阅。在非交互模式（`-p`）中，存在密钥时始终使用该密钥。在交互模式中，系统会提示您在密钥覆盖您的订阅之前批准一次。要改用您的订阅，请运行 `unset ANTHROPIC_API_KEY` |

148| `ANTHROPIC_AWS_API_KEY` | [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 的工作区 API 密钥，在 AWS 控制台中生成。作为 `x-api-key` 发送，优先于 AWS SigV4 |148| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 的工作区 API 密钥，在 AWS 控制台中生成。作为 `x-api-key` 发送，优先于 AWS SigV4 |

149| `ANTHROPIC_AWS_BASE_URL` | 覆盖 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 端点 URL。用于自定义区域或通过 [LLM 网关](/docs/zh-CN/llm-gateway) 路由时。默认为 `https://aws-external-anthropic.{region}.api.aws`。Claude Code 使用 [与 Amazon Bedrock 相同的优先级](/docs/zh-CN/amazon-bedrock#3-configure-claude-code) 解析区域 |149| `ANTHROPIC_AWS_BASE_URL` | 覆盖 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 端点 URL。用于自定义区域或通过 [LLM 网关](/docs/zh-CN/llm-gateway) 路由。默认为 `https://aws-external-anthropic.{region}.api.aws`。Claude Code 使用 [与 Amazon Bedrock 相同的优先级](/docs/zh-CN/amazon-bedrock#3-configure-claude-code) 解析区域 |

150| `ANTHROPIC_AWS_WORKSPACE_ID` | [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 所需。在每个请求上作为 `anthropic-workspace-id` 标头发送 |150| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 所需。在每个请求上作为 `anthropic-workspace-id` 标头发送 |

151| `ANTHROPIC_BASE_URL` | 覆盖 API 端点以通过代理或网关路由请求。设置为非第一方主机时，[MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search) 默认禁用。如果您的代理转发 `tool_reference` 块，设置 `ENABLE_TOOL_SEARCH=true`。从 v2.1.196 开始，当此指向除 `api.anthropic.com` 之外的主机时，[Remote Control](/docs/zh-CN/remote-control#requirements) 被禁用，与其在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的行为相匹配 |151| `ANTHROPIC_BASE_URL` | 覆盖 API 端点以通过代理或网关路由请求。设置为非第一方主机时，[MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search) 默认禁用。如果您的代理转发 `tool_reference` 块，设置 `ENABLE_TOOL_SEARCH=true`。从 v2.1.196 开始，当这指向除 `api.anthropic.com` 之外的主机时，[Remote Control](/docs/zh-CN/remote-control#requirements) 被禁用，与其在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的行为相匹配 |

152| `ANTHROPIC_BEDROCK_BASE_URL` | 覆盖 Amazon Bedrock 端点 URL。用于自定义 Amazon Bedrock 端点或通过 [LLM 网关](/docs/zh-CN/llm-gateway) 路由时。请参阅 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) |152| `ANTHROPIC_BEDROCK_BASE_URL` | 覆盖 Amazon Bedrock 端点 URL。用于自定义 Amazon Bedrock 端点或通过 [LLM 网关](/docs/zh-CN/llm-gateway) 路由。参见 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) |

153| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆盖 Amazon Bedrock Mantle 端点 URL。请参阅 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint) |153| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆盖 Amazon Bedrock Mantle 端点 URL。参见 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint) |

154| `ANTHROPIC_BEDROCK_REGION_PREFIX` | 跨区域推理配置文件前缀（`us`、`eu`、`apac`、`jp`、`au` 或 `global`）Claude Code 首先尝试而不是从 AWS 区域派生的前缀。在 AWS GovCloud 区域中被忽略。需要 Claude Code v2.1.224 或更高版本。请参阅 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock#cross-region-inference-profile-prefixes) |154| `ANTHROPIC_BEDROCK_REGION_PREFIX` | 跨区域推理配置文件前缀（`us`、`eu`、`apac`、`jp`、`au` 或 `global`）Claude Code 首先尝试而不是从 AWS 区域派生的前缀。在 AWS GovCloud 区域中被忽略。需要 Claude Code v2.1.224 或更高版本。参见 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock#cross-region-inference-profile-prefixes) |

155| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [服务层](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作为 `X-Amzn-Bedrock-Service-Tier` 标头发送。请参阅 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock#service-tiers) |155| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [服务层](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作为 `X-Amzn-Bedrock-Service-Tier` 标头发送。参见 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock#service-tiers) |

156| `ANTHROPIC_BETAS` | 逗号分隔的其他 `anthropic-beta` 标头值列表，包含在 API 请求中。Claude Code 已发送它需要的测试版标头；在 Claude Code 添加原生支持之前，使用此选项选择加入 [Anthropic API 测试版](https://platform.claude.com/docs/en/api/beta-headers)。与 [`--betas` 标志](/docs/zh-CN/cli-reference#cli-flags)（需要 API 密钥身份验证）不同，此变量适用于所有身份验证方法，包括 Claude.ai 订阅 |156| `ANTHROPIC_BETAS` | 逗号分隔的附加 `anthropic-beta` 标头值列表，包含在 API 请求中。Claude Code 已经发送它需要的测试版标头；在 Claude Code 添加原生支持之前，使用此变量选择加入 [Anthropic API 测试版](https://platform.claude.com/docs/en/api/beta-headers)。与 [`--betas` 标志](/docs/zh-CN/cli-reference#cli-flags)（需要 API 密钥身份验证）不同，此变量适用于所有身份验证方法，包括 Claude.ai 订阅 |

157| `ANTHROPIC_CUSTOM_HEADERS` | 要添加到请求的自定义标头（`Name: Value` 格式，多个标头用换行符分隔）。如果名称或值包含 HTTP 标头无法携带的字符（如弯引号或零宽空格），请求将失败并显示按位置标识该对的错误。需要 Claude Code v2.1.227 或更高版本。[无效的请求标头值](/docs/zh-CN/errors#invalid-request-header-value) 列出了确切的字符集和检查运行的位置。设置凭证、组织或租户、路由或 API 行为标头（如 `Authorization` 或 `Host`）的值在服务器管理的设置传递时计为 [需要批准的设置](/docs/zh-CN/server-managed-settings#environment-variables-and-the-approval-dialog)。从项目或本地设置，此类值遵循 [何时应用 `env` 值的规则](/docs/zh-CN/settings-reference#when-claude-code-applies-env-values) |157| `ANTHROPIC_CUSTOM_HEADERS` | 要添加到请求的自定义标头（`Name: Value` 格式，多个标头用换行符分隔）。如果名称或值包含 HTTP 标头无法携带的字符（如弯引号或零宽空格），请求将失败并显示按位置标识该对的错误。需要 Claude Code v2.1.227 或更高版本。[Invalid request header value](/docs/zh-CN/errors#invalid-request-header-value) 列出了确切的字符集和检查运行的位置。设置凭证、组织或租户、路由或 API 行为标头（如 `Authorization` 或 `Host`）的值在服务器管理的设置传递时计为 [需要批准的设置](/docs/zh-CN/server-managed-settings#environment-variables-and-the-approval-dialog)。从项目或本地设置，此类值遵循 [何时应用 `env` 值的规则](/docs/zh-CN/settings-reference#when-claude-code-applies-env-values) |

158| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 模型 ID，作为自定义条目添加到 `/model` 选择器中。使用此选项可以选择非标准或网关特定的模型，而无需替换内置别名。请参阅 [模型配置](/docs/zh-CN/model-config#add-a-custom-model-option) |158| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 模型 ID，作为自定义条目添加到 `/model` 选择器中。使用此选项可以使非标准或网关特定的模型可选，而无需替换内置别名。参见 [模型配置](/docs/zh-CN/model-config#add-a-custom-model-option) |

160| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 选择器中自定义模型条目的显示名称。未设置时，如果 Claude Code [识别 ID](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)，条目显示模型的名称，否则显示模型 ID |160| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 选择器中自定义模型条目的显示名称。未设置时，如果 Claude Code [识别 ID](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)，条目显示模型的名称，否则显示模型 ID |

161| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 逗号分隔的自定义模型支持的 [功能](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) 列表，例如 `effort,thinking`。请参阅 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |161| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 逗号分隔的自定义模型支持的 [功能](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) 列表，例如 `effort,thinking`。参见 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

162| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 别名解析为的模型 ID，以及 Claude Code 识别为 Fable 模型的 ID，用于第三方提供商上的 [自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)。请参阅 [模型配置](/docs/zh-CN/model-config#environment-variables) |162| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 别名解析为的模型 ID，以及 Claude Code 识别为 Fable 模型的 ID，用于第三方提供商上的 [自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)。参见 [模型配置](/docs/zh-CN/model-config#environment-variables) |

163| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 选择器中固定 Fable 模型的显示描述。未设置时，行显示以 `Custom Fable model` 开头的默认描述。请参阅 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |163| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 选择器中固定 Fable 模型的显示描述。未设置时，行显示以 `Custom Fable model` 开头的默认描述。参见 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

164| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 选择器中固定 Fable 模型的显示名称。未设置时，如果 Claude Code 识别固定 ID，行显示模型的名称，否则显示固定 ID。请参阅 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |164| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 选择器中固定 Fable 模型的显示名称。未设置时，如果 Claude Code 识别固定 ID，行显示模型的名称，否则显示固定 ID。参见 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

165| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 逗号分隔的固定 Fable 模型支持的 [功能](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) 列表，例如 `effort,thinking`。请参阅 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |165| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 逗号分隔的固定 Fable 模型支持的 [功能](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) 列表，例如 `effort,thinking`。参见 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

166| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 别名解析为的模型 ID，也用于 [后台功能](/docs/zh-CN/costs#background-token-usage)。请参阅 [模型配置](/docs/zh-CN/model-config#environment-variables) |166| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 别名解析为的模型 ID，也用于 [后台功能](/docs/zh-CN/costs#background-token-usage)。参见 [模型配置](/docs/zh-CN/model-config#environment-variables) |

167| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | `/model` 选择器中固定 Haiku 模型的显示描述。未设置时，行显示以 `Custom Haiku model` 开头的默认描述。请参阅 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |167| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | `/model` 选择器中固定 Haiku 模型的显示描述。未设置时，行显示以 `Custom Haiku model` 开头的默认描述。参见 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

168| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 选择器中固定 Haiku 模型的显示名称。未设置时，如果 Claude Code 识别固定 ID，行显示模型的名称，否则显示固定 ID。请参阅 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |168| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 选择器中固定 Haiku 模型的显示名称。未设置时，如果 Claude Code 识别固定 ID，行显示模型的名称，否则显示固定 ID。参见 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 逗号分隔的固定 Haiku 模型支持的 [功能](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) 列表，例如 `effort,thinking`。请参阅 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 逗号分隔的固定 Haiku 模型支持的 [功能](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) 列表，例如 `effort,thinking`。参见 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

170| `ANTHROPIC_DEFAULT_MODEL` | 新会话默认启动的模型。需要 Claude Code v2.1.236 或更高版本。请参阅 [为新会话设置默认模型](/docs/zh-CN/model-config#set-a-default-model-for-new-sessions) |170| `ANTHROPIC_DEFAULT_MODEL` | 新会话默认启动的模型。需要 Claude Code v2.1.236 或更高版本。参见 [为新会话设置默认模型](/docs/zh-CN/model-config#set-a-default-model-for-new-sessions) |

171| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 别名解析为的模型 ID，以及 Plan Mode 活跃时 `opusplan` 使用的模型 ID。请参阅 [模型配置](/docs/zh-CN/model-config#environment-variables) |171| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 别名解析为的模型 ID，以及 Plan Mode 活跃时 `opusplan` 使用的模型 ID。参见 [模型配置](/docs/zh-CN/model-config#environment-variables) |

172| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 选择器中固定 Opus 模型的显示描述。未设置时，行显示以 `Custom Opus model` 开头的默认描述。请参阅 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |172| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 选择器中固定 Opus 模型的显示描述。未设置时，行显示以 `Custom Opus model` 开头的默认描述。参见 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

173| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 选择器中固定 Opus 模型的显示名称。未设置时，如果 Claude Code 识别固定 ID，行显示模型的名称，否则显示固定 ID。请参阅 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |173| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 选择器中固定 Opus 模型的显示名称。未设置时，如果 Claude Code 识别固定 ID，行显示模型的名称，否则显示固定 ID。参见 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

174| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 逗号分隔的固定 Opus 模型支持的 [功能](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) 列表，例如 `effort,thinking`。请参阅 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |174| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 逗号分隔的固定 Opus 模型支持的 [功能](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) 列表，例如 `effort,thinking`。参见 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

175| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 别名解析为的模型 ID，以及 Plan Mode 不活跃时 `opusplan` 使用的模型 ID。请参阅 [模型配置](/docs/zh-CN/model-config#environment-variables) |175| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 别名解析为的模型 ID，以及 Plan Mode 不活跃时 `opusplan` 使用的模型 ID。参见 [模型配置](/docs/zh-CN/model-config#environment-variables) |

176| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | `/model` 选择器中固定 Sonnet 模型的显示描述。未设置时，行显示以 `Custom Sonnet model` 开头的默认描述。请参阅 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |176| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | `/model` 选择器中固定 Sonnet 模型的显示描述。未设置时，行显示以 `Custom Sonnet model` 开头的默认描述。参见 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

177| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 选择器中固定 Sonnet 模型的显示名称。未设置时，如果 Claude Code 识别固定 ID，行显示模型的名称，否则显示固定 ID。请参阅 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |177| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 选择器中固定 Sonnet 模型的显示名称。未设置时，如果 Claude Code 识别固定 ID，行显示模型的名称，否则显示固定 ID。参见 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

178| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 逗号分隔的固定 Sonnet 模型支持的 [功能](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) 列表，例如 `effort,thinking`。请参阅 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |178| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 逗号分隔的固定 Sonnet 模型支持的 [功能](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) 列表，例如 `effort,thinking`。参见 [模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

179| `ANTHROPIC_FEDERATION_RULE_ID` | [工作负载身份联合](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的联合规则 ID。当您将其与 `ANTHROPIC_ORGANIZATION_ID` 一起设置时，Claude Code 选择联合凭证，其优先级高于您的 `/login` 凭证。请参阅 [身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |179| `ANTHROPIC_FEDERATION_RULE_ID` | [工作负载身份联合](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的联合规则 ID。当您将其与 `ANTHROPIC_ORGANIZATION_ID` 一起设置时，Claude Code 选择联合凭证，其优先级高于您的 `/login` 凭证。参见 [身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |

181| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | Microsoft Foundry 身份验证的持有者令牌，例如 Microsoft Entra 访问令牌。Claude Code 将其作为 `Authorization: Bearer` 标头发送。优先于 `ANTHROPIC_FOUNDRY_API_KEY` 和 Azure 默认凭证链。请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)。需要 Claude Code v2.1.203 或更高版本 |181| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | Microsoft Foundry 身份验证的 Bearer 令牌，例如 Microsoft Entra 访问令牌。Claude Code 将其作为 `Authorization: Bearer` 标头发送。优先于 `ANTHROPIC_FOUNDRY_API_KEY` 和 Azure 默认凭证链。参见 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)。需要 Claude Code v2.1.203 或更高版本 |

182| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 资源的完整基础 URL（例如，`https://my-resource.services.ai.azure.com/anthropic`）。`ANTHROPIC_FOUNDRY_RESOURCE` 的替代方案（请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)） |182| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 资源的完整基础 URL（例如，`https://my-resource.services.ai.azure.com/anthropic`）。`ANTHROPIC_FOUNDRY_RESOURCE` 的替代方案（参见 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)） |

183| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 资源名称（例如，`my-resource`）。如果未设置 `ANTHROPIC_FOUNDRY_BASE_URL`，则为必需（请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)） |183| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 资源名称（例如，`my-resource`）。如果未设置 `ANTHROPIC_FOUNDRY_BASE_URL`，则为必需（参见 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)） |

185| `ANTHROPIC_ORGANIZATION_ID` | [工作负载身份联合](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的组织 ID。将其与 `ANTHROPIC_FEDERATION_RULE_ID` 一起设置。请参阅 [身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |185| `ANTHROPIC_ORGANIZATION_ID` | [工作负载身份联合](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的组织 ID。与 `ANTHROPIC_FEDERATION_RULE_ID` 一起设置。参见 [身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |

186| `ANTHROPIC_PROFILE` | 要使用的 Anthropic 配置文件的名称，例如由 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 创建的或通过 [在没有 API 密钥的情况下登录控制台帐户](/docs/zh-CN/authentication#sign-in-without-an-api-key)。请参阅 [身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |186| `ANTHROPIC_PROFILE` | 要使用的 Anthropic 配置文件的名称，例如由 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 创建的或通过 [在没有 API 密钥的情况下登录控制台帐户](/docs/zh-CN/authentication#sign-in-without-an-api-key)。参见 [身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |

188| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 时覆盖 Haiku 级模型的 AWS 区域。在 Amazon Bedrock 上，仅当也设置了 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已弃用的 `ANTHROPIC_SMALL_FAST_MODEL` 时，此选项才生效，因为 Amazon Bedrock 否则会在 [默认 Sonnet 模型或会话区域中的主模型](/docs/zh-CN/amazon-bedrock#4-pin-model-versions) 上运行后台任务 |188| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 时覆盖 Haiku 类模型的 AWS 区域。在 Amazon Bedrock 上，仅当也设置了 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已弃用的 `ANTHROPIC_SMALL_FAST_MODEL` 时才生效，因为 Amazon Bedrock 否则会在 [默认 Sonnet 模型或会话区域中的主模型](/docs/zh-CN/amazon-bedrock#4-pin-model-versions) 上运行后台任务 |

189| `ANTHROPIC_VERTEX_BASE_URL` | 覆盖 Google Cloud 的 Agent Platform 端点 URL。用于自定义 Google Cloud 的 Agent Platform 端点或通过 [LLM 网关](/docs/zh-CN/llm-gateway) 路由时。请参阅 [Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) |189| `ANTHROPIC_VERTEX_BASE_URL` | 覆盖 Google Cloud's Agent Platform 端点 URL。用于自定义 Google Cloud's Agent Platform 端点或通过 [LLM 网关](/docs/zh-CN/llm-gateway) 路由。参见 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) |

190| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud 的 Agent Platform 请求所针对的 GCP 项目 ID。请参阅 [配置 GCP 凭证](/docs/zh-CN/google-vertex-ai#3-configure-gcp-credentials) |190| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 请求所针对的 GCP 项目 ID。参见 [配置 GCP 凭证](/docs/zh-CN/google-vertex-ai#3-configure-gcp-credentials) |

191| `ANTHROPIC_WORKSPACE_ID` | [工作负载身份联合](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作区 ID。当您的联合规则的范围涵盖多个工作区时设置此项，以便令牌交换知道要针对哪个工作区 |191| `ANTHROPIC_WORKSPACE_ID` | [工作负载身份联合](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作区 ID。当您的联合规则的范围涵盖多个工作区时设置此项，以便令牌交换知道要针对哪个工作区 |

192| `API_FORCE_IDLE_TIMEOUT` | 覆盖 5 分钟的正文空闲超时，当没有字节到达时中止流式模型响应。设置为 `0` 以关闭超时，例如当缓慢的 [网关](/docs/zh-CN/llm-gateway) 或本地模型在块之间暂停超过 5 分钟时，或设置为 `1` 以为每个提供商保持打开。未设置时，超时在除直接 Anthropic API 和 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 之外的提供商上处于活跃状态。[流监视狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) 独立运行，即使您在此处设置 `0`，也会中止长时间的静默暂停 |192| `API_FORCE_IDLE_TIMEOUT` | 覆盖 5 分钟的正文空闲超时，该超时在没有字节到达时中止流式模型响应。设置为 `0` 以关闭超时，例如当缓慢的 [网关](/docs/zh-CN/llm-gateway) 或本地模型在块之间暂停超过 5 分钟时，或设置为 `1` 以为每个提供商保持打开。未设置时，超时在除直接 Anthropic API 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 之外的提供商上处于活跃状态。[流监视狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) 独立运行，即使您在此处设置 `0`，也会中止长时间的无声暂停 |

194| `AWS_BEARER_TOKEN_BEDROCK` | Amazon Bedrock API 密钥用于身份验证（请参阅 [Amazon Bedrock API 密钥](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |194| `AWS_BEARER_TOKEN_BEDROCK` | Amazon Bedrock API 密钥用于身份验证（参见 [Amazon Bedrock API 密钥](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |

196| `BASH_MAX_OUTPUT_LENGTH` | Claude Code 读回到命令结果中的 bash 输出的最大字符数（默认值：30000；最大值：150000）。如果您设置了 [`bashOutputMaxChars`](/docs/zh-CN/settings-reference#bashoutputmaxchars) 设置，Claude Code 会忽略此变量。请参阅 [输出限制](/docs/zh-CN/tools-reference#output-limits) |196| `BASH_MAX_OUTPUT_LENGTH` | Claude Code 读回到命令结果中的 bash 输出的最大字符数（默认值：30000；最大值：150000）。如果您设置了 [`bashOutputMaxChars`](/docs/zh-CN/settings-reference#bashoutputmaxchars) 设置，Claude Code 会忽略此变量。参见 [输出限制](/docs/zh-CN/tools-reference#output-limits) |

198| `BETA_TRACING_ENDPOINT` | [详细测试版跟踪](/docs/zh-CN/monitoring-usage#traces-beta) 的 OTLP 端点：使用 `ENABLE_BETA_TRACING_DETAILED=1`，日志和跟踪转到那里而不是配置的导出器。在您的 shell、用户设置或托管设置中设置它。在 [项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env) 中被忽略 |198| `BETA_TRACING_ENDPOINT` | [详细测试版跟踪](/docs/zh-CN/monitoring-usage#traces-beta) 的 OTLP 端点：使用 `ENABLE_BETA_TRACING_DETAILED=1`，日志和跟踪转到那里而不是配置的导出器。在您的 shell、用户设置或托管设置中设置它。在 [项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env) 中被忽略 |

199| `CCR_FORCE_BUNDLE` | 设置为 `1` 以强制 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) 捆绑并上传您的本地存储库，即使 GitHub 访问可用 |199| `CCR_FORCE_BUNDLE` | 设置为 `1` 以强制 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) 捆绑并上传您的本地存储库，而不是从其远程克隆 |

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

201| `CLAUDE_AFK_COUNTDOWN_MS` | 在自动继续之前屏幕上的倒计时出现在未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话框上的毫秒数。默认 `20000`（20 秒），上限为自动继续超时。除非自动继续打开，否则无效；请参阅 [`askUserQuestionTimeout`](/docs/zh-CN/settings-reference#askuserquestiontimeout) 设置和 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更高版本 |201| `CLAUDE_AFK_COUNTDOWN_MS` | 在自动继续前多少毫秒屏幕上的倒计时出现在未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话上。默认 `20000`（20 秒），上限为自动继续超时。除非自动继续打开，否则无效；参见 [`askUserQuestionTimeout`](/docs/zh-CN/settings-reference#askuserquestiontimeout) 设置和 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更高版本 |

202| `CLAUDE_AFK_TIMEOUT_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话框在没有您的情况下自动继续之前的空闲时间（毫秒）。自动继续默认关闭；使用 [`askUserQuestionTimeout`](/docs/zh-CN/settings-reference#askuserquestiontimeout) 设置选择加入。此变量是演示和自动化测试的覆盖：设置时，它优先于该设置并打开自动继续，即使设置未设置或为 `never`。设置 `0` 不会关闭超时；它立即关闭对话框。在 v2.1.198 和 v2.1.199 中，自动继续默认打开，超时为 `60000`（60 秒）。需要 Claude Code v2.1.198 或更高版本 |202| `CLAUDE_AFK_TIMEOUT_MS` | 在未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话自动继续而无需您的多少毫秒空闲时间。自动继续默认关闭；使用 [`askUserQuestionTimeout`](/docs/zh-CN/settings-reference#askuserquestiontimeout) 设置选择加入。此变量是演示和自动化测试的覆盖：设置后，它优先于该设置并打开自动继续，即使设置未设置或为 `never`。设置 `0` 不会关闭超时；它立即关闭对话。在 v2.1.198 和 v2.1.199 中，自动继续默认打开，超时为 `60000`（60 秒）。需要 Claude Code v2.1.198 或更高版本 |

203| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 设置为 `1` 以禁用所有内置 [子代理](/docs/zh-CN/sub-agents) 类型，例如 Explore 和 Plan。仅适用于非交互模式（`-p` 标志）。对于想要空白板的 SDK 用户很有用。这也删除了 `general-purpose`，即当 Agent 工具调用省略 `subagent_type` 时 Claude Code 运行的子代理。这样的调用然后失败，显示 [`subagent_type is required`](/docs/zh-CN/errors#subagent-type-is-required) |203| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 设置为 `1` 以禁用所有内置 [子代理](/docs/zh-CN/sub-agents) 类型，例如 Explore 和 Plan。仅在非交互模式（`-p` 标志）中应用。对于想要空白板的 SDK 用户很有用。这也删除了 `general-purpose`，即当 Agent 工具调用省略 `subagent_type` 时 Claude Code 运行的子代理。此类调用随后失败，显示 [`subagent_type is required`](/docs/zh-CN/errors#subagent-type-is-required) |

205| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 子代理的停滞超时时间（毫秒）。默认 `600000`（10 分钟）；如果您在流监视狗打开时提高 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，默认值会随之上升，如 [处理缓慢或停滞的 API 响应](/docs/zh-CN/agent-sdk/typescript#handle-slow-or-stalled-api-responses) 所述。计时器在每个流式进度事件上重置；如果在窗口内没有进度到达，Claude Code 会中止子代理并向父级报告停滞 |205| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 子代理的停滞超时时间（毫秒）。默认 `600000`（10 分钟）；如果您在流监视狗打开时提高 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，默认值会随之上升，如 [处理缓慢或停滞的 API 响应](/docs/zh-CN/agent-sdk/typescript#handle-slow-or-stalled-api-responses) 所述。计时器在每个流式进度事件上重置；如果在窗口内没有进度到达，Claude Code 中止子代理并向父级报告停滞 |

206| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 设置自动压缩窗口的百分比（1-100），在该百分比处自动压缩触发。使用较低的值（如 `50`）以更早压缩；该变量无法提高阈值，因此高于默认百分比的值会被忽略。它仅适用于在模型的上下文限制之前 [压缩的会话](/docs/zh-CN/model-config#context-window-and-auto-compaction)。适用于主对话和子代理 |206| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 设置自动压缩窗口的百分比（1-100），在该百分比处自动压缩触发。使用较低的值（如 `50`）以更早压缩；该变量无法提高阈值，因此高于默认百分比的值被忽略。它仅适用于在模型的上下文限制之前 [压缩的会话](/docs/zh-CN/model-config#context-window-and-auto-compaction)。适用于主对话和子代理 |

207| `CLAUDE_AUTO_BACKGROUND_TASKS` | 设置为 `1` 以强制启用长时间运行的代理任务的自动后台处理。启用后，子代理在运行约两分钟后移到后台。还在 Claude Code v2.1.212 或更高版本的非交互模式下启用 [长 MCP 工具调用的自动后台处理](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls) |207| `CLAUDE_AUTO_BACKGROUND_TASKS` | 设置为 `1` 以强制启用长时间运行的代理任务的自动后台处理。启用后，子代理在运行约两分钟后移到后台。也在 Claude Code v2.1.212 或更高版本的非交互模式中启用 [长 MCP 工具调用的自动后台处理](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls) |

208| `CLAUDE_AX_PREPARK_MS` | 在 [屏幕阅读器模式](/docs/zh-CN/accessibility#what-your-screen-reader-hears) 中，Claude Code 在行首等待光标后写入新行或更改行之前的毫秒数。默认 `50`。设置 `0` 以立即写入。Claude Code 将等待上限设置为 `5000`。需要 Claude Code v2.1.233 或更高版本 |208| `CLAUDE_AX_PREPARK_MS` | 在 [屏幕阅读器模式](/docs/zh-CN/accessibility#what-your-screen-reader-hears) 中，Claude Code 在光标位于行首时等待多少毫秒，然后写入新的或更改的行。默认 `50`。设置 `0` 以立即写入。Claude Code 将等待上限设置为 `5000`。需要 Claude Code v2.1.233 或更高版本 |

209| `CLAUDE_AX_SCREEN_READER` | 设置为 `1` 以呈现屏幕阅读器友好的输出：没有装饰性边框或动画的平面文本。设置为 `0` 以强制关闭屏幕阅读器模式，即使 [`axScreenReader`](/docs/zh-CN/settings-reference#axscreenreader) 为 `true`。[`--ax-screen-reader`](/docs/zh-CN/cli-reference#cli-flags) 标志优先。需要 Claude Code v2.1.181 或更高版本 |209| `CLAUDE_AX_SCREEN_READER` | 设置为 `1` 以呈现屏幕阅读器友好的输出：没有装饰性边框或动画的平面文本。设置为 `0` 以强制关闭屏幕阅读器模式，即使 [`axScreenReader`](/docs/zh-CN/settings-reference#axscreenreader) 为 `true`。[`--ax-screen-reader`](/docs/zh-CN/cli-reference#cli-flags) 标志优先。需要 Claude Code v2.1.181 或更高版本 |

210| `CLAUDE_AX_STARTUP_QUIET_MS` | 在 [屏幕阅读器模式](/docs/zh-CN/accessibility) 中，Claude Code 在启动确认行后保持第一个界面呈现的毫秒数，以便您的屏幕阅读器可以在新输出中断之前完整地说出该行。默认 `3000`。设置 `0` 以立即呈现。Claude Code 将保持上限设置为 `600000`（10 分钟）。您的第一次按键会提前结束保持。需要 Claude Code v2.1.217 或更高版本 |210| `CLAUDE_AX_STARTUP_QUIET_MS` | 在 [屏幕阅读器模式](/docs/zh-CN/accessibility) 中，Claude Code 在启动确认行后保持第一个界面呈现多少毫秒，以便您的屏幕阅读器可以在新输出中断之前完整地说出该行。默认 `3000`。设置 `0` 以立即呈现。Claude Code 将保持上限设置为 `600000`（10 分钟）。您的第一次按键会提前结束保持。需要 Claude Code v2.1.217 或更高版本 |

212| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 字节级流式空闲监视狗的超时时间（毫秒）；设置时，它优先于 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 用于该监视狗，并保持事件级监视狗不变。Claude Code 将此变量限制在 10 秒到 30 分钟之间。需要 Claude Code v2.1.210 或更高版本 |212| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 字节级流式空闲监视狗的超时时间（毫秒）；设置后，它优先于 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 用于该监视狗，并保持事件级监视狗不变。Claude Code 将此变量限制在 10 秒到 30 分钟之间。需要 Claude Code v2.1.210 或更高版本 |

213| `CLAUDE_CLIENT_PRESENCE_FILE` | 外部工具（如屏幕锁定侦听器）在您解锁屏幕时创建并在您锁定屏幕时删除的文件路径。文件存在时，Claude Code 跳过 [Remote Control 移动推送通知](/docs/zh-CN/remote-control#mobile-push-notifications)，因此您在主动使用计算机时停止接收推送。文件不存在或不可读时，通知照常发送。Claude Code 每次推送触发事件检查一次文件，而不是轮询它。需要 Claude Code v2.1.181 或更高版本 |213| `CLAUDE_CLIENT_PRESENCE_FILE` | 外部工具（如屏幕锁定侦听器）在您解锁屏幕时创建并在您锁定屏幕时删除的文件的路径。文件存在时，Claude Code 跳过 [Remote Control 移动推送通知](/docs/zh-CN/remote-control#mobile-push-notifications)，因此您在主动使用计算机时停止接收推送。文件不存在或不可读时，通知照常发送。Claude Code 每个推送触发事件检查一次文件，而不是轮询。需要 Claude Code v2.1.181 或更高版本 |

215| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 设置为 `1` 以从使用 `--add-dir` 指定的目录加载内存文件。加载 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。默认情况下，其他目录不加载内存文件 |215| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 设置为 `1` 以从使用 `--add-dir` 指定的目录加载内存文件。加载 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。默认情况下，其他目录不加载内存文件 |

216| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 设置为 `1` 以在 [全屏呈现](/docs/zh-CN/fullscreen) 中的每一帧上重新绘制整个屏幕，而不是发送增量更新。如果全屏模式显示陈旧或错位的文本片段，请使用此选项。Claude Code 在 Windows 上的后台会话和 [代理视图](/docs/zh-CN/agent-view) 上自动启用此功能 |216| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 设置为 `1` 以在 [全屏呈现](/docs/zh-CN/fullscreen) 中的每一帧上重新绘制整个屏幕，而不是发送增量更新。如果全屏模式显示陈旧或错位的文本片段，请使用此选项。Claude Code 在 Windows 上的后台会话和 [代理视图](/docs/zh-CN/agent-view) 上自动启用此功能 |

217| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 设置为 `1` 以在每个请求中发送 [effort](/docs/zh-CN/model-config#adjust-effort-level) 参数，即使 Claude Code 不将模型 ID 识别为支持 effort 的。在通过 [LLM 网关](/docs/zh-CN/llm-gateway) 或第三方提供商以自定义标识符提供模型时使用此选项。在 API 处拒绝 effort 参数的模型（包括 Claude 3 模型、Sonnet 4.0 和 4.5、Opus 4.0 和 4.1 以及 Haiku 4.5）仍被排除，因此请求不会失败 |217| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 设置为 `1` 以在每个请求中发送 [effort](/docs/zh-CN/model-config#adjust-effort-level) 参数，即使 Claude Code 不将模型 ID 识别为支持 effort 的。在通过 [LLM 网关](/docs/zh-CN/llm-gateway) 或第三方提供商使用自定义标识符提供模型时使用此选项。在 API 处拒绝 effort 参数的模型（包括 Claude 3 模型、Sonnet 4.0 和 4.5、Opus 4.0 和 4.1 以及 Haiku 4.5）仍被排除，因此请求不会失败 |

219| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 设置为 `0` 以停止 Claude Code 在发布新 [artifact](/docs/zh-CN/artifacts#create-an-artifact) 时自动打开浏览器 |219| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 设置为 `0` 以停止 Claude Code 在发布新 [artifact](/docs/zh-CN/artifacts#create-an-artifact) 时自动打开浏览器 |

220| `CLAUDE_CODE_ARTIFACT_COMMENTS` | 设置为 `0` 以停止 Claude 读取和回复 [artifact 上的评论](/docs/zh-CN/artifacts#collect-comments-on-an-artifact)。当 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` [关闭 artifact](/docs/zh-CN/artifacts#availability) 时无效。需要 Claude Code v2.1.221 或更高版本 |220| `CLAUDE_CODE_ARTIFACT_COMMENTS` | 设置为 `0` 以停止 Claude 读取和回复 [artifact 上的评论](/docs/zh-CN/artifacts#collect-comments-on-an-artifact)。当 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` [关闭 artifact](/docs/zh-CN/artifacts#availability) 时无效。需要 Claude Code v2.1.221 或更高版本 |

221| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | 设置为 `0` 以停止 Claude [自动回复发送给它的评论](/docs/zh-CN/artifacts#let-claude-reply-to-comments-on-its-own)。需要 Claude Code v2.1.228 或更高版本 |221| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | 设置为 `0` 以停止 Claude [自动回复发送给它的评论](/docs/zh-CN/artifacts#let-claude-reply-to-comments-on-its-own)。需要 Claude Code v2.1.228 或更高版本 |

222| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 设置为 `0` 以从系统提示的开头省略 [归属块](/docs/zh-CN/llm-gateway-protocol#system-prompt-attribution-block)，该块携带客户端版本和提示指纹。直接连接到 Anthropic API 的缓存无论如何都不受影响。在某些直接连接设置中，Claude Code 在 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器请求上保持块，即使您设置 `0`。在 [系统提示归属块](/docs/zh-CN/llm-gateway-protocol#system-prompt-attribution-block) 中，检查此覆盖的连接和凭证。在 v2.1.181 之前，该块在自定义基础 URL 和 Microsoft Foundry 连接上包含每个请求令牌，因此在这些版本上，当您的 LLM 网关在请求正文上缓存或将请求转发给第三方提供商，或当您直接连接到 Microsoft Foundry 时，将其设置为 `0` |222| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 设置为 `0` 以从系统提示的开头省略 [attribution 块](/docs/zh-CN/llm-gateway-protocol#system-prompt-attribution-block)，该块携带客户端版本和提示指纹。直接连接到 Anthropic API 的缓存无论如何都不受影响。在某些直接连接设置中，Claude Code 在 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分类器请求上保持块，即使您设置 `0`。在 [系统提示 attribution 块](/docs/zh-CN/llm-gateway-protocol#system-prompt-attribution-block) 中，检查此覆盖的连接和凭证。在 v2.1.181 之前，该块在自定义基础 URL 和 Microsoft Foundry 连接上包含每个请求的令牌，因此在这些版本上，当您的 LLM 网关在请求正文上缓存或转发请求到第三方提供商时，或当您直接连接到 Microsoft Foundry 时，将其设置为 `0` |

223| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | 启用 `CLAUDE_AUTO_BACKGROUND_TASKS` 时，Claude 检查仍在运行的 [后台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background) 的提醒之间的秒数。仅接受 `1` 到 `86400` 的纯整数；任何其他值或拼写读作未设置。未设置时，没有检查提醒。需要 Claude Code v2.1.248 或更高版本 |223| `CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS` | 当启用 `CLAUDE_AUTO_BACKGROUND_TASKS` 时，提醒 Claude 检查仍在运行的 [后台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background) 之间的秒数。仅接受 `1` 到 `86400` 的纯整数；任何其他值或拼写读作未设置。未设置时，没有检查提醒。需要 Claude Code v2.1.248 或更高版本 |

224| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 设置 [自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window)（令牌），从 `100000` 到 `1000000`。仅接受纯整数（如 `500000`）：像 `500k` 这样的值读作 `500` 并限制到 100K 最小值。有效窗口也上限为模型的上下文窗口。优先于 `/autocompact` 命令、`--autocompact` 标志和 `autoCompactWindow` 设置。状态行的 `used_percentage` 始终针对模型的完整上下文窗口进行测量，因此一旦设置此变量，该百分比不再指示何时运行压缩 |224| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 设置 [自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window)（令牌），从 `100000` 到 `1000000`。仅接受纯整数（如 `500000`）：像 `500k` 这样的值读作 `500` 并限制到 100K 最小值。有效窗口也上限为模型的上下文窗口。优先于 `/autocompact` 命令、`--autocompact` 标志和 `autoCompactWindow` 设置。状态行的 `used_percentage` 始终针对模型的完整上下文窗口进行测量，因此一旦设置此变量，该百分比不再指示何时压缩将运行 |

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

226| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 默认凭证提供商链生成凭证的时间（毫秒），然后请求失败，显示 [`AWS default-chain credential resolve timed out`](/docs/zh-CN/errors#aws-default-chain-credential-resolve-timed-out)（默认值：`60000`）。当链中的步骤合法需要更长时间时提高它，例如通过 `aws-vault` 等包装器进行基于浏览器的 SSO 登录和 MFA。适用于 Claude Code 使用默认链签名的任何地方：[Amazon Bedrock](/docs/zh-CN/amazon-bedrock#credential-caching-and-resolution-timeout)、[AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 和 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)。需要 Claude Code v2.1.207 或更高版本 |226| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 默认凭证提供商链生成凭证的时间（毫秒），然后请求失败，显示 [`AWS default-chain credential resolve timed out`](/docs/zh-CN/errors#aws-default-chain-credential-resolve-timed-out)（默认值：`60000`）。当链中的步骤合法需要更长时间时提高它，例如通过 `aws-vault` 等包装器进行基于浏览器的 SSO 登录和 MFA。适用于 Claude Code 使用默认链签名的任何地方：[Amazon Bedrock](/docs/zh-CN/amazon-bedrock#credential-caching-and-resolution-timeout)、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)。需要 Claude Code v2.1.207 或更高版本 |

227| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 在会话具有活跃 [Remote Control](/docs/zh-CN/remote-control) 连接时在 Bash 工具和 [hook 命令](/docs/zh-CN/hooks) 子进程中自动设置，连接结束时删除。值是会话的 ID，采用 `session_` 形式，与会话的 `claude.ai/code` URL 中出现的标识符相同，因此脚本可以链接回运行它的会话。需要 Claude Code v2.1.199 或更高版本。在 [云会话](/docs/zh-CN/claude-code-on-the-web) 中，改为读取 `CLAUDE_CODE_REMOTE_SESSION_ID` |227| `CLAUDE_CODE_BASH_EDIT_DIFF` | 设置为 `0` 以关闭 [Bash 命令更改的文件的 diff](/docs/zh-CN/hooks#bash)，或 `1` 以在每个权限模式中记录它。优先于 [`bashEditDiffEnabled`](/docs/zh-CN/settings-reference#basheditdiffenabled) 设置。需要 Claude Code v2.1.269 或更高版本 |

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

228| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | 设置为 `0` 以使 Claude Code 将 `0x08` 字节（也写作 `^H`）读作纯 Backspace，或 `1` 以读作 Ctrl+Backspace。任一值都替换平台默认值。默认情况下，Claude Code 在 Windows 上将其读作 Ctrl+Backspace，除非 `TERM_PROGRAM` 是 `mintty` 或 `TERM` 是 `cygwin`，在 macOS 和 Linux 上读作纯 Backspace。在 Windows 终端中设置 `0`，其中 [Backspace 删除整个单词](/docs/zh-CN/terminal-config#fix-backspace-deleting-a-whole-word-on-windows) |229| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | 设置为 `0` 以使 Claude Code 将 `0x08` 字节（也写作 `^H`）读作纯 Backspace，或 `1` 以读作 Ctrl+Backspace。任一值都替换平台默认值。默认情况下，Claude Code 在 Windows 上将其读作 Ctrl+Backspace，除非 `TERM_PROGRAM` 是 `mintty` 或 `TERM` 是 `cygwin`，在 macOS 和 Linux 上读作纯 Backspace。在 Windows 终端中设置 `0`，其中 [Backspace 删除整个单词](/docs/zh-CN/terminal-config#fix-backspace-deleting-a-whole-word-on-windows) |

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

230| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 通过 Bash、PowerShell 和 Monitor 工具、[hook](/docs/zh-CN/hooks) 命令和 [状态行](/docs/zh-CN/statusline) 命令生成的子进程中设置为 `1`。未为 stdio [MCP 服务器](/docs/zh-CN/mcp) 子进程设置，这些子进程是长期存在的并超过生成它们的会话。与 `CLAUDECODE` 不同，这仅在 Claude Code 启动子进程时由 Claude Code 本身设置，而不是由 IDE 扩展设置，因此它可靠地区分嵌套会话与在 IDE 集成终端中启动的顶级 `claude`。以这种方式启动的嵌套交互式 `claude` TUI 自动从 `--resume`、`--continue`、向上箭头历史和 `claude agents` 列表中排除。非交互式 `claude -p` 会话仍然持续。设置 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 以覆盖此排除。需要 Claude Code v2.1.172 或更高版本 |231| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 通过 Bash、PowerShell 和 Monitor 工具、[hook](/docs/zh-CN/hooks) 命令和 [状态行](/docs/zh-CN/statusline) 命令生成的子进程中设置为 `1`。未为 stdio [MCP 服务器](/docs/zh-CN/mcp) 子进程设置，这些是长期存在的并超过生成它们的会话。与 `CLAUDECODE` 不同，这仅在 Claude Code 启动子进程时由 Claude Code 本身设置，而不是由 IDE 扩展设置，因此它可靠地区分嵌套会话与在 IDE 集成终端中启动的顶级 `claude`。以这种方式启动的嵌套交互式 `claude` TUI 自动从 `--resume`、`--continue`、向上箭头历史和 `claude agents` 列表中排除。非交互式 `claude -p` 会话仍然持续。设置 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 以覆盖此排除。需要 Claude Code v2.1.172 或更高版本 |

234| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 在 v2.1.186 中删除，现在是无操作。以前为流式 API 请求的连接、TLS 和响应标头阶段设置单独的超时。使用 `API_TIMEOUT_MS` 获取每个请求的超时。对于流式请求的响应标头阶段，请参阅 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |235| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 在 v2.1.186 中删除，现在是无操作。以前为流式 API 请求的连接、TLS 和响应标头阶段设置单独的超时。使用 `API_TIMEOUT_MS` 获取每个请求的超时。对于流式请求的响应标头阶段，参见 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |

235| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆盖调试日志文件路径。尽管名称如此，这是文件路径，而不是目录。需要通过 `--debug`、`/debug` 或 `DEBUG` 环境变量单独启用调试模式：仅设置此变量不会启用日志记录。[`--debug-file`](/docs/zh-CN/cli-reference#cli-flags) 标志同时执行两者。默认为 `~/.claude/debug/<session-id>.txt` |236| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆盖调试日志文件路径。尽管名称如此，这是文件路径，而不是目录。需要通过 `--debug`、`/debug` 或 `DEBUG` 环境变量单独启用调试模式：仅设置此变量不会启用日志记录。[`--debug-file`](/docs/zh-CN/cli-reference#cli-flags) 标志同时执行两者。默认为 `~/.claude/debug/<session-id>.txt` |

236| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 写入调试日志文件的最小日志级别。值：`verbose`、`debug`（默认）、`info`、`warn`、`error`。设置为 `verbose` 以包含高容量诊断（如完整状态行命令输出），或提高到 `error` 以减少噪音 |237| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 写入调试日志文件的最小日志级别。值：`verbose`、`debug`（默认）、`info`、`warn`、`error`。设置为 `verbose` 以包含高容量诊断（如完整状态行命令输出），或提高到 `error` 以减少噪音 |

237| `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) |238| `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) |

238| `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 及更高版本无效，它们始终使用自适应推理 |239| `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 及更高版本无效，它们始终使用自适应推理 |

239| `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 或更高版本 |240| `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 或更高版本 |

240| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 设置为 `1` 以禁用 [advisor 工具](/docs/zh-CN/advisor)。`/advisor` 命令变为不可用，任何配置的 `advisorModel` 被忽略，`--advisor` 标志被接受但无效，因此传递它的现有脚本继续工作而不出错 |241| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 设置为 `1` 以禁用 [advisor 工具](/docs/zh-CN/advisor)。`/advisor` 命令变为不可用，任何配置的 `advisorModel` 被忽略，`--advisor` 标志被接受但无效，因此传递它的现有脚本继续工作而不出错 |

241| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 设置为 `1` 以关闭 [后台代理和代理视图](/docs/zh-CN/agent-view)：`claude agents`、`--bg`、`/background` 和按需主管。等同于 [`disableAgentView`](/docs/zh-CN/settings-reference#disableagentview) 设置 |242| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 设置为 `1` 以关闭 [后台代理和代理视图](/docs/zh-CN/agent-view)：`claude agents`、`--bg`、`/background` 和按需主管。等同于 [`disableAgentView`](/docs/zh-CN/settings-reference#disableagentview) 设置 |

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

243| `CLAUDE_CODE_DISABLE_ARTIFACT` | 设置为 `1` 以关闭 [Artifact](/docs/zh-CN/artifacts) 工具，该工具将会话输出发布为 claude.ai 上的私有网页。一旦设置，没有设置文件会打开该工具。要改为从设置文件关闭该工具，请将 [`enableArtifact`](/docs/zh-CN/settings-reference#enableartifact) 设置为 `false`；已弃用的 [`disableArtifact`](/docs/zh-CN/settings-reference#disableartifact) 键也会关闭它 |244| `CLAUDE_CODE_DISABLE_ARTIFACT` | 设置为 `1` 以关闭 [Artifact](/docs/zh-CN/artifacts) 工具，该工具将会话输出发布为 claude.ai 上的私有网页。设置后，没有设置文件会打开该工具。要改为从设置文件关闭该工具，请将 [`enableArtifact`](/docs/zh-CN/settings-reference#enableartifact) 设置为 `false`；已弃用的 [`disableArtifact`](/docs/zh-CN/settings-reference#disableartifact) 密钥也会关闭它 |

245| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 设置为 `1` 以禁用 [自动内存](/docs/zh-CN/memory#auto-memory)。设置为 `0` 以强制启用自动内存，即使 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-CN/settings-reference#automemoryenabled) 会禁用它。禁用时，Claude 不创建或加载自动内存文件 |246| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 设置为 `1` 以禁用 [自动内存](/docs/zh-CN/memory#auto-memory)。设置为 `0` 以强制启用自动内存，即使 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-CN/settings-reference#automemoryenabled) 会禁用它。禁用时，Claude 不创建或加载自动内存文件 |

246| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 设置为 `1` 以禁用所有后台任务功能，包括 Bash 和子代理工具上的 `run_in_background` 参数、自动后台处理和 Ctrl+B 快捷键 |247| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 设置为 `1` 以禁用所有后台任务功能，包括 Bash 和子代理工具上的 `run_in_background` 参数、自动后台处理和 Ctrl+B 快捷键 |

247| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 设置为 `1` 以停止 Claude Code 将 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 流式响应（缺少或空的 `Content-Type` 标头）视为 Amazon Bedrock 的二进制事件流。默认情况下，Claude Code 假设网关从其他未修改的响应中删除了标头，因此它解码正文并继续流式传输。仅为也将流重新发出为服务器发送事件的网关设置此选项；Claude Code 然后将无标头正文读作服务器发送事件。需要 Claude Code v2.1.239 或更高版本 |248| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 设置为 `1` 以停止 Claude Code 将缺少或空的 `Content-Type` 标头的 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 流式响应视为 Amazon Bedrock 的二进制事件流。默认情况下，Claude Code 假设网关从其他未修改的响应中删除了标头，因此它解码正文并流式处理继续工作。仅为也将流重新发出为服务器发送事件的网关设置此项；Claude Code 随后将无标头正文读作服务器发送事件。需要 Claude Code v2.1.239 或更高版本 |

248| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 设置为 `1` 以跳过检查 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 流式响应是否携带 `application/vnd.amazon.eventstream` 内容类型。没有此变量，当响应携带不同的内容类型时，Claude Code 会因命名该类型的错误而失败请求，这意味着 [网关或代理正在转换响应](/docs/zh-CN/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。配置网关以转发 `Content-Type` 标头和正文不修改，而不是设置此变量。需要 Claude Code v2.1.208 或更高版本 |249| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 设置为 `1` 以跳过检查 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 流式响应是否携带 `application/vnd.amazon.eventstream` 内容类型。没有此变量，当响应携带不同的内容类型时，Claude Code 失败请求，显示命名该类型的错误，这意味着 [网关或代理正在转换响应](/docs/zh-CN/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。配置网关以转发 `Content-Type` 标头和正文未修改，而不是设置此变量。需要 Claude Code v2.1.208 或更高版本 |

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

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

251| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 设置为 `1` 以禁用 Claude Code 包含的 [skills](/docs/zh-CN/skills) 和工作流：捆绑的 skills 和工作流被完全删除，而内置命令（如 `/init`）保持可输入但对模型隐藏。`/doctor` 保持可输入，如内置命令；使用 `DISABLE_DOCTOR_COMMAND` 隐藏它。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 Skills 不受影响。等同于 [`disableBundledSkills`](/docs/zh-CN/settings-reference#disablebundledskills) 设置 |252| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 设置为 `1` 以禁用 Claude Code 包含的 [skills](/docs/zh-CN/skills) 和工作流：捆绑的 skills 和工作流被完全删除，而内置命令（如 `/init`）保持可输入但从模型中隐藏。`/doctor` 保持可输入，如内置命令；使用 `DISABLE_DOCTOR_COMMAND` 隐藏它。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 Skills 不受影响。等同于 [`disableBundledSkills`](/docs/zh-CN/settings-reference#disablebundledskills) 设置 |

252| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 设置为 `1` 以保持 [Chrome 中的 Claude](/docs/zh-CN/chrome) 浏览器工具可用，同时省略系统提示的 Chrome 部分和 `/claude-in-chrome` [捆绑 skill](/docs/zh-CN/skills#bundled-skills)。对于嵌入 Claude Code 并提供自己的浏览器指导的主机。需要 Claude Code v2.1.257 或更高版本 |253| `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 或更高版本 |

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

255| `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) 涵盖覆盖应用的位置 |256| `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) 涵盖覆盖应用的位置 |

256| `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 或更高版本 |257| `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 或更高版本 |

258| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 设置为 `1` 以禁用"Claude 做得怎么样？"会话质量调查。当 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 被设置时，调查也被禁用，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 选择重新加入。要设置样本率而不是完全禁用，请使用 [`feedbackSurveyRate`](/docs/zh-CN/settings-reference#feedbacksurveyrate) 设置。请参阅 [会话质量调查](/docs/zh-CN/data-usage#session-quality-surveys) |259| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 设置为 `1` 以禁用"Claude 表现如何？"会话质量调查。当设置 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时，调查也被禁用，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 选择重新加入。要改为设置样本率而不是完全禁用，请使用 [`feedbackSurveyRate`](/docs/zh-CN/settings-reference#feedbacksurveyrate) 设置。参见 [会话质量调查](/docs/zh-CN/data-usage#session-quality-surveys) |

259| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 设置为 `1` 以禁用文件 [checkpointing](/docs/zh-CN/checkpointing)。`/rewind` 命令将无法恢复代码更改。覆盖 [`fileCheckpointingEnabled`](/docs/zh-CN/settings-reference#filecheckpointingenabled) 设置 |260| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 设置为 `1` 以禁用文件 [checkpointing](/docs/zh-CN/checkpointing)。`/rewind` 命令将无法恢复代码更改。覆盖 [`fileCheckpointingEnabled`](/docs/zh-CN/settings-reference#filecheckpointingenabled) 设置 |

260| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 设置为 `1` 以从 Claude 的系统提示中删除内置提交和 PR 工作流说明以及 git 状态快照。在使用自己的 git 工作流 skills 时很有用。当设置时优先于 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions) 设置 |261| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 设置为 `1` 以从 Claude 的系统提示中删除内置提交和 PR 工作流指令以及 git 状态快照。在使用您自己的 git 工作流 skills 时很有用。当设置时优先于 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions) 设置 |

261| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 设置为 `1` 以防止在 Anthropic API 上自动重新映射 Opus 4.0 和 4.1 到当前 Opus 版本。在您想有意固定较旧模型时使用。重新映射不在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上运行 |262| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 设置为 `1` 以防止在 Anthropic API 上自动重新映射 Opus 4.0 和 4.1 到当前 Opus 版本。在您想有意固定较旧模型时使用。重新映射不在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上运行 |

262| `CLAUDE_CODE_DISABLE_MOUSE` | 设置为 `1` 以禁用 [全屏呈现](/docs/zh-CN/fullscreen) 中的鼠标跟踪。使用 `PgUp` 和 `PgDn` 的键盘滚动仍然有效。使用此选项保持终端的本机选择复制行为 |263| `CLAUDE_CODE_DISABLE_MOUSE` | 设置为 `1` 以在 [全屏呈现](/docs/zh-CN/fullscreen) 中禁用鼠标跟踪。使用 `PgUp` 和 `PgDn` 的键盘滚动仍然有效。使用此选项保持您终端的本机选择复制行为 |

263| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 设置为 `1` 以禁用 [全屏呈现](/docs/zh-CN/fullscreen) 中的点击、拖动和悬停处理，同时保持鼠标滚轮滚动。当您希望滚轮滚动在 Claude Code 内工作但不希望点击定位光标、展开工具输出或打开链接时使用此选项。设置两者时 `CLAUDE_CODE_DISABLE_MOUSE` 优先。需要 Claude Code v2.1.195 或更高版本 |264| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 设置为 `1` 以在 [全屏呈现](/docs/zh-CN/fullscreen) 中禁用点击、拖动和悬停处理，同时保持鼠标滚轮滚动。在您想要滚轮滚动在 Claude Code 内工作但不想要点击定位光标、展开工具输出或打开链接时使用此选项。当两者都设置时，`CLAUDE_CODE_DISABLE_MOUSE` 优先。需要 Claude Code v2.1.195 或更高版本 |

264| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | 设置为 `1` 以停止 Claude Code 在 API 请求因连接级错误（如连接重置或 TLS 握手错误）失败时重新读取 [mTLS 客户端证书和密钥](/docs/zh-CN/network-config#mtls-authentication)。禁用重新加载后，Claude Code 仅在下次应用设置或下次启动时加载轮换的文件。需要 Claude Code v2.1.232 或更高版本 |265| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | 设置为 `1` 以停止 Claude Code 在 API 请求因连接级错误（如连接重置或 TLS 握手错误）失败时重新读取 [mTLS 客户端证书和密钥](/docs/zh-CN/network-config#mtls-authentication)。禁用重新加载后，Claude Code 仅在下次应用设置或下次启动时加载轮换的文件。需要 Claude Code v2.1.232 或更高版本 |

265| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 设置为任何非空值（如 `1`）以禁用非必要网络流量：自动更新、遥测、错误报告、`/feedback` 命令、[Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)、发行说明、[PR 和 MR 状态徽章](/docs/zh-CN/interactive-mode#pr-review-status) 检查以及可用性检查（如 [快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 检查）。它还停止 [插件 `command` 源的后台运行](/docs/zh-CN/plugin-marketplaces#when-claude-code-re-runs-the-command)，这些是本地命令而不是网络流量，因为它们可能触发依赖项安装。**将其设置为 `0` 或 `false` 仍会禁用此流量**，与大多数打开/关闭变量不同；取消设置变量以再次允许它。还禁用功能标志获取，这使 [Remote Control](/docs/zh-CN/remote-control#requirements) 和其他 [需要功能标志获取的功能](#features-that-need-feature-flag-fetching) 不可用。官方插件市场自动安装不涵盖；使用 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 禁用它。不影响 [网关模型发现](/docs/zh-CN/llm-gateway-connect#add-gateway-models-to-the-model-picker)，它有自己的选择加入 |266| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 设置为任何非空值（如 `1`）以禁用非必要网络流量：自动更新、遥测、错误报告、`/feedback` 命令、[Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)、发行说明、[PR 和 MR 状态徽章](/docs/zh-CN/interactive-mode#pr-review-status) 检查以及可用性检查（如 [快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 检查）。它也停止 [插件 `command` 源的后台运行](/docs/zh-CN/plugin-marketplaces#when-claude-code-re-runs-the-command)，这是本地命令而不是网络流量，因为它们可以触发依赖项安装。**将其设置为 `0` 或 `false` 仍会禁用此流量**，与大多数打开/关闭变量不同；取消设置变量以再次允许它。也禁用功能标志获取，这使 [Remote Control](/docs/zh-CN/remote-control#requirements) 和其他 [需要功能标志获取的功能](#features-that-need-feature-flag-fetching) 不可用。官方插件市场自动安装不被覆盖；使用 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 禁用它。不影响 [网关模型发现](/docs/zh-CN/llm-gateway-connect#add-gateway-models-to-the-model-picker)，它有自己的选择加入 |

267| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 设置为 `1` 以在您在终端中输入或专注时发送 `PushNotification` 工具的桌面通知。默认情况下，当工具检测到最近的键盘活动或终端焦点时，工具会跳过桌面通知和 [移动推送](/docs/zh-CN/remote-control#mobile-push-notifications)。此变量仅禁用该本地检查，因此服务器在检测到您处于活跃状态时仍可以抑制移动推送。需要 Claude Code v2.1.193 或更高版本 |268| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 设置为 `1` 以在您在终端中输入或聚焦时发送 `PushNotification` 工具的桌面通知。默认情况下，当工具检测到最近的键盘活动或终端焦点时，工具跳过桌面通知和 [移动推送](/docs/zh-CN/remote-control#mobile-push-notifications)。此变量仅禁用该本地检查，因此服务器在检测到您处于活跃状态时仍可以抑制移动推送。需要 Claude Code v2.1.193 或更高版本 |

268| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 设置为 `1` 以禁用官方插件市场的自动注册。Claude Code 在即将注册市场时读取该变量，通常在机器的第一次交互启动期间。如果变量在该点设置，Claude Code 永久跳过注册。稍后取消设置变量不会撤销跳过。随时运行 `claude plugin marketplace add anthropics/claude-plugins-official` 以注册市场 |269| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 设置为 `1` 以禁用官方插件市场的自动注册。Claude Code 在即将注册市场时读取变量，通常在机器的第一次交互启动期间。如果变量在该点设置，Claude Code 永久跳过注册。稍后取消设置变量不会撤销跳过。随时运行 `claude plugin marketplace add anthropics/claude-plugins-official` 以注册市场 |

269| `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 或更高版本 |270| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 设置为 `1` 以停止 Claude Code 在 Claude Code 将它们发送到 Agent SDK 的 `canUseTool` 回调的会话中运行您的 [`Notification` 钩子用于未回答的权限请求](/docs/zh-CN/hooks#notification)，这是 Claude Desktop 和 VS Code 扩展如何托管 Claude Code 的方式。在终端会话中无效。需要 Claude Code v2.1.233 或更高版本 |

272| `CLAUDE_CODE_DISABLE_THINKING` | 设置为 `1` 以从 API 请求中完全省略 `thinking` 参数。这是拒绝该参数的代理和网关的兼容性选项。在默认思考的模型上，省略参数意味着模型仍可能思考。要在 Anthropic API 上显式禁用 [扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，请改用 `MAX_THINKING_TOKENS=0`。两个变量都不会在 Fable 模型上关闭思考，Fable 模型无法关闭思考。在 [第三方提供商](/docs/zh-CN/third-party-integrations) 上，`MAX_THINKING_TOKENS=0` 同样省略参数，因此两个变量在那里的行为相同 |273| `CLAUDE_CODE_DISABLE_THINKING` | 设置为 `1` 以从 API 请求中完全省略 `thinking` 参数。这是代理和网关拒绝该参数的兼容性选项。在默认思考的模型上，省略参数意味着模型仍可能思考。要在 Anthropic API 上明确禁用 [扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，请改用 `MAX_THINKING_TOKENS=0`。两个变量都不会在 Fable 模型上关闭思考，Fable 模型无法关闭思考。在 [第三方提供商](/docs/zh-CN/third-party-integrations) 上，`MAX_THINKING_TOKENS=0` 同样省略参数，因此两个变量在那里的行为相同 |

273| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 设置为 `1` 以跳过当 Claude Code 不识别模型 ID（如 [LLM 网关](/docs/zh-CN/llm-gateway) 别名）时的主动 [自动压缩](/docs/zh-CN/costs#reduce-token-usage)。没有此变量，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 或更高版本 |274| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 设置为 `1` 以在 Claude Code 不识别模型 ID（如 [LLM 网关](/docs/zh-CN/llm-gateway) 别名）时跳过主动 [自动压缩](/docs/zh-CN/costs#reduce-token-usage)。没有此变量，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 或更高版本 |

274| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 设置为 `1` 以禁用 [全屏呈现](/docs/zh-CN/fullscreen) 中的虚拟滚动并呈现转录中的每条消息。如果全屏模式中的滚动显示消息应出现的空白区域，请使用此选项 |275| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 设置为 `1` 以在 [全屏呈现](/docs/zh-CN/fullscreen) 中禁用虚拟滚动并呈现成绩单中的每条消息。如果全屏模式中的滚动显示应显示消息的空白区域，请使用此选项 |

275| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 设置为 `1` 以禁用 [工作流](/docs/zh-CN/workflows#turn-workflows-off)。等同于 [`disableWorkflows`](/docs/zh-CN/settings-reference#disableworkflows) 设置 |276| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 设置为 `1` 以禁用 [工作流](/docs/zh-CN/workflows#turn-workflows-off)。等同于 [`disableWorkflows`](/docs/zh-CN/settings-reference#disableworkflows) 设置 |

276| `CLAUDE_CODE_EFFORT_LEVEL` | 为支持的模型设置 effort 级别。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型默认值。可用级别取决于模型。优先于 `--effort`、`/effort` 和 `modelSettings` 和 `effortLevel` 设置。[`maxEffortLevel`](/docs/zh-CN/settings-reference#maxeffortlevel) 上限仍然适用。请参阅 [调整 effort 级别](/docs/zh-CN/model-config#adjust-effort-level) |277| `CLAUDE_CODE_EFFORT_LEVEL` | 为支持的模型设置 effort 级别。值：`low`、`medium`、`high`、`xhigh`、`max` 或 `auto` 以使用模型默认值。可用级别取决于模型。优先于 `--effort`、`/effort` 和 `modelSettings` 和 `effortLevel` 设置。[`maxEffortLevel`](/docs/zh-CN/settings-reference#maxeffortlevel) 上限仍然适用。参见 [调整 effort 级别](/docs/zh-CN/model-config#adjust-effort-level) |

277| `CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT` | 设置为 `1` 以启用将额外文本附加到除 [forked 子代理](/docs/zh-CN/sub-agents#fork-the-current-conversation) 之外的每个 [子代理](/docs/zh-CN/sub-agents) 的系统提示末尾。[`--append-subagent-system-prompt`](/docs/zh-CN/cli-reference#cli-flags) 和 [`--append-subagent-system-prompt-file`](/docs/zh-CN/cli-reference#cli-flags) 标志提供附加的文本并自动设置此变量，因此您不需要自己设置它。需要 Claude Code v2.1.205 或更高版本 |278| `CLAUDE_CODE_ENABLE_APPEND_SUBAGENT_PROMPT` | 设置为 `1` 以启用将额外文本附加到除 [forked 子代理](/docs/zh-CN/sub-agents#fork-the-current-conversation) 之外的每个 [子代理](/docs/zh-CN/sub-agents) 的系统提示末尾。[`--append-subagent-system-prompt`](/docs/zh-CN/cli-reference#cli-flags) 和 [`--append-subagent-system-prompt-file`](/docs/zh-CN/cli-reference#cli-flags) 标志提供附加的文本并自动设置此变量，因此您不需要自己设置它。需要 Claude Code v2.1.205 或更高版本 |

278| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 为了与较旧版本兼容而接受，无效。自动模式在每个提供商上默认可用，包括 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的 [Claude 应用网关](/docs/zh-CN/claude-apps-gateway) 会话。在 v2.1.158 到 v2.1.206 中，需要将此设置为 `1` 以在这些提供商上提供 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) |279| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 为了与较旧版本兼容而接受，无效。自动模式在每个提供商上默认可用，包括 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 和已登录的 [Claude 应用网关](/docs/zh-CN/claude-apps-gateway) 会话。在 v2.1.158 到 v2.1.206 中，设置此项为 `1` 是在这些提供商上使 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 可用所必需的 |

279| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆盖 [会话回顾](/docs/zh-CN/interactive-mode#session-recap) 可用性。设置为 `0` 以强制关闭回顾，无论 `/config` 切换如何。设置为 `1` 以在 [`awaySummaryEnabled`](/docs/zh-CN/settings-reference#awaysummaryenabled) 为 `false` 时强制打开回顾。优先于设置和 `/config` 切换 |280| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆盖 [会话回顾](/docs/zh-CN/interactive-mode#session-recap) 可用性。设置为 `0` 以强制关闭回顾，无论 `/config` 切换如何。设置为 `1` 以在 [`awaySummaryEnabled`](/docs/zh-CN/settings-reference#awaysummaryenabled) 为 `false` 时强制打开回顾。优先于设置和 `/config` 切换 |

280| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 设置为 `1` 以在后台安装完成后在 [非交互模式](/docs/zh-CN/headless) 中的转边界处刷新插件状态。默认关闭，因为刷新在会话中期更改系统提示，这会使该转的 [提示缓存](/docs/zh-CN/prompt-caching) 失效 |281| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 设置为 `1` 以在后台安装完成后在 [非交互模式](/docs/zh-CN/headless) 中的转边界处刷新插件状态。默认关闭，因为刷新在会话中期更改系统提示，这会使该转的 [提示缓存](/docs/zh-CN/prompt-caching) 失效 |

281| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 设置为 `1` 以在 Anthropic 绑定的非必要流量被阻止时将"Claude 做得怎么样？"会话质量调查路由到您自己的 [OpenTelemetry 收集器](/docs/zh-CN/monitoring-usage)。调查评级仅作为 OTEL 事件发出到您配置的收集器。在此模式下，没有调查数据发送到 Anthropic。当 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 被设置时适用，否则无效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和组织产品反馈政策优先 |282| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 设置为 `1` 以在 Anthropic 绑定的非必要流量被阻止时将"Claude 表现如何？"会话质量调查路由到您自己的 [OpenTelemetry 收集器](/docs/zh-CN/monitoring-usage)。调查评级仅作为 OTEL 事件发出到您配置的收集器。在此模式下，没有调查数据发送到 Anthropic。当设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 时应用，否则无效。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和组织产品反馈政策优先 |

282| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具调用输入是否在 Claude 生成时从 API 流式传输。关闭此选项时，大型工具输入（如长文件写入）仅在 Claude 完成生成后到达，这可能看起来像它挂起了。在 Anthropic API 上默认启用。在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上，在部署的容器支持的每个模型上启用。设置为 `0` 以选择退出。设置为 `1` 以在通过 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 通过代理路由时强制打开。在 Microsoft Foundry 和 [网关](/docs/zh-CN/llm-gateway) 连接上默认关闭 |283| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具调用输入是否在 API 生成时从 API 流式传输。关闭此选项时，大型工具输入（如长文件写入）仅在 Claude 完成生成后到达，这可能看起来像它挂起了。在 Anthropic API 上默认启用。在 Amazon Bedrock 和 Google Cloud's Agent Platform 上，在部署的容器支持的每个模型上启用。设置为 `0` 以选择退出。设置为 `1` 以在通过 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 通过代理路由时强制打开。在 Microsoft Foundry 和 [网关](/docs/zh-CN/llm-gateway) 连接上默认关闭 |

283| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 设置为 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 兼容网关（如 LiteLLM、Kong 或内部代理）时从网关的 `/v1/models` 端点填充 `/model` 选择器。默认关闭，因为由共享 API 密钥支持的网关会向每个用户显示密钥可以访问的每个模型。发现的模型仍由会话接收的 [`availableModels`](/docs/zh-CN/settings-reference#availablemodels) 允许列表过滤；通过 [MDM 或托管设置文件](/docs/zh-CN/managed-settings#delivery-mechanisms) 传递列表，因为 [服务器管理的传递在网关配置上不可用](/docs/zh-CN/server-managed-settings#platform-availability) |284| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 设置为 `1` 以在 `ANTHROPIC_BASE_URL` 指向 Anthropic 兼容网关（如 LiteLLM、Kong 或内部代理）时从您的网关的 `/v1/models` 端点填充 `/model` 选择器。默认关闭，因为由共享 API 密钥支持的网关会否则向密钥可以访问的每个用户显示每个模型。发现的模型仍由会话接收的 [`availableModels`](/docs/zh-CN/settings-reference#availablemodels) 允许列表过滤；通过 [MDM 或托管设置文件](/docs/zh-CN/managed-settings#delivery-mechanisms) 传递列表，因为 [服务器管理的传递在网关配置上不可用](/docs/zh-CN/server-managed-settings#platform-availability) |

285| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 设置为 `false` 以关闭提示建议，即在提示输入中出现的灰显预测。优先于 [`promptSuggestionEnabled`](/docs/zh-CN/settings-reference#promptsuggestionenabled) 设置，这是 `/config` 中的**提示建议**切换写入的。Claude Code 还 [在您的帐户接近或达到使用限制时暂停建议](/docs/zh-CN/interactive-mode#when-claude-code-skips-suggestions)。设置为 `true` 以在达到限制之前保持它们打开。需要 Claude Code v2.1.238 或更高版本。请参阅 [提示建议](/docs/zh-CN/interactive-mode#prompt-suggestions) |286| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 设置为 `false` 以关闭提示建议，即出现在您的提示输入中的灰显预测。优先于 [`promptSuggestionEnabled`](/docs/zh-CN/settings-reference#promptsuggestionenabled) 设置，这是 `/config` 中的**提示建议**切换写入的内容。Claude Code 也 [在您的帐户接近或达到使用限制时暂停建议](/docs/zh-CN/interactive-mode#when-claude-code-skips-suggestions)。设置为 `true` 以在达到限制之前保持它们打开。需要 Claude Code v2.1.238 或更高版本。参见 [提示建议](/docs/zh-CN/interactive-mode#prompt-suggestions) |

286| `CLAUDE_CODE_ENABLE_TASKS` | 选择 Claude Code 在 [具有它们的会话](/docs/zh-CN/tools-reference#task-tool-availability) 中提供哪些任务跟踪工具。默认情况下，Claude Code 提供 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 和 `TaskList`。设置为 `0` 以改为获取旧版 `TodoWrite` 工具。请参阅 [任务列表](/docs/zh-CN/interactive-mode#task-list) |287| `CLAUDE_CODE_ENABLE_TASKS` | 选择 Claude Code 在 [具有它们的会话](/docs/zh-CN/tools-reference#task-tool-availability) 中提供的任务跟踪工具。默认情况下，Claude Code 提供 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 和 `TaskList`。设置为 `0` 以改为获取旧版 `TodoWrite` 工具。参见 [任务列表](/docs/zh-CN/interactive-mode#task-list) |

287| `CLAUDE_CODE_ENABLE_TELEMETRY` | 设置为 `1` 以启用指标和日志记录的 OpenTelemetry 数据收集。在配置 OTel 导出器之前需要。请参阅 [监控](/docs/zh-CN/monitoring-usage) |288| `CLAUDE_CODE_ENABLE_TELEMETRY` | 设置为 `1` 以启用指标和日志记录的 OpenTelemetry 数据收集。在配置 OTel 导出器之前需要。参见 [监控](/docs/zh-CN/monitoring-usage) |

288| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 设置为 `1` 以在 [任务工具可用性](/docs/zh-CN/tools-reference#task-tool-availability) 下列出的模型上获取任务跟踪工具，Claude Code 否则会将其排除。`CLAUDE_CODE_ENABLE_TASKS` 仍选择 Task 工具或 `TodoWrite`。需要 Claude Code v2.1.233 或更高版本 |289| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 设置为 `1` 以在每个模型上获取任务跟踪工具。没有它，Claude Code 仅在 [任务工具可用性](/docs/zh-CN/tools-reference#task-tool-availability) 下列出的模型上默认提供它们。`CLAUDE_CODE_ENABLE_TASKS` 仍选择 Task 工具或 `TodoWrite`。需要 Claude Code v2.1.233 或更高版本 |

291| `CLAUDE_CODE_EXTRA_BODY` | JSON 对象以合并到每个 API 请求正文的顶级。对传递 Claude Code 不直接公开的提供商特定参数很有用。在您的 shell 中导出的值也适用于您使用 `claude agents` 或 `--bg` 调度的 [后台会话](/docs/zh-CN/agent-view)。在 v2.1.206 之前，后台会话忽略了 shell 导出的值，并使用后台主管进程继承的任何副本 |292| `CLAUDE_CODE_EXTRA_BODY` | JSON 对象以合并到每个 API 请求正文的顶级。对于传递 Claude Code 不直接公开的提供商特定参数很有用。在您的 shell 中导出的值也适用于您使用 `claude agents` 或 `--bg` 分派的 [后台会话](/docs/zh-CN/agent-view)。在 v2.1.206 之前，后台会话忽略了 shell 导出的值并使用了后台主管进程继承的任何副本 |

293| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 设置为 `1` 以强制转录持久性、提示历史和 `claude agents` 注册，即使此 `claude` 是从另一个 Claude Code 会话内启动的。当继承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如来自 `screen` 会话或由 Claude Code 的 Bash 工具首先启动的后台启动器）导致真正的顶级会话被误分类为嵌套时使用。从 v2.1.178 开始，Claude Code 自动检测 tmux 情况并忽略继承的标记，因此 tmux 不再需要此变量。也在 v2.1.169 及更早版本上受尊重；对 v2.1.170 和 v2.1.171 无效，其中它覆盖的嵌套会话检测被删除 |294| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 设置为 `1` 以强制成绩单持久性、提示历史和 `claude agents` 注册，即使此 `claude` 是从另一个 Claude Code 会话内启动的。在继承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如来自 `screen` 会话或由 Claude Code 的 Bash 工具首先启动的后台启动器）导致真正的顶级会话被误分类为嵌套时使用。从 v2.1.178 开始，Claude Code 自动检测 tmux 情况并忽略继承的标记，因此 tmux 不再需要此变量。也在 v2.1.169 及更早版本上受尊重；对 v2.1.170 和 v2.1.171 无效，其中它覆盖的嵌套会话检测被删除 |

294| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 设置为 `1` 以在您的终端支持但未自动检测时强制 `~~text~~` 的删除线呈现，例如通过 SSH 而不转发 `TERM_PROGRAM`。没有这个，未检测到的终端显示文字 `~~` 标记而不是将文本呈现为删除线。需要 Claude Code v2.1.186 或更高版本 |295| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 设置为 `1` 以在您的终端支持但未自动检测时强制 `~~text~~` 的删除线呈现，例如通过 SSH 而不转发 `TERM_PROGRAM`。没有这个，未检测到的终端显示文字 `~~` 标记而不是将文本呈现为删除线。需要 Claude Code v2.1.186 或更高版本 |

295| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 设置为 `1` 以在您的终端支持但未自动检测时强制启用 DEC 私有模式 2026 [同步输出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)。对于实现 BSU/ESU 但不回复功能探针的 Emacs `eat` 等模拟器很有用。在 tmux 下无效。与 `CLAUDE_CODE_NO_FLICKER` 不同，后者切换到 [全屏呈现](/docs/zh-CN/fullscreen)，这不会改变渲染器 |296| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 设置为 `1` 以在您的终端支持但未自动检测时强制启用 DEC 私有模式 2026 [同步输出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)。对于实现 BSU/ESU 但不回复功能探针的 Emacs `eat` 等模拟器很有用。在 tmux 下无效。与 `CLAUDE_CODE_NO_FLICKER` 不同，后者切换到 [全屏呈现](/docs/zh-CN/fullscreen)，这不改变渲染器 |

296| `CLAUDE_CODE_FORK_SUBAGENT` | 控制 [fork 模式](/docs/zh-CN/sub-agents#turn-fork-mode-on-or-off)，它让 Claude 生成 [forked 子代理](/docs/zh-CN/sub-agents#fork-the-current-conversation) 本身，在交互式会话中默认打开。设置为 `1` 以在 `claude -p` 和 Agent SDK 中也打开它，或 `0` 以在每种会话中关闭它。无论 fork 模式是否打开，您都可以运行 `/subtask`。交互式默认需要 Claude Code v2.1.232 或更高版本；在较早的版本上，设置变量为 `1` 以打开 fork 模式 |297| `CLAUDE_CODE_FORK_SUBAGENT` | 控制 [fork 模式](/docs/zh-CN/sub-agents#turn-fork-mode-on-or-off)，它让 Claude 生成 [forked 子代理](/docs/zh-CN/sub-agents#fork-the-current-conversation) 本身，在交互式会话中默认打开。设置为 `1` 以在 `claude -p` 和 Agent SDK 中也打开它，或 `0` 以在每种会话中关闭它。无论 fork 模式是否打开，您都可以运行 `/subtask`。交互式默认需要 Claude Code v2.1.232 或更高版本；在较早版本上，设置变量为 `1` 以打开 fork 模式 |

297| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | 设置为 `1` 以在 `claude -p --output-format stream-json` 输出中发出 [子代理](/docs/zh-CN/sub-agents) 文本和思考块，与 [`--forward-subagent-text`](/docs/zh-CN/cli-reference#cli-flags) 标志相同的行为。当某个外部工具（harness）调用 `claude` 而自身无法传递该标志时，请使用该变量。与标志不同，标志在带 stream-json 输出的非交互模式之外使用时会以错误退出，而变量在那里会被忽略，以便在进程范围内设置该变量时嵌套调用仍能继续工作。需要 Claude Code v2.1.211 或更高版本 |298| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | 设置为 `1` 以在 `claude -p --output-format stream-json` 输出中发出 [子代理](/docs/zh-CN/sub-agents) 文本和思考块，与 [`--forward-subagent-text`](/docs/zh-CN/cli-reference#cli-flags) 标志相同的行为。当工具调用 `claude` 的工具无法自己传递标志时使用变量。与标志不同，标志在非交互模式下使用 stream-json 输出时以错误退出，变量在那里被忽略，以便嵌套调用在设置进程范围时继续工作。需要 Claude Code v2.1.211 或更高版本 |

298| `CLAUDE_CODE_GIT_BASH_PATH` | 仅限 Windows：Git Bash 可执行文件（`bash.exe`）的路径。当 Git Bash 已安装但不在您的 PATH 中时使用。如果路径不存在或文件未命名为 `bash.exe`、`sh.exe`、`bash` 或 `sh`，Claude Code 会忽略该变量并自动检测 Git Bash，就像它未设置一样，记录在 `--debug` 中可见的警告。在 v2.1.219 之前，当路径不存在时 Claude Code 在启动时退出，并使用任何现有文件作为 shell，而不检查它是否为 bash 或 sh。请参阅 [Windows 设置](/docs/zh-CN/setup#set-up-on-windows) |299| `CLAUDE_CODE_GIT_BASH_PATH` | 仅限 Windows：Git Bash 可执行文件（`bash.exe`）的路径。在 Git Bash 已安装但不在您的 PATH 中时使用。如果路径不存在或文件未命名为 `bash.exe`、`sh.exe`、`bash` 或 `sh`，Claude Code 忽略变量并自动检测 Git Bash，就像它未设置一样，记录可见的警告 `--debug`。在 v2.1.219 之前，当路径不存在时 Claude Code 在启动时退出，并使用任何现有文件作为 shell，而不检查它是否为 bash 或 sh。参见 [Windows 设置](/docs/zh-CN/setup#set-up-on-windows) |

299| `CLAUDE_CODE_GLOB_HIDDEN` | 设置为 `false` 以在 Claude 调用 [Glob 工具](/docs/zh-CN/tools-reference#glob-tool-behavior) 时从结果中排除点文件。默认包含。不影响 `@` 文件自动完成、`ls`、Grep 或 Read |300| `CLAUDE_CODE_GLOB_HIDDEN` | 设置为 `false` 以在 Claude 调用 [Glob 工具](/docs/zh-CN/tools-reference#glob-tool-behavior) 时从结果中排除点文件。默认包含。不影响 `@` 文件自动完成、`ls`、Grep 或 Read |

300| `CLAUDE_CODE_GLOB_NO_IGNORE` | 设置为 `false` 以使 [Glob 工具](/docs/zh-CN/tools-reference#glob-tool-behavior) 尊重 `.gitignore` 模式。默认情况下，Glob 返回所有匹配的文件，包括 gitignored 的文件。不影响 `@` 文件自动完成，它有自己的 [`respectGitignore` 设置](/docs/zh-CN/settings-reference#respectgitignore) |301| `CLAUDE_CODE_GLOB_NO_IGNORE` | 设置为 `false` 以使 [Glob 工具](/docs/zh-CN/tools-reference#glob-tool-behavior) 尊重 `.gitignore` 模式。默认情况下，Glob 返回所有匹配的文件，包括 gitignored 的文件。不影响 `@` 文件自动完成，它有自己的 [`respectGitignore` 设置](/docs/zh-CN/settings-reference#respectgitignore) |

302| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 后台工作可以让活跃目标等待多少分钟，然后 Claude Code [要求 Claude 检查它](/docs/zh-CN/goal#background-work-defers-evaluation)。默认 `30`。设置 `0` 以关闭检查。给出纯数字的整分钟，最多 `10080`，即一周。Claude Code 将任何其他值视为未设置并使用默认值。需要 Claude Code v2.1.234 或更高版本 |303| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 后台工作可以保持活跃目标等待多少分钟，然后 Claude Code [要求 Claude 检查它](/docs/zh-CN/goal#background-work-defers-evaluation)。默认 `30`。设置 `0` 以关闭检查。给出纯数字的整分钟，最多 `10080`，即一周。Claude Code 将任何其他值视为未设置并使用默认值。需要 Claude Code v2.1.234 或更高版本 |

305| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 设置为 `1` 以跳过 IDE 扩展的自动安装。等同于将 [`autoInstallIdeExtension`](/docs/zh-CN/settings-reference#autoinstallideextension) 设置为 `false` |306| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 设置为 `1` 以跳过 IDE 扩展的自动安装。等同于将 [`autoInstallIdeExtension`](/docs/zh-CN/settings-reference#autoinstallideextension) 设置为 `false` |

307| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 在 Agent 工具拒绝生成另一个之前，一个会话中可以运行多少个 [子代理](/docs/zh-CN/sub-agents#concurrent-subagent-limit)（默认值：20）。接受纯数字的正整数；任何其他内容都被忽略，因此变量可以调整上限但不能禁用它。需要 Claude Code v2.1.217 或更高版本 |308| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 在 Agent 工具拒绝生成另一个之前，一个会话中可以运行多少个 [子代理](/docs/zh-CN/sub-agents#concurrent-subagent-limit)（默认值：20）。仅接受纯数字的正整数；任何其他值被忽略，因此变量可以调整上限但不能禁用它。需要 Claude Code v2.1.217 或更高版本 |

308| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆盖 Claude Code 为活跃模型假设的上下文窗口大小。从 v2.1.193 开始，它的应用方式取决于 Claude Code 如何解析模型 ID；请参阅 [为网关或自定义模型 ID 纠正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。当通过 `ANTHROPIC_BASE_URL` 路由到模型时使用此选项，其上下文窗口与其名称的内置大小不匹配 |309| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆盖 Claude Code 为活跃模型假设的上下文窗口大小。从 v2.1.193 开始，它的应用方式取决于 Claude Code 如何解析模型 ID；参见 [为网关或自定义模型 ID 纠正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。在通过 `ANTHROPIC_BASE_URL` 路由到其上下文窗口与其名称的内置大小不匹配的模型时使用此选项 |

309| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 为大多数请求设置最大输出令牌数。默认值和上限因模型而异；请参阅 [最大输出令牌](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。Claude Code 为它不识别的模型 ID（如网关特定的名称）默认为 32000，并将高于模型上限的值降低到上限。增加此值会减少 [自动压缩](/docs/zh-CN/costs#reduce-token-usage) 触发之前可用的有效上下文窗口 |310| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 为大多数请求设置最大输出令牌数。默认值和上限因模型而异；参见 [最大输出令牌](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。Claude Code 为它不识别的模型 ID（如网关特定的名称）默认为 32000，并将高于模型上限的值降低到上限。增加此值会减少在 [自动压缩](/docs/zh-CN/costs#reduce-token-usage) 触发之前可用的有效上下文窗口 |

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

311| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | 在 v2.1.224 中删除，现在是无操作。以前上限了 Claude 可以在一个会话中使用 Agent 工具生成的 [子代理](/docs/zh-CN/sub-agents) 总数（默认值：200）；超过上限生成失败，显示 `Subagent spawn limit reached`。[并发子代理限制](/docs/zh-CN/sub-agents#concurrent-subagent-limit) 和 [深度限制](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents) 仍然适用 |312| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | 在 v2.1.224 中删除，现在是无操作。以前上限了 Claude 可以在一个会话中使用 Agent 工具生成的 [子代理](/docs/zh-CN/sub-agents) 总数（默认值：200）；超过上限生成失败，显示 `Subagent spawn limit reached`。[并发子代理限制](/docs/zh-CN/sub-agents#concurrent-subagent-limit) 和 [深度限制](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents) 仍然适用 |

312| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 主对话下方允许的 [子代理层](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents) 数（默认值：3）。在默认值处，子代理可以生成自己的子代理，第三层的子代理无法进一步生成；设置 `1` 以关闭嵌套。在 v2.1.217 到 v2.1.218 中，默认值为 1，因此子代理无法生成自己的，除非您提高限制；v2.1.219 将默认值提高到 3。接受纯数字的正整数；任何其他内容都被忽略，因此限制可以调整但不能删除。需要 Claude Code v2.1.217 或更高版本 |313| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 主对话下方允许的 [子代理层](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents) 数（默认值：3）。在默认值处，子代理可以生成自己的子代理，第三层的子代理无法进一步生成；设置 `1` 以关闭嵌套。在 v2.1.217 到 v2.1.218 中，默认值为 1，因此子代理无法生成自己的，除非您提高限制；v2.1.219 将默认值提高到 3。仅接受纯数字的正整数；任何其他值被忽略，因此限制可以调整但不能删除。需要 Claude Code v2.1.217 或更高版本 |

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

315| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 一个会话可以进行的 [WebSearch](/docs/zh-CN/tools-reference#websearch-tool-behavior) 调用总数的上限（默认值：200）。当 Claude 达到上限时，进一步的 WebSearch 调用返回通知，告诉它继续使用已收集的信息。接受没有上限的正整数。任何其他内容都被忽略，默认值适用，因此上限可以提高但不能关闭。需要 Claude Code v2.1.212 或更高版本 |316| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 一个会话可以进行的 [WebSearch](/docs/zh-CN/tools-reference#websearch-tool-behavior) 调用总数的上限（默认值：200）。当 Claude 达到上限时，进一步的 WebSearch 调用返回通知，告诉它继续使用已收集的信息。接受没有上限的正整数。任何其他值被忽略，默认值适用，因此上限可以提高但不能关闭。需要 Claude Code v2.1.212 或更高版本 |

317| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 仍在运行的 MCP 工具调用 [移到后台任务](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls) 之前的经过时间（毫秒）（默认值：120000，或 2 分钟）。设置为 `0` 以关闭自动后台处理。需要 Claude Code v2.1.212 或更高版本 |318| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | MCP 工具调用 [移到后台任务](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls) 之前的经过时间（毫秒）（默认值：120000，或 2 分钟）。设置为 `0` 以关闭自动后台处理。需要 Claude Code v2.1.212 或更高版本 |

318| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 工具调用的空闲超时时间（毫秒）。当 stdio、HTTP、SSE、WebSocket 或 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) MCP 服务器在这么长时间内没有发送响应和进度通知时，工具调用中止并显示错误，而不是等待整体 `MCP_TOOL_TIMEOUT`。覆盖网络服务器 300000（5 分钟）和 stdio 服务器 1800000（30 分钟）的每个传输默认值。设置为 `0` 以禁用空闲检查。低于 1000 的值提高到一秒，值上限为有效 `MCP_TOOL_TIMEOUT`。`.mcp.json` 中的每个服务器 `timeout` 至少 1000 会将该服务器的空闲窗口提高到至少 `timeout` 值。不适用于 IDE 服务器或 SDK 进程内服务器。需要 Claude Code v2.1.187 或更高版本。在 v2.1.203 之前，stdio 服务器免除空闲超时 |319| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 工具调用的空闲超时时间（毫秒）。当 stdio、HTTP、SSE、WebSocket 或 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) MCP 服务器在这么长时间内没有发送响应和进度通知时，工具调用中止，显示错误，而不是等待整体 `MCP_TOOL_TIMEOUT`。覆盖网络服务器的 300000（5 分钟）和 stdio 服务器的 1800000（30 分钟）的每个传输默认值。设置为 `0` 以禁用空闲检查。低于 1000 的值提高到一秒，值上限为有效 `MCP_TOOL_TIMEOUT`。`.mcp.json` 中的每个服务器 `timeout` 至少 1000 将该服务器的空闲窗口提高到至少 `timeout` 值。不适用于 IDE 服务器或 SDK 进程内服务器。需要 Claude Code v2.1.187 或更高版本。在 v2.1.203 之前，stdio 服务器免除空闲超时 |

319| `CLAUDE_CODE_MESSAGING_SOCKET` | 由 Claude Code 设置，不由您设置：在绑定 [收件箱套接字](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket) 的会话中，Claude Code 在绑定套接字时将该套接字的路径导出到 hooks 和 Bash 命令。在以消息打开的会话中，Claude Code 在任何 hook 运行之前绑定套接字。机器上的其他会话将消息传递到此路径。每个会话导出自己的套接字而不是从父级继承的套接字，到达它的消息通过会话的 [入站控制](/docs/zh-CN/cross-session-messaging#control-inbound-messages) 进行。设置 `env` 块无法设置它。需要 Claude Code v2.1.224 或更高版本 |320| `CLAUDE_CODE_MESSAGING_SOCKET` | 由 Claude Code 设置，不由您设置：在绑定 [收件箱套接字](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket) 的会话中，Claude Code 在绑定套接字时将该套接字的路径导出到钩子和 Bash 命令。在以消息打开启动的会话中，Claude Code 在任何钩子运行之前绑定套接字。机器上的其他会话将消息传递到此路径。每个会话导出自己的套接字，而不是从父级继承的套接字，到达它的消息通过会话的 [入站控制](/docs/zh-CN/cross-session-messaging#control-inbound-messages) 进行。设置 `env` 块无法设置它。需要 Claude Code v2.1.224 或更高版本 |

320| `CLAUDE_CODE_MESSAGING_TOKEN` | 由 Claude Code 设置，不由您设置：在绑定 [收件箱套接字](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket) 的会话中，Claude Code 将此每个会话令牌与 `CLAUDE_CODE_MESSAGING_SOCKET` 一起导出到 hooks 和 Bash 命令。发布到套接字的脚本可以发送 `{"type":"auth","token":"<token>"}` 作为其第一行以证明它属于会话。在本机 Windows 上，Claude Code 需要此行并关闭任何不以有效行打开的连接。[自有子规则](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket) 说明何时 Claude Code 查询令牌。每个会话导出自己的令牌，从不从父会话继承的令牌。设置 `env` 块无法设置它。需要 Claude Code v2.1.228 或更高版本 |321| `CLAUDE_CODE_MESSAGING_TOKEN` | 由 Claude Code 设置，不由您设置：在绑定 [收件箱套接字](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket) 的会话中，Claude Code 将此每个会话令牌导出到钩子和 Bash 命令，与 `CLAUDE_CODE_MESSAGING_SOCKET` 一起。发布到套接字的脚本可以发送 `{"type":"auth","token":"<token>"}` 作为其第一行以证明它属于会话。在本机 Windows 上，Claude Code 需要此行并关闭任何不以有效行打开的连接。[自有子规则](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket) 说明何时 Claude Code 查询令牌。每个会话导出自己的令牌，从不从父会话继承的令牌。设置 `env` 块无法设置它。需要 Claude Code v2.1.228 或更高版本 |

322| `CLAUDE_CODE_NEW_INIT` | 设置为 `1` 以使 `/init` 运行交互式设置流程。流程在探索代码库和编写它们之前询问要生成哪些文件，包括 CLAUDE.md、skills 和 hooks。没有此变量，`/init` 自动生成 CLAUDE.md 而不提示 |323| `CLAUDE_CODE_NEW_INIT` | 设置为 `1` 以使 `/init` 运行交互式设置流程。流程在探索代码库并写入它们之前询问要生成哪些文件，包括 CLAUDE.md、skills 和钩子。没有此变量，`/init` 自动生成 CLAUDE.md 而不提示 |

323| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 设置为 `1` 以通过第二个非阻塞文件描述符写入终端输出，因此停止读取的终端（如暂停的 tmux 控制模式窗格或停滞的 SSH 连接）无法在会话中期冻结 Claude Code。在 macOS、Linux 和 WSL 上应用，当 stdout 是终端时。需要 Claude Code v2.1.261 或更高版本 |324| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 设置为 `1` 以通过第二个非阻塞文件描述符写入终端输出，因此停止读取的终端（如暂停的 tmux 控制模式窗格或停滞的 SSH 连接）无法在会话中期冻结 Claude Code。在 macOS、Linux 和 WSL 上应用，当 stdout 是终端时。需要 Claude Code v2.1.261 或更高版本 |

324| `CLAUDE_CODE_NO_FLICKER` | 设置为 `1` 以启用 [全屏呈现](/docs/zh-CN/fullscreen)，一个减少闪烁并在长对话中保持内存平坦的研究预览。覆盖 [`tui`](/docs/zh-CN/settings-reference#tui) 设置；您也可以使用 `/tui fullscreen` 切换 |325| `CLAUDE_CODE_NO_FLICKER` | 设置为 `1` 以启用 [全屏呈现](/docs/zh-CN/fullscreen)，一个减少闪烁并在长对话中保持内存平坦的研究预览。覆盖 [`tui`](/docs/zh-CN/settings-reference#tui) 设置；您也可以使用 `/tui fullscreen` 切换 |

325| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 身份验证的 OAuth 刷新令牌。设置时，`claude auth login` 直接交换此令牌而不是打开浏览器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。对在自动化环境中配置身份验证很有用 |326| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | Claude.ai 身份验证的 OAuth 刷新令牌。设置后，`claude auth login` 直接交换此令牌，而不是打开浏览器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。对于在自动化环境中配置身份验证很有用 |

326| `CLAUDE_CODE_OAUTH_SCOPES` | 刷新令牌颁发的空格分隔 OAuth 范围，例如 `"user:profile user:inference user:sessions:claude_code"`。设置 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 时需要 |327| `CLAUDE_CODE_OAUTH_SCOPES` | 刷新令牌颁发的空格分隔 OAuth 范围，例如 `"user:profile user:inference user:sessions:claude_code"`。设置 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 时需要 |

327| `CLAUDE_CODE_OAUTH_TOKEN` | claude.ai 身份验证的 OAuth 访问令牌。`/login` 对 SDK 和自动化环境的替代方案。优先于钥匙串存储的凭证。使用 [`claude setup-token`](/docs/zh-CN/authentication#generate-a-long-lived-token) 生成一个。除非您运行 [`/login`](/docs/zh-CN/authentication#authentication-precedence)，Claude Code 为整个会话使用您设置的令牌。要替换过期的令牌，生成一个新令牌并重启 |328| `CLAUDE_CODE_OAUTH_TOKEN` | claude.ai 身份验证的 OAuth 访问令牌。`/login` 对 SDK 和自动化环境的替代方案。优先于钥匙链存储的凭证。使用 [`claude setup-token`](/docs/zh-CN/authentication#generate-a-long-lived-token) 生成一个。除非您运行 [`/login`](/docs/zh-CN/authentication#authentication-precedence)，Claude Code 为整个会话使用您设置的令牌。要替换过期的令牌，生成一个新令牌并重启 |

328| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 在 v2.1.160 中删除，现在是无操作。以前将 [快速模式](/docs/zh-CN/fast-mode) 固定到 Claude Opus 4.6 而不是当前默认值。Opus 4.6 不再支持快速模式 |329| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 在 v2.1.160 中删除，现在是无操作。以前将 [快速模式](/docs/zh-CN/fast-mode) 固定到 Claude Opus 4.6，而不是当前默认值。Opus 4.6 不再支持快速模式 |

329| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 内容承载 OpenTelemetry 属性（模型响应、工具内容、系统提示、原始 API 正文）的最大长度，截断标记包括在内，以 UTF-16 代码单位为单位（默认值：61440，即 60 KB）。仅当您的遥测后端接受大于 64 KB 的属性值时才提高它，或降低它以减少遥测量。需要 Claude Code v2.1.214 或更高版本。请参阅 [监控](/docs/zh-CN/monitoring-usage) |330| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 内容承载 OpenTelemetry 属性（模型响应、工具内容、系统提示、原始 API 正文）的最大长度，截断标记包括在内，以 UTF-16 代码单位为单位（默认值：61440，即 60 KB）。仅当您的遥测后端接受大于 64 KB 的属性值时才提高它，或降低它以减少遥测量。需要 Claude Code v2.1.214 或更高版本。参见 [监控](/docs/zh-CN/monitoring-usage) |

330| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 设置为 `1` 以将 OpenTelemetry 导出器诊断错误写入 stderr。默认情况下，这些错误仅在 `--debug` 中出现，因此配置不当的导出器（如 Prometheus 端口冲突）否则会无声地失败。需要 Claude Code v2.1.179 或更高版本。请参阅 [监控](/docs/zh-CN/monitoring-usage) |331| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 设置为 `1` 以将 OpenTelemetry 导出器诊断错误写入 stderr。默认情况下这些错误仅与 `--debug` 一起出现，因此配置错误的导出器（如 Prometheus 端口冲突）否则会无声地失败。需要 Claude Code v2.1.179 或更高版本。参见 [监控](/docs/zh-CN/monitoring-usage) |

332| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新动态 OpenTelemetry 标头的间隔（毫秒）（默认值：1740000 / 29 分钟）。请参阅 [动态标头](/docs/zh-CN/monitoring-usage#dynamic-headers) |333| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新动态 OpenTelemetry 标头的间隔（毫秒）（默认值：1740000 / 29 分钟）。参见 [动态标头](/docs/zh-CN/monitoring-usage#dynamic-headers) |

333| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 导出器在关闭时完成的超时时间（毫秒）（默认值：2000）。如果指标在退出时被删除，请增加。请参阅 [监控](/docs/zh-CN/monitoring-usage) |334| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 导出器在关闭时完成的超时时间（毫秒）（默认值：2000）。如果指标在退出时被删除，请增加。参见 [监控](/docs/zh-CN/monitoring-usage) |

334| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 设置为 `1` 以让 Claude Code 在新版本可用时在后台运行您的包管理器的升级命令。适用于 Homebrew 和 WinGet 安装。其他包管理器继续显示升级命令而不运行它。请参阅 [自动更新](/docs/zh-CN/setup#auto-updates) |335| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 设置为 `1` 以让 Claude Code 在新版本可用时在后台运行您的包管理器的升级命令。适用于 Homebrew 和 WinGet 安装。其他包管理器继续显示升级命令而不运行它。参见 [自动更新](/docs/zh-CN/setup#auto-updates) |

335| `CLAUDE_CODE_PERFORCE_MODE` | 设置为 `1` 以启用 Perforce 感知写入保护。设置时，如果目标文件缺少所有者写入位（Perforce 在同步文件上清除，直到 `p4 edit` 打开它们），Edit、Write 和 NotebookEdit 会失败并显示 `p4 edit <file>` 提示。这防止 Claude Code 绕过 Perforce 更改跟踪 |336| `CLAUDE_CODE_PERFORCE_MODE` | 设置为 `1` 以启用 Perforce 感知写保护。设置后，如果目标文件缺少所有者写位（Perforce 在同步文件上清除，直到 `p4 edit` 打开它们），Edit、Write 和 NotebookEdit 失败，显示 `p4 edit <file>` 提示。这防止 Claude Code 绕过 Perforce 更改跟踪 |

337| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 安装或更新插件时 git 操作的超时时间（毫秒）（默认值：120000）。对于大型存储库或缓慢的网络连接，增加此值。请参阅 [Git 操作超时](/docs/zh-CN/plugin-marketplaces#git-operations-time-out) |338| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 安装或更新插件时 git 操作的超时时间（毫秒）（默认值：120000）。对于大型存储库或缓慢网络连接，增加此值。参见 [Git 操作超时](/docs/zh-CN/plugin-marketplaces#git-operations-time-out) |

338| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 设置为 `1` 以在 `git pull` 失败时跳过重新克隆尝试并继续使用现有市场缓存。在离线或隔离环境中很有用，其中重新克隆会以相同方式失败。请参阅 [市场更新在离线环境中失败](/docs/zh-CN/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) |339| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 设置为 `1` 以在 `git pull` 失败时跳过重新克隆尝试并继续使用现有市场缓存。在离线或隔离环境中很有用，其中重新克隆会以相同方式失败。参见 [市场更新在离线环境中失败](/docs/zh-CN/plugin-marketplaces#marketplace-updates-fail-in-offline-environments) |

339| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 设置为 `1` 以通过 HTTPS 而不是 SSH 克隆 GitHub `owner/repo` 速记源。适用于插件安装和更新，以及 `/plugin marketplace add` 和 `update`。在 CI 运行器、容器或任何没有为 `github.com` 配置 SSH 密钥的环境中很有用 |340| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 设置为 `1` 以通过 HTTPS 而不是 SSH 克隆 GitHub `owner/repo` 速记源。适用于插件安装和更新，以及 `/plugin marketplace add` 和 `update`。在 CI 运行器、容器或任何没有为 `github.com` 配置 SSH 密钥的环境中很有用 |

340| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一个或多个只读插件种子目录的路径，在 Unix 上用 `:` 分隔，在 Windows 上用 `;` 分隔。使用此选项将预填充的插件目录捆绑到容器镜像中。Claude Code 在启动时从这些目录注册市场，并使用预缓存的插件而不重新克隆。请参阅 [为容器预填充插件](/docs/zh-CN/plugin-marketplaces#pre-populate-plugins-for-containers) |341| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一个或多个只读插件种子目录的路径，在 Unix 上用 `:` 分隔，在 Windows 上用 `;` 分隔。使用此选项将预填充的插件目录捆绑到容器镜像中。Claude Code 在启动时从这些目录注册市场，并使用预缓存的插件而不重新克隆。参见 [为容器预填充插件](/docs/zh-CN/plugin-marketplaces#pre-populate-plugins-for-containers) |

341| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 设置为 `1` 以停止 Claude Code 在为工具调用、hooks 和状态行命令生成 PowerShell 时传递 `-ExecutionPolicy Bypass`，并改为尊重机器的有效执行策略。默认情况下 Claude Code 在进程范围内绕过执行策略，以便 `.ps1` 脚本和模块导入在默认受限的 Windows 安装上工作。进程范围绕过永远不会覆盖组策略 `MachinePolicy` 或 `UserPolicy`，无论此设置如何 |342| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 设置为 `1` 以停止 Claude Code 在为工具调用、钩子和状态行命令生成 PowerShell 时传递 `-ExecutionPolicy Bypass`，并改为尊重机器的有效执行策略。默认情况下 Claude Code 在进程范围内绕过执行策略，以便 `.ps1` 脚本和模块导入在默认受限 Windows 安装上工作。进程范围绕过从不覆盖组策略 `MachinePolicy` 或 `UserPolicy`，无论此设置如何 |

342| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在 [非交互模式](/docs/zh-CN/headless#background-tasks-at-exit) 中使用 `-p` 标志后最终转后等待后台子代理和工作流的空闲等待上限（毫秒）。每次 Claude 采取转处理后台结果时，空闲等待重新开始。默认值：`600000`，或 10 分钟。当空闲等待达到上限时，Claude Code 停止等待剩余的后台任务并退出。设置为 `0` 以无限期等待。此上限与适用于纯后台 shells 的五秒宽限期分开。需要 Claude Code v2.1.182 或更高版本 |343| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在 [非交互模式](/docs/zh-CN/headless#background-tasks-at-exit) 中使用 `-p` 标志后最终转后等待后台子代理和工作流的空闲等待的上限（毫秒）。每次 Claude 采取转处理后台结果时，空闲等待重新开始。默认值：`600000`，或 10 分钟。当空闲等待达到上限时，Claude Code 停止等待剩余的后台任务并退出。设置为 `0` 以无限期等待。此上限与适用于纯后台 shell 的五秒宽限期分开。需要 Claude Code v2.1.182 或更高版本 |

343| `CLAUDE_CODE_PROCESS_WRAPPER` | 通过给定为 argv 前缀的公司启动器（如 `/opt/corp/launcher`）启动 Claude Code 从其自己的二进制文件启动的进程，例如托管 [代理视图](/docs/zh-CN/agent-view) 会话的后台服务。在用户或 [托管设置](/docs/zh-CN/managed-settings) 的 `env` 块中设置它，而不是作为 shell 导出，以便分离的后台服务继承它；项目和本地设置无法设置它。等同于 [`processWrapper` 设置](/docs/zh-CN/settings-reference#processwrapper)，需要 Claude Code v2.1.210 或更高版本；当两者都设置时此变量优先。VS Code 扩展通过其 `claudeProcessWrapper` 设置单独配置自己的启动器。在 Windows 上被忽略。请参阅 [在公司启动器后面运行 Claude Code](/docs/zh-CN/corporate-launcher) 了解值格式、启动器涵盖的内容以及启动器必须满足的合同。需要 Claude Code v2.1.208 或更高版本 |344| `CLAUDE_CODE_PROCESS_WRAPPER` | 通过给定为 argv 前缀（如 `/opt/corp/launcher`）的企业启动器启动 Claude Code 从其自己的二进制文件启动的进程，例如托管 [代理视图](/docs/zh-CN/agent-view) 会话的后台服务。在用户或 [托管设置](/docs/zh-CN/managed-settings) 的 `env` 块中设置它，而不是作为 shell 导出，以便分离的后台服务继承它；项目和本地设置无法设置它。等同于 [`processWrapper` 设置](/docs/zh-CN/settings-reference#processwrapper)，需要 Claude Code v2.1.210 或更高版本；当两者都设置时此变量优先。VS Code 扩展通过其 `claudeProcessWrapper` 设置单独配置自己的启动器。在 Windows 上被忽略。参见 [在企业启动器后面运行 Claude Code](/docs/zh-CN/corporate-launcher) 了解值格式、启动器覆盖的内容以及启动器必须满足的合同。需要 Claude Code v2.1.208 或更高版本 |

344| `CLAUDE_CODE_PROJECT_DIR_NAME` | 与 `CLAUDE_CONFIG_DIR` 一起设置以选择 `projects/` 目录名称 Claude Code 在其下存储该会话的转录和自动内存，代替从工作目录路径派生的名称。例如，使用 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 启动 Claude Code 将它们存储在 `/srv/tenant-a/projects/work/` 下。当 `CLAUDE_CONFIG_DIR` 未设置时 Claude Code 忽略此变量，并仅从启动 `claude` 的环境读取它，从不从 [设置文件 `env` 块](#in-settings-files)。请参阅 [自己命名项目目录](/docs/zh-CN/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更高版本 |345| `CLAUDE_CODE_PROJECT_DIR_NAME` | 与 `CLAUDE_CONFIG_DIR` 一起设置以选择 Claude Code 存储该会话的成绩单和自动内存的 `projects/` 目录名称，代替从工作目录路径派生的名称。例如，使用 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 启动 Claude Code 将它们存储在 `/srv/tenant-a/projects/work/` 下。当 `CLAUDE_CONFIG_DIR` 未设置时，Claude Code 忽略此变量，并仅从启动 `claude` 的环境读取它，从不从 [设置文件 `env` 块](#in-settings-files)。参见 [自己命名项目目录](/docs/zh-CN/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更高版本 |

345| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 设置 `5m` 或 `1h`，Claude Code 接受的唯一值，为主对话选择 [提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime)：您的交互式、`-p` 和 SDK 转，加上与它们内联运行的帮助程序。优先于 `promptCacheTtl` 设置和 `ENABLE_PROMPT_CACHING_1H`，`FORCE_PROMPT_CACHING_5M` 覆盖它。1 小时缓存写入按更高费率计费。需要 Claude Code v2.1.242 或更高版本 |346| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 设置 `5m` 或 `1h`，Claude Code 接受的唯一值，以为主对话选择 [提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime)：您的交互式、`-p` 和 SDK 转，加上与它们内联运行的帮助程序。优先于 `promptCacheTtl` 设置和 `ENABLE_PROMPT_CACHING_1H`，`FORCE_PROMPT_CACHING_5M` 覆盖它。API 以更高的速率计费 1 小时缓存写入。需要 Claude Code v2.1.242 或更高版本 |

346| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 设置为 `1` 以在 `ANTHROPIC_BASE_URL` 指向自定义代理时传播 W3C 跟踪上下文。传播涵盖模型和 HTTP MCP 请求上的 `traceparent` 标头以及 Bash、PowerShell 和 hook 子进程的 `TRACEPARENT` 环境变量。默认情况下，传播仅在直接连接到 Anthropic API 时启用。在 v2.1.152 中添加。请参阅 [跟踪（测试版）](/docs/zh-CN/monitoring-usage#traces-beta) |347| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 设置为 `1` 以在 `ANTHROPIC_BASE_URL` 指向自定义代理时传播 W3C 跟踪上下文。传播涵盖模型和 HTTP MCP 请求上的 `traceparent` 标头以及 Bash、PowerShell 和 hook 子进程的 `TRACEPARENT` 环境变量。默认情况下，传播仅在直接连接到 Anthropic API 时启用。在 v2.1.152 中添加。参见 [跟踪（测试版）](/docs/zh-CN/monitoring-usage#traces-beta) |

347| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由代表 Claude Code 管理模型提供商路由的嵌入 Claude Code 的主机平台设置。设置时，Claude Code 在设置文件中忽略提供商选择、端点和身份验证变量（如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`），因此用户设置无法覆盖主机的路由。Claude Code 也忽略 [托管设置](/docs/zh-CN/managed-settings) 中的模型选择键（如 `model`、`fallbackModel` 和 `modelOverrides`），无论托管源传递它们，因此主机的模型配置优先于过时的托管模型固定。Claude Code 也忽略托管 `env` 块中的模型选择变量（如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列）；托管设置中的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表仍然适用，除非主机提供自己的。Claude Code 也跳过它在第三方提供商（如 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud 的 Agent Platform 和 Microsoft Foundry）上应用的自动遥测选择退出，因此遥测遵循标准 `DISABLE_TELEMETRY` 选择退出。请参阅 [按 API 提供商的默认行为](/docs/zh-CN/data-usage#default-behaviors-by-api-provider) |348| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 并代表其管理模型提供商路由的主机平台设置。设置后，Claude Code 在设置文件中忽略提供商选择、端点和身份验证变量（如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`），因此用户设置无法覆盖主机的路由。Claude Code 也忽略 [托管设置](/docs/zh-CN/managed-settings) 中的模型选择键（如 `model`、`fallbackModel` 和 `modelOverrides`），无论哪个托管源传递它们，因此主机的模型配置优先于过时的托管模型固定。Claude Code 也忽略托管 `env` 块中的模型选择变量（如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列）；托管设置中的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表仍然适用，除非主机提供自己的。Claude Code 跳过它在第三方提供商（如 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 和 Microsoft Foundry）上否则应用的自动遥测选择退出，因此遥测遵循标准 `DISABLE_TELEMETRY` 选择退出。参见 [按 API 提供商的默认行为](/docs/zh-CN/data-usage#default-behaviors-by-api-provider) |

349| `CLAUDE_CODE_REMOTE` | 当 Claude Code 作为 [云会话](/docs/zh-CN/claude-code-on-the-web) 运行时自动设置为 `true`。从 hook 或设置脚本读取此项以检测您是否在云会话中 |350| `CLAUDE_CODE_REMOTE` | 当 Claude Code 作为 [云会话](/docs/zh-CN/claude-code-on-the-web) 运行时自动设置为 `true`。从钩子或设置脚本读取此项以检测您是否在云会话中 |

350| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在 [云会话](/docs/zh-CN/claude-code-on-the-web) 中自动设置为当前会话的 ID。读取此项以构造回到会话转录的链接。请参阅 [将输出链接回会话](/docs/zh-CN/cloud-environments#link-output-back-to-the-session) |351| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在 [云会话](/docs/zh-CN/claude-code-on-the-web) 中自动设置为当前会话的 ID。读取此项以构造回到会话成绩单的链接。参见 [将输出链接回会话](/docs/zh-CN/cloud-environments#link-output-back-to-the-session) |

351| `CLAUDE_CODE_RESTRICTED` | 设置为 `1` 以在受限模式下启动会话，与传递 [`--restricted`](/docs/zh-CN/cli-reference#cli-flags) 相同。Claude Code 在设置文件的 `env` 块中忽略此变量。需要 Claude Code v2.1.248 或更高版本 |352| `CLAUDE_CODE_RESTRICTED` | 设置为 `1` 以在受限模式下启动会话，与传递 [`--restricted`](/docs/zh-CN/cli-reference#cli-flags) 相同。Claude Code 在设置文件的 `env` 块中忽略此变量。需要 Claude Code v2.1.248 或更高版本 |

352| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 设置为 `1` 以在前一个会话在转中期结束时自动恢复。在 SDK 模式中使用，以便模型继续而无需 SDK 重新发送提示。要关闭此功能，取消设置变量或将其设置为 `0`。在 v2.1.221 之前，Claude Code 忽略 `0` 和其他虚假值，因此在非交互模式下设置 `0` 仍会触发恢复，取消设置变量是关闭它的唯一方法 |353| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 设置为 `1` 以在上一个会话在转中期结束时自动恢复。在 SDK 模式中使用，以便模型继续而无需 SDK 重新发送提示。要关闭此功能，取消设置变量或将其设置为 `0`。在 v2.1.221 之前，Claude Code 忽略 `0` 和其他虚假值，因此在非交互模式中设置 `0` 仍然触发恢复，取消设置变量是关闭它的唯一方法 |

353| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 在转中期结束的会话继续自动恢复的最后转录消息的最大年龄（毫秒）。当最后一条消息比此界限更旧时，Claude Code 跳过 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 自动恢复和注入的 `CLAUDE_CODE_RESUME_PROMPT` 继续消息，会话启动空闲以便您显式继续。未设置或 `0` 表示无界限；负值或非数值值应用一小时界限。长时间运行的代理的生成脚本可以设置此项，以便针对旧转录的重启不会重新运行陈旧的提示。Claude Code 在重启崩溃的 [代理视图](/docs/zh-CN/agent-view) 会话时自动设置一小时界限，该会话从交互式会话继承其对话。需要 Claude Code v2.1.211 或更高版本 |354| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 最后成绩单消息的最大年龄（毫秒），用于在恢复时继续在转中期结束的会话。当最后消息比此界限更旧时，Claude Code 跳过 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 自动恢复和注入的 `CLAUDE_CODE_RESUME_PROMPT` 继续消息，会话启动空闲，以便您显式继续。未设置或 `0` 意味着无界限；负值或非数值值应用一小时界限。长时间运行的代理的生成脚本可以设置此项，以便针对旧成绩单的重启不重新运行陈旧的提示。Claude Code 在重启崩溃的 [代理视图](/docs/zh-CN/agent-view) 会话时自己设置一小时界限，该会话从交互式会话继承其对话。需要 Claude Code v2.1.211 或更高版本 |

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

355| `CLAUDE_CODE_RETRY_WATCHDOG` | 对于无人值守的会话（如 eval 工具、CI 作业或远程工作者），设置为 `1`。重试 `429` 和 `529` 容量错误无限期而不是在 `CLAUDE_CODE_MAX_RETRIES` 尝试后失败。Claude Code 在报告支出限制或耗尽使用信用的 `429` 上立即失败，即使来自 [网关支出上限](/docs/zh-CN/errors#spend-limit-reached) 按计划重置的。在 v2.1.239 之前，监视狗无限期重试这些。监视狗在尝试之间退避最多 5 分钟，或直到限制重置（当响应携带速率限制重置时间时），因此达到使用限制的会话等待剩余窗口。在 v2.1.199 或更高版本上，它也为其他瞬时错误（如服务器错误、超时和丢弃的连接）提高默认重试计数为 300，大约三小时的退避，如果您显式设置该变量，则删除 `CLAUDE_CODE_MAX_RETRIES` 上的 15 上限。需要 Claude Code v2.1.186 或更高版本 |356| `CLAUDE_CODE_RETRY_WATCHDOG` | 对于无人值守会话（如评估工具、CI 作业或远程工作者），设置为 `1`。无限期重试 `429` 和 `529` 容量错误，而不是在 `CLAUDE_CODE_MAX_RETRIES` 尝试后失败。当标准速度请求获得报告支出限制或耗尽使用信用的 `429` 时，Claude Code 立即失败，即使来自 [网关支出上限](/docs/zh-CN/errors#spend-limit-reached) 的按计划重置。在 v2.1.239 之前，监视狗无限期重试这些。对于快速模式请求，参见 [处理速率限制](/docs/zh-CN/fast-mode#handle-rate-limits)。监视狗在尝试之间备份最多 5 分钟，或直到限制重置（当响应携带速率限制重置时间时），因此达到使用限制的会话等待剩余窗口。在 v2.1.199 或更高版本上，它也为其他瞬时错误（如服务器错误、超时和丢弃的连接）提高默认重试计数到 300，大约三小时的备份，如果您显式设置该变量，则删除 `CLAUDE_CODE_MAX_RETRIES` 的上限 15。需要 Claude Code v2.1.186 或更高版本 |

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

357| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 对象限制当 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 设置时特定脚本在每个会话中可以调用多少次。键是与命令文本匹配的子字符串；值是整数调用限制。例如，`{"deploy.sh": 2}` 允许 `deploy.sh` 最多调用两次。匹配是基于子字符串的，因此 shell 扩展技巧（如 `./scripts/deploy.sh $(evil)`）仍然计入上限。通过 `xargs` 或 `find -exec` 的运行时扇出未被检测到；这是深度防御控制 |358| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 对象限制当 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 设置时特定脚本在每个会话中可能被调用多少次。键是与命令文本匹配的子字符串；值是整数调用限制。例如，`{"deploy.sh": 2}` 允许 `deploy.sh` 最多被调用两次。匹配是基于子字符串的，因此 shell 扩展技巧（如 `./scripts/deploy.sh $(evil)`）仍然计入上限。通过 `xargs` 或 `find -exec` 的运行时扇出未被检测；这是深度防御控制 |

358| `CLAUDE_CODE_SCROLL_SPEED` | 在 [全屏呈现](/docs/zh-CN/fullscreen#mouse-wheel-scrolling) 中设置鼠标滚轮滚动乘数。接受任何正值最多 20，包括低于 1 的分数值（如 `0.5`）以减慢已经放大滚轮和轨迹板滚动的终端中的加速滚动。设置为 `3` 以匹配 `vim`（如果您的终端在没有放大的情况下每个凹口发送一个滚轮事件）。在 JetBrains IDE 终端中被忽略，Claude Code 在其中使用自己的滚动处理 |359| `CLAUDE_CODE_SCROLL_SPEED` | 在 [全屏呈现](/docs/zh-CN/fullscreen#mouse-wheel-scrolling) 中设置鼠标滚轮滚动乘数。接受任何正值到 20，包括低于 1 的分数值（如 `0.5`）以减慢已放大的触控板和滚轮滚动在已放大滚轮事件的终端中。设置为 `3` 以匹配 `vim`，如果您的终端在没有放大的情况下每个凹口发送一个滚轮事件。在 JetBrains IDE 终端中被忽略，Claude Code 在其中使用自己的滚动处理 |

359| `CLAUDE_CODE_SEND_FEEDBACK` | 设置为 `0` 以关闭会话的 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)。设置为 `1` 以在您的帐户已有访问权限的地方打开它；变量本身无法授予访问权限，关闭反馈的其他开关（如 `DISABLE_FEEDBACK_COMMAND` 和 [`feedbackDrafts`](/docs/zh-CN/settings-reference#feedbackdrafts) 设置的 `off` 值）仍然适用 |360| `CLAUDE_CODE_SEND_FEEDBACK` | 设置为 `0` 以为会话关闭 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)。设置为 `1` 以在您的帐户已有访问权限的地方打开它；变量本身无法授予访问权限，关闭反馈的其他开关（如 `DISABLE_FEEDBACK_COMMAND` 和 [`feedbackDrafts`](/docs/zh-CN/settings-reference#feedbackdrafts) 设置的 `off` 值）仍然适用 |

360| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆盖 [SessionEnd](/docs/zh-CN/hooks#sessionend) hooks 的时间预算（毫秒）。适用于会话退出、`/clear` 和通过交互式 `/resume` 切换会话。默认情况下预算为 1.5 秒，自动提高到设置文件中配置的最高每个 hook `timeout`，最多 60 秒。插件提供的 hooks 上的超时不会提高预算 |361| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆盖 [SessionEnd](/docs/zh-CN/hooks#sessionend) 钩子的时间预算（毫秒）。值也是未设置自己 `timeout` 的每个钩子的超时。适用于会话退出、`/clear` 和通过交互式 `/resume` 切换会话。默认情况下预算为 1.5 秒，自动提高到设置文件中配置的最高每个钩子 `timeout`，最多 60 秒。插件提供的钩子上的超时不提高预算 |

361| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子进程、[hook 命令](/docs/zh-CN/hooks) 子进程和 stdio [MCP 服务器](/docs/zh-CN/mcp) 子进程中自动设置为当前会话 ID。对于 Bash、PowerShell 和 hooks，这与 hook JSON 输入中的 `session_id` 字段匹配，并在 `/clear` 上更新。MCP 服务器子进程保留它生成时的 ID。在 `--resume <session-id>` 上它接收恢复的 ID，与 hooks 和 Bash 匹配。在 `--continue` 或 `--resume` 没有显式 ID 上它可能接收初始启动 ID。用于将脚本和外部工具与启动它们的 Claude Code 会话相关联 |362| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子进程、[hook 命令](/docs/zh-CN/hooks) 子进程和 stdio [MCP 服务器](/docs/zh-CN/mcp) 子进程中自动设置为当前会话 ID。对于 Bash、PowerShell 和钩子，这匹配钩子 JSON 输入中的 `session_id` 字段，在 `/clear` 上更新。MCP 服务器子进程保留它生成时的 ID。在 `--resume <session-id>` 上它接收恢复的 ID，匹配钩子和 Bash。在 `--continue` 或 `--resume` 没有显式 ID 上它可能接收初始启动 ID。用于将脚本和外部工具与启动它们的 Claude Code 会话相关联 |

362| `CLAUDE_CODE_SHELL` | 设置 Claude Code 用于运行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二进制文件的路径，例如 `/opt/homebrew/bin/bash`。不支持 `fish` 等其他 shells。如果值不是工作的 `bash` 或 `zsh` 路径，Claude Code 会忽略它并回退到自动检测。自动检测在指向 `bash` 或 `zsh` 时使用您的 `$SHELL`，否则它选择在您的 `PATH` 和标准安装位置上找到的第一个工作 `zsh` 然后 `bash` |363| `CLAUDE_CODE_SHELL` | 设置 Claude Code 用于运行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二进制文件的路径，例如 `/opt/homebrew/bin/bash`。不支持 `fish` 等其他 shell。如果值不是工作的 `bash` 或 `zsh` 路径，Claude Code 忽略它并回退到自动检测。自动检测在指向 `bash` 或 `zsh` 时使用您的 `$SHELL`，否则它选择在您的 `PATH` 和标准安装位置上找到的第一个工作 `zsh` 然后 `bash` |

363| `CLAUDE_CODE_SHELL_PREFIX` | 包装 Claude Code 生成的 shell 命令的命令前缀：Bash 工具调用、[hook](/docs/zh-CN/hooks) 命令、[状态行](/docs/zh-CN/statusline) 命令和 stdio [MCP 服务器](/docs/zh-CN/mcp) 启动命令。PowerShell hooks 和 exec 形式 hooks 运行而不带前缀。对日志记录或审计很有用。设置裸可执行文件路径（如 `/path/to/logger.sh`）将每个命令作为 `/path/to/logger.sh '<command>'` 运行。包装器在 `$1` 中接收命令行作为单个 shell 引用的参数，因此包装器必须使用 shell 重新评估 `$1`，例如 `exec bash -c "$1"`。将 `$1` 视为裸可执行文件路径会破坏传递参数的 stdio MCP 服务器，例如 `npx -y <package>`。对于 Bash 工具调用，`$1` 包含 Claude Code 组装的完整 shell 调用，包括环境设置，而不仅仅是 Claude 运行的命令 |364| `CLAUDE_CODE_SHELL_PREFIX` | 命令前缀，包装 Claude Code 生成的 shell 命令：Bash 工具调用、[hook](/docs/zh-CN/hooks) 命令、[状态行](/docs/zh-CN/statusline) 命令和 stdio [MCP 服务器](/docs/zh-CN/mcp) 启动命令。PowerShell 钩子和 exec 形式钩子运行而不带前缀。对于日志记录或审计很有用。设置裸可执行文件路径（如 `/path/to/logger.sh`）将每个命令作为 `/path/to/logger.sh '<command>'` 运行。包装器在 `$1` 中接收命令行作为单个 shell 引用的参数，因此包装器必须使用 shell 重新评估 `$1`，例如 `exec bash -c "$1"`。将 `$1` 视为裸可执行文件路径会破坏传递参数的 stdio MCP 服务器，例如 `npx -y <package>`。对于 Bash 工具调用，`$1` 包含 Claude Code 组装的完整 shell 调用，包括环境设置，而不仅仅是 Claude 运行的命令 |

364| `CLAUDE_CODE_SIMPLE` | 设置为 `1` 以使用最小系统提示和仅 Bash、文件读取和文件编辑工具运行。来自 `--mcp-config` 的 MCP 工具仍然可用。禁用 hooks、skills、自定义命令、子代理、插件、MCP 服务器、自动内存和 CLAUDE.md 的自动发现。您使用 `--add-dir` 传递的目录中的 Skills 仍然加载。OAuth 令牌和钥匙串凭证不被读取，因此 Anthropic 身份验证必须来自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同于传递 [`--bare`](/docs/zh-CN/headless#start-faster-with-bare-mode) |365| `CLAUDE_CODE_SIMPLE` | 设置为 `1` 以使用最小系统提示和仅 Bash、文件读取和文件编辑工具运行。来自 `--mcp-config` 的 MCP 工具仍然可用。禁用钩子、skills、自定义命令、子代理、插件、MCP 服务器、自动内存和 CLAUDE.md 的自动发现。您使用 `--add-dir` 传递的目录中的 Skills 仍然加载。OAuth 令牌和钥匙链凭证未被读取，因此 Anthropic 身份验证必须来自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同于传递 [`--bare`](/docs/zh-CN/headless#start-faster-with-bare-mode) |

365| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 设置为 `1` 以在任何模型上使用较短的系统提示和缩写的工具描述。设置为 `0`、`false`、`no` 或 `off` 以选择退出，即使在实验或服务器配置会启用它的模型上。完整的工具集、hooks、MCP 服务器和 CLAUDE.md 发现保持启用 |366| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 设置为 `1` 以在任何模型上使用较短的系统提示和缩写的工具描述。设置为 `0`、`false`、`no` 或 `off` 以选择退出，即使实验或服务器配置会否则启用它。完整工具集、钩子、MCP 服务器和 CLAUDE.md 发现保持启用 |

366| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 跳过 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 的客户端身份验证，用于自己签署请求的网关 |367| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 跳过 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 的客户端身份验证，用于自己签署请求的网关 |

367| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 设置为 `1` 以关闭从 AWS 默认凭证提供商链解析的凭证的进程内缓存，以便 Claude Code 在每个 API 请求上解析链。禁用缓存后，SSO 支持的配置文件在每个请求上从 IAM Identity Center 请求凭证。请参阅 [凭证缓存和解析超时](/docs/zh-CN/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更高版本 |368| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 设置为 `1` 以关闭 AWS 默认凭证提供商链解析的进程内缓存，以便 Claude Code 在每个 API 请求上解析链。禁用缓存后，由 SSO 支持的配置文件在每个请求上从 IAM Identity Center 请求凭证。参见 [凭证缓存和解析超时](/docs/zh-CN/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更高版本 |

369| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 设置为 `1` 以将失败的 [快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 可用性检查视为可用，用于阻止检查对 `api.anthropic.com` 的直接请求的网络。Claude Code 仍然尊重"您的组织禁用了快速模式"响应 |370| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 设置为 `1` 以将失败的 [快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 可用性检查视为可用，用于阻止检查对 `api.anthropic.com` 的直接请求的网络。Claude Code 仍然尊重"您的组织禁用了快速模式"响应 |

370| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 设置为 `1` 以跳过客户端 [快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 可用性检查，用于拦截检查请求的代理而不是拒绝它。当您的组织禁用了快速模式时 API 仍然拒绝快速模式请求 |371| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 设置为 `1` 以跳过客户端 [快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 可用性检查，用于拦截检查请求的代理而不是拒绝它。API 在您的组织禁用快速模式时仍然拒绝快速模式请求 |

371| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 跳过 Microsoft Foundry 的 Azure 身份验证，用于代理或网关注入自己的 `Authorization` 标头。Claude Code 发送没有 Azure 凭证的请求并保留您提供的 `Authorization` 标头，例如通过 `ANTHROPIC_CUSTOM_HEADERS`。当 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 被设置时被忽略。在 v2.1.203 之前，此变量使 Microsoft Foundry 客户端无法发送请求，除非也设置了 API 密钥 |372| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 跳过 Microsoft Foundry 的 Azure 身份验证，用于代理或网关注入自己的 `Authorization` 标头。Claude Code 发送没有 Azure 凭证的请求并保留您提供的 `Authorization` 标头，例如通过 `ANTHROPIC_CUSTOM_HEADERS`。当设置 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 时被忽略。在 v2.1.203 之前，此变量使 Microsoft Foundry 客户端无法发送请求，除非也设置了 API 密钥 |

373| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 设置为 `1` 以跳过将提示历史和会话转录写入磁盘。使用此变量启动的会话不出现在 `--resume`、`--continue` 或向上箭头历史中。对临时脚本会话很有用 |374| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 设置为 `1` 以跳过将提示历史和会话成绩单写入磁盘。使用此变量启动的会话不出现在 `--resume`、`--continue` 或向上箭头历史中。对于临时脚本会话很有用 |

375| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-CN/hooks#stop) 或 [SubagentStop](/docs/zh-CN/hooks#subagentstop) hook 可以在 Claude Code 覆盖它并无论如何结束转之前连续阻止转结束的最大次数（默认值：8）。设置为 `0` 以禁用上限。如果您的 hook 合法需要更多迭代来解决，请提高此值 |376| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-CN/hooks#stop) 或 [SubagentStop](/docs/zh-CN/hooks#subagentstop) 钩子可能在 Claude Code 覆盖它并结束转之前阻止转结束的最大连续次数（默认值：8）。设置为 `0` 以禁用上限。如果您的钩子合法需要更多迭代来解决，请提高此值 |

376| `CLAUDE_CODE_SUBAGENT_MODEL` | [子代理](/docs/zh-CN/sub-agents#choose-a-model)、[代理团队](/docs/zh-CN/agent-teams#specify-teammates-and-models) 队友和 [工作流](/docs/zh-CN/workflows) 代理的默认模型，这些代理没有以其他方式分配模型。接受别名（如 `haiku`）或完整模型名称。两个源优先于它：Claude 生成代理时传递的模型和代理定义中的 `model` 字段，包括 `inherit`。要改变这一点，设置 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model)。请参阅 [选择模型](/docs/zh-CN/sub-agents#choose-a-model) 了解完整顺序。将其设置为 `inherit` 与保留其未设置相同。在 v2.1.251 之前，此变量覆盖了每个调用模型和定义的 `model` 字段 |377| `CLAUDE_CODE_SUBAGENT_MODEL` | [子代理](/docs/zh-CN/sub-agents#choose-a-model)、[代理团队](/docs/zh-CN/agent-teams#specify-teammates-and-models) 队友和 [工作流](/docs/zh-CN/workflows) 代理的默认模型，这些代理未以其他方式分配模型。接受别名（如 `haiku`）或完整模型名称。两个来源优先于它：Claude 生成代理时传递的模型和代理定义中的 `model` 字段，包括 `inherit`。要改变这一点，设置 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model)。参见 [选择模型](/docs/zh-CN/sub-agents#choose-a-model) 了解完整顺序。将其设置为 `inherit` 与保留它未设置相同。在 v2.1.251 之前，此变量覆盖了每个调用模型和定义的 `model` 字段 |

377| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 设置为 `1` 以强制一个模型到子代理、队友和工作流代理。[在一个模型上运行每个子代理](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model) 说明那是哪个模型。需要 Claude Code v2.1.257 或更高版本 |378| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 设置为 `1` 以强制一个模型到子代理、队友和工作流代理。[在一个模型上运行每个子代理](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model) 说明那是哪个模型。需要 Claude Code v2.1.257 或更高版本 |

378| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | 设置 `5m` 或 `1h`，Claude Code 接受的唯一值，为主对话外的请求选择 [提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime)，例如 [子代理](/docs/zh-CN/sub-agents)、工作流和后台工作。优先于 `subagentPromptCacheTtl` 设置和 `ENABLE_PROMPT_CACHING_1H`，`FORCE_PROMPT_CACHING_5M` 覆盖它。1 小时缓存写入按更高费率计费。需要 Claude Code v2.1.242 或更高版本 |379| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | 设置 `5m` 或 `1h`，Claude Code 接受的唯一值，以为主对话外的请求选择 [提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime)，例如 [子代理](/docs/zh-CN/sub-agents)、工作流和后台工作。优先于 `subagentPromptCacheTtl` 设置和 `ENABLE_PROMPT_CACHING_1H`，`FORCE_PROMPT_CACHING_5M` 覆盖它。API 以更高的速率计费 1 小时缓存写入。需要 Claude Code v2.1.242 或更高版本 |

379| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 设置为 `1` 以从子进程环境中删除凭证（Bash 工具、hooks、MCP stdio 服务器）：Anthropic 和云提供商凭证、Claude Code 识别为凭证的任何其他变量以及包含在包注册表 URL 中的凭证。父 Claude 进程保留这些凭证用于 API 调用，但子进程无法读取它们，减少了试图通过 shell 扩展窃取秘密的提示注入攻击的暴露。在 Linux 上，这也在隔离的 PID 命名空间中运行 Bash 子进程，以便它们无法通过 `/proc` 读取主机进程环境；作为副作用，`ps`、`pgrep` 和 `kill` 无法看到或信号主机进程。`claude-code-action` 在配置 `allowed_non_write_users` 时自动设置此项 |380| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 设置为 `1` 以从子进程环境中删除凭证（Bash 工具、钩子、MCP stdio 服务器）：Anthropic 和云提供商凭证、Claude Code 识别为凭证的任何其他变量以及嵌入在包注册表 URL 中的凭证。父 Claude 进程为 API 调用保留这些凭证，但子进程无法读取它们，减少了试图通过 shell 扩展窃取秘密的提示注入攻击的暴露。在 v2.1.251 或更高版本上，清理也删除 Claude Code 自己的配置存储指针变量（如 `CLAUDE_CONFIG_DIR`），因此子进程无法定位重新定位的配置目录。如果子进程需要这些变量，请保留清理未设置。在 Linux 上，这也在隔离的 PID 命名空间中运行 Bash 子进程，因此它们无法通过 `/proc` 读取主机进程环境；作为副作用，`ps`、`pgrep` 和 `kill` 无法看到或信号主机进程。`claude-code-action` 在配置 `allowed_non_write_users` 时自动设置此项 |

380| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非交互模式（`-p` 标志）中设置为 `1` 以等待插件安装完成，然后再进行第一个查询。没有这个，插件在后台安装，可能在第一个转上不可用。与 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 结合以限制等待 |381| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非交互模式（`-p` 标志）中设置为 `1` 以等待插件安装完成，然后进行第一个查询。没有这个，插件在后台安装，可能在第一个转上不可用。与 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 结合以限制等待 |

382| `CLAUDE_CODE_SYNC_SKILLS` | 设置为 `1` 以将您启用的 claude.ai skills 下载到 `~/.claude/skills/synced/` 并每 10 分钟重新同步一次。在运行第一个查询之前，Claude Code 等待最多 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` 以获取您的 skills 列表。下载本身在后台完成，Claude 在调用 skill 时等待 skill 的下载。`synced` 文件夹名称是 [为此下载保留的](/docs/zh-CN/skills#where-skills-live)。在 v2.1.227 之前，skills 直接下载到 `~/.claude/skills/` 中。仅适用于非交互模式，使用 `-p` 标志。需要 claude.ai 身份验证。[Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 会话自动接收您启用的 claude.ai skills；您不需要在那里设置此项。Claude Code 对下载的 skills 应用 [额外规则](/docs/zh-CN/skills#how-synced-skills-behave)，例如不在您的机器上运行它们的 `!` 命令 |383| `CLAUDE_CODE_SYNC_SKILLS` | 设置为 `1` 以将您启用的 claude.ai skills 下载到 `~/.claude/skills/synced/` 并每 10 分钟重新同步。在运行第一个查询之前，Claude Code 等待最多 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` 以获取您的 skills 列表。下载本身在后台完成，Claude 在调用该 skill 时等待 skill 的下载。`synced` 文件夹名称是 [为此下载保留的](/docs/zh-CN/skills#where-skills-live)。在 v2.1.227 之前，skills 直接下载到 `~/.claude/skills/` 中。仅在非交互模式中应用 `-p` 标志。需要 claude.ai 身份验证。[云会话](/docs/zh-CN/claude-code-on-the-web) 自动接收您启用的 claude.ai skills；您不需要在那里设置此项。Claude Code 对下载的 skills 应用 [额外规则](/docs/zh-CN/skills#how-synced-skills-behave)，例如不在您的机器上运行它们的 `!` 命令 |

383| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 当 `CLAUDE_CODE_SYNC_SKILLS` 被设置时，会话中期 skills 重新同步的超时时间（毫秒）（默认值：30000）。限制在 skill 重新加载期间触发的下载。超过时，重新同步停止，剩余下载在后台继续 |384| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 当设置 `CLAUDE_CODE_SYNC_SKILLS` 时，会话中期 skills 重新同步的超时时间（毫秒）（默认值：30000）。限制在主机请求 skill 重新加载期间触发的下载。超过时，重新同步停止，剩余下载在后台继续 |

384| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 当 `CLAUDE_CODE_SYNC_SKILLS` 被设置时，第一个查询等待初始 skill 列表的超时时间（毫秒）（默认值：5000）。超过时，第一个查询使用已到达的任何 skills 运行。下载无论如何都在后台完成，Claude 在调用 skill 时等待 skill 的下载 |385| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 当设置 `CLAUDE_CODE_SYNC_SKILLS` 时，第一个查询等待初始 skill 列表的超时时间（毫秒）（默认值：5000）。超过时，第一个查询使用已到达的任何 skills 运行。下载无论如何都在后台完成，Claude 在调用该 skill 时等待 skill 的下载 |

385| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 设置为 `false` 以禁用 diff 输出中的语法突出显示。当颜色干扰您的终端设置时很有用。要也禁用代码块和文件预览中的突出显示，请使用 [`syntaxHighlightingDisabled`](/docs/zh-CN/settings-reference#syntaxhighlightingdisabled) 设置 |386| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 设置为 `false` 以在 diff 输出中禁用语法突出显示。当颜色干扰您的终端设置时很有用。要也禁用代码块和文件预览中的突出显示，请使用 [`syntaxHighlightingDisabled`](/docs/zh-CN/settings-reference#syntaxhighlightingdisabled) 设置 |

386| `CLAUDE_CODE_TASK_LIST_ID` | 跨会话共享任务列表。在多个 Claude Code 实例中设置相同的 ID 以在 [具有 Task 工具的会话](/docs/zh-CN/tools-reference#task-tool-availability) 中协调共享任务列表。请参阅 [任务列表](/docs/zh-CN/interactive-mode#task-list) |387| `CLAUDE_CODE_TASK_LIST_ID` | 跨会话共享任务列表。在多个 Claude Code 实例中设置相同的 ID 以在 [具有 Task 工具的会话](/docs/zh-CN/tools-reference#task-tool-availability) 中协调共享任务列表。参见 [任务列表](/docs/zh-CN/interactive-mode#task-list) |

387| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 覆盖非交互式会话在退出时等待其 [代理团队](/docs/zh-CN/agent-teams) 完成拆卸的时间（毫秒）。接受 1000 到 60000；超出范围的值被忽略，默认值 10000 适用。需要 Claude Code v2.1.206 或更高版本 |388| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 覆盖，以毫秒为单位，非交互式会话在退出时等待其 [代理团队](/docs/zh-CN/agent-teams) 完成拆卸的时间。接受 1000 到 60000；超出范围的值被忽略，默认值 10000 适用。需要 Claude Code v2.1.206 或更高版本 |

388| `CLAUDE_CODE_TMPDIR` | 覆盖用于内部临时文件的临时目录。Claude Code 在 Unix 上附加 `/claude-{uid}/` 或在 Windows 上附加 `/claude/` 到此路径。默认值：macOS 上 `/tmp`，Linux 和 Windows 上 `os.tmpdir()`。在 macOS 和 Linux 上，当您的覆盖是长路径时，[沙箱化](/docs/zh-CN/sandboxing) Bash 子进程在系统默认值下接收短回退 `$TMPDIR`，因为某些工具在临时路径变得太长时失败。未沙箱化的 Bash 命令继承您的 shell 的 `$TMPDIR` 不变。Claude Code 自己的临时文件始终使用您的覆盖。在您的 shell、用户设置或托管设置中设置它。在 [项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env) 中被忽略 |389| `CLAUDE_CODE_TMPDIR` | 覆盖用于内部临时文件的临时目录。Claude Code 在 Unix 上附加 `/claude-{uid}/` 或在 Windows 上附加 `/claude/` 到此路径。默认值：macOS 上的 `/tmp`，Linux 和 Windows 上的 `os.tmpdir()`。在 macOS 和 Linux 上，[沙箱化](/docs/zh-CN/sandboxing) Bash 子进程在您的覆盖是长路径时在系统默认下接收短回退 `$TMPDIR`，因为某些工具在临时路径变得太长时失败。未沙箱化的 Bash 命令继承您的 shell 的 `$TMPDIR` 不变。Claude Code 自己的临时文件始终使用您的覆盖。在您的 shell、用户设置或托管设置中设置它。在 [项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env) 中被忽略 |

389| `CLAUDE_CODE_TMUX_TRUECOLOR` | 设置为任何非空值（如 `1`）以允许 tmux 内的 24 位真彩色输出。**将其设置为 `0` 或 `false` 仍允许真彩色**，与大多数打开/关闭变量不同；取消设置变量以恢复 256 色限制。默认情况下，当 `$TMUX` 被设置时 Claude Code 限制到 256 色，因为 tmux 不通过真彩色转义序列，除非配置为这样做。在将 `set -ga terminal-overrides ',*:Tc'` 添加到您的 `~/.tmux.conf` 后设置此项。请参阅 [终端配置](/docs/zh-CN/terminal-config) 了解其他 tmux 设置 |390| `CLAUDE_CODE_TMUX_TRUECOLOR` | 设置为任何非空值（如 `1`）以允许 tmux 内的 24 位真彩色输出。**将其设置为 `0` 或 `false` 仍允许真彩色**，与大多数打开/关闭变量不同；取消设置变量以恢复 256 色限制。默认情况下，当设置 `$TMUX` 时 Claude Code 限制到 256 色，因为 tmux 不通过真彩色转义序列，除非配置为。在将 `set -ga terminal-overrides ',*:Tc'` 添加到您的 `~/.tmux.conf` 后设置此项。参见 [终端配置](/docs/zh-CN/terminal-config) 了解其他 tmux 设置 |

390| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | 在 Linux 和 WSL 上，设置为 Claude Code [从工具内存上限排除](/docs/zh-CN/tools-reference#memory-limit-on-linux-and-wsl) 的进程类型的逗号分隔列表，例如 `mcp` 或 `lsp`。设置 `none` 以限制每种类型，或 `all-new` 以仅限制 Bash、PowerShell 和 Monitor 工具命令。Claude Code 无论您列出什么都将 Bash、PowerShell 和 Monitor 工具命令保持在上限下。需要 Claude Code v2.1.246 或更高版本 |391| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | 在 Linux 和 WSL 上，设置为逗号分隔的 Claude Code [从工具内存上限中排除](/docs/zh-CN/tools-reference#memory-limit-on-linux-and-wsl) 的进程类型列表，例如 `mcp` 或 `lsp`。设置 `none` 以上限每种类型，或 `all-new` 以仅上限 Bash、PowerShell 和 Monitor 工具命令。Claude Code 无论您列出什么都将 Bash、PowerShell 和 Monitor 工具命令保持在上限下。需要 Claude Code v2.1.246 或更高版本 |

391| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | 在 Linux 和 WSL 上，设置为大小（如 `4G`）以 [限制 Bash 和 PowerShell 工具命令可以使用的内存](/docs/zh-CN/tools-reference#memory-limit-on-linux-and-wsl)，以及 v2.1.246 或更高版本上的 Monitor 工具命令。用纯数字单独写入大小（字节数）或带 `K`、`M`、`G` 或 `T` 后缀。设置 `0` 或 `off` 以关闭上限。一旦 Claude Code 启动的第一个进程打开或关闭了上限，更改的值在您下次启动 `claude` 时生效。需要 Claude Code v2.1.233 或更高版本 |392| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | 在 Linux 和 WSL 上，设置为大小（如 `4G`）以 [上限 Bash 和 PowerShell 工具命令可以使用的内存](/docs/zh-CN/tools-reference#memory-limit-on-linux-and-wsl)，以及 v2.1.246 或更高版本上的 Monitor 工具命令。用纯数字单独写大小（字节数）或带 `K`、`M`、`G` 或 `T` 后缀。设置 `0` 或 `off` 以关闭上限。一旦 Claude Code 启动的第一个进程打开或关闭了上限，更改的值在您下次启动 `claude` 时生效。需要 Claude Code v2.1.233 或更高版本 |

392| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code 取消转发给远程客户端（如 [Remote Control](/docs/zh-CN/remote-control) 或 SDK 主机）的对话框的截止时间（毫秒），或 [保持的跨会话消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages) 的批准对话框；权限提示和 `AskUserQuestion` 问题使用自己的流程，不受其管理。在 Claude Code v2.1.236 或更高版本上，它也限制会话中期 [Fable 使用信用同意提示](/docs/zh-CN/model-config#fable-and-usage-credits)，该会话可能无人值守。[控制入站消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages) 和 [非交互式会话](/docs/zh-CN/cross-session-messaging#non-interactive-sessions) 涵盖完整的保持消息过期规则，包括截止时间不适用的情况。覆盖 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 设置。`0` 或负值禁用截止时间 |393| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code 在取消转发给远程客户端（如 [Remote Control](/docs/zh-CN/remote-control) 或 SDK 主机）的对话或 [保持的跨会话消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages) 的批准对话之前的截止时间（毫秒）；权限提示和 `AskUserQuestion` 问题使用自己的流程，不受其管理。在 Claude Code v2.1.236 或更高版本上，它也限制可能无人值守运行的会话中的会话中期 [Fable 使用信用同意提示](/docs/zh-CN/model-config#fable-and-usage-credits)。[控制入站消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages) 和 [非交互式会话](/docs/zh-CN/cross-session-messaging#non-interactive-sessions) 涵盖完整的保持消息过期规则，包括截止时间不适用的情况。覆盖 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 设置。`0` 或负值禁用截止时间 |

397| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 设置为 `1` 以使用 Node.js 文件 API 而不是 ripgrep 发现自定义命令、子代理和输出样式。如果捆绑的 ripgrep 二进制文件在您的环境中不可用或被阻止，请设置此项。不影响 Grep 或文件搜索工具 |398| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 设置为 `1` 以使用 Node.js 文件 API 而不是 ripgrep 发现自定义命令、子代理和输出样式。如果捆绑的 ripgrep 二进制文件在您的环境中不可用或被阻止，请设置此项。不影响 Grep 或文件搜索工具 |

398| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在没有 Git Bash 的 Windows 上，工具自动启用；设置为 `0` 以禁用它。在安装了 Git Bash 的 Windows 上，工具对 claude.ai 和 Console 帐户默认打开；设置为 `1` 以在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 会话中启用它，或 `0` 以关闭它。在 Linux、macOS 和 WSL 上，设置为 `1` 以启用它，这需要您的 `PATH` 上的 `pwsh`。在 Windows 上启用时，Claude 可以本地运行 PowerShell 命令，而不是通过 Git Bash 路由。请参阅 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool) |399| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在没有 Git Bash 的 Windows 上，工具自动启用；设置为 `0` 以禁用它。在安装了 Git Bash 的 Windows 上，工具对 claude.ai 和 Console 帐户默认打开；设置为 `1` 以在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 会话中启用它，或 `0` 以关闭它。在 Linux、macOS 和 WSL 上，设置为 `1` 以启用它，这需要您的 `PATH` 上的 `pwsh`。在 Windows 上启用时，Claude 可以本地运行 PowerShell 命令，而不是通过 Git Bash 路由。参见 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool) |

400| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | 设置为 [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior) 保持每个获取 URL 响应缓存的毫秒数。默认值为 `900000`，即 15 分钟。仅接受纯数字；`0`、小数或任何其他拼写保持默认值。Claude Code 每次启动读取一次值，因此设置 `env` 块中的更改在您下次启动 `claude` 时适用。需要 Claude Code v2.1.233 或更高版本 |401| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | 设置为 [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior) 保持每个获取 URL 的响应缓存的毫秒数。默认值为 `900000`，即 15 分钟。仅接受纯数字；`0`、小数或任何其他拼写保持默认值。Claude Code 每次启动读取一次值，因此设置 `env` 块中的更改在您下次启动 `claude` 时应用。需要 Claude Code v2.1.233 或更高版本 |

401| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior) 等待页面下载的上限（毫秒），包括它遵循的任何重定向。未在此时间内完成的下载失败，显示截止时间错误。默认值为 `300000`，即五分钟。设置为 `0` 以删除限制。仅接受纯数字；小数或任何其他拼写保持默认值。需要 Claude Code v2.1.268 或更高版本 |402| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior) 等待页面下载的上限（毫秒），包括它遵循的任何重定向。未在那时完成的下载失败，显示截止时间错误。默认值为 `300000`，即五分钟。设置为 `0` 以删除限制。仅接受纯数字；小数或任何其他拼写保持默认值。需要 Claude Code v2.1.268 或更高版本 |

402| `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 或更高版本 |403| `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 或更高版本 |

403| `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) 中被忽略 |404| `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) 中被忽略 |

404| `CLAUDE_DISABLE_ADOPT` | 设置为 `1` 以在通过按 `←` 或使用 [`/background`](/docs/zh-CN/agent-view#from-inside-a-session) 后台处理会话时停止进行中的后台工作，而不是将其进行。Claude Code 要求您在后台处理前确认，然后停止会进行的任务。需要 Claude Code v2.1.195 或更高版本 |405| `CLAUDE_DISABLE_ADOPT` | 设置为 `1` 以在通过按 `←` 或 [`/background`](/docs/zh-CN/agent-view#from-inside-a-session) 后台处理会话时停止进行中的后台工作，而不是进行中的工作。Claude Code 要求您在后台处理前确认，然后停止会否则进行中的任务。需要 Claude Code v2.1.195 或更高版本 |

405| `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 参数时设置 |406| `CLAUDE_EFFORT` | 在 Bash 工具子进程和 hook 命令中自动设置为子进程启动时生效的 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。Ultracode 不是不同的级别，报告为 `xhigh`。匹配传递给 [钩子](/docs/zh-CN/hooks) 的 `effort.level` 字段。仅在当前模型支持 effort 参数时设置 |

406| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 设置为 `1` 以强制启用字节级流式空闲监视狗，或设置为 `0` 以强制禁用它。`0` 也关闭 [第一字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs) 在运行该截止时间的连接上。未设置时，监视狗在直接 Anthropic API 和 [AWS 上的 Claude Platform](/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) |407| `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) |

407| `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` 配置超时 |408| `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` 配置超时 |

408| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 设置为 `0` 以强制禁用事件级流式空闲监视狗，或设置为 `1` 以强制启用它。未设置时，监视狗在所有提供商上默认打开。在 v2.1.196 之前，未设置的默认值在直接 Anthropic API 上由服务器控制，在其他提供商上关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时；对于与此一起运行的其他停滞计时器，请参阅 [流式空闲监视狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |409| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 设置为 `0` 以强制禁用事件级流式空闲监视狗，或设置为 `1` 以强制启用它。未设置时，监视狗对所有提供商默认打开。在 v2.1.196 之前，未设置默认值由服务器在直接 Anthropic API 上控制，在其他提供商上关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时；对于与此一起运行的其他停滞计时器，参见 [流式空闲监视狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |

409| `CLAUDE_ENV_FILE` | shell 脚本的路径，其内容 Claude Code 在同一 shell 进程中的每个 Bash 命令之前运行，因此文件中的导出对命令可见。用于在命令之间保持 virtualenv 或 conda 激活。也由 [SessionStart](/docs/zh-CN/hooks#persist-environment-variables)、[Setup](/docs/zh-CN/hooks#setup)、[CwdChanged](/docs/zh-CN/hooks#cwdchanged) 和 [FileChanged](/docs/zh-CN/hooks#filechanged) hooks 动态填充 |410| `CLAUDE_ENV_FILE` | shell 脚本的路径，其内容 Claude Code 在同一 shell 进程中的每个 Bash 命令之前运行，因此文件中的导出对命令可见。用于在命令之间持久化 virtualenv 或 conda 激活。也由 [SessionStart](/docs/zh-CN/hooks#persist-environment-variables)、[Setup](/docs/zh-CN/hooks#setup)、[CwdChanged](/docs/zh-CN/hooks#cwdchanged) 和 [FileChanged](/docs/zh-CN/hooks#filechanged) 钩子动态填充 |

410| `CLAUDE_JOB_DIR` | 由 Claude Code 在每个 [后台会话](/docs/zh-CN/agent-view) 中设置为该会话的 `~/.claude/jobs/<id>` 目录。会话运行的 shell 命令继承它。将暂存文件写入 [`$CLAUDE_JOB_DIR/tmp`](/docs/zh-CN/agent-view#where-state-is-stored)。Claude 的 `Write` 和 `Edit` 调用在那里不提示权限，目录在会话被删除时被删除 |411| `CLAUDE_JOB_DIR` | 由 Claude Code 在每个 [后台会话](/docs/zh-CN/agent-view) 中设置为该会话的 `~/.claude/jobs/<id>` 目录。会话运行的 shell 命令继承它。将临时文件写入 [`$CLAUDE_JOB_DIR/tmp`](/docs/zh-CN/agent-view#where-state-is-stored)。Claude 的 `Write` 和 `Edit` 调用那里不提示权限，目录在会话被删除时被删除 |

411| `CLAUDE_PID` | Claude Code 在它生成的子进程中将其设置为自己的进程 ID：Bash 和 PowerShell 工具命令和 hook 命令。在 Linux 上，Bash 工具的 shell 集成使用它来拒绝与 Claude Code 进程本身匹配的 `pkill` 模式；请参阅 [错误参考](/docs/zh-CN/errors#pkill-pattern-matches-the-claude-code-process)。从您自己的脚本读取它以有意识地识别或信号父 Claude Code 进程。需要 Claude Code v2.1.214 或更高版本 |412| `CLAUDE_PID` | Claude Code 在它生成的子进程中设置为其自己的进程 ID：Bash 和 PowerShell 工具命令和 hook 命令。在 Linux 上，Bash 工具的 shell 集成使用它来拒绝会匹配 Claude Code 进程本身的 `pkill` 模式；参见 [错误参考](/docs/zh-CN/errors#pkill-pattern-matches-the-claude-code-process)。从您自己的脚本读取它以有意识地识别或信号父 Claude Code 进程。需要 Claude Code v2.1.214 或更高版本 |

412| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 当没有提供显式名称时，自动生成的 [Remote Control](/docs/zh-CN/remote-control) 会话名称的前缀。默认为您的机器的主机名，生成名称如 `myhost-graceful-unicorn`。`--remote-control-session-name-prefix` CLI 标志为单个调用设置相同的值 |413| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 当未提供显式名称时，自动生成的 [Remote Control](/docs/zh-CN/remote-control) 会话名称的前缀。默认为您的机器的主机名，生成名称如 `myhost-graceful-unicorn`。`--remote-control-session-name-prefix` CLI 标志为单个调用设置相同的值 |

413| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | 流式请求的第一个响应字节的截止时间（毫秒），在 [第一字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs) 运行的连接上。对于 Claude Code 如何限制它、它为大型请求正文添加的额外时间以及当您保留此未设置时如何选择截止时间，请参阅 [来自 API 的无响应](/docs/zh-CN/errors#no-response-from-api)。需要 Claude Code v2.1.242 或更高版本 |414| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | 流式请求的第一个响应字节的截止时间（毫秒），在 [第一字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs) 运行的连接上。对于 Claude Code 如何限制它、它为大型请求正文添加的额外时间以及当您保留此未设置时如何选择截止时间，参见 [来自 API 的无响应](/docs/zh-CN/errors#no-response-from-api)。需要 Claude Code v2.1.242 或更高版本 |

414| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件级和字节级流式空闲监视狗在关闭停滞连接之前的超时时间（毫秒）。当您显式设置此变量时，最小值为 `300000`（5 分钟）；较低的值无声地限制到吸收扩展思考暂停和代理缓冲，字节级监视狗将值上限为 30 分钟。`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 优先于此变量用于字节级监视狗。对于每个监视狗未设置的默认值，请参阅 [流式空闲监视狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |415| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件级和字节级流式空闲监视狗在关闭停滞连接之前的超时时间（毫秒）。当您显式设置此变量时，最小值为 `300000`（5 分钟）；较低的值无声地限制到吸收扩展思考暂停和代理缓冲，字节级监视狗将值上限为 30 分钟。`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 优先于此变量用于字节级监视狗。对于每个监视狗未设置默认值，参见 [流式空闲监视狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |

415| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | 在 v2.1.260 中删除，现在是无操作。以前上限了 [子代理](/docs/zh-CN/sub-agents) 启动的 [后台 shell 命令](/docs/zh-CN/interactive-mode#background-bash-commands) 可以运行多长时间（毫秒），默认 60 分钟。请参阅 [后台命令生命周期规则](/docs/zh-CN/tools-reference#background-commands) |416| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | 在 v2.1.260 中删除，现在是无操作。以前上限了 [子代理](/docs/zh-CN/sub-agents) 启动的 [后台 shell 命令](/docs/zh-CN/interactive-mode#background-bash-commands) 可以运行多长时间（毫秒），默认 60 分钟。参见 [后台命令生命周期规则](/docs/zh-CN/tools-reference#background-commands) |

416| `DEBUG` | 设置为 `1` 以启用调试模式，等同于使用 [`--debug`](/docs/zh-CN/cli-reference#cli-flags) 启动。调试日志写入 `~/.claude/debug/<session-id>.txt`，或写入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 设置的路径。仅真值 `1`、`true`、`yes` 和 `on` 启用调试模式，因此为其他工具设置的命名空间模式（如 `DEBUG=express:*`）不会触发它 |417| `DEBUG` | 设置为 `1` 以启用调试模式，等同于使用 [`--debug`](/docs/zh-CN/cli-reference#cli-flags) 启动。调试日志写入 `~/.claude/debug/<session-id>.txt`，或写入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 设置的路径。仅真值 `1`、`true`、`yes` 和 `on` 启用调试模式，因此为其他工具设置的命名空间模式（如 `DEBUG=express:*`）不触发它 |

418| `DISABLE_AUTO_COMPACT` | 设置为 `1` 以禁用接近上下文限制时的自动压缩。手动 `/compact` 命令保持可用。当您想明确控制何时进行压缩时使用。覆盖 [`autoCompactEnabled`](/docs/zh-CN/settings-reference#autocompactenabled) 设置 |419| `DISABLE_AUTO_COMPACT` | 设置为 `1` 以在接近上下文限制时禁用自动压缩。手动 `/compact` 命令保持可用。在您想要显式控制何时压缩时使用。覆盖 [`autoCompactEnabled`](/docs/zh-CN/settings-reference#autocompactenabled) 设置 |

421| `DISABLE_DOCTOR_COMMAND` | 设置为 `1` 以隐藏 [`/doctor`](/docs/zh-CN/commands#all-commands) 设置检查 skill 及其 `/checkup` 别名。对于用户不应从会话运行设置诊断的托管部署很有用。不影响 `claude doctor` 终端命令。在 v2.1.205 之前，此变量隐藏了 `/doctor` 诊断屏幕命令 |422| `DISABLE_DOCTOR_COMMAND` | 设置为 `1` 以隐藏 [`/doctor`](/docs/zh-CN/commands#all-commands) 设置检查 skill 及其 `/checkup` 别名。对于用户不应从会话运行设置诊断的托管部署很有用。不影响 `claude doctor` 终端命令。在 v2.1.205 之前，此变量隐藏了 `/doctor` 诊断屏幕命令 |

424| `DISABLE_FEEDBACK_COMMAND` | 设置为 `1` 以禁用 `/feedback` 命令和 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)。也禁用 `/bug` 和 `/share`，它们通过相同的路径报告；在 v2.1.212 之前它们是 `/feedback` 的别名，因此命令在每个名称下被禁用。较旧的名称 `DISABLE_BUG_COMMAND` 也被接受 |425| `DISABLE_FEEDBACK_COMMAND` | 设置为 `1` 以禁用 `/feedback` 命令和 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)。也禁用 `/bug` 和 `/share`，它们通过相同路径报告；在 v2.1.212 之前它们是 `/feedback` 的别名，因此命令在每个名称下被禁用。较旧的名称 `DISABLE_BUG_COMMAND` 也被接受 |

425| `DISABLE_GROWTHBOOK` | 设置为 `1` 或 `true` 以禁用 GrowthBook 功能标志获取并为每个标志使用代码默认值。这使 [Remote Control](/docs/zh-CN/remote-control#requirements) 和其他 [需要功能标志获取的功能](#features-that-need-feature-flag-fetching) 不可用。将其设置为 `0` 或 `false` 保持获取打开。遥测事件日志记录保持打开，除非 `DISABLE_TELEMETRY` 也被设置 |426| `DISABLE_GROWTHBOOK` | 设置为 `1` 或 `true` 以禁用 GrowthBook 功能标志获取并为每个标志使用代码默认值。这使 [Remote Control](/docs/zh-CN/remote-control#requirements) 和其他 [需要功能标志获取的功能](#features-that-need-feature-flag-fetching) 不可用。将其设置为 `0` 或 `false` 保持获取打开。遥测事件日志记录保持打开，除非也设置了 `DISABLE_TELEMETRY` |

427| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 设置为 `1` 以隐藏 `/install-github-app` 命令。当使用第三方提供商（Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry）时已隐藏 |428| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 设置为 `1` 以隐藏 `/install-github-app` 命令。当使用第三方提供商（Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry）时已隐藏 |

428| `DISABLE_INTERLEAVED_THINKING` | 设置为 `1` 以防止发送交错思考测试版标头。当您的 LLM 网关或提供商不支持 [交错思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) 时很有用 |429| `DISABLE_INTERLEAVED_THINKING` | 设置为 `1` 以防止发送交错思考测试版标头。当您的 LLM 网关或提供商不支持 [交错思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking) 时很有用 |

436| `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) |437| `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) |

437| `DISABLE_UPDATES` | 设置为 `1` 以阻止所有更新，包括手动 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更严格。当通过您自己的渠道分发 Claude Code 且用户不应自我更新时使用 |438| `DISABLE_UPDATES` | 设置为 `1` 以阻止所有更新，包括手动 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更严格。在通过您自己的渠道分发 Claude Code 且用户不应自我更新时使用 |

439| `DO_NOT_TRACK` | 设置为 `1` 以选择退出遥测，效果与 `DISABLE_TELEMETRY` 相同，包括使 [Remote Control](/docs/zh-CN/remote-control#requirements) 和其他 [需要功能标志获取的功能](#features-that-need-feature-flag-fetching) 不可用。Claude Code 将此变量读作标准布尔值，因此 `0` 保持遥测打开，并尊重许多开发者 CLI 识别的跨工具约定 |440| `DO_NOT_TRACK` | 设置为 `1` 以选择退出遥测，效果与 `DISABLE_TELEMETRY` 相同，包括使 [Remote Control](/docs/zh-CN/remote-control#requirements) 和其他 [需要功能标志获取的功能](#features-that-need-feature-flag-fetching) 不可用。Claude Code 将此变量读作标准布尔值，因此 `0` 保持遥测打开，并将其视为许多开发者 CLI 识别的跨工具约定 |

440| `ENABLE_BETA_TRACING_DETAILED` | 设置为 `1`，与 `BETA_TRACING_ENDPOINT` 一起，以打开 [详细测试版跟踪](/docs/zh-CN/monitoring-usage#traces-beta)，它添加内容承载跨度属性和 `claude_code.hook` 跨度。交互式 CLI 会话也需要您的组织被列入测试版白名单。两个变量在 [项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env) 中被忽略 |441| `ENABLE_BETA_TRACING_DETAILED` | 设置为 `1`，与 `BETA_TRACING_ENDPOINT` 一起，以打开 [详细测试版跟踪](/docs/zh-CN/monitoring-usage#traces-beta)，它添加内容承载跨度属性和 `claude_code.hook` 跨度。交互式 CLI 会话也需要您的组织被列入测试版白名单。两个变量在 [项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env) 中被忽略 |

441| `ENABLE_CLAUDEAI_MCP_SERVERS` | 设置为 `false` 以停止 Claude Code 从 [claude.ai MCP 服务器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) 获取。对于已登录的用户默认启用。要按项目或按组织禁用，改为在设置中设置 [`disableClaudeAiConnectors`](/docs/zh-CN/settings-reference#disableclaudeaiconnectors) |442| `ENABLE_CLAUDEAI_MCP_SERVERS` | 设置为 `false` 以停止 Claude Code 从 [claude.ai MCP 服务器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) 获取。对于已登录的用户默认启用。要按项目或按组织禁用，改为在设置中设置 [`disableClaudeAiConnectors`](/docs/zh-CN/settings-reference#disableclaudeaiconnectors) |

442| `ENABLE_PROMPT_CACHING_1H` | 设置为 `1` 以请求 1 小时 [提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime) 而不是默认 5 分钟。针对 API 密钥、[Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai)、[Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 和 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 用户。订阅用户在包含的使用范围内在 [主对话](/docs/zh-CN/prompt-caching#which-ttl-each-request-gets) 上自动接收 1 小时 TTL。订阅用户从 [使用信用](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 中提取可以设置它以保持 1 小时 TTL。1 小时缓存写入按更高费率计费。要按请求桶选择 TTL，请改用 `CLAUDE_CODE_PROMPT_CACHE_TTL` 和 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`，它们优先于此变量 |443| `ENABLE_PROMPT_CACHING_1H` | 设置为 `1` 以请求 1 小时 [提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime) 而不是默认 5 分钟。用于 API 密钥、[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) 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 用户。包含使用内的订阅用户在 [主对话](/docs/zh-CN/prompt-caching#which-ttl-each-request-gets) 上自动接收 1 小时 TTL。从 [使用信用](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 中提取的订阅用户可以设置它以保持 1 小时 TTL。1 小时缓存写入以更高的速率计费。要改为按请求桶选择 TTL，请使用 `CLAUDE_CODE_PROMPT_CACHE_TTL` 和 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`，它们优先于此变量 |

444| `ENABLE_TOOL_SEARCH` | 控制 [MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)。未设置时，Claude Code 默认延迟所有 MCP 工具。它仍在 Google Cloud 的 Agent Platform 模型上早于 Claude 4.5 代、Microsoft Foundry 部署托管在 Azure 上以及当 `ANTHROPIC_BASE_URL` 指向非第一方主机时立即加载它们。`true` 始终延迟并发送测试版标头，除了在这些相同的 Agent Platform 模型和 Microsoft Foundry 部署上；请求在不支持 `tool_reference` 的代理上失败。`auto` 在工具定义适合上下文的 10% 内时立即加载。`auto:N` 设置自定义阈值，例如 `auto:5` 为 5%。`false` 立即加载所有工具。您自己设置的值在 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 被设置时被忽略。在 v2.1.221 之前，Claude Code 在 Google Cloud 的 Agent Platform 上为所有模型禁用工具搜索，除非您将此变量设置为 `true` |445| `ENABLE_TOOL_SEARCH` | 控制 [MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)。未设置时，Claude Code 默认延迟所有 MCP 工具。它仍在早于 Claude 4.5 代的 Google Cloud's Agent Platform 模型上立即加载它们，在 Azure 上托管的 Microsoft Foundry 部署上，以及当 `ANTHROPIC_BASE_URL` 指向非第一方主机时。`true` 始终延迟并发送测试版标头，除了在这些相同的 Agent Platform 模型和 Microsoft Foundry 部署上；请求在不支持 `tool_reference` 的代理上失败。`auto` 在工具定义适应上下文的 10% 时立即加载。`auto:N` 设置自定义阈值，例如 `auto:5` 为 5%。`false` 立即加载所有工具。您自己设置的值在设置 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 时被忽略。在 v2.1.221 之前，Claude Code 在 Google Cloud's Agent Platform 上为所有模型禁用工具搜索，除非您将此变量设置为 `true` |

445| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 设置为任何非空值（如 `1`）以使 Claude Code 在没有配置回退模型时停止对每个模型的重复过载错误重试。**将其设置为 `0` 或 `false` 仍会启用此**，与大多数打开/关闭变量不同；取消设置变量以恢复默认重试行为。没有它，Claude Code 在您使用 API 密钥或 [第三方提供商](/docs/zh-CN/third-party-integrations) 而不是 Claude 订阅进行身份验证时，停止对它识别为 Opus、Fable 或 Mythos 模型的重复过载错误重试。在 Claude Code v2.1.160 或更高版本上，Claude Code 在重复过载错误时切换到您配置的 [回退模型链](/docs/zh-CN/model-config#fallback-model-chains)，用于任何主模型，因此此变量不影响切换到回退模型 |446| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 设置为任何非空值（如 `1`）以使 Claude Code 在没有配置回退模型时停止对每个模型的重复过载错误重试。**将其设置为 `0` 或 `false` 仍启用此功能**，与大多数打开/关闭变量不同；取消设置变量以恢复默认重试行为。没有它，Claude Code 在您使用 API 密钥或 [第三方提供商](/docs/zh-CN/third-party-integrations) 而不是 Claude 订阅进行身份验证时，停止对它识别为 Opus、Fable 或 Mythos 模型的模型重试这种方式。在 Claude Code v2.1.160 或更高版本上，Claude Code 在重复过载错误时切换到您配置的 [回退模型链](/docs/zh-CN/model-config#fallback-model-chains) 用于任何主模型，因此此变量不影响切换到回退模型 |

447| `FORCE_HYPERLINK` | 设置为 `1` 以在您的终端支持但未自动检测时启用可点击的 OSC 8 超链接，或 `0` 以禁用它们。未设置时，Claude Code 仅在检测到终端支持时启用超链接。Claude Code 将此值解析为数字，而不是布尔值，因此 `false`、`no` 或 `off` 等值启用超链接而不是禁用它们。页脚 [PR 或合并请求徽章](/docs/zh-CN/interactive-mode#pr-review-status) 即使 Claude Code 无法检测到终端支持（如通过 SSH）也呈现为超链接。设置 `0` 以将徽章呈现为纯文本 |448| `FORCE_HYPERLINK` | 设置为 `1` 以在您的终端支持但未自动检测时启用可点击的 OSC 8 超链接，或 `0` 以禁用它们。未设置时，Claude Code 仅在检测到终端支持时启用超链接。Claude Code 将此值解析为数字，而不是布尔值，因此 `false`、`no` 或 `off` 等值启用超链接而不是禁用它们。页脚 [PR 或合并请求徽章](/docs/zh-CN/interactive-mode#pr-review-status) 即使在 Claude Code 无法检测到终端支持时（如通过 SSH）也呈现为超链接。设置 `0` 以将徽章呈现为纯文本 |

448| `FORCE_PROMPT_CACHING_5M` | 设置为 `1` 以强制 5 分钟提示缓存 TTL，即使 1 小时 TTL 会以其他方式适用。覆盖 `CLAUDE_CODE_PROMPT_CACHE_TTL`、`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`、`ENABLE_PROMPT_CACHING_1H` 和 `promptCacheTtl` 和 `subagentPromptCacheTtl` 设置 |449| `FORCE_PROMPT_CACHING_5M` | 设置为 `1` 以强制 5 分钟提示缓存 TTL，即使 1 小时 TTL 会否则适用。覆盖 `CLAUDE_CODE_PROMPT_CACHE_TTL`、`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`、`ENABLE_PROMPT_CACHING_1H` 和 `promptCacheTtl` 和 `subagentPromptCacheTtl` 设置 |

451| `IS_DEMO` | 设置为任何非空值（如 `1`）以启用演示模式：从标头和 `/status` 输出中隐藏您的电子邮件和组织名称，并跳过入职。**将其设置为 `0` 或 `false` 仍会启用演示模式**，与大多数打开/关闭变量不同；取消设置变量以关闭它。在流式传输或录制会话时很有用 |452| `IS_DEMO` | 设置为任何非空值（如 `1`）以启用演示模式：从标头和 `/status` 输出中隐藏您的电子邮件和组织名称，并跳过入职。**将其设置为 `0` 或 `false` 仍启用演示模式**，与大多数打开/关闭变量不同；取消设置变量以关闭它。在流式传输或录制会话时很有用 |

452| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具响应中允许的最大令牌数。当输出超过 10,000 令牌时 Claude Code 显示警告。声明 [`anthropic/maxResultSizeChars`](/docs/zh-CN/mcp#raise-the-limit-for-a-specific-tool) 的工具对文本内容使用该字符限制，但来自这些工具的图像内容仍受此变量约束（默认值：25000） |453| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具响应中允许的最大令牌数。当输出超过 10,000 令牌时 Claude Code 显示警告。声明 [`anthropic/maxResultSizeChars`](/docs/zh-CN/mcp#raise-the-limit-for-a-specific-tool) 的工具对文本内容使用该字符限制，但来自这些工具的图像内容仍受此变量约束（默认值：25000） |

453| `MAX_STRUCTURED_OUTPUT_RETRIES` | 当模型的响应在非交互模式下使用 `-p` 标志的 [`--json-schema`](/docs/zh-CN/cli-reference#cli-flags) 验证失败时 Claude Code 允许的尝试次数；在那么多失败的尝试后没有有效输出，运行失败。当 [工作流](/docs/zh-CN/workflows) 子代理的结构化输出验证失败时应用相同的上限。默认为 5，第一次尝试加四次重试 |454| `MAX_STRUCTURED_OUTPUT_RETRIES` | 当模型的响应未能针对非交互模式中的 [`--json-schema`](/docs/zh-CN/cli-reference#cli-flags) 进行验证时，Claude Code 允许的尝试次数，使用 `-p` 标志；在那么多失败的尝试后没有有效输出，运行失败。当 [工作流](/docs/zh-CN/workflows) 子代理的结构化输出未能验证时，相同的上限适用。默认为 5，第一次尝试加四次重试 |

454| `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 上禁用思考，除了 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_DISABLE_ADAPTIVE_THINKING` 关闭自适应推理的模型上 |455| `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 上禁用思考，除了 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 关闭自适应推理的模型 |

455| `MCP_CLIENT_SECRET` | 需要 [预配置凭证](/docs/zh-CN/mcp#use-pre-configured-oauth-credentials) 的 MCP 服务器的 OAuth 客户端密钥。在使用 `--client-secret` 添加服务器时避免交互式提示 |456| `MCP_CLIENT_SECRET` | 需要 [预配置凭证](/docs/zh-CN/mcp#use-pre-configured-oauth-credentials) 的 MCP 服务器的 OAuth 客户端密钥。在使用 `--client-secret` 添加服务器时避免交互式提示 |

456| `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`）中，Claude Code 也在第一个转之前等待仍待处理的服务器，当您显式传递 [`--mcp-config`](/docs/zh-CN/cli-reference#cli-flags) 时有更长的截止时间；请参阅该标志的条目了解缓存服务器的例外情况 |457| `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`）中，Claude Code 也在第一个转之前等待仍然待处理的服务器，当您显式传递 [`--mcp-config`](/docs/zh-CN/cli-reference#cli-flags) 时有更长的截止时间；参见该标志的条目了解缓存服务器异常 |

457| `MCP_CONNECT_TIMEOUT_MS` | 阻塞 MCP 启动等待连接批次的时间（毫秒），然后快照工具列表（默认值：5000）。当 `MCP_CONNECTION_NONBLOCKING=0` 或对于标记为 [`alwaysLoad: true`](/docs/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器时适用。仍待处理的服务器在截止时间处继续在后台连接。与 `MCP_TIMEOUT` 不同，后者限制单个服务器的连接尝试 |458| `MCP_CONNECT_TIMEOUT_MS` | 阻塞 MCP 启动等待连接批次的时间（毫秒），然后快照工具列表（默认值：5000）。当 `MCP_CONNECTION_NONBLOCKING=0` 或对于标记为 [`alwaysLoad: true`](/docs/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器时应用。仍然待处理的服务器在截止时间处继续在后台连接。与 `MCP_TIMEOUT` 不同，后者限制单个服务器的连接尝试 |

458| `MCP_DISCOVERY_CACHE` | 打开或关闭 [MCP 发现缓存](/docs/zh-CN/mcp#server-status-detail)。启用缓存后，您之前使用过的远程 HTTP 或 SSE 服务器可以显示 [`cached` 状态](/docs/zh-CN/mcp#server-status-detail)，Claude Code 在其第一个工具调用时连接它，而不是在启动时。缓存默认关闭，除非逐步推出已为您的帐户启用它。设置为 `1` 以打开它，或 `0` 以即使推出已启用它也保持关闭。在 v2.1.238 之前，缓存默认打开。`cached` 状态需要 Claude Code v2.1.221 或更高版本 |459| `MCP_DISCOVERY_CACHE` | 打开或关闭 [MCP 发现缓存](/docs/zh-CN/mcp#server-status-detail)。启用缓存后，您之前使用过的远程 HTTP 或 SSE 服务器可以显示 [`cached` 状态](/docs/zh-CN/mcp#server-status-detail)，Claude Code 在其第一个工具调用时连接它，而不是在启动时。缓存默认关闭，除非逐步推出已为您的帐户启用它。设置为 `1` 以打开它，或 `0` 以保持关闭，即使推出已启用它。在 v2.1.238 之前，缓存默认打开。`cached` 状态需要 Claude Code v2.1.221 或更高版本 |

459| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [发现缓存](/docs/zh-CN/mcp#server-status-detail) 条目的最大年龄（秒）（默认值：14400，或 4 小时）。在条目比那更旧的启动处，Claude Code 丢弃它并在启动时连接服务器，就像缓存关闭一样。Claude Code 将值上限为 7 天。在 v2.1.238 之前，默认值为 86400，或 24 小时，Claude Code 没有上限值 |460| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [发现缓存](/docs/zh-CN/mcp#server-status-detail) 条目的最大年龄（秒）（默认值：14400，或 4 小时）。在条目比那更旧的启动处，Claude Code 丢弃它并在启动时连接服务器，就像缓存关闭时一样。Claude Code 将值上限为 7 天。在 v2.1.238 之前，默认值为 86400，或 24 小时，Claude Code 没有上限值 |

460| `MCP_DISCOVERY_CACHE_STRIKES` | 在 [发现缓存](/docs/zh-CN/mcp#server-status-detail) 条目比 `MCP_DISCOVERY_CACHE_TTL_S` 更旧的启动处，Claude Code 在后台刷新它。此变量设置在 Claude Code 丢弃条目并在下一个启动时连接服务器之前可以连续失败多少次刷新（默认值：1）。如果您的网络连接偶尔断开，请提高它，以便一次失败的刷新不会丢弃条目。需要 Claude Code v2.1.238 或更高版本 |461| `MCP_DISCOVERY_CACHE_STRIKES` | 在 [发现缓存](/docs/zh-CN/mcp#server-status-detail) 条目比 `MCP_DISCOVERY_CACHE_TTL_S` 更旧的启动处，Claude Code 在后台刷新它。此变量设置在 Claude Code 丢弃条目并在下一次启动时连接服务器之前，刷新可以连续失败多少次（默认值：1）。如果您的网络连接偶尔断开，请提高它，以便一次失败的刷新不丢弃条目。需要 Claude Code v2.1.238 或更高版本 |

461| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code 使用 [发现缓存](/docs/zh-CN/mcp#server-status-detail) 条目而不刷新它的秒数（默认值：900）。在条目比那更旧的启动处，Claude Code 仍使用它但在后台刷新它。一旦条目比 `MCP_DISCOVERY_CACHE_MAX_STALE_S` 更旧，Claude Code 改为丢弃它。Claude Code 将值上限为 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，默认为 4 小时。在 v2.1.238 之前，Claude Code 没有上限值 |462| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code 使用 [发现缓存](/docs/zh-CN/mcp#server-status-detail) 条目而不刷新它的秒数（默认值：900）。在条目比那更旧的启动处，Claude Code 仍然使用它但在后台刷新它。一旦条目比 `MCP_DISCOVERY_CACHE_MAX_STALE_S` 更旧，Claude Code 改为丢弃它。Claude Code 将值上限为 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，默认为 4 小时。在 v2.1.238 之前，Claude Code 没有上限值 |

462| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重定向回调的固定端口，作为在使用 [预配置凭证](/docs/zh-CN/mcp#use-pre-configured-oauth-credentials) 添加 MCP 服务器时 `--callback-port` 的替代方案 |463| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重定向回调的固定端口，作为在添加具有 [预配置凭证](/docs/zh-CN/mcp#use-pre-configured-oauth-credentials) 的 MCP 服务器时 `--callback-port` 的替代方案 |

463| `MCP_PROTOCOL_NEGOTIATION` | 仅在 [v2 MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes) 上，Claude Code 是否探测服务器以获取 MCP 协议修订版 2026-07-28。设置 `auto` 以探测 HTTP、claude.ai 连接器和 stdio 服务器；不回答探测的服务器在较早的协议上连接，SSE 和 WebSocket 服务器始终这样做。设置 `legacy` 以跳过每个服务器的探测。没有变量，Claude Code 在 Claude Code v2.1.232 或更高版本上探测 HTTP 和 claude.ai 连接器服务器，但 [MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes) 部分列出的例外情况除外。任何其他值被忽略并在调试日志中显示警告。需要 Claude Code v2.1.221 或更高版本 |464| `MCP_PROTOCOL_NEGOTIATION` | 仅在 [v2 MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes) 上，Claude Code 是否探测服务器以获取 MCP 协议修订版 2026-07-28。设置 `auto` 以探测 HTTP、claude.ai 连接器和 stdio 服务器；不回答探测的服务器在较早的协议上连接，SSE 和 WebSocket 服务器始终这样做。设置 `legacy` 以跳过每个服务器的探测。没有变量，Claude Code 在 Claude Code v2.1.232 或更高版本上探测 HTTP 和 claude.ai 连接器服务器，[MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes) 部分列出的异常除外。任何其他值被忽略，调试日志中显示警告。需要 Claude Code v2.1.221 或更高版本 |

465| `MCP_SDK_GENERATION` | 固定此进程连接到 MCP 服务器的 [MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes)：`v1`，基于 MCP TypeScript SDK 1.x，或 `v2`，基于 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/)。没有变量，Claude Code 在 Claude Code v2.1.232 或更高版本上使用 v2，除了该部分说它使用 v1 的地方。在 Claude Code v2.1.221 或更高版本上，v2 运行时检查 MCP OAuth 服务器在其授权响应中返回的发行者，当它不匹配时以以 `Issuer mismatch in authorization response` 开头的错误失败登录。v1 运行时不运行此检查。如果您设置无法识别的值，Claude Code 忽略它并写入调试日志的警告。Claude Code 每个进程读取一次值。需要 Claude Code v2.1.218 或更高版本 |466| `MCP_SDK_GENERATION` | 固定此进程连接到 MCP 服务器的 [MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes)：`v1`，基于 MCP TypeScript SDK 1.x，或 `v2`，基于 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/)。没有变量，Claude Code 在 Claude Code v2.1.232 或更高版本上使用 v2，除了该部分说它使用 v1 的地方。在 Claude Code v2.1.221 或更高版本上，v2 运行时检查 MCP OAuth 服务器在其授权响应中返回的发行者，当它不匹配时以以 `Issuer mismatch in authorization response` 开头的错误失败登录。v1 运行时不运行此检查。如果您设置无法识别的值，Claude Code 忽略它并在调试日志中写入警告。Claude Code 每个进程读取一次值。需要 Claude Code v2.1.218 或更高版本 |

468| `MCP_TOOL_TIMEOUT` | MCP 工具执行的超时时间（毫秒）（默认值：100000000，约 28 小时）。对于 HTTP、SSE 或 claude.ai 连接器服务器，每个请求也默认在 60 秒后超时；将此变量或每个服务器 `timeout` 设置为 60000 以上以提高该每个请求限制。较低的值仍会缩短整体工具执行超时，但保持每个请求限制为 60 秒。Stdio 和 WebSocket 服务器没有每个请求计时器。`.mcp.json` 中的每个服务器 `timeout` 字段覆盖此项用于该服务器。至少 1000 的每个服务器 `timeout` 也为该服务器的工具调用设置最小空闲窗口，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 永远不会更早中止它们；此下限需要 Claude Code v2.1.203 或更高版本。对于 env 变量，低于 1000 的值提高到一秒；对于每个服务器字段，低于 1000 的值被忽略 |469| `MCP_TOOL_TIMEOUT` | MCP 工具执行的超时时间（毫秒）（默认值：100000000，约 28 小时）。对于 HTTP、SSE 或 claude.ai 连接器服务器，每个请求也默认在 60 秒后超时；将此变量或每个服务器 `timeout` 设置为 60000 以上以提高该每个请求限制。较低的值仍然缩短整体工具执行超时，但保持每个请求限制为 60 秒。Stdio 和 WebSocket 服务器没有每个请求计时器。`.mcp.json` 中的每个服务器 `timeout` 字段覆盖此项用于该服务器。至少 1000 的每个服务器 `timeout` 也为该服务器的工具调用设置最小空闲窗口，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 从不更早中止它们；此下限需要 Claude Code v2.1.203 或更高版本。对于 env 变量，低于 1000 的值下限为一秒；对于每个服务器字段，低于 1000 的值被忽略 |

470| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 标准 OpenTelemetry SDK 属性值长度限制。Claude Code 将内容承载遥测属性上限为此和 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 中的较小者，因此截断标记保持在 SDK 限制内。Claude Code 以相同方式读取 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 和 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 变体，最小设置值适用于所有信号。需要 Claude Code v2.1.214 或更高版本。请参阅 [监控](/docs/zh-CN/monitoring-usage#common-configuration-variables) |471| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 标准 OpenTelemetry SDK 属性值长度限制。Claude Code 将内容承载遥测属性上限为此和 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 中的较小者，因此截断标记保持在 SDK 限制内。Claude Code 以相同方式读取 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 和 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 变体，最小设置值适用于所有信号。需要 Claude Code v2.1.214 或更高版本。参见 [监控](/docs/zh-CN/monitoring-usage#common-configuration-variables) |

471| `OTEL_LOG_ASSISTANT_RESPONSES` | 设置为 `1` 以在 `assistant_response` OpenTelemetry 日志事件上包含模型的响应文本。未设置时，使用 `OTEL_LOG_USER_PROMPTS` 的值。设置为 `0` 以即使 `OTEL_LOG_USER_PROMPTS` 被设置也保持响应被编辑。需要 Claude Code v2.1.193 或更高版本。请参阅 [监控](/docs/zh-CN/monitoring-usage#assistant-response-event) |472| `OTEL_LOG_ASSISTANT_RESPONSES` | 设置为 `1` 以在 `assistant_response` OpenTelemetry 日志事件上包含模型的响应文本。未设置时，使用 `OTEL_LOG_USER_PROMPTS` 的值。设置为 `0` 以保持响应被编辑，即使 `OTEL_LOG_USER_PROMPTS` 被设置。需要 Claude Code v2.1.193 或更高版本。参见 [监控](/docs/zh-CN/monitoring-usage#assistant-response-event) |

472| `OTEL_LOG_RAW_API_BODIES` | 发出 Anthropic Messages API 请求和响应 JSON 作为 `api_request_body` / `api_response_body` 日志事件。设置为 `1` 用于在内容限制处截断的内联正文，或 `file:<dir>` 以将未截断的正文写入磁盘并改为发出 `body_ref` 路径。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 配置内容限制，默认 60 KB。默认禁用；正文包括整个对话历史。在您的 shell、用户设置或托管设置中设置它。在 [项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env) 中被忽略。请参阅 [监控](/docs/zh-CN/monitoring-usage#api-request-body-event) |473| `OTEL_LOG_RAW_API_BODIES` | 发出 Anthropic Messages API 请求和响应 JSON 作为 `api_request_body` / `api_response_body` 日志事件。设置为 `1` 用于在内容限制处截断的内联正文，或 `file:<dir>` 以将未截断的正文写入磁盘并改为发出 `body_ref` 路径。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 配置内容限制，默认 60 KB。默认禁用；正文包括整个对话历史。在您的 shell、用户设置或托管设置中设置它。在 [项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env) 中被忽略。参见 [监控](/docs/zh-CN/monitoring-usage#api-request-body-event) |

474| `OTEL_LOG_TOOL_DETAILS` | 设置为 `1` 以在 OpenTelemetry 跟踪和日志中包含工具输入参数、MCP 服务器名称、用户创作的工作流名称、工具失败上的原始错误字符串、`api_refusal` 事件上的拒绝 `category` 和其他工具详情。默认禁用以保护 PII。请参阅 [监控](/docs/zh-CN/monitoring-usage) |475| `OTEL_LOG_TOOL_DETAILS` | 设置为 `1` 以在 OpenTelemetry 跟踪和日志中包含工具输入参数、MCP 服务器名称、用户创作的工作流名称、工具失败上的原始错误字符串、`api_refusal` 事件上的拒绝 `category` 和其他工具详情。默认禁用以保护 PII。参见 [监控](/docs/zh-CN/monitoring-usage) |

477| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 设置为 `true` 以在指标属性中包含会话入口点（默认值：排除）。在 v2.1.152 中添加。请参阅 [监控](/docs/zh-CN/monitoring-usage) |478| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 设置为 `true` 以在指标属性中包含会话入口点（默认值：排除）。在 v2.1.152 中添加。参见 [监控](/docs/zh-CN/monitoring-usage) |

478| `OTEL_METRICS_INCLUDE_REPOSITORY` | 设置为 `true` 以使用 `vcs.*` 属性标记 OpenTelemetry 指标和事件，识别会话的存储库（默认值：排除）。需要 Claude Code v2.1.269 或更高版本。请参阅 [存储库属性](/docs/zh-CN/monitoring-usage#repository-attributes) |479| `OTEL_METRICS_INCLUDE_REPOSITORY` | 设置为 `true` 以使用标识会话存储库的 `vcs.*` 属性标记 OpenTelemetry 指标和事件（默认值：排除）。需要 Claude Code v2.1.269 或更高版本。参见 [存储库属性](/docs/zh-CN/monitoring-usage#repository-attributes) |

479| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 从 v2.1.161 开始，Claude Code 将 `OTEL_RESOURCE_ATTRIBUTES` 键附加到指标数据点标签。设置为 `false` 以排除它们（默认值：包含）。请参阅 [监控](/docs/zh-CN/monitoring-usage#multi-team-organization-support) |480| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 从 v2.1.161 开始，Claude Code 将 `OTEL_RESOURCE_ATTRIBUTES` 键附加到指标数据点标签。设置为 `false` 以排除它们（默认值：包含）。参见 [监控](/docs/zh-CN/monitoring-usage#multi-team-organization-support) |

482| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆盖 [Skill 工具](/docs/zh-CN/skills#control-who-invokes-a-skill) 显示的 skill 元数据的字符预算。预算在上下文窗口的 1% 处动态缩放，回退为 8,000 字符。为向后兼容性保留的旧名称 |483| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆盖 [Skill 工具](/docs/zh-CN/skills#control-who-invokes-a-skill) 显示的 skill 元数据的字符预算。预算在 1% 的上下文窗口处动态缩放，回退为 8,000 字符。为了向后兼容保留的旧名称 |

483| `TASK_MAX_OUTPUT_LENGTH` | [后台任务](/docs/zh-CN/tools-reference#background-commands) 输出的最大字符数，`TaskOutput` 工具保持（默认值：32000；最大值：160000）。如果您设置了 [`taskOutputMaxChars`](/docs/zh-CN/settings-reference#taskoutputmaxchars) 设置，Claude Code 会忽略此变量 |484| `TASK_MAX_OUTPUT_LENGTH` | [后台任务](/docs/zh-CN/tools-reference#background-commands) 输出的最大字符数，`TaskOutput` 工具保持（默认值：32000；最大值：160000）。如果您设置 [`taskOutputMaxChars`](/docs/zh-CN/settings-reference#taskoutputmaxchars) 设置，Claude Code 忽略此变量 |

~~502~~ 503

503标准 OpenTelemetry 导出器变量（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 和信号特定变体）也被支持。请参阅 [监控](/docs/zh-CN/monitoring-usage) 了解配置详情。504标准 OpenTelemetry 导出器变量（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 和信号特定变体）也被支持。参见 [监控](/docs/zh-CN/monitoring-usage) 了解配置详情。

504 505

505<h2 id="features-that-need-feature-flag-fetching">506<h2 id="features-that-need-feature-flag-fetching">

506 需要特性标志获取的功能507 需要特性标志获取的功能

fast-mode.md +16 −3

Details

32* 输入 `/fast` 并按 Tab 键打开或关闭32* 输入 `/fast` 并按 Tab 键打开或关闭

33* 在您的[用户设置文件](/docs/zh-CN/settings)中设置 `"fastMode": true`33* 在您的[用户设置文件](/docs/zh-CN/settings)中设置 `"fastMode": true`

34 34

35默认情况下，在交互式会话中打开的快速模式在会话之间保持。在[非交互式模式](/docs/zh-CN/headless)中，使用 `-p` 标志，`/fast` 仅在使用快速模式在其 [`--settings`](/docs/zh-CN/cli-reference#cli-flags) 值中启动的会话中工作，例如 `claude -p --settings '{"fastMode": true}'`；切换然后仅适用于该会话，不会保存为您的默认值，在任何其他非交互式会话中，该命令报告快速模式不可用。您可以配置快速模式在每个会话时重置。有关详细信息，请参阅[要求每个会话选择加入](#require-per-session-opt-in)。35默认情况下，在交互式会话中打开的快速模式在会话之间保持。您可以配置快速模式在每个会话时重置。有关详细信息，请参阅[要求每个会话选择加入](#require-per-session-opt-in)。

37在[云会话](#use-fast-mode-in-cloud-sessions)之外，在[非交互式模式](/docs/zh-CN/headless)中使用 `-p` 标志，`/fast` 仅在使用快速模式在其 [`--settings`](/docs/zh-CN/cli-reference#cli-flags) 值中启动的会话中工作，例如 `claude -p --settings '{"fastMode": true}'`；切换然后仅适用于该会话，不会保存为您的默认值。`-p` 形式需要 Claude Code v2.1.205 或更高版本。在非交互式模式的其他地方，该命令报告快速模式不可用。

36 38

37您可以在 Claude 工作时运行 `/fast`，Claude Code 会在不等待当前轮次结束的情况下切换快速模式。Claude Code 以其原始速度完成正在运行的轮次，因此速度变化从您的下一轮开始生效。如果您当前的模型不支持快速模式，打开它也会切换您的模型，Claude Code 会在该轮次的下一个请求中使用新模型。39您可以在 Claude 工作时运行 `/fast`，Claude Code 会在不等待当前轮次结束的情况下切换快速模式。Claude Code 以其原始速度完成正在运行的轮次，因此速度变化从您的下一轮开始生效。如果您当前的模型不支持快速模式，打开它也会切换您的模型，Claude Code 会在该轮次的下一个请求中使用新模型。

38 40

62 64

63Claude Code 在模型切换、重新连接或失败的[可用性检查](#use-fast-mode-behind-proxies-and-llm-gateways)后，会将会话的快速模式状态重新发送到通过远程控制连接的设备。65Claude Code 在模型切换、重新连接或失败的[可用性检查](#use-fast-mode-behind-proxies-and-llm-gateways)后，会将会话的快速模式状态重新发送到通过远程控制连接的设备。

64 66

67<h3 id="use-fast-mode-in-cloud-sessions">

68 在云会话中使用快速模式

69</h3>

71当快速模式在您的账户上可用时，快速模式在[云会话](/docs/zh-CN/claude-code-on-the-web)中工作，无论会话是在 Anthropic 管理的基础设施还是[自托管运行器](/docs/zh-CN/self-hosted-environments)上运行。需要会话环境中的 Claude Code v2.1.271 或更高版本。

73在会话中输入 `/fast on` 以打开快速模式。它仅对该会话保持打开，不会保存为您的默认值。[要求](#requirements)也适用于云会话。

65<h2 id="understand-the-cost-tradeoff">75<h2 id="understand-the-cost-tradeoff">

66 了解成本权衡76 了解成本权衡

67</h2>77</h2>

135* **团队和企业的所有者启用**：快速模式默认对团队和企业组织禁用。所有者必须明确[启用快速模式](#enable-fast-mode-for-your-organization)，用户才能访问它。145* **团队和企业的所有者启用**：快速模式默认对团队和企业组织禁用。所有者必须明确[启用快速模式](#enable-fast-mode-for-your-organization)，用户才能访问它。

136 146

137<Note>147<Note>

138 如果您的组织尚未启用快速模式，`/fast` 命令将显示"Fast mode has been disabled by your organization."。如果您的组织的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表排除了快速模式 Opus 模型，`/fast` 将被拒绝，显示"is not in your organization's allowed models"。例外情况是已在支持快速模式的允许 Opus 模型上运行的会话：`/fast` 随后在您当前的模型上启用快速模式，而不是切换模型。148 两个组织设置可以阻止使用 `/fast` 启用快速模式：

149

150 * **快速模式未启用**：如果您的组织尚未启用快速模式，使用 `/fast` 启用快速模式会显示"Fast mode has been disabled by your organization."。

151 * **快速模式模型不允许**：如果您的组织的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表排除了快速模式 Opus 模型，启用它会被拒绝，显示"is not in your organization's allowed models"。在已在支持快速模式的允许 Opus 模型上运行的会话中，`/fast` 改为在您当前的模型上启用快速模式，而不是切换模型。

139</Note>152</Note>

140 153

141<h3 id="enable-fast-mode-for-your-organization">154<h3 id="enable-fast-mode-for-your-organization">

173 186

174在这两种情况下，设置 `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1` 来恢复快速模式。`CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` 不适用于任何一种情况，因为它仅绕过失败的检查，而这两种情况都会产生禁用响应。允许列表对承载者令牌情况没有帮助，它从不发送请求。187在这两种情况下，设置 `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1` 来恢复快速模式。`CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` 不适用于任何一种情况，因为它仅绕过失败的检查，而这两种情况都会产生禁用响应。允许列表对承载者令牌情况没有帮助，它从不发送请求。

175 188

176这些变量仅影响客户端检查。当您的组织禁用了快速模式时，API 会拒绝快速模式请求，无论是否设置了这些变量。189这些变量仅影响客户端检查。当您的组织禁用了快速模式时，API 会拒绝快速模式请求，无论是否设置了这些变量。来自 API 的拒绝即使设置了跳过变量也会成立。Claude Code 会以标准速度重试被拒绝的请求，关闭快速模式，并且 `/fast` 报告您的组织已禁用快速模式。

177 190

178设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 也会抑制可用性检查。没有之前缓存的成功检查，`/fast` 报告"Fast mode is currently unavailable"；两个跳过变量在该配置中也会恢复快速模式。191设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 也会抑制可用性检查。没有之前缓存的成功检查，`/fast` 报告"Fast mode is currently unavailable"；两个跳过变量在该配置中也会恢复快速模式。

179 192

feature-availability.md +4 −1

Details

36* [Checkpoints](/docs/zh-CN/checkpointing)、[sandboxing](/docs/zh-CN/sandboxing) 和 [Workflows](/docs/zh-CN/workflows)36* [Checkpoints](/docs/zh-CN/checkpointing)、[sandboxing](/docs/zh-CN/sandboxing) 和 [Workflows](/docs/zh-CN/workflows)

37* [OpenTelemetry metrics](/docs/zh-CN/monitoring-usage) 和[托管设置文件](/docs/zh-CN/managed-settings#delivery-mechanisms)37* [OpenTelemetry metrics](/docs/zh-CN/monitoring-usage) 和[托管设置文件](/docs/zh-CN/managed-settings#delivery-mechanisms)

38 38

~~39这三个有提供商特定的差异：~~39这些有提供商特定的差异：

40 40

41* **CLAUDE.md memory**：`CLAUDE.md` 文件在每个提供商上加载。将 [`AGENTS.md` 文件](/docs/zh-CN/memory#agents-md)作为项目说明读取也需要一个[获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话

41* **MCP servers**：[来自 claude.ai 的连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)仅在您的 claude.ai 订阅是活跃身份验证方法时加载。[工具搜索](/docs/zh-CN/mcp#configure-tool-search)在 `ANTHROPIC_BASE_URL` 指向非第一方主机时默认关闭，在 Google Cloud's Agent Platform 上早于 Claude 4.5 代的模型或在 Microsoft Foundry [部署在 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)时不受支持42* **MCP servers**：[来自 claude.ai 的连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)仅在您的 claude.ai 订阅是活跃身份验证方法时加载。[工具搜索](/docs/zh-CN/mcp#configure-tool-search)在 `ANTHROPIC_BASE_URL` 指向非第一方主机时默认关闭，在 Google Cloud's Agent Platform 上早于 Claude 4.5 代的模型或在 Microsoft Foundry [部署在 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)时不受支持

42* **Subagents**：内置的 [Explore subagent](/docs/zh-CN/sub-agents#built-in-subagents) 在 Claude API 上将其继承的模型限制为 Opus，在任何其他提供商（包括 Claude Platform on AWS）上直接继承主对话的模型43* **Subagents**：内置的 [Explore subagent](/docs/zh-CN/sub-agents#built-in-subagents) 在 Claude API 上将其继承的模型限制为 Opus，在任何其他提供商（包括 Claude Platform on AWS）上直接继承主对话的模型

43* **[Commands](/docs/zh-CN/commands#all-commands)**：44* **[Commands](/docs/zh-CN/commands#all-commands)**：

226 227

227<Note>228<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 时才有效。229 如果您通过 [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 时才有效。

230

231 有关 Claude Code 发送的请求在 Amazon Bedrock 或 Agent Platform 格式网关、`ANTHROPIC_BASE_URL` 网关和 Claude apps gateway 登录之间如何不同，请参阅[按连接方法的客户端行为](/docs/zh-CN/llm-gateway-protocol#how-the-connection-method-changes-client-behavior)。

229</Note>232</Note>

230 233

231<h3 id="summary-by-provider">234<h3 id="summary-by-provider">

features-overview.md +1 −1

Details

294 294

295 * agent 的自己的系统提示，而不是 Claude Code 系统提示295 * agent 的自己的系统提示，而不是 Claude Code 系统提示

296 * agent 的 `skills:` 字段中列出的 skills 的完整内容296 * agent 的 `skills:` 字段中列出的 skills 的完整内容

297 * CLAUDE.md 和 git 状态，除了内置的 Explore 和 Plan agents [省略两者](/docs/zh-CN/sub-agents#what-loads-at-startup)297 * CLAUDE.md 和 git 状态，除了内置的 Explore 和 Plan agents [省略两者](/docs/zh-CN/sub-agents#what-loads-at-startup)，以及定义设置 [`omitClaudeMd`](/docs/zh-CN/sub-agents#supported-frontmatter-fields) 的 agent 跳过用户、项目和本地 CLAUDE.md 文件

298 * 主 agent 在提示中传递的任何上下文298 * 主 agent 在提示中传递的任何上下文

299 299

300 对于 [fork](/docs/zh-CN/sub-agents#fork-the-current-conversation)，Claude Code 加载父对话到目前为止、系统提示和工具。300 对于 [fork](/docs/zh-CN/sub-agents#fork-the-current-conversation)，Claude Code 加载父对话到目前为止、系统提示和工具。

fullscreen.md +1 −0

Details

102* **在 `/` 命令或 `@` 文件列表中单击建议**以接受它。悬停会突出显示光标下的行。102* **在 `/` 命令或 `@` 文件列表中单击建议**以接受它。悬停会突出显示光标下的行。

103* **在选择菜单中单击选项**以选择它。这包括权限提示、`/model`、`/config` 和其他显示选项列表的对话框。悬停会在光标下的行上显示指针。需要 Claude Code v2.1.187 或更高版本。103* **在选择菜单中单击选项**以选择它。这包括权限提示、`/model`、`/config` 和其他显示选项列表的对话框。悬停会在光标下的行上显示指针。需要 Claude Code v2.1.187 或更高版本。

104* **在多选菜单中单击选项**以切换它，然后单击提交按钮以确认您的选择。单击自由文本行（例如多选题中的 `Other` 行）会聚焦其输入字段，以便您可以输入答案。需要 Claude Code v2.1.208 或更高版本。104* **在多选菜单中单击选项**以切换它，然后单击提交按钮以确认您的选择。单击自由文本行（例如多选题中的 `Other` 行）会聚焦其输入字段，以便您可以输入答案。需要 Claude Code v2.1.208 或更高版本。

105* **单击 `/config` 面板中的设置值**以更改它，并使用鼠标滚轮滚动设置列表。需要 Claude Code v2.1.271 或更高版本。

105* **单击折叠的工具结果**以展开它并查看完整输出。再次单击以折叠。工具调用及其结果一起展开。只有有更多内容要显示的消息才可点击。106* **单击折叠的工具结果**以展开它并查看完整输出。再次单击以折叠。工具调用及其结果一起展开。只有有更多内容要显示的消息才可点击。

106 * 单击也会展开 `!` shell 命令的输出，无论是较旧的截断结果还是命令运行时的实时进度行。需要 Claude Code v2.1.257 或更高版本。107 * 单击也会展开 `!` shell 命令的输出，无论是较旧的截断结果还是命令运行时的实时进度行。需要 Claude Code v2.1.257 或更高版本。

107* **在 macOS 上按住 `Cmd`，或在 Linux 和 Windows 上按住 `Ctrl`，然后单击 URL 或文件路径**以打开它。纯 `http://` 和 `https://` URL 在您的浏览器中打开，工具输出中的文件路径（如 Edit 或 Write 后打印的路径）在您的默认应用程序中打开。不带修饰符的纯单击不会打开链接，与本机终端行为相匹配。108* **在 macOS 上按住 `Cmd`，或在 Linux 和 Windows 上按住 `Ctrl`，然后单击 URL 或文件路径**以打开它。纯 `http://` 和 `https://` URL 在您的浏览器中打开，工具输出中的文件路径（如 Edit 或 Write 后打印的路径）在您的默认应用程序中打开。不带修饰符的纯单击不会打开链接，与本机终端行为相匹配。

github-actions.md +1 −1

Details

11多个产品共享 Claude Code 名称。本页涵盖 `claude-code-action` 工作流集成，您可以使用仓库中的工作流文件进行配置。对于相关产品，请参阅：11多个产品共享 Claude Code 名称。本页涵盖 `claude-code-action` 工作流集成，您可以使用仓库中的工作流文件进行配置。对于相关产品，请参阅：

12 12

13* [Code Review](/docs/zh-CN/code-review)：在每个拉取请求上自动审查，无需编写工作流13* [Code Review](/docs/zh-CN/code-review)：在每个拉取请求上自动审查，无需编写工作流

~~14* [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web)：从您的浏览器或手机进行 Claude Code 会话~~14* [Claude Code in the cloud](/docs/zh-CN/claude-code-on-the-web)：在云基础设施上运行的 Claude Code 会话，而不是在您的机器上

15* [Claude Agent SDK](/docs/zh-CN/agent-sdk/overview)：GitHub Actions 之外的自定义自动化。Claude Code GitHub Action 建立在 SDK 之上15* [Claude Agent SDK](/docs/zh-CN/agent-sdk/overview)：GitHub Actions 之外的自定义自动化。Claude Code GitHub Action 建立在 SDK 之上

16* [GitHub Enterprise Server](/docs/zh-CN/github-enterprise-server)：带有自托管 GitHub 的 Claude Code16* [GitHub Enterprise Server](/docs/zh-CN/github-enterprise-server)：带有自托管 GitHub 的 Claude Code

17 17

github-actions-cloud-providers.md +2 −2

Details

41 设置集成41 设置集成

42</h2>42</h2>

43 43

44除了前置条件外，您需要创建四样东西：Claude Code GitHub Action 的 GitHub 身份、云端信任配置、存储库密钥和工作流文件。下面的步骤将逐一介绍每一项。44除了前置条件外，您需要为 Claude Code GitHub Action 创建 GitHub 身份、云端信任配置、存储库密钥和工作流文件。下面的步骤将逐一介绍每一项。

45 45

46<Steps>46<Steps>

47 <Step title="选择 GitHub 身份">47 <Step title="选择 GitHub 身份">

48 Claude Code GitHub Action 通过 GitHub 身份推送提交和发布评论。[快速设置](/docs/zh-CN/github-actions#quick-setup) 为此安装了官方 Claude GitHub App。使用云提供商时，您可以自己选择身份：48 Claude Code GitHub Action 通过 GitHub 身份推送提交和发布评论。[快速设置](/docs/zh-CN/github-actions#quick-setup) 为此安装了官方 Claude GitHub App。使用云提供商时，您可以自己选择身份：

49 49

50 * **官方 [Claude GitHub App](https://github.com/apps/claude)**: 在存储库上安装它，或如果已经安装，请跳到下一步50 * **官方 [Claude GitHub App](https://github.com/apps/claude)**: 在存储库上安装它，或如果已经安装，请跳到下一步

51 * **自定义 GitHub App**: 当您只想要 Claude Code GitHub Action 使用的三个权限而不是[官方应用的完整权限集](/docs/zh-CN/github-actions#github-app-permissions)时，创建您自己的应用，如下所述51 * **自定义 GitHub App**: 当您只想要 Claude Code GitHub Action 使用的三个权限而不是[官方应用的完整权限集](/docs/zh-CN/github-actions#github-app-permissions)时，创建您自己的应用

52 * **GitHub 的自动 `GITHUB_TOKEN`**: 无需创建或安装应用，但 GitHub 不会在使用它进行的提交上触发您的 CI 工作流52 * **GitHub 的自动 `GITHUB_TOKEN`**: 无需创建或安装应用，但 GitHub 不会在使用它进行的提交上触发您的 CI 工作流

53 53

54 第四步中的工作流示例使用自定义应用进行身份验证。该步骤还说明了如何为其他两个选项进行更改。54 第四步中的工作流示例使用自定义应用进行身份验证。该步骤还说明了如何为其他两个选项进行更改。

github-enterprise-server.md +12 −12

Details

4 4

5# Claude Code 与 GitHub Enterprise Server5# Claude Code 与 GitHub Enterprise Server

6 6

~~7> 将 Claude Code 连接到自托管的 GitHub Enterprise Server 实例，用于网络会话、代码审查和插件市场。~~7> 将 Claude Code 连接到自托管的 GitHub Enterprise Server 实例，用于云会话、代码审查和插件市场。

8 8

9<Note>9<Note>

10 GitHub Enterprise Server 支持适用于 Team 和 Enterprise 计划。10 GitHub Enterprise Server 支持适用于 Team 和 Enterprise 计划。

11</Note>11</Note>

12 12

13GitHub Enterprise Server (GHES) 支持让您的组织使用 Claude Code 处理托管在自管理 GitHub 实例上的存储库，而不是 github.com。一旦所有者连接您的 GHES 实例，开发人员可以运行网络会话和获得自动化代码审查，无需任何按存储库的配置。您实例上托管的插件市场也受支持；凭证要求因表面而异，如 [GHES 上的插件市场](#plugin-marketplaces-on-ghes) 中所述。13GitHub Enterprise Server (GHES) 支持让您的组织使用 Claude Code 处理托管在自管理 GitHub 实例上的存储库，而不是 github.com。一旦所有者连接您的 GHES 实例，开发人员可以运行云会话和获得自动化代码审查，无需任何按存储库的配置。您实例上托管的插件市场也受支持；凭证要求因表面而异，如 [GHES 上的插件市场](#plugin-marketplaces-on-ghes) 中所述。

14 14

15对于 github.com 上的存储库，请参阅 [网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web) 和 [代码审查](/docs/zh-CN/code-review)。要在您自己的 CI 基础设施中运行 Claude，请参阅 [GitHub Actions](/docs/zh-CN/github-actions)。15对于 github.com 上的存储库，请参阅 [云上的 Claude Code](/docs/zh-CN/claude-code-on-the-web) 和 [代码审查](/docs/zh-CN/code-review)。要在您自己的 CI 基础设施中运行 Claude，请参阅 [GitHub Actions](/docs/zh-CN/github-actions)。

16 16

17<h2 id="what-works-with-github-enterprise-server">17<h2 id="what-works-with-github-enterprise-server">

18 GitHub Enterprise Server 支持的功能18 GitHub Enterprise Server 支持的功能

22 22

23| 功能 | GHES 支持 | 备注 |23| 功能 | GHES 支持 | 备注 |

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

~~25| 网络上的 Claude Code | ✅ 支持 | 所有者连接 GHES 实例一次；开发人员像往常一样使用 `claude --cloud` 或 [claude.ai/code](https://claude.ai/code) |~~25| 云会话 | ✅ 支持 | 所有者连接 GHES 实例一次；开发人员像往常一样使用 `claude --cloud` 或 [claude.ai/code](https://claude.ai/code) |

26| 代码审查 | ✅ 支持 | 与 github.com 相同的自动化 PR 审查 |26| 代码审查 | ✅ 支持 | 与 github.com 相同的自动化 PR 审查 |

27| Claude Security | ✅ 支持 | 在 [claude.ai/security](https://claude.ai/security) 为 Enterprise 计划提供公开测试版 |27| Claude Security | ✅ 支持 | 在 [claude.ai/security](https://claude.ai/security) 为 Enterprise 计划提供公开测试版 |

~~28| Teleport 会话 | ✅ 支持 | 使用 `--teleport` 在网络和终端之间移动会话 |~~28| Teleport 会话 | ✅ 支持 | 使用 `--teleport` 在云和终端之间移动会话 |

29| 插件市场 | ✅ 支持 | 凭证要求因表面而异。请参阅 [GHES 上的插件市场](#plugin-marketplaces-on-ghes) |29| 插件市场 | ✅ 支持 | 凭证要求因表面而异。请参阅 [GHES 上的插件市场](#plugin-marketplaces-on-ghes) |

30| 贡献指标 | ✅ 支持 | 通过 webhook 传递到 [分析仪表板](/docs/zh-CN/analytics) |30| 贡献指标 | ✅ 支持 | 通过 webhook 传递到 [分析仪表板](/docs/zh-CN/analytics) |

31| GitHub Actions | ✅ 支持 | 需要手动工作流设置；`/install-github-app` 仅适用于 github.com |31| GitHub Actions | ✅ 支持 | 需要手动工作流设置；`/install-github-app` 仅适用于 github.com |

110cd api-service110cd api-service

111```111```

112 112

113然后启动网络会话。Claude 从您的 git 远程检测 GHES 主机，并通过您组织的配置实例路由会话：113然后启动云会话。Claude 从您的 git 远程检测 GHES 主机，并通过您组织的配置实例路由会话：

114 114

115```bash theme={null}115```bash theme={null}

116claude --cloud "Add retry logic to the payment webhook handler"116claude --cloud "Add retry logic to the payment webhook handler"

122 将会话 Teleport 到您的终端122 将会话 Teleport 到您的终端

123</h3>123</h3>

124 124

125使用 `claude --teleport` 将网络会话拉入您的本地终端。Teleport 在获取分支和加载会话历史之前验证您在同一 GHES 存储库的检出中。有关详细信息，请参阅 [teleport 要求](/docs/zh-CN/claude-code-on-the-web#teleport-requirements)。125使用 `claude --teleport` 将云会话拉入您的本地终端。Teleport 在获取分支和加载会话历史之前验证您在同一 GHES 存储库的检出中。有关详细信息，请参阅 [teleport 要求](/docs/zh-CN/claude-code-on-the-web#teleport-requirements)。

126 126

127<h2 id="plugin-marketplaces-on-ghes">127<h2 id="plugin-marketplaces-on-ghes">

128 GHES 上的插件市场128 GHES 上的插件市场

137| claude.ai 组织插件设置 | 所有者选择 GHES 实例作为源；Anthropic 的后端使用来自 [admin setup](#admin-setup) 的 GitHub App 获取并同步存储库 | 添加后每个用户无需任何操作。添加它的所有者需要连接自己的 GitHub Enterprise 账户作为访问检查，并且 GitHub App 必须安装在市场存储库上 |137| claude.ai 组织插件设置 | 所有者选择 GHES 实例作为源；Anthropic 的后端使用来自 [admin setup](#admin-setup) 的 GitHub App 获取并同步存储库 | 添加后每个用户无需任何操作。添加它的所有者需要连接自己的 GitHub Enterprise 账户作为访问检查，并且 GitHub App 必须安装在市场存储库上 |

140 140

141<Warning>141<Warning>

142 当从用户设置添加市场时，claude.ai 上的 GitHub Enterprise 连接是按用户的。[admin setup](#admin-setup) 将您的 GHES 实例连接到您的组织，但它不连接单个用户账户：每个从自己的设置添加 GHES 市场的用户必须首先连接自己的 GitHub Enterprise 账户，一个用户的连接（包括所有者的）不会覆盖任何其他人。由所有者在组织插件设置中添加的市场不会对用户施加此要求，因为持续的获取使用组织的 GitHub App。添加市场的所有者仍然需要在添加时连接自己的 GitHub Enterprise 账户。142 当从用户设置添加市场时，claude.ai 上的 GitHub Enterprise 连接是按用户的。[admin setup](#admin-setup) 将您的 GHES 实例连接到您的组织，但它不连接单个用户账户：每个从自己的设置添加 GHES 市场的用户必须首先连接自己的 GitHub Enterprise 账户，一个用户的连接（包括所有者的）不会覆盖任何其他人。由所有者在组织插件设置中添加的市场不会对用户施加此要求，因为持续的获取使用组织的 GitHub App。添加市场的所有者仍然需要在添加时连接自己的 GitHub Enterprise 账户。

220 故障排除220 故障排除

221</h2>221</h2>

222 222

223<h3 id="web-session-fails-to-clone-repository">223<h3 id="cloud-session-fails-to-clone-repository">

224 网络会话无法克隆存储库224 云会话无法克隆存储库

225</h3>225</h3>

226 226

227如果 `claude --cloud` 因克隆错误而失败，请验证 Owner 已完成您的 GHES 实例的设置，并且 GitHub App 已安装在您正在处理的存储库上。与连接该实例的 Owner 确认在 Claude 设置中注册的主机名与您的 git 远程中的主机名匹配。227如果 `claude --cloud` 因克隆错误而失败，请验证 Owner 已完成您的 GHES 实例的设置，并且 GitHub App 已安装在您正在处理的存储库上。与连接该实例的 Owner 确认在 Claude 设置中注册的主机名与您的 git 远程中的主机名匹配。

246 GHES 实例无法访问246 GHES 实例无法访问

247</h3>247</h3>

248 248

249如果审查或 Anthropic 托管的网络会话超时，您的 GHES 实例可能无法从 Anthropic 基础设施访问。确认您的防火墙允许来自 Anthropic 的 [出站 IP 地址](https://platform.claude.com/docs/en/api/ip-addresses#outbound-ip-addresses) 的入站连接。[自托管环境](/docs/zh-CN/self-hosted-environments) 中的会话从您的网络内部访问 GHES，因此对于它们，请检查运行器自己的网络路径和 [SCM 连接器](/docs/zh-CN/self-hosted-environments-reference#scm-connector-flags) 代替。249如果审查或 Anthropic 托管的云会话超时，您的 GHES 实例可能无法从 Anthropic 基础设施访问。确认您的防火墙允许来自 Anthropic 的 [出站 IP 地址](https://platform.claude.com/docs/en/api/ip-addresses#outbound-ip-addresses) 的入站连接。[自托管环境](/docs/zh-CN/self-hosted-environments) 中的会话从您的网络内部访问 GHES，因此对于它们，请检查运行器自己的网络路径和 [SCM 连接器](/docs/zh-CN/self-hosted-environments-reference#scm-connector-flags) 代替。

250 250

251<h3 id="session-start-fails-with-unable-to-get-organization-uuid">251<h3 id="session-start-fails-with-unable-to-get-organization-uuid">

252 会话启动失败，显示 `Unable to get organization UUID`252 会话启动失败，显示 `Unable to get organization UUID`

253</h3>253</h3>

254 254

255网络会话需要 Team 或 Enterprise 组织。使用 `/login` 和您的组织账户登录。如果您改用 API 密钥进行身份验证，网络会话会更早失败，并显示一条消息要求您运行 `/login`。255云会话需要 Team 或 Enterprise 组织。使用 `/login` 和您的组织账户登录。如果您改用 API 密钥进行身份验证，云会话会更早失败，并显示一条消息要求您运行 `/login`。

256 256

257<h2 id="related-resources">257<h2 id="related-resources">

258 相关资源258 相关资源

glossary.md +22 −5

Details

12 A12 A

13</h2>13</h2>

14 14

15<h3 id="agents-md">

16 AGENTS.md

17</h3>

19您为 AI 编码代理编写的项目说明的 markdown 文件。如果您的存储库有一个且没有 [CLAUDE.md](#claude-md)，Claude 会将其作为您的项目说明读取，而无需添加第二个文件。您可以在 `/config` 中更改**项目说明**设置，以让 Claude 同时读取两个文件或仅读取 `CLAUDE.md`。直接读取 `AGENTS.md` 需要会话中的 Claude Code v2.1.277 或更高版本，该会话会获取功能标志；在其他版本上，从 CLAUDE.md 导入它。

21了解更多：[AGENTS.md](/docs/zh-CN/memory#agents-md)

15<h3 id="agent-teams">23<h3 id="agent-teams">

16 Agent teams24 Agent teams

17</h3>25</h3>

122 130

123一个 markdown 文件，包含您为 Claude 编写的持久指令，在每个会话开始时作为系统提示后的用户消息加载。在此处放置项目约定、架构笔记和"始终执行 X"规则。Project-root CLAUDE.md 在 [compaction](#compaction) 期间保留，之后从磁盘重新读取。131一个 markdown 文件，包含您为 Claude 编写的持久指令，在每个会话开始时作为系统提示后的用户消息加载。在此处放置项目约定、架构笔记和"始终执行 X"规则。Project-root CLAUDE.md 在 [compaction](#compaction) 期间保留，之后从磁盘重新读取。

124 132

125您可以在项目范围内的 `./CLAUDE.md` 或 `./.claude/CLAUDE.md`、用户范围内的 `~/.claude/CLAUDE.md` 或作为组织的[托管策略](#managed-settings)放置 CLAUDE.md。所有发现的文件都被连接到上下文中，而不是相互覆盖，按从最广泛的范围到最具体的范围排序。133您可以在项目范围内的 `./CLAUDE.md` 或 `./.claude/CLAUDE.md`、用户范围内的 `~/.claude/CLAUDE.md` 或作为组织的[托管策略](#managed-settings)放置 CLAUDE.md。所有发现的文件都被连接到上下文中，而不是相互覆盖，按从最广泛的范围到最具体的范围排序。Claude Code 也可以加载项目的 [AGENTS.md](#agents-md) 文件，单独或与 CLAUDE.md 一起。

126 134

127了解更多：[CLAUDE.md files](/docs/zh-CN/memory#claude-md-files)135了解更多：[CLAUDE.md files](/docs/zh-CN/memory#claude-md-files)

128 136

137<h3 id="cloud-session">

138 Cloud session

139</h3>

140

141一个 Claude Code 会话，在您关闭笔记本电脑后继续运行，因为它在云基础设施上运行而不是在您的机器上：默认由 Anthropic 管理，或由您的组织运营的[自托管环境](/docs/zh-CN/self-hosted-environments)。您可以从 claude.ai/code、Claude 移动应用、选择了**Cloud**的 Desktop 应用、`claude --cloud` 或[例程](/docs/zh-CN/routines)启动一个。在您的终端、IDE 或选择了**Local**的 Desktop 应用中的会话是本地会话；要从另一台设备访问本地会话，请使用[远程控制](#remote-control)。

142

143了解更多：[Use Claude Code in the cloud](/docs/zh-CN/claude-code-on-the-web)

144

129<h3 id="command">145<h3 id="command">

130 Command146 Command

131</h3>147</h3>

332 Remote Control348 Remote Control

333</h3>349</h3>

334 350

335一种通过 claude.ai 从您的手机或浏览器继续本地 Claude Code 会话的方式。您的代码执行和文件保留在您的机器上；界面是远程的。与在 web 上运行的 Claude Code 不同，后者在云沙箱中运行。351一种通过 claude.ai 从您的手机或浏览器继续本地 Claude Code 会话的方式。您的代码执行和文件保留在您的机器上；界面是远程的。与[云会话](/docs/zh-CN/claude-code-on-the-web)不同，后者在云沙箱中运行。

336 352

337了解更多：[Remote Control](/docs/zh-CN/remote-control)353了解更多：[Remote Control](/docs/zh-CN/remote-control)

338 354

408 Teleport424 Teleport

409</h3>425</h3>

410 426

411一个命令 `/teleport`，将云 Claude Code 会话拉入您的本地终端。Claude 获取分支、加载对话历史并从 web 会话的最后状态恢复。反向方向是 `--cloud`，它将本地任务发送到 web 上运行。427一个命令 `/teleport`，将云 Claude Code 会话拉入您的本地终端。Claude 获取分支、加载对话历史并从云会话的最后状态恢复。反向方向是 `--cloud`，它将本地任务发送到云上运行。

412 428

413了解更多：[从 web 到终端](/docs/zh-CN/claude-code-on-the-web#from-web-to-terminal)429了解更多：[从云到终端](/docs/zh-CN/claude-code-on-the-web#from-cloud-to-terminal)

414 430

415<h3 id="tool">431<h3 id="tool">

416 Tool432 Tool

461这些术语出现在较旧的文档、博客文章和社区内容中。搜索此网站时使用当前名称。477这些术语出现在较旧的文档、博客文章和社区内容中。搜索此网站时使用当前名称。

462 478

463| 旧术语 | 现在称为 | 注释 |479| 旧术语 | 现在称为 | 注释 |

464| --------------- | --------------------------------------------- | -------------------------- |480| ----------------------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------- |

482| Web session; "Claude Code on the web" as the name for any cloud session | [Cloud session](#cloud-session) | "Claude Code on the web" 现在仅命名 claude.ai/code 处的浏览器界面 |

headless.md +8 −2

Details

343`--allowedTools` 标志使用 [权限规则语法](/docs/zh-CN/settings-reference#permission-rule-syntax)。尾部的 ` *` 启用前缀匹配，因此 `Bash(git diff *)` 允许任何以 `git diff` 开头的命令。空格在 `*` 之前很重要：没有它，`Bash(git diff*)` 也会匹配 `git diff-index`。343`--allowedTools` 标志使用 [权限规则语法](/docs/zh-CN/settings-reference#permission-rule-syntax)。尾部的 ` *` 启用前缀匹配，因此 `Bash(git diff *)` 允许任何以 `git diff` 开头的命令。空格在 `*` 之前很重要：没有它，`Bash(git diff*)` 也会匹配 `git diff-index`。

344 344

345<Note>345<Note>

346 用户调用的 [skills](/docs/zh-CN/skills) 和自定义命令在 `-p` 模式下工作：在提示字符串中包含 `/skill-name`，Claude Code 会在运行前展开它。仅在终端界面中运行的内置命令，例如 `/login`，在 `-p` 模式下不可用。`/model`、`/effort`、`/fast`、`/color` 和 `/rename` 接受该值作为参数，例如 `/model sonnet`，`/mcp` 不带参数打印服务器状态的文本摘要；这些形式需要 Claude Code v2.1.205 或更高版本，并遵循每个命令的 [可用性说明](/docs/zh-CN/commands#all-commands)。要从 `-p` 调用更改设置，请将 `key=value` 传递给 `/config`，例如 `/config thinking=false`。346 命令支持在 `-p` 模式下有所不同：

347

348 * 用户调用的 [skills](/docs/zh-CN/skills) 和自定义命令工作。在提示字符串中包含 `/skill-name`，Claude Code 会在运行前展开它。

349 * 仅在终端界面中运行的内置命令，例如 `/login`，在 `-p` 模式下不可用。

350 * `/model`、`/effort`、`/fast`、`/color` 和 `/rename` 接受该值作为参数，例如 `/model sonnet`，`/mcp` 不带参数打印服务器状态的文本摘要。这些形式需要 Claude Code v2.1.205 或更高版本，并遵循每个命令的 [可用性说明](/docs/zh-CN/commands#all-commands)。

351 * 要从 `-p` 调用更改设置，请将 `key=value` 传递给 `/config`，例如 `/config thinking=false`。

352 * `/output-style <style>` 切换 [输出样式](/docs/zh-CN/output-styles)，`/output-style` 单独列出它们。需要 Claude Code v2.1.269 或更高版本。

347</Note>353</Note>

348 354

349<h3 id="customize-the-system-prompt">355<h3 id="customize-the-system-prompt">

366 继续对话372 继续对话

367</h3>373</h3>

368 374

369使用 `--continue` 继续最近的对话，或使用 `--resume` 与会话 ID 继续特定对话。在 Claude Code v2.1.257 或更高版本上，当您传递 `--continue` 时，Claude Code 会打开已完成的[后台会话](/docs/zh-CN/sessions#resume-a-session)，但不会打开仍在运行的后台会话。此示例运行审查，然后发送后续提示：375使用 `--continue` 继续最近的对话，或使用 `--resume` 与会话 ID 继续特定对话。在 Claude Code v2.1.257 或更高版本上，当您传递 `--continue` 时，Claude Code 会打开已完成的 [后台会话](/docs/zh-CN/sessions#resume-a-session)，但不会打开仍在运行的后台会话。此示例运行审查，然后发送后续提示：

370 376

371```bash theme={null}377```bash theme={null}

372# First request378# First request

how-claude-code-works.md +2 −2

Details

76* **您的项目。** 您目录和子目录中的文件，以及其他地方有您许可的文件。76* **您的项目。** 您目录和子目录中的文件，以及其他地方有您许可的文件。

77* **您的终端。** 您可以运行的任何命令：构建工具、git、包管理器、系统实用程序、脚本。如果您可以从命令行做到，Claude 也可以。77* **您的终端。** 您可以运行的任何命令：构建工具、git、包管理器、系统实用程序、脚本。如果您可以从命令行做到，Claude 也可以。

78* **您的 git 状态。** 当前分支、未提交的更改和最近的提交历史。78* **您的 git 状态。** 当前分支、未提交的更改和最近的提交历史。

~~79* **您的 [CLAUDE.md](/docs/zh-CN/memory)。** 一个 markdown 文件，您可以在其中存储项目特定的说明、约定和 Claude 应该在每个会话中了解的上下文。~~79* **您的 [CLAUDE.md](/docs/zh-CN/memory)。** 一个 markdown 文件，您可以在其中存储项目特定的说明、约定和 Claude 应该在每个会话中了解的上下文。如果您的存储库有用于其他编码代理的 AGENTS.md，Claude [可以自己读取](/docs/zh-CN/memory#agents-md)或与 CLAUDE.md 一起读取。

80* **[自动内存](/docs/zh-CN/memory#auto-memory)。** Claude 在您工作时自动保存的学习内容，如您的偏好。MEMORY.md 的前 200 行或 25KB（以先到者为准）在每个会话开始时加载。80* **[自动内存](/docs/zh-CN/memory#auto-memory)。** Claude 在您工作时自动保存的学习内容，如您的偏好。MEMORY.md 的前 200 行或 25KB（以先到者为准）在每个会话开始时加载。

81* **您配置的扩展。** 用于外部服务的 [MCP servers](/docs/zh-CN/mcp)、用于工作流的 [skills](/docs/zh-CN/skills)、用于委派工作的 [subagents](/docs/zh-CN/sub-agents) 和用于浏览器交互的 [Claude in Chrome](/docs/zh-CN/chrome)。81* **您配置的扩展。** 用于外部服务的 [MCP servers](/docs/zh-CN/mcp)、用于工作流的 [skills](/docs/zh-CN/skills)、用于委派工作的 [subagents](/docs/zh-CN/sub-agents) 和用于浏览器交互的 [Claude in Chrome](/docs/zh-CN/chrome)。

82 82

86 环境和界面86 环境和界面

87</h2>87</h2>

88 88

~~89上面描述的代理循环、工具和功能在您使用 Claude Code 的任何地方都是相同的。改变的是代码执行的位置以及您与它交互的方式。~~89[代理循环](#the-agentic-loop)、[工具](#tools) 和功能在您使用 Claude Code 的任何地方都是相同的。改变的是代码执行的位置以及您与它交互的方式。

90 90

91<h3 id="execution-environments">91<h3 id="execution-environments">

92 执行环境92 执行环境

interactive-mode.md +2 −1

Details

615 615

616* **跳转到文件**：单击列表中的其行。使用鼠标滚轮滚动面板。当文件列表本身太长无法容纳时，使用 `Alt+Up` 和 `Alt+Down` 或 `Ctrl+Up` 和 `Ctrl+Down` 滚动它。616* **跳转到文件**：单击列表中的其行。使用鼠标滚轮滚动面板。当文件列表本身太长无法容纳时，使用 `Alt+Up` 和 `Alt+Down` 或 `Ctrl+Up` 和 `Ctrl+Down` 滚动它。

617* **询问 Claude 关于特定行的问题**：在面板中用鼠标选择它们。Claude Code 将选择附加到您的下一个提示，并在您发送之前在输入旁边显示行数。617* **询问 Claude 关于特定行的问题**：在面板中用鼠标选择它们。Claude Code 将选择附加到您的下一个提示，并在您发送之前在输入旁边显示行数。

618 * 要在不选择的情况下发送提示，请将光标移动到行数指示器之后，然后按 `Backspace` 删除它。需要 Claude Code v2.1.271 或更高版本。

618* **显示面板遗漏的文件**：列表跳过测试文件和生成的文件，并将此会话之前的更改折叠为底部的一行。单击任一计数行以展开它。619* **显示面板遗漏的文件**：列表跳过测试文件和生成的文件，并将此会话之前的更改折叠为底部的一行。单击任一计数行以展开它。

619* **更改面板比较的内容**：按 `Ctrl+X B` 在此会话的更改、您的未提交更改作为一个列表，以及自您的分支从默认分支分离以来的所有内容之间循环。Claude Code 为每个项目记住该选择。620* **更改面板比较的内容**：按 `Ctrl+X B` 在此会话的更改、您的未提交更改作为一个列表，以及自您的分支从默认分支分离以来的所有内容之间循环。Claude Code 为每个项目记住该选择。

620 621

650在 [VS Code 扩展](/docs/zh-CN/vs-code#use-the-prompt-box)的聊天面板中，`/btw` 打开一个面板而不是本节描述的覆盖层，你可以直接在面板中提出后续问题。该面板的线程在窗口重新加载后仍然存在，遵循该页面描述的保留计划。你需要 v2.1.227 或更高版本的扩展。早期的扩展版本不提供 `/btw`。651在 [VS Code 扩展](/docs/zh-CN/vs-code#use-the-prompt-box)的聊天面板中，`/btw` 打开一个面板而不是本节描述的覆盖层，你可以直接在面板中提出后续问题。该面板的线程在窗口重新加载后仍然存在，遵循该页面描述的保留计划。你需要 v2.1.227 或更高版本的扩展。早期的扩展版本不提供 `/btw`。

651 652

652* **Claude 工作时可用**：即使 Claude 正在处理响应，你也可以运行 `/btw`。附加问题独立运行，不会中断主要回合。它可以看到到目前为止对话中的所有内容，除了 Claude 仍在编写的回复。653* **Claude 工作时可用**：即使 Claude 正在处理响应，你也可以运行 `/btw`。附加问题独立运行，不会中断主要回合。它可以看到到目前为止对话中的所有内容，除了 Claude 仍在编写的回复。

653* **无工具访问**：附加问题仅从上下文中已有的内容回答。Claude 在回答附加问题时无法读取文件、运行命令或搜索。654* **无工具访问**：附加问题仅从上下文中已有的内容回答。Claude 在回答附加问题时无法读取文件、运行命令或搜索。如果 Claude 无论如何都将工具调用写成文本，答案会以一条注释结尾，说明没有执行任何操作。

654* **单一响应**：覆盖层中没有后续回合。要继续线程，请提出另一个 `/btw` 问题。要在本地会话中继续使用完整的工具访问，按 `f` 将此问题和答案分叉到 [后台子代理](/docs/zh-CN/sub-agents#fork-the-current-conversation)。655* **单一响应**：覆盖层中没有后续回合。要继续线程，请提出另一个 `/btw` 问题。要在本地会话中继续使用完整的工具访问，按 `f` 将此问题和答案分叉到 [后台子代理](/docs/zh-CN/sub-agents#fork-the-current-conversation)。

655* **低成本**：当对话的 [prompt cache](/docs/zh-CN/prompt-caching) 预热时，附加问题的成本仅略高于答案本身。656* **低成本**：当对话的 [prompt cache](/docs/zh-CN/prompt-caching) 预热时，附加问题的成本仅略高于答案本身。

656 657

jetbrains.md +1 −1

Details

231 安全考虑231 安全考虑

232</h2>232</h2>

233 233

234当 Claude Code 在 JetBrains IDE 中以 [`acceptEdits` 权限模式](/docs/zh-CN/permission-modes#auto-approve-file-edits-with-acceptedits-mode)运行时，它可能能够修改 IDE 配置文件，这些文件可以由您的 IDE 自动执行。这可能会增加在 `acceptEdits` 模式下运行 Claude Code 的风险，并允许绕过 Claude Code 对 bash 执行的权限提示。234当 Claude Code 在 JetBrains IDE 中以 [`acceptEdits` 权限模式](/docs/zh-CN/permission-modes#auto-approve-file-edits-with-acceptedits-mode)运行时，它可能能够修改 IDE 配置文件，这些文件可以由您的 IDE 自动执行。这可能会增加在 `acceptEdits` 模式下运行 Claude Code 的风险，并允许绕过 Claude Code 对 Bash 执行的权限提示。

235 235

236在 JetBrains IDE 中运行时，请考虑：236在 JetBrains IDE 中运行时，请考虑：

237 237

llm-gateway.md +1 −1

Details

28* **审计日志**：记录每个模型请求以实现合规性28* **审计日志**：记录每个模型请求以实现合规性

29* **提供商切换**：在网关配置中更改提供商，无需接触开发人员机器29* **提供商切换**：在网关配置中更改提供商，无需接触开发人员机器

30 30

31除了提供商切换外，所有这些都适用于上游是 Anthropic 的 API 还是[云提供商](/docs/zh-CN/third-party-integrations)。提供商切换而无需重新配置开发人员机器也取决于网关公开单个[Anthropic 格式端点](/docs/zh-CN/llm-gateway-protocol#api-formats)，无论上游如何；公开提供商自己格式的网关将客户端配置与该提供商绑定。31除了提供商切换外，所有这些都适用于上游是 Anthropic 的 API 还是[云提供商](/docs/zh-CN/third-party-integrations)。提供商切换而无需重新配置开发人员机器也取决于网关公开单个[Anthropic 格式端点](/docs/zh-CN/llm-gateway-protocol#api-formats)，无论上游如何；公开提供商自己格式的网关将客户端配置与该提供商绑定，并改变[Claude Code 发送的内容以及它应用的默认值](/docs/zh-CN/llm-gateway-protocol#how-the-connection-method-changes-client-behavior)。

32 32

33权衡是网关成为您的组织运营的基础设施。Claude Code 在每个版本中添加功能，不转发这些功能的网关会破坏相应的功能，因此网关产品需要随着 Claude Code 的发展而保持更新。[网关兼容性指南](/docs/zh-CN/llm-gateway-protocol)涵盖要转发的内容。33权衡是网关成为您的组织运营的基础设施。Claude Code 在每个版本中添加功能，不转发这些功能的网关会破坏相应的功能，因此网关产品需要随着 Claude Code 的发展而保持更新。[网关兼容性指南](/docs/zh-CN/llm-gateway-protocol)涵盖要转发的内容。

34 34

llm-gateway-connect.md +6 −5

Details

286 ```286 ```

287</CodeGroup>287</CodeGroup>

288 288

289<h3 id="slack-web-and-remote-control">289<h3 id="slack-cloud-sessions-and-remote-control">

290 Slack、网络和远程控制290 Slack、云会话和远程控制

291</h3>291</h3>

292 292

293[Slack 中的 Claude Code](/docs/zh-CN/slack) 和[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web) 是 Anthropic 托管的产品，始终使用 Anthropic 的 API；它们不是网关部署的一部分。在云会话的环境配置中设置的网关变量不适用。如果您的流量必须保持在网关上，请不要为这些用户启用这些界面。293[Slack 中的 Claude Code](/docs/zh-CN/slack) 和[云会话](/docs/zh-CN/claude-code-on-the-web)始终使用 Anthropic 的 API；它们不是网关部署的一部分。在云会话的环境配置中设置的网关变量不适用。如果您的流量必须保持在网关上，请不要为这些用户启用这些界面。

294 294

295[远程控制](/docs/zh-CN/remote-control)和[语音听写](/docs/zh-CN/voice-dictation)都依赖于 claude.ai 身份：远程控制将实时会话与您的账户配对，语音听写到达 claude.ai 转录端点。当 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 处于活动状态时，它们不可用。从 v2.1.196 开始，当 `ANTHROPIC_BASE_URL` 指向非 Anthropic 主机时，远程控制也被禁用，因此仅使用 claude.ai 登录是不够的。295[远程控制](/docs/zh-CN/remote-control)和[语音听写](/docs/zh-CN/voice-dictation)都依赖于 claude.ai 身份：远程控制将实时会话与您的账户配对，语音听写到达 claude.ai 转录端点。当 `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 处于活动状态时，它们不可用。远程控制在 `ANTHROPIC_BASE_URL` 指向非 Anthropic 主机时也被禁用，因此仅使用 claude.ai 登录是不够的。在 v2.1.196 之前，非 Anthropic 基础 URL 不会阻止远程控制。

296 296

297要恢复任一功能，请使用 claude.ai 登录并取消设置它检查的网关变量。`claude doctor` 的远程控制部分命名要取消设置的凭证变量。297要恢复任一功能，请使用 claude.ai 登录并取消设置该功能检查的网关变量。`claude doctor` 的远程控制部分命名当前阻止远程控制的内容。

298 298

299* 语音听写：取消设置网关凭证299* 语音听写：取消设置网关凭证

300* 远程控制：取消设置网关凭证和 `ANTHROPIC_BASE_URL`300* 远程控制：取消设置网关凭证和 `ANTHROPIC_BASE_URL`

587| `400` 错误命名 `context_management`、`Extra inputs are not permitted` 或其他无法识别的字段 | 网关将请求转发到上游，该上游拒绝 Claude Code 发送到 Anthropic 格式端点的字段 | 设置 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`，它抑制大多数预发布字段；请参阅[功能传递](/docs/zh-CN/llm-gateway-protocol#feature-pass-through)。某些 beta 不受此标志限制；对于那些，设置匹配的 `CLAUDE_CODE_USE_*` 提供商变量，以便 Claude Code 仅发送该提供商接受的内容 |587| `400` 错误命名 `context_management`、`Extra inputs are not permitted` 或其他无法识别的字段 | 网关将请求转发到上游，该上游拒绝 Claude Code 发送到 Anthropic 格式端点的字段 | 设置 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`，它抑制大多数预发布字段；请参阅[功能传递](/docs/zh-CN/llm-gateway-protocol#feature-pass-through)。某些 beta 不受此标志限制；对于那些，设置匹配的 `CLAUDE_CODE_USE_*` 提供商变量，以便 Claude Code 仅发送该提供商接受的内容 |

588| `400` 错误命名 `thinking` 或 `adaptive`，例如 `Input tag 'adaptive' found` | 上游模型构建不接受自适应推理，Claude Code 为 Claude 4.6 及更高版本的模型请求 | 升级网关的上游。在 Opus 4.6 和 Sonnet 4.6 上，`CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 代替有效。[模型配置](/docs/zh-CN/model-config)能力变量仅适用于提供商配置，例如 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_VERTEX`，不在 `ANTHROPIC_BASE_URL` 网关后面 |588| `400` 错误命名 `thinking` 或 `adaptive`，例如 `Input tag 'adaptive' found` | 上游模型构建不接受自适应推理，Claude Code 为 Claude 4.6 及更高版本的模型请求 | 升级网关的上游。在 Opus 4.6 和 Sonnet 4.6 上，`CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` 代替有效。[模型配置](/docs/zh-CN/model-config)能力变量仅适用于提供商配置，例如 `CLAUDE_CODE_USE_BEDROCK` 和 `CLAUDE_CODE_USE_VERTEX`，不在 `ANTHROPIC_BASE_URL` 网关后面 |

589| `400` 错误声明网关自己的措辞中的上下文或令牌限制，例如 `ContextWindowExceededError` 或 `prompt token count of N exceeds the limit of M` | 网关强制执行比模型的本机窗口更小的上下文，并重写上游错误，因此 Claude Code 不会将其识别为[过长错误](/docs/zh-CN/errors#prompt-is-too-long)，也不会自动紧凑和重试 | 运行 `/compact` 以恢复会话。要防止它，请将 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 设置为网关的限制；Claude Code 将该值限制在至少 100,000 令牌和最多模型的上下文窗口，因此您无法匹配低于 100,000 的网关限制，`/compact` 仍然是那里的恢复。还要将 `CLAUDE_CODE_MAX_OUTPUT_TOKENS` 设置为低于网关模型的输出限制 |589| `400` 错误声明网关自己的措辞中的上下文或令牌限制，例如 `ContextWindowExceededError` 或 `prompt token count of N exceeds the limit of M` | 网关强制执行比模型的本机窗口更小的上下文，并重写上游错误，因此 Claude Code 不会将其识别为[过长错误](/docs/zh-CN/errors#prompt-is-too-long)，也不会自动紧凑和重试 | 运行 `/compact` 以恢复会话。要防止它，请将 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 设置为网关的限制；Claude Code 将该值限制在至少 100,000 令牌和最多模型的上下文窗口，因此您无法匹配低于 100,000 的网关限制，`/compact` 仍然是那里的恢复。还要将 `CLAUDE_CODE_MAX_OUTPUT_TOKENS` 设置为低于网关模型的输出限制 |

590| `400` 错误在每个请求上，在网关自己的措辞中拒绝工具的输入架构或其 `pattern`，在 Claude Code v2.1.265 到 v2.1.267 上 | 在这些版本的逐步推出中，[Artifact 工具](/docs/zh-CN/artifacts#availability)架构携带带有 `\p{...}` Unicode 字符类的正则表达式。Anthropic API 接受它，但检查每个工具架构的 `pattern` 的网关或上游使用其自己的正则表达式引擎拒绝整个请求 | 更新到 v2.1.268 或更高版本，它不发送正则表达式。在受影响的版本上，[关闭 artifacts](/docs/zh-CN/artifacts#disable-artifacts)，这会从请求中删除工具及其架构 |

590| 模型从 `/model` 选择器中缺失 | 网关模型名称不在 Claude Code 的内置列表中，或 Claude Code 显示替换内置选项的 [`modelPicker`](/docs/zh-CN/settings-reference#modelpicker) 阵容 | 启用[网关模型发现](#add-gateway-models-to-the-model-picker)或使用[模型配置](/docs/zh-CN/model-config)变量添加名称。如果 Claude Code 显示替换 `modelPicker` 阵容，请将网关模型添加到其中，或在托管设置提供时要求您的管理员添加它们 |591| 模型从 `/model` 选择器中缺失 | 网关模型名称不在 Claude Code 的内置列表中，或 Claude Code 显示替换内置选项的 [`modelPicker`](/docs/zh-CN/settings-reference#modelpicker) 阵容 | 启用[网关模型发现](#add-gateway-models-to-the-model-picker)或使用[模型配置](/docs/zh-CN/model-config)变量添加名称。如果 Claude Code 显示替换 `modelPicker` 阵容，请将网关模型添加到其中，或在托管设置提供时要求您的管理员添加它们 |

591| `/fast` 报告 `Fast mode unavailable due to network connectivity issues`，而推理请求有效 | [快速模式](/docs/zh-CN/fast-mode)可用性检查直接转到 `api.anthropic.com`，不遵循 `ANTHROPIC_BASE_URL`，因此阻止的直接出口会导致检查失败。当检查呈现来自 `ANTHROPIC_API_KEY` 或 `apiKeyHelper` 的网关颁发的密钥且 Anthropic 拒绝它时，在开放网络上也会出现相同的消息 | 如果出口被阻止，请将 `api.anthropic.com` 列入白名单，或设置跳过变量；对于被拒绝的网关密钥，只有跳过变量有帮助。请参阅[在代理和 LLM 网关后面使用快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) |592| `/fast` 报告 `Fast mode unavailable due to network connectivity issues`，而推理请求有效 | [快速模式](/docs/zh-CN/fast-mode)可用性检查直接转到 `api.anthropic.com`，不遵循 `ANTHROPIC_BASE_URL`，因此阻止的直接出口会导致检查失败。当检查呈现来自 `ANTHROPIC_API_KEY` 或 `apiKeyHelper` 的网关颁发的密钥且 Anthropic 拒绝它时，在开放网络上也会出现相同的消息 | 如果出口被阻止，请将 `api.anthropic.com` 列入白名单，或设置跳过变量；对于被拒绝的网关密钥，只有跳过变量有帮助。请参阅[在代理和 LLM 网关后面使用快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) |

592| `/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) |593| `/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) |

llm-gateway-protocol.md +87 −31

Details

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

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

4 4

~~5# Claude Code gateway 兼容性指南~~5# Claude Code 网关兼容性指南

6 6

~~7> 保持 LLM gateway 与 Claude Code 兼容：它调用的端点、必须转发的请求头和请求体字段，以及删除它们时会破坏什么。~~7> 保持 LLM 网关与 Claude Code 兼容：它调用的端点、必须转发的标头和正文字段，以及删除它们时会破坏的功能。

8 8

9本页面记录了 Claude Code 发送到 gateway 的请求，包括它调用的端点、gateway 必须转发的请求头和请求体字段，以及当 gateway 不转发这些内容时哪些功能会停止工作。本页面是为配置 gateway 产品以与 Claude Code 配合工作的运营人员编写的。9本页面记录了 Claude Code 发送到网关的请求，包括它调用的端点、网关必须转发的标头和正文字段，以及不转发时停止工作的功能。本指南是为配置网关产品以与 Claude Code 兼容的运营人员编写的。

10 10

11[Claude apps gateway](/docs/zh-CN/claude-apps-gateway)（Anthropic 的自托管 gateway）在 `GET /protocol` 处提供自己的端点参考，涵盖该 gateway 的登录、推理、托管设置、模型发现和遥测端点。这是一份与本指南分开的文档。11[Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 是 Anthropic 的自托管网关，在 `GET /protocol` 处提供自己的端点参考，涵盖该网关的登录、推理、托管设置、模型发现和遥测端点。这是一份与本指南分开的文档。

12 12

13<Note>13<Note>

~~14 * 要为您的组织推出现有或第三方 gateway，请参阅[推出 LLM gateway](/docs/zh-CN/llm-gateway-rollout)~~14 * 要为您的组织推出现有或第三方网关，请参阅[推出 LLM 网关](/docs/zh-CN/llm-gateway-rollout)

~~15 * 如果您是使用给定凭证向 gateway 验证 Claude Code 的个人开发者，请参阅[将 Claude Code 连接到 LLM gateway](/docs/zh-CN/llm-gateway-connect)~~15 * 如果您是使用给定的凭证向网关验证 Claude Code 的个人开发者，请参阅[将 Claude Code 连接到 LLM 网关](/docs/zh-CN/llm-gateway-connect)

16</Note>16</Note>

17 17

18本页面涵盖：18本页面涵盖：

19 19

20* [API 格式](#api-formats)和每种格式要提供的端点20* [API 格式](#api-formats)和每种格式要提供的端点

~~21* [请求头](#request-headers)：哪些必须到达上游，哪些您的 gateway 可以使用~~21* [按连接方法的客户端行为](#how-the-connection-method-changes-client-behavior)：模型 ID、`anthropic-beta` 值、请求字段和默认值在格式和 Claude apps 网关登录之间的差异

~~22* [系统提示归属块](#system-prompt-attribution-block)及其与提示缓存的交互方式~~22* [请求标头](#request-headers)：哪些必须到达上游，哪些您的网关可以使用

~~23* [功能传递](#feature-pass-through)：当请求头或请求体字段被删除时会破坏什么~~23* [响应标头](#response-headers)：返回什么以使停滞检测、重试和使用限制显示工作

24* [系统提示属性块](#system-prompt-attribution-block)及其与提示缓存的交互方式

25* [功能传递](#feature-pass-through)：删除标头或正文字段时会破坏什么

24* [模型发现](#model-discovery)26* [模型发现](#model-discovery)

25 27

~~26本页面对您的 gateway 处理每个请求头和请求体字段的方式使用两个术语：~~28本页面使用两个术语来描述您的网关对每个标头和正文字段的处理方式：

27 29

~~28* **转发不变**：将其逐字节传递到上游~~30* **转发不变**：逐字节将其传递到上游

~~29* **使用**：gateway 可能会读取它用于路由、归属或跟踪，不需要转发它~~31* **使用**：网关可能会读取它以进行路由、属性或跟踪，不需要转发它

30 32

31任何未标记为转发不变的内容都可以由您使用或忽略。33任何未标记为转发不变的内容都可以由您使用或忽略。

32 34

34 API 格式36 API 格式

35</h2>37</h2>

36 38

~~37gateway 必须向 Claude Code 客户端公开以下至少一种 API 格式。客户端选择一种格式，并通过下表"选择者"列中的变量将 Claude Code 指向您的 gateway。~~39网关必须向 Claude Code 客户端公开以下至少一种 API 格式。客户端选择一种格式，并通过下表"选择方式"列中的变量将 Claude Code 指向您的网关。

38 40

~~39Google Cloud 的 Agent Platform 是 Google Cloud 的 Claude 端点，原名 Vertex AI；其变量名保留 `VERTEX` 拼写。~~41Google Cloud 的 Agent Platform 是 Google Cloud 的 Claude 端点，原名为 Vertex AI；其变量名保留 `VERTEX` 拼写。

40 42

41| 格式 | 选择者 | 端点 | 转发不变 |43| 格式 | 选择方式 | 端点 | 原样转发 |

42| :--------------------------------------- | :---------------------------------------------------------- | :----------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |44| :--------------------------------------- | :---------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------- |

44| Amazon Bedrock InvokeModel | `ANTHROPIC_BEDROCK_BASE_URL` 配合 `CLAUDE_CODE_USE_BEDROCK=1` | `/model/{model}/invoke`、`/model/{model}/invoke-with-response-stream`、`/model/{model}/count-tokens`（可选） | `anthropic_beta` 和 `anthropic_version` 请求体字段 |46| Amazon Bedrock InvokeModel | `ANTHROPIC_BEDROCK_BASE_URL` 配合 `CLAUDE_CODE_USE_BEDROCK=1` | `/model/{model}/invoke`, `/model/{model}/invoke-with-response-stream`, `/model/{model}/count-tokens`（可选） | `anthropic_beta` 和 `anthropic_version` 请求体字段 |

45| Google Cloud 的 Agent Platform rawPredict | `ANTHROPIC_VERTEX_BASE_URL` 配合 `CLAUDE_CODE_USE_VERTEX=1` | `:rawPredict`、`:streamRawPredict`、`count-tokens:rawPredict`（可选） | `anthropic-beta` 和 `anthropic-version` 请求头，以及 `anthropic_version` 请求体字段 |47| Google Cloud's Agent Platform rawPredict | `ANTHROPIC_VERTEX_BASE_URL` 配合 `CLAUDE_CODE_USE_VERTEX=1` | `:rawPredict`, `:streamRawPredict`, `count-tokens:rawPredict`（可选） | `anthropic-beta` 和 `anthropic-version` 请求头，以及 `anthropic_version` 请求体字段 |

46 48

47<h3 id="foundry-and-claude-platform-on-aws">49<h3 id="foundry-and-claude-platform-on-aws">

48 Foundry 和 AWS 上的 Claude Platform50 Foundry 和 AWS 上的 Claude Platform

49</h3>51</h3>

50 52

51Microsoft Foundry 和 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 实现了 Anthropic Messages 格式。Claude Code 通过它们自己的变量 `ANTHROPIC_FOUNDRY_BASE_URL` 和 `ANTHROPIC_AWS_BASE_URL` 路由到它们，但 fronting 任一方的 gateway 实现上面的 Anthropic Messages 行。fronting AWS 上的 Claude Platform 的 gateway 还必须转发 `anthropic-workspace-id` 请求头，[该平台在每个请求上都需要](/docs/zh-CN/claude-platform-on-aws)。53Microsoft Foundry 和 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 实现了 Anthropic Messages 格式。Claude Code 通过它们自己的变量 `ANTHROPIC_FOUNDRY_BASE_URL` 和 `ANTHROPIC_AWS_BASE_URL` 路由到它们，但网关在任一前面实现上述 Anthropic Messages 行。在 AWS 上的 Claude Platform 前面的网关还必须转发 `anthropic-workspace-id` 头，[该平台在每个请求上都需要](/docs/zh-CN/claude-platform-on-aws)。

52 54

53<h3 id="optional-endpoints-and-startup-traffic">55<h3 id="optional-endpoints-and-startup-traffic">

54 可选端点和启动流量56 可选端点和启动流量

55</h3>57</h3>

56 58

~~57令牌计数端点是唯一可选的：当它们不存在时，Claude Code 会回退到基于字符的上下文使用情况估计。~~59令牌计数端点是唯一可选的：当它们不存在时，Claude Code 会回退到基于字符的上下文使用估计。

58 60

~~59按路径匹配，而不是完整 URL：~~61根据路径而不是完整 URL 进行匹配：

60 62

61* 推理请求发送到 `/v1/messages?beta=true`63* 推理请求发送到 `/v1/messages?beta=true`

62* Google Cloud 的 Agent Platform 方法后缀附加到发布者模型路径，如 `/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict`64* Google Cloud 的 Agent Platform 方法后缀附加到发布者模型路径，如 `/projects/{project}/locations/{location}/publishers/anthropic/models/{model}:streamRawPredict`

63 65

64gateway 还会看到尽力而为的启动流量，它可以拒绝而不会破坏任何东西。Anthropic Messages 格式的 gateway 会收到 `HEAD /api/hello` 连接预热探针，当配置了 HTTP 代理或客户端证书时，Claude Code 会跳过此探针。Amazon Bedrock 格式的 gateway 会收到 `GET /inference-profiles?type=SYSTEM_DEFINED` 请求，以及当配置的模型是推理配置文件时，`GET /inference-profiles/{profile}` 查询。66网关还会看到尽力而为的启动流量，可以拒绝而不会破坏任何东西。Anthropic Messages 格式的网关接收 `HEAD /api/hello` 连接预热探针，当配置了 HTTP 代理或客户端证书时，Claude Code 会跳过该探针。Amazon Bedrock 格式的网关接收 `GET /inference-profiles?type=SYSTEM_DEFINED` 请求，以及当配置的模型是推理配置文件时，`GET /inference-profiles/{profile}` 查询。

65 67

66[快速模式](/docs/zh-CN/fast-mode)可用性检查永远不会出现在 gateway 日志中：它直接调用 `api.anthropic.com` 而不是遵循 `ANTHROPIC_BASE_URL`，因此在阻止直接出站到 `api.anthropic.com` 的网络上，快速模式可能会报告连接错误，而通过 gateway 的推理仍然有效。[WebFetch 域名安全检查](/docs/zh-CN/data-usage#webfetch-domain-safety-check)也直接调用 `api.anthropic.com`。[在代理和 LLM gateway 后面使用快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)涵盖了恢复它的变量。68[快速模式](/docs/zh-CN/fast-mode)可用性检查永远不会出现在网关日志中：它直接调用 `api.anthropic.com` 而不是遵循 `ANTHROPIC_BASE_URL`，因此在阻止直接出站到 `api.anthropic.com` 的网络上，快速模式可能会报告连接错误，而通过网关的推理继续工作。[WebFetch 域安全检查](/docs/zh-CN/data-usage#webfetch-domain-safety-check)也直接调用 `api.anthropic.com`。[在代理和 LLM 网关后面使用快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)涵盖了恢复它的变量。

67 69

68<h3 id="streaming">70<h3 id="streaming">

69 流式传输71 流式传输

70</h3>72</h3>

71 73

~~72流式传输推理响应。Claude Code 在流到达时读取它，因此如果您的 gateway 在中继之前缓冲完整响应，Claude Code 会停滞。~~74流式传输推理响应。Claude Code 在流到达时读取流，因此如果您的网关在中继之前缓冲完整响应，Claude Code 会停滞。

73 75

74当客户端使用 Amazon Bedrock 格式时，不修改地中继 `InvokeModelWithResponseStream` 响应体及其 `Content-Type: application/vnd.amazon.eventstream` 请求头，并且不要将流转换为服务器发送事件。请参阅[在 gateway 或代理后面的流式传输错误](/docs/zh-CN/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。76当客户端使用 Amazon Bedrock 格式时，原样中继 `InvokeModelWithResponseStream` 响应体及其 `Content-Type: application/vnd.amazon.eventstream` 头，不要将流转换为服务器发送事件。请参阅[网关或代理后面的流式传输错误](/docs/zh-CN/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。

75 77

76同时转发保活 ping。在通过 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 的连接上，Claude Code 计算您的 gateway 中继的每一个字节，包括 SSE `ping` 事件和注释行，并默认在 300 秒内没有流量的流上中止。上游的 ping 是长思考暂停期间唯一的流量，因此如果您的 gateway 剥离或缓冲它们，Claude Code 会在这些暂停期间中止流；[自动重试](/docs/zh-CN/errors#automatic-retries)涵盖了根据响应进度有多远，中止的流会报告什么。完全不发送 ping 的上游，例如 Amazon Bedrock 的二进制事件流，在这些暂停中没有任何东西可转发。当从这样的上游转换时，在静默间隙期间发出您自己的 `ping` 事件。通过 `ANTHROPIC_BEDROCK_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_FOUNDRY_BASE_URL` 到达的 gateway 不被这个字节级监视狗包装，即使它们中继 Anthropic Messages 格式；在那里，[5 分钟空闲超时](/docs/zh-CN/env-vars)会中止静默流，在 `ANTHROPIC_BEDROCK_BASE_URL` 连接上，您可以使用 [`CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK`](/docs/zh-CN/env-vars) 添加字节监视狗。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) 添加字节监视程序。

77 79

78<h3 id="format-mismatch-with-the-upstream">80<h3 id="format-mismatch-with-the-upstream">

79 与上游的格式不匹配81 与上游的格式不匹配

80</h3>82</h3>

81 83

~~82客户端使用的格式决定了您的 gateway 接收的内容。常见的失败模式是客户端发送到您的 gateway 的格式与上游提供商接受的格式之间的不匹配。~~84客户端使用的格式决定了您的网关接收的内容。常见的失败模式是客户端发送到您的网关的格式与其后面的上游提供商接受的格式不匹配。

83 85

84* 当客户端使用 Amazon Bedrock 或 Google Cloud 的 Agent Platform 格式时，Claude Code 仅发送这些提供商接受的完整功能集的子集86* 当客户端使用 Amazon Bedrock 或 Google Cloud 的 Agent Platform 格式时，Claude Code 仅发送这些提供商接受的完整功能集的子集

~~85* 当客户端使用 Anthropic Messages 格式时，Claude Code 发送完整集合，即使您的 gateway 转发到 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上游~~87* 当客户端使用 Anthropic Messages 格式时，Claude Code 发送完整集，即使您的网关转发到 Amazon Bedrock 或 Google Cloud 的 Agent Platform 上游

86 88

~~87弥合这种差异是您的 gateway 的工作。[功能传递](#feature-pass-through)描述了当它不这样做时会破坏什么。~~89弥合这种差异是您的网关的工作。[功能传递](#feature-pass-through)描述了当它不这样做时会破坏什么。

91如果您的上游是 Amazon Bedrock 或 Google Cloud 的 Agent Platform，您可以通过公开该提供商的格式来避免桥接。[通过网关路由到云提供商](/docs/zh-CN/llm-gateway-connect#route-to-a-cloud-provider-through-a-gateway)显示了该格式的客户端配置。

93<h2 id="how-the-connection-method-changes-client-behavior">

94 连接方法如何改变客户端行为

95</h2>

97开发者连接到网关的方式决定了 Claude Code 发送的模型 ID、`anthropic-beta` 值和请求字段，以及它应用的默认值。您的网关会看到以下三种客户端行为之一：

99* **Amazon Bedrock 或 Agent Platform 格式**：开发者设置 `CLAUDE_CODE_USE_BEDROCK=1` 和 `ANTHROPIC_BEDROCK_BASE_URL`，或 `CLAUDE_CODE_USE_VERTEX=1` 和 `ANTHROPIC_VERTEX_BASE_URL`，指向您的网关。Claude Code 使用该提供商的模型 ID、请求字段和默认值。

100* **Anthropic Messages 格式**：开发者将 `ANTHROPIC_BASE_URL` 设置为您的网关。Claude Code 将网关视为 Claude API，无法判断您转发到哪个上游。

101* **Claude apps gateway 登录**：开发者登录到 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway)。该网关使用 Anthropic Messages 格式，但可以路由到任何上游，因此 Claude Code 仅发送 Amazon Bedrock 和 Agent Platform 也接受的 `anthropic-beta` 值和模型能力假设。

102

103<h3 id="requests-and-defaults-by-connection-method">

104 按连接方法的请求和默认值

105</h3>

106

107下表比较了三种连接方法，每行一个行为。它省略了 Microsoft Foundry 和 Claude Platform on AWS，它们也使用 Anthropic Messages 格式，但 Claude Code 通过它们自己的变量访问。有关这些，请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 页面。

108

109| 行为 | Amazon Bedrock 或 Agent Platform 格式 | Anthropic Messages 格式 | Claude apps gateway 登录 |

110| :-------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ |

112| 发送的 `anthropic-beta` 值 | Amazon Bedrock 和 Agent Platform 接受的子集 | [功能传递](#feature-pass-through)下描述的完整集合，除非开发者设置 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](#disable-pre-release-capabilities) | Amazon Bedrock 和 Agent Platform 接受的子集 |

114| 开发者选择加入时的一小时 [prompt cache TTL](/docs/zh-CN/prompt-caching#choose-the-ttl-yourself) | 通过 `cache_control` 中的 `ttl` 字段请求，没有 beta 值 | 通过 `ttl` 字段加上 `anthropic-beta` 中的 `extended-cache-ttl` 值请求，您必须转发 | 请参阅 Claude apps gateway [可用性和限制](/docs/zh-CN/claude-apps-gateway#availability-and-limitations) 表 |

115| [后台任务](/docs/zh-CN/costs#background-token-usage) 的模型，除非 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 固定一个 | 默认 Sonnet 模型，或选择主模型后的主模型，如 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock#4-pin-model-versions) 和 [Agent Platform](/docs/zh-CN/google-vertex-ai#5-pin-model-versions) 页面所述 | 主模型，或当 `ANTHROPIC_API_KEY` 或 `apiKeyHelper` 提供 Anthropic Console 密钥且 `ANTHROPIC_AUTH_TOKEN` 未设置时的默认 Haiku 模型 | 主模型 |

116

117有关每个连接支持的功能以及它默认发送给 Anthropic 的遥测，请参阅 [功能可用性](/docs/zh-CN/feature-availability#availability-by-model-provider) 和 [按 API 提供商的默认行为](/docs/zh-CN/data-usage#default-behaviors-by-api-provider)。

118

119<h3 id="settings-for-unrecognized-model-ids">

120 未识别模型 ID 的设置

121</h3>

122

123两个客户端设置改变了 Claude Code 对它无法识别的模型 ID 的假设，无论开发者使用哪种连接方法：

124

125* **上下文窗口**：Claude Code 假设 200K，或当 ID 包含 `[1m]` 时为 1M。要声明真实窗口，请参阅 [为网关或自定义模型 ID 更正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)

126* **能力**：要给网关别名赋予其后面模型的能力，请使用您分发的设置中的 [`modelOverrides`](/docs/zh-CN/errors#unrecognized-model-id-on-a-request) 条目将该模型的 Anthropic ID 映射到您的别名。有关 `ANTHROPIC_DEFAULT_*_MODEL_SUPPORTED_CAPABILITIES` 变量适用的位置，请参阅 [功能传递](#feature-pass-through)

88 127

89<h2 id="request-headers">128<h2 id="request-headers">

90 请求头129 请求头

115 154

116例外是非 Anthropic 上游，如 Amazon Bedrock 或 Google Cloud 的 Agent Platform，其中弥合架构差异是 gateway 的工作；请参阅[功能传递](#feature-pass-through)。155例外是非 Anthropic 上游，如 Amazon Bedrock 或 Google Cloud 的 Agent Platform，其中弥合架构差异是 gateway 的工作；请参阅[功能传递](#feature-pass-through)。

117 156

157<h2 id="response-headers">

158 响应头

159</h2>

160

161Claude Code 读取这些响应头来检测停滞的流、决定是否以及何时重试，以及显示使用限制。该表列出了每个响应头应返回的内容。同时转发错误响应体不做修改，以便 Claude Code 的[能力拒绝恢复](#automatic-retry-and-error-forwarding)可以匹配上游的错误措辞。

162

163| 头部 | 返回内容及原因 |

164| :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

165| `content-type` | 在流式 Anthropic Messages 格式响应上返回 `text/event-stream`，在 Amazon Bedrock 格式响应上返回 `application/vnd.amazon.eventstream`（不做修改），其中[不同的类型会导致请求失败](/docs/zh-CN/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。[流式传输](#streaming)列出了哪些连接在这些流上运行停滞检测 |

166| `retry-after` | 返回整数秒而不是 HTTP 日期。Claude Code 在下一次[自动重试](/docs/zh-CN/errors#automatic-retries)之前至少等待该时长，在 [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/zh-CN/env-vars) 会话之外，超过 60 的值会停止重试并立即显示错误 |

167| `x-should-retry` | 原样转发上游的值。Claude Code 在决定是否重试失败的请求时将此头部作为一个输入来读取：`true` 标记响应可重试，`false` 标记响应不可重试。有关重试次数、退避和 Claude Code 重试的失败情况，请参阅[自动重试](/docs/zh-CN/errors#automatic-retries) |

168| `anthropic-ratelimit-unified-*` | 在每个响应上原样转发上游的值。Claude Code 在成功响应上读取它们以向使用 claude.ai 登录的开发人员显示针对计划限制的使用情况，在 `429` 上读取它们以区分计划限制或支出上限与临时限流；请参阅[使用限制](/docs/zh-CN/errors#usage-limits) |

169

118<h2 id="system-prompt-attribution-block">170<h2 id="system-prompt-attribution-block">

119 系统提示归属块171 系统提示归属块

120</h2>172</h2>

168Claude Code 在上游拒绝后的操作取决于被拒绝的内容：220Claude Code 在上游拒绝后的操作取决于被拒绝的内容：

169 221

170* 当上游拒绝 `thinking` 字段、中途对话系统消息或这些消息之一上的 `cache_control` 标记时，Claude Code 会重试请求并为对话的其余部分禁用被拒绝的功能222* 当上游拒绝 `thinking` 字段、中途对话系统消息或这些消息之一上的 `cache_control` 标记时，Claude Code 会重试请求并为对话的其余部分禁用被拒绝的功能

171* 当上游拒绝[思考签名](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)时，Claude Code 会重试请求而不包含对话的早期思考块，并将其排除在每个后续请求之外。新响应仍然包括思考223* 当上游拒绝[思考签名](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)时，包括带有 `400` 的拒绝，其消息说该块被 `bound to a different conversation`，Claude Code 会从请求中删除早期思考块，重试，并将其排除在每个后续请求之外。新响应仍然包括思考

172* Claude Code 不重试上下文管理或工具架构字段拒绝，因此这些 `400` 错误到达开发者224* Claude Code 不重试上下文管理或工具架构字段拒绝，因此这些 `400` 错误到达开发者

173 225

226`bound to a different conversation` 拒绝来自 API 的[保留思考](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking)检查，当 `system`、`tools` 或早期 `messages` 内容与产生思考的请求不同时，该检查失败。重写任何该内容的 gateway 可能会导致拒绝本身；[库、代理和网关](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#libraries-proxies-gateways)涵盖了要原封不动地传递的内容。

227

174重试逻辑与上游的错误措辞匹配，因此原封不动地转发错误响应体。将上游错误包装在自己的信封中的 gateway 会破坏恢复路径，即使它保留了状态代码，除非信封的消息携带稳定的 `capability_rejected:` 令牌。[Claude apps gateway 为云提供商的错误措辞替换这些令牌](/docs/zh-CN/claude-apps-gateway-config#upstream-error-messages)，例如 `capability_rejected: prompt_too_long`。228重试逻辑与上游的错误措辞匹配，因此原封不动地转发错误响应体。将上游错误包装在自己的信封中的 gateway 会破坏恢复路径，即使它保留了状态代码，除非信封的消息携带稳定的 `capability_rejected:` 令牌。[Claude apps gateway 为云提供商的错误措辞替换这些令牌](/docs/zh-CN/claude-apps-gateway-config#upstream-error-messages)，例如 `capability_rejected: prompt_too_long`。

175 229

176<h3 id="disable-pre-release-capabilities">230<h3 id="disable-pre-release-capabilities">

211 265

212请求是 `GET /v1/models?limit=1000`，超时为 3 秒，任何重定向都被视为失败，因此凭证不会泄露到重定向目标。响应缓慢或重定向 `/v1/models` 的 gateway，即使是 `http` 到 `https`，也会无声地失败发现；在配置的基础 URL 处直接提供端点。266请求是 `GET /v1/models?limit=1000`，超时为 3 秒，任何重定向都被视为失败，因此凭证不会泄露到重定向目标。响应缓慢或重定向 `/v1/models` 的 gateway，即使是 `http` 到 `https`，也会无声地失败发现；在配置的基础 URL 处直接提供端点。

213 267

268要给缓慢的 gateway 更长的时间，请设置 [`CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS`](/docs/zh-CN/env-vars#variables)。该变量需要 Claude Code v2.1.269 或更高版本。

269

214Claude Code 使用下面两个凭证请求头发送发现请求，并省略其值无法解析的请求头。发送两个请求头需要 Claude Code v2.1.248 或更高版本。早期版本在设置了 `ANTHROPIC_AUTH_TOKEN` 时仅发送 `Authorization`，否则仅发送 `x-api-key`。270Claude Code 使用下面两个凭证请求头发送发现请求，并省略其值无法解析的请求头。发送两个请求头需要 Claude Code v2.1.248 或更高版本。早期版本在设置了 `ANTHROPIC_AUTH_TOKEN` 时仅发送 `Authorization`，否则仅发送 `x-api-key`。

215 271

216* `Authorization`：`ANTHROPIC_AUTH_TOKEN` 作为承载令牌，否则 [`apiKeyHelper`](/docs/zh-CN/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 值作为承载令牌。在这种情况下，Claude Code 在发送请求前等待助手返回。272* `Authorization`：`ANTHROPIC_AUTH_TOKEN` 作为承载令牌，否则 [`apiKeyHelper`](/docs/zh-CN/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 值作为承载令牌。在这种情况下，Claude Code 在发送请求前等待助手返回。

llm-gateway-rollout.md +15 −1

Details

283 283

284| 变化 | 当网关没有跟上时的症状 | 行动 |284| 变化 | 当网关没有跟上时的症状 | 行动 |

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

286| 新的 Claude Code 版本添加 `anthropic-beta` 值和请求正文字段 | 开发者在更新 Claude Code 后报告 `400` 错误，命名新字段；请参阅[功能传递](/docs/zh-CN/llm-gateway-protocol#feature-pass-through) | 逐字转发 `anthropic-*` 标头和请求正文，而不是允许列表；在新 Claude Code 版本到达开发者之前针对网关测试它们 |286| 新的 Claude Code 版本添加 `anthropic-beta` 值和请求正文字段 | 开发者在更新 Claude Code 后报告 `400` 错误，命名新字段；请参阅[功能传递](/docs/zh-CN/llm-gateway-protocol#feature-pass-through) | 逐字转发 `anthropic-*` 标头和请求正文，而不是允许列表；在新 Claude Code 版本到达开发者之前针对网关测试它们，检查[规划 Claude Code 版本升级](#plan-claude-code-version-upgrades)中的区域 |

287| 新的 Claude 模型变得可用 | 开发者选择新模型名称得到 `404`；`/model` 选择器不列出它 | 将模型名称添加到网关的路由配置，然后重新运行[路由检查](#confirm-the-gateway-routes-your-models)。如果您分发 `ANTHROPIC_MODEL` 或默认模型变量，更新托管设置 |287| 新的 Claude 模型变得可用 | 开发者选择新模型名称得到 `404`；`/model` 选择器不列出它 | 将模型名称添加到网关的路由配置，然后重新运行[路由检查](#confirm-the-gateway-routes-your-models)。如果您分发 `ANTHROPIC_MODEL` 或默认模型变量，更新托管设置 |

288| 凭证过期或需要轮换 | 所有开发者请求开始从上游失败，出现 `401` | 按照自己的计划轮换网关的提供商凭证；开发者密钥在网关处轮换，[`apiKeyHelper`](/docs/zh-CN/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 处理每个开发者的轮换，无需重新分发设置 |288| 凭证过期或需要轮换 | 所有开发者请求开始从上游失败，出现 `401` | 按照自己的计划轮换网关的提供商凭证；开发者密钥在网关处轮换，[`apiKeyHelper`](/docs/zh-CN/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 处理每个开发者的轮换，无需重新分发设置 |

289 289

290在调整每个密钥的速率限制时，考虑客户端[重试瞬时故障](/docs/zh-CN/errors#automatic-retries)，包括 `429` 响应，最多 10 次，带有退避，遵守 `Retry-After`。将[兼容性指南](/docs/zh-CN/llm-gateway-protocol)作为每个 Claude Code 版本发送的内容的参考。290在调整每个密钥的速率限制时，考虑客户端[重试瞬时故障](/docs/zh-CN/errors#automatic-retries)，包括 `429` 响应，最多 10 次，带有退避，遵守 `Retry-After`。将[兼容性指南](/docs/zh-CN/llm-gateway-protocol)作为每个 Claude Code 版本发送的内容的参考。

291 291

292<h3 id="plan-claude-code-version-upgrades">

293 规划 Claude Code 版本升级

294</h3>

295

296某些 Claude Code 行为内置于已安装的版本中，而不是在您的网关处设置，因此将开发者移至新版本可以改变整个部署中的行为，即使网关配置没有改变。要控制何时发生这种情况，请使用 [`requiredMaximumVersion`](/docs/zh-CN/settings-reference#requiredmaximumversion) 将开发者固定到已测试的版本，或者如果您通过自己的渠道分发 Claude Code，请使用 [`DISABLE_UPDATES`](/docs/zh-CN/setup#disable-auto-updates)。在提高固定版本之前，请阅读新版本的[更新日志](/docs/en/changelog)条目并[针对网关测试它](#test-claude-code-against-the-gateway)。

297

298当您测试一个版本时，网关拒绝的新标头或请求字段显示为[维护网关](#maintain-the-gateway)中描述的 `400` 错误。下表涵盖不产生错误的版本相关变化，以及保持每个变化在升级中保持不变的设置。

299

300| 区域 | 开发者升级时可能改变的内容 | 保持其不变的设置 |

301| :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

302| 功能标志默认值 | [不从 Anthropic 获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话，例如云提供商上的会话或关闭遥测的会话，使用内置于已安装版本中的标志默认值。当版本改变其中一个默认值时，这些开发者的行为在他们升级后立即改变 | 版本固定本身，`requiredMaximumVersion` 或 `DISABLE_UPDATES` |

303| 模型能力假设 | 已安装版本不识别的模型 ID，例如网关别名 `prod-opus`，对[自适应推理](/docs/zh-CN/model-config#adaptive-reasoning-and-fixed-thinking-budgets)、努力参数和[上下文窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)运行默认假设，直到更高版本识别该 ID 或您映射它 | 在网关处路由 Anthropic 模型 ID，或添加[`modelOverrides`](/docs/zh-CN/model-config#override-model-ids-per-version)条目，将 Anthropic 模型 ID 映射到您的别名。在云提供商连接上，您可以改为[声明固定模型的能力](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

304| 默认模型和别名 | 新会话默认启动的模型，以及别名（如 `opus` 和 `sonnet`）解析到的模型，[内置于每个版本](/docs/zh-CN/model-config#pin-models-for-third-party-deployments)中，开发者升级时可能改变 | [`ANTHROPIC_DEFAULT_MODEL`](/docs/zh-CN/model-config#set-a-default-model-for-new-sessions) 用于新会话启动的模型，以及 [`ANTHROPIC_DEFAULT_*_MODEL` 变量](/docs/zh-CN/model-config#environment-variables)，例如 `ANTHROPIC_DEFAULT_OPUS_MODEL`，用于每个别名解析到的内容。`ANTHROPIC_DEFAULT_MODEL` 需要 Claude Code v2.1.236 或更高版本 |

305

292<h2 id="related-resources">306<h2 id="related-resources">

293 相关资源307 相关资源

294</h2>308</h2>

managed-mcp.md +25 −11

Details

48 使用 managed-mcp.json 进行独占控制48 使用 managed-mcp.json 进行独占控制

49</h2>49</h2>

50 50

51如果你部署 `managed-mcp.json` 文件，Claude Code 仅加载该文件定义的服务器、你[通过 `managedMcpServers` 提供的服务器](#provide-servers-through-managed-settings)，以及启动会话的应用注册的任何进程内服务器，例如 VS Code 扩展自己的服务器或[桌面应用提供的连接器](/docs/zh-CN/mcp#how-connectors-reach-claude-code)。用户无法添加、修改或使用任何其他 MCP 服务器，包括插件提供的服务器和通过 [`--mcp-config` CLI 标志](/docs/zh-CN/cli-reference#cli-flags)传递的服务器。该文件还会抑制 Claude Code 自身获取的 claude.ai 连接器，除非你[允许它们与托管集合一起使用](#allow-claude-ai-connectors-alongside-the-managed-set)。51当你部署 `managed-mcp.json` 文件时，Claude Code 仅加载以下 MCP 服务器：

53* 该文件定义的服务器

54* 你[通过 `managedMcpServers` 提供的服务器](#provide-servers-through-managed-settings)

55* 启动会话的应用注册的进程内服务器，例如 VS Code 扩展自己的服务器或[桌面应用提供的连接器](/docs/zh-CN/mcp#how-connectors-reach-claude-code)

57用户无法添加、修改或使用任何其他 MCP 服务器，包括插件提供的服务器和通过 [`--mcp-config` CLI 标志](/docs/zh-CN/cli-reference#cli-flags)传递的服务器。该文件还会抑制 Claude Code 自身获取的 claude.ai 连接器，除非你[允许它们与托管集合一起使用](#allow-claude-ai-connectors-alongside-the-managed-set)。

52 58

53<h3 id="deploy-managed-mcp-json">59<h3 id="deploy-managed-mcp-json">

54 部署 managed-mcp.json60 部署 managed-mcp.json

108* 在工作站上，Claude Code 在启动时退出，显示 `You cannot dynamically configure MCP servers when an enterprise MCP config is present`。114* 在工作站上，Claude Code 在启动时退出，显示 `You cannot dynamically configure MCP servers when an enterprise MCP config is present`。

109* 在部署了该文件的主机上的[云会话](/docs/zh-CN/claude-code-on-the-web)中，例如[自托管运行器](/docs/zh-CN/self-hosted-environments-configuration#mcp-servers)，Claude Code 仅使用托管服务器启动，并跳过 claude.ai 连接器和云主机通过 `--mcp-config` 交付的其他服务器。会话中没有任何内容告诉用户哪些服务器被遗漏了。Claude Code 在其 stderr 上的警告中命名它们，自托管运行器在 `debug` 日志级别记录这些警告。115* 在部署了该文件的主机上的[云会话](/docs/zh-CN/claude-code-on-the-web)中，例如[自托管运行器](/docs/zh-CN/self-hosted-environments-configuration#mcp-servers)，Claude Code 仅使用托管服务器启动，并跳过 claude.ai 连接器和云主机通过 `--mcp-config` 交付的其他服务器。会话中没有任何内容告诉用户哪些服务器被遗漏了。Claude Code 在其 stderr 上的警告中命名它们，自托管运行器在 `debug` 日志级别记录这些警告。

110 116

111如果用户传递 `--strict-mcp-config`，Claude Code 在工作站和云会话中都会在启动时退出，因为该标志要求替换托管集合。117`--strict-mcp-config` 标志要求替换托管集合。如果用户在部署了这样的文件时传递它，Claude Code 在工作站和云会话中都会在启动时退出。

112 118

113<h3 id="how-allowlists-and-denylists-apply-to-the-managed-set">119<h3 id="how-allowlists-and-denylists-apply-to-the-managed-set">

114 允许列表和拒绝列表如何应用于托管集合120 允许列表和拒绝列表如何应用于托管集合

129 135

130要确认文件生效，请在托管机器上运行两项检查：136要确认文件生效，请在托管机器上运行两项检查：

131 137

1321. `claude mcp list` 仅显示 `managed-mcp.json` 中的服务器，加上你通过 `managedMcpServers` 提供的任何服务器。如果用户自己的服务器仍然出现，则文件未被读取；检查路径和权限。1381. `claude mcp list` 仅显示 `managed-mcp.json` 中的服务器，加上你通过 `managedMcpServers` 提供的任何服务器。两个其他结果意味着出现了问题：

139 * 如果用户自己的服务器仍然出现，Claude Code 未读取该文件，因此请检查其路径和父目录的权限。

140 * 如果文件的服务器未出现，且 `MCP config diagnostics` 部分将企业配置标记为无法解析，Claude Code 无法读取或解析该文件。修复该部分命名的错误，然后让用户重新启动 Claude Code。

1332. `claude mcp add --transport http test https://example.com/mcp` 失败，显示 `Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers`。URL 不需要是真实服务器，因为策略检查在联系任何内容之前拒绝该命令。1412. `claude mcp add --transport http test https://example.com/mcp` 失败，显示 `Cannot add MCP server: enterprise MCP configuration is active and has exclusive control over MCP servers`。URL 不需要是真实服务器，因为策略检查在联系任何内容之前拒绝该命令。

134 142

135<h3 id="disable-mcp-entirely">143<h3 id="disable-mcp-entirely">

267 275

268要将服务器部署给用户，请使用 [`managed-mcp.json`](#exclusive-control-with-managed-mcp-json) 或 [`managedMcpServers`](#provide-servers-through-managed-settings)。两个列表也过滤通过 [`--mcp-config` CLI 标志](/docs/zh-CN/cli-reference#cli-flags)传递的服务器，除了进程内 `type: "sdk"` 条目；`--strict-mcp-config` 限制哪些配置文件加载，不会绕过任一列表。276要将服务器部署给用户，请使用 [`managed-mcp.json`](#exclusive-control-with-managed-mcp-json) 或 [`managedMcpServers`](#provide-servers-through-managed-settings)。两个列表也过滤通过 [`--mcp-config` CLI 标志](/docs/zh-CN/cli-reference#cli-flags)传递的服务器，除了进程内 `type: "sdk"` 条目；`--strict-mcp-config` 限制哪些配置文件加载，不会绕过任一列表。

269 277

270要使允许列表具有权威性，请在[托管设置源](/docs/zh-CN/admin-setup#decide-how-settings-reach-devices)（如服务器托管设置或已部署的 `managed-settings.json` 文件）中同时设置 `allowedMcpServers` 和 `allowManagedMcpServersOnly: true`。[将允许列表限制为仅托管设置](#restrict-the-allowlist-to-managed-settings-only)显示配置。如果没有 `allowManagedMcpServersOnly`，来自每个设置范围的允许列表会合并，包括用户自己的 `~/.claude/settings.json`，因此用户可以扩展您的允许列表允许的内容。拒绝列表无论如何都会从每个范围合并。278要使允许列表具有权威性，请在[托管设置源](/docs/zh-CN/admin-setup#decide-how-settings-reach-devices)（如服务器托管设置或已部署的 `managed-settings.json` 文件）中同时设置 `allowedMcpServers` 和 `allowManagedMcpServersOnly: true`。

279

280该锁定从每个管理员控制的托管源应用，因此已部署文件中的锁定在同时使用不提及 MCP 的服务器托管设置时仍然适用。当锁定打开时，托管允许列表来自设置该列表的最高排名管理员源。跨源读取锁定和允许列表需要 Claude Code v2.1.273 或更高版本。

281

282[将允许列表限制为仅托管设置](#restrict-the-allowlist-to-managed-settings-only)显示配置。

283

284如果没有 `allowManagedMcpServersOnly`，来自每个设置范围的允许列表会合并，包括用户自己的 `~/.claude/settings.json`，因此用户可以扩展您的允许列表允许的内容。拒绝列表无论如何都会从每个范围合并。

271 285

272<Note>286<Note>

273 `allowManagedMcpServersOnly` 与 `allowManagedPermissionRulesOnly` 分开，后者锁定[权限规则](/docs/zh-CN/permissions#managed-settings)。设置该标志不会强制执行 MCP 允许列表。287 `allowManagedMcpServersOnly` 与 `allowManagedPermissionRulesOnly` 分开，后者锁定[权限规则](/docs/zh-CN/permissions#managed-settings)。设置该标志不会强制执行 MCP 允许列表。

311 325

312在加载服务器之前，包括来自 `managed-mcp.json` 的服务器，Claude Code 按顺序运行以下三个检查。当用户重新连接服务器或在 `/mcp` 中打开已禁用的服务器时，它会再次运行它们。进程内 `type: "sdk"` 服务器（[启动会话的应用程序注册](/docs/zh-CN/mcp#how-connectors-reach-claude-code)）跳过全部三个。326在加载服务器之前，包括来自 `managed-mcp.json` 的服务器，Claude Code 按顺序运行以下三个检查。当用户重新连接服务器或在 `/mcp` 中打开已禁用的服务器时，它会再次运行它们。进程内 `type: "sdk"` 服务器（[启动会话的应用程序注册](/docs/zh-CN/mcp#how-connectors-reach-claude-code)）跳过全部三个。

313 327

3141. **合并列表。** 来自每个设置范围的允许列表和拒绝列表条目合并为一个允许列表和一个拒绝列表，托管范围的列表来自 [Claude Code 应用的托管源或源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)。当 `allowManagedMcpServersOnly` 为 `true` 时，仅保留托管允许列表；拒绝列表始终从每个范围合并。3281. **合并列表。** 来自每个设置范围的允许列表和拒绝列表条目合并为一个允许列表和一个拒绝列表。当 `allowManagedMcpServersOnly` 为 `true` 时，仅保留托管允许列表；拒绝列表始终从每个范围合并。当存在多个托管源时，[从每个管理员源读取的键](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)说明其中哪些提供托管范围的列表。

3152. **检查拒绝列表。** 与任何拒绝列表条目匹配的服务器（按 URL、命令或名称）被阻止。没有任何东西可以覆盖拒绝列表匹配。3292. **检查拒绝列表。** 与任何拒绝列表条目匹配的服务器（按 URL、命令或名称）被阻止。没有任何东西可以覆盖拒绝列表匹配。

3163. **检查允许列表。** 如果 `allowedMcpServers` 未在任何地方设置，每个通过拒绝列表的服务器都会加载。如果已设置，服务器必须匹配的内容取决于其类型，如下表所示。3303. **检查允许列表。** 如果 `allowedMcpServers` 未在任何地方设置，每个通过拒绝列表的服务器都会加载。如果已设置，服务器必须匹配的内容取决于其类型，如下表所示。

317 331

505| 用户在来自 `managedMcpServers` 的服务器上运行 `claude mcp remove` | `MCP server "<name>" is provided by your organization (managed settings) and cannot be removed locally.` |519| 用户在来自 `managedMcpServers` 的服务器上运行 `claude mcp remove` | `MCP server "<name>" is provided by your organization (managed settings) and cannot be removed locally.` |

507| 服务器在会话运行时被阻止，用户选择**重新连接**或在 `/mcp` 中将其重新打开 | [`MCP server <name> is blocked by enterprise managed policy`](/docs/zh-CN/errors#mcp-server-is-blocked-by-enterprise-managed-policy) |521| 服务器在会话运行时被阻止，用户选择**重新连接**或在 `/mcp` 中将其重新打开 | [`MCP server <name> is blocked by enterprise managed policy`](/docs/zh-CN/errors#mcp-server-is-blocked-by-enterprise-managed-policy) |

508 522

509当服务器无声地消失时，用户无法获得策略是原因的信号，因此在推出新限制时，告诉受影响的用户哪些服务器被阻止。523当服务器无声地消失时，用户无法获得策略是原因的信号，因此在推出新限制时，告诉受影响的用户哪些服务器被阻止。

521本页面涵盖的每个文件和设置、它控制的内容以及如何交付它：535本页面涵盖的每个文件和设置、它控制的内容以及如何交付它：

522 536

523| 表面 | 控制的内容 | 位置 | 如何交付 |537| 表面 | 控制的内容 | 位置 | 如何交付 |

524| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- |538| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------ | :----------------------------------------------------------------------------------------------------------------------- |

527| `allowedMcpServers` | 允许的服务器允许列表 | 任何[设置范围](/docs/zh-CN/settings#where-settings-live)；Claude Code 合并来自每个范围的列表，除非设置了 `allowManagedMcpServersOnly`，并从它[选择](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)或[组合](/docs/zh-CN/managed-settings#compose-every-managed-source)的托管源中获取列表 | 为了强制执行，一个[托管设置源](/docs/zh-CN/admin-setup#decide-how-settings-reach-devices)：服务器管理的设置、`managed-settings.json`、MDM 配置文件或注册表 |541| `allowedMcpServers` | 允许的服务器允许列表 | 任何[设置范围](/docs/zh-CN/settings#where-settings-live)；[服务器如何被评估](#how-a-server-is-evaluated)说明来自多个范围和托管源的列表如何组合 | 为了强制执行，一个[托管设置源](/docs/zh-CN/admin-setup#decide-how-settings-reach-devices)：服务器管理的设置、`managed-settings.json`、MDM 配置文件或注册表 |

530| `allowAllClaudeAiMcps` | 加载 claude.ai 连接器，Claude Code 自身与 `managed-mcp.json` 一起获取。[在运行云会话的主机上的 `managed-mcp.json` 仍然会抑制该会话的连接器](#allow-claude-ai-connectors-alongside-the-managed-set) | 仅托管设置源；该设置在其他地方无效 | 与 `allowedMcpServers` 相同 |544| `allowAllClaudeAiMcps` | 加载 claude.ai 连接器，Claude Code 自身与 `managed-mcp.json` 一起获取。[在运行云会话的主机上的 `managed-mcp.json` 仍然会抑制该会话的连接器](#allow-claude-ai-connectors-alongside-the-managed-set) | 仅托管设置源；该设置在其他地方无效 | 与 `allowedMcpServers` 相同 |

531 545

532<h2 id="related-resources">546<h2 id="related-resources">

536* [决定要强制执行的内容](/docs/zh-CN/admin-setup#decide-what-to-enforce)：MCP 限制以及权限规则、沙箱和其他管理控制550* [决定要强制执行的内容](/docs/zh-CN/admin-setup#decide-what-to-enforce)：MCP 限制以及权限规则、沙箱和其他管理控制

537* [通过 MCP 将 Claude Code 连接到工具](/docs/zh-CN/mcp)：完整的 MCP 参考，包括传输、范围和身份验证551* [通过 MCP 将 Claude Code 连接到工具](/docs/zh-CN/mcp)：完整的 MCP 参考，包括传输、范围和身份验证

538* [设置](/docs/zh-CN/settings)：设置层次结构以及托管设置如何优先552* [设置](/docs/zh-CN/settings)：设置层次结构以及托管设置如何优先

539* [服务器管理的设置](/docs/zh-CN/server-managed-settings)：从 Claude.ai 管理控制台交付 `allowedMcpServers` 和 `deniedMcpServers`553* [服务器管理的设置](/docs/zh-CN/server-managed-settings)：从 claude.ai 管理控制台交付 `allowedMcpServers` 和 `deniedMcpServers`

540* [安全](/docs/zh-CN/security)：这些控制防御的威胁模型554* [安全](/docs/zh-CN/security)：这些控制防御的威胁模型

541* [Claude 企业管理员指南](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide)：SSO、SCIM、座位管理和推出剧本555* [Claude 企业管理员指南](https://claude.com/resources/tutorials/claude-enterprise-administrator-guide)：SSO、SCIM、座位管理和推出剧本

managed-settings.md +54 −43

Details

60上述步骤中的文件是将托管设置放到机器上的四种方式之一。每种机制都携带与 `settings.json` 文件相同的策略密钥，因此[设置参考](/docs/zh-CN/settings-reference)适用于所有这些。少数密钥与特定源相关联，每个条目的 Scope 行说明了哪些：60上述步骤中的文件是将托管设置放到机器上的四种方式之一。每种机制都携带与 `settings.json` 文件相同的策略密钥，因此[设置参考](/docs/zh-CN/settings-reference)适用于所有这些。少数密钥与特定源相关联，每个条目的 Scope 行说明了哪些：

61 61

62* **交付控制**：[`policyHelper`](/docs/zh-CN/settings-reference#policyhelper)、[`wslInheritsWindowsSettings`](/docs/zh-CN/settings-reference#wslinheritswindowssettings) 和 [`managedSourcesBehavior`](/docs/zh-CN/settings-reference#managedsourcesbehavior)62* **交付控制**：[`policyHelper`](/docs/zh-CN/settings-reference#policyhelper)、[`wslInheritsWindowsSettings`](/docs/zh-CN/settings-reference#wslinheritswindowssettings) 和 [`managedSourcesBehavior`](/docs/zh-CN/settings-reference#managedsourcesbehavior)

~~63* **网关登录密钥**：[`forceLoginGatewayUrl`](/docs/zh-CN/settings-reference#forcelogingatewayurl) 和 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 的 `"gateway"` 值~~63* **网关登录密钥**：[`forceLoginGatewayUrl`](/docs/zh-CN/settings-reference#forcelogingatewayurl)、[`gatewayInternalNetworks`](/docs/zh-CN/settings-reference#gatewayinternalnetworks) 和 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 的 `"gateway"` 值

64 64

65托管设置文件、MDM 配置文件或 claude.ai 控制台对其到达的每个人应用一个策略。要为一组开发者提供不同的策略，请将不同的文件或配置文件部署到该组；claude.ai 控制台[还不能针对一个组](/docs/zh-CN/server-managed-settings#current-limitations)，而自托管[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)按 IdP 组交付托管设置。65托管设置文件、MDM 配置文件或 claude.ai 控制台对其到达的每个人应用一个策略。要为一组开发者提供不同的策略，请将不同的文件或配置文件部署到该组；claude.ai 控制台[还不能针对一个组](/docs/zh-CN/server-managed-settings#current-limitations)，而自托管[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)按 IdP 组交付托管设置。

66 66

144当您的组织向同一台机器交付多个托管源时，[`managedSourcesBehavior`](/docs/zh-CN/settings-reference#managedsourcesbehavior) 键决定 Claude Code 对其他源的处理方式：144当您的组织向同一台机器交付多个托管源时，[`managedSourcesBehavior`](/docs/zh-CN/settings-reference#managedsourcesbehavior) 键决定 Claude Code 对其他源的处理方式：

145 145

146* **`"first-wins"`，默认值**：Claude Code 使用提供至少一个策略键的最高排名源，并忽略其余源，而不是合并它们，除了 [从每个管理员源读取的键](#keys-read-from-every-admin-source) 中的键。Claude Code 不会对跳过的源显示警告；`/status` [命名它使用的源和跳过的源](#read-the-source-in-/status)。146* **`"first-wins"`，默认值**：Claude Code 使用提供至少一个策略键的最高排名源，并忽略其余源，而不是合并它们，除了 [从每个管理员源读取的键](#keys-read-from-every-admin-source) 中的键。Claude Code 不会对跳过的源显示警告；`/status` [命名它使用的源和跳过的源](#read-the-source-in-/status)。

147* **`"merge"`**：Claude Code 应用提供策略键的每个管理员源，并按键的类型组合它们：在大多数键上，较高排名源的值适用，列表合并，锁定采用最严格的值。[组合每个托管源](#compose-every-managed-source) 说明在哪里设置键以及每种键的组合方式。需要 Claude Code v2.1.242 或更高版本。147* **`"merge"`**：Claude Code 应用每个提供策略键的管理员源，并按键的类型组合它们：在大多数键上，较高排名源的值适用，列表合并，锁采用最严格的值。[组合每个托管源](#compose-every-managed-source) 说明在哪里设置键以及每种键的组合方式。需要 Claude Code v2.1.242 或更高版本。

148 148

149两种设置以相同的方式对源进行排名。本节中重复出现两个术语：149两种设置以相同的方式对源进行排名。这些术语在本节中重复出现：

150 150

151* **策略键**：除了两个控制键 [`wslInheritsWindowsSettings`](/docs/zh-CN/settings-reference#wslinheritswindowssettings) 和 [`managedSourcesBehavior`](/docs/zh-CN/settings-reference#managedsourcesbehavior) 之外的任何设置键。仅包含这两个键的托管设置文件或 MDM 策略不计数，Claude Code 会继续查看下一个源。151* **策略键**：除了两个控制键 [`wslInheritsWindowsSettings`](/docs/zh-CN/settings-reference#wslinheritswindowssettings) 和 [`managedSourcesBehavior`](/docs/zh-CN/settings-reference#managedsourcesbehavior) 之外的任何设置键。仅包含这些键的托管设置文件或 MDM 策略不计数，Claude Code 会移至下一个源。

152* **管理员源**：下面前三个源之一。HKCU 注册表是用户可写的，不是管理员源。152* **管理员源**：下面前三个源之一。HKCU 注册表是用户可写的，不是管理员源。

153 153

154Claude Code 按此顺序检查源，优先级最高的在前：154Claude Code 按此顺序检查源，优先级最高的优先：

155 155

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 以外的地方时，它从下一个源开始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 以外的地方时，它从下一个源开始

1572. MDM 或操作系统级策略：macOS plist 或 HKLM 注册表键1572. MDM 或操作系统级策略：macOS plist 或 HKLM 注册表键

1583. 托管设置文件，`managed-settings.d/*.json` 和 `managed-settings.json` 合并在一起1583. 托管设置文件，`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) 提供限制性键时才读取它1594. HKCU 注册表，在 Windows 上，以及在 WSL 上一旦 HKLM 注册表或 Windows 托管设置文件打开 [`wslInheritsWindowsSettings`](/docs/zh-CN/settings-reference#wslinheritswindowssettings) 并且 HKCU 值也设置它时。Claude Code 仅在上面没有源提供策略键且没有 [主机提供的父设置](#let-an-embedding-host-add-policy) 提供限制性键时才读取它

160 160

161此图显示排名，以及 Claude Code 在任一设置下从前三个源读取的跨源键的示例：161此图显示排名，以及 Claude Code 在任一设置下从前三个源读取的跨源键的示例：

162 162

163<img src="https://mintcdn.com/claude-code/zuWID2B-Rxm8DEC8/images/managed-source-precedence.svg?fit=max&auto=format&n=zuWID2B-Rxm8DEC8&q=85&s=53f6be49f06eff48e01422c8ae1bc2e6" className="dark:hidden" alt="Diagram showing the four managed settings sources ranked from remote settings at the top through MDM, managed settings files, and the HKCU registry at the bottom. By default the first source with a policy key supplies the policy and the rest are skipped; with managedSourcesBehavior set to merge, every admin source with a policy key contributes, combined by kind of key, and the HKCU registry stays out. A side panel shows that cross-source keys such as the sandbox locks, forceRemoteSettingsRefresh, and the per-variable env merge are read from every admin source, which excludes the HKCU registry." width="680" height="330" data-path="images/managed-source-precedence.svg" />163<img src="https://mintcdn.com/claude-code/zuWID2B-Rxm8DEC8/images/managed-source-precedence.svg?fit=max&auto=format&n=zuWID2B-Rxm8DEC8&q=85&s=53f6be49f06eff48e01422c8ae1bc2e6" className="dark:hidden" alt="显示四个托管设置源的图表，从顶部的远程设置到 MDM、托管设置文件和底部的 HKCU 注册表。默认情况下，具有策略键的第一个源提供策略，其余的被跳过；当 managedSourcesBehavior 设置为 merge 时，每个具有策略键的管理员源都会贡献，按键的类型组合，HKCU 注册表保持不变。侧面板显示跨源键（如沙箱锁、forceRemoteSettingsRefresh 和每个变量的 env 合并）从每个管理员源读取，不包括 HKCU 注册表。" width="680" height="330" data-path="images/managed-source-precedence.svg" />

164 164

165<img src="https://mintcdn.com/claude-code/zuWID2B-Rxm8DEC8/images/managed-source-precedence-dark.svg?fit=max&auto=format&n=zuWID2B-Rxm8DEC8&q=85&s=ae407a9a08a3d680e80cf1a2af845d71" className="hidden dark:block" alt="Diagram showing the four managed settings sources ranked from remote settings at the top through MDM, managed settings files, and the HKCU registry at the bottom. By default the first source with a policy key supplies the policy and the rest are skipped; with managedSourcesBehavior set to merge, every admin source with a policy key contributes, combined by kind of key, and the HKCU registry stays out. A side panel shows that cross-source keys such as the sandbox locks, forceRemoteSettingsRefresh, and the per-variable env merge are read from every admin source, which excludes the HKCU registry." width="680" height="330" data-path="images/managed-source-precedence-dark.svg" />165<img src="https://mintcdn.com/claude-code/zuWID2B-Rxm8DEC8/images/managed-source-precedence-dark.svg?fit=max&auto=format&n=zuWID2B-Rxm8DEC8&q=85&s=ae407a9a08a3d680e80cf1a2af845d71" className="hidden dark:block" alt="显示四个托管设置源的图表，从顶部的远程设置到 MDM、托管设置文件和底部的 HKCU 注册表。默认情况下，具有策略键的第一个源提供策略，其余的被跳过；当 managedSourcesBehavior 设置为 merge 时，每个具有策略键的管理员源都会贡献，按键的类型组合，HKCU 注册表保持不变。侧面板显示跨源键（如沙箱锁、forceRemoteSettingsRefresh 和每个变量的 env 合并）从每个管理员源读取，不包括 HKCU 注册表。" width="680" height="330" data-path="images/managed-source-precedence-dark.svg" />

166 166

167<h3 id="keys-read-from-every-admin-source">167<h3 id="keys-read-from-every-admin-source">

168 从每个管理员源读取的键168 从每个管理员源读取的键

170 170

171在默认的 `"first-wins"` 设置下，Claude Code 仅从 [它选择的源](#how-claude-code-combines-managed-sources) 读取大多数键，即使选定的源未设置该键，也会忽略较低排名源中的值。171在默认的 `"first-wins"` 设置下，Claude Code 仅从 [它选择的源](#how-claude-code-combines-managed-sources) 读取大多数键，即使选定的源未设置该键，也会忽略较低排名源中的值。

172 172

173少数几个键的工作方式不同。Claude Code 从每个管理员源读取它们，因此当选定的源未设置它们时，较低排名的 MDM 策略或托管设置文件仍然可以设置它们。Claude Code 将用户可写的 HKCU 注册表排除在该扫描之外；当 HKCU 是唯一的源且没有主机提供父设置时，HKCU 的应用方式与任何选定的源相同。173少数键的工作方式不同。Claude Code 从每个管理员源读取它们，因此当选定的源不设置时，较低排名的 MDM 策略或托管设置文件仍然可以设置它们。Claude Code 将用户可写的 HKCU 注册表排除在该扫描之外；当 HKCU 是唯一的源且没有主机提供父设置时，HKCU 的应用方式与任何选定的源相同。

174 174

175跨源键包括：175跨源键包括：

176 176

177* `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly`：任何管理员源中的 `true` 都会打开锁定。当锁定打开时，Claude Code 会合并它锁定的允许列表，`sandbox.network.allowedDomains` 与 `WebFetch(domain:...)` 允许规则，或 `sandbox.filesystem.allowRead`，跨越每个管理员源。没有锁定时，Claude Code 将允许列表视为任何其他键，因此在 `"first-wins"` 下，未选定的管理员源的允许列表被忽略177* `sandbox.network.allowManagedDomainsOnly` 和 `sandbox.filesystem.allowManagedReadPathsOnly`：任何管理员源中的 `true` 都会打开锁。当锁打开时，Claude Code 会合并它锁定的允许列表，`sandbox.network.allowedDomains` 与 `WebFetch(domain:...)` 允许规则，或 `sandbox.filesystem.allowRead`，跨每个管理员源。没有锁时，Claude Code 将允许列表视为任何其他键，因此在 `"first-wins"` 下，未选定的管理员源的允许列表被忽略

178* `allowAllClaudeAiMcps`178* `allowAllClaudeAiMcps`

179* `allowManagedMcpServersOnly`：任何管理员源中的 `true` 都会打开 MCP 允许列表锁。当锁打开时，托管的 `allowedMcpServers` 列表来自设置一个的最高排名管理员源。服务器管理的列表替换较低源的列表，而不是与其组合。

180

181 如果没有管理员源设置列表，每个通过拒绝列表的服务器都会加载，除非 [父设置](#let-an-embedding-host-add-policy) 提供列表。

182

183 没有锁时，Claude Code 从它应用的托管源读取 `allowedMcpServers`，因此在 `"first-wins"` 下，未选定的管理员源的列表被忽略。需要 Claude Code v2.1.273 或更高版本

184* `deniedMcpServers` 和 [`disableClaudeAiConnectors`](/docs/zh-CN/settings-reference#disableclaudeaiconnectors)：任何管理员源中的条目或 `true` 都会应用。需要 Claude Code v2.1.273 或更高版本

179* 沙箱二进制路径 `sandbox.bwrapPath` 和 `sandbox.socatPath`185* 沙箱二进制路径 `sandbox.bwrapPath` 和 `sandbox.socatPath`

180* 沙箱 `ripgrep` 二进制文件，[`sandbox.ripgrep`](/docs/zh-CN/settings-reference#sandbox-ripgrep)186* 沙箱 `ripgrep` 二进制文件，[`sandbox.ripgrep`](/docs/zh-CN/settings-reference#sandbox-ripgrep)

181* `sandbox.filesystem.disabled` 和 `sandbox.network.strictAllowlist`187* `sandbox.filesystem.disabled` 和 `sandbox.network.strictAllowlist`

182* [`useAutoModeDuringPlan`](/docs/zh-CN/settings-reference#useautomodeduringplan) 和 [`syncClaudeAiSkills`](/docs/zh-CN/settings-reference#syncclaudeaiskills)，其中任何管理员源中的 `false` 都会关闭该行为。开发者的用户或本地设置中的 `false` 也会关闭它；每个键只能拒绝188* [`useAutoModeDuringPlan`](/docs/zh-CN/settings-reference#useautomodeduringplan)、[`syncClaudeAiSkills`](/docs/zh-CN/settings-reference#syncclaudeaiskills) 和 [`syncClaudeAiPlugins`](/docs/zh-CN/settings-reference#syncclaudeaiplugins)，其中任何管理员源的 `false` 都会关闭该行为。开发人员的用户或本地设置中的 `false` 也会关闭它；每个键只能拒绝

183* [`enableArtifact`](/docs/zh-CN/settings-reference#enableartifact)，其中任何管理员源中的 `false` 都会关闭 [Artifact 工具](/docs/zh-CN/artifacts)。开发者的用户、项目或本地设置中的 `false` 也会关闭它，没有源可以将其打开；请参阅 [哪些较低级别的值仍然计数](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence)。需要 Claude Code v2.1.242 或更高版本189* [`enableArtifact`](/docs/zh-CN/settings-reference#enableartifact)，其中任何管理员源的 `false` 都会关闭 [Artifact 工具](/docs/zh-CN/artifacts)。开发人员的用户、项目或本地设置中的 `false` 也会关闭它，没有源会将其打开；请参阅 [哪些较低级别的值仍然计数](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence)。需要 Claude Code v2.1.242 或更高版本

184* [`maxEffortLevel`](/docs/zh-CN/settings-reference#maxeffortlevel)，其中任何管理员源中的最低上限适用。如果开发者在自己的设置或使用 `--settings` 中设置了更低的上限，Claude Code 会应用那个；没有源可以提高上限。需要 Claude Code v2.1.267 或更高版本190* [`maxEffortLevel`](/docs/zh-CN/settings-reference#maxeffortlevel)，其中任何管理员源中的最低上限适用。如果开发人员在自己的设置或使用 `--settings` 中设置了较低的上限，Claude Code 会应用该上限；没有源可以提高上限。需要 Claude Code v2.1.267 或更高版本

185* 来自任何层级的 `attribution` 中的提交预告片选择退出，或在已弃用的 `includeCoAuthoredBy` 中191* `attribution` 中的提交预告片选择退出，或在已弃用的 `includeCoAuthoredBy` 中，来自任何层级

186* [`forceRemoteSettingsRefresh`](/docs/zh-CN/server-managed-settings)192* [`forceRemoteSettingsRefresh`](/docs/zh-CN/server-managed-settings)

187* `env`，跨管理员源按变量合并：每个变量来自定义它的最高优先级源，因此较低源填充较高源未设置的变量。少数几个变量遵循自己的规则；[跨托管源的按键异常](/docs/zh-CN/server-managed-settings#per-key-exceptions-across-managed-sources) 命名每一个。需要 Claude Code v2.1.223 或更高版本。在 v2.1.223 之前，Claude Code 仅应用选定源的整个 `env` 块193* `env`，跨管理员源按变量合并：每个变量来自定义它的最高优先级源，因此较低源填充较高源未设置的变量。少数变量遵循自己的规则；[跨托管源的每个键异常](/docs/zh-CN/server-managed-settings#per-key-exceptions-across-managed-sources) 命名每一个。需要 Claude Code v2.1.223 或更高版本。在 v2.1.223 之前，Claude Code 仅应用选定源的整个 `env` 块

188 194

189[网关登录键](#choose-a-delivery-mechanism)，[`forceLoginGatewayUrl`](/docs/zh-CN/settings-reference#forcelogingatewayurl) 和 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 的 `"gateway"` 值，遵循单独的规则。Claude Code 从不从服务器管理的设置读取它们，因此当服务器管理的设置是选定的源时，机器上排名最高的包含策略键的管理员源仍然提供它们。排名低于该源的管理员源中的值，或 HKCU 注册表中的值，被忽略。195[网关登录键](#choose-a-delivery-mechanism) 遵循单独的规则。Claude Code 从不从服务器管理的设置读取它们，因此当服务器管理的设置是选定的源时，机器上排名最高的具有策略键的管理员源仍然提供它们。排名低于该源的管理员源中的值，或 HKCU 注册表中的值，被忽略。

196

197当管理员源设置 `allowManagedMcpServersOnly` 或 `allowedMcpServers` 列表且该值不是生效的值时，`/status` 和 `claude doctor` 命名该源和键。

190 198

191<h3 id="compose-every-managed-source">199<h3 id="compose-every-managed-source">

192 组合每个托管源200 组合每个托管源

193</h3>201</h3>

194 202

195要让 Claude Code 应用您的组织交付的每个管理员源，请在您部署的最高排名源中将 [`managedSourcesBehavior`](/docs/zh-CN/settings-reference#managedsourcesbehavior) 设置为 `"merge"`。Claude Code 仅从包含该键或策略键的最高排名源读取该键，因此较低源无法选择自己与上面的源合并，并且从不接收服务器管理设置的机器也需要在其 MDM 配置文件中有该键。用户可写的 HKCU 注册表从不与另一个源合并。需要 Claude Code v2.1.242 或更高版本。203要让 Claude Code 应用您的组织交付的每个管理员源，请在您部署的最高排名源中将 [`managedSourcesBehavior`](/docs/zh-CN/settings-reference#managedsourcesbehavior) 设置为 `"merge"`。Claude Code 仅从具有该键或策略键的最高排名源读取该键，因此较低源无法选择自己与上面的源合并，从不接收服务器管理设置的机器也需要在其 MDM 配置文件中有该键。用户可写的 HKCU 注册表永远不会与另一个源合并。需要 Claude Code v2.1.242 或更高版本。

196 204

197在 `"merge"` 下，Claude Code 添加较低源的列表条目，例如 `permissions.allow` 规则和 hooks，到策略中，因此仅在排名低于最高源的每个源都在管理员的控制下时才打开它。205在 `"merge"` 下，Claude Code 添加较低源的列表条目，如 `permissions.allow` 规则和 hooks，到策略中，因此仅当排名低于最高源的每个源都在管理员的控制下时才打开它。

198 206

199此表显示 Claude Code 在 `"merge"` 下如何组合每种键。[`managedSourcesBehavior` 条目](/docs/zh-CN/settings-reference#managedsourcesbehavior) 在三行中命名每个键：限制允许列表、整体取值的值和仅从最高排名源读取的键。207此表显示 Claude Code 在 `"merge"` 下如何组合每种键。[`managedSourcesBehavior` 条目](/docs/zh-CN/settings-reference#managedsourcesbehavior) 命名三行中的每个键：限制允许列表、整体取值和仅从最高排名源读取的键。

200 208

201| 键的类型 | Claude Code 如何组合它 | 示例 |209| 键的类型 | Claude Code 如何组合它 | 示例 |

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

203| 列表 | 组合来自每个源的条目 | `permissions.allow`、`hooks`、`sandbox.network.allowedDomains`、`deniedMcpServers` |211| 列表 | 组合来自每个源的条目 | `permissions.allow`、`hooks`、`sandbox.network.allowedDomains`、`deniedMcpServers` |

204| 锁定 | 应用任何源设置的最严格值；较宽松的值仅从最高排名源适用 | `allowManagedHooksOnly`、`permissions.disableBypassPermissionsMode`、`crossSessionInbound` |212| 锁 | 应用任何源设置的最严格值；较宽松的值仅从最高排名源适用 | `allowManagedHooksOnly`、`permissions.disableBypassPermissionsMode`、`crossSessionInbound` |

209| `env` | 在任一设置下跨管理员源按变量合并，如 [从每个管理员源读取的键](#keys-read-from-every-admin-source) 所述 | |217| `env` | 在任一设置下跨管理员源按变量合并，如 [从每个管理员源读取的键](#keys-read-from-every-admin-source) 所述 | |

211 219

217 225

218[`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 是您的 MDM 策略或托管设置文件命名的可执行文件，Claude Code 在启动时运行它来计算托管设置。当选定的源配置一个并且辅助程序发出 `managedSettings` 对象时，该输出改变 Claude Code 读取的内容：226[`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 是您的 MDM 策略或托管设置文件命名的可执行文件，Claude Code 在启动时运行它来计算托管设置。当选定的源配置一个并且辅助程序发出 `managedSettings` 对象时，该输出改变 Claude Code 读取的内容：

219 227

220* **发出的 `managedSettings` 对象是会话的唯一托管设置**，包括对于 [它以其他方式从每个管理员源读取的键](#keys-read-from-every-admin-source)，除了 [`forceRemoteSettingsRefresh`，它有自己的启动规则](/docs/zh-CN/settings-reference#forceremotesettingsrefresh)228* **发出的 `managedSettings` 对象是会话的唯一托管设置**，包括对于 [它否则从每个管理员源读取的键](#keys-read-from-every-admin-source)，除了 [`forceRemoteSettingsRefresh`，它有自己的启动规则](/docs/zh-CN/settings-reference#forceremotesettingsrefresh)

221 229

222对于辅助程序运行失败的情况，以及当一个失败时 Claude Code 的处理方式，请参阅 [辅助程序失败](/docs/zh-CN/settings-reference#helper-failures)。230对于哪些辅助程序运行失败，以及当一个失败时 Claude Code 做什么，请参阅 [辅助程序失败](/docs/zh-CN/settings-reference#helper-failures)。

223 231

224<span id="parent-settings-from-embedding-hosts" />232<span id="parent-settings-from-embedding-hosts" />

225 233

231 让嵌入主机添加策略239 让嵌入主机添加策略

232</h3>240</h3>

233 241

234当另一个应用程序启动 Claude Code 时，例如 Claude Desktop、IDE 扩展或 Agent SDK 应用，该主机可以通过 SDK `managedSettings` 选项传递自己的托管设置。Claude Code 将这些称为父设置。242当另一个应用程序启动 Claude Code 时，如 Claude Desktop、IDE 扩展或 Agent SDK 应用，该主机可以通过 SDK `managedSettings` 选项传递自己的托管设置。Claude Code 将这些称为父设置。

235 243

236默认情况下，当存在管理员源时，Claude Code 忽略父设置：服务器管理的设置、MDM 或操作系统级策略，或托管设置文件。244默认情况下，只要存在管理员源，Claude Code 就会忽略父设置：服务器管理的设置、MDM 或操作系统级策略，或托管设置文件。

237 245

238要让 Claude Code 将父设置与管理员源合并，请在最高优先级托管源中将 [`parentSettingsBehavior`](/docs/zh-CN/settings-reference#parentsettingsbehavior) 设置为 `"merge"`；Claude Code 仅从该源读取该键。246要让 Claude Code 将父设置与管理员源合并，请在最高优先级托管源中将 [`parentSettingsBehavior`](/docs/zh-CN/settings-reference#parentsettingsbehavior) 设置为 `"merge"`；Claude Code 仅从该源读取该键。

239 247

240Claude Code 然后仅保留主机的限制 Claude 可以做什么的值，有一个需要了解的间隙：除非您也设置 `allowManaged*Only` 锁定，主机的权限允许规则和沙箱允许列表仍然适用。请参阅 [限制父设置](/docs/zh-CN/claude-apps-gateway#restrict-parent-settings) 以了解锁定。248Claude Code 然后仅保留主机的限制 Claude 可以做什么的值，有一个需要了解的间隙：除非您也设置 `allowManaged*Only` 锁，主机的权限允许规则和沙箱允许列表仍然适用。请参阅 [限制父设置](/docs/zh-CN/claude-apps-gateway#restrict-parent-settings) 以了解锁。

241 249

242[`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 可以独立于此键关闭父合并；其条目说明何时。250[`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 可以独立于此键关闭父合并；其条目说明何时。

243 251

244Claude Code 也对父提供的值本身应用这些检查：252Claude Code 也对父提供的值本身应用这些检查：

245 253

246* 当任何管理员源设置 `allowManagedPermissionRulesOnly` 时，Claude Code 在读取时删除 [父提供的](/docs/zh-CN/claude-apps-gateway#restrict-parent-settings) 权限允许规则和 `additionalDirectories`，即使较高优先级源未设置该键。该键对您自己的权限规则的影响来自 Claude Code 应用的托管设置，或来自您选择合并的父设置254* 当任何管理员源设置 `allowManagedPermissionRulesOnly` 时，Claude Code 会删除 [父提供的](/docs/zh-CN/claude-apps-gateway#restrict-parent-settings) 权限允许规则和 `additionalDirectories`，即使较高优先级源未设置该键。该键对您自己的权限规则的影响来自 Claude Code 应用的托管设置，或来自您选择合并的父设置

247* Claude Code 强制执行它应用的托管设置中的 `forceLoginOrgUUID` 或 `allowedMcpServers` 值，并阻止父提供的值。Claude Code 不应用的较低管理员源中的值既不应用也不阻止父的值。[`managedSourcesBehavior`](/docs/zh-CN/settings-reference#managedsourcesbehavior) 条目说明在 `"merge"` 下哪个源提供每个键。在 v2.1.223 之前，任何管理员源中的值都会阻止父的值255* Claude Code 强制执行它应用的托管设置中的 `forceLoginOrgUUID` 或 `allowedMcpServers` 值，并阻止父提供的值。Claude Code 不应用的较低管理员源中的值既不应用也不阻止父的值。在 MCP 允许列表锁之外，Claude Code 不应用的较低管理员源中的值既不应用也不阻止父的值。

248* `availableModels` 值遵循与 `allowedMcpServers` 相同的规则256

257 在 Claude Code v2.1.273 或更高版本上，当 `allowManagedMcpServersOnly` 打开时，来自设置一个的最高排名管理员源的 `allowedMcpServers` 列表应用并阻止父的，作为 [跨源键](#keys-read-from-every-admin-source)。父的列表仅在没有管理员源设置一个时应用。[`managedSourcesBehavior`](/docs/zh-CN/settings-reference#managedsourcesbehavior) 条目说明在 `"merge"` 下哪个源提供每个键。在 v2.1.223 之前，任何管理员源中的值都会阻止父的值

258* 对于 `availableModels`，Claude Code 强制执行它应用的托管设置中的值并阻止父提供的列表

249 259

250<h4 id="keep-cowork-folder-access-when-only-managed-rules-apply">260<h4 id="keep-cowork-folder-access-when-only-managed-rules-apply">

251 当仅应用托管规则时保持 Cowork 文件夹访问261 当仅应用托管规则时保持 Cowork 文件夹访问

252</h4>262</h4>

253 263

254Claude Desktop 应用中的 [Cowork](https://claude.com/docs/cowork/overview) 在 Claude Code 上运行其会话，并通过在启动会话时提供的允许规则授予每个会话对其工作文件夹（例如用户连接的文件夹）的访问权限。当您的托管策略设置 [`allowManagedPermissionRulesOnly`](/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly) 时，Claude Code 仅保留托管策略中的允许规则：它删除主机作为父设置、`--allowedTools` 或在设置文件中提供的允许规则，因此对这些文件夹的写入失去其预先批准。在要求编辑前提示的 Cowork 会话中，Cowork 无法显示提示，Claude 将每次写入报告为被阻止，因为路径解析为受保护的位置或连接文件夹外的路径。264Claude Desktop 应用中的 [Cowork](https://claude.com/docs/cowork/overview) 在 Claude Code 上运行其会话，并通过它在启动会话时提供的允许规则授予每个会话对其工作文件夹（如用户连接的文件夹）的访问权限。当您的托管策略设置 [`allowManagedPermissionRulesOnly`](/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly) 时，Claude Code 仅保留托管策略中的允许规则：它删除主机作为父设置、`--allowedTools` 或设置文件中提供的允许规则，因此对这些文件夹的写入失去其预先批准。在要求编辑前提示的 Cowork 会话中，Cowork 无法显示提示，Claude 将每次写入报告为被阻止，因为路径解析为受保护的位置或连接文件夹外的路径。

255 265

256要恢复写入，请为这些文件夹添加允许规则到 Claude Code [选择](#precedence-within-the-managed-tier) 的托管源在这些机器上：在 MDM 管理的队列上，那是 MDM 策略而不是单独的托管设置文件。此示例使用文件形式，MDM 策略采用相同的键。它保持 `allowManagedPermissionRulesOnly` 设置并允许在每个用户主目录中的 `CoworkProjects` 文件夹下编辑；将路径替换为您的用户连接的文件夹：266要恢复写入，请为这些文件夹添加允许规则到 Claude Code [选择](#precedence-within-the-managed-tier) 的托管源在这些机器上：在 MDM 管理的队列上，那是 MDM 策略而不是单独的托管设置文件。此示例使用文件形式，MDM 策略采用相同的键。它保持 `allowManagedPermissionRulesOnly` 设置并允许在每个用户主目录中的 `CoworkProjects` 文件夹下编辑；用您的用户连接的文件夹替换路径：

257 267

258```json managed-settings.json theme={null}268```json managed-settings.json theme={null}

259{269{

266}276}

267```277```

268 278

269部署策略后，Claude 可以在新 Cowork 会话中的该文件夹下保存文件。[读取和编辑规则](/docs/zh-CN/permissions#read-and-edit) 涵盖路径语法，包括绝对路径的 `//` 形式。279部署策略后，Claude 可以在新 Cowork 会话中的该文件夹下保存文件。[读和编辑规则](/docs/zh-CN/permissions#read-and-edit) 涵盖路径语法，包括绝对路径的 `//` 形式。

270 280

271<h3 id="what-a-developer-can-change">281<h3 id="what-a-developer-can-change">

272 开发者可以更改什么282 开发人员可以更改什么

273</h3>283</h3>

274 284

275开发者自己的设置文件、`--settings` 值和项目文件从不覆盖托管值；[异常](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence) 仅允许更严格的较低级别值计数。四件事在该规则之外：285开发人员自己的设置文件、`--settings` 值和项目文件永远不会覆盖托管值；[异常](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence) 仅让更严格的较低级别值计数。这些情况在该规则之外：

276 286

277* **会话的模型**：托管的 `model` 是默认值，不是锁定。`--model` 和 `ANTHROPIC_MODEL` 仍然为该会话选择模型，因此部署 [`availableModels`](/docs/zh-CN/settings-reference#availablemodels) 来限制选择。287* **会话的模型**：托管的 `model` 是默认值，不是锁。`--model` 和 `ANTHROPIC_MODEL` 仍然为该会话选择模型，因此部署 [`availableModels`](/docs/zh-CN/settings-reference#availablemodels) 来限制选择。

278* **本地管理员权限**：作为机器上管理员的开发者可以编辑托管源本身，这就是为什么 MDM 工具可以按计划重新部署配置文件或文件，以及为什么 HKLM 注册表和 macOS 托管首选项域存在。288* **本地管理员权限**：作为机器上的管理员的开发人员可以编辑托管源本身，这就是为什么 MDM 工具可以按计划重新部署配置文件或文件，以及为什么 HKLM 注册表和 macOS 托管首选项域存在。

279* **服务器管理的缓存**：服务器管理的设置来自 Anthropic 的服务器，对本地缓存的编辑 [仅持续到下一次成功获取](/docs/zh-CN/server-managed-settings#security-considerations)。289* **服务器管理的缓存**：服务器管理的设置来自 Anthropic 的服务器，对本地缓存的编辑 [仅持续到下一次成功获取](/docs/zh-CN/server-managed-settings#security-considerations)。

280* **其他工具**：托管设置仅绑定 Claude Code。从另一个工具调用 API 的开发者不在它们下。290* **其他工具**：托管设置仅绑定 Claude Code。从另一个工具调用 API 的开发人员不在它们下。

281 291

282<span id="verify-enforcement" />292<span id="verify-enforcement" />

283 293

375| `gatewayInternalNetworks` | 当无效值来自机器上最高的托管源时，`/login` 拒绝该机器上的每个新[云网关](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)登录，直到修复该值。 |

365| `crossSessionInbound` | 视为 `refuse`，最严格的值，因此入站[跨会话消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)被拒绝，直到修复该值。开发人员看到[警告](/docs/zh-CN/errors#crosssessioninbound-must-be-one-of-accept-hold-refuse)。 |376| `crossSessionInbound` | 视为 `refuse`，最严格的值，因此入站[跨会话消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)被拒绝，直到修复该值。开发人员看到[警告](/docs/zh-CN/errors#crosssessioninbound-must-be-one-of-accept-hold-refuse)。 |

367| `sandbox.credentials` | 可恢复的无效条目降级为 `mode: "deny"` 并带有警告；不可恢复的条目被剥离；有效条目保持强制执行。请参阅[托管设置中的无效凭据条目](/docs/zh-CN/settings-reference#invalid-credential-entries-in-managed-settings) |378| `sandbox.credentials` | 可恢复的无效条目降级为 `mode: "deny"` 并带有警告；不可恢复的条目被剥离；有效条目保持强制执行。请参阅[托管设置中的无效凭据条目](/docs/zh-CN/settings-reference#invalid-credential-entries-in-managed-settings) |

388| :----------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |399| :----------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

389| [`allowAllClaudeAiMcps`](/docs/zh-CN/settings-reference#allowallclaudeaimcps) | 加载 Claude Code 自己获取的 claude.ai 连接器，与部署的 `managed-mcp.json` 一起，而不是抑制它们 |400| [`allowAllClaudeAiMcps`](/docs/zh-CN/settings-reference#allowallclaudeaimcps) | 加载 Claude Code 自己获取的 claude.ai 连接器，与部署的 `managed-mcp.json` 一起，而不是抑制它们 |

390| [`allowedChannelPlugins`](/docs/zh-CN/settings-reference#allowedchannelplugins) | 可能推送消息的通道插件的允许列表。设置时替换默认 Anthropic 允许列表。需要 `channelsEnabled: true`。请参阅[限制哪些通道插件可以运行](/docs/zh-CN/channels#restrict-which-channel-plugins-can-run) |401| [`allowedChannelPlugins`](/docs/zh-CN/settings-reference#allowedchannelplugins) | 可能推送消息的通道插件的允许列表。设置时替换默认 Anthropic 允许列表。需要 `channelsEnabled: true`。请参阅[限制哪些通道插件可以运行](/docs/zh-CN/channels#restrict-which-channel-plugins-can-run) |

391| [`allowManagedHooksOnly`](/docs/zh-CN/settings-reference#allowmanagedhooksonly) | 当 `true` 时，限制哪些钩子运行；请参阅[在 `allowManagedHooksOnly` 下运行什么](/docs/zh-CN/settings-reference#what-runs-under-allowmanagedhooksonly)以获取完整效果列表 |402| [`allowManagedHooksOnly`](/docs/zh-CN/settings-reference#allowmanagedhooksonly) | 当 `true` 时，限制哪些 hooks 运行；请参阅[在 `allowManagedHooksOnly` 下运行什么](/docs/zh-CN/settings-reference#what-runs-under-allowmanagedhooksonly)以获取完整效果列表 |

392| [`allowManagedMcpServersOnly`](/docs/zh-CN/settings-reference#allowmanagedmcpserversonly) | 当 `true` 时，仅尊重来自托管设置的 `allowedMcpServers`。`deniedMcpServers` 仍然从所有源合并。请参阅[托管 MCP 配置](/docs/zh-CN/managed-mcp) |403| [`allowManagedMcpServersOnly`](/docs/zh-CN/settings-reference#allowmanagedmcpserversonly) | 当 `true` 时，仅尊重来自托管设置的 `allowedMcpServers`。`deniedMcpServers` 仍然从所有源合并。请参阅[从每个管理源读取的密钥](#keys-read-from-every-admin-source)以了解哪些托管源可以设置它，以及[托管 MCP 配置](/docs/zh-CN/managed-mcp) |

393| [`allowManagedPermissionRulesOnly`](/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly) | 使托管设置成为权限规则的唯一设置源。条目列出它忽略的每个源 |404| [`allowManagedPermissionRulesOnly`](/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly) | 使托管设置成为权限规则的唯一设置源。条目列出它忽略的每个源 |

394| [`blockedMarketplaces`](/docs/zh-CN/settings-reference#blockedmarketplaces) | 市场源的阻止列表。被阻止的源在下载前被检查，因此它们永远不会接触文件系统。请参阅[托管市场限制](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) |405| [`blockedMarketplaces`](/docs/zh-CN/settings-reference#blockedmarketplaces) | 市场源的阻止列表。被阻止的源在下载前被检查，因此它们永远不会接触文件系统。请参阅[托管市场限制](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) |

395| [`channelsEnabled`](/docs/zh-CN/settings-reference#channelsenabled) | 允许组织的[通道](/docs/zh-CN/channels)。请参阅[企业控制](/docs/zh-CN/channels#enterprise-controls)以获取每个计划上的默认值 |406| [`channelsEnabled`](/docs/zh-CN/settings-reference#channelsenabled) | 允许组织的[通道](/docs/zh-CN/channels)。请参阅[企业控制](/docs/zh-CN/channels#enterprise-controls)以获取每个计划上的默认值 |

405| [`sandbox.filesystem.allowManagedReadPathsOnly`](/docs/zh-CN/settings-reference#sandbox-filesystem-allowmanagedreadpathsonly) | 当 `true` 时，仅尊重来自托管设置的 `filesystem.allowRead` 路径。`denyRead` 仍然从所有源合并 |416| [`sandbox.filesystem.allowManagedReadPathsOnly`](/docs/zh-CN/settings-reference#sandbox-filesystem-allowmanagedreadpathsonly) | 当 `true` 时，仅尊重来自托管设置的 `filesystem.allowRead` 路径。`denyRead` 仍然从所有源合并 |

406| [`sandbox.network.allowManagedDomainsOnly`](/docs/zh-CN/settings-reference#sandbox-network-allowmanageddomainsonly) | 仅尊重托管 `allowedDomains` 和 `WebFetch(domain:...)` 允许规则；阻止其他域而不提示 |417| [`sandbox.network.allowManagedDomainsOnly`](/docs/zh-CN/settings-reference#sandbox-network-allowmanageddomainsonly) | 仅尊重托管 `allowedDomains` 和 `WebFetch(domain:...)` 允许规则；阻止其他域而不提示 |

407| [`strictKnownMarketplaces`](/docs/zh-CN/settings-reference#strictknownmarketplaces) | 控制用户可以添加和安装插件的插件市场源。请参阅[托管市场限制](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) |418| [`strictKnownMarketplaces`](/docs/zh-CN/settings-reference#strictknownmarketplaces) | 控制用户可以添加和安装插件的插件市场源。请参阅[托管市场限制](/docs/zh-CN/plugin-marketplaces#managed-marketplace-restrictions) |

408| [`strictPluginOnlyCustomization`](/docs/zh-CN/settings-reference#strictpluginonlycustomization) | 阻止来自用户和项目源的技能、代理、钩子和 MCP 服务器；`true` 锁定所有四个，数组命名哪些 |419| [`strictPluginOnlyCustomization`](/docs/zh-CN/settings-reference#strictpluginonlycustomization) | 阻止来自用户和项目源的 skills、agents、hooks 和 MCP 服务器；`true` 锁定所有四个，数组命名哪些 |

409| [`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`；条目给出顺序 |420| [`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`；条目给出顺序 |

410 421

411<Note>422<Note>

412 在 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) 设置按设备禁用。网络会话没有按设备托管设置密钥。423 在 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) 设置按设备禁用。云会话没有按设备托管设置密钥。

413 424

414 要检查这些组织设置是否到达给定机器，在那里运行 `claude doctor` 并读取 `Organization policy` 行，它说 Claude Code 从哪里加载策略或为什么它没有加载。需要 Claude Code v2.1.261 或更高版本。在运行会话中，当策略未加载时，`/status` 显示相同的行。425 要检查这些组织设置是否到达给定机器，在那里运行 `claude doctor` 并读取 `Organization policy` 行，它说 Claude Code 从哪里加载策略或为什么它没有加载。需要 Claude Code v2.1.261 或更高版本。在运行会话中，当策略未加载时，`/status` 显示相同的行。

415</Note>426</Note>

mcp.md +64 −14

Details

151 151

152 没有 `--`，Claude Code 会尝试将服务器的标志（如上面的 `--port`）解析为自己的选项。152 没有 `--`，Claude Code 会尝试将服务器的标志（如上面的 `--port`）解析为自己的选项。

153 153

154 `--env` 接受多个 `KEY=value` 对。如果服务器名称直接跟在 `--env` 之后，CLI 会将名称读取为另一对并拒绝它，因此在 `--env` 和服务器名称之间至少放置一个其他选项，如上面的示例所示。154 `--env` 接受多个 `KEY=value` 对。如果服务器名称直接跟在 `--env` 之后，CLI 会将名称读取为另一对并拒绝它，因此在 `--env` 和服务器名称之间至少放置一个其他选项，如 `--transport stdio`。

155</Note>155</Note>

156 156

157<h3 id="option-4-add-a-remote-websocket-server">157<h3 id="option-4-add-a-remote-websocket-server">

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 不修剪空格并完全按照写入的方式使用值，因此编辑配置以删除它。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 不修剪空格并完全按照写入的方式使用值，因此编辑配置以删除它。

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 密钥。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 密钥。

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` 未被保留，因此用户配置的服务器可以在该名称下注册。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` 未被保留，因此用户配置的服务器可以在该名称下注册。

326* **缺少环境变量**：如果 [`${VAR}` 引用](#environment-variable-expansion-in-mcp-json) 在服务器的配置中命名一个未设置且没有 `:-default` 的变量，Claude Code 在 `claude mcp list` 输出和 `/mcp` 中警告，命名变量，并仍然加载服务器，`${VAR}` 文本未展开。设置变量或添加 `${VAR:-default}` 回退。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) 而不是，没有警告。

327 327

328<h4 id="tool-availability">328<h4 id="tool-availability">

329 工具可用性329 工具可用性

360 360

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 运行时。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 运行时。

362 362

363在 Claude Code v2.1.232 或更高版本上，Claude Code 使用 v2 运行时。它在每次启动时选择一个运行时，并保持到您退出。当您运行它时，它使用 v1：363Claude Code 在每次启动时选择一个运行时，并保持到您退出。在 Claude Code v2.1.232 或更高版本上，在 [获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) 的会话中，它使用 v2 运行时。

364 364

365* 在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上，除非嵌入 Claude Code 的主机平台设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars)365在不获取功能标志的会话中，Claude Code 在 Claude Code v2.1.274 或更高版本上默认使用 v2 运行时：

366* 通过 [Claude 应用网关](/docs/zh-CN/claude-apps-gateway) 登录366

367* 使用 [功能标志获取关闭](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)367* Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上的会话，除非嵌入 Claude Code 的主机平台设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars)

368* 通过 [Claude 应用网关](/docs/zh-CN/claude-apps-gateway) 登录的会话

369* 您关闭遥测或功能标志获取的会话，例如使用 `DISABLE_TELEMETRY`

368 370

369在 v2 上，Claude Code 也：371在 v2 上，Claude Code 也：

370 372

371* 询问 HTTP 和 claude.ai 连接器服务器是否支持较新的修订版，并与支持的服务器一起使用。它仅在您设置 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 为 `auto` 时询问 stdio 服务器，并像 v1 一样连接到每个其他服务器。373* 询问 HTTP 服务器是否支持较新的修订版，并与支持的服务器一起使用它。它也询问在获取功能标志的会话中的 claude.ai 连接器服务器。要让它询问 stdio 服务器或在每个会话中询问连接器服务器，请设置 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 为 `auto`。它像 v1 一样连接到每个其他服务器。

372* 从 [它保持打开的流](#notification-streams-on-the-v2-runtime) 上的较新修订版的服务器接收 `list_changed` 通知。374* 从 [它保持打开的流](#notification-streams-on-the-v2-runtime) 上的较新修订版的服务器接收 `list_changed` 通知。

373* 不注册在较新修订版上连接的 [通道](#push-messages-with-channels) 服务器，因为该修订版无法携带通道消息。375* 不注册在较新修订版上连接的 [通道](#push-messages-with-channels) 服务器，因为该修订版无法携带通道消息。

374* 失败 [MCP OAuth 登录](#authenticate-with-remote-mcp-servers)，其授权响应命名意外的发行者。376* 失败 [MCP OAuth 登录](#authenticate-with-remote-mcp-servers)，其授权响应命名意外的发行者。

375 377

376Anthropic 可以使用 Claude Code 获取的功能标志将特定服务器保持在较早的协议上，或将其从该流中移除。378Anthropic 可以使用 Claude Code 获取的功能标志将特定服务器保持在较早的协议上，或将其从该流中移除。

377 379

378要自己选择运行时，请设置 [`MCP_SDK_GENERATION`](/docs/zh-CN/env-vars) 为 `v1` 或 `v2`。要决定 Claude Code 是否询问，请设置 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 为 `auto` 或 `legacy`。在 Claude Code 默认使用 v1 的地方，固定 `v2` 不会使其询问，因此也设置 `auto`。380要自己选择运行时，请设置 [`MCP_SDK_GENERATION`](/docs/zh-CN/env-vars) 为 `v1` 或 `v2`。要决定 Claude Code 是否询问，请设置 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 为 `auto` 或 `legacy`。

379 381

380<h3 id="dynamic-tool-updates">382<h3 id="dynamic-tool-updates">

381 动态工具更新383 动态工具更新

679 681

680Claude Code 支持 `.mcp.json` 文件中的环境变量扩展，允许团队共享配置，同时为特定于机器的路径和 API 密钥等敏感值保持灵活性。682Claude Code 支持 `.mcp.json` 文件中的环境变量扩展，允许团队共享配置，同时为特定于机器的路径和 API 密钥等敏感值保持灵活性。

681 683

682**支持的语法：**684<h4 id="supported-syntax">

685 支持的语法

686</h4>

683 687

684* `${VAR}`：扩展为环境变量 `VAR` 的值688* `${VAR}`：扩展为环境变量 `VAR` 的值

685* `${VAR:-default}`：如果设置了 `VAR`，则扩展为 `VAR`，否则使用 `default`689* `${VAR:-default}`：如果设置了 `VAR`，则扩展为 `VAR`，否则使用 `default`

686 690

687**扩展位置：**691<h4 id="expansion-locations">

692 扩展位置

693</h4>

694

688环境变量可以在以下位置扩展：695环境变量可以在以下位置扩展：

689 696

690* `command`：服务器可执行文件路径697* `command`：服务器可执行文件路径

693* `url`：对于 HTTP 服务器类型700* `url`：对于 HTTP 服务器类型

694* `headers`：对于 HTTP 服务器身份验证701* `headers`：对于 HTTP 服务器身份验证

695 702

696**带有变量扩展的示例：**703<h4 id="example-with-variable-expansion">

704 带有变量扩展的示例

705</h4>

697 706

698```json theme={null}707```json theme={null}

699{708{

709}718}

710```719```

711 720

712如果未设置所需的环境变量且没有默认值，配置仍然会加载：Claude Code 在 `claude mcp list` 输出中为该服务器报告缺失变量警告，并按原样使用未扩展的 `${VAR}` 文本。设置变量或添加 `:-default` 回退，以便服务器使用您想要的值启动。721<h4 id="unset-variables-without-a-default">

722 未设置且无默认值的变量

723</h4>

724

725如果未设置所需的环境变量且没有默认值，配置仍然会加载：Claude Code 在 `claude mcp list` 输出中为该服务器报告缺失变量警告，并按原样使用未扩展的 `${VAR}` 文本。设置变量或添加 `:-default` 回退，以便服务器使用您想要的值启动。在远程服务器的 `url` 和 `headers` 中，某些凭据变量[读取为空](#credential-variables-that-read-as-empty)，没有警告。

726

727<h4 id="credential-variables-that-read-as-empty">

728 读取为空的凭据变量

729</h4>

730

731在远程服务器的 `url` 和 `headers` 中，Claude Code 从您的环境中读取凭据变量为空，而不是扩展它们。这可以防止项目的 `.mcp.json` 或插件将您的 Claude Code 或云提供商凭据发送到它命名的服务器。如果您写入 `Bearer ${ANTHROPIC_AUTH_TOKEN}`，服务器会收到 `Bearer ` 而没有凭据，并拒绝请求，通常返回 `401`。Claude Code 将其报告为连接失败。

732

733涵盖的名称包括：

734

735* Claude Code 自己的凭据，例如 `ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN`

736* 您的云提供商的凭据，例如 `AWS_BEARER_TOKEN_BEDROCK`

737* 您的环境携带的其他凭据，例如 `HTTPS_PROXY` 和 `NPM_TOKEN`

738

739涵盖的名称读取为空，无论您是否设置了变量，其上的 `:-default` 回退被忽略。提供商基础 URL（例如 `ANTHROPIC_BASE_URL`）仍然会扩展，因此 `"url": "${ANTHROPIC_BASE_URL}/mcp"` 有效，除非 URL 的值本身嵌入凭据（例如用户名和密码）。

740

741此集合之外的名称（例如 `API_KEY`）按原样扩展。要向服务器提供涵盖的凭据之一，请将其复制到具有您自己的名称的变量中，并改为引用该名称。

742

743当远程服务器的 `url` 或 `headers` 引用您已设置的涵盖变量时，Claude Code 在调试日志行中命名它。要读取该行，请运行 `claude --debug-file /tmp/claude-debug.log` 并在该文件中搜索 `never expanded toward a remote server`。

744

745<h4 id="how-references-appear-in-/mcp-and-cli-output">

746 引用在 `/mcp` 和 CLI 输出中的显示方式

747</h4>

748

749对于本地、项目或用户[范围](#mcp-installation-scopes)中的服务器，以下界面按名称而不是按其解析值显示 `${VAR}` 引用：

750

751* 服务器的 `/mcp` 详细视图中的 URL 或命令行

752* `claude mcp list` 和 `claude mcp get` 输出

753

754`/mcp` 详细视图在 Claude Code v2.1.268 或更高版本中以这种方式显示引用。

755

756对于您的组织通过 `managedMcpServers` 设置提供的服务器，这些界面仅显示[URL 的主机](/docs/zh-CN/managed-mcp#what-users-can-see-and-change)。

757

758要检查当连接失败时 `claude mcp list`、`claude mcp get` 和 `/mcp` 显示的内容，请参阅[服务器状态详情](#server-status-detail)。

713 759

714<h2 id="practical-examples">760<h2 id="practical-examples">

715 实际示例761 实际示例

779 825

780* 对于您尚未登录的服务器，任一状态代码都会在 `/mcp` 中标记它，以便您可以完成 OAuth 流程。826* 对于您尚未登录的服务器，任一状态代码都会在 `/mcp` 中标记它，以便您可以完成 OAuth 流程。

781* 对于 [claude.ai 连接器](#use-mcp-servers-from-claude-ai)，由 claude.ai 拒绝您的会话令牌导致的 `401` 不会标记连接器，因为重新授权连接器无法修复您的登录。Claude Code 改为显示 [会话令牌被拒绝状态](/docs/zh-CN/errors#claude-ai-rejected-the-session-token)。827* 对于 [claude.ai 连接器](#use-mcp-servers-from-claude-ai)，由 claude.ai 拒绝您的会话令牌导致的 `401` 不会标记连接器，因为重新授权连接器无法修复您的登录。Claude Code 改为显示 [会话令牌被拒绝状态](/docs/zh-CN/errors#claude-ai-rejected-the-session-token)。

782* 对于您在 `headers` 中配置了 `Authorization` 标头的服务器，或通过 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 配置的服务器，连接时的 `401` 或 `403` 不会标记服务器，因为要修复的凭据是您配置的凭据。Claude Code 改为报告连接失败。828* 对于您在 `headers` 中配置了 `Authorization` 标头的服务器，或通过 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 配置的服务器，连接时的 `401` 或 `403` 不会标记服务器，因为要修复的凭据是您配置的凭据。Claude Code 改为报告连接失败。如果您从 `${VAR}` 引用设置该标头，请检查该变量是否是 Claude Code [读取为空](#credential-variables-that-read-as-empty) 的变量之一。

783* 对于 [传递到云会话的连接器](#how-connectors-reach-claude-code)，Claude Code 不运行登录流程，因为会话的代理使用您在 claude.ai 中授予的授权向连接器进行身份验证。当那里的连接器需要再次授权时，请在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 重新连接它，而不是从会话中重新连接。829* 对于 [传递到云会话的连接器](#how-connectors-reach-claude-code)，Claude Code 不运行登录流程，因为会话的代理使用您在 claude.ai 中授予的授权向连接器进行身份验证。当那里的连接器需要再次授权时，请在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 重新连接它，而不是从会话中重新连接。

784 830

785当对您已登录的 OAuth 服务器的请求返回 `401 Unauthorized` 时，Claude Code 会刷新存储的令牌、重新连接并重试请求一次。只有在该重试也失败时，它才会在 `/mcp` 中标记服务器。在 v2.1.206 之前，由于网络错误等暂时性原因导致的令牌刷新失败会将 OAuth 服务器标记为在会话的其余时间需要身份验证，即使其刷新令牌仍然有效。831当对您已登录的 OAuth 服务器的请求返回 `401 Unauthorized` 时，Claude Code 会刷新存储的令牌、重新连接并重试请求一次。只有在该重试也失败时，它才会在 `/mcp` 中标记服务器。在 v2.1.206 之前，由于网络错误等暂时性原因导致的令牌刷新失败会将 OAuth 服务器标记为在会话的其余时间需要身份验证，即使其刷新令牌仍然有效。

790 836

791Claude Code 也会在启动时显示通知，当一个或多个配置的服务器需要身份验证时，这样您就不必打开 `/mcp` 来发现哪些服务器需要登录。该通知需要 Claude Code v2.1.193 或更高版本。它仅计算您可以从 Claude Code 登录的服务器。在 v2.1.218 之前，它还计算 [claude.ai 连接器](#use-mcp-servers-from-claude-ai)，这些连接器在 claude.ai 中未连接，您只能从 claude.ai 设置中连接。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 设置中连接。

792 838

839该通知每次启动时宣布每个服务器一次，并将其从计数中排除，直到该服务器已连接并再次需要登录。`/mcp` 仍然列出每个需要登录的服务器。

840

793在非交互模式下，没有 `/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>` 完成登录。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>` 完成登录。

794 842

795如果您为服务器配置了 `headers.Authorization`，而服务器拒绝了该标头，Claude Code 会将连接报告为失败，而不是回退到 OAuth。检查令牌对于 MCP 端点是否有效，或删除标头以使用 OAuth 流程。843如果您为服务器配置了 `headers.Authorization`，而服务器拒绝了该标头，Claude Code 会将连接报告为失败，而不是回退到 OAuth。检查令牌对于 MCP 端点是否有效，或删除标头以使用 OAuth 流程。

983 1031

984如果授权服务器在 `scopes_supported` 中公开 `offline_access`，Claude Code 会将其附加到固定范围，以便可以在没有新浏览器登录的情况下刷新访问令牌。1032如果授权服务器在 `scopes_supported` 中公开 `offline_access`，Claude Code 会将其附加到固定范围，以便可以在没有新浏览器登录的情况下刷新访问令牌。

985 1033

986如果服务器稍后为工具调用返回 403 `insufficient_scope`，Claude Code 会使用相同的固定范围重新进行身份验证。当您需要的工具需要固定范围之外的范围时，扩展 `oauth.scopes`。1034如果服务器稍后为工具调用返回 403 `insufficient_scope`，调用会失败，并显示 [`需要额外权限`](/docs/zh-CN/errors#mcp-server-needs-you-to-sign-in-again) 消息，该消息命名服务器请求的范围。服务器在 `/mcp` 中显示为需要身份验证。

1035

1036如果该范围不在您的固定 `oauth.scopes` 中，请添加它，然后运行 `/mcp` 并再次对服务器进行身份验证。Claude Code 请求固定范围而不是服务器命名的范围，因此如果您在不添加它的情况下再次进行身份验证，您获得的令牌仍然缺少它。

987 1037

988<h3 id="use-dynamic-headers-for-custom-authentication">1038<h3 id="use-dynamic-headers-for-custom-authentication">

989 使用动态标头进行自定义身份验证1039 使用动态标头进行自定义身份验证

mcp-quickstart.md +2 −2

Details

305 305

306本指南使用 `claude mcp` CLI 命令，但每个 Claude Code 界面都可以连接到 MCP 服务器：306本指南使用 `claude mcp` CLI 命令，但每个 Claude Code 界面都可以连接到 MCP 服务器：

307 307

308* **Claude Code 桌面应用**：通过 [连接器 UI](/docs/zh-CN/desktop#connect-external-tools) 添加服务器。308* **Claude Code 桌面应用**：通过[连接器 UI](/docs/zh-CN/desktop#connect-external-tools)添加服务器。

309* **Claude 桌面聊天应用**：与 Claude Code 不同的应用。要将其 `claude_desktop_config.json` 中的服务器复制到 CLI，请在 macOS 或 WSL 上运行 `claude mcp add-from-claude-desktop`。309* **Claude 桌面聊天应用**：与 Claude Code 不同的应用。要将其 `claude_desktop_config.json` 中的服务器复制到 CLI，请在 macOS 或 WSL 上运行 `claude mcp add-from-claude-desktop`。

310* **VS Code**：请参阅[使用 MCP 连接到外部工具](/docs/zh-CN/vs-code#connect-to-external-tools-with-mcp)。310* **VS Code**：请参阅[使用 MCP 连接到外部工具](/docs/zh-CN/vs-code#connect-to-external-tools-with-mcp)。

311* **网络上的 Claude Code**：从您的存储库读取 `.mcp.json`。请参阅[直接编辑 .mcp.json](#edit-mcp-json-directly)。311* **云会话**：将 `.mcp.json` 提交到您的存储库；一个包含一个存储库的会话会加载它。请参阅[直接编辑 .mcp.json](#edit-mcp-json-directly) 和[您的设置中保留的内容](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)。

312* **Claude.ai**：您在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 添加的连接器在您使用该帐户登录 CLI 时自动加载。请参阅[从 Claude.ai 使用 MCP 服务器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)。312* **Claude.ai**：您在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 添加的连接器在您使用该帐户登录 CLI 时自动加载。请参阅[从 Claude.ai 使用 MCP 服务器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)。

313 313

314<h2 id="troubleshooting">314<h2 id="troubleshooting">

memory.md +243 −114

Details

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

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

4 4

~~5# Claude 如何记住你的项目~~5# Claude 如何记住您的项目

6 6

~~7> 使用 CLAUDE.md 文件为 Claude 提供持久指令，并让 Claude 通过自动记忆功能自动积累学习内容。~~7> 使用 CLAUDE.md 或 AGENTS.md 文件为 Claude 提供持久指令，并让 Claude 通过自动记忆自动积累学习。

8 8

~~9每个 Claude Code 会话都从一个全新的上下文窗口开始。两种机制可以跨会话传递知识：~~9每个 Claude Code 会话都以全新的上下文窗口开始。两种机制可以跨会话传递知识：

10 10

~~11* **CLAUDE.md 文件**：你编写的指令，为 Claude 提供持久上下文~~11* **CLAUDE.md 文件**：您编写的指令，为 Claude 提供持久上下文。Claude 也可以读取存储库的 [`AGENTS.md` 文件](#agents-md)，单独使用或与 CLAUDE.md 一起使用

~~12* **自动记忆**：Claude 根据你的更正和偏好自己编写的笔记~~12* **自动记忆**：Claude 根据您的更正和偏好自己编写的笔记

13 13

14本页面涵盖以下内容：14本页面涵盖以下内容：

15 15

16* [编写和组织 CLAUDE.md 文件](#claude-md-files)16* [编写和组织 CLAUDE.md 文件](#claude-md-files)

~~17* [使用 `.claude/rules/` 将规则范围限定到特定文件类型](#organize-rules-with-claude/rules/)~~17* [使用现有 AGENTS.md](#agents-md) 作为您的项目指令，单独使用或与 CLAUDE.md 一起使用

~~18* [配置自动记忆](#auto-memory)，使 Claude 自动记笔记~~18* [使用 `.claude/rules/` 将规则范围限定为特定文件类型](#organize-rules-with-claude/rules/)

~~19* [故障排除](#troubleshoot-memory-issues)，当指令未被遵循时~~19* [配置自动记忆](#auto-memory)，以便 Claude 自动记笔记

20* [故障排除](#troubleshoot-memory-issues)当指令未被遵循时

20 21

21<h2 id="claude-md-vs-auto-memory">22<h2 id="claude-md-vs-auto-memory">

22 CLAUDE.md 与自动记忆23 CLAUDE.md 与自动记忆

40 CLAUDE.md 文件41 CLAUDE.md 文件

41</h2>42</h2>

42 43

43CLAUDE.md 文件是 markdown 文件，为项目、你的个人工作流或整个组织为 Claude 提供持久指令。你用纯文本编写这些文件；Claude 在每个会话开始时读取它们。44CLAUDE.md 文件是 markdown 文件，为 Claude 提供项目、个人工作流或整个组织的持久指令。您用纯文本编写这些文件；Claude 在每个会话开始时读取它们。如果您的存储库改用 `AGENTS.md`，请参阅 [AGENTS.md](#agents-md)。

44 45

45<h3 id="when-to-add-to-claude-md">46<h3 id="when-to-add-to-claude-md">

46 何时添加到 CLAUDE.md47 何时添加到 CLAUDE.md

47</h3>48</h3>

48 49

~~49将 CLAUDE.md 视为你写下你本来会重新解释的内容的地方。在以下情况下添加到它：~~50将 CLAUDE.md 视为您写下本来需要重新解释的内容的地方。在以下情况下添加到它：

50 51

51* Claude 第二次犯同样的错误52* Claude 第二次犯同样的错误

~~52* 代码审查发现 Claude 应该了解这个代码库的内容~~53* 代码审查发现 Claude 应该了解的关于此代码库的内容

~~53* 你在聊天中输入的相同更正或澄清是你上个会话输入的~~54* 您在聊天中输入的相同更正或澄清是您上一个会话中输入的

54* 新队友需要相同的上下文才能提高生产力55* 新队友需要相同的上下文才能提高生产力

55 56

56将其保持为 Claude 应该在每个会话中保持的事实：构建命令、约定、项目布局、"总是做 X"规则。如果一个条目是多步骤过程或仅对代码库的一部分重要，将其移到 [skill](/docs/zh-CN/skills) 或 [路径范围规则](#path-specific-rules) 中。[扩展概述](/docs/zh-CN/features-overview#build-your-setup-over-time)涵盖何时使用每种机制。57将其保持为 Claude 应该在每个会话中保留的事实：构建命令、约定、项目布局、"始终执行 X"规则。如果条目是多步骤过程或仅对代码库的一部分重要，请将其移至 [skill](/docs/zh-CN/skills) 或 [path-scoped rule](#organize-rules-with-claude/rules/) 代替。[扩展概述](/docs/zh-CN/features-overview#build-your-setup-over-time) 涵盖何时使用每种机制。

57 58

58<h3 id="choose-where-to-put-claude-md-files">59<h3 id="choose-where-to-put-claude-md-files">

59 选择 CLAUDE.md 文件的位置60 选择 CLAUDE.md 文件的位置

60</h3>61</h3>

61 62

62CLAUDE.md 文件可以位于多个位置，每个位置有不同的范围。下表按加载顺序列出它们，从最广泛的范围到最具体的范围，因此项目指令在用户指令之后出现在上下文中。63CLAUDE.md 文件可以位于多个位置，每个位置具有不同的范围。下表按加载顺序列出它们，从最广泛的范围到最具体的范围，因此项目指令在用户指令之后出现在上下文中。

63 64

64| 范围 | 位置 | 目的 | 用例示例 | 共享对象 |65| 范围 | 位置 | 目的 | 用例示例 | 共享对象 |

65| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ---------------- | ------------ |66| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ---------------- | ------------ |

70 71

71工作目录上方目录层次结构中的 CLAUDE.md 和 CLAUDE.local.md 文件在启动时完整加载。子目录中的文件在 Claude 读取这些目录中的文件时按需加载。有关完整的解析顺序，请参阅 [CLAUDE.md 文件如何加载](#how-claude-md-files-load)。72工作目录上方目录层次结构中的 CLAUDE.md 和 CLAUDE.local.md 文件在启动时加载。子目录中的文件在 Claude 读取这些目录中的文件时按需加载。有关完整的解析顺序，请参阅 [CLAUDE.md 文件如何加载](#how-claude-md-files-load)。

72 73

73对于大型项目，你可以使用 [项目规则](#organize-rules-with-claude/rules/) 将指令分解为特定主题的文件。规则让你将指令范围限定到特定文件类型或子目录。74对于大型项目，您可以使用 [project rules](#organize-rules-with-claude/rules/) 将指令分解为特定主题的文件。规则允许您将指令范围限定为特定文件类型或子目录。

74 75

75<h3 id="set-up-a-project-claude-md">76<h3 id="set-up-a-project-claude-md">

76 设置项目 CLAUDE.md77 设置项目 CLAUDE.md

77</h3>78</h3>

78 79

79项目 CLAUDE.md 可以存储在 `./CLAUDE.md` 或 `./.claude/CLAUDE.md` 中。创建此文件并添加适用于在项目上工作的任何人的指令：构建和测试命令、编码标准、架构决策、命名约定和常见工作流。这些指令通过版本控制与你的团队共享，因此请关注项目级标准而不是个人偏好。要确认文件已加载，在会话中运行 `/context` 并检查 **Memory files** 下的列表。80项目 CLAUDE.md 可以存储在 `./CLAUDE.md` 或 `./.claude/CLAUDE.md` 中。创建此文件并添加适用于在项目上工作的任何人的指令：构建和测试命令、编码标准、架构决策、命名约定和常见工作流。这些指令通过版本控制与您的团队共享，因此请关注项目级标准而不是个人偏好。要确认文件已加载，请在会话中运行 `/context` 并检查 **Memory files** 下的列表。

80 81

81<Tip>82<Tip>

82 运行 `/init` 自动生成起始 CLAUDE.md。Claude 分析你的代码库并创建一个包含构建命令、测试指令和它发现的项目约定的文件。如果 CLAUDE.md 已存在，`/init` 会建议改进而不是覆盖它。从那里进行细化，添加 Claude 不会自己发现的指令。83 运行 `/init` 自动生成起始 CLAUDE.md。Claude 分析您的代码库并创建一个包含构建命令、测试指令和它发现的项目约定的文件。如果 CLAUDE.md 已存在，`/init` 会建议改进而不是覆盖它。从那里进行细化，添加 Claude 不会自己发现的指令。

83 84

84 设置 `CLAUDE_CODE_NEW_INIT=1` 以启用交互式多阶段流程。`/init` 询问要设置哪些工件：CLAUDE.md 文件、skills 和 hooks。然后它使用 subagent 探索你的代码库，通过后续问题填补空白，并在写入任何文件之前呈现可审查的提案。85 设置 `CLAUDE_CODE_NEW_INIT=1` 以启用交互式多阶段流程。`/init` 询问要设置哪些工件：CLAUDE.md 文件、skills 和 hooks。然后它使用子代理探索您的代码库，通过后续问题填补空白，并在写入任何文件之前呈现可审查的提案。

85</Tip>86</Tip>

86 87

87<h3 id="write-effective-instructions">88<h3 id="write-effective-instructions">

88 编写有效的指令89 编写有效的指令

89</h3>90</h3>

90 91

91CLAUDE.md 文件在每个会话开始时加载到上下文窗口中，与你的对话一起消耗令牌。[上下文窗口可视化](/docs/zh-CN/context-window)显示 CLAUDE.md 相对于其余启动上下文的加载位置。因为它们是上下文而不是强制配置，你编写指令的方式会影响 Claude 遵循它们的可靠性。具体、简洁、结构良好的指令效果最好。92CLAUDE.md 文件在每个会话开始时加载到上下文窗口中，与您的对话一起消耗令牌。[上下文窗口可视化](/docs/zh-CN/context-window) 显示 CLAUDE.md 相对于其余启动上下文的加载位置。因为它们是上下文而不是强制配置，您编写指令的方式会影响 Claude 遵循它们的可靠性。具体、简洁、结构良好的指令效果最好。

92 93

93**大小**：每个 CLAUDE.md 文件目标在 200 行以下。较长的文件消耗更多上下文并降低遵守度。如果你的指令变得很大，使用 [路径范围规则](#path-specific-rules) 以便指令仅在 Claude 处理匹配文件时加载。你也可以将内容分割成 [导入](#import-additional-files) 以便组织，尽管导入的文件仍然加载并在启动时进入上下文窗口。94**大小**：每个 CLAUDE.md 文件目标在 200 行以下。较长的文件消耗更多上下文并降低遵守度。如果您的指令变得很大，请使用 [path-scoped rules](#path-specific-rules)，以便指令仅在 Claude 处理匹配文件时加载。您也可以将内容拆分为 [imports](#import-additional-files) 以便组织，尽管导入的文件仍然加载并在启动时进入上下文窗口。

94 95

95**结构**：使用 markdown 标题和项目符号来分组相关指令。Claude 扫描结构的方式与读者相同：有组织的部分比密集段落更容易遵循。96**结构**：使用 markdown 标题和项目符号来分组相关指令。Claude 扫描结构的方式与读者相同：有组织的部分比密集段落更容易遵循。

96 97

97**具体性**：编写具体到足以验证的指令。例如：98**具体性**：编写具体到足以验证的指令。例如：

98 99

99* "使用 2 空格缩进"而不是"正确格式化代码"100* "使用 2 空格缩进"而不是"正确格式化代码"

100* "在提交前运行 `npm test`"而不是"测试你的更改"101* "在提交前运行 `npm test`"而不是"测试您的更改"

101* "API 处理程序位于 `src/api/handlers/`"而不是"保持文件有组织"102* "API 处理程序位于 `src/api/handlers/`"而不是"保持文件有组织"

102 103

103**一致性**：如果两条规则相互矛盾，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 文件。

104 105

105<h3 id="import-additional-files">106<h3 id="import-additional-files">

106 导入其他文件107 导入其他文件

107</h3>108</h3>

108 109

109CLAUDE.md 文件可以使用 `@path/to/import` 语法导入其他文件。导入的文件在启动时展开并加载到上下文中，与引用它们的 CLAUDE.md 一起。110CLAUDE.md 文件可以使用 `@path/to/import` 语法导入其他文件。导入的文件被展开并在启动时加载到上下文中，与引用它们的 CLAUDE.md 一起。

110 111

111允许相对路径和绝对路径。相对路径相对于包含导入的文件解析，而不是工作目录。导入的文件可以递归导入其他文件，最大深度为四跳。112允许相对路径和绝对路径。相对路径相对于包含导入的文件解析，而不是工作目录。导入的文件可以递归导入其他文件，最大深度为四跳。

112 113

113导入解析跳过 Markdown 代码跨度和围栏代码块。要在你的 CLAUDE.md 中提及路径而不导入它，将其包装在反引号中：写 `` `@README` `` 保持文本字面，而 `@README` 在反引号外导入文件。114导入解析跳过 Markdown 代码跨度和围栏代码块。要在您的 CLAUDE.md 中提及路径而不导入它，请将其包装在反引号中：编写 `` `@README` `` 保持文本字面，而 `@README` 在反引号外导入文件。

114 115

115要引入 README、package.json 和工作流指南，在你的 CLAUDE.md 中的任何地方使用 `@` 语法引用它们：116要引入 README、package.json 和工作流指南，请在 CLAUDE.md 中的任何地方使用 `@` 语法引用它们：

116 117

117```text theme={null}118```text theme={null}

118有关项目概述，请参阅 @README，有关此项目的可用 npm 命令，请参阅 @package.json。119See @README for project overview and @package.json for available npm commands for this project.

119 120

120# 其他指令121# Additional Instructions

121- git 工作流 @docs/git-instructions.md122- git workflow @docs/git-instructions.md

122```123```

123 124

124对于你不想签入版本控制的私人项目偏好，在项目根目录创建 `CLAUDE.local.md`。它与 `CLAUDE.md` 一起加载并以相同方式处理。将 `CLAUDE.local.md` 添加到你的 `.gitignore` 以便它不被提交。设置 `CLAUDE_CODE_NEW_INIT=1` 后，运行 `/init` 并选择个人选项会为你做这个。125对于不应该检入版本控制的私人项目特定偏好，请在项目根目录创建 `CLAUDE.local.md`。它与 `CLAUDE.md` 一起加载并以相同方式处理。将 `CLAUDE.local.md` 添加到您的 `.gitignore` 以便不提交它。设置 `CLAUDE_CODE_NEW_INIT=1` 后，运行 `/init` 并选择个人选项会为您执行此操作。

125 126

126如果你在同一存储库的多个 git worktrees 中工作，一个被 gitignore 的 `CLAUDE.local.md` 仅存在于你创建它的 worktree 中。要在 worktrees 中共享个人指令，改为从你的主目录导入文件：127如果您在同一存储库的多个 git worktrees 中工作，gitignored `CLAUDE.local.md` 仅存在于您创建它的 worktree 中。要在 worktrees 中共享个人指令，请改为从您的主目录导入文件：

127 128

128```text theme={null}129```text theme={null}

129# 个人偏好130# Individual Preferences

130- @~/.claude/my-project-instructions.md131- @~/.claude/my-project-instructions.md

131```132```

132 133

133<Warning>134<Warning>

134 项目级内存文件中的导入是外部的，当其路径解析到工作目录外时，例如上面的主目录导入。Claude Code 第一次在项目中遇到外部导入时，它会显示一个批准对话框，列出这些文件。如果你拒绝，导入保持禁用状态，对话框不会再出现。135 项目级内存文件中的导入是外部的，当其路径解析到工作目录外时，例如上面的主目录导入。Claude Code 首次在项目中遇到外部导入时，会显示一个批准对话框，列出文件。如果您拒绝，导入保持禁用状态，对话框不会再出现。

135 136

136 Claude Code 显示对话框是为了保护你免受其他人提交到共享项目的文件。用户范围内存文件，例如 `~/.claude/CLAUDE.md` 和 `~/.claude/rules/`，是你自己编写的文件。除了在你的桌面上的 [Cowork](https://claude.com/product/cowork) 会话中，Claude Code 加载它们的导入而不显示对话框，并像信任你的其余个人配置一样信任它们。137 Claude Code 显示对话框以保护您免受其他人提交到共享项目的文件。用户范围内存文件，例如 `~/.claude/CLAUDE.md` 和 `~/.claude/rules/`，是您自己编写的文件。除了在您的桌面上的 [Cowork](https://claude.com/product/cowork) 会话中，Claude Code 加载它们的导入而不显示对话框，并像信任您的其余个人配置一样信任它们。

137 138

138 在你的桌面上的 Cowork 会话中，Claude Code 跳过用户范围文件中解析到会话工作目录外的路径的任何导入，并加载文件的其余部分。在这些会话中，它也跳过本身是符号链接或硬链接的 `~/.claude/CLAUDE.md`，以及指向工作目录外的符号链接 `~/.claude/rules/` 目录或规则文件。139 在您的桌面上的 Cowork 会话中，Claude Code 跳过用户范围文件中解析到会话工作目录外的路径的任何导入，并加载文件的其余部分。在这些会话中，它也跳过本身是符号链接或硬链接的 `~/.claude/CLAUDE.md`，以及指向工作目录外的符号链接 `~/.claude/rules/` 目录或规则文件。

139</Warning>140</Warning>

140 141

141<h3 id="agents-md">

142 AGENTS.md

143</h3>

~~144~~

145Claude Code 读取 `CLAUDE.md`，而不是 `AGENTS.md`。如果你的存储库已经为其他编码代理使用 `AGENTS.md`，创建一个导入它的 `CLAUDE.md`，这样两个工具都可以读取相同的指令而无需重复。你也可以在导入下方添加 Claude 特定的指令。Claude 在会话开始时加载导入的文件，然后附加其余部分：

~~146~~

147```markdown CLAUDE.md theme={null}

148@AGENTS.md

~~149~~

150## Claude Code

~~151~~

152对 `src/billing/` 下的更改使用 Plan Mode。

153```

~~154~~

155一个符号链接也可以工作，如果你不需要添加 Claude 特定的内容：

~~156~~

157```bash theme={null}

158ln -s AGENTS.md CLAUDE.md

159```

~~160~~

161该命令在成功时不打印任何输出。在你的下一个会话中，运行 `/context` 并确认 `CLAUDE.md` 出现在 **Memory files** 下。

~~162~~

163在 Windows 上，创建符号链接需要管理员权限或开发者模式，所以改用 `@AGENTS.md` 导入。

~~164~~

165运行 [`/init`](/docs/zh-CN/commands) 读取 Cursor 规则，在 `.cursor/rules/` 或 `.cursorrules` 中，以及 Copilot 规则，在 `.github/copilot-instructions.md` 中，并将相关部分合并到生成的 `CLAUDE.md` 中。设置 `CLAUDE_CODE_NEW_INIT=1` 后，`/init` 也读取 `AGENTS.md`、`.devin/rules/`、`.windsurf/rules/` 或 `.windsurfrules`，以及 `.clinerules`。

~~166~~

167你也可以运行 [`/import`](/docs/zh-CN/commands) 将支持的编码代理的配置引入 Claude Code，它将指令文件（如 `AGENTS.md`）的一次性副本附加到匹配的 `CLAUDE.md`，并携带 MCP 服务器、命令、subagents 和 skills。需要 Claude Code v2.1.213 或更高版本。

~~168~~

169<h3 id="how-claude-md-files-load">142<h3 id="how-claude-md-files-load">

170 CLAUDE.md 文件如何加载143 CLAUDE.md 文件如何加载

171</h3>144</h3>

172 145

173Claude Code 从你的当前工作目录和其上方的每个目录加载 `CLAUDE.md` 和 `CLAUDE.local.md`。在 `foo/bar/` 中运行 Claude Code，它会从 `foo/bar/CLAUDE.md`、`foo/CLAUDE.md` 和沿途的任何 `CLAUDE.local.md` 文件加载指令。146Claude Code 从您的当前工作目录和其上方的每个目录加载 `CLAUDE.md` 和 `CLAUDE.local.md`。在 `foo/bar/` 中运行 Claude Code，它从 `foo/bar/CLAUDE.md`、`foo/CLAUDE.md` 和任何 `CLAUDE.local.md` 文件加载指令。

174 147

175所有发现的文件被连接到上下文中，而不是相互覆盖。在目录树中，内容从文件系统根目录向下排序到你的工作目录。对于 `foo/bar/` 示例，`foo/CLAUDE.md` 在上下文中出现在 `foo/bar/CLAUDE.md` 之前，因此更接近你启动 Claude 的位置的指令最后被读取。在每个目录中，`CLAUDE.local.md` 在 `CLAUDE.md` 之后附加，因此你的个人笔记是 Claude 在该级别读取的最后内容。148所有发现的文件被连接到上下文中，而不是相互覆盖。在目录树中，内容从文件系统根目录向下排序到您的工作目录。对于 `foo/bar/` 示例，`foo/CLAUDE.md` 在上下文中出现在 `foo/bar/CLAUDE.md` 之前，因此更接近您启动 Claude 的位置的指令最后读取。在每个目录中，`CLAUDE.local.md` 附加在 `CLAUDE.md` 之后，因此您的个人笔记是 Claude 在该级别读取的最后一件事。

176 149

177Claude 还在当前工作目录下的子目录中发现 `CLAUDE.md` 和 `CLAUDE.local.md` 文件。它们不是在启动时加载，而是在 Claude 读取这些子目录中的文件时包含。150Claude 还发现当前工作目录下子目录中的 `CLAUDE.md` 和 `CLAUDE.local.md` 文件。它们不是在启动时加载，而是在 Claude 读取这些子目录中的文件时包含。

178 151

179如果你在一个大型 monorepo 中工作，其他团队的 CLAUDE.md 文件被拾取，使用 [`claudeMdExcludes`](#exclude-specific-claude-md-files) 跳过它们。对于根目录和每个目录的 CLAUDE.md 文件和规则的完整布局，请参阅 [Monorepos 和大型存储库](/docs/zh-CN/large-codebases)。152如果您在大型 monorepo 中工作，其中其他团队的 CLAUDE.md 文件被拾取，请使用 [`claudeMdExcludes`](#exclude-specific-claude-md-files) 跳过它们。有关根目录和每目录 CLAUDE.md 文件和规则的完整布局，请参阅 [Monorepos 和大型存储库](/docs/zh-CN/large-codebases)。

180 153

181块级 HTML 注释（``）在 CLAUDE.md 文件中在内容注入到 Claude 的上下文之前被剥离。使用它们为人类维护者留下笔记，而不在它们上花费上下文令牌。代码块内的注释被保留。当你直接用 Read 工具打开 CLAUDE.md 文件时，注释保持可见。154CLAUDE.md 文件中的块级 HTML 注释（``）在内容注入到 Claude 的上下文之前被剥离。使用它们为人类维护者留下笔记，而不在注释上花费上下文令牌。代码块内的注释被保留。当您直接使用 Read 工具打开 CLAUDE.md 文件时，注释保持可见。

182 155

183<h4 id="load-from-additional-directories">156<h4 id="load-from-additional-directories">

184 从其他目录加载157 从其他目录加载

185</h4>158</h4>

186 159

187`--add-dir` 标志使 Claude 可以访问主工作目录外的其他目录。默认情况下，不加载这些目录中的 CLAUDE.md 文件。160`--add-dir` 标志使 Claude 能够访问主工作目录外的其他目录。默认情况下，这些目录中的 CLAUDE.md 文件不加载。

188 161

189要也从其他目录加载内存文件，设置 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` 环境变量：162要也从其他目录加载内存文件，请设置 `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` 环境变量：

190 163

191```bash theme={null}164```bash theme={null}

192CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config165CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

193```166```

194 167

195这会从其他目录加载 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。如果你从 [`--setting-sources`](/docs/zh-CN/cli-reference) 中排除 `local`，`CLAUDE.local.md` 会被跳过。168这从其他目录加载 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。如果您从 [`--setting-sources`](/docs/zh-CN/cli-reference) 中排除 `local`，则跳过 `CLAUDE.local.md`。

196 169

197<h3 id="organize-rules-with-claude/rules/">170<h3 id="organize-rules-with-claude/rules/">

198 使用 `.claude/rules/` 组织规则171 使用 `.claude/rules/` 组织规则

199</h3>172</h3>

200 173

201对于较大的项目，你可以使用 `.claude/rules/` 目录将指令组织到多个文件中。这使指令保持模块化并更容易让团队维护。规则也可以 [范围限定到特定文件路径](#path-specific-rules)，因此它们仅在 Claude 处理匹配文件时加载到上下文中，减少噪音并节省上下文空间。174对于较大的项目，您可以使用 `.claude/rules/` 目录将指令组织到多个文件中。这使指令模块化并更容易让团队维护。规则也可以 [范围限定到特定文件路径](#path-specific-rules)，因此它们仅在 Claude 处理匹配文件时加载到上下文中，减少噪音并节省上下文空间。

202 175

203<Note>176<Note>

204 规则在每个会话或打开匹配文件时加载到上下文中。对于不需要始终在上下文中的特定任务指令，改用 [skills](/docs/zh-CN/skills)，它仅在你调用它们或 Claude 确定它们与你的提示相关时加载。177 规则在每个会话或打开匹配文件时加载到上下文中。对于不需要始终在上下文中的特定任务指令，请改用 [skills](/docs/zh-CN/skills)，它仅在您调用它们或 Claude 确定它们与您的提示相关时加载。

205</Note>178</Note>

206 179

207<h4 id="set-up-rules">180<h4 id="set-up-rules">

208 设置规则181 设置规则

209</h4>182</h4>

210 183

211在你的项目的 `.claude/rules/` 目录中放置 markdown 文件。每个文件应涵盖一个主题，具有描述性文件名，如 `testing.md` 或 `api-design.md`。所有 `.md` 文件都被递归发现，因此你可以将规则组织到子目录中，如 `frontend/` 或 `backend/`：184在项目的 `.claude/rules/` 目录中放置 markdown 文件。每个文件应涵盖一个主题，具有描述性文件名，如 `testing.md` 或 `api-design.md`。所有 `.md` 文件被递归发现，因此您可以将规则组织到子目录中，如 `frontend/` 或 `backend/`：

212 185

213```text theme={null}186```text theme={null}

214your-project/187your-project/

215├── .claude/188├── .claude/

216│ ├── CLAUDE.md # 主项目指令189│ ├── CLAUDE.md # Main project instructions

217│ └── rules/190│ └── rules/

218│ ├── code-style.md # 代码样式指南191│ ├── code-style.md # Code style guidelines

219│ ├── testing.md # 测试约定192│ ├── testing.md # Testing conventions

220│ └── security.md # 安全要求193│ └── security.md # Security requirements

221```194```

222 195

223没有 [`paths` frontmatter](#path-specific-rules) 的规则在启动时加载，优先级与 `.claude/CLAUDE.md` 相同。196没有 [`paths` frontmatter](#path-specific-rules) 的规则在启动时加载，优先级与 `.claude/CLAUDE.md` 相同。

224 197

225项目规则如果你从 [`--setting-sources`](/docs/zh-CN/cli-reference) 中排除 `project`，则被跳过。在 v2.1.211 之前，加载按需的规则，包括路径范围规则和嵌套 `.claude/rules/` 目录中的规则，即使 `project` 被排除也会加载。198如果您从 [`--setting-sources`](/docs/zh-CN/cli-reference) 中排除 `project`，项目规则被跳过。在 v2.1.211 之前，加载按需的规则，包括路径范围规则和嵌套 `.claude/rules/` 目录中的规则，即使 `project` 被排除也会加载。

226 199

227<h4 id="path-specific-rules">200<h4 id="path-specific-rules">

228 特定路径的规则201 路径特定规则

229</h4>202</h4>

230 203

231规则可以使用带有 `paths` 字段的 YAML frontmatter 范围限定到特定文件。这些条件规则仅在 Claude 处理与指定模式匹配的文件时适用。204规则可以使用带有 `paths` 字段的 YAML frontmatter 范围限定到特定文件。这些条件规则仅在 Claude 处理与指定模式匹配的文件时适用。

236 - "src/api/**/*.ts"209 - "src/api/**/*.ts"

237---210---

238 211

239# API 开发规则212# API Development Rules

240 213

241- 所有 API 端点必须包括输入验证214- All API endpoints must include input validation

242- 使用标准错误响应格式215- Use the standard error response format

243- 包括 OpenAPI 文档注释216- Include OpenAPI documentation comments

244```217```

245 218

246没有 `paths` 字段的规则无条件加载并适用于所有文件。路径范围规则在 Claude 读取与模式匹配的文件时触发，而不是在每次工具使用时。从 v2.1.198 起，匹配也适用于 Claude 通过项目目录的符号链接路径到达文件时，例如在符号链接的检出中。219没有 `paths` 字段的规则无条件加载并适用于所有文件。路径范围规则在 Claude 读取与模式匹配的文件时触发，而不是在每个工具使用时。从 v2.1.198 开始，当 Claude 通过项目目录的符号链接路径到达文件时，匹配也有效，例如在符号链接检出中。

247 220

248在 `paths` 字段中使用 glob 模式按扩展名、目录或任何组合匹配文件：221在 `paths` 字段中使用 glob 模式按扩展名、目录或任何组合匹配文件：

249 222

254| `*.md` | 项目根目录中的 Markdown 文件 |227| `*.md` | 项目根目录中的 Markdown 文件 |

255| `src/components/*.tsx` | 特定目录中的 React 组件 |228| `src/components/*.tsx` | 特定目录中的 React 组件 |

256 229

257你可以指定多个模式并使用大括号扩展在一个模式中匹配多个扩展名：230您可以指定多个模式并使用大括号扩展在一个模式中匹配多个扩展名：

258 231

259```markdown theme={null}232```markdown theme={null}

260---233---

265---238---

266```239```

267 240

268每个大括号组乘以扩展的模式数量：`src/*.{ts,tsx}` 扩展为两个模式，`{a,b}/{c,d}/*.{ts,tsx}` 扩展为八个。要保持扩展有界，规则的整个 `paths` 列表共享一个 1,000 个扩展模式和 4 MiB 的预算，没有大括号的模式不计入其中。241每个大括号组将扩展的模式数量相乘：`src/*.{ts,tsx}` 扩展为两个模式，`{a,b}/{c,d}/*.{ts,tsx}` 扩展为八个。为了保持扩展有界，规则的整个 `paths` 列表共享一个 1,000 个扩展模式和 4 MiB 的预算，没有大括号的模式不计入其中。

269 242

270Claude Code 使用任何会超过预算的模式未展开，其字面大括号不匹配任何文件。在 v2.1.217 之前，具有许多大括号组的 `paths` 值在启动时导致 CLI 停滞或崩溃。243Claude Code 使用任何会超过预算的未展开模式，其字面大括号不匹配任何文件。在 v2.1.217 之前，具有许多大括号组的 `paths` 值在启动时使 CLI 停滞或崩溃。

271 244

272Glob 语法将 `[` 视为括号表达式的开始，例如 `[abc]`。一个包含 `[` 的模式无法读作括号表达式，例如 `photos [2024/**`，是无效的：它不匹配任何内容，规则的其他模式继续工作。要匹配文件名中的字面 `[`，将其转义为 `photos \[2024/**`。在 v2.1.207 之前，一个无效模式会导致 Read 工具对规则被评估的每个文件失败，而不是不匹配任何内容。245Glob 语法将 `[` 视为括号表达式的开始，例如 `[abc]`。具有无法读作括号表达式的 `[` 的模式，例如 `photos [2024/**`，是无效的：它不匹配任何内容，规则的其他模式继续工作。要匹配文件名中的字面 `[`，请将其转义为 `photos \[2024/**`。在 v2.1.207 之前，一个无效模式使 Read 工具对规则被评估的每个文件失败，而不是不匹配任何内容。

273 246

274<h4 id="share-rules-across-projects-with-symlinks">247<h4 id="share-rules-across-projects-with-symlinks">

275 使用符号链接跨项目共享规则248 使用符号链接在项目间共享规则

276</h4>249</h4>

277 250

278`.claude/rules/` 目录支持符号链接，因此你可以维护一组共享规则并将它们链接到多个项目中。符号链接被解析并正常加载，循环符号链接被检测并优雅处理。251`.claude/rules/` 目录支持符号链接，因此您可以维护一组共享规则并将它们链接到多个项目中。循环符号链接被检测并妥善处理。

279 252

280Claude Code 将其目标在工作目录外的符号链接视为 [外部导入](#import-additional-files)。链接的规则在你批准项目的外部导入后才加载，之后仅没有 [`paths` 字段](#path-specific-rules) 的规则加载。Claude Code 仅在项目内存文件使用 `@path` 导入工作目录外的文件时要求该批准，而不是仅针对符号链接。要加载共享规则而不需要该批准，将它们保持在 [`~/.claude/rules/`](#user-level-rules) 中，它们适用于你机器上的每个项目。253Claude Code 将其目标在工作目录外的符号链接视为 [external import](#import-additional-files)。链接的规则不加载，直到您批准项目的外部导入，之后仅加载没有 [`paths` 字段](#path-specific-rules) 的规则。Claude Code 仅当项目内存文件使用 `@path` 导入工作目录外的文件时才要求该批准，而不是仅针对符号链接。要加载共享规则而不需要该批准，请将它们保存在 [`~/.claude/rules/`](#user-level-rules) 中，它们适用于您机器上的每个项目。

281 254

282此示例链接共享目录和单个文件：255此示例链接共享目录和单个文件：

283 256

290 用户级规则263 用户级规则

291</h4>264</h4>

292 265

293`~/.claude/rules/` 中的个人规则适用于你机器上的每个项目。使用它们来处理不是项目特定的偏好：266`~/.claude/rules/` 中的个人规则适用于您机器上的每个项目。使用它们来处理不是项目特定的偏好：

294 267

295```text theme={null}268```text theme={null}

296~/.claude/rules/269~/.claude/rules/

297├── preferences.md # 你的个人编码偏好270├── preferences.md # Your personal coding preferences

298└── workflows.md # 你的首选工作流271└── workflows.md # Your preferred workflows

299```272```

300 273

301用户级规则在项目规则之前加载，给予项目规则更高的优先级。274用户级规则在项目规则之前加载，给予项目规则更高的优先级。

304 为大型团队管理 CLAUDE.md277 为大型团队管理 CLAUDE.md

305</h3>278</h3>

306 279

307对于在团队中部署 Claude Code 的组织，你可以集中指令并控制加载哪些 CLAUDE.md 文件。280对于在团队中部署 Claude Code 的组织，您可以集中指令并控制加载哪些 CLAUDE.md 文件。

308 281

309<h4 id="deploy-organization-wide-claude-md">282<h4 id="deploy-organization-wide-claude-md">

310 部署组织范围的 CLAUDE.md283 部署组织范围的 CLAUDE.md

311</h4>284</h4>

312 285

313组织可以部署一个集中管理的 CLAUDE.md，适用于机器上的所有用户。此文件不能被个人设置排除。286组织可以部署一个集中管理的 CLAUDE.md，适用于机器上的所有用户。此文件无法通过个人设置排除。

314 287

315<Steps>288<Steps>

316 <Step title="在托管策略位置创建文件">289 <Step title="在托管策略位置创建文件">

319 * Windows: `C:\Program Files\ClaudeCode\CLAUDE.md`292 * Windows: `C:\Program Files\ClaudeCode\CLAUDE.md`

320 </Step>293 </Step>

321 294

322 <Step title="使用你的配置管理系统部署">295 <Step title="使用您的配置管理系统部署">

323 使用 MDM、Group Policy、Ansible 或类似工具在开发者机器上分发文件。有关其他组织范围配置选项，请参阅 [托管设置](/docs/zh-CN/managed-settings)。296 使用 MDM、Group Policy、Ansible 或类似工具在开发者机器中分发文件。有关其他组织范围配置选项，请参阅 [managed settings](/docs/zh-CN/managed-settings)。

324 </Step>297 </Step>

325</Steps>298</Steps>

326 299

327`claudeMd` 键让你将托管 CLAUDE.md 内容直接放入 `managed-settings.json` 中，而不是部署单独的文件。300`claudeMd` 键允许您将托管 CLAUDE.md 内容直接放入 `managed-settings.json` 中，而不是部署单独的文件。

328 301

329**范围**：机器上的每个 Claude Code 会话，在每个存储库中。对于存储库特定的指导，改为提交项目 CLAUDE.md。302**范围**：机器上的每个 Claude Code 会话，在每个存储库中。对于存储库特定的指导，改为提交项目 CLAUDE.md。

330 303

340}313}

341```314```

342 315

343托管 CLAUDE.md 和 [托管设置](/docs/zh-CN/managed-settings) 服务于不同的目的。使用设置进行技术强制，使用 CLAUDE.md 进行行为指导：316托管 CLAUDE.md 和 [managed settings](/docs/zh-CN/managed-settings) 服务于不同的目的。使用设置进行技术强制，使用 CLAUDE.md 进行行为指导：

344 317

345| 关注点 | 配置在 |318| 关注点 | 配置在 |

346| :-------------- | :------------------------------------------ |319| :-------------- | :------------------------------------------ |

351| 代码样式和质量指南 | 托管 CLAUDE.md |324| 代码样式和质量指南 | 托管 CLAUDE.md |

352| 数据处理和合规提醒 | 托管 CLAUDE.md |325| 数据处理和合规提醒 | 托管 CLAUDE.md |

353| Claude 的行为指令 | 托管 CLAUDE.md |326| Claude 的行为指令 | 托管 CLAUDE.md |

358 排除特定的 CLAUDE.md 文件331 排除特定的 CLAUDE.md 文件

359</h4>332</h4>

360 333

361在大型 monorepos 中，祖先 CLAUDE.md 文件可能包含与你的工作无关的指令。`claudeMdExcludes` 设置让你按路径或 glob 模式跳过特定文件。334在大型 monorepos 中，祖先 CLAUDE.md 文件可能包含与您的工作无关的指令。`claudeMdExcludes` 设置允许您按路径或 glob 模式跳过特定文件。

362 335

363此示例排除顶级 CLAUDE.md 和来自父文件夹的规则目录。将其添加到 `.claude/settings.local.json` 以使排除保持本地到你的机器：336此示例排除顶级 CLAUDE.md 和来自父文件夹的规则目录。将其添加到 `.claude/settings.local.json` 以使排除保持本地到您的机器：

364 337

365```json theme={null}338```json theme={null}

366{339{

371}344}

372```345```

373 346

374模式使用 glob 语法与绝对文件路径匹配。你可以在任何 [设置层](/docs/zh-CN/settings#where-settings-live) 配置 `claudeMdExcludes`：用户、项目、本地或托管策略。数组跨层合并。347模式使用 glob 语法与绝对文件路径匹配。您可以在任何 [settings layer](/docs/zh-CN/settings#where-settings-live) 配置 `claudeMdExcludes`：用户、项目、本地或托管策略。数组跨层合并。

348

349要排除您通过 [symlink](#share-rules-across-projects-with-symlinks) 到达的规则文件，无论文件还是其目录是链接，请针对任一路径编写模式：文件在 `.claude/rules/` 下的路径或其链接目标。匹配任一路径的模式排除文件。在 v2.1.239 之前，仅匹配链接目标的模式排除文件。

350

351托管策略 CLAUDE.md 文件无法排除。这确保组织范围指令始终适用，无论个人设置如何。

352

353<h2 id="agents-md">

354 AGENTS.md

355</h2>

356

357Claude Code 可以将 [`AGENTS.md`](/docs/zh-CN/glossary#agents-md) 作为您的项目说明读取，因此已为其他编码代理设置的存储库无需添加 `CLAUDE.md`、导入或设置即可工作。此表显示了存储库中指令文件的每种组合下 Claude 默认读取的内容：

358

359| 您的存储库有 | Claude 读取 |

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

361| 一个 `AGENTS.md`，且在您的工作目录或其上方没有 `CLAUDE.md` 或 `CLAUDE.local.md` | 您的 `AGENTS.md` |

362| 一个 `AGENTS.md` 和一个 `CLAUDE.md` 或 `CLAUDE.local.md` 在您的工作目录或其上方 | 仅您的 `CLAUDE.md` 文件 |

363| 一个已[导入 `AGENTS.md`](#share-one-file-with-other-coding-tools)的 `CLAUDE.md` | 您的 `CLAUDE.md`，通过导入包含 `AGENTS.md` |

364

365要更改默认值，例如让 Claude 始终读取两个文件、仅读取 `CLAUDE.md` 或仅读取您组织的托管说明，请[更改**项目说明**设置](#choose-which-instruction-files-load)。

366

367<Note>

368 直接读取 `AGENTS.md` 需要 Claude Code v2.1.277 或更高版本。在某些会话中，例如在 Amazon Bedrock 上或禁用遥测的会话中，Claude [无法读取 `AGENTS.md`](#when-agents-md-support-is-unavailable)，因此请[从 `CLAUDE.md` 中导入它](#share-one-file-with-other-coding-tools)。

369</Note>

370

371<h3 id="when-claude-code-reads-agents-md">

372 Claude Code 何时读取 AGENTS.md

373</h3>

374

375默认情况下，Claude 仅在您的工作目录或其上方没有 `CLAUDE.md` 时才读取 `AGENTS.md`。以下是此检查中计数的文件：

376

377* **计数，因此 Claude 读取它们而不是 `AGENTS.md`**：您的工作目录或其上方任何目录中的 `CLAUDE.md`、`.claude/CLAUDE.md` 或 `CLAUDE.local.md`

378* **不计数，并继续与 `AGENTS.md` 一起加载**：您的 `~/.claude/CLAUDE.md`、您组织的托管 `CLAUDE.md` 和 `.claude/rules/` 文件

379

380当没有计数时，以下是 Claude 读取的内容以及您如何判断：

381

382* **在会话开始时**：您的工作目录和其上方目录中的每个 `AGENTS.md` 和 `.claude/AGENTS.md`。在交互式会话中，您会看到一行，例如 `no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md` 在对话中

383* **当 Claude 在子目录中工作时**：当 Claude 使用 Read 工具打开该处的文件且该子目录没有三个 `CLAUDE.md` 文件中的任何一个时，子目录的 `AGENTS.md`

384* **在每个 `AGENTS.md` 内**：[`@path` 导入](#import-additional-files)被展开，[`claudeMdExcludes`](#exclude-specific-claude-md-files) 模式适用，[跳过项目说明](/docs/zh-CN/sub-agents#what-loads-at-startup)的子代理也会跳过这些文件

385* **不读取**：`AGENTS.local.md`、`AGENTS.override.md` 或 `.agents/` 目录下的任何内容

386

387<Note>

388 因为 `CLAUDE.local.md` 计数，在依赖 `AGENTS.md` 的项目中添加一个来保留您自己的未提交说明会停止 Claude 为您读取 `AGENTS.md`。要保留您的 `CLAUDE.local.md` 并仍然让 Claude 读取 `AGENTS.md`，请将**项目说明**设置为 [`claude-md-and-agents-md`](#choose-which-instruction-files-load)。

389</Note>

390

391<h3 id="choose-which-instruction-files-load">

392 选择加载哪些说明文件

393</h3>

394

395要更改 Claude 读取的文件，请在 Claude Code 会话中键入 `/config` 以打开设置面板，然后将**项目说明**设置为以下值之一：

396

397| 值 | Claude 读取的内容 |

398| :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

399| `claude-md-or-agents-md` | 您的 `CLAUDE.md` 文件，或当您的工作目录或其上方没有 `CLAUDE.md` 或 `CLAUDE.local.md` 时您的 `AGENTS.md` 文件。这是默认值 |

400| `claude-md-and-agents-md` | 您的 `CLAUDE.md` 和 `AGENTS.md` 文件一起，每个目录的 `CLAUDE.md` 文件首先，其 `AGENTS.md` 在之后。Claude Code 跳过已加载的 `AGENTS.md`，因此您的 `CLAUDE.md` 导入或符号链接到的 `AGENTS.md` 不会被读取两次 |

401| `claude-md` | 仅您的 `CLAUDE.md` 文件 |

402| `managed-only` | 仅您组织的托管 `CLAUDE.md` 和启动时的[自动内存](#auto-memory)。您的项目、本地和用户 `CLAUDE.md` 文件、您的 `.claude/rules/` 文件和每个 `AGENTS.md` 都被排除在外。当 Claude 读取该处的文件时，子目录的 `CLAUDE.md` 和 `.claude/rules/` 文件仍会加载，[路径范围规则](#path-specific-rules)仍会应用 |

403

404您也可以在设置文件中设置该值，而不是在 `/config` 中。在 [`pluginConfigs`](/docs/zh-CN/settings-reference#pluginconfigs) 中的内置 `agents-md` 插件的 ID 下添加它，在 `~/.claude/settings.json`、`--settings` 文件或[托管设置](/docs/zh-CN/managed-settings)中。Claude Code 在项目和本地设置文件中忽略它。此示例让 Claude 读取两个文件：

405

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

407{

408 "pluginConfigs": {

409 "agents-md@builtin": {

410 "options": { "instructionFiles": "claude-md-and-agents-md" }

411 }

412 }

413}

414```

415

416您的更改从您发送的下一条消息和每个新会话中应用。

417

418<h3 id="when-agents-md-support-is-unavailable">

419 当 AGENTS.md 支持不可用时

420</h3>

421

422在这些会话中，Claude 仅读取 `CLAUDE.md` 文件，**项目说明**不会出现在 `/config` 设置面板中：

423

424* 您使用的是 v2.1.277 之前的 Claude Code 版本

425* 您的会话不会[从 Anthropic 获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)，例如因为您使用 Amazon Bedrock 或其他第三方提供商，或您禁用了遥测。链接的部分有完整列表

426* 这是您[安装或升级](/docs/zh-CN/env-vars#first-session-after-an-install-or-upgrade)到具有 `AGENTS.md` 支持的版本后的第一个会话。Claude 从您的下一个会话开始读取 `AGENTS.md`

427* 您或您的组织设置了 [`disableAllHooks`](/docs/zh-CN/settings-reference#disableallhooks) 或 [`allowManagedHooksOnly`](/docs/zh-CN/settings-reference#allowmanagedhooksonly)，或您在 `/plugin` 中禁用了内置 `agents-md` 插件

428

429要在这些会话中向 Claude 提供您的 `AGENTS.md`，请[从 `CLAUDE.md` 中导入它](#share-one-file-with-other-coding-tools)。

430

431<h3 id="where-agents-md-differs-from-claude-md">

432 AGENTS.md 与 CLAUDE.md 的区别

433</h3>

375 434

376要通过 [符号链接](#share-rules-across-projects-with-symlinks) 到达的规则文件排除它，无论文件还是其目录是链接，针对任一路径编写模式：文件在 `.claude/rules/` 下的路径或其链接目标。匹配任一路径的模式排除文件。在 v2.1.239 之前，仅匹配链接目标的模式排除文件。435通过**项目说明**设置读取的 `AGENTS.md` 与 `CLAUDE.md` 在以下方面有所不同：

377 436

378托管策略 CLAUDE.md 文件不能被排除。这确保组织范围指令始终适用，无论个人设置如何。437| | `CLAUDE.md` | 通过设置读取的 `AGENTS.md` |

438| :--------------------------------------------------------------------------------------------------------------- | :------------------------------------------------ | :---------------------------------------------------------------------------------------------------------- |

439| `/memory` 和 `/context` 中的**内存文件**列表 | 已列出 | 未列出。要确认 Claude 读取了它，请查找默认值下的 [`AGENTS.md loaded` 行](#when-claude-code-reads-agents-md)，或询问 Claude 其项目说明说了什么 |

440| [`InstructionsLoaded` hooks](/docs/zh-CN/hooks#instructionsloaded) | 触发 | 不触发。它们照常为 `CLAUDE.md` 导入或符号链接到的 `AGENTS.md` 触发 |

441| 当设置了 [`CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD`](#load-from-additional-directories) 时，您使用 `--add-dir` 添加的目录 | 它们的 `CLAUDE.md` 加载 | 它们的 `AGENTS.md` 不加载 |

442| `@path` 导入工作目录外的文件 | Claude Code 要求您批准[外部导入](#import-additional-files) | 仅在您已为此项目批准外部导入时加载，无提示 |

443

444<h3 id="remove-an-earlier-agents-md-workaround">

445 删除早期的 AGENTS.md 解决方案

446</h3>

447

448如果您在 Claude Code 自行读取 `AGENTS.md` 之前设置它来读取 `AGENTS.md`，以下是对每个常见设置的处理方法：

449

450* **包含 `@AGENTS.md` 的 `CLAUDE.md`**：您可以保留它。保留导入永远不会让 Claude 读取 `AGENTS.md` 两次，无论您使用哪个**项目说明**值。如果 `CLAUDE.md` 不包含其他内容，请删除它，或如果您的某些会话[无法直接加载 `AGENTS.md`](#when-agents-md-support-is-unavailable)，请保留它。

451* **告诉 Claude 用词语读取 `AGENTS.md` 的 `CLAUDE.md`**：仅当 Claude 决定打开文件时，它才会看到 `AGENTS.md`。删除 `CLAUDE.md` 以便 Claude 直接读取 `AGENTS.md`，或用 `@AGENTS.md` 导入替换该句子。

452* **符号链接到 `AGENTS.md` 的 `CLAUDE.md`**：无，或删除符号链接。无论哪种方式，Claude 都会读取内容一次。

453* **打印 `AGENTS.md` 的 `SessionStart` hook**：删除它。一旦 Claude 直接读取 `AGENTS.md`，该 hook 会向上下文添加第二个副本。

454

455<h3 id="share-one-file-with-other-coding-tools">

456 与其他编码工具共享一个文件

457</h3>

458

459当 Claude 不直接读取您的 `AGENTS.md` 时，您仍然可以通过在其旁边的 `CLAUDE.md` 中放置 `@AGENTS.md` 导入来将其保留为每个工具共享的一个文件。当您的项目也有 `CLAUDE.md` 时、当您已将**项目说明**设置为 `claude-md` 时，或在[无法加载 `AGENTS.md`](#when-agents-md-support-is-unavailable)的会话中执行此操作。在导入下方添加任何 Claude 特定的说明，Claude 会先读取导入的文件，然后读取其余部分：

460

461```markdown CLAUDE.md theme={null}

462@AGENTS.md

463

464## Claude Code

465

466对 `src/billing/` 下的更改使用计划模式。

467```

468

469如果您不需要 Claude 特定的内容，符号链接也可以工作：

470

471```bash theme={null}

472ln -s AGENTS.md CLAUDE.md

473```

474

475该命令在成功时不打印任何输出。在选择符号链接而不是导入之前，请检查这些约束：

476

477* **编辑**：Claude 通过链接读取 `CLAUDE.md`，但 Edit 和 Write 工具[拒绝通过符号链接写入](/docs/zh-CN/errors#refusing-after-a-symlink-changed)，拒绝指示 Claude 编辑链接的目标 `AGENTS.md`

478* **Windows**：如果您或克隆存储库的任何人在 Windows 上工作，请改用 `@AGENTS.md` 导入。在那里创建符号链接需要管理员权限或开发人员模式，Git 会将提交的符号链接检出为纯文本文件，除非启用了 `core.symlinks`，这会使该克隆具有一行 `CLAUDE.md` 代替您的说明

479

480使用任一方法，在您的下一个会话中运行 `/context` 并确认 `CLAUDE.md` 出现在**内存文件**下。

481

482<h3 id="migrate-instructions-from-other-tools">

483 从其他工具迁移说明

484</h3>

485

486运行 [`/init`](/docs/zh-CN/commands) 会读取其他工具的说明文件并将相关部分合并到生成的 `CLAUDE.md` 中：

487

488* `.cursor/rules/` 或 `.cursorrules` 中的 Cursor 规则

489* `.github/copilot-instructions.md` 中的 Copilot 规则

490* 设置 `CLAUDE_CODE_NEW_INIT=1` 时：`AGENTS.md`、`.devin/rules/`、`.windsurf/rules/` 或 `.windsurfrules`，以及 `.clinerules`

491

492您也可以运行 [`/import`](/docs/zh-CN/commands) 将支持的编码代理的配置引入 Claude Code，这会将 `AGENTS.md` 等说明文件的一次性副本追加到匹配的 `CLAUDE.md`，并携带 MCP 服务器、命令、子代理和 skills。需要 Claude Code v2.1.213 或更高版本。

379 493

380<h2 id="auto-memory">494<h2 id="auto-memory">

381 自动记忆495 自动记忆

422}536}

423```537```

424 538

425该值必须是绝对路径或以 `~/` 开头。当在项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中设置时，Claude Code 在与[设置文件中的 hooks 相同的工作区信任规则](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder)下遵守它。539该值必须是绝对路径或以 `~/` 开头。

540

541当在项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中设置时，Claude Code 在与[设置文件中的 hooks 相同的工作区信任规则](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder)下遵守它。当 [`permissions.blockReadsOutsideWorkingDirectories`](/docs/zh-CN/settings-reference#permissions-blockreadsoutsideworkingdirectories) 开启时，Claude Code 不从[存储库提供的设置文件](/docs/zh-CN/permissions#when-your-local-settings-file-needs-trust)选择的目录加载自动记忆，也不向其保存任何内容，无论该目录位于何处。

426 542

427目录包含一个 `MEMORY.md` 索引和每个记忆一个主题文件：543目录包含一个 `MEMORY.md` 索引和每个记忆一个主题文件：

428 544

468 使用 `/memory` 查看和编辑584 使用 `/memory` 查看和编辑

469</h2>585</h2>

470 586

471`/memory` 命令列出你的 CLAUDE.md、CLAUDE.local.md 和其他内存文件在用户和项目范围内的位置，包括尚不存在的文件的用户和项目 CLAUDE.md 条目。它还让你切换自动记忆开或关，并提供打开自动记忆文件夹的选项。选择任何文件在你的编辑器中打开它；选择一个尚不存在的文件会先创建它。要检查哪些文件实际加载到当前会话中，请运行 `/context`。587`/memory` 命令列出你的 CLAUDE.md、CLAUDE.local.md 和其他内存文件在用户和项目范围内的位置，包括尚不存在的文件的用户和项目 CLAUDE.md 条目。它还让你切换自动记忆开或关，并提供打开自动记忆文件夹的选项。选择任何文件在你的编辑器中打开它；选择一个尚不存在的文件会先创建它。要检查哪些 `CLAUDE.md` 和规则文件加载到当前会话中，请运行 `/context`。

472 588

473VS Code 等 GUI 编辑器在单独的窗口中打开文件，你可以在文件打开时继续使用会话。在 v2.1.216 之前，`/memory` 会等待你关闭文件后才响应。Vim 等终端编辑器会接管终端，直到你退出。589VS Code 等 GUI 编辑器在单独的窗口中打开文件，你可以在文件打开时继续使用会话。在 v2.1.216 之前，`/memory` 会等待你关闭文件后才响应。Vim 等终端编辑器会接管终端，直到你退出。

474 590

488 604

489要调试：605要调试：

490 606

491* 运行 `/context` 并检查 **Memory files** 下的列表，以验证你的 CLAUDE.md 和 CLAUDE.local.md 文件已加载。如果文件未列出，Claude 看不到它。使用 `/memory` 打开和编辑文件。607* 运行 `/context` 并检查 **Memory files** 下的列表，以验证你的 CLAUDE.md 和 CLAUDE.local.md 文件已加载。如果 `CLAUDE.md` 文件未列出，Claude 看不到它。`AGENTS.md` 仅在 `CLAUDE.md` 导入它时出现，而不是当 Claude [直接读取它](#where-agents-md-differs-from-claude-md) 时。使用 `/memory` 打开和编辑文件。

492* 检查相关 CLAUDE.md 是否在为你的会话加载的位置（参见 [选择 CLAUDE.md 文件的位置](#choose-where-to-put-claude-md-files)）。608* 检查相关 CLAUDE.md 是否在为你的会话加载的位置（参见 [选择 CLAUDE.md 文件的位置](#choose-where-to-put-claude-md-files)）。

493* 使指令更具体。"使用 2 空格缩进"比"格式化代码很好"效果更好。609* 使指令更具体。"使用 2 空格缩进"比"格式化代码很好"效果更好。

494* 查找跨 CLAUDE.md 文件的冲突指令。如果两个文件为相同行为提供不同的指导，Claude 可能会任意选择一个。610* 查找跨 CLAUDE.md 文件的冲突指令。如果两个文件为相同行为提供不同的指导，Claude 可能会任意选择一个。

498对于你想要在系统提示级别的指令，使用 [`--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)。614对于你想要在系统提示级别的指令，使用 [`--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)。

499 615

500<Tip>616<Tip>

501 使用 [`InstructionsLoaded` hook](/docs/zh-CN/hooks#instructionsloaded) 记录确切加载了哪些指令文件、何时加载以及为什么。这对于调试特定路径规则或子目录中的延迟加载文件很有用。617 使用 [`InstructionsLoaded` hook](/docs/zh-CN/hooks#instructionsloaded) 记录确切加载了哪些 `CLAUDE.md` 和规则文件、何时加载以及为什么。这对于调试特定路径规则或子目录中的延迟加载文件很有用。

502</Tip>618</Tip>

503 619

620<h3 id="my-agents-md-isn’t-loading">

621 我的 AGENTS.md 未加载

622</h3>

623

624如果你的存储库有 `AGENTS.md` 而 Claude 似乎不知道它说什么，通常原因是项目路径上某处有 `CLAUDE.md`。默认情况下，Claude 仅在你的工作目录或其上方没有 `CLAUDE.md` 或 `CLAUDE.local.md` 时读取 `AGENTS.md`。按顺序检查这些：

625

6261. 在你的工作目录或其上方的任何目录中查找 `CLAUDE.md`、`.claude/CLAUDE.md` 或 `CLAUDE.local.md`，除了你的 `~/.claude/CLAUDE.md`。如果你找到一个，Claude 会读取它而不是 `AGENTS.md`，除非你将 **Project instructions** 设置为 `claude-md-and-agents-md`。

6272. 运行 `claude --version` 并确认 v2.1.277 或更高版本。

6283. 检查你的会话是否是 [无法加载 `AGENTS.md`](#when-agents-md-support-is-unavailable) 的会话，例如第三方提供商上的会话或禁用遥测的会话。

6294. 在你的会话中输入 `/config` 以打开设置面板，并确认 **Project instructions** 未设置为 `claude-md` 或 `managed-only`。如果你根本看不到该设置，你的会话是 [无法加载 `AGENTS.md`](#when-agents-md-support-is-unavailable) 的会话。

630

631当 Claude 直接读取 `AGENTS.md` 时，你不会在 `/memory` 或 `/context` 中看到它，所以检查 `AGENTS.md loaded` 行或询问 Claude 其项目指令说什么。如果你想保留你找到的 `CLAUDE.md`，或你的会话无法加载 `AGENTS.md`，[添加一个 `CLAUDE.md` 在你的 `AGENTS.md` 旁边来导入它](#share-one-file-with-other-coding-tools)。

632

504<h3 id="i-don’t-know-what-auto-memory-saved">633<h3 id="i-don’t-know-what-auto-memory-saved">

505 我不知道自动记忆保存了什么634 我不知道自动记忆保存了什么

506</h3>635</h3>

mobile.md +9 −8

Details

6 6

7> 从您的手机使用 Claude 应用程序启动、监控和指导 Claude Code 任务，支持 iOS 和 Android。7> 从您的手机使用 Claude 应用程序启动、监控和指导 Claude Code 任务，支持 iOS 和 Android。

8 8

9Claude [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 会话的客户端，而不是代码运行的地方。从您的手机，您可以访问云中的[云会话](#start-and-monitor-cloud-sessions)、通过[远程控制](#continue-a-local-session-with-remote-control)运行在您自己机器上的会话，或通过 [Dispatch](/docs/zh-CN/desktop#sessions-from-dispatch) 访问桌面应用。9Claude [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 会话的客户端，而不是代码运行的地方。从您的手机，您可以访问云中的[云会话](#start-and-monitor-cloud-sessions)和[项目](/docs/zh-CN/claude-projects)，通过[远程控制](#continue-a-local-session-with-remote-control)运行在您自己机器上的会话，或通过 [Dispatch](/docs/zh-CN/desktop#sessions-from-dispatch) 访问桌面应用。

10 10

11<Note>11<Note>

12 Claude Code 没有单独的移动应用：云会话和远程控制都位于 Claude 应用中的 **Code** 选项卡中，Dispatch 是您在应用中向其发送消息的任务。12 Claude Code 没有单独的移动应用：云会话和远程控制都位于 Claude 应用中的 **Code** 选项卡中，Dispatch 是您在应用中向其发送消息的任务。

21 为 [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 或 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) 安装 Claude 应用程序。在 iPad 上，安装相同的 iOS 应用程序。21 为 [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 或 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) 安装 Claude 应用程序。在 iPad 上，安装相同的 iOS 应用程序。

22 22

23 <Tip>23 <Tip>

~~24 在 Claude Code 会话中运行 `/mobile` 以显示您可以扫描的下载二维码。`/ios` 和 `/android` 执行相同的操作。~~24 在 Claude Code 会话中运行 `/mobile` 以显示 [claude.ai/mobile](https://claude.ai/mobile) 的二维码，该二维码会打开适合您手机的应用商店。`/ios` 和 `/android` 执行相同的操作。

25 </Tip>25 </Tip>

26 </Step>26 </Step>

27 27

38 从您的手机工作38 从您的手机工作

39</h2>39</h2>

40 40

41从应用程序中，您可以启动云会话、驱动在您的计算机上运行的 Claude Code 会话，或向 Dispatch 消息传递任务。应用程序对所有三者都是相同的；它们在工作发生的位置上有所不同。41从应用程序中，您可以启动云会话、打开项目、驱动在您的计算机上运行的 Claude Code 会话，或向 Dispatch 消息传递任务。应用程序对所有这些都是相同的；它们在工作发生的位置上有所不同。

42 42

43| 功能 | 您连接到的内容 | 何时使用 |43| 功能 | 您连接到的内容 | 何时使用 |

~~44| :------------------------------------------------ | :-------------------------- | :--------------------------------------------------------------------- |~~44| :------------------------------------------------ | :------------------------- | :-------------------------------------------------------------------- |

46| [项目](/docs/zh-CN/claude-projects) | Claude 协调平行云会话作为线程的对话 | 您有一系列相关工作而不是一个任务，并且想要查看哪些线程已完成或需要您。 |

48 49

49如果您的计算机将关闭，请使用云会话，它们在云中运行，并在您的笔记本电脑关闭后继续运行。远程控制和 Dispatch 驱动您自己的机器，因此它需要保持打开状态并运行 Claude Code 或桌面应用程序。如果您的机器在远程控制会话期间进入睡眠状态，Claude Code 会在机器重新上线时重新连接。50如果您的计算机将关闭，请使用云会话或项目，它们在云中运行，并在您的笔记本电脑关闭后继续运行。远程控制和 Dispatch 驱动您自己的机器，因此它需要保持打开状态并运行 Claude Code 或桌面应用程序。如果您的机器在远程控制会话期间进入睡眠状态，Claude Code 会在机器重新上线时重新连接。

50 51

51有关更完整的比较，请参阅[当您远离终端时工作](/docs/zh-CN/platforms#work-when-you-are-away-from-your-terminal)。52有关更完整的比较，请参阅[当您远离终端时工作](/docs/zh-CN/platforms#work-when-you-are-away-from-your-terminal)。

52 53

56 启动和监控云会话57 启动和监控云会话

57</h3>58</h3>

58 59

59Claude Code 网页版在云基础设施上运行任务，默认由 Anthropic 托管，因此会话在您放下手机后继续进行。从 Code 选项卡中，选择一个存储库和分支，描述任务，然后提交。会话在设备之间持久化：您在笔记本电脑上启动的任务已准备好从您的手机进行审查，您从手机启动的任务在您回到办公桌时正在等待。60云会话在云基础设施上运行任务，默认由 Anthropic 托管，因此会话在您放下手机后继续进行。从 Code 选项卡中，选择一个存储库和分支，描述任务，然后提交。会话在设备之间持久化：您在笔记本电脑上启动的任务已准备好从您的手机进行审查，您从手机启动的任务在您回到办公桌时正在等待。

60 61

61在应用程序中打开会话以检查进度、回答 Claude 的问题或将其引导到新的方向。您也可以告诉 Claude [监视拉取请求](/docs/zh-CN/claude-code-on-the-web#auto-fix-pull-requests)并在 CI 失败或审查评论到达时修复它们。要连接 GitHub 并设置您的环境，请按照[网页快速入门](/docs/zh-CN/web-quickstart)进行操作，并查看[Claude Code 网页版](/docs/zh-CN/claude-code-on-the-web)了解云会话可以执行的所有操作。62在应用程序中打开会话以检查进度、回答 Claude 的问题或将其引导到新的方向。您也可以告诉 Claude [监视拉取请求](/docs/zh-CN/claude-code-on-the-web#auto-fix-pull-requests)并在 CI 失败或审查评论到达时修复它们。要连接 GitHub 并设置您的环境，请按照[云快速入门](/docs/zh-CN/web-quickstart)进行操作，并查看[在云中使用 Claude Code](/docs/zh-CN/claude-code-on-the-web) 了解云会话可以执行的所有操作。

62 63

63<h3 id="continue-a-local-session-with-remote-control">64<h3 id="continue-a-local-session-with-remote-control">

64 使用远程控制继续本地会话65 使用远程控制继续本地会话

model-config.md +4 −4

Details

294 294

295* 云会话在[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)说明了该文件何时适用。云会话中的中途模型切换在请求的模型被允许列表排除时被拒绝。会话创建时的服务器端拒绝适用于[组织模型限制](#organization-model-restrictions)，而不是 `availableModels` 设置密钥。295* 云会话在[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` 列表非空时，服务器拒绝用户启动云会话的请求，该请求在列表排除的模型上。

296* Cowork 是 Claude 桌面应用中的代理工作选项卡，在 Claude Code 上运行其会话，但根据设计，不从 claude.ai 管理控制台接收服务器管理设置。托管设置文件在会话运行的地方存在时适用于 Cowork 会话；远程 Cowork 会话在 Anthropic 管理的 VM 上运行，其中不存在设备部署的文件。296* Cowork 是 Claude 桌面应用中的代理工作选项卡，在 Claude Code 上运行其会话，但根据设计，不从 claude.ai 管理控制台接收服务器管理设置。托管设置文件在会话运行的地方存在时适用于 Cowork 会话；远程 Cowork 会话在 Anthropic 管理的 VM 上运行，其中不存在设备部署的文件。

297* [第三方提供商](/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 或托管设置文件交付允许列表。297* [第三方提供商](/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 或托管设置文件交付允许列表。

298* 服务器管理交付还需要会话使用[符合条件的登录或密钥](/docs/zh-CN/server-managed-settings#platform-availability)进行身份验证。仅通过 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本生成密钥的舰队应通过 MDM 或托管设置文件交付允许列表。298* 服务器管理交付还需要会话使用[符合条件的登录或密钥](/docs/zh-CN/server-managed-settings#platform-availability)进行身份验证。仅通过 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本生成密钥的舰队应通过 MDM 或托管设置文件交付允许列表。

299* 桌面 Code 选项卡也托管[SSH 会话](/docs/zh-CN/desktop#ssh-sessions)，它们从运行的远程主机读取托管设置文件。请参阅[桌面托管设置](/docs/zh-CN/desktop#managed-settings)。299* 桌面 Code 选项卡也托管[SSH 会话](/docs/zh-CN/desktop#ssh-sessions)，它们从运行的远程主机读取托管设置文件。请参阅[桌面托管设置](/docs/zh-CN/desktop#managed-settings)。

300* claude.ai 和桌面应用中的模型选择器隐藏或灰显您的组织的允许列表排除的模型。选择器状态是用户的便利；强制执行发生在会话中。300* claude.ai 和桌面应用中的模型选择器隐藏或灰显您的组织的允许列表排除的模型。选择器状态是用户的便利；它不强制执行允许列表。

301 301

302<h3 id="default-model-behavior">302<h3 id="default-model-behavior">

303 默认模型行为303 默认模型行为

376 376

377当成员登录或使用自己的 API 密钥时，限制适用。组织范围的凭证，如组织服务密钥，不与用户绑定，因此限制不适用于它们。377当成员登录或使用自己的 API 密钥时，限制适用。组织范围的凭证，如组织服务密钥，不与用户绑定，因此限制不适用于它们。

378 378

379Claude Console 没有模型限制控制。没有 Claude Enterprise 计划的组织，包括其成员通过 Anthropic API 进行身份验证的组织，使用[托管设置](/docs/zh-CN/managed-settings)中的 [`availableModels`](#restrict-model-selection) 限制模型，添加 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 以覆盖默认选项。这些设置由 Claude Code 本身强制执行，而不是由服务器强制执行。379Claude Console 没有模型限制控制。没有 Claude Enterprise 计划的组织，包括其成员通过 Anthropic API 进行身份验证的组织，使用[托管设置](/docs/zh-CN/managed-settings)中的 [`availableModels`](#restrict-model-selection) 限制模型，添加 [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 以覆盖默认选项。[表面覆盖](#surface-coverage)说明了每个表面如何接收和强制执行这些设置。

380 380

381受限模型从 `/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.` 并且会话保持其当前模型。381受限模型从 `/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.` 并且会话保持其当前模型。

382 382

545 545

546* 当标记的类别没有回退模型时，例如 Opus 5 上的生物学标记，Claude Code 不显示提示，请求以拒绝结束。546* 当标记的类别没有回退模型时，例如 Opus 5 上的生物学标记，Claude Code 不显示提示，请求以拒绝结束。

547* 如果两个模型都标记相同的请求，您可以编辑提示并重试，或启动新会话。547* 如果两个模型都标记相同的请求，您可以编辑提示并重试，或启动新会话。

548* 在移动[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web) 会话上，不支持编辑和重试。切换模型，或从桌面浏览器或桌面应用继续会话。548* 在移动[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)会话上，不支持编辑和重试。切换模型，或从桌面浏览器或桌面应用继续会话。

549* 在[非交互模式](/docs/zh-CN/cli-reference#cli-flags)和无法显示提示的 SDK 集成中，标记的请求以拒绝结束轮次。549* 在[非交互模式](/docs/zh-CN/cli-reference#cli-flags)和无法显示提示的 SDK 集成中，标记的请求以拒绝结束轮次。

550* 当回退目标被 [`availableModels`](#restrict-model-selection) 阻止时，Claude Code 不显示提示。标记的请求以拒绝结束，与目标被阻止时的自动回退相同。550* 当回退目标被 [`availableModels`](#restrict-model-selection) 阻止时，Claude Code 不显示提示。标记的请求以拒绝结束，与目标被阻止时的自动回退相同。

551 551

monitoring-usage.md +36 −4

Details

122| `OTEL_LOG_USER_PROMPTS` | 启用用户提示内容的日志记录（默认值：禁用） | `1` 启用 |122| `OTEL_LOG_USER_PROMPTS` | 启用用户提示内容的日志记录（默认值：禁用） | `1` 启用 |

123| `OTEL_LOG_ASSISTANT_RESPONSES` | 在 `assistant_response` 事件上启用助手响应文本的日志记录（默认值：禁用）。未设置时，回退到 `OTEL_LOG_USER_PROMPTS` 的值。需要 Claude Code v2.1.193 或更高版本 | `1` 启用，`0` 保持编辑 |123| `OTEL_LOG_ASSISTANT_RESPONSES` | 在 `assistant_response` 事件上启用助手响应文本的日志记录（默认值：禁用）。未设置时，回退到 `OTEL_LOG_USER_PROMPTS` 的值。需要 Claude Code v2.1.193 或更高版本 | `1` 启用，`0` 保持编辑 |

124| `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` 启用 |124| `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` 启用 |

125| `OTEL_LOG_TOOL_CONTENT` | 启用跨度事件中工具输入和输出内容的日志记录（默认值：禁用）。需要[跟踪](#traces-beta)。内容在内容限制处截断（默认值：60 KB） | `1` 启用 |125| `OTEL_LOG_TOOL_CONTENT` | 启用 [`tool.output` 跨度事件](#tool-output-span-event)中工具内容的日志记录（默认值：禁用）。跨度属性在[其自己的门控](#new-context-gates)下携带工具内容。需要[跟踪](#traces-beta)。内容在内容限制处截断（默认值：60 KB） | `1` 启用 |

126| `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` 指针 |126| `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` 指针 |

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

286 286

287当 `OTEL_LOG_TOOL_CONTENT=1` 时，此跨度还记录一个 `tool.output` 跨度事件，其属性包含工具的输入和输出正文，在内容限制处截断（默认值：60 KB）每个属性。287<span id="tool-output-span-event" />**`tool.output` 跨度事件在 `claude_code.tool` 上**

288

289如果您设置 `OTEL_LOG_TOOL_CONTENT=1`，Read 和 Bash 调用可以在 `claude_code.tool` 跨度上记录 `tool.output` 跨度事件。Edit 和 Write 调用仅在您也设置 `OTEL_LOG_TOOL_DETAILS=1` 时才记录一个。该变量不限于这两个工具，因此请检查其[配置表中的行](#common-configuration-variables)以了解它在其他地方添加的参数。

290

291Claude Code 从工具调用的成功返回时写入此事件，因此引发错误的调用不记录任何内容，无论工具如何。在确实返回的调用中，它不为以下内容记录 `tool.output` 事件：

292

293* 对除 Read、Edit、Write 和 Bash 之外的任何工具的调用，包括 MCP 工具和 WebFetch

294* 返回除文件文本之外的任何内容的 Read，例如图像、PDF 或重新读取内容未更改的文件

295* Edit 或 Write 调用，除非您也设置 `OTEL_LOG_TOOL_DETAILS=1`

296

297该事件携带这些属性，每个属性在内容限制处截断（默认值：60 KB）。`由以下控制` 命名属性在 `OTEL_LOG_TOOL_CONTENT=1` 之上需要的变量，对于 Edit 和 Write，该变量控制事件本身而不是属性。

298

299| 属性 | 描述 | 由以下控制 |

300| -------------- | ------------------------------------- | ----------------------------------- |

301| `content` | Read 工具返回的文本，或 Write 调用被要求写入的文本 | `OTEL_LOG_TOOL_DETAILS` 用于 Write 工具 |

302| `output` | Bash 命令的组合输出，stderr 交错到 stdout | |

303| `diff` | Edit 工具应用的结构化补丁 | `OTEL_LOG_TOOL_DETAILS` |

304| `file_path` | Read、Edit 和 Write 工具的目标文件路径，重复同名的跨度属性 | `OTEL_LOG_TOOL_DETAILS` |

305| `bash_command` | Bash 工具的命令字符串 | `OTEL_LOG_TOOL_DETAILS` |

306

307父跨度的 `tool_name` 属性告诉您事件来自哪个工具。在内容限制处切割的属性伴随 `<attribute>_truncated` 和 `<attribute>_original_length`。

288 308

289**`claude_code.tool.blocked_on_user`**309**`claude_code.tool.blocked_on_user`**

290 310

325 345

346<span id="new-context-gates" />

347

326<Note>348<Note>

327 其他内容承载属性，例如 `new_context`、`system_prompt_preview`、`user_system_prompt`、`tool_input` 和 `response.model_output`，仅在启用详细的测试版跟踪时发出。它们不是稳定跨度架构的一部分。349 其他内容承载属性，例如 `new_context`、`system_prompt_preview`、`user_system_prompt`、`tool_input` 和 `response.model_output`，仅在启用详细的测试版跟踪时发出。它们不是稳定跨度架构的一部分。

328 350

351 `new_context` 上的门控取决于哪个跨度携带它，每个副本在内容限制处截断（默认值：60 KB）。在 `claude_code.tool` 跨度上，它携带该工具调用的结果，无论工具如何，并需要 `OTEL_LOG_TOOL_CONTENT=1`。在 `claude_code.interaction` 跨度上，它携带用户提示，在 `claude_code.llm_request` 跨度上，它携带该请求的新用户消息和工具结果。这两者都需要 `OTEL_LOG_USER_PROMPTS=1`。

352

329 `user_system_prompt` 另外需要 `OTEL_LOG_USER_PROMPTS=1`。它仅携带您通过 `systemPrompt` SDK 选项或 `--system-prompt` 和 `--append-system-prompt` 标志提供的系统提示文本，在内容限制处截断（默认值：60 KB），并且每个会话发出一次而不是每个请求。353 `user_system_prompt` 另外需要 `OTEL_LOG_USER_PROMPTS=1`。它仅携带您通过 `systemPrompt` SDK 选项或 `--system-prompt` 和 `--append-system-prompt` 标志提供的系统提示文本，在内容限制处截断（默认值：60 KB），并且每个会话发出一次而不是每个请求。

330</Note>354</Note>

331 355

876* `body_truncated`：当发生内联截断时为 `"true"`。在文件模式下和未发生截断时不存在。900* `body_truncated`：当发生内联截断时为 `"true"`。在文件模式下和未发生截断时不存在。

877* `model`：来自请求参数的模型标识符901* `model`：来自请求参数的模型标识符

878* `query_source`：发出请求的子系统（例如，`"compact"`）902* `query_source`：发出请求的子系统（例如，`"compact"`）

903* `request_body_id`：UUID，标识此尝试的请求主体。成功的 [`api_response_body` 事件](#api-response-body-event) 携带相同的值，因此您可以将响应与产生它的确切请求配对。需要 Claude Code v2.1.274 或更高版本

879 904

880<h4 id="api-response-body-event">905<h4 id="api-response-body-event">

881 API 响应主体事件906 API 响应主体事件

883 908

884当设置了 `OTEL_LOG_RAW_API_BODIES` 时，为每个成功的 API 响应记录。909当设置了 `OTEL_LOG_RAW_API_BODIES` 时，为每个成功的 API 响应记录。

885 910

911在文件模式下（`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 或更高版本。

912

886**事件名称**：`claude_code.api_response_body`913**事件名称**：`claude_code.api_response_body`

887 914

888**属性**：915**属性**：

898* `model`：模型标识符925* `model`：模型标识符

899* `query_source`：发出请求的子系统926* `query_source`：发出请求的子系统

900* `request_id`：来自响应的 `request-id` 标头的 Anthropic API 请求 ID，例如 `"req_011..."`。仅当 API 返回时存在。927* `request_id`：来自响应的 `request-id` 标头的 Anthropic API 请求 ID，例如 `"req_011..."`。仅当 API 返回时存在。

928* `request_body_id`：此响应回答的 [`api_request_body` 事件](#api-request-body-event) 的 `request_body_id`。需要 Claude Code v2.1.274 或更高版本

929* `message.id`：API 分配给响应的消息 ID，响应主体的 `id` 字段。需要 Claude Code v2.1.274 或更高版本

930* `message.uuid`：响应的最终记录条目的 UUID。与 `request_body_id` 一起，它将记录消息链接到其后面的请求和响应主体。需要 Claude Code v2.1.274 或更高版本

901 931

902<h4 id="tool-decision-event">932<h4 id="tool-decision-event">

903 工具决策事件933 工具决策事件

1524* OpenTelemetry 导出到您的后端是可选的，需要显式配置。有关 Anthropic 的单独操作遥测以及如何禁用它，请参阅 [数据使用](/docs/zh-CN/data-usage#telemetry-services)1554* OpenTelemetry 导出到您的后端是可选的，需要显式配置。有关 Anthropic 的单独操作遥测以及如何禁用它，请参阅 [数据使用](/docs/zh-CN/data-usage#telemetry-services)

1525* 原始文件内容和代码片段不包含在指标或事件中。Trace spans 是一个单独的数据路径：请参阅下面的 `OTEL_LOG_TOOL_CONTENT` 项目符号1555* 原始文件内容和代码片段不包含在指标或事件中。Trace spans 是一个单独的数据路径：请参阅下面的 `OTEL_LOG_TOOL_CONTENT` 项目符号

1526* 通过 OAuth 认证时，`user.email` 包含在遥测属性中，仅发送到您配置的 OTel 端点，永远不会发送到 Anthropic。如果这对您的组织是一个问题，请与您的遥测后端合作以过滤或编辑此字段1556* 通过 OAuth 认证时，`user.email` 包含在遥测属性中，仅发送到您配置的 OTel 端点，永远不会发送到 Anthropic。如果这对您的组织是一个问题，请与您的遥测后端合作以过滤或编辑此字段

1527* 默认情况下不收集用户提示内容。仅记录提示长度。要包含提示内容，请设置 `OTEL_LOG_USER_PROMPTS=1`1557* 默认情况下不收集用户提示内容。仅记录提示长度。要包含提示内容，请设置 `OTEL_LOG_USER_PROMPTS=1`。在详细的 beta 追踪下，此变量的作用范围更广：它还控制 [`new_context` span 属性](#new-context-gates)，该属性在 `claude_code.llm_request` span 上携带工具结果

1528* 默认情况下不收集助手响应文本。仅记录响应长度。要包含响应文本，请设置 `OTEL_LOG_ASSISTANT_RESPONSES=1`。与来自 Claude Code 的所有 OpenTelemetry 数据一样，响应文本仅发送到您配置的 OTel 端点，永远不会发送到 Anthropic。当此变量未设置时，`OTEL_LOG_USER_PROMPTS` 用作后备，因此如果您想要提示内容而不要响应内容，请设置 `OTEL_LOG_ASSISTANT_RESPONSES=0`1558* 默认情况下不收集助手响应文本。仅记录响应长度。要包含响应文本，请设置 `OTEL_LOG_ASSISTANT_RESPONSES=1`。与来自 Claude Code 的所有 OpenTelemetry 数据一样，响应文本仅发送到您配置的 OTel 端点，永远不会发送到 Anthropic。当此变量未设置时，`OTEL_LOG_USER_PROMPTS` 用作后备，因此如果您想要提示内容而不要响应内容，请设置 `OTEL_LOG_ASSISTANT_RESPONSES=0`

1529* 默认情况下不记录工具输入参数和参数。要包含它们，请设置 `OTEL_LOG_TOOL_DETAILS=1`。对于 Claude Desktop 的内置服务器，在 Claude Desktop 拥有的会话中，`tool_decision` 和 `tool_result` 携带 `mcp_server_name`/`mcp_tool_name` 对，即主机编写的名称而非参数内容，即使关闭该标志也是如此。此异常需要 Claude Code v2.1.214 或更高版本。此数据仅发送到您配置的 OTEL 端点，永远不会发送到 Anthropic。参数仍可能包含敏感值，因此请根据需要配置您的遥测后端以过滤或编辑这些属性。启用后：1559* 默认情况下不记录工具输入参数和参数。要包含它们，请设置 `OTEL_LOG_TOOL_DETAILS=1`。对于 Claude Desktop 的内置服务器，在 Claude Desktop 拥有的会话中，`tool_decision` 和 `tool_result` 携带 `mcp_server_name`/`mcp_tool_name` 对，即主机编写的名称而非参数内容，即使关闭该标志也是如此。此异常需要 Claude Code v2.1.214 或更高版本。此数据仅发送到您配置的 OTEL 端点，永远不会发送到 Anthropic。参数仍可能包含敏感值，因此请根据需要配置您的遥测后端以过滤或编辑这些属性。启用后：

1530 * `tool_result` 和 `tool_decision` 事件包含 `tool_parameters` 属性，其中包含 Bash 命令、MCP 服务器和工具名称以及技能名称。`full_command` 等字段以未截断的形式发出1560 * `tool_result` 和 `tool_decision` 事件包含 `tool_parameters` 属性，其中包含 Bash 命令、MCP 服务器和工具名称以及技能名称。`full_command` 等字段以未截断的形式发出

1531 * `tool_result` 事件另外包含 `tool_input` 属性，其中包含文件路径、URL、搜索模式和其他参数。超过 512 个字符的单个值被截断，总数限制为约 4 K 字符1561 * `tool_result` 事件另外包含 `tool_input` 属性，其中包含文件路径、URL、搜索模式和其他参数。超过 512 个字符的单个值被截断，总数限制为约 4 K 字符

1532 * `user_prompt` 事件包含自定义、插件和 MCP 命令的逐字 `command_name`1562 * `user_prompt` 事件包含自定义、插件和 MCP 命令的逐字 `command_name`

1533 * Trace spans 包含相同的 `tool_input` 属性和输入派生属性（如 `file_path`），与 `tool_input` 的截断方式相同1563 * Trace spans 包含相同的 `tool_input` 属性和输入派生属性（如 `file_path`），与 `tool_input` 的截断方式相同

1534* 默认情况下，trace spans 中不记录工具输入和输出内容。要包含它，请设置 `OTEL_LOG_TOOL_CONTENT=1`。启用后，span 事件包含完整的工具输入和输出内容，在内容限制处截断（默认为 60 KB）每个属性。这可能包括 Read 工具结果中的原始文件内容和 Bash 命令输出。根据需要配置您的遥测后端以过滤或编辑这些属性1564* 默认情况下，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)。根据需要配置您的遥测后端以过滤或编辑这些属性

1535* 默认情况下不记录原始 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 如何传递主体：1565* 默认情况下不记录原始 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 如何传递主体：

1536 * 使用 `=1` 时，Claude Code 为每个 API 调用发出 `api_request_body` 和 `api_response_body` 日志事件。事件的 `body` 属性携带 JSON 序列化的有效负载，在内容限制处截断（默认为 60 KB）1566 * 使用 `=1` 时，Claude Code 为每个 API 调用发出 `api_request_body` 和 `api_response_body` 日志事件。事件的 `body` 属性携带 JSON 序列化的有效负载，在内容限制处截断（默认为 60 KB）

1537 * 使用 `=file:<dir>` 时，Claude Code 将未截断的主体写入该目录下的 `.request.json` 和 `.response.json` 文件，事件携带 `body_ref` 路径而不是内联主体。使用日志收集器或 sidecar 传输目录，而不是通过遥测流1567 * 使用 `=file:<dir>` 时，Claude Code 将未截断的主体写入该目录下的 `.request.json` 和 `.response.json` 文件，事件携带 `body_ref` 路径而不是内联主体。使用日志收集器或 sidecar 传输目录，而不是通过遥测流

1538 1568

1569 对于每个成功的响应，Claude Code 还会在该目录中的 `index.jsonl` 中追加一行，将响应文件链接到生成它的请求文件以及它成为的记录消息。每行不包含任何消息内容，[API 响应主体事件](#api-response-body-event)部分列出了其字段。索引文件需要 Claude Code v2.1.274 或更高版本

1570

1539<h2 id="monitor-claude-code-on-amazon-bedrock">1571<h2 id="monitor-claude-code-on-amazon-bedrock">

1540 在 Amazon Bedrock 上监控 Claude Code1572 在 Amazon Bedrock 上监控 Claude Code

1541</h2>1573</h2>

output-styles.md +4 −3

Details

34 34

35通过以下方式之一选择样式：35通过以下方式之一选择样式：

36 36

37* **`/output-style` 命令**：运行 `/output-style <style>` 来切换，例如 `/output-style concise`。不带参数时，该命令列出你可以选择的样式并标记当前样式。Claude Code 将你的选择保存到[本地项目级别](/docs/zh-CN/settings)的 `.claude/settings.local.json`。

39 该命令也适用于[非交互模式](/docs/zh-CN/headless)和 Agent SDK 会话，以及来自移动应用或网页的[远程控制](/docs/zh-CN/remote-control#limitations)，其中你只能列出和选择[内置样式](#built-in-output-styles)。需要 Claude Code v2.1.269 或更高版本。

37* **Terminal**：运行 `/config` 并选择**输出样式**从菜单中选择一种样式。Claude Code 将你的选择保存到[本地项目级别](/docs/zh-CN/settings)的 `.claude/settings.local.json`。40* **Terminal**：运行 `/config` 并选择**输出样式**从菜单中选择一种样式。Claude Code 将你的选择保存到[本地项目级别](/docs/zh-CN/settings)的 `.claude/settings.local.json`。

38* **VS Code extension**：使用 `/` 打开[命令菜单](/docs/zh-CN/vs-code#use-the-prompt-box)并选择**输出样式**来选择一种样式，包括你的自定义样式。Claude Code 将你的选择保存到 `.claude/settings.local.json`，这是终端菜单写入的同一个文件。需要 Claude Code v2.1.257 或更高版本。41* **VS Code extension**：使用 `/` 打开[命令菜单](/docs/zh-CN/vs-code#use-the-prompt-box)并选择**输出样式**来选择一种样式，包括你的自定义样式。Claude Code 将你的选择保存到 `.claude/settings.local.json`，这是终端菜单写入的同一个文件。需要 Claude Code v2.1.257 或更高版本。

39* **Desktop app**：在设置文件中设置 `outputStyle` 字段，例如 `.claude/settings.local.json`，这是终端菜单写入的文件。当你在那里运行 `/config` 时，Claude Code [打开**设置 > Claude Code**](/docs/zh-CN/desktop#what%E2%80%99s-not-available-in-desktop)而不是菜单。42* **Desktop app**：在设置文件中设置 `outputStyle` 字段，例如 `.claude/settings.local.json`，这是终端菜单写入的文件。当你在那里运行 `/config` 时，Claude Code [打开**设置 > Claude Code**](/docs/zh-CN/desktop#what%E2%80%99s-not-available-in-desktop)而不是菜单。

40 43

~~41<Note>独立的 `/output-style` 命令在 v2.1.73 中已弃用，在 v2.1.91 中被移除。使用 `/config` 或直接编辑 `outputStyle` 设置。</Note>~~

43要在不使用菜单的情况下设置样式，直接编辑设置文件中的 `outputStyle` 字段：44要在不使用菜单的情况下设置样式，直接编辑设置文件中的 `outputStyle` 字段：

44 45

45```json theme={null}46```json theme={null}

90 </Step>91 </Step>

91 92

92 <Step title="切换到你的样式">93 <Step title="切换到你的样式">

93 在终端中运行 `/config` 并在**输出样式**下选择你的样式。Claude 从你的下一条消息开始使用新样式。在终端中，Claude Code 在启动时读取样式文件，所以如果你在运行会话期间创建或编辑一个样式文件，请重启 Claude Code 以获取更改。94 在终端中运行 `/output-style <style>`，或运行 `/config` 并在**输出样式**下选择你的样式。Claude 从你的下一条消息开始使用新样式。在终端中，Claude Code 在启动时读取样式文件，所以如果你在运行会话期间创建或编辑一个样式文件，请重启 Claude Code 以获取更改。

94 </Step>95 </Step>

95</Steps>96</Steps>

96 97

overview.md +4 −4

Details

121 </Tab>121 </Tab>

122 122

123 <Tab title="Web">123 <Tab title="Web">

124 在浏览器中运行 Claude Code，无需本地设置。启动长时间运行的任务，完成后再检查，处理你本地没有的仓库，或并行运行多个任务。可在桌面浏览器和 [Claude iOS 和 Android 应用](/docs/zh-CN/mobile)中使用。124 在浏览器中运行 Claude Code，无需本地设置。启动长时间运行的任务，完成后再检查，处理你本地没有的仓库，或并行运行多个任务。对于较长的工作，创建一个[项目](/docs/zh-CN/claude-projects)，让 Claude 为你协调并行会话。可在桌面浏览器和 [Claude iOS 和 Android 应用](/docs/zh-CN/mobile)中使用。

125 125

126 在 [claude.ai/code](https://claude.ai/code) 开始编码。126 在 [claude.ai/code](https://claude.ai/code) 开始编码。

127 127

173 </Accordion>173 </Accordion>

174 174

175 <Accordion title="使用说明、skills 和 hooks 进行自定义" icon="sliders">175 <Accordion title="使用说明、skills 和 hooks 进行自定义" icon="sliders">

176 [`CLAUDE.md`](/docs/zh-CN/memory) 是一个 markdown 文件，你可以将其添加到项目根目录，Claude Code 会在每个会话开始时读取它。使用它来设置编码标准、架构决策、首选库和审查清单。Claude 还会在工作时构建[自动内存](/docs/zh-CN/memory#auto-memory)，保存学习内容，跨会话使用，无需你编写任何内容。176 [`CLAUDE.md`](/docs/zh-CN/memory) 是一个 markdown 文件，你可以将其添加到项目根目录，Claude Code 会在每个会话开始时读取它。使用它来设置编码标准、架构决策、首选库和审查清单。如果你的存储库已经有一个用于其他编码代理的 `AGENTS.md`，Claude Code [可以自己读取它](/docs/zh-CN/memory#agents-md)或与 `CLAUDE.md` 一起读取。Claude 还会在工作时构建[自动内存](/docs/zh-CN/memory#auto-memory)，保存学习内容，跨会话使用，无需你编写任何内容。

177 177

178 创建 [skills](/docs/zh-CN/skills) 来打包你的团队可以共享的可重复工作流，如 `/review-pr` 或 `/deploy-staging`。178 创建 [skills](/docs/zh-CN/skills) 来打包你的团队可以共享的可重复工作流，如 `/review-pr` 或 `/deploy-staging`。

179 179

231除了上面的[终端](/docs/zh-CN/quickstart)、[VS Code](/docs/zh-CN/vs-code)、[JetBrains](/docs/zh-CN/jetbrains)、[桌面](/docs/zh-CN/desktop)和[网络](/docs/zh-CN/claude-code-on-the-web)界面外，Claude Code 还与 CI/CD、聊天和浏览器工作流集成：231除了上面的[终端](/docs/zh-CN/quickstart)、[VS Code](/docs/zh-CN/vs-code)、[JetBrains](/docs/zh-CN/jetbrains)、[桌面](/docs/zh-CN/desktop)和[网络](/docs/zh-CN/claude-code-on-the-web)界面外，Claude Code 还与 CI/CD、聊天和浏览器工作流集成：

232 232

233| 我想要... | 最佳选项 |233| 我想要... | 最佳选项 |

234| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |234| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |

235| 从我的手机或另一台设备继续本地会话 | [远程控制](/docs/zh-CN/remote-control) |235| 从我的手机或另一台设备继续本地会话 | [远程控制](/docs/zh-CN/remote-control) |

236| 从 Telegram、Discord、iMessage 或我自己的 webhook 推送事件到会话中 | [Channels](/docs/zh-CN/channels) |236| 从 Telegram、Discord、iMessage 或我自己的 webhook 推送事件到会话中 | [Channels](/docs/zh-CN/channels) |

237| 在本地启动任务，在移动设备上继续 | [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-web)，然后使用 [Claude 移动应用](/docs/zh-CN/mobile) |237| 在本地启动任务，在移动设备上继续 | [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)，然后使用 [Claude 移动应用](/docs/zh-CN/mobile) |

238| 按定期计划运行 Claude | [Routines](/docs/zh-CN/routines) 或[桌面计划任务](/docs/zh-CN/desktop-scheduled-tasks) |238| 按定期计划运行 Claude | [Routines](/docs/zh-CN/routines) 或[桌面计划任务](/docs/zh-CN/desktop-scheduled-tasks) |

239| 自动化 PR 审查和问题分类 | [GitHub Actions](/docs/zh-CN/github-actions) 或 [GitLab CI/CD](/docs/zh-CN/gitlab-ci-cd) |239| 自动化 PR 审查和问题分类 | [GitHub Actions](/docs/zh-CN/github-actions) 或 [GitLab CI/CD](/docs/zh-CN/gitlab-ci-cd) |

240| 在每个 PR 上获得自动代码审查 | [GitHub Code Review](/docs/zh-CN/code-review) |240| 在每个 PR 上获得自动代码审查 | [GitHub Code Review](/docs/zh-CN/code-review) |

permission-modes.md +8 −6

Details

247 使用 plan mode 在编辑前进行分析247 使用 plan mode 在编辑前进行分析

248</h2>248</h2>

249 249

250Plan mode 告诉 Claude 研究并提议更改而不进行编辑。Claude 读取文件、运行 shell 命令进行探索并编写计划，但不编辑您的源代码。除了在[绕过权限可用](#skip-all-checks-with-bypasspermissions-mode)的会话中，编辑保持阻止状态，直到您批准计划。250Plan mode 告诉 Claude 研究并提议更改而不进行编辑。Claude 读取文件、运行 shell 命令进行探索并编写计划，但不编辑您的源代码。除了在[绕过权限可用](#skip-all-checks-with-bypasspermissions-mode)的交互式终端会话中，编辑保持阻止状态，直到您批准计划。

251 251

252当[自动模式](/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 中，没有绕过权限的会话为只读集合外的每个命令提示，无论自动模式是否可用。252当[自动模式](/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 中，没有绕过权限的会话为只读集合外的每个命令提示，无论自动模式是否可用。

253 253

254通过按 `Shift+Tab` 或在单个提示前加上 `/plan` 进入 plan mode。您也可以从 CLI 启动 plan mode：254通过按 `Shift+Tab` 或在单个提示前加上 `/plan` 进入 plan mode。您也可以从 CLI 启动 plan mode：

255 255

545* [`isolatePeerMachines`](/docs/zh-CN/settings-reference#isolatepeermachines)批准提示用于发送到超出此机器的会话的消息仍然出现。545* [`isolatePeerMachines`](/docs/zh-CN/settings-reference#isolatepeermachines)批准提示用于发送到超出此机器的会话的消息仍然出现。

546* 当没有[`crossSessionInbound`](/docs/zh-CN/cross-session-messaging#control-inbound-messages)值适用时，Claude Code 会从您的另一个会话中的入站消息保留以供您批准，仅当发送会话将自己标识为也绕过权限提示时才无需询问即可传递。如果您在保留消息时离开权限模式，Claude Code 会重新应用入站规则，并传递任何现在接受的保留消息。546* 当没有[`crossSessionInbound`](/docs/zh-CN/cross-session-messaging#control-inbound-messages)值适用时，Claude Code 会从您的另一个会话中的入站消息保留以供您批准，仅当发送会话将自己标识为也绕过权限提示时才无需询问即可传递。如果您在保留消息时离开权限模式，Claude Code 会重新应用入站规则，并传递任何现在接受的保留消息。

547 547

548在具有可用绕过权限的会话中，Claude Code 也不强制执行[计划模式的](#analyze-before-you-edit-with-plan-mode)块。Claude 仍然被指示在不编辑的情况下进行计划，但它在计划期间尝试的文件编辑或 shell 命令无需提示即可运行。显式[询问规则](/docs/zh-CN/permissions#manage-permissions)和针对[关键路径](#critical-paths)的 `rm` 和 `rmdir` 删除仍会提示。548在具有可用绕过权限的交互式终端会话中，Claude Code 也不强制执行[计划模式的](#analyze-before-you-edit-with-plan-mode)块。Claude 仍然被指示在不编辑的情况下进行计划，但它在计划期间尝试的文件编辑或 shell 命令无需提示即可运行。显式[询问规则](/docs/zh-CN/permissions#manage-permissions)和针对[关键路径](#critical-paths)的 `rm` 和 `rmdir` 删除仍会提示。

549

550计划模式在 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` 稍后可选。

549 551

550<Warning>552<Warning>

551 仅在隔离环境（如容器、虚拟机或没有互联网访问的开发容器）中使用此模式，其中 Claude Code 无法损害您的主机系统。553 仅在隔离环境（如容器、虚拟机或没有互联网访问的开发容器）中使用此模式，其中 Claude Code 无法损害您的主机系统。

581 受保护的路径583 受保护的路径

582</h2>584</h2>

583 585

584对一小组路径的写入永远不会自动批准，唯一的例外是 `bypassPermissions` 模式，以及可使用[绕过权限](#skip-all-checks-with-bypasspermissions-mode)的 plan 模式会话。这可以防止意外损坏存储库状态和 Claude 自己的配置。586对一小组路径的写入永远不会自动批准，唯一的例外是 `bypassPermissions` 模式，以及可使用[绕过权限](#skip-all-checks-with-bypasspermissions-mode)的 plan 模式交互式终端会话。这可以防止意外损坏存储库状态和 Claude 自己的配置。

585 587

586| 模式 | 受保护路径写入 |588| 模式 | 受保护路径写入 |

587| :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------- |589| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |

588| `default`、`acceptEdits` | 提示 |590| `default`、`acceptEdits` | 提示 |

589| `plan` | 在[绕过权限](#skip-all-checks-with-bypasspermissions-mode)可用的会话中允许。否则，当[自动模式](#eliminate-prompts-with-auto-mode)在规划期间可用时路由到分类器，当它不可用时提示 |591| `plan` | 在[绕过权限](#skip-all-checks-with-bypasspermissions-mode)可用的交互式终端会话中允许。否则，当[自动模式](#eliminate-prompts-with-auto-mode)在规划期间可用时路由到分类器，当它不可用时提示 |

591| `dontAsk` | 拒绝 |593| `dontAsk` | 拒绝 |

592| `bypassPermissions` | 允许 |594| `bypassPermissions` | 允许 |

permissions.md +16 −3

Details

333 333

334没有文件在其后的目标不被检查：`/dev/null`、文件描述符形式如 `2>&1` 和 `<&3`，以及 here-docs 和 here-strings。334没有文件在其后的目标不被检查：`/dev/null`、文件描述符形式如 `2>&1` 和 `<&3`，以及 here-docs 和 here-strings。

335 335

336Claude Code 也检查 `tee` 命令写入的文件，包括在管道中，如 `make | tee build.log`。检查涵盖您的 `Edit` allow 和 deny 规则、[受保护的路径](/docs/zh-CN/permission-modes#protected-paths)和[工作目录](#working-directories)。像 `Bash(tee *)` 这样的 allow 规则不涵盖工作目录外的目标。Claude Code 在 v2.1.269 及更高版本中检查 `tee` 目标。

337

336<h3 id="powershell">338<h3 id="powershell">

337 PowerShell339 PowerShell

338</h3>340</h3>

370Claude Code 仅根据 `Edit(path)` 和 `Read(path)` 规则检查文件权限。如果您为 `Write`、`NotebookEdit`、`Glob` 或旧版 `MultiEdit` 工具编写路径规则，Claude Code 接受该规则但从不查询它，并在启动时[警告](/docs/zh-CN/errors#is-not-matched-by-file-permission-checks)，除了在 `--allowedTools` 中传递的 `Glob` 规则。使用 `Edit(docs/**)` 代替 `Write(docs/**)`、`NotebookEdit(docs/**)` 或 `MultiEdit(docs/**)`，以及 `Read(docs/**)` 代替 `Glob(docs/**)`。Claude Code 不会警告没有路径的工具名称规则，如 `Write` 的 deny 规则；它在任何地方在工具级别匹配该规则。需要 Claude Code v2.1.210 或更高版本。372Claude Code 仅根据 `Edit(path)` 和 `Read(path)` 规则检查文件权限。如果您为 `Write`、`NotebookEdit`、`Glob` 或旧版 `MultiEdit` 工具编写路径规则，Claude Code 接受该规则但从不查询它，并在启动时[警告](/docs/zh-CN/errors#is-not-matched-by-file-permission-checks)，除了在 `--allowedTools` 中传递的 `Glob` 规则。使用 `Edit(docs/**)` 代替 `Write(docs/**)`、`NotebookEdit(docs/**)` 或 `MultiEdit(docs/**)`，以及 `Read(docs/**)` 代替 `Glob(docs/**)`。Claude Code 不会警告没有路径的工具名称规则，如 `Write` 的 deny 规则；它在任何地方在工具级别匹配该规则。需要 Claude Code v2.1.210 或更高版本。

371 373

372<Warning>374<Warning>

373 Read 和 Edit deny 规则适用于 Claude 的内置文件工具、Claude Code 在 Bash 中识别的文件命令（如 `cat`、`head`、`tail` 和 `sed`）以及 Bash [重定向](#redirections)的目标（如 `> file` 和 `< file`）。它们不适用于读取文件而不命名它们的命令，如从保存文件的目录运行的 `grep -r pattern .`，或间接读取或写入文件的任意子进程，如打开文件本身的 Python 或 Node 脚本。对于阻止所有进程访问路径的 OS 级别强制执行，请[启用沙箱](/docs/zh-CN/sandboxing)。375 Read 和 Edit deny 规则适用于 Claude 的内置文件工具、Claude Code 在 Bash 中识别的文件命令（如 `cat`、`head`、`tail`、`sed` 和 `tee`）以及 Bash [重定向](#redirections)的目标（如 `> file` 和 `< file`）。它们不适用于读取文件而不命名它们的命令，如从保存文件的目录运行的 `grep -r pattern .`，或间接读取或写入文件的任意子进程，如打开文件本身的 Python 或 Node 脚本。对于阻止所有进程访问路径的 OS 级别强制执行，请[启用沙箱](/docs/zh-CN/sandboxing)。

374</Warning>376</Warning>

375 377

376Read 和 Edit 规则都使用[gitignore](https://git-scm.com/docs/gitignore)模式语法，具有四种不同的模式类型；对于单段目录模式，匹配深度也取决于规则类型，本节后面描述：378Read 和 Edit 规则都使用[gitignore](https://git-scm.com/docs/gitignore)模式语法，具有四种不同的模式类型；对于单段目录模式，匹配深度也取决于规则类型，本节后面描述：

454 456

455其路径不可用作 gitignore 模式的 deny 或 ask 规则仍然保护该确切路径。其模式不可用的 allow 规则不批准任何内容。457其路径不可用作 gitignore 模式的 deny 或 ask 规则仍然保护该确切路径。其模式不可用的 allow 规则不批准任何内容。

456 458

459一个 deny 或 ask 模式，其路径以 `!` 开头是 gitignore 否定。它从其前面列出的 `path` 或 `./path` 规则中切割出它匹配的路径。在一个设置文件的 `deny` 列表中，`Read(*.env)` 后跟 `Read(!sample.env)` 阻止名称以 `.env` 结尾的每个文件在任何深度，除了名为 `sample.env` 的文件。首先列出的 `!` 规则切割不出任何内容。

460

461切割范围仅到达来自同一源的规则。项目设置或 `--disallowedTools` 中的 `Read(!.env)` 不会取消来自托管设置或任何其他设置文件的 `Read(./.env)` deny。

462

463两个限制缩小了 `!` 模式可以切割的内容：

464

465* Claude Code 读取 `!` 模式相对于当前目录，即使 `/`、`~/` 或 `//` 跟随 `!`，因此模式无法到达用其中一个前缀锚定的规则。`Read(!~/notes/public/**)` 从 `Read(~/notes/**)` 中切割不出任何内容。

466* 切割不能重新打开规则作为整体阻止的目录内的文件。使用 `Read(secrets/**)` 和 `Read(!secrets/public/**)`，Claude Code 仍然阻止 `secrets/public` 以及 `secrets` 的其余部分。

467

457当 Claude 访问符号链接时，权限规则检查两个路径：符号链接本身和它解析到的文件。Allow 和 deny 规则对该对的处理方式不同：allow 规则回退到提示您，而 deny 规则直接阻止。468当 Claude 访问符号链接时，权限规则检查两个路径：符号链接本身和它解析到的文件。Allow 和 deny 规则对该对的处理方式不同：allow 规则回退到提示您，而 deny 规则直接阻止。

458 469

459* **Allow 规则**：仅在符号链接路径及其目标都匹配时适用。允许目录内的符号链接指向其外部仍然会提示您。470* **Allow 规则**：仅在符号链接路径及其目标都匹配时适用。允许目录内的符号链接指向其外部仍然会提示您。

506}517}

507```518```

508 519

509当您要求 Claude 获取页面时，它无需提示即可获取。当您要求它对沙箱允许列表外的主机运行[沙箱](/docs/zh-CN/sandboxing) `curl` 时，Claude Code 仍然会提示您该主机，或在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中将请求发送到分类器，因为裸规则没有将主机添加到允许列表。520当您要求 Claude 获取页面时，它无需提示即可获取。当您要求它对沙箱允许列表外的主机运行[沙箱](/docs/zh-CN/sandboxing) `curl` 时，Claude Code 仍然会提示您该主机，因为裸规则没有将主机添加到允许列表。

521

522在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中，Claude 改为在命令的[每个命令允许的域](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)中命名主机以供分类器审查。

510 523

511<h3 id="mcp">524<h3 id="mcp">

512 MCP525 MCP

646权限和[沙箱](/docs/zh-CN/sandboxing)是互补的安全层：659权限和[沙箱](/docs/zh-CN/sandboxing)是互补的安全层：

647 660

648* **权限**控制 Claude Code 可以使用哪些工具以及它可以访问哪些文件或域。它们适用于 Bash、Read、Edit、WebFetch、MCP 和其他所有工具，除了 deny 或 ask 规则无法阻止 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior)，而任何其他工具仍然存在。661* **权限**控制 Claude Code 可以使用哪些工具以及它可以访问哪些文件或域。它们适用于 Bash、Read、Edit、WebFetch、MCP 和其他所有工具，除了 deny 或 ask 规则无法阻止 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior)，而任何其他工具仍然存在。

649* **沙箱**提供 OS 级别的强制执行，限制 Bash 工具的文件系统和网络访问。它仅适用于 Bash 命令及其子进程。662* **沙箱**提供 OS 级别的强制执行，限制 shell 命令的文件系统和网络访问。它仅适用于 Bash、PowerShell 和 [Monitor](/docs/zh-CN/tools-reference#monitor-tool) 命令及其子进程。

650 663

651使用两者进行深度防御，因为即使提示注入绕过 Claude 的决策制定，沙箱限制仍然适用。来自沙箱设置和权限规则的路径和域被[合并到最终沙箱配置](/docs/zh-CN/sandboxing#permission-rules)中。664使用两者进行深度防御，因为即使提示注入绕过 Claude 的决策制定，沙箱限制仍然适用。来自沙箱设置和权限规则的路径和域被[合并到最终沙箱配置](/docs/zh-CN/sandboxing#permission-rules)中。

652 665

platforms.md +2 −1

Details

73* [Desktop](/docs/zh-CN/desktop)：视觉 diff 审查、并行会话、计算机使用和 Dispatch73* [Desktop](/docs/zh-CN/desktop)：视觉 diff 审查、并行会话、计算机使用和 Dispatch

74* [VS Code](/docs/zh-CN/vs-code)：编辑器内的 Claude Code 扩展74* [VS Code](/docs/zh-CN/vs-code)：编辑器内的 Claude Code 扩展

75* [JetBrains](/docs/zh-CN/jetbrains)：IntelliJ、PyCharm 和其他 JetBrains IDE 的扩展75* [JetBrains](/docs/zh-CN/jetbrains)：IntelliJ、PyCharm 和其他 JetBrains IDE 的扩展

~~76* [Web 上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)：断开连接时继续运行的云会话~~76* [Web](/docs/zh-CN/claude-code-on-the-web)：云会话，可从浏览器访问 claude.ai/code，断开连接时继续运行

77* [Projects](/docs/zh-CN/claude-projects)：一个对话，Claude 在其中协调许多云会话以完成一项工作并报告结果

77* [Mobile](/docs/zh-CN/mobile)：用于在远离计算机时启动和监控任务的 [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 和 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) 版 Claude 应用78* [Mobile](/docs/zh-CN/mobile)：用于在远离计算机时启动和监控任务的 [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 和 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) 版 Claude 应用

78 79

79<h3 id="integrations">80<h3 id="integrations">

plugin-dependencies.md +2 −2

Details

41}41}

42```42```

43 43

44条目可以是仅包含插件名称的裸字符串，如上例中的 `"audit-logger"`，它依赖于该插件的 marketplace 提供的任何版本。为了获得更多控制，请使用具有以下字段的对象：44条目可以是仅包含插件名称的裸字符串，如 `"audit-logger"` 在 `deploy-kit` manifest 中，它依赖于该插件的 marketplace 提供的任何版本。为了获得更多控制，请使用具有以下字段的对象：

45 45

46| 字段 | 类型 | 描述 |46| 字段 | 类型 | 描述 |

47| :------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |47| :------------ | :----- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

75 75

76安装 `backend-standard` 会解析并安装所有四个依赖项。76安装 `backend-standard` 会解析并安装所有四个依赖项。

77 77

78要稍后向标准集添加工具，请发布新的 `backend-standard` 版本并添加额外的依赖项。对于非 Anthropic marketplace，自动更新默认处于关闭状态，因此工程师可以通过以下两种方式之一获取新版本：78要稍后向标准集添加工具，请发布新的 `backend-standard` 版本并添加额外的依赖项。除非 marketplace [自动更新](/docs/zh-CN/discover-plugins#configure-auto-updates)，工程师可以通过以下两种方式之一获取新版本：

79 79

80* 在 `/plugin` 中为 marketplace 启用自动更新。下一次自动更新会将捆绑包移至新版本并安装它添加的任何依赖项。80* 在 `/plugin` 中为 marketplace 启用自动更新。下一次自动更新会将捆绑包移至新版本并安装它添加的任何依赖项。

81* 运行 `claude plugin update backend-standard`，然后运行 `/reload-plugins` 以安装新添加的依赖项。81* 运行 `claude plugin update backend-standard`，然后运行 `/reload-plugins` 以安装新添加的依赖项。

plugin-marketplaces.md +84 −37

Details

71 ```71 ```

72 72

73 <Note>73 <Note>

74 设置 `version` 意味着用户仅在你更改此字段时才会收到更新，因此在每次发布时都要提升版本号。具有 command source 的 plugin 不会被此字段固定。如果你省略 `version`，版本来自 [版本管理](/docs/zh-CN/plugins-reference#version-management) 中的下一个来源。74 设置 `version` 意味着用户仅在你更改此字段时才会收到更新，因此在每次发布时都要提升版本号。具有 [`command` source](#command-sources) 的 plugin 不会被此字段固定。从本地目录添加的 marketplace 中 [就地加载](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution) 的 plugin 也不会被固定。如果你省略 `version`，版本来自 [版本管理](/docs/zh-CN/plugins-reference#version-management) 中的下一个来源。

75 </Note>75 </Note>

76 </Step>76 </Step>

77 77

116要了解更多关于 plugins 可以做什么的信息，包括 hooks、agents、MCP servers 和 LSP servers，请参阅 [Plugins](/docs/zh-CN/plugins)。116要了解更多关于 plugins 可以做什么的信息，包括 hooks、agents、MCP servers 和 LSP servers，请参阅 [Plugins](/docs/zh-CN/plugins)。

117 117

118<Note>118<Note>

119 **plugins 如何安装**：当用户安装 plugin 时，Claude Code 将 plugin 目录复制到缓存位置，除了 link mode 中的 command source，它被就地使用。复制的 plugins 无法使用 `../shared-utils` 之类的路径引用其目录外的文件，因为这些文件不会被复制。119 **plugins 如何安装**：当用户安装 plugin 时，Claude Code 将 plugin 目录复制到缓存位置，除非 plugin 就地加载。link mode 中的 [`command` source](#copy-mode-and-link-mode) 就地加载，从本地目录添加的 marketplace 中的 [相对路径 source](#relative-paths) 也是如此。复制的 plugins 无法使用 `../shared-utils` 之类的路径引用其目录外的文件，因为这些文件不会被复制。

120 120

121 如果你需要在 plugins 之间共享文件，请使用符号链接。有关详细信息，请参阅 [Plugin 缓存和文件解析](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution)。121 如果你需要在 plugins 之间共享文件，请使用符号链接。有关详细信息，请参阅 [Plugin 缓存和文件解析](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution)。

122</Note>122</Note>

167</h3>167</h3>

168 168

169| 字段 | 类型 | 描述 | 示例 |169| 字段 | 类型 | 描述 | 示例 |

170| :-------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |170| :-------- | :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------- |

171| `name` | string | Marketplace 标识符，采用 kebab-case 格式，不包含空格、控制字符或双向格式化字符。这是面向公众的：用户在安装 plugins 时会看到它（例如，`/plugin install my-tool@your-marketplace`）。每个用户只能为每个名称注册一个 marketplace：添加第二个同名 marketplace 时，Claude Code 会替换第一个。要在一个 marketplace 名称下发布多个 plugins，请在[单个 `marketplace.json`](#create-the-marketplace-file) 中列出它们。 | `"acme-tools"` |171| `name` | string | Marketplace 标识符，采用 kebab-case 格式，不包含空格、控制字符或双向格式化字符。这是面向公众的：用户在安装 plugins 时会看到它（例如，`/plugin install my-tool@your-marketplace`）。每个用户只能为每个名称注册一个 marketplace：添加第二个同名 marketplace 时，Claude Code 会替换第一个。要在一个 marketplace 名称下发布多个 plugins，请在[单个 `marketplace.json`](#create-the-marketplace-file) 中列出它们。 | `"acme-tools"` |

174 174

175<Note>175<Note>

176 **保留名称**：以下 marketplace 名称为 Anthropic 官方使用保留，第三方 marketplaces 无法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`claude-plugins-community`、`claude-community`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`knowledge-work-plugins`、`life-sciences`、`claude-for-legal`、`claude-for-financial-services`、`financial-services-plugins`、`first-party-plugins`、`claude-tag-plugins`、`healthcare`。冒充官方 marketplaces 的名称（如 `official-claude-plugins` 或 `anthropic-plugins-v2`）也被阻止。保留这些名称可防止第三方 marketplace 将自己呈现为 Anthropic 发布的来源。176 **保留名称**：以下 marketplace 名称为 Anthropic 官方使用保留，第三方 marketplaces 无法使用：`claude-code-marketplace`、`claude-code-plugins`、`claude-plugins-official`、`claude-plugins-community`、`claude-community`、`anthropic-marketplace`、`anthropic-plugins`、`agent-skills`、`anthropic-agent-skills`、`knowledge-work-plugins`、`life-sciences`、`claude-for-legal`、`claude-for-financial-services`、`financial-services-plugins`、`first-party-plugins`、`claude-tag-plugins`、`healthcare`。冒充官方 marketplaces 的名称（如 `official-claude-plugins` 或 `anthropic-plugins-v2`）也被阻止。保留这些名称可防止第三方 marketplace 将自己呈现为 Anthropic 发布的来源。

177 177

178 Claude Code 每次加载 marketplace 时都会重新检查保留名称，而不仅仅是在添加时。在该名称成为保留名称之前以其中一个名称注册的 marketplace 停止加载，并报告它是[从不受信任的来源注册的](/docs/zh-CN/errors#marketplace-is-registered-from-an-untrusted-source)。移除该 marketplace 并从官方 Anthropic 来源重新添加它。受新保留名称影响的第三方 marketplace 在你以不同名称重新添加它后立即再次加载。在 v2.1.205 之前，`first-party-plugins` 和 `healthcare` 不是保留的，已在保留名称下注册的 marketplace 继续加载。在 v2.1.265 之前，`claude-tag-plugins` 不是保留的。178 Claude Code 每次加载 marketplace 时都会重新检查保留名称，而不仅仅是在添加时。在该名称成为保留名称之前以其中一个名称注册的 marketplace 停止加载，并报告它是[从不受信任的来源注册的](/docs/zh-CN/errors#marketplace-is-registered-from-an-untrusted-source)。移除该 marketplace 并从官方 Anthropic 来源重新添加它。受新保留名称影响的第三方 marketplace 在你以不同名称重新添加它后立即再次加载。在 v2.1.205 之前，`first-party-plugins` 和 `healthcare` 不是保留的，已在保留名称下注册的 marketplace 继续加载。在 v2.1.265 之前，`claude-tag-plugins` 不是保留的。

179

180 你也不能将 marketplace 命名为 `npm`、`pip`、`uv`、`cargo`、`github` 或 `gh`，无论大小写如何。此检查需要 Claude Code v2.1.275 或更高版本。

179</Note>181</Note>

180 182

181<h3 id="owner-fields">183<h3 id="owner-fields">

225**标准元数据字段：**227**标准元数据字段：**

226 228

227| 字段 | 类型 | 描述 |229| 字段 | 类型 | 描述 |

228| :--------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |230| :--------------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

231| `version` | string | Plugin 版本。如果设置（在此处或在 `plugin.json` 中），plugin 将固定到此字符串，用户仅在其更改时才会收到更新。具有 [`command` 源](#command-sources)的 plugin 不会被任一字段固定。如果在两个地方都未设置，版本来自 [版本管理](/docs/zh-CN/plugins-reference#version-management)中的下一个源。 |233| `version` | string | Plugin 版本。如果设置（在此处或在 `plugin.json` 中），plugin 将固定到此字符串，用户仅在其更改时才会收到更新。具有 [`command` 源](#command-sources)的 plugin 不会被任一字段固定。也不会从 marketplace 添加为本地目录的 [就地加载](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution)的 plugin。如果在两个地方都未设置，版本来自 [版本管理](/docs/zh-CN/plugins-reference#version-management)中的下一个源。 |

274 276

275Plugin 源告诉 Claude Code 在你的 marketplace 中列出的每个单独 plugin 从哪里获取。这些在 `marketplace.json` 中每个 plugin 条目的 `source` 字段中设置。277Plugin 源告诉 Claude Code 在你的 marketplace 中列出的每个单独 plugin 从哪里获取。这些在 `marketplace.json` 中每个 plugin 条目的 `source` 字段中设置。

276 278

277Claude Code 将每个已安装的 plugin 复制到本地版本化 plugin 缓存中，位置为 `~/.claude/plugins/cache`，除了[链接模式](#copy-mode-and-link-mode)中的 [`command` 源](#command-sources)，Claude Code 会就地使用。Claude Code 还会[将 plugin 的符合条件的 Node.js 包依赖项安装](/docs/zh-CN/plugins-reference#node-js-package-dependencies)到缓存副本中。279Claude Code 将每个已安装的 plugin 复制到本地版本化 plugin 缓存中，位置为 `~/.claude/plugins/cache`，除非 plugin 就地加载。链接模式中的 [`command` 源](#copy-mode-and-link-mode)就地加载，[相对路径源](#relative-paths)从本地目录添加的 marketplace 也是如此。Claude Code 还会[将 plugin 的符合条件的 Node.js 包依赖项安装](/docs/zh-CN/plugins-reference#node-js-package-dependencies)到缓存副本中。见[Plugin 缓存和文件解析](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution)了解从本地目录 marketplace 就地加载的 plugin 如何获取你的编辑。

278 280

279| 源 | 类型 | 字段 | 注释 |281| 源 | 类型 | 字段 | 注释 |

280| ------------ | ---------------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |282| ------------ | ---------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |

288 290

314}316}

315```317```

316 318

317路径相对于 marketplace 根目录解析，即包含 `.claude-plugin/` 的目录。在上面的示例中，`./plugins/my-plugin` 指向 `<repo>/plugins/my-plugin`，即使 `marketplace.json` 位于 `<repo>/.claude-plugin/marketplace.json`。不要使用 `../` 来引用 marketplace 根目录外的路径。在 macOS 和 Linux 上，Claude Code 拒绝在前导 `./` 之后任何地方包含反斜杠的条目路径，所以在每个平台上将分隔符写为 `/`。319路径相对于 marketplace 根目录解析，即包含 `.claude-plugin/` 的目录。源 `./plugins/my-plugin` 因此指向 `<repo>/plugins/my-plugin`，即使 `marketplace.json` 位于 `<repo>/.claude-plugin/marketplace.json`。不要使用 `../` 来引用 marketplace 根目录外的路径。在 macOS 和 Linux 上，Claude Code 拒绝在前导 `./` 之后任何地方包含反斜杠的条目路径，所以在每个平台上将分隔符写为 `/`。

318 320

319裸名是没有 `/` 的单个目录名，例如 `"formatter"`。要写裸名而不是 `./` 路径，请设置 [`metadata.pluginRoot`](#optional-fields) 为它们解析的目录。使用 `"pluginRoot": "./plugins"`，Claude Code 将 `"source": "formatter"` 解析为 `./plugins/formatter`。需要 Claude Code v2.1.239 或更高版本。321裸名是没有 `/` 的单个目录名，例如 `"formatter"`。要写裸名而不是 `./` 路径，请设置 [`metadata.pluginRoot`](#optional-fields) 为它们解析的目录。使用 `"pluginRoot": "./plugins"`，Claude Code 将 `"source": "formatter"` 解析为 `./plugins/formatter`。需要 Claude Code v2.1.239 或更高版本。

320 322

437 npm 包439 npm 包

438</h3>440</h3>

439 441

440作为 npm 包分发的 Plugins 使用 `npm install` 安装。这适用于公共 npm registry 上的任何包或你的团队托管的私有 registry。442npm 源可以命名公共 npm registry 上的任何包或你的团队托管的私有 registry 上的任何包。Claude Code 使用你的 npm 客户端解析包，下载 tarball，并将其解包到 plugin 缓存中。

443

444包的安装脚本（例如 `preinstall` 或 `postinstall`）永远不会运行，其依赖项在获取期间不会被安装。

445

446如果包在其 `package.json` 旁边附带支持的 lockfile，Claude Code 会在单独的步骤中安装那些[Node.js 包依赖项](/docs/zh-CN/plugins-reference#node-js-package-dependencies)，也禁用脚本。否则，发布已构建所需一切的 plugin。需要其他包的 MCP 服务器可以通过 `npx` 启动，它在首次运行时安装它们。

441 447

442```json theme={null}448```json theme={null}

443{449{

612 用户如何接受 headersHelper 命令618 用户如何接受 headersHelper 命令

613</h4>619</h4>

614 620

615用户每次从 plugin 的自己的视图在 `/plugin` 或使用 `claude plugin install` 或 `claude plugin update` 自己安装或更新该单个 plugin 时接受 plugin 条目的命令。Claude Code 显示命令和存档 URL，并仅在用户接受后运行命令。在非交互式 shell 中，传递 [`--yes`](/docs/zh-CN/plugins-reference#plugin-install) 以接受它。621用户每次从 plugin 的自己的视图在 `/plugin` 或使用 `claude plugin install` 或 `claude plugin update` 自己安装或更新该单个 plugin 时接受 plugin 条目的命令。Claude Code 显示命令和存档 URL，并仅在用户接受后运行命令。

622

623在非交互式 shell 中，传递 [`--yes`](/docs/zh-CN/plugins-reference#plugin-install) 以接受命令。要接受仅前一个 `--json` 运行显示的命令，传递 [`--accept-command`](/docs/zh-CN/plugins-reference#plugin-install) 和运行报告的 `sha256`。

616 624

617Claude Code 仅运行它显示的命令，用于它显示的存档 URL。如果条目的命令或存档 URL 在此期间更改，Claude Code 拒绝安装或更新。仅查询字符串中的更改不计算。625Claude Code 仅运行它显示的命令，用于它显示的存档 URL。如果条目的命令或存档 URL 在此期间更改，Claude Code 拒绝安装或更新。仅查询字符串中的更改不计算。

618 626

693 701

694Claude Code 在用户的机器上运行你的命令，所以它将每次运行绑定到用户的明确接受：702Claude Code 在用户的机器上运行你的命令，所以它将每次运行绑定到用户的明确接受：

695 703

696* 当用户从 `/plugin` 中的 plugin 详情屏幕安装 plugin，或在交互式终端中使用 `claude plugin install` 或 `claude plugin update` 安装或更新它时，Claude Code 首先向他们显示确切的命令字符串，并为该安装记录接受的命令。可以在接受相同命令的记录接受上进行的 `claude plugin update` 显示无。在非交互式 shell 中，例如配置脚本，传递 `--yes` 到 `claude plugin install` 或 `claude plugin update` 以接受它打印的命令。704* 当用户从 `/plugin` 中的 plugin 详情屏幕安装 plugin，或在交互式终端中使用 `claude plugin install` 或 `claude plugin update` 安装或更新它时，Claude Code 首先向他们显示确切的命令字符串，并为该安装记录接受的命令。可以在接受相同命令的记录接受上进行的 `claude plugin update` 显示无。在非交互式 shell 中，例如配置脚本，传递 `--yes` 到 `claude plugin install` 或 `claude plugin update` 以接受它打印的命令。要接受仅前一个 `--json` 运行显示的命令，传递 [`--accept-command`](/docs/zh-CN/plugins-reference#plugin-install) 和运行报告的 `sha256`。

697* 每条其他路径仅运行用户已接受的命令。这包括从 `/plugin` 启动的更新和[何时 Claude Code 重新运行命令](#when-claude-code-re-runs-the-command)中描述的后台运行。当未接受任何内容时，Claude Code 拒绝运行命令并告诉用户如何查看它。Claude Code 从不将 command 源 plugin 安装为另一个 plugin 的依赖项，所以用户自己先安装它。705* 每条其他路径仅运行用户已接受的命令。这包括从 `/plugin` 启动的更新和[何时 Claude Code 重新运行命令](#when-claude-code-re-runs-the-command)中描述的后台运行。当未接受任何内容时，Claude Code 拒绝运行命令并告诉用户如何查看它。Claude Code 从不将 command 源 plugin 安装为另一个 plugin 的依赖项，所以用户自己先安装它。

698* 如果你更改条目的 `command` 或切换其 `mode`，用户保留他们已有的版本，Claude Code 停止重新运行命令。在交互式会话中，`/plugin` 错误选项卡显示新命令，直到用户通过运行 `claude plugin update <plugin>@<marketplace>` 查看并接受它。706* 如果你更改条目的 `command` 或切换其 `mode`，用户保留他们已有的版本，Claude Code 停止重新运行命令。在交互式会话中，`/plugin` 错误选项卡显示新命令，直到用户通过运行 `claude plugin update <plugin>@<marketplace>` 查看并接受它。

699 707

810 托管和分发 marketplaces818 托管和分发 marketplaces

811</h2>819</h2>

812 820

821当用户添加托管在 git 存储库中的 marketplace，或安装其列出的基于 git 的 plugin 时，Claude Code 会将该 marketplace 或 plugin 存储库克隆到他们的机器上。克隆永远不会下载 [Git LFS](https://git-lfs.com) 内容，所以 LFS 跟踪的文件作为指针文件到达。将你的 plugins 需要的文件保留在 LFS 之外。

822

813<h3 id="host-on-github-recommended">823<h3 id="host-on-github-recommended">

814 在 GitHub 上托管（推荐）824 在 GitHub 上托管（推荐）

815</h3>825</h3>

836 私有存储库846 私有存储库

837</h3>847</h3>

838 848

839Claude Code 支持从私有存储库安装 plugins。如果你通过[**组织设置 > Plugins**](https://claude.ai/admin-settings/plugins)分发你的 marketplace，你的 git 凭证不涉及：组织同步通过 Claude GitHub App 或你的组织的 GitHub Enterprise App 读取 marketplace 存储库，plugin 源如果无法进行身份验证必须是公开的。有关完整规则，请参阅[通过组织设置分发](#distribute-through-organization-settings)。849Claude Code 支持从私有存储库安装 plugins。如果你通过[**组织设置 > Plugins**](https://claude.ai/admin-settings/plugins)分发你的 marketplace，你的 git 凭证不涉及：组织同步通过你的组织的 GitHub 或 GitLab 连接在 claude.ai 上读取 marketplace 存储库。有关哪些 plugin 源可以是私有的，请参阅[通过组织设置分发](#distribute-through-organization-settings)。

840 850

841<h4 id="commands-you-run">851<h4 id="commands-you-run">

842 你运行的命令852 你运行的命令

848 后台自动更新858 后台自动更新

849</h4>859</h4>

850 860

851默认情况下，后台刷新会为其 `git pull` 禁用 git 凭证助手，所以即使配置了助手，pull 也无法对 HTTPS 上的私有存储库进行身份验证。SSH 远程不受影响：加载到 `ssh-agent` 中的密钥以与你运行的命令相同的方式对后台 pulls 进行身份验证。当后台 pull 失败时，Claude Code 会回退到从头重新克隆 marketplace。重新克隆确实使用你存储的 git 凭证，但它可能在大型存储库上[超时](#git-operations-time-out)，所以私有 marketplace 自动更新可能会间歇性失败。861默认情况下，后台刷新会在检查 marketplace 的远程以查找新提交时禁用 git 凭证助手，所以检查无法对 HTTPS 上的私有存储库进行身份验证，即使配置了助手。SSH 远程不受影响：加载到 `ssh-agent` 中的密钥以与你运行的命令相同的方式对后台检查进行身份验证。

862

863当检查找到新提交，或因为无法到达或对远程进行身份验证而失败时，Claude Code 会再次克隆 marketplace 并交换新克隆。如果该克隆失败，现有检出保持就位。重新克隆确实使用你存储的 git 凭证，但它可能在大型存储库上[超时](#git-operations-time-out)，所以私有 marketplace 自动更新可能会间歇性失败。

852 864

853两个设置使私有 marketplaces 的行为可预测：865两个设置使私有 marketplaces 的行为可预测：

854 866

855* 设置 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在后台 pull 失败时保留现有克隆，而不是删除并重新克隆。你的 plugins 继续从最后同步的状态工作，使用 `/plugin marketplace update` 的手动更新仍然使用你的凭证进行 pull。867* 设置 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在后台检查无法到达或对远程进行身份验证时保留现有检出，而不尝试重新克隆。你的 plugins 继续从最后同步的状态工作，使用 `/plugin marketplace update` 的手动更新仍然使用你的凭证进行身份验证。

856* 配置 git 凭证助手，例如使用 `gh auth setup-git` 用于 GitHub，以便重新克隆回退可以在不提示的情况下进行身份验证。868* 配置 git 凭证助手，例如使用 `gh auth setup-git` 用于 GitHub，以便重新克隆可以在不提示的情况下进行身份验证。

857 869

858在你的环境中设置提供商令牌（如 `GITHUB_TOKEN`）本身不会启用后台身份验证。令牌仅通过配置的凭证助手（例如 `gh` CLI 的助手，它读取 `GH_TOKEN` 和 `GITHUB_TOKEN`）生效。870在你的环境中设置提供商令牌（如 `GITHUB_TOKEN`）本身不会启用后台身份验证。令牌仅通过配置的凭证助手（例如 `gh` CLI 的助手，它读取 `GH_TOKEN` 和 `GITHUB_TOKEN`）生效。

859 871

860要使后台 pull 本身通过 HTTPS 进行身份验证，请配置全局 git URL 重写。重写在远程 URL 中嵌入令牌，所以即使后台 pull 禁用凭证助手，它也会生效，成功的 pull 会跳过重新克隆回退。以下示例重写 marketplace 存储库的 URL 以包含访问令牌：872要使后台检查本身通过 HTTPS 进行身份验证，请配置全局 git URL 重写。重写在远程 URL 中嵌入令牌，所以即使后台检查禁用凭证助手，它也会生效。当检查发现检出是最新的时，Claude Code 会跳过重新克隆。以下示例重写 marketplace 存储库的 URL 以包含访问令牌：

861 873

862```bash theme={null}874```bash theme={null}

863git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"875git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"

876重写以纯文本形式在你的 gitconfig 中存储令牌，所以使用对 marketplace 存储库具有只读访问权限的令牌。888重写以纯文本形式在你的 gitconfig 中存储令牌，所以使用对 marketplace 存储库具有只读访问权限的令牌。

877 889

878<Note>890<Note>

879 在 CI/CD 环境中，在从私有存储库安装 plugins 之前配置 git 凭证助手。在 GitHub Actions 上，导出对 marketplace 存储库具有读取访问权限的令牌作为 `GH_TOKEN`，然后运行 `gh auth setup-git`。默认工作流令牌只能访问工作流自己的存储库，所以另一个存储库中的私有 marketplace 需要个人访问令牌或应用令牌。在管道中配置的全局 URL 重写也直接对后台 pull 进行身份验证。891 在 CI/CD 环境中，在从私有存储库安装 plugins 之前配置 git 凭证助手。在 GitHub Actions 上，导出对 marketplace 存储库具有读取访问权限的令牌作为 `GH_TOKEN`，然后运行 `gh auth setup-git`。默认工作流令牌只能访问工作流自己的存储库，所以另一个存储库中的私有 marketplace 需要个人访问令牌或应用令牌。

892

893 如果你在管道中配置全局 URL 重写，重写也直接对后台检查进行身份验证。

880</Note>894</Note>

881 895

882<h3 id="distribute-through-organization-settings">896<h3 id="distribute-through-organization-settings">

885 899

886如果你在 Team 或 Enterprise 计划上通过[**组织设置 > Plugins**](https://claude.ai/admin-settings/plugins)分发 plugins，这些源规则适用：900如果你在 Team 或 Enterprise 计划上通过[**组织设置 > Plugins**](https://claude.ai/admin-settings/plugins)分发 plugins，这些源规则适用：

887 901

888* marketplace 存储库必须是私有或内部的。组织同步通过 Claude GitHub App 或你的组织的 GitHub Enterprise App 读取它。902* 在 github.com 和 gitlab.com 上，marketplace 存储库必须是私有或内部的。组织同步通过与其主机匹配的连接读取存储库：

903 * **github.com**：Claude GitHub App

904 * **你的 GitHub Enterprise Server 主机**：你的组织的 [GitHub Enterprise App](/docs/zh-CN/github-enterprise-server#admin-setup)

905 * **gitlab.com 或你的自托管 GitLab 实例**：你的组织的 [GitLab 配置](#sync-a-gitlab-hosted-marketplace)中该主机的访问令牌

889* 每个 plugin 源必须是 `github`、`url` 或 `git-subdir` 类型，或[相对路径](#relative-paths)，以 `./` 开头。如果你在 `metadata.pluginRoot` 下按裸名称列出 plugin，组织同步会将其拒绝为不支持的源，所以写出路径，例如 `./plugins/deploy-tools`。906* 每个 plugin 源必须是 `github`、`url` 或 `git-subdir` 类型，或[相对路径](#relative-paths)，以 `./` 开头。如果你在 `metadata.pluginRoot` 下按裸名称列出 plugin，组织同步会将其拒绝为不支持的源，所以写出路径，例如 `./plugins/deploy-tools`。

890* plugin 源可以在两种情况下是私有的：907* plugin 源可以在三种情况下是私有的：

891 * 与 marketplace 存储库的所有者共享的 github.com 源908 * 与 marketplace 存储库的所有者共享的 github.com 源

892 * 在你的组织的 GitHub Enterprise 主机上安装了 GHE App 的源909 * 在你的组织的 GitHub Enterprise 主机上安装了 GHE App 的源

893* 组织同步在没有凭证的情况下获取所有其他源，所以不同所有者下的 github.com 存储库和其他主机上的存储库（例如 GitLab 或 Bitbucket）必须是公开的。910 * 与 marketplace 存储库在同一 GitLab 主机上的 `url` 或 `git-subdir` 源。在 gitlab.com 上，源也必须在与 marketplace 存储库相同的顶级组或用户命名空间下。

911* 任何其他 plugin 源必须是 github.com、gitlab.com 或 bitbucket.org 上的公开存储库，组织同步在没有凭证的情况下获取。组织同步拒绝这些规则不涵盖的主机上的 plugin 源。

894 912

895有关管理员工作流，请参阅[为你的组织管理 plugins](https://support.claude.com/en/articles/13837433)。913有关管理员工作流，请参阅[为你的组织管理 plugins](https://support.claude.com/en/articles/13837433)。

896 914

905}923}

906```924```

907 925

926<h4 id="sync-a-gitlab-hosted-marketplace">

927 同步 GitLab 托管的 marketplace

928</h4>

929

930要从 gitlab.com 或自托管 GitLab 实例同步 marketplace，[所有者](/docs/zh-CN/server-managed-settings#access-control)首先在[**组织设置 > Claude Code**](https://claude.ai/admin-settings/claude-code)为该主机添加 GitLab 配置。GitLab 配置处于公开测试版，仅适用于 plugin marketplace 同步。添加一个不会使 GitLab 存储库在[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web#limitations) 中可用。有关设置步骤，请参阅[为你的组织管理 plugins](https://support.claude.com/en/articles/13837433)。

931

932当你添加 marketplace 时，输入项目的 HTTPS URL，例如 `https://gitlab.example.com/platform/claude-plugins`。嵌套子组中的项目有效。组织同步读取项目的默认分支。如果你打开**自动同步**，只有对默认分支的 pushes 才会启动同步。

933

908<h4 id="keep-executables-out-of-the-top-level-bin-directory">934<h4 id="keep-executables-out-of-the-top-level-bin-directory">

909 将可执行文件保留在顶级 bin 目录之外935 将可执行文件保留在顶级 bin 目录之外

910</h4>936</h4>

984 1010

985行为详情：1011行为详情：

986 1012

987* **只读**：种子目录永远不会被写入。由于 git pull 会在只读文件系统上失败，种子 marketplaces 的自动更新被禁用。1013* **只读**：Claude Code 永远不会写入种子目录。

1014* **自动更新禁用**：种子 marketplaces 不会自动更新。

988* **种子条目优先**：在每次启动时，种子中声明的 marketplaces 会覆盖用户配置中的任何匹配条目。要选择退出种子 plugin，请使用 `/plugin disable` 而不是删除 marketplace。1015* **种子条目优先**：在每次启动时，种子中声明的 marketplaces 会覆盖用户配置中的任何匹配条目。要选择退出种子 plugin，请使用 `/plugin disable` 而不是删除 marketplace。

989* **路径解析**：Claude Code 通过在运行时探测 `$CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/` 来定位 marketplace 内容，而不是信任存储在种子 JSON 内的路径。这意味着即使在与构建时不同的路径上挂载，种子也能正确工作。1016* **路径解析**：Claude Code 通过在运行时探测 `$CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/` 来定位 marketplace 内容，而不是信任存储在种子 JSON 内的路径。这意味着即使在与构建时不同的路径上挂载，种子也能正确工作。

990* **变更被阻止**：针对种子管理的 marketplace 运行 `/plugin marketplace remove` 或 `/plugin marketplace update` 会失败，并提示你要求管理员更新种子镜像。1017* **变更被阻止**：针对种子管理的 marketplace 运行 `/plugin marketplace remove` 或 `/plugin marketplace update` 会失败，并提示你要求管理员更新种子镜像。

1018}1045}

1019```1046```

1020 1047

1048Claude Code 下载[从 claude.ai 同步的](/docs/zh-CN/plugins-reference#synced-plugins) plugins 来自你的账户而不是来自 marketplace，所以这个锁定不涵盖它们。要同时停止这些，请在托管设置中将 [`syncClaudeAiPlugins`](/docs/zh-CN/settings-reference#syncclaudeaiplugins) 设置为 `false`，或在 claude.ai 上为你的组织关闭 Skills。

1049

1021仅允许官方 Anthropic marketplace。单个存储库条目的匹配是精确的，所以此条目不涵盖同一存储库的 `ref` 或 `path` 变体：1050仅允许官方 Anthropic marketplace。单个存储库条目的匹配是精确的，所以此条目不涵盖同一存储库的 `ref` 或 `path` 变体：

1022 1051

1023```json theme={null}1052```json theme={null}

1128 1157

1129允许列表的精确匹配将仅因尾部斜杠、`.git` 后缀或 `ssh://` 和 `https://` 方案不同的 URL 视为不同的值。如果你的组织的 marketplace 可以通过多个 URL 形式克隆，优先使用 `hostPattern` 条目而不是字面 URL，以便 `https://`、`ssh://` 和 `user@host:path` 形式都匹配。1158允许列表的精确匹配将仅因尾部斜杠、`.git` 后缀或 `ssh://` 和 `https://` 方案不同的 URL 视为不同的值。如果你的组织的 marketplace 可以通过多个 URL 形式克隆，优先使用 `hostPattern` 条目而不是字面 URL，以便 `https://`、`ssh://` 和 `user@host:path` 形式都匹配。

1130 1159

1160一个[托管在 claude.ai 上的 marketplace](/docs/zh-CN/discover-plugins#add-from-claude-ai) 通过主机匹配：一个与 `claude.ai` 匹配的 `hostPattern` 条目在 `strictKnownMarketplaces` 和 `blockedMarketplaces` 中管理它。在允许列表上，这样的条目不允许成员的个人 claude.ai 上传。需要 Claude Code v2.1.273 或更高版本。

1161

1131因为 `strictKnownMarketplaces` 在[托管设置](/docs/zh-CN/managed-settings)中设置，个别用户和项目配置无法覆盖这些限制。1162因为 `strictKnownMarketplaces` 在[托管设置](/docs/zh-CN/managed-settings)中设置，个别用户和项目配置无法覆盖这些限制。

1132 1163

1133有关完整的配置详细信息，包括所有支持的源类型和与 `extraKnownMarketplaces` 的比较，请参阅 [strictKnownMarketplaces 参考](/docs/zh-CN/settings-reference#strictknownmarketplaces)。1164有关完整的配置详细信息，包括所有支持的源类型和与 `extraKnownMarketplaces` 的比较，请参阅 [strictKnownMarketplaces 参考](/docs/zh-CN/settings-reference#strictknownmarketplaces)。

1139Plugin 版本确定缓存路径和更新检测：如果解析的版本与用户已有的版本匹配，`/plugin update` 和自动更新会跳过该 plugin。对于 git 源，如果你省略 `version`，Claude Code 使用源的解析提交 SHA，所以用户在该提交更改时获得更新；这是内部或积极开发的 plugins 的最简单设置。有关完整的解析顺序（包括 `archive` 源），请参阅[版本管理](/docs/zh-CN/plugins-reference#version-management)。1170Plugin 版本确定缓存路径和更新检测：如果解析的版本与用户已有的版本匹配，`/plugin update` 和自动更新会跳过该 plugin。对于 git 源，如果你省略 `version`，Claude Code 使用源的解析提交 SHA，所以用户在该提交更改时获得更新；这是内部或积极开发的 plugins 的最简单设置。有关完整的解析顺序（包括 `archive` 源），请参阅[版本管理](/docs/zh-CN/plugins-reference#version-management)。

1140 1171

1141<Warning>1172<Warning>

1142 设置 `version` 为除了 [`command`](#command-sources) 之外的每个源类型固定 plugin，其版本始终包括命令生成内容的哈希。如果你在 `plugin.json` 中声明 `"version": "1.0.0"` 并推送新提交而不改变该字符串，这些源的现有用户保留缓存副本，因为 Claude Code 看到相同的版本。在每个发布时提升该字段，或省略它以回退到解析的版本。1173 设置 `version` 为除了 [`command`](#command-sources) 之外的每个源类型固定 plugin，其版本始终包括命令生成内容的哈希。一个[从 marketplace 加载的 plugin](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution)添加为本地目录也不会被固定。如果你在 `plugin.json` 中声明 `"version": "1.0.0"` 并推送新提交而不改变该字符串，这些源的现有用户保留缓存副本，因为 Claude Code 看到相同的版本。在每个发布时提升该字段，或省略它以回退到解析的版本。

1143 1174

1144 避免在 `plugin.json` 和 marketplace 条目中都设置 `version`。Claude Code 总是无声地使用 `plugin.json` 值，所以陈旧的 manifest 版本可能会掩盖你在 `marketplace.json` 中设置的版本。1175 避免在 `plugin.json` 和 marketplace 条目中都设置 `version`。Claude Code 总是无声地使用 `plugin.json` 值，所以陈旧的 manifest 版本可能会掩盖你在 `marketplace.json` 中设置的版本。

1145</Warning>1176</Warning>

1330**选项：**1361**选项：**

1331 1362

1332| 选项 | 描述 | 默认值 |1363| 选项 | 描述 | 默认值 |

1333| :-------------------- | :----------------------------------------------------------------------------------------------------------------- | :----- |1364| :-------------------- | :--------------------------------------------------------------------------------------------------------------------- | :----- |

1367| `--claudeai` | 将参数读取为 [claude.ai 上托管的 marketplace](/docs/zh-CN/discover-plugins#add-from-claude-ai) 的名称，而不是源。需要 Claude Code v2.1.273 或更高版本 | |

1336 1368

1337从 GitHub 使用 `owner/repo` 简写添加 marketplace：1369从 GitHub 使用 `owner/repo` 简写添加 marketplace：

1338 1370

1376claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins1408claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

1377```1409```

1378 1410

1411添加 [claude.ai 上托管的 marketplace](/docs/zh-CN/discover-plugins#add-from-claude-ai)，使用 `claude plugin marketplace list` 的 `From claude.ai:` 部分中打印的名称：

1412

1413```bash theme={null}

1414claude plugin marketplace add --claudeai claudeai-organization-library

1415```

1416

1417使用 `--claudeai`，命令拒绝 `--scope` 和 `--sparse`。marketplace 为你的账户托管，不在设置文件中声明，所以你无法通过项目的 `.claude/settings.json` 共享它。

1418

1379<h3 id="plugin-marketplace-list">1419<h3 id="plugin-marketplace-list">

1380 Plugin marketplace list1420 Plugin marketplace list

1381</h3>1421</h3>

1394 1434

1395使用 `--json`，每个条目包括 `name`、`source`、一个包含 marketplace 存储的本地缓存路径的 `installLocation` 字段，以及源特定字段：GitHub 源的 `repo`、git 和 URL 源的 `url`，以及本地源的 `path`。当 marketplace 使用固定分支或标签添加时，GitHub 和 git 源也包括 `ref` 字段。1435使用 `--json`，每个条目包括 `name`、`source`、一个包含 marketplace 存储的本地缓存路径的 `installLocation` 字段，以及源特定字段：GitHub 源的 `repo`、git 和 URL 源的 `url`，以及本地源的 `path`。当 marketplace 使用固定分支或标签添加时，GitHub 和 git 源也包括 `ref` 字段。

1396 1436

1437添加的 [claude.ai marketplace](/docs/zh-CN/discover-plugins#add-from-claude-ai) 没有本地克隆，所以其条目使用其 claude.ai 标识符 `marketplaceId` 和 `organizationUuid` 代替 `installLocation`。

1438

1439在 [plugins 从你的 claude.ai 账户同步](/docs/zh-CN/plugins-reference#synced-plugins) 的终端会话中，文本列表以 `From claude.ai:` 部分结尾，命名 claude.ai 为你的账户列出的内容，超出你添加的 marketplaces。要添加其中之一，见 [从 claude.ai 添加](/docs/zh-CN/discover-plugins#add-from-claude-ai)。`--json` 输出仅涵盖配置的 marketplaces，并省略该部分。需要 Claude Code v2.1.273 或更高版本。

1440

1397<h3 id="plugin-marketplace-remove">1441<h3 id="plugin-marketplace-remove">

1398 Plugin marketplace remove1442 Plugin marketplace remove

1399</h3>1443</h3>

1575 1619

1576对于后台自动更新：1620对于后台自动更新：

1577 1621

1578* 默认情况下，后台刷新会为拉取禁用 git 凭证助手，因此拉取无法通过 HTTPS 进行身份验证。在 `ssh-agent` 中加载了密钥的 SSH 远程仍然可以进行身份验证。失败的拉取会触发从头重新克隆，这使用你存储的凭证，但在大型存储库上可能超时1622* 默认情况下，后台刷新会为检查远程禁用 git 凭证助手，因此检查无法通过 HTTPS 进行身份验证。在 `ssh-agent` 中加载了密钥的 SSH 远程仍然可以进行身份验证

1579* 设置 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在后台拉取失败时保留现有克隆1623* 当检查无法进行身份验证时，Claude Code 使用你存储的凭证重新克隆 marketplace，但重新克隆可能在大型存储库上超时

1580* 配置 git 凭证助手，例如 `gh auth setup-git`，以便重新克隆回退可以进行身份验证1624* 设置 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在后台检查无法到达或无法进行身份验证到远程时保留现有检出，而不尝试重新克隆

1625* 配置 git 凭证助手，例如 `gh auth setup-git`，以便重新克隆可以进行身份验证

1581* 如果重新克隆在大型存储库上超时，请使用 [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out) 增加限制1626* 如果重新克隆在大型存储库上超时，请使用 [`CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`](#git-operations-time-out) 增加限制

1582* 配置一个 [git URL 重写](#private-repositories) 作用于 marketplace 存储库，以便后台拉取直接进行身份验证1627* 配置一个 [git URL 重写](#private-repositories) 作用于 marketplace 存储库，以便后台检查直接进行身份验证

1583* 或使用 `/plugin marketplace update <name>` 手动更新私有 marketplaces，这使用你的凭证1628* 或使用 `/plugin marketplace update <name>` 手动更新私有 marketplaces，这使用你的凭证

1584 1629

1585<h3 id="marketplace-updates-fail-in-offline-environments">1630<h3 id="marketplace-updates-fail-in-offline-environments">

1586 Marketplace 更新在离线环境中失败1631 Marketplace 更新在离线环境中失败

1587</h3>1632</h3>

1588 1633

1589**症状**：Marketplace `git pull` 在后台失败，Claude Code 反复尝试无法成功的重新克隆。1634**症状**：在离线或隔离的环境中，后台 marketplace 刷新无法到达远程，Claude Code 反复尝试无法成功的重新克隆。

1635

1636**原因**：后台刷新检查 marketplace 的远程以查找新提交，当检查无法到达远程时，Claude Code 尝试再次克隆 marketplace。离线时，克隆以相同的方式失败，现有检出保持不变。在 v2.1.274 之前，刷新在现有检出中运行 `git pull`，当拉取失败时将检出移到一边以重新克隆，并在事后尽力恢复它。

1590 1637

1591**原因**：默认情况下，当 `git pull` 失败时，Claude Code 会尝试从头重新克隆。在离线或隔离的环境中，重新克隆以相同的方式失败，之后对先前缓存的恢复是尽力而为的。刷新在启动后在后台运行，因此不会延迟启动，但每个会话都会重复失败的尝试，每个 git 操作都可以等待 [120 秒超时](#git-operations-time-out)。1638刷新在启动后在后台运行，因此不会延迟启动。每个会话仍然重复失败的尝试，每个 git 操作可以等待 [120 秒超时](#git-operations-time-out)。

1592 1639

1593**解决方案**：设置 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在拉取失败时跳过重新克隆尝试并继续使用现有缓存：1640**解决方案**：设置 `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1` 以在检查无法到达远程时跳过重新克隆尝试并继续使用现有检出：

1594 1641

1595```bash theme={null}1642```bash theme={null}

1596export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=11643export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

1602 Git 操作超时1649 Git 操作超时

1603</h3>1650</h3>

1604 1651

1605**症状**：Plugin 安装或 marketplace 更新失败，出现超时错误，如"Git clone timed out after 120s"或"Git pull timed out after 120s"。1652**症状**：Plugin 安装或 marketplace 更新失败，出现超时错误，如 `Git clone timed out after 120s`。

1606 1653

1607**原因**：Claude Code 对所有 git 操作使用 120 秒超时，包括克隆 plugin 存储库和拉取 marketplace 更新。大型存储库或缓慢的网络连接可能超过此限制。1654**原因**：Claude Code 对所有 git 操作使用 120 秒超时，包括克隆 plugin 存储库和重新克隆 marketplace 以更新它。大型存储库或缓慢的网络连接可能超过此限制。

1608 1655

1609**解决方案**：使用 `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` 环境变量增加超时。该值以毫秒为单位：1656**解决方案**：使用 `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` 环境变量增加超时。该值以毫秒为单位：

1610 1657

1634 1681

1635**症状**：Plugin 安装但对文件的引用失败，特别是 plugin 目录外的文件1682**症状**：Plugin 安装但对文件的引用失败，特别是 plugin 目录外的文件

1636 1683

1637**原因**：Plugins 被复制到缓存目录而不是就地使用，除了[链接模式中的 `command` 源](#copy-mode-and-link-mode)。引用 plugin 目录外文件的路径（如 `../shared-utils`）不会工作，因为这些文件不会被复制。1684**原因**：Claude Code 将已安装的 plugins 复制到缓存目录，除非 plugin 就地加载。[链接模式中的 `command` 源](#copy-mode-and-link-mode)就地加载，[相对路径源](#relative-paths)在从本地目录添加的 marketplace 中也是如此。引用复制的 plugin 目录外文件的路径（如 `../shared-utils`）不会工作，因为这些文件不会被复制。

1638 1685

1639**解决方案**：见 [Plugin 缓存和文件解析](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution) 了解解决方法，包括符号链接和目录重组。1686**解决方案**：见 [Plugin 缓存和文件解析](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution) 了解解决方法，包括符号链接和目录重组。

1640 1687

plugin-relevance.md +3 −1

Details

86| `filesRead` | array of strings | 与Claude在此会话中读取的文件路径匹配的Glob模式，例如`["**/*.tf"]`。正斜杠规范化且不区分大小写。最多10个模式，每个256个字符。 |86| `filesRead` | array of strings | 与Claude在此会话中读取的文件路径匹配的Glob模式，例如`["**/*.tf"]`。正斜杠规范化且不区分大小写。最多10个模式，每个256个字符。 |

87| `manifestDeps` | array of objects | Claude在此会话中读取的包清单中声明的依赖项。每个条目是`{ "file": "...", "pattern": "..." }`，其中`file`是与清单文件路径匹配的正则表达式（如会话状态中记录的，通常是绝对路径），`pattern`是与该文件内容匹配的正则表达式。在末尾锚定`file`，例如JSON转义形式中的`[/\\\\]package\\.json$`，因为起始锚定的模式永远不会匹配绝对路径。路径对于此信号不进行分隔符规范化，因此Windows路径使用反斜杠。大于512 KB的清单文件会被跳过。两个值都是最多256个字符的JavaScript `RegExp`源字符串。`file`不区分大小写匹配。`pattern`区分大小写。最多10个条目。 |87| `manifestDeps` | array of objects | Claude在此会话中读取的包清单中声明的依赖项。每个条目是`{ "file": "...", "pattern": "..." }`，其中`file`是与清单文件路径匹配的正则表达式（如会话状态中记录的，通常是绝对路径），`pattern`是与该文件内容匹配的正则表达式。在末尾锚定`file`，例如JSON转义形式中的`[/\\\\]package\\.json$`，因为起始锚定的模式永远不会匹配绝对路径。路径对于此信号不进行分隔符规范化，因此Windows路径使用反斜杠。大于512 KB的清单文件会被跳过。两个值都是最多256个字符的JavaScript `RegExp`源字符串。`file`不区分大小写匹配。`pattern`区分大小写。最多10个条目。 |

88 88

89`cli`、`hosts`、`filesRead`和`manifestDeps`信号需要会话历史记录，因此它们只能在spinner提示和Discover标签页上匹配。`filesRead`和`manifestDeps`信号测试会话的记录文件状态，其中还包括Claude已写入或编辑的文件以及自动加载的`CLAUDE.md`内存文件。89`cli`、`hosts`、`filesRead`和`manifestDeps`信号需要会话历史记录，因此它们只能在spinner提示和Discover标签页上匹配。

91`filesRead`和`manifestDeps`信号测试会话的记录文件状态，其中还包括Claude已写入或编辑的文件以及自动加载的`CLAUDE.md`内存文件。对于这两个信号，Claude Code会跳过其自身[配置目录](/docs/zh-CN/claude-directory)及其临时目录下的路径。

90 92

91以下示例使用`manifestDeps`在Claude读取了依赖于`stripe`的`package.json`后建议Stripe插件。`file`模式使用`[/\\\\]`以匹配正斜杠和反斜杠路径分隔符，使用`\\.`以使点为字面。在JSON中，正则表达式中的每个反斜杠都写两次。93以下示例使用`manifestDeps`在Claude读取了依赖于`stripe`的`package.json`后建议Stripe插件。`file`模式使用`[/\\\\]`以匹配正斜杠和反斜杠路径分隔符，使用`\\.`以使点为字面。在JSON中，正则表达式中的每个反斜杠都写两次。

92 94

plugins.md +2 −2

Details

75 ```75 ```

76 76

77 | 字段 | 目的 |77 | 字段 | 目的 |

78 | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |78 | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

81 | `version` | 可选。如果设置，用户仅在你更新此字段时接收更新，除了 [`command` 源](/docs/zh-CN/plugin-marketplaces#command-sources)；请参阅[版本管理](/docs/zh-CN/plugins-reference#version-management)。如果省略，版本来自[版本管理](/docs/zh-CN/plugins-reference#version-management)中的下一个源。 |81 | `version` | 可选。如果设置，用户仅在你更新此字段时接收更新，除了 [`command` 源](/docs/zh-CN/plugin-marketplaces#command-sources)或[就地加载](/docs/zh-CN/plugins-reference#plugin-caching-and-file-resolution)的插件；请参阅[版本管理](/docs/zh-CN/plugins-reference#version-management)。如果省略，版本来自[版本管理](/docs/zh-CN/plugins-reference#version-management)中的下一个源。 |

83 83

84 有关 `homepage`、`repository` 和 `license` 等其他字段，请参阅[完整清单架构](/docs/zh-CN/plugins-reference#plugin-manifest-schema)。84 有关 `homepage`、`repository` 和 `license` 等其他字段，请参阅[完整清单架构](/docs/zh-CN/plugins-reference#plugin-manifest-schema)。

plugins-reference.md +27 −11

Details

71Detailed system prompt for the agent describing its role, expertise, and behavior.71Detailed system prompt for the agent describing its role, expertise, and behavior.

72```72```

73 73

74插件代理支持 `name`、`description`、`model`、`effort`、`maxTurns`、`tools`、`disallowedTools`、`skills`、`memory`、`background` 和 `isolation` frontmatter 字段。唯一有效的 `isolation` 值是 `"worktree"`。出于安全原因，插件提供的代理不支持 `hooks`、`mcpServers` 和 `permissionMode`。74插件代理支持 `name`、`description`、`model`、`effort`、`maxTurns`、`tools`、`disallowedTools`、`skills`、`memory`、`background`、[`omitClaudeMd`](/docs/zh-CN/sub-agents#supported-frontmatter-fields) 和 `isolation` frontmatter 字段。唯一有效的 `isolation` 值是 `"worktree"`。

76出于安全原因，插件提供的代理不支持 `hooks`、`mcpServers` 或 `permissionMode`。

75 77

76Claude Code 会加载插件代理，即使其 frontmatter 没有 `name` 或无法解析：78Claude Code 会加载插件代理，即使其 frontmatter 没有 `name` 或无法解析：

77 79

444 446

445通过 `claude plugin list` 打印的 `<name>@synced` ID 来管理同步的插件：447通过 `claude plugin list` 打印的 `<name>@synced` ID 来管理同步的插件：

446 448

447* **关闭一个插件**：在同步会话中，运行 `claude plugin disable <name>@synced`，或要求 Claude 运行它。Claude Code 会将该选择保存为该环境的用户级 [`enabledPlugins`](/docs/zh-CN/settings-reference#enabledplugins) 中的 `"<name>@synced": false`。要重新打开该插件，在同一会话中运行 `claude plugin enable <name>@synced`。要将插件排除在每个同步会话之外，[为你的 claude.ai 账户关闭它](/docs/zh-CN/desktop#extend-claude-code)。要将其排除在一个项目的每个环境中的同步会话之外，在该项目的已提交 `.claude/settings.json` 中的 `enabledPlugins` 下设置 `"<name>@synced": false`。449* **关闭一个插件**：在同步会话中，运行 `claude plugin disable <name>@synced`，或要求 Claude 运行它。Claude Code 会将该选择保存为该环境的用户级 [`enabledPlugins`](/docs/zh-CN/settings-reference#enabledplugins) 中的 `"<name>@synced": false`。你的组织要求的同步插件无法通过这种方式关闭。该命令会报告该插件是你的组织所需的，并且不会保存任何内容。要重新打开该插件，在同一会话中运行 `claude plugin enable <name>@synced`。

450* **将一个插件排除在同步会话之外**：要将一个插件排除在每个同步会话之外，[为你的 claude.ai 账户关闭它](/docs/zh-CN/desktop#extend-claude-code)。要将其排除在一个项目的每个环境中的同步会话之外，在该项目的已提交 `.claude/settings.json` 中的 `enabledPlugins` 下设置 `"<name>@synced": false`。

448* **在 claude.ai 上管理插件本身**：`claude plugin install`、`update` 和 `uninstall` 不适用于同步的插件。要删除一个，为你的 claude.ai 账户关闭该插件；下一个同步会话将在没有它的情况下启动。451* **在 claude.ai 上管理插件本身**：`claude plugin install`、`update` 和 `uninstall` 不适用于同步的插件。要删除一个，为你的 claude.ai 账户关闭该插件；下一个同步会话将在没有它的情况下启动。

449 452

450当来自任何其他来源的启用插件（例如 marketplace 安装、[skills-directory 插件](#skills-directory-plugins)或 `--plugin-dir` 插件）与同步插件的名称匹配时，Claude Code 会加载该插件并报告同步副本未加载。要改用 claude.ai 副本，请禁用你自己的副本。在 v2.1.239 之前，Claude Code 会加载同步副本而不是同名的 marketplace 安装。453当来自任何其他来源的启用插件（例如 marketplace 安装、[skills-directory 插件](#skills-directory-plugins)或 `--plugin-dir` 插件）与同步插件的名称匹配时，Claude Code 会加载该插件并报告同步副本未加载。要改用 claude.ai 副本，请禁用你自己的副本。在 v2.1.239 之前，Claude Code 会加载同步副本而不是同名的 marketplace 安装。

553 556

554在 `plugin.json` 中设置 `defaultEnabled: false` 以发布已禁用安装的 plugin。用户使用 `claude plugin enable <plugin>` 或 `/plugin` 界面将其打开。对于添加成本或用户应该选择加入的范围的 plugin 使用此选项，例如连接到外部服务的 plugin。557在 `plugin.json` 中设置 `defaultEnabled: false` 以发布已禁用安装的 plugin。用户使用 `claude plugin enable <plugin>` 或 `/plugin` 界面将其打开。对于添加成本或用户应该选择加入的范围的 plugin 使用此选项，例如连接到外部服务的 plugin。

555 558

556`defaultEnabled` 是当没有其他因素决定 plugin 状态时的后备。两件事优先于它：559`defaultEnabled` 是当没有其他因素决定 plugin 状态时的后备。用户的设置和依赖项要求优先于它：

557 560

558* **用户的设置**：任何设置范围内 `enabledPlugins` 中的 plugin 条目。一旦写入，它会在 plugin 更新和重新安装中持续存在，因此在后续版本中更改 `defaultEnabled` 不会翻转现有用户。561* **用户的设置**：任何设置范围内 `enabledPlugins` 中的 plugin 条目。一旦写入，它会在 plugin 更新和重新安装中持续存在，因此在后续版本中更改 `defaultEnabled` 不会翻转现有用户。

559* **依赖项要求**：当 plugin 被另一个活跃的 plugin 需要时，Claude Code 在安装或启用时为其写入 `true`。这给了它一个显式设置，所以它自己的默认值不再适用。请参阅[启用或禁用具有依赖项的 plugin](/docs/zh-CN/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)。562* **依赖项要求**：当 plugin 被另一个活跃的 plugin 需要时，Claude Code 在安装或启用时为其写入 `true`。这给了它一个显式设置，所以它自己的默认值不再适用。请参阅[启用或禁用具有依赖项的 plugin](/docs/zh-CN/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)。

582| `dependencies` | array | 此 plugin 需要的其他 plugin，可选择带有 semver 版本约束。请参阅[约束 plugin 依赖项版本](/docs/zh-CN/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |585| `dependencies` | array | 此 plugin 需要的其他 plugin，可选择带有 semver 版本约束。请参阅[约束 plugin 依赖项版本](/docs/zh-CN/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |

583 586

584<h3 id="experimental-components">587<h3 id="experimental-components">

614键必须是有效的标识符。每个选项支持这些字段：617键必须是有效的标识符。每个选项支持这些字段：

615 618

616| 字段 | 必需 | 描述 |619| 字段 | 必需 | 描述 |

617| :------------ | :- | :-------------------------------------------------- |620| :------------ | :- | :---------------------------------------------------------------------- |

618| `type` | 是 | `string`、`number`、`boolean`、`directory` 或 `file` 之一 |621| `type` | 是 | `string`、`number`、`boolean`、`directory` 或 `file` 之一 |

619| `title` | 是 | 在配置对话框中显示的标签 |622| `title` | 是 | 在配置对话框中显示的标签 |

620| `description` | 是 | 在字段下方显示的帮助文本 |623| `description` | 是 | 在字段下方显示的帮助文本 |

621| `sensitive` | 否 | 如果为 `true`，掩盖输入并将值存储在安全存储中而不是 `settings.json` |624| `sensitive` | 否 | 如果为 `true`，掩盖输入并将值存储在安全存储中而不是 `settings.json` |

622| `required` | 否 | 如果为 `true`，当字段为空时验证失败 |625| `required` | 否 | 如果为 `true`，当字段为空时验证失败 |

623| `default` | 否 | 当用户未提供任何内容时使用的值 |626| `default` | 否 | 当用户未提供任何内容时使用的值 |

627| `options` | 否 | 对于 `string` 类型，字段接受的值，在 `/config` 中显示为选择器。需要 Claude Code v2.1.271 或更高版本 |

624| `multiple` | 否 | 对于 `string` 类型，允许字符串数组 |628| `multiple` | 否 | 对于 `string` 类型，允许字符串数组 |

625| `min` / `max` | 否 | `number` 类型的边界 |629| `min` / `max` | 否 | `number` 类型的边界 |

626 630

631除了 `sensitive` 字段和 `multiple` 列表外，每个启用的 plugin 的每个字段也作为一行出现在 `/config` 面板中。这些行需要 Claude Code v2.1.269 或更高版本。

632

627每个值都可用于在 MCP 和 LSP 服务器配置以及 hook 命令中作为 `${user_config.KEY}` 进行替换。非敏感值也可以在 skill 和 agent 内容中替换。所有值都作为 `CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量导出到 hook 进程，其中 `<KEY>` 是选项键的大写形式。633每个值都可用于在 MCP 和 LSP 服务器配置以及 hook 命令中作为 `${user_config.KEY}` 进行替换。非敏感值也可以在 skill 和 agent 内容中替换。所有值都作为 `CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量导出到 hook 进程，其中 `<KEY>` 是选项键的大写形式。

628 634

629在 shell 中运行的字段拒绝 `${user_config.*}`：将配置的值替换到 shell 命令中会让 shell 运行该值包含的任何内容，因此组件失败并出现[错误](/docs/zh-CN/errors#plugin-command-references-user-config)。每个被拒绝的字段都有一种替代方式来传递值：635在 shell 中运行的字段拒绝 `${user_config.*}`：将配置的值替换到 shell 命令中会让 shell 运行该值包含的任何内容，因此组件失败并出现[错误](/docs/zh-CN/errors#plugin-command-references-user-config)。每个被拒绝的字段都有一种替代方式来传递值：

1061该命令接受这些选项：1067该命令接受这些选项：

1062 1068

1063| 选项 | 描述 | 默认值 |1069| 选项 | 描述 | 默认值 |

1064| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |1070| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |

1067| `-y, --yes` | 接受插件市场声明的命令，无需确认提示：生成具有 [`command` source](/docs/zh-CN/plugin-marketplaces#command-sources) 的插件的命令，或验证存档下载的 [`headersHelper`](/docs/zh-CN/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更高版本。Claude Code 仍会首先打印命令。当 stdin 或 stdout 不是 TTY 时需要。在 Claude Code 会话内无效，因此从您自己的终端运行命令 | |1073| `-y, --yes` | 接受插件市场声明的命令，无需确认提示：生成具有 [`command` source](/docs/zh-CN/plugin-marketplaces#command-sources) 的插件的命令，或验证存档下载的 [`headersHelper`](/docs/zh-CN/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更高版本。Claude Code 仍会首先打印命令。当 stdin 或 stdout 不是 TTY 时需要，除非您传递 `--accept-command`。在 Claude Code 会话内无效，因此从您自己的终端运行命令 | |

1074| `--accept-command <sha256>` | 接受市场声明的命令，其 `sha256` 之前的 [`--json` 运行](#plugin-json-result) 在 `shownCommand` 中报告，代替 `-y`。接受计数仅适用于该特定命令、插件和市场目录。如果自命令显示以来其中任何一个已更改，包括通过运行自己的市场刷新，Claude Code 不接受摘要并再次显示命令。不能与 `-y` 组合。在 Claude Code 会话内无效，因此从您自己的终端运行命令。需要 Claude Code v2.1.271 或更高版本 | |

1068| `--json` | 将结果作为 stdout 最后一行的一个 JSON 对象打印，用于脚本。请参阅 [JSON result format](#plugin-json-result)。需要 Claude Code v2.1.268 或更高版本 | |1075| `--json` | 将结果作为 stdout 最后一行的一个 JSON 对象打印，用于脚本。请参阅 [JSON result format](#plugin-json-result)。需要 Claude Code v2.1.268 或更高版本 | |

1070 1077

1078 1085

1079其他字段，例如 `pluginId`、`scope` 和 `failureCode`，仅在适用时出现。`plugin uninstall`、`plugin update`、`plugin enable` 和 `plugin disable` 上的 `--json` 选项打印具有该子命令自己字段的相同对象。使用错误，例如无效的 `--scope`，不打印结果行并以 stderr 上的原因退出 1。1086其他字段，例如 `pluginId`、`scope` 和 `failureCode`，仅在适用时出现。`plugin uninstall`、`plugin update`、`plugin enable` 和 `plugin disable` 上的 `--json` 选项打印具有该子命令自己字段的相同对象。使用错误，例如无效的 `--scope`，不打印结果行并以 stderr 上的原因退出 1。

1080 1087

1088当运行显示市场声明的命令且不运行它时，`failed` 结果也会携带一个 `shownCommand` 对象，其字段包括显示的命令、它所属的插件和命令的 `sha256`。要接受完全相同的命令，使用该 `sha256` 作为 `--accept-command` 重新运行。需要 Claude Code v2.1.271 或更高版本。

1089

1090如果 `shownCommand.acceptCommandMatched` 是 `false`，您传递的摘要与现在显示的命令不匹配。在传递其 `sha256` 之前向某人显示该命令。

1091

1081这些示例显示常见的调用：1092这些示例显示常见的调用：

1082 1093

1083```bash theme={null}1094```bash theme={null}

1173 plugin disable1184 plugin disable

1174</h3>1185</h3>

1175 1186

1176禁用插件而不卸载它。当目标从市场安装时，如果另一个启用的插件[依赖](/docs/zh-CN/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)它，该命令会失败。错误消息包含一个链式命令，首先禁用每个依赖它的插件。1187禁用插件而不卸载它。

1188

1189当目标从市场安装时，如果另一个启用的插件[依赖](/docs/zh-CN/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies)它，该命令会失败。错误消息包含一个链式命令，首先禁用每个依赖它的插件。

1190

1191对于您的组织需要的[同步插件](#synced-plugins)，该命令会失败并且不保存任何内容。

1177 1192

1178```bash theme={null}1193```bash theme={null}

1179claude plugin disable [plugin] [options]1194claude plugin disable [plugin] [options]

1209该命令接受这些选项：1224该命令接受这些选项：

1210 1225

1211| 选项 | 描述 | 默认值 |1226| 选项 | 描述 | 默认值 |

1212| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |1227| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----- |

1214| `-y, --yes` | 接受插件市场声明的命令，无需确认提示：生成具有 [`command` source](/docs/zh-CN/plugin-marketplaces#command-sources) 的插件的命令，或验证存档下载的 [`headersHelper`](/docs/zh-CN/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更高版本。Claude Code 仍会首先打印命令。当 stdin 或 stdout 不是 TTY 时需要。在 Claude Code 会话内无效，因此从您自己的终端运行命令 | |1229| `-y, --yes` | 接受插件市场声明的命令，无需确认提示：生成具有 [`command` source](/docs/zh-CN/plugin-marketplaces#command-sources) 的插件的命令，或验证存档下载的 [`headersHelper`](/docs/zh-CN/plugin-marketplaces#authenticate-archive-downloads)。接受 `headersHelper` 需要 Claude Code v2.1.238 或更高版本。Claude Code 仍会首先打印命令。当 stdin 或 stdout 不是 TTY 时需要，除非您传递 `--accept-command`。在 Claude Code 会话内无效，因此从您自己的终端运行命令 | |

1230| `--accept-command <sha256>` | 接受市场声明的命令，其 `sha256` 之前的 [`--json` 运行](#plugin-json-result) 在 `shownCommand` 中报告，代替 `-y`。接受计数仅适用于该特定命令、插件和市场目录。如果自命令显示以来其中任何一个已更改，包括通过运行自己的市场刷新，Claude Code 不接受摘要并再次显示命令。不能与 `-y` 组合。在 Claude Code 会话内无效，因此从您自己的终端运行命令。需要 Claude Code v2.1.271 或更高版本 | |

1215| `--json` | 将结果作为 stdout 最后一行的一个 JSON 对象打印，格式与 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更高版本 | |1231| `--json` | 将结果作为 stdout 最后一行的一个 JSON 对象打印，格式与 [`plugin install --json`](#plugin-json-result) 相同。需要 Claude Code v2.1.268 或更高版本 | |

1217 1233

prompt-caching.md +3 −3

Details

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

264 更改输出样式264 更改输出样式

265</h3>265</h3>

266 266

267当您在会话中使用 `/config` 或 `outputStyle` 设置切换[输出样式](/docs/zh-CN/output-styles)时，Claude 从您的下一条消息开始使用新样式。Claude Code 将新样式的指令作为对话中的消息传递，所以该请求仍然从缓存中读取系统提示和早期对话。267当您在会话中使用 [`/output-style`](/docs/zh-CN/output-styles#change-your-output-style)、`/config` 或 `outputStyle` 设置切换[输出样式](/docs/zh-CN/output-styles)时，Claude 从您的下一条消息开始使用新样式。Claude Code 将新样式的指令作为对话中的消息传递，所以该请求仍然从缓存中读取系统提示和早期对话。

268 268

269在 v2.1.251 之前，中途样式切换保持缓存但直到您运行 `/clear` 或启动新会话时才应用。269在 v2.1.251 之前，中途样式切换保持缓存但直到您运行 `/clear` 或启动新会话时才应用。

270 270

294 294

295当你[恢复会话](/docs/zh-CN/sessions#resume-a-session)时，Claude Code 会重新发送整个对话，请求会从缓存中读取其前缀中未更改且仍在[缓存生命周期](#cache-lifetime)内的任何部分。本页顶部的层表说明了每一层的变化。295当你[恢复会话](/docs/zh-CN/sessions#resume-a-session)时，Claude Code 会重新发送整个对话，请求会从缓存中读取其前缀中未更改且仍在[缓存生命周期](#cache-lifetime)内的任何部分。本页顶部的层表说明了每一层的变化。

296 296

297系统提示词会在[Claude Code 升级](#upgrading-claude-code)后或在恢复时使用不同的[`--append-system-prompt`](/docs/zh-CN/cli-reference#system-prompt-flags)文本时发生变化。默认情况下，恢复的对话会保持其启动时的系统提示词，因此其历史记录仍然位于相同的提示词后面，更改会在对话被压缩或在新对话中生效。[恢复的对话中的系统提示词标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)涵盖了`--system-prompt-snapshot off`和裸模式，其中这不适用。297系统提示词会在[Claude Code 升级](#upgrading-claude-code)后或在恢复时使用不同的[`--append-system-prompt`](/docs/zh-CN/cli-reference#system-prompt-flags)文本时发生变化。默认情况下，恢复的对话会保持其启动时的系统提示词，因此其历史记录仍然位于相同的提示词后面，更改会在对话被压缩或在新对话中生效。[恢复的对话中的系统提示词标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)涵盖了系统提示词标志在恢复的对话中的情况。

298 298

299<h2 id="cache-lifetime">299<h2 id="cache-lifetime">

300 缓存生命周期300 缓存生命周期

remote-control.md +58 −61

Details

46 46

47<Tabs>47<Tabs>

48 <Tab title="服务器模式">48 <Tab title="服务器模式">

~~49 导航到您的项目目录并运行：~~49 在您的项目目录中，运行：

50 50

51 ```bash theme={null}51 ```bash theme={null}

52 claude remote-control52 claude remote-control

132 检查连接状态132 检查连接状态

133</h3>133</h3>

134 134

135在交互式终端会话中，当连接处于活动状态时，`/rc active` 指示器显示，如果终端太窄无法容纳它，则隐藏。使用[全屏渲染](/docs/zh-CN/fullscreen)时，它位于启动标头中的工作目录行的末尾，没有它时，位于输入框下方的页脚中。135在交互式会话中，当 Remote Control 连接时，终端显示一个 `/rc active` 指示器，该指示器链接到 claude.ai 上的会话。当终端太窄无法容纳它时，指示器被隐藏。要查看会话 URL 和 QR 码以[从另一个设备连接](#connect-from-another-device)，请再次运行 `/remote-control` 以打开状态面板。该面板还允许您在本地会话继续运行时断开 Remote Control。

136 136

137指示器文本是指向 claude.ai 上会话的链接。再次运行 `/remote-control` 以打开状态面板，其中包含会话 URL 和 QR 码，用于[从另一个设备连接](#connect-from-another-device)。当指示器在页脚中时，您也可以使用向下箭头键选择指示器并按 Enter 来打开面板。面板还提供断开连接选项，该选项关闭 Remote Control，同时您的本地会话继续在终端中运行。137<span id="session-ended-elsewhere" />如果连接在交互式会话中失败，指示器会改变以显示失败，Claude Code 会在通知中显示原因并将其添加到对话中。运行 `/remote-control` 以重新连接，除非原因说会话在其他地方改变：

138 138

139如果连接失败，Claude Code 会显示一条通知，说明失败原因，向对话添加一条带有原因的警告行，并将指示器切换到保留在原位的失败状态。要重新连接，请运行 `/remote-control`，除非[原因说会话在其他地方被接管或结束，或服务器找不到它](#session-ended-elsewhere)。139* **另一个连接接管了此会话**：另一个设备或 Claude Code 会话现在拥有它。仅当您想从它收回时才运行 `/remote-control`。

~~140~~ 140* **此会话从另一个设备或应用被结束或存档**：仅当您想要它回来时才运行 `/remote-control`。Claude Code 会重新打开存档的会话。

141<span id="session-ended-elsewhere" />在重新连接之前读取原因。当会话从另一个设备、应用或 Claude Code 会话被接管或结束，或服务器找不到它时，原因会说明是哪种情况，Claude Code 会省略其通常的建议来运行 `/remote-control`：141* **服务器不再报告此会话**：它可能已从另一个设备或应用中删除。

~~142~~

143* **另一个设备或 Claude Code 会话接管了会话**：仅当您想从该设备收回它时才运行 `/remote-control`。

144* **您从另一个设备或应用结束或存档了会话**：仅当您想要它回来时才运行 `/remote-control`；Claude Code 会重新打开存档的会话。

145* **服务器找不到会话**：它可能已从另一个设备或应用中删除。

146 142

147<h3 id="session-url-reminders">143<h3 id="session-url-reminders">

148 会话 URL 提醒144 会话 URL 提醒

178 174

179当您从 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 本身中运行）在任何版本上设置名称。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 本身中运行）在任何版本上设置名称。

180 176

181如果您还没有 Claude 应用，请在 Claude Code 中使用 `/mobile` 命令显示 [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 或 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) 的下载 QR 码。177如果您还没有 Claude 应用，请在 Claude Code 中运行 `/mobile` 以显示 QR 码以访问 [claude.ai/mobile](https://claude.ai/mobile)，这会打开您手机的正确应用商店。

182 178

183<h3 id="what-connected-devices-see">179<h3 id="what-connected-devices-see">

184 连接的设备看到什么180 连接的设备看到什么

188 184

189* **压缩和 `/clear`**：当 Claude Code [压缩对话](/docs/zh-CN/context-window#what-survives-compaction)时，连接的设备显示进度，然后显示对话被压缩的位置。当您运行 `/clear` 时，对话也会在连接的设备上重置。185* **压缩和 `/clear`**：当 Claude Code [压缩对话](/docs/zh-CN/context-window#what-survives-compaction)时，连接的设备显示进度，然后显示对话被压缩的位置。当您运行 `/clear` 时，对话也会在连接的设备上重置。

190* **使用 `/resume` 切换对话**：连接的设备不会接收切换到的对话的标题或早期历史记录，但双向的新消息会进出您的终端中打开的任何对话。要再次从设备处理原始对话，请在您的终端中运行 `/resume` 并切换回它。186* **使用 `/resume` 切换对话**：连接的设备不会接收切换到的对话的标题或早期历史记录，但双向的新消息会进出您的终端中打开的任何对话。要再次从设备处理原始对话，请在您的终端中运行 `/resume` 并切换回它。

191* **使用 `/teleport` 拉取会话**：当您使用 `/teleport` 将[Claude Code on the web 会话](/docs/zh-CN/claude-code-on-the-web#from-web-to-terminal)拉入您的终端时，连接的设备不会接收拉取的对话的早期历史记录。双向的新消息会进出拉取的对话，这现在是您的终端中打开的对话。187* **使用 `/teleport` 拉取会话**：当您使用 `/teleport` 将[云会话](/docs/zh-CN/claude-code-on-the-web#from-cloud-to-terminal)拉入您的终端时，连接的设备不会接收拉取的对话的早期历史记录。双向的新消息会进出拉取的对话，这现在是您的终端中打开的对话。

192* **来自您其他会话的消息**：使用[跨会话消息传递](/docs/zh-CN/cross-session-messaging)，相同的连接在您不同机器上的自己的会话之间以及来自您的[Claude Code on the web](/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 或更高版本。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 或更高版本。

193* **您在回合中途发送的提示**：当您在当前回合结束之前从连接的设备发送提示时，Claude Code 会将其排队并在该回合完成后将其保留在设备的记录中。189* **您在回合中途发送的提示**：当您在当前回合结束之前从连接的设备发送提示时，Claude Code 会将其排队并在该回合完成后将其保留在设备的记录中。

194* **您的更改的差异**：当会话的目录在 git 存储库中时，连接的设备的差异窗格显示您未提交更改的差异。设备通过连接请求差异，Claude Code 在您的机器上计算它。当您的工作树是干净的时，Claude Code 改为提供您的分支自从它从默认分支分叉以来的更改。在 v2.1.247 之前，Claude Code 仅向由 `claude remote-control` 提供的会话中的连接设备报告差异。190* **您的更改的差异**：当会话的目录在 git 存储库中时，连接的设备的差异窗格显示您未提交更改的差异。设备通过连接请求差异，Claude Code 在您的机器上计算它。当您的工作树是干净的时，Claude Code 改为提供您的分支自从它从默认分支分叉以来的更改。在 v2.1.247 之前，Claude Code 仅向由 `claude remote-control` 提供的会话中的连接设备报告差异。

195* **模型**：当您从连接的设备选择[模型](/docs/zh-CN/model-config)时，Claude Code 在该模型上运行会话。终端的 `/model` 选择器、`/status` 和 `/config` 显示该模型。需要 Claude Code v2.1.238 或更高版本。191* **模型**：当您从连接的设备选择[模型](/docs/zh-CN/model-config)时，Claude Code 在该模型上运行会话。终端的 `/model` 选择器、`/status` 和 `/config` 显示该模型。需要 Claude Code v2.1.238 或更高版本。

312 308

313对于丢失或被盗的设备，成员从此页面删除它。如果成员无法登录，管理员可以在管理员控制台中使用**到处登出**为该成员撤销每个会话和已注册设备，之后成员重新注册他们仍然持有的设备。309对于丢失或被盗的设备，成员从此页面删除它。如果成员无法登录，管理员可以在管理员控制台中使用**到处登出**为该成员撤销每个会话和已注册设备，之后成员重新注册他们仍然持有的设备。

314 310

315<h2 id="remote-control-vs-claude-code-on-the-web">311<h2 id="remote-control-vs-cloud-sessions">

316 Remote Control 与网络上的 Claude Code 的比较312 Remote Control 与云会话的比较

317</h2>313</h2>

318 314

319Remote Control 和[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)都使用 claude.ai/code 界面。关键区别在于会话运行的位置：Remote Control 在您的机器上执行，因此您的本地 MCP servers、工具和项目配置保持可用。网络上的 Claude Code 在云中执行。315Remote Control 和[云会话](/docs/zh-CN/claude-code-on-the-web)都使用 claude.ai/code 界面。关键区别在于会话运行的位置：Remote Control 在您的机器上执行，因此您的本地 MCP 服务器、工具和项目配置保持可用。云会话在云基础设施上执行，默认由 Anthropic 管理。

320 316

321当您处于本地工作中间并想从另一个设备继续时，使用 Remote Control。当您想在没有任何本地设置的情况下启动任务、处理您没有克隆的存储库或并行运行多个任务时，使用网络上的 Claude Code。317当您处于本地工作中间并想从另一个设备继续时，使用 Remote Control。当您想在没有任何本地设置的情况下启动任务、处理您没有克隆的存储库或并行运行多个任务时，使用云会话。

322 318

323<h2 id="mobile-push-notifications">319<h2 id="mobile-push-notifications">

324 移动推送通知320 移动推送通知

374 * 文本输出命令：`/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/usage-credits`、`/recap` 和 `/reload-plugins`。`/usage-credits` 打印计费 URL 而不是打开浏览器。`/reload-plugins` 仅在会话在交互式终端中运行时工作；没有交互式终端的会话会拒绝它。370 * 文本输出命令：`/compact`、`/clear`、`/context`、`/usage`、`/exit`、`/usage-credits`、`/recap` 和 `/reload-plugins`。`/usage-credits` 打印计费 URL 而不是打开浏览器。`/reload-plugins` 仅在会话在交互式终端中运行时工作；没有交互式终端的会话会拒绝它。

375 * `/model`、`/effort`、`/fast`、`/color` 和 `/rename`：将值作为参数传递，例如 `/model sonnet` 或 `/effort high`。从移动和网络，`/model` 和 `/effort` 在终端选择器或滑块的位置接受参数。371 * `/model`、`/effort`、`/fast`、`/color` 和 `/rename`：将值作为参数传递，例如 `/model sonnet` 或 `/effort high`。从移动和网络，`/model` 和 `/effort` 在终端选择器或滑块的位置接受参数。

376 * `/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` 会重新连接每个已失败或需要身份验证的服务器。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 * `/config`，从 v2.1.181 开始：从移动应用，传递 `key=value` 以设置一个设置，或不带参数运行它以列出您可以设置的键。在网络上，`/config` 打开您设置的 Claude Code 部分，并忽略命令后的文本。373 * `/config`：从移动应用，传递 `key=value` 以设置一个设置，或不带参数运行它以列出您可以设置的键。在网络上，`/config` 打开您设置的 Claude Code 部分，并忽略命令后的文本。

378 * 在 Team 和 Enterprise 上，从移动或网络运行的 `/usage-credits` 不会向您的管理员发送[使用额度请求](/docs/zh-CN/costs#add-usage-credits-to-your-subscription)。发送需要仅在交互式 CLI 中出现的确认，因此命令告诉您改为在那里运行它。在 v2.1.211 之前，文本形式在没有确认的情况下发送请求。374 * 在 Team 和 Enterprise 上，从移动或网络运行的 `/usage-credits` 不会向您的管理员发送[使用额度请求](/docs/zh-CN/costs#add-usage-credits-to-your-subscription)。发送需要仅在交互式 CLI 中出现的确认，因此命令告诉您改为在那里运行它。在 v2.1.211 之前，文本形式在没有确认的情况下发送请求。

379 * `/autocompact`，从 v2.1.221 开始：将窗口大小作为参数传递，例如 `/autocompact 500k`。不带参数时，它将当前窗口大小打印为文本，而不是打开命令在终端会话中显示的对话框。375 * `/autocompact`，从 v2.1.221 开始：将窗口大小作为参数传递，例如 `/autocompact 500k`。不带参数时，它将当前窗口大小打印为文本，而不是打开命令在终端会话中显示的对话框。

380 * `/advisor`，从 v2.1.260 开始：将模型作为参数传递，例如 `/advisor opus`，或传递 `off` 以关闭顾问。两种形式都仅适用于当前会话，并保持您保存的默认值不变。不带参数时，它将当前顾问打印为文本，而不是打开选择器。376 * `/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)，请在会话本身中选择它。

381 378

382<h2 id="troubleshooting">379<h2 id="troubleshooting">

383 故障排除380 故障排除

384</h2>381</h2>

385 382

386<h3 id="remote-control-requires-a-claude-ai-subscription">383<h3 id="remote-control-requires-a-claude-ai-subscription">

387 "Remote Control 需要 claude.ai 订阅"384 "Remote Control requires a claude.ai subscription"

388</h3>385</h3>

389 386

390您未使用 claude.ai 账户进行身份验证，或另一个凭证优先于您的登录。该消息采用以下形式之一：387您未使用 claude.ai 账户登录，或者另一个凭证优先于您的登录。该消息采用以下形式之一：

391 388

392* 已登出，来自 `/remote-control` 或 `--remote-control`：`Remote Control requires a claude.ai subscription.`389* 已登出，来自 `/remote-control` 或 `--remote-control`：`Remote Control requires a claude.ai subscription.` 或 `/remote-control requires a claude.ai subscription.`

393* 已登出，来自 `claude remote-control`：`You must be logged in to use Remote Control. Remote Control is only available with claude.ai subscriptions.`390* 已登出，来自 `claude remote-control`：`You must be logged in to use Remote Control. Remote Control is only available with claude.ai subscriptions.`

394* 已登入，但正在使用 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` 的命名方式相同。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` 的命名方式相同。

395 392

396运行 `claude auth login` 并选择 claude.ai 选项。如果消息名称为 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，请在设置它的任何地方删除它：您的 shell 环境或[设置文件](/docs/zh-CN/settings-reference#env)的 `env` 块。如果它名称为 `apiKeyHelper`，请删除该设置。393运行 `claude auth login` 并选择 claude.ai 选项。如果消息中提到 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，请在设置它的任何地方删除它：您的 shell 环境或[设置文件](/docs/zh-CN/settings-reference#env)的 `env` 块。如果消息中提到 `apiKeyHelper`，请删除该设置。

397 394

398在 v2.1.206 之前，在未登录的情况下运行 `/remote-control` 会报告 `Unknown command: /remote-control` 而不是此消息。395在 v2.1.206 之前，在已登出时运行 `/remote-control` 会报告 `Unknown command: /remote-control` 而不是此消息。

399 396

400<h3 id="remote-control-requires-a-full-scope-login-token">397<h3 id="remote-control-requires-a-full-scope-login-token">

401 "Remote Control 需要完整范围的登录令牌"398 "Remote Control requires a full-scope login token"

402</h3>399</h3>

403 400

404您使用来自 `claude setup-token` 或 `CLAUDE_CODE_OAUTH_TOKEN` 环境变量的长期令牌进行身份验证。这些令牌仅限于进行模型请求，因此无法建立 Remote Control 会话。运行 `claude auth login` 以改用完整范围的会话令牌进行身份验证。401您使用的是来自 `claude setup-token` 或 `CLAUDE_CODE_OAUTH_TOKEN` 环境变量的长期令牌进行身份验证。这些令牌只能发出模型请求，因此无法建立 Remote Control 会话。运行 `claude auth login` 以改用完整范围的会话令牌进行身份验证。

405 402

406<h3 id="unable-to-determine-your-organization-for-remote-control-eligibility">403<h3 id="unable-to-determine-your-organization-for-remote-control-eligibility">

407 "无法确定您的组织以进行 Remote Control 资格检查"404 "Unable to determine your organization for Remote Control eligibility"

408</h3>405</h3>

409 406

410您的缓存账户信息已过期或不完整。运行 `claude auth login` 以刷新它。407您的缓存账户信息已过期或不完整。运行 `claude auth login` 以刷新它。

411 408

412<h3 id="remote-control-isn’t-enabled-for-this-account">409<h3 id="remote-control-isn’t-enabled-for-this-account">

413 "Remote Control 尚未为此账户启用"410 "Remote Control isn't enabled for this account"

414</h3>411</h3>

415 412

416Claude Code 检查了您登录的账户的 Remote Control 可用性，检查结果为关闭。通常的原因是缓存的权利在计划更改后已过期。运行 `claude auth logout` 然后 `claude auth login` 以刷新它们，如果您使用的是旧版本，请更新 Claude Code。413Claude Code 检查了您登录的账户的 Remote Control 可用性，检查结果为关闭。通常原因是在计划更改后过期的缓存权利。运行 `claude auth logout` 然后 `claude auth login` 以刷新它们，如果您使用的是旧版本，请更新 Claude Code。

417 414

418运行 `claude doctor` 以查看哪个单独的资格检查失败。环境变量冲突、无法到达的检查和您的组织的 Remote Control 设置各自产生自己的消息，因此此错误意味着账户级别的检查本身。415运行 `claude doctor` 以查看哪个单独的资格检查失败。环境变量冲突、无法访问的检查和您的组织的 Remote Control 设置各自产生自己的消息，因此此错误意味着账户级别的检查本身。

419 416

420在 v2.1.239 之前，此消息读作"Remote Control is not yet enabled for your account"。在 v2.1.154 之前，禁用功能标志评估的变量（例如 `DISABLE_TELEMETRY` 或 `DO_NOT_TRACK`）也会产生此消息；下面的"Remote Control 需要功能标志评估"条目涵盖该配置。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 418

422<h3 id="couldn’t-verify-remote-control-eligibility">419<h3 id="couldn’t-verify-remote-control-eligibility">

423 "无法验证 Remote Control 资格"420 "Couldn't verify Remote Control eligibility"

424</h3>421</h3>

425 422

426Claude Code 无法到达功能标志服务以检查是否为您的账户启用了 Remote Control，通常是因为您离线或代理阻止了请求。一旦您有网络访问权限，请重试，或运行 `claude doctor` 以获取详细信息。相关消息"无法验证您的组织的 Remote Control 策略"具有相同的原因和相同的修复。这两条消息都在 v2.1.178 中添加。423Claude Code 无法访问功能标志服务以检查您的账户是否启用了 Remote Control，通常是因为您离线或代理阻止了请求。一旦您有网络访问权限，请重试，或运行 `claude doctor` 以获取详细信息。相关消息"Couldn't verify your organization's Remote Control policy"意味着 Claude Code 无法读取该策略，具有相同的修复。这两条消息都在 v2.1.178 中添加。

427 424

428<h3 id="remote-control-requires-feature-flag-evaluation">425<h3 id="remote-control-requires-feature-flag-evaluation">

429 "Remote Control 需要功能标志评估"426 "Remote Control requires feature-flag evaluation"

430</h3>427</h3>

431 428

432设置了以下变量之一：[`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"。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 430

434<h3 id="remote-control-is-only-available-when-using-claude-via-api-anthropic-com">431<h3 id="remote-control-is-only-available-when-using-claude-via-api-anthropic-com">

435 "Remote Control 仅在通过 api.anthropic.com 使用 Claude 时可用"432 "Remote Control is only available when using Claude via api.anthropic.com"

436</h3>433</h3>

437 434

438该会话不是直接与 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)。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)。

439 436

440该消息会命名将会话路由离开 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`。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`。

441 438

442<h3 id="remote-control-is-disabled-by-your-organization’s-policy">439<h3 id="remote-control-is-disabled-by-your-organization’s-policy">

443 "Remote Control 被您的组织的策略禁用"440 "Remote Control is disabled by your organization's policy"

444</h3>441</h3>

445 442

446策略阻止 Remote Control，或 Claude Code 无法在此机器上加载您的组织的策略，同时保持 Remote Control 关闭。按顺序检查这些原因：443策略阻止了 Remote Control，或者 Claude Code 无法在此机器上加载您的组织策略，同时保持 Remote Control 关闭。按顺序检查这些原因：

447 444

448* **错误提及 `disableRemoteControl`**：您的 IT 管理员已通过[托管设置](/docs/zh-CN/managed-settings)在此设备上禁用了 Remote Control，独立于组织范围的切换和您的登录方式。445* **错误提到 `disableRemoteControl`**：您的 IT 管理员已通过[托管设置](/docs/zh-CN/managed-settings)在此设备上禁用了 Remote Control，独立于组织范围的切换和您的登录方式。

449* **您的 claude.ai 计划是 Pro 或 Max**：Claude Code 仍然以来自较早登录的 Team 或 Enterprise 组织身份登录，因此它检查该组织的 Remote Control 策略。运行 `/status` 以查看您的登录使用的计划和组织。运行 `claude auth logout` 然后 `claude auth login` 以在您当前的计划下重新登录。446* **您的 claude.ai 计划是 Pro 或 Max**：Claude Code 仍然以来自较早登录的 Team 或 Enterprise 组织身份登录，因此它检查该组织的 Remote Control 策略。运行 `/status` 以查看您的登录使用的计划和组织。运行 `claude auth logout` 然后 `claude auth login` 以在您当前的计划下重新登录。

450* **组织策略未在此机器上加载**：运行 `claude doctor` 并阅读 `Organization policy` 行。如果该行显示策略未加载，这就是保持 Remote Control 关闭的原因。在 v2.1.261 之前，`claude doctor` 不打印此行。447* **组织策略未在此机器上加载**：运行 `claude doctor` 并读取 `Organization policy` 行。如果该行显示策略未加载，那就是保持 Remote Control 关闭的原因。在 v2.1.261 之前，`claude doctor` 不打印此行。

451* **消息未说联系您的组织管理员**：您的组织有与 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"。

452* **否则，所有者尚未为您的组织启用它**：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** 切换来启用它。此切换是服务器端组织设置。

453 450

454<h3 id="remote-credentials-fetch-failed">451<h3 id="remote-credentials-fetch-failed">

455 "Remote credentials fetch failed"452 "Remote credentials fetch failed"

463 460

464常见原因：461常见原因：

465 462

466* 未登录：运行 `claude` 并使用 `/login` 使用您的 claude.ai 账户进行身份验证。Remote Control 不支持 API 密钥身份验证。463* 未登录：运行 `claude` 并使用 `/login` 以您的 claude.ai 账户进行身份验证。Remote Control 不支持 API 密钥身份验证。

467* 网络或代理问题：防火墙或代理可能阻止出站 HTTPS 请求。Remote Control 需要访问端口 443 上的 Anthropic API。464* 网络或代理问题：防火墙或代理可能阻止了出站 HTTPS 请求。Remote Control 需要访问端口 443 上的 Anthropic API。

468* 会话创建失败：如果您还看到 `Session creation failed — see debug log`，失败发生在设置的早期。检查您的订阅是否处于活动状态。465* 会话创建失败：如果您还看到 `Session creation failed — see debug log`，失败发生在设置的早期。检查您的订阅是否有效。

469 466

470过期的登录令牌不会导致此错误。当 Anthropic API 拒绝保存的令牌时，例如因为另一个 Claude Code 进程已经刷新了它，Claude Code 会刷新令牌并自动重试。在 v2.1.224 之前，过期的令牌会导致 Remote Control 启动失败并显示此消息，因此设置为[自动连接](#enable-remote-control-for-all-sessions)的会话可能在启动时间歇性失败。467过期的登录令牌不会导致此错误。当 Anthropic API 拒绝保存的令牌时，例如因为另一个 Claude Code 进程已经刷新了它，Claude Code 会刷新令牌并自动重试。在 v2.1.224 之前，过期的令牌会导致 Remote Control 启动失败并显示此消息，因此设置为[自动连接](#enable-remote-control-for-all-sessions)的会话可能在启动时间歇性失败。

471 468

472<h3 id="couldn’t-reconnect-to-your-remote-control-session">469<h3 id="couldn’t-reconnect-to-your-remote-control-session">

473 "无法重新连接到您的 Remote Control 会话"470 "Couldn't reconnect to your Remote Control session"

474</h3>471</h3>

475 472

476当您使用 `claude --resume` 或 `claude --continue` 恢复对话时，Claude Code 会重新连接到该对话中记录的 Remote Control 会话。此消息意味着重新连接因可能是临时的原因（例如网络中断或服务器错误）而失败，因此 Claude Code 无法确认远程会话是否仍然存在。473当您使用 `claude --resume` 或 `claude --continue` 恢复对话时，Claude Code 会重新连接到该对话中记录的 Remote Control 会话。此消息意味着重新连接因可能是临时的原因（例如网络中断或服务器错误）而失败，因此 Claude Code 无法确认远程会话是否仍然存在。

477 474

478运行 `/remote-control` 以重试连接，或使用 `claude --remote-control` 启动新会话以创建新的 Remote Control 会话。您的本地会话继续运行而不使用 Remote Control。475运行 `/remote-control` 以重试连接，或使用 `claude --remote-control` 启动新会话以创建新的 Remote Control 会话。您的本地会话同时继续运行而不使用 Remote Control。

479 476

480<span id="resume-outcomes" />恢复时，您也可以获得以下结果之一而不是此消息：477<span id="resume-outcomes" />恢复时，您也可以获得以下结果之一而不是此消息：

481 478

482* **服务器报告记录的会话已消失，或重新连接记录命名不同的账户**：Claude Code 按照对话的重新连接记录所说的内容进行操作：479* **服务器报告记录的会话已消失，或重新连接记录命名不同的账户**：Claude Code 遵循对话的重新连接记录所说的内容：

483 * **记录命名您登录的账户**：Claude Code 使用自动生成的名称启动替换会话，并将对话的早期消息排除在外。例如，在您从 claude.ai 或 Claude 应用中删除会话后，您会看到这种情况。480 * **记录命名您登录的账户**：Claude Code 使用自动生成的名称启动替换会话，并将对话的早期消息排除在外。例如，在您从 claude.ai 或 Claude 应用中删除会话后，您会看到这种情况。

484 * **记录命名不同的账户**：Claude Code 启动新会话而不显示消息，无论记录的会话是否仍然存在，都不包括对话的早期消息。481 * **记录命名不同的账户**：Claude Code 启动新会话而不包含对话的早期消息，无论记录的会话是否仍然存在，都不显示消息。

485 * **记录未说明哪个账户拥有会话，或 Claude Code 无法读取您保存的登录**：Claude Code 显示 [`Previous session is unavailable — run /remote-control to start a new one`](#previous-session-is-unavailable) 而不是此消息，不启动任何内容，并从对话中删除记录。482 * **记录未说明哪个账户拥有会话，或 Claude Code 无法读取您保存的登录**：Claude Code 显示 [`Previous session is unavailable — run /remote-control to start a new one`](#previous-session-is-unavailable) 而不是此消息，不启动任何内容，并从对话中删除记录。

486* **您在恢复前关闭了 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 保留记录并重新连接。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 保留记录并重新连接。

487* **此机器上的另一个 Claude Code 仍然拥有会话**：您会看到以 `Remote Control not started here` 开头的通知，Claude Code [在恢复的会话中保持 Remote Control 关闭](#resume-sessions-after-stopping-the-server)。在那里运行 `/remote-control` 以移动它。484* **此机器上的另一个 Claude Code 仍然拥有该会话**：您会看到一条以 `Remote Control not started here` 开头的通知，Claude Code [在恢复的会话中保持 Remote Control 关闭](#resume-sessions-after-stopping-the-server)。在那里运行 `/remote-control` 以移动它。

488 485

489<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 在任何重新连接失败后创建新会话。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 在任何重新连接失败后创建新会话。

490 487

491<h3 id="previous-session-is-unavailable">488<h3 id="previous-session-is-unavailable">

492 "Previous session is unavailable — run /remote-control to start a new one"489 "Previous session is unavailable — run /remote-control to start a new one"

493</h3>490</h3>

494 491

495Claude Code 无法恢复之前的 Remote Control 会话，而是停止而不是自动启动新会话。在您使用 `claude --resume` 或 `claude --continue` 恢复对话后，或在 Claude Code [在断开连接后自动重新连接](/docs/zh-CN/errors#remote-control-couldnt-refresh-your-login)后，您可能会看到此消息。492Claude Code 无法恢复之前的 Remote Control 会话，而是停止而不是自动启动新会话。在使用 `claude --resume` 或 `claude --continue` 恢复对话后，或在 Claude Code [在断开连接后自动重新连接](/docs/zh-CN/errors#remote-control-couldnt-refresh-your-login)后，您可能会看到此消息。

496 493

497运行 `/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 会将对话的早期消息排除在新会话之外。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 会将对话的早期消息排除在新会话之外。

498 495

499在恢复时，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)中。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)中。

500 497

501<h3 id="remote-control-got-an-unexpected-server-response">498<h3 id="remote-control-got-an-unexpected-server-response">

502 "Remote Control got an unexpected server response"499 "Remote Control got an unexpected server response"

503</h3>500</h3>

504 501

505Remote Control 服务器接受了请求，但以此版本的 Claude Code 无法读取的形式回复，同时创建远程会话或获取其凭证。在同一版本上重试会以相同的方式失败。运行 `claude update`，然后运行 `/remote-control` 以重新连接。此消息在 v2.1.225 中添加。502Remote Control 服务器接受了请求但以此版本的 Claude Code 无法读取的形式回复，同时创建远程会话或获取其凭证。在同一版本上重试会以相同方式失败。运行 `claude update`，然后运行 `/remote-control` 以重新连接。此消息在 v2.1.225 中添加。

506 503

507<h3 id="your-organization-requires-trusted-devices-for-remote-control-but-this-device-is-not-enrolled">504<h3 id="your-organization-requires-trusted-devices-for-remote-control-but-this-device-is-not-enrolled">

508 "您的组织需要受信任的设备用于 Remote Control，但此设备未注册"505 "Your organization requires Trusted Devices for Remote Control, but this device is not enrolled"

509</h3>506</h3>

510 507

511您的组织已[启用受信任的设备](#trusted-devices)，此机器尚未注册。在 Claude Code 中运行 `/login`。注册作为登录的一部分进行，没有单独的注册命令。508您的组织已启用[Trusted Devices](#trusted-devices)，此机器尚未注册。在 Claude Code 中运行 `/login`。注册作为登录的一部分进行，没有单独的注册命令。

512 509

513<h3 id="session-expired-for-trusted-device-check">510<h3 id="session-expired-for-trusted-device-check">

514 "session expired for trusted-device check"511 "session expired for trusted-device check"

515</h3>512</h3>

516 513

517您的登录已超过 18 小时。在 Claude Code 中运行 `/login`，或在 claude.ai 或移动应用提示您时使用 Face ID、Touch ID、Windows Hello 或通行密钥确认。请参阅[受信任的设备](#trusted-devices)。514您的登录已超过 18 小时。在 Claude Code 中运行 `/login`，或当 claude.ai 或移动应用提示您时，使用 Face ID、Touch ID、Windows Hello 或通行密钥进行确认。请参阅 [Trusted Devices](#trusted-devices)。

518 515

519<h2 id="choose-the-right-approach">516<h2 id="choose-the-right-approach">

520 选择正确的方法517 选择正确的方法

536</h2>533</h2>

537 534

538* [网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)：在云中运行会话而不是在您的机器上，通过[云环境](/docs/zh-CN/cloud-environments)配置535* [网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)：在云中运行会话而不是在您的机器上，通过[云环境](/docs/zh-CN/cloud-environments)配置

539* [跨会话消息传递](/docs/zh-CN/cross-session-messaging)：让 Claude 在其他机器上或在[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web) 上向您的会话发送消息536* [跨会话消息传递](/docs/zh-CN/cross-session-messaging)：让 Claude 在其他机器上或在[云会话](/docs/zh-CN/claude-code-on-the-web)上向您的会话发送消息

540* [Channels](/docs/zh-CN/channels)：将 Telegram、Discord 或 iMessage 转发到会话中，以便 Claude 在您离开时对消息做出反应537* [Channels](/docs/zh-CN/channels)：将 Telegram、Discord 或 iMessage 转发到会话中，以便 Claude 在您离开时对消息做出反应

541* [Dispatch](/docs/zh-CN/desktop#sessions-from-dispatch)：从您的手机发送任务消息，它可以生成 Desktop 会话来处理它538* [Dispatch](/docs/zh-CN/desktop#sessions-from-dispatch)：从您的手机发送任务消息，它可以生成 Desktop 会话来处理它

542* [身份验证](/docs/zh-CN/authentication)：设置 `/login` 并管理 claude.ai 的凭证539* [身份验证](/docs/zh-CN/authentication)：设置 `/login` 并管理 claude.ai 的凭证

543* [CLI 参考](/docs/zh-CN/cli-reference)：包括 `claude remote-control` 的标志和命令的完整列表540* [CLI 参考](/docs/zh-CN/cli-reference)：包括 `claude remote-control` 的标志和命令的完整列表

544* [安全](/docs/zh-CN/security)：Remote Control 会话如何适应 Claude Code 安全模型541* [安全](/docs/zh-CN/security)：Remote Control 会话如何适应 Claude Code 安全模型

545* [数据使用](/docs/zh-CN/data-usage)：在本地和远程会话期间通过 Anthropic API 流动的数据542* [数据使用](/docs/zh-CN/data-usage)：在本地、Remote Control 和云会话期间通过 Anthropic API 流动的数据

routines.md +15 −17

Details

174 174

175<Steps>175<Steps>

176 <Step title="打开例程进行编辑">176 <Step title="打开例程进行编辑">

177 转到 [claude.ai/code/routines](https://claude.ai/code/routines)，单击您想通过 API 触发的例程，然后单击铅笔图标打开 **Edit routine**。177 转到 [claude.ai/code/routines](https://claude.ai/code/routines)，单击您想通过 API 触发的例程，然后打开例程名称旁边的菜单并选择 **Edit**。

178 </Step>178 </Step>

179 179

180 <Step title="添加 API 触发器">180 <Step title="添加 API 触发器">

254 254

255<Steps>255<Steps>

256 <Step title="打开例程进行编辑">256 <Step title="打开例程进行编辑">

257 转到 [claude.ai/code/routines](https://claude.ai/code/routines)，单击例程，然后单击铅笔图标打开 **Edit routine**。257 转到 [claude.ai/code/routines](https://claude.ai/code/routines)，单击例程，然后打开例程名称旁边的菜单并选择 **Edit**。

258 </Step>258 </Step>

259 259

260 <Step title="添加 GitHub 事件触发器">260 <Step title="添加 GitHub 事件触发器">

331从例程详细信息页面，您可以：331从例程详细信息页面，您可以：

332 332

333* 单击 **Run now** 立即启动运行，而无需等待下一个计划时间。您可以选择提供特定于运行的文本，该文本以与 API 触发器的 `text` 字段相同的方式到达例程。333* 单击 **Run now** 立即启动运行，而无需等待下一个计划时间。您可以选择提供特定于运行的文本，该文本以与 API 触发器的 `text` 字段相同的方式到达例程。

334* 使用 **Repeats** 部分中的切换来暂停或恢复计划。暂停的例程保持其配置但不运行，直到您重新启用它们。334* 使用页面顶部的开/关开关来暂停或恢复计划。暂停的例程保持其配置但不运行，直到您重新启用它们。

335* 单击铅笔图标打开 **Edit routine** 并更改名称、提示、存储库、环境、connectors 或例程的任何触发器。**Select a trigger** 部分是您添加或删除计划、API 令牌和 GitHub 事件触发器的地方。335* 打开例程名称旁边的菜单并选择 **Edit** 以更改名称、提示、存储库、环境、connectors 或例程的任何触发器。**Select a trigger** 部分是您添加或删除计划、API 令牌和 GitHub 事件触发器的地方。

336* 单击删除图标以删除例程。例程创建的过去会话保留在您的会话列表中。336* 打开同一菜单并选择 **Delete** 以删除例程。

337 337

338<h3 id="manage-routines-from-the-cli">338<h3 id="manage-routines-from-the-cli">

339 从 CLI 管理例程339 从 CLI 管理例程

381 381

382<Steps>382<Steps>

383 <Step title="打开例程进行编辑">383 <Step title="打开例程进行编辑">

384 在例程的详细信息页面上，单击铅笔图标以打开 **Edit routine**。384 在例程的详细信息页面上，打开例程名称旁边的菜单并选择 **Edit**。

385 </Step>385 </Step>

386 386

387 <Step title="打开环境选择器">387 <Step title="打开环境选择器">

421 `/schedule` 返回"Unknown command"421 `/schedule` 返回"Unknown command"

422</h3>422</h3>

423 423

424当不满足其中一个要求时，CLI 会隐藏 `/schedule`：命令菜单在您输入时显示 `No commands match "/schedule"`，提交它会返回 `Unknown command: /schedule`。除了拥有 Console API 密钥或启用了功能标志获取的 Anthropic 配置文件外，在以下所有情况下都会返回 `Unknown command: /schedule`。原因通常是以下之一：424当不满足其中一个要求时，CLI 会隐藏 `/schedule`：命令菜单在您输入时显示 `No commands match "/schedule"`，提交它会返回 `Unknown command: /schedule`，除了下面注明不同答案的情况外。

425 425

426* 您使用 Console API 密钥、[Anthropic 配置文件或联合凭证](/docs/zh-CN/authentication#anthropic-profiles-and-federation-credentials)或云提供商（如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry）进行身份验证。`/schedule` 需要 claude.ai 订阅登录。使用 Console API 密钥或配置文件时，提交 `/schedule` 会显示 `/schedule is available with Claude for Enterprise — ask your admin about migrating from API-key access`。使用云提供商登录时，您仍然会看到 `Unknown command: /schedule`。如果在您的 shell 中设置了 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，或在 `settings.json` 中设置了 `apiKeyHelper`，请先删除它，因为这些会优先于 claude.ai 登录。配置文件或联合凭证也会优先，所以也要关闭它426原因通常是以下之一：

427* 您在 Claude Code 网页会话中。改为从 [web UI](https://claude.ai/code/routines) 管理例程

428* 您的组织的策略禁用了 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web)，例程在其上运行

429* Owner 为您的 Team 或 Enterprise 组织[关闭了例程](#routines-are-disabled-by-your-organizations-policy)。在 v2.1.227 之前，命令在这种情况下仍然出现，当 Claude 尝试创建或运行例程时，claude.ai 会拒绝该例程

~~430~~

431除非您的组织的策略禁用了例程或 Claude Code on the web，否则无论 CLI 如何配置，您都可以在 [claude.ai/code/routines](https://claude.ai/code/routines) 处创建和管理例程。

432 427

433<h3 id="/schedule-asks-you-to-authenticate">428* 您使用 Console API 密钥、[Anthropic 配置文件或联合凭证](/docs/zh-CN/authentication#anthropic-profiles-and-federation-credentials)或云提供商（如 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry）进行身份验证。`/schedule` 需要 claude.ai 订阅登录。使用 Console API 密钥或配置文件时，如果启用了功能标志获取，提交 `/schedule` 会显示 `/schedule is available with Claude for Enterprise — ask your admin about migrating from API-key access`。使用云提供商登录时，您仍然会看到 `Unknown command: /schedule`。如果在您的 shell 中设置了 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`，或在 `settings.json` 中设置了 `apiKeyHelper`，请先删除它，因为这些会优先于 claude.ai 登录。配置文件或联合凭证也会优先，所以也要关闭它

434 `/schedule` 要求您进行身份验证429* 您完全登出，没有 API 密钥或其他凭证。如果启用了功能标志获取，提交 `/schedule` 会显示 `/schedule requires a claude.ai subscription. Run /login to sign in with your claude.ai account.` 在 v2.1.268 之前，登出的会话显示与 Console API 密钥相同的 Claude for Enterprise 消息

435</h3>430* 您在云会话中。改为从 [web UI](https://claude.ai/code/routines) 管理例程

431* 您的组织的策略禁用了 [cloud sessions](/docs/zh-CN/claude-code-on-the-web)，例程需要这些。在这种情况下，提交 `/schedule` 会回答 [`Cloud sessions are disabled by your organization's policy`](/docs/zh-CN/errors#cloud-sessions-are-disabled-by-your-organizations-policy)。在 v2.1.268 之前，它返回 `Unknown command: /schedule`

432* Owner 为您的 Team 或 Enterprise 组织[关闭了例程](#routines-are-disabled-by-your-organizations-policy)。在 v2.1.227 之前，命令在这种情况下仍然出现，当 Claude 尝试创建或运行例程时，claude.ai 会拒绝该例程

436 433

437如果 `/schedule` 运行但 Claude 响应您需要先使用 claude.ai 账户进行身份验证，则 CLI 没有存储的 claude.ai 登录。API 账户不支持例程。运行 `/login`，使用您的 claude.ai 账户登录，然后再次运行 `/schedule`。434除非您的组织的策略禁用了例程或 cloud sessions，否则无论 CLI 如何配置，您都可以在 [claude.ai/code/routines](https://claude.ai/code/routines) 处创建和管理例程。

438 435

439<h3 id="routines-are-disabled-by-your-organizations-policy">436<h3 id="routines-are-disabled-by-your-organizations-policy">

440 "Routines 被您的组织的策略禁用"437 "Routines 被您的组织的策略禁用"

449* [`/loop` and in-session scheduling](/docs/zh-CN/scheduled-tasks)：在打开的 CLI 会话中计划本地任务446* [`/loop` and in-session scheduling](/docs/zh-CN/scheduled-tasks)：在打开的 CLI 会话中计划本地任务

450* [Desktop scheduled tasks](/docs/zh-CN/desktop-scheduled-tasks)：在您的机器上运行的本地计划任务，可以访问本地文件447* [Desktop scheduled tasks](/docs/zh-CN/desktop-scheduled-tasks)：在您的机器上运行的本地计划任务，可以访问本地文件

451* [Cloud environments](/docs/zh-CN/cloud-environments)：为云会话配置网络访问、环境变量和设置脚本448* [Cloud environments](/docs/zh-CN/cloud-environments)：为云会话配置网络访问、环境变量和设置脚本

449* [Projects](/docs/zh-CN/claude-projects)：Claude 在并行云会话中协调的持续工作；从项目创建的例程会显示在其**例程**选项卡上

452* [MCP connectors](/docs/zh-CN/mcp)：连接外部服务，如 Slack、Linear 和 Google Drive450* [MCP connectors](/docs/zh-CN/mcp)：连接外部服务，如 Slack、Linear 和 Google Drive

453* [GitHub Actions](/docs/zh-CN/github-actions)：在存储库事件的 CI 管道中运行 Claude451* [GitHub Actions](/docs/zh-CN/github-actions)：在存储库事件的 CI 管道中运行 Claude

sandbox-environments.md +13 −13

Details

21下表中的前两种方法在主机操作系统上运行，不使用容器。其余方法将 Claude Code 放在容器或虚拟机内。21下表中的前两种方法在主机操作系统上运行，不使用容器。其余方法将 Claude Code 放在容器或虚拟机内。

22 22

23| 方法 | 隔离的内容 | 需要 Docker | 设置工作量 |23| 方法 | 隔离的内容 | 需要 Docker | 设置工作量 |

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

~~25| [Sandboxed Bash tool](#sandboxed-bash-tool) | Bash 命令及其子进程 | 否 | macOS 上最少；Linux 和 WSL2 上较少 |~~25| [Sandboxed Bash tool](#sandboxed-bash-tool) | Bash、PowerShell 和 Monitor 命令及其子进程 | 否 | macOS 上最少；Linux 和 WSL2 上较少 |

26| [Sandbox runtime](#sandbox-runtime) | 整个 Claude Code 进程，包括文件工具、MCP 服务器和 hooks | 否 | 较少 |26| [Sandbox runtime](#sandbox-runtime) | 整个 Claude Code 进程，包括文件工具、MCP 服务器和 hooks | 否 | 较少 |

27| [Dev container](#dev-containers) | 完整开发环境 | 是 | 中等 |27| [Dev container](#dev-containers) | 完整开发环境 | 是 | 中等 |

28| [Custom container](#custom-container) | 完整开发环境 | 是 | 中等到高 |28| [Custom container](#custom-container) | 完整开发环境 | 是 | 中等到高 |

29| [Virtual machine](#virtual-machine) | 完整操作系统 | 否 | 高 |29| [Virtual machine](#virtual-machine) | 完整操作系统 | 否 | 高 |

31 31

32[Sandboxed Bash tool](/docs/zh-CN/sandboxing) 内置于 Claude Code 中，仅限制 Bash 命令。内置文件工具、MCP 服务器和 hooks 仍直接在您的主机上运行。表中的所有其他方法都将整个 Claude Code 进程放在隔离边界内，因此文件工具、MCP 服务器和 hooks 也受到限制。32[Sandboxed Bash tool](/docs/zh-CN/sandboxing) 内置于 Claude Code 中，仅限制 Bash 命令。内置文件工具、MCP 服务器和 hooks 仍直接在您的主机上运行。表中的所有其他方法都将整个 Claude Code 进程放在隔离边界内，因此文件工具、MCP 服务器和 hooks 也受到限制。

33 33

44将您的目标与下面的一行匹配，然后阅读随后的详细部分。44将您的目标与下面的一行匹配，然后阅读随后的详细部分。

45 45

46| 您想要 | 开始使用 |46| 您想要 | 开始使用 |

~~47| :------------------------------------------------------- | :---------------------------------------------------------------------------------------------------- |~~47| :------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- |

49| 让 Claude 使用 `--dangerously-skip-permissions` 或自动模式无人值守工作 | 预配置的 [dev container](/docs/zh-CN/devcontainer)、任何容器或虚拟机，或 [sandbox runtime](#sandbox-runtime) |49| 让 Claude 使用 `--dangerously-skip-permissions` 或自动模式无人值守工作 | 预配置的 [dev container](/docs/zh-CN/devcontainer)、任何容器或虚拟机，或 [sandbox runtime](#sandbox-runtime) |

50| 隔离 MCP 服务器和 hooks 以及 Bash，不使用 Docker | sandbox runtime |50| 隔离 MCP 服务器和 hooks 以及 Bash，不使用 Docker | sandbox runtime |

52| 在团队中标准化沙箱环境 | 预配置的 [dev container](/docs/zh-CN/devcontainer)，复制到您的存储库中 |52| 在团队中标准化沙箱环境 | 预配置的 [dev container](/docs/zh-CN/devcontainer)，复制到您的存储库中 |

53| 从没有本地设置的设备使用 Claude Code | [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web)，需要 Claude 订阅和连接的 GitHub 账户 |53| 从没有本地设置的设备使用 Claude Code | [cloud session](/docs/zh-CN/claude-code-on-the-web)，需要 Claude 订阅和连接的 GitHub 账户 |

54| 为组织中的每个开发人员要求隔离 | [在整个组织中强制实施隔离](#enforce-isolation-across-an-organization) |54| 为组织中的每个开发人员要求隔离 | [在整个组织中强制实施隔离](#enforce-isolation-across-an-organization) |

55| 在本机 Windows 主机上工作 | 容器或虚拟机，或在 WSL2 内运行 Bash 沙箱 |55| 在本机 Windows 主机上工作 | 容器或虚拟机，或在 WSL2 内运行 Bash 沙箱 |

56 56

66 66

67[Auto mode](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 用审查操作的分类器替换提示。分类器是按操作控制，而不是隔离边界，因此隔离边界仍然为无人值守运行添加纵深防御，并且不像 `--dangerously-skip-permissions` 那样是必需的。67[Auto mode](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 用审查操作的分类器替换提示。分类器是按操作控制，而不是隔离边界，因此隔离边界仍然为无人值守运行添加纵深防御，并且不像 `--dangerously-skip-permissions` 那样是必需的。

68 68

69[sandboxed Bash tool](#sandboxed-bash-tool) 本身仅限制 Bash，因此对于任一模式的完全无人值守运行都不足够。您可以分层方法：在容器或虚拟机内运行沙箱化 Bash 工具可在外部环境边界之上为您提供操作系统级命令限制。有关 Bash 沙箱本身如何与权限规则和模式交互的信息，请参阅 [How sandboxing relates to permissions and permission modes](/docs/zh-CN/sandboxing#how-sandboxing-relates-to-permissions-and-permission-modes)。69[sandboxed Bash tool](#sandboxed-bash-tool) 本身仅限制 shell 命令，因此对于任一模式的完全无人值守运行都不足够。您可以分层方法：在容器或虚拟机内运行沙箱化 Bash 工具可在外部环境边界之上为您提供操作系统级命令限制。有关 Bash 沙箱本身如何与权限规则和权限模式交互的信息，请参阅 [How sandboxing relates to permissions and permission modes](/docs/zh-CN/sandboxing#how-sandboxing-relates-to-permissions-and-permission-modes)。

70 70

71<h2 id="sandboxed-bash-tool">71<h2 id="sandboxed-bash-tool">

72 Sandboxed Bash tool72 Sandboxed Bash tool

76 此选项不支持本机 Windows。在 Windows 主机上，使用 WSL2 或下面的容器或虚拟机方法之一。76 此选项不支持本机 Windows。在 Windows 主机上，使用 WSL2 或下面的容器或虚拟机方法之一。

77</Note>77</Note>

78 78

~~79Sandboxed Bash tool 内置于 Claude Code 中。它使用操作系统原语来限制 Claude 运行的每个 Bash 命令的文件系统和网络访问。~~79Sandboxed Bash tool 内置于 Claude Code 中。它使用操作系统原语来限制 Claude 运行的每个 Bash、PowerShell 或 Monitor 命令的文件系统和网络访问。

80 80

81运行 `/sandbox` 命令打开沙箱面板并选择一个模式。[Sandboxing](/docs/zh-CN/sandboxing) 指南涵盖批准模式、默认边界以及如何扩大或缩小它。81运行 `/sandbox` 命令打开沙箱面板并选择一个模式。[Sandboxing](/docs/zh-CN/sandboxing) 指南涵盖批准模式、默认边界以及如何扩大或缩小它。

82 82

91 Sandbox runtime91 Sandbox runtime

92</h2>92</h2>

93 93

94[`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime) 包将整个进程包装在内置 Bash 沙箱使用的相同 Seatbelt 或 bubblewrap 隔离中。通过它运行 Claude Code 会限制会话中的每个工具、hook 和 MCP 服务器，而不仅仅是 Bash。运行时是测试版研究预览，其配置格式可能会随着包的发展而改变。94[`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime) 包将整个进程包装在内置 Bash 沙箱使用的相同 Seatbelt 或 bubblewrap 隔离中。通过它运行 Claude Code 会限制会话中的每个工具、hook 和 MCP 服务器，而不仅仅是 Bash 命令。运行时是测试版研究预览，其配置格式可能会随着包的发展而改变。

95 95

96本部分涵盖您配置的内容以及运行时自身强制执行的内容。有关在 Agent SDK 应用程序中部署运行时，请参阅[安全部署指南](/docs/zh-CN/agent-sdk/secure-deployment#sandbox-runtime)。96本部分涵盖您配置的内容以及运行时自身强制执行的内容。有关在 Agent SDK 应用程序中部署运行时，请参阅[安全部署指南](/docs/zh-CN/agent-sdk/secure-deployment#sandbox-runtime)。

97 97

175 175

176[Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) 提供了一个具有自己的 Docker 守护程序和工作区同步的 microVM，可以在任何安装了 Docker Sandboxes 的主机上运行 Claude Code。它是来自 Docker 的免费独立产品，不需要 Docker Desktop。176[Docker Sandboxes](https://docs.docker.com/ai/sandboxes/) 提供了一个具有自己的 Docker 守护程序和工作区同步的 microVM，可以在任何安装了 Docker Sandboxes 的主机上运行 Claude Code。它是来自 Docker 的免费独立产品，不需要 Docker Desktop。

177 177

178<h2 id="claude-code-on-the-web">178<h2 id="cloud-sessions">

179 Claude Code on the web179 云会话

180</h2>180</h2>

181 181

182[Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 在隔离的、由 Anthropic 管理的虚拟机中运行每个会话。网络代理强制执行默认允许列表，单独的代理在沙箱外保存您的 GitHub 令牌，同时在其内部为存储库访问发出作用域凭据。您的组织路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话在您配置的基础设施上运行，其中隔离、出站控制和 git 凭据是您部署的责任。182[云会话](/docs/zh-CN/claude-code-on-the-web)在隔离的、由 Anthropic 管理的虚拟机中运行。网络代理强制执行默认允许列表，单独的代理在沙箱外保存您的 GitHub 令牌，同时在其内部为存储库访问发出作用域凭据。您的组织路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话在您配置的基础设施上运行，其中隔离、出站控制和 git 凭据是您部署的责任。

183 183

184当您想要完整的虚拟机隔离而无需自己配置基础设施，或当您从没有本地开发环境的设备委派任务时，使用此方法。它需要 Claude 订阅。当您从 Web 界面启动会话时，您还需要一个连接的 GitHub 账户，以便沙箱可以克隆您的存储库。当您使用 `--cloud` 从 CLI 启动时，Claude Code 可以[捆绑并上传您的本地存储库](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github)。有关计划可用性和 GitHub 身份验证选项，请参阅 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web)。184当您想要完整的虚拟机隔离而无需自己配置基础设施，或当您从没有本地开发环境的设备委派任务时，使用此方法。它需要 Claude 订阅。除非您从 CLI 启动，否则您还需要一个连接的 GitHub 账户，以便沙箱可以克隆您的存储库。当您使用 `--cloud` 从 CLI 启动时，Claude Code 可以[捆绑并上传您的本地存储库](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github)。有关计划可用性和 GitHub 身份验证选项，请参阅[在云中使用 Claude Code](/docs/zh-CN/claude-code-on-the-web)。

185 185

186<h2 id="enforce-isolation-across-an-organization">186<h2 id="enforce-isolation-across-an-organization">

187 在整个组织中强制实施隔离187 在整个组织中强制实施隔离

sandboxing.md +44 −28

Details

6 6

7> 了解 Claude Code 的沙箱化 Bash 工具如何提供文件系统和网络隔离，以实现更安全、更自主的代理执行。7> 了解 Claude Code 的沙箱化 Bash 工具如何提供文件系统和网络隔离，以实现更安全、更自主的代理执行。

8 8

9Bash 沙箱让 Claude 可以运行大多数 shell 命令，而无需停下来请求权限。与其批准每个命令不同，你定义命令可以接触哪些文件和网络域，操作系统为每个 Bash 命令及其子进程强制执行该边界。9Bash 沙箱让 Claude 可以运行大多数 shell 命令，而无需停下来请求权限。与其批准每个命令不同，你定义命令可以接触哪些文件和网络域，操作系统为每个 Bash、PowerShell 或 Monitor 命令及其子进程强制执行该边界。

10 10

11<Note>11<Note>

12 要比较其他隔离方法，如开发容器、自定义容器和虚拟机，请参阅 [Sandbox environments](/docs/zh-CN/sandbox-environments)。要减少 Bash 以外工具的权限提示，请参阅 [permission modes](/docs/zh-CN/permission-modes)。12 要比较其他隔离方法，如开发容器、自定义容器和虚拟机，请参阅 [Sandbox environments](/docs/zh-CN/sandbox-environments)。要减少 Bash 以外工具的权限提示，请参阅 [permission modes](/docs/zh-CN/permission-modes)。

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)。命令第一次需要新的网络域时，Claude Code 会提示批准，或在 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 中将请求发送给分类器。45 要求 Claude 运行一个命令，例如构建或测试套件。默认情况下，沙箱内的命令可以写入工作目录、会话临时目录以及任何你用 `--add-dir`、`/add-dir` 或 `permissions.additionalDirectories` [添加的目录](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)。命令第一次需要新的网络域时，Claude Code 会提示批准；在 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 中，Claude 改为在 [命令本身上命名](#per-command-allowed-domains-in-auto-mode) 命令需要的主机供分类器与其一起审查。

46 46

47 无法沙箱化运行的命令会回退到常规权限流程。Claude Code 将其权限提示标题为"Bash 命令（非沙箱化）"而不是"Bash 命令"，这样你可以看出哪些命令在沙箱外运行。要扩大或缩小沙箱允许的范围，请参阅 [配置沙箱](#configure-sandboxing)。47 无法沙箱化运行的命令会回退到常规权限流程。Claude Code 将其权限提示标题为"Bash 命令（非沙箱化）"而不是"Bash 命令"，这样你可以看出哪些命令在沙箱外运行。要扩大或缩小沙箱允许的范围，请参阅 [配置沙箱](#configure-sandboxing)。

48 48

145* 裸 `Bash` 询问规则，或等效的 `Bash(*)` 形式，对于运行沙箱化的命令会被跳过；它仍然适用于回退到常规权限流程的命令。在 [plan mode](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode) 中，该规则不会被跳过：它也会对沙箱化命令提示，包括只读命令。在 v2.1.212 之前，跳过也适用于 plan mode145* 裸 `Bash` 询问规则，或等效的 `Bash(*)` 形式，对于运行沙箱化的命令会被跳过；它仍然适用于回退到常规权限流程的命令。在 [plan mode](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode) 中，该规则不会被跳过：它也会对沙箱化命令提示，包括只读命令。在 v2.1.212 之前，跳过也适用于 plan mode

146 146

147<Info>147<Info>

148 自动允许模式独立于你的权限模式设置工作，有一个例外：[plan mode](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)。即使你不在"接受编辑"模式中，启用自动允许时沙箱化的 Bash 命令也会自动运行。这意味着在沙箱边界内修改文件的 Bash 命令将执行而不提示，即使在 Manual 模式下，文件编辑工具会提示。148 自动允许模式独立于你的权限模式设置工作，除了在 [plan mode](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode) 中，以及在自动模式中，对于携带 [per-command allowed domains](#per-command-allowed-domains-in-auto-mode) 的命令。即使你不在"接受编辑"模式中，启用自动允许时沙箱化的 Bash 命令也会自动运行。这意味着在沙箱边界内修改文件的 Bash 命令将执行而不提示，即使在 Manual 模式下，文件编辑工具会提示。

149 149

150 在 plan mode 中，自动允许不会扩大批准；请参阅 [plan mode](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode) 了解 Claude Code 如何在你计划时限制命令。在 v2.1.212 之前，自动允许在 plan mode 中也无需提示地运行沙箱化命令。150 在 plan mode 中，自动允许不会扩大批准；请参阅 [plan mode](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode) 了解 Claude Code 如何在你计划时限制命令。在 v2.1.212 之前，自动允许在 plan mode 中也无需提示地运行沙箱化命令。

151</Info>151</Info>

540 540

541* **在你的工作目录及其上方的目录中**：`.claude` 设置文件、`.claude/skills`、`.claude/agents`、`.claude/commands` 和 `.claude/hooks` 目录、`.mcp.json`，以及 Claude Code 自己运行的文件，例如 `.claude/workflows` 和 `.claude/scheduled_tasks.json`541* **在你的工作目录及其上方的目录中**：`.claude` 设置文件、`.claude/skills`、`.claude/agents`、`.claude/commands` 和 `.claude/hooks` 目录、`.mcp.json`，以及 Claude Code 自己运行的文件，例如 `.claude/workflows` 和 `.claude/scheduled_tasks.json`

542* **仅在你的工作目录中**：shell 启动文件，例如 `.bashrc` 和 `.zshrc`、`.gitconfig`、`.vscode` 和 `.idea` 目录，以及 `.git` 内的 `hooks` 和 `config`542* **仅在你的工作目录中**：shell 启动文件，例如 `.bashrc` 和 `.zshrc`、`.gitconfig`、`.vscode` 和 `.idea` 目录，以及 `.git` 内的 `hooks` 和 `config`

543* **会将你的工作目录变成裸 git 存储库的文件**：顶级的 `HEAD`、`objects` 和 `refs`，加上 `config` 和 `hooks`（当它们已经存在时），即使 `config` 目录属于你的项目而不是 git。在 Linux 和 WSL2 上，沙箱删除在沙箱化命令运行时出现的顶级 `HEAD` 文件或 `objects` 或 `refs` 目录543* **会将你的工作目录变成裸 git 存储库的文件**：顶级的 `HEAD`、`objects` 和 `refs`，加上 `config` 和 `hooks`（当它们已经存在时）。即使 `config` 文件没有 `HEAD` 也会被拒绝。在 Linux 和 WSL2 上，沙箱删除在沙箱化命令运行时出现的顶级 `HEAD` 文件或 `objects` 或 `refs` 目录

544* **在 `~/.claude` 中，或 `CLAUDE_CONFIG_DIR` 指向的目录中**：其大部分内容，加上 `~/.claude.json` 和 `.credentials.json` 凭证存储544* **在 `~/.claude` 中，或 `CLAUDE_CONFIG_DIR` 指向的目录中**：其大部分内容，加上 `~/.claude.json` 和 `.credentials.json` 凭证存储

545 545

546如果在会话期间受保护设置文件的路径处出现符号链接，沙箱也会拒绝对其指向的文件进行写入，从下一个命令开始。546如果在会话期间受保护设置文件的路径处出现符号链接，沙箱也会拒绝对其指向的文件进行写入，从下一个命令开始。

555 555

556网络访问通过在沙箱外运行的代理服务器进行控制：556网络访问通过在沙箱外运行的代理服务器进行控制：

557 557

558* **域名限制**：Claude Code 默认不预先允许任何域名。命令第一次需要新的域名时，Claude Code 会提示批准，或在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中将请求发送给分类器。如果在提示时选择"是"，Claude Code 会在当前会话的其余时间内允许该主机，之后连接到同一主机时不会再次提示。如果选择"是，以后不再询问"，Claude Code 会将 `WebFetch(domain:...)` 允许规则保存到你的[本地设置](/docs/zh-CN/permissions#permission-system)，因此该主机在未来会话中保持允许。使用 [`allowedDomains`](/docs/zh-CN/settings-reference#sandbox-network-alloweddomains) 预先允许域名以完全避免提示。Claude Code 也预先允许来自 `WebFetch(domain:...)` 允许规则的域名，如[权限规则](#permission-rules)中所述。558* **域名限制**：Claude Code 默认不预先允许任何域名。命令第一次需要新的域名时，Claude Code 会提示批准；在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中，Claude 会根据[按命令允许的域名](#per-command-allowed-domains-in-auto-mode)在命令本身上命名命令需要的主机。

559* **批准选择**：如果在提示时选择"是"，Claude Code 会在当前会话的其余时间内允许该主机，之后连接到同一主机时不会再次提示。如果选择"是，以后不再询问"，Claude Code 会将 `WebFetch(domain:...)` 允许规则保存到你的[本地设置](/docs/zh-CN/permissions#permission-system)，因此该主机在未来会话中保持允许。

560* **预先允许的域名**：使用 [`allowedDomains`](/docs/zh-CN/settings-reference#sandbox-network-alloweddomains) 预先允许域名以完全避免提示。Claude Code 也预先允许来自 `WebFetch(domain:...)` 允许规则的域名，如[权限规则](#permission-rules)中所述。

559* **严格允许列表**：如果在用户、托管或 CLI `--settings` 设置中将 [`strictAllowlist`](/docs/zh-CN/settings-reference#sandbox-network-strictallowlist) 设置为 `true`，Claude Code 会拒绝沙箱化命令访问允许列表外的任何主机，而不是提示。允许列表与沙箱否则会提示的相同：`allowedDomains` 加上来自 `WebFetch(domain:...)` 允许规则的域名，或当设置了 `allowManagedDomainsOnly` 时仅限托管设置条目。Claude Code 仅对沙箱化命令强制执行此；进程内工具（例如 `WebFetch`）仍然遵循其[权限规则](#permission-rules)。在存储库的 `.claude/settings.json` 或 `.claude/settings.local.json` 中设置它没有效果。需要 Claude Code v2.1.219 或更高版本。561* **严格允许列表**：如果在用户、托管或 CLI `--settings` 设置中将 [`strictAllowlist`](/docs/zh-CN/settings-reference#sandbox-network-strictallowlist) 设置为 `true`，Claude Code 会拒绝沙箱化命令访问允许列表外的任何主机，而不是提示。允许列表与沙箱否则会提示的相同：`allowedDomains` 加上来自 `WebFetch(domain:...)` 允许规则的域名，或当设置了 `allowManagedDomainsOnly` 时仅限托管设置条目。Claude Code 仅对沙箱化命令强制执行此；进程内工具（例如 `WebFetch`）仍然遵循其[权限规则](#permission-rules)。在存储库的 `.claude/settings.json` 或 `.claude/settings.local.json` 中设置它没有效果。需要 Claude Code v2.1.219 或更高版本。

560* **托管锁定**：如果在托管设置中设置了 [`allowManagedDomainsOnly`](/docs/zh-CN/settings-reference#sandbox-network-allowmanageddomainsonly)，非允许的域名会自动被阻止而不是提示，只有来自托管设置的 `allowedDomains` 和 `WebFetch(domain:...)` 允许规则被尊重。562* **托管锁定**：如果在托管设置中设置了 [`allowManagedDomainsOnly`](/docs/zh-CN/settings-reference#sandbox-network-allowmanageddomainsonly)，非允许的域名会自动被阻止而不是提示，只有来自托管设置的 `allowedDomains` 和 `WebFetch(domain:...)` 允许规则被尊重。

561* **企业代理**：当你的网络要求出站流量通过企业代理时，按照[代理配置](/docs/zh-CN/network-config#proxy-configuration)的描述在你的设置的 `env` 块中设置 `HTTPS_PROXY`、`HTTP_PROXY` 和 `NO_PROXY`，以便[后台代理](/docs/zh-CN/network-config#set-network-variables-in-settings-not-the-shell)也能获得它们，或在你启动 Claude Code 的环境中设置。Claude Code 强制执行域名允许列表，然后通过该上游代理隧道允许的连接。563* **企业代理**：当你的网络要求出站流量通过企业代理时，按照[代理配置](/docs/zh-CN/network-config#proxy-configuration)的描述在你的设置的 `env` 块中设置 `HTTPS_PROXY`、`HTTP_PROXY` 和 `NO_PROXY`，以便[后台代理](/docs/zh-CN/network-config#set-network-variables-in-settings-not-the-shell)也能获得它们，或在你启动 Claude Code 的环境中设置。Claude Code 强制执行域名允许列表，然后通过该上游代理隧道允许的连接。

568 内置代理基于请求的主机名强制执行允许列表，默认情况下不会终止或检查 TLS 流量。实验性的 [`network.tlsTerminate`](/docs/zh-CN/settings-reference#sandbox-network-tlsterminate) 设置在 Claude Code v2.1.199 及更高版本中可用，使内置代理自行终止 TLS，这是 [`mask` 凭证条目](#mask-credentials)所需的。有关默认设置的含义，请参阅[安全限制](#security-limitations)，如果你的威胁模型需要 TLS 检查，请参阅[自定义代理配置](#custom-proxy-configuration)。570 内置代理基于请求的主机名强制执行允许列表，默认情况下不会终止或检查 TLS 流量。实验性的 [`network.tlsTerminate`](/docs/zh-CN/settings-reference#sandbox-network-tlsterminate) 设置在 Claude Code v2.1.199 及更高版本中可用，使内置代理自行终止 TLS，这是 [`mask` 凭证条目](#mask-credentials)所需的。有关默认设置的含义，请参阅[安全限制](#security-limitations)，如果你的威胁模型需要 TLS 检查，请参阅[自定义代理配置](#custom-proxy-configuration)。

569</Note>571</Note>

570 572

573<h4 id="per-command-allowed-domains-in-auto-mode">

574 自动模式中按命令允许的域名

575</h4>

576

577在启用沙箱的[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中，Claude 会在命令本身上命名命令需要的主机，而不是为每个连接触发网络批准。在沙箱中运行的每个 Bash、PowerShell 或[监视器](/docs/zh-CN/tools-reference#monitor-tool)命令都可以携带超出沙箱允许列表的主机列表：一个域名，例如 `registry.npmjs.org`，一个通配符，例如 `*.pythonhosted.org`，或一个 IP 地址，每个都带有可选的 `:port`。分类器将主机与命令一起审查。需要 Claude Code v2.1.271 或更高版本。

578

579批准的列表仅为该一个命令打开这些主机，只要它运行。没有任何内容被添加到你的会话允许的主机或你的设置；下一个命令命名它自己的主机。

580

581携带主机的命令会进入分类器，而不是由权限规则或沙箱的[自动允许模式](#sandbox-modes)批准。如果[询问规则](/docs/zh-CN/permissions#manage-permissions)强制对命令进行提示，你的终端中的权限对话框会在其旁边列出主机，在那里批准会同时覆盖两者。

582

583按命令列表仅扩大沙箱默认拒绝的内容。[`deniedDomains`](/docs/zh-CN/settings-reference#sandbox-network-denieddomains) 条目仍然会阻止。当 [`strictAllowlist`](/docs/zh-CN/settings-reference#sandbox-network-strictallowlist) 或 [`allowManagedDomainsOnly`](/docs/zh-CN/settings-reference#sandbox-network-allowmanageddomainsonly) 锁定允许列表时，Claude Code 拒绝按命令列表。

584

585当按命令列表适用时，Claude Code 拒绝连接到没有批准命令列出的主机，没有提示或分类器检查。拒绝在命令的结果中命名主机，Claude 会重新运行添加了主机的命令。

586

571<h4 id="ipv6-addresses-in-domain-lists">587<h4 id="ipv6-addresses-in-domain-lists">

572 域名列表中的 IPv6 地址588 域名列表中的 IPv6 地址

573</h4>589</h4>

598这些相同的原语作为独立的 [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime) 包提供，[Sandbox environments](/docs/zh-CN/sandbox-environments#sandbox-runtime) 页面将其作为包装整个 Claude Code 进程的单独方法进行介绍。614这些相同的原语作为独立的 [`@anthropic-ai/sandbox-runtime`](https://github.com/anthropic-experimental/sandbox-runtime) 包提供，[Sandbox environments](/docs/zh-CN/sandbox-environments#sandbox-runtime) 页面将其作为包装整个 Claude Code 进程的单独方法进行介绍。

599 615

600<h2 id="how-sandboxing-relates-to-permissions-and-permission-modes">616<h2 id="how-sandboxing-relates-to-permissions-and-permission-modes">

601 沙箱如何与权限和权限模式相关617 沙箱隔离与权限和权限模式的关系

602</h2>618</h2>

603 619

604沙箱、[permission rules](/docs/zh-CN/permissions) 和 [permission modes](/docs/zh-CN/permission-modes) 是互补的层。下面的部分介绍沙箱如何与每个交互。620沙箱隔离、[权限规则](/docs/zh-CN/permissions)和[权限模式](/docs/zh-CN/permission-modes)是互补的层级。下面的部分涵盖了沙箱隔离如何与每一个交互。

605 621

606<h3 id="permission-rules">622<h3 id="permission-rules">

607 权限规则623 权限规则

608</h3>624</h3>

609 625

610权限规则和沙箱控制不同的事物：626权限规则和沙箱隔离控制不同的事项：

611 627

612* **权限规则**控制 Claude Code 可以使用哪些工具，在任何工具运行之前进行评估。它们适用于所有工具：Bash、Read、Edit、WebFetch、MCP 和其他工具，除了拒绝或询问规则无法阻止 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior)，而任何其他工具仍然存在。628* **权限规则**控制 Claude Code 可以使用哪些工具，并在任何工具运行之前进行评估。它们适用于每个工具：Bash、Read、Edit、WebFetch、MCP 和其他工具，除了拒绝或询问规则无法阻止 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior)，而任何其他工具仍然存在。

613* **沙箱**提供操作系统级强制执行，限制 Bash 命令在文件系统和网络级别可以访问的内容。它仅适用于 Bash 命令及其子进程。629* **沙箱隔离**提供操作系统级别的强制执行，限制 shell 命令在文件系统和网络级别可以访问的内容。它仅适用于 Bash、PowerShell 和 [Monitor](/docs/zh-CN/tools-reference#monitor-tool) 命令及其子进程。

614 630

615这两个层在强制执行方式上也有所不同。Claude Code 在命令运行之前根据命令字符串和（在自动模式下）单独分类器关于命令是否安全的判断来评估权限决定。操作系统在运行的进程上强制执行沙箱边界，因此无论模型选择运行什么，它都成立，即使允许的命令做的比其名称暗示的更多。631这两个层级在强制执行方式上也有所不同。Claude Code 在命令运行之前根据命令字符串和在自动模式下单独分类器对命令是否安全的判断来评估权限决策。操作系统在运行的进程上强制执行沙箱边界，因此无论模型选择运行什么，即使允许的命令执行的操作超出其名称所示，它也会保持有效。

616 632

617文件系统和网络限制通过沙箱设置和权限规则进行配置：633文件系统和网络限制通过沙箱设置和权限规则进行配置：

618 634

619| 设置或规则 | 它做什么 |635| 设置或规则 | 作用 |

620| :------------------------------------------------------------- | :-------------------------------------------------- |636| :------------------------------------------------------------- | :----------------------------------------------------- |

630 646

631来自沙箱设置和权限规则的路径和域名被合并到最终沙箱配置中。647来自沙箱设置和权限规则的路径和域被合并到最终的沙箱配置中。

632 648

633[claude-code repository 的示例目录](https://github.com/anthropics/claude-code/tree/main/examples/settings)包括常见部署场景的启动设置配置，包括沙箱特定的示例。使用这些作为起点，并根据你的需求调整它们。649[claude-code 存储库的示例目录](https://github.com/anthropics/claude-code/tree/main/examples/settings)包含常见部署场景的启动设置配置，包括沙箱特定的示例。使用这些作为起点，并根据您的需求进行调整。

634 650

635<h3 id="permission-modes">651<h3 id="permission-modes">

636 权限模式652 权限模式

637</h3>653</h3>

638 654

639`/sandbox` 不是 [permission mode](/docs/zh-CN/permission-modes)。权限模式决定工具调用是否运行以及是否首先提示你，而沙箱限制 Bash 命令运行后可以访问的内容。它们在控制的内容和替换每个操作提示的内容上有所不同：655`/sandbox` 不是[权限模式](/docs/zh-CN/permission-modes)。权限模式决定工具调用是否运行以及是否首先提示您，而沙箱限制 Bash 命令运行后可以访问的内容。它们在控制的内容和替代每个操作提示的内容上有所不同：

640 656

641| | 它控制什么 | 替换提示的内容 |657| | 控制的内容 | 替代提示的内容 |

642| :-------------------------------------------------------------------- | :---------------- | :----------------------------------------------------------------------------------------------------------------------------------- |658| :--------------------------------------------------------------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------ |

645| `--dangerously-skip-permissions` | 每个工具调用是否运行 | 无。[受保护路径](/docs/zh-CN/permission-modes#protected-paths)检查也被跳过；[任何模式都不会自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)仍然适用 |661| `--dangerously-skip-permissions` | 每个工具调用是否运行 | 无。[受保护路径](/docs/zh-CN/permission-modes#protected-paths)检查也被跳过；[模式自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)仍然适用 |

646 662

647沙箱的 [auto-allow mode](#sandbox-modes) 与 [auto mode](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 分开：自动允许批准 Bash 命令，因为沙箱边界包含它们，而自动模式使用分类器审查操作。两者独立工作，可以结合。要为无人值守运行选择隔离边界，请参阅 [Sandbox environments](/docs/zh-CN/sandbox-environments#how-isolation-relates-to-permission-modes)。有关常见权限模式和沙箱配对及启动每个配对的标志的表格，请参阅 [Common setups](/docs/zh-CN/permission-modes#common-setups)。663沙箱的[自动允许模式](#sandbox-modes)与[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分开：自动允许批准 Bash 命令是因为沙箱边界包含它们，而自动模式使用分类器来审查操作。这两者独立工作，可以组合，但[沙箱模式](#sandbox-modes)下列出的例外除外。要为无人值守运行选择隔离边界，请参阅[沙箱环境](/docs/zh-CN/sandbox-environments#how-isolation-relates-to-permission-modes)。有关常见权限模式和沙箱配对及启动每个配对的标志的表格，请参阅[常见设置](/docs/zh-CN/permission-modes#common-setups)。

648 664

649<h2 id="configure-the-sandbox-for-your-organization">665<h2 id="configure-the-sandbox-for-your-organization">

650 为你的组织配置沙箱666 为你的组织配置沙箱

656 使用托管设置强制执行沙箱672 使用托管设置强制执行沙箱

657</h3>673</h3>

658 674

659要为每个开发者要求沙箱，通过 [managed settings](/docs/zh-CN/managed-settings#delivery-mechanisms) 提供 `sandbox` 密钥，可以是由你的 MDM 管理的文件，也可以是通过 Claude.ai 上的 [server-managed settings](/docs/zh-CN/server-managed-settings)。675要为每个开发者要求沙箱，通过 [managed settings](/docs/zh-CN/managed-settings#delivery-mechanisms) 提供 `sandbox` 密钥，可以是由你的 MDM 管理的文件，也可以是通过 claude.ai 上的 [server-managed settings](/docs/zh-CN/server-managed-settings)。

660 676

661以下托管设置配置启用沙箱，如果沙箱无法初始化则拒绝启动 Claude Code，并防止模型在沙箱外重试命令：677以下托管设置配置启用沙箱，如果沙箱无法初始化则拒绝启动 Claude Code，并防止模型在沙箱外重试命令：

662 678

scheduled-tasks.md +2 −2

Details

169cancel the deploy check job169cancel the deploy check job

170```170```

171 171

172在幕后，Claude 使用这些工具：172这些是 Claude 使用的底层工具：

173 173

174| 工具 | 目的 |174| 工具 | 目的 |

175| :----------- | :------------------------------------------ |175| :----------- | :------------------------------------------ |

238* 任务仅在 Claude Code 运行且空闲时触发。关闭终端或让会话退出会停止它们触发。[将会话放在后台](/docs/zh-CN/agent-view#from-inside-a-session)会将 `/loop` 任务转移到后台会话，该会话继续运行而无需终端。238* 任务仅在 Claude Code 运行且空闲时触发。关闭终端或让会话退出会停止它们触发。[将会话放在后台](/docs/zh-CN/agent-view#from-inside-a-session)会将 `/loop` 任务转移到后台会话，该会话继续运行而无需终端。

239* 没有错过触发的追赶。如果任务的计划时间在 Claude 忙于长时间运行的请求时经过，它会在 Claude 变为空闲时触发一次，而不是每个错过的间隔触发一次。239* 没有错过触发的追赶。如果任务的计划时间在 Claude 忙于长时间运行的请求时经过，它会在 Claude 变为空闲时触发一次，而不是每个错过的间隔触发一次。

240* 启动新对话会清除所有会话范围的任务。当您使用 `claude --resume` 或 `claude --continue` 恢复会话时，Claude Code 会恢复使用 `CronCreate` 调度的任务，除了已[过期](#seven-day-expiry)的重复任务和计划时间已经过去的一次性任务。[自定步调的 `/loop`](#let-claude-choose-the-interval)不会被恢复，因此请再次运行 `/loop` 以重新启动它。后台 Bash 和监视器任务在恢复时永远不会被恢复。240* 启动新对话会清除所有会话范围的任务。当您使用 `claude --resume` 或 `claude --continue` 恢复会话时，Claude Code 会恢复使用 `CronCreate` 调度的任务，除了已[过期](#seven-day-expiry)的重复任务和计划时间已经过去的一次性任务。[自定步调的 `/loop`](#let-claude-choose-the-interval)不会被恢复，因此请再次运行 `/loop` 以重新启动它。后台 Bash 和监视器任务在恢复时永远不会被恢复。

241* 当[功能标志获取关闭](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)时，Claude Code 会将您要求在会话间保留的任务存储在项目的 `.claude` 目录中。当该目录或其中的任务文件是符号链接时，Claude Code 会返回错误而不是调度任务。241* 当[功能标志获取关闭](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)时，Claude Code 会将您要求在会话间保留的任务存储在项目的 `.claude/scheduled_tasks.json` 文件中。当 `.claude` 目录或该文件是符号链接时，Claude Code 会返回错误而不是调度任务。保存的任务仅在您创建它的项目文件夹中运行。如果您将文件复制到另一个文件夹（例如新的 worktree），那里的会话会列出复制的任务但不会运行它们，因此请在该文件夹中再次创建任务。

242 242

243对于需要无人值守运行的 cron 驱动自动化：243对于需要无人值守运行的 cron 驱动自动化：

244 244

security.md +2 −2

Details

122 云执行安全性122 云执行安全性

123</h2>123</h2>

124 124

125使用 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 时，会实施额外的安全控制。您的组织路由到 [自托管环境](/docs/zh-CN/self-hosted-environments) 的会话在您自己的基础设施上运行，其中隔离、网络出口和 git 凭证是您部署的责任。在 Anthropic 托管的环境中：125使用 [cloud sessions](/docs/zh-CN/claude-code-on-the-web) 时，会实施额外的安全控制。您的组织路由到 [自托管环境](/docs/zh-CN/self-hosted-environments) 的会话在您自己的基础设施上运行，其中隔离、网络出口和 git 凭证是您部署的责任。在 Anthropic 托管的环境中：

126 126

127* **隔离的虚拟机**：每个云会话在隔离的、由 Anthropic 管理的 VM 中运行127* **隔离的虚拟机**：每个云会话在隔离的、由 Anthropic 管理的 VM 中运行

128* **网络访问控制**：网络访问默认受限，可以配置为禁用或仅允许特定域128* **网络访问控制**：网络访问默认受限，可以配置为禁用或仅允许特定域

131* **审计日志**：云会话中的所有操作都被记录以用于合规和审计目的131* **审计日志**：云会话中的所有操作都被记录以用于合规和审计目的

132* **自动清理**：会话 VM 在一段时间不活动后被回收132* **自动清理**：会话 VM 在一段时间不活动后被回收

133 133

134有关云执行的更多详情，请参阅 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web)；要为云会话配置网络访问，请参阅 [Configure cloud environments](/docs/zh-CN/cloud-environments#network-access)。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 135

136[Remote Control](/docs/zh-CN/remote-control) 会话的工作方式不同：Web 界面连接到在您本地机器上运行的 Claude Code 进程。所有代码执行和文件访问都保持本地，会话流量通过 TLS 上的 Anthropic API 传输；连接时，会话记录存储在 Anthropic 服务器上以跨设备同步对话，如 [Connection and security](/docs/zh-CN/remote-control#connection-and-security) 中所述。不涉及云 VM 或沙箱。连接使用多个短期的、范围狭窄的凭证，每个凭证限制于特定目的并独立过期，以限制任何单个受损凭证的影响范围。136[Remote Control](/docs/zh-CN/remote-control) 会话的工作方式不同：Web 界面连接到在您本地机器上运行的 Claude Code 进程。所有代码执行和文件访问都保持本地，会话流量通过 TLS 上的 Anthropic API 传输；连接时，会话记录存储在 Anthropic 服务器上以跨设备同步对话，如 [Connection and security](/docs/zh-CN/remote-control#connection-and-security) 中所述。不涉及云 VM 或沙箱。连接使用多个短期的、范围狭窄的凭证，每个凭证限制于特定目的并独立过期，以限制任何单个受损凭证的影响范围。

137 137

security-guidance.md +2 −2

Details

34`/plugin` 打开一个交互式面板，仅在终端 CLI 中可用。如果 Claude 回复说 `/plugin` 在此环境中不可用，请以其他方式安装：34`/plugin` 打开一个交互式面板，仅在终端 CLI 中可用。如果 Claude 回复说 `/plugin` 在此环境中不可用，请以其他方式安装：

35 35

36* **Claude 桌面应用、本地或 SSH 会话**：通过点击提示旁边的 **+** 按钮，然后点击 **Plugins**，再点击 **Add plugin** 来打开 [插件浏览器](/docs/zh-CN/desktop#install-plugins)36* **Claude 桌面应用、本地或 SSH 会话**：通过点击提示旁边的 **+** 按钮，然后点击 **Plugins**，再点击 **Add plugin** 来打开 [插件浏览器](/docs/zh-CN/desktop#install-plugins)

~~37* **网络上的 Claude Code 或桌面云会话**：在 `.claude/settings.json` 中声明插件，如 [在云会话中启用](#enable-in-cloud-sessions-and-shared-repositories) 下所示~~37* **云会话**：在 `.claude/settings.json` 中声明插件，如 [在云会话和共享存储库中启用](#enable-in-cloud-sessions-and-shared-repositories) 下所示

38 38

39终端安装会提示输入范围。选择用户范围以将插件写入您的用户设置，这样它会在您在此计算机上启动的每个新本地会话中加载。39终端安装会提示输入范围。选择用户范围以将插件写入您的用户设置，这样它会在您在此计算机上启动的每个新本地会话中加载。

40 40

49 在云会话和共享存储库中启用49 在云会话和共享存储库中启用

50</h3>50</h3>

51 51

52用户范围的插件不会进入 [网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)，因为这些会话在云上运行，而不是在您的计算机上。要在那里启用该插件，或为克隆存储库的所有人打开它，请在项目的已检入设置中声明它：52用户范围的插件不会进入 [云会话](/docs/zh-CN/claude-code-on-the-web)，因为这些会话不在您的计算机上运行。要在那里启用该插件，或为克隆存储库的所有人打开它，请在项目的已检入设置中声明它：

53 53

54```json .claude/settings.json theme={null}54```json .claude/settings.json theme={null}

55{55{

self-hosted-environments.md +3 −3

Details

10 自托管环境在 Team 和 Enterprise 计划上处于公开测试阶段，默认关闭。请参阅[可用性和限制](#availability-and-limitations)了解启用路径和排除的内容。10 自托管环境在 Team 和 Enterprise 计划上处于公开测试阶段，默认关闭。请参阅[可用性和限制](#availability-and-limitations)了解启用路径和排除的内容。

11</Note>11</Note>

12 12

13自托管环境在您的组织运营的基础设施上执行 Claude Code 云会话。[云会话](/docs/zh-CN/claude-code-on-the-web)是指在开发者机器以外的任何地方运行的会话：开发者可以从 claude.ai、移动和桌面应用、带有 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-web) 的终端以及[计划例程](/docs/zh-CN/routines)启动这些会话，默认情况下它们在 Anthropic 的基础设施上执行。在自托管环境中，这些相同的会话在您的网络内执行，开发者体验基本相同，除了[可用性和限制](#availability-and-limitations)中的差异以及部署页面的[已知问题](/docs/zh-CN/self-hosted-environments-deploy#known-issues-and-limitations)。13自托管环境在您的组织运营的基础设施上执行 Claude Code 云会话。[云会话](/docs/zh-CN/claude-code-on-the-web)是指在开发者机器以外的任何地方运行的会话：开发者可以从 claude.ai、移动和桌面应用、带有 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud) 的终端以及[计划例程](/docs/zh-CN/routines)启动这些会话，默认情况下它们在 Anthropic 的基础设施上执行。在自托管环境中，这些相同的会话在您的网络内执行，开发者体验基本相同，除了[可用性和限制](#availability-and-limitations)中的差异以及部署页面的[已知问题](/docs/zh-CN/self-hosted-environments-deploy#known-issues-and-limitations)。

14 14

15如果您的团队不使用云会话，这里没有什么需要配置的：终端或 IDE 中的会话始终在开发者自己的机器上运行。如果您想在自己的常开机器上运行 Claude Code 并从其他设备驱动它，请使用[远程控制](/docs/zh-CN/remote-control)，它也可在 Pro 和 Max 计划上使用。当您准备好设置时，直接转到[快速入门](/docs/zh-CN/self-hosted-environments-quickstart)；如果您想先审查安全态势，请从[部署到生产](/docs/zh-CN/self-hosted-environments-deploy)开始。本页的其余部分解释自托管的工作原理以及何时选择它。15如果您的团队不使用云会话，这里没有什么需要配置的：终端或 IDE 中的会话始终在开发者自己的机器上运行。如果您想在自己的常开机器上运行 Claude Code 并从其他设备驱动它，请使用[远程控制](/docs/zh-CN/remote-control)，它也可在 Pro 和 Max 计划上使用。当您准备好设置时，直接转到[快速入门](/docs/zh-CN/self-hosted-environments-quickstart)；如果您想先审查安全态势，请从[部署到生产](/docs/zh-CN/self-hosted-environments-deploy)开始。本页的其余部分解释自托管的工作原理以及何时选择它。

16 16

44 44

45在规划推出之前检查这些：45在规划推出之前检查这些：

46 46

47* **计划**：Team 和 Enterprise 组织的公开测试版。自托管环境默认关闭；[所有者](/docs/zh-CN/cloud-environments#organization-shared-environments)在[**云环境**管理页面](https://claude.ai/admin-settings/cloud-environments)上打开**允许自托管环境**，这需要为组织启用 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web)。47* **计划**：Team 和 Enterprise 组织的公开测试版。自托管环境默认关闭；[所有者](/docs/zh-CN/cloud-environments#organization-shared-environments)在[**云环境**管理页面](https://claude.ai/admin-settings/cloud-environments)上打开**允许自托管环境**，这需要为组织启用 [cloud sessions](/docs/zh-CN/claude-code-on-the-web)。

48* **零数据保留**：对于启用了[零数据保留](/docs/zh-CN/zero-data-retention)的组织不可用。48* **零数据保留**：对于启用了[零数据保留](/docs/zh-CN/zero-data-retention)的组织不可用。

49* **模型推理**：会话使用 Anthropic API，推理不能通过 [Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry](/docs/zh-CN/third-party-integrations) 或 [LLM 网关](/docs/zh-CN/llm-gateway)路由。49* **模型推理**：会话使用 Anthropic API，推理不能通过 [Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry](/docs/zh-CN/third-party-integrations) 或 [LLM 网关](/docs/zh-CN/llm-gateway)路由。

50* **表面**：从 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web)、移动和桌面应用、[计划例程](/docs/zh-CN/routines)以及终端启动的会话，带有 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-web) 或 [`--environment` 调度](/docs/zh-CN/self-hosted-environments-testing#run-the-test-loop)，可以在自托管环境中运行。[Claude Tag](https://claude.com/docs/claude-tag/overview) 会话也可以在其中运行，但 Claude 还不能在这些会话中使用[访问包](https://claude.com/docs/claude-tag/concepts/glossary#access-bundle)。[Claude Security](/docs/zh-CN/claude-security) 和[代码审查](/docs/zh-CN/code-review)会话还不能路由到它们。对这两个表面的支持将单独跟进。50* **表面**：从 [claude.ai/code](https://claude.ai/code)、移动和桌面应用、[计划例程](/docs/zh-CN/routines)以及终端启动的会话，带有 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud) 或 [`--environment` 调度](/docs/zh-CN/self-hosted-environments-testing#run-the-test-loop)，可以在自托管环境中运行。[Claude Tag](https://claude.com/docs/claude-tag/overview) 会话也可以在其中运行，但 Claude 还不能在这些会话中使用[访问包](https://claude.com/docs/claude-tag/concepts/glossary#access-bundle)。[Claude Security](/docs/zh-CN/claude-security) 和[代码审查](/docs/zh-CN/code-review)会话还不能路由到它们。对这两个表面的支持将单独跟进。

51* **存储库**：会话从 GitHub 检出存储库；请参阅 [GitHub 身份验证选项](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)。51* **存储库**：会话从 GitHub 检出存储库；请参阅 [GitHub 身份验证选项](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)。

52* **计费**：自托管环境中的会话消耗您的组织的 Claude Code 使用情况，与 Anthropic 托管环境中的会话相同。52* **计费**：自托管环境中的会话消耗您的组织的 Claude Code 使用情况，与 Anthropic 托管环境中的会话相同。

53 53

self-hosted-environments-configuration.md +3 −1

Details

407 每个会话的配置如何组装407 每个会话的配置如何组装

408</h3>408</h3>

409 409

410运行器为每个会话提供自己的配置目录，从运行器在启动时捕获的主机 `~/.claude/` 的内存快照中播种：`settings.json`、`CLAUDE.md`、钩子、代理、命令和技能在您的运行器镜像中应用于每个会话作为用户级基线。因为快照在启动时获取，运行主机上的配置更改仅在运行器重启后生效。设置 `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` 以从不同路径播种，或将其指向空目录以禁用播种。410运行器为每个会话提供自己的配置目录，从运行器在启动时捕获的主机 `~/.claude/` 的快照中播种：`settings.json`、`CLAUDE.md`、钩子、代理、命令和技能在您的运行器镜像中应用于每个会话作为用户级基线。如果您更改运行主机上的配置，更改仅在您重启运行器后生效。

411

412设置 `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` 以从不同路径播种，或将其指向空目录以禁用播种。

411 413

412存储库提交的 `.claude/settings.json` 作为项目设置分层。会话还从运行器镜像中的标准系统路径读取 [`managed-settings.json`](/docs/zh-CN/settings#where-settings-live)。其密钥是否与 [server-managed settings](/docs/zh-CN/server-managed-settings) 一起应用遵循 [how Claude Code combines managed sources](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)：默认情况下，当您的组织交付任何服务器管理的密钥时，会话忽略运行器镜像的文件，除了 [keys Claude Code reads from every admin source](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)，例如 `env` 块、沙箱锁、沙箱二进制路径和 `forceRemoteSettingsRefresh`。请参阅 [settings precedence](/docs/zh-CN/settings#settings-precedence)。414存储库提交的 `.claude/settings.json` 作为项目设置分层。会话还从运行器镜像中的标准系统路径读取 [`managed-settings.json`](/docs/zh-CN/settings#where-settings-live)。其密钥是否与 [server-managed settings](/docs/zh-CN/server-managed-settings) 一起应用遵循 [how Claude Code combines managed sources](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)：默认情况下，当您的组织交付任何服务器管理的密钥时，会话忽略运行器镜像的文件，除了 [keys Claude Code reads from every admin source](/docs/zh-CN/managed-settings#keys-read-from-every-admin-source)，例如 `env` 块、沙箱锁、沙箱二进制路径和 `forceRemoteSettingsRefresh`。请参阅 [settings precedence](/docs/zh-CN/settings#settings-precedence)。

413 415

self-hosted-environments-deploy.md +18 −12

Details

434 434

435* **任何克隆形状都可以工作**：路径处的完整、浅层或单分支克隆按原样使用。运行器在获取到现有克隆时永远不会传递 `--depth`，因此完整的预热保持其完整历史，浅层克隆保持浅层。`CLAUDE_RUNNER_FETCH_DEPTH`（`full`、`0` 或一个数字；默认 50）仅控制当尚不存在克隆时运行器进行的冷克隆。435* **任何克隆形状都可以工作**：路径处的完整、浅层或单分支克隆按原样使用。运行器在获取到现有克隆时永远不会传递 `--depth`，因此完整的预热保持其完整历史，浅层克隆保持浅层。`CLAUDE_RUNNER_FETCH_DEPTH`（`full`、`0` 或一个数字；默认 50）仅控制当尚不存在克隆时运行器进行的冷克隆。

436* **跟踪的更改重置，未跟踪的文件保留**：每个会话从硬重置开始，该重置会清除前一个会话的跟踪修改，但运行器永远不会运行 `git clean`，因此来自锁定所有者早期会话的未跟踪文件保留在树中。436* **跟踪的更改重置，未跟踪的文件保留**：每个会话从硬重置开始，该重置会清除前一个会话的跟踪修改，但运行器永远不会运行 `git clean`，因此来自锁定所有者早期会话的未跟踪文件保留在树中。

437* **按会话目录也会保留**：在检出旁边，运行器在 `<base-dir>/_sessions/` 下为其运行的每个会话创建按会话条目。会话的 Claude 配置目录保存对话记录的本地副本。在其旁边是会话的上传文件，当会话有任何文件时。会话目录也在那里：它保存会话运行时的任何按会话工作树和 `checkout` hook 检出，以及 Claude 在其中写入的任何其他内容。

438

439 默认情况下，运行器在会话结束时将这些保留在原地，因此在持久化的磁盘上它们会累积。每个会话都以运行器自己的用户身份运行，因此该磁盘服务的任何后续会话都可以读取它们。如果保持持久的 `--base-dir`，请为该增长调整卷的大小。同样适用于在同一文件系统上重启运行器的任何设置，包括 [Docker Compose 配方](#docker-compose)。

440* **使用 `--remove-session-state` 时，按会话目录不会保留**：使用 [`--remove-session-state`](/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags) 启动运行器，以便在会话结束时删除每个会话的按会话目录。删除是尽力而为的：当运行器在清理运行前被杀死时，目录保留。规范克隆和会话在主机上其他地方写入的文件，例如临时目录，无论如何都会保留。

437* **使用 git 代理时，重置变成检出**：使用 [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)，运行器在每个会话前清理克隆的 `.git/`，保留对象存储、引用和浅层状态，但删除索引，因此每个会话需要进行完整的工作树检出而不是近乎瞬间的重置；它仍然永远不会重新克隆。代理下不支持子模块预热。441* **使用 git 代理时，重置变成检出**：使用 [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy)，运行器在每个会话前清理克隆的 `.git/`，保留对象存储、引用和浅层状态，但删除索引，因此每个会话需要进行完整的工作树检出而不是近乎瞬间的重置；它仍然永远不会重新克隆。代理下不支持子模块预热。

438* **长克隆不需要解决方法**：运行器使用 120 秒无进度监视器和 30 分钟硬上限来限制每个 git 操作，而不是平面超时，因此保持报告进度的缓慢冷克隆会完成。442* **长克隆不需要解决方法**：运行器使用 120 秒无进度监视器和 30 分钟硬上限来限制每个 git 操作，而不是平面超时，因此保持报告进度的缓慢冷克隆会完成。

439 443

512 故障排除516 故障排除

513</h2>517</h2>

514 518

515为了获得引导诊断，在运行器主机上运行 doctor 子命令。doctor 子命令启动交互式 Claude Code 会话，附加运行器的日志和状态。首先在该主机上使用 `claude auth login` 登录，以便会话可以查询您的环境、其运行器和其排队的会话。没有该登录，例如当主机使用 API 密钥进行身份验证时，它仅限于本地健康端点、指标和运行器的日志，并且仅在您使用 `--log-file` 启动运行器时读取日志。519如需引导式诊断，请在运行器主机上运行 doctor 子命令。doctor 子命令启动一个交互式 Claude Code 会话，并附加运行器的日志和状态。首先在该主机上使用 `claude auth login` 登录，以便会话可以查询您的环境、其运行器和排队的会话。如果没有该登录（例如当主机使用 API 密钥进行身份验证时），它仅限于本地健康端点、指标和运行器日志，并且仅当您使用 `--log-file` 启动运行器时才读取日志。

516 520

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

518claude self-hosted-runner doctor522claude self-hosted-runner doctor

520 524

521常见问题：525常见问题：

522 526

523* **运行器不出现在环境中**：确认主机可以通过 HTTPS 到达 `api.anthropic.com`，环境密钥是最新的，主机时钟在真实时间的五分钟内；更大的偏差导致身份验证失败。运行器在身份验证失败时使用拒绝原因记录 `[runner:fatal]`。527* **运行器未出现在环境中**：确认主机可以通过 HTTPS 到达 `api.anthropic.com`，环境密钥是最新的，并且主机时钟与实际时间相差在五分钟以内；更大的时间偏差会导致身份验证失败。运行器在身份验证失败时会记录 `[runner:fatal]` 和拒绝原因。

524* **运行器在启动时以 `cannot create or write to base directory` 退出**：运行器无法创建或写入 `--base-dir`，默认为 `/workspace`。修复目录的所有权或将 `--base-dir` 指向可写路径，如[在运行器之间保持基目录和容量相同](#keep-the-base-directory-and-capacity-identical-across-runners)所述。如果运行器改为记录 `[runner:fatal]` 说基目录检查超时，目录在挂起的 NFS 或 CSI 挂载上。检查挂载健康而不是权限。运行器在打开 `--log-file` 之前将这两个启动失败打印到 stderr，所以在终端或您的平台的容器日志中查找它们，而不是日志文件。在 v2.1.225 之前，运行器在启动时不检查基目录，此错误配置在获取后失败会话。528* **运行器在启动时退出，显示 `cannot create or write to base directory`**：运行器无法创建或写入 `--base-dir`，其默认值为 `/workspace`。修复目录的所有权或将 `--base-dir` 指向可写路径，如 [保持基础目录和容量在运行器之间相同](#keep-the-base-directory-and-capacity-identical-across-runners) 中所述。如果运行器改为记录 `[runner:fatal]` 说基础目录检查超时，则该目录位于挂起的 NFS 或 CSI 挂载上。检查挂载健康状况而不是权限。运行器在打开 `--log-file` 之前将这两个启动失败打印到 stderr，因此请在终端或您的平台的容器日志中查找它们，而不是日志文件。在 v2.1.225 之前，运行器在启动时不检查基础目录，此错误配置在拾取后失败会话。

525* **会话保持排队**：每个在线运行器可能被锁定到不同的所有者。检查每个运行器的 `claude_code_self_hosted_runner_locked_account` [指标](/docs/zh-CN/self-hosted-environments-reference#prometheus-metrics)或其 `[runner:health]` 日志行的 `locked_account` 字段以查看谁持有它。两者仅在运行器被发出携带 `act.email` 声明的会话令牌后显示所有者的电子邮件，Claude Tag 代理的会话永远不会这样做。没有声明，运行器发出没有 `locked_account` 系列并记录 `locked_account=yes`，这告诉您运行器被锁定但不是对哪个所有者。添加副本，或等待现有运行器 drain 并重启。如果环境使用按需运行器，改为检查编排器；请参阅[按需运行器](/docs/zh-CN/self-hosted-environments-configuration#on-demand-runners)。529* **会话保持排队**：每个在线运行器可能被锁定到不同的所有者。检查每个运行器的 `claude_code_self_hosted_runner_locked_account` [指标](/docs/zh-CN/self-hosted-environments-reference#prometheus-metrics) 或其 `[runner:health]` 日志行的 `locked_account` 字段，以查看谁持有它。两者仅在运行器被颁发携带 `act.email` 声明的会话令牌后才显示所有者的电子邮件，Claude Tag 代理的会话永远不会这样做。没有该声明，运行器不发出 `locked_account` 系列，并记录 `locked_account=yes`，这告诉您运行器被锁定但不知道是哪个所有者。添加副本，或等待现有运行器耗尽并重新启动。如果环境使用按需运行器，请改为检查编排器；请参阅 [按需运行器](/docs/zh-CN/self-hosted-environments-configuration#on-demand-runners)。

526* **会话在获取后立即失败**：在 claude.ai/code 中打开会话以查看错误。最常见的原因是运行器镜像中缺少 [git 凭证](#configure-git)和未安装的构建工具。不可写的基目录在启动时停止运行器，而不是失败会话。请参阅此列表中的**运行器在启动时以 `cannot create or write to base directory` 退出**条目。530* **会话在拾取后立即失败**：在 claude.ai/code 中打开会话以查看错误。最常见的原因是运行器镜像中缺少 [git 凭证](#configure-git) 和未安装的构建工具。不可写的基础目录会在启动时停止运行器，而不是失败会话。请参阅此列表中的 **运行器在启动时退出，显示 `cannot create or write to base directory`** 条目。

527* **会话无法通过身份验证的出站代理到达网络**：当您使用 [`--proxy-authorization-command` 或 `--proxy-authorization-file`](#authenticate-to-an-egress-proxy) 设置的源失败、在 30 秒后超时或产生空值时，运行器以 `502 Bad Gateway` 应答该连接并记录原因。运行器在该日志中编辑命令的 stderr，从不记录标头值。使用 `--proxy-authorization-command`，在主机上自己运行命令以确认它在 stdout 上打印整个标头值。如果运行器改为在启动时以 `could not start the proxy-authorization listener` 退出，它无法打开其环回侦听器。531* **会话无法通过身份验证出口代理到达网络**：当您使用 [`--proxy-authorization-command` 或 `--proxy-authorization-file`](#authenticate-to-an-egress-proxy) 设置的源失败、在 30 秒后超时或产生空值时，运行器以 `502 Bad Gateway` 应答该连接并记录原因。运行器在该日志中编辑命令的 stderr，并且永远不会记录标头值。使用 `--proxy-authorization-command` 时，在主机上自己运行该命令以确认它在 stdout 上打印整个标头值。如果运行器改为在启动时退出，显示 `could not start the proxy-authorization listener`，则它无法打开其环回监听器。

528* **运行器记录 `Poll failed` 行包含 `rejecting the malformed poll response`**：运行器接收工作轮询响应，其主体不是队列的预期 JSON，最常见的是因为运行器和 `api.anthropic.com` 之间的某些东西（例如拦截代理或强制门户）用其自己的页面应答。运行器拒绝响应，在 `claude_code_self_hosted_runner_poll_errors_total` [指标](/docs/zh-CN/self-hosted-environments-reference#prometheus-metrics)的 `transport` 类型下计数，并在[会话生命周期](/docs/zh-CN/self-hosted-environments#session-lifecycle)中描述的失败轮询计划上重试。运行器继续为其活跃会话服务。配置代理以从 `api.anthropic.com` 通过未更改的响应。在 v2.1.246 之前，运行器将此类响应读取为空工作队列，这可能会结束其活跃会话或使其退出。532* **运行器记录包含 `rejecting the malformed poll response` 的 `Poll failed` 行**：运行器收到的工作轮询响应的正文不是队列的预期 JSON，最常见的原因是运行器和 `api.anthropic.com` 之间的某些内容（例如拦截代理或强制门户）用自己的页面进行了应答。运行器拒绝响应，在 `claude_code_self_hosted_runner_poll_errors_total` [指标](/docs/zh-CN/self-hosted-environments-reference#prometheus-metrics) 的 `transport` 类型下计数，并按 [会话生命周期](/docs/zh-CN/self-hosted-environments#session-lifecycle) 中描述的失败轮询计划重试。运行器继续为其实时会话提供服务。配置代理以将来自 `api.anthropic.com` 的响应原封不动地传递。在 v2.1.246 之前，运行器将这样的响应读取为空工作队列，这可能会结束其实时会话或使其退出。

529* **会话的分支不再存在于远程**：对于会话仅从中读取的 git 源，运行器跳过该源并继续其余的。对于会话推送结果的源，删除的分支（通常因为它被合并和自动删除）使会话失败，错误命名存储库和分支，并要求您恢复分支并重试。当跳过会使其没有存储库时，运行器使用相同的错误使会话失败。在 v2.1.228 之前，此类会话在空目录中启动。533* **会话的分支在远程上不再存在**：对于会话仅从中读取的 git 源，运行器跳过该源并继续处理其余源。对于会话推送结果的源，删除的分支（通常是因为它被合并并自动删除）会导致会话失败，并显示一个错误，命名存储库和分支，并要求您恢复分支并重试。当跳过会导致它完全没有存储库时，运行器会以相同的错误失败会话。在 v2.1.228 之前，这样的会话在空目录中启动。

530* **会话需要数分钟才能启动**：初始克隆通常主导。观看 `claude_code_self_hosted_runner_session_init_duration_seconds` [指标](/docs/zh-CN/self-hosted-environments-reference#prometheus-metrics)以确认，并使用[预热检出](#reuse-a-pre-warmed-checkout)或较小的 `CLAUDE_RUNNER_FETCH_DEPTH` 切割克隆。534* **会话需要数分钟才能启动**：初始克隆通常占主导地位。观察 `claude_code_self_hosted_runner_session_init_duration_seconds` [指标](/docs/zh-CN/self-hosted-environments-reference#prometheus-metrics) 以确认，并使用 [预热检出](#reuse-a-pre-warmed-checkout) 或更小的 `CLAUDE_RUNNER_FETCH_DEPTH` 减少克隆。

531* **Pod 在 drain 中途被杀死**：将 `terminationGracePeriodSeconds` 提高到至少运行器在启动时记录的值。请参阅[关闭时序](#shutdown-timing)。535* **Pod 在耗尽中途被杀死**：将 `terminationGracePeriodSeconds` 提高到至少运行器在启动时记录的值。请参阅 [关闭时序](#shutdown-timing)。

~~532~~ 536

533日志初始化后，运行器将其生命周期日志（包括 `[runner:fatal]` 行）写入 stdout，调试输出写入 stderr，都作为纯文本行而不是 JSON。上面故障排除条目中描述的启动失败在该点之前打印到 stderr。使用 `--log-file` 捕获两个流，这也让 `self-hosted-runner doctor` 尾随它们，或使用您的平台的日志收集。每个会话的子进程写入单独的调试日志。失败时运行器保留日志，在运行器日志中打印日志的路径，并在 claude.ai/code 中的会话旁边显示日志的尾部。537初始化日志后，运行器将其生命周期日志（包括 `[runner:fatal]` 行）写入 stdout，将调试输出写入 stderr，全部作为纯文本行而不是 JSON。上述故障排除条目中描述的启动失败在该点之前打印到 stderr。使用 `--log-file` 捕获两个流，这也让 `self-hosted-runner doctor` 能够跟踪它们，或使用您的平台的日志收集。

538

539每个会话的子进程写入单独的调试日志。失败时，运行器在 claude.ai/code 中将日志的尾部与会话一起显示。除非您使用 [`--remove-session-state`](/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags) 启动了运行器，否则它也会在磁盘上保留失败会话的日志，并在运行器日志中打印其路径。

534 540

535<h2 id="what’s-next">541<h2 id="what’s-next">

536 接下来542 接下来

self-hosted-environments-identity.md +1 −1

Details

10 自托管环境在 Team 和 Enterprise 计划上处于公开测试阶段；[所有者](/docs/zh-CN/cloud-environments#organization-shared-environments)可以通过在[**云环境**管理页面](https://claude.ai/admin-settings/cloud-environments)上打开**允许自托管环境**来启用它们。本页面涵盖会话身份验证；有关设置，请参阅[快速入门](/docs/zh-CN/self-hosted-environments-quickstart)，有关舰队配方，请参阅[部署到生产](/docs/zh-CN/self-hosted-environments-deploy)。10 自托管环境在 Team 和 Enterprise 计划上处于公开测试阶段；[所有者](/docs/zh-CN/cloud-environments#organization-shared-environments)可以通过在[**云环境**管理页面](https://claude.ai/admin-settings/cloud-environments)上打开**允许自托管环境**来启用它们。本页面涵盖会话身份验证；有关设置，请参阅[快速入门](/docs/zh-CN/self-hosted-environments-quickstart)，有关舰队配方，请参阅[部署到生产](/docs/zh-CN/self-hosted-environments-deploy)。

11</Note>11</Note>

12 12

13[自托管环境](/docs/zh-CN/self-hosted-environments)让[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web) 会话在您运营的基础设施上运行，而不是在 Anthropic 的基础设施上运行。由于会话在您的网络内运行，Claude 可以直接调用您的内部服务。这些服务需要一种方式来确认请求来自您环境中的 Claude Code 会话，并识别创建该会话的用户或服务身份。13[自托管环境](/docs/zh-CN/self-hosted-environments)让 Claude Code [云会话](/docs/zh-CN/claude-code-on-the-web)在您运营的基础设施上运行，而不是在 Anthropic 的基础设施上运行。由于会话在您的网络内运行，Claude 可以直接调用您的内部服务。这些服务需要一种方式来确认请求来自您环境中的 Claude Code 会话，并识别创建该会话的用户或服务身份。

14 14

15自托管环境中的每个会话都会在 `CLAUDE_CODE_SESSION_ACCESS_TOKEN` 环境变量中收到一个签名的 JSON Web Token (JWT)。会话像任何持有者凭证一样呈现令牌；例如，Claude 运行的脚本可以使用 `curl -H "Authorization: Bearer $CLAUDE_CODE_SESSION_ACCESS_TOKEN"` 调用您的服务。Anthropic 对令牌进行签名，并在公开 JWKS 端点发布验证密钥。您的服务获取这些密钥，验证签名，并读取声明以决定授予什么访问权限。15自托管环境中的每个会话都会在 `CLAUDE_CODE_SESSION_ACCESS_TOKEN` 环境变量中收到一个签名的 JSON Web Token (JWT)。会话像任何持有者凭证一样呈现令牌；例如，Claude 运行的脚本可以使用 `curl -H "Authorization: Bearer $CLAUDE_CODE_SESSION_ACCESS_TOKEN"` 调用您的服务。Anthropic 对令牌进行签名，并在公开 JWKS 端点发布验证密钥。您的服务获取这些密钥，验证签名，并读取声明以决定授予什么访问权限。

16 16

self-hosted-environments-reference.md +3 −0

Details

32| `--defer-shutdown-max-min <n>` | `SELF_HOSTED_RUNNER_DEFER_SHUTDOWN_MAX_MS` | `0` | 在第一个 `SIGTERM` 或 `SIGINT` 上，继续为已附加的会话提供服务而不是排空它们，然后在 N 分钟后释放仍然附加的任何内容并退出。在设置此值之前提高主机的停止超时。请参阅[将排空推迟到第一个信号之后](/docs/zh-CN/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal)。`0` 禁用。需要 Claude Code v2.1.238 或更高版本。 |32| `--defer-shutdown-max-min <n>` | `SELF_HOSTED_RUNNER_DEFER_SHUTDOWN_MAX_MS` | `0` | 在第一个 `SIGTERM` 或 `SIGINT` 上，继续为已附加的会话提供服务而不是排空它们，然后在 N 分钟后释放仍然附加的任何内容并退出。在设置此值之前提高主机的停止超时。请参阅[将排空推迟到第一个信号之后](/docs/zh-CN/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal)。`0` 禁用。需要 Claude Code v2.1.238 或更高版本。 |

33| `--drain-grace-sec <n>` | `SELF_HOSTED_RUNNER_DRAIN_GRACE_MS` | `0` | 在运行器接收到关闭信号或达到其退休时间之前，控制运行器在其活跃会话完成后何时退出：`0` 立即退出而不轮询更多内容，正值使运行器保持活跃并首先重新轮询锁定所有者的队列那么多秒，代价是[加强部分](/docs/zh-CN/self-hosted-environments-deploy#harden-your-deployment)中描述的每个会话容器隔离。在您使用 [`--defer-shutdown-max-min`](/docs/zh-CN/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal) 推迟的第一个信号之后，运行器在不持有任何会话时立即退出，无论您在此处设置什么。 |33| `--drain-grace-sec <n>` | `SELF_HOSTED_RUNNER_DRAIN_GRACE_MS` | `0` | 在运行器接收到关闭信号或达到其退休时间之前，控制运行器在其活跃会话完成后何时退出：`0` 立即退出而不轮询更多内容，正值使运行器保持活跃并首先重新轮询锁定所有者的队列那么多秒，代价是[加强部分](/docs/zh-CN/self-hosted-environments-deploy#harden-your-deployment)中描述的每个会话容器隔离。在您使用 [`--defer-shutdown-max-min`](/docs/zh-CN/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal) 推迟的第一个信号之后，运行器在不持有任何会话时立即退出，无论您在此处设置什么。 |

34| `--drain-marker-file <path>` | `SELF_HOSTED_RUNNER_DRAIN_MARKER_FILE` | 未设置 | 标记文件，您的主机写入该文件以在发送 `SIGTERM` 之前宣布优雅排空。当文件在排空开始时存在时，运行器将其退出报告给 Anthropic 作为主机排空而不是普通关闭信号。排空本身（包括 `--drain-wait-sec` 保持）的运行方式与没有标志相同。在会话无法写入的本地文件系统上命名路径。需要 Claude Code v2.1.271 或更高版本。 |

34| `--drain-wait-sec <n>` | `SELF_HOSTED_RUNNER_DRAIN_WAIT_MS` | `0` | 一旦排空开始（在 `SIGTERM` 上，除非您设置 [`--defer-shutdown-max-min`](/docs/zh-CN/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal)），等待最多 N 秒以完成每个会话的进行中的轮次和后台任务，然后终止子进程。在此等待期间，运行器将刚刚完成的后台任务计为仍在运行，直到读取其结果的后续轮次开始，最多为 [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings) 窗口。 |35| `--drain-wait-sec <n>` | `SELF_HOSTED_RUNNER_DRAIN_WAIT_MS` | `0` | 一旦排空开始（在 `SIGTERM` 上，除非您设置 [`--defer-shutdown-max-min`](/docs/zh-CN/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal)），等待最多 N 秒以完成每个会话的进行中的轮次和后台任务，然后终止子进程。在此等待期间，运行器将刚刚完成的后台任务计为仍在运行，直到读取其结果的后续轮次开始，最多为 [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings) 窗口。 |

35| `--environment-secret-file <path>` | `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` | 必需 | 包含环境密钥的文件的路径，或对于由[编排器](/docs/zh-CN/self-hosted-environments-configuration#on-demand-runners)生成的运行器，单次使用的工作订单 JWT。`SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` 直接携带密钥值，而不是文件路径。较旧的 `--pool-secret-file` 标志和 `SELF_HOSTED_RUNNER_POOL_SECRET` 变量仍然有效并向 stderr 打印弃用通知；早于 2.1.216 的预览程序运行器构建仅识别这些较旧的名称。 |36| `--environment-secret-file <path>` | `SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` | 必需 | 包含环境密钥的文件的路径，或对于由[编排器](/docs/zh-CN/self-hosted-environments-configuration#on-demand-runners)生成的运行器，单次使用的工作订单 JWT。`SELF_HOSTED_RUNNER_ENVIRONMENT_SECRET` 直接携带密钥值，而不是文件路径。较旧的 `--pool-secret-file` 标志和 `SELF_HOSTED_RUNNER_POOL_SECRET` 变量仍然有效并向 stderr 打印弃用通知；早于 2.1.216 的预览程序运行器构建仅识别这些较旧的名称。 |

39| `--git-ssh-rewrite <host>` | 无 | 未设置 | 在克隆之前将 `https://<host>/...` 源 URL 重写为 `git@<host>:...`，用于仅 SSH git 主机。可重复；仅标志。 |40| `--git-ssh-rewrite <host>` | 无 | 未设置 | 在克隆之前将 `https://<host>/...` 源 URL 重写为 `git@<host>:...`，用于仅 SSH git 主机。可重复；仅标志。 |

43| `--host-config-snapshot <mode>` | `SELF_HOSTED_RUNNER_HOST_CONFIG_SNAPSHOT` | `disk` | 运行器保持[主机配置目录](#environment-variable-only-settings)启动快照的位置，它从该快照为每个会话播种。`disk` 将快照复制到 `--base-dir` 下的运行器拥有的目录中，并在每个会话启动时，验证每个文件与内存中的摘要。如果副本中的文件已被修改，会话失败，运行器拒绝会话，直到您重新启动它。`memory` 在堆上保持整个快照，上限为 64 MiB；超过上限，会话启动时没有主机配置，并显示说明这一点的通知。当运行器无法写入磁盘快照时，它记录失败并为该运行使用 `memory`。需要 Claude Code v2.1.271 或更高版本。 |

42| `--kill-session-after-min <n>` | `SELF_HOSTED_RUNNER_MAX_LIFETIME_MS` | `0` | 将会话限制为 N 分钟的挂钟时间，作为卡住会话的安全限制。在 v2.1.260 或更高版本上，运行器释放达到限制的会话，以便它可以在其用户的下一条消息上恢复，仅当它在 [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](#environment-variable-only-settings) 宽限期结束时仍在运行器上时才终止它。在 v2.1.260 之前，运行器在限制处终止会话。请参阅[某些会话不计为空闲](/docs/zh-CN/self-hosted-environments-deploy#some-sessions-don%E2%80%99t-count-as-idle)了解详情以及如何选择值。`0` 禁用。 |44| `--kill-session-after-min <n>` | `SELF_HOSTED_RUNNER_MAX_LIFETIME_MS` | `0` | 将会话限制为 N 分钟的挂钟时间，作为卡住会话的安全限制。在 v2.1.260 或更高版本上，运行器释放达到限制的会话，以便它可以在其用户的下一条消息上恢复，仅当它在 [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](#environment-variable-only-settings) 宽限期结束时仍在运行器上时才终止它。在 v2.1.260 之前，运行器在限制处终止会话。请参阅[某些会话不计为空闲](/docs/zh-CN/self-hosted-environments-deploy#some-sessions-don%E2%80%99t-count-as-idle)了解详情以及如何选择值。`0` 禁用。 |

48| `--proxy-authorization-file <path>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_FILE` | 未设置 | 运行器为每个到您的出口代理的连接读取的文件，使用其修剪的内容作为 `Proxy-Authorization` 标头值。对另一个进程轮换到位的令牌使用此标志。与 `--proxy-authorization-command` 具有相同的要求，不能与其结合。请参阅[向出口代理进行身份验证](/docs/zh-CN/self-hosted-environments-deploy#authenticate-to-an-egress-proxy)。需要 Claude Code v2.1.238 或更高版本。 |50| `--proxy-authorization-file <path>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_FILE` | 未设置 | 运行器为每个到您的出口代理的连接读取的文件，使用其修剪的内容作为 `Proxy-Authorization` 标头值。对另一个进程轮换到位的令牌使用此标志。与 `--proxy-authorization-command` 具有相同的要求，不能与其结合。请参阅[向出口代理进行身份验证](/docs/zh-CN/self-hosted-environments-deploy#authenticate-to-an-egress-proxy)。需要 Claude Code v2.1.238 或更高版本。 |

49| `--push-outcome-on-release` | `SELF_HOSTED_RUNNER_PUSH_OUTCOME_ON_RELEASE` | 关闭 | 在运行器启动的会话结束（例如排空或空闲释放）时，在删除工作区之前将跟踪的结果分支推送到 `origin`，以便进行中的提交在重新启动后存活。尽力而为；向关闭预算添加 30 秒，需要 git 2.29 或更高版本以从推送的分支恢复。在启用之前限制对 `claude/*` refs 的推送访问；请参阅[恢复的会话丢失未推送的工作](/docs/zh-CN/self-hosted-environments-deploy#additional-limitations)。通过 `checkout` 生命周期钩子检出的存储库不会被推送；改为从 [`post-session` 钩子](/docs/zh-CN/self-hosted-environments-configuration#post-session)快照这些。 |51| `--push-outcome-on-release` | `SELF_HOSTED_RUNNER_PUSH_OUTCOME_ON_RELEASE` | 关闭 | 在运行器启动的会话结束（例如排空或空闲释放）时，在删除工作区之前将跟踪的结果分支推送到 `origin`，以便进行中的提交在重新启动后存活。尽力而为；向关闭预算添加 30 秒，需要 git 2.29 或更高版本以从推送的分支恢复。在启用之前限制对 `claude/*` refs 的推送访问；请参阅[恢复的会话丢失未推送的工作](/docs/zh-CN/self-hosted-environments-deploy#additional-limitations)。通过 `checkout` 生命周期钩子检出的存储库不会被推送；改为从 [`post-session` 钩子](/docs/zh-CN/self-hosted-environments-configuration#post-session)快照这些。 |

50| `--release-idle-session-min <n>` | `SELF_HOSTED_RUNNER_SESSION_IDLE_MS` | `0` | 在轮次完成或会话等待用户操作后，在 N 分钟的不活动后释放会话槽。仍在进行中的会话（包括持有永不完成的后台任务或从运行的工具调用内部请求的批准的会话）不计为空闲；与 `--kill-session-after-min` 配对作为硬后挡。在会话的后台任务完成后，运行器认为会话繁忙，直到读取结果的后续轮次开始，最多为 [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings) 窗口。在运行器接收到关闭信号或达到其退休时间之前，留下运行器没有活跃会话的释放启动与正常排空相同的退出路径，由 `--drain-grace-sec` 管理。在您使用 [`--defer-shutdown-max-min`](/docs/zh-CN/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal) 推迟的第一个信号之后，运行器在释放使其不持有任何会话时立即退出。`0` 禁用。 |52| `--release-idle-session-min <n>` | `SELF_HOSTED_RUNNER_SESSION_IDLE_MS` | `0` | 在轮次完成或会话等待用户操作后，在 N 分钟的不活动后释放会话槽。仍在进行中的会话（包括持有永不完成的后台任务或从运行的工具调用内部请求的批准的会话）不计为空闲；与 `--kill-session-after-min` 配对作为硬后挡。在会话的后台任务完成后，运行器认为会话繁忙，直到读取结果的后续轮次开始，最多为 [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings) 窗口。在运行器接收到关闭信号或达到其退休时间之前，留下运行器没有活跃会话的释放启动与正常排空相同的退出路径，由 `--drain-grace-sec` 管理。在您使用 [`--defer-shutdown-max-min`](/docs/zh-CN/self-hosted-environments-deploy#defer-the-drain-past-the-first-signal) 推迟的第一个信号之后，运行器在释放使其不持有任何会话时立即退出。`0` 禁用。 |

53| `--remove-session-state [bool]` | `SELF_HOSTED_RUNNER_REMOVE_SESSION_STATE` | 关闭 | 当会话在此运行器上结束时，删除 `<base-dir>/_sessions/` 下的会话的每个会话目录，无论结果如何。[重用预热的检出](/docs/zh-CN/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout)描述它们保存的内容以及当它们保留时谁可以读取它们。删除是尽力而为：当运行器被杀死或在清理运行之前达到其排空截止时间时，每个会话目录保持到位。启用标志后，失败或中断的会话的调试日志不会保留在磁盘上。需要 Claude Code v2.1.268 或更高版本。 |

51| `--retire-at <epoch-seconds>` | `SELF_HOSTED_RUNNER_RETIRE_AT` | 未设置 | 在绝对 Unix 时间戳（以秒为单位）处退休运行器，用于在已知时间杀死运行器的基础设施；[运行器生命周期](/docs/zh-CN/self-hosted-environments#runner-lifecycle)描述释放序列以及如何调整边距。2001 年之前或 5138 年之后的值被标志拒绝，被环境变量忽略。 |54| `--retire-at <epoch-seconds>` | `SELF_HOSTED_RUNNER_RETIRE_AT` | 未设置 | 在绝对 Unix 时间戳（以秒为单位）处退休运行器，用于在已知时间杀死运行器的基础设施；[运行器生命周期](/docs/zh-CN/self-hosted-environments#runner-lifecycle)描述释放序列以及如何调整边距。2001 年之前或 5138 年之后的值被标志拒绝，被环境变量忽略。 |

53| `--startup-timeout-min <n>` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | 如果子进程在生成后 N 分钟内未在[活动频道](/docs/zh-CN/self-hosted-environments-configuration#keep-stdin-and-file-descriptor-3-attached)上发出初始化信号，则释放会话槽。由子进程的初始化信号清除，而不是普通输出，之后 `--release-idle-session-min` 接管。`0` 禁用。 |56| `--startup-timeout-min <n>` | `SELF_HOSTED_RUNNER_STARTUP_TIMEOUT_MS` | `15` | 如果子进程在生成后 N 分钟内未在[活动频道](/docs/zh-CN/self-hosted-environments-configuration#keep-stdin-and-file-descriptor-3-attached)上发出初始化信号，则释放会话槽。由子进程的初始化信号清除，而不是普通输出，之后 `--release-idle-session-min` 接管。`0` 禁用。 |

self-hosted-environments-testing.md +2 −2

Details

74 启动运行器之前74 启动运行器之前

75</h3>75</h3>

76 76

~~77hook 依赖的两件事：~~77hook 有以下要求：

78 78

79* 在启动运行器之前安装它。运行器在启动时对 `~/.claude/` 进行快照，因此添加到运行中的运行器的 hook 仅在重新启动后才生效。79* 在启动运行器之前安装它。运行器在启动时对 `~/.claude/` 进行快照，因此添加到运行中的运行器的 hook 仅在重新启动后才生效。

80* 将 `E2E_REPLY_DIR` 导出到运行器进程。当变量未设置或目录不存在时，hook 是无操作的，因此在启动运行器的任何地方设置它，例如 systemd 单元、pod 规范或 CI 步骤。下面的测试脚本也需要它。80* 将 `E2E_REPLY_DIR` 导出到运行器进程。当变量未设置或目录不存在时，hook 是无操作的，因此在启动运行器的任何地方设置它，例如 systemd 单元、pod 规范或 CI 步骤。下面的测试脚本也需要它。

214 临时 CI 运行器214 临时 CI 运行器

215</h3>215</h3>

216 216

217目前没有针对此的长期 CI 令牌。授予远程会话控制的范围 `user:sessions:claude_code` 在服务器端限制为 30 天，因此 `claude setup-token`（它铸造一年推理令牌）不涵盖它。[环境秘密](/docs/zh-CN/self-hosted-environments-quickstart#set-up-an-environment-and-runner)也不被接受，因为它仅授权运行器向环境注册，而不是创建会话。217目前没有针对此的长期 CI 令牌。授予云会话控制的范围 `user:sessions:claude_code` 在服务器端限制为 30 天，因此 `claude setup-token`（它铸造一年推理令牌）不涵盖它。[环境秘密](/docs/zh-CN/self-hosted-environments-quickstart#set-up-an-environment-and-runner)也不被接受，因为它仅授权运行器向环境注册，而不是创建会话。

218 218

219要在临时运行器上配置存储的登录，请设置 [`CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 和 `CLAUDE_CODE_OAUTH_SCOPES`](/docs/zh-CN/env-vars#variables)，以便 `claude auth login` 交换令牌而不需要浏览器；相同的 30 天上限适用于刷新授予。如果您需要不受人类帐户约束的机器身份路径，请联系您的 Anthropic 帐户团队。219要在临时运行器上配置存储的登录，请设置 [`CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 和 `CLAUDE_CODE_OAUTH_SCOPES`](/docs/zh-CN/env-vars#variables)，以便 `claude auth login` 交换令牌而不需要浏览器；相同的 30 天上限适用于刷新授予。如果您需要不受人类帐户约束的机器身份路径，请联系您的 Anthropic 帐户团队。

220 220

server-managed-settings.md +3 −1

Details

165 165

166三种类型的键是无合并规则的例外：166三种类型的键是无合并规则的例外：

167 167

168* **跨源锁定键**：一小组键，例如沙箱允许列表锁，[列在托管设置页面上](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)。当任何管理员控制的托管源设置它们时，Claude Code 会遵守它们；用户可写的 HKCU 注册表层被排除。当 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 提供托管设置时，其输出是这些检查读取的唯一源，除了 [`forceRemoteSettingsRefresh`](/docs/zh-CN/settings-reference#forceremotesettingsrefresh)，Claude Code 在启动时直接从管理员源读取它。168* **跨源锁定键**：一小组键，例如沙箱允许列表锁，[列在托管设置页面上](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)。当任何管理员控制的托管源设置它们时，Claude Code 会遵守它们；用户可写的 HKCU 注册表层被排除。

169

170 当 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper) 提供托管设置时，其输出是这些检查读取的唯一源，除了 [`forceRemoteSettingsRefresh`](/docs/zh-CN/settings-reference#forceremotesettingsrefresh)，Claude Code 在启动时直接从管理员源读取它。

169* **`env` 块**：除了与凭证键配对的遥测单元和路由变量（下面涵盖）外，它在管理员控制的源之间按键合并。对于每个环境变量，定义它的最高优先级源获胜，较低的管理员源填充较高源未设置的变量。因此，端点管理的 `env` 条目在服务器管理的配置未设置该变量时应用，或在该变量的缓存服务器值[等待服务器确认而被暂扣](#fetch-and-caching-behavior)期间应用。需要 Claude Code v2.1.223 或更高版本。在 v2.1.223 之前，Claude Code 仅应用选定源的整个 `env` 块。171* **`env` 块**：除了与凭证键配对的遥测单元和路由变量（下面涵盖）外，它在管理员控制的源之间按键合并。对于每个环境变量，定义它的最高优先级源获胜，较低的管理员源填充较高源未设置的变量。因此，端点管理的 `env` 条目在服务器管理的配置未设置该变量时应用，或在该变量的缓存服务器值[等待服务器确认而被暂扣](#fetch-and-caching-behavior)期间应用。需要 Claude Code v2.1.223 或更高版本。在 v2.1.223 之前，Claude Code 仅应用选定源的整个 `env` 块。

170 * **遥测单元**：`OTEL_EXPORTER_OTLP_*` 导出器键、`OTEL_LOG_*` 内容捕获切换、`OTEL_LOGS_EXPORTER` 以及测试版跟踪变量 `ENABLE_BETA_TRACING_DETAILED` 和 `BETA_TRACING_ENDPOINT` 遵循设置其中任何一个的最高源作为一个单元。传递 `otelHeadersHelper` 凭证键的源也声称该单元，但仅在它是选定源时才放置这些变量：未被选定但传递该键的源不贡献其中任何一个，仍然阻止较低源填充它们。无论哪种方式，来自一个源的导出器端点永远不能与来自另一个源的凭证配对。172 * **遥测单元**：`OTEL_EXPORTER_OTLP_*` 导出器键、`OTEL_LOG_*` 内容捕获切换、`OTEL_LOGS_EXPORTER` 以及测试版跟踪变量 `ENABLE_BETA_TRACING_DETAILED` 和 `BETA_TRACING_ENDPOINT` 遵循设置其中任何一个的最高源作为一个单元。传递 `otelHeadersHelper` 凭证键的源也声称该单元，但仅在它是选定源时才放置这些变量：未被选定但传递该键的源不贡献其中任何一个，仍然阻止较低源填充它们。无论哪种方式，来自一个源的导出器端点永远不能与来自另一个源的凭证配对。

171 * **凭证配对的路由**：将路由变量与选定源专用凭证键（例如 `apiKeyHelper` 或 `otelHeadersHelper`）配对的源仅在它赢得该槽位时贡献这些路由变量。173 * **凭证配对的路由**：将路由变量与选定源专用凭证键（例如 `apiKeyHelper` 或 `otelHeadersHelper`）配对的源仅在它赢得该槽位时贡献这些路由变量。

settings.md +36 −35

Details

400 设置文件及其影响范围400 设置文件及其影响范围

401</h2>401</h2>

402 402

403Claude Code 从四个文件读取设置，组织也可以从 claude.ai 控制台提供托管设置。每个来源都有一个范围：设置应用的人员和项目集合，可能是仅你、项目中的所有人或组织中的所有人。403Claude Code 从四个文件读取设置，组织也可以从 claude.ai 控制台提供托管设置。每个来源都有一个作用域：设置应用的人员和项目范围，可能是仅限于你、项目中的所有人，或组织中的所有人。

404 404

405| 范围 | 文件 | 影响对象 | 用途 |405| 作用域 | 文件 | 影响范围 | 用途 |

406| :--- | :----------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | :-------------------------- |406| :--- | :----------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- | :---------------------------- |

411 411

412在"文件"列中，`~/.claude` 是你主目录中的 `.claude` 文件夹，而单独的 `.claude` 是项目内的 `.claude` 文件夹。412在"文件"列中，`~/.claude` 是你主目录中的 `.claude` 文件夹，而单独的 `.claude` 是项目内的 `.claude` 文件夹。

416<span id="compare-what-each-file-reaches" />416<span id="compare-what-each-file-reaches" />

417 417

418<h3 id="compare-the-scope-of-each-settings-file">418<h3 id="compare-the-scope-of-each-settings-file">

419 比较每个设置文件的范围419 比较每个设置文件的作用域

420</h3>420</h3>

421 421

422假设你的机器上有三个项目 `website/`、`api/` 和 `acme-app/`，一个队友有他们自己的 `acme-app/` 克隆，你在 `acme-app/` 上启动了一个[云会话](#settings-in-cloud-sessions)。422假设你在机器上有三个项目：`website/`、`api/` 和 `acme-app/`，一个队友有他们自己的 `acme-app/` 克隆，你在 `acme-app/` 上启动了一个[云会话](#settings-in-cloud-sessions)。

423 423

424下面的图表显示当你从这些文件夹启动 Claude Code 时，设置应用在哪些文件夹中。点击一个设置文件以查看它到达的文件夹。424下面的图表显示当你从这些文件夹启动 Claude Code 时，设置应用在哪些文件夹中。点击一个设置文件查看它到达的文件夹。

425 425

426<SettingsScope />426<SettingsScope />

427 427

428* **`~/.claude/settings.json`**：你机器上的每个项目，以及队友或云会话中的任何内容都不会428* **`~/.claude/settings.json`**：你机器上的每个项目，以及队友机器上或云会话中都没有

429* **`acme-app/.claude/settings.json`**：你的 `acme-app/`。只有当你将文件提交到版本控制时，它才会到达你队友的克隆和云会话；在此之前，它就像任何其他文件一样在你的磁盘上，没有人有它429* **`acme-app/.claude/settings.json`**：你的 `acme-app/`。只有当你将文件提交到版本控制时，它才会到达你队友的克隆和云会话；在此之前，它就像任何其他磁盘上的文件一样，其他人没有它

430* **`acme-app/.claude/settings.local.json`**：仅你的 `acme-app/`。Claude Code 第一次写入文件时将其添加到你的全局 git 排除项，所以它不会进入你的提交；如果你手动创建文件，[自己将其添加到 `.gitignore`](#keep-personal-settings-out-of-a-repository)430* **`acme-app/.claude/settings.local.json`**：仅你的 `acme-app/`。Claude Code 第一次写入文件时将其添加到你的全局 git 排除项中，因此它不会进入你的提交；如果你手动创建文件，[自己添加到 `.gitignore`](#keep-personal-settings-out-of-a-repository)

431* **托管设置**，无论是 `managed-settings.json` 文件、MDM 策略还是来自 claude.ai 控制台的[服务器托管设置](/docs/zh-CN/server-managed-settings)：你的组织部署到的每台机器上的每个项目，或你使用组织账户登录的地方。只有服务器托管设置才能到达云会话431* **托管设置**，无论是 `managed-settings.json` 文件、MDM 策略，还是来自 claude.ai 控制台的[服务器托管设置](/docs/zh-CN/server-managed-settings)：你的组织部署到的每台机器上的每个项目，或你使用组织账户登录的地方。只有服务器托管设置到达云会话

432 432

433<span id="which-files-you-have" />433<span id="which-files-you-have" />

434 434

439安装 Claude Code 不会创建任何设置文件。如果你的机器或项目已经有一个，它来自以下来源之一：439安装 Claude Code 不会创建任何设置文件。如果你的机器或项目已经有一个，它来自以下来源之一：

440 440

441* **托管**：你的组织部署它。你不创建或编辑它。441* **托管**：你的组织部署它。你不创建或编辑它。

442* **共享项目**：已经使用 Claude Code 的项目可能有一个已提交。如果没有，在项目文件夹中的 `.claude/settings.json` 处创建它。442* **共享项目**：已经使用 Claude Code 的项目可能已提交一个。如果没有，在项目文件夹中的 `.claude/settings.json` 创建一个。

443* **用户**和**项目本地**：自己创建它们，或让 Claude Code 创建它们。当你在 `/config` 菜单中更改存储在用户设置中的选项（如主题）时，它会写入 `~/.claude/settings.json`，当你在权限提示上给予常设批准时（如对 Bash 命令的"是的，不要再问"），它会写入 `.claude/settings.local.json`。一些 `/config` 选项，包括**显示提示**，保存到 `.claude/settings.local.json` 而不是用户文件。443* **用户**和**项目本地**：自己创建它们，或让 Claude Code 创建它们。当你在 `/config` 菜单中更改存储在用户设置中的选项（如主题）时，它会写入 `~/.claude/settings.json`，当你在权限提示上给予常设批准（如对 Bash 命令的"是的，不要再问"）时，它会写入 `.claude/settings.local.json`。一些 `/config` 选项，包括**显示提示**，保存到 `.claude/settings.local.json` 而不是用户文件。

444 444

445<Info>445<Info>

446 在 Windows 上，`~/.claude` 表示 `%USERPROFILE%\.claude`。要将主目录文件保存在其他地方，设置 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars)；Claude Code 然后将你的设置、会话历史和插件存储在那里。446 在 Windows 上，`~/.claude` 表示 `%USERPROFILE%\.claude`。要将主目录文件保存在其他地方，设置 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars)；Claude Code 然后将你的设置、会话历史和 plugins 存储在那里。

447</Info>447</Info>

448 448

449Claude Code 还保留第五个文件 [`~/.claude.json`](/docs/zh-CN/claude-directory#ce-claude-json)，它为自己写入；你不需要编辑它。它保存你的登录会话、[MCP 服务器](/docs/zh-CN/mcp)配置、每个项目的状态（如信任决定）和 `/config` 为你写入的[全局配置键](/docs/zh-CN/settings-reference#global-config-settings)。449Claude Code 还保留第五个文件 [`~/.claude.json`](/docs/zh-CN/claude-directory#ce-claude-json)，它为自己写入；你不需要编辑它。它保存你的登录会话、[MCP server](/docs/zh-CN/mcp) 配置、每个项目的状态（如信任决定），以及 `/config` 为你写入的[全局配置键](/docs/zh-CN/settings-reference#global-config-settings)。

450 450

451<h3 id="share-settings-with-your-team">451<h3 id="share-settings-with-your-team">

452 与你的团队共享设置452 与你的团队共享设置

453</h3>453</h3>

454 454

455提交 `.claude/settings.json` 以便克隆仓库的每个人都获得相同的权限、hooks、遥测和插件。每个队友仍然可以在他们自己的 `.claude/settings.local.json` 中为自己覆盖它，所以个人例外不需要提交。有关完整的团队文件，请参阅[团队的共享设置](/docs/zh-CN/settings-example#a-teams-shared-settings)。455提交 `.claude/settings.json` 以便克隆仓库的每个人都获得相同的权限、hooks、遥测和 plugins。每个队友仍然可以在他们自己的 `.claude/settings.local.json` 中为自己覆盖它，因此个人例外不需要提交。有关完整的团队文件，请参阅[团队的共享设置](/docs/zh-CN/settings-example#a-teams-shared-settings)。

456 456

457你提交的一些内容等待每个队友[信任文件夹](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)，少数键永远不会从仓库文件生效；[排查不适用的设置](#common-cases)涵盖两者。457你提交的一些内容等待每个队友[信任文件夹](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)，少数键永远不会从仓库文件生效；[排查不适用的设置](#common-cases)涵盖两者。

458 458

468 将个人设置保留在仓库之外468 将个人设置保留在仓库之外

469</h3>469</h3>

470 470

471要在一个项目中为自己更改设置而不为队友更改它，将其保存在项目内的 `.claude/settings.local.json` 中。Claude Code 在提交的 `.claude/settings.json` 上应用该文件，所以如果你的团队文件设置 `"model": "claude-sonnet-5"` 而你想要 Opus，在你的本地文件中放入 `"model": "claude-opus-4-8"`，只有你的会话会改变。471要在一个项目中为自己更改设置而不为队友更改，请在项目内的 `.claude/settings.local.json` 中保存它。Claude Code 在提交的 `.claude/settings.json` 上应用该文件，因此如果你的团队文件设置 `"model": "claude-sonnet-5"` 而你想要 Opus，在你的本地文件中放入 `"model": "claude-opus-4-8"`，只有你的会话会改变。

472 472

473关于本地文件有三件事要知道：473Claude Code 也会写入此文件，将其保留在你的提交之外，并应用其允许规则而无需信任步骤：

474 474

475* **Claude Code 也写入它。** 当 Claude 要求权限运行 Bash 命令而你选择"是的，不要再问"时，Claude Code 将该[权限批准](/docs/zh-CN/permissions#permission-system)保存为 `allow` 规则。475* **Claude Code 也会写入它。** 当 Claude 要求运行 Bash 命令的权限，你选择"是的，不要再问"时，Claude Code 将该[权限批准](/docs/zh-CN/permissions#permission-system)保存为此处的 `allow` 规则。

476* **你不需要自己 gitignore 它，除非你手动创建了它。** Claude Code 第一次在不已经忽略它的 git 仓库中写入文件时，它将 `**/.claude/settings.local.json` 添加到你的全局 git 排除文件，所以该文件在每个仓库中都不会进入你的提交。该文件是 `core.excludesFile`，当你的全局 git 配置将其设置为绝对路径或 `~` 前缀路径时；否则它是 `$XDG_CONFIG_HOME/git/ignore`，或当 `XDG_CONFIG_HOME` 未设置时是 `~/.config/git/ignore`。如果你手动创建了文件而 Claude Code 还没有写入它，自己将其添加到 `.gitignore`。476* **除非你手动创建，否则你不需要 gitignore 它。** Claude Code 第一次在不已忽略它的 git 仓库中写入文件时，它会将 `**/.claude/settings.local.json` 添加到你的全局 git 排除文件中，因此该文件在每个仓库中都不会进入你的提交。该文件是 `core.excludesFile`（当你的全局 git 配置将其设置为绝对路径或 `~` 前缀路径时）；否则是 `$XDG_CONFIG_HOME/git/ignore`，或当 `XDG_CONFIG_HOME` 未设置时是 `~/.config/git/ignore`。如果你手动创建了文件，Claude Code 还没有写入它，请自己添加到 `.gitignore`。

477* **其 allow 规则在文件保持未跟踪时不等待信任。** 因为文件是你的而不是仓库的，Claude Code 应用其 `allow` 规则而不需要它对提交文件要求的[工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)步骤。如果文件由 git 跟踪，信任步骤也适用于它；请参阅[当你的本地设置文件需要信任](/docs/zh-CN/permissions#when-your-local-settings-file-needs-trust)。477* **当文件保持未跟踪时，其允许规则不等待信任。** 因为文件是你的而不是仓库的，Claude Code 应用其 `allow` 规则而无需它对提交文件要求的[工作区信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)步骤。如果文件被 git 跟踪，信任步骤也适用于它；请参阅[当你的本地设置文件需要信任](/docs/zh-CN/permissions#when-your-local-settings-file-needs-trust)。

478 478

479<span id="where-claude-code-looks-for-each-file" />479<span id="where-claude-code-looks-for-each-file" />

480 480

486 Claude Code 在 git 仓库中保留本地文件的位置486 Claude Code 在 git 仓库中保留本地文件的位置

487</h4>487</h4>

488 488

489当 Claude 要求权限运行 Bash 命令而你选择"是的，不要再问"时，Claude Code 将该批准保存为 `.claude/settings.local.json` 中的 `allow` 规则。如果你在 git 仓库的子目录中启动 Claude Code，它在仓库根目录读取和写入该文件，并在整个仓库中应用批准。在[工作树](/docs/zh-CN/worktrees)中，它使用主检出根目录处的文件。489当 Claude 要求运行 Bash 命令的权限，你选择"是的，不要再问"时，Claude Code 将该批准保存为 `.claude/settings.local.json` 中的 `allow` 规则。如果你在 git 仓库的子目录中启动 Claude Code，它会在仓库根目录读取和写入该文件，并在整个仓库中应用批准。在[worktree](/docs/zh-CN/worktrees) 中，它使用主检出根目录处的文件。

490 490

491两条规则限定根位置：491两条规则限定根位置：

492 492

493* **当文件与 `.claude/settings.json` 保持在一起时**：在 git 仓库外，当仓库根是你的主目录时，在 Windows 上，或当仓库根或其 `.git` 或 `.claude` 条目不由你的用户拥有时。493* **当文件与 `.claude/settings.json` 保持在一起时**：在 git 仓库之外，当仓库根是你的主目录时，在 Windows 上，或当仓库根或其 `.git` 或 `.claude` 条目不由你的用户拥有时。

494* **文件中的路径不在仓库根处锚定**：以 `/` 开头的权限规则或相对沙箱路径[在会话的主工作目录处锚定](/docs/zh-CN/permissions#read-and-edit)。494* **文件中的路径不在仓库根处锚定**：以 `/` 开头的权限规则或相对沙箱路径[在会话的主工作目录处锚定](/docs/zh-CN/permissions#read-and-edit)。

495 495

496在 v2.1.211 之前，Claude Code 在启动目录中保留文件。它仍然读取早期版本在根文件旁边留下的文件；当两者都设置相同的键时，根的值适用，两个文件的权限规则都适用。Agent SDK 的 [`resolveSettings()`](/docs/zh-CN/agent-sdk/typescript#resolvesettings) 助手总是从启动目录读取文件。496在 v2.1.211 之前，Claude Code 将文件保留在启动目录中。它仍然读取早期版本在根文件旁边留下的文件；当两者设置相同的键时，根的值适用，两个文件的权限规则都适用。Agent SDK 的 [`resolveSettings()`](/docs/zh-CN/agent-sdk/typescript#resolvesettings) 助手始终从启动目录读取文件。

497 497

498Claude Code 从会话的[主工作目录](/docs/zh-CN/permissions#working-directories)读取共享的 `.claude/settings.json`，所以要使用在仓库根处提交的文件，在那里启动 Claude Code。在你[使用 `/cd` 移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory)后，Claude Code 改为从新目录读取两个项目文件，按相同规则放置本地文件。从你移动到的目录读取它们需要 Claude Code v2.1.246 或更高版本。498Claude Code 从会话的[主工作目录](/docs/zh-CN/permissions#working-directories)读取共享的 `.claude/settings.json`，因此要使用在仓库根处提交的文件，请从那里启动 Claude Code。在你[使用 `/cd` 移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory)后，Claude Code 改为从新目录读取两个项目文件，按相同规则放置本地文件。从你移动到的目录读取它们需要 Claude Code v2.1.246 或更高版本。

499 499

500<span id="managed-settings-delivery" />500<span id="managed-settings-delivery" />

501 501

515 515

516托管设置通过托管设置页面上的[交付机制](/docs/zh-CN/managed-settings#delivery-mechanisms)到达你，最常见的是：516托管设置通过托管设置页面上的[交付机制](/docs/zh-CN/managed-settings#delivery-mechanisms)到达你，最常见的是：

517 517

518* [服务器托管设置](/docs/zh-CN/server-managed-settings)，Claude Code 从 claude.ai 管理控制台或自托管的[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)获取518* [服务器托管设置](/docs/zh-CN/server-managed-settings)，Claude Code 从 claude.ai 管理控制台或自托管的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 获取

519* MDM 或操作系统级别的策略，以及系统目录中的 `managed-settings.json` 文件519* MDM 或操作系统级别的策略，以及系统目录中的 `managed-settings.json` 文件

520* 嵌入主机（如 Claude Desktop），通过 SDK `managedSettings` 选项；请参阅[从嵌入主机控制策略](/docs/zh-CN/managed-settings#parent-settings-from-embedding-hosts)520* 嵌入主机（如 Claude Desktop），通过 SDK `managedSettings` 选项；请参阅[从嵌入主机控制策略](/docs/zh-CN/managed-settings#parent-settings-from-embedding-hosts)

521 521

522在在 Claude Desktop 应用中在你的机器上运行的 [Cowork](https://claude.com/docs/cowork/overview) 会话中，Claude Code 不从 claude.ai 管理控制台获取服务器托管设置，它读取部署到你的设备的策略，除非你的组织的 Claude Desktop 配置设置 `requireCoworkFullVmSandbox`。[策略应用的位置和时间](/docs/zh-CN/managed-settings#where-and-when-a-policy-applies)涵盖 Cowork 和云会话。522在在 Claude Desktop 应用中在你的机器上运行的 [Cowork](https://claude.com/docs/cowork/overview) 会话中，Claude Code 不会从 claude.ai 管理控制台获取服务器托管设置，它读取部署到你的设备的策略，除非你的组织的 Claude Desktop 配置设置 `requireCoworkFullVmSandbox`。[策略应用的位置和时间](/docs/zh-CN/managed-settings#where-and-when-a-policy-applies)涵盖 Cowork 和云会话。

523 523

524如果你是管理员，[为你的组织设置 Claude Code](/docs/zh-CN/admin-setup) 会指导你选择要强制执行的内容，[部署托管设置](/docs/zh-CN/managed-settings)涵盖交付以及如何确认策略生效。524如果你是管理员，[为你的组织设置 Claude Code](/docs/zh-CN/admin-setup) 介绍了选择要强制执行的内容，[部署托管设置](/docs/zh-CN/managed-settings)涵盖交付以及如何确认策略生效。

525 525

526<h2 id="change-a-setting">526<h2 id="change-a-setting">

527 更改设置527 更改设置

765 765

766两件事阻止 `.claude/settings.json` 中的键为克隆它的每个人应用：766两件事阻止 `.claude/settings.json` 中的键为克隆它的每个人应用：

767 767

768* **Claude Code 忽略存储库文件中的键。** 在[设置索引](/docs/zh-CN/settings-reference#settings-index)的作用域列中查找 `User, local, or managed`、`User or managed`、`Managed` 或 `Global config`；这些键永远不会从共享文件应用，除了 [`autoContinueAtUsageLimit`](/docs/zh-CN/settings-reference#autocontinueatusagelimit)，存储库文件仍然可以关闭：当文件设置键而没有用户、`--settings` 或托管值时，Claude Code 读取设置为关闭。`Global config` 键仅从 `~/.claude.json` 应用。768* **Claude Code 忽略存储库文件中的键。** 在[设置索引](/docs/zh-CN/settings-reference#settings-index)的作用域列中查找 `User, local, or managed`、`User or managed`、`Managed` 或 `Global config`。这些键永远不会从共享文件应用，除了少数几个存储库文件仍然可以关闭的。每个这些条目在其作用域行上说明。`Global config` 键仅从 `~/.claude.json` 应用。

769* **键等待信任。** `permissions.allow` 规则、`permissions.additionalDirectories`、`extraKnownMarketplaces` 和大多数 [`env`](/docs/zh-CN/settings-reference#env) 值仅在每个队友[信任文件夹](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)后应用。在那之前他们仍然看到提示并不从文件声明的市场获得插件。`deny` 和 `ask` 规则立即应用。769* **键等待信任。** `permissions.allow` 规则、`permissions.additionalDirectories`、`extraKnownMarketplaces` 和大多数 [`env`](/docs/zh-CN/settings-reference#env) 值仅在每个队友[信任文件夹](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)后应用。在那之前他们仍然看到提示并不从文件声明的市场获得插件。`deny` 和 `ask` 规则立即应用。

770 770

771<h4 id="permission-rules-combine-differently-than-you-expected">771<h4 id="permission-rules-combine-differently-than-you-expected">

792| [`crossSessionInbound`](/docs/zh-CN/settings-reference#crosssessioninbound) | 来自 `.claude/settings.json` 或 `.claude/settings.local.json` 的更严格值，在 `accept` \< `hold` \< `refuse` 梯形上 | 在托管、`--settings` 和用户值上被尊重；不是更严格的项目或本地值被忽略 |792| [`crossSessionInbound`](/docs/zh-CN/settings-reference#crosssessioninbound) | 来自 `.claude/settings.json` 或 `.claude/settings.local.json` 的更严格值，在 `accept` \< `hold` \< `refuse` 梯形上 | 在托管、`--settings` 和用户值上被尊重；不是更严格的项目或本地值被忽略 |

793| [`useAutoModeDuringPlan`](/docs/zh-CN/settings-reference#useautomodeduringplan) | 来自任何托管来源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使获胜的托管来源设置 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |793| [`useAutoModeDuringPlan`](/docs/zh-CN/settings-reference#useautomodeduringplan) | 来自任何托管来源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使获胜的托管来源设置 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |

794| [`syncClaudeAiSkills`](/docs/zh-CN/settings-reference#syncclaudeaiskills) | 来自任何托管来源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使获胜的托管来源设置 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |794| [`syncClaudeAiSkills`](/docs/zh-CN/settings-reference#syncclaudeaiskills) | 来自任何托管来源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使获胜的托管来源设置 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |

795| [`syncClaudeAiPlugins`](/docs/zh-CN/settings-reference#syncclaudeaiplugins) | 来自任何托管来源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 的 `false` | 即使获胜的托管来源设置 `true` 也被尊重；`.claude/settings.json` 中的 `false` 被忽略 |

795| [`maxEffortLevel`](/docs/zh-CN/settings-reference#maxeffortlevel) | 来自任何作用域（包括 `--settings`）的较低上限 | 即使 Claude Code 应用的托管设置设置更高的上限也被尊重；最低的上限适用。需要 Claude Code v2.1.267 或更高版本 |796| [`maxEffortLevel`](/docs/zh-CN/settings-reference#maxeffortlevel) | 来自任何作用域（包括 `--settings`）的较低上限 | 即使 Claude Code 应用的托管设置设置更高的上限也被尊重；最低的上限适用。需要 Claude Code v2.1.267 或更高版本 |

796 797

797运行 Claude Code 的应用并设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 也是例外。Claude Code 从该应用的模型配置优先于来自每个托管来源的 `model`、`fallbackModel`、`modelPicker` 和 `modelOverrides` 键，以及托管 `env` 块中的模型选择变量，如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列。Claude Code 保持托管 [`availableModels`](/docs/zh-CN/settings-reference#availablemodels) 允许列表生效，除非应用提供自己的。798运行 Claude Code 的应用并设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 也是例外。Claude Code 从该应用的模型配置优先于来自每个托管来源的 `model`、`fallbackModel`、`modelPicker` 和 `modelOverrides` 键，以及托管 `env` 块中的模型选择变量，如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列。Claude Code 保持托管 [`availableModels`](/docs/zh-CN/settings-reference#availablemodels) 允许列表生效，除非应用提供自己的。

800 云会话中的设置801 云会话中的设置

801</h2>802</h2>

802 803

803云会话，在 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 或从 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-web)，在[云环境](/docs/zh-CN/cloud-environments)中运行在您的存储库的新克隆上，而不是在您的机器上。这改变了哪些设置到达它：804[云会话](/docs/zh-CN/claude-code-on-the-web)在[云环境](/docs/zh-CN/cloud-environments)中运行在您的存储库的新克隆上，而不是在您的机器上。这改变了哪些设置到达它：

804 805

805* **共享项目设置** (`.claude/settings.json`)：读取，因为文件是克隆的一部分。在那里提交设置以在云会话中应用它。806* **共享项目设置** (`.claude/settings.json`)：在一个存储库的会话中读取，因为该文件是克隆的一部分，会话在其中启动。在那里提交设置以在这些会话中应用它。具有多个存储库的会话在克隆上方启动，因此从每个存储库的 `.claude/settings.json` 它仅加载该文件声明的插件和市场，而不是权限规则、hooks、`env` 或其他键；请参阅[从您的设置中携带什么](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)。

806* **用户和项目本地设置** (`~/.claude/settings.json` 和 `.claude/settings.local.json`)：不读取。两者都保持在您的机器上，本地文件不在克隆中。807* **用户和项目本地设置** (`~/.claude/settings.json` 和 `.claude/settings.local.json`)：不读取。两者都保持在您的机器上，本地文件不在克隆中。

807* **托管设置**：仅[服务器管理设置](/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)说该文件何时适用。808* **托管设置**：仅[服务器管理设置](/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)说该文件何时适用。

808* **`/config`**：在网络上，打开您的 claude.ai 设置的 Claude Code 部分而不是更改值。要为云会话更改设置，在环境上设置[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)或将键提交到存储库的 `.claude/settings.json`。809* **`/config`**：在您的浏览器中的 claude.ai/code，打开您的 claude.ai 设置的 Claude Code 部分而不是更改值。要为云会话更改设置，在环境上设置[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)，或在具有一个存储库的会话中，将键提交到该存储库的 `.claude/settings.json`。

809 810

810[从您的设置中携带什么](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)列出其余的：`CLAUDE.md`、skills、MCP 服务器、插件和凭证。811[从您的设置中携带什么](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)列出其余的：`CLAUDE.md`、skills、MCP 服务器、plugins 和凭证。

811 812

812<h2 id="what’s-next">813<h2 id="what’s-next">

813 接下来是什么814 接下来是什么

settings-reference.md +105 −29

Details

1152* **类型**: 具有可选 `multiplier` 和可选 `overrides` 映射的对象1155* **类型**: 具有可选 `multiplier` 和可选 `overrides` 映射的对象

1153* **默认值**: 未设置，因此 Claude Code 报告列表价格，除非主机应用程序提供表1156* **默认值**: 未设置，因此 Claude Code 报告列表价格，除非主机应用程序提供表

1154 1157

1155此示例为 Sonnet 4.6 设置合同费率，然后将每个数字减少 15%，包括 Sonnet 行。单独设置 `multiplier` 以获得统一折扣，单独设置 `overrides` 以获得每模型费率，或两者：1158单独设置 `multiplier` 以获得统一折扣或加价，单独设置 `overrides` 以获得每模型费率，或两者。

1159

1160此示例为 Sonnet 4.6 设置合同费率，然后将每个数字减少 15%，包括 Sonnet 行：

1156 1161

1157```json managed-settings.json theme={null}1162```json managed-settings.json theme={null}

1158{1163{

1170}1175}

1171```1176```

1172 1177

1178将 `multiplier` 设置为 1 以上，最多 10，以标记每个数字。加价需要 Claude Code v2.1.271 或更高版本。早期版本忽略 `multiplier` 大于 1 的警告，并保留设置的其余部分。

1179

1173有关步骤，包括如何确认费率有效，请参阅[按您的合同费率报告支出](/docs/zh-CN/costs#report-spend-at-your-contracted-rates)。1180有关步骤，包括如何确认费率有效，请参阅[按您的合同费率报告支出](/docs/zh-CN/costs#report-spend-at-your-contracted-rates)。

1174 1181

1175<span id="modelpricing-multiplier" />1182<span id="modelpricing-multiplier" />

1182 1189

1183| 字段 | 类型 | 它做什么 |1190| 字段 | 类型 | 它做什么 |

1184| :----------- | :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |1191| :----------- | :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |

1186| `overrides` | 模型 ID 到具有 `input`、`output`、`cacheRead` 和 `cacheWrite` 的费率对象的映射，每个 0 到 10000 | 该模型的美元每百万令牌费率，全部四个必需。`cacheWrite` 涵盖五分钟和一小时缓存写入。请参阅[`modelPricing` 行适用于哪些模型](#which-models-a-modelpricing-row-applies-to) |1193| `overrides` | 模型 ID 到具有 `input`、`output`、`cacheRead` 和 `cacheWrite` 的费率对象的映射，每个 0 到 10000 | 该模型的美元每百万令牌费率，全部四个必需。`cacheWrite` 涵盖五分钟和一小时缓存写入。请参阅[`modelPricing` 行适用于哪些模型](#which-models-a-modelpricing-row-applies-to) |

1187 1194

1188Claude 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)。1195Claude 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)。

1369 1376

1370使托管设置成为权限规则的唯一设置源。Claude Code 随后会忽略用户、项目、本地和 `--settings` 文件中的 `allow`、`ask` 和 `deny` 规则，忽略 `--allowedTools`，隐藏权限提示中的始终允许选项，并停止保存新规则。1377使托管设置成为权限规则的唯一设置源。Claude Code 随后会忽略用户、项目、本地和 `--settings` 文件中的 `allow`、`ask` 和 `deny` 规则，忽略 `--allowedTools`，隐藏权限提示中的始终允许选项，并停止保存新规则。

1371 1378

1372当[来自嵌入主机的父设置](/docs/zh-CN/managed-settings#let-an-embedding-host-add-policy)适用时，Claude Code 将其视为托管层的一部分：它保留其 `deny` 和 `ask` 规则，并删除其 `allow` 规则和 `additionalDirectories`。1379当[来自嵌入主机的父设置](/docs/zh-CN/managed-settings#let-an-embedding-host-add-policy)适用时，Claude Code 将其视为托管层的一部分。它删除其 `allow` 规则和 `additionalDirectories`，并保留其 `deny` 和 `ask` 规则，除了 `Read` 和 `Edit` 规则，其模式以 `!` 开头。主机无法使用 `!` 规则从托管规则中切割出路径，无论您是否设置此键。

1373 1380

1374`--disallowedTools` 规则和当前会话的 `deny` 和 `ask` 规则仍然适用，包括在 Claude Code 在会话中途重新加载设置后。它们仅限制，因此无法扩展托管规则授予的权限。在 v2.1.257 之前，Claude Code 在第一次设置重新加载时删除了这些命令行和会话规则。1381`--disallowedTools` 规则和当前会话的 `deny` 和 `ask` 规则仍然适用，包括在 Claude Code 在会话中途重新加载设置后。它们仅限制，因此无法扩展托管规则授予的权限。在 v2.1.257 之前，Claude Code 在第一次设置重新加载时删除了这些命令行和会话规则。

1375 1382

1383有关 `!` 模式在 `--disallowedTools` 或会话规则中可以切割出什么，请参阅[Read 和 Edit 规则](/docs/zh-CN/permissions#read-and-edit)。

1384

1376* **作用域**: [`Managed`](#scopes)1385* **作用域**: [`Managed`](#scopes)

1377* **类型**: 布尔值1386* **类型**: 布尔值

1378 * `true`：托管设置成为权限规则的唯一设置源1387 * `true`：托管设置成为权限规则的唯一设置源

1413 `autoMode.classifyAllShell`1422 `autoMode.classifyAllShell`

1414</h3>1423</h3>

1415 1424

1416在自动模式处于活动状态时，通过自动模式分类器发送每个 Bash 和 PowerShell 命令。默认情况下，自动模式仅暂停可能运行任意代码的允许规则：工具范围和通配符规则（如 `Bash(*)`）以及解释器或 shell 包装器前缀（如 `Bash(python *)`）。任何其他允许规则匹配的命令（如 `Bash(npm test)`）会跳过分类器，规则的前缀未预期的破坏性参数可能会被看不见地通过。设置此键会为会话暂停每个 shell 允许规则，以便分类器看到每个命令。需要 Claude Code v2.1.193 或更高版本。1425在自动模式处于活动状态时，通过自动模式分类器发送每个 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 或更高版本。

1417 1426

1418* **作用域**: [`User or managed`](#scopes)。在读取 [`autoMode`](#automode) 的任何地方读取。1427* **作用域**: [`User or managed`](#scopes)。在读取 [`autoMode`](#automode) 的任何地方读取。

1419* **类型**: 布尔值1428* **类型**: 布尔值

1420 * `true`：在自动模式处于活动状态时，Claude Code 通过分类器发送每个 Bash 和 PowerShell 命令，并暂停您的 shell 允许规则；在自动模式之外，规则仍然适用1429 * `true`：在自动模式处于活动状态时，Claude Code 通过分类器发送每个 Bash 和 PowerShell 命令，并暂停您的 shell 允许规则；在自动模式之外，规则仍然适用

1421 * `false`：自动模式仅暂停可能运行任意代码的允许规则，如 `Bash(*)` 和 `Bash(python *)`；任何其他允许规则匹配的命令会跳过分类器，每个其他 shell 命令都会通过它1430 * `false`：自动模式仅暂停可能运行任意代码的允许规则，如 `Bash(*)` 和 `Bash(python *)`；任何其他允许规则匹配的命令会跳过分类器，除非它携带[每命令允许的域](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)，每个其他 shell 命令都会通过它

1422* **默认值**: `false`1431* **默认值**: `false`

1423 1432

1424```json settings.json theme={null}1433```json settings.json theme={null}

1554 `permissions.deny`1563 `permissions.deny`

1555</h3>1564</h3>

1556 1565

1557列出 Claude Code 阻止的工具使用。将其用于保存 API 密钥、机密或环境值的文件：Claude Code 从文件发现和搜索结果中排除匹配的文件，拒绝读取它们，并在匹配的路径上阻止[编辑和写入工具](/docs/zh-CN/permissions#read-and-edit)。读取和编辑拒绝规则适用于 Claude 的内置文件工具、Claude Code 在 Bash 中识别的文件命令（如 `cat`、`head`、`tail` 和 `sed`）以及 Bash[重定向](/docs/zh-CN/permissions#redirections)的目标（如 `> file` 和 `< file`）；它们不适用于读取文件而不命名它们的命令（如 `grep -r pattern .`）或任意子进程，因此对于操作系统级别的强制执行，请[启用沙箱](/docs/zh-CN/sandboxing)。1566列出 Claude Code 阻止的工具使用。将其用于保存 API 密钥、机密或环境值的文件：Claude Code 从文件发现和搜索结果中排除匹配的文件，拒绝读取它们，并在匹配的路径上阻止[编辑和写入工具](/docs/zh-CN/permissions#read-and-edit)。读取和编辑拒绝规则适用于 Claude 的内置文件工具、Claude Code 在 Bash 中识别的文件命令（如 `cat`、`head`、`tail`、`sed` 和 `tee`）以及 Bash[重定向](/docs/zh-CN/permissions#redirections)的目标（如 `> file` 和 `< file`）；它们不适用于读取文件而不命名它们的命令（如 `grep -r pattern .`）或任意子进程，因此对于操作系统级别的强制执行，请[启用沙箱](/docs/zh-CN/sandboxing)。

1558 1567

1559* **作用域**: [`Any file`](#scopes)1568* **作用域**: [`Any file`](#scopes)

1560* **类型**: 权限规则字符串数组1569* **类型**: 权限规则字符串数组

1606 1615

1607阻止 Claude 在每个权限模式（包括 `bypassPermissions`）中使用 Read、Grep、Glob 和 LSP 工具读取会话[工作目录](/docs/zh-CN/permissions#working-directories)之外的路径。通过 Claude Code 识别的文件命令（如 `cat`）读取匹配路径的 Bash 命令会在自动模式和 `bypassPermissions` 模式中提示您。需要 Claude Code v2.1.257 或更高版本。1616阻止 Claude 在每个权限模式（包括 `bypassPermissions`）中使用 Read、Grep、Glob 和 LSP 工具读取会话[工作目录](/docs/zh-CN/permissions#working-directories)之外的路径。通过 Claude Code 识别的文件命令（如 `cat`）读取匹配路径的 Bash 命令会在自动模式和 `bypassPermissions` 模式中提示您。需要 Claude Code v2.1.257 或更高版本。

1608 1617

1609当您选择在[自动模式的提示中阻止此类读取（在第一次读取工作目录之外之前）](/docs/zh-CN/permission-modes#first-read-outside-the-working-directories)时，Claude Code 也会在此处写入 `true`。1618shell 解析器无法追踪的 Bash 命令（如多次更改目录或运行子 shell 的命令）会在自动模式和 `bypassPermissions` 模式中提示您。即使命令未命名工作目录之外的任何路径，提示也会出现。当命令在[沙箱](/docs/zh-CN/sandboxing)中运行且沙箱强制执行该块时，此提示不适用。

1619

1620Claude Code 也会在此处写入 `true`，当您选择在[自动模式的提示中阻止此类读取（在第一次读取工作目录之外之前）](/docs/zh-CN/permission-modes#first-read-outside-the-working-directories)时。

1610 1621

1611* **作用域**: [`Any file`](#scopes)。如果任何设置源设置 `true`，则应用该块，因此存储库的签入文件可以为项目打开该块，但无法解除您设置的块。1622* **作用域**: [`Any file`](#scopes)。如果任何设置源设置 `true`，则应用该块，因此存储库的签入文件可以为项目打开该块，但无法解除您设置的块。

1612* **类型**: 布尔值1623* **类型**: 布尔值

1622}1633}

1623```1634```

1624 1635

1625如果仅存储库的签入设置文件添加目录，该块仍然适用于那里的读取。Claude Code 本身需要的文件保持可读，如您的技能、插件、规则、代理、命令以及 `~/.claude/` 下的 `CLAUDE.md` 内存文件。1636如果仅存储库的签入设置文件添加目录，该块仍然适用于那里的读取。当 [`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` 内存文件。

1626 1637

1627当[沙箱](/docs/zh-CN/sandboxing)打开时，该块也会拒绝沙箱命令对工作目录之外的主目录和挂载卷根的读取访问。需要批准以[在沙箱外运行](/docs/zh-CN/sandboxing#the-unsandboxed-retry-escape-hatch)的重试会在 `bypassPermissions` 模式中提示您。工具从您的主目录读取的文件（如 `~/.gitconfig`）与其余文件一起被拒绝；当工具需要它时，使用 [`sandbox.filesystem.allowRead`](#sandbox-filesystem-allowread) 重新打开特定路径。1638当[沙箱](/docs/zh-CN/sandboxing)打开时，该块也会拒绝沙箱命令对工作目录之外的主目录和挂载卷根的读取访问。需要批准以[在沙箱外运行](/docs/zh-CN/sandboxing#the-unsandboxed-retry-escape-hatch)的重试会在 `bypassPermissions` 模式中提示您。工具从您的主目录读取的文件（如 `~/.gitconfig`）与其余文件一起被拒绝；当工具需要它时，使用 [`sandbox.filesystem.allowRead`](#sandbox-filesystem-allowread) 重新打开特定路径。

1628 1639

1654}1665}

1655```1666```

1656 1667

1657权限规则分层在每个模式之上：`deny` 规则在每个模式中阻止，包括 `bypassPermissions`。请参阅[权限模式](/docs/zh-CN/permission-modes)。`manual` 命名 CLI 和 VS Code 扩展中标记为"手动"的权限模式；别名需要 Claude Code v2.1.200 或更高版本。在网络上的 Claude Code 中，Claude Code 仅从此键中遵守 `acceptEdits`、`plan`、`default` 和 `auto`。对于 VS Code 扩展启动的对话，请参阅[扩展为启动权限模式读取的设置](/docs/zh-CN/permission-modes#switch-permission-modes)。1668权限规则分层在每个模式之上：`deny` 规则在每个模式中阻止，包括 `bypassPermissions`。请参阅[权限模式](/docs/zh-CN/permission-modes)。`manual` 命名 CLI 和 VS Code 扩展中标记为"手动"的权限模式；别名需要 Claude Code v2.1.200 或更高版本。在云会话中，Claude Code 仅从此键中遵守 `acceptEdits`、`plan`、`default` 和 `auto`。对于 VS Code 扩展启动的对话，请参阅[扩展为启动权限模式读取的设置](/docs/zh-CN/permission-modes#switch-permission-modes)。

1658 1669

1659<h3 id="permissions-disablebypasspermissionsmode">1670<h3 id="permissions-disablebypasspermissionsmode">

1660 `permissions.disableBypassPermissionsMode`1671 `permissions.disableBypassPermissionsMode`

1917Claude Code 也删除尾部 `/**`，因此 `~/build/**` 和 `~/build` 覆盖同一目录。通配符（如 `*` ）是否有效取决于条目所在的列表和平台：1928Claude Code 也删除尾部 `/**`，因此 `~/build/**` 和 `~/build` 覆盖同一目录。通配符（如 `*` ）是否有效取决于条目所在的列表和平台：

1918 1929

1919* **`allowWrite` 和 `denyWrite`**: 在 macOS 上，通配符有效。在 Linux 和 WSL2 上，沙箱挂载具体路径，因此 Claude Code 在删除尾部 `/**` 后跳过包含 `*`、`?` 或 `[` 的条目，该条目无效。Claude Code 将您的 `Edit` 权限规则中的路径添加到这些列表中，因此相同的限制适用于它们，`/sandbox` 的 **Config** 选项卡警告包含通配符的 `Edit` 和 `Read` 权限规则。1930* **`allowWrite` 和 `denyWrite`**: 在 macOS 上，通配符有效。在 Linux 和 WSL2 上，沙箱挂载具体路径，因此 Claude Code 在删除尾部 `/**` 后跳过包含 `*`、`?` 或 `[` 的条目，该条目无效。Claude Code 将您的 `Edit` 权限规则中的路径添加到这些列表中，因此相同的限制适用于它们，`/sandbox` 的 **Config** 选项卡警告包含通配符的 `Edit` 和 `Read` 权限规则。

1920* **`denyRead` 和 `allowRead`**: 通配符在每个平台上都有效。在 Linux 和WSL2 上，Claude Code 将读取条目扩展到它匹配的具体路径，对写入列表不执行此操作。1931* **`denyRead` 和 `allowRead`**: 通配符在每个平台上都有效。在 Linux 和 WSL2 上，Claude Code 将读取条目扩展到它匹配的具体路径，对写入列表不执行此操作。

1921 1932

1922<h3 id="sandbox-filesystem-allowwrite">1933<h3 id="sandbox-filesystem-allowwrite">

1923 `sandbox.filesystem.allowWrite`1934 `sandbox.filesystem.allowWrite`

2670* **Scope**: [`User or managed`](#scopes)。存储库无法打开或关闭它。2681* **Scope**: [`User or managed`](#scopes)。存储库无法打开或关闭它。

2671* **Type**: 布尔值2682* **Type**: 布尔值

2672 * `true`: Claude Code 拒绝沙箱化命令访问允许列表外的主机2683 * `true`: Claude Code 拒绝沙箱化命令访问允许列表外的主机

2673 * `false`: 除非另一个受信任的设置文件设置 `true`，Claude Code 根据权限模式而不是直接拒绝来决定允许列表外的主机：它在自动模式下运行分类器，在 `dontAsk` 模式下拒绝，在 `bypassPermissions` 模式下允许，在计划模式下当绕过可用时允许，否则询问您2684 * `false`: 除非另一个受信任的设置文件设置 `true`，Claude Code 根据权限模式而不是直接拒绝来决定允许列表外的主机：它在自动模式下检查主机对命令的 [per-command allowed domains](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)，在 `dontAsk` 模式下拒绝，在 `bypassPermissions` 模式下允许，在交互式终端计划模式会话中当绕过可用时允许，否则询问您

2674* **Default**: `false`2685* **Default**: `false`

2675 2686

2676```json settings.json theme={null}2687```json settings.json theme={null}

3136 `axScreenReader`3147 `axScreenReader`

3137</h3>3148</h3>

3138 3149

3139渲染屏幕阅读器友好的输出：没有装饰性边框或动画的平面文本。屏幕阅读器模式使用经典渲染器，因此在它处于活动状态时 `tui` 设置无效；附加的[后台会话](/docs/zh-CN/agent-view)仍会全屏渲染。需要 Claude Code v2.1.181 或更高版本。3150渲染屏幕阅读器友好的输出：没有装饰性边框或动画的平面文本。屏幕阅读器模式使用经典渲染器，因此在它处于活动状态时 `tui` 设置无效；附加的[后台会话](/docs/zh-CN/agent-view)仍会全屏渲染。

3140 3151

3141* **Scope**: [`Any file`](#scopes)3152* **Scope**: [`Any file`](#scopes)

3142* **Type**: Boolean3153* **Type**: Boolean

3151}3162}

3152```3163```

3153 3164

3154需要 Claude Code v2.1.181 或更高版本。3165<h3 id="basheditdiffenabled">

3166 `bashEditDiffEnabled`

3167</h3>

3168

3169选择 Claude Code 是否记录 Bash 命令在 Git 存储库中更改的文件。当它记录它们时，您会在命令后在终端中看到它们的差异，您的 [PostToolUse Bash hooks](/docs/zh-CN/hooks#bash) 会接收更改的文件列表。

3170

3171将键设置为 `true` 以在每个权限模式中记录它们。需要 Claude Code v2.1.269 或更高版本。

3172

3173* **Scope**: [`User or managed`](#scopes)。`true` 仅从您的用户设置、使用 `--settings` 传递的 JSON 或[托管设置](/docs/zh-CN/managed-settings)计数，因此存储库的 `.claude/settings.json` 或 `.claude/settings.local.json` 中的 `true` 无法打开记录。存储库文件中的 `false` 仍会关闭它，除非[更高优先级](/docs/zh-CN/settings#settings-precedence)的文件设置 `true`。

3174* **Type**: Boolean

3175* **Default**: unset，所以当 Claude Code 指导 Claude 通过 Bash 编辑文件时，Claude Code 在自动模式和 `bypassPermissions` 模式中记录更改

3176* **Per-session overrides**: [`CLAUDE_CODE_BASH_EDIT_DIFF`](/docs/zh-CN/env-vars) 在单个会话中优先于此键

3177

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

3179{

3180 "bashEditDiffEnabled": true

3181}

3182```

3155 3183

3156<h3 id="companyannouncements">3184<h3 id="companyannouncements">

3157 `companyAnnouncements`3185 `companyAnnouncements`

4297 `workflowSizeGuideline`4325 `workflowSizeGuideline`

4298</h3>4326</h3>

4299 4327

4300设置 [Claude 在其编写的动态工作流中针对的代理计数](/docs/zh-CN/workflows#set-a-size-guideline)。Claude Code 将值作为建议而不是强制上限发送给 Claude：`"small"` 要求少于 5 个代理，`"medium"` 少于 15 个，`"large"` 少于 50 个。当您想限制工作流花费的内容时，选择 `"small"`。需要 Claude Code v2.1.219 或更高版本。4328设置 [Claude 在其编写的动态工作流中针对的代理计数](/docs/zh-CN/workflows#set-a-size-guideline)。Claude Code 将值作为建议而不是强制上限发送给 Claude：`"small"` 要求少于 5 个代理，`"medium"` 少于 10 个，`"large"` 少于 50 个。当您想限制工作流花费的内容时，选择 `"small"`。需要 Claude Code v2.1.219 或更高版本。

4301 4329

4302* **作用域**: [`任何文件`](#scopes)。那里的值优先于 `/config` 中的 **动态工作流大小** 选择，Claude Code 将其存储在 `~/.claude.json` 中，当设置文件设置键时，Claude Code 隐藏该行。4330* **作用域**: [`任何文件`](#scopes)。那里的值优先于 `/config` 中的 **动态工作流大小** 选择，Claude Code 将其存储在 `~/.claude.json` 中，当设置文件设置键时，Claude Code 隐藏该行。

4303* **类型**: 字符串，以下之一：4331* **类型**: 字符串，以下之一：

4304 * `"unrestricted"`: 无指导，因此 Claude 根据任务调整工作流大小4332 * `"unrestricted"`: 无指导，因此 Claude 根据任务调整工作流大小

4305 * `"small"`: Claude 针对少于 5 个代理4333 * `"small"`: Claude 针对少于 5 个代理

4306 * `"medium"`: Claude 针对少于 15 个代理4334 * `"medium"`: Claude 针对少于 10 个代理

4307 * `"large"`: Claude 针对少于 50 个代理4335 * `"large"`: Claude 针对少于 50 个代理

4308* **默认值**: `"medium"`4336* **默认值**: `"medium"`，或当您在 Pro 计划上使用 Claude Code v2.1.271 或更高版本登录时为 `"small"`

4309 4337

4310```json settings.json theme={null}4338```json settings.json theme={null}

4311{4339{

4401 `syncClaudeAiSkills`4429 `syncClaudeAiSkills`

4402</h3>4430</h3>

4403 4431

4404关闭 [您在 claude.ai 上启用的技能](/docs/zh-CN/skills#how-synced-skills-behave) 的下载。当您使用 `-p` 标志在 [非交互模式](/docs/zh-CN/headless) 中运行它并设置 [`CLAUDE_CODE_SYNC_SKILLS`](/docs/zh-CN/env-vars#variables) 时，Claude Code 将它们下载到 `~/.claude/skills/synced/`。设置为 `false` 以停止该下载并隐藏已同步的技能。Claude Code 仅接受 `false`：`true` 与未设置相同，不会打开同步。4432关闭 [您在 claude.ai 上启用的技能](/docs/zh-CN/skills#how-synced-skills-behave) 的下载。Claude Code 在 [您使用 claude.ai 帐户登录的终端会话](/docs/zh-CN/skills#where-synced-skills-load)（交互式或非交互式）以及 Cowork 和云会话中将它们下载到 `~/.claude/skills/synced/`。设置为 `false` 以停止该下载并停止加载已同步的技能。Claude Code 仅接受 `false`：`true` 与未设置相同，不会打开同步。

4405 4433

4406* **Scope**: [`User, local, or managed`](#scopes)。存储库无法为您关闭它。4434* **Scope**: [`User, local, or managed`](#scopes)，以及使用 `--settings` 传递的文件。存储库无法为您关闭它。

4407* **Type**: Boolean4435* **Type**: Boolean

4408 * `false`: Claude Code 停止下载同步的技能并隐藏 `~/.claude/skills/synced/` 中已有的技能。在用户或托管设置中，它还将它们移动到 `~/.claude/skills/.trash/`4436 * `false`: Claude Code 停止下载同步的技能并停止加载 `~/.claude/skills/synced/` 中已有的技能。在用户或托管设置中，它还将它们移动到 `~/.claude/skills/.trash/`

4409 * `true`: 与未设置相同4437 * `true`: 与未设置相同

4410* **Default**: 未设置，因此使用 `CLAUDE_CODE_SYNC_SKILLS` 设置的非交互运行会下载技能4438* **Default**: 未设置，因此使用 claude.ai 帐户登录的会话会同步您的技能

4411 4439

4412此示例防止机器下载帐户的技能，无论会话在其环境中设置什么：4440此示例防止机器在任何会话中下载帐户的技能：

4413 4441

4414```json settings.json theme={null}4442```json settings.json theme={null}

4415{4443{

4417}4445}

4418```4446```

4419 4447

4448<h3 id="syncclaudeaiplugins">

4449 `syncClaudeAiPlugins`

4450</h3>

4451

4452关闭 [您在 claude.ai 上启用的插件](/docs/zh-CN/plugins-reference#synced-plugins) 的下载。Claude Code 在您使用 claude.ai 帐户登录的终端会话开始时将它们下载到 `~/.claude/plugins/synced/`，以及在 Cowork 和云会话中，并将每个加载为 `<name>@synced`。设置为 `false` 以停止该下载并停止加载已同步的插件。Claude Code 仅接受 `false`：`true` 与未设置相同，不会打开同步。需要 Claude Code v2.1.273 或更高版本。

4453

4454* **Scope**: [`User, local, or managed`](#scopes)，以及使用 `--settings` 传递的文件。存储库无法为您关闭它。

4455* **Type**: Boolean

4456 * `false`: Claude Code 停止下载同步的插件并停止加载 `~/.claude/plugins/synced/` 中已有的插件。在用户或托管设置中，它还将它们移动到 `~/.claude/plugins/.trash/`

4457 * `true`: 与未设置相同

4458* **Default**: 未设置，因此使用 claude.ai 帐户登录的会话会同步您的插件

4459

4460要关闭一个同步的插件而不是全部，请在 [`enabledPlugins`](#enabledplugins) 中设置 `"<name>@synced": false`。

4461

4462此示例防止机器在任何会话中下载帐户的插件：

4463

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

4465{

4466 "syncClaudeAiPlugins": false

4467}

4468```

4469

4420<h3 id="allowedchannelplugins">4470<h3 id="allowedchannelplugins">

4421 `allowedChannelPlugins`4471 `allowedChannelPlugins`

4422</h3>4472</h3>

4858 4908

4859`git` 来源类型适用于任何 git 托管服务，包括自托管 GitLab 和 Bitbucket。Claude Code 使用该机器上 `git clone` 会使用的相同身份验证克隆存储库：配置的凭证助手或 SSH 密钥。提供者令牌如 `GITHUB_TOKEN` 仅通过读取它的凭证助手生效。请参阅 [私有存储库](/docs/zh-CN/plugin-marketplaces#private-repositories) 了解设置详情。4909`git` 来源类型适用于任何 git 托管服务，包括自托管 GitLab 和 Bitbucket。Claude Code 使用该机器上 `git clone` 会使用的相同身份验证克隆存储库：配置的凭证助手或 SSH 密钥。提供者令牌如 `GITHUB_TOKEN` 仅通过读取它的凭证助手生效。请参阅 [私有存储库](/docs/zh-CN/plugin-marketplaces#private-repositories) 了解设置详情。

4860 4910

4861对于 `github` 和 `git` 来源，在 `source` 对象内部设置 `"skipLfs": true`，与 `repo` 或 `url` 一起，以在 Claude Code 克隆或更新市场存储库时跳过 Git LFS 下载。LFS 指针文件保持为指针而不是下载其内容。当存储库包含与插件内容无关的大型 LFS 对象时使用此功能。4911对于 `github` 和 `git` 来源，Claude Code 在克隆市场存储库以添加或更新时永远不会下载 [Git LFS](https://git-lfs.com) 内容。LFS 跟踪的文件被检出为指针文件，添加或更新输出报告有多少。

4912

4913`skipLfs` 字段在 `source` 对象内部被接受且没有效果。在 v2.1.274 之前，Claude Code 下载 LFS 内容，除非您设置 `"skipLfs": true`。

4862 4914

4863对于 `url` 来源，当 `headers` 中的凭证过期且命令必须生成新凭证时，在 `source` 对象内部设置 `headersHelper`。需要 Claude Code v2.1.238 或更高版本。有关命令必须打印什么以及 Claude Code 在哪里运行它，请参阅 [编写 headersHelper 命令](/docs/zh-CN/plugin-marketplaces#write-the-headershelper-command)，以及 Claude Code 不运行它的情况，请参阅 [何时 Claude Code 跳过 headersHelper 命令或丢弃其输出](/docs/zh-CN/plugin-marketplaces#when-claude-code-skips-a-headershelper-command-or-drops-its-output)。在 `https://` 市场 URL 上设置 `headersHelper` 后，Claude Code 在两个点运行命令，重用一次运行的输出长达 60 秒：4915对于 `url` 来源，当 `headers` 中的凭证过期且命令必须生成新凭证时，在 `source` 对象内部设置 `headersHelper`。需要 Claude Code v2.1.238 或更高版本。有关命令必须打印什么以及 Claude Code 在哪里运行它，请参阅 [编写 headersHelper 命令](/docs/zh-CN/plugin-marketplaces#write-the-headershelper-command)，以及 Claude Code 不运行它的情况，请参阅 [何时 Claude Code 跳过 headersHelper 命令或丢弃其输出](/docs/zh-CN/plugin-marketplaces#when-claude-code-skips-a-headershelper-command-or-drops-its-output)。在 `https://` 市场 URL 上设置 `headersHelper` 后，Claude Code 在两个点运行命令，重用一次运行的输出长达 60 秒：

4864 4916

4934}4986}

4935```4987```

4936 4988

4989内置插件使用带有 `@builtin` 后缀的相同键存储其选项。例如，控制 Claude Code 是否读取 `AGENTS.md` 文件的 [**Project instructions**](/docs/zh-CN/memory#choose-which-instruction-files-load) 设置是 `pluginConfigs["agents-md@builtin"].options.instructionFiles`。

4990

4937Claude Code 忽略项目和本地条目，因为它将这些值替换到插件 hook、MCP 和 LSP 配置中，克隆的存储库不得能够提供它们。在 v2.1.207 之前，项目和本地设置也被读取。4991Claude Code 忽略项目和本地条目，因为它将这些值替换到插件 hook、MCP 和 LSP 配置中，克隆的存储库不得能够提供它们。在 v2.1.207 之前，项目和本地设置也被读取。

4938 4992

4939<h2 id="mcp">4993<h2 id="mcp">

5020阻止特定的 MCP 服务器。Claude Code 拒绝加载匹配的服务器，无论在何处定义，包括插件服务器、使用 `--mcp-config` 传递的服务器、来自 `managed-mcp.json` 的服务器、来自 [`managedMcpServers`](#managedmcpservers) 的服务器，以及 [它自行获取](/docs/zh-CN/mcp#how-connectors-reach-claude-code)的 claude.ai 连接器。进程内 `type: "sdk"` 服务器不受限制；启动会话的应用会注册它们。5074阻止特定的 MCP 服务器。Claude Code 拒绝加载匹配的服务器，无论在何处定义，包括插件服务器、使用 `--mcp-config` 传递的服务器、来自 `managed-mcp.json` 的服务器、来自 [`managedMcpServers`](#managedmcpservers) 的服务器，以及 [它自行获取](/docs/zh-CN/mcp#how-connectors-reach-claude-code)的 claude.ai 连接器。进程内 `type: "sdk"` 服务器不受限制；启动会话的应用会注册它们。

5021 5075

5022* **作用域**: [`Any file`](#scopes)。来自每个文件的条目合并为一个拒绝列表，[`allowManagedMcpServersOnly`](#allowmanagedmcpserversonly) 不会改变这一点。在托管设置中部署它以强制执行。5076* **作用域**: [`Any file`](#scopes)。来自每个文件的条目合并为一个拒绝列表，[`allowManagedMcpServersOnly`](#allowmanagedmcpserversonly) 不会改变这一点。在托管设置中部署它以强制执行。

5023* **类型**: 对象数组，每个对象恰好有一个密钥：`serverName`，任何非空字符串，因此 claude.ai 连接器的显示名称（例如 `"claude.ai Slack"`）有效；`serverCommand`，一个与命令及其参数完全匹配的数组；或 `serverUrl`，一个带有 `*` 通配符的 URL 模式5077* **类型**: 对象数组，每个对象恰好有一个密钥：`serverName`，一个字符串，因此 claude.ai 连接器的显示名称（例如 `"claude.ai Slack"`）有效；`serverCommand`，一个与命令及其参数完全匹配的数组；或 `serverUrl`，一个带有 `*` 通配符的 URL 模式

5024* **默认值**: 未设置，因此不阻止任何服务器；空数组也不阻止任何内容5078* **默认值**: 未设置，因此不阻止任何服务器；空数组也不阻止任何内容

5025 5079

5026```json settings.json theme={null}5080```json settings.json theme={null}

5037 `disableClaudeAiConnectors`5091 `disableClaudeAiConnectors`

5038</h3>5092</h3>

5039 5093

5040关闭 [claude.ai MCP 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) [Claude Code 自行获取](/docs/zh-CN/mcp#how-connectors-reach-claude-code)，因此它既不获取也不连接它们。任何设置文件中的 `true` 都适用：签入的项目 `.claude/settings.json` 可以选择退出存储库中的这些连接器，但项目级别的 `false` 无法覆盖用户级别或托管级别的 `true`。需要 Claude Code v2.1.182 或更高版本。5094关闭 [claude.ai MCP 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) [Claude Code 自行获取](/docs/zh-CN/mcp#how-connectors-reach-claude-code)，因此它既不获取也不连接它们。任何设置文件中的 `true` 都适用：签入的项目 `.claude/settings.json` 可以选择退出存储库中的这些连接器，但项目级别的 `false` 无法覆盖用户级别或托管级别的 `true`。

5041 5095

5042* **作用域**: [`Any file`](#scopes)5096* **作用域**: [`Any file`](#scopes)

5043* **类型**: 布尔值5097* **类型**: 布尔值

5052}5106}

5053```5107```

5054 5108

5055您使用 `--mcp-config` 显式传递的服务器不受影响。要阻止单个连接器而不是全部，请使用 [`deniedMcpServers`](#deniedmcpservers)。请参阅[禁用 claude.ai 连接器](/docs/zh-CN/mcp#disable-claude-ai-connectors)。需要 Claude Code v2.1.182 或更高版本。5109您使用 `--mcp-config` 显式传递的服务器不受影响。要阻止单个连接器而不是全部，请使用 [`deniedMcpServers`](#deniedmcpservers)。请参阅[禁用 claude.ai 连接器](/docs/zh-CN/mcp#disable-claude-ai-connectors)。

5056 5110

5057<h3 id="disabledmcpjsonservers">5111<h3 id="disabledmcpjsonservers">

5058 `disabledMcpjsonServers`5112 `disabledMcpjsonServers`

5266}5320}

5267```5321```

5268 5322

5269在 v2.1.179 之前，默认值为 `auto`。`iterm2` 值需要 Claude Code v2.1.186 或更高版本。5323`iterm2` 值需要 Claude Code v2.1.186 或更高版本。

5270 5324

5271<span id="worktree-settings" />5325<span id="worktree-settings" />

5272 5326

5791 5845

5792请参阅[限制登录到您的组织](/docs/zh-CN/authentication#restrict-login-to-your-organization)，了解 Claude Code 如何处理 Claude Console 登录、其他登录路径和环境凭证。5846请参阅[限制登录到您的组织](/docs/zh-CN/authentication#restrict-login-to-your-organization)，了解 Claude Code 如何处理 Claude Console 登录、其他登录路径和环境凭证。

5793 5847

5848<h3 id="gatewayinternalnetworks">

5849 `gatewayInternalNetworks`

5850</h3>

5851

5852声明您的组织从其内部网络编号的公共 IPv4 块，以便 `/login` 在那里接受 [cloud gateway](/docs/zh-CN/claude-apps-gateway)。需要 Claude Code v2.1.268 或更高版本。

5853

5854没有此密钥，`/login` 连接到私有地址上的任何网关，仅此而已。有了它，`/login` 也接受列出的块内的网关，仅通过直接连接。该机器在该连接上的自身地址也必须在同一块内。

5855

5856* **Scope**: [`Managed`](#scopes)。仅从机器上的源读取：`managed-settings.json`、macOS plist 或 Windows HKLM 注册表或策略辅助程序。Claude Code 在 HKCU 和服务器托管设置中忽略它。

5857* **Type**: 字符串数组，最多四个 IPv4 CIDR 块，每个 `/8` 到 `/32`，彼此不重叠，且都不与私有空间重叠。

5858* **Default**: 未设置，因此 `/login` 仅接受私有地址上的网关

5859

5860```json managed-settings.json theme={null}

5861{

5862 "gatewayInternalNetworks": ["203.0.113.0/24"]

5863}

5864```

5865

5866将示例中的文档范围替换为您自己的块。Claude Code 拒绝文档范围、VPN 和 NAT64 客户端在本地使用的范围，以及保留空间（没有网络从其编号），例如多播。

5867

5868如果条目无效或值不是字符串列表，`/login` 会命名问题，并拒绝机器上的每个新网关登录，直到您修复该值。现有登录继续工作。请参阅[允许网关在您拥有的公共地址空间上](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)，了解完整规则和开发人员看到的内容。

5869

5794<h3 id="gcpauthrefresh">5870<h3 id="gcpauthrefresh">

5795 `gcpAuthRefresh`5871 `gcpAuthRefresh`

5796</h3>5872</h3>

6105 6181

6106Claude 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 或更高版本。6182Claude 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 或更高版本。

6107 6183

6108在云会话中，Claude Code 也会忽略服务器传递的中途 MCP 更新，这是云会话配置和远程工作者上 SDK `setMcpServers()` 背后的路径。进程内 `type: "sdk"` 条目在那里仍然豁免。在 v2.1.239 之前，服务器传递的 `--mcp-config` 会阻止云会话启动。6184在云会话中，Claude Code 也会忽略服务器传递的中途 MCP 更新，这是云会话配置和 SDK `setMcpServers()` 调用背后的路径，这些调用到达这些会话。进程内 `type: "sdk"` 条目在那里仍然豁免。在 v2.1.239 之前，服务器传递的 `--mcp-config` 会阻止云会话启动。

6109 6185

6110<h3 id="forceremotesettingsrefresh">6186<h3 id="forceremotesettingsrefresh">

6111 `forceRemoteSettingsRefresh`6187 `forceRemoteSettingsRefresh`

6170 6246

6171* **[`policyHelper`](#policyhelper)**: Claude Code 仅在携带策略密钥的最高源是 MDM 策略或托管设置文件时才接受它，因此在服务器管理的设置下它不适用。6247* **[`policyHelper`](#policyhelper)**: Claude Code 仅在携带策略密钥的最高源是 MDM 策略或托管设置文件时才接受它，因此在服务器管理的设置下它不适用。

6172* **[`modelOverrides`](#modeloverrides)**: 与 `availableModels` 配对。Claude Code 从设置它的最高源取值 `modelOverrides`，除非较高源设置 `availableModels` 而不设置 `modelOverrides`。在这种情况下，它忽略来自每个源的 `modelOverrides`。6248* **[`modelOverrides`](#modeloverrides)**: 与 `availableModels` 配对。Claude Code 从设置它的最高源取值 `modelOverrides`，除非较高源设置 `availableModels` 而不设置 `modelOverrides`。在这种情况下，它忽略来自每个源的 `modelOverrides`。

6173* **[`forceLoginGatewayUrl`](#forcelogingatewayurl) 和 [`forceLoginMethod`](#forceloginmethod) 的 `"gateway"` 值**: Claude Code 从不从服务器管理的设置读取它们，因此那里的值既不适用也不隐藏在 MDM 策略或托管设置文件中设置的值。在机器上的管理员源中，仅携带策略密钥的最高排名源提供它们，无论服务器管理的设置是否也存在。6249* **[`forceLoginGatewayUrl`](#forcelogingatewayurl)、[`gatewayInternalNetworks`](#gatewayinternalnetworks) 和 [`forceLoginMethod`](#forceloginmethod) 的 `"gateway"` 值**: Claude Code 从不从服务器管理的设置读取它们，因此那里的值既不适用也不隐藏在 MDM 策略或托管设置文件中设置的值。在机器上的管理员源中，仅携带策略密钥的最高排名源提供它们，无论服务器管理的设置是否也存在。

6174 6250

6175要确认机器上合并了哪些源，请运行 `/status` 并[读取 `Setting sources` 行](/docs/zh-CN/managed-settings#read-the-source-in-/status)。6251要确认机器上合并了哪些源，请运行 `/status` 并[读取 `Setting sources` 行](/docs/zh-CN/managed-settings#read-the-source-in-/status)。

6176 6252

setup.md +1 −1

Details

202 身份验证202 身份验证

203</h2>203</h2>

204 204

205Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 账户。免费的 Claude.ai 计划不包括 Claude Code 访问权限。您也可以通过第三方 API 提供商（如 [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)）使用 Claude Code。205Claude Code 需要 Pro、Max、Team、Enterprise 或 Console 账户。免费的 claude.ai 计划不包括 Claude Code 访问权限。您也可以通过第三方 API 提供商（如 [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)）使用 Claude Code。

206 206

207安装后，通过运行 `claude` 并按照浏览器提示登录。如果设置了 `ANTHROPIC_API_KEY` 环境变量，Claude Code 会提示您一次以批准该密钥，而不是打开浏览器。有关所有账户类型和团队设置选项，请参阅[身份验证](/docs/zh-CN/authentication)。207安装后，通过运行 `claude` 并按照浏览器提示登录。如果设置了 `ANTHROPIC_API_KEY` 环境变量，Claude Code 会提示您一次以批准该密钥，而不是打开浏览器。有关所有账户类型和团队设置选项，请参阅[身份验证](/docs/zh-CN/authentication)。

208 208

skills.md +108 −91

Details

117</Steps>117</Steps>

118 118

119<h2 id="where-skills-live">119<h2 id="where-skills-live">

120 选择 skills 的加载位置120 选择技能加载的位置

121</h2>121</h2>

122 122

123skills 的保存位置决定了哪些会话会加载它。将其保存在主目录下可在每个项目中使用，将其提交到存储库可与该处的所有人共享，或通过插件或托管设置分发以覆盖整个团队。123技能的保存位置决定了哪些会话会加载它。将其保存在主目录下可以在每个项目中使用，将其提交到存储库可以与在那里工作的每个人共享，或通过插件或托管设置分发以覆盖整个团队。

124 124

125| 位置 | 路径 | 加载位置 |125| 位置 | 路径 | 加载位置 |

126| :------------------- | :--------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- |126| :------------------- | :--------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ |

130| Nested | `<subdir>/.claude/skills/<skill-name>/SKILL.md` | 在 `<subdir>` 中或其下方启动的会话。在其上方启动的会话在 Claude 处理该处的文件时加载该 skill。请参阅[单体仓库和子目录](#discovery-from-parent-and-nested-directories) |130| Nested | `<subdir>/.claude/skills/<skill-name>/SKILL.md` | 在 `<subdir>` 中或下方启动的会话。在其上方启动的会话在 Claude 处理那里的文件时加载技能。请参阅 [monorepos 和子目录](#discovery-from-parent-and-nested-directories) |

134 134

135Skill 文件夹还遵循以下规则：135技能文件夹还遵循以下规则：

136 136

137* **符号链接文件夹**：enterprise、personal 或 project 位置中的 `<skill-name>` 条目可以是指向磁盘上其他位置的目录的符号链接。Claude Code 从目标读取 `SKILL.md` 并加载 skill，即使多个位置指向同一目标也只加载一次。插件 skills [以不同方式处理符号链接](/docs/zh-CN/plugins-reference#share-files-within-a-marketplace-with-symlinks)。137* **符号链接文件夹**：企业、个人或项目位置中的 `<skill-name>` 条目可以是指向磁盘上其他位置的目录的符号链接。Claude Code 从目标读取 `SKILL.md` 并加载技能一次，即使多个位置指向同一目标。插件技能 [以不同方式处理符号链接](/docs/zh-CN/plugins-reference#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`，无论大小写如何。Claude Code 使用 `~/.claude/skills/synced/` 来存放 [从 claude.ai 下载的技能](#where-synced-skills-load)，并跳过您在企业、个人和项目位置中以该名称创作的技能。

139* **命令文件**：`.claude/commands/` 中的 Markdown 文件是较旧的格式，仍然有效。它支持相同的[前置元数据](#frontmatter-reference)，除了 `name` 和 `paths`。要找到您键入以调用它的名称，请参阅[skill 如何获得其命令名称](#how-a-skill-gets-its-command-name)。对于新工作，优先使用 skill，因为 skills 还支持[支持文件](#add-supporting-files)。139* **命令文件**：`.claude/commands/` 中的 Markdown 文件是较旧的格式，仍然有效。它支持相同的 [frontmatter](#frontmatter-reference)，除了 `name` 和 `paths`。要找到您输入以调用它的名称，请参阅 [技能如何获得其命令名称](#how-a-skill-gets-its-command-name)。对于新工作，更倾向于使用技能，因为技能还支持 [支持文件](#add-supporting-files)。

140* **Skill 文件夹作为插件**：将 `.claude-plugin/plugin.json` 添加到 skill 文件夹，它将作为[插件](/docs/zh-CN/plugins-reference#skills-directory-plugins)加载，名称为 `<name>@skills-dir`，因此它可以捆绑代理、hooks 和 MCP 服务器。在项目的 `.claude/skills/` 中，这需要首先接受工作区信任对话框。140* **技能文件夹作为插件**：将 `.claude-plugin/plugin.json` 添加到技能文件夹，它将作为 [插件](/docs/zh-CN/plugins-reference#skills-directory-plugins) 加载，名称为 `<name>@skills-dir`，因此它可以捆绑代理、hooks 和 MCP 服务器。在项目的 `.claude/skills/` 中，这需要首先接受工作区信任对话框。

141 141

142<h3 id="discovery-from-parent-and-nested-directories">142<h3 id="discovery-from-parent-and-nested-directories">

143 在单体仓库和子目录中加载 skills143 在 monorepos 和子目录中加载技能

144</h3>144</h3>

145 145

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。146Claude Code 从启动它的目录中的 `.claude/skills/` 以及直到存储库根目录的每个父目录中加载项目技能，因此在 `packages/frontend/` 中启动仍然会获取在根目录中定义的技能。当您在 v2.1.246 或更高版本上 [使用 `/cd` 移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory) 时，Claude Code 会添加新目录的项目技能。

147 147

148启动位置下方的 `.claude/skills/` 目录中的 Skills 在启动时不会加载。它们在 Claude 首次读取或编辑该子目录中的文件时加载，并在会话的其余部分保持可用。在此之前，它们不会出现在 `/` 菜单中，您也无法按名称调用它们。要更早加载它们，请使用子目录的路径运行 `/add-dir`，这需要 Claude Code v2.1.257 或更高版本。148`.claude/skills/` 目录中启动位置下方的技能在启动时不会加载。它们在 Claude 首次读取或编辑该子目录中的文件时加载，并在会话的其余部分保持可用。在此之前，它们不会出现在 `/` 菜单中，您也无法按名称调用它们。要更早加载它们，请使用子目录的路径运行 `/add-dir`，这需要 Claude Code v2.1.257 或更高版本。

149 149

150当嵌套 skill 与另一个 skill 共享名称时，两者都保持可用。在存储库根目录有一个 `deploy` skill，在 `apps/web/.claude/skills/` 中有另一个：150当嵌套技能与另一个技能共享名称时，两者都保持可用。在存储库根目录和 `apps/web/.claude/skills/` 中都有一个 `deploy` 技能：

151 151

152* `/deploy` 运行根 skill。Claude Code 还为 Claude 列出目录限定的变体，并指示调用其目录包含它正在处理的文件的那个，因此嵌套 skill 仍适用于 `apps/web/` 中的工作。152* `/deploy` 运行根技能。Claude Code 还为 Claude 列出目录限定的变体，并带有说明以调用其目录包含它正在处理的文件的变体，因此嵌套技能仍然适用于 `apps/web/` 中的工作。

153* `/apps/web:deploy` 单独运行嵌套 skill。其描述命名了它适用的目录。153* `/apps/web:deploy` 单独运行嵌套技能。其描述命名了它适用的目录。

154 154

155<h3 id="skills-from-additional-directories">155<h3 id="skills-from-additional-directories">

156 从项目外的目录加载 skills156 从项目外的目录加载技能

157</h3>157</h3>

158 158

159当您使用 `--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` 设置仅授予文件访问权限，不加载这些中的任何一个。159当您使用 `--add-dir` 或 `/add-dir` 添加目录时，Claude Code 会加载该目录的 `.claude/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` 设置仅授予文件访问权限，不加载这些中的任何一个。

160 160

161Claude Code 在启动时使用 `--add-dir` 传递的目录中监视 `.claude/skills/`，如[在会话期间编辑 skill](#live-change-detection) 所述。它不监视添加目录的 `.claude/commands/` 或 `.claude/agents/`，因此在更改该处的文件后重新启动会话。161Claude Code 在启动时使用 `--add-dir` 传递的目录中的 `.claude/skills/` 进行监视，如 [在会话期间编辑技能](#live-change-detection) 所述。它不监视添加目录的 `.claude/commands/` 或 `.claude/agents/`，因此在更改那里的文件后重新启动会话。

162 162

163这些加载取决于 `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) 各自进一步限制它们，如这些页面所述。有关添加目录加载的完整表格（包括 `CLAUDE.md` 和插件设置），请参阅[其他目录授予文件访问权限，而不是配置](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration)。163这些加载取决于 `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` 和插件设置。

164 164

165<h3 id="resolve-skills-that-share-a-name">165<h3 id="resolve-skills-that-share-a-name">

166 解决共享名称的 skills166 解决共享名称的技能

167</h3>167</h3>

168 168

169当两个 skills 共享名称时，每个来自的位置决定了 `/name` 运行哪一个。该表涵盖 enterprise、personal、project、nested、plugin 和 claude.ai 位置、捆绑 skills 和命令文件：169当两个技能共享名称时，每个技能来自的位置决定了 `/name` 运行哪一个。该表涵盖企业、个人、项目、嵌套、插件和 claude.ai 位置、捆绑技能和命令文件：

170 170

171| 相同名称在 | 运行哪一个 |171| 相同名称在 | 运行哪一个 |

172| :------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |172| :--------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------- |

173| Enterprise、personal 和 project 中的两个 | Enterprise 优于 personal，personal 优于 project。在 `~/.claude/skills/` 和项目的 `.claude/skills/` 中都有 `deploy` 时，`/deploy` 运行 personal 的 |173| 企业、个人和项目中的两个 | Enterprise 优于 personal，personal 优于 project。在 `~/.claude/skills/` 和项目的 `.claude/skills/` 中都有 `deploy` 时，`/deploy` 运行 personal 的 |

174| 这些位置中的任何一个和[捆绑 skill](#bundled-skills) | 您的 skill 替换捆绑命令，但不替换其别名。项目 `code-review` skill 替换 `/code-review`，捆绑别名 `/review` 永远不会运行您的 skill |174| 这些位置中的任何一个和 [捆绑技能](#bundled-skills) | 您的技能替换捆绑命令，但不替换其别名。项目 `code-review` 技能替换 `/code-review`，捆绑别名 `/review` 永远不会运行您的技能 |

175| Skill 和 `.claude/commands/` 中的文件 | Skill |175| 技能和 `.claude/commands/` 中的文件 | 技能 |

176| 项目根 skill 和嵌套 skill | 两者都加载。请参阅[单体仓库和子目录](#discovery-from-parent-and-nested-directories) |176| 项目根技能和嵌套技能 | 两者都加载。请参阅 [monorepos 和子目录](#discovery-from-parent-and-nested-directories) |

178| 上述任何一个和从 claude.ai 同步的 skill | 其他 skill 或命令。请参阅[当同步的 skill 名称与另一个命令匹配时](#when-a-synced-skill-name-matches-another-command) |178| 上述任何一个和 [从您的 claude.ai 账户同步的技能](#how-synced-skills-behave) | 其他技能或命令。同步的技能仍然作为 `/anthropic-skills:<name>` 运行。请参阅 [当同步的技能名称与另一个命令匹配时](#when-a-synced-skill-name-matches-another-command) |

179 179

180<h3 id="skills-in-cowork-and-cloud-sessions">180<h3 id="skills-in-cowork-and-cloud-sessions">

181 在 Cowork 和云会话中使用 skills181 在 Cowork 和云会话中使用技能

182</h3>182</h3>

183 183

184[Cowork](https://claude.com/product/cowork) 会话和[云会话](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)（包括[例程](/docs/zh-CN/routines)）不读取您机器上的 `~/.claude/skills/`。交互式和计划的 Cowork 会话都加载为您的 claude.ai 账户启用的 skills，在会话开始时同步；从 Desktop 应用侧边栏中的**自定义**或 claude.ai 上的 skills 设置管理它们。云会话还加载提交到克隆存储库的 `.claude/skills/` 的项目 skills。184[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 账户启用的技能，在会话开始时同步；从 Desktop 应用侧边栏中的 **Customize** 或从 claude.ai 上的技能设置管理它们。云会话还加载提交到克隆存储库的 `.claude/skills/` 的项目技能。

185 185

186如果 skill 仅存在于您机器上的 `~/.claude/skills/` 中，当[例程](/docs/zh-CN/routines)调用它时，Claude Code 会报告找不到该 skill，因为每次例程运行都作为新的远程会话启动。要在这些会话中提供个人 skill：186如果技能仅存在于您机器上的 `~/.claude/skills/` 中，当 [routine](/docs/zh-CN/routines) 调用它时，Claude Code 会报告找不到该技能，因为每个 routine 运行都作为新的云会话启动。要在这些会话中使用个人技能：

187 187

188* 对于 Cowork 和云会话，为您的 claude.ai 账户启用该 skill。188* 对于 Cowork 和云会话，为您的 claude.ai 账户启用该技能。

189* 对于云会话，您可以改为将 skill 提交到存储库的 `.claude/skills/`，或在存储库的 `.claude/settings.json` 中声明的插件中提供它。存储库声明的插件[在会话开始时安装](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)；仅在用户设置中启用的插件不会转移。189* 对于云会话，您可以改为将技能提交到存储库的 `.claude/skills/`，或在存储库的 `.claude/settings.json` 中声明的插件中提供它。Repo 声明的插件 [在会话开始时安装](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)；仅在您的用户设置中启用的插件不会转移。

190 190

191[Desktop 计划任务](/docs/zh-CN/desktop-scheduled-tasks)在您的机器上本地运行，因此它们确实加载 `~/.claude/skills/`。191[Desktop scheduled tasks](/docs/zh-CN/desktop-scheduled-tasks) 在您的机器上本地运行，因此它们确实加载 `~/.claude/skills/`。

192 192

193<h3 id="how-synced-skills-behave">193<h3 id="how-synced-skills-behave">

194 从 claude.ai 同步的 Skills194 从 claude.ai 同步的技能

195</h3>195</h3>

196 196

197本部分适用于为 claude.ai 账户启用了 skills 的您。在 Cowork 和云会话中，Claude Code 加载这些 skills，无需在您的机器上进行任何设置。在您机器上的任何其他会话中，Claude Code 仅在使用[其中同步的 skills 加载](#where-synced-skills-load)中所述的 [`CLAUDE_CODE_SYNC_SKILLS`](/docs/zh-CN/env-vars#variables) 在非交互式运行中打开同步后才加载它们。197如果您使用 Cowork 或云会话，或在终端中使用 claude.ai 账户登录 Claude Code，本部分适用于您。在这些会话中，Claude Code 加载为您的 claude.ai 账户启用的技能，无需您进行任何设置，如 [同步技能加载的位置](#where-synced-skills-load) 所述。这些技能包括您在 claude.ai 设置中创建或启用的技能、您的组织在那里提供的技能，以及 Anthropic 的内置技能，例如 `pdf` 和 `xlsx`。

198 198

199Claude Code 从您的账户下载同步的 skill，而不是读取您在运行会话的机器上编写的文件，因此它对同步 skills 应用不适用于您存储在[skills 位置](#where-skills-live)中的 skills 的规则。199Claude Code 从您的账户下载同步的技能，而不是读取您在会话运行的机器上编写的文件，因此它对同步技能应用不适用于您存储在 [技能位置](#where-skills-live) 中的技能的规则。

200 200

201<h4 id="where-synced-skills-load">201<h4 id="where-synced-skills-load">

202 同步的 skills 加载位置202 同步技能加载的位置

203</h4>203</h4>

204 204

205在 Cowork 或云会话中，Claude Code 加载为您的 claude.ai 账户启用的 skills，[Cowork 和云会话中的 Skills](#skills-in-cowork-and-cloud-sessions) 说明了如何选择这些会话获得哪些 skills。205在 Cowork 或云会话中，Claude Code 加载为您的 claude.ai 账户启用的技能，[Cowork 和云会话中的技能](#skills-in-cowork-and-cloud-sessions) 说明了如何选择这些会话获得哪些技能。

206 206

207在您机器上的任何其他会话中，Claude Code 仅在您在非交互式运行中首次下载它们后才加载它们：207在您的终端中，Claude Code 在您使用 claude.ai 账户登录的会话中同步这些技能。当会话启动时，Claude Code 在后台将您账户的技能下载到 `~/.claude/skills/synced/`，然后在会话运行时大约每 10 分钟检查一次 claude.ai 是否有更改。当检查发现技能在 claude.ai 上被添加、编辑或关闭时，Claude Code 在运行的会话中添加、更新或删除它，无需重新启动。终端会话中的同步需要 Claude Code v2.1.273 或更高版本。

208 208

209<Steps>209同步永远不会延迟启动，因为 Claude 仅在调用技能时等待技能的下载。因此，短 [非交互式](/docs/zh-CN/headless) 运行可能在新添加的技能下载之前完成，在这种情况下，稍后的会话会下载它。要使非交互式运行下载您的技能并在回答提示之前等待列表，请将 [`CLAUDE_CODE_SYNC_SKILLS`](/docs/zh-CN/env-vars#variables) 设置为 `1`。

210 <Step title="为您的 claude.ai 账户启用 skills">

211 为您的 claude.ai 账户启用您想要的每个 skill，如[Cowork 和云会话中的 Skills](#skills-in-cowork-and-cloud-sessions) 所述。Claude Code 仅下载您启用的 skills，它需要您的 claude.ai 登录来下载它们。

212 </Step>

213 210

214 <Step title="在启用同步的非交互式模式下运行 Claude Code">211Claude Code 仅在使用您的 claude.ai 账户登录的会话中同步，并 [从 Anthropic 获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)。它不在这些会话中同步：

215 Claude Code 仅在您以[非交互式模式](/docs/zh-CN/headless)运行它并使用 `-p` 标志且设置 [`CLAUDE_CODE_SYNC_SKILLS`](/docs/zh-CN/env-vars#variables) 为 `1` 时下载同步的 skills。您传递的提示不影响下载。

216 212

217 ```bash theme={null}213* 不使用 `/login` 存储的登录的会话，例如使用 API 密钥进行身份验证的会话，或 `ANTHROPIC_AUTH_TOKEN`、`CLAUDE_CODE_OAUTH_TOKEN` 或 `apiKeyHelper` 脚本提供凭证的会话

218 CLAUDE_CODE_SYNC_SKILLS=1 claude -p "List the skills you have available"214* 不获取功能标志的会话，例如 Amazon Bedrock 上的会话或您设置 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 的会话

219 ```215* [bare mode](/docs/zh-CN/headless#start-faster-with-bare-mode) 中的会话或您使用 `--safe-mode` 启动的会话

216* 您的组织的托管设置 [将技能锁定到插件源](/docs/zh-CN/settings-reference#strictpluginonlycustomization-skills) 的会话，或您使用 [`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 列表启动的会话，该列表省略了 `user`

220 217

221 Claude Code 将 skills 下载到 `~/.claude/skills/synced/`，回答提示，并像任何其他非交互式运行一样退出。下载的 skills 在它退出后保留在磁盘上，因此您不需要保持运行打开。Claude Code 仅在设置了 `CLAUDE_CODE_SYNC_SKILLS` 的运行期间下载 skills，因此在您在 claude.ai 上启用或更改 skill 后，再次运行该命令。要更改运行在回答提示之前等待同步的时间，设置 [`CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`](/docs/zh-CN/env-vars#variables)。218如果您在会话期间使用 `/login` 登录，请重新启动 Claude Code 以开始同步。

222 </Step>

223 219

224 <Step title="确认 skills 在本地会话中加载">220较早会话同步的技能保留在磁盘上。Claude Code 在稍后登录到同一账户的会话中加载它们，即使它无法到达 claude.ai。

225 启动交互式会话，不设置 `CLAUDE_CODE_SYNC_SKILLS`，并运行 `/skills`。菜单在 `claude.ai sync` 下列出下载的 skills。之后您使用相同 claude.ai 登录启动的每个本地会话也会从 `~/.claude/skills/synced/` 加载它们。221

226 </Step>222要查看哪些技能已同步，请运行 `/skills`。菜单在 `claude.ai sync` 下列出它们。

227</Steps>223

224Anthropic 的某些技能，例如 `pdf` 和 `xlsx`，始终同步。对于其余的，在 claude.ai 上的技能设置中打开或关闭技能以更改是否同步。

225

226要停止在机器上同步，请在您的用户设置中将 [`syncClaudeAiSkills`](/docs/zh-CN/settings-reference#syncclaudeaiskills) 设置为 `false`。Claude Code 停止下载，下次启动时，它将已同步的技能移动到 `~/.claude/skills/.trash/`，不再加载它们。您的组织可以通过关闭 claude.ai 上的 Skills 来为所有人关闭同步。要在保持 Skills 打开的情况下停止同步，它可以在 [托管设置](/docs/zh-CN/managed-settings) 中设置相同的密钥。

227

228如果您的组织关闭 claude.ai 上的 Skills，Claude Code 会删除下载的技能，它们停止加载。删除的技能移动到 `~/.claude/skills/.trash/`，您可以在 [保留扫描](/docs/zh-CN/claude-directory#cleaned-up-automatically) 删除它们之前恢复这些文件。一旦您的组织重新打开 Skills，Claude Code 会在下次同步时下载您启用的技能。

228 229

229<h4 id="when-a-synced-skill-name-matches-another-command">230<h4 id="when-a-synced-skill-name-matches-another-command">

230 当同步的 skill 名称与另一个命令匹配时231 当同步的技能名称与另一个命令匹配时

231</h4>232</h4>

232 233

233Claude Code 跳过名称与任何其他命令匹配的同步 skill，并运行该其他命令。其他命令可以是内置命令、[捆绑 skill](#bundled-skills)、任何[本地级别](#where-skills-live)的 skill、插件 skill、`.claude/commands/` 中的文件或[MCP 提示](/docs/zh-CN/mcp#use-mcp-prompts-as-commands)。Claude Code 还保留其自己的内置命令和捆绑 skills 的名称，即使它们在您的会话中不可用，例如在您关闭捆绑 skills 后，因此它跳过具有这些名称之一的同步 skill。234您可以通过其完整名称 `/anthropic-skills:<name>` 或其短名称 `/<name>` 调用同步的技能。当另一个命令使用该短名称时，`/<name>` 运行其他命令，同步的技能仅作为 `/anthropic-skills:<name>` 运行。使用本地 `deploy` 技能和同步的 `deploy`，`/deploy` 运行本地技能，`/anthropic-skills:deploy` 运行同步的技能。在 v2.1.269 之前，同步的技能仅有其短名称。

235

236其他命令可以是以下任何一个：

237

238* 内置命令或 [捆绑技能](#bundled-skills)，包括在您的会话中不可用的，例如在您关闭捆绑技能后

239* 任何 [本地级别](#where-skills-live) 的技能或 `.claude/commands/` 中的文件

240* 插件技能

241* [MCP 提示](/docs/zh-CN/mcp#use-mcp-prompts-as-commands)

234 242

235Claude Code 标记同步 skills，以便您可以告诉它们来自何处。`/skills` 菜单和 `/context` 在 `claude.ai sync` 下分组同步 skills，`/` 命令菜单将它们标记为来自 claude.ai。243Claude Code 标记同步的技能，以便您可以看出它们来自哪里。`/skills` 菜单和 `/context` 在 `claude.ai sync` 下分组同步的技能，`/` 命令菜单将它们标记为来自 claude.ai。

236 244

237比较名称时，Claude Code 忽略大小写、间距和不可见字符，并将兼容性形式（如全宽字母和破折号变体）视为其纯等效形式，因此同步的 `Commit` 无法与本地 `commit` 并排加载。仅因来自另一个字母表的相似字母而不同的名称计为不同的名称，`claude.ai sync` 标签是您区分两者的方式。这些检查和标签需要 Claude Code v2.1.228 或更高版本。245比较名称时，Claude Code 忽略大小写、间距和不可见字符，并将兼容性形式（如全宽字母和破折号变体）视为其纯等效形式。例如，名为 `Commit` 的同步技能和名为 `commit` 的本地技能计为相同名称，因此 `/commit` 继续运行您的本地技能。

246

247仅因来自另一个字母表的相似字母而不同的名称计为不同名称，`claude.ai sync` 标签是您区分两者的方式。这些检查和标签需要 Claude Code v2.1.228 或更高版本。

238 248

239<h4 id="how-claude-code-handles-the-frontmatter-of-a-synced-skill">249<h4 id="how-claude-code-handles-the-frontmatter-of-a-synced-skill">

240 Claude Code 如何处理同步 skill 的前置元数据250 Claude Code 如何处理同步技能的 frontmatter

241</h4>251</h4>

242 252

243Claude Code 对同步 skill 的前置元数据应用两个规则：253Claude Code 对同步技能的 frontmatter 应用两条规则：

244 254

245* Claude Code 在每种会话中都遵守前置元数据，因此 `allowed-tools` 授予通过正常[权限流](/docs/zh-CN/permissions)。255* Claude Code 在每种会话中都遵守 frontmatter，因此 `allowed-tools` 授予通过正常的 [权限流](/docs/zh-CN/permissions)。

246* Claude Code 清理 skill 提供的显示文本，例如其描述。它删除控制字符，在到达 Claude 的文本（如描述）中，它还转义角括号，以便文本无法模仿 Claude Code 的内部格式。这种清理需要 Claude Code v2.1.228 或更高版本。256* Claude Code 清理技能提供的显示文本，例如其描述。它删除控制字符，在到达 Claude 的文本（如描述）中，它还转义尖括号，以便文本无法模仿 Claude Code 的内部格式。此清理需要 Claude Code v2.1.228 或更高版本。

247 257

248<h4 id="how-claude-code-handles-the-body-of-a-synced-skill">258<h4 id="how-claude-code-handles-the-body-of-a-synced-skill">

249 Claude Code 如何处理同步 skill 的正文259 Claude Code 如何处理同步技能的正文

250</h4>260</h4>

251 261

252Claude Code 对同步 skill 的正文的处理取决于会话运行的位置：262Claude Code 对同步技能的正文的处理取决于会话运行的位置：

253 263

254* 在云会话中，正文保持本地 skill 具有的行为，因为会话在隔离容器中运行。264* 在云会话中，正文保持本地技能具有的行为，因为会话在隔离容器中运行。

255* 在您桌面上的 Cowork 会话中，正文保持本地 skill 具有的行为，除了 Claude Code 将每个 `!` 命令行替换为[`disableSkillShellExecution` 占位符](#inject-dynamic-context)，就像它对您在那里提供的每个 skill 所做的那样。265* 在您桌面上的 Cowork 会话中，正文保持本地技能具有的行为，除了 Claude Code 将每个 `!` 命令行替换为 [`disableSkillShellExecution` 占位符](#inject-dynamic-context)，就像它对您在那里提供的每个技能所做的那样。

256* 在您机器上的任何其他会话中，Claude Code 不运行[`!` 命令](#inject-dynamic-context)，不附加 `@` 引用命名的文件（就像它对本地 skill 所做的那样），不替换 `${CLAUDE_PROJECT_DIR}` 和 `${CLAUDE_SESSION_ID}` 占位符，因此 `@` 引用和两个占位符都作为文字文本到达 Claude。`!` 命令行也作为文字文本到达 Claude，或当 `disableSkillShellExecution` 打开时作为该占位符。这种处理需要 Claude Code v2.1.228 或更高版本。266* 在您机器上的任何其他会话中，Claude Code 不运行 [`!` 命令](#inject-dynamic-context)，不附加 `@` 引用命名的文件，就像它对本地技能所做的那样，不替换 `${CLAUDE_PROJECT_DIR}` 和 `${CLAUDE_SESSION_ID}` 占位符，因此 `@` 引用和两个占位符都作为文字文本到达 Claude。`!` 命令行也作为文字文本到达 Claude，或当 `disableSkillShellExecution` 打开时作为该占位符。此处理需要 Claude Code v2.1.228 或更高版本。

257 267

258<h3 id="live-change-detection">268<h3 id="live-change-detection">

259 在会话期间编辑 skill269 在会话期间编辑技能

260</h3>270</h3>

261 271

262Claude 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，以便它可以监视新目录。272Claude Code 监视技能目录的文件更改，除了在 [bare mode](/docs/zh-CN/headless#start-faster-with-bare-mode) 中。当您在 `~/.claude/skills/`、项目 `.claude/skills/` 或 `--add-dir` 目录内的 `.claude/skills/` 下添加、编辑或删除技能时，Claude Code 在当前会话中获取更改，无需重新启动。如果您创建了会话启动时不存在的顶级技能目录，请重新启动 Claude Code，以便它可以监视新目录。

263 273

264实时更改检测仅涵盖 `SKILL.md` 文本。对于也是[插件](/docs/zh-CN/plugins-reference#skills-directory-plugins)的 skill 文件夹，对 `hooks/`、`.mcp.json`、`agents/` 和 `output-styles/` 的更改需要 `/reload-plugins` 才能生效。274实时更改检测仅涵盖 `SKILL.md` 文本。对于也是 [插件](/docs/zh-CN/plugins-reference#skills-directory-plugins) 的技能文件夹，对 `hooks/`、`.mcp.json`、`agents/` 和 `output-styles/` 的更改需要 `/reload-plugins` 才能生效。

265 275

266<h3 id="remove-a-skill">276<h3 id="remove-a-skill">

267 删除 skill277 删除技能

268</h3>278</h3>

269 279

270删除 skill 的方式取决于它来自何处：280删除技能的方式取决于它来自哪里：

271 281

272* **Personal 或 project skill**：删除 skill 的目录，`~/.claude/skills/<skill-name>/` 或 `.claude/skills/<skill-name>/`。Claude Code [在当前会话中从 `/skills` 中删除它](#live-change-detection)；Claude Code 已从中加载的内容遵循[skill 内容生命周期](#skill-content-lifecycle)。282* **Personal 或 project 技能**：删除技能的目录，`~/.claude/skills/<skill-name>/` 或 `.claude/skills/<skill-name>/`。Claude Code [在当前会话中从 `/skills` 中删除它](#live-change-detection)；Claude Code 已从中加载的内容遵循 [技能内容生命周期](#skill-content-lifecycle)。

273* **Enterprise skill**：管理员从[托管设置目录](/docs/zh-CN/managed-settings#delivery-mechanisms)内的 `.claude/skills/` 删除 skill 的目录，例如 Linux 上的 `/etc/claude-code/.claude/skills/<skill-name>/`。283* **Enterprise 技能**：管理员从 [托管设置目录](/docs/zh-CN/managed-settings#delivery-mechanisms) 内的 `.claude/skills/` 中删除技能的目录，例如 Linux 上的 `/etc/claude-code/.claude/skills/<skill-name>/`。

274* **Plugin skill**：从 `/plugin` 菜单禁用或卸载提供它的插件，或使用 `/plugin uninstall <plugin-name>@<marketplace-name>`。Claude Code 在[更改应用](/docs/zh-CN/discover-plugins#apply-plugin-changes-without-restarting)时或重新启动后卸载插件的 skills。284* **Plugin 技能**：从 `/plugin` 菜单禁用或卸载提供它的插件，或使用 `/plugin uninstall <plugin-name>@<marketplace-name>`。Claude Code 在 [更改应用](/docs/zh-CN/discover-plugins#apply-plugin-changes-without-restarting) 时或重新启动时卸载插件的技能。

275* **从 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 上保持启用时再次下载它。285* **从 claude.ai 同步的技能**：在您 [启用它](#skills-in-cowork-and-cloud-sessions) 的同一位置为您的 claude.ai 账户关闭该技能。Claude Code 在下次 [同步您的技能](#where-synced-skills-load) 时将其从 `~/.claude/skills/synced/` 中删除。如果您改为手动删除目录，下次同步会在技能在 claude.ai 上保持启用时再次下载它。

276* **捆绑 skill**：设置 [`disableBundledSkills`](#bundled-skills) 为 `true` 以关闭捆绑 skills，或在 [`skillOverrides`](#override-skill-visibility-from-settings) 中将一个 skill 设置为 `"off"` 以隐藏它。286* **Bundled 技能**：将 [`disableBundledSkills`](#bundled-skills) 设置为 `true` 以关闭捆绑技能，或在 [`skillOverrides`](#override-skill-visibility-from-settings) 中将一个技能设置为 `"off"` 以隐藏它。

277 287

278要保留 personal 或 project skill 但阻止 Claude 自动调用它，在其前置元数据中设置 [`disable-model-invocation: true`](#control-who-invokes-a-skill)，或在 [`skillOverrides`](#override-skill-visibility-from-settings) 中设置 `"user-invocable-only"`（当您不想编辑文件时）。288要保留个人或项目技能但阻止 Claude 自动调用它，请在其 frontmatter 中设置 [`disable-model-invocation: true`](#control-who-invokes-a-skill)，或在 [`skillOverrides`](#override-skill-visibility-from-settings) 中设置 `"user-invocable-only"`，当您不想编辑文件时。

279 289

280<h2 id="configure-skills">290<h2 id="configure-skills">

281 配置 skills291 配置 skills

360| `context` | 否 | 设置为 `fork` 以在分叉子代理上下文中运行。请参阅[在子代理中运行 skills](#run-skills-in-a-subagent)。 |370| `context` | 否 | 设置为 `fork` 以在分叉子代理上下文中运行。请参阅[在子代理中运行 skills](#run-skills-in-a-subagent)。 |

361| `agent` | 否 | 设置 `context: fork` 时要使用的子代理类型。 |371| `agent` | 否 | 设置 `context: fork` 时要使用的子代理类型。 |

362| `background` | 否 | 仅适用于 `context: fork`。设置为 `false` 以在调用 skill 的回合中等待分叉子代理的结果，而不是[在后台运行它](#run-skills-in-a-subagent)。默认值：`true`。需要 Claude Code v2.1.218 或更高版本。 |372| `background` | 否 | 仅适用于 `context: fork`。设置为 `false` 以在调用 skill 的回合中等待分叉子代理的结果，而不是[在后台运行它](#run-skills-in-a-subagent)。默认值：`true`。需要 Claude Code v2.1.218 或更高版本。 |

363| `hooks` | 否 | Claude Code 在调用 skill 时注册并在会话的其余部分保持运行的 hooks。请参阅[skills 和代理中的 Hooks](/docs/zh-CN/hooks#hooks-in-skills-and-agents)以了解配置格式和 `once` 选项。 |373| `hooks` | 否 | Claude Code 在调用 skill 时注册并在会话的其余部分保持运行的 hooks。请参阅[skills 和代理中的 hooks](/docs/zh-CN/hooks#hooks-in-skills-and-agents)以了解配置格式和 `once` 选项。 |

364| `paths` | 否 | 限制何时激活此 skill 的 Glob 模式。接受以逗号分隔的字符串或 YAML 列表。设置后，Claude 仅在处理与模式匹配的文件时自动加载该 skill。使用与[路径特定规则](/docs/zh-CN/memory#path-specific-rules)相同的格式。 |374| `paths` | 否 | 限制何时激活此 skill 的 Glob 模式。接受以逗号分隔的字符串或 YAML 列表。设置后，Claude 仅在处理与模式匹配的文件时自动加载该 skill。使用与[路径特定规则](/docs/zh-CN/memory#path-specific-rules)相同的格式。 |

365| `shell` | 否 | 用于此 skill 中的 `` !`command` `` 和 ` ```! ` 块的 shell。接受 `bash`（默认）或 `powershell`。设置 `powershell` 在启用[PowerShell 工具](/zh-CN/tools-reference#powershell-tool)时通过 PowerShell 运行内联 shell 命令：在没有 Git Bash 的 Windows 上默认启用，在带有 Git Bash 的 claude.ai 和 Console 帐户上默认启用，在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 会话以及 macOS、Linux 和 WSL 上需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。设置为 `0` 以关闭工具。 |375| `shell` | 否 | 用于此 skill 中的 `` !`command` `` 和 ` ```! ` 块的 shell。接受 `bash`（默认）或 `powershell`。设置 `powershell` 在启用[PowerShell 工具](/zh-CN/tools-reference#powershell-tool)时通过 PowerShell 运行内联 shell 命令：在没有 Git Bash 的 Windows 上默认启用，在带有 Git Bash 的 claude.ai 和 Console 帐户上默认启用，在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 会话以及 macOS、Linux 和 WSL 上需要 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`。设置为 `0` 以关闭工具。 |

366| `metadata` | 否 | 用于你自己的键值数据的自由格式 YAML 映射，例如权利或目录字段，由你自己的工具从 `SKILL.md` 读取。Claude Code 不对其内容进行操作，并删除不是映射的值。不要重用 frontmatter 字段名称（如 `paths`）作为键。 |376| `metadata` | 否 | 用于你自己的键值数据的自由格式 YAML 映射，例如权利或目录字段，由你自己的工具从 `SKILL.md` 读取。Claude Code 不对其内容进行操作，并删除不是映射的值。不要重用 frontmatter 字段名称（如 `paths`）作为键。 |

406| 插件根 `SKILL.md` | Frontmatter `name`，以插件目录名称作为后备 | `my-plugin/SKILL.md` 带有 `name: review` → `/my-plugin:review`。请参阅[路径行为规则](/docs/zh-CN/plugins-reference#path-behavior-rules) |416| 插件根 `SKILL.md` | Frontmatter `name`，以插件目录名称作为后备 | `my-plugin/SKILL.md` 带有 `name: review` → `/my-plugin:review`。请参阅[路径行为规则](/docs/zh-CN/plugins-reference#path-behavior-rules) |

417| 从 claude.ai [同步的 skill](#how-synced-skills-behave) | 你的 claude.ai 帐户上 skill 的名称，前缀为 `anthropic-skills:` | 帐户 skill `deploy` → `/anthropic-skills:deploy`，或在没有其他命令使用该名称时为 `/deploy` |

407 418

408在插件 skill 中，frontmatter `name` 替换命令最后一段中的目录名称，因此 `my-plugin/skills/review/SKILL.md` 带有 `name: fancy` 变为 `/my-plugin:fancy`。裸 `/fancy` 也调用该 skill，除非另一个命令已使用该名称。如果你写的 `name` 已经以插件自己的前缀开头，Claude Code 在 v2.1.246 或更高版本上不会再次添加前缀。例如，`name: my-plugin:fancy` 仍然变为 `/my-plugin:fancy`。从 v2.1.216 到 v2.1.245，当 `name` 已经携带前缀时，Claude Code 会加倍前缀。419在插件 skill 中，frontmatter `name` 替换命令最后一段中的目录名称，因此 `my-plugin/skills/review/SKILL.md` 带有 `name: fancy` 变为 `/my-plugin:fancy`。裸 `/fancy` 也调用该 skill，除非另一个命令已使用该名称。如果你写的 `name` 已经以插件自己的前缀开头，Claude Code 在 v2.1.246 或更高版本上不会再次添加前缀。例如，`name: my-plugin:fancy` 仍然变为 `/my-plugin:fancy`。从 v2.1.216 到 v2.1.245，当 `name` 已经携带前缀时，Claude Code 会加倍前缀。

409 420

410在[非交互式会话](/docs/zh-CN/headless)中，名称 `help` 和 `feedback` 不是为其仅限终端的内置命令保留的，因此具有其中一个名称的插件 skill 在那里保持其裸命令。每个其他仅限终端的内置命令的名称（如 `/login`）即使该命令无法在这些会话中运行，仍然保留。同步的名为 `help` 或 `feedback` 的 skill 仍然在那里被跳过，因为 Claude Code[跳过同步 skill](#when-a-synced-skill-name-matches-another-command)，其名称与任何内置命令匹配，无论该命令是否可以运行。421在[非交互式会话](/docs/zh-CN/headless)中，名称 `help` 和 `feedback` 不是为其仅限终端的内置命令保留的，因此具有其中一个名称的插件 skill 在那里保持其裸命令。每个其他仅限终端的内置命令的名称（如 `/login`）即使该命令无法在这些会话中运行，仍然保留。

411 422

412对于插件根 `SKILL.md`，没有 skill 目录来获取名称，因此 `name` 提供整个最后一段。没有 `name` 字段，Claude Code 回退到插件的目录名称。423对于插件根 `SKILL.md`，没有 skill 目录来获取名称，因此 `name` 提供整个最后一段。没有 `name` 字段，Claude Code 回退到插件的目录名称。

413 424

709 720

710使用默认的 `bash` shell，将 `|| true` 附加到任何你期望退出非零的其他命令。一个在发现问题时退出 1 的检查脚本就是一个例子。721使用默认的 `bash` shell，将 `|| true` 附加到任何你期望退出非零的其他命令。一个在发现问题时退出 1 的检查脚本就是一个例子。

711 722

712注入命令永远不会提示权限。当命令的权限检查返回除允许之外的任何内容时，Claude Code 中止调用。这包括通常会询问你的规则。中止显示 `Shell command permission check failed for pattern "..."`。723<h4 id="permission-checks-on-injected-commands">

724 注入命令的权限检查

725</h4>

726

727注入命令在技能呈现时永远不会提示权限。Claude Code 首先根据你的[权限规则](/docs/zh-CN/permissions)检查每一个。命令与拒绝规则匹配的命令会中止调用，显示 `Shell command permission check failed for pattern "..."`。

728

729在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)之外，当命令的权限检查返回除允许之外的任何内容时，Claude Code 会中止调用。这包括通常会询问你的规则。要防止不匹配的命令在此处中止，请使用 [`allowed-tools`](#pre-approve-tools-for-a-skill) 预先批准它。拒绝和询问规则仍然会覆盖 `allowed-tools`。请参阅[管理权限](/docs/zh-CN/permissions#manage-permissions)。

713 730

714要防止不匹配的命令在此处中止，请使用 [`allowed-tools`](#pre-approve-tools-for-a-skill) 预先批准它。匹配的询问或拒绝规则仍然会中止调用，无论 `allowed-tools` 如何。请参阅[管理权限](/docs/zh-CN/permissions#manage-permissions)。731在自动模式中，原本需要你批准的命令不会中止调用。技能加载时带有指令，告诉 Claude 首先运行该命令，然后 Claude 自己的调用通过[自动模式的常规检查](/docs/zh-CN/permission-modes#how-the-classifier-evaluates-actions)。调用仍然会在[分叉技能](#run-skills-in-a-subagent)中中止，该技能设置 `agent`，以及在 Claude 没有[运行注入命令的 shell 工具](#how-injected-commands-run)的会话中。

715 732

716<h3 id="run-skills-in-a-subagent">733<h3 id="run-skills-in-a-subagent">

717 在子代理中运行技能734 在子代理中运行技能

743技能和[子代理](/docs/zh-CN/sub-agents)在两个方向上协同工作：760技能和[子代理](/docs/zh-CN/sub-agents)在两个方向上协同工作：

744 761

745| 方法 | 系统提示 | 任务 | 也加载 |762| 方法 | 系统提示 | 任务 | 也加载 |

746| :--------------------- | :--------------- | :----------- | :----------------------------- |763| :--------------------- | :--------------- | :----------- | :------------------------------------------------------------------------ |

749 766

750使用 `context: fork`，你在你的技能中编写任务并选择一个代理类型来执行它。内置的 Explore 和 Plan 代理[跳过 CLAUDE.md 和 git 状态](/docs/zh-CN/sub-agents#what-loads-at-startup)以保持其上下文较小，因此使用 `agent: Explore` 的分叉技能仅看到 SKILL.md 内容和代理自己的系统提示。对于相反的情况，你定义一个使用技能作为参考材料的自定义子代理，请参阅[子代理](/docs/zh-CN/sub-agents#preload-skills-into-subagents)。767使用 `context: fork`，你在你的技能中编写任务并选择一个代理类型来执行它。内置的 Explore 和 Plan 代理[跳过 CLAUDE.md 和 git 状态](/docs/zh-CN/sub-agents#what-loads-at-startup)以保持其上下文较小，因此使用 `agent: Explore` 的分叉技能仅看到 SKILL.md 内容和代理自己的系统提示。对于相反的情况，你定义一个使用技能作为参考材料的自定义子代理，请参阅[子代理](/docs/zh-CN/sub-agents#preload-skills-into-subagents)。

751 768

slack.md +18 −18

Details

13 * **Pro 和 Max 计划：** Claude Tag 在个人计划上不可用，因此本页面仍然是设置路径。13 * **Pro 和 Max 计划：** Claude Tag 在个人计划上不可用，因此本页面仍然是设置路径。

14</Warning>14</Warning>

15 15

16Slack 中的 Claude Code 将 Claude Code 的强大功能直接引入您的 Slack 工作区。当您使用编码任务提及 `@Claude` 时，Claude 会自动检测意图并在网络上创建 Claude Code 会话，允许您在不离开团队对话的情况下委派开发工作。16Slack 中的 Claude Code 将 Claude Code 的强大功能直接引入您的 Slack 工作区。当您使用编码任务提及 `@Claude` 时，Claude 会自动检测意图并创建 Claude Code 云会话，允许您在不离开团队对话的情况下委派开发工作。

17 17

18此集成基于现有的 Claude for Slack 应用程序构建，但为与编码相关的请求添加了到网络上 Claude Code 的智能路由。每个会话在您自己的 Claude 账户下运行，使用您连接的存储库和您的计划限制。18此集成基于现有的 Claude for Slack 应用程序构建，但为与编码相关的请求添加了到 Claude Code 云会话的智能路由。每个会话在您自己的 Claude 账户下运行，使用您连接的存储库和您的计划限制。

19 19

20<h2 id="use-cases">20<h2 id="use-cases">

21 用例21 用例

33在使用 Slack 中的 Claude Code 之前，请确保您具有以下条件：33在使用 Slack 中的 Claude Code 之前，请确保您具有以下条件：

34 34

35| 要求 | 详情 |35| 要求 | 详情 |

~~36| :--------------- | :------------------------------------------------------------------------- |~~36| :-------- | :------------------------------------------------------------------------- |

37| Claude 计划 | Pro、Max、Team 或 Enterprise，具有 Claude Code 访问权限（高级席位或 Chat + Claude Code 席位） |37| Claude 计划 | Pro、Max、Team 或 Enterprise，具有 Claude Code 访问权限（高级席位或 Chat + Claude Code 席位） |

~~38| 网络上的 Claude Code | 必须启用对[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)的访问 |~~38| 云会话 | [云会话](/docs/zh-CN/claude-code-on-the-web)已为您的账户启用 |

~~39| GitHub 账户 | 连接到网络上的 Claude Code，至少有一个存储库已认证 |~~39| GitHub 账户 | 在 [claude.ai/code](https://claude.ai/code) 连接，至少有一个存储库已认证 |

40| Slack 认证 | 您的 Slack 账户通过 Claude 应用程序链接到您的 Claude 账户 |40| Slack 认证 | 您的 Slack 账户通过 Claude 应用程序链接到您的 Claude 账户 |

41 41

42<h2 id="setting-up-claude-code-in-slack">42<h2 id="setting-up-claude-code-in-slack">

52 安装应用程序后，认证您的个人 Claude 账户：52 安装应用程序后，认证您的个人 Claude 账户：

53 53

54 1. 通过单击您的应用程序部分中的"Claude"在 Slack 中打开 Claude 应用程序54 1. 通过单击您的应用程序部分中的"Claude"在 Slack 中打开 Claude 应用程序

~~55 2. 导航到应用程序主页选项卡~~55 2. 打开应用程序主页选项卡

56 3. 单击"Connect"将您的 Slack 账户与您的 Claude 账户链接56 3. 单击"Connect"将您的 Slack 账户与您的 Claude 账户链接

57 4. 在浏览器中完成认证流程57 4. 在浏览器中完成认证流程

58 </Step>58 </Step>

59 59

~~60 <Step title="配置网络上的 Claude Code">~~60 <Step title="配置云会话">

~~61 确保您网络上的 Claude Code 已正确配置：~~61 确保为您的账户正确配置云会话：

62 62

63 * 访问 [claude.ai/code](https://claude.ai/code) 并使用您连接到 Slack 的同一账户登录63 * 访问 [claude.ai/code](https://claude.ai/code) 并使用您连接到 Slack 的同一账户登录

64 * 如果尚未连接，请连接您的 GitHub 账户64 * 如果尚未连接，请连接您的 GitHub 账户

66 </Step>66 </Step>

67 67

68 <Step title="选择您的路由模式">68 <Step title="选择您的路由模式">

~~69 连接您的账户后，配置 Claude 如何在 Slack 中处理您的消息。导航到 Slack 中的 Claude 应用程序主页以找到**路由模式**设置。~~69 连接您的账户后，配置 Claude 如何在 Slack 中处理您的消息。打开 Slack 中的 Claude 应用程序主页以找到**路由模式**设置。

70 70

71 | 模式 | 行为 |71 | 模式 | 行为 |

72 | :---------- | :---------------------------------------------------------------------------------------------------- |72 | :---------- | :---------------------------------------------------------------------------------------------------- |

91 自动检测91 自动检测

92</h3>92</h3>

93 93

94在 Code + Chat 路由模式下，当您在 Slack 频道或线程中提及 @Claude 时，Claude 会自动检测您的消息是否是编码任务。编码任务会被发送到网络上的 Claude Code。其他任何内容都会获得常规聊天回复。在仅 Code 模式下，每个 @mention 都会发送到 Claude Code。94在 Code + Chat 路由模式下，当您在 Slack 频道或线程中提及 @Claude 时，Claude 会自动检测您的消息是否是编码任务。编码任务会被发送到 Claude Code 云会话。其他任何内容都会获得常规聊天回复。在仅 Code 模式下，每个 @mention 都会发送到 Claude Code。

95 95

96您也可以明确告诉 Claude 将请求作为编码任务处理，即使它没有自动检测到。96您也可以明确告诉 Claude 将请求作为编码任务处理，即使它没有自动检测到。

97 97

182 182

183**在 Slack 中**：您将看到状态更新、完成摘要和操作按钮。完整记录被保留并始终可访问。183**在 Slack 中**：您将看到状态更新、完成摘要和操作按钮。完整记录被保留并始终可访问。

184 184

185**在网络上**：完整的 Claude Code 会话，包含完整的对话历史、所有代码更改和文件操作。会话保存在您的 Claude Code 历史记录中，位于 [claude.ai/code](https://claude.ai/code)，您可以在那里继续过去的会话、参考它们或创建拉取请求。185**在 claude.ai/code**：完整的 Claude Code 会话，包含完整的对话历史、所有代码更改和文件操作。会话保存在您的 Claude Code 历史记录中，位于 [claude.ai/code](https://claude.ai/code)，您可以在那里继续过去的会话、参考它们或创建拉取请求。

186 186

187对于 Enterprise 和 Team 账户，从 Slack 中的 Claude 创建的会话会自动对组织可见。有关更多详情，请参阅 [Claude Code 网络共享](/docs/zh-CN/claude-code-on-the-web#share-sessions)。187对于 Enterprise 和 Team 账户，从 Slack 中的 Claude 创建的会话会自动对组织可见。有关更多详情，请参阅 [云会话共享](/docs/zh-CN/claude-code-on-the-web#share-sessions)。

188 188

189<h2 id="best-practices">189<h2 id="best-practices">

190 最佳实践190 最佳实践

196 196

197* **具体说明**：在相关时包括文件名、函数名或错误消息。197* **具体说明**：在相关时包括文件名、函数名或错误消息。

198* **提供上下文**：如果从对话中不清楚，请提及存储库或项目。198* **提供上下文**：如果从对话中不清楚，请提及存储库或项目。

199* **定义成功**：解释"完成"的样子——Claude 应该编写测试吗？更新文档？创建 PR？199* **定义成功**：解释"完成"的样子。Claude 应该编写测试吗？更新文档？创建 PR？

200* **使用线程**：在讨论 Bug 或功能时在线程中回复，以便 Claude 可以收集完整的上下文。200* **使用线程**：在讨论 Bug 或功能时在线程中回复，以便 Claude 可以收集完整的上下文。

201 201

202<h3 id="when-to-use-slack-vs-web">202<h3 id="when-to-use-slack-vs-web">

222</h3>222</h3>

223 223

2241. 验证您的 Claude 账户在 Claude 应用程序主页中已连接2241. 验证您的 Claude 账户在 Claude 应用程序主页中已连接

2252. 检查您是否启用了网络上的 Claude Code 访问权限2252. 检查您的账户是否启用了云会话

2263. 确保您至少有一个 GitHub 存储库连接到 Claude Code2263. 确保您至少有一个 GitHub 存储库连接到 Claude Code

227 227

228<h3 id="sessions-from-a-claude-tag-channel-fail-to-start">228<h3 id="sessions-from-a-claude-tag-channel-fail-to-start">

242 存储库未显示242 存储库未显示

243</h3>243</h3>

244 244

2451. 在 [claude.ai/code](https://claude.ai/code) 的网络上的 Claude Code 中连接存储库2451. 在 [claude.ai/code](https://claude.ai/code) 连接存储库

2462. 验证您对该存储库的 GitHub 权限2462. 验证您对该存储库的 GitHub 权限

2473. 尝试断开并重新连接您的 GitHub 账户2473. 尝试断开并重新连接您的 GitHub 账户

248 248

267 267

268* **仅 GitHub**：存储库必须在 GitHub 上。268* **仅 GitHub**：存储库必须在 GitHub 上。

269* **一次一个 PR**：每个会话可以创建一个拉取请求。269* **一次一个 PR**：每个会话可以创建一个拉取请求。

270* **需要网络访问**：用户需要访问网络上的 Claude Code；没有访问权限的用户，Claude 将回复标准聊天响应。270* **需要云会话访问**：用户需要访问[云会话](/docs/zh-CN/claude-code-on-the-web)；没有访问权限的用户，Claude 将回复标准聊天响应。

271 271

272<h2 id="related-resources">272<h2 id="related-resources">

273 相关资源273 相关资源

274</h2>274</h2>

275 275

276<CardGroup>276<CardGroup>

277 <Card title="网络上的 Claude Code" icon="globe" href="/docs/zh-CN/claude-code-on-the-web">277 <Card title="云端 Claude Code" icon="cloud" href="/docs/zh-CN/claude-code-on-the-web">

278 了解有关网络上的 Claude Code 的更多信息278 了解有关云端会话的更多信息

279 </Card>279 </Card>

280 280

281 <Card title="Claude for Slack" icon="slack" href="https://claude.com/claude-and-slack">281 <Card title="Claude for Slack" icon="slack" href="https://claude.com/claude-and-slack">

statusline.md +14 −14

Details

86 逐步构建状态行86 逐步构建状态行

87</h2>87</h2>

88 88

~~89本演练展示了通过手动创建显示当前模型、工作目录和上下文窗口使用百分比的状态行来了解幕后发生的情况。~~89本演练展示了 `/statusline` 为你设置的内容，通过手动创建显示当前模型、工作目录和上下文窗口使用百分比的状态行。

90 90

91<Note>使用[`/statusline`](#use-the-%2Fstatusline-command)和你想要的内容的描述会自动为你配置所有这些。</Note>91<Note>使用[`/statusline`](#use-the-%2Fstatusline-command)和你想要的内容的描述会自动为你配置所有这些。</Note>

92 92

192| `workspace.git_worktree` | 当前目录在使用 `git worktree add` 创建的链接 worktree 内时的 Git worktree 名称。在主工作树中不存在。对于任何 git worktree 都会填充，不同于仅在[worktree 会话](/docs/zh-CN/worktrees)期间出现的 `worktree.*` |192| `workspace.git_worktree` | 当前目录在使用 `git worktree add` 创建的链接 worktree 内时的 Git worktree 名称。在主工作树中不存在。对于任何 git worktree 都会填充，不同于仅在 [worktree 会话](/docs/zh-CN/worktrees) 期间出现的 `worktree.*` |

193| `workspace.repo.host`, `workspace.repo.owner`, `workspace.repo.name` | 从 `origin` 远程解析的存储库标识，例如 `"github.com"`、`"anthropics"`、`"claude-code"`。在 git 存储库外或未配置 `origin` 远程时不存在。对于嵌套在子组中的 gitlab.com 项目，`owner` 是带有斜杠的完整命名空间路径，例如 `"group/subgroup"`。在 v2.1.260 之前，这些项目的 `workspace.repo` 不存在 |193| `workspace.repo.host`, `workspace.repo.owner`, `workspace.repo.name` | 从 `origin` 远程解析的存储库标识，例如 `"github.com"`、`"anthropics"`、`"claude-code"`。在 git 存储库外或未配置 `origin` 远程时不存在。对于嵌套在子组中的 gitlab.com 项目，`owner` 是带有斜杠的完整命名空间路径，例如 `"group/subgroup"`。在 v2.1.260 之前，这些项目的 `workspace.repo` 不存在 |

194| `cost.total_cost_usd` | 以美元计的估计会话成本，在客户端按列表价格计算，除非有 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing) 表生效。可能与你的实际账单不同。当 `/clear` 启动新会话时重置为 \$0。在 v2.1.211 之前，总计在 `/clear` 后继续累积 |194| `cost.total_cost_usd` | 以美元计的估计会话成本，在客户端按列表价格计算，除非有 [`modelPricing`](/docs/zh-CN/settings-reference#modelpricing) 表生效。可能与你的实际账单不同。当 `/clear` 启动新会话时重置为 \$0。在 v2.1.211 之前，总计在 `/clear` 后继续累积 |

205| `effort.level` | 当前推理工作量（`low`、`medium`、`high`、`xhigh` 或 `max`）。反映实时会话值，包括中途 `/effort` 更改。Ultracode 不是一个独立的级别，报告为 `xhigh`。当当前模型不支持工作量参数时不存在 |205| `effort.level` | 当前推理工作量（`low`、`medium`、`high`、`xhigh` 或 `max`）。反映实时会话值，包括中途 `/effort` 更改。Ultracode 不是一个独立的级别，报告为 `xhigh`。当当前模型不支持工作量参数时不存在 |

210| `prompt_cache` | 会话的主对话的 [prompt cache](/docs/zh-CN/prompt-caching) 统计信息：命中率、未命中次数以及缓存是否预热。有关每个字段，请参阅 [prompt cache 字段](#prompt-cache-fields)。在主对话的第一次 API 响应之前不存在。需要 Claude Code v2.1.251 或更高版本 |210| `prompt_cache` | 会话的主对话的 [prompt cache](/docs/zh-CN/prompt-caching) 统计信息：命中率、未命中次数以及缓存是否预热。有关每个字段，请参阅 [prompt cache 字段](#prompt-cache-fields)。在主对话的第一次 API 响应之前不存在。需要 Claude Code v2.1.251 或更高版本 |

212| `session_name` | 会话名称。使用使用 `--name` 标志或 `/rename` 设置的自定义名称（如果存在），否则使用 AI 生成的会话标题。[默认显示名称](/docs/zh-CN/sessions#name-your-sessions)（例如 `my-app-3f`）不会填充此字段。当会话既没有自定义名称也没有 AI 生成的标题时不存在 |212| `session_name` | 会话名称。使用使用 `--name` 标志或 `/rename` 设置的自定义名称（如果存在），否则使用 AI 生成的会话标题。[默认显示名称](/docs/zh-CN/sessions#name-your-sessions)（例如 `my-app-3f`）不会填充此字段。当会话既没有自定义名称也没有 AI 生成的标题时不存在 |

213| `prompt_id` | 标识当前正在处理的用户提示的 UUID。与 OpenTelemetry 事件上的 [`prompt.id` 属性](/docs/zh-CN/monitoring-usage#event-correlation-attributes)匹配。在第一次用户输入之前不存在。需要 Claude Code v2.1.196 或更高版本 |213| `prompt_id` | 标识当前正在处理的用户提示的 UUID。与 OpenTelemetry 事件上的 [`prompt.id` 属性](/docs/zh-CN/monitoring-usage#event-correlation-attributes) 匹配。在第一次用户输入之前不存在。需要 Claude Code v2.1.196 或更高版本 |

219| `pr.number`, `pr.url` | 当前分支的开放拉取请求。镜像底部状态栏中的 PR 徽章。在具有 GitLab 远程的存储库中，Claude Code 从分支的开放 [merge request](/docs/zh-CN/interactive-mode#gitlab-merge-requests) 填充这些字段，因此 `pr.number` 是 merge request 编号。Merge request 数据需要 Claude Code v2.1.234 或更高版本。当不在 git 存储库中、找到拉取请求或 merge request 之前，或一旦它合并或关闭后不存在 |219| `pr.number`, `pr.url` | 当前分支的开放拉取请求。镜像底部状态栏中的 PR 徽章。在具有 GitLab 远程的存储库中，Claude Code 从分支的开放 [merge request](/docs/zh-CN/interactive-mode#gitlab-merge-requests) 填充这些字段，因此 `pr.number` 是 merge request 编号。Merge request 数据需要 Claude Code v2.1.234 或更高版本。当不在 git 存储库中、找到拉取请求或 merge request 之前，或一旦它合并或关闭后不存在 |

221| `pr.kind` | 当 `pr` 描述 [GitLab merge request](/docs/zh-CN/interactive-mode#gitlab-merge-requests) 时为 `mr`。对于 GitHub 拉取请求不存在，因此在此字段之前编写的脚本继续工作。对于 merge request，当 GitLab 报告它可合并时，Claude Code 将 `review_state` 设置为 `approved`，对于任何其他开放状态设置为 `pending`，对于草稿设置为 `draft`。需要 Claude Code v2.1.234 或更高版本 |221| `pr.kind` | 当 `pr` 描述 [GitLab merge request](/docs/zh-CN/interactive-mode#gitlab-merge-requests) 时为 `mr`。对于 GitHub 拉取请求不存在，因此在此字段之前编写的脚本继续工作。对于 merge request，当 GitLab 报告它可合并时，Claude Code 将 `review_state` 设置为 `approved`，对于任何其他开放状态设置为 `pending`，对于草稿设置为 `draft`。需要 Claude Code v2.1.234 或更高版本 |

349 * `vim`：仅在启用 vim 模式时出现349 * `vim`：仅在启用 vim 模式时出现

350 * `agent`：仅在使用 `--agent` 标志或配置的代理设置运行时出现350 * `agent`：仅在使用 `--agent` 标志或配置的代理设置运行时出现

351 * `pr`：仅在为当前分支找到开放 PR 或 GitLab merge request 时出现，一旦它合并或关闭就会被移除。`pr.review_state` 和 `pr.kind` 可能独立不存在351 * `pr`：仅在为当前分支找到开放 PR 或 GitLab merge request 时出现，一旦它合并或关闭就会被移除。`pr.review_state` 和 `pr.kind` 可能独立不存在

352 * `worktree`：仅在[worktree 会话](/docs/zh-CN/worktrees)期间出现。当存在时，对于基于钩子的 worktree，`branch` 和 `original_branch` 也可能不存在352 * `worktree`：仅在 [worktree 会话](/docs/zh-CN/worktrees) 期间出现。当存在时，对于基于钩子的 worktree，`branch` 和 `original_branch` 也可能不存在

353 * `rate_limits`：仅对 Claude.ai Pro 和 Max 订阅者，或在为你设置支出限制的 Claude apps gateway 后面，以及仅在会话中第一次 API 响应后出现。每个窗口（`five_hour`、`seven_day`、`spend_limit`）可能独立不存在，Claude Code 在其 `resets_at` 时间过去后删除一个窗口。使用 `jq -r '.rate_limits.five_hour.used_percentage // empty'` 来优雅地处理缺失。353 * `rate_limits`：仅对 Claude.ai Pro 和 Max 订阅者，或在为你设置支出限制的 Claude apps gateway 后面，以及仅在会话中第一次 API 响应后出现。每个窗口（`five_hour`、`seven_day`、`spend_limit`）可能独立不存在，Claude Code 在其 `resets_at` 时间过去后删除一个窗口。使用 `jq -r '.rate_limits.five_hour.used_percentage // empty'` 来优雅地处理缺失。

354 * `prompt_cache`：在主对话的第一次 API 响应后出现。请参阅 [prompt cache 字段](#prompt-cache-fields)354 * `prompt_cache`：在主对话的第一次 API 响应后出现。请参阅 [prompt cache 字段](#prompt-cache-fields)

355 355

377* `cache_creation_input_tokens`：写入缓存的令牌377* `cache_creation_input_tokens`：写入缓存的令牌

378* `cache_read_input_tokens`：从缓存读取的令牌378* `cache_read_input_tokens`：从缓存读取的令牌

379 379

380有关缓存字段的含义以及它们如何计费的信息，请参阅[检查缓存性能](/docs/zh-CN/prompt-caching#check-cache-performance)。380有关缓存字段的含义以及它们如何计费的信息，请参阅 [检查缓存性能](/docs/zh-CN/prompt-caching#check-cache-performance)。

381 381

382`used_percentage` 字段仅从输入令牌计算：`input_tokens + cache_creation_input_tokens + cache_read_input_tokens`。它不包括 `output_tokens`。382`used_percentage` 字段仅从输入令牌计算：`input_tokens + cache_creation_input_tokens + cache_read_input_tokens`。它不包括 `output_tokens`。

383 383

396该表列出了每个字段及其含义。时间戳是 Unix 纪元秒，与 `rate_limits.*.resets_at` 相同的单位。短状态行通常显示其中一个或两个；`warm` 和 `hit_ratio` 最直接地总结缓存状态。396该表列出了每个字段及其含义。时间戳是 Unix 纪元秒，与 `rate_limits.*.resets_at` 相同的单位。短状态行通常显示其中一个或两个；`warm` 和 `hit_ratio` 最直接地总结缓存状态。

397 397

398| 字段 | 描述 |398| 字段 | 描述 |

399| ------------------------ | --------------------------------------------------------------------------------------------- |399| ------------------------ | ----------------------------------------------------------------------------------------------- |

402| `ttl` | 当前缓存前缀的[缓存生命周期](/docs/zh-CN/prompt-caching#cache-lifetime)：`"5m"` 或 `"1h"` |402| `ttl` | 当前缓存前缀的 [缓存生命周期](/docs/zh-CN/prompt-caching#cache-lifetime)：`"5m"` 或 `"1h"` |

414 414

415Claude Code 在终端上显示相同的统计信息，在 [`/usage` 命令的 `Prompt cache (main)` 行](/docs/zh-CN/costs#prompt-cache-statistics)上。415Claude Code 在终端上显示相同的统计信息，在 [`/usage` 命令的 `Prompt cache (main)` 行](/docs/zh-CN/costs#prompt-cache-statistics) 上。

416 416

417<h4 id="last-miss-cause">417<h4 id="last-miss-cause">

418 最后一次未命中原因418 最后一次未命中原因

860 速率限制使用情况860 速率限制使用情况

861</h3>861</h3>

862 862

863在状态行中显示 Claude.ai 订阅速率限制使用情况。`rate_limits` 对象包含一个滚动的 `five_hour` 窗口和一个每周的 `seven_day` 窗口。每个窗口提供 `used_percentage`（从 0 到 100）和 `resets_at`（Unix 纪元秒，当窗口重置时）。863在状态行中显示 claude.ai 订阅速率限制使用情况。`rate_limits` 对象包含一个滚动的 `five_hour` 窗口和一个每周的 `seven_day` 窗口。每个窗口提供 `used_percentage`（从 0 到 100）和 `resets_at`（Unix 纪元秒，当窗口重置时）。

864 864

865在具有支出限制的 Claude 应用网关后面，`rate_limits` 携带 `spend_limit`，其中包含适用于你的支出限制的相同两个字段，除了其 `used_percentage` 一旦超过限制可能会超过 100。需要 Claude Code v2.1.251 或更高版本。865在具有支出限制的 Claude 应用网关后面，`rate_limits` 携带 `spend_limit`，其中包含适用于你的支出限制的相同两个字段，除了其 `used_percentage` 一旦超过限制可能会超过 100。需要 Claude Code v2.1.251 或更高版本。

866 866

867`rate_limits` 对象仅对 Claude.ai Pro 和 Max 订阅者或具有支出限制的 Claude 应用网关后面的用户出现，并且仅在第一次 API 响应后出现。每个脚本优雅地处理缺失字段：867`rate_limits` 对象仅对 claude.ai Pro 和 Max 订阅者或具有支出限制的 Claude 应用网关后面的用户出现，并且仅在第一次 API 响应后出现。每个脚本优雅地处理缺失字段：

868 868

869<CodeGroup>869<CodeGroup>

870 ```bash Bash theme={null}870 ```bash Bash theme={null}

sub-agents.md +14 −9

Details

32 32

33Claude Code 包括内置 subagents，Claude 在适当时自动使用。每个都继承父对话的权限；大多数运行时工具集受限。33Claude Code 包括内置 subagents，Claude 在适当时自动使用。每个都继承父对话的权限；大多数运行时工具集受限。

34 34

35Explore 和 Plan 会跳过您的 CLAUDE.md 文件和父会话的 git 状态，以保持研究快速且成本低廉。所有其他内置和[自定义 subagent](#configure-subagents) 都会加载两者。有关到达 subagent 的内容的完整分解，请参阅[启动时加载的内容](#what-loads-at-startup)。35Explore 和 Plan 会跳过您的 CLAUDE.md 文件和父会话的 git 状态，以保持研究快速且成本低廉。所有其他内置和[自定义 subagent](#configure-subagents) 都会加载两者，除非其定义设置了 [`omitClaudeMd`](#supported-frontmatter-fields) 字段以跳过用户、项目和本地 CLAUDE.md 文件。有关到达 subagent 的内容的完整分解，请参阅[启动时加载的内容](#what-loads-at-startup)。

36 36

37<Tabs>37<Tabs>

38 <Tab title="Explore">38 <Tab title="Explore">

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` 和 `isolation`。对系统提示使用 `prompt`，等同于基于文件的 subagents 中的 markdown 正文。JSON 中的每个顶级键是代理的名称。不要以 `-` 开头的名称。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 正文。

234

235JSON 中的每个顶级键是代理的名称。不要以 `-` 开头的名称。

234 236

235有关 Claude Code 对无法加载的值的处理，以及跳过该检查的标志和环境变量，请参阅 [`Invalid --agents configuration`](/docs/zh-CN/errors#invalid-agents-configuration)。237有关 Claude Code 对无法加载的值的处理，以及跳过该检查的标志和环境变量，请参阅 [`Invalid --agents configuration`](/docs/zh-CN/errors#invalid-agents-configuration)。

236 238

313| `hooks` | 否 | [Lifecycle hooks](#define-hooks-for-subagents) 限定于此 subagent。对于 [plugin subagents](#choose-the-subagent-scope) 被忽略 |315| `hooks` | 否 | [Lifecycle hooks](#define-hooks-for-subagents) 限定于此 subagent。对于 [plugin subagents](#choose-the-subagent-scope) 被忽略 |

314| `memory` | 否 | [Persistent memory scope](#enable-persistent-memory)：`user`、`project` 或 `local`。启用跨会话学习 |316| `memory` | 否 | [Persistent memory scope](#enable-persistent-memory)：`user`、`project` 或 `local`。启用跨会话学习 |

315| `background` | 否 | 设置为 `true` 以即使 Claude 要求在前台运行也保持此 subagent 在后台。其中 [fork mode](#turn-fork-mode-on-or-off) 打开时，Claude Code 已经在 [background](#run-subagents-in-foreground-or-background) 中运行 Claude 生成的 subagents |317| `background` | 否 | 设置为 `true` 以即使 Claude 要求在前台运行也保持此 subagent 在后台。其中 [fork mode](#turn-fork-mode-on-or-off) 打开时，Claude Code 已经在 [background](#run-subagents-in-foreground-or-background) 中运行 Claude 生成的 subagents |

318| `omitClaudeMd` | 否 | 设置为 `true` 以启动此 subagent 而不使用用户、项目和本地 CLAUDE.md 文件；[managed policy files](/docs/zh-CN/memory#how-claude-md-files-load) 仍然加载，除了 [managed subagents](#choose-the-subagent-scope)。对于从 [delegation prompt](#what-loads-at-startup) 获取所需一切的 subagents 使用它。当代理通过 `--agent` 或 `agent` 设置作为主会话代理运行时被忽略。需要 Claude Code v2.1.271 或更高版本 |

316| `effort` | 否 | 此 subagent 活跃时的努力级别。覆盖会话努力级别。默认：从会话继承。选项：`low`、`medium`、`high`、`xhigh`、`max`；可用级别取决于模型 |319| `effort` | 否 | 此 subagent 活跃时的努力级别。覆盖会话努力级别。默认：从会话继承。选项：`low`、`medium`、`high`、`xhigh`、`max`；可用级别取决于模型 |

317| `isolation` | 否 | 设置为 `worktree` 以在临时 [git worktree](/docs/zh-CN/worktrees) 中运行 subagent，为其提供存储库的隔离副本，默认从您的 [default branch](/docs/zh-CN/worktrees#choose-the-base-branch) 分支，而不是父会话的 `HEAD`。如果 subagent 不进行任何更改，worktree 会自动清理 |320| `isolation` | 否 | 设置为 `worktree` 以在临时 [git worktree](/docs/zh-CN/worktrees) 中运行 subagent，为其提供存储库的隔离副本，默认从您的 [default branch](/docs/zh-CN/worktrees#choose-the-base-branch) 分支，而不是父会话的 `HEAD`。如果 subagent 不进行任何更改，worktree 会自动清理 |

318| `color` | 否 | Subagent 在任务列表和转录中的显示颜色。接受 `red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink` 或 `cyan` |321| `color` | 否 | Subagent 在任务列表和转录中的显示颜色。接受 `red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink` 或 `cyan` |

439* `WaitForMcpServers`442* `WaitForMcpServers`

440* `Workflow`443* `Workflow`

441 444

442第二个过滤器适用于在后台运行的 subagents。除了 `Agent` 和 `ExitPlanMode`，它们遵循第一个过滤器的条件，无论 subagent 在哪里运行，后台 subagent 保留每个 MCP 工具但仅这些内置工具：`Read`、`Grep`、`Glob`、`Bash`、`PowerShell`、`Edit`、`Write`、`NotebookEdit`、`WebFetch`、`WebSearch`、`TodoWrite`、`Skill`、`ToolSearch`、`EnterWorktree`、`ExitWorktree`、`Monitor`、`TaskStop`、`SendMessage` 和 `Artifact`。Claude Code 从后台 subagent 删除每个其他内置工具，无论继承还是在 `tools` 字段中列出，因此相同的定义可以在前台和后台解析为不同的工具。删除报告没有错误，除非它使 `tools` 列表 [resolving to nothing](/docs/zh-CN/errors#agent-would-be-spawned-with-zero-tools)。445第二个过滤器适用于在后台运行的 subagents。除了 `Agent` 和 `ExitPlanMode`，它们遵循第一个过滤器的条件，无论 subagent 在哪里运行，后台 subagent 保留每个 MCP 工具但仅这些内置工具：`Read`、`Grep`、`Glob`、`Bash`、`PowerShell`、`Edit`、`Write`、`NotebookEdit`、`WebFetch`、`WebSearch`、`TodoWrite`、`Skill`、`ToolSearch`、`EnterWorktree`、`ExitWorktree`、`Monitor`、`TaskStop`、`SendMessage` 和 `Artifact`，加上 [`SubagentHandback`](/docs/zh-CN/tools-reference) 用于通过它报告的 subagent。Claude Code 从后台 subagent 删除每个其他内置工具，无论继承还是在 `tools` 字段中列出，因此相同的定义可以在前台和后台解析为不同的工具。删除报告没有错误，除非它使 `tools` 列表 [resolving to nothing](/docs/zh-CN/errors#agent-would-be-spawned-with-zero-tools)。

443 446

444[`ListAgents`](/docs/zh-CN/cross-session-messaging) 遵循这些过滤器，如任何内置工具：前台 subagent 在启用跨会话消息的会话中继承它，后台 subagent 不保留它。447[`ListAgents`](/docs/zh-CN/cross-session-messaging) 遵循这些过滤器，如任何内置工具：前台 subagent 在启用跨会话消息的会话中继承它，后台 subagent 不保留它。

445 448

578 581

579主对话的权限模式决定 Claude Code 是否使用您设置的值：582主对话的权限模式决定 Claude Code 是否使用您设置的值：

580 583

581* 当主对话在 `bypassPermissions`、`acceptEdits` 或 [auto mode](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 时，subagent 在该相同模式中运行，Claude Code 忽略您设置的 `permissionMode`。在自动模式下，分类器使用主对话的块和允许规则评估 subagent 的工具调用。584* 当主对话在 `bypassPermissions`、`acceptEdits` 或 [auto mode](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 时，subagent 在该相同模式中运行，Claude Code 忽略您设置的 `permissionMode`。在自动模式下，分类器使用主对话的块和允许规则评估 subagent 的工具调用。当 subagent 完成时，分类器也会在报告被传递之前审查其工作和最终报告，如 [How auto mode handles subagents](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 所述。

582* 当主对话在 `default`、`dontAsk` 或 `plan` 模式时，subagent 在您设置的权限模式中运行，除了 `bypassPermissions`。声明 `bypassPermissions` 的 subagent 改为保持主对话的模式。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更高版本。585* 当主对话在 `default`、`dontAsk` 或 `plan` 模式时，subagent 在您设置的权限模式中运行，除了 `bypassPermissions`。声明 `bypassPermissions` 的 subagent 改为保持主对话的模式。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更高版本。

583 586

584`permissionMode` 接受这些值，以及 `manual` 作为 `default` 的别名：587`permissionMode` 接受这些值，以及 `manual` 作为 `default` 的别名：

884claude --agent code-reviewer887claude --agent code-reviewer

885```888```

886 889

887Subagent 的系统提示完全替换默认 Claude Code 系统提示，就像 [`--system-prompt`](/docs/zh-CN/cli-reference) 一样。`CLAUDE.md` 文件和项目内存仍然通过正常消息流加载。代理名称在启动标题中显示为 `@<name>`，以便您可以确认它是活跃的。890Subagent 的系统提示完全替换默认 Claude Code 系统提示，就像 [`--system-prompt`](/docs/zh-CN/cli-reference) 一样。`CLAUDE.md` 文件和项目内存仍然通过正常消息流加载，即使代理的定义设置了 [`omitClaudeMd`](#supported-frontmatter-fields)。代理名称在启动标题中显示为 `@<name>`，以便您可以确认它是活跃的。

888 891

889这适用于内置和自定义 subagents，当您恢复会话时选择会持续：Claude Code 恢复代理的工具限制和模型以及对话。如果代理在您恢复时不再存在，会话继续使用默认工具并显示 [警告命名代理](/docs/zh-CN/errors#session-agent-no-longer-available)。对于任一情况下的系统提示，请参阅 [已恢复对话中的系统提示标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。892这适用于内置和自定义 subagents，当您恢复会话时选择会持续：Claude Code 恢复代理的工具限制和模型以及对话。如果代理在您恢复时不再存在，会话继续使用默认工具并显示 [警告命名代理](/docs/zh-CN/errors#session-agent-no-longer-available)。对于任一情况下的系统提示，请参阅 [已恢复对话中的系统提示标志](/docs/zh-CN/cli-reference#system-prompt-flags-in-resumed-conversations)。

890 893

1057 1060

1058默认情况下，subagent 可以生成自己的 subagents，最多在主对话下方三层。在深度限制处，Claude Code 从除 [fork](#fork-the-current-conversation) 外的每个 subagent 中扣留 `Agent` 工具，所以限制处的 subagent 自己进行委托工作并返回一个摘要。限制处的 fork 在其继承的工具列表中保持 `Agent`，但工具返回错误而不是生成。1061默认情况下，subagent 可以生成自己的 subagents，最多在主对话下方三层。在深度限制处，Claude Code 从除 [fork](#fork-the-current-conversation) 外的每个 subagent 中扣留 `Agent` 工具，所以限制处的 subagent 自己进行委托工作并返回一个摘要。限制处的 fork 在其继承的工具列表中保持 `Agent`，但工具返回错误而不是生成。

1059 1062

1060嵌套 subagents 适合委托任务本身分裂成并行子任务，例如审查者 subagent 为每个发现分派验证者，所以中间输出永远不会到达您的主对话。只有顶级 subagent 的摘要返回给您。1063嵌套 subagents 适合委托任务本身分裂成并行子任务，例如审查者 subagent 为每个发现分派验证者。在交互式会话中，只有顶级 subagent 的摘要返回给您，中间输出保留在 subagent 的上下文中：生成后台 subagents 的 subagent 在完成之前等待其结果。在 [非交互模式](/docs/zh-CN/headless) 和 Agent SDK 中，启动 subagent 不等待，所以在其启动器已结束后完成的嵌套后台 subagent 报告给您的主对话。

1061 1064

1062要改变限制，将 [`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`](/docs/zh-CN/env-vars) 设置为您想要在主对话下方的 subagent 层数。例如，此条目在 [`settings.json`](/docs/zh-CN/settings) 中将嵌套限制为两层：1065要改变限制，将 [`CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`](/docs/zh-CN/env-vars) 设置为您想要在主对话下方的 subagent 层数。例如，此条目在 [`settings.json`](/docs/zh-CN/settings) 中将嵌套限制为两层：

1063 1066

1111 1114

1112* **系统提示**：代理自己的提示加上 Claude Code 附加的环境详情，而不是 Claude Code 系统提示。自定义 subagents 在 [markdown 正文](#write-subagent-files) 或 `prompt` 字段中定义它们。内置代理有预定义的提示。1115* **系统提示**：代理自己的提示加上 Claude Code 附加的环境详情，而不是 Claude Code 系统提示。自定义 subagents 在 [markdown 正文](#write-subagent-files) 或 `prompt` 字段中定义它们。内置代理有预定义的提示。

1113* **任务消息**：Claude 在移交工作时编写的委托提示。1116* **任务消息**：Claude 在移交工作时编写的委托提示。

1114* **CLAUDE.md 文件**：主对话加载的 [CLAUDE.md 层次结构](/docs/zh-CN/memory#how-claude-md-files-load) 的每个级别，包括 `~/.claude/CLAUDE.md`、项目规则、`CLAUDE.local.md` 和托管策略文件。内置的 Explore 和 Plan 代理跳过这个。1117* **CLAUDE.md 文件**：主对话加载的 [CLAUDE.md 层次结构](/docs/zh-CN/memory#how-claude-md-files-load) 的每个级别，包括 `~/.claude/CLAUDE.md`、项目规则、`CLAUDE.local.md` 和托管策略文件。内置的 Explore 和 Plan 代理跳过这个。Subagent 的定义设置 [`omitClaudeMd`](#supported-frontmatter-fields) 时仅加载托管策略文件，或当定义来自 [托管设置](#choose-the-subagent-scope) 时不加载任何文件。

1115* **Git 状态**：在父会话开始时拍摄的快照。当工作目录不是 Git 存储库或 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions) 为 `false` 时不存在。Explore 和 Plan 无论如何都跳过它。1118* **Git 状态**：在父会话开始时拍摄的快照。当工作目录不是 Git 存储库或 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions) 为 `false` 时不存在。Explore 和 Plan 无论如何都跳过它。

1116* **预加载的技能**：代理的 [`skills` 字段](#preload-skills-into-subagents) 中命名的任何技能的完整内容。内置代理不预加载技能。1119* **预加载的技能**：代理的 [`skills` 字段](#preload-skills-into-subagents) 中命名的任何技能的完整内容。内置代理不预加载技能。

1117* **兄弟名单**：系统提醒，列出 `main` 和会话中的每个其他命名代理，每个都是 [`SendMessage`](#resume-subagents) 的有效 `to` 值。需要 Claude Code v2.1.206 或更高版本。名单仅在 subagent 的工具包括 `SendMessage` 且至少有一个其他代理有名称时出现，无论 Claude 在生成时命名它还是它作为 [agent team](/docs/zh-CN/agent-teams) 队友运行。它是 subagent 启动时拍摄的快照，所以稍后命名的代理不会出现。1120* **兄弟名单**：系统提醒，列出 `main` 和会话中的每个其他命名代理，每个都是 [`SendMessage`](#resume-subagents) 的有效 `to` 值。需要 Claude Code v2.1.206 或更高版本。名单仅在 subagent 的工具包括 `SendMessage` 且至少有一个其他代理有名称时出现，无论 Claude 在生成时命名它还是它作为 [agent team](/docs/zh-CN/agent-teams) 队友运行。它是 subagent 启动时拍摄的快照，所以稍后命名的代理不会出现。

1118 1121

1119Explore 和 Plan 是仅有的省略 CLAUDE.md 和 git 状态的 subagents。没有 frontmatter 字段或按代理设置来改变哪些代理跳过它们。1122要启动您自己的 subagents 而不使用用户、项目和本地 CLAUDE.md 文件，在其 frontmatter 中设置 [`omitClaudeMd: true`](#supported-frontmatter-fields) 或 `--agents` JSON。

1123

1124主对话仍然有您的完整 CLAUDE.md 当它读取这些 subagents 的结果时，所以大多数规则不需要到达 subagent 本身。如果规则必须，例如"忽略 `vendor/` 目录"，在您给 Claude 委托时的提示中重新陈述它。

1120 1125

1121主对话使用完整的 CLAUDE.md 上下文读取 Explore 和 Plan 结果，所以大多数规则不需要到达 subagent 本身。如果规则必须，例如"忽略 `vendor/` 目录"，在您给 Claude 委托时的提示中重新陈述它。1126您无法改变哪些 subagents 接收 git 状态。只有 Explore 和 Plan 跳过它。

1122 1127

1123某些主对话状态永远不会到达非 fork subagent：1128某些主对话状态永远不会到达非 fork subagent：

1124 1129

terminal-config.md +1 −1

Details

126 配置 tmux126 配置 tmux

127</h2>127</h2>

128 128

129当 Claude Code 在 tmux 中运行时，默认情况下会出现两个问题：Shift+Enter 提交而不是插入换行符，桌面通知和[进度条](/docs/zh-CN/settings-reference#terminalprogressbarenabled)永远无法到达外部终端。将这些行添加到 `~/.tmux.conf`，然后运行 `tmux source-file ~/.tmux.conf` 将其应用到运行中的服务器：129当 Claude Code 在 tmux 中运行时，默认情况下 Shift+Enter 提交而不是插入换行符，桌面通知和[进度条](/docs/zh-CN/settings-reference#terminalprogressbarenabled)永远无法到达外部终端。将这些行添加到 `~/.tmux.conf`，然后运行 `tmux source-file ~/.tmux.conf` 将其应用到运行中的服务器：

130 130

131```bash ~/.tmux.conf theme={null}131```bash ~/.tmux.conf theme={null}

132set -g allow-passthrough on132set -g allow-passthrough on

third-party-integrations.md +2 −2

Details

141 </tr>141 </tr>

142 142

143 <tr>143 <tr>

144 <td>prompt caching</td>144 <td>Prompt caching</td>

145 <td>默认启用</td>145 <td>默认启用</td>

146 <td>默认启用</td>146 <td>默认启用</td>

147 <td>默认启用</td>147 <td>默认启用</td>

152 152

153 <tr>153 <tr>

154 <td>身份验证</td>154 <td>身份验证</td>

155 <td>Claude.ai SSO 或电子邮件</td>155 <td>claude.ai SSO 或电子邮件</td>

156 <td>API 密钥或 [Console 无密钥登录](/docs/zh-CN/authentication#sign-in-without-an-api-key)</td>156 <td>API 密钥或 [Console 无密钥登录](/docs/zh-CN/authentication#sign-in-without-an-api-key)</td>

157 <td>API 密钥或 AWS 凭证</td>157 <td>API 密钥或 AWS 凭证</td>

158 <td>API 密钥或 AWS 凭证</td>158 <td>API 密钥或 AWS 凭证</td>

tools-reference.md +16 −10

Details

27| `CronList` | 列出会话中的所有计划任务 | 否 |27| `CronList` | 列出会话中的所有计划任务 | 否 |

28| `Edit` | 对特定文件进行有针对性的编辑。请参阅 [Edit 工具行为](#edit-tool-behavior) | 是 |28| `Edit` | 对特定文件进行有针对性的编辑。请参阅 [Edit 工具行为](#edit-tool-behavior) | 是 |

29| `EndConversation` | 结束会话，在持续滥用输入的罕见情况下或当您要求 Claude 演示该工具时。需要 Claude Code v2.1.213 或更高版本。请参阅 [EndConversation 工具行为](#endconversation-tool-behavior) | 否 |29| `EndConversation` | 结束会话，在持续滥用输入的罕见情况下或当您要求 Claude 演示该工具时。需要 Claude Code v2.1.213 或更高版本。请参阅 [EndConversation 工具行为](#endconversation-tool-behavior) | 否 |

30| `EnterPlanMode` | 切换到计划模式以在编码前设计方法 | 否 |30| `EnterPlanMode` | 切换到 Plan Mode 以在编码前设计方法 | 否 |

31| `EnterWorktree` | 创建一个隔离的 [git worktree](/docs/zh-CN/worktrees) 并切换到它。传递 `path` 以切换到现有 worktree，而不是创建新的。首次进入时，目标可能是当前存储库的 worktree，或在多存储库工作区中，是嵌套在其中的存储库的 worktree。在 v2.1.203 之前，嵌套存储库的 worktree 被拒绝。`.claude/worktrees/` 之外的 `path` 会在进入前提示您的批准，因为它会移动会话的工作目录和对该位置的写入访问权限。新 worktree 创建和 `.claude/worktrees/` 下的路径不会提示。在 v2.1.206 之前，Claude 进入 `.claude/worktrees/` 之外的路径而不提示。从 worktree 会话内，或从具有固定工作目录的子代理（例如 [`isolation: worktree`](/docs/zh-CN/sub-agents#supported-frontmatter-fields)），只有 `path` 形式可用，目标必须在会话存储库的 `.claude/worktrees/` 下 | 是 |31| `EnterWorktree` | 创建一个隔离的 [git worktree](/docs/zh-CN/worktrees) 并切换到它。传递 `path` 以切换到现有 worktree，而不是创建新的。首次进入时，目标可能是当前存储库的 worktree，或在多存储库工作区中，是嵌套在其中的存储库的 worktree。在 v2.1.203 之前，嵌套存储库的 worktree 被拒绝。`.claude/worktrees/` 之外的 `path` 会在进入前提示您的批准，因为它会移动会话的工作目录和对该位置的写入访问权限。新 worktree 创建和 `.claude/worktrees/` 下的路径不会提示。在 v2.1.206 之前，Claude 进入 `.claude/worktrees/` 之外的路径而不提示。从 worktree 会话内，或从具有固定工作目录的子代理（例如 [`isolation: worktree`](/docs/zh-CN/sub-agents#supported-frontmatter-fields)），只有 `path` 形式可用，目标必须在会话存储库的 `.claude/worktrees/` 下 | 是 |

32| `ExitPlanMode` | 呈现计划以供批准并退出计划模式 | 是 |32| `ExitPlanMode` | 呈现计划以供批准并退出 Plan Mode | 是 |

33| `ExitWorktree` | 退出 worktree 会话并返回到原始目录。不适用于已在自己的工作目录中运行的子代理，例如 [`isolation: worktree`](/docs/zh-CN/sub-agents#supported-frontmatter-fields) | 否 |33| `ExitWorktree` | 退出 worktree 会话并返回到原始目录。不适用于已在自己的工作目录中运行的子代理，例如 [`isolation: worktree`](/docs/zh-CN/sub-agents#supported-frontmatter-fields) | 否 |

34| `Glob` | 基于模式匹配查找文件。请参阅 [Glob 工具行为](#glob-tool-behavior) | 否 |34| `Glob` | 基于模式匹配查找文件。在 macOS、Linux 和 WSL 上默认不存在。请参阅 [Glob 工具行为](#glob-tool-behavior) | 否 |

35| `Grep` | 在文件内容中搜索模式。请参阅 [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)公开的资源 | 否 |

38| `LSP` | 通过语言服务器的代码智能：跳转到定义、查找引用、报告类型错误和警告。请参阅 [LSP 工具行为](#lsp-tool-behavior) | 否 |38| `LSP` | 通过语言服务器的代码智能：跳转到定义、查找引用、报告类型错误和警告。请参阅 [LSP 工具行为](#lsp-tool-behavior) | 否 |

47| `ScheduleWakeup` | 重新安排[自定步调 `/loop`](/docs/zh-CN/scheduled-tasks#let-claude-choose-the-interval)的下一次迭代。Claude 在每次迭代结束时调用此方法以选择下一次运行的时间，在一分钟到一小时之间；您不直接调用它。要改为结束循环，Claude 使用 `stop: true` 调用它，这会取消待处理的唤醒。`stop` 字段需要 Claude Code v2.1.202 或更高版本。待处理的唤醒出现在[停止 hook 输入](/docs/zh-CN/hooks#stop-input)中的 `session_crons` 中 | 否 |47| `ScheduleWakeup` | 重新安排[自定步调 `/loop`](/docs/zh-CN/scheduled-tasks#let-claude-choose-the-interval)的下一次迭代。Claude 在每次迭代结束时调用此方法以选择下一次运行的时间，在一分钟到一小时之间；您不直接调用它。要改为结束循环，Claude 使用 `stop: true` 调用它，这会取消待处理的唤醒。`stop` 字段需要 Claude Code v2.1.202 或更高版本。待处理的唤醒出现在[停止 hook 输入](/docs/zh-CN/hooks#stop-input)中的 `session_crons` 中 | 否 |

48| `SendFeedback` | 起草关于 Claude Code 的反馈报告，涵盖产品问题或 Claude 在会话中的自身行为，并将其排队在您的机器上供您审查。Claude Code 在您选择发送草稿之前不会发送任何内容。请参阅 [SendFeedback 工具行为](#sendfeedback-tool-behavior)。需要 Claude Code v2.1.238 或更高版本 | 否 |48| `SendFeedback` | 起草关于 Claude Code 的反馈报告，涵盖产品问题或 Claude 在会话中的自身行为，并将其排队在您的机器上供您审查。Claude Code 在您选择发送草稿之前不会发送任何内容。请参阅 [SendFeedback 工具行为](#sendfeedback-tool-behavior)。需要 Claude Code v2.1.238 或更高版本 | 否 |

49| `SendMessage` | 向另一个代理发送消息：[代理团队](/docs/zh-CN/agent-teams)队友、[通过代理 ID 或名称恢复的子代理](/docs/zh-CN/sub-agents#resume-subagents)，或您的其他 Claude Code 会话之一，在此机器上或超越它。消息传递其他会话需要 Claude Code v2.1.224 或更高版本。[跨会话消息传递](/docs/zh-CN/cross-session-messaging)涵盖 Claude 可以到达的会话、[消息到达时的样子](/docs/zh-CN/cross-session-messaging#what-a-message-looks-like)以及[Claude 如何在另一个会话空闲时获得通知](/docs/zh-CN/cross-session-messaging#get-a-notice-when-another-session-goes-idle)。Claude 可以包含可选的 `summary` 输入，通常为 5-10 个单词，Claude Code 显示为单行预览。当 Claude 在[纯文本消息](/docs/zh-CN/cross-session-messaging#limitations)上省略它时，Claude Code 使用消息的第一行作为摘要。Claude Code 使用省略号截断长于 200 个字符的摘要 | 否 |49| `SendMessage` | 向另一个代理发送消息：[代理团队](/docs/zh-CN/agent-teams)队友、[通过代理 ID 或名称恢复的子代理](/docs/zh-CN/sub-agents#resume-subagents)，或您的其他 Claude Code 会话之一，在此机器上或超越它。消息传递其他会话需要 Claude Code v2.1.224 或更高版本。[跨会话消息传递](/docs/zh-CN/cross-session-messaging)涵盖 Claude 可以到达的会话、[消息到达时的样子](/docs/zh-CN/cross-session-messaging#what-a-message-looks-like)以及[Claude 如何在另一个会话空闲时获得通知](/docs/zh-CN/cross-session-messaging#get-a-notice-when-another-session-goes-idle)。Claude 可以包含可选的 `summary` 输入，通常为 5-10 个单词，Claude Code 显示为单行预览。当 Claude 在[纯文本消息](/docs/zh-CN/cross-session-messaging#limitations)上省略它时，Claude Code 使用消息的第一行作为摘要。Claude Code 使用省略号截断长于 200 个字符的摘要 | 否 |

50| `SendUserFile` | 从会话向您发送文件，带有可选标题，以便生成的报告、图表、屏幕截图或构建的工件到达您的设备，而不仅仅在成绩单中提及。从 v2.1.196 开始，可选的 `display` 输入控制呈现：`render` 在客户端中内联打开文件，`attach` 仅显示下载卡，未设置时客户端按文件类型决定。在连接[远程控制](/docs/zh-CN/remote-control)客户端或会话在托管云环境（例如[网络版 Claude Code](/docs/zh-CN/claude-code-on-the-web)）中运行时可用。传递通过 Anthropic 托管的基础设施运行，因此该工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用 | 否 |50| `SendUserFile` | 从会话向您发送文件，带有可选标题，以便生成的报告、图表、屏幕截图或构建的工件到达您的设备，而不仅仅在成绩单中提及。从 v2.1.196 开始，可选的 `display` 输入控制呈现：`render` 在客户端中内联打开文件，`attach` 仅显示下载卡，未设置时客户端按文件类型决定。在连接[远程控制](/docs/zh-CN/remote-control)客户端或在[网络版 Claude Code](/docs/zh-CN/claude-code-on-the-web)中时可用。传递通过 Anthropic 托管的基础设施运行，因此该工具在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上不可用 | 否 |

51| `ShareOnboardingGuide` | 上传 `ONBOARDING.md` 并返回队友可以在 Claude Code 中打开的共享链接。在编写指南后从 `/team-onboarding` 调用。适用于 Pro、Max、Team 和 Enterprise 计划上的 claude.ai 订阅者 | 是 |51| `ShareOnboardingGuide` | 上传 `ONBOARDING.md` 并返回队友可以在 Claude Code 中打开的共享链接。在编写指南后从 `/team-onboarding` 调用。适用于 Pro、Max、Team 和 Enterprise 计划上的 claude.ai 订阅者 | 是 |

52| `Skill` | 在主对话中执行[skill](/docs/zh-CN/skills#control-who-invokes-a-skill) | 是 |52| `Skill` | 在主对话中执行[skill](/docs/zh-CN/skills#control-who-invokes-a-skill) | 是 |

53| `SubagentHandback` | 将子代理的最终报告传递给接收该子代理结果的任何对话。仅在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中提供，给 Agent 工具在本地运行的子代理，除了[分叉](/docs/zh-CN/sub-agents#fork-the-current-conversation)，并在终端 CLI、IDE 扩展、网络版会话和 Agent SDK 中可用；分类器在传递报告前审查它。需要 Claude Code v2.1.271 或更高版本 | 否 |

53| `TaskCreate` | 在任务列表中创建新任务。仅在[任务工具可用性](#task-tool-availability)下列出的模型上默认提供，在其他模型上当您选择加入时提供 | 否 |54| `TaskCreate` | 在任务列表中创建新任务。仅在[任务工具可用性](#task-tool-availability)下列出的模型上默认提供，在其他模型上当您选择加入时提供 | 否 |

54| `TaskGet` | 检索特定任务的完整详细信息。仅在[任务工具可用性](#task-tool-availability)下列出的模型上默认提供，在其他模型上当您选择加入时提供 | 否 |55| `TaskGet` | 检索特定任务的完整详细信息。仅在[任务工具可用性](#task-tool-availability)下列出的模型上默认提供，在其他模型上当您选择加入时提供 | 否 |

55| `TaskList` | 列出所有任务及其当前状态。仅在[任务工具可用性](#task-tool-availability)下列出的模型上默认提供，在其他模型上当您选择加入时提供 | 否 |56| `TaskList` | 列出所有任务及其当前状态。仅在[任务工具可用性](#task-tool-availability)下列出的模型上默认提供，在其他模型上当您选择加入时提供 | 否 |

99 Agent tool 行为100 Agent tool 行为

100</h2>101</h2>

101 102

102Agent tool 在单独的上下文窗口中生成一个子代理。子代理自主地完成其任务，然后向父对话返回单个文本结果。父对话看不到子代理的中间 tool 调用或输出，只能看到最终结果。启用 [agent teams](/docs/zh-CN/agent-teams) 后，携带 `name` 的调用可以启动一个 [teammate](/docs/zh-CN/agent-teams#how-claude-starts-agent-teams)，它通过团队消息而不是返回结果来报告。103Agent tool 在单独的上下文窗口中生成一个子代理。子代理自主地完成其任务，然后向父对话返回其结果。父对话看不到子代理的中间 tool 调用或输出，只能看到最终结果。启用 [agent teams](/docs/zh-CN/agent-teams) 后，携带 `name` 的调用可以启动一个 [teammate](/docs/zh-CN/agent-teams#how-claude-starts-agent-teams)，它通过团队消息而不是返回结果来报告。

103 104

104要限制子代理运行的轮数，请在 [subagent definition](/docs/zh-CN/sub-agents#supported-frontmatter-fields) 中设置 `maxTurns`。当子代理达到限制时，Claude Code 将返回的结果标记为部分输出，Claude 可以 [resume the subagent](/docs/zh-CN/sub-agents#resume-subagents) 来继续。105要限制子代理运行的轮数，请在 [subagent definition](/docs/zh-CN/sub-agents#supported-frontmatter-fields) 中设置 `maxTurns`。当子代理达到限制时，Claude Code 将返回的结果标记为部分输出，Claude 可以 [resume the subagent](/docs/zh-CN/sub-agents#resume-subagents) 来继续。

105 106

112* **仅 `disallowedTools`**：子代理获得除列出的 tools 之外的每个父 tool。113* **仅 `disallowedTools`**：子代理获得除列出的 tools 之外的每个父 tool。

113* **两者都设置**：`disallowedTools` 优先。同时列在两者中的 tool 被移除。114* **两者都设置**：`disallowedTools` 优先。同时列在两者中的 tool 被移除。

114 115

115在任何情况下，解析的集合都限于 [tools available to subagents](/docs/zh-CN/sub-agents#available-tools)：不可用于子代理的 tool 永远不会被授予，即使在 `tools` 中列出。116在任何情况下，解析的集合都限于 [tools available to subagents](/docs/zh-CN/sub-agents#available-tools)：不可用于子代理的 tool 永远不会被授予，即使在 `tools` 中列出。在 `SubagentHandback` tools-table 条目中的条件成立的地方，Claude Code 也会给子代理该 tool，即使您将其排除在 `tools` 之外或在 `disallowedTools` 中列出它。

116 117

117如果子代理的 `tools` 列表中的每个条目都无法匹配可用的 tool，Agent tool 通常会返回一个错误，命名这些条目而不是启动子代理；请参阅 [Agent would be spawned with zero tools](/docs/zh-CN/errors#agent-would-be-spawned-with-zero-tools) 了解消息以及如何修复每个条目。118如果子代理的 `tools` 列表中的每个条目都无法匹配可用的 tool，Agent tool 通常会返回一个错误，命名这些条目而不是启动子代理；请参阅 [Agent would be spawned with zero tools](/docs/zh-CN/errors#agent-would-be-spawned-with-zero-tools) 了解消息以及如何修复每个条目。

118 119

277 * 通过 [Agent SDK](/docs/zh-CN/agent-sdk/overview) TypeScript 和 Python 包的会话278 * 通过 [Agent SDK](/docs/zh-CN/agent-sdk/overview) TypeScript 和 Python 包的会话

278 * [VS Code 扩展](/docs/zh-CN/vs-code)面板，它捆绑了自己的 CLI279 * [VS Code 扩展](/docs/zh-CN/vs-code)面板，它捆绑了自己的 CLI

279 * [GitHub Actions](/docs/zh-CN/github-actions)280 * [GitHub Actions](/docs/zh-CN/github-actions)

280 * [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web)281 * [云会话](/docs/zh-CN/claude-code-on-the-web)

281* **启动模式**：不是 [`--bare`](/docs/zh-CN/headless#start-faster-with-bare-mode) 会话。裸模式仅加载 shell 和文件工具，因此该工具从不在那里注册。282* **启动模式**：不是 [`--bare`](/docs/zh-CN/headless#start-faster-with-bare-mode) 会话。裸模式仅加载 shell 和文件工具，因此该工具从不在那里注册。

282* **提供商**：在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws)、[Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上不可用，或在通过[云网关](/docs/zh-CN/claude-apps-gateway)登录的会话上不可用。283* **提供商**：在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws)、[Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上不可用，或在通过[云网关](/docs/zh-CN/claude-apps-gateway)登录的会话上不可用。

283 284

363 364

364您可以在同一会话中继续工作，Claude 在事件到达时进行插入。365您可以在同一会话中继续工作，Claude 在事件到达时进行插入。

365 366

367每个 Claude 启动的监视都有一个截止时间：默认为 5 分钟，最多 30 分钟，在 [非交互式](/docs/zh-CN/headless) 运行中使用单个提示和 `-p` 时最多 10 分钟。

368

369在截止时间时，监视结束。Claude 会收到一个通知，因此如果仍然需要，它可以重新启动监视。

370

366通过要求 Claude 取消监视或结束会话来停止监视。当您停止启动了监视的 [subagent](/docs/zh-CN/sub-agents)（例如来自 `/tasks`）时，这些监视会随之停止。371通过要求 Claude 取消监视或结束会话来停止监视。当您停止启动了监视的 [subagent](/docs/zh-CN/sub-agents)（例如来自 `/tasks`）时，这些监视会随之停止。

367 372

368当 Monitor 运行命令时，它使用与 Bash 相同的 [权限规则](/docs/zh-CN/permissions#tool-specific-permission-rules)，因此您为 Bash 设置的 `allow` 和 `deny` 模式也适用于此处。当 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 处于活动状态时，Claude Code 会搁置命名 `Monitor` 本身的允许规则，以及它删除的其他 [广泛允许规则](/docs/zh-CN/permission-modes#how-the-classifier-evaluates-actions)，因此分类器以与审查 Bash 命令相同的方式审查 Monitor 命令。373当 Monitor 运行命令时，它使用与 Bash 相同的 [权限规则](/docs/zh-CN/permissions#tool-specific-permission-rules)，因此您为 Bash 设置的 `allow` 和 `deny` 模式也适用于此处。当 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 处于活动状态时，Claude Code 会搁置命名 `Monitor` 本身的允许规则，以及它删除的其他 [广泛允许规则](/docs/zh-CN/permission-modes#how-the-classifier-evaluates-actions)，因此分类器以与审查 Bash 命令相同的方式审查 Monitor 命令。

395| `url` | 是 | 要连接的端点。必须是 `ws://` 或 `wss://` URL，不包含嵌入的凭据或空格，仅使用 ASCII 字符 |400| `url` | 是 | 要连接的端点。必须是 `ws://` 或 `wss://` URL，不包含嵌入的凭据或空格，仅使用 ASCII 字符 |

396| `protocols` | 否 | 在握手期间提供的 WebSocket 子协议名称。每个条目必须是有效的子协议令牌，列表不能包含重复项 |401| `protocols` | 否 | 在握手期间提供的 WebSocket 子协议名称。每个条目必须是有效的子协议令牌，列表不能包含重复项 |

397 402

398`timeout_ms` 和 `persistent` 输入的行为与它们对命令的行为相同：除非设置了 `persistent`，否则监视在截止时间结束，`TaskStop` 会提前取消它。403`timeout_ms` 截止时间也适用于 WebSocket 监视：监视在截止时间结束，`TaskStop` 会提前取消它。

399 404

400打开 WebSocket 会提示批准；在 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 中，分类器会决定。该提示不提供跳过同一主机的未来提示的选项。405打开 WebSocket 会提示批准；在 [自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 中，分类器会决定。该提示不提供跳过同一主机的未来提示的选项。

401 406

573Claude Code 在使用 Claude API 而不是云提供商的您自己机器上的交互式终端会话中包含该工具。它在以下情况下省略该工具：578Claude Code 在使用 Claude API 而不是云提供商的您自己机器上的交互式终端会话中包含该工具。它在以下情况下省略该工具：

574 579

575* 非交互式 `-p` 运行和 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 会话，这些没有屏幕来查看队列580* 非交互式 `-p` 运行和 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 会话，这些没有屏幕来查看队列

576* 云会话，例如 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web)，无法在您的机器上写入队列581* [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 等云会话，无法在您的机器上写入队列

577* [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws)、[Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上的会话582* [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws)、[Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上的会话

578* 您设置 [`CLAUDE_CODE_SEND_FEEDBACK=0`](/docs/zh-CN/env-vars) 或 [`DISABLE_FEEDBACK_COMMAND=1`](/docs/zh-CN/env-vars) 的会话，将 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 设置为任何非空值，或关闭 [功能标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)583* 您设置 [`CLAUDE_CODE_SEND_FEEDBACK=0`](/docs/zh-CN/env-vars) 或 [`DISABLE_FEEDBACK_COMMAND=1`](/docs/zh-CN/env-vars) 的会话，将 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 设置为任何非空值，或关闭 [功能标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)

579* 已关闭产品反馈的组织，以及 [零数据保留的组织](/docs/zh-CN/zero-data-retention#features-disabled-under-zdr)584* 已关闭产品反馈的组织，以及 [零数据保留的组织](/docs/zh-CN/zero-data-retention#features-disabled-under-zdr)

609 614

610几个行为塑造了 Claude 接收的响应：615几个行为塑造了 Claude 接收的响应：

611 616

617* WebFetch 拒绝 `localhost` 和任何其他没有点的主机名，例如裸露的内网名称，在发出请求之前。它返回的[错误](/docs/zh-CN/errors#webfetch-cannot-fetch-localhost)告诉 Claude 通过 Bash 使用 `curl` 到达本地服务器。

612* HTTP URL 会自动升级到 HTTPS。618* HTTP URL 会自动升级到 HTTPS。

613* 大型页面在处理前会被截断到固定的字符限制。619* 大型页面在处理前会被截断到固定的字符限制。

614* WebFetch 默认缓存每个响应 15 分钟，所以重复获取同一 URL 会快速返回。在 Claude Code v2.1.233 或更高版本上，设置 [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/zh-CN/env-vars#variables) 以更改 WebFetch 保留每个响应的时长。620* WebFetch 默认缓存每个响应 15 分钟，所以重复获取同一 URL 会快速返回。在 Claude Code v2.1.233 或更高版本上，设置 [`CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS`](/docs/zh-CN/env-vars#variables) 以更改 WebFetch 保留每个响应的时长。

ultrareview.md +17 −10

Details

10 Ultrareview 是一个研究预览功能。该功能、定价和可用性可能会根据反馈而改变。该命令是 `/code-review ultra`。当 ultrareview 对您的账户可用时，`/ultrareview` 是一个别名。10 Ultrareview 是一个研究预览功能。该功能、定价和可用性可能会根据反馈而改变。该命令是 `/code-review ultra`。当 ultrareview 对您的账户可用时，`/ultrareview` 是一个别名。

11</Note>11</Note>

12 12

13Ultrareview 是在 Claude Code 网络基础设施上运行的深度代码审查。当您运行 `/code-review ultra` 时，Claude Code 在远程沙箱中启动一队审查代理来查找您的分支或拉取请求中的错误。13Ultrareview 是在 Anthropic 基础设施上运行的[云会话](/docs/zh-CN/claude-code-on-the-web)中进行的深度代码审查。当您运行 `/code-review ultra` 时，Claude Code 在云沙箱中启动一队审查代理来查找您的分支或拉取请求中的错误。

14 14

15与本地 `/code-review` 相比，ultrareview 提供：15与本地 `/code-review` 相比，ultrareview 提供：

16 16

17* **更高的信号质量**：每个报告的发现都经过独立复现和验证，因此结果专注于真实的错误而不是风格建议17* **更高的信号质量**：每个报告的发现都经过独立复现和验证，因此结果专注于真实的错误而不是风格建议

18* **更广泛的覆盖范围**：许多审查代理并行探索更改，这会发现本地审查可能遗漏的问题18* **更广泛的覆盖范围**：许多审查代理并行探索更改，这会发现本地审查可能遗漏的问题

~~19* **无本地资源使用**：审查完全在远程沙箱中运行，因此您的终端在运行时保持空闲，可用于其他工作~~19* **无本地资源使用**：审查完全在云沙箱中运行，因此您的终端在运行时保持空闲，可用于其他工作

20 20

21Ultrareview 需要使用 claude.ai 账户进行身份验证，因为它在 Claude Code 网络基础设施上运行。如果您仅使用 API 密钥登录，请先运行 `/login` 并使用 claude.ai 进行身份验证。当使用 Claude Code 与 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 时，Ultrareview 不可用，对于已启用零数据保留的组织也不可用。当 ultrareview 不可用时，`/code-review ultra` 会在您的会话中运行本地审查。21Ultrareview 需要使用 claude.ai 账户进行身份验证，因为它在 Anthropic 基础设施上作为云会话运行。如果您仅使用 API 密钥登录，请先运行 `/login` 并使用 claude.ai 进行身份验证。当使用 Claude Code 与 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 时，Ultrareview 不可用，对于已启用零数据保留的组织也不可用。当 ultrareview 不可用时，`/code-review ultra` 会在您的会话中运行本地审查。

22 22

23<h2 id="run-ultrareview-from-the-cli">23<h2 id="run-ultrareview-from-the-cli">

24 从 CLI 运行 ultrareview24 从 CLI 运行 ultrareview

32 32

33不带参数时，ultrareview 审查您当前分支与默认分支之间的差异，包括未提交和暂存的更改。对于名称类似凭证或密钥的文件（如 `.env` 和 `*.tfvars` 文件）中的未提交更改，Claude Code 遵循[将本地存储库上传到云会话](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github)的规则。33不带参数时，ultrareview 审查您当前分支与默认分支之间的差异，包括未提交和暂存的更改。对于名称类似凭证或密钥的文件（如 `.env` 和 `*.tfvars` 文件）中的未提交更改，Claude Code 遵循[将本地存储库上传到云会话](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github)的规则。

34 34

35对于分支审查，Claude Code 捆绑存储库状态并将其上传到远程沙箱；当您[审查拉取请求](#review-a-pull-request)时，Claude Code 不会从您的计算机上传任何内容。35对于分支审查，Claude Code 捆绑存储库状态并将其上传到云沙箱；当您[审查拉取请求](#review-a-pull-request)时，Claude Code 不会从您的计算机上传任何内容。

36 36

37启动前，Claude Code 显示一个确认对话框，其中包含审查范围、您剩余的免费运行次数和估计成本；对于分支审查，范围包括文件和行数。确认后，审查在后台继续进行，您可以继续使用您的会话。37启动前，Claude Code 显示一个确认对话框，其中包含审查范围、您剩余的免费运行次数和估计成本；对于分支审查，范围包括文件和行数。确认后，审查在后台继续进行，您可以继续使用您的会话。

38 38

62 62

63该命令也接受 `#1234`、`PR 1234` 和粘贴的 PR URL；粘贴的 URL 必须指向您当前目录中的存储库。63该命令也接受 `#1234`、`PR 1234` 和粘贴的 PR URL；粘贴的 URL 必须指向您当前目录中的存储库。

64 64

65在 PR 模式下，远程沙箱直接从主机克隆拉取请求，而不是捆绑您的本地工作树。PR 模式适用于 `github.com` 上的存储库以及 Owner 已连接到 Claude Code 的 [GitHub Enterprise Server](/docs/zh-CN/github-enterprise-server) 实例。65在 PR 模式下，云沙箱直接从主机克隆拉取请求，而不是捆绑您的本地工作树。PR 模式适用于 `github.com` 上的存储库以及 Owner 已连接到 Claude Code 的 [GitHub Enterprise Server](/docs/zh-CN/github-enterprise-server) 实例。

66 66

67对于 `github.com` 上的存储库，沙箱使用连接到您的 Claude 账户的 GitHub 账户进行克隆，因此该账户必须能够读取 PR 的存储库。Claude Code 在创建云会话之前检查这一点，除非您已设置 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-CN/env-vars#variables)，并在[未连接账户](/docs/zh-CN/errors#no-github-account-is-connected-to-your-claude-account)或[账户无法看到存储库](/docs/zh-CN/errors#your-connected-github-account-cant-see-the-repository)时拒绝启动；拒绝会说明修复方法。在 v2.1.248 之前，Claude Code 在启动前不检查这一点。67对于 `github.com` 上的存储库，沙箱使用连接到您的 Claude 账户的 GitHub 账户进行克隆，因此该账户必须能够读取 PR 的存储库。Claude Code 在创建云会话之前检查这一点，除非您已设置 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-CN/env-vars#variables)，并在[未连接账户](/docs/zh-CN/errors#no-github-account-is-connected-to-your-claude-account)或[账户无法看到存储库](/docs/zh-CN/errors#your-connected-github-account-cant-see-the-repository)时拒绝启动；拒绝会说明修复方法。在 v2.1.248 之前，Claude Code 在启动前不检查这一点。

68 68

79* **交互式**：在启动对话框中，选择**运行并将发现作为我发布到 PR**。如果您将 `--post` 添加到命令中，如 `/code-review ultra 1234 --post`，Claude Code 会预选该选择，但仍会在启动前询问。79* **交互式**：在启动对话框中，选择**运行并将发现作为我发布到 PR**。如果您将 `--post` 添加到命令中，如 `/code-review ultra 1234 --post`，Claude Code 会预选该选择，但仍会在启动前询问。

80* **非交互式**：使用 `--post` 运行 [`claude ultrareview` 子命令](#run-ultrareview-non-interactively)。通过使用该标志运行子命令，您同意发布，因此 Claude Code 会发布而不询问。在 `claude -p '/code-review ultra'` 运行中，Claude Code 在发现到达前退出，因此不会发布任何内容；改用子命令。80* **非交互式**：使用 `--post` 运行 [`claude ultrareview` 子命令](#run-ultrareview-non-interactively)。通过使用该标志运行子命令，您同意发布，因此 Claude Code 会发布而不询问。在 `claude -p '/code-review ultra'` 运行中，Claude Code 在发现到达前退出，因此不会发布任何内容；改用子命令。

81 81

82Claude Code 不会从您的计算机发布。它将发现发送到 [Claude Code on the web](/docs/zh-CN/claude-code-on-the-web) 上的会话，该会话通过您连接到 Claude 的 GitHub 账户发布评论。发布需要与审查本身相同的 claude.ai 登录。由于发布通过 Claude Code on the web 运行，它在第三方提供商上或当您设置 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-CN/env-vars) 时不可用。82Claude Code 不会从您的计算机发布。它将审查的会话 ID 发送到 Anthropic API，该 API 通过您连接到 Claude 的 GitHub 账户将审查的存储发现作为评论发布。发布需要与审查本身相同的 claude.ai 登录，并且在第三方提供商上或当您设置 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-CN/env-vars) 时不可用。

83 83

84在交互式会话中，Claude Code 在发现到达时启动发布，因此请保持会话打开直到审查完成。Claude Code 仅在该会话中保留发布选择。如果会话在审查完成前结束，Claude Code 不会发布任何内容，即使您稍后恢复对话。84在交互式会话中，Claude Code 在发现到达时启动发布，因此请保持会话打开直到审查完成。Claude Code 仅在该会话中保留发布选择。如果会话在审查完成前结束，Claude Code 不会发布任何内容，即使您稍后恢复对话。

85 85

~~86当发布无法在您的会话打开时启动时，Claude 会告诉您没有任何内容发送到 PR 以及原因，发现会保留在您的终端中，以便您可以手动发布。~~86当发布完成时，Claude 会告诉您结果：

88* **已发布**：Claude 为您提供评论的链接。

89* **已发布**：同一审查的早期发布已将评论放在 PR 上，因此 Claude 会链接您到拉取请求，而不是再次发布。

90* **失败**：Claude 会告诉您原因，发现会保留在您的终端中，以便您可以手动发布。

87 91

88<h3 id="pass-a-request-in-plain-words">92<h3 id="pass-a-request-in-plain-words">

89 用纯文本传递请求93 用纯文本传递请求

185 189

186如果您中断子命令，远程审查会继续运行；按照打印到 stderr 的会话 URL 在浏览器中观看它。190如果您中断子命令，远程审查会继续运行；按照打印到 stderr 的会话 URL 在浏览器中观看它。

187 191

188使用 `--post` 时，子命令在打印发现后立即开始发布。如果运行失败、超时或您中断它，子命令不发布任何内容。如果审查完成但发布无法启动，Claude Code 将原因打印到 stderr，发现保留在 stdout 上，以便您可以手动发布它们。192使用 `--post` 时，子命令在打印发现后立即开始发布，并将链接打印到 stderr。

193

194* 如果运行失败、超时或您中断它，子命令不发布任何内容。

195* 如果审查完成但注释未发布，Claude Code 将原因打印到 stderr，发现保留在 stdout 上，以便您可以手动发布它们。

189 196

190对于 GitHub 拉取请求上的自动审查，[Code Review](/docs/zh-CN/code-review) 直接与您的存储库集成，并将发现作为内联 PR 注释发布，无需 CLI 步骤。197对于 GitHub 拉取请求上的自动审查，[Code Review](/docs/zh-CN/code-review) 直接与您的存储库集成，并将发现作为内联 PR 注释发布，无需 CLI 步骤。

191 198

199| ---- | ------------------------- | ------------------------------- |206| ---- | ------------------------- | ------------------------------- |

200| 目标 | 您的工作差异、pull request、分支或路径 | 您的工作差异或 pull request |207| 目标 | 您的工作差异、pull request、分支或路径 | 您的工作差异或 pull request |

202| 深度 | 随着 effort 参数扩展 | 具有独立验证的多代理队列 |209| 深度 | 随着 effort 参数扩展 | 具有独立验证的多代理队列 |

204| 成本 | 计入正常使用量 | 免费运行，然后大约 \$5 到 \$25 每次审查作为使用额度 |211| 成本 | 计入正常使用量 | 免费运行，然后大约 \$5 到 \$25 每次审查作为使用额度 |

210 相关资源217 相关资源

211</h2>218</h2>

212 219

213* [Claude Code 网络版](/docs/zh-CN/claude-code-on-the-web)：了解远程会话和云沙箱如何工作220* [在云端使用 Claude Code](/docs/zh-CN/claude-code-on-the-web)：了解云会话和云沙箱如何工作

214* [有效管理成本](/docs/zh-CN/costs)：跟踪使用情况并设置支出限制221* [有效管理成本](/docs/zh-CN/costs)：跟踪使用情况并设置支出限制

voice-dictation.md +1 −1

Details

17语音听写将你录制的音频流传输到 Anthropic 的服务器进行转录。音频不在本地处理。它需要以下所有条件：17语音听写将你录制的音频流传输到 Anthropic 的服务器进行转录。音频不在本地处理。它需要以下所有条件：

18 18

19* **一个 Claude.ai 账户**：语音转文本服务仅在你使用 Claude.ai 账户进行身份验证时可用，当 Claude Code 配置为直接使用 Anthropic API 密钥、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 时不可用。19* **一个 Claude.ai 账户**：语音转文本服务仅在你使用 Claude.ai 账户进行身份验证时可用，当 Claude Code 配置为直接使用 Anthropic API 密钥、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 时不可用。

~~20* **一个本地麦克风**：语音听写在远程环境中不起作用，例如[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)或 SSH 会话。~~20* **一个本地麦克风**：语音听写在[云会话](/docs/zh-CN/claude-code-on-the-web)或 SSH 会话中不起作用。

21* **如果你在 WSL 中运行 Claude Code，则需要 WSLg**：WSLg 包含在 Windows 10 或 11 上从 Microsoft Store 安装的 WSL2 中。如果 WSLg 不可用，例如在 WSL1 上，改为在本机 Windows 中运行 Claude Code。21* **如果你在 WSL 中运行 Claude Code，则需要 WSLg**：WSLg 包含在 Windows 10 或 11 上从 Microsoft Store 安装的 WSL2 中。如果 WSLg 不可用，例如在 WSL1 上，改为在本机 Windows 中运行 Claude Code。

22 22

23转录不消耗 Claude 消息或令牌，也不计入 `/usage` 中显示的限制。有关 Anthropic 如何处理你的数据，请参阅[数据使用](/docs/zh-CN/data-usage)。23转录不消耗 Claude 消息或令牌，也不计入 `/usage` 中显示的限制。有关 Anthropic 如何处理你的数据，请参阅[数据使用](/docs/zh-CN/data-usage)。

vs-code.md +15 −4

Details

125 125

126 Claude 的最新待办事项列表保持可见，Claude 提出的待处理问题的文本也保持可见；这需要 Claude Code v2.1.225 或更高版本。当 Claude 运行[子代理](/docs/zh-CN/sub-agents)时，带有其最新活动的实时进度行出现在启动它们的工具调用组下。这需要 Claude Code v2.1.269 或更高版本。126 Claude 的最新待办事项列表保持可见，Claude 提出的待处理问题的文本也保持可见；这需要 Claude Code v2.1.225 或更高版本。当 Claude 运行[子代理](/docs/zh-CN/sub-agents)时，带有其最新活动的实时进度行出现在启动它们的工具调用组下。这需要 Claude Code v2.1.269 或更高版本。

127 * 要报告错误，请点击菜单底部的 **Report a problem**，或输入 `/bug` 或 `/feedback` 以及可选的描述来预填充报告。当您提交报告并且您在第一方连接上登录到 Anthropic 时，Claude Code 会将其发送给 Anthropic。在第三方提供商上，或没有 Anthropic 凭证的情况下，对话框仍会打开，但提交会显示错误并不发送任何内容：与 CLI 的 `/bug` 不同，扩展程序不会写入本地存档。需要 Claude Code v2.1.229 或更高版本。127 * 要报告错误，请点击菜单底部的 **Report a problem**，或输入 `/bug` 或 `/feedback` 以及可选的描述来预填充报告。当您提交报告并且您在第一方连接上登录到 Anthropic 时，Claude Code 会将其发送给 Anthropic。在第三方提供商上，或没有 Anthropic 凭证的情况下，对话框仍会打开，但提交会显示错误并不发送任何内容：与 CLI 的 `/bug` 不同，扩展程序不会写入本地存档。需要 Claude Code v2.1.229 或更高版本。

128

129 如果您的组织的策略关闭了产品反馈，**Report a problem** 不会出现在菜单中，`/bug` 和 `/feedback` 会显示 `Feedback is turned off by your organization's policy or this environment's settings.` 通知，而不是打开报告。

128* **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 或更高版本。130* **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 或更高版本。

129* **Context indicator**：提示框显示您使用了多少 Claude 的上下文窗口。Claude 在需要时自动压缩，或者您可以手动运行 `/compact`。131* **Context indicator**：提示框显示您使用了多少 Claude 的上下文窗口。Claude 在需要时自动压缩，或者您可以手动运行 `/compact`。

132* **Prompt cache clock**：上下文指示器旁边的时钟图标估计对话的 [prompt cache](/docs/zh-CN/prompt-caching) 在过期前还剩多少时间。它从缓存的五分钟或一小时[生命周期](/docs/zh-CN/prompt-caching#cache-lifetime)倒计时，每个使用缓存的响应都会重新启动倒计时。除了压缩外，[使缓存失效的操作](/docs/zh-CN/prompt-caching#actions-that-invalidate-the-cache)不会重置时钟，因此在您切换模型后它仍然可以显示剩余的分钟数。

133 * 在倒计时结束之前，图标显示剩余的分钟数，例如 **12m**。

134 * 当倒计时结束时，分钟消失，图标变为红色，或您主题的错误颜色，直到下一个响应。缓存可能已过期，因此在缓存重建时，您对下一条消息的响应可能会更慢、更昂贵。如果五分钟的生命周期在您的消息之间不断耗尽，请参阅[自己选择 TTL](/docs/zh-CN/prompt-caching#choose-the-ttl-yourself)。

135 * 在对话[压缩](/docs/zh-CN/prompt-caching#compacting-the-conversation)后，图标也会变为红色，没有分钟直到下一个响应，因为缓存还不覆盖压缩的对话。

130* **Agent map**：当对话包括[子代理](/docs/zh-CN/sub-agents)时，代理计数（例如 **2 agents**）出现在提示框的底部。其点显示任何子代理是否正在工作或等待您的权限。136* **Agent map**：当对话包括[子代理](/docs/zh-CN/sub-agents)时，代理计数（例如 **2 agents**）出现在提示框的底部。其点显示任何子代理是否正在工作或等待您的权限。

131 137

132 点击代理计数来打开代理地图，它将对话的子代理绘制为主代理下的树，每个都有其状态、经过的时间和令牌计数。点击子代理来查看其提示和工具调用、打开其只读记录，或在其运行时停止它。需要 Claude Code v2.1.269 或更高版本。138 点击代理计数来打开代理地图，它将对话的子代理绘制为主代理下的树，每个都有其状态、经过的时间和令牌计数。点击子代理来查看其提示和工具调用、打开其只读记录，或在其运行时停止它。需要 Claude Code v2.1.269 或更高版本。

146 152

147对于大型 PDF，您可以要求 Claude 读取特定页面而不是整个文件：单个页面、范围如第 1-10 页，或开放式范围如第 3 页及以后。153对于大型 PDF，您可以要求 Claude 读取特定页面而不是整个文件：单个页面、范围如第 1-10 页，或开放式范围如第 3 页及以后。

148 154

149当您在编辑器中选择文本时，Claude 可以自动看到您突出显示的代码。提示框页脚显示选择了多少行。按 `Option+K`（Mac）/ `Alt+K`（Windows/Linux）来插入带有文件路径和行号的 @-mention（例如 `@app.ts#5-10`）。点击选择指示器上的 **X** 来删除它，这样 Claude 就不会收到选择。当您选择其他文本或切换到不同的文件时，指示器会重新出现。155当您在编辑器中选择文本时，Claude 可以自动看到您突出显示的代码。提示框页脚显示选择了多少行。按 `Option+K`（Mac）/ `Alt+K`（Windows/Linux）来插入带有文件路径和行号的 @-mention（例如 `@app.ts#5-10`）。点击选择指示器上的 **X** 来删除它，这样 Claude 就不会收到选择。当您选择其他文本时，指示器会重新出现。

156

157Claude 也会看到您在编辑器中打开的文件，即使没有选择任何内容，提示框也会显示其名称。要仅添加您选择的文本，请关闭[附加打开文件设置](vscode://settings/claudeCode.attachOpenFile)。该设置需要 Claude Code v2.1.271 或更高版本。

150 158

151要附加图像，请从剪贴板将其粘贴到提示框中。您也可以在将文件拖入提示框时按住 `Shift` 来将它们添加为附件。点击任何附件上的 X 来从上下文中删除它。159要附加图像，请从剪贴板将其粘贴到提示框中。您也可以在将文件拖入提示框时按住 `Shift` 来将它们添加为附件。点击任何附件上的 X 来从上下文中删除它。

152 160

165 173

166要恢复存档的会话，请展开 **Archived sessions** 并点击 **Unarchive session**。在 v2.1.257 之前，该操作是 **Delete session**，它隐藏了一个会话而无法恢复。您之前删除的会话在升级后会出现在 **Archived sessions** 下。174要恢复存档的会话，请展开 **Archived sessions** 并点击 **Unarchive session**。在 v2.1.257 之前，该操作是 **Delete session**，它隐藏了一个会话而无法恢复。您之前删除的会话在升级后会出现在 **Archived sessions** 下。

167 175

168当您恢复的对话以计划模式结束时，Claude Code 会恢复计划模式。需要 Claude Code v2.1.246 或更高版本。Claude Code 在两种情况下不会恢复它：176当您恢复的对话以 Plan 模式结束时，Claude Code 会恢复 Plan 模式。需要 Claude Code v2.1.246 或更高版本。Claude Code 在两种情况下不会恢复它：

169 177

170* 扩展程序从 `claudeCode.initialPermissionMode` 或从较早对话中继承的选择[选择起始权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)178* 扩展程序从 `claudeCode.initialPermissionMode` 或从较早对话中继承的选择[选择起始权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)

171* 您配置了 `claudeCode.claudeProcessWrapper`179* 您配置了 `claudeCode.claudeProcessWrapper`

174 从 Claude.ai 恢复云会话182 从 Claude.ai 恢复云会话

175</h3>183</h3>

176 184

177如果您使用[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)，您可以直接在 VS Code 中恢复这些云会话。这需要使用 **Claude.ai Subscription** 登录，而不是 Anthropic Console。185如果您运行[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)，您可以直接在 VS Code 中恢复这些云会话。这需要使用 **Claude.ai Subscription** 登录，而不是 Anthropic Console。

178 186

179<Steps>187<Steps>

180 <Step title="打开会话历史">188 <Step title="打开会话历史">

450| `initialPermissionMode` | - | 控制新对话的批准提示：`default`、`plan`、`acceptEdits` 或 `bypassPermissions`。`manual` 是 `default` 的别名，选择模式指示器中标记为 **Manual** 的模式。当您将其留空时，扩展会选择起始权限模式，如[切换权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)中所述。 |458| `initialPermissionMode` | - | 控制新对话的批准提示：`default`、`plan`、`acceptEdits` 或 `bypassPermissions`。`manual` 是 `default` 的别名，选择模式指示器中标记为 **Manual** 的模式。当您将其留空时，扩展会选择起始权限模式，如[切换权限模式](/docs/zh-CN/permission-modes#switch-permission-modes)中所述。 |

461| `attachOpenFile` | `true` | 将编辑器中打开的文件添加到您的消息中，并在提示框中显示它。关闭时，仅添加您选择的文本。需要 Claude Code v2.1.271 或更高版本 |

494| MCP server config | 是 | 是（在聊天面板中使用 `/mcp` [添加和管理服务器](#connect-to-external-tools-with-mcp)） |503| MCP server config | 是 | 是（在聊天面板中使用 `/mcp` [添加和管理服务器](#connect-to-external-tools-with-mcp)） |

495| Checkpoints | 是 | 是 |504| Checkpoints | 是 | 是 |

496| `!` bash shortcut | 是 | 否 |505| `!` Bash shortcut | 是 | 否 |

497| Tab completion | 是 | 否 |506| Tab completion | 是 | 否 |

498 507

499<h3 id="rewind-with-checkpoints">508<h3 id="rewind-with-checkpoints">

625 634

626**选择和打开文件上下文。** 连接时，CLI 会在您发送的每个提示中包含您当前的编辑器选择和活动文件的路径作为上下文。当发生这种情况时，记录会显示一行 `⧉ Selected N lines from <file>`。要排除敏感文件（如 `.env`），请为其路径添加 [`Read` 拒绝规则](/docs/zh-CN/permissions#read-and-edit)。匹配的拒绝规则可防止该文件的选定文本和打开文件通知到达 Claude。635**选择和打开文件上下文。** 连接时，CLI 会在您发送的每个提示中包含您当前的编辑器选择和活动文件的路径作为上下文。当发生这种情况时，记录会显示一行 `⧉ Selected N lines from <file>`。要排除敏感文件（如 `.env`），请为其路径添加 [`Read` 拒绝规则](/docs/zh-CN/permissions#read-and-edit)。匹配的拒绝规则可防止该文件的选定文本和打开文件通知到达 Claude。

627 636

637如果您关闭[附加打开文件设置](#extension-settings)，CLI 仅在您在该文件中选择文本时接收活动文件的路径。

638

628**传输和身份验证。** 服务器绑定到 `127.0.0.1` 上的随机端口，范围在 10000–65535，端口不可配置。传输是未加密的 `ws://`；因为套接字仅限于本地回环，任何可以捕获流量的进程也可以从锁文件中读取令牌，所以 TLS 不会增加保护。每次扩展激活都会生成一个新的随机身份验证令牌，将其写入 `~/.claude/ide/<port>.lock` 处的锁文件，CLI 必须将其作为 `X-Claude-Code-Ide-Authorization` 标头呈现才能连接。锁文件在 `0700` 目录中具有 `0600` 权限，因此只有运行 VS Code 的用户才能读取它。如果设置了 `CLAUDE_CONFIG_DIR`，锁文件将写入 `$CLAUDE_CONFIG_DIR/ide/` 目录。639**传输和身份验证。** 服务器绑定到 `127.0.0.1` 上的随机端口，范围在 10000–65535，端口不可配置。传输是未加密的 `ws://`；因为套接字仅限于本地回环，任何可以捕获流量的进程也可以从锁文件中读取令牌，所以 TLS 不会增加保护。每次扩展激活都会生成一个新的随机身份验证令牌，将其写入 `~/.claude/ide/<port>.lock` 处的锁文件，CLI 必须将其作为 `X-Claude-Code-Ide-Authorization` 标头呈现才能连接。锁文件在 `0700` 目录中具有 `0600` 权限，因此只有运行 VS Code 的用户才能读取它。如果设置了 `CLAUDE_CONFIG_DIR`，锁文件将写入 `$CLAUDE_CONFIG_DIR/ide/` 目录。

629 640

630**暴露给模型的工具。** 服务器托管十几个工具，但只有两个对模型可见。其余的是 CLI 用于自己的 UI 的内部 RPC——打开 diff、读取选择、保存文件——在工具列表到达 Claude 之前被过滤掉。641**暴露给模型的工具。** 服务器托管十几个工具，但只有两个对模型可见。其余的是 CLI 用于自己的 UI 的内部 RPC——打开 diff、读取选择、保存文件——在工具列表到达 Claude 之前被过滤掉。

web-quickstart.md +32 −26

Details

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

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

4 4

~~5# 在网络上开始使用 Claude Code~~5# 在云中开始使用 Claude Code

6 6

7> 从浏览器或手机在云中运行 Claude Code。连接 GitHub 仓库、提交任务，并在无需本地设置的情况下审查 PR。7> 从浏览器或手机在云中运行 Claude Code。连接 GitHub 仓库、提交任务，并在无需本地设置的情况下审查 PR。

8 8

9<Note>9<Note>

~~10 Claude Code on the web 处于研究预览阶段，适用于 Pro、Max 和 Team 用户，以及拥有高级席位或 Chat + Claude Code 席位的企业用户。~~10 云会话处于研究预览阶段，适用于 Pro、Max 和 Team 用户，以及拥有高级席位或 Chat + Claude Code 席位的企业用户。

11</Note>11</Note>

12 12

13Claude Code on the web 在 Anthropic 管理的云基础设施上运行，而不是在您的机器上。从浏览器中的 [claude.ai/code](https://claude.ai/code) 或 Claude 移动应用提交任务。13云会话在云基础设施上运行 Claude Code，而不是在您的机器上，默认由 Anthropic 管理。此快速入门从浏览器中的 [claude.ai/code](https://claude.ai/code) 启动一个会话。您也可以从 Claude 移动应用、Desktop 应用或终端使用 `claude --cloud` 启动一个会话。

14 14

15您需要一个 GitHub 仓库来[开始使用](#connect-github)。Claude 将其克隆到隔离的虚拟机中，进行更改，并为您推送一个分支以供审查。会话在设备间持久化，因此您在笔记本电脑上开始的任务稍后可以从手机上审查。15您需要一个 GitHub 仓库来[开始使用](#connect-github)。Claude 将其克隆到隔离的虚拟机中，进行更改，并为您推送一个分支以供审查。会话在设备间持久化，因此您在笔记本电脑上开始的任务稍后可以从手机上审查。

16 16

~~17Claude Code on the web 适用于：~~17云会话适用于：

18 18

19* **并行任务**：同时运行多个独立任务，每个任务在自己的会话和分支中，无需管理多个 worktrees19* **并行任务**：同时运行多个独立任务，每个任务在自己的会话和分支中，无需管理多个 worktrees

20* **您本地没有的仓库**：Claude 在每个会话中新鲜克隆仓库，因此您无需检出它20* **您本地没有的仓库**：Claude 在每个会话中新鲜克隆仓库，因此您无需检出它

40 比较运行 Claude Code 的方式40 比较运行 Claude Code 的方式

41</h2>41</h2>

42 42

43Claude Code 在任何地方的行为都相同。改变的是代码执行的位置以及您的本地配置是否可用。Desktop 应用提供本地和云会话，因此其下面的答案取决于您选择的是哪一个：43Claude Code 在任何地方的行为都相同。改变的是会话运行的位置以及您的本地配置是否可用：

44 44

~~46| :---------------------------------- | :--------------------------------------------------------------------------------------------- | :-------------- | :----------- | :------------- |~~46| :---------------------------------- | :--------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------- | :--------------------------------------------------------- |

49| **使用您的本地配置** | 否，仅限仓库 | 是 | 是 | 本地为是，云为否 |49| **您从以下位置聊天** | claude.ai、移动应用，或 Desktop 应用 | 您启动它的位置 | claude.ai 或移动应用，以及您启动它的位置 |

50| **需要 GitHub** | 是，或通过 `--cloud` [捆绑本地仓库](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) | 否 | 否 | 仅限云会话 |50| **使用您的本地配置** | 否，仅限仓库 | 是 | 是 |

51| **断开连接时继续运行** | 是 | 当终端保持打开时 | 否 | 取决于会话类型 |51| **需要 GitHub** | 是，或通过 `--cloud` [捆绑本地仓库](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) | 否 | 否 |

52| **[权限模式](/docs/zh-CN/permission-modes)** | 接受编辑、Plan、自动 | 询问、自动接受编辑、Plan | 所有模式 | 取决于会话类型 |52| **断开连接时继续运行** | 是 | 否 | 当会话在您的机器上保持打开时 |

54 55

~~55请参阅[终端快速入门](/docs/zh-CN/quickstart)、[Desktop 应用](/docs/zh-CN/desktop)或 [Remote Control](/docs/zh-CN/remote-control) 文档来设置这些。~~56请参阅[终端快速入门](/docs/zh-CN/quickstart)、[Desktop 应用](/docs/zh-CN/desktop)或 [Remote Control](/docs/zh-CN/remote-control) 文档来设置本地会话。

56 57

57<h2 id="connect-github">58<h2 id="connect-github">

58 连接 GitHub59 连接 GitHub

66 67

67<Steps>68<Steps>

68 <Step title="访问 claude.ai/code">69 <Step title="访问 claude.ai/code">

69 转到 [claude.ai/code](https://claude.ai/code)并使用您的 claude.ai 账户登录。在 macOS 或 Windows 上，第一个屏幕提供 Claude Code 桌面应用和其他安装 Claude Code 的方式。要留在浏览器中，请单击页面底部的**Continue on web**。70 转到 [claude.ai/code](https://claude.ai/code)并使用您的 claude.ai 账户登录。

70 </Step>71 </Step>

71 72

72 <Step title="使用 GitHub 登录">73 <Step title="使用 GitHub 登录">

73 登录后，claude.ai/code 会提示您连接 GitHub。按照提示操作，claude.ai/code 会将您发送到 GitHub 的授权页面。批准授权请求，GitHub 会将您返回到 claude.ai/code。云会话可以与现有 GitHub 存储库配合使用。要启动新项目，请先[在 GitHub 上创建一个空存储库](https://github.com/new)。74 登录后，claude.ai/code 会提示您连接 GitHub。按照提示操作，claude.ai/code 会将您发送到 GitHub 的授权页面。批准授权请求，GitHub 会将您返回到 claude.ai/code。云会话可以与现有 GitHub 存储库配合使用。要启动新项目，请先[在 GitHub 上创建一个空存储库](https://github.com/new)。

74 75

75 通过此连接，会话可以克隆任何公共存储库，但只有在 Claude GitHub App 安装在私有存储库上时，才能在私有存储库中工作。[安装应用](https://github.com/apps/claude/installations/new)到您想要使用其私有存储库的每个 GitHub 账户或组织。在 GitHub 组织上，组织所有者可能需要批准安装。安装应用还会启用[Auto-fix](/docs/zh-CN/claude-code-on-the-web#auto-fix-pull-requests)，这让 Claude 能够响应这些存储库中拉取请求的 CI 失败和审查评论。76 通过此连接，会话可以克隆任何公共存储库，但只有在 Claude GitHub App 安装在私有存储库上时，才能在私有存储库中工作。[安装 Claude GitHub App](https://github.com/apps/claude/installations/new) 到您想要使用其私有存储库的每个 GitHub 账户或组织。在 GitHub 组织上，组织所有者可能需要批准安装。安装应用还会启用[Auto-fix](/docs/zh-CN/claude-code-on-the-web#auto-fix-pull-requests)，这让 Claude 能够响应这些存储库中拉取请求的 CI 失败和审查评论。

76 77

~~77 如果入门流程在此时提示您安装应用，而您想稍后再做，请单击**Skip**。~~78 如果入门流程在此时提示您安装 Claude GitHub App，而您想稍后再做，请单击**Skip**。

78 </Step>79 </Step>

79 80

80 <Step title="设置您的默认环境">81 <Step title="设置您的默认环境">

93 从终端连接94 从终端连接

94</h3>95</h3>

95 96

96如果您已经使用 GitHub CLI (`gh`)，可以从终端设置 Claude Code on the web。这需要[Claude Code CLI](/docs/zh-CN/quickstart)。在 Team 和 Enterprise 计划上，只有在所有者打开[Quick web setup](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)后，`/web-setup` 才可用。97如果您已经使用 GitHub CLI (`gh`)，可以从终端为云会话连接 GitHub。这需要[Claude Code CLI](/docs/zh-CN/quickstart)。在 Team 和 Enterprise 计划上，只有在所有者打开[Quick web setup](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)后，`/web-setup` 才可用。

97 98

98运行 `/web-setup` 时，Claude Code 读取 `gh auth token` 打印的令牌，要求您确认，并将令牌发送给 Anthropic。Anthropic 使用您的 claude.ai 账户加密存储它，您的云会话使用它进行 GitHub 访问，直到您[删除它](#remove-the-web-setup-token)。云会话随后可以访问该令牌可以访问的任何存储库，无需安装 Claude GitHub App。99运行 `/web-setup` 时，Claude Code 读取 `gh auth token` 打印的令牌，要求您确认，并将令牌发送给 Anthropic。Anthropic 使用您的 claude.ai 账户加密存储它，您的云会话使用它进行 GitHub 访问，直到您[删除它](#remove-the-web-setup-token)。您自己启动的云会话随后可以访问该令牌可以访问的任何存储库，无需安装 Claude GitHub App。[项目](/docs/zh-CN/claude-projects#set-up-github-access)中的线程仍然需要该应用。

99 100

100如果您已经在浏览器中连接了 GitHub，`/web-setup` 会警告您继续将替换您的云会话的该连接。101如果您已经在浏览器中连接了 GitHub，`/web-setup` 会警告您继续将替换您的云会话的该连接。

101 102

123 /web-setup124 /web-setup

124 ```125 ```

125 126

126 确认提示以将您的 `gh` 令牌发送到您的 Claude 账户。成功后，Claude Code 打印 `Connected as <your-github-username>` 并在您的浏览器中打开 [claude.ai/code](https://claude.ai/code)。如果您还没有云环境，`/web-setup` 会创建一个具有 Trusted 网络访问且没有设置脚本的环境。您可以[稍后编辑环境或添加变量](/docs/zh-CN/cloud-environments#configure-your-environment)。`/web-setup` 完成后，您可以使用 [`--cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-web) 从终端启动云会话，或使用 [`/schedule`](/docs/zh-CN/routines) 设置定期任务。127 确认提示以将您的 `gh` 令牌发送到您的 Claude 账户。成功后，Claude Code 打印 `Connected as <your-github-username>` 并在您的浏览器中打开 [claude.ai/code](https://claude.ai/code)。如果您还没有云环境，`/web-setup` 会创建一个具有 Trusted 网络访问且没有设置脚本的环境。您可以[稍后编辑环境或添加变量](/docs/zh-CN/cloud-environments#configure-your-environment)。`/web-setup` 完成后，您可以使用 [`--cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud) 从终端启动云会话，或使用 [`/schedule`](/docs/zh-CN/routines) 设置定期任务。

127 </Step>128 </Step>

128</Steps>129</Steps>

129 130

226 页面仅显示 GitHub 登录按钮227 页面仅显示 GitHub 登录按钮

227</h3>228</h3>

228 229

229云会话需要连接的 GitHub 账户。通过上面的浏览器流程连接，或如果您使用 GitHub CLI，从您的终端运行 `/web-setup`。如果您根本不想连接 GitHub，请参阅 [Remote Control](/docs/zh-CN/remote-control) 以在您自己的机器上运行 Claude Code 并从网络监控它。230云会话需要连接的 GitHub 账户。通过上面的浏览器流程连接，或如果您使用 GitHub CLI，从您的终端运行 `/web-setup`。如果您根本不想连接 GitHub，请参阅 [Remote Control](/docs/zh-CN/remote-control) 以在您自己的机器上运行 Claude Code 并从浏览器或手机监控它。

230 231

231<h3 id="not-available-for-the-selected-organization">232<h3 id="not-available-for-the-selected-organization">

232 "Not available for the selected organization"233 "Not available for the selected organization"

233</h3>234</h3>

234 235

235企业组织可能需要管理员启用 Claude Code on the web。联系您的 Anthropic 账户团队。236企业组织可能需要所有者启用云会话。联系您的 Anthropic 账户团队。

236 237

237<h3 id="/web-setup-says-not-signed-in-to-claude">238<h3 id="/web-setup-says-not-signed-in-to-claude">

238 `/web-setup` 说 "Not signed in to Claude"239 `/web-setup` 说 "Not signed in to Claude"

254 255

255如果您在 Claude Code 内输入它，命令菜单显示 `No commands match "/web-setup"`，或提交它返回 `Unknown command: /web-setup`，该命令被隐藏是因为未满足要求。原因通常是您使用 API 密钥或第三方提供商而不是 claude.ai 订阅进行身份验证。运行 `/login` 以使用您的 claude.ai 账户登录。256如果您在 Claude Code 内输入它，命令菜单显示 `No commands match "/web-setup"`，或提交它返回 `Unknown command: /web-setup`，该命令被隐藏是因为未满足要求。原因通常是您使用 API 密钥或第三方提供商而不是 claude.ai 订阅进行身份验证。运行 `/login` 以使用您的 claude.ai 账户登录。

256 257

257在 Team 和 Enterprise 计划上，该命令默认被隐藏：[快速网络设置切换](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)关闭，直到所有者打开它。当它关闭时，[从浏览器连接 GitHub](#connect-github) 代替。当管理员为您的组织禁用 Claude Code on the web 时，或当您的 Enterprise 组织启用了[零数据保留](/docs/zh-CN/zero-data-retention)（这使 Claude Code on the web 不可用）时，该命令也被隐藏。258在 Team 和 Enterprise 计划上，该命令默认被隐藏：[快速网络设置切换](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)关闭，直到所有者打开它。当它关闭时，[从浏览器连接 GitHub](#connect-github) 代替。

259

260该命令在另外两种情况下也被隐藏：

261

262* 管理员为您的组织禁用了云会话。在这种情况下，提交 `/web-setup` 返回 [`Cloud sessions are disabled by your organization's policy`](/docs/zh-CN/errors#cloud-sessions-are-disabled-by-your-organizations-policy)。在 v2.1.268 之前，这种情况也返回 `Unknown command: /web-setup`。

263* 您的 Enterprise 组织启用了[零数据保留](/docs/zh-CN/zero-data-retention)，这使云会话不可用。

258 264

259<h3 id="could-not-create-a-cloud-environment-or-no-cloud-environment-available-when-using-cloud">265<h3 id="could-not-create-a-cloud-environment-or-no-cloud-environment-available-when-using-cloud">

260 使用 `--cloud` 时出现 "Could not create a cloud environment" 或 "No cloud environment available"266 使用 `--cloud` 时出现 "Could not create a cloud environment" 或 "No cloud environment available"

261</h3>267</h3>

262 268

263远程会话功能如果您没有云环境，会自动创建一个默认的云环境。如果您看到 "Could not create a cloud environment"，自动创建失败。如果您看到 "No cloud environment available"，您的 CLI 早于自动创建。在任何一种情况下，在 Claude Code CLI 中运行 `/web-setup`，或从 [claude.ai/code](https://claude.ai/code) 的[环境选择器](/docs/zh-CN/cloud-environments#configure-your-environment)添加环境。269云会话功能如果您没有云环境，会自动创建一个默认的云环境。如果您看到 "Could not create a cloud environment"，自动创建失败。如果您看到 "No cloud environment available"，您的 CLI 早于自动创建。在任何一种情况下，在 Claude Code CLI 中运行 `/web-setup`，或从 [claude.ai/code](https://claude.ai/code) 的[环境选择器](/docs/zh-CN/cloud-environments#configure-your-environment)添加环境。

264 270

265<h3 id="setup-script-failed">271<h3 id="setup-script-failed">

266 设置脚本失败272 设置脚本失败

302* [配置云环境](/docs/zh-CN/cloud-environments)：网络访问级别、环境变量和云会话的设置脚本308* [配置云环境](/docs/zh-CN/cloud-environments)：网络访问级别、环境变量和云会话的设置脚本

303* [Routines](/docs/zh-CN/routines)：按计划、通过 API 调用或响应 GitHub 事件自动化工作309* [Routines](/docs/zh-CN/routines)：按计划、通过 API 调用或响应 GitHub 事件自动化工作

304* [CLAUDE.md](/docs/zh-CN/memory)：给 Claude 持久指令和上下文，在每个会话开始时加载310* [CLAUDE.md](/docs/zh-CN/memory)：给 Claude 持久指令和上下文，在每个会话开始时加载

305* 为 [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 或 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) 安装 Claude 移动应用以从您的手机监控会话。从 Claude Code CLI，`/mobile` 显示 QR 码。311* 为 [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) 或 [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) 安装 Claude 移动应用以从您的手机监控会话。从 Claude Code CLI，`/mobile` 显示 QR 码，用于 [claude.ai/mobile](https://claude.ai/mobile)，该码会为您的手机打开正确的应用商店。

whats-new.md +24 −0

Details

8 8

9每周开发摘要突出了最有可能改变您工作方式的功能。每个条目都包括可运行的代码、简短的演示和完整文档的链接。有关每个错误修复和次要改进，请参阅[更新日志](/docs/en/changelog)。9每周开发摘要突出了最有可能改变您工作方式的功能。每个条目都包括可运行的代码、简短的演示和完整文档的链接。有关每个错误修复和次要改进，请参阅[更新日志](/docs/en/changelog)。

10 10

11<Update label="Week 37" description="September 7–11, 2026" tags={["v2.1.263–v2.1.269"]}>

12 **`claude plugin eval`**：针对一套测试用例运行您的插件，对结果进行评分，并与无插件基线进行比较。`claude plugin eval init` 为您起草用例和评分器。

14 本周还有：将任何 **Claude Code Desktop 窗格**弹出到其自己的窗口中，稍后将其停靠回来；**`maxEffortLevel`** 设置限制每个提供商的努力级别；以及 **WebFetch** 在五分钟内未完成下载的页面会失败而不是挂起。

16 [阅读 Week 37 摘要 →](/docs/zh-CN/whats-new/2026-w37)

17</Update>

19<Update label="Week 36" description="August 31 – September 4, 2026" tags={["v2.1.251–v2.1.261"]}>

20 **Claude Fable 5.1**：在 Claude Code 中可用，具有 1M 令牌上下文窗口。

22 本周还有：在 Pro 和 Max 计划上，**Desktop 应用中的计算机使用**在 macOS 上在后台工作，同时您继续工作；在全屏渲染中，**`/diff`** 在对话旁边打开一个实时面板，在 Claude 编辑时刷新；**`/skill-doctor`** 显示您每个技能在上下文中的成本以及它被使用的频率。

24 [阅读 Week 36 摘要 →](/docs/zh-CN/whats-new/2026-w36)

25</Update>

27<Update label="Week 35" description="August 24–28, 2026" tags={["v2.1.240–v2.1.250"]}>

28 **在 Desktop 应用中恢复终端会话**：在 Claude Code Desktop 提示框中键入 `/resume` 以继续您从 CLI 启动的任何会话，保持完整的对话和上下文。

30 本周还有：**Claude 起草的反馈**在会话中出现问题时让 Claude 编写反馈报告，您审查并从 `/feedback` 发送；**`--restricted`** 启动没有命令运行工具或您的用户和项目设置的会话，用于共享机器上的评估工具；**`modelPicker`** 设置控制 `/model` 选择器列出的模型。

32 [阅读 Week 35 摘要 →](/docs/zh-CN/whats-new/2026-w35)

33</Update>

11<Update label="Week 34" description="August 17–21, 2026" tags={["v2.1.234–v2.1.239"]}>35<Update label="Week 34" description="August 17–21, 2026" tags={["v2.1.234–v2.1.239"]}>

12 **`/design`**：一个研究预览版，将 Claude Design 的画板工作流程引入 CLI 和 Claude Code Desktop，基于 artifacts 构建，因此 Claude 为您的 UI 草拟可编辑的画板并实现您选择的那个。36 **`/design`**：一个研究预览版，将 Claude Design 的画板工作流程引入 CLI 和 Claude Code Desktop，基于 artifacts 构建，因此 Claude 为您的 UI 草拟可编辑的画板并实现您选择的那个。

13 37

whats-new/2026-w35.md +98 −0 created

Details

1> ## Documentation Index

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

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

5# 第 35 周 · 2026 年 8 月 24–28 日

7> 在 Claude Code Desktop 应用中恢复终端会话，查看 Claude 为您起草的反馈报告，并在受限模式下启动会话。

9<div className="digest-meta">

10 <span>发布版本 <a href="/docs/en/changelog#2-1-240">v2.1.240 → v2.1.250</a></span>

11 <span>3 项功能 · 8 月 24–28 日</span>

12</div>

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">在 Desktop 应用中恢复终端会话</span>

17 <span className="digest-feature-pill">Desktop</span>

18 </div>

20 <p className="digest-feature-lede">在 Claude Code Desktop 提示框中输入 <code>/resume</code> 以选择您从 CLI 启动的任何会话，并在应用中继续该会话，保持完整的对话和上下文。按标题、文件夹或分支搜索您的会话，并在恢复前预览您停止的位置。</p>

22 <Frame>

23 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/f9HTZGyMtxIFOUgt/images/whats-new/desktop-resume-cli-session.mp4?fit=max&auto=format&n=f9HTZGyMtxIFOUgt&q=85&s=41e4a5fda6b9d63280589f2cbdabf44f" data-path="images/whats-new/desktop-resume-cli-session.mp4" />

24 </Frame>

26 <p className="digest-feature-try">在 Desktop 会话中，运行命令以列出您的终端会话：</p>

28 ```text Claude Code theme={null}

29 > /resume

30 ```

32 <p className="digest-feature-try">选择一个会话并按 <code>Enter</code>。对话将在您停止的位置在应用中打开。</p>

34 <a className="digest-feature-link" href="/docs/zh-CN/desktop#coming-from-the-cli">在 CLI 和 Desktop 之间移动</a>

35</div>

37<div className="digest-feature">

38 <div className="digest-feature-header">

39 <span className="digest-feature-title">Claude 起草的反馈</span>

40 <span className="digest-feature-pill">CLI</span>

41 </div>

43 <p className="digest-feature-lede">当工具持续失败、Claude 无法帮助处理请求或您指出错误时，Claude 现在会使用 <code>SendFeedback</code> 工具为您起草反馈报告。您的提示上方会显示一张卡片，您可以从那里查看、发送或关闭它。在您发送之前，任何内容都不会到达 Anthropic。需要 v2.1.238 或更高版本。</p>

45 <Frame>

46 <img className="w-full" src="https://mintcdn.com/claude-code/f9HTZGyMtxIFOUgt/images/whats-new/claude-drafted-feedback.jpg?fit=max&auto=format&n=f9HTZGyMtxIFOUgt&q=85&s=5cacb3be0dffd1cbd417381f3721637e" alt="一个 Claude Code 会话，其中 Claude 已起草了一份标题为"Sandbox image pull fails behind proxy"的错误报告，显示为提示上方的卡片，带有查看、发送或关闭的选项" width="1440" height="756" data-path="images/whats-new/claude-drafted-feedback.jpg" />

47 </Frame>

49 <p className="digest-feature-try">运行 <code>/feedback</code> 不带参数以打开来自每个会话的草稿队列：</p>

51 ```text Claude Code theme={null}

52 > /feedback

53 ```

55 <p className="digest-feature-try">选择一份草稿，然后编辑、发送或丢弃它。要关闭起草功能，请在 <code>/config</code> 中将 <strong>Claude-drafted feedback</strong> 设置为 <code>off</code>。</p>

57 <a className="digest-feature-link" href="/docs/zh-CN/tools-reference#sendfeedback-tool-behavior">SendFeedback 工具行为</a>

58</div>

60<div className="digest-feature">

61 <div className="digest-feature-header">

62 <span className="digest-feature-title">受限模式</span>

63 <span className="digest-feature-pill">v2.1.248</span>

64 </div>

66 <p className="digest-feature-lede">受限模式启动 Claude Code 时不包含运行命令或代码的内置工具。当评估工具在共享机器上驱动 <code>claude</code> 时使用它。使用 `--restricted` 启动或设置 <code>CLAUDE\_CODE\_RESTRICTED=1</code>。Claude Code 还会移除 <code>WebFetch</code>，将文件工具限制在工作目录中，仅加载托管设置和 `--settings`，并拒绝 <code>bypassPermissions</code> 权限模式。</p>

68 <p className="digest-feature-try">运行不带命令运行工具的非交互式查询：</p>

70 ```bash terminal theme={null}

71 claude --restricted -p "review src/ for SQL injection risks"

72 ```

74 <p className="digest-feature-try">要为 Claude 恢复已移除的工具之一，请在 `--tools` 中将其与您想要的其他内置工具一起列出，例如 `--tools "Bash,Read,Edit"`。`--tools` 是一个允许列表，其 <code>default</code> 预设不会恢复已移除的工具。</p>

76 <a className="digest-feature-link" href="/docs/zh-CN/cli-reference#cli-flags">CLI 标志</a>

77</div>

79<div className="digest-wins">

80 <p className="digest-wins-title">其他亮点</p>

82 <div className="digest-wins-grid">

83 <div>设置新的 <a href="/docs/zh-CN/settings-reference#modelpicker"><code>modelPicker</code></a> 设置以使用您自己的有序、标记的条目扩展或替换 <code>/model</code> 选择器的内置列表，包括 Amazon Bedrock 或 Google Cloud 的 Agent Platform 模型 ID</div>

84 <div>将 <a href="/docs/zh-CN/prompt-caching#choose-the-ttl-yourself"><code>promptCacheTtl</code></a> 设置为 <code>1h</code> 以在使用 API 密钥或云提供商时在主对话上保持一小时的提示缓存；<code>subagentPromptCacheTtl</code> 为子代理和主对话外的所有其他请求设置 TTL</div>

85 <div>在 Pro、Max、Team 和 Enterprise 计划上，<a href="/docs/zh-CN/costs#plan-usage-breakdown"><code>/usage</code></a> 添加了 Loops 分解：运行计数、总令牌数、每次运行的令牌数以及使用最多令牌的 <code>/loop</code> 和计划任务的最后一次运行</div>

86 <div>按合同费率的组织可以设置 <a href="/docs/zh-CN/costs#report-spend-at-your-contracted-rates"><code>modelPricing</code></a> 托管设置，以便 <code>/usage</code>、状态行和 OpenTelemetry 按这些费率而不是列表价格报告成本</div>

87 <div><code>/login</code> 在 <strong>Anthropic Console 账户</strong>选项下提供 <strong>使用您的 Console 账户登录</strong>，因此 Console 组织的成员如果不允许 API 密钥，可以在不创建 API 密钥的情况下登录</div>

88 <div>运行 <code>/permissions</code> 并打开新的 <a href="/docs/zh-CN/auto-mode-config#edit-rules-from-permissions"><strong>Auto mode</strong> 标签页</a>以查看和编辑自动模式分类器规则，而无需打开设置文件</div>

89 <div>当自动模式可用时，Manual 和 <code>acceptEdits</code> 权限模式中的 Bash 权限提示提供 <a href="/docs/zh-CN/permission-modes#switch-permission-modes"><strong>是的，并切换到自动模式</strong></a>选项；选择它以批准命令并将会话切换到自动模式</div>

90 <div>在您 <a href="/docs/zh-CN/permissions#move-the-session-to-another-directory">使用 <code>/cd</code> 移动会话</a>后，新目录的项目设置、hooks、<code>.mcp.json</code> 服务器、skills 和子代理立即生效，而不是在下一个 `--resume` 时生效</div>

91 <div>在非交互式会话中，包括 <code>-p</code> 运行、Agent SDK 运行和云会话，Claude Code <a href="/docs/zh-CN/errors#the-response-above-may-be-incomplete">继续响应</a>，该响应被服务器错误、连接断开或停滞中断，当部分响应包含文本且没有工具调用时</div>

92 <div>在其 <code>maxTurns</code> 限制处停止的子代理返回其输出标记为部分，并提示 Claude 可以 <a href="/docs/zh-CN/sub-agents#resume-subagents">使用 <code>SendMessage</code> 继续它</a>，而不是显示为已完成</div>

93 <div>在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，同一机器上的会话现在可以 <a href="/docs/zh-CN/cross-session-messaging#availability">相互消息</a>，<code>/loop</code> 可以 <a href="/docs/zh-CN/scheduled-tasks#let-claude-choose-the-interval">选择自己的间隔</a>，<code>/model</code> 和 <code>/effort</code> 立即应用而不是在回合结束后应用</div>

94 <div>本机安装程序和自动更新程序下载 zstd 压缩的构建，在 Linux x64 上约为 75 MB 而不是 340 MB，本机构建按需加载代码，每个会话使用的内存大约少 40 到 70 MB</div>

95 </div>

96</div>

98[v2.1.240–v2.1.250 的完整更新日志 →](/docs/en/changelog#2-1-240)

whats-new/2026-w36.md +109 −0 created

Details

1> ## Documentation Index

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

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

5# 第 36 周 · 8 月 31 日 – 9 月 4 日，2026 年

7> 切换到 Claude Fable 5.1，让计算机使用在 Desktop 上后台运行，并在实时 /diff 面板中观看 Claude 的编辑。

9<div className="digest-meta">

10 <span>Releases <a href="/docs/en/changelog#2-1-251">v2.1.251 → v2.1.261</a></span>

11 <span>4 个功能 · 8 月 31 日 – 9 月 4 日</span>

12</div>

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">Claude Fable 5.1</span>

17 <span className="digest-feature-pill">新模型</span>

18 </div>

20 <p className="digest-feature-lede">Claude Fable 5.1 在 Claude Code 中可用，具有 1M 令牌上下文窗口，<code>fable</code> 别名现在选择它。在 Claude 应用网关会话中，<code>fable</code> 仍然选择 Fable 5。如果您的网关提供 Fable 5.1，请运行 <code>/model claude-fable-5-1</code>。需要 v2.1.257 或更高版本。</p>

22 <p className="digest-feature-try">将当前会话切换到 Fable 5.1 并将其保存为默认值：</p>

24 ```text Claude Code theme={null}

25 > /model fable

26 ```

28 <p className="digest-feature-try">在 Anthropic API 上，选择器仅在服务器报告您的组织可用时才列出 Fable，但键入 <code>/model fable</code> 会直接与服务器检查。</p>

30 <a className="digest-feature-link" href="/docs/zh-CN/model-config#work-with-fable">使用 Fable</a>

31</div>

33<div className="digest-feature">

34 <div className="digest-feature-header">

35 <span className="digest-feature-title">计算机使用在 Desktop 上后台运行</span>

36 <span className="digest-feature-pill">Desktop</span>

37 </div>

39 <p className="digest-feature-lede">在 macOS 上，Claude Code Desktop 应用中的计算机使用现在可以在后台工作：Claude 可以在您批准的应用中查看和操作，同时您继续工作。后台计算机使用在 Pro 和 Max 计划上处于测试阶段。</p>

41 <Frame>

42 <img className="w-full" src="https://mintcdn.com/claude-code/f9HTZGyMtxIFOUgt/images/whats-new/background-computer-use.jpg?fit=max&auto=format&n=f9HTZGyMtxIFOUgt&q=85&s=a599a6c6fa544cb8d1b426b93706caf4" alt="一个 Claude Code Desktop 会话，其中 Claude 请求使用 Xcode，旁边有一张计算机使用权限卡，上面写着"让 Claude 在您批准的应用中查看和操作，在后台或完全控制您的屏幕"，以及一个"启用"按钮" width="1440" height="810" data-path="images/whats-new/background-computer-use.jpg" />

43 </Frame>

45 <a className="digest-feature-link" href="/docs/zh-CN/desktop#let-claude-use-your-computer">让 Claude 使用您的计算机</a>

46</div>

48<div className="digest-feature">

49 <div className="digest-feature-header">

50 <span className="digest-feature-title">全屏渲染中的实时 diff 面板</span>

51 <span className="digest-feature-pill">v2.1.260</span>

52 </div>

54 <p className="digest-feature-lede">在全屏渲染中，<code>/diff</code> 现在在对话旁边打开一个面板，而不是您必须关闭的查看器。该面板列出更改的文件及其添加和删除的行数，并在每次 Claude 编辑文件或运行 shell 命令时刷新。在面板中用鼠标选择行以将其附加到您的下一个提示。</p>

56 <Frame>

57 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/f9HTZGyMtxIFOUgt/images/whats-new/diff-panel.mp4?fit=max&auto=format&n=f9HTZGyMtxIFOUgt&q=85&s=9d7553c19e7f227891cd95f1f59d796d" data-path="images/whats-new/diff-panel.mp4" />

58 </Frame>

60 <p className="digest-feature-try">启用全屏渲染，在 git 存储库中，并在至少 110 列宽的终端中，切换面板：</p>

62 ```text Claude Code theme={null}

63 > /diff

64 ```

66 <p className="digest-feature-try">再次运行 <code>/diff</code> 或单击其标题中的 <code>✕</code> 来关闭它。</p>

68 <a className="digest-feature-link" href="/docs/zh-CN/interactive-mode#diff-panel">Diff 面板</a>

69</div>

71<div className="digest-feature">

72 <div className="digest-feature-header">

73 <span className="digest-feature-title">使用 /skill-doctor 查找未使用的 skills</span>

74 <span className="digest-feature-pill">CLI</span>

75 </div>

77 <p className="digest-feature-lede"><code>/skill-doctor</code> 显示您的每个 skill 在上下文中的成本以及它被使用的频率，因此您可以决定关闭哪些。<a href="/docs/zh-CN/skills#skill-descriptions-are-cut-short">skill 列表</a>中的每个 skill 都会在每个回合中添加到您的上下文中，无论 Claude 是否使用它。需要 v2.1.252 或更高版本，在跳过<a href="/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching">功能标志获取</a>的会话中不可用。</p>

79 <p className="digest-feature-try">在交互式会话中运行它以在 <code>/plugin</code> 管理器的<strong>Stats</strong>选项卡中打开报告：</p>

81 ```text Claude Code theme={null}

82 > /skill-doctor

83 ```

85 <p className="digest-feature-try">在非交互模式下使用 <code>-p</code>，Claude Code 会将报告打印为文本。</p>

87 <a className="digest-feature-link" href="/docs/zh-CN/skills#find-unused-skills">查找未使用的 skills</a>

88</div>

90<div className="digest-wins">

91 <p className="digest-wins-title">其他亮点</p>

93 <div className="digest-wins-grid">

94 <div><a href="/docs/zh-CN/hooks#premodelswitch"><code>PreModelSwitch</code></a> hook 可以阻止您请求的模型切换，<a href="/docs/zh-CN/hooks#postmodelswitch"><code>PostModelSwitch</code></a> hook 可以在会话的模型更改后为 Claude 添加上下文</div>

95 <div><a href="/docs/zh-CN/costs#prompt-cache-statistics"><code>/cost</code></a> 添加了一行 <code>Prompt cache (main)</code>：从缓存提供的输入令牌份额、缓存未命中、缓存是否预热，以及当 Claude Code 可以命名一个时上次未命中的可能原因。状态行脚本获得匹配的 <code>prompt\_cache</code> 对象</div>

96 <div>组织可以在<a href="/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings"><code>managedMcpServers</code></a> 托管设置下列出 HTTP 和 SSE MCP 服务器，以将其提供给每个用户，除了用户自己添加的服务器</div>

97 <div><code>/effort</code> 和 <code>/model</code> 选择器现在<a href="/docs/zh-CN/model-config#adjust-effort-level">为每个模型保存单独的努力级别</a>；按 <code>s</code> 而不是 <code>Enter</code> 仅将级别应用于当前会话</div>

98 <div>默认情况下，自动模式分类器<a href="/docs/zh-CN/permission-modes#what-the-classifier-blocks-by-default">现在也阻止</a>诸如从云实例元数据端点请求凭证或连接到 Claude 未启动的同级容器等操作</div>

99 <div>在自动模式下，Claude Code 在 Claude <a href="/docs/zh-CN/permission-modes#first-read-outside-the-working-directories">首次读取工作目录外的文件</a>之前询问您，并提供从那时起阻止此类读取的选项</div>

100 <div>提高 <a href="/docs/zh-CN/settings-reference#bashoutputmaxchars"><code>bashOutputMaxChars</code></a> 和 <a href="/docs/zh-CN/settings-reference#taskoutputmaxchars"><code>taskOutputMaxChars</code></a>，最高可达 128,000 个字符，以便 Claude 内联接收来自成功命令或后台任务的更多输出</div>

101 <div>提示的<a href="/docs/zh-CN/interactive-mode#make-ctrl-w-delete-back-to-whitespace">字编辑快捷键遵循 readline</a> 对所有人，<code>keybindingFlavor</code> 设置不再有任何效果。<code>Ctrl+W</code> 删除回到前一个空格，<code>Alt+B</code>、<code>Alt+F</code> 和 <code>Alt+D</code> 将标点符号（如 <code>/</code> 和 <code>.</code>）视为单词分隔符</div>

102 <div>如果您在项目的 <code>.claude/settings.json</code> 或 <code>.claude/settings.local.json</code> 中将 <code>defaultMode</code> 设置为 <code>"bypassPermissions"</code>，它<a href="/docs/zh-CN/permission-modes#which-mode-a-session-starts-in">不再生效</a>，会话以手动模式启动；改为在用户或托管设置中设置 <code>"bypassPermissions"</code>，或传递 `--permission-mode`</div>

103 <div>基于座位的企业计划现在<a href="/docs/zh-CN/model-config#default-model-setting">默认为 Opus 5</a></div>

104 <div>在 VS Code 扩展中，单击提示框底部的模型名称以<a href="/docs/zh-CN/vs-code#use-the-prompt-box">打开模型选择器</a></div>

105 <div>在 VS Code 扩展中，在命令菜单的"自定义"部分中选择<strong>输出样式</strong>以<a href="/docs/zh-CN/vs-code#use-the-prompt-box">选择输出样式</a>，包括您的自定义样式</div>

106 </div>

107</div>

108

109[v2.1.251–v2.1.261 的完整更新日志 →](/docs/en/changelog#2-1-251)

whats-new/2026-w37.md +69 −0 created

Details

1> ## Documentation Index

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

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

5# 第37周 · 2026年9月7日–11日

7> 使用 claude plugin eval 测试您的插件，并将 Claude Code Desktop 窗格弹出到各自的窗口中。

9<div className="digest-meta">

10 <span>发布版本 <a href="/docs/en/changelog#2-1-263">v2.1.263 → v2.1.269</a></span>

11 <span>2 项功能 · 9月7日–11日</span>

12</div>

14<div className="digest-feature">

15 <div className="digest-feature-header">

16 <span className="digest-feature-title">使用 claude plugin eval 测试插件</span>

17 <span className="digest-feature-pill">v2.1.269</span>

18 </div>

20 <p className="digest-feature-lede"><code>claude plugin eval</code> 针对一套测试用例运行您的插件，对结果进行评分，默认情况下每个用例都会再次运行一次（不使用插件），以便您可以看到它的贡献。<code>claude plugin eval init</code> 询问您什么是好的结果，然后提议测试用例和对其进行评分的检查，尝试一次该套件，并写入文件。每次运行，以及每个有第二个模型判断回复的检查，都是您账户上的真实模型调用。</p>

22 <Frame>

23 <img className="w-full" src="https://mintcdn.com/claude-code/f9HTZGyMtxIFOUgt/images/whats-new/plugin-eval.jpg?fit=max&auto=format&n=f9HTZGyMtxIFOUgt&q=85&s=913066f6d4a2a15426e98a627802f47f" alt="claude plugin eval 的终端输出：一个包含七个用例的表格，每个用例都显示有插件和无插件的分数、两者之间的差值、运行次数和成本，后面是一个汇总行，显示平均差值、总持续时间和总成本" width="1600" height="900" data-path="images/whats-new/plugin-eval.jpg" />

24 </Frame>

26 <p className="digest-feature-try">从您的插件根目录，让 Claude 起草该套件：</p>

28 ```bash terminal theme={null}

29 claude plugin eval init

30 ```

32 <p className="digest-feature-try">当 Claude 告诉您该套件已准备好时，退出 <code>claude plugin eval init</code> 打开的会话，并运行 <code>claude plugin eval .</code> 来对每个用例进行评分。汇总表在您的终端中打印，<code>evals/results/</code> 下的 <code>report.html</code> 包含每次运行的详细信息。</p>

34 <a className="digest-feature-link" href="/docs/zh-CN/plugin-evals">使用 evals 测试插件</a>

35</div>

37<div className="digest-feature">

38 <div className="digest-feature-header">

39 <span className="digest-feature-title">将 Desktop 窗格弹出到各自的窗口中</span>

40 <span className="digest-feature-pill">Desktop</span>

41 </div>

43 <p className="digest-feature-lede">在 Claude Code Desktop 应用中，您可以将任何窗格弹出到其自己的窗口中。将 diff 或终端拖到第二个屏幕，同时 Claude 在主窗口中继续工作，然后在完成后将窗格停靠回去。</p>

45 <Frame>

46 <video autoPlay muted loop playsInline className="w-full" src="https://mintcdn.com/claude-code/f9HTZGyMtxIFOUgt/images/whats-new/desktop-pop-out-panes.mp4?fit=max&auto=format&n=f9HTZGyMtxIFOUgt&q=85&s=ff3770dd09bb15ed9cf17a460f3d1e23" data-path="images/whats-new/desktop-pop-out-panes.mp4" />

47 </Frame>

49 <a className="digest-feature-link" href="/docs/zh-CN/desktop#arrange-your-workspace">整理您的工作区</a>

50</div>

52<div className="digest-wins">

53 <p className="digest-wins-title">其他改进</p>

55 <div className="digest-wins-grid">

56 <div>在顶级或 <code>modelSettings</code> 下按模型设置 <a href="/docs/zh-CN/settings-reference#maxeffortlevel"><code>maxEffortLevel</code></a> 以限制每个提供商（包括 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry）上的努力级别；任何更高的级别都以上限运行</div>

57 <div>将 `--plugin-dir` 指向一个插件文件夹，以 <a href="/docs/zh-CN/plugins#test-your-plugins-locally">加载每个具有清单的直接子文件夹</a></div>

58 <div>如果 WebFetch 在五分钟内未完成下载页面，<a href="/docs/zh-CN/tools-reference#webfetch-tool-behavior">获取失败并显示截止时间错误</a>，而不是挂起；设置 <code>CLAUDE\_CODE\_WEBFETCH\_DEADLINE\_MS</code> 以更改截止时间，或设置为 <code>0</code> 以移除限制</div>

59 <div>将 `--json` 传递给 <code>claude plugin install</code>、<code>uninstall</code>、<code>update</code>、<code>enable</code> 或 <code>disable</code> 以将结果打印为 <a href="/docs/zh-CN/plugins-reference#plugin-json-result">stdout 最后一行的一个 JSON 对象</a></div>

60 <div>当自动模式分类器阻止一个操作时，Claude 收到的原因 <a href="/docs/zh-CN/auto-mode-config#fix-a-denial-with-an-allow-rule-an-environment-entry-or-a-retry">通常会命名匹配的规则</a>，例如 <code>\[Data Exfiltration]</code></div>

61 <div>当您在提示中途键入 <code>/</code> 时，您现在可以从 <a href="/docs/zh-CN/interactive-mode#complete-a-command-mid-prompt">匹配命令的列表</a>中选择，而不是单个建议。该列表在全屏渲染中键入时打开。插件技能也可以按其名称（不带插件前缀）进行匹配</div>

62 <div>在 VS Code 扩展中，单击提示框底部的代理计数以打开 <a href="/docs/zh-CN/vs-code#use-the-prompt-box">代理地图</a>，您可以在其中打开子代理的只读记录或停止它</div>

63 <div>在 VS Code 扩展中，在命令菜单的"自定义"部分中选择 <strong>Hooks</strong> 或 <strong>Permissions</strong> 以 <a href="/docs/zh-CN/vs-code#use-the-prompt-box">在您的用户、项目和本地设置中添加或删除 hooks 和权限规则</a></div>

64 <div>Claude 可以选择一个 <a href="/docs/zh-CN/artifacts#create-an-artifact">浏览器标签图标</a>来匹配它发布的每个工件</div>

65 <div>在 Claude Code 网页版中，在 Claude 读取之前在云会话中取回一条排队的消息：从队列中删除它，或按 <code>Esc</code> 或 <code>Up</code>，文本返回到消息框</div>

66 </div>

67</div>

69[v2.1.263–v2.1.269 的完整更新日志 →](/docs/en/changelog#2-1-263)

workflows.md +33 −18

Details

375 工作流如何运行375 工作流如何运行

376</h2>376</h2>

377 377

378工作流运行时在隔离环境中执行脚本，与您的对话分开。中间结果保留在脚本变量中，而不是进入 Claude 的上下文。378工作流运行时在隔离的环境中执行脚本，与您的对话分离。中间结果保留在脚本变量中，而不是进入 Claude 的上下文。

379 379

380每次运行都会将其脚本写入您会话目录下 `~/.claude/projects/` 中的文件。运行开始时 Claude 会收到该路径，因此您可以要求它提供。您可以打开该文件来读取 Claude 编写的编排脚本，将其与之前运行的脚本进行对比，或编辑它并要求 Claude 从编辑后的版本重新启动。380每次运行都会将其脚本写入您会话目录下 `~/.claude/projects/` 中的文件。Claude 在运行开始时接收路径，因此您可以要求它提供路径。您可以打开该文件来读取 Claude 编写的编排，将其与之前运行的脚本进行对比，或编辑它并要求 Claude 从编辑后的版本重新启动。

381 381

382Claude 只能从会话已允许读取的脚本文件启动工作流。要运行保存在工作目录外的脚本，请先使用 [`/add-dir`](/docs/zh-CN/permissions#working-directories) 或 [Read 允许规则](/docs/zh-CN/permissions#read-and-edit) 添加其目录。382Claude 只能从会话已允许读取的脚本文件启动工作流。要运行保存在工作目录外的脚本，请先使用 [`/add-dir`](/docs/zh-CN/permissions#working-directories) 或 [Read allow rule](/docs/zh-CN/permissions#read-and-edit) 添加其目录。

383 383

384运行时在运行进行时跟踪每个代理的结果，这是使运行在同一会话中[可恢复](#resume-after-a-pause)的原因。384运行时在运行进行时跟踪每个代理的结果，这正是使运行在同一会话内 [可恢复](#resume-after-a-pause) 的原因。

385 385

386<h3 id="prompt-caching-in-a-fan-out">386<h3 id="prompt-caching-in-a-fan-out">

387 扇出中的 prompt caching387 扇出中的 prompt caching

388</h3>388</h3>

389 389

390同一运行中的代理可以读取彼此的 [prompt cache](/docs/zh-CN/prompt-caching#subagents-and-the-cache)。使用相同模型、努力级别、代理类型、工具、输出架构和工作目录运行的两个代理会构建相同的工具和系统提示前缀，因此在匹配的兄弟代理响应开始后启动的代理会在其第一个请求中读取该兄弟代理的缓存。390同一运行中的代理可以读取彼此的 [prompt cache](/docs/zh-CN/prompt-caching#subagents-and-the-cache)。两个使用相同模型、努力级别、代理类型、工具、输出架构和工作目录运行的代理会构建相同的工具和系统提示前缀，因此在匹配的兄弟代理响应开始后启动的代理会在其第一个请求中读取该兄弟代理的缓存。

391 391

392工作流代理的请求不在主对话的 [cache TTL bucket](/docs/zh-CN/prompt-caching#which-ttl-each-request-gets) 之外，因此其缓存默认保持五分钟，包括在 Claude 订阅上。要将其保持一小时，请将 [`subagentPromptCacheTtl`](/docs/zh-CN/settings-reference#subagentpromptcachettl) 设置为 `1h`。API 以更高的速率计费 1 小时缓存写入。392工作流代理的请求落在主对话的 [cache TTL bucket](/docs/zh-CN/prompt-caching#which-ttl-each-request-gets) 之外，因此其缓存默认保持五分钟，包括在 Claude 订阅上。要将其保持一小时，请将 [`subagentPromptCacheTtl`](/docs/zh-CN/settings-reference#subagentpromptcachettl) 设置为 `1h`。API 以更高的费率计费 1 小时缓存写入。

393 393

394当扇出同时启动多个匹配的代理时，Claude Code 会保留除第一个之外的所有代理，直到第一个代理的响应开始，然后一起释放保留的代理，以便它们的第一个请求读取共享前缀，而不是每个都未缓存地处理它。Claude Code 将保留时间限制在 [`CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS`](/docs/zh-CN/env-vars) 毫秒，默认为 `5000`。将其设置为 `0` 以禁用保留。394当扇出同时启动多个匹配的代理时，Claude Code 会保留除第一个之外的所有代理，直到第一个代理的响应开始，然后一起释放保留的代理，以便它们的第一个请求读取共享前缀，而不是每个都未缓存地处理它。Claude Code 将保留限制在 [`CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS`](/docs/zh-CN/env-vars) 毫秒，默认为 `5000`。将其设置为 `0` 以禁用保留。

395 395

396<h3 id="behavior-and-limits">396<h3 id="behavior-and-limits">

397 行为和限制397 行为和限制

399 399

400运行时应用以下约束：400运行时应用以下约束：

401 401

402| 约束 | 为什么 |402| 约束 | 原因 |

403| :------------------------------------------------------------- | :-------------------------------------------------------------------- |403| :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------- |

404| 无中途用户输入 | 仅代理权限提示可以暂停运行。对于阶段之间的签署，将每个阶段作为其自己的工作流运行 |404| 无中途用户输入 | 运行仅在代理权限提示和 [使用限制等待](#when-a-run-hits-your-usage-limit) 时暂停。对于阶段之间的签署，将每个阶段作为其自己的工作流运行 |

405| 无来自工作流本身的直接文件系统或 shell 访问 | 代理读取、写入和运行命令。脚本协调代理 |405| 工作流本身无直接文件系统或 shell 访问 | 代理读取、写入和运行命令。脚本协调代理 |

407| 最多 16 个并发代理，在 Claude Code 可用 CPU 较少时更少，包括在 CPU 受限的容器内 | 限制本地资源使用 |407| 最多 16 个并发代理，当 Claude Code 可用的 CPU 较少时更少，包括在 CPU 受限的容器内。要更改限制，请将 [`CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS`](/docs/zh-CN/env-vars#variables) 设置为 1 到 256 之间的值，这需要 Claude Code v2.1.269 或更高版本 | 限制本地资源使用 |

408| 在扇出中，共享第一个代理的 prompt-cache 前缀的代理默认在其后最多启动 5 秒 | 除第一个外的所有代理都读取[第一个代理缓存的前缀](#prompt-caching-in-a-fan-out)，而不是每个都未缓存地处理它 |408| 在扇出中，共享第一个代理的 prompt-cache 前缀的代理最多在其后 5 秒启动，默认情况下 | 除第一个外的所有代理都读取 [第一个代理缓存的前缀](#prompt-caching-in-a-fan-out)，而不是每个都未缓存地处理它 |

410| 每次运行总共 1,000 个代理 | 防止失控循环 |410| 每次运行总共 1,000 个代理 | 防止失控循环 |

411 411

412<h2 id="manage-runs">412<h2 id="manage-runs">

440 440

441在本地和云会话中，当 Claude 重新启动较早的运行并且 Claude Code 根本找不到该运行的保存结果时，重新启动会失败并显示 `nothing to resume` 错误，而不是自动启动运行。要求 Claude 将工作流作为新运行启动。441在本地和云会话中，当 Claude 重新启动较早的运行并且 Claude Code 根本找不到该运行的保存结果时，重新启动会失败并显示 `nothing to resume` 错误，而不是自动启动运行。要求 Claude 将工作流作为新运行启动。

442 442

443<h3 id="when-a-run-hits-your-usage-limit">

444 当运行达到您的使用限制时

445</h3>

446

447当代理达到您的 claude.ai [使用限制](/docs/zh-CN/interactive-mode#wait-for-a-usage-limit-to-reset)时，运行会暂停而不是该代理失败：达到限制的代理会等待重置，并且不会启动新代理。限制重置后不久，等待的代理会再次运行，运行会自动继续。需要 Claude Code v2.1.271 或更高版本；在较早的版本上，受影响的代理会失败。

448

449当运行等待时，其在任务面板中的进度行和 [`/workflows`](#watch-the-run) 标题显示限制何时重置。

450

451运行仅在以下所有条件都成立时暂停；当其中一个不成立时，受影响的代理会失败：

452

453* 会话是交互式的并使用 claude.ai 订阅登录。运行不会在[非交互模式](/docs/zh-CN/headless)中使用 `claude -p` 或 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 暂停，在[后台会话](/docs/zh-CN/agent-view)中，或在 [Remote Control](/docs/zh-CN/remote-control) 或[代理团队](/docs/zh-CN/agent-teams)队友会话中。

454* [`autoContinueAtUsageLimit`](/docs/zh-CN/settings-reference#autocontinueatusagelimit) 已打开，这是让会话本身[等待使用限制重置](/docs/zh-CN/interactive-mode#wait-for-a-usage-limit-to-reset)的相同设置。如果您在等待期间关闭它，等待会结束，等待的代理会失败。

455* 限制在 24 小时内重置。每周限制可能重置得更远。

456* 运行还没有等待过两次。当它第三次达到限制时，代理会失败。

457

443<h3 id="cost">458<h3 id="cost">

444 成本459 成本

445</h3>460</h3>

446 461

447工作流生成许多代理，所以单次运行可以使用比在对话中处理相同任务更多的令牌。运行计入您的计划使用和速率限制，如任何其他会话。462工作流生成许多代理，所以单次运行可以使用比在对话中处理相同任务更多的令牌。运行计入您的计划使用和速率限制。

448 463

449要在提交大型任务前评估支出，请先在小范围上运行工作流：一个目录而不是整个仓库，或一个狭窄的问题而不是一个宽泛的问题。`/workflows` 视图显示每个代理的令牌使用情况，随着运行进行，您可以随时在那里停止运行，通常不会丢失已完成的工作。[暂停后恢复](#resume-after-a-pause)涵盖了停止的运行保留的内容。运行时的[代理上限](#behavior-and-limits)限制单次运行可以生成多少个代理，这限制了失控脚本的成本。要保持运行的代理数量较少，选择 `small` [大小指南](#set-a-size-guideline)。464要在提交大型任务前评估支出，请先在小范围上运行工作流：一个目录而不是整个仓库，或一个狭窄的问题而不是一个宽泛的问题。`/workflows` 视图显示每个代理的令牌使用情况，随着运行进行，您可以随时在那里停止运行，通常不会丢失已完成的工作。[暂停后恢复](#resume-after-a-pause)涵盖了停止的运行保留的内容。运行时的[代理上限](#behavior-and-limits)限制单次运行可以生成多少个代理，这限制了失控脚本的成本。要保持运行的代理数量较少，选择 `small` [大小指南](#set-a-size-guideline)。

450 465

476| :------------- | :--------------------- |491| :------------- | :--------------------- |

481 496

482默认值是 `medium`。在您选择值之前，`/config` 行显示 `medium (default)`，工作流的 `Running in background` 行显示 `medium size (/config)`。需要 Claude Code v2.1.219 或更高版本；较早的版本默认为 `unrestricted`。497默认值是 `medium`，或当您在使用 Claude Code v2.1.271 或更高版本的 Pro 计划上登录时为 `small`。在您选择值之前，`/config` 行将值标记为默认值，工作流的 `Running in background` 行命名生效的大小。需要 Claude Code v2.1.219 或更高版本；较早的版本默认为 `unrestricted`。

483 498

484要更改指南，在 `/config` 中为 Dynamic workflow size 设置选择一个值，或运行 `/config workflowSizeGuideline=small`。在 v2.1.219 及更高版本上，您也可以在任何设置文件中设置 [`workflowSizeGuideline` 键](/docs/zh-CN/settings-reference#workflowsizeguideline)；该值优先于 `/config`，当设置文件提供一个时，Claude Code 会隐藏 `/config` 行。499要更改指南，在 `/config` 中为 Dynamic workflow size 设置选择一个值，或运行 `/config workflowSizeGuideline=small`。在 v2.1.219 及更高版本上，您也可以在任何设置文件中设置 [`workflowSizeGuideline` 键](/docs/zh-CN/settings-reference#workflowsizeguideline)；该值优先于 `/config`，当设置文件提供一个时，Claude Code 会隐藏 `/config` 行。

485 500

worktrees.md +5 −2

Details

139当您[后台](/docs/zh-CN/agent-view#send-the-session-to-the-background)一个 `--worktree` 会话时，其 worktree 变成后台会话 worktree，扫描可以删除。扫描在这些情况下保留 worktree：139当您[后台](/docs/zh-CN/agent-view#send-the-session-to-the-background)一个 `--worktree` 会话时，其 worktree 变成后台会话 worktree，扫描可以删除。扫描在这些情况下保留 worktree：

140 140

141* worktree 仍然保留工作：已更改或未跟踪的文件，或未推送的提交。141* worktree 仍然保留工作：已更改或未跟踪的文件，或未推送的提交。

142* Claude Code 无法确定存储库配置定义的过滤驱动程序，在[三种也阻止 worktree 创建的情况](#git-lfs-content-is-missing-from-a-worktree-claude-code-created)中的任何一种。142* Claude Code 无法确定存储库配置定义的过滤驱动程序，或在其中找到它无法关闭的设置，或[四种也阻止 worktree 创建的情况](#git-lfs-content-is-missing-from-a-worktree-claude-code-created)中的任何一种适用。

143* worktree 属于您未后台的 `--worktree` 会话，无论其年龄如何。143* worktree 属于您未后台的 `--worktree` 会话，无论其年龄如何。

144* 您自己使用 `git worktree add` 创建了 worktree，即使您随后在其中运行了 `--worktree <name>` 会话并后台了该会话。144* 您自己使用 `git worktree add` 创建了 worktree，即使您随后在其中运行了 `--worktree <name>` 会话并后台了该会话。

145 145

353 353

354要获取真实文件，请在 worktree 内运行 `git lfs pull`。354要获取真实文件，请在 worktree 内运行 `git lfs pull`。

355 355

356在三种罕见的情况下，Claude Code 无法判断存储库的配置定义的过滤驱动程序，并根本不创建 worktree。将错误与其修复匹配：356在四种罕见的情况下，Claude Code 无法判断存储库的配置定义的过滤驱动程序，或找到一个它无法关闭的设置，因此根本不创建 worktree。将错误与其修复匹配：

357 357

358* **`Could not read the repository git config to neutralize filter drivers`**：Claude Code 无法读取存储库的 `.git/config`，例如因为其权限。修复它并重试。358* **`Could not read the repository git config to neutralize filter drivers`**：Claude Code 无法读取存储库的 `.git/config`，例如因为其权限。修复它并重试。

359* **`The repository git config defines a filter driver whose name cannot be neutralized (contains "=" or a newline)`**：在 `.git/config` 中重命名或删除该过滤驱动程序并重试。359* **`The repository git config defines a filter driver whose name cannot be neutralized (contains "=" or a newline)`**：在 `.git/config` 中重命名或删除该过滤驱动程序并重试。

360* **`The repository git config has a conditional include (includeIf)`**：将 `includeIf` 在 `.git/config` 中拉入的设置直接移到该文件中，删除 `includeIf`，并重试。您全局 git 配置中的 `includeIf` 不会触发此问题。360* **`The repository git config has a conditional include (includeIf)`**：将 `includeIf` 在 `.git/config` 中拉入的设置直接移到该文件中，删除 `includeIf`，并重试。您全局 git 配置中的 `includeIf` 不会触发此问题。

361* **`Git was not run: the repository's own git config sets <key>`**：消息命名一个指向 Git LFS 运行程序的键，例如 `lfs.customtransfer.<name>.path` 或 `lfs.standalonetransferagent`。如果该设置是您的，将其移到您的全局 git 配置。如果您不认识它，从存储库的 git 配置中删除它，因为您不信任的工具或检出可能已写入它。一旦键从存储库的配置中消失，重试。

361 362

362<h3 id="claude-code-refuses-to-use-a-worktree">363<h3 id="claude-code-refuses-to-use-a-worktree">

363 Claude Code 拒绝使用 worktree364 Claude Code 拒绝使用 worktree

406 407

407拒绝结尾嵌入在每个错误中与交互式通知共享，因此它仍然匹配[Claude Code 拒绝使用 worktree](#claude-code-refuses-to-use-a-worktree) 下的其条目。408拒绝结尾嵌入在每个错误中与交互式通知共享，因此它仍然匹配[Claude Code 拒绝使用 worktree](#claude-code-refuses-to-use-a-worktree) 下的其条目。

408 409

410在 stream-json 结果中，[`startup_failure_reason`](/docs/zh-CN/agent-sdk/typescript#startup_failure_reason) 对于 `could not verify worktree` 错误是 `worktree_unverified`，对于 `cannot resume into worktree` 和 `The worktree binding is kept` 错误是 `worktree_resume_refused`。应用程序可以基于它进行分支，而不是匹配错误文本。在 v2.1.274 之前，结果没有携带 `startup_failure_reason` 字段。

411

409<h2 id="see-also">412<h2 id="see-also">

410 另请参阅413 另请参阅

411</h2>414</h2>

zero-data-retention.md +2 −3

Details

64当为 Claude for Enterprise 上的 Claude Code 组织启用 ZDR 时，某些需要存储提示或完成的功能会在后端级别自动禁用：64当为 Claude for Enterprise 上的 Claude Code 组织启用 ZDR 时，某些需要存储提示或完成的功能会在后端级别自动禁用：

65 65

66| 功能 | 原因 |66| 功能 | 原因 |

~~67| -------------------------------------------------- | --------------------------------- |~~67| ------------------------------------------------------------------------------------------------------ | --------------------------------- |

~~68| [网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web) | 需要服务器端存储对话历史。 |~~68| [网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web)，包括从 [Desktop 应用](/docs/zh-CN/desktop#cloud-sessions)启动的应用 | 需要服务器端存储会话数据，包括包含提示和完成的对话历史。 |

~~69| 来自 Desktop 应用的[云会话](/docs/zh-CN/desktop#cloud-sessions) | 需要包含提示和完成的持久会话数据。 |~~

70| [Claude Tag](/docs/zh-CN/claude-tag) | 保留频道内存和会话记录。 |69| [Claude Tag](/docs/zh-CN/claude-tag) | 保留频道内存和会话记录。 |

71| [Artifacts](/docs/zh-CN/artifacts) | 需要在 Anthropic 运营的基础设施上存储已发布的页面内容。 |70| [Artifacts](/docs/zh-CN/artifacts) | 需要在 Anthropic 运营的基础设施上存储已发布的页面内容。 |

72| 反馈提交（`/feedback`、`/bug`、`/share`） | 提交反馈会将对话数据发送给 Anthropic。 |71| 反馈提交（`/feedback`、`/bug`、`/share`） | 提交反馈会将对话数据发送给 Anthropic。 |

Documentation 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC