Documentation — Spybara

admin-setup.md +1 −0

Details

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

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

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

109| [Provider restrictions](/docs/zh-CN/settings-reference#allowedproviders) | 限制机器可以使用的 API 提供商。不在列表中的提供商上的会话在启动时、登录时以及下次联系 API 时被拒绝。需要 Claude Code v2.1.285 或更高版本 | `allowedProviders` |

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

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

agent-sdk/hooks.md +6 −2

Details

418 ```418 ```

419</CodeGroup>419</CodeGroup>

420 420

421要确认阻止，请在 `PreToolUse` 下注册回调，使用 `Write|Edit` 匹配器，并要求代理在 `/etc` 下创建文件：Write 工具在消息流中的结果包含 `Writing to /etc is not allowed`，并且不会创建任何文件。

422

421<h3 id="auto-approve-specific-tools">423<h3 id="auto-approve-specific-tools">

422 自动批准特定工具424 自动批准特定工具

423</h3>425</h3>

468 470

469当事件触发时，所有匹配的 hooks 并行运行。对于权限决策，最严格的结果获胜：单个 `deny` 会阻止工具调用，无论其他 hooks 返回什么。由于完成顺序是不确定的，请编写每个 hook 以独立行动，而不是依赖另一个 hook 已运行。471当事件触发时，所有匹配的 hooks 并行运行。对于权限决策，最严格的结果获胜：单个 `deny` 会阻止工具调用，无论其他 hooks 返回什么。由于完成顺序是不确定的，请编写每个 hook 以独立行动，而不是依赖另一个 hook 已运行。

470 472

471下面的示例为每个工具调用注册三个独立检查：473下面的示例为每个工具调用注册三个独立检查。其中的 hook 名称，例如 Python 中的 `audit_logger` 或 TypeScript 中的 `auditLogger`，代表您定义的回调：

472 474

473<CodeGroup>475<CodeGroup>

474 ```python Python theme={null}476 ```python Python theme={null}

500 使用多工具匹配器过滤502 使用多工具匹配器过滤

501</h3>503</h3>

502 504

503使用多工具匹配器在相关工具间共享一个回调。此示例注册三个具有不同范围的匹配器：505使用多工具匹配器在相关工具间共享一个回调。此示例注册三个具有不同范围的匹配器，其中每个 hook 名称代表您定义的回调：

504 506

505* 管道分隔的精确列表（`Write|Edit|NotebookEdit`）仅对文件修改工具触发 `file_security_hook`。507* 管道分隔的精确列表（`Write|Edit|NotebookEdit`）仅对文件修改工具触发 `file_security_hook`。

506* 正则表达式（`^mcp__`）对任何名称以 `mcp__` 开头的 MCP 工具触发 `mcp_audit_hook`。508* 正则表达式（`^mcp__`）对任何名称以 `mcp__` 开头的 MCP 工具触发 `mcp_audit_hook`。

585 ```587 ```

586</CodeGroup>588</CodeGroup>

587 589

590要确认 hook 触发，请注册回调并要求代理将小任务委派给子代理，例如列出当前目录中的文件：当子代理完成时，回调会打印 `[SUBAGENT] Completed:` 行，其中包含子代理的 ID 和脚本路径。

591

588<h3 id="make-http-requests-from-hooks">592<h3 id="make-http-requests-from-hooks">

589 从 hooks 发出 HTTP 请求593 从 hooks 发出 HTTP 请求

590</h3>594</h3>

agent-sdk/permissions.md +9 −0

Details

121 121

122权限模式提供对 Claude 如何使用工具的全局控制。您可以在调用 `query()` 时设置权限模式，或在流式会话期间动态更改它。122权限模式提供对 Claude 如何使用工具的全局控制。您可以在调用 `query()` 时设置权限模式，或在流式会话期间动态更改它。

123 123

124如果您没有设置权限模式，Claude Code 会根据[会话启动时的模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)中的规则选择起始权限模式：

125

126* 当适用时，来自会话的[设置文件](/docs/zh-CN/settings#where-settings-live)中的 `permissions.defaultMode`

127* 否则使用内置默认值，可以是[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)

128

129在自动模式下启动的会话会放弃广泛的允许规则，例如裸 `Bash` 条目，如[自动模式如何评估操作](/docs/zh-CN/permission-modes#how-auto-mode-evaluates-actions)所述。如果您的应用程序依赖于 `default` 模式或此类规则，请显式传递 `default`。

130

131在 TypeScript Agent SDK v0.3.286 之前，省略 `permissionMode` 与传递 `default` 相同。

132

124<h3 id="available-modes">133<h3 id="available-modes">

125 可用模式134 可用模式

126</h3>135</h3>

agent-sdk/python.md +245 −71

Details

517 async def set_model(self, model: str | None = None) -> None517 async def set_model(self, model: str | None = None) -> None

518 async def rewind_files(self, user_message_id: str) -> None518 async def rewind_files(self, user_message_id: str) -> None

519 async def get_mcp_status(self) -> McpStatusResponse519 async def get_mcp_status(self) -> McpStatusResponse

520 async def get_context_usage(self) -> ContextUsageResponse

520 async def reconnect_mcp_server(self, server_name: str) -> None521 async def reconnect_mcp_server(self, server_name: str) -> None

521 async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None522 async def toggle_mcp_server(self, server_name: str, enabled: bool) -> None

522 async def stop_task(self, task_id: str) -> None523 async def stop_task(self, task_id: str) -> None

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

544| `get_context_usage()` | 获取按类别、技能和工具分类的上下文窗口使用情况的详细信息。这与 `/context` 在交互式会话中显示的数据相同。返回 [`ContextUsageResponse`](#contextusageresponse)。为了计算详细信息，Claude Code 会发出几个不出现在消息流中的令牌计数 API 请求；见[这些请求如何处理](#contextusageresponse) |

616 示例 - 使用 ClaudeSDKClient 进行流式输入618 示例 - 使用 ClaudeSDKClient 进行流式输入

617</h4>619</h4>

618 620

621`query()` 也接受用户消息字典的异步可迭代对象，因此你可以在发送时组装提示或包含内容块，如图像。Claude Code 在第一个产生的消息到达时立即开始响应，无需等待可迭代对象完成，`receive_response()` 在结束该响应的 `ResultMessage` 处停止。将 Claude 应该在回答前读取的所有内容放入一条消息中，如本生成器所做的那样，并将每个 `query()` 调用与其自己的 `receive_response()` 循环配对。

622

619```python theme={null}623```python theme={null}

620import asyncio624import asyncio

621from claude_agent_sdk import ClaudeSDKClient625from claude_agent_sdk import ClaudeSDKClient

622 626

623 627

624async def message_stream():628async def message_stream():

625 """Generate messages dynamically."""629 """Assemble the prompt at send time and yield it as one user message."""

626 yield {630 readings = {"Temperature": "25°C", "Humidity": "60%"}

627 "type": "user",631 data = ", ".join(f"{name}: {value}" for name, value in readings.items())

628 "message": {"role": "user", "content": "Analyze the following data:"},

629 }

630 await asyncio.sleep(0.5)

631 yield {

632 "type": "user",

633 "message": {"role": "user", "content": "Temperature: 25°C, Humidity: 60%"},

634 }

635 await asyncio.sleep(0.5)

636 yield {632 yield {

637 "type": "user",633 "type": "user",

638 "message": {"role": "user", "content": "What patterns do you see?"},634 "message": {

635 "role": "user",

636 "content": f"Analyze the following sensor data and describe any patterns you see: {data}",

637 },

639 }638 }

640 639

641 640

1609 1608

1609<h3 id="contextusageresponse">

1610 `ContextUsageResponse`

1611</h3>

1612

1613来自 [`ClaudeSDKClient.get_context_usage()`](#methods) 的响应。这是 Claude Code 为交互式会话中的 `/context` 命令呈现的相同有效负载，因此除了令牌计数外，它还携带显示字段，如 `color` 和 `gridRows`，Claude Code 使用这些字段来绘制 `/context` 使用网格。

1614

1615Claude Code 通过向[令牌计数](https://platform.claude.com/docs/en/build-with-claude/token-counting) API 发送多个请求来构建此有效负载。这些请求不会出现在消息流中，因此读取流的成本跟踪不会看到它们。在 Anthropic API 上，令牌计数不计费。

1616

1617```python theme={null}

1618class ContextUsageResponse(TypedDict):

1619 categories: list[ContextUsageCategory]

1620 totalTokens: int

1621 maxTokens: int

1622 rawMaxTokens: int

1623 percentage: float

1624 model: str

1625 isAutoCompactEnabled: bool

1626 memoryFiles: list[dict[str, Any]]

1627 mcpTools: list[dict[str, Any]]

1628 agents: list[dict[str, Any]]

1629 gridRows: list[list[dict[str, Any]]]

1630 autoCompactThreshold: NotRequired[int]

1631 deferredBuiltinTools: NotRequired[list[dict[str, Any]]]

1632 systemTools: NotRequired[list[dict[str, Any]]]

1633 systemPromptSections: NotRequired[list[dict[str, Any]]]

1634 slashCommands: NotRequired[dict[str, Any]]

1635 skills: NotRequired[dict[str, Any]] # skill usage with frontmatter breakdown

1636 messageBreakdown: NotRequired[dict[str, Any]] # message tokens by type

1637 apiUsage: NotRequired[dict[str, Any] | None]

1638```

1639

1640每个 `ContextUsageCategory` 条目携带 `name`、`tokens`、`color` 和可选的 `isDeferred` 标志。`totalTokens` 是会话的当前上下文使用情况，`maxTokens` 是测量使用情况的窗口。该窗口是模型的上下文窗口，或当应用一个时的较低自动压缩窗口，`rawMaxTokens` 携带与 `maxTokens` 相同的值。`apiUsage` 保存最新 API 响应的使用情况，而不是会话的运行总计。Claude Code 保持可选的 `deferredBuiltinTools`、`systemTools` 和 `systemPromptSections` 键未设置，因此即使类型声明它们，也应该期望它们不存在。

1641

1610<h3 id="sdkpluginconfig">1642<h3 id="sdkpluginconfig">

1611 `SdkPluginConfig`1643 `SdkPluginConfig`

1612</h3>1644</h3>

2712 2744

2713所有内置 Claude Code 工具的输入/输出模式文档。虽然 Python SDK 不将这些导出为类型，但它们代表消息中工具输入和输出的结构。2745所有内置 Claude Code 工具的输入/输出模式文档。虽然 Python SDK 不将这些导出为类型，但它们代表消息中工具输入和输出的结构。

2714 2746

2747每个显示的输出是您从该工具的 [`UserMessage.tool_use_result`](#usermessage) 读取的值。关键名称完全按照 Claude Code 发出的方式出现。带有 `| None` 注释的关键字，以及带有"present when"或"optional"注释的关键字，在不适用时会被省略。

2748

2715<h3 id="agent">2749<h3 id="agent">

2716 Agent2750 Agent

2717</h3>2751</h3>

2805```python theme={null}2839```python theme={null}

2806{2840{

2807 "status": "remote_launched",2841 "status": "remote_launched",

2808 "taskId": str, # 远程任务的 ID2842 "taskId": str, # 分派任务的 ID

2809 "sessionUrl": str, # 远程云会话的链接2843 "sessionUrl": str, # 云会话的链接

2810 "description": str, # 任务描述2844 "description": str, # 任务描述

2811 "prompt": str, # 代理运行的提示2845 "prompt": str, # 代理运行的提示

2812 "outputFile": str, # 代理输出被写入的文件路径2846 "outputFile": str, # 代理输出被写入的文件路径

2813}2847}

2814```2848```

2815 2849

2816返回来自子代理的结果。输出在 `status` 字段上进行区分：`"completed"` 用于完成的任务，`"async_launched"` 用于后台任务，`"remote_launched"` 用于 Claude Code 分派到远程云会话的任务，其中 `sessionUrl` 链接到该会话，`taskId` 标识它。如果 Claude Code [保留了子代理的隔离 worktree](/docs/zh-CN/worktrees#isolate-subagents-with-worktrees)，`completed` 变体上的 `worktreePath` 是找到它的位置，`worktreeBranch` 是当 Claude Code 使用 git 创建 worktree 时的分支。2850返回来自子代理的结果。输出在 `status` 字段上进行区分：`"completed"` 用于完成的任务，`"async_launched"` 用于后台任务，`"remote_launched"` 用于 Claude Code 分派到云会话的任务，其中 `sessionUrl` 链接到该会话，`taskId` 标识它。如果 Claude Code [保留了子代理的隔离 worktree](/docs/zh-CN/worktrees#isolate-subagents-with-worktrees)，`completed` 变体上的 `worktreePath` 是找到它的位置，`worktreeBranch` 是当 Claude Code 使用 git 创建 worktree 时的分支。

2817 2851

2818在 `completed` 变体上，`resolvedModel` 命名子代理启动时的模型，当应用 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 或其他覆盖时，它可能与请求的 `model` 输入不同。此字段需要 Claude Code v2.1.174 或更高版本。在 `async_launched` 变体上，`resolvedModel` 命名代理移到后台时使用的模型，因此在后台转换之前发生的交换会反映在那里。两个变体上的 `modelsUsed` 字段按顺序列出使用的模型，连续重复被折叠；仅当模型在运行中被交换时才设置。`modelsUsed` 和后台转换时的 `resolvedModel` 行为需要 Claude Code v2.1.212 或更高版本。2852在 `completed` 变体上，`resolvedModel` 命名子代理启动时的模型，当应用 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 或其他覆盖时，它可能与请求的 `model` 输入不同。此字段需要 Claude Code v2.1.174 或更高版本。在 `async_launched` 变体上，`resolvedModel` 命名代理移到后台时使用的模型，因此在后台转换之前发生的交换会反映在那里。两个变体上的 `modelsUsed` 字段按顺序列出使用的模型，连续重复被折叠；仅当模型在运行中被交换时才设置。`modelsUsed` 和后台转换时的 `resolvedModel` 行为需要 Claude Code v2.1.212 或更高版本。

2819 2853

2885 2919

2886**工具名称：** `Bash`2920**工具名称：** `Bash`

2887 2921

2888关于设置前台上限的内容，见 [超时和输出限制](/docs/zh-CN/tools-reference#timeout-and-output-limits)。关于后台时间限制，见 [后台命令](/docs/zh-CN/tools-reference#background-commands)。2922关于设置前台上限的内容，见 [超时和输出限制](/docs/zh-CN/tools-reference#timeout-and-output-limits)。关于后台时间限制，见 [后台命令的时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)。

2889 2923

2890**输入：**2924**输入：**

2891 2925

2962 2996

2963```python theme={null}2997```python theme={null}

2964{2998{

2965 "message": str, # 确认消息2999 "filePath": str, # 被编辑的文件

2966 "replacements": int, # 进行的替换次数3000 "oldString": str, # 被替换的文本

2967 "file_path": str, # 被编辑的文件路径3001 "newString": str, # 替换它的文本

3002 "originalFile": str | None, # 编辑前的文件内容

3003 "structuredPatch": [ # 更改的 diff hunks

3004 {

3005 "oldStart": int,

3006 "oldLines": int,

3007 "newStart": int,

3008 "newLines": int,

3009 "lines": list[str],

3010 }

3011 ],

3012 "userModified": bool, # 用户是否在接受前更改了建议的编辑

3013 "replaceAll": bool, # 是否替换了所有出现

3014 "gitDiff": { # 文件的可选 git diff 摘要

3015 "filename": str,

3016 "status": "modified" | "added",

3017 "additions": int,

3018 "deletions": int,

3019 "changes": int,

3020 "patch": str,

3021 "repository": str | None, # 可用时的 GitHub owner/repo

3022 } | None,

2968}3023}

2969```3024```

2970 3025

2984}3039}

2985```3040```

2986 3041

2987**输出（文本文件）：**3042输出根据 Claude 读取的内容采用以下形状之一。检查 `type` 键来区分它们。

3043

3044**输出（type: `"text"`）：**

3045

3046```python theme={null}

3047{

3048 "type": "text",

3049 "file": {

3050 "filePath": str, # 被读取的文件

3051 "content": str, # 返回的内容

3052 "numLines": int, # 返回内容中的行数

3053 "startLine": int, # 内容开始的行号

3054 "totalLines": int, # 文件中的总行数

3055 "truncatedByTokenCap": bool | None, # 当整个文件读取超过令牌上限且内容是第一页时出现且为 True

3056 },

3057}

3058```

3059

3060**输出（type: `"image"`）：**

3061

3062```python theme={null}

3063{

3064 "type": "image",

3065 "file": {

3066 "base64": str, # Base64 编码的图像数据

3067 "type": "image/jpeg" | "image/png" | "image/gif" | "image/webp", # 图像 MIME 类型

3068 "originalSize": int, # 原始文件大小（字节）

3069 "dimensions": { # 坐标映射的可选大小信息

3070 "originalWidth": int | None, # 可选；原始宽度（像素）

3071 "originalHeight": int | None, # 可选；原始高度（像素）

3072 "displayWidth": int | None, # 可选；调整大小后的宽度

3073 "displayHeight": int | None, # 可选；调整大小后的高度

3074 } | None,

3075 },

3076}

3077```

3078

3079**输出（type: `"notebook"`）：**

3080

3081```python theme={null}

3082{

3083 "type": "notebook",

3084 "file": {

3085 "filePath": str, # 被读取的笔记本

3086 "cells": list, # 笔记本单元格

3087 },

3088}

3089```

3090

3091**输出（type: `"pdf"`）：**

3092

3093```python theme={null}

3094{

3095 "type": "pdf",

3096 "file": {

3097 "filePath": str, # 被读取的 PDF

3098 "base64": str, # Base64 编码的 PDF 数据

3099 "originalSize": int, # 文件大小（字节）

3100 },

3101}

3102```

3103

3104**输出（type: `"parts"`）：**

2988 3105

2989```python theme={null}3106```python theme={null}

2990{3107{

2991 "content": str, # 带行号的文件内容3108 "type": "parts",

2992 "total_lines": int, # 文件中的总行数3109 "file": {

2993 "lines_returned": int, # 实际返回的行数3110 "filePath": str, # 被读取的 PDF

3111 "originalSize": int, # 文件大小（字节）

3112 "count": int, # 提取为图像的页数

3113 "outputDir": str, # 包含提取的页面图像的目录

3114 },

3115 "firstPage": int | None, # 可选的第一个提取页面的文档页码

2994}3116}

2995```3117```

2996 3118

2997**输出（图像）：**3119**输出（type: `"file_unchanged"`）：**

2998 3120

2999```python theme={null}3121```python theme={null}

3000{3122{

3001 "image": str, # Base64 编码的图像数据3123 "type": "file_unchanged", # 文件自 Claude 在此会话中上次读取以来未更改，因此不重复内容

3002 "mime_type": str, # 图像 MIME 类型3124 "file": {

3003 "file_size": int, # 文件大小（字节）3125 "filePath": str,

3126 },

3127 "source": "seeded" | None, # 当较早的副本来自在启动时加载的 CLAUDE.md 或内存文件而不是 Read 调用时出现

3004}3128}

3005```3129```

3006 3130

3023 3147

3024```python theme={null}3148```python theme={null}

3025{3149{

3026 "message": str, # 成功消息3150 "type": "create" | "update", # 写入是创建了新文件还是覆盖了现有文件

3027 "bytes_written": int, # 写入的字节数3151 "filePath": str, # 被写入的文件

3028 "file_path": str, # 被写入的文件路径3152 "content": str, # 被写入的内容

3153 "structuredPatch": [ # Diff hunks；对于新文件、未更改或 Claude Code 跳过 diff 时为空

3154 {

3155 "oldStart": int,

3156 "oldLines": int,

3157 "newStart": int,

3158 "newLines": int,

3159 "lines": list[str],

3160 }

3161 ],

3162 "originalFile": str | None, # 之前的内容；对于新文件或之前的内容太大而无法包含时为 None

3163 "gitDiff": { # 文件的可选 git diff 摘要

3164 "filename": str,

3165 "status": "modified" | "added",

3166 "additions": int,

3167 "deletions": int,

3168 "changes": int,

3169 "patch": str,

3170 "repository": str | None, # 可用时的 GitHub owner/repo

3171 } | None,

3172 "userModified": bool | None, # 可选；用户是否在接受前编辑了建议的内容

3029}3173}

3030```3174```

3031 3175

3048 3192

3049```python theme={null}3193```python theme={null}

3050{3194{

3051 "matches": list[str], # 匹配的文件路径数组3195 "durationMs": int, # 运行搜索所花费的时间（毫秒）

3052 "count": int, # 找到的匹配数3196 "numFiles": int, # 返回的路径数，任何截断后

3053 "search_path": str, # 使用的搜索目录3197 "filenames": list[str], # 匹配的文件路径

3198 "truncated": bool, # 结果是否在 100 文件限制处被截断

3199 "totalMatches": int | None, # 可选的截断前匹配文件的总数；当 countIsComplete 为 False 时为下界

3200 "countIsComplete": bool | None, # 可选；totalMatches 是否精确

3054}3201}

3055```3202```

3056 3203

3204`totalMatches` 和 `countIsComplete` 需要 Claude Code v2.1.191 或更高版本。

3205

3057<h3 id="grep">3206<h3 id="grep">

3058 Grep3207 Grep

3059</h3>3208</h3>

3074 "-B": int | None, # 每个匹配前显示的行数3223 "-B": int | None, # 每个匹配前显示的行数

3075 "-A": int | None, # 每个匹配后显示的行数3224 "-A": int | None, # 每个匹配后显示的行数

3076 "-C": int | None, # 每个匹配前后显示的行数3225 "-C": int | None, # 每个匹配前后显示的行数

3226 "context": int | None, # 每个匹配前后显示的行数；-C 是别名

3227 "-o": bool | None, # 仅打印每行的匹配部分

3077 "head_limit": int | None, # 将输出限制为前 N 行/条目3228 "head_limit": int | None, # 将输出限制为前 N 行/条目

3229 "offset": int | None, # 在应用 head_limit 前跳过前 N 行/条目

3078 "multiline": bool | None, # 启用多行模式3230 "multiline": bool | None, # 启用多行模式

3079}3231}

3080```3232```

3081 3233

3082**输出（content 模式）：**3234**输出：**

3083 3235

3084```python theme={null}3236```python theme={null}

3085{3237{

3086 "matches": [3238 "mode": "content" | "files_with_matches" | "count" | None, # 使用的输出模式

3087 {3239 "numFiles": int, # 结果中的文件数；在 content 模式中始终为 0

3088 "file": str,3240 "filenames": list[str], # files_with_matches 模式中的匹配文件；在其他模式中为空

3089 "line_number": int | None,3241 "content": str | None, # content 模式中的匹配行，或 count 模式中的每个文件计数

3090 "line": str,3242 "numLines": int | None, # content 中的行数，在 content 模式中出现

3091 "before_context": list[str] | None,3243 "numMatches": int | None, # 总匹配计数，在 count 模式中出现

3092 "after_context": list[str] | None,3244 "totalFiles": int | None, # 可选的 head_limit 和 offset 前的总数，在 files_with_matches 模式中

3093 }3245 "totalLines": int | None, # 可选的 head_limit 和 offset 前的总数，在 content 模式中

3094 ],3246 "appliedLimit": int | None, # 当 head_limit 截断结果时出现

3095 "total_matches": int,3247 "appliedOffset": int | None, # 当应用了 offset 时出现

3096}3248}

3097```3249```

3098 3250

3099**输出（files\_with\_matches 模式）：**3251Grep 在每个输出模式中返回此 dict 形状。哪些可选键存在取决于 `output_mode`。

3100 3252

3101```python theme={null}3253`totalFiles` 需要 Claude Code v2.1.208 或更高版本。`totalLines` 需要 Claude Code v2.1.210 或更高版本。

3102{

3103 "files": list[str], # 包含匹配的文件

3104 "count": int, # 包含匹配的文件数

3105}

3106```

3107 3254

3108<h3 id="notebookedit">3255<h3 id="notebookedit">

3109 NotebookEdit3256 NotebookEdit

3127 3274

3128```python theme={null}3275```python theme={null}

3129{3276{

3130 "message": str, # 成功消息3277 "new_source": str, # 写入单元格的源代码

3131 "edit_type": "replaced" | "inserted" | "deleted", # 执行的编辑类型3278 "old_source": str | None, # 之前的单元格源代码，对于 replace 和 delete 出现

3132 "cell_id": str | None, # 受影响的单元格 ID3279 "cell_id": str | None, # 编辑的单元格的 ID，当可用时

3133 "total_cells": int, # 编辑后笔记本中的总单元格数3280 "cell_type": "code" | "markdown", # 单元格类型

3281 "language": str, # 笔记本的编程语言

3282 "edit_mode": str, # 使用的编辑模式

3283 "error": str | None, # 操作失败时的错误消息

3284 "notebook_path": str, # 笔记本文件

3285 "original_file": str, # 编辑前的笔记本内容

3286 "updated_file": str, # 编辑后的笔记本内容

3134}3287}

3135```3288```

3136 3289

3228 3381

3229```python theme={null}3382```python theme={null}

3230{3383{

3231 "message": str, # 成功消息3384 "oldTodos": [ # 更新前的待办事项列表

3232 "stats": {"total": int, "pending": int, "in_progress": int, "completed": int},3385 {

3386 "content": str,

3387 "status": "pending" | "in_progress" | "completed",

3388 "activeForm": str,

3389 }

3390 ],

3391 "newTodos": [ # 更新后的待办事项列表

3392 {

3393 "content": str,

3394 "status": "pending" | "in_progress" | "completed",

3395 "activeForm": str,

3396 }

3397 ],

3233}3398}

3234```3399```

3235 3400

3401 3566

3402```python theme={null}3567```python theme={null}

3403{3568{

3404 "message": str, # 确认消息3569 "plan": str | None, # 呈现给用户的计划

3405 "approved": bool | None, # 用户是否批准了计划3570 "isAgent": bool, # 当子代理调用工具时为 True

3571 "filePath": str | None, # 当计划被保存到文件时出现

3572 "hasTaskTool": bool | None, # 可选；Agent 工具是否在当前上下文中可用

3573 "planWasEdited": bool | None, # 当用户在批准前编辑了计划时出现且为 True

3574 "awaitingLeaderApproval": bool | None, # 当队友将计划发送给团队负责人以获得批准时出现且为 True

3575 "requestId": str | None, # 该批准请求的可选 ID

3406}3576}

3407```3577```

3408 3578

3420}3590}

3421```3591```

3422 3592

3593结果是一个列表而不是 dict，所以 `tool_use_result` 为此工具保存一个 `list`。

3594

3423**输出：**3595**输出：**

3424 3596

3425```python theme={null}3597```python theme={null}

3426{3598[ # 每个资源一个条目

3427 "resources": [

3428 {3599 {

3429 "uri": str,3600 "uri": str, # 资源 URI

3430 "name": str,3601 "name": str, # 资源名称

3431 "description": str | None,3602 "mimeType": str | None, # 可选 MIME 类型

3432 "mimeType": str | None,3603 "description": str | None, # 可选描述

3433 "server": str,3604 "server": str, # 提供此资源的服务器

3434 }3605 }

3435 ],3606]

3436 "total": int,

3437}

3438```3607```

3439 3608

3440<h3 id="readmcpresource">3609<h3 id="readmcpresource">

3457```python theme={null}3626```python theme={null}

3458{3627{

3459 "contents": [3628 "contents": [

3460 {"uri": str, "mimeType": str | None, "text": str | None, "blob": str | None}3629 {

3630 "uri": str, # 资源 URI

3631 "mimeType": str | None, # 可选 MIME 类型

3632 "text": str | None, # 文本内容，或关于二进制内容的注释

3633 "blobSavedTo": str | None, # 当 Claude Code 将二进制内容保存到磁盘时出现；保存文件的路径

3634 }

3461 ],3635 ],

3462 "server": str,3636 "error": str | None, # 当服务器无法读取资源时出现

3463}3637}

3464```3638```

3465 3639

agent-sdk/typescript.md +183 −176

Details

542| `additionalDirectories` | `string[]` | `[]` | Claude 可以访问的其他目录。SDK 将每个条目作为 `--add-dir` 传递给 Claude Code，因此使用 `project` 设置源时，Claude Code 也会[加载目录的 skills、commands 和 subagents](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) |542| `additionalDirectories` | `string[]` | `[]` | Claude 可以访问的其他目录。SDK 将每个条目作为 `--add-dir` 传递给 Claude Code，因此使用 `project` 设置源时，Claude Code 也会[加载目录的 skills、commands 和 subagents](/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) |

546| `allowDangerouslySkipPermissions` | `boolean` | `false` | 启用绕过权限。使用 `permissionMode: 'bypassPermissions'` 时需要，在启动时或稍后通过 `setPermissionMode()` 进行。请参阅 [plan mode](/docs/zh-CN/agent-sdk/permissions#plan-mode-plan) 了解它如何与 `permissionMode: 'plan'` 交互 |546| `allowDangerouslySkipPermissions` | `boolean` | `false` | 启用绕过权限。使用 `permissionMode: 'bypassPermissions'` 时需要，可在启动时或稍后通过 `setPermissionMode()` 设置。参见[计划模式](/docs/zh-CN/agent-sdk/permissions#plan-mode-plan)了解它如何与 `permissionMode: 'plan'` 交互 |

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

549| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自定义权限函数，仅在[权限流](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)落到提示时调用。不会为 `allowedTools`、allow 规则或 `permissionMode` 自动批准的调用调用。allow 规则不会预先批准[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)；请参阅 [`CanUseTool`](#canusetool) 了解详情 |549| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | 自定义权限函数，仅在[权限流程](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)转向提示时调用。不会为 `allowedTools`、allow 规则或 `permissionMode` 自动批准的调用调用。allow 规则不会预批准[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)。参见 [`CanUseTool`](#canusetool) 了解详情 |

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

557| `env` | `Record<string, string \| undefined>` | `process.env` | 环境变量。设置此选项时，这会替换子进程环境而不是与 `process.env` 合并，因此请传递 `{ ...process.env, YOUR_VAR: 'value' }` 以保留继承的变量如 `PATH`。请参阅[处理缓慢或停滞的 API 响应](#handle-slow-or-stalled-api-responses)了解此模式的示例，以及[环境变量](/docs/zh-CN/env-vars)了解底层 CLI 读取的变量。设置 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 标头中标识您的应用 |557| `env` | `Record<string, string \| undefined>` | `process.env` | 环境变量。设置时，这会替换子进程环境而不是与 `process.env` 合并，因此传递 `{ ...process.env, YOUR_VAR: 'value' }` 以保留继承的变量如 `PATH`。参见[处理缓慢或停滞的 API 响应](#handle-slow-or-stalled-api-responses)了解此模式的示例，以及[环境变量](/docs/zh-CN/env-vars)了解底层 CLI 读取的变量。设置 `CLAUDE_AGENT_SDK_CLIENT_APP` 以在 User-Agent 标头中标识您的应用 |

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

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

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

565| `includeHookEvents` | `boolean` | `false` | 在消息流中包括 hook 生命周期事件，作为 [`SDKHookStartedMessage`](#sdkhookstartedmessage)、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage)。`SessionStart` 和 `Setup` hooks 的生命周期事件始终包括在内，不需要此选项。某些 hook 事件，如 `Notification`、`SessionEnd`、`PreCompact` 和 `PostCompact`，即使使用此选项也永远不会产生 `SDKHookStartedMessage`。对于这些事件，Claude Code 仍会在运行超过一秒的命令 hook 产生输出时发出 `SDKHookProgressMessage`，并仅在[在后台运行](/docs/zh-CN/hooks#run-hooks-in-the-background)的 hook 完成时发出 `SDKHookResponseMessage` |565| `includeHookEvents` | `boolean` | `false` | 在消息流中包含 hook 生命周期事件，作为 [`SDKHookStartedMessage`](#sdkhookstartedmessage)、[`SDKHookProgressMessage`](#sdkhookprogressmessage) 和 [`SDKHookResponseMessage`](#sdkhookresponsemessage)。`SessionStart` 和 `Setup` hooks 的生命周期事件始终包含，不需要此选项。某些 hook 事件，如 `Notification`、`SessionEnd`、`PreCompact` 和 `PostCompact`，即使使用此选项也不会产生 `SDKHookStartedMessage`。对于这些事件，Claude Code 仍会在运行超过一秒的命令 hook 产生输出时发出 `SDKHookProgressMessage`，并仅在[在后台运行的 hook](/docs/zh-CN/hooks#run-hooks-in-the-background) 完成时发出 `SDKHookResponseMessage` |

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

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

574| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | 用于处理 MCP 引出请求的回调。当 MCP 服务器请求用户输入且没有 hook 首先处理它时调用。未提供时，未处理的引出请求会自动被拒绝 |574| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | 处理 MCP 引出请求的回调。当 MCP 服务器请求用户输入且没有 hook 首先处理时调用。未提供时，未处理的引出请求会自动拒绝 |

575| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 为代理结果定义输出格式。请参阅[结构化输出](/docs/zh-CN/agent-sdk/structured-outputs)了解详情 |575| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | 为代理结果定义输出格式。参见[结构化输出](/docs/zh-CN/agent-sdk/structured-outputs)了解详情 |

580| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 谁回答权限提示：`'host'` 将它们路由到您的 [`canUseTool`](#canusetool) 回调或 `permissionPromptToolName` 工具，`'none'` [拒绝会提示的调用](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)。需要 Claude Code v2.1.259 或更高版本 |580| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 谁回答权限提示：`'host'` 将它们路由到您的 [`canUseTool`](#canusetool) 回调或 `permissionPromptToolName` 工具，`'none'` [拒绝会提示的调用](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)。需要 Claude Code v2.1.259 或更高版本 |

584| `projectConfigRoot` | `string` | `undefined` | `cwd` 是 worktree 的受信任检出的绝对路径。Claude Code 从此目录而不是 `cwd` 读取项目设置、`.mcp.json` 和项目的 `.claude/` commands、agents、skills、workflows、routines 和 output styles，并将 `CLAUDE_PROJECT_DIR` 设置为它。Hooks、helper scripts 如 `apiKeyHelper` 和 stdio MCP 服务器以此目录作为其工作目录启动。`CLAUDE.md` 文件和 `.claude/rules/` 仍然从 `cwd` 加载。需要 Claude Code v2.1.275 或更高版本 |584| `projectConfigRoot` | `string` | `undefined` | `cwd` 是其 worktree 的受信任检出的绝对路径。Claude Code 从此目录而不是 `cwd` 读取项目设置、`.mcp.json` 和项目的 `.claude/` commands、agents、skills、workflows、routines 和 output styles，并将 `CLAUDE_PROJECT_DIR` 设置为它。Hooks、helper scripts 如 `apiKeyHelper` 和 stdio MCP 服务器以此目录作为其工作目录启动。`CLAUDE.md` 文件和 `.claude/rules/` 仍从 `cwd` 加载。需要 Claude Code v2.1.275 或更高版本 |

585| `promptSuggestions` | `boolean` | `false` | 启用提示建议。在每个轮次后，Claude Code 发出 `prompt_suggestion` 消息，包含预测的下一个用户提示。Claude Code 不会为某些轮次生成建议，例如当您的帐户接近或达到其使用限制时。请参阅[Claude Code 何时跳过建议](/docs/zh-CN/interactive-mode#when-claude-code-skips-suggestions) |585| `promptSuggestions` | `boolean` | `false` | 启用提示建议。在一个轮次后，Claude Code 发出一个 `prompt_suggestion` 消息，携带预测的下一个用户提示。Claude Code 对某些轮次不生成建议，例如当您的账户接近或达到使用限制时。参见[Claude Code 何时跳过建议](/docs/zh-CN/interactive-mode#when-claude-code-skips-suggestions) |

587| `resumeDropsTurn` | `string` | `undefined` | 使用 `resumeSessionAt`：截断恢复打算丢弃的轮次的提示 UUID。当丢弃的范围包含任何不可归因于该轮次的内容（例如吸收的排队消息或任务通知）时，Claude Code 会拒绝恢复，并在拒绝消息中命名 `--resume-drops-turn` 标志。仅 Agent SDK 和打印模式恢复读取该对。需要 Claude Code v2.1.223 或更高版本 |587| `resumeDropsTurn` | `string` | `undefined` | 使用 `resumeSessionAt`：截断恢复打算丢弃的轮次的提示 UUID。当丢弃的范围包含任何不可归因于该轮次的内容（如吸收的排队消息或任务通知）时，Claude Code 拒绝恢复，并在拒绝消息中命名 `--resume-drops-turn` 标志。仅 Agent SDK 和打印模式恢复读取该对。需要 Claude Code v2.1.223 或更高版本 |

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

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

599| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined`（最小提示） | 系统提示配置。传递字符串以获取自定义提示，或 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系统提示。传递一个字符串数组，其中包含导出的 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 常量在静态和每个请求部分之间，以[缓存自定义提示的静态部分](/docs/zh-CN/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt)。使用预设对象形式时，添加 `append` 以使用其他说明扩展它，并设置 `excludeDynamicSections: true` 以将每个会话上下文移到第一条用户消息中，以便[更好地跨机器重用提示缓存](/docs/zh-CN/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)。设置 `snapshot: false` 以在每个请求上重建提示，而不是[重用会话在其第一个请求上记录的提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)。要在自定义提示上设置 `snapshot`，请传递 `{ type: 'custom', prompt }` 形式。`{ type: 'custom' }` 形式和 `snapshot` 字段需要 TypeScript Agent SDK v0.3.257 或更高版本 |599| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined`（最小提示） | 系统提示配置。传递字符串以获得自定义提示，或 `{ type: 'preset', preset: 'claude_code' }` 以使用 Claude Code 的系统提示。传递字符串数组，在静态和每个请求部分之间使用导出的 `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 常量，以[缓存自定义提示的静态部分](/docs/zh-CN/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt)。使用预设对象形式时，添加 `append` 以使用其他说明扩展它，并设置 `excludeDynamicSections: true` 以将每个会话的上下文移到第一个用户消息中，以[更好地跨机器重用提示缓存](/docs/zh-CN/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)。设置 `snapshot: false` 以在每个请求上重建提示而不是[重用会话在其第一个请求上记录的提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)。要在自定义提示上设置 `snapshot`，传递 `{ type: 'custom', prompt }` 形式。`{ type: 'custom' }` 形式和 `snapshot` 字段需要 TypeScript Agent SDK v0.3.257 或更高版本 |

600| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* API 端任务预算（以令牌为单位）。设置后，模型会被告知其剩余令牌预算，以便它可以调整工具使用速度并在达到限制前完成 |600| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* API 端任务预算（令牌）。设置时，模型被告知其剩余令牌预算，以便它可以调整工具使用速度并在限制前完成 |

601| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 支持的模型为 `{ type: 'adaptive' }` | 控制 Claude 的思考/推理行为。请参阅 [`ThinkingConfig`](#thinkingconfig) 了解选项 |601| `thinking` | [`ThinkingConfig`](#thinkingconfig) | 支持的模型为 `{ type: 'adaptive' }` | 控制 Claude 的思考/推理行为。参见 [`ThinkingConfig`](#thinkingconfig) 了解选项 |

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

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

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

607 607

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

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

627});627});

628```628```

629 629

630* `API_TIMEOUT_MS`：Anthropic 客户端上的每个请求超时，以毫秒为单位。默认 `600000`。适用于主循环和所有 subagents。630* `API_TIMEOUT_MS`：Anthropic 客户端上的每个请求超时（毫秒）。默认 `600000`。适用于主循环和所有 subagents。

631* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重试次数。默认 `10`，上限为 `15`。每次重试都有自己的 `API_TIMEOUT_MS` 窗口，因此最坏情况下的实际时间大约是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加上退避。对于需要等待更长时间中断的无人值守运行，设置 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/zh-CN/errors#tune-retry-behavior)：它无限期重试瞬时容量错误，从 Claude Code v2.1.199 开始，为其他瞬时错误提高默认值至 `300` 并移除此变量的上限。631* `CLAUDE_CODE_MAX_RETRIES`：最大 API 重试次数。默认 `10`，上限 `15`。每次重试都有自己的 `API_TIMEOUT_MS` 窗口，因此最坏情况下的墙时间大约是 `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` 加退避。对于需要等待更长中断的无人值守运行，设置 [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/zh-CN/errors#tune-retry-behavior)：它无限期重试瞬时容量错误，并且在 Claude Code v2.1.199 或更高版本上，将其他瞬时错误的默认值提高到 `300` 并移除此变量的上限。

632* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：subagents 的停滞监视程序。当流监视程序打开时，默认值为 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加 5 分钟，即 `600000`，除非您提高该变量。当流监视程序关闭时，默认值为 `600000`。在 v2.1.257 之前，默认值始终为 `600000`。632* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：subagents 的停滞监视器。当流监视器打开时，默认值为 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 加 5 分钟，即 `600000`，除非您提高该变量。关闭流监视器时，默认值为 `600000`。在 v2.1.257 之前，默认值始终为 `600000`。

633 633

634 计时器在每个流事件上重置。在停滞时，Claude Code 中止 subagent 并向父级报告停滞。对于后台 subagent，它也会将任务标记为失败并附加任何部分结果。634 计时器在每个流事件上重置。停滞时，Claude Code 中止 subagent 并向父级报告停滞。对于后台 subagent，它也会标记任务失败并附加任何部分结果。

635* `CLAUDE_ENABLE_STREAM_WATCHDOG` 与 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：当标头已到达但响应正文停止流式传输时中止请求的流监视程序。监视程序对所有提供商默认启用；设置 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以禁用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默认为 `300000` 并被限制为该最小值。中止后，[自动重试](/docs/zh-CN/errors#automatic-retries)涵盖 Claude Code 根据响应进度的程度所做的事情。635* `CLAUDE_ENABLE_STREAM_WATCHDOG` 与 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：流监视器，当标头已到达但响应体停止流式传输时中止请求。监视器对所有提供商默认打开；设置 `CLAUDE_ENABLE_STREAM_WATCHDOG=0` 以禁用它。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 默认为 `300000` 并被限制在该最小值。中止后，[自动重试](/docs/zh-CN/errors#automatic-retries)涵盖 Claude Code 的操作，基于响应进展的程度。

636 636

637 当监视程序等待 `ANTHROPIC_BASE_URL` 后面的网关用保活 ping 保持打开的响应时，设置 `includePartialMessages` 的主机继续接收 `ping` [流事件](#sdkpartialassistantmessage)，因此将这些帧读作活跃性而不是在沉默时超时会话。在 v2.1.257 之前，帧在最后一个真实流事件后 5 分钟停止。637 当监视器等待 `ANTHROPIC_BASE_URL` 后面的网关用保活 ping 保持打开的响应时，设置 `includePartialMessages` 的主机继续接收 `ping` [流事件](#sdkpartialassistantmessage)，因此将这些帧读作活跃性而不是在沉默时超时会话。在 v2.1.257 之前，帧在最后一个真实流事件后 5 分钟停止。

638 638

639<h3 id="query-object">639<h3 id="query-object">

640 `Query` 对象640 `Query` 对象

641</h3>641</h3>

642 642

643由 `query()` 函数返回的接口。643`query()` 函数返回的接口。

644 644

645```typescript theme={null}645```typescript theme={null}

646interface Query extends AsyncGenerator<SDKMessage, void> {646interface Query extends AsyncGenerator<SDKMessage, void> {

696 696

697| 方法 | 描述 |697| 方法 | 描述 |

698| :- | :- |698| :- | :- |

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

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

705| `updateSettings(source, settings)` | 将一个允许列表键写入项目的本地设置文件或您的用户设置文件，以便该值对后续会话持久化。请参阅 [`updateSettings()`](#updatesettings)。需要 TypeScript SDK v0.3.257 或更高版本，它捆绑 Claude Code v2.1.257 |705| `updateSettings(source, settings)` | 将一个允许列表的键写入项目的本地设置文件或您的用户设置文件，以便该值对后续会话持久化。参见 [`updateSettings()`](#updatesettings)。需要 TypeScript SDK v0.3.257 或更高版本，它捆绑 Claude Code v2.1.257 |

707| `reinitialize()` | 重新发送 `initialize` 控制请求到运行的 CLI，并返回新的结果而不是缓存的首次连接结果。在传输间隙后使用它，例如在断开连接后重新连接到会话，以便待处理的权限请求再次到达您的 `canUseTool` 回调。使回调对每个请求 ID 幂等，因为响应丢失的请求会再次分派。需要 Claude Code v2.1.195 或更高版本 |707| `reinitialize()` | 重新发送 `initialize` 控制请求到运行的 CLI 并返回新的结果而不是缓存的首次连接结果。在传输间隙后使用它，例如在断开连接后重新连接到会话，以便待处理的权限请求再次到达您的 `canUseTool` 回调。使回调对每个请求 ID 幂等，因为响应丢失的请求会再次分派。需要 Claude Code v2.1.195 或更高版本 |

708| `supportedCommands()` | 返回可用的 slash commands。从 Agent SDK v0.3.216 开始，列表反映中期命令更改；请参阅 [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |708| `supportedCommands()` | 返回可用的命令。从 Agent SDK v0.3.216 开始，列表反映中期会话命令更改；参见 [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |

712| `getContextUsage(opts?)` | 返回 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)，按类别、skill 和工具分解会话的上下文窗口使用情况。使用默认 `detail`，它与 `/context` 在交互式会话中显示的数据相同。[`detail` 选项](#sdkcontrolgetcontextusageresponse)需要 Agent SDK v0.3.257 或更高版本 |712| `getContextUsage(opts?)` | 返回 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse)，按类别、skill 和工具分解会话的上下文窗口使用情况。使用默认 `detail`，它与 `/context` 在交互式会话中显示的数据相同，使用不出现在消息流中的令牌计数 API 请求计算；参见[这些请求如何处理](#sdkcontrolgetcontextusageresponse)。[`detail` 选项](#sdkcontrolgetcontextusageresponse)需要 Agent SDK v0.3.257 或更高版本 |

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

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

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

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

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

719| `toggleMcpServer(serverName, enabled)` | 按名称启用或禁用 MCP 服务器，名称解析与 `reconnectMcpServer()` 相同。禁用会断开服务器连接 |719| `toggleMcpServer(serverName, enabled)` | 按名称启用或禁用 MCP 服务器，使用与 `reconnectMcpServer()` 相同的名称解析。禁用 stdio、SSE 或 HTTP 服务器会断开连接并移除其工具；对于您使用 `setMcpServers()` 在中期会话添加的服务器，工具移除需要 Claude Code v2.1.285 或更高版本 |

721| `readMcpResource(serverName, uri)` | *Alpha.* 从连接的 MCP 服务器读取一个 MCP Apps `ui://` 资源，以便您的应用程序可以呈现工具的小部件。使用 [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse) 进行解决。需要 TypeScript Agent SDK v0.3.280 或更高版本 |721| `readMcpResource(serverName, uri)` | *Alpha.* 从连接的 MCP 服务器读取一个 MCP Apps `ui://` 资源，以便您的应用可以呈现工具的小部件。使用 [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse) 解决。需要 TypeScript Agent SDK v0.3.280 或更高版本 |

727 `applyFlagSettings()`727 `applyFlagSettings()`

728</h4>728</h4>

729 729

730在运行的会话上更改[设置](/docs/zh-CN/settings)而无需重新启动查询。当没有专用设置器的设置需要在会话中期更改时使用它，例如在代理读取不受信任的输入后收紧 `permissions`。`setModel()` 和 `setPermissionMode()` 是这两个键的专用设置器；`applyFlagSettings()` 是接受任何设置键子集的通用形式，在此处传递 `model` 的行为与 `setModel()` 相同。730在运行的会话上更改[设置](/docs/zh-CN/settings)而无需重启查询。当没有专用设置器的设置需要在中期会话更改时使用，例如在代理读取不受信任的输入后收紧 `permissions`。`setModel()` 和 `setPermissionMode()` 是这两个键的专用设置器；`applyFlagSettings()` 是接受任何设置键子集的通用形式，在此处传递 `model` 的行为与 `setModel()` 相同。

731 731

732仅某些键在会话中期生效：732仅某些键在中期会话生效：

733 733

734* **在下一个轮次应用**：`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。切换 `agent` 也会在下一个轮次应用该代理的模型覆盖和 hooks。其系统提示在下一个轮次应用，或在[重用记录的系统提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)的会话中，一旦会话被压缩。734* **在下一轮应用**：`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。切换 `agent` 也会在下一轮应用该代理的模型覆盖和 hooks。其系统提示在下一轮应用，或在[重用记录的系统提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)的会话中，一旦会话被压缩。

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

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

737 737

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

739 739

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

741 741

742连续调用浅合并顶级键。第二次调用 `{ permissions: {...} }` 会替换先前调用中的整个 `permissions` 对象，而不是深度合并到其中。742连续调用浅合并顶级键。第二个调用 `{ permissions: {...} }` 替换来自先前调用的整个 `permissions` 对象，而不是深度合并到其中。

743 743

744要清除您使用 `applyFlagSettings()` 设置的键，请为该键传递 `null`。大多数键然后回退首先到 `query()` 的 `settings` 选项在启动时设置的值，然后到较低优先级源。清除的 `model` 重置为[Claude Code 的默认模型](/docs/zh-CN/model-config)，即使设置文件设置 `model`。传递 `undefined` 无效，因为 JSON 序列化会将其删除。744要清除您使用 `applyFlagSettings()` 设置的键，为该键传递 `null`。大多数键然后首先回退到 `query()` 的 `settings` 选项在启动时设置的值，然后回退到较低优先级源。清除的 `model` 重置为 [Claude Code 的默认模型](/docs/zh-CN/model-config)，即使设置文件设置 `model`。传递 `undefined` 无效，因为 JSON 序列化会丢弃它。

745 745

746除了 `model` 的三个键重置会话状态而不是回退：746除 `model` 外的三个键重置会话状态而不是回退：

747 747

748* `effortLevel: null` 将会话返回到模型的默认努力级别，而不是 `query()` 的 `effort` 选项或设置文件中的 `effortLevel`。748* `effortLevel: null` 将会话返回到模型的默认努力级别，而不是 `query()` 的 `effort` 选项或设置文件中的 `effortLevel`。

749* `agent: null` 从下一个轮次开始在没有代理的情况下运行主线程，而不是恢复 `query()` 的 `agent` 选项或设置文件中的 `agent`。如果清除的代理应用了自己的模型，会话返回到在启动时解决的模型。749* `agent: null` 从下一轮开始不使用代理运行主线程，而不是恢复 `query()` 的 `agent` 选项或设置文件中的 `agent`。如果清除的代理应用了自己的模型，会话返回到在启动时解决的模型。

750* `ultracode: null` 关闭 ultracode，如 `false` 一样，而不是恢复设置文件中的 `ultracode` 值。会话保持其当前努力级别，因此在同一调用中传递 `effortLevel` 以更改它。750* `ultracode: null` 关闭 ultracode，如 `false` 一样，而不是恢复设置文件中的 `ultracode` 值。会话保持其当前努力级别，因此在同一调用中传递 `effortLevel` 以更改它。

751 751

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

753 753

754下面的示例在会话中期切换活动模型，然后清除覆盖，以便模型重置为[Claude Code 的默认模型](/docs/zh-CN/model-config)。754下面的示例在中期会话切换活动模型，然后清除覆盖，以便模型重置为 [Claude Code 的默认模型](/docs/zh-CN/model-config)。

755 755

756```typescript theme={null}756```typescript theme={null}

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

758 758

759const q = query({ prompt: messageStream });759const q = query({ prompt: messageStream });

760 760

761// 覆盖会话其余部分的模型761// Override the model for the rest of the session

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

763 763

764// 稍后：清除覆盖；模型重置为 Claude Code 的默认模型764// Later: clear the override; the model resets to Claude Code's default

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

766```766```

767 767

768<Note>768<Note>

769 `applyFlagSettings()` 仅适用于 TypeScript。Python SDK 不公开等效方法。769 `applyFlagSettings()` 仅限 TypeScript。Python SDK 不公开等效方法。

770</Note>770</Note>

771 771

772<h4 id="updatesettings">772<h4 id="updatesettings">

773 `updateSettings()`773 `updateSettings()`

774</h4>774</h4>

775 775

776将一个允许列表键写入设置文件，以便该值对加载该源的后续会话持久化。每个源接受一个键，具有字符串值：776将一个允许列表的键写入磁盘上的设置文件，以便该值对加载该源的后续会话持久化。每个源接受一个键，具有字符串值：

777 777

778* **`"localSettings"`**：接受 `outputStyle` 并将其合并到项目的本地设置文件 `.claude/settings.local.json` 中。新样式在会话的下一个请求时生效。778* **`"localSettings"`**：接受 `outputStyle` 并将其合并到项目的本地设置文件 `.claude/settings.local.json`。新样式在会话的下一个请求上生效。

779* **`"userSettings"`**：接受 `effortLevel` 并将其保存为会话当前模型的默认[努力级别](/docs/zh-CN/model-config#adjust-effort-level)，在您的用户设置文件中的 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 下。传递 `max` 不写任何内容，因为 `max` 仅限会话。运行的会话无论如何都保持其当前努力级别，因此当您也想更改它时调用 [`applyFlagSettings()`](#applyflagsettings)。此源需要 TypeScript SDK v0.3.277 或更高版本，它捆绑 Claude Code v2.1.277。779* **`"userSettings"`**：接受 `effortLevel` 并将其保存为会话当前模型的默认[努力级别](/docs/zh-CN/model-config#adjust-effort-level)，在您的用户设置文件中的 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 下。传递 `max` 不写任何内容，因为 `max` 仅限会话。运行的会话无论如何都保持其当前努力级别，因此当您也想更改那个时调用 [`applyFlagSettings()`](#applyflagsettings)。此源需要 TypeScript SDK v0.3.277 或更高版本，它捆绑 Claude Code v2.1.277。

780 780

781当请求携带任何其他键、会话通过远程传输运行以及会话的 [`settingSources`](#options) 排除您命名的源时，调用会拒绝。不支持删除键。781当请求携带任何其他键、会话在远程传输上运行以及会话的 [`settingSources`](#options) 排除您命名的源时，调用拒绝。不支持删除键。

782 782

783<h3 id="warmquery">783<h3 id="warmquery">

784 `WarmQuery`784 `WarmQuery`

785</h3>785</h3>

786 786

787由 [`startup()`](#startup) 返回的句柄。子进程已生成并初始化，因此在此句柄上调用 `query()` 会直接将提示写入准备好的进程，无需启动延迟。787由 [`startup()`](#startup) 返回的句柄。子进程已生成并初始化，因此在此句柄上调用 `query()` 将提示直接写入准备好的进程，无启动延迟。

788 788

789```typescript theme={null}789```typescript theme={null}

790interface WarmQuery extends AsyncDisposable {790interface WarmQuery extends AsyncDisposable {

800| 方法 | 描述 |800| 方法 | 描述 |

801| :- | :- |801| :- | :- |

804 804

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

806 806

807<h3 id="spareprocess">807<h3 id="spareprocess">

808 `SpareProcess`808 `SpareProcess`

809</h3>809</h3>

810 810

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

812 812

813```typescript theme={null}813```typescript theme={null}

814interface SpareProcess extends AsyncDisposable {814interface SpareProcess extends AsyncDisposable {

828 828

829| 成员 | 描述 |829| 成员 | 描述 |

830| :- | :- |830| :- | :- |

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

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

835 835

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

837 837

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

839 839

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

841 `SDKControlInitializeResponse`841 `SDKControlInitializeResponse`

857};857};

858```858```

859 859

860`hooks_applied` 报告 Claude Code 是否注册了 `initialize` 请求携带的 `hooks`。SDK 在会话启动时发送该请求一次，并在每个 [`reinitialize()`](#query-object) 调用上再次发送。该字段需要 Agent SDK v0.3.238 或更高版本。860`hooks_applied` 报告 Claude Code 是否注册了 `initialize` 请求携带的 `hooks`。SDK 在会话启动时发送该请求一次，在每个 [`reinitialize()`](#query-object) 调用上再次发送。该字段需要 Agent SDK v0.3.238 或更高版本。

861 861

862当请求不携带 hooks 时，Claude Code 会省略该字段。当请求携带 hooks 时，该值取决于请求是否是会话的第一个初始化，以及对于重复的请求，它如何到达会话：862当请求不携带 hooks 时，Claude Code 省略该字段。当请求携带 hooks 时，值取决于请求是否是会话的第一个初始化，以及对于重复的，它如何到达会话：

863 863

864* `true`：Claude Code 注册了 hooks。会话的第一个初始化返回此值。通过 CLI 的 stdin 发送的重复初始化也返回 `true`。在这种情况下，新请求中的 hooks 替换之前注册的 hooks。864* `true`：Claude Code 注册了 hooks。会话的第一个初始化返回此值。通过 CLI 的 stdin 发送的重复初始化也返回 `true`。在这种情况下，新请求中的 hooks 替换之前注册的 hooks。

865* `false`：Claude Code 忽略了 hooks。发送到远程会话的重复初始化返回此值，因此加入会话的第二个客户端无法替换第一个客户端注册的 hooks。865* `false`：Claude Code 忽略了 hooks。发送到远程会话的重复初始化返回此值，因此加入会话的第二个客户端无法替换第一个客户端注册的 hooks。

866 866

867在 Agent SDK v0.3.238 之前，响应从不携带该字段，Claude Code 在每个重复初始化上忽略 `hooks`。867在 Agent SDK v0.3.238 之前，响应从不携带该字段，Claude Code 在每个重复初始化上忽略 `hooks`。

868 868

869响应始终报告 `fast_mode_state`，当某些东西阻止[快速模式](/docs/zh-CN/fast-mode)时，`fast_mode_disabled_reason` 携带原因代码，以便您可以解释阻止的状态而不是重新推导可用性。两种行为都需要 Claude Code v2.1.219 或更高版本。在 v2.1.219 之前，当快速模式不可用时响应会省略 `fast_mode_state`，并且从不携带原因。有关原因代码及其含义，请参阅结果消息上的 [`fast_mode_disabled_reason`](#sdkresultmessage)。869响应始终报告 `fast_mode_state`，当某些东西阻止[快速模式](/docs/zh-CN/fast-mode)时，`fast_mode_disabled_reason` 在其旁边携带原因代码，以便您可以解释阻止的状态而不是重新推导可用性。两种行为都需要 Claude Code v2.1.219 或更高版本。在 v2.1.219 之前，当快速模式不可用时响应省略 `fast_mode_state`，从不携带原因。有关原因代码及其含义，参见结果消息上的 [`fast_mode_disabled_reason`](#sdkresultmessage)。

870 870

871成功 `initialize` 的控制响应包装器也携带 `pending_permission_requests` 数组。该字段位于响应包装器本身，而不是上面的 `SDKControlInitializeResponse` 有效负载中。每个条目都是一个完整的 `control_request` 消息，具有与会话在运行时为权限请求流式传输的相同 `{ type: "control_request", request_id, request }` 形状。871成功 `initialize` 的控制响应包装器也携带 `pending_permission_requests` 数组。该字段在响应包装器本身上，而不是上面的 `SDKControlInitializeResponse` 有效负载中。每个条目是一个完整的 `control_request` 消息，具有与会话在运行时为权限请求流的相同 `{ type: "control_request", request_id, request }` 形状。

872 872

873该数组列出此 Claude Code 进程已发出且尚未解决的权限请求。SDK 为您读取数组并将每个条目分派到您的 [`canUseTool`](#canusetool) 回调，这与 [`reinitialize()`](#query-object) 在传输间隙后触发的相同重新发送。使用重复的请求 ID 幂等地处理，因为条目可以重复回调已在连接断开前收到的请求。873数组列出此 Claude Code 进程已发出且尚未解决的权限请求。SDK 为您读取数组并将每个条目分派到您的 [`canUseTool`](#canusetool) 回调，与 [`reinitialize()`](#query-object) 在传输间隙后触发的相同重新传递。幂等处理重复的请求 ID，因为条目可以重复回调已在连接断开前接收的请求。

874 874

875该数组在成功 `initialize` 响应上始终存在，当此进程没有未解决的权限请求时为空。需要 Claude Code v2.1.268 或更高版本。较早的版本可能会省略该字段，因此如果您自己解析线路协议，请将缺失的字段视为较旧的 CLI，而不是没有待处理的证明。875数组在成功 `initialize` 响应上始终存在，当此进程没有未解决的权限请求时为空。需要 Claude Code v2.1.268 或更高版本。较早的版本可能省略该字段，因此如果您自己解析线路协议，将缺失字段视为较旧的 CLI 而不是没有待处理的证明。

876 876

877<h3 id="sdkcontrolinterruptresponse">877<h3 id="sdkcontrolinterruptresponse">

878 `SDKControlInterruptResponse`878 `SDKControlInterruptResponse`

879</h3>879</h3>

880 880

881中断收据：[`interrupt()`](#query-object) 在通告 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中的 `interrupt_receipt_v1` 功能的 CLI 上解决的值。需要 Claude Code v2.1.205 或更高版本。较早的 CLI 使用空成功有效负载回答中断，因此 `interrupt()` 解决为 `undefined`。881中断收据：[`interrupt()`](#query-object) 在通告 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中 `interrupt_receipt_v1` 能力的 CLI 上解决的值。需要 Claude Code v2.1.205 或更高版本。较早的 CLI 使用空成功有效负载回答中断，因此 `interrupt()` 解决为 `undefined`。

882 882

883```typescript theme={null}883```typescript theme={null}

884type SDKControlInterruptResponse = {884type SDKControlInterruptResponse = {

887};887};

888```888```

889 889

890`still_queued` 列出中断时待处理的用户消息的 UUID：仍在队列中的消息，加上 Claude Code 已从队列中取出用于下一个轮次的任何消息。除非您首先取消它，否则每个都在中断后作为其自己的轮次运行。如果您在第一个轮次启动之前中断，Claude Code 会在轮次启动时立即中止该轮次，该轮次中列出的消息不会获得响应。890`still_queued` 列出中断到达时待处理的用户消息的 UUID：仍在队列中的消息，加上 Claude Code 已从队列中取出用于下一轮的任何消息。一旦会话的第一轮开始，Claude Code 在中断后处理列出的消息，除非您首先取消它们，并可以将多个合并为一轮。如果您在第一轮开始前中断，Claude Code 在轮次开始时立即中止它，该轮次中列出的消息不会获得响应。

891 891

892使用收据来决定是否重新发送任何内容。列出的消息如果您不取消它会进入对话，因此重新发送它会向 Claude 传递两次。892使用收据决定是否重新发送任何内容。未取消的列出消息进入对话，无论是否获得响应，因此重新发送它会将其传递给 Claude 两次。

893 893

894使用这些注意事项解释列表：894使用这些注意事项解释列表：

895 895

896* 仅出现已使用 UUID 入队的消息。空数组并不意味着没有其他内容会运行。896* 仅出现使用 UUID 入队的消息。空数组不意味着没有其他内容会运行。

897* 仅列出主线程消息。寻址到 subagent 的消息超出范围。897* 仅列出主线程消息。寻址到 subagent 的消息超出范围。

898* 列表可以包括您的客户端从未发送的 UUID，例如[计划任务](/docs/zh-CN/scheduled-tasks)触发器。忽略您不识别的 UUID，而不是将其视为错误。898* 列表可以包括您的客户端从未发送的 UUID，例如[计划任务](/docs/zh-CN/scheduled-tasks)触发器。忽略您不识别的 UUID 而不是将其视为错误。

899 899

900直接驱动 CLI 控制协议的客户端（而不是通过 `interrupt()`）可以在 `interrupt` 控制请求上设置 `cancel_queued: true`。Claude Code v2.1.219 及更高版本在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中通告 `interrupt_cancel_queued_v1` 功能的支持；较早的 CLI 忽略该字段并让排队的消息照常运行。这样的中断也会取消每条否则会在 `still_queued` 下列出的消息：收据在 `cancelled` 下列出它们，`still_queued` 为空，它们都不运行。900直接驱动 CLI 控制协议的客户端（而不是通过 `interrupt()`）可以在 `interrupt` 控制请求上设置 `cancel_queued: true`。Claude Code v2.1.219 及更高版本在 [`SDKSystemMessage.capabilities`](#sdksystemmessage) 中使用 `interrupt_cancel_queued_v1` 能力通告支持；较早的 CLI 忽略该字段并让排队的消息照常运行。这样的中断也取消每条会否则在 `still_queued` 下列出的消息：收据在 `cancelled` 下列出它们，`still_queued` 为空，它们都不运行。

901 901

902`cancelled` 列表与 `still_queued` 具有相同的注意事项。`interrupt()` 方法从不发送 `cancel_queued`，因此它解决的收据不携带 `cancelled`。902`cancelled` 列表携带与 `still_queued` 相同的注意事项。`interrupt()` 方法从不发送 `cancel_queued`，因此它解决的收据不携带 `cancelled`。

903 903

904收据是在处理中断时拍摄的快照，在干净中断时，它在中断轮次的 [`SDKResultMessage`](#sdkresultmessage) 之前到达。在该结果之后读取收据而不是检查队列：循环立即启动下一个排队的轮次，因此您在结果后检查的队列已经改变。904收据是处理中断时的快照，在干净中断上它在中断轮次的 [`SDKResultMessage`](#sdkresultmessage) 之前到达。读取收据而不是在该结果后检查队列：循环立即启动下一个排队轮次，因此您在结果后检查的队列已更改。

905 905

906<h3 id="sdkcontrolgetcontextusageresponse">906<h3 id="sdkcontrolgetcontextusageresponse">

907 `SDKControlGetContextUsageResponse`907 `SDKControlGetContextUsageResponse`

908</h3>908</h3>

909 909

910[`getContextUsage()`](#query-object) 的返回类型。使用默认 `detail`，这是 Claude Code 在交互式会话中为 `/context` 命令呈现的相同有效负载，因此除了令牌计数外，它还携带显示字段，如 `color` 和 `gridRows`，Claude Code 使用这些字段来绘制 `/context` 使用情况网格。910[`getContextUsage()`](#query-object) 的返回类型。使用默认 `detail`，这是 Claude Code 在交互式会话中为 `/context` 命令呈现的相同有效负载，因此除了令牌计数外，它还携带显示字段如 `color` 和 `gridRows`，Claude Code 使用这些字段绘制 `/context` 使用网格。

911 911

912该方法的可选 `detail` 参数选择 Claude Code 如何计算每个类别。使用默认值 `'full'`，Claude Code 使用令牌计数 API 请求计算每个类别。传递 `{ detail: 'summary' }` 以从最后一个响应的使用情况和本地估计获取答案。没有令牌计数请求出去，每个类别的数字是近似的。`detail` 参数需要 Agent SDK v0.3.257 或更高版本。912方法的可选 `detail` 参数选择 Claude Code 如何计数每个类别。`detail` 参数需要 Agent SDK v0.3.257 或更高版本。

913 913

914当您发送 `/context` 作为提示而不是调用该方法时，Claude Code 会将 [`SDKContextUsage`](#sdkcontextusage) 有效负载附加到传递结果的助手消息的 `context_usage` 字段。该字段需要 Agent SDK v0.3.232 或更高版本。914* **`'full'`**：默认值。Claude Code 使用[令牌计数](https://platform.claude.com/docs/en/build-with-claude/token-counting) API 请求计数每个类别。这些请求不出现在消息流中，因此读取流的成本跟踪不会看到它们。在 Anthropic API 上，令牌计数不计费。

915* **`'summary'`**：传递 `{ detail: 'summary' }` 以从最后一个响应的使用情况和本地估计获得答案。没有令牌计数请求出去，每个类别的数字是近似的。

916

917当您发送 `/context` 作为提示而不是调用方法时，Claude Code 将 [`SDKContextUsage`](#sdkcontextusage) 有效负载附加到传递结果的助手消息的 `context_usage` 字段。该字段需要 Agent SDK v0.3.232 或更高版本。

915 918

916```typescript theme={null}919```typescript theme={null}

917type SDKControlGetContextUsageResponse = {920type SDKControlGetContextUsageResponse = {

1010 1013

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

1012 1015

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

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

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

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

1017 1020

1018`totalTokens` 是会话的当前上下文使用情况，`maxTokens` 是针对该使用情况测量的窗口。该窗口是模型的上下文窗口，或当应用一个时的较低自动压缩窗口。`rawMaxTokens` 携带与 `maxTokens` 相同的值，`percentage` 是 `totalTokens` 作为该窗口的四舍五入百分比。1021`totalTokens` 是会话的当前上下文使用情况，`maxTokens` 是使用情况测量的窗口。该窗口是模型的上下文窗口，或应用自动压缩时的较低自动压缩窗口。`rawMaxTokens` 携带与 `maxTokens` 相同的值，`percentage` 是 `totalTokens` 作为该窗口的四舍五入百分比。`apiUsage` 保存最新 API 响应的使用情况，而不是会话的运行总计。

1019 1022

1020Claude Code 保留可选的 `deferredBuiltinTools`、`systemTools` 和 `systemPromptSections` 诊断未设置，因此即使类型声明它们，也应该期望它们不存在。1023Claude Code 保留可选的 `deferredBuiltinTools`、`systemTools` 和 `systemPromptSections` 诊断未设置，因此即使类型声明它们也期望它们不存在。

1021 1024

1022<h3 id="sdkcontrolreadfileresponse">1025<h3 id="sdkcontrolreadfileresponse">

1023 `SDKControlReadFileResponse`1026 `SDKControlReadFileResponse`

1034};1037};

1035```1038```

1036 1039

1037`contents` 保存文件文本，或当您请求 `encoding: 'base64'` 时的 base64 数据；响应的 `encoding` 字段在这种情况下设置为 `'base64'`。`absPath` 是解析的绝对路径。当文件长于 `maxBytes` 上限且内容在该限制处被切割时，`truncated` 被设置。1040`contents` 保存文件文本，或当您请求 `encoding: 'base64'` 时的 base64 数据；响应的 `encoding` 字段在这种情况下设置为 `'base64'`。`absPath` 是解决的绝对路径。`truncated` 在文件长于 `maxBytes` 上限且内容在该限制处被切割时设置。

1038 1041

1039<h4 id="what-readfile-can-read">1042<h4 id="what-readfile-can-read">

1040 `readFile()` 可以读取什么1043 `readFile()` 可以读取什么

1042 1045

1043`readFile()` 提供的文件集比 Read 工具更窄：1046`readFile()` 提供的文件集比 Read 工具更窄：

1044 1047

1045* 会话的工作目录之一内的常规文件，如 `cwd` 和 `additionalDirectories`1048* 会话工作目录之一内的常规文件，例如 `cwd` 和 `additionalDirectories`

1046* Claude Code 自己的一些文件用于会话，如工具结果1049* Claude Code 自己的一些文件用于会话，例如工具结果

1047 1050

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

1049 1052

1050<h3 id="sdkcontrolreloadpluginsresponse">1053<h3 id="sdkcontrolreloadpluginsresponse">

1051 `SDKControlReloadPluginsResponse`1054 `SDKControlReloadPluginsResponse`

1076 1079

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

1078 1081

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

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

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

1082 1085

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

1084 1087

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

1086 1089

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

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

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

1090 1093

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

1092 1095

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

1094 `SDKControlReloadSkillsResponse`1097 `SDKControlReloadSkillsResponse`

1136};1139};

1137```1140```

1138 1141

1139将 `readMcpResource()` 的服务器名称作为 `mcpServerStatus()` 报告的名称和 `ui://` URI（例如工具在其 [`_meta`](#mcpserverstatus) 中声明的 `ui.resourceUri`）传递。对于任何其他 URI 方案、您的应用程序自己托管的 [SDK MCP 服务器](#createsdkmcpserver) 以及未连接的服务器，调用会拒绝。当初始化消息的 [`capabilities`](#sdksystemmessage) 包含 `mcp_read_resource_v1` 时可用。1142传递 `readMcpResource()` 服务器名称如 `mcpServerStatus()` 报告的和 `ui://` URI，例如工具在其 [`_meta`](#mcpserverstatus) 中声明的 `ui.resourceUri`。调用对任何其他 URI 方案拒绝，对于您的应用自己托管的 [SDK MCP 服务器](#createsdkmcpserver)，以及对于未连接的服务器。当初始化消息的 [`capabilities`](#sdksystemmessage) 包含 `mcp_read_resource_v1` 时可用。

1143

1144每个 `contents` 条目是服务器发送的一个内容项，减去 `com.anthropic/` 前缀下的任何 `_meta` 键，这是为 Claude Code 保留的。`blob` 为二进制项保存 base64 数据，`_meta` 是项目自己的 `_meta`，MCP Apps 服务器在其中放置资源的 `ui.csp` 和 `ui.permissions`。

1140 1145

1141每个 `contents` 条目是服务器发送的一个内容项。`blob` 为二进制项保存 base64 数据，`_meta` 是项目自己的 `_meta`，其中 MCP Apps 服务器放置资源的 `ui.csp` 和 `ui.permissions`。内容是不受信任的第三方 HTML，因此在沙箱中呈现它们。1146内容是不受信任的第三方 HTML，因此在沙箱中呈现它们。

1142 1147

1143<h3 id="agentdefinition">1148<h3 id="agentdefinition">

1144 `AgentDefinition`1149 `AgentDefinition`

1169| 字段 | 必需 | 描述 |1174| 字段 | 必需 | 描述 |

1170| :- | :- | :- |1175| :- | :- | :- |

1171| `description` | 是 | 何时使用此代理的自然语言描述 |1176| `description` | 是 | 何时使用此代理的自然语言描述 |

1172| `tools` | 否 | 允许的工具名称数组。如果省略，继承[可用于 subagents 的每个工具](/docs/zh-CN/sub-agents#available-tools)。要将 Skills 预加载到代理的上下文中，请使用 `skills` 字段而不是在此处列出 `'Skill'` |1177| `tools` | 否 | 允许的工具名称数组。如果省略，继承[可用于 subagents 的每个工具](/docs/zh-CN/sub-agents#available-tools)。要将 Skills 预加载到代理的上下文中，使用 `skills` 字段而不是在此处列出 `'Skill'` |

1173| `disallowedTools` | 否 | 要为此代理明确禁止的工具名称数组。也接受 MCP 服务器级别的模式：`mcp__server` 或 `mcp__server__*` 移除该服务器的每个工具，`mcp__*` 移除任何服务器的每个 MCP 工具 |1178| `disallowedTools` | 否 | 要为此代理明确禁止的工具名称数组。也接受 MCP 服务器级别的模式：`mcp__server` 或 `mcp__server__*` 移除该服务器的每个工具，`mcp__*` 移除任何服务器的每个 MCP 工具 |

1174| `prompt` | 是 | 代理的系统提示 |1179| `prompt` | 是 | 代理的系统提示 |

1175| `model` | 否 | 此代理的模型覆盖。接受别名，如 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'`，或完整的模型 ID。`'inherit'` 使用主模型。当您省略它时，Claude Code 在[subagent 模型顺序](/docs/zh-CN/sub-agents#choose-a-model)中选择模型 |1180| `model` | 否 | 此代理的模型覆盖。接受别名如 `'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'` 或完整模型 ID。`'inherit'` 使用主模型。当您省略它时，Claude Code 在[subagent 模型顺序](/docs/zh-CN/sub-agents#choose-a-model)中选择模型 |

1176| `mcpServers` | 否 | 此代理的 MCP 服务器规范 |1181| `mcpServers` | 否 | 此代理的 MCP 服务器规范 |

1177| `skills` | 否 | 要预加载到代理上下文中的 skill 名称数组 |1182| `skills` | 否 | 要预加载到代理上下文中的 skill 名称数组 |

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

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

1180| `background` | 否 | 调用时将此代理作为非阻塞后台任务运行 |1185| `background` | 否 | 当调用时作为非阻止后台任务运行此代理 |

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

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

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

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

1185| `criticalSystemReminder_EXPERIMENTAL` | 否 | 实验性：添加到系统提示的关键提醒 |1190| `criticalSystemReminder_EXPERIMENTAL` | 否 | 实验性：添加到系统提示的关键提醒 |

1186 1191

1187<h3 id="agentmcpserverspec">1192<h3 id="agentmcpserverspec">

1188 `AgentMcpServerSpec`1193 `AgentMcpServerSpec`

1189</h3>1194</h3>

1190 1195

1191指定 subagent 可用的 MCP 服务器。可以是服务器名称（字符串，引用父级 `mcpServers` 配置中的服务器）或内联服务器配置记录，将服务器名称映射到配置。1196指定可用于 subagent 的 MCP 服务器。可以是服务器名称（引用父级 `mcpServers` 配置中的服务器的字符串）或内联服务器配置记录，将服务器名称映射到配置。

1192 1197

1193```typescript theme={null}1198```typescript theme={null}

1194type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;1199type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;

1200 `SettingSource`1205 `SettingSource`

1201</h3>1206</h3>

1202 1207

1203控制 SDK 从哪些基于文件系统的配置源加载设置。1208控制 SDK 加载设置的基于文件系统的配置源。

1204 1209

1205```typescript theme={null}1210```typescript theme={null}

1206type SettingSource = "user" | "project" | "local";1211type SettingSource = "user" | "project" | "local";

1210| :- | :- | :- |1215| :- | :- | :- |

1214 1219

1215<h4 id="default-behavior">1220<h4 id="default-behavior">

1216 默认行为1221 默认行为

1217</h4>1222</h4>

1218 1223

1219当 `settingSources` 被省略或 `undefined` 时，`query()` 加载与 Claude Code CLI 相同的文件系统设置：用户、项目和本地。请参阅[settingSources 不控制的内容](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control)了解无论此选项如何都会读取的输入，以及如何禁用它们。1224当 `settingSources` 被省略或 `undefined` 时，`query()` 加载与 Claude Code CLI 相同的文件系统设置：用户、项目和本地。参见[`settingSources` 不控制什么](/docs/zh-CN/agent-sdk/claude-code-features#what-settingsources-does-not-control)了解无论此选项如何都读取的输入，以及如何禁用它们。

1220 1225

1221<h4 id="why-use-settingsources">1226<h4 id="why-use-settingsources">

1222 为什么使用 settingSources1227 为什么使用 settingSources

1227```typescript theme={null}1232```typescript theme={null}

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

1229 1234

1230// 不从磁盘加载用户、项目或本地设置1235// Do not load user, project, or local settings from disk

1231const result = query({1236const result = query({

1232 prompt: "Analyze this code",1237 prompt: "Analyze this code",

1233 options: { settingSources: [] }1238 options: { settingSources: [] }

1239```typescript theme={null}1244```typescript theme={null}

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

1241 1246

1242// 仅加载项目设置，忽略用户和本地1247// Load only project settings, ignore user and local

1243const result = query({1248const result = query({

1244 prompt: "Run CI checks",1249 prompt: "Run CI checks",

1245 options: {1250 options: {

1246 settingSources: ["project"] // 仅 .claude/settings.json1251 settingSources: ["project"] // Only .claude/settings.json

1247 }1252 }

1248});1253});

1249```1254```

1250 1255

1251要加载 CLAUDE.md 项目说明，请在 `settingSources` 中包含 `"project"`。请参阅[修改系统提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions)了解 CLAUDE.md 加载如何与系统提示选项交互。1256要加载 CLAUDE.md 项目说明，在 `settingSources` 中包含 `"project"`。参见[修改系统提示](/docs/zh-CN/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions)了解 CLAUDE.md 加载如何与系统提示选项交互。

1252 1257

1253<h4 id="settings-precedence">1258<h4 id="settings-precedence">

1254 设置优先级1259 设置优先级

1255</h4>1260</h4>

1256 1261

1257加载多个源时，设置按此优先级合并（从高到低）：1262当加载多个源时，设置以此优先级合并（最高到最低）：

1258 1263

12591. 本地设置（`.claude/settings.local.json`）12641. 本地设置（`.claude/settings.local.json`）

12602. 项目设置（`.claude/settings.json`）12652. 项目设置（`.claude/settings.json`）

12613. 用户设置（`~/.claude/settings.json`）12663. 用户设置（`~/.claude/settings.json`）

1262 1267

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

1264 1269

1265<h3 id="permissionmode">1270<h3 id="permissionmode">

1266 `PermissionMode`1271 `PermissionMode`

1268 1273

1269```typescript theme={null}1274```typescript theme={null}

1270type PermissionMode =1275type PermissionMode =

1271 | "default" // 标准权限行为1276 | "default" // Standard permission behavior

1272 | "acceptEdits" // 自动接受文件编辑1277 | "acceptEdits" // Auto-accept file edits

1273 | "bypassPermissions" // 绕过权限检查；显式 ask 规则仍然提示1278 | "bypassPermissions" // Bypass permission checks; explicit ask rules still prompt

1274 | "plan" // Plan Mode - 仅读取工具1279 | "plan" // Planning mode - explore without editing

1275 | "dontAsk" // 不提示权限，如果未预先批准则拒绝1280 | "dontAsk" // Don't prompt for permissions, deny if not pre-approved

1276 | "auto"; // 模型分类器批准或拒绝权限提示1281 | "auto"; // A model classifier reviews actions such as shell commands and network requests

1277```1282```

1278 1283

1279<h3 id="canusetool">1284<h3 id="canusetool">

1282 1287

1283用于控制工具使用的自定义权限函数类型。1288用于控制工具使用的自定义权限函数类型。

1284 1289

1285该函数是 SDK 替代交互式权限提示：仅当[权限评估流](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)解决为提示时才调用它。已由 `allowedTools` 条目、设置 allow 规则或权限模式（如 `acceptEdits` 或 `bypassPermissions`）批准的工具调用永远不会调用它。要限制每个工具调用，请改用 [`PreToolUse` hook](/docs/zh-CN/agent-sdk/hooks)。1290该函数是交互式权限提示的 SDK 替代品：仅当[权限评估流程](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)解决为提示时调用。已由 `allowedTools` 条目、设置 allow 规则或权限模式（如 `acceptEdits` 或 `bypassPermissions`）预批准的工具调用从不调用它。要限制每个工具调用，改用 [`PreToolUse` hook](/docs/zh-CN/agent-sdk/hooks)。

1286 1291

1287[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)不会被 allow 规则预先批准；请参阅[权限如何被评估](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)了解哪些到达回调以及在 `dontAsk` 和 `auto` 模式下会发生什么。1292allow 规则不预批准[任何模式都不自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)；参见[权限如何评估](/docs/zh-CN/agent-sdk/permissions#how-permissions-are-evaluated)了解其中哪些到达回调以及在 `dontAsk` 和 `auto` 模式中发生什么。

1288 1293

1289```typescript theme={null}1294```typescript theme={null}

1290type CanUseTool = (1295type CanUseTool = (

1307 1312

1308| 选项 | 类型 | 描述 |1313| 选项 | 类型 | 描述 |

1309| :- | :- | :- |1314| :- | :- | :- |

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

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

1320 1325

1321回调通常通过返回 [`PermissionResult`](#permissionresult) 来解决请求，SDK 将其写回其传输作为 `control_response`。仅当您的应用程序已通过其自己的通道为此请求发送 `control_response`（回显 `requestId`）时才返回 `null`；SDK 然后跳过将响应写入其传输。在任何其他情况下返回 `null` 会使工具调用无限期被阻止，因为永远不会发送 `control_response` 且权限提示不会超时。1326回调通常通过返回 [`PermissionResult`](#permissionresult) 解决请求，SDK 将其写回其传输作为 `control_response`。仅当您的应用已通过其自己的通道为此请求发送 `control_response`（回显 `requestId`）时才返回 `null`；SDK 然后跳过写入响应到其传输。在任何其他情况下返回 `null` 会使工具调用无限期阻止，因为从不发送 `control_response` 且权限提示不超时。

1322 1327

1323`requestId` 选项和 `null` 返回值需要 Claude Code v2.1.199 或更高版本。1328`requestId` 选项和 `null` 返回值需要 Claude Code v2.1.199 或更高版本。

1324 1329

1442 `SdkPluginConfig`1447 `SdkPluginConfig`

1443</h3>1448</h3>

1444 1449

1445SDK 中加载 plugins 的配置。1450在 SDK 中加载插件的配置。

1446 1451

1447```typescript theme={null}1452```typescript theme={null}

1448type SdkPluginConfig = {1453type SdkPluginConfig = {

1454 1459

1455| 字段 | 类型 | 描述 |1460| 字段 | 类型 | 描述 |

1456| :- | :- | :- |1461| :- | :- | :- |

1460 1465

1461**示例：**1466**示例：**

1462 1467

1467];1472];

1468```1473```

1469 1474

1470有关创建和使用 plugins 的完整信息，请参阅[Plugins](/docs/zh-CN/agent-sdk/plugins)。1475有关创建和使用插件的完整信息，参见[插件](/docs/zh-CN/agent-sdk/plugins)。

1471 1476

1472<h2 id="message-types">1477<h2 id="message-types">

1473 消息类型1478 消息类型

1819```typescript theme={null}1824```typescript theme={null}

1820type SDKStartupFailureReason =1825type SDKStartupFailureReason =

1821 | "org_pin_api_key_conflict"1826 | "org_pin_api_key_conflict"

1827 | "provider_not_allowed"

1822 | "org_verify_failed"1828 | "org_verify_failed"

1823 | "org_pin_mismatch"1829 | "org_pin_mismatch"

1824 | "managed_settings_invalid"1830 | "managed_settings_invalid"

1841| 值 | 停止会话的原因 |1847| 值 | 停止会话的原因 |

1842| :- | :- |1848| :- | :- |

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

1850| `provider_not_allowed` | 托管设置[列出此机器可能使用的 API 提供商](/docs/zh-CN/settings-reference#allowedproviders)，会话设置为不在列表中的提供商，或设置未固定的端点。需要 Claude Code v2.1.285 或更高版本 |

1846| `managed_settings_invalid` | 无法读取托管策略设置，pin 未命名任何组织，或[托管模型限制](/docs/zh-CN/errors#managed-settings-block-the-default-model)为默认选项留下没有允许的模型 |1853| `managed_settings_invalid` | 无法读取托管策略设置，pin 未命名任何组织，或[托管模型限制](/docs/zh-CN/errors#managed-settings-block-the-default-model)为默认选项留下没有允许的模型 |

2064 2071

2065<h3 id="sdkpermissiondenial">2072<h3 id="sdkpermissiondenial">

2080 `SDKContextUsage`2087 `SDKContextUsage`

2081</h3>2088</h3>

2082 2089

2083`/context` 报告的结构化形式，作为 `context_usage` 在传递 `/context` 结果的 [`SDKAssistantMessage`](#sdkassistantmessage) 上携带。Agent SDK v0.3.232 及更高版本导出该类型。与 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) 不同，它仅携带呈现使用情况分解所需的数据，不包含 `color` 和 `gridRows` 等显示字段。2090`/context` 报告的结构化形式，作为 `context_usage` 在传递 `/context` 结果的 [`SDKAssistantMessage`](#sdkassistantmessage) 上携带。Agent SDK v0.3.232 及更高版本导出该类型。与 [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) 不同，它仅携带呈现使用情况分解所需的数据，不包含 `color` 和 `gridRows` 等显示字段。Claude Code 使用不出现在消息流中的令牌计数 API 请求计算报告；请参阅[这些请求如何处理](#sdkcontrolgetcontextusageresponse)。

2084 2091

2085```typescript theme={null}2092```typescript theme={null}

2086type SDKContextUsage = {2093type SDKContextUsage = {

3181};3188};

3182```3189```

3183 3190

3184执行 Bash 命令，支持可选超时和后台执行。工作目录在命令之间保持不变，包括多轮会话后续轮次中运行的命令；shell 状态（如导出的环境变量）不保持。有关哪些目录更改会保持的限制，请参阅[命令之间保持什么](/docs/zh-CN/tools-reference#what-persists-between-commands)。有关设置前台上限的内容，请参阅[超时和输出限制](/docs/zh-CN/tools-reference#timeout-and-output-limits)。有关后台时间限制，请参阅[后台命令](/docs/zh-CN/tools-reference#background-commands)。3191执行 Bash 命令，支持可选超时和后台执行。工作目录在命令之间保持不变，包括多轮会话后续轮次中运行的命令；shell 状态（如导出的环境变量）不保持。有关哪些目录更改会保持的限制，请参阅[命令之间保持什么](/docs/zh-CN/tools-reference#what-persists-between-commands)。有关设置前台上限的内容，请参阅[超时和输出限制](/docs/zh-CN/tools-reference#timeout-and-output-limits)。有关后台时间限制，请参阅[后台命令的时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)。

3185 3192

3186<h3 id="monitor">3193<h3 id="monitor">

3187 Monitor3194 Monitor

4085 4092

4086`timedOutAfterMs` 是超时时间（以毫秒为单位），当命令达到其超时并移至后台而不是显式启动时设置。`backgroundCwdHint` 在后台命令包含目录更改内置命令（如 `cd`、`pushd`、`popd` 或 `chdir`）时设置，并注意会话工作目录未更改。两个字段都需要 Claude Code v2.1.210 或更高版本。4093`timedOutAfterMs` 是超时时间（以毫秒为单位），当命令达到其超时并移至后台而不是显式启动时设置。`backgroundCwdHint` 在后台命令包含目录更改内置命令（如 `cd`、`pushd`、`popd` 或 `chdir`）时设置，并注意会话工作目录未更改。两个字段都需要 Claude Code v2.1.210 或更高版本。

4087 4094

4088当在前台运行的子代理拥有后台命令时，该命令[在该子代理的运行结束时结束](/docs/zh-CN/tools-reference#background-commands)。Claude Code 在此类命令上将 `backgroundEndsWithFinalResponse` 设置为 `true`，并在命令存活该轮时省略该字段，如主对话或后台子代理启动的命令那样。该字段需要 Claude Code v2.1.227 或更高版本。4095当在前台运行的子代理拥有后台命令时，该命令[在该子代理的运行结束时结束](/docs/zh-CN/tools-reference#when-a-background-command-stops)。Claude Code 在此类命令上将 `backgroundEndsWithFinalResponse` 设置为 `true`，并在命令存活该轮时省略该字段，如主对话或后台子代理启动的命令那样。该字段需要 Claude Code v2.1.227 或更高版本。

4089 4096

4090Claude Code 将 `gitOperation.commit.branch` 设置为 git 提交摘要行中命名的分支，对于在分离 HEAD 上进行的提交则省略它。该字段需要 Agent SDK v0.3.227 或更高版本。Claude Code 将 `gh pr reopen` 命令报告为 `reopened` PR 操作，这需要 Agent SDK v0.3.234 或更高版本。4097Claude Code 将 `gitOperation.commit.branch` 设置为 git 提交摘要行中命名的分支，对于在分离 HEAD 上进行的提交则省略它。该字段需要 Agent SDK v0.3.227 或更高版本。Claude Code 将 `gh pr reopen` 命令报告为 `reopened` PR 操作，这需要 Agent SDK v0.3.234 或更高版本。

4091 4098

agent-view.md +2 −20

Details

8 8

9Agent view 通过 `claude agents` 打开，是所有后台会话的一个屏幕：什么正在运行、什么需要你的输入、什么已完成。调度新会话，一目了然地查看它们的状态而不是滚动浏览记录，只在需要时才介入。每个后台会话都是一个完整的 Claude Code 对话，在没有终端连接的情况下继续运行，所以你可以随时打开它、回复并离开。9Agent view 通过 `claude agents` 打开，是所有后台会话的一个屏幕：什么正在运行、什么需要你的输入、什么已完成。调度新会话，一目了然地查看它们的状态而不是滚动浏览记录，只在需要时才介入。每个后台会话都是一个完整的 Claude Code 对话，在没有终端连接的情况下继续运行，所以你可以随时打开它、回复并离开。

10 10

11<img src="https://mintcdn.com/claude-code/1B48Qz2Z9hac4SLG/images/agent-view-light.png?fit=max&auto=format&n=1B48Qz2Z9hac4SLG&q=85&s=7a186c96ed47d6700d084d77e786be65" className="dark:hidden" alt="终端中的 Agent view：标题显示 Claude Code v2.1.140、模型、工作目录和摘要计数。会话分组在'需要输入'、'正在工作'和'已完成'下，底部有调度输入和键盘提示页脚。" width="1772" height="780" data-path="images/agent-view-light.png" />11<img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/agent-view-light.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=d6905012bee31f3e6b3920b09c05dd02" className="dark:hidden" alt="终端中的 Agent view。顶部的一行计算等待输入、正在工作和已完成的会话。四个会话分组在'需要输入'、'正在工作'和'已完成'下。每行显示会话的名称、其最新状态或问题以及时间。底部是用于描述新任务的输入和一行键盘提示。" width="1872" height="680" data-path="images/agent-view-light.png" />

12 12

13<img src="https://mintcdn.com/claude-code/1B48Qz2Z9hac4SLG/images/agent-view-dark.png?fit=max&auto=format&n=1B48Qz2Z9hac4SLG&q=85&s=a5bed7434bae368faea3a8f023b52aa2" className="hidden dark:block" alt="终端中的 Agent view：标题显示 Claude Code v2.1.140、模型、工作目录和摘要计数。会话分组在'需要输入'、'正在工作'和'已完成'下，底部有调度输入和键盘提示页脚。" width="1772" height="780" data-path="images/agent-view-dark.png" />13<img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/agent-view-dark.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=fc3c195bfc57e313ced1f1beb36cee93" className="hidden dark:block" alt="终端中的 Agent view。顶部的一行计算等待输入、正在工作和已完成的会话。四个会话分组在'需要输入'、'正在工作'和'已完成'下。每行显示会话的名称、其最新状态或问题以及时间。底部是用于描述新任务的输入和一行键盘提示。" width="1872" height="680" data-path="images/agent-view-dark.png" />

14 14

15当你有多个独立任务 Claude 可以在不需要你观看每一步的情况下处理时，使用 agent view。调度一个 bug 修复、一个拉取请求审查和一个不稳定测试调查作为三行，在另一个窗口中继续工作，当一行显示它需要你或有结果时检查回来。15当你有多个独立任务 Claude 可以在不需要你观看每一步的情况下处理时，使用 agent view。调度一个 bug 修复、一个拉取请求审查和一个不稳定测试调查作为三行，在另一个窗口中继续工作，当一行显示它需要你或有结果时检查回来。

16 16

966 966

967Claude Code 永远不会重新启动运行[shell 命令](#run-a-shell-command)的行，无论是从 `Enter` 还是从 `claude attach`，因为那样会再次运行该命令；该行的消息和 `claude attach` 都说该命令不会再次运行。967Claude Code 永远不会重新启动运行[shell 命令](#run-a-shell-command)的行，无论是从 `Enter` 还是从 `claude attach`，因为那样会再次运行该命令；该行的消息和 `claude attach` 都说该命令不会再次运行。

968 968

969<h4 id="terminal-host-died">

970 终端主机已死亡

971</h4>

~~972~~

973在 Linux 和 WSL 上，主管每隔几秒检查一次每个主机进程，无论您是否打开会话，当进程已退出但其与主管的连接从未关闭时，将会话标记为失败。

~~974~~

975* 在代理视图中，该行显示 `terminal host process died — press Enter to restart`。在它上面按 `Enter`，Claude Code 在新的主机进程上重新启动会话。

976* 从 shell，`claude attach <id>` 重新启动已标记为失败的会话。否则它报告原因并退出，告诉您运行 `claude attach <id>`。

~~977~~

978<h4 id="session-isn’t-responding">

979 会话没有响应

980</h4>

~~981~~

982当主管接受打开但约十秒内没有输出到达时，Claude Code 结束尝试并提供重新启动。仅仅停滞的会话，例如跨机器睡眠，不会达到此提议：主管[在打开时自己重新启动它](#read-session-state)。

~~983~~

984* 在代理视图中，页脚显示 `Press enter again to restart this session — it isn't responding (its conversation is saved and resumes).` 在同一行上再次按 `Enter`，Claude Code 停止无响应的进程并重新启动会话；没有第二次按下，它不会停止任何内容。

985* 从 shell，`claude attach <id>` 报告原因并退出，告诉您运行 `claude stop <id>`，然后 `claude attach <id>`。

~~986~~

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

988 会话在启动前失败，并显示 `possibly low memory` 注释970 会话在启动前失败，并显示 `possibly low memory` 注释

989</h3>971</h3>

amazon-bedrock.md +12 −0

Details

384 384

385模型别名（如 `opus`）不充当固定版本，Claude Code 无法识别的模型 ID（如应用推理配置文件 ARN）也不充当固定版本。385模型别名（如 `opus`）不充当固定版本，Claude Code 无法识别的模型 ID（如应用推理配置文件 ARN）也不充当固定版本。

386 386

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

388

389<h3 id="when-a-model-is-disabled-mid-session">

390 当模型在会话中被禁用时

391</h3>

392

393如果您的账户失去对会话正在运行的模型的访问权限，例如因为管理员在您的 Amazon Bedrock 账户中禁用了它，Claude Code 会将会话切换到另一个模型，而不是使每个请求都失败，并显示 `Switched to <fallback> because <model> is not available`。它尝试与启动回退相同的模型：首先尝试同一层级的早期版本，对于没有可用 Opus 版本的 Opus 会话，则使用默认 Sonnet 模型。

394

395切换仅适用于您未固定的层级，这与启动回退的条件相同。在您选择的特定版本上的会话，或在[应用推理配置文件 ARN](#map-each-model-version-to-an-inference-profile) 上的会话，会保持其模型，没有回退模型链，请求会失败。在[自动模式](/docs/zh-CN/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)中，Claude Code 仅切换到自动模式在 Amazon Bedrock 上支持的模型。如果这些模型中也没有可用的，请求会失败并显示 [AWS 身份验证失败](/docs/zh-CN/errors#aws-authentication-failed)，并提示启用该模型。

396

397您配置的[回退模型链](/docs/zh-CN/model-config#fallback-model-chains)会替换层级切换：在这些拒绝上，Claude Code 会切换到您配置的回退模型。要使被拒绝的请求失败而不是切换，请设置 [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](/docs/zh-CN/env-vars)。您配置的回退链仍会在这些拒绝上切换；如果您希望每个被拒绝的请求都失败，也请移除该链。

398

387<h2 id="cross-region-inference-profile-prefixes">399<h2 id="cross-region-inference-profile-prefixes">

388 跨区域推理配置文件前缀400 跨区域推理配置文件前缀

389</h2>401</h2>

artifacts.md +1 −1

Details

400 400

401一旦您在 [`--settings`](/docs/zh-CN/cli-reference#cli-flags) 文件中或使用 `CLAUDE_CODE_DISABLE_ARTIFACT` 关闭 artifacts，或您的管理员在[托管设置](/docs/zh-CN/server-managed-settings)中关闭它们，任何设置文件都无法将其重新打开。在 v2.1.242 之前，[优先级堆栈](/docs/zh-CN/settings#settings-precedence)中较高位置的文件可能会重新打开 artifacts，即使较低优先级的文件设置了 `"enableArtifact": false`。401一旦您在 [`--settings`](/docs/zh-CN/cli-reference#cli-flags) 文件中或使用 `CLAUDE_CODE_DISABLE_ARTIFACT` 关闭 artifacts，或您的管理员在[托管设置](/docs/zh-CN/server-managed-settings)中关闭它们，任何设置文件都无法将其重新打开。

402 402

403您也可以在项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中设置 `"enableArtifact": false` 来为该项目中的会话关闭 artifacts。任何文件中的 `"enableArtifact": true` 都不会将其重新打开。在项目和本地设置中支持此键需要 Claude Code v2.1.242 或更高版本。403您也可以在项目的 `.claude/settings.json` 或 `.claude/settings.local.json` 中设置 `"enableArtifact": false` 来为该项目中的会话关闭 artifacts。任何文件中的 `"enableArtifact": true` 都不会将其重新打开。在项目和本地设置中支持此键需要 Claude Code v2.1.242 或更高版本。

404 404

authentication.md +20 −0

Details

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

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

196 196

197<h3 id="restrict-which-api-providers-a-machine-may-use">

198 限制机器可能使用的 API 提供商

199</h3>

200

201[`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders) 在 [托管设置](/docs/zh-CN/managed-settings) 中列出托管机器可能通过哪些服务访问 Claude，例如 Anthropic API、Amazon Bedrock 或 LLM 网关。它补充 `forceLoginMethod` 和 `forceLoginOrgUUID`，它们管理会话在与 Anthropic 通信时使用的账户。需要 Claude Code v2.1.285 或更高版本。

202

203```json managed-settings.json theme={null}

204{

205 "forceLoginMethod": "claudeai",

206 "forceLoginOrgUUID": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"],

207 "allowedProviders": ["anthropic", "bedrock"]

208}

209```

210

211使用此文件，登录到您的 claude.ai 组织或为 Amazon Bedrock 配置的开发人员正常启动。为任何其他提供商设置的会话在启动时被拒绝，运行中切换到一个的会话在其下一个请求时被拒绝。[托管设置不允许此 API 提供商](/docs/zh-CN/errors#managed-settings-dont-allow-this-api-provider) 显示每条消息。

212

213* **允许 LLM 网关或代理**：列出 `"customEndpoint"` 并在同一源的托管 `env` 块中设置网关的 URL。[设置参考](/docs/zh-CN/settings-reference#allowedproviders) 列出每个值并说明哪些端点变量需要托管 `env` 引脚。

214* **在托管机器上部署**：将列表放在承载您的其余策略的托管源中。条目的 [范围说明](/docs/zh-CN/settings-reference#allowedproviders) 说明服务器托管列表如何与其结合。

215* **仅服务器托管设置**：您仅在 [服务器托管设置](/docs/zh-CN/server-managed-settings) 中设置的列表仅到达获取您的组织设置的会话，因此将其视为您无法通过设备管理到达的机器的便利，而不是强制执行。[平台可用性](/docs/zh-CN/server-managed-settings#platform-availability) 列出哪些会话获取它们。

216

197<h2 id="credential-management">217<h2 id="credential-management">

198 凭证管理218 凭证管理

199</h2>219</h2>

auto-mode-config.md +2 −6

Details

281 从 `/permissions` 编辑规则281 从 `/permissions` 编辑规则

282</h2>282</h2>

283 283

284要在不打开设置文件的情况下查看和编辑分类器规则，请运行 [`/permissions`](/docs/zh-CN/permissions#manage-permissions) 并选择 **Auto mode** 选项卡。该选项卡需要 Claude Code v2.1.246 或更高版本，仅当 [auto mode 对您的会话可用](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 时才会显示。284要在不打开设置文件的情况下查看和编辑分类器规则和 `environment` 条目，请运行 [`/permissions`](/docs/zh-CN/permissions#manage-permissions) 并选择 **Auto mode** 选项卡。该选项卡需要 Claude Code v2.1.246 或更高版本，仅当 [auto mode 对您的会话可用](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) 时才会显示。

285 285

286该选项卡列出了来自 [分类器读取的每个作用域](#where-the-classifier-reads-configuration) 的 `allow`、`soft_deny`、`hard_deny` 和 `environment` 条目，并显示内置规则是否对每个部分生效。Claude Code 将来自 [managed settings](/docs/zh-CN/server-managed-settings) 或 `--settings` 标志的条目显示为只读，并将您在该选项卡上所做的每项更改保存到 `~/.claude/settings.json`。从该选项卡中，您可以：286Claude Code 将来自 [managed settings](/docs/zh-CN/server-managed-settings) 或 `--settings` 标志的条目显示为只读，并将您在该选项卡上所做的每项更改保存到 `~/.claude/settings.json`。

~~287~~

288* 在 `allow`、`soft_deny` 和 `hard_deny` 部分中添加、编辑或删除规则。当您向某个部分添加第一条规则时，Claude Code 也会插入 `"$defaults"`，以便 [内置规则](#override-the-block-and-allow-rules) 保持生效。

289* 关闭或重新打开 `allow`、`soft_deny` 或 `hard_deny` 的内置规则。Claude Code 通过在您的列表中为该部分添加或删除 `"$defaults"` 来记录该选择，因此一个部分需要至少有一条您自己的规则，然后才能关闭其内置规则。

290* 在编辑器中将 `environment` 条目编辑为一个文档。如果您还没有配置任何 `environment` 条目，Claude Code 首先会询问是否替换内置环境，然后在完整的内置文本上打开编辑器。保存时，Claude Code 会将您的 `autoMode.environment` 数组替换为该文档。包含 `"$defaults"` 行以 [保留内置条目](#define-trusted-infrastructure)。

291 287

292<h2 id="route-all-shell-commands-through-the-classifier">288<h2 id="route-all-shell-commands-through-the-classifier">

293 通过分类器路由所有 shell 命令289 通过分类器路由所有 shell 命令

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

Details

1387 1387

1388`parentSettingsBehavior: "merge"` 保持 Claude Desktop 向其嵌入式 Claude Code 会话传递出站允许列表的功能；[向 Claude Desktop 会话传递策略](/docs/zh-CN/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions)解释了该机制以及选择加入必须位于的位置。1388`parentSettingsBehavior: "merge"` 保持 Claude Desktop 向其嵌入式 Claude Code 会话传递出站允许列表的功能；[向 Claude Desktop 会话传递策略](/docs/zh-CN/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions)解释了该机制以及选择加入必须位于的位置。

1389 1389

1390为了防止开发者通过云提供商变量或他们自己的 `ANTHROPIC_BASE_URL` 绕过网关，请在同一文件中添加 `"allowedProviders": ["gateway"]`。Claude Code 随后会拒绝机器上未设置为云网关的每个会话，并仅允许网关在它是 `forceLoginGatewayUrl` 命名的网关或文件的 `env` 块将其 URL 设置为 `ANTHROPIC_BASE_URL` 的网关时。`claude gateway` 拒绝在设置该列表的机器上运行，因此请在网关主机上保持该密钥关闭。请参阅设置参考中的 [`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders) 条目。需要 Claude Code v2.1.285 或更高版本。

1391

1390将 `managed-settings.json` 文件部署到每个设备，通常通过你的 MDM 平台。文件路径因平台而异。请参阅[每个机制存储策略的位置](/docs/zh-CN/managed-settings#where-each-mechanism-stores-the-policy)。1392将 `managed-settings.json` 文件部署到每个设备，通常通过你的 MDM 平台。文件路径因平台而异。请参阅[每个机制存储策略的位置](/docs/zh-CN/managed-settings#where-each-mechanism-stores-the-policy)。

1391 1393

1392默认情况下，Windows 上的注册表策略或 macOS 上的托管首选项 plist 会替换 `managed-settings.json` 文件而不是与其合并，除了[上面的例外密钥和跨源检查](#precedence-with-other-managed-sources)。此代码片段中的所有三个密钥都遵循最高优先级源规则，因此通过组策略或配置文件传递策略的团队必须改为将所有三个密钥放在该机制中。1394默认情况下，Windows 上的注册表策略或 macOS 上的托管首选项 plist 会替换 `managed-settings.json` 文件而不是与其合并，除了[上面的例外密钥和跨源检查](#precedence-with-other-managed-sources)。此代码片段中的所有三个密钥都遵循最高优先级源规则，因此通过组策略或配置文件传递策略的团队必须改为将所有三个密钥放在该机制中。

claude-directory.md +1 −0

Details

1562| `image-cache/<session>/` | Claude Code v2.1.274 及更早版本保存的附加图像。更高版本将粘贴和附加的图像保存在 `~/.claude` 之外，在 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars) 控制的临时目录下每个会话的 `images/` 目录中。扫描会删除其他会话在此处留下的目录，无论其年龄如何。 |1562| `image-cache/<session>/` | Claude Code v2.1.274 及更早版本保存的附加图像。更高版本将粘贴和附加的图像保存在 `~/.claude` 之外，在 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars) 控制的临时目录下每个会话的 `images/` 目录中。扫描会删除其他会话在此处留下的目录，无论其年龄如何。 |

1563| `uploads/<session>/` | 您从网络或移动应用附加的文件，以及从移动应用附加的照片，当向 [Remote Control](/docs/zh-CN/remote-control) 会话发送消息时。对 [cloud session](/docs/zh-CN/claude-code-on-the-web) 的附件保存在该会话自己的云环境中，而不是在您的机器上。 |1563| `uploads/<session>/` | 您从网络或移动应用附加的文件，以及从移动应用附加的照片，当向 [Remote Control](/docs/zh-CN/remote-control) 会话发送消息时。对 [cloud session](/docs/zh-CN/claude-code-on-the-web) 的附件保存在该会话自己的云环境中，而不是在您的机器上。 |

1564| `dev-mods/<session>/` | [Claude 在会话期间编写的 Mods](/docs/zh-CN/plugins/mods/create#ask-claude-for-a-mod) |

1566| `shell-snapshots/` | 在启动时捕获的别名、函数和 shell 选项，由 [Bash 工具](/docs/zh-CN/tools-reference#bash-tool-behavior) 应用于每个命令。在正常退出时删除。扫描清理任何在崩溃后留下的内容。 |1567| `shell-snapshots/` | 在启动时捕获的别名、函数和 shell 选项，由 [Bash 工具](/docs/zh-CN/tools-reference#bash-tool-behavior) 应用于每个命令。在正常退出时删除。扫描清理任何在崩溃后留下的内容。 |

cli-reference.md +4 −3

Details

84| `--dangerously-skip-permissions` | 跳过权限提示。等同于 `--permission-mode bypassPermissions`。请参阅[权限模式](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)了解此操作跳过和不跳过的内容。对于使用 `--bg` 启动的会话，当主管重新启动会话时，该模式[持续存在](/docs/zh-CN/agent-view#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` |84| `--dangerously-skip-permissions` | 跳过权限提示。等同于 `--permission-mode bypassPermissions`。请参阅[权限模式](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)了解此操作跳过和不跳过的内容。对于使用 `--bg` 启动的会话，当主管重新启动会话时，该模式[持续存在](/docs/zh-CN/agent-view#permission-mode-model-and-effort) | `claude --dangerously-skip-permissions` |

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

88| `--disallowedTools`, `--disallowed-tools` | 拒绝规则。裸工具名称从 Claude 的上下文中删除匹配的工具：`"Edit"` 删除 Edit，`"*"` 删除每个工具，`"mcp__*"` 删除每个 MCP 工具。作用域规则（如 `Bash(rm *)`）使工具保持可用，仅拒绝[如所写](/docs/zh-CN/permissions#bash-rule-limits)匹配的调用。命名 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 的规则在任何其他工具保持时无法删除它 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |89| `--disallowedTools`, `--disallowed-tools` | 拒绝规则。裸工具名称从 Claude 的上下文中删除匹配的工具：`"Edit"` 删除 Edit，`"*"` 删除每个工具，`"mcp__*"` 删除每个 MCP 工具。作用域规则（如 `Bash(rm *)`）使工具保持可用，仅拒绝[如所写](/docs/zh-CN/permissions#bash-rule-limits)匹配的调用。命名 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 的规则在任何其他工具保持时无法删除它 | `"Bash(git log *)" "Bash(git diff *)" "Edit"` |

89| `--effort` | 为当前会话设置[努力级别](/docs/zh-CN/model-config#adjust-effort-level)。选项：`low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`。可用级别取决于模型。`ultracode` 请求 `xhigh` 努力，[ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode) 打开，需要 Claude Code v2.1.203 或更高版本。覆盖此会话的 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 和 [`effortLevel`](/docs/zh-CN/settings-reference#effortlevel) 设置，不持续 | `claude --effort high` |90| `--effort` | 为当前会话设置[努力级别](/docs/zh-CN/model-config#adjust-effort-level)。选项：`low`、`medium`、`high`、`xhigh`、`max` 或 `ultracode`。可用级别取决于模型。`ultracode` 请求 `xhigh` 努力，[ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode) 打开，需要 Claude Code v2.1.203 或更高版本。覆盖此会话的 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 和 [`effortLevel`](/docs/zh-CN/settings-reference#effortlevel) 设置，不持续 | `claude --effort high` |

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

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

115| `--permission-prompt-tool` | 指定 MCP 工具以在非交互模式下处理权限提示。Claude Code 在运行第一个转之前等待该工具的 MCP 服务器连接，最多 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 启动超时，默认 30 秒。<br /><br />提示工具无法批准标记为[需要用户交互](/docs/zh-CN/mcp#require-approval-for-a-specific-tool)的 MCP 工具：Claude Code 将其 `allow` 结果转换为拒绝。此限制需要 Claude Code v2.1.199 或更高版本 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |116| `--permission-prompt-tool` | 指定 MCP 工具以在非交互模式下处理权限提示。Claude Code 在运行第一个转之前等待该工具的 MCP 服务器连接，最多 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 启动超时，默认 30 秒。<br /><br />提示工具无法批准标记为[需要用户交互](/docs/zh-CN/mcp#require-approval-for-a-specific-tool)的 MCP 工具：Claude Code 将其 `allow` 结果转换为拒绝。此限制需要 Claude Code v2.1.199 或更高版本 | `claude -p --permission-prompt-tool mcp_auth_tool "query"` |

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

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

120| `--prompt-suggestions` | 在生成提示建议的每个转之后发出 `prompt_suggestion` 消息，其中包含预测的下一个用户提示；非常短的对话可能不会产生任何。需要 `--print`、`--output-format stream-json` 和 `--verbose`。请参阅[提示建议](/docs/zh-CN/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |121| `--prompt-suggestions` | 在生成提示建议的每个转之后发出 `prompt_suggestion` 消息，其中包含预测的下一个用户提示；非常短的对话可能不会产生任何。需要 `--print`、`--output-format stream-json` 和 `--verbose`。请参阅[提示建议](/docs/zh-CN/interactive-mode#prompt-suggestions) | `claude -p --prompt-suggestions --output-format stream-json --verbose "query"` |

124| `--remote-control-session-name-prefix <prefix>` | 当未设置显式名称时，[远程控制](/docs/zh-CN/remote-control)自动生成会话名称的前缀。默认为您的机器主机名，生成名称如 `myhost-graceful-unicorn`。设置 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以获得相同效果 | `claude remote-control --remote-control-session-name-prefix dev-box` |125| `--remote-control-session-name-prefix <prefix>` | 当未设置显式名称时，[远程控制](/docs/zh-CN/remote-control)自动生成会话名称的前缀。默认为您的机器主机名，生成名称如 `myhost-graceful-unicorn`。设置 `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` 以获得相同效果 | `claude remote-control --remote-control-session-name-prefix dev-box` |

125| `--replay-user-messages` | 从 stdin 重新发出用户消息回到 stdout 以进行确认。需要 `--input-format stream-json` 和 `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |126| `--replay-user-messages` | 从 stdin 重新发出用户消息回到 stdout 以进行确认。需要 `--input-format stream-json` 和 `--output-format stream-json` | `claude -p --input-format stream-json --output-format stream-json --verbose --replay-user-messages` |

126| `--restricted` | 在受限模式下启动。当评估工具在共享机器上驱动 `claude` 且 Claude Code 不得运行命令或读取该机器的用户和项目设置时使用。Claude Code 删除运行命令或代码的内置工具和 WebFetch，除非您在 `--tools` 中单独命名它们，而不是通过 `default` 预设。它还将内置文件工具限制在[工作目录](/docs/zh-CN/permissions#working-directories)，仅加载[托管设置](/docs/zh-CN/managed-settings)和 `--settings`，拒绝 [`bypassPermissions`](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)，并[拒绝从受限会话创建云会话](/docs/zh-CN/errors#cloud-sessions-cannot-be-created-from-a-restricted-session)。需要 Claude Code v2.1.248 或更高版本 | `claude --restricted -p "query"` |127| `--restricted` | 在受限模式下启动。当评估工具在共享机器上驱动 `claude` 且 Claude Code 不得运行命令或读取该机器的用户和项目设置时使用。Claude Code 删除运行命令或代码的内置工具和 WebFetch，除非您在 `--tools` 中单独命名它们，而不是通过 `default` 预设。它还将内置文件工具限制在[工作目录](/docs/zh-CN/permissions#working-directories)，仅加载[托管设置](/docs/zh-CN/managed-settings)和 `--settings`，拒绝 [`bypassPermissions`](/docs/zh-CN/permission-modes#skip-all-checks-with-bypasspermissions-mode)，并[拒绝从受限会话创建云会话](/docs/zh-CN/errors#cloud-sessions-cannot-be-created-from-a-restricted-session)。需要 Claude Code v2.1.248 或更高版本 | `claude --restricted -p "query"` |

127| `--resume`, `-r` | 按 ID 或名称恢复特定会话，或显示交互式选择器以选择会话。代替 ID，您可以传递会话的 `.jsonl` [记录文件](/docs/zh-CN/sessions#where-transcripts-are-stored)的绝对路径。选择器和名称搜索包括使用 `/add-dir` 添加此目录的会话。当您传递会话 ID 时，Claude Code 搜索当前项目目录及其 git worktrees，然后搜索此机器上的所有其他项目。在 v2.1.223 之前，ID 搜索仅涵盖当前项目目录及其 git worktrees。[后台会话](/docs/zh-CN/agent-view)在选择器中显示，标记为 `bg` | `claude --resume auth-refactor` |128| `--resume`, `-r` | 按 ID 或名称恢复特定会话，或显示交互式选择器以选择会话。代替 ID，您可以传递会话的 `.jsonl` [记录文件](/docs/zh-CN/sessions#where-transcripts-are-stored)的绝对路径。选择器和名称搜索包括使用 `/add-dir` 添加此目录的会话。当您传递会话 ID 时，Claude Code 搜索当前项目目录及其 git worktrees，然后搜索此机器上的所有其他项目。在 v2.1.223 之前，ID 搜索仅涵盖当前项目目录及其 git worktrees。[后台会话](/docs/zh-CN/agent-view)在选择器中显示，标记为 `bg`。恢复仍在运行的[打开该会话](/docs/zh-CN/sessions#resume-a-running-background-session)在此终端中通过 `claude attach`，您在命令行上传递的提示作为其下一个转进行。在 v2.1.285 之前，Claude Code 拒绝并打印 `claude attach` 命令以改为运行 | `claude --resume auth-refactor` |

128| `--safe-mode` | 禁用所有自定义以排除故障的损坏配置：CLAUDE.md、skills、plugins、hooks、MCP 服务器、自定义命令和代理、输出样式、工作流、自定义主题、自定义快捷键、状态行和文件建议命令、LSP 服务器和自动内存不加载。身份验证、模型选择、内置工具和权限正常工作，这与 [`--bare`](/docs/zh-CN/headless#start-faster-with-bare-mode) 不同。托管设置策略仍然适用，包括策略配置的 hooks、状态行和文件建议命令；托管 plugins、托管 skills、托管 CLAUDE.md 和策略配置的 MCP 服务器不适用。用于检查自定义是否触发[自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)。设置 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-CN/env-vars) | `claude --safe-mode` |129| `--safe-mode` | 禁用所有自定义以排除故障的损坏配置：CLAUDE.md、skills、plugins、hooks、MCP 服务器、自定义命令和代理、输出样式、工作流、自定义主题、自定义快捷键、状态行和文件建议命令、LSP 服务器和自动内存不加载。身份验证、模型选择、内置工具和权限正常工作，这与 [`--bare`](/docs/zh-CN/headless#start-faster-with-bare-mode) 不同。托管设置策略仍然适用，包括策略配置的 hooks、状态行和文件建议命令；托管 plugins、托管 skills、托管 CLAUDE.md 和策略配置的 MCP 服务器不适用。用于检查自定义是否触发[自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)。设置 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-CN/env-vars) | `claude --safe-mode` |

130| `--setting-sources` | 要加载的设置源的逗号分隔列表（`user`、`project`、`local`）。请参阅[代理视图](/docs/zh-CN/agent-view#what-carries-over-when-you-background)和[代理团队](/docs/zh-CN/agent-teams#context-and-communication)以了解从此会话启动的会话继承列表 | `claude --setting-sources user,project` |131| `--setting-sources` | 要加载的设置源的逗号分隔列表（`user`、`project`、`local`）。请参阅[代理视图](/docs/zh-CN/agent-view#what-carries-over-when-you-background)和[代理团队](/docs/zh-CN/agent-teams#context-and-communication)以了解从此会话启动的会话继承列表 | `claude --setting-sources user,project` |

cloud-environments.md +1 −1

Details

439 439

440* **Claude 运行的命令**：云环境不设置自己的命令超时，因此 Bash 工具的默认值适用。Claude 默认等待 2 分钟的命令，最多可以要求 10 分钟。440* **Claude 运行的命令**：云环境不设置自己的命令超时，因此 Bash 工具的默认值适用。Claude 默认等待 2 分钟的命令，最多可以要求 10 分钟。

441 441

442 当命令达到其[超时](/docs/zh-CN/tools-reference#timeout-and-output-limits)时，Claude Code [将其移到后台](/docs/zh-CN/tools-reference#background-commands)，而不是停止它，除非命令以 `sleep` 开头。以这种方式移动的命令可以继续运行最多 30 分钟，然后 Claude Code 在其[后台时间限制](/docs/zh-CN/tools-reference#background-commands)处停止它。将 `BASH_DEFAULT_TIMEOUT_MS` 设置为 `1800000` 毫秒以上会延长该限制以及前台默认值。442 当命令达到其[超时](/docs/zh-CN/tools-reference#timeout-and-output-limits)时，Claude Code [将其移到后台](/docs/zh-CN/tools-reference#foreground-commands-that-move-to-the-background)，而不是停止它，除非命令以 `sleep` 开头。以这种方式移动的命令可以继续运行最多 30 分钟，然后 Claude Code 在其[后台时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)处停止它。将 `BASH_DEFAULT_TIMEOUT_MS` 设置为 `1800000` 毫秒以上会延长该限制以及前台默认值。

443* **SessionStart hooks**：Claude Code 在 600 秒后取消 `command` hook，除非您在 hook 条目上设置 [`timeout`](/docs/zh-CN/hooks#common-fields)（以秒为单位）。Claude Code 不会对您使用 [`async: true`](/docs/zh-CN/hooks#run-hooks-in-the-background) 运行的 hook 强制执行超时。443* **SessionStart hooks**：Claude Code 在 600 秒后取消 `command` hook，除非您在 hook 条目上设置 [`timeout`](/docs/zh-CN/hooks#common-fields)（以秒为单位）。Claude Code 不会对您使用 [`async: true`](/docs/zh-CN/hooks#run-hooks-in-the-background) 运行的 hook 强制执行超时。

444* **设置脚本**：花费超过大约五分钟的脚本不会被缓存。[脚本要求](#script-requirements)涵盖如何保持在该时间以下。444* **设置脚本**：花费超过大约五分钟的脚本不会被缓存。[脚本要求](#script-requirements)涵盖如何保持在该时间以下。

445* **空闲会话**：会话在一段时间不活动后停止，其 VM 被回收。[设置环境变量](#set-environment-variables)描述会话在每种情况下会获取什么，[环境已过期](/docs/zh-CN/claude-code-on-the-web#environment-expired)涵盖如何重新打开 VM 被回收的会话。445* **空闲会话**：会话在一段时间不活动后停止，其 VM 被回收。[设置环境变量](#set-environment-variables)描述会话在每种情况下会获取什么，[环境已过期](/docs/zh-CN/claude-code-on-the-web#environment-expired)涵盖如何重新打开 VM 被回收的会话。

commands.md +1 −1

Details

132| `/remote-control` | 使此会话可从 claude.ai 进行 [Remote Control](/docs/zh-CN/remote-control)。在未登录时运行它会打印 Remote Control 需要 claude.ai 订阅并告诉你如何登录；在 v2.1.206 之前它报告 `Unknown command: /remote-control`。别名：`/rc` |132| `/remote-control` | 使此会话可从 claude.ai 进行 [Remote Control](/docs/zh-CN/remote-control)。在未登录时运行它会打印 Remote Control 需要 claude.ai 订阅并告诉你如何登录；在 v2.1.206 之前它报告 `Unknown command: /remote-control`。别名：`/rc` |

133| `/remote-env` | 为你从 CLI 启动的 cloud sessions 选择默认[云环境](/docs/zh-CN/cloud-environments#select-an-environment-from-the-cli) |133| `/remote-env` | 为你从 CLI 启动的 cloud sessions 选择默认[云环境](/docs/zh-CN/cloud-environments#select-an-environment-from-the-cli) |

134| `/rename [name]` | 重命名当前会话并在提示栏上显示名称。没有名称，从对话历史自动生成一个。也可在非交互模式 (`-p`) 中使用；需要 Claude Code v2.1.205 或更高版本。从每个重命名表面，包括 claude.ai 和桌面应用，Claude Code 用空格替换新名称中的控制和不可见字符，并将名称限制在 200 个字符。如果名称在移除不可见字符后为空，Claude Code 拒绝它并显示 `That name is empty once invisible characters are removed. Usage: /rename <name>`。字符替换和长度限制需要 Claude Code v2.1.221 或更高版本。如果这台机器上的另一个活跃会话已经使用你传递的名称，Claude Code 应用[它的变体](/docs/zh-CN/sessions#name-your-sessions) |134| `/rename [name]` | 重命名当前会话并在提示栏上显示名称。没有名称，从对话历史自动生成一个。也可在非交互模式 (`-p`) 中使用；需要 Claude Code v2.1.205 或更高版本。从每个重命名表面，包括 claude.ai 和桌面应用，Claude Code 用空格替换新名称中的控制和不可见字符，并将名称限制在 200 个字符。如果名称在移除不可见字符后为空，Claude Code 拒绝它并显示 `That name is empty once invisible characters are removed. Usage: /rename <name>`。字符替换和长度限制需要 Claude Code v2.1.221 或更高版本。如果这台机器上的另一个活跃会话已经使用你传递的名称，Claude Code 应用[它的变体](/docs/zh-CN/sessions#name-your-sessions) |

135| `/resume [session]` | 按 ID 或名称恢复对话，或打开会话选择器。[后台会话](/docs/zh-CN/agent-view)在选择器中标记为 `bg` 出现；仍在运行的会话无法在此处恢复，所以从 `claude agents` 附加到它或先在那里停止它。别名：`/continue` |135| `/resume [session]` | 按 ID 或名称恢复对话，或打开会话选择器。[后台会话](/docs/zh-CN/agent-view)在选择器中标记为 `bg` 出现。恢复仍在运行的会话，从选择器或按 ID 或名称，[打开该会话](/docs/zh-CN/sessions#resume-a-running-background-session)：你的当前对话移到后台，此终端附加到运行的会话。在空提示符上按 `←` 返回代理视图，它也列出你离开的对话。在 v2.1.285 之前，Claude Code 拒绝并告诉你使用 `claude attach` 打开会话或先停止它。别名：`/continue` |

136| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [pr#\|branch\|path]` | [`/code-review`](/docs/zh-CN/code-review#review-a-diff-locally) 的别名：审查当前差异，或你传递的 PR 号、分支或路径，例如 `/review 1234`，并采用相同的工作量级别和标志。没有给定级别时，审查重用你输入的最后一个 `low` 到 `max` 级别；有关确切规则，请参阅[本地审查差异](/docs/zh-CN/code-review#review-a-diff-locally)。对于深度云审查，使用 [`/code-review ultra`](/docs/zh-CN/ultrareview)。在 v2.1.223 之前，`/review` 是一个单独的命令，运行 GitHub 拉取请求号的单遍、只读审查，在运行不带参数时列出打开的 PR 以选择；从 v2.1.186 到 v2.1.201，它运行与 `/code-review medium` 相同的多代理引擎 |136| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [pr#\|branch\|path]` | [`/code-review`](/docs/zh-CN/code-review#review-a-diff-locally) 的别名：审查当前差异，或你传递的 PR 号、分支或路径，例如 `/review 1234`，并采用相同的工作量级别和标志。没有给定级别时，审查重用你输入的最后一个 `low` 到 `max` 级别；有关确切规则，请参阅[本地审查差异](/docs/zh-CN/code-review#review-a-diff-locally)。对于深度云审查，使用 [`/code-review ultra`](/docs/zh-CN/ultrareview)。在 v2.1.223 之前，`/review` 是一个单独的命令，运行 GitHub 拉取请求号的单遍、只读审查，在运行不带参数时列出打开的 PR 以选择；从 v2.1.186 到 v2.1.201，它运行与 `/code-review medium` 相同的多代理引擎 |

138| `/run` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 启动并驱动你的项目应用以查看更改工作，而不仅仅是通过测试。请参阅[运行和验证你的应用](/docs/zh-CN/skills#run-and-verify-your-app) |138| `/run` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 启动并驱动你的项目应用以查看更改工作，而不仅仅是通过测试。请参阅[运行和验证你的应用](/docs/zh-CN/skills#run-and-verify-your-app) |

context-window.md +1 −1

Details

1634 1634

1635如果您需要更大的窗口而不是更小的对话，Fable 模型、Sonnet 5 及更高版本、Opus 4.6 及更高版本以及 Sonnet 4.6 支持 100 万令牌的上下文窗口。有关按计划的可用性以及如何选择 `[1m]` 模型变体，请参阅[扩展上下文](/docs/zh-CN/model-config#extended-context)。压缩在更大的限制下以相同的方式工作。1635如果您需要更大的窗口而不是更小的对话，Fable 模型、Sonnet 5 及更高版本、Opus 4.6 及更高版本以及 Sonnet 4.6 支持 100 万令牌的上下文窗口。有关按计划的可用性以及如何选择 `[1m]` 模型变体，请参阅[扩展上下文](/docs/zh-CN/model-config#extended-context)。压缩在更大的限制下以相同的方式工作。

1636 1636

1637Sonnet 5.5 和 Sonnet 5 以 1M 上下文窗口运行，没有 `[1m]` 变体可选择。有关其自动压缩阈值和 LLM 网关异常，请参阅[Sonnet 5.5 和 Sonnet 5 上下文窗口](/docs/zh-CN/model-config#sonnet-5-5-and-sonnet-5-context-window)。1637Sonnet 5.5 和 Sonnet 5 以 1M 上下文窗口运行，没有 `[1m]` 变体可选择。有关其自动压缩阈值，请参阅[Sonnet 5.5 和 Sonnet 5 上下文窗口](/docs/zh-CN/model-config#sonnet-5-5-and-sonnet-5-context-window)，以及[网关后面的上下文窗口](/docs/zh-CN/model-config#context-window-behind-a-gateway)，了解当您将 `ANTHROPIC_BASE_URL` 设置为 [LLM 网关](/docs/zh-CN/llm-gateway)时 Claude Code 如何调整窗口大小。

1638 1638

1639自动压缩运行的位置取决于您的模型和配置。有关每个模型的边界，请参阅[默认自动压缩阈值](/docs/zh-CN/model-config#default-auto-compact-thresholds)，如果 Claude Code 为您的模型 ID（例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名）假设了错误的窗口，请参阅[更正网关或自定义模型 ID 的窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。1639自动压缩运行的位置取决于您的模型和配置。有关每个模型的边界，请参阅[默认自动压缩阈值](/docs/zh-CN/model-config#default-auto-compact-thresholds)，如果 Claude Code 为您的模型 ID（例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名）假设了错误的窗口，请参阅[更正网关或自定义模型 ID 的窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。

1640 1640

costs.md +1 −1

Details

51 51

52该行中的未命中、预期重建以及热或冷部分的含义如下：52该行中的未命中、预期重建以及热或冷部分的含义如下：

53 53

54* **Misses（未命中）**：重新处理缓存已保存内容的请求，包括最后一次未命中的时间以及这些请求写回缓存的令牌数。当请求重新处理了超过 5% 且至少 2,000 个令牌的内容时，Claude Code 会将请求计为未命中，这些内容本可以从缓存中读取。[使缓存失效的操作](/docs/zh-CN/prompt-caching#actions-that-invalidate-the-cache)列出了常见原因。当 Claude Code 能够识别最后一次未命中的可能原因时，该行也会命名它，例如 `likely cause: tool definitions changed`。可能原因文本需要 Claude Code v2.1.260 或更高版本。54* **Misses（未命中）**：重新处理缓存已保存内容的请求，包括最后一次未命中的时间以及这些请求写回缓存的令牌数。[使缓存失效的操作](/docs/zh-CN/prompt-caching#actions-that-invalidate-the-cache)列出了常见原因。当 Claude Code 能够识别最后一次未命中的可能原因时，该行也会命名它，例如 `likely cause: tool definitions changed`。可能原因文本需要 Claude Code v2.1.260 或更高版本。

55* **Expected rebuilds（预期重建）**：当 Claude Code 本身刚刚重写对话时，通过[压缩](/docs/zh-CN/prompt-caching#compacting-the-conversation)或从上下文中清除旧工具结果，它会将相同类型的未命中计为预期重建。此部分仅在至少发生过一次预期重建后出现。55* **Expected rebuilds（预期重建）**：当 Claude Code 本身刚刚重写对话时，通过[压缩](/docs/zh-CN/prompt-caching#compacting-the-conversation)或从上下文中清除旧工具结果，它会将相同类型的未命中计为预期重建。此部分仅在至少发生过一次预期重建后出现。

56* **Warm or cold（热或冷）**：缓存的前缀是否仍在其[缓存生命周期](/docs/zh-CN/prompt-caching#cache-lifetime)内，以及生效的 TTL。当缓存冷时，该行显示会话已空闲多长时间。当没有响应报告缓存令牌时，该行以 `no prompt caching reported by the API` 结尾。56* **Warm or cold（热或冷）**：缓存的前缀是否仍在其[缓存生命周期](/docs/zh-CN/prompt-caching#cache-lifetime)内，以及生效的 TTL。当缓存冷时，该行显示会话已空闲多长时间。当没有响应报告缓存令牌时，该行以 `no prompt caching reported by the API` 结尾。

57 57

desktop.md +8 −0

Details

967 967

968要将 CLI 会话移动到 Desktop，在终端中运行 `/desktop`。Claude 保存你的会话并在桌面应用中打开它，然后退出 CLI。此命令在 macOS 和 x64 Windows 上可用，当你使用 Claude 订阅登录时。它不适用于 API 密钥身份验证或 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。968要将 CLI 会话移动到 Desktop，在终端中运行 `/desktop`。Claude 保存你的会话并在桌面应用中打开它，然后退出 CLI。此命令在 macOS 和 x64 Windows 上可用，当你使用 Claude 订阅登录时。它不适用于 API 密钥身份验证或 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry。

969 969

970从你的 shell，[`claude --desktop`](/docs/zh-CN/cli-reference#cli-flags) 直接打开 Desktop，无需启动终端会话。它需要 Claude Code v2.1.285 或更高版本，并具有与 `/desktop` 相同的平台和登录要求。没有其他参数时，它在当前目录中打开 Desktop。要在 Desktop 中打开现有的 CLI 会话，添加 `--continue` 以获取此目录中最近的对话，或使用 `--resume` 和 `/status` 显示的会话 ID：

971

972```bash theme={null}

973claude --desktop --resume <session-id>

974```

975

976Claude Code 打印 `Opening session <session-id> in Claude Desktop`，会话在应用中打开，命令退出。会话名称不能代替 ID。Claude Code 不会移动在另一个终端中打开或仍在后台运行的会话。如果未安装 Claude Desktop，命令会打印下载链接并退出。

977

970你也可以从 Desktop 内部使用 `/resume` 选择 CLI 会话。此命令在本地会话中可用，不在 SSH、WSL 或云会话中可用。978你也可以从 Desktop 内部使用 `/resume` 选择 CLI 会话。此命令在本地会话中可用，不在 SSH、WSL 或云会话中可用。

971 979

972要在 Desktop 中继续终端会话：980要在 Desktop 中继续终端会话：

desktop-linux.md +12 −0

Details

163 163

164如果 `claude-desktop` 以此消息退出，说明您以 root 身份启动了它。以普通用户身份登录并从那里启动它。164如果 `claude-desktop` 以此消息退出，说明您以 root 身份启动了它。以普通用户身份登录并从那里启动它。

165 165

166<h3 id="your-sign-in-won’t-be-saved-on-this-device">

167 您的登录信息不会在此设备上保存

168</h3>

169

170Claude Desktop 将您的登录信息保存在您桌面的密钥环中，例如 GNOME Keyring 或 KDE Wallet。如果它无法访问已解锁的密钥环，您的登录信息不会被保存，每次启动应用时您都需要重新登录。选择与您的系统相匹配的情况：

171

172* **未安装密钥环，在 KDE Plasma 以外的桌面上**：如果您使用 `--no-install-recommends` 安装，或在跳过推荐软件包的最小镜像上，apt 没有安装密钥环。使用 `sudo apt install gnome-keyring` 安装 GNOME Keyring。

173* **KDE Plasma 同时安装了 GNOME Keyring**：KDE Wallet 随 Plasma 桌面一起提供。这两个密钥环会冲突，Claude Desktop 可能会显示此通知，即使 KDE Wallet 正常工作。使用 `sudo apt remove gnome-keyring` 删除额外的密钥环，然后重新启动您的计算机。

174* **密钥环已安装但被锁定**：解锁它。

175

176修复后，重新启动应用并登录。然后退出并再次启动它以确认应用打开时您仍然已登录。

177

166<h3 id="cowork-isn’t-available">178<h3 id="cowork-isn’t-available">

167 Cowork 不可用179 Cowork 不可用

168</h3>180</h3>

env-vars.md +8 −6

Details

56 </Tab>56 </Tab>

57</Tabs>57</Tabs>

58 58

~~59赋值行在成功时不会打印任何内容，因此在运行 `claude` 之前，通过在同一 shell 中打印变量来确认它已设置：~~59赋值行在成功时不会打印任何内容。要确认变量已设置，请在同一 shell 中打印它：

60 60

61<Tabs>61<Tabs>

62 <Tab title="macOS, Linux, WSL">62 <Tab title="macOS, Linux, WSL">

127数值变量（如超时、令牌预算和重试次数）除了接受纯数字外，还接受科学记数法和数字分隔符拼写，除非变量的行注明仅接受纯数字。例如，Claude Code 将 `2e3` 读作 2000，将 `64_000` 读作 64000。在 v2.1.211 之前，这些拼写可能会无声地设置一个更小的值，例如 `1e6` 将超时设置为 1。127数值变量（如超时、令牌预算和重试次数）除了接受纯数字外，还接受科学记数法和数字分隔符拼写，除非变量的行注明仅接受纯数字。例如，Claude Code 将 `2e3` 读作 2000，将 `64_000` 读作 64000。在 v2.1.211 之前，这些拼写可能会无声地设置一个更小的值，例如 `1e6` 将超时设置为 1。

128 128

129<Note>129<Note>

130 对于打开或关闭行为的变量，设置 `1` 或 `true` 以打开，设置 `0` 或 `false` 以关闭，不区分大小写。130 对于打开或关闭行为的变量，设置 `1`、`true`、`yes` 或 `on` 以打开，设置 `0`、`false`、`no` 或 `off` 以关闭，不区分大小写。

131 131

132 某些变量仅读取您是否设置了它们，因此任何非空值（包括 `0`）都会打开该行为，而通过取消设置变量或将其设置为空值来关闭该行为。这些变量的工作方式如下：132 某些变量仅读取您是否设置了它们，因此任何非空值（包括 `0`）都会打开该行为，而通过取消设置变量或将其设置为空值来关闭该行为。这些变量的工作方式如下：

133 133

192| `API_FORCE_IDLE_TIMEOUT` | 覆盖 5 分钟的正文空闲超时，当没有字节到达时中止流式模型响应。设置为 `0` 以关闭超时，例如当缓慢的 [网关](/docs/zh-CN/llm-gateway) 或本地模型在块之间暂停超过 5 分钟时，或 `1` 以为每个提供商保持打开。未设置时，超时在除直接 Anthropic API、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和设置了 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` 的 Amazon Bedrock 之外的提供商上处于活跃状态。[流监视程序](/docs/zh-CN/network-config#streaming-idle-watchdogs) 独立运行，即使您在此处设置 `0`，也会中止长时间的无声暂停 |192| `API_FORCE_IDLE_TIMEOUT` | 覆盖 5 分钟的正文空闲超时，当没有字节到达时中止流式模型响应。设置为 `0` 以关闭超时，例如当缓慢的 [网关](/docs/zh-CN/llm-gateway) 或本地模型在块之间暂停超过 5 分钟时，或 `1` 以为每个提供商保持打开。未设置时，超时在除直接 Anthropic API、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和设置了 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1` 的 Amazon Bedrock 之外的提供商上处于活跃状态。[流监视程序](/docs/zh-CN/network-config#streaming-idle-watchdogs) 独立运行，即使您在此处设置 `0`，也会中止长时间的无声暂停 |

193| `API_TIMEOUT_MS` | API 请求的超时时间（毫秒）（默认值：600000，或 10 分钟；最大值：2147483647）。在缓慢网络上请求超时或通过代理路由时增加此值。超过最大值的值会导致底层计时器溢出，导致请求立即失败 |193| `API_TIMEOUT_MS` | API 请求的超时时间（毫秒）（默认值：600000，或 10 分钟；最大值：2147483647）。在缓慢网络上请求超时或通过代理路由时增加此值。超过最大值的值会导致底层计时器溢出，导致请求立即失败 |

194| `AWS_BEARER_TOKEN_BEDROCK` | Amazon Bedrock API 密钥用于身份验证（参见 [Amazon Bedrock API 密钥](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |194| `AWS_BEARER_TOKEN_BEDROCK` | Amazon Bedrock API 密钥用于身份验证（参见 [Amazon Bedrock API 密钥](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |

195| `BASH_DEFAULT_TIMEOUT_MS` | 前台 Bash 或 PowerShell 工具命令的默认超时时间（毫秒）（默认值：120000，或 2 分钟）。超过 30 分钟的默认值也成为后台命令的默认 [时间限制](/docs/zh-CN/tools-reference#background-commands)。后台时间限制需要 Claude Code v2.1.285 或更高版本 |195| `BASH_DEFAULT_TIMEOUT_MS` | 前台 Bash 或 PowerShell 工具命令的默认超时时间（毫秒）（默认值：120000，或 2 分钟）。超过 30 分钟的默认值也成为后台命令的默认 [时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)。后台时间限制需要 Claude Code v2.1.285 或更高版本 |

196| `BASH_MAX_OUTPUT_LENGTH` | Claude Code 读回到命令结果中的 bash 输出的最大字符数（默认值：30000；最大值：150000）。如果您设置了 [`bashOutputMaxChars`](/docs/zh-CN/settings-reference#bashoutputmaxchars) 设置，Claude Code 会忽略此变量。参见 [输出限制](/docs/zh-CN/tools-reference#output-limits) |196| `BASH_MAX_OUTPUT_LENGTH` | Claude Code 读回到命令结果中的 bash 输出的最大字符数（默认值：30000；最大值：150000）。如果您设置了 [`bashOutputMaxChars`](/docs/zh-CN/settings-reference#bashoutputmaxchars) 设置，Claude Code 会忽略此变量。参见 [输出限制](/docs/zh-CN/tools-reference#output-limits) |

197| `BASH_MAX_TIMEOUT_MS` | 模型可以为前台 Bash 或 PowerShell 工具命令设置的最大超时时间（毫秒）（默认值：600000，或 10 分钟）。有效的上限是此值和 `BASH_DEFAULT_TIMEOUT_MS` 中的较大者。超过 2 小时的有效上限也成为后台命令的最大 [时间限制](/docs/zh-CN/tools-reference#background-commands)。后台时间限制需要 Claude Code v2.1.285 或更高版本 |197| `BASH_MAX_TIMEOUT_MS` | 模型可以为前台 Bash 或 PowerShell 工具命令设置的最大超时时间（毫秒）（默认值：600000，或 10 分钟）。有效的上限是此值和 `BASH_DEFAULT_TIMEOUT_MS` 中的较大者。超过 2 小时的有效上限也成为后台命令的最大 [时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)。后台时间限制需要 Claude Code v2.1.285 或更高版本 |

198| `BETA_TRACING_ENDPOINT` | [详细测试版跟踪](/docs/zh-CN/monitoring-usage#traces-beta) 的 OTLP 端点：使用 `ENABLE_BETA_TRACING_DETAILED=1`，日志和跟踪转到那里而不是配置的导出器。在您的 shell、用户设置或托管设置中设置它。在 [项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env) 中被忽略 |198| `BETA_TRACING_ENDPOINT` | [详细测试版跟踪](/docs/zh-CN/monitoring-usage#traces-beta) 的 OTLP 端点：使用 `ENABLE_BETA_TRACING_DETAILED=1`，日志和跟踪转到那里而不是配置的导出器。在您的 shell、用户设置或托管设置中设置它。在 [项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env) 中被忽略 |

199| `CCR_FORCE_BUNDLE` | 设置为 `1` 以强制 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) 捆绑并上传您的本地存储库，而不是从其远程克隆 |199| `CCR_FORCE_BUNDLE` | 设置为 `1` 以强制 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github) 捆绑并上传您的本地存储库，而不是从其远程克隆 |

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

263| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 设置为 `1` 以禁用文件 [checkpointing](/docs/zh-CN/checkpointing)。`/rewind` 命令将无法恢复代码更改。覆盖 [`fileCheckpointingEnabled`](/docs/zh-CN/settings-reference#filecheckpointingenabled) 设置 |263| `CLAUDE_CODE_DISABLE_FILE_CHECKPOINTING` | 设置为 `1` 以禁用文件 [checkpointing](/docs/zh-CN/checkpointing)。`/rewind` 命令将无法恢复代码更改。覆盖 [`fileCheckpointingEnabled`](/docs/zh-CN/settings-reference#filecheckpointingenabled) 设置 |

264| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 设置为 `1` 以删除内置提交和 PR 工作流说明以及 Claude 上下文中的 git 状态快照。在使用您自己的 git 工作流 skills 时很有用。当设置时优先于 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions) 设置 |264| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 设置为 `1` 以删除内置提交和 PR 工作流说明以及 Claude 上下文中的 git 状态快照。在使用您自己的 git 工作流 skills 时很有用。当设置时优先于 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions) 设置 |

265| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 设置为 `1` 以防止在 Anthropic API 上自动将 Opus 4.0 和 4.1 重新映射到当前 Opus 版本。在您想有意固定较旧模型时使用。重新映射不在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上运行 |265| `CLAUDE_CODE_DISABLE_LEGACY_MODEL_REMAP` | 设置为 `1` 以防止在 Anthropic API 上自动将 Opus 4.0 和 4.1 重新映射到当前 Opus 版本。在您想有意固定较旧模型时使用。重新映射不在 Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry 上运行 |

266| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | 设置为 `1` 以停止 Claude Code 在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock#when-a-model-is-disabled-mid-session) 和 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai#when-a-model-is-disabled-mid-session) 上在您的帐户在会话中途失去对会话模型的访问权限时切换到较旧的模型；拒绝的请求立即失败。您配置的 [回退模型链](/docs/zh-CN/model-config#fallback-model-chains) 仍在该拒绝时切换，[启动模型检查](/docs/zh-CN/amazon-bedrock#startup-model-checks) 仍在启动时回退。需要 Claude Code v2.1.285 或更高版本 |

266| `CLAUDE_CODE_DISABLE_MOUSE` | 设置为 `1` 以在 [全屏呈现](/docs/zh-CN/fullscreen) 中禁用鼠标跟踪。使用 `PgUp` 和 `PgDn` 的键盘滚动仍然有效。使用此选项保持您终端的本机选择复制行为 |267| `CLAUDE_CODE_DISABLE_MOUSE` | 设置为 `1` 以在 [全屏呈现](/docs/zh-CN/fullscreen) 中禁用鼠标跟踪。使用 `PgUp` 和 `PgDn` 的键盘滚动仍然有效。使用此选项保持您终端的本机选择复制行为 |

267| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 设置为 `1` 以在 [全屏呈现](/docs/zh-CN/fullscreen) 中禁用点击、拖动和悬停处理，同时保持鼠标滚轮滚动。当您希望滚轮滚动在 Claude Code 内工作但不希望点击定位光标、展开工具输出或打开链接时使用此选项。当两者都设置时，`CLAUDE_CODE_DISABLE_MOUSE` 优先。需要 Claude Code v2.1.195 或更高版本 |268| `CLAUDE_CODE_DISABLE_MOUSE_CLICKS` | 设置为 `1` 以在 [全屏呈现](/docs/zh-CN/fullscreen) 中禁用点击、拖动和悬停处理，同时保持鼠标滚轮滚动。当您希望滚轮滚动在 Claude Code 内工作但不希望点击定位光标、展开工具输出或打开链接时使用此选项。当两者都设置时，`CLAUDE_CODE_DISABLE_MOUSE` 优先。需要 Claude Code v2.1.195 或更高版本 |

268| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | 设置为 `1` 以停止 Claude Code 在 API 请求因连接级错误（如连接重置或 TLS 握手错误）失败时重新读取 [mTLS 客户端证书和密钥](/docs/zh-CN/network-config#mtls-authentication)。禁用重新加载后，Claude Code 仅在下次应用设置或下次启动时加载轮换的文件。需要 Claude Code v2.1.232 或更高版本 |269| `CLAUDE_CODE_DISABLE_MTLS_RELOAD_ON_STALE_CONNECTION` | 设置为 `1` 以停止 Claude Code 在 API 请求因连接级错误（如连接重置或 TLS 握手错误）失败时重新读取 [mTLS 客户端证书和密钥](/docs/zh-CN/network-config#mtls-authentication)。禁用重新加载后，Claude Code 仅在下次应用设置或下次启动时加载轮换的文件。需要 Claude Code v2.1.232 或更高版本 |

352| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 设置为 `1` 以停止 Claude Code 在为工具调用、hooks 和状态行命令生成 PowerShell 时传递 `-ExecutionPolicy Bypass`，并改为尊重机器的有效执行策略。默认情况下，Claude Code 在进程范围内绕过执行策略，以便 `.ps1` 脚本和模块导入在默认受限的 Windows 安装上工作。进程范围绕过无论此设置如何都永远不会覆盖 Group Policy `MachinePolicy` 或 `UserPolicy` |353| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 设置为 `1` 以停止 Claude Code 在为工具调用、hooks 和状态行命令生成 PowerShell 时传递 `-ExecutionPolicy Bypass`，并改为尊重机器的有效执行策略。默认情况下，Claude Code 在进程范围内绕过执行策略，以便 `.ps1` 脚本和模块导入在默认受限的 Windows 安装上工作。进程范围绕过无论此设置如何都永远不会覆盖 Group Policy `MachinePolicy` 或 `UserPolicy` |

353| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在 [非交互模式](/docs/zh-CN/headless#background-tasks-at-exit) 中使用 `-p` 标志后，在最后一个转向后等待后台子代理和工作流的空闲等待的上限（毫秒）。每次 Claude 采取转向处理后台结果时，空闲等待重新开始。默认值：`600000`，或 10 分钟。当空闲等待达到上限时，Claude Code 停止等待剩余的后台任务并退出。设置为 `0` 以无限期等待。此上限与适用于纯后台 shell 的五秒宽限期分开。需要 Claude Code v2.1.182 或更高版本 |354| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在 [非交互模式](/docs/zh-CN/headless#background-tasks-at-exit) 中使用 `-p` 标志后，在最后一个转向后等待后台子代理和工作流的空闲等待的上限（毫秒）。每次 Claude 采取转向处理后台结果时，空闲等待重新开始。默认值：`600000`，或 10 分钟。当空闲等待达到上限时，Claude Code 停止等待剩余的后台任务并退出。设置为 `0` 以无限期等待。此上限与适用于纯后台 shell 的五秒宽限期分开。需要 Claude Code v2.1.182 或更高版本 |

354| `CLAUDE_CODE_PROCESS_WRAPPER` | 通过给定为 argv 前缀（如 `/opt/corp/launcher`）的企业启动器启动 Claude Code 从其自己的二进制文件启动的进程，例如托管 [代理视图](/docs/zh-CN/agent-view) 会话的后台服务。在用户或 [托管设置](/docs/zh-CN/managed-settings) 的 `env` 块中设置它，而不是作为 shell 导出，以便分离的后台服务继承它；项目和本地设置无法设置它。等同于 [`processWrapper` 设置](/docs/zh-CN/settings-reference#processwrapper)，需要 Claude Code v2.1.210 或更高版本；当两者都设置时，此变量优先。VS Code 扩展通过其 `claudeProcessWrapper` 设置单独配置其自己的启动器。在 Windows 上被忽略。参见 [在企业启动器后面运行 Claude Code](/docs/zh-CN/corporate-launcher) 了解值格式、启动器涵盖的内容以及启动器必须满足的合同。需要 Claude Code v2.1.208 或更高版本 |355| `CLAUDE_CODE_PROCESS_WRAPPER` | 通过给定为 argv 前缀（如 `/opt/corp/launcher`）的企业启动器启动 Claude Code 从其自己的二进制文件启动的进程，例如托管 [代理视图](/docs/zh-CN/agent-view) 会话的后台服务。在用户或 [托管设置](/docs/zh-CN/managed-settings) 的 `env` 块中设置它，而不是作为 shell 导出，以便分离的后台服务继承它；项目和本地设置无法设置它。等同于 [`processWrapper` 设置](/docs/zh-CN/settings-reference#processwrapper)，需要 Claude Code v2.1.210 或更高版本；当两者都设置时，此变量优先。VS Code 扩展通过其 `claudeProcessWrapper` 设置单独配置其自己的启动器。在 Windows 上被忽略。参见 [在企业启动器后面运行 Claude Code](/docs/zh-CN/corporate-launcher) 了解值格式、启动器涵盖的内容以及启动器必须满足的合同。需要 Claude Code v2.1.208 或更高版本 |

355| `CLAUDE_CODE_PROJECT_DIR_NAME` | 与 `CLAUDE_CONFIG_DIR` 一起设置以选择 `projects/` 目录名称 Claude Code 在其下存储该会话的成绩单和自动内存，代替从工作目录路径派生的名称。例如，使用 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 启动 Claude Code 在 `/srv/tenant-a/projects/work/` 下存储它们。当 `CLAUDE_CONFIG_DIR` 未设置时，Claude Code 忽略此变量，并仅从启动 `claude` 的环境读取它，从不从 [设置文件 `env` 块](#in-settings-files)。参见 [自己命名项目目录](/docs/zh-CN/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更高版本 |356| `CLAUDE_CODE_PROJECT_DIR_NAME` | 与 `CLAUDE_CONFIG_DIR` 一起设置以选择 `projects/` 目录名称 Claude Code 在其下存储该会话的成绩单和自动内存，代替从工作目录路径派生的名称。例如，使用 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 启动 Claude Code 在 `/srv/tenant-a/projects/work/` 下存储它们。当 `CLAUDE_CONFIG_DIR` 未设置时，Claude Code 忽略此变量，并读取它仅从启动 `claude` 的环境，从不从 [设置文件 `env` 块](#in-settings-files)。参见 [自己命名项目目录](/docs/zh-CN/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更高版本 |

356| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 设置 `5m` 或 `1h`，Claude Code 接受的唯一值，以选择主对话的 [提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime)：您的交互式、`-p` 和 SDK 转向，加上与它们内联运行的帮助程序。优先于 `promptCacheTtl` 设置和 `ENABLE_PROMPT_CACHING_1H`，`FORCE_PROMPT_CACHING_5M` 覆盖它。API 以更高的速率计费 1 小时缓存写入。需要 Claude Code v2.1.242 或更高版本 |357| `CLAUDE_CODE_PROMPT_CACHE_TTL` | 设置 `5m` 或 `1h`，Claude Code 接受的唯一值，以选择主对话的 [提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime)：您的交互式、`-p` 和 SDK 转向，加上与它们内联运行的帮助程序。优先于 `promptCacheTtl` 设置和 `ENABLE_PROMPT_CACHING_1H`，`FORCE_PROMPT_CACHING_5M` 覆盖它。API 以更高的速率计费 1 小时缓存写入。需要 Claude Code v2.1.242 或更高版本 |

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

358| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 并代表其管理模型提供商路由的主机平台设置。设置时，Claude Code 在设置文件中忽略提供商选择、端点和身份验证变量（如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`），因此用户设置无法覆盖主机的路由。Claude Code 也忽略 [托管设置](/docs/zh-CN/managed-settings) 中的模型选择密钥（如 `model`、`fallbackModel` 和 `modelOverrides`），无论哪个托管源传递它们，因此主机的模型配置优先于过期的托管模型固定。Claude Code 也忽略托管 `env` 块中的模型选择变量（如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列）；托管设置中的 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 允许列表仍然适用，除非主机提供其自己的。Claude Code 也跳过它在第三方提供商（如 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 和 Microsoft Foundry）上否则应用的自动遥测选择退出，因此遥测遵循标准 `DISABLE_TELEMETRY` 选择退出。参见 [按 API 提供商的默认行为](/docs/zh-CN/data-usage#default-behaviors-by-api-provider) |359| `CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST` | 由嵌入 Claude Code 并代表其管理模型提供商路由的主机平台设置。设置时，Claude Code 在设置文件中忽略提供商选择、端点和身份验证变量（如 `CLAUDE_CODE_USE_BEDROCK`、`ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`），因此用户设置无法覆盖主机的路由。Claude Code 也忽略 [托管设置](/docs/zh-CN/managed-settings) 中的模型选择密钥（如 `model`、`fallbackModel` 和 `modelOverrides`），无论哪个托管源传递它们，因此主机的模型配置优先于过期的托管模型固定。Claude Code 也忽略托管 `env` 块中的模型选择变量（如 `ANTHROPIC_MODEL` 和 `ANTHROPIC_DEFAULT_*_MODEL` 系列）；托管设置中的 [`availableModels`](/docs/zh-CN/settings-reference#availablemodels) 允许列表仍然适用，除非主机提供其自己的。Claude Code 也跳过它在第三方提供商（如 Amazon Bedrock、Claude Platform on AWS、Google Cloud's Agent Platform 和 Microsoft Foundry）上否则应用的自动遥测选择退出，因此遥测遵循标准 `DISABLE_TELEMETRY` 选择退出。参见 [按 API 提供商的默认行为](/docs/zh-CN/data-usage#default-behaviors-by-api-provider) |

360| `CLAUDE_CODE_REMOTE` | 当 Claude Code 作为 [云会话](/docs/zh-CN/claude-code-on-the-web) 运行时自动设置为 `true`。从 hook 或设置脚本读取此项以检测您是否在云会话中 |361| `CLAUDE_CODE_REMOTE` | 当 Claude Code 作为 [云会话](/docs/zh-CN/claude-code-on-the-web) 运行时自动设置为 `true`。从 hook 或设置脚本读取此项以检测您是否在云会话中 |

361| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在 [云会话](/docs/zh-CN/claude-code-on-the-web) 中自动设置为当前会话的 ID。读取此项以构造回到会话成绩单的链接。参见 [将输出链接回会话](/docs/zh-CN/cloud-environments#link-output-back-to-the-session) |362| `CLAUDE_CODE_REMOTE_SESSION_ID` | 在 [云会话](/docs/zh-CN/claude-code-on-the-web) 中自动设置为当前会话的 ID。读取此项以构造回到会话成绩单的链接。参见 [将输出链接回会话](/docs/zh-CN/cloud-environments#link-output-back-to-the-session) |

381| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 设置为 `1` 以跳过客户端 [快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 可用性检查，用于拦截检查请求而不是拒绝它的代理。当您的组织禁用快速模式时，API 仍然拒绝快速模式请求 |382| `CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK` | 设置为 `1` 以跳过客户端 [快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) 可用性检查，用于拦截检查请求而不是拒绝它的代理。当您的组织禁用快速模式时，API 仍然拒绝快速模式请求 |

382| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 跳过 Microsoft Foundry 的 Azure 身份验证，用于代理或网关注入其自己的 `Authorization` 标头。Claude Code 发送没有 Azure 凭证的请求并保留您提供的 `Authorization` 标头，例如通过 `ANTHROPIC_CUSTOM_HEADERS`。当设置 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 时被忽略。在 v2.1.203 之前，此变量使 Microsoft Foundry 客户端无法发送请求，除非也设置了 API 密钥 |383| `CLAUDE_CODE_SKIP_FOUNDRY_AUTH` | 跳过 Microsoft Foundry 的 Azure 身份验证，用于代理或网关注入其自己的 `Authorization` 标头。Claude Code 发送没有 Azure 凭证的请求并保留您提供的 `Authorization` 标头，例如通过 `ANTHROPIC_CUSTOM_HEADERS`。当设置 `ANTHROPIC_FOUNDRY_API_KEY` 或 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 时被忽略。在 v2.1.203 之前，此变量使 Microsoft Foundry 客户端无法发送请求，除非也设置了 API 密钥 |

385| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | [启动模型检查](/docs/zh-CN/amazon-bedrock#startup-model-checks) 在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 和 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 上记住在此机器上哪些模型他们发现您的帐户无法调用，最多一天。设置为 `1` 以关闭该内存。需要 Claude Code v2.1.285 或更高版本 |

384| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 设置为 `1` 以跳过将提示历史和会话成绩单写入磁盘。使用此变量启动的会话不出现在 `--resume`、`--continue` 或向上箭头历史中。对于临时脚本会话很有用 |386| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 设置为 `1` 以跳过将提示历史和会话成绩单写入磁盘。使用此变量启动的会话不出现在 `--resume`、`--continue` 或向上箭头历史中。对于临时脚本会话很有用 |

386| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | 设置为 `1` 以使用 `--output-format stream-json` 启动的会话为启动失败写入 [结果消息，说明 Claude Code 为什么拒绝启动](/docs/zh-CN/agent-sdk/typescript#startup_failure_reason)，否则仅以 stderr 结束。需要 Claude Code v2.1.274 或更高版本 |388| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | 设置为 `1` 以使用 `--output-format stream-json` 启动的会话为启动失败写入 [结果消息，说明 Claude Code 为什么拒绝启动](/docs/zh-CN/agent-sdk/typescript#startup_failure_reason)，否则仅以 stderr 结束。需要 Claude Code v2.1.274 或更高版本 |

errors.md +352 −323

Details

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

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

325| `Claude Code's fullscreen renderer didn't finish starting last time on this machine` / `Claude Code's fullscreen renderer has repeatedly failed to start on this machine` | [配置警告](#fullscreen-failed-start-notice) |325| `Claude Code's fullscreen renderer didn't finish starting last time on this machine` / `Claude Code's fullscreen renderer has repeatedly failed to start on this machine` | [全屏渲染](/docs/zh-CN/fullscreen#fullscreen-renderer-didnt-finish-starting) |

326| `Claude Code exited after an unrecoverable interface error (...)` | [配置警告](#exited-after-an-unrecoverable-interface-error) |326| `Claude Code exited after an unrecoverable interface error (...)` | [配置警告](#exited-after-an-unrecoverable-interface-error) |

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

333| `Claude Code can't start: your organization's managed settings block the default model` / `Claude Code can't start: your organization allows only the models listed in "availableModels"` | [配置警告](#managed-settings-block-the-default-model) |333| `Claude Code can't start: your organization's managed settings block the default model` / `Claude Code can't start: your organization allows only the models listed in "availableModels"` | [配置警告](#managed-settings-block-the-default-model) |

334| `Your organization's managed settings allow Claude Code to use: <providers>` | [配置警告](#managed-settings-dont-allow-this-api-provider) |

335| `Your organization's managed settings allow Claude Code to use no API provider at all` | [配置警告](#managed-settings-dont-allow-this-api-provider) |

334| `MCP server <name> is blocked by enterprise managed policy` | [配置警告](#mcp-server-is-blocked-by-enterprise-managed-policy) |336| `MCP server <name> is blocked by enterprise managed policy` | [配置警告](#mcp-server-is-blocked-by-enterprise-managed-policy) |

335| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [配置警告](#managed-settings-document-could-not-be-parsed) |337| `Managed settings document could not be parsed as a JSON object; none of its settings are in effect. Fix or remove it.` | [配置警告](#managed-settings-document-could-not-be-parsed) |

339| `Unable to read managed policy settings` | [配置警告](#unable-to-read-managed-policy-settings) |

338| `"crossSessionInbound" must be one of "accept", "hold", "refuse"` | [配置警告](#crosssessioninbound-must-be-one-of-accept-hold-refuse) |341| `"crossSessionInbound" must be one of "accept", "hold", "refuse"` | [配置警告](#crosssessioninbound-must-be-one-of-accept-hold-refuse) |

2846 命令行错误2849 命令行错误

2847</h2>2850</h2>

2848 2851

2849这些错误来自 `claude` 命令行及其子命令、您在提示符处提交的命令名称，以及诸如 `/security-review` 之类的命令，这些命令通过运行 shell 命令来收集上下文，然后再运行其提示。它们也来自 `/tui`，它会重新启动 CLI。2852这些错误来自 `claude` 命令行及其子命令、您在提示符处提交的命令名称，以及诸如 `/security-review` 之类的命令，这些命令在运行其提示之前通过运行 shell 命令来收集上下文。它们也来自 `/tui`，它会重新启动 CLI。

2850 2853

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

2852 \--bg 和 --print 之间的冲突2855 `--bg` 和 `--print` 之间的冲突

2853</h3>2856</h3>

2854 2857

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

2856 2859

2857```text theme={null}2860```text theme={null}

2861--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.

2858```2862```

2859 2863

2860**要做什么：**2864**应该做什么：**

2861 2865

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

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

2864 2868

2865<h3 id="invalid-agents-configuration">2869<h3 id="invalid-agents-configuration">

2866 无效的 --agents 配置2870 无效的 `--agents` 配置

2867</h3>2871</h3>

2868 2872

2869您传递给 `--agents` 的值无效，因此 `claude` 以代码 1 退出，而不是启动会话。当您传递 `--safe-mode` 或设置 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-CN/env-vars#variables) 时，Claude Code 忽略 `--agents` 完全。使用 `--resume` 或 `--continue` 时，内联 JSON 值不被检查，会话启动；从文件读取的值在每次启动时被检查。在 v2.1.242 之前，Claude Code 无论如何都会启动会话。2873您传递给 `--agents` 的值无效，所以 `claude` 以代码 1 退出，而不是启动会话。当您传递 `--safe-mode` 或设置 [`CLAUDE_CODE_SAFE_MODE`](/docs/zh-CN/env-vars#variables) 时，Claude Code 会完全忽略 `--agents`。使用 `--resume` 或 `--continue` 时，不会检查内联 JSON 值，会话会启动；从文件读取的值在每次启动时都会被检查。在 v2.1.242 之前，Claude Code 无论如何都会启动会话。

2870 2874

2871```text theme={null}2875```text theme={null}

2872Error: Invalid --agents configuration:2876Error: Invalid --agents configuration:

2876 2879

2877第一行之后的内容取决于值如何失败。Claude Code 按顺序运行这些检查，并在第一个失败的检查处停止。如果您的值有两种问题，您只有在修复第一个问题后才会看到第二个问题：2880第一行之后的内容取决于值如何失败。Claude Code 按顺序运行这些检查，并在第一个失败的检查处停止。如果您的值有两种问题，您只有在修复第一个问题后才会看到第二个问题：

2878 2881

28791. 当值以 `{` 开头但不能解析为 JSON 时，或 `--agents` 文件的内容不能解析时，Claude Code 打印一行 `invalid JSON:` 行，其中包含 JSON 解析器自己的消息28821. 当值以 `{` 开头但不能解析为 JSON，或 `--agents` 文件的内容不能解析时，Claude Code 会打印一行 `invalid JSON:`，其中包含 JSON 解析器自己的消息

28802. 当它解析但代理定义与 [CLI 定义的子代理](/docs/zh-CN/sub-agents#choose-the-subagent-scope) 的架构不匹配时，Claude Code 为每个问题打印一行28832. 当它解析但代理定义与 [CLI 定义的子代理](/docs/zh-CN/sub-agents#choose-the-subagent-scope)的架构不匹配时，Claude Code 会为每个问题打印一行

28813. 当代理名称以 `-` 开头时，Claude Code 打印 `<name>: agent names must not start with '-'`28843. 当代理名称以 `-` 开头时，Claude Code 会打印 `<name>: agent names must not start with '-'`

2882 2885

2883当有超过 20 个问题行时，Claude Code 打印前 20 个，并用 `…and N more` 替换其余的。2886当有超过 20 行问题时，Claude Code 会打印前 20 行，并用 `…and N more` 替换其余部分。

2884 2887

2885使用 `--print` 时，`--agents` 也接受[JSON 文件的路径](/docs/zh-CN/sub-agents#choose-the-subagent-scope)代替内联对象。在 v2.1.281 之前，`--agents` 仅接受内联 JSON，并将文件路径视为无效 JSON。文件形式有其自己的拒绝，打印在此消息的位置，包括这些：2888使用 `--print` 时，`--agents` 也接受 [JSON 文件的路径](/docs/zh-CN/sub-agents#choose-the-subagent-scope)代替内联对象。在 v2.1.281 之前，`--agents` 仅接受内联 JSON，并将文件路径视为无效 JSON。文件形式有其自己的拒绝，打印在此消息的位置，包括这些：

2886 2889

2887* **`Error: --agents takes a JSON object, or a file path only with --print (-p)`**：Claude Code 在交互式会话中将值读取为文件路径。将定义作为内联 JSON 传递，或添加 `-p` 从文件读取它们。2890* **`Error: --agents takes a JSON object, or a file path only with --print (-p)`**：Claude Code 在交互会话中将值读取为文件路径。将定义作为内联 JSON 传递，或添加 `-p` 从文件读取它们。

2888* **`Error: --agents file not found: <path>`**：该路径处不存在文件。不以 `{` 开头且不是有效 JSON 的值被读取为路径，因此您的 shell 损坏的内联 JSON 也可能以这种方式失败。检查路径或引用，然后再次运行命令。2891* **`Error: --agents file not found: <path>`**：该路径不存在任何文件。不以 `{` 开头且不是有效 JSON 的值被读取为路径，所以您的 shell 损坏的内联 JSON 也可能以这种方式失败。检查路径或引号，然后再次运行命令。

2889 2892

2890**要做什么：**2893**应该做什么：**

2891 2894

2892* 修复消息列出的每个问题，然后再次运行命令。请参阅 [CLI 定义的子代理采用的字段](/docs/zh-CN/sub-agents#choose-the-subagent-scope)。2895* 修复消息列出的每个问题，然后再次运行命令。请参阅 [CLI 定义的子代理采用的字段](/docs/zh-CN/sub-agents#choose-the-subagent-scope)。

2893 2896

2894<h3 id="cloud-sessions-cannot-be-created-from-a-restricted-session">2897<h3 id="cloud-sessions-cannot-be-created-from-a-restricted-session">

2895 无法从 --restricted 会话创建云会话2898 无法从 `--restricted` 会话创建云会话

2896</h3>2899</h3>

2897 2900

2898当您使用 [`--restricted`](/docs/zh-CN/cli-reference#cli-flags) 启动会话时，Claude Code 拒绝从它创建[云会话](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)，因为新会话将在受限进程之外运行，不会强制执行受限模式。Claude Code 在客户端拒绝，在联系服务器之前，因此不会创建云会话：2901当您使用 [`--restricted`](/docs/zh-CN/cli-reference#cli-flags) 启动会话时，Claude Code 拒绝从中创建[云会话](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)，因为新会话将在受限进程之外运行，不会强制执行受限模式。Claude Code 在客户端拒绝，在联系服务器之前，所以不会创建云会话：

2899 2902

2900```text theme={null}2903```text theme={null}

2901Cloud sessions cannot be created from a --restricted session: they would not enforce it.2904Cloud sessions cannot be created from a --restricted session: they would not enforce it.

2902```2905```

2903 2906

2904**要做什么：**2907**应该做什么：**

2905 2908

2906* 在受限会话中本地运行任务2909* 在受限会话中本地运行任务

2907* 如果您控制会话的启动方式，请启动一个没有 `--restricted` 的新 `claude` 会话，并从那里创建云会话2910* 如果您控制会话的启动方式，请启动一个没有 `--restricted` 的新 `claude` 会话，并从那里创建云会话

2909在 v2.1.248 之前，Claude Code 没有 `--restricted` 标志；较早的版本会以未知选项错误拒绝该标志本身。2912在 v2.1.248 之前，Claude Code 没有 `--restricted` 标志；较早的版本会以未知选项错误拒绝该标志本身。

2910 2913

2911<h3 id="cloud-sessions-are-disabled-by-your-organizations-policy">2914<h3 id="cloud-sessions-are-disabled-by-your-organizations-policy">

2912 云会话被您的组织的策略禁用2915 您的组织的策略禁用了云会话

2913</h3>2916</h3>

2914 2917

2915您的组织的 `allow_remote_sessions` 策略已关闭，因此[云会话](/docs/zh-CN/claude-code-on-the-web)和使用它们的命令不可用：2918您的组织的 `allow_remote_sessions` 策略已关闭，所以[云会话](/docs/zh-CN/claude-code-on-the-web)和使用它们的命令不可用：

2916 2919

2917```text theme={null}2920```text theme={null}

2918Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.2921Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.

2919```2922```

2920 2923

2921当您[从终端创建云会话](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)时，消息会出现，当您提交需要云会话的命令时，例如 `/teleport`、`/remote-env` 或 `/web-setup`。在 v2.1.268 之前，提交其中一个命令会返回 [`Unknown command`](#unknown-command)。2924当您[从终端创建云会话](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)时，消息会出现，当您提交需要云会话的命令时，例如 `/teleport`、`/remote-env` 或 `/web-setup`。在 v2.1.268 之前，提交其中一个命令会返回[`Unknown command`](#unknown-command)。

2922 2925

2923这是一个服务器端组织策略，因此无法从本地设置、环境变量或 CLI 标志覆盖。2926这是一个服务器端组织策略，所以它不能从本地设置、环境变量或 CLI 标志中被覆盖。

2924 2927

2925如果 Claude Code 尚未加载您的组织的策略或无法获取它，这些命令会回答 `Couldn't verify your organization's policy for cloud sessions. Check your network connection, then restart Claude Code and try again.`。2928如果 Claude Code 还没有加载您的组织策略或无法获取它，这些命令会回答 `Couldn't verify your organization's policy for cloud sessions. Check your network connection, then restart Claude Code and try again.`。

2926 2929

2927**要做什么：**2930**应该做什么：**

2928 2931

2929* 要求您的组织中的[所有者](/docs/zh-CN/server-managed-settings#access-control)在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 的 Claude Code 管理员设置中启用云会话2932* 请您的组织中的[所有者](/docs/zh-CN/server-managed-settings#access-control)在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 的 Claude Code 管理员设置中启用云会话

2930* 如果消息说它无法验证策略，请检查您的网络连接，然后重新启动 Claude Code 并重试2933* 如果消息说它无法验证策略，请检查您的网络连接，然后重新启动 Claude Code 并重试

2931 2934

2932<h3 id="the-json-schema-value-is-not-a-valid-json-schema">2935<h3 id="the-json-schema-value-is-not-a-valid-json-schema">

2933 \--json-schema 值不是有效的 JSON Schema2936 `--json-schema` 值不是有效的 JSON Schema

2934</h3>2937</h3>

2935 2938

2936您传递给 [`--json-schema`](/docs/zh-CN/cli-reference#cli-flags) 的架构在[非交互模式](/docs/zh-CN/headless#get-structured-output)中未能通过 JSON Schema 编译，因此 `claude` 以代码 1 退出，而不是运行提示。在 v2.1.205 之前，无效的架构会产生无结构的输出，没有错误，任何使用 `format` 关键字的架构都被视为无效。2939您传递给 [`--json-schema`](/docs/zh-CN/cli-reference#cli-flags) 的架构在[非交互模式](/docs/zh-CN/headless#get-structured-output)中失败了 JSON Schema 编译，所以 `claude` 以代码 1 退出，而不是运行提示。在 v2.1.205 之前，无效的架构会产生无结构的输出，没有错误，任何使用 `format` 关键字的架构都被视为无效。

2937 2940

2938```text theme={null}2941```text theme={null}

2939Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values2942Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values

2941 2944

2942第二个冒号后的文本是验证器的诊断，并命名失败的关键字或位置。使用 `format` 关键字的架构，例如 `"format": "email"`，是有效的：Claude Code 接受 `format` 作为注释，不强制执行它。2945第二个冒号后的文本是验证器的诊断，并命名失败的关键字或位置。使用 `format` 关键字的架构，例如 `"format": "email"`，是有效的：Claude Code 接受 `format` 作为注释，不强制执行它。

2943 2946

2944Claude Code 在架构编译之前运行两个检查：它拒绝不可解析的 JSON 值，错误为 `Error: --json-schema is not valid JSON`，以及有效的 JSON 但不是对象的值，错误为 `Error: --json-schema must be a JSON object`。2947Claude Code 在架构编译之前运行两个检查：它拒绝不可解析的 JSON 值，显示 `Error: --json-schema is not valid JSON`，以及不是对象的有效 JSON，显示 `Error: --json-schema must be a JSON object`。

2945 2948

2946**要做什么：**2949**应该做什么：**

2947 2950

2948* 修复诊断命名的架构部分，然后重新运行命令2951* 修复诊断命名的架构部分，然后重新运行命令

2949* 请参阅[获取结构化输出](/docs/zh-CN/headless#get-structured-output)以获取工作架构和命令2952* 请参阅[获取结构化输出](/docs/zh-CN/headless#get-structured-output)以获取工作架构和命令

2952 设置文件超过 2MiB 限制2955 设置文件超过 2MiB 限制

2953</h3>2956</h3>

2954 2957

2955您传递给 [`--settings`](/docs/zh-CN/cli-reference#cli-flags) 的文件大于 2 MiB，因此 `claude` 在启动时以代码 1 退出，而不是加载它。在 v2.1.214 之前，Claude Code 读取文件时没有大小检查，多 GB 的文件或诸如 `/dev/zero` 之类的设备文件会无限增长内存。2958您传递给 [`--settings`](/docs/zh-CN/cli-reference#cli-flags) 的文件大于 2 MiB，所以 `claude` 在启动时以代码 1 退出，而不是加载它。在 v2.1.214 之前，Claude Code 读取文件时没有大小检查，多 GB 文件或诸如 `/dev/zero` 之类的设备文件会无限增长内存。

2956 2959

2957```text theme={null}2960```text theme={null}

2958Error: Settings file exceeds the 2MiB limit: /path/to/settings.json2961Error: Settings file exceeds the 2MiB limit: /path/to/settings.json

2960 2963

2961Claude Code 以相同的方式拒绝不是常规文件的 `--settings` 路径：设备、FIFO 或套接字报告 `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))`，后跟路径，目录报告 `EISDIR` 原因。2964Claude Code 以相同的方式拒绝不是常规文件的 `--settings` 路径：设备、FIFO 或套接字报告 `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))`，后跟路径，目录报告 `EISDIR` 原因。

2962 2965

2963**要做什么：**2966**应该做什么：**

2964 2967

2965* 将 `--settings` 指向 2 MiB 以下的常规 JSON 设置文件。请参阅[设置](/docs/zh-CN/settings)以了解格式。2968* 将 `--settings` 指向 2 MiB 以下的常规 JSON 设置文件。请参阅[设置](/docs/zh-CN/settings)了解格式。

2966 2969

2967<h3 id="the-current-directory-no-longer-exists">2970<h3 id="the-current-directory-no-longer-exists">

2968 当前目录不再存在2971 当前目录不再存在

2969</h3>2972</h3>

2970 2973

2971您从一个在您的 shell 进入后被删除或移动的目录启动了 `claude`，例如 worktree 或另一个 shell 删除的临时目录。Claude Code 无法读取其工作目录，因此它在启动会话之前以代码 1 退出，在交互和[非交互](/docs/zh-CN/headless)模式中都是如此。在 v2.1.239 之前，Claude Code 会因缩小的捆绑源和原始 `ENOENT ... uv_cwd` 堆栈在 stderr 上崩溃，而不是显示此消息。2974您从一个在您的 shell 进入后被删除或移动的目录启动了 `claude`，例如另一个 shell 删除的 worktree 或临时目录。Claude Code 无法读取其工作目录，所以它在启动会话之前以代码 1 退出，在交互和[非交互](/docs/zh-CN/headless)模式中都是如此。在 v2.1.239 之前，Claude Code 会因缩小的捆绑源和原始 `ENOENT ... uv_cwd` 堆栈在 stderr 上崩溃，而不是显示此消息。

2972 2975

2973```text theme={null}2976```text theme={null}

2974The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.2977The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.

2975error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again.2978error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again.

2976```2979```

2977 2980

2978原因和修复对两种形式都是相同的。2981两种形式的原因和修复是相同的。

2979 2982

2980当 Claude Code 因其他原因（例如权限更改）无法读取工作目录时，消息会命名错误代码：`Can't read the current directory (EACCES). Start Claude Code from a different directory.`2983当 Claude Code 因其他原因（例如权限更改）无法读取工作目录时，消息会命名错误代码：`Can't read the current directory (EACCES). Start Claude Code from a different directory.`

2981 2984

2982在 macOS 上，`~/Desktop`、`~/Documents`、`~/Downloads` 或 iCloud Drive 中目录的 `EPERM` 通常意味着 macOS 阻止您的终端应用访问该文件夹。读取该文件夹的其他命令也会以相同的方式失败：即使使用 `sudo`，`ls` 也会报告 `Operation not permitted`。2985在 macOS 上，`~/Desktop`、`~/Documents`、`~/Downloads` 或 iCloud Drive 中目录的 `EPERM` 通常意味着 macOS 阻止您的终端应用访问该文件夹。读取该文件夹的其他命令也会以相同的方式失败：即使使用 `sudo`，`ls` 也会报告 `Operation not permitted`。

2983 2986

2984**要做什么：**2987**应该做什么：**

2985 2988

2986* 更改为存在的目录，例如您的主目录或项目目录，然后再次运行 `claude`2989* 更改为存在的目录，例如您的主目录或项目目录，然后再次运行 `claude`

2987* 如果目录在同一路径处被重新创建，您的 shell 仍然持有已删除的目录。运行 `cd "$PWD"` 或离开并重新进入目录，然后再次运行 `claude`2990* 如果目录在同一路径被重新创建，您的 shell 仍然持有已删除的目录。运行 `cd "$PWD"` 或离开并重新进入目录，然后再次运行 `claude`

2988* 对于 macOS 上的 `EPERM`，使用 Cmd+Q 退出您的终端应用，重新打开它，返回该文件夹，然后运行 `claude`。如果该文件夹中的 `ls` 仍然失败，请打开**系统设置 > 隐私和安全 > 文件和文件夹**，为您的终端应用打开该文件夹，然后重新打开终端2991* 对于 macOS 上的 `EPERM`，使用 Cmd+Q 退出您的终端应用，重新打开它，返回该文件夹，然后运行 `claude`。如果该文件夹中的 `ls` 仍然失败，请打开**系统设置 > 隐私和安全 > 文件和文件夹**，为您的终端应用打开该文件夹，然后重新打开终端

2989 2992

2990<h3 id="temp-directory-refused-or-cannot-be-created">2993<h3 id="temp-directory-refused-or-cannot-be-created">

2991 临时目录被拒绝或无法创建2994 临时目录被拒绝或无法创建

2992</h3>2995</h3>

2993 2996

2994在 macOS 和 Linux 上，Claude Code 在启动时创建一个私有临时目录 `claude-<uid>`，位于系统临时目录或 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars) 覆盖下。当无法创建目录或该路径处的现有条目未通过安全检查时，Claude Code 将失败打印到 stderr 并以代码 1 退出，而不是启动会话：2997在 macOS 和 Linux 上，Claude Code 在启动时创建一个私有临时目录 `claude-<uid>`，位于系统临时目录或 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars) 覆盖下。当目录无法创建，或该路径处的现有条目未通过安全检查时，Claude Code 将失败打印到 stderr 并以代码 1 退出，而不是启动会话：

2995 2998

2996```text wrap theme={null}2999```text wrap theme={null}

2997ENOSPC: no space left on device, mkdir '/tmp/claude-501'3000ENOSPC: no space left on device, mkdir '/tmp/claude-501'

3003Temp directory /tmp/claude-501 is not readable (its mode may have been altered, or a path component denies search). Refusing to use it — restore its permissions (chmod 0700) or remove it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.3006Temp directory /tmp/claude-501 is not readable (its mode may have been altered, or a path component denies search). Refusing to use it — restore its permissions (chmod 0700) or remove it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it.

3004```3007```

3005 3008

3006**要做什么：**3009**应该做什么：**

3007 3010

3008* 对于 `ENOSPC`，释放保存临时目录的卷上的磁盘空间3011* 对于 `ENOSPC`，释放保存临时目录的卷上的磁盘空间

3009* 对于 `Refusing to use it` 形式，删除命名的条目本身，而不是链接指向的内容，然后再次启动 Claude Code；对于 `owned by uid` 形式，只有管理员或该用户可以删除它3012* 对于 `Refusing to use it` 形式，删除命名的条目本身，而不是链接指向的内容，然后再次启动 Claude Code；对于 `owned by uid` 形式，只有管理员或该用户可以删除它

3010* 对于 `is not readable`，在命名目录上运行 `chmod 0700`，或删除它并重新启动3013* 对于 `is not readable`，在命名目录上运行 `chmod 0700`，或删除它并重新启动

3011* 在任何这些情况下，将 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars) 设置为您控制的目录并启动 Claude Code，保持拒绝的路径不变3014* 在任何这些情况下，将 [`CLAUDE_CODE_TMPDIR`](/docs/zh-CN/env-vars) 设置为您控制的目录并启动 Claude Code，保留被拒绝的路径不变

3012 3015

3013<h3 id="directory-couldnt-be-resolved-to-a-real-location">3016<h3 id="directory-couldnt-be-resolved-to-a-real-location">

3014 目录无法解析为真实位置3017 目录无法解析为真实位置

3016 3019

3017您为工作目录的子目录运行了 `/add-dir`，Claude Code 无法将目录解析为其真实位置。3020您为工作目录的子目录运行了 `/add-dir`，Claude Code 无法将目录解析为其真实位置。

3018 3021

3019您已经有对工作目录的子目录的文件访问权限，因此 `/add-dir` 仅加载其 skills、命令和代理。在加载它们之前，Claude Code 检查目录的真实位置（解析任何符号链接）是否在工作目录内。当 Claude Code 无法解析该位置时，它不加载任何内容并显示此消息：3022您已经可以访问工作目录的子目录，所以 `/add-dir` 只加载其 skills、命令和代理。在加载它们之前，Claude Code 检查目录的真实位置（解析任何符号链接）是否在工作目录内。当 Claude Code 无法解析该位置时，它不加载任何内容并显示此消息：

3020 3023

3021```text theme={null}3024```text theme={null}

3022packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.3025packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.

3023```3026```

3024 3027

3025**要做什么：**3028**应该做什么：**

3026 3029

3027* 检查路径是否命名工作目录内的真实目录，然后再次运行 `/add-dir`3030* 检查路径是否命名工作目录内的真实目录，然后再次运行 `/add-dir`

3028* 消息不会改变您的文件访问；它仅报告目录的 `.claude/` 内容未被加载3031* 消息不会改变您的文件访问权限；它只报告目录的 `.claude/` 内容未被加载

3029 3032

3030在 v2.1.261 之前，当工作目录在 `/net/<host>` 自动挂载上时，此消息也会为每个 `/add-dir <subdirectory>` 出现，Claude Code 根据设计拒绝解析路径；目录很好，重试无法帮助。3033在 v2.1.261 之前，当工作目录在 `/net/<host>` 自动挂载上时，此消息也会为每个 `/add-dir <subdirectory>` 出现，Claude Code 按设计拒绝解析路径；目录很好，重试无法帮助。

3031 3034

3032<h3 id="workspace-not-trusted-when-starting-remote-control">3035<h3 id="workspace-not-trusted-when-starting-remote-control">

3033 启动远程控制时工作区不受信任3036 启动远程控制时工作区不受信任

3034</h3>3037</h3>

3035 3038

3036您在未信任的目录中使用 `claude remote-control` 或其 `claude rc` 别名启动了[远程控制](/docs/zh-CN/remote-control)服务器模式，命令无法询问您是否信任它。当命令的标准输入或标准输出不是终端时，此消息会出现，例如因为其中之一被重定向或管道化。命令以代码 1 退出：3039您在未信任的目录中使用 `claude remote-control` 或其 `claude rc` 别名启动了[远程控制](/docs/zh-CN/remote-control)服务器模式，命令无法询问您是否信任它。例如，命令的标准输入或标准输出不是终端，因为其中一个被重定向或管道化。命令以代码 1 退出：

3037 3040

3038```text theme={null}3041```text theme={null}

3039Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.3042Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.

3040```3043```

3041 3044

3042两个也以 `Error: Workspace not trusted.` 开头的变体也出现在足够小的终端中，无法显示信任目录打开的内容，或一个没有报告其大小的终端。扩大窗口或切换到正常终端窗口，然后再次运行 `claude rc`。3045两个也以 `Error: Workspace not trusted.` 开头的变体也出现在足够小的终端中，无法显示信任目录会打开什么，或一个没有报告其大小的终端。放大窗口或切换到正常终端窗口，然后再次运行 `claude rc`。

3043 3046

3044在您的主目录中，消息是不同的，因为工作区信任对话框永远不会保存主目录的信任，因此在那里接受它无法满足此检查。在 v2.1.214 之前，主目录显示上述消息，其建议无法在那里成功。3047在您的主目录中，消息是不同的，因为工作区信任对话永远不会为主目录保存信任，所以在那里接受它无法满足此检查。在 v2.1.214 之前，主目录显示上面的消息，其建议在那里无法成功。

3045 3048

3046```text theme={null}3049```text theme={null}

3047Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).3050Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).

3049 3052

3050如果您在 [`Trust <directory>?` 问题](/docs/zh-CN/remote-control#requirements)处回答 `n` 或按 Enter，命令会打印一条 `Remote Control did not start` 消息，命名目录并以代码 1 退出。再次运行 `claude rc` 以回答 `y`。3053如果您在 [`Trust <directory>?` 问题](/docs/zh-CN/remote-control#requirements)处回答 `n` 或按 Enter，命令会打印一条 `Remote Control did not start` 消息，命名目录并以代码 1 退出。再次运行 `claude rc` 以回答 `y`。

3051 3054

3052**要做什么：**3055**应该做什么：**

3053 3056

3054* 首先从终端信任目录：在那里运行 `claude rc` 并回答 `y`，或运行 `claude` 并接受[工作区信任对话框](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)，然后再次运行您的原始命令3057* 首先从终端信任目录：在那里运行 `claude rc` 并回答 `y`，或运行 `claude` 并接受[工作区信任对话](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)，然后再次运行您的原始命令

3055* 在您的主目录中，更改为项目目录并在那里启动远程控制3058* 在您的主目录中，更改为项目目录并在那里启动远程控制

3056 3059

3057在 v2.1.284 之前，命令从不询问，即使在终端中。3060在 v2.1.284 之前，命令从不询问，即使在终端中也是如此。

3058 3061

3059<h3 id="not-carried-over-to-the-sessions-remote-control-starts">3062<h3 id="not-carried-over-to-the-sessions-remote-control-starts">

3060 未被远程控制启动的会话继承3063 未被远程控制启动的会话继承

3061</h3>3064</h3>

3062 3065

3063您使用全局 `claude` 标志在 `remote-control` 动词之前启动了[远程控制](/docs/zh-CN/remote-control)，该标志会限制或配置远程控制启动的会话，例如 `--settings`、`--setting-sources`、`--permission-mode`、`--disallowed-tools` 或 `--mcp-config`。放在动词之前的标志永远不会到达这些会话。Claude Code 拒绝启动，而是命名标志：3066您使用全局 `claude` 标志在 `remote-control` 动词之前启动了[远程控制](/docs/zh-CN/remote-control)，该标志会限制或配置远程控制启动的会话，例如 `--settings`、`--setting-sources`、`--permission-mode`、`--disallowed-tools` 或 `--mcp-config`。放在动词之前的标志永远不会到达这些会话。Claude Code 拒绝启动，命名标志：

3064 3067

3065```text theme={null}3068```text theme={null}

3066Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).3069Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`).

3068 3071

3069Claude Code 不拒绝无害的全局标志，例如 `--verbose`、`--model` 或包装器注入的 `--session-id` 或 `--plugin-dir`：它忽略它们，远程控制启动。3072Claude Code 不拒绝无害的全局标志，例如 `--verbose`、`--model` 或包装器注入的 `--session-id` 或 `--plugin-dir`：它忽略它们，远程控制启动。

3070 3073

3071Claude Code 也拒绝启动一个它尚未识别为无害的全局标志，因此在较新版本中添加的标志可能会出现在此消息中，直到稍后的版本将其标记为无害。3074Claude Code 也拒绝启动一个它还不认识为无害的全局标志，所以较新版本中添加的标志可能会出现在此消息中，直到稍后的版本将其标记为无害。

3072 3075

3073**要做什么：**3076**应该做什么：**

3074 3077

3075* 从动词之前删除标志，并在其后传递[远程控制自己的选项](/docs/zh-CN/remote-control#start-a-remote-control-session)；`claude remote-control --help` 列出它们3078* 从动词之前删除标志，并在其后传递[远程控制自己的选项](/docs/zh-CN/remote-control#start-a-remote-control-session)；`claude remote-control --help` 列出它们

3076* 当拒绝的标志是 `--permission-mode` 时，运行 `claude remote-control --permission-mode <mode>` 为远程控制启动的会话设置权限模式3079* 当被拒绝的标志是 `--permission-mode` 时，运行 `claude remote-control --permission-mode <mode>` 为远程控制启动的会话设置权限模式

3077 3080

3078在 v2.1.248 之前，当全局标志首先出现时，`claude remote-control` 不接受自己的标志，命令失败并出现 `unknown option` 错误。3081在 v2.1.248 之前，当全局标志首先出现时，`claude remote-control` 不接受其自己的标志，命令失败并显示未知选项错误。

3079 3082

3080<h3 id="claude-import-is-not-yet-available-in-this-build">3083<h3 id="claude-import-is-not-yet-available-in-this-build">

3081 claude import 在此构建中尚不可用3084 claude import 在此构建中尚不可用

3082</h3>3085</h3>

3083 3086

3084您运行了 [`claude import`](/docs/zh-CN/cli-reference#cli-commands)，Claude Code 发现导入流已关闭，因此命令以代码 1 退出，而不是启动导入。在 v2.1.222 之前，导入流关闭的构建将 `import` 视为提示并启动交互会话，而不是打印此消息。3087您运行了 [`claude import`](/docs/zh-CN/cli-reference#cli-commands)，Claude Code 发现导入流已关闭，所以命令以代码 1 退出，而不是启动导入。在 v2.1.222 之前，关闭导入流的构建将 `import` 视为提示并启动交互会话，而不是打印此消息。

3085 3088

3086```text theme={null}3089```text theme={null}

3087`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.3090`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.

3088```3091```

3089 3092

3090Claude Code 通过从 Anthropic 获取的功能标志打开 `claude import`，并在磁盘上缓存。此消息意味着缓存的值已关闭。原因通常是以下之一：3093Claude Code 通过从 Anthropic 获取并在磁盘上缓存的功能标志打开 `claude import`。此消息意味着缓存的值已关闭。原因通常是以下之一：

3091 3094

3092* 您自安装以来尚未启动会话，因此 Claude Code 尚未获取标志。第一个 `claude import` 即使在功能对您可用时也可能打印此消息。3095* 您自安装以来还没有启动会话，所以 Claude Code 还没有获取标志。第一个 `claude import` 即使功能对您可用，也可能打印此消息。

3093* 您通过 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform，或通过[Claude 应用网关](/docs/zh-CN/claude-apps-gateway#availability-and-limitations)使用 Claude Code。Claude Code 在这些会话中不获取功能标志，因此 `claude import` 保持不可用。3096* 您通过 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或 AWS 上的 Claude Platform，或通过[Claude 应用网关](/docs/zh-CN/claude-apps-gateway#availability-and-limitations)使用 Claude Code。Claude Code 在这些会话中不获取功能标志，所以 `claude import` 保持不可用。

3094* 您设置了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK`、`DISABLE_GROWTHBOOK` 或 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-CN/env-vars)，这会关闭功能标志获取，因此 `claude import` 保持不可用。3097* 您设置了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK`、`DISABLE_GROWTHBOOK` 或 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-CN/env-vars)，它们关闭功能标志获取，所以 `claude import` 保持不可用。

3095 3098

3096**要做什么：**3099**应该做什么：**

3097 3100

3098* 在全新安装上，启动 `claude`，等待会话加载，退出，然后再次运行 `claude import`3101* 在新安装上，启动 `claude`，等待会话加载，退出，然后再次运行 `claude import`

3099* 在功能标志获取保持关闭的地方，自己设置配置：使用 [`claude mcp add`](/docs/zh-CN/mcp#installing-mcp-servers) 添加 MCP 服务器，并创建您想要继承的 [`CLAUDE.md` 文件](/docs/zh-CN/memory#how-claude-md-files-load)、[skills 和命令](/docs/zh-CN/skills#where-skills-live)以及[子代理](/docs/zh-CN/sub-agents#choose-the-subagent-scope)。消息也命名 `~/.claude/settings.json`。在 `claude import` 继承的配置中，该文件仅保存[权限模式](/docs/zh-CN/settings-reference#permission-settings)；Claude Code 不从它读取 MCP 服务器。3102* 在功能标志获取保持关闭的地方，自己设置配置：使用 [`claude mcp add`](/docs/zh-CN/mcp#installing-mcp-servers) 添加 MCP 服务器，并创建您想要继承的 [`CLAUDE.md` 文件](/docs/zh-CN/memory#how-claude-md-files-load)、[skills 和命令](/docs/zh-CN/skills#where-skills-live)以及[子代理](/docs/zh-CN/sub-agents#choose-the-subagent-scope)。消息也命名 `~/.claude/settings.json`。在 `claude import` 继承的配置中，该文件仅保存[权限模式](/docs/zh-CN/settings-reference#permission-settings)；Claude Code 不从中读取 MCP 服务器。

3100 3103

3101<h3 id="could-not-read-claude-code-config">3104<h3 id="could-not-read-claude-code-config">

3102 无法读取 Claude Code 配置3105 无法读取 Claude Code 配置

3103</h3>3106</h3>

3104 3107

3105您运行了 [`claude import`](/docs/zh-CN/cli-reference#cli-commands)，而 Claude Code 无法解析 `~/.claude.json`，这是它存储您的登录和每个项目状态的文件。子命令读取该文件以检查可用性，但不显示交互会话显示的恢复对话框，因此它以代码 1 退出。在 v2.1.222 之前，带有不可读配置文件的 `claude import` 启动了交互会话，其恢复对话框处理了该文件。3108您在 Claude Code 无法解析 `~/.claude.json` 时运行了 [`claude import`](/docs/zh-CN/cli-reference#cli-commands)，这是它存储您的登录和每个项目状态的文件。子命令读取该文件以检查可用性，但不显示交互会话显示的恢复对话，所以它以代码 1 退出。在 v2.1.222 之前，`claude import` 使用不可读的配置文件启动交互会话，其恢复对话处理该文件。

3106 3109

3107```text theme={null}3110```text theme={null}

3108Could not read Claude Code config — run `claude` with no arguments to recover it.3111Could not read Claude Code config — run `claude` with no arguments to recover it.

3109```3112```

3110 3113

3111**要做什么：**3114**应该做什么：**

3112 3115

3113* 运行 `claude` 不带参数。Claude Code 检测无效文件并提供重置它。然后再次运行 `claude import`。3116* 运行不带参数的 `claude`。Claude Code 检测无效文件并提供重置它。然后再次运行 `claude import`。

3114* 要保留您所做的手动编辑，请在编辑器中修复 `~/.claude.json` 中的 JSON 语法，然后重新运行 `claude import`3117* 要保留您所做的手动编辑，请在编辑器中修复 `~/.claude.json` 中的 JSON 语法，然后重新运行 `claude import`

3115 3118

3116<h3 id="could-not-import-a-server-from-claude-desktop">3119<h3 id="could-not-import-a-server-from-claude-desktop">

3117 无法从 Claude Desktop 导入服务器3120 无法从 Claude Desktop 导入服务器

3118</h3>3121</h3>

3119 3122

3120Claude Code 无法添加您在 `claude mcp add-from-claude-desktop` 中选择的其中一个服务器。该命令仍然导入其他选定的服务器，并为每个无法添加的服务器打印一行。在 v2.1.205 之前，第一个失败的服务器会停止导入。3123Claude Code 无法添加您在 `claude mcp add-from-claude-desktop` 中选择的其中一个服务器。命令仍然导入其他选定的服务器，并为每个无法添加的服务器打印一行。在 v2.1.205 之前，第一个失败的服务器停止了导入。

3121 3124

3122```text theme={null}3125```text theme={null}

3123Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.3126Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.

3124```3127```

3125 3128

3126服务器名称后的文本是原因。最常见的是名称检查：Claude Desktop 允许服务器名称中的字符，例如空格和句号，而 `claude mcp` 限制为字母、数字、连字符和下划线。其他原因包括未通过验证的服务器配置和被您的组织的 [MCP 策略](/docs/zh-CN/managed-mcp)阻止的服务器。3129服务器名称后的文本是原因。最常见的是名称检查：Claude Desktop 允许服务器名称中的字符，例如空格和句号，而 `claude mcp` 限制为字母、数字、连字符和下划线。其他原因包括失败验证的服务器配置和被您的组织的 [MCP 策略](/docs/zh-CN/managed-mcp)阻止的服务器。

3127 3130

3128**要做什么：**3131**应该做什么：**

3129 3132

3130* 在 `claude_desktop_config.json` 中重命名服务器以仅使用字母、数字、连字符和下划线，然后再次运行 `claude mcp add-from-claude-desktop`3133* 在 `claude_desktop_config.json` 中重命名服务器以仅使用字母、数字、连字符和下划线，然后再次运行 `claude mcp add-from-claude-desktop`

3131* 使用有效名称直接使用 `claude mcp add` 或 `claude mcp add-json` 添加该服务器。请参阅[从 Claude Desktop 导入 MCP 服务器](/docs/zh-CN/mcp#import-mcp-servers-from-claude-desktop)。3134* 使用 `claude mcp add` 或 `claude mcp add-json` 在有效名称下直接添加该服务器。请参阅[从 Claude Desktop 导入 MCP 服务器](/docs/zh-CN/mcp#import-mcp-servers-from-claude-desktop)。

3132 3135

3133<h3 id="cannot-add-mcp-server-to-the-managed-scope">3136<h3 id="cannot-add-mcp-server-to-the-managed-scope">

3134 无法将 MCP 服务器添加到托管范围3137 无法将 MCP 服务器添加到托管范围

3135</h3>3138</h3>

3136 3139

3137您使用 `--scope managed` 运行了 `claude mcp add` 或 `claude mcp add-json`。该范围保存您的组织通过 [`managedMcpServers`](/docs/zh-CN/settings-reference#managedmcpservers) 托管设置提供的服务器。Claude Code 仅从托管设置读取它们，因此命令无法向该范围写入服务器。3140您使用 `--scope managed` 运行了 `claude mcp add` 或 `claude mcp add-json`。该范围保存您的组织通过 [`managedMcpServers`](/docs/zh-CN/settings-reference#managedmcpservers) 托管设置提供的服务器。Claude Code 仅从托管设置读取它们，所以命令无法向该范围写入服务器。

3138 3141

3139```text theme={null}3142```text theme={null}

3140Cannot add MCP server to scope: managed3143Cannot add MCP server to scope: managed

3141```3144```

3142 3145

3143**要做什么：**3146**应该做什么：**

3144 3147

3145* 将服务器添加到您可以写入的范围：`local`、`user` 或 `project`。不带 `--scope`，命令使用 `local`。请参阅 [MCP 安装范围](/docs/zh-CN/mcp#mcp-installation-scopes)3148* 将服务器添加到您可以写入的范围：`local`、`user` 或 `project`。不带 `--scope` 时，命令使用 `local`。请参阅 [MCP 安装范围](/docs/zh-CN/mcp#mcp-installation-scopes)

3146* 要为您的组织中的每个用户提供服务器，请将其添加到您部署的托管设置中的 [`managedMcpServers`](/docs/zh-CN/settings-reference#managedmcpservers)3149* 要为您的组织中的每个用户提供服务器，请将其添加到您部署的托管设置中的 [`managedMcpServers`](/docs/zh-CN/settings-reference#managedmcpservers)

3147 3150

3148<h3 id="cant-read-mcp-json">3151<h3 id="cant-read-mcp-json">

3149 无法读取 .mcp.json3152 无法读取 .mcp.json

3150</h3>3153</h3>

3151 3154

3152读取项目的 [`.mcp.json`](/docs/zh-CN/mcp#project-scope) 的命令，例如 `claude mcp add` 或 `claude mcp add-json` 带 `--scope project`，或 `claude mcp remove`，发现您当前目录中的文件不是常规文件或大于 2 MiB，因此它以此错误退出，而不是读取文件。3155读取项目的 [`.mcp.json`](/docs/zh-CN/mcp#project-scope) 的命令，例如 `claude mcp add` 或 `claude mcp add-json` 使用 `--scope project`，或 `claude mcp remove`，发现您当前目录中的文件不是常规文件或大于 2 MiB，所以它以此错误退出，而不是读取文件。

3153 3156

3154```text theme={null}3157```text theme={null}

3155Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.3158Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.

3156```3159```

3157 3160

3158在 v2.1.257 之前，`.mcp.json` 处的 FIFO 会使命令无限期等待，没有输出，到设备文件（如 `/dev/zero`）的符号链接会增长内存，直到进程被杀死。3161在 v2.1.257 之前，`.mcp.json` 处的 FIFO 使命令永远等待，没有输出，指向诸如 `/dev/zero` 之类的设备文件的符号链接会增长内存，直到进程被杀死。

3159 3162

3160**要做什么：**3163**应该做什么：**

3161 3164

3162* 检查您当前目录中 `.mcp.json` 处的内容。将其替换为[项目范围格式](/docs/zh-CN/mcp#project-scope)中的普通 JSON 文件，或删除它，然后再次运行命令。3165* 检查您当前目录中 `.mcp.json` 处的内容。将其替换为 [project-scope 格式](/docs/zh-CN/mcp#project-scope)中的普通 JSON 文件，或删除它，然后再次运行命令。

3163 3166

3164<h3 id="mcp-server-was-not-saved-or-removed">3167<h3 id="mcp-server-was-not-saved-or-removed">

3165 MCP 服务器未被保存或删除3168 MCP 服务器未被保存或删除

3166</h3>3169</h3>

3167 3170

3168您为 `user` 或 `local` [范围](/docs/zh-CN/mcp#mcp-installation-scopes)中的服务器运行了 `claude mcp add`、`claude mcp add-json` 或 `claude mcp remove`。两个范围都存储在 `~/.claude.json` 中，当 Claude Code 在写入后读回该文件时，更改不在该文件中。命令以此错误退出，而不是其成功行。3171您为 `user` 或 `local` [范围](/docs/zh-CN/mcp#mcp-installation-scopes)中的服务器运行了 `claude mcp add`、`claude mcp add-json` 或 `claude mcp remove`。两个范围都存储在 `~/.claude.json` 中，当 Claude Code 在写入后读取该文件时，更改不在该文件中。命令以此错误退出，而不是其成功行。

3169 3172

3170```text theme={null}3173```text theme={null}

3171MCP server "example" was not saved to /home/user/.claude.json. If that file is read-only or protected by a sandbox, make it writable or run the command outside the sandbox, then add the server again.3174MCP server "example" was not saved to /home/user/.claude.json. If that file is read-only or protected by a sandbox, make it writable or run the command outside the sandbox, then add the server again.

3172```3175```

3173 3176

3174删除后，消息读取 `was not removed from` 并以 `then remove the server again` 结尾。对于 `local` 范围的服务器，路径后跟项目目录，该条目属于该目录，如 `(local scope for /path/to/project)`。3177删除后，消息读取 `was not removed from` 并以 `then remove the server again` 结尾。对于 `local` 范围服务器，路径后跟项目目录条目所属的，如 `(local scope for /path/to/project)`。

3175 3178

3176在 v2.1.283 之前，`claude mcp add`、`claude mcp add-json` 和 `claude mcp remove` 即使更改未到达文件也报告成功。3179在 v2.1.283 之前，`claude mcp add`、`claude mcp add-json` 和 `claude mcp remove` 即使更改没有到达文件也报告成功。

3177 3180

3178**要做什么：**3181**应该做什么：**

3179 3182

3180* 使消息命名的文件可写，或在沙箱外运行命令，然后再次运行相同的添加或删除命令。3183* 使消息命名的文件可写，或在沙箱外运行命令，然后再次运行相同的添加或删除命令。

3181 3184

3183 MCP 服务器可能未被保存或删除3186 MCP 服务器可能未被保存或删除

3184</h3>3187</h3>

3185 3188

3186您为 `user` 或 `local` [范围](/docs/zh-CN/mcp#mcp-installation-scopes)中的服务器运行了 `claude mcp add`、`claude mcp add-json` 或 `claude mcp remove`，Claude Code 无法读回 `~/.claude.json` 以确认更改。更改可能在磁盘上，也可能不在。括号中的文本是该读取的错误。3189您为 `user` 或 `local` [范围](/docs/zh-CN/mcp#mcp-installation-scopes)中的服务器运行了 `claude mcp add`、`claude mcp add-json` 或 `claude mcp remove`，Claude Code 无法读取 `~/.claude.json` 回来确认更改。更改可能在磁盘上，也可能不在。括号中的文本是该读取的错误。

3187 3190

3188```text theme={null}3191```text theme={null}

3189MCP server "example" may not have been saved: /home/user/.claude.json could not be read to confirm the change (EACCES: permission denied, open '/home/user/.claude.json'). Run `claude mcp get example` to check, then add the server again if it is missing.3192MCP server "example" may not have been saved: /home/user/.claude.json could not be read to confirm the change (EACCES: permission denied, open '/home/user/.claude.json'). Run `claude mcp get example` to check, then add the server again if it is missing.

3191 3194

3192删除后，消息读取 `may not have been removed` 并以 `then remove the server again if it is still listed` 结尾。3195删除后，消息读取 `may not have been removed` 并以 `then remove the server again if it is still listed` 结尾。

3193 3196

3194在 v2.1.283 之前，命令即使无法确认更改也报告成功。3197在 v2.1.283 之前，命令即使更改无法确认也报告成功。

3195 3198

3196**要做什么：**3199**应该做什么：**

3197 3200

3198* 运行 `claude mcp get <name>` 检查更改是否在磁盘上。对于 `local` 范围的服务器，从服务器所属的项目目录运行它，因为本地范围是每个项目的。3201* 运行 `claude mcp get <name>` 检查更改是否在磁盘上。对于 `local` 范围服务器，从服务器所属的项目目录运行它，因为本地范围是每个项目的。

3199* 如果服务器在添加后缺失，或在删除后仍然列出，请再次运行相同的添加或删除命令。3202* 如果服务器在添加后丢失，或在删除后仍然列出，请再次运行相同的添加或删除命令。

3200 3203

3201<h3 id="anthropic-hosted-and-doesnt-support-local-oauth">3204<h3 id="anthropic-hosted-and-doesnt-support-local-oauth">

3202 服务器是 Anthropic 托管的，不支持本地 OAuth3205 服务器是 Anthropic 托管的，不支持本地 OAuth

3203</h3>3206</h3>

3204 3207

3205您为 URL 指向通过第三方身份提供商进行身份验证的 Anthropic 托管连接器主机的 MCP 服务器启动了登录。这些主机包括 `microsoft365.mcp.claude.com`、`gmail.mcp.claude.com` 和 `gcal.mcp.claude.com`。Claude Code 拒绝从 `/mcp` 面板和 `claude mcp login` 为这些主机启动其本地 OAuth 流，因为[它们的登录仅通过 claude.ai 工作](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)。3208您为 MCP 服务器启动了登录，其 URL 指向通过第三方身份提供商进行身份验证的 Anthropic 托管连接器主机。这些主机包括 `microsoft365.mcp.claude.com`、`gmail.mcp.claude.com` 和 `gcal.mcp.claude.com`。Claude Code 拒绝为这些主机从 `/mcp` 面板和 `claude mcp login` 启动其本地 OAuth 流，因为[它们的登录仅通过 claude.ai 工作](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)。

3206 3209

3207```text theme={null}3210```text theme={null}

3208"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.3211"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.

3209```3212```

3210 3213

3211Claude Code 按 URL 匹配这些主机，因此当您使用 `claude mcp add` 或在 `.mcp.json` 中添加的服务器指向其中之一时，消息会出现。3214**应该做什么：**

~~3212~~

3213**要做什么：**

3214 3215

3215* 使用 `claude mcp remove <name>` 删除您的条目，以便它无法隐藏同一 URL 处的 claude.ai 连接器3216* 使用 `claude mcp remove <name>` 删除您的条目，以便它不能隐藏同一 URL 处的 claude.ai 连接器

3216* 删除后，在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 连接服务，同时登录到您在 Claude Code 中使用的帐户。连接后，如果您的活跃身份验证方法是 claude.ai 订阅登录，[连接器会自动出现在 Claude Code 中](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)3217* 删除后，在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 连接服务，同时登录到您在 Claude Code 中使用的帐户。连接后，如果您的活跃身份验证方法是 claude.ai 订阅登录，[连接器会自动出现在 Claude Code 中](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)

3217 3218

3218<h3 id="server-rejected-the-authorization-header-minted-by-the-configured-headershelper">3219<h3 id="server-rejected-the-authorization-header-minted-by-the-configured-headershelper">

3219 服务器拒绝了由配置的 headersHelper 生成的 Authorization 标头3220 服务器拒绝了由配置的 headersHelper 生成的 Authorization 标头

3220</h3>3221</h3>

3221 3222

3222其 [`headersHelper`](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication) 提供 `Authorization` 标头的 MCP 服务器以 HTTP 401 或 403 回答连接，因此 Claude Code 将连接报告为失败。因为助手提供 `Authorization` 标头，Claude Code [不会回退到 OAuth](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers) 对于服务器：3223其 [`headersHelper`](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication) 提供 `Authorization` 标头的 MCP 服务器以 HTTP 401 或 403 回答连接，所以 Claude Code 将连接报告为失败。因为助手提供 `Authorization` 标头，Claude Code [不会回退到 OAuth](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers) 对于服务器：

3223 3224

3224```text theme={null}3225```text theme={null}

3225Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.3226Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.

3226```3227```

3227 3228

3228Claude Code 在每次连接尝试时重新运行助手，因此在暂时拒绝后重试（例如令牌轮换竞争）可以使用新凭证成功。3229Claude Code 在每次连接尝试时重新运行助手，所以在短暂拒绝后重试，例如令牌轮换竞争，可以使用新凭证成功。

3229 3230

3230**要做什么：**3231**应该做什么：**

3231 3232

3232* 按照 Claude Code 运行它的方式自己运行 `headersHelper` 命令：从 [Claude Code 运行它的目录](/docs/zh-CN/mcp#where-the-helper-runs)，使用 [Claude Code 为其设置的环境变量](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication)，以及不使用 [Claude Code 为来自项目 `.mcp.json`、插件或项目代理文件的服务器删除的凭证变量](/docs/zh-CN/mcp#which-variables-a-helper-can-read)。检查它打印的 `Authorization` 值是否被服务器的端点接受3233* 按照 Claude Code 运行它的方式自己运行 `headersHelper` 命令：从 [Claude Code 运行它的目录](/docs/zh-CN/mcp#where-the-helper-runs)，使用 [Claude Code 为其设置的环境变量](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication)，以及不使用 [Claude Code 为来自项目 `.mcp.json`、插件或项目代理文件的服务器删除的凭证变量](/docs/zh-CN/mcp#which-variables-a-helper-can-read)。检查它是否打印服务器端点接受的 `Authorization` 值

3233* 修复助手或其凭证源后，在 `/mcp` 中选择服务器并选择**重新连接**3234* 修复助手或其凭证源后，在 `/mcp` 中选择服务器并选择**重新连接**

3234 3235

3235在 v2.1.248 之前，Claude Code 为其助手提供 `Authorization` 标头的服务器运行 OAuth 发现。该发现可能失败，错误为 `Incompatible auth server: does not support dynamic client registration`，而不是报告被拒绝的凭证。3236在 v2.1.248 之前，Claude Code 为其助手提供 `Authorization` 标头的服务器运行 OAuth 发现。该发现可能失败，显示 `Incompatible auth server: does not support dynamic client registration` 而不是报告被拒绝的凭证。

3236 3237

3237<h3 id="mcp-permission-prompt-tool-not-found">3238<h3 id="mcp-permission-prompt-tool-not-found">

3238 找不到 MCP 权限提示工具3239 未找到 MCP 权限提示工具

3239</h3>3240</h3>

3240 3241

3241您传递给 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 的工具在运行首次需要权限决定时不在连接的 MCP 工具中，要么因为其服务器从未连接，要么因为没有连接的服务器公开该名称的工具。Claude Code 仍然发送您的提示：[非交互](/docs/zh-CN/headless)运行在第一个需要批准的工具调用时以此错误和代码 1 退出，因此即使请求已发出，它也不会产生答案。在第一个提示之前，Claude Code 等待最多由 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 设置的每个服务器连接超时 30 秒，以便该服务器连接。在 v2.1.206 之前，启动不等待服务器完成连接，因此启动缓慢但健康的服务器也会产生此错误。3242您传递给 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 的工具在运行首次需要权限决定时不在连接的 MCP 工具中，要么因为其服务器从未连接，要么因为没有连接的服务器公开该名称的工具。Claude Code 仍然发送您的提示：[非交互](/docs/zh-CN/headless)运行在第一个工具调用时以此错误和退出代码 1 退出，所以即使请求已发出，它也不会产生答案。在第一个提示之前，Claude Code 等待最多由 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 设置的每个服务器连接超时 30 秒，以便该服务器连接。在 v2.1.206 之前，启动不等待服务器完成连接，所以启动缓慢但健康的服务器也会产生此错误。

3242 3243

3243```text theme={null}3244```text theme={null}

3244Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none3245Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none

3245```3246```

3246 3247

3247等待结束时连接的 MCP 工具之后的列表命名了 MCP 工具。3248`Available MCP tools:` 后的列表命名已连接的 MCP 工具。

3248 3249

3249**要做什么：**3250**应该做什么：**

3250 3251

3251* 检查服务器启动并保持连接：在同一目录中运行 `claude mcp list` 并确认服务器列为已连接3252* 检查服务器启动并保持连接：在同一目录中运行 `claude mcp list` 并确认服务器列为已连接

3252* 确认工具名称与服务器公开的 `mcp__<server>__<tool>` 名称匹配3253* 确认工具名称与服务器公开的 `mcp__<server>__<tool>` 名称匹配

3256 OAuth 回调端口已在使用中3257 OAuth 回调端口已在使用中

3257</h3>3258</h3>

3258 3259

3259当您使用 OAuth 登录远程 MCP 服务器时，Claude Code 启动本地侦听器以接收登录回调。如果该侦听器需要的端口被另一个进程持有，登录会失败并显示此消息。这主要发生在通过 [`MCP_OAUTH_CALLBACK_PORT`](/docs/zh-CN/env-vars) 变量或 `--callback-port` 设置的[固定回调端口](/docs/zh-CN/mcp#use-a-fixed-oauth-callback-port)上，因为没有一个 Claude Code 会选择可用端口。3260当您使用 OAuth 登录远程 MCP 服务器时，Claude Code 启动本地侦听器以接收登录回调。如果该侦听器需要的端口被另一个进程持有，登录失败，显示此消息。这主要发生在[固定回调端口](/docs/zh-CN/mcp#use-a-fixed-oauth-callback-port)通过 [`MCP_OAUTH_CALLBACK_PORT`](/docs/zh-CN/env-vars) 变量或 `--callback-port` 设置时，因为没有一个 Claude Code 会选择可用端口。

3260 3261

3261```text theme={null}3262```text theme={null}

3262OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.3263OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.

3264 3265

3265在 Windows 上，建议的命令是 `netstat -ano | findstr :<port>`。3266在 Windows 上，建议的命令是 `netstat -ano | findstr :<port>`。

3266 3267

3267**要做什么：**3268**应该做什么：**

3268 3269

3269* 运行消息中的命令以找到持有端口的进程，并停止它或等待它完成3270* 运行消息中的命令以找到持有端口的进程，并停止它或等待它完成

3270* 如果另一个程序永久需要该端口，请向服务器注册不同的重定向 URI，并使用 `MCP_OAUTH_CALLBACK_PORT` 或 `--callback-port` 设置其端口，以及您使用的任何一个3271* 如果另一个程序永久需要该端口，请向服务器注册不同的重定向 URI，并使用 `MCP_OAUTH_CALLBACK_PORT` 或 `--callback-port` 设置其端口，以及您使用的任何一个

3271* 然后再次启动登录，例如通过在 `/mcp` 中选择服务器3272* 然后再次启动登录，例如通过在 `/mcp` 中选择服务器

3272 3273

3273<h3 id="no-available-ports-for-oauth-redirect">3274<h3 id="no-available-ports-for-oauth-redirect">

3274 没有可用的 OAuth 重定向端口3275 OAuth 重定向没有可用的端口

3275</h3>3276</h3>

3276 3277

3277当您使用[OAuth](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers) 登录远程 MCP 服务器时，Claude Code 启动本地侦听器以接收登录回调。当 Claude Code 无法为其绑定本地端口时，登录会失败并显示此消息。机器上的某些内容阻止它在 `127.0.0.1` 上侦听，例如安全软件或拒绝本地侦听器的沙箱策略。3278当您使用[OAuth](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers)登录远程 MCP 服务器时，Claude Code 启动本地侦听器以接收登录回调。当 Claude Code 无法为其绑定本地端口时，登录失败，显示此消息。机器上的某些内容阻止它在 `127.0.0.1` 上侦听，例如安全软件或拒绝本地侦听器的沙箱策略。

3278 3279

3279```text theme={null}3280```text theme={null}

3280No available ports for OAuth redirect3281No available ports for OAuth redirect

3281```3282```

3282 3283

3283在 v2.1.268 之前，Claude Code 没有回退到操作系统分配的端口，因此消息也出现在只有其自选端口无法绑定时。这可能发生在 Hyper-V 保留覆盖 Claude Code 选择的端口的端口范围的 Windows 主机上。3284在 v2.1.268 之前，Claude Code 不会回退到操作系统分配的端口，所以消息也会在仅其自选端口无法绑定时出现。这可能发生在 Hyper-V 保留覆盖 Claude Code 选择的端口的端口范围的 Windows 主机上。

3284 3285

3285**要做什么：**3286**应该做什么：**

3286 3287

3287* 检查安全软件或沙箱策略是否阻止进程在 `127.0.0.1` 上侦听，并允许 Claude Code 绑定本地端口3288* 检查安全软件或沙箱策略是否阻止进程在 `127.0.0.1` 上侦听，并允许 Claude Code 绑定本地端口

3288* 然后再次启动登录，例如通过在 `/mcp` 中选择服务器3289* 然后再次启动登录，例如通过在 `/mcp` 中选择服务器

3289 3290

3290<h3 id="security-review-fails-without-origin-head">3291<h3 id="security-review-fails-without-origin-head">

3291 /security-review 在没有 origin/HEAD 的情况下失败3292 /security-review 在没有 origin/HEAD 时失败

3292</h3>3293</h3>

3293 3294

3294[`/security-review`](/docs/zh-CN/commands#all-commands) 通过将您的分支与 `origin/HEAD` 进行比较来构建其审查上下文，这是记录您的 `origin` 远程上哪个分支是默认分支的本地 ref。当该 ref 不存在时，收集差异的 git 命令会失败，审查在启动前停止。3295[`/security-review`](/docs/zh-CN/commands#all-commands) 通过将您的分支与 `origin/HEAD` 进行比较来构建其审查上下文，这是记录您的 `origin` 远程上哪个分支是默认分支的本地 ref。当该 ref 不存在时，收集差异的 git 命令失败，审查在启动前停止。

3295 3296

3296```text theme={null}3297```text theme={null}

3297Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]3298Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]

3300'git <command> [<revision>...] -- [<file>...]'3301'git <command> [<revision>...] -- [<file>...]'

3301```3302```

3302 3303

3303消息可能引用 `git log` 或不同的 `git diff`。Git 仅在远程通告默认分支且您的获取 refspec 覆盖它时创建 `origin/HEAD`，这是完整 `git clone` 的远程提交所做的。该 ref 在这些设置中缺失：3304消息可能引用 `git log` 或不同的 `git diff`。Git 仅在远程通告默认分支且您的获取 refspec 覆盖它时创建 `origin/HEAD`，完整的远程克隆带有提交时会这样做。在这些设置中 ref 丢失：

3304 3305

3305* 单分支或 CI 检出，它获取太窄的 refspec3306* 单分支或 CI 检出，它获取太窄的 refspec

3306* 远程的服务器端 HEAD 指向没有人推送的分支3307* 远程服务器端 HEAD 指向没有人推送的分支

3307* 没有 `origin` 远程的存储库，或您从未获取的存储库3308* 没有 `origin` 远程的存储库，或您从未获取的存储库

3308 3309

3309Claude Code 为任何[注入动态上下文](/docs/zh-CN/skills#when-an-injected-command-fails)的 skill 显示相同的错误，失败的注入命令会中止该 skill 的调用。两个同级字符串在命令运行之前就会触发：3310Claude Code 为任何 [injects dynamic context](/docs/zh-CN/skills#when-an-injected-command-fails) 的 skill 显示相同的错误，失败的注入命令会中止该 skill 的调用。两个兄弟字符串在命令运行之前就会触发：

3310 3311

3311* `Shell command permission check failed for pattern "..."`：命令的权限检查不允许它。[注入命令的权限检查](/docs/zh-CN/skills#permission-checks-on-injected-commands)涵盖在每个权限模式中哪些结果中止以及如何使用 `allowed-tools` 预批准命令3312* `Shell command permission check failed for pattern "..."`：命令的权限检查不允许它。[Permission checks on injected commands](/docs/zh-CN/skills#permission-checks-on-injected-commands) 涵盖在每个权限模式中哪些结果会中止，以及如何使用 `allowed-tools` 预先批准命令

3312* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``：skill 的 frontmatter 在没有它的机器上要求 bash。安装 Git for Windows 或将 frontmatter 更改为 `shell: powershell`。请参阅[注入命令如何运行](/docs/zh-CN/skills#how-injected-commands-run)3313* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``：skill 的 frontmatter 在没有它的机器上要求 bash。安装 Git for Windows 或将 frontmatter 更改为 `shell: powershell`。请参阅[注入命令如何运行](/docs/zh-CN/skills#how-injected-commands-run)

3313 3314

3314**要做什么：**3315**应该做什么：**

3315 3316

3316* 通过命名您的远程的默认分支创建 ref：`git remote set-head origin <default-branch>`。只要本地跟踪 ref `origin/<default-branch>` 存在，这就有效。如果不存在，如在单分支克隆中，首先获取分支：运行 `git remote set-branches --add origin <branch>`，然后 `git fetch origin`，然后重新运行 set-head 命令。重新运行 `/security-review`。3317* 通过命名您的远程默认分支创建 ref：`git remote set-head origin <default-branch>`。只要本地跟踪 ref `origin/<default-branch>` 存在，这就有效。如果它不存在，如在单分支克隆中，首先获取分支：运行 `git remote set-branches --add origin <branch>`，然后 `git fetch origin`，然后重新运行 set-head 命令。重新运行 `/security-review`。

3317* 如果您不想命名分支，运行 `git fetch origin` 然后 `git remote set-head origin --auto`，它询问远程哪个分支是其默认分支。当远程不通告默认分支时它失败，错误为 `error: Cannot determine remote HEAD`，因为它是空的或其 HEAD 指向没有人推送的分支；改为显式命名分支。当您的克隆不获取该分支时它失败，错误为 `error: Not a valid ref`；首先按上述方式扩大 refspec。3318* 如果您不想命名分支，运行 `git fetch origin` 然后 `git remote set-head origin --auto`，它询问远程其默认分支是什么。当远程不通告默认分支时它失败，显示 `error: Cannot determine remote HEAD`，因为它是空的或其 HEAD 指向没有人推送的分支；改为显式命名分支。当您的克隆不获取该分支时它失败，显示 `error: Not a valid ref`；首先按上面的方式扩大 refspec。

3318* 如果存储库没有远程，使用 `git remote add origin <url>` 添加一个并在创建 ref 之前获取。如果远程是空的，首先使用 `git push -u origin HEAD` 推送您的分支，并在 set-head 命令中命名该分支；`origin/HEAD` 然后指向您刚推送的分支，因此 `/security-review` 看到空差异，直到分支与它分歧。3319* 如果存储库没有远程，使用 `git remote add origin <url>` 添加一个并在创建 ref 之前获取。如果远程是空的，首先使用 `git push -u origin HEAD` 推送您的分支，并在 set-head 命令中命名该分支；`origin/HEAD` 然后指向您刚推送的分支，所以 `/security-review` 看到空差异，直到分支与其分歧。

3319 3320

3320<h3 id="input-must-be-provided-when-using-print">3321<h3 id="input-must-be-provided-when-using-print">

3321 使用 --print 时必须提供输入3322 使用 `--print` 时必须提供输入

3322</h3>3323</h3>

3323 3324

3324裸 `claude` 需要 stdout 是终端才能启动交互 UI。当 stdout 被重定向或控制台不是真实终端时，例如 PowerShell ISE 和某些 IDE 输出窗格，`claude` 改为以[非交互](/docs/zh-CN/headless)方式运行。这与 `claude -p` 相同，它需要提示，因此消息命名 `--print`，即使您没有传递标志。在任何地方传递 `-p`/`--print` 不带提示且 stdin 上没有任何内容会产生相同的错误。3325裸 `claude` 需要 stdout 是终端才能启动交互 UI。当 stdout 被重定向，或控制台不是真实终端时，例如 PowerShell ISE 和某些 IDE 输出窗格，`claude` 改为以[非交互](/docs/zh-CN/headless)模式运行。这与 `claude -p` 相同，它需要提示，所以消息命名 `--print`，即使您没有传递标志。在任何地方传递 `-p`/`--print` 而不带提示且 stdin 上没有任何内容会产生相同的错误。

3325 3326

3326```text theme={null}3327```text theme={null}

3327Error: Input must be provided either through stdin or as a prompt argument when using --print3328Error: Input must be provided either through stdin or as a prompt argument when using --print

3328```3329```

3329 3330

3330**要做什么：**3331**应该做什么：**

3331 3332

3332* 对于交互使用，在真实终端中运行 `claude`：Windows Terminal 或 PowerShell 控制台而不是 ISE，以及您的 IDE 的集成终端而不是输出窗格3333* 对于交互使用，在真实终端中运行 `claude`：Windows Terminal 或 PowerShell 控制台而不是 ISE，以及您的 IDE 的集成终端而不是输出窗格

3333* 对于一次性使用，传递提示：`claude -p "your question"`，或使用 `echo "your question" | claude -p` 管道它3334* 对于一次性使用，传递提示：`claude -p "your question"`，或使用 `echo "your question" | claude -p` 管道它

3339在[非交互模式](/docs/zh-CN/headless)中，Claude Code 拒绝完全由空格、制表符或换行符组成的提示，而不是发送它，因为 API 拒绝没有可见文本的消息。您看到的消息取决于空白提示来自何处：3340在[非交互模式](/docs/zh-CN/headless)中，Claude Code 拒绝完全由空格、制表符或换行符组成的提示，而不是发送它，因为 API 拒绝没有可见文本的消息。您看到的消息取决于空白提示来自何处：

3340 3341

3341* **`claude -p` 的提示参数或管道 stdin**：`claude` 以 `Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print` 退出3342* **`claude -p` 的提示参数或管道 stdin**：`claude` 以 `Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print` 退出

3342* **提交给运行的 `--input-format stream-json` 或[Agent SDK](/docs/zh-CN/agent-sdk/overview) 会话的消息**：Claude Code 在没有调用模型的情况下结束轮次，会话保持可用。拒绝作为信息消息和轮次的结果文本到达：`Blank prompt — the message was only whitespace, so nothing was sent to the model.`3343* **提交给运行 `--input-format stream-json` 或 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 会话的消息**：Claude Code 在不调用模型的情况下结束轮次，会话保持可用。拒绝作为信息消息和轮次的结果文本到达：`Blank prompt — the message was only whitespace, so nothing was sent to the model.`

3343 3344

3344在 v2.1.229 之前，Claude Code 将仅空格的消息发送到 API，API 以 400 错误拒绝请求。3345在 v2.1.229 之前，Claude Code 将仅空格消息发送到 API，API 以 400 错误拒绝请求。

3345 3346

3346**要做什么：**3347**应该做什么：**

3347 3348

3348* 在提示中包含可见文本。如果脚本从变量或文件构建提示，请在调用 Claude Code 之前检查源是否不为空。3349* 在提示中包含可见文本。如果脚本从变量或文件构建提示，请在调用 Claude Code 之前检查源是否不为空。

3349 3350

3351 stream-json 输入在没有换行符的情况下超过 256M 个字符3352 stream-json 输入在没有换行符的情况下超过 256M 个字符

3352</h3>3353</h3>

3353 3354

3354您的程序在 stdin 上发送了超过 268,435,456 个字符，没有换行符到 `claude -p --input-format stream-json` 运行，因此 Claude Code 将此错误打印到 stderr 并以代码 1 退出，而不是缓冲更多输入。消息将该预算表示为 `256M`。在 v2.1.257 之前，Claude Code 无限制地缓冲此类输入，增长内存直到进程崩溃或被杀死。3355您的程序在没有换行符的情况下在 stdin 上发送了超过 268,435,456 个字符到 `claude -p --input-format stream-json` 运行，所以 Claude Code 将此错误打印到 stderr 并以代码 1 退出，而不是缓冲更多输入。消息将该预算表示为 `256M`。在 v2.1.257 之前，Claude Code 无限制地缓冲此类输入，增长内存直到进程崩溃或被杀死。

3355 3356

3356```text theme={null}3357```text theme={null}

3357Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.3358Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.

3358```3359```

3359 3360

3360这么长的输入没有换行符通常意味着生产者根本不是 stream-json 生产者，例如二进制文件或意外管道的纯日志输出。超过预算的单个消息会失败相同的检查。3361没有换行符的这么长的输入通常意味着生产者根本不是 stream-json 生产者，例如二进制文件或意外管道的纯日志输出。超过预算的单个消息失败相同的检查。

3361 3362

3362**要做什么：**3363**应该做什么：**

3363 3364

3364* 检查什么被管道到 stdin。使用 [`--input-format stream-json`](/docs/zh-CN/cli-reference#cli-flags)，每条消息必须是一个换行符终止的 JSON 行3365* 检查什么被管道到 stdin。使用 [`--input-format stream-json`](/docs/zh-CN/cli-reference#cli-flags)，每条消息必须是一个换行符终止的 JSON 行

3365* 要改为发送纯文本，请删除 `--input-format stream-json`；`claude -p` 默认从 stdin 读取纯文本提示3366* 要改为发送纯文本，请删除 `--input-format stream-json`；`claude -p` 默认从 stdin 读取纯文本提示

3368 未知命令3369 未知命令

3369</h3>3370</h3>

3370 3371

3371在交互式终端会话中，您提交了一个 `/` 名称，它与此会话中的任何命令都不匹配，因此 Claude Code 报告该名称而不是运行任何内容：3372在交互终端会话中，您提交了一个 `/` 名称，它与此会话中的任何命令都不匹配，所以 Claude Code 报告该名称而不是运行任何内容：

3372 3373

3373```text theme={null}3374```text theme={null}

3374Unknown command: /hepl. Did you mean /help?3375Unknown command: /hepl. Did you mean /help?

3376 3377

3377Claude Code 建议此会话中菜单列出的最接近的命令名称或别名。当没有接近的时候，消息在名称后结束。原因通常是以下之一：3378Claude Code 建议此会话中菜单列出的最接近的命令名称或别名。当没有接近的时候，消息在名称后结束。原因通常是以下之一：

3378 3379

3379* 打字错误，例如 `/hepl` 代替 `/help`。[命令菜单如何匹配您键入的内容](/docs/zh-CN/commands#how-the-command-menu-matches-what-you-type)涵盖在提交前选择接近匹配3380* 打字错误，例如 `/hepl` 代替 `/help`。[How the command menu matches what you type](/docs/zh-CN/commands#how-the-command-menu-matches-what-you-type) 涵盖在提交前选择接近的匹配

3380* 存在但在此会话中不可用的命令，因为不满足要求，例如您的平台、计划或身份验证方法。[`/web-setup`](/docs/zh-CN/web-quickstart#web-setup-shows-no-commands-match-or-unknown-command) 和 [`/schedule`](/docs/zh-CN/routines#schedule-returns-unknown-command) 的故障排除条目演示了两个常见情况。某些命令在您的组织的策略禁用它们时用自己的消息回答，例如[`Cloud sessions are disabled by your organization's policy`](#cloud-sessions-are-disabled-by-your-organizations-policy)3381* 存在但在此会话中不可用的命令，因为不满足要求，例如您的平台、计划或身份验证方法。[`/web-setup`](/docs/zh-CN/web-quickstart#web-setup-shows-no-commands-match-or-unknown-command) 和 [`/schedule`](/docs/zh-CN/routines#schedule-returns-unknown-command) 的故障排除条目演示两个常见情况。某些命令在您的组织的策略禁用它们时用自己的消息回答，例如 [`Cloud sessions are disabled by your organization's policy`](#cloud-sessions-are-disabled-by-your-organizations-policy)

3381* 来自此会话中未安装或未连接的[插件](/docs/zh-CN/plugins/overview)或 [MCP 服务器](/docs/zh-CN/mcp#use-mcp-prompts-as-commands)的命令3382* 来自[插件](/docs/zh-CN/plugins/overview)或[MCP 服务器](/docs/zh-CN/mcp#use-mcp-prompts-as-commands)的命令，在此会话中未安装或连接

3382 3383

3383Claude Code 仅在交互式终端会话中以这种方式回答不匹配的 `/` 名称。在所有其他会话中，它将提示作为普通消息发送给 Claude，并注意命令未运行以及 Claude 可以在会话中运行的命令列表。这些会话包括：3384Claude Code 仅在交互终端会话中以这种方式回答不匹配的 `/` 名称。在所有其他会话中，它将提示作为正常消息发送给 Claude，并注意命令未运行以及 Claude 可以在会话中运行的命令列表。这些会话包括：

3384 3385

3385* `-p` 运行3386* `-p` 运行

3386* [Agent SDK](/docs/zh-CN/agent-sdk/overview) 应用程序3387* [Agent SDK](/docs/zh-CN/agent-sdk/overview) 应用程序

3388* [VS Code 扩展](/docs/zh-CN/vs-code)的聊天面板3389* [VS Code 扩展](/docs/zh-CN/vs-code)的聊天面板

3389* [云会话](/docs/zh-CN/claude-code-on-the-web)和[例程](/docs/zh-CN/routines)3390* [云会话](/docs/zh-CN/claude-code-on-the-web)和[例程](/docs/zh-CN/routines)

3390 3391

3391对于无法在这些会话之一中运行的内置命令，Claude Code 仍然回答该命令不可用，而不是将其发送给 Claude。在 v2.1.274 之前，只有云会话和例程将不匹配的名称发送给 Claude。在 v2.1.273 之前，他们也回答 `Unknown command`。3392对于无法在这些会话之一中运行的内置命令，Claude Code 仍然回答命令不可用，而不是将其发送给 Claude。在 v2.1.274 之前，仅云会话和例程将不匹配的名称发送给 Claude。在 v2.1.273 之前，它们也回答 `Unknown command`。

3392 3393

3393Claude Code 不将每个以 `/` 开头的提示视为命令。当 `/` 后的第一个单词以标点符号开头时，它将提示作为普通消息发送给 Claude，例如打开 Lean 文档注释的 `/--`，或是路径，例如 `/var/log/syslog`。3394Claude Code 不将每个以 `/` 开头的提示视为命令。当 `/` 后的第一个单词以标点符号开头时，它将提示作为正常消息发送给 Claude，例如打开 Lean doc 注释的 `/--`，或是路径，例如 `/var/log/syslog`。

3394 3395

3395在 v2.1.236 之前，如果您在命令菜单列出您键入的名称的接近匹配时按 `Enter`，Claude Code 会运行该匹配，因此 `/hepl` 之类的打字错误会运行 `/help` 而不是产生此消息。3396在 v2.1.236 之前，如果您在命令菜单列出您键入的名称的接近匹配时按 `Enter`，Claude Code 会运行该匹配，所以 `/hepl` 之类的打字错误会运行 `/help` 而不是产生此消息。

3396 3397

3397**要做什么：**3398**应该做什么：**

3398 3399

3399* 运行建议的名称，或键入 `/` 后跟名称的一部分以查看此会话中可用的内容3400* 运行建议的名称，或键入 `/` 后跟名称的一部分以查看此会话中可用的内容

3400* 如果 Claude Code 将记录的命令报告为未知，请检查[命令参考](/docs/zh-CN/commands)中其行以了解它命名的要求3401* 如果 Claude Code 将记录的命令报告为未知，请检查[命令参考](/docs/zh-CN/commands)中的其行以了解它命名的要求

3401 3402

3402<h3 id="diff-is-too-large-for-ultrareview">3403<h3 id="diff-is-too-large-for-ultrareview">

3403 Diff 对于 ultrareview 来说太大3404 Diff 对于 ultrareview 来说太大了

3404</h3>3405</h3>

3405 3406

3406您的分支与基础分支之间的差异，包括未提交和暂存的更改，超过了 [ultrareview](/docs/zh-CN/ultrareview) 的大小限制，因此 `/code-review ultra` 和 `claude ultrareview` 子命令在云会话启动前拒绝审查。被拒绝的审查不使用免费运行，也不计费使用信用。消息命名生效的限制、您的差异大小以及贡献最多更改行的文件。在 v2.1.216 之前，消息仅显示原始差异统计。3407您的分支和基础分支之间的差异，包括未提交和暂存的更改，超过了 [ultrareview](/docs/zh-CN/ultrareview) 的大小限制，所以 `/code-review ultra` 和 `claude ultrareview` 子命令在云会话启动前拒绝审查。被拒绝的审查不使用免费运行，也不计费使用信用。消息命名有效的限制、您的差异大小以及贡献最多更改行的文件。在 v2.1.216 之前，消息仅显示原始差异统计。

3407 3408

3408```text theme={null}3409```text theme={null}

3409Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.3410Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.

3411 3412

3412审查拉取请求应用相同的限制；该形式的消息以 `PR #<N> is too large for ultrareview` 开头，并命名 PR 的文件和行数。3413审查拉取请求应用相同的限制；该形式的消息以 `PR #<N> is too large for ultrareview` 开头，并命名 PR 的文件和行数。

3413 3414

3414**要做什么：**3415**应该做什么：**

3415 3416

3416* 传递更接近您的工作的基础分支，例如 `/code-review ultra develop`，以便审查仅涵盖与该分支的差异3417* 传递更接近您的工作的基础分支，例如 `/code-review ultra develop`，以便审查仅涵盖与该分支的差异

3417* 将更改分成较小的分支并审查每一个。消息命名的文件贡献最多更改行，因此首先将这些移到它们自己的分支。3418* 将更改分成较小的分支并审查每一个。消息命名的文件贡献最多更改行，所以首先将这些移到它们自己的分支。

3418 3419

3419<h3 id="could-not-find-merge-base-with-the-base-branch">3420<h3 id="could-not-find-merge-base-with-the-base-branch">

3420 无法找到与基础分支的合并基础3421 无法找到与基础分支的合并基础

3421</h3>3422</h3>

3422 3423

3423`/code-review ultra` 和 `claude ultrareview` 子命令审查您的分支与基础分支之间的差异，这需要两者共享的提交。当 `git merge-base` 找不到时，Claude Code 在云会话启动前拒绝审查。在 Claude Code 可以验证完整的克隆上，至少有一个分支，它改为回退到[审查每个跟踪文件](/docs/zh-CN/ultrareview#diff-limits-and-fallbacks)而不是拒绝。您在基础分支根本找不到、Claude Code 无法验证您的克隆完整或在罕见的存储库中看到此拒绝，其中整个树差异不可能，例如 SHA-256 对象格式。3424`/code-review ultra` 和 `claude ultrareview` 子命令审查您的分支和基础分支之间的差异，这需要两者共享的提交。当 `git merge-base` 找不到时，Claude Code 在云会话启动前拒绝审查。在 Claude Code 可以验证完整的克隆上，至少有一个分支，它改为回退到[审查每个跟踪文件](/docs/zh-CN/ultrareview#diff-limits-and-fallbacks)而不是拒绝。您在基础分支根本找不到时、Claude Code 无法验证您的克隆完整时，或在罕见的存储库中看到此拒绝，其中整个树差异不可能，例如 SHA-256 对象格式。

3424 3425

3425```text theme={null}3426```text theme={null}

3426Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.3427Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.

3428 3429

3429第一句后的提示取决于 Claude Code 观察到的内容：3430第一句后的提示取决于 Claude Code 观察到的内容：

3430 3431

3431* **您没有传递基础分支**：Claude Code 与存储库的默认分支进行了比较，并建议显式传递您的基础，如上例所示3432* **您没有传递基础分支**：Claude Code 与存储库的默认分支进行了比较，并建议显式传递您的基础，如上面的示例

3432* **您传递了已在克隆中的基础分支**：提示读取 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``3433* **您传递的基础分支已在您的克隆中**：提示读取 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``

3433* **您传递了不在克隆中的基础分支**：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`。3434* **您传递的基础分支不在您的克隆中**：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`。

3434 3435

3435**要做什么：**3436**应该做什么：**

3436 3437

3437* 如果另一个分支是您的真实基础，显式传递它：`/code-review ultra <branch>`3438* 如果另一个分支是您的真实基础，显式传递它：`/code-review ultra <branch>`

3438* 如果您的克隆可能没有完整历史，运行 `git fetch --unshallow origin` 并重新运行审查3439* 如果您的克隆可能没有完整历史，运行 `git fetch --unshallow origin` 并重新运行审查

3441 您的检出没有分支3442 您的检出没有分支

3442</h3>3443</h3>

3443 3444

3444检出可以有提交但没有分支：如果您运行 `git init` 后跟 `git fetch <url>` 和 `git checkout FETCH_HEAD`，您会得到一个分离的 HEAD，没有 refs。Claude Code 将您的存储库打包为 git 包以上传以进行 [ultrareview](/docs/zh-CN/ultrareview)，它无法打包没有分支或其他 refs 的存储库，因此 `/code-review ultra` 和 `claude ultrareview` 子命令在云会话启动前拒绝审查。3445检出可以有提交但没有分支：如果您运行 `git init` 后跟 `git fetch <url>` 和 `git checkout FETCH_HEAD`，您会得到一个分离的 HEAD，没有 refs。Claude Code 将您的存储库打包为 git 包以上传它进行 [ultrareview](/docs/zh-CN/ultrareview)，它无法打包没有分支或其他 refs 的存储库，所以 `/code-review ultra` 和 `claude ultrareview` 子命令在云会话启动前拒绝审查。

3445 3446

3446```text theme={null}3447```text theme={null}

3447Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.3448Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.

3449 3450

3450在 v2.1.221 之前，Claude Code 尝试审查此检出中的每个跟踪文件，上传失败。3451在 v2.1.221 之前，Claude Code 尝试审查此检出中的每个跟踪文件，上传失败。

3451 3452

3452**要做什么：**3453**应该做什么：**

3453 3454

3454* 使用 `git checkout -b <name>` 在您当前的提交处创建分支，然后重新运行审查3455* 使用 `git checkout -b <name>` 在您当前的提交处创建分支，然后重新运行审查

3455 3456

3457 没有 GitHub 帐户连接到您的 Claude 帐户3458 没有 GitHub 帐户连接到您的 Claude 帐户

3458</h3>3459</h3>

3459 3460

3460您运行了 `/code-review ultra <PR#>` 或 `claude ultrareview <PR#>`，在创建云会话之前，Claude Code 询问服务器[连接到您的 Claude 帐户的 GitHub 帐户](/docs/zh-CN/ultrareview#review-a-pull-request)是否可以到达 PR 的存储库。没有帐户连接，或连接已过期，因此云克隆会失败，Claude Code 拒绝启动。Claude Code 不为被拒绝的启动花费免费运行或计费使用信用。3461您运行了 `/code-review ultra <PR#>` 或 `claude ultrareview <PR#>`，在创建云会话前 Claude Code 询问服务器[连接到您的 Claude 帐户的 GitHub 帐户](/docs/zh-CN/ultrareview#review-a-pull-request)是否可以到达 PR 的存储库。没有帐户连接，或连接已过期，所以云克隆会失败，Claude Code 拒绝启动。Claude Code 不为被拒绝的启动花费免费运行或计费使用信用。

3461 3462

3462```text theme={null}3463```text theme={null}

3463Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).3464Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).

3465 3466

3466当 [`/web-setup`](/docs/zh-CN/web-quickstart#connect-from-your-terminal) 在您的会话中不可用时，消息仅命名 claude.ai 链接。3467当 [`/web-setup`](/docs/zh-CN/web-quickstart#connect-from-your-terminal) 在您的会话中不可用时，消息仅命名 claude.ai 链接。

3467 3468

3468**要做什么：**3469**应该做什么：**

3469 3470

3470* 运行 `/web-setup` 将您的 GitHub CLI 登录连接到您的 Claude 帐户，或在 [claude.ai/connect-github](https://claude.ai/connect-github) 连接帐户3471* 运行 `/web-setup` 将您的 GitHub CLI 登录连接到您的 Claude 帐户，或在 [claude.ai/connect-github](https://claude.ai/connect-github) 连接帐户

3471* 连接后一分钟重新运行审查3472* 连接后一分钟重新运行审查

3476 您连接的 GitHub 帐户看不到存储库3477 您连接的 GitHub 帐户看不到存储库

3477</h3>3478</h3>

3478 3479

3479您运行了 `/code-review ultra <PR#>` 或 `claude ultrareview <PR#>`，[连接到您的 Claude 帐户的 GitHub 帐户](/docs/zh-CN/ultrareview#review-a-pull-request)无法读取 PR 的存储库，因此云克隆会失败，Claude Code 拒绝启动。Claude Code 不为被拒绝的启动花费免费运行或计费使用信用。3480您运行了 `/code-review ultra <PR#>` 或 `claude ultrareview <PR#>`，[连接到您的 Claude 帐户的 GitHub 帐户](/docs/zh-CN/ultrareview#review-a-pull-request)无法读取 PR 的存储库，所以云克隆会失败，Claude Code 拒绝启动。Claude Code 不为被拒绝的启动花费免费运行或计费使用信用。

3480 3481

3481```text theme={null}3482```text theme={null}

3482Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.3483Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.

3484 3485

3485当 [`/web-setup`](/docs/zh-CN/web-quickstart#connect-from-your-terminal) 在您的会话中不可用时，消息仅命名应用安装。3486当 [`/web-setup`](/docs/zh-CN/web-quickstart#connect-from-your-terminal) 在您的会话中不可用时，消息仅命名应用安装。

3486 3487

3487**要做什么：**3488**应该做什么：**

3488 3489

3489* 如果您的本地 `gh` CLI 可以读取存储库，运行 `/web-setup` 将该登录连接到您的 Claude 帐户3490* 如果您的本地 `gh` CLI 可以读取存储库，运行 `/web-setup` 将该登录连接到您的 Claude 帐户

3490* 更改后重新运行审查3491* 更改后重新运行审查

3492在 v2.1.248 之前，Claude Code 在启动前不检查这个。3493在 v2.1.248 之前，Claude Code 在启动前不检查这个。

3493 3494

3494<h3 id="the-github-app-preflight-failed-transiently">3495<h3 id="the-github-app-preflight-failed-transiently">

3495 GitHub 应用预检失败暂时3496 GitHub App 预检暂时失败

3496</h3>3497</h3>

3497 3498

3498您从本地存储库启动了[云会话](/docs/zh-CN/claude-code-on-the-web)，两个步骤一起失败。Claude Code 无法构建或上传您的存储库包。在上传之前，它检查了云服务是否可以从 GitHub 克隆存储库，而不是明确的答案，该检查以重试可能清除的错误结束，例如网络错误、超时或临时服务器错误。完整消息以停止包的内容开头，例如 `Could not upload repo bundle (<error>)`，并以预检句子结尾：3499您从本地存储库启动了[云会话](/docs/zh-CN/claude-code-on-the-web)，两个步骤一起失败了。Claude Code 无法构建或上传您的存储库包。在上传之前，它检查了云服务是否可以从 GitHub 克隆存储库，而不是明确的答案，该检查以重试可能清除的错误结束，例如网络错误、超时或临时服务器错误。完整消息以停止包的内容开头，例如 `Could not upload repo bundle (<error>)`，并以预检句子结尾：

3499 3500

3500```text theme={null}3501```text theme={null}

3501Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead3502Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead

3502```3503```

3503 3504

3504**要做什么：**3505**应该做什么：**

3505 3506

3506* 片刻后重新运行命令。当 GitHub 检查通过时，Claude Code 可以从 GitHub 克隆启动会话，因此失败的上传不再阻止启动3507* 片刻后重新运行命令。当 GitHub 检查通过时，Claude Code 可以从 GitHub 克隆启动会话，所以失败的上传不再阻止启动

3507* 如果重试继续失败，消息的开头命名了停止上传的内容。当该原因是您可以修复的内容时，修复它以便会话可以从您的本地存储库启动。3508* 如果重试继续失败，消息的开头命名停止上传的内容。当该原因是您可以修复的内容时，修复它以便会话可以从您的本地存储库启动

3508 3509

3509在 v2.1.251 之前，Claude Code 以 `Please set up GitHub on https://claude.ai/code` 结束消息，即使 GitHub 检查仅暂时失败，设置建议也无法清除暂时失败。3510在 v2.1.251 之前，Claude Code 以 `Please set up GitHub on https://claude.ai/code` 结束消息，即使 GitHub 检查仅暂时失败，设置建议无法清除暂时失败。

3510 3511

3511<h3 id="the-repository-upload-cant-follow-a-git-setting">3512<h3 id="the-repository-upload-cant-follow-a-git-setting">

3512 存储库上传无法遵循 git 设置3513 存储库上传无法遵循 git 设置

3513</h3>3514</h3>

3514 3515

3515您启动了[上传您的本地存储库的云会话](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github)或[分支的 ultrareview](/docs/zh-CN/ultrareview)，上传无法遵循决定哪些属性规则适用于您的文件的 git 设置之一。如果上传继续并错过了规则，git 在存储它之前转换的文件（例如清理过滤器加密的文件）可能会到达云端，就像它在磁盘上一样。Claude Code 拒绝上传，什么都不上传：3516您启动了[上传您的本地存储库的云会话](/docs/zh-CN/claude-code-on-the-web#send-local-repositories-without-github)，或分支的 [ultrareview](/docs/zh-CN/ultrareview)，上传无法遵循决定哪个属性规则适用于您的文件的 git 设置之一。如果上传继续并错过了规则，git 在存储它之前转换的文件，例如清理过滤器加密的文件，可能会到达云端，因为它在磁盘上。Claude Code 拒绝上传，什么都不上传：

3516 3517

3517```text theme={null}3518```text theme={null}

3518Not uploading this working tree: core.ignoreCase (which decides whether .gitattributes patterns match file names regardless of letter case) is set in <file>, and the upload cannot follow that setting, so a file git would change before storing it (to encrypt it, for example) could be uploaded as it is on disk. Move the core.ignoreCase line into this repository's .git/config or directly into your ~/.gitconfig, then retry.3519Not uploading this working tree: core.ignoreCase (which decides whether .gitattributes patterns match file names regardless of letter case) is set in <file>, and the upload cannot follow that setting, so a file git would change before storing it (to encrypt it, for example) could be uploaded as it is on disk. Move the core.ignoreCase line into this repository's .git/config or directly into your ~/.gitconfig, then retry.

3519```3520```

3520 3521

3521消息命名设置和它的设置位置，并以该情况的修复结尾。相同的拒绝出现在 `core.attributesFile` 和 `attr.tree` 中，每个都有自己的修复。3522消息命名设置和它的设置位置，并以该情况的修复结尾。相同的拒绝出现在 `core.attributesFile` 和 `attr.tree`，每个都有自己的修复。

3522 3523

3523消息可以命名您的 git 配置通过 `include` 或 `includeIf` 指令拉入的配置文件，即使该指令的条件不适用于此存储库。3524消息可以命名您的 git 配置通过 `include` 或 `includeIf` 指令拉入的配置文件，即使该指令的条件不适用于此存储库。

3524 3525

3525**要做什么：**3526**应该做什么：**

3526 3527

3527* 应用消息最后一句中的修复3528* 应用消息最后一句中的修复

3528 3529

3530 GitHub 未连接到您的 Claude 帐户3531 GitHub 未连接到您的 Claude 帐户

3531</h3>3532</h3>

3532 3533

3533您从本地存储库启动了[云会话](/docs/zh-CN/claude-code-on-the-web)，例如使用 `/autofix-pr`。没有 GitHub 帐户连接到您的 Claude 帐户，或连接已过期，因此 Claude Code 拒绝启动：3534您从本地存储库启动了[云会话](/docs/zh-CN/claude-code-on-the-web)，例如使用 `/autofix-pr`。没有 GitHub 帐户连接到您的 Claude 帐户，或连接已过期，所以 Claude Code 拒绝启动：

3534 3535

3535```text theme={null}3536```text theme={null}

3536GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github3537GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github

3538 3539

3539当您使用 [`/schedule`](/docs/zh-CN/routines) 创建例程时，相同的消息作为命名存储库的设置注释出现；注释不会阻止创建例程。3540当您使用 [`/schedule`](/docs/zh-CN/routines) 创建例程时，相同的消息作为命名存储库的设置注释出现；注释不会阻止创建例程。

3540 3541

3541**要做什么：**3542**应该做什么：**

3542 3543

3543* 运行 `/web-setup` 将您的 GitHub CLI 登录连接到您的 Claude 帐户，或在 [claude.ai/connect-github](https://claude.ai/connect-github) 连接帐户。请参阅 [GitHub 身份验证选项](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)以了解两者的区别。3544* 运行 `/web-setup` 将您的 GitHub CLI 登录连接到您的 Claude 帐户，或在 [claude.ai/connect-github](https://claude.ai/connect-github) 连接帐户。请参阅[GitHub 身份验证选项](/docs/zh-CN/claude-code-on-the-web#github-authentication-options)了解两者的区别。

3544* 连接后一分钟重新运行命令3545* 连接后一分钟重新运行命令

3545 3546

3546在 v2.1.268 之前，Claude Code 将此报告为 Claude GitHub 应用检查的临时失败，并建议重试或安装应用；两者都不连接 GitHub 帐户。3547在 v2.1.268 之前，Claude Code 将此报告为 Claude GitHub App 检查的临时失败，并建议重试或安装应用；两者都不连接 GitHub 帐户。

3547 3548

3548<h3 id="single-sign-on-authorization-needed">3549<h3 id="single-sign-on-authorization-needed">

3549 需要单点登录授权3550 需要单点登录授权

3550</h3>3551</h3>

3551 3552

3552您运行了 [`/install-github-app`](/docs/zh-CN/github-actions#quick-setup) 并选择了其组织强制执行 SAML 单点登录的存储库。在设置之前，Claude Code 使用 GitHub CLI 检查您对存储库的访问权限，GitHub 拒绝了该检查，因为您的 `gh` 令牌尚未为组织授权。向导显示警告和授权步骤：3553您运行了 [`/install-github-app`](/docs/zh-CN/github-actions#quick-setup)，并选择了其组织强制执行 SAML 单点登录的存储库。在设置之前，Claude Code 使用 GitHub CLI 检查您对存储库的访问权限，GitHub 拒绝了该检查，因为您的 `gh` 令牌还没有为组织授权。向导显示警告和授权步骤：

3553 3554

3554```text theme={null}3555```text theme={null}

3555Single sign-on authorization needed3556Single sign-on authorization needed

3556<owner>/<repo> belongs to an organization that enforces SAML single sign-on, and your GitHub CLI token isn't authorized for it yet.3557<owner>/<repo> belongs to an organization that enforces SAML single sign-on, and your GitHub CLI token isn't authorized for it yet.

3557```3558```

3558 3559

3559**要做什么：**3560**应该做什么：**

3560 3561

3561* 通过运行 `gh auth refresh -h github.com -s repo,workflow` 使用 `repo` 和 `workflow` 范围重新授权您的 GitHub CLI 登录，并在 GitHub 提示单点登录时授权组织3562* 通过运行 `gh auth refresh -h github.com -s repo,workflow` 使用 `repo` 和 `workflow` 范围重新授权您的 GitHub CLI 登录，并在 GitHub 提示单点登录时授权组织

3562* 如果您在 `GH_TOKEN` 中使用个人访问令牌进行身份验证，请打开 [github.com/settings/tokens](https://github.com/settings/tokens)，在令牌上选择**配置 SSO**，并授权组织3563* 如果您使用 `GH_TOKEN` 中的个人访问令牌进行身份验证，请打开 [github.com/settings/tokens](https://github.com/settings/tokens)，在令牌上选择**配置 SSO**，并授权组织

3563* 再次运行 `/install-github-app`3564* 再次运行 `/install-github-app`

3564 3565

3565在 v2.1.273 之前，Claude Code 为此条件显示 `Admin permissions required` 警告。3566在 v2.1.273 之前，Claude Code 为此条件显示 `Admin permissions required` 警告。

3568 无法恢复对话3569 无法恢复对话

3569</h3>3570</h3>

3570 3571

3571Claude Code 无法读取或处理您从 [`claude --resume` 选择器](/docs/zh-CN/sessions#use-the-session-picker)选择的会话的保存成绩单，因此它结束进程而不是在部分加载状态下继续。消息包括重试的命令：3572Claude Code 无法读取或处理您从 [`claude --resume` 选择器](/docs/zh-CN/sessions#use-the-session-picker)选择的会话的保存成绩单，所以它结束进程而不是在部分加载状态下继续。消息包括重试的命令：

3572 3573

3573```text theme={null}3574```text theme={null}

3574Failed to resume the conversation.3575Failed to resume the conversation.

3575Run claude --resume <session-id> to retry, or claude to start a new session.3576Run claude --resume <session-id> to retry, or claude to start a new session.

3576```3577```

3577 3578

3578Claude Code 在显示消息后以代码 1 退出。运行会话内的 `/resume` 选择器报告对话中的 `Failed to resume conversation`，您当前的会话保持运行。在 v2.1.216 之前，来自 `claude --resume` 选择器的失败恢复在 `Resuming conversation…` 微调器上无限期停留，而不是显示此消息。3579Claude Code 显示消息后以代码 1 退出。运行会话内的 `/resume` 选择器报告对话中的 `Failed to resume conversation`，您当前的会话保持运行。在 v2.1.216 之前，来自 `claude --resume` 选择器的失败恢复在 `Resuming conversation…` 微调器上无限期停留，而不是显示此消息。

3579 3580

3580**要做什么：**3581**应该做什么：**

3581 3582

3582* 运行 `claude --resume <session-id>`，其中 session-id 来自消息以重试3583* 使用消息中的会话 ID 运行 `claude --resume <session-id>` 重试

3583* 如果每次重试都以相同的方式失败，运行 `claude update` 并再次恢复。v2.1.275 之前的版本在保存的成绩单包含它们无法读取的条目时恢复失败。3584* 如果每次重试都以相同的方式失败，运行 `claude update` 并再次恢复。v2.1.275 之前的版本在保存的成绩单包含它们无法读取的条目时恢复失败。

3584* 如果重试再次失败，运行 `claude` 启动新会话3585* 如果重试再次失败，运行 `claude` 启动新会话

3585 3586

3586<h3 id="no-conversation-found-with-the-session-id">3587<h3 id="no-conversation-found-with-the-session-id">

3587 找不到具有会话 ID 的对话3588 未找到具有会话 ID 的对话

3588</h3>3589</h3>

3589 3590

3590您将会话 ID 传递给 `claude --resume <session-id>`，没有保存的成绩单与之匹配：3591您将会话 ID 传递给 `claude --resume <session-id>`，没有保存的成绩单与其匹配：

3591 3592

3592```text theme={null}3593```text theme={null}

3593No conversation found with session ID: <session-id>3594No conversation found with session ID: <session-id>

3594```3595```

3595 3596

3596Claude Code 在显示消息后以代码 1 退出。Claude Code [首先搜索当前项目，然后搜索此机器上的所有其他项目](/docs/zh-CN/sessions#resume-a-session)以查找 ID。在 v2.1.223 之前，查找在当前项目目录及其 git worktrees 处停止，因此从会话最后工作的目录恢复。3597Claude Code 显示消息后以代码 1 退出。Claude Code [首先搜索当前项目，然后搜索此机器上的所有其他项目](/docs/zh-CN/sessions#resume-a-session)以查找 ID。在 v2.1.223 之前，查找停止在当前项目目录及其 git worktrees，所以从会话最后工作的目录恢复。

3597 3598

3598常见原因：3599常见原因：

3599 3600

3600* **打字错误的 ID**：对于非交互式运行，ID 是 [`--output-format json` 输出](/docs/zh-CN/headless#get-structured-output)的 `session_id` 字段3601* **打字错误的 ID**：对于非交互运行，ID 是 [`--output-format json` 输出](/docs/zh-CN/headless#get-structured-output)的 `session_id` 字段

3601* **删除的成绩单**：Claude Code 在[保留期](/docs/zh-CN/sessions#where-transcripts-are-stored)后删除成绩单，默认 30 天，遵循[保留扫描规则](/docs/zh-CN/claude-directory#cleaned-up-automatically)3602* **删除的成绩单**：Claude Code 在[保留期](/docs/zh-CN/sessions#where-transcripts-are-stored)后删除成绩单，默认 30 天，遵循[保留扫描规则](/docs/zh-CN/claude-directory#cleaned-up-automatically)

3602* **不同的机器**：Claude Code 在本地存储成绩单，因此在运行会话的机器上恢复会话3603* **不同的机器**：Claude Code 在本地存储成绩单，所以在运行它的机器上恢复会话

3603* **重复副本**：如果您在 `~/.claude/projects` 下复制了项目目录，以便两个成绩单携带相同的 ID，Claude Code 报告此消息而不是任意恢复一个副本3604* **重复副本**：如果您在 `~/.claude/projects` 下复制了项目目录，所以两个成绩单携带相同的 ID，Claude Code 报告此消息而不是任意恢复一个副本

3604 3605

3605**要做什么：**3606**应该做什么：**

3606 3607

3607* 对于交互式会话，使用 `claude --resume` 打开[会话选择器](/docs/zh-CN/sessions#use-the-session-picker)，按 `Ctrl+A` 将其扩展到此机器上的每个项目，然后选择会话3608* 对于交互会话，使用 `claude --resume` 打开[会话选择器](/docs/zh-CN/sessions#use-the-session-picker)，按 `Ctrl+A` 将其扩展到此机器上的每个项目，然后选择会话

3608* 使用 `claude -p` 或 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 创建的会话不会出现在选择器中，因此重新检查 ID 与您的原始运行打印的 `session_id`3609* 使用 `claude -p` 或 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 创建的会话不会出现在选择器中，所以重新检查 ID 与您的原始运行打印的 `session_id`

3609 3610

3610<h3 id="windows-reported-an-error-ebadf">3611<h3 id="windows-reported-an-error-ebadf">

3611 Windows 报告了读取此会话的成绩单文件时的错误 (EBADF)3612 Windows 在 Claude Code 读取此会话的成绩单文件时报告了错误 (EBADF)

3612</h3>3613</h3>

3613 3614

3614您在 Windows 上恢复了一个会话，其保存的[成绩单文件](/docs/zh-CN/sessions#where-transcripts-are-stored)正常打开，读取它然后失败，错误为 EBADF。系统错误没有说为什么读取失败，因此消息建议可能的原因和要尝试的内容：3615您在 Windows 上恢复了会话，其保存的[成绩单文件](/docs/zh-CN/sessions#where-transcripts-are-stored)正常打开，读取它然后失败，显示系统错误 EBADF。系统错误没有说读取失败的原因，所以消息建议可能的原因和要尝试的内容：

3615 3616

3616```text theme={null}3617```text theme={null}

3617Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again.3618Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again.

3618```3619```

3619 3620

3620消息遵循命令自己的失败行，例如 `Failed to resume session <session-id>`。`claude --resume` 或 [`claude -p`](/docs/zh-CN/headless) 命令在显示它后以代码 1 退出。在会话内的 `/resume` 后，您当前的会话保持运行。3621消息遵循命令自己的失败行，例如 `Failed to resume session <session-id>`。`claude --resume` 或 [`claude -p`](/docs/zh-CN/headless) 命令显示它后以代码 1 退出。在会话内的 `/resume` 后，您当前的会话保持运行。

3621 3622

3622**要做什么：**3623**应该做什么：**

3623 3624

3624* 从扫描或拦截文件读取的软件（如安全、加密或端点管理工具）中排除保存会话成绩单的文件夹。成绩单默认位于 `%USERPROFILE%\.claude\projects` 下，或位于 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars) 命名的目录下3625* 从扫描或拦截文件读取的软件（例如安全、加密或端点管理工具）中排除保存会话成绩单的文件夹。成绩单默认位于 `%USERPROFILE%\.claude\projects` 下，或位于 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars) 命名的目录下

3625* 如果您无法添加排除项，改为将 Claude Code 添加到该软件的允许应用程序中3626* 如果您无法添加排除，请改为将 Claude Code 添加到该软件的允许应用程序

3626* 再次恢复会话3627* 再次恢复会话

3627 3628

3628在 v2.1.282 之前，失败没有解释：`claude --resume <session-id>` 在 `Failed to resume session <session-id>` 处结束，`-p` 运行仅打印系统错误文本，例如 `Failed to resume session: EBADF: bad file descriptor, read`。3629在 v2.1.282 之前，失败没有解释：`claude --resume <session-id>` 在 `Failed to resume session <session-id>` 处结束，`-p` 运行仅打印系统错误文本，例如 `Failed to resume session: EBADF: bad file descriptor, read`。

3631 无法在此会话中切换渲染器3632 无法在此会话中切换渲染器

3632</h3>3633</h3>

3633 3634

3634当您切换渲染器时，Claude Code 重新启动其进程。您在 Claude Code 拒绝重新启动的会话中运行了 [`/tui`](/docs/zh-CN/fullscreen#enable-fullscreen-rendering)，因此它不切换并保存任何内容。您看到的消息告诉您原因：3635当您切换渲染器时，Claude Code 重新启动其进程。您在 Claude Code 拒绝重新启动的会话中运行了 [`/tui`](/docs/zh-CN/fullscreen#enable-fullscreen-rendering)，所以它不切换并保存任何内容。您看到的消息告诉您原因：

3635 3636

3636* `Cannot switch renderers while work is running in the background`：您有在后台运行的工作，重新启动会放弃，例如后台 shell 或子代理。等待工作完成或使用 [`/tasks`](/docs/zh-CN/commands) 停止它，然后再次运行 `/tui fullscreen` 或 `/tui default`3637* `Cannot switch renderers while work is running in the background`：您有在后台运行的工作，重新启动会放弃，例如后台 shell 或子代理。等待工作完成或使用 [`/tasks`](/docs/zh-CN/commands) 停止它，然后再次运行 `/tui fullscreen` 或 `/tui default`

3637* `Cannot switch renderers in this session`：会话有 Claude Code 无法传递给重新启动的进程的限制。在 v2.1.234 之前，Claude Code 无论如何都会重新启动，重新启动的会话运行时没有它们3638* `Cannot switch renderers in this session`：会话有 Claude Code 无法传递给重新启动的进程的限制。在 v2.1.234 之前，Claude Code 无论如何都会重新启动，重新启动的会话运行时没有它们

3647* `launch flags: a custom system prompt, a tool allowlist, or restricted settings`：您使用 Claude Code 不传递回重新启动的进程的标志启动了会话。这些标志包括 [`--system-prompt`](/docs/zh-CN/cli-reference#cli-flags)、`--system-prompt-file`、`--append-system-prompt-file`、[`--tools`](/docs/zh-CN/cli-reference#cli-flags) 允许列表、[`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 和 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags)3648* `launch flags: a custom system prompt, a tool allowlist, or restricted settings`：您使用 Claude Code 不传递回重新启动的进程的标志启动了会话。这些标志包括 [`--system-prompt`](/docs/zh-CN/cli-reference#cli-flags)、`--system-prompt-file`、`--append-system-prompt-file`、[`--tools`](/docs/zh-CN/cli-reference#cli-flags) 允许列表、[`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 和 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags)

3648* `permission rules set for this session only`：来自钩子或 SDK 调用者的[权限更新](/docs/zh-CN/hooks#permission-update-entries)添加了带有 `session` 目标的拒绝或询问规则。会话范围的允许规则不会触发拒绝。重新启动会删除它们，Claude Code 改为再次提示3649* `permission rules set for this session only`：来自钩子或 SDK 调用者的[权限更新](/docs/zh-CN/hooks#permission-update-entries)添加了带有 `session` 目标的拒绝或询问规则。会话范围的允许规则不会触发拒绝。重新启动会删除它们，Claude Code 改为再次提示

3649* `ask-before-running rules with no command-line form`：来自钩子或 SDK 调用者的权限更新添加了询问规则以及 Claude Code 作为 `--allowed-tools` 和 `--disallowed-tools` 传递回的规则。不存在询问规则的标志3650* `ask-before-running rules with no command-line form`：来自钩子或 SDK 调用者的权限更新添加了询问规则以及 Claude Code 作为 `--allowed-tools` 和 `--disallowed-tools` 传递回的规则。不存在询问规则的标志

3650* `permission rules a command line cannot carry intact` 和 `added directories a command line cannot carry intact`：权限更新在会话中期添加了规则或目录路径。重新启动的进程的命令行无法将其文本作为相同值继承3651* `permission rules a command line cannot carry intact` 和 `added directories a command line cannot carry intact`：权限更新在会话中期添加了规则或目录路径。重新启动的进程的命令行无法将其文本作为相同的值继承

3651 3652

3652**要做什么：**3653**应该做什么：**

3653 3654

3654* 在没有这些限制的会话中，运行 `/tui fullscreen` 或 `/tui default` 切换回。Claude Code 在那里保存 [`tui` 设置](/docs/zh-CN/settings-reference#tui)3655* 在没有这些限制的会话中，运行 `/tui fullscreen`，或 `/tui default` 切换回。Claude Code 在那里保存 [`tui` 设置](/docs/zh-CN/settings-reference#tui)

3655 3656

3656<h3 id="couldnt-open-claude-desktop">3657<h3 id="couldnt-open-claude-desktop">

3657 无法打开 Claude Desktop3658 无法打开 Claude Desktop

3658</h3>3659</h3>

3659 3660

3660您运行了 [`/desktop`](/docs/zh-CN/desktop#coming-from-the-cli) 或其别名 `/app`，Claude Code 用来打开 Claude Desktop 的系统命令失败。会话保持在终端中。3661您在会话中运行了 [`/desktop`](/docs/zh-CN/desktop#coming-from-the-cli) 或其别名 `/app`，或在您的 shell 中运行了 [`claude --desktop`](/docs/zh-CN/cli-reference#cli-flags)，Claude Code 用来打开 Claude Desktop 的系统命令失败了。在 `/desktop` 后，会话保持在终端中；`claude --desktop` 打印消息而不带 `Error:` 前缀，并以状态 1 退出。

3662

3663括号中的文本命名失败的命令，带有其退出状态和其错误输出的第一行（如果它产生了）。在 macOS 上该命令是 `open`，如本例所示；在 Windows 上它是 `rundll32`：

3661 3664

3662```text theme={null}3665```text theme={null}

3663Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and run /desktop again.3666Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.

3664```3667```

3665 3668

3666**要做什么：**3669**应该做什么：**

3667 3670

3668* 自己打开 Claude Desktop，然后再次运行 `/desktop`3671* 自己打开 Claude Desktop，然后再次运行 `/desktop` 或 `claude --desktop`

3669* 要读取该命令的完整错误输出，使用 `/debug` 打开调试日志，再次运行 `/desktop`，并检查调试日志3672* 要读取失败命令的完整错误输出，使用 `/debug` 打开调试日志并再次运行 `/desktop`，或运行 `claude --desktop --debug-file <path>`，然后检查调试日志

3670 3673

3671在 v2.1.275 之前，消息是 `Failed to open Claude Desktop. Please try opening it manually.`，没有说什么失败。3674在 v2.1.285 之前，消息以 `Open Claude Desktop and run /desktop again.` 结尾。在 v2.1.275 之前，它是 `Failed to open Claude Desktop. Please try opening it manually.`，没有说什么失败了。

3672 3675

3673<h3 id="terminal-setup-left-your-zed-keymap-unchanged">3676<h3 id="terminal-setup-left-your-zed-keymap-unchanged">

3674 /terminal-setup 保持您的 Zed 快捷键不变3677 /terminal-setup 保持您的 Zed 快捷键不变

3675</h3>3678</h3>

3676 3679

3677您在 Zed 中运行了 [`/terminal-setup`](/docs/zh-CN/terminal-config#enter-multiline-prompts)，Claude Code 无法完成对您的 Zed `keymap.json` 的更新，因此它保持文件不变。3680您在 Zed 中运行了 [`/terminal-setup`](/docs/zh-CN/terminal-config#enter-multiline-prompts)，Claude Code 无法完成对您的 Zed `keymap.json` 的更新，所以它保持文件不变。

3678 3681

3679每条消息命名您的快捷键的路径，并以您自己添加的快捷键块结尾：3682每条消息命名您的快捷键的路径，并以您自己添加的快捷键块结尾：

3680 3683

3687消息的第一行命名原因：3690消息的第一行命名原因：

3688 3691

3689* `Couldn't read your Zed keymap, so it was left unchanged.`：Claude Code 无法读取文件，例如由于文件权限3692* `Couldn't read your Zed keymap, so it was left unchanged.`：Claude Code 无法读取文件，例如由于文件权限

3690* `Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.`：文件读取良好，但不解析为快捷键块数组，即使允许 `//` 注释和尾随逗号3693* `Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.`：文件读取正常但不解析为快捷键块数组，即使允许 `//` 注释和尾随逗号

3691* `Couldn't back up your Zed keymap; not modifying it.`：Claude Code 无法将文件复制到其旁边的 `.bak` 备份，因此它没有更改任何内容3694* `Couldn't back up your Zed keymap; not modifying it.`：Claude Code 无法将文件复制到其旁边的 `.bak` 备份，所以它没有更改任何内容

3692* `Couldn't update your Zed keymap, so it was left unchanged.`：合并的结果未验证为有效的快捷键，携带绑定，因此 Claude Code 丢弃它而不是写入。具有重复键的快捷键块可能导致这种情况3695* `Couldn't update your Zed keymap, so it was left unchanged.`：合并的结果没有验证为携带绑定的有效快捷键，所以 Claude Code 丢弃它而不是写入。具有重复键的快捷键块可能导致这种情况

3693 3696

3694**要做什么：**3697**应该做什么：**

3695 3698

3696* 将消息中的块复制到您的 `keymap.json` 中消息命名的路径处的顶级数组中3699* 将消息中的块复制到消息命名的路径处 `keymap.json` 中的顶级数组

3697* 对于 `isn't a readable list of keybindings`，修复语法错误，或使文件的顶级值成为数组，然后再次运行 `/terminal-setup`3700* 对于 `isn't a readable list of keybindings`，修复语法错误，或使文件的顶级值成为数组，然后再次运行 `/terminal-setup`

3698 3701

3699在 v2.1.247 之前，`/terminal-setup` 无法解析使用 `//` 注释或尾随逗号的 Zed 快捷键，它用仅自己的绑定替换整个文件，同时报告绑定已安装。要恢复较早版本替换的快捷键，请使用[输入多行提示](/docs/zh-CN/terminal-config#enter-multiline-prompts)下描述的 `.bak` 备份文件。3702在 v2.1.247 之前，`/terminal-setup` 无法解析使用 `//` 注释或尾随逗号的 Zed 快捷键，它用仅其自己的绑定替换整个文件，同时报告绑定已安装。要恢复较早版本替换的快捷键，请使用[输入多行提示](/docs/zh-CN/terminal-config#enter-multiline-prompts)下描述的 `.bak` 备份文件。

3700 3703

3701<h3 id="skill-usage-reports-are-not-available-on-this-connection">3704<h3 id="skill-usage-reports-are-not-available-on-this-connection">

3702 此连接上不提供 Skill 使用报告3705 Skill 使用报告在此连接上不可用

3703</h3>3706</h3>

3704 3707

3705您在[远程控制](/docs/zh-CN/remote-control)上运行了 [`/skill-doctor`](/docs/zh-CN/skills#find-unused-skills)，从您的手机或浏览器。Claude Code 不通过远程控制发送 skill 使用报告，而是用此消息回复：3708您在[远程控制](/docs/zh-CN/remote-control)上、从您的手机或浏览器运行了 [`/skill-doctor`](/docs/zh-CN/skills#find-unused-skills)。Claude Code 不通过远程控制发送 skill 使用报告，改为用此消息回复：

3706 3709

3707```text theme={null}3710```text theme={null}

3708Skill usage reports are not available on this connection.3711Skill usage reports are not available on this connection.

3709```3712```

3710 3713

3711**要做什么：**3714**应该做什么：**

3712 3715

3713* 在会话运行的机器上的终端中运行 `/skill-doctor`，或在那里运行 `claude -p "/skill-doctor"`3716* 在会话运行的机器上的终端中运行 `/skill-doctor`，或在那里运行 `claude -p "/skill-doctor"`

3714 3717

3716 无法通过远程控制选择自定义输出样式3719 无法通过远程控制选择自定义输出样式

3717</h3>3720</h3>

3718 3721

3719您从移动应用或网络通过[远程控制](/docs/zh-CN/remote-control)运行了 [`/output-style`](/docs/zh-CN/output-styles#change-your-output-style)，或命令在中继到会话的消息中到达。因为这样的轮次可能不来自帐户所有者，Claude Code 仅在其上列出和选择[内置样式](/docs/zh-CN/output-styles#built-in-output-styles)，并在命令列出样式或不识别您给出的名称时添加此通知。[自定义样式](/docs/zh-CN/output-styles#create-a-custom-output-style)名称获得与不存在的名称相同的回复：3722您从移动应用或网络通过[远程控制](/docs/zh-CN/remote-control)运行了 [`/output-style`](/docs/zh-CN/output-styles#change-your-output-style)，或命令在中继到会话的消息中到达。因为此类轮次可能不来自帐户所有者，Claude Code 仅在其上列出并选择[内置样式](/docs/zh-CN/output-styles#built-in-output-styles)，并在命令列出样式或不识别您给出的名称时添加此通知。[自定义样式](/docs/zh-CN/output-styles#create-a-custom-output-style)名称获得与不存在的名称相同的回复：

3720 3723

3721```text theme={null}3724```text theme={null}

3722Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.3725Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.

3723```3726```

3724 3727

3725**要做什么：**3728**应该做什么：**

3726 3729

3727* 选择内置样式，例如 `/output-style concise`3730* 选择内置样式，例如 `/output-style concise`

3728* 要使用自定义样式，在项目的 `.claude/settings.local.json` 中设置 [`outputStyle`](/docs/zh-CN/settings-reference#outputstyle)，或在会话自己的终端中运行 `/output-style <style>`（如果它有的话）3731* 要使用自定义样式，在项目的 `.claude/settings.local.json` 中设置 [`outputStyle`](/docs/zh-CN/settings-reference#outputstyle)，或在会话自己的终端中运行 `/output-style <style>`（如果它有的话）

3731 输出样式保存到此会话不加载的本地设置3734 输出样式保存到此会话不加载的本地设置

3732</h3>3735</h3>

3733 3736

3734您尝试在设置源排除 `local` 的会话中使用 `/output-style <style>` 或 `/config outputStyle=<style>` 切换[输出样式](/docs/zh-CN/output-styles)。示例是 [`settingSources`](/docs/zh-CN/agent-sdk/typescript#options) 遗漏 `"local"` 的 [Agent SDK](/docs/zh-CN/agent-sdk/typescript) 会话和使用遗漏 `local` 的 [`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 值启动的 CLI 会话。两个命令都将样式保存到 `.claude/settings.local.json`，这样的会话永远不会读回，因此 Claude Code 拒绝而不是写入没有效果的设置：3737您尝试在其设置源排除 `local` 的会话中使用 `/output-style <style>` 或 `/config outputStyle=<style>` 切换[输出样式](/docs/zh-CN/output-styles)。示例是 [`settingSources`](/docs/zh-CN/agent-sdk/typescript#options) 留出 `"local"` 的 [Agent SDK](/docs/zh-CN/agent-sdk/typescript) 会话，以及使用 [`--setting-sources`](/docs/zh-CN/cli-reference#cli-flags) 值启动的 CLI 会话，该值留出 `local`。两个命令都将样式保存到 `.claude/settings.local.json`，此类会话从不读取回的文件，所以 Claude Code 拒绝而不是写入无效的设置：

3735 3738

3736```text theme={null}3739```text theme={null}

3737Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load, so the style can't be changed here.3740Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load, so the style can't be changed here.

3738```3741```

3739 3742

3740**要做什么：**3743**应该做什么：**

3741 3744

3742* 将 `local` 添加到会话的设置源并再次切换3745* 将 `local` 添加到会话的设置源并再次切换

3743* 在会话确实加载的设置文件中设置 [`outputStyle`](/docs/zh-CN/settings-reference#outputstyle) 键，例如项目中的 `.claude/settings.json` 或 `~/.claude/settings.json`。在 TypeScript SDK 中，改为在内联 `settings` 对象内设置 `outputStyle`；请参阅[激活输出样式](/docs/zh-CN/agent-sdk/modifying-system-prompts#activate-an-output-style)3746* 在会话确实加载的设置文件中设置 [`outputStyle`](/docs/zh-CN/settings-reference#outputstyle) 键，例如项目中的 `.claude/settings.json` 或 `~/.claude/settings.json`。在 TypeScript SDK 中，改为在内联 `settings` 对象内设置 `outputStyle`；请参阅[激活输出样式](/docs/zh-CN/agent-sdk/modifying-system-prompts#activate-an-output-style)

3744 3747

3745<h2 id="plugin-errors">3748<h2 id="plugin-errors">

3746 Plugin 错误3749 插件错误

3747</h2>3750</h2>

3748 3751

3749这些错误来自 [plugin](/docs/zh-CN/plugins/overview) 和 [marketplace](/docs/zh-CN/plugins/overview) 配置。对于不产生此页面上任何消息的 plugin 问题，例如无法加载的 marketplace URL 或已安装但不显示的 plugin，请参阅 [Plugin 故障排除](/docs/zh-CN/plugins/troubleshooting)。3752这些错误来自[插件](/docs/zh-CN/plugins/overview)和[marketplace](/docs/zh-CN/plugins/overview)配置。对于不会产生此页面上的消息之一的插件问题，例如无法加载的 marketplace URL 或已安装但未显示的插件，请参阅[插件故障排除](/docs/zh-CN/plugins/troubleshooting)。

3750 3753

3751<h3 id="plugin-eval-is-currently-in-early-access">3754<h3 id="plugin-eval-is-currently-in-early-access">

3752 plugin eval 目前处于早期访问阶段3755 plugin eval 目前处于早期访问阶段

3753</h3>3756</h3>

3754 3757

3755您运行了 [`claude plugin eval`](/docs/zh-CN/plugin-evals) 或 `claude plugin eval init`，它在执行任何操作之前以退出代码 1 和以下消息之一退出：3758您运行了[`claude plugin eval`](/docs/zh-CN/plugin-evals)或`claude plugin eval init`，它在执行任何操作之前以退出代码 1 和以下消息之一退出：

3756 3759

3757```text theme={null}3760```text theme={null}

3758`plugin eval` is currently in early access3761`plugin eval` is currently in early access

3762`plugin eval` is currently unavailable3765`plugin eval` is currently unavailable

3763```3766```

3764 3767

3765第一条消息表示您的构建版本早于 v2.1.269，这是该命令正式发布的第一个版本。第二条消息表示 Anthropic 已在服务器端关闭该命令；您的机器上没有任何东西可以将其重新打开。3768第一条消息表示您的构建版本早于 v2.1.269，这是该命令正式发布的第一个版本。第二条消息表示 Anthropic 已在服务器端关闭了该命令；您的机器上没有任何东西可以将其重新打开。

3766 3769

3767**要做什么：**3770**要做什么：**

3768 3771

3769* 运行 `claude --version`，然后运行 `claude update`，并在新会话中再次运行该命令。请参阅 [plugin evals 的要求](/docs/zh-CN/plugin-evals#requirements)3772* 运行`claude --version`，然后运行`claude update`，并在新会话中再次运行该命令。请参阅[插件 evals 的要求](/docs/zh-CN/plugin-evals#requirements)

3770* 如果您在当前构建上看到第二条消息，请在另一次 `claude update` 后稍后重试3773* 如果您在当前构建上看到第二条消息，请在另一次`claude update`后稍后重试

3771 3774

3772<h3 id="marketplace-is-registered-from-an-untrusted-source">3775<h3 id="marketplace-is-registered-from-an-untrusted-source">

3773 Marketplace 从不受信任的源注册3776 Marketplace 从不受信任的来源注册

3774</h3>3777</h3>

3775 3778

3776marketplace 注册的名称是 [为官方 Anthropic marketplaces 保留的](/docs/zh-CN/plugins/marketplace-reference#marketplace-file)，但其注册源不是 `anthropics` GitHub 存储库。Claude Code 每次加载或刷新 marketplace 时都会重新检查保留的名称，因此 marketplace 和从中安装的 plugin 停止加载。在 v2.1.205 之前，仅在添加 marketplace 时检查名称，因此在其名称被保留之前注册的条目继续加载。3779marketplace 注册在一个名称下，该名称是[为官方 Anthropic marketplaces 保留的](/docs/zh-CN/plugins/marketplace-reference#marketplace-file)，但其注册来源不是`anthropics` GitHub 存储库。Claude Code 每次加载或刷新 marketplace 时都会重新检查保留的名称，因此 marketplace 及从中安装的插件停止加载。在 v2.1.205 之前，在其名称被保留之前注册的条目继续加载。

3777 3780

3778```text theme={null}3781```text theme={null}

3779Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.3782Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.

3780```3783```

3781 3784

3782对于源不是 GitHub 存储库或 Git URL（例如本地目录）的 marketplace，中间句子改为 `can only be used with GitHub sources from the 'anthropics' organization`。`claude plugin marketplace add` 运行相同的检查，并以 `Failed to add marketplace:` 后跟相同的保留名称句子拒绝保留的名称。3785对于来源不是 GitHub 存储库或 Git URL 的 marketplace，例如本地目录，中间句子改为`can only be used with GitHub sources from the 'anthropics' organization`。`claude plugin marketplace add`运行相同的检查，并拒绝保留的名称，返回`Failed to add marketplace:`后跟相同的保留名称句子。

3783 3786

3784**要做什么：**3787**要做什么：**

3785 3788

3786* 如果 marketplace 已注册，运行 `claude plugin marketplace remove <name>`，然后从官方 `github.com/anthropics` 存储库重新添加它3789* 如果 marketplace 已注册，运行`claude plugin marketplace remove <name>`，然后从官方`github.com/anthropics`存储库重新添加它

3787* 如果您发布了在名称被保留之前使用该名称的第三方 marketplace，请重命名它并要求用户从您的源重新添加它3790* 如果您发布了在名称被保留之前使用该名称的第三方 marketplace，请重命名它并要求用户从您的来源重新添加它

3788* 请参阅 [Marketplace schema](/docs/zh-CN/plugins/marketplace-reference#marketplace-file) 下的保留名称列表3791* 请参阅[Marketplace schema](/docs/zh-CN/plugins/marketplace-reference#marketplace-file)下的保留名称列表

3789 3792

3790<h3 id="marketplace-name-is-another-spelling-of-a-reserved-name">3793<h3 id="marketplace-name-is-another-spelling-of-a-reserved-name">

3791 Marketplace 名称是保留名称的另一种拼写3794 Marketplace 名称是保留名称的另一种拼写

3792</h3>3795</h3>

3793 3796

3794marketplace 的名称本身不是保留名称，但 Claude Code 将其视为另一种拼写。[保留的 marketplace 名称](/docs/zh-CN/plugins/marketplace-reference#reserved-name-spellings) 列出了哪些拼写算作保留名称。Claude Code 在您添加 marketplace 时拒绝这样的名称：3797marketplace 的名称本身不是保留名称，但 Claude Code 将其视为保留名称的另一种拼写。[保留名称](/docs/zh-CN/plugins/marketplace-reference#reserved-name-spellings)列出了哪些拼写算作保留名称。当您添加 marketplace 时，Claude Code 拒绝这样的名称：

3795 3798

3796```text theme={null}3799```text theme={null}

3797Failed to add marketplace: "claude.code.plugins" is another spelling of "claude-code-plugins", a reserved marketplace name.3800Failed to add marketplace: "claude.code.plugins" is another spelling of "claude-code-plugins", a reserved marketplace name.

3798```3801```

3799 3802

3800当 marketplace 已在这样的名称下注册时，其条目停止加载，`/plugin`、`claude plugin install` 和 `claude plugin update` 警告：3803当 marketplace 已在这样的名称下注册时，其条目停止加载，`/plugin`、`claude plugin install`和`claude plugin update`警告：

3801 3804

3802```text wrap theme={null}3805```text wrap theme={null}

3803known_marketplaces.json has an entry named "claude.code.plugins", another spelling of the reserved marketplace name "claude-code-plugins", so it is ignored. Remove it with: claude plugin marketplace remove claude.code.plugins3806known_marketplaces.json has an entry named "claude.code.plugins", another spelling of the reserved marketplace name "claude-code-plugins", so it is ignored. Remove it with: claude plugin marketplace remove claude.code.plugins

3804```3807```

3805 3808

3806当名称需要 shell 引用时，添加时的拒绝读作 `This marketplace's name is another spelling of "<reserved>", a reserved marketplace name. It is not exactly the reserved name it appears to be.`3809当名称需要 shell 引用时，添加时的拒绝读作`This marketplace's name is another spelling of "<reserved>", a reserved marketplace name. It is not exactly the reserved name it appears to be.`

3807 3810

3808**要做什么：**3811**要做什么：**

3809 3812

3810* 将 marketplace 重命名为不拼写保留名称的名称并重新添加它3813* 将 marketplace 重命名为不拼写保留名称的名称，然后重新添加它

3811* 对于被忽略的条目警告，运行它给出的 `claude plugin marketplace remove` 命令，或从 `~/.claude/plugins/known_marketplaces.json` 中删除该条目3814* 对于忽略的条目警告，运行它给出的`claude plugin marketplace remove`命令，或从`~/.claude/plugins/known_marketplaces.json`中删除该条目

3812 3815

3813<h3 id="claude-code-refuses-the-marketplace-name">3816<h3 id="claude-code-refuses-the-marketplace-name">

3814 Claude Code 拒绝 marketplace 名称3817 Claude Code 拒绝 marketplace 名称

3815</h3>3818</h3>

3816 3819

3817已注册的 marketplace 的名称 [冒充官方 Anthropic marketplace](/docs/zh-CN/plugins/marketplace-reference#reserved-names)，根据该部分列出的规则。3820已注册的 marketplace 的名称[冒充官方 Anthropic marketplace](/docs/zh-CN/plugins/marketplace-reference#reserved-names)，违反了该部分列出的规则。

3818 3821

3819如果 marketplace 在这样的名称下注册时检查阻止了它，marketplace 和从中安装的 plugin 停止加载，因为 Claude Code 每次读取 marketplace 的目录时都会检查名称。当名称模仿官方名称时，`claude plugin list` 和 `/plugin` **Errors** 选项卡报告每个受影响的 plugin，消息开头为：3822如果 marketplace 在这样的名称下注册时检查阻止了它，marketplace 及从中安装的插件停止加载，因为 Claude Code 每次读取 marketplace 的目录时都会检查名称。当名称模仿官方名称时，`claude plugin list`和`/plugin`**Errors**选项卡报告每个受影响的插件，消息开头为：

3820 3823

3821```text theme={null}3824```text theme={null}

3822Claude Code refuses the marketplace name "anthropic-plugins-v2"3825Claude Code refuses the marketplace name "anthropic-plugins-v2"

3823```3826```

3824 3827

3825对于模仿名称，marketplace 自己的错误读作 `Claude Code refuses this marketplace's name: it looks like one of Anthropic's own`。`claude plugin marketplace add` 拒绝任何冒充名称，消息为 `Marketplace name impersonates an official Anthropic/Claude marketplace`。3828对于模仿名称，marketplace 自己的错误读作`Claude Code refuses this marketplace's name: it looks like one of Anthropic's own`。`claude plugin marketplace add`拒绝任何冒充名称，返回`Marketplace name impersonates an official Anthropic/Claude marketplace`。

3826 3829

3827在 v2.1.282 之前，`claude plugin list` 和 `/plugin` 报告模仿名称的 plugin 也加载失败，没有将 marketplace 的名称命名为原因。3830在 v2.1.282 之前，`claude plugin list`和`/plugin`报告模仿名称的插件加载失败，但没有将 marketplace 的名称命名为原因。

3828 3831

3829**要做什么：**3832**要做什么：**

3830 3833

3831* 运行 `claude plugin marketplace remove <name>`。这也会卸载从 marketplace 安装的 plugin 并删除其保存的数据3834* 运行`claude plugin marketplace remove <name>`。这也会卸载从 marketplace 安装的插件并删除其保存的数据

3832* 要保留 marketplace，请等待其维护者重命名它，然后运行 `claude plugin marketplace update <name>`3835* 要保留 marketplace，请等待其维护者重命名它，然后运行`claude plugin marketplace update <name>`

3833* 如果您发布 marketplace，在您的 `marketplace.json` 中重命名它；用户随后更新 marketplace 而不是删除它3836* 如果您发布 marketplace，在您的`marketplace.json`中重命名它；用户随后更新 marketplace 而不是删除它

3834 3837

3835<h3 id="marketplace-is-already-added-from-a-different-source">3838<h3 id="marketplace-is-already-added-from-a-different-source">

3836 Marketplace 已从不同的源添加3839 Marketplace 已从不同的来源添加

3837</h3>3840</h3>

3838 3841

3839您通过 [`/plugin install <plugin> --marketplace <source>`](/docs/zh-CN/plugins/install#add-a-marketplace-and-install-in-one-command) 确认添加了 marketplace，而 Claude Code 从该源获取的目录将自身命名为与您已从不同源添加的 marketplace 相同的名称。Claude Code 保留现有的 marketplace 而不是替换它，plugin 未被安装。3842您通过[`/plugin install <plugin> --marketplace <source>`](/docs/zh-CN/plugins/install#add-a-marketplace-and-install-in-one-command)确认添加了 marketplace，Claude Code 从该来源获取的目录将自己命名为与您已从不同来源添加的 marketplace 相同。Claude Code 保留现有的 marketplace 而不是替换它，插件未安装。

3840 3843

3841```text theme={null}3844```text theme={null}

3842Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.3845Marketplace "acme-tools" is already added from a different source (github:acme/plugins). To use this source instead, remove that marketplace first with /plugin marketplace remove acme-tools.

3844 3847

3845**要做什么：**3848**要做什么：**

3846 3849

3847* 如果您已添加的 marketplace 是您想要的，请按名称从中安装：`/plugin install <plugin>@<name>`3850* 如果您已添加的 marketplace 是您想要的，按名称从中安装：`/plugin install <plugin>@<name>`

3848* 要切换到新源，运行 `/plugin marketplace remove <name>`，然后重试安装3851* 要切换到新来源，运行`/plugin marketplace remove <name>`，然后重试安装

3849 3852

3850<h3 id="plugin-command-references-user-config">3853<h3 id="plugin-command-references-user-config">

3851 Plugin 命令在 shell 命令中引用 user\_config3854 插件命令在 shell 命令中引用 user\_config

3852</h3>3855</h3>

3853 3856

3854一个 plugin hook、[monitor](/docs/zh-CN/plugins/components#monitors) 或 MCP [`headersHelper`](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication) 命令引用了 `${user_config.KEY}` [plugin 选项](/docs/zh-CN/plugins/manifest-reference#user-configuration)，而替换后的字符串将被传递到 shell。配置的值包含 `$(...)` 、反引号或 `;` 会在那里作为代码运行，因此 Claude Code 拒绝启动该组件而不是替换该值。检查在命令模板上运行，因此即使尚未配置任何值，错误也会出现。在 v2.1.207 之前，该值被替换到 shell 命令中。3857插件 hook、[monitor](/docs/zh-CN/plugins/components#monitors)或 MCP [`headersHelper`](/docs/zh-CN/mcp#use-dynamic-headers-for-custom-authentication)命令引用`${user_config.KEY}` [插件选项](/docs/zh-CN/plugins/manifest-reference#user-configuration)，替换后的字符串将被传递到 shell。配置的值包含`$(...)` 、反引号或`;`会在那里作为代码运行，因此 Claude Code 拒绝启动该组件而不是替换该值。检查在命令模板上运行，因此即使尚未配置任何值，错误也会出现。在 v2.1.207 之前，该值被替换到 shell 命令中。

3855 3858

3856措辞取决于哪个表面引用了该选项。shell 形式的 hook 报告：3859措辞取决于哪个界面引用了该选项。shell 形式的 hook 报告：

3857 3860

3858```text theme={null}3861```text theme={null}

3859Hook from plugin formatter@acme-tools references ${user_config.*} in a shell-form command. The substituted value would be re-parsed by the shell. Use exec form instead — {"command": "<executable>", "args": ["${user_config.KEY}", ...]} — or read $CLAUDE_PLUGIN_OPTION_<KEY> from the hook's environment. Command: ./scripts/notify.sh ${user_config.webhook_url}3862Hook from plugin formatter@acme-tools references ${user_config.*} in a shell-form command. The substituted value would be re-parsed by the shell. Use exec form instead — {"command": "<executable>", "args": ["${user_config.KEY}", ...]} — or read $CLAUDE_PLUGIN_OPTION_<KEY> from the hook's environment. Command: ./scripts/notify.sh ${user_config.webhook_url}

3865Monitor "deploy-status" from plugin deploy-tools references ${user_config.*} in its command. The substituted value would be passed to a shell. Monitor commands cannot safely reference ${user_config.*}; have the monitor script read the value from a config file or prompt instead.3868Monitor "deploy-status" from plugin deploy-tools references ${user_config.*} in its command. The substituted value would be passed to a shell. Monitor commands cannot safely reference ${user_config.*}; have the monitor script read the value from a config file or prompt instead.

3866```3869```

3867 3870

3868MCP `headersHelper` 报告：3871MCP `headersHelper`报告：

3869 3872

3870```text theme={null}3873```text theme={null}

3871headersHelper for MCP server 'internal-api' references ${user_config.*}. The substituted value would be passed to a shell; read the value inside the helper script instead (e.g. from an env var set in the server's "env" block).3874headersHelper for MCP server 'internal-api' references ${user_config.*}. The substituted value would be passed to a shell; read the value inside the helper script instead (e.g. from an env var set in the server's "env" block).

3873 3876

3874**要做什么：**3877**要做什么：**

3875 3878

3876* 对于 hook，添加 `args` 数组以便它在 [exec 形式](/docs/zh-CN/hooks#exec-form-and-shell-form) 中运行，其中每个 `${user_config.KEY}` 成为一个参数，中间没有 shell。或删除引用并读取脚本内的 `$CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量3879* 对于 hook，添加`args`数组使其以[exec 形式](/docs/zh-CN/hooks#exec-form-and-shell-form)运行，其中每个`${user_config.KEY}`成为一个参数，中间没有 shell。或删除引用并读取脚本内的`$CLAUDE_PLUGIN_OPTION_<KEY>`环境变量

3877* 对于 monitor，删除引用并让 monitor 脚本从配置文件读取该值3880* 对于 monitor，删除引用并让 monitor 脚本从配置文件读取该值

3878* 对于 `headersHelper`，将 `${user_config.KEY}` 移到服务器的 `headers` 字段中，该字段不会被 shell 解析，或在 helper 脚本内读取该值3881* 对于`headersHelper`，将`${user_config.KEY}`移到服务器的`headers`字段中，该字段不被 shell 解析，或在 helper 脚本内读取该值

3879 3882

3880<h3 id="plugin-archive-integrity-check-failed">3883<h3 id="plugin-archive-integrity-check-failed">

3881 Plugin 存档完整性检查失败3884 插件存档完整性检查失败

3882</h3>3885</h3>

3883 3886

3884plugin 的 marketplace 条目使用带有 `sha256` pin 的 [`archive` 源](/docs/zh-CN/plugins/marketplace-reference#archive-plugin-source)，而下载文件的摘要与 pin 不匹配。Claude Code 拒绝安装，因此 plugin 缓存中没有任何更改。不匹配有三个可能的原因：3887插件的 marketplace 条目使用带有`sha256`引脚的[`archive`源](/docs/zh-CN/plugins/marketplace-reference#archive-plugin-source)，下载文件的摘要与引脚不匹配。Claude Code 拒绝安装，因此插件缓存中没有任何更改。不匹配有三个可能的原因：

3885 3888

3886* 作者计算 pin 后，URL 处的文件已更改3889* 作者计算引脚后 URL 处的文件已更改

3887* 作者在 marketplace 条目中输入了错误的摘要3890* 作者在 marketplace 条目中输入了错误的摘要

3888* URL 提供的文件与作者 pin 的文件不同3891* URL 提供的文件与作者引脚的文件不同

3889 3892

3890```text theme={null}3893```text theme={null}

3891Plugin archive integrity check failed for https://artifacts.example.com/claude-plugins/my-plugin.zip: expected sha256 6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1, got ac52220c0914ef8ca6a602e4a7362f88d30fb021110f72a6d15b68c3fe7df2b7. The archive was not installed. Verify the sha256 in the marketplace entry, or that the URL serves the intended file.3894Plugin archive integrity check failed for https://artifacts.example.com/claude-plugins/my-plugin.zip: expected sha256 6bfa50e3d2e00c052b46abe51fff89346ac803e45771f76dcf6df1ab74cca5e1, got ac52220c0914ef8ca6a602e4a7362f88d30fb021110f72a6d15b68c3fe7df2b7. The archive was not installed. Verify the sha256 in the marketplace entry, or that the URL serves the intended file.

3893 3896

3894**要做什么：**3897**要做什么：**

3895 3898

3896* 如果您发布 plugin，使用 `shasum -a 256 my-plugin.zip` 或 PowerShell 中的 `Get-FileHash -Algorithm SHA256 my-plugin.zip` 重新计算 URL 提供的确切文件的摘要，并更新 marketplace 条目中的 `sha256`3899* 如果您发布插件，重新计算 URL 提供的确切文件的摘要，例如使用`shasum -a 256 my-plugin.zip`或在 PowerShell 中使用`Get-FileHash -Algorithm SHA256 my-plugin.zip`，并更新 marketplace 条目中的`sha256`

3897* 如果您安装 plugin，运行 `/plugin marketplace update <name>` 以刷新目录以防条目已更正，然后重试安装3900* 如果您安装插件，运行`/plugin marketplace update <name>`以刷新目录以防条目已更正，然后重试安装

3898* 如果刷新后摘要仍然不一致，请在安装前询问 marketplace 所有者他们 pin 了哪个文件3901* 如果刷新后摘要仍然不一致，请在安装前询问 marketplace 所有者他们引脚的是哪个文件

3899 3902

3900<h3 id="path-escapes-plugin-directory">3903<h3 id="path-escapes-plugin-directory">

3901 路径逃逸 plugin 目录3904 路径逃逸插件目录

3902</h3>3905</h3>

3903 3906

3904plugin 组件路径在 plugin 的 `plugin.json` 或其 [marketplace 条目](/docs/zh-CN/plugins/marketplace-reference#plugin-entries) 中声明，解析到 plugin 自己的目录之外。Claude Code 删除该路径并加载 plugin 的其余部分。消息中的组件名称（例如 `commands` 或 `hooks`）命名声明路径的字段。3907插件组件路径在插件的`plugin.json`或其[marketplace 条目](/docs/zh-CN/plugins/marketplace-reference#plugin-entries)中声明，解析到插件自己目录之外。Claude Code 删除该路径并加载插件的其余部分。消息中的组件名称（例如`commands`或`hooks`）命名声明路径的字段。

3905 3908

3906```text theme={null}3909```text theme={null}

3907commands path escapes plugin directory: ./../shared.md3910commands path escapes plugin directory: ./../shared.md

3908```3911```

3909 3912

3910在 `claude plugin` 命令输出中，相同的错误读作 `Path escapes plugin directory: ./../shared.md (commands)`。3913在`claude plugin`命令输出中，相同的错误读作`Path escapes plugin directory: ./../shared.md (commands)`。

3911 3914

3912Claude Code 拒绝指向 plugin 外部的路径（如 `../shared-utils`）和导致 plugin 外部的符号链接，以及 [marketplace 符号链接规则](/docs/zh-CN/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks) 不允许的符号链接。对于符号链接，消息还说明路径解析的位置：3915Claude Code 拒绝指向插件外部的路径（如`../shared-utils`）和导致插件外部的符号链接，[marketplace 符号链接规则](/docs/zh-CN/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks)不允许的符号链接。对于符号链接，消息还说明路径解析的位置：

3913 3916

3914```text theme={null}3917```text theme={null}

3915commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory3918commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory

3916```3919```

3917 3920

3918在 macOS 和 Linux 上，Claude Code 还拒绝包含反斜杠的组件路径，即使路径保留在 plugin 内。其组件路径使用 Windows 风格分隔符的 plugin 在 Windows 上加载，并在其他平台上触发此拒绝：3921在 macOS 和 Linux 上，Claude Code 也拒绝包含反斜杠的组件路径，即使路径保留在插件内。使用 Windows 风格分隔符的组件路径的插件在 Windows 上加载并在其他平台上触发此拒绝：

3919 3922

3920```text theme={null}3923```text theme={null}

3921commands path escapes plugin directory: ./commands\deploy.md — its path contains a backslash, which is not resolved reliably on this platform3924commands path escapes plugin directory: ./commands\deploy.md — its path contains a backslash, which is not resolved reliably on this platform

3922```3925```

3923 3926

3924在 v2.1.251 之前，Claude Code 加载在 marketplace 条目中声明的 `commands` 路径，即使它指向 plugin 目录之外。Claude Code 已经拒绝在 `plugin.json` 中声明的路径和 marketplace 条目中的其他组件路径。3927在 v2.1.251 之前，Claude Code 加载在 marketplace 条目中声明的`commands`路径，即使它指向插件目录之外。

3925 3928

3926在 v2.1.257 之前，检查仅查看路径的拼写，而不是符号链接导向的位置。3929在 v2.1.257 之前，检查仅查看路径的拼写，而不是符号链接导向的位置。

3927 3930

3928**要做什么：**3931**要做什么：**

3929 3932

3930* 将引用的文件移到 plugin 目录内，并使用 `./` 相对路径指向它3933* 将引用的文件移到插件目录内，并使用`./`相对路径指向它

3931* 如果路径是指向 plugin 外部文件的符号链接，请用文件副本替换符号链接3934* 如果路径是指向插件外部文件的符号链接，用文件副本替换符号链接

3932* 如果消息说路径包含反斜杠，请使用正斜杠写入路径，例如 `./commands/deploy.md`3935* 如果消息说路径包含反斜杠，用正斜杠写路径，例如`./commands/deploy.md`

3933* 要与同一 marketplace 中的其他 plugin 共享文件，请使用 plugin 目录内的符号链接链接它们，遵循 [符号链接规则](/docs/zh-CN/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks)3936* 要与同一 marketplace 中的其他插件共享文件，使用插件目录内的符号链接链接它们，遵循[符号链接规则](/docs/zh-CN/plugins/host-marketplace#share-files-within-a-marketplace-with-symlinks)

3934 3937

3935<h3 id="path-could-not-be-checked">3938<h3 id="path-could-not-be-checked">

3936 路径无法检查3939 路径无法检查

3937</h3>3940</h3>

3938 3941

3939Claude Code 询问操作系统 plugin 路径是否存在，并收到除"未找到"之外的错误，因此它不加载路径命名的内容。plugin 的加载量取决于哪个路径失败：3942Claude Code 询问操作系统插件路径是否存在，并收到"未找到"以外的错误，因此它不加载路径命名的内容。插件加载多少取决于哪个路径失败：

3940 3943

3941* plugin 的 [默认组件位置](/docs/zh-CN/plugins/manifest-reference#standard-layout) 之一，例如 `skills/` 文件夹、`monitors/monitors.json` 文件或 [plugin 根目录的 `SKILL.md`](/docs/zh-CN/plugins/components#skills)：plugin 的其他组件仍然加载3944* 插件的[默认组件位置](/docs/zh-CN/plugins/manifest-reference#standard-layout)之一，例如`skills/`文件夹、`monitors/monitors.json`文件或[插件根目录的`SKILL.md`](/docs/zh-CN/plugins/components#skills)：插件的其他组件仍然加载

3942* plugin 自己的目录：该 plugin 中没有任何内容加载3945* 插件自己的目录：该插件中没有任何内容加载

3943 3946

3944对于根本不存在的路径，您看不到此错误。在 `/plugin` 中，错误出现在 plugin 下方，并命名路径和操作系统返回的代码：3947对于根本不存在的路径，您看不到此错误。在`/plugin`中，错误出现在插件下方，并命名路径和操作系统返回的代码：

3945 3948

3946```text theme={null}3949```text theme={null}

3947skills path could not be checked: /home/user/my-plugin/skills (ELOOP)3950skills path could not be checked: /home/user/my-plugin/skills (ELOOP)

3948```3951```

3949 3952

3950在 `claude plugin list` 中，相同的错误读作 `Path not found: /home/user/my-plugin/skills (skills, ELOOP)`。3953在`claude plugin list`中，相同的错误读作`Path not found: /home/user/my-plugin/skills (skills, ELOOP)`。

3951 3954

3952产生此错误的原因包括：3955产生此错误的原因包括：

3953 3956

3954* `ELOOP`：路径中的符号链接指向自身或形成循环3957* `ELOOP`：路径中的符号链接指向自己或形成循环

3955* `EIO` 或 `ESTALE`：路径在损坏或陈旧的网络挂载上3958* `EIO`或`ESTALE`：路径在损坏或陈旧的网络挂载上

3956* `EACCES`：路径上方的目录之一拒绝您遍历它的权限3959* `EACCES`：路径上方的目录之一拒绝您遍历它的权限

3957 3960

3958**要做什么：**3961**要做什么：**

3959 3962

3960* 用真实文件夹替换指向自身的符号链接，或删除它3963* 用真实文件夹替换指向自己的符号链接，或删除它

3961* 如果路径在网络挂载上，重新挂载共享3964* 如果路径在网络挂载上，重新挂载共享

3962* 如果代码是 `EACCES`，恢复您对路径上方目录的执行权限3965* 如果代码是`EACCES`，恢复您对路径上方目录的执行权限

3963* 修复路径后运行 `/reload-plugins`，或重启 Claude Code，以加载 plugin 或组件3966* 修复路径后运行`/reload-plugins`，或重启 Claude Code，以加载插件或组件

3964 3967

3965在 v2.1.265 之前，Claude Code 将无法检查的默认组件文件夹视为不存在，并加载 plugin 而不使用该组件，没有错误。3968在 v2.1.265 之前，Claude Code 将无法检查的默认组件文件夹视为不存在，并加载没有该组件的插件，没有错误。

3966 3969

3967<h3 id="marketplace-entry-path-does-not-stay-inside-the-marketplace-directory">3970<h3 id="marketplace-entry-path-does-not-stay-inside-the-marketplace-directory">

3968 Marketplace 条目路径不保留在 marketplace 目录内3971 Marketplace 条目路径不保留在 marketplace 目录内

3969</h3>3972</h3>

3970 3973

3971plugin 的 [marketplace 条目](/docs/zh-CN/plugins/marketplace-reference#plugin-entries) 声明了一个源路径，Claude Code 无法将其解析到 marketplace 自己的目录内的位置，因此 plugin 不会安装或加载。拒绝涵盖：3974插件的[marketplace 条目](/docs/zh-CN/plugins/marketplace-reference#plugin-entries)声明了一个源路径，Claude Code 无法将其解析到 marketplace 自己目录内的位置，因此插件不安装或加载。拒绝涵盖：

3972 3975

3973* 绝对的条目路径、使用 `..` 爬出 marketplace 的路径或拼写为网络路径的路径3976* 绝对的条目路径、使用`..`爬出 marketplace 的路径或拼写为网络路径的路径

3974* 在 macOS 和 Linux 上，在前导 `./` 之后的任何地方包含反斜杠的条目路径3977* 在 macOS 和 Linux 上，在前导`./`之后任何地方包含反斜杠的条目路径

3975* 从远程源（例如 git 或 URL）获取的 marketplace 中的条目，通过解析到 marketplace 目录外的符号链接到达其目标3978* 从远程来源（例如 git 或 URL）获取的 marketplace 中的条目，通过解析到 marketplace 目录外的符号链接到达其目标

3976* 从直接 URL 添加到其 `marketplace.json` 的 marketplace 中的相对条目：Claude Code 仅下载该文件，因此不存在本地 plugin 文件供路径命名。请参阅 [相对路径的 Plugins 在基于 URL 的 marketplaces 中失败](/docs/zh-CN/plugins/troubleshooting#plugins-with-relative-paths-fail-in-url-based-marketplaces)3979* 从直接 URL 添加到其`marketplace.json`的 marketplace 中的相对条目：Claude Code 仅下载该文件，因此不存在本地插件文件供路径命名。请参阅[相对路径的插件在基于 URL 的 marketplace 中失败](/docs/zh-CN/plugins/troubleshooting#plugins-with-relative-paths-fail-in-url-based-marketplaces)

3977 3980

3978`claude plugin install` 报告拒绝如下：3981`claude plugin install`报告拒绝如下：

3979 3982

3980```text theme={null}3983```text theme={null}

3981Cannot install my-plugin@my-marketplace: its marketplace entry path does not stay inside the marketplace directory (an absolute, climbing, network-shaped, backslash-containing or link-traversing entry, an entry of a fetched marketplace that resolves or opens outside its tree — or a relative entry in a url-catalog marketplace, which has no local directory)3984Cannot install my-plugin@my-marketplace: its marketplace entry path does not stay inside the marketplace directory (an absolute, climbing, network-shaped, backslash-containing or link-traversing entry, an entry of a fetched marketplace that resolves or opens outside its tree — or a relative entry in a url-catalog marketplace, which has no local directory)

3982```3985```

3983 3986

3984当已安装的 plugin 的条目失败相同的检查时，`claude plugin list` 显示 plugin 为 `failed to load`，带有：3987当已安装的插件的条目失败相同的检查时，`claude plugin list`显示插件为`failed to load`，带有：

3985 3988

3986```text theme={null}3989```text theme={null}

3987Plugin source path refused: ./my-plugin does not stay inside its marketplace directory. Check that the marketplace entry has a plain relative path.3990Plugin source path refused: ./my-plugin does not stay inside its marketplace directory. Check that the marketplace entry has a plain relative path.

3989 3992

3990**要做什么：**3993**要做什么：**

3991 3994

3992* 如果您维护 marketplace，将条目的 `source` 写为带有正斜杠的纯相对路径，例如 `./plugins/my-plugin`，并保持它穿过的任何符号链接指向 marketplace 目录内3995* 如果您维护 marketplace，将条目的`source`写为带正斜杠的纯相对路径，例如`./plugins/my-plugin`，并保持它跨越的任何符号链接指向 marketplace 目录内

3993* 如果您从直接 URL 添加了 marketplace，相对条目无法解析。要求 marketplace 作者使用 [另一个 plugin 源](/docs/zh-CN/plugins/marketplace-reference#plugin-sources)，或改为从其 git 存储库添加 marketplace3996* 如果您从直接 URL 添加了 marketplace，相对条目无法解析。要求 marketplace 作者使用[另一个插件源](/docs/zh-CN/plugins/marketplace-reference#plugin-sources)，或从其 git 存储库添加 marketplace

3994 3997

3995<h3 id="failed-to-load-marketplace-configuration">3998<h3 id="failed-to-load-marketplace-configuration">

3996 无法加载 marketplace 配置3999 无法加载 marketplace 配置

3997</h3>4000</h3>

3998 4001

3999Claude Code 将您添加的 plugin marketplaces 保存在 `~/.claude/plugins/known_marketplaces.json` 的注册表文件中。当 Claude Code 无法使用该文件时，需要注册表的 plugin 命令（例如 `claude plugin install`）会失败，并显示以下两条消息之一：4002Claude Code 将您添加的插件 marketplace 保存在`~/.claude/plugins/known_marketplaces.json`的注册表文件中。当 Claude Code 无法使用该文件时，需要注册表的插件命令（例如`claude plugin install`）失败，返回两条消息之一：

4000 4003

4001* `Failed to load marketplace configuration`：文件不是有效的 JSON，或无法读取。空文件也会以这种方式失败。4004* `Failed to load marketplace configuration`：文件存在但不是有效的 JSON 或无法读取。空文件也会以这种方式失败。

4002* `Marketplace configuration file is corrupted`：文件是有效的 JSON，但其内容与注册表架构不匹配。4005* `Marketplace configuration file is corrupted`：文件是有效的 JSON，但其内容与注册表架构不匹配。

4003 4006

4004缺少的文件不是失败：Claude Code 将其视为没有 marketplaces 的注册表。4007对于空文件，`claude plugin install`报告：

~~4005~~

4006对于空文件，`claude plugin install` 报告：

4007 4008

4008```text theme={null}4009```text theme={null}

4009✘ Failed to install plugin "my-plugin": Failed to load marketplace configuration: JSON Parse error: Unexpected EOF4010✘ Failed to install plugin "my-plugin": Failed to load marketplace configuration: JSON Parse error: Unexpected EOF

4010```4011```

4011 4012

4012在 v2.1.246 之前，`claude plugin install` 没有报告此失败。4013在 v2.1.246 之前，`claude plugin install`没有报告此失败。

4013 4014

4014**要做什么：**4015**要做什么：**

4015 4016

4016* 打开 `~/.claude/plugins/known_marketplaces.json` 并修复 JSON，或修复消息命名为与注册表架构不匹配的条目4017* 打开`~/.claude/plugins/known_marketplaces.json`并修复 JSON，或修复消息命名为与注册表架构不匹配的条目

4017* 如果您无法修复它，删除文件或用 `{}` 替换其内容，然后使用 `claude plugin marketplace add <source>` 重新添加每个 marketplace。Claude Code 在您下次在您信任的文件夹中启动它时重新注册您的用户或托管设置在 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces) 中声明的 marketplaces。4018* 如果您无法修复它，删除文件或用`{}`替换其内容，然后使用`claude plugin marketplace add <source>`重新添加每个 marketplace。Claude Code 在您下次在您信任的文件夹中启动它时重新注册您的用户或托管设置在[`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces)中声明的 marketplace。

4018 4019

4019<h3 id="plugin-is-required-by-your-organization">4020<h3 id="plugin-is-required-by-your-organization">

4020 Plugin 由您的组织要求4021 插件由您的组织要求

4021</h3>4022</h3>

4022 4023

4023您运行了 `claude plugin disable`，或使用 `/plugin` **Installed** 选项卡关闭了从 claude.ai 同步的 [plugin](/docs/zh-CN/plugins/loading#synced-plugins)，您的组织将其标记为必需：4024您运行了`claude plugin disable`，或使用`/plugin`**Installed**选项卡关闭了从 claude.ai 同步的[插件](/docs/zh-CN/plugins/loading#synced-plugins)，您的组织将其标记为必需：

4024 4025

4025```text theme={null}4026```text theme={null}

4026Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.4027Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.

4027```4028```

4028 4029

4029Claude Code 不保存任何内容，plugin 保持启用。4030Claude Code 不保存任何内容，插件保持启用。

4030 4031

4031当您尝试禁用必需 plugin 依赖的 plugin 时，Claude Code 以相同的方式拒绝，消息命名需要它的必需 plugin。4032当您尝试禁用必需插件依赖的插件时，Claude Code 以相同的方式拒绝，消息命名需要它的必需插件。

4032 4033

4033**要做什么：**4034**要做什么：**

4034 4035

4035* 要求您的 claude.ai 组织的管理员在 claude.ai 上更改 plugin 的必需状态4036* 要求您的 claude.ai 组织的管理员在 claude.ai 上更改插件的必需状态

4036 4037

4037<h3 id="plugin-was-not-uninstalled">4038<h3 id="plugin-was-not-uninstalled">

4038 Plugin 未被卸载4039 插件未卸载

4039</h3>4040</h3>

4040 4041

4041您运行了 [`claude plugin uninstall`](/docs/zh-CN/plugins/cli-reference#plugin-uninstall)，或在 `/plugin` **Installed** 选项卡中选择了 **Uninstall**，卸载停止，消息开头为 `"<plugin>" was not uninstalled:`。如果冒号后的文本以 `installed_plugins.json` 开头而不是命名设置文件，原因是 `installed_plugins.json` 中的内容此版本的 Claude Code 无法读取。对于该形式，请参阅 [`installed_plugins.json` 保存此版本无法读取的记录](/docs/zh-CN/plugins/troubleshooting#installed-plugins-json-holds-a-record-this-version-cannot-read)。4042您运行了[`claude plugin uninstall`](/docs/zh-CN/plugins/cli-reference#plugin-uninstall)，或在`/plugin`**Installed**选项卡中选择了**Uninstall**，卸载停止，消息开头为`"<plugin>" was not uninstalled:`。如果该冒号后的文本以`installed_plugins.json`开头而不是命名设置文件，原因是`installed_plugins.json`中的内容，此版本的 Claude Code 无法读取。对于该形式，请参阅[`installed_plugins.json`保存此版本无法读取的记录](/docs/zh-CN/plugins/troubleshooting#installed-plugins-json-holds-a-record-this-version-cannot-read)。

4042 4043

4043当 Claude Code 从 `enabledPlugins` 中删除 plugin 的条目并读回该范围的设置文件时，要么 plugin 仍在那里被打开，要么可以打开它的文件无法读取或检查。在设置条目可以将其重新打开时删除 plugin 的保存选项、机密和数据会丢失它们，因此卸载停止：plugin 保持安装，它保存的任何内容都不会被删除。4044当 Claude Code 从`enabledPlugins`中删除插件的条目并读回该范围的设置文件时，要么插件仍在那里打开，要么可以打开它的文件无法读取或检查。删除插件保存的选项、机密和数据，同时设置条目可以将其打开，会丢失它们，因此卸载停止：插件保持安装，它保存的任何内容都不会被删除。

4044 4045

4045```text theme={null}4046```text theme={null}

4046✘ Failed to uninstall plugin "formatter": "formatter" was not uninstalled: it is still switched on in /home/user/project/.claude/settings.local.json, although the settings change reported no error. It is still installed. Take it out of "enabledPlugins" in that file yourself, then uninstall it again.4047✘ Failed to uninstall plugin "formatter": "formatter" was not uninstalled: it is still switched on in /home/user/project/.claude/settings.local.json, although the settings change reported no error. It is still installed. Take it out of "enabledPlugins" in that file yourself, then uninstall it again.

4048 4049

4049消息的中间部分命名文件和原因：4050消息的中间部分命名文件和原因：

4050 4051

4051* `it is still switched on in <file>, although the settings change reported no error`：设置写入报告成功但条目在读回文件时仍然存在4052* `it is still switched on in <file>, although the settings change reported no error`：设置写报告成功，但读回文件时条目仍在那里

4052* `it is still switched on in <file>, and the settings change failed (<error>)`：文件无法保存，原因在括号中4053* `it is still switched on in <file>, and the settings change failed (<error>)`：文件无法保存，原因在括号中

4053* `<file> is there and could not be read`：文件存在但无法作为设置读取，例如因为它不是有效的 JSON，所以它可能仍然启用 plugin4054* `<file> is there and could not be read`：文件存在但无法作为设置读取，例如因为它不是有效的 JSON，所以它可能仍然启用插件

4054* `<file> (not read: it is on a network path or is a link to one, or could not be checked)`：Claude Code 没有读取项目或本地设置文件，因为文件或保存它的 `.claude` 文件夹是指向网络位置的链接，或因为它无法检查该路径4055* `<file> (not read: it is on a network path or is a link to one, or could not be checked)`：Claude Code 没有读取项目或本地设置文件，因为文件或保存它的`.claude`文件夹是指向网络位置的链接，或因为它无法检查该路径

4055 4056

4056`claude plugin uninstall` 退出 1，使用 `--json` 时结果包含 `failureCode: "settings_still_on"`。`/plugin` 显示相同的消息。4057`claude plugin uninstall`退出 1，使用`--json`时结果带有`failureCode: "settings_still_on"`。`/plugin`显示相同的消息。

4057 4058

4058**要做什么：**4059**要做什么：**

4059 4060

4060* 遵循消息的最后一句：修复或替换它命名的设置文件，或自己从该文件中的 `enabledPlugins` 中删除 plugin 的条目，然后再次运行卸载4061* 遵循消息的最后一句：修复或替换它命名的设置文件，或自己从该文件中的`enabledPlugins`中删除插件的条目，然后再次运行卸载

4061 4062

4062<h2 id="tool-errors">4063<h2 id="tool-errors">

4063 工具错误4064 工具错误

4626terminal host process died — press Enter to restart4627terminal host process died — press Enter to restart

4627```4628```

4628 4629

4629如果您在检查运行之前打开该行，页脚显示 `This session's terminal host process died (the conversation is saved) — press Enter to restart it`，该行变为失败。

~~4630~~

4631从 shell，`claude attach <id>` 重启已标记为死主机失败的会话，否则打印原因并退出：4630从 shell，`claude attach <id>` 重启已标记为死主机失败的会话，否则打印原因并退出：

4632 4631

4633```text theme={null}4632```text theme={null}

5029 5028

5030Claude Code 将大多数这些消息写入 stderr，而不是写入对话中，并在启动时写入大多数消息。当消息出现在其他地方（例如在调试日志中或作为对话视图中的启动通知）或在其他时间（例如[请求时的无法识别的模型诊断行](#unrecognized-model-id-on-a-request)）时，条目会说明这一点。5029Claude Code 将大多数这些消息写入 stderr，而不是写入对话中，并在启动时写入大多数消息。当消息出现在其他地方（例如在调试日志中或作为对话视图中的启动通知）或在其他时间（例如[请求时的无法识别的模型诊断行](#unrecognized-model-id-on-a-request)）时，条目会说明这一点。

5031 5030

5032<h3 id="fullscreen-failed-start-notice">

5033 全屏渲染器未能完成启动

5034</h3>

~~5035~~

5036此计算机上的上一个[全屏](/docs/zh-CN/fullscreen)会话在完成启动前退出，因此 Claude Code 在经典渲染器上启动此会话并打印以下通知之一：

~~5037~~

5038```text theme={null}

5039Claude Code's fullscreen renderer didn't finish starting last time on this machine, so this launch is using the classic renderer. It will try fullscreen again next launch; /tui default keeps the classic renderer.

~~5040~~

5041Claude Code's fullscreen renderer has repeatedly failed to start on this machine, so it has been turned off here. Run /tui fullscreen to try it again (this also resets after an update).

5042```

~~5043~~

5044**要做什么：**

~~5045~~

5046* 按照[全屏渲染](/docs/zh-CN/fullscreen#fullscreen-renderer-didnt-finish-starting)进行操作。它说明您获得哪个通知、Claude Code 在后续会话中的操作，以及如何再次尝试全屏或保持经典渲染器。

5047* 如果已死亡的会话打印了退出消息，请参阅[Claude Code 因无法恢复的界面错误而退出](#exited-after-an-unrecoverable-interface-error)了解其名称。

~~5048~~

5049在 v2.1.236 之前，Claude Code 未打印通知，并在失败启动后继续在全屏渲染中启动会话。

~~5050~~

5051<h3 id="exited-after-an-unrecoverable-interface-error">5031<h3 id="exited-after-an-unrecoverable-interface-error">

5052 Claude Code 因无法恢复的界面错误而退出5032 Claude Code 因无法恢复的界面错误而退出

5053</h3>5033</h3>

5199* 如果您管理设置，请将您的用户可以运行的模型添加到 `availableModels`，或缩小阻止每个回退的 `deniedModels` 条目。[阻止特定模型或版本](/docs/zh-CN/model-config#block-specific-models-or-versions)描述默认选项如何降级5179* 如果您管理设置，请将您的用户可以运行的模型添加到 `availableModels`，或缩小阻止每个回退的 `deniedModels` 条目。[阻止特定模型或版本](/docs/zh-CN/model-config#block-specific-models-or-versions)描述默认选项如何降级

5200* 如果您不管理它们，请将消息发送给您的管理员。您自己的设置文件无法扩大托管的 `availableModels` 或 `deniedModels` 列表5180* 如果您不管理它们，请将消息发送给您的管理员。您自己的设置文件无法扩大托管的 `availableModels` 或 `deniedModels` 列表

5201 5181

5182<h3 id="managed-settings-dont-allow-this-api-provider">

5183 托管设置不允许此 API 提供商

5184</h3>

5185

5186您的组织的[托管设置](/docs/zh-CN/managed-settings)设置了 [`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders) 列表，会话的 API 提供商不在其上，或会话使用的端点不是按该条目要求的方式固定的。Claude Code 在启动前、登录前或会话下次联系 API 时拒绝。消息以允许的提供商开头：

5187

5188```text theme={null}

5189Your organization's managed settings allow Claude Code to use: Anthropic API, Amazon Bedrock.

5190```

5191

5192当列表为空时，消息改为读取：

5193

5194```text theme={null}

5195Your organization's managed settings allow Claude Code to use no API provider at all (allowedProviders is an empty list), so it cannot start on this machine.

5196```

5197

5198当每个条目都无法识别时，括号读取 `(allowedProviders lists only unrecognized entries)` 代替。

5199

5200**要做什么：**

5201

5202* 按照消息的 `To continue:` 步骤进行

5203* 如果您管理设置，消息的以 `Admins:` 开头的行命名要添加的条目或要固定的值，[`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders) 条目说明哪个源的 `env` 块可以固定它

5204

5202<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">5205<h3 id="mcp-server-is-blocked-by-enterprise-managed-policy">

5203 MCP 服务器被企业托管策略阻止5206 MCP 服务器被企业托管策略阻止

5204</h3>5207</h3>

5252* 如果您管理计算机，修复命名的文档使其解析为 JSON 对象，或删除文件、配置文件或注册表值。空的 `managed-settings.json` 计为 `{}` 并不阻止启动。5255* 如果您管理计算机，修复命名的文档使其解析为 JSON 对象，或删除文件、配置文件或注册表值。空的 `managed-settings.json` 计为 `{}` 并不阻止启动。

5253* 如果您不管理，请要求您的管理员修复部署的文档。您自己的设置文件中的任何内容都不会导致或清除此错误。5256* 如果您不管理，请要求您的管理员修复部署的文档。您自己的设置文件中的任何内容都不会导致或清除此错误。

5254 5257

5258<h3 id="unable-to-read-managed-policy-settings">

5259 无法读取托管策略设置

5260</h3>

5261

5262您的组织部署[托管设置](/docs/zh-CN/managed-settings)，其中一个部署的源存在但无法读取，原因例如 I/O 错误而不是操作系统拒绝读取。没有其他管理员源提供策略，Claude Code 在启动时退出，而不是在没有源可能携带的策略的情况下运行：

5263

5264```text theme={null}

5265Unable to read managed policy settings.

5266This machine may require organization login enforcement, but the policy file failed to load.

5267Contact your administrator.

5268

5269Detail: <source>: <reason>

5270```

5271

5272在相同的状态下，登录流、来自已运行的会话的 API 请求和 [`claude gateway`](/docs/zh-CN/claude-apps-gateway) 服务器被拒绝，其中第一行的变体命名 [`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders)。

5273

5274操作系统拒绝的读取，例如在仅限 root 的文件上，不会产生此退出：[会话启动时不使用该源的策略](/docs/zh-CN/managed-settings#find-entries-claude-code-dropped)。对于无法解析的源，Claude Code 以[不同的消息命名源](#managed-settings-document-could-not-be-parsed)退出。

5275

5276**要做什么：**

5277

5278* 如果您管理计算机，修复 `Detail:` 行命名的问题，以便部署的源可以被读取，或删除源

5279* 如果您不管理，请将消息发送给您的管理员。您自己的设置文件中的任何内容都不会导致或清除此错误

5280

5281在 v2.1.285 之前，仅使用 claude.ai 或 Claude Console 凭据登录的会话以此消息退出，操作系统拒绝的读取也产生了它。

5282

5255<h3 id="otelheadershelper-failed">5283<h3 id="otelheadershelper-failed">

5256 otelHeadersHelper 失败5284 otelHeadersHelper 失败

5257</h3>5285</h3>

5464 回复质量似乎低于预期5492 回复质量似乎低于预期

5465</h2>5493</h2>

5466 5494

5467如果 Claude 的回答似乎不如你预期的那样有能力，但没有显示错误，原因通常是对话状态而不是模型本身。Claude Code 不会无声地更改模型版本。它只能在三种特定情况下切换到备用模型：5495如果 Claude 的回答似乎不如你预期的那样有能力，但没有显示错误，原因通常是对话状态而不是模型本身。Claude Code 不会无声地更改模型版本。它只能在这些情况下切换到备用模型：

5468 5496

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

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

5471* [自动模型备用](/docs/zh-CN/model-config#automatic-model-fallback) 在 Fable 5.1、Fable 5、Opus 5.5、Sonnet 5.5 和 Opus 5 上，当该类别有备用模型时，将会话移动到标记类别的备用模型，并在记录中显示通知5499* [自动模型备用](/docs/zh-CN/model-config#automatic-model-fallback) 在 Fable 5.1、Fable 5、Opus 5.5、Sonnet 5.5 和 Opus 5 上，当该类别有备用模型时，将会话移动到标记类别的备用模型，并在记录中显示通知

5472 5500

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

google-vertex-ai.md +12 −0

Details

293 293

294模型别名（如 `opus`）不充当固定值，Claude Code 不识别的模型 ID 也不充当固定值。294模型别名（如 `opus`）不充当固定值，Claude Code 不识别的模型 ID 也不充当固定值。

295 295

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

297

298<h3 id="when-a-model-is-disabled-mid-session">

299 当模型在会话中途被禁用时

300</h3>

301

302如果您的项目失去对会话正在运行的模型的访问权限，例如因为管理员在 [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) 中禁用了它，Claude Code 会将会话切换到另一个模型，而不是让每个请求都失败，并显示 `Switched to <fallback> because <model> is not available`。它尝试与启动回退相同的模型：首先尝试同一层级的早期版本，对于没有可用 Opus 版本的 Opus 会话，则使用默认 Sonnet 模型。

303

304切换仅适用于您未固定的层级，这与启动回退的条件相同。在您选择的特定版本上的会话保持其模型，没有回退模型链，请求会失败。在 [auto mode](/docs/zh-CN/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry) 中，Claude Code 仅切换到 auto mode 在 Agent Platform 上支持的模型。如果这些模型都不可用，请求会失败。

305

306您配置的[回退模型链](/docs/zh-CN/model-config#fallback-model-chains)会替换层级切换：在这些拒绝上，Claude Code 会切换到您配置的回退。要使被拒绝的请求失败而不是切换，请设置 [`CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK=1`](/docs/zh-CN/env-vars)。您配置的回退链仍会在这些拒绝上切换；如果您希望每个被拒绝的请求都失败，也要移除该链。

307

296<h2 id="iam-configuration">308<h2 id="iam-configuration">

297 IAM 配置309 IAM 配置

298</h2>310</h2>

headless.md +2 −2

Details

296 自动批准工具296 自动批准工具

297</h3>297</h3>

298 298

299使用 `--allowedTools` 让 Claude 使用某些工具而无需提示。此示例运行测试套件并修复失败，允许 Claude 执行 Bash 命令和读取/编辑文件而无需请求权限：299使用 `--allowedTools` 让 Claude 使用某些工具而无需提示。列出 `Read` 和 `Edit` 让 Claude 读取和编辑文件而无需请求权限。列出 `Bash` 对 shell 命令执行相同操作，除了在 [auto 模式](/docs/zh-CN/permission-modes#how-auto-mode-evaluates-actions) 中启动的运行，其中 Claude Code 删除裸 `Bash` 条目作为广泛允许规则，auto 模式改为评估每个命令。此示例运行测试套件并修复失败，允许这三个工具：

300 300

301```bash theme={null}301```bash theme={null}

302claude -p "Run the test suite and fix any failures" \302claude -p "Run the test suite and fix any failures" \

303 --allowedTools "Bash,Read,Edit"303 --allowedTools "Bash,Read,Edit"

304```304```

305 305

306要为整个会话设置基线而不是列出单个工具，请传递 [权限模式](/docs/zh-CN/permission-modes)。对于 `-p`，[内置启动权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in) 在每个计划上都是 Manual，因此传递您想要的权限模式：306要为整个会话设置基线而不是列出单个工具，请传递 [权限模式](/docs/zh-CN/permission-modes)。对于不设置权限模式的运行，采用 [内置启动权限模式](/docs/zh-CN/permission-modes#which-mode-a-session-starts-in)，可能是 `auto`，因此传递您想要的权限模式：

307 307

308* **`auto`**：传递 `--permission-mode auto` 以让分类器审查大多数操作而不是您308* **`auto`**：传递 `--permission-mode auto` 以让分类器审查大多数操作而不是您

309* **`dontAsk`**：Claude Code 拒绝每个原本会提示的调用，这对于锁定的 CI 运行很有用。在 Manual 模式下无需批准的操作仍会运行，例如工作目录中的文件读取和 [只读命令集](/docs/zh-CN/permissions#read-only-commands)，您的 `--allowedTools` 条目或 `permissions.allow` 规则涵盖的操作也是如此。`AskUserQuestion`、连接器工具 [您的组织设置为 `ask`](/docs/zh-CN/mcp#organization-controls-on-connector-tools) 和标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使当允许规则匹配时也被拒绝309* **`dontAsk`**：Claude Code 拒绝每个原本会提示的调用，这对于锁定的 CI 运行很有用。在 Manual 模式下无需批准的操作仍会运行，例如工作目录中的文件读取和 [只读命令集](/docs/zh-CN/permissions#read-only-commands)，您的 `--allowedTools` 条目或 `permissions.allow` 规则涵盖的操作也是如此。`AskUserQuestion`、连接器工具 [您的组织设置为 `ask`](/docs/zh-CN/mcp#organization-controls-on-connector-tools) 和标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具即使当允许规则匹配时也被拒绝

hooks.md +68 −68

Details

12 12

13Hooks 是用户定义的 shell 命令、HTTP 端点、MCP 工具调用、LLM 提示或子代理，在 Claude Code 生命周期中的特定点自动执行。Claude Code 在其运行的任何地方都会触发相同的 hook 事件：终端中的会话、IDE 扩展、[桌面应用](/docs/zh-CN/desktop-quickstart)和[云会话](/docs/zh-CN/claude-code-on-the-web)。使用此参考查找事件架构、配置选项、JSON 输入/输出格式以及异步 hooks、HTTP hooks 和 MCP 工具 hooks 等高级功能。13Hooks 是用户定义的 shell 命令、HTTP 端点、MCP 工具调用、LLM 提示或子代理，在 Claude Code 生命周期中的特定点自动执行。Claude Code 在其运行的任何地方都会触发相同的 hook 事件：终端中的会话、IDE 扩展、[桌面应用](/docs/zh-CN/desktop-quickstart)和[云会话](/docs/zh-CN/claude-code-on-the-web)。使用此参考查找事件架构、配置选项、JSON 输入/输出格式以及异步 hooks、HTTP hooks 和 MCP 工具 hooks 等高级功能。

14 14

15插件也可以将 hooks 注册为 JavaScript 函数，Claude Code 在其自己的进程中调用这些函数，这些函数既可以在界面中绘制，也可以对事件进行操作。执行此操作的插件是[mod](/docs/zh-CN/plugins/mods/overview)，这些函数 hooks 在[对事件做出反应](/docs/zh-CN/plugins/mods/events)中介绍，而不是在这里。此页面上的 hooks 继续与 mods 一起工作。

15<h2 id="hook-lifecycle">17<h2 id="hook-lifecycle">

16 Hook 生命周期18 Hook 生命周期

17</h2>19</h2>

270 272

271[云会话](/docs/zh-CN/claude-code-on-the-web) 不读取本地 `~/.claude/settings.json`。在 [自托管环境](/docs/zh-CN/self-hosted-environments-configuration#permissions-and-tool-approval) 中，Claude Code 还运行操作员从运行程序主机的 `~/.claude/` 中植入的 hooks，并在该文件属于 [Claude Code 应用的托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources) 时运行运行程序镜像的托管设置文件中的 hooks，这默认意味着仅当服务器托管设置和 MDM 交付的 Claude Code 策略都不提供托管层时。有关哪些设置文件和插件（以及因此哪些 hooks）到达云会话的信息，请参阅 [从设置中携带的内容](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)。273[云会话](/docs/zh-CN/claude-code-on-the-web) 不读取本地 `~/.claude/settings.json`。在 [自托管环境](/docs/zh-CN/self-hosted-environments-configuration#permissions-and-tool-approval) 中，Claude Code 还运行操作员从运行程序主机的 `~/.claude/` 中植入的 hooks，并在该文件属于 [Claude Code 应用的托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources) 时运行运行程序镜像的托管设置文件中的 hooks，默认情况下仅当服务器托管设置和 MDM 交付的 Claude Code 策略都不提供托管层时才运行。有关哪些设置文件和插件（以及哪些 hooks）到达云会话，请参阅 [从设置中继承的内容](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)。

272 274

273有关设置文件解析的详细信息，请参阅 [settings](/docs/zh-CN/settings)。275有关设置文件解析的详细信息，请参阅 [settings](/docs/zh-CN/settings)。

274 276

275来自设置文件、托管策略设置和插件的 Hooks 也在 [subagents](/docs/zh-CN/sub-agents) 内运行。当子代理调用工具时，工具事件（如 `PreToolUse` 和 `PostToolUse`）触发与主对话中相同的配置 hooks，输入包含标识子代理的 `agent_id` 和 `agent_type` [通用输入字段](#common-input-fields)。277来自设置文件、托管策略设置和插件的 Hooks 也在 [subagents](/docs/zh-CN/sub-agents) 内运行。当子代理调用工具时，工具事件（如 `PreToolUse` 和 `PostToolUse`）会触发与主对话中配置的相同 hooks，输入包含标识子代理的 `agent_id` 和 `agent_type` [通用输入字段](#common-input-fields)。

276 278

277管理员可以使用 [`allowManagedHooksOnly`](/docs/zh-CN/settings-reference#allowmanagedhooksonly) 在 [托管设置](/docs/zh-CN/managed-settings) 中限制哪些 hooks 运行：279管理员可以在 [托管设置](/docs/zh-CN/managed-settings) 中使用 [`allowManagedHooksOnly`](/docs/zh-CN/settings-reference#allowmanagedhooksonly) 来限制哪些 hooks 运行：

278 280

279* 用户、项目、本地和插件 hooks 被阻止。托管设置 `enabledPlugins` 中强制启用的插件中的 Hooks 除外281* 您的用户、项目、本地和插件 hooks 被阻止。在托管设置 `enabledPlugins` 中强制启用的插件中的 Hooks 除外

280* Claude Code 还将 [`statusLine`](/docs/zh-CN/statusline)、[`fileSuggestion`](/docs/zh-CN/settings-reference#filesuggestion) 和 [`subagentStatusLine`](/docs/zh-CN/statusline#subagent-status-lines) 设置限制为托管设置282* Claude Code 还将您的 [`statusLine`](/docs/zh-CN/statusline)、[`fileSuggestion`](/docs/zh-CN/settings-reference#filesuggestion) 和 [`subagentStatusLine`](/docs/zh-CN/statusline#subagent-status-lines) 设置缩小到托管设置

281* Claude Code 还禁用具有 [`command` 源](/docs/zh-CN/plugins/marketplace-reference#command-plugin-source) 的插件，包括托管设置 `enabledPlugins` 中强制启用的插件，除非 [`disableCommandPluginSources`](/docs/zh-CN/settings-reference#disablecommandpluginsources) 明确设置为 `false`。`command` 源需要 Claude Code v2.1.229 或更高版本283* Claude Code 还禁用具有 [`command` 源](/docs/zh-CN/plugins/marketplace-reference#command-plugin-source) 的插件，包括在托管设置 `enabledPlugins` 中强制启用的插件，除非 [`disableCommandPluginSources`](/docs/zh-CN/settings-reference#disablecommandpluginsources) 明确设置为 `false`。`command` 源需要 Claude Code v2.1.229 或更高版本

282* Claude Code 还阻止市场 [`headersHelper` 命令](/docs/zh-CN/plugins/host-marketplace#authenticate-archive-downloads)，除非 [`disableCommandPluginSources`](/docs/zh-CN/settings-reference#disablecommandpluginsources) 明确设置为 `false`，托管设置本身声明的市场除外284* Claude Code 还阻止市场 [`headersHelper` 命令](/docs/zh-CN/plugins/host-marketplace#authenticate-archive-downloads)，除非 [`disableCommandPluginSources`](/docs/zh-CN/settings-reference#disablecommandpluginsources) 明确设置为 `false`，但托管设置本身声明的市场除外

283 285

284请参阅 [在 `allowManagedHooksOnly` 下运行的内容](/docs/zh-CN/settings-reference#what-runs-under-allowmanagedhooksonly)。286请参阅 [在 `allowManagedHooksOnly` 下运行的内容](/docs/zh-CN/settings-reference#what-runs-under-allowmanagedhooksonly)。

285 287

286Hook 条目在设置级别之间合并而不是相互替换：用户、项目和本地设置添加自己的 hooks 而不删除托管的 hooks，[`disableAllHooks`](#disable-or-remove-hooks) 设置无法禁用来自托管设置外部的托管 hooks。288Hook 条目在设置级别之间合并而不是相互替换：用户、项目和本地设置添加自己的 hooks 而不删除托管的 hooks，[`disableAllHooks`](#disable-or-remove-hooks) 设置无法禁用来自托管设置外部的托管 hooks。

287 289

288[HTTP hook 允许列表](/docs/zh-CN/settings-reference#hook-and-skill-settings) 适用于来自每个源的 hooks，包括托管策略设置：290[HTTP hook 允许列表](/docs/zh-CN/settings-reference#hook-and-skill-settings) 适用于来自所有源的 hooks，包括托管策略设置：

289 291

290* `allowedHttpHookUrls`：在任何设置级别定义时，Claude Code 仅在其 URL 与合并的允许列表匹配时运行 HTTP hook 处理程序292* `allowedHttpHookUrls`：在任何设置级别定义时，Claude Code 仅在其 URL 与合并的允许列表匹配时运行 HTTP hook 处理程序

291* `httpHookAllowedEnvVars`：定义时，Claude Code 仅将该列表上的环境变量插值到 hook 标头中293* `httpHookAllowedEnvVars`：定义时，Claude Code 仅将该列表上的环境变量插值到 hook 标头中

299| 匹配器值 | 评估为 | 示例 |301| 匹配器值 | 评估为 | 示例 |

300| :- | :- | :- |302| :- | :- | :- |

301| `"*"`、`""` 或省略 | 匹配所有 | 在事件的每次出现时触发 |303| `"*"`、`""` 或省略 | 匹配所有 | 在事件的每次出现时触发 |

304 306

305在正则表达式路径上的匹配器使用 JavaScript 的 `RegExp.prototype.test` 进行测试，该测试在值中任何位置的匹配时成功。`Edit.*` 匹配 `Edit` 和 `NotebookEdit`；当需要整个字符串匹配时，用 `^` 和 `$` 包装模式，如 `^Edit$`。307正则表达式路径上的匹配器使用 JavaScript 的 `RegExp.prototype.test` 进行测试，该测试在值中任何位置的匹配时成功。`Edit.*` 同时匹配 `Edit` 和 `NotebookEdit`；当需要整个字符串匹配时，用 `^` 和 `$` 包装模式，如 `^Edit$`。

306 308

308 310

309`FileChanged` 事件在构建其监视列表时不遵循这些规则。请参阅 [FileChanged](#filechanged)。311`FileChanged` 事件在构建其监视列表时不遵循这些规则。请参阅 [FileChanged](#filechanged)。

310 312

319| `Notification` | 通知类型 | `permission_prompt`、`idle_prompt`、`auth_success`、`elicitation_dialog`、`elicitation_url_dialog`、`elicitation_complete`、`elicitation_response`、`agent_needs_input`、`agent_completed`、`quota_auto_resume_fired`、`quota_auto_resume_stale`、`quota_auto_resume_disabled` |321| `Notification` | 通知类型 | `permission_prompt`、`idle_prompt`、`auth_success`、`elicitation_dialog`、`elicitation_url_dialog`、`elicitation_complete`、`elicitation_response`、`agent_needs_input`、`agent_completed`、`quota_auto_resume_fired`、`quota_auto_resume_stale`、`quota_auto_resume_disabled` |

328| `StopFailure` | 错误类型 | `rate_limit`、`overloaded`、`authentication_failed`、`oauth_org_not_allowed`、`account_on_hold`、`billing_error`、`invalid_request`、`model_not_found`、`server_error`、`max_output_tokens`、`cloud_credential_error`、`unknown` |330| `StopFailure` | 错误类型 | `rate_limit`、`overloaded`、`authentication_failed`、`oauth_org_not_allowed`、`account_on_hold`、`billing_error`、`invalid_request`、`model_not_found`、`server_error`、`max_output_tokens`、`cloud_credential_error`、`unknown` |

334 336

358 360

359如果向不支持匹配器的事件添加 `matcher` 字段，它会被静默忽略。361如果向不支持匹配器的事件添加 `matcher` 字段，它会被静默忽略。

360 362

361对于工具事件，可以通过在单个 hook 处理程序上设置 [`if` 字段](#common-fields) 来更狭隘地过滤。`if` 使用 [权限规则语法](/docs/zh-CN/permissions) 来匹配工具名称和参数，因此 `"Bash(git *)"` 在任何 Bash 输入的子命令匹配 `git *` 时运行，`"Edit(*.ts)"` 仅对 TypeScript 文件运行。363对于工具事件，您可以通过在单个 hook 处理程序上设置 [`if` 字段](#common-fields) 来更狭隘地过滤。`if` 使用 [权限规则语法](/docs/zh-CN/permissions) 来匹配工具名称和参数，所以 `"Bash(git *)"` 在任何 Bash 输入的子命令匹配 `git *` 时运行，`"Edit(*.ts)"` 仅对 TypeScript 文件运行。

362 364

363<h4 id="match-mcp-tools">365<h4 id="match-mcp-tools">

364 匹配 MCP 工具366 匹配 MCP 工具

365</h4>367</h4>

366 368

367[MCP](/docs/zh-CN/mcp) 服务器工具在工具事件中显示为常规工具（`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`、`PermissionDenied`），因此可以像匹配任何其他工具名称一样匹配它们。369[MCP](/docs/zh-CN/mcp) 服务器工具在工具事件中显示为常规工具（`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest`、`PermissionDenied`），因此您可以像匹配任何其他工具名称一样匹配它们。

368 370

369MCP 工具遵循命名模式 `mcp__<server>__<tool>`，例如：371MCP 工具遵循命名模式 `mcp__<server>__<tool>`，例如：

370 372

372* `mcp__filesystem__read_file`：Filesystem 服务器的读取文件工具374* `mcp__filesystem__read_file`：Filesystem 服务器的读取文件工具

373* `mcp__github__search_repositories`：GitHub 服务器的搜索工具375* `mcp__github__search_repositories`：GitHub 服务器的搜索工具

374 376

375要匹配来自服务器的每个工具，请将 `.*` 附加到服务器前缀。`.*` 是必需的：像 `mcp__memory` 或 `mcp__brave-search` 这样的匹配器仅包含精确匹配字符，因此它被比较为精确字符串，不匹配任何工具。377要匹配来自服务器的每个工具，请在服务器前缀后附加 `.*`。`.*` 是必需的：像 `mcp__memory` 或 `mcp__brave-search` 这样的匹配器仅包含精确匹配字符，因此它被比较为精确字符串，不匹配任何工具。

376 378

377* `mcp__memory__.*` 匹配来自 `memory` 服务器的所有工具379* `mcp__memory__.*` 匹配来自 `memory` 服务器的所有工具

378* `mcp__brave-search__.*` 匹配来自名称包含连字符的服务器的所有工具380* `mcp__brave-search__.*` 匹配来自名称包含连字符的服务器的所有工具

379* `mcp__.*__write.*` 匹配来自任何服务器的名称以 `write` 开头的任何工具381* `mcp__.*__write.*` 匹配来自任何服务器的名称以 `write` 开头的任何工具

380 382

381来自 [插件捆绑的 MCP 服务器](/docs/zh-CN/mcp#plugin-provided-mcp-servers) 的工具使用包含插件名称的范围服务器段：`mcp__plugin_<plugin-name>_<server-name>__<tool>`。针对裸服务器密钥编写的匹配器永远不会对这些工具触发。对于名为 `my-plugin` 的插件，在密钥 `db` 下捆绑服务器，`query` 工具显示为 `mcp__plugin_my-plugin_db__query`，因此来自该服务器的每个工具的匹配器是 `mcp__plugin_my-plugin_db__.*`。在处理程序的 [`if` 字段](#common-fields) 中使用相同的范围工具名称。有关如何构建范围名称的信息，请参阅 [插件提供的 MCP 服务器](/docs/zh-CN/mcp#plugin-provided-mcp-servers)。383来自 [插件捆绑的 MCP 服务器](/docs/zh-CN/mcp#plugin-provided-mcp-servers) 的工具使用包含插件名称的范围服务器段：`mcp__plugin_<plugin-name>_<server-name>__<tool>`。针对裸服务器密钥编写的匹配器永远不会对这些工具触发。对于名为 `my-plugin` 的插件，在密钥 `db` 下捆绑服务器，`query` 工具显示为 `mcp__plugin_my-plugin_db__query`，因此来自该服务器的每个工具的匹配器是 `mcp__plugin_my-plugin_db__.*`。在处理程序的 [`if` 字段](#common-fields) 中使用相同的范围工具名称。请参阅 [插件提供的 MCP 服务器](/docs/zh-CN/mcp#plugin-provided-mcp-servers) 了解范围名称如何构建。

382 384

383此示例记录所有内存服务器操作并验证来自任何 MCP 服务器的写入操作：385此示例记录所有内存服务器操作并验证来自任何 MCP 服务器的写入操作：

384 386

415 417

416内部 `hooks` 数组中的每个对象都是一个 hook 处理程序：当匹配器匹配时运行的 shell 命令、HTTP 端点、MCP 工具、LLM 提示或代理。有五种类型：418内部 `hooks` 数组中的每个对象都是一个 hook 处理程序：当匹配器匹配时运行的 shell 命令、HTTP 端点、MCP 工具、LLM 提示或代理。有五种类型：

417 419

418* **[命令 hooks](#command-hook-fields)**（`type: "command"`）：运行 shell 命令。脚本在 stdin 上接收事件的 [JSON 输入](#hook-input-and-output)，并通过退出代码和 stdout 传回结果。420* **[命令 hooks](#command-hook-fields)**（`type: "command"`）：运行 shell 命令。您的脚本在 stdin 上接收事件的 [JSON 输入](#hook-input-and-output)，并通过退出代码和 stdout 传回结果。

419* **[HTTP hooks](#http-hook-fields)**（`type: "http"`）：将事件的 JSON 输入作为 HTTP POST 请求发送到 URL。端点通过响应体使用与命令 hooks 相同的 [JSON 输出格式](#json-output) 传回结果。421* **[HTTP hooks](#http-hook-fields)**（`type: "http"`）：将事件的 JSON 输入作为 HTTP POST 请求发送到 URL。端点通过响应体使用与命令 hooks 相同的 [JSON 输出格式](#json-output) 传回结果。

420* **[MCP 工具 hooks](#mcp-tool-hook-fields)**（`type: "mcp_tool"`）：在已连接的 [MCP 服务器](/docs/zh-CN/mcp) 上调用工具。工具的文本输出被视为命令 hook stdout。422* **[MCP 工具 hooks](#mcp-tool-hook-fields)**（`type: "mcp_tool"`）：在配置的 [MCP 服务器](/docs/zh-CN/mcp) 上调用工具。工具的文本输出被视为命令 hook stdout。

421* **[提示 hooks](#prompt-and-agent-hook-fields)**（`type: "prompt"`）：向 Claude 模型发送提示以进行单轮评估。模型以 JSON 形式返回其决定。请参阅 [基于提示的 hooks](#prompt-based-hooks)。423* **[提示 hooks](#prompt-and-agent-hook-fields)**（`type: "prompt"`）：向 Claude 模型发送提示以进行单轮评估。模型以 JSON 形式返回其决定。请参阅 [基于提示的 hooks](#prompt-based-hooks)。

422* **[代理 hooks](#prompt-and-agent-hook-fields)**（`type: "agent"`）：生成一个子代理，可以使用 Read、Grep 和 Glob 等工具来验证条件，然后返回决定。代理 hooks 是实验性的，可能会改变。请参阅 [基于代理的 hooks](#agent-based-hooks)。424* **[代理 hooks](#prompt-and-agent-hook-fields)**（`type: "agent"`）：生成一个子代理，可以使用 Read、Grep 和 Glob 等工具来验证条件，然后返回决定。代理 hooks 是实验性的，可能会改变。请参阅 [基于代理的 hooks](#agent-based-hooks)。

423 425

424所有匹配的 hooks 并行运行。如果在多个设置文件中定义相同的处理程序，它运行一次。插件或技能的相同处理程序副本保持分离。426所有匹配的 hooks 并行运行。如果在多个设置文件中定义相同的处理程序，它运行一次。插件或技能的相同处理程序副本保持分离。

425 427

426处理程序在当前目录中使用 Claude Code 的环境运行。如果当前目录不再存在，例如另一个 shell 在会话中途删除的 worktree 或临时目录，Claude Code 从以下第一个仍然存在的目录运行命令 hooks：会话启动的目录、项目根目录、主目录或系统临时目录。Claude Code 在 [调试日志](#debug-hooks) 中记录一条警告，命名回退目录。428处理程序在当前目录中使用 Claude Code 的环境运行。如果当前目录不再存在，例如另一个 shell 在会话中途删除的 worktree 或临时目录，Claude Code 从以下第一个仍然存在的目录运行命令 hooks：会话启动的目录、项目根目录、您的主目录或系统临时目录。Claude Code 在 [调试日志](#debug-hooks) 中记录一个警告，命名回退目录。

427 429

428`$CLAUDE_CODE_REMOTE` 环境变量在远程 web 环境中为 `"true"`，在本地 CLI 中未设置。Claude Code v2.1.199 及更高版本在本地会话具有活跃的 Remote Control 连接时将 [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/zh-CN/env-vars) 设置为 [Remote Control](/docs/zh-CN/remote-control) 会话 ID。430`$CLAUDE_CODE_REMOTE` 环境变量在远程 web 环境中为 `"true"`，在本地 CLI 中未设置。Claude Code v2.1.199 及更高版本在本地会话有活跃的远程控制连接时将 [`$CLAUDE_CODE_BRIDGE_SESSION_ID`](/docs/zh-CN/env-vars) 设置为 [远程控制](/docs/zh-CN/remote-control) 会话 ID。

429 431

430<h4 id="common-fields">432<h4 id="common-fields">

431 通用字段433 通用字段

436| 字段 | 必需 | 描述 |438| 字段 | 必需 | 描述 |

437| :- | :- | :- |439| :- | :- | :- |

438| `type` | 是 | `"command"`、`"http"`、`"mcp_tool"`、`"prompt"` 或 `"agent"` |440| `type` | 是 | `"command"`、`"http"`、`"mcp_tool"`、`"prompt"` 或 `"agent"` |

439| `if` | 否 | 权限规则语法来过滤此 hook 何时运行，如 `"Bash(git *)"` 或 `"Edit(*.ts)"`。hook 命令仅在工具调用与模式匹配时运行。有关 Bash 模式如何针对子命令、`$()` 和反引号评估的信息，请参阅下面的 [Bash 匹配表](#bash-if-matching)。仅在工具事件上评估：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 和 `PermissionDenied`。在其他事件上，设置了 `if` 的 hook 永远不会运行。使用与 [权限规则](/docs/zh-CN/permissions) 相同的语法 |441| `if` | 否 | 权限规则语法来过滤此 hook 何时运行，如 `"Bash(git *)"` 或 `"Edit(*.ts)"`。hook 命令仅在工具调用匹配模式时运行。请参阅下面的 [Bash 匹配表](#bash-if-matching) 了解 Bash 模式如何针对子命令、`$()` 和反引号进行评估。仅在工具事件上评估：`PreToolUse`、`PostToolUse`、`PostToolUseFailure`、`PermissionRequest` 和 `PermissionDenied`。在其他事件上，设置了 `if` 的 hook 永远不会运行。使用与 [权限规则](/docs/zh-CN/permissions) 相同的语法 |

440| `timeout` | 否 | 取消前的秒数。Claude Code 不在使用 [`async: true`](#run-hooks-in-the-background) 运行的命令 hook 上强制执行。默认值：`command`、`http` 和 `mcp_tool` 为 600；`prompt` 为 30；`agent` 为 60。Claude Code 在 [`UserPromptSubmit`](#userpromptsubmit)、[`PreModelSwitch`](#premodelswitch) 和 [`PostModelSwitch`](#postmodelswitch) 上将 `command`、`http` 和 `mcp_tool` 默认值降低到 30，在 [`MessageDisplay`](#messagedisplay) 上降低到 10。[`SessionEnd`](#sessionend) hooks 共享 1.5 秒的预算；如果设置设置了更长的每个 hook `timeout`，Claude Code 将预算提高到匹配，最多 60 秒 |442| `timeout` | 否 | 取消前的秒数。Claude Code 不在您使用 [`async: true`](#run-hooks-in-the-background) 运行的命令 hook 上强制执行。默认值：`command`、`http` 和 `mcp_tool` 为 600；`prompt` 为 30；`agent` 为 60。Claude Code 在 [`UserPromptSubmit`](#userpromptsubmit)、[`PreModelSwitch`](#premodelswitch) 和 [`PostModelSwitch`](#postmodelswitch) 上将 `command`、`http` 和 `mcp_tool` 默认值降低到 30，在 [`MessageDisplay`](#messagedisplay) 上降低到 10。[`SessionEnd`](#sessionend) hooks 共享 1.5 秒的预算；如果您的设置设置了更长的每个 hook `timeout`，Claude Code 会提高预算以匹配，最多 60 秒 |

441| `statusMessage` | 否 | hook 运行时显示的自定义微调器消息 |443| `statusMessage` | 否 | hook 运行时显示的自定义微调消息 |

442| `once` | 否 | 如果为 `true`，Claude Code 在第一次成功运行后删除 hook。失败、以退出代码 2 阻止或超时的运行将 hook 保留在原位，因此它在下一个匹配事件上再次运行。仅对在 [技能 frontmatter](#hooks-in-skills-and-agents) 中声明的 hooks 有效；在设置文件和代理 frontmatter 中被忽略 |444| `once` | 否 | 如果为 `true`，Claude Code 在第一次成功运行后删除 hook。失败、以退出代码 2 阻止或超时的运行会将 hook 保留在原位，因此它在下一个匹配事件上再次运行。仅在 [技能 frontmatter](#hooks-in-skills-and-agents) 中声明的 hooks 上受尊重；在设置文件和代理 frontmatter 中被忽略 |

443 445

444`if` 字段恰好包含一个权限规则。没有 `&&`、`||` 或列表语法来组合规则；要应用多个条件，为每个定义一个单独的 hook 处理程序。446`if` 字段恰好包含一个权限规则。没有 `&&`、`||` 或列表语法来组合规则；要应用多个条件，为每个定义一个单独的 hook 处理程序。

445 447

446在文件工具的 `if` 条件中，单段目录模式如 `"Edit(src/**)"` 仅匹配工作目录中的 `src` 目录及其下的文件。要匹配工作目录下任何深度的名为 `src` 的目录，请写 `"Edit(**/src/**)"`。在 v2.1.214 之前，`"Edit(src/**)"` 匹配工作目录下任何深度的名为 `src` 的目录。448在文件工具的 `if` 条件中，单段目录模式如 `"Edit(src/**)"` 仅匹配工作目录中的 `src` 目录及其下的文件。要匹配任何深度的名为 `src` 的目录，请写 `"Edit(**/src/**)"`。在 v2.1.214 之前，`"Edit(src/**)"` 匹配工作目录下任何深度的名为 `src` 的目录。

447 449

448<span id="bash-if-matching" />对于 Bash 模式，hook 命令是否运行取决于模式的形状和 Claude 调用的 Bash 命令。在匹配前剥离前导 `VAR=value` 赋值。450<span id="bash-if-matching" />对于 Bash 模式，您的 hook 命令是否运行取决于模式的形状和 Claude 调用的 Bash 命令。匹配前会剥离前导 `VAR=value` 赋值。

449 451

451| :- | :- | :- | :- |453| :- | :- | :- | :- |

459 459

460当 Claude Code 无法确定 Bash 输入运行哪些命令时，它无论模式如何都运行 hook。因为 `if` 过滤是尽力而为的，使用 [权限系统](/docs/zh-CN/permissions) 而不是 hook 来强制执行硬允许或拒绝。460当 Claude Code 无法确定 Bash 输入运行哪些命令时，它无论如何都会运行您的 hook，无论模式如何。因为 `if` 过滤是尽力而为的，使用 [权限系统](/docs/zh-CN/permissions) 而不是 hook 来强制执行硬允许或拒绝。

461 461

462<h4 id="command-hook-fields">462<h4 id="command-hook-fields">

463 命令 hook 字段463 命令 hook 字段

464</h4>464</h4>

465 465

466除了 [通用字段](#common-fields)，命令 hooks 接受这些字段：466除了 [通用字段](#common-fields) 外，命令 hooks 接受这些字段：

467 467

468| 字段 | 必需 | 描述 |468| 字段 | 必需 | 描述 |

469| :- | :- | :- |469| :- | :- | :- |

479 Exec 形式和 shell 形式479 Exec 形式和 shell 形式

480</h5>480</h5>

481 481

482当设置 `args` 时，命令 hook 以 exec 形式运行，当省略 `args` 时以 shell 形式运行。每当 hook 引用 [路径占位符](#reference-scripts-by-path) 时设置 `args`，因为每个元素作为一个参数传递，不带引号。当需要 shell 功能如管道或 `&&` 时省略 `args`，或当两个问题都不适用时。482当设置 `args` 时，命令 hook 以 exec 形式运行，当省略 `args` 时以 shell 形式运行。每当 hook 引用 [路径占位符](#reference-scripts-by-path) 时设置 `args`，因为每个元素作为一个参数传递，不带引号。当您需要 shell 功能如管道或 `&&` 时省略 `args`，或当两个问题都不适用时。

483 483

484**Exec 形式**在设置 `args` 时运行。Claude Code 在 `PATH` 上解析 `command` 作为可执行文件，并直接使用 `args` 作为参数向量生成它。没有 shell，因此每个 `args` 元素恰好是一个参数，完全按照编写的方式，路径占位符如 `${CLAUDE_PLUGIN_ROOT}` 被替换为 `command` 和每个 `args` 元素中的纯字符串。特殊字符如撇号、`$` 和反引号逐字传递，因为没有 shell 来解释它们。在任何平台上都不会发生 shell 标记化。484**Exec 形式**在存在 `args` 时运行。Claude Code 在 `PATH` 上解析 `command` 作为可执行文件，并直接使用 `args` 作为参数向量生成它。没有 shell，所以每个 `args` 元素恰好是一个参数，完全按照编写的方式，路径占位符如 `${CLAUDE_PLUGIN_ROOT}` 被替换为 `command` 和每个 `args` 元素作为纯字符串。特殊字符如撇号、`$` 和反引号逐字传递，因为没有 shell 来解释它们。在任何平台上都不会发生 shell 标记化。

485 485

486**Shell 形式**在省略 `args` 时运行。`command` 字符串被传递到 shell：在 macOS 和 Linux 上为 `sh -c`，在 Windows 上为 Git Bash，或在未安装 Git Bash 时为 PowerShell。设置 `shell` 字段来明确选择。shell 标记化字符串、扩展变量并解释管道、`&&`、重定向和 globs。486**Shell 形式**在省略 `args` 时运行。`command` 字符串被传递给 shell：macOS 和 Linux 上的 `sh -c`、Windows 上的 Git Bash，或未安装 Git Bash 时的 PowerShell。设置 `shell` 字段来明确选择。shell 标记化字符串、扩展变量并解释管道、`&&`、重定向和 globs。

487 487

488<Note>488<Note>

489 在 Windows 上，exec 形式需要 `command` 解析为真实可执行文件如 `.exe`。npm、npx、eslint 和其他工具在 `node_modules/.bin` 中安装的 `.cmd` 和 `.bat` 垫片不是可执行文件，不能在没有 shell 的情况下生成。要在 exec 形式中运行它们，直接使用 `node` 调用底层脚本，例如 `"command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/node_modules/eslint/bin/eslint.js"]`。`node` 加脚本路径模式在每个平台上都有效，因为 `node.exe` 是真实二进制文件。要按名称运行 `.cmd` 或 `.bat` 垫片，使用 shell 形式。489 在 Windows 上，exec 形式需要 `command` 解析为真实可执行文件如 `.exe`。npm、npx、eslint 和其他工具在 `node_modules/.bin` 中安装的 `.cmd` 和 `.bat` 垫片不是可执行文件，不能在没有 shell 的情况下生成。要在 exec 形式中运行它们，直接使用 `node` 调用底层脚本，例如 `"command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/node_modules/eslint/bin/eslint.js"]`。`node` 加脚本路径模式在每个平台上都有效，因为 `node.exe` 是真实二进制文件。要按名称运行 `.cmd` 或 `.bat` 垫片，使用 shell 形式。

508}508}

509```509```

510 510

511两种形式都支持相同的 [路径占位符](#reference-scripts-by-path)，并且都将它们导出为生成过程上的环境变量 `CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT` 和 `CLAUDE_PLUGIN_DATA`，因此脚本可以读取 `process.env.CLAUDE_PLUGIN_ROOT` 无论如何启动。511两种形式都支持相同的 [路径占位符](#reference-scripts-by-path)，并且两者都将它们导出为生成的进程上的环境变量 `CLAUDE_PROJECT_DIR`、`CLAUDE_PLUGIN_ROOT` 和 `CLAUDE_PLUGIN_DATA`，所以脚本可以读取 `process.env.CLAUDE_PLUGIN_ROOT`，无论它如何启动。

512 512

513插件 hooks 另外替换 [`${user_config.*}`](/docs/zh-CN/plugins/manifest-reference#user-configuration) 值，仅在 exec 形式中：值被替换为 `command` 和每个 `args` 元素中的纯字符串，因此没有 shell 重新解析它。513插件 hooks 另外替换 [`${user_config.*}`](/docs/zh-CN/plugins/manifest-reference#user-configuration) 值，仅在 exec 形式中：值被替换为 `command` 和每个 `args` 元素作为纯字符串，所以没有 shell 重新解析它。

514 514

515shell 形式的插件 hook，其 `command` 引用 `${user_config.*}` 失败并出现 [错误](/docs/zh-CN/errors#plugin-command-references-user-config) 而不是运行。要从 shell 形式的 hook 使用选项值，读取 `$CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量，如 `webhook_url` 选项的 `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL`，或设置 `args` 来将 hook 切换到 exec 形式。在 v2.1.207 之前，shell 形式的插件 hook 命令也替换 `${user_config.*}`。515其 `command` 引用 `${user_config.*}` 的 shell 形式插件 hook 失败并出现 [错误](/docs/zh-CN/errors#plugin-command-references-user-config) 而不是运行。要从 shell 形式 hook 使用选项值，读取 `$CLAUDE_PLUGIN_OPTION_<KEY>` 环境变量，如 `webhook_url` 选项的 `$CLAUDE_PLUGIN_OPTION_WEBHOOK_URL`，或设置 `args` 来将 hook 切换到 exec 形式。在 v2.1.207 之前，shell 形式插件 hook 命令也替换 `${user_config.*}`。

516 516

517<Note>517<Note>

518 在 exec 形式中，`command` 仅是可执行文件名或路径。如果 `command` 是没有路径分隔符的裸名称，并且与 `args` 一起包含空格，Claude Code 记录一条警告，因为生成将失败：没有名为 `node script.js` 的可执行文件。将额外的标记移到 `args` 中。带空格的绝对路径，如 `C:\Program Files\nodejs\node.exe`，是单个有效的可执行文件，不会触发警告。518 在 exec 形式中，`command` 仅是可执行文件名或路径。如果 `command` 是没有路径分隔符的裸名称，并且与 `args` 一起包含空格，Claude Code 记录一个警告，因为生成将失败：没有名为 `node script.js` 的可执行文件。将额外的标记移到 `args` 中。带空格的绝对路径，如 `C:\Program Files\nodejs\node.exe`，是单个有效的可执行文件，不会触发警告。

519</Note>519</Note>

520 520

521<h4 id="http-hook-fields">521<h4 id="http-hook-fields">

522 HTTP hook 字段522 HTTP hook 字段

523</h4>523</h4>

524 524

525除了 [通用字段](#common-fields)，HTTP hooks 接受这些字段：525除了 [通用字段](#common-fields) 外，HTTP hooks 接受这些字段：

526 526

527| 字段 | 必需 | 描述 |527| 字段 | 必需 | 描述 |

528| :- | :- | :- |528| :- | :- | :- |

563 MCP 工具 hook 字段563 MCP 工具 hook 字段

564</h4>564</h4>

565 565

566除了 [通用字段](#common-fields)，MCP 工具 hooks 接受这些字段：566除了 [通用字段](#common-fields) 外，MCP 工具 hooks 接受这些字段：

567 567

568| 字段 | 必需 | 描述 |568| 字段 | 必需 | 描述 |

569| :- | :- | :- |569| :- | :- | :- |

570| `server` | 是 | 配置的 MCP 服务器的名称。对于 [插件捆绑的服务器](/docs/zh-CN/mcp#plugin-provided-mcp-servers)，这是范围名称 `plugin:<plugin-name>:<server-name>`，如 `plugin:my-plugin:db`，不是裸服务器密钥 |570| `server` | 是 | 配置的 MCP 服务器的名称。对于 [插件捆绑的服务器](/docs/zh-CN/mcp#plugin-provided-mcp-servers)，这是范围名称 `plugin:<plugin-name>:<server-name>`，如 `plugin:my-plugin:db`，不是裸服务器密钥 |

571| `tool` | 是 | 在该服务器上调用的工具的名称 |571| `tool` | 是 | 该服务器上要调用的工具的名称 |

572| `input` | 否 | 传递给工具的参数。字符串值支持来自 hook 的 [JSON 输入](#hook-input-and-output) 的 `${path}` 替换，如 `"${tool_input.file_path}"` |572| `input` | 否 | 传递给工具的参数。字符串值支持来自 hook 的 [JSON 输入](#hook-input-and-output) 的 `${path}` 替换，如 `"${tool_input.file_path}"` |

573 573

574此示例在每个 `Write` 或 `Edit` 后在 `my_server` MCP 服务器上调用 `security_scan` 工具，传递编辑文件的路径：574此示例在每个 `Write` 或 `Edit` 后在 `my_server` MCP 服务器上调用 `security_scan` 工具，传递编辑文件的路径：

597 工具结果如何被读取597 工具结果如何被读取

598</h5>598</h5>

599 599

600Claude Code 读取工具的文本内容的方式与读取命令 hook stdout 相同，遵循 [退出代码 0 下的解析规则](#exit-code-0)。如果工具返回 `isError: true`，hook 产生非阻止错误，执行继续。600Claude Code 读取工具的文本内容的方式与读取命令 hook stdout 的方式相同，遵循 [退出代码 0 下的解析规则](#exit-code-0)。如果工具返回 `isError: true`，hook 产生非阻止错误，执行继续。

601 601

602<h5 id="when-the-server-is-still-connecting">602<h5 id="when-the-server-is-still-connecting">

603 当服务器仍在连接时603 当服务器仍在连接时

604</h5>604</h5>

605 605

606在 hook 可以阻止或改变结果的事件上，如 `PreToolUse` 或 `Stop`，Claude Code 在调用工具之前等待连接的服务器，最多 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars) 和在 hook 自己的 [`timeout`](#common-fields) 内。在观察事件上，如 `Notification` 或 `SessionEnd`，它不等待。606在 hook 可以阻止或改变结果的事件上，如 `PreToolUse` 或 `Stop`，Claude Code 在调用工具前等待连接的服务器，最多 [`MCP_TIMEOUT`](/docs/zh-CN/env-vars)，在 hook 自己的 [`timeout`](#common-fields) 内。在观察事件上，如 `Notification` 或 `SessionEnd`，它不等待。

607 607

608显示 [`cached` 状态](/docs/zh-CN/mcp#server-status-detail) 的服务器在 hook 调用其工具时连接。如果服务器在该点未连接，hook 产生非阻止错误，执行继续。hook 永远不会启动 OAuth 流，因此 [从 `/mcp` 先验证服务器](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers)。608显示 [`cached` 状态](/docs/zh-CN/mcp#server-status-detail) 的服务器在 hook 调用其工具时连接。如果服务器在该点未连接，hook 产生非阻止错误，执行继续。hook 永远不会启动 OAuth 流，所以 [从 `/mcp` 验证服务器](/docs/zh-CN/mcp#authenticate-with-remote-mcp-servers)。

609 609

610<h5 id="events-that-fire-before-mcp-servers-are-available">610<h5 id="events-that-fire-before-mcp-servers-are-available">

611 MCP 服务器可用之前触发的事件611 在 MCP 服务器可用之前触发的事件

612</h5>612</h5>

613 613

614`SessionStart` 在启动时（包括使用 `--continue` 或 `--resume`）和每个 `Setup` 事件在会话的 MCP 服务器对 hooks 可用之前触发。Claude Code 跳过其 `mcp_tool` hooks 而不调用工具，[调试日志](#debug-hooks) 记录 `mcp_tool hooks are not available for the 'SessionStart' hook event (no MCP client context)`，或相同的消息命名 `Setup`。当 `SessionStart` 稍后在会话中再次触发时，在 `/clear` 或压缩后，其 `mcp_tool` hooks 运行。对于会话在启动时需要的任何东西，改用 `SessionStart` 上的 `type: "command"` hook。614启动时的 `SessionStart`，包括使用 `--continue` 或 `--resume`，以及每个 `Setup` 事件在会话的 MCP 服务器对 hooks 可用之前触发。Claude Code 跳过其 `mcp_tool` hooks 而不调用工具，[调试日志](#debug-hooks) 记录 `mcp_tool hooks are not available for the 'SessionStart' hook event (no MCP client context)`，或相同的消息命名 `Setup`。当 `SessionStart` 稍后在会话中再次触发时，在 `/clear` 或压缩后，其 `mcp_tool` hooks 运行。对于会话在启动时需要的任何内容，改为在 `SessionStart` 上使用 `type: "command"` hook。

615 615

616<h4 id="prompt-and-agent-hook-fields">616<h4 id="prompt-and-agent-hook-fields">

617 提示和代理 hook 字段617 提示和代理 hook 字段

618</h4>618</h4>

619 619

620除了 [通用字段](#common-fields)，提示和代理 hooks 接受这些字段：620除了 [通用字段](#common-fields) 外，提示和代理 hooks 接受这些字段：

621 621

622| 字段 | 必需 | 描述 |622| 字段 | 必需 | 描述 |

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

628 按路径引用脚本628 按路径引用脚本

629</h3>629</h3>

630 630

631使用这些占位符来相对于项目或插件根目录引用 hook 脚本，无论 hook 运行时的工作目录如何：631使用这些占位符来引用相对于项目或插件根目录的 hook 脚本，无论 hook 运行时的工作目录如何：

632 632

633* `${CLAUDE_PROJECT_DIR}`：会话启动的项目根目录。Claude Code 还在 [stdio MCP 服务器](/docs/zh-CN/mcp#option-3-add-a-local-stdio-server) 和插件 LSP 服务器的环境中设置此变量。633* `${CLAUDE_PROJECT_DIR}`：会话启动的项目根目录。Claude Code 还在 [stdio MCP 服务器](/docs/zh-CN/mcp#option-3-add-a-local-stdio-server) 和插件 LSP 服务器的环境中设置此变量。

634* `${CLAUDE_PLUGIN_ROOT}`：插件的安装目录，用于与 [插件](/docs/zh-CN/plugins/overview) 捆绑的脚本。有关路径在更新中的行为方式，请参阅 [插件环境变量](/docs/zh-CN/plugins/manifest-reference#environment-variables)。634* `${CLAUDE_PLUGIN_ROOT}`：插件的安装目录，用于与 [插件](/docs/zh-CN/plugins/overview) 捆绑的脚本。请参阅 [插件环境变量](/docs/zh-CN/plugins/manifest-reference#environment-variables) 了解路径在更新中的行为。

635* `${CLAUDE_PLUGIN_DATA}`：插件的 [持久数据目录](/docs/zh-CN/plugins/components#path-variables-and-persistent-data)，用于应该在插件更新中存活的依赖项和状态。635* `${CLAUDE_PLUGIN_DATA}`：插件的 [持久数据目录](/docs/zh-CN/plugins/components#path-variables-and-persistent-data)，用于应该在插件更新中存活的依赖项和状态。

636 636

637<Note>637<Note>

638 **Worktrees 是不同的。** 如果 Claude 在会话期间进入 [worktree](/docs/zh-CN/worktrees)，Claude Code 将 `${CLAUDE_PROJECT_DIR}` 保持在原位，并以不同的方式将 worktree 路径传递给 hooks：638 **Worktrees 是不同的。** 如果 Claude 在会话期间进入 [worktree](/docs/zh-CN/worktrees)，Claude Code 保持 `${CLAUDE_PROJECT_DIR}` 在原位，并以不同的方式将 worktree 路径传递给您的 hooks：

639 639

640 * **`${CLAUDE_PROJECT_DIR}` 保持不变**：它仍然指向会话启动的项目根目录，因此像 `${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh` 这样的命令仍然在主检出中运行脚本。640 * **`${CLAUDE_PROJECT_DIR}` 保持不变**：它仍然指向会话启动的项目根目录，所以像 `${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh` 这样的命令仍然在主检出中运行脚本。

641 * **`cwd` 跟随 Claude**：hook 的 [输入 JSON](#common-input-fields) 中的 `cwd` 字段在 Claude 进入 worktree 后是 worktree 根目录，在 Claude 运行 `cd` 后是新目录。当 hook 需要知道 Claude 正在处理哪个目录时读取它。641 * **`cwd` 跟随 Claude**：hook 的 [输入 JSON](#common-input-fields) 中的 `cwd` 字段在 Claude 进入 worktree 后是 worktree 根目录，在 Claude 运行 `cd` 后是新目录。当 hook 需要知道 Claude 正在哪个目录中工作时读取它。

642</Note>642</Note>

643 643

644对于任何引用路径占位符的 hook，优先使用 [exec 形式](#exec-form-and-shell-form)。在 shell 形式中，用双引号包装每个占位符。644对于任何引用路径占位符的 hook，优先使用 [exec 形式](#exec-form-and-shell-form)。在 shell 形式中，用双引号包装每个占位符。

668 </Tab>668 </Tab>

669 669

670 <Tab title="插件脚本">670 <Tab title="插件脚本">

671 在 `hooks/hooks.json` 中定义插件 hooks，带有可选的顶级 `description` 字段。启用插件时，其 hooks 与用户和项目 hooks 合并。671 在 `hooks/hooks.json` 中定义插件 hooks，带有可选的顶级 `description` 字段。启用插件时，其 hooks 与您的用户和项目 hooks 合并。

672 672

673 此示例运行与插件捆绑的格式化脚本：673 此示例运行与插件捆绑的格式化脚本：

674 674

698</Tabs>698</Tabs>

699 699

700<h3 id="hooks-in-skills-and-agents">700<h3 id="hooks-in-skills-and-agents">

701 Hooks in skills and agents701 Skills 和代理中的 Hooks

702</h3>702</h3>

703 703

704除了设置文件和插件，hooks 可以直接在 [skills](/docs/zh-CN/skills) 和 [subagents](/docs/zh-CN/sub-agents) 中使用 frontmatter 定义，采用与基于设置的 hooks 相同的配置格式。Claude Code 保持它们注册多长时间取决于组件：704除了设置文件和插件外，hooks 可以直接在 [skills](/docs/zh-CN/skills) 和 [subagents](/docs/zh-CN/sub-agents) 中使用 frontmatter 定义，采用与基于设置的 hooks 相同的配置格式。Claude Code 保持它们注册多长时间取决于组件：

705 705

706* **Subagent hooks**：Claude Code 仅在该子代理运行时运行它们，并在完成时删除它们。Claude Code 在此处将 `Stop` hook 转换为 `SubagentStop`，这是它在子代理完成时触发的事件。706* **Subagent hooks**：Claude Code 仅在该子代理运行时运行它们，并在其完成时删除它们。Claude Code 在此处将 `Stop` hook 转换为 `SubagentStop`，这是它在子代理完成时触发的事件。

707* **Skill hooks**：Claude Code 在调用技能时注册它们，并在会话的其余部分保持运行它们，在技能自己的轮次之后的轮次上也是如此。要让 Claude Code 在第一次成功运行后删除 hook，请在其上设置 [`once: true`](#common-fields)。707* **Skill hooks**：Claude Code 在您或 Claude 调用技能时注册它们，并为会话的其余部分保持运行它们，在技能自己的回合之后的回合上也是如此。要让 Claude Code 在第一次成功运行后删除 hook，改为在其上设置 [`once: true`](#common-fields)。

708 708

709此技能定义了一个 `PreToolUse` hook，在每个 `Bash` 命令之前运行安全验证脚本：709此技能定义了一个 `PreToolUse` hook，在每个 `Bash` 命令前运行安全验证脚本：

710 710

711```yaml theme={null}711```yaml theme={null}

712---712---

723 723

724Subagents 在其 YAML frontmatter 中使用相同的格式。724Subagents 在其 YAML frontmatter 中使用相同的格式。

725 725

726项目技能中的 Frontmatter hooks 遵循与设置文件中的 hooks 相同的 [工作区信任规则](#workspace-trust)。Claude Code 在调用技能时注册它们，包括在未信任的文件夹中的 `-p` 运行。726项目技能中的 Frontmatter hooks 遵循与设置文件中的 hooks 相同的 [工作区信任规则](#workspace-trust)。Claude Code 在您或 Claude 调用技能时注册它们，包括在您未信任的文件夹中的 `-p` 运行。

727 727

728项目子代理中的 Frontmatter hooks 仅在接受代理文件来自的文件夹的 [工作区信任对话](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust) 后运行。`-p` 会话不计为接受它。[在信任文件夹之前运行的内容](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 将此与设置文件规则进行比较，subagents 页面列出 [哪些范围被豁免](/docs/zh-CN/sub-agents#hooks-in-subagent-frontmatter)。在 v2.1.218 之前，这些 hooks 可以从未信任的文件夹运行。728项目子代理中的 Frontmatter hooks 仅在您接受代理文件来自的文件夹的 [工作区信任对话](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust) 后运行。`-p` 会话不计为接受它。[在您信任文件夹前运行的内容](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 将此与设置文件规则进行比较，subagents 页面列出 [哪些范围被豁免](/docs/zh-CN/sub-agents#hooks-in-subagent-frontmatter)。在 v2.1.218 之前，这些 hooks 可以从您未信任的文件夹运行。

729 729

730<h3 id="the-/hooks-menu">730<h3 id="the-/hooks-menu">

731 `/hooks` 菜单731 `/hooks` 菜单

732</h3>732</h3>

733 733

734在 Claude Code 中键入 `/hooks` 以打开配置的 hooks 的只读浏览器。菜单显示每个 hook 事件及其配置的 hooks 计数，让你深入了解匹配器，并显示每个 hook 处理程序的完整详细信息。使用它来验证配置、检查 hook 来自哪个设置文件或检查 hook 的命令、提示或 URL。734在 Claude Code 中键入 `/hooks` 来打开已配置 hooks 的只读浏览器。菜单显示每个 hook 事件及其配置的 hooks 计数，让您深入了解匹配器，并显示每个 hook 处理程序的完整详细信息。使用它来验证配置、检查 hook 来自哪个设置文件，或检查 hook 的命令、提示或 URL。

735 735

736菜单显示所有五种 hook 类型：`command`、`prompt`、`agent`、`http` 和 `mcp_tool`。每个 hook 都标有 `[type]` 前缀和指示其定义位置的源：736菜单显示所有五种 hook 类型：`command`、`prompt`、`agent`、`http` 和 `mcp_tool`。每个 hook 都标有 `[type]` 前缀和指示其定义位置的源：

737 737

741* `Plugin Hooks`：来自插件的 `hooks/hooks.json`741* `Plugin Hooks`：来自插件的 `hooks/hooks.json`

742* `Session Hooks`：为当前会话在内存中注册742* `Session Hooks`：为当前会话在内存中注册

743 743

744选择 hook 打开详细视图，显示其事件、匹配器、类型、源文件和完整命令、提示或 URL。菜单是只读的：要添加、修改或删除 hooks，直接编辑设置 JSON 或要求 Claude 进行更改。744选择 hook 打开详细视图，显示其事件、匹配器、类型、源文件以及完整的命令、提示或 URL。菜单是只读的：要添加、修改或删除 hooks，直接编辑设置 JSON 或要求 Claude 进行更改。

745 745

746<h3 id="disable-or-remove-hooks">746<h3 id="disable-or-remove-hooks">

747 禁用或删除 hooks747 禁用或删除 hooks

749 749

750要删除 hook，从设置 JSON 文件中删除其条目。750要删除 hook，从设置 JSON 文件中删除其条目。

751 751

752要临时禁用所有 hooks 而不删除它们，在设置文件中设置 `"disableAllHooks": true`。Claude Code 读取 [设置优先级](/docs/zh-CN/settings#settings-precedence) 应用后留下的值，因此项目的 `.claude/settings.json` 中的 `"disableAllHooks": false` 覆盖用户设置中的 `true`。要关闭一次运行，无论项目的设置如何，传递 `--settings '{"disableAllHooks": true}'`，这优先于项目和本地设置。没有办法禁用单个 hook 同时将其保留在配置中。752要临时禁用所有 hooks 而不删除它们，在设置文件中设置 `"disableAllHooks": true`。Claude Code 读取 [设置优先级](/docs/zh-CN/settings#settings-precedence) 应用后留下的值，所以项目的 `.claude/settings.json` 中的 `"disableAllHooks": false` 覆盖用户设置中的 `true`。要无论项目的设置如何关闭一次运行的 hooks，传递 `--settings '{"disableAllHooks": true}'`，这优先于项目和本地设置。没有办法在保持 hook 在配置中的同时禁用单个 hook。

753 753

754`disableAllHooks` 设置尊重托管设置层次结构。如果管理员通过托管策略设置配置了 hooks，在用户、项目或本地设置中设置的 `disableAllHooks` 无法禁用这些托管 hooks。仅在托管设置级别设置的 `disableAllHooks` 可以禁用托管 hooks。有关每个级别的完整范围，请参阅 [`disableAllHooks`](/docs/zh-CN/settings-reference#disableallhooks)。754`disableAllHooks` 设置尊重托管设置层次结构。如果管理员通过托管策略设置配置了 hooks，在用户、项目或本地设置中设置的 `disableAllHooks` 无法禁用这些托管 hooks。仅在托管设置级别设置的 `disableAllHooks` 可以禁用托管 hooks。对于每个级别的完整范围，请参阅 [`disableAllHooks`](/docs/zh-CN/settings-reference#disableallhooks)。

755 755

756设置文件中对 hooks 的直接编辑通常由文件监视程序自动拾取。756对设置文件中 hooks 的直接编辑通常由文件监视程序自动拾取。

757 757

758<h2 id="hook-input-and-output">758<h2 id="hook-input-and-output">

759 Hook 输入和输出759 Hook 输入和输出

hooks-guide.md +3 −1

Details

1014 1014

1015`PreToolUse` hooks 在任何权限模式检查之前触发，在每个[权限模式](/docs/zh-CN/permission-modes)中，包括 `dontAsk`。返回 `permissionDecision: "deny"` 的 hook 会阻止工具，即使在 `bypassPermissions` 模式或使用 `--dangerously-skip-permissions` 时也是如此。这让你强制执行用户无法通过更改其权限模式来绕过的策略。1015`PreToolUse` hooks 在任何权限模式检查之前触发，在每个[权限模式](/docs/zh-CN/permission-modes)中，包括 `dontAsk`。返回 `permissionDecision: "deny"` 的 hook 会阻止工具，即使在 `bypassPermissions` 模式或使用 `--dangerously-skip-permissions` 时也是如此。这让你强制执行用户无法通过更改其权限模式来绕过的策略。

1016 1016

1017反面不成立：返回 `"allow"` 的 hook 不会绕过来自设置的拒绝规则，它也无法抑制标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具的提示或[你的组织设置为 `ask`](/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具在该设置到达 Claude Code 的会话中的提示。Hooks 可以收紧限制，但不能放松它们超过权限规则允许的范围。1017反面不成立：返回 `"allow"` 的 hook 不会绕过来自设置的拒绝规则，它也无法抑制标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具的提示或[你的组织设置为 `ask`](/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的连接器工具在该设置到达 Claude Code 的会话中的提示。Hooks 在设置文件和插件的 `hooks/hooks.json` 中可以收紧限制，但不能放松它们超过权限规则允许的范围。

1018

1019一个你安装的[mod](/docs/zh-CN/plugins/mods/overview)如果 hooks `tool.check` 可以批准你的 `PreToolUse` hook 阻止的调用，除非该 hook 在托管设置中。[使用 hooks 扩展权限](/docs/zh-CN/permissions#extend-permissions-with-hooks)列出了哪些规则优先于 mod。

1018 1020

1019<h3 id="hook-not-firing">1021<h3 id="hook-not-firing">

1020 Hook 未触发1022 Hook 未触发

interactive-mode.md +4 −6

Details

346* 提示 Claude Code 在后台运行命令346* 提示 Claude Code 在后台运行命令

347* 按 `Ctrl+B` 将常规 Bash 工具调用移到后台。Tmux 用户必须按两次 `Ctrl+B`，因为 tmux 有前缀键。347* 按 `Ctrl+B` 将常规 Bash 工具调用移到后台。Tmux 用户必须按两次 `Ctrl+B`，因为 tmux 有前缀键。

348 348

349当命令在完成前达到超时时，Claude Code 会自动[将其移到后台](/docs/zh-CN/tools-reference#background-commands)而不是停止它，除非命令以 `sleep` 开头。要更改命令在此之前运行多长时间，请设置 [Bash 超时环境变量](/docs/zh-CN/tools-reference#timeout-and-output-limits)。349当命令在完成前达到超时时，Claude Code 会自动[将其移到后台](/docs/zh-CN/tools-reference#foreground-commands-that-move-to-the-background)而不是停止它，除非命令以 `sleep` 开头。如果你已通过 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/zh-CN/env-vars#variables) 关闭了后台任务，或通过启动[裸模式](/docs/zh-CN/headless#start-faster-with-bare-mode)，命令会在超时时停止。要更改超时，请设置 [Bash 超时环境变量](/docs/zh-CN/tools-reference#timeout-and-output-limits)。

350 350

351**主要功能：**351**主要功能：**

352 352

358* 在 macOS 和 Linux 上，当操作系统报告严重内存压力时，Claude Code 会停止运行中的后台任务，前提是会话已空闲至少 30 分钟且没有 turn 或 subagent 运行。需要 Claude Code v2.1.193 或更高版本358* 在 macOS 和 Linux 上，当操作系统报告严重内存压力时，Claude Code 会停止运行中的后台任务，前提是会话已空闲至少 30 分钟且没有 turn 或 subagent 运行。需要 Claude Code v2.1.193 或更高版本

359 * [调试日志](/docs/zh-CN/debug-your-config)说明了为什么任务被停止，或为什么压力事件让它们继续运行359 * [调试日志](/docs/zh-CN/debug-your-config)说明了为什么任务被停止，或为什么压力事件让它们继续运行

360 * 将 [`CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP`](/docs/zh-CN/env-vars) 设置为 `1` 可关闭内存压力停止360 * 将 [`CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP`](/docs/zh-CN/env-vars) 设置为 `1` 可关闭内存压力停止

361* 后台 Bash 和 PowerShell 命令有时间限制，从命令进入后台的时刻开始计算：30 分钟，或 Claude 在启动后台命令时要求的 `timeout`，最多 2 小时。在运行时移到后台的命令（例如使用 `Ctrl+B`）从移动时获得 30 分钟。当命令达到其限制时，Claude Code 会停止它并告诉 Claude 原因，Claude 可以使用更长的 `timeout` 重新启动它，如果工作仍然需要的话。两个环境变量提高限制（以毫秒为单位），两者都不能缩短限制：361* 后台 Bash 和 PowerShell 命令有时间限制，从命令进入后台的时刻开始计算：30 分钟，或 Claude 在启动后台命令时要求的 `timeout`，最多 2 小时。在运行时移到后台的命令（例如使用 `Ctrl+B`）从移动时获得 30 分钟。当命令达到其限制时，Claude Code 会停止它并告诉 Claude 原因，Claude 可以使用更长的 `timeout` 重新启动它，如果工作仍然需要的话。要延长限制，请参阅工具参考中的[提高后台命令的时间限制](/docs/zh-CN/tools-reference#raise-the-time-limit-for-background-commands)

362 * 将 [`BASH_DEFAULT_TIMEOUT_MS`](/docs/zh-CN/env-vars) 设置为 `1800000` 以上，以用该值替换 30 分钟的默认值，也适用于移动的命令362* 由前台[子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)启动的后台命令在该子代理的运行结束时结束，无论是完成、失败还是被中断；请参阅工具参考中的[后台命令何时停止](/docs/zh-CN/tools-reference#when-a-background-command-stops)

363 * 将 [`BASH_MAX_TIMEOUT_MS`](/docs/zh-CN/env-vars) 设置为 `7200000` 以上以提高 2 小时的最大值。将 `BASH_DEFAULT_TIMEOUT_MS` 设置为 `7200000` 以上会以相同方式提高它

364* 由前台[子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)启动的后台命令在该子代理的运行结束时结束，无论是完成、失败还是被中断；请参阅工具参考中的[后台命令](/docs/zh-CN/tools-reference#background-commands)

365 363

366要禁用所有后台任务功能，请将 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 环境变量设置为 `1`。有关详细信息，请参阅[环境变量](/docs/zh-CN/env-vars)。364要禁用所有后台任务功能，请将 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](/docs/zh-CN/env-vars#variables) 环境变量设置为 `1`。启动[裸模式](/docs/zh-CN/headless#start-faster-with-bare-mode)也会关闭它。

367 365

368**常见的后台命令：**366**常见的后台命令：**

369 367

keybindings.md +1 −3

Details

545* 在非拉丁布局（如西里尔字母）下，当终端使用 Kitty 键盘协议并报告该位置时，Claude Code 通过按键的美国布局位置来匹配 Ctrl 快捷键。在这样的终端中，使用俄语布局时，按下 Ctrl 和物理 W 键会触发 `ctrl+w`。在不报告位置的终端中，Claude Code 匹配终端为按键发送的任何内容：ASCII 控制代码触发拉丁快捷键，作为西里尔字符到达的按键不匹配任何绑定545* 在非拉丁布局（如西里尔字母）下，当终端使用 Kitty 键盘协议并报告该位置时，Claude Code 通过按键的美国布局位置来匹配 Ctrl 快捷键。在这样的终端中，使用俄语布局时，按下 Ctrl 和物理 W 键会触发 `ctrl+w`。在不报告位置的终端中，Claude Code 匹配终端为按键发送的任何内容：ASCII 控制代码触发拉丁快捷键，作为西里尔字符到达的按键不匹配任何绑定

546* 在重新排列拉丁字母的布局（如 AZERTY）下，Claude Code 匹配按键输入的字母，因此按下 Ctrl 和标记为 A 的按键会触发 `ctrl+a`546* 在重新排列拉丁字母的布局（如 AZERTY）下，Claude Code 匹配按键输入的字母，因此按下 Ctrl 和标记为 A 的按键会触发 `ctrl+a`

547 547

548在 v2.1.247 之前，在使用 Kitty 键盘协议的终端（如 Ghostty、Kitty、WezTerm 和 iTerm2）中，在非拉丁布局下按下 Ctrl 快捷键不会触发其绑定。

~~549~~

550<h3 id="chords">548<h3 id="chords">

551 和弦549 和弦

552</h3>550</h3>

697* 拼写错误的修饰符，例如 `ctl+k`。Claude Code 会删除它无法识别的部分，并将绑定应用于剩余的按键，在此示例中为 `k`。695* 拼写错误的修饰符，例如 `ctl+k`。Claude Code 会删除它无法识别的部分，并将绑定应用于剩余的按键，在此示例中为 `k`。

698* 无效的上下文名称696* 无效的上下文名称

699* 无效的操作值，例如不是字符串或 `null` 的操作697* 无效的操作值，例如不是字符串或 `null` 的操作

700* 未知的操作名称，例如注册操作的拼写错误。Claude Code 跳过该绑定并保持该键的任何默认绑定有效。在 v2.1.246 之前，具有未知操作名称的绑定会静默禁用该键698* 未知的操作名称，例如注册操作的拼写错误。Claude Code 跳过该绑定并保持该键的任何默认绑定有效。

701* 保留快捷键冲突699* 保留快捷键冲突

702* 同一上下文中的重复绑定700* 同一上下文中的重复绑定

703 701

llm-gateway.md +2 −0

Details

45 45

46[为您的组织部署 LLM 网关](/docs/zh-CN/llm-gateway-rollout)逐步讲解每个步骤，并显示在每个步骤中分发的配置文件。网关是组织设置的一部分；对于策略强制执行、使用情况可见性和数据处理决策，请参阅[为您的组织设置 Claude Code](/docs/zh-CN/admin-setup)。46[为您的组织部署 LLM 网关](/docs/zh-CN/llm-gateway-rollout)逐步讲解每个步骤，并显示在每个步骤中分发的配置文件。网关是组织设置的一部分；对于策略强制执行、使用情况可见性和数据处理决策，请参阅[为您的组织设置 Claude Code](/docs/zh-CN/admin-setup)。

47 47

48要使通过 `ANTHROPIC_BASE_URL` 访问的网关成为托管机器唯一可以使用的目标，请在同一托管设置文件中将 [`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders) 设置为 `["customEndpoint"]`，并将网关的 `ANTHROPIC_BASE_URL` 放在该文件的 `env` 块中。Claude Code 随后会拒绝指向其他任何地方的会话，包括直接指向 Anthropic 或开发人员自己的代理，并仅接受您在那里设置的值的 `ANTHROPIC_BASE_URL`。对于通过提供商特定端点变量（如 `ANTHROPIC_BEDROCK_BASE_URL`）访问的网关，`allowedProviders` 条目指定要固定的变量。需要 Claude Code v2.1.285 或更高版本。

48<h2 id="subscriptions-and-gateways">50<h2 id="subscriptions-and-gateways">

49 订阅和网关51 订阅和网关

50</h2>52</h2>

llm-gateway-protocol.md +1 −1

Details

310 310

311Claude Code 使用下面两个凭证请求头发送发现请求，并省略其值无法解析的请求头。发送两个请求头需要 Claude Code v2.1.248 或更高版本。早期版本在设置了 `ANTHROPIC_AUTH_TOKEN` 时仅发送 `Authorization`，否则仅发送 `x-api-key`。311Claude Code 使用下面两个凭证请求头发送发现请求，并省略其值无法解析的请求头。发送两个请求头需要 Claude Code v2.1.248 或更高版本。早期版本在设置了 `ANTHROPIC_AUTH_TOKEN` 时仅发送 `Authorization`，否则仅发送 `x-api-key`。

312 312

313* `Authorization`：`ANTHROPIC_AUTH_TOKEN` 作为承载令牌，否则 [`apiKeyHelper`](/docs/zh-CN/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 值作为承载令牌。在这种情况下，Claude Code 在发送请求前等待助手返回。313* `Authorization`：`ANTHROPIC_AUTH_TOKEN` 作为承载令牌，否则 [`apiKeyHelper`](/docs/zh-CN/llm-gateway-connect#rotate-credentials-with-apikeyhelper) 值作为承载令牌。

314* `x-api-key`：Claude Code 解析的 API 密钥，例如 `ANTHROPIC_API_KEY`。当助手值是唯一的凭证时，此请求头也会携带它，因此该值会在两个请求头中到达。314* `x-api-key`：Claude Code 解析的 API 密钥，例如 `ANTHROPIC_API_KEY`。当助手值是唯一的凭证时，此请求头也会携带它，因此该值会在两个请求头中到达。

315 315

316Claude Code 还发送来自 `ANTHROPIC_CUSTOM_HEADERS` 的任何请求头。当自定义请求头具有非空值时，Claude Code 会发送它来代替同名的内置请求头，不区分大小写地匹配名称。316Claude Code 还发送来自 `ANTHROPIC_CUSTOM_HEADERS` 的任何请求头。当自定义请求头具有非空值时，Claude Code 会发送它来代替同名的内置请求头，不区分大小写地匹配名称。

managed-settings.md +8 −2

Details

199 199

200[网关登录键](#choose-a-delivery-mechanism) 遵循单独的规则。Claude Code 从不从服务器管理的设置读取它们，因此当服务器管理的设置是选定的源时，机器上排名最高的具有策略键的管理员源仍然提供它们。排名低于该源的管理员源中的值，或 HKCU 注册表中的值，被忽略。200[网关登录键](#choose-a-delivery-mechanism) 遵循单独的规则。Claude Code 从不从服务器管理的设置读取它们，因此当服务器管理的设置是选定的源时，机器上排名最高的具有策略键的管理员源仍然提供它们。排名低于该源的管理员源中的值，或 HKCU 注册表中的值，被忽略。

201 201

202[`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders) 有自己的规则：其条目的 Scope 注释说明机器上设置的列表如何与服务器管理的列表组合。需要 Claude Code v2.1.285 或更高版本。

203

202当管理员源设置 `allowManagedMcpServersOnly` 或 `allowedMcpServers` 列表且该值不是生效的值时，`/status` 和 `claude doctor` 命名该源和键。204当管理员源设置 `allowManagedMcpServersOnly` 或 `allowedMcpServers` 列表且该值不是生效的值时，`/status` 和 `claude doctor` 命名该源和键。

203 205

204<h3 id="compose-every-managed-source">206<h3 id="compose-every-managed-source">

353* 空的托管设置文件计为 `{}`。355* 空的托管设置文件计为 `{}`。

354* 用户可写的 HKCU 注册表密钥中的格式错误的值永远不会阻止启动。Claude Code 在 `/status` 和 `claude doctor` 中将其报告为通知。356* 用户可写的 HKCU 注册表密钥中的格式错误的值永远不会阻止启动。Claude Code 在 `/status` 和 `claude doctor` 中将其报告为通知。

355 357

356如果无法读取托管设置文件、drop-in 文件或 `managed-settings.d/` 目录，且没有管理员源提供策略，使用 claude.ai 或 Claude Console 凭据登录的会话将在启动时退出，并显示联系管理员的消息。358当托管设置文件、drop-in 文件、`managed-settings.d/` 目录、MDM 配置文件或 HKLM 注册表值存在但无法读取，且没有管理员源提供策略时，发生的情况取决于读取失败的原因：

359

360* 如果操作系统拒绝了读取，例如在仅限 root 的文件上，每个会话都会在没有该源的策略的情况下启动。`/status` 和 `claude doctor` 记录失败，使用 `-p` 运行也会将其打印到 stderr。

361* 对于任何其他读取失败，例如 I/O 错误，每个会话在启动时以[联系管理员的消息](/docs/zh-CN/errors#unable-to-read-managed-policy-settings)退出。

357 362

358要查找丢弃的条目，请查看以下三个位置之一：363要查找丢弃的条目，请查看以下三个位置之一：

359 364

387| 字段 | 存在但无效时的行为 |392| 字段 | 存在但无效时的行为 |

388| :- | :- |393| :- | :- |

389| `allowedMcpServers` | 强制执行为空的允许列表，直到修复该值，因此用户添加的 MCP 服务器都不被允许。您的组织通过 [`managedMcpServers`](/docs/zh-CN/settings-reference#managedmcpservers) 传递的服务器仍然加载，`managed-mcp.json` 服务器根据[如何评估服务器](/docs/zh-CN/managed-mcp#how-a-server-is-evaluated)加载。单个无效条目被剥离，有效子集被强制执行。 |394| `allowedMcpServers` | 强制执行为空的允许列表，直到修复该值，因此用户添加的 MCP 服务器都不被允许。您的组织通过 [`managedMcpServers`](/docs/zh-CN/settings-reference#managedmcpservers) 传递的服务器仍然加载，`managed-mcp.json` 服务器根据[如何评估服务器](/docs/zh-CN/managed-mcp#how-a-server-is-evaluated)加载。单个无效条目被剥离，有效子集被强制执行。 |

395| [`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders) | 强制执行为空的允许列表，直到修复该值，因此每个 API 提供商都被拒绝，Claude Code 在机器上不启动。如果只有单个条目不是已知的提供商名称，Claude Code 会丢弃并报告该条目并强制执行其余的。 |

390| `allowedHttpHookUrls` | Claude Code 强制执行空的托管[允许列表](/docs/zh-CN/settings-reference#allowedhttphookurls)，直到您修复该值，因此 HTTP hook 仅在另一个设置文件列出其 URL 时运行。如果只有单个条目无效，Claude Code 会剥离该条目并强制执行其余的。 |396| `allowedHttpHookUrls` | Claude Code 强制执行空的托管[允许列表](/docs/zh-CN/settings-reference#allowedhttphookurls)，直到您修复该值，因此 HTTP hook 仅在另一个设置文件列出其 URL 时运行。如果只有单个条目无效，Claude Code 会剥离该条目并强制执行其余的。 |

391| `httpHookAllowedEnvVars` | Claude Code 强制执行空的托管[允许列表](/docs/zh-CN/settings-reference#httphookallowedenvvars)，直到您修复该值，因此仅当另一个设置文件命名标头变量时才会插值。如果只有单个条目无效，Claude Code 会剥离该条目并强制执行其余的。 |397| `httpHookAllowedEnvVars` | Claude Code 强制执行空的托管[允许列表](/docs/zh-CN/settings-reference#httphookallowedenvvars)，直到您修复该值，因此仅当另一个设置文件命名标头变量时才会插值。如果只有单个条目无效，Claude Code 会剥离该条目并强制执行其余的。 |

437 443

438大多数是锁：锁管理的值，例如权限规则或 `sandbox.network.allowedDomains`，是任何级别都可以设置的普通密钥，锁告诉 Claude Code 仅尊重托管值。444大多数是锁：锁管理的值，例如权限规则或 `sandbox.network.allowedDomains`，是任何级别都可以设置的普通密钥，锁告诉 Claude Code 仅尊重托管值。

439 445

440表涵盖权限、插件和交付控制。对于此处未列出的任何密钥，[设置参考](/docs/zh-CN/settings-reference#all-settings)索引的 Scope 列说明它是否仅托管；那里的剩余仅托管密钥包括网关登录 URL、版本、浏览器、移动模拟器、SSH 主机、Desktop 本地会话、沙箱二进制路径、模型定价、模型限制和 CLAUDE.md 控制。446表涵盖权限、插件和交付控制。对于此处未列出的任何密钥，[设置参考](/docs/zh-CN/settings-reference#all-settings)索引的 Scope 列说明它是否仅托管。

441 447

442| 设置 | 描述 |448| 设置 | 描述 |

443| :- | :- |449| :- | :- |

mcp.md +97 −93

Details

128 128

129Claude Code 在生成的服务器的环境中设置 `CLAUDE_PROJECT_DIR` 为项目根目录，以便您的服务器可以解析项目相对路径，而不依赖于工作目录。这与 hooks 在其 `CLAUDE_PROJECT_DIR` 变量中接收的目录相同。从服务器进程内读取它，例如 Node 中的 `process.env.CLAUDE_PROJECT_DIR` 或 Python 中的 `os.environ["CLAUDE_PROJECT_DIR"]`。129Claude Code 在生成的服务器的环境中设置 `CLAUDE_PROJECT_DIR` 为项目根目录，以便您的服务器可以解析项目相对路径，而不依赖于工作目录。这与 hooks 在其 `CLAUDE_PROJECT_DIR` 变量中接收的目录相同。从服务器进程内读取它，例如 Node 中的 `process.env.CLAUDE_PROJECT_DIR` 或 Python 中的 `os.environ["CLAUDE_PROJECT_DIR"]`。

130 130

131`CLAUDE_PROJECT_DIR` 是稳定的项目根目录，在会话中添加或删除工作目录时不会更改。限制自己的文件系统访问到一组允许目录的服务器应该改为实现 MCP `roots/list` 请求。Claude Code 使用会话的启动目录加上您使用 `--add-dir`、`/add-dir` 或 `additionalDirectories` 设置授予的每个 [额外工作目录](/docs/zh-CN/permissions#working-directories) 来回答 `roots/list`。当该集合更改时，Claude Code 发送 `notifications/roots/list_changed`。在 v2.1.203 之前，`roots/list` 仅返回启动目录，Claude Code 不发送 `notifications/roots/list_changed`。131`CLAUDE_PROJECT_DIR` 是稳定的项目根目录，在会话中添加或删除工作目录时不会更改。限制自己的文件系统访问到一组允许目录的服务器应该改为实现 MCP `roots/list` 请求。Claude Code 使用会话的启动目录加上您通过 `--add-dir`、`/add-dir` 或 `additionalDirectories` 设置授予的每个 [额外工作目录](/docs/zh-CN/permissions#working-directories) 来回答 `roots/list`。当该集合更改时，Claude Code 发送 `notifications/roots/list_changed`。在 v2.1.203 之前，`roots/list` 仅返回启动目录，Claude Code 不发送 `notifications/roots/list_changed`。

132 132

133此变量在服务器的环境中设置，而不是在 Claude Code 自己的环境中，因此通过项目范围的 `.mcp.json` 条目或 `~/.claude.json` 中的本地或用户范围服务器条目中的 `command` 或 `args` 中的 `${VAR}` 扩展来引用它需要默认值，例如 `${CLAUDE_PROJECT_DIR:-.}`。插件提供的 MCP 配置直接替换 `${CLAUDE_PROJECT_DIR}` 并且不需要默认值。133此变量在服务器的环境中设置，而不是在 Claude Code 自己的环境中，因此通过项目范围的 `.mcp.json` 条目或 `~/.claude.json` 中的本地或用户范围服务器条目中的 `command` 或 `args` 中的 `${VAR}` 扩展来引用它需要默认值，例如 `${CLAUDE_PROJECT_DIR:-.}`。插件提供的 MCP 配置直接替换 `${CLAUDE_PROJECT_DIR}` 并且不需要默认值。

134 134

169 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'169 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

170```170```

171 171

172`type: "ws"` 条目接受与 `http` 相同的 `url`、`headers`、`headersHelper`、`timeout` 和 `alwaysLoad` 字段。身份验证仅限于标头，因此在 `headers` 中传递静态令牌或使用 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 在连接时生成一个。`claude mcp add --transport` 标志不接受 `ws`。172`type: "ws"` 条目接受与 `http` 相同的 `url`、`headers`、`headersHelper`、`timeout` 和 `alwaysLoad` 字段。身份验证仅限标头，因此在 `headers` 中传递静态令牌或在连接时使用 [`headersHelper`](#use-dynamic-headers-for-custom-authentication) 生成一个。`claude mcp add --transport` 标志不接受 `ws`。

173 173

174<h3 id="add-a-server-from-setup-instructions-written-for-another-client">174<h3 id="add-a-server-from-setup-instructions-written-for-another-client">

175 从为另一个客户端编写的设置说明添加服务器175 从为另一个客户端编写的设置说明添加服务器

199 从 `npx`、`uvx` 或二进制命令199 从 `npx`、`uvx` 或二进制命令

200</h4>200</h4>

201 201

202启动命令表示服务器作为本地 stdio 进程运行。将整个命令放在 `--` 之后，以便 Claude Code 将标志（例如 `-y`）传递给启动服务器的命令，而不是将其读取为自己的选项。使用 `--env` 传递说明要求的任何环境变量，在服务器名称之后和 `--` 之前：202启动命令表示服务器作为本地 stdio 进程运行。将整个命令放在 `--` 之后，以便 Claude Code 将标志（如 `-y`）传递给启动服务器的命令，而不是将它们读取为自己的选项。使用 `--env` 传递说明要求的任何环境变量，在服务器名称之后和 `--` 之前：

203 203

204```bash theme={null}204```bash theme={null}

205claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server205claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

213 213

214为另一个 MCP 客户端（例如 Claude Desktop）编写的 `mcpServers` 块使用 Claude Code 读取的包装器密钥和条目形状。将 `claude mcp add-json` 传递给 `mcpServers` 内的对象，而不是包装器。两个条目需要先修复：214为另一个 MCP 客户端（例如 Claude Desktop）编写的 `mcpServers` 块使用 Claude Code 读取的包装器密钥和条目形状。将 `claude mcp add-json` 传递给 `mcpServers` 内的对象，而不是包装器。两个条目需要先修复：

215 215

216* **没有 `type` 的 `url`**：添加 `"type": "http"`、`"type": "sse"` 或 `"type": "ws"` 以匹配端点。Claude Code 将没有 `type` 的条目读取为 stdio 服务器，因此没有 `type` 的 `url` 条目会失败。216* **`url` 没有 `type`**：添加 `"type": "http"`、`"type": "sse"` 或 `"type": "ws"` 以匹配端点。Claude Code 将没有 `type` 的条目读取为 stdio 服务器，因此没有 `type` 的 `url` 条目会失败。

217* **具有除字母、数字、连字符和下划线以外的字符的密钥**：选择仅使用这些字符的服务器名称。否则密钥是服务器名称。217* **密钥包含除字母、数字、连字符和下划线以外的字符**：选择仅使用这些字符的服务器名称。否则密钥是服务器名称。

218 218

219例如，此块：219例如，此块：

220 220

237 237

238[从 JSON 配置添加 MCP 服务器](#add-mcp-servers-from-json-configuration) 涵盖 `add-json` 的 shell 转义和 `--scope` 标志。要与您的团队共享服务器，请改为添加 `--scope project`，或在项目根目录的 `.mcp.json` 下的 `mcpServers` 中添加条目并提交它。[项目范围](#project-scope) 涵盖 Claude Code 如何加载和批准该文件。238[从 JSON 配置添加 MCP 服务器](#add-mcp-servers-from-json-configuration) 涵盖 `add-json` 的 shell 转义和 `--scope` 标志。要与您的团队共享服务器，请改为添加 `--scope project`，或在项目根目录的 `.mcp.json` 下的 `mcpServers` 中添加条目并提交它。[项目范围](#project-scope) 涵盖 Claude Code 如何加载和批准该文件。

239 239

240每个 `claude mcp add` 和 `claude mcp add-json` 命令都会打印一行 `Added ...`。要检查 Claude Code 是否已连接，请运行 `claude mcp get <name>`；[服务器状态](#server-status) 涵盖它显示的状态和 `.mcp.json` 服务器的批准步骤。240每个 `claude mcp add` 和 `claude mcp add-json` 命令在成功时打印 `Added ...` 行。要检查 Claude Code 是否已连接，请运行 `claude mcp get <name>`；[服务器状态](#server-status) 涵盖它显示的状态和 `.mcp.json` 服务器的批准步骤。

241 241

242<h3 id="managing-your-servers">242<h3 id="managing-your-servers">

243 管理您的服务器243 管理您的服务器

271 271

272此列表中的状态报告配置决策而不是连接尝试，因此 Claude Code 在不连接到服务器的情况下打印它们：272此列表中的状态报告配置决策而不是连接尝试，因此 Claude Code 在不连接到服务器的情况下打印它们：

273 273

274* ``⏸ Pending approval (run `claude` to approve)``：来自 `.mcp.json` 的项目范围服务器，您尚未批准。Claude Code 在 `claude mcp list` 和 `claude mcp get <name>` 中都显示它。以交互方式运行 `claude` 来审查和批准它。274* ``⏸ Pending approval (run `claude` to approve)``：来自 `.mcp.json` 的项目范围服务器，您尚未批准。Claude Code 在 `claude mcp list` 和 `claude mcp get <name>` 中都显示它。运行 `claude` 交互式地审查和批准它。

275* `✘ Rejected (see disabledMcpjsonServers in settings)`：由 [`disabledMcpjsonServers`](/docs/zh-CN/settings-reference#disabledmcpjsonservers) 条目拒绝的 `.mcp.json` 服务器。Claude Code 仅在 `claude mcp get <name>` 中显示它。275* `✘ Rejected (see disabledMcpjsonServers in settings)`：由 [`disabledMcpjsonServers`](/docs/zh-CN/settings-reference#disabledmcpjsonservers) 条目拒绝的 `.mcp.json` 服务器。Claude Code 仅在 `claude mcp get <name>` 中显示它。

276* `⊘ Disabled for this project (re-enable via /mcp)`：项目的 [`disabledMcpServers`](#disable-a-server-without-removing-it) 列表命名的服务器。Claude Code 在 `claude mcp list` 和 `claude mcp get <name>` 中都显示它。从 `/mcp` 面板打开服务器。在 v2.1.238 之前，两个命令都连接到禁用的服务器以进行健康检查并报告连接结果。276* `⊘ Disabled for this project (re-enable via /mcp)`：项目的 [`disabledMcpServers`](#disable-a-server-without-removing-it) 列表命名的服务器。Claude Code 在 `claude mcp list` 和 `claude mcp get <name>` 中都显示它。从 `/mcp` 面板打开服务器。

277 277

278WebSocket 服务器不会出现在 `claude mcp list` 输出中。使用 `claude mcp get <name>` 或 `/mcp` 面板来检查它们。278WebSocket 服务器不出现在 `claude mcp list` 输出中。使用 `claude mcp get <name>` 或 `/mcp` 面板检查它们。

279 279

280<h4 id="project-server-approvals-and-workspace-trust">280<h4 id="project-server-approvals-and-workspace-trust">

281 项目服务器批准和工作区信任281 项目服务器批准和工作区信任

282</h4>282</h4>

283 283

284从 v2.1.196 开始，`claude mcp list` 和 `claude mcp get` 仅从未检入存储库的设置文件中读取 `.mcp.json` 批准，直到您通过在其中运行 `claude` 并接受工作区信任对话来信任工作区。克隆的存储库无法批准自己的服务器：提交到项目的 `.claude/settings.json` 的 [`enableAllProjectMcpServers`](/docs/zh-CN/settings-reference#enableallprojectmcpservers) 或 [`enabledMcpjsonServers`](/docs/zh-CN/settings-reference#enabledmcpjsonservers) 在不受信任的文件夹中被忽略，服务器保持在 `⏸ Pending approval` 而不是被连接和健康检查。284从 v2.1.196 开始，`claude mcp list` 和 `claude mcp get` 仅从未签入存储库的设置文件中读取 `.mcp.json` 批准，直到您通过在其中运行 `claude` 并接受工作区信任对话来信任工作区。克隆的存储库无法批准自己的服务器：提交到项目的 `.claude/settings.json` 的 [`enableAllProjectMcpServers`](/docs/zh-CN/settings-reference#enableallprojectmcpservers) 或 [`enabledMcpjsonServers`](/docs/zh-CN/settings-reference#enabledmcpjsonservers) 在不受信任的文件夹中被忽略，服务器保持在 `⏸ Pending approval` 而不是被连接和健康检查。

285 285

286这些来源的批准仍然适用于不受信任的文件夹：286这些来源的批准仍然适用于不受信任的文件夹：

287 287

289* 托管设置289* 托管设置

290* 使用 `--settings` 传递的设置290* 使用 `--settings` 传递的设置

291 291

292Claude Code 也应用来自未跟踪的 `.claude/settings.local.json` 的批准，但它运行 git 来检查文件是否被跟踪，并且仅在 [受信任的文件夹](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust) 中运行该检查。在您从未信任的文件夹中，Claude Code 等待信任对话后才应用文件的批准，除非该文件夹是您自己的配置主目录：您的主目录，或一个您已设置为 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars) 的 `.claude` 的目录。在 v2.1.207 之前，Claude Code 即使在您从未信任的文件夹中也应用来自未跟踪的 `.claude/settings.local.json` 的批准。292Claude Code 也应用来自未跟踪的 `.claude/settings.local.json` 的批准，但它运行 git 来检查文件是否被跟踪，并且仅在 [受信任的文件夹](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust) 中运行该检查。在您从未信任的文件夹中，Claude Code 等待信任对话后才应用文件的批准，除非该文件夹是您自己的配置主目录：您的主目录，或其 `.claude` 您已设置为 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars) 的目录。在 v2.1.207 之前，Claude Code 即使在您从未信任的文件夹中也应用来自未跟踪的 `.claude/settings.local.json` 的批准。

293 293

294任何设置文件中的 `disabledMcpjsonServers` 条目仍然拒绝服务器。294任何设置文件中的 `disabledMcpjsonServers` 条目仍然拒绝服务器。

295 295

297 服务器状态详情297 服务器状态详情

298</h4>298</h4>

299 299

300在 `/mcp` 中（包括服务器的菜单）和 [`/plugin`](/docs/zh-CN/plugins/install) 管理器中，您之前使用过的远程 HTTP 或 SSE 服务器可以显示 `cached` 状态，例如 `cached 2h ago · connects on first use · 5 tools`。Claude Code 从发现缓存（保存在上一个会话中）加载了服务器的工具列表，而不是在启动时连接，Claude Code 在 Claude 首次调用服务器的工具之一时连接服务器。工具从您的第一条消息开始可用，因此您无需执行任何操作。发现缓存及其 `cached` 状态需要 Claude Code v2.1.221 或更高版本。300在 `/mcp` 中（包括服务器的菜单）和 [`/plugin`](/docs/zh-CN/plugins/install) 管理器中，您之前使用过的远程 HTTP 或 SSE 服务器可以显示 `cached` 状态，例如 `cached 2h ago · connects on first use · 5 tools`。Claude Code 从发现缓存加载了服务器的工具列表，该缓存保存在上一个会话中，而不是在启动时连接，Claude Code 在 Claude 首次调用服务器的工具之一时连接服务器。工具从您的第一条消息开始可用，因此您无需执行任何操作。发现缓存及其 `cached` 状态需要 Claude Code v2.1.221 或更高版本。

301 301

302发现缓存默认关闭，除非逐步推出已为您的帐户启用它。设置 [`MCP_DISCOVERY_CACHE=1`](/docs/zh-CN/env-vars) 以打开它，或设置为 `0` 以在推出启用它时保持关闭。在 v2.1.238 之前，缓存默认打开。302发现缓存默认关闭，除非逐步推出已为您的帐户启用它。设置 [`MCP_DISCOVERY_CACHE=1`](/docs/zh-CN/env-vars) 打开它，或设置为 `0` 即使推出已启用它也保持关闭。在 v2.1.238 之前，缓存默认打开。

303 303

304当您从 `/mcp` 中的服务器菜单中选择 **Disable** 或 **Clear authentication** 时，Claude Code 也会丢弃该服务器的缓存条目。**Reconnect** 在已连接或失败的服务器上也会丢弃它；在 `cached` 服务器上，**Reconnect** 现在连接服务器并保留条目。丢弃条目后，Claude Code 从服务器而不是从缓存获取服务器的工具列表。304当您从 `/mcp` 中的服务器菜单选择 **Disable** 或 **Clear authentication** 时，Claude Code 也会丢弃该服务器的缓存条目。**Reconnect** 在连接或失败的服务器上也会丢弃它；在 `cached` 服务器上，**Reconnect** 现在连接服务器并保留条目。Claude Code 下次连接到服务器后丢弃条目时，它从服务器而不是从缓存获取工具列表。

305 305

306当服务器的状态为 `✘ Failed to connect` 时，`claude mcp list` 将失败详情附加到该状态行，`claude mcp get <name>` 在 `Issue:` 行上显示它：HTTP 状态或错误代码，加上服务器返回的任何错误文本。`/mcp` 中的服务器详情视图在其 `Issue:` 行中包含相同的服务器报告的文本。Claude Code 从此详情中编辑类似凭证的文本，并且永远不包括扩展的服务器 URL，它可能携带机密。Claude Code 不向 `✘ Connection error` 状态附加详情，因为它会打印的异常文本可以嵌入该 URL。在 v2.1.219 之前，两个命令仅显示裸失败状态，没有状态代码或服务器的错误文本。306当服务器的状态为 `✘ Failed to connect` 时，`claude mcp list` 将失败详情附加到该状态行，`claude mcp get <name>` 在 `Issue:` 行上显示它：HTTP 状态或错误代码，加上服务器返回的任何错误文本。`/mcp` 中的服务器详情视图在其 `Issue:` 行中包含相同的服务器报告文本。Claude Code 从此详情中编辑类似凭证的文本，并且永远不包括扩展的服务器 URL，它可能携带机密。Claude Code 不向 `✘ Connection error` 状态附加详情，因为它会打印的异常文本可以嵌入该 URL。在 v2.1.219 之前，两个命令仅显示裸失败状态，没有状态代码或服务器的错误文本。

307 307

308当您从 `/mcp` 完成身份验证且连接仍然因 HTTP 状态或传输错误代码失败时，Claude Code 在尝试后打印的消息中添加该代码和服务器 URL 的来源。来源是方案和主机，加上 URL 命名的端口（如果有），例如 `https://mcp.example.com`。308当您从 `/mcp` 完成身份验证且连接仍然因 HTTP 状态或传输错误代码失败时，Claude Code 在尝试后打印的消息中添加该代码和服务器 URL 的来源。来源是方案和主机，加上 URL 命名的端口（如果有），例如 `https://mcp.example.com`。

309 309

310* 路径和查询永远不会出现在该消息中。310* 路径和查询永远不会出现在该消息中。

311* 对于本地、项目或用户 [范围](#mcp-installation-scopes) 中的服务器或托管 MCP 配置中的服务器，来源显示在该配置中写入的主机，因此主机中的 `${VAR}` 引用在消息中不会展开。311* 对于本地、项目或用户 [范围](#mcp-installation-scopes) 中的服务器或托管 MCP 配置中的服务器，来源显示该配置中写入的主机，因此主机中的 `${VAR}` 引用在消息中不会展开。

312* 对于没有状态或错误代码的失败，Claude Code 显示没有来源的错误文本。312* 对于没有状态或错误代码的失败，Claude Code 显示错误文本而不显示来源。

313 313

314配置为空 `url` 的远程服务器在 `/mcp`、`claude mcp list` 和 [`/plugin`](/docs/zh-CN/plugins/install) 管理器中显示为 `not configured`，Claude Code 不尝试连接到它。插件可以包含这样的占位符条目，用于您稍后配置的连接器，因此 Claude Code 不会将其报告为错误或设置问题。`/mcp` 中的服务器详情视图读取 `No URL configured for this server`；设置条目的 `url` 以连接它。在 v2.1.208 之前，Claude Code 将空 `url` 报告为配置问题，并提示重新连接。314配置为空 `url` 的远程服务器在 `/mcp`、`claude mcp list` 和 [`/plugin`](/docs/zh-CN/plugins/install) 管理器中显示为 `not configured`，Claude Code 不尝试连接到它。插件可以包含这样的占位符条目，用于您稍后配置的连接器，因此 Claude Code 不将其报告为错误或设置问题。`/mcp` 中的服务器详情视图读取 `No URL configured for this server`；设置条目的 `url` 以连接它。在 v2.1.208 之前，Claude Code 将空 `url` 报告为配置问题，并提示重新连接。

315 315

316<h4 id="configuration-warnings">316<h4 id="configuration-warnings">

317 配置警告317 配置警告

319 319

320Claude Code 警告以下配置问题。每个条目说明 Claude Code 检查什么以及如何清除警告：320Claude Code 警告以下配置问题。每个条目说明 Claude Code 检查什么以及如何清除警告：

321 321

322* **隐藏的空白**：当 MCP 配置值携带隐藏的前导或尾随空白时，Claude Code 发出警告，这通常来自粘贴带有尾随换行符的令牌。Claude Code 检查 `command`、`url`、每个 `args` 条目以及 `env` 和 `headers` 下的值和密钥名称。Claude Code 在 `claude mcp list` 输出和 `/mcp` 中显示警告，命名受影响的字段而不回显其值，例如 `Leading or trailing whitespace in: headers.Authorization`。Claude Code 不修剪空白并完全按照写入的方式使用值，因此编辑配置以删除它。322* **隐藏的空格**：当 MCP 配置值携带隐藏的前导或尾随空格时，Claude Code 发出警告，这通常来自粘贴带有尾随换行符的令牌。Claude Code 检查 `command`、`url`、每个 `args` 条目以及 `env` 和 `headers` 下的值和密钥名称。Claude Code 在 `claude mcp list` 输出和 `/mcp` 中显示警告，命名受影响的字段而不回显其值，例如 `Leading or trailing whitespace in: headers.Authorization`。Claude Code 不修剪空格并完全按照写入的方式使用值，因此编辑配置以删除它。

323* **在多个范围中具有相同名称**：如果您在多个 [范围](#mcp-installation-scopes) 中定义相同的服务器名称，具有不同的端点，Claude Code 在 `claude mcp list` 输出和 `/mcp` 中警告冲突。Claude Code 按端点存储 OAuth 登录，因此当您对在一个项目中加载的定义进行身份验证时，您仍然需要在另一个项目中单独登录，其中不同的定义加载。保留您想要的端点并使用 `claude mcp remove <name> --scope <scope>` 删除其他端点。在警告中，Claude Code 引用每个范围的端点，如您的配置中所写，带有 [`${VAR}` 引用](#environment-variable-expansion-in-mcp-json) 未展开，因此它永远不会显示已解析的值，例如 API 密钥。323* **在多个范围中使用相同名称**：如果您在多个 [范围](#mcp-installation-scopes) 中定义相同的服务器名称，具有不同的端点，Claude Code 在 `claude mcp list` 输出和 `/mcp` 中警告冲突。Claude Code 按端点存储 OAuth 登录，因此当您在一个项目中验证加载的定义时，您仍然需要在不同定义加载的项目中单独登录。保留您想要的端点并使用 `claude mcp remove <name> --scope <scope>` 删除其他端点。在警告中，Claude Code 引用每个范围的端点，如您的配置中所写，带有 [`${VAR}` 引用](#environment-variable-expansion-in-mcp-json) 未展开，因此它永远不显示已解析的值，例如 API 密钥。

324* **保留名称**：Claude Code 保留其内置服务器的名称，包括 `workspace`、`claude-in-chrome`、`computer-use`、`Claude Preview` 和 `Claude Browser`。如果您的配置定义具有保留名称的服务器，Claude Code 在加载时跳过它并显示警告，要求您重命名它。`claude mcp add` 拒绝保留名称并出现错误。`Claude Preview` 和 `Claude Browser` 都命名 [Claude Code 桌面应用的预览窗格](/docs/zh-CN/desktop#preview-your-app) 使用的内置服务器。在 v2.1.205 之前，`Claude Browser` 未被保留，因此用户配置的服务器可以在该名称下注册。324* **保留名称**：Claude Code 保留其内置服务器的名称，包括 `workspace`、`claude-in-chrome`、`computer-use`、`Claude Preview` 和 `Claude Browser`。如果您的配置定义具有保留名称的服务器，Claude Code 在加载时跳过它并显示警告，要求您重命名它。`claude mcp add` 拒绝保留名称并出现错误。`Claude Preview` 和 `Claude Browser` 都命名 [Claude Code 桌面应用的预览窗格](/docs/zh-CN/desktop#preview-your-app) 使用的内置服务器。

325* **缺少环境变量**：如果服务器配置中的 [`${VAR}` 引用](#environment-variable-expansion-in-mcp-json) 命名未设置且没有 `:-default` 的变量，Claude Code 在 `claude mcp list` 输出和 `/mcp` 中警告，命名变量，并仍然使用 `${VAR}` 文本未展开加载服务器。设置变量或添加 `${VAR:-default}` 回退。在远程服务器的 `url` 和 `headers` 中，某些凭证变量 [读取为空](#credential-variables-that-read-as-empty) 而不是警告。325* **缺少环境变量**：如果服务器配置中的 [`${VAR}` 引用](#environment-variable-expansion-in-mcp-json) 命名未设置且没有 `:-default` 的变量，Claude Code 在 `claude mcp list` 输出和 `/mcp` 中警告，命名变量，并仍然使用 `${VAR}` 文本未展开加载服务器。设置变量或添加 `${VAR:-default}` 回退。在远程服务器的 `url` 和 `headers` 中，某些凭证变量 [读取为空](#credential-variables-that-read-as-empty) 而不显示警告。

326 326

327<h4 id="tool-availability">327<h4 id="tool-availability">

328 工具可用性328 工具可用性

329</h4>329</h4>

330 330

331`/mcp` 面板在每个已连接的服务器旁边显示工具计数，并标记声称工具功能但不公开工具的服务器。331`/mcp` 面板在每个连接的服务器旁边显示工具计数，并标记声称工具能力但不公开工具的服务器。

332 332

333如果您的请求需要来自仍在后台连接的服务器的工具，Claude 会在继续之前等待该服务器。等待的方式取决于您的配置：333如果您的请求需要来自仍在后台连接的服务器的工具，Claude 会在继续之前等待该服务器。等待的方式取决于您的配置：

334 334

335* **使用 [工具搜索](#scale-with-mcp-tool-search)（默认）**：等待发生在 `ToolSearch` 调用内。335* **使用 [工具搜索](#scale-with-mcp-tool-search)（默认）**：等待发生在 `ToolSearch` 调用内。

336* **不使用工具搜索**：Claude 改为使用 `WaitForMcpServers` 工具。不使用工具搜索的配置包括自定义 `ANTHROPIC_BASE_URL`、`ENABLE_TOOL_SEARCH=false` 和 Google Cloud 的 Agent Platform 上早于 Claude 4.5 代的模型。336* **不使用工具搜索**：Claude 改为使用 `WaitForMcpServers` 工具。不使用工具搜索的配置包括自定义 `ANTHROPIC_BASE_URL`、`ENABLE_TOOL_SEARCH=false` 和 Google Cloud 的 Agent Platform 上早于 Claude 4.5 代的模型。

337* **在 Microsoft Foundry [部署在 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)**：Claude 在工具搜索路径上启动而不是使用 `WaitForMcpServers`，因为 Claude Code 仅从 API 发现部署的服务器端拒绝。Claude Code 将该部署切换到 [前期加载](#scale-with-mcp-tool-search) 后，来自完成连接的服务器的工具在 Claude 的下一个请求中变为可用。337* **在 Microsoft Foundry [部署托管在 Azure 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)**：Claude 在工具搜索路径上启动而不是使用 `WaitForMcpServers`，因为 Claude Code 仅从 API 发现部署的服务器端拒绝。Claude Code 将该部署切换到 [前期加载](#scale-with-mcp-tool-search) 后，来自完成连接的服务器的工具在 Claude 的下一个请求中变为可用。

338 338

339启用工具搜索后，当服务器在 Claude 工作时完成连接时，Claude Code 在同一轮的下一个请求中将服务器的工具名称列出给 Claude。Claude 然后可以搜索和调用这些工具，而无需等待您的下一条消息。339启用工具搜索后，当服务器在 Claude 工作时完成连接时，Claude Code 在同一轮的下一个请求中将服务器的工具名称列出给 Claude。Claude 然后可以搜索和调用这些工具，而无需等待您的下一条消息。

340 340

342 禁用服务器而不删除它342 禁用服务器而不删除它

343</h3>343</h3>

344 344

345在 `/mcp` 面板中切换服务器关闭，以停止 Claude Code 连接到它，而不会丢失其配置。Claude Code 仍然在 `/mcp` 中列出服务器，标记为禁用。345在 `/mcp` 面板中切换服务器关闭，以停止 Claude Code 连接到它，而不丢失其配置。Claude Code 仍然在 `/mcp` 中列出服务器，标记为禁用。

346 346

347切换服务器时，Claude Code 在 `~/.claude.json` 中按项目记录您的选择，在两个涵盖不相交服务器集的列表之一中：347当您切换服务器时，Claude Code 在 `~/.claude.json` 中按项目记录您的选择，在两个涵盖不相交服务器集的列表之一中：

348 348

349* `disabledMcpServers`：用户配置的服务器、插件服务器、您的组织 [通过托管设置提供](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings) 的服务器、Claude Code [自己获取](#how-connectors-reach-claude-code) 的 claude.ai 连接器以及默认打开的内置服务器的选择退出列表。Claude Code 不连接到您在此处列出的服务器。当您使用 [禁用 claude.ai 连接器](#disable-claude-ai-connectors) 中描述的按项目 `/mcp` 切换禁用 claude.ai 连接器时，Claude Code 在此列表下使用其显示名称（例如 `claude.ai Slack`）写入它。349* `disabledMcpServers`：用户配置的服务器、插件服务器、您的组织 [通过托管设置提供](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings) 的服务器、Claude Code [自己获取](#how-connectors-reach-claude-code) 的 claude.ai 连接器以及默认打开的内置服务器的选择退出列表。Claude Code 不连接您在此处列出的服务器。当您使用 [禁用 claude.ai 连接器](#disable-claude-ai-connectors) 中描述的按项目 `/mcp` 切换禁用 claude.ai 连接器时，Claude Code 在此列表下使用其显示名称（例如 `claude.ai Slack`）写入它。

350* `enabledMcpServers`：默认关闭的内置服务器（例如 `computer-use`）的选择加入列表。Claude Code 仅当您在此处列出它时才连接到默认关闭的服务器。350* `enabledMcpServers`：默认关闭的内置服务器（例如 `computer-use`）的选择加入列表。Claude Code 仅当您在此处列出它时才连接默认关闭的服务器。

351 351

352Claude Code 为每个服务器查询恰好两个列表之一，因此两个列表都不会覆盖另一个。如果您将常规服务器添加到 `enabledMcpServers`，或将默认关闭的内置服务器添加到 `disabledMcpServers`，Claude Code 会忽略该条目。352Claude Code 为每个服务器查询恰好两个列表之一，因此两个列表都不会覆盖另一个。如果您将常规服务器添加到 `enabledMcpServers`，或将默认关闭的内置服务器添加到 `disabledMcpServers`，Claude Code 会忽略该条目。

353 353

359 359

360Claude Code 通过两个客户端运行时之一连接到 MCP 服务器。v1 运行时基于 MCP TypeScript SDK 1.x。v2 运行时是 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 上的相同代码，它添加了 MCP 协议修订版 2026-07-28。本页的其余部分适用于两个运行时，除非某个部分命名 v2 运行时。360Claude Code 通过两个客户端运行时之一连接到 MCP 服务器。v1 运行时基于 MCP TypeScript SDK 1.x。v2 运行时是 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 上的相同代码，它添加了 MCP 协议修订版 2026-07-28。本页的其余部分适用于两个运行时，除非某个部分命名 v2 运行时。

361 361

362Claude Code 每次启动时选择一个运行时，并在您退出前保持它。在 [获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) 的会话中，它在 Claude Code v2.1.232 或更高版本上使用 v2 运行时。362Claude Code 在每次启动时选择一个运行时，并在您退出前保持它。在 [获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) 的会话中，它在 Claude Code v2.1.232 或更高版本上使用 v2 运行时。

363 363

364在不获取功能标志的会话中，Claude Code 在 Claude Code v2.1.274 或更高版本上默认使用 v2 运行时：364在不获取功能标志的会话中，Claude Code 在 Claude Code v2.1.274 或更高版本上默认使用 v2 运行时：

365 365

371 371

372* 询问 HTTP 服务器是否支持较新的修订版，并与支持的服务器一起使用它。它也在获取功能标志的会话中询问 claude.ai 连接器服务器。要让它询问 stdio 服务器或每个会话中的连接器服务器，请设置 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 为 `auto`。它连接到每个其他服务器，如 v1 所做的那样。372* 询问 HTTP 服务器是否支持较新的修订版，并与支持的服务器一起使用它。它也在获取功能标志的会话中询问 claude.ai 连接器服务器。要让它询问 stdio 服务器或每个会话中的连接器服务器，请设置 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 为 `auto`。它连接到每个其他服务器，如 v1 所做的那样。

373* 从 [它保持打开的流](#notification-streams-on-the-v2-runtime) 上的较新修订版的服务器接收 `list_changed` 通知。373* 从 [它保持打开的流](#notification-streams-on-the-v2-runtime) 上的较新修订版的服务器接收 `list_changed` 通知。

374* 不注册在较新修订版上连接的 [通道](#push-messages-with-channels) 服务器，因为该修订版无法携带通道消息。374* 不注册在较新修订版上连接的 [channel](#push-messages-with-channels) 服务器，因为该修订版无法携带频道消息。

375* 失败 [MCP OAuth 登录](#authenticate-with-remote-mcp-servers)，其授权响应命名意外的发行者。375* 失败 [MCP OAuth 登录](#authenticate-with-remote-mcp-servers)，其授权响应命名意外的发行者。

376* 仅将 [MCP OAuth](#authenticate-with-remote-mcp-servers) 凭证发送到通过 HTTPS 或在 `localhost`、`127.0.0.1` 或 `::1` 处提供的令牌端点。对于令牌端点为纯 `http://` 的服务器（例如本地网络上的设备），登录失败。请参阅 [拒绝向非 https 令牌端点发送凭证](/docs/zh-CN/errors#refusing-to-send-credentials-to-non-https-token-endpoint)。376* 仅将 [MCP OAuth](#authenticate-with-remote-mcp-servers) 凭证发送到通过 HTTPS 或在 `localhost`、`127.0.0.1` 或 `::1` 上提供的令牌端点。对于令牌端点为纯 `http://` 的服务器（例如本地网络上的设备），登录失败。请参阅 [拒绝向非 https 令牌端点发送凭证](/docs/zh-CN/errors#refusing-to-send-credentials-to-non-https-token-endpoint)。

377 377

378Anthropic 可以使用 Claude Code 获取的功能标志将特定服务器保持在较早的协议上，或关闭该流。378Anthropic 可以使用功能标志 Claude Code 获取来将特定服务器保持在较早的协议上，或将其从该流中删除。

379 379

380要自己选择运行时，请设置 [`MCP_SDK_GENERATION`](/docs/zh-CN/env-vars) 为 `v1` 或 `v2`。要决定 Claude Code 是否询问，请设置 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 为 `auto` 或 `legacy`。380要自己选择运行时，请设置 [`MCP_SDK_GENERATION`](/docs/zh-CN/env-vars) 为 `v1` 或 `v2`。要决定 Claude Code 是否询问，请设置 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 为 `auto` 或 `legacy`。

381 381

417 失败的首次连接417 失败的首次连接

418</h4>418</h4>

419 419

420当 HTTP 或 SSE 服务器的首次连接因瞬时错误（例如 5xx 响应、连接被拒绝或超时）失败时，Claude Code 最多重试三次。如果连接仍然失败，Claude Code 将服务器标记为失败。Claude Code 在启动时和在会话中期添加服务器时以这种方式重试。这包括 Claude Code 从其配置添加到 [云会话](/docs/zh-CN/claude-code-on-the-web) 的服务器和您使用 Agent SDK 的 [`setMcpServers()`](/docs/zh-CN/agent-sdk/typescript) 添加的服务器。420当 HTTP 或 SSE 服务器的首次连接因瞬时错误（例如 5xx 响应、连接被拒绝或超时）失败时，Claude Code 最多重试三次。如果连接仍然失败，Claude Code 将服务器标记为失败。

421 421

422Claude Code 在这些情况下不重试：422Claude Code 在这些情况下不重试：

423 423

428 失败的发现请求428 失败的发现请求

429</h4>429</h4>

430 430

431服务器连接后，Claude Code 向其发送功能发现请求，例如 `tools/list`、`prompts/list` 和 `resources/list`。Claude Code 在瞬时网络或服务器错误后最多重试这些请求三次，短退避。它不重试身份验证错误、4xx 响应或请求超时。431服务器连接后，Claude Code 向其发送能力发现请求，例如 `tools/list`、`prompts/list` 和 `resources/list`。Claude Code 在瞬时网络或服务器错误后最多重试这些请求三次，短退避。它不重试身份验证错误、4xx 响应或请求超时。

432 432

433<h4 id="how-claude-learns-that-a-server-failed">433<h4 id="how-claude-learns-that-a-server-failed">

434 Claude 如何了解服务器失败434 Claude 如何了解服务器失败

435</h4>435</h4>

436 436

437Claude Code 是否告诉 Claude 配置的服务器无法连接取决于 [工具搜索](#scale-with-mcp-tool-search)，默认打开：437Claude Code 是否告诉 Claude 配置的服务器未能连接取决于 [工具搜索](#scale-with-mcp-tool-search)，默认打开：

438 438

439* 使用工具搜索，Claude Code 告诉 Claude 哪个服务器失败及其连接错误，因此 Claude 在其响应中报告连接失败。Claude Code 在 `ToolSearch` 结果中包含相同的信息，这些结果找不到匹配的工具。439* 使用工具搜索，Claude Code 告诉 Claude 哪个服务器失败及其连接错误，因此 Claude 在其响应中报告连接失败。Claude Code 在 `ToolSearch` 结果中包含相同的信息，这些结果找不到匹配的工具。

440* 在任何 [不使用工具搜索的配置](#configure-tool-search) 中，Claude Code 不向 Claude 报告失败的服务器连接。440* 在任何 [不使用工具搜索的配置](#configure-tool-search) 中，Claude Code 不向 Claude 报告失败的服务器连接。

441 441

442<h3 id="push-messages-with-channels">442<h3 id="push-messages-with-channels">

443 使用通道推送消息443 使用频道推送消息

444</h3>444</h3>

445 445

446MCP 服务器也可以直接将消息推送到您的会话中，以便 Claude 可以对外部事件（如 CI 结果、监控警报或聊天消息）做出反应。要启用此功能，您的服务器声明 `claude/channel` 功能，您在启动时使用 `--channels` 标志选择加入。请参阅 [通道](/docs/zh-CN/channels) 以使用官方支持的通道，或 [通道参考](/docs/zh-CN/channels-reference) 以构建您自己的。446MCP 服务器也可以直接将消息推送到您的会话中，以便 Claude 可以对外部事件（如 CI 结果、监控警报或聊天消息）做出反应。要启用此功能，您的服务器声明 `claude/channel` 能力，您在启动时使用 `--channels` 标志选择加入。请参阅 [频道](/docs/zh-CN/channels) 以使用官方支持的频道，或 [频道参考](/docs/zh-CN/channels-reference) 以构建您自己的。

447 447

448在 [v2 运行时](#mcp-client-runtimes) 上，如果您设置 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 为 `auto` 并且通道服务器协商 MCP 协议修订版 2026-07-28，它无法传递通道消息，因此 Claude Code 不将其注册为通道。保留变量未设置，或将其设置为 `legacy`，将 stdio 服务器保持在较早的握手上。448在 [v2 运行时](#mcp-client-runtimes) 上，如果您设置 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 为 `auto` 并且频道服务器协商 MCP 协议修订版 2026-07-28，它无法传递频道消息，因此 Claude Code 不将其注册为频道。保留变量未设置，或将其设置为 `legacy`，将 stdio 服务器保持在较早的握手上。

449 449

450<Tip>450<Tip>

451 提示：451 提示：

454 * `local`（默认）：仅在当前项目中对您可用454 * `local`（默认）：仅在当前项目中对您可用

455 * `project`：通过 `.mcp.json` 文件与项目中的每个人共享455 * `project`：通过 `.mcp.json` 文件与项目中的每个人共享

456 * `user`：在所有项目中对您可用456 * `user`：在所有项目中对您可用

457 * 使用 `-e` 或 `--env` 标志设置环境变量（例如，`-e KEY=value`）457 * 使用 `-e` 或 `--env` 标志设置环境变量（例如 `-e KEY=value`）

458 * `--transport` 和 `--header` 标志也接受 `-t` 和 `-H` 短形式458 * `--transport` 和 `--header` 标志也接受 `-t` 和 `-H` 短形式

459 * 使用 `MCP_TIMEOUT` 环境变量配置 MCP 服务器启动超时（例如，`MCP_TIMEOUT=10000 claude` 设置 10 秒超时）459 * 使用 `MCP_TIMEOUT` 环境变量配置 MCP 服务器启动超时（例如 `MCP_TIMEOUT=10000 claude` 设置 10 秒超时）

460 * 通过在该服务器的 `.mcp.json` 条目中添加 `timeout` 字段（以毫秒为单位）来设置每个服务器的工具执行超时，例如 `"timeout": 600000` 表示十分钟。这仅对该服务器覆盖 `MCP_TOOL_TIMEOUT` 环境变量460 * 通过在该服务器的 `.mcp.json` 条目中添加 `timeout` 字段（以毫秒为单位）来设置按服务器工具执行超时，例如 `"timeout": 600000` 表示十分钟。这仅对该服务器覆盖 `MCP_TOOL_TIMEOUT` 环境变量

461 * 当 MCP 工具输出超过 10,000 个令牌时，Claude Code 显示警告，默认限制输出为 25,000 个令牌。要提高限制，请设置 `MAX_MCP_OUTPUT_TOKENS` 环境变量（例如，`MAX_MCP_OUTPUT_TOKENS=50000`）；警告阈值是固定的。请参阅 [MCP 输出限制和警告](#mcp-output-limits-and-warnings)461 * 当 MCP 工具输出超过 10,000 个令牌时，Claude Code 显示警告，默认限制输出为 25,000 个令牌。要提高限制，请设置 `MAX_MCP_OUTPUT_TOKENS` 环境变量（例如 `MAX_MCP_OUTPUT_TOKENS=50000`）；警告阈值是固定的。请参阅 [MCP 输出限制和警告](#mcp-output-limits-and-warnings)

462 * 使用 `/mcp` 对需要 OAuth 2.0 身份验证的远程服务器进行身份验证462 * 使用 `/mcp` 与需要 OAuth 2.0 身份验证的远程服务器进行身份验证

463</Tip>463</Tip>

464 464

465每个服务器的 `timeout` 是每个工具调用的硬墙钟限制，来自服务器的进度通知不会延长它。低于 1000 的值被忽略并回退到 `MCP_TOOL_TIMEOUT`，或在该变量未设置时回退到其约 28 小时的默认值。对于 HTTP、SSE 或 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) 服务器，还有第二个按请求计时器，涵盖从服务器的第一个响应字节的每个请求。Claude Code 将该计时器设置为三个值中最大的：60 秒、适用于服务器的工具超时和 `MCP_TIMEOUT`。未设置的 `MCP_TOOL_TIMEOUT` 的 28 小时默认值不进入该比较，低于 60 秒的值不会缩短计时器。Stdio 和 WebSocket 服务器没有按请求计时器。465按服务器的 `timeout` 是每个工具调用的硬墙钟限制，来自服务器的进度通知不会延长它。低于 1000 的值被忽略并落入 `MCP_TOOL_TIMEOUT`，或在该变量未设置时落入其约 28 小时的默认值。对于 HTTP、SSE 或 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) 服务器，还有第二个按请求计时器，涵盖每个请求到服务器的第一个响应字节。Claude Code 将该计时器设置为三个值中最大的：60 秒、适用于服务器的工具超时和 `MCP_TIMEOUT`。未设置的 `MCP_TOOL_TIMEOUT` 的 28 小时默认值不进入该比较，低于 60 秒的值不会缩短计时器。Stdio 和 WebSocket 服务器没有按请求计时器。

466 466

467至少 1000 的每个服务器 `timeout` 也充当下面描述的空闲超时的下限：Claude Code 永远不会因空闲而中止该服务器的工具调用早于每个服务器的 `timeout`。需要 Claude Code v2.1.203 或更高版本。467至少 1000 的按服务器 `timeout` 也充当下面描述的空闲超时的下限：Claude Code 永远不会因空闲而中止该服务器的工具调用早于按服务器 `timeout`。需要 Claude Code v2.1.203 或更高版本。

468 468

469对 MCP 服务器的工具调用，在空闲窗口内不发送响应和不发送进度通知，会因错误而中止，而不是等待墙钟限制。空闲超时适用于除 IDE 服务器和 SDK 进程内服务器外的每个服务器类型。空闲窗口对于 HTTP、SSE、WebSocket 和 [claude.ai 连接器](#use-mcp-servers-from-claude-ai) 服务器默认为五分钟，对于 stdio 服务器默认为 30 分钟。在 v2.1.203 之前，stdio 服务器免除空闲超时。469对 MCP 服务器的工具调用，在空闲窗口内不发送响应和不发送进度通知，会因错误而中止，而不是等待墙钟限制。空闲超时适用于除 IDE 服务器和 SDK 进程内服务器外的每个服务器类型。空闲窗口对 HTTP、SSE、WebSocket 和 [claude.ai 连接器](#use-mcp-servers-from-claude-ai) 服务器默认为五分钟，对 stdio 服务器默认为 30 分钟。在 v2.1.203 之前，stdio 服务器免除空闲超时。

470 470

471在 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/zh-CN/env-vars) 环境变量中设置毫秒以更改空闲窗口，或将其设置为 `0` 以禁用检查。471设置 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/zh-CN/env-vars) 环境变量（以毫秒为单位）来更改空闲窗口，或将其设置为 `0` 以禁用检查。

472 472

473这些超时限制调用可以运行多长时间，不总是它阻止会话多长时间：在两分钟后仍在运行的主对话调用首先移动到后台任务。请参阅 [长工具调用的自动后台处理](#automatic-backgrounding-of-long-tool-calls)。473这些超时限制调用可以运行多长时间，不总是它阻止会话多长时间：在两分钟后仍在运行的主对话调用首先移到后台任务。请参阅 [长工具调用的自动后台处理](#automatic-backgrounding-of-long-tool-calls)。

474 474

475<h3 id="automatic-backgrounding-of-long-tool-calls">475<h3 id="automatic-backgrounding-of-long-tool-calls">

476 长工具调用的自动后台处理476 长工具调用的自动后台处理

477</h3>477</h3>

478 478

479主对话中的 MCP 工具调用在两分钟后仍在运行时移动到后台任务，而不是阻止会话。Claude 立即接收任务 ID 并继续工作，结果在调用解决时作为任务通知到达。自动后台处理需要 Claude Code v2.1.212 或更高版本。479主对话中的 MCP 工具调用在两分钟后仍在运行时移到后台任务，而不是阻止会话。Claude 立即接收任务 ID 并继续工作，结果在调用解决时作为任务通知到达。自动后台处理需要 Claude Code v2.1.212 或更高版本。

480 480

481任务出现在 [`/tasks`](/docs/zh-CN/commands#all-commands) 中，您也可以在其中停止它，并且在退出会话时不会保留。每个调用的限制仍然适用于在后台运行的调用：由每个服务器 `timeout` 或 [`MCP_TOOL_TIMEOUT`](/docs/zh-CN/env-vars) 设置的墙钟限制，以及由 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/zh-CN/env-vars) 设置的空闲超时。481任务出现在 [`/tasks`](/docs/zh-CN/commands#all-commands) 中，您也可以在其中停止它，它不会在退出会话时存活。任务的条目显示服务器报告的最新进度。

482 482

483设置 [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](/docs/zh-CN/env-vars) 环境变量（以毫秒为单位）以更改阈值，或将其设置为 `0` 以关闭自动后台处理。将 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 设置为 `1` 也会关闭它，以及所有其他后台任务功能。483每调用限制仍然适用于调用在后台运行时：由按服务器 `timeout` 或 [`MCP_TOOL_TIMEOUT`](/docs/zh-CN/env-vars) 设置的墙钟限制，以及由 [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/zh-CN/env-vars) 设置的空闲超时。

484 484

485某些调用永远不会移动到后台：485设置 [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](/docs/zh-CN/env-vars) 环境变量（以毫秒为单位）来更改阈值，或将其设置为 `0` 以关闭自动后台处理。将 `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` 设置为 `1` 也会关闭它，以及所有其他后台任务功能。

486

487某些调用永远不会移到后台：

486 488

487* 来自 [子代理](/docs/zh-CN/sub-agents) 的调用；Claude Code 仅后台处理主对话调用489* 来自 [子代理](/docs/zh-CN/sub-agents) 的调用；Claude Code 仅后台处理主对话调用

488* 对 IDE 服务器的调用490* 对 IDE 服务器的调用

498 500

499**插件 MCP 服务器如何工作**：501**插件 MCP 服务器如何工作**：

500 502

501* 插件在插件根目录的 `.mcp.json` 中或在 `plugin.json` 中内联定义 MCP 服务器503* 插件在插件根目录的 `.mcp.json` 中或内联在 `plugin.json` 中定义 MCP 服务器

502* 启用插件时，Claude Code 自动启动其 MCP 服务器504* 当您启用插件时，Claude Code 自动启动其 MCP 服务器

503* Claude Code 将插件 MCP 工具与手动配置的 MCP 工具一起提供505* Claude Code 将插件 MCP 工具与手动配置的 MCP 工具一起提供

504* 您通过安装或卸载插件来添加和删除插件服务器，而不是使用 `/mcp` 命令。您仍然可以在 `/mcp` 中 [切换已安装的插件服务器关闭](#disable-a-server-without-removing-it)，这会停止 Claude Code 连接到它，而不删除插件506* 您通过安装或卸载插件来添加和删除插件服务器，而不是使用 `/mcp` 命令。您仍然可以在 `/mcp` 中 [切换已安装的插件服务器关闭](#disable-a-server-without-removing-it)，这会停止 Claude Code 连接到它而不删除插件

505 507

506**示例插件 MCP 配置**：508**示例插件 MCP 配置**：

507 509

521}523}

522```524```

523 525

524或在 `plugin.json` 中内联：526或内联在 `plugin.json` 中：

525 527

526```json theme={null}528```json theme={null}

527{529{

537 539

538**插件 MCP 功能**：540**插件 MCP 功能**：

539 541

540* **自动生命周期**：服务器在这些点连接和断开连接：542* **自动生命周期**：服务器在这些点连接和断开：

541 * 在会话启动时，Claude Code 自动连接启用的插件的服务器。在 `/mcp` 中，您之前使用过的远程（HTTP 或 SSE）插件服务器可以显示 [`cached` 状态](#server-status-detail) 而不是；Claude Code 在 Claude 首次调用其工具之一时连接它543 * 在会话启动时，Claude Code 自动连接启用的插件的服务器。在 `/mcp` 中，您之前使用过的远程（HTTP 或 SSE）插件服务器可以显示 [`cached` 状态](#server-status-detail) 而不是；Claude Code 在 Claude 首次调用其工具之一时连接它

542 * 如果您在会话期间启用或禁用插件，Claude Code 在更改应用时连接或断开其 MCP 服务器。[在不重启的情况下应用插件更改](/docs/zh-CN/plugins/cli-reference#reload-plugins) 描述何时应用。在没有交互式终端的会话中，`/reload-plugins` 不连接或断开插件 MCP 服务器；这些更改在您的下一个会话中生效544 * 如果您在会话期间启用或禁用插件，Claude Code 在更改应用时连接或断开其 MCP 服务器。[在不重新启动的情况下应用插件更改](/docs/zh-CN/plugins/cli-reference#reload-plugins) 描述何时应用。在没有交互式终端的会话中，`/reload-plugins` 不连接或断开插件 MCP 服务器；这些更改在您的下一个会话中生效

543 * 重新加载时，Claude Code 保留配置未更改的插件服务器的实时连接，并在您从 Agent SDK [替换会话的 MCP 服务器列表](/docs/zh-CN/agent-sdk/typescript#mcpsetserversresult) 而不命名它们时执行相同操作545 * 当您重新加载时，Claude Code 保留配置未更改的插件服务器的实时连接，并在您从 Agent SDK [替换会话的 MCP 服务器列表](/docs/zh-CN/agent-sdk/typescript#mcpsetserversresult) 而不命名它们时执行相同操作

544 * 当您在 v2.1.246 或更高版本上使用 `/cd` [移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory) 时，Claude Code 连接新目录的设置启用的插件的服务器，并断开不再启用的插件的服务器，因此您不需要在移动后运行 `/reload-plugins`546 * 当您在 v2.1.246 或更高版本上使用 `/cd` [移动会话](/docs/zh-CN/permissions#move-the-session-to-another-directory) 时，Claude Code 连接新目录的设置启用的插件的服务器，并断开不再启用的插件的服务器，因此您不需要在移动后运行 `/reload-plugins`

545 * 在 [云会话](/docs/zh-CN/claude-code-on-the-web) 中，对尚未连接的插件服务器的 MCP 调用（例如在空闲会话唤醒后），按需启动服务器并等待它连接547 * 在 [云会话](/docs/zh-CN/claude-code-on-the-web) 中，对尚未连接的插件服务器的 MCP 调用（例如空闲会话唤醒后）按需启动服务器并等待它连接

546* **路径占位符**：`${CLAUDE_PLUGIN_ROOT}` 解析为插件的安装目录，`${CLAUDE_PLUGIN_DATA}` 解析为其 [持久状态](/docs/zh-CN/plugins/components#path-variables-and-persistent-data) 目录，`${CLAUDE_PROJECT_DIR}` 解析为稳定的项目根目录。替换适用于：548* **路径占位符**：`${CLAUDE_PLUGIN_ROOT}` 解析为插件的安装目录，`${CLAUDE_PLUGIN_DATA}` 解析为其 [持久状态](/docs/zh-CN/plugins/components#path-variables-and-persistent-data) 目录，`${CLAUDE_PROJECT_DIR}` 解析为稳定的项目根目录。替换适用于：

547 * `stdio` 服务器：`command`、`args`、`env`549 * `stdio` 服务器：`command`、`args`、`env`

548 * `http`、`sse` 和 `ws` 服务器：`url`、`headers` 和 `headersHelper`550 * `http`、`sse` 和 `ws` 服务器：`url`、`headers` 和 `headersHelper`

551 553

552插件服务器在 `/mcp` 中出现，指示器显示它们来自插件。554插件服务器在 `/mcp` 中出现，指示器显示它们来自插件。

553 555

556对于插件的 stdio 服务器，`claude mcp get` 打印 `Command: stdio`、空 `Args:` 行和每个环境变量作为 `NAME=[REDACTED]`。值被隐藏，因为它们可能携带凭证。

557

554**插件 MCP 工具名称**：558**插件 MCP 工具名称**：

555 559

556来自插件捆绑的 MCP 服务器的工具在其可调用名称中包含插件名称和服务器密钥。完整形式是 `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`，其中 `A-Z`、`a-z`、`0-9`、`_` 和 `-` 之外的任何字符都被替换为 `_`。对于名为 `my-plugin` 的插件中捆绑的 `database-tools` 服务器，`query` 工具可调用为：560来自插件捆绑的 MCP 服务器的工具在其可调用名称中包含插件名称和服务器密钥。完整形式是 `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`，其中 `A-Z`、`a-z`、`0-9`、`_` 和 `-` 之外的任何字符都被替换为 `_`。对于名为 `my-plugin` 的插件中捆绑的 `database-tools` 服务器，`query` 工具可调用为：

559mcp__plugin_my-plugin_database-tools__query563mcp__plugin_my-plugin_database-tools__query

560```564```

561 565

562在 [权限规则](/docs/zh-CN/permissions)、技能的 `allowed-tools` 列表、[子代理的 `tools` 字段](/docs/zh-CN/sub-agents#available-tools) 或 [hook 匹配器](/docs/zh-CN/hooks#match-mcp-tools) 中引用工具时使用此完整名称。针对裸服务器密钥编写的 hook 匹配器（例如 `mcp__database-tools__.*`）永远不会对插件捆绑的服务器触发。566在 [权限规则](/docs/zh-CN/permissions)、技能的 `allowed-tools` 列表、[子代理的 `tools` 字段](/docs/zh-CN/sub-agents#available-tools) 或 [hook 匹配器](/docs/zh-CN/hooks#match-mcp-tools) 中引用工具时使用此完整名称。针对裸服务器密钥编写的 hook 匹配器（例如 `mcp__database-tools__.*`）永远不会为插件捆绑的服务器触发。

563 567

564服务器本身在作用域名称 `plugin:<plugin-name>:<server-name>` 下注册，例如 `plugin:my-plugin:database-tools`。在需要配置的服务器名称的地方使用该名称，例如 [`mcp_tool` hook 的 `server` 字段](/docs/zh-CN/hooks#mcp-tool-hook-fields)。568服务器本身在作用域名称 `plugin:<plugin-name>:<server-name>` 下注册，例如 `plugin:my-plugin:database-tools`。在需要配置的服务器名称的地方使用该名称，例如 [`mcp_tool` hook 的 `server` 字段](/docs/zh-CN/hooks#mcp-tool-hook-fields)。

565 569

1237 </Step>1241 </Step>

1238</Steps>1242</Steps>

1239 1243

1240Anthropic 还自己提供一些连接器，无需您或管理员添加它们。在 [Claude Docs](/docs/zh-CN/artifacts#write-a-document-with-claude-docs) 可用的账户上，`/mcp` 列出 `claude.ai Claude Docs`，无需设置，当您要求创建供他人使用的文档时，Claude 会使用它。要关闭它，请将 `serverName` 条目 `"claude.ai Claude Docs"` 添加到 `deniedMcpServers`，或使用 `/mcp` 切换，两者都在 [禁用 claude.ai 连接器](#disable-claude-ai-connectors) 中描述。1244Anthropic 本身也提供一些 connectors，无需您或管理员添加。在 [Claude Docs](/docs/zh-CN/artifacts#write-a-document-with-claude-docs) 可用的账户上，`/mcp` 列出 `claude.ai Claude Docs`，无需设置，当您要求创建供他人使用的文档时，Claude 会使用它。要关闭它，请将 `"claude.ai Claude Docs"` 的 `serverName` 条目添加到 `deniedMcpServers`，或使用 `/mcp` 切换，两者都在 [禁用 claude.ai connectors](#disable-claude-ai-connectors) 中描述。

1241 1245

1242当您的组织在 claude.ai 中管理其身份验证时，Claude Code 在 `/mcp` 和 [`/plugin`](/docs/zh-CN/plugins/install) 管理器中将连接器标记为 `managed`。托管状态不会改变 Claude Code 连接到连接器的方式或应用您的组织的 [工具控制](#organization-controls-on-connector-tools)。1246当您的组织在 claude.ai 中管理其身份验证时，Claude Code 在 `/mcp` 和 [`/plugin`](/docs/zh-CN/plugins/install) 管理器中将 connector 标记为 `managed`。Managed 状态不会改变 Claude Code 连接到 connector 的方式或应用您组织的 [工具控制](#organization-controls-on-connector-tools)。

1243 1247

1244您从未登录过的连接器会在 claude.ai 部分末尾的 `Show unused connectors` 行后面折叠，因此组织预配的列表不会填满面板。选择该行以展开它们。您之前登录过的连接器即使当前需要重新身份验证，也会保持可见。1248您从未登录过的 Connectors 会折叠在 claude.ai 部分末尾的 `Show unused connectors` 行后面，因此组织预配的列表不会填满面板。选择该行以展开它们。您之前登录过的 connector 即使当前需要重新身份验证，也会保持可见。

1245 1249

1246仅当您的活跃 [身份验证方法](/docs/zh-CN/authentication#authentication-precedence) 是 claude.ai 订阅登录时，才会从 claude.ai 获取连接器。即使您之前运行过 `/login`，在以下情况下也不会加载它们：1250Connectors 来自 claude.ai 仅在您的活跃 [身份验证方法](/docs/zh-CN/authentication#authentication-precedence) 是 claude.ai 订阅登录时才会获取。即使您之前运行过 `/login`，在以下情况下也不会加载：

1247 1251

1248* `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 处于活跃状态1252* `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN` 或 `apiKeyHelper` 处于活跃状态

1249* Amazon Bedrock 或 Google Cloud 的 Agent Platform 等第三方提供商处于活跃状态1253* 第三方提供商（如 Amazon Bedrock 或 Google Cloud 的 Agent Platform）处于活跃状态

1250* `ANTHROPIC_PROFILE`、联合变量或活跃的 [Anthropic 配置文件](/docs/zh-CN/authentication#anthropic-profiles-and-federation-credentials) 提供凭证1254* `ANTHROPIC_PROFILE`、联合变量或活跃的 [Anthropic 配置文件](/docs/zh-CN/authentication#anthropic-profiles-and-federation-credentials) 提供凭证

1251* `CLAUDE_CODE_OAUTH_TOKEN` 持有来自 [`claude setup-token`](/docs/zh-CN/authentication#generate-a-long-lived-token) 的令牌，该令牌只能进行模型请求1255* `CLAUDE_CODE_OAUTH_TOKEN` 持有来自 [`claude setup-token`](/docs/zh-CN/authentication#generate-a-long-lived-token) 的令牌，该令牌只能进行模型请求

1252 1256

1253如果 `/mcp` 没有列出您添加的连接器，请运行 `/status` 以确认哪个身份验证方法处于活跃状态。取消设置该环境变量、删除 `apiKeyHelper` 设置或 [关闭配置文件](/docs/zh-CN/authentication#anthropic-profiles-and-federation-credentials)，然后运行 `/login` 以选择您的 claude.ai 账户。1257如果 `/mcp` 没有列出您添加的 connector，请运行 `/status` 以确认哪个身份验证方法处于活跃状态。取消设置该环境变量，删除 `apiKeyHelper` 设置，或 [关闭配置文件](/docs/zh-CN/authentication#anthropic-profiles-and-federation-credentials)，然后运行 `/login` 以选择您的 claude.ai 账户。

1254 1258

1255如果临时网络问题导致连接器列表在会话启动时无法加载，Claude Code 会在后台重试最多三次，连接器会在重试成功后出现。如果它们仍未出现，请重启 Claude Code 以再次获取列表。1259如果临时网络问题导致您的会话启动时 connector 列表无法加载，Claude Code 会在后台重试最多三次，一旦重试成功，connectors 就会出现。如果它们仍未出现，请重启 Claude Code 以再次获取列表。

1256 1260

1257如果 `/mcp` 显示连接器为 `session token rejected`，或其详细视图显示 [`claude.ai rejected the session token`](/docs/zh-CN/errors#claude-ai-rejected-the-session-token)，则 claude.ai 拒绝了来自您的 Claude Code 登录的令牌。再次授权连接器不会清除此状态，因为被拒绝的不是连接器在 claude.ai 中的自身授权。要清除它：1261如果 `/mcp` 显示 connector 为 `session token rejected`，或其详细视图显示 [`claude.ai rejected the session token`](/docs/zh-CN/errors#claude-ai-rejected-the-session-token)，则 claude.ai 拒绝了您的 Claude Code 登录中的令牌。再次授权 connector 不会清除此状态，因为被拒绝的不是 connector 在 claude.ai 中的自身授权。要清除它：

1258 1262

12591. 运行 `/login` 以重新登录。12631. 运行 `/login` 以重新登录。

12602. 从 `/mcp` 重新连接连接器。12642. 从 `/mcp` 重新连接 connector。

1261 1265

1262在 v2.1.222 之前，Claude Code 将连接器标记为需要身份验证，授权它们无法解决此问题。1266在 v2.1.222 之前，Claude Code 将 connectors 标记为需要身份验证，授权它们无法解决此问题。

1263 1267

1264您在 Claude Code 中添加的服务器优先于指向相同 URL 的 claude.ai 连接器。发生这种情况时，`/mcp` 会将连接器列为隐藏，并显示如何删除重复项（如果您更希望使用连接器）。1268您在 Claude Code 中添加的服务器优先于指向相同 URL 的 claude.ai connector。发生这种情况时，`/mcp` 将 connector 列为隐藏，并显示如何删除重复项（如果您更希望使用 connector）。

1265 1269

1266某些 Anthropic 托管的连接器（如 Microsoft 365、Gmail 和 Google Calendar）不支持来自 Claude Code 的本地 OAuth，因为上游身份提供商仅接受 claude.ai 注册的重定向 URL。当您使用 `claude mcp add` 或在 `.mcp.json` 中添加的服务器指向这些主机之一，并且您从 `/mcp` 或使用 `claude mcp login` 登录时，Claude Code 会显示 [`is Anthropic-hosted and doesn't support local OAuth`](/docs/zh-CN/errors#anthropic-hosted-and-doesnt-support-local-oauth)，指导您改为在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 连接服务。1270某些 Anthropic 托管的 connectors（如 Microsoft 365、Gmail 和 Google Calendar）不支持来自 Claude Code 的本地 OAuth，因为上游身份提供商仅接受 claude.ai 注册的重定向 URL。当您使用 `claude mcp add` 或在 `.mcp.json` 中添加的服务器指向这些主机之一，并且您从 `/mcp` 或使用 `claude mcp login` 登录时，Claude Code 会显示 [`is Anthropic-hosted and doesn't support local OAuth`](/docs/zh-CN/errors#anthropic-hosted-and-doesnt-support-local-oauth)，指导您改为在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 连接该服务。

1267 1271

1268使用 `claude mcp remove <name>` 删除您的条目并在 claude.ai 上连接服务后，连接器会自动出现在 Claude Code 中。1272在您使用 `claude mcp remove <name>` 删除您的条目并在 claude.ai 上连接该服务后，connector 会自动出现在 Claude Code 中。

1269 1273

1270<h3 id="how-connectors-reach-claude-code">1274<h3 id="how-connectors-reach-claude-code">

1271 连接器如何到达 Claude Code1275 Connectors 如何到达 Claude Code

1272</h3>1276</h3>

1273 1277

1274哪些设置控制 claude.ai 连接器取决于您的会话在哪里运行，因为只有某些会话本身从 claude.ai 获取连接器。下表中的每一行命名了连接器在一种会话中的到达方式以及在那里控制它们的内容。桌面应用的 [WSL 会话](/docs/zh-CN/desktop-wsl#what-works-in-a-wsl-session) 没有行，因为连接器在其中尚不可用。1278哪些设置管理 claude.ai connector 取决于您的会话在哪里运行，因为只有某些会话从 claude.ai 本身获取 connectors。下表中的每一行命名 connectors 在一种会话中的到达方式以及在那里控制它们的内容。桌面应用的 [WSL 会话](/docs/zh-CN/desktop-wsl#what-works-in-a-wsl-session) 没有行，因为 connectors 在其中尚不可用。

1275 1279

1277| :- | :- | :- |1281| :- | :- | :- |

1278| Terminal、[VS Code](/docs/zh-CN/vs-code)、[JetBrains](/docs/zh-CN/jetbrains) 和 [Agent SDK](/docs/zh-CN/agent-sdk/claude-code-features) 会话 | Claude Code 从 claude.ai 获取它们 | 本部分中的设置和 [托管 MCP 配置](/docs/zh-CN/managed-mcp) |1282| Terminal、[VS Code](/docs/zh-CN/vs-code)、[JetBrains](/docs/zh-CN/jetbrains) 和 [Agent SDK](/docs/zh-CN/agent-sdk/claude-code-features) 会话 | Claude Code 从 claude.ai 获取它们 | 本部分中的设置和 [managed MCP 配置](/docs/zh-CN/managed-mcp) |

1279| [Cloud 会话](/docs/zh-CN/claude-code-on-the-web) | 远程主机传入它们 | 您的 claude.ai 组织设置，加上到达会话的 [allowlist 和 denylist](/docs/zh-CN/managed-mcp#policy-based-control-with-allowlists-and-denylists) 设置以及运行它的主机上的任何 `managed-mcp.json` |1283| [Cloud 会话](/docs/zh-CN/claude-code-on-the-web) | 云主机传入它们 | 您的 claude.ai 组织设置，加上到达会话的 [allowlist 和 denylist](/docs/zh-CN/managed-mcp#policy-based-control-with-allowlists-and-denylists) 设置以及运行它的主机上的任何 `managed-mcp.json` |

1281 1285

1282[`disableClaudeAiConnectors`](#disable-claude-ai-connectors)、`ENABLE_CLAUDEAI_MCP_SERVERS` 和 [`allowAllClaudeAiMcps`](/docs/zh-CN/settings-reference#allowallclaudeaimcps) 仅作用于第一行，即 Claude Code 本身获取的连接器。其他两行在这些方面与它不同：1286[`disableClaudeAiConnectors`](#disable-claude-ai-connectors)、`ENABLE_CLAUDEAI_MCP_SERVERS` 和 [`allowAllClaudeAiMcps`](/docs/zh-CN/settings-reference#allowallclaudeaimcps) 仅作用于第一行，即 Claude Code 自身获取的 connectors。其他两行在这些方面与它不同：

1283 1287

1284* **Cloud 会话**：到达会话的 `allowedMcpServers` 和 `deniedMcpServers` 条目（例如通过 [服务器管理的设置](/docs/zh-CN/server-managed-settings)）也会过滤传入的连接器。会话的代理会重写每个连接器的 URL，因此为连接器自身 URL 编写的 `serverUrl` 模式不会匹配它。要在自托管环境中的 URL allowlist 旁边允许传入的连接器，请添加 [连接器流量离开您的网络](/docs/zh-CN/self-hosted-environments-deploy#connector-traffic-leaves-your-network) 下列出的 `serverUrl` 条目。当运行会话的主机上存在 `managed-mcp.json` 时（例如 [自托管运行器主机](/docs/zh-CN/self-hosted-environments-configuration#mcp-servers)），Claude Code 会删除传入的连接器，无论您是否设置 `allowAllClaudeAiMcps`。1288* **Cloud 会话**：到达会话的 `allowedMcpServers` 和 `deniedMcpServers` 条目（例如通过 [server-managed 设置](/docs/zh-CN/server-managed-settings)）也会过滤传入的 connectors。会话的代理重写每个 connector 的 URL，因此为 connector 自身 URL 编写的 `serverUrl` 模式不会匹配它。要在自托管环境中的 URL allowlist 旁边允许传入的 connectors，请添加 [Connector 流量离开您的网络](/docs/zh-CN/self-hosted-environments-deploy#connector-traffic-leaves-your-network) 下列出的 `serverUrl` 条目。当运行会话的主机上存在 `managed-mcp.json` 时（例如 [self-hosted runner 主机](/docs/zh-CN/self-hosted-environments-configuration#mcp-servers)），Claude Code 会删除传入的 connectors，无论您是否设置 `allowAllClaudeAiMcps`。

1285* **桌面应用本地和 SSH 会话**：桌面应用将连接器注册为进程内 `type: "sdk"` 服务器，没有 MCP 设置或 `managed-mcp.json` 到达它们。用户通过在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 断开连接器来将其排除在自己的会话之外。组织可以阻止连接器的 [工具](#organization-controls-on-connector-tools) 或完全 [关闭桌面应用中的 Claude Code](/docs/zh-CN/desktop#admin-console-controls)。1289* **桌面应用本地和 SSH 会话**：桌面应用将 connectors 注册为进程内 `type: "sdk"` 服务器，没有 MCP 设置或 `managed-mcp.json` 到达它们。用户通过在 [claude.ai/customize/connectors](https://claude.ai/customize/connectors) 断开连接来将 connector 排除在自己的会话之外。组织阻止 connector 的 [工具](#organization-controls-on-connector-tools) 或完全关闭 [桌面应用中的 Claude Code](/docs/zh-CN/desktop#admin-console-controls)。

1286 1290

1287<h3 id="organization-controls-on-connector-tools">1291<h3 id="organization-controls-on-connector-tools">

1288 连接器工具的组织控制1292 组织对 connector 工具的控制

1289</h3>1293</h3>

1290 1294

1291您的组织可以在 [claude.ai 连接器](https://claude.com/docs/connectors) 上设置每个工具的控制。Claude Code 在启动时读取这些设置并在本地强制执行它们，除了在桌面应用的 [本地和 SSH 会话](#how-connectors-reach-claude-code) 中。在那里，桌面应用在传入连接器之前扣留 `blocked` 工具，`ask` 设置不会到达 Claude Code，因此它将会话的普通 [权限规则](/docs/zh-CN/permissions) 应用于这些工具，而不是在每次调用时提示。在 Claude Code 本身获取连接器的会话中，运行 `/mcp` 以查看哪个设置适用于连接器上的每个工具。1295您的组织可以在 [claude.ai connectors](https://claude.com/docs/connectors) 上设置每个工具的控制。Claude Code 在启动时读取这些设置并在本地强制执行它们，除了桌面应用的 [本地和 SSH 会话](#how-connectors-reach-claude-code)。在那里，桌面应用在传入 connector 之前扣留 `blocked` 工具，`ask` 设置不会到达 Claude Code，因此它将会话的普通 [权限规则](/docs/zh-CN/permissions) 应用于这些工具，而不是在每次调用时提示。在 Claude Code 自身获取 connectors 的会话中，运行 `/mcp` 以查看哪个设置适用于 connector 上的每个工具。

1292 1296

1293* **工具设置为 `ask`**：Claude Code 在每次调用时提示，原因是 `Your organization requires approval for this tool`。即使在 `acceptEdits`、`auto` 和 `bypassPermissions` [权限模式](/docs/zh-CN/permissions#permission-modes) 中，提示也会出现，并且从不提供记住您的选择的选项。匹配工具的 [Allow 规则](/docs/zh-CN/permissions) 也不会跳过提示。在从不提示的 `dontAsk` 模式中，Claude Code 会改为拒绝调用。1297* **工具设置为 `ask`**：Claude Code 在每次调用时提示，原因是 `Your organization requires approval for this tool`。即使在 `acceptEdits`、`auto` 和 `bypassPermissions` [权限模式](/docs/zh-CN/permissions#permission-modes) 中，提示也会出现，并且从不提供记住您选择的选项。匹配该工具的 [Allow 规则](/docs/zh-CN/permissions) 也不会跳过提示。在 `dontAsk` 模式中（从不提示），Claude Code 会改为拒绝调用。

1294* **工具设置为 `blocked`**：Claude Code 在 Claude 看到它之前过滤掉工具，因此它永远不会出现在工具列表中。在 Claude Code 本身获取连接器的会话中，`/mcp` 工具列表仍然显示该工具，标记为 `disabled by your organization`。桌面应用和 claude.ai 聊天应用相同的 `blocked` 设置，因此 Claude 也无法在那里使用该工具，您无法从桌面应用的会话中扣留工具，同时在聊天中保持其可用。桌面应用会跳过其所有工具都被阻止的连接器。1298* **工具设置为 `blocked`**：Claude Code 在 Claude 看到它之前过滤掉该工具，因此它从不出现在 Claude 的工具列表中。在 Claude Code 自身获取 connectors 的会话中，`/mcp` 工具列表仍然显示该工具，标记为 `disabled by your organization`。

1299

1300桌面应用和 claude.ai 聊天应用相同的 `blocked` 设置，因此 Claude 也无法在那里使用被阻止的工具，您无法从桌面应用的会话中扣留工具，同时在聊天中保持其可用。桌面应用跳过其所有工具都被阻止的 connector。

1295 1301

1296<h3 id="disable-claude-ai-connectors">1302<h3 id="disable-claude-ai-connectors">

1297 禁用 claude.ai 连接器1303 禁用 claude.ai connectors

1298</h3>1304</h3>

1299 1305

1300Claude Code 仅将 [`disableClaudeAiConnectors`](/docs/zh-CN/settings-reference#disableclaudeaiconnectors) 应用于它 [本身获取](#how-connectors-reach-claude-code) 的连接器，而不是云主机或桌面应用传入的连接器。要关闭它获取的连接器，请在任何设置范围中将设置设置为 `true`：1306Claude Code 仅将 [`disableClaudeAiConnectors`](/docs/zh-CN/settings-reference#disableclaudeaiconnectors) 应用于它 [自身获取](#how-connectors-reach-claude-code) 的 connectors，而不是云主机或桌面应用传入的 connectors。要关闭它获取的 connectors，请在任何设置范围中将设置设置为 `true`：

1301 1307

1302```json theme={null}1308```json theme={null}

1303{1309{

1305}1311}

1306```1312```

1307 1313

1308此设置使用任何源为真的语义：任何设置源中的 `true` 优先。已检入的项目 `.claude/settings.json` 可以选择退出 Claude Code 本身获取的连接器，但项目级别的 `false` 无法重新启用用户或策略级别的 `true` 已禁用的连接器。通过 `--mcp-config` 显式传递的服务器不受影响。1314此设置使用任何源为真的语义：任何设置源中的 `true` 优先。已检入的项目 `.claude/settings.json` 可以选择退出 Claude Code 自身获取的 connectors，但项目级别的 `false` 无法重新启用用户或策略级别的 `true` 已禁用的 connectors。通过 `--mcp-config` 显式传递的服务器不受影响。

1309 1315

1310您也可以将 `ENABLE_CLAUDEAI_MCP_SERVERS` 环境变量设置为 `false`，这对当前 shell 会话具有相同的效果：1316您也可以将 `ENABLE_CLAUDEAI_MCP_SERVERS` 环境变量设置为 `false`，这对当前 shell 会话具有相同的效果：

1311 1317

1313ENABLE_CLAUDEAI_MCP_SERVERS=false claude1319ENABLE_CLAUDEAI_MCP_SERVERS=false claude

1314```1320```

1315 1321

1316要阻止单个 claude.ai 连接器而不是全部，请按名称或 URL 模式将它们添加到 [`deniedMcpServers`](/docs/zh-CN/managed-mcp)。例如，`serverName` 条目 `"claude.ai Slack"` 会阻止 Slack 连接器。您也可以运行 `/mcp` 以仅为当前项目切换 Claude Code 获取的任何连接器的开关。1322要阻止单个 claude.ai connectors 而不是全部，请按名称或 URL 模式将它们添加到 [`deniedMcpServers`](/docs/zh-CN/managed-mcp) 中。例如，`"claude.ai Slack"` 的 `serverName` 条目会阻止 Slack connector。您也可以运行 `/mcp` 以仅为当前项目切换 Claude Code 获取的任何 connector。

1317 1323

1318<h2 id="use-claude-code-as-an-mcp-server">1324<h2 id="use-claude-code-as-an-mcp-server">

1319 将 Claude Code 用作 MCP 服务器1325 将 Claude Code 用作 MCP 服务器

1454* 顶级属性名称必须为 1 到 64 个字符长，并且只能使用 ASCII 字母和数字、`_`、`.` 和 `-`1460* 顶级属性名称必须为 1 到 64 个字符长，并且只能使用 ASCII 字母和数字、`_`、`.` 和 `-`

1455* 架构必须对 JSON Schema draft 2020-12 元架构有效。Claude Code 对未声明 `$schema` 的架构和声明 draft 2020-12 的架构应用此检查。声明任何其他方言的架构会跳过此检查，尽管上面的属性名称检查仍然适用1461* 架构必须对 JSON Schema draft 2020-12 元架构有效。Claude Code 对未声明 `$schema` 的架构和声明 draft 2020-12 的架构应用此检查。声明任何其他方言的架构会跳过此检查，尽管上面的属性名称检查仍然适用

1456 1462

1457Claude Code 在 [根级组合器重写](#tool-input-schemas-with-a-root-level-combinator) 之后运行检查，对它实际会发送的架构进行检查。

~~1458~~

1459当 Claude Code 排除一个工具时，它会在服务器的日志中记录原因，并告诉 Claude 它排除了哪些工具以及原因，这样你可以询问 Claude 为什么工具缺失。如果你修复了服务器上的架构，下次 Claude Code 加载服务器的工具时该工具就会回来。1463当 Claude Code 排除一个工具时，它会在服务器的日志中记录原因，并告诉 Claude 它排除了哪些工具以及原因，这样你可以询问 Claude 为什么工具缺失。如果你修复了服务器上的架构，下次 Claude Code 加载服务器的工具时该工具就会回来。

1460 1464

1461Claude Code 通过从 Anthropic 获取的功能标志打开排除。在 [禁用标志获取的部署](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) 上，或在标志从未到达的机器上（例如隔离的机器），Claude Code 仍然运行检查并在服务器的日志中记录哪个工具会被拒绝，但仍然将工具的架构发送到 API。API 拒绝包含该架构的请求，并 [以 400 错误按其位置命名工具](/docs/zh-CN/errors#tool-input-schema-is-invalid)。在 v2.1.216 之前，没有部署运行这些检查。1465Claude Code 通过从 Anthropic 获取的功能标志打开排除。在 [禁用标志获取的部署](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) 上，或在标志从未到达的机器上（例如隔离的机器），Claude Code 仍然运行检查并在服务器的日志中记录哪个工具会被拒绝，但仍然将工具的架构发送到 API。API 拒绝包含该架构的请求，并 [以 400 错误按其位置命名工具](/docs/zh-CN/errors#tool-input-schema-is-invalid)。在 v2.1.216 之前，没有部署运行这些检查。

mcp-quickstart.md +3 −1

Details

360 360

361 接下来发生的事情告诉您问题在哪里：361 接下来发生的事情告诉您问题在哪里：

362 362

363 * 命令启动并等待输入：服务器本身工作。运行 `claude mcp get <name>` 并确认那里显示的命令与您刚刚运行的命令匹配。如果显示的命令与您键入的不同，您可能在服务器命令之前省略了 `--` 分隔符。删除服务器并使用 `--` 重新添加它。如果您手工编写了 `.mcp.json`，请检查其语法和位置。363 * 命令启动并等待输入：服务器本身工作。

364

365 运行 `claude mcp get <name>` 并确认那里显示的命令与您刚刚运行的命令匹配。如果显示的命令与您键入的不同，您可能在服务器命令之前省略了 `--` 分隔符。删除服务器并使用 `--` 重新添加它。如果您手工编写了 `.mcp.json`，请检查其语法和位置。在 v2.1.285 之前，`claude mcp get` 对于保存时没有 `type` 字段的 stdio 条目（例如手工编写的 `.mcp.json` 条目）不打印 `Command` 行。在这些版本上，运行 `claude mcp list` 代替，它无论如何都会打印命令行。

364 * 命令出错：消息命名缺少的内容，例如 Node.js 或浏览器。366 * 命令出错：消息命名缺少的内容，例如 Node.js 或浏览器。

365 </Accordion>367 </Accordion>

366 368

model-config.md +10 −5

Details

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

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

41| **`haiku`** | 为简单任务使用快速高效的 Haiku 模型 |41| **`haiku`** | 为简单任务使用快速高效的 Haiku 模型 |

42| **`sonnet[1m]`** | 为长会话使用具有 [100 万令牌上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) 的 Sonnet。当 `sonnet` 已解析到具有原生 1M 窗口的 Sonnet 5.5 或 Sonnet 5 时无效；在 [LLM 网关](/docs/zh-CN/llm-gateway) 后面，为该模型选择 1M 窗口 |42| **`sonnet[1m]`** | 为长会话使用具有 [100 万令牌上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) 的 Sonnet。当 `sonnet` 已解析到具有原生 1M 窗口的 Sonnet 5.5 或 Sonnet 5 时无效 |

43| **`opus[1m]`** | 为长会话使用具有 [100 万令牌上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) 的 Opus |43| **`opus[1m]`** | 为长会话使用具有 [100 万令牌上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) 的 Opus |

44| **`opusplan`** | 特殊模式，在 Plan Mode 期间使用 `opus`，然后在执行期间切换到 `sonnet` |44| **`opusplan`** | 特殊模式，在 Plan Mode 期间使用 `opus`，然后在执行期间切换到 `sonnet` |

45 45

521 回退模型链521 回退模型链

522</h3>522</h3>

523 523

524当主模型过载、不可用或返回另一个不可重试的服务器错误时，Claude Code 可以切换到回退模型，而不是使请求失败。身份验证、计费、速率限制、请求大小和传输错误，以及[您组织的策略检查拒绝](/docs/zh-CN/errors#automatic-retries)，永远不会触发切换；这些遵循其正常的重试和错误处理。524当主模型过载、不可用或返回另一个不可重试的服务器错误时，Claude Code 可以切换到回退模型，而不是使请求失败。身份验证、计费、速率限制、请求大小和传输错误，以及[您组织的策略检查拒绝](/docs/zh-CN/errors#automatic-retries)，永远不会触发切换；这些遵循其正常的重试和错误处理。当 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock#when-a-model-is-disabled-mid-session) 或 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai#when-a-model-is-disabled-mid-session) 拒绝您的账户无法调用的模型时，它会切换，Claude Code 将其视为模型不可用而不是身份验证错误。

525 525

526配置一个或多个回退模型，Claude Code 会按顺序尝试它们，在切换时显示通知。切换仅持续当前轮次，因此您的下一条消息会首先再次尝试主模型。Claude Code 在删除重复项后将链限制为三个模型，并忽略额外条目。526配置一个或多个回退模型，Claude Code 会按顺序尝试它们，在切换时显示通知。切换仅持续当前轮次，因此您的下一条消息会首先再次尝试主模型。Claude Code 在删除重复项后将链限制为三个模型，并忽略额外条目。

527 527

775 775

776Claude Code 仅在直接连接到 Anthropic API 时检查这些计划要求。如果您将 `ANTHROPIC_BASE_URL` 指向[LLM 网关](/docs/zh-CN/llm-gateway#subscriptions-and-gateways)，您保存的 claude.ai 登录保持活跃凭证，Claude Code 不检查账户的使用额度。`/model` 中的 `[1m]` 选项保持可用，网关决定请求是否成功。在 v2.1.229 之前，当 Claude Code 无法确认账户上的使用额度时，它在该配置中拒绝 `/model sonnet[1m]`。776Claude Code 仅在直接连接到 Anthropic API 时检查这些计划要求。如果您将 `ANTHROPIC_BASE_URL` 指向[LLM 网关](/docs/zh-CN/llm-gateway#subscriptions-and-gateways)，您保存的 claude.ai 登录保持活跃凭证，Claude Code 不检查账户的使用额度。`/model` 中的 `[1m]` 选项保持可用，网关决定请求是否成功。在 v2.1.229 之前，当 Claude Code 无法确认账户上的使用额度时，它在该配置中拒绝 `/model sonnet[1m]`。

777 777

778<span id="context-window-behind-a-gateway" />

779

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

781

778要关闭 1M 上下文，设置 `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`。Claude Code 从模型选择器中删除 1M 模型变体。在具有本地 1M 窗口的模型上，例如 Sonnet 5 和 Fable 模型，它也将模型视为具有 200K 上下文窗口：782要关闭 1M 上下文，设置 `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`。Claude Code 从模型选择器中删除 1M 模型变体。在具有本地 1M 窗口的模型上，例如 Sonnet 5 和 Fable 模型，它也将模型视为具有 200K 上下文窗口：

779 783

780* 启用自动压缩时，会话在 200K 边界处通过[自动压缩](#set-the-auto-compact-window)进行压缩。将自动压缩窗口设置在 200K 以上不会解除保持，因为 Claude Code 将该窗口限制为模型的上下文窗口。784* 启用自动压缩时，会话在 200K 边界处通过[自动压缩](#set-the-auto-compact-window)进行压缩。将自动压缩窗口设置在 200K 以上不会解除保持，因为 Claude Code 将该窗口限制为模型的上下文窗口。

803 807

804在 Anthropic API 上，Sonnet 5.5 和 Sonnet 5 始终运行 1M 上下文窗口。没有 200K 变体，没有 `[1m]` 后缀可选择，任何计划上都不需要使用额度。会话在窗口填满前自动压缩，默认约 967K 令牌；设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/zh-CN/env-vars) 以选择不同的阈值。808在 Anthropic API 上，Sonnet 5.5 和 Sonnet 5 始终运行 1M 上下文窗口。没有 200K 变体，没有 `[1m]` 后缀可选择，任何计划上都不需要使用额度。会话在窗口填满前自动压缩，默认约 967K 令牌；设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/zh-CN/env-vars) 以选择不同的阈值。

805 809

806两个配置将窗口预算为 200K：810Claude Code 在[LLM 网关](/docs/zh-CN/llm-gateway)或另一个自定义 `ANTHROPIC_BASE_URL` 后面给 Sonnet 5.5 和 Sonnet 5 相同的 1M 窗口。如果您的网关强制更低的限制，请参阅[网关后面的上下文窗口](#context-window-behind-a-gateway)。

811

812此设置将窗口预算为 200K：

807 813

808* **LLM 网关**：当 `ANTHROPIC_BASE_URL` 指向[网关](/docs/zh-CN/llm-gateway)时，Claude Code 无法验证 1M 支持。要使用完整窗口，在模型选择器中选择 Sonnet 5.5 (1M context) 或 Sonnet 5 (1M context)，它映射到 `sonnet[1m]`，或运行 `/model claude-sonnet-5[1m]` 用于 Sonnet 5。

809* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**：将具有本地 1M 窗口的每个模型上的会话保持在 200K 窗口；请参阅[扩展上下文](#extended-context)了解保持如何被强制执行。对于需要限制上下文的部署很有用。814* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**：将具有本地 1M 窗口的每个模型上的会话保持在 200K 窗口；请参阅[扩展上下文](#extended-context)了解保持如何被强制执行。对于需要限制上下文的部署很有用。

810 815

811<h2 id="context-window-and-auto-compaction">816<h2 id="context-window-and-auto-compaction">

841* [云会话](/docs/zh-CN/claude-code-on-the-web)在对话接近模型限制时进行压缩846* [云会话](/docs/zh-CN/claude-code-on-the-web)在对话接近模型限制时进行压缩

842* Sonnet 4.6 和 Opus 4.6（不带[扩展上下文](#extended-context)）在 200K 边界处进行压缩，Opus 4.8 和更高版本在使用 200K 上下文窗口运行时也是如此，例如在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上847* Sonnet 4.6 和 Opus 4.6（不带[扩展上下文](#extended-context)）在 200K 边界处进行压缩，Opus 4.8 和更高版本在使用 200K 上下文窗口运行时也是如此，例如在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上

843* 当您设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-CN/env-vars) 时，具有原生 1M 窗口的模型（例如 Sonnet 5 和 Fable 模型）在 200K 边界处进行压缩848* 当您设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-CN/env-vars) 时，具有原生 1M 窗口的模型（例如 Sonnet 5 和 Fable 模型）在 200K 边界处进行压缩

844* 使用原生 1M 窗口运行的模型（例如 Sonnet 5、Fable 模型以及 Anthropic API 上的 Opus 4.7 及更高版本）在窗口填满之前进行压缩，默认情况下约为 967K 令牌。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，[为第三方部署固定模型](#pin-models-for-third-party-deployments)说明了哪些模型使用该窗口；对于将 Sonnet 5.5 和 Sonnet 5 预算为 200K 的配置，请参阅 [Sonnet 5.5 和 Sonnet 5 上下文窗口](#sonnet-5-5-and-sonnet-5-context-window)849* 使用原生 1M 窗口运行的模型在窗口填满之前进行压缩，默认情况下约为 967K 令牌。在 Anthropic API 上，这些包括 Sonnet 5、Fable 模型以及 Opus 4.7 及更高版本。在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，请参阅[为第三方部署固定模型](#pin-models-for-third-party-deployments)以了解哪些模型使用该窗口。在自定义 `ANTHROPIC_BASE_URL` 后面，请参阅[网关后面的上下文窗口](#context-window-behind-a-gateway)

845* 在 Claude Code 不识别的模型 ID（例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名）上的会话在 Claude Code 为该 ID 假设的上下文窗口处进行压缩；请参阅[为网关或自定义模型 ID 更正窗口](#correct-the-window-for-a-gateway-or-custom-model-id)850* 在 Claude Code 不识别的模型 ID（例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名）上的会话在 Claude Code 为该 ID 假设的上下文窗口处进行压缩；请参阅[为网关或自定义模型 ID 更正窗口](#correct-the-window-for-a-gateway-or-custom-model-id)

846 851

847<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">852<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">

monitoring-usage.md +1 −0

Details

1430* `error.type`：Claude Code 停止会话的原因。仅在 `refused` 事件上存在：1430* `error.type`：Claude Code 停止会话的原因。仅在 `refused` 事件上存在：

1431 * `"helper_failed"`：[策略助手运行失败](/docs/zh-CN/settings-reference#helper-failures)1431 * `"helper_failed"`：[策略助手运行失败](/docs/zh-CN/settings-reference#helper-failures)

1432 * `"policy_invalid"`：管理设置包含停止 Claude Code 启动的错误，或管理源无法加载，因此 Claude Code 无法检查组织登录强制1432 * `"policy_invalid"`：管理设置包含停止 Claude Code 启动的错误，或管理源无法加载，因此 Claude Code 无法检查组织登录强制

1433 * `"provider_not_allowed"`：会话将使用 API 提供商，或将提供商的流量发送到管理的 [`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders) 列表不允许的主机。需要 Claude Code v2.1.285 或更高版本

1433 * `"consent_rejected"`：用户拒绝了服务器管理设置的[安全批准对话](/docs/zh-CN/server-managed-settings#security-approval-dialogs)1434 * `"consent_rejected"`：用户拒绝了服务器管理设置的[安全批准对话](/docs/zh-CN/server-managed-settings#security-approval-dialogs)

1434 * `"force_refresh_failed"`：[`forceRemoteSettingsRefresh`](/docs/zh-CN/settings-reference#forceremotesettingsrefresh) 需要的设置获取失败1435 * `"force_refresh_failed"`：[`forceRemoteSettingsRefresh`](/docs/zh-CN/settings-reference#forceremotesettingsrefresh) 需要的设置获取失败

1435 * `"gateway_rejected"`：[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)用 HTTP 403 回答了管理设置加载1436 * `"gateway_rejected"`：[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)用 HTTP 403 回答了管理设置加载

network-config.md +1 −1

Details

249| `*.frame.claudeusercontent.com` | [Artifact](/docs/zh-CN/artifacts) 内容读取。当 Claude 打开 Artifact 时，CLI 从此主机获取 Artifact 的文件，仅当 Artifact 工具对您的账户[可用](/docs/zh-CN/artifacts#availability)时。要关闭该工具并删除此要求，请设置 [`"enableArtifact": false`](/docs/zh-CN/settings-reference#enableartifact) 或 [`CLAUDE_CODE_DISABLE_ARTIFACT=1`](/docs/zh-CN/env-vars)；Claude Code 也遵守已弃用的 [`disableArtifact`](/docs/zh-CN/settings-reference#disableartifact) 设置。有关这些设置如何相互作用，请参阅[禁用 Artifact](/docs/zh-CN/artifacts#disable-artifacts) |249| `*.frame.claudeusercontent.com` | [Artifact](/docs/zh-CN/artifacts) 内容读取。当 Claude 打开 Artifact 时，CLI 从此主机获取 Artifact 的文件，仅当 Artifact 工具对您的账户[可用](/docs/zh-CN/artifacts#availability)时。要关闭该工具并删除此要求，请设置 [`"enableArtifact": false`](/docs/zh-CN/settings-reference#enableartifact) 或 [`CLAUDE_CODE_DISABLE_ARTIFACT=1`](/docs/zh-CN/env-vars) |

250| `github.com` | 克隆 GitHub 托管的[插件市场](/docs/zh-CN/plugins/overview)和插件，包括官方 Anthropic 市场，通过 HTTPS 或 SSH。要仅通过 HTTPS 克隆 GitHub `owner/repo` 源，请设置 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-CN/env-vars) |250| `github.com` | 克隆 GitHub 托管的[插件市场](/docs/zh-CN/plugins/overview)和插件，包括官方 Anthropic 市场，通过 HTTPS 或 SSH。要仅通过 HTTPS 克隆 GitHub `owner/repo` 源，请设置 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-CN/env-vars) |

251| `raw.githubusercontent.com` | [`/release-notes`](/docs/zh-CN/commands) 的更新日志源。在交互式会话中，当 Claude Code 的缓存更新日志尚未涵盖运行版本时（例如更新后的首次启动），Claude Code 也会在启动时在后台获取它；非交互式和云会话永远不会获取它 |251| `raw.githubusercontent.com` | [`/release-notes`](/docs/zh-CN/commands) 的更新日志源。在交互式会话中，当 Claude Code 的缓存更新日志尚未涵盖运行版本时（例如更新后的首次启动），Claude Code 也会在启动时在后台获取它；非交互式和云会话永远不会获取它 |

252| `*-review.googlesource.com` | `googlesource.com` 检出上的 Gerrit 更改查询。当 Claude Desktop Code 标签会话在[受信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)的检出上启动或恢复，且其 `origin` 是 `googlesource.com` 主机时，Claude Code 会匿名向该主机的 `-review` 服务器查询与 HEAD 的 `Change-Id` 匹配的开放更改，每次启动或恢复一次。其他会话类型跳过查询，不会联系其他 Gerrit 主机。可选：使用 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-CN/env-vars) 禁用 |252| `*-review.googlesource.com` | `googlesource.com` 检出上的 Gerrit 更改查询。当 Claude Desktop Code 标签会话在[受信任](/docs/zh-CN/permissions#project-allow-rules-and-workspace-trust)的检出上启动或恢复，且其 `origin` 是 `googlesource.com` 主机时，Claude Code 会匿名向该主机的 `-review` 服务器查询与 HEAD 的 `Change-Id` 匹配的开放更改，每次启动或恢复一次。其他会话类型跳过查询，不会联系其他 Gerrit 主机。可选：使用 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-CN/env-vars) 禁用 |

permission-modes.md +47 −47

Details

86| 您如何运行 Claude Code | 内置起始权限模式 |86| 您如何运行 Claude Code | 内置起始权限模式 |

87| :- | :- |87| :- | :- |

88| 任何设置文件将 `disableAutoMode` 设置为 `"disable"` | `default` |88| 任何设置文件将 `disableAutoMode` 设置为 `"disable"` | `default` |

~~89| `claude -p` 或 [Agent SDK](/docs/zh-CN/agent-sdk/permissions) | `default` |~~89| `claude -p` 或 [Agent SDK](/docs/zh-CN/agent-sdk/permissions#permission-modes) | 在[获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话中为 `default`。在不获取功能标志的会话中，例如在第三方提供商上或关闭遥测的情况下，Claude Code v2.1.285 或更高版本中为 `auto`，较早版本中为 `default`。组织策略禁止 `auto` 默认值的会话改为以 `default` 启动 |

90| 在终端或通过 [VS Code 扩展](/docs/zh-CN/vs-code) | `auto`（Claude Code v2.1.283 或更高版本）；在较早的版本上，在 Pro、Max 或 Team 计划中 `auto`（在[获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话中），否则为 `default` |90| 在终端或通过 [VS Code 扩展](/docs/zh-CN/vs-code) | Claude Code v2.1.283 或更高版本中为 `auto`；在较早的版本上，在 Pro、Max 或 Team 计划中为 `auto`（在[获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话中），否则为 `default` |

91 91

92在您[安装或升级后的第一个会话](/docs/zh-CN/env-vars#first-session-after-an-install-or-upgrade)中，Claude Code 可以在其功能标志到达之前选择起始权限模式。该会话可能以与表格不同的权限模式启动，您的下一个会话与表格匹配。92在您[安装或升级后的第一个会话](/docs/zh-CN/env-vars#first-session-after-an-install-or-upgrade)中，Claude Code 可以在其功能标志到达之前选择起始权限模式。该会话可能以与表格不同的权限模式启动，您的下一个会话与表格匹配。

93 93

98* 在终端中，一次，在会话顶部98* 在终端中，一次，在会话顶部

99* 在 VS Code 扩展中，作为新对话屏幕上的卡片，保留直到您关闭它99* 在 VS Code 扩展中，作为新对话屏幕上的卡片，保留直到您关闭它

100 100

101在 Pro、Max 和 Team 计划上，如果您的 `~/.claude/settings.json` 将 `defaultMode` 设置为 `auto` 以外的值，且没有其他设置文件设置它，您的会话继续以该模式启动。Claude Code 在终端或 VS Code 扩展中询问一次是否将设置更改为自动模式。如果您拒绝，您的设置保持原样。101如果您的 `~/.claude/settings.json` 将 `defaultMode` 设置为 `auto` 以外的值，且没有其他设置文件设置它，您的会话继续以该模式启动。在 Pro、Max 和 Team 计划上，以及在[不获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话中，Claude Code 在终端或 VS Code 扩展中询问一次是否将设置更改为自动模式。如果您拒绝，您的设置保持原样。

102 102

103<h3 id="start-in-a-different-mode">103<h3 id="start-in-a-different-mode">

104 以不同的权限模式启动104 以不同的权限模式启动

302自动模式还会促使 Claude 继续工作而不停下来提出澄清问题，尽管当您的提示或技能明确依赖它时 Claude 仍会询问。为了在仍会提示您的模式中获得更强的自主行为，请改为设置[主动输出风格](/docs/zh-CN/output-styles)。302自动模式还会促使 Claude 继续工作而不停下来提出澄清问题，尽管当您的提示或技能明确依赖它时 Claude 仍会询问。为了在仍会提示您的模式中获得更强的自主行为，请改为设置[主动输出风格](/docs/zh-CN/output-styles)。

303 303

304<Warning>304<Warning>

305 自动模式减少了权限提示，但不保证安全。将其用于您信任总体方向的任务，而不是作为敏感操作审查的替代品。305 自动模式减少权限提示但不保证安全。将其用于您信任总体方向的任务，而不是作为敏感操作审查的替代品。

306</Warning>306</Warning>

307 307

308自动模式仅在您的账户满足以下所有要求时可用：308自动模式仅在您的账户满足所有这些要求时可用：

309 309

310* **计划**：所有计划。310* **计划**：所有计划。

311* **组织**：在 Team 和 Enterprise 上，自动模式默认可用。管理员可以通过在[托管设置](/docs/zh-CN/managed-settings)中将 `permissions.disableAutoMode` 设置为 `"disable"` 来为组织关闭它。311* **组织**：在 Team 和 Enterprise 上，自动模式默认可用。管理员可以通过在[托管设置](/docs/zh-CN/managed-settings)中将 `permissions.disableAutoMode` 设置为 `"disable"` 来为组织关闭它。

312* **模型**：在 Anthropic API 和 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 上，Claude Opus 4.6 或更高版本、Sonnet 4.6 或更高版本，或[Fable 模型](/docs/zh-CN/model-config#work-with-fable)。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)会话上，仅 Claude Sonnet 5 或更高版本、Opus 4.7 或更高版本和 Fable 模型。较旧的模型，包括 Sonnet 4.5、Opus 4.5、Haiku 和 claude-3 模型，在任何提供商上都不受支持。312* **模型**：在 Anthropic API 和 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 上，Claude Opus 4.6 或更高版本、Sonnet 4.6 或更高版本，或[Fable 模型](/docs/zh-CN/model-config#work-with-fable)。在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)会话上，仅 Claude Sonnet 5 或更高版本、Opus 4.7 或更高版本和 Fable 模型。较旧的模型，包括 Sonnet 4.5、Opus 4.5、Haiku 和 claude-3 模型，在任何提供商上都不受支持。

313* **提供商**：在 Anthropic API、AWS 上的 Claude Platform、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的 Claude 应用网关会话上默认可用。313* **提供商**：在 Anthropic API、AWS 上的 Claude Platform、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和已登录的 Claude 应用网关会话上默认可用。

314 314

315如果 Claude Code 报告自动模式不可用，首先检查这些要求以及任何设置文件是否设置了 [`disableAutoMode`](/docs/zh-CN/settings-reference#disableautomode)。Anthropic 也可能已在服务器端关闭了自动模式，或服务器可能已为您的账户拒绝了自动模式。收到任一答案的会话会保持自动模式关闭直到会话结束，因此稍后启动新会话。315如果 Claude Code 报告自动模式不可用，首先检查这些要求以及任何设置文件是否设置了 [`disableAutoMode`](/docs/zh-CN/settings-reference#disableautomode)。Anthropic 也可能已在服务器端关闭自动模式，或服务器可能已为您的账户拒绝自动模式。接收任一答案的会话会保持自动模式关闭直到会话结束，因此稍后启动新会话。

316 316

317一条单独的消息命名一个模型并说自动模式"无法确定"操作的安全性意味着分类器请求失败。该失败通常是暂时的，但在 Amazon Bedrock 上，它可能会重复直到您的账户可以调用命名的模型。有关原因和处理方法，请参阅[错误参考](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)。317一条单独的消息命名一个模型并说自动模式"无法确定"操作的安全性意味着分类器请求失败。该失败通常是暂时的，但在 Amazon Bedrock 上，它可能会重复直到您的账户可以调用命名的模型。有关原因和处理方法，请参阅[错误参考](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)。

318 318

322 Bedrock、Agent Platform 或 Foundry 上的自动模式322 Bedrock、Agent Platform 或 Foundry 上的自动模式

323</h3>323</h3>

324 324

325在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai)、[Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 和已登录的[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)会话上，自动模式默认可用。在 Claude Code v2.1.283 或更高版本中，它也是交互式终端和 [VS Code](/docs/zh-CN/vs-code) 会话的[内置起始权限模式](#which-mode-a-session-starts-in)。要自己选择起始权限模式，请按照[以不同权限模式启动](#start-in-a-different-mode)的描述设置 `permissions.defaultMode`，或从 VS Code 扩展的模式指示器中选择权限模式。325在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai)、[Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 和已登录的[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)会话上，自动模式默认可用。当没有其他设置权限模式时，它也是[内置起始权限模式](#which-mode-a-session-starts-in)，在该部分的表列出的版本上。要自己选择起始权限模式，请按照[以不同权限模式启动](#start-in-a-different-mode)的描述设置 `permissions.defaultMode`，或从 VS Code 扩展的模式指示器中选择权限模式。

326 326

327仅这些提供商上支持 Claude Sonnet 5 或更高版本、Opus 4.7 或更高版本和 Fable 模型。在任何其他模型上，会话以 Manual 模式启动。327这些提供商上仅支持 Claude Sonnet 5 或更高版本、Opus 4.7 或更高版本和 Fable 模型。在任何其他模型上，会话以 Manual 模式启动。

328 328

329要防止开发人员使用自动模式，请在[托管设置](/docs/zh-CN/managed-settings)中将 `disableAutoMode` 设置为 `"disable"`。这会从 `Shift+Tab` 循环中移除 `auto`，并且使用 `--permission-mode auto` 启动的会话会以 Manual 模式启动。已在自动模式中运行的会话在设置从[管理员部署的源](/docs/zh-CN/managed-settings#which-managed-source-claude-code-uses)到达该会话时会离开它，并显示 `auto mode disabled by settings`。在 v2.1.251 之前，运行中的会话会保持自动模式直到它结束。329要防止开发人员使用自动模式，请在[托管设置](/docs/zh-CN/managed-settings)中将 `disableAutoMode` 设置为 `"disable"`。这会从 `Shift+Tab` 循环中移除 `auto`，并且使用 `--permission-mode auto` 启动的会话以 Manual 模式启动。已在自动模式中运行的会话在设置从[管理员部署的源](/docs/zh-CN/managed-settings#which-managed-source-claude-code-uses)到达该会话时会离开它，并显示 `auto mode disabled by settings`。在 v2.1.251 之前，运行中的会话会保持自动模式直到它结束。

330 330

331在 v2.1.158 到 v2.1.206 中，自动模式在这些提供商上是关闭的，直到您设置 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`，并且 Claude Code 在这些提供商上忽略 `defaultMode: "auto"`，除非也设置了该变量。该变量仍被接受以保持兼容性，从 v2.1.207 开始无效。331在 v2.1.158 到 v2.1.206 中，自动模式在这些提供商上是关闭的，直到您设置 `CLAUDE_CODE_ENABLE_AUTO_MODE=1`，并且 Claude Code 在这些提供商上忽略 `defaultMode: "auto"`，除非也设置了该变量。该变量仍被接受以保持兼容性，从 v2.1.207 开始无效。

332 332

340* **云提供商、LLM 网关或代理**：在 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws)、Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，以及每当您将 `ANTHROPIC_BASE_URL` 指向[LLM 网关或代理](/docs/zh-CN/llm-gateway)时，无论您的计划如何。默认询问需要 Claude Code v2.1.278 或更高版本。340* **云提供商、LLM 网关或代理**：在 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws)、Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，以及每当您将 `ANTHROPIC_BASE_URL` 指向[LLM 网关或代理](/docs/zh-CN/llm-gateway)时，无论您的计划如何。默认询问需要 Claude Code v2.1.278 或更高版本。

341* **已登录的[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)会话**：需要 Claude Code v2.1.280 或更高版本341* **已登录的[Claude 应用网关](/docs/zh-CN/claude-apps-gateway)会话**：需要 Claude Code v2.1.280 或更高版本

342 342

343服务器审查操作的地方，其判决决定了它们。还有两种其他可能的结果：343服务器审查操作的地方，其判决决定了它们。另外两种结果是可能的：

344 344

345* **服务器不审查会话**：响应完成时没有审查结果，或服务器回答它不审查此会话。最常见的原因是 LLM 网关或代理丢弃审查请求或结果，以及平台、区域或凭证还没有服务器端检查。Claude Code 回退到自己的分类器请求。一旦该回退对会话的其余部分生效，它会在那些请求被计费的账户上显示[关于分类器请求费用的通知](/docs/zh-CN/auto-mode-classifier-billing)。345* **服务器不审查会话**：响应完成时没有审查结果，或服务器回答它不审查此会话。最常见的原因是 LLM 网关或代理丢弃审查请求或结果，以及平台、区域或凭证还没有服务器端检查。Claude Code 回退到自己的分类器请求。一旦该回退对会话的其余部分生效，它会在那些请求被计费的账户上显示[关于分类器请求费用的通知](/docs/zh-CN/auto-mode-classifier-billing)。

346* **服务器对操作没有给出判决**：Claude Code 拒绝该操作而不是运行它而不审查。在任何连接上，当响应在审查结果到达之前结束或结果以 Claude Code 无法读取的形式到达时，这会发生。丢弃响应或重写结果的 LLM 网关或代理可能导致任一情况。在直接连接到 Anthropic API 时，当服务器对操作的检查失败时也会发生，例如超时。[服务器未返回安全判决](/docs/zh-CN/errors#the-server-returned-no-safety-verdict)涵盖拒绝消息、拒绝重复时发生的情况以及处理方法。346* **服务器对操作没有给出判决**：Claude Code 拒绝该操作而不是运行它未审查。在任何连接上，当响应在审查结果到达之前结束或结果以 Claude Code 无法读取的形式到达时，这会发生。LLM 网关或代理切断响应或重写结果可能导致任一情况。在直接连接到 Anthropic API 时，当服务器对操作的检查失败时也会发生，例如超时。[服务器未返回安全判决](/docs/zh-CN/errors#the-server-returned-no-safety-verdict)涵盖拒绝消息、拒绝重复时发生的情况以及处理方法。

347 347

348要跳过询问服务器并始终使用 Claude Code 自己的分类器请求，请设置 [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](/docs/zh-CN/env-vars)。在直接连接到 Anthropic API 时，该变量需要 Claude Code v2.1.281 或更高版本。将其设置为 `1` 会在没有它的会话中打开服务器审查，例如 `-p` 或 Agent SDK 会话，除非您也设置了 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`。如果您设置 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` 并保持 `CLAUDE_CODE_AUTO_MODE_SERVER` 未设置，Claude Code 也会停止询问服务器，除了[禁用预发布功能](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities)描述的情况。348要跳过询问服务器并始终使用 Claude Code 自己的分类器请求，请设置 [`CLAUDE_CODE_AUTO_MODE_SERVER=0`](/docs/zh-CN/env-vars)。在直接连接到 Anthropic API 时，该变量需要 Claude Code v2.1.281 或更高版本。将其设置为 `1` 会在没有它的会话中打开服务器审查，例如 `-p` 或 Agent SDK 会话，除非您也设置了 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`。如果您设置 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` 并保持 `CLAUDE_CODE_AUTO_MODE_SERVER` 未设置，Claude Code 也会停止询问服务器，除了[禁用预发布功能](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities)描述的情况。

349 349

363* 修改共享基础设施363* 修改共享基础设施

364* 不可逆地销毁会话前存在的文件364* 不可逆地销毁会话前存在的文件

365* 强制推送365* 强制推送

366* 提交或推送会在运行时向仓库外发送秘密或敏感数据的更改，或扩大部署公开的内容。这涵盖将秘密传递给不已接收它的目的地的 CI 工作流或部署配置、读取秘密存储并发送数据的脚本或设置步骤，以及扩大部署发布内容的配置更改，例如注册表、可见性、工件或源映射设置。检查适用于任何分支，即使仓库是公开的也适用，并在提交或推送时触发，无论该提交或推送是否触发管道；清除它需要命名执行效果，而不仅仅是提交或推送。在 v2.1.211 之前，此检查的范围仅限于默认分支：当推送携带敏感内容、隐瞒或误描述相对于您要求的内容、从仓库外移植的内容或绕过您要求的审查的内容时，推送到那里会被阻止366* 提交或推送会在运行时向仓库外发送秘密或敏感数据的更改，或扩大部署公开的内容。这涵盖将秘密传递给不已接收它的目的地的 CI 工作流或部署配置、读取秘密存储并发送数据的脚本或设置步骤，以及扩大部署发布内容的配置更改，例如注册表、可见性、工件或源映射设置。检查适用于任何分支，即使仓库是公开的也适用，并在提交或推送时触发，无论该提交或推送是否触发管道；清除它需要命名执行效果，而不仅仅是提交或推送。在 v2.1.211 之前，此检查的范围仅限于默认分支：推送到那里在携带敏感内容、隐瞒或误描述相对于您要求的内容、从仓库外移植的内容或绕过您要求的审查的内容时被阻止

367* `git reset --hard`、`git checkout -- .`、`git restore .`、`git clean -fd`、`git stash drop` 或 `git stash clear`，分类器假设会丢弃未提交的更改367* `git reset --hard`、`git checkout -- .`、`git restore .`、`git clean -fd`、`git stash drop` 或 `git stash clear`，分类器推测会丢弃未提交的更改

368* `git commit --amend` 当 HEAD 处的提交不是在此会话中创建的368* `git commit --amend` 当 HEAD 处的提交不是在此会话中创建的

369* 从 v2.1.198 开始，`git commit --amend` 当 HEAD 处的提交已被推送。仅消息重述不被阻止：`--amend -m` 在 Claude 在此会话期间创建的提交上没有新暂存的内容369* 从 v2.1.198 开始，`git commit --amend` 当 HEAD 处的提交已被推送。仅消息重述不被阻止：`--amend -m` 在此会话中 Claude 创建的提交上没有新暂存的内容

370* `terraform destroy`、`pulumi destroy`、`cdk destroy` 或 `terragrunt destroy`，以及应用销毁资源的计划370* `terraform destroy`、`pulumi destroy`、`cdk destroy` 或 `terragrunt destroy`，以及应用销毁资源的计划

371* 写入秘密管理器，或更改 DNS 记录或 TLS 证书371* 写入秘密管理器，或更改 DNS 记录或 TLS 证书

372* 合并没有人类批准的拉取请求、批准 Claude 自己的拉取请求或禁用 CI 检查372* 合并没有人类批准的拉取请求、批准 Claude 自己的拉取请求或禁用 CI 检查

379* 打开隧道或反向 shell 使本地服务可从公网访问379* 打开隧道或反向 shell 使本地服务可从公网访问

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

381* 访问在您的[环境](/docs/zh-CN/auto-mode-config#define-trusted-infrastructure)中列为敏感数据位置的位置，或从一个位置复制数据。从 v2.1.198 开始，这也阻止从一个位置向条目排除的受众发送数据381* 访问在您的[环境](/docs/zh-CN/auto-mode-config#define-trusted-infrastructure)中列为敏感数据位置的位置，或从一个位置复制数据。从 v2.1.198 开始，这也阻止从一个位置向条目排除的受众发送数据

382* 绕过您的内部包注册表将包安装路由到公共注册表。从 v2.1.198 开始，这也适用于您在对话中告诉 Claude 内部注册表或镜像存在的情况，而不仅仅是在您的环境中列出的情况382* 绕过您的内部包注册表路由包安装到公开注册表。从 v2.1.198 开始，这也适用于您在对话中告诉 Claude 内部注册表或镜像存在的情况，而不仅仅是在您的环境中列出的情况

383* 使用禁用安全防护的标志运行命令，如 `--insecure`383* 使用禁用安全防护的标志运行命令，如 `--insecure`

384* 启动在没有人类批准或沙箱的情况下运行的自主代理循环，例如使用 `--dangerously-skip-permissions` 或 `--no-sandbox` 启动的循环。从 v2.1.198 开始，这也涵盖运行禁用隔离和按操作批准的第三方代理或评估工具，例如使用 `--yes-always` 启动的运行器384* 启动在没有人类批准或沙箱的情况下运行的自主代理循环，例如使用 `--dangerously-skip-permissions` 或 `--no-sandbox` 启动的循环。从 v2.1.198 开始，这也涵盖运行禁用隔离和按操作批准的第三方代理或评估工具，例如使用 `--yes-always` 启动的运行器

385* [Chrome 中的 Claude](/docs/zh-CN/chrome)浏览器操作可能会向外源发送页面内容、cookie 或凭证385* [Chrome 中的 Claude](/docs/zh-CN/chrome)浏览器操作可能会向源外发送页面内容、cookie 或凭证

386 386

387其中几个类别取决于[环境](/docs/zh-CN/auto-mode-config#define-trusted-infrastructure)条目，例如敏感的远程目标和受保护的 IaC 范围，您可以将其缩小到具体名称。387其中几个类别取决于[环境](/docs/zh-CN/auto-mode-config#define-trusted-infrastructure)条目，例如敏感的远程目标和受保护的 IaC 范围，您可以将其缩小到具体名称。

388 388

389Claude Code v2.1.198 及更高版本也默认阻止这些：389Claude Code v2.1.198 及更高版本也默认阻止这些：

390 390

391* 通过通配符、glob 或年龄过滤器而不是特定命名路径删除 `/tmp`、`$TMPDIR` 或其他共享暂存或缓存目录中的文件391* 通过通配符、glob 或年龄过滤器而不是特定命名路径删除 `/tmp`、`$TMPDIR` 或另一个共享暂存或缓存目录中的文件

392* 在您自己的消息未授权这些详情给该收件人的情况下，在发送、上传、发布或写入给其他人或共享系统的内容中包含敏感详情。当仓库在信任边界外或公开时，PR 和问题正文、提交消息和评论计为这种出站内容，包括您组织自己的公开仓库；内部文件路径、代码名称、实时 API 响应数据（如电子邮件或账户标识符）和基础设施标识符计为敏感详情。PR、问题和提交消息范围需要 Claude Code v2.1.200 或更高版本。PR 或问题正文中的实时个人数据（如电子邮件地址、账户或组织标识符或使用指标）需要您命名这些详情和收件人，无论仓库的可见性或信任边界如何。该检查需要 Claude Code v2.1.203 或更高版本392* 在发送、上传、发布或写入其他人或共享系统的内容中包含敏感详情，当您自己的消息没有为该收件人授权这些详情时。PR 和问题正文、提交消息和评论在仓库在信任边界外或公开时计为这种出站内容，包括您组织自己的公开仓库；内部文件路径、代码名称、实时 API 响应数据（如电子邮件或账户标识符）和基础设施标识符计为敏感详情。PR、问题和提交消息范围需要 Claude Code v2.1.200 或更高版本。PR 或问题正文中的实时个人数据（如电子邮件地址、账户或组织标识符或使用指标）需要您命名这些详情和收件人，无论仓库的可见性或信任边界如何。该检查需要 Claude Code v2.1.203 或更高版本

393* 向 Claude Code 自己的 tmux 窗格发送按键以驱动其自己的界面，分类器将其视为 Claude 更改自己的权限或监督393* 向 Claude Code 自己的 tmux 窗格发送按键以驱动其自己的界面，分类器将其视为 Claude 更改自己的权限或监督

394 394

395Claude Code v2.1.200 及更高版本也默认阻止这些：395Claude Code v2.1.200 及更高版本也默认阻止这些：

396 396

397* 注释掉、删除或强制通过保护安全行为的测试或断言，例如身份验证、访问控制、输入验证或沙箱397* 注释掉、删除或强制通过保护安全行为的测试或断言，例如身份验证、访问控制、输入验证或沙箱

398* 删除或拆除 Claude 在会话中未创建的有状态资源，当没有更具体的删除规则适用且您未命名该资源时398* 删除或拆除 Claude 在会话中未创建的有状态资源，当没有更具体的删除规则适用且您没有命名该资源时

399* 将 API 基础 URL、代理端点、webhook 接收器或注册表镜像重新指向不适合任务的第三方主机，包括在 `.env.example` 等示例文件中399* 将 API 基础 URL、代理端点、webhook 接收器或注册表镜像重新指向不适合任务的第三方主机，包括在 `.env.example` 等示例文件中

400* 使用 `git remote set-url` 或 `git remote add` 更改推送去向，除非您命名了新远程400* 使用 `git remote set-url` 或 `git remote add` 更改推送去向，除非您命名了新远程

401* 将秘密或个人或受信数据推送到已知为公开的仓库，或将不属于该仓库自己工作的机密材料推送到那里。dotfiles 仓库自己的主题是个人或受信数据的唯一例外，来自私有仓库到任何公开表面的内容以相同方式被阻止；两项改进都需要 Claude Code v2.1.203 或更高版本。在 v2.1.203 之前，个人数据与机密材料分组，仅当它不属于该仓库自己的工作时才被阻止。当仓库的可见性未确定时，分类器不仅基于此阻止；它改为根据其他规则判断内容401* 推送秘密或个人或受信任的数据到已知为公开的仓库，或推送不属于该仓库自己工作的机密材料到那里。dotfiles 仓库自己的主题是个人或受信任数据的唯一例外，来自私有仓库到任何公开表面的内容以相同方式被阻止；两项改进都需要 Claude Code v2.1.203 或更高版本。在 v2.1.203 之前，个人数据与机密材料分组，仅在不属于该仓库自己的工作时被阻止。当仓库的可见性未建立时，分类器不仅基于此阻止；它改为根据其他规则判断内容

402* 针对不同仓库或组织打开拉取请求、使用 `gh repo fork` 进行分叉或推送到第三方仓库，除非您命名了该外部目标402* 针对不同仓库或组织打开拉取请求、使用 `gh repo fork` 进行分叉或推送到第三方仓库，除非您命名了该外部目标

403 403

404Claude Code v2.1.203 及更高版本也默认阻止这些：404Claude Code v2.1.203 及更高版本也默认阻止这些：

405 405

406* 来自敏感本地存储或其名称、路径或类型将其标记为敏感的文件的内容进入提交、推送、PR 或问题文本、gist 或粘贴或包发布，除非您命名了源和目的地。会话记录和对话日志、凭证和配置点文件夹（如 SSH 密钥、云凭证、浏览器配置文件和 shell 历史记录）以及用户数据导出都计为此，仓库是私有的不会清除它406* 来自敏感本地存储或其名称、路径或类型将其标记为敏感的文件的内容进入提交、推送、PR 或问题文本、gist 或粘贴或包发布，除非您命名了源和目的地。会话记录和对话日志、凭证和配置点文件夹（如 SSH 密钥、云凭证、浏览器配置文件和 shell 历史）以及用户数据导出都计为此，仓库是私有的不会清除它

407 407

408Claude Code v2.1.205 及更高版本也默认阻止这些：408Claude Code v2.1.205 及更高版本也默认阻止这些：

409 409

410* 写入 Claude Code 会话记录、`~/.claude/projects/` 下的 `.jsonl` 历史文件或您配置的配置目录，无论是直接还是通过 shell 命令。该规则也涵盖 Claude Code 为其自己的检查附加到每个记录条目的元数据行。读取记录不被阻止410* 写入 Claude Code 会话记录、`~/.claude/projects/` 下的 `.jsonl` 历史文件或您配置的配置目录，无论是直接还是通过 shell 命令。该规则也涵盖 Claude Code 为其自己的检查附加到每个记录条目的元数据行。读取记录不被阻止

411* 递归强制删除，例如 `rm -rf "$VAR"` 或 `Remove-Item -Recurse -Force $dir`，其目标是分类器看不到的任何地方分配的 shell 变量，或以这样的变量为根的 glob。该值仅来自较早的命令输出，分类器从不接收，因此分类器无法根据其他删除规则验证删除目标。当您命名被删除的确切路径或 Claude 使用写入命令的已解析文字路径重新运行删除时，该块会清除。分类器可以解析其目标的删除不受影响。411* 递归强制删除，例如 `rm -rf "$VAR"` 或 `Remove-Item -Recurse -Force $dir`，其目标是在分类器看到的对话中任何地方都未分配的 shell 变量，或以这样的变量为根的 glob。该值仅来自较早的命令输出，分类器永远不会接收，因此分类器无法根据其他删除规则验证删除目标。当您命名被删除的确切路径或 Claude 使用写入命令的已解析文字路径重新运行删除时，该块会清除。其目标分类器可以解析的删除不受影响。

412 412

413 直接在变量下的 glob，如 `rm -rf "$VAR"/*`，是[关键路径](#critical-paths)。`Remove-Item` 目标是裸 `*` 或以 `/*` 或 `\*` 结尾的从不到达分类器：Claude Code [直接拒绝它们](#remove-item-in-powershell)。413 直接在变量下的 glob，如 `rm -rf "$VAR"/*`，是[关键路径](#critical-paths)。`Remove-Item` 目标是裸 `*` 或以 `/*` 或 `\*` 结尾的永远不会到达分类器：Claude Code [直接拒绝它们](#remove-item-in-powershell)。

414 414

415Claude Code v2.1.257 及更高版本也默认阻止这些：415Claude Code v2.1.257 及更高版本也默认阻止这些：

416 416

417* 从云实例元数据端点请求凭证，例如 `169.254.169.254`，或使用机器自己的服务账户或节点身份显式验证云、集群或注册表调用417* 从云实例元数据端点请求凭证，例如 `169.254.169.254`，或使用机器自己的服务账户或节点身份显式验证云、集群或注册表调用

418* 通过直接请求以外的路由到达公共主机，例如隧道、反向 shell 或重写为指向外部的解析器或代理配置418* 通过直接请求以外的路由到达公开主机，例如隧道、反向 shell 或重写为指向外部的解析器或代理配置

419* 读取属于主机而不是您的任务的凭证，例如节点证书或节点的容器注册表身份验证419* 读取属于主机而不是您的任务的凭证，例如节点证书或节点的容器注册表身份验证

420* 连接到或扫描 Claude 未启动的同级容器、pod 或 VM，或容器下的节点420* 连接到或扫描 Claude 未启动的同级容器、pod 或 VM，或容器下的节点

421 421

438* 向您在 [`environment`](/docs/zh-CN/auto-mode-config#define-trusted-infrastructure) 中列出的受信任域、存储桶和服务发送数据。这仅涵盖数据流，不涵盖同一基础设施上的破坏性或凭证操作438* 向您在 [`environment`](/docs/zh-CN/auto-mode-config#define-trusted-infrastructure) 中列出的受信任域、存储桶和服务发送数据。这仅涵盖数据流，不涵盖同一基础设施上的破坏性或凭证操作

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

440 440

441沙箱命令默认不获得网络访问。Claude 在命令本身上命名命令需要的主机，分类器与命令一起审查它们，批准的列表仅为该一个命令打开这些主机。[按命令允许的域](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)涵盖列表可以和不能打开什么以及命令到达未列出的主机时发生的情况。441沙箱命令默认不获得网络访问。Claude 在命令本身上命名命令需要的主机，分类器与命令一起审查它们，批准的列表仅为该一个命令打开这些主机。[每个命令允许的域](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)涵盖列表可以和不能打开什么以及命令到达未列出的主机时发生的情况。

442 442

443运行 `claude auto-mode defaults` 以将完整规则列表打印为 JSON。如果常规操作被阻止，管理员可以通过 `autoMode.environment` 设置添加受信任的仓库、存储桶和服务：请参阅[配置自动模式](/docs/zh-CN/auto-mode-config)。443运行 `claude auto-mode defaults` 以将完整规则列表打印为 JSON。如果常规操作被阻止，管理员可以通过 `autoMode.environment` 设置添加受信任的仓库、存储桶和服务：请参阅[配置自动模式](/docs/zh-CN/auto-mode-config)。

444 444

463 您在对话中陈述的边界463 您在对话中陈述的边界

464</h3>464</h3>

465 465

466分类器将您在对话中陈述的边界视为阻止信号。如果您告诉 Claude"不要推送"或"在我审查前等待再部署"，分类器会阻止匹配的操作，即使默认规则会允许它们。边界保持有效直到您在后续消息中解除它。Claude 自己的判断条件已满足不会解除它。466分类器将您在对话中陈述的边界视为阻止信号。如果您告诉 Claude"不要推送"或"在我审查后再部署"，分类器会阻止匹配的操作，即使默认规则会允许它们。边界保持有效直到您在后续消息中解除它。Claude 自己的条件已满足的判断不会解除它。

467 467

468边界不存储为规则。分类器在每次检查时从记录中重新读取它们，因此如果[上下文压缩](/docs/zh-CN/costs#reduce-token-usage)移除陈述它的消息，边界可能会丢失。为了硬保证，请改为添加[拒绝规则](/docs/zh-CN/permissions#permission-rule-syntax)。468边界不存储为规则。分类器在每次检查时从记录中重新读取它们，因此如果[上下文压缩](/docs/zh-CN/costs#reduce-token-usage)移除陈述边界的消息，边界可能会丢失。为了硬保证，请改为添加[拒绝规则](/docs/zh-CN/permissions#permission-rule-syntax)。

469 469

470<h3 id="approvals-you-state-in-conversation">470<h3 id="approvals-you-state-in-conversation">

471 您在对话中陈述的批准471 您在对话中陈述的批准

473 473

474如果您告诉 Claude 被阻止的操作是允许的，分类器将其读取为您的批准并可以清除阻止。您如何措辞决定了操作是否运行以及批准到达多远：474如果您告诉 Claude 被阻止的操作是允许的，分类器将其读取为您的批准并可以清除阻止。您如何措辞决定了操作是否运行以及批准到达多远：

475 475

476* **命名操作及其具体情况**：您的消息必须命名操作和使其危险的具体事物，例如强制推送的分支。仅命名动词不会清除任何内容，因此"您可以强制推送"会使阻止保持有效。476* **命名操作及其具体情况**：您的消息必须命名操作和使其危险的具体事项，例如强制推送的分支。仅命名动词不会清除任何内容，因此"您可以强制推送"会使阻止保持有效。

477* **期望它涵盖一个操作**：批准涵盖您命名的破坏性操作，因此稍后的操作再次被阻止，除非您授予批准为常设。要停止一次一个地批准常规模式，请将其添加到 [`autoMode.allow`](/docs/zh-CN/auto-mode-config#override-the-block-and-allow-rules)。477* **期望它涵盖一个操作**：批准涵盖您命名的破坏性操作，因此稍后的操作再次被阻止，除非您授予批准为常设。要停止一次一个地批准常规模式，请将其添加到 [`autoMode.allow`](/docs/zh-CN/auto-mode-config#override-the-block-and-allow-rules)。

478* **某些阻止保持有效**：[分类器的优先级顺序](/docs/zh-CN/auto-mode-config#override-the-block-and-allow-rules)规定了您的批准可以到达哪些阻止。要运行它不会清除的步骤，请[离开自动模式](#switch-permission-modes)并回答权限提示。478* **某些阻止保持有效**：[分类器的优先级顺序](/docs/zh-CN/auto-mode-config#override-the-block-and-allow-rules)列出您的批准可以到达的阻止。要运行它不会清除的步骤，请[离开自动模式](#switch-permission-modes)并回答权限提示。

479 479

480<h3 id="when-auto-mode-falls-back">480<h3 id="when-auto-mode-falls-back">

481 当自动模式回退时481 当自动模式回退时

485 485

486* **被阻止的操作**：Claude Code 显示通知并在 `/permissions` 下的**最近拒绝**选项卡中列出操作，您可以按 `r` 使用手动批准重试它。486* **被阻止的操作**：Claude Code 显示通知并在 `/permissions` 下的**最近拒绝**选项卡中列出操作，您可以按 `r` 使用手动批准重试它。

487* **重复阻止**：如果分类器连续阻止操作 3 次或总共 20 次，自动模式暂停，Claude Code 恢复提示。批准提示的操作恢复自动模式。有关如何计数阻止的信息，请参阅[重复阻止阈值](#repeated-block-thresholds)。487* **重复阻止**：如果分类器连续阻止操作 3 次或总共 20 次，自动模式暂停，Claude Code 恢复提示。批准提示的操作恢复自动模式。有关如何计数阻止的信息，请参阅[重复阻止阈值](#repeated-block-thresholds)。

488* **分类器无判决**：当独立于自动模式的安全检查拒绝分类器自己的请求或分类器的响应不解析时，Claude Code 拒绝操作而不显示通知或**最近拒绝**条目。有关每种情况显示的消息和处理方法，请参阅[自动模式无法确定操作的安全性](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)。488* **分类器无判决**：当与自动模式分离的安全检查拒绝分类器自己的请求或分类器的响应不解析时，Claude Code 拒绝操作而不显示通知或**最近拒绝**条目。有关每种情况显示的消息和处理方法，请参阅[自动模式无法确定操作的安全性](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)。

489* **服务器无判决**：在[服务器端分类器审查](#server-side-classifier-review)下，Claude Code 拒绝服务器给不出判决的操作，并在连续十个响应都没有判决后停止轮次。请参阅[服务器未返回安全判决](/docs/zh-CN/errors#the-server-returned-no-safety-verdict)。489* **服务器无判决**：在[服务器端分类器审查](#server-side-classifier-review)下，Claude Code 拒绝服务器给不出判决的操作，并在连续十个响应都没有判决后停止轮次。请参阅[服务器未返回安全判决](/docs/zh-CN/errors#the-server-returned-no-safety-verdict)。

490* **检查期间的模式切换**：如果您在分类器检查待处理时切换权限模式，Claude Code 丢弃新模式不会请求的判决。您改为被提示批准，或在 [`dontAsk` 模式](#allow-only-pre-approved-tools-with-dontask-mode)中自动拒绝操作。490* **检查期间的模式切换**：如果您在分类器检查待处理时切换权限模式，Claude Code 丢弃新模式不会请求的判决。您改为被提示批准，或在 [`dontAsk` 模式](#allow-only-pre-approved-tools-with-dontask-mode)中操作被自动拒绝。

491 491

492<h4 id="repeated-block-thresholds">492<h4 id="repeated-block-thresholds">

493 重复阻止阈值493 重复阻止阈值

494</h4>494</h4>

495 495

4963 个连续阻止和 20 个总阻止的阈值不可配置。总计数器对会话持续并仅在其自己的限制触发回退时重置。当独立于自动模式的安全检查拒绝分类器自己的请求时，Claude Code 不计数拒绝到任一阈值。4963 个连续阻止和 20 个总阻止的阈值不可配置。总计数器对会话持续并仅在其自己的限制触发回退时重置。当与自动模式分离的安全检查拒绝分类器自己的请求时，Claude Code 不计数拒绝到任一阈值。

497 497

498没有 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 的[非交互式](/docs/zh-CN/headless) `-p` 运行没有回退提示。当重复阻止达到阈值时，操作不运行，Claude 继续工作。Claude Code 不停止运行。498没有 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 的[非交互式](/docs/zh-CN/headless) `-p` 运行没有回退提示。当重复阻止到达阈值时，操作不运行，Claude 继续工作。Claude Code 不停止运行。

499 499

500重复阻止通常意味着分类器缺少关于您的基础设施的上下文。使用 `/feedback` 报告误报，或让管理员[配置受信任的基础设施](/docs/zh-CN/auto-mode-config)。500重复阻止通常意味着分类器缺少关于您的基础设施的上下文。使用 `/feedback` 报告假阳性，或让管理员[配置受信任的基础设施](/docs/zh-CN/auto-mode-config)。

501 501

502<h3 id="how-auto-mode-evaluates-actions">502<h3 id="how-auto-mode-evaluates-actions">

503 自动模式如何评估操作503 自动模式如何评估操作

508<span id="how-the-classifier-evaluates-actions" />508<span id="how-the-classifier-evaluates-actions" />

509 509

510<AccordionGroup>510<AccordionGroup>

511 <Accordion title="分类器如何评估操作">511 <Accordion title="自动模式如何评估操作">

512 每个操作都经过固定的决策顺序。第一个匹配的步骤获胜：512 每个操作都经过固定的决策顺序。第一个匹配的步骤获胜：

513 513

514 1. 与您的[允许、询问或拒绝规则](/docs/zh-CN/permissions#manage-permissions)匹配的操作立即解决，但有以下例外：514 1. 与您的[允许、询问或拒绝规则](/docs/zh-CN/permissions#manage-permissions)匹配的操作立即解决，但有以下例外：

515 * 写入[受保护路径](#protected-paths)的操作路由到分类器，即使允许规则匹配515 * 写入[受保护路径](#protected-paths)的操作路由到分类器，即使允许规则匹配

516 * 没有允许规则批准针对[关键路径](#critical-paths)的 `rm` 和 `rmdir` 删除516 * 没有允许规则批准针对[关键路径](#critical-paths)的 `rm` 和 `rmdir` 删除

517 * 标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具直接提示您，即使允许规则匹配，连接器工具您的组织在会话中设置为 `ask` 的[也是如此](/docs/zh-CN/mcp#organization-controls-on-connector-tools)，其中该设置到达 Claude Code517 * 标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具直接提示您，即使允许规则匹配，连接器工具您的组织在会话中设置为 `ask` 的[组织控制](/docs/zh-CN/mcp#organization-controls-on-connector-tools)也是如此，其中该设置到达 Claude Code

518 * 携带[按命令允许的域](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)的 shell 命令也路由到分类器，即使允许规则匹配，因为规则批准命令，而不是其主机518 * 携带[每个命令允许的域](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)的 shell 命令也路由到分类器，即使允许规则匹配，因为规则批准命令，而不是其主机

519 * 与命令内容匹配的询问规则，例如 `Bash(git push *)`，回退到权限提示519 * 在命令内容上匹配的询问规则，例如 `Bash(git push *)`，回退到权限提示

520 * [符号链接检查](/docs/zh-CN/permissions#symlinks)解决为受保护路径的写入在 Claude 请求的路径本身不受保护时提示您520 * [符号链接检查](/docs/zh-CN/permissions#symlinks)解决为受保护路径的写入在 Claude 请求的路径本身不受保护时提示您

521 2. 只读操作和您工作目录中的文件编辑自动批准，除了写入[受保护路径](#protected-paths)和[工作目录外的第一次读取](#first-read-outside-the-working-directories)，这会提示您521 2. 只读操作和您工作目录中的文件编辑被自动批准，除了写入[受保护路径](#protected-paths)和[工作目录外的第一次读取](#first-read-outside-the-working-directories)，这会提示您

522 * 在具有[服务器端分类器审查](#server-side-classifier-review)的会话中，只读和[沙箱](/docs/zh-CN/sandboxing#sandbox-modes) shell 命令等待该审查，如果它标记它们则被阻止522 * 在具有[服务器端分类器审查](#server-side-classifier-review)的会话中，只读和[沙箱](/docs/zh-CN/sandboxing#sandbox-modes) shell 命令等待该审查，如果它标记它们则被阻止

523 * 您工作目录内的写入，[符号链接检查](/docs/zh-CN/permissions#symlinks)解决为其外的位置，提示您523 * 您工作目录内的写入，[符号链接检查](/docs/zh-CN/permissions#symlinks)解决为其外的位置，提示您

524 3. 其他所有内容都进入分类器，除了[关键路径删除](#critical-paths)在其默认处理下。在步骤 1 中直接提示您的连接器工具和 `requiresUserInteraction` MCP 工具从不到达分类器，因此既不是组织要求的批准也不是同意步骤自动批准524 3. 其他所有内容都进入分类器，除了[关键路径删除](#critical-paths)在其默认处理下。在步骤 1 中直接提示您的连接器工具和 `requiresUserInteraction` MCP 工具永远不会到达分类器，因此既不是组织要求的批准也不是同意步骤被自动批准

525 4. 如果分类器阻止，Claude 接收原因。在大多数会话中，原因命名分类器匹配的规则，例如 `[Data Exfiltration]`，而不是给出书面解释；请参阅[审查拒绝](/docs/zh-CN/auto-mode-config#review-denials)525 4. 如果分类器阻止，Claude 接收原因。在大多数会话中，原因命名分类器匹配的规则，例如 `[Data Exfiltration]`，而不是给出书面解释；请参阅[审查拒绝](/docs/zh-CN/auto-mode-config#review-denials)

526 526

527 进入自动模式时，授予任意代码执行的广泛允许规则被丢弃：527 进入自动模式时，授予任意代码执行的广泛允许规则被丢弃：

532 * `Agent` 允许规则532 * `Agent` 允许规则

533 * [`Monitor`](/docs/zh-CN/tools-reference#monitor-tool)允许规则，因为 Claude Code 通过 shell 运行 Monitor 命令533 * [`Monitor`](/docs/zh-CN/tools-reference#monitor-tool)允许规则，因为 Claude Code 通过 shell 运行 Monitor 命令

534 534

535 窄规则如 `Bash(npm test)` 保持有效。当您离开自动模式时，Claude Code 恢复丢弃的规则。在 v2.1.236 之前，Claude Code 在自动模式中保持 `Monitor` 允许规则有效，因此与整个工具匹配的规则在没有分类器审查的情况下批准 Monitor 命令。535 狭窄的规则，如 `Bash(npm test)` 保持有效。Claude Code 在您离开自动模式时恢复丢弃的规则。在 v2.1.236 之前，Claude Code 在自动模式中保持 `Monitor` 允许规则有效，因此与整个工具匹配的规则批准 Monitor 命令而不进行分类器审查。

536 536

537 Claude Code 也在会丢弃未提交工作的命令之前运行 `git status`，例如 `git reset --hard` 或 `rm -rf`，并向分类器显示是否存在暂存、修改或未跟踪的工作。即使仓库的 git 配置设置 `status.showUntrackedFiles=no`，Claude Code 也在该检查中报告未跟踪的文件。537 Claude Code 也在会丢弃未提交工作的命令之前运行 `git status`，例如 `git reset --hard` 或 `rm -rf`，并向分类器显示是否存在暂存、修改或未跟踪的工作。Claude Code 在该检查中报告未跟踪的文件，即使仓库的 git 配置设置 `status.showUntrackedFiles=no`。

538 538

539 在 Claude Code 本身发送的分类器请求中，分类器看到用户消息、除只读查找（如文件读取和搜索）之外的工具调用以及您的 CLAUDE.md 内容。工具结果从这些请求中被剥离，因此文件或网页中的恶意内容无法直接操纵分类器。539 在 Claude Code 本身发送的分类器请求中，分类器看到用户消息、除只读查找（如文件读取和搜索）之外的工具调用以及您的 CLAUDE.md 内容。工具结果从这些请求中被剥离，因此文件或网页中的恶意内容无法直接操纵分类器。

540 540

547 分类器在三个点检查[子代理](/docs/zh-CN/sub-agents)工作：547 分类器在三个点检查[子代理](/docs/zh-CN/sub-agents)工作：

548 548

549 1. 在子代理启动之前，委托的任务描述被评估，因此看起来危险的任务在生成时被阻止。549 1. 在子代理启动之前，委托的任务描述被评估，因此看起来危险的任务在生成时被阻止。

550 2. 当子代理运行时，其每个操作都通过分类器，使用与父会话相同的规则，子代理前言中的任何 `permissionMode` 被忽略。550 2. 当子代理运行时，其每个操作都经过与父会话相同的[决策顺序](#how-the-classifier-evaluates-actions)，具有相同的阻止和允许规则。子代理的 frontmatter 中的任何 `permissionMode` 都被忽略。

551 3. 当子代理完成时，分类器审查其工作和最终报告，然后父代读取报告。当分类器标记子代理的工作或报告，或单独的 API 安全检查拒绝审查时，报告仍被传递，前面加上安全警告。当分类器对审查不可用时，报告到达时带有注意在根据它采取行动前验证子代理工作的注意。551 3. 当子代理完成时，分类器审查其工作和最终报告，然后父会话读取报告。当分类器标记子代理的工作或报告，或单独的 API 安全检查拒绝审查时，报告仍被传递，前面带有安全警告。当分类器对审查不可用时，报告到达时带有注意在根据其采取行动之前验证子代理工作的注意。

552 </Accordion>552 </Accordion>

553 553

554 <Accordion title="成本和延迟">554 <Accordion title="成本和延迟">

555 分类器默认在 Claude Sonnet 5 上运行，而不是在您的 `/model` 选择上。Anthropic 配置的服务器端分类器模型优先于该默认值。当您的会话模型是 Claude Sonnet 4.6 时，或当 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 排除 Sonnet 5 时，分类器改为在会话的模型上运行，或在会话在[Fable 模型](/docs/zh-CN/model-config#work-with-fable)上运行时在 Opus 模型上运行；在 Anthropic API 以外的提供商上，该 Opus 回退是提供商的默认 Opus 模型。555 分类器默认在 Claude Sonnet 5 上运行，而不是在您的 `/model` 选择上。Anthropic 配置的服务器端分类器模型优先于该默认值。当您的会话模型是 Claude Sonnet 4.6 或当 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 排除 Sonnet 5 时，分类器改为在会话的模型上运行，或在会话在[Fable 模型](/docs/zh-CN/model-config#work-with-fable)上运行时在 Opus 模型上运行；在 Anthropic API 以外的提供商上，该 Opus 回退是提供商的默认 Opus 模型。

556 556

557 会话的第一个自动模式请求验证 Sonnet 5 默认值：如果请求成功，Sonnet 5 保持会话的分类器模型，如果它失败是因为模型不可用，会话改为使用回退。在该验证解决后，分类器的模型对会话不改变。557 会话的第一个自动模式请求验证 Sonnet 5 默认值：如果请求成功，Sonnet 5 保持会话的分类器模型，如果它因模型不可用而失败，会话改为使用回退。

558 558

559 在 Enterprise 计划和使用 Claude API 的账户、[AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws)、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上，分类器调用计入您的令牌使用。每次检查发送记录的一部分加上待处理操作，在执行前添加往返。读取和工作目录编辑在受保护路径外跳过分类器，因此开销主要来自 shell 命令和网络操作。服务器审查操作作为会话模型请求的一部分的地方，没有单独的分类器调用计数；请参阅[服务器端分类器审查](#server-side-classifier-review)。559 在 Enterprise 计划和使用 Claude API 的账户、[AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws)、Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry 上，分类器调用计入您的令牌使用。每次检查发送记录的一部分加上待处理操作，在执行前添加往返。读取和工作目录编辑在受保护路径外跳过分类器，因此开销主要来自 shell 命令和网络操作。服务器审查操作作为会话模型请求的一部分的地方，没有单独的分类器调用计数；请参阅[服务器端分类器审查](#server-side-classifier-review)。

560 560

561 沙箱网络访问不添加按连接分类器请求。分类器在一次审查中与命令一起判断[命令命名的主机](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)，Claude Code 检查每个连接对批准列表而不再次调用分类器。561 沙箱网络访问不添加每个连接分类器请求。分类器在一次审查中与命令一起判断[命令命名的主机](/docs/zh-CN/sandboxing#per-command-allowed-domains-in-auto-mode)，Claude Code 根据批准的列表检查每个连接而不再次调用分类器。

562 </Accordion>562 </Accordion>

563</AccordionGroup>563</AccordionGroup>

564 564

permissions.md +14 −3

Details

600 600

601[Claude Code hooks](/docs/zh-CN/hooks-guide) 让您可以注册自定义 shell 命令，在运行时评估权限。当 Claude Code 进行工具调用时，PreToolUse hooks 在权限提示之前运行，适用于除了 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 之外的每个工具。hook 输出可以拒绝工具调用、强制提示或跳过提示以让调用继续。601[Claude Code hooks](/docs/zh-CN/hooks-guide) 让您可以注册自定义 shell 命令，在运行时评估权限。当 Claude Code 进行工具调用时，PreToolUse hooks 在权限提示之前运行，适用于除了 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 之外的每个工具。hook 输出可以拒绝工具调用、强制提示或跳过提示以让调用继续。

602 602

603Hook 决定不会绕过权限规则。Claude Code 评估 deny 和 ask 规则，无论 PreToolUse hook 返回什么：匹配的 deny 规则会阻止调用，匹配的 ask 规则即使在 hook 返回 `"allow"` 或 `"ask"` 时仍然会提示。这保留了[管理权限](#manage-permissions)中描述的 deny 优先级，包括在托管设置中设置的 deny 规则。603PreToolUse hook 决定不会绕过权限规则。Claude Code 评估 deny 和 ask 规则，无论 PreToolUse hook 返回什么：匹配的 deny 规则会阻止调用，匹配的 ask 规则即使在 hook 返回 `"allow"` 或 `"ask"` 时仍然会提示。这保留了[管理权限](#manage-permissions)中描述的 deny 优先级，包括在托管设置中设置的 deny 规则。

604

605该优先级涵盖设置文件中的 hooks 和插件的 `hooks/hooks.json` 中的 hooks。您安装的[模块](/docs/zh-CN/plugins/mods/overview)如果 hooks `tool.check` 会在规则和 `PreToolUse` hooks 已经决定之后回答，其答案可以替代它们的答案：

606

607* **Ask 规则**：模块可以批准 ask 规则会提示的调用

608* **来自 `PreToolUse` hook 的阻止**：模块可以批准调用，除非 hook 在托管设置中

609* **自动模式分类器**：在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中，模块批准的调用运行时无需分类器检查

610* **Deny 规则**：在具有托管设置的机器上，或当您使用团队或企业计划登录时，deny 规则默认优先于模块，您的组织可以更改这一点。在其他任何地方，模块可以批准 deny 规则拒绝的调用。

611

612请参见[决定是否信任模块](/docs/zh-CN/plugins/mods/overview#decide-whether-to-trust-a-mod)，或如果您部署托管设置，请参见[为您的组织管理模块](/docs/zh-CN/plugins/mods/admin#know-what-happens-by-default)。

604 613

605标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具在 hook 返回 `"allow"` 时仍然会提示，连接器工具[您的组织设置为 `ask`](/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的工具在该设置到达 Claude Code 的会话中也是如此。614标记为 [`requiresUserInteraction`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 的 MCP 工具在 hook 返回 `"allow"` 时仍然会提示，连接器工具[您的组织设置为 `ask`](/docs/zh-CN/mcp#organization-controls-on-connector-tools) 的工具在该设置到达 Claude Code 的会话中也是如此。

606 615

718 727

719同样的规则也适用于设置范围：如果用户设置允许某个权限而项目设置拒绝它，deny 规则会阻止它。反之亦然：用户级别的 deny 会阻止项目级别的 allow，因为来自任何范围的 deny 规则在 allow 规则之前被评估。728同样的规则也适用于设置范围：如果用户设置允许某个权限而项目设置拒绝它，deny 规则会阻止它。反之亦然：用户级别的 deny 会阻止项目级别的 allow，因为来自任何范围的 deny 规则在 allow 规则之前被评估。

720 729

730这个优先级是在设置文件和命令行参数之间的。关于 deny 规则是否对你安装的 [mod](/docs/zh-CN/plugins/mods/overview) 有效，请参阅[使用 hooks 扩展权限](#extend-permissions-with-hooks)。

731

721嵌入主机可以通过 SDK `managedSettings` 选项提供额外的托管策略，包括权限允许规则，除非管理员设置了 `allowManaged*Only` 锁；[向 Claude Desktop 会话传递策略](/docs/zh-CN/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions)涵盖了嵌入器策略何时适用。732嵌入主机可以通过 SDK `managedSettings` 选项提供额外的托管策略，包括权限允许规则，除非管理员设置了 `allowManaged*Only` 锁；[向 Claude Desktop 会话传递策略](/docs/zh-CN/claude-apps-gateway#deliver-policy-to-claude-desktop-sessions)涵盖了嵌入器策略何时适用。

722 733

723<h2 id="project-allow-rules-and-workspace-trust">734<h2 id="project-allow-rules-and-workspace-trust">

764| 设置文件中的 [Hooks](/docs/zh-CN/hooks)、[`env`](/docs/zh-CN/settings-reference#env) 块和辅助命令（如 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper)），以及项目技能的 [hooks](/docs/zh-CN/hooks#hooks-in-skills-and-agents) 和 [`allowed-tools`](/docs/zh-CN/skills#pre-approve-tools-for-a-skill) | 已使用 | 已使用。工作区信任在任何会话中都不会限制技能的 `allowed-tools` |775| 设置文件中的 [Hooks](/docs/zh-CN/hooks)、[`env`](/docs/zh-CN/settings-reference#env) 块和辅助命令（如 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper)），以及项目技能的 [hooks](/docs/zh-CN/hooks#hooks-in-skills-and-agents) 和 [`allowed-tools`](/docs/zh-CN/skills#pre-approve-tools-for-a-skill) | 已使用 | 已使用。工作区信任在任何会话中都不会限制技能的 `allowed-tools` |

765| `.claude/settings.json` 中的 `permissions.allow` 规则和 `additionalDirectories` | 在您接受信任对话框之前不使用，对话框再次出现列出它们 | 不使用。Claude Code 向 stderr 打印 [`this workspace has not been trusted`](/docs/zh-CN/errors#workspace-has-not-been-trusted) 警告 |776| `.claude/settings.json` 中的 `permissions.allow` 规则和 `additionalDirectories` | 在您接受信任对话框之前不使用，对话框再次出现列出它们 | 不使用。Claude Code 向 stderr 打印 [`this workspace has not been trusted`](/docs/zh-CN/errors#workspace-has-not-been-trusted) 警告 |

766| 项目[子代理](/docs/zh-CN/sub-agents#hooks-in-subagent-frontmatter)中的 Frontmatter hooks、项目 [`@skills-dir` 插件](/docs/zh-CN/plugins/loading#plugins-shared-through-a-repository) 和来自存储库或 `--add-dir` 目录的 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces) 条目 | 不使用，不提供对话框 | 不使用 |777| 项目[子代理](/docs/zh-CN/sub-agents#hooks-in-subagent-frontmatter)中的 Frontmatter hooks、项目 [`@skills-dir` 插件](/docs/zh-CN/plugins/loading#plugins-shared-through-a-repository) 和来自存储库或 `--add-dir` 目录的 [`extraKnownMarketplaces`](/docs/zh-CN/settings-reference#extraknownmarketplaces) 条目 | 不使用，不提供对话框 | 不使用 |

767| 来自存储库或 `--add-dir` 目录的子代理 frontmatter 中的内联 [`mcpServers`](/docs/zh-CN/sub-agents#scope-mcp-servers-to-a-subagent)。在 v2.1.238 之前，Claude Code 在两种情况下都加载这些服务器 | 不使用，不提供对话框 | 不使用 |778| 来自存储库或 `--add-dir` 目录的子代理 frontmatter 中的内联 [`mcpServers`](/docs/zh-CN/sub-agents#scope-mcp-servers-to-a-subagent) | 不使用，不提供对话框 | 不使用 |

768| `.mcp.json` 中的服务器，包括存储库[在其自己的设置中批准的](/docs/zh-CN/mcp#project-server-approvals-and-workspace-trust)服务器 | Claude Code 在连接它们之前询问您。存储库自己的批准不计数 | 连接而不询问，无论是否批准。SDK 仅在 `settingSources` 包括项目设置时加载它们。同一文件夹中的 `claude mcp list` 仍然将此类服务器报告为待处理 |779| `.mcp.json` 中的服务器，包括存储库[在其自己的设置中批准的](/docs/zh-CN/mcp#project-server-approvals-and-workspace-trust)服务器 | Claude Code 在连接它们之前询问您。存储库自己的批准不计数 | 连接而不询问，无论是否批准。SDK 仅在 `settingSources` 包括项目设置时加载它们。同一文件夹中的 `claude mcp list` 仍然将此类服务器报告为待处理 |

769| `.mcp.json` 中服务器上的 [`headersHelper`](/docs/zh-CN/mcp#trust-a-folder-before-its-headershelper-runs)。在 v2.1.238 之前，Claude Code 在两种情况下都运行辅助程序 | 在您接受信任对话框之前不运行，对话框再次出现命名声明辅助程序的位置。Claude Code 仅使用其静态 `headers` 连接服务器直到那时 | 不运行。Claude Code 仅使用其静态 `headers` 连接服务器，并为每个服务器向 stderr 打印 [`headersHelper not run`](/docs/zh-CN/errors#headershelper-not-run) 行 |780| `.mcp.json` 中服务器上的 [`headersHelper`](/docs/zh-CN/mcp#trust-a-folder-before-its-headershelper-runs) | 在您接受信任对话框之前不运行，对话框再次出现命名声明辅助程序的位置。Claude Code 仅使用其静态 `headers` 连接服务器直到那时 | 不运行。Claude Code 仅使用其静态 `headers` 连接服务器，并为每个服务器向 stderr 打印 [`headersHelper not run`](/docs/zh-CN/errors#headershelper-not-run) 行 |

770 781

771对于需要此确切文件夹被信任的行，手动信任它：在 `~/.claude.json` 中设置 `projects["<path>"].hasTrustDialogAccepted` 为 `true`，其中 `<path>` 是存储库根目录，或存储库外的文件夹本身。Claude Code 在跳过的子代理 hook 或内联 MCP 服务器的调试日志行中打印确切的键，在跳过的允许规则的 stderr 警告中，以及在跳过的辅助程序的 `headersHelper not run` 行中。782对于需要此确切文件夹被信任的行，手动信任它：在 `~/.claude.json` 中设置 `projects["<path>"].hasTrustDialogAccepted` 为 `true`，其中 `<path>` 是存储库根目录，或存储库外的文件夹本身。Claude Code 在跳过的子代理 hook 或内联 MCP 服务器的调试日志行中打印确切的键，在跳过的允许规则的 stderr 警告中，以及在跳过的辅助程序的 `headersHelper not run` 行中。

772 783

plugins/cli-reference.md +36 −2

Details

29每个子命令共享这些退出代码、插件参数和作用域值：29每个子命令共享这些退出代码、插件参数和作用域值：

30 30

31* **退出代码**：成功时为 `0`，失败时为 `1`。`validate` 为意外错误添加退出 `2`，`eval` 添加 [其部分](#plugin-eval) 中列出的代码。31* **退出代码**：成功时为 `0`，失败时为 `1`。`validate` 为意外错误添加退出 `2`，`eval` 添加 [其部分](#plugin-eval) 中列出的代码。

~~32* **插件参数**：`<plugin>` 参数是插件 `name` 或 `name@marketplace`。当两个市场提供相同的名称时，使用限定形式。~~32* **插件参数**：`<plugin>` 参数是插件 `name` 或 `name@marketplace`。当两个市场提供相同的名称时，使用限定形式。`configure` 仅接受限定形式。

33* **作用域**：`--scope` 接受 `user`、`project` 或 `local`，并命名命令写入的设置文件。`update` 也接受 `managed`。33* **作用域**：`--scope` 接受 `user`、`project` 或 `local`，并命名命令写入的设置文件。`update` 也接受 `managed`。

34 34

35<h3 id="plugin-init">35<h3 id="plugin-init">

87| 标志 | 描述 |87| 标志 | 描述 |

88| :- | :- |88| :- | :- |

89| `-s, --scope <scope>` | 安装作用域：`user`、`project` 或 `local`。默认为 `user` |89| `-s, --scope <scope>` | 安装作用域：`user`、`project` 或 `local`。默认为 `user` |

~~90| `--config <key=value>` | 设置插件清单声明的 [`userConfig`](/docs/zh-CN/plugins/manifest-reference) 选项。为每个选项重复该标志。需要 Claude Code v2.1.147 或更高版本 |~~90| `--config <key=value>` | 设置插件清单声明的 [`userConfig`](/docs/zh-CN/plugins/manifest-reference) 选项。为每个选项重复该标志。需要 Claude Code v2.1.147 或更高版本。写作 `<server>.<key>` 的键设置 [捆绑 MCP 服务器](/docs/zh-CN/plugins/components#include-a-packaged-mcpb-server) 在其自己的 `user_config` 中声明的设置，用于在插件内部发送的捆绑文件。`<server>.<key>` 形式需要 Claude Code v2.1.285 或更高版本 |

91| `-y, --yes` | 接受显示的安装命令，无需 `Run this command now?` 提示。在 Claude Code 会话内运行命令时被忽略，例如从 Bash 工具或 hook。需要 Claude Code v2.1.229 或更高版本 |91| `-y, --yes` | 接受显示的安装命令，无需 `Run this command now?` 提示。在 Claude Code 会话内运行命令时被忽略，例如从 Bash 工具或 hook。需要 Claude Code v2.1.229 或更高版本 |

92| `--accept-command <sha256>` | 接受显示的安装命令，其 `sha256` 之前的 [`--json` 运行](#plugin-json-result) 在 `shownCommand` 中报告，代替 `-y`。不能与 `-y` 组合。请参阅 [接受显示的安装命令](#accept-a-displayed-install-command)。需要 Claude Code v2.1.271 或更高版本 |92| `--accept-command <sha256>` | 接受显示的安装命令，其 `sha256` 之前的 [`--json` 运行](#plugin-json-result) 在 `shownCommand` 中报告，代替 `-y`。不能与 `-y` 组合。请参阅 [接受显示的安装命令](#accept-a-displayed-install-command)。需要 Claude Code v2.1.271 或更高版本 |

93| `--json` | 将结果打印为 stdout 最后一行的一个 JSON 对象，而不是人类可读的消息，供脚本使用。请参阅 [JSON 结果格式](#plugin-json-result)。需要 Claude Code v2.1.268 或更高版本 |93| `--json` | 将结果打印为 stdout 最后一行的一个 JSON 对象，而不是人类可读的消息，供脚本使用。请参阅 [JSON 结果格式](#plugin-json-result)。需要 Claude Code v2.1.268 或更高版本 |

297| :- | :- |297| :- | :- |

300| `--data-size [plugin]` | 测量每个已安装插件的 [保存数据目录](#what-an-uninstall-deletes-and-keeps)，或仅命名插件的，给定为 `name@marketplace`。没有 `--json` 时无效。如果名称没有安装记录，命令打印 `--data-size names a plugin that is not installed` 并退出 `1`，而不是打印列表。需要 Claude Code v2.1.285 或更高版本 |

300 301

301Claude Code 按每个插件的加载方式对人类可读的输出进行分组：302Claude Code 按每个插件的加载方式对人类可读的输出进行分组：

302 303

332| `hasUserConfig` | boolean | 当插件加载且其清单声明 [`userConfig` 选项](/docs/zh-CN/plugins/manifest-reference#user-configuration) 时存在且为 `true`。对于加载失败的插件不存在，无论其清单声明什么。保存的值永远不包括。需要 Claude Code v2.1.285 或更高版本 |

333| `projectEnabled` | boolean | 项目的共享 `.claude/settings.json` 是否打开插件。仅市场安装。需要 Claude Code v2.1.285 或更高版本 |

334| `dataDirSize` | object | 使用 `--data-size` 时，插件的 [保存数据目录](#what-an-uninstall-deletes-and-keeps) 的大小为 `bytes` 和 `human`；当目录缺失或为空时不存在。仅市场安装。需要 Claude Code v2.1.285 或更高版本 |

335| `dataDirUnreadable` | boolean | 使用 `--data-size` 时，当保存的数据目录存在但无法测量时为 `true`。仅市场安装。需要 Claude Code v2.1.285 或更高版本 |

331 336

332使用 `--json --available` 时，Claude Code 打印一个对象而不是数组。其 `installed` 字段保存已安装插件对象的数组，其 `available` 字段保存每个未安装的市场插件的一个对象，带有下面的字段。337使用 `--json --available` 时，Claude Code 打印一个对象而不是数组。其 `installed` 字段保存已安装插件对象的数组，其 `available` 字段保存每个未安装的市场插件的一个对象，带有下面的字段。

333 338

371 376

372对于未加载的插件，Claude Code 打印 ``Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.`` 并退出 `1`。377对于未加载的插件，Claude Code 打印 ``Plugin "formatter" not found. Run `claude plugin list` to see installed plugins, or pass --plugin-dir <path> to load one from disk.`` 并退出 `1`。

373 378

379<h3 id="plugin-configure">

380 plugin configure

381</h3>

382

383显示已安装插件的 [`userConfig`](/docs/zh-CN/plugins/manifest-reference#user-configuration) 选项及其设置的选项，或保存在 stdin 上管道传入的值。需要 Claude Code v2.1.285 或更高版本。

384

385```bash theme={null}

386claude plugin configure <plugin>

387```

388

389| 标志 | 描述 |

390| :- | :- |

391| `--values-stdin` | 从 stdin 读取选项值作为单行字符串的 JSON 对象并保存它们。你留出的选项保留其保存的值 |

392| `--json` | 将结果打印为 stdout 上的一个 JSON 对象。不使用 `--values-stdin` 时，对象携带选项的 `schema` 和 `choices`、它们的起始 `inputs` 和 `configured` 和 `unconfigured` 选项名称。使用 `--values-stdin` 时，它携带 `saved` 选项名称和，当它们可以被读回时，`unconfigured` 的名称 |

393

394不使用标志时，命令列出每个选项，最多三个标签：`required` 或 `optional`，然后 `sensitive` 用于清单声明敏感的选项，然后 `set` 或 `not set`。它不打印保存的值。使用 `--json` 时，输出包括不敏感的选项的保存值，永远不包括敏感的文本。

395

396要保存值，将它们写入文件作为将选项键映射到字符串值的 JSON 对象，然后在 stdin 上传递文件。将 `formatter@my-marketplace` 替换为你自己的插件的 id，如 `claude plugin list` 所示。此示例从包含 `{"api_url": "https://example.com"}` 的文件 `values.json` 设置一个名为 `api_url` 的选项：

397

398```bash theme={null}

399claude plugin configure formatter@my-marketplace --values-stdin < values.json

400```

401

402Claude Code 根据选项的声明类型验证每个值并打印 `Configuration saved. Restart Claude Code to apply it.` 如果你传递清单不声明的键，或失败验证的值，命令不保存任何内容，打印 `Failed to save configuration:` 带原因，并退出 `1`。使用 `--json` 时，拒绝的值也打印 stdout 上的对象，其 `refused` 字段携带 `message` 和，当一个选项有问题时，其 `option` 键。

403

404传递插件的完整 `name@marketplace` id，如 `claude plugin list` 所示。`configure` 不接受裸 `name`。当没有加载的插件有该 id 时，命令打印 `No installed plugin has the id "<plugin>".` 并退出 `1`。

405

406对于捆绑 MCP 服务器的设置，请参阅 [`plugin install --config`](#plugin-install) 或 `/plugin` 中的 **Configure** 项。

407

374<h3 id="plugin-prune">408<h3 id="plugin-prune">

375 plugin prune409 plugin prune

376</h3>410</h3>

plugins/components.md +15 −2

Details

791 791

792`hooks/hooks.json` 和 `hooks` 清单键中的 hooks 都会加载。对于每个事件及其有效负载，参见 [Hook 事件](/docs/zh-CN/hooks#hook-events)。792`hooks/hooks.json` 和 `hooks` 清单键中的 hooks 都会加载。对于每个事件及其有效负载，参见 [Hook 事件](/docs/zh-CN/hooks#hook-events)。

793 793

794要将 hooks 写成在 Claude Code 内运行并可以在其界面中绘制的 JavaScript 函数，在同一 `hooks/hooks.json` 中的 `modules` 键下列出一个模块文件。具有一个的插件是 mod。参见 [创建 mod](/docs/zh-CN/plugins/mods/create)。

795

794<h4 id="when-plugin-hooks-fire">796<h4 id="when-plugin-hooks-fire">

795 插件 hooks 何时触发797 插件 hooks 何时触发

796</h4>798</h4>

868 870

869服务器从捆绑清单中的 `name` 获取其名称。871服务器从捆绑清单中的 `name` 获取其名称。

870 872

873捆绑的自己的清单可以在 `user_config` 块中声明服务器需要的用户设置。具有必需设置但没有保存值的捆绑服务器不启动。`/plugin` **Errors** 标签显示 `Bundled MCP server "<name>" was not started: it needs configuration`。

874

875用户可以通过以下两种方式之一提供值：

876

877* **在 `/plugin` 中**：在 **Installed** 标签上选择插件并选择 **Configure**

878* **在安装时，从 shell**：将 [`--config <server>.<key>=<value>`](/docs/zh-CN/plugins/cli-reference#plugin-install) 传递给 `claude plugin install`。需要 Claude Code v2.1.285 或更高版本，仅适用于打包在插件内的捆绑。

879

871对于传输和身份验证，参见 [MCP](/docs/zh-CN/mcp#plugin-provided-mcp-servers)。880对于传输和身份验证，参见 [MCP](/docs/zh-CN/mcp#plugin-provided-mcp-servers)。

872 881

873<h3 id="lsp-servers">882<h3 id="lsp-servers">

1071 配置对话框何时出现1080 配置对话框何时出现

1072</h3>1081</h3>

1073 1082

1074对话框仅在交互式 `/plugin` 界面中出现。当用户执行以下任何操作时，它为任何尚未设置的选项打开：1083对话框是交互式 `/plugin` 界面的一部分。当用户执行以下任何操作时，它为任何尚未设置的选项打开：

1075 1084

1076* 在 `/plugin` 中安装插件1085* 在 `/plugin` 中安装插件

1077* 在会话内运行 `/plugin install <plugin>@<marketplace>`1086* 在会话内运行 `/plugin install <plugin>@<marketplace>`

1079 1088

1080要在任何时间打开相同的对话框，用户运行 `/plugin configure <plugin>@<marketplace>`。1089要在任何时间打开相同的对话框，用户运行 `/plugin configure <plugin>@<marketplace>`。

1081 1090

1082`claude plugin install` shell 命令从不提示 `userConfig` 值。要从 shell 设置值，将每个值作为 `--config KEY=VALUE` 传递。当选项保持未设置时，命令打印一个 `userConfig options not yet set` 行，命名两种设置它们的方式。[`userConfig` 对话框从不出现](/docs/zh-CN/plugins/troubleshooting#the-userconfig-dialog-never-appears)引用该行。1091VS Code 扩展的[管理插件对话框](/docs/zh-CN/vs-code#install-plugins)在安装后作为表单请求未设置的选项，插件行上的齿轮图标再次打开包含每个选项的表单。

1092

1093`claude plugin install` shell 命令从不提示 `userConfig` 值。要从 shell 设置值，在安装时将每个值作为 `--config KEY=VALUE` 传递，或之后将 JSON 对象管道传输到 [`claude plugin configure --values-stdin`](/docs/zh-CN/plugins/cli-reference#plugin-configure)。

1094

1095当选项保持未设置时，`claude plugin install` 打印一个 `userConfig options not yet set` 行。有关该行的确切文本，请参阅[`userConfig` 对话框从不出现](/docs/zh-CN/plugins/troubleshooting#the-userconfig-dialog-never-appears)。

1083 1096

1084对于选项字段、每个值存储的位置、组件如何引用保存的值以及哪些字段拒绝 `${user_config.*}`，请参阅[用户配置](/docs/zh-CN/plugins/manifest-reference#user-configuration)。1097对于选项字段、每个值存储的位置、组件如何引用保存的值以及哪些字段拒绝 `${user_config.*}`，请参阅[用户配置](/docs/zh-CN/plugins/manifest-reference#user-configuration)。

1085 1098

plugins/install.md +10 −4

Details

72 摘要的最后一句告诉您插件在此会话中是否可用：72 摘要的最后一句告诉您插件在此会话中是否可用：

73 73

74 * **Active now**：`Plugin is now active.` 不需要重新加载。74 * **Active now**：`Plugin is now active.` 不需要重新加载。

75 * **Reload needed**：`Run /reload-plugins to activate.` 面板关闭，Claude Code 为您运行该重新加载。如果重新加载会 [invalidate the prompt cache](/docs/zh-CN/prompt-caching#enabling-or-disabling-a-plugin)，它会警告并改为保留插件待处理。运行 `/reload-plugins --force` 以激活它，这会花费一个未缓存的请求。75 * **Active, but a server needs setup**：`Plugin is now active.` 后跟 `Its bundled MCP server needs configuration before it can start`。插件的 [bundled MCP server](/docs/zh-CN/plugins/components#include-a-packaged-mcpb-server) 在您设置其选项之前无法启动。在 `/plugin` 的 **Installed** 选项卡上选择插件，然后选择 **Configure** 以设置服务器的选项。

76 * **Load failed**：`The plugin couldn't be loaded`。在 `/plugin` 中打开 **Errors** 选项卡以了解原因，然后查看 [After install: plugin not working](/docs/zh-CN/plugins/troubleshooting#plugin-installed-but-not-working)。76 * **Reload needed**：`Run /reload-plugins to activate.` 面板关闭，Claude Code 为您运行该重新加载。如果重新加载会 [使提示缓存失效](/docs/zh-CN/prompt-caching#enabling-or-disabling-a-plugin)，它会警告并改为保留插件待处理。运行 `/reload-plugins --force` 以激活它，这会花费一个未缓存的请求。

77 * **Load failed**：`The plugin couldn't be loaded`。在 `/plugin` 中打开 **Errors** 选项卡以了解原因，然后查看 [安装后：插件不工作](/docs/zh-CN/plugins/troubleshooting#plugin-installed-but-not-working)。

77 </Step>78 </Step>

78 79

79 <Step title="确认插件有效">80 <Step title="确认插件有效">

248私有市场是您需要凭证才能克隆的存储库中的市场，在 GitHub 或任何其他 git 主机上。您使用与公共市场相同的 `/plugin marketplace add` 或 `claude plugin marketplace add` 命令添加它。Claude Code 使用已在您的机器上的 git 凭证克隆它，从不提示，因此每种连接方式都有要求：249私有市场是您需要凭证才能克隆的存储库中的市场，在 GitHub 或任何其他 git 主机上。您使用与公共市场相同的 `/plugin marketplace add` 或 `claude plugin marketplace add` 命令添加它。Claude Code 使用已在您的机器上的 git 凭证克隆它，从不提示，因此每种连接方式都有要求：

249 250

250* **HTTPS**：您的 git 凭证助手适用，因此您使用 `gh auth login`、macOS Keychain 或 `git-credential-store` 设置的访问权限有效。交互式提示被抑制，因此您从未认证过的主机失败而不是要求密码。251* **HTTPS**：您的 git 凭证助手适用，因此您使用 `gh auth login`、macOS Keychain 或 `git-credential-store` 设置的访问权限有效。交互式提示被抑制，因此您从未认证过的主机失败而不是要求密码。

251* **SSH**：主机必须已在您的 `known_hosts` 文件中，密钥必须在没有密码短语提示的情况下工作，因为主机指纹和密码短语提示也被抑制。252* **SSH**：主机必须已在您的 `known_hosts` 文件中，密钥必须在没有密码短语提示的情况下工作。如果您的 git 设置在 `GIT_SSH_COMMAND`、`GIT_SSH` 或您的 git 配置的 `core.sshCommand` 中命名 SSH 程序，Claude Code 运行该程序。

252* **GitHub `owner/repo` shorthand**：Claude Code 检查您的 SSH 密钥是否向 `github.com` 认证，如果认证则通过 SSH 克隆，如果不认证则通过 HTTPS 克隆。设置 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-CN/env-vars#variables) 以跳过该检查并始终通过 HTTPS 克隆。253* **GitHub `owner/repo` shorthand**：Claude Code 检查您的 SSH 密钥是否向 `github.com` 认证，如果认证则通过 SSH 克隆，如果不认证则通过 HTTPS 克隆。设置 [`CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`](/docs/zh-CN/env-vars#variables) 以跳过该检查并始终通过 HTTPS 克隆。

253 254

254当您运行 `/plugin install`、`/plugin marketplace update` 和 `claude plugin update` 时，相同的凭证适用。255当您运行 `/plugin install`、`/plugin marketplace update` 和 `claude plugin update` 时，相同的凭证适用。

288 289

289* 输入以按名称或描述过滤。290* 输入以按名称或描述过滤。

290* 按 **Space** 启用或禁用所选插件，按 **f** 将其收藏。291* 按 **Space** 启用或禁用所选插件，按 **f** 将其收藏。

291* 按 **Enter** 打开插件的详细信息。那里的菜单提供 **Disable plugin** 或 **Enable plugin**、**Update now** 和 **Uninstall**。采用设置的插件也提供 **Configure options**。292* 按 **Enter** 打开插件的详细信息。

293

294插件的详细信息菜单提供 **Disable plugin** 或 **Enable plugin**、**Update now** 和 **Uninstall**。采用设置的插件还会显示两个更多项目，一个插件可以同时显示两者：

295

296* **Configure options**：当插件的清单声明 [`userConfig` 选项](/docs/zh-CN/plugins/manifest-reference#user-configuration) 时显示。打开这些选项的对话框

297* **Configure**：当插件包含 [bundled MCP server](/docs/zh-CN/plugins/components#include-a-packaged-mcpb-server) 时显示。设置该服务器自己的 `user_config` 设置

292 298

293该选项卡也可以显示 **Managed** 范围的插件。您的组织通过 [managed settings](/docs/zh-CN/settings#settings-files) 安装了这些，您无法在此处启用、禁用或卸载它们。299该选项卡也可以显示 **Managed** 范围的插件。您的组织通过 [managed settings](/docs/zh-CN/settings#settings-files) 安装了这些，您无法在此处启用、禁用或卸载它们。

294 300

plugins/manifest-reference.md +12 −0

Details

149| `types` | Path | 声明 [mod](/docs/zh-CN/plugins/mods/reference#files) 的 `$.state` 值和 `$` 名词的 `.d.ts` 文件 |

170 171

171Claude Code 在其下命名空间每个组件，因此 plugin `deploy-tools` 中的 agent `reviewer` 显示为 `deploy-tools:reviewer`。172Claude Code 在其下命名空间每个组件，因此 plugin `deploy-tools` 中的 agent `reviewer` 显示为 `deploy-tools:reviewer`。

172 173

174`claude plugin validate` 还检查该名称是否通过作为 Anthropic 自己的 plugin 之一。检查忽略大小写并将任何分隔符的运行视为一个：

175

176| 名称 | 结果 |

177| :- | :- |

178| 以 `claude-`、`anthropic-`、`anthropics-` 或 `cc-plugin-` 开头 | 错误 |

179| 是 `claude`、`anthropic`、`anthropics`、`claude-code` 或 `claude-mods` | 错误 |

180| 将 `official` 放在 `claude` 或 `anthropic` 旁边，例如 `official-claude-tools` | 错误 |

181| 在其他任何地方有 `claude`、`anthropic` 或 `anthropics` 作为整个单词，例如 `mcp-for-claude` | 警告 |

182

183错误读作 `Plugin name "<name>" is reserved: it passes as one of Anthropic's own`，警告读作 `Plugin name "<name>" reads as one of Anthropic's own`。`claude plugin init` 和 `claude plugin tag` 拒绝引发错误的名称。仅这些命令检查名称。Claude Code 仍然安装和加载其名称被拒绝的 plugin。

184

173<h3 id="displayname">185<h3 id="displayname">

174 `displayName`186 `displayName`

175</h3>187</h3>

plugins/marketplace-reference.md +2 −0

Details

484| `Author name cannot be empty` | 错误 | `owner.name` |484| `Author name cannot be empty` | 错误 | `owner.name` |

485| `Plugin name cannot contain spaces. Use kebab-case (e.g., "my-plugin")` | 错误 | `plugins[i].name` |485| `Plugin name cannot contain spaces. Use kebab-case (e.g., "my-plugin")` | 错误 | `plugins[i].name` |

486| `Plugin name cannot contain control or bidirectional-formatting characters` | 错误 | `plugins[i].name` |486| `Plugin name cannot contain control or bidirectional-formatting characters` | 错误 | `plugins[i].name` |

487| `Plugin name "x" is reserved: it passes as one of Anthropic's own` | 错误 | `plugins[i].name`。请参阅 manifest 的 [`name`](/docs/zh-CN/plugins/manifest-reference#name) 以了解保留名称 |

488| `Plugin name "x" reads as one of Anthropic's own` | 警告 | `plugins[i].name` |

487| `Claude Code cannot install plugins from marketplace "x". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change the marketplace's "name".` | 错误 | `name` |489| `Claude Code cannot install plugins from marketplace "x". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change the marketplace's "name".` | 错误 | `name` |

488| `Claude Code cannot install plugin "x". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change this entry's "name".` | 错误 | `plugins[i].name` |490| `Claude Code cannot install plugin "x". Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. Change this entry's "name".` | 错误 | `plugins[i].name` |

489| `Duplicate plugin name "x" found in marketplace` | 错误 | 两个条目共享一个 `name` |491| `Duplicate plugin name "x" found in marketplace` | 错误 | 两个条目共享一个 `name` |

plugins/mods/admin.md +375 −0 created

Details

1> ## Documentation Index

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

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

5# 为您的组织管理 mods

7> 使用托管设置控制 Claude Code mods：停止用户安装的 mods、仅允许您自己的 mods、查看 mod 可以执行的操作，以及使用您自己的 mod 强制执行策略。

9[mod](/docs/zh-CN/plugins/mods/overview) 是在 Claude Code 内运行代码的插件，具有安装它的用户的权限。Mods 不是沙箱化的。通过[托管设置](/docs/zh-CN/managed-settings)，您可以决定 mods 是否在用户的机器上运行、运行哪些 mods 以及运行顺序。您还可以安装自己的 mod，用于监视或拒绝其他 mods 的操作。

11本页面适用于为 Claude Code 部署托管设置的人员，无论是通过文件、MDM 还是从 claude.ai 管理控制台部署。在 Claude Code v2.1.287 及更高版本中，Mods 默认处于启用状态。从与您要执行的操作相匹配的部分开始：

13* **排除用户自己的 mods，有或没有您自己的 mods**：[停止用户安装的 mods 加载](#stop-user-installed-mods-from-loading)

14* **查看当您不做任何更改时用户会获得什么**：[了解默认情况下会发生什么](#know-what-happens-by-default)

15* **保持 mods 开启并设置其他限制**：[选择允许的程度](#choose-how-much-to-allow)

17<Note>

18 这些情况在其他页面上有介绍：

20 * **您之前没有部署过托管设置**：从[部署托管设置](/docs/zh-CN/managed-settings)开始

21 * **您想控制用户可以安装哪些插件**：请参阅[为您的组织管理插件](/docs/zh-CN/plugins/org)

22</Note>

24<h2 id="stop-user-installed-mods-from-loading">

25 停止用户安装的 mods 加载

26</h2>

28要防止用户带来的每个 mod 加载，请在[内置保护](#know-what-happens-by-default)上设置 `allowManagedModsOnly` 选项，这是一个策略 mod，Claude Code 在用户安装的每个 mod 之前加载。该选项位于 `pluginConfigs` 下的托管设置中，由 `cc-plugin-sec-default@builtin` 键入：

30```json managed-settings.json theme={null}

31{

32 "pluginConfigs": {

33 "cc-plugin-sec-default@builtin": {

34 "options": {

35 "allowManagedModsOnly": true

36 }

37 }

38 }

39}

40```

42设置了托管设置中的选项后：

44* **用户带来的任何 mod 都不会加载**：这包括用户安装的插件中的 mod、使用 `--plugin-dir` 加载的 mod 以及[Claude 在会话期间编写的](/docs/zh-CN/plugins/mods/create#ask-claude-for-a-mod) mod

45* **您组织的 mods 仍然加载**：[计为您组织的](#install-your-organizations-mods) mod 不会被检查。所有其他 mod 都计为用户的 mod，不会加载。这包括您从 GitHub 或其他远程市场启用的插件中的 mod，以及您的组织为其成员在 claude.ai 上启用的 mod。如果没有计为您的 mod，则不会加载任何已安装的 mod。

46* **用户无法撤销它**：保护程序仅从托管设置读取选项，因此用户、项目或本地设置文件中的相同条目，或使用 `--settings` 传递的文件中的条目不会改变任何内容

47* **文件或 MDM 策略涵盖每个提供商**：当您以文件形式或通过 MDM 提供选项时，它在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的工作方式相同。对于从 claude.ai 管理控制台的交付，请参阅[平台可用性](/docs/zh-CN/server-managed-settings#platform-availability)

48* **用户的其他自定义保持工作**：他们[设置文件中的 hooks](/docs/zh-CN/hooks)、状态行和 `/goal` 不受影响

49* **内置 mods 继续运行**：内置于 Claude Code 的 mods，例如 `AGENTS.md` 支持，各有[自己的开关](/docs/zh-CN/plugins/mods/overview#mods-built-into-claude-code)

51要确认用户机器上的选项，请使用 `--plugin-dir` 和包含 mod 的目录路径（例如 `claude --plugin-dir ./first-mod`）启动该机器上的 Claude Code。mod 的 hooks 不会运行，成绩单和调试日志会显示[保护程序的消息](/docs/zh-CN/plugins/mods/troubleshoot#messages-from-the-built-in-guard)，其中命名了 mod 和 `allowManagedModsOnly`。如果 mod 加载，请参阅[检查策略是否生效](/docs/zh-CN/managed-settings#check-that-a-policy-is-in-force)和[决定选项是否生效的规则](#set-options-on-the-built-in-guard)。

53如果您在早期访问期间将 `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` 设置为 `0`，请将其替换为此选项。Claude Code v2.1.287 及更高版本在任何值下都会忽略该变量，因此那里的 `0` 会使 mods 保持开启。

55<h2 id="know-what-happens-by-default">

56 了解默认情况下会发生什么

57</h2>

59如果您没有自己的 mod 设置，这就是您的用户会获得的：

61* **Mods 处于开启状态。** 用户可以安装包含来自您的插件设置允许的任何市场的 mod 的插件，或使用 `--plugin-dir` 从目录加载一个。

62* **内置保护程序首先运行。** Claude Code 在用户安装的每个 mod 之前加载一个名为 `sec-default@builtin` 的内置 mod。用户无法将其关闭。`/plugin` 和调试日志将其列为 `cc-plugin-sec-default`。保护程序在以下任一情况为真时加载：

64 * 机器有托管设置

65 * 用户使用 Team 或 Enterprise 计划登录到 Claude Code

67 使用 API 密钥进行身份验证的用户，或通过 Amazon Bedrock、Google Cloud 的 Agent Platform 或 Microsoft Foundry，仅在具有托管设置的机器上获得保护程序。

68* **保护程序保护您管理的内容。** 用户的 mod 无法更改您的托管 hooks 接收或决定的内容、系统提示、您的托管 `CLAUDE.md` 和其他托管说明、任何 mod 读取的设置内容，或您的托管 MCP 服务器的工具和描述。

69* **允许所有其他内容。** 保护程序不添加其他限制。用户的 mod 仍然可以读写文件、启动进程、发出网络请求、重写工具调用和提示、拒绝工具调用、批准否则会提示的工具调用，以及在界面中绘制，所有这些都具有该用户的权限。

70* **拒绝规则和您的托管 hooks 优先。** 保护程序加载的地方，用户的 mod 无法批准 `deny` 规则拒绝的调用，无论哪个设置文件持有该规则。来自托管设置中 `PreToolUse` hook 的块也是最终的。两者都适用于 Claude 的工具调用。两者都不适用于 mod 自己的 [`$.fs` 和 `$.process` 调用](/docs/zh-CN/plugins/mods/api#reach-files-processes-and-the-network)：即使 `Read(.env)` 被拒绝，mod 仍然可以使用 `$.fs.read` 读取该文件或启动执行此操作的程序。要限制这些调用，请防止 mod 加载或在[策略 mod](#enforce-a-policy-with-a-mod-of-your-own) 中挂接调用。

71* **其他权限检查可以被覆盖。** 批准工具调用的用户 mod 可以批准 `ask` 规则会提示的调用，或 `PreToolUse` hook 在托管设置外阻止的调用。在自动模式下，mod 批准的调用运行时不进行分类器检查。

73保护程序的源代码在 [Claude Code 存储库的 `mods/sec-default` 目录](https://github.com/anthropics/claude-code/tree/main/mods/sec-default)中是公开的。

75<h3 id="know-which-controls-still-apply">

76 了解哪些控制仍然适用

77</h3>

79Mods 不会替换您已有的控制：

81* **设置 hooks 继续工作。** 设置文件和插件的 `hooks/hooks.json` 中的命令、HTTP、提示和代理 hooks 照常运行，与 mods 一起。关于它们的任何内容都没有被弃用。

82* **拒绝规则在保护程序加载的地方优先。** 用户的 mod 无法批准 `deny` 规则拒绝的调用，除非您设置 [`allowModsToOverrideDenyRules`](#set-options-on-the-built-in-guard)。

83* **托管 hooks 首先运行。** 托管设置中的 `PreToolUse` hook 在任何 mod 看到工具调用之前运行，其块是最终的。如果 mod 随后重写调用，您的托管 hooks 在重写的调用上再次运行，因此块仍然适用。来自其他设置文件和插件的 `PreToolUse` hooks 在最后一个 mod 之后运行，因此返回自己结果代替运行工具的 mod 会阻止这些运行。请参阅[mods 运行的顺序](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in)。

84* **网络策略涵盖 `$.http.fetch`。** 如果您的组织关闭了网络获取，或为会话关闭了非必要的网络流量，Claude Code 会拒绝 mod 使用 `$.http.fetch` 发出的网络请求。该策略不涵盖 mod 使用 `$.process.run` 启动的程序。该程序使用用户自己的访问权限到达网络。

85* **插件控制涵盖 mods。** Mod 是一个插件，因此[限制用户可以安装的内容的设置](/docs/zh-CN/plugins/org#restrict-what-users-can-install)，例如 `strictKnownMarketplaces`，决定它是否可以被安装。

86* **Mods 无法更改权限提示。** Mod 可以重新设置 Claude Code 界面的大部分样式，但不能更改权限提示，因此它无法更改提示显示的内容。Mod 仍然可以在提示出现之前批准或拒绝工具调用，如[了解默认情况下会发生什么](#know-what-happens-by-default)所述。

87* **信任提示首先出现。** 在用户尚未信任的目录中的交互式会话中，在他们回答信任提示之前，没有 mod 加载。

88* **`--safe-mode` 关闭已安装的 mods，包括您的。** 使用 `claude --safe-mode` 启动会话以检查 mod 是否导致了问题。

90这些控制中的任何一个都不会沙箱化 mod。您允许的 mod 以用户身份运行，具有用户对文件、进程和网络的访问权限。

92<h2 id="decide-whether-to-leave-mods-on">

93 决定是否保持 mods 开启

94</h2>

96Mod 可以做的比插件的其他部分更多，因为它在 Claude Code 内运行。它看到每个提示和工具调用，可以更改它们，并可以在权限提示出现之前允许或拒绝工具调用。

98用户可以加载什么作为 mod 取决于您已有的插件控制：

100| 您今天的插件控制 | 用户可以加载什么作为 mod |

101| :- | :- |

102| 无 | 来自任何市场的 mod、来自任何带有 `--plugin-dir` 的目录的 mod，或 Claude 在会话期间编写的 mod |

103| 市场允许列表 | 来自您允许的市场的 mod，或来自任何带有 `--plugin-dir` 的目录的 mod。Claude 在会话期间编写的 mod 仅在允许列表[包含 `skills-dir`](/docs/zh-CN/plugins/org#keep-skills-directory-plugins-loading) 时加载。 |

104| 市场允许列表和 `disableSideloadFlags` | 来自您允许的市场的 mod |

105

106[为您的组织管理插件](/docs/zh-CN/plugins/org)列出了插件加载的每种方式以及控制每种方式的设置。

107

108要在用户安装市场中的 mods 之前检查它们，请参阅[查看 mod 可以执行的操作](#review-what-a-mod-can-do)。要在您完成此操作之前排除用户的 mods，请参阅[停止用户安装的 mods 加载](#stop-user-installed-mods-from-loading)。

109

110<h3 id="review-what-a-mod-can-do">

111 查看 mod 可以执行的操作

112</h3>

113

114您可以看到 mod 能够做什么而无需运行它。在您的 shell 中，在插件的目录上运行 `claude plugin validate`：

115

116```bash theme={null}

117claude plugin validate ./some-mod

118```

119

120输出中的两行描述了 mod 的代码：

121

122```text theme={null}

123 ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}

124 ❯ ./register.js calls: $.fs.read, $.http.fetch, $.store.set, $.ui.open

125```

126

127`hooks:` 行列出了 mod 接收的事件。`calls:` 行列出了其代码调用的 mods API 方法。[mods API](/docs/zh-CN/plugins/mods/api)（在 mod 的代码中写作 `$`）是 mod 到达文件、进程和网络的方式。Claude Code 拒绝加载以此命令无法读取的方式使用 mods API 的 mod。

128

129查看 `calls:` 行以获取这些：

130

131| 调用 | 它的含义 |

132| :- | :- |

133| `$.fs.read`, `$.fs.write` | 读取或写入用户可以访问的任何地方的文件 |

134| `$.process.run`, `$.process.spawn` | 以用户身份启动程序 |

135| `$.http.fetch` | 发出网络请求 |

136| `$.env.get`, `$.settings.read` | 读取环境变量和设置，可以保存 API 密钥。输出中的 `env reads:` 行命名每个变量。 |

137| `$.env.set` | 为 Claude Code 以及它启动的每个命令和 MCP 服务器设置环境变量，可以改变这些程序运行的内容。`env writes:` 行命名每个变量。 |

138| `$.mcp.call` | 在连接的 MCP 服务器上调用工具，在会话的权限规则下 |

139| `$.model.complete` | 使用用户的计划或 API 密钥进行模型调用 |

140| `$.prompt.submit` | 提交提示，可以将其作为用户自己的话语发送 |

141| `$.session.send` | 发送另一个会话或子代理的 Claude 读取的消息 |

142

143在 `hooks:` 行中，[`tool.call`](/docs/zh-CN/plugins/mods/reference#tools) 和 [`prompt.submit`](/docs/zh-CN/plugins/mods/reference#prompts-and-what-claude-reads) 意味着 mod 看到每个工具调用和每个提示，并可以更改它们。[`session.append`](/docs/zh-CN/plugins/mods/reference#session) 意味着 mod 可以在存储之前重写对话的每一行。[`ui.render{component=AskUserQuestion}`](/docs/zh-CN/plugins/mods/interface#change-what-claude-code-already-draws) 意味着 mod 可以重新绘制 Claude 用来询问用户问题的对话框。`tool.check` 意味着 mod 可以在权限提示出现之前批准或拒绝工具调用。[了解默认情况下会发生什么](#know-what-happens-by-default)列出了您的哪些规则和 hooks 优先于其答案。

144

145<h2 id="choose-how-much-to-allow">

146 选择允许的程度

147</h2>

148

149Mod 策略的范围从根本没有已安装的 mods 到用户选择的任何 mod，以及您自己的 mod 检查其他 mods，每一个都是几个托管设置。在第一列中找到您想要的策略，并设置第二列命名的内容。[部署托管设置](/docs/zh-CN/managed-settings)涵盖托管设置的位置。

150

151| 您想要什么 | 设置 |

152| :- | :- |

153| 没有已安装的 mods，hooks 保持不变 | 设置 [`allowManagedModsOnly`](#set-options-on-the-built-in-guard) 并且不部署您自己的 mods |

154| 没有已安装的 mods 和根本没有 hooks，包括您的托管 hooks | 将 `disableAllHooks` 设置为 `true` |

155| 仅您组织的 mods | 设置保护程序的 [`allowManagedModsOnly` 选项](#stop-user-installed-mods-from-loading)，并[安装您的 mods](#install-your-organizations-mods) 以便它们计为您的 |

156| 来自您批准的市场的任何 mod | 保持您的[市场限制](/docs/zh-CN/plugins/org#restrict-what-users-can-install)，并将 `disableSideloadFlags` 设置为 `true` |

157| 任何 mod，您自己的 mod 检查其他 mods | [安装您的 mod](#install-your-organizations-mods)，并在 `prependPlugins` 中与 `sec-default@builtin` 一起列出它 |

158

159每个设置的作用：

160

161* **`allowManagedModsOnly`**：内置保护程序上的选项。用户自己的 mods 不加载，他们的设置 hooks、状态行和 `/goal` 继续工作。[停止用户安装的 mods 加载](#stop-user-installed-mods-from-loading)列出了它涵盖的内容。

162* **`allowManagedHooksOnly`**：更广泛的设置。仅[您组织的 mods](#install-your-organizations-mods) 和内置于 Claude Code 的 mods 加载。用户自己安装的 mod 不加载。该设置还阻止用户自己的设置文件中的 hooks。在设置之前，请阅读[`allowManagedHooksOnly` 下运行什么](/docs/zh-CN/settings-reference#what-runs-under-allowmanagedhooksonly)。

163* **`disableAllHooks`**：最广泛的设置。在托管设置中，它停止每个已安装插件中的 mods，包括您的，并关闭设置文件中的每个 hook，因此您的托管设置中的 `PreToolUse` hook 不再阻止任何内容。自定义状态行和 `/goal` 也停止工作。在设置之前，请阅读[`disableAllHooks`](/docs/zh-CN/settings-reference#disableallhooks)。

164* **`disableSideloadFlags`**：在启动时拒绝 `--plugin-dir` 和 `--plugin-url`，因此没有人从目录加载 mod，并防止 Claude 在会话期间编写的 mods 加载。该设置还拒绝 `--agents` 和 `--mcp-config`。在设置之前，请阅读[`disableSideloadFlags`](/docs/zh-CN/settings-reference#disablesideloadflags)。

165

166内置于 Claude Code 的 Mods，例如 `AGENTS.md` 支持，不受这些设置的影响。每个都有[自己的开关](/docs/zh-CN/plugins/mods/overview#mods-built-into-claude-code)。

167

168mod 未加载的用户在其调试日志中找到原因。[拒绝消息](/docs/zh-CN/plugins/mods/troubleshoot#refusal-messages)列出了 `allowManagedHooksOnly` 和 `disableAllHooks` 的行，[来自内置保护程序的消息](/docs/zh-CN/plugins/mods/troubleshoot#messages-from-the-built-in-guard)有 `allowManagedModsOnly` 的行。

169

170<h3 id="set-options-on-the-built-in-guard">

171 在内置保护程序上设置选项

172</h3>

173

174内置保护程序采用两个选项。在托管设置中的 `pluginConfigs` 下设置它们，由 `cc-plugin-sec-default@builtin` 键入，如[停止用户安装的 mods 加载](#stop-user-installed-mods-from-loading)中的示例所示。

175

176该表给出了您的用户在每个选项未设置和设置为 `true` 时获得的内容：

177

178| 选项 | 未设置 | `true` |

179| :- | :- | :- |

180| `allowManagedModsOnly` | 用户自己的 mods 加载 | 仅[您组织的 mods](#install-your-organizations-mods) 和内置于 Claude Code 的 mods 加载。Claude Code 拒绝所有其他 mods，包括用户安装的或使用 `--plugin-dir` 命名的。 |

181| `allowModsToOverrideDenyRules` | 拒绝规则优先于用户的 mods | 批准工具调用的用户 mod 可以批准 `deny` 规则拒绝的调用 |

182

183这些规则决定选项是否生效：

184

185* **id 在这里有一个拼写**：Claude Code 仅在 `cc-plugin-sec-default@builtin` 下读取选项。`prependPlugins` 也接受 `sec-default@builtin`，而 `pluginConfigs` 不接受。

186* **仅托管设置计数**：用户、项目或本地设置文件中的相同条目，或使用 `--settings` 传递的文件中的相同条目既不设置选项也不放松选项

187* **保护程序必须加载**：如果您设置 `prependPlugins`，[在列表中命名保护程序](#install-your-organizations-mods)。保护程序不加载的地方，两个选项都不适用。

188* **保护程序失败关闭**：如果保护程序无法读取托管设置，它会拒绝每个用户的 mod 加载。如果它无法检查用户的 mod 批准的调用的拒绝规则，它会拒绝该调用。

189

190[来自内置保护程序的消息](/docs/zh-CN/plugins/mods/troubleshoot#messages-from-the-built-in-guard)是您的用户在任一选项适用时看到的内容。

191

192<h2 id="run-your-organization’s-own-mods">

193 运行您组织自己的 mods

194</h2>

195

196您可以将自己的 mods 部署给每个用户，选择它们相对于用户 mods 的运行位置，并使用一个来强制执行策略。

197

198<h3 id="install-your-organizations-mods">

199 安装您组织的 mods 并设置顺序

200</h3>

201

202您组织的 mods 在用户 mods 不存在的地方加载，并且可以在用户 mods 之前运行，因此 Claude Code 必须能够判断 mod 是否来自您。只有当以下所有条件都为真时，它才会将 mod 视为您组织的：

203

204* 托管的 `enabledPlugins` 将 mod 的插件设置为 `true`

205* 托管设置通过绝对路径将插件的 [marketplace](/docs/zh-CN/plugins/create-marketplace) 命名为用户机器上的目录。`extraKnownMarketplaces` 条目可以做到这一点，并且也为用户注册 marketplace。

206* marketplace 通过相对路径列出插件，因此 Claude Code [从该目录就地加载它](/docs/zh-CN/plugins/loading#in-place-and-copied-plugins)

207

208为了满足这些条件，让您的设备管理将 marketplace 目录复制到每台机器上的相同路径。使该目录及其上方的每个目录仅可由管理员写入，就像托管设置文件一样。任何可以在那里写入的人都可以重写您的 mod。您从 claude.ai 管理员控制台交付的托管设置可以携带这些密钥，但它们无法将目录放在机器上。

209

210该目录包含 marketplace 的清单和插件：

211

212```text theme={null}

213/opt/acme/claude-plugins/

214├── .claude-plugin/

215│ └── marketplace.json

216└── plugins/

217 └── acme-guard/

218 ├── .claude-plugin/

219 │ └── plugin.json

220 └── hooks/

221 ├── hooks.json

222 └── register.js

223```

224

225清单通过相对于该目录的路径列出插件：

226

227```json /opt/acme/claude-plugins/.claude-plugin/marketplace.json theme={null}

228{

229 "name": "acme-tools",

230 "owner": { "name": "Acme" },

231 "plugins": [

232 { "name": "acme-guard", "source": "./plugins/acme-guard", "description": "Acme policy mod" }

233 ]

234}

235```

236

237Claude Code 复制到其缓存中的插件计为用户的，即使托管的 `enabledPlugins` 启用了它。这涵盖了来自 GitHub、git、URL 或 npm 源的每个插件。其 mod 在用户 mods 中运行，`prependPlugins` 和 `appendPlugins` 跳过它，并且它不在 `allowManagedModsOnly` 或 `allowManagedHooksOnly` 下加载。用户的调试日志有一行以插件的 id 和 `is enabled by managed settings, but` 开头。

238

239Claude Code 每次即将采取行动（例如运行工具）时都会引发一个事件，并依次将其传递给每个 mod。计为您的 mod [在用户 mods 之前运行](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in)，即使您没有在任何地方列出它。要设置其位置，请在两个设置之一中列出其 id。id 是插件的名称、`@` 和 marketplace 的名称，例如 `acme-guard@acme-tools`。

240

241* **`prependPlugins`**：您的 mod 在任何用户 mod 之前看到每个事件，在之后看到每个结果。它可以更改事件、拒绝事件或跳过用户 mods。

242* **`appendPlugins`**：您的 mod 在每个用户 mod 之后运行，因此它只看到这些 mods 传递的事件，以及它们传递的形式

243

244此示例在 `/opt/acme/claude-plugins` 声明 `acme-tools` marketplace，启用来自它的 `acme-guard`，并首先运行该 mod，内置保护在其后：

245

246```json managed-settings.json theme={null}

247{

248 "extraKnownMarketplaces": {

249 "acme-tools": {

250 "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }

251 }

252 },

253 "enabledPlugins": { "acme-guard@acme-tools": true },

254 "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"]

255}

256```

257

258每个密钥做一项工作：

259

260* **`extraKnownMarketplaces`**：命名保存 `acme-tools` marketplace 的目录。`path` 是包含 `.claude-plugin/marketplace.json` 的目录的绝对路径。

261* **`enabledPlugins`**：为接收这些托管设置的每个用户打开 `acme-guard`

262* **`prependPlugins`**：将 `acme-guard` 放在第一位，内置保护放在第二位，都在用户安装的任何 mod 之前。Claude Code 遵循您列出的顺序。

263

264要确认用户的机器收到了设置，请参阅 [检查策略是否生效](/docs/zh-CN/managed-settings#check-that-a-policy-is-in-force)。

265

266要确认 mod 运行的位置，请在该机器上使用 `claude --debug` 启动会话，并在 [调试日志](/docs/zh-CN/plugins/mods/troubleshoot#read-the-debug-log) 中搜索 mod 的 id：

267

268* **`hooks module acme-guard@acme-tools loaded`，带有 `tier prepend`**：mod 计为您组织的，并首先运行

269* **同一行带有 `tier user`**：Claude Code 将其视为用户的 mod。第二行 `prependPlugins names acme-guard@acme-tools, which is not an enabled managed plugin with a hooks module; skipped` 表示列表跳过了它。

270

271这些规则决定了两个列表中哪些 id 生效：

272

273* **列表替换默认值**：当您在托管设置中设置 `prependPlugins` 时，在其中命名 `sec-default@builtin` 以保留内置保护。保护是内置的，不需要 `enabledPlugins` 条目。

274* **您自己的 id 必须计为您的**：在托管设置中，Claude Code 跳过其插件不满足组织 mod 三个条件的 id

275* **存储库无法设置它们**：Claude Code 从托管设置读取两个设置，从不从存储库的设置文件读取。用户可以在 `~/.claude/settings.json` 中设置它们以仅在没有托管设置的机器上对其自己的 mods 进行排序，并且仅当他们未使用 Team 或 Enterprise 计划登录时。在其他任何地方，Claude Code 忽略用户设置中的两个密钥。那里的列表既不添加也不删除内置保护。

276

277<h3 id="enforce-a-policy-with-a-mod-of-your-own">

278 使用您自己的 mod 强制执行策略

279</h3>

280

281要阻止每个用户的 mod，您不需要自己的 mod。设置 [`allowManagedModsOnly`](#stop-user-installed-mods-from-loading)。当您想允许某些用户的 mods 并拒绝其他的，或记录 mods 的作用时，编写策略 mod。

282

283每次另一个 mod 即将加载时，您的 mod 会收到 `claude plugin validate` 打印的列表，在名为 [`plugin.register`](/docs/zh-CN/plugins/mods/reference#other-mods) 的事件中。`prependPlugins` 中的 mod 可以读取该列表并拒绝该 mod。它也可以 [按名称钩住任何 mods API 调用](/docs/zh-CN/plugins/mods/api#reach-files-processes-and-the-network) 以记录或拒绝每个其他 mod 的该调用。名称是没有 `$.` 的方法，因此 `fs.write` 上的钩子看到每个 `$.fs.write` 调用。

284

285此策略 mod 拒绝任何用户的 mod，其自己的代码调用 `$.process.run` 或 `$.process.spawn`。它也保留审计日志，将每个工具调用和每个 mod 写入的文件写入调试日志。因为它首先运行，日志记录了在任何用户 mod 更改之前请求的内容。将其保存为 `acme-guard/hooks/register.js`：

286

287```javascript acme-guard/hooks/register.js theme={null}

288// 用户 mod 不得调用的方法，每个拼写为 namespace.method

289const BLOCKED_CALLS = ['process.run', 'process.spawn']

290

291export function register(on) {

292 // 每次另一个 mod 即将加载时运行

293 on('plugin.register', async ($, e, next) => {

294 // 保留该 mod 代码中在阻止列表上的调用

295 const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))

296 if (e.tier === 'user' && blocked.length > 0) {

297 // 返回 refuse 阻止 mod 加载，文本是原因

298 return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }

299 }

300 // 让每个其他 mod 加载

301 return next(e)

302 })

303

304 // 记录每个工具调用，然后让它继续不变

305 on('tool.call', async ($, e, next) => {

306 $.ui.log('audit tool.call ' + e.tool, { to: 'debug' })

307 return next(e)

308 })

309

310 // 记录哪个 mod 写了文件，然后是路径，引用因为 mod 选择了它

311 on('fs.write', async ($, e, next) => {

312 $.ui.log('audit fs.write by ' + next.origin.plugin + ' ' + JSON.stringify(e.path), { to: 'debug' })

313 return next(e)

314 })

315}

316```

317

318该文件注册三个钩子：

319

320* **`plugin.register`**：决定另一个 mod 是否加载。它拒绝调用阻止方法的用户 mod，并传递每个其他 mod。

321* **`tool.call`**：为每个工具调用向调试日志写入一行，例如 `audit tool.call Bash`，并且不改变任何内容

322* **`fs.write`**：为每个 `$.fs.write` 调用另一个 mod 进行的写入一行，例如 `audit fs.write by reader "/tmp/notes.md"`，并且不改变任何内容。mod 的名称首先出现，路径被引用，因此 mod 选择的路径无法冒充该行的另一个字段。

323

324`plugin.register` 钩子读取事件的两个字段：

325

326* **`e.tier`**：mod 将运行的位置，`prepend`、`user`、`append` 或 `builtin` 之一。每个人安装的每个 mod 都是 `user`。

327* **`e.uses.calls`**：mod 调用的 mods API 方法，每个拼写为 `namespace.method`，例如 `process.run`，不带 `claude plugin validate` 打印的 `$.`

328

329当用户安装调用 `$.process.run` 的 mod 时，mod 不加载，其调试日志有一行以 `refused by acme-guard:` 和您的原因结尾。拒绝也到达 [热重新加载插件目录的会话](/docs/zh-CN/plugins/mods/troubleshoot#find-out-why-a-mod-does-nothing) 中的记录。要在不拒绝整个 mod 的情况下阻止调用，请从该调用名称上的钩子返回 `{ deny: 'your reason' }`。

330

331要将审计行发送到调试日志以外的地方，请从相同的钩子调用 `$.http.fetch`。

332

333会话可以在没有您的 mod 的情况下运行。如果运行已安装 mods 的工作线程 [崩溃三次](/docs/zh-CN/plugins/mods/troubleshoot#mods-that-run-in-the-hooks-worker-are-off-for-this-session)，Claude Code 卸载每个不是内置的 mod，包括您的，直到用户运行 `/reload-plugins` 或启动新会话。并且使用 `--safe-mode` 启动 Claude Code 的用户运行时没有已安装的 mods，包括您的。

334

335[创建 mod](/docs/zh-CN/plugins/mods/create) 涵盖 mod 需要的文件。[测试判断其他 mods 的 mod](/docs/zh-CN/plugins/mods/test#test-a-mod-that-judges-other-mods) 有此策略 mod 的测试文件。

336

337<h4 id="refuse-mods-when-your-check-fails">

338 当您的检查失败时拒绝 mods

339</h4>

340

341如果您的 `plugin.register` 钩子抛出或超过其时间限制，Claude Code 跳过钩子，因此检查失败打开，它正在检查的 mod 加载。要失败关闭并拒绝用户 mods，将检查移到命名函数中并添加返回拒绝的 `.catch` 处理程序。此版本的文件仅显示 `plugin.register` 钩子，因此在 `register` 中保留第一个版本的两个审计钩子：

342

343```javascript acme-guard/hooks/register.js theme={null}

344const BLOCKED_CALLS = ['process.run', 'process.spawn']

345

346// 与之前相同的检查，移到其自己的函数中

347async function checkMod($, e, next) {

348 const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))

349 if (e.tier === 'user' && blocked.length > 0) {

350 return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }

351 }

352 return next(e)

353}

354

355export function register(on) {

356 // 处理程序仅在 checkMod 抛出或超过其时间限制时运行

357 on('plugin.register', checkMod).catch(async ($, e, next) => {

358 // 让您组织的 mods 和内置 mods 加载

359 if (e.tier !== 'user') return next(e)

360 // 拒绝无法检查的用户 mod

361 return { refuse: 'Acme policy check failed, so this mod was not loaded' }

362 })

363}

364```

365

366处理程序就位后，正在检查时检查抛出或超时的 mod 不加载，拒绝行携带第二个原因，如 `refused by acme-guard: Acme policy check failed, so this mod was not loaded`。处理程序将 `user` 层外的每个 mod 传递给 `next(e)`，因此失败的检查不会停止您组织列出的 mods。[处理失败的钩子](/docs/zh-CN/plugins/mods/events#handle-a-hook-that-fails) 涵盖其他事件的 `.catch`。

367

368<h2 id="next-steps">

369 后续步骤

370</h2>

371

372* [插件安全](/docs/zh-CN/plugins/security)：任何插件可以在用户机器上执行的操作，以及如何在安装前查看一个

373* [Mods 概述](/docs/zh-CN/plugins/mods/overview)：什么是 mod 以及它与 hooks、skills 和 MCP 服务器的比较

374* [mods 运行的顺序](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in)：`prependPlugins` 和 `appendPlugins` 如何与用户的 mods 配合

375* [设置和环境变量](/docs/zh-CN/plugins/mods/reference#settings-and-environment-variables)：本页命名的每个设置在一个表中

plugins/mods/api.md +218 −0 created

Details

1> ## Documentation Index

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

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

5# 使用 mods API

7> 从 Claude Code mod 调用 mods API 来添加命令和工具、调用模型、在计时器上运行工作、向其他会话发送消息，以及访问文件和网络。

9mods API 是 mod 调用以执行操作的方法集：添加命令和工具、调用模型、在事件之间运行工作，以及访问文件系统、进程和网络。每个 hook 都将其作为第一个参数 `$` 接收，方法按命名空间分组，例如 `$.ui` 和 `$.fs`。[事件](/docs/zh-CN/plugins/mods/events)决定何时运行 hook，mods API 是 hook 运行后调用的内容。

11在开始之前，请构建您的[第一个 mod](/docs/zh-CN/plugins/mods/create)。对于每个方法，请参阅 [mods API 方法](/docs/zh-CN/plugins/mods/reference#mods-api-methods)或阅读[您的构建的类型](/docs/zh-CN/plugins/mods/create#get-the-types-for-your-build)。

13<h2 id="add-a-command-or-a-tool">

14 添加命令或工具

15</h2>

17mod 可以添加供用户运行的命令和供 Claude 调用的工具。在 [`session.start`](/docs/zh-CN/plugins/mods/reference#session) hook 中注册两者。Claude Code 在第一个提示之前等待该 hook，因此您注册的内容从第一轮开始就可用。

19<h3 id="add-a-command">

20 添加命令

21</h3>

23命令是供用户使用的。注册它，然后为其名称处理 [`command.run`](/docs/zh-CN/plugins/mods/reference#commands-and-configuration)。此示例添加了一个 `/standup` 命令，该命令接受可选的天数：

25```javascript theme={null}

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

27 // 将 /standup 添加到命令列表，并附上用户在那里看到的描述

28 await $.command.register({ name: 'standup', description: 'Summarize what changed today', argumentHint: '[days]' })

29 return next(e)

30})

32// 匹配器将 hook 限制为 /standup，因此其他命令不会到达它

33on('command.run', { command: 'standup' }, async ($, e) => {

34 // e.args 是在命令名称后键入的文本，或空字符串

35 return { text: 'Summary for the last ' + (e.args || '1') + ' day(s): ...' }

36})

37```

39会话启动后，`/standup` 及其描述会出现在您键入 `/` 时看到的列表中。`argumentHint` 在您键入命令和空格后显示在提示中，如 `/standup [days]`。当您运行 `/standup 3` 时，第二个 hook 返回 `Summary for the last 3 day(s): ...`，并且成绩单在插件名称后显示该文本。hook 永远不会调用 `next`，因为该命令除了您的行为外没有其他行为。

41您返回的 `text` 会打印在成绩单中，Claude 会读取它。要不打印任何内容，如仅打开[窗格](/docs/zh-CN/plugins/mods/interface#pick-where-to-draw)的命令，请返回 `{}`。要让命令在 Claude 工作时运行，请在注册中添加 `immediate: true`。

43选择一个没有内置命令使用的名称。在会话中键入 `/` 以查看它们。`$.command.register` 对于已占用的名称会抛出异常，并显示诸如 `"/focus" refused: it is the built-in /focus"` 的消息。抛出异常的 hook 会被跳过，因此您的 `session.start` hook 的其余部分也不会运行。在该 hook 中最后注册命令，或将调用包装在 `try` 和 `catch` 中。

45<h3 id="add-a-tool">

46 添加工具

47</h3>

49工具是供 Claude 使用的。使用名称、Claude 读取的描述和其输入的 JSON Schema 注册它。Claude 在由 `mcp__`、您的插件名称、两个下划线和您注册的名称组成的较长名称下看到它。您在 [`tool.call`](/docs/zh-CN/plugins/mods/events#guard-or-change-a-tool-call) hook 中处理其调用，该 hook 被过滤到该完整名称。此示例来自名为 `my-mod` 的插件，注册 `ticket`，因此完整名称是 `mcp__my-mod__ticket`。它为 Claude 提供了一个在问题跟踪器中查找工单的工具：

51```javascript theme={null}

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

53 await $.tool.register({

54 name: 'ticket',

55 // Claude 根据此描述决定何时调用该工具

56 description: 'Look up a ticket by its id and return its title and status',

57 // Claude 必须发送的参数：一个名为 id 的必需字符串

58 inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },

59 })

60 return next(e)

61})

63// 完整工具名称是 mcp__、插件名称和注册名称

64on('tool.call', { tool: 'mcp__my-mod__ticket' }, async ($, e) => {

65 // 工具的参数是 e 的字段，因此 id 是 e.id

66 const response = await $.http.fetch('https://tickets.example.com/api/' + encodeURIComponent(e.id))

67 // 无论如何都返回结果，以便 Claude 了解查找何时失败

68 return { result: response.ok ? response.text : 'Lookup failed with status ' + response.status }

69})

70```

72当您询问工单时，Claude 可以使用其 id 调用 `mcp__my-mod__ticket`。第二个 hook 获取工单并返回响应体，Claude 将其作为工具的结果读取。当服务器以错误状态回答时，Claude 读取 `Lookup failed with status` 和数字。

74<h2 id="call-a-model">

75 调用模型

76</h2>

78mod 可以向模型提出自己的问题，在对话之外，用于排序或总结文本等小工作。`$.model.complete` 使用您的会话凭据向模型发送一个提示，并解析为回复。它没有对话历史。

80此 hook 通过要求小型模型标记在其后键入的文本来回答 `/triage` 命令（[注册为命令](#add-a-command)）：

82```javascript theme={null}

83on('command.run', { command: 'triage' }, async ($, e) => {

84 const r = await $.model.complete({

85 model: 'haiku',

86 // 系统提示设置工作，提示携带要标记的文本

87 system: 'Reply with one word: bug, feature, or question.',

88 prompt: e.args,

89 // 一个单词需要很少的令牌，调用在 15 秒后放弃

90 maxTokens: 20,

91 timeoutMs: 15000,

92 })

93 // r.text 仅在模型回答时存在，因此首先检查 r.isAnswered

94 const label = r.isAnswered ? r.text.trim() : 'unknown'

95 return { text: 'Label: ' + label }

96})

97```

99当您运行 `/triage the export button does nothing` 时，mod 将该文本发送到模型并打印其答案，例如 `Label: bug`。Claude 的对话不是请求的一部分。当模型不回答时，标签是 `unknown`。

100

101Claude API 失败不会拒绝调用，因此检查 `r.isAnswered`，当其为 `false` 时读取 `r.reason`。调用仅对 Claude Code 不会发送的请求拒绝，例如您的组织阻止的模型。[您的构建的类型](/docs/zh-CN/plugins/mods/create#get-the-types-for-your-build)列出其他选项，例如 `effort`，[限制](/docs/zh-CN/plugins/mods/reference#limits)给出 `maxTokens` 默认值。

102

103`$.model.fork({ prompt })` 改为在当前对话上提出一个问题，使用相同的模型和系统提示，因此 Claude API 从提示缓存为大部分内容提供服务。

104

105这些调用使用用户的计划或 API 密钥。

106

107<h2 id="run-work-in-the-background">

108 在后台运行工作

109</h2>

110

111超越一个事件的工作，例如每分钟检查一次，在您从 `session.start` 启动的计时器上运行。hook 本身为一个事件运行，其自身运行时间限制为 10 秒。在 `next` 或 mods API 调用上花费的时间不计算，除了 `$.clock.sleep`。`$.clock.every` 和 `$.clock.after` 代替 `setInterval` 和 `setTimeout`，延迟以毫秒为单位：`$.clock.after(5000, fn)` 在五秒后调用 `fn` 一次。每个都返回一个带有 `cancel()` 方法的计时器，`await $.clock.now()` 给出以毫秒为单位的时间。

112

113此 hook 每分钟查找一次拉取请求的检查，并在提示下显示结果。`summarize` 是您自己的函数，将命令的 JSON 输出转换为几个单词：

114

115```javascript theme={null}

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

117 // 每 60,000 毫秒调用一次函数，从现在开始一分钟后

118 $.clock.every(60_000, async () => {

119 const status = await $.process.run(['gh', 'pr', 'checks', '--json', 'state'])

120 // 用最新摘要替换提示下的行

121 $.ui.status('checks: ' + summarize(status.stdout))

122 })

123 // 返回而不等待计时器，以便会话立即启动

124 return next(e)

125})

126```

127

128会话照常启动。一分钟后，提示下会出现一行，带有 `⚠`、mod 的名称，然后是 `checks:` 和您的摘要。之后每分钟替换一次。计时器的回调在任何事件之外运行，因此它在轮次之间保持运行，不会启动一个。如果回调抛出异常，错误会进入[调试日志](/docs/zh-CN/plugins/mods/troubleshoot#read-the-debug-log)，计时器在下一个间隔再次运行。

129

130<h3 id="show-something-without-starting-a-turn">

131 显示内容而不启动轮次

132</h3>

133

134后台工作可以显示用户内容而不启动轮次。这些调用中的每一个都将文本放在不同的位置：

135

136| 调用 | 用户看到的内容 |

137| :- | :- |

138| `$.ui.status(text)` | 提示下的一行，保持不变直到您更改它。它以 `⚠` 和 mod 的名称开头，如 `⚠ my-mod: checks: 3 passing`。 |

139| `$.ui.toast(text)` | 右上角的一个小框，mod 的名称在文本上方，几秒后消失 |

140| `$.ui.log(text)` | 成绩单中的一条暗线，Claude 不读取。它以 `●` 和 mod 的名称开头，如 `● my-mod: build finished`。 |

141

142<h3 id="start-a-turn-from-a-background-job">

143 从后台工作启动轮次

144</h3>

145

146当后台工作发现需要 Claude 注意的内容时，它可以通过使用 `$.prompt.submit({ text })` 提交提示来启动轮次。Claude 在命名您的 mod 为发送者的句子后读取文本。要将其作为用户自己的话发送，不带该句子，请添加 `asUser: true`。调用等待直到会话空闲，然后启动新轮次。它在该轮次启动时解析，因此不要在 Claude 工作时运行的处理程序中 `await` 它。

147

148<h3 id="stop-background-work">

149 停止后台工作

150</h3>

151

152后台工作以两种方式停止。当模块重新加载时，计时器停止。对于 hook 内的长时间运行工作，[`next.signal`](/docs/zh-CN/plugins/mods/reference#the-hook-function) 是一个 `AbortSignal`，当您的 hook 处理的事件被放弃时中止，例如当用户中断时，因此将其传递给任何长时间运行的内容。

153

154<h2 id="send-and-receive-messages-between-sessions">

155 在会话之间发送和接收消息

156</h2>

157

158mod 可以向您的另一个会话或此会话的子代理之一发送纯文本消息，并观察到达和离开的消息。`$.session.send({ to, text })` 发送一个，与 SendMessage 工具进行相同的传递。`to` 是 `{ sessionId }` 用于会话，`{ agentId }` 用于来自 `$.agent.list()` 的子代理，或接收消息来自的字符串地址。调用在消息排队后解析，带有 `{ isDelivered: true }`。当没有传递任何内容时，它使用 `{ isDelivered: false, reason }` 解析，`reason` 说明原因。

159

160此 hook 通过要求您在其后键入的 id 的会话获取状态来回答 `/ping` 命令（[注册为命令](#add-a-command)）：

161

162```javascript theme={null}

163on('command.run', { command: 'ping' }, async ($, e) => {

164 // e.args 是在 /ping 后键入的会话 id

165 const sent = await $.session.send({ to: { sessionId: e.args }, text: 'Status? One line.' })

166 // 调用无论如何都解析，因此检查 isDelivered 以了解发生了什么

167 if (!sent.isDelivered) $.ui.toast('Not delivered: ' + sent.reason)

168 // 空结果在此会话的成绩单中不打印任何内容

169 return {}

170})

171```

172

173当消息排队时，您的会话中不会出现任何内容，其他会话的 Claude 读取 `Status? One line.`。当没有传递任何内容时，右上角的小框给出原因并在几秒后消失。

174

175两个事件让 mod 观察消息。从两者都返回 `next(e)` 以不变地传递每条消息：

176

177| 事件 | 何时触发 | 有用的字段 |

178| :- | :- | :- |

179| `session.receive` | 消息到达此会话，在 Claude 读取之前 | `e.text` 和 `e.origin.kind`，例如 `peer` 或 `peer-send-message` 用于另一个会话或代理，`task-notification` 或 `scheduled-trigger`。返回 `{ consumed: reason }` 以防止 Claude 读取。 |

180| `session.send` | 消息即将离开，来自 SendMessage 工具或 mod | `e.to`、`e.text` 和 `e.origin.kind`，即 `model` 或 `plugin` |

181

182设置为[拒绝入站消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)的会话在 `session.receive` 触发之前拒绝消息，因此 hook 永远看不到它。为您的批准而保留的消息首先到达 hook，因此 mod 可以读取您尚未批准的消息。hook 的 `next(e)` 在消息未传递时拒绝。

183

184接收消息上的发送者名称是发送者写的任何内容，因此不要基于它做出决定。

185

186<h2 id="reach-files-processes-and-the-network">

187 访问文件、进程和网络

188</h2>

189

190mod 通过 mods API 访问文件系统、进程和网络，具有与运行 Claude Code 的用户相同的权限。hooks 模块本身没有 Node.js API、没有计时器全局变量（如 `setTimeout`），也没有自己的网络或文件访问。标准 JavaScript 和 Web API（如 `URL`、`TextEncoder`、`AbortController` 和 `crypto.subtle`）可用。下面的每个命名空间涵盖一种访问：

191

192| 命名空间 | 它做什么 |

193| :- | :- |

194| `$.fs` | `read(path)`、`write(path, text)`、`exists(path)`、`stat(path)` 和 `list(path)` 作用于文件和目录 |

195| `$.process` | `run(['git', 'status'])` 启动命令并在其退出时解析。`spawn` 流式传输长时间运行命令的输出。 |

196| `$.http` | `fetch(url, init)` 通过 `http` 或 `https`。它在读取体后解析为 `{ status, ok, headers, text }`。 |

197| `$.store` | 您的插件自己的 JSON 键值存储，在会话之间保留 |

198| `$.env` | `get` 和 `set` 环境变量。将名称写为文字字符串。 |

199| `$.settings` | `read` 设置文件和托管策略持有的内容 |

200| `$.session` | `messages()` 将成绩单作为 `{ role, text, toolUses }` 列表返回。还有工作目录、模型等。[`usage()`](/docs/zh-CN/plugins/mods/reference#mods-api-methods) 返回上下文窗口使用和计划限制。 |

201| `$.mcp` | `call` 连接的 MCP 服务器上的工具 |

202

203文件和进程有一些自己的规则：

204

205* **路径**：相对路径在会话的工作目录下

206* **`$.fs.list`**：将一个目录的条目作为 `{ name, kind, size, isLink }` 返回，不下降到子目录

207* **`$.process.run`**：接受参数列表，不使用 shell。它解析为 `{ exitCode, stdout, stderr }`，无论退出代码如何。如果程序无法启动或在超时时仍在运行，它会拒绝，默认为 30 秒，因此将其包装在 `try` 和 `catch` 中。

208

209这些调用中的每一个本身都是一个事件，以其命名空间和方法命名，不带 `$.`，例如 `fs.read` 用于 `$.fs.read`。[链中较早的](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in) mod 可以观察、重写或拒绝您的调用，这是组织限制 mod 到达的方式。

210

211<h2 id="next-steps">

212 后续步骤

213</h2>

214

215* [对事件做出反应](/docs/zh-CN/plugins/mods/events)：hook 工具调用、提示和轮次

216* [在界面中绘制](/docs/zh-CN/plugins/mods/interface)：在窗格或提示上方显示您的 mod 收集的内容

217* [测试 mod](/docs/zh-CN/plugins/mods/test)：在测试中存根这些调用中的任何一个

218* [Mods 参考](/docs/zh-CN/plugins/mods/reference)：每个事件、每个 mods API 方法和限制

plugins/mods/create.md +395 −0 created

Details

1> ## Documentation Index

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

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

5# 创建一个 mod

7> 让 Claude 从描述中编写一个 Claude Code mod，或者自己编写一个来计算工具调用并添加命令。学习重新加载和验证循环。

9Mod 是一个 Claude Code [插件](/docs/zh-CN/plugins/overview)，具有一个入口文件，称为 hooks 模块：一个 JavaScript 或 TypeScript 文件，其函数在事件发生时由 Claude Code 调用。有两种方式来创建一个：

11* **让 Claude 编写它**：在 Claude Code 会话中[描述你想要的内容](#ask-claude-for-a-mod)

12* **自己编写**：[按照教程](#write-a-mod-yourself)学习 mod 代码的工作原理。你不需要 Node.js、打包工具或构建步骤，因为 Claude Code 直接加载 `.js` 和 `.ts` 文件。

14如果你还没有决定 mod 是否是合适的工具，请先阅读[概述中的比较](/docs/zh-CN/plugins/mods/overview#compare-mods-settings-hooks-skills-and-mcp-servers)。

16<Note>

17 Mod 需要 Claude Code v2.1.287 或更高版本。在你的 shell 中，运行 `claude --version` 来检查。要查看 mod 是否可以为你加载，请参阅[检查 mod 是否可以加载](/docs/zh-CN/plugins/mods/troubleshoot#check-whether-mods-can-load)。

18</Note>

20<h2 id="ask-claude-for-a-mod">

21 让 Claude 为你编写一个 mod

22</h2>

24在交互式 Claude Code 会话中描述你想要的 mod，Claude 会编写它。Claude 使用一个名为 `plugin-authoring` 的内置[技能](/docs/zh-CN/skills)，它告诉 Claude 在哪里编写 mod、你的版本有哪些事件和方法，以及 mod 如何被加载。当你请求一个 mod 时，Claude 可以加载该技能，或者你可以通过在 Claude Code 提示符处运行 `/plugin-authoring` 来自己加载它。

26一旦你批准了 mod，它就会运行，除了在[某些会话中 Claude 编写的 mod 无法加载](#sessions-that-skip-the-approval)的情况。

28<Steps>

29 <Step title="描述 mod">

30 用你自己的话请求 mod，例如 `make a mod that shows the current git branch above the prompt`。Claude 在会话的 mods 文件夹中的自己的目录中编写 mod，该文件夹是 `~/.claude/dev-mods/` 后跟会话的 ID。mod 的完整路径看起来像 `~/.claude/dev-mods/3f2a9c1e-5b7d-4e8a-9c21-6d0f4b8a7e13/git-branch/`。

32 <Note>

33 在 `default` 和 `acceptEdits` [权限模式](/docs/zh-CN/permission-modes#protected-paths)中，Claude Code 在 Claude 创建 mod 的每个文件之前都会询问，因为 `~/.claude` 是一个受保护的路径。在每个文件出现时批准它。

34 </Note>

35 </Step>

37 <Step title="批准 mod">

38 当 Claude 保存第一个文件时，Claude Code 会询问是否为会话启用热重新加载。热重新加载运行此会话中 Claude 编写的 mod，并在每个后续更改它们的转折处选择每个更改。

40 选择以下答案之一：

42 * **为此会话启用**：会话的 mods 文件夹中的 mod 在转折结束时加载，并在每个更改它们的转折结束时重新加载。你的答案在整个会话中持续，包括在你恢复它之后。

43 * **暂时不**：现在什么都不加载。文件保留在 Claude 编写的位置，mod 在该会话下次启动时加载。要防止 mod 加载，请删除其目录。

44 </Step>

46 <Step title="检查 mod 是否已加载">

47 在 Claude Code 提示符处运行 `/plugin`，然后按 Tab 直到选中**已安装**选项卡。它列出了 mod，你可以在那里关闭它。

48 </Step>

50 <Step title="尝试 mod">

51 使用你请求的内容。对于示例提示，当前分支名称出现在提示框上方。如果 mod 没有做你想要的，告诉 Claude 要改变什么。mod 在每个更改其文件的转折结束时重新加载，所以你可以在 Claude 完成后立即尝试更改。

52 </Step>

53</Steps>

55<h3 id="use-the-mod-in-other-sessions">

56 在其他会话中使用 mod

57</h3>

59Claude 编写的 mod 仅在创建它的会话中加载，一旦 Claude Code 的会话比 [`cleanupPeriodDays`](/docs/zh-CN/settings-reference#cleanupperioddays) 更旧，它就会删除该会话的 mods 文件夹。要保留 mod，请将其目录从 mods 文件夹复制到你自己的位置，例如 `~/mods/git-branch`。然后选择如何加载它：

61* **在你启动的会话中**：在你的 shell 中，运行 `claude --plugin-dir ~/mods/git-branch`

62* **对于其他人**：[将其添加到市场](#share-your-mod)，以便他们可以安装它

64<h3 id="sessions-that-skip-the-approval">

65 Claude 编写的 mod 无法加载的会话

66</h3>

68Claude 编写的 mod 仅在你批准它后加载，在允许 mod 运行的受信任工作区中。在这些会话中它不会加载：

70* **没有人在那里批准**：会话无法向你显示提示，如在 `claude -p` 运行或 [`dontAsk` 模式](/docs/zh-CN/permission-modes)中

71* **工作区不受信任**：你还没有接受目录的信任提示

72* **Mod 已停止**：你使用 `--safe-mode` 或 `--bare` 启动，你设置了 `disableAllHooks`，或你的组织的[托管设置阻止了它](/docs/zh-CN/plugins/mods/admin#choose-how-much-to-allow)

74<h2 id="write-a-mod-yourself">

75 自己编写一个 mod

76</h2>

78在本教程中，你构建一个名为 `first-mod` 的 mod，它计算 Claude 进行的工具调用，在 Claude 工作时在微调器旁边显示计数，并添加一个 `/tally` 命令来打印它。然后你读取 Claude Code 在你的 mod 旁边写入的类型声明，并运行 `claude plugin validate`。它们一起向你展示你的版本提供的事件和方法，以及 Claude Code 从你的代码中读取的内容。

80这个录制显示了完成的 mod。微调器计算工具调用，`/tally` 打印计数，对代码的编辑在会话运行时生效：

82<Frame>

83 <video autoPlay muted loop playsInline controls className="w-full dark:hidden" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-first-mod-light.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=eb561134afa90375777408453ba51c77" aria-label="In a Claude Code session, the prompt 'list the files here and read the README' is typed and sent. The spinner reads 'Thinking · tool calls: 1' and the count rises as Claude works. The /tally command prints 'first-mod: Claude has made 3 tool calls since this mod loaded'. A line says first-mod reloaded and lists its four hooks. On the next prompt the spinner reads 'Thinking · tools used: 1'." data-path="images/mods-first-mod-light.mp4" />

85 <video autoPlay muted loop playsInline controls className="w-full hidden dark:block" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-first-mod-dark.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=09779dadc7ef66c2b1e2da0c2e31ac72" aria-label="In a Claude Code session, the prompt 'list the files here and read the README' is typed and sent. The spinner reads 'Thinking · tool calls: 1' and the count rises as Claude works. The /tally command prints 'first-mod: Claude has made 3 tool calls since this mod loaded'. A line says first-mod reloaded and lists its four hooks. On the next prompt the spinner reads 'Thinking · tools used: 1'." data-path="images/mods-first-mod-dark.mp4" />

86</Frame>

88你编写三个文件：

90```text theme={null}

91first-mod/

92├── .claude-plugin/

93│ └── plugin.json

94└── hooks/

95 ├── hooks.json

96 └── register.js

97```

99* **`plugin.json`**：插件的[清单](/docs/zh-CN/plugins/manifest-reference)

100* **`hooks.json`**：[指向你的代码文件](/docs/zh-CN/plugins/mods/reference#files)

101* **`register.js`**：你的代码，称为 hooks 模块

102

103<Steps>

104 <Step title="创建插件目录">

105 创建保存文件的两个目录：

106

107 <Tabs>

108 <Tab title="Bash or Zsh">

109 ```bash theme={null}

110 mkdir -p first-mod/.claude-plugin first-mod/hooks

111 ```

112 </Tab>

113

114 <Tab title="PowerShell">

115 ```powershell theme={null}

116 New-Item -ItemType Directory -Force first-mod\.claude-plugin, first-mod\hooks

117 ```

118 </Tab>

119 </Tabs>

120 </Step>

121

122 <Step title="编写清单">

123 Mod 是一个插件，mod 需要一个[清单](/docs/zh-CN/plugins/manifest-reference)。这个 mod 的清单没有特殊字段。将其保存为 `first-mod/.claude-plugin/plugin.json`：

124

125 ```json first-mod/.claude-plugin/plugin.json theme={null}

126 {

127 "name": "first-mod",

128 "version": "0.1.0",

129 "description": "Counts Claude's tool calls, shows the count beside the spinner, and adds a /tally command",

130 "author": { "name": "Your Name" }

131 }

132 ```

133 </Step>

134

135 <Step title="告诉 Claude Code 你的代码在哪里">

136 当 Claude Code 加载一个插件时，它读取插件的 `hooks/hooks.json`。该文件中的 `modules` 键给出你的代码的路径，拥有它是使插件成为 mod 的原因。列出一个路径，相对于 `hooks.json`。这里它指向 `register.js`，你在下一步中编写。

137

138 将其保存为 `first-mod/hooks/hooks.json`：

139

140 ```json first-mod/hooks/hooks.json theme={null}

141 {

142 "description": "The first-mod hooks module",

143 "modules": ["./register.js"]

144 }

145 ```

146 </Step>

147

148 <Step title="编写代码">

149 这个文件是 mod 的代码，称为 hooks 模块。当 mod 加载时，Claude Code 调用文件导出的 `register` 函数，并传递一个名为 [`on`](/docs/zh-CN/plugins/mods/reference#the-hook-function) 的函数。每次调用 `on` 都会为它命名的事件注册一个事件处理程序，称为 hook。

150

151 将其保存为 `first-mod/hooks/register.js`：

152

153 ```javascript first-mod/hooks/register.js theme={null}

154 // The count, shared by the hooks below

155 let calls = 0

156

157 // Claude Code calls this once when the mod loads

158 export function register(on) {

159 // Runs when the session starts, before your first prompt

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

161 // Add the /tally command

162 await $.command.register({

163 name: 'tally',

164 description: 'Show how many tool calls Claude has made',

165 })

166 // Let the session start as usual

167 return next(e)

168 })

169

170 // Runs each time Claude is about to use a tool

171 on('tool.call', async ($, e, next) => {

172 calls += 1

173 // Ask Claude Code to draw the interface again, so the new count shows

174 $.ui.invalidate('ui.render')

175 // Let the tool run as usual

176 return next(e)

177 })

178

179 // Runs when you type /tally, and only then, because of the matcher

180 on('command.run', { command: 'tally' }, async () => {

181 // The text to print in the transcript

182 return { text: 'Claude has made ' + calls + ' tool calls since this mod loaded' }

183 })

184

185 // Runs each time Claude Code draws the spinner

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

187 // Keep Claude Code's spinner, with the count added after its word

188 return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

189 })

190 }

191 ```

192

193 该文件在 `calls` 中保持计数，并注册四个 hook：

194

195 * **[`session.start`](/docs/zh-CN/plugins/mods/reference#session)** 在会话启动时运行，在你的第一个提示之前，以及每次 mod 重新加载时。它将 `/tally` 命令添加到 Claude Code。

196 * **[`tool.call`](/docs/zh-CN/plugins/mods/reference#tools)** 每次 Claude 即将使用工具时运行。它将 1 添加到 `calls` 并要求 Claude Code 再次绘制界面。

197 * **[`command.run`](/docs/zh-CN/plugins/mods/reference#commands-and-configuration)** 当你键入 `/tally` 时运行。它返回要打印的文本。

198 * **[`ui.render`](/docs/zh-CN/plugins/mods/reference#interface)** 每次 Claude Code 绘制微调器时运行。它在微调器的单词后添加计数。

199

200 [示例 mod 如何工作](#how-the-example-mod-works)解释了每个 hook 采用的三个参数以及每个参数返回的内容。

201 </Step>

202

203 <Step title="加载 mod">

204 使用 `--plugin-dir` 标志启动 Claude Code，它为一个会话加载一个插件目录而不安装它：

205

206 ```bash theme={null}

207 claude --plugin-dir ./first-mod

208 ```

209 </Step>

210

211 <Step title="尝试 mod">

212 要求 Claude 做一些需要几个工具调用的事情，例如 `list the files here and read the README`。当 Claude 工作时，微调器的单词后跟一个上升的计数，如 `Thinking · tool calls: 2…`。当 Claude 完成时，键入 `/tally` 并按 Enter。转录显示 `first-mod: Claude has made 2 tool calls since this mod loaded`，带有你自己的计数。Claude Code 将插件的名称放在命令的文本前面。

213

214 要在非交互模式下检查命令，请运行它：

215

216 ```bash theme={null}

217 claude -p "/tally" --plugin-dir ./first-mod

218 ```

219

220 ```text theme={null}

221 first-mod: Claude has made 0 tool calls since this mod loaded

222 ```

223

224 如果 `/tally` 不在命令列表中，则模块未加载。请参阅[找出为什么 mod 什么都不做](/docs/zh-CN/plugins/mods/troubleshoot#find-out-why-a-mod-does-nothing)。

225 </Step>

226

227 <Step title="在会话运行时更改代码">

228 保持会话打开。在 `register.js` 中，在 `ui.render` hook 中将 `' · tool calls: '` 更改为 `' · tools used: '` 并保存。突出显示的行是更改的行：

229

230 ```javascript first-mod/hooks/register.js {4} theme={null}

231 // Runs each time Claude Code draws the spinner

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

233 // Keep Claude Code's spinner, with the count added after its word

234 return next({ ...e, props: { ...e.props, suffix: ' · tools used: ' + calls + '…' } })

235 })

236 ```

237

238 转录中的一行说 `first-mod` 重新加载并列出其 hook，下一个微调器使用新文本，如 `Thinking · tools used: 1…`。

239 </Step>

240</Steps>

241

242<h3 id="how-the-example-mod-works">

243 示例 mod 如何工作

244</h3>

245

246你传递给 `on` 的每个函数都是一个 hook，它是一个事件处理程序。Claude Code 将相同的三个参数传递给每个 hook：

247

248* **Mods API**，名为 `$`：mod 可以调用的每个方法来到达自身之外，在[命名空间](/docs/zh-CN/plugins/mods/reference#mods-api-methods)中，例如 `$.ui` 和 `$.command`

249* **事件**，名为 `e`：[事件的输入](/docs/zh-CN/plugins/mods/reference#events)作为纯数据，例如工具调用的名称和参数

250* **下一个处理程序**，名为 [`next`](/docs/zh-CN/plugins/mods/events#how-a-hook-handles-an-event)：一个函数，将事件传递给其他 mod，然后传递给 Claude Code 自己的行为，并返回结果

251

252`first-mod` 中的 hook 以 hook 可以处理的三种方式处理它们的事件：

253

254* **观察**：`session.start` hook 注册命令，`tool.call` hook 计算调用并要求重新绘制。两者都返回 `next(e)`，所以会话启动，工具照常运行。

255* **回答**：`command.run` hook 返回自己的结果，从不调用 `next`。`on` 的第二个参数 `{ command: 'tally' }` 是一个过滤器，称为[匹配器](/docs/zh-CN/plugins/mods/events#filter-which-events-a-hook-handles)，所以 hook 仅对 `/tally` 运行。

256* **重写**：`ui.render` hook 使用 `e` 的副本调用 `next`，其 `suffix` 保持计数，所以 Claude Code 绘制其通常的微调器，你的文本在单词后面

257

258Claude Code 监视使用 `--plugin-dir` 加载的目录，并在其中的文件更改时热重新加载 hooks 模块。每次重新加载都会再次运行 `register`，所以 `calls` 回到 `0`，`/tally` 开始重新计数。要在重新加载中保持值，请参阅[保持状态](/docs/zh-CN/plugins/mods/interface#keep-state)。

259

260<h2 id="keep-working-on-a-mod">

261 继续处理 mod

262</h2>

263

264一旦 mod 加载，你可以让 Claude 更改它，根据你的版本的类型定义检查你的代码，列出 Claude Code 在其中找到的事件和调用，并测试它。

265

266<h3 id="change-a-mod-with-claude">

267 使用 Claude 更改 mod

268</h3>

269

270要更改你已有的 mod，使用 `--plugin-dir` 指向 mod 的目录启动会话，以便 Claude 编写的内容在同一会话中加载：

271

272```bash theme={null}

273claude --plugin-dir ./first-mod

274```

275

276然后请求更改，例如 `add a /tally-reset command to this mod that sets the tally back to zero`。Claude 编辑 hooks 模块，运行 `claude plugin validate`，并修复它报告的内容。你使用 `--plugin-dir` 加载的目录是一个[受保护的路径](/docs/zh-CN/permission-modes#protected-paths)，所以在 `default` 和 `acceptEdits` 模式中，你被要求批准 Claude 对 mod 的每个编辑。受保护的路径表给出其他权限模式的结果。

277

278Claude 在其转折期间保存的文件在转折结束时重新加载，所以你可以在 Claude 完成后立即尝试 `/tally-reset`。

279

280<h3 id="get-the-types-for-your-build">

281 获取你的版本的类型定义

282</h3>

283

284每次 Claude Code 从你传递给 `--plugin-dir` 的目录加载或重新加载 mod，或 mod [Claude 为你编写](#ask-claude-for-a-mod)时，它会将 TypeScript 声明文件（以 `.d.ts` 结尾）写入 mod 目录内的 `.claude-plugin/types/`。它们描述你正在运行的 Claude Code 版本中的确切事件、mods API 方法和元素，所以你的编辑器可以自动完成和类型检查你的 hooks。要在线浏览声明，请阅读 Claude Code 仓库中的 [`mods/types/claude-code.d.ts`](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts)，其第一行命名了写入它的版本。该目录包含这些文件：

285

286| 路径 | 它声明的内容 |

287| :- | :- |

288| `claude-code/index.d.ts` | 每个事件及其输入和结果，每个 mods API 命名空间和方法，以及每个表面可以绘制的元素 |

289| `claude-code-tools/index.d.ts` | 内置工具的输入和结果，以便检查 `e.tool === 'Bash'` 缩小 `e` |

290| `claude-code-mcp/index.d.ts` | 上次在 mod 中保存文件时连接的 MCP 工具的输入 |

291| 以插件命名的目录中的 `index.d.ts` | 该插件添加到 mods API 的内容。你的 `plugin.json` 在 `dependencies` 下列出的每个插件都有一个目录。 |

292| `tsconfig.json` | 适合 hooks 模块的编译器选项 |

293

294如果你的 mod 没有自己的 `tsconfig.json`，Claude Code 会在 mod 的根目录添加一个，扩展生成的那个，所以你的编辑器和 `tsc -p ./first-mod` 类型检查 mod 而无需更多设置。

295

296事件和方法可以在版本之间更改，所以当它们不同意时，相信这些文件而不是任何页面，包括这个。

297

298`claude-code/index.d.ts` 是你的构建的最完整的参考，每个 mods API 方法都有注释和示例。要查找某些内容，请在文件中搜索其名称，例如 `'tool.call'`。

299

300<h3 id="check-what-claude-code-reads-from-your-mod">

301 检查 Claude Code 从你的 mod 中读取的内容

302</h3>

303

304要以 Claude Code 看到的方式查看你的 mod，而不运行你的代码或启动会话，请使用 `claude plugin validate`。它检查清单并对 hooks 模块的源运行相同的静态分析，Claude Code 在加载 mod 时运行。在你的 shell 中，在 mod 的目录上运行它：

305

306```bash theme={null}

307claude plugin validate ./first-mod

308```

309

310对于 `first-mod`，输出包括这些行。

311

312```text theme={null}

313 ❯ ./register.js hooks: session.start, tool.call, command.run{command=tally}, ui.render{component=Spinner}

314 ❯ ./register.js calls: $.command.register, $.ui.invalidate

315

316✔ Validation passed

317```

318

319`hooks:` 行列出你的模块 hook 的事件，每个都带有其在大括号中的过滤器。`calls:` 行列出它调用的每个 mods API 方法。读取或设置环境变量的模块也会获得 `env reads:` 和 `env writes:` 行，使用 [`$.state`](/docs/zh-CN/plugins/mods/interface#keep-state) 的模块会获得 `state reads:` 和 `state writes:`。

320

321如果你打算 hook 的事件在第一行中缺失，Claude Code 也不会调用该 hook。通常的原因是事件名称拼写错误，命令报告为错误，例如 `"tool.calls" is not an event`。

322

323遵循这些规则，以便静态分析可以找到每个 hook 和调用：

324

325* 完整拼写每个 mods API 调用：`$`、命名空间，然后是方法，如 `$.store.get('notes')`。你可以将 `$` 传递给在同一文件的顶级声明的函数，对于你的名为 `loadNotes` 的函数，`calls:` 行然后读取 `$.store.get (via loadNotes)`。将 `$` 传递给方法、在 hook 内定义的函数或从另一个文件导入的函数会导致验证失败。[`$.state`](/docs/zh-CN/plugins/mods/interface#keep-state) 使用的 `read` 和 `update` 函数是可以接受它的导入。不要将 `$` 或其命名空间之一分配给变量、解构它或使用计算名称索引它。`const ui = $.ui` 失败，出现 `$.ui is used as a value`。

326* 在每个 `on` 调用中将事件名称写为字符串文字，例如 `'tool.call'`。变量或循环遍历名称列表会失败，出现 `the event name passed to on() is not a string literal`。

327* 在 `register` 内，不要声明第二个名为 `on` 的变量或参数。验证失败，出现 `"on" is declared again (shadowed)`。

328* 仅从插件目录内的文件导入，通过相对路径。唯一允许的裸导入是 `claude-code`，用于类型和一些帮助程序。

329* 在文件顶部使用 `import` 声明，如 `import { name } from './file.js'`。动态 `import()` 失败，出现 `a dynamic import(); a hooks module imports its own files with an import declaration`。

330* 将每个文件写为 ES 模块，使用 `import` 而不是 `require`。[参考](/docs/zh-CN/plugins/mods/reference#files)列出 Claude Code 加载的文件扩展名。

331

332<h3 id="test-the-mod">

333 测试 mod

334</h3>

335

336你可以为 mod 编写自动化测试，并使用 `claude plugin test` 从你的 shell 运行它们，无需会话、登录或网络。测试引发你的 hook 处理的事件，并检查 hook 做了什么。

337

338这个测试引发两个工具调用，运行 `/tally`，并检查回复计算两者。将其保存为 `first-mod/tests/first-mod.test.ts`：

339

340```typescript first-mod/tests/first-mod.test.ts theme={null}

341import { expect, test } from 'claude-code/testing'

342

343test('/tally reports the tool calls the mod has seen', async ($, on) => {

344 // Answer each tool call in Claude Code's place, so no tool runs

345 on('tool.call', () => ({ result: 'ok' }))

346

347 // Raise two tool calls, which the mod's tool.call hook counts

348 await $.tool.call({ tool: 'Bash', command: 'ls' })

349 await $.tool.call({ tool: 'Read', file_path: 'README.md' })

350

351 // Run /tally and check the text its hook returns

352 const answer = await $.command.run({ command: 'tally', args: '' })

353 expect(answer.text).toBe('Claude has made 2 tool calls since this mod loaded')

354})

355```

356

357在你的 shell 中，从 `first-mod` 目录运行测试：

358

359```bash theme={null}

360claude plugin test

361```

362

363输出命名每个测试及其是否通过，时间从运行到运行变化：

364

365```text theme={null}

366tests/first-mod.test.ts:

367(pass) /tally reports the tool calls the mod has seen [22.87ms]

368

369 1 pass

370 0 fail

371Ran 1 test across 1 file. [0.19s]

372```

373

374[测试 mod](/docs/zh-CN/plugins/mods/test)涵盖存根模型调用或存储，以及测试计时器和绘图。

375

376<h2 id="share-your-mod">

377 分享你的 mod

378</h2>

379

380Mod 是一个插件，所以你在清单中对其进行版本控制，人们使用 `/plugin` 命令安装和更新它。要将其提供给其他人，[将其添加到市场](/docs/zh-CN/plugins/publish)。

381

382在你这样做之前，检查插件的 `name`：`claude plugin validate` 失败一个[看起来像 Anthropic 自己的](/docs/zh-CN/plugins/manifest-reference#name)名称，例如以 `claude-` 开头的名称。事件和方法可以在版本之间更改，所以你的 README 是说明你测试的 Claude Code 版本的地方。

383

384继续针对目录使用 `--plugin-dir` 进行开发，而不是针对已安装的副本。Claude Code 按版本缓存已安装的插件，所以你的编辑在你提高版本并再次安装之前不会到达已安装的副本。

385

386<h2 id="next-steps">

387 后续步骤

388</h2>

389

390* [在界面中绘制](/docs/zh-CN/plugins/mods/interface)：打开一个窗格，在提示上方绘制，并添加按钮和文本字段

391* [对事件做出反应](/docs/zh-CN/plugins/mods/events)：hook 工具调用、提示和转折

392* [使用 mods API](/docs/zh-CN/plugins/mods/api)：添加命令和工具、调用模型、在计时器上运行工作

393* [测试 mod](/docs/zh-CN/plugins/mods/test)：存根 Claude Code 会回答的内容，以及测试计时器和绘图

394* [排查 mod 故障](/docs/zh-CN/plugins/mods/troubleshoot)：mod 什么都不做的原因和调试日志

395* [阅读内置 mod 的源代码](/docs/zh-CN/plugins/mods/overview#read-the-source-of-built-in-mods)：完整的插件，每个都有其 hooks 模块和测试

plugins/mods/events.md +336 −0 created

Details

1> ## Documentation Index

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

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

5# 使用 mod 响应事件

7> 从 mod 处理 Claude Code 事件：观察、重写或回答工具调用、提示和轮次，过滤 hook 处理的事件，并为其他 mod 做计划。

9hook 是一个事件处理程序：Claude Code 在命名事件发生时运行的函数。Claude Code 在即将采取行动的每个点触发事件，例如当它运行工具、提交提示、向模型发送请求或启动或结束会话时。你的 hook 在 Claude Code 采取行动之前运行，因此它可以观察事件、重写事件或代替 Claude Code 回答事件。你使用 [`on(eventName, handler)`](/docs/zh-CN/plugins/mods/reference#the-hook-function) 注册 hook。

11在开始之前，请构建你的[第一个 mod](/docs/zh-CN/plugins/mods/create)。对于每个事件及其确切字段，请参阅[参考](/docs/zh-CN/plugins/mods/reference#events)或阅读[你的构建的类型](/docs/zh-CN/plugins/mods/create#get-the-types-for-your-build)。

13<h2 id="how-a-hook-handles-an-event">

14 hook 如何处理事件

15</h2>

17hook 位于事件和 Claude Code 对其采取的行动之间，因此它可以观察事件、重写事件或自己回答事件。它接收三个参数：[mods API](/docs/zh-CN/plugins/mods/api) 作为 `$`、事件作为 `e` 和下一个处理程序作为 `next`。事件的处理程序形成中间件链。`next(e)` 调用下一个处理程序，这是另一个 mod 的 hook 或链末端的 Claude Code 自己的行为，它解析为结果。你的 hook 对 `next` 做什么决定了它做以下三件事中的哪一件。

19<h3 id="observe-an-event">

20 观察事件

21</h3>

23要观察事件而不改变它，请执行你的工作并返回 `next(e)`。此 hook 记录 Claude 即将使用的每个工具：

25```javascript theme={null}

26on('tool.call', async ($, e, next) => {

27 // 在工具运行之前运行

28 $.ui.log('Claude is about to use ' + e.tool)

29 // 原样传递事件

30 return next(e)

31})

32```

34在每个工具运行之前，转录中会出现一条暗线，例如 `● my-mod: Claude is about to use Bash`，其中 `my-mod` 是你的插件的名称。工具的运行方式与没有 mod 时相同。

36要在事件后采取行动，请 `await next(e)`、执行你的工作并返回结果。此 hook 在每个工具运行后记录它：

38```javascript theme={null}

39on('tool.call', async ($, e, next) => {

40 // 让工具运行，并等待其结果

41 const result = await next(e)

42 // 在工具运行后运行

43 $.ui.log(e.tool + ' finished')

44 // 原样返回结果

45 return result

46})

47```

49该行现在出现在每个工具完成后。Claude 读取相同的结果，因为 hook 返回 `next(e)` 解析的内容。

51<h3 id="rewrite-an-event">

52 重写事件

53</h3>

55要更改 Claude Code 作用的内容，例如提示的文本，请使用修改后的事件副本调用 `next`。事件本身是不可变的：它在每个深度都被冻结，分配给字段会抛出错误。此 hook 在发送前修剪每个提示：

57```javascript theme={null}

58on('prompt.submit', async ($, e, next) => {

59 // 传递事件的副本，其文本已更改

60 return next({ ...e, text: e.text.trim() })

61})

62```

64后续处理程序和 Claude Code 接收修剪后的提示，永远看不到原始提示。你也可以更改结果：`await next(e)`，然后返回替换了字段的结果副本。

66<h3 id="answer-an-event">

67 回答事件

68</h3>

70要自己处理事件，请返回结果而不调用 `next`。这会短路链，因此后续 mod 和 Claude Code 自己的行为不会运行。此 hook 拒绝每个 Bash 命令：

72```javascript theme={null}

73on('tool.call', { tool: 'Bash' }, async () => {

74 // 没有调用 next，所以命令永远不会运行

75 return { deny: 'Bash is turned off in this project. Use the file tools.' }

76})

77```

79当 Claude 尝试 Bash 命令时，命令不会运行，Claude 将 `deny` 文本读作工具的结果。每个事件都有自己的结果形状，[事件参考](/docs/zh-CN/plugins/mods/reference#events)列出了这些。

81<h3 id="filter-which-events-a-hook-handles">

82 过滤 hook 处理的事件

83</h3>

85要仅为某些事件运行 hook，请将过滤器作为第二个参数传递给 `on`。Claude Code 将过滤器称为 matcher。它是一个对象，其字段与事件的字段进行比较，只有当每个字段都匹配时，hook 才会运行。字段可以是值、允许值的数组或正则表达式。

87此示例中的每一行都为更窄的工具调用集合注册相同的函数 `hook`：

89```javascript theme={null}

90// 字符串匹配一个值：仅 Bash 调用

91on('tool.call', { tool: 'Bash' }, hook)

92// 数组匹配其中任何值：Edit 调用和 Write 调用

93on('tool.call', { tool: ['Edit', 'Write'] }, hook)

94// 正则表达式按模式匹配：来自一个 MCP 服务器的每个工具

95on('tool.call', { tool: /^mcp__github__/ }, hook)

96```

98`hook` 为 Bash、Edit 或 Write 调用各运行一次，为名称以 `mcp__github__` 开头的工具调用运行一次。对任何其他工具（如 Read）的调用都不匹配这三个中的任何一个，因此 `hook` 不会为它运行。

100事件名称可以是通配符。`'classic.*'` 匹配每个[设置 hook 事件](#hook-the-settings-hook-events)。`'*'` 匹配除[遥测事件](/docs/zh-CN/plugins/mods/reference#telemetry)之外的每个事件，你可以按名称或作为 `'telemetry.*'` 来 hook 这些事件。

101

102为每个 matcher 注册一次事件。如果你为 `session.start` 调用 `on` 两次而没有 matcher，模块将无法加载，错误为 `on("session.start") is registered twice without a matcher`。将你的 mod 在会话启动时执行的所有操作放在一个 hook 中。

103

104<h2 id="hook-what-claude-is-doing">

105 Hook Claude 正在做的事情

106</h2>

107

108Hook 这些事件以查看或更改工具调用、提示或轮次。对于每个事件以及 hook 可以返回的内容，请参阅[事件参考](/docs/zh-CN/plugins/mods/reference#events)。

109

110<h3 id="guard-or-change-a-tool-call">

111 保护或更改工具调用

112</h3>

113

114`tool.call` hook 看到 Claude 即将使用的每个工具，因此它可以拒绝调用、更改其参数或让其通过。`tool.call` 在 Claude Code 即将运行工具时触发，包括子代理进行的调用和对 MCP 工具的调用。`e.tool` 是工具的名称，工具的参数是 `e` 的字段，例如 Bash 的 `e.command`。当你调用 `next(e)` 时，Claude Code 运行权限检查，然后运行工具。

115

116此 hook 拒绝强制推送的 Bash 命令，并告诉 Claude 原因：

117

118```javascript theme={null}

119// matcher 将 hook 限制为 Bash 调用，因此 e.command 是 shell 命令

120on('tool.call', { tool: 'Bash' }, async ($, e, next) => {

121 if (/git push .*--force/.test(e.command)) {

122 // 返回而不调用 next 会回答事件，所以命令永远不会运行

123 return { deny: 'Force pushes are not allowed in this repository. Push to a new branch instead.' }

124 }

125 // 每个其他命令都会进行权限检查，然后进行 Bash

126 return next(e)

127})

128```

129

130当 Claude 尝试 `git push --force` 时，命令不会运行，也不会出现权限提示，因为 hook 永远不会调用 `next`。Claude 将 `deny` 文本读作工具的结果，因此将其写成 Claude 可以采取行动的指令。每个其他 Bash 命令的运行方式与没有 mod 时相同。

131

132要在工具运行后采取行动，请 `await next(e)`、执行你的工作并返回 `next` 给你的内容。此 hook 记录 Claude 更改的每个 `.mdx` 文件，使用 [`$.ui.log`](/docs/zh-CN/plugins/mods/api#show-something-without-starting-a-turn)，它向转录中添加一条暗线，Claude 不会读取：

133

134```javascript theme={null}

135on('tool.call', { tool: ['Edit', 'Write'] }, async ($, e, next) => {

136 // 等待权限检查和工具，并保留它们生成的内容

137 const result = await next(e)

138 // 被拒绝的调用返回为 { deny }，失败的调用设置了 isError

139 const changed = !result.deny && !result.isError

140 if (changed && e.file_path.endsWith('.mdx')) $.ui.log('Claude changed ' + e.file_path)

141 // 原样返回结果，所以 Claude 读取工具返回的内容

142 return result

143})

144```

145

146Claude 编辑或写入 `.mdx` 文件后，转录中的暗线会命名该文件。对于另一种文件或被拒绝或失败的调用，不会记录任何内容。Claude 对调用的看法不会改变，因为 hook 返回它接收的结果。

147

148要更改调用，请将更改的参数传递给 `next`。要重试调用，请再次调用 `next(e)`：看到第一个结果上的 `isError` 的 hook 可以第二次运行工具并返回该结果。要自己回答调用，请返回带有 `result` 字段的对象，例如 `{ result: 'Skipped by my-mod' }`，而不调用 `next`。当你这样做时，不会出现权限提示，工具不会运行，因此你返回的结果是 Claude 了解发生了什么的全部内容。

149

150你的组织的[托管设置](/docs/zh-CN/server-managed-settings)中的 hooks 在任何 mod 的 `tool.call` hook 之前运行，其中一个的块是最终的。

151

152<h4 id="hold-a-tool-call-until-the-user-decides">

153 保持工具调用直到用户决定

154</h4>

155

156hook 可以暂停工具调用并在继续之前询问用户该怎么做。`tool.call` hook 可以在调用 `next` 或返回之前 `await`，工具调用保持待处理状态直到那时。要向用户提出问题，请调用 `$.ui.ask`。它在 Claude 用来问你的对话框中的编号列表上方显示你的问题，并解析为用户选择的标签。在你的选项之后，对话框添加一行用于输入不同的答案和一个**聊天此问题**行。

157

158此示例中的 `RISKY` 模式匹配 `rm -r`、`rm -rf`、`git reset --hard` 和带有 `--force` 的 `git push`，它会错过其他拼写，例如 `git push -f`。此模块在运行与模式匹配的 Bash 命令之前询问：

159

160```javascript theme={null}

161const RISKY = /\brm\s+-rf?\b|\bgit\s+reset\s+--hard\b|\bgit\s+push\b.*--force/

162

163export function register(on) {

164 on('tool.call', { tool: 'Bash' }, async ($, e, next) => {

165 // 让每个其他命令通过而不提问

166 if (!RISKY.test(e.command)) return next(e)

167 // 从安全答案开始，所以没有人回答的问题会拒绝命令

168 let answer = 'Refuse'

169 try {

170 // 工具调用在这里等待，直到用户选择两个标签之一

171 answer = await $.ui.ask('Run this command? ' + e.command, ['Run it', 'Refuse'])

172 } catch {

173 // 用户关闭了问题，或这是一个 claude -p 运行，没有人可以问

174 }

175 if (answer !== 'Run it') {

176 // 回答而不调用 next，所以命令不会运行

177 return { deny: 'The user declined this command. Ask before trying a different approach.' }

178 }

179 return next(e)

180 })

181}

182```

183

184当 Claude 尝试诸如 `rm -rf build` 的命令时，问题会出现，命令会等待答案：

185

186* **用户选择 Run it**：hook 调用 `next(e)`，通常的权限检查仍然在之后运行

187* **用户选择 Refuse**：命令不会运行，Claude 读取 `deny` 文本

188* **用户输入答案**：`$.ui.ask` 解析为输入的文本。hook 将其与 `Run it` 进行比较，因此任何其他文本都会拒绝命令。

189* **没有人回答**：当用户关闭问题或选择**聊天此问题**时，`$.ui.ask` 会拒绝，在 `claude -p` 运行中也是如此，因此 `catch` 块将答案保留在 `Refuse`

190

191将等待保持在 mods API 调用（如 `$.ui.ask`）内，因为该时间不计入 hook 的[10 秒时间限制](/docs/zh-CN/plugins/mods/reference#limits)。花在等待你自己的承诺上的时间确实计入。Claude Code 跳过超时的 hook，因此保持的命令会运行。

192

193<h3 id="rewrite-or-add-to-a-prompt">

194 重写或添加到提示

195</h3>

196

197`prompt.submit` hook 在轮次开始之前看到每个提示，因此它可以重写文本或添加到其中。`e.text` 是输入的内容。

198

199| 要执行此操作 | 返回此内容 |

200| :- | :- |

201| 重写提示。转录中的消息显示新文本。 | `next({ ...e, text: newText })` |

202| 仅添加 Claude 读取的文本，在提示之后 | `next({ ...e, context: [...(e.context ?? []), extraText] })` |

203| 停止发送提示 | `{ drop: 'the reason' }` |

204

205此 hook 在提示提及拉取请求时为 Claude 添加当前分支名称：

206

207```javascript theme={null}

208on('prompt.submit', async ($, e, next) => {

209 // 原样传递不提及拉取请求的提示

210 if (!/\bPR\b|pull request/i.test(e.text)) return next(e)

211 const git = await $.process.run(['git', 'branch', '--show-current'])

212 // 在 git 存储库外，命令失败，因此没有分支可添加

213 if (git.exitCode !== 0) return next(e)

214 // 保留早期 hook 添加的任何上下文，并为 Claude 添加一行

215 return next({ ...e, context: [...(e.context ?? []), 'Current branch: ' + git.stdout.trim()] })

216})

217```

218

219当你发送诸如 `open a PR for this change` 的提示时，你的消息在转录中看起来相同，Claude 也会在其后读取诸如 `Current branch: feature/auth` 的行。不提及拉取请求的提示会原样通过，`git` 不会运行。

220

221[其他事件](/docs/zh-CN/plugins/mods/reference#prompts-and-what-claude-reads)涵盖 Claude 读取的其余内容：`prompt.section` 用于系统提示的每个部分，`prompt.context` 用于与第一条消息一起发送的上下文，`skill.prompt` 用于技能的文本。来自这些 hook 的文本在请求之间更改时会[使提示缓存失效](/docs/zh-CN/prompt-caching)。

222

223<h3 id="follow-a-turn">

224 跟踪轮次

225</h3>

226

227轮次是 Claude 为回答一个提示而做的所有事情。Hook `turn.start`、`turn.step` 和 `turn.complete` 来跟踪一个：

228

229| 事件 | 何时触发 | hook 可以做什么 |

230| :- | :- | :- |

231| `turn.start` | 轮次开始 | 观察。`e.turnId` 在其他两个事件中标识轮次。 |

232| `turn.step` | Claude Code 即将向模型发送一个请求。具有工具调用的轮次有多个。`e.agentId` 为子代理的请求设置。 | 读取每个请求的令牌使用情况，使用 `next({ ...e, model })` 将其发送到不同的模型，或在不调用模型的情况下回答 |

233| `turn.complete` | 轮次结束，包括用户中断的轮次，其中 `e.isAborted` 为 `true`。`e.answer` 是 Claude 的最终文本，`e.durationMs` 是花费的时间，`e.usage` 是轮次的令牌总数。子代理的轮次使用 `e.agentId` 设置触发它。 | 观察，或返回带有 `text` 字段的对象，例如 `{ text: 'Done in 12 seconds' }`，以在答案下显示一行 |

234

235将 `turn.step` hook 写成异步生成器，因为事件流。`yield* next(e)` 在流式传输时转发响应并评估为完成的结果。此 hook 记录每个请求中 Claude API 从[提示缓存](/docs/zh-CN/prompt-caching)提供的数量：

236

237```javascript theme={null}

238// function* 使 hook 成为生成器，可以逐块传递响应

239on('turn.step', async function* ($, e, next) {

240 // 发送请求，在每个片段到达时转发它，并保留完成的结果

241 const result = yield* next(e)

242 // 跳过不报告令牌计数的结果

243 if (result.usage) {

244 $.ui.log('cache read ' + result.usage.cache_read_input_tokens + ' · wrote ' + result.usage.cache_creation_input_tokens)

245 }

246 // 原样返回结果，所以轮次照常继续

247 return result

248})

249```

250

251Claude 的响应流式传输到屏幕，就像没有 mod 时一样。每个请求完成后，转录中的暗线给出从缓存读取的令牌数和写入的令牌数。具有工具调用的轮次有多个请求，因此它添加多行。

252

253`result.usage` 保存 Claude API 为请求报告的四个令牌计数，加上回答的 `model`：`input_tokens`、`output_tokens`、`cache_read_input_tokens` 和 `cache_creation_input_tokens`。hook 也为子代理的请求运行，因此当你只想要主对话时检查 `e.agentId`。

254

255<h3 id="hook-the-settings-hook-events">

256 Hook 设置 hook 事件

257</h3>

258

259设置 hooks 是你在设置文件中配置的命令、HTTP、提示和代理 hooks。每个[设置 hook 事件](/docs/zh-CN/hooks#hook-events)，例如 `Stop`、`SessionEnd` 或 `PostToolUse`，也是一个名为 `classic.` 后跟设置 hook 事件名称的事件，例如 `classic.Stop`。`e` 是设置 hook 在 stdin 上接收的 JSON，包括 `transcript_path`。

260

261此 hook 使用 `Stop`（在 Claude 完成响应时触发）来记录会话的转录保存位置：

262

263```javascript theme={null}

264on('classic.Stop', async ($, e, next) => {

265 // e 具有设置文件中的 Stop hook 从 stdin 读取的相同字段

266 $.ui.log('Transcript saved at ' + e.transcript_path)

267 // 传递事件，所以你的设置文件中的 Stop hooks 仍然运行

268 return next(e)

269})

270```

271

272每次 Claude 完成响应时，转录中的暗线都会给出转录文件的路径。hook 返回 `next(e)`，因此它观察事件并不改变轮次的结束方式。

273

274<h2 id="run-alongside-other-mods">

275 与其他 mod 一起运行

276</h2>

277

278多个 mod 可以 hook 同一事件，其中任何一个都可能失败。如果你的 mod 阻止工具调用，请检查它在链中的位置以及当其 hook 失败时会发生什么。

279

280<h3 id="the-order-mods-run-in">

281 mod 运行的顺序

282</h3>

283

284同一事件上的 hooks 形成一个中间件链。每个 mod 的 `next` 调用以下 mod 的 hook，最后的 `next` 到达 Claude Code 自己的行为。第一个 mod 是最外层的：它在其他 mod 之前看到事件，在它们之后看到结果，并决定其他 mod 是否运行。后续 mod 无法阻止早期 mod 看到事件。

285

286Claude Code 按每个 mod 的来源对链进行排序：

287

2881. 内置保护 `sec-default@builtin`，一个内置于 Claude Code 的 mod，`/plugin` 列为 `cc-plugin-sec-default`，其中[它加载](/docs/zh-CN/plugins/mods/admin#know-what-happens-by-default)，你的组织在 [`prependPlugins`](/docs/zh-CN/plugins/mods/admin#install-your-organizations-mods) 中列出的 mod，然后是任何其他计为你的组织的 mod，不在 `appendPlugins` 中

2892. 你安装的 mod

2903. 你的组织在 `appendPlugins` 中列出的 mod

2914. 其他内置于 Claude Code 的 mod

292

293在你安装的 mod 中，mod 在它在清单中的 `dependencies` 下列出的 mod 之前运行。在一个模块中，hooks 按 `register` 调用 `on` 的顺序运行。

294

295<h4 id="where-settings-hooks-run-in-the-order">

296 设置 hooks 在顺序中运行的位置

297</h4>

298

299在设置文件中配置的 `PreToolUse` hooks 也在工具调用期间运行，在 mod 链中的固定点：

300

301* **来自托管设置的 `PreToolUse` hooks**：在第一个 mod 的 `tool.call` hook 之前运行，其中一个的块是最终的，因此没有 mod 看到调用。

302* **来自每个其他设置文件和插件的 `hooks/hooks.json` 的 `PreToolUse` hooks**：在最后一个 mod 调用 `next` 后运行，作为 Claude Code 自己的行为的一部分。回答 `tool.call` 而不调用 `next` 的 mod 会阻止它们运行，调用 `next` 的 mod 在它返回的结果中看到它们的决定。

303

304[`tool.check`](/docs/zh-CN/plugins/mods/reference#tools) 是 Claude Code 决定是否允许工具调用运行的事件。它在这些 hooks 和权限规则决定后触发，`next(e)` 解析为它们的决定。`tool.check` 上的 hook 可以返回不同的决定，例如 `{ decision: 'allow' }`，因此它可以批准第二组中的 hook 阻止的调用。[使用 hooks 扩展权限](/docs/zh-CN/permissions#extend-permissions-with-hooks)列出哪些决定对 mod 有效。

305

306<h3 id="handle-a-hook-that-fails">

307 处理失败的 hook

308</h3>

309

310失败的 hook 不会破坏会话，你可以决定接下来会发生什么。当没有 `.catch` 处理程序的 hook 抛出、超时或返回错误形状的结果时，接下来会发生什么取决于它是否调用了 `next`：

311

312* **它在调用 `next` 之前失败**：Claude Code 跳过它，下一个处理程序代替运行

313* **它在 `next` 解析后失败**：该结果成立，没有任何东西运行第二次

314

315一行命名 mod、事件和原因，例如 `my-mod: tool.call hook skipped: threw Error: boom`。你读取它的位置取决于会话，如[找出 mod 为什么不做任何事](/docs/zh-CN/plugins/mods/troubleshoot#find-out-why-a-mod-does-nothing)列出的。其绘图不验证的 `ui.render` hook 的报告方式不同，如[从元素构建树](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements)所述。

316

317要使阻止调用的 hook 失败关闭，请添加一个 `.catch` 错误处理程序来代替回答。这里，`guard` 是你的 hook 函数：

318

319```javascript theme={null}

320// on 返回一个注册，.catch 将处理程序附加到该 hook

321on('tool.call', { tool: 'Bash' }, guard).catch(async ($, e, next) => {

322 // next.error.kind 是 'throw' 或 'timeout'，说明 guard 如何失败

323 return { deny: 'The command guard failed, so this command was not run: ' + next.error.kind }

324})

325```

326

327当 `guard` 工作时，处理程序永远不会运行。当 `guard` 在 Bash 调用上抛出或超时时，Claude Code 使用相同的事件调用处理程序。处理程序返回 `{ deny }`，所以命令不会运行，Claude 读取末尾带有 `throw` 或 `timeout` 的文本。没有处理程序，Claude Code 会跳过 `guard` 并运行命令。处理程序有[一秒](/docs/zh-CN/plugins/mods/reference#limits)来回答。

328

329<h2 id="next-steps">

330 后续步骤

331</h2>

332

333* [使用 mods API](/docs/zh-CN/plugins/mods/api)：添加命令和工具、调用模型并在计时器上运行工作

334* [在界面中绘制](/docs/zh-CN/plugins/mods/interface)：在窗格中或提示上方显示你的 hooks 收集的内容

335* [测试 mod](/docs/zh-CN/plugins/mods/test)：从测试中触发这些事件中的任何一个

336* [Mods 参考](/docs/zh-CN/plugins/mods/reference)：每个事件、每个 mods API 方法和限制

plugins/mods/interface.md +867 −0 created

Details

1> ## Documentation Index

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

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

5# 使用 mod 在界面中绘制

7> 从 Claude Code mod 中绘制窗格、提示符上方的条带、按钮和文本字段，处理按键和输入，并在重绘和会话之间保持状态。

9mod 可以在 Claude Code 中绘制自己的界面，并更改 Claude Code 已经绘制的界面部分。mod 可以绘制的每个位置称为[渲染站点](/docs/zh-CN/plugins/mods/reference#render-sites)，例如窗格、提示符上方的条带或加载指示器。Claude Code 在即将绘制渲染站点时会触发 [`ui.render`](/docs/zh-CN/plugins/mods/reference#interface) 事件，你的该事件钩子返回在那里绘制的内容。

11此地图显示 mod 可以在终端会话中的绘制位置：

13<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5fda26b6609c62b68c6f9e528c1590ea" className="dark:hidden" alt="Claude Code 终端会话的地图。mod 可以在右侧添加窗格作为侧边栏，在记录的右上角添加 toast，在记录中添加日志行，在提示符上方添加条带，以及在提示符下方添加状态行。mod 可以重绘消息、工具调用行和加载指示器。提示符是 Claude Code 自己的。" width="600" height="336" data-path="images/mods-screen-map.svg" />

15<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-screen-map-dark.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=5b4161581a1bd2c0450b0c8b57bc1225" className="hidden dark:block" alt="Claude Code 终端会话的地图。mod 可以在右侧添加窗格作为侧边栏，在记录的右上角添加 toast，在记录中添加日志行，在提示符上方添加条带，以及在提示符下方添加状态行。mod 可以重绘消息、工具调用行和加载指示器。提示符是 Claude Code 自己的。" width="600" height="336" data-path="images/mods-screen-map-dark.svg" />

17在较窄的终端中，窗格位于提示符上方而不是记录旁边。

19在开始之前，请构建你的[第一个 mod](/docs/zh-CN/plugins/mods/create)。从工作示例开始，该示例构建一个具有两个选项卡和计数器的窗格，然后阅读你想要更改的每个部分的部分。

21<Note>

22 要查找一个属性或限制，请参阅[参考](/docs/zh-CN/plugins/mods/reference#render-sites)。

23</Note>

25<h2 id="build-a-pane-with-tabs">

26 构建带有选项卡的窗格

27</h2>

29在本部分中，你将构建一个 mod，该 mod 添加 `/hello-tabs` 命令，该命令打开一个窗格。窗格是在宽全屏终端中记录旁边的侧边栏，或在其他情况下是提示符上方的框架区域。此窗格显示两个选项卡，第二个选项卡有一个按钮，可以将计数器加一。重新启动 Claude Code 后，计数仍然存在。

31完成的 mod 看起来像这样。录制打开窗格，切换到第二个选项卡，按几次按钮，然后返回到第一个选项卡：

33<Frame>

34 <video autoPlay muted loop playsInline controls className="w-full dark:hidden" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-hello-tabs-light.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=49d520094d87b5b44bfe50fa49677f06" aria-label="在 Claude Code 提示符处键入 /hello-tabs 命令，一个框架窗格在其上方打开，顶部显示"1: One"和"2: Two"，文本为"This is the first tab."。第二个选项卡显示"Add one"按钮，旁边是"Count: 1"，计数上升到 3。窗格然后返回到第一个选项卡。" data-path="images/mods-hello-tabs-light.mp4" />

36 <video autoPlay muted loop playsInline controls className="w-full hidden dark:block" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-hello-tabs-dark.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=ff7a14d713d6e5d3b0000efa8522ea4b" aria-label="在 Claude Code 提示符处键入 /hello-tabs 命令，一个框架窗格在其上方打开，顶部显示"1: One"和"2: Two"，文本为"This is the first tab."。第二个选项卡显示"Add one"按钮，旁边是"Count: 1"，计数上升到 3。窗格然后返回到第一个选项卡。" data-path="images/mods-hello-tabs-dark.mp4" />

37</Frame>

39Claude Code 没有内置的 tabs 元素，所以选项卡是一行中的两个按钮。mod 跟踪哪一个是活动的，并在该行下方绘制该选项卡的内容。

41<Steps>

42 <Step title="创建插件">

43 mod 是一个具有清单、指向你的代码的 `hooks.json` 和代码文件的插件。[创建 mod](/docs/zh-CN/plugins/mods/create#write-a-mod-yourself) 解释了每一个。创建一个名为 `hello-tabs` 的目录，其中包含 `.claude-plugin` 和 `hooks` 目录，然后保存前两个文件。

45 将清单保存为 `hello-tabs/.claude-plugin/plugin.json`：

47 ```json hello-tabs/.claude-plugin/plugin.json theme={null}

48 {

49 "name": "hello-tabs",

50 "version": "0.1.0",

51 "description": "Opens a pane with two tabs and a counter",

52 "author": { "name": "Your Name" }

53 }

54 ```

56 在 `hello-tabs/hooks/hooks.json` 中命名你的入口点：

58 ```json hello-tabs/hooks/hooks.json theme={null}

59 {

60 "modules": ["./register.js"]

61 }

62 ```

63 </Step>

65 <Step title="编写代码">

66 代码执行三个任务，每个钩子一个：

68 * 添加 `/hello-tabs` 命令

69 * 运行该命令时打开窗格

70 * 绘制窗格的内容：选项卡行和打开的选项卡的主体

72 两个模块级变量 `tab` 和 `count` 保存窗格的状态。

74 将其保存为 `hello-tabs/hooks/register.js`：

76 ```javascript hello-tabs/hooks/register.js theme={null}

77 // 窗格的 id，用于打开窗格和在绘制时识别它

78 const PANE = 'hello-tabs'

80 // 窗格显示的内容：哪个选项卡是打开的，以及计数器的值

81 let tab = 'one'

82 let count = 0

84 export function register(on) {

85 // 在你的第一个提示符之前运行，以及重新加载后再次运行

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

87 await $.command.register({ name: 'hello-tabs', description: 'Open the hello-tabs pane' })

88 // 加载早期会话保存的计数（如果有的话）

89 const saved = await $.store.get('count')

90 if (typeof saved === 'number') count = saved

91 return next(e)

92 })

94 // 当你键入 /hello-tabs 时运行

95 on('command.run', { command: 'hello-tabs' }, async ($) => {

96 // 打开窗格，给它键盘焦点，让 Esc 关闭它

97 await $.ui.open({ id: PANE, title: 'Hello tabs', focus: true, closeOnEscape: true })

98 // 在记录中不打印任何内容

99 return {}

100 })

101

102 // 每次 Claude Code 绘制窗格时运行

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

104 // 不理其他 mod 的窗格

105 if (e.requestId !== PANE) return next(e)

106 // 获取此应用可以绘制的元素

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

108 // 要求 Claude Code 再次运行此钩子

109 const redraw = () => $.ui.invalidate('ui.render')

110

111 // 一个选项卡：一个按钮，按下时切换到其选项卡

112 const tabButton = (name, label, hotkey) =>

113 Button({

114 key: 'tab-' + name,

115 label,

116 hotkey,

117 plain: true,

118 // 使不是打开的选项卡变暗

119 dimColor: tab !== name,

120 onPress: () => {

121 tab = name

122 redraw()

123 },

124 })

125

126 // 根据打开的选项卡，在选项卡下方显示的内容

127 const body =

128 tab === 'one'

129 ? [Text({ children: ['This is the first tab.'] })]

130 : [

131 Box({

132 flexDirection: 'row',

133 columnGap: 2,

134 children: [

135 Button({

136 key: 'more',

137 label: 'Add one',

138 hotkey: 'a',

139 onPress: async () => {

140 count += 1

141 redraw()

142 // 保存计数，以便在重新启动后仍然存在

143 await $.store.set('count', count)

144 },

145 }),

146 Text({ children: ['Count: ' + count] }),

147 ],

148 }),

149 ]

150

151 // 整个窗格：选项卡行、空白行，然后是主体

152 return Box({

153 flexDirection: 'column',

154 children: [

155 Box({

156 flexDirection: 'row',

157 columnGap: 3,

158 children: [tabButton('one', 'One', '1'), tabButton('two', 'Two', '2')],

159 }),

160 Text({ children: [' '] }),

161 ...body,

162 ],

163 })

164 })

165 }

166 ```

167

168 每个钩子也做代码没有明确说明的事情：

169

170 * **[`session.start`](/docs/zh-CN/plugins/mods/reference#session)** 也从 [`$.store`](#keep-state) 读取保存的计数，这是一个在会话之间持久化的键值存储。

171 * **[`command.run`](/docs/zh-CN/plugins/mods/api#add-a-command)** 只告诉 Claude Code 窗格存在。打开窗格本身不绘制任何内容：Claude Code 然后触发 `ui.render` 来询问在其中放入什么。

172 * **`ui.render`** 返回元素树，一个 `Box`，它保存其他框、文本和按钮，并从 `tab` 和 `count` 每次运行时重新构建它。

173

174 按下按钮会运行其 `onPress` 回调，该回调更改变量并调用 `redraw`。Claude Code 然后再次运行 `ui.render` 钩子，该钩子从新值构建新树。每个交互式绘制都使用该渲染周期：回调更改状态，钩子从新状态重新渲染。

175 </Step>

176

177 <Step title="打开窗格">

178 在你的 shell 中，使用 `claude --plugin-dir ./hello-tabs` 启动 Claude Code。在 Claude Code 提示符处，运行 `/hello-tabs`。一个窗格打开，顶部显示 `1: One` 和 `2: Two`。按 `2`，然后按 `a`，**Add one** 的快捷键，几次。计数上升。

179 </Step>

180

181 <Step title="检查计数是否已保存">

182 按 Esc 关闭窗格，然后退出会话。在你的 shell 中，使用相同的 `claude --plugin-dir ./hello-tabs` 命令再次启动 Claude Code，在 Claude Code 提示符处运行 `/hello-tabs`。计数在你离开的地方。

183

184 要清除计数，让 mod 调用 `$.store.delete('count')`。[保持状态](#keep-state) 涵盖每种值持续多长时间。

185 </Step>

186</Steps>

187

188<h2 id="pick-where-to-draw">

189 选择绘制位置

190</h2>

191

192`ui.render` 钩子为每个渲染站点运行，除非你将其缩小到你想要绘制的站点。要选择渲染站点，请将称为[匹配器](/docs/zh-CN/plugins/mods/events#filter-which-events-a-hook-handles)的过滤器作为第二个参数传递给 `on`。`{ component: 'Pane' }` 仅为窗格运行钩子。在钩子中，`e.component` 命名站点，`e.surface` 说明哪个应用在绘制，`e.props` 保存站点自己的数据。对于窗格，`e.requestId` 是你用来打开它的 `id`。

193

194两个站点是空的，直到 mod 填充它们，窗格和条带。选择一个选项卡以查看每个是什么以及如何在其中绘制：

195

196<Tabs>

197 <Tab title="Pane">

198 窗格是在宽全屏终端中记录旁边的侧边栏，或在其他情况下是提示符上方的框架区域。打开多个窗格时，每个窗格都会获得一个显示其标题的选项卡。

199

200 当你的 mod 使用你选择的 `id` 调用 `$.ui.open` 时，窗格出现，如 `$.ui.open({ id: 'hello-tabs' })`。[在正确的时间打开窗格](#open-a-pane-at-the-right-time) 涵盖其他字段以及窗格何时等待更宽的终端。

201

202 要在你的窗格中绘制，请过滤 `{ component: 'Pane' }` 并检查 `e.requestId` 是否是你的 `id`。

203 </Tab>

204

205 <Tab title="Band above the prompt">

206 条带是直接在提示符输入上方的条纹。它始终存在，每个 mod 都共享它。

207

208 你的钩子返回一棵树以在条带中显示某些内容，或返回 `next(e)` 以不显示任何内容。一棵树替换 mod [在你之后](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in) 在那里绘制的内容。要保留他们的，将 `await next(e)` 的结果放在你的树中的 [`Box`](#build-a-tree-from-elements) 的子项中。

209

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

211 </Tab>

212</Tabs>

213

214<h3 id="change-what-claude-code-already-draws">

215 更改 Claude Code 已经绘制的内容

216</h3>

217

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

219

220| 站点 | 它是什么 |

221| :- | :- |

222| `UserMessage`, `AssistantMessage` | 记录中的消息 |

223| `ToolUse`, `ToolResult`, `ToolGroup` | 工具调用的行、其结果和折叠的调用运行 |

224| `CommandOutput` | 命令打印的行 |

225| `AskUserQuestion` | Claude 打开的对话框以询问你一个问题 |

226| `Spinner`, `ToolProgress`, `TurnDuration` | 轮次的状态行：在 Claude 工作时动画的行、运行工具的实时进度行以及关闭轮次的行 |

227| `InfoNotice`, `SessionMode`, `PromptHint` | 徽标下的状态行、页脚中的模式标签以及提示符下的提示行 |

228

229在 Claude Code 已经绘制的站点，你的钩子有三个选择：更改详细信息、替换绘制或不理它。选择一个选项卡以查看每一个应用于加载指示器。示例读取另一个钩子计数的 `calls` 变量，如[教程 mod](/docs/zh-CN/plugins/mods/create#write-a-mod-yourself) 中所示。

230

231<Tabs>

232 <Tab title="Change a detail">

233 要保留 Claude Code 的绘制并更改其一部分，请将 `next` 传递给更改了 `props` 的事件副本。此钩子更改加载指示器单词后的文本：

234

235 ```javascript theme={null}

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

237 // 保留 Claude Code 的加载指示器，并更改其单词后的文本

238 return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

239 })

240 ```

241

242 加载指示器保留其动画和单词，你的文本跟在单词后面：

243

244 ```text theme={null}

245 Thinking · tool calls: 2…

246 ```

247 </Tab>

248

249 <Tab title="Replace the drawing">

250 要在站点的位置绘制你自己的内容，请返回一棵树，不要调用 `next`。此钩子在加载指示器所在的位置绘制一行文本：

251

252 ```javascript theme={null}

253 on('ui.render', { component: 'Spinner' }, async ($, e) => {

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

255 // 没有对 next 的调用，所以这一行在加载指示器的位置绘制

256 return Text({ children: ['Claude has made ' + calls + ' tool calls'] })

257 })

258 ```

259

260 当 Claude 工作时，你的行显示，Claude Code 的加载指示器不显示：

261

262 ```text theme={null}

263 Claude has made 2 tool calls

264 ```

265 </Tab>

266

267 <Tab title="Leave it alone">

268 要将站点保留为 Claude Code 绘制的方式，请返回 `next(e)`。钩子通常对某些事件这样做，对其他事件不这样做。此钩子在有要计数的调用之前保留加载指示器：

269

270 ```javascript theme={null}

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

272 // 还没有什么要显示的，所以不变地传递事件

273 if (calls === 0) return next(e)

274 return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

275 })

276 ```

277

278 在第一个工具调用之前，加载指示器看起来就像没有 mod 的样子：

279

280 ```text theme={null}

281 Thinking…

282 ```

283 </Tab>

284</Tabs>

285

286权限提示不是渲染站点，所以 mod 无法更改它显示的内容。问题对话框 `AskUserQuestion` 是一个，所以 mod 可以更改它。

287

288终端和桌面应用不会触发所有相同的站点。`Pane`、`AbovePrompt`、`Spinner` 和记录站点在两者中都有效。其他一些状态行仅在终端中触发。[渲染站点表](/docs/zh-CN/plugins/mods/reference#render-sites) 列出了每个站点在哪里触发。

289

290<h3 id="open-a-pane-at-the-right-time">

291 在正确的时间打开窗格

292</h3>

293

294窗格仅在你的 mod 打开它时出现。你如何以及何时打开它决定了它是否获得键盘焦点、它要求多少空间，以及它是否在狭窄的终端中显示。

295

296要打开窗格，请使用你选择的 `id` 调用 [`$.ui.open`](/docs/zh-CN/plugins/mods/reference#mods-api-methods)。`id` 是窗格的名称：你的 `ui.render` 钩子检查它，你再次传递它来关闭窗格。

297

298```javascript theme={null}

299await $.ui.open({ id: 'hello-tabs', title: 'Hello tabs', focus: true })

300```

301

302要关闭窗格，请使用你打开它的 `id` 调用 `$.ui.close`：

303

304```javascript theme={null}

305await $.ui.close({ id: 'hello-tabs' })

306```

307

308除了 `id`，`$.ui.open` 还接受这些可选字段：

309

310| 字段 | 它做什么 |

311| :- | :- |

312| `title` | 打开多个窗格时窗格的选项卡标签 |

313| `focus` | 请求[键盘焦点](#know-which-keys-your-mod-can-receive) |

314| `closeOnEscape` | 使 Esc 关闭窗格。传递 `true` 或省略字段，因为 Claude Code 拒绝 `false`。 |

315| `holdToasts` | 保持 toast，来自 [`$.ui.toast`](/docs/zh-CN/plugins/mods/api#show-something-without-starting-a-turn) 的小通知，直到窗格关闭 |

316| `rows` | 当窗格位于提示符上方时要求的高度。默认值是空间的三分之一。 |

317| `columns` | 当窗格位于记录旁边时要求的宽度 |

318

319要让命令在 Claude 工作时打开窗格，请在[注册命令](/docs/zh-CN/plugins/mods/api#add-a-command)时添加 `immediate: true`。没有它，在轮次期间键入的命令会等待轮次结束。

320

321<h4 id="when-a-pane-waits-for-a-wider-terminal">

322 当窗格等待更宽的终端时

323</h4>

324

325你的 mod 打开的窗格而不被要求不会在狭窄的终端中出现，所以它无法接管小屏幕。它是否出现取决于打开它的内容：

326

327* **由用户做的事情打开**，例如他们运行的命令或他们按下的按钮，窗格在任何宽度出现

328* **由你的 mod 自己打开**，例如从计时器或 [`turn.start`](/docs/zh-CN/plugins/mods/events#follow-a-turn) 钩子，窗格仅在至少 144 列宽的终端中出现。用户自己打开该窗格一次后，110 列就足够了。

329

330当窗格出现时，`$.ui.open` 解析为 `{ isPlaced: true }`。当窗格在等待时，`isPlaced` 是 `false`，`reason` 是一个说明原因的字符串。等待的窗格在用户打开它或拓宽终端时出现。要说某些内容可用而不打开窗格，请调用 `$.ui.toast('Your message')`，它显示一个在几秒后消失的小通知。

331

332<h2 id="build-a-tree-from-elements">

333 从元素构建树

334</h2>

335

336`ui.render` 钩子返回的是一个元素树：对要绘制的内容的描述，由相互嵌套的框、文本和控件组成。你描述绘制，Claude Code 在终端或桌面应用中呈现它。

337

338要获取元素，请在你的钩子中调用 `$.ui.resolve(e)`，如 `const { Box, Text, Button } = $.ui.resolve(e)`。每个元素都是一个函数。你传递它属性，你把在其中的元素和字符串放在 `children` 中。

339

340大多数绘制使用四个元素。选择一个选项卡以查看每一个以及终端如何绘制它：

341

342<Tabs>

343 <Tab title="Text">

344 `Text` 绘制一个字符串，带有可选的样式，如 `bold` 和 `color`：

345

346 ```javascript theme={null}

347 Text({ children: ['This is the first tab.'] })

348 ```

349

350 ```text theme={null}

351 This is the first tab.

352 ```

353 </Tab>

354

355 <Tab title="Box">

356 `Box` 排列其中的内容，在一行或一列中。这个把一个按钮和一行文本并排放在一起，相隔两列：

357

358 ```javascript theme={null}

359 Box({

360 flexDirection: 'row',

361 columnGap: 2,

362 children: [

363 Button({ key: 'more', label: 'Add one', onPress: addOne }),

364 Text({ children: ['Count: 0'] }),

365 ],

366 })

367 ```

368

369 ```text theme={null}

370 [ Add one ] Count: 0

371 ```

372 </Tab>

373

374 <Tab title="Button">

375 `Button` 是用户可以按下的控件。它运行你的 `onPress` 回调。使用 `plain: true` 它没有括号并显示其快捷键：

376

377 ```javascript theme={null}

378 Button({ key: 'more', label: 'Add one', onPress: addOne })

379 Button({ key: 'tab-one', label: 'One', hotkey: '1', plain: true, onPress: showTabOne })

380 ```

381

382 ```text theme={null}

383 [ Add one ]

384 1: One

385 ```

386 </Tab>

387

388 <Tab title="Input">

389 `Input` 是一个文本字段。当用户按 Enter 时，它使用文本运行你的 `onSubmit` 回调：

390

391 ```javascript theme={null}

392 Input({

393 key: 'new-note',

394 label: 'Note',

395 placeholder: 'Type a note and press Enter',

396 value: '',

397 submitLabel: 'add',

398 onSubmit: addNote,

399 })

400 ```

401

402 ```text theme={null}

403 Note: Type a note and press Enter ⏎ add

404 ```

405 </Tab>

406</Tabs>

407

408此表列出了每个元素：

409

410| 元素 | 它绘制什么 | 位置 |

411| :- | :- | :- |

412| `Box` | 一个 flex 容器。接受布局属性，如 `flexDirection`、`columnGap`、`padding`、`borderStyle` 和 `width`。 | 到处 |

413| `Text` | 样式化文本。接受 `color`、`bold`、`dimColor`、`italic` 和 `wrap`。`color` 是主题键或颜色，如 `'red'`。`wrap` 是 `'wrap'`、`'truncate'`、`'truncate-start'`、`'truncate-middle'` 或 `'truncate-end'`。 | 到处 |

414| `Button` | 调用 `onPress` 的控件 | 到处 |

415| `Link`, `Code`, `Markdown` | 带有 `href` 和可选 `label` 的链接、代码块和格式化为 Claude 回复方式的文本。`Markdown` 在 `text` 属性中而不是在 `children` 中获取其内容，当你传递 `onLinkPress` 时需要 `key`。 | 到处 |

416| `Input`, `Select` | 文本字段和选择器 | 终端、桌面 |

417| `Svg` | SVG 文档 | 桌面 |

418| `Client` | 由你的第二个文件绘制的区域，用于动画和指针输入。该文件没有 mod API。它仅通过发布数据到达你的钩子，该数据作为 `ui.message` 事件到达。 | 终端、桌面 |

419| `Raster`, `Image` | [彩色单元格网格](#draw-a-grid-of-colored-cells)和图片 | 终端 |

420

421如果你的模块是 `.tsx` 或 `.jsx` 文件，你可以将树写成 JSX。首先从 `$.ui.resolve(e)` 解构元素，因为钩子模块没有元素全局。

422

423如果树使用应用没有的元素、元素不接受的属性或没有子项的位置，Claude Code 绘制其自己的站点版本。

424

425在使用 `--plugin-dir` 启动的会话中，记录行说明这一点，例如 `ui.render (Pane) refused: Text prop "bogusProp" is not allowed; the engine drew its own`。[调试日志](/docs/zh-CN/plugins/mods/troubleshoot#read-the-debug-log) 将其记录为 `ui.render (Pane): a hook returned a tree that does not validate` 并带有相同的原因。会话中没有其他内容出现，所以当绘制不显示时，检查该行或日志。

426

427<h3 id="draw-a-grid-of-colored-cells">

428 绘制彩色单元格网格

429</h3>

430

431对于热力图、迷你图或终端中的游戏板，绘制一个 `Raster` 而不是每个单元格的 `Box`。`Raster` 接受 `key`、其大小（以 `columns` 和 `rows` 为单位）和 `cells`，它将每个单元格打包到一个字符串中。每个单元格是三个数字：字符的代码点、其颜色和其背景颜色。颜色是十六进制数字，红、绿、蓝各两位，例如 `0xc62828` 表示红色，或 `0x01000000` 表示终端的默认值。

432

433桌面应用没有 `Raster`，所以检查 `e.surface` 并在那里绘制文本。此窗格主体绘制一个三乘二的热力图：

434

435```javascript theme={null}

436// 表示"使用终端的默认颜色"的值

437const DEFAULT_COLOR = 0x01000000

438

439// 将 [character, color] 对的行打包到 Raster 接受的一个字符串中

440// 一个单元格是三个数字：字符的代码点、其颜色和其背景

441function cellsOf(rows) {

442 const numbers = rows.flat().flatMap(([char, color]) => [char.codePointAt(0), color, DEFAULT_COLOR])

443 return new Uint8Array(Uint32Array.from(numbers).buffer).toBase64()

444}

445

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

447 // 仅在使用 id 'heat' 打开的窗格中绘制

448 if (e.requestId !== 'heat') return next(e)

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

450 // 三个单元格的两行，每个都是一个块字符及其颜色

451 const rows = [

452 [['█', 0x2e7d32], ['█', 0xf9a825], ['█', 0xc62828]],

453 [['█', 0x2e7d32], ['█', 0x2e7d32], ['█', 0xf9a825]],

454 ]

455 if (e.surface !== 'terminal') {

456 return Text({ children: ['The heat map needs the terminal.'] })

457 }

458 return Box({

459 flexDirection: 'column',

460 children: [Raster({ key: 'grid', columns: 3, rows: 2, cells: cellsOf(rows) })],

461 })

462})

463```

464

465在终端中，窗格显示网格：

466

467<img src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-heat-map.svg?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=b91bcce3bad74bc851149133d4acc5d5" alt="终端中的一个窗格，包含一个小的彩色块网格，两行三列。顶行是绿色、琥珀色和红色。底行是绿色、绿色和琥珀色。" width="360" height="132" data-path="images/mods-heat-map.svg" />

468

469`rows` 数组是你要更改的部分，`cellsOf` 将其转换为打包的字符串。钩子仅在 `id` 为 `heat` 的窗格中绘制，所以从命令中使用 `$.ui.open({ id: 'heat' })` 打开一个，如 [`hello-tabs` 示例](#build-a-pane-with-tabs) 打开其窗格。

470

471每个字符必须是一个单元格宽。要动画化已经在屏幕上的 `Raster`，请使用窗格的 `id` 作为 `requestId`、`Raster` 的 `key`、相同的大小和新单元格调用 `$.ui.blit`。对于此示例，这是 `$.ui.blit({ requestId: 'heat', key: 'grid', columns: 3, rows: 2, cells: cellsOf(newRows) })`。它重新绘制该一个元素而不再次运行你的 `ui.render` 钩子。

472

473<h2 id="respond-to-presses-and-typing">

474 响应按键和输入

475</h2>

476

477当用户按下你绘制的按钮、输入字段或从列表中选择时，Claude Code 调用你给该控件的函数，它在你的模块中运行。每个控件接受其自己的回调：

478

479* **`Button`**：接受 `onPress(e)`，其中 `e.surface` 是按键来自的应用

480* **`Input`**：接受 `onSubmit(value)` 和 `onInput(value)`

481* **`Select`**：接受 `onSelect(value)`，其选择在 `options` 中，至少一个选择的列表，具有唯一值，例如 `[{ value: 'sm', label: 'Small' }, { value: 'lg', label: 'Large' }]`

482

483测试通过其 `key` 按下或输入到控件中，所以给每个控件一个。控件的每次使用也会触发 [`ui.press`、`ui.input` 或 `ui.select`](/docs/zh-CN/plugins/mods/reference#interface)，其中 `key` 在 `e.element` 中，另一个 mod 可以钩住这些事件。其钩子在你的回调之前运行，所以它看到用户输入到你的 `Input` 中的内容，可以更改它或代替你的回调回答。mod API 没有按下另一个 mod 的按钮的方法。

484

485<h3 id="know-which-keys-your-mod-can-receive">

486 键盘焦点和快捷键

487</h3>

488

489你的 mod 永远不会自己读取键盘。用户按下一个键，Claude Code 决定它是为你的哪个控件，该控件的回调运行。除了[条带上的数字快捷键](/docs/zh-CN/plugins/mods/reference#elements)，这仅在你的窗格或条带有键盘焦点时发生。其余时间，键进入提示符。

490

491<h4 id="how-a-pane-gets-keyboard-focus">

492 窗格如何获得键盘焦点

493</h4>

494

495窗格通过以下三种方式之一获得键盘焦点：

496

497* 你的 mod 从命令或按键使用 `focus: true` 打开它

498* 用户按 Ctrl+X 然后 Tab

499* 用户点击它

500

501Claude Code 仅在提示符为空且没有其他内容有键盘焦点时授予 `focus: true`。在用户输入时打开的窗格不会获取他们的按键。

502

503<h4 id="what-each-key-does">

504 每个键做什么

505</h4>

506

507此表列出了当你的窗格或条带有键盘焦点时每个键做什么：

508

509| 键 | 它做什么 |

510| :- | :- |

511| Tab | 移动到下一个控件 |

512| 上和下 | 在你的绘制适合时在控件之间移动。当窗格或条带的行数超过它可以显示的行数时，它们会滚动它。 |

513| Enter | 按下焦点 `Button`、提交焦点 `Input` 或在 `Select` 中选择 |

514| 按钮的快捷键 | 按下该按钮。当 `Input` 有焦点时，每个可打印键都进入字段。 |

515| Esc | 将键盘焦点返回到提示符。使用 `closeOnEscape: true`，它也关闭窗格。 |

516

517mod 无法将 Tab 或箭头键绑定到其他任何东西，所以游戏用 `w`、`a`、`s` 和 `d` 操舵。

518

519<h4 id="set-a-hotkey-and-the-first-focus">

520 设置快捷键和第一个焦点

521</h4>

522

523控件上的两个属性决定了键盘如何到达它：

524

525* **`hotkey`**：要让用户用一个键按下 `Button`，给它一个 `hotkey`，一个数字或一个小写字母，如 `hotkey: 'a'`

526* **`autoFocus`**：要选择窗格打开时哪个控件有焦点，向它添加 `autoFocus: true`。在其他上省略属性，因为 Claude Code 拒绝 `autoFocus: false`。

527

528快捷键的显示方式取决于按钮和应用：

529

530| 按钮 | 在终端中 | 在桌面应用中 |

531| :- | :- | :- |

532| 带括号，默认 | `[ Add one ]`，没有显示快捷键 | 标签，旁边有一个小键 |

533| 使用 `plain: true` | `1: One` | 标签，旁边有一个小键 |

534

535在终端中，在括号按钮的标签中命名键，或使用 `plain: true`，所以用户可以看到要按什么。[元素参考](/docs/zh-CN/plugins/mods/reference#elements) 有其他 `Button` 规则：`action`、条带上的数字快捷键和一个快捷键上的两个按钮。

536

537<h3 id="take-typed-input-and-draw-a-row-for-each-item">

538 获取输入的文本并为每个项目绘制一行

539</h3>

540

541许多窗格是一个文本字段，下面有一个列表。本部分中的示例是一个笔记窗格：你输入一个笔记并按 Enter 添加它，每个笔记都有一个删除它的 `x` 按钮。添加两个笔记后，终端这样绘制窗格：

542

543```text theme={null}

544╭──────────────────────────────────────────────────────────╮

545│ Note: Type a note and press Enter ⏎ add ✕ │

546│ x buy milk │

547│ x call bob │

548╰──────────────────────────────────────────────────────────╯

549```

550

551示例使用两种技术：

552

553* **获取输入的文本**：当用户按 Enter 时，`Input` 使用字段的文本调用 `onSubmit(value)`，在每次更改时调用 `onInput(value)`

554* **绘制列表**：将你的数据映射到每个一行，并给每行的按钮其自己的 `key`

555

556此钩子绘制窗格的内容：

557

558```javascript theme={null}

559// 窗格绘制的列表

560let notes = []

561

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

563 // 仅在使用 id 'notes' 打开的窗格中绘制

564 if (e.requestId !== 'notes') return next(e)

565 const { Box, Text, Button, Input } = $.ui.resolve(e)

566 const redraw = () => $.ui.invalidate('ui.render')

567

568 return Box({

569 flexDirection: 'column',

570 children: [

571 Input({

572 key: 'new-note',

573 label: 'Note',

574 placeholder: 'Type a note and press Enter',

575 // 每次绘制字段为空，这在提交后清除它

576 value: '',

577 submitLabel: 'add',

578 autoFocus: true,

579 // 当你在字段中按 Enter 时运行

580 onSubmit: async (value) => {

581 // 忽略空行

582 if (!value.trim()) return

583 notes = [...notes, value.trim()]

584 redraw()

585 await $.store.set('notes', notes)

586 },

587 }),

588 // 每个笔记一行：一个删除按钮，然后是笔记的文本

589 ...notes.map((note, i) =>

590 Box({

591 flexDirection: 'row',

592 columnGap: 1,

593 children: [

594 Button({

595 // 它自己的键，所以每行的按钮可以区分

596 key: 'delete-' + i,

597 label: 'x',

598 plain: true,

599 onPress: async () => {

600 notes = notes.filter((_, j) => j !== i)

601 redraw()

602 await $.store.set('notes', notes)

603 },

604 }),

605 Text({ children: [note] }),

606 ],

607 }),

608 ),

609 ],

610 })

611})

612```

613

614要尝试窗格：

615

616* **添加笔记**：输入一行并按 Enter。该行显示为新行，字段清空。

617* **删除笔记**：按 Tab 直到笔记的 `x` 按钮有焦点，然后按 Enter。`x` 是按钮的标签，不是快捷键，所以输入字母不会按下它。

618

619每个更改遵循与 `hello-tabs` 相同的渲染周期：回调更改 `notes`，调用 `redraw`，并将列表保存到 `$.store`。

620

621字段在每次提交后清空，因为其 `value` 属性。`value` 是绘制字段时保存的文本，用户的输入替换它，直到你的钩子再次绘制字段。示例总是用 `''` 绘制字段。

622

623示例保存笔记而不加载它们。要在下一个会话中将它们带回，请在 `session.start` 钩子中读取它们，就像 `hello-tabs` 读取 `count` 的方式一样。

624

625三个属性组成字段的行，`Note: Type a note and press Enter ⏎ add`：

626

627| 属性 | 在示例中 | 它是什么 |

628| :- | :- | :- |

629| `label` | `Note` | 字段前的文本。终端在其后绘制 `: `。 |

630| `placeholder` | `Type a note and press Enter` | 当字段为空时显示的暗文本 |

631| `submitLabel` | `add` | `⏎` 后的单词，说明 Enter 做什么 |

632

633提交 `Input` 不会启动轮次，除非你的回调调用 [`$.prompt.submit`](/docs/zh-CN/plugins/mods/api#start-a-turn-from-a-background-job)。

634

635<h2 id="redraw-when-something-changes">

636 重绘站点

637</h2>

638

639绘制是一个快照：它显示你的 `ui.render` 钩子上次运行时返回的内容。要显示新内容，钩子必须再次运行。Claude Code 为某些更改再次运行它，你的 mod 要求其余的。

640

641<h3 id="when-claude-code-redraws-without-being-asked">

642 当 Claude Code 在不被要求时重绘

643</h3>

644

645当站点的属性更改或终端的宽度更改时，Claude Code 再次运行你的 `ui.render` 钩子。它不在计时器上运行钩子，也无法判断你的模块中的变量何时更改。

646

647<h3 id="redraw-when-your-data-changes">

648 当你的数据更改时重绘

649</h3>

650

651要在你自己的数据更改后再次绘制你的站点，请调用 `$.ui.invalidate('ui.render')`。此窗格计数按键。按钮的回调更改 `count`，然后要求重绘：

652

653```javascript theme={null}

654let count = 0

655

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

657 if (e.requestId !== 'counter') return next(e)

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

659 return Box({

660 flexDirection: 'row',

661 columnGap: 2,

662 children: [

663 Button({

664 key: 'more',

665 label: 'Add one',

666 onPress: () => {

667 count += 1

668 // 数据更改了，所以要求 Claude Code 再次绘制窗格

669 $.ui.invalidate('ui.render')

670 },

671 }),

672 Text({ children: ['Count: ' + count] }),

673 ],

674 })

675})

676```

677

678每次按键都会提高窗格中的数字。[`hello-tabs` 示例](#build-a-pane-with-tabs) 将相同的调用包装在其 `redraw` 函数中。

679

680你在 [`$.state`](#keep-a-value-in-\$-state) 中保存的值不需要调用，因为写入值会重绘读取它的站点。

681

682<h3 id="redraw-on-a-timer">

683 在计时器上重绘

684</h3>

685

686要保持时钟、倒计时或来自会话外部的值最新，请按计划重绘。在模块的 `session.start` 钩子中启动计时器。如果模块已经有一个，如 `hello-tabs` 所做的，请将 [`$.clock.every`](/docs/zh-CN/plugins/mods/api#run-work-in-the-background) 行添加到它：

687

688```javascript theme={null}

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

690 // 每 1000 毫秒，要求 Claude Code 再次绘制你的站点

691 $.clock.every(1000, () => $.ui.invalidate('ui.render'))

692 return next(e)

693})

694```

695

696Claude Code 现在每秒运行你的 `ui.render` 钩子一次。当模块重新加载时计时器停止，新副本启动其自己的。

697

698<h3 id="how-often-a-site-can-redraw">

699 站点可以重绘的频率

700</h3>

701

702Claude Code 限制重绘的频率，所以你的 mod 可以在其数据更改时调用 `$.ui.invalidate`。可见窗格和条带的限制比其他站点更高，[限制表](/docs/zh-CN/plugins/mods/reference#limits) 中有具体数字。

703

704比限制更快的调用被合并为一次重绘。该重绘运行你的钩子一次，钩子读取你的数据，因为它在那一刻的样子，所以最新值显示，中间的值不显示。动画无法比限制运行得更快。

705

706<h2 id="keep-state">

707 保持状态

708</h2>

709

710mod 有三个地方可以保存值，它们在值持续多长时间方面有所不同：直到模块重新加载、直到会话结束或从一个会话到下一个会话。根据值必须持续多长时间选择：

711

712| 在其中保存 | 它持续到 | 用于 |

713| :- | :- | :- |

714| 模块级变量 | 模块重新加载，这在开发期间每次保存文件时发生 | 你可以丢失的值，如 `hello-tabs` 中的 `tab` |

715| `$.state` | 会话结束，或用户运行 `/clear`、`/resume` 或 `/branch` | 绘制依赖的值，应该在重新加载后存活 |

716| `$.store` | 你的 mod 删除它，或没有会话在 [`cleanupPeriodDays`](/docs/zh-CN/settings-reference#cleanupperioddays) 内读取或写入存储。存储是一个键值存储，保存为你的插件自己的 JSON 文件，位于 `~/.claude/plugins/store/` 下。 | 设置、历史记录、用户期望下次找到的任何内容 |

717

718`$.store.get(key)` 解析为值或 `undefined`，`$.store.set(key, value)` 接受任何 JSON 值。

719

720<h3 id="keep-a-value-in-state">

721 在 `$.state` 中保存值

722</h3>

723

724`$.state` 为会话的长度保存值，并为你重绘。它是反应式状态：读取值的 `ui.render` 钩子订阅它，所以 Claude Code 每次你写入值时重绘该站点，你不调用 `$.ui.invalidate`。`$.state` 中的值也在模块重新加载后存活，变量不会。

725

726要设置它，声明你的值，将你的清单指向声明，然后定义和使用每个值。示例将 `count` 从 `hello-tabs` 移到 `$.state`。

727

728<h4 id="declare-the-values">

729 声明值

730</h4>

731

732在类型文件中声明值。外键是你的插件的名称，其下的每个条目是一个值及其类型。将其保存为 `hello-tabs/types/index.d.ts`：

733

734```typescript hello-tabs/types/index.d.ts theme={null}

735declare module 'claude-code' {

736 interface PluginState {

737 'hello-tabs': {

738 tab: 'one' | 'two'

739 count: number

740 }

741 }

742}

743```

744

745<h4 id="point-the-manifest-at-the-declaration">

746 将清单指向声明

747</h4>

748

749要让 `claude plugin validate` 根据该文件检查你的代码，请向清单添加 `types` 字段及其路径：

750

751```json hello-tabs/.claude-plugin/plugin.json theme={null}

752{

753 "name": "hello-tabs",

754 "version": "0.1.0",

755 "description": "Opens a pane with two tabs and a counter",

756 "author": { "name": "Your Name" },

757 "types": "./types/index.d.ts"

758}

759```

760

761<h4 id="define-read-and-write-a-value">

762 定义、读取和写入值

763</h4>

764

765在你的模块中，定义每个值及其默认值，在绘制时读取它，并从回调中写入它。`atom` 命名值及其默认值，`read` 返回它，`update` 写入它。三个帮助程序为你调用 `$.state.get` 和 `$.state.set`：

766

767```javascript theme={null}

768import { atom, read, update } from 'claude-code'

769

770// 在模块顶部：命名值并给出其默认值

771const count = atom({ plugin: 'hello-tabs', key: 'count' }, 0)

772

773// 在 ui.render 钩子中：读取值以绘制它

774const n = await read($, count)

775

776// 在按钮中：从旧值写入新值

777onPress: () => update($, count, (value) => value + 1)

778```

779

780因为 `ui.render` 钩子读取了 `count`，Claude Code 每次按钮写入它时再次运行钩子。

781

782三个规则适用于代码：

783

784* **将 `plugin` 和 `key` 写成字面字符串**：`claude plugin validate` 从你的源代码中读取它们

785* **在类型文件中声明每个值**：否则验证失败，出现 `hello-tabs.count is not declared`

786* **从回调或另一个事件的钩子中写入**：`ui.render` 钩子可以读取状态，不能写入它，所以从 `onPress`、`onSubmit` 或另一个事件的钩子中写入

787

788<h4 id="change-hello-tabs-to-use-state">

789 更改 `hello-tabs` 以使用 `$.state`

790</h4>

791

792要将 `hello-tabs` 中的 `count` 移到 `$.state`，请更改使用它的每一行：

793

794* **在模块顶部**：添加 `import` 行，并用 `atom` 行替换 `let count = 0`

795* **在 `ui.render` 钩子中**：在 `tabButton` 之前添加 `read` 行，并在 `Text` 中绘制 `'Count: ' + n`

796* **在 Add one 按钮中**：用[从多个会话保存](#save-from-more-than-one-session)中的按钮替换 `onPress`，它保存计数以及写入它

797* **在 `session.start` 钩子中**：用[在 `/clear` 后再次加载保存的值](#load-a-saved-value-again-after-clear)中的 `loadCount` 调用替换读取 `saved` 的两行

798

799为选项卡按钮保留 `redraw`，因为 `tab` 仍然是一个变量。

800

801<h3 id="load-a-saved-value-again-after-clear">

802 在 `/clear` 后再次加载保存的值

803</h3>

804

805如果你的 mod 在 `session.start` 时将保存的值从 `$.store` 复制到 `$.state`，它必须在 `/clear`、`/resume` 或 `/branch` 后再次复制。这些命令将每个 `$.state` 值放回其默认值，`session.start` 不再触发。[`classic.SessionStart`](/docs/zh-CN/plugins/mods/events#hook-the-settings-hook-events) 在每个之后触发，`e.source` 设置为 `clear`、`resume` 或 `fork`，所以在其上的钩子中再次复制值。否则你的绘制显示默认值，保存 `$.state` 值的回调将默认值写入你存储的内容。

806

807此代码从两个钩子加载 `count`。它基于 `hello-tabs` 的 `$.state` 版本，其中 `count` 是原子，`update` 被导入。将 `loadCount` 放在 `register` 上方，并将 `loadCount` 调用添加到你已经拥有的 `session.start` 钩子。`classic.SessionStart` 也在启动和压缩后触发，这不会重置 `$.state`，所以对 `source` 的过滤将钩子保留到三个重置：

808

809```javascript theme={null}

810// 将保存的计数从 $.store 复制到 $.state，如果没有保存任何内容则为 0

811async function loadCount($) {

812 const saved = Number((await $.store.get('count')) ?? 0)

813 await update($, count, () => saved)

814}

815

816// 在你的第一个提示符之前运行，以及重新加载后再次运行

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

818 await loadCount($)

819 return next(e)

820})

821

822// 在 /clear、/resume 和 /branch 后再次运行，报告 fork

823on('classic.SessionStart', { source: ['clear', 'resume', 'fork'] }, async ($, e, next) => {

824 await loadCount($)

825 return next(e)

826})

827```

828

829两个钩子就位后，窗格在 `/clear` 后显示保存的计数，而不是 `0`，**Add one** 的下一次按键添加到保存的计数。

830

831`loadCount` 将存储的值写入 `$.state` 中的值，`session.start` 每次模块重新加载时再次触发。要保持存储不落后，请在每次更改时保存，如 **Add one** 按钮所做的。

832

833要在不会话的情况下检查重新加载，请[在 `/clear` 后测试绘制](/docs/zh-CN/plugins/mods/test#test-a-drawing-after-clear)。

834

835<h3 id="save-from-more-than-one-session">

836 从多个会话保存

837</h3>

838

839你的机器上运行你的 mod 的每个会话共享一个 `$.store`。`get` 后跟 `set` 不是原子的。当两个会话各自读取值、更改它并写回时，它们竞争，第二次写入替换第一次。

840

841两个选择使这种情况不太可能：

842

843* **给每个项目其自己的键**：`set` 仅更改其自己的键，所以写入不同键的会话不会相互覆盖

844* **在写入前再次读取**：对于多个会话更改的值，在回调中 `get` 键，并从该值构建新值，而不是从你在 `session.start` 加载的副本。如果另一个会话的写入落在你的 `get` 和 `set` 之间，它仍然会丢失。

845

846此按钮将一个添加到存储现在保存的任何内容，然后更新绘制：

847

848```javascript theme={null}

849onPress: async () => {

850 // 读取存储现在保存的内容，另一个会话可能已更改

851 const saved = Number((await $.store.get('count')) ?? 0)

852 // 保存新计数，然后显示它

853 await $.store.set('count', saved + 1)

854 await update($, count, () => saved + 1)

855}

856```

857

858如果第二个会话自此会话启动以来按下了其自己的按钮三次，此按键显示并保存包括这三个的计数。

859

860<h2 id="next-steps">

861 后续步骤

862</h2>

863

864* [对事件做出反应](/docs/zh-CN/plugins/mods/events)：从工具调用和轮次提供你的绘制

865* [使用 mod API](/docs/zh-CN/plugins/mods/api)：从计时器和模型调用提供你的绘制

866* [测试绘制](/docs/zh-CN/plugins/mods/test#test-a-drawing)：从测试按下你的按钮，在多个表面上

867* [渲染站点](/docs/zh-CN/plugins/mods/reference#render-sites)和[元素](/docs/zh-CN/plugins/mods/reference#elements)：每个站点的属性和每个元素的属性

plugins/mods/overview.md +269 −0 created

Details

1> ## Documentation Index

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

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

5# Mods 概览

7> 使用 mod 向 Claude Code 添加窗格、命令和工具调用规则。了解 mod 可以做什么、如何创建或安装 mod，以及 mod 在哪里运行。

9Mod 是一个[插件](/docs/zh-CN/plugins/overview)，它改变 Claude Code 的外观和行为。它由 JavaScript 或 TypeScript 事件处理程序组成：Claude Code 在事件发生时调用一个处理程序，例如工具调用、提交的提示或界面的一部分被绘制，处理程序可以观察事件、更改事件或接管事件。使用 mod 向 Claude Code 添加自己的功能，例如一个窗格，在每个请求后显示上下文有多满。有关 mod 中的文件和完整示例，请参阅[Mod 如何工作](#how-a-mod-works)。

11<Note>

12 Claude Code 现有的 [hooks](/docs/zh-CN/hooks) 也在事件上运行，作为 shell 命令、HTTP 请求或在设置文件中配置的提示。Mod 的处理程序是在 Claude Code 内部运行的函数。Claude Code 调用两种类型的 hooks：在这些页面上，"hook" 指的是 mod 的处理程序，而设置文件类型是"设置 hook"。

13</Note>

15<h2 id="what-a-mod-can-do">

16 Mod 可以做什么

17</h2>

19设置 hooks、skills、状态行和 MCP 服务器从 Claude Code 外部工作：每一个都运行一个脚本，或给 Claude 文本或工具。Mod 在 Claude Code 内部运行，所以它可以做他们做不了的事情：

21* **绘制可以使用的界面**：在文本记录旁边的窗格或提示上方的带状区域，带有选项卡、按钮和文本字段。请参阅[在界面中绘制](/docs/zh-CN/plugins/mods/interface)。

22* **重新绘制 Claude Code 自己的界面**：替换或重新设置 Claude Code 自己绘制的部分，例如工具调用的行、微调器或 Claude 提出问题的对话框。请参阅[更改 Claude Code 已经绘制的内容](/docs/zh-CN/plugins/mods/interface#change-what-claude-code-already-draws)。

23* **进入工具调用或请求**：例如，在向用户提出问题时保持工具调用，在不运行工具的情况下回答问题，或将一个请求发送到不同的模型。请参阅[保护或更改工具调用](/docs/zh-CN/plugins/mods/events#guard-or-change-a-tool-call)和[跟随一个转折](/docs/zh-CN/plugins/mods/events#follow-a-turn)。

24* **在命令上运行自己的代码**：一个 `/command`，立即运行你的函数，没有 Claude 转折，即使 Claude 正在工作。请参阅[添加命令或工具](/docs/zh-CN/plugins/mods/api#add-a-command-or-a-tool)。

25* **在 hooks 之间共享数据**：mod 的 hooks 共享其文件中的变量，所以一个 hook 记录的内容，另一个可以显示。例如，一个 hook 可以计算工具调用，而另一个在微调器旁边显示计数，或者一个可以读取每个请求的令牌使用情况，而另一个在窗格中绘制它。请参阅[对事件做出反应](/docs/zh-CN/plugins/mods/events)。

27Mods 在 Claude Code CLI 和 Claude Desktop 应用的代码选项卡中工作。请参阅[Mods 在哪里运行](#where-mods-run)以了解它们在其他地方的行为，例如在 VS Code 扩展、`claude -p` 和云会话中。如果设置 hook、skill 或 MCP 服务器已经做了你需要的事情，在编写 mod 之前[比较它们](#compare-mods-settings-hooks-skills-and-mcp-servers)。要为组织管理 mods，请参阅[为你的组织管理 mods](/docs/zh-CN/plugins/mods/admin)。

29<h2 id="get-a-mod">

30 获取 mod

31</h2>

33你可以通过以下三种方式之一开始使用 mod：

35* **使用你已经拥有的**：Claude Code 的一些自己的功能是 mods，例如 `/diff`。请参阅[内置于 Claude Code 的 Mods](#mods-built-into-claude-code)。

36* **创建一个**：在 Claude Code 会话中描述你想要的内容，Claude 会编写 mod。请参阅[向 Claude 请求 mod](/docs/zh-CN/plugins/mods/create#ask-claude-for-a-mod)。要了解 mod 代码如何工作，[自己编写一个](/docs/zh-CN/plugins/mods/create#write-a-mod-yourself)。

37* **安装一个**：请参阅[安装或更新 mod](#install-or-update-a-mod)

39<h3 id="install-or-update-a-mod">

40 安装或更新 mod

41</h3>

43<Warning>

44 Mod 是使用你的权限运行的代码。它可以读写你的文件、启动进程和发出网络请求。仅从你信任的作者和市场安装 mods。请参阅[决定是否信任 mod](#decide-whether-to-trust-a-mod)。

45</Warning>

47Mod 作为插件从市场安装。给出插件的名称、一个 `@` 和市场的名称。这些示例从名为 `your-org` 的市场安装名为 `token-chart` 的插件：

49* 在 Claude Code 会话中，运行 `/plugin install token-chart@your-org`。

50* 在你的 shell 中，运行 `claude plugin install token-chart@your-org`。

52[安装插件](/docs/zh-CN/plugins/install)涵盖市场、作用域、VS Code 扩展和桌面应用，以及[保持插件更新](/docs/zh-CN/plugins/install#keep-plugins-updated)，所有这些都适用于包含 mod 的插件，无需更改。

54如果在会话打开时从 shell 安装或更新 mod，在该会话中运行 `/reload-plugins` 以加载它。否则，它将在下次启动 Claude Code 时加载。

56<h2 id="decide-whether-to-trust-a-mod">

57 决定是否信任 mod

58</h2>

60Mod 是使用你的权限在 Claude Code 内部运行的代码。仅从你信任的作者和[市场](/docs/zh-CN/plugins/security)安装 mods。

62<h3 id="what-a-mod-can-reach">

63 Mod 可以访问什么

64</h3>

66Mod 使用你的权限运行，所以在安装之前，了解它可以访问什么。一旦加载，mod 可以：

68* **在你的机器上以你的身份行动**：读写你的用户账户可以访问的任何地方的文件、启动程序和发出网络请求

69* **读取你的秘密**：环境变量和设置文件，包括你保存在其中任何一个的 API 密钥

70* **查看你的会话**：你发送的每个提示和 Claude 进行的每个工具调用

71* **更改你的会话**：重写提示或工具调用、提交提示就像你输入的一样，或向你的另一个会话发送消息

72* **在不询问你的情况下行动**：在被询问之前批准工具调用

73* **花费你的使用量**：在你的计划或 API 密钥上调用模型

75批准工具调用的 mod 可以批准 `ask` 规则会提示的工具调用，或你自己的 `PreToolUse` hooks 阻止的工具调用。[使用 hooks 扩展权限](/docs/zh-CN/permissions#extend-permissions-with-hooks)列出了这样的 mod 可以批准的内容，包括它何时可以批准 `deny` 规则拒绝的调用。

77Mod 可以重新设置 Claude Code 界面的大部分样式，但不能重新设置权限提示。它不能改变提示显示给你的内容。

79<h3 id="list-what-a-mod-does-before-you-install-one">

80 在安装 mod 之前列出它做什么

81</h3>

83在安装 mod 之前，你可以列出它 hooks 的事件以及它要求 Claude Code 做什么，例如读取文件或发出网络请求，而无需运行它。首先获取插件的文件，例如通过克隆其存储库。然后，在你的 shell 中，在插件的目录上运行 `claude plugin validate`：

85```bash theme={null}

86claude plugin validate ./some-mod

87```

89输出中的 `hooks:` 和 `calls:` 行列出了 mod 处理的事件以及它要求 Claude Code 做什么。[查看 mod 可以做什么](/docs/zh-CN/plugins/mods/admin#review-what-a-mod-can-do)显示输出以及要查找的调用。

91<h2 id="turn-mods-on-or-off">

92 打开或关闭 mods

93</h2>

95Mods 需要 Claude Code v2.1.287 或更高版本，默认情况下它们是打开的。在你的 shell 中，运行 `claude --version` 以检查，如果你的版本较旧，请更新 Claude Code。

97要关闭 mods，选择要停止多少个，以及停止多长时间。要重新打开它们，撤销相同的更改：

99* **一个 mod**：从[`/plugin` 中的**已安装**选项卡](/docs/zh-CN/plugins/install#manage-installed-plugins)禁用或卸载其插件

100* **每个已安装的 mod，对于一个会话**：使用 [`--safe-mode`](/docs/zh-CN/cli-reference#cli-flags) 启动 Claude Code，这也会排除你的其他自定义

101* **你安装的每个 mod，在每个会话中**：在 `~/.claude/settings.json` 中设置 [`"disableAllHooks": true`](/docs/zh-CN/settings-reference#disableallhooks)。你的设置 hooks 和自定义状态行也会停止。你的组织管理的内容继续运行。

102

103如果你通过组织使用 Claude Code，管理员也可以限制哪些 mods 加载。管理员从[停止用户安装的 mods 加载](/docs/zh-CN/plugins/mods/admin#stop-user-installed-mods-from-loading)开始。

104

105要了解 mods 是否可以为你加载，请参阅[检查 mods 是否可以加载](/docs/zh-CN/plugins/mods/troubleshoot#check-whether-mods-can-load)。

106

107<Note>

108 如果你在早期访问期间设置了 `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS`，请删除它。Claude Code v2.1.287 及更高版本忽略它，所以将其设置为 `0` 不会保持 mods 关闭。

109</Note>

110

111<h3 id="see-which-mods-a-session-loaded">

112 查看会话加载了哪些 mods

113</h3>

114

115要查看终端会话加载了哪些 mods，在 Claude Code 提示符处运行 `/plugin`。选项卡下的暗线给出计数和名称，例如 `1 mod active · first-mod`。如果你安装的 mod 没有在那里命名，请参阅[找出为什么 mod 什么都不做](/docs/zh-CN/plugins/mods/troubleshoot#find-out-why-a-mod-does-nothing)。

116

117<h2 id="how-a-mod-works">

118 Mod 如何工作

119</h2>

120

121Mod 是一个[插件](/docs/zh-CN/plugins/overview)，其代码注册事件处理程序，称为 hooks。Claude Code 在其事件发生时运行 hook，例如当 Claude 调用工具或绘制微调器时。一个小 mod 有三个文件：

122

123```text theme={null}

124first-mod/

125├── .claude-plugin/

126│ └── plugin.json

127└── hooks/

128 ├── hooks.json

129 └── register.js

130```

131

132* **`plugin.json`**：插件的[清单](/docs/zh-CN/plugins/manifest-reference)

133* **`hooks.json`**：[指向你的代码文件](/docs/zh-CN/plugins/mods/reference#files)

134* **`register.js`**：[你的代码](/docs/zh-CN/plugins/mods/create#write-a-mod-yourself)，称为 hooks 模块。它告诉 Claude Code 在哪些事件上运行你的函数。

135

136这是一个完整的 `register.js`。它计算 Claude 进行的工具调用，并在 Claude 工作时在微调器旁边显示计数，如 `Thinking · tool calls: 3…`。

137

138```javascript hooks/register.js theme={null}

139// The count, shared by the two hooks below

140let calls = 0

141

142// Claude Code calls this once when the mod loads

143export function register(on) {

144 // Runs each time Claude is about to use a tool

145 on('tool.call', async ($, e, next) => {

146 calls += 1

147 // Ask Claude Code to draw the interface again, so the new count shows

148 $.ui.invalidate('ui.render')

149 // Let the tool run as usual

150 return next(e)

151 })

152

153 // Runs each time Claude Code draws the spinner

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

155 // Keep Claude Code's spinner, with the count added after its word

156 return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })

157 })

158}

159```

160

161该文件注册了两个 hooks，两者都使用顶部的 `calls` 变量：

162

163* **[`tool.call`](/docs/zh-CN/plugins/mods/reference#tools) hook** 在 Claude 即将使用工具时运行。它将一个添加到 `calls`，要求 Claude Code 再次绘制界面，并让工具照常运行。

164* **[`ui.render`](/docs/zh-CN/plugins/mods/reference#interface) hook** 在 Claude Code 绘制微调器时运行。它保持 Claude Code 自己的微调器，并在单词后添加计数。

165

166这个录制显示了 mod 的工作。观看提示框上方的微调器行：当 Claude 列出目录并读取两个文件时，它读取 `Thinking · tool calls: 1…`，然后 `2…`，然后 `3…`。

167

168<Frame>

169 <video autoPlay muted loop playsInline controls className="w-full dark:hidden" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-overview-light.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=00a18aa0743b59a700f0275ce226e6d1" aria-label="在 Claude Code 会话中，输入并发送提示'列出此处的文件并读取 README'。当 Claude 工作时，微调器读取'Thinking · tool calls: 1'，然后 2，然后 3，因为 Claude 列出文件并读取其中两个。" data-path="images/mods-overview-light.mp4" />

170

171 <video autoPlay muted loop playsInline controls className="w-full hidden dark:block" src="https://mintcdn.com/claude-code/dgiVO_Od1X1faduV/images/mods-overview-dark.mp4?fit=max&auto=format&n=dgiVO_Od1X1faduV&q=85&s=d5223da2fef16ceaaa214a36d72c0536" aria-label="在 Claude Code 会话中，输入并发送提示'列出此处的文件并读取 README'。当 Claude 工作时，微调器读取'Thinking · tool calls: 1'，然后 2，然后 3，因为 Claude 列出文件并读取其中两个。" data-path="images/mods-overview-dark.mp4" />

172</Frame>

173

174<h3 id="what-a-hook-can-do-with-an-event">

175 Hook 可以对事件做什么

176</h3>

177

178Claude Code 在对事件采取行动之前运行你的 hook，所以 hook 决定接下来会发生什么。它有三个选择：

179

180* **观察**：注意正在发生的事情并让它继续不变，就像示例中的 `tool.call` hook 一样

181* **重写**：在事件继续之前更改事件，就像 `ui.render` hook 在向微调器添加计数时所做的那样

182* **回答**：自己处理事件，所以通常的行为不会运行，例如拒绝命令

183

184要做任何超出其自己代码的事情，例如绘制、添加命令、调用模型、读取文件、启动进程或发出网络请求，hook 调用 mods API。Hook 没有其他方式来做这些事情，这就是为什么 Claude Code 可以在安装之前[列出 mod 做什么](#list-what-a-mod-does-before-you-install-one)。

185

186有关每个选择背后的代码，请参阅[对事件做出反应](/docs/zh-CN/plugins/mods/events#how-a-hook-handles-an-event)。有关 hook 可以调用什么，请参阅[使用 mods API](/docs/zh-CN/plugins/mods/api)。

187

188<h3 id="where-mods-run">

189 Mods 在哪里运行

190</h3>

191

192Mod 的 hooks 在加载插件的每种会话中运行。绘制更窄：只有终端和桌面应用显示 mod 的窗格、带状区域和替换的行。此表列出了你可能运行 Claude Code 的每个地方：

193

194| 你运行 Claude Code 的地方 | Hooks 运行 | Mod 绘制的内容出现 |

195| :- | :- | :- |

196| 终端中的 `claude`，包括编辑器的集成终端和 JetBrains 插件 | 是 | 是 |

197| 桌面应用的代码选项卡，除了 WSL 会话中 | 是 | 是，除了[元素表](/docs/zh-CN/plugins/mods/reference#elements)标记为仅终端的元素 |

198| 桌面应用中的 [WSL 会话](/docs/zh-CN/desktop-wsl) | 否，因为插件在 WSL 会话中不可用 | 否 |

199| VS Code 扩展的聊天面板 | 是 | 否 |

200| `claude -p` 和[代理 SDK](/docs/zh-CN/agent-sdk/overview) | 是 | 否 |

201| 从 claude.ai 或移动应用[远程控制](/docs/zh-CN/remote-control) | 是，在你机器上的会话中 | 在你机器上的终端中 |

202| [云会话](/docs/zh-CN/claude-code-on-the-web) | 是，对于[到达云会话](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)的插件 | 否 |

203

204绘制的 mod 可以检查它运行在哪个应用中，并在文本记录中的行或命令的文本回复中回退，其中没有任何内容绘制。

205

206<h2 id="control-mods-for-your-organization">

207 为你的组织控制 mods

208</h2>

209

210管理员通过[托管设置](/docs/zh-CN/managed-settings)决定 mods 是否运行以及哪些运行。[为你的组织管理 mods](/docs/zh-CN/plugins/mods/admin)涵盖默认情况下发生的事情、如何查看 mod 以及如何使用你自己的 mod 强制执行策略。

211

212<h2 id="compare-mods-settings-hooks-skills-and-mcp-servers">

213 比较 mods、设置 hooks、skills 和 MCP 服务器

214</h2>

215

216Mods、设置 hooks、skills 和 MCP 服务器重叠。此表显示每一个是什么以及何时选择它。

217

218| | Mod | 设置 hook | Skill | MCP 服务器 |

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

222| 它可以在界面中绘制吗 | 是 | 否 | 否 | 否 |

225

226其他每一个都有自己的页面：[Hooks](/docs/zh-CN/hooks)、[Skills](/docs/zh-CN/skills) 和 [MCP](/docs/zh-CN/mcp)。一个插件可以容纳所有四个，所以 mod 可以与 skill 和 MCP 服务器一起在同一个插件中发货。

227

228<h2 id="mods-built-into-claude-code">

229 内置于 Claude Code 的 Mods

230</h2>

231

232Claude Code 的一些自己的功能是 mods。要查看你的会话拥有的，在 Claude Code 提示符处运行 `/plugin` 并转到**已安装**选项卡，它在**内置**下列出它们。你不能更新或卸载内置 mod，表的最后一列说明如何关闭每一个。[`mods active` 行](#see-which-mods-a-session-loaded)排除了内置 mods。

233

234此表按 `/plugin` 显示的名称列出每个条目：

235

237| :- | :- | :- | :- |

238| `cc-plugin-agents-md` | 将 `AGENTS.md` 加载为项目指令 | 每个会话，除了[无法读取 `AGENTS.md` 的会话](/docs/zh-CN/memory#when-agents-md-support-is-unavailable) | 在 `/plugin` 中禁用它，或[选择哪些指令文件加载](/docs/zh-CN/memory#choose-which-instruction-files-load) |

241| `cc-plugin-sec-default` | 保护你的组织管理的内容免受用户安装的 mods | [保护加载的地方](/docs/zh-CN/plugins/mods/admin#know-what-happens-by-default) | 你不能。管理员在托管设置中[设置顺序](/docs/zh-CN/plugins/mods/admin#install-your-organizations-mods) |

243| `cc-plugin-you-should-know` | 运行一个侧面代理，在 Claude 处理较长任务时监视你的背后。当它发现值得了解的东西而你可能会错过时，它会在提示符上方显示一条注释。 | 默认禁用。如果可用于你的组织，在 `/plugin` -> **已安装** -> **显示禁用**中列出。使用 [`/plugin enable cc-plugin-you-should-know@builtin`](/docs/zh-CN/plugins/cli-reference#plugin-in-a-session) 启用。 | 在 `/plugin` 中禁用它 |

244

245停止已安装 mods 的设置和标志，例如 `disableAllHooks`、`--bare` 和 `--safe-mode`，不会停止内置 mods。

246

247<h3 id="read-the-source-of-built-in-mods">

248 阅读内置 mods 的源代码

249</h3>

250

251这些 mods 中的四个的源代码在 [Claude Code 存储库的 `mods` 目录](https://github.com/anthropics/claude-code/tree/main/mods)中是公开的。每一个都是一个完整的插件，带有其 hooks 模块和测试：

252

253* [`diff`](https://github.com/anthropics/claude-code/tree/main/mods/diff)：`/diff` 窗格，带有绑定到键盘操作的按钮和 mod 自己处理的滚动

254* [`agents-md`](https://github.com/anthropics/claude-code/tree/main/mods/agents-md)：将 `AGENTS.md` 加载为项目指令，带有 [`userConfig`](/docs/zh-CN/plugins/components#user-configuration) 选项

255* [`sec-default`](https://github.com/anthropics/claude-code/tree/main/mods/sec-default)：[了解默认情况下发生的事情](/docs/zh-CN/plugins/mods/admin#know-what-happens-by-default)中描述的保护，一个强制执行策略的 mod 的模型

256* [`telemetry`](https://github.com/anthropics/claude-code/tree/main/mods/telemetry)：添加其他 mods 可以调用的方法，并发货其类型

257

258<h2 id="next-steps">

259 后续步骤

260</h2>

261

262* [创建 mod](/docs/zh-CN/plugins/mods/create)：构建一个计算工具调用、在微调器旁边显示计数并添加命令的 mod，并学习编辑和重新加载循环

263* [在界面中绘制](/docs/zh-CN/plugins/mods/interface)：窗格、提示上方的带状区域、按钮、文本字段和状态

264* [对事件做出反应](/docs/zh-CN/plugins/mods/events)：工具调用、提示、转折和 mods 运行的顺序

265* [使用 mods API](/docs/zh-CN/plugins/mods/api)：命令、工具、模型调用、计时器和文件

266* [测试 mod](/docs/zh-CN/plugins/mods/test)：在没有会话的情况下运行的自动化测试

267* [对 mod 进行故障排除](/docs/zh-CN/plugins/mods/troubleshoot)：mod 什么都不做的原因和调试日志

268* [为你的组织管理 mods](/docs/zh-CN/plugins/mods/admin)：默认值、托管设置、查看 mod 和策略 mods

269* [Mods 参考](/docs/zh-CN/plugins/mods/reference)：每个事件、方法、元素和限制

plugins/mods/test.md +422 −0 created

Details

1> ## Documentation Index

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

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

5# 测试 mod

7> 为 Claude Code mod 编写自动化测试，该测试可以触发事件、存根 Claude Code 的答案、按下按钮，无需会话、登录或网络。

9您可以为 mod 编写自动化测试，并使用 [`claude plugin test`](/docs/zh-CN/plugins/mods/reference#commands) 从您的 shell 运行它们。测试会触发您的 hooks 处理的事件并检查 hooks 做了什么，这样您可以在问题到达会话之前捕获它。第一个示例测试来自 [Create a mod](/docs/zh-CN/plugins/mods/create) 的 mod。

11<h2 id="write-a-test">

12 编写测试

13</h2>

15测试加载您的 mod，通过其 hooks 发送事件，就像 Claude Code 会做的那样，并检查 hooks 做了什么，无需会话、登录或网络。您可以使用 `claude plugin test` 从 shell 运行测试，每个测试文件都导入测试工具包，这是 `claude-code/testing` 模块中的测试库。

17给每个测试文件一个以 `.test.ts` 结尾的名称，例如 `first-mod.test.ts`，并将其保存在插件目录中的任何位置。每个测试文件至少需要一个 `test()`，否则运行会失败并显示 `declares no test(): nothing ran`。测试文件可以导入您的 mod 自己的文件和兄弟 `.ts` 帮助程序，因此您可以对纯函数（例如游戏的规则）进行单元测试，而无需使用工具包。

19此测试触发两个工具调用，从 [Create a mod](/docs/zh-CN/plugins/mods/create) 运行 `/tally` 命令，并检查回复是否计算了两者。其第一行是一个 [stub](#stub-what-claude-code-would-answer)，它代替 Claude Code 回答工具调用。将其保存为 `first-mod/tests/first-mod.test.ts`：

21```typescript first-mod/tests/first-mod.test.ts theme={null}

22import { expect, test } from 'claude-code/testing'

24test('/tally reports the tool calls the mod has seen', async ($, on) => {

25 // Answer each tool call in Claude Code's place, so no tool runs

26 on('tool.call', () => ({ result: 'ok' }))

28 // Raise two tool calls, which the mod's tool.call hook counts

29 await $.tool.call({ tool: 'Bash', command: 'ls' })

30 await $.tool.call({ tool: 'Read', file_path: 'README.md' })

32 // Run /tally and check the text its hook returns

33 const answer = await $.command.run({ command: 'tally', args: '' })

34 expect(answer.text).toBe('Claude has made 2 tool calls since this mod loaded')

35})

36```

38在您的 shell 中，从 `first-mod` 目录运行测试：

40```bash theme={null}

41claude plugin test

42```

44输出列出每个测试及其是否通过，时间从一次运行到另一次运行会有所不同：

46```text theme={null}

47tests/first-mod.test.ts:

48(pass) /tally reports the tool calls the mod has seen [22.87ms]

50 1 pass

51 0 fail

52Ran 1 test across 1 file. [0.19s]

53```

55每个 `$.tool.call` 都通过了 mod 的 [`tool.call`](/docs/zh-CN/plugins/mods/reference#tools) hook，该 hook 将其计数加一并将调用传递给 stub。没有 `ls` 运行，也没有文件被读取。然后 `$.command.run` 进入 mod 的 [`command.run`](/docs/zh-CN/plugins/mods/reference#commands-and-configuration) hook，`answer` 是该 hook 返回的对象。

57当测试失败时，命令以状态 1 退出，因此它在 CI 中有效。如果您自己的 mods 无法在运行它的 shell 中加载，它会打印一行以 `claude plugin test: hooks modules are turned off` 开头的行，说明原因，并以状态 1 退出。

59<h3 id="stub-what-claude-code-would-answer">

60 Stub Claude Code 会回答的内容

61</h3>

63在测试中没有模型、存储或工具运行，因此无论您的 mod 期望 Claude Code 回答什么，测试都会使用 stub 提供答案。测试函数为此接收两个参数：

65* **`$`**：测试自己的 `$`，它代替 Claude Code。它不是 hook 接收的 [mods API](/docs/zh-CN/plugins/mods/reference#mods-api-methods)。它的每个方法都会触发同名事件，通过您的 mod 的 hooks 发送它，并解析为结果：`$.tool.call({ tool: 'Bash', command: 'ls' })` 触发 `tool.call`。`$.command.run`、`$.prompt.submit`、`$.session.start` 和 `$.turn.complete` 的工作方式相同，`$.classic.Stop` 和其他 `$.classic` 方法触发 [settings hook 事件](/docs/zh-CN/plugins/mods/events#hook-the-settings-hook-events)。测试无法直接触发 mods API 调用，例如 `ui.close`。通过您的 mod 触发它，例如按下关闭窗格的按钮。

66* **`on`**：调用它来注册 stubs，这些是代替 Claude Code 回答的 hooks。为 mods API 调用命名 stub 时不要使用 `$.`，因此注册为 `store.get` 的 stub 会回答您的 mod 的 `$.store.get`。当您的 mod 调用 [`$.model.complete`](/docs/zh-CN/plugins/mods/api#call-a-model) 或 [`$.store.get`](/docs/zh-CN/plugins/mods/interface#keep-state) 时，stub 会提供答案。

68此示例 stubs 一个模型调用。hook 属于一个名为 `grader` 的 mod，处理一个 `/grade` 命令，该命令将句子发送到模型并报告回复是否以 `PASS` 开头。该文件仅包含被测试的 hook，因此 mod 还需要 `plugin.json` 和 `hooks.json`，如 [Create a mod](/docs/zh-CN/plugins/mods/create#write-a-mod-yourself) 中所示。要在会话中输入 `/grade`，mod 还必须 [注册命令](/docs/zh-CN/plugins/mods/api#add-a-command)：

70```javascript grader/hooks/register.js theme={null}

71export function register(on) {

72 on('command.run', { command: 'grade' }, async ($, e) => {

73 // e.args is the text typed after /grade

74 const reply = await $.model.complete({

75 model: 'haiku',

76 system: 'Grade the sentence. Start your reply with PASS or FAIL.',

77 prompt: e.args,

78 })

79 const passed = reply.isAnswered && reply.text.startsWith('PASS')

80 return { text: passed ? 'Passed' : 'Try again' }

81 })

82}

83```

85此测试 stubs 模型调用以检查 hook 对通过回复的处理：

87```typescript grader/tests/grader.test.ts theme={null}

88import { expect, test } from 'claude-code/testing'

90test('a passing grade is reported', async ($, on) => {

91 // Answer the mod's $.model.complete call with a fixed reply, so no model runs

92 on('model.complete', () => ({

93 value: {

94 isAnswered: true,

95 text: 'PASS\nNice sentence.',

96 usage: { input_tokens: 10, output_tokens: 5, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 },

97 },

98 }))

100 // Run /grade, which makes the mod call the model

101 const answer = await $.command.run({ command: 'grade', args: 'The cat sat on the mat.' })

102 expect(answer.text).toBe('Passed')

103})

104```

105

106测试通过是因为 hook 的 `reply` 是 `value` 下的对象，其 `text` 以 `PASS` 开头。要检查另一个分支，添加第二个测试，其 stub 返回以 `FAIL` 开头的 `text`，并期望 `Try again`。

107

108mods API 调用的 stub 返回一个带有 `value` 字段的对象，该字段保存调用在您的 mod 中解析的内容：`{ value: 7 }` 使 `$.store.get` 解析为 `7`。Claude Code 事件（例如 [`turn.step`](/docs/zh-CN/plugins/mods/reference#turns) 或 `tool.call`）的 stub 返回该事件自己的结果，例如 `{ result: 'ok' }`。`$.session.send` 和 `$.prompt.fill` 也采用其事件的结果，如表所示。[查看 stub 返回的内容](#look-up-what-a-stub-returns) 显示每个常见名称采用的形式。两个错误意味着 stub 是错误的或缺失的。失败的测试的输出包括一个以 `the engine reported:` 开头的块，每个错误都出现在那里：

109

110* `returned neither { value } nor { deny }`：mods API 调用的 stub 返回了一个裸值

111* `no implementation for` 后跟一个名称：您的 mod 进行了该调用，没有 stub 回答它

112

113工具包还导出内存中的 mocks，为您回答整个命名空间。`mock.clock(on)` 回答 [`$.clock`](/docs/zh-CN/plugins/mods/api#run-work-in-the-background)，`mock.store(on, { count: 7 })` 从以这些条目开始的存储中回答 `$.store`，`mock.env(on, { CI: 'true' })` 从这些变量中回答 `$.env.get`。`mock.clock` 返回一个您的测试可以推进的 mock 时钟，因此计时器的测试不会等待。`mock.store` 返回 nothing，因此要检查您的 mod 保存了什么，请自己编写两个 `store` stubs，如 [drawing test](#test-a-drawing) 所做的那样。

114

115<h3 id="follow-the-test-kit’s-rules">

116 遵循测试工具包的规则

117</h3>

118

119测试工具包有一些自己的规则，违反其中一个会产生新测试作者首先遇到的错误：

120

121* **在测试对 `$` 的第一次调用之前注册每个 stub。** 在那之后调用 `on` 会抛出一个错误，例如 `on("ui.render") after the test first called $`。

122

123* **[`session.start`](/docs/zh-CN/plugins/mods/reference#session) 不会自己运行。** 每个测试都以您的模块新加载开始，其 hooks 都没有被调用，因此模块级变量保持其初始值。如果 hook 依赖于 `session.start` 设置的内容，请先触发它：

124

125 ```typescript theme={null}

126 // Answer the event after your hook passes it on with next(e)

127 on('session.start', () => ({ cwd: '/work' }))

128 // Answer the $.command.register call your hook makes

129 on('command.register', () => ({ value: undefined }))

130 // Raise the event, which runs your session.start hook

131 await $.session.start({ surface: 'terminal', isInteractive: true, cwd: '/work' })

132 ```

133

134 第二个 stub 回答 `session.start` hook（例如 [tutorial](/docs/zh-CN/plugins/mods/create#write-a-mod-yourself) 中的那个）进行的 `$.command.register` 调用。没有它，该调用会以 `no implementation for command.register` 拒绝，工具包会跳过您的 hook，因此 hook 中调用后的任何内容都不会运行。测试在那一点不会失败。仅当稍后的检查失败时，跳过的 hook 才会在 `the engine reported:` 下列出。

135

136* **返回 `next(e)` 的 hook 需要一个 stub 来回答。** 例如，当您的 [`ui.render`](/docs/zh-CN/plugins/mods/reference#interface) hook 返回 `next(e)` 时，为了在 Claude 空闲时不绘制任何内容，[mounting it](#test-a-drawing) 会失败并显示 `no implementation for ui.render`。注册一个返回元素作为纯数据的 stub：

137

138 ```typescript theme={null}

139 // Stands for what Claude Code would draw at the site

140 on('ui.render', () => ({ type: 'Text', props: {}, children: ['drawn by Claude Code'] }))

141 ```

142

143 注册 stub 后，mount 成功，`ui.find({ type: 'Text' })` 在您的 hook 返回 `next(e)` 时返回该元素。

144

145* **`turn.step` 的 stub 是一个异步生成器**，测试读取流到其末尾以获得结果：

146

147 ```typescript theme={null}

148 on('turn.step', async function* ($, e) {

149 // Each yield is one piece of the model's streamed reply

150 yield { kind: 'text', index: 0, text: 'ok' }

151 // The return value is the result of the whole request

152 return { turnId: e.turnId, index: e.index, answer: 'ok', toolUses: [], stopReason: 'end_turn', usage: null }

153 })

154

155 // Raise one request to the model, which runs your turn.step hook

156 const stream = $.turn.step({ turnId: 't', index: 0, model: 'claude-test', messageCount: 1 })

157 // Read every piece until the stream says it's done

158 let step = await stream.next()

159 while (step.done !== true) step = await stream.next()

160 const result = step.value

161 ```

162

163 当循环结束时，`result` 是 stub 返回的对象，在您的 `turn.step` hook 有机会更改它之后。这里 `result.answer` 是 `'ok'`。

164

165* **使用工具的名称和参数作为字段触发工具调用**，例如 `await $.tool.call({ tool: 'Bash', command: 'ls' })`，并注册一个返回 `{ result }` 的 `tool.call` stub。

166

167<h3 id="look-up-what-a-stub-returns">

168 查看 stub 返回的内容

169</h3>

170

171您的 mod 在测试中进行的每个 mods API 调用都需要一个 stub 来回答，除了工具包自己回答的少数几个：[`$.ui.invalidate`](/docs/zh-CN/plugins/mods/interface#redraw-when-something-changes) 和 [`$.state`](/docs/zh-CN/plugins/mods/interface#keep-state) 调用。对于 `$.clock` 调用，使用 `mock.clock(on)`，否则您的 mod 的 `$.clock.now()` 会失败并显示 `no implementation for clock.now`。

172

173此表列出了 mods 最常使用的。第一列是您的 mod 进行的调用或它使用 `next(e)` 传递的事件。第二列是传递给 `on` 的函数，使用该名称，因此 `$.store.get` 行变成 `on('store.get', ($, e) => ({ value: saved.get(e.key) }))`。stub 中的 `'...'` 标记您需要填写的文本：

174

175| 您的 mod 调用或传递 | Stub |

176| :- | :- |

177| `$.command.register`、`$.tool.register`、`$.ui.toast`、`$.ui.log`、`$.ui.status`、`$.ui.close`、`$.store.set` | `() => ({ value: undefined })`。对于 `ui.toast` 和 `ui.log`，文本是 `e.text`。 |

178| `$.store.get` | `($, e) => ({ value: saved.get(e.key) })` |

179| `$.fs.read` | `($, e) => ({ value: e.path.endsWith('notes.md') ? '# Notes' : '' })`。`e.path` 作为绝对路径到达，因此与 `endsWith` 比较。 |

180| `$.ui.open` | `() => ({ value: { isPlaced: true } })` |

181| `$.ui.ask` | 一个 `tool.call` stub，因为问题作为对 `AskUserQuestion` 工具的调用到达它：`($, e) => ({ result: { answers: { [e.questions[0].question]: 'Run it' } } })`。如果您的 mod 传递其他工具调用，请先检查 `e.tool`。 |

182| `$.model.complete` | `() => ({ value: { isAnswered: true, text: '...', usage } })` |

183| `$.process.run` | `($, e) => ({ value: { exitCode: 0, stdout: '...', stderr: '' } })`。`e.argv` 是参数列表，`e.init` 保存 `cwd` 和 `timeoutMs`。 |

184| 任何应该失败的 mods API 调用 | `() => ({ deny: 'the reason' })`，这使调用在您的 mod 中拒绝。抛出的 stub 会被跳过。 |

185| `session.start` | `() => ({ cwd: '/work' })` |

186| `turn.start` | `($, e) => ({ turnId: e.turnId })` |

187| `tool.call` | `() => ({ result: '...' })` |

188| `turn.complete` | `() => ({ text: '' })`。使用 `$.turn.complete({ turnId, answer, durationMs, isAborted: false, usage: null })` 触发它。 |

189| `prompt.submit` | `($, e) => ({ text: e.text })` |

190| `prompt.fill` | `() => ({ isFilled: true })` |

191| `$.prompt.read` | `() => ({ value: { text: '...', cursor: 0 } })` |

192| `$.ui.copy` | `() => ({ value: { isCopied: true } })` |

193| `$.session.messages` | `() => ({ value: [{ role: 'assistant', text: '...', toolUses: [] }] })` |

194| `$.session.id`、`$.agent.list` | `() => ({ value: 'abc123' })`、`() => ({ value: [] })` |

195| `session.send` | `() => ({ isDelivered: true })`。`e.to` 即使您的 mod 传递 `{ sessionId }`，也作为字符串到达。 |

196| `session.receive` | `($, e) => ({ text: e.text })`。使用 `$.session.receive({ origin: { kind: 'peer-send-message' }, text })` 触发它。 |

197| `ui.render` | `() => ({ type: 'Text', props: {}, children: ['...'] })` |

198

199`expect` 有断言 `toBe`、`toEqual`、`toMatch`、`toMatchObject`、`toContain`、`toBeDefined`、`toBeUndefined` 和 `toThrow`，以及任何之前的 `.not`。

200

201<h2 id="test-a-timer">

202 测试计时器

203</h2>

204

205在计时器上运行工作的 mod 需要测试控制的时钟，因此测试可以向前移动时间而不是等待。`const clock = mock.clock(on)` 返回一个从 `0` 开始的 mock 时钟，仅在您的测试移动它时才移动。要在另一个时间开始，请以毫秒为单位传递它，如 `mock.clock(on, { now: 5000 })`。时钟有这些方法：

206

207| 方法 | 它做什么 |

208| :- | :- |

209| `await clock.advance(1000)` | 将时间向前移动该毫秒数并运行每个到期的计时器 |

210| `await clock.set(5000)` | 将时间向前移动到该值，如 `advance` 会做的那样 |

211| `clock.now()` | 返回时间，这是您的 mod 的 `$.clock.now()` 解析的内容 |

212| `await clock.settle()` | 运行已经到期的计时器，例如一系列零延迟 `$.clock.after` 调用，而不移动时间 |

213| `await clock.sleep(2000)` | 在 stub 内，使该 stub 仅在测试推进到那么远时才回答，这是您模拟缓慢模型或进程的方式 |

214

215此 hook 属于一个名为 `countdown` 的 mod，处理一个 `/countdown` 命令，该命令接受秒数，启动一个一秒的 `$.clock.every` 计时器，并在零时显示 toast。与 `grader` 一样，该文件仅包含被测试的 hook，不注册命令：

216

217```javascript countdown/hooks/register.js theme={null}

218export function register(on) {

219 on('command.run', { command: 'countdown' }, async ($, e) => {

220 // e.args is the text typed after /countdown

221 let left = Number(e.args)

222 const timer = $.clock.every(1000, () => {

223 left -= 1

224 if (left === 0) {

225 timer.cancel()

226 $.ui.toast('Time is up')

227 }

228 })

229 // Print nothing in the transcript

230 return {}

231 })

232}

233```

234

235此测试运行 `/countdown 3` 并移动 mock 时钟，因此它检查三秒的行为而不等待三秒：

236

237```typescript countdown/tests/countdown.test.ts theme={null}

238import { expect, mock, test } from 'claude-code/testing'

239

240test('the countdown ends with a toast', async ($, on) => {

241 // Answer every $.clock call from a clock the test controls

242 const clock = mock.clock(on)

243 // Collect the text of each toast the mod shows

244 const toasts: string[] = []

245 on('ui.toast', ($, e) => {

246 toasts.push(e.text)

247 return { value: undefined }

248 })

249

250 await $.command.run({ command: 'countdown', args: '3' })

251 // After two seconds the timer has fired twice, and no toast is due

252 await clock.advance(2000)

253 expect(toasts).toEqual([])

254 // The third second brings the count to zero

255 await clock.advance(1000)

256 expect(toasts).toEqual(['Time is up'])

257})

258```

259

260第一个 `expect` 显示 toast 不会提前出现，第二个显示它出现一次。每个 `advance` 在到期的计时器运行后解析，因此下一行的检查会看到它们的效果。

261

262<h2 id="test-a-drawing">

263 测试绘图

264</h2>

265

266测试可以绘制您的 mod 的 [render sites](/docs/zh-CN/plugins/mods/reference#render-sites) 之一，然后按下、输入和查找它绘制的元素。`$.ui.mount` 通过您的 mod 的 `ui.render` hook 绘制站点，并返回一个带有每个方法的句柄。要在一个测试中覆盖多个应用，请将 `surface` 设置为要绘制的应用。此测试打开来自 [Build a pane with tabs](/docs/zh-CN/plugins/mods/interface#build-a-pane-with-tabs) 的窗格，切换选项卡，按下按钮，并检查终端和桌面应用中的计数：

267

268```typescript hello-tabs/tests/hello-tabs.test.ts theme={null}

269import { expect, test } from 'claude-code/testing'

270

271// What Claude Code passes to a ui.render hook for this pane, apart from the app

272const PANE = {

273 plugin: 'hello-tabs',

274 component: 'Pane',

275 requestId: 'hello-tabs',

276 viewport: { columns: 100, rows: 30 },

277 props: {

278 title: 'Hello tabs',

279 isFocused: true,

280 bodyColumns: 60,

281 placement: 'inline',

282 scroll: { offset: 0, bodyRows: 10 },

283 view: {},

284 },

285} as const

286

287test('the second tab counts presses and saves the count', async ($, on) => {

288 // Stub $.store with a Map, so the test can read what the mod saved

289 const saved = new Map<string, unknown>()

290 on('store.get', ($, e) => ({ value: saved.get(e.key) }))

291 on('store.set', ($, e) => {

292 saved.set(e.key, e.value)

293 return { value: undefined }

294 })

295

296 // Draw the pane once for each app

297 for (const surface of ['terminal', 'desktop'] as const) {

298 const ui = await $.ui.mount({ ...PANE, surface })

299 // Press the buttons by the key the mod gave them

300 await ui.press({ key: 'tab-two' })

301 await ui.press({ key: 'more' })

302 // The second tab's count line is in the drawing

303 expect(await ui.find({ type: 'Text', text: /^Count: \d+$/ })).toBeDefined()

304 await ui.unmount()

305 }

306

307 // One press in each app makes two

308 expect(saved.get('count')).toBe(2)

309})

310```

311

312在您的 shell 中，从 `hello-tabs` 目录运行 `claude plugin test`。当两个应用都绘制计数行且 mod 已保存 `2` 时，测试通过。计数从第一个应用转移到第二个应用，因为两个 mounts 都使用相同的加载模块。

313

314`$.ui.mount` 返回的句柄有这些方法，它们通过您给它们的 `key` 来寻址元素：

315

316| 方法 | 它做什么 |

317| :- | :- |

318| `press({ key: 'more' })` | 按下具有该 key 的 `Button` |

319| `input({ key: 'new-note', text: 'buy milk' })` | 将文本输入到具有该 key 的 `Input` 中并按 Enter。添加 `kind: 'change'` 以输入而不提交。 |

320| `select({ key: 'size', value: 'large' })` | 在具有该 key 的 `Select` 中选择具有该值的选项 |

321| `find({ key: 'more' })` 或 `find({ type: 'Text', text: 'Count: 2' })` | 返回第一个匹配的元素作为 `{ type, props, children }`，或 `undefined`。`text` 可以是字符串或正则表达式。 |

322| `unmount()` | 移除绘图 |

323

324每个方法在您的处理程序完成后解析，因此您可以在下一行检查结果。将 `props` 设置为 Claude Code 为该站点传递的内容。[render sites table](/docs/zh-CN/plugins/mods/reference#render-sites) 列出每个站点的 props，[您的构建的类型](/docs/zh-CN/plugins/mods/create#get-the-types-for-your-build) 有它们的类型。

325

326绘图测试检查您的 hook 返回的树以及它对该应用是否有效。它不检查应用如何绘制它，因此也在真实会话中查看新布局。

327

328<h3 id="test-a-drawing-after-clear">

329 在 `/clear` 后测试绘图

330</h3>

331

332每个测试都以每个 `$.state` 值在其默认值开始，这是 `/clear` 留下它们的方式。要测试您的 mod 接下来做什么，跳过 `session.start`，使用 `source: 'clear'` 触发 `classic.SessionStart`，并检查您的 mod 绘制的内容。

333

334此测试检查来自 [Load a saved value again after `/clear`](/docs/zh-CN/plugins/mods/interface#load-a-saved-value-again-after-clear) 的模块。将其添加到来自 [Test a drawing](#test-a-drawing) 的文件中，其中定义了 `PANE`。该文件的第一个测试期望按钮保存计数，如 [Save from more than one session](/docs/zh-CN/plugins/mods/interface#save-from-more-than-one-session) 中的按钮所做的那样：

335

336```typescript hello-tabs/tests/hello-tabs.test.ts theme={null}

337test('the saved count comes back after /clear', async ($, on) => {

338 // The store already holds a count of 7

339 on('store.get', () => ({ value: 7 }))

340 // Answer the event after your hook passes it on with next(e)

341 on('classic.SessionStart', () => ({}))

342

343 // Raise the event that fires after /clear, which runs your hook

344 await $.classic.SessionStart({ source: 'clear' })

345

346 const ui = await $.ui.mount({ ...PANE, surface: 'terminal' })

347 await ui.press({ key: 'tab-two' })

348 // The pane shows the stored count, not the default of 0

349 expect(await ui.find({ type: 'Text', text: 'Count: 7' })).toBeDefined()

350})

351```

352

353当您的 `classic.SessionStart` hook 在窗格绘制之前将存储的 `7` 复制到 `$.state` 时，测试通过。如果您的模块中没有该 hook，窗格绘制 `Count: 0`，`find` 返回 `undefined`，测试在 `toBeDefined` 处失败。

354

355<h2 id="test-a-mod-that-judges-other-mods">

356 测试判断其他 mods 的 mod

357</h2>

358

359您的组织在 [`prependPlugins`](/docs/zh-CN/plugins/mods/admin) 中列出的 mod 可以在另一个 mod 加载之前拒绝它。要测试一个，请设置您的 mod 的层级并给测试第二个 mod，供您的 mod 接受或拒绝：

360

361* **`tier`**：在测试文件的顶部调用它一次，如 `tier('prepend')`，以将您的 mod 加载为 `prepend`、`append` 或 `builtin`，其在 [mods 运行的顺序](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in) 中的位置。没有它，您的 mod 加载为 `user`。

362* **`plugins`**：在测试体之前将 `test` 传递一个选项对象。其 `plugins` 数组保存您内联编写的 mods，每个都有一个 `name` 和一个 `register` 函数。要在 `user` 以外的地方加载一个，请将 `tier` 添加到它。

363

364此测试文件首先加载 [admin page 中的 policy mod](/docs/zh-CN/plugins/mods/admin#enforce-a-policy-with-a-mod-of-your-own)。它检查 policy mod 是否拒绝启动进程的 mod 并接受不启动的 mod：

365

366```typescript acme-guard/tests/guard.test.ts theme={null}

367import { expect, test, tier } from 'claude-code/testing'

368

369// Load the mod under test ahead of every other mod

370tier('prepend')

371

372// A second mod whose code calls $.process.run, which the policy blocks

373const runner = {

374 name: 'runner',

375 register(on) {

376 on('tool.call', async ($, e, next) => {

377 await $.process.run(['ls'])

378 return { result: 'runner answered' }

379 })

380 },

381}

382

383// A second mod that calls nothing the policy blocks

384const reader = {

385 name: 'reader',

386 register(on) {

387 on('tool.call', async ($, e, next) => {

388 return { result: 'reader answered' }

389 })

390 },

391}

392

393test('refuses a mod that starts a process', { plugins: [runner] }, async ($, on) => {

394 on('tool.call', () => ({ result: 'claude code answered' }))

395 let message = ''

396 try {

397 // The first call on $ loads the mods, so the refusal is thrown here

398 await $.tool.call({ tool: 'Bash', command: 'ls' })

399 } catch (error) {

400 message = error.message

401 }

402 expect(message).toBe('runner: refused by acme-guard: Acme policy: mods may not call process.run')

403})

404

405test('admits a mod that starts no process', { plugins: [reader] }, async ($, on) => {

406 on('tool.call', () => ({ result: 'claude code answered' }))

407 const out = await $.tool.call({ tool: 'Bash', command: 'ls' })

408 // The answer comes from reader, which shows that it loaded

409 expect(out).toEqual({ result: 'reader answered' })

410})

411```

412

413在您的 shell 中，从 `acme-guard` 目录运行 `claude plugin test`。当 policy mod 如 admin page 所示时，两个测试都通过。

414

415工具包在测试对 `$` 的第一次调用时加载每个 mod。当您的 mod 拒绝一个时，该调用会抛出，消息会命名被拒绝的 mod、拒绝它的 mod 和您的原因。在第二个测试中，没有任何东西被拒绝，因此 `reader` 在到达 stub 之前回答工具调用。

416

417<h2 id="next-steps">

418 后续步骤

419</h2>

420

421* [Troubleshoot a mod](/docs/zh-CN/plugins/mods/troubleshoot)：找出为什么 mod 在会话中不做任何事情

422* [Mods reference](/docs/zh-CN/plugins/mods/reference)：每个事件的输入和结果，用于编写 stubs

plugins/mods/troubleshoot.md +284 −0 created

Details

1> ## Documentation Index

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

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

5# 排查 mod 问题

7> 了解为什么 Claude Code mod 不起作用：将症状或消息与其原因匹配，查找拒绝消息，并阅读调试日志。

9当 mod 的模块或其中一个 hooks 失败时，Claude Code 会跳过它，会话继续进行，因此损坏的 mod 看起来像什么都不做的 mod。首先检查 Claude Code 从 mod 读取了什么以及它在哪里报告问题，然后找到您遇到的症状或消息。

11<h2 id="find-out-why-a-mod-does-nothing">

12 找出为什么 mod 不起作用

13</h2>

15当 mod 不起作用时，两项检查可以找到原因：Claude Code 从 mod 文件读取的内容，以及它在跳过某些内容时写入的行。对于第一项，在您的 shell 中运行 [`claude plugin validate`](/docs/zh-CN/plugins/mods/create#check-what-claude-code-reads-from-your-mod)，使用 mod 的目录，如 `claude plugin validate ./first-mod`。它可以捕获拼写错误的事件、错误的清单和 Claude Code 无法读取的模块，而无需启动会话。

17当模块未加载、hook 被跳过或另一个 mod 拒绝您的 mod 时，Claude Code 会写入一行，其中命名您的 mod。您读取该行的位置取决于会话：

19* **热重新加载插件目录的会话**：成绩单中的暗行。这是您使用 `--plugin-dir` 启动的交互式会话，或者是您为 Claude 编写的 mod [启用热重新加载](/docs/zh-CN/plugins/mods/create#ask-claude-for-a-mod) 的会话。

20* **任何其他交互式会话，例如运行您从市场安装的 mod 的会话**：[调试日志](#read-the-debug-log) 仅。要获取一个，请使用 `claude --debug` 启动会话。

21* **带有 `--plugin-dir` 的 `claude -p` 运行**：stderr，采用默认文本输出格式。另一个 mod 的拒绝仅进入调试日志。

23<h2 id="check-whether-mods-can-load">

24 检查 mod 是否可以加载

25</h2>

27要检查您的设置是否允许 mod 加载，而无需安装一个，请在您的 shell 中从不包含 mod 的目录运行 `claude plugin test`。您不需要会话。它打印的消息告诉您状态：

29| 消息包含 | 这意味着什么 |

30| :- | :- |

31| `no hooks module to load` | Mod 可以加载。该命令在此目录中找不到要测试的 mod。 |

32| `hooks modules are turned off here` | 一个设置正在阻止您的 mod：您自己的设置中的 `disableAllHooks`，或您的组织的策略 |

33| `hooks modules are turned off in this process` | Anthropic 已远程关闭已安装的 mod。您机器上的任何设置都无法将其打开。 |

35组织还可以设置 `allowManagedModsOnly` 以仅允许其自己的 mod，此命令不会报告。在这种情况下，您安装的 mod 不会加载，[消息会说明原因](/docs/zh-CN/plugins/mods/troubleshoot#messages-from-the-built-in-guard)。

37<h2 id="the-mod-doesn’t-load">

38 mod 不加载

39</h2>

41mod 添加的任何内容都不会出现：没有命令、没有绘图，也没有行为改变。

43<h3 id="your-version-is-older-than-2-1-287">

44 您的版本早于 2.1.287

45</h3>

47`claude --version` 打印的版本早于 2.1.287。您的版本早于 mod 默认启用的时期。

49[更新 Claude Code](/docs/zh-CN/setup#update-claude-code)。

51<h3 id="the-mods-active-line-doesn’t-name-the-mod">

52 `mods active` 行不命名 mod

53</h3>

55mod 添加的任何内容都不会出现，`/plugin` 中的 [`mods active` 行](/docs/zh-CN/plugins/mods/overview#see-which-mods-a-session-loaded) 不命名它。hooks 模块未加载。当 Claude Code 拒绝它时，调试日志有一行以 `hooks module`、mod 的名称和 `not loaded:` 开头，如 `hooks module first-mod@inline not loaded: disableAllHooks in managed settings`，用于使用 `--plugin-dir` 加载的 mod。

57读取冒号后的原因。[拒绝消息](#refusal-messages) 部分列出了每一个。如果日志中没有这样的行，请逐一处理此组中的其他条目。

59<h3 id="a-claude-p-run-prints-hooks-module-not-loaded">

60 `claude -p` 运行打印 `hooks module not loaded`

61</h3>

63该行以 mod 的名称开头并进入 stderr。hooks 模块被拒绝。非交互式运行没有成绩单，因此消息进入 stderr。

65读取冒号后的原因。[拒绝消息](#refusal-messages) 部分列出了每一个。

67<h3 id="refusal-messages">

68 拒绝消息

69</h3>

71这些消息中的每一个都遵循调试日志中的 `hooks module`、mod 的名称和 `not loaded:`。

73| 消息开头 | 这意味着什么 |

74| :- | :- |

75| `hooks modules are turned off for installed plugins in this process` | Anthropic 已远程关闭已安装的 mod。您机器上的任何设置都无法将其打开。 |

76| `disableAllHooks in managed settings` | 您的组织关闭了来自已安装插件的 hooks |

77| `only managed plugins and built-in plugins run` | 设置了 `allowManagedHooksOnly`，或在托管设置以外的设置文件中设置了 `disableAllHooks` |

78| `installed plugins that are not managed load no hooks module in this mode (--bare)` | 您使用 `--bare` 启动了 Claude Code |

79| `another plugin of that name loads first` | 两个插件共享一个名称。使用托管的或首先加载的。 |

81<h3 id="messages-from-the-built-in-guard">

82 来自内置保护的消息

83</h3>

85在具有托管设置的机器上，或对于使用 Team 或 Enterprise 计划登录的用户，[内置保护](/docs/zh-CN/plugins/mods/admin#know-what-happens-by-default) 可以拒绝 mod 或其答案之一。每条消息都命名您的组织管理员设置以更改规则的选项。

87| 消息包含 | 这意味着什么 | 它出现在哪里 |

88| :- | :- | :- |

89| `mods are limited to your organization's by policy (allowManagedModsOnly)` | 您的组织仅允许 [其自己的 mod](/docs/zh-CN/plugins/mods/admin#install-your-organizations-mods)，因此您的 mod 未被加载 | 调试日志，以及 [热重新加载插件目录的会话](#find-out-why-a-mod-does-nothing) 中的成绩单 |

90| `tried to lift a deny rule in your settings` | 您的 mod 的 [`tool.check`](/docs/zh-CN/plugins/mods/reference#tools) hook 批准了 `deny` 规则拒绝的调用。该调用保持被拒绝。 | 成绩单和调试日志，会话中每个 mod 一次。在 `claude -p` 运行中，仅调试日志。 |

91| `the deny rules in your settings could not be checked for this call, so it is refused` | 保护在检查 mod 批准的调用时失败，因此它拒绝了该调用 | Claude 为被拒绝的调用读取的原因 |

93<h3 id="validate-passes-and-lists-no-hooks-line">

94 `validate` 通过且不列出 `hooks` 行

95</h3>

97`hooks/hooks.json` 没有 `modules` 键，或键拼写错误。

99添加 `"modules": ["./register.js"]`。

100

101<h3 id="hooks-module-did-not-load">

102 `hooks module did not load`

103</h3>

104

105该行以 mod 的名称开头，然后是 `hooks module did not load:` 和一个原因，当问题在您的代码中时，它给出文件和行。Claude Code 无法加载模块，例如因为其顶级代码抛出了异常。

106

107修复原因命名的错误。

108

109<h3 id="options-do-not-fit-plugin-json-userconfig">

110 `options do not fit plugin.json userConfig`

111</h3>

112

113该行以 mod 的名称开头，然后是 `hooks module did not load: options do not fit plugin.json userConfig:` 和一个原因。选项不适合其 [`userConfig`](/docs/zh-CN/plugins/components#user-configuration) 字段，例如高于字段 `max` 的数字，或必需字段没有值。

114

115设置或更改值。该行的末尾命名其在 `settings.json` 中的 `pluginConfigs` 条目。

116

117<h3 id="no-mod-loads-in-a-directory-you-opened-for-the-first-time">

118 没有 mod 在您首次打开的目录中加载

119</h3>

120

121您还没有回答该目录的信任提示。

122

123使用 `claude` 在该目录中启动交互式会话，并接受它打开的信任提示。

124

125<h3 id="no-installed-plugin-loads-at-all">

126 没有已安装的插件加载

127</h3>

128

129您使用 `--safe-mode` 启动了 Claude Code。

130

131启动时不使用该标志。

132

133<h2 id="a-hook-is-skipped-or-a-mod-is-unloaded">

134 hook 被跳过或 mod 被卸载

135</h2>

136

137mod 已加载，然后 Claude Code 跳过了其中一个 hooks 或卸载了它。

138

139<h3 id="hook-skipped">

140 `hook skipped`

141</h3>

142

143该行命名 mod 和事件，然后说 `hook skipped:` 和一个原因，如 `first-mod: tool.call hook skipped: threw Error: boom`。hook 抛出了异常、运行超过了其 [10 秒时间限制](/docs/zh-CN/plugins/mods/reference#limits)，或返回了错误形状的结果。该行对每个事件和失败类型出现一次，直到 mod 重新加载。

144

145修复错误。调试日志对每次出现都有一行。

146

147<h3 id="it-crashed-the-hooks-worker">

148 `it crashed the hooks worker`

149</h3>

150

151该行以 mod 的名称开头，如 `first-mod was unloaded: it crashed the hooks worker`。已安装的 mod 共享一个工作线程。工作线程停止响应或崩溃，Claude Code 将其追踪到此 mod 并卸载了它。阻止线程的 hook（例如永不等待的循环）是一个原因。

152

153修复 hook。

154

155<h3 id="mods-that-run-in-the-hooks-worker-are-off-for-this-session">

156 `mods that run in the hooks worker are off for this session`

157</h3>

158

159该行读取 `hooks: mods that run in the hooks worker are off for this session: it crashed 3 times`。工作线程停止了三次，Claude Code 无法将停止追踪到一个 mod，因此它卸载了每个不是内置的 mod，包括您的组织安装的 mod。此行在每个交互式会话中到达成绩单。

160

161运行 `/reload-plugins` 以再次加载它们。

162

163<h2 id="a-tool-call-is-denied">

164 工具调用被拒绝

165</h2>

166

167mod 已加载，其 hooks 运行，它接触的工具调用被拒绝。

168

169<h3 id="a-hook-changed-this-call’s-input-after-the-model-wrote-it">

170 `a hook changed this call's input after the model wrote it`

171</h3>

172

173在自动模式下，被拒绝的工具调用给出此原因。hook 在 [服务器端分类器](/docs/zh-CN/permission-modes#server-side-classifier-review) 审查后更改了工具调用的输入，因此该审查不涵盖将运行的内容。hook 可以是 mod 的 [`tool.call`](/docs/zh-CN/plugins/mods/reference#tools) 或 [`turn.step`](/docs/zh-CN/plugins/mods/reference#turns) hook，或 [`PreToolUse`](/docs/zh-CN/hooks#pretooluse) 设置 hook。消息不说明是哪一个。

174

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

176

177<h3 id="a-message-about-the-deny-rules-in-your-settings">

178 关于您的设置中的拒绝规则的消息

179</h3>

180

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

182

183在 [来自内置保护的消息](#messages-from-the-built-in-guard) 中查找它们。

184

185<h2 id="a-drawing-doesn’t-appear-or-respond">

186 绘图不出现或不响应

187</h2>

188

189mod 已加载，其窗格、带或控件的行为不符合您的预期。

190

191<h3 id="a-pane-or-band-is-empty-or-shows-claude-code’s-usual-content">

192 窗格或带为空或显示 Claude Code 的常规内容

193</h3>

194

195您的 hook 返回的 [树](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) 未验证。使用 `--plugin-dir`，成绩单说 `ui.render (Pane) refused:` 带有原因，如 `first-mod: ui.render (Pane) refused: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse; the engine drew its own`。调试日志有 `a hook returned a tree that does not validate` 带有相同的原因。

196

197读取该行上的原因。常见原因是元素不接受的 prop 和应用没有的元素。

198

199<h3 id="ui-open-runs-and-no-pane-appears">

200 `$.ui.open` 运行且没有窗格出现

201</h3>

202

203调用不是来自用户做的事情，终端宽度小于 144 列。

204

205从命令或按钮打开窗格，或检查调用的 `isPlaced` 结果。请参阅 [在正确的时间打开窗格](/docs/zh-CN/plugins/mods/interface#open-a-pane-at-the-right-time)。

206

207<h3 id="hotkeys-do-nothing">

208 热键不起作用

209</h3>

210

211您的窗格没有键盘焦点。

212

213按 Ctrl+X 然后 Tab，或单击窗格。使用 `focus: true` 从命令打开它。

214

215<h3 id="a-drawing-works-in-the-terminal-and-not-in-the-desktop-app">

216 绘图在终端中有效，在桌面应用中无效

217</h3>

218

219该网站或元素在那里不可用。

220

221检查 [渲染网站](/docs/zh-CN/plugins/mods/reference#render-sites) 和 [元素](/docs/zh-CN/plugins/mods/reference#elements) 表。

222

223<h2 id="an-edit-or-a-value-is-lost">

224 编辑或值丢失

225</h2>

226

227mod 运行，您所做的更改或它保留的值不存在。

228

229<h3 id="your-edits-don’t-take-effect">

230 您的编辑不生效

231</h3>

232

233您正在编辑您安装的插件。Claude Code 运行已安装版本的缓存副本。

234

235使用指向您的工作副本的 `--plugin-dir` 进行开发，如 `claude --plugin-dir ./first-mod`，它在您保存时重新加载。

236

237<h3 id="a-value-resets-when-the-module-reloads">

238 模块重新加载时值重置

239</h3>

240

241模块级变量在每次重新加载时重新初始化。

242

243[将值保留在 `$.state` 或 `$.store` 中](/docs/zh-CN/plugins/mods/interface#keep-state)。

244

245<h3 id="a-value-resets-after-/clear-/resume-or-/branch">

246 值在 `/clear`、`/resume` 或 `/branch` 后重置

247</h3>

248

249值重置，或保存的值被其默认值替换。这些命令中的每一个都将 `$.state` 重置为其默认值，`session.start` 不再触发。

250

251[在 `classic.SessionStart` hook 中再次加载保存的值](/docs/zh-CN/plugins/mods/interface#load-a-saved-value-again-after-clear)。

252

253<h2 id="read-the-debug-log">

254 阅读调试日志

255</h2>

256

257调试日志对 Claude Code 加载或拒绝的每个模块、每个失败的 hook 以及它拒绝的每个结果都有一行，因此当成绩单显示无内容时，这是查看的地方。要写入一个，在您的 shell 中使用 `--debug` 启动 Claude Code，或使用 `--debug-file <path>` 选择它的位置：

258

259```bash theme={null}

260claude --debug-file ./mod-debug.log --plugin-dir ./first-mod

261```

262

263在另一个终端中，跟踪文件并按您的 mod 名称过滤：

264

265```bash theme={null}

266tail -f ./mod-debug.log | grep first-mod

267```

268

269已加载的 mod 有一行命名它并列出它 hooks 的事件。使用 `--plugin-dir` 加载的 mod 出现在其名称后跟 `@inline` 下：

270

271```text theme={null}

272hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render

273```

274

275未验证的绘图计为被拒绝的结果，也会获得一行。要在日志中写入您自己的行，请调用 [`$.ui.log`](/docs/zh-CN/plugins/mods/api#show-something-without-starting-a-turn)，带有第二个参数，如 `$.ui.log('message', { to: 'debug' })`。没有第二个参数，`$.ui.log` 会在成绩单中添加一条暗行。

276

277当您编辑使用 `--plugin-dir` 加载的 mod 时，成绩单为每次重新加载显示一行，命名 mod 并列出其 hooks。如果保存破坏了模块，该行说 `reload failed, the previous version stays loaded:` 带有原因，最后一个工作版本继续运行。

278

279<h2 id="next-steps">

280 后续步骤

281</h2>

282

283* [测试 mod](/docs/zh-CN/plugins/mods/test)：在问题到达会话之前捕获它们

284* [排查插件问题](/docs/zh-CN/plugins/troubleshooting)：与安装和加载不特定于 mod 的插件相关的问题

plugins/org.md +4 −1

Details

214| [`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1`](/docs/zh-CN/env-vars) | 停止交互式终端会话自动注册官方市场 | 不删除已注册的市场。允许列表和阻止列表在没有它的情况下门控相同的自动注册。在设置它的情况下启动一次的机器在您取消设置它后不会恢复自动注册 |214| [`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL=1`](/docs/zh-CN/env-vars) | 停止交互式终端会话自动注册官方市场 | 不删除已注册的市场。允许列表和阻止列表在没有它的情况下门控相同的自动注册。在设置它的情况下启动一次的机器在您取消设置它后不会恢复自动注册 |

215| [`allowManagedModsOnly`](/docs/zh-CN/plugins/mods/admin#stop-user-installed-mods-from-loading) | 停止每个已安装的[mod](/docs/zh-CN/plugins/mods/overview)，其不[计为您的组织的](/docs/zh-CN/plugins/mods/admin#install-your-organizations-mods)从加载 | 不停止包含 mod 的插件安装。为此，使用此表中的市场键 |

215 216

216表中的每个键都是托管设置，除了 `enabledPlugins`、`syncClaudeAiPlugins` 和 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`：217表中的每个键都是托管设置，除了 `enabledPlugins`、`syncClaudeAiPlugins`、`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 和 `allowManagedModsOnly`：

217 218

218* **`enabledPlugins`**：您可以在任何范围内设置它，托管设置锁定它。219* **`enabledPlugins`**：您可以在任何范围内设置它，托管设置锁定它。

219* **`syncClaudeAiPlugins`**：每个用户也可以在自己的用户或本地设置中设置它。请参阅其[设置参考中的范围](/docs/zh-CN/settings-reference#syncclaudeaiplugins)。220* **`syncClaudeAiPlugins`**：每个用户也可以在自己的用户或本地设置中设置它。请参阅其[设置参考中的范围](/docs/zh-CN/settings-reference#syncclaudeaiplugins)。

220* **`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`**：这是一个环境变量，您通过[关闭整个车队的更新](#turn-updates-off-for-the-whole-fleet)下显示的托管 `env` 块交付。221* **`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL`**：这是一个环境变量，您通过[关闭整个车队的更新](#turn-updates-off-for-the-whole-fleet)下显示的托管 `env` 块交付。

222* **`allowManagedModsOnly`**：这是一个内置插件上的选项，您在托管设置中的 `pluginConfigs` 下设置。请参阅[停止用户安装的 mods 从加载](/docs/zh-CN/plugins/mods/admin#stop-user-installed-mods-from-loading)。

221 223

222此处的每个设置键在[设置参考](/docs/zh-CN/settings-reference)中都有条目。224此处的每个设置键在[设置参考](/docs/zh-CN/settings-reference)中都有条目。

223 225

457* [市场参考](/docs/zh-CN/plugins/marketplace-reference#marketplace-sources)：`extraKnownMarketplaces`、`strictKnownMarketplaces` 和 `blockedMarketplaces` 接受的 `source` 值459* [市场参考](/docs/zh-CN/plugins/marketplace-reference#marketplace-sources)：`extraKnownMarketplaces`、`strictKnownMarketplaces` 和 `blockedMarketplaces` 接受的 `source` 值

458* [托管和维护市场](/docs/zh-CN/plugins/host-marketplace)：运行您的策略指向的市场460* [托管和维护市场](/docs/zh-CN/plugins/host-marketplace)：运行您的策略指向的市场

459* [插件安全和信任](/docs/zh-CN/plugins/security)：插件可以在机器上做什么以及在安装前如何审查一个461* [插件安全和信任](/docs/zh-CN/plugins/security)：插件可以在机器上做什么以及在安装前如何审查一个

462* [管理您的组织的 mods](/docs/zh-CN/plugins/mods/admin)：关闭或限制 mods，在 Claude Code 内运行 JavaScript 的插件

460* [服务器托管设置](/docs/zh-CN/server-managed-settings)：从 claude.ai 管理控制台交付这些键463* [服务器托管设置](/docs/zh-CN/server-managed-settings)：从 claude.ai 管理控制台交付这些键

461* [插件故障排除](/docs/zh-CN/plugins/troubleshooting#blocked-by-your-organization)：策略阻止用户时看到的消息464* [插件故障排除](/docs/zh-CN/plugins/troubleshooting#blocked-by-your-organization)：策略阻止用户时看到的消息

plugins/overview.md +2 −1

Details

30* [**Skills**](/docs/zh-CN/plugins/components#skills)：`SKILL.md` 指令，Claude 在相关时加载，您也可以作为命令运行30* [**Skills**](/docs/zh-CN/plugins/components#skills)：`SKILL.md` 指令，Claude 在相关时加载，您也可以作为命令运行

31* [**Agents**](/docs/zh-CN/plugins/components#agents)：Claude 可以委派给的子代理定义31* [**Agents**](/docs/zh-CN/plugins/components#agents)：Claude 可以委派给的子代理定义

32* [**Hooks**](/docs/zh-CN/plugins/components#hooks)：Claude Code 在其生命周期中的特定点运行的命令，例如每次编辑后32* [**Hooks**](/docs/zh-CN/plugins/components#hooks)：Claude Code 在其生命周期中的特定点运行的命令，例如每次编辑后

33* [**一个 hooks 模块**](/docs/zh-CN/plugins/mods/overview)：作为 JavaScript 函数编写的 hooks，也可以绘制窗格和添加命令。拥有一个的插件称为 mod

33* [**MCP 服务器**](/docs/zh-CN/plugins/components#mcp-servers)：工具服务器，Claude Code 在启用插件时连接到34* [**MCP 服务器**](/docs/zh-CN/plugins/components#mcp-servers)：工具服务器，Claude Code 在启用插件时连接到

34 35

~~35此图显示了一个名为 `my-plugin` 的插件，其中包含这些组件中的每一个，以及插件加载后您从每个文件获得的内容。~~36此图显示了一个名为 `my-plugin` 的插件，其中包含一个 skill、一个 agent、hooks 和一个 MCP 服务器，以及插件加载后您从每个文件获得的内容。

36 37

37<img src="https://mintcdn.com/claude-code/2Q_GtOEovg5qaBem/images/plugin-directory.svg?fit=max&auto=format&n=2Q_GtOEovg5qaBem&q=85&s=f623b64e82713b830e48174f0a922888" className="dark:hidden" alt="两列图表，由五个直箭头连接。左侧是名为 my-plugin 的插件目录，包含 .claude-plugin/plugin.json 处的清单、skills/review/SKILL.md、agents/reviewer.md、hooks/hooks.json、.mcp.json 和其他组件。右侧是每个文件在您的会话中提供的内容：清单设置插件名称 my-plugin；skill 作为 /my-plugin:review 运行；agent 文件是 Claude 可以委派给的子代理；hooks 文件包含在生命周期事件上运行的 hooks；.mcp.json 添加了一个 MCP 服务器，为 Claude 提供工具。" width="760" height="336" data-path="images/plugin-directory.svg" />38<img src="https://mintcdn.com/claude-code/2Q_GtOEovg5qaBem/images/plugin-directory.svg?fit=max&auto=format&n=2Q_GtOEovg5qaBem&q=85&s=f623b64e82713b830e48174f0a922888" className="dark:hidden" alt="两列图表，由五个直箭头连接。左侧是名为 my-plugin 的插件目录，包含 .claude-plugin/plugin.json 处的清单、skills/review/SKILL.md、agents/reviewer.md、hooks/hooks.json、.mcp.json 和其他组件。右侧是每个文件在您的会话中提供的内容：清单设置插件名称 my-plugin；skill 作为 /my-plugin:review 运行；agent 文件是 Claude 可以委派给的子代理；hooks 文件包含在生命周期事件上运行的 hooks；.mcp.json 添加了一个 MCP 服务器，为 Claude 提供工具。" width="760" height="336" data-path="images/plugin-directory.svg" />

38 39

plugins/security.md +2 −1

Details

29插件可以包含在您的机器上使用您的用户权限运行代码的内容，以及作为指令进入 Claude 上下文的内容，所以[在安装前审查插件](#review-a-plugin-before-you-install)。以下是已安装的插件可以做的事情：29插件可以包含在您的机器上使用您的用户权限运行代码的内容，以及作为指令进入 Claude 上下文的内容，所以[在安装前审查插件](#review-a-plugin-before-you-install)。以下是已安装的插件可以做的事情：

30 30

31* **Hooks**：插件的 [hooks](/docs/zh-CN/hooks) 在 Claude Code 生命周期中的特定点（例如工具调用之前或之后）作为 shell 命令运行。31* **Hooks**：插件的 [hooks](/docs/zh-CN/hooks) 在 Claude Code 生命周期中的特定点（例如工具调用之前或之后）作为 shell 命令运行。

32* **Mods**：插件的 [mod](/docs/zh-CN/plugins/mods/overview) 在 Claude Code 内使用您的权限运行 JavaScript。要在安装前列出 mod 的功能，请参阅[决定是否信任 mod](/docs/zh-CN/plugins/mods/overview#decide-whether-to-trust-a-mod)。

32* **MCP 和 LSP 服务器**：Claude Code 连接到启用的插件声明的 [MCP 服务器](/docs/zh-CN/mcp)，并为 Claude 提供它们的工具。stdio MCP 服务器作为 Claude Code 在您的机器上启动的进程运行。Claude Code 也启动插件声明的语言服务器。33* **MCP 和 LSP 服务器**：Claude Code 连接到启用的插件声明的 [MCP 服务器](/docs/zh-CN/mcp)，并为 Claude 提供它们的工具。stdio MCP 服务器作为 Claude Code 在您的机器上启动的进程运行。Claude Code 也启动插件声明的语言服务器。

33* **`bin/` 目录**：Claude Code 将每个启用的插件的 `bin/` 目录添加到 Bash 工具 shell 的 `PATH` 中，所以 Claude 的 Bash 命令可以运行那里的任何可执行文件。34* **`bin/` 目录**：Claude Code 将每个启用的插件的 `bin/` 目录添加到 Bash 工具 shell 的 `PATH` 中，所以 Claude 的 Bash 命令可以运行那里的任何可执行文件。

34* **Skills、commands 和 agents**：这些作为指令进入 Claude 的上下文，所以它们影响 Claude 对它已有的工具的使用。35* **Skills、commands 和 agents**：这些作为指令进入 Claude 的上下文，所以它们影响 Claude 对它已有的工具的使用。

37Claude Code 的[权限规则](/docs/zh-CN/permissions)和[沙箱](/docs/zh-CN/sandboxing)涵盖 Claude 进行的工具调用，而不是插件自己运行的代码：38Claude Code 的[权限规则](/docs/zh-CN/permissions)和[沙箱](/docs/zh-CN/sandboxing)涵盖 Claude 进行的工具调用，而不是插件自己运行的代码：

38 39

39* **Hooks 和服务器进程**：命令 hooks 使用您的完整用户权限执行 shell 命令。Claude Code 在沙箱外运行 hooks 和 MCP 服务器。40* **Hooks 和服务器进程**：命令 hooks 使用您的完整用户权限执行 shell 命令。Claude Code 在沙箱外运行 hooks 和 MCP 服务器。

40* **Claude 的工具调用**：对插件的 MCP 工具之一的调用，以及运行插件 `bin/` 中的可执行文件的 Bash 命令，都是工具调用，所以您的权限规则适用于它们。41* **Claude 的工具调用**：对插件的 MCP 工具之一的调用，以及运行插件 `bin/` 中的可执行文件的 Bash 命令，都是工具调用，所以您的权限规则适用于它们。关于 mod 对工具调用可以做什么，请参阅[决定是否信任 mod](/docs/zh-CN/plugins/mods/overview#decide-whether-to-trust-a-mod)。

41 42

42安装插件也会启用它，除非其清单或市场条目设置了 [`defaultEnabled: false`](/docs/zh-CN/plugins/install#choose-an-install-scope)，并且您自己没有启用它。43安装插件也会启用它，除非其清单或市场条目设置了 [`defaultEnabled: false`](/docs/zh-CN/plugins/install#choose-an-install-scope)，并且您自己没有启用它。

43 44

plugins/troubleshooting.md +41 −2

Details

201 201

202成功的添加打印 `Successfully added marketplace: <name>`。202成功的添加打印 `Successfully added marketplace: <name>`。

203 203

204<h3 id="invalid-git-url">

205 `Invalid git URL`

206</h3>

207

208您添加了市场、安装了插件或从 git 地址运行了更新，命令失败，消息中显示 `Invalid git URL`。

209

210Claude Code 在运行 git 之前检查每个 git 地址。它拒绝其协议不支持的地址。它也拒绝 git 可能读取为命名不同服务器或文件夹的地址。

211

212地址后面的文本命名要更改的内容。按照消息说的重写地址并再次运行命令。

213

214拒绝消息改为说 `is blocked by enterprise policy` 来自您组织的设置。请参阅 [市场源被企业策略阻止](#marketplace-source-is-blocked-by-enterprise-policy)。

215

204<h3 id="path-does-not-exist">216<h3 id="path-does-not-exist">

205 `Path does not exist: <path>`217 `Path does not exist: <path>`

206</h3>218</h3>

410 422

411您的 shell 中的 `claude plugin install` 打印不同的消息。对于已在目标作用域安装的插件，它打印 `Plugin "<name>@<marketplace>" is already installed (scope: user)` 并以 0 退出。如果其缓存目录缺失，相同的命令重新下载它。423您的 shell 中的 `claude plugin install` 打印不同的消息。对于已在目标作用域安装的插件，它打印 `Plugin "<name>@<marketplace>" is already installed (scope: user)` 并以 0 退出。如果其缓存目录缺失，相同的命令重新下载它。

412 424

425<h3 id="plugin-would-share-its-folder">

426 `"<plugin>" was not installed: it would share its folder with "<other>"`

427</h3>

428

429您通过 `claude plugin install`、`/plugin` 或会话中的安装建议安装了插件，Claude Code 拒绝了它，显示此行或 `would share its saved data with`。

430

431被拒绝的插件的 id 和已安装的插件的 id 映射到磁盘上的同一文件夹：一旦 `.` 和 `@` 被写成 `-`，它们就是相同的。在 macOS 和 Windows 上，仅在大小写上不同的 id 也映射到同一文件夹。安装两者都会将一个插件的文件放在另一个的文件夹中，所以 Claude Code 拒绝并且已安装的插件保留其文件。

432

433消息命名了出路：

434

435* **其他插件已安装**：消息说 `Only one of the two can be installed.` 并命名 `claude plugin uninstall` 命令，或 `/plugin` 中的卸载步骤，删除其他插件。运行它，然后再次安装。对于卸载删除和保留的内容，请参阅 [卸载删除和保留的内容](/docs/zh-CN/plugins/cli-reference#what-an-uninstall-deletes-and-keeps)。

436* **两个 id 在一次安装中到达**，例如插件及其需要的依赖项：没有安装顺序有帮助。只有列出这两个插件的市场的维护者可以通过重命名其中一个来修复它。当两者来自不同的市场时，任一个的维护者都可以。

437

413<h3 id="this-plugin-uses-a-source-type-your-claude-code-version-does-not-suppo">438<h3 id="this-plugin-uses-a-source-type-your-claude-code-version-does-not-suppo">

414 `This plugin uses a source type your Claude Code version does not support`439 `This plugin uses a source type your Claude Code version does not support`

415</h3>440</h3>

790* **`URL is unset or invalid`**：URL 使用的 `${user_config.*}` 选项未设置。运行 `/plugin configure <plugin>` 设置它815* **`URL is unset or invalid`**：URL 使用的 `${user_config.*}` 选项未设置。运行 `/plugin configure <plugin>` 设置它

791* **`has an invalid MCP url`** 或 **`headersHelper for MCP server '<server>' references ${user_config.*}`**：插件自己的配置有问题。修复您的插件的 MCP 配置中的 `url` 或 `headersHelper`，或如果插件不是您的，向插件的作者报告。`headersHelper` 情况在 [插件命令参考 user\_config](/docs/zh-CN/errors#plugin-command-references-user-config) 下有其自己的条目816* **`has an invalid MCP url`** 或 **`headersHelper for MCP server '<server>' references ${user_config.*}`**：插件自己的配置有问题。修复您的插件的 MCP 配置中的 `url` 或 `headersHelper`，或如果插件不是您的，向插件的作者报告。`headersHelper` 情况在 [插件命令参考 user\_config](/docs/zh-CN/errors#plugin-command-references-user-config) 下有其自己的条目

792 817

818<h4 id="bundled-mcp-server-name-was-not-started-it-needs-configuration">

819 `Bundled MCP server "<name>" was not started: it needs configuration`

820</h4>

821

822插件包括服务器作为 [MCPB bundle](/docs/zh-CN/plugins/components#include-a-packaged-mcpb-server)，声明 `user_config`，且必需的设置没有保存的值或保存的值失败 bundle 自己的验证，所以 Claude Code 跳过启动服务器。插件的其余部分工作。

823

824在 `/plugin` 的 **Installed** 选项卡上选择插件并选择 **Configure** 以提供值。保存后，`/plugin` 显示 `Configuration saved.` 并关闭，Claude Code 重新加载插件如 [管理已安装的插件](/docs/zh-CN/plugins/install#manage-installed-plugins) 下所述。服务器在该重新加载应用后启动。在 v2.1.285 之前，Claude Code 跳过服务器而不显示此行。

825

793<h4 id="server-is-configured-but-never-connects">826<h4 id="server-is-configured-but-never-connects">

794 服务器已配置但永远不连接827 服务器已配置但永远不连接

795</h4>828</h4>

934 967

935你的插件声明了 `userConfig` 选项，但安装时没有出现配置对话框。968你的插件声明了 `userConfig` 选项，但安装时没有出现配置对话框。

936 969

937交互式安装显示对话框，shell 命令改为将值作为标志：970安装是否要求这些值取决于你在哪里运行它：

938 971

939* **在会话中 `/plugin install`，或 `/plugin` 中的 Discover 选项卡**：对话框是此交互式安装的一部分972* **在会话中 `/plugin install`，或 `/plugin` 中的 Discover 选项卡**：对话框是此交互式安装的一部分

973* **VS Code 扩展的 Manage plugins 对话框**：在安装后作为表单要求未设置的选项。在 v2.1.285 之前，在那里安装不显示选项表单，所以使用 `/plugin configure <plugin>@<marketplace>` 从终端会话设置值

940* **在你的 shell 中 `claude plugin install`**：从不提示 `userConfig` 值。它保存你传递的任何 `--config KEY=VALUE` 值，当选项保持未设置时，它打印 `N userConfig options not yet set — run /plugin configure <plugin>@<marketplace> in Claude Code, or pass --config KEY=VALUE.` 当任何未设置的选项是必需的时，`(M required)` 跟在 `not yet set` 后面。974* **在你的 shell 中 `claude plugin install`**：从不提示 `userConfig` 值。它保存你传递的任何 `--config KEY=VALUE` 值，当选项保持未设置时，它打印 `N userConfig options not yet set — run /plugin configure <plugin>@<marketplace> in Claude Code, or pass --config KEY=VALUE.` 当任何未设置的选项是必需的时，`(M required)` 跟在 `not yet set` 后面。

941 975

942如果你从 shell 安装，请使用 `--config` 传递值，每个选项一个标志：976如果你从 shell 安装，请使用 `--config` 传递值，每个选项一个标志：

945claude plugin install my-plugin@my-marketplace --config api_url=https://example.com979claude plugin install my-plugin@my-marketplace --config api_url=https://example.com

946```980```

947 981

948当每个选项都设置后，安装输出不会包含 `not yet set` 行。要在之后打开对话框，请在会话中运行 `/plugin configure my-plugin@my-marketplace`。982当每个选项都设置后，安装输出不会包含 `not yet set` 行。

983

984要在之后打开对话框，请在会话中运行 `/plugin configure my-plugin@my-marketplace`。从 shell，[`claude plugin configure`](/docs/zh-CN/plugins/cli-reference#plugin-configure) 显示哪些选项仍未设置，并保存在 stdin 上管道传入的值。它需要 Claude Code v2.1.285 或更高版本。

949 985

950如果你传递清单未声明的 `--config` 键，插件仍会安装，命令会打印 `⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig.` 后跟插件声明的键。986如果你传递清单未声明的 `--config` 键，插件仍会安装，命令会打印 `⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig.` 后跟插件声明的键。

951 987

988对于运送声明自己的 `user_config` 的[MCPB 包文件](/docs/zh-CN/plugins/components#include-a-packaged-mcpb-server)的插件，消息改为读取 `isn't declared in this plugin's userConfig or by its bundled MCP servers.`，已知的键包括该服务器的键，写作 `<server>.<key>`。清单通过 URL 引用的包在安装时不会被读取，所以其键不会被列出，消息说在 `/plugin` 中配置它。设置 `<server>.<key>` 键需要 Claude Code v2.1.285 或更高版本。

989

952<h3 id="claude-plugin-validate-reports-errors">990<h3 id="claude-plugin-validate-reports-errors">

953 `claude plugin validate` 报告错误991 `claude plugin validate` 报告错误

954</h3>992</h3>

970| `No frontmatter block found` 或 `YAML frontmatter failed to parse: <error>` | skill、agent 或 command 文件缺少或有无效的 YAML frontmatter。 | 在 `---` 分隔符之间添加或修复 frontmatter。在验证插件目录时报告。 |1008| `No frontmatter block found` 或 `YAML frontmatter failed to parse: <error>` | skill、agent 或 command 文件缺少或有无效的 YAML frontmatter。 | 在 `---` 分隔符之间添加或修复 frontmatter。在验证插件目录时报告。 |

1009| `Plugin name "<name>" is reserved: it passes as one of Anthropic's own` | 插件的 `name` 是[保留名称](/docs/zh-CN/plugins/manifest-reference#name)之一。 | 根据其功能重命名插件。 |

972 1011

973在每次修复后再次运行命令，直到它不打印任何错误。1012在每次修复后再次运行命令，直到它不打印任何错误。

scheduled-tasks.md +1 −1

Details

84<span id="loop-provider-differences" />84<span id="loop-provider-differences" />

85 85

86<Note>86<Note>

87 动态选择的间隔和[内置维护提示词](#run-the-built-in-maintenance-prompt)在每个提供商上都有效，并且[特性标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)已关闭。在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，或关闭获取时，两者都需要 Claude Code v2.1.248 或更高版本。在这些情况下，在早期版本上，没有间隔的提示词在固定的 10 分钟计划上运行，没有提示词的 `/loop` 会打印使用消息。87 动态选择的间隔和[内置维护提示词](#run-the-built-in-maintenance-prompt)在每个提供商上都有效，并且[特性标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)已关闭。在 Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上，或关闭获取时，两者都需要 Claude Code v2.1.248 或更高版本。

88</Note>88</Note>

89 89

90<h3 id="run-the-built-in-maintenance-prompt">90<h3 id="run-the-built-in-maintenance-prompt">

self-hosted-environments.md +1 −1

Details

87运行器一次为一个所有者服务。运行器拾取的第一个会话将运行器锁定到该会话的所有者，然后运行器仅为该所有者运行会话，达到配置的容量。所有者是谁取决于会话如何启动：87运行器一次为一个所有者服务。运行器拾取的第一个会话将运行器锁定到该会话的所有者，然后运行器仅为该所有者运行会话，达到配置的容量。所有者是谁取决于会话如何启动：

88 88

89* **用户启动的会话**：所有者是该用户的帐户。89* **用户启动的会话**：所有者是该用户的帐户。

90* **Claude Tag 频道会话**：Claude 运行它们时没有附加用户帐户，因此所有者是启动会话的 [Claude Tag 代理](https://claude.com/docs/claude-tag/concepts/glossary#agent-identity)。该代理启动的每个频道会话都有相同的所有者，无论谁发送了 Slack 消息，因此当您在 `--capacity` 大于 1 或正 `--drain-grace-sec` 时运行它时，锁定到它的运行器为不同的人启动的会话服务。锁定到用户的运行器永远不会拾取这些，锁定到 Claude Tag 代理的运行器永远不会拾取用户的会话。90* **Claude Tag 频道会话**：Claude 运行它们时没有附加用户帐户，因此所有者是启动会话的 [Claude Tag 代理](https://claude.com/docs/claude-tag/concepts/glossary#agent-identity)。该代理启动的每个频道会话都有相同的所有者，无论谁发送了 Slack 消息，因此当您在 `--capacity` 大于 1 或正 `--drain-grace-sec` 时运行它时，锁定到它的运行器为不同的人启动的会话服务。

91 91

92因此，最小舰队大小是您期望同时活跃的所有者数量，计算用户和 Claude Tag 代理。92因此，最小舰队大小是您期望同时活跃的所有者数量，计算用户和 Claude Tag 代理。

93 93

server-managed-settings.md +2 −1

Details

163 跨托管源的每键例外163 跨托管源的每键例外

164</h3>164</h3>

165 165

166三种类型的键是无合并规则的例外：166这些键是无合并规则的例外：

167 167

168* **跨源锁定键**：一小组键，例如沙箱允许列表锁，[列在托管设置页面上](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)。当任何管理员控制的托管源设置它们时，Claude Code 会遵守它们；用户可写的 HKCU 注册表层被排除。168* **跨源锁定键**：一小组键，例如沙箱允许列表锁，[列在托管设置页面上](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)。当任何管理员控制的托管源设置它们时，Claude Code 会遵守它们；用户可写的 HKCU 注册表层被排除。

169 169

171* **`env` 块**：除了与凭证键配对的遥测单元和路由变量（下面涵盖）外，它在管理员控制的源之间按键合并。对于每个环境变量，定义它的最高优先级源获胜，较低的管理员源填充较高源未设置的变量。因此，端点管理的 `env` 条目在服务器管理的配置未设置该变量时应用，或在该变量的缓存服务器值[等待服务器确认而被暂扣](#fetch-and-caching-behavior)期间应用。需要 Claude Code v2.1.223 或更高版本。在 v2.1.223 之前，Claude Code 仅应用选定源的整个 `env` 块。171* **`env` 块**：除了与凭证键配对的遥测单元和路由变量（下面涵盖）外，它在管理员控制的源之间按键合并。对于每个环境变量，定义它的最高优先级源获胜，较低的管理员源填充较高源未设置的变量。因此，端点管理的 `env` 条目在服务器管理的配置未设置该变量时应用，或在该变量的缓存服务器值[等待服务器确认而被暂扣](#fetch-and-caching-behavior)期间应用。需要 Claude Code v2.1.223 或更高版本。在 v2.1.223 之前，Claude Code 仅应用选定源的整个 `env` 块。

172 * **遥测单元**：`OTEL_EXPORTER_OTLP_*` 导出器键、`OTEL_LOG_*` 内容捕获切换、`OTEL_LOGS_EXPORTER` 以及测试版跟踪变量 `ENABLE_BETA_TRACING_DETAILED` 和 `BETA_TRACING_ENDPOINT` 遵循设置其中任何一个的最高源作为一个单元。传递 `otelHeadersHelper` 凭证键的源也声称该单元，但仅在它是选定源时才放置这些变量：未被选定但传递该键的源不贡献其中任何一个，仍然阻止较低源填充它们。无论哪种方式，来自一个源的导出器端点永远不能与来自另一个源的凭证配对。172 * **遥测单元**：`OTEL_EXPORTER_OTLP_*` 导出器键、`OTEL_LOG_*` 内容捕获切换、`OTEL_LOGS_EXPORTER` 以及测试版跟踪变量 `ENABLE_BETA_TRACING_DETAILED` 和 `BETA_TRACING_ENDPOINT` 遵循设置其中任何一个的最高源作为一个单元。传递 `otelHeadersHelper` 凭证键的源也声称该单元，但仅在它是选定源时才放置这些变量：未被选定但传递该键的源不贡献其中任何一个，仍然阻止较低源填充它们。无论哪种方式，来自一个源的导出器端点永远不能与来自另一个源的凭证配对。

173 * **凭证配对的路由**：将路由变量与选定源专用凭证键（例如 `apiKeyHelper` 或 `otelHeadersHelper`）配对的源仅在它赢得该槽位时贡献这些路由变量。173 * **凭证配对的路由**：将路由变量与选定源专用凭证键（例如 `apiKeyHelper` 或 `otelHeadersHelper`）配对的源仅在它赢得该槽位时贡献这些路由变量。

174* **`allowedProviders`**：机器上设置的列表和服务器管理的列表按照[其条目的范围说明](/docs/zh-CN/settings-reference#allowedproviders)所述进行组合。需要 Claude Code v2.1.285 或更高版本

174* **网关登录键**：Claude Code 永远不会从服务器管理的设置中读取 [`forceLoginGatewayUrl`](/docs/zh-CN/settings-reference#forcelogingatewayurl)、[`gatewayInternalNetworks`](/docs/zh-CN/settings-reference#gatewayinternalnetworks) 或 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 的 `"gateway"` 值，因此服务器管理的设置中的值既不适用也不隐藏在 MDM 策略或托管设置文件中设置的值。[`managedSourcesBehavior` 条目](/docs/zh-CN/settings-reference#managedsourcesbehavior)说明机器上的哪个管理员源提供它们。175* **网关登录键**：Claude Code 永远不会从服务器管理的设置中读取 [`forceLoginGatewayUrl`](/docs/zh-CN/settings-reference#forcelogingatewayurl)、[`gatewayInternalNetworks`](/docs/zh-CN/settings-reference#gatewayinternalnetworks) 或 [`forceLoginMethod`](/docs/zh-CN/settings-reference#forceloginmethod) 的 `"gateway"` 值，因此服务器管理的设置中的值既不适用也不隐藏在 MDM 策略或托管设置文件中设置的值。[`managedSourcesBehavior` 条目](/docs/zh-CN/settings-reference#managedsourcesbehavior)说明机器上的哪个管理员源提供它们。

175 176

176<h3 id="fetch-and-caching-behavior">177<h3 id="fetch-and-caching-behavior">

sessions.md +20 −2

Details

29 29

30`claude --continue` 打开已完成的[后台会话](/docs/zh-CN/agent-view)，但不打开仍在运行的会话；打开已完成的后台会话需要 Claude Code v2.1.257 或更高版本。如果您最近的对话是您[移到后台](/docs/zh-CN/agent-view#send-the-session-to-the-background)的会话，并且它仍在那里运行，Claude Code 会以 `Your most recent conversation is running in the background` 和该会话的 ID 退出。从 [`claude agents`](/docs/zh-CN/agent-view#attach-to-a-session) 附加到会话，或运行 `claude --resume` 选择另一个。30`claude --continue` 打开已完成的[后台会话](/docs/zh-CN/agent-view)，但不打开仍在运行的会话；打开已完成的后台会话需要 Claude Code v2.1.257 或更高版本。如果您最近的对话是您[移到后台](/docs/zh-CN/agent-view#send-the-session-to-the-background)的会话，并且它仍在那里运行，Claude Code 会以 `Your most recent conversation is running in the background` 和该会话的 ID 退出。从 [`claude agents`](/docs/zh-CN/agent-view#attach-to-a-session) 附加到会话，或运行 `claude --resume` 选择另一个。

31 31

32<span id="resume-a-running-background-session" />

34当您使用 `claude --resume` 或 `/resume` 恢复的对话属于仍在运行的[后台会话](/docs/zh-CN/agent-view)时，Claude Code 会打开运行中的会话本身。在命令行上使用 `--bg` 时，恢复是[后台调度](/docs/zh-CN/agent-view#from-your-shell)。在 v2.1.285 之前，Claude Code 拒绝并告诉您使用 `claude attach <id>` 打开会话，或首先使用 `claude stop <id>` 停止它。

36* **从您的 shell**：`claude --resume <session>` 在同一终端中对该会话运行 [`claude attach`](/docs/zh-CN/agent-view#attach-to-a-session)，而不是加载文本记录本身。您在命令行上传递的提示，如 `claude --resume <session> "check the tests too"`，首先作为其下一轮转到会话，Claude Code 在附加之前打印 `Sent your prompt to the background session (<id>); opening it…`。`claude -p --resume <session> "prompt"` 在终端中输入时执行相同操作，因此 `-p` 不会保持该运行非交互式。

38 当命令行具有以下任何内容时，Claude Code 不会打开会话：

40 * 管道或重定向的输入或输出

41 * 配置会话的标志，例如 `--permission-mode`、`--model` 或 `--settings`

42 * 读取输出的标志，例如 `--output-format json` 或 `--json-schema`

43 * 限制或倒带运行的标志，例如 `--max-turns` 或 `--max-budget-usd`

45 使用这些中的任何一个，或当[代理视图被关闭](/docs/zh-CN/agent-view#turn-off-agent-view)时，Claude Code 不发送任何内容并以状态 1 退出，打印会话在后台运行以及打开它的 `claude attach <id>` 命令，或当它无法确定 ID 时告诉您在 `claude agents` 中找到它。添加 `--fork-session` 以恢复对话的副本。要在您自己的会话中继续对话本身，应用您的标志，运行 `claude stop <id>`，然后重复该命令。

47 以 `/` 或 `!` 开头的提示不会被发送，会话等待您回答问题时的任何提示也不会。在这两种情况下，Claude Code 都不会打开会话，消息包括 `Your prompt was not sent to it` 和原因。

48* **从会话内**：`/resume` 将您当前的对话移到后台，并将此终端附加到运行中的会话，打印 `Opening "<title>", running in the background (<id>)`。在空提示上按 `←` 返回代理视图，这也列出您离开的对话。当当前对话无法移到后台时，例如因为您已附加到后台会话或会话持久性已关闭，`/resume` 会打印 `claude attach` 命令以改为运行。

32您可以从任何目录运行 `claude --resume <session-id>`：Claude Code 首先在当前项目目录及其 git worktrees 中查找 ID，然后在此计算机上的所有其他项目中查找，因此它会找到在其他地方启动或使用 [`/cd`](/docs/zh-CN/commands) 移动的会话。跨项目搜索仅在恰好一个其他项目持有具有该 ID 的消息的文本记录时解析 ID，因此手动复制的重复项会导致 Claude Code 报告未找到，而不是恢复任意副本。如果没有存储的会话与 ID 匹配，Claude Code 会报告 `No conversation found with session ID: <session-id>`。在 v2.1.223 之前，查找在当前项目目录及其 git worktrees 处停止，因此您必须从会话最后工作的目录恢复。50您可以从任何目录运行 `claude --resume <session-id>`：Claude Code 首先在当前项目目录及其 git worktrees 中查找 ID，然后在此计算机上的所有其他项目中查找，因此它会找到在其他地方启动或使用 [`/cd`](/docs/zh-CN/commands) 移动的会话。跨项目搜索仅在恰好一个其他项目持有具有该 ID 的消息的文本记录时解析 ID，因此手动复制的重复项会导致 Claude Code 报告未找到，而不是恢复任意副本。如果没有存储的会话与 ID 匹配，Claude Code 会报告 `No conversation found with session ID: <session-id>`。在 v2.1.223 之前，查找在当前项目目录及其 git worktrees 处停止，因此您必须从会话最后工作的目录恢复。

33 51

34<h3 id="what-a-resumed-session-restores">52<h3 id="what-a-resumed-session-restores">

35 恢复的会话恢复的内容53 恢复的会话恢复的内容

36</h3>54</h3>

37 55

~~38恢复的会话会恢复对话以及保存在其中的状态：~~56当 Claude Code 从其文本记录加载对话时，恢复的会话会恢复对话以及保存在其中的状态：

39 57

40* 对话历史：完整历史，包括工具调用和结果。如果工具在上一个进程结束时仍在运行（例如在崩溃中），当您恢复时它不会完成或再次运行。Claude 会看到该调用被标记为在记录其结果之前被切断，并被告知在再次运行之前检查它是否生效，除非设置了 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/zh-CN/env-vars#variables)。在 v2.1.281 之前，Claude Code 会从对话中删除切断的调用或将其显示为您中断的调用。58* 对话历史：完整历史，包括工具调用和结果。如果工具在上一个进程结束时仍在运行（例如在崩溃中），当您恢复时它不会完成或再次运行。Claude 会看到该调用被标记为在记录其结果之前被切断，并被告知在再次运行之前检查它是否生效，除非设置了 [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/zh-CN/env-vars#variables)。在 v2.1.281 之前，Claude Code 会从对话中删除切断的调用或将其显示为您中断的调用。

41* 模型：会话继续使用它正在使用的模型。当模型已被停用或不被 `availableModels` 允许时，模型不会被恢复；当在启动时通过 `--model` 标志或 `ANTHROPIC_MODEL` 系列环境变量选择模型时；或在使用特定于提供商的部署 ID 的提供商上，例如 [Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-CN/third-party-integrations)；请参阅[模型配置](/docs/zh-CN/model-config#setting-your-model)了解解析顺序。59* 模型：会话继续使用它正在使用的模型。当模型已被停用或不被 `availableModels` 允许时，模型不会被恢复；当在启动时通过 `--model` 标志或 `ANTHROPIC_MODEL` 系列环境变量选择模型时；或在使用特定于提供商的部署 ID 的提供商上，例如 [Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry](/docs/zh-CN/third-party-integrations)；请参阅[模型配置](/docs/zh-CN/model-config#setting-your-model)了解解析顺序。

51 恢复时的权限模式69 恢复时的权限模式

52</h4>70</h4>

53 71

~~54Claude Code 启动恢复会话的权限模式取决于您如何恢复：~~72Claude Code 启动恢复会话的权限模式取决于您如何恢复。下面的情况适用于 Claude Code 从其文本记录加载对话时；当您[打开仍在运行的后台会话](#resume-a-running-background-session)时，该会话保持它所在的权限模式。

55 73

56* 终端：`claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（当名称与一个会话匹配时），不带 `-p`。Claude Code 恢复会话所在的权限模式，除了表中的情况。传递 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆盖恢复的模式。74* 终端：`claude --continue`、`claude --resume <session-id>` 或 `claude --resume <name>`（当名称与一个会话匹配时），不带 `-p`。Claude Code 恢复会话所在的权限模式，除了表中的情况。传递 `--permission-mode` 或 `--dangerously-skip-permissions` 以覆盖恢复的模式。

57* 非交互式：`claude -p --resume` 或 `claude -p --continue`。Claude Code 在新 `claude -p` 运行会启动的权限模式中启动运行，除了在[下面的条件](#resume-in-plan-mode-with-p)下以计划模式结束的会话在计划模式中恢复。75* 非交互式：`claude -p --resume` 或 `claude -p --continue`。Claude Code 在新 `claude -p` 运行会启动的权限模式中启动运行，除了在[下面的条件](#resume-in-plan-mode-with-p)下以计划模式结束的会话在计划模式中恢复。

settings-reference.md +52 −5

Details

3675 `spinnerTipsOverride`3676 `spinnerTipsOverride`

3676</h3>3677</h3>

3677 3678

3678将您自己的提示添加到 Claude Code 在 Claude 工作时显示的[加载动画提示](#spinnertipsenabled)，或用您的提示替换内置提示。Claude Code 将您的提示放在与内置提示相同的轮换中：它选择未显示时间最长的提示，跳过仍在冷却期中的提示，并通过优先级打破平局。3679将您自己的提示添加到 Claude Code 在 Claude 工作时显示的[加载动画提示](#spinnertipsenabled)，或用您的提示替换内置提示。Claude Code 将您的提示放在与内置提示相同的轮换中。

3679 3680

3680如果您将 [`spinnerTipsEnabled`](#spinnertipsenabled) 设置为 `false`，Claude Code 会隐藏所有提示，包括您的。3681如果您将 [`spinnerTipsEnabled`](#spinnertipsenabled) 设置为 `false`，Claude Code 会隐藏所有提示，包括您的。

3681 3682

3683* **Type**: 对象，包含 `tips`、`tipsFile`、`label` 和 `excludeDefault` 字段，每个都是可选的3684* **Type**: 对象，包含 `tips`、`tipsFile`、`label` 和 `excludeDefault` 字段，每个都是可选的

3684* **Default**: unset，所以 Claude Code 仅显示内置提示3685* **Default**: unset，所以 Claude Code 仅显示内置提示

3685 3686

3686提示对象、`tipsFile`、`label` 和 Scope 行的规则（项目和本地设置仅贡献纯字符串）需要 Claude Code v2.1.247 或更高版本。在较早的版本上，项目或本地文件的 `excludeDefault` 也适用。3687提示对象、`tipsFile`、`label` 和 Scope 行的规则（项目和本地设置仅贡献纯字符串）需要 Claude Code v2.1.247 或更高版本。

3687 3688

3688每个 `tips` 条目是纯字符串或具有这些字段的对象：3689每个 `tips` 条目是纯字符串或具有这些字段的对象：

3689 3690

5653 5654

5654* **作用域**: [`任何文件`](#scopes)5655* **作用域**: [`任何文件`](#scopes)

5655* **类型**: 布尔值5656* **类型**: 布尔值

5656 * `true`: Claude Code 为该文件适用的每个会话关闭 Artifact 工具，且没有其他文件将其打开。在 v2.1.242 之前，优先级较高的文件可能会覆盖较低文件的 `true`，而不是该键充当锁定5657 * `true`: Claude Code 为该文件适用的每个会话关闭 Artifact 工具，且没有其他文件将其打开

5657 * `false`: 被忽略；要保持工具打开，请删除该键5658 * `false`: 被忽略；要保持工具打开，请删除该键

5658* **默认值**: 未设置，因此工具遵循你账户的[可用性](/docs/zh-CN/artifacts#availability)5659* **默认值**: 未设置，因此工具遵循你账户的[可用性](/docs/zh-CN/artifacts#availability)

5659* **每个会话的覆盖**: [`CLAUDE_CODE_DISABLE_ARTIFACT`](/docs/zh-CN/env-vars) 设置为 `1` 会为一个会话关闭工具5660* **每个会话的覆盖**: [`CLAUDE_CODE_DISABLE_ARTIFACT`](/docs/zh-CN/env-vars) 设置为 `1` 会为一个会话关闭工具

5740}5741}

5741```5742```

5742 5743

5743当除你自己的用户设置之外的源保持工具关闭时，Claude Code 在 `/config` 中隐藏**Artifacts** 行，因为在那里打开它不会改变任何东西。[禁用 artifacts](/docs/zh-CN/artifacts#disable-artifacts) 列出了关闭工具的每种方式。在 v2.1.242 之前，Claude Code 在项目和本地设置中忽略此键，[优先级堆栈](/docs/zh-CN/settings#settings-precedence)中较高的文件可能会在较低文件的关闭上打开工具。5744当除你自己的用户设置之外的源保持工具关闭时，Claude Code 在 `/config` 中隐藏**Artifacts** 行，因为在那里打开它不会改变任何东西。[禁用 artifacts](/docs/zh-CN/artifacts#disable-artifacts) 列出了关闭工具的每种方式。

5744 5745

5745<h3 id="inputneedednotifenabled">5746<h3 id="inputneedednotifenabled">

5746 `inputNeededNotifEnabled`5747 `inputNeededNotifEnabled`

5879 5880

5880通过辅助脚本提供凭证，对于组织，强制使用登录方法或组织。请参阅[身份验证](/docs/zh-CN/authentication)。5881通过辅助脚本提供凭证，对于组织，强制使用登录方法或组织。请参阅[身份验证](/docs/zh-CN/authentication)。

5881 5882

5883<h3 id="allowedproviders">

5884 `allowedProviders`

5885</h3>

5886

5887列出机器可以通过其到达 Claude 的服务，例如 Anthropic API、Amazon Bedrock 或 LLM 网关。未列出的提供商上的会话在启动时、登录时以及下次联系 API 时被拒绝，因此在会话中期切换到未列出的提供商也被拒绝。[拒绝消息](/docs/zh-CN/errors#managed-settings-dont-allow-this-api-provider)会命名选择提供商的内容和继续的步骤。需要 Claude Code v2.1.285 或更高版本。

5888

5889* **Scope**: [`Managed`](#scopes)。机器自身管理员源设置的列表、MDM 策略和托管设置文件在服务器托管设置也提供一个列表时继续应用：会话随后只能使用两个列表上的提供商，因此服务器托管列表可以缩小机器允许的范围但永远不能扩大它。哪个机器源的 `allowedProviders` 计数遵循[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)。通过仅服务器托管设置传递的列表仅到达[获取服务器托管设置](/docs/zh-CN/server-managed-settings#platform-availability)的会话。

5890* **Type**: 字符串数组，每个都是以下之一：

5891 * `"anthropic"`：Anthropic 自有主机上的 Anthropic API，通过 claude.ai 或 Console 登录或 API 密钥。将其与 [`forceLoginMethod`](#forceloginmethod) 或 [`forceLoginOrgUUID`](#forceloginorguuid) 配对以也限制登录

5892 * `"bedrock"`：[Amazon Bedrock](/docs/zh-CN/amazon-bedrock)

5893 * `"vertex"`：[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai)，以前称为 Vertex AI

5894 * `"foundry"`：[Microsoft Foundry](/docs/zh-CN/microsoft-foundry)

5895 * `"anthropicAws"`：[AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws)

5896 * `"mantle"`：Amazon Bedrock [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)。[在 Invoke API 旁边运行 Mantle](/docs/zh-CN/amazon-bedrock#run-mantle-alongside-the-invoke-api) 的会话使用两个提供商，因此将 `"bedrock"` 和 `"mantle"` 一起列出

5897 * `"customEndpoint"`：Anthropic API 或云提供商的 API 发送到另一个主机，例如由 `ANTHROPIC_BASE_URL` 命名的 [LLM 网关](/docs/zh-CN/llm-gateway)、提供商的 `ANTHROPIC_*_BASE_URL` 变量或不是裸资源名称的 `ANTHROPIC_FOUNDRY_RESOURCE` 值。Claude Code 仅为托管 [`env`](#env) 块固定的确切值允许它

5898 * `"gateway"`：[Cloud 网关](/docs/zh-CN/claude-apps-gateway)登录

5899* **Default**: 未设置，因此可以使用任何提供商

5900

5901```json managed-settings.json theme={null}

5902{

5903 "allowedProviders": ["anthropic", "bedrock"]

5904}

5905```

5906

5907每个云提供商的条目意味着该提供商自己的服务，包括其区域、FIPS 和私有端点。

5908

5909Claude Code 不识别为提供商名称的条目被删除并报告，列表的其余部分保持强制执行。使用空列表，或其每个条目都无法识别的列表，Claude Code 拒绝每个提供商并不在机器上启动。

5910

5911<h4 id="endpoints-that-need-a-pin-in-managed-env">

5912 需要在托管 `env` 中固定的端点

5913</h4>

5914

5915固定是在托管 [`env`](#env) 块中设置的端点变量的值。当会话将提供商的流量发送到该提供商自己的服务以外的地方时，Claude Code 仅在会话的值与固定值相同时允许它。这些端点需要一个：

5916

5917* **`"customEndpoint"` 会话**：命名主机的变量，例如 `ANTHROPIC_BASE_URL`

5918* **Amazon Bedrock**：AWS SDK 的 `AWS_ENDPOINT_URL`、`AWS_ENDPOINT_URL_BEDROCK` 和 `AWS_ENDPOINT_URL_BEDROCK_RUNTIME` 变量当它们指向 Bedrock 自己的服务之外时。会话保持在 `"bedrock"` 下而不是 `"customEndpoint"`

5919* **网关登录的 URL**：会话保持在 `"gateway"` 下，[`forceLoginGatewayUrl`](#forcelogingatewayurl) 也计为固定

5920

5921哪些 `env` 块计为固定取决于列表设置的位置：

5922

5923* **机器上的管理员源设置列表**：仅机器自身管理员源的 `env` 块计为固定

5924* **仅服务器托管设置设置列表**：这些服务器托管设置中的 `env` 值也计为固定

5925

5926列表不判断云提供商的凭证和租赁变量或网络路径，例如 `HTTPS_PROXY` 和证书设置。在托管 `env` 块中为舰队设置这些。

5927

5882<h3 id="apikeyhelper">5928<h3 id="apikeyhelper">

5883 `apiKeyHelper`5929 `apiKeyHelper`

5884</h3>5930</h3>

6401| :- | :- | :- |6447| :- | :- | :- |

6403| Locks | 应用任何源设置的最严格值。当没有源设置严格值时，仅从最高源应用较宽松的值 | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly)、[`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) 和其他布尔值或枚举锁 |6449| Locks | 应用任何源设置的最严格值。当没有源设置严格值时，仅从最高源应用较宽松的值 | [`allowManagedPermissionRulesOnly`](#allowmanagedpermissionrulesonly)、[`permissions.disableBypassPermissionsMode`](#permissions-disablebypasspermissionsmode) 和其他布尔值或枚举锁 |

6404| Restriction allowlists | 从设置它的最高源整体取值，不从较低源添加条目。当最高源未设置时，从下一个较低源整体取值 | [`availableModels`](#availablemodels)、[`allowedMcpServers`](#allowedmcpservers)、[`strictKnownMarketplaces`](#strictknownmarketplaces)、[`allowedChannelPlugins`](#allowedchannelplugins) 和 [`fallbackModel`](#fallbackmodel) 链 |6450| Restriction allowlists | 从设置它的最高源整体取值，不从较低源添加条目。当最高源未设置时，从下一个较低源整体取值 | [`availableModels`](#availablemodels)、[`allowedMcpServers`](#allowedmcpservers)、[`allowedProviders`](#allowedproviders)、[`strictKnownMarketplaces`](#strictknownmarketplaces)、[`allowedChannelPlugins`](#allowedchannelplugins) 和 [`fallbackModel`](#fallbackmodel) 链 |

6405| Values taken whole | 从设置它的最高源整体取值，不合并来自较低源的条目或字段。当最高源未设置时，从下一个较低源整体取值 | [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs)、[`sandbox.ripgrep`](#sandbox-ripgrep) |6451| Values taken whole | 从设置它的最高源整体取值，不合并来自较低源的条目或字段。当最高源未设置时，从下一个较低源整体取值 | [`sandbox.credentials.awsPairs`](#sandbox-credentials-awspairs)、[`sandbox.ripgrep`](#sandbox-ripgrep) |

6407| Read from the highest-priority source only | 仅从携带策略密钥的最高优先级源读取密钥，因此即使最高源未设置任何值，较低源的值也会被忽略 | [`apiKeyHelper`](#apikeyhelper)、[`awsAuthRefresh`](#awsauthrefresh)、[`awsCredentialExport`](#awscredentialexport)、[`gcpAuthRefresh`](#gcpauthrefresh)、[`otelHeadersHelper`](#otelheadershelper)、`proxyAuthHelper`、[`forceLoginOrgUUID`](#forceloginorguuid)、[`forceLoginMethod`](#forceloginmethod) 的 `"claudeai"` 和 `"console"` 值、[`parentSettingsBehavior`](#parentsettingsbehavior)、[`modelPicker`](#modelpicker)、[`policyHelper`](#policyhelper)、[`permissions.defaultMode`](#permissions-defaultmode) |6453| Read from the highest-priority source only | 仅从携带策略密钥的最高优先级源读取密钥，因此即使最高源未设置任何值，较低源的值也会被忽略 | [`apiKeyHelper`](#apikeyhelper)、[`awsAuthRefresh`](#awsauthrefresh)、[`awsCredentialExport`](#awscredentialexport)、[`gcpAuthRefresh`](#gcpauthrefresh)、[`otelHeadersHelper`](#otelheadershelper)、`proxyAuthHelper`、[`forceLoginOrgUUID`](#forceloginorguuid)、[`forceLoginMethod`](#forceloginmethod) 的 `"claudeai"` 和 `"console"` 值、[`parentSettingsBehavior`](#parentsettingsbehavior)、[`modelPicker`](#modelpicker)、[`policyHelper`](#policyhelper)、[`permissions.defaultMode`](#permissions-defaultmode) |

6415* **[`policyHelper`](#policyhelper)**: Claude Code 仅在携带策略密钥的最高源是 MDM 策略或托管设置文件时才接受它，因此在服务器管理的设置下它不适用。6461* **[`policyHelper`](#policyhelper)**: Claude Code 仅在携带策略密钥的最高源是 MDM 策略或托管设置文件时才接受它，因此在服务器管理的设置下它不适用。

6416* **[`modelOverrides`](#modeloverrides)**: 与 `availableModels` 配对。Claude Code 从设置它的最高源取值 `modelOverrides`，除非较高源设置 `availableModels` 而不设置 `modelOverrides`。在这种情况下，它忽略来自每个源的 `modelOverrides`。6462* **[`modelOverrides`](#modeloverrides)**: 与 `availableModels` 配对。Claude Code 从设置它的最高源取值 `modelOverrides`，除非较高源设置 `availableModels` 而不设置 `modelOverrides`。在这种情况下，它忽略来自每个源的 `modelOverrides`。

6417* **[`forceLoginGatewayUrl`](#forcelogingatewayurl)、[`gatewayInternalNetworks`](#gatewayinternalnetworks) 和 [`forceLoginMethod`](#forceloginmethod) 的 `"gateway"` 值**: Claude Code 从不从服务器管理的设置读取它们中的任何一个，因此那里的值既不适用也不隐藏在 MDM 策略或托管设置文件中设置的值。在机器上的管理员源中，仅携带策略密钥的最高排名源提供它们，无论是否也存在服务器管理的设置。6463* **[`forceLoginGatewayUrl`](#forcelogingatewayurl)、[`gatewayInternalNetworks`](#gatewayinternalnetworks) 和 [`forceLoginMethod`](#forceloginmethod) 的 `"gateway"` 值**: Claude Code 从不从服务器管理的设置读取它们中的任何一个，因此那里的值既不适用也不隐藏在 MDM 策略或托管设置文件中设置的值。在机器上的管理员源中，仅携带策略密钥的最高排名源提供它们，无论是否也存在服务器管理的设置。

6464* **[`allowedProviders`](#allowedproviders)**: 在表格的规则之后，机器自己的列表仍然限制结果，如其条目的 Scope 注释所述。

6418 6465

6419要确认机器上合并了哪些源，请运行 `/status` 并[读取 `Setting sources` 行](/docs/zh-CN/managed-settings#read-the-source-in-/status)。6466要确认机器上合并了哪些源，请运行 `/status` 并[读取 `Setting sources` 行](/docs/zh-CN/managed-settings#read-the-source-in-/status)。

6420 6467

skills.md +1 −1

Details

740 740

741* **工作目录**：Claude Code 在会话 shell 的当前工作目录中运行每个命令。当 Claude 运行 `cd` 时，该目录会移动。在必须每次都以相同方式解析的路径中使用 [`${CLAUDE_SKILL_DIR}` 或 `${CLAUDE_PROJECT_DIR}`](#available-string-substitutions)。741* **工作目录**：Claude Code 在会话 shell 的当前工作目录中运行每个命令。当 Claude 运行 `cd` 时，该目录会移动。在必须每次都以相同方式解析的路径中使用 [`${CLAUDE_SKILL_DIR}` 或 `${CLAUDE_PROJECT_DIR}`](#available-string-substitutions)。

742* **stderr**：使用默认的 `bash` shell，Claude Code 将 stderr 合并到 stdout。命令写入 stderr 的任何内容都会出现在注入的文本中。742* **stderr**：使用默认的 `bash` shell，Claude Code 将 stderr 合并到 stdout。命令写入 stderr 的任何内容都会出现在注入的文本中。

743* **超时**：每个命令在 Bash 工具的默认 2 分钟[超时](/docs/zh-CN/tools-reference#timeout-and-output-limits)下运行。当 Bash 工具[将超时的命令移到后台](/docs/zh-CN/tools-reference#background-commands)时，技能仍然呈现。注入的文本报告移动并命名后台任务和收集命令输出的文件。当命令是 Bash 工具从不自动后台化的命令之一时，Claude Code 在超时时杀死它。该失败[中止调用](#when-an-injected-command-fails)。743* **超时**：每个命令在 Bash 工具的默认 2 分钟[超时](/docs/zh-CN/tools-reference#timeout-and-output-limits)下运行。当 Bash 工具[将超时的命令移到后台](/docs/zh-CN/tools-reference#foreground-commands-that-move-to-the-background)时，技能仍然呈现。注入的文本报告移动并命名后台任务和收集命令输出的文件。当命令是 Bash 工具从不自动后台化的命令之一时，Claude Code 在超时时杀死它。该失败[中止调用](#when-an-injected-command-fails)。

744* **输出大小**：超过 Bash 工具内联上限的输出作为文件路径加短预览到达，而不是截断的文本。[输出限制](/docs/zh-CN/tools-reference#output-limits)涵盖上限以及如何调整每个边界。744* **输出大小**：超过 Bash 工具内联上限的输出作为文件路径加短预览到达，而不是截断的文本。[输出限制](/docs/zh-CN/tools-reference#output-limits)涵盖上限以及如何调整每个边界。

745 745

746PowerShell 工具对它运行的命令应用相同的超时、后台化和输出上限行为。有关其具体信息，请参阅 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)部分。746PowerShell 工具对它运行的命令应用相同的超时、后台化和输出上限行为。有关其具体信息，请参阅 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)部分。

statusline.md +7 −7

Details

20这是一个[多行状态行](#display-multiple-lines)的示例，它在第一行显示 git 信息，在第二行显示颜色编码的上下文栏。20这是一个[多行状态行](#display-multiple-lines)的示例，它在第一行显示 git 信息，在第二行显示颜色编码的上下文栏。

21 21

22<Frame>22<Frame>

23 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-multiline.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=60f11387658acc9ff75158ae85f2ac87" alt="一个多行状态行，显示第一行上的模型名称、目录、git 分支，第二行上的上下文使用进度条、成本和持续时间" width="776" height="212" data-path="images/statusline-multiline.png" />23 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-multiline.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=a9d0a2fe8e446d80b1abc46da3f93270" alt="一个多行状态行，显示第一行上的模型名称、目录、git 分支，第二行上的上下文使用进度条、成本和持续时间" width="1224" height="262" data-path="images/statusline-multiline.png" />

24</Frame>24</Frame>

25 25

26本页面介绍了[设置基本状态行](#set-up-a-status-line)，解释了[数据如何从 Claude Code 流向你的脚本](#how-status-lines-work)，列出了[你可以显示的所有字段](#available-data)，并提供了[常见模式的现成示例](#examples)，如 git 状态、成本跟踪和进度条。26本页面介绍了[设置基本状态行](#set-up-a-status-line)，解释了[数据如何从 Claude Code 流向你的脚本](#how-status-lines-work)，列出了[你可以显示的所有字段](#available-data)，并提供了[常见模式的现成示例](#examples)，如 git 状态、成本跟踪和进度条。

93这些示例使用 Bash 脚本，在 macOS 和 Linux 上工作。在 Windows 上，请参阅[Windows 配置](#windows-configuration)了解 PowerShell 和 Git Bash 示例。93这些示例使用 Bash 脚本，在 macOS 和 Linux 上工作。在 Windows 上，请参阅[Windows 配置](#windows-configuration)了解 PowerShell 和 Git Bash 示例。

94 94

95<Frame>95<Frame>

96 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-quickstart.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=696445e59ca0059213250651ad23db6b" alt="一个状态行，显示模型名称、目录和上下文百分比" width="726" height="164" data-path="images/statusline-quickstart.png" />96 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-quickstart.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=88a7eab9c1038dd098ee8e284d96b7e6" alt="一个状态行，显示模型名称、目录和上下文百分比" width="1224" height="224" data-path="images/statusline-quickstart.png" />

97</Frame>97</Frame>

98 98

99<Steps>99<Steps>

444显示当前模型和上下文窗口使用情况，带有可视进度条。每个脚本从 stdin 读取 JSON，提取 `used_percentage` 字段，并构建一个 10 字符的栏，其中填充的块（▓）代表使用情况：444显示当前模型和上下文窗口使用情况，带有可视进度条。每个脚本从 stdin 读取 JSON，提取 `used_percentage` 字段，并构建一个 10 字符的栏，其中填充的块（▓）代表使用情况：

445 445

446<Frame>446<Frame>

447 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-context-window-usage.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=15b58ab3602f036939145dde3165c6f7" alt="一个状态行，显示模型名称和带有百分比的进度条" width="448" height="152" data-path="images/statusline-context-window-usage.png" />447 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-context-window-usage.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=f3918a549912dc47e90f2b69e68bc847" alt="一个状态行，显示模型名称和带有百分比的进度条" width="1224" height="224" data-path="images/statusline-context-window-usage.png" />

448</Frame>448</Frame>

449 449

450<CodeGroup>450<CodeGroup>

513显示 git 分支，带有暂存和修改文件的颜色编码指示器。此脚本使用[ANSI 转义码](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors)表示终端颜色：`\033[32m` 是绿色，`\033[33m` 是黄色，`\033[0m` 重置为默认值。513显示 git 分支，带有暂存和修改文件的颜色编码指示器。此脚本使用[ANSI 转义码](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors)表示终端颜色：`\033[32m` 是绿色，`\033[33m` 是黄色，`\033[0m` 重置为默认值。

514 514

515<Frame>515<Frame>

516 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-git-context.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=e656f34f90d1d9a1d0e220988914345f" alt="一个状态行，显示模型、目录、git 分支和暂存和修改文件的彩色指示器" width="742" height="178" data-path="images/statusline-git-context.png" />516 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-git-context.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=f13c190724d9ec7188c17cd2f98b7bf4" alt="一个状态行，显示模型、目录、git 分支和暂存和修改文件的彩色指示器" width="1224" height="224" data-path="images/statusline-git-context.png" />

517</Frame>517</Frame>

518 518

519每个脚本检查当前目录是否是 git 存储库，计算暂存和修改文件，并显示颜色编码的指示器：519每个脚本检查当前目录是否是 git 存储库，计算暂存和修改文件，并显示颜色编码的指示器：

611每个脚本将成本格式化为货币并将毫秒转换为分钟和秒：611每个脚本将成本格式化为货币并将毫秒转换为分钟和秒：

612 612

613<Frame>613<Frame>

614 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-cost-tracking.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=e3444a51fe6f3440c134bd5f1f08ad29" alt="一个状态行，显示模型名称、会话成本和持续时间" width="588" height="180" data-path="images/statusline-cost-tracking.png" />614 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-cost-tracking.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=925f7024c3b38be0f0eca63564bfb52f" alt="一个状态行，显示模型名称、会话成本和持续时间" width="1224" height="224" data-path="images/statusline-cost-tracking.png" />

615</Frame>615</Frame>

616 616

617<CodeGroup>617<CodeGroup>

672你的脚本可以输出多行来创建更丰富的显示。672你的脚本可以输出多行来创建更丰富的显示。

673 673

674<Frame>674<Frame>

675 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-multiline.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=60f11387658acc9ff75158ae85f2ac87" alt="一个多行状态行，显示第一行上的模型名称、目录、git 分支，第二行上的上下文使用进度条、成本和持续时间" width="776" height="212" data-path="images/statusline-multiline.png" />675 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-multiline.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=a9d0a2fe8e446d80b1abc46da3f93270" alt="一个多行状态行，显示第一行上的模型名称、目录、git 分支，第二行上的上下文使用进度条、成本和持续时间" width="1224" height="262" data-path="images/statusline-multiline.png" />

676</Frame>676</Frame>

677 677

678此示例结合了几种技术：基于阈值的颜色（70% 以下为绿色，70-89% 为黄色，90%+ 为红色）、进度条和 git 分支信息。每个 `print` 或 `echo` 语句创建单独的行：678此示例结合了几种技术：基于阈值的颜色（70% 以下为绿色，70-89% 为黄色，90%+ 为红色）、进度条和 git 分支信息。每个 `print` 或 `echo` 语句创建单独的行：

781此示例创建指向你的 GitHub 存储库的可点击链接。按住 Cmd（macOS）或 Ctrl（Windows/Linux）并单击以在浏览器中打开链接。781此示例创建指向你的 GitHub 存储库的可点击链接。按住 Cmd（macOS）或 Ctrl（Windows/Linux）并单击以在浏览器中打开链接。

782 782

783<Frame>783<Frame>

784 <img src="https://mintcdn.com/claude-code/nibzesLaJVh4ydOq/images/statusline-links.png?fit=max&auto=format&n=nibzesLaJVh4ydOq&q=85&s=4bcc6e7deb7cf52f41ab85a219b52661" alt="一个状态行，显示指向 GitHub 存储库的可点击链接" width="726" height="198" data-path="images/statusline-links.png" />784 <img src="https://mintcdn.com/claude-code/HDAmBwgbrZVk0pOt/images/statusline-links.png?fit=max&auto=format&n=HDAmBwgbrZVk0pOt&q=85&s=4778a144a28cb498c99d5fa018bb374a" alt="一个状态行，显示指向 GitHub 存储库的可点击链接" width="1224" height="224" data-path="images/statusline-links.png" />

785</Frame>785</Frame>

786 786

787每个脚本获取 git 远程 URL，将 SSH 格式转换为 HTTPS，并将存储库名称包装在 OSC 8 转义码中。Bash 版本使用 `printf '%b'`，它比 `echo -e` 更可靠地跨不同 shell 解释反斜杠转义：787每个脚本获取 git 远程 URL，将 SSH 格式转换为 HTTPS，并将存储库名称包装在 OSC 8 转义码中。Bash 版本使用 `printf '%b'`，它比 `echo -e` 更可靠地跨不同 shell 解释反斜杠转义：

third-party-integrations.md +2 −0

Details

253 253

254安全团队可以配置托管权限，定义 Claude Code 允许和不允许做什么，这不能被本地配置覆盖。[了解更多](/docs/zh-CN/security)。254安全团队可以配置托管权限，定义 Claude Code 允许和不允许做什么，这不能被本地配置覆盖。[了解更多](/docs/zh-CN/security)。

255 255

256要限制托管机器可以使用的这些部署选项，请在托管设置中设置 [`allowedProviders`](/docs/zh-CN/settings-reference#allowedproviders)。例如，`["bedrock"]` 仅允许 Amazon Bedrock；同时启用 Mantle 端点的 Bedrock 队列也列出 `"mantle"`。该条目说明哪些端点变量还需要托管 `env` 固定。需要 Claude Code v2.1.285 或更高版本。

257

256<h3 id="leverage-mcp-for-integrations">258<h3 id="leverage-mcp-for-integrations">

257 利用 MCP 进行集成259 利用 MCP 进行集成

258</h3>260</h3>

tools-reference.md +20 −5

Details

174* `BASH_DEFAULT_TIMEOUT_MS` — 当 Claude 不传递超时时的默认值；开箱即用为两分钟174* `BASH_DEFAULT_TIMEOUT_MS` — 当 Claude 不传递超时时的默认值；开箱即用为两分钟

175* `BASH_MAX_TIMEOUT_MS` — 使用默认值，设置上限以限制 Claude 请求的任何内容：有效上限是两者中较大的，开箱即用为十分钟175* `BASH_MAX_TIMEOUT_MS` — 使用默认值，设置上限以限制 Claude 请求的任何内容：有效上限是两者中较大的，开箱即用为十分钟

176 176

177对于 Claude 在后台启动的命令，`timeout` 改为设置命令在那里可以运行多长时间，具有在[后台命令](#background-commands)下描述的单独默认值和最大值。[PowerShell 工具](#powershell-tool)遵循相同的超时规则并读取相同的两个变量。177对于 Claude 在后台启动的命令，`timeout` 改为设置命令在那里可以运行多长时间，具有在[后台命令时间限制](#time-limit-for-background-commands)下描述的单独默认值和最大值。[PowerShell 工具](#powershell-tool)遵循相同的超时规则并读取相同的两个变量。

178 178

179<h4 id="output-limits">179<h4 id="output-limits">

180 输出限制180 输出限制

199 199

200对于长时间运行的进程（例如开发服务器或监视构建），Claude 可以设置 `run_in_background: true` 以将命令作为后台任务启动并在其运行时继续工作。使用 `/tasks` 列出和停止后台任务。在您从那里停止一个后，或从连接的客户端（例如桌面应用）停止，Claude 继续而不是等待。如果子代理启动了命令，则是该子代理继续。200对于长时间运行的进程（例如开发服务器或监视构建），Claude 可以设置 `run_in_background: true` 以将命令作为后台任务启动并在其运行时继续工作。使用 `/tasks` 列出和停止后台任务。在您从那里停止一个后，或从连接的客户端（例如桌面应用）停止，Claude 继续而不是等待。如果子代理启动了命令，则是该子代理继续。

201 201

202[前台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)启动的命令在该子代理的运行结束时停止，无论它是完成、失败还是被中断。主对话或后台子代理启动的命令在最终响应后继续运行，直到它退出、被停止或达到其时间限制。在使用 `-p` 标志的非交互模式下，[后台命令在运行的最终结果后不久结束](/docs/zh-CN/headless#background-tasks-at-exit)。202<h4 id="when-a-background-command-stops">

203 后台命令何时停止

204</h4>

205

206[前台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)启动的命令在该子代理的运行结束时停止，无论它是完成、失败还是被中断。主对话或后台子代理启动的命令在最终响应后继续运行，直到它退出、被停止或达到其[时间限制](#time-limit-for-background-commands)。在使用 `-p` 标志的非交互模式下，[后台命令在运行的最终结果后不久结束](/docs/zh-CN/headless#background-tasks-at-exit)。

207

208<h4 id="time-limit-for-background-commands">

209 后台命令的时间限制

210</h4>

203 211

204后台 Bash 和 PowerShell 命令有时间限制，从命令进入后台的时刻开始计算：212后台 Bash 和 PowerShell 命令有时间限制，从命令进入后台的时刻开始计算：

205 213

206* Claude 在后台启动的命令获得 30 分钟，或 Claude 使用 `run_in_background` 传递的 `timeout`，最多 2 小时214* Claude 在后台启动的命令获得 30 分钟，或 Claude 使用 `run_in_background` 传递的 `timeout`，最多 2 小时

207* 在前台启动然后移到后台的命令，例如使用 `Ctrl+B` 或在其超时时，从移动时获得 30 分钟215* 在前台启动然后移到后台的命令，例如使用 `Ctrl+B` 或在其超时时，从移动时获得 30 分钟

208 216

217当后台命令达到其时间限制时，Claude Code 停止它并告诉 Claude 原因，Claude 可以使用更长的 `timeout` 重新启动命令，如果工作仍然需要的话。停止通知读作 `Background command "<description>" was stopped after reaching its background time limit`。

218

219<h4 id="raise-the-time-limit-for-background-commands">

220 提高后台命令的时间限制

221</h4>

222

209两个[环境变量](/docs/zh-CN/env-vars)提高这些限制，对于 Bash 和 PowerShell 命令都是如此。两者都采用毫秒，都不能缩短限制：较低的值保留 30 分钟的默认值和 2 小时的最大值。223两个[环境变量](/docs/zh-CN/env-vars)提高这些限制，对于 Bash 和 PowerShell 命令都是如此。两者都采用毫秒，都不能缩短限制：较低的值保留 30 分钟的默认值和 2 小时的最大值。

210 224

211* 将 `BASH_DEFAULT_TIMEOUT_MS` 设置为高于 `1800000` 以用该值替换 30 分钟的默认值，既适用于 Claude 启动的没有 `timeout` 的命令，也适用于移动的命令225* 将 `BASH_DEFAULT_TIMEOUT_MS` 设置为高于 `1800000` 以用该值替换 30 分钟的默认值，既适用于 Claude 启动的没有 `timeout` 的命令，也适用于移动的命令

212* 将 `BASH_MAX_TIMEOUT_MS` 设置为高于 `7200000` 以将 2 小时的最大值提高到该值。将 `BASH_DEFAULT_TIMEOUT_MS` 设置为高于 `7200000` 以相同方式提高最大值226* 将 `BASH_MAX_TIMEOUT_MS` 设置为高于 `7200000` 以将 2 小时的最大值提高到该值。将 `BASH_DEFAULT_TIMEOUT_MS` 设置为高于 `7200000` 以相同方式提高最大值

213 227

214当后台命令达到其时间限制时，Claude Code 停止它并告诉 Claude 原因，Claude 可以使用更长的 `timeout` 重新启动命令，如果工作仍然需要的话。停止通知读作 `Background command "<description>" was stopped after reaching its background time limit`。228<h4 id="foreground-commands-that-move-to-the-background">

229 移到后台的前台命令

230</h4>

215 231

216当前台命令在完成前达到其超时时，Claude Code 会将其移到后台而不是停止它，除非命令以 `sleep` 开头。移动的命令的时间限制从移动时开始计算，前台子代理的移动命令仍然在该子代理的运行结束时停止。232当前台命令在完成前达到其超时时，Claude Code 会将其移到后台而不是停止它，除非命令以 `sleep` 开头。移动的命令的[时间限制](#time-limit-for-background-commands)从移动时开始计算，前台子代理的移动命令仍然在该子代理的运行结束时停止。

217 233

218设置 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/zh-CN/env-vars#variables) 禁用自动后台处理以及其余后台任务功能。234设置 [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`](/docs/zh-CN/env-vars#variables) 禁用自动后台处理以及其余后台任务功能。

219 235

246无论您列出什么，这些规则适用：262无论您列出什么，这些规则适用：

247 263

248* **未知名称**：Claude Code 忽略它不识别的名称264* **未知名称**：Claude Code 忽略它不识别的名称

249* **Bash、PowerShell 和 Monitor**：Claude Code 无论您列出什么，都将 Bash、PowerShell 和 Monitor 工具命令保持在上限以下

250* **变量未设置**：Claude Code 从 Anthropic 从服务器传递的配置中获取其他限制类型的集合，该集合可能随时间变化，因此当您需要不变的集合时设置变量265* **变量未设置**：Claude Code 从 Anthropic 从服务器传递的配置中获取其他限制类型的集合，该集合可能随时间变化，因此当您需要不变的集合时设置变量

251* **权限门控 hooks**：即使每种类型都受限，Claude Code 也会从上限中排除可以阻止或更改操作结果的 hook，以及任何此类 hook 调用的 MCP 服务器，因此内核杀死权限门控 hook 不能允许它阻止的操作266* **权限门控 hooks**：即使每种类型都受限，Claude Code 也会从上限中排除可以阻止或更改操作结果的 hook，以及任何此类 hook 调用的 MCP 服务器，因此内核杀死权限门控 hook 不能允许它阻止的操作

252 267

ultrareview.md +1 −1

Details

66 66

67在 PR 模式下，云沙箱直接从主机克隆拉取请求，而不是捆绑您的本地工作树。PR 模式适用于 `github.com` 上的存储库以及 Owner 已连接到 Claude Code 的 [GitHub Enterprise Server](/docs/zh-CN/github-enterprise-server) 实例。67在 PR 模式下，云沙箱直接从主机克隆拉取请求，而不是捆绑您的本地工作树。PR 模式适用于 `github.com` 上的存储库以及 Owner 已连接到 Claude Code 的 [GitHub Enterprise Server](/docs/zh-CN/github-enterprise-server) 实例。

68 68

69对于 `github.com` 上的存储库，沙箱使用连接到您的 Claude 账户的 GitHub 账户进行克隆，因此该账户必须能够读取 PR 的存储库。Claude Code 在创建云会话之前检查这一点，除非您已设置 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-CN/env-vars#variables)，并在[未连接账户](/docs/zh-CN/errors#no-github-account-is-connected-to-your-claude-account)或[账户无法看到存储库](/docs/zh-CN/errors#your-connected-github-account-cant-see-the-repository)时拒绝启动；拒绝会说明修复方法。在 v2.1.248 之前，Claude Code 在启动前不检查这一点。69对于 `github.com` 上的存储库，沙箱使用连接到您的 Claude 账户的 GitHub 账户进行克隆，因此该账户必须能够读取 PR 的存储库。

70 70

71运行 [`/web-setup`](/docs/zh-CN/web-quickstart#connect-from-your-terminal) 将您的 GitHub CLI 登录连接到您的 Claude 账户。71运行 [`/web-setup`](/docs/zh-CN/web-quickstart#connect-from-your-terminal) 将您的 GitHub CLI 登录连接到您的 Claude 账户。

72 72

vs-code.md +25 −5

Details

58 58

59 * **活动栏**：点击左侧边栏中的 Spark 图标以打开会话列表。点击任何会话以在您的[首选位置](#extension-settings)中打开它，或开始新的会话。此图标在活动栏中始终可见。59 * **活动栏**：点击左侧边栏中的 Spark 图标以打开会话列表。点击任何会话以在您的[首选位置](#extension-settings)中打开它，或开始新的会话。此图标在活动栏中始终可见。

60 * **命令面板**：`Cmd+Shift+P`（Mac）或 `Ctrl+Shift+P`（Windows/Linux），输入"Claude Code"，然后选择一个选项，如"在新选项卡中打开"60 * **命令面板**：`Cmd+Shift+P`（Mac）或 `Ctrl+Shift+P`（Windows/Linux），输入"Claude Code"，然后选择一个选项，如"在新选项卡中打开"

61 * **状态栏**：如果您已将 [`preferredLocation`](#extension-settings) 设置为 `sidebar`，或使用**Claude Code: Open in Side Bar** 打开了 Claude，请点击窗口右下角的 **✻ Claude Code**。即使没有打开文件，这也有效。61 * **状态栏**：点击窗口右下角的 **✻ Claude Code**。即使没有打开文件，这也有效。

62 62

63 您可以拖动 Claude 面板以在 VS Code 中的任何位置重新定位它。有关详细信息，请参阅[自定义您的工作流](#customize-your-workflow)。63 您可以拖动 Claude 面板以在 VS Code 中的任何位置重新定位它。有关详细信息，请参阅[自定义您的工作流](#customize-your-workflow)。

64 </Step>64 </Step>

362 362

363在 Plugins 选项卡中：363在 Plugins 选项卡中：

364 364

365* **已安装的插件**显示在顶部，带有切换开关以启用或禁用它们365* **已安装的插件**显示在顶部，带有切换开关以启用或禁用它们。

366 * 如果您关闭项目的共享 `.claude/settings.json` 启用的插件，扩展会先询问：**为我禁用**仅为您关闭它，而**为所有人禁用**会更改共享文件。

366* **可用插件**来自您配置的市场，显示在下方367* **可用插件**来自您配置的市场，显示在下方

367* 搜索以按名称或描述过滤插件368* 搜索以按名称或描述过滤插件

368* 点击任何可用插件上的**安装**369* 点击任何可用插件上的**安装**

373* **为此项目安装**：与项目协作者共享（项目范围）374* **为此项目安装**：与项目协作者共享（项目范围）

374* **本地安装**：仅供您使用，仅在此存储库中（本地范围）375* **本地安装**：仅供您使用，仅在此存储库中（本地范围）

375 376

377安装完成后，表单会要求设置任何尚未设置的插件的 [configuration options](/docs/zh-CN/plugins/components#user-configuration)。要稍后查看或更改选项，请点击插件行上的齿轮图标。

378

379敏感文本字段被掩盖，您之前保存的密钥显示 **(unchanged)**。将字段留空以保持保存的值。

380

381保存更改后，打开的会话会重新加载其插件，对话框显示**重启 Claude 以应用插件更改**。

382

383<h3 id="uninstall-plugins">

384 卸载插件

385</h3>

386

387每个已安装的行都标明了它安装的 [scope](/docs/zh-CN/plugins/install#choose-an-install-scope)。要卸载该安装，请点击该行的垃圾桶图标。暗淡的垃圾桶图标标记您无法从此工作区卸载的行，例如您的组织管理的插件或为另一个项目安装的插件。

388

389扩展在两种情况下会先询问：

390

391* **项目的共享 `.claude/settings.json` 启用的插件**：选择**为我禁用**，这会为您的协作者保留插件安装，或**为所有人卸载**，这会使用 [`--keep-data`](/docs/zh-CN/plugins/cli-reference#what-an-uninstall-deletes-and-keeps) 删除项目的安装，因此插件的保存数据目录会保留。如果您已经为自己关闭了插件，垃圾桶图标会删除您自己的安装而不会提问。

392* **否则，最后一个具有保存数据的插件安装**：选择是否保留或删除数据；**保留**是默认选项

393

376<h3 id="share-a-plugin-install-link">394<h3 id="share-a-plugin-install-link">

377 分享插件安装链接395 分享插件安装链接

378</h3>396</h3>

407 425

408* 输入 GitHub 仓库、URL 或本地路径以添加新市场426* 输入 GitHub 仓库、URL 或本地路径以添加新市场

409* 点击刷新图标以更新市场的插件列表427* 点击刷新图标以更新市场的插件列表

410* 点击垃圾桶图标以删除市场428* 点击垃圾桶图标以删除市场。删除它会 [卸载您从中安装的每个插件](/docs/zh-CN/plugins/install#manage-marketplaces)，因此确认会首先列出这些插件

429

430您在对话框中所做的插件更改会立即应用到该 VS Code 窗口中打开的 Claude Code 会话。

411 431

412您在对话框中所做的插件更改会立即应用到该 VS Code 窗口中打开的 Claude Code 会话。如果您打开对话框的会话无法重新加载其插件，对话框会提供重试或在该会话中重启 Claude 的选项。432如果您打开对话框的会话无法重新加载其插件，对话框会提供重试或在该会话中重启 Claude 的选项。

413 433

414<Note>434<Note>

415 VS Code 中的插件管理在底层使用相同的 CLI 命令。您在扩展中配置的插件和市场也可在 CLI 中使用，反之亦然。435 VS Code 中的插件管理在底层使用相同的 CLI 命令。您在扩展中配置的插件和市场也可在 CLI 中使用，反之亦然。

7904. **禁用冲突的扩展程序**：临时禁用其他 AI 扩展程序（Cline、Continue 等）8104. **禁用冲突的扩展程序**：临时禁用其他 AI 扩展程序（Cline、Continue 等）

7915. **检查工作区信任**：该扩展程序在受限模式下不起作用8115. **检查工作区信任**：该扩展程序在受限模式下不起作用

792 812

793或者，如果您已将 [`preferredLocation`](#extension-settings) 设置为 `sidebar`，或使用**Claude Code: Open in Side Bar** 打开了 Claude，请点击**状态栏**（右下角）中的"✻ Claude Code"。即使没有打开文件，这也能工作。您也可以使用**命令面板**（`Cmd+Shift+P` / `Ctrl+Shift+P`）并输入"Claude Code"。813或者，点击窗口右下角**状态栏**中的 **✻ Claude Code**。即使没有打开文件，这也能工作。您也可以使用**命令面板**（`Cmd+Shift+P` / `Ctrl+Shift+P`）并输入"Claude Code"。

794 814

795<h3 id="cmd-esc-does-nothing-on-macos">815<h3 id="cmd-esc-does-nothing-on-macos">

796 Cmd+Esc 在 macOS 上无效816 Cmd+Esc 在 macOS 上无效

worktrees.md +1 −1

Details

145* worktree 属于您未后台的 `--worktree` 会话，无论其年龄如何。145* worktree 属于您未后台的 `--worktree` 会话，无论其年龄如何。

146* 您自己使用 `git worktree add` 创建了 worktree，即使您随后在其中运行了 `--worktree <name>` 会话并后台了该会话。146* 您自己使用 `git worktree add` 创建了 worktree，即使您随后在其中运行了 `--worktree <name>` 会话并后台了该会话。

147 147

148Claude Code 将标记写入它使用 git 创建的每个 worktree 的 git 元数据中，扫描会保留任何没有标记的 worktree，包括 [`WorktreeCreate` hook](#non-git-version-control) 创建的 worktree。在 v2.1.246 之前，扫描没有检查标记，当旧的后台会话记录指向它时可能会删除您自己创建的 worktree。148Claude Code 将标记写入它使用 git 创建的每个 worktree 的 git 元数据中，扫描会保留任何没有标记的 worktree，包括 [`WorktreeCreate` hook](#non-git-version-control) 创建的 worktree。

149 149

150当代理运行时，Claude Code 在其 worktree 上持有 `git worktree lock`，以便并发清理无法删除它，当代理完成时释放锁。Claude Code 在为后台会话创建的 worktree 上持有相同的锁，同时会话运行，因此扫描会保留 worktree 并且 `git worktree remove` 拒绝删除它。150当代理运行时，Claude Code 在其 worktree 上持有 `git worktree lock`，以便并发清理无法删除它，当代理完成时释放锁。Claude Code 在为后台会话创建的 worktree 上持有相同的锁，同时会话运行，因此扫描会保留 worktree 并且 `git worktree remove` 拒绝删除它。

151 151

Documentation 2026-09-30 23:00 UTC to 2026-10-01 21:02 UTC