Documentation 2026-11-02 23:57 UTC to 2026-11-03 23:58 UTC

79* 通过 HKLM 注册表或 `C:\Program Files\ClaudeCode` 文件部署 `wslInheritsWindowsSettings: true`，以便 WSL 会话继承与主机会话相同的策略。79* 通过 HKLM 注册表或 `C:\Program Files\ClaudeCode` 文件部署 `wslInheritsWindowsSettings: true`，以便 WSL 会话继承与主机会话相同的策略。

80* 通过在 WSL 会话内运行 `/status` 进行验证，并读取 `Setting sources` 行。要解释它列出的内容，请参阅[在 /status 中读取来源](https://code.claude.com/docs/zh-CN/managed-settings.md#read-the-source-in-/status)。80* 通过在 WSL 会话内运行 `/status` 进行验证，并读取 `Setting sources` 行。要解释它列出的内容，请参阅[在 /status 中读取来源](https://code.claude.com/docs/zh-CN/managed-settings.md#read-the-source-in-/status)。

81 81 

82如果 WSL 会话在配有 Claude Desktop [`allowedWorkspaceFolders`](https://claude.com/docs/third-party/claude-desktop/configuration#allowedworkspacefolders) 列表的设备上启动，则 `~` 条目表示发行版内的主目录。

83 

82WSL 2 实用程序 VM 内的进程对 Windows 端端点检测传感器不可见。要观察发行版内的进程和文件活动，请查看您的端点检测供应商的 WSL 指南，了解您可以在发行版内运行的 Linux 传感器及其需要的排除项。Claude Code 的 [OpenTelemetry 工具执行遥测](https://code.claude.com/docs/zh-CN/monitoring-usage.md) 对 WSL 和本机会话的发出方式相同。84WSL 2 实用程序 VM 内的进程对 Windows 端端点检测传感器不可见。要观察发行版内的进程和文件活动，请查看您的端点检测供应商的 WSL 指南，了解您可以在发行版内运行的 Linux 传感器及其需要的排除项。Claude Code 的 [OpenTelemetry 工具执行遥测](https://code.claude.com/docs/zh-CN/monitoring-usage.md) 对 WSL 和本机会话的发出方式相同。

83 85 

84## 决定要强制执行的内容86## 决定要强制执行的内容

127 129 

128### 已连接的 GitHub 账户130### 已连接的 GitHub 账户

129 131 

130在 Team 和 Enterprise 计划中，[**Organization settings > Git providers**](https://claude.ai/admin-settings/source-control) 的 GitHub 部分列出了通过 [Claude GitHub App](https://github.com/apps/claude) 关联到您 Claude 组织的 GitHub 组织和个人账户。Claude Code、[Claude Tag](https://claude.com/docs/claude-tag/admins/configure-github) 和 Claude Security 共享该列表。打开此页面需要您在 Claude 组织中拥有管理员角色。132在 Team 和 Enterprise 计划中，[**Organization settings > Git providers**](https://claude.ai/admin-settings/source-control) 的 GitHub 部分列出了通过 [Claude GitHub App](https://github.com/apps/claude) 关联到您 Claude 组织的 GitHub 组织和个人账户。Claude Code、[Claude Tag](https://claude.com/docs/claude-tag/admins/configure-github) 和 Claude Security 共享该列表。打开此页面需要您在 Claude 组织中拥有[所有者角色](https://code.claude.com/docs/zh-CN/server-managed-settings.md#access-control)。管理员角色无法打开此页面。

131 133 

132管理员或成员都可以关联账户：134可以通过 Git 提供商页面关联账户，也可以通过将 GitHub 连接到 Claude 来关联账户：

133 135 

134* **管理员连接**：管理员在该部分点击 **Connect**，或在已连接账户后点击 **Add organization**，然后在 GitHub 组织上安装 Claude GitHub App。以这种方式关联组织，需要一个既是该 GitHub 组织所有者、又是您 Claude 组织管理员的人员。136* **所有者连接**：所有者在该部分点击 **Connect**，或在已连接账户后点击 **Add organization**，然后在 GitHub 组织上安装 Claude GitHub App。以这种方式关联组织，需要一位同时拥有该 GitHub 组织的您 Claude 组织的所有者。

135* **成员连接**：当成员将其 GitHub 账户连接到 Claude 时（例如在[设置云端会话](https://code.claude.com/docs/zh-CN/web-quickstart.md#connect-github)时），Claude 会关联该成员所拥有且已安装 Claude GitHub App 的 GitHub 账户。这可能包括其个人账户以及其拥有的 GitHub 组织。137* **成员连接**：当成员将其 GitHub 账户连接到 Claude 时（例如在[设置云端会话](https://code.claude.com/docs/zh-CN/web-quickstart.md#connect-github)时），Claude 会关联该成员所拥有且已安装 Claude GitHub App 的 GitHub 账户。这可能包括其个人账户以及其拥有的 GitHub 组织。

136 138 

137标记为 **Not linked** 的行来自您自己的 GitHub 登录。它是您在 GitHub 上可以看到且已安装 Claude GitHub App 的账户。139标记为 **Not linked** 的行来自您自己的 GitHub 登录。它是您在 GitHub 上可以看到且已安装 Claude GitHub App 的账户。

222>222>

223> `effort` 在每个响应内交换延迟和令牌成本以获得推理深度。[扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 是一个单独的功能，在输出中产生 `thinking` 块，[Python](https://code.claude.com/docs/zh-CN/agent-sdk/python.md#thinkingconfig) 或 [TypeScript](https://code.claude.com/docs/zh-CN/agent-sdk/typescript.md#thinkingconfig) 上 `ThinkingConfig` 的 `display` 字段控制你是否接收它们的文本。它们是独立的：你可以设置 `effort: "low"` 并启用扩展思考，或 `effort: "max"` 而不启用它。223> `effort` 在每个响应内交换延迟和令牌成本以获得推理深度。[扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) 是一个单独的功能，在输出中产生 `thinking` 块，[Python](https://code.claude.com/docs/zh-CN/agent-sdk/python.md#thinkingconfig) 或 [TypeScript](https://code.claude.com/docs/zh-CN/agent-sdk/typescript.md#thinkingconfig) 上 `ThinkingConfig` 的 `display` 字段控制你是否接收它们的文本。它们是独立的：你可以设置 `effort: "low"` 并启用扩展思考，或 `effort: "max"` 而不启用它。

224 224 

225对于执行简单、范围明确的任务（如列出文件或运行单个 grep）的代理，使用较低的努力来降低成本和延迟。在顶级 `query()` 选项中为整个会话设置 `effort`，或在 [`AgentDefinition`](https://code.claude.com/docs/zh-CN/agent-sdk/subagents#agentdefinition-configuration) 上使用 `effort` 字段为每个子代理设置以覆盖会话级别。225对于执行简单、范围明确的任务（如列出文件或运行单个 grep）的 Agent，使用较低的 effort 来降低成本和延迟。在顶级 `query()` 选项中为[会话](https://code.claude.com/docs/zh-CN/sub-agents.md#choose-an-effort-level)设置 `effort`，或在 [`AgentDefinition`](https://code.claude.com/docs/zh-CN/agent-sdk/subagents#agentdefinition-configuration) 上使用 `effort` 字段为每个子代理设置以覆盖会话级别。

226 226 

227### 权限模式227### 权限模式

228 228 

224| `matcher` | `string` | `undefined` | 针对事件的过滤字段匹配的模式，遵循[设置文件中匹配器的规则](https://code.claude.com/docs/zh-CN/hooks.md#matcher-patterns)。对于工具 hook，该字段是工具名称。内置工具包括 `Bash`、`Read`、`Write`、`Edit`、`Glob`、`Grep`、`WebFetch`、`Agent` 等。请参阅[工具输入类型](https://code.claude.com/docs/zh-CN/agent-sdk/typescript.md#tool-input-types)以获取完整列表。MCP 工具使用模式 `mcp__<server>__<action>`，其中 `<server>` 是您在 `mcpServers` 配置中使用的键，其拼写方式遵循[工具命名约定](https://code.claude.com/docs/zh-CN/agent-sdk/mcp.md#tool-naming-convention)中的说明。 |224| `matcher` | `string` | `undefined` | 针对事件的过滤字段匹配的模式，遵循[设置文件中匹配器的规则](https://code.claude.com/docs/zh-CN/hooks.md#matcher-patterns)。对于工具 hook，该字段是工具名称。内置工具包括 `Bash`、`Read`、`Write`、`Edit`、`Glob`、`Grep`、`WebFetch`、`Agent` 等。请参阅[工具输入类型](https://code.claude.com/docs/zh-CN/agent-sdk/typescript.md#tool-input-types)以获取完整列表。MCP 工具使用模式 `mcp__<server>__<action>`，其中 `<server>` 是您在 `mcpServers` 配置中使用的键，其拼写方式遵循[工具命名约定](https://code.claude.com/docs/zh-CN/agent-sdk/mcp.md#tool-naming-convention)中的说明。 |

225| `hooks` | `HookCallback[]` | - | 必需。当模式匹配时执行的回调函数数组 |225| `hooks` | `HookCallback[]` | - | 必需。当模式匹配时执行的回调函数数组 |

226| `timeout` | `number` | `undefined` | 超时时间（秒）。省略时，Claude Code 应用[事件的默认超时](#hook-timeout)。您的 SDK 回调遵循 `command` hook 默认值 |226| `timeout` | `number` | `undefined` | 超时时间（秒）。省略时，Claude Code 应用[事件的默认超时](#hook-timeout)。您的 SDK 回调遵循 `command` hook 默认值 |

227| `onFailure` | `"continue" \| "block"` | `undefined` | 回调失败时的行为。设置为 `"block"` 可[在回调失败时阻止操作](#block-the-action-when-a-callback-fails)。在 Python 中，使用 `on_failure` |

227 228 

228尽可能使用 `matcher` 模式来针对特定工具。带有 `'Bash'` 的匹配器仅对 Bash 命令运行，而省略模式会为事件的每次出现运行您的回调。229尽可能使用 `matcher` 模式来针对特定工具。带有 `'Bash'` 的匹配器仅对 Bash 命令运行，而省略模式会为事件的每次出现运行您的回调。

229 230 

283>284>

284> 异步输出无法阻止、修改或将上下文注入到操作中，因为 Agent 已经继续。仅将它们用于日志记录、指标或通知等副作用。285> 异步输出无法阻止、修改或将上下文注入到操作中，因为 Agent 已经继续。仅将它们用于日志记录、指标或通知等副作用。

285 286 

287### 在回调失败时阻止操作

288 

289在大多数事件上，如果回调抛出异常或返回未通过验证的输出，操作会继续进行，并且您的应用程序会收到一条 `tag` 为 `hook_callback_failed` 的 [`SDKInformationalMessage`](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#sdkinformationalmessage) 警告。这样一来，崩溃的 `PreToolUse` 守卫会让工具调用进入正常的权限流程。不返回任何内容的回调（例如某条没有 `return` 的路径）也算作失败。在 Python 中，请从 `SystemMessage.data` 读取 `tag`。

290 

291要改为阻止操作，请在匹配器上设置 `onFailure: "block"`（TypeScript）或 `on_failure="block"`（Python）。需要 TypeScript Agent SDK v0.3.317 或更高版本，或 Python Agent SDK v0.2.177 或更高版本。此示例在 Python 中的 `check_policy` 或 TypeScript 中的 `checkPolicy` 失败时阻止 Bash 调用：

292 

293```python Python theme={null}

294options = ClaudeAgentOptions(

295 hooks={

296 "PreToolUse": [

297 HookMatcher(matcher="Bash", hooks=[check_policy], on_failure="block")

298 ]

299 }

300)

301```

302 

303```typescript TypeScript theme={null}

304import type { Options } from "@anthropic-ai/claude-agent-sdk";

305 

306const options: Options = {

307 hooks: {

308 PreToolUse: [{ matcher: "Bash", hooks: [checkPolicy], onFailure: "block" }]

309 }

310};

311```

312 

313要进行测试，请让回调抛出错误，然后让 Claude 运行一条 Bash 命令。工具结果会包含 `failed; blocking because onFailure is "block"`，并且 Claude 看不到您的错误文本。

314 

315当回调没有意见时，请返回 `{}`。设置 `"block"` 后，没有 `return` 的路径会阻止操作。捕获自身错误并返回 `{}` 的回调不算失败，因此请让错误从守卫中向上传播。

316 

317#### 行为不同的事件

318 

319设置 `"block"` 后，以下事件并不总是会阻止：

320 

321* **`Stop`、`SubagentStop`、`TaskCompleted` 和 `TeammateIdle`**：这些事件会忽略该选项，因此操作会继续进行。

322* **`PermissionRequest`**：仅当阻止在您的 `canUseTool` 回调作出响应之前到达时才生效。

323* **`PostToolUse`**：工具已经运行，因此 Claude 会将失败作为反馈接收。

324 

325超出超时时间的回调遵循 [Hook 超时](#hook-timeout)。设置 `"block"` 后，超时还会阻止 `PreCompact`、`Elicitation` 和 `WorktreeCreate`。

326 

327#### `onFailure` 的启动错误

328 

329设置 `"block"` 后，如果无法遵循该选项，查询会在启动时失败，并且不会发送任何提示词：

330 

331* **Claude Code 不支持该选项**：错误包含 `does not honor`。请更新 Claude Code，或移除该选项。

332* **会话已在运行且未注册您的 hook**：错误包含 `did not register your hooks`。请启动新会话。

333 

286## 示例334## 示例

287 335 

288本节中的几个示例仅显示回调函数。要运行一个示例，请在选项的 `hooks` 字段中的匹配事件下注册回调，如 [配置 hooks](#configure-hooks) 中所示。336本节中的几个示例仅显示回调函数。要运行一个示例，请在选项的 `hooks` 字段中的匹配事件下注册回调，如 [配置 hooks](#configure-hooks) 中所示。

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

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

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

782* 其他事件，如 `Notification`、`PreCompact` 和 `PostModelSwitch`：Claude Code 记录失败并继续。830* 其他事件，如 `Notification`、`PreCompact` 和 `PostModelSwitch`：Claude Code 记录失败并继续。使用 [`onFailure: "block"`](#block-the-action-when-a-callback-fails) 时，`PreCompact`、`Elicitation` 或 `WorktreeCreate` 上的超时会阻止该操作。

783 831 

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

785 833 

2161 None # Timeout in seconds. When omitted, the per-event default applies:2161 None # Timeout in seconds. When omitted, the per-event default applies:

2162 # 600 for most events, 30 for UserPromptSubmit2162 # 600 for most events, 30 for UserPromptSubmit

2163 )2163 )

2164 on_failure: Literal["continue", "block"] | None = (

2165 None # "block" blocks the action when a callback fails

2166 )

2164```2167```

2165 2168 

2169要确定 `on_failure` 涵盖的范围，见 [回调失败时阻止操作](https://code.claude.com/docs/zh-CN/agent-sdk/hooks.md#block-the-action-when-a-callback-fails)。

2170 

2166### `HookInput`2171### `HookInput`

2167 2172 

2168所有 hook 输入类型的联合类型。实际类型取决于 `hook_event_name` 字段。2173所有 hook 输入类型的联合类型。实际类型取决于 `hook_event_name` 字段。

2183 level: "info" | "notice" | "suggestion" | "warning";2183 level: "info" | "notice" | "suggestion" | "warning";

2184 tool_use_id?: string;2184 tool_use_id?: string;

2185 prevent_continuation?: boolean;2185 prevent_continuation?: boolean;

2186 tag?: string;

2186 uuid: UUID;2187 uuid: UUID;

2187 session_id: string;2188 session_id: string;

2188};2189};

2558 matcher?: string;2559 matcher?: string;

2559 hooks: HookCallback[];2560 hooks: HookCallback[];

2560 timeout?: number; // 此匹配器中所有 hooks 的超时时间（秒）2561 timeout?: number; // 此匹配器中所有 hooks 的超时时间（秒）

2562 onFailure?: "continue" | "block"; // "block" 在回调失败时阻止该操作

2561}2563}

2562```2564```

2563 2565 

2566要确定 `onFailure` 涵盖哪些情况，请参阅[在回调失败时阻止操作](https://code.claude.com/docs/zh-CN/agent-sdk/hooks.md#block-the-action-when-a-callback-fails)。

2567 

2564### `HookInput`2568### `HookInput`

2565 2569 

2566所有 hook 输入类型的联合类型。2570所有 hook 输入类型的联合类型。

158* **系列别名，例如 `opus`**：在 Anthropic API 和 Claude Platform on AWS 上，Claude Code 会在允许列表允许的该系列最新版本上运行队友。在使用提供商特定模型 ID 的提供商上，[替换机制不起作用](https://code.claude.com/docs/zh-CN/model-config.md#restrict-model-selection)，被阻止的别名会像其他被阻止的值一样，按照下一条规则回退158* **系列别名，例如 `opus`**：在 Anthropic API 和 Claude Platform on AWS 上，Claude Code 会在允许列表允许的该系列最新版本上运行队友。在使用提供商特定模型 ID 的提供商上，[替换机制不起作用](https://code.claude.com/docs/zh-CN/model-config.md#restrict-model-selection)，被阻止的别名会像其他被阻止的值一样，按照下一条规则回退

159* **任何其他被阻止的值，包括在替换机制不起作用的提供商上的系列别名，或其系列没有允许版本的别名**：Claude Code 会改为在负责人的模型上运行队友。如果您设置了 `CLAUDE_CODE_SUBAGENT_MODEL`，Claude Code 会先尝试该模型，并遵循同样的规则159* **任何其他被阻止的值，包括在替换机制不起作用的提供商上的系列别名，或其系列没有允许版本的别名**：Claude Code 会改为在负责人的模型上运行队友。如果您设置了 `CLAUDE_CODE_SUBAGENT_MODEL`，Claude Code 会先尝试该模型，并遵循同样的规则

160 160 

161默认情况下，队友继承负责人的 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)。在分屏窗格模式下，此行为从 v2.1.186 起适用；早期版本不会将负责人的会话 effort 传递给分屏窗格队友。161默认情况下，使用负责人模型的队友会继承负责人的 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)。在分屏窗格模式下，此行为从 v2.1.186 起适用；早期版本不会将负责人的会话 effort 传递给分屏窗格队友。对于使用其他模型的队友，请参阅[子代理和队友的 effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#effort-level-of-subagents-and-teammates)。

162 162 

163### 让队友在实施前先制定计划163### 让队友在实施前先制定计划

164 164 

165对于复杂或有风险的任务，您可以让队友在实施前先制定计划。当负责人处于[计划模式](https://code.claude.com/docs/zh-CN/permission-modes.md#analyze-before-you-edit-with-plan-mode)时由 Claude 生成的队友，会在只读的计划模式下工作，直到其计划准备就绪。先将负责人切换到计划模式，然后请求生成队友：165对于复杂或有风险的任务，您可以让队友在实施前先制定计划。当负责人处于[计划模式](https://code.claude.com/docs/zh-CN/permission-modes.md#analyze-before-you-edit-with-plan-mode)时由 Claude 生成的队友，同样会在计划模式下工作，直到其计划准备就绪。先将负责人切换到计划模式，然后请求生成队友：

166 166 

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

168Spawn an architect teammate to refactor the authentication module.168Spawn an architect teammate to refactor the authentication module.

169```169```

170 170 

171当该队友完成计划后，它会向负责人发送计划批准请求。如果自该队友生成以来您未更改其权限模式，Claude Code 会在请求到达后立即批准该计划，无需负责人审查。队友的编辑和命令仍需经过[权限](#permissions)中所述的权限提示。获得批准后，队友退出计划模式并开始实施。171当该队友完成计划后，它会向负责人发送计划批准请求。如果自该队友生成以来您未更改其权限模式，Claude Code 会在请求到达后立即批准该计划，无需负责人审查。获得批准后，队友退出计划模式并开始实施。Claude Code 会将负责人当前的[权限模式](#permissions)传递给该队友；如果负责人当前处于计划模式，则传递 Manual。

172 172 

173如果您在查看某个正在运行的进程内队友的会话时按 [`Shift+Tab`](https://code.claude.com/docs/zh-CN/permission-modes#switch-permission-modes) 将其置于计划模式，则该次运行的计划将由负责人审查，而不是由 Claude Code 批准。系统不会要求您批准；负责人会批准该计划或将其退回修改。173如果您在查看某个正在运行的进程内队友的会话时按 [`Shift+Tab`](https://code.claude.com/docs/zh-CN/permission-modes#switch-permission-modes) 将其置于计划模式，则该次运行的计划将由负责人审查，而不是由 Claude Code 批准。系统不会要求您批准；负责人会批准该计划或将其退回修改。

174 174 

288 288 

289### 权限289### 权限

290 290 

291队友从负责人的权限模式开始，除了 [`dontAsk` 模式](https://code.claude.com/docs/zh-CN/permission-modes#allow-only-pre-approved-tools-with-dontask-mode)，他们不继承该模式。如果负责人使用 `--dangerously-skip-permissions` 运行，所有队友也会这样做。生成后，你可以更改个别队友的权限模式，但在生成时无法设置每个队友的权限模式。291要循环切换正在运行的队友的权限模式，请按 [`Shift+Tab`](https://code.claude.com/docs/zh-CN/permission-modes#switch-permission-modes)，不过进程内队友可能会改为以负责人的模式运行。对于分割窗格队友，请在其窗格中按该键。对于 [进程内](#choose-a-display-mode) 队友，请在 [查看其会话](#talk-to-teammates-directly) 时按该键，队友会在开始下一轮次时检查其模式。

292 

293> [!NOTE]

294>

295> 不处于 [计划模式](#have-teammates-plan-before-implementing) 的进程内队友，在负责人处于 [`acceptEdits`](https://code.claude.com/docs/zh-CN/permission-modes#auto-approve-file-edits-with-acceptedits-mode)、[`auto`](https://code.claude.com/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 或 [`bypassPermissions`](https://code.claude.com/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode) 模式时，会以负责人的模式运行。将该队友切换到 Manual 不会改变这一点，即使其状态栏显示 Manual。

296>

297> 要让它在编辑前询问，请在 Agent 面板中的 `main` 行上按 Enter，并将负责人也切换到 Manual 模式。之后负责人也会询问，任何其他处于 Manual 模式的队友同样如此。

298 

299您无法在生成时设置每个队友的权限模式。新队友以负责人的模式启动，包括由 `--dangerously-skip-permissions` 开启的 `bypassPermissions` 模式。如果负责人处于 [`dontAsk` 模式](https://code.claude.com/docs/zh-CN/permission-modes#allow-only-pre-approved-tools-with-dontask-mode)，队友则改为以 [Manual 模式](https://code.claude.com/docs/zh-CN/permission-modes.md#available-modes) 启动。

292 300 

293[进程内](#choose-a-display-mode)队友在负责人实时的允许和拒绝规则下运行，因此 [`--disallowedTools`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags)、`--tools` 和 `--allowedTools` 都适用于它。对于分割窗格队友，请逐一检查各个标志：301[进程内](#choose-a-display-mode)队友在负责人实时的允许和拒绝规则下运行，因此 [`--disallowedTools`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags)、`--tools` 和 `--allowedTools` 都适用于它。对于分割窗格队友，请逐一检查各个标志：

294 302 

488* **没有嵌套团队**：队友无法生成自己的队友。只有负责人可以管理团队。496* **没有嵌套团队**：队友无法生成自己的队友。只有负责人可以管理团队。

489* **没有来自 in-process 队友的后台子代理**：in-process 队友自己的子代理在前台运行，因为队友的后台工作无法超越负责人的进程。Claude Code 在队友生成定义设置 `background: true` 的子代理时返回错误。队友的 `run_in_background: true` 请求也会失败，要么返回错误，要么在前台静默运行。从主对话启动的子代理遵循[后台默认值](https://code.claude.com/docs/zh-CN/sub-agents.md#run-subagents-in-foreground-or-background)。497* **没有来自 in-process 队友的后台子代理**：in-process 队友自己的子代理在前台运行，因为队友的后台工作无法超越负责人的进程。Claude Code 在队友生成定义设置 `background: true` 的子代理时返回错误。队友的 `run_in_background: true` 请求也会失败，要么返回错误，要么在前台静默运行。从主对话启动的子代理遵循[后台默认值](https://code.claude.com/docs/zh-CN/sub-agents.md#run-subagents-in-foreground-or-background)。

490* **负责人是固定的**：主会话在其生命周期内是其团队的负责人。你无法将队友提升为负责人或转移领导权。498* **负责人是固定的**：主会话在其生命周期内是其团队的负责人。你无法将队友提升为负责人或转移领导权。

491* **权限在生成时设置**：队友从 [权限](#permissions) 下描述的权限模式开始。你可以在生成后更改个别队友的权限模式，但在生成时无法设置每个队友的权限模式。499* **生成时无法为每个队友设置权限模式**：队友以 [权限](#permissions) 下描述的权限模式启动。

492* **分割窗格需要 tmux 或 iTerm2**：默认 in-process 模式在任何终端中工作。VS Code 的集成终端、Windows Terminal 或 Ghostty 不支持分割窗格模式。500* **分割窗格需要 tmux 或 iTerm2**：默认 in-process 模式在任何终端中工作。VS Code 的集成终端、Windows Terminal 或 Ghostty 不支持分割窗格模式。

493 501 

494## 后续步骤502## 后续步骤

442 442 

443运行 `/background` 或其别名 `/bg` 将当前对话移到后台会话。传递一个提示词，例如 `/bg run the test suite and fix any failures`，可以先再给出一条指令。如果您运行 `/bg` 时 Claude 正在回复，回复会在后台会话中继续。443运行 `/background` 或其别名 `/bg` 将当前对话移到后台会话。传递一个提示词，例如 `/bg run the test suite and fix any failures`，可以先再给出一条指令。如果您运行 `/bg` 时 Claude 正在回复，回复会在后台会话中继续。

444 444 

445退出仍有后台工作运行的会话（例如子代理、后台 shell 命令、工作流或 [monitor](https://code.claude.com/docs/zh-CN/tools-reference.md#monitor-tool)）时，会显示 `Background work is running` 对话框，而不是立即退出。选择 `Move to background and exit` 可以像 `/background` 一样将会话移到后台并返回到您的 shell。当 Agent 视图 [已关闭](#turn-off-agent-view) 时不显示该选项。445如果您在某些类型的后台工作（例如子代理或工作流）正在运行时退出会话，`Background work is running` 对话框会警告这些工作将会停止。选择 `Move to background and exit` 可以像 `/background` 一样将会话移到后台并返回到您的 shell。当 Agent 视图 [已关闭](#turn-off-agent-view) 时不显示该选项。

446 446 

447如果列表上的后台会话已使用该对话的名称，Claude Code 会为新行的名称编号，例如 `my-session (2)`，并保持现有行的名称不变。要重命名新行，请在 Agent 视图中选择它并按 `Ctrl+R`。447如果列表上的后台会话已使用该对话的名称，Claude Code 会为新行的名称编号，例如 `my-session (2)`，并保持现有行的名称不变。要重命名新行，请在 Agent 视图中选择它并按 `Ctrl+R`。

448 448 

315* [托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)的 `env` 块中的固定版本315* [托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)的 `env` 块中的固定版本

316* 指向[应用推理配置文件 ARN](#map-each-model-version-to-an-inference-profile) 的固定版本，因为这些由您的管理员管理316* 指向[应用推理配置文件 ARN](#map-each-model-version-to-an-inference-profile) 的固定版本，因为这些由您的管理员管理

317 317 

318如果针对托管设置中的固定版本仍出现更新提示，请将 Claude Code 更新到 v2.1.314 或更高版本。在 v2.1.314 之前，接受后托管的固定版本仍然有效，因此下次启动时该提示会再次出现。

319 

318如果您未固定模型且当前默认模型在您的账户中不可用，Claude Code 会为当前会话进行回退并显示通知。它首先尝试默认模型的早期版本，当默认模型是 Opus 模型且没有可用的 Opus 版本时，会回退到默认 Sonnet 模型。回退不会被保留。在您的 Amazon Bedrock 账户中启用较新的模型或[固定一个版本](#4-pin-model-versions)以使选择永久生效。320如果您未固定模型且当前默认模型在您的账户中不可用，Claude Code 会为当前会话进行回退并显示通知。它首先尝试默认模型的早期版本，当默认模型是 Opus 模型且没有可用的 Opus 版本时，会回退到默认 Sonnet 模型。回退不会被保留。在您的 Amazon Bedrock 账户中启用较新的模型或[固定一个版本](#4-pin-model-versions)以使选择永久生效。

319 321 

322### 在特定模型上启动会话

323 

320当您在特定 Sonnet 或 Opus 版本上启动会话时，例如使用 `--model`、`ANTHROPIC_MODEL` 或[`model` 设置](https://code.claude.com/docs/zh-CN/settings-reference#model)，该版本将作为会话针对匹配的 `sonnet` 或 `opus` 别名的固定默认版本。Claude Code 会跳过对您的模型替换的内置默认版本的可用性检查，并在您配置的模型上启动，不显示回退通知。324当您在特定 Sonnet 或 Opus 版本上启动会话时，例如使用 `--model`、`ANTHROPIC_MODEL` 或[`model` 设置](https://code.claude.com/docs/zh-CN/settings-reference#model)，该版本将作为会话针对匹配的 `sonnet` 或 `opus` 别名的固定默认版本。Claude Code 会跳过对您的模型替换的内置默认版本的可用性检查，并在您配置的模型上启动，不显示回退通知。

321 325 

322在以下对象上启动会话时，它们不充当固定版本：326在以下对象上启动会话时，它们不充当固定版本：

324* 模型别名，例如 `opus`328* 模型别名，例如 `opus`

325* Claude Code 无法识别的模型 ID，例如应用推理配置文件 ARN329* Claude Code 无法识别的模型 ID，例如应用推理配置文件 ARN

326 330 

327当这些检查发现您的账户无法调用的模型时，Claude Code 会在这台机器上记住该拒绝长达一天，在此期间启动时会跳过记住的模型，而不再询问 Amazon Bedrock。Claude Code 会在距离上次检查已过十分钟后再次检查当前默认模型的记住拒绝，因此您的管理员重新启用的默认模型会恢复。要关闭此记忆功能，请设置 [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](https://code.claude.com/docs/zh-CN/env-vars)。331### 记住的模型拒绝

332 

333当启动模型检查发现您的账户无法调用的模型时，Claude Code 可以在这台机器上记住该拒绝长达一天。距离上次检查已过十分钟后，Claude Code 会在启动时再次检查当前默认模型的记住拒绝。这样，您的管理员重新启用的默认模型就会恢复。要关闭此记忆功能，请设置 [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](https://code.claude.com/docs/zh-CN/env-vars)。

328 334 

329### 当您的组织强制执行模型允许列表时335### 当您的组织强制执行模型允许列表时

330 336 

457 463 

458## AWS Guardrails464## AWS Guardrails

459 465 

460[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) 让您为 Claude Code 实现内容过滤。在 [Amazon Bedrock 控制台](https://console.aws.amazon.com/bedrock/)中创建 Guardrail，发布一个版本，然后将 Guardrail 标头添加到您的[设置文件](https://code.claude.com/docs/zh-CN/settings.md)。如果您使用跨区域推理配置文件，请在您的 Guardrail 上启用跨区域推理。466[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) 让您为 Claude Code 实现内容过滤。在 [Amazon Bedrock 控制台](https://console.aws.amazon.com/bedrock/)中创建 Guardrail 并发布一个版本。如果您使用跨区域推理配置文件，请在您的 Guardrail 上启用跨区域推理。

461 467 

462示例配置：468要通过 [Claude apps gateway](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 应用 Guardrail，请按照[应用 Amazon Bedrock guardrail](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config.md#apply-an-amazon-bedrock-guardrail) 中的说明操作。如果没有 Claude apps gateway，请将 Guardrail 标头添加到您的[设置文件](https://code.claude.com/docs/zh-CN/settings.md)。

469 

470设置文件配置示例：

463 471 

464```json theme={null}472```json theme={null}

465{473{

469}477}

470```478```

471 479 

472如果您的组织通过 [Claude apps gateway](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 策略传递 guardrail 标头，它们将被视为[需要批准的设置](https://code.claude.com/docs/zh-CN/server-managed-settings.md#environment-variables-and-the-approval-dialog)。

473 

474当 guardrail 在中途阻止响应时，已流式传输的文本会保留，并且回复将以 guardrail 上为被阻止响应配置的消息结尾。480当 guardrail 在中途阻止响应时，已流式传输的文本会保留，并且回复将以 guardrail 上为被阻止响应配置的消息结尾。

475 481 

476## 使用 Mantle 端点482## 使用 Mantle 端点

2512. `ANTHROPIC_AUTH_TOKEN` 环境变量。作为 `Authorization: Bearer` 标头发送。当通过[LLM 网关或代理](https://code.claude.com/docs/zh-CN/llm-gateway)进行路由时使用此选项，该网关或代理使用持有者令牌而不是 Anthropic API 密钥进行身份验证。2512. `ANTHROPIC_AUTH_TOKEN` 环境变量。作为 `Authorization: Bearer` 标头发送。当通过[LLM 网关或代理](https://code.claude.com/docs/zh-CN/llm-gateway)进行路由时使用此选项，该网关或代理使用持有者令牌而不是 Anthropic API 密钥进行身份验证。

2523. `ANTHROPIC_API_KEY` 环境变量。作为 `X-Api-Key` 标头发送。用于直接 Anthropic API 访问，使用来自 [Claude Console](https://platform.claude.com) 的密钥。在交互模式下，系统会提示您一次批准或拒绝该密钥，您的选择会被记住。要稍后更改它，请使用 `/config` 中的"使用自定义 API 密钥"切换。该切换仅在 `ANTHROPIC_API_KEY` 在您的环境中设置时出现。在非交互模式（`-p`）下，当密钥存在时始终使用该密钥。2523. `ANTHROPIC_API_KEY` 环境变量。作为 `X-Api-Key` 标头发送。用于直接 Anthropic API 访问，使用来自 [Claude Console](https://platform.claude.com) 的密钥。在交互模式下，系统会提示您一次批准或拒绝该密钥，您的选择会被记住。要稍后更改它，请使用 `/config` 中的"使用自定义 API 密钥"切换。该切换仅在 `ANTHROPIC_API_KEY` 在您的环境中设置时出现。在非交互模式（`-p`）下，当密钥存在时始终使用该密钥。

2534. [`apiKeyHelper`](https://code.claude.com/docs/zh-CN/settings-reference#apikeyhelper) 脚本输出。用于动态或轮换凭证，例如从保管库获取的短期令牌。2534. [`apiKeyHelper`](https://code.claude.com/docs/zh-CN/settings-reference#apikeyhelper) 脚本输出。用于动态或轮换凭证，例如从保管库获取的短期令牌。

2545. `CLAUDE_CODE_OAUTH_TOKEN` 环境变量。由 [`claude setup-token`](#generate-a-long-lived-token) 生成的长期 OAuth 令牌。用于 CI 管道和脚本，其中浏览器登录不可用。如果您在设置了该变量时运行 `/login`，Claude Code 会将当前会话切换到新登录，但在每个新会话中都会再次读取该变量，直到您从 shell 配置文件或[设置文件](https://code.claude.com/docs/zh-CN/settings.md)的 `env` 块中删除它。2545. `CLAUDE_CODE_OAUTH_TOKEN` 环境变量。由 [`claude setup-token`](#generate-a-long-lived-token) 生成的长期 OAuth 令牌。用于无法进行浏览器登录的 CI 管道和脚本。如果您在设置了该变量时运行 `/login`，Claude Code 会将当前会话切换到新登录。要在新会话中保留该登录，请从您的 shell 配置文件以及[可以设置该变量的设置文件](https://code.claude.com/docs/zh-CN/settings-reference.md#variables-claude-code-ignores-in-env)（例如您的用户设置）中删除该变量。

2556. Anthropic 配置文件和联合凭证，即 `ant` CLI 和 Workload Identity Federation 使用的凭证。`ant auth login` 写入的配置文件仅在您在 `ANTHROPIC_PROFILE` 中命名它时才排在此处；否则它排在 `/login` 下方。请参阅 [Anthropic 配置文件和联合凭证](#anthropic-profiles-and-federation-credentials)。2556. Anthropic 配置文件和联合凭证，即 `ant` CLI 和 Workload Identity Federation 使用的凭证。`ant auth login` 写入的配置文件仅在您在 `ANTHROPIC_PROFILE` 中命名它时才排在此处；否则它排在 `/login` 下方。请参阅 [Anthropic 配置文件和联合凭证](#anthropic-profiles-and-federation-credentials)。

2567. 来自 `/login` 的订阅 OAuth 凭据。这是 Claude Pro、Max、Ultra、Team 和 Enterprise 用户的默认设置。2567. 来自 `/login` 的订阅 OAuth 凭据。这是 Claude Pro、Max、Ultra、Team 和 Enterprise 用户的默认设置。

257 257 

603>603>

604> `claude -p --worktree` 运行需要您自己清理，因为它退出时不会询问。使用 `git worktree remove <path>` 删除它们；如果 git 因 worktree 被锁定而拒绝，请先执行 `git worktree unlock <path>`。604> `claude -p --worktree` 运行需要您自己清理，因为它退出时不会询问。使用 `git worktree remove <path>` 删除它们；如果 git 因 worktree 被锁定而拒绝，请先执行 `git worktree unlock <path>`。

605 605 

606对于跨许多文件的一次大型机械性更改，[`/batch migrate every handler to the v2 response helpers`](https://code.claude.com/docs/zh-CN/commands) 会将工作拆分为 5 到 30 个单元并向您展示计划。然后它会在各自的 worktree 中运行每个单元，并为其创建 PR。从 shell 中，[`claude agents`](https://code.claude.com/docs/zh-CN/agent-view)（目前仍为研究预览版）可以在一个屏幕上显示您机器后台运行的所有内容。606对于跨许多文件的一次大型机械性更改，[`/batch migrate every handler to the v2 response helpers`](https://code.claude.com/docs/zh-CN/commands) 会将工作拆分为 5 到 30 个单元并向您展示计划。您批准后，每个单元都会获得自己的 worktree，并创建一个 PR 或报告执行情况。从 shell 中，[`claude agents`](https://code.claude.com/docs/zh-CN/agent-view)（目前仍为研究预览版）可以在一个屏幕上显示您机器后台运行的所有内容。

607 607 

608第二个会话也是您能获得的最简单的独立审查者。一个会话编写速率限制器，另一个会话在没有看到编写过程的情况下审查 `@src/middleware/rateLimiter.ts`，然后您将发现粘贴回第一个会话。这与 `/code-review` 的思路相同，只是由您来传递消息。608第二个会话也是您能获得的最简单的独立审查者。一个会话编写速率限制器，另一个会话在没有看到编写过程的情况下审查 `@src/middleware/rateLimiter.ts`，然后您将发现粘贴回第一个会话。这与 `/code-review` 的思路相同，只是由您来传递消息。

609 609 

85| `--desktop` | 在当前目录上打开 [Claude Desktop 应用](https://code.claude.com/docs/zh-CN/desktop.md)并退出，而不在终端中启动会话。添加 `--continue`，或带会话 ID 的 `--resume`，可改为[在 Desktop 中打开该会话](https://code.claude.com/docs/zh-CN/desktop.md#coming-from-the-cli)。此处的 `--resume` 仅接受会话 ID，不接受名称或会话记录路径。不接受提示词，也不接受除 `--verbose` 和 `--debug` 标志外的其他标志，因为应用会自行启动会话。当您使用 Claude 订阅登录时，可在 macOS 和 x64 Windows 上使用。需要 Claude Code v2.1.285 或更高版本 | `claude --desktop` |85| `--desktop` | 在当前目录上打开 [Claude Desktop 应用](https://code.claude.com/docs/zh-CN/desktop.md)并退出，而不在终端中启动会话。添加 `--continue`，或带会话 ID 的 `--resume`，可改为[在 Desktop 中打开该会话](https://code.claude.com/docs/zh-CN/desktop.md#coming-from-the-cli)。此处的 `--resume` 仅接受会话 ID，不接受名称或会话记录路径。不接受提示词，也不接受除 `--verbose` 和 `--debug` 标志外的其他标志，因为应用会自行启动会话。当您使用 Claude 订阅登录时，可在 macOS 和 x64 Windows 上使用。需要 Claude Code v2.1.285 或更高版本 | `claude --desktop` |

86| `--disable-slash-commands` | 为此会话禁用所有 skill 和命令 | `claude --disable-slash-commands` |86| `--disable-slash-commands` | 为此会话禁用所有 skill 和命令 | `claude --disable-slash-commands` |

87| `--disallowedTools`, `--disallowed-tools` | 拒绝规则。裸工具名称从 Claude 的上下文中删除匹配的工具：`"Edit"` 删除 Edit，`"*"` 删除每个工具，`"mcp__*"` 删除每个 MCP 工具。作用域规则（如 `Bash(rm *)`）使工具保持可用，仅拒绝[按字面](https://code.claude.com/docs/zh-CN/permissions.md#bash-rule-limits)匹配的调用。只要还有任何其他工具保留，命名 [`EndConversation`](https://code.claude.com/docs/zh-CN/tools-reference#endconversation-tool-behavior) 的规则就无法删除它 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |87| `--disallowedTools`, `--disallowed-tools` | 拒绝规则。裸工具名称从 Claude 的上下文中删除匹配的工具：`"Edit"` 删除 Edit，`"*"` 删除每个工具，`"mcp__*"` 删除每个 MCP 工具。作用域规则（如 `Bash(rm *)`）使工具保持可用，仅拒绝[按字面](https://code.claude.com/docs/zh-CN/permissions.md#bash-rule-limits)匹配的调用。只要还有任何其他工具保留，命名 [`EndConversation`](https://code.claude.com/docs/zh-CN/tools-reference#endconversation-tool-behavior) 的规则就无法删除它 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |

88| `--effort` | 为当前会话设置 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)。选项：`low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`。可用级别取决于模型。`ultracode` 请求 `xhigh` effort 并开启 [ultracode](https://code.claude.com/docs/zh-CN/workflows.md#let-claude-decide-with-ultracode)，需要 Claude Code v2.1.203 或更高版本。覆盖此会话的 [`modelSettings`](https://code.claude.com/docs/zh-CN/settings-reference#modelsettings) 和 [`effortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#effortlevel) 设置，不会持久保存 | `claude --effort high` |88| `--effort` | 为当前会话设置 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)。选项：`low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`。可用级别取决于模型。`ultracode` 请求 `xhigh` effort 并开启 [ultracode](https://code.claude.com/docs/zh-CN/workflows.md#let-claude-decide-with-ultracode)，需要 Claude Code v2.1.203 或更高版本。对于主对话的模型，会在此会话中覆盖 [`modelSettings`](https://code.claude.com/docs/zh-CN/settings-reference#modelsettings) 和 [`effortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#effortlevel) 设置，且不会持久保存 | `claude --effort high` |

89| `--enable-auto-mode` | 在 v2.1.111 中删除。自动模式现在默认在 `Shift+Tab` 循环中；使用 `--permission-mode auto` 以该模式启动 | `claude --permission-mode auto` |89| `--enable-auto-mode` | 在 v2.1.111 中删除。自动模式现在默认在 `Shift+Tab` 循环中；使用 `--permission-mode auto` 以该模式启动 | `claude --permission-mode auto` |

90| `--environment <environment-id>` | 创建在具有给定 ID 的[自托管环境](https://code.claude.com/docs/zh-CN/self-hosted-environments)上运行的新云端会话。环境 ID 以 `ccpool_` 开头。有关调度行为和它拒绝的标志组合，请参阅 [`--environment` 调度行为](https://code.claude.com/docs/zh-CN/self-hosted-environments-testing#environment-dispatch-behavior)。需要 Claude Code v2.1.224 或更高版本 | `claude -p "Fix the login bug" --environment ccpool_abc123` |90| `--environment <environment-id>` | 创建在具有给定 ID 的[自托管环境](https://code.claude.com/docs/zh-CN/self-hosted-environments)上运行的新云端会话。环境 ID 以 `ccpool_` 开头。有关调度行为和它拒绝的标志组合，请参阅 [`--environment` 调度行为](https://code.claude.com/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| `--exclude-dynamic-system-prompt-sections` | 将每用户上下文（如自动记忆位置）从系统提示词移到第一条用户消息中。改进在运行相同任务的不同用户和机器之间的提示词缓存重用。仅适用于默认系统提示词；当设置 `--system-prompt` 或 `--system-prompt-file` 时忽略。与 `-p` 一起用于脚本化的多用户工作负载 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |91| `--exclude-dynamic-system-prompt-sections` | 将每用户上下文（如自动记忆位置）从系统提示词移到第一条用户消息中。改进在运行相同任务的不同用户和机器之间的提示词缓存重用。仅适用于默认系统提示词；当设置 `--system-prompt` 或 `--system-prompt-file` 时忽略。与 `-p` 一起用于脚本化的多用户工作负载 | `claude -p --exclude-dynamic-system-prompt-sections "query"` |

33 33 

34**2. 继续工作**34**2. 继续工作**

35 35 

36审查作为后台[子代理](https://code.claude.com/docs/zh-CN/sub-agents.md)运行，拥有自己的上下文窗口，因此不会占满您的对话。审查完成后，发现的问题会出现在您的对话中。36在终端会话中，审查作为后台[子代理](https://code.claude.com/docs/zh-CN/sub-agents.md)运行，拥有自己的上下文窗口，因此不会占满您的对话。审查完成后，发现的问题会出现在您的对话中。

37 37 

38**3. 处理发现的问题**38**3. 处理发现的问题**

39 39 

59| `/autocompact [auto\|<tokens>]` | 设置自动压缩窗口：即上下文窗口填充到多满时 Claude Code 会自动压缩。传递大小（例如 `500k`），或传递 `auto` 以恢复为针对您的模型调整的窗口。Claude Code 会将该值保存到用户设置并应用于当前会话。有关接受的值以及哪些设置会覆盖它，请参阅[设置自动压缩窗口](https://code.claude.com/docs/zh-CN/model-config.md#set-the-auto-compact-window)。不带参数时，打开显示当前窗口的对话框。需要 Claude Code v2.1.221 或更高版本 |59| `/autocompact [auto\|<tokens>]` | 设置自动压缩窗口：即上下文窗口填充到多满时 Claude Code 会自动压缩。传递大小（例如 `500k`），或传递 `auto` 以恢复为针对您的模型调整的窗口。Claude Code 会将该值保存到用户设置并应用于当前会话。有关接受的值以及哪些设置会覆盖它，请参阅[设置自动压缩窗口](https://code.claude.com/docs/zh-CN/model-config.md#set-the-auto-compact-window)。不带参数时，打开显示当前窗口的对话框。需要 Claude Code v2.1.221 或更高版本 |

60| `/autofix-pr [prompt]` | 生成一个[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md#auto-fix-pull-requests)，监视当前分支的 PR，并在 CI 失败或审阅者留下评论时推送修复。通过 `gh pr view` 从您检出的分支检测打开的 PR；要监视其他 PR，请先检出其分支。默认情况下，云端会话会被指示修复每个 CI 失败和审阅评论；传递提示词可给出不同的指令，例如 `/autofix-pr only fix lint and type errors`。需要 `gh` CLI 以及[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)访问权限 |60| `/autofix-pr [prompt]` | 生成一个[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md#auto-fix-pull-requests)，监视当前分支的 PR，并在 CI 失败或审阅者留下评论时推送修复。通过 `gh pr view` 从您检出的分支检测打开的 PR；要监视其他 PR，请先检出其分支。默认情况下，云端会话会被指示修复每个 CI 失败和审阅评论；传递提示词可给出不同的指令，例如 `/autofix-pr only fix lint and type errors`。需要 `gh` CLI 以及[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)访问权限 |

61| `/background [prompt]` | 将当前会话分离，作为[后台 Agent](https://code.claude.com/docs/zh-CN/agent-view.md) 运行，并释放此终端。传递提示词可在分离前再发送一条指令。使用 `claude agents` 监视该会话。要将对话复制到新的后台会话中，同时让当前会话继续运行，请使用 `/fork`。别名：`/bg` |61| `/background [prompt]` | 将当前会话分离，作为[后台 Agent](https://code.claude.com/docs/zh-CN/agent-view.md) 运行，并释放此终端。传递提示词可在分离前再发送一条指令。使用 `claude agents` 监视该会话。要将对话复制到新的后台会话中，同时让当前会话继续运行，请使用 `/fork`。别名：`/bg` |

62| `/batch <instruction>` | **[Skill](https://code.claude.com/docs/zh-CN/skills.md#bundled-skills)。** 在代码库中并行编排大规模更改。研究代码库，将工作分解为 5 到 30 个独立单元，并呈现计划。获得批准后，为每个单元在隔离的 [worktree](https://code.claude.com/docs/zh-CN/worktrees.md) 中生成一个[后台子代理](https://code.claude.com/docs/zh-CN/sub-agents.md#run-subagents-in-foreground-or-background)。每个子代理实现其单元、运行测试并发布其更改。需要 git 仓库，或一个用于创建 worktree 的 [`WorktreeCreate` hook](https://code.claude.com/docs/zh-CN/worktrees#non-git-version-control)。在 git 仓库之外，`/batch` 需要 Claude Code v2.1.281 或更高版本。示例：`/batch migrate src/ from JavaScript to TypeScript` |62| `/batch <instruction>` | **[Skill](https://code.claude.com/docs/zh-CN/skills.md#bundled-skills)。** 在代码库中并行编排大规模更改。研究代码库，将工作分解为 5 到 30 个独立单元，并呈现计划。获得批准后，为每个单元在隔离的 [worktree](https://code.claude.com/docs/zh-CN/worktrees.md) 中生成一个[后台子代理](https://code.claude.com/docs/zh-CN/sub-agents.md#run-subagents-in-foreground-or-background)。每个子代理实现其单元、运行测试，然后创建 PR 或报告所发生的情况。需要 git 仓库，或一个用于创建 worktree 的 [`WorktreeCreate` hook](https://code.claude.com/docs/zh-CN/worktrees#non-git-version-control)。在 git 仓库之外，`/batch` 需要 Claude Code v2.1.281 或更高版本。示例：`/batch migrate src/ from JavaScript to TypeScript` |

63| `/branch [name]` | 在此处创建当前对话的分支，以便您可以尝试不同的方向而不丢失当前的对话。会将您切换到该分支并保留原始对话，您可以使用 `/resume` 返回原始对话。要将副本作为单独的[后台会话](https://code.claude.com/docs/zh-CN/agent-view.md)运行而不切换进去，请使用 `/fork`；要将附带任务交给会向此对话汇报结果的[子代理](https://code.claude.com/docs/zh-CN/sub-agents.md)，请使用 `/subtask` |63| `/branch [name]` | 在此处创建当前对话的分支，以便您可以尝试不同的方向而不丢失当前的对话。会将您切换到该分支并保留原始对话，您可以使用 `/resume` 返回原始对话。要将副本作为单独的[后台会话](https://code.claude.com/docs/zh-CN/agent-view.md)运行而不切换进去，请使用 `/fork`；要将附带任务交给会向此对话汇报结果的[子代理](https://code.claude.com/docs/zh-CN/sub-agents.md)，请使用 `/subtask` |

64| `/btw [question]` | 询问有关当前会话的[附带问题](https://code.claude.com/docs/zh-CN/interactive-mode.md#side-questions-with-%2Fbtw)，而不将其添加到对话中。如果不带问题运行 `/btw`，Claude Code 会显示您最近的附带问题，以便您浏览之前的回答；如果您还没有提问过，Claude Code 会输出一行用法说明 |64| `/btw [question]` | 询问有关当前会话的[附带问题](https://code.claude.com/docs/zh-CN/interactive-mode.md#side-questions-with-%2Fbtw)，而不将其添加到对话中。如果不带问题运行 `/btw`，Claude Code 会显示您最近的附带问题，以便您浏览之前的回答；如果您还没有提问过，Claude Code 会输出一行用法说明 |

65| `/bug [report]` | 报告 bug 或分享您的对话。您可以选择包含多少会话历史，并在发送任何内容之前在同意屏幕上确认。当您通过第一方连接登录 Anthropic 时，报告会发送给 Anthropic；在第三方提供商上，或没有 Anthropic 凭据时，Claude Code 会将报告写入[位于 `~/.claude/feedback-bundles/` 下的本地归档](https://code.claude.com/docs/zh-CN/data-usage#telemetry-services)，由您自行转发。在 [VS Code 扩展](https://code.claude.com/docs/zh-CN/vs-code.md#use-the-prompt-box)中，`/bug` 会改为打开扩展自己的反馈对话框；需要 Claude Code v2.1.229 或更高版本。如果在 Claude 回复时运行此命令，Claude Code 会立即打开对话框。在 v2.1.232 之前，Claude Code 会将该命令排队，直到该轮次结束。别名：`/share`。在 v2.1.212 之前，`/bug` 和 `/share` 是 `/feedback` 的别名 |65| `/bug [report]` | 报告 bug 或分享您的对话。您可以选择包含多少会话历史，并在发送任何内容之前在同意屏幕上确认。当您通过第一方连接登录 Anthropic 时，报告会发送给 Anthropic；在第三方提供商上，或没有 Anthropic 凭据时，Claude Code 会将报告写入[位于 `~/.claude/feedback-bundles/` 下的本地归档](https://code.claude.com/docs/zh-CN/data-usage#telemetry-services)，由您自行转发。在 [VS Code 扩展](https://code.claude.com/docs/zh-CN/vs-code.md#use-the-prompt-box)中，`/bug` 会改为打开扩展自己的反馈对话框；需要 Claude Code v2.1.229 或更高版本。如果在 Claude 回复时运行此命令，Claude Code 会立即打开对话框。在 v2.1.232 之前，Claude Code 会将该命令排队，直到该轮次结束。别名：`/share`。在 v2.1.212 之前，`/bug` 和 `/share` 是 `/feedback` 的别名 |

335| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 设置为 `1` 可通过第二个非阻塞文件描述符写入终端输出，这样停止读取的终端（例如已暂停的 tmux 控制模式窗格或停滞的 SSH 连接）就不会在会话中途冻结 Claude Code。在 stdout 为终端时适用于 macOS、Linux 和 WSL。需要 Claude Code v2.1.261 或更高版本 |335| `CLAUDE_CODE_NONBLOCKING_STDOUT` | 设置为 `1` 可通过第二个非阻塞文件描述符写入终端输出，这样停止读取的终端（例如已暂停的 tmux 控制模式窗格或停滞的 SSH 连接）就不会在会话中途冻结 Claude Code。在 stdout 为终端时适用于 macOS、Linux 和 WSL。需要 Claude Code v2.1.261 或更高版本 |

336| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 限制 Claude Code 重新发送超时的[非流式请求](https://code.claude.com/docs/zh-CN/errors.md#streaming-response-ended-before-any-complete-data-was-received)的次数。设置为 `0` 时，请求在第一次超时时即失败。有关超时时间，请参阅[调整重试行为](https://code.claude.com/docs/zh-CN/errors.md#tune-retry-behavior)。需要 Claude Code v2.1.285 或更高版本 |336| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 限制 Claude Code 重新发送超时的[非流式请求](https://code.claude.com/docs/zh-CN/errors.md#streaming-response-ended-before-any-complete-data-was-received)的次数。设置为 `0` 时，请求在第一次超时时即失败。有关超时时间，请参阅[调整重试行为](https://code.claude.com/docs/zh-CN/errors.md#tune-retry-behavior)。需要 Claude Code v2.1.285 或更高版本 |

337| `CLAUDE_CODE_NO_FLICKER` | 设置为 `1` 可启用[全屏渲染](https://code.claude.com/docs/zh-CN/fullscreen.md)，这是一项研究预览功能，可减少闪烁并在长对话中保持内存占用平稳。覆盖 [`tui`](https://code.claude.com/docs/zh-CN/settings-reference#tui) 设置；您也可以使用 `/tui fullscreen` 进行切换 |337| `CLAUDE_CODE_NO_FLICKER` | 设置为 `1` 可启用[全屏渲染](https://code.claude.com/docs/zh-CN/fullscreen.md)，这是一项研究预览功能，可减少闪烁并在长对话中保持内存占用平稳。覆盖 [`tui`](https://code.claude.com/docs/zh-CN/settings-reference#tui) 设置；您也可以使用 `/tui fullscreen` 进行切换 |

338| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | 用于 Claude.ai 身份验证的 OAuth 刷新令牌。设置后，`claude auth login` 会直接交换此令牌，而不是打开浏览器。需要同时设置 `CLAUDE_CODE_OAUTH_SCOPES`。适用于在自动化环境中预配身份验证 |338| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | 用于 claude.ai 身份验证的 OAuth 刷新令牌。设置后，`claude auth login` 会直接交换此令牌，而不是打开浏览器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。适用于在自动化环境中预置身份验证。在[项目设置和本地设置](https://code.claude.com/docs/zh-CN/settings-reference.md#variables-claude-code-ignores-in-env)中会被忽略 |

339| `CLAUDE_CODE_OAUTH_SCOPES` | 颁发刷新令牌时使用的以空格分隔的 OAuth 作用域，例如 `"user:profile user:inference user:sessions:claude_code"`。设置 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 时必需 |339| `CLAUDE_CODE_OAUTH_SCOPES` | 签发刷新令牌时使用的 OAuth 作用域，以空格分隔，例如 `"user:profile user:inference user:sessions:claude_code"`。设置 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 时必需。在[项目设置和本地设置](https://code.claude.com/docs/zh-CN/settings-reference.md#variables-claude-code-ignores-in-env)中会被忽略 |

340| `CLAUDE_CODE_OAUTH_TOKEN` | 用于 claude.ai 身份验证的 OAuth 访问令牌。是 SDK 和自动化环境中 `/login` 的替代方案。优先于钥匙串中存储的凭据。可使用 [`claude setup-token`](https://code.claude.com/docs/zh-CN/authentication#generate-a-long-lived-token) 生成。除非您运行 [`/login`](https://code.claude.com/docs/zh-CN/authentication#authentication-precedence)，否则 Claude Code 会在整个会话中使用您设置的令牌。要替换过期的令牌，请生成新令牌并重新启动 |340| `CLAUDE_CODE_OAUTH_TOKEN` | 用于 claude.ai 身份验证的 OAuth 访问令牌。在 SDK 和自动化环境中可替代 `/login`。在[项目设置和本地设置](https://code.claude.com/docs/zh-CN/settings-reference.md#variables-claude-code-ignores-in-env)中会被忽略。优先于存储在钥匙串中的凭据。使用 [`claude setup-token`](https://code.claude.com/docs/zh-CN/authentication#generate-a-long-lived-token) 生成。除非您运行 [`/login`](https://code.claude.com/docs/zh-CN/authentication#authentication-precedence)，否则 Claude Code 会在整个会话中使用您设置的令牌。要替换已过期的令牌，请生成新令牌并重新启动 |

341| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 已在 v2.1.160 中移除，现在不起作用。此前用于将[快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md)固定到 Claude Opus 4.6，而不是当前默认模型。Opus 4.6 不再支持快速模式 |341| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 已在 v2.1.160 中移除，现在不起作用。此前用于将[快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md)固定到 Claude Opus 4.6，而不是当前默认模型。Opus 4.6 不再支持快速模式 |

342| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 承载内容的 OpenTelemetry 属性（模型响应、工具内容、系统提示词、原始 API 正文）的最大长度，包含截断标记，以 UTF-16 代码单元计（默认：61440，即 60 KB）。仅当您的遥测后端接受大于 64 KB 的属性值时才调高此值，也可以调低此值以减少遥测数据量。需要 Claude Code v2.1.214 或更高版本。请参阅[监控](https://code.claude.com/docs/zh-CN/monitoring-usage.md) |342| `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` | 承载内容的 OpenTelemetry 属性（模型响应、工具内容、系统提示词、原始 API 正文）的最大长度，包含截断标记，以 UTF-16 代码单元计（默认：61440，即 60 KB）。仅当您的遥测后端接受大于 64 KB 的属性值时才调高此值，也可以调低此值以减少遥测数据量。需要 Claude Code v2.1.214 或更高版本。请参阅[监控](https://code.claude.com/docs/zh-CN/monitoring-usage.md) |

343| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 设置为 `1` 可将 OpenTelemetry 导出器的诊断错误写入 stderr。默认情况下，这些错误仅在使用 `--debug` 时显示，因此配置错误的导出器（例如 Prometheus 端口冲突）否则会静默失败。需要 Claude Code v2.1.179 或更高版本。请参阅[监控](https://code.claude.com/docs/zh-CN/monitoring-usage.md) |343| `CLAUDE_CODE_OTEL_DIAG_STDERR` | 设置为 `1` 可将 OpenTelemetry 导出器的诊断错误写入 stderr。默认情况下，这些错误仅在使用 `--debug` 时显示，因此配置错误的导出器（例如 Prometheus 端口冲突）否则会静默失败。需要 Claude Code v2.1.179 或更高版本。请参阅[监控](https://code.claude.com/docs/zh-CN/monitoring-usage.md) |

66| `This organization has been disabled` | [身份验证](#this-organization-has-been-disabled) |66| `This organization has been disabled` | [身份验证](#this-organization-has-been-disabled) |

67| `Your organization has disabled API key authentication` | [身份验证](#your-organization-has-disabled-api-key-authentication) |67| `Your organization has disabled API key authentication` | [身份验证](#your-organization-has-disabled-api-key-authentication) |

68| `Your organization has disabled Claude subscription access` | [身份验证](#your-organization-has-disabled-claude-subscription-access) |68| `Your organization has disabled Claude subscription access` | [身份验证](#your-organization-has-disabled-claude-subscription-access) |

69| `Routines are disabled by your organization's policy` | [身份验证](#routines-are-disabled-by-your-organizations-policy) |69| `Scheduled tasks are off for your organization` | [身份验证](#routines-are-disabled-by-your-organizations-policy) |

70| `Routines are off for your organization` | [身份验证](#routines-are-disabled-by-your-organizations-policy) |

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

71| `OAuth token refresh failed — run /login to re-authenticate` | [身份验证](#remote-control-couldnt-refresh-your-login) |72| `OAuth token refresh failed — run /login to re-authenticate` | [身份验证](#remote-control-couldnt-refresh-your-login) |

72| `JWT refresh failed: no OAuth token — run /login` | [身份验证](#remote-control-couldnt-refresh-your-login) |73| `JWT refresh failed: no OAuth token — run /login` | [身份验证](#remote-control-couldnt-refresh-your-login) |

755Auto mode is unavailable — the server returned no safety verdict for the last 10 responses, so Claude stopped. Send a message to try again, or switch out of auto mode.756Auto mode is unavailable — the server returned no safety verdict for the last 10 responses, so Claude stopped. Send a message to try again, or switch out of auto mode.

756```757```

757 758 

759某些拒绝不计入这十次，包括[因 hook 或 mod 的更改而导致的拒绝](#hook-changed-input-after-review)。

760 

758停止消息在每种会话中出现在不同的位置：761停止消息在每种会话中出现在不同的位置：

759 762 

760* 在交互式会话中，消息作为警告出现在会话记录中，轮次结束763* 在交互式会话中，消息作为警告出现在会话记录中，轮次结束

774 777 

775在 v2.1.302 之前，在直接连接到 Anthropic API 时，Claude Code 不会压缩已增长到对服务器检查而言过长的对话。778在 v2.1.302 之前，在直接连接到 Anthropic API 时，Claude Code 不会压缩已增长到对服务器检查而言过长的对话。

776 779 

780#### `a hook changed this call's input after auto mode reviewed it`

781 

782此拒绝表示 hook 或 mod 在服务器审查该调用之后[更改了该调用的输入](https://code.claude.com/docs/zh-CN/hooks.md#pretooluse-updatedinput-in-auto-mode)，因此审查并未覆盖将要运行的内容。这并不是对该操作不安全的判断。

783 

784同一 Claude 回复中的后续调用可能会以此原因被拒绝：

785 

786```text theme={null}

787another call in this response was changed by a hook after auto mode reviewed it, or could not be confirmed unchanged

788```

789 

790Claude 随后可以再次发出每个被拒绝的调用，以便服务器对其进行审查。如果打开了权限提示，请作出回应。除非 Claude 在回复中说明自动模式无法检查该调用，否则您无需执行其他任何操作。在这种情况下，请停止该更改或自行批准该调用，然后让 Claude 再次尝试该调用：

791 

792* **停止该更改**：关闭更改了该调用或同一 Claude 回复中较早调用的 [hook](https://code.claude.com/docs/zh-CN/hooks.md#disable-or-remove-hooks) 或 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md#turn-mods-on-or-off)，或请您的管理员将其关闭。要查找 hook，请在 Claude Code 提示符处运行 [`/hooks`](https://code.claude.com/docs/zh-CN/hooks#the-%2Fhooks-menu)。在终端会话中，运行 `/plugin` 查看已启用的 mod。

793* **自行批准该调用**：[切换到手动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#switch-permission-modes)

794 

777### Was not reviewed and did not run795### Was not reviewed and did not run

778 796 

779`was not reviewed and did not run` 拒绝表示对话过长，[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)分类器无法检查该操作，因此该操作没有运行。Claude Code 向 Claude 返回以下消息：797`was not reviewed and did not run` 拒绝表示对话过长，[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)分类器无法检查该操作，因此该操作没有运行。Claude Code 向 Claude 返回以下消息：

1188* 改用 Console API 密钥而不是订阅进行身份验证。设置方法请参阅 [Claude Console 身份验证](https://code.claude.com/docs/zh-CN/authentication.md#claude-console-authentication)。1206* 改用 Console API 密钥而不是订阅进行身份验证。设置方法请参阅 [Claude Console 身份验证](https://code.claude.com/docs/zh-CN/authentication.md#claude-console-authentication)。

1189* 如果您是管理员但找不到启用访问的选项，请联系 [Anthropic 支持](https://support.claude.com)1207* 如果您是管理员但找不到启用访问的选项，请联系 [Anthropic 支持](https://support.claude.com)

1190 1208 

1191### Routine 已被您组织的策略禁用1209### Scheduled tasks are off for your organization

1192 1210 

1193您的 Team 或 Enterprise 组织中的 Owner 已在组织级别关闭了[云端定时任务](https://code.claude.com/docs/zh-CN/routines.md)（原 Routine）。当您尝试创建或运行定时任务时（例如在 [claude.ai/code/routines](https://claude.ai/code/routines) 上），会出现此错误。在 Claude Code v2.1.227 或更高版本中，同一设置还会在 CLI 中[隐藏 `/schedule`](https://code.claude.com/docs/zh-CN/routines#troubleshooting)。1211您的组织已关闭[云端定时任务](https://code.claude.com/docs/zh-CN/routines.md)，因此您无法创建或运行它们。来自 claude.ai 的消息会将其称为 scheduled tasks 或 routines，后面跟着一句关于您的管理员的说明：

1194 1212 

1195```text theme={null}1213```text theme={null}

1196Routines are disabled by your organization's policy.1214Scheduled tasks are off for your organization. …

1215Routines are off for your organization. …

1197```1216```

1198 1217 

1199这是服务器端设置，因此无法通过本地设置、环境变量或 CLI 标志覆盖。1218您无法通过本地设置、环境变量或 CLI 标志启用它们。

1200 1219 

1201**解决方法：**1220**解决方法：**

1202 1221 

1203* 请组织中的 Owner 在 [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities) 中打开 **Scheduled tasks (Was Routines)** 开关1222* 询问您的 Team 或 Enterprise Owner 能否在 [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities) 中打开标记为 **Scheduled tasks (Was Routines)** 或 **Routines** 的开关

1204 1223 

1205### Remote Control 需要 Anthropic API1224### Remote Control 需要 Anthropic API

1206 1225 

197* **如果您接受**：Claude Code 会将新的模型 ID 写入您的[用户设置文件](https://code.claude.com/docs/zh-CN/settings.md)并重启197* **如果您接受**：Claude Code 会将新的模型 ID 写入您的[用户设置文件](https://code.claude.com/docs/zh-CN/settings.md)并重启

198* **如果您拒绝**：Claude Code 会记住您的选择，直到下一次默认版本更改198* **如果您拒绝**：Claude Code 会记住您的选择，直到下一次默认版本更改

199 199 

200对于[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)的 `env` 块中的固定，Claude Code 不会运行检查，也不会显示提示。200对于[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)的 `env` 块中的固定，Claude Code 不会运行检查，也不会显示提示。如果针对此固定仍然出现更新提示，请将 Claude Code 更新到 v2.1.314 或更高版本。在 v2.1.314 之前，您接受后托管固定仍然有效，因此下次启动时提示会再次出现。

201 201 

202如果您没有固定模型，并且当前默认值在您的项目中不可用，Claude Code 会在当前会话中回退并显示通知。它首先尝试默认模型的早期版本，当默认值是 Opus 模型且没有可用的 Opus 版本时，会回退到默认 Sonnet 模型。回退不会被持久化。在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中启用较新的模型或[固定一个版本](#5-pin-model-versions)以使选择永久化。202如果您没有固定模型，并且当前默认值在您的项目中不可用，Claude Code 会在当前会话中回退并显示通知。它首先尝试默认模型的早期版本，当默认值是 Opus 模型且没有可用的 Opus 版本时，会回退到默认 Sonnet 模型。回退不会被持久化。在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中启用较新的模型或[固定一个版本](#5-pin-model-versions)以使选择永久化。

203 203 

204### 在特定模型上启动会话

205 

204当您在特定的 Sonnet 或 Opus 版本上启动会话时，例如使用 `--model`、`ANTHROPIC_MODEL` 或 [`model` 设置](https://code.claude.com/docs/zh-CN/settings-reference#model)，该版本充当会话的固定默认值，用于匹配的 `sonnet` 或 `opus` 别名。Claude Code 跳过对您的模型替换的内置默认值的可用性检查，并在您配置的模型上启动，没有回退通知。206当您在特定的 Sonnet 或 Opus 版本上启动会话时，例如使用 `--model`、`ANTHROPIC_MODEL` 或 [`model` 设置](https://code.claude.com/docs/zh-CN/settings-reference#model)，该版本充当会话的固定默认值，用于匹配的 `sonnet` 或 `opus` 别名。Claude Code 跳过对您的模型替换的内置默认值的可用性检查，并在您配置的模型上启动，没有回退通知。

205 207 

206模型别名（如 `opus`）不充当固定值，Claude Code 不识别的模型 ID 也不充当固定值。208当您在模型别名（如 `opus`）或 Claude Code 不识别的模型 ID 上启动会话时，该值不充当固定值。

209 

210### 记住的模型拒绝

207 211 

208当这些检查发现您的项目无法调用的模型时，Claude Code 会在这台机器上记住该拒绝长达一天，并在此期间启动时跳过记住的模型，而不再询问 Agent Platform。Claude Code 会在距离上次检查已过十分钟后，再次检查当前默认模型的记住拒绝，因此管理员重新启用的默认值会恢复。要关闭此内存，请设置 [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](https://code.claude.com/docs/zh-CN/env-vars)。212当启动模型检查发现您的项目无法调用的模型时，Claude Code 可以在这台机器上记住该拒绝长达一天。距离上次检查已过十分钟后，Claude Code 会在启动时再次检查当前默认模型的记住拒绝。这样，管理员重新启用的默认值就会恢复。要关闭此记忆，请设置 [`CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY=1`](https://code.claude.com/docs/zh-CN/env-vars)。

209 213 

210### 当您的组织强制执行模型允许列表时214### 当您的组织强制执行模型允许列表时

211 215 

901 901 

902#### hook 失败时阻止操作902#### hook 失败时阻止操作

903 903 

904在大多数事件上，当 hook 失败或超时时，Claude Code 仍会执行该操作。这样一来，路径错误或脚本崩溃的策略 hook 会放行一切。要改为阻止操作，请在 `command` 或 `http` hook 上设置 `"onFailure": "block"`。需要 Claude Code v2.1.295 或更高版本。904在大多数事件上，当 hook 失败或超时时，Claude Code 仍会执行该操作。这样一来，路径错误或脚本崩溃的策略 hook 会放行一切。要改为阻止操作，请在 `command` 或 `http` hook 上设置 `"onFailure": "block"`。需要 Claude Code v2.1.295 或更高版本。关于 Agent SDK 回调 hook，请参阅[回调失败时阻止操作](https://code.claude.com/docs/zh-CN/agent-sdk/hooks.md#block-the-action-when-a-callback-fails)。

905 905 

906> [!NOTE]906> [!NOTE]

907>907>

1960| :- | :- |1960| :- | :- |

1961| `permissionDecision` | `"allow"` 会跳过权限提示，但[任何模式都不会自动批准的操作](https://code.claude.com/docs/zh-CN/permission-modes.md#actions-no-mode-auto-approves)和[从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)除外。对于[Agent SDK 应用标记为 `always_ask` 的工具](https://code.claude.com/docs/zh-CN/agent-sdk/custom-tools#require-approval-for-specific-tools)的调用，它同样不会跳过批准，除非[权限模式批准该调用](https://code.claude.com/docs/zh-CN/agent-sdk/typescript.md#permission-modes-that-can-approve-an-always_ask-call)。`AskUserQuestion` 和 `ExitPlanMode` 需要[将 `updatedInput` 与 `"allow"` 搭配使用](#allow-with-updatedinput)。有关计划模式，请参阅[计划模式中的 hook 批准](https://code.claude.com/docs/zh-CN/permissions.md#hook-approvals-in-plan-mode)。`"deny"` 会阻止工具调用。`"ask"` 会提示用户确认。`"defer"` 会结束当前轮次，以便稍后恢复该工具，并且需要在使用 `-p` 标志的[非交互模式](#defer-a-tool-call-for-later)下运行。无论 hook 返回什么，[拒绝和询问规则](https://code.claude.com/docs/zh-CN/permissions.md#manage-permissions)仍会被评估 |1961| `permissionDecision` | `"allow"` 会跳过权限提示，但[任何模式都不会自动批准的操作](https://code.claude.com/docs/zh-CN/permission-modes.md#actions-no-mode-auto-approves)和[从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)除外。对于[Agent SDK 应用标记为 `always_ask` 的工具](https://code.claude.com/docs/zh-CN/agent-sdk/custom-tools#require-approval-for-specific-tools)的调用，它同样不会跳过批准，除非[权限模式批准该调用](https://code.claude.com/docs/zh-CN/agent-sdk/typescript.md#permission-modes-that-can-approve-an-always_ask-call)。`AskUserQuestion` 和 `ExitPlanMode` 需要[将 `updatedInput` 与 `"allow"` 搭配使用](#allow-with-updatedinput)。有关计划模式，请参阅[计划模式中的 hook 批准](https://code.claude.com/docs/zh-CN/permissions.md#hook-approvals-in-plan-mode)。`"deny"` 会阻止工具调用。`"ask"` 会提示用户确认。`"defer"` 会结束当前轮次，以便稍后恢复该工具，并且需要在使用 `-p` 标志的[非交互模式](#defer-a-tool-call-for-later)下运行。无论 hook 返回什么，[拒绝和询问规则](https://code.claude.com/docs/zh-CN/permissions.md#manage-permissions)仍会被评估 |

1962| `permissionDecisionReason` | 对于 `"ask"`，在权限提示中显示给用户。当 Claude Code 在无人能回应该提示的 `-p` 运行中[拒绝该调用](https://code.claude.com/docs/zh-CN/headless.md#turn-off-permission-prompts-in-unattended-runs)时，Claude 会在工具结果中读取该原因。对于 `"deny"`，显示给 Claude。对于 `"allow"` 和 `"defer"`，仅写入[调试日志](#debug-hooks) |1962| `permissionDecisionReason` | 对于 `"ask"`，在权限提示中显示给用户。当 Claude Code 在无人能回应该提示的 `-p` 运行中[拒绝该调用](https://code.claude.com/docs/zh-CN/headless.md#turn-off-permission-prompts-in-unattended-runs)时，Claude 会在工具结果中读取该原因。对于 `"deny"`，显示给 Claude。对于 `"allow"` 和 `"defer"`，仅写入[调试日志](#debug-hooks) |

1963| `updatedInput` | 在执行前修改工具的输入参数。会替换整个输入对象，因此请将未更改的字段与修改后的字段一起包含。Claude Code 会针对您的 hook 返回的输入（而非 Claude 发送的输入）评估权限规则以及 Bash 命令的[自动转入后台资格](https://code.claude.com/docs/zh-CN/tools-reference.md#foreground-commands-that-move-to-the-background)。与 `"allow"` 结合可自动批准，与 `"ask"` 结合可向用户显示修改后的输入。对于 `"defer"`，会被忽略 |1963| `updatedInput` | 在执行前修改工具的输入参数。会替换整个输入对象，因此请将未更改的字段与修改后的字段一并包含。Claude Code 会根据您的 hook 返回的输入（而不是 Claude 发送的输入）评估权限规则和 Bash 命令的[自动转入后台资格](https://code.claude.com/docs/zh-CN/tools-reference.md#foreground-commands-that-move-to-the-background)。与 `"allow"` 组合可自动批准，与 `"ask"` 组合可向用户显示修改后的输入。对于 `"defer"`，会被忽略。如果没有 `permissionDecision`，[自动模式可能会拒绝更改后的调用](#pretooluse-updatedinput-in-auto-mode) |

1964| `additionalContext` | 与工具结果一起添加到 Claude 上下文中的字符串。当 `permissionDecision` 为 `"defer"` 时会被忽略。请参阅[为 Claude 添加上下文](#add-context-for-claude) |1964| `additionalContext` | 与工具结果一起添加到 Claude 上下文中的字符串。当 `permissionDecision` 为 `"defer"` 时会被忽略。请参阅[为 Claude 添加上下文](#add-context-for-claude) |

1965 1965 

1966当多个 PreToolUse hook 返回不同的决策时，优先级为 `deny` > `defer` > `ask` > `allow`。1966当多个 PreToolUse hook 返回不同的决策时，优先级为 `deny` > `defer` > `ask` > `allow`。

1987>1987>

1988> PreToolUse 以前使用顶层的 `decision` 和 `reason` 字段，但这些字段在此事件中已弃用。请改用 `hookSpecificOutput.permissionDecision` 和 `hookSpecificOutput.permissionDecisionReason`。已弃用的值 `"approve"` 和 `"block"` 分别映射到 `"allow"` 和 `"deny"`。PostToolUse 和 Stop 等其他事件继续使用顶层 `decision` 和 `reason` 作为其当前格式。1988> PreToolUse 以前使用顶层的 `decision` 和 `reason` 字段，但这些字段在此事件中已弃用。请改用 `hookSpecificOutput.permissionDecision` 和 `hookSpecificOutput.permissionDecisionReason`。已弃用的值 `"approve"` 和 `"block"` 分别映射到 `"allow"` 和 `"deny"`。PostToolUse 和 Stop 等其他事件继续使用顶层 `decision` 和 `reason` 作为其当前格式。

1989 1989 

1990#### 自动模式下的 PreToolUse `updatedInput`

1991 

1992在[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)下，当您的 hook 返回 `updatedInput` 而没有 `permissionDecision` 时，Claude Code 可能会拒绝更改后的调用。[服务器审查的](https://code.claude.com/docs/zh-CN/permission-modes.md#server-side-classifier-review)是 Claude 编写的输入，而不是您的 hook 返回的输入。在直接连接到 Anthropic API 的交互式终端会话和 VS Code 会话中，拒绝信息包含以下文本：

1993 

1994```text theme={null}

1995a hook changed this call's input after auto mode reviewed it

1996```

1997 

1998在出现带有此文本的拒绝后，Claude 可以再次发出更改后的调用，以便服务器审查它。如果 Claude 在下一条回复中原样重复更改后的输入，您的 hook 仍会运行：

1999 

2000* 它可以拒绝该调用或将其发送到权限提示

2001* 它返回的任何 `updatedInput` 都会被丢弃，因此实际运行的是服务器审查过的内容

2002 

2003除非 [Claude 在回复中告诉您自动模式无法检查该调用](https://code.claude.com/docs/zh-CN/errors.md#hook-changed-input-after-review)，否则您无需为此拒绝更改您的 hook。

2004 

2005在显示此文本的会话中，设置或插件 hook 文件中的 [`command` hook](#command-hook-fields) 可以更改 Bash、PowerShell、Monitor、Edit、Write 和 NotebookEdit 调用而不触发此拒绝。该拒绝仍可能出现，例如当任何 hook 更改了同一条 Claude 回复中较早的调用，或者 Bash 命令请求在沙箱之外运行时。

2006 

1990#### 自动模式下的 PreToolUse `ask` 决策2007#### 自动模式下的 PreToolUse `ask` 决策

1991 2008 

1992在[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)下，PreToolUse hook 返回的 `"ask"` 通常会将工具调用发送到权限提示，[分类器](https://code.claude.com/docs/zh-CN/permission-modes.md#how-the-classifier-evaluates-actions)不会对其做出决定。某些调用会走不同的路径：2009在[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)下，PreToolUse hook 返回的 `"ask"` 通常会将工具调用发送到权限提示，[分类器](https://code.claude.com/docs/zh-CN/permission-modes.md#how-the-classifier-evaluates-actions)不会对其做出决定。某些调用会走不同的路径：

287 287 

288### 使用 Ctrl+R 进行反向搜索288### 使用 Ctrl+R 进行反向搜索

289 289 

290按 `Ctrl+R` 以交互方式搜索你的命令历史。在[全屏渲染](https://code.claude.com/docs/zh-CN/fullscreen.md)中，`Ctrl+R` 打开搜索对话框：输入以过滤，按 `Up` 和 `Down` 在匹配项中移动，按 `Ctrl+S` 循环切换范围（此会话、此项目和所有项目）。按 `Enter` 或 `Tab` 将匹配项放在提示词输入中，或按 `Esc` 取消。下面的步骤描述经典渲染器的内联搜索：290按 `Ctrl+R` 以交互方式搜索您的命令历史。在[全屏渲染](https://code.claude.com/docs/zh-CN/fullscreen.md)中，`Ctrl+R` 会改为打开一个搜索对话框。在对话框中输入以进行过滤，按 `Up` 和 `Down` 在匹配项列表中移动，预览窗格会显示当前突出显示的匹配项的开头部分。

291 

292在对话框中，按 `Ctrl+S` 可在此会话、此项目和所有项目之间循环切换范围。按 `Enter` 或 `Tab` 将匹配项放入提示词输入框，或按 `Esc` 取消。下面的步骤描述经典渲染器的内联搜索：

291 293 

2921. **开始搜索**：按 `Ctrl+R` 激活反向历史搜索2941. **开始搜索**：按 `Ctrl+R` 激活反向历史搜索

2932. **输入查询**：输入要在以前的命令中搜索的文本。搜索词在匹配结果中突出显示2952. **输入查询**：输入要在以前的命令中搜索的文本。当前匹配项会显示在提示词输入框中。

2943. **导航匹配项**：再次按 `Ctrl+R` 循环浏览较早的匹配项2963. **导航匹配项**：再次按 `Ctrl+R` 循环浏览较早的匹配项

2954. **搜索范围**：内联搜索始终搜索来自所有项目的提示词2974. **搜索范围**：内联搜索始终搜索来自所有项目的提示词

2965. **接受匹配项**：2985. **接受匹配项**：

300 * 按 `Ctrl+C` 取消并恢复你的原始输入302 * 按 `Ctrl+C` 取消并恢复你的原始输入

301 * 在空搜索上按 `Backspace` 取消303 * 在空搜索上按 `Backspace` 取消

302 304 

303内联搜索扫描你的完整提示词历史，最新的优先，重复项折叠到最新出现。全屏对话框在选定的范围内搜索你的整个提示词历史，最新的优先，重复项折叠到最新出现：最近的提示词立即出现，较早提示词的匹配项在 Claude Code 加载其余部分时填充。匹配的提示词显示时搜索词突出显示，因此你可以找到并重用以前的输入。

304 

305接受匹配项或取消搜索立即生效，即使 Claude Code 仍在加载历史记录。305接受匹配项或取消搜索立即生效，即使 Claude Code 仍在加载历史记录。

306 306 

307## 后台 Bash 命令307## 后台 Bash 命令

39 39 

40从 JetBrains Marketplace 安装 [Claude Code 插件](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-)，然后重启您的 IDE。40从 JetBrains Marketplace 安装 [Claude Code 插件](https://plugins.jetbrains.com/plugin/27310-claude-code-beta-)，然后重启您的 IDE。

41 41 

42> [!NOTE]

43>

44> JetBrains Marketplace 是第三方软件，Anthropic 不为其背书，也不对其进行维护或审核。Anthropic 会将 Claude Code 插件提交至 JetBrains Marketplace 进行发布。

45 

42如果 `claude` 安装在您的 IDE 找不到的位置，请在插件的 [Claude 命令设置](#general-settings)中设置完整路径。46如果 `claude` 安装在您的 IDE 找不到的位置，请在插件的 [Claude 命令设置](#general-settings)中设置完整路径。

43 47 

44Claude Code 适用于任何付费 Claude 订阅（Pro、Max、Ultra、Team 或 Enterprise）或 Claude Console 账户，无需 API 密钥。首次运行 `claude` 时，系统会提示您[登录](https://code.claude.com/docs/zh-CN/authentication.md#log-in-to-claude-code)。48Claude Code 适用于任何付费 Claude 订阅（Pro、Max、Ultra、Team 或 Enterprise）或 Claude Console 账户，无需 API 密钥。首次运行 `claude` 时，系统会提示您[登录](https://code.claude.com/docs/zh-CN/authentication.md#log-in-to-claude-code)。

278 278 

279在 v2.1.305 或更高版本上，在出现命名工具搜索或 Claude Code 无法识别原因的 `400` 或 `422` 之后，Claude Code 会重新发送不带 [`defer_loading` 字段和 `tool_reference` 块](https://code.claude.com/docs/zh-CN/mcp#tool-search-through-a-gateway)的请求。重试成功后，该对话中的后续请求也会省略它们。279在 v2.1.305 或更高版本上，在出现命名工具搜索或 Claude Code 无法识别原因的 `400` 或 `422` 之后，Claude Code 会重新发送不带 [`defer_loading` 字段和 `tool_reference` 块](https://code.claude.com/docs/zh-CN/mcp#tool-search-through-a-gateway)的请求。重试成功后，该对话中的后续请求也会省略它们。

280 280 

281开发者的请求无需对网关做任何更改即可继续正常工作，其 MCP 工具会预先加载。当 Claude Code 再次尝试工具搜索时，网关会再次看到被拒绝的请求及其后的重试。对于工具搜索本身，Claude Code 期望网关将 `defer_loading` 字段和 `tool_reference` 块连同其 `anthropic-beta` 值一起转发。281开发者的请求无需在网关上做任何更改即可继续正常工作，其 MCP 工具会预先加载。当 Claude Code 再次尝试工具搜索时，网关会看到又一个被拒绝的请求，随后是该请求的重试。对于工具搜索本身，Claude Code 要求网关转发 `defer_loading` 字段和 `tool_reference` 块，以及它们对应的 `anthropic-beta` 值。

282 282 

283### 禁用预发布功能283### 禁用预发布功能

284 284 

171* 沙箱二进制路径 `sandbox.bwrapPath` 和 `sandbox.socatPath`171* 沙箱二进制路径 `sandbox.bwrapPath` 和 `sandbox.socatPath`

172* 沙箱 `ripgrep` 二进制文件，[`sandbox.ripgrep`](https://code.claude.com/docs/zh-CN/settings-reference#sandbox-ripgrep)172* 沙箱 `ripgrep` 二进制文件，[`sandbox.ripgrep`](https://code.claude.com/docs/zh-CN/settings-reference#sandbox-ripgrep)

173* `sandbox.filesystem.disabled` 和 `sandbox.network.strictAllowlist`173* `sandbox.filesystem.disabled` 和 `sandbox.network.strictAllowlist`

174* [`useAutoModeDuringPlan`](https://code.claude.com/docs/zh-CN/settings-reference#useautomodeduringplan)、[`syncClaudeAiSkills`](https://code.claude.com/docs/zh-CN/settings-reference#syncclaudeaiskills) 和 [`syncClaudeAiPlugins`](https://code.claude.com/docs/zh-CN/settings-reference#syncclaudeaiplugins)，其中任何管理员源的 `false` 都会关闭该行为。开发人员的用户或本地设置中的 `false` 也会关闭它；每个键只能拒绝174* [`useAutoModeDuringPlan`](https://code.claude.com/docs/zh-CN/settings-reference#useautomodeduringplan)、[`syncClaudeAiSkills`](https://code.claude.com/docs/zh-CN/settings-reference#syncclaudeaiskills) 和 [`syncClaudeAiPlugins`](https://code.claude.com/docs/zh-CN/settings-reference#syncclaudeaiplugins)，其中任何管理员源的 `false` 都会关闭该行为。每个键只能拒绝：

175 * 开发人员的用户或本地设置中的 `false` 也会关闭它

176 * 对于 `useAutoModeDuringPlan`，开发人员通过 [`--setting-sources`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 等选项排除的用户或本地文件中的 `false` 不计数。忽略被排除的文件需要 Claude Code v2.1.314 或更高版本

175* [`enableArtifact`](https://code.claude.com/docs/zh-CN/settings-reference#enableartifact)，其中任何管理员源的 `false` 都会关闭 [Artifact 工具](https://code.claude.com/docs/zh-CN/artifacts.md)。开发人员的用户、项目或本地设置中的 `false` 也会关闭它，没有源会将其打开；请参阅 [哪些较低级别的值仍然计数](https://code.claude.com/docs/zh-CN/settings.md#exceptions-to-managed-settings-precedence)。需要 Claude Code v2.1.242 或更高版本177* [`enableArtifact`](https://code.claude.com/docs/zh-CN/settings-reference#enableartifact)，其中任何管理员源的 `false` 都会关闭 [Artifact 工具](https://code.claude.com/docs/zh-CN/artifacts.md)。开发人员的用户、项目或本地设置中的 `false` 也会关闭它，没有源会将其打开；请参阅 [哪些较低级别的值仍然计数](https://code.claude.com/docs/zh-CN/settings.md#exceptions-to-managed-settings-precedence)。需要 Claude Code v2.1.242 或更高版本

176* [`maxEffortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#maxeffortlevel)，其中任何管理员源中的最低上限适用。如果开发人员在自己的设置或使用 `--settings` 中设置了较低的上限，Claude Code 会应用该上限；没有源可以提高上限。需要 Claude Code v2.1.267 或更高版本178* [`maxEffortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#maxeffortlevel)，其中任何管理员源中的最低上限适用。如果开发人员在自己的设置或使用 `--settings` 中设置了较低的上限，Claude Code 会应用该上限；没有源可以提高上限。需要 Claude Code v2.1.267 或更高版本

177* `attribution` 中的提交预告片选择退出，或在已弃用的 `includeCoAuthoredBy` 中，来自任何层级179* `attribution` 中的提交预告片选择退出，或在已弃用的 `includeCoAuthoredBy` 中，来自任何层级

6134. 您的设置：您为模型保存的级别或 [`effortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#effortlevel) 键，在 [`modelSettings`](https://code.claude.com/docs/zh-CN/settings-reference#modelsettings) 中说明它们之间和跨设置文件的优先级6134. 您的设置：您为模型保存的级别或 [`effortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#effortlevel) 键，在 [`modelSettings`](https://code.claude.com/docs/zh-CN/settings-reference#modelsettings) 中说明它们之间和跨设置文件的优先级

6145. 模型的默认 effort：在支持 effort 的每个模型上为 `high`，除了 Opus 5.5、Sonnet 5.5 和 Haiku 5.5 默认为 `medium`、Opus 4.7 默认为 `xhigh`。如果您的组织为其[组织默认模型](#organization-default-model)设置了默认 effort 级别，则当您运行该模型时，该级别即为默认值。6145. 模型的默认 effort：在支持 effort 的每个模型上为 `high`，除了 Opus 5.5、Sonnet 5.5 和 Haiku 5.5 默认为 `medium`、Opus 4.7 默认为 `xhigh`。如果您的组织为其[组织默认模型](#organization-default-model)设置了默认 effort 级别，则当您运行该模型时，该级别即为默认值。

615 615 

616自动模型回退后适用的级别，请参阅[回退后的 effort 级别](#effort-level-after-a-fallback)。616自动模型回退后适用的级别，请参阅[回退后的 effort 级别](#effort-level-after-a-fallback)。关于子代理和队友，请参阅[子代理和队友的 effort 级别](#effort-level-of-subagents-and-teammates)。

617 617 

618Opus 5.5 从 `medium` 开始，除非上面的源之一为其设置级别，您的用户设置文件中的顶级 `effortLevel` 不计入 Opus 5.5。该键是较旧的形式 `/effort` 在 Claude Code 按模型保存级别之前写入的：它继续在它之前应用的地方应用，在 Opus 5、Fable 5.1 和更早的模型上，而 Opus 5.5 和在它之后发布的模型从它们自己的默认开始，直到您使用 `/effort` 或 `/model` 选择器为它们选择级别。项目、本地或托管设置中的顶级 `effortLevel`，或使用 `--settings` 传递的，适用于每个模型。618Opus 5.5 从 `medium` 开始，除非上面的源之一为其设置级别，您的用户设置文件中的顶级 `effortLevel` 不计入 Opus 5.5。该键是较旧的形式 `/effort` 在 Claude Code 按模型保存级别之前写入的：它继续在它之前应用的地方应用，在 Opus 5、Fable 5.1 和更早的模型上，而 Opus 5.5 和在它之后发布的模型从它们自己的默认开始，直到您使用 `/effort` 或 `/model` 选择器为它们选择级别。项目、本地或托管设置中的顶级 `effortLevel`，或使用 `--settings` 传递的，适用于每个模型。

619 619 

700 700 

701[`maxEffortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#maxeffortlevel) 或[组织 effort 上限](#organization-effort-limits)仍然限制 skill 或子代理运行的级别。如果您在[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)中设置 `effortLevel`，Claude Code 在 [effort 解析顺序](#adjust-effort-level)的设置步骤处应用它，用户仍然可以使用 `/effort` 或 `--effort` 更改级别。要将用户保持在或低于某个级别，设置 [`maxEffortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#maxeffortlevel)。701[`maxEffortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#maxeffortlevel) 或[组织 effort 上限](#organization-effort-limits)仍然限制 skill 或子代理运行的级别。如果您在[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)中设置 `effortLevel`，Claude Code 在 [effort 解析顺序](#adjust-effort-level)的设置步骤处应用它，用户仍然可以使用 `/effort` 或 `--effort` 更改级别。要将用户保持在或低于某个级别，设置 [`maxEffortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#maxeffortlevel)。

702 702 

703#### 子代理和队友的 effort 级别

704 

705在主对话的模型上，没有自己 `effort` 的[子代理](https://code.claude.com/docs/zh-CN/sub-agents.md#choose-an-effort-level)或[队友](https://code.claude.com/docs/zh-CN/agent-teams.md#specify-teammates-and-models)以您在会话中选择或使用 `--effort` 设置的级别运行。在其他模型上，该级别不适用。要选择子代理的级别，请在其定义中设置 `effort`。

706 

703#### 检查您设置的 effort 级别707#### 检查您设置的 effort 级别

704 708 

705选择支持的模型时，effort 滑块会出现在 `/model` 中。会话标题中显示的级别（例如"with low effort"）来自您的 effort 设置，即使 Claude [仍在以旧级别工作](#when-a-new-effort-level-starts)。在启动时以及您更改级别时，页脚也会简要显示为您的会话设置的级别。709选择支持的模型时，effort 滑块会出现在 `/model` 中。会话标题中显示的级别（例如"with low effort"）来自您的 effort 设置，即使 Claude [仍在以旧级别工作](#when-a-new-effort-level-starts)。在启动时以及您更改级别时，页脚也会简要显示为您的会话设置的级别。

330 330 

331在交互式 CLI 会话中，详细测试版跟踪还需要您的组织被列入该功能的白名单。Agent SDK 和非交互式 `-p` 会话不需要白名单。331在交互式 CLI 会话中，详细测试版跟踪还需要您的组织被列入该功能的白名单。Agent SDK 和非交互式 `-p` 会话不需要白名单。

332 332 

333> [!WARNING]

334>

335> 请仅在调试时设置 `ENABLE_BETA_TRACING_DETAILED`，不要在生产环境中设置。详细测试版跟踪的导出量很大，并且其[内容属性](#new-context-gates)不属于稳定跨度 schema 的一部分。

336 

333| 属性 | 描述 | 门控 |337| 属性 | 描述 | 门控 |

334| - | - | - |338| - | - | - |

335| `hook_event` | 钩子事件类型，例如 `PreToolUse` | |339| `hook_event` | 钩子事件类型，例如 `PreToolUse` | |

131 131 

132Claude Code 在会话的调试日志中记录每个被忽略的密钥。132Claude Code 在会话的调试日志中记录每个被忽略的密钥。

133 133 

134在[Claude Desktop](https://code.claude.com/docs/zh-CN/desktop.md)会话中，应用管理提供商连接，例如[第三方提供商](https://code.claude.com/docs/zh-CN/third-party-integrations.md)上的代码选项卡和 Cowork 会话，Claude Code 仅从[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)和 `~/.claude/settings.json` 读取这些变量和代理变量 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY`：它忽略存储库自己的设置文件中的这些变量，因此已检出的存储库无法重定向凭证来自应用的会话的 TLS 或代理路径。在通过 claude.ai 登录的本地、SSH 或 WSL 代码选项卡会话中，应用不管理连接，Claude Code 从每个设置范围读取这些变量，就像任何终端会话一样；[云会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)无论您在何处启动它们，都遵循上述云会话规则。在 v2.1.217 之前，当应用管理连接时，Claude Code 忽略每个设置文件中的这些变量。134在由应用管理提供商连接的 [Claude Desktop](https://code.claude.com/docs/zh-CN/desktop.md) 会话中（例如[第三方提供商](https://code.claude.com/docs/zh-CN/third-party-integrations.md)上的 Code 选项卡以及 Cowork 会话），Claude Code 仅从[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)和 `~/.claude/settings.json` 读取这些变量（`CLAUDE_CODE_OAUTH_SCOPES` 除外）以及代理变量 `HTTP_PROXY`、`HTTPS_PROXY` 和 `NO_PROXY`。它会忽略仓库自身设置文件中的这些变量，因此已检出的仓库无法重定向凭据来自应用的会话的 TLS 或代理路径。在 v2.1.217 之前，当应用管理连接时，Claude Code 会忽略每个设置文件中的这些变量。

135 

136在通过 claude.ai 登录的本地、SSH 或 WSL Code 选项卡会话中，您可以在任何设置文件中设置这些变量和代理变量，`CLAUDE_CODE_OAUTH_SCOPES` 除外。Desktop 会在 Code 选项卡和 Cowork 会话中自行设置 `CLAUDE_CODE_OAUTH_SCOPES`，因此您无法设置它。

137 

138当会话的启动环境已设置某个变量时，Claude Code 会[忽略设置文件中的值](https://code.claude.com/docs/zh-CN/settings-reference.md#how-env-values-interact-with-your-shell)，并在[调试日志](https://code.claude.com/docs/zh-CN/debug-your-config.md)中注明该变量的名称。要在本地会话中使用您自己的代理或证书值，请[将其添加到已保存的本地环境](https://code.claude.com/docs/zh-CN/desktop.md#set-environment-variables-for-local-sessions)。[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)无论您在何处启动，都遵循上述云端会话规则。

135 139 

136## 验证你的配置140## 验证你的配置

137 141 

383* **服务器不审查该会话**：响应完成但没有审查结果，或服务器答复它不审查此会话。最常见的原因是 LLM 网关或代理丢弃了审查请求或结果，以及平台、区域或凭据尚不支持服务器端检查。Claude Code 会回退到其自身的分类器请求。一旦该回退在会话剩余时间内保持生效，在这些请求需要计费的账户上，它会显示[关于分类器请求费用的通知](https://code.claude.com/docs/zh-CN/auto-mode-classifier-billing.md)。383* **服务器不审查该会话**：响应完成但没有审查结果，或服务器答复它不审查此会话。最常见的原因是 LLM 网关或代理丢弃了审查请求或结果，以及平台、区域或凭据尚不支持服务器端检查。Claude Code 会回退到其自身的分类器请求。一旦该回退在会话剩余时间内保持生效，在这些请求需要计费的账户上，它会显示[关于分类器请求费用的通知](https://code.claude.com/docs/zh-CN/auto-mode-classifier-billing.md)。

384* **服务器未对某个操作给出裁决**：Claude Code 会拒绝该操作，而不是在未经审查的情况下运行它。在任何连接上，当响应在审查结果到达前结束，或结果以 Claude Code 无法读取的形式到达时，都会发生这种情况。截断响应或改写结果的 LLM 网关或代理可能导致上述任一情况。在直接连接到 Anthropic API 时，当服务器对该操作的检查失败（例如超时）时也会发生这种情况。[服务器未返回安全裁决](https://code.claude.com/docs/zh-CN/errors.md#the-server-returned-no-safety-verdict)介绍了拒绝消息、拒绝反复发生时的情况以及处理方法。384* **服务器未对某个操作给出裁决**：Claude Code 会拒绝该操作，而不是在未经审查的情况下运行它。在任何连接上，当响应在审查结果到达前结束，或结果以 Claude Code 无法读取的形式到达时，都会发生这种情况。截断响应或改写结果的 LLM 网关或代理可能导致上述任一情况。在直接连接到 Anthropic API 时，当服务器对该操作的检查失败（例如超时）时也会发生这种情况。[服务器未返回安全裁决](https://code.claude.com/docs/zh-CN/errors.md#the-server-returned-no-safety-verdict)介绍了拒绝消息、拒绝反复发生时的情况以及处理方法。

385 385 

386 如果 [hook](https://code.claude.com/docs/zh-CN/hooks.md#pretooluse-updatedinput-in-auto-mode) 或 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 在服务器审查之后更改了操作的输入，Claude Code 可能会在没有裁决的情况下拒绝该操作。在直接连接到 Anthropic API 的交互式终端和 VS Code 会话中，拒绝消息的文本包含 `a hook changed this call's input after auto mode reviewed it`。[其错误条目](https://code.claude.com/docs/zh-CN/errors.md#hook-changed-input-after-review)介绍了处理方法。

387 

386要跳过请求服务器审查并始终使用 Claude Code 自身的分类器请求，请设置 [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](https://code.claude.com/docs/zh-CN/env-vars)。在直接连接到 Anthropic API 时，该变量需要 Claude Code v2.1.281 或更高版本。在这种连接上将其设置为 `1`，会在尚未启用服务器审查的会话中启用它，除非您同时设置了 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`。如果您设置了 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` 且未设置 `CLAUDE_CODE_AUTO_MODE_SERVER`，Claude Code 也会停止请求服务器审查，[禁用预发布功能](https://code.claude.com/docs/zh-CN/llm-gateway-protocol.md#disable-pre-release-capabilities)中描述的情况除外。388要跳过请求服务器审查并始终使用 Claude Code 自身的分类器请求，请设置 [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](https://code.claude.com/docs/zh-CN/env-vars)。在直接连接到 Anthropic API 时，该变量需要 Claude Code v2.1.281 或更高版本。在这种连接上将其设置为 `1`，会在尚未启用服务器审查的会话中启用它，除非您同时设置了 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`。如果您设置了 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` 且未设置 `CLAUDE_CODE_AUTO_MODE_SERVER`，Claude Code 也会停止请求服务器审查，[禁用预发布功能](https://code.claude.com/docs/zh-CN/llm-gateway-protocol.md#disable-pre-release-capabilities)中描述的情况除外。

387 389 

388### 默认分类器模型390### 默认分类器模型

557* **操作被阻止**：Claude Code 会显示通知，并在 `/permissions` 的 **Recently blocked** 选项卡下列出该操作，您可以在那里[批准该操作，以便 Claude 重试](https://code.claude.com/docs/zh-CN/auto-mode-config.md#review-denials)。559* **操作被阻止**：Claude Code 会显示通知，并在 `/permissions` 的 **Recently blocked** 选项卡下列出该操作，您可以在那里[批准该操作，以便 Claude 重试](https://code.claude.com/docs/zh-CN/auto-mode-config.md#review-denials)。

558* **反复阻止**：如果分类器连续 3 次或累计 20 次阻止操作，自动模式会暂停，Claude Code 会恢复提示。批准被提示的操作后会恢复自动模式。有关阻止次数的计算方式，请参阅[反复阻止阈值](#repeated-block-thresholds)。560* **反复阻止**：如果分类器连续 3 次或累计 20 次阻止操作，自动模式会暂停，Claude Code 会恢复提示。批准被提示的操作后会恢复自动模式。有关阻止次数的计算方式，请参阅[反复阻止阈值](#repeated-block-thresholds)。

559* **分类器未给出裁决**：当独立于自动模式的安全检查拒绝了分类器自身的请求，或分类器的响应无法解析时，Claude Code 会阻止该操作，且不显示通知，也不会添加 **Recently blocked** 条目。有关每种情况显示的消息及处理方法，请参阅[自动模式无法确定操作的安全性](https://code.claude.com/docs/zh-CN/errors.md#auto-mode-cannot-determine-the-safety-of-an-action)。561* **分类器未给出裁决**：当独立于自动模式的安全检查拒绝了分类器自身的请求，或分类器的响应无法解析时，Claude Code 会阻止该操作，且不显示通知，也不会添加 **Recently blocked** 条目。有关每种情况显示的消息及处理方法，请参阅[自动模式无法确定操作的安全性](https://code.claude.com/docs/zh-CN/errors.md#auto-mode-cannot-determine-the-safety-of-an-action)。

560* **服务器未给出裁决**：在[服务器端分类器审查](#server-side-classifier-review)下，Claude Code 会拒绝服务器未给出裁决的操作，并在连续十个响应均无裁决后停止当前轮次。请参阅[服务器未返回安全裁决](https://code.claude.com/docs/zh-CN/errors.md#the-server-returned-no-safety-verdict)。562* **服务器未返回判定结果**：在[服务器端分类器审查](#server-side-classifier-review)下，如果服务器未对某项操作给出判定结果，Claude Code 会拒绝该操作；如果连续十次响应都没有判定结果，Claude Code 可能会停止当前轮次。请参阅[服务器未返回安全判定结果](https://code.claude.com/docs/zh-CN/errors.md#the-server-returned-no-safety-verdict)。

561* **检查期间切换模式**：如果您在分类器检查尚未完成时切换权限模式，Claude Code 会丢弃新模式本不会请求的裁决。此时会改为提示您批准，或者在 [`dontAsk` 模式](#allow-only-pre-approved-tools-with-dontask-mode)下自动拒绝该操作。563* **检查期间切换模式**：如果您在分类器检查尚未完成时切换权限模式，Claude Code 会丢弃新模式本不会请求的裁决。此时会改为提示您批准，或者在 [`dontAsk` 模式](#allow-only-pre-approved-tools-with-dontask-mode)下自动拒绝该操作。

562 564 

563#### 反复阻止阈值565#### 反复阻止阈值

199 199 

200消息告诉 Claude 再次发出记录的调用。如果也被拒绝，hook 每次都更改输入，因此关闭 mod 或 hook，或离开自动模式并自己批准调用。200消息告诉 Claude 再次发出记录的调用。如果也被拒绝，hook 每次都更改输入，因此关闭 mod 或 hook，或离开自动模式并自己批准调用。

201 201 

202> [!NOTE]

203>

204> 在[部分交互式终端会话和 VS Code 会话](https://code.claude.com/docs/zh-CN/hooks.md#pretooluse-updatedinput-in-auto-mode)中，同样的拒绝会给出原因 `a hook changed this call's input after auto mode reviewed it`。在这些会话中，重复的调用会携带 mod 的第一次更改，并且 `tool.call` hook 仍会在其上运行，但进一步的更改会被丢弃。除非 Claude 在回复中告诉您[自动模式无法检查该调用](https://code.claude.com/docs/zh-CN/errors.md#hook-changed-input-after-review)，否则无需更改您的 mod。

205 

202### 关于您的设置中的拒绝规则的消息206### 关于您的设置中的拒绝规则的消息

203 207 

204`tried to lift a deny rule in your settings` 和 `the deny rules in your settings could not be checked for this call, so it is refused` 都来自内置保护。208`tried to lift a deny rule in your settings` 和 `the deny rules in your settings could not be checked for this call, so it is refused` 都来自内置保护。

31>31>

32> 另有两项功能会在您的计算机上而非云端安排工作：[Desktop 定时任务](https://code.claude.com/docs/zh-CN/desktop-scheduled-tasks.md)和 [`/loop`](https://code.claude.com/docs/zh-CN/scheduled-tasks)。要在这三者之间进行选择，请参阅[比较调度选项](https://code.claude.com/docs/zh-CN/scheduled-tasks.md#compare-scheduling-options)。32> 另有两项功能会在您的计算机上而非云端安排工作：[Desktop 定时任务](https://code.claude.com/docs/zh-CN/desktop-scheduled-tasks.md)和 [`/loop`](https://code.claude.com/docs/zh-CN/scheduled-tasks)。要在这三者之间进行选择，请参阅[比较调度选项](https://code.claude.com/docs/zh-CN/scheduled-tasks.md#compare-scheduling-options)。

33 33 

34Team 和 Enterprise 的 Owner 可以通过 [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities) 中的 **Scheduled tasks (Was Routines)** 开关为所有成员关闭定时任务。关闭该开关后，现有定时任务将停止运行，成员也无法创建新的定时任务。34Team 和 Enterprise 的 Owner 可以通过 [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities) 中的 **Scheduled tasks (Was Routines)** 或 **Routines** 开关为所有成员关闭定时任务。关闭该开关后，现有定时任务将停止运行，成员也无法创建新的定时任务。

35 35 

36如果您的 Enterprise 组织通过[自定义角色](https://support.claude.com/en/articles/13930452)管理您的访问权限，您还需要一个包含定时任务权限的角色。Owner 可以在 [**Organization settings > Roles**](https://claude.ai/admin-settings/roles) 中角色的 **Remote sessions** 部分添加该权限。36如果您的 Enterprise 组织通过[自定义角色](https://support.claude.com/en/articles/13930452)管理您的访问权限，您还需要一个包含定时任务权限的角色。Owner 可以在 [**Organization settings > Roles**](https://claude.ai/admin-settings/roles) 中角色的 **Remote sessions** 部分添加该权限。

37 37 

485* **网址**：`claude.ai/code/routines`485* **网址**：`claude.ai/code/routines`

486* **CLI**：`/schedule` 的别名 `/routines`、该命令的描述，以及 Claude 在设置任务时的回复486* **CLI**：`/schedule` 的别名 `/routines`、该命令的描述，以及 Claude 在设置任务时的回复

487* **API**：`/fire` 端点路径、其 beta 标头、其响应中的 `type`、`<routine-fire-payload>` 标签，以及 [Trigger a routine through the API](https://platform.claude.com/docs/en/api/claude-code/routines-fire) 参考页面487* **API**：`/fire` 端点路径、其 beta 标头、其响应中的 `type`、`<routine-fire-payload>` 标签，以及 [Trigger a routine through the API](https://platform.claude.com/docs/en/api/claude-code/routines-fire) 参考页面

488* **组织设置**：**Scheduled tasks (Was Routines)** 开关488* **组织设置**：**Scheduled tasks (Was Routines)** 或 **Routines** 开关

489 489 

490## 故障排除490## 故障排除

491 491 

504 504 

505如果原因在于您的 CLI 登录方式或您处于云端会话中，您仍可以在 [claude.ai/code/routines](https://claude.ai/code/routines) 创建和管理定时任务。您需要在该处使用 Pro、Max、Ultra、Team 或 Enterprise 账户。如果您的组织关闭了定时任务或云端会话，或者您的角色中缺少相应权限，您也无法在 Web 端创建定时任务。505如果原因在于您的 CLI 登录方式或您处于云端会话中，您仍可以在 [claude.ai/code/routines](https://claude.ai/code/routines) 创建和管理定时任务。您需要在该处使用 Pro、Max、Ultra、Team 或 Enterprise 账户。如果您的组织关闭了定时任务或云端会话，或者您的角色中缺少相应权限，您也无法在 Web 端创建定时任务。

506 506 

507### "Routines are disabled by your organization's policy"507### 您的组织已关闭定时任务

508 508 

509您 Team 或 Enterprise 组织中的 Owner 可能已在 [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities) 关闭了 **Scheduled tasks (Was Routines)** 开关。在 Claude Code v2.1.227 或更高版本中，同一开关还会在 CLI 中隐藏 `/schedule`。这是一项服务器端的组织设置，因此无法通过您的本地配置覆盖。请联系 Owner 为您的组织重新启用定时任务。509您的组织已关闭云端定时任务，且您无法通过本地配置更改这一点。请询问您 Team 或 Enterprise 组织的 Owner 能否在 [**Organization settings > Capabilities > Remote sessions**](https://claude.ai/admin-settings/capabilities) 打开 **Scheduled tasks (Was Routines)** 或 **Routines** 开关。

510 510 

511### "The last run" 警告511### "The last run" 警告

512 512 

1074* **文件系统权限提升**：过于宽泛的文件系统写入权限可能导致权限提升攻击。允许写入包含 `$PATH` 中的可执行文件、系统配置目录或用户 shell 配置文件（例如 `.bashrc` 或 `.zshrc`）的目录可能导致当其他用户或系统进程访问这些文件时在不同的安全上下文中执行代码。1074* **文件系统权限提升**：过于宽泛的文件系统写入权限可能导致权限提升攻击。允许写入包含 `$PATH` 中的可执行文件、系统配置目录或用户 shell 配置文件（例如 `.bashrc` 或 `.zshrc`）的目录可能导致当其他用户或系统进程访问这些文件时在不同的安全上下文中执行代码。

1075* **Linux 沙箱强度**：Linux 实现提供强大的文件系统和网络隔离，但包括一个 `enableWeakerNestedSandbox` 模式，使其能够在 Docker 环境中工作而无需特权命名空间。此选项大大削弱了安全性，应仅在其他隔离被强制执行时使用。1075* **Linux 沙箱强度**：Linux 实现提供强大的文件系统和网络隔离，但包括一个 `enableWeakerNestedSandbox` 模式，使其能够在 Docker 环境中工作而无需特权命名空间。此选项大大削弱了安全性，应仅在其他隔离被强制执行时使用。

1076* **macOS 上的 Apple Events**：macOS 沙箱默认阻止 Apple Events。`allowAppleEvents` 设置解除此限制，以便 `open` 和 `osascript` 等工具可以工作，但它移除了代码执行隔离：沙箱化命令可以在没有用户提示的情况下启动其他未沙箱化的应用程序，并可以向运行的应用程序发送 AppleScript 命令，受限于每个应用程序的 macOS 自动化同意提示 (TCC)。它仅从用户、托管或 CLI 设置中被遵守。项目设置无法启用它。1076* **macOS 上的 Apple Events**：macOS 沙箱默认阻止 Apple Events。`allowAppleEvents` 设置解除此限制，以便 `open` 和 `osascript` 等工具可以工作，但它移除了代码执行隔离：沙箱化命令可以在没有用户提示的情况下启动其他未沙箱化的应用程序，并可以向运行的应用程序发送 AppleScript 命令，受限于每个应用程序的 macOS 自动化同意提示 (TCC)。它仅从用户、托管或 CLI 设置中被遵守。项目设置无法启用它。

1077* **macOS 上的 Mach 和 XPC 服务**：沙箱化命令可以访问沙箱外您在 [`network.allowMachLookup`](https://code.claude.com/docs/zh-CN/settings-reference#sandbox-network-allowmachlookup) 中列出的每个服务，并且沙箱不会限制这些服务为这些命令执行的操作。

1077* **Linux 和 WSL2 上的用户命名空间**：默认情况下，沙箱化命令无法创建用户命名空间。如果您将 [`allowNestedUserNamespaces`](https://code.claude.com/docs/zh-CN/settings-reference#sandbox-allownestedusernamespaces) 设置为 `true`，就会关闭一道安全边界：来自沙箱化命令的代码最终可能在沙箱外运行。在启用此设置之前，请阅读 [Linux 上 Chromium 或 rootless Podman 在沙箱内运行失败](#chromium-or-rootless-podman-fails-inside-the-sandbox-on-linux)中的警告。1078* **Linux 和 WSL2 上的用户命名空间**：默认情况下，沙箱化命令无法创建用户命名空间。如果您将 [`allowNestedUserNamespaces`](https://code.claude.com/docs/zh-CN/settings-reference#sandbox-allownestedusernamespaces) 设置为 `true`，就会关闭一道安全边界：来自沙箱化命令的代码最终可能在沙箱外运行。在启用此设置之前，请阅读 [Linux 上 Chromium 或 rootless Podman 在沙箱内运行失败](#chromium-or-rootless-podman-fails-inside-the-sandbox-on-linux)中的警告。

1078 1079 

1079### 范围1080### 范围

16 16 

17## 包装脚本17## 包装脚本

18 18 

19当每个会话需要运行器无法自行完成的设置时，使用包装脚本：为会话创建者配置作用域的短期凭据、导出特定于环境的密钥、准备语言工具链或围绕子进程应用资源限制。运行器每个会话启动一次您的包装脚本，而不是 Claude Code 二进制文件。通过 `exec` 进入 `$CLAUDE_RUNNER_CLAUDE_BIN`（运行器自己的二进制文件）来结束包装脚本，以便信号和退出码正确传播。19当每个会话需要运行器无法自行完成的设置时，使用包装脚本：

20 

21* 配置作用域限定为会话创建者的短期凭据

22* 导出特定于环境的密钥

23* 准备语言工具链

24* 围绕子进程应用资源限制

25 

26运行器每次启动会话时（包括会话恢复或重新排队时），都会启动您的包装脚本来代替 Claude Code 二进制文件。通过 `exec` 进入 `$CLAUDE_RUNNER_CLAUDE_BIN`（运行器自己的二进制文件）来结束包装脚本，以便信号和退出码正确传播。

20 27 

21启动运行器时，使用 `--exec-path` 或 `SELF_HOSTED_RUNNER_EXEC_PATH` 指向包装脚本，并按照[快速入门](https://code.claude.com/docs/zh-CN/self-hosted-environments-quickstart.md#set-up-manually)中的说明替换 `<writable-dir>`：28启动运行器时，使用 `--exec-path` 或 `SELF_HOSTED_RUNNER_EXEC_PATH` 指向包装脚本，并按照[快速入门](https://code.claude.com/docs/zh-CN/self-hosted-environments-quickstart.md#set-up-manually)中的说明替换 `<writable-dir>`：

22 29 

139 146 

140### checkout147### checkout

141 148 

142每个仓库运行一次，代替运行器的内置克隆和获取。使用此 hook 从您通过 HTTPS 或 SSH 访问的读通镜像克隆、从存档为工作树设置种子，或应用按会话的 git 身份验证。运行器设置以下变量，并且可能设置表中未列出的其他 `CLAUDE_RUNNER_` 变量：149每次运行器启动会话时（包括会话恢复或重新排队时），都会针对每个仓库运行，代替运行器的内置克隆和获取。使用此 hook 从您通过 HTTPS 或 SSH 访问的读通镜像克隆、从存档为工作树设置种子，或应用按会话的 git 身份验证。

150 

151运行器设置以下变量，并且可能设置表中未列出的其他 `CLAUDE_RUNNER_` 变量：

143 152 

144| 变量 | 描述 |153| 变量 | 描述 |

145| :- | :- |154| :- | :- |

179 188 

180### post-session189### post-session

181 190 

182每个会话运行一次，在 Claude Code 子进程退出后和运行器拆卸工作区之前。此钩子是保存未提交工作的唯一机会：在 `--capacity` 高于 1 时，运行器在钩子返回后立即删除按会话工作树，在 `--capacity 1` 时重用的 [canonical clone](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#reuse-a-pre-warmed-checkout) 在下一个会话启动时硬重置，因此未提交的跟踪更改在两条路径上都不会存活。典型用途是推送未提交更改的快照分支、存档日志或向您自己的系统发出会话结束事件。191在 Claude Code 子进程退出后、运行器拆卸工作区之前运行。此 hook 是保存未提交工作的唯一机会，因为未提交的跟踪更改在以下两条路径上都不会保留：

192 

193* **在 `--capacity` 高于 1 时**：运行器在 hook 返回后立即删除按会话的 worktree

194* **在 `--capacity 1` 时**：重用的 [canonical clone](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#reuse-a-pre-warmed-checkout) 会在下一个会话启动时被硬重置

195 

196典型用途是推送未提交更改的快照分支、存档日志或向您自己的系统发出会话结束事件。

183 197 

184钩子在每个会话结束时触发，其中生成了子进程，无论原因如何；下面的 `CLAUDE_RUNNER_EXIT_REASON` 值枚举了这些情况。当运行器突然终止时（例如 VM 抢占或断电）它无法触发；如果您需要针对突然终止的保证，请改为使用 Claude Code `PostToolUse` 钩子从会话内定期快照。运行器设置：198钩子在每个会话结束时触发，其中生成了子进程，无论原因如何；下面的 `CLAUDE_RUNNER_EXIT_REASON` 值枚举了这些情况。当运行器突然终止时（例如 VM 抢占或断电）它无法触发；如果您需要针对突然终止的保证，请改为使用 Claude Code `PostToolUse` 钩子从会话内定期快照。运行器设置：

185 199 

275 289 

276### command290### command

277 291 

278每个会话在检出后运行一次，代替内置子进程生成。钩子接收与 [wrapper script](#wrapper-scripts) 相同的环境，应该以相同的方式 `exec` 进入 `"$CLAUDE_RUNNER_CLAUDE_BIN"`。使用 `command` 钩子将所有自定义保留在一个钩子目录中；当包装脚本在其他地方时使用 `--exec-path`。如果也设置了 `--exec-path`，标志优先，`command` 钩子被忽略。292每次会话启动或恢复时，在检出之后运行，代替内置子进程生成。钩子接收与 [wrapper script](#wrapper-scripts) 相同的环境，应该以相同的方式 `exec` 进入 `"$CLAUDE_RUNNER_CLAUDE_BIN"`。使用 `command` 钩子将所有自定义保留在一个钩子目录中；当包装脚本在其他地方时使用 `--exec-path`。如果也设置了 `--exec-path`，标志优先，`command` 钩子被忽略。

279 293 

280始终 `exec` 运行器自己的二进制文件，而不是 PATH 解析的 `claude`；否则您会破坏 [version pinning](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#pin-the-version)。294始终 `exec` 运行器自己的二进制文件，而不是 PATH 解析的 `claude`；否则您会破坏 [version pinning](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#pin-the-version)。

281 295 

523 537 

524* **元数据端点**：如果您完全禁止会话访问[云元数据端点](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#harden-your-deployment)，则由该端点提供的凭据（例如实例配置文件）也无法到达 Claude Code。基于文件的 Web 身份（例如 Amazon EKS 上的 IAM Roles for Service Accounts (IRSA) 或 Workload Identity Federation 凭据文件）不依赖于该端点。538* **元数据端点**：如果您完全禁止会话访问[云元数据端点](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#harden-your-deployment)，则由该端点提供的凭据（例如实例配置文件）也无法到达 Claude Code。基于文件的 Web 身份（例如 Amazon EKS 上的 IAM Roles for Service Accounts (IRSA) 或 Workload Identity Federation 凭据文件）不依赖于该端点。

525* **续期**：会话的持续时间可能超过凭据的有效期，因此请使用能够自动续期的方法，例如基于文件的 Web 身份539* **续期**：会话的持续时间可能超过凭据的有效期，因此请使用能够自动续期的方法，例如基于文件的 Web 身份

526* **包装脚本**：runner 每个会话只启动一次您的[包装脚本](#provision-credentials-scoped-to-the-session-creator)，因此它导出的凭据不会续期。Claude Code 会从其环境中读取 AWS 凭据，因此如果您的包装脚本已为其他工作导出了 AWS 凭据，Claude Code 可能会使用这些凭据对模型请求进行签名。540* **包装脚本**：您的[包装脚本](#provision-credentials-scoped-to-the-session-creator)导出的凭据值在 Claude Code 运行期间不会续期，因此对于长时间运行的会话，请使用能够自动续期的方法。Claude Code 会从其环境中读取 AWS 凭据，因此如果您的包装脚本已为其他工作导出了 AWS 凭据，Claude Code 可能会使用这些凭据对模型请求进行签名。

527 541 

528**3. 在 runner 的环境中设置一个提供商的变量**542**3. 在 runner 的环境中设置一个提供商的变量**

529 543 

827 827 

828### 某些会话不计为空闲828### 某些会话不计为空闲

829 829 

830持有永不完成的后台任务的会话不计为空闲，所以 `--release-idle-session-min` 不会释放该会话的槽。等待从运行中工具调用内请求的批准的会话也不计为空闲。始终将 `--kill-session-after-min` 与其一起设置作为硬后挡，以便没有会话可以无限期地持有槽。830持有持续运行的后台任务的会话不计为空闲，所以 `--release-idle-session-min` 不会释放该会话的槽。等待从运行中工具调用内请求的批准的会话也不计为空闲。请同时设置 `--kill-session-after-min` 作为硬后挡。

831 831 

832`--kill-session-after-min` 是失控会话的后挡。在 v2.1.260 或更高版本的运行器上，达到限制的会话不会立即终止。运行器给它一个宽限窗口，默认 15 分钟，您可以使用 [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#environment-variable-only-settings) 更改：832`--kill-session-after-min` 是失控会话的后挡。在 v2.1.260 或更高版本的运行器上，达到限制的会话不会立即终止。运行器给它一个宽限窗口，默认 15 分钟，您可以使用 [`SELF_HOSTED_RUNNER_MAX_LIFETIME_GRACE_MS`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#environment-variable-only-settings) 更改：

833 833 

153}153}

154```154```

155 155 

156在自定义探针中使用 `last_poll_age_ms` 作为活跃信号；无限增长的值表示轮询循环卡住。`last_poll_at` 和 `last_poll_age_ms` 都是 `null`，直到第一次轮询完成。156基于 `last_poll_age_ms` 设置警报，但不要在存活探针中使用它；存活探针应继续依据 HTTP 状态代码。该值是自上次成功轮询以来经过的时间，因此当运行器无法连接到 Anthropic 时它也会上升。在第一次轮询成功之前，`last_poll_at` 和 `last_poll_age_ms` 都是 `null`。要捕获从一开始就失败的轮询，还应针对 `claude_code_self_hosted_runner_poll_errors_total` 设置警报，该指标列在 [Prometheus 指标](#prometheus-metrics)下。

157 157 

158编排器自己的 `/healthz`（位于其健康端口上）始终返回 `200`。正文携带报告最近一次轮询是否成功的 `connected` 字段，加上 `queue_counts` 中的每个状态生成队列计数。要了解 `connected` 为何是 `false`，请读取顶层 `last_error` 字段，每次成功轮询都会将其重置为 `null`。使用 `connected` 而不是状态代码来控制就绪和警报。158编排器自己的 `/healthz`（位于其健康端口上）始终返回 `200`。正文携带报告最近一次轮询是否成功的 `connected` 字段，加上 `queue_counts` 中的每个状态生成队列计数。要了解 `connected` 为何是 `false`，请读取顶层 `last_error` 字段，每次成功轮询都会将其重置为 `null`。使用 `connected` 而不是状态代码来控制就绪和警报。

159 159 

313| [`autoMode.classifyAllShell`](https://code.claude.com/docs/zh-CN/settings-reference#automode-classifyallshell) | `~/.claude/settings.json` 或 `--settings` 中的 `true` | 即使托管来源设置为 `false` 也会采用 |313| [`autoMode.classifyAllShell`](https://code.claude.com/docs/zh-CN/settings-reference#automode-classifyallshell) | `~/.claude/settings.json` 或 `--settings` 中的 `true` | 即使托管来源设置为 `false` 也会采用 |

314| [`remoteControlAtStartup`](https://code.claude.com/docs/zh-CN/settings-reference#remotecontrolatstartup) | `.claude/settings.json` 或 `.claude/settings.local.json` 中的 `false` | 即使托管来源设置为 `true` 也会采用；项目或本地设置中的 `true` 会被忽略 |314| [`remoteControlAtStartup`](https://code.claude.com/docs/zh-CN/settings-reference#remotecontrolatstartup) | `.claude/settings.json` 或 `.claude/settings.local.json` 中的 `false` | 即使托管来源设置为 `true` 也会采用；项目或本地设置中的 `true` 会被忽略 |

315| [`crossSessionInbound`](https://code.claude.com/docs/zh-CN/settings-reference#crosssessioninbound) | `.claude/settings.json` 或 `.claude/settings.local.json` 中更严格的值，严格程度依次为 `accept` \< `hold` \< `refuse` | 优先于托管、`--settings` 和用户设置中的值；项目或本地设置中不更严格的值会被忽略 |315| [`crossSessionInbound`](https://code.claude.com/docs/zh-CN/settings-reference#crosssessioninbound) | `.claude/settings.json` 或 `.claude/settings.local.json` 中更严格的值，严格程度依次为 `accept` \< `hold` \< `refuse` | 优先于托管、`--settings` 和用户设置中的值；项目或本地设置中不更严格的值会被忽略 |

316| [`useAutoModeDuringPlan`](https://code.claude.com/docs/zh-CN/settings-reference#useautomodeduringplan) | 任何托管来源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 中的 `false` | 即使最终采用的托管来源设置为 `true` 也会采用；`.claude/settings.json` 中的 `false` 会被忽略 |316| [`useAutoModeDuringPlan`](https://code.claude.com/docs/zh-CN/settings-reference#useautomodeduringplan) | 任何托管来源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 中的 `false` | 即使最终采用的托管来源设置为 `true` 也会采用；`.claude/settings.json` 中的 `false` 会被忽略。对于启动时省略的文件，请参阅[该键的条目](https://code.claude.com/docs/zh-CN/settings-reference.md#useautomodeduringplan) |

317| [`syncClaudeAiSkills`](https://code.claude.com/docs/zh-CN/settings-reference#syncclaudeaiskills) | 任何托管来源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 中的 `false` | 即使最终采用的托管来源设置为 `true` 也会采用；`.claude/settings.json` 中的 `false` 会被忽略 |317| [`syncClaudeAiSkills`](https://code.claude.com/docs/zh-CN/settings-reference#syncclaudeaiskills) | 任何托管来源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 中的 `false` | 即使最终采用的托管来源设置为 `true` 也会采用；`.claude/settings.json` 中的 `false` 会被忽略 |

318| [`syncClaudeAiPlugins`](https://code.claude.com/docs/zh-CN/settings-reference#syncclaudeaiplugins) | 任何托管来源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 中的 `false` | 即使最终采用的托管来源设置为 `true` 也会采用；`.claude/settings.json` 中的 `false` 会被忽略 |318| [`syncClaudeAiPlugins`](https://code.claude.com/docs/zh-CN/settings-reference#syncclaudeaiplugins) | 任何托管来源、`--settings`、`~/.claude/settings.json` 或 `.claude/settings.local.json` 中的 `false` | 即使最终采用的托管来源设置为 `true` 也会采用；`.claude/settings.json` 中的 `false` 会被忽略 |

319| [`maxEffortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#maxeffortlevel) | 任何作用域（包括 `--settings`）中更低的上限 | 即使 Claude Code 应用的托管设置设置了更高的上限也会采用；以最低的上限为准。需要 Claude Code v2.1.267 或更高版本 |319| [`maxEffortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#maxeffortlevel) | 任何作用域（包括 `--settings`）中更低的上限 | 即使 Claude Code 应用的托管设置设置了更高的上限也会采用；以最低的上限为准。需要 Claude Code v2.1.267 或更高版本 |

925选择 Claude Code 是否在计划模式下使用自动模式分类器审查 shell 命令。在默认值 `true` 下，当自动模式可用时，分类器会在规划期间审查每条命令，您不会看到提示，[关键路径删除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)除外。设置为 `false` 后，对于内置只读命令集之外的每条命令，您都会收到权限提示。在 `/config` 中显示为 **Use auto mode during plan**。925选择 Claude Code 是否在计划模式下使用自动模式分类器审查 shell 命令。在默认值 `true` 下，当自动模式可用时，分类器会在规划期间审查每条命令，您不会看到提示，[关键路径删除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)除外。设置为 `false` 后，对于内置只读命令集之外的每条命令，您都会收到权限提示。在 `/config` 中显示为 **Use auto mode during plan**。

926 926 

927* **作用域**：[`User, local, or managed`](#scopes)。仓库无法替您关闭它。927* **作用域**：[`User, local, or managed`](#scopes)。仓库无法替您关闭它。

928 * 这些文件中任何一个或 `--settings` 中的 `false` 都会将其关闭，除非您使用 [`--setting-sources`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 等选项排除了该用户或本地文件。忽略被排除的文件需要 Claude Code v2.1.314 或更高版本

928* **类型**：Boolean929* **类型**：Boolean

929 * `true`：与未设置相同；当自动模式可用时，分类器会在规划期间审查每条 shell 命令，而不是向您发出提示，[关键路径删除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths)除外。这些文件中任何一个设置为 `false` 仍会将其关闭930 * `true`：与未设置相同；当自动模式可用时，分类器会在规划期间审查 shell 命令

930 * `false`：对于内置只读命令集之外的每条命令，您都会收到权限提示931 * `false`：对于内置只读命令集之外的每条命令，您都会收到权限提示

931* **默认值**：`true`932* **默认值**：`true`

932 933 

2073 2074 

2074### `sandbox.network.allowMachLookup`2075### `sandbox.network.allowMachLookup`

2075 2076 

2076列出 macOS 沙箱可以查找的其他 XPC 和 Mach 服务名称。通过 XPC 通信的工具（如 iOS Simulator 或 Playwright）需要在此处列出其服务。2077列出 macOS 沙箱可以查找的额外 XPC 和 Mach 服务名称。通过 XPC 通信的工具（例如 iOS Simulator 或 Playwright）需要在此处列出其服务。沙箱化命令可以访问沙箱外您列出的每个服务，而沙箱[不会限制这些服务为这些命令所做的事情](https://code.claude.com/docs/zh-CN/sandboxing.md#security-limitations)。

2077 2078 

2078* **作用域**：[`Any file`](#scopes)，[对项目设置和本地设置有限制](https://code.claude.com/docs/zh-CN/sandboxing.md#repository-settings-under-an-admin-required-sandbox)2079* **作用域**：[`Any file`](#scopes)，[对项目设置和本地设置有限制](https://code.claude.com/docs/zh-CN/sandboxing.md#repository-settings-under-an-admin-required-sandbox)

2079* **类型**：字符串数组，每项是一个服务名称；单个末尾 `*` 匹配前缀，单独的 `"*"` 匹配所有服务2080* **类型**：字符串数组，每项是一个服务名称；单个末尾 `*` 匹配前缀，单独的 `"*"` 匹配所有服务

2422 2423 

2423 在项目设置和本地设置中忽略此组变量需要 Claude Code v2.1.282 或更高版本。2424 在项目设置和本地设置中忽略此组变量需要 Claude Code v2.1.282 或更高版本。

2424 * 改变 Claude Code 启动或同步方式的变量，例如 `CLAUDE_CODE_PROCESS_WRAPPER`、`CLAUDE_CODE_SYNC_SKILLS`、`CLAUDE_CODE_SYNC_PLUGINS`、`CLAUDE_CODE_PLUGIN_CACHE_DIR` 和 `CLAUDE_CODE_PLUGIN_SEED_DIR`。2425 * 改变 Claude Code 启动或同步方式的变量，例如 `CLAUDE_CODE_PROCESS_WRAPPER`、`CLAUDE_CODE_SYNC_SKILLS`、`CLAUDE_CODE_SYNC_PLUGINS`、`CLAUDE_CODE_PLUGIN_CACHE_DIR` 和 `CLAUDE_CODE_PLUGIN_SEED_DIR`。

2426 * 设置您的 claude.ai 登录信息的变量，例如 [`CLAUDE_CODE_OAUTH_TOKEN`、`CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 和 `CLAUDE_CODE_OAUTH_SCOPES`](https://code.claude.com/docs/zh-CN/env-vars#variables)。

2425 * [屏幕阅读器模式](https://code.claude.com/docs/zh-CN/accessibility.md)变量 `CLAUDE_AX_SCREEN_READER`，以及其他名称以 `CLAUDE_AX_` 开头的变量，例如 [`CLAUDE_AX_STARTUP_QUIET_MS`](https://code.claude.com/docs/zh-CN/env-vars#variables)。2427 * [屏幕阅读器模式](https://code.claude.com/docs/zh-CN/accessibility.md)变量 `CLAUDE_AX_SCREEN_READER`，以及其他名称以 `CLAUDE_AX_` 开头的变量，例如 [`CLAUDE_AX_STARTUP_QUIET_MS`](https://code.claude.com/docs/zh-CN/env-vars#variables)。

2426 * [`CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS`](https://code.claude.com/docs/zh-CN/env-vars#variables)，用于设置未响应对话框的计时器。2428 * [`CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS`](https://code.claude.com/docs/zh-CN/env-vars#variables)，用于设置未响应对话框的计时器。

2427 * [`CLAUDE_CODE_DISABLE_ATTACHMENTS`](https://code.claude.com/docs/zh-CN/env-vars#variables)，用于关闭附件处理。2429 * [`CLAUDE_CODE_DISABLE_ATTACHMENTS`](https://code.claude.com/docs/zh-CN/env-vars#variables)，用于关闭附件处理。

40>40>

41> **macOS、Linux、WSL：**41> **macOS、Linux、WSL：**

42>42>

43> ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}43> ```bash theme={null}

44> curl -fsSL https://claude.ai/install.sh | bash44> curl -fsSL https://claude.ai/install.sh | bash

45> ```45> ```

46>46>

48>48>

49> **Windows PowerShell：**49> **Windows PowerShell：**

50>50>

51> ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}51> ```powershell theme={null}

52> irm https://claude.ai/install.ps1 | iex52> irm https://claude.ai/install.ps1 | iex

53> ```53> ```

54>54>

55> **Windows CMD：**55> **Windows CMD：**

56>56>

57> ```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}57> ```batch theme={null}

58> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd58> curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

59> ```59> ```

60>60>

72 72 

73> [tab] Homebrew73> [tab] Homebrew

74>74>

75> ```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}75> ```bash theme={null}

76> brew install --cask claude-code76> brew install --cask claude-code

77> ```77> ```

78>78>

84 84 

85> [tab] WinGet85> [tab] WinGet

86>86>

87> ```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}87> ```powershell theme={null}

88> winget install Anthropic.ClaudeCode88> winget install Anthropic.ClaudeCode

89> ```89> ```

90>90>

416 416 

417当您要求 Claude 以特定 effort 级别运行非分叉子代理时，它还可以为该次调用传入 `effort` 参数。该参数会覆盖 `effort` 字段，并在子代理被[恢复](#resume-subagents)时保持有效。[`CLAUDE_CODE_EFFORT_LEVEL`](https://code.claude.com/docs/zh-CN/env-vars#variables) 环境变量优先于这两者。单次调用参数需要 Claude Code v2.1.292 或更高版本。417当您要求 Claude 以特定 effort 级别运行非分叉子代理时，它还可以为该次调用传入 `effort` 参数。该参数会覆盖 `effort` 字段，并在子代理被[恢复](#resume-subagents)时保持有效。[`CLAUDE_CODE_EFFORT_LEVEL`](https://code.claude.com/docs/zh-CN/env-vars#variables) 环境变量优先于这两者。单次调用参数需要 Claude Code v2.1.292 或更高版本。

418 418 

419#### 当子代理没有 `effort` 字段或参数时

420 

421在主对话的模型上，子代理以您在会话中选择的级别运行，例如通过 `/effort` 选择或通过 `--effort` 设置的级别。在其他模型上，[该级别不适用](https://code.claude.com/docs/zh-CN/model-config.md#effort-level-of-subagents-and-teammates)。若要选择其级别，请设置 `effort` 字段。

422 

419### 控制子代理的能力423### 控制子代理的能力

420 424 

421您可以通过工具访问、权限模式和条件规则来控制子代理能做什么。425您可以通过工具访问、权限模式和条件规则来控制子代理能做什么。

69 69 

70通过此连接，会话可以克隆任何公共存储库，但只有在 Claude GitHub App 安装在私有存储库上时，才能在私有存储库中工作。[安装 Claude GitHub App](https://github.com/apps/claude/installations/new) 到您想要使用其私有存储库的每个 GitHub 账户或组织。在 GitHub 组织上，组织所有者可能需要批准安装。安装应用还会启用[Auto-fix](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md#auto-fix-pull-requests)，这让 Claude 能够响应这些存储库中拉取请求的 CI 失败和审查评论。70通过此连接，会话可以克隆任何公共存储库，但只有在 Claude GitHub App 安装在私有存储库上时，才能在私有存储库中工作。[安装 Claude GitHub App](https://github.com/apps/claude/installations/new) 到您想要使用其私有存储库的每个 GitHub 账户或组织。在 GitHub 组织上，组织所有者可能需要批准安装。安装应用还会启用[Auto-fix](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md#auto-fix-pull-requests)，这让 Claude 能够响应这些存储库中拉取请求的 CI 失败和审查评论。

71 71 

72连接时，如果您拥有的 GitHub 账户安装了 Claude GitHub App，Claude 还会将这些账户关联到您的 Claude 组织。在 Team 和 Enterprise 计划上，管理员可以在[已连接的 GitHub 账户列表](https://code.claude.com/docs/zh-CN/admin-setup.md#connected-github-accounts)中看到这些账户。72连接时，如果您拥有的 GitHub 账户安装了 Claude GitHub App，Claude 还会将这些账户关联到您的 Claude 组织。在 Team 和 Enterprise 计划上，您的 Claude 组织的所有者可以在[已连接的 GitHub 账户列表](https://code.claude.com/docs/zh-CN/admin-setup.md#connected-github-accounts)中看到这些账户。

73 73 

74如果入门流程在此时提示您安装 Claude GitHub App，而您想稍后再做，请单击**Skip**。74如果入门流程在此时提示您安装 Claude GitHub App，而您想稍后再做，请单击**Skip**。

75 75