Documentation — Spybara

advisor.md +4 −3

Details

98| Opus 4.7 或 Opus 4.8 | Fable、Opus 4.7 或更高版本、Sonnet 5.5 |98| Opus 4.7 或 Opus 4.8 | Fable、Opus 4.7 或更高版本、Sonnet 5.5 |

99| Sonnet 5.5 | Fable、Opus 5 或更高版本、Sonnet 5.5 |99| Sonnet 5.5 | Fable、Opus 5 或更高版本、Sonnet 5.5 |

100| Opus 5 或 Opus 5.5 | Fable、Opus 5 或更高版本 |100| Opus 5 或 Opus 5.5 | Fable、Opus 5 或更高版本 |

101| Fable 5 | Fable 5.1 或 Fable 5 |101| Fable 5 | Fable 5.2、Fable 5.1 或 Fable 5 |

102| Fable 5.1 | Fable 5.1 |102| Fable 5.1 | Fable 5.2 或 Fable 5.1 |

103| Fable 5.2 | Fable 5.2 |

103 104

104Fable 5.1 需要 Claude Code v2.1.257 或更高版本。Fable 模型需要 [Fable 访问权限](https://code.claude.com/docs/zh-CN/model-config.md#work-with-fable)。将 Sonnet 5.5 作为 Opus 4.7 或 Opus 4.8 主模型的顾问需要 Claude Code v2.1.287 或更高版本。将 Haiku 5.5 作为主模型或顾问需要 Claude Code v2.1.293 或更高版本。105Fable 5.2 需要 Claude Code v2.1.321 或更高版本，Fable 5.1 需要 v2.1.257 或更高版本。Fable 模型需要 [Fable 访问权限](https://code.claude.com/docs/zh-CN/model-config.md#work-with-fable)。将 Sonnet 5.5 作为 Opus 4.7 或 Opus 4.8 主模型的顾问需要 Claude Code v2.1.287 或更高版本。将 Haiku 5.5 作为主模型或顾问需要 Claude Code v2.1.293 或更高版本。

105 106

106将顾问设置为 `fable`、`opus` 或 `sonnet`。这些别名解析为 Claude Code 为每个模型系列[内置的默认版本](https://code.claude.com/docs/zh-CN/model-config.md#model-aliases)，该版本随新的 Claude Code 版本而推进。您也可以传递完整的模型 ID，例如 `claude-opus-5-5` 或 `claude-haiku-5-5`。Haiku 4.5 可以调用顾问，但不能充当顾问。107将顾问设置为 `fable`、`opus` 或 `sonnet`。这些别名解析为 Claude Code 为每个模型系列[内置的默认版本](https://code.claude.com/docs/zh-CN/model-config.md#model-aliases)，该版本随新的 Claude Code 版本而推进。您也可以传递完整的模型 ID，例如 `claude-opus-5-5` 或 `claude-haiku-5-5`。Haiku 4.5 可以调用顾问，但不能充当顾问。

107 108

agent-sdk/custom-tools.md +17 −11

Details

56 56

57### 天气工具示例57### 天气工具示例

58 58

59此示例定义了一个 `get_temperature` 工具并将其包装在 MCP 服务器中，但没有将服务器传递给 `query`。要运行该工具，请参阅下面的[调用自定义工具](#call-a-custom-tool)。59此示例定义了一个 `get_temperature` 工具并将其包装在 MCP 服务器中，但没有将服务器传递给 `query`。要运行该工具，请参阅[调用自定义工具](#call-a-custom-tool)。

60 60

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

62from typing import Annotated, Any62from typing import Annotated, Any

148* **TypeScript**：向 Zod 字段添加 `.optional()`。148* **TypeScript**：向 Zod 字段添加 `.optional()`。

149* **Python**：字典 schema 要求每个键都必须提供。请使用 JSON Schema 形式，将该参数从 `required` 中省略，并使用 `args.get()` 读取它。如需带有可选键的类型化 schema，请参阅 [TypedDict 类](https://code.claude.com/docs/zh-CN/agent-sdk/python.md#input-schema-options)。149* **Python**：字典 schema 要求每个键都必须提供。请使用 JSON Schema 形式，将该参数从 `required` 中省略，并使用 `args.get()` 读取它。如需带有可选键的类型化 schema，请参阅 [TypedDict 类](https://code.claude.com/docs/zh-CN/agent-sdk/python.md#input-schema-options)。

150 150

151下面的 [`get_precipitation_chance` 工具](#add-more-tools)展示了这两种写法。151[`get_precipitation_chance` 工具](#add-more-tools)展示了这两种写法。

152 152

153### 调用自定义工具153### 调用自定义工具

154 154

155通过 `mcpServers` 选项将您创建的 MCP 服务器传递给 `query`，并在 `allowedTools` 中列出每个工具的[完全限定名称](https://code.claude.com/docs/zh-CN/agent-sdk/mcp.md#tool-naming-convention)，以便工具运行而无需权限提示。该名称为 `mcp__{server_name}__{tool_name}`，其中 `{server_name}` 是您在 `mcpServers` 中为服务器指定的键。如果该键包含 `.` 或空格等字符，请在编写 `{server_name}` 时将其替换为 `_`。155要调用自定义工具，请按以下步骤操作：

156

1571. 通过 `mcpServers` 选项将您创建的 MCP 服务器传递给 `query`。

1582. 在 `allowedTools` 中列出该工具的[完全限定名称](https://code.claude.com/docs/zh-CN/agent-sdk/mcp.md#tool-naming-convention)，以[预先批准](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md#allow-and-deny-rules)对它的调用。该名称遵循 `mcp__{server_name}__{tool_name}` 约定，其中 `{server_name}` 是您在 `mcpServers` 中为服务器指定的键。如果该键包含 `.` 或空格等字符，请在编写 `{server_name}` 时将其替换为 `_`。

156 159

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

158 161

329| :- | :- | :- |332| :- | :- | :- |

334 337

335注释是元数据，不是强制执行。标记为 `readOnlyHint: true` 的工具如果处理程序这样做，仍然可以写入磁盘。保持注释与处理程序准确一致。338注释是元数据，不是强制执行。标记为 `readOnlyHint: true` 的工具如果处理程序这样做，仍然可以写入磁盘。保持注释与处理程序准确一致。

336 339

373 376

374### 配置允许的工具377### 配置允许的工具

375 378

376`tools`选项和允许/禁止列表影响两个层级：可用性（控制工具是否出现在Claude的上下文中）和权限（控制Claude尝试调用后是否批准该调用）。`tools`和裸名称`disallowedTools`条目改变可用性。`allowedTools`和作用域`disallowedTools`规则改变权限。如果您在`allowedTools`中命名其中一个[任务跟踪工具](https://code.claude.com/docs/zh-CN/agent-sdk/todo-tracking.md#model-availability)，Claude Code也会为该会话启用这些工具。379您可以通过`tools`、`allowedTools`和`disallowedTools`选项控制两个层级：

380

381* **可用性**：工具是否出现在Claude的上下文中。要更改它，请使用`tools`选项，或在`disallowedTools`中列出裸内置工具名称，例如`"Bash"`。

382* **权限**：当Claude发起调用时，Claude Code是否批准该调用。要更改它，请使用`allowedTools`或限定范围的`disallowedTools`规则，例如`"Bash(rm *)"`。

377 383

378| 选项 | 层级 | 效果 |384| 选项 | 层级 | 效果 |

379| :- | :- | :- |385| :- | :- | :- |

380| `tools: ["Read", "Grep"]` | 可用性 | 仅列出的内置工具在Claude的上下文中。未列出的内置工具被移除。MCP工具不受影响。 |386| `tools: ["Read", "Grep"]` | 可用性 | 仅列出的内置工具在Claude的上下文中。未列出的内置工具被移除。MCP工具不受影响。 |

381| `tools: []` | 可用性 | 所有内置工具都被移除。Claude只能使用您的MCP工具。 |387| `tools: []` | 可用性 | 所有内置工具都被移除。Claude只能使用您的MCP工具。 |

382| 允许的工具 | 权限 | 列出的工具无需权限提示即可运行。其他未列出的工具保持可用；调用通过[权限流程](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md)进行。 |388| 允许的工具 | 权限 | 列出的工具会被预先批准，但[任何允许规则都不会批准的调用](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md#calls-an-allow-rule-never-approves)除外。对未列入列表的工具的调用将通过[权限流程](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md)进行。 |

383| 禁止的工具 | 两者 | 裸工具名称如`"Bash"`从Claude的上下文中移除工具，与从`tools`中省略它的效果相同。作用域规则如`"Bash(rm *)"`将工具保留在上下文中，仅拒绝与[如所写](https://code.claude.com/docs/zh-CN/permissions.md#bash-rule-limits)匹配的调用。 |389| 禁止的工具 | 两者 | 裸内置工具名称如`"Bash"`会从Claude的上下文中移除该工具。限定范围的规则如`"Bash(rm *)"`将工具保留在上下文中，并拒绝与其[如所写](https://code.claude.com/docs/zh-CN/permissions.md#bash-rule-limits)匹配的调用。 |

384 390

385要完全移除内置工具，请从`tools`中省略它或在`disallowedTools`中列出其裸名称（Python：`disallowed_tools`）；两者都将工具保留在上下文之外，以便Claude永远不会尝试它。作用域`disallowedTools`规则阻止匹配的调用但将工具保留为可见，因此Claude可能会浪费一个回合尝试它。有关完整的评估顺序，请参阅[配置权限](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md)。391要从Claude的上下文中移除内置工具，请从`tools`中省略它，或在`disallowedTools`（TypeScript）或`disallowed_tools`（Python）中列出其裸名称。有关完整的评估顺序，请参阅[配置权限](https://code.claude.com/docs/zh-CN/agent-sdk/permissions.md#how-permissions-are-evaluated)。

386 392

387### 要求特定工具需经批准393### 要求特定工具需经批准

388 394

637 643

638## 返回结构化数据644## 返回结构化数据

639 645

640`structuredContent` 是结果上的可选 JSON 对象，与 `content` 数组分开。使用它来返回原始值，Claude 可以将其作为精确字段读取，而不是从文本字符串或图像中解析它们。646`structuredContent` 是结果上的可选 JSON 对象，与 `content` 数组分开。使用它来返回原始值，Claude 可以将其作为精确字段读取，而不是从文本字符串或图像中解析它们。对于 Python 处理程序，请参阅 [Python 中的结构化内容](#structured-content-in-python)。

641 647

642当设置 `structuredContent` 时，Claude 会接收 JSON 以及来自 `content` 的任何图像或资源块。`content` 中的文本块不会被转发，因为假设它们会复制结构化数据。下面的示例将图表呈现为图像块，并从同一处理程序的 `structuredContent` 中返回其后面的数据点。在代码片段中，`chartPngBuffer` 是一个包含呈现的 PNG 字节的 `Buffer`。648当 TypeScript `tool()` 处理程序设置 `structuredContent` 时，Claude 会接收 JSON 以及 `content` 中的图像和资源块，而 `content` 中的文本块不会到达 Claude。下面的示例将图表呈现为图像块，并从同一处理程序的 `structuredContent` 中返回其后面的数据点。在代码片段中，`chartPngBuffer` 是一个包含呈现的 PNG 字节的 `Buffer`。

643 649

644```typescript TypeScript theme={null}650```typescript TypeScript theme={null}

645return {651return {

agent-sdk/mcp.md +1 −1

Details

205 205

206### 使用 allowedTools 自动批准206### 使用 allowedTools 自动批准

207 207

208使用 `allowedTools` 自动批准特定的 MCP 工具，这样 Claude 就可以在没有权限提示的情况下使用它们：208使用 `allowedTools` 自动批准特定的 MCP 工具：

209 209

210```typescript TypeScript hidelines={1,-1} theme={null}210```typescript TypeScript hidelines={1,-1} theme={null}

211const _ = {211const _ = {

agent-sdk/permissions.md +6 −6

Details

18 18

19**1. Hooks**19**1. Hooks**

20 20

21运行 [hook](https://code.claude.com/docs/zh-CN/agent-sdk/hooks.md)。hook 可以直接拒绝该调用，也可以将其放行。返回 `allow` 的 hook 不会跳过下方的拒绝和询问规则，无论 hook 结果如何，这些规则都会被评估。21运行 [hook](https://code.claude.com/docs/zh-CN/agent-sdk/hooks.md)。hook 可以直接拒绝该调用，也可以将其放行。返回 `allow` 的 hook 不会跳过拒绝规则和询问规则步骤，无论 hook 结果如何，这些步骤都会被评估。

22 22

23返回 `allow` 的 `PreToolUse` hook 也不能批准目标被 Claude Code 识别为 [关键路径](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths) 的 `rm` 或 `rmdir` 命令，例如 `rm -rf ~`。关于该 `allow` 在计划模式下的作用，请参阅 [计划模式下的 hook 批准](https://code.claude.com/docs/zh-CN/permissions.md#hook-approvals-in-plan-mode)。23返回 `allow` 的 `PreToolUse` hook 也不能批准目标被 Claude Code 识别为 [关键路径](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths) 的 `rm` 或 `rmdir` 命令，例如 `rm -rf ~`。关于该 `allow` 在计划模式下的作用，请参阅 [计划模式下的 hook 批准](https://code.claude.com/docs/zh-CN/permissions.md#hook-approvals-in-plan-mode)。

24 24

54 54

55被识别出的 [关键路径删除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths) 不会被允许规则批准，被标记为 `Dangerous rm operation not ruled out` 的命令也不会被 `Bash` 或 `Bash(*)` 规则批准。它们是否随后到达您的回调取决于权限模式：例如在 `auto` 模式的 Agent SDK 会话中，Claude Code 默认拒绝它们而不调用它。[关键路径模式表](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-path-removals-in-each-permission-mode) 列出了每种模式对它们的处理方式。55被识别出的 [关键路径删除](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-paths) 不会被允许规则批准，被标记为 `Dangerous rm operation not ruled out` 的命令也不会被 `Bash` 或 `Bash(*)` 规则批准。它们是否随后到达您的回调取决于权限模式：例如在 `auto` 模式的 Agent SDK 会话中，Claude Code 默认拒绝它们而不调用它。[关键路径模式表](https://code.claude.com/docs/zh-CN/permission-modes.md#critical-path-removals-in-each-permission-mode) 列出了每种模式对它们的处理方式。

56 56

~~57允许规则不会批准从 [网络路径](https://code.claude.com/docs/zh-CN/permissions.md#network-paths) 进行的读取。~~57允许规则不会批准从[网络路径](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)进行的读取。

58 58

59**6. canUseTool 回调**59**6. canUseTool 回调**

60 60

61如果上述任何步骤都未解决，调用您的 [`canUseTool` 回调](https://code.claude.com/docs/zh-CN/agent-sdk/user-input) 以获得决定。在 `dontAsk` 模式下，此步骤被跳过，工具被拒绝，不过您安装的 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 仍然可以批准[部分此类调用](https://code.claude.com/docs/zh-CN/permissions.md#precedence-among-rules-hooks-and-mods)。61如果前面的步骤都未能解决该请求，则调用您的 [`canUseTool` 回调](https://code.claude.com/docs/zh-CN/agent-sdk/user-input)来做出决定。在 `dontAsk` 模式下，此步骤会被跳过，工具将被拒绝，不过您安装的 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/overview.md) 仍可以批准[某些此类调用](https://code.claude.com/docs/zh-CN/permissions.md#precedence-among-rules-hooks-and-mods)。

62 62

63在 TypeScript SDK 中，如果您设置了 [`permissionPrompts: 'none'`](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#options)，您的回调在此步骤不会被调用。[`PermissionRequest` hook](https://code.claude.com/docs/zh-CN/hooks#permissionrequest) 仍然有机会决定，如果它不决定，Claude Code 拒绝调用。该选项需要 Claude Code v2.1.259 或更高版本。63在 TypeScript SDK 中，如果您设置了 [`permissionPrompts: 'none'`](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#options)，您的回调在此步骤不会被调用。[`PermissionRequest` hook](https://code.claude.com/docs/zh-CN/hooks#permissionrequest) 仍然有机会决定，如果它不决定，Claude Code 拒绝调用。该选项需要 Claude Code v2.1.259 或更高版本。

64 64

80 80

81## 允许和拒绝规则81## 允许和拒绝规则

82 82

83`allowed_tools` 和 `disallowed_tools`（TypeScript：`allowedTools` / `disallowedTools`）在上述评估流程中向允许和拒绝规则列表添加条目。如果你在 `allowed_tools` 中命名了某个[任务跟踪工具](https://code.claude.com/docs/zh-CN/agent-sdk/todo-tracking.md#model-availability)，Claude Code 也会为该会话启用这些工具。任何其他未在 `allowed_tools` 中列出的工具仍然可供 Claude 使用，对其的调用如果需要批准，则会进入权限模式。拒绝规则的行为取决于它们是命名工具还是在工具内限定模式。83当您设置 `allowedTools` 和 `disallowedTools`（TypeScript）或 `allowed_tools` 和 `disallowed_tools`（Python）时，Claude Code 会将其中的条目添加到[权限评估流程](#how-permissions-are-evaluated)中的允许和拒绝规则列表。任何其他未在 `allowed_tools` 中列出的工具仍然可供 Claude 使用，对其的调用如果需要批准，则会进入权限模式。

84 84

85| 选项 | 效果 |85| 选项 | 效果 |

86| :- | :- |86| :- | :- |

87| `allowed_tools=["Read", "Grep"]` | `Read` 和 `Grep` 被自动批准，[从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)除外。此处未列出的其他工具仍然存在，对它们的调用如果需要批准，则会进入权限模式和 `canUseTool`。 |87| `allowed_tools=["Read", "Grep"]` | `Read` 和 `Grep` 被自动批准，[从网络路径读取](https://code.claude.com/docs/zh-CN/permissions.md#network-paths)除外。此处未列出的其他工具仍然存在，对它们的调用如果需要批准，则会进入权限模式和 `canUseTool`。 |

89| `disallowed_tools=["Bash(rm *)"]` | `Bash` 保持可用。匹配 `rm *` [如所写](https://code.claude.com/docs/zh-CN/permissions.md#bash-rule-limits) 的调用在每种权限模式中都被拒绝，包括 `bypassPermissions`。其他 `Bash` 调用（包括 `/bin/rm`）会进入权限模式。 |89| `disallowed_tools=["Bash(rm *)"]` | `Bash` 保持可用。匹配 `rm *` [如所写](https://code.claude.com/docs/zh-CN/permissions.md#bash-rule-limits) 的调用在每种权限模式中都被拒绝，包括 `bypassPermissions`。其他 `Bash` 调用（包括 `/bin/rm`）会进入权限模式。 |

91 91

92允许规则仅在字面 `mcp__<server>__` 前缀之后接受工具名称通配符。服务器段必须无通配符，以便规则命名您配置的特定服务器：`mcp__puppeteer__*` 匹配来自 `puppeteer` 服务器的每个工具，`mcp__github__get_*` 匹配其 `get_` 工具。未锚定的条目（如 `allowed_tools=["*"]` 或 `allowed_tools=["mcp__*"]`）会被忽略，不会自动批准任何内容。92允许规则仅在字面 `mcp__<server>__` 前缀之后接受工具名称通配符。服务器段必须无通配符，以便规则命名您配置的特定服务器：`mcp__puppeteer__*` 匹配来自 `puppeteer` 服务器的每个工具，`mcp__github__get_*` 匹配其 `get_` 工具。未锚定的条目（如 `allowed_tools=["*"]` 或 `allowed_tools=["mcp__*"]`）会被忽略，不会自动批准任何内容。

93 93

agent-sdk/python.md +1 −1

Details

2787 2787

2788运行一个后台来源，并将每个事件传递给 Claude，使其无需轮询即可做出响应：`command` 运行一个脚本，每行 stdout 产生一个事件；`ws` 打开一个 WebSocket，每个文本帧产生一个事件。`command` 和 `ws` 必须且只能提供其中一个。2788运行一个后台来源，并将每个事件传递给 Claude，使其无需轮询即可做出响应：`command` 运行一个脚本，每行 stdout 产生一个事件；`ws` 打开一个 WebSocket，每个文本帧产生一个事件。`command` 和 `ws` 必须且只能提供其中一个。

2789 2789

2790当 Monitor 运行命令时，它遵循与 Bash 相同的权限规则；WebSocket 监视会单独请求批准。`ws` 来源需要 Claude Code v2.1.195 或更高版本。有关行为和提供商可用性，请参阅 [Monitor 工具参考](https://code.claude.com/docs/zh-CN/tools-reference.md#monitor-tool)。2790`ws` 来源需要 Claude Code v2.1.195 或更高版本。当 Monitor 运行命令时，它遵循与 Bash 相同的权限规则。有关 WebSocket 权限、行为和提供商可用性，请参阅 [Monitor 工具参考](https://code.claude.com/docs/zh-CN/tools-reference.md#monitor-tool)。

2791 2791

2792**输入：**2792**输入：**

2793 2793

agent-sdk/typescript.md +5 −3

Details

3387 3387

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

3389 3389

3390`timeout_ms` 是监视的截止时间（以毫秒为单位）。它默认为 300000，接受最高 3600000 的值。有效截止时间最多为 1800000，即 30 分钟，因此更大的接受值会被缩短到该值。在截止时间，监视结束，Claude 收到一个通知，以便在仍需要时可以启动新的监视。3390`timeout_ms` 是监视的截止时间（以毫秒为单位）：

3391 3391

3392导出的类型将 `timeout_ms` 标记为必需，因为 schema 填充了默认值；省略它的调用会验证通过。3392* **默认值和限制**：它默认为 300000，接受最高 3600000 的值。有效截止时间最多为 1800000，即 30 分钟，因此更大的接受值会被缩短到该值

3393* **到达截止时间时**：监视结束，Claude 收到一个通知，以便在仍需要时可以启动新的监视

3394* **在类型中为必需**：导出的类型将 `timeout_ms` 标记为必需，因为 schema 填充了默认值；省略它的调用会验证通过

3393 3395

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

3395 3397

3396### TaskOutput3398### TaskOutput

3397 3399

best-practices.md +2 −2

Details

433 433

434### 更改模型和 effort434### 更改模型和 effort

435 435

436[Effort](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level) 是控制 Claude 思考时长的主要手段，它取代了人们过去通过提示词措辞所做的大部分工作。Claude Opus 5.5、Sonnet 5.5 和 Haiku 5.5 默认为 `medium`，这对于范围明确的日常功能开发已经足够。您会在会话中使用 `/effort` 调整它的情况：436[Effort](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level) 是控制 Claude 思考时长的主要手段，它取代了人们过去通过提示词措辞所做的大部分工作。Claude Fable 5.2、Opus 5.5、Sonnet 5.5 和 Haiku 5.5 默认为 `medium`，这对于范围明确的日常功能开发已经足够。您会在会话中使用 `/effort` 调整它的情况：

437 437

438* 当做对事情取决于容易被忽略的情况时，使用 `/effort high` 或 `/effort xhigh` 调高。比如您没写过的代码中的错误、不稳定的测试，或者 Claude 必须找到旧 schema 的每一个读取方的 schema 变更。Claude 随后会在回答前检查更多边界情况并验证更多工作，额外的时间和 token 就花在这里。438* 当做对事情取决于容易被忽略的情况时，使用 `/effort high` 或 `/effort xhigh` 调高。比如您没写过的代码中的错误、不稳定的测试，或者 Claude 必须找到旧 schema 的每一个读取方的 schema 变更。Claude 随后会在回答前检查更多边界情况并验证更多工作，额外的时间和 token 就花在这里。

439* 当您快速来回交流并且无论如何都会审查每个结果时，使用 `/effort low` 调低：头脑风暴、初步草图、跨几个文件的重命名。Claude 会更快地给您一个起点，而且由于您在引导每一步，额外的深思熟虑除了让您多等之外不会改变太多。439* 当您快速来回交流并且无论如何都会审查每个结果时，使用 `/effort low` 调低：头脑风暴、初步草图、跨几个文件的重命名。Claude 会更快地给您一个起点，而且由于您在引导每一步，额外的深思熟虑除了让您多等之外不会改变太多。

440* 将 `max` 留给您希望 Claude 在没有您参与的情况下攻克的难题，比如寻找安全漏洞。在普通任务上它往往会过度思考，所以您付出更多，得到的答案却可能并不比 `high` 更好。440* 将 `max` 留给您希望 Claude 在没有您参与的情况下攻克的难题，比如寻找安全漏洞。在普通任务上它往往会过度思考，所以您付出更多，得到的答案却可能并不比 `high` 更好。

441* 当只有下一条消息需要它时，比如在一系列常规工作中间出现一个棘手的问题，请在那条提示词中加入 [`ultrathink`](https://code.claude.com/docs/zh-CN/model-config#use-ultrathink-for-one-off-deep-reasoning)，而不是更改设置。441* 当只有下一条消息需要它时，比如在一系列常规工作中间出现一个棘手的问题，请在那条提示词中加入 [`ultrathink`](https://code.claude.com/docs/zh-CN/model-config#use-ultrathink-for-one-off-deep-reasoning)，而不是更改设置。

442 442

443至于模型本身，默认的 Opus 5.5 能很好地处理大多数编码工作，而 Sonnet 在常规工作上成本更低。当您通过 `/model fable` 明确选择时，可以使用 [Claude Fable 5.1](https://code.claude.com/docs/zh-CN/model-config.md#work-with-fable)，而 Haiku 很适合执行简单任务的子代理。[模型配置](https://code.claude.com/docs/zh-CN/model-config.md)列出了各套餐和提供商的完整列表。443至于模型本身，默认的 Opus 5.5 能很好地处理大多数编码工作，而 Sonnet 在常规工作上成本更低。要使用 [Claude Fable 5.2](https://code.claude.com/docs/zh-CN/model-config.md#work-with-fable)，请运行 `/model fable`。Haiku 很适合执行简单任务的子代理。[模型配置](https://code.claude.com/docs/zh-CN/model-config.md)列出了各套餐和提供商的完整列表。

444 444

445### 了解子代理的成本445### 了解子代理的成本

446 446

claude-apps-gateway.md +1 −1

Details

172 172

173成功启动不会验证推理路径，因为 Amazon Bedrock 和 Google Cloud 的 Agent Platform 实例凭据在第一个请求时解析，而不是在启动时。173成功启动不会验证推理路径，因为 Amazon Bedrock 和 Google Cloud 的 Agent Platform 实例凭据在第一个请求时解析，而不是在启动时。

174 174

175监视 stderr 以获取启动序列。日志行使用格式 `[gateway] <timestamp> <level> <message>`，审计事件是带有 `evt` 字段的单行 JSON，启动横幅（下面省略）在迁移和侦听行之间打印。新数据库每个 schema 迁移打印一行 `migration N applied`；已迁移的数据库不打印任何内容。您应该按顺序看到：175监视 stderr 以获取启动序列。默认情况下，日志行使用格式 `[gateway] <timestamp> <level> <message>`，启动横幅（下面省略）在迁移和侦听行之间打印。审计事件是带有 `evt` 字段的单行 JSON。新数据库每个 schema 迁移打印一行 `migration N applied`；已迁移的数据库不打印任何内容。您应该按顺序看到：

176 176

177```text theme={null}177```text theme={null}

178{"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}178{"ts":"2026-06-10T17:03:21.114Z","evt":"config.load","path":"/etc/claude/gateway.yaml","sha256":"…"}

claude-apps-gateway-config.md +40 −2

Details

28 28

29**可选部分：**29**可选部分：**

30 30

31* [`login_notice`](#login_notice)：开发人员登录时看到的通知

31* [`admin`](#admin)：Admin API 身份验证和支出限制的保留32* [`admin`](#admin)：Admin API 身份验证和支出限制的保留

32* [`enforcement`](#enforcement)：支出限制故障开放或故障关闭行为33* [`enforcement`](#enforcement)：支出限制故障开放或故障关闭行为

33* [`pricing`](#pricing)：合同费率，以及适用于支出计量器和开发人员所见成本数字的乘数34* [`pricing`](#pricing)：合同费率，以及适用于支出计量器和开发人员所见成本数字的乘数

847 848

848## 可选部分849## 可选部分

849 850

851### `login_notice`

852

853要在开发者登录时向其显示一条通知，请将顶层 `login_notice` 键设置为通知文本，最多 500 个字符。此示例说明了该网关面向哪些人员以及在何处申请访问权限：

854

855```yaml theme={null}

856login_notice: This gateway is for Example Corp staff. For access questions, email it-help@example.com.

857```

858

859开发者会在浏览器中网关的验证页面上以及终端中的交互式登录界面上，于 `Notice from <gateway hostname>` 下方看到该文本。文本中的换行会变为空格。该通知在登录之前显示，因此任何能够访问网关的人都可以读取它。

860

861需要网关服务器上运行 Claude Code v2.1.319 或更高版本；若要在终端界面中显示，开发者的机器上也需要该版本。较早版本的网关在发现该键时会拒绝启动。请在添加该键之前升级所有副本，并在回滚之前移除该键。

862

850### `admin`863### `admin`

851 864

852可选。启用 `/v1/organizations/spend_limits`（它与 Anthropic 的公开 Admin API 一致），并在 `/v1/messages` 上按开发者执行支出限制。有关上限的设置和执行方式，请参阅[支出限制](https://code.claude.com/docs/zh-CN/claude-apps-gateway-spend-limits.md)；本节介绍用于启用和调整该功能的 `gateway.yaml` 键。865可选。启用 `/v1/organizations/spend_limits`（它与 Anthropic 的公开 Admin API 一致），并在 `/v1/messages` 上按开发者执行支出限制。有关上限的设置和执行方式，请参阅[支出限制](https://code.claude.com/docs/zh-CN/claude-apps-gateway-spend-limits.md)；本节介绍用于启用和调整该功能的 `gateway.yaml` 键。

865 # IdP groups granted full admin via the normal gateway JWT (no API key).878 # IdP groups granted full admin via the normal gateway JWT (no API key).

866 admin_groups: [platform-finops]879 admin_groups: [platform-finops]

867 blocked_message: request an increase at https://go.example.com/claude-limits880 blocked_message: request an increase at https://go.example.com/claude-limits

881 # Try eng-platform's pooled budget first, then eng-all's, then any other group's.

882 pooled_conflict_rule: priority_list

883 pooled_priority_order: [eng-platform, eng-all]

868```884```

869 885

870| 字段 | 必需 | 描述 |886| 字段 | 必需 | 描述 |

877| `spend_retention_months` | 否 | 默认值 `13`。早于此时间的 `spend` 计数器行会被清除。默认值保留完整一年加上当前未满的月份，以便进行同比报告。 |893| `spend_retention_months` | 否 | 默认值 `13`。早于此时间的 `spend` 计数器行会被清除。默认值保留完整一年加上当前未满的月份，以便进行同比报告。 |

878| `identity_retention_days` | 否 | 默认值 `90`。`principal_emails` 行的最后活跃 TTL，这些行保存每位开发者的电子邮件、显示名称和组（PII）。有意设置得比支出保留期短，以便已取消配置的身份过期，而其匿名支出计数器仍然保留。 |894| `identity_retention_days` | 否 | 默认值 `90`。`principal_emails` 行的最后活跃 TTL，这些行保存每位开发者的电子邮件、显示名称和组（PII）。有意设置得比支出保留期短，以便已取消配置的身份过期，而其匿名支出计数器仍然保留。 |

879| `group_limit_mode` | 否 | `min`（默认）或 `max`。当开发者属于多个设有上限的组时，`min` 执行最严格的上限，`max` 执行最宽松的上限。执行和 `/effective` 都使用此设置。 |895| `group_limit_mode` | 否 | `min`（默认）或 `max`。当开发者属于多个设有上限的组时，`min` 执行最严格的上限，`max` 执行最宽松的上限。执行和 `/effective` 都使用此设置。 |

896| `pooled_conflict_rule` | 否 | `default_order`（默认）或 `priority_list`。网关尝试开发者共享预算的顺序。请参阅[共享预算顺序](#pooled-budget-order)。需要 v2.1.319 或更高版本。 |

897| `pooled_priority_order` | 使用 `priority_list` 时必需 | 最多 50 个组名，每个只列出一次，拼写与您的 IdP 发送的一致。网关会优先尝试这些组的共享预算。请参阅[共享预算顺序](#pooled-budget-order)。需要 v2.1.319 或更高版本。 |

898

899#### 共享预算顺序

900

901共享预算是整个组共同消耗的一个月度限额。要设置共享预算，请在[设置该组月度上限的请求](https://code.claude.com/docs/zh-CN/claude-apps-gateway-spend-limits.md#set-a-cap)中添加 `pooled_budget`，例如 `"pooled_budget": {"amount": "500000"}` 表示 \$5,000。该请求还需要该组的 `scope`、`"period": "monthly"` 和 `amount`，其中 `amount` 仍是每位成员自己的上限。

902

903对于属于多个此类组的开发者，每个请求都会计入第一个支出低于其限额的预算；当所有预算都已用完时，请求会被拒绝。`pooled_conflict_rule` 设置网关尝试这些预算的顺序：

904

905* **`default_order`**：限额最大的优先，限额相同时按组名升序排列

906* **`priority_list`**：先按列表顺序尝试 `pooled_priority_order` 中各组的预算，然后按组名尝试其他组的预算

907

908如果您列出了组但未设置 `pooled_conflict_rule: priority_list`，网关会忽略该列表并在启动时记录一条警告。

909

910早于 v2.1.319 的网关服务器在发现 `pooled_conflict_rule` 或 `pooled_priority_order` 时会拒绝启动。请在添加任一键之前升级所有副本，并在回滚之前移除这两个键。

880 911

881### `enforcement`912### `enforcement`

882 913

1676# 也会记录每个 id_token 中的声明名称，用于 groups_claim 诊断。1707# 也会记录每个 id_token 中的声明名称，用于 groups_claim 诊断。

1677# 它不影响审计事件，总是发出。1708# 它不影响审计事件，总是发出。

1709# 设置 CLAUDE_GATEWAY_LOG_FORMAT=json 可将操作日志行写为包含

1710# severity、time 和 message 的 JSON 对象。

1678 1711

1679listen:1712listen:

1680 host: 0.0.0.01713 host: 0.0.0.0

1697 # 可以省略电子邮件和组；网关从 /userinfo 填充它们。1730 # 可以省略电子邮件和组；网关从 /userinfo 填充它们。

1698 userinfo_fallback: true1731 userinfo_fallback: true

1699 # allowed_groups: [claude-code-users]1732 # allowed_groups: [claude-code-users]

1700 # Okta 仅在请求 `groups` 范围且1733 # Okta 仅在请求 `groups` 作用域且

1701 # 应用的组声明过滤允许它们时发出组。下面的承包商策略1734 # 应用的组声明过滤允许它们时发出组。下面的承包商策略

1702 # 匹配组，因此范围在此处请求。1735 # 匹配组，因此作用域在此处请求。

1703 scopes: [openid, profile, email, offline_access, groups]1736 scopes: [openid, profile, email, offline_access, groups]

1704 # extra_auth_params: { access_type: offline, prompt: consent } # Google1737 # extra_auth_params: { access_type: offline, prompt: consent } # Google

1705 # groups_claim: groups # Entra 应用角色：使用 `roles`1738 # groups_claim: groups # Entra 应用角色：使用 `roles`

1715 # connect_timeout_seconds: 51748 # connect_timeout_seconds: 5

1716 # readiness_grace_seconds: 300 # 在数据库故障转移期间保持通过就绪检查1749 # readiness_grace_seconds: 300 # 在数据库故障转移期间保持通过就绪检查

1717 1750

1751# 登录时显示的通知。任何能够访问网关的人都可以阅读它。

1752# login_notice: This gateway is for Example Corp staff. For access questions, email it-help@example.com.

1753

1718# 启用 /v1/organizations/spend_limits（镜像 Anthropic Admin API）1754# 启用 /v1/organizations/spend_limits（镜像 Anthropic Admin API）

1719# 和 /v1/messages 上的每开发者支出强制。省略以禁用。1755# 和 /v1/messages 上的每开发者支出强制。省略以禁用。

1720# 上限本身通过 admin API 设置，而不是此处。1756# 上限本身通过 admin API 设置，而不是此处。

1729# # spend_retention_months: 131765# # spend_retention_months: 13

1730# # identity_retention_days: 901766# # identity_retention_days: 90

1731# # group_limit_mode: min1767# # group_limit_mode: min

1768# # pooled_conflict_rule: priority_list

1769# # pooled_priority_order: [eng-platform, eng-all]

1732 1770

1733# enforcement:1771# enforcement:

1734# fail_closed_on_error: false1772# fail_closed_on_error: false

claude-apps-gateway-deploy.md +14 −0

Details

173 * `admin.denied` 记录被拒绝的管理员 API 身份验证尝试，包括客户端 IP、方法、路径和原因，不包括呈现的密钥材料：当呈现了 `x-api-key` 但与配置的密钥不匹配时为 `invalid_key`，当仅呈现了 `Authorization` 标头且其未验证为 `admin.admin_groups` 中的网关会话时为 `bearer_rejected`，或当两个标头都未呈现时为 `no_credentials`173 * `admin.denied` 记录被拒绝的管理员 API 身份验证尝试，包括客户端 IP、方法、路径和原因，不包括呈现的密钥材料：当呈现了 `x-api-key` 但与配置的密钥不匹配时为 `invalid_key`，当仅呈现了 `Authorization` 标头且其未验证为 `admin.admin_groups` 中的网关会话时为 `bearer_rejected`，或当两个标头都未呈现时为 `no_credentials`

174* **运维日志**：人类可读的 `[gateway]` 前缀行，用于启动、警告和上游错误。`CLAUDE_GATEWAY_LOG_LEVEL` 环境变量控制详细程度，接受 `debug`、`info`、`warn` 或 `error`，默认为 `info`。在 `debug` 时，每次登录和刷新也记录 id\_token 中声明的名称（不是值），加上当 `userinfo_fallback` 提供任何时 userinfo 声明的名称，因此您可以诊断 `email_claim` 和 `groups_claim` 设置而不记录 PII。它不影响审计事件，这些事件总是被发出。174* **运维日志**：人类可读的 `[gateway]` 前缀行，用于启动、警告和上游错误。`CLAUDE_GATEWAY_LOG_LEVEL` 环境变量控制详细程度，接受 `debug`、`info`、`warn` 或 `error`，默认为 `info`。在 `debug` 时，每次登录和刷新也记录 id\_token 中声明的名称（不是值），加上当 `userinfo_fallback` 提供任何时 userinfo 声明的名称，因此您可以诊断 `email_claim` 和 `groups_claim` 设置而不记录 PII。它不影响审计事件，这些事件总是被发出。

175 175

176#### 以 JSON 格式写入运维日志

177

178如果您的日志收集器从 JSON 字段中读取每一行的级别，请在网关的环境中设置 `CLAUDE_GATEWAY_LOG_FORMAT=json`。需要网关服务器上的 Claude Code v2.1.319 或更高版本。

179

180随后每条运维日志行都是一个包含 `severity`、`time` 和 `message` 的对象：

181

182```json theme={null}

183{"severity":"INFO","time":"2026-11-04T17:03:21.512Z","message":"claude gateway listening on http://0.0.0.0:8080"}

184```

185

186`severity` 是大写的日志级别，其中 `warn` 写作 `WARNING`。启动失败会产生一条 `ERROR` 行。

187

188审计事件同样写入 stderr，不会改变。它们携带 `ts` 和 `evt`，不带 `severity`。

189

176### 健康190### 健康

177 191

178网关提供 `GET /healthz` 作为活跃探针和 `GET /readyz` 作为就绪探针。`/readyz` 验证存储是否可达。如果您设置了 [`store.readiness_grace_seconds`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#store)，`/readyz` 在存储停止应答后最多继续报告就绪达到那么多秒。192网关提供 `GET /healthz` 作为活跃探针和 `GET /readyz` 作为就绪探针。`/readyz` 验证存储是否可达。如果您设置了 [`store.readiness_grace_seconds`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#store)，`/readyz` 在存储停止应答后最多继续报告就绪达到那么多秒。

claude-apps-gateway-spend-limits.md +11 −2

Details

6 6

7> 通过 Claude 应用网关为每个开发者按天、周或月设置支出上限。使用 Admin API 设置限制，网关在每个请求上实时执行这些限制。7> 通过 Claude 应用网关为每个开发者按天、周或月设置支出上限。使用 Admin API 设置限制，网关在每个请求上实时执行这些限制。

8 8

9支出限制限制了每个开发者在给定的一天、一周或一个月内通过你的 [Claude 应用网关](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 可以花费的金额。当开发者超过他们的上限时，网关在他们的下一个请求上返回 `429`，并阻止他们直到该周期重置或管理员提高上限。使用支出限制为每个开发者、团队或整个组织设置一个共享凭证的上限。9支出限制限定了每个开发者在给定的一天、一周或一个月内通过您的 [Claude 应用网关](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 可以花费的金额。当开发者超过其上限时，网关会对其后续请求返回 `429`，直到管理员提高上限，或者在上限高于 \$0 的情况下直到上限重置。使用支出限制可以为每个开发者、每个组或整个组织在所有人共享的凭据上设置一个上限。

10 10

11默认情况下，Claude 应用网关通过一个共享的上游凭证转发所有推理，因此你的提供商的账单将所有内容归属于该凭证，而不是单个开发者。在 Amazon Bedrock 上，[按开发者的 AWS 成本归属](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config.md#per-developer-aws-cost-attribution) 改变了这一点。没有按开发者的限制，一个失控的代理群可能会花费组织的整个承诺。支出限制是网关在该共享账单之上的按开发者视图和断路器。11默认情况下，Claude 应用网关通过一个共享的上游凭证转发所有推理，因此你的提供商的账单将所有内容归属于该凭证，而不是单个开发者。在 Amazon Bedrock 上，[按开发者的 AWS 成本归属](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config.md#per-developer-aws-cost-attribution) 改变了这一点。没有按开发者的限制，一个失控的代理群可能会花费组织的整个承诺。支出限制是网关在该共享账单之上的按开发者视图和断路器。

12 12

51 51

52在每个 `/v1/messages` 请求上，网关在一个 Postgres 查询中查找开发者的上限和期间至今的支出。超过任何上限的开发者会获得 `429` 和 `error.type: billing_error` 以及标头 `x-should-retry: false`。52在每个 `/v1/messages` 请求上，网关在一个 Postgres 查询中查找开发者的上限和期间至今的支出。超过任何上限的开发者会获得 `429` 和 `error.type: billing_error` 以及标头 `x-should-retry: false`。

53 53

54消息命名该期间和重置时间，例如 `spend limit reached (daily; resets 2026-08-08 00:00 UTC)`，后跟你的 [`admin.blocked_message`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#admin)（如果设置）。当开发者同时超过多个上限时，消息命名最后重置的上限。响应还包含一个 `retry-after` 标头，其中包含直到该重置的剩余秒数。在网关服务器上的 v2.1.225 之前，消息是 `spend limit reached`，没有期间、重置时间或 `retry-after` 标头。54对于高于 `"0"` 的上限，消息会给出该上限重置的 UTC 日期。如果您设置了 [`admin.blocked_message`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#admin)，网关会将其附加在后面，如下例所示：

56```text theme={null}

57spend limit reached · resets Dec 1 · request an increase at https://go.example.com/claude-limits

58```

60对于 `"0"` 上限，由于重置不会解除该上限，消息中不包含日期。当开发者同时超过多个上限时，消息描述最后重置的上限。响应还包含一个 `retry-after` 标头，其中包含直到该上限期间结束的剩余秒数。

62在网关服务器上的 v2.1.319 之前，消息会命名期间和重置时间，例如 `spend limit reached (daily; resets 2026-08-08 00:00 UTC)`。在 v2.1.225 之前，消息是 `spend limit reached`，没有期间、重置时间或 `retry-after` 标头。

55 63

56在 v2.1.227 或更高版本上，`<public_url>/protocol` 处的协议参考也列出了确切的使用限制响应标头和 `429` 正文。64在 v2.1.227 或更高版本上，`<public_url>/protocol` 处的协议参考也列出了确切的使用限制响应标头和 `429` 正文。

57 65

106| 在带有 [`admin:`](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#admin) 块的网关上，当没有上限适用于开发者时，`/usage` 中 **Spend (UTC)** 下显示的估计支出，例如"\$13.06 today · \$80.76 this week · \$272.06 this month" | v2.1.319 或更高版本 | v2.1.319 或更高版本 |

98 107

99警告和百分比来自 `anthropic-ratelimit-unified-*` 标头，网关会将这些标头添加到具有上限的开发者的每个成功 `/v1/messages` 响应中。标头始终描述开发者自己的上限：网关会剥离上游提供商的速率限制标头（这些标头描述您的共享配额），从不转发它们。108警告和百分比来自 `anthropic-ratelimit-unified-*` 标头，网关会将这些标头添加到具有上限的开发者的每个成功 `/v1/messages` 响应中。标头始终描述开发者自己的上限：网关会剥离上游提供商的速率限制标头（这些标头描述您的共享配额），从不转发它们。

100 109

cli-reference.md +2 −2

Details

42| `claude plugin` | 管理 Claude Code [插件](https://code.claude.com/docs/zh-CN/plugins/overview.md)。别名：`claude plugins`。请参阅 [插件参考](https://code.claude.com/docs/zh-CN/plugins/cli-reference.md#claude-plugin-commands) 了解子命令 | `claude plugin install code-review@claude-plugins-official` |42| `claude plugin` | 管理 Claude Code [插件](https://code.claude.com/docs/zh-CN/plugins/overview.md)。别名：`claude plugins`。请参阅 [插件参考](https://code.claude.com/docs/zh-CN/plugins/cli-reference.md#claude-plugin-commands) 了解子命令 | `claude plugin install code-review@claude-plugins-official` |

43| `claude purge [path]` | 删除项目的所有本地 Claude Code 状态：会话记录、任务列表、调试日志、文件编辑历史、提示词历史行和项目在 `~/.claude.json` 中的条目。省略 `[path]` 以从交互式列表中选择。标志：`--dry-run` 预览，`-y`/`--yes` 跳过确认，`-i`/`--interactive` 确认每一项，`--all` 用于每个项目。请参阅 [清除本地数据](https://code.claude.com/docs/zh-CN/claude-directory.md#clear-local-data) | `claude purge ~/work/repo --dry-run` |43| `claude purge [path]` | 删除项目的所有本地 Claude Code 状态：会话记录、任务列表、调试日志、文件编辑历史、提示词历史行和项目在 `~/.claude.json` 中的条目。省略 `[path]` 以从交互式列表中选择。标志：`--dry-run` 预览，`-y`/`--yes` 跳过确认，`-i`/`--interactive` 确认每一项，`--all` 用于每个项目。请参阅 [清除本地数据](https://code.claude.com/docs/zh-CN/claude-directory.md#clear-local-data) | `claude purge ~/work/repo --dry-run` |

44| `claude remote-control` | 启动 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 服务器以从 Claude.ai 或 Claude 应用控制 Claude Code。在服务器模式下运行（无本地交互式会话）。请参阅 [服务器模式标志](https://code.claude.com/docs/zh-CN/remote-control.md#start-a-remote-control-session)。停止服务器后，您可以恢复它正在服务的会话。请参阅 [停止服务器后恢复会话](https://code.claude.com/docs/zh-CN/remote-control.md#resume-sessions-after-stopping-the-server) | `claude remote-control --name "My Project"` |44| `claude remote-control` | 启动 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 服务器以从 claude.ai 或 Claude 应用控制 Claude Code。别名：`claude rc`。在服务器模式下运行（无本地交互式会话）。请参阅 [服务器模式标志](https://code.claude.com/docs/zh-CN/remote-control.md#start-a-remote-control-session)。停止服务器后，您可以恢复它正在服务的会话。请参阅 [停止服务器后恢复会话](https://code.claude.com/docs/zh-CN/remote-control.md#resume-sessions-after-stopping-the-server) | `claude remote-control --name "My Project"` |

45| `claude respawn <id>` | 重启 [后台会话](https://code.claude.com/docs/zh-CN/agent-view.md#manage-sessions-from-the-shell)，运行或已停止，保持其对话完整。使用 `--all` 重启每个运行中的会话，例如以获取更新的 Claude Code 二进制文件 | `claude respawn 7c5dcf5d` |45| `claude respawn <id>` | 重启 [后台会话](https://code.claude.com/docs/zh-CN/agent-view.md#manage-sessions-from-the-shell)，运行或已停止，保持其对话完整。使用 `--all` 重启每个运行中的会话，例如以获取更新的 Claude Code 二进制文件 | `claude respawn 7c5dcf5d` |

46| `claude rm <id>` | 从列表中删除 [后台会话](https://code.claude.com/docs/zh-CN/agent-view.md#manage-sessions-from-the-shell)。当删除因 [会话的 worktree 而被拒绝](https://code.claude.com/docs/zh-CN/agent-view.md#what-deleting-a-session-removes) 且第二个 `claude rm` 可以解决它时，拒绝会打印要传递的确切标志和值：`--discard-unpushed <commit>@<worktree-id>` 丢弃具有未推送提交的 worktree 及其提交，`--force-remove-worktree <worktree-id>` 删除 git 或 `WorktreeRemove` hook 无法删除的 worktree 目录。`--discard-unpushed` 需要 Claude Code v2.1.260 或更高版本，而 `--force-remove-worktree` 需要 v2.1.268 或更高版本。会话记录保留在您的本地计算机上，可通过 `claude --resume` 访问 | `claude rm 7c5dcf5d` |46| `claude rm <id>` | 从列表中删除 [后台会话](https://code.claude.com/docs/zh-CN/agent-view.md#manage-sessions-from-the-shell)。当删除因 [会话的 worktree 而被拒绝](https://code.claude.com/docs/zh-CN/agent-view.md#what-deleting-a-session-removes) 且第二个 `claude rm` 可以解决它时，拒绝会打印要传递的确切标志和值：`--discard-unpushed <commit>@<worktree-id>` 丢弃具有未推送提交的 worktree 及其提交，`--force-remove-worktree <worktree-id>` 删除 git 或 `WorktreeRemove` hook 无法删除的 worktree 目录。`--discard-unpushed` 需要 Claude Code v2.1.260 或更高版本，而 `--force-remove-worktree` 需要 v2.1.268 或更高版本。会话记录保留在您的本地计算机上，可通过 `claude --resume` 访问 | `claude rm 7c5dcf5d` |

47| `claude self-hosted-runner` | 启动运行程序进程，将此计算机或容器注册到 [self-hosted environment](https://code.claude.com/docs/zh-CN/self-hosted-environments)，并在您的基础设施上托管 Claude Code 云端会话。运行 `claude self-hosted-runner setup` 以获得引导式操作员演练，运行 `claude self-hosted-runner doctor` 以 [诊断已部署的运行程序](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#troubleshooting)，运行 `claude self-hosted-runner orchestrator` 以生成 [on-demand runners](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration.md#on-demand-runners)。需要 Claude Code v2.1.224 或更高版本 | `claude self-hosted-runner setup` |47| `claude self-hosted-runner` | 启动运行程序进程，将此计算机或容器注册到 [self-hosted environment](https://code.claude.com/docs/zh-CN/self-hosted-environments)，并在您的基础设施上托管 Claude Code 云端会话。运行 `claude self-hosted-runner setup` 以获得引导式操作员演练，运行 `claude self-hosted-runner doctor` 以 [诊断已部署的运行程序](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#troubleshooting)，运行 `claude self-hosted-runner orchestrator` 以生成 [on-demand runners](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration.md#on-demand-runners)。需要 Claude Code v2.1.224 或更高版本 | `claude self-hosted-runner setup` |

111| `--no-session-persistence` | 禁用会话持久性，以便会话不保存到磁盘且无法恢复。仅限 print 模式。[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](https://code.claude.com/docs/zh-CN/env-vars) 环境变量在任何模式下执行相同操作 | `claude -p --no-session-persistence "query"` |111| `--no-session-persistence` | 禁用会话持久性，以便会话不保存到磁盘且无法恢复。仅限 print 模式。[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](https://code.claude.com/docs/zh-CN/env-vars) 环境变量在任何模式下执行相同操作 | `claude -p --no-session-persistence "query"` |

113| `--permission-mode` | 在指定的[权限模式](https://code.claude.com/docs/zh-CN/permission-modes.md)中开始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 或 `manual`（作为 `default` 的别名）。`manual` 别名选择 UI 标记为 Manual 的权限模式，需要 Claude Code v2.1.200 或更高版本；`claude --help` 列出它来代替 `default`，两个值都有效。覆盖设置文件中的 `defaultMode`。没有此标志或 `--dangerously-skip-permissions` 时，新会话以[会话以哪种权限模式启动](https://code.claude.com/docs/zh-CN/permission-modes.md#which-mode-a-session-starts-in)中描述的权限模式启动，该部分也涵盖了 `-p` 运行以何种模式启动 | `claude --permission-mode plan` |113| `--permission-mode` | 在指定的[权限模式](https://code.claude.com/docs/zh-CN/permission-modes.md)中开始。接受 `default`、`acceptEdits`、`plan`、`auto`、`dontAsk`、`bypassPermissions` 或 `manual`（作为 `default` 的别名）。`manual` 别名选择 UI 标记为 Manual 的权限模式，需要 Claude Code v2.1.200 或更高版本；`claude --help` 列出它来代替 `default`，两个值都有效。覆盖设置文件中的 `defaultMode`。没有此标志或 `--dangerously-skip-permissions` 时，新会话以[会话以哪种权限模式启动](https://code.claude.com/docs/zh-CN/permission-modes.md#which-mode-a-session-starts-in)中描述的权限模式启动，该部分也涵盖了 `-p` 运行以何种模式启动 | `claude --permission-mode plan` |

114| `--permission-prompt-tool` | 指定 MCP 工具以在非交互模式下处理权限提示。传递本次运行所加载的 MCP 服务器上某个工具的完整名称，例如 `mcp__<server>__<tool>`。Claude Code 在运行第一轮之前等待该工具的 MCP 服务器连接，最多等待 [`MCP_TIMEOUT`](https://code.claude.com/docs/zh-CN/env-vars) 启动超时时间，默认 30 秒。该提示工具无法批准标记为[需要用户交互](https://code.claude.com/docs/zh-CN/mcp.md#require-approval-for-a-specific-tool)的 MCP 工具：Claude Code 会将此类工具的 `allow` 结果转换为拒绝。此限制需要 Claude Code v2.1.199 或更高版本 | `claude -p --mcp-config ./mcp.json --permission-prompt-tool mcp__permissions__approve "query"` |114| `--permission-prompt-tool` | 指定 MCP 工具以在非交互模式下处理权限提示。传递本次运行所加载的 MCP 服务器上某个工具的完整名称，例如 `mcp__<server>__<tool>`。Claude Code 在运行第一轮之前等待该工具的 MCP 服务器连接，最多等待 [`MCP_TIMEOUT`](https://code.claude.com/docs/zh-CN/env-vars) 启动超时时间，默认 30 秒。请参阅[该工具必须返回的内容](https://code.claude.com/docs/zh-CN/errors.md#permission-prompt-tool-returned-an-invalid-result)。该提示工具无法批准标记为[需要用户交互](https://code.claude.com/docs/zh-CN/mcp.md#require-approval-for-a-specific-tool)的 MCP 工具：Claude Code 会将此类工具的 `allow` 结果转换为拒绝。此限制需要 Claude Code v2.1.199 或更高版本 | `claude -p --mcp-config ./mcp.json --permission-prompt-tool mcp__permissions__approve "query"` |

115| `--permission-prompts` | 在 print 模式下设置由谁回答权限提示。使用默认值 `host` 时，Claude Code 将它们发送到 Agent SDK 主机或 `--permission-prompt-tool` 工具。当没有人可以回答时传递 `none`，Claude Code 会改为拒绝它们。请参阅[在无人值守运行中关闭权限提示](https://code.claude.com/docs/zh-CN/headless.md#turn-off-permission-prompts-in-unattended-runs)。需要 Claude Code v2.1.259 或更高版本 | `claude -p --permission-prompts none "query"` |115| `--permission-prompts` | 在 print 模式下设置由谁回答权限提示。使用默认值 `host` 时，Claude Code 将它们发送到 Agent SDK 主机或 `--permission-prompt-tool` 工具。当没有人可以回答时传递 `none`，Claude Code 会改为拒绝它们。请参阅[在无人值守运行中关闭权限提示](https://code.claude.com/docs/zh-CN/headless.md#turn-off-permission-prompts-in-unattended-runs)。需要 Claude Code v2.1.259 或更高版本 | `claude -p --permission-prompts none "query"` |

116| `--plugin-dir` | 从目录或 `.zip` 存档加载插件，或从[插件文件夹](https://code.claude.com/docs/zh-CN/plugins/create.md#load-a-directory-or-archive-for-one-session)加载多个插件，仅用于此会话。每个标志接受一个路径。重复标志以传递更多路径：`--plugin-dir A --plugin-dir B.zip`。传递插件文件夹需要 Claude Code v2.1.265 或更高版本 | `claude --plugin-dir ./my-plugin` |116| `--plugin-dir` | 从目录或 `.zip` 存档加载插件，或从[插件文件夹](https://code.claude.com/docs/zh-CN/plugins/create.md#load-a-directory-or-archive-for-one-session)加载多个插件，仅用于此会话。每个标志接受一个路径。重复标志以传递更多路径：`--plugin-dir A --plugin-dir B.zip`。传递插件文件夹需要 Claude Code v2.1.265 或更高版本 | `claude --plugin-dir ./my-plugin` |

commands.md +1 −1

Details

162| `/ultrareview [PR or branch]` | 使用 [ultrareview](https://code.claude.com/docs/zh-CN/ultrareview.md) 在云端沙箱中运行深度多 Agent 代码审查。传递 PR 引用可审查该 Pull Request，或传递基准分支或提交以更改比较基准。首选调用方式是 `/code-review ultra`，`/ultrareview` 是其别名。Pro、Max 和 Ultra 包含 3 次免费运行，之后需要[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |162| `/ultrareview [PR or branch]` | 使用 [ultrareview](https://code.claude.com/docs/zh-CN/ultrareview.md) 在云端沙箱中运行深度多 Agent 代码审查。传递 PR 引用可审查该 Pull Request，或传递基准分支或提交以更改比较基准。首选调用方式是 `/code-review ultra`，`/ultrareview` 是其别名。Pro、Max 和 Ultra 包含 3 次免费运行，之后需要[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) |

163| `/update-config [request]` | **[Skill](https://code.claude.com/docs/zh-CN/skills.md#bundled-skills)。** 描述一项设置更改，例如允许某个命令、设置环境变量或添加 [hook](https://code.claude.com/docs/zh-CN/hooks.md)，Claude 会编辑相应的 [`settings.json`](https://code.claude.com/docs/zh-CN/settings) 文件。对于主题和模型等选项，请改用 `/config` |163| `/update-config [request]` | **[Skill](https://code.claude.com/docs/zh-CN/skills.md#bundled-skills)。** 描述一项设置更改，例如允许某个命令、设置环境变量或添加 [hook](https://code.claude.com/docs/zh-CN/hooks.md)，Claude 会编辑相应的 [`settings.json`](https://code.claude.com/docs/zh-CN/settings) 文件。对于主题和模型等选项，请改用 `/config` |

165| `/usage` | 显示会话开销、套餐用量限制和活动统计信息。在 Pro、Max、Ultra、Team 或 Enterprise 套餐上，包括[计入套餐限制的内容明细](https://code.claude.com/docs/zh-CN/costs.md#plan-usage-breakdown)。`/cost` 和 `/stats` 是其别名 |165| `/usage` | 显示会话开销、套餐用量限制和活动统计信息。在 Pro、Max、Ultra、Team 或 Enterprise 套餐上，包括[计入套餐限制的内容明细](https://code.claude.com/docs/zh-CN/costs.md#plan-usage-breakdown)。在跟踪支出的 Claude apps gateway 之后使用时，显示[您通过该网关产生的支出](https://code.claude.com/docs/zh-CN/claude-apps-gateway-spend-limits.md#usage-warnings-in-claude-code)。`/cost` 和 `/stats` 是其别名 |

166| `/usage-credits` | 在达到限制时配置使用额度，或向管理员申请使用额度。在浏览器中打开您的[使用额度计费设置](https://code.claude.com/docs/zh-CN/costs.md#add-usage-credits-to-your-subscription)；但没有计费访问权限的 Team 和 Enterprise 成员会在对话框中确认该请求会通知其管理员后，改为从 CLI 向管理员发送使用额度请求。当无法打开浏览器访问计费页面时（例如通过 SSH），该命令会改为输出要访问的 URL；这需要 Claude Code v2.1.205 或更高版本，更早版本在这种情况下不显示任何内容。以前为 `/extra-usage` |166| `/usage-credits` | 在达到限制时配置使用额度，或向管理员申请使用额度。在浏览器中打开您的[使用额度计费设置](https://code.claude.com/docs/zh-CN/costs.md#add-usage-credits-to-your-subscription)；但没有计费访问权限的 Team 和 Enterprise 成员会在对话框中确认该请求会通知其管理员后，改为从 CLI 向管理员发送使用额度请求。当无法打开浏览器访问计费页面时（例如通过 SSH），该命令会改为输出要访问的 URL；这需要 Claude Code v2.1.205 或更高版本，更早版本在这种情况下不显示任何内容。以前为 `/extra-usage` |

167| `/verify` | **[Skill](https://code.claude.com/docs/zh-CN/skills.md#bundled-skills)。** 通过构建、运行您项目的应用并观察结果来确认代码更改是否按预期工作，而不是依赖测试或类型检查。请参阅[运行并验证您的应用](https://code.claude.com/docs/zh-CN/skills.md#run-and-verify-your-app) |167| `/verify` | **[Skill](https://code.claude.com/docs/zh-CN/skills.md#bundled-skills)。** 通过构建、运行您项目的应用并观察结果来确认代码更改是否按预期工作，而不是依赖测试或类型检查。请参阅[运行并验证您的应用](https://code.claude.com/docs/zh-CN/skills.md#run-and-verify-your-app) |

168| `/vim` | 已在 v2.1.92 中移除。要在 Vim 和 Normal 编辑模式之间切换，请使用 `/config` → Editor mode |168| `/vim` | 已在 v2.1.92 中移除。要在 Vim 和 Normal 编辑模式之间切换，请使用 `/config` → Editor mode |

costs.md +1 −1

Details

236 * 如果您已启用[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，运行 `/usage-credits` 申请超出额度的用量。236 * 如果您已启用[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，运行 `/usage-credits` 申请超出额度的用量。

237 * 在 Claude Code v2.1.234 或更高版本中，[等待重置后自动继续被中断的任务](https://code.claude.com/docs/zh-CN/interactive-mode.md#wait-for-a-usage-limit-to-reset)；该部分列出了 Claude Code 何时会自行开始等待，以及开发者何时需要从 `/rate-limit-options` 中选择等待。要为您的所有设备控制 Claude Code 是否自行开始该等待，请在[托管设置](https://code.claude.com/docs/zh-CN/settings.md#settings-precedence)中设置 [`autoContinueAtUsageLimit`](https://code.claude.com/docs/zh-CN/settings-reference#autocontinueatusagelimit)。237 * 在 Claude Code v2.1.234 或更高版本中，[等待重置后自动继续被中断的任务](https://code.claude.com/docs/zh-CN/interactive-mode.md#wait-for-a-usage-limit-to-reset)；该部分列出了 Claude Code 何时会自行开始等待，以及开发者何时需要从 `/rate-limit-options` 中选择等待。要为您的所有设备控制 Claude Code 是否自行开始该等待，请在[托管设置](https://code.claude.com/docs/zh-CN/settings.md#settings-precedence)中设置 [`autoContinueAtUsageLimit`](https://code.claude.com/docs/zh-CN/settings-reference#autocontinueatusagelimit)。

238* **"You've hit your individual spend limit"、"org's monthly spend limit"或"team's shared budget"**：开发者的请求本应计入使用额度，而这些额度已达到您设置的支出限制。要让开发者继续使用，请前往 [**Organization settings > Usage**](https://claude.ai/admin-settings/usage) 并提高消息中提到的限制。如果消息中还指明了套餐重置时间，开发者也可以等到那时。各种变体请参阅[错误参考](https://code.claude.com/docs/zh-CN/errors.md#youve-hit-your-monthly-spend-limit)。238* **"You've hit your individual spend limit"、"org's monthly spend limit"或"team's shared budget"**：开发者的请求本应计入使用额度，而这些额度已达到您设置的支出限制。要让开发者继续使用，请前往 [**Organization settings > Usage**](https://claude.ai/admin-settings/usage) 并提高消息中提到的限制。如果消息中还指明了套餐重置时间，开发者也可以等到那时。各种变体请参阅[错误参考](https://code.claude.com/docs/zh-CN/errors.md#youve-hit-your-monthly-spend-limit)。

239* **来自 [Claude apps gateway](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 的支出限制消息**：开发者超出了您在自托管网关上设置的支出上限，网关会阻止其请求，直到周期重置或您提高上限。有关上限、重置计划以及开发者看到的消息，请参阅[网关支出限制](https://code.claude.com/docs/zh-CN/claude-apps-gateway-spend-limits.md)。239* **来自 [Claude apps gateway](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 的支出限制消息**：开发者超出了您在自托管网关上设置的支出上限。网关会阻止其请求，直到您提高上限；如果上限高于 \$0，也会在上限重置后解除阻止。有关上限、重置计划以及开发者看到的消息，请参阅[网关支出限制](https://code.claude.com/docs/zh-CN/claude-apps-gateway-spend-limits.md)。

240* **上下文或自动压缩警告**：这不是用量限制。对话已接近会话的[自动压缩窗口](https://code.claude.com/docs/zh-CN/model-config.md#set-the-auto-compact-window)，即 Claude Code 汇总较早历史记录以释放空间的阈值。请引导开发者参阅[减少 token 用量](#reduce-token-usage)。240* **上下文或自动压缩警告**：这不是用量限制。对话已接近会话的[自动压缩窗口](https://code.claude.com/docs/zh-CN/model-config.md#set-the-auto-compact-window)，即 Claude Code 汇总较早历史记录以释放空间的阈值。请引导开发者参阅[减少 token 用量](#reduce-token-usage)。

241* **API 或云服务提供商套餐上的意外高额支出**：通常源于从未清除的长会话，或将 Opus 保留为默认模型。最值得分享的高影响习惯是在不相关的任务之间进行清除，以及根据工作选择合适的模型，这两点都在[减少 token 用量](#reduce-token-usage)中有介绍。241* **API 或云服务提供商套餐上的意外高额支出**：通常源于从未清除的长会话，或将 Opus 保留为默认模型。最值得分享的高影响习惯是在不相关的任务之间进行清除，以及根据工作选择合适的模型，这两点都在[减少 token 用量](#reduce-token-usage)中有介绍。

242 242

env-vars.md +2 −1

Details

365| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 设置为 `5m` 或 `1h`（Claude Code 仅接受这两个值），以选择主对话的[提示缓存 TTL](https://code.claude.com/docs/zh-CN/prompt-caching.md#cache-lifetime)：包括您的交互式、`-p` 和 SDK 轮次，以及与它们内联运行的辅助程序。优先于 `promptCacheTtl` 设置和 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 会覆盖它。API 对 1 小时缓存写入按更高费率计费。需要 Claude Code v2.1.242 或更高版本 |365| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 设置为 `5m` 或 `1h`（Claude Code 仅接受这两个值），以选择主对话的[提示缓存 TTL](https://code.claude.com/docs/zh-CN/prompt-caching.md#cache-lifetime)：包括您的交互式、`-p` 和 SDK 轮次，以及与它们内联运行的辅助程序。优先于 `promptCacheTtl` 设置和 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 会覆盖它。API 对 1 小时缓存写入按更高费率计费。需要 Claude Code v2.1.242 或更高版本 |

366| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 设置为 `1` 可在 `ANTHROPIC_BASE_URL` 指向自定义代理时传播 W3C 跟踪上下文。传播范围包括模型和 HTTP MCP 请求上的 `traceparent` 标头，以及 Bash、PowerShell 和 hook 子进程的 `TRACEPARENT` 环境变量。默认情况下，仅在直接连接到 Anthropic API 时才启用传播。在 v2.1.152 中添加。请参阅[跟踪（beta）](https://code.claude.com/docs/zh-CN/monitoring-usage.md#traces-beta) |366| `CLAUDE_CODE_PROPAGATE_TRACEPARENT` | 设置为 `1` 可在 `ANTHROPIC_BASE_URL` 指向自定义代理时传播 W3C 跟踪上下文。传播范围包括模型和 HTTP MCP 请求上的 `traceparent` 标头，以及 Bash、PowerShell 和 hook 子进程的 `TRACEPARENT` 环境变量。默认情况下，仅在直接连接到 Anthropic API 时才启用传播。在 v2.1.152 中添加。请参阅[跟踪（beta）](https://code.claude.com/docs/zh-CN/monitoring-usage.md#traces-beta) |

367| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 并代为管理模型提供商路由的宿主平台设置。设置后，Claude Code 会忽略设置文件中的提供商选择、端点和身份验证变量，例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`，因此用户设置无法覆盖宿主的路由。Claude Code 还会忽略[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)中的模型选择键，例如 `model`、`fallbackModel` 和 `modelOverrides`，无论它们由哪个托管来源下发，因此宿主的模型配置优先于过时的托管模型固定设置。Claude Code 还会忽略托管 `env` 块中的模型选择变量，例如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列；托管设置中的 [`availableModels`](https://code.claude.com/docs/zh-CN/model-config#restrict-model-selection) 允许列表仍然适用，除非宿主提供了自己的允许列表。Claude Code 还会跳过它在第三方提供商（例如 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 和 Microsoft Foundry）上原本会应用的自动遥测退出，因此遥测遵循标准的 `DISABLE_TELEMETRY` 退出方式。请参阅[按 API 提供商划分的默认行为](https://code.claude.com/docs/zh-CN/data-usage.md#default-behaviors-by-api-provider) |367| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 并代为管理模型提供商路由的宿主平台设置。设置后，Claude Code 会忽略设置文件中的提供商选择、端点和身份验证变量，例如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`，因此用户设置无法覆盖宿主的路由。Claude Code 还会忽略[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)中的模型选择键，例如 `model`、`fallbackModel` 和 `modelOverrides`，无论它们由哪个托管来源下发，因此宿主的模型配置优先于过时的托管模型固定设置。Claude Code 还会忽略托管 `env` 块中的模型选择变量，例如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列；托管设置中的 [`availableModels`](https://code.claude.com/docs/zh-CN/model-config#restrict-model-selection) 允许列表仍然适用，除非宿主提供了自己的允许列表。Claude Code 还会跳过它在第三方提供商（例如 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 和 Microsoft Foundry）上原本会应用的自动遥测退出，因此遥测遵循标准的 `DISABLE_TELEMETRY` 退出方式。请参阅[按 API 提供商划分的默认行为](https://code.claude.com/docs/zh-CN/data-usage.md#default-behaviors-by-api-provider) |

368| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 设置为 `1` 可允许由代理而非调用方执行 DNS 解析。适用于应由代理处理主机名解析的环境，需主动启用 |368| `CLAUDE_CODE_PROXY_RESOLVES_HOSTS` | 设置为 `1`，允许由代理而非调用方执行 DNS 解析。适用于应由代理处理主机名解析的环境，需主动选择启用。设置了 `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` 时，请在启动 Claude Code 的进程的环境中设置此变量 |

369| `CLAUDE_CODE_REMOTE` | 当 Claude Code 作为[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)运行时自动设置为 `true`。可在 hook 或环境设置脚本中读取此变量，以检测是否处于云端会话中 |369| `CLAUDE_CODE_REMOTE` | 当 Claude Code 作为[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)运行时自动设置为 `true`。可在 hook 或环境设置脚本中读取此变量，以检测是否处于云端会话中 |

370| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)中自动设置为当前会话的 ID。读取此变量可构造返回会话记录的链接。请参阅[将输出链接回会话](https://code.claude.com/docs/zh-CN/cloud-environments.md#link-output-back-to-the-session) |370| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)中自动设置为当前会话的 ID。读取此变量可构造返回会话记录的链接。请参阅[将输出链接回会话](https://code.claude.com/docs/zh-CN/cloud-environments.md#link-output-back-to-the-session) |

371| `CLAUDE_CODE_RESTRICTED` | 设置为 `1` 可在受限模式下启动会话，与传递 [`--restricted`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 相同。Claude Code 会忽略设置文件 `env` 块中的此变量。需要 Claude Code v2.1.248 或更高版本 |371| `CLAUDE_CODE_RESTRICTED` | 设置为 `1` 可在受限模式下启动会话，与传递 [`--restricted`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 相同。Claude Code 会忽略设置文件 `env` 块中的此变量。需要 Claude Code v2.1.248 或更高版本 |

532| `VERTEX_REGION_CLAUDE_FABLE_5_2` | 使用 Google Cloud's Agent Platform 时覆盖 Claude Fable 5.2 的区域。在 v2.1.321 中添加 |

534 535

errors.md +93 −16

Details

52| `Credit balance is too low` | [使用限制](#credit-balance-is-too-low) |52| `Credit balance is too low` | [使用限制](#credit-balance-is-too-low) |

53| `You've hit your monthly spend limit` / `You've hit your individual spend limit` / `You've hit your org's monthly spend limit` / `You've hit your channel's monthly spend limit` / `You've hit your team's shared budget` / `You've hit your individual usage limit` | [使用限制](#youve-hit-your-monthly-spend-limit) |53| `You've hit your monthly spend limit` / `You've hit your individual spend limit` / `You've hit your org's monthly spend limit` / `You've hit your channel's monthly spend limit` / `You've hit your team's shared budget` / `You've hit your individual usage limit` | [使用限制](#youve-hit-your-monthly-spend-limit) |

54| `Could not update your spend limit` | [使用限制](#could-not-update-your-spend-limit) |54| `Could not update your spend limit` | [使用限制](#could-not-update-your-spend-limit) |

56| `Not logged in · Please run /login` | [身份验证](#not-logged-in) |56| `Not logged in · Please run /login` | [身份验证](#not-logged-in) |

57| `Couldn't save your login` | [身份验证](#couldnt-save-your-login) |57| `Couldn't save your login` | [身份验证](#couldnt-save-your-login) |

58| `Sign in again to take your previous account or API key off the config file.` | [身份验证](#sign-in-again-to-take-your-previous-account-or-api-key-off-the-config-file) |58| `Sign in again to take your previous account or API key off the config file.` | [身份验证](#sign-in-again-to-take-your-previous-account-or-api-key-off-the-config-file) |

336| `MCP server "<name>" connection closed before the tool call was answered` | [工具错误](#connection-closed-before-the-tool-call-was-answered) |336| `MCP server "<name>" connection closed before the tool call was answered` | [工具错误](#connection-closed-before-the-tool-call-was-answered) |

338| `MCP server "<name>" tool "<tool>" timed out after <N>s. The server asked the user a question, and no answer came before the time limit.` | [工具错误](#mcp-tool-call-timed-out-with-the-servers-question-unanswered) |338| `MCP server "<name>" tool "<tool>" timed out after <N>s. The server asked the user a question, and no answer came before the time limit.` | [工具错误](#mcp-tool-call-timed-out-with-the-servers-question-unanswered) |

339| `Permission prompt tool returned an invalid result` | [工具错误](#permission-prompt-tool-returned-an-invalid-result) |

341| `<path> is outside <dirs>; the permissions.blockWritesOutsideWorkingDirectories setting blocks writes outside the working directories` | [工具错误](#setting-blocks-writes-outside-the-working-directories) |342| `<path> is outside <dirs>; the permissions.blockWritesOutsideWorkingDirectories setting blocks writes outside the working directories` | [工具错误](#setting-blocks-writes-outside-the-working-directories) |

420| `The Claude Code program for this computer, the <build> build, could not be found` | [包装器和 IDE 错误](#the-claude-code-program-for-this-computer-could-not-be-found) |421| `The Claude Code program for this computer, the <build> build, could not be found` | [包装器和 IDE 错误](#the-claude-code-program-for-this-computer-could-not-be-found) |

422| `No files were restored: N files failed (backup missing, or the file could not be updated)` | [Rewind 警告和错误](#no-files-were-restored) |423| `No files were restored: N files failed (backup missing, or the file could not be updated)` | [Rewind 警告和错误](#no-files-were-restored) |

424| `The file backups are still being copied. Nothing was changed. Try again in a moment.` | 在 [`/rewind`](https://code.claude.com/docs/zh-CN/checkpointing) 中再次选择同一个点。如果您在 [`/branch`](https://code.claude.com/docs/zh-CN/sessions#branch-a-session) 之后不久恢复代码，Claude Code 可能仍在将文件备份复制到新会话。 |

424| `Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set` | [会话保存警告](#transcript-saving-is-off-skip-prompt-history) |426| `Transcript saving is off — CLAUDE_CODE_SKIP_PROMPT_HISTORY is set` | [会话保存警告](#transcript-saving-is-off-skip-prompt-history) |

425| `Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker` | [会话保存警告](#transcript-saving-is-off-child-session-marker) |427| `Transcript saving is off — inherited CLAUDE_CODE_CHILD_SESSION marker` | [会话保存警告](#transcript-saving-is-off-child-session-marker) |

431| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [配置警告](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |433| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [配置警告](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |

432| `N skill or command names refused: run with --debug to see which ([names]), rename, then restart` | [配置警告](#skill-or-command-name-refused) |434| `N skill or command names refused: run with --debug to see which ([names]), rename, then restart` | [配置警告](#skill-or-command-name-refused) |

433| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [配置警告](#workspace-has-not-been-trusted) |435| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [配置警告](#workspace-has-not-been-trusted) |

436| `Two Claude Code config files exist: this run uses <path>, not <path>` | [配置警告](#two-claude-code-config-files-exist) |

434| `Make this change again later: <path> could not be updated, so it applies to this session only` | [配置警告](#make-this-change-again-later) |437| `Make this change again later: <path> could not be updated, so it applies to this session only` | [配置警告](#make-this-change-again-later) |

468| `CLAUDE_CODE_AUTO_COMPACT_WINDOW="<value>" isn't a usable size, so Claude Code ignores it` | [`CLAUDE_CODE_AUTO_COMPACT_WINDOW` 的值和警告](https://code.claude.com/docs/zh-CN/model-config#claude_code_auto_compact_window-values) |471| `CLAUDE_CODE_AUTO_COMPACT_WINDOW="<value>" isn't a usable size, so Claude Code ignores it` | [`CLAUDE_CODE_AUTO_COMPACT_WINDOW` 的值和警告](https://code.claude.com/docs/zh-CN/model-config#claude_code_auto_compact_window-values) |

469| `Model "<model>" isn't recognized · context assumed to be 200k tokens` | [更正网关或自定义模型 ID 的窗口](https://code.claude.com/docs/zh-CN/model-config.md#correct-the-window-for-a-gateway-or-custom-model-id) |472| `Model "<model>" isn't recognized · context assumed to be 200k tokens` | [更正网关或自定义模型 ID 的窗口](https://code.claude.com/docs/zh-CN/model-config.md#correct-the-window-for-a-gateway-or-custom-model-id) |

470| `Claude Code doesn't recognize the model "<model>", so it assumes a context window of 200k tokens` | [更正网关或自定义模型 ID 的窗口](https://code.claude.com/docs/zh-CN/model-config.md#correct-the-window-for-a-gateway-or-custom-model-id) |473| `Claude Code doesn't recognize the model "<model>", so it assumes a context window of 200k tokens` | [更正网关或自定义模型 ID 的窗口](https://code.claude.com/docs/zh-CN/model-config.md#correct-the-window-for-a-gateway-or-custom-model-id) |

474| `Model "<model>" isn't recognized · did you mean "<suggestion>"?` / `Claude Code doesn't recognize the model "<model>". Did you mean "<suggestion>"?` | [修正拼写错误的模型名称](https://code.claude.com/docs/zh-CN/model-config.md#fix-a-mistyped-model-name) |

472| `is ignored — managed settings set allowManagedReadPathsOnly` / `is ignored — managed settings set allowManagedDomainsOnly` | [配置警告](#sandbox-allow-entries-are-ignored-under-a-managed-lock) |476| `is ignored — managed settings set allowManagedReadPathsOnly` / `is ignored — managed settings set allowManagedDomainsOnly` | [配置警告](#sandbox-allow-entries-are-ignored-under-a-managed-lock) |

909Fable 5.1 now uses usage credits · the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change913Fable 5.1 now uses usage credits · the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change

910```914```

911 915

912消息命名会话的 Fable 模型，因此在 Fable 5 上它们读作 `continuing on Fable 5` 和 `Fable 5 now uses usage credits`。在 v2.1.257 之前，第一条消息以 `Fable 5 limit reached` 开头。916消息命名会话的 Fable 模型，因此在 Fable 5.2 上它们读作 `continuing on Fable 5.2` 和 `Fable 5.2 now uses usage credits`。在 v2.1.257 之前，第一条消息以 `Fable 5 limit reached` 开头。

913 917

914这发生在 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 会话、[background sessions](https://code.claude.com/docs/zh-CN/agent-view.md)、[agent team](https://code.claude.com/docs/zh-CN/agent-teams.md) 队友会话以及另一个应用程序通过 Agent SDK 托管的会话中。有关 Claude Code 何时关闭提示，请参阅 [Fable and usage credits](https://code.claude.com/docs/zh-CN/model-config.md#fable-and-usage-credits)。918这发生在 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 会话、[background sessions](https://code.claude.com/docs/zh-CN/agent-view.md)、[agent team](https://code.claude.com/docs/zh-CN/agent-teams.md) 队友会话以及另一个应用程序通过 Agent SDK 托管的会话中。有关 Claude Code 何时关闭提示，请参阅 [Fable and usage credits](https://code.claude.com/docs/zh-CN/model-config.md#fable-and-usage-credits)。

915 919

983 987

984### Spend limit reached988### Spend limit reached

985 989

986您通过 [Claude apps gateway](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 连接，并已超过您的网关操作员设置的 [spend cap](https://code.claude.com/docs/zh-CN/claude-apps-gateway-spend-limits.md)。网关阻止您的请求，直到命名的期间重置或操作员提高上限。它将每个被阻止的 `429` 响应标记为 `x-should-retry: false`，因此 Claude Code 显示此消息而不重试。990您通过 [Claude apps gateway](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 连接，并已达到您的网关操作员设置的 [spend cap](https://code.claude.com/docs/zh-CN/claude-apps-gateway-spend-limits.md)。网关会阻止您的请求，直到操作员提高上限，或者在上限高于 \$0 时直到上限重置。它将每个被阻止的 `429` 响应标记为 `x-should-retry: false`，因此在终端中 Claude Code 会显示此消息而不重试。

987 991

988```text theme={null}992```text theme={null}

989spend limit reached (daily; resets 2026-08-09 00:00 UTC)993spend limit reached · resets Dec 1

990```994```

991 995

992消息命名上限的期间和重置时间，当操作员配置了 `blocked_message` 时，他们的说明跟在它后面。在 v2.1.225 之前，消息仅读作 `spend limit reached`；较旧版本上的网关仍然发送该较短的形式。996检查消息中是否有日期：

997

998* **带有日期**：上限会在该日期的 00:00 UTC 重置

999* **没有日期**：您的上限为 \$0，或您的网关运行的版本早于 v2.1.225

1000

1001消息中的任何其他文本都是您的网关操作员的说明。

1002

1003在网关服务器上从 v2.1.225 到 v2.1.319 期间，消息会命名上限的期间和重置时间，如 `spend limit reached (daily; resets 2026-08-09 00:00 UTC)`。

993 1004

994**要做什么：**1005**要做什么：**

995 1006

996* 等待消息命名的重置时间，或如果消息包含说明，请遵循操作员的说明1007* 如果消息带有日期，请等待重置，或如果消息包含操作员的说明，请遵循该说明

997* 如果您经常达到上限，要求您的网关操作员提高上限1008* 如果消息没有日期、日期过后您仍被阻止，或您经常达到上限，请要求您的网关操作员提高上限

1009

1010另一条网关消息 `This request exceeds your group's budget` 表示您所在组的 [pooled budget](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config.md#pooled-budget-order) 已用完。请按照其中列出的步骤操作：

1011

1012```text theme={null}

1013This request exceeds your group's budget. Ask your organization's admins to raise it, or try again after it resets on November 1 at 00:00 UTC.

1014```

998 1015

999一条相关消息 `spend limit unavailable` 意味着网关无法读取其支出记录，并作为预防措施而不是超过您的上限而阻止了请求。它通常会自行清除；如果它持续存在，请告诉您的网关操作员。1016一条相关消息 `spend limit unavailable` 意味着网关无法读取其支出记录，并作为预防措施而不是超过您的上限而阻止了请求。它通常会自行清除；如果它持续存在，请告诉您的网关操作员。

1000 1017

2287 2304

2288### Couldn't send feedback2305### Couldn't send feedback

2289 2306

2290以 `Couldn't send feedback` 开头的消息表示反馈服务未确认收到您从 [`/feedback`、`/bug` 或 `/share` 对话框](https://code.claude.com/docs/zh-CN/commands#all-commands)提交的报告，或者已排队的[反馈草稿](https://code.claude.com/docs/zh-CN/tools-reference.md#sendfeedback-tool-behavior)。请将其视为未收到。如果冒号之后是一句关于您组织的说明，则表示您的组织拒绝接收反馈，同一份报告再次发送也会得到相同的结果。2307以 `Couldn't send feedback` 开头的消息表示反馈服务未确认收到您从 [`/feedback`、`/bug` 或 `/share` 对话框](https://code.claude.com/docs/zh-CN/commands#all-commands)提交的报告，或者已排队的[反馈草稿](https://code.claude.com/docs/zh-CN/tools-reference.md#sendfeedback-tool-behavior)。请将其视为未收到。如果冒号之后是一句关于您组织的说明，则表示您的组织拒绝接收反馈。

2291 2308

2292以下两个示例中，第二个是组织拒绝：2309第二个示例是组织的拒绝：

2293 2310

2294```text wrap theme={null}2311```text wrap theme={null}

2295Couldn't send feedback (couldn't reach the service). If it keeps failing, you can file at https://github.com/anthropics/claude-code/issues instead.2312Couldn't send feedback (couldn't reach the service). If it keeps failing, you can file at https://github.com/anthropics/claude-code/issues instead.

2300**解决方法：**2317**解决方法：**

2301 2318

2302* **未登录**：消息后续为 `: not signed in. Run /login, then retry.`。请运行 `/login`，然后再次发送2319* **未登录**：消息后续为 `: not signed in. Run /login, then retry.`。请运行 `/login`，然后再次发送

2303* **您的组织拒绝**：例如 `: Feedback has not been enabled for your organization.` 或 `: Feedback collection is not available for organizations with custom data retention policies.`。如果消息附有 `To report a bug, open an issue`，请在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 提交 issue。已排队的草稿会保留在队列中，您可以[将其丢弃](https://code.claude.com/docs/zh-CN/tools-reference.md#discard-or-keep-a-draft)2320* **您的组织拒绝**：例如 `: Feedback has not been enabled for your organization.` 或 `: Feedback collection is not available for organizations with custom data retention policies.`。如果消息附有 `To report a bug, open an issue`，请在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 提交 issue。之后在七天内，`/feedback` 可能会提示它已[被您组织的策略禁用](#feedback-is-disabled-by-your-organizations-policy)。已排队的草稿会保留在队列中，并仍会[按计划过期](https://code.claude.com/docs/zh-CN/tools-reference.md#discard-or-keep-a-draft)

2304* **凭据被拒绝**：消息后续为 `: the sign-in this session uses is not allowed to send feedback` 或 `: the server did not accept the credentials this session uses`。请在 Claude Code 提示符处运行 `/status`，查看此会话发送的是哪个登录、令牌或 API 密钥2321* **凭据被拒绝**：消息后续为 `: the sign-in this session uses is not allowed to send feedback` 或 `: the server did not accept the credentials this session uses`。请在 Claude Code 提示符处运行 `/status`，查看此会话发送的是哪个登录、令牌或 API 密钥

2305* **紧跟在 `Couldn't send feedback` 之后的 `(request timed out)` 或 `(couldn't reach the service)`**：请再次发送报告或已排队的草稿。对话框会保留您的文本，已排队草稿的消息会显示 `The draft is still queued.`。如果其他请求也在失败，请检查您的网络连接，并参阅 [Unable to connect to API](#unable-to-connect-to-api)。如果持续失败，请在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 提交报告2322* **紧跟在 `Couldn't send feedback` 之后的 `(request timed out)` 或 `(couldn't reach the service)`**：请再次发送报告或已排队的草稿。对话框会保留您的文本，已排队草稿的消息会显示 `The draft is still queued.`。如果其他请求也在失败，请检查您的网络连接，并参阅 [Unable to connect to API](#unable-to-connect-to-api)。如果持续失败，请在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 提交报告

2306* **紧跟在 `Couldn't send feedback` 之后的 `(server returned <status>)`，或没有任何原因**：该状态码是服务的响应代码。如果服务发送了自己的消息，该消息会跟在状态码之后，例如 `(server returned 403: Access Forbidden)`。如果持续失败，请在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 提交报告2323* **紧跟在 `Couldn't send feedback` 之后的 `(server returned <status>)`，或没有任何原因**：该状态码是服务的响应代码。如果服务发送了自己的消息，该消息会跟在状态码之后，例如 `(server returned 403: Access Forbidden)`。如果持续失败，请在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 提交报告

3431* **`Error: Workspace not trusted. <folder> is your home directory`**：由于主目录的信任从不保存，先在那里运行 `claude` 也无济于事。请改为在项目目录中运行 `claude ultrareview`（先在那里运行一次 `claude` 以接受信任对话框），或追加 `--trust-workspace`。3448* **`Error: Workspace not trusted. <folder> is your home directory`**：由于主目录的信任从不保存，先在那里运行 `claude` 也无济于事。请改为在项目目录中运行 `claude ultrareview`（先在那里运行一次 `claude` 以接受信任对话框），或追加 `--trust-workspace`。

3432* **`No answer in time.` 后跟 `Error: Workspace not trusted`**：`Trust <folder>? [y/N]` 问题在 5 分钟内未得到回答。再次运行 `claude ultrareview` 并回答该问题。3449* **`No answer in time.` 后跟 `Error: Workspace not trusted`**：`Trust <folder>? [y/N]` 问题在 5 分钟内未得到回答。再次运行 `claude ultrareview` 并回答该问题。

3433* **`Ultrareview did not start: <folder> is not trusted`**：您在 `Trust <folder>? [y/N]` 问题处拒绝了，例如回答 `n` 或按 Enter。若要开始审查，请再次运行 `claude ultrareview` 并回答 `y`。3450* **`Ultrareview did not start: <folder> is not trusted`**：您在 `Trust <folder>? [y/N]` 问题处拒绝了，例如回答 `n` 或按 Enter。若要开始审查，请再次运行 `claude ultrareview` 并回答 `y`。

3434* **``Ultrareview did not start: `--trust-workspace` takes no value``**：`--trust-workspace` 后面跟了非标志的内容，例如 PR 编号或 `false`。如果您不信任该文件夹，请去掉该标志。要在本次运行中信任它，请将 PR 编号或基准分支放在该标志之前：`claude ultrareview 1234 --trust-workspace`。3451* **``Ultrareview did not start: `--trust-workspace` takes no value``**：`--trust-workspace` 后面跟着的不是标志，例如 PR 编号或 `false`。如果您不信任该文件夹，请不要使用该标志。要在本次运行中信任它，请将 PR 编号或基础分支放在该标志之前：`claude ultrareview 1234 --trust-workspace`。

3435 3452

3436在 v2.1.309 之前，`claude ultrareview` 不接受 `--trust-workspace`。3453在 v2.1.309 之前，`claude ultrareview` 不接受 `--trust-workspace`。

3437 3454

3724 3741

3725以下相关消息会在命令运行之前就出现：3742以下相关消息会在命令运行之前就出现：

3726 3743

3727* `Shell command permission check failed for pattern "..."`：该命令的权限检查未允许它运行。[注入命令的权限检查](https://code.claude.com/docs/zh-CN/skills.md#permission-checks-on-injected-commands)介绍了在每种权限模式下哪些结果会导致中止，以及如何使用 `allowed-tools` 预先批准命令3744* `Shell command permission check failed for pattern "..."`：该命令的权限检查未允许它。[注入命令的权限检查](https://code.claude.com/docs/zh-CN/skills.md#permission-checks-on-injected-commands)介绍了在每种权限模式下哪些结果会导致中止，以及如何使用 `allowed-tools` 预先批准命令

3728* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``：该 skill 的 frontmatter 要求 bash，但机器上没有 bash。请安装 Git for Windows，或将 frontmatter 改为 `shell: powershell`。请参阅[注入命令如何运行](https://code.claude.com/docs/zh-CN/skills.md#how-injected-commands-run)3745* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``：该 skill 的 frontmatter 要求使用 bash，但机器上没有 bash。请安装 Git for Windows，或将 frontmatter 改为 `shell: powershell`。请参阅[注入命令的运行方式](https://code.claude.com/docs/zh-CN/skills.md#how-injected-commands-run)

3729 3746

3730**解决方法：**3747**解决方法：**

3731 3748

3878 3895

3879* **您没有传入基础分支**：Claude Code 与仓库的默认分支进行了比较，并建议您显式传入基础分支，如上例所示3896* **您没有传入基础分支**：Claude Code 与仓库的默认分支进行了比较，并建议您显式传入基础分支，如上例所示

3880* **您传入的基础分支已存在于您的克隆中**：提示为 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``3897* **您传入的基础分支已存在于您的克隆中**：提示为 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``

3881* **您传入的基础分支不在您的克隆中**：Claude Code 在比较前已从 origin 获取该分支。提示内容为 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``；当 Claude Code 无法判断您的克隆是否为浅克隆时，它会改为建议 `git fetch --unshallow origin`。在 v2.1.221 之前，对于每个获取的基础分支，提示都会建议 `git fetch --unshallow origin`，而在完整克隆上，该命令会失败并显示 `fatal: --unshallow on a complete repository does not make sense`。3898* **您传入的基础分支不在克隆中**：Claude Code 在比较之前从 origin 获取了该分支。提示内容为 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``；当 Claude Code 无法判断您的克隆是否为浅克隆时，它会改为建议运行 `git fetch --unshallow origin`。在 v2.1.221 之前，对于每个获取的基础分支，提示都会建议运行 `git fetch --unshallow origin`，而在完整克隆上该命令会失败并显示 `fatal: --unshallow on a complete repository does not make sense`。

3882 3899

3883**解决方法：**3900**解决方法：**

3884 3901

4227 4244

4228### /feedback is disabled by your organization's policy4245### /feedback is disabled by your organization's policy

4229 4246

4230此消息表示您组织的策略不允许从 Claude Code 提交产品反馈，因此 `/feedback`、`/bug` 和 `/share` 不会打开反馈对话框。该消息会指明您在 Claude Code 提示符处输入的命令：4247此消息表示产品反馈已关闭，因此您输入的命令不会打开反馈对话框。组织策略和之前的拒绝都会产生此消息：

4248

4249* **组织策略**：您组织的策略不允许从 Claude Code 提交产品反馈。`/feedback`、`/bug` 和 `/share` 都会以此消息回应。

4250* **之前的拒绝**：反馈服务拒绝了您发送的报告，例如显示 [`Couldn't send feedback: Feedback has not been enabled for your organization.`](#couldnt-send-feedback)。此后 `/feedback` 和 `/bug` 可能会以此消息回应。该状态在本机上从该次拒绝起持续七天。这适用于所有套餐，包括 Pro 和 Max。

4251

4252该消息会指出您在 Claude Code 提示符处输入的命令：

4231 4253

4232```text wrap theme={null}4254```text wrap theme={null}

4233/feedback is disabled by your organization's policy. To report a bug, open an issue at https://github.com/anthropics/claude-code/issues. Issues are public, so leave out anything confidential.4255/feedback is disabled by your organization's policy. To report a bug, open an issue at https://github.com/anthropics/claude-code/issues. Issues are public, so leave out anything confidential.

4238**解决方法：**4260**解决方法：**

4239 4261

4240* 如需报告 bug，请在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 提交 issue。那里的 issue 任何人都可以阅读，因此请勿包含代码、会话记录以及任何其他机密内容。4262* 如需报告 bug，请在 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues) 提交 issue。那里的 issue 任何人都可以阅读，因此请勿包含代码、会话记录以及任何其他机密内容。

4263* 如果是之前的拒绝导致的，请等待七天后再次发送报告，看服务是否仍然拒绝

4264

4265在 v2.1.319 之前，之前的拒绝不会产生此消息。

4241 4266

4242在 v2.1.302 之前，完整消息为 `/feedback is disabled by your organization's policy. Contact your organization admin to enable it.`4267在 v2.1.302 之前，完整消息为 `/feedback is disabled by your organization's policy. Contact your organization admin to enable it.`

4243 4268

4654* 如需给回答留出更多时间，请在该服务器的配置条目中设置更长的 [`timeout`](https://code.claude.com/docs/zh-CN/mcp#time-limits-on-mcp-tool-calls)（以毫秒为单位），例如 `"timeout": 600000` 表示 10 分钟4679* 如需给回答留出更多时间，请在该服务器的配置条目中设置更长的 [`timeout`](https://code.claude.com/docs/zh-CN/mcp#time-limits-on-mcp-tool-calls)（以毫秒为单位），例如 `"timeout": 600000` 表示 10 分钟

4655* 改为在交互式会话中运行该任务，并自行回答服务器的[对话框](https://code.claude.com/docs/zh-CN/mcp.md#respond-to-mcp-elicitation-requests)4680* 改为在交互式会话中运行该任务，并自行回答服务器的[对话框](https://code.claude.com/docs/zh-CN/mcp.md#respond-to-mcp-elicitation-requests)

4656 4681

4682### Permission prompt tool returned an invalid result

4683

4684您传给 [`--permission-prompt-tool`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 的工具返回了一个 Claude Code 无法读取的应答，因此等待该应答的工具调用没有运行，即使该应答允许了该调用：

4685

4686```text wrap theme={null}

4687Permission prompt tool returned an invalid result. Expected a single text block param with type="text" and a string text value.

4688```

4689

4690**处理方法：**

4691

4692* 返回一个文本块，其文本为 `{"behavior": "allow"}` 或 `{"behavior": "deny", "message": "<reason>"}`。如需更改输入，请在 `allow` 对象中添加 `updatedInput`。从 v2.1.86 到 v2.1.206，`allow` 需要 `"updatedInput": {}` 才能保留输入。

4693* 不要返回 [`structuredContent`](https://code.claude.com/docs/zh-CN/agent-sdk/custom-tools#return-structured-data)，您的 MCP SDK 可能会自行添加它。例如，按以下方式注册该工具：

4694 * **来自 `mcp.server` 的 `FastMCP` 或 `MCPServer`**：使用 `structured_output=False`

4695 * **来自 `fastmcp` 的 `FastMCP`**：使用 `output_schema=None`，并返回字符串

4696 * **MCP TypeScript SDK**：不使用 `outputSchema`

4697* 如果该错误只在输入约为 40 KB 或更大时出现，请不要将输入复制到 `updatedInput` 或拒绝的 `message` 中。如需更改这么大的输入，请[提高您的提示工具的输出限制](https://code.claude.com/docs/zh-CN/mcp.md#raise-the-limit-for-a-specific-tool)。

4698

4657### Agent would be spawned with zero tools4699### Agent would be spawned with zero tools

4658 4700

4659子代理 [`tools` 列表](https://code.claude.com/docs/zh-CN/sub-agents#supported-frontmatter-fields)中的每个条目都未能匹配到可用工具，因此 Claude Code 拒绝启动该子代理：没有任何工具，它无法执行操作。该消息按问题类型对您的条目进行分组：4701子代理 [`tools` 列表](https://code.claude.com/docs/zh-CN/sub-agents#supported-frontmatter-fields)中的每个条目都未能匹配到可用工具，因此 Claude Code 拒绝启动该子代理：没有任何工具，它无法执行操作。该消息按问题类型对您的条目进行分组：

6432 6474

6433在 v2.1.257 之前，`claude doctor` 不会标记这些文件；当会话被终止时，更早的版本也会留下相同的占位文件。6475在 v2.1.257 之前，`claude doctor` 不会标记这些文件；当会话被终止时，更早的版本也会留下相同的占位文件。

6434 6476

6477### Two Claude Code config files exist

6478

6479Claude Code 正在使用此消息列出的第一个文件，因此第二个文件中的内容不会生效。第一个文件是 `.config.json`，即 [`.claude.json`](https://code.claude.com/docs/zh-CN/claude-directory#ce-claude-json) 的旧名称。消息中包含一项检查，用于确定哪个文件保存了您的配置：

6480

6481```text wrap theme={null}

6482Two Claude Code config files exist: this run uses /home/you/.claude/.config.json, not /home/you/.claude.json. The file with the higher count here is usually yours, and this prints nothing else from them: grep -c -E '"(hasCompletedOnboarding|mcpServers)"' "/home/you/.claude/.config.json" "/home/you/.claude.json". To end this: if several hosts share this home, first get every host to version 2.1.319 or later, since an older one can write a moved .config.json back. Then stop your Claude processes on every host, move aside the one you do not want, and start none until no host lists it.

6483```

6484

6485在 Windows 上，`The one with hasCompletedOnboarding or mcpServers in it is usually yours.` 会替换包含 `grep` 命令的那句话。

6486

6487**解决方法：**

6488

6489**1. 找到保存您配置的文件**

6490

6491* **在 Windows 上**：打开两个文件，查看哪个文件中包含 `hasCompletedOnboarding` 或 `mcpServers`

6492* **在其他平台上**：在 shell 中运行消息中的 `grep` 命令，查看哪个文件的计数更高

6493

6494**2. 更新共享该主目录的每台主机**

6495

6496如果多台主机共享此主目录，请先将每台主机上的 Claude Code 更新到消息中指出的版本或更高版本。旧版本可能会将已移走的 `.config.json` 写回。

6497

6498**3. 停止 Claude Code**

6499

6500停止每台主机上的 Claude Code 进程。

6501

6502**4. 移走您不需要的文件**

6503

6504将您不需要的文件移出其所在文件夹。请移动而不是删除它，以便之后可以放回。

6505

6506**5. 等待后再重新启动 Claude Code**

6507

6508在没有任何主机仍在其原路径下列出已移走的文件之前，不要在任何主机上启动 Claude Code。

6509

6510两个文件中的一个被移走后，该消息就不再出现。

6511

6435### Make this change again later: \~/.claude.json could not be updated6512### Make this change again later: \~/.claude.json could not be updated

6436 6513

6437stderr 上的此通知表示对 [`~/.claude.json`](https://code.claude.com/docs/zh-CN/claude-directory#ce-claude-json) 的某项更改（例如登录或对信任提示的回答）未保存到该文件：6514stderr 上的此通知表示对 [`~/.claude.json`](https://code.claude.com/docs/zh-CN/claude-directory#ce-claude-json) 的某项更改（例如登录或对信任提示的回答）未保存到该文件：

6450 6527

6451* 配置的 [`--fallback-model`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 在可用性错误后接管该轮，并在记录中显示通知6528* 配置的 [`--fallback-model`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 在可用性错误后接管该轮，并在记录中显示通知

6452* Amazon Bedrock 或 Google Cloud 的 Agent Platform 启动检查发现你的默认模型不可用，或你的账户[在会话中途失去对它的访问权限](https://code.claude.com/docs/zh-CN/amazon-bedrock.md#when-a-model-is-disabled-mid-session)6529* Amazon Bedrock 或 Google Cloud 的 Agent Platform 启动检查发现你的默认模型不可用，或你的账户[在会话中途失去对它的访问权限](https://code.claude.com/docs/zh-CN/amazon-bedrock.md#when-a-model-is-disabled-mid-session)

6453* [自动模型备用](https://code.claude.com/docs/zh-CN/model-config.md#automatic-model-fallback) 在 Fable 5.1、Fable 5、Opus 5.5、Sonnet 5.5 和 Opus 5 上，当该类别有备用模型时，将会话移动到标记类别的备用模型，并在记录中显示通知6530* 在 Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 上，[自动模型回退](https://code.claude.com/docs/zh-CN/model-config.md#automatic-model-fallback)会在被标记类别有备用模型时，将会话移至该类别的备用模型。会话记录中会显示通知

6454 6531

6455下面的模型选择检查捕获第二和第三种情况；第一种情况显示为记录通知而不是 `/model` 更改。[模型配置](https://code.claude.com/docs/zh-CN/model-config.md) 解释了每个备用何时适用。6532下面的模型选择检查捕获第二和第三种情况；第一种情况显示为记录通知而不是 `/model` 更改。[模型配置](https://code.claude.com/docs/zh-CN/model-config.md) 解释了每个备用何时适用。

6456 6533

fast-mode.md +21 −16

Details

4 4

5# 使用快速模式加快响应速度5# 使用快速模式加快响应速度

6 6

~~7> 通过切换快速模式在 Claude Code 中获得更快的 Opus 响应。~~7> 通过使用 `/fast` 切换快速模式，在 Claude Code 中获得更快的 Opus 和 Fable 响应。

8 8

9> [!NOTE]9> [!NOTE]

10>10>

~~11> Claude Opus 5.5 的快速模式现已可用，Claude Opus 5 和 Claude Opus 4.8 的快速模式目前为[研究预览版](#research-preview)。~~11> Claude Fable 5.2 和 Claude Opus 5.5 的快速模式现已可用，Claude Opus 5 和 Claude Opus 4.8 的快速模式目前为[研究预览版](#research-preview)。

12 12

13快速模式是 Claude Opus 的高速配置，使模型速度提高最多 2.5 倍，但每个令牌的成本更高。当您需要速度进行交互式工作（如快速迭代或实时调试）时，使用 `/fast` 将其打开，当成本比延迟更重要时，将其关闭。13快速模式是受支持模型的高速配置，使模型速度提高最多 2.5 倍，但每个 token 的成本更高。当您需要速度进行交互式工作（如快速迭代或实时调试）时，使用 `/fast` 将其打开，当成本比延迟更重要时，将其关闭。

14 14

15快速模式不是一个不同的模型。它使用 Claude Opus，但采用不同的 API 配置，优先考虑速度而不是成本效率。您获得相同的质量和功能，只是响应速度更快。快速模式在 Opus 5.5、Opus 5 和 Opus 4.8 上受支持。它在 Sonnet、Haiku 或其他模型上不可用。15快速模式使用相同的模型，但采用不同的 API 配置，优先考虑速度而不是成本效率，因此质量和功能保持不变。快速模式在 Fable 5.2、Opus 5.5、Opus 5 和 Opus 4.8 上受支持。它在 Sonnet、Haiku 或其他模型上不可用。

16 16

17> [!WARNING]17> [!WARNING]

18>18>

26需要了解的内容：26需要了解的内容：

27 27

28* 使用 `/fast` 在 Claude Code CLI 中切换快速模式。[VS Code 扩展](https://code.claude.com/docs/zh-CN/vs-code.md)在选定的模型支持快速模式时提供**切换快速模式**命令。Claude Code 将该切换保存到您的 [`fastMode` 设置](#toggle-fast-mode)。28* 使用 `/fast` 在 Claude Code CLI 中切换快速模式。[VS Code 扩展](https://code.claude.com/docs/zh-CN/vs-code.md)在选定的模型支持快速模式时提供**切换快速模式**命令。Claude Code 将该切换保存到您的 [`fastMode` 设置](#toggle-fast-mode)。

~~29* 快速模式定价在 Opus 5.5 上为 $8/$40 MTok 输入/输出，在 Opus 5 和 Opus 4.8 上为 $10/$50 MTok 输入/输出。~~29* 快速模式定价（每 MTok 输入/输出）在 Fable 5.2 上为 \$16/\$80，在 Opus 5.5 上为 \$8/\$40，在 Opus 5 和 Opus 4.8 上为 \$10/\$50。

30* 可供订阅套餐（Pro/Max/Ultra/Team/Enterprise）上的 Claude Code 用户和 Claude 控制台使用。Team 和 Enterprise 组织需要所有者先启用它，Console 组织需要先配置访问权限才能在 Opus 5 或 Opus 4.8 上使用它。[要求](#requirements)对这两者进行了说明。30* 可供订阅套餐（Pro/Max/Ultra/Team/Enterprise）上的 Claude Code 用户和 Claude 控制台使用。Team 和 Enterprise 组织需要所有者先启用它，Console 组织需要先配置访问权限才能在 Opus 5 或 Opus 4.8 上使用它。[要求](#requirements)对这两者进行了说明。

31* 对于订阅套餐（Pro/Max/Ultra/Team/Enterprise）上的 Claude Code 用户，快速模式仅通过使用额度提供，不包含在订阅速率限制中。31* 对于订阅套餐（Pro/Max/Ultra/Team/Enterprise）上的 Claude Code 用户，快速模式仅通过使用额度提供，不包含在订阅速率限制中。

32 32

35在 CLI 中，可以通过以下任一方式切换快速模式：35在 CLI 中，可以通过以下任一方式切换快速模式：

36 36

37* 运行 `/fast`，按 Space 切换开启或关闭，然后按 Enter 确认37* 运行 `/fast`，按 Space 切换开启或关闭，然后按 Enter 确认

38* 在支持快速模式的模型上，在[用户设置文件](https://code.claude.com/docs/zh-CN/settings.md)中设置 `"fastMode": true`。如果您在其他任何模型上设置此项，您将继续使用该模型，且快速模式保持关闭。38* 在支持快速模式的模型上，在[用户设置文件](https://code.claude.com/docs/zh-CN/settings.md)中设置 `"fastMode": true`。如果您在其他任何模型上设置此项，您将继续使用该模型，且快速模式保持关闭。在 Fable 5.2 上，仅设置此项不会生效，直到您在使用 Fable 5.2 时运行 `/fast`。

39 39

40默认情况下，在受支持的模型上，在交互式会话中开启的快速模式会跨会话保留。您可以将快速模式配置为每个会话重置。有关详细信息，请参阅[要求按会话选择启用](#require-per-session-opt-in)。40默认情况下，在受支持的模型上，在交互式会话中开启的快速模式会跨会话保留。在 Fable 5.2 上，仅当您[在使用 Fable 5.2 时开启](#switch-models-while-fast-mode-is-on)快速模式，它才会保留。您可以将快速模式配置为每个会话重置。有关详细信息，请参阅[要求按会话选择启用](#require-per-session-opt-in)。

41 41

42在[云端会话](#use-fast-mode-in-cloud-sessions)之外，在使用 `-p` 标志的[非交互模式](https://code.claude.com/docs/zh-CN/headless.md)下，`/fast` 仅在其 [`--settings`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 值中包含快速模式的会话中有效，例如 `claude -p --settings '{"fastMode": true}'`；此时切换仅适用于该会话，不会保存为您的默认设置。`-p` 形式需要 Claude Code v2.1.205 或更高版本。在非交互模式的其他情况下，该命令会报告快速模式不可用。42在[云端会话](#use-fast-mode-in-cloud-sessions)之外，在使用 `-p` 标志的[非交互模式](https://code.claude.com/docs/zh-CN/headless.md)下，`/fast` 仅在其 [`--settings`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 值中包含快速模式的会话中有效，例如 `claude -p --settings '{"fastMode": true}'`；此时切换仅适用于该会话，不会保存为您的默认设置。`-p` 形式需要 Claude Code v2.1.205 或更高版本。在非交互模式的其他情况下，该命令会报告快速模式不可用。

43 43

48使用 `/fast` 启用快速模式时：48使用 `/fast` 启用快速模式时：

49 49

50* 如果您当前的模型不支持快速模式，Claude Code 会切换到 Opus50* 如果您当前的模型不支持快速模式，Claude Code 会切换到 Opus

51* 在 Fable 5.2 上使用快速模式需要 Claude Code v2.1.321 或更高版本

51* 您将看到一条确认消息："Fast mode ON"52* 您将看到一条确认消息："Fast mode ON"

52* 快速模式处于活动状态时，提示词旁边会出现一个小的 `↯` 图标53* 快速模式处于活动状态时，提示词旁边会出现一个小的 `↯` 图标

53* 随时再次运行 `/fast` 可检查快速模式是开启还是关闭54* 随时再次运行 `/fast` 可检查快速模式是开启还是关闭

54 55

55在 Claude Code v2.1.280 及更高版本中，Opus 5.5 是快速模式的默认模型。在 v2.1.280 之前，从 v2.1.219 起快速模式默认使用 Opus 5。56在 Claude Code v2.1.280 及更高版本中，Opus 5.5 是快速模式的默认模型。在 v2.1.280 之前，从 v2.1.219 起快速模式默认使用 Opus 5。

56 57

~~57当您再次使用 `/fast` 禁用快速模式时，您仍将使用 Opus。要切换到其他模型，请使用 `/model`。~~58当您再次使用 `/fast` 禁用快速模式时，您仍将使用当前模型。要切换到其他模型，请使用 `/model`。

58 59

59### 在快速模式开启时切换模型60### 在快速模式开启时切换模型

60 61

~~61快速模式会双向跟随您的模型切换：~~62快速模式会跟随您的模型切换：

62 63

63* **切换离开**：当您切换到不支持快速模式的模型时，Claude Code 会关闭快速模式。这包括 Opus 4.7；在 v2.1.221 之前，切换到 Opus 4.7 后快速模式仍保持开启，API 会拒绝这些请求。64* **切换离开**：当您切换到不支持快速模式的模型时，Claude Code 会关闭快速模式。这包括 Opus 4.7；在 v2.1.221 之前，切换到 Opus 4.7 后快速模式仍保持开启，API 会拒绝这些请求。

64* **切换回来**：当您保存的快速模式偏好为开启时（新会话默认即从该偏好开始），切换回受支持的 Opus 模型会再次开启快速模式。对于保存的偏好为关闭的会话，模型切换永远不会开启快速模式；如果配置了[按会话选择启用](#require-per-session-opt-in)，切换回来也不会开启快速模式；请运行 `/fast` 重新启用。65* **切换回来**：当您保存的偏好为开启时，切换回受支持的 Opus 模型会再次开启快速模式。如果使用[按会话选择启用](#require-per-session-opt-in)，请改为运行 `/fast`。

66* **切换到 Fable 5.2**：除非您在使用 Fable 5.2 时开启了快速模式，否则快速模式会关闭。要开启快速模式，请在 Fable 5.2 上运行 `/fast`。除非您设置了[按会话选择启用](#require-per-session-opt-in)，否则此设置会跨会话保留，直到您将其关闭或在其他模型上开启快速模式。

65 67

66每当模型切换开启或关闭快速模式时，Claude Code 都会显示 `Fast mode ON` 或 `Fast mode OFF` 确认消息，并且在快速模式开启时会出现 `↯` 图标。无论您是使用 `/model`、使用 [`/config model=<model>`](https://code.claude.com/docs/zh-CN/settings) 还是从通过 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 连接的设备进行切换，都是如此。68每当模型切换开启或关闭快速模式时，Claude Code 都会显示 `Fast mode ON` 或 `Fast mode OFF` 确认消息，并且在快速模式开启时会出现 `↯` 图标。无论您是使用 `/model`、使用 [`/config model=<model>`](https://code.claude.com/docs/zh-CN/settings) 还是从通过 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 连接的设备进行切换，都是如此。

67 69

77 79

78## 了解成本权衡80## 了解成本权衡

79 81

~~80快速模式的每个令牌定价高于标准 Opus：~~82快速模式的每 token 定价高于标准速度：

81 83

82| 模型 | 输入 (MTok) | 输出 (MTok) |84| 模型 | 输入 (MTok) | 输出 (MTok) |

83| - | - | - |85| - | - | - |

86| Fable 5.2 | \$16 | \$80 |

84| Opus 5.5 | \$8 | \$40 |87| Opus 5.5 | \$8 | \$40 |

85| Opus 5 | \$10 | \$50 |88| Opus 5 | \$10 | \$50 |

86| Opus 4.8 | \$10 | \$50 |89| Opus 4.8 | \$10 | \$50 |

87 90

88快速模式定价在整个 1M 令牌上下文窗口中是固定的。有关要比较的标准 Opus 费率，请参阅 [Claude 定价参考](https://platform.claude.com/docs/zh-CN/about-claude/pricing)。91快速模式定价在整个 1M token 上下文窗口中是固定的。有关要比较的标准费率，请参阅 [Claude 定价参考](https://platform.claude.com/docs/zh-CN/about-claude/pricing)。

89 92

90在对话中首次启用快速模式时，您需要为整个对话上下文支付完整的快速模式未缓存输入 token 价格。对话进行得越深入，成本就越高，因此在对话开始时启用快速模式的费用最低。快速模式和标准速度使用[各自独立的缓存](https://code.claude.com/docs/zh-CN/prompt-caching.md#turning-on-fast-mode)，因此之后的每次切换都会再次以未缓存方式读取部分或全部对话。93在对话中首次启用快速模式时，您需要为整个对话上下文支付完整的快速模式未缓存输入 token 价格。对话进行得越深入，成本就越高，因此在对话开始时启用快速模式的费用最低。快速模式和标准速度使用[各自独立的缓存](https://code.claude.com/docs/zh-CN/prompt-caching.md#turning-on-fast-mode)，因此之后的每次切换都会再次以未缓存方式读取部分或全部对话。

91 94

137 140

138* **付费控制台组织**：Claude 控制台账户不使用使用额度，您的组织按令牌为快速模式付费，与其余 API 使用量一起。在控制台的免费 Evaluation 计划上，`/fast` 显示"Fast mode unavailable during evaluation. Please purchase credits."。要清除它，在您的[控制台计费设置](https://platform.claude.com/settings/billing)中购买额度。141* **付费控制台组织**：Claude 控制台账户不使用使用额度，您的组织按令牌为快速模式付费，与其余 API 使用量一起。在控制台的免费 Evaluation 计划上，`/fast` 显示"Fast mode unavailable during evaluation. Please purchase credits."。要清除它，在您的[控制台计费设置](https://platform.claude.com/settings/billing)中购买额度。

139 142

140 Opus 5.5 上的快速模式还取决于您的组织的[使用层级](https://platform.claude.com/docs/en/api/rate-limits)。143 Fable 5.2 或 Opus 5.5 上的快速模式还取决于您的组织的[使用层级](https://platform.claude.com/docs/en/api/rate-limits)。

141* **团队和企业的所有者启用**：快速模式默认对团队和企业组织禁用。所有者必须明确[启用快速模式](#enable-fast-mode-for-your-organization)，用户才能访问它。144* **团队和企业的所有者启用**：快速模式默认对团队和企业组织禁用。所有者必须明确[启用快速模式](#enable-fast-mode-for-your-organization)，用户才能访问它。

142 145

143> [!NOTE]146> [!NOTE]

147> * **快速模式未启用**：如果您的组织尚未启用快速模式，使用 `/fast` 启用快速模式会显示"Fast mode has been disabled by your organization."。150> * **快速模式未启用**：如果您的组织尚未启用快速模式，使用 `/fast` 启用快速模式会显示"Fast mode has been disabled by your organization."。

148> * **快速模式被托管设置关闭**：如果您的组织部署[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)，设置 [`fastMode: false`](https://code.claude.com/docs/zh-CN/settings-reference#fastmode)，使用 `/fast` 启用快速模式会显示相同的"Fast mode has been disabled by your organization"消息。151> * **快速模式被托管设置关闭**：如果您的组织部署[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)，设置 [`fastMode: false`](https://code.claude.com/docs/zh-CN/settings-reference#fastmode)，使用 `/fast` 启用快速模式会显示相同的"Fast mode has been disabled by your organization"消息。

149> * **需要每个会话选择加入**：托管设置设置 [`fastModePerSessionOptIn: true`](#require-per-session-opt-in) 在除交互式终端会话外的任何地方都拒绝 `/fast on`，显示相同的消息。152> * **需要每个会话选择加入**：托管设置设置 [`fastModePerSessionOptIn: true`](#require-per-session-opt-in) 在除交互式终端会话外的任何地方都拒绝 `/fast on`，显示相同的消息。

150> * **快速模式模型不允许**：如果您的组织的 [`availableModels`](https://code.claude.com/docs/zh-CN/model-config#restrict-model-selection) 允许列表排除了快速模式 Opus 模型，启用它会被拒绝，显示"is not in your organization's allowed models"。在已在支持快速模式的允许 Opus 模型上运行的会话中，`/fast` 改为在您当前的模型上启用快速模式，而不是切换模型。153> * **快速模式模型不允许**：如果您的组织的 [`availableModels`](https://code.claude.com/docs/zh-CN/model-config#restrict-model-selection) 允许列表排除了快速模式 Opus 模型，启用它会被拒绝，显示"is not in your organization's allowed models"。在已在支持快速模式的允许模型上运行的会话中，`/fast` 改为在您当前的模型上启用快速模式，而不是切换模型。

151 154

152### 为您的组织启用快速模式155### 为您的组织启用快速模式

153 156

196 199

197### 要求每个会话选择加入200### 要求每个会话选择加入

198 201

199默认情况下，用户在交互式会话中启用的快速模式会在支持的模型上跨会话保持。要更改此行为，在任何[设置文件](https://code.claude.com/docs/zh-CN/settings.md#where-settings-live)中将 `fastModePerSessionOptIn` 设置为 `true`，这会导致每个会话以快速模式关闭开始，并要求用户使用 `/fast` 明确启用它。[Team](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) 或 [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) 计划上的所有者可以通过[服务器托管设置](https://code.claude.com/docs/zh-CN/server-managed-settings.md)在组织范围内部署它。202默认情况下，用户在交互式会话中启用的快速模式会在支持的模型上跨会话保持。在 Fable 5.2 上，仅当用户[在使用 Fable 5.2 时启用了快速模式](#switch-models-while-fast-mode-is-on)时，它才会保持。

203

204要让每个会话都以快速模式关闭的状态开始，请在任何[设置文件](https://code.claude.com/docs/zh-CN/settings.md#where-settings-live)中将 `fastModePerSessionOptIn` 设置为 `true`。之后，用户需要在每个会话中使用 `/fast` 启用它。[Team](https://claude.com/pricing?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_teams#team-&-enterprise) 或 [Enterprise](https://anthropic.com/contact-sales?utm_source=claude_code\&utm_medium=docs\&utm_content=fast_mode_enterprise) 套餐上的所有者可以通过[服务器托管设置](https://code.claude.com/docs/zh-CN/server-managed-settings.md)在组织范围内部署它。

200 205

201```json theme={null}206```json theme={null}

202{207{

210 215

211## 处理速率限制216## 处理速率限制

212 217

213快速模式与标准 Opus 有单独的速率限制；对于 Console 组织，Claude Platform 的[速率限制](https://platform.claude.com/docs/en/api/rate-limits)页面对此进行了说明。当您达到快速模式速率限制时：218快速模式与标准速度有单独的速率限制；对于 Console 组织，Claude Platform 的[速率限制](https://platform.claude.com/docs/en/api/rate-limits)页面对此进行了说明。当您达到快速模式速率限制时：

214 219

2151. 快速模式自动回退到标准速度2201. 快速模式自动回退到标准速度

2162. `↯` 图标变灰以指示冷却2212. `↯` 图标变灰以指示冷却

hooks.md +12 −4

Details

1089 1089

1090#### 发出终端通知1090#### 发出终端通知

1091 1091

1092Hook 运行时没有控制终端，因此直接将转义序列写入 `/dev/tty` 会失败。请改为在 `terminalSequence` 字段中返回转义序列，Claude Code 会通过其自己的终端写入路径为您发出它。这不存在竞争问题，可在 tmux 和 GNU screen 中工作，也可在没有 `/dev/tty` 的 Windows 上工作。1092Hook 运行时没有控制终端，因此直接将转义序列写入 `/dev/tty` 会失败。请改为在 `terminalSequence` 字段中返回转义序列，Claude Code 会通过其自己的终端写入路径为您发出它。这不存在竞争问题，也可在没有 `/dev/tty` 的 Windows 上工作。

1093 1093

1094该字段接受包含一个或多个允许列表中转义序列的字符串：1094该字段接受包含一个或多个允许列表中转义序列的字符串：

1095 1095

1101 1101

1102序列可以用 BEL 或 ST 终止。允许列表之外的任何内容，包括 CSI 光标和颜色序列、OSC 调色板序列、OSC 8 超链接、OSC 52 剪贴板写入和 OSC 1337，都会被拒绝，该字段被忽略。1102序列可以用 BEL 或 ST 终止。允许列表之外的任何内容，包括 CSI 光标和颜色序列、OSC 调色板序列、OSC 8 超链接、OSC 52 剪贴板写入和 OSC 1337，都会被拒绝，该字段被忽略。

1103 1103

1104Claude Code 在处理您的 hook 输出时自行写入序列，因此该字段在丢弃 `systemMessage` 和 `continue` 的事件（如 `Notification` 和 `StopFailure`）上也能工作。它有两个限制：1104Claude Code 在处理您的 hook 输出时自行写入序列，因此该字段在丢弃 `systemMessage` 和 `continue` 的事件（如 `Notification` 和 `StopFailure`）上也能工作。它有一些限制：

1105 1105

1106* Claude Code 仅在交互式会话中且仅当其界面在屏幕上时写入序列。在使用 `-p` 标志的非交互模式和 Agent SDK 中，它忽略该字段。1106* Claude Code 仅在交互式会话中且仅当其界面打开时写入序列。在使用 `-p` 标志的非交互模式和 Agent SDK 中，它忽略该字段。

1107* 该字段仅在不于[后台](#run-hooks-in-the-background)运行的 hook 中有效，因此请不要启用 `async` 和 `asyncRewake`。

1107* `WorktreeCreate` 命令 hook 无法返回 JSON，因为 Claude Code 将其 stdout 读取为 worktree 路径。HTTP `WorktreeCreate` hook 返回 JSON，可以包括该字段。1108* `WorktreeCreate` 命令 hook 无法返回 JSON，因为 Claude Code 将其 stdout 读取为 worktree 路径。HTTP `WorktreeCreate` hook 返回 JSON，可以包括该字段。

1108 1109

1109下面的示例从 `Notification` hook 触发桌面通知。转义序列使用 `printf` 八进制转义构建，因此控制字节从不出现在 shell 命令行上，`jq -n --arg` 构建 JSON 输出，因此通知消息中的引号、反斜杠和换行符会被正确转义：1110如果您使用 tmux 或 GNU screen，请先完成[针对它们的设置](#get-terminal-notifications-inside-tmux-or-gnu-screen)。下面的示例在可读取 OSC `777` 的终端（如 Ghostty 或 Warp）中，从 `Notification` hook 触发桌面通知。脚本中的 `jq -nc --arg` 调用构建 JSON 输出，并转义通知消息中的所有引号、反斜杠和换行符：

1110 1111

1111```bash theme={null}1112```bash theme={null}

1112#!/bin/bash1113#!/bin/bash

1120 1121

1121`{ "terminalSequence": "..." }` 的结构在任何 shell 或语言中都相同。1122`{ "terminalSequence": "..." }` 的结构在任何 shell 或语言中都相同。

1122 1123

1124#### 在 tmux 或 GNU screen 中获取终端通知

1125

1126当 Claude Code 在 tmux 或 GNU screen 中运行时，OSC 序列需要满足以下条件才能到达您的终端应用程序：

1127

1128* **tmux 3.3 或更高版本**：将 `set -g allow-passthrough on` 添加到 `~/.tmux.conf`，然后在 shell 中运行 `tmux source-file ~/.tmux.conf`。该选项适用于这些窗格中的每个程序，而不仅仅是 Claude Code。使用 `on` 时，只有 tmux 正在显示的窗格才能发送这些序列。要让您已附加的会话中的其他窗格也能发送，请在 tmux 3.4 或更高版本上使用 `all` 代替 `on`。

1129* **GNU screen**：在 screen 中保持 Claude Code 的窗口处于显示状态，因为来自后台窗口的序列不会到达您的终端应用程序

1130

1123#### 为 Claude 添加上下文1131#### 为 Claude 添加上下文

1124 1132

1125`additionalContext` 字段将字符串从您的 hook 传递到 Claude 的上下文窗口。Claude Code 将字符串包装在[系统提醒](https://code.claude.com/docs/zh-CN/glossary.md#system-reminder)中，并在 hook 触发的位置将其插入对话。Claude 在下一次模型请求时读取提醒，但它不会作为聊天消息出现在界面中。1133`additionalContext` 字段将字符串从您的 hook 传递到 Claude 的上下文窗口。Claude Code 将字符串包装在[系统提醒](https://code.claude.com/docs/zh-CN/glossary.md#system-reminder)中，并在 hook 触发的位置将其插入对话。Claude 在下一次模型请求时读取提醒，但它不会作为聊天消息出现在界面中。

llm-gateway-protocol.md +1 −1

Details

223| Beta [工具字段](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | 工具相关的 beta 请求头与工具 schema 字段（如 `strict` 和 `defer_loading`）配对 | 当请求体通过而没有其请求头时，命名无法识别的工具 schema 字段的 `400`。关于 `defer_loading`，请参阅[不带工具搜索的重试](#retry-without-tool-search) | 转发两者，或 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities) |223| Beta [工具字段](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview) | 工具相关的 beta 请求头与工具 schema 字段（如 `strict` 和 `defer_loading`）配对 | 当请求体通过而没有其请求头时，命名无法识别的工具 schema 字段的 `400`。关于 `defer_loading`，请参阅[不带工具搜索的重试](#retry-without-tool-search) | 转发两者，或 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities) |

224| [努力](https://platform.claude.com/docs/en/build-with-claude/effort)和[结构化输出](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | `output_config` 请求体字段携带努力、结构化输出格式和任务预算设置；每个都与自己的 beta 请求头配对 | 在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上游上命名 `output_config` 的 `400`，通常是 `Extra inputs are not permitted` | 一起转发该字段及其请求头，或让开发者设置 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities)，这会移除格式和任务预算设置，但不会移除努力。若只想移除格式，开发者可以改为设置 [`CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1`](https://code.claude.com/docs/zh-CN/env-vars)，这需要 v2.1.288 或更高版本 |224| [努力](https://platform.claude.com/docs/en/build-with-claude/effort)和[结构化输出](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) | `output_config` 请求体字段携带努力、结构化输出格式和任务预算设置；每个都与自己的 beta 请求头配对 | 在 Amazon Bedrock 和 Google Cloud 的 Agent Platform 上游上命名 `output_config` 的 `400`，通常是 `Extra inputs are not permitted` | 一起转发该字段及其请求头，或让开发者设置 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities)，这会移除格式和任务预算设置，但不会移除努力。若只想移除格式，开发者可以改为设置 [`CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS=1`](https://code.claude.com/docs/zh-CN/env-vars)，这需要 v2.1.288 或更高版本 |

225| 对话中途的系统消息 | 无 beta 请求头。对于 Claude Opus 4.8、在其之后发布的模型以及无法识别的模型 ID，Claude Code 会将部分提醒和附件文本作为 `messages` 中的 `role: "system"` 条目发送 | `400`，例如 `Unexpected role "system"` | Claude Code 会[在不带系统消息的情况下重试](#automatic-retry-and-error-forwarding)。若要在 Claude Opus 4.8 之前发布的模型的别名上停止系统消息，请在您分发的设置中添加 [`modelOverrides` 条目](#settings-for-unrecognized-model-ids) |225| 对话中途的系统消息 | 无 beta 请求头。对于 Claude Opus 4.8、在其之后发布的模型以及无法识别的模型 ID，Claude Code 会将部分提醒和附件文本作为 `messages` 中的 `role: "system"` 条目发送 | `400`，例如 `Unexpected role "system"` | Claude Code 会[在不带系统消息的情况下重试](#automatic-retry-and-error-forwarding)。若要在 Claude Opus 4.8 之前发布的模型的别名上停止系统消息，请在您分发的设置中添加 [`modelOverrides` 条目](#settings-for-unrecognized-model-ids) |

226| [按轮次设置的努力](https://code.claude.com/docs/zh-CN/prompt-caching.md#changing-effort-level) | 在 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.1 上，beta 请求头与 `role: "system"` 条目上的 `output_config.effort` 配对，这些条目可以是系统消息，也可以是内容为空的条目 | 当您的网关从空条目中删除该字段时，出现带有 `messages.N: system content must contain at least one block` 的 `400` | 转发两者，或让开发者设置 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities) 以停止发送该字段和空条目 |226| [按轮次设置的努力](https://code.claude.com/docs/zh-CN/prompt-caching.md#changing-effort-level) | 在 Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5.2 和 Fable 5.1 上，beta 请求头与 `role: "system"` 条目上的 `output_config.effort` 配对，这些条目可以是系统消息，也可以是内容为空的条目 | 当您的网关从空条目中删除该字段时，出现带有 `messages.N: system content must contain at least one block` 的 `400` | 转发两者，或让开发者设置 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](#disable-pre-release-capabilities) 以停止发送该字段和空条目 |

227| [提示缓存](https://code.claude.com/docs/zh-CN/prompt-caching.md) | 无 beta 配对。Claude Code 将 `cache_control` 标记附加到 `system` 块和 `messages` 条目，包括在对话中途附加的 `role: "system"` 条目 | 无错误：对话在每个回合都作为未缓存的输入计费，在 `usage` 中可见为高 `input_tokens` 且缓存活动很少或没有 | 在任何地方原封不动地转发 `cache_control`，并且不要将块形式的 `system` 或消息内容转换为纯字符串 |227| [提示缓存](https://code.claude.com/docs/zh-CN/prompt-caching.md) | 无 beta 配对。Claude Code 将 `cache_control` 标记附加到 `system` 块和 `messages` 条目，包括在对话中途附加的 `role: "system"` 条目 | 无错误：对话在每个回合都作为未缓存的输入计费，在 `usage` 中可见为高 `input_tokens` 且缓存活动很少或没有 | 在任何地方原封不动地转发 `cache_control`，并且不要将块形式的 `system` 或消息内容转换为纯字符串 |

229 229

model-config.md +53 −24

Details

30| 模型别名 | 行为 |30| 模型别名 | 行为 |

31| - | - |31| - | - |

32| **`default`** | 特殊值，清除任何模型覆盖并恢复到[您账户的运行时默认值](#default-model-setting)。本身不是模型别名 |32| **`default`** | 特殊值，清除任何模型覆盖并恢复到[您账户的运行时默认值](#default-model-setting)。本身不是模型别名 |

34| **`fable`** | 为您最困难和运行时间最长的任务使用[您的提供商的 Fable 模型](#fable-alias-resolution) |34| **`fable`** | 为您最困难和运行时间最长的任务使用[您的提供商的 Fable 模型](#fable-alias-resolution) |

35| **`sonnet`** | 为日常编码任务使用最新的 Sonnet 模型 |35| **`sonnet`** | 为日常编码任务使用最新的 Sonnet 模型 |

36| **`opus`** | 为复杂推理任务使用最新的 Opus 模型 |36| **`opus`** | 为复杂推理任务使用最新的 Opus 模型 |

50 50

51除非您设置 `ANTHROPIC_DEFAULT_FABLE_MODEL`，否则 `fable` 别名解析到 Fable 5.1，但在 [Claude apps gateway](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 会话中除外，其中 `fable` 和 `best` 解析到 Fable 5。51除非您设置 `ANTHROPIC_DEFAULT_FABLE_MODEL`，否则 `fable` 别名在 [Claude apps gateway](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 会话中解析到 Fable 5，在其他所有情况下解析到 Fable 5.2。

52 52

~~53未配置为提供 `claude-fable-5-1` 的网关会拒绝对该模型的请求。要通过提供它的网关使用 Fable 5.1，请使用 `/model claude-fable-5-1` 选择它。~~53未配置为提供 `claude-fable-5-2` 的网关会拒绝对该模型的请求。要通过提供它的网关使用 Fable 5.2，请使用 `/model claude-fable-5-2` 选择它。

54 54

55当 `opus` 或 `sonnet` 解析到较旧的模型时，可以通过显式选择完整模型名称或设置 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 来使用较新的模型。55当 `opus` 或 `sonnet` 解析到较旧的模型时，可以通过显式选择完整模型名称或设置 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 来使用较新的模型。

56 56

64 64

65### 使用 Fable65### 使用 Fable

66 66

67[Claude Fable 5.1](https://platform.claude.com/docs/en/about-claude/models/overview) 和 Claude Fable 5 是 Claude Code 中最强大的模型，适合一次无法完成的大型任务。它们能够维持长时间的自主会话，在行动前进行调查，并比较小的模型更频繁地验证其工作。Fable 5.1 是较新的版本。67[Claude Fable 模型](https://platform.claude.com/docs/en/about-claude/models/overview)是 Claude Code 中最强大的模型，适合一次无法完成的大型任务。它们能够维持长时间的自主会话，在行动前进行调查，并比较小的模型更频繁地验证其工作。

68 68

~~69这两个 Fable 模型都不是任何套餐或提供商上的账户类型默认值。请显式选择一个：~~69任何 Fable 模型都不是任何套餐或提供商上的账户类型默认值。请显式选择一个：

70 70

71* **Fable 5.1**：运行 `/model fable`，或使用 `claude --model fable` 启动。在 [Claude apps gateway](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 会话中，别名解析到 Fable 5，请改为运行 `/model claude-fable-5-1`。71* **Fable 5.2**：运行 `/model fable`，或使用 `claude --model fable` 启动。在 [Claude apps gateway](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 会话中，请改为运行 `/model claude-fable-5-2`。

72* **Fable 5**：按模型 ID 选择它。在 Anthropic API 上，运行 `/model claude-fable-5` 或使用 `claude --model claude-fable-5` 启动。在其他提供商上，使用您的提供商的 Fable 5 模型 ID，或使用 `ANTHROPIC_DEFAULT_FABLE_MODEL` [固定它](#pin-models-for-third-party-deployments)。72* **Fable 5.1 或 Fable 5**：按模型 ID 选择它。在 Anthropic API 上，运行 `/model claude-fable-5-1` 或 `/model claude-fable-5`，或使用 `claude --model claude-fable-5-1` 启动。在其他提供商上，使用您的提供商的模型 ID，或使用 `ANTHROPIC_DEFAULT_FABLE_MODEL` [固定它](#pin-models-for-third-party-deployments)。

73 73

74如果您直接连接到 Anthropic API，并且您的用户设置将 `claude-fable-5` 或 `claude-fable-5[1m]` 作为模型（例如因为您在 v2.1.257 之前在 `/model` 选择器中选择了 Fable），Claude Code 会在您首次运行 v2.1.257 或更高版本时将该保存的值更改为 `fable` 或 `fable[1m]` 别名。启动模型行会显示一次 `(auto-updated)`。项目、本地或托管设置中的 `claude-fable-5` 值保持原样。74在 Pro、Max、Team 和 Enterprise 套餐上，保存在您用户设置中的 `claude-fable-5-1` 模型会迁移到 `fable` 别名：

76* **Pro 或 Max 套餐**：迁移会在您首次运行 v2.1.321 或更高版本时进行。在终端中，启动模型行可能会显示一次 `(auto-updated)`。

77* **Team 或 Enterprise 套餐**：迁移会等待您组织的设置，因此可能在之后的某次启动时进行，也可能根本不会进行。迁移从下一个会话开始生效，不会显示 `(auto-updated)` 行。要检查您的模型，请运行 `/model`。

79迁移后，除非您已为 Fable 5.2 [设置了级别](#adjust-effort-level)，否则会话会以 Fable 5.2 的默认 effort 启动。Console 账户、第三方提供商以及项目、本地或托管设置会保留 `claude-fable-5-1`。

75 80

76被 Fable 模型的安全分类器标记的请求（最常见于网络安全和生物学领域）会触发[自动模型回退](#automatic-model-fallback)。81被 Fable 模型的安全分类器标记的请求（最常见于网络安全和生物学领域）会触发[自动模型回退](#automatic-model-fallback)。

77 82

84 89

85> [!NOTE]90> [!NOTE]

86>91>

87> Fable 5.1 需要 Claude Code v2.1.257 或更高版本。如果来自较旧版本的请求失败，请参阅 [Claude Code does not support this model](https://code.claude.com/docs/zh-CN/errors.md#claude-code-does-not-support-this-model)。运行 `claude update` 进行升级。有关零数据保留下的可用性，请参阅 [Model availability under ZDR](https://code.claude.com/docs/zh-CN/zero-data-retention.md#model-availability-under-zdr)。92> Fable 5.2 需要 Claude Code v2.1.321 或更高版本，Fable 5.1 需要 v2.1.257 或更高版本。如果从较旧版本对其中某个模型的请求失败，请参阅 [Claude Code does not support this model](https://code.claude.com/docs/zh-CN/errors.md#claude-code-does-not-support-this-model)。运行 `claude update` 进行升级。有关零数据保留下的可用性，请参阅 [Model availability under ZDR](https://code.claude.com/docs/zh-CN/zero-data-retention.md#model-availability-under-zdr)。

88 93

89在 Anthropic API 上，Fable 模型会出现在 `/model` 选择器中，除非 [`availableModels`](#restrict-model-selection) 或[组织模型限制](#organization-model-restrictions)将其排除。当您的组织完全无法使用 Fable 时，例如在[零数据保留](https://code.claude.com/docs/zh-CN/zero-data-retention.md#model-availability-under-zdr)下，该行在选择器中保持灰显，并附有说明原因的注释。94在 Anthropic API 上，Fable 模型会出现在 `/model` 选择器中，除非 [`availableModels`](#restrict-model-selection) 或[组织模型限制](#organization-model-restrictions)将其排除。当您的组织完全无法使用 Fable 时，例如在[零数据保留](https://code.claude.com/docs/zh-CN/zero-data-retention.md#model-availability-under-zdr)下，该行在选择器中保持灰显，并附有说明原因的注释。

90 95

163 168

164有关这些消息，请参阅 [Model is not a recognized model id](https://code.claude.com/docs/zh-CN/errors.md#model-is-not-a-recognized-model-id) 和 [Model not found](https://code.claude.com/docs/zh-CN/errors.md#model-not-found)。169有关这些消息，请参阅 [Model is not a recognized model id](https://code.claude.com/docs/zh-CN/errors.md#model-is-not-a-recognized-model-id) 和 [Model not found](https://code.claude.com/docs/zh-CN/errors.md#model-not-found)。

165 170

166如果您使用 `--model` 标志、`ANTHROPIC_MODEL` 环境变量或 `model` 设置来设置模型，Claude Code 不会预先检查，拼写错误的值会在第一个请求时产生 [There's an issue with the selected model](https://code.claude.com/docs/zh-CN/errors.md#theres-an-issue-with-the-selected-model)。171如果您使用 `--model` 标志、`ANTHROPIC_MODEL` 环境变量或 `model` 设置来设置模型，Claude Code 不会预先拒绝拼写错误的值。会话会正常启动，第一个请求会产生 [There's an issue with the selected model](https://code.claude.com/docs/zh-CN/errors.md#theres-an-issue-with-the-selected-model)。在 Anthropic API 上，不以 `claude-` 开头且与某个模型名称或别名拼写相近的值，还可能产生一条[建议该名称的启动警告](#fix-a-mistyped-model-name)。

167 172

168当请求的模型有计划的停用日期或会被自动重新映射到较新版本时，Claude Code 会显示一条指明所请求模型的警告。交互式会话将其显示为启动通知。从 v2.1.182 开始，在使用默认文本输出格式的[非交互模式](https://code.claude.com/docs/zh-CN/headless.md)中，相同的警告会写入 stderr。该检查也涵盖在[子代理 frontmatter](https://code.claude.com/docs/zh-CN/sub-agents.md) 中设置的 `model`。对于 `--output-format json` 和 `stream-json`，stderr 警告会被抑制；请改为从[结果消息](https://code.claude.com/docs/zh-CN/headless.md#get-structured-output)的 `modelUsage` 字段读取实际模型。173当请求的模型有计划的停用日期或会被自动重新映射到较新版本时，Claude Code 会显示一条指明所请求模型的警告。交互式会话将其显示为启动通知。从 v2.1.182 开始，在使用默认文本输出格式的[非交互模式](https://code.claude.com/docs/zh-CN/headless.md)中，相同的警告会写入 stderr。该检查也涵盖在[子代理 frontmatter](https://code.claude.com/docs/zh-CN/sub-agents.md) 中设置的 `model`。对于 `--output-format json` 和 `stream-json`，stderr 警告会被抑制；请改为从[结果消息](https://code.claude.com/docs/zh-CN/headless.md#get-structured-output)的 `modelUsage` 字段读取实际模型。

169 174

225 230

226## 限制模型选择231## 限制模型选择

227 232

228管理员可以在[托管或策略设置](https://code.claude.com/docs/zh-CN/managed-settings.md)中使用 `availableModels` 来限制用户可以选择的模型。条目可以匹配模型系列（如 `sonnet`）、版本前缀（如 `claude-sonnet-4-5`）或完整模型 ID（如 `claude-sonnet-4-5-20250929`）。版本前缀也会匹配扩展它的后续模型 ID，因此 `claude-fable-5` 允许 Fable 5 和 Fable 5.1，而 `claude-fable-5-1` 仅允许 Fable 5.1。要阻止列表允许的模型，或使每个模型 ID 条目仅允许它命名的版本，请参阅[阻止特定模型或版本](#block-specific-models-or-versions)。233管理员可以在[托管或策略设置](https://code.claude.com/docs/zh-CN/managed-settings.md)中使用 `availableModels` 来限制用户可以选择的模型。每个条目匹配以下之一：

234

235* 模型系列，如 `sonnet`

236* 版本前缀，如 `claude-sonnet-4-5`。它也会匹配以另一个段扩展它的后续模型 ID。例如，`claude-fable-5` 允许 Fable 5、Fable 5.1 和 Fable 5.2，而 `claude-fable-5-1` 仅允许 Fable 5.1

237* 完整模型 ID，如 `claude-sonnet-4-5-20250929`

238

239要阻止列表允许的模型，或使每个模型 ID 条目仅允许它命名的版本，请参阅[阻止特定模型或版本](#block-specific-models-or-versions)。

229 240

230在嵌入 Claude Code 并设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/zh-CN/env-vars) 的平台上，主机的模型配置优先于托管模型设置，而托管的 `availableModels` 允许列表保持有效，除非主机提供自己的列表；[托管设置优先级的例外](https://code.claude.com/docs/zh-CN/settings.md#exceptions-to-managed-settings-precedence)说明了主机覆盖的键和变量。241在嵌入 Claude Code 并设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/zh-CN/env-vars) 的平台上，主机的模型配置优先于托管模型设置，而托管的 `availableModels` 允许列表保持有效，除非主机提供自己的列表；[托管设置优先级的例外](https://code.claude.com/docs/zh-CN/settings.md#exceptions-to-managed-settings-precedence)说明了主机覆盖的键和变量。

231 242

465 476

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

467 478

468Fable 模型在任何套餐或提供商上都不是账户类型默认值。使用 `/model` 选择一个会将其保存为用户设置中的选定模型，以便后续会话从它开始。关于 Claude Code v2.1.257 对保存的 Fable 5 选择所做的一次性更改，请参阅[使用 Fable](#work-with-fable)。479> [!NOTE]

480>

481> Fable 模型在任何套餐或提供商上都不是账户类型默认值。使用 `/model` 选择一个会将其保存为用户设置中的选定模型，以便后续会话从它开始，但[对已保存的 Fable 5.1 选择所做的一次性更改](#work-with-fable)除外。

469 482

470### `opusplan` 模型设置483### `opusplan` 模型设置

471 484

521 534

522Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 运行安全分类器，最常标记网络安全和生物学内容。对于这两个类别，备用模型取决于哪个模型拒绝：535Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 运行安全分类器，最常标记网络安全和生物学内容。对于这两个类别，备用模型取决于哪个模型拒绝：

523 536

524* **Fable 5.1、Fable 5 和 Opus 5.5**：生物学标记的请求在 Opus 5 上重新运行，网络安全标记的请求在 Opus 4.8 上重新运行。537* **Fable 模型和 Opus 5.5**：生物学标记的请求在 Opus 5 上重新运行，网络安全标记的请求在 Opus 4.8 上重新运行。

525* **Sonnet 5.5**：网络安全标记的请求在 Sonnet 5 上重新运行。生物学标记的请求以拒绝结束，因为 Sonnet 5.5 没有生物学备用模型。538* **Sonnet 5.5**：网络安全标记的请求在 Sonnet 5 上重新运行。生物学标记的请求以拒绝结束，因为 Sonnet 5.5 没有生物学备用模型。

526* **Opus 5**：网络安全标记的请求在 Opus 4.8 上重新运行。生物学标记的请求以拒绝结束，因为 Opus 5 运行自己的生物学分类器，没有备用模型。539* **Opus 5**：网络安全标记的请求在 Opus 4.8 上重新运行。生物学标记的请求以拒绝结束，因为 Opus 5 运行自己的生物学分类器，没有备用模型。

527 540

582 595

583在 [Amazon Bedrock](https://code.claude.com/docs/zh-CN/amazon-bedrock.md)、[Google Cloud's Agent Platform](https://code.claude.com/docs/zh-CN/google-vertex-ai.md) 和 [Microsoft Foundry](https://code.claude.com/docs/zh-CN/microsoft-foundry.md) 上，模型 ID 是提供商特定的，因此自动回退仅在 Claude Code 可以识别每个涉及的模型时运行：596在 [Amazon Bedrock](https://code.claude.com/docs/zh-CN/amazon-bedrock.md)、[Google Cloud's Agent Platform](https://code.claude.com/docs/zh-CN/google-vertex-ai.md) 和 [Microsoft Foundry](https://code.claude.com/docs/zh-CN/microsoft-foundry.md) 上，模型 ID 是提供商特定的，因此自动回退仅在 Claude Code 可以识别每个涉及的模型时运行：

584 597

585* Claude Code 必须将当前模型识别为回退源。当模型 ID 包含 `claude-fable-5`、匹配 `ANTHROPIC_DEFAULT_FABLE_MODEL` 的值或使用 [`modelOverrides`](#override-model-ids-per-version) 映射时，Fable 5.1 和 Fable 5 被识别。Opus 5.5、Sonnet 5.5 和 Opus 5 通过其提供商模型 ID 或 [`modelOverrides`](#override-model-ids-per-version) 映射被识别。598* Claude Code 必须将当前模型识别为回退源。当模型 ID 包含 `claude-fable-5`、匹配 `ANTHROPIC_DEFAULT_FABLE_MODEL` 的值或使用 [`modelOverrides`](#override-model-ids-per-version) 映射时，Fable 模型被识别。Opus 5.5、Sonnet 5.5 和 Opus 5 通过其提供商模型 ID 或 [`modelOverrides`](#override-model-ids-per-version) 映射被识别。

586* 一个 Opus 目标必须在您的部署中解析，无论哪个模型拒绝：设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`，或在提供商的模型列表中保留一个 Opus 4.8 条目。没有一个，回退对每个源模型都保持关闭，包括 Sonnet 5.5，标记的请求以拒绝结束。599* 一个 Opus 目标必须在您的部署中解析，无论哪个模型拒绝：设置 `ANTHROPIC_DEFAULT_OPUS_MODEL`，或在提供商的模型列表中保留一个 Opus 4.8 条目。没有一个，回退对每个源模型都保持关闭，包括 Sonnet 5.5，标记的请求以拒绝结束。

587* 标记的类别的备用模型必须在您的部署中解析。从 Fable 模型、Opus 5.5 或 Opus 5，如果您设置了 `ANTHROPIC_DEFAULT_OPUS_MODEL`，标记的请求会在该模型上为每个具有回退的类别重新运行；Opus 5 上的生物学标记仍以拒绝结束。如果您没有设置它，网络安全标记的请求会在 Opus 4.8 条目上重新运行，来自 Fable 模型或 Opus 5.5 的生物学标记请求会在 Opus 5 条目上重新运行。从 Sonnet 5.5，网络安全标记的请求会在您在 `ANTHROPIC_DEFAULT_SONNET_MODEL` 中设置的模型上重新运行，或在提供商模型列表中的 Sonnet 5 条目上（如果您没有设置它）。600* 标记的类别的备用模型必须在您的部署中解析。从 Fable 模型、Opus 5.5 或 Opus 5，如果您设置了 `ANTHROPIC_DEFAULT_OPUS_MODEL`，标记的请求会在该模型上为每个具有回退的类别重新运行；Opus 5 上的生物学标记仍以拒绝结束。如果您没有设置它，网络安全标记的请求会在 Opus 4.8 条目上重新运行，来自 Fable 模型或 Opus 5.5 的生物学标记请求会在 Opus 5 条目上重新运行。从 Sonnet 5.5，网络安全标记的请求会在您在 `ANTHROPIC_DEFAULT_SONNET_MODEL` 中设置的模型上重新运行，或在提供商模型列表中的 Sonnet 5 条目上（如果您没有设置它）。

588 601

596 609

597#### 安全研究和生物学工作负载610#### 安全研究和生物学工作负载

598 611

599进攻性安全或生物学中的工作负载，包括渗透测试、Capture the Flag (CTF) 练习和生物学相邻代码库，经常触发回退，通常在第一个请求上。对于 Fable 5.1、Fable 5 或 Opus 5.5 上的实质性生物学工作，第一个切换模型的标记请求会将会话移动到 Opus 5，后来的生物学标记请求在那里以拒绝结束，因为 Opus 5 没有生物学回退。在 Opus 5 和 Sonnet 5.5 上，您从第一个标记的请求获得这些拒绝。612进攻性安全或生物学中的工作负载，包括渗透测试、Capture the Flag (CTF) 练习和生物学相邻代码库，经常触发回退，通常在第一个请求上。这是这些域的预期路由，不是账户标记。如果您的组织需要 Fable 级别的能力来完成这项工作，请向您的 Anthropic 账户团队询问受信任的访问计划。

600 613

601这是这些域的预期路由，不是账户标记。如果您的组织需要 Fable 级别的能力来完成这项工作，请向您的 Anthropic 账户团队询问受信任的访问计划。614对于 Fable 模型或 Opus 5.5 上的实质性生物学工作，第一个切换模型的标记请求会将会话移动到 Opus 5。后来的生物学标记请求在那里以拒绝结束，因为 Opus 5 没有生物学回退。在 Opus 5 和 Sonnet 5.5 上，这些拒绝从第一个标记的请求开始。

602 615

603### 调整 effort 级别616### 调整 effort 级别

604 617

608 621

609| 模型 | 级别 |622| 模型 | 级别 |

610| :- | :- |623| :- | :- |

614 627

6202. 您在会话中选择的级别，例如通过 `/effort`、`/model` 选择器或 [`applyFlagSettings()`](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#applyflagsettings)6332. 您在会话中选择的级别，例如通过 `/effort`、`/model` 选择器或 [`applyFlagSettings()`](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#applyflagsettings)

6213. 使用 `--effort` 启动6343. 使用 `--effort` 启动

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

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

624 637

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

626 639

671| 级别 | 何时使用 |684| 级别 | 何时使用 |

672| :- | :- |685| :- | :- |

673| `low` | 快速交换，您审查每个结果，例如头脑风暴、初稿或小改动如重命名 |686| `low` | 快速交换，您审查每个结果，例如头脑风暴、初稿或小改动如重命名 |

674| `medium` | Opus 5.5、Sonnet 5.5 和 Haiku 5.5 上的默认值。在 Opus 5.5 和 Sonnet 5.5 上，它适合具有明确范围的日常工程工作，例如实现新功能。在默认值更高的模型上，减少成本敏感工作的 token 使用，可以权衡一些智能 |687| `medium` | Fable 5.2、Opus 5.5、Sonnet 5.5 和 Haiku 5.5 模型上的默认值。在 Opus 5.5 和 Sonnet 5.5 上，它适合具有明确范围的日常工程工作，例如实现新功能。在默认值更高的模型上，减少成本敏感工作的 token 使用，可以权衡一些智能 |

677| `max` | 您想让 Claude 自己完成的难题，例如发现安全漏洞。`max` 可能显示收益递减，容易过度思考，所以在广泛采用前测试 |690| `max` | 您想让 Claude 自己完成的难题，例如发现安全漏洞。`max` 可能显示收益递减，容易过度思考，所以在广泛采用前测试 |

691 704

692* 在不以 `/` 开头的提示词中重新键入该词，并确保它不在引号、括号、路径或命令等任何内容之内705* 在不以 `/` 开头的提示词中重新键入该词，并确保它不在引号、括号、路径或命令等任何内容之内

693* 如果 `CLAUDE_CODE_EFFORT_LEVEL` 设置为低于 `xhigh` 的级别，请取消设置它。或者将您自己的 [`maxEffortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#maxeffortlevel) 提高到 `xhigh` 或更高，或请组织管理员提高您的[组织限制](#organization-effort-limits)706* 如果 `CLAUDE_CODE_EFFORT_LEVEL` 设置为低于 `xhigh` 的级别，请取消设置它。或者将您自己的 [`maxEffortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#maxeffortlevel) 提高到 `xhigh` 或更高，或请组织管理员提高您的[组织限制](#organization-effort-limits)

694* 在会话中运行 `/model` 切换到 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 5.1 模型。在该词无法提升轮次的情况下（例如在 Amazon Bedrock 上），请改为[设置 effort 级别](#set-the-effort-level)707* 在会话中运行 `/model` 切换到 Opus 5.5、Sonnet 5.5、Haiku 5.5、Fable 5.2 或 Fable 5.1 模型。在该词无法提升轮次的情况下（例如在 Amazon Bedrock 上），请改为[设置 effort 级别](#set-the-effort-level)

695 708

696#### 设置 effort 级别709#### 设置 effort 级别

697 710

767 780

768### 扩展上下文781### 扩展上下文

769 782

770Fable 5.1、Fable 5、Sonnet 5 及更高版本、Haiku 5.5、Opus 4.6 及更高版本和 Sonnet 4.6 支持[100 万 token 上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)，用于具有大型代码库的长会话。783具有大型代码库的长会话可以使用 [100 万 token 上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)。Fable 模型、Sonnet 5 及更高版本、Haiku 5.5、Opus 4.6 及更高版本和 Sonnet 4.6 支持它。

771 784

772Fable 5.1、Fable 5、Sonnet 5 及更高版本、Haiku 5.5 和 Opus 4.7 及更高版本默认运行 1M 窗口，无需 `[1m]` 后缀。这包括 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的会话，以及 [Claude apps gateway](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 会话。要改为以 200K 窗口运行它们，请参阅[关闭 1M 上下文](#turn-off-1m-context)。785Fable 模型、Sonnet 5 及更高版本、Haiku 5.5 和 Opus 4.7 及更高版本默认运行 1M 窗口，无需 `[1m]` 后缀。这包括 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的会话，以及 [Claude apps gateway](https://code.claude.com/docs/zh-CN/claude-apps-gateway) 会话。要改为以 200K 窗口运行它们，请参阅[关闭 1M 上下文](#turn-off-1m-context)。

773 786

774Opus 4.6 和 Sonnet 4.6 仅通过其 `[1m]` 变体达到 1M，对该变体的访问取决于您的套餐。在 Max、Ultra、Team 和 Enterprise 套餐上，包括 Team Standard 和 Team Premium 席位，Opus 4.6 与 1M 上下文包含在您的订阅中。Sonnet 4.6 与 1M 上下文在每个订阅套餐上都需要[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，包括 Max 和 Ultra。787Opus 4.6 和 Sonnet 4.6 仅通过其 `[1m]` 变体达到 1M，对该变体的访问取决于您的套餐。在 Max、Ultra、Team 和 Enterprise 套餐上，包括 Team Standard 和 Team Premium 席位，Opus 4.6 与 1M 上下文包含在您的订阅中。Sonnet 4.6 与 1M 上下文在每个订阅套餐上都需要[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，包括 Max 和 Ultra。

775 788

798 811

799#### LLM 网关后面的上下文窗口812#### LLM 网关后面的上下文窗口

800 813

801如果您将 `ANTHROPIC_BASE_URL` 设置为 [LLM 网关](https://code.claude.com/docs/zh-CN/llm-gateway)或另一个代理，Claude Code 给每个它识别的模型与该模型在 Anthropic API 上具有的相同上下文窗口。Fable 5.1、Fable 5、Sonnet 5 及更高版本、Haiku 5.5 和 Opus 4.7 及更高版本获得 1M 窗口，没有 `[1m]` 变体可选择，仅通过其 `[1m]` 变体达到 1M 的模型（如 Opus 4.6）在没有它的情况下运行在 200K。Claude Code 无法检测网关或其后面的服务器强制的更低限制。如果您的网关拒绝超过 200K token 的请求，请在启动 Claude Code 的环境中设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](https://code.claude.com/docs/zh-CN/env-vars)，以便所有模型上的会话都[在该边界处压缩](#set-the-auto-compact-window)。814如果您将 `ANTHROPIC_BASE_URL` 设置为 [LLM 网关](https://code.claude.com/docs/zh-CN/llm-gateway)或另一个代理，Claude Code 给每个它识别的模型与该模型在 Anthropic API 上具有的相同上下文窗口。Fable 模型、Sonnet 5 及更高版本、Haiku 5.5 和 Opus 4.7 及更高版本获得 1M 窗口，无需 `[1m]` 变体。仅通过其 `[1m]` 变体达到 1M 的模型（如 Opus 4.6）在没有它的情况下运行在 200K。

815

816Claude Code 无法检测网关或其后面的服务器强制的更低限制。如果您的网关拒绝超过 200K token 的请求，请在启动 Claude Code 的环境中设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000`](https://code.claude.com/docs/zh-CN/env-vars)，以便所有模型上的会话都[在该边界处压缩](#set-the-auto-compact-window)。

802 817

803#### 关闭 1M 上下文818#### 关闭 1M 上下文

804 819

885 900

886一旦 Claude Code 识别了该 ID 或使用了您提供的窗口，在该 ID 上启动会话时就不会再出现该警告。901一旦 Claude Code 识别了该 ID 或使用了您提供的窗口，在该 ID 上启动会话时就不会再出现该警告。

887 902

903#### 修正拼错的模型名称

904

905以下任一警告都表示 Claude Code 无法识别您设置的模型 ID，且该 ID 的拼写与它能识别的某个模型名称或别名非常接近：

906

907```text theme={null}

908⚠ Model "<model>" isn't recognized · did you mean "<suggestion>"?

909Claude Code doesn't recognize the model "<model>". Did you mean "<suggestion>"?

910```

911

912* **您拼错了 ID**：在[您设置模型的位置](#setting-your-model)将其改为建议的名称

913* **该 ID 是有意设置的**：保持原样即可。会话会按您填写的内容原样发送该 ID。如果 Claude Code 为其假设的上下文窗口不正确，请[更正窗口](#correct-the-window-for-a-gateway-or-custom-model-id)

914

888#### `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 适用于哪些 ID915#### `CLAUDE_CODE_MAX_CONTEXT_TOKENS` 适用于哪些 ID

889 916

890在 [LLM 网关](https://code.claude.com/docs/zh-CN/llm-gateway)或其他自定义部署上，Claude Code 可能会为模型 ID 假设一个与模型实际窗口不同的上下文窗口，无论它是否将 ID 解析为 Claude 模型。设置 [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](https://code.claude.com/docs/zh-CN/env-vars) 为 Claude Code 应该假设的窗口。917在 [LLM 网关](https://code.claude.com/docs/zh-CN/llm-gateway)或其他自定义部署上，Claude Code 可能会为模型 ID 假设一个与模型实际窗口不同的上下文窗口，无论它是否将 ID 解析为 Claude 模型。设置 [`CLAUDE_CODE_MAX_CONTEXT_TOKENS`](https://code.claude.com/docs/zh-CN/env-vars) 为 Claude Code 应该假设的窗口。

1099 1126

1100| 版本 | 更改 |1127| 版本 | 更改 |

1101| :- | :- |1128| :- | :- |

1129| v2.1.321 | `fable` 解析为 Fable 5.2，Claude 应用网关会话中除外 |

1130| v2.1.321 | `best` 解析为与 `opus` 相同的模型。在可使用 Fable 的情况下，更早版本使用 `fable` 所解析的模型 |

1102| v2.1.293 | `haiku` 在 Anthropic API 上解析为 Haiku 5.5 |1131| v2.1.293 | `haiku` 在 Anthropic API 上解析为 Haiku 5.5 |

1103| v2.1.284 | `sonnet` 在 Anthropic API 上解析为 Sonnet 5.5 |1132| v2.1.284 | `sonnet` 在 Anthropic API 上解析为 Sonnet 5.5 |

1104| v2.1.280 | `opus` 在 Anthropic API、AWS 上的 Claude Platform、Amazon Bedrock 和 Google Cloud 的 Agent Platform 上解析为 Opus 5.5 |1133| v2.1.280 | `opus` 在 Anthropic API、AWS 上的 Claude Platform、Amazon Bedrock 和 Google Cloud 的 Agent Platform 上解析为 Opus 5.5 |

permissions.md +2 −1

Details

253| :- | :- | :- |253| :- | :- | :- |

257 257

258您的其他规则和权限模式决定最后一列中的命令。258您的其他规则和权限模式决定最后一列中的命令。

259 259

273* **`docker` 指向另一个守护程序**：当命令携带选择不同守护程序的标志时，`docker` 的只读形式提示，如 `-H`、`--context` 或 Podman 的 `--url` 和 `--connection`。273* **`docker` 指向另一个守护程序**：当命令携带选择不同守护程序的标志时，`docker` 的只读形式提示，如 `-H`、`--context` 或 Podman 的 `--url` 和 `--connection`。

274* **`file` 带有路径打开标志**：当 `file` 传递 `-m`/`--magic-file` 或 `-f`/`--files-from` 时，`file` 提示，因为这些标志使 `file` 打开标志值中命名的路径。274* **`file` 带有路径打开标志**：当 `file` 传递 `-m`/`--magic-file` 或 `-f`/`--files-from` 时，`file` 提示，因为这些标志使 `file` 打开标志值中命名的路径。

275* **可能打印环境变量的 `ps`**：当 `ps` 的某个参数可能充当 `e` 选项时（如 `ps auxe` 或 `ps aux -e`），`ps` 会提示，因为该选项会打印进程环境变量。`ps aux` 和 `ps -ef` 无需提示即可运行。对 `ps aux -e` 等带短横线形式的检查需要 Claude Code v2.1.290 或更高版本。275* **可能打印环境变量的 `ps`**：当 `ps` 的某个参数可能充当 `e` 选项时（如 `ps auxe` 或 `ps aux -e`），`ps` 会提示，因为该选项会打印进程环境变量。`ps aux` 和 `ps -ef` 无需提示即可运行。对 `ps aux -e` 等带短横线形式的检查需要 Claude Code v2.1.290 或更高版本。

276* **带有查找和显示以外标志的 `which`**：当 `which` 传递 `-i`/`--read-alias` 或 `--read-functions` 等标志时会提示。`which node` 和 `which -a node` 无需提示即可运行。

276* **Windows 上的网络路径**：其参数包括网络 (UNC) 路径的命令，如 `\\server\share\file`，提示是因为访问网络路径可能会将您的 Windows 凭据发送到它命名的主机。同样的检查适用于[PowerShell 工具](https://code.claude.com/docs/zh-CN/tools-reference.md#powershell-tool)命令。277* **Windows 上的网络路径**：其参数包括网络 (UNC) 路径的命令，如 `\\server\share\file`，提示是因为访问网络路径可能会将您的 Windows 凭据发送到它命名的主机。同样的检查适用于[PowerShell 工具](https://code.claude.com/docs/zh-CN/tools-reference.md#powershell-tool)命令。

277* **写入特殊 shell 变量**：设置、取消设置或遍历某些特殊 shell 变量（如 `PATH` 或 `IFS`）的命令会提示，即使命令的其余部分是只读的。278* **写入特殊 shell 变量**：设置、取消设置或遍历某些特殊 shell 变量（如 `PATH` 或 `IFS`）的命令会提示，即使命令的其余部分是只读的。

278* **分析无法解析的命令**：当 Claude Code 无法完全解析命令时，它会要求批准而不是将命令视为只读。超过 10,000 个字符的命令总是提示，因为它们超过了分析解析的内容。279* **分析无法解析的命令**：当 Claude Code 无法完全解析命令时，它会要求批准而不是将命令视为只读。超过 10,000 个字符的命令总是提示，因为它们超过了分析解析的内容。

plugins/mods/events.md +1 −1

Details

279* **您的 hook 在其 `next(e)` 调用已放行提示词之后返回 `drop`**：轮次仍会运行，并且该 hook 会[失败](#handle-a-hook-that-fails)，错误消息中包含 `a drop after its next() was answered`279* **您的 hook 在其 `next(e)` 调用已放行提示词之后返回 `drop`**：轮次仍会运行，并且该 hook 会[失败](#handle-a-hook-that-fails)，错误消息中包含 `a drop after its next() was answered`

280* **您的 hook 抛出异常或超时**：Claude Code 会跳过它并发送提示词。请[添加 `.catch` 处理程序](#handle-a-hook-that-fails)，以免失败时发送了本应被该 hook 阻止的提示词。280* **您的 hook 抛出异常或超时**：Claude Code 会跳过它并发送提示词。请[添加 `.catch` 处理程序](#handle-a-hook-that-fails)，以免失败时发送了本应被该 hook 阻止的提示词。

281 281

282[其他事件](https://code.claude.com/docs/zh-CN/plugins/mods/reference.md#prompts-and-what-claude-reads)涵盖了 Claude 读取的其余内容：`prompt.section` 用于系统提示词的每个部分，`prompt.context` 用于随第一条消息发送的上下文，`skill.prompt` 用于 skill 的文本。这些 hook 产生的文本如果在请求之间发生变化，会[使提示缓存失效](https://code.claude.com/docs/zh-CN/prompt-caching.md)。在 `skill.prompt` hook 中，您还可以读取[该 skill 来自哪个插件或文件](https://code.claude.com/docs/zh-CN/plugins/mods/reference.md#skill-prompt-fields)。282[其他事件](https://code.claude.com/docs/zh-CN/plugins/mods/reference.md#prompts-and-what-claude-reads)涵盖了 Claude 读取的其余内容：`prompt.section` 用于系统提示词的每个部分，`prompt.context` 用于随第一条消息发送的上下文，`skill.prompt` 用于 skill 的文本。要在对话开始后更改某个部分，请参阅[发送更改后的系统提示词部分或工具描述](https://code.claude.com/docs/zh-CN/plugins/mods/reference.md#break-prompt-cache)。在 `skill.prompt` hook 中，您还可以读取[该 skill 来自哪个插件或文件](https://code.claude.com/docs/zh-CN/plugins/mods/reference.md#skill-prompt-fields)。

283 283

284### 跟踪轮次284### 跟踪轮次

285 285

plugins/mods/interface.md +87 −0

Details

197>197>

198> 要在条带中绘制，请过滤 `{ component: 'AbovePrompt' }`。198> 要在条带中绘制，请过滤 `{ component: 'AbovePrompt' }`。

199 199

200mod 还可以[在会话记录中放置自己的一行](#place-a-row-in-the-transcript)。

201

200### 更改 Claude Code 已经绘制的内容202### 更改 Claude Code 已经绘制的内容

201 203

202Claude Code 自己绘制大部分界面：消息、工具调用行、加载指示器等。这些部分中的每一个也是一个渲染站点，因此 mod 可以重新设置其样式或替换它。要更改其中一个，请让您的 `ui.render` hook 按此表中的名称进行过滤：204Claude Code 自己绘制大部分界面：消息、工具调用行、加载指示器等。这些部分中的每一个也是一个渲染站点，因此 mod 可以重新设置其样式或替换它。要更改其中一个，请让您的 `ui.render` hook 按此表中的名称进行过滤：

349* **提示词建议**：`$.prompt.suggest` 会以 `isShown: false` 解析且不显示任何内容，因为面板将输入框中的灰色建议文本保留给 Claude 自己的建议。351* **提示词建议**：`$.prompt.suggest` 会以 `isShown: false` 解析且不显示任何内容，因为面板将输入框中的灰色建议文本保留给 Claude 自己的建议。

350* **文本限制**：面板会将状态栏截断为 200 个字符或两行，将 toast 截断为 500 个字符。352* **文本限制**：面板会将状态栏截断为 200 个字符或两行，将 toast 截断为 500 个字符。

351 353

354### 在会话记录中放置一行

355

356行是您的 mod 在终端中添加到会话记录里、位于最新消息之后的一行内容。随着对话的进行，它会停留在该位置，并且 Claude 看不到它。`$.ui.place` 需要 Claude Code v2.1.314 或更高版本。

357

358**1. 放置行**

359

360使用一个 `id` 调用 [`$.ui.place`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#mods-api-methods)。`id` 是您为该行自拟的名称，例如 `build-status`。它可以包含 1 到 64 个字母、数字、`_` 或 `-`，并且您的 mod 在会话记录中的每一行都需要有自己的 `id`。

361

362**2. 绘制行**

363

364在 [`Placed`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#render-sites) 渲染位置绘制该行。

365

366此示例添加了一个 `/build-status` 命令。当用户运行该命令时，mod 会添加一行显示 `Build: passing` 的内容。为了让示例保持简短，文本是固定的，实际的 mod 会绘制自己的结果：

367

368```javascript theme={null}

369export function register(on) {

370 on('session.start', async ($, e, next) => {

371 await $.command.register({ name: 'build-status', description: 'Show the build status' })

372 return next(e)

373 })

374

375 on('command.run', { command: 'build-status' }, async ($) => {

376 const placed = await $.ui.place({ id: 'build-status' })

377 // Where nothing draws the row, reply with text instead

378 return placed.isPlaced ? {} : { text: 'Build: passing' }

379 })

380

381 on('ui.render', { component: 'Placed' }, async ($, e, next) => {

382 // This hook runs for every mod's rows, and another mod can use the same id

383 if (e.props.plugin !== $.plugin.name || e.props.id !== 'build-status') return next(e)

384 const { Text } = $.ui.resolve(e)

385 return Text({ children: ['Build: passing'] })

386 })

387}

388```

389

390要试用此示例，请将这段代码放入一个 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/create.md) 中。在终端会话中，于 Claude Code 提示符处运行 `/build-status`。`Build: passing` 会作为一行出现在会话记录的末尾。

391

392该调用并不总是会显示一行，而且一行之后也可能消失，因此请在您的 mod 中处理以下情况：

393

394* **结果**：当终端绘制该行时，结果为 `{ isPlaced: true, requestId }`。否则 `isPlaced` 为 `false`，`reason` 说明原因，例如 `no attached surface draws placed rows yet`。其中一个原因是 mod 同一时间可拥有的[行数限制](https://code.claude.com/docs/zh-CN/plugins/mods/reference.md#limits)。

395* **使用相同 `id` 的第二次调用**：当第一行仍在会话记录中时，该调用不会添加新行，而是以该行的 `requestId` 解析。要更改该行显示的内容，请[重新绘制该行](#redraw-when-something-changes)。

396* **行何时消失**：对话结束时、用户回退到该行之前时，或者在[全屏渲染](https://code.claude.com/docs/zh-CN/fullscreen.md)之外对话被压缩时。`--resume` 不会恢复该行。要再次显示该行，请再次调用 `$.ui.place`。

397

398### 在对话后方放置背景

399

400> [!NOTE]

401>

402> `$.theme.set` 和 `$.theme.clear` 取代了 `$.ui.backdrop`，后者已在 Claude Code v2.1.319 中移除。请将 `$.ui.backdrop({ id: 'your-backdrop' })` 改为 `$.theme.set({ backdrop: { id: 'your-backdrop' } })`，将 `$.ui.backdrop(undefined)` 改为 `$.theme.clear()`，后者会移除任何 mod 设置的背景。

403

404要在 Desktop 应用或移动应用中于对话后方放置背景，请使用 `backdrop` 调用 [`$.theme.set`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#mods-api-methods)，然后在 [`Backdrop`](https://code.claude.com/docs/zh-CN/plugins/mods/reference#render-sites) 渲染位置绘制该背景。要移除背景，请调用 `$.theme.clear()`。终端不绘制背景。`$.theme.set` 和 `$.theme.clear` 需要 Claude Code v2.1.319 或更高版本。

405

406此 mod 在会话开始时设置背景、绘制该背景，并添加一个用于移除背景的 `/plain` 命令：

407

408```javascript theme={null}

409export function register(on) {

410 // Neither a reload of this mod nor --resume keeps the backdrop, so set it here

411 on('session.start', async ($, e, next) => {

412 await $.theme.set({ backdrop: { id: 'night-sky', colorScheme: 'dark' } })

413 await $.command.register({ name: 'plain', description: 'Take the backdrop off' })

414 return next(e)

415 })

416

417 on('ui.render', { component: 'Backdrop' }, async ($, e, next) => {

418 // This hook runs for every mod's backdrop, and another mod can use the same id

419 if (e.props.plugin !== $.plugin.name || e.props.id !== 'night-sky') return next(e)

420 const { Box, Text } = $.ui.resolve(e)

421 return Box({ backgroundColor: 'blue', children: [Text({ children: ['Night sky'] })] })

422 })

423

424 on('command.run', { command: 'plain' }, async ($) => {

425 const cleared = await $.theme.clear()

426 return { text: cleared.reason }

427 })

428}

429```

430

431要试用此示例，请将这段代码放入一个 [mod](https://code.claude.com/docs/zh-CN/plugins/mods/create.md) 中，并在 Desktop 应用或移动应用中启动一个会话。要移除背景，请在 Claude Code 提示符处运行 `/plain`。会话记录会在 mod 名称后显示 `the theme is cleared`，例如对于名为 `night-sky` 的 mod，显示为 `night-sky: the theme is cleared`。

432

433请了解 `backdrop` 接受哪些内容、调用结果会告诉您什么，以及其他 mod 可以更改什么：

434

435* **`backdrop` 字段**：`id` 是您选择的[名称](https://code.claude.com/docs/zh-CN/plugins/mods/reference.md#limits)，为必填项，其他字段均为可选。`colorScheme` 为 `'light'` 或 `'dark'`，用于说明您绘制的内容是浅色还是深色。有关 `glass`，请参阅[适用于您所用版本的类型](https://code.claude.com/docs/zh-CN/plugins/mods/create.md#get-the-types-for-your-build)。

436* **背景是否被绘制**：当连接到该会话的 Desktop 或移动应用表示它会绘制背景时，`$.theme.set` 以 `isDrawn: true` 解析。否则 `isDrawn` 为 `false`，`reason` 说明原因。

437* **每个会话一个背景**：无论背景是由哪个 mod 设置的，`$.theme.set` 调用都会替换会话的背景，`$.theme.clear()` 都会移除该背景。请仅在用户要求时调用 `$.theme.clear()`。

438

352## 从元素构建树439## 从元素构建树

353 440

354`ui.render` hook 返回的是一个元素树：对要绘制的内容的描述，由相互嵌套的框、文本和控件组成。您描述绘制，Claude Code 会在用户打开的任一应用中呈现它：终端、桌面应用或 VS Code 扩展。441`ui.render` hook 返回的是一个元素树：对要绘制的内容的描述，由相互嵌套的框、文本和控件组成。您描述绘制，Claude Code 会在用户打开的任一应用中呈现它：终端、桌面应用或 VS Code 扩展。

plugins/mods/reference.md +14 −4

Details

57| :- | :- | :- |57| :- | :- | :- |

58| [`tool.call`](https://code.claude.com/docs/zh-CN/plugins/mods/events#guard-or-change-a-tool-call) | 工具即将运行 | `next(e)`、`{ deny: reason }` 或 `{ result }` |58| [`tool.call`](https://code.claude.com/docs/zh-CN/plugins/mods/events#guard-or-change-a-tool-call) | 工具即将运行 | `next(e)`、`{ deny: reason }` 或 `{ result }` |

59| [`tool.check`](https://code.claude.com/docs/zh-CN/plugins/mods/events#where-settings-hooks-run-in-the-order) | Claude Code 在 `tool.call` 和 `PreToolUse` hook 之后决定是否允许运行某个工具调用。`next(e)` 解析为规则、权限模式和这些 hook 得出的决定。 | `next(e)` 或 `{ decision }`，其中 `decision` 设为 `allow`、`ask` 或 `deny`，并可附带可选的 `reason` |59| [`tool.check`](https://code.claude.com/docs/zh-CN/plugins/mods/events#where-settings-hooks-run-in-the-order) | Claude Code 在 `tool.call` 和 `PreToolUse` hook 之后决定是否允许运行某个工具调用。`next(e)` 解析为规则、权限模式和这些 hook 得出的决定。 | `next(e)` 或 `{ decision }`，其中 `decision` 设为 `allow`、`ask` 或 `deny`，并可附带可选的 `reason` |

60| `tool.describe` | 每个工具一次，在其描述首次发送给 Claude 时。对于 MCP 工具，当 Claude 通过[工具搜索](https://code.claude.com/docs/zh-CN/mcp.md#scale-with-mcp-tool-search)加载它时会再触发一次，此时 `e.description` 设为 Claude 针对已加载工具读取的文本。 | `{ description }`，可选择将 `isDeferred` 设为 `true` 以将该工具置于工具搜索之后，或设为 `false` 以预先加载它 |60| `tool.describe` | 每个工具一次，在其描述首次发送给 Claude 时。对于 MCP 工具，当 Claude 通过[工具搜索](https://code.claude.com/docs/zh-CN/mcp.md#scale-with-mcp-tool-search)加载它时会再触发一次，此时 `e.description` 设为 Claude 针对已加载工具读取的文本。 | `{ description }`，可选择将 `isDeferred` 设为 `true` 以将该工具置于工具搜索之后，或设为 `false` 以预先加载它。添加 [`breakPromptCache: true`](#break-prompt-cache) 可在下一轮次发送更改后的描述。 |

61 61

62#### `tool.check` 上的 Agent 和组织字段62#### `tool.check` 上的 Agent 和组织字段

63 63

86| `prompt.autocomplete` | 用户在输入框中输入内容，且光标处有一个词结束。`e.token` 即该词。Claude Code 不会等待该 hook：其自身的自动补全行会先显示。 | `{ suggestions }`，一个由 `{ text, label, description }` 行组成的列表，显示在 Claude Code 自身的行下方。选择某一行会用其 `text` 覆盖该词。 |86| `prompt.autocomplete` | 用户在输入框中输入内容，且光标处有一个词结束。`e.token` 即该词。Claude Code 不会等待该 hook：其自身的自动补全行会先显示。 | `{ suggestions }`，一个由 `{ text, label, description }` 行组成的列表，显示在 Claude Code 自身的行下方。选择某一行会用其 `text` 覆盖该词。 |

87| `prompt.compose` | Claude Code 渲染系统提示词 | `{ sections }`，一个按发送顺序排列的 `{ id, text, scope }` 列表 |87| `prompt.compose` | Claude Code 渲染系统提示词 | `{ sections }`，一个按发送顺序排列的 `{ id, text, scope }` 列表 |

88| [`prompt.section`](https://code.claude.com/docs/zh-CN/plugins/mods/events#rewrite-or-add-to-a-prompt) | 系统提示词的每个命名部分一次。`e.name` 是该部分在 `prompt.compose` 中的 `id`。 | `{ text }`，或 `{ text: null }` 以省略该部分 |88| [`prompt.section`](https://code.claude.com/docs/zh-CN/plugins/mods/events#rewrite-or-add-to-a-prompt) | 系统提示词的每个命名部分一次。`e.name` 是该部分在 `prompt.compose` 中的 `id`。 | `{ text }`，或 `{ text: null }` 以省略该部分。添加 [`breakPromptCache: true`](#break-prompt-cache) 可在下一轮次发送更改后的部分。 |

89| [`prompt.context`](https://code.claude.com/docs/zh-CN/plugins/mods/events#rewrite-or-add-to-a-prompt) | 每个对话一次，用于随第一条消息发送的上下文 | `{ blocks }` |89| [`prompt.context`](https://code.claude.com/docs/zh-CN/plugins/mods/events#rewrite-or-add-to-a-prompt) | 每个对话一次，用于随第一条消息发送的上下文 | `{ blocks }` |

90| `prompt.attachment` | Claude Code 为 Claude 添加一条它自己的消息，例如提醒。`e.type` 指明消息类型；对于类型声明中已声明的类型，`e.detail` 包含编写该文本所依据的事实。 | `{ text }`，或 `{ text: null }` 以省略它 |90| `prompt.attachment` | Claude Code 为 Claude 添加一条它自己的消息，例如提醒。`e.type` 指明消息类型；对于类型声明中已声明的类型，`e.detail` 包含编写该文本所依据的事实。 | `{ text }`，或 `{ text: null }` 以省略它 |

91| `prompt.mention` | Claude Code 即将读取提示词中 @ 提及的文件。需要 Claude Code v2.1.290 或更高版本。 | `next({ ...e, path })` 以读取其他文件，或 `{ deny: reason }` |91| `prompt.mention` | Claude Code 即将读取提示词中 @ 提及的文件。需要 Claude Code v2.1.290 或更高版本。 | `next({ ...e, path })` 以读取其他文件，或 `{ deny: reason }` |

108 108

109在 `skill.prompt` 上，`e.source`、`e.pluginName`、`e.path`、`e.frontmatter` 和 `e.frontmatterProblem` 需要 Claude Code v2.1.299 或更高版本。109在 `skill.prompt` 上，`e.source`、`e.pluginName`、`e.path`、`e.frontmatter` 和 `e.frontmatterProblem` 需要 Claude Code v2.1.299 或更高版本。

110 110

111#### 使用 `breakPromptCache` 发送更改后的系统提示词部分或工具描述

112

113要在正在运行的对话中更改某个部分或工具描述，请调用 `$.ui.invalidate('prompt.section')` 或 `$.ui.invalidate('tool.describe')`，使您的 hook 再次运行，并从中返回 `{ text, breakPromptCache: true }` 或 `{ description, breakPromptCache: true }`。如果没有该字段，对于某个部分或预先加载的工具，Claude 会继续读取[随对话保存](https://code.claude.com/docs/zh-CN/cli-reference.md#system-prompt-flags-in-resumed-conversations)的文本，直到开始新对话或进行[压缩](https://code.claude.com/docs/zh-CN/prompt-caching.md#compacting-the-conversation)。

114

115更改后的文本会在下一轮次传达给 Claude，并且[提示缓存](https://code.claude.com/docs/zh-CN/prompt-caching.md)会重新开始，因此该轮次会更慢且成本更高。该字段需要 Claude Code v2.1.321 或更高版本。从 v2.1.299 到 v2.1.321 之前，正在运行的对话会在下一轮次获得更改后的文本。

116

111### 命令和配置117### 命令和配置

112 118

113| 事件 | 触发时机 | hook 可以返回 |119| 事件 | 触发时机 | hook 可以返回 |

212| 命名空间 | 方法 |218| 命名空间 | 方法 |

213| :- | :- |219| :- | :- |

215| [`$.ui`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、`focus`、`scroll`、`toast`、`notify`、`status`、`log`、`notice`、`ask`、`copy`、`selection`、`blit` |221| [`$.ui`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#pick-where-to-draw) | `resolve`、`invalidate`、`open`、`close`、`panes`、[`place`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#place-a-row-in-the-transcript)、`focus`、`scroll`、`toast`、`notify`、`status`、`log`、`notice`、`ask`、`copy`、`selection`、`blit`、`view`。`view` 需要 Claude Code v2.1.300 或更高版本，`place` 需要 v2.1.314 或更高版本。 |

222| [`$.theme`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`、`clear`：设置一个由 Desktop 或移动应用绘制的背景，以及移除该背景。需要 Claude Code v2.1.319 或更高版本。 |

218| `$.agent` | `register`、`spawn`、`list`。`list()` 返回此会话的子代理和队友，每项都带有 `status`，其值为 `pending`、`running`、`waiting`、`idle`、`completed`、`failed` 或 `killed` 之一，其中 `idle` 和 `waiting` 需要 Claude Code v2.1.289 或更高版本。 |225| `$.agent` | `register`、`spawn`、`list`。`list()` 返回此会话的子代理和队友，每项都带有 `status`，其值为 `pending`、`running`、`waiting`、`idle`、`completed`、`failed` 或 `killed` 之一，其中 `idle` 和 `waiting` 需要 Claude Code v2.1.289 或更高版本。 |

243| :- | :- | :- | :- |250| :- | :- | :- | :- |

254| [`Backdrop`](https://code.claude.com/docs/zh-CN/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `id`、`plugin`、`glass`、`colorScheme` | `backdrop` | `desktop` 和 `mobile` 使用入口。当 Desktop 或移动应用请求绘制背景时，您的 hook 会运行。 |

400| `$.ui.toast` | 显示 4 秒，除非您传入 `{ timeoutMs }`。在[经典渲染器](https://code.claude.com/docs/zh-CN/fullscreen.md#enable-fullscreen-rendering)中，mod 较新的 toast 可能会[取代其较早的 toast](https://code.claude.com/docs/zh-CN/plugins/mods/troubleshoot.md#a-toast-doesn’t-appear)，无论较早的 toast 正在显示还是正在等待显示。 |409| `$.ui.toast` | 显示 4 秒，除非您传入 `{ timeoutMs }`。在[经典渲染器](https://code.claude.com/docs/zh-CN/fullscreen.md#enable-fullscreen-rendering)中，mod 较新的 toast 可能会[取代其较早的 toast](https://code.claude.com/docs/zh-CN/plugins/mods/troubleshoot.md#a-toast-doesn’t-appear)，无论较早的 toast 正在显示还是正在等待显示。 |

401| 非用户主动打开的窗格 | 终端至少 144 列宽时放置；用户打开过一次后，110 列宽即可 |410| 非用户主动打开的窗格 | 终端至少 144 列宽时放置；用户打开过一次后，110 列宽即可 |

411| 单个 mod 在一个对话中同时拥有的来自 `$.ui.place` 的行 | 500。达到此限制时，使用新 `id` 的调用会解析为 `{ isPlaced: false, reason: 'a plugin holds at most 500 placed rows' }`。 |

402| mods API 调用参数的嵌套深度 | 28,000 层。超过此深度，调用会被拒绝，消息以 `nesting deeper than 28000 levels is not supported` 结尾。需要 Claude Code v2.1.299 或更高版本。 |412| mods API 调用参数的嵌套深度 | 28,000 层。超过此深度，调用会被拒绝，消息以 `nesting deeper than 28000 levels is not supported` 结尾。需要 Claude Code v2.1.299 或更高版本。 |

403| 传递给 `next` 的已更改事件的嵌套深度，[异步生成器 hook](#events)（例如 `turn.step` 上的 hook）除外 | 28,000 层。超过此深度，`next` 会拒绝，消息以 `nesting deeper than 28000 levels is not supported` 结尾。需要 Claude Code v2.1.299 或更高版本。 |413| 传递给 `next` 的已更改事件的嵌套深度，[异步生成器 hook](#events)（例如 `turn.step` 上的 hook）除外 | 28,000 层。超过此深度，`next` 会拒绝，消息以 `nesting deeper than 28000 levels is not supported` 结尾。需要 Claude Code v2.1.299 或更高版本。 |

404| hook 返回值的嵌套深度，`ui.render`、`ui.resolve` 和异步生成器 hook 除外 | 28,000 层。超过此深度，该 hook 的结果会被拒绝，[报告此问题的通知](https://code.claude.com/docs/zh-CN/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing)中包含 `nesting deeper than 28000 levels is not supported`。需要 Claude Code v2.1.299 或更高版本。 |414| hook 返回值的嵌套深度，`ui.render`、`ui.resolve` 和异步生成器 hook 除外 | 28,000 层。超过此深度，该 hook 的结果会被拒绝，[报告此问题的通知](https://code.claude.com/docs/zh-CN/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing)中包含 `nesting deeper than 28000 levels is not supported`。需要 Claude Code v2.1.299 或更高版本。 |

405| 在 hook 模块的单个文件中相互嵌套的作用域（如函数、代码块和循环） | 2,000 |415| 在 hook 模块的单个文件中相互嵌套的作用域（如函数、代码块和循环） | 2,000 |

408 418

409## 设置和环境变量419## 设置和环境变量

prompt-caching.md +2 −2

Details

33有两个设置不在层表中出现，但仍然影响缓存的内容：33有两个设置不在层表中出现，但仍然影响缓存的内容：

34 34

35* **模型**：每个模型都有自己的缓存。切换模型会重新计算整个请求，即使内容相同。请参阅下面的[切换模型](#switching-models)。35* **模型**：每个模型都有自己的缓存。切换模型会重新计算整个请求，即使内容相同。请参阅下面的[切换模型](#switching-models)。

36* **effort 级别**：在大多数模型上，每个 effort 级别都有自己的缓存，因此在会话中途更改 effort 级别会重新计算整个请求。在使用 API 密钥或 Claude 订阅的 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.1 上，缓存默认保持完整。请参阅下面的[更改 effort 级别](#changing-effort-level)。36* **effort 级别**：在大多数模型上，每个 effort 级别都有自己的缓存，因此在会话中途更改 effort 级别会重新计算整个请求。使用 API 密钥或 Claude 订阅时，在 Fable 5.1 及更高版本、Opus 5.5、Sonnet 5.5 和 Haiku 5.5 上，缓存默认保持完整。请参阅下面的[更改 effort 级别](#changing-effort-level)。

37 37

38> [!TIP]38> [!TIP]

39>39>

94 94

95在大多数模型上，在会话中途更改 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)意味着下一个请求会读取整个对话历史记录而没有缓存命中。当缓存仍然温暖时，Claude Code 会要求您先确认更改。95在大多数模型上，在会话中途更改 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)意味着下一个请求会读取整个对话历史记录而没有缓存命中。当缓存仍然温暖时，Claude Code 会要求您先确认更改。

96 96

97在 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.1 上使用 API 密钥或 Claude 订阅时，更改 effort 会保持缓存。Claude Code 会在不询问的情况下[应用新级别](https://code.claude.com/docs/zh-CN/model-config.md#when-a-new-effort-level-starts)。在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 [Claude 应用网关](https://code.claude.com/docs/zh-CN/claude-apps-gateway)上，或者当您设置了 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](https://code.claude.com/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities) 或您的组织具有 HIPAA 配置时，其行为与大多数模型相同。97在 Fable 5.1 及更高版本、Opus 5.5、Sonnet 5.5 和 Haiku 5.5 上使用 API 密钥或 Claude 订阅时，更改 effort 会保持缓存。Claude Code 会在不询问的情况下[应用新级别](https://code.claude.com/docs/zh-CN/model-config.md#when-a-new-effort-level-starts)。在 Amazon Bedrock、Google Cloud 的 Agent Platform 或 [Claude 应用网关](https://code.claude.com/docs/zh-CN/claude-apps-gateway)上，或者当您设置了 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](https://code.claude.com/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities) 或您的组织具有 HIPAA 配置时，其行为与大多数模型相同。

98 98

99在 v2.1.260 之前，在 Fable 5.1 上使用 API 密钥或 Claude 订阅更改 effort 也会使缓存失效。99在 v2.1.260 之前，在 Fable 5.1 上使用 API 密钥或 Claude 订阅更改 effort 也会使缓存失效。

100 100

remote-control.md +3 −0

Details

49> claude remote-control49> claude remote-control

50> ```50> ```

51>51>

52> `claude rc` 是此命令的别名。

53>

52> 在您接受 Remote Control 的一次性确认之前，`claude remote-control` 会先说明其作用，并在启动服务器前询问 `Enable Remote Control? (y/n)`。回答 `y` 即可接受并启动服务器。如果您拒绝，Claude Code 会退出而不启动服务器，并在您下次运行该命令时再次询问。54> 在您接受 Remote Control 的一次性确认之前，`claude remote-control` 会先说明其作用，并在启动服务器前询问 `Enable Remote Control? (y/n)`。回答 `y` 即可接受并启动服务器。如果您拒绝，Claude Code 会退出而不启动服务器，并在您下次运行该命令时再次询问。

53>55>

54> 在服务器模式下，该进程会在终端中持续运行，等待远程连接。它会显示一个 URL，您可以用它[从另一台设备连接](#connect-from-another-device)，还可以按空格键显示二维码，以便从手机快速访问。远程会话处于活动状态时，终端会显示连接状态和工具活动。56> 在服务器模式下，该进程会在终端中持续运行，等待远程连接。它会显示一个 URL，您可以用它[从另一台设备连接](#connect-from-another-device)，还可以按空格键显示二维码，以便从手机快速访问。远程会话处于活动状态时，终端会显示连接状态和工具活动。

462* **您的 claude.ai 套餐是 Pro、Max 或 Ultra**：Claude Code 仍然以来自较早登录的 Team 或 Enterprise 组织身份登录，因此它检查该组织的 Remote Control 策略。运行 `/status` 以查看您的登录使用的套餐和组织。运行 `claude auth logout` 然后 `claude auth login` 以在您当前的套餐下重新登录。464* **您的 claude.ai 套餐是 Pro、Max 或 Ultra**：Claude Code 仍然以来自较早登录的 Team 或 Enterprise 组织身份登录，因此它检查该组织的 Remote Control 策略。运行 `/status` 以查看您的登录使用的套餐和组织。运行 `claude auth logout` 然后 `claude auth login` 以在您当前的套餐下重新登录。

463* **消息未说联系您的组织管理员**：您的组织应用了 [HIPAA 配置](https://code.claude.com/docs/zh-CN/hipaa-setup.md)，该配置会关闭 Remote Control。要确认这一点，请运行 `/status` 并在 `Organization configuration` 行中查找 `HIPAA`。所有者会在[管理设置](https://claude.ai/admin-settings/claude-code)中看到 **Remote Control** 切换呈灰显状态，且无法将其打开。如果您对该配置有疑问，请询问所有者，所有者可以联系您组织的 Anthropic 客户团队。在 v2.1.267 之前，此情况显示"Remote Control isn't available for your organization due to its compliance policy"。465* **消息未说联系您的组织管理员**：您的组织应用了 [HIPAA 配置](https://code.claude.com/docs/zh-CN/hipaa-setup.md)，该配置会关闭 Remote Control。要确认这一点，请运行 `/status` 并在 `Organization configuration` 行中查找 `HIPAA`。所有者会在[管理设置](https://claude.ai/admin-settings/claude-code)中看到 **Remote Control** 切换呈灰显状态，且无法将其打开。如果您对该配置有疑问，请询问所有者，所有者可以联系您组织的 Anthropic 客户团队。在 v2.1.267 之前，此情况显示"Remote Control isn't available for your organization due to its compliance policy"。

464* **Remote Control 对组织中的其他人有效，但对您无效**：如果您的 Enterprise 组织使用[自定义角色](https://support.claude.com/en/articles/13930452)管理您的访问权限，则原因可能在于您的角色。Remote Control 同时需要云端会话权限和 **Claude Code remote control** 权限。请让所有者检查您的角色是否同时包含这两项权限，并在 [**Organization settings > Roles**](https://claude.ai/admin-settings/roles) 中添加缺少的权限。466* **Remote Control 对组织中的其他人有效，但对您无效**：如果您的 Enterprise 组织使用[自定义角色](https://support.claude.com/en/articles/13930452)管理您的访问权限，则原因可能在于您的角色。Remote Control 同时需要云端会话权限和 **Claude Code remote control** 权限。请让所有者检查您的角色是否同时包含这两项权限，并在 [**Organization settings > Roles**](https://claude.ai/admin-settings/roles) 中添加缺少的权限。

467* **所有者在[管理设置](https://claude.ai/admin-settings/claude-code)中看到 [Zero Data Retention](https://code.claude.com/docs/zh-CN/zero-data-retention.md) 横幅**：Remote Control 不适用于您的组织，且所有者无法将其打开。

465* **否则，所有者尚未为您的组织启用它**：Remote Control 在 Team 和 Enterprise 计划上默认关闭。所有者可以在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 通过打开 **Remote Control** 切换来启用它。此切换是服务器端组织设置。468* **否则，所有者尚未为您的组织启用它**：Remote Control 在 Team 和 Enterprise 计划上默认关闭。所有者可以在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 通过打开 **Remote Control** 切换来启用它。此切换是服务器端组织设置。

466 469

467在 v2.1.281 之前，当 Claude Code 未在此计算机上加载您的组织策略时，此消息也会出现，例如在离线启动后。更高版本将该状态报告为[`Couldn't verify your organization's policy for remote control`](#couldnt-verify-your-organizations-policy-for-remote-control)。470在 v2.1.281 之前，当 Claude Code 未在此计算机上加载您的组织策略时，此消息也会出现，例如在离线启动后。更高版本将该状态报告为[`Couldn't verify your organization's policy for remote control`](#couldnt-verify-your-organizations-policy-for-remote-control)。

self-hosted-environments-configuration.md +5 −1

Details

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

156| `CLAUDE_RUNNER_REPO_REF` | 要检出的修订版本，即会话所请求的形式：分支、标签、提交 SHA，或完整引用名称（例如 `refs/heads/<branch>` 或 `refs/pull/<number>/head`）。为空表示仓库的默认分支。 |156| `CLAUDE_RUNNER_REPO_REF` | 要检出的修订版本，即会话所请求的形式：分支、标签、提交 SHA，或完整引用名称（例如 `refs/heads/<branch>` 或 `refs/pull/<number>/head`）。为空表示仓库的默认分支。 |

166 166

167在您的 hook 返回后，运行器会验证 `CLAUDE_RUNNER_CHECKOUT_PATH` 包含 `.git`。如果您的 hook 具体化的是非 git 源（例如 Perforce 或解包的 tarball），请在运行器的环境中设置 `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` 以跳过该检查。基于 Git 的流程（例如工作分支创建和推送结果）需要 git 检出，因此请使用 [`post-session` hook](#post-session) 从非 git 树导出结果。167在您的 hook 返回后，运行器会验证 `CLAUDE_RUNNER_CHECKOUT_PATH` 包含 `.git`。如果您的 hook 具体化的是非 git 源（例如 Perforce 或解包的 tarball），请在运行器的环境中设置 `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` 以跳过该检查。基于 Git 的流程（例如工作分支创建和推送结果）需要 git 检出，因此请使用 [`post-session` hook](#post-session) 从非 git 树导出结果。

168 168

169#### 检出文件夹名称

170

171`CLAUDE_RUNNER_CHECKOUT_PATH` 以名为 `<repo-owner>-<repo>` 的文件夹结尾，例如 `acme-api`。会话中的两个仓库不能共用同一个文件夹，即使它们的名称仅在大小写上不同也是如此。例如，如果会话先列出 `acme/api`，然后列出 `Acme/API`，则第一个获得 `acme-api`，第二个获得 `Acme-API-2`。

172

169#### 在 hook 中获取 git 凭据173#### 在 hook 中获取 git 凭据

170 174

171运行器不会将 git 凭据传递给 hook。`decode-token` 子命令在此处同样不可用，因为 `CLAUDE_RUNNER_CLAUDE_BIN` 未在 checkout-hook 环境中设置。请改为从会话的身份生成按会话的克隆凭据，或回退到主机自身的 git 身份验证：175运行器不会将 git 凭据传递给 hook。`decode-token` 子命令在此处同样不可用，因为 `CLAUDE_RUNNER_CLAUDE_BIN` 未在 checkout-hook 环境中设置。请改为从会话的身份生成按会话的克隆凭据，或回退到主机自身的 git 身份验证：

self-hosted-environments-deploy.md +19 −2

Details

23 * **使用 [Anthropic 托管的 git](#use-the-anthropic-git-proxy) 时**：有了此类凭据，Claude 会直接访问 GitHub，而不是通过 Anthropic 托管的 git。23 * **使用 [Anthropic 托管的 git](#use-the-anthropic-git-proxy) 时**：有了此类凭据，Claude 会直接访问 GitHub，而不是通过 Anthropic 托管的 git。

24 * **不使用 Anthropic 托管的 git 时**：如果您按照[在镜像中附带 git 配置](#ship-git-config-in-your-image)所述严格限定克隆凭据的范围，则该凭据可以保留在镜像中。24 * **不使用 Anthropic 托管的 git 时**：如果您按照[在镜像中附带 git 配置](#ship-git-config-in-your-image)所述严格限定克隆凭据的范围，则该凭据可以保留在镜像中。

25* **将环境密钥保持在运行会话的主机之外**：环境密钥可以注册运行器并获取在环境上排队的任何会话。在固定队列上，它存在于每个运行器主机上，任何会话的代码都可以读取密钥文件。优先使用[按需运行器](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration.md#on-demand-runners)，其中密钥保留在编排器主机上，该主机从不运行用户代码，每个运行器接收单次使用的工作单，恰好注册一个运行器。在固定队列上，将环境密钥文件视为可由每个会话读取，并在任何可疑会话泄露后轮换密钥。25* **将环境密钥保持在运行会话的主机之外**：环境密钥可以注册运行器并获取在环境上排队的任何会话。在固定队列上，它存在于每个运行器主机上，任何会话的代码都可以读取密钥文件。优先使用[按需运行器](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration.md#on-demand-runners)，其中密钥保留在编排器主机上，该主机从不运行用户代码，每个运行器接收单次使用的工作单，恰好注册一个运行器。在固定队列上，将环境密钥文件视为可由每个会话读取，并在任何可疑会话泄露后轮换密钥。

26 * **发生可疑泄露后**：请[所有者](https://code.claude.com/docs/zh-CN/cloud-environments.md#organization-shared-environments)在环境的 **Configuration** 选项卡中创建新密钥并撤销旧密钥，然后推出新密钥。Anthropic 会拒绝所有使用旧密钥的编排器和运行器，包括来自其工作单的按需运行器。您的运行器将退出，从而中断其会话。

26* **默认拒绝网络出站流量**：在每个环境上限制运行器和会话容器的出站流量在您自己的网络边界；[默认拒绝出站流量](#default-deny-egress)涵盖允许什么以及原因。27* **默认拒绝网络出站流量**：在每个环境上限制运行器和会话容器的出站流量在您自己的网络边界；[默认拒绝出站流量](#default-deny-egress)涵盖允许什么以及原因。

27* **最小权限主机 IAM**：附加到运行器主机的计算身份（例如实例配置文件或节点服务帐户）应仅授予运行器本身需要的内容。会话应通过您的包装脚本而不是继承主机的身份获取自己的凭证。28* **最小权限主机 IAM**：附加到运行器主机的计算身份（例如实例配置文件或节点服务帐户）应仅授予运行器本身需要的内容。会话应通过您的包装脚本而不是继承主机的身份获取自己的凭证。

28* **阻止会话访问云元数据端点**：保持会话不访问主机身份需要阻止它们访问云元数据端点，子网级出站策略不会拦截链接本地元数据流量，因此在容器本身中阻止它：29* **阻止会话访问云元数据端点**：保持会话不访问主机身份需要阻止它们访问云元数据端点，子网级出站策略不会拦截链接本地元数据流量，因此在容器本身中阻止它：

203> [!WARNING]204> [!WARNING]

204>205>

205> 设置 `--use-anthropic-git-proxy` 后，运行器会删除并替换其运行用户的全局 git 配置，且不保留备份。它会在启动时以及每个会话之前执行此操作。您保存在其中的登录或凭据助手将会丢失。[`--configure-git`](#let-the-runner-configure-git) 写入的设置会保留。请以专用用户身份或在容器中运行运行器，切勿以您自己的用户身份运行。206> 设置 `--use-anthropic-git-proxy` 后，运行器会删除并替换其运行用户的全局 git 配置，且不保留备份。它会在启动时以及每个会话之前执行此操作。您保存在其中的登录或凭据助手将会丢失。[`--configure-git`](#let-the-runner-configure-git) 写入的设置会保留。请以专用用户身份或在容器中运行运行器，切勿以您自己的用户身份运行。

207>

208> 全局 git 配置包括以下全部三项：`~/.gitconfig`、您设置了 `GIT_CONFIG_GLOBAL` 时它所指定的文件，以及整个 `$XDG_CONFIG_HOME/git` 目录（默认为 `~/.config/git`）。

206 209

207将非机密的 git 设置（例如身份和 `safe.directory`）保存在系统 git 配置中。210将非机密的 git 设置（例如身份和 `safe.directory`）保存在系统 git 配置中。

208 211

247* **包含 `remote: access denied by the git proxy` 的行**：Anthropic 提供服务的会话仍可能被拒绝，例如当组织策略拒绝该会话的 git 访问，或该会话未获得该仓库的授权时。此时运行器的日志会显示一行包含 `remote: access denied by the git proxy` 的内容，该行的其余部分说明了原因。250* **包含 `remote: access denied by the git proxy` 的行**：Anthropic 提供服务的会话仍可能被拒绝，例如当组织策略拒绝该会话的 git 访问，或该会话未获得该仓库的授权时。此时运行器的日志会显示一行包含 `remote: access denied by the git proxy` 的内容，该行的其余部分说明了原因。

248* **`GitHub authentication required`**：当会话的创建者在 claude.ai 上没有可用的 GitHub 连接时会出现此情况。会话的克隆失败，git 错误显示为 `GitHub authentication required. Please reconnect your GitHub account.` 请让该用户在其 claude.ai 设置中连接或重新连接 GitHub。251* **`GitHub authentication required`**：当会话的创建者在 claude.ai 上没有可用的 GitHub 连接时会出现此情况。会话的克隆失败，git 错误显示为 `GitHub authentication required. Please reconnect your GitHub account.` 请让该用户在其 claude.ai 设置中连接或重新连接 GitHub。

249 252

250修复原因后，请重新启动失败的会话。253修复原因后，请重新启动导致会话失败的运行器，然后让每个创建者在其会话中发送一条消息，或由 Owner 选择 **Retry**。

251 254

252#### 关闭 Anthropic git 代理255#### 关闭 Anthropic git 代理

253 256

265 268

266为运行器会话使用的每个 git 主机（包括 github.com）提供无需提示即可工作的凭据。运行器用户全局 git 配置中的任何凭据都已丢失，因为在设置 `--use-anthropic-git-proxy` 期间运行器删除了该配置。请[在镜像中提供凭据](#ship-git-config-in-your-image)或使用 [`checkout` 生命周期钩子](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#checkout)。269为运行器会话使用的每个 git 主机（包括 github.com）提供无需提示即可工作的凭据。运行器用户全局 git 配置中的任何凭据都已丢失，因为在设置 `--use-anthropic-git-proxy` 期间运行器删除了该配置。请[在镜像中提供凭据](#ship-git-config-in-your-image)或使用 [`checkout` 生命周期钩子](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#checkout)。

267 270

271如果要改为将凭据保存在[全局 git 配置](#git-proxy-replaces-global-git-config)中，请先[停止运行器](#shutdown-timing)，因为使用该标志启动的运行器会在每个会话之前重写该配置。然后删除 `$XDG_CONFIG_HOME/git`（默认为 `~/.config/git`），并用您自己的文件替换 `~/.gitconfig` 或 `GIT_CONFIG_GLOBAL` 所指定的文件。

272

268**3. 打开网络路径**273**3. 打开网络路径**

269 274

270允许运行器通过 443 或 22 端口访问运行器会话使用的每个 git 主机。请参阅[网络要求](#network-requirements)中的 git 主机行。275允许运行器通过 443 或 22 端口访问运行器会话使用的每个 git 主机。请参阅[网络要求](#network-requirements)中的 git 主机行。

507 512

508## Kubernetes513## Kubernetes

509 514

510运行器默认在端口 8080 上提供 `GET /healthz`，可使用 `--health-port` 配置，因此 Kubernetes 探针无需额外设置即可工作。端点在进程活着时返回 `200`，所以下面的探针检测死进程，而不是卡住的进程；要捕获停止轮询的运行器，请在 [`/metrics`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#prometheus-metrics) 的 `last_poll_age_seconds` 系列上发出警报。下面的 Deployment 从 Kubernetes Secret 挂载环境密钥，将活跃度和就绪探针指向 `/healthz`，并设置 90 秒的终止宽限期。请参阅[关闭时序](#shutdown-timing)了解为什么宽限期很重要。515运行器默认在端口 8080 上提供 `GET /healthz`，可使用 `--health-port` 配置。启动后，只要进程处于活动状态，端点就会返回 `200`，所以下面的探针检测死进程，而不是卡住的进程。要捕获停止轮询的运行器，请在 [`/metrics`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#prometheus-metrics) 的 `last_poll_age_seconds` 系列上发出警报。

516

517下面的 Deployment 从 Kubernetes Secret 挂载环境密钥，将活跃度和就绪探针指向 `/healthz`，并设置 90 秒的终止宽限期。请参阅[关闭时序](#shutdown-timing)了解为什么宽限期很重要。

511 518

512清单在运行器容器上设置没有 CPU 或内存 `resources`。添加为您运行的容量调整大小的块，如[为会话调整 CPU 和内存大小](#size-cpu-and-memory-for-sessions)所述。519清单在运行器容器上设置没有 CPU 或内存 `resources`。添加为您运行的容量调整大小的块，如[为会话调整 CPU 和内存大小](#size-cpu-and-memory-for-sessions)所述。

513 520

565 secretName: claude-runner-environment-secret572 secretName: claude-runner-environment-secret

566```573```

567 574

575> [!NOTE]

576>

577> 如果 pod 的事件显示活跃度探针在启动期间失败，请调高其 `initialDelaySeconds` 或添加 `startupProbe`。在运行器完成注册并完成启动检查之前，健康端口上不会有任何响应。使用上述设置，Kubernetes 会重启大约 90 秒内仍未提供服务的运行器。

578

568上面的 Deployment 存在于 `claude-runners` 命名空间中。首先创建命名空间：579上面的 Deployment 存在于 `claude-runners` 命名空间中。首先创建命名空间：

569 580

570```bash theme={null}581```bash theme={null}

942 如果每个调用在会话大约 30 分钟后开始失败，包装脚本可能已断开会话的 stdin，因此令牌轮换无法到达它；请参阅 [保持 stdin 和文件描述符 3 附加](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration.md#keep-stdin-and-file-descriptor-3-attached)。953 如果每个调用在会话大约 30 分钟后开始失败，包装脚本可能已断开会话的 stdin，因此令牌轮换无法到达它；请参阅 [保持 stdin 和文件描述符 3 附加](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration.md#keep-stdin-and-file-descriptor-3-attached)。

943 954

944 在 v2.1.274 之前，运行器在几次尝试后停止重试失败的获取，并等待下一个计划的获取。失败的轮次不会触发获取，因此每个轮次都会失败，显示 401，直到下一个计划的获取。955 在 v2.1.274 之前，运行器在几次尝试后停止重试失败的获取，并等待下一个计划的获取。失败的轮次不会触发获取，因此每个轮次都会失败，显示 401，直到下一个计划的获取。

956* **会话显示 `The server has refused to renew this session's access to the model`**：会话的 [`CLAUDE_CODE_OAUTH_TOKEN`](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#wrapper-scripts) 已过期，并且运行器在请求新令牌时收到了 HTTP 400 响应。运行器会记录 `the server has refused to renew the inference_token`。该会话中的轮次会失败。只要会话的进程仍在运行，运行器就会持续请求新令牌：

957

958 * **请求成功**：显示过该警告的会话随后会显示 `The server renewed this session's access to the model`

959 * **轮次持续失败**：进程最终会退出，会话会显示一条失败信息，例如 `The session process exited with code 1`

960

961 要在不等待新令牌的情况下继续工作，请启动新会话。如果新会话也失败，请检查是否是您的某个代理或网关给出了 HTTP 400 响应。如果都不是，请提供第一个会话的 ID 并[联系您的 Anthropic 客户团队](#report-an-issue)。

945* **轮次在 claude.ai/code 中失败，显示 `This model needs a newer version of Claude Code`**：您的运行器用于启动会话的 Claude Code 版本低于该会话的模型所要求的版本，因此 API [拒绝了该请求](https://code.claude.com/docs/zh-CN/errors.md#claude-code-does-not-support-this-model)。按照 [固定版本](#pin-the-version) 中的说明，将运行器升级到消息要求的版本或更高版本。在此之前，用户可以在会话中选择其他模型。962* **轮次在 claude.ai/code 中失败，显示 `This model needs a newer version of Claude Code`**：您的运行器用于启动会话的 Claude Code 版本低于该会话的模型所要求的版本，因此 API [拒绝了该请求](https://code.claude.com/docs/zh-CN/errors.md#claude-code-does-not-support-this-model)。按照 [固定版本](#pin-the-version) 中的说明，将运行器升级到消息要求的版本或更高版本。在此之前，用户可以在会话中选择其他模型。

946* **Pod 在耗尽中途被杀死**：将 `terminationGracePeriodSeconds` 提高到至少运行器在启动时记录的值。请参阅 [关闭时序](#shutdown-timing)。963* **Pod 在耗尽中途被杀死**：将 `terminationGracePeriodSeconds` 提高到至少运行器在启动时记录的值。请参阅 [关闭时序](#shutdown-timing)。

947* **运行器记录一条以 `was paused or too slow` 结尾的 `[runner:log]` 行**：运行器仍在运行，无需重新启动。在该行中指明的 stdout 或 stderr 流被再次读取之前，运行器丢弃了该流中除最新 256 KiB 之外的所有行。如果您传递了 [`--log-file`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags)，请在该文件中查找被丢弃的行。964* **运行器记录一条以 `was paused or too slow` 结尾的 `[runner:log]` 行**：运行器仍在运行，无需重新启动。在该行中指明的 stdout 或 stderr 流被再次读取之前，运行器丢弃了该流中除最新 256 KiB 之外的所有行。如果您传递了 [`--log-file`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags)，请在该文件中查找被丢弃的行。

self-hosted-environments-quickstart.md +3 −1

Details

73 73

74转到管理设置中的[**Cloud environments** 页面](https://claude.ai/admin-settings/cloud-environments)。在 **Self-hosted environments** 下，选择 **New**，命名环境，然后选择 **Create**。在向导的第二步，选择 **Copy environment key** 以复制环境密钥，管理 UI 将其标记为环境密钥。claude.ai 仅显示一次密钥，您之后无法检索它；它在创建后 365 天过期。环境的 `ccpool_...` ID 在其详细信息对话框中保持可见；您需要它用于[令牌验证](https://code.claude.com/docs/zh-CN/self-hosted-environments-identity.md)中的 `aud` 检查，以及用于从 CI [分派测试会话](https://code.claude.com/docs/zh-CN/self-hosted-environments-testing.md#run-the-test-loop)。74转到管理设置中的[**Cloud environments** 页面](https://claude.ai/admin-settings/cloud-environments)。在 **Self-hosted environments** 下，选择 **New**，命名环境，然后选择 **Create**。在向导的第二步，选择 **Copy environment key** 以复制环境密钥，管理 UI 将其标记为环境密钥。claude.ai 仅显示一次密钥，您之后无法检索它；它在创建后 365 天过期。环境的 `ccpool_...` ID 在其详细信息对话框中保持可见；您需要它用于[令牌验证](https://code.claude.com/docs/zh-CN/self-hosted-environments-identity.md)中的 `aud` 检查，以及用于从 CI [分派测试会话](https://code.claude.com/docs/zh-CN/self-hosted-environments-testing.md#run-the-test-loop)。

75 75

76如果您丢失了密钥或需要轮换它，请从环境的 **Configuration** 选项卡创建新密钥，将新密钥推出到您的运行器，然后撤销旧密钥。持有已撤销密钥的运行器在其下一次经过身份验证的轮询时失败并退出，记录 `poll auth failed`，您的编排器使用新密钥重新启动它们。76如果密钥可能已泄露，请按照[部署页面中针对疑似泄露的步骤](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#after-a-suspected-compromise)操作，而不是执行下面的轮换。

78如果您丢失了密钥或计划轮换它，请从环境的 **Configuration** 选项卡创建新密钥。将新密钥推出到您的运行器，然后撤销旧密钥。持有已撤销密钥的运行器在其下一次经过身份验证的轮询时失败并退出，记录 `poll auth failed`，您的编排器使用新密钥重新启动它们。

77 79

78**2. 启动运行器**80**2. 启动运行器**

79 81

self-hosted-environments-reference.md +1 −1

Details

141 141

142## 健康端点142## 健康端点

143 143

144运行器在配置的健康端口上提供 `GET /healthz`。只要进程活跃，响应就是 `200 OK`，无论轮询循环处于什么状态，因此此端点上的 HTTP 探针仅检测死进程。JSON 正文描述当前状态：144运行器在完成注册并结束启动检查后，会在配置的健康端口上提供 `GET /healthz`。从那时起，只要进程活跃，响应就是 `200 OK`，无论轮询循环处于什么状态，因此此端点上的 HTTP 探针仅检测死进程。JSON 正文描述当前状态：

145 145

146```json theme={null}146```json theme={null}

147{147{

settings.md +1 −0

Details

311| [`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/zh-CN/settings-reference#permissions-blockreadsoutsideworkingdirectories) | 任何作用域中的 `true` | 即使托管来源设置为 `false` 也会采用。需要 Claude Code v2.1.257 或更高版本 |311| [`permissions.blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/zh-CN/settings-reference#permissions-blockreadsoutsideworkingdirectories) | 任何作用域中的 `true` | 即使托管来源设置为 `false` 也会采用。需要 Claude Code v2.1.257 或更高版本 |

312| [`permissions.blockWritesOutsideWorkingDirectories`](https://code.claude.com/docs/zh-CN/settings-reference#permissions-blockwritesoutsideworkingdirectories) | 任何作用域中的 `true` | 即使托管来源设置为 `false` 也会采用。需要 Claude Code v2.1.314 或更高版本 |312| [`permissions.blockWritesOutsideWorkingDirectories`](https://code.claude.com/docs/zh-CN/settings-reference#permissions-blockwritesoutsideworkingdirectories) | 任何作用域中的 `true` | 即使托管来源设置为 `false` 也会采用。需要 Claude Code v2.1.314 或更高版本 |

313| [`permissions.denyInsteadOfPrompting`](https://code.claude.com/docs/zh-CN/settings-reference#permissions-denyinsteadofprompting) | `~/.claude/settings.json` 或 `--settings` 中的 `true` | 即使托管来源设置为 `false` 也会采用。需要 Claude Code v2.1.319 或更高版本 |

313| [`autoMode.classifyAllShell`](https://code.claude.com/docs/zh-CN/settings-reference#automode-classifyallshell) | `~/.claude/settings.json` 或 `--settings` 中的 `true` | 即使托管来源设置为 `false` 也会采用 |314| [`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` 会被忽略 |315| [`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` 和用户设置中的值；项目或本地设置中不更严格的值会被忽略 |316| [`crossSessionInbound`](https://code.claude.com/docs/zh-CN/settings-reference#crosssessioninbound) | `.claude/settings.json` 或 `.claude/settings.local.json` 中更严格的值，严格程度依次为 `accept` \< `hold` \< `refuse` | 优先于托管、`--settings` 和用户设置中的值；项目或本地设置中不更严格的值会被忽略 |

settings-reference.md +4 −4

Details

448 448

449在可用的会话中开启[快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md)，适用于快速迭代或实时调试等需要以更高的每 token 成本换取速度的交互式工作。通常无需手动编辑此键。运行 `/fast` 会将 `fastMode: true` 写入 `~/.claude/settings.json`，再次运行以关闭快速模式则会移除该键。449在可用的会话中开启[快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md)，适用于快速迭代或实时调试等需要以更高的每 token 成本换取速度的交互式工作。通常无需手动编辑此键。运行 `/fast` 会将 `fastMode: true` 写入 `~/.claude/settings.json`，再次运行以关闭快速模式则会移除该键。

450 450

451只有 Opus 5.5、Opus 5 和 Opus 4.8 支持快速模式。在其他模型上运行 `/fast` 会将您切换到 Opus，而切换到不受支持的模型则会关闭快速模式。请参阅[在快速模式开启时切换模型](https://code.claude.com/docs/zh-CN/fast-mode.md#switch-models-while-fast-mode-is-on)。451只有 Fable 5.2、Opus 5.5、Opus 5 和 Opus 4.8 支持快速模式。在其他模型上运行 `/fast` 会将您切换到 Opus，而切换到不受支持的模型则会关闭快速模式。请参阅[在快速模式开启时切换模型](https://code.claude.com/docs/zh-CN/fast-mode.md#switch-models-while-fast-mode-is-on)。

452 452

453* **作用域**：[`Any file`](#scopes)453* **作用域**：[`Any file`](#scopes)

454* **类型**：Boolean454* **类型**：Boolean

455 * `true`：Claude Code 在可用的会话中开启快速模式455 * `true`：Claude Code 在可用的会话中开启快速模式。在 Fable 5.2 上，您还必须[在使用 Fable 5.2 时运行 `/fast`](https://code.claude.com/docs/zh-CN/fast-mode#switch-models-while-fast-mode-is-on)

456 * `false`：快速模式保持关闭456 * `false`：快速模式保持关闭

457* **默认值**：未设置，因此快速模式处于关闭状态457* **默认值**：未设置，因此快速模式处于关闭状态

458* **单会话覆盖**：[`CLAUDE_CODE_DISABLE_FAST_MODE`](https://code.claude.com/docs/zh-CN/env-vars) 会在单个会话中关闭快速模式，且此键无法将其重新开启458* **单会话覆盖**：[`CLAUDE_CODE_DISABLE_FAST_MODE`](https://code.claude.com/docs/zh-CN/env-vars) 会在单个会话中关闭快速模式，且此键无法将其重新开启

465 465

466### `fastModePerSessionOptIn`466### `fastModePerSessionOptIn`

467 467

468通常，运行 `/fast` 会将 [`fastMode`](#fastmode) 保存到个人的用户设置中，因此在受支持模型上的新会话开始时快速模式都会开启。将此键设置为 `true` 可阻止这种行为：已保存的 `fastMode: true` 不再在会话开始时开启快速模式，每个人需要在每个想要使用快速模式的会话中运行 `/fast`。Claude Code 会保留其文件中的 `fastMode`，因此关闭此键即可恢复原来的行为。468通常，运行 `/fast` 会将 [`fastMode`](#fastmode) 保存到个人的用户设置中，因此在受支持模型上的新会话开始时快速模式都会开启。在 Fable 5.2 上，只有当用户[在使用 Fable 5.2 时开启了快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md#switch-models-while-fast-mode-is-on)，才会如此。要让每个人在每个想要使用快速模式的会话中运行 `/fast`，请将此键设置为 `true`。Claude Code 会保留其文件中的 `fastMode`，因此关闭此键即可恢复原来的行为。

469 469

470Team 或 Enterprise 计划的所有者可以通过[服务器托管设置](https://code.claude.com/docs/zh-CN/server-managed-settings.md)在整个组织中部署此项。当托管设置设置了此键时，`/fast on` 在交互式终端会话之外会被拒绝，并报告您的组织已禁用快速模式。这涵盖[非交互模式](https://code.claude.com/docs/zh-CN/headless.md)、[VS Code 扩展](https://code.claude.com/docs/zh-CN/vs-code.md)和[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)。470Team 或 Enterprise 计划的所有者可以通过[服务器托管设置](https://code.claude.com/docs/zh-CN/server-managed-settings.md)在整个组织中部署此项。当托管设置设置了此键时，`/fast on` 在交互式终端会话之外会被拒绝，并报告您的组织已禁用快速模式。这涵盖[非交互模式](https://code.claude.com/docs/zh-CN/headless.md)、[VS Code 扩展](https://code.claude.com/docs/zh-CN/vs-code.md)和[云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)。

471 471

472* **作用域**：[`Any file`](#scopes)472* **作用域**：[`Any file`](#scopes)

473* **类型**：Boolean473* **类型**：Boolean

474 * `true`：已保存的 `fastMode: true` 不再在会话开始时开启快速模式，因此每个人需要在每个想要使用快速模式的会话中运行 `/fast`；通过 `--settings` 传入的 `fastMode: true` 仍对该会话有效，除非托管设置设置了此键474 * `true`：已保存的 `fastMode: true` 不再在会话开始时开启快速模式，因此每个人需要在每个想要使用快速模式的会话中运行 `/fast`；通过 `--settings` 传入的 `fastMode: true` 仍对该会话有效，除非托管设置设置了此键

475 * `false`：已保存的 `fastMode: true` 会在受支持模型上的每个新会话开始时开启快速模式475 * `false`：已保存的 `fastMode: true` 按照 [`fastMode`](#fastmode) 所述的方式生效

476* **默认值**：`false`476* **默认值**：`false`

477 477

478```json settings.json theme={null}478```json settings.json theme={null}

sub-agents.md +2 −0

Details

592主对话的权限模式决定 Claude Code 是否使用您设置的值：592主对话的权限模式决定 Claude Code 是否使用您设置的值：

593 593

594* 当主对话处于 `bypassPermissions`、`acceptEdits` 或[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)时，子代理以相同模式运行，Claude Code 会忽略您设置的 `permissionMode`。在自动模式下，分类器使用主对话的阻止和允许规则评估子代理的工具调用。当子代理完成时，分类器还会在交付最终报告之前审查其工作和最终报告，如[自动模式如何处理子代理](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)中所述。594* 当主对话处于 `bypassPermissions`、`acceptEdits` 或[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)时，子代理以相同模式运行，Claude Code 会忽略您设置的 `permissionMode`。在自动模式下，分类器使用主对话的阻止和允许规则评估子代理的工具调用。当子代理完成时，分类器还会在交付最终报告之前审查其工作和最终报告，如[自动模式如何处理子代理](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)中所述。

595

596 如果在主对话处于 `bypassPermissions` 时子代理请求权限，请检查其工具调用是否属于[任何模式都不会自动批准的操作](https://code.claude.com/docs/zh-CN/permission-modes.md#actions-no-mode-auto-approves)。

595* 当主对话处于 `plan` 模式时，无论您设置了什么 `permissionMode`，子代理都会保持在计划模式，除非它作为 [agent team 队友](#subagent-names)按照 [agent team 规则](https://code.claude.com/docs/zh-CN/agent-teams.md#have-teammates-plan-before-implementing)运行。如果您设置了 `dontAsk`，子代理也不会提示您：计划模式下原本会请求您批准的操作将被拒绝。597* 当主对话处于 `plan` 模式时，无论您设置了什么 `permissionMode`，子代理都会保持在计划模式，除非它作为 [agent team 队友](#subagent-names)按照 [agent team 规则](https://code.claude.com/docs/zh-CN/agent-teams.md#have-teammates-plan-before-implementing)运行。如果您设置了 `dontAsk`，子代理也不会提示您：计划模式下原本会请求您批准的操作将被拒绝。

596* 当主对话处于 `default` 或 `dontAsk` 模式时，子代理以您设置的权限模式运行。在以下情况下，它会改为保持主对话的权限模式：598* 当主对话处于 `default` 或 `dontAsk` 模式时，子代理以您设置的权限模式运行。在以下情况下，它会改为保持主对话的权限模式：

597 * 您设置了 `bypassPermissions`。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更高版本。599 * 您设置了 `bypassPermissions`。`bypassPermissions` 例外需要 Claude Code v2.1.267 或更高版本。

tools-reference.md +22 −7

Details

26| `CronDelete` | 按 ID 取消会话级定时任务 | 否 |26| `CronDelete` | 按 ID 取消会话级定时任务 | 否 |

27| `CronList` | 列出所有会话级定时任务 | 否 |27| `CronList` | 列出所有会话级定时任务 | 否 |

28| `Edit` | 对特定文件进行有针对性的编辑。请参阅 [Edit 工具行为](#edit-tool-behavior) | 是 |28| `Edit` | 对特定文件进行有针对性的编辑。请参阅 [Edit 工具行为](#edit-tool-behavior) | 是 |

29| `EndConversation` | 结束会话，在持续滥用输入的罕见情况下或当您要求 Claude 演示该工具时。请参阅 [EndConversation 工具行为](#endconversation-tool-behavior) | 否 |29| `EndConversation` | 结束会话，在持续滥用输入的罕见情况下，或当您要求 Claude 结束会话并随后确认时使用。请参阅 [EndConversation 工具行为](#endconversation-tool-behavior) | 否 |

30| `EnterPlanMode` | 切换到计划模式以在编码前设计方法 | 否 |30| `EnterPlanMode` | 切换到计划模式以在编码前设计方法 | 否 |

31| `EnterWorktree` | 创建一个隔离的 [git worktree](https://code.claude.com/docs/zh-CN/worktrees.md) 并切换到它，或切换到现有的 worktree。请参阅 [EnterWorktree 工具行为](#enterworktree-tool-behavior) | 是 |31| `EnterWorktree` | 创建一个隔离的 [git worktree](https://code.claude.com/docs/zh-CN/worktrees.md) 并切换到它，或切换到现有的 worktree。请参阅 [EnterWorktree 工具行为](#enterworktree-tool-behavior) | 是 |

32| `ExitPlanMode` | 呈现计划以供批准并退出计划模式 | 是 |32| `ExitPlanMode` | 呈现计划以供批准并退出计划模式 | 是 |

274 274

275EndConversation 工具结束当前会话。Claude 仅在两种情况下使用它：275EndConversation 工具结束当前会话。Claude 仅在两种情况下使用它：

276 276

277* 作为对持续辱骂性输入的最后手段，在尝试重定向对话失败且在之前的消息中发出明确警告之后277* 当 Claude 发出明确警告且未能重定向对话后，您仍持续发送辱骂性消息时

278* 当你明确要求查看该工具的演示并确认你想要结束会话时278* 当您明确要求 Claude 结束会话，并在 Claude 询问您是否仍要继续时予以确认

279 279

280一般性的沮丧、粗言秽语或任务进行不顺利都不符合条件，对有害内容的请求也不符合，Claude 会拒绝这些请求而不是结束会话。Claude Code 遵循与 claude.ai 相同的方法，后者可以[结束少数聊天](https://www.anthropic.com/research/end-subset-conversations)。280一般性的沮丧、粗言秽语或任务进行不顺利都不符合条件，对有害内容的请求也不符合，Claude 会拒绝这些请求而不是结束会话。Claude Code 遵循与 claude.ai 相同的方法，后者可以[结束少数聊天](https://www.anthropic.com/research/end-subset-conversations)。

281 281

390 390

391当 Monitor 运行命令时，它使用与 Bash 相同的 [权限规则](https://code.claude.com/docs/zh-CN/permissions.md#tool-specific-permission-rules)，因此您为 Bash 设置的 `allow` 和 `deny` 模式也适用于此处。当 [自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode) 处于活动状态时，Claude Code 会搁置命名 `Monitor` 本身的允许规则，以及它删除的其他 [广泛允许规则](https://code.claude.com/docs/zh-CN/permission-modes.md#how-the-classifier-evaluates-actions)，因此分类器以与审查 Bash 命令相同的方式审查 Monitor 命令。391当 Monitor 运行命令时，它使用与 Bash 相同的 [权限规则](https://code.claude.com/docs/zh-CN/permissions.md#tool-specific-permission-rules)，因此您为 Bash 设置的 `allow` 和 `deny` 模式也适用于此处。当 [自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode) 处于活动状态时，Claude Code 会搁置命名 `Monitor` 本身的允许规则，以及它删除的其他 [广泛允许规则](https://code.claude.com/docs/zh-CN/permission-modes.md#how-the-classifier-evaluates-actions)，因此分类器以与审查 Bash 命令相同的方式审查 Monitor 命令。

392 392

393[WebSocket 源](#websocket-source) 有其自己的批准提示，分类器也在自动模式下决定。

~~394~~

395在以下情况下，Monitor 需要最低版本或 Git Bash：393在以下情况下，Monitor 需要最低版本或 Git Bash：

396 394

397* **最低版本**：在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上，或者设置了 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时，Monitor 需要 Claude Code v2.1.310 或更高版本。此要求在 [功能标志获取](https://code.claude.com/docs/zh-CN/env-vars.md#features-that-need-feature-flag-fetching) 关闭时适用395* **最低版本**：在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上，或者设置了 `DISABLE_TELEMETRY` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时，Monitor 需要 Claude Code v2.1.310 或更高版本。此要求在 [功能标志获取](https://code.claude.com/docs/zh-CN/env-vars.md#features-that-need-feature-flag-fetching) 关闭时适用

417 415

418`timeout_ms` 截止时间也适用于 WebSocket 监视：监视在截止时间结束，`TaskStop` 会提前取消它。416`timeout_ms` 截止时间也适用于 WebSocket 监视：监视在截止时间结束，`TaskStop` 会提前取消它。

419 417

420打开 WebSocket 会提示批准；在 [自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode) 中，分类器会决定。该提示不提供跳过同一主机的未来提示的选项。418如果没有 `Monitor` 允许规则，Claude 打开 WebSocket 之前会向您显示权限提示；在 [自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode) 中则由分类器决定，除非适用某条 [询问规则](#bash-rules-that-deny-or-prompt-for-websocket-watches)。该提示不提供跳过同一主机的未来提示的选项。

419

420#### WebSocket 监视被拒绝的地址和主机

421

422Claude Code 拒绝指向私有、链接本地或云元数据地址的 URL，包括您的计算机解析为其中之一的主机名。在 [代理](https://code.claude.com/docs/zh-CN/network-config.md#proxy-configuration) 之后，监视可以访问私有、链接本地或云元数据地址，除非代理阻止它，因为 Claude Code 不会检查代理找到的地址。Claude Code 还拒绝 `sandbox.network.deniedDomains` 中的主机，以及当在托管设置中设置了 [`allowManagedDomainsOnly`](https://code.claude.com/docs/zh-CN/settings-reference#sandbox-network-allowmanageddomainsonly) 时，任何在托管允许列表之外的主机。

423

424如果代理之后的监视因 `could not resolve <host>` 而失败，请将 [`CLAUDE_CODE_PROXY_RESOLVES_HOSTS`](https://code.claude.com/docs/zh-CN/env-vars#variables) 设置为 `1` 并重新启动 Claude Code v2.1.319 或更高版本，以便由代理查找主机名。

425

426#### 拒绝 WebSocket 监视或对其进行提示的 Bash 规则

427

428如果 Claude Code 拒绝了打开 WebSocket 的 `Monitor` 调用，请查找写为 `Bash` 或 `Bash(*)` 的 [拒绝或询问规则](https://code.claude.com/docs/zh-CN/permissions.md#manage-permissions)。如果尽管您设置了 `Monitor` 允许规则，该调用仍出现提示，也请同样检查。针对所有 Bash 命令的规则同样涵盖这些 WebSocket 监视：

429

430* **拒绝规则**：如果该规则在会话开始时已存在，Claude 将不会拥有 Monitor 工具，因此无法启动监视。如果您在会话期间添加该规则，Claude 的下一次 `Monitor` 调用将被拒绝。拒绝信息为 `Permission to use Monitor has been denied: it runs code as Bash does, and a rule denies Bash.`

431* **询问规则**：系统会请您批准该监视。允许规则、`PreToolUse` hook、`bypassPermissions` 模式或自动模式分类器都无法代您批准。您可以通过 [`PermissionRequest` hook](https://code.claude.com/docs/zh-CN/hooks#permissionrequest) 批准它。在无人能够响应的情况下（例如在 `dontAsk` 模式中），Claude Code 会拒绝该监视。

432

433要允许这些监视运行，请将规则收窄到您实际针对的命令，例如 `Bash(rm *)`。

421 434

422Claude Code 拒绝指向私有、链接本地或云元数据地址的 URL，包括解析为其中之一的主机名。它还拒绝 `sandbox.network.deniedDomains` 中的主机，以及当在托管设置中设置了 [`allowManagedDomainsOnly`](https://code.claude.com/docs/zh-CN/settings-reference#sandbox-network-allowmanageddomainsonly) 时，任何在托管允许列表之外的主机。435在 Claude Code v2.1.319 或更高版本中，询问规则以及您在会话期间添加的拒绝规则会涵盖这些监视。

423 436

424## NotebookEdit 工具行为437## NotebookEdit 工具行为

425 438

594* 非交互式 `-p` 运行和 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/overview.md) 会话，这些没有屏幕来查看队列607* 非交互式 `-p` 运行和 [Agent SDK](https://code.claude.com/docs/zh-CN/agent-sdk/overview.md) 会话，这些没有屏幕来查看队列

595* [云会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)，无法在您的机器上写入队列608* [云会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md)，无法在您的机器上写入队列

596* [Amazon Bedrock](https://code.claude.com/docs/zh-CN/amazon-bedrock.md)、[Claude Platform on AWS](https://code.claude.com/docs/zh-CN/claude-platform-on-aws.md)、[Google Cloud's Agent Platform](https://code.claude.com/docs/zh-CN/google-vertex-ai.md) 或 [Microsoft Foundry](https://code.claude.com/docs/zh-CN/microsoft-foundry.md) 上的会话609* [Amazon Bedrock](https://code.claude.com/docs/zh-CN/amazon-bedrock.md)、[Claude Platform on AWS](https://code.claude.com/docs/zh-CN/claude-platform-on-aws.md)、[Google Cloud's Agent Platform](https://code.claude.com/docs/zh-CN/google-vertex-ai.md) 或 [Microsoft Foundry](https://code.claude.com/docs/zh-CN/microsoft-foundry.md) 上的会话

610* 通过 [LLM 网关](https://code.claude.com/docs/zh-CN/llm-gateway) 并使用网关自身的密钥或令牌访问 Claude 的会话

597* 您设置 [`CLAUDE_CODE_SEND_FEEDBACK=0`](https://code.claude.com/docs/zh-CN/env-vars) 或 [`DISABLE_FEEDBACK_COMMAND=1`](https://code.claude.com/docs/zh-CN/env-vars) 的会话，将 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 设置为任何非空值，或关闭 [功能标志获取](https://code.claude.com/docs/zh-CN/env-vars.md#features-that-need-feature-flag-fetching)611* 您设置 [`CLAUDE_CODE_SEND_FEEDBACK=0`](https://code.claude.com/docs/zh-CN/env-vars) 或 [`DISABLE_FEEDBACK_COMMAND=1`](https://code.claude.com/docs/zh-CN/env-vars) 的会话，将 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 设置为任何非空值，或关闭 [功能标志获取](https://code.claude.com/docs/zh-CN/env-vars.md#features-that-need-feature-flag-fetching)

598* 已关闭产品反馈的组织、[零数据保留的组织](https://code.claude.com/docs/zh-CN/zero-data-retention.md#features-disabled-under-zdr)，以及已应用 [HIPAA 配置](https://code.claude.com/docs/zh-CN/hipaa-setup.md) 的组织612* 已关闭产品反馈的组织、[零数据保留的组织](https://code.claude.com/docs/zh-CN/zero-data-retention.md#features-disabled-under-zdr)，以及已应用 [HIPAA 配置](https://code.claude.com/docs/zh-CN/hipaa-setup.md) 的组织

613* Claude Code 已[在报告被拒绝后停止提供反馈](https://code.claude.com/docs/zh-CN/errors.md#feedback-is-disabled-by-your-organizations-policy)的会话

599 614

600## Task 工具可用性615## Task 工具可用性

601 616

zero-data-retention.md +2 −2

Details

70 70

71### ZDR 下的模型可用性71### ZDR 下的模型可用性

72 72

73Claude Fable 5.1 和 Fable 5 是[覆盖模型](https://support.claude.com/en/articles/15425695-covered-models)，[默认需要数据保留](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)，ZDR 组织或工作区是否可以使用它们由覆盖模型政策而非 Claude Code 管理。如果您的组织无法使用它们，这些模型要么在 `/model` 选择器中不存在，要么显示为禁用，服务器无论客户端配置如何都会拒绝对其的请求。73Claude Fable 5.2、Fable 5.1 和 Fable 5 是[覆盖模型](https://support.claude.com/en/articles/15425695-covered-models)，[默认需要数据保留](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements)，ZDR 组织或工作区是否可以使用它们由覆盖模型政策而非 Claude Code 管理。如果您的组织无法使用它们，这些模型要么在 `/model` 选择器中不存在，要么显示为禁用，服务器无论客户端配置如何都会拒绝对其的请求。

74 74

~~75其他模型在 ZDR 下仍然可用。Fable 模型不是默认模型，`best` 别名在可用的地方解析为最新的 Fable 模型，在不可用的地方解析为 Opus。~~75其他模型在 ZDR 下仍然可用。Fable 模型不是默认模型，`best` 别名解析为 Opus。

76 76

77## 政策违规的数据保留77## 政策违规的数据保留

78 78

Documentation 2026-11-08 22:58 UTC to 2026-11-09 23:02 UTC