Documentation — Spybara

agent-sdk/modifying-system-prompts.md +2 −2

Details

126 126

127输出样式是一个 markdown 文件，包含用于元数据的 [frontmatter](/docs/zh-CN/output-styles#frontmatter)，后跟提示内容。将其保存到 `~/.claude/output-styles/` 以获得在每个项目中可用的用户级样式，或保存到你的存储库中的 `.claude/output-styles/` 以获得可以提交并与你的团队共享的项目级样式。127输出样式是一个 markdown 文件，包含用于元数据的 [frontmatter](/docs/zh-CN/output-styles#frontmatter)，后跟提示内容。将其保存到 `~/.claude/output-styles/` 以获得在每个项目中可用的用户级样式，或保存到你的存储库中的 `.claude/output-styles/` 以获得可以提交并与你的团队共享的项目级样式。

128 128

129自定义输出样式会排除 `claude_code` 预设的软件工程指令，并使用你自己的。要保留它们并在其上分层你的指令，请在 frontmatter 中设置 `keep-coding-instructions: true`。这些指令仅在 Claude Code 的完整系统提示中，因此该设置在较短系统提示的会话中无效，你可以使用 [`CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT`](/docs/zh-CN/env-vars#variables) 固定打开或关闭。当你的代理仍在进行软件工程工作时保留它们。当你完全替换角色时排除它们。129自定义输出样式会省略 `claude_code` 预设的软件工程指令，转而使用您自己的指令。要保留这些指令并在其上叠加您的指令，请在 frontmatter 中设置 `keep-coding-instructions: true`。这些指令仅存在于 Claude Code 的完整系统提示词中，因此在使用较短系统提示词的会话中，该设置不起作用；将 [`CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT`](/docs/zh-CN/env-vars#variables) 设置为 `0` 即可在任何模型上选择完整提示词。当您的 Agent 仍在执行软件工程工作时，请保留它们。当您要完全替换角色时，请省略它们。

130 130

131下面的示例定义了一个代码审查角色，它保留编码指令，因为审查代码仍然受益于 Claude Code 的安全和代码质量指导。将其保存为 `~/.claude/output-styles/code-reviewer.md` 以使其在项目中可用：131下面的示例定义了一个代码审查角色，它保留编码指令，因为审查代码仍然受益于 Claude Code 的安全和代码质量指导。将其保存为 `~/.claude/output-styles/code-reviewer.md` 以使其在项目中可用：

132 132

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

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

550| **自定义级别** | 仅添加 | 替换或扩展默认 | 仅添加 | 完全控制 |550| **自定义级别** | 仅添加 | 添加；可省略编码指令 | 仅添加 | 完全控制 |

553 553

agent-sdk/python.md +169 −168

Details

2768 工具输入/输出类型2768 工具输入/输出类型

2769</h2>2769</h2>

2770 2770

2771内置 Claude Code 工具的输入/输出 schema 文档。虽然 Python SDK 不将这些导出为类型，但它们代表消息中工具输入和输出的结构。2771内置 Claude Code 工具的输入/输出 schema 文档。虽然 Python SDK 不会将这些作为类型导出，但它们代表了消息中工具输入和输出的结构。

2772 2772

2773每个显示的输出是您从该工具的 [`UserMessage.tool_use_result`](#usermessage) 读取的值。键名完全按照 Claude Code 发出的方式出现。标注了 `| None` 并带有"present when"或"optional"注释的键在不适用时会被省略。2773下面展示的每个输出都是您从该工具的 [`UserMessage.tool_use_result`](#usermessage) 中读取的值。键名与 Claude Code 发出的完全一致。标注了 `| None` 并带有"present when"或"optional"注释的键，在不适用时会被省略。

2774 2774

2775<h3 id="agent">2775<h3 id="agent">

2776 Agent2776 Agent

2777</h3>2777</h3>

2778 2778

2779**工具名称：** `Agent`。之前的名称 `Task` 仍然被接受作为别名，初始化 [`SystemMessage`](#systemmessage) 中的 `tools` 列表为了向后兼容将此工具报告为 `Task`。2779**工具名称：** `Agent`。先前的名称 `Task` 仍作为别名被接受，并且为了向后兼容，init [`SystemMessage`](#systemmessage) 中的 `tools` 列表会将此工具报告为 `Task`。

2780 2780

2781**输入：**2781**输入：**

2782 2782

2783```python theme={null}2783```python theme={null}

2784{2784{

2785 "description": str, # 任务的简短描述（3-5 个单词）2785 "description": str, # 任务的简短描述（3-5 个词）

2786 "prompt": str, # Agent 要执行的任务2786 "prompt": str, # 要由 Agent 执行的任务

2787 "subagent_type": str | None, # 要使用的专门 Agent 的类型2787 "subagent_type": str | None, # 要使用的专用 Agent 类型

2790 "name": str | None, # 生成的 Agent 的名称2790 "run_in_background": bool | None, # Agent 默认在后台运行；设置为 False 可同步运行

2791 "team_name": str | None, # 已弃用；被忽略2791 "name": str | None, # 所生成 Agent 的名称

2794 "isolation": "worktree" | "remote" | None, # Agent 所做更改的隔离模式

2794}2795}

2795```2796```

2796 2797

2797启动一个新 Agent 来自主处理复杂的多步骤任务。2798启动一个新的 Agent 来自主处理复杂的多步骤任务。

2798 2799

~~2799**输出（状态：`"completed"`）：**~~2800**输出（status：`"completed"`）：**

2800 2801

2801```python theme={null}2802```python theme={null}

2802{2803{

2803 "status": "completed",2804 "status": "completed",

2804 "agentId": str, # 运行的 Agent 的 ID2805 "agentId": str, # 运行的 Agent 的 ID

2805 "agentType": str | None, # 处理任务的子代理类型2806 "agentType": str | None, # 处理该任务的子代理类型

2806 "content": [ # 结果内容块2807 "content": [ # 结果内容块

2807 {2808 {

2808 "type": "text",2809 "type": "text",

2810 "citations": list | None,2811 "citations": list | None,

2811 }2812 }

2812 ],2813 ],

2813 "resolvedModel": str | None, # 子代理启动时的模型2814 "resolvedModel": str | None, # 子代理启动时使用的模型

2814 "modelsUsed": list[str] | None, # 按顺序使用的模型，连续重复被折叠2815 "modelsUsed": list[str] | None, # 按顺序使用的模型，连续重复项已合并

2815 "totalToolUseCount": int, # Agent 进行的工具调用次数2816 "totalToolUseCount": int, # Agent 进行的工具调用次数

2816 "totalDurationMs": int, # 执行持续时间（毫秒）2817 "totalDurationMs": int, # 执行时长（毫秒）

2817 "totalTokens": int, # 来自最终 API 请求的 token 计数，不是整个运行2818 "totalTokens": int, # 来自最后一次 API 请求的 token 数，而非整个运行过程

2818 "usage": { # token 使用统计2819 "usage": { # token 使用统计

2819 "input_tokens": int,2820 "input_tokens": int,

2820 "output_tokens": int,2821 "output_tokens": int,

2829 "output_tokens_details": {"thinking_tokens": int | None} | None,2830 "output_tokens_details": {"thinking_tokens": int | None} | None,

2830 "fallback_credit": Any | None,2831 "fallback_credit": Any | None,

2831 },2832 },

2832 "toolStats": { # 运行的聚合工具活动2833 "toolStats": { # 本次运行的工具活动汇总

2833 "readCount": int,2834 "readCount": int,

2834 "searchCount": int,2835 "searchCount": int,

2835 "bashCount": int,2836 "bashCount": int,

2840 "frameCount": int | None,2841 "frameCount": int | None,

2841 } | None,2842 } | None,

2842 "prompt": str, # Agent 运行的提示词2843 "prompt": str, # Agent 运行的提示词

2843 "worktreePath": str | None, # 当 Claude Code 保留子代理的 worktree 时出现2844 "worktreePath": str | None, # 当 Claude Code 保留了子代理的 worktree 时存在

2844 "worktreeBranch": str | None, # 当 Claude Code 使用 git 创建该 worktree 时出现2845 "worktreeBranch": str | None, # 当 Claude Code 使用 git 创建了该 worktree 时存在

2845}2846}

2846```2847```

2847 2848

~~2848**输出（状态：`"async_launched"`）：**~~2849**输出（status：`"async_launched"`）：**

2849 2850

2850```python theme={null}2851```python theme={null}

2851{2852{

2852 "status": "async_launched",2853 "status": "async_launched",

2853 "isAsync": bool | None, # 后台启动时为 True2854 "isAsync": bool | None, # 后台启动时为 True

2854 "agentId": str, # 启动的 Agent 的 ID2855 "agentId": str, # 已启动 Agent 的 ID

2855 "description": str, # 任务描述2856 "description": str, # 任务描述

2856 "resolvedModel": str | None, # 后台转换时使用的模型2857 "resolvedModel": str | None, # 转入后台时正在使用的模型

2857 "modelsUsed": list[str] | None, # 后台转换前使用的模型，按顺序，连续重复被折叠2858 "modelsUsed": list[str] | None, # 转入后台之前按顺序使用的模型，连续重复项已合并

2858 "prompt": str, # Agent 运行的提示词2859 "prompt": str, # Agent 运行的提示词

2859 "outputFile": str, # Agent 输出被写入的文件路径2860 "outputFile": str, # 写入 Agent 输出的文件路径

2860 "canReadOutputFile": bool | None, # 输出文件是否可以直接读取2861 "canReadOutputFile": bool | None, # 是否可以直接读取输出文件

2861}2862}

2862```2863```

2863 2864

~~2864**输出（状态：`"remote_launched"`）：**~~2865**输出（status：`"remote_launched"`）：**

2865 2866

2866```python theme={null}2867```python theme={null}

2867{2868{

2868 "status": "remote_launched",2869 "status": "remote_launched",

2869 "taskId": str, # 分派任务的 ID2870 "taskId": str, # 已派发任务的 ID

2870 "sessionUrl": str, # 云端会话的链接2871 "sessionUrl": str, # 指向云端会话的链接

2871 "description": str, # 任务描述2872 "description": str, # 任务描述

2872 "prompt": str, # Agent 运行的提示词2873 "prompt": str, # Agent 运行的提示词

2873 "outputFile": str, # Agent 输出被写入的文件路径2874 "outputFile": str, # 写入 Agent 输出的文件路径

2874}2875}

2875```2876```

2876 2877

2877返回来自子代理的结果。输出在 `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 时的分支。2878返回子代理的结果。输出通过 `status` 字段进行区分：`"completed"` 表示已完成的任务，`"async_launched"` 表示后台任务，`"remote_launched"` 表示 Claude Code 派发到云端会话的任务，其中 `sessionUrl` 链接到该会话，`taskId` 用于标识该会话。如果 Claude Code [保留了子代理的隔离 worktree](/docs/zh-CN/worktrees#isolate-subagents-with-worktrees)，`completed` 变体上的 `worktreePath` 就是该 worktree 的位置；当 Claude Code 使用 git 创建该 worktree 时，`worktreeBranch` 是其分支。

2878 2879

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

2880 2881

2881Claude Code 从子代理的最终 API 请求而不是整个运行中填充 `usage` 和 `totalTokens`。当存在时，`usage` 中 `output_tokens_details` 下的 `thinking_tokens` 是该请求的输出 token 中属于思考 token 的数量。`output_tokens_details` 键需要 Python SDK v0.2.136 或更高版本，它捆绑了 Claude Code v2.1.228。`fallback_credit` 键需要 Python SDK v0.2.162 或更高版本，它捆绑了 Claude Code v2.1.285。2882Claude Code 根据子代理的最后一次 API 请求（而非整个运行过程）填充 `usage` 和 `totalTokens`。如果存在，`usage` 中 `output_tokens_details` 下的 `thinking_tokens` 表示该请求的输出 token 中属于思考 token 的数量。`output_tokens_details` 键需要 Python SDK v0.2.136 或更高版本，该版本捆绑了 Claude Code v2.1.228。`fallback_credit` 键需要 Python SDK v0.2.162 或更高版本，该版本捆绑了 Claude Code v2.1.285。

2882 2883

2883<h3 id="askuserquestion">2884<h3 id="askuserquestion">

2884 AskUserQuestion2885 AskUserQuestion

2886 2887

2887**工具名称：** `AskUserQuestion`2888**工具名称：** `AskUserQuestion`

2888 2889

2889在执行期间向用户提出澄清问题。见 [处理批准和用户输入](/docs/zh-CN/agent-sdk/user-input#handle-clarifying-questions) 了解使用详情。2890在执行过程中向用户提出澄清问题。有关用法详情，请参阅[处理批准和用户输入](/docs/zh-CN/agent-sdk/user-input#handle-clarifying-questions)。

2890 2891

2891**输入：**2892**输入：**

2892 2893

2895 "questions": [ # 要向用户提出的问题（1-4 个问题）2896 "questions": [ # 要向用户提出的问题（1-4 个问题）

2896 {2897 {

2897 "question": str, # 要向用户提出的完整问题2898 "question": str, # 要向用户提出的完整问题

2898 "header": str, # 显示为芯片/标签的非常简短的标签（最多 12 个字符）2899 "header": str, # 以标签/徽标形式显示的极短标签（最多 12 个字符）

2899 "options": [ # 可用的选择（2-4 个选项）2900 "options": [ # 可用选项（2-4 个选项）

2900 {2901 {

2901 "label": str, # 此选项的显示文本（1-5 个单词）2902 "label": str, # 此选项的显示文本（1-5 个词）

2902 "description": str, # 此选项含义的说明2903 "description": str, # 对此选项含义的说明

2903 "preview": str | None, # 当选项被聚焦时呈现的预览内容2904 "preview": str | None, # 选项获得焦点时渲染的预览内容

2904 }2905 }

2905 ],2906 ],

2906 "multiSelect": bool, # 设置为 true 以允许多个选择2907 "multiSelect": bool, # 设置为 true 以允许多选

2907 }2908 }

2908 ],2909 ],

2909 "answers": dict[str, str] | None,2910 "answers": dict[str, str] | None,

2910 # 由权限系统填充的用户答案。多选2911 # 由权限系统填充的用户答案。多选答案是

2911 # 答案是所选标签的逗号连接字符串；2912 # 所选标签以逗号连接而成的字符串；输入时也接受

2912 # 输入时接受标签列表并强制转换为该形式2913 # 标签列表，并会被转换为该形式

2913 "annotations": dict[str, dict] | None,2914 "annotations": dict[str, dict] | None,

2914 # 来自用户的按问题文本键入的每个问题注释。2915 # 用户针对每个问题的注释，以问题文本为键。

2915 # 每个值可以携带"preview"（所选选项的预览2916 # 每个值可以包含 "preview"（所选选项的预览

2916 # 内容）和"notes"（关于选择的自由文本注释）2917 # 内容）和 "notes"（关于所选内容的自由文本备注）

2917 "metadata": dict | None, # 分析元数据，例如 {"source": "remember"}；不向用户显示2918 "metadata": dict | None, # 分析元数据，例如 {"source": "remember"}；不会向用户显示

2918}2919}

2919```2920```

2920 2921

2922 2923

2923```python theme={null}2924```python theme={null}

2924{2925{

2925 "questions": [ # 被提出的问题2926 "questions": [ # 已提出的问题

2926 {2927 {

2927 "question": str,2928 "question": str,

2928 "header": str,2929 "header": str,

2933 "answers": dict[str, str], # 将问题文本映射到答案字符串2934 "answers": dict[str, str], # 将问题文本映射到答案字符串

2934 # 多选答案以逗号分隔2935 # 多选答案以逗号分隔

2935 "response": str | None,2936 "response": str | None,

2936 # 用户输入的自由形式回复而不是回答问题；当设置时，2937 # 用户未回答问题而是直接输入的自由回复；设置后，

2937 # Claude 收到"用户回复：..."而不是答案列表2938 # Claude 收到的是 "The user responded: ..." 而不是答案列表

2938 "annotations": dict[str, dict] | None, # 来自用户选择的每个问题"preview"和"notes"2939 "annotations": dict[str, dict] | None, # 用户所选内容中针对每个问题的 "preview" 和 "notes"

2939 "afkTimeoutMs": int | None, # 在用户不活动这么多毫秒后对话框自动解决时设置；用户回答时不存在2940 "afkTimeoutMs": int | None, # 当对话框因用户在这么多毫秒内无操作而自动结束时设置；用户作答时不存在

2940}2941}

2941```2942```

2942 2943

2946 2947

2947**工具名称：** `Bash`2948**工具名称：** `Bash`

2948 2949

2949关于设置前台上限的内容，见 [超时和输出限制](/docs/zh-CN/tools-reference#timeout-and-output-limits)。关于后台时间限制，见 [后台命令的时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)。2950有关前台上限由什么决定，请参阅[超时和输出限制](/docs/zh-CN/tools-reference#timeout-and-output-limits)。有关后台时间限制，请参阅[后台命令的时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)。

2950 2951

2951**输入：**2952**输入：**

2952 2953

2953```python theme={null}2954```python theme={null}

2954{2955{

2955 "command": str, # 要执行的命令2956 "command": str, # 要执行的命令

2956 "timeout": int | None, # 毫秒。前台：默认上限为 600000，更高的值被限制。使用 run_in_background（Claude Code v2.1.285 或更高版本）：后台时间限制，省略时为 1800000，上限为 7200000，除非提高2957 "timeout": int | None, # 毫秒。前台：默认上限为 600000，更高的值会被截断。使用 run_in_background 时（Claude Code v2.1.285 或更高版本）：后台时间限制，省略时为 1800000，除非调高，否则上限为 7200000

2957 "description": str | None, # 清晰、简洁的描述（5-10 个单词）2958 "description": str | None, # 清晰、简洁的描述（5-10 个词）

2958 "run_in_background": bool | None, # 设置为 true 以在后台运行2959 "run_in_background": bool | None, # 设置为 true 以在后台运行

2959}2960}

2960```2961```

2963 2964

2964```python theme={null}2965```python theme={null}

2965{2966{

2966 "stdout": str, # 命令的输出；stdout 和 stderr 合并到这个一个交错流中2967 "stdout": str, # 命令的输出；stdout 和 stderr 合并到这一个交错的流中

2967 "stderr": str, # 工具本身添加的通知，不是命令的 stderr2968 "stderr": str, # 工具本身添加的通知，而非命令的 stderr

2968 "interrupted": bool, # 命令是否被中断2969 "interrupted": bool, # 命令是否被中断

2969 "isImage": bool | None, # stdout 是否包含图像数据2970 "isImage": bool | None, # stdout 是否包含图像数据

2970 "backgroundTaskId": str | None, # 如果命令在后台运行，后台任务的 ID2971 "backgroundTaskId": str | None, # 命令在后台运行时的后台任务 ID

2971}2972}

2972```2973```

2973 2974

2977 2978

2978**工具名称：** `Monitor`2979**工具名称：** `Monitor`

2979 2980

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

2981 2982

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

2983 2984

2984**输入：**2985**输入：**

2985 2986

2986```python theme={null}2987```python theme={null}

2987{2988{

2988 "command": str | None, # Shell 脚本；每个 stdout 行是一个事件，退出结束监视2989 "command": str | None, # Shell 脚本；每行 stdout 是一个事件，退出即结束监视

2989 "ws": dict | None, # WebSocket 源：{"url": str, "protocols": list[str] | None}；每个文本帧是一个事件2990 "ws": dict | None, # WebSocket 来源：{"url": str, "protocols": list[str] | None}；每个文本帧是一个事件

2990 "description": str, # 在通知中显示的简短描述2991 "description": str, # 在通知中显示的简短描述

2991 "timeout_ms": int | None, # 截止时间（毫秒）（默认 300000，最大 3600000；有效截止时间最多为 1800000）2992 "timeout_ms": int | None, # 截止时间（毫秒）（默认 300000，最大 3600000；实际生效的截止时间最多为 1800000）

2992}2993}

2993```2994```

2994 2995

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

2998{2999{

2999 "taskId": str, # 后台监视任务的 ID3000 "taskId": str, # 后台监视任务的 ID

3000 "timeoutMs": int, # 监视的有效截止时间（毫秒）3001 "timeoutMs": int, # 监视实际生效的截止时间（毫秒）

3001 "persistent": bool | None, # False：每个监视都有一个截止时间3002 "persistent": bool | None, # False：每个监视都有截止时间

3002}3003}

3003```3004```

3004 3005

3014{3015{

3015 "file_path": str, # 要修改的文件的绝对路径3016 "file_path": str, # 要修改的文件的绝对路径

3016 "old_string": str, # 要替换的文本3017 "old_string": str, # 要替换的文本

3017 "new_string": str, # 替换为的文本3018 "new_string": str, # 用于替换的文本

3018 "replace_all": bool | None, # 替换所有出现（默认 False）3019 "replace_all": bool | None, # 替换所有匹配项（默认 False）

3019}3020}

3020```3021```

3021 3022

3025{3026{

3026 "filePath": str, # 被编辑的文件3027 "filePath": str, # 被编辑的文件

3027 "oldString": str, # 被替换的文本3028 "oldString": str, # 被替换的文本

3028 "newString": str, # 替换它的文本3029 "newString": str, # 替换后的文本

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

3030 "structuredPatch": [ # 更改的 diff hunks3031 "structuredPatch": [ # 此次更改的 diff 块

3031 {3032 {

3032 "oldStart": int,3033 "oldStart": int,

3033 "oldLines": int,3034 "oldLines": int,

3036 "lines": list[str],3037 "lines": list[str],

3037 }3038 }

3038 ],3039 ],

3039 "userModified": bool, # 用户是否在接受前更改了建议的编辑3040 "userModified": bool, # 用户在接受之前是否修改了提议的编辑

3040 "replaceAll": bool, # 是否替换了所有出现3041 "replaceAll": bool, # 是否替换了所有匹配项

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

3042 "filename": str,3043 "filename": str,

3043 "status": "modified" | "added",3044 "status": "modified" | "added",

3044 "additions": int,3045 "additions": int,

3045 "deletions": int,3046 "deletions": int,

3046 "changes": int,3047 "changes": int,

3047 "patch": str,3048 "patch": str,

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

3049 } | None,3050 } | None,

3050}3051}

3051```3052```

3066}3067}

3067```3068```

3068 3069

3069输出根据 Claude 读取的内容采用以下形状之一。检查 `type` 键来区分它们。3070根据 Claude 读取的内容，输出采用以下形状之一。请检查 `type` 键来区分它们。

3070 3071

~~3071**输出（type: `"text"`）：**~~3072**输出（type：`"text"`）：**

3072 3073

3073```python theme={null}3074```python theme={null}

3074{3075{

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

3078 "content": str, # 返回的内容3079 "content": str, # 返回的内容

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

3080 "startLine": int, # 内容开始的行号3081 "startLine": int, # 内容起始的行号

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

3082 "truncatedByTokenCap": bool | None, # 当整个文件读取超过 token 上限且内容是第一页时出现且为 True3083 "truncatedByTokenCap": bool | None, # 当整个文件的读取超出 token 上限且 content 为第一页时存在，值为 True

3083 },3084 },

3084}3085}

3085```3086```

3086 3087

~~3087**输出（type: `"image"`）：**~~3088**输出（type：`"image"`）：**

3088 3089

3089```python theme={null}3090```python theme={null}

3090{3091{

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

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

3096 "dimensions": { # 坐标映射的可选大小信息3097 "dimensions": { # 用于坐标映射的可选尺寸信息

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

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

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

3103}3104}

3104```3105```

3105 3106

~~3106**输出（type: `"notebook"`）：**~~3107**输出（type：`"notebook"`）：**

3107 3108

3108```python theme={null}3109```python theme={null}

3109{3110{

3110 "type": "notebook",3111 "type": "notebook",

3111 "file": {3112 "file": {

3112 "filePath": str, # 被读取的笔记本3113 "filePath": str, # 被读取的 notebook

3113 "cells": list, # 笔记本单元格3114 "cells": list, # Notebook 单元格

3114 },3115 },

3115}3116}

3116```3117```

3117 3118

~~3118**输出（type: `"pdf"`）：**~~3119**输出（type：`"pdf"`）：**

3119 3120

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

3121{3122{

3128}3129}

3129```3130```

3130 3131

~~3131**输出（type: `"parts"`）：**~~3132**输出（type：`"parts"`）：**

3132 3133

3133```python theme={null}3134```python theme={null}

3134{3135{

3137 "filePath": str, # 被读取的 PDF3138 "filePath": str, # 被读取的 PDF

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

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

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

3141 },3142 },

3142 "firstPage": int | None, # 可选的第一个提取页面的文档页码3143 "firstPage": int | None, # 可选；第一个提取页面在文档中的页码

3143}3144}

3144```3145```

3145 3146

~~3146**输出（type: `"file_unchanged"`）：**~~3147**输出（type：`"file_unchanged"`）：**

3147 3148

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

3149{3150{

3150 "type": "file_unchanged", # 文件自 Claude 在此会话中上次读取以来未更改，因此不重复内容3151 "type": "file_unchanged", # 自 Claude 在此会话中上次读取以来文件未发生变化，因此不会重复返回内容

3151 "file": {3152 "file": {

3152 "filePath": str,3153 "filePath": str,

3153 },3154 },

3154 "source": "seeded" | None, # 当较早的副本来自在启动时加载的 CLAUDE.md 或记忆文件而不是 Read 调用时出现3155 "source": "seeded" | None, # 当之前的副本来自启动时加载的 CLAUDE.md 或记忆文件（而非 Read 调用）时存在

3155}3156}

3156```3157```

3157 3158

3174 3175

3175```python theme={null}3176```python theme={null}

3176{3177{

3177 "type": "create" | "update", # 写入是创建了新文件还是覆盖了现有文件3178 "type": "create" | "update", # 此次写入是创建了新文件还是覆盖了现有文件

3178 "filePath": str, # 被写入的文件3179 "filePath": str, # 被写入的文件

3179 "content": str, # 被写入的内容3180 "content": str, # 写入的内容

3180 "structuredPatch": [ # Diff hunks；对于新文件、未更改或 Claude Code 跳过 diff 时为空3181 "structuredPatch": [ # diff 块；对于新文件、内容无变化或 Claude Code 跳过 diff 时为空

3181 {3182 {

3182 "oldStart": int,3183 "oldStart": int,

3183 "oldLines": int,3184 "oldLines": int,

3186 "lines": list[str],3187 "lines": list[str],

3187 }3188 }

3188 ],3189 ],

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

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

3191 "filename": str,3192 "filename": str,

3192 "status": "modified" | "added",3193 "status": "modified" | "added",

3193 "additions": int,3194 "additions": int,

3194 "deletions": int,3195 "deletions": int,

3195 "changes": int,3196 "changes": int,

3196 "patch": str,3197 "patch": str,

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

3198 } | None,3199 } | None,

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

3200}3201}

3201```3202```

3202 3203

3219 3220

3220```python theme={null}3221```python theme={null}

3221{3222{

3222 "durationMs": int, # 运行搜索所花费的时间（毫秒）3223 "durationMs": int, # 运行搜索所用的时间（毫秒）

3223 "numFiles": int, # 返回的路径数，任何截断后3224 "numFiles": int, # 截断后返回的路径数量

3224 "filenames": list[str], # 匹配的文件路径3225 "filenames": list[str], # 匹配的文件路径

3225 "truncated": bool, # 结果是否在 100 文件限制处被截断3226 "truncated": bool, # 结果是否因 100 个文件的限制而被截断

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

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

3228}3229}

3229```3230```

3247 "output_mode": str | None, # "content"、"files_with_matches" 或 "count"3248 "output_mode": str | None, # "content"、"files_with_matches" 或 "count"

3248 "-i": bool | None, # 不区分大小写的搜索3249 "-i": bool | None, # 不区分大小写的搜索

3249 "-n": bool | None, # 显示行号3250 "-n": bool | None, # 显示行号

3250 "-B": int | None, # 每个匹配前显示的行数3251 "-B": int | None, # 每个匹配项之前显示的行数

3251 "-A": int | None, # 每个匹配后显示的行数3252 "-A": int | None, # 每个匹配项之后显示的行数

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

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

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

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

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

3257 "multiline": bool | None, # 启用多行模式3258 "multiline": bool | None, # 启用多行模式

3258}3259}

3259```3260```

3262 3263

3263```python theme={null}3264```python theme={null}

3264{3265{

3266 "numFiles": int, # 结果中的文件数；在 content 模式中始终为 03267 "numFiles": int, # 结果中的文件数；在 content 模式下始终为 0

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

3268 "content": str | None, # content 模式中的匹配行，或 count 模式中的每个文件计数3269 "content": str | None, # content 模式下的匹配行，或 count 模式下每个文件的计数

3269 "numLines": int | None, # content 中的行数，在 content 模式中出现3270 "numLines": int | None, # content 中的行数，在 content 模式下存在

3270 "numMatches": int | None, # 总匹配计数，在 count 模式中出现3271 "numMatches": int | None, # 匹配总数，在 count 模式下存在

3271 "totalFiles": int | None, # 可选的 head_limit 和 offset 前的总数，在 files_with_matches 模式中3272 "totalFiles": int | None, # 可选；应用 head_limit 和 offset 之前的总数，在 files_with_matches 模式下

3272 "totalLines": int | None, # 可选的 head_limit 和 offset 前的总数，在 content 模式中3273 "totalLines": int | None, # 可选；应用 head_limit 和 offset 之前的总数，在 content 模式下

3273 "appliedLimit": int | None, # 当 head_limit 截断结果时出现3274 "appliedLimit": int | None, # 当 head_limit 截断了结果时存在

3274 "appliedOffset": int | None, # 当应用了 offset 时出现3275 "appliedOffset": int | None, # 当应用了 offset 时存在

3275}3276}

3276```3277```

3277 3278

3278Grep 在每个输出模式中返回此 dict 形状。哪些可选键存在取决于 `output_mode`。3279Grep 在每种输出模式下都返回这种 dict 形状。存在哪些可选键取决于 `output_mode`。

3279 3280

3280`totalFiles` 需要 Claude Code v2.1.208 或更高版本。`totalLines` 需要 Claude Code v2.1.210 或更高版本。3281`totalFiles` 需要 Claude Code v2.1.208 或更高版本。`totalLines` 需要 Claude Code v2.1.210 或更高版本。

3281 3282

3289 3290

3290```python theme={null}3291```python theme={null}

3291{3292{

3292 "notebook_path": str, # Jupyter 笔记本的绝对路径3293 "notebook_path": str, # Jupyter notebook 的绝对路径

3293 "cell_id": str | None, # 要编辑的单元格的 ID3294 "cell_id": str | None, # 要编辑的单元格的 ID

3294 "new_source": str, # 单元格的新源代码3295 "new_source": str, # 单元格的新源代码

3295 "cell_type": "code" | "markdown" | None, # 单元格的类型3296 "cell_type": "code" | "markdown" | None, # 单元格的类型

3302```python theme={null}3303```python theme={null}

3303{3304{

3304 "new_source": str, # 写入单元格的源代码3305 "new_source": str, # 写入单元格的源代码

3305 "old_source": str | None, # 之前的单元格源代码，对于 replace 和 delete 出现3306 "old_source": str | None, # 之前的单元格源代码，replace 和 delete 时存在

3306 "cell_id": str | None, # 编辑的单元格的 ID，当可用时3307 "cell_id": str | None, # 被编辑单元格的 ID（如果可用）

3307 "cell_type": "code" | "markdown", # 单元格类型3308 "cell_type": "code" | "markdown", # 单元格类型

3308 "language": str, # 笔记本的编程语言3309 "language": str, # notebook 的编程语言

3309 "edit_mode": str, # 使用的编辑模式3310 "edit_mode": str, # 所使用的编辑模式

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

3311 "notebook_path": str, # 笔记本文件3312 "notebook_path": str, # notebook 文件

3312 "original_file": str, # 编辑前的笔记本内容3313 "original_file": str, # 编辑前的 notebook 内容

3313 "updated_file": str, # 编辑后的笔记本内容3314 "updated_file": str, # 编辑后的 notebook 内容

3314}3315}

3315```3316```

3316 3317

3325```python theme={null}3326```python theme={null}

3326{3327{

3327 "url": str, # 要从中获取内容的 URL3328 "url": str, # 要从中获取内容的 URL

3328 "prompt": str, # 在获取的内容上运行的提示词3329 "prompt": str, # 要在获取的内容上运行的提示词

3329}3330}

3330```3331```

3331 3332

3333 3334

3334```python theme={null}3335```python theme={null}

3335{3336{

3336 "bytes": int, # 获取的内容大小（字节）3337 "bytes": int, # 获取内容的大小（字节）

3337 "code": int, # HTTP 响应代码3338 "code": int, # HTTP 响应码

3338 "codeText": str, # HTTP 响应代码文本3339 "codeText": str, # HTTP 响应码文本

3339 "result": str, # 通过将提示词应用于内容得到的处理结果3340 "result": str, # 将提示词应用于内容后得到的处理结果

3340 "durationMs": int, # 获取和处理内容的时间（毫秒）3341 "durationMs": int, # 获取和处理内容所用的时间（毫秒）

3341 "url": str, # 被获取的 URL3342 "url": str, # 被获取的 URL

3342}3343}

3343```3344```

3353```python theme={null}3354```python theme={null}

3354{3355{

3355 "query": str, # 要使用的搜索查询3356 "query": str, # 要使用的搜索查询

3356 "allowed_domains": list[str] | None, # 仅包含来自这些域的结果3357 "allowed_domains": list[str] | None, # 仅包含来自这些域名的结果

3357 "blocked_domains": list[str] | None, # 永远不包含来自这些域的结果3358 "blocked_domains": list[str] | None, # 绝不包含来自这些域名的结果

3358}3359}

3359```3360```

3360 3361

3364{3365{

3365 "query": str, # 搜索查询3366 "query": str, # 搜索查询

3366 "results": list[str | {"tool_use_id": str, "content": list[{"title": str, "url": str}]}],3367 "results": list[str | {"tool_use_id": str, "content": list[{"title": str, "url": str}]}],

3367 "durationSeconds": float, # 搜索持续时间（秒）3368 "durationSeconds": float, # 搜索时长（秒）

3368}3369}

3369```3370```

3370 3371

3387 3388

3388 此默认集合适用于 Claude Code v2.1.268 及更高版本，TypeScript Agent SDK 从 v0.3.268 开始捆绑此版本。3389 此默认集合适用于 Claude Code v2.1.268 及更高版本，TypeScript Agent SDK 从 v0.3.268 开始捆绑此版本。

3389 3390

3390 见 [模型可用性](/docs/zh-CN/agent-sdk/todo-tracking#model-availability) 以选择加入。3391 请参阅[模型可用性](/docs/zh-CN/agent-sdk/todo-tracking#model-availability)以选择启用。

3391</Note>3392</Note>

3392 3393

3393**输入：**3394**输入：**

3398 {3399 {

3399 "content": str, # 任务描述3400 "content": str, # 任务描述

3400 "status": "pending" | "in_progress" | "completed", # 任务状态3401 "status": "pending" | "in_progress" | "completed", # 任务状态

3401 "activeForm": str, # 描述的活跃形式3402 "activeForm": str, # 描述的进行时形式

3402 }3403 }

3403 ]3404 ]

3404}3405}

3438 "subject": str, # 简短的任务标题3439 "subject": str, # 简短的任务标题

3439 "description": str, # 详细的任务正文3440 "description": str, # 详细的任务正文

3440 "activeForm": str | None, # 进行中时显示的现在时标签3441 "activeForm": str | None, # 进行中时显示的现在时标签

3441 "metadata": dict | None, # 任意调用者元数据3442 "metadata": dict | None, # 任意调用方元数据

3442}3443}

3443```3444```

3444 3445

3446 3447

3447```python theme={null}3448```python theme={null}

3448{3449{

3449 "task": {"id": str, "subject": str}, # 创建的任务及其分配的 ID3450 "task": {"id": str, "subject": str}, # 已创建的任务及其分配的 ID

3450}3451}

3451```3452```

3452 3453

3460 3461

3461```python theme={null}3462```python theme={null}

3462{3463{

3463 "taskId": str, # 要修补的任务的 ID3464 "taskId": str, # 要修改的任务的 ID

3464 "status": Literal["pending", "in_progress", "completed", "deleted"] | None,3465 "status": Literal["pending", "in_progress", "completed", "deleted"] | None,

3465 "subject": str | None,3466 "subject": str | None,

3466 "description": str | None,3467 "description": str | None,

3467 "activeForm": str | None,3468 "activeForm": str | None,

3468 "addBlocks": list[str] | None, # 此任务现在阻止的任务 ID3469 "addBlocks": list[str] | None, # 此任务现在阻塞的任务 ID

3469 "addBlockedBy": list[str] | None, # 现在阻止此任务的任务 ID3470 "addBlockedBy": list[str] | None, # 现在阻塞此任务的任务 ID

3470 "owner": str | None,3471 "owner": str | None,

3471 "metadata": dict | None,3472 "metadata": dict | None,

3472}3473}

3478{3479{

3479 "success": bool,3480 "success": bool,

3480 "taskId": str,3481 "taskId": str,

3481 "updatedFields": list[str], # 更改的字段名称3482 "updatedFields": list[str], # 发生变化的字段名称

3482 "error": str | None,3483 "error": str | None,

3483 "statusChange": {"from": str, "to": str} | None,3484 "statusChange": {"from": str, "to": str} | None,

3484}3485}

3509 "status": Literal["pending", "in_progress", "completed"],3510 "status": Literal["pending", "in_progress", "completed"],

3510 "blocks": list[str],3511 "blocks": list[str],

3511 "blockedBy": list[str],3512 "blockedBy": list[str],

3512 } | None, # 当 ID 未找到时为 None3513 } | None, # 未找到该 ID 时为 None

3513}3514}

3514```3515```

3515 3516

3545 TaskOutput3546 TaskOutput

3546</h3>3547</h3>

3547 3548

3548在 Claude Code v2.1.277 中移除。之前检索来自运行中或已完成的后台任务的输出，`BashOutput` 被接受作为别名；Claude 改用 `Read` 在后台任务的输出文件上读取。3549已在 Claude Code v2.1.277 中移除。此前用于从正在运行或已完成的后台任务中检索输出，并接受 `BashOutput` 作为别名；现在 Claude 改用 `Read` 读取后台任务的输出文件。

3549 3550

3550`disallowed_tools` 条目或仍然命名任一名称的拒绝规则被忽略而不发出警告。3551仍然引用这两个名称之一的 `disallowed_tools` 条目或拒绝规则会被忽略，且不会发出警告。

3551 3552

3552<h3 id="taskstop">3553<h3 id="taskstop">

3553 TaskStop3554 TaskStop

3554</h3>3555</h3>

3555 3556

3556**工具名称：** `TaskStop`。之前的名称 `KillShell` 和 `KillBash` 仍然被接受作为别名。3557**工具名称：** `TaskStop`。先前的名称 `KillShell` 和 `KillBash` 仍作为别名被接受。

3557 3558

3558**输入：**3559**输入：**

3559 3560

3560```python theme={null}3561```python theme={null}

3561{3562{

3562 "task_id": str | None, # 要停止的后台任务的 ID3563 "task_id": str | None, # 要停止的后台任务的 ID

3563 "shell_id": str | None, # 已弃用：改用 task_id3564 "shell_id": str | None, # 已弃用：请改用 task_id

3564}3565}

3565```3566```

3566 3567

3568 3569

3569```python theme={null}3570```python theme={null}

3570{3571{

3571 "message": str, # 关于操作的状态消息3572 "message": str, # 关于该操作的状态消息

3572 "task_id": str, # 被停止的任务的 ID3573 "task_id": str, # 已停止任务的 ID

3573 "task_type": str, # 被停止的任务的类型3574 "task_type": str, # 已停止任务的类型

3574 "command": str | None, # 被停止的任务的命令或描述3575 "command": str | None, # 已停止任务的命令或描述

3575}3576}

3576```3577```

3577 3578

3585 3586

3586```python theme={null}3587```python theme={null}

3587{3588{

3588 "plan": str # 要提交给用户批准的计划3589 "plan": str # 要呈给用户过目以获得批准的计划

3589}3590}

3590```3591```

3591 3592

3594```python theme={null}3595```python theme={null}

3595{3596{

3596 "plan": str | None, # 呈现给用户的计划3597 "plan": str | None, # 呈现给用户的计划

3597 "isAgent": bool, # 当子代理调用工具时为 True3598 "isAgent": bool, # 当子代理调用该工具时为 True

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

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

3600 "planWasEdited": bool | None, # 当用户在批准前编辑了计划时出现且为 True3601 "planWasEdited": bool | None, # 当用户在批准之前编辑了计划时存在，值为 True

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

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

3603}3604}

3604```3605```

3605 3606

3613 3614

3614```python theme={null}3615```python theme={null}

3615{3616{

3616 "server": str | None # 可选的服务器名称以按其过滤资源3617 "server": str | None # 可选；用于过滤资源的服务器名称

3617}3618}

3618```3619```

3619 3620

3620结果是一个列表而不是 dict，所以 `tool_use_result` 为此工具保存一个 `list`。3621结果是一个列表而不是 dict，因此对于此工具，`tool_use_result` 包含一个 `list`。

3621 3622

3622**输出：**3623**输出：**

3623 3624

3626 {3627 {

3627 "uri": str, # 资源 URI3628 "uri": str, # 资源 URI

3628 "name": str, # 资源名称3629 "name": str, # 资源名称

3629 "mimeType": str | None, # 可选 MIME 类型3630 "mimeType": str | None, # 可选的 MIME 类型

3630 "description": str | None, # 可选描述3631 "description": str | None, # 可选的描述

3631 "server": str, # 提供此资源的服务器3632 "server": str, # 提供此资源的服务器

3632 }3633 }

3633]3634]

3655 "contents": [3656 "contents": [

3656 {3657 {

3657 "uri": str, # 资源 URI3658 "uri": str, # 资源 URI

3658 "mimeType": str | None, # 可选 MIME 类型3659 "mimeType": str | None, # 可选的 MIME 类型

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

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

3661 }3662 }

3662 ],3663 ],

3663 "error": str | None, # 当服务器无法读取资源时出现3664 "error": str | None, # 当服务器无法读取该资源时存在

3664}3665}

3665```3666```

3666 3667

agent-sdk/typescript.md +72 −61

Details

218| :- | :- | :- |218| :- | :- | :- |

223| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)`; searchHint?: string; alwaysLoad?: boolean }` | 可选的 extras。`annotations` 为客户端提供 MCP 行为提示。`searchHint` 是当[工具搜索](/docs/zh-CN/agent-sdk/tool-search)处于活动状态时在延迟工具列表中显示的单行功能短语。`alwaysLoad: true` 将此工具的完整架构保留在初始提示中，而不是延迟它 |223| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)`; searchHint?: string; alwaysLoad?: boolean }` | 可选的 extras。`annotations` 为客户端提供 MCP 行为提示。`searchHint` 是当[工具搜索](/docs/zh-CN/agent-sdk/tool-search)处于活动状态时在延迟工具列表中显示的单行功能短语。`alwaysLoad: true` 将此工具的完整 schema 保留在初始提示中，而不是延迟它 |

224 224

225<h4 id="toolannotations">225<h4 id="toolannotations">

226 `ToolAnnotations`226 `ToolAnnotations`

227</h4>227</h4>

228 228

229从 `@modelcontextprotocol/sdk/types.js` 重新导出。所有字段都是可选提示；客户端不应依赖它们做出安全决策。229在 `@modelcontextprotocol/sdk/types.js` 中定义。所有字段都是可选提示；客户端不应依赖它们做出安全决策。

230 230

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

232| :- | :- | :- | :- |232| :- | :- | :- | :- |

238 238

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

240import { tool } from "@anthropic-ai/claude-agent-sdk";240import { tool } from "@anthropic-ai/claude-agent-sdk";

282| `options.timeout` | `number` | 此服务器的工具调用超时（毫秒）。Claude Code 将其应用于此服务器以代替 [`MCP_TOOL_TIMEOUT`](/docs/zh-CN/env-vars)。传递至少 1000 的整数。Claude Code 忽略其他值。需要 TypeScript Agent SDK v0.3.248 或更高版本 |282| `options.timeout` | `number` | 此服务器的工具调用超时时间（毫秒）。Claude Code 将其应用于此服务器以代替 [`MCP_TOOL_TIMEOUT`](/docs/zh-CN/env-vars)。传递至少 1000 的整数。Claude Code 忽略其他值。需要 TypeScript Agent SDK v0.3.248 或更高版本 |

283 283

284<h3 id="listsessions">284<h3 id="listsessions">

285 `listSessions()`285 `listSessions()`

299| :- | :- | :- | :- |299| :- | :- | :- | :- |

303 303

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

305 返回类型：`SDKSessionInfo`305 返回类型：`SDKSessionInfo`

373 373

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

420 `renameSession()`420 `renameSession()`

421</h3>421</h3>

422 422

423通过附加自定义标题条目来重命名会话。重复调用是安全的；最新的标题获胜。423通过附加自定义标题条目来重命名会话。重复调用是安全的；以最新的标题为准。

424 424

425```typescript theme={null}425```typescript theme={null}

426function renameSession(426function renameSession(

444 `tagSession()`444 `tagSession()`

445</h3>445</h3>

446 446

447标记会话。传递 `null` 以清除标签。重复调用是安全的；最新的标签获胜。447标记会话。传递 `null` 以清除标签。重复调用是安全的；以最新的标签为准。

448 448

449```typescript theme={null}449```typescript theme={null}

450function tagSession(450function tagSession(

498| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | 所有源 | 要加载的文件系统源。传递 `[]` 以跳过用户、项目和本地设置。[端点管理的策略](/docs/zh-CN/managed-settings#delivery-mechanisms)在所有情况下都会加载。`resolveSettings()` 仅当您传递 `options.serverManagedSettings` 时才包括服务器管理的设置 |498| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | 所有源 | 要加载的文件系统源。传递 `[]` 以跳过用户、项目和本地设置。[端点管理的策略](/docs/zh-CN/managed-settings#delivery-mechanisms)在所有情况下都会加载。`resolveSettings()` 仅当您传递 `options.serverManagedSettings` 时才包括服务器管理的设置 |

499| `options.managedSettings` | `Settings` | `undefined` | 由嵌入主机提供的策略层设置。遵循与 [`managedSettings` in `Options`](#options) 相同的规则，除了 `resolveSettings()` 不执行配置的 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper)，因此快照可以包括实时会话删除的设置 |499| `options.managedSettings` | `Settings` | `undefined` | 由嵌入主机提供的策略层设置。遵循与 [`managedSettings` in `Options`](#options) 相同的规则，除了 `resolveSettings()` 不执行配置的 [`policyHelper`](/docs/zh-CN/settings-reference#policyhelper)，因此快照可以包括实时会话删除的设置 |

501 501

502<h4 id="return-type-resolvedsettings">502<h4 id="return-type-resolvedsettings">

503 返回类型：`ResolvedSettings`503 返回类型：`ResolvedSettings`

504</h4>504</h4>

505 505

506`resolveSettings()` 返回一个对象，描述合并的设置和为每个密钥提供的源。506`resolveSettings()` 返回一个对象，描述合并的设置和为每个键提供值的源。

507 507

508| 属性 | 类型 | 描述 |508| 属性 | 类型 | 描述 |

509| :- | :- | :- |509| :- | :- | :- |

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

513 513

514<h4 id="example-5">514<h4 id="example-5">

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

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

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

1759* `resume_reason`：在重启中断该轮后，Claude Code 重新运行该轮的原因。在两个分支上都存在，且仅在此类重新运行上存在。请参阅 [`resume_reason`](#resume_reason)。1759* `resume_reason`：Claude Code 在重启中断该轮次后重新运行它的原因。出现在两个分支上。请参阅 [`resume_reason`](#resume_reason)。

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

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

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

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

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

1847 1847

1848该值是一个简短的小写标记，命名轮被重新运行的原因，例如 `interrupted_turn`。该字段在所有其他轮上不存在。1848该值是一个简短的小写标记，指明该轮次被重新运行的原因，例如 `interrupted_turn`。

1849 1849

1850<h4 id="queued_turn_count">1850<h4 id="queued_turn_count">

1851 `queued_turn_count`1851 `queued_turn_count`

1887 | "worktree_resume_refused"1887 | "worktree_resume_refused"

1888 | "worktree_unverified"1888 | "worktree_unverified"

1889 | "cli_version_too_old"1889 | "cli_version_too_old"

1890 | "bypass_root";1890 | "bypass_root"

1891 | "org_config_required_unavailable"

1892 | "org_config_refused";

1891```1893```

1892 1894

1893每个值命名一个拒绝：1895每个值命名一个拒绝：

1916| `org_config_required_unavailable` | 会话在启动前需要组织的策略和托管设置，但无法加载它们，例如由于网络故障或 Anthropic 服务器错误。需要 Agent SDK v0.3.293 或更高版本 |

1917| `org_config_refused` | Anthropic 拒绝为此次登录提供组织的策略和托管设置，例如因为登录已过期或被吊销，或组织不允许此账户使用 Claude Code。需要 Agent SDK v0.3.293 或更高版本 |

1914 1918

1915<h3 id="sdksystemmessage">1919<h3 id="sdksystemmessage">

1916 `SDKSystemMessage`1920 `SDKSystemMessage`

3124 工具输入类型3128 工具输入类型

3125</h2>3129</h2>

3126 3130

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

3128 3132

3129<h3 id="toolinputschemas">3133<h3 id="toolinputschemas">

3130 `ToolInputSchemas`3134 `ToolInputSchemas`

3190 prompt: string;3194 prompt: string;

3191 subagent_type?: string;3195 subagent_type?: string;

3197 effort?: "low" | "medium" | "high" | "xhigh" | "max";

3193 run_in_background?: boolean;3198 run_in_background?: boolean;

3194 name?: string;3199 name?: string;

3195 team_name?: string; // 已弃用；被忽略3200 team_name?: string; // 已弃用；被忽略

3198};3203};

3199```3204```

3200 3205

3201启动新代理以自主处理复杂的多步骤任务。3206启动新的 Agent 以自主处理复杂的多步骤任务。

3202 3207

3203<h3 id="askuserquestion">3208<h3 id="askuserquestion">

3204 AskUserQuestion3209 AskUserQuestion

3262 3267

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

3264 3269

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

3266 3271

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

3268 3273

3381};3386};

3382```3387```

3383 3388

3384按 ID 停止运行的后台任务或 shell。自 v2.1.198 起，`task_id` 也接受代理团队队友或按代理 ID 或名称的命名后台代理。3389按 ID 停止运行的后台任务或 shell。自 v2.1.198 起，`task_id` 也接受 agent team 队友，或按 Agent ID 或名称指定的命名后台 Agent。

3385 3390

3386<h3 id="notebookedit">3391<h3 id="notebookedit">

3387 NotebookEdit3392 NotebookEdit

3450};3455};

3451```3456```

3452 3457

3453运行[动态工作流](/docs/zh-CN/workflows)：一个脚本，在后台协调许多子代理并返回一个统一的结果。Workflow 工具在 Agent SDK v0.3.149 及更高版本中可用。至少需要 `script`、`name` 或 `scriptPath` 之一。3458运行[动态工作流](/docs/zh-CN/workflows)：一个脚本，在后台协调许多子代理并返回一个统一的结果。`Workflow` 工具在 Agent SDK v0.3.149 及更高版本中可用。至少需要 `script`、`name` 或 `scriptPath` 之一。

3454 3459

3455| 字段 | 类型 | 描述 |3460| 字段 | 类型 | 描述 |

3456| - | - | - |3461| - | - | - |

3457| `script` | `string` | 内联工作流脚本。必须以 `export const meta = { name, description }` 作为字面量开头，后跟使用 `agent()`、`parallel()`、`pipeline()` 和 `phase()` 的脚本主体。`meta` 中的可选 `phases` 数组在进度视图中将代理分组到命名阶段下 |3462| `script` | `string` | 内联工作流脚本。必须以 `export const meta = { name, description }` 作为字面量开头，后跟使用 `agent()`、`parallel()`、`pipeline()` 和 `phase()` 的脚本主体。`meta` 中的可选 `phases` 数组在进度视图中将 Agent 分组到命名阶段下 |

3578};3583};

3579```3584```

3580 3585

3581退出 Plan Mode。`allowedPrompts` 字段已弃用且被忽略；Claude Code 仍然接受它，以便现有调用者和记录验证。在 v2.1.205 之前，它请求基于提示的 Bash 权限以实现计划。3586退出计划模式。`allowedPrompts` 字段已弃用且被忽略；Claude Code 仍然接受它，以便现有调用者和会话记录能够通过验证。在 v2.1.205 之前，它请求基于提示词的 Bash 权限以实现计划。

3582 3587

3583<h3 id="listmcpresources">3588<h3 id="listmcpresources">

3584 ListMcpResources3589 ListMcpResources

3622};3627};

3623```3628```

3624 3629

3625创建并进入临时 git worktree 以进行隔离工作。传递 `path` 以切换到现有 worktree 而不是创建新的。在首次进入时，目标必须是当前存储库的已注册 worktree，或在多存储库工作区中，必须是嵌套在其中的存储库的已注册 worktree；从 worktree 会话内进入时，必须在会话存储库的 `.claude/worktrees/` 下。`name` 和 `path` 互斥。3630创建并进入临时 git worktree 以进行隔离工作。传递 `path` 以切换到现有 worktree 而不是创建新的。在首次进入时，目标必须是当前仓库的已注册 worktree，或在多仓库工作区中，必须是嵌套在其中的仓库的已注册 worktree；从 worktree 会话内进入时，必须在会话仓库的 `.claude/worktrees/` 下。`name` 和 `path` 互斥。

3626 3631

3627<h3 id="exitworktree">3632<h3 id="exitworktree">

3628 ExitWorktree3633 ExitWorktree

3649type EnterPlanModeInput = {};3654type EnterPlanModeInput = {};

3650```3655```

3651 3656

3652进入 Plan Mode，Claude 在其中研究并呈现计划，然后再进行更改。3657进入计划模式，Claude 在其中研究并呈现计划，然后再进行更改。

3653 3658

3654<h3 id="croncreate">3659<h3 id="croncreate">

3655 CronCreate3660 CronCreate

3666};3671};

3667```3672```

3668 3673

3669在本地时间的 5 字段 cron 计划上安排提示运行。将 `recurring` 设置为 `false` 以在下一个匹配时仅触发一次。作业默认为会话范围，恢复时使用 `--resume` 或 `--continue` 会恢复尚未过期的作业。请参阅[计划任务](/docs/zh-CN/scheduled-tasks)。3674按本地时间的 5 字段 cron 计划安排提示词运行。将 `recurring` 设置为 `false` 以在下一个匹配时仅触发一次。作业默认限定于会话，使用 `--resume` 或 `--continue` 恢复时会还原尚未过期的作业。请参阅[定时任务](/docs/zh-CN/scheduled-tasks)。

3670 3675

3671将 `durable` 设置为 `true` 请求持久化到 `.claude/scheduled_tasks.json`，以便作业在重启后继续存在。持久化调度并非在每个会话中都可用：当不可用时，Claude Code 接受 `durable: true` 但创建仅会话的作业。读取输出的 `durable` 字段以查看作业是否已持久化。3676将 `durable` 设置为 `true` 请求持久化到 `.claude/scheduled_tasks.json`，以便作业在重启后继续存在。持久化调度并非在每个会话中都可用：当不可用时，Claude Code 接受 `durable: true` 但创建仅会话的作业。读取输出的 `durable` 字段以查看作业是否已持久化。

3672 3677

3712};3717};

3713```3718```

3714 3719

3715安排一次性唤醒，在延迟后触发给定的提示。此工具支持自定步调的 `/loop` 命令。运行时将 `delaySeconds` 限制在 60 到 3600 秒之间。除非 `stop` 为 true，否则 `delaySeconds`、`reason`、`prompt` 和 `noop` 字段是必需的。`noop: true` 报告没有任何更改的唤醒。设置 `stop: true` 取消待处理的唤醒并结束自定步调的 `/loop`。`stop` 字段需要 Claude Code v2.1.202 或更高版本。请参阅[工具参考中的 ScheduleWakeup 行](/docs/zh-CN/tools-reference)。3720安排一次性唤醒，在延迟后触发给定的提示词。此工具支持自定步调的 `/loop` 命令。运行时将 `delaySeconds` 限制在 60 到 3600 秒之间。除非 `stop` 为 true，否则 `delaySeconds`、`reason`、`prompt` 和 `noop` 字段是必需的。`noop: true` 报告没有任何更改的唤醒。设置 `stop: true` 取消待处理的唤醒并结束自定步调的 `/loop`。`stop` 字段需要 Claude Code v2.1.202 或更高版本。请参阅[工具参考中的 ScheduleWakeup 行](/docs/zh-CN/tools-reference)。

3716 3721

3717<h3 id="remotetrigger">3722<h3 id="remotetrigger">

3718 RemoteTrigger3723 RemoteTrigger

3740};3745};

3741```3746```

3742 3747

3743管理[例程](/docs/zh-CN/routines)，即在云中托管的计划和触发的 Claude Code 运行。此工具支持 `/schedule` 命令。`trigger_id` 对于 `get`、`update`、`run` 和 `list_runs` 操作是必需的。`body` 对于 `create`、`update` 和 `create_webhook_trigger` 是必需的，对于 `run` 是可选的。3748管理 [Routines](/docs/zh-CN/routines)，即在云端托管的按计划和按触发运行的 Claude Code 任务。此工具支持 `/schedule` 命令。`trigger_id` 对于 `get`、`update`、`run` 和 `list_runs` 操作是必需的。`body` 对于 `create`、`update` 和 `create_webhook_trigger` 是必需的，对于 `run` 是可选的。

3744 3749

3745`create_webhook_trigger` 将事件源附加到现有例程，例如触发它的 [GitHub 事件](/docs/zh-CN/routines#add-a-github-trigger)。`body` 命名源、事件和要触发的例程。需要 Claude Code v2.1.225 或更高版本。3750`create_webhook_trigger` 将事件源附加到现有 Routine，例如触发它的 [GitHub 事件](/docs/zh-CN/routines#add-a-github-trigger)。`body` 命名源、事件和要触发的 Routine。需要 Claude Code v2.1.225 或更高版本。

3746 3751

3747`list_runs` 列出例程的最近运行，`get_run_log` 读取一个运行的日志。`session_id` 从 `list_runs` 结果命名要读取的运行，`cursor` 分页浏览任一操作的结果。两个操作都需要 Claude Code v2.1.227 或更高版本。3752`list_runs` 列出 Routine 的最近运行，`get_run_log` 读取一次运行的日志。`session_id` 从 `list_runs` 结果中指定要读取的运行，`cursor` 分页浏览任一操作的结果。两个操作都需要 Claude Code v2.1.227 或更高版本。

3748 3753

3749此工具仅在会话使用启用了例程的计划的 claude.ai 账户进行身份验证时可用，当您的组织的策略禁用[网络上的 Claude Code](/docs/zh-CN/claude-code-on-the-web) 时不存在。在 Claude Code v2.1.227 或更高版本上，当所有者为组织[关闭例程](/docs/zh-CN/routines#routines-are-disabled-by-your-organizations-policy)时，该工具也不存在。在 v2.1.227 之前，仅关闭例程切换的会话仍然显示该工具，服务器拒绝其调用。3754此工具仅在会话使用启用了 Routines 的计划的 claude.ai 账户进行身份验证时可用，当您的组织的策略禁用[云端会话](/docs/zh-CN/claude-code-on-the-web)时不存在。在 Claude Code v2.1.227 或更高版本上，当所有者[为组织关闭 Routines](/docs/zh-CN/routines#routines-are-disabled-by-your-organizations-policy) 时，该工具也不存在。在 v2.1.227 之前，仅关闭 Routines 开关的会话仍然显示该工具，服务器拒绝其调用。

3750 3755

3751<h3 id="pushnotification">3756<h3 id="pushnotification">

3752 PushNotification3757 PushNotification

3767 REPL3772 REPL

3768</h3>3773</h3>

3769 3774

3770在 v2.1.275 中移除。通过 v2.1.274，可以通过在 [`env` 选项](#options)中设置 `CLAUDE_CODE_REPL=1` 来打开实验性 `REPL` 工具。3775在 v2.1.275 中移除。在 v2.1.274 及之前，可以通过在 [`env` 选项](#options)中设置 `CLAUDE_CODE_REPL=1` 来打开实验性 `REPL` 工具。

3771 3776

3772<h3 id="reportfindings">3777<h3 id="reportfindings">

3773 ReportFindings3778 ReportFindings

3797 3802

3798每个发现包含这些字段：3803每个发现包含这些字段：

3799 3804

3800* `file`：发现所在的存储库相对路径。可选的 `line` 是它锚定到的 1 索引行。3805* `file`：发现所在的仓库相对路径。可选的 `line` 是它锚定到的 1 索引行。

3801* `summary`：缺陷的单句陈述。`failure_scenario` 描述导致错误输出或崩溃的具体输入和状态。3806* `summary`：缺陷的单句陈述。`failure_scenario` 描述导致错误输出或崩溃的具体输入和状态。

3802* `short_summary`：可选的最多 60 个字符的压缩标签，用于紧凑显示。需要 Claude Code v2.1.212 或更高版本。3807* `short_summary`：可选的最多 60 个字符的压缩标签，用于紧凑显示。需要 Claude Code v2.1.212 或更高版本。

3803* `category`：可选的发现类型的短 kebab-case slug，例如 `correctness` 或 `test-coverage`。需要 Claude Code v2.1.199 或更高版本。3808* `category`：可选的发现类型的短 kebab-case slug，例如 `correctness` 或 `test-coverage`。需要 Claude Code v2.1.199 或更高版本。

3828};3833};

3829```3834```

3830 3835

3831将本地 `.html` 或 `.md` 文件发布为托管的 artifact 页面，或列出用户发布的 artifacts。省略 `action` 或传递 `"publish"` 以发布 `file_path`，这对于发布操作是必需的。每个下面的字段适用于发布：3836将本地 `.html` 或 `.md` 文件发布为托管的 Artifact 页面，或列出用户发布的 Artifact。省略 `action` 或传递 `"publish"` 以发布 `file_path`，这对于发布操作是必需的。下面的每个字段适用于发布：

3832 3837

3833* `icon`：artifact 浏览器标签图标的一个短通用词，例如 `chart` 或 `map`。Claude 在首次发布时包含它，在更新时省略它，这会保留 artifact 的存储图标。3838* `icon`：Artifact 浏览器标签图标的一个短通用词，例如 `chart` 或 `map`。Claude 在首次发布时包含它，在更新时省略它，这会保留 Artifact 的存储图标。

3834* `favicon`：已弃用，Claude 会省略它。3839* `favicon`：已弃用，Claude 会省略它。

3835* `title`：当 HTML 文件没有 `<title>` 标签时，在浏览器标签和库中命名发布的页面。3840* `title`：当 HTML 文件没有 `<title>` 标签时，在浏览器标签和库中命名发布的页面。

3836* `url`：针对现有 artifact 以就地更新，而不是创建新的。3841* `url`：针对现有 Artifact 以就地更新，而不是创建新的。

3837 3842

3838`force` 是最后手段的覆盖，丢弃另一个会话发布的较新版本。在冲突时，失败的发布返回较新的内容；Claude 将其更改合并到该内容上，或重新读取 artifact，然后再次发布。仅当用户明确要求丢弃该版本时才传递 `force`。3843`force` 是最后手段的覆盖，丢弃另一个会话发布的较新版本。在冲突时，失败的发布返回较新的内容；Claude 将其更改合并到该内容上，或重新读取 Artifact，然后再次发布。仅当用户明确要求丢弃该版本时才传递 `force`。

3839 3844

3840传递 `"list"` 以枚举用户发布的 artifacts；仅 `limit` 和 `scope` 可能伴随它。`scope` 默认为 `"mine"`，列出用户拥有的 artifacts；`"shared"` 列出其他人与用户共享的 artifacts，`"all"` 列出两者。3845传递 `"list"` 以枚举用户发布的 Artifact；仅 `limit` 和 `scope` 可以伴随它。`scope` 默认为 `"mine"`，列出用户拥有的 Artifact；`"shared"` 列出其他人与用户共享的 Artifact，`"all"` 列出两者。

3841 3846

3842* `capabilities`：发布的页面使用的运行时功能，由功能名称键入，例如[页面可能调用的连接器](/docs/zh-CN/artifacts#pull-live-data-with-mcp-connectors)。artifact 服务验证声明并拒绝命名账户无法使用的功能或给予一个无效配置的发布。传递 `{}` 以清除存储的声明，在重新部署时省略字段以保留它。需要 Agent SDK v0.3.235 或更高版本。3847`limit` 设置列表返回的 Artifact 最大数量，范围为 1 到 200。大于 50 的 `limit` 需要 Agent SDK v0.3.292 或更高版本。不指定 `limit` 时，列表最多返回 25 个。

3843* `contract`：发布的页面运行的运行时版本。省略它以保留 artifact 的当前版本，传递 `"latest"` 以升级，或传递特定版本以固定或回滚。需要 Agent SDK v0.3.235 或更高版本。

3844 3848

3845这些类型已导出，但该工具在 Agent SDK 会话中默认处于关闭状态。发布还需要 [artifacts 可用性表](/docs/zh-CN/artifacts#availability)中的每个条件，使用 API 密钥进行身份验证的会话不满足这些条件。3849* `capabilities`：发布的页面使用的运行时功能，以功能名称为键，例如[页面可能调用的连接器](/docs/zh-CN/artifacts#pull-live-data-with-mcp-connectors)。Artifact 服务验证声明，并拒绝命名了账户无法使用的功能或为某功能提供无效配置的发布。传递 `{}` 以清除存储的声明，在重新部署时省略该字段以保留它。需要 Agent SDK v0.3.235 或更高版本。

3850* `contract`：发布的页面运行所基于的运行时版本。省略它以保留 Artifact 的当前版本，传递 `"latest"` 以升级，或传递特定版本以固定或回滚。需要 Agent SDK v0.3.235 或更高版本。

3851

3852这些类型已导出，但该工具在 Agent SDK 会话中默认处于关闭状态。发布还需要满足 [Artifact 可用性表](/docs/zh-CN/artifacts#availability)中的每个条件，使用 API 密钥进行身份验证的会话不满足这些条件。

3846 3853

3847<h3 id="projects">3854<h3 id="projects">

3848 Projects3855 Projects

3867};3874};

3868```3875```

3869 3876

3870读取和写入附加到会话的 claude.ai Project。在 `method` 上分派：3877读取和写入附加到会话的 claude.ai Project。根据 `method` 分派：

3871 3878

3872* `project_info`：返回项目元数据和文档列表。3879* `project_info`：返回项目元数据和文档列表。

3873* `project_read`：按 `path` 读取一个文档。3880* `project_read`：按 `path` 读取一个文档。

3874* `project_search`：使用 `query` 查询项目的知识库。`n` 限制命中数并默认为 5。3881* `project_search`：使用 `query` 查询项目的知识库。`n` 限制命中数并默认为 `5`。

3875* `project_write`：从 `content`（包含内联文本）或 `local_path`（命名工作目录内的文件）中的恰好一个在 `path` 处创建或替换文档。`present_to_user: true` 将写入的文档标记为用户需要看到的可交付成果。3882* `project_write`：从 `content`（包含内联文本）或 `local_path`（命名工作目录内的文件）中的恰好一个在 `path` 处创建或替换文档。`present_to_user: true` 将写入的文档标记为用户需要看到的可交付成果。

3876* `project_delete`：按 `path` 删除文档。3883* `project_delete`：按 `path` 删除文档。

3877 3884

3914type ShowOnboardingRolePickerInput = {};3921type ShowOnboardingRolePickerInput = {};

3915```3922```

3916 3923

3917在 Cowork 入职期间呈现可点击的角色选择器芯片行，以便用户可以选择其角色并获得匹配的插件安装。不需要参数；角色列表由客户端定义。调用会阻塞直到用户响应。3924在 Cowork 入职期间呈现可点击的角色选择器芯片行，以便用户可以选择其角色并安装匹配的插件。不需要参数；角色列表由客户端定义。调用会阻塞直到用户响应。

3918 3925

3919<h3 id="mcpinput">3926<h3 id="mcpinput">

3920 McpInput3927 McpInput

3928};3935};

3929```3936```

3930 3937

3931MCP 工具参数是开放对象：每个服务器定义自己的参数，因此类型对字段名称或值不施加任何约束。请查阅服务器自己的工具架构以了解特定工具接受的字段。3938MCP 工具参数是开放对象：每个服务器定义自己的参数，因此类型对字段名称或值不施加任何约束。请查阅服务器自己的工具 schema 以了解特定工具接受的字段。

3932 3939

3933<h2 id="tool-output-types">3940<h2 id="tool-output-types">

3934 工具输出类型3941 工具输出类型

3935</h2>3942</h2>

3936 3943

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

3938 3945

3939<h3 id="tooloutputschemas">3946<h3 id="tooloutputschemas">

3940 `ToolOutputSchemas`3947 `ToolOutputSchemas`

4059 };4066 };

4060```4067```

4061 4068

4062返回来自子代理的结果。在 `status` 字段上进行区分：`"completed"` 表示已完成的任务，`"async_launched"` 表示后台任务，`"remote_launched"` 表示 Claude Code 分派到远程云会话的任务，其中 `sessionUrl` 链接到该会话，`taskId` 标识它。4069返回来自子代理的结果。在 `status` 字段上进行区分：`"completed"` 表示已完成的任务，`"async_launched"` 表示后台任务，`"remote_launched"` 表示 Claude Code 分派到云端会话的任务，其中 `sessionUrl` 链接到该会话，`taskId` 标识它。

4063 4070

4064在 `completed` 变体上，`resolvedModel` 命名子代理启动时所用的模型，当应用 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 或其他覆盖时，该模型可能与请求的 `model` 输入不同。此字段需要 Claude Code v2.1.174 或更高版本。在 `async_launched` 上，它命名任务移至后台时使用的模型。4071在 `completed` 变体上，`resolvedModel` 命名子代理启动时所用的模型，当应用 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection) 或其他覆盖时，该模型可能与请求的 `model` 输入不同。此字段需要 Claude Code v2.1.174 或更高版本。在 `async_launched` 上，它命名任务移至后台时使用的模型。

4065 4072

4198};4205};

4199```4206```

4200 4207

4201返回编辑操作的结构化差异。4208返回编辑操作的结构化 diff。

4202 4209

4203<h3 id="read-2">4210<h3 id="read-2">

4204 Read4211 Read

4310};4317};

4311```4318```

4312 4319

4313返回写入结果，包含结构化差异信息。`originalFile` 和 `structuredPatch` 持有的内容取决于写入：4320返回写入结果，包含结构化 diff 信息。`originalFile` 和 `structuredPatch` 持有的内容取决于写入：

4314 4321

4315* 对于新创建的文件，`originalFile` 为 null，`structuredPatch` 为空4322* 对于新创建的文件，`originalFile` 为 null，`structuredPatch` 为空

4316* 在覆盖时，`originalFile` 携带之前的内容，除非该内容大于约 10 MB：Claude Code 则跳过差异并返回 `originalFile` null 和 `structuredPatch` 空4323* 在覆盖时，`originalFile` 携带之前的内容，除非该内容大于约 10 MB：Claude Code 则跳过 diff 并返回 `originalFile` null 和 `structuredPatch` 空

4317* 当写入未更改任何内容或差异超时时，`structuredPatch` 也为空4324* 当写入未更改任何内容或 diff 超时时，`structuredPatch` 也为空

4318 4325

4319<h3 id="glob-2">4326<h3 id="glob-2">

4320 Glob4327 Glob

4426 4433

4427返回获取的内容，包含 HTTP 状态和元数据。4434返回获取的内容，包含 HTTP 状态和元数据。

4428 4435

4429`artifactRead` 是 Claude Code 自己的工件读取记录，仅当 Claude 获取会话可以发布的工件时出现。Claude Code 在会话恢复时读取它回来，以便稍后的发布基于正确的版本；您的代码不需要对其采取行动。`slug` 命名工件，`ver` 是读取记录的版本，当它未记录任何内容时不存在，`seeded: false` 标记其完整源未到达 Claude 的读取。`seeded` 字段需要 Agent SDK v0.3.239 或更高版本。4436`artifactRead` 是 Claude Code 自己的 Artifact 读取记录，仅当 Claude 获取会话可以发布的 Artifact 时出现。Claude Code 在会话恢复时读取它回来，以便稍后的发布基于正确的版本；您的代码不需要对其采取行动。`slug` 命名 Artifact，`ver` 是读取记录的版本，当它未记录任何内容时不存在，`seeded: false` 标记其完整源未到达 Claude 的读取。`seeded` 字段需要 Agent SDK v0.3.239 或更高版本。

4430 4437

4431<h3 id="websearch-2">4438<h3 id="websearch-2">

4432 WebSearch4439 WebSearch

4477 4484

4478| 字段 | 类型 | 描述 |4485| 字段 | 类型 | 描述 |

4479| - | - | - |4486| - | - | - |

4491 4498

4492<h3 id="todowrite-2">4499<h3 id="todowrite-2">

4625};4632};

4626```4633```

4627 4634

4628返回退出规划模式后的计划状态。4635返回退出计划模式后的计划状态。

4629 4636

4630<h3 id="listmcpresources-2">4637<h3 id="listmcpresources-2">

4631 ListMcpResources4638 ListMcpResources

4714};4721};

4715```4722```

4716 4723

4717返回进入规划模式的确认。4724返回进入计划模式的确认。

4718 4725

4719<h3 id="croncreate-2">4726<h3 id="croncreate-2">

4720 CronCreate4727 CronCreate

4876 rel?: "mine" | "shared";4883 rel?: "mine" | "shared";

4877 }>;4884 }>;

4878 truncated?: boolean;4885 truncated?: boolean;

4886 total?: number;

4887 total_at_least?: true;

4879 scope?: "shared" | "all";4888 scope?: "shared" | "all";

4880 };4889 };

4881```4890```

4882 4891

4883返回已发布页面的 `url` 和为发布操作发布的本地 `path`，当发布重新部署现有工件时 `updated` 设置为 true，`warnings` 携带任何发布时建议。列表操作返回 `artifacts` 行，当存在比请求限制更多的工件时 `truncated` 设置。在范围不是 `"mine"` 的列表上，每行携带 `rel` 标记用户是否拥有工件或与他们共享，输出的 `scope` 记录哪个非默认范围产生了列表；两者在默认列表上不存在。4892返回已发布页面的 `url` 和为发布操作发布的本地 `path`，当发布重新部署现有 Artifact 时 `updated` 设置为 true，`warnings` 携带任何发布时建议。列表操作返回 `artifacts` 行，当存在比请求限制更多的 Artifact 时 `truncated` 设置。在作用域不是 `"mine"` 的列表上，每行携带 `rel` 标记用户是否拥有该 Artifact 或该 Artifact 是与他们共享的，输出的 `scope` 记录哪个非默认作用域产生了列表；两者在默认列表上不存在。

4893

4894列表结果还会报告 `total`，即与所列作用域匹配的 Artifact 数量，包括超出 `limit` 的部分。设置 `total_at_least` 时，该数字是下界，可能还存在更多 Artifact。这两个字段都需要 Agent SDK v0.3.292 或更高版本。

4884 4895

4885<h3 id="projects-2">4896<h3 id="projects-2">

4886 Projects4897 Projects

agent-teams.md +2 −0

Details

1593. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/zh-CN/model-config#environment-variables)，当它设置为除 `inherit` 之外的任何值时。1593. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/zh-CN/model-config#environment-variables)，当它设置为除 `inherit` 之外的任何值时。

1604. 负责人的当前模型。1604. 负责人的当前模型。

161 161

162如果已安装的 [mod](/docs/zh-CN/plugins/mods/overview) 在其 [`agent.spawn`](/docs/zh-CN/plugins/mods/reference#subagents) hook 中设置了模型，Claude Code 会使用该模型代替第一个来源。

163

162如果你设置 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1`](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model)，前两个来源不适用。当 Claude Code 设置为除 `inherit` 之外的任何值时，Claude Code 从 `CLAUDE_CODE_SUBAGENT_MODEL` 为每个队友选择模型，否则从负责人的当前模型选择。需要 Claude Code v2.1.257 或更高版本。164如果你设置 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1`](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model)，前两个来源不适用。当 Claude Code 设置为除 `inherit` 之外的任何值时，Claude Code 从 `CLAUDE_CODE_SUBAGENT_MODEL` 为每个队友选择模型，否则从负责人的当前模型选择。需要 Claude Code v2.1.257 或更高版本。

163 165

164在 v2.1.251 之前，`CLAUDE_CODE_SUBAGENT_MODEL` 在此顺序中排在第一位。166在 v2.1.251 之前，`CLAUDE_CODE_SUBAGENT_MODEL` 在此顺序中排在第一位。

agent-view.md +12 −7

Details

226 226

227在窥视面板中输入回复并按 `Enter` 将其发送到该会话。在回复前加上 `!` 可改为发送 Bash 命令。回复的处理方式取决于会话以及您发送的内容：227在窥视面板中输入回复并按 `Enter` 将其发送到该会话。在回复前加上 `!` 可改为发送 Bash 命令。回复的处理方式取决于会话以及您发送的内容：

228 228

229* 正在工作的会话：回复会加入会话的[消息队列](/docs/zh-CN/interactive-mode#queue-messages-while-claude-works)而不是打断回复，并[在排队输入生效时](/docs/zh-CN/interactive-mode#when-claude-code-sends-what-you-queued)生效。[命令](/docs/zh-CN/commands)会等待当前轮次结束，即使是在会话自身的提示符处输入后会立即运行的命令229* 正在工作的会话：`/model`、`/effort`、`/rename` 和 `/usage` 会立即运行。其他回复会加入会话的[消息队列](/docs/zh-CN/interactive-mode#queue-messages-while-claude-works)而不是打断回复，并[在排队输入生效时](/docs/zh-CN/interactive-mode#when-claude-code-sends-what-you-queued)生效。其他[命令](/docs/zh-CN/commands)会等待当前轮次结束，即使是在会话自身的提示符处输入后会立即运行的命令

230* 恰好为 `/stop` 的回复：立即停止会话，而不是发送给会话，无论会话正在工作还是在等待您230* 恰好为 `/stop` 的回复：立即停止会话，而不是发送给会话，无论会话正在工作还是在等待您

231* [shell 作业](#run-a-shell-command)：回复（包括 `/stop`）会作为键入的输入发送到该命令的终端231* [shell 作业](#run-a-shell-command)：回复（包括 `/stop`）会作为键入的输入发送到该命令的终端

232 232

238 238

239当 [`PermissionRequest`](/docs/zh-CN/hooks#permissionrequest) 或 [`PreToolUse`](/docs/zh-CN/hooks#pretooluse) hook 针对会话正在询问的调用返回了 Claude Code 无法验证的输出时，该行会在待处理请求的文本之前显示 hook 事件以及 `hook output invalid:` 和验证错误。对于以其他方式失败的 hook，该行会说明 hook 失败。会话仍在等待同一个请求。239当 [`PermissionRequest`](/docs/zh-CN/hooks#permissionrequest) 或 [`PreToolUse`](/docs/zh-CN/hooks#pretooluse) hook 针对会话正在询问的调用返回了 Claude Code 无法验证的输出时，该行会在待处理请求的文本之前显示 hook 事件以及 `hook output invalid:` 和验证错误。对于以其他方式失败的 hook，该行会说明 hook 失败。会话仍在等待同一个请求。

240 240

241由于后台服务无法访问或发送失败而无法送达的回复会被保存，并在会话进程再次启动时作为其下一个提示词发送给会话，错误消息会说明回复已保存。以 `!` 开头的回复不会被保存，因为保存的文本会以普通提示词而不是 Bash 命令的形式送达会话。241当回复无法送达时，错误消息会说明它是否已保存。以 `!` 或 `/` 开头的回复永远不会被保存。下次您重启会话时，Claude Code 会将已保存的回复作为会话的下一个提示词发送；其他回复请重新发送。

242 242

243在[按住模式](/docs/zh-CN/voice-dictation#hold-to-record)下启用[语音听写](/docs/zh-CN/voice-dictation)后，在回复输入框获得焦点时按住您的按键通话键，即可通过听写而非键入来回复。agent view 底部的分派输入框中也同样适用。243在[按住模式](/docs/zh-CN/voice-dictation#hold-to-record)下启用[语音听写](/docs/zh-CN/voice-dictation)后，在回复输入框获得焦点时按住您的按键通话键，即可通过听写而非键入来回复。agent view 底部的分派输入框中也同样适用。

244 244

288 288

289在您用方向键或鼠标移动选择后，您按下 `←` 时所在的行仍会保持粗体、不暗淡的名称，便于您辨认自己来自哪个会话。289在您用方向键或鼠标移动选择后，您按下 `←` 时所在的行仍会保持粗体、不暗淡的名称，便于您辨认自己来自哪个会话。

290 290

291如果按 `←` 时有工具正在运行，Claude Code 会最多等待约十秒让其完成后再转入后台，Claude 会在后台会话中继续回复。再按一次 `←` 可立即转入后台而不等待。当进行中的工作无法转移到后台会话时，Claude Code 会先显示 `Background this session?` 对话框，与 [`/background`](#from-inside-a-session) 相同。291如果按 `←` 时有工具正在运行，Claude Code 会等待其完成后再转入后台，Claude 会在后台会话中继续回复。再按一次 `←` 可立即转入后台而不等待。当进行中的工作无法转移到后台会话时，Claude Code 会先显示 `Background this session?` 对话框，与 [`/background`](#from-inside-a-session) 相同。

292 292

293当 Claude 在对话中启动的[前台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)仍在运行时，十秒限制不适用。Claude Code 会继续等待以便转移它们的工作，并在等待期间显示 `Still backgrounding after the current tool` 通知。再按一次 `←` 可不等待直接转入后台，这会从头重新启动这些子代理。Claude Code 不会等待[动态工作流](/docs/zh-CN/workflows)正在运行的子代理。当工作流有子代理正在运行时，Claude Code 会改为显示 `Background this session?` 对话框。293大约十秒后，Claude Code 会不再等待，直接将会话转入后台，但以下情况等除外：

294 294

295当提示输入框中有未发送的文本时，Claude Code 不会将会话转入后台，因为这些文本会留在终端的输入框中，不会移到后台会话。如果您在 Claude Code 等待转入后台期间在输入框中输入内容，它会取消切换并显示 `Backgrounding cancelled — you have unsent text in the input. Send it or clear it, then press ← again.`295* **前台子代理仍在运行**：Claude Code 会继续等待，以便 Claude 启动的[前台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)的工作能够转移，并显示 `Still backgrounding after the current tool`。再按一次 `←` 可不等待直接转入后台，这会从头重新启动这些子代理。

296* **有权限提示或问题在等待您的回答**：当权限提示或 Claude 提出的问题处于等待状态时，Claude Code 会继续等待并显示 `Still backgrounding after the current tool — a question is waiting for your answer.`

297* **您在提示输入框中输入内容**：Claude Code 会取消切换，因为未发送的文本会留在终端的输入框中，不会移到后台会话。它会显示 `Backgrounding cancelled — you have unsent text in the input. Send it or clear it, then press ← again.`

298* **排队的消息无法移动**：您[在 Claude 工作时排队的消息](/docs/zh-CN/interactive-mode#queue-messages-while-claude-works)会随对话移到后台会话。当其中某条消息无法移动时，会话会留在前台，Claude Code 会显示类似 `Cannot open agents — 1 queued message can't move to the background. Press ← again once Claude has read it.` 的通知。

296 299

297即使对话还没有任何消息，按 `←` 也会创建该会话的行，因此 `→` 仍可返回该会话。300即使对话还没有任何消息，按 `←` 也会创建该会话的行，因此 `→` 仍可返回该会话。

298 301

876 879

877每个会话都是监督进程下的独立 Claude Code 进程，该进程发生的情况取决于会话的状态：880每个会话都是监督进程下的独立 Claude Code 进程，该进程发生的情况取决于会话的状态：

878 881

879* **工作中、暂停在权限提示或其他对话框上，或已连接**：进程继续运行。运行中的子代理、工作流或监视器计为工作中。882* **工作中、暂停在权限提示或其他对话框上，或已连接**：进程继续运行。运行中的子代理、工作流或监视器计为工作中，待执行的[会话范围定时任务](/docs/zh-CN/scheduled-tasks)（例如 `/loop` 唤醒）也同样计为工作中。

880* **已完成或等待您的下一条消息，且未连接约一小时**：监督进程停止该进程以释放资源。以向您提问结束其轮次的会话计为等待您的下一条消息。对话保存在磁盘上，下次您连接或回复时，会话从中断处恢复。使用 `Ctrl+T` 固定会话以保持其进程运行。883* **已完成或等待您的下一条消息，且未连接约一小时**：监督进程停止该进程以释放资源。以向您提问结束其轮次的会话计为等待您的下一条消息。对话保存在磁盘上，下次您连接或回复时，会话从中断处恢复。使用 `Ctrl+T` 固定会话以保持其进程运行。

881* **在监督进程运行时意外退出**：监督进程重新启动该进程。如果通过 `kill` 等方式结束您自己使用 `←` 或 `/background` 后台化的会话，该会话会被标记为已停止，而不是重新启动。对于以关闭结束的会话，请参阅[会话在关闭后显示为失败或已停止](#sessions-show-as-failed-after-shutdown)。884* **在监督进程运行时意外退出**：监督进程重新启动该进程。如果通过 `kill` 等方式结束您自己使用 `←` 或 `/background` 后台化的会话，该会话会被标记为已停止，而不是重新启动。对于以关闭结束的会话，请参阅[会话在关闭后显示为失败或已停止](#sessions-show-as-failed-after-shutdown)。

882* **自动更新后**：监督进程重新启动自身到新版本，并在后台移动空闲会话。工作中、等待您或已连接的会话不会被中断。885* **自动更新后**：监督进程重新启动自身到新版本，并在后台移动空闲会话。工作中、等待您或已连接的会话不会被中断。

970* 您恢复对话的终端，例如使用 `claude --resume` 或 `/resume`：该行显示 `Open in a terminal`，并提示在那里继续，打开该行显示 `Can't open — this session is running in another terminal`。在该终端中继续，或退出它并再次打开该行。973* 您恢复对话的终端，例如使用 `claude --resume` 或 `/resume`：该行显示 `Open in a terminal`，并提示在那里继续，打开该行显示 `Can't open — this session is running in another terminal`。在该终端中继续，或退出它并再次打开该行。

971* 另一个非交互式 Claude Code 进程，例如同一对话的后台会话进程，尚未退出：打开该行显示 `This conversation is already open in another running Claude session`。使用该进程，或等待它退出并再次打开该行。974* 另一个非交互式 Claude Code 进程，例如同一对话的后台会话进程，尚未退出：打开该行显示 `This conversation is already open in another running Claude session`。使用该进程，或等待它退出并再次打开该行。

972 975

973Claude Code 保存您在被拒绝的尝试中输入的回复，并在会话下次启动时发送它。976Claude Code 保存您在被拒绝的尝试中输入的回复（以 `!` 或 `/` 开头的回复除外），并在会话下次启动时发送它。

974 977

975<h3 id="opening-a-session-says-it-has-no-saved-transcript">978<h3 id="opening-a-session-says-it-has-no-saved-transcript">

976 打开会话说它没有保存的会话记录979 打开会话说它没有保存的会话记录

1093| 版本 | 更改 |1096| 版本 | 更改 |

1094| - | - |1097| - | - |

1095| v2.1.290 | [`claude attach` 和 `claude logs`](#manage-sessions-from-the-shell) 可以使用正在运行的会话名称的一部分来代替 ID。 |1098| v2.1.290 | [`claude attach` 和 `claude logs`](#manage-sessions-from-the-shell) 可以使用正在运行的会话名称的一部分来代替 ID。 |

1099| v2.1.290 | `/model`、`/effort`、`/rename` 和 `/usage` 作为[窥视回复](#peek-and-reply)发送给正在工作的会话时会立即运行。 |

1100| v2.1.290 | 无法投递的[窥视回复](#peek-and-reply)如果以 `/` 开头，或者在会话进程运行期间回答的是带有预定义选项的问题，则不再被保存以待下次重启时发送。 |

1096| v2.1.288 | `Ctrl+F` 按名称查找会话，`Alt+↑` / `Alt+↓` 在组标题之间跳转。这两者以及 `Ctrl+R` 都可以[重新绑定](/docs/zh-CN/keybindings#agents-actions)。 |1101| v2.1.288 | `Ctrl+F` 按名称查找会话，`Alt+↑` / `Alt+↓` 在组标题之间跳转。这两者以及 `Ctrl+R` 都可以[重新绑定](/docs/zh-CN/keybindings#agents-actions)。 |

1097| v2.1.287 | [`n:<text>` 筛选器](#filter-sessions)按名称或第一个提示词查找会话。当任何筛选器处于活动状态时，您折叠的组会展开以显示其匹配项，并且第一个匹配项被选中，因此 `Enter` 会打开它。 |1102| v2.1.287 | [`n:<text>` 筛选器](#filter-sessions)按名称或第一个提示词查找会话。当任何筛选器处于活动状态时，您折叠的组会展开以显示其匹配项，并且第一个匹配项被选中，因此 `Enter` 会打开它。 |

1098| v2.1.287 | 作为[窥视回复](#peek-and-reply)发送的命令会在会话当前轮次结束时运行，包括在会话自身的输入框中一键入就立即运行的命令。内容恰好为 `/stop` 的回复会立即停止会话。 |1103| v2.1.287 | 作为[窥视回复](#peek-and-reply)发送的命令会在会话当前轮次结束时运行，包括在会话自身的输入框中一键入就立即运行的命令。内容恰好为 `/stop` 的回复会立即停止会话。 |

amazon-bedrock.md +49 −12

Details

136 2. 配置 AWS 凭证136 2. 配置 AWS 凭证

137</h3>137</h3>

138 138

139Claude Code 使用默认 AWS SDK 凭证链。使用以下方法之一设置您的凭证：139Claude Code 使用默认 AWS SDK 凭据链。如果机器已经向该链提供凭据，例如 Amazon EC2 实例配置文件或 Amazon ECS 任务凭据，请直接跳到[第 3 步](#3-configure-claude-code)。

140 140

141**选项 A：AWS CLI 配置**141AWS [不建议在开发专用软件或处理真实数据时使用 IAM 用户的访问密钥](https://docs.aws.amazon.com/cli/latest/userguide/cli-authentication-user.html)。使用以下方法之一设置您的凭据：

142

143* [`aws configure`](#use-aws-configure)：将 IAM 用户的访问密钥保存到 `~/.aws` 目录中的配置文件

144* [访问密钥环境变量](#export-an-access-key)：仅在当前 shell 中设置访问密钥，或带会话令牌的临时凭据

145* [SSO 配置文件](#use-an-sso-profile)：在浏览器中通过 IAM Identity Center 登录并获取临时凭据。如果您通过 IAM Identity Center 访问 AWS 账户，请使用此方法。

146* [AWS 管理控制台凭据](#use-aws-management-console-credentials)：在浏览器中使用您的 AWS 管理控制台凭据登录并获取临时凭据。如果您以根用户、IAM 用户身份或通过 IAM 联合身份访问 AWS 账户，AWS [推荐此方法](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html)。

147* [Amazon Bedrock API 密钥](#use-an-amazon-bedrock-api-key)：使用仅适用于 Amazon Bedrock 的持有者令牌进行身份验证，而不是使用 AWS 凭据

148

149<h4 id="use-aws-configure">

150 使用 `aws configure`

151</h4>

152

153运行 `aws configure`，并在提示时输入您的访问密钥 ID、秘密访问密钥和默认区域：

142 154

143```bash theme={null}155```bash theme={null}

144aws configure156aws configure

145```157```

146 158

147**选项 B：环境变量（访问密钥）**159AWS CLI 会将密钥保存到 `~/.aws/credentials` 中的 `default` 配置文件，凭据链会从那里读取它。

160

161<h4 id="export-an-access-key">

162 导出访问密钥

163</h4>

164

165将您的访问密钥导出为环境变量。`AWS_SESSION_TOKEN` 仅在使用临时凭据时需要，因此如果您的访问密钥属于 IAM 用户，请省略该行：

148 166

149```bash theme={null}167```bash theme={null}

150export AWS_ACCESS_KEY_ID=your-access-key-id168export AWS_ACCESS_KEY_ID=your-access-key-id

152export AWS_SESSION_TOKEN=your-session-token170export AWS_SESSION_TOKEN=your-session-token

153```171```

154 172

155**选项 C：环境变量（SSO 配置文件）**173<h4 id="use-an-sso-profile">

174 使用 SSO 配置文件

175</h4>

156 176

157在运行这些命令之前，将 `your-profile-name` 替换为您的 AWS 配置文件的名称。177如果您还没有配置文件，请使用 `aws configure sso` 创建一个。然后登录 IAM Identity Center 并设置 `AWS_PROFILE`，使凭据链使用该配置文件。在运行这些命令之前，将 `your-profile-name` 替换为您的 AWS 配置文件的名称。

158 178

159```bash theme={null}179```bash theme={null}

160aws sso login --profile=your-profile-name180aws sso login --profile=your-profile-name

164 184

165Claude Code 从配置文件的 `sso_region` 命名的 IAM Identity Center 区域请求角色凭证，这不需要与您运行 Amazon Bedrock 的区域匹配。在 v2.1.207 中，Amazon Bedrock 区域覆盖了 `sso_region`，因此 IAM Identity Center 实例在不同区域的配置文件无法使用 `Session token not found or invalid` 错误进行身份验证。185Claude Code 从配置文件的 `sso_region` 命名的 IAM Identity Center 区域请求角色凭证，这不需要与您运行 Amazon Bedrock 的区域匹配。在 v2.1.207 中，Amazon Bedrock 区域覆盖了 `sso_region`，因此 IAM Identity Center 实例在不同区域的配置文件无法使用 `Session token not found or invalid` 错误进行身份验证。

166 186

167**选项 D：AWS 管理控制台凭证**187<h4 id="use-aws-management-console-credentials">

188 使用 AWS 管理控制台凭据

189</h4>

190

191`aws login` 命令需要 AWS CLI 2.32.0 或更高版本。有关您的身份所需的 IAM 策略，请参阅 [AWS 关于 `aws login` 的说明](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html)。

192

193运行以下命令，在浏览器中使用您的 AWS 管理控制台凭据登录：

168 194

169```bash theme={null}195```bash theme={null}

170aws login196aws login

171```197```

172 198

173[了解更多](https://docs.aws.amazon.com/signin/latest/userguide/command-line-sign-in.html)关于 `aws login`。199会话最长有效 12 小时，之后需要再次运行 `aws login`。

200

201<h4 id="use-an-amazon-bedrock-api-key">

202 使用 Amazon Bedrock API 密钥

203</h4>

204

205Amazon Bedrock API 密钥是一种持有者令牌，可代替 AWS 凭据对您的请求进行身份验证。AWS 提供[两种类型的密钥](https://docs.aws.amazon.com/bedrock/latest/userguide/api-keys.html)：

174 206

175**选项 E：Amazon Bedrock API 密钥**207* **短期密钥**：最长有效 12 小时。对于生产环境，AWS 更推荐使用短期密钥而非长期密钥。

208* **长期密钥**：在您设置的到期日期之前一直有效。AWS 仅建议将其用于探索。

209

210将密钥导出为 `AWS_BEARER_TOKEN_BEDROCK`：

176 211

177```bash theme={null}212```bash theme={null}

178export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key213export AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

179```214```

180 215

181Amazon Bedrock API 密钥提供了一种更简单的身份验证方法，无需完整的 AWS 凭证。[了解更多关于 Amazon Bedrock API 密钥](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)。216设置 `AWS_BEARER_TOKEN_BEDROCK` 后，Claude Code 会使用该密钥进行身份验证，并且不会解析凭据链，即使存在其他 AWS 凭据也是如此。[了解更多关于 Amazon Bedrock API 密钥](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)。

182 217

183<h4 id="credential-caching-and-resolution-timeout">218<h4 id="credential-caching-and-resolution-timeout">

184 凭证缓存和解析超时219 凭证缓存和解析超时

186 221

187Claude Code 解析 AWS 默认凭证提供程序链一次，并将解析的凭证保存在内存中。它重复使用这些凭证，直到它们过期前五分钟，或在没有过期时间时使用一小时，因此 SSO 支持的配置文件大约每个凭证生命周期从 IAM Identity Center 请求一次凭证。来自 API 的凭证错误会清除缓存，重试会解析新凭证。需要 Claude Code v2.1.207 或更高版本。222Claude Code 解析 AWS 默认凭证提供程序链一次，并将解析的凭证保存在内存中。它重复使用这些凭证，直到它们过期前五分钟，或在没有过期时间时使用一小时，因此 SSO 支持的配置文件大约每个凭证生命周期从 IAM Identity Center 请求一次凭证。来自 API 的凭证错误会清除缓存，重试会解析新凭证。需要 Claude Code v2.1.207 或更高版本。

188 223

189缓存涵盖上述所有凭证选项，除了 Amazon Bedrock API 密钥，它不使用提供程序链。要在每个请求上解析链，请改为设置 [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/zh-CN/env-vars)。224缓存涵盖此步骤开头列出的所有凭据方法，但 Amazon Bedrock API 密钥除外，它不使用提供程序链。要在每个请求上解析链，请改为设置 [`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/zh-CN/env-vars)。

190 225

191填充缓存的解析在 60 秒后超时。如果链中的某个步骤停滞，例如等待无法接收的输入的 `credential_process` 帮助程序，请求会失败并显示 [`AWS default-chain credential resolve timed out`](/docs/zh-CN/errors#aws-default-chain-credential-resolve-timed-out)。如果您的链运行合法需要更长时间的交互式登录，例如通过 `aws-vault` 等包装器进行基于浏览器的 SSO 和 MFA，请使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-CN/env-vars) 以毫秒为单位提高限制。设置 `CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1` 后，每个 API 请求解析链时不受此限制。226填充缓存的解析在 60 秒后超时。如果链中的某个步骤停滞，例如等待无法接收的输入的 `credential_process` 帮助程序，请求会失败并显示 [`AWS default-chain credential resolve timed out`](/docs/zh-CN/errors#aws-default-chain-credential-resolve-timed-out)。如果您的链运行合法需要更长时间的交互式登录，例如通过 `aws-vault` 等包装器进行基于浏览器的 SSO 和 MFA，请使用 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/zh-CN/env-vars) 以毫秒为单位提高限制。设置 `CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1` 后，每个 API 请求解析链时不受此限制。

192 227

509 1M 令牌上下文窗口544 1M 令牌上下文窗口

510</h2>545</h2>

511 546

512Claude Sonnet 5、Opus 4.6 及更高版本，以及 Sonnet 4.6 在 Amazon Bedrock 上支持 [1M 令牌上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)。Sonnet 5 在 Invoke API 和 [Mantle 端点](#use-the-mantle-endpoint)上始终以 1M 窗口运行，没有 `[1m]` 变体可选择。对于 Invoke API 上的其他模型，当您选择 1M 模型变体时，Claude Code 会自动启用扩展上下文窗口。547Fable 模型、Sonnet 5 及更高版本，以及 Opus 4.7 及更高版本在 Amazon Bedrock 上默认以 [1M token 上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)运行，Invoke API 和 [Mantle 端点](#use-the-mantle-endpoint)均是如此，无需 `[1m]` 后缀。当 [`modelOverrides`](#map-each-model-version-to-an-inference-profile) 条目将其模型映射到应用程序推理配置文件 ARN 时，该 ARN 将获得 1M 窗口。如需改为保留 200K 窗口，请设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-CN/model-config#turn-off-1m-context)。

548

549在 Invoke API 上，当您选择 Opus 4.6 和 Sonnet 4.6 的 `[1m]` 变体时，它们将使用 1M 窗口。[设置向导](#sign-in-with-bedrock)在固定模型时提供 1M 上下文选项。如需改为为手动固定的模型启用它，请在模型 ID 后附加 `[1m]`。请参阅[为第三方部署固定模型](/docs/zh-CN/model-config#pin-models-for-third-party-deployments)了解详情，包括如何在不更改固定的情况下使用 1M 窗口。

513 550

514[设置向导](#sign-in-with-bedrock)在固定模型时提供 1M 上下文选项。要为手动固定的模型启用它，请在模型 ID 后附加 `[1m]`。请参阅[为第三方部署固定模型](/docs/zh-CN/model-config#pin-models-for-third-party-deployments)了解详情，包括如何在不更改固定的情况下使用 1M 窗口。551在 v2.1.287 之前，Fable 模型以及 Opus 4.7 及更高版本在 Invoke API 上默认以 200K 窗口运行，需通过 `[1m]` 后缀才能在其上使用 1M 窗口。

515 552

516<h2 id="service-tiers">553<h2 id="service-tiers">

517 服务层级554 服务层级

artifacts.md +38 −10

Details

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

52```52```

53 53

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

55 55

56工件对你保持私密，直到你[共享它](#share-an-artifact)。在你公开共享后，Claude Code 会在每次对话中要求你的批准一次后再更改它，或在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)下让分类器审查更改。56首次发布后，Claude 会打印 URL，您的浏览器会打开新页面。

57 57

58如果你关闭了[功能标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)，Claude Code 会在每个工件的首次发布前询问，或在自动模式下让分类器审查它。58* **重新打开页面**：随时按 `Ctrl+]` 可重新打开会话中最近的 Artifact

59* **查看本会话的 Artifact**：输入框下方的 `⧉` 标签会显示 Artifact 的名称，当会话中有多个 Artifact 时则显示数量。在[全屏渲染](/docs/zh-CN/fullscreen)中，点击它可打开 [`/artifacts`](#find-an-artifact-again) 列表

60* **阻止浏览器自动打开**：在您的环境中设置 `CLAUDE_CODE_ARTIFACT_AUTO_OPEN=0`

61* **Remote Control**：如果您通过 [Remote Control](/docs/zh-CN/remote-control) 从 claude.ai、Claude Desktop 或 Claude 移动应用发送提示词，运行会话的机器上不会打开标签页。下次 Claude 根据您在终端中输入的提示词发布该 Artifact 时，浏览器会在那台机器上打开

59 62

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

61 64

62Claude 会选择工件的标题和一个表情符号，两者都会出现在你在 claude.ai 上的[工件库](#share-an-artifact)和共享链接中。Claude 还可以选择与页面内容相匹配的浏览器标签页图标，例如图表或日历。如果你想要特定的标题、表情符号或标签页图标，请告诉 Claude。65如果 Claude 回复说无法发布，或者写入了本地 HTML 文件但没有提供链接，则说明您的会话未启用 Artifact。请检查[可用性](#availability)要求。如果终端显示 `Artifacts need a claude.ai login`，请参阅[该错误的条目](/docs/zh-CN/errors#artifacts-need-a-claude-ai-login)了解如何登录。

63 66

~~64要停止在发布新工件时自动打开浏览器，请在你的环境中设置 `CLAUDE_CODE_ARTIFACT_AUTO_OPEN=0`。~~67<h3 id="when-claude-code-asks-before-publishing">

68 Claude Code 何时会在发布前询问

69</h3>

71Claude 根据您输入的提示词发布的新 Artifact 会直接通过，无需权限提示或分类器审查。在以下情况下，Claude Code 会先询问您，或在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)下让分类器审查该发布：

65 72

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

74| :- | :- |

75| 会话处于[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode) | 在每个 Artifact 首次发布前询问 |

76| 该发布声明了页面的运行时功能，例如[连接器调用](#pull-live-data-with-mcp-connectors)或[文件下载](#offer-a-file-download) | 在该次发布前询问 |

77| 您已公开共享该 Artifact | 每个对话中在更改它之前询问一次 |

78| 您关闭了[功能标志获取](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) | 在每个 Artifact 首次发布前询问 |

79| Claude 在由会话中触发的[定时任务](/docs/zh-CN/scheduled-tasks)（而非您输入的提示词）启动的轮次中发布 | 在每个 Artifact 首次发布前询问 |

80| Claude 未经您批准无法读取该文件 | 在发布前询问。针对 `Artifact` 工具的允许规则不会跳过此提示 |

82Claude 可以无需询问即读取会话[工作目录](/docs/zh-CN/permissions#working-directories)中的文件，以及它写入页面所用的临时目录中的文件。要让 Claude 从其他文件夹发布而不弹出提示，请在启动时使用 [`--add-dir`](/docs/zh-CN/cli-reference#cli-flags) 或在会话期间使用 `/add-dir` 将该文件夹添加为工作目录。

67 83

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

69 更新一个 artifact85 更新一个 artifact

87 再次查找一个artifact103 再次查找一个artifact

88</h2>104</h2>

89 105

90在Claude Code中运行`/artifacts`以列出您拥有的每个artifact和与您共享的每个artifact。选择一个并按`o`在浏览器中打开它，或按`c`复制其链接。按`Enter`将其附加到当前会话；在v2.1.216之前，`Enter`在浏览器中打开它。Claude Code从您的claude.ai账户读取列表，因此它在新会话中工作，在`/clear`之后工作，当链接已从终端滚出时也能工作。需要Claude Code v2.1.208或更高版本。106在Claude Code中运行`/artifacts`，以列出您拥有的Artifact以及与您共享的Artifact。当前会话的Artifact排在最前面，位于**This session**下。需要Claude Code v2.1.208或更高版本。

107

108选择一个Artifact，然后按以下任一按键：

109

110* **`Enter`**：如果它已附加到当前会话，则在浏览器中打开它；如果尚未附加，则将其附加到当前会话。在v2.1.216之前，`Enter`会在浏览器中打开它

111* **`o`**：在浏览器中打开它

112* **`c`**：复制其链接

113

114Claude Code从您的claude.ai账户读取列表，因此它在新会话中以及在`/clear`之后都能工作，即使链接已从终端滚出也能使用。

91 115

92<h2 id="share-an-artifact">116<h2 id="share-an-artifact">

93 分享一个artifact117 分享一个artifact

110 134

111编辑者发布新版本的方式与你[从另一个会话更新artifact](#update-an-artifact)的方式相同：他们向Claude提供artifact的URL，或从[`/artifacts`](#find-an-artifact-again)附加它，Claude会拉取当前内容并用他们的更改重新发布。打开该页面的每个人都会实时看到每个更新。135编辑者发布新版本的方式与你[从另一个会话更新artifact](#update-an-artifact)的方式相同：他们向Claude提供artifact的URL，或从[`/artifacts`](#find-an-artifact-again)附加它，Claude会拉取当前内容并用他们的更改重新发布。打开该页面的每个人都会实时看到每个更新。

112 136

137如果编辑者发布时Claude持有的是该页面的旧副本，Claude Code会拒绝基于该副本的发布。随后Claude会将其更改合并到较新的版本上并再次发布。

138

113<h2 id="read-an-artifact-shared-with-you">139<h2 id="read-an-artifact-shared-with-you">

114 阅读与你共享的工件140 阅读与你共享的工件

115</h2>141</h2>

168 194

169Claude 还会在处理该工件上的 60 条已发送评论或线程激活后的一小时内停止自动回复该工件。您会看到`评论正在等待工件：<name>`一次，当该小时的评论过期时，Claude 会重新开始。195Claude 还会在处理该工件上的 60 条已发送评论或线程激活后的一小时内停止自动回复该工件。您会看到`评论正在等待工件：<name>`一次，当该小时的评论过期时，Claude 会重新开始。

170 196

171运行 `/tasks` 查看您的会话正在监视的每个工件，列为实时更新任务。您可以通过以下任何方式停止 Claude 自动回复：197运行 `/tasks` 查看您的会话正在监视的 Artifact。`/tasks` 会将 Claude Code 自行启动的监视归入 **System tasks** 行下。在该行上按 `Enter` 即可列出它们。您要求 Claude 启动的监视显示在 **Monitors** 下。

198

199您可以通过以下任何方式停止 Claude 自动回复：

172 200

173* **在空闲提示符处按一次 Ctrl+C**：Claude 暂停回复您的会话正在监视的每个工件。在您发送下一条消息后，回复会重新开始。201* **在空闲提示符处按一次 Ctrl+C**：Claude 暂停回复您的会话正在监视的每个工件。在您发送下一条消息后，回复会重新开始。

174* **在 `/tasks` 中停止任务**：Claude 停止回复该工件，直到您要求它在那里恢复回复。重新发布工件不会再次启动回复，当您稍后恢复会话时，停止仍然适用。202* **在 `/tasks` 中停止任务**：Claude 停止回复该工件，直到您要求它在那里恢复回复。重新发布工件不会再次启动回复，当您稍后恢复会话时，停止仍然适用。

391| 身份验证 | 会话由 claude.ai 账户支持：在 CLI 或桌面应用中使用 `/login` 登录。Claude Tag 会话通过代理的身份登录，因此不需要任何步骤。使用 API 密钥、[网关令牌](/docs/zh-CN/llm-gateway) 或云提供商凭证的会话无法发布。 |419| 身份验证 | 会话由 claude.ai 账户支持：在 CLI 或桌面应用中使用 `/login` 登录。Claude Tag 会话通过代理的身份登录，因此不需要任何步骤。使用 API 密钥、[网关令牌](/docs/zh-CN/llm-gateway) 或云提供商凭证的会话无法发布。 |

392| 模型提供商 | Anthropic API。在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上不可用。 |420| 模型提供商 | Anthropic API。在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 或 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上不可用。 |

393| 组织策略 | 客户管理的加密密钥 (CMEK)、HIPAA 和 [零数据保留](/docs/zh-CN/zero-data-retention) 未为组织启用。 |421| 组织策略 | 客户管理的加密密钥 (CMEK)、HIPAA 和 [零数据保留](/docs/zh-CN/zero-data-retention) 未为组织启用。 |

394| 表面 | Claude Code CLI，或 Claude 桌面应用版本 1.13576.0 或更高版本。当 Claude Tag 和 artifacts 都为组织启用时，[Claude Tag](https://claude.com/docs/claude-tag/overview) 会话也可以发布 artifacts。在 [Agent SDK](/docs/zh-CN/agent-sdk/overview)、GitHub Action 和 MCP-server 上下文中默认关闭，以及当设置 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-CN/env-vars) 时。 |422| 使用入口 | Claude Code CLI，或 Claude 桌面应用版本 1.13576.0 或更高版本。当 Claude Tag 和 artifacts 都为组织启用时，[Claude Tag](https://claude.com/docs/claude-tag/overview) 会话也可以发布 artifacts。由 [`claude remote-control`](/docs/zh-CN/remote-control) 提供服务的会话，在会话由您自己启动时可以发布 artifacts。需要 Claude Code v2.1.281 或更高版本。在 [Agent SDK](/docs/zh-CN/agent-sdk/overview)、GitHub Action 和 MCP 服务器上下文中默认关闭；当您从自己的终端或脚本中使用 [`-p`](/docs/zh-CN/headless) 运行 Claude Code 时，以及设置了 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-CN/env-vars) 时，也默认关闭。 |

395 423

396您的组织是否允许 artifacts 来自您的组织策略，Claude Code 从 `api.anthropic.com` 加载。当 Claude Code 无法加载策略时，artifacts 不可用。当您请求一个时，Claude 会说明原因。424您的组织是否允许 artifacts 来自您的组织策略，Claude Code 从 `api.anthropic.com` 加载。当 Claude Code 无法加载策略时，artifacts 不可用。当您请求一个时，Claude 会说明原因。

397 425

authentication.md +0 −2

Details

142* **它将您登出的内容**：Claude Code 将您登出存储在机器上的任何 claude.ai 登录142* **它将您登出的内容**：Claude Code 将您登出存储在机器上的任何 claude.ai 登录

143* **如何撤销它**：运行 `/logout`，它会删除并撤销此登录写入的凭证143* **如何撤销它**：运行 `/logout`，它会删除并撤销此登录写入的凭证

144 144

145如果您的组织使用 [服务器托管设置](/docs/zh-CN/server-managed-settings)，它们会在 Claude Code v2.1.257 或更高版本上应用于此登录。

~~146~~

147关于配置文件的所有其他内容都适用于此登录，包括它在您的其他凭证中的排名、您在 `/status` 中获得的 `Profile` 行，以及需要 claude.ai 登录的功能。请参阅 [Anthropic 配置文件和联合凭证](#anthropic-profiles-and-federation-credentials)。145关于配置文件的所有其他内容都适用于此登录，包括它在您的其他凭证中的排名、您在 `/status` 中获得的 `Profile` 行，以及需要 claude.ai 登录的功能。请参阅 [Anthropic 配置文件和联合凭证](#anthropic-profiles-and-federation-credentials)。

148 146

149<h3 id="cloud-provider-authentication">147<h3 id="cloud-provider-authentication">

claude-apps-gateway.md +2 −1

Details

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

304</h3>304</h3>

305 305

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

307 307

308<Warning>308<Warning>

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

521| 功能 | 状态 | 注释 |521| 功能 | 状态 | 注释 |

522| - | - | - |522| - | - | - |

523| 推理转发 (Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry、Anthropic) | 可用 | 具有按上游模型转换和故障转移。Amazon Bedrock 上游使用 `bedrock-runtime` 端点和 AWS 默认凭据链。[Amazon Bedrock Mantle 上游](/docs/zh-CN/claude-apps-gateway-config#amazon-bedrock-mantle-endpoint)需要网关服务器上的 Claude Code v2.1.283 或更高版本，[Claude Platform on AWS 上游](/docs/zh-CN/claude-apps-gateway-config#claude-platform-on-aws)需要 v2.1.198 或更高版本。 |523| 推理转发 (Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry、Anthropic) | 可用 | 具有按上游模型转换和故障转移。Amazon Bedrock 上游使用 `bedrock-runtime` 端点和 AWS 默认凭据链。[Amazon Bedrock Mantle 上游](/docs/zh-CN/claude-apps-gateway-config#amazon-bedrock-mantle-endpoint)需要网关服务器上的 Claude Code v2.1.283 或更高版本，[Claude Platform on AWS 上游](/docs/zh-CN/claude-apps-gateway-config#claude-platform-on-aws)需要 v2.1.198 或更高版本。 |

524| 1M token 上下文窗口 | 可用 | Fable 模型、Sonnet 5 及更高版本以及 Opus 4.7 及更高版本默认使用 1M 窗口运行；请参阅[扩展上下文](/docs/zh-CN/model-config#extended-context)。Fable 和 Opus 模型的 1M 默认值需要开发人员机器上的 Claude Code v2.1.287 或更高版本 |

524| 按 IdP 组的模型访问和托管设置 | 可用 | 模型访问在服务器端强制执行；托管设置按 IdP 组交付，由 CLI 在[托管设置层](/docs/zh-CN/settings#settings-precedence)应用 |525| 按 IdP 组的模型访问和托管设置 | 可用 | 模型访问在服务器端强制执行；托管设置按 IdP 组交付，由 CLI 在[托管设置层](/docs/zh-CN/settings#settings-precedence)应用 |

525| Claude Desktop | 可用（需要选择加入） | 网关在 `/user/bootstrap` 处为 Claude Desktop 的配置提供服务，一旦策略[使用 `desktop` 密钥选择加入](/docs/zh-CN/claude-apps-gateway-config#claude-desktop-overlay)，Claude Desktop 从其 Cowork 和 Code 选项卡以及从 Chat 选项卡（当您启用它时）发送模型请求通过网关。要打开 Chat 选项卡，请参阅[连接 Claude Desktop](#connect-claude-desktop)。需要网关服务器上的 Claude Code v2.1.203 或更高版本。 |526| Claude Desktop | 可用（需要选择加入） | 网关在 `/user/bootstrap` 处为 Claude Desktop 的配置提供服务，一旦策略[使用 `desktop` 密钥选择加入](/docs/zh-CN/claude-apps-gateway-config#claude-desktop-overlay)，Claude Desktop 从其 Cowork 和 Code 选项卡以及从 Chat 选项卡（当您启用它时）发送模型请求通过网关。要打开 Chat 选项卡，请参阅[连接 Claude Desktop](#connect-claude-desktop)。需要网关服务器上的 Claude Code v2.1.203 或更高版本。 |

526| 遥测扇出 (OTLP/HTTP) | 可用 | 按导出标识戳；protobuf 和 JSON 编码 |527| 遥测扇出 (OTLP/HTTP) | 可用 | 按导出标识戳；protobuf 和 JSON 编码 |

claude-apps-gateway-deploy.md +22 −7

Details

6 6

7> 向身份提供商注册网关，构建容器，在 Kubernetes 或 Cloud Run 上部署，并运维它：健康检查、密钥轮换、升级和安全。7> 向身份提供商注册网关，构建容器，在 Kubernetes 或 Cloud Run 上部署，并运维它：健康检查、密钥轮换、升级和安全。

8 8

9<Info>

10 **请先规划网关的网络。** 登录时，如果 Claude 应用网关的主机名解析为公共 IP 地址，Claude Code 会拒绝连接，即使该地址无法从互联网访问也是如此。

12 Claude 应用网关可以向用户的机器推送设置，包括运行 shell 命令的 hook。此检查有助于防止用户意外登录到公共互联网上的恶意网关。也请不要让您自己的网关暴露在互联网上。

14 在选择网关的运行位置之前，请先选择网关的地址。通常这是一个私有地址，用户可以在内部网络上或通过 VPN 访问。如果您的内部网络使用公共 IPv4 地址段，您可以列出一个同时包含网关和用户机器的地址段。Claude Code 会将该匹配视为网关位于您内部网络上的标志。请参阅 [为网关选择地址](#choose-an-address-for-the-gateway)。如果以上两种方式都不适合您的网络，请联系您的 Anthropic 客户团队。

15</Info>

9本页面涵盖运行 [Claude 应用网关](/docs/zh-CN/claude-apps-gateway) 的运维方面：在身份提供商 (IdP) 中注册 OAuth 客户端、将网关部署为容器，以及日常运行。关于网关在启动时读取的 `gateway.yaml` 文件中的每个选项，请参阅 [配置参考](/docs/zh-CN/claude-apps-gateway-config)。17本页面涵盖运行 [Claude 应用网关](/docs/zh-CN/claude-apps-gateway) 的运维方面：在身份提供商 (IdP) 中注册 OAuth 客户端、将网关部署为容器，以及日常运行。关于网关在启动时读取的 `gateway.yaml` 文件中的每个选项，请参阅 [配置参考](/docs/zh-CN/claude-apps-gateway-config)。

10 18

11生产部署按顺序遵循四个步骤，下面的部分与之相对应。前两个是您做出选择的地方；后两个是在运行后参考的材料。19生产部署按顺序遵循四个步骤，下面的部分与之相对应。前两个是您做出选择的地方；后两个是在运行后参考的材料。

17 25

18如果在此过程中登录或启动失败，请直接转到 [故障排除](#troubleshooting)，该部分按您看到的错误进行索引。26如果在此过程中登录或启动失败，请直接转到 [故障排除](#troubleshooting)，该部分按您看到的错误进行索引。

19 27

~~20<Note>~~

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

~~22</Note>~~

24<h2 id="identity-provider-setup">28<h2 id="identity-provider-setup">

25 身份提供商设置29 身份提供商设置

26</h2>30</h2>

51 部署55 部署

52</h2>56</h2>

53 57

54网关是一个单一的无状态 Linux 二进制文件，通过 Postgres 进行协调，因此按照您在环境中部署任何其他无状态服务的方式部署它。将其保持在您的网络内，您的开发者和 IdP 可以通过 HTTPS 到达它，并将其视为任何持有生产凭证的服务。58网关是一个单一的无状态 Linux 二进制文件，通过 Postgres 进行协调，因此按照您在环境中部署任何其他无状态服务的方式部署它。将其保持在您的网络内，您的开发者和 IdP 可以通过 HTTPS 到达它，并将其视为任何持有生产凭据的服务。

55 59

56除了运行位置外，还有一些决策塑造部署：60除了运行位置外，还有一些决策塑造部署：

57 61

71 75

72默认值（如 ALB 的 60 秒）足以保持安静的流打开。[AWS 工作示例](/docs/zh-CN/claude-apps-gateway-on-aws#troubleshooting) 无论如何将其提高到一小时，其故障排除行涵盖早于 v2.1.229 的网关，这些网关在现在获得 ping 的上游上的安静期间没有发送任何内容。76默认值（如 ALB 的 60 秒）足以保持安静的流打开。[AWS 工作示例](/docs/zh-CN/claude-apps-gateway-on-aws#troubleshooting) 无论如何将其提高到一小时，其故障排除行涵盖早于 v2.1.229 的网关，这些网关在现在获得 ping 的上游上的安静期间没有发送任何内容。

73 77

78<h3 id="choose-an-address-for-the-gateway">

79 为网关选择地址

80</h3>

82Claude Code 通过以下两种方式之一接受网关的地址：

84* **私有地址**：将网关置于内部负载均衡器或 VPN 之后，并使用仅解析为私有地址（如 RFC 1918 或 CGNAT `100.64.0.0/10`）的主机名。用户的机器可以使用任何地址。[私有网络前提条件](/docs/zh-CN/claude-apps-gateway#prerequisites) 列出了可接受的地址范围。

85* **声明的地址块**：如果您的内部网络使用贵组织拥有的公共 IPv4 地址空间，请在 `gatewayInternalNetworks` 托管设置中列出该地址块。网关和用户的机器都必须位于该地址块内。请参阅 [允许网关使用您拥有的公共地址空间](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)。

87如果没有单个地址块能同时包含两者，请改为给网关分配私有地址。

74<h3 id="container-image">89<h3 id="container-image">

75 容器镜像90 容器镜像

76</h3>91</h3>

375 故障排除390 故障排除

376</h2>391</h2>

377 392

378如有问题和反馈，请使用 [Claude Code 支持](https://support.claude.com/en/collections/14445694-claude-code)，或在 [Claude Code GitHub 仓库](https://github.com/anthropics/claude-code/issues)上提交问题。报告问题时，请包括：393如有问题和反馈，请使用 [Claude Code 支持](https://support.claude.com/en/collections/14445694-claude-code)，或在 [Claude Code GitHub 仓库](https://github.com/anthropics/claude-code/issues)上提交问题。您也可以联系您的 Anthropic 客户团队。报告问题时，请包括：

379 394

380* **网关问题**：相关时间窗口内网关的 stderr、您的 `gateway.yaml`（已隐藏密钥）、网关版本（显示在 `/` 的登陆页面和 `/managed/settings` 的 `x-cc-gateway-version` 响应头中），以及最近的更改395* **网关问题**：相关时间窗口内网关的 stderr、您的 `gateway.yaml`（已隐藏密钥）、网关版本（显示在 `/` 的登陆页面和 `/managed/settings` 的 `x-cc-gateway-version` 响应头中），以及最近的更改

381* **登录问题**：开发者运行 `claude --debug-file ./claude-debug.txt`、重现问题，然后发送该文件以及同一时间窗口内网关的审计日志396* **登录问题**：开发者运行 `claude --debug-file ./claude-debug.txt`、重现问题，然后发送该文件以及同一时间窗口内网关的审计日志

394| CLI `/login`：`The gateway is limiting sign-in attempts right now`，或在较旧版本上 `Request failed with status code 429`。`/device` 页面可能向尚未尝试过的开发者显示 `Too many attempts` | 达到了每 IP 登录速率限制。要么 `listen.trusted_proxies` 不覆盖负载均衡器，所以每个开发者共享其地址，要么许多开发者共享一个 NAT 或 VPN 出口地址。具有 `result: rate_limited` 的审计事件显示相同的一个或几个 `client_ip` 值。 | 首先将 `listen.trusted_proxies` 设置为负载均衡器的源范围，然后如果开发者仍然共享地址，提高 `rate_limits`。请参阅[大规模推出](#large-rollouts)。 |409| CLI `/login`：`The gateway is limiting sign-in attempts right now`，或在较旧版本上 `Request failed with status code 429`。`/device` 页面可能向尚未尝试过的开发者显示 `Too many attempts` | 达到了每 IP 登录速率限制。要么 `listen.trusted_proxies` 不覆盖负载均衡器，所以每个开发者共享其地址，要么许多开发者共享一个 NAT 或 VPN 出口地址。具有 `result: rate_limited` 的审计事件显示相同的一个或几个 `client_ip` 值。 | 首先将 `listen.trusted_proxies` 设置为负载均衡器的源范围，然后如果开发者仍然共享地址，提高 `rate_limits`。请参阅[大规模推出](#large-rollouts)。 |

395| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | 网关主机名解析为至少一个公网 IP 地址。Claude Code 检查每个解析的地址，要求每个都是私网。常见原因是双栈名称，其中一个族解析为公网地址，包括 AWS 内部双栈负载均衡器，它们返回公网范围的 AAAA 地址。 | 让网关名称在开发者机器上仅解析为私网地址。对于双栈名称，删除公网范围的记录或提供单独的仅内部 DNS 名称。请参阅[私网前提条件](/docs/zh-CN/claude-apps-gateway#prerequisites)。如果地址是您的组织拥有并在内部使用的公网空间，请[声明该块](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)。 |410| CLI `/login`：`Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip>` | 网关主机名解析为至少一个公网 IP 地址。Claude Code 检查每个解析的地址，要求每个都是私网。常见原因是双栈名称，其中一个族解析为公网地址，包括 AWS 内部双栈负载均衡器，它们返回公网范围的 AAAA 地址。 | 让网关名称在开发者机器上仅解析为私网地址。对于双栈名称，删除公网范围的记录或提供单独的仅内部 DNS 名称。请参阅[私网前提条件](/docs/zh-CN/claude-apps-gateway#prerequisites)。如果地址是您的组织拥有并在内部使用的公网空间，请[声明该块](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)。 |

396| CLI `/login`：`Gateway login would go through proxy <proxy>, which is not on a private network` | `HTTPS_PROXY` 或 `HTTP_PROXY` 适用于网关主机，且代理的主机名解析为公网地址。主机名仅解析为私网地址的代理是允许的，不会触发此错误 | 在开发者的机器上将网关主机添加到 `NO_PROXY`，以便连接是直接的，或使用主机名解析为私网地址的代理。消息会命名要添加的确切 `NO_PROXY` 条目 |411| CLI `/login`：`Gateway login would go through proxy <proxy>, which is not on a private network` | `HTTPS_PROXY` 或 `HTTP_PROXY` 适用于网关主机，且代理的主机名解析为公网地址。主机名仅解析为私网地址的代理是允许的，不会触发此错误 | 在开发者的机器上将网关主机添加到 `NO_PROXY`，以便连接是直接的，或使用主机名解析为私网地址的代理。消息会命名要添加的确切 `NO_PROXY` 条目 |

397| CLI `/login`：`Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | 网关在 [`gatewayInternalNetworks`](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) 中声明的块上，开发者的机器从该块外的地址到达它：VPN 地址池、容器或 WSL2 NAT 段，或不是您的网络 | 让开发者从您的网络上的主机 OS 运行 `/login`。如果显示的地址也是您的组织自己的公网空间，将网关的条目替换为覆盖两者的块，最多 `/8`；第二个重叠条目会被拒绝 |412| CLI `/login`：`Claude Code only signs in to <host> from inside its declared network <block> (managed settings), and this machine is connecting from <ip>, outside it` | 网关在 [`gatewayInternalNetworks`](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) 中声明的块上，开发者的机器从该块外的地址到达它：VPN 地址池、容器或 WSL2 NAT 段，或不是您的网络 | 让开发者从您的网络上的主机 OS 运行 `/login`。如果显示的地址也是您的组织自己的公网空间，将网关的条目替换为覆盖两者的块，最多 `/8`；第二个重叠条目会被拒绝。如果没有能覆盖两者的块，请参阅[为网关选择地址](#choose-an-address-for-the-gateway) |

398| CLI `/login`：`Every address for gateway host <host> must be inside its declared network <block>, and it also resolves to <ip>` | 网关的名称解析为 [`gatewayInternalNetworks`](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) 中声明的块外的地址：第二个站点，或双栈名称上的 IPv6 记录。在声明的块下，每条记录都必须在该单个 IPv4 块内，包括私网和 IPv6 地址 | 在开发者机器上仅为网关名称发布块内的记录，或提供单独的仅内部名称 |413| CLI `/login`：`Every address for gateway host <host> must be inside its declared network <block>, and it also resolves to <ip>` | 网关的名称解析为 [`gatewayInternalNetworks`](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own) 中声明的块外的地址：第二个站点，或双栈名称上的 IPv6 记录。在声明的块下，每条记录都必须在该单个 IPv4 块内，包括私网和 IPv6 地址 | 在开发者机器上仅为网关名称发布块内的记录，或提供单独的仅内部名称 |

399| CLI `/login`：`<host> is on the declared network <block>, which Claude Code checks over a direct connection, not through an HTTP proxy` | `HTTPS_PROXY` 或 `HTTP_PROXY` 适用于声明块上的网关 | 在开发者的机器上，添加消息命名的 `NO_PROXY` 条目 |414| CLI `/login`：`<host> is on the declared network <block>, which Claude Code checks over a direct connection, not through an HTTP proxy` | `HTTPS_PROXY` 或 `HTTP_PROXY` 适用于声明块上的网关 | 在开发者的机器上，添加消息命名的 `NO_PROXY` 条目 |

400| CLI `/login`：消息以 `gatewayInternalNetworks in managed settings` 开头 | 该值违反了[验证规则](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)之一，消息会命名哪一个。在您修复它之前，Claude Code 拒绝机器上的每个新网关 `/login`，包括私网上的网关；现有登录保持工作 | 在您部署的托管设置源中，更正消息命名的条目，然后重新运行 `/login` |415| CLI `/login`：消息以 `gatewayInternalNetworks in managed settings` 开头 | 该值违反了[验证规则](/docs/zh-CN/claude-apps-gateway#allow-a-gateway-on-public-address-space-you-own)之一，消息会命名哪一个。在您修复它之前，Claude Code 拒绝机器上的每个新网关 `/login`，包括私网上的网关；现有登录保持工作 | 在您部署的托管设置源中，更正消息命名的条目，然后重新运行 `/login` |

claude-code-on-the-web.md +8 −8

Details

4 4

5# 在云端使用 Claude Code5# 在云端使用 Claude Code

6 6

~~7> 从浏览器、手机、桌面应用或终端在云端运行 Claude Code 会话，使用 `--cloud` 和 `--teleport` 移动会话，以及自动修复拉取请求。~~7> 从浏览器、手机、桌面应用或终端在云端运行 Claude Code 会话，使用 `--cloud` 和 `--teleport` 移动会话，以及自动修复 Pull Request。

8 8

9<Note>9<Note>

10 云会话在 Pro、Max 和 Team 计划上可用，以及拥有高级席位或 Chat + Claude Code 席位的 Enterprise 用户。10 云会话在 Pro、Max 和 Team 计划上可用，以及拥有高级席位或 Chat + Claude Code 席位的 Enterprise 用户。

11</Note>11</Note>

12 12

13云会话是在云基础设施上运行的 Claude Code 会话，而不是在你的机器上运行。默认情况下，它在 Anthropic 管理的基础设施上运行，或在路由到你的组织的[自托管环境](/docs/zh-CN/self-hosted-environments)时在那里运行。即使关闭笔记本电脑后，会话也会继续运行，你可以从任何设备检查或控制它。13云端会话是在云基础设施上运行的 Claude Code 会话，而不是在您的机器上运行。默认情况下，它在 Anthropic 管理的基础设施上运行，或在路由到您的组织的[自托管环境](/docs/zh-CN/self-hosted-environments)时在那里运行。即使关闭笔记本电脑后，会话也会继续运行，您可以从任何设备检查或控制它。它会与您的其他 Claude 和 Claude Code 使用量一起计入您计划的用量限制，云端 VM 不会单独收费。

14 14

15要让云端会话从 GitHub 克隆代码并推送分支，请使用其中一种 [GitHub 连接方式](#github-authentication-options)连接 GitHub。如果您的仓库位于 GitLab、Bitbucket 或其他托管平台上，请参阅[平台限制](#limitations)了解哪些功能可用。15要让云端会话从 GitHub 克隆代码并推送分支，请使用其中一种 [GitHub 连接方式](#github-authentication-options)连接 GitHub。如果您的仓库位于 GitLab、Bitbucket 或其他托管平台上，请参阅[平台限制](#limitations)了解哪些功能可用。

16 16

411 安全和隔离411 安全和隔离

412</h2>412</h2>

413 413

414每个云会话通过多个层与你的机器和其他会话分离：414每个云端会话通过多个层与您的机器和其他会话分离：

415 415

416* **隔离的虚拟机**：每个会话在隔离的、Anthropic 管理的 VM 中运行。你的组织路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话改为在你自己的基础设施上运行，其中隔离是你的部署的责任416* **隔离的虚拟机**：每个会话在隔离的、Anthropic 管理的 VM 中运行。您的组织路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话改为在您自己的基础设施上运行，其中隔离是您的部署的责任

417* <span id="default-allowed-domains" />**网络访问控制**：在 Anthropic 托管的环境中，网络访问默认受限，可以禁用。请参阅[网络访问](/docs/zh-CN/cloud-environments#network-access)了解访问级别、[默认允许的域](/docs/zh-CN/cloud-environments#default-allowed-domains)和不通过允许列表的流量。在自托管环境中，你在自己的网络边界处限制会话出口。当在禁用网络访问的情况下运行时，Claude Code 仍然可以与 Anthropic API 通信，这可能允许数据从 VM 中退出。417* <span id="default-allowed-domains" />**网络访问控制**：在 Anthropic 托管的环境中，网络访问默认受限，可以禁用。请参阅[网络访问](/docs/zh-CN/cloud-environments#network-access)了解访问级别、[默认允许的域](/docs/zh-CN/cloud-environments#default-allowed-domains)和不通过允许列表的流量。在自托管环境中，您在自己的网络边界处限制会话出口。当在禁用网络访问的情况下运行时，Claude Code 仍然可以与 Anthropic API 通信，这可能允许数据从 VM 中退出。

418* **凭证保护**：在 Anthropic 托管的环境中，git 凭证和签名密钥保持在沙箱外，代理使用作用域凭证代表会话进行身份验证。在自托管环境中，你的部署提供 git 凭证；请参阅[配置 git](/docs/zh-CN/self-hosted-environments-deploy#configure-git)418* **凭据保护**：在 Anthropic 托管的环境中，git 凭据和签名密钥保持在沙箱外，代理使用作用域凭据代表会话进行身份验证。在自托管环境中，您的部署提供 git 凭据；请参阅[配置 git](/docs/zh-CN/self-hosted-environments-deploy#configure-git)

419* **网络密钥**：在 Pro 和 Max 计划的 Anthropic 托管环境中，您[添加到云环境](/docs/zh-CN/cloud-environments#add-api-credentials)的密钥以相同的方式保持在沙箱外，在请求离开会话后附加到匹配的请求。自托管环境没有网络密钥，Team 和 Enterprise 计划目前也还没有419* **网络密钥**：在 Pro 和 Max 计划的 Anthropic 托管环境中，您[添加到云环境](/docs/zh-CN/cloud-environments#add-network-secrets)的密钥以相同的方式保持在沙箱外，在请求离开会话后附加到匹配的请求。自托管环境没有网络密钥，Team 和 Enterprise 计划目前也还没有

420* **安全分析**：代码在会话的隔离环境内分析和修改，然后创建 PR420* **安全分析**：代码在会话的隔离环境内分析和修改，然后创建 PR

421 421

422<h2 id="troubleshooting">422<h2 id="troubleshooting">

491 491

492在依赖云会话进行工作流之前，请考虑这些约束：492在依赖云会话进行工作流之前，请考虑这些约束：

493 493

494* **速率限制**：云会话与你账户内所有其他 Claude 和 Claude Code 使用共享速率限制。并行运行多个任务会按比例消耗更多速率限制。云 VM 没有单独的计算费用。494* **速率限制**：云端会话与您账户内所有其他 Claude 和 Claude Code 使用共享速率限制。并行运行多个任务会按比例消耗更多速率限制。

495* **时间限制**：Claude 运行的命令和 SessionStart hooks 有你可以更改的默认超时，设置脚本仅在大约五分钟内完成时才被缓存。请参阅[时间限制](/docs/zh-CN/cloud-environments#time-limits)495* **时间限制**：Claude 运行的命令和 SessionStart hooks 有你可以更改的默认超时，设置脚本仅在大约五分钟内完成时才被缓存。请参阅[时间限制](/docs/zh-CN/cloud-environments#time-limits)

496* **存储库身份验证**：你只能在认证到相同账户时将云会话拉入你的终端496* **存储库身份验证**：你只能在认证到相同账户时将云会话拉入你的终端

497* **平台限制**：存储库克隆和拉取请求创建需要 GitHub。自托管[GitHub Enterprise Server](/docs/zh-CN/github-enterprise-server) 实例支持 Team 和 Enterprise 计划。你可以通过设置 `CCR_FORCE_BUNDLE=1` 将 GitLab、Bitbucket 或其他非 GitHub 存储库作为[本地捆绑](#send-local-repositories-without-github)发送到云会话，但会话无法将结果推送回该远程497* **平台限制**：存储库克隆和拉取请求创建需要 GitHub。自托管[GitHub Enterprise Server](/docs/zh-CN/github-enterprise-server) 实例支持 Team 和 Enterprise 计划。你可以通过设置 `CCR_FORCE_BUNDLE=1` 将 GitLab、Bitbucket 或其他非 GitHub 存储库作为[本地捆绑](#send-local-repositories-without-github)发送到云会话，但会话无法将结果推送回该远程

claude-platform-on-aws.md +10 −3

Details

217 1. 配置 AWS 凭证217 1. 配置 AWS 凭证

218</h3>218</h3>

219 219

220Claude Code 支持两种 AWS 上的 Claude Platform 身份验证方法。选择适合您的团队如何管理访问的方法。220Claude Code 支持两种 AWS 上的 Claude Platform 身份验证方法。请根据您的团队管理访问的方式选择合适的方法：

221 221

222**选项 A：使用 SigV4 的 AWS 凭证**222* [使用 SigV4 的 AWS 凭据](#use-aws-credentials-with-sigv4)：以 IAM 主体身份进行身份验证，凭据来自标准 AWS 凭据链

223* [工作区 API 密钥](#use-a-workspace-api-key)：使用您在 AWS Console 中生成的长期有效密钥进行身份验证

224

225<h4 id="use-aws-credentials-with-sigv4">

226 使用 SigV4 的 AWS 凭据

227</h4>

223 228

224Claude Code 使用标准 AWS 凭证链使用 SigV4 对请求进行签名：环境变量、`~/.aws/credentials` 中的共享凭证、IAM 角色、AWS SSO 会话以及 AWS SDK 支持的任何其他来源。229Claude Code 使用标准 AWS 凭证链使用 SigV4 对请求进行签名：环境变量、`~/.aws/credentials` 中的共享凭证、IAM 角色、AWS SSO 会话以及 AWS SDK 支持的任何其他来源。

225 230

244 249

245配置了 `awsAuthRefresh` 后，运行 `/login`，选择 **3rd-party platform**，然后在 **Using 3rd-party platforms** 下选择 **Claude Platform on AWS · refresh credentials**。Claude Code 运行配置的命令并重新读取您的 AWS 凭证，无需重启。250配置了 `awsAuthRefresh` 后，运行 `/login`，选择 **3rd-party platform**，然后在 **Using 3rd-party platforms** 下选择 **Claude Platform on AWS · refresh credentials**。Claude Code 运行配置的命令并重新读取您的 AWS 凭证，无需重启。

246 251

247**选项 B：工作区 API 密钥**252<h4 id="use-a-workspace-api-key">

253 使用工作区 API 密钥

254</h4>

248 255

249工作区 API 密钥是一个长期有效的密钥，当您不想管理联合 AWS 凭证时很有用。在 AWS Console 中的 **Claude Platform on AWS → API keys** 下生成一个，并将其设置为 `ANTHROPIC_AWS_API_KEY`：256工作区 API 密钥是一个长期有效的密钥，当您不想管理联合 AWS 凭证时很有用。在 AWS Console 中的 **Claude Platform on AWS → API keys** 下生成一个，并将其设置为 `ANTHROPIC_AWS_API_KEY`：

250 257

claude-projects.md +1 −1

Details

398 398

399每个新云线程都在项目的[云环境](/docs/zh-CN/cloud-environments)中启动。环境决定线程可以访问哪些域、它们拥有哪些环境变量、哪些网络密钥会被添加到它们的请求中，以及设置脚本在 Claude 启动之前安装什么。在您于 **Project settings > Environment** 中选择环境之前，云线程使用默认的 Anthropic 托管环境。399每个新云线程都在项目的[云环境](/docs/zh-CN/cloud-environments)中启动。环境决定线程可以访问哪些域、它们拥有哪些环境变量、哪些网络密钥会被添加到它们的请求中，以及设置脚本在 Claude 启动之前安装什么。在您于 **Project settings > Environment** 中选择环境之前，云线程使用默认的 Anthropic 托管环境。

400 400

401如果云线程需要访问内部 API 或私有包注册表，或需要您的机器通常持有的令牌，请更改环境而不是项目：请参阅[网络访问](/docs/zh-CN/cloud-environments#network-access)、[添加网络密钥](/docs/zh-CN/cloud-environments#add-api-credentials)和[设置脚本](/docs/zh-CN/cloud-environments#setup-scripts)。401如果云线程需要访问内部 API 或私有包注册表，或需要您的机器通常持有的令牌，请更改环境而不是项目：请参阅[网络访问](/docs/zh-CN/cloud-environments#network-access)、[添加网络密钥](/docs/zh-CN/cloud-environments#add-network-secrets)和[设置脚本](/docs/zh-CN/cloud-environments#setup-scripts)。

402 402

403<h3 id="get-skills-plugins-connectors-and-tools-into-threads">403<h3 id="get-skills-plugins-connectors-and-tools-into-threads">

404 将 skill、插件、连接器和工具引入线程404 将 skill、插件、连接器和工具引入线程

cloud-environments.md +61 −59

Details

4 4

5# 配置云环境5# 配置云环境

6 6

~~7> 为 Claude Code 云会话配置云环境：网络访问级别、环境变量、设置脚本和环境缓存。~~7> 为 Claude Code 云端会话配置云环境：网络访问级别、环境变量、设置脚本和环境缓存。

8 8

9<Note>9<Note>

10 云环境适用于[云会话](/docs/zh-CN/claude-code-on-the-web)，这些会话在 Pro、Max 和 Team 计划上可用，以及具有[高级席位或 Chat + Claude Code 席位](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan)的 Enterprise 用户。10 云环境适用于[云端会话](/docs/zh-CN/claude-code-on-the-web)，这些会话在 Pro、Max 和 Team 计划上可用，以及具有[高级席位或 Chat + Claude Code 席位](https://support.claude.com/en/articles/11845131-use-claude-code-with-your-team-or-enterprise-plan)的 Enterprise 用户。

11</Note>11</Note>

12 12

13每个[云端会话](/docs/zh-CN/claude-code-on-the-web)都在云环境中运行。您可以配置环境以允许或拒绝[网络访问](#access-levels)、为会话[设置环境变量](#set-environment-variables)、在 Pro 和 Max 计划上存储会话使用但无法看到的[网络密钥](#add-api-credentials)，以及在 Claude 开始工作前运行[设置脚本](#setup-scripts)。13每个[云端会话](/docs/zh-CN/claude-code-on-the-web)都在云环境中运行。您可以配置环境以允许或拒绝[网络访问](#access-levels)、为会话[设置环境变量](#set-environment-variables)、在 Pro 和 Max 计划上存储会话使用但无法看到的[网络密钥](#add-network-secrets)，以及在 Claude 开始工作前运行[设置脚本](#setup-scripts)。

14 14

15相同的环境适用于您启动云会话的任何地方：[Desktop 应用](/docs/zh-CN/desktop)、[Claude 移动应用](/docs/zh-CN/mobile)、浏览器中的 [claude.ai/code](https://claude.ai/code)、终端中搭配 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)、[例程](/docs/zh-CN/routines)和 [Claude Tag](https://claude.com/docs/claude-tag/overview)。这些界面中的每一个也可以路由到[自托管环境](/docs/zh-CN/self-hosted-environments)。[可用性和限制](/docs/zh-CN/self-hosted-environments#availability-and-limitations)涵盖了当 Claude Tag 会话在其中运行时 Claude 还不能使用的内容。15相同的环境适用于您启动云端会话的任何地方：[Desktop 应用](/docs/zh-CN/desktop)、[Claude 移动应用](/docs/zh-CN/mobile)、浏览器中的 [claude.ai/code](https://claude.ai/code)、终端中搭配 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)、[Routine](/docs/zh-CN/routines) 和 [Claude Tag](https://claude.com/docs/claude-tag/overview)。这些使用入口中的每一个也可以路由到[自托管环境](/docs/zh-CN/self-hosted-environments)。[可用性和限制](/docs/zh-CN/self-hosted-environments#availability-and-limitations)涵盖了当 Claude Tag 会话在其中运行时 Claude 还不能使用的内容。

16 16

17<Info>17<Info>

18 [Remote Control](/docs/zh-CN/remote-control) 会话将网页和移动界面连接到您自己机器上的会话，该会话使用您机器的网络和文件，而不是云环境。Claude Tag 频道会话仅使用组织级别的环境，即[共享环境](#organization-shared-environments)或[自托管环境](/docs/zh-CN/self-hosted-environments)。18 [Remote Control](/docs/zh-CN/remote-control) 会话将网页和移动界面连接到您自己机器上的会话，该会话使用您机器的网络和文件，而不是云环境。Claude Tag 频道会话仅使用组织级别的环境，即[共享环境](#organization-shared-environments)或[自托管环境](/docs/zh-CN/self-hosted-environments)。

41当默认环境不够用时，请配置环境：当 Claude 需要访问[默认允许列表](#default-allowed-domains)之外的域、需要为其会话设置环境变量，或需要在开始工作前安装依赖项时。41当默认环境不够用时，请配置环境：当 Claude 需要访问[默认允许列表](#default-allowed-domains)之外的域、需要为其会话设置环境变量，或需要在开始工作前安装依赖项时。

42 42

43<h2 id="configure-your-environment">43<h2 id="configure-your-environment">

~~44 配置你的环境~~44 配置您的环境

45</h2>45</h2>

46 46

47在环境选择器中创建、编辑和归档环境，你可以在[网页快速入门](/docs/zh-CN/web-quickstart)后从[claude.ai/code](https://claude.ai/code)访问它，或从[桌面应用](/docs/zh-CN/desktop#cloud-sessions)的提示框中访问。你创建的环境是你账户的个人环境；由所有者创建的[共享环境](#organization-shared-environments)会出现在同一个选择器中。查看[已安装的工具](#installed-tools)了解无需任何配置即可使用的工具。47在环境选择器中创建、编辑和归档环境。完成[网页快速入门](/docs/zh-CN/web-quickstart)后，您可以在 [claude.ai/code](https://claude.ai/code) 访问该选择器，也可以从[桌面应用](/docs/zh-CN/desktop#cloud-sessions)的输入框中访问。您创建的环境是您账户的个人环境；由所有者创建的[共享环境](#organization-shared-environments)会出现在同一个选择器中。查看[已安装的工具](#installed-tools)，了解无需任何配置即可使用的工具。

48 48

49<Steps>49<Steps>

50 <Step title="打开环境选择器">50 <Step title="打开环境选择器">

~~51 在[claude.ai/code](https://claude.ai/code)上，选择显示当前环境名称的云图标，它位于消息框上方的行中。选择器没有设置页面或直接URL。~~51 在 [claude.ai/code](https://claude.ai/code) 上，选择显示当前环境名称的云图标，它位于消息框上方的行中。选择器没有设置页面或直接 URL。

52 52

53 <Frame>53 <Frame>

54 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-selector.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=cc2813a5664519eaf5a89d793ce5af26" alt="环境选择器在claude.ai/code的消息框上方打开。显示环境名称Default的云按钮位于消息框上方的行中。打开的菜单列出了一个带有Download和Desktop only标签的Local行、一个Cloud部分，其中Default环境被选中并显示一个复选标记，悬停时显示一个设置齿轮图标、一个Add cloud environment选项，以及一个带有设置说明的Remote Control部分。" width="1672" height="682" data-path="images/cloud-environment-selector.png" />54 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-selector.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=cc2813a5664519eaf5a89d793ce5af26" alt="环境选择器在 claude.ai/code 的消息框上方打开。显示环境名称 Default 的云按钮位于消息框上方的行中。打开的菜单列出了一个带有 Download 和 Desktop only 标签的 Local 行、一个 Cloud 部分（其中 Default 环境被选中并显示复选标记，悬停时显示设置齿轮图标）、一个 Add cloud environment 选项，以及一个带有设置说明的 Remote Control 部分。" width="1672" height="682" data-path="images/cloud-environment-selector.png" />

55 </Frame>55 </Frame>

56 </Step>56 </Step>

57 57

58 <Step title="添加或编辑环境">58 <Step title="添加或编辑环境">

~~59 选择**Cloud**来列出你的环境。然后选择**Add cloud environment**，或悬停在现有环境上并选择右侧出现的设置图标。~~59 选择 **Cloud** 来列出您的环境。然后选择 **Add cloud environment**，或悬停在现有环境上并选择右侧出现的设置图标。

60 60

61 对话框包括名称、网络访问级别、环境变量和设置脚本。当您在 Pro 或 Max 计划上编辑现有的云环境时，对话框还包括[网络机密](#add-api-credentials)。61 对话框包括名称、网络访问级别、环境变量和设置脚本。当您在 Pro 或 Max 计划上编辑现有的云环境时，对话框还包括[网络机密](#add-network-secrets)。

62 62

63 <Frame>63 <Frame>

64 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-dialog.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=30d4478b31d1f879f7ee287ddab32505" alt="New cloud environment对话框。一个Name字段，占位符为Default，一个Network access选择器设置为Trusted，带有网络策略和访问级别的链接，一个Environment variables框显示.env格式占位符文本，并注明值对使用该环境的任何人都可见，一个Setup script框描述为在新会话启动时运行的Bash脚本，在Claude Code启动之前，以及Cancel和Create environment按钮。" width="874" height="1372" data-path="images/cloud-environment-dialog.png" />64 <img src="https://mintcdn.com/claude-code/ZFId6l95856c5LSw/images/cloud-environment-dialog.png?fit=max&auto=format&n=ZFId6l95856c5LSw&q=85&s=30d4478b31d1f879f7ee287ddab32505" alt="New cloud environment 对话框。一个占位符为 Default 的 Name 字段；一个设置为 Trusted 的 Network access 选择器，带有网络策略和访问级别的链接；一个 Environment variables 框，显示 .env 格式的占位符文本，并注明值对使用该环境的任何人都可见；一个 Setup script 框，描述为在新会话启动时、Claude Code 启动之前运行的 Bash 脚本；以及 Cancel 和 Create environment 按钮。" width="874" height="1372" data-path="images/cloud-environment-dialog.png" />

65 </Frame>65 </Frame>

66 </Step>66 </Step>

67</Steps>67</Steps>

70 设置环境变量70 设置环境变量

71</h3>71</h3>

72 72

73环境变量使用`.env`格式，每行一个`KEY=value`对。普通值不需要引号，如果你用匹配的一对引号引用一个值，引号不会成为该值的一部分。引用跨越多行或包含`#`的值：在未引用的值中，`#`开始注释，该行的其余部分被丢弃。73环境变量使用 `.env` 格式，每行一个 `KEY=value` 对。普通值不需要引号，如果您用匹配的一对引号引用一个值，引号不会成为该值的一部分。跨越多行或包含 `#` 的值需要加引号：在未加引号的值中，`#` 会开始注释，该行的其余部分会被丢弃。

74 74

75以下示例定义了三个变量。75以下示例定义了三个变量。

76 76

80DATABASE_URL=postgres://localhost:5432/myapp80DATABASE_URL=postgres://localhost:5432/myapp

81```81```

82 82

83会话在创建时将环境的值读入普通环境变量中，Claude运行的任何命令都可以读取这些变量，除了`OTEL_*`变量。Claude Code使用这些变量进行自己的[遥测导出](/docs/zh-CN/monitoring-usage#telemetry-from-cloud-sessions-and-claude-tag)，不会将它们传递给它运行的命令。83会话会将环境的值读入普通环境变量中，Claude 运行的任何命令都可以读取这些变量，`OTEL_*` 变量除外。Claude Code 使用这些变量进行自己的[遥测导出](/docs/zh-CN/monitoring-usage#telemetry-from-cloud-sessions-and-claude-tag)，不会将它们传递给它运行的命令。

84 84

~~85在Anthropic托管的环境中，会话在创建时读取环境的值，以及之后每次Claude Code在会话的VM中启动时读取，这发生在两种情况下：~~85在 Anthropic 托管的环境中，会话在创建时读取环境的值，之后每次 Claude Code 在会话的 VM 中启动时也会再次读取，这发生在两种情况下：

86 86

~~87* **VM在空闲后被恢复**：在几分钟没有活动后，会话的VM会暂停，其文件被保存。你的下一条消息会恢复同一个VM并再次启动Claude Code。~~87* **VM 在空闲后被恢复**：在几分钟没有活动后，会话的 VM 会暂停，其文件会被保存。您的下一条消息会恢复同一个 VM 并再次启动 Claude Code。

~~88* **VM被回收并被重建**：如果暂停的VM已经被[回收](/docs/zh-CN/claude-code-on-the-web#environment-expired)，重新打开会话会配置一个新的VM。~~88* **VM 被回收并被重建**：如果暂停的 VM 已经被[回收](/docs/zh-CN/claude-code-on-the-web#environment-expired)，重新打开会话会配置一个新的 VM。

89 89

90编辑、添加或删除变量后，Anthropic托管环境中的现有会话会保持它最后读取的值，直到其VM下次被恢复或重建，然后使用你的更改。其VM在会话空闲后会自动暂停，你无法自己暂停它。要立即使用新值，请要求Claude在它运行的命令上设置它，例如`LOG_LEVEL=trace npm test`，或启动一个新会话。90编辑、添加或删除变量后，Anthropic 托管环境中的现有会话会保持它最后读取的值，直到其 VM 下次被恢复或重建，此后才使用您的更改。会话空闲后其 VM 会自动暂停，您无法手动暂停它。要立即使用新值，请要求 Claude 在它运行的命令上设置该值，例如 `LOG_LEVEL=trace npm test`，或启动一个新会话。

91 91

92云会话在启动时也会自己设置一些变量。对于[`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/zh-CN/claude-code-on-the-web#manage-context)，会话设置的值会覆盖你在这里添加的值，所以在这里添加该键没有效果。92云端会话在启动时也会自行设置一些变量。对于 [`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`](/docs/zh-CN/claude-code-on-the-web#manage-context)，会话设置的值会覆盖您在这里添加的值，因此在这里添加该键没有效果。

93 93

94使用该环境的任何人都可以读取这些值。在 Pro 和 Max 计划上，对于 Agent 代理可以附加到请求中的密钥，请改用[网络机密](#add-api-credentials)。[永远不会获得机密的请求](#requests-that-never-get-the-credential)在该处列出。94使用该环境的任何人都可以读取这些值。在 Pro 和 Max 计划上，对于 Agent 代理可以附加到请求中的密钥，请改用[网络机密](#add-network-secrets)。[永远不会获得机密的请求](#requests-that-never-get-the-credential)在该处列出。

95 95

~~96<h3 id="add-api-credentials">~~96<span id="add-api-credentials" />

98<h3 id="add-network-secrets">

97 添加网络机密99 添加网络机密

98</h3>100</h3>

99 101

107 109

108以下要求决定您是否可以添加机密，以及添加后 Agent 代理是否可以使用它：110以下要求决定您是否可以添加机密，以及添加后 Agent 代理是否可以使用它：

109 111

110* **Role**：你的claude.ai组织中的组织管理员角色112* **Role**：您的 claude.ai 组织中的组织管理员角色

111 * 在Team和Enterprise上，所有者持有它，管理员没有113 * 在 Team 和 Enterprise 上，所有者持有该角色，管理员（Admin）不持有

112 * 在Pro和Max上，你在自己的组织中持有它114 * 在 Pro 和 Max 上，您在自己的组织中持有该角色

113* **Environment type**：一个已存在的 Anthropic 托管云环境。[自托管环境](/docs/zh-CN/self-hosted-environments)没有网络机密115* **Environment type**：一个已存在的 Anthropic 托管云环境。[自托管环境](/docs/zh-CN/self-hosted-environments)没有网络机密

114* **API reachability**：API接受来自互联网的连接，因为请求来自Anthropic的网络116* **API reachability**：API 接受来自互联网的连接，因为请求从 Anthropic 的网络发出

115* **Encryption keys**：如果您的组织使用客户管理的加密密钥，则无法保存网络机密117* **Encryption keys**：如果您的组织使用客户管理的加密密钥，则无法保存网络机密

116 118

117<h4 id="add-a-credential">119<h4 id="add-a-credential">

155Agent 代理永远不会将您添加的机密附加到以下请求：157Agent 代理永远不会将您添加的机密附加到以下请求：

156 158

157* **GitHub**：[GitHub 代理](#github-proxy)会代为对发往 GitHub 的请求进行身份验证，因此您无需为其设置网络机密159* **GitHub**：[GitHub 代理](#github-proxy)会代为对发往 GitHub 的请求进行身份验证，因此您无需为其设置网络机密

158* **Anthropic API和公共包注册表**：`api.anthropic.com`、`registry.npmjs.org`、`jsr.io`、`npm.jsr.io`、`pypi.org`、`files.pythonhosted.org`、`index.crates.io`和`proxy.golang.org`160* **Anthropic API 和公共包注册表**：`api.anthropic.com`、`registry.npmjs.org`、`jsr.io`、`npm.jsr.io`、`pypi.org`、`files.pythonhosted.org`、`index.crates.io` 和 `proxy.golang.org`

159* **Setup script请求**：Claude Code在启动时连接到代理，在[setup script](#setup-scripts)运行后161* **设置脚本请求**：Claude Code 在启动时才连接到 Agent 代理，此时[设置脚本](#setup-scripts)已经运行完毕

160* **Claude Code的遥测导出**：Claude Code自己发送其[遥测导出](/docs/zh-CN/monitoring-usage#telemetry-from-cloud-sessions-and-claude-tag)，而不是通过它运行的命令，该请求不会通过代理162* **Claude Code 的遥测导出**：Claude Code 自行发送其[遥测导出](/docs/zh-CN/monitoring-usage#telemetry-from-cloud-sessions-and-claude-tag)，而不是通过它运行的命令发送，该请求不会经过 Agent 代理

161 163

162<h3 id="select-an-environment-from-the-cli">164<h3 id="select-an-environment-from-the-cli">

163 从CLI选择环境165 从 CLI 选择环境

164</h3>166</h3>

165 167

166在你的终端中运行`/remote-env`来为你从CLI创建的云会话（例如[`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)）选择默认环境。该命令打开你现有环境的选择器并将你的选择保存到你的[用户设置](/docs/zh-CN/settings#where-settings-live)中的`remote.defaultEnvironmentId`键，所以它适用于你机器上的每个项目，直到你更改它，除非在更高优先级的[设置层](/docs/zh-CN/settings#settings-precedence)（例如仓库的项目设置）上设置了相同的键。168在终端中运行 `/remote-env`，为您从 CLI 创建的云端会话（例如 [`claude --cloud`](/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud)）选择默认环境。该命令会打开现有环境的选择器，并将您的选择保存到[用户设置](/docs/zh-CN/settings#where-settings-live)中的 `remote.defaultEnvironmentId` 键，因此它适用于您机器上的每个项目，直到您更改它为止，除非在更高优先级的[设置层级](/docs/zh-CN/settings#settings-precedence)（例如仓库的项目设置）中设置了相同的键。

167 169

168[自托管环境](/docs/zh-CN/self-hosted-environments)ID的形式为`ccpool_...`，遵循更严格的源规则。查看[`remote.defaultEnvironmentId`](/docs/zh-CN/settings-reference#remote-defaultenvironmentid)了解Claude Code遵守它的设置层。170[自托管环境](/docs/zh-CN/self-hosted-environments) ID 的形式为 `ccpool_...`，遵循更严格的来源规则。查看 [`remote.defaultEnvironmentId`](/docs/zh-CN/settings-reference#remote-defaultenvironmentid)，了解 Claude Code 会从哪些设置层级采用该值。

169 171

170`/remote-env`仅设置默认值：它不启动会话，也不能添加或编辑环境。从[环境选择器](#configure-your-environment)管理它们。172`/remote-env` 仅设置默认值：它不会启动会话，也不能添加或编辑环境。请从[环境选择器](#configure-your-environment)管理环境。

171 173

172<h3 id="archive-an-environment">174<h3 id="archive-an-environment">

173 归档环境175 归档环境

174</h3>176</h3>

175 177

176要归档你自己的环境之一，请打开它进行编辑并选择**Archive**。所有者从管理设置中的**Cloud environments**页面归档[共享环境](#organization-shared-environments)。你不能删除环境，只能归档它。178要归档您自己的某个环境，请打开它进行编辑并选择 **Archive**。所有者从管理设置中的 **Cloud environments** 页面归档[共享环境](#organization-shared-environments)。您无法删除环境，只能归档它。

177 179

178归档影响新会话，不影响运行中的会话：180归档影响新会话，不影响运行中的会话：

179 181

180* 已经在环境中运行的会话继续工作。182* 已经在环境中运行的会话会继续工作。

181* 环境从选择器和`/remote-env`中消失，所以你无法为新会话选择它。183* 环境会从选择器和 `/remote-env` 中消失，因此您无法为新会话选择它。

182* 环境中的网络机密在其正在运行的会话中仍保持附加状态。请在归档前删除不再需要的机密。184* 环境中的网络机密在其正在运行的会话中仍保持附加状态。请在归档前删除不再需要的机密。

183* 没有新会话可以在任何表面上的归档环境中启动。如果该环境是你保存的[CLI默认值](#select-an-environment-from-the-cli)，当你的列表有一个时，Claude Code会在Anthropic托管的环境中启动CLI云会话，否则在你列表中不是[Remote Control bridge环境](#the-default-environment)的第一个环境中启动。任何显式配置了该环境的东西，例如[routine](/docs/zh-CN/routines#environments-and-network-access)，无法在其中启动新会话。将其指向另一个环境。185* 在任何使用入口上都无法在已归档的环境中启动新会话。如果该环境是您保存的 [CLI 默认值](#select-an-environment-from-the-cli)，当您的列表中有 Anthropic 托管的环境时，Claude Code 会在该环境中启动 CLI 云端会话，否则会在列表中第一个不是 [Remote Control bridge 环境](#the-default-environment)的环境中启动。任何显式配置了该环境的内容，例如 [Routine](/docs/zh-CN/routines#environments-and-network-access)，都无法在其中启动新会话。请将其指向另一个环境。

184 186

185<h3 id="organization-shared-environments">187<h3 id="organization-shared-environments">

186 组织共享环境188 组织共享环境

187</h3>189</h3>

188 190

189在Team和Enterprise计划上，所有者可以创建与组织的每个成员共享的云环境。同一角色管理**Cloud environments**管理页面上的其他所有内容，包括[自托管环境](/docs/zh-CN/self-hosted-environments)；管理员角色无法打开该页面。可以打开它的完整角色列表是[管理服务器管理的设置](/docs/zh-CN/server-managed-settings#access-control)的角色列表。191在 Team 和 Enterprise 计划上，所有者可以创建与组织每个成员共享的云环境。同一角色管理 **Cloud environments** 管理页面上的其他所有内容，包括[自托管环境](/docs/zh-CN/self-hosted-environments)；管理员（Admin）角色无法打开该页面。可以打开该页面的完整角色列表与[管理服务器托管设置](/docs/zh-CN/server-managed-settings#access-control)的角色列表相同。

190 192

191共享环境出现在每个成员的[环境选择器](#configure-your-environment)中，在**Organization**标题下，位于成员自己的环境之后（在**Personal**下），所以团队可以标准化一个配置，而不是每个成员重新创建它。在那里选择共享环境的设置图标会为每个成员（包括所有者）打开其配置的只读摘要。193共享环境出现在每个成员的[环境选择器](#configure-your-environment)中的 **Organization** 标题下，位于成员自己在 **Personal** 下的环境之后，因此团队可以统一使用一套配置，而无需每个成员各自重新创建。在那里选择共享环境的设置图标，会为每个成员（包括所有者）打开其配置的只读摘要。

192 194

193所有者通过以下两种方式之一使环境对组织可用：195所有者可以通过以下两种方式之一使环境对组织可用：

194 196

195* **创建共享环境**：使用[admin settings](https://claude.ai/admin-settings)中的**Cloud environments**页面，这也是所有者编辑和归档共享环境的地方。每个都有一个名称、一个[网络访问级别](#access-levels)、`.env`格式的[环境变量](#set-environment-variables)和一个[setup script](#setup-scripts)。197* **创建共享环境**：使用[管理设置](https://claude.ai/admin-settings)中的 **Cloud environments** 页面，所有者也在该页面编辑和归档共享环境。每个共享环境都有一个名称、一个[网络访问级别](#access-levels)、`.env` 格式的[环境变量](#set-environment-variables)和一个[设置脚本](#setup-scripts)。

196* **共享个人环境**：在环境选择器中打开你自己的环境之一进行编辑，然后从**Who can use it**行共享它。环境保持其ID，所以已经使用它的会话和routine不受影响，每个成员都可以看到它并在其中启动会话。198* **共享个人环境**：在环境选择器中打开您自己的某个环境进行编辑，然后从 **Who can use it** 行共享它。环境会保留其 ID，因此已经使用它的会话和 Routine 不受影响，每个成员随后都可以看到它并在其中启动会话。

197 199

198所有者在[claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)单独选择组织的[默认环境](#the-default-environment)。200所有者在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 单独选择组织的[默认环境](#the-default-environment)。

199 201

200每个成员在共享环境中的会话都会读取其变量，因此请勿在其中包含机密信息。[网络机密](#add-api-credentials)可以为会话提供其无法读取的密钥，但目前尚不适用于 Team 或 Enterprise 计划。202每个成员在共享环境中的会话都会读取其变量，因此请勿在其中包含机密信息。[网络机密](#add-network-secrets)可以为会话提供其无法读取的密钥，但目前尚不适用于 Team 或 Enterprise 计划。

201 203

202<h3 id="set-the-environment-a-claude-tag-channel-uses">204<h3 id="set-the-environment-a-claude-tag-channel-uses">

203 设置Claude Tag频道使用的环境205 设置 Claude Tag 频道使用的环境

204</h3>206</h3>

205 207

206在[Claude Tag](https://claude.com/docs/claude-tag/overview)频道中，Claude作为你组织的共享身份工作，而不是任何成员，所以频道会话仅使用组织级别的环境，要么是共享环境，要么是[自托管环境](/docs/zh-CN/self-hosted-environments)。要给频道一个不是[预安装](#installed-tools)的工具链，例如.NET，所有者可以从**Cloud environments**管理页面创建一个[共享环境](#organization-shared-environments)，带有一个[setup script](#setup-scripts)来安装它。通过以下两种方式之一将频道指向一个环境：208在 [Claude Tag](https://claude.com/docs/claude-tag/overview) 频道中，Claude 以您组织的共享身份工作，而不是以任何成员的身份工作，因此频道会话仅使用组织级别的环境，即共享环境或[自托管环境](/docs/zh-CN/self-hosted-environments)。要为频道提供未[预安装](#installed-tools)的工具链（例如 .NET），所有者可以从 **Cloud environments** 管理页面创建一个[共享环境](#organization-shared-environments)，并使用[设置脚本](#setup-scripts)安装该工具链。通过以下两种方式之一将频道指向某个环境：

207 209

208* 在[claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)将共享或自托管环境设置为组织的[默认环境](#the-default-environment)。210* 在 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code) 将共享环境或自托管环境设置为组织的[默认环境](#the-default-environment)。

209* 在Claude Tag管理设置中[将一个固定到频道](https://claude.com/docs/claude-tag/admins/troubleshooting#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one)。211* 在 Claude Tag 管理设置中[将某个环境固定到频道](https://claude.com/docs/claude-tag/admins/troubleshooting#channel-sessions-use-the-wrong-environment-or-can%E2%80%99t-find-one)。

210 212

211<h2 id="network-access">213<h2 id="network-access">

212 网络访问214 网络访问

214 216

215每个环境都设置一个网络访问级别，控制其会话可以进行的出站连接。默认级别 **Trusted** 允许包注册表和其他[允许列表中的域](#default-allowed-domains)；**Custom** 采用您自己的域列表。217每个环境都设置一个网络访问级别，控制其会话可以进行的出站连接。默认级别 **Trusted** 允许包注册表和其他[允许列表中的域](#default-allowed-domains)；**Custom** 采用您自己的域列表。

216 218

217要更改环境的网络访问，[打开它进行编辑](#configure-your-environment)并在对话框中使用 **Network access** 选择器。[共享环境](#organization-shared-environments)在那里以只读方式打开，因此 Owner 改为从[管理设置](https://claude.ai/admin-settings)中的 **Cloud environments** 页面更改其网络访问。打开选择器的云图标出现在[Default 环境](#the-default-environment)下列出的应用界面上，以及[例程编辑器](/docs/zh-CN/routines#environments-and-network-access)中；个人环境在您的 claude.ai 账户设置中没有单独的页面。219要更改环境的网络访问，[打开它进行编辑](#configure-your-environment)并在对话框中使用 **Network access** 选择器。[共享环境](#organization-shared-environments)在那里以只读方式打开，因此 Owner 改为从[管理设置](https://claude.ai/admin-settings)中的 **Cloud environments** 页面更改其网络访问。打开选择器的云图标出现在[Default 环境](#the-default-environment)下列出的应用使用入口上，以及 [Routine 编辑器](/docs/zh-CN/routines#environments-and-network-access)中；个人环境在您的 claude.ai 账户设置中没有单独的页面。

218 220

219当您更改 Anthropic 托管环境的网络访问时，其现有会话在约一分钟内遵循新设置，用于通过会话的[网络允许列表](#access-levels)的请求。您无需启动新会话。221当您更改 Anthropic 托管环境的网络访问时，其现有会话在约一分钟内遵循新设置，用于通过会话的[网络允许列表](#access-levels)的请求。您无需启动新会话。

220 222

221<Note>223<Note>

222 您在会话或例程上启用的 MCP 连接器无需将其主机添加到 **Allowed domains**，因为连接器流量通过 Anthropic 的服务器而不是会话的网络传输。这依赖于[安全性和隔离](/docs/zh-CN/claude-code-on-the-web#security-and-isolation)下提到的同一条通往 Anthropic 的通道。关闭任何您不需要的连接器，以限制 Claude 可以访问的工具。224 您在会话或 Routine 上启用的 MCP 连接器无需将其主机添加到 **Allowed domains**，因为连接器流量通过 Anthropic 的服务器而不是会话的网络传输。这依赖于[安全性和隔离](/docs/zh-CN/claude-code-on-the-web#security-and-isolation)下提到的同一条通往 Anthropic 的通道。关闭任何您不需要的连接器，以限制 Claude 可以访问的工具。

223</Note>225</Note>

224 226

225<h3 id="access-levels">227<h3 id="access-levels">

239 241

240* GitHub，通过其[单独的代理](#github-proxy)242* GitHub，通过其[单独的代理](#github-proxy)

241* 您启用的 [MCP 连接器](#network-access)，其流量通过 Anthropic 的服务器传输243* 您启用的 [MCP 连接器](#network-access)，其流量通过 Anthropic 的服务器传输

242* 您在环境的[网络密钥](#add-api-credentials)上列出的主机，除了[永远不会获得该密钥的主机](#requests-that-never-get-the-credential)244* 您在环境的[网络密钥](#add-network-secrets)上列出的主机，除了[永远不会获得该密钥的主机](#requests-that-never-get-the-credential)

243* Anthropic API，用于 Claude Code 自己的请求，即使在 **None** 下也是如此，如[安全性和隔离](/docs/zh-CN/claude-code-on-the-web#security-and-isolation)下所述245* Anthropic API，用于 Claude Code 自己的请求，即使在 **None** 下也是如此，如[安全性和隔离](/docs/zh-CN/claude-code-on-the-web#security-and-isolation)下所述

244 246

245<h3 id="allow-specific-domains">247<h3 id="allow-specific-domains">

254registry.example.com256registry.example.com

255```257```

256 258

257此环境中的会话现在可以访问 `api.example.com`、`internal.example.com` 的任何子域和 `registry.example.com`，但无法通过会话的网络访问其他域。[GitHub 流量](#github-proxy)、[MCP 连接器流量](#network-access)和对环境[网络密钥](#add-api-credentials)的主机的请求（除了[永远不会获得该密钥的主机](#requests-that-never-get-the-credential)）不经过此允许列表。前导 `*.` 匹配每个子域。要同时保留 [Trusted 域](#default-allowed-domains)，请勾选 **Also include default list of common package managers**；不勾选则只允许您列出的内容。259此环境中的会话现在可以访问 `api.example.com`、`internal.example.com` 的任何子域和 `registry.example.com`，但无法通过会话的网络访问其他域。[GitHub 流量](#github-proxy)、[MCP 连接器流量](#network-access)和对环境[网络密钥](#add-network-secrets)的主机的请求（除了[永远不会获得该密钥的主机](#requests-that-never-get-the-credential)）不经过此允许列表。前导 `*.` 匹配每个子域。要同时保留 [Trusted 域](#default-allowed-domains)，请勾选 **Also include default list of common package managers**；不勾选则只允许您列出的内容。

258 260

259如果您的组织使用[工件](/docs/zh-CN/artifacts#availability)，会话读取工件时不需要在列表中包含 `*.frame.claudeusercontent.com`。当列表中没有该主机时，Claude Code 通过会话与 Anthropic 的连接读取工件内容。在两种情况下保留允许列表中的主机：261如果您的组织使用 [Artifact](/docs/zh-CN/artifacts#availability)，会话读取 Artifact 时不需要在列表中包含 `*.frame.claudeusercontent.com`。当列表中没有该主机时，Claude Code 通过会话与 Anthropic 的连接读取 Artifact 内容。在两种情况下保留允许列表中的主机：

260 262

261* **此环境中的会话打开另一个组织的公开工件**：Claude Code 直接从主机获取这些工件，因此将其添加到此列表。263* **此环境中的会话打开另一个组织的公开 Artifact**：Claude Code 直接从主机获取这些 Artifact，因此将其添加到此列表。

262* **您正在配置本地 CLI 或自托管运行器**：在该允许列表中保留主机。请参阅[网络访问要求](/docs/zh-CN/network-config#network-access-requirements)和自托管[网络要求](/docs/zh-CN/self-hosted-environments-deploy#network-requirements)。264* **您正在配置本地 CLI 或自托管运行器**：在该允许列表中保留主机。请参阅[网络访问要求](/docs/zh-CN/network-config#network-access-requirements)和自托管[网络要求](/docs/zh-CN/self-hosted-environments-deploy#network-requirements)。

263 265

264每个环境都有自己的允许域列表；没有组织级别的允许列表可供管理员推送到每个成员的环境。[服务器管理的设置](/docs/zh-CN/server-managed-settings)也不会将域添加到环境的网络允许列表。要为团队提供一个标准列表，Owner 可以创建一个具有 **Custom** 网络访问和该列表的[组织共享环境](#organization-shared-environments)。266每个环境都有自己的允许域列表；没有组织级别的允许列表可供管理员推送到每个成员的环境。[服务器管理的设置](/docs/zh-CN/server-managed-settings)也不会将域添加到环境的网络允许列表。要为团队提供一个标准列表，Owner 可以创建一个具有 **Custom** 网络访问和该列表的[组织共享环境](#organization-shared-environments)。

267 GitHub 代理269 GitHub 代理

268</h3>270</h3>

269 271

270在 Anthropic 托管的环境中，所有 GitHub 操作都经过专用代理，使您的真实 GitHub 凭证保留在会话的 VM 之外，独立于环境的[访问级别](#access-levels)。自托管环境中的会话使用您的部署提供的凭证进行 git 操作身份验证；[配置 git](/docs/zh-CN/self-hosted-environments-deploy#configure-git)涵盖了选项，包括按会话生成的凭证和选择加入此同一代理。代理提供：272在 Anthropic 托管的环境中，所有 GitHub 操作都经过专用代理，使您的真实 GitHub 凭据保留在会话的 VM 之外，独立于环境的[访问级别](#access-levels)。自托管环境中的会话使用您的部署提供的凭据进行 git 操作身份验证；[配置 git](/docs/zh-CN/self-hosted-environments-deploy#configure-git)涵盖了选项，包括按会话生成的凭据和选择加入此同一代理。代理提供：

271 273

272* **Git 凭证**：VM 内的 git 客户端使用范围受限的凭证，代理验证并将其交换为您的实际 GitHub 令牌。274* **Git 凭据**：VM 内的 git 客户端使用范围受限的凭据，代理验证并将其交换为您的实际 GitHub 令牌。

273* **API 请求**：来自内置 GitHub 工具的请求，以及来自 [`proxy-injected` 占位符](#work-with-github-issues-and-pull-requests)下的 `gh` 的请求，会在替换为您的真实凭证后发出。275* **API 请求**：来自内置 GitHub 工具的请求，以及来自 [`proxy-injected` 占位符](#work-with-github-issues-and-pull-requests)下的 `gh` 的请求，会在替换为您的真实凭据后发出。

274* **推送限制**：代理会拒绝分支删除，以及推送分支以外的任何内容（例如标签）。它不限制推送可以更新哪些分支。如需限制，请在 GitHub 上使用分支保护规则或规则集。276* **推送限制**：代理会拒绝分支删除，以及推送分支以外的任何内容（例如标签）。它不限制推送可以更新哪些分支。如需限制，请在 GitHub 上使用分支保护规则或规则集。

275* **仓库范围**：代理为附加到会话的仓库处理 GitHub API 请求。针对其他仓库的 API 请求会收到 403，其消息以 `GitHub access to` 开头并包含 `is not enabled for this session`。277* **仓库范围**：代理为附加到会话的仓库处理 GitHub API 请求。针对其他仓库的 API 请求会收到 403，其消息以 `GitHub access to` 开头并包含 `is not enabled for this session`。

276* **GraphQL 限制**：代理会拒绝发往 GitHub GraphQL 端点的请求，返回 403，其消息以 `GitHub GraphQL is not available from Claude Code sessions` 开头，并指明 REST 回退方式 `gh api repos/{owner}/{repo}/...`。使用 GraphQL 的 `gh` 子命令（例如 `gh pr` 和 `gh issue`）也会收到相同的 403。无论您提供的凭据如何，限制都适用于通过代理的每个请求，因此您设置的 `GH_TOKEN` 会收到相同的 403。Claude 无法通过代理访问仅存在于 GraphQL 中的 GitHub API，例如 Projects v2。278* **GraphQL 限制**：代理会拒绝发往 GitHub GraphQL 端点的请求，返回 403，其消息以 `GitHub GraphQL is not available from Claude Code sessions` 开头，并指明 REST 回退方式 `gh api repos/{owner}/{repo}/...`。使用 GraphQL 的 `gh` 子命令（例如 `gh pr` 和 `gh issue`）也会收到相同的 403。无论您提供的凭据如何，限制都适用于通过代理的每个请求，因此您设置的 `GH_TOKEN` 会收到相同的 403。Claude 无法通过代理访问仅存在于 GraphQL 中的 GitHub API，例如 Projects v2。

277 279

278来自公开存储库的已提交文件通过 `raw.githubusercontent.com` 到达，改由[安全代理](#security-proxy)处理。该域在默认 [Trusted 列表](#default-allowed-domains)中，因此除非环境的[访问级别](#access-levels)排除它，否则这些文件保持可访问。280来自公开仓库的已提交文件通过 `raw.githubusercontent.com` 到达，改由[安全代理](#security-proxy)处理。该域在默认 [Trusted 列表](#default-allowed-domains)中，因此除非环境的[访问级别](#access-levels)排除它，否则这些文件保持可访问。

279 281

280<h3 id="security-proxy">282<h3 id="security-proxy">

281 安全代理283 安全代理

282</h3>284</h3>

283 285

284Anthropic 托管环境中的云会话在 HTTP/HTTPS 网络代理后面运行，用于安全和滥用防范目的；在[自托管环境](/docs/zh-CN/self-hosted-environments-deploy#default-deny-egress)中，出站流量通过您自己的网络边界离开。来自 Anthropic 托管会话的所有出站互联网流量都经过此代理，它提供：286Anthropic 托管环境中的云端会话在 HTTP/HTTPS 网络代理后面运行，用于安全和滥用防范目的；在[自托管环境](/docs/zh-CN/self-hosted-environments-deploy#default-deny-egress)中，出站流量通过您自己的网络边界离开。来自 Anthropic 托管会话的所有出站互联网流量都经过此代理，它提供：

285 287

286* 防范恶意请求288* 防范恶意请求

287* 速率限制和滥用防范289* 速率限制和滥用防范

316| 仅在您的用户设置中启用的插件 | 否 | 用户作用域的 `enabledPlugins` 位于您机器上的 `~/.claude/settings.json` |318| 仅在您的用户设置中启用的插件 | 否 | 用户作用域的 `enabledPlugins` 位于您机器上的 `~/.claude/settings.json` |

317| 您使用 `claude mcp add` 在默认本地作用域或用户作用域添加的 MCP 服务器 | 否 | 这些写入您机器上的 `~/.claude.json`，而不是仓库。请使用 `claude mcp add --scope project` 添加服务器，它会写入仓库的 [`.mcp.json`](/docs/zh-CN/mcp#project-scope)，并提交该文件。具有一个仓库的会话会加载它 |319| 您使用 `claude mcp add` 在默认本地作用域或用户作用域添加的 MCP 服务器 | 否 | 这些写入您机器上的 `~/.claude.json`，而不是仓库。请使用 `claude mcp add --scope project` 添加服务器，它会写入仓库的 [`.mcp.json`](/docs/zh-CN/mcp#project-scope)，并提交该文件。具有一个仓库的会话会加载它 |

318| 您的仓库的 `.claude/settings.json` `env` 块中的传输变量，例如 `NODE_EXTRA_CA_CERTS` 和 [mTLS 客户端证书变量](/docs/zh-CN/network-config#mtls-authentication) | 否 | 托管环境管理会话的 API 连接，因此 Claude Code 忽略这些键，并在会话的调试日志中记录每个被忽略的键 |320| 您的仓库的 `.claude/settings.json` `env` 块中的传输变量，例如 `NODE_EXTRA_CA_CERTS` 和 [mTLS 客户端证书变量](/docs/zh-CN/network-config#mtls-authentication) | 否 | 托管环境管理会话的 API 连接，因此 Claude Code 忽略这些键，并在会话的调试日志中记录每个被忽略的键 |

319| Claude 调用的服务的 API 密钥和令牌 | 在 Pro 和 Max 计划中，作为[网络密钥](#add-api-credentials) | 您在环境中添加一次密钥，Agent 代理会将其附加到发往您列出的主机的请求。Agent 代理[无法附加](#requests-that-never-get-the-credential)的密钥，或 Team 或 Enterprise 计划中的任何密钥，保留在环境变量中 |321| Claude 调用的服务的 API 密钥和令牌 | 在 Pro 和 Max 计划中，作为[网络密钥](#add-network-secrets) | 您在环境中添加一次密钥，Agent 代理会将其附加到发往您列出的主机的请求。Agent 代理[无法附加](#requests-that-never-get-the-credential)的密钥，或 Team 或 Enterprise 计划中的任何密钥，保留在环境变量中 |

320| 交互式身份验证，例如 AWS SSO | 否 | 不支持。SSO 需要基于浏览器的登录，无法在云端会话中执行 |322| 交互式身份验证，例如 AWS SSO | 否 | 不支持。SSO 需要基于浏览器的登录，无法在云端会话中执行 |

321 323

322要在云端会话中提供您自己的配置，请将其提交到仓库。324要在云端会话中提供您自己的配置，请将其提交到仓库。

323 325

324任何使用环境的人都可以读取其环境变量和设置脚本。对话框在**环境变量**下的注释说明了这一点，并警告不要在那里放置密钥。在 Pro 和 Max 计划中，请改为将 Agent 代理可以附加的密钥存储为[网络密钥](#add-api-credentials)。326任何使用环境的人都可以读取其环境变量和设置脚本。对话框在**环境变量**下的注释说明了这一点，并警告不要在那里放置密钥。在 Pro 和 Max 计划中，请改为将 Agent 代理可以附加的密钥存储为[网络密钥](#add-network-secrets)。

325 327

326<h4 id="add-personal-preferences-without-committing-to-the-repo">328<h4 id="add-personal-preferences-without-committing-to-the-repo">

327 添加个人偏好而无需提交到仓库329 添加个人偏好而无需提交到仓库

commands.md +1 −1

Details

87| `/design-sync [hint]` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 转换您仓库中的 React 设计系统并将其上传到 [Claude Design](https://claude.ai/design)，使其生成的设计使用您的真实组件。可选择为设计系统命名，例如 `/design-sync Acme DS`。首次同步会验证每个组件，在大型仓库上可能需要几个小时。可在 Anthropic API 上使用。它需要 claude.ai，而 CLI 在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 上，或通过 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway#availability-and-limitations) 使用时不会连接 claude.ai，因此该命令在这些情况下不可用 |87| `/design-sync [hint]` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 转换您仓库中的 React 设计系统并将其上传到 [Claude Design](https://claude.ai/design)，使其生成的设计使用您的真实组件。可选择为设计系统命名，例如 `/design-sync Acme DS`。首次同步会验证每个组件，在大型仓库上可能需要几个小时。可在 Anthropic API 上使用。它需要 claude.ai，而 CLI 在 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 或 Claude Platform on AWS 上，或通过 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway#availability-and-limitations) 使用时不会连接 claude.ai，因此该命令在这些情况下不可用 |

88| `/desktop` | 在 Claude Code Desktop 应用中继续当前会话。需要 macOS 或 x64 Windows 以及 Claude 订阅。别名：`/app` |88| `/desktop` | 在 Claude Code Desktop 应用中继续当前会话。需要 macOS 或 x64 Windows 以及 Claude 订阅。别名：`/app` |

89| `/diff` | 审查工作树中的更改，包括 Claude 到目前为止所做的编辑。请参阅[使用 /diff 审查更改](/docs/zh-CN/interactive-mode#review-changes-with-%2Fdiff) |89| `/diff` | 审查工作树中的更改，包括 Claude 到目前为止所做的编辑。请参阅[使用 /diff 审查更改](/docs/zh-CN/interactive-mode#review-changes-with-%2Fdiff) |

90| `/doctor [prompt-audit [path]]` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 运行设置检查，诊断问题并可以修复它们。检查安装健康状况，包括重复或残留的安装、`PATH` 问题以及无法解析的设置文件。找出未使用的 skill、MCP 服务器和插件，并与其上下文开销进行对比，标记运行缓慢的 [hook](/docs/zh-CN/hooks)，并检查您的[发布渠道](/docs/zh-CN/setup#configure-release-channel)上是否有较新版本。将本地 `CLAUDE.md` 文件与已签入的文件进行去重，通过删除 Claude 可以从代码库推导出的内容来精简已签入的 [`CLAUDE.md`](/docs/zh-CN/memory#my-claude-md-is-too-large) 文件，并将剩余的始终加载的指导迁移到按需加载的 [skill](/docs/zh-CN/skills) 和嵌套 `CLAUDE.md` 文件中。还会提议将[自动模式](/docs/zh-CN/permissions#permission-modes)设为默认模式，并[预先批准](/docs/zh-CN/permissions)经常被拒绝的只读命令。先报告发现的问题，并在更改任何内容之前请求确认。在终端中，`claude doctor` 会输出只读的安装诊断信息而不启动会话。别名：`/checkup`。运行 `/doctor prompt-audit` 可让 Claude [审计您的 `CLAUDE.md` 文件、skill 和其他配置](/docs/zh-CN/memory#audit-your-instruction-files)，查找过时或相互冲突的指令，而不是运行设置检查。`prompt-audit` 子命令需要 Claude Code v2.1.283 或更高版本。`CLAUDE.md` 精简检查需要 Claude Code v2.1.206 或更高版本。在 v2.1.205 之前，`/doctor` 会打开只读诊断屏幕，按 `f` 会将报告发送给 Claude |90| `/doctor [prompt-audit [path]]` | **[Skill](/docs/zh-CN/skills#bundled-skills)。** 运行设置检查，诊断安装、设置、扩展和 `CLAUDE.md` 方面的问题，并提出修复建议，Claude 会在您确认后应用这些修复。有关检查涵盖的内容，或要改用 `prompt-audit` 审计您的指令，请参阅[使用 `/doctor` 检查您的设置](/docs/zh-CN/skills#check-your-setup-with-/doctor)。`prompt-audit` 子命令需要 Claude Code v2.1.283 或更高版本。别名：`/checkup` |

91| `/effort [level\|auto\|status\|ultracode [on\|off]]` | 设置 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)：`low` 到 `xhigh`、`max` 或 `auto`；`status` 会输出当前级别。`ultracode` 或 `ultracode on` 会以当前级别为会话开启 [ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)，`ultracode off` 会将其关闭；[`ultracode`](/docs/zh-CN/settings-reference#ultracode) 键会持久保存。`max` 仅对当前会话有效。`on` 和 `off` 参数以及保持当前级别需要 Claude Code v2.1.284 或更高版本。在 v2.1.284 之前，`/effort ultracode` 会将会话设置为 `xhigh`，而 `/effort ultracode off` 会失败并报告 `Invalid argument`。在 Claude 回复时运行此命令，一旦您确认[缓存警告](/docs/zh-CN/prompt-caching#changing-effort-level)（如果 Claude Code 显示了该警告），Claude Code 就会将新级别应用于该轮次中的下一个请求。在 v2.1.242 之前，Claude Code 会根据从 Anthropic 获取的功能标志来决定是在轮次中途运行该命令，还是将其排队直到轮次结束，并且在不[获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话中（例如在[第三方提供商](/docs/zh-CN/third-party-integrations)上）始终将其排队。可在 `-p` 中使用 |91| `/effort [level\|auto\|status\|ultracode [on\|off]]` | 设置 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)：`low` 到 `xhigh`、`max` 或 `auto`；`status` 会输出当前级别。`ultracode` 或 `ultracode on` 会以当前级别为会话开启 [ultracode](/docs/zh-CN/workflows#let-claude-decide-with-ultracode)，`ultracode off` 会将其关闭；[`ultracode`](/docs/zh-CN/settings-reference#ultracode) 键会持久保存。`max` 仅对当前会话有效。`on` 和 `off` 参数以及保持当前级别需要 Claude Code v2.1.284 或更高版本。在 v2.1.284 之前，`/effort ultracode` 会将会话设置为 `xhigh`，而 `/effort ultracode off` 会失败并报告 `Invalid argument`。在 Claude 回复时运行此命令，一旦您确认[缓存警告](/docs/zh-CN/prompt-caching#changing-effort-level)（如果 Claude Code 显示了该警告），Claude Code 就会将新级别应用于该轮次中的下一个请求。在 v2.1.242 之前，Claude Code 会根据从 Anthropic 获取的功能标志来决定是在轮次中途运行该命令，还是将其排队直到轮次结束，并且在不[获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)的会话中（例如在[第三方提供商](/docs/zh-CN/third-party-integrations)上）始终将其排队。可在 `-p` 中使用 |

92| `/exit` | 退出 CLI。在已附加的[后台会话](/docs/zh-CN/agent-view#attach-to-a-session)中，此操作会分离，会话继续运行。别名：`/quit` |92| `/exit` | 退出 CLI。在已附加的[后台会话](/docs/zh-CN/agent-view#attach-to-a-session)中，此操作会分离，会话继续运行。别名：`/quit` |

93| `/export [filename]` | 将当前对话导出为纯文本。提供文件名时，直接写入该文件。不提供时，打开对话框以复制到剪贴板或保存到文件 |93| `/export [filename]` | 将当前对话导出为纯文本。提供文件名时，直接写入该文件。不提供时，打开对话框以复制到剪贴板或保存到文件 |

common-workflows.md +2 −3

Details

391 Explain the logic in @src/utils/auth.js391 Explain the logic in @src/utils/auth.js

392 ```392 ```

393 393

394 这在对话中包含文件的完整内容。394 当文件符合 [Read 工具](/docs/zh-CN/tools-reference#read-tool-behavior)的 token 限制（默认为 25,000 个 token）时，这会将文件内容包含在对话中。大于 256KB 的文本文件不会被包含。

395 </Step>395 </Step>

396 396

397 <Step title="引用目录">397 <Step title="引用目录">

446 询问 Claude 关于其功能446 询问 Claude 关于其功能

447</h3>447</h3>

448 448

449Claude 内置访问其文档，可以回答关于其自身功能和限制的问题。449Claude 可以回答关于其自身功能和限制的问题。它会在最新的 Claude Code 文档中查找答案，因此答案不局限于您正在运行的版本。

450 450

451<h4 id="example-questions">451<h4 id="example-questions">

452 示例问题452 示例问题

483<Tip>483<Tip>

484 提示：484 提示：

485 485

486 * Claude 始终可以访问最新的 Claude Code 文档，无论您使用的版本如何

487 * 提出具体问题以获得详细答案486 * 提出具体问题以获得详细答案

488 * Claude 可以解释复杂的功能，如 MCP 集成、企业配置和高级工作流程487 * Claude 可以解释复杂的功能，如 MCP 集成、企业配置和高级工作流程

489</Tip>488</Tip>

context-window.md +0 −2

Details

1634 1634

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

1636 1636

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

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)。1637自动压缩运行的位置取决于您的模型和配置。有关每个模型的边界，请参阅[默认自动压缩阈值](/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 1638

1641<h2 id="check-your-own-session">1639<h2 id="check-your-own-session">

corporate-launcher.md +1 −0

Details

128* **在大约三秒内到达 `exec`，每次启动器运行。** 冷后台调度在第一个输出字节之前连续运行启动器两次，因此请懒惰地或从缓存中执行单点登录交换等缓慢工作。128* **在大约三秒内到达 `exec`，每次启动器运行。** 冷后台调度在第一个输出字节之前连续运行启动器两次，因此请懒惰地或从缓存中执行单点登录交换等缓慢工作。

129* **容忍从内部调用自己。** Claude Code 将启动器应用于每个嵌套的自生成，因此获取独占资源的启动器必须检测它是否已持有它。129* **容忍从内部调用自己。** Claude Code 将启动器应用于每个嵌套的自生成，因此获取独占资源的启动器必须检测它是否已持有它。

130* **不要在 Claude Code 启动前写入终端。** 在 `exec` 前打印的任何内容都会在会话在初始化前死亡时报告为崩溃原因。130* **不要在 Claude Code 启动前写入终端。** 在 `exec` 前打印的任何内容都会在会话在初始化前死亡时报告为崩溃原因。

131* **不要依赖参数的书写方式。** 标志的值可能作为独立参数传入（`--flag value`），也可能与标志连在一起（`--flag=value`）。标志使用哪种形式可能会在不同版本之间发生变化。

131 132

132<h3 id="format-of-the-launcher-value">133<h3 id="format-of-the-launcher-value">

133 启动器值的格式134 启动器值的格式

debug-your-config.md +12 −1

Details

85 针对干净配置进行测试85 针对干净配置进行测试

86</h2>86</h2>

87 87

88使用 [`claude --safe-mode`](/docs/zh-CN/cli-reference#cli-flags) 开始，它会启动一个会话，禁用所有自定义，包括 `CLAUDE.md`、skills、plugins、hooks、MCP 服务器以及自定义命令和代理。身份验证、模型选择、内置工具和权限正常工作。如果问题在安全模式下消失，则其中一个方面是原因；使用上面的针对性检查来找出是哪一个。安全模式仍然应用来自你的组织的托管 hooks 和设置策略。托管 plugins、skills、CLAUDE.md 和 MCP 服务器被关闭。88首先使用 [`claude --safe-mode`](/docs/zh-CN/cli-reference#cli-flags)，它会启动一个禁用您的自定义内容的会话，包括：

90* `CLAUDE.md`

91* Skill、插件和 hook

92* MCP 服务器

93* 自定义命令和 Agent

94* 自定义输出样式

95* 自定义快捷键

97身份验证、模型选择、内置工具和权限正常工作。如果问题在安全模式下消失，则说明原因已缩小到您关闭的某一项。要找出具体是哪一项，请使用该项对应的检查，例如[查看加载到上下文中的内容](#see-what-loaded-into-context)、[检查 MCP 服务器](#check-mcp-servers)或[检查 hook](#check-hooks)。

99安全模式仍然应用来自您组织的托管 hook 和设置策略。托管插件、skill、`CLAUDE.md` 和 MCP 服务器会被关闭。

89 100

90如果问题在安全模式下仍然存在，或你的设置本身可疑，请与从你的常规设置中不加载任何内容的会话进行比较。将 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars) 指向一个空目录以绕过 `~/.claude` 下的所有内容，并从没有 `.claude` 文件夹、`.mcp.json` 或 `CLAUDE.md` 的目录启动，以便也跳过项目配置。101如果问题在安全模式下仍然存在，或你的设置本身可疑，请与从你的常规设置中不加载任何内容的会话进行比较。将 [`CLAUDE_CONFIG_DIR`](/docs/zh-CN/env-vars) 指向一个空目录以绕过 `~/.claude` 下的所有内容，并从没有 `.claude` 文件夹、`.mcp.json` 或 `CLAUDE.md` 的目录启动，以便也跳过项目配置。

91 102

desktop.md +131 −83

Details

63 使用提示框63 使用提示框

64</h3>64</h3>

65 65

66输入你想让 Claude 做的事情，然后按 **Enter** 发送。Claude 会读取你的项目文件，进行更改，并根据你的[权限模式](#choose-a-permission-mode)运行命令。你可以随时重定向 Claude：点击停止按钮立即中断，或输入更正并按 **Enter** 发送，无需停止正在运行的操作。Claude 会在当前操作完成后立即读取更正，并在下一步之前进行调整。66输入您想让 Claude 做的事情，然后按 **Enter** 发送。Claude 会读取您的项目文件，进行更改，并根据您的[权限模式](#choose-a-permission-mode)运行命令。您可以随时重定向 Claude：点击停止按钮立即中断，或输入更正并按 **Enter** 发送，无需停止正在运行的操作。Claude 会在当前操作完成后立即读取更正，并在下一步之前进行调整。

67 67

~~68提示框旁边的 **+** 按钮让你可以访问文件附件、[skills](#use-skills)、[connectors](#connect-external-tools) 和 [plugins](#install-plugins)。~~68提示框旁边的 **+** 按钮让您可以访问文件附件、[skill](#use-skills)、[连接器](#connect-external-tools) 和[插件](#install-plugins)。

70<h3 id="accept-a-suggested-prompt">

71 接受建议的提示词

72</h3>

74Claude 回复后，Code 选项卡可能会在空的输入框中以灰色文本显示建议的下一条提示词。Claude Code 通过一个简短的后台请求，根据您的对话[生成每条建议](/docs/zh-CN/interactive-mode#prompt-suggestions)，该请求会计入您套餐的用量限制或您的 API 费用。

76* **使用建议**：按 **Tab** 或 **右箭头** 将其放入输入框，根据需要进行编辑，然后按 **Enter** 发送。在接受建议之前按 **Enter** 不会发送它。

77* **编写自己的提示词**：直接开始输入。建议仅在输入框为空且没有附加文件时显示。

79前往 **Settings > Claude Code**，在 **Sessions** 下关闭 **Prompt suggestions**，即可从每个会话下次启动或恢复时起停止显示建议。

69 80

70<h3 id="add-files-and-context-to-prompts">81<h3 id="add-files-and-context-to-prompts">

71 向提示添加文件和上下文82 向提示添加文件和上下文

73 84

74提示框支持两种方式来引入外部上下文：85提示框支持两种方式来引入外部上下文：

75 86

~~76* **@mention 文件**：输入 `@` 后跟文件名，将文件添加到对话上下文。Claude 随后可以读取和引用该文件。@mention 在云或 WSL 会话中不可用。~~87* **@mention 文件**：输入 `@` 后跟文件名，将文件添加到对话上下文。Claude 随后可以读取和引用该文件。@mention 在云端或 WSL 会话中不可用。

77* **附加文件**：使用附件按钮将图像、PDF 和其他文件附加到你的提示，或直接将文件拖放到提示中。这对于共享错误的屏幕截图、设计模型或参考文档很有用。88* **附加文件**：使用附件按钮将图像、PDF 和其他文件附加到您的提示，或直接将文件拖放到提示中。这对于共享错误的屏幕截图、设计模型或参考文档很有用。

78 89

79<h3 id="choose-a-permission-mode">90<h3 id="choose-a-permission-mode">

80 选择权限模式91 选择权限模式

81</h3>92</h3>

82 93

83权限模式控制 Claude 在会话期间的自主程度：它是否在编辑文件、运行命令或两者之前询问。你可以随时使用发送按钮旁边的模式选择器切换权限模式。要自己批准每项更改，请切换到 Manual。94权限模式控制 Claude 在会话期间的自主程度：它是否在编辑文件、运行命令或两者之前询问。您可以随时使用发送按钮旁边的模式选择器切换权限模式。要自己批准每项更改，请切换到 Manual。

84 95

85要为新的本地会话设置默认模式，请将 `permissions.defaultMode` 添加到你的[设置文件](/docs/zh-CN/settings#where-settings-live)。桌面应用读取与 CLI 相同的设置文件。你在选择器中选择的模式会被记住（按文件夹），并对该文件夹优先于 `defaultMode`，除了 Plan，它仅适用于当前会话。96要为新的本地会话设置默认模式，请将 `permissions.defaultMode` 添加到您的[设置文件](/docs/zh-CN/settings#where-settings-live)。桌面应用读取与 CLI 相同的设置文件。您在选择器中选择的模式会被记住（按文件夹），并对该文件夹优先于 `defaultMode`，除了 Plan，它仅适用于当前会话。

86 97

87| 模式 | 设置键 | 行为 |98| 模式 | 设置键 | 行为 |

88| - | - | - |99| - | - | - |

93| **Bypass permissions** | `bypassPermissions` | Claude 运行时不需要权限提示，除了[任何模式都不会自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)、当 Claude [在外部网站上操作](#browse-external-sites)时的安全分类器，或桌面操作（Claude 总是首先询问），例如[归档会话](#work-across-sessions)。等同于 CLI 中的 `--dangerously-skip-permissions`。在 Pro 和 Max 计划上，在你的设置 → Claude Code 中启用它，在"允许绕过权限模式"下；在 Team 和 Enterprise 计划上没有设置切换，组织策略控制它。仅在沙箱容器或虚拟机中使用。 |104| **Bypass permissions** | `bypassPermissions` | Claude 运行时不需要权限提示，除了[任何模式都不会自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)、当 Claude [在外部网站上操作](#browse-external-sites)时的安全分类器，或桌面操作（Claude 总是首先询问），例如[归档会话](#work-across-sessions)。等同于 CLI 中的 `--dangerously-skip-permissions`。在 Pro 和 Max 计划上，在您的设置 → Claude Code 中启用它，在"Allow bypass permissions mode"下；在 Team 和 Enterprise 计划上没有设置切换，由组织策略控制它。仅在沙箱容器或虚拟机中使用。 |

94 105

~~95代码选项卡的早期版本将这些模式标记为 Ask permissions、Auto accept edits 和 Plan mode。~~106Code 选项卡的早期版本将这些模式标记为 Ask permissions、Auto accept edits 和 Plan mode。

96 107

97`dontAsk` 权限模式仅在 [CLI](/docs/zh-CN/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) 中可用。108`dontAsk` 权限模式仅在 [CLI](/docs/zh-CN/permission-modes#allow-only-pre-approved-tools-with-dontask-mode) 中可用。

98 109

99<Tip title="最佳实践">110<Tip title="最佳实践">

100 在 Plan 中开始复杂任务，以便 Claude 在进行更改之前制定方法。一旦你批准计划，切换到 Accept edits 或 Manual 来执行它。有关此工作流的更多信息，请参阅[先探索，然后计划，然后编码](/docs/zh-CN/best-practices#explore-first-then-plan-then-code)。111 在 Plan 中开始复杂任务，以便 Claude 在进行更改之前制定方法。一旦您批准计划，切换到 Accept edits 或 Manual 来执行它。有关此工作流的更多信息，请参阅[先探索，然后计划，然后编码](/docs/zh-CN/best-practices#explore-first-then-plan-then-code)。

101</Tip>112</Tip>

102 113

103云会话支持 Accept edits、Plan 和 Auto。Accept edits 对应于 `default` 模式：云会话预先批准文件编辑，因此选择器显示 Accept edits 而不是 Manual。Bypass permissions 在云会话中不可用，包括[自托管环境](/docs/zh-CN/self-hosted-environments)中的会话。114云端会话支持 Accept edits、Plan 和 Auto。Accept edits 对应于 `default` 模式：云端会话预先批准文件编辑，因此选择器显示 Accept edits 而不是 Manual。Bypass permissions 在云端会话中不可用，包括[自托管环境](/docs/zh-CN/self-hosted-environments)中的会话。

104 115

105Enterprise 管理员可以限制哪些权限模式可用。有关详细信息，请参阅[企业配置](#enterprise-configuration)。116Enterprise 管理员可以限制哪些权限模式可用。有关详细信息，请参阅[企业配置](#enterprise-configuration)。

106 117

113在将 Desktop 路由到 Google Cloud 的 Agent Platform 的 Enterprise 部署中，自动模式也默认可用；有关支持的模型，请参阅 [Bedrock、Agent Platform 或 Foundry 上的自动模式](/docs/zh-CN/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)。124在将 Desktop 路由到 Google Cloud 的 Agent Platform 的 Enterprise 部署中，自动模式也默认可用；有关支持的模型，请参阅 [Bedrock、Agent Platform 或 Foundry 上的自动模式](/docs/zh-CN/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry)。

114 125

115<h3 id="preview-your-app">126<h3 id="preview-your-app">

116 预览你的应用127 预览您的应用

117</h3>128</h3>

118 129

119Claude 可以启动开发服务器并在浏览器窗格中打开它以验证其更改。这适用于前端 Web 应用以及后端服务器：Claude 可以测试 API 端点、查看服务器日志，并迭代它发现的问题。在大多数情况下，Claude 在编辑项目文件后自动启动服务器。你也可以随时要求 Claude 进行预览。默认情况下，Claude [自动验证](#auto-verify-changes)每次编辑后的更改。130Claude 可以启动开发服务器并在浏览器窗格中打开它以验证其更改。这适用于前端 Web 应用以及后端服务器：Claude 可以测试 API 端点、查看服务器日志，并迭代它发现的问题。在大多数情况下，Claude 在编辑项目文件后自动启动服务器。您也可以随时要求 Claude 进行预览。默认情况下，Claude [自动验证](#auto-verify-changes)每次编辑后的更改。

120 131

121浏览器窗格也可以打开项目中的静态 HTML 文件、PDF、图像和视频。在聊天中点击 HTML、PDF、图像或视频路径以在那里打开它。132浏览器窗格也可以打开项目中的静态 HTML 文件、PDF、图像和视频。在聊天中点击 HTML、PDF、图像或视频路径以在那里打开它。

122 133

123从浏览器窗格，你可以：134从浏览器窗格，您可以：

124 135

125* 直接在浏览器窗格中与运行的应用交互136* 直接在浏览器窗格中与运行的应用交互

126* 观看 Claude 自动验证其自己的更改：它拍摄屏幕截图、检查 DOM、点击元素、填充表单，并修复它发现的问题137* 观看 Claude 自动验证其自己的更改：它拍摄屏幕截图、检查 DOM、点击元素、填充表单，并修复它发现的问题

127* 从浏览器窗格标题栏中的 **Dev servers** 菜单启动或停止服务器，或一次停止所有服务器138* 从浏览器窗格标题栏中的 **Dev servers** 菜单启动或停止服务器，或一次停止所有服务器

128* 通过浏览器窗格 **⋮** 菜单中的 **Keep cookies**，选择浏览器在您退出应用后是否保留 cookie，这样您就不必在开发期间重新登录139* 通过浏览器窗格 **⋮** 菜单中的 **Keep cookies**，选择浏览器在您退出应用后是否保留 cookie，这样您就不必在开发期间重新登录

129 140

130Claude 根据你的项目创建初始服务器配置。如果你的应用使用自定义开发命令，编辑 `.claude/launch.json` 以匹配你的设置。有关完整参考，请参阅[配置预览服务器](#configure-preview-servers)。141Claude 根据您的项目创建初始服务器配置。如果您的应用使用自定义开发命令，编辑 `.claude/launch.json` 以匹配您的设置。有关完整参考，请参阅[配置预览服务器](#configure-preview-servers)。

131 142

132要清除浏览器保存的数据，请在浏览器窗格的 **⋮** 菜单中选择 **Clear browsing data**。要完全关闭浏览器，请在 **Settings > Claude Code** 中关闭 **Browser tools**。143要清除浏览器保存的数据，请在浏览器窗格的 **⋮** 菜单中选择 **Clear browsing data**。要完全关闭浏览器，请在 **Settings > Claude Code** 中关闭 **Browser tools**。

133 144

139 150

140您第一次点击聊天中的外部链接时，会出现一个对话框，询问链接是在浏览器窗格中打开还是在您的默认浏览器中打开。要在之后更改您的选择，请使用浏览器窗格 **⋮** 菜单中的 **Open links in built-in browser**。在 macOS 上 **Cmd** 点击或在 Windows 上 **Ctrl** 点击会直接在您的默认浏览器中打开链接。151您第一次点击聊天中的外部链接时，会出现一个对话框，询问链接是在浏览器窗格中打开还是在您的默认浏览器中打开。要在之后更改您的选择，请使用浏览器窗格 **⋮** 菜单中的 **Open links in built-in browser**。在 macOS 上 **Cmd** 点击或在 Windows 上 **Ctrl** 点击会直接在您的默认浏览器中打开链接。

141 152

142Claude 可以使用与[验证你的应用](#preview-your-app)相同的工具读取和交互外部页面，并进行两项额外的安全检查：153Claude 可以使用与[验证您的应用](#preview-your-app)相同的工具读取和交互外部页面，并进行两项额外的安全检查：

143 154

144* 安全分类器在每个权限模式中审查 Claude 在外部页面上的写入操作，例如点击和输入。这些与 [auto mode](#choose-a-permission-mode) 使用的分类器相同，当它们标记操作时，无论模式如何，你都会获得权限提示。155* 安全分类器在每个权限模式中审查 Claude 在外部页面上的写入操作，例如点击和输入。这些与[自动模式](#choose-a-permission-mode)使用的分类器相同，当它们标记操作时，无论模式如何，您都会收到权限提示。

145* 在 Auto 和 Bypass permissions 以外的权限模式中，在 Claude 导航到新网站之前也会应用域名允许列表检查。156* 在 Auto 和 Bypass permissions 以外的权限模式中，在 Claude 导航到新网站之前也会应用域名允许列表检查。

146 157

147<h4 id="approve-claude’s-actions-on-a-site">158<h4 id="approve-claude’s-actions-on-a-site">

148 批准 Claude 在网站上的操作159 批准 Claude 在网站上的操作

149</h4>160</h4>

150 161

151Claude 第一次在外部网站上操作时，会出现权限卡，Claude 等待你的选择：**允许一次**、**始终允许**或**拒绝**。**允许一次**批准操作而不保存任何内容。**始终允许**在你的设备上保存该网站的批准，你可以在设置中撤销它。每个网站都需要自己的批准，包括子域。你的本地开发服务器和项目文件不需要批准，因此[自动验证](#auto-verify-changes)继续工作而不需要提示。162Claude 第一次在外部网站上操作时，会出现权限卡，Claude 等待您的选择：**Allow once**、**Always allow** 或 **Deny**。**Allow once** 批准操作而不保存任何内容。**Always allow** 在您的设备上保存该网站的批准，您可以在设置中撤销它。每个网站都需要自己的批准，包括子域。您的本地开发服务器和项目文件不需要批准，因此[自动验证](#auto-verify-changes)继续工作而不需要提示。

152 163

153即使在批准的网站上，Claude 也不会在没有你的输入的情况下购买物品、创建账户或绕过 CAPTCHA。在浏览器窗格中浏览使用与 [Claude in Chrome extension](/docs/zh-CN/chrome) 相同的安全模型。有关 Claude 如何处理敏感网站和风险操作的信息，请参阅[安全使用 Chrome 中的 Claude](https://support.claude.com/en/articles/12902428-using-claude-in-chrome-safely)。164即使在批准的网站上，Claude 也不会在没有您的输入的情况下购买物品、创建账户或绕过 CAPTCHA。在浏览器窗格中浏览使用与 [Claude in Chrome extension](/docs/zh-CN/chrome) 相同的安全模型。有关 Claude 如何处理敏感网站和风险操作的信息，请参阅[安全使用 Chrome 中的 Claude](https://support.claude.com/en/articles/12902428-using-claude-in-chrome-safely)。

154 165

155<h4 id="choose-between-the-browser-and-the-chrome-extension">166<h4 id="choose-between-the-browser-and-the-chrome-extension">

156 在浏览器和 Chrome 扩展之间选择167 在浏览器和 Chrome 扩展之间选择

157</h4>168</h4>

158 169

159浏览器窗格使用干净的浏览器配置文件，与你的个人浏览器分开，没有你保存的登录或历史记录。将其用于构建和测试你的应用以及不需要你的身份的网站。当你想让 Claude 在你的登录会话中充当你时，请改用 [Claude in Chrome extension](/docs/zh-CN/chrome)，它共享你的浏览器的登录状态。170浏览器窗格使用干净的浏览器配置文件，与您的个人浏览器分开，没有您保存的登录或历史记录。将其用于构建和测试您的应用以及不需要您的身份的网站。当您想让 Claude 在您的登录会话中以您的身份操作时，请改用 [Claude in Chrome extension](/docs/zh-CN/chrome)，它共享您的浏览器的登录状态。

160 171

161<h4 id="restrict-external-browsing-for-your-organization">172<h4 id="restrict-external-browsing-for-your-organization">

162 为你的组织限制外部浏览173 为您的组织限制外部浏览

163</h4>174</h4>

164 175

165浏览器遵循与 Claude in Chrome 扩展相同的[网站允许列表和阻止列表控制](https://support.claude.com/en/articles/13065128-claude-in-chrome-admin-controls)。如果你的组织已经为扩展配置了这些列表，浏览器会自动尊重它们。管理员也可以使用 [`browserExternalPageTools` 托管设置](#managed-settings)关闭 Claude 在外部页面上的工具。禁用工具后，用户仍然可以导航到外部网站；Claude 的工具无法读取或操作它们。176浏览器遵循与 Claude in Chrome 扩展相同的[网站允许列表和阻止列表控制](https://support.claude.com/en/articles/13065128-claude-in-chrome-admin-controls)。如果您的组织已经为扩展配置了这些列表，浏览器会自动遵循它们。管理员也可以使用 [`browserExternalPageTools` 托管设置](#managed-settings)关闭 Claude 在外部页面上的工具。禁用工具后，用户仍然可以访问外部网站；Claude 的工具无法读取或操作它们。

166 177

167要完全关闭外部浏览，请将 [`disableBrowserExternalNavigation` 托管设置](#managed-settings)设置为 `true`。这会阻止浏览器中的所有外部导航，包括你的组织允许列表上的网站；localhost 开发服务器和文件预览继续工作。使用 `browserExternalPageTools` 让用户继续浏览外部网站而不使用 Claude 的工具，使用 `disableBrowserExternalNavigation` 为用户和 Claude 阻止外部网站。178要完全关闭外部浏览，请将 [`disableBrowserExternalNavigation` 托管设置](#managed-settings)设置为 `true`。这会阻止浏览器中的所有外部导航，包括您的组织允许列表上的网站；localhost 开发服务器和文件预览继续工作。使用 `browserExternalPageTools` 让用户继续浏览外部网站而不使用 Claude 的工具，使用 `disableBrowserExternalNavigation` 为用户和 Claude 阻止外部网站。

168 179

169<h3 id="review-changes-with-diff-view">180<h3 id="review-changes-with-diff-view">

170 使用差异视图审查更改181 使用 diff 视图审查更改

171</h3>182</h3>

172 183

173Claude 对你的代码进行更改后，差异视图让你在创建拉取请求之前逐个文件审查修改。184Claude 对您的代码进行更改后，diff 视图让您在创建 Pull Request 之前逐个文件审查修改。

174 185

175当 Claude 更改文件时，会出现一个差异统计指示器，显示添加和删除的行数，例如 `+12 -1`。点击此指示器打开差异查看器，它在左侧显示文件列表，在右侧显示每个文件的更改。186当 Claude 更改文件时，会出现一个 diff 统计指示器，显示添加和删除的行数，例如 `+12 -1`。点击此指示器打开 diff 查看器，它在左侧显示文件列表，在右侧显示每个文件的更改。

176 187

177要对特定行进行评论，点击差异中的任何行以打开评论框。输入你的反馈并按 **Enter** 添加评论。在多行添加评论后，一次提交所有评论：188要对特定行进行评论，点击 diff 中的任何行以打开评论框。输入您的反馈并按 **Enter** 添加评论。在多行添加评论后，一次提交所有评论：

178 189

179* **macOS**：按 **Cmd+Enter**190* **macOS**：按 **Cmd+Enter**

180* **Windows**：按 **Ctrl+Enter**191* **Windows**：按 **Ctrl+Enter**

181 192

182Claude 读取你的评论并进行请求的更改，这些更改显示为你可以审查的新差异。193Claude 读取您的评论并进行请求的更改，这些更改显示为您可以审查的新 diff。

183 194

184<h3 id="review-your-code">195<h3 id="review-your-code">

185 审查你的代码196 审查您的代码

186</h3>197</h3>

187 198

188要让 Claude 在您提交之前审查您的更改，请在[输入框](#use-the-prompt-box)中输入 `/code-review`。审查完成后，结果会出现在对话中。199要让 Claude 在您提交之前审查您的更改，请在[输入框](#use-the-prompt-box)中输入 `/code-review`。审查完成后，结果会出现在对话中。

195在任何会话中，您也可以在输入框中要求 Claude 修复审查发现的问题。有关 `/code-review` 检查的内容及其接受的参数，请参阅[在本地审查 diff](/docs/zh-CN/code-review#review-a-diff-locally)。206在任何会话中，您也可以在输入框中要求 Claude 修复审查发现的问题。有关 `/code-review` 检查的内容及其接受的参数，请参阅[在本地审查 diff](/docs/zh-CN/code-review#review-a-diff-locally)。

196 207

197<h3 id="monitor-pull-request-status">208<h3 id="monitor-pull-request-status">

198 监控拉取请求状态209 监控 Pull Request 状态

199</h3>210</h3>

200 211

201打开拉取请求后，CI 状态栏会出现在会话中。Claude Code 使用 GitHub CLI 轮询检查结果并显示失败。212打开 Pull Request 后，CI 状态栏会出现在会话中。Claude Code 使用 GitHub CLI 轮询检查结果并显示失败。

202 213

203* **Auto-fix CI & address comments**：启用后，Claude 会通过读取失败输出并迭代来自动尝试修复失败的 CI 检查。在本地会话中，当评论作者是仓库所有者、组织成员、协作者或 GitHub App 时，Claude 还会处理除您之外的其他人留下的新审查评论。214* **Auto-fix CI & address comments**：启用后，Claude 会通过读取失败输出并迭代来自动尝试修复失败的 CI 检查。在本地会话中，当评论作者是仓库所有者、组织成员、协作者或 GitHub App 时，Claude 还会处理除您之外的其他人留下的新审查评论。

204* **Auto-merge when ready**：启用后，Claude 在所有检查通过后合并 PR。合并方法是 squash。请先在您的 [GitHub 仓库设置](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository)中启用自动合并；没有它，Claude 无法合并 PR。215* **Auto-merge when ready**：启用后，Claude 在所有检查通过后合并 PR。合并方法是 squash。请先在您的 [GitHub 仓库设置](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-auto-merge-for-pull-requests-in-your-repository)中启用自动合并；没有它，Claude 无法合并 PR。

206要启用这些选项，请点击状态栏中的 **CI**。要在 PR 合并或关闭后自动归档会话，请在 **Settings > Claude Code** 中打开[自动归档](#work-in-parallel-with-sessions)。217要启用这些选项，请点击状态栏中的 **CI**。要在 PR 合并或关闭后自动归档会话，请在 **Settings > Claude Code** 中打开[自动归档](#work-in-parallel-with-sessions)。

207 218

208<Note>219<Note>

209 PR 监控需要在你的机器上安装并认证 [GitHub CLI (`gh`)](https://cli.github.com/)。如果未安装 `gh`，Desktop 会在你第一次尝试创建 PR 时提示你安装它。220 PR 监控需要在您的机器上安装并认证 [GitHub CLI (`gh`)](https://cli.github.com/)。如果未安装 `gh`，Desktop 会在您第一次尝试创建 PR 时提示您安装它。

210</Note>221</Note>

211 222

212<h2 id="arrange-your-workspace">223<h2 id="arrange-your-workspace">

231 打开和编辑文件242 打开和编辑文件

232</h3>243</h3>

233 244

234点击聊天或 diff 查看器中的文件路径在文件窗格中打开它。HTML、PDF、图像和视频路径改为在[浏览器窗格](#preview-your-app)中打开。进行现场编辑并点击 **Save** 来写回。如果文件自你打开它以来在磁盘上更改，窗格会警告你并让你覆盖或丢弃。点击 **Discard** 来恢复你的编辑，或点击窗格标题中的路径来复制绝对路径。245点击聊天或 diff 查看器中的文件路径在文件窗格中打开它。HTML、PDF、图像和视频路径改为在[浏览器窗格](#preview-your-app)中打开。进行现场编辑并点击 **Save** 来写回。如果文件自您打开它以来在磁盘上更改，窗格会警告您并让您覆盖或丢弃。点击 **Discard** 来恢复您的编辑，或点击窗格标题中的路径来复制绝对路径。

235 246

236文件窗格在本地和 SSH 会话中可用。对于云会话，要求 Claude 进行更改。247文件窗格在本地和 SSH 会话中可用。对于云端会话，要求 Claude 进行更改。

237 248

238<h3 id="open-files-in-other-apps">249<h3 id="open-files-in-other-apps">

239 在其他应用中打开文件250 在其他应用中打开文件

241 252

242右键点击聊天、diff 查看器或文件窗格中的任何文件路径来打开上下文菜单：253右键点击聊天、diff 查看器或文件窗格中的任何文件路径来打开上下文菜单：

243 254

244* **Attach as context**：将文件添加到你的下一个提示255* **Attach as context**：将文件添加到您的下一个提示词

245* **Open in**：在已安装的编辑器（如 VS Code、Cursor 或 Zed）中打开文件256* **Open in**：在已安装的编辑器（如 VS Code、Cursor 或 Zed）中打开文件

246* **Show in Finder**（macOS）、**Show in Explorer**（Windows）：打开包含文件夹257* **Show in Finder**（macOS）、**Show in Explorer**（Windows）：打开包含文件夹

247* **Copy path**：将绝对路径复制到你的剪贴板258* **Copy path**：将绝对路径复制到您的剪贴板

248 259

249<h3 id="switch-view-modes">260<h3 id="switch-view-modes">

250 切换视图模式261 切换视图模式

254 265

255| 模式 | 显示内容 |266| 模式 | 显示内容 |

256| - | - |267| - | - |

257| **Normal** | 工具调用折叠成摘要，带有完整文本响应 |268| **Normal** | 工具调用折叠成摘要，带有完整文本回复 |

258| **Thinking** | 工具调用折叠成摘要，加上 Claude 的思考 |269| **Thinking** | 工具调用折叠成摘要，加上 Claude 的思考 |

259| **Verbose** | Claude 采取的每个工具调用、文件读取和中间步骤，加上 Claude 的思考 |270| **Verbose** | Claude 采取的每个工具调用、文件读取和中间步骤，加上 Claude 的思考 |

260 271

261使用 Thinking 来跟踪 Claude 的推理，工具调用仍然折叠。在调试 Claude 为什么采取特定操作时使用 Verbose。Claude Desktop 1.46388.1 之前的版本也列出了 Summary 模式，仍然设置为 Summary 的会话在你更新后会以 Normal 打开。272使用 Thinking 来跟踪 Claude 的推理，工具调用仍然折叠。在调试 Claude 为什么采取特定操作时使用 Verbose。Claude Desktop 1.46388.1 之前的版本也列出了 Summary 模式，仍然设置为 Summary 的会话在您更新后会以 Normal 打开。

262 273

263<h3 id="keyboard-shortcuts">274<h3 id="keyboard-shortcuts">

264 快捷键275 快捷键

276| `Esc` | 停止 Claude 的响应 |287| `Esc` | 停止 Claude 的回复 |

288| `Tab` / `Right arrow` | 在空输入框中[接受建议的提示词](#accept-a-suggested-prompt) |

287| `1`–`9` | 在打开的菜单中选择项目 |299| `1`–`9` | 在打开的菜单中选择项目 |

288 300

289这些快捷键仅适用于 Code 选项卡。基于终端的[交互模式快捷键](/docs/zh-CN/interactive-mode#keyboard-shortcuts)（如 `Shift+Tab` 来循环权限模式）在 Desktop 中不适用。301这些快捷键适用于 Code 选项卡。在 Desktop 中，`Shift+Tab` 不会像在终端的[交互模式](/docs/zh-CN/interactive-mode#keyboard-shortcuts)中那样循环切换权限模式。

290 302

291<h3 id="check-usage">303<h3 id="check-usage">

292 检查使用情况304 检查使用情况

293</h3>305</h3>

294 306

295点击模型选择器旁的使用环形图来查看你当前的上下文窗口使用情况和你的计划在该期间的使用情况。上下文使用是按会话的；计划使用在所有 Claude Code 表面上共享。307点击模型选择器旁的使用环形图来查看您当前的上下文窗口使用情况和您的计划在该期间的使用情况。上下文使用是按会话的；计划使用在所有 Claude Code 使用入口上共享。

296 308

297<h2 id="let-claude-use-your-computer">309<h2 id="let-claude-use-your-computer">

298 让 Claude 使用你的计算机310 让 Claude 使用你的计算机

458* 选择 **Cloud** 可将会话作为[云端会话](/docs/zh-CN/claude-code-on-the-web)继续，您的对话会以摘要形式带过去。在您确认之前，对话框会说明您的文件是否也会一并移动，以及云端会话就绪后此会话是否会被存档。通过 [SSH](#ssh-sessions) 或在 [WSL](/docs/zh-CN/desktop-wsl) 中运行的会话无法以这种方式移动。470* 选择 **Cloud** 可将会话作为[云端会话](/docs/zh-CN/claude-code-on-the-web)继续，您的对话会以摘要形式带过去。在您确认之前，对话框会说明您的文件是否也会一并移动，以及云端会话就绪后此会话是否会被存档。通过 [SSH](#ssh-sessions) 或在 [WSL](/docs/zh-CN/desktop-wsl) 中运行的会话无法以这种方式移动。

459* 选择已安装的编辑器或文件管理器，可在其中打开该会话在磁盘上的文件夹。471* 选择已安装的编辑器或文件管理器，可在其中打开该会话在磁盘上的文件夹。

460 472

473<h3 id="control-which-sessions-appear-on-your-other-devices">

474 控制哪些会话显示在您的其他设备上

475</h3>

476

477本地会话在 [Remote Control](/docs/zh-CN/remote-control) 将其连接后，会显示在您的其他设备上。已连接的会话会出现在 [claude.ai/code](https://claude.ai/code) 的会话列表中，以及登录了您 claude.ai 账户的设备上的 Claude 应用中。

478

479本地会话会在您为其打开 Remote Control 时连接，或在启动时自动连接：

480

481* **您为该会话打开它**：使用该会话的 **Remote Control** 开关，或在其输入框中输入 `/remote-control`。

482* **在启动时连接**：当 **Settings > Claude Code** 中的 **Connect new sessions to Remote Control** 处于打开状态时，新会话会自动连接。如果您从未更改过该设置，Desktop 会遵循您的用户设置或托管设置中的 [`remoteControlAtStartup`](/docs/zh-CN/settings-reference#remotecontrolatstartup)，其次是您组织的默认值。

483

484要查看会话是否已连接，请查看工具栏中会话标题前的笔记本电脑图标。会话已连接或正在连接时，该图标会高亮显示。点击它可打开该会话的 **Remote Control** 开关。

485

486要让会话不出现在您的其他设备上，请在所需的级别关闭 Remote Control：

487

488* **单个会话**：关闭其 **Remote Control** 开关。在启动时已自动连接的会话中，输入 `/remote-control` 会保持 Remote Control 打开，并显示 `Remote Control is already on. This session connected automatically when it started.`。点击该行上的 **Turn off** 即可断开连接。

489* **此计算机上的新 Desktop 会话**：在 **Settings > Claude Code** 中关闭 **Connect new sessions to Remote Control**。如果它已显示为关闭，请先将其打开再关闭，以便 Desktop 保存您的选择。保存后，它优先于 `remoteControlAtStartup` 和默认值。

490* **此计算机上的任何会话，包括 CLI**：在 `~/.claude/settings.json` 中将 [`disableRemoteControl`](/docs/zh-CN/settings-reference#disableremotecontrol) 设置为 `true`，以阻止会话连接。保存该文件时已连接的会话会保持连接，直到您为其关闭 Remote Control。

491

492要隐藏已显示在您其他设备上的会话，请在 Desktop 中将其存档。Desktop 也会存档该会话的 Remote Control 副本，使其从这些设备上的默认会话列表中移除。要在那里查看或删除它，请参阅[存档会话](/docs/zh-CN/claude-code-on-the-web#archive-sessions)。

493

461<h3 id="sessions-from-dispatch">494<h3 id="sessions-from-dispatch">

462 来自 Dispatch 的会话495 来自 Dispatch 的会话

463</h3>496</h3>

836 为你的团队预配置 SSH 连接869 为你的团队预配置 SSH 连接

837</h4>870</h4>

838 871

839管理员可以通过将 `sshConfigs` 添加到[托管设置](/docs/zh-CN/managed-settings)文件来向团队成员分发 SSH 连接。以这种方式定义的连接会自动出现在每个用户的环境下拉菜单中，并显示为托管的，因此用户可以选择它们，但不能在应用中编辑或删除它们。872管理员可以通过在[托管设置](/docs/zh-CN/managed-settings)中设置 `sshConfigs` 来向团队成员分发 SSH 连接。以这种方式定义的连接会自动出现在每个用户的环境下拉菜单中，并显示为托管的，因此用户可以选择它们，但不能在应用中编辑或删除它们。

840 873

841以下示例预配置了一个单个连接：874以下示例预配置了一个单个连接：

842 875

860 限制用户可以连接的 SSH 主机893 限制用户可以连接的 SSH 主机

861</h4>894</h4>

862 895

863管理员可以通过将 `sshHostAllowlist` 添加到[托管设置](/docs/zh-CN/managed-settings)文件来限制 Desktop 的 SSH 会话到一组已批准的主机。设置后，用户只能连接到其解析的主机名与其中一个模式匹配的主机。将其设置为空数组以完全禁用 SSH 会话。896管理员可以通过在[托管设置](/docs/zh-CN/managed-settings)中设置 `sshHostAllowlist` 来将 Desktop 的 SSH 会话限制为一组已批准的主机。设置后，用户只能连接到其解析的主机名与其中一个模式匹配的主机。将其设置为空数组可禁用 SSH 会话。[`sshHostAllowlist` 参考条目](/docs/zh-CN/settings-reference#sshhostallowlist)说明了空数组如何与其他托管来源中的列表组合。

864 897

865以下示例允许连接到 `devboxes.example.com` 下的任何主机以及单个命名的堡垒主机：898以下示例允许连接到 `devboxes.example.com` 下的任何主机以及单个命名的堡垒主机：

866 899

870}903}

871```904```

872 905

906<Warning>

907 如果您的组织提供[服务器托管设置](/docs/zh-CN/server-managed-settings)，请在那里设置 `sshHostAllowlist`。默认情况下，Desktop 仅从[提供策略键的最高优先级托管来源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)读取该键。如果该来源未设置该键，Desktop 会忽略较低优先级的 MDM 策略或托管设置文件中的列表，并将该键视为[未设置](/docs/zh-CN/settings-reference#sshhostallowlist)。Desktop 不会显示任何警告。

908

909 同时，请在每个用户的机器上保留相同的列表，放在该机器上最高优先级的 MDM 策略或托管设置文件中。Desktop 在启动时获取服务器托管设置，并且不保留缓存副本，因此在获取成功之前，适用的是该机器上的列表。

910</Warning>

911

873模式不区分大小写。`*` 匹配任何主机，`*.example.com` 匹配 `example.com` 和任何子域。其他任何内容都是精确匹配。检查针对通过 `ssh -G` 进行 `~/.ssh/config` 解析后的主机名运行，因此允许 `Host` 别名和 `ProxyCommand`/`ProxyJump` 条目，只要解析的 `HostName` 匹配。912模式不区分大小写。`*` 匹配任何主机，`*.example.com` 匹配 `example.com` 和任何子域。其他任何内容都是精确匹配。检查针对通过 `ssh -G` 进行 `~/.ssh/config` 解析后的主机名运行，因此允许 `Host` 别名和 `ProxyCommand`/`ProxyJump` 条目，只要解析的 `HostName` 匹配。

874 913

875`sshHostAllowlist` 仅从托管设置中读取；用户或项目设置中的值被忽略。只有 Claude Desktop 应用遵守此设置；Claude Code CLI 和 IDE 扩展不读取它，它也不限制通过 Bash 工具运行的 `ssh` 命令。它管理 Desktop 应用连接到的主机，而不是网络出口，因此如果你需要硬边界，请将其与你的组织的网络或零信任控制配对。914`sshHostAllowlist` 仅从托管设置中读取；用户或项目设置中的值被忽略。只有 Claude Desktop 应用遵守此设置；Claude Code CLI 和 IDE 扩展不读取它，它也不限制通过 Bash 工具运行的 `ssh` 命令。它管理 Desktop 应用连接到的主机，而不是网络出口，因此如果你需要硬边界，请将其与你的组织的网络或零信任控制配对。

895<Note>934<Note>

896 Cowork 下的 OpenTelemetry 表单位于管理员控制台的[数据和隐私设置](https://claude.ai/admin-settings/data-privacy-controls)中的**监控**下，仅适用于 Cowork 会话。在此机器上的 Cowork 会话中，桌面应用将该收集器作为 `OTEL_*` 环境变量传递给 Claude Code，因此该表单生效，尽管该会话中的 Claude Code [从不获取管理员控制台设置](#managed-settings)。935 Cowork 下的 OpenTelemetry 表单位于管理员控制台的[数据和隐私设置](https://claude.ai/admin-settings/data-privacy-controls)中的**监控**下，仅适用于 Cowork 会话。在此机器上的 Cowork 会话中，桌面应用将该收集器作为 `OTEL_*` 环境变量传递给 Claude Code，因此该表单生效，尽管该会话中的 Claude Code [从不获取管理员控制台设置](#managed-settings)。

897 936

898 要从 Code 选项卡会话导出遥测，请在 Claude Code 托管设置的 `env` 块中设置 `CLAUDE_CODE_ENABLE_TELEMETRY` 和 `OTEL_*` 变量，如[监控的管理员配置](/docs/zh-CN/monitoring-usage#administrator-configuration)中所示。本地、云端和 SSH 会话各自从不同来源读取[托管设置](#managed-settings)。有关云端会话可以到达的主机，请参阅[网络访问](/docs/zh-CN/cloud-environments#network-access)。有关 Code 选项卡会话报告的 `service.name`，请参阅[服务信息](/docs/zh-CN/monitoring-usage#service-information)。937 要从 Code 选项卡会话导出遥测，请在 Claude Code 托管设置的 `env` 块中设置 `CLAUDE_CODE_ENABLE_TELEMETRY` 和 `OTEL_*` 变量，如[监控的管理员配置](/docs/zh-CN/monitoring-usage#administrator-configuration)中所示。本地、云端和 SSH 会话各自[从不同来源读取托管设置](#managed-settings)。有关云端会话可以到达的主机，请参阅[网络访问](/docs/zh-CN/cloud-environments#network-access)。有关 Code 选项卡会话报告的 `service.name`，请参阅[服务信息](/docs/zh-CN/monitoring-usage#service-information)。

899</Note>938</Note>

900 939

901<h3 id="managed-settings">940<h3 id="managed-settings">

913| `disableMobileSimulatorTools` | 设置为 `true` 以阻止 Claude 在 [iOS Simulator 窗格](/docs/zh-CN/desktop-ios-simulator#turn-off-simulator-access)中控制和捕获设备的工具。该窗格仍可用于用户自己的点击；仅删除 Claude 的访问权限。该值必须是 JSON 布尔值 `true`；字符串 `"true"` 被忽略。 |952| `disableMobileSimulatorTools` | 设置为 `true` 以阻止 Claude 在 [iOS Simulator 窗格](/docs/zh-CN/desktop-ios-simulator#turn-off-simulator-access)中控制和捕获设备的工具。该窗格仍可用于用户自己的点击；仅删除 Claude 的访问权限。该值必须是 JSON 布尔值 `true`；字符串 `"true"` 被忽略。 |

914| `disableBrowserExternalNavigation` | 设置为 `true` 以完全关闭[浏览器窗格](#browse-external-sites)中的外部浏览。用户和 Claude 都无法导航到外部网站，localhost 开发服务器预览不受影响。该值必须是 JSON 布尔值 `true`；字符串 `"true"` 被忽略。 |953| `disableBrowserExternalNavigation` | 设置为 `true` 以完全关闭[浏览器窗格](#browse-external-sites)中的外部浏览。用户和 Claude 都无法导航到外部网站，localhost 开发服务器预览不受影响。该值必须是 JSON 布尔值 `true`；字符串 `"true"` 被忽略。 |

917| `disableDesktopLocalSessions` | 设置为 `true` 以关闭[在设备上运行的 Code 会话](#local-sessions-on-managed-devices)，仅保留到其他主机的 SSH 会话和云端会话可用。该值必须是 JSON 布尔值 `true`。仅从托管设置中读取。需要 Claude Desktop v1.37937.0 或更高版本。 |956| `disableDesktopLocalSessions` | 设置为 `true` 以关闭[在设备上运行的 Code 会话](#local-sessions-on-managed-devices)，仅保留到其他主机的 SSH 会话和云端会话可用。该值必须是 JSON 布尔值 `true`。仅从托管设置中读取。需要 Claude Desktop v1.37937.0 或更高版本。 |

918| `disableSshSavedPasswords` | 设置为 `true` 以阻止 Desktop 提供记住 SSH 密码的选项，并阻止其使用或显示之前保存的密码。启用此设置不会删除这些密码。仅从托管设置中读取。需要 Claude Desktop v1.49585.0 或更高版本。 |957| `disableSshSavedPasswords` | 设置为 `true` 以阻止 Desktop 提供记住 SSH 密码的选项，并阻止其使用或显示之前保存的密码。启用此设置不会删除这些密码。仅从托管设置中读取。需要 Claude Desktop v1.49585.0 或更高版本。 |

919| `managedMcpServers` | 将 MCP 服务器配置推送到所有用户。仅在第三方 (3P) Desktop 部署中可用。在每个条目中，设置 `"http"`、`"sse"` 或 `"stdio"` 的传输、连接详细信息，以及可选的 `toolPolicy` 映射，该映射限制该服务器中用户可以调用的工具。通过托管设置文件、MDM 或 Claude apps gateway 策略的 [`desktop` 块](/docs/zh-CN/claude-apps-gateway-config#claude-desktop-overlay)提供它，因为 3P 部署不接收管理员控制台设置。要通过网关提供它，您需要网关服务器上的 Claude Code v2.1.232 或更高版本。这是桌面应用自己的键；Claude Code 读取自己的[同名托管设置](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings)，具有不同的条目形状。 |958| `managedMcpServers` | 将 MCP 服务器配置推送到所有用户。仅在第三方 (3P) Desktop 部署中可用。在每个条目中，设置 `"http"`、`"sse"` 或 `"stdio"` 的传输、连接详细信息，以及可选的 `toolPolicy` 映射，该映射限制该服务器中用户可以调用的工具。通过托管设置文件、MDM 或 Claude apps gateway 策略的 [`desktop` 块](/docs/zh-CN/claude-apps-gateway-config#claude-desktop-overlay)提供它，因为 3P 部署不接收管理员控制台设置。要通过网关提供它，您需要网关服务器上的 Claude Code v2.1.232 或更高版本。这是桌面应用自己的键；Claude Code 读取自己的[同名托管设置](/docs/zh-CN/managed-mcp#provide-servers-through-managed-settings)，具有不同的条目形状。 |

920 959

921哪些托管设置到达 Desktop 会话取决于该会话运行的位置。模型限制（如 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection)）在 Desktop 的 Claude Code 会话中的执行方式与在终端 CLI 中相同；请参阅[使用入口覆盖范围](/docs/zh-CN/model-config#surface-coverage)。960哪些托管设置到达 Desktop 会话取决于该会话运行的位置。模型限制（如 [`availableModels`](/docs/zh-CN/model-config#restrict-model-selection)）在 Desktop 的 Claude Code 会话中的执行方式与在终端 CLI 中相同；请参阅[使用入口覆盖范围](/docs/zh-CN/model-config#surface-coverage)。

922 961

923* **此机器上的本地会话**：部署到磁盘的托管设置文件适用。通过管理员控制台远程推送的托管设置也在会话使用[符合条件的登录或密钥](/docs/zh-CN/server-managed-settings#platform-availability)向 Anthropic 的 API 进行身份验证时到达这些会话，遵循与终端 CLI 相同的[设置优先级](/docs/zh-CN/settings#settings-precedence)。962* **此机器上的本地会话**：部署到磁盘的托管设置文件适用。通过管理员控制台远程推送的托管设置也在会话使用[符合条件的登录](/docs/zh-CN/server-managed-settings#platform-availability)向 Anthropic 的 API 进行身份验证时到达这些会话，遵循与终端 CLI 相同的[设置优先级](/docs/zh-CN/settings#settings-precedence)。

924* **[云端会话](#cloud-sessions)**：接收[服务器管理的设置](/docs/zh-CN/server-managed-settings)；设备部署的文件无法到达它们，因为它们在 Anthropic 管理的虚拟机上运行。路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话也读取运行程序镜像中的托管设置文件。[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明该文件何时适用。963* **[云端会话](#cloud-sessions)**：接收[服务器管理的设置](/docs/zh-CN/server-managed-settings)；设备部署的文件无法到达它们，因为它们在 Anthropic 管理的虚拟机上运行。路由到[自托管环境](/docs/zh-CN/self-hosted-environments)的会话也读取运行程序镜像中的托管设置文件。[Claude Code 如何组合托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)说明该文件何时适用。

925* **[SSH 会话](#ssh-sessions)**：会话从远程主机读取托管设置文件。Desktop 本身从本地机器的托管设置中读取 `sshConfigs`、`sshHostAllowlist`、`disableSshSavedPasswords` 和 `disableDesktopLocalSessions`。964* **[SSH 会话](#ssh-sessions)**：会话从远程主机读取托管设置文件。Desktop 本身在本地机器上读取 `sshConfigs`、`sshHostAllowlist`、`disableSshSavedPasswords` 和 `disableDesktopLocalSessions`。如果您提供多个托管源，它[默认只从其中一个](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)读取。

926* **[Cowork](https://claude.com/docs/cowork/overview) 会话**：在此机器上的 Cowork 会话中，Claude Code 永远不会获取管理员控制台设置，即使用户使用 Team 或 Enterprise 帐户登录，并读取部署到机器的策略，除非您的 Claude Desktop 配置设置了 `requireCoworkFullVmSandbox`。远程 Cowork 会话两者都不接收。请参阅[策略应用的位置和时间](/docs/zh-CN/managed-settings#where-and-when-a-policy-applies)了解哪些设备文件到达 Cowork，以及[MCP 权限规则](/docs/zh-CN/permissions#mcp)了解 `Bash` 和 `WebFetch` 规则如何应用于 Cowork 的工具。965* **[Cowork](https://claude.com/docs/cowork/overview) 会话**：在此机器上的 Cowork 会话中，Claude Code 永远不会获取管理员控制台设置，即使用户使用 Team 或 Enterprise 帐户登录，并读取部署到机器的策略，除非您的 Claude Desktop 配置设置了 `requireCoworkFullVmSandbox`。远程 Cowork 会话两者都不接收。请参阅[策略应用的位置和时间](/docs/zh-CN/managed-settings#where-and-when-a-policy-applies)了解哪些设备文件到达 Cowork，以及[MCP 权限规则](/docs/zh-CN/permissions#mcp)了解 `Bash` 和 `WebFetch` 规则如何应用于 Cowork 的工具。

927 966

928在本地和 SSH 会话中，桌面应用直接将每个用户连接的 claude.ai 连接器传递给 Claude Code。无论您使用哪个设置源或文件位置，都没有 MCP 设置或 `managed-mcp.json` 到达这些连接器。要在这些会话中阻止连接器的工具，请使用您的组织的[连接器工具控制](/docs/zh-CN/mcp#organization-controls-on-connector-tools)。[连接器如何到达 Claude Code](/docs/zh-CN/mcp#how-connectors-reach-claude-code)显示在每种会话中哪些设置管理连接器。967在本地和 SSH 会话中，桌面应用直接将每个用户连接的 claude.ai 连接器传递给 Claude Code。无论您使用哪个设置源或文件位置，都没有 MCP 设置或 `managed-mcp.json` 到达这些连接器。要在这些会话中阻止连接器的工具，请使用您的组织的[连接器工具控制](/docs/zh-CN/mcp#organization-controls-on-connector-tools)。[连接器如何到达 Claude Code](/docs/zh-CN/mcp#how-connectors-reach-claude-code)显示在每种会话中哪些设置管理连接器。

975assets-proxy.anthropic.com1014assets-proxy.anthropic.com

976claude.ai1015claude.ai

977a.claude.ai1016a.claude.ai

978a-cdn.claude.ai

979assets.claude.ai1017assets.claude.ai

980downloads.claude.ai1018downloads.claude.ai

981*.livepreview.claude.ai1019*.livepreview.claude.ai

1023 来自 CLI？1061 来自 CLI？

1024</h2>1062</h2>

1025 1063

1026如果你已经使用 Claude Code CLI，Desktop 运行相同的底层引擎，具有图形界面。你可以在同一机器上同时运行两者，甚至在同一项目上。每个维护单独的会话列表，你可以将 CLI 会话带入 Desktop。它们通过 CLAUDE.md 文件共享配置和项目内存。1064如果您已经使用 Claude Code CLI，Desktop 运行相同的底层引擎，具有图形界面。您可以在同一机器上同时运行两者，甚至在同一项目上。每个维护单独的会话列表，您可以将 CLI 会话带入 Desktop。它们通过 CLAUDE.md 文件共享配置和项目记忆。

1027 1065

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

1029 1067

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

1031 1069

1032```bash theme={null}1070```bash theme={null}

1033claude --desktop --resume <session-id>1071claude --desktop --resume <session-id>

1035 1073

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

1037 1075

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

1039 1077

1040要在 Desktop 中继续终端会话：1078要在 Desktop 中继续终端会话：

1041 1079

10421. 在终端中关闭会话。10801. 在终端中关闭会话。

10432. 在 Desktop 提示框中，输入 `/resume`。Desktop 列出你从 CLI 在此计算机上启动的会话。按标题、文件夹或分支搜索，并预览每个会话的停止位置。10812. 在 Desktop 输入框中，输入 `/resume`。Desktop 列出您从 CLI 在此计算机上启动的会话。按标题、文件夹或分支搜索，并预览每个会话的停止位置。

10443. 选择会话。它在应用中继续，具有完整的对话和上下文。10823. 选择会话。它在应用中继续，具有完整的对话和上下文。

1045 1083

1046Desktop 继续相同的会话而不是副本，所以之后在终端中 `claude --resume` 仍然可以找到它。1084Desktop 继续相同的会话而不是副本，所以之后在终端中 `claude --resume` 仍然可以找到它。

1047 1085

1048<Tip>1086<Tip>

1049 何时使用 Desktop vs CLI：当你想要管理一个窗口中的并行会话、并排排列窗格或可视化审查更改时，使用 Desktop。当你需要脚本、自动化或更喜欢终端工作流时，使用 CLI。1087 何时使用 Desktop vs CLI：当您想要在一个窗口中管理并行会话、并排排列窗格或可视化审查更改时，使用 Desktop。当您需要脚本、自动化或更喜欢终端工作流时，使用 CLI。

1050</Tip>1088</Tip>

1051 1089

1052<h3 id="cli-flag-equivalents">1090<h3 id="cli-flag-equivalents">

1058| CLI | Desktop 等效项 |1096| CLI | Desktop 等效项 |

1059| - | - |1097| - | - |

1063| `--dangerously-skip-permissions` | 绕过权限模式。在 Pro 和 Max 计划上，在设置 → Claude Code → "允许绕过权限模式"中启用它；在 Team 和 Enterprise 计划上，组织策略控制它 |1101| `--dangerously-skip-permissions` | 绕过权限模式。在 Pro 和 Max 套餐上，在设置 → Claude Code → "允许绕过权限模式"中启用它；在 Team 和 Enterprise 套餐上，由组织策略控制 |

1072 共享配置1110 共享配置

1073</h3>1111</h3>

1074 1112

1075Desktop 和 CLI 读取相同的配置文件，因此你的设置会转移：1113Desktop 和 CLI 读取相同的配置文件，因此您的设置会沿用：

1076 1114

1077* **[CLAUDE.md](/docs/zh-CN/memory)** 和 `CLAUDE.local.md` 文件在你的项目中被两者使用1115* 项目中的 **[CLAUDE.md](/docs/zh-CN/memory)** 和 `CLAUDE.local.md` 文件由两者共同使用

1078* **[MCP servers](/docs/zh-CN/mcp)** 在 `~/.claude.json` 或 `.mcp.json` 中配置在两者中工作1116* 在 `~/.claude.json` 或 `.mcp.json` 中配置的 **[MCP 服务器](/docs/zh-CN/mcp)** 在两者中均可使用

1079* **[Hooks](/docs/zh-CN/hooks)** 和 **[skills](/docs/zh-CN/skills)** 在设置中定义适用于两者1117* 在设置中定义的 **[hook](/docs/zh-CN/hooks)** 和 **[skill](/docs/zh-CN/skills)** 适用于两者

1080* **[Settings](/docs/zh-CN/settings)** 在 `~/.claude.json` 和 `~/.claude/settings.json` 中是共享的。权限规则、允许的工具和 `settings.json` 中的其他设置适用于 Desktop 会话。1118* `~/.claude.json` 和 `~/.claude/settings.json` 中的 **[设置](/docs/zh-CN/settings)** 是共享的。权限规则、允许的工具和 `settings.json` 中的其他设置适用于 Desktop 会话。

1081* **Models**：相同的[模型](/docs/zh-CN/model-config#available-models)在两者中都可用。在 Desktop 中，从发送按钮旁的下拉菜单中选择模型。你可以在会话期间从相同的下拉菜单更改模型。1119* **模型**：相同的[模型](/docs/zh-CN/model-config#available-models)在两者中都可用。在 Desktop 中，从发送按钮旁的下拉菜单中选择模型。您可以在会话期间从相同的下拉菜单更改模型。

1082 1120

1083<h4 id="mcp-servers-from-the-claude-desktop-chat-app">1121<h4 id="mcp-servers-from-the-claude-desktop-chat-app">

1084 来自 Claude Desktop 聊天应用的 MCP servers1122 来自 Claude Desktop 聊天应用的 MCP 服务器

1085</h4>1123</h4>

1086 1124

1087Desktop 应用从 `claude_desktop_config.json` 将 MCP servers 加载到本地 Code 选项卡会话中，以及来自 `~/.claude.json` 和 `.mcp.json` 的服务器。在 `claude_desktop_config.json` 中定义的服务器在 Desktop 聊天表面和本地 Code 选项卡会话中都可用。1125Desktop 应用会将 `claude_desktop_config.json` 中的 MCP 服务器加载到本地 Code 选项卡会话中，与来自 `~/.claude.json` 和 `.mcp.json` 的服务器一起使用。在 `claude_desktop_config.json` 中定义的服务器在 Desktop 聊天使用入口和本地 Code 选项卡会话中都可用。

1088 1126

1089如果你在 `claude_desktop_config.json` 和 `~/.claude.json` 或 `.mcp.json` 中定义相同的服务器名称，本地会话中的 Code 选项卡连接一次并使用 `claude_desktop_config.json` 定义。1127如果您在 `claude_desktop_config.json` 和 `~/.claude.json` 或 `.mcp.json` 中定义相同的服务器名称，本地会话中的 Code 选项卡只连接一次并使用 `claude_desktop_config.json` 中的定义。

1090 1128

1091该应用还将来自 `~/.claude.json` 的 stdio 服务器重新传递到本地会话中的嵌入式 CLI。当 `~/.claude.json`（用户范围）和 `.mcp.json` 的顶级定义相同的 stdio 服务器名称时，Code 选项卡使用 `~/.claude.json` 定义，偏离 CLI [范围层次结构](/docs/zh-CN/mcp#scope-hierarchy-and-precedence)。1129该应用还将来自 `~/.claude.json` 的 stdio 服务器重新传递到本地会话中的嵌入式 CLI。当 `~/.claude.json` 的顶层（用户作用域）和 `.mcp.json` 定义相同的 stdio 服务器名称时，Code 选项卡使用 `~/.claude.json` 中的定义，这与 CLI 的[作用域层次结构](/docs/zh-CN/mcp#scope-hierarchy-and-precedence)不同。

1092 1130

1093<Note>1131<Note>

1094 独立 CLI 不读取 `claude_desktop_config.json`。在 macOS 和 WSL 上，运行 `claude mcp add-from-claude-desktop` 将这些服务器复制到 `~/.claude.json`。请参阅[从 Claude Desktop 导入 MCP servers](/docs/zh-CN/mcp#import-mcp-servers-from-claude-desktop)了解导入流程和范围选项。1132 独立 CLI 不读取 `claude_desktop_config.json`。在 macOS 和 WSL 上，运行 `claude mcp add-from-claude-desktop` 将这些服务器复制到 `~/.claude.json`。请参阅[从 Claude Desktop 导入 MCP 服务器](/docs/zh-CN/mcp#import-mcp-servers-from-claude-desktop)了解导入流程和作用域选项。

1095</Note>1133</Note>

1096 1134

1097<h3 id="feature-comparison">1135<h3 id="feature-comparison">

1102 1140

1103| 功能 | CLI | Desktop |1141| 功能 | CLI | Desktop |

1104| - | - | - |1142| - | - | - |

1106| [第三方提供商](/docs/zh-CN/third-party-integrations) | Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry | Anthropic 的 API 默认。对于网关路由，请参阅[将桌面应用连接到网关](/docs/zh-CN/llm-gateway-connect#desktop-app)。要在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自托管 LLM 网关上运行 Code 选项卡，请参阅 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)。 |1144| [第三方提供商](/docs/zh-CN/third-party-integrations) | Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry | 默认使用 Anthropic 的 API。对于网关路由，请参阅[将桌面应用连接到网关](/docs/zh-CN/llm-gateway-connect#desktop-app)。要在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自托管 LLM 网关上运行 Code 选项卡，请参阅 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)。 |

1110| 文件附件 | 不可用 | 图像、PDF |1148| 文件附件 | 不可用 | 图像、PDF |

1116| Dispatch 集成 | 不可用 | [Dispatch 会话](#sessions-from-dispatch)在侧边栏中 |1154| Dispatch 集成 | 不可用 | 侧边栏中的 [Dispatch 会话](#sessions-from-dispatch) |

1117| 脚本和自动化 | [`--print`](/docs/zh-CN/cli-reference)、[Agent SDK](/docs/zh-CN/headless) | 不可用 |1155| 脚本和自动化 | [`--print`](/docs/zh-CN/cli-reference)、[Agent SDK](/docs/zh-CN/headless) | 不可用 |

1118 1156

1119<h3 id="what’s-not-available-in-desktop">1157<h3 id="what’s-not-available-in-desktop">

1124 1162

1125* **第三方提供商**：Desktop 默认连接到 Anthropic 的 API。要通过网关路由 Desktop，或在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自托管 LLM 网关上运行 Code 选项卡，请按照[第三方提供商行](#feature-comparison)中的链接操作。1163* **第三方提供商**：Desktop 默认连接到 Anthropic 的 API。要通过网关路由 Desktop，或在 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 或自托管 LLM 网关上运行 Code 选项卡，请按照[第三方提供商行](#feature-comparison)中的链接操作。

1126* **Linux (beta)**：Linux 桌面应用中尚不提供计算机使用。请参阅 [Claude Desktop on Linux](/docs/zh-CN/desktop-linux)。1164* **Linux (beta)**：Linux 桌面应用中尚不提供计算机使用。请参阅 [Claude Desktop on Linux](/docs/zh-CN/desktop-linux)。

1127* **内联代码建议**：Desktop 不提供自动完成风格的建议。它通过对话提示和显式代码更改工作。1165* **内联代码建议**：Desktop 不提供自动完成风格的代码补全。它通过对话式提示词和显式代码更改工作，并可以在 Claude 回复后[建议您的下一个提示词](#accept-a-suggested-prompt)。

1128* **Agent teams**：协调的团队，其中 Claude 作为团队负责人从共享任务列表中为队友分配任务，在 [CLI](/docs/zh-CN/agent-teams) 中可用，不在 Desktop 中。对于一个会话内的多 agent 工作，使用[动态工作流](/docs/zh-CN/workflows)，它在 Desktop 中运行；Claude 也可以[直接消息和管理你的其他会话](#work-across-sessions)。1166* **Agent team**：协调的团队（由 Claude 作为团队负责人从共享任务列表中为队友分配任务）在 [CLI](/docs/zh-CN/agent-teams) 中可用，不在 Desktop 中。对于一个会话内的多 Agent 工作，请使用[动态工作流](/docs/zh-CN/workflows)，它可在 Desktop 中运行；Claude 也可以直接[向您的其他会话发送消息并管理它们](#work-across-sessions)。

1129* **Terminal-dialog 命令**：在终端中打开交互式面板的内置命令，其行为在 Code 选项卡中有所不同。直接编辑[设置文件](/docs/zh-CN/settings)来管理权限规则和配置，或从独立 CLI 运行命令。1167* **Terminal-dialog 命令**：在终端中打开交互式面板的内置命令，其行为在 Code 选项卡中有所不同。直接编辑[设置文件](/docs/zh-CN/settings)来管理权限规则和配置，或从独立 CLI 运行命令。

1130 * 没有参数形式的命令，例如 `/permissions`，回复 `isn't available in this environment`。1168 * 没有参数形式的命令，例如 `/permissions`，会回复 `isn't available in this environment`。

1131 * `/config` 打开设置 → Claude Code。命令后的文本被忽略，所以 `/config theme=dark` 不设置主题。1169 * `/config` 打开设置 → Claude Code。命令后的文本会被忽略，所以 `/config theme=dark` 不会设置主题。

1132 1170

1133<h2 id="troubleshooting">1171<h2 id="troubleshooting">

1134 故障排除1172 故障排除

1147 1185

1148点击版本号将其复制到你的剪贴板。1186点击版本号将其复制到你的剪贴板。

1149 1187

1188<h4 id="claude-code-version-in-the-code-tab">

1189 Code 选项卡中的 Claude Code 版本

1190</h4>

1191

1192要查看会话运行的 Claude Code 版本，请在 **Code** 选项卡的本地会话中输入 `/status`，然后查看 **Claude Code** 行，其中会显示版本号，例如 `2.1.286`。

1193

1194要为本地会话获取更新的版本，请在 macOS 上打开 **Claude → Check for Updates**，或在 Windows 上打开 **Help → Check for Updates**，然后启动新会话。

1195

1196在本地会话中，**Code** 选项卡运行其自己的 Claude Code 副本，该副本有自己的版本号。桌面应用会下载并更新该副本，因此它可能与终端中的 `claude` 命令版本不同，并且更新其中一个不会更新另一个。

1197

1150<h3 id="403-or-authentication-errors-in-the-code-tab">1198<h3 id="403-or-authentication-errors-in-the-code-tab">

1151 Code 选项卡中的 403 或身份验证错误1199 Code 选项卡中的 403 或身份验证错误

1152</h3>1200</h3>

desktop-quickstart.md +5 −5

Details

45 45

46<Steps>46<Steps>

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

48 在 macOS 和 Windows 上，从上面的链接下载安装程序并运行它。在 Linux 上，请按照 [Claude Desktop on Linux](/docs/zh-CN/desktop-linux) 中的安装步骤进行操作。在 macOS 上从应用程序文件夹启动 Claude，在 Windows 上从开始菜单启动，或在 Linux 上从应用程序启动器启动，然后使用您的 Anthropic 账户登录。48 在 macOS 和 Windows 上，从上面的链接下载安装程序并运行它。在 Linux 上，请按照 [Linux 上的 Claude Desktop](/docs/zh-CN/desktop-linux) 中的安装步骤进行操作。在 macOS 上从应用程序文件夹启动 Claude，在 Windows 上从开始菜单启动，或在 Linux 上从应用程序启动器启动，然后使用您的 Anthropic 账户登录。

49 </Step>49 </Step>

50 50

51 <Step title="打开 Code 选项卡">51 <Step title="打开 Code 选项卡">

118 118

119**在提交前审查更改。** Claude 编辑文件后，会出现 `+12 -1` 指示符。点击它以打开 [diff 视图](/docs/zh-CN/desktop#review-changes-with-diff-view)，逐个文件审查修改，并对特定行进行评论。Claude 会读取您的评论并进行修订。要让 Claude 自行审查这些更改，请在提示框中输入 [`/code-review`](/docs/zh-CN/desktop#review-your-code)。119**在提交前审查更改。** Claude 编辑文件后，会出现 `+12 -1` 指示符。点击它以打开 [diff 视图](/docs/zh-CN/desktop#review-changes-with-diff-view)，逐个文件审查修改，并对特定行进行评论。Claude 会读取您的评论并进行修订。要让 Claude 自行审查这些更改，请在提示框中输入 [`/code-review`](/docs/zh-CN/desktop#review-your-code)。

120 120

121**调整您拥有的控制权。** 您的 [permission mode](/docs/zh-CN/desktop#choose-a-permission-mode) 设置了 Claude 在不请求批准的情况下可以执行的操作：121**调整您拥有的控制权。** 您的 [权限模式](/docs/zh-CN/desktop#choose-a-permission-mode) 设置了 Claude 在不请求批准的情况下可以执行的操作：

122 122

123* **Auto**：分类器在后台审查操作，并阻止风险操作，而不是询问您。123* **Auto**：分类器在后台审查操作，并阻止风险操作，而不是询问您。

124* **Manual**：Claude 在编辑文件或运行命令前询问。124* **Manual**：Claude 在编辑文件或运行命令前询问。

125* **Accept edits**：Claude 自动接受文件编辑以加快迭代。125* **Accept edits**：Claude 自动接受文件编辑以加快迭代。

126* **Plan**：Claude 提出一种方法而不编辑任何文件，这在大型重构前很有用。126* **Plan**：Claude 提出一种方法而不编辑任何文件，这在大型重构前很有用。

127 127

128**添加插件以获得更多功能。** 点击提示框旁边的 **+** 按钮并选择 **Plugins** 以浏览和安装 [plugins](/docs/zh-CN/desktop#install-plugins)，这些插件添加 skills、agents、MCP servers 等。128**添加插件以获得更多功能。** 点击提示框旁边的 **+** 按钮并选择 **Plugins** 以浏览和安装 [插件](/docs/zh-CN/desktop#install-plugins)，这些插件添加 skills、agents、MCP servers 等。

129 129

130**整理您的工作区。** 将聊天、diff、终端、文件和浏览器窗格拖动到您想要的任何布局中。使用 **Ctrl+\`** 打开终端以在您的会话旁边运行命令，或点击文件路径以在文件窗格中打开它。请参阅 [整理您的工作区](/docs/zh-CN/desktop#arrange-your-workspace)。130**整理您的工作区。** 将聊天、diff、终端、文件和浏览器窗格拖动到您想要的任何布局中。使用 **Ctrl+\`** 打开终端以在您的会话旁边运行命令，或点击文件路径以在文件窗格中打开它。请参阅 [整理您的工作区](/docs/zh-CN/desktop#arrange-your-workspace)。

131 131

133 133

134**跟踪您的拉取请求。** 打开 PR 后，Claude Code 会监控 CI 检查结果，并可以自动修复失败，或在所有检查通过后合并 PR。请参阅 [监控拉取请求状态](/docs/zh-CN/desktop#monitor-pull-request-status)。134**跟踪您的拉取请求。** 打开 PR 后，Claude Code 会监控 CI 检查结果，并可以自动修复失败，或在所有检查通过后合并 PR。请参阅 [监控拉取请求状态](/docs/zh-CN/desktop#monitor-pull-request-status)。

135 135

136**将 Claude 放在日程上。** 设置 [scheduled tasks](/docs/zh-CN/desktop-scheduled-tasks) 以定期自动运行 Claude：每天早上进行代码审查、每周进行依赖项审计，或从您连接的工具中提取信息的简报。136**将 Claude 放在日程上。** 设置 [定时任务](/docs/zh-CN/desktop-scheduled-tasks) 以定期自动运行 Claude：每天早上进行代码审查、每周进行依赖项审计，或从您连接的工具中提取信息的简报。

137 137

138**准备好时扩展。** 从侧边栏打开 [parallel sessions](/docs/zh-CN/desktop#work-in-parallel-with-sessions) 以同时处理多个任务，可选择每个任务都在其自己的 Git worktree 中，并打开 [tasks pane](/docs/zh-CN/desktop#watch-background-tasks) 以观看会话正在运行的子代理和后台命令。打开 [side chat](/docs/zh-CN/desktop#ask-a-side-question-without-derailing-the-session) 以提出问题而不偏离主线程。将 [long-running work 发送到云](/docs/zh-CN/desktop#run-long-running-tasks-in-the-cloud) 以便即使关闭应用也能继续，或 [将您已开始的会话移至云端](/docs/zh-CN/desktop#continue-in-another-surface)（如果任务花费的时间比预期长）。[连接外部工具](/docs/zh-CN/desktop#extend-claude-code)（如 GitHub、Slack 和 Linear）以整合您的工作流。138**准备好时扩展。** 从侧边栏打开 [并行会话](/docs/zh-CN/desktop#work-in-parallel-with-sessions) 以同时处理多个任务，可选择每个任务都在其自己的 Git worktree 中，并打开 [任务窗格](/docs/zh-CN/desktop#watch-background-tasks) 以观看会话正在运行的子代理和后台命令。打开 [侧边聊天](/docs/zh-CN/desktop#ask-a-side-question-without-derailing-the-session) 以提出问题而不偏离主线程。将 [长时间运行的工作发送到云端](/docs/zh-CN/desktop#run-long-running-tasks-in-the-cloud) 以便即使关闭应用也能继续，或 [将您已开始的会话移至云端](/docs/zh-CN/desktop#continue-in-another-surface)（如果任务花费的时间比预期长）。[连接外部工具](/docs/zh-CN/desktop#extend-claude-code)（如 GitHub、Slack 和 Linear）以整合您的工作流。

139 139

140<h2 id="what’s-next">140<h2 id="what’s-next">

141 接下来141 接下来

env-vars.md +320 −317

Details

126 变量126 变量

127</h2>127</h2>

128 128

129超时时间、token 预算和重试次数等数值变量除了接受纯数字外，还接受科学计数法和数字分隔符写法，除非该变量所在行注明只接受纯数字。例如，Claude Code 将 `2e3` 读作 2000，将 `64_000` 读作 64000。在 v2.1.211 之前，这些写法可能会在无提示的情况下设置一个小得多的值，例如 `1e6` 会将超时时间设置为 1。129超时时间、token 预算和重试次数等数值变量除了接受纯数字外，还接受科学计数法和带数字分隔符的写法，但在变量所在行注明仅接受纯数字的情况除外。例如，Claude Code 会将 `2e3` 读取为 2000，将 `64_000` 读取为 64000。在 v2.1.211 之前，这些写法可能会在不提示的情况下设置一个小得多的值，例如 `1e6` 会将超时时间设置为 1。

130 130

131<Note>131<Note>

132 对于用于启用或关闭某项行为的变量，设置为 `1`、`true`、`yes` 或 `on` 可启用，设置为 `0`、`false`、`no` 或 `off` 可关闭，不区分大小写。132 对于启用或关闭某项行为的变量，设置为 `1`、`true`、`yes` 或 `on` 即可启用，设置为 `0`、`false`、`no` 或 `off` 即可关闭，不区分大小写。

133 133

134 有些变量只检查是否已设置，因此任何非空值（包括 `0`）都会启用该行为；要关闭该行为，请取消设置该变量或将其设置为空值。以下变量采用这种方式：134 有些变量只检查是否设置了它们，因此任何非空值（包括 `0`）都会启用该行为，要关闭该行为，需要取消设置该变量或将其设置为空值。以下变量按这种方式工作：

135 135

136 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`136 * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`

137 * `DISABLE_TELEMETRY`137 * `DISABLE_TELEMETRY`

140 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`140 * `FALLBACK_FOR_ALL_PRIMARY_MODELS`

141 * `IS_DEMO`141 * `IS_DEMO`

142 142

143 另有一个变量有自己的规则：`FORCE_HYPERLINK` 读取一个数字，因此只有 `0` 会将其关闭。每个变量所在行也会说明其自身的规则。143 还有一个变量有其自身的规则：`FORCE_HYPERLINK` 读取的是数字，因此只有 `0` 会关闭它。每个变量所在行也会说明其自身的规则。

144</Note>144</Note>

145 145

146| 变量 | 用途 |146| 变量 | 用途 |

147| :- | :- |147| :- | :- |

148| `ANTHROPIC_API_KEY` | 作为 `X-Api-Key` 标头发送的 API 密钥。设置后，即使您已登录，也会使用此密钥，而不是您的 Claude Pro、Max、Team 或 Enterprise 订阅。在非交互模式（`-p`）下，只要存在该密钥，就始终使用它。在交互模式下，系统会提示您批准该密钥一次，之后它才会覆盖您的订阅。要改用您的订阅，请运行 `unset ANTHROPIC_API_KEY` |148| `ANTHROPIC_API_KEY` | 作为 `X-Api-Key` 标头发送的 API 密钥。设置后，即使您已登录，也会使用此密钥，而不是您的 Claude Pro、Max、Team 或 Enterprise 订阅。在非交互模式（`-p`）下，只要存在该密钥就始终会使用它。在交互模式下，系统会在该密钥覆盖您的订阅之前提示您批准一次。若要改用您的订阅，请运行 `unset ANTHROPIC_API_KEY` |

150| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 的工作区 API 密钥，在 AWS Console 中生成。作为 `x-api-key` 发送，并优先于 AWS SigV4 |150| `ANTHROPIC_AWS_API_KEY` | [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 的工作区 API 密钥，在 AWS Console 中生成。作为 `x-api-key` 发送，优先于 AWS SigV4 |

151| `ANTHROPIC_AWS_BASE_URL` | 覆盖 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 端点 URL。用于自定义区域或通过 [LLM 网关](/docs/zh-CN/llm-gateway)路由时。默认为 `https://aws-external-anthropic.{region}.api.aws`。Claude Code 按照[与 Amazon Bedrock 相同的优先级](/docs/zh-CN/amazon-bedrock#3-configure-claude-code)解析区域 |151| `ANTHROPIC_AWS_BASE_URL` | 覆盖 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 端点 URL。用于自定义区域或通过 [LLM 网关](/docs/zh-CN/llm-gateway)路由时。默认为 `https://aws-external-anthropic.{region}.api.aws`。Claude Code 按[与 Amazon Bedrock 相同的优先级](/docs/zh-CN/amazon-bedrock#3-configure-claude-code)解析区域 |

152| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 必需。作为 `anthropic-workspace-id` 标头随每个请求发送 |152| `ANTHROPIC_AWS_WORKSPACE_ID` | [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 必需。在每个请求中作为 `anthropic-workspace-id` 标头发送 |

153| `ANTHROPIC_BASE_URL` | 覆盖 API 端点，以通过代理或网关路由请求。当设置为非第一方主机时，默认禁用 [MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)。如果您的代理会转发 `tool_reference` 块，请设置 `ENABLE_TOOL_SEARCH=true`。自 v2.1.196 起，当此变量指向 `api.anthropic.com` 以外的主机时，[Remote Control](/docs/zh-CN/remote-control#requirements) 将被禁用，与其在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的行为一致 |153| `ANTHROPIC_BASE_URL` | 覆盖 API 端点，以便通过代理或网关路由请求。当设置为非第一方主机时，默认禁用 [MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)。如果您的代理会转发 `tool_reference` 块，请设置 `ENABLE_TOOL_SEARCH=true`。从 v2.1.196 起，当此变量指向 `api.anthropic.com` 以外的主机时，[Remote Control](/docs/zh-CN/remote-control#requirements) 会被禁用，与其在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的行为一致 |

154| `ANTHROPIC_BEDROCK_BASE_URL` | 覆盖 Amazon Bedrock 端点 URL。用于自定义 Amazon Bedrock 端点或通过 [LLM 网关](/docs/zh-CN/llm-gateway)路由时。请参阅 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) |154| `ANTHROPIC_BEDROCK_BASE_URL` | 覆盖 Amazon Bedrock 端点 URL。用于自定义 Amazon Bedrock 端点或通过 [LLM 网关](/docs/zh-CN/llm-gateway)路由时。请参阅 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) |

155| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆盖 Amazon Bedrock Mantle 端点 URL。请参阅 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint) |155| `ANTHROPIC_BEDROCK_MANTLE_BASE_URL` | 覆盖 Amazon Bedrock Mantle 端点 URL。请参阅 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint) |

156| `ANTHROPIC_BEDROCK_REGION_PREFIX` | Claude Code 优先尝试的跨区域推理配置文件前缀（`us`、`eu`、`apac`、`jp`、`au` 或 `global`），而不是从 AWS 区域派生的前缀。在 AWS GovCloud 区域中会被忽略。需要 Claude Code v2.1.224 或更高版本。请参阅 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock#cross-region-inference-profile-prefixes) |156| `ANTHROPIC_BEDROCK_REGION_PREFIX` | Claude Code 优先尝试的跨区域推理配置文件前缀（`us`、`eu`、`apac`、`jp`、`au` 或 `global`），而不是根据 AWS 区域推导出的前缀。在 AWS GovCloud 区域中会被忽略。需要 Claude Code v2.1.224 或更高版本。请参阅 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock#cross-region-inference-profile-prefixes) |

157| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [服务层级](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作为 `X-Amzn-Bedrock-Service-Tier` 标头发送。请参阅 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock#service-tiers) |157| `ANTHROPIC_BEDROCK_SERVICE_TIER` | Amazon Bedrock [服务层级](https://docs.aws.amazon.com/bedrock/latest/userguide/service-tiers-inference.html)（`default`、`flex` 或 `priority`）。作为 `X-Amzn-Bedrock-Service-Tier` 标头发送。请参阅 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock#service-tiers) |

158| `ANTHROPIC_BETAS` | 要包含在 API 请求中的额外 `anthropic-beta` 标头值的逗号分隔列表。Claude Code 已经会发送其所需的 beta 标头；在 Claude Code 添加原生支持之前，可使用此变量选择加入某项 [Anthropic API beta](https://platform.claude.com/docs/en/api/beta-headers)。与需要 API 密钥身份验证的 [`--betas` 标志](/docs/zh-CN/cli-reference#cli-flags)不同，此变量适用于所有身份验证方式，包括 Claude.ai 订阅 |158| `ANTHROPIC_BETAS` | 以逗号分隔的额外 `anthropic-beta` 标头值列表，会包含在 API 请求中。Claude Code 已经会发送其所需的 beta 标头；可使用此变量在 Claude Code 添加原生支持之前选择加入某个 [Anthropic API beta](https://platform.claude.com/docs/en/api/beta-headers)。与需要 API 密钥身份验证的 [`--betas` 标志](/docs/zh-CN/cli-reference#cli-flags)不同，此变量适用于所有身份验证方式，包括 Claude.ai 订阅 |

159| `ANTHROPIC_CUSTOM_HEADERS` | 要添加到请求中的自定义标头（`Name: Value` 格式，多个标头以换行分隔）。如果名称或值包含 HTTP 标头无法承载的字符，例如弯引号或零宽空格，请求将失败，并显示一条按位置标识该键值对的错误。需要 Claude Code v2.1.227 或更高版本。[Invalid request header value](/docs/zh-CN/errors#invalid-request-header-value) 列出了确切的字符集以及检查的运行位置。设置凭据、组织或租户、路由或 API 行为标头（例如 `Authorization` 或 `Host`）的值，在由服务器托管设置下发时，算作[需要批准的设置](/docs/zh-CN/server-managed-settings#environment-variables-and-the-approval-dialog)。在项目或本地设置中，此类值遵循[何时应用 `env` 值的规则](/docs/zh-CN/settings-reference#when-claude-code-applies-env-values) |159| `ANTHROPIC_CUSTOM_HEADERS` | 要添加到请求中的自定义标头（`Name: Value` 格式，多个标头以换行分隔）。如果名称或值包含 HTTP 标头无法承载的字符，例如弯引号或零宽空格，请求会失败，并给出按位置标识该键值对的错误。需要 Claude Code v2.1.227 或更高版本。[Invalid request header value](/docs/zh-CN/errors#invalid-request-header-value) 列出了确切的字符集以及检查的运行位置。设置凭据、组织或租户、路由或 API 行为标头（例如 `Authorization` 或 `Host`）的值，在由服务器托管设置下发时，属于[需要批准的设置](/docs/zh-CN/server-managed-settings#environment-variables-and-the-approval-dialog)。来自项目或本地设置时，此类值遵循[何时应用 `env` 值的规则](/docs/zh-CN/settings-reference#when-claude-code-applies-env-values) |

160| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要作为自定义条目添加到 `/model` 选择器中的模型 ID。可使用此变量让非标准或网关专用的模型变为可选，而无需替换内置别名。请参阅[模型配置](/docs/zh-CN/model-config#add-a-custom-model-option) |160| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 要在 `/model` 选择器中添加为自定义条目的模型 ID。使用此变量可以让非标准模型或网关专用模型变为可选，而无需替换内置别名。请参阅[模型配置](/docs/zh-CN/model-config#add-a-custom-model-option) |

162| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 选择器中自定义模型条目的显示名称。未设置时，如果 Claude Code [能识别该 ID](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)，条目显示模型名称，否则显示模型 ID |162| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | `/model` 选择器中自定义模型条目的显示名称。未设置时，如果 Claude Code [能识别该 ID](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)，条目会显示模型名称，否则显示模型 ID |

163| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 自定义模型所支持[能力](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)的逗号分隔列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |163| `ANTHROPIC_CUSTOM_MODEL_OPTION_SUPPORTED_CAPABILITIES` | 以逗号分隔的自定义模型所支持的[能力](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

164| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 别名解析到的模型 ID，也是 Claude Code 在第三方提供商上进行[自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)时识别为 Fable 模型的 ID。请参阅[模型配置](/docs/zh-CN/model-config#environment-variables) |164| `ANTHROPIC_DEFAULT_FABLE_MODEL` | `fable` 别名解析到的模型 ID，也是 Claude Code 在第三方提供商上进行[自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)时识别为 Fable 模型的 ID。请参阅[模型配置](/docs/zh-CN/model-config#environment-variables) |

165| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 选择器中固定的 Fable 模型的显示描述。未设置时，该行显示以 `Custom Fable model` 开头的默认描述。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |165| `ANTHROPIC_DEFAULT_FABLE_MODEL_DESCRIPTION` | `/model` 选择器中固定 Fable 模型的显示描述。未设置时，该行显示以 `Custom Fable model` 开头的默认描述。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

166| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 选择器中固定的 Fable 模型的显示名称。未设置时，如果 Claude Code 能识别固定的 ID，该行显示模型名称，否则显示固定的 ID。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |166| `ANTHROPIC_DEFAULT_FABLE_MODEL_NAME` | `/model` 选择器中固定 Fable 模型的显示名称。未设置时，如果 Claude Code 能识别固定的 ID，该行显示模型名称，否则显示固定的 ID。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

167| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 固定的 Fable 模型所支持[能力](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)的逗号分隔列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |167| `ANTHROPIC_DEFAULT_FABLE_MODEL_SUPPORTED_CAPABILITIES` | 以逗号分隔的固定 Fable 模型所支持的[能力](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

168| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 别名解析到的模型 ID，也用于[后台功能](/docs/zh-CN/costs#background-token-usage)。请参阅[模型配置](/docs/zh-CN/model-config#environment-variables) |168| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | `haiku` 别名解析到的模型 ID，也用于[后台功能](/docs/zh-CN/costs#background-token-usage)。请参阅[模型配置](/docs/zh-CN/model-config#environment-variables) |

169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | `/model` 选择器中固定的 Haiku 模型的显示描述。未设置时，该行显示以 `Custom Haiku model` 开头的默认描述。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |169| `ANTHROPIC_DEFAULT_HAIKU_MODEL_DESCRIPTION` | `/model` 选择器中固定 Haiku 模型的显示描述。未设置时，该行显示以 `Custom Haiku model` 开头的默认描述。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

170| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 选择器中固定的 Haiku 模型的显示名称。未设置时，如果 Claude Code 能识别固定的 ID，该行显示模型名称，否则显示固定的 ID。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |170| `ANTHROPIC_DEFAULT_HAIKU_MODEL_NAME` | `/model` 选择器中固定 Haiku 模型的显示名称。未设置时，如果 Claude Code 能识别固定的 ID，该行显示模型名称，否则显示固定的 ID。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

171| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 固定的 Haiku 模型所支持[能力](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)的逗号分隔列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |171| `ANTHROPIC_DEFAULT_HAIKU_MODEL_SUPPORTED_CAPABILITIES` | 以逗号分隔的固定 Haiku 模型所支持的[能力](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

172| `ANTHROPIC_DEFAULT_MODEL` | 新会话默认启动时使用的模型。需要 Claude Code v2.1.236 或更高版本。请参阅[为新会话设置默认模型](/docs/zh-CN/model-config#set-a-default-model-for-new-sessions) |172| `ANTHROPIC_DEFAULT_MODEL` | 新会话默认启动时使用的模型。需要 Claude Code v2.1.236 或更高版本。请参阅[为新会话设置默认模型](/docs/zh-CN/model-config#set-a-default-model-for-new-sessions) |

173| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 别名解析到的模型 ID，也是 `opusplan` 在计划模式激活时使用的模型 ID。请参阅[模型配置](/docs/zh-CN/model-config#environment-variables) |173| `ANTHROPIC_DEFAULT_OPUS_MODEL` | `opus` 别名解析到的模型 ID，也是 `opusplan` 在计划模式激活时使用的模型 ID。请参阅[模型配置](/docs/zh-CN/model-config#environment-variables) |

174| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 选择器中固定的 Opus 模型的显示描述。未设置时，该行显示以 `Custom Opus model` 开头的默认描述。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |174| `ANTHROPIC_DEFAULT_OPUS_MODEL_DESCRIPTION` | `/model` 选择器中固定 Opus 模型的显示描述。未设置时，该行显示以 `Custom Opus model` 开头的默认描述。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

175| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 选择器中固定的 Opus 模型的显示名称。未设置时，如果 Claude Code 能识别固定的 ID，该行显示模型名称，否则显示固定的 ID。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |175| `ANTHROPIC_DEFAULT_OPUS_MODEL_NAME` | `/model` 选择器中固定 Opus 模型的显示名称。未设置时，如果 Claude Code 能识别固定的 ID，该行显示模型名称，否则显示固定的 ID。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

176| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 固定的 Opus 模型所支持[能力](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)的逗号分隔列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |176| `ANTHROPIC_DEFAULT_OPUS_MODEL_SUPPORTED_CAPABILITIES` | 以逗号分隔的固定 Opus 模型所支持的[能力](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

177| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 别名解析到的模型 ID，也是 `opusplan` 在计划模式未激活时使用的模型 ID。请参阅[模型配置](/docs/zh-CN/model-config#environment-variables) |177| `ANTHROPIC_DEFAULT_SONNET_MODEL` | `sonnet` 别名解析到的模型 ID，也是 `opusplan` 在计划模式未激活时使用的模型 ID。请参阅[模型配置](/docs/zh-CN/model-config#environment-variables) |

178| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | `/model` 选择器中固定的 Sonnet 模型的显示描述。未设置时，该行显示以 `Custom Sonnet model` 开头的默认描述。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |178| `ANTHROPIC_DEFAULT_SONNET_MODEL_DESCRIPTION` | `/model` 选择器中固定 Sonnet 模型的显示描述。未设置时，该行显示以 `Custom Sonnet model` 开头的默认描述。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

179| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 选择器中固定的 Sonnet 模型的显示名称。未设置时，如果 Claude Code 能识别固定的 ID，该行显示模型名称，否则显示固定的 ID。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |179| `ANTHROPIC_DEFAULT_SONNET_MODEL_NAME` | `/model` 选择器中固定 Sonnet 模型的显示名称。未设置时，如果 Claude Code 能识别固定的 ID，该行显示模型名称，否则显示固定的 ID。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

180| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 固定的 Sonnet 模型所支持[能力](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)的逗号分隔列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |180| `ANTHROPIC_DEFAULT_SONNET_MODEL_SUPPORTED_CAPABILITIES` | 以逗号分隔的固定 Sonnet 模型所支持的[能力](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities)列表，例如 `effort,thinking`。请参阅[模型配置](/docs/zh-CN/model-config#customize-pinned-model-display-and-capabilities) |

181| `ANTHROPIC_FEDERATION_RULE_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的联合规则 ID。当您将其与 `ANTHROPIC_ORGANIZATION_ID` 一起设置时，Claude Code 会选择联合凭据，其优先级高于您的 `/login` 凭据。请参阅[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |181| `ANTHROPIC_FEDERATION_RULE_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的联合规则 ID。当您将其与 `ANTHROPIC_ORGANIZATION_ID` 一起设置时，Claude Code 会选择联合凭据，其优先级高于您的 `/login` 凭据。请参阅[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |

182| `ANTHROPIC_FOUNDRY_API_KEY` | 用于 Microsoft Foundry 身份验证的 API 密钥（请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)） |182| `ANTHROPIC_FOUNDRY_API_KEY` | 用于 Microsoft Foundry 身份验证的 API 密钥（请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)） |

183| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | 用于 Microsoft Foundry 身份验证的 Bearer 令牌，例如 Microsoft Entra 访问令牌。Claude Code 将其作为 `Authorization: Bearer` 标头发送。优先于 `ANTHROPIC_FOUNDRY_API_KEY` 和 Azure 默认凭据链。请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)。需要 Claude Code v2.1.203 或更高版本 |183| `ANTHROPIC_FOUNDRY_AUTH_TOKEN` | 用于 Microsoft Foundry 身份验证的 Bearer 令牌，例如 Microsoft Entra 访问令牌。Claude Code 将其作为 `Authorization: Bearer` 标头发送。优先于 `ANTHROPIC_FOUNDRY_API_KEY` 和 Azure 默认凭据链。请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)。需要 Claude Code v2.1.203 或更高版本 |

184| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 资源的完整基础 URL（例如 `https://my-resource.services.ai.azure.com/anthropic`）。可替代 `ANTHROPIC_FOUNDRY_RESOURCE`（请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)） |184| `ANTHROPIC_FOUNDRY_BASE_URL` | Microsoft Foundry 资源的完整基础 URL（例如 `https://my-resource.services.ai.azure.com/anthropic`）。可替代 `ANTHROPIC_FOUNDRY_RESOURCE`（请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)） |

185| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 资源名称（例如 `my-resource`）。Claude Code [会拒绝 URL 或主机名](/docs/zh-CN/errors#anthropic-foundry-resource-must-be-a-foundry-resource-name)。如果未设置 `ANTHROPIC_FOUNDRY_BASE_URL`，则为必需（请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)） |185| `ANTHROPIC_FOUNDRY_RESOURCE` | Microsoft Foundry 资源名称（例如 `my-resource`）。Claude Code [会拒绝 URL 或主机名](/docs/zh-CN/errors#anthropic-foundry-resource-must-be-a-foundry-resource-name)。未设置 `ANTHROPIC_FOUNDRY_BASE_URL` 时必需（请参阅 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry)） |

187| `ANTHROPIC_ORGANIZATION_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的组织 ID。请将其与 `ANTHROPIC_FEDERATION_RULE_ID` 一起设置。请参阅[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |187| `ANTHROPIC_ORGANIZATION_ID` | [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的组织 ID。请将其与 `ANTHROPIC_FEDERATION_RULE_ID` 一起设置。请参阅[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |

188| `ANTHROPIC_PROFILE` | 用于身份验证的 Anthropic 配置文件名称，例如由 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 或[在没有 API 密钥的情况下登录 Console 账户](/docs/zh-CN/authentication#sign-in-without-an-api-key)所创建的配置文件。请参阅[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |188| `ANTHROPIC_PROFILE` | 用于身份验证的 Anthropic 配置文件名称，例如由 [`ant auth login`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/authentication) 创建的配置文件，或通过[在没有 API 密钥的情况下登录 Console 账户](/docs/zh-CN/authentication#sign-in-without-an-api-key)创建的配置文件。请参阅[身份验证优先级](/docs/zh-CN/authentication#authentication-precedence) |

190| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 时，覆盖 Haiku 级模型的 AWS 区域。在 Amazon Bedrock 上，仅当同时设置了 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已弃用的 `ANTHROPIC_SMALL_FAST_MODEL` 时才生效，因为否则 Amazon Bedrock 会在会话区域中使用[默认 Sonnet 模型或主模型](/docs/zh-CN/amazon-bedrock#4-pin-model-versions)运行后台任务 |190| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | 使用 Amazon Bedrock 或 Amazon Bedrock Mantle 时，覆盖 Haiku 级模型的 AWS 区域。在 Amazon Bedrock 上，只有在同时设置了 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 或已弃用的 `ANTHROPIC_SMALL_FAST_MODEL` 时此变量才会生效，因为否则 Amazon Bedrock 会在会话区域中使用[默认 Sonnet 模型或主模型](/docs/zh-CN/amazon-bedrock#4-pin-model-versions)运行后台任务 |

191| `ANTHROPIC_VERTEX_BASE_URL` | 覆盖 Google Cloud's Agent Platform 端点 URL。用于自定义 Google Cloud's Agent Platform 端点或通过 [LLM 网关](/docs/zh-CN/llm-gateway)路由时。请参阅 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) |191| `ANTHROPIC_VERTEX_BASE_URL` | 覆盖 Google Cloud's Agent Platform 端点 URL。用于自定义 Google Cloud's Agent Platform 端点或通过 [LLM 网关](/docs/zh-CN/llm-gateway)路由时。请参阅 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) |

192| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 请求所发往的 GCP 项目 ID。请参阅[配置 GCP 凭据](/docs/zh-CN/google-vertex-ai#3-configure-gcp-credentials) |192| `ANTHROPIC_VERTEX_PROJECT_ID` | Google Cloud's Agent Platform 请求所指向的 GCP 项目 ID。请参阅[配置 GCP 凭据](/docs/zh-CN/google-vertex-ai#3-configure-gcp-credentials) |

193| `ANTHROPIC_WORKSPACE_ID` | [workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作区 ID。当您的联合规则作用于多个工作区时设置此变量，以便令牌交换知道要定位哪个工作区 |193| `ANTHROPIC_WORKSPACE_ID` | [workload identity federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 的工作区 ID。当您的联合规则的作用范围涵盖多个工作区时设置此变量，以便令牌交换知道要定位到哪个工作区 |

194| `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`，也会中止长时间的静默暂停 |194| `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`，它们也会中止长时间的静默暂停 |

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

196| `AWS_BEARER_TOKEN_BEDROCK` | 用于身份验证的 Amazon Bedrock API 密钥（请参阅 [Amazon Bedrock API 密钥](https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/)） |196| `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/)） |

197| `BASH_DEFAULT_TIMEOUT_MS` | 前台 Bash 或 PowerShell 工具命令的默认超时时间（毫秒）（默认值：120000，即 2 分钟）。超过 30 分钟的默认值也会成为无人值守会话中[后台命令的默认时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)。后台时间限制需要 Claude Code v2.1.285 或更高版本 |197| `BASH_DEFAULT_TIMEOUT_MS` | 前台 Bash 或 PowerShell 工具命令的默认超时时间，以毫秒为单位（默认值：120000，即 2 分钟）。高于[后台命令默认时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)的值会在无人值守的会话中替换该默认值。后台时间限制需要 Claude Code v2.1.285 或更高版本 |

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

199| `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 或更高版本 |199| `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 或更高版本 |

200| `BETA_TRACING_ENDPOINT` | 用于[详细 beta 追踪](/docs/zh-CN/monitoring-usage#traces-beta)的 OTLP/HTTP 端点：在设置 `ENABLE_BETA_TRACING_DETAILED=1` 时，日志和追踪会发送到该端点，而不是已配置的导出器。请在您的 shell、用户设置或托管设置中设置它。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略 |200| `BETA_TRACING_ENDPOINT` | 用于[详细 beta 追踪](/docs/zh-CN/monitoring-usage#traces-beta)的 OTLP/HTTP 端点：设置 `ENABLE_BETA_TRACING_DETAILED=1` 后，日志和追踪会发送到该端点，而不是发送到已配置的导出器。请在您的 shell、用户设置或托管设置中设置它。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略 |

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

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

203| `CLAUDE_AFK_COUNTDOWN_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话框在自动继续前多少毫秒显示屏幕倒计时。默认值 `20000`（20 秒），上限为自动继续超时时间。除非启用了自动继续，否则无效；请参阅 [`askUserQuestionTimeout`](/docs/zh-CN/settings-reference#askuserquestiontimeout) 设置和 `CLAUDE_AFK_TIMEOUT_MS`。需要 Claude Code v2.1.198 或更高版本 |203| `CLAUDE_AFK_COUNTDOWN_MS` | 在未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话框自动继续之前，屏幕倒计时提前多少毫秒出现。默认值为 `20000`（20 秒），上限为自动继续超时时间。除非启用了自动继续，否则不起作用；请参阅 [`askUserQuestionTimeout`](/docs/zh-CN/settings-reference#askuserquestiontimeout) 设置和 `CLAUDE_AFK_TIMEOUT_MS`。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略。需要 Claude Code v2.1.198 或更高版本 |

204| `CLAUDE_AFK_TIMEOUT_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话框在空闲多少毫秒后无需您参与即自动继续。自动继续默认关闭；可通过 [`askUserQuestionTimeout`](/docs/zh-CN/settings-reference#askuserquestiontimeout) 设置选择启用。此变量是用于演示和自动化测试的覆盖项：设置后，它优先于该设置，即使该设置未设置或为 `never`，也会启用自动继续。设置 `0` 不会关闭超时，而是立即关闭对话框。在 v2.1.198 和 v2.1.199 中，自动继续默认启用，超时时间为 `60000`（60 秒）。需要 Claude Code v2.1.198 或更高版本 |204| `CLAUDE_AFK_TIMEOUT_MS` | 未回答的 [`AskUserQuestion`](/docs/zh-CN/tools-reference) 对话框在空闲多少毫秒后无需您参与即自动继续。自动继续默认关闭；可通过 [`askUserQuestionTimeout`](/docs/zh-CN/settings-reference#askuserquestiontimeout) 设置选择启用。此变量是用于演示和自动化测试的覆盖项：设置后，它优先于该设置，即使该设置未设置或为 `never`，也会启用自动继续。设置为 `0` 不会关闭超时，而是会立即关闭对话框。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略。在 v2.1.200 之前，自动继续默认启用，超时时间为 `60000`（60 秒）。需要 Claude Code v2.1.198 或更高版本 |

205| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 设置为 `1` 可禁用所有内置[子代理](/docs/zh-CN/sub-agents)类型，例如 Explore 和 Plan。仅适用于非交互模式（`-p` 标志）。对于希望从零开始的 SDK 用户很有用。这也会移除 `general-purpose`，即当 Agent 工具调用省略 `subagent_type` 时 Claude Code 运行的子代理。此类调用随后将失败并显示 [`subagent_type is required`](/docs/zh-CN/errors#subagent-type-is-required) |205| `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` | 设置为 `1` 可禁用所有内置[子代理](/docs/zh-CN/sub-agents)类型，例如 Explore 和 Plan。仅适用于非交互模式（`-p` 标志）。适用于希望从空白状态开始的 SDK 用户。这还会移除 `general-purpose`，即 Agent 工具调用省略 `subagent_type` 时 Claude Code 运行的子代理。此后此类调用会失败并报错 [`subagent_type is required`](/docs/zh-CN/errors#subagent-type-is-required) |

207| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 子代理的停滞超时时间（毫秒）。默认值 `600000`（10 分钟）；如果您在流式看门狗启用时提高 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，默认值也会随之提高，如[处理缓慢或停滞的 API 响应](/docs/zh-CN/agent-sdk/typescript#handle-slow-or-stalled-api-responses)所述。计时器会在每个流式进度事件时重置；如果在该时间窗口内没有进度到达，Claude Code 会中止该子代理并向父级报告停滞 |207| `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS` | 子代理的停滞超时时间，以毫秒为单位。默认值为 `600000`（10 分钟）；如果您在流式监视器启用时提高了 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，默认值也会随之提高，详见[处理缓慢或停滞的 API 响应](/docs/zh-CN/agent-sdk/typescript#handle-slow-or-stalled-api-responses)。计时器会在每个流式进度事件时重置；如果在该时间窗口内没有进度到达，Claude Code 会中止该子代理并向父级报告停滞 |

208| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 设置触发自动压缩时自动压缩窗口的百分比（1-100）。使用较低的值（例如 `50`）可更早压缩；该变量无法提高阈值，因此高于默认百分比的值会被忽略。它仅适用于[在达到模型上下文限制之前进行压缩](/docs/zh-CN/model-config#context-window-and-auto-compaction)的会话。同时适用于主对话和子代理 |208| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | 设置触发自动压缩时自动压缩窗口的百分比（1-100）。使用较低的值（如 `50`）可以更早压缩；该变量无法提高阈值，因此高于默认百分比的值会被忽略。它仅适用于[在达到模型上下文限制之前进行压缩](/docs/zh-CN/model-config#context-window-and-auto-compaction)的会话。同时适用于主对话和子代理 |

209| `CLAUDE_AUTO_BACKGROUND_TASKS` | 设置为 `1` 可强制启用长时间运行的 Agent 任务的自动后台化。启用后，子代理运行约两分钟后会被移至后台。在 Claude Code v2.1.212 或更高版本上，还会在非交互模式下启用[长时间 MCP 工具调用的自动后台化](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls) |209| `CLAUDE_AUTO_BACKGROUND_TASKS` | 设置为 `1` 可强制启用长时间运行的 Agent 任务的自动后台化。启用后，子代理运行约两分钟后会被移至后台。在 Claude Code v2.1.212 或更高版本中，还会在非交互模式下启用[长时间 MCP 工具调用的自动后台化](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls) |

210| `CLAUDE_AX_PREPARK_MS` | 在[屏幕阅读器模式](/docs/zh-CN/accessibility)下，Claude Code 在写入新行或已更改的行之前等待的毫秒数。默认值 `0`，因此 Claude Code 不会等待。在 v2.1.287 之前，默认值为 `50`。Claude Code 将等待时间上限设为 `5000`。需要 Claude Code v2.1.233 或更高版本 |210| `CLAUDE_AX_PREPARK_MS` | 在[屏幕阅读器模式](/docs/zh-CN/accessibility)下，Claude Code 在写入新行或已更改的行之前等待的毫秒数。默认值为 `0`，因此 Claude Code 不会等待。在 v2.1.287 之前，默认值为 `50`。Claude Code 将等待上限设为 `5000`。需要 Claude Code v2.1.233 或更高版本 |

211| `CLAUDE_AX_SCREEN_READER` | 设置为 `1` 可渲染适合屏幕阅读器的输出：不带装饰性边框或动画的纯文本。设置为 `0` 可强制关闭屏幕阅读器模式，即使 [`axScreenReader`](/docs/zh-CN/settings-reference#axscreenreader) 为 `true`。[`--ax-screen-reader`](/docs/zh-CN/cli-reference#cli-flags) 标志优先。需要 Claude Code v2.1.181 或更高版本 |211| `CLAUDE_AX_SCREEN_READER` | 设置为 `1` 可呈现对屏幕阅读器友好的输出：不带装饰性边框或动画的纯文本。设置为 `0` 可强制关闭屏幕阅读器模式，即使 [`axScreenReader`](/docs/zh-CN/settings-reference#axscreenreader) 为 `true`。[`--ax-screen-reader`](/docs/zh-CN/cli-reference#cli-flags) 标志优先。需要 Claude Code v2.1.181 或更高版本 |

212| `CLAUDE_AX_STARTUP_QUIET_MS` | 在[屏幕阅读器模式](/docs/zh-CN/accessibility)下，Claude Code 在启动确认行之后推迟首次界面渲染的毫秒数，以便您的屏幕阅读器在新输出打断之前完整朗读该行。默认值 `3000`。设置 `0` 可立即渲染。Claude Code 将推迟时间上限设为 `600000`（10 分钟）。您的第一次按键会提前结束推迟。需要 Claude Code v2.1.217 或更高版本 |212| `CLAUDE_AX_STARTUP_QUIET_MS` | 在[屏幕阅读器模式](/docs/zh-CN/accessibility)下，Claude Code 在启动确认行之后推迟首次界面渲染的毫秒数，以便您的屏幕阅读器在新输出打断之前完整朗读该行。默认值为 `3000`。设置为 `0` 可立即渲染。Claude Code 将推迟时间上限设为 `600000`（10 分钟）。您的第一次按键会提前结束推迟。需要 Claude Code v2.1.217 或更高版本 |

214| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 字节级流式空闲看门狗的超时时间（毫秒）；设置后，对于该看门狗，它优先于 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，并保持事件级看门狗不变。Claude Code 将此变量限制在 10 秒到 30 分钟之间。需要 Claude Code v2.1.210 或更高版本 |214| `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` | 字节级流式空闲监视器的超时时间，以毫秒为单位；设置后，对于该监视器，它优先于 `CLAUDE_STREAM_IDLE_TIMEOUT_MS`，并且不改变事件级监视器。Claude Code 将此变量限制在 10 秒到 30 分钟之间。需要 Claude Code v2.1.210 或更高版本 |

215| `CLAUDE_CLIENT_PRESENCE_FILE` | 一个文件的路径，该文件由外部工具（例如锁屏监听器）在您解锁屏幕时创建、在您锁定屏幕时删除。当该文件存在时，Claude Code 会跳过 [Remote Control 移动推送通知](/docs/zh-CN/remote-control#mobile-push-notifications)，这样您在主动使用计算机时就不会收到推送。当该文件不存在或无法读取时，通知照常发送。Claude Code 在每次触发推送的事件时检查一次该文件，而不是轮询。需要 Claude Code v2.1.181 或更高版本 |215| `CLAUDE_CLIENT_PRESENCE_FILE` | 一个文件的路径，由外部工具（例如屏幕锁定监听器）在您解锁屏幕时创建、在您锁定屏幕时删除。当该文件存在时，Claude Code 会跳过 [Remote Control 移动推送通知](/docs/zh-CN/remote-control#mobile-push-notifications)，这样您在积极使用计算机时就不会收到推送。当该文件不存在或无法读取时，通知会照常发送。Claude Code 在每次触发推送的事件时检查该文件一次，而不是轮询它。需要 Claude Code v2.1.181 或更高版本 |

217| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 设置为 `1` 可从通过 `--add-dir` 指定的目录加载记忆文件。加载 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。默认情况下，附加目录不会加载记忆文件 |217| `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` | 设置为 `1` 可从通过 `--add-dir` 指定的目录加载记忆文件。会加载 `CLAUDE.md`、`.claude/CLAUDE.md`、`.claude/rules/*.md` 和 `CLAUDE.local.md`。默认情况下，附加目录不会加载记忆文件 |

218| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 设置为 `1` 可在[全屏渲染](/docs/zh-CN/fullscreen)中每帧重绘整个屏幕，而不是发送增量更新。如果全屏模式显示过时或错位的文本片段，请使用此选项。Claude Code 会在 Windows 上为后台会话和 [Agent 视图](/docs/zh-CN/agent-view)自动启用此选项 |218| `CLAUDE_CODE_ALT_SCREEN_FULL_REPAINT` | 设置为 `1` 可在[全屏渲染](/docs/zh-CN/fullscreen)中每一帧都重绘整个屏幕，而不是发送增量更新。如果全屏模式显示过时或错位的文本片段，请使用此变量。在 Windows 上，Claude Code 会为后台会话和 [Agent 视图](/docs/zh-CN/agent-view)自动启用此功能 |

219| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 设置为 `1` 可在每个请求中发送 [effort](/docs/zh-CN/model-config#adjust-effort-level) 参数，即使 Claude Code 未将该模型 ID 识别为支持 effort。通过 [LLM 网关](/docs/zh-CN/llm-gateway)或以自定义标识符提供模型的第三方提供商路由时使用此选项。在 API 层拒绝 effort 参数的模型（包括 Claude 3 模型、Sonnet 4.0 和 4.5、Opus 4.0 和 4.1 以及 Haiku 4.5）仍会被排除，因此请求不会失败 |219| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 设置为 `1` 可在每个请求中发送 [effort](/docs/zh-CN/model-config#adjust-effort-level) 参数，即使 Claude Code 未将该模型 ID 识别为支持 effort。当通过以自定义标识符提供模型的 [LLM 网关](/docs/zh-CN/llm-gateway)或第三方提供商路由时，请使用此变量。在 API 层面拒绝 effort 参数的模型（包括 Claude 3 模型、Sonnet 4.0 和 4.5、Opus 4.0 和 4.1 以及 Haiku 4.5）仍会被排除，因此请求不会失败 |

220| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 刷新凭据的时间间隔（毫秒）（使用 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 时） |220| `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` | 刷新凭据的间隔，以毫秒为单位（使用 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 时） |

221| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 设置为 `0` 可阻止 Claude Code 在发布新的 [Artifact](/docs/zh-CN/artifacts#create-an-artifact) 时自动打开浏览器 |221| `CLAUDE_CODE_ARTIFACT_AUTO_OPEN` | 设置为 `0` 可阻止 Claude Code 在发布新的 [Artifact](/docs/zh-CN/artifacts#create-an-artifact) 时自动打开浏览器 |

222| `CLAUDE_CODE_ARTIFACT_COMMENTS` | 设置为 `0` 可阻止 Claude 读取和回复 [Artifact 上的评论](/docs/zh-CN/artifacts#collect-comments-on-an-artifact)。当 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 已[关闭 Artifact](/docs/zh-CN/artifacts#availability) 时无效。需要 Claude Code v2.1.221 或更高版本 |222| `CLAUDE_CODE_ARTIFACT_COMMENTS` | 设置为 `0` 可阻止 Claude 读取和回复 [Artifact 上的评论](/docs/zh-CN/artifacts#collect-comments-on-an-artifact)。当 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 已[关闭 Artifact](/docs/zh-CN/artifacts#availability) 时不起作用。需要 Claude Code v2.1.221 或更高版本 |

223| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | 设置为 `0` 可阻止 Claude [自行回复发送给它的评论](/docs/zh-CN/artifacts#let-claude-reply-to-comments-on-its-own)。需要 Claude Code v2.1.228 或更高版本 |223| `CLAUDE_CODE_ARTIFACT_COMMENTS_AUTOREACT` | 设置为 `0` 可阻止 Claude [自行回复发送给它的评论](/docs/zh-CN/artifacts#let-claude-reply-to-comments-on-its-own)。需要 Claude Code v2.1.228 或更高版本 |

224| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 设置为 `0` 可从系统提示词开头省略[归属块](/docs/zh-CN/llm-gateway-protocol#system-prompt-attribution-block)，该块包含客户端版本和提示词指纹。无论如何设置，直接连接 Anthropic API 时的缓存都不受影响。在某些直接连接配置中，即使您设置了 `0`，Claude Code 也会在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器请求中保留该块。请在[系统提示词归属块](/docs/zh-CN/llm-gateway-protocol#system-prompt-attribution-block)中查看此情况涵盖哪些连接和凭据。在 v2.1.181 之前，该块在自定义基础 URL 和 Microsoft Foundry 连接上包含每个请求各不相同的 token，因此在这些版本上，当您的 LLM 网关根据请求体进行缓存或将请求转发给第三方提供商时，或者当您直接连接到 Microsoft Foundry 时，请将其设置为 `0` |224| `CLAUDE_CODE_ATTRIBUTION_HEADER` | 设置为 `0` 可从系统提示词开头省略[归属块](/docs/zh-CN/llm-gateway-protocol#system-prompt-attribution-block)，该块携带客户端版本和提示词指纹。无论如何设置，直接连接 Anthropic API 时的缓存都不受影响。在某些直接连接的设置中，即使您设置了 `0`，Claude Code 仍会在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器请求中保留该块。请在[系统提示词归属块](/docs/zh-CN/llm-gateway-protocol#system-prompt-attribution-block)中查看这涵盖哪些连接和凭据。在 v2.1.181 之前，该块在自定义基础 URL 和 Microsoft Foundry 连接上包含每个请求的 token，因此在这些版本上，当您的 LLM 网关基于请求体进行缓存或将请求转发给第三方提供商时，或者当您直接连接 Microsoft Foundry 时，请将其设置为 `0` |

226| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 以 token 为单位设置[自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window)，范围为 `100000` 到 `1000000`。仅接受纯整数，例如 `500000`：像 `500k` 这样的值会被读作 `500`，并被限制为 100K 的最小值。有效窗口还会以模型的上下文窗口为上限。优先于 `/autocompact` 命令、`--autocompact` 标志和 `autoCompactWindow` 设置。状态栏的 `used_percentage` 始终根据模型的完整上下文窗口计算，因此一旦设置了此变量，该百分比就不再表示何时会进行压缩 |226| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | 以 token 为单位设置[自动压缩窗口](/docs/zh-CN/model-config#set-the-auto-compact-window)，范围为 `100000` 到 `1000000`。仅接受纯整数，例如 `500000`：像 `500k` 这样的值会被读取为 `500`，并被限制到 100K 的最小值。有效窗口还会以模型的上下文窗口为上限。优先于 `/autocompact` 命令、`--autocompact` 标志和 `autoCompactWindow` 设置。状态栏的 `used_percentage` 始终以模型的完整上下文窗口为基准，因此一旦设置了此变量，该百分比就不再表示何时进行压缩 |

227| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆盖自动 [IDE 连接](/docs/zh-CN/vs-code)。默认情况下，在受支持的 IDE 集成终端中启动时，Claude Code 会自动连接。设置为 `false` 可阻止此行为。设置为 `true` 可在自动检测失败时（例如 tmux 遮蔽了父终端）强制尝试连接。优先于 [`autoConnectIde`](/docs/zh-CN/settings-reference#autoconnectide) 全局配置设置 |227| `CLAUDE_CODE_AUTO_CONNECT_IDE` | 覆盖自动 [IDE 连接](/docs/zh-CN/vs-code)。默认情况下，在受支持 IDE 的集成终端中启动时，Claude Code 会自动连接。设置为 `false` 可阻止此行为。设置为 `true` 可在自动检测失败时（例如 tmux 遮蔽了父终端时）强制尝试连接。优先于 [`autoConnectIde`](/docs/zh-CN/settings-reference#autoconnectide) 全局配置设置 |

228| `CLAUDE_CODE_AUTO_MODE_SERVER` | 控制 Claude Code 是否请求服务器[审查自动模式操作](/docs/zh-CN/permission-modes#server-side-classifier-review)。设置为 `0` 可改用 Claude Code 自己的分类器请求。在直接连接 Anthropic API 时，需要 v2.1.281 或更高版本。链接的章节列出了在未设置该变量时哪些会话会请求服务器，以及从哪个版本开始。需要 Claude Code v2.1.271 或更高版本 |228| `CLAUDE_CODE_AUTO_MODE_SERVER` | 控制 Claude Code 是否请求服务器[审查自动模式操作](/docs/zh-CN/permission-modes#server-side-classifier-review)。设置为 `0` 可改用 Claude Code 自身的分类器请求。在直接连接 Anthropic API 时，需要 v2.1.281 或更高版本。链接的章节列出了在该变量未设置时哪些会话会请求服务器，以及从哪个版本开始。需要 Claude Code v2.1.271 或更高版本 |

229| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 默认凭据提供程序链生成凭据的时间（毫秒），超时后请求将失败并显示 [`AWS default-chain credential resolve timed out`](/docs/zh-CN/errors#aws-default-chain-credential-resolve-timed-out)（默认值：`60000`）。当链中某个步骤确实需要更长时间时，请提高此值，例如通过 `aws-vault` 等包装器进行带 MFA 的基于浏览器的 SSO 登录。适用于 Amazon Bedrock、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)。请参阅[凭据缓存和解析超时](/docs/zh-CN/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更高版本 |229| `CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS` | Claude Code 等待 AWS 默认凭据提供程序链生成凭据的时间（以毫秒为单位），超时后请求会失败并报错 [`AWS default-chain credential resolve timed out`](/docs/zh-CN/errors#aws-default-chain-credential-resolve-timed-out)（默认值：`60000`）。当您的凭据链中某个步骤确实需要更长时间时（例如通过 `aws-vault` 等包装器进行带 MFA 的基于浏览器的 SSO 登录），请提高此值。适用于 Amazon Bedrock、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和 [Mantle 端点](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint)。请参阅[凭据缓存和解析超时](/docs/zh-CN/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更高版本 |

230| `CLAUDE_CODE_BASH_EDIT_DIFF` | 设置为 `0` 可关闭[在 Bash 命令运行期间所更改文件的 diff](/docs/zh-CN/hooks#bash)，设置为 `1` 可在每种权限模式下记录它。优先于 [`bashEditDiffEnabled`](/docs/zh-CN/settings-reference#basheditdiffenabled) 设置。需要 Claude Code v2.1.269 或更高版本 |230| `CLAUDE_CODE_BASH_EDIT_DIFF` | 设置为 `0` 可关闭 [Bash 命令运行期间所更改文件的 diff](/docs/zh-CN/hooks#bash)，设置为 `1` 可在每种权限模式下记录它。优先于 [`bashEditDiffEnabled`](/docs/zh-CN/settings-reference#basheditdiffenabled) 设置。需要 Claude Code v2.1.269 或更高版本 |

231| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | 设置为 `0` 可使非交互会话在每个轮次结束时向其宿主报告空闲状态，即使后台工作仍在运行。默认情况下，当后台 Agent 或[工作流](/docs/zh-CN/workflows)运行等后台工作仍处于活动状态时，会话在轮次结束后会继续报告运行状态。这可以防止监视该状态的宿主（例如远程会话列表）在工作进行中宣布 Claude 正在等待您的输入。后台 shell 命令（例如开发服务器）不会保持运行状态。运行状态默认值和 `0` 选择退出需要 Claude Code v2.1.269 或更高版本；在更早的版本上，请设置 `1` 以保持运行状态 |231| `CLAUDE_CODE_BG_TASKS_REPORT_RUNNING` | 设置为 `0` 可使非交互会话在每个轮次结束时向其宿主报告空闲状态，即使后台工作仍在运行。默认情况下，当后台 Agent 或[工作流](/docs/zh-CN/workflows)运行等后台工作仍在进行时，会话在轮次结束后会继续报告运行状态。这可以防止监视该状态的宿主（例如远程会话列表）在工作进行中宣布 Claude 正在等待您的输入。后台 shell 命令（例如开发服务器）不会保持运行状态。运行状态默认行为和 `0` 选择退出需要 Claude Code v2.1.269 或更高版本；在更早的版本上，请设置 `1` 以保持运行状态 |

232| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 当会话具有活动的 [Remote Control](/docs/zh-CN/remote-control) 连接时，在 Bash 工具和 [hook 命令](/docs/zh-CN/hooks)子进程中自动设置，并在连接结束时移除。其值为 `session_` 形式的会话 ID，与会话的 `claude.ai/code` URL 中出现的标识符相同，因此脚本可以链接回运行它的会话。需要 Claude Code v2.1.199 或更高版本。在[云端会话](/docs/zh-CN/claude-code-on-the-web)中，请改为读取 `CLAUDE_CODE_REMOTE_SESSION_ID` |232| `CLAUDE_CODE_BRIDGE_SESSION_ID` | 当会话有活动的 [Remote Control](/docs/zh-CN/remote-control) 连接时，在 Bash 工具和 [hook 命令](/docs/zh-CN/hooks)子进程中自动设置，并在连接结束时移除。其值为 `session_` 形式的会话 ID，与会话的 `claude.ai/code` URL 中出现的标识符相同，因此脚本可以链接回运行它的会话。需要 Claude Code v2.1.199 或更高版本。在[云端会话](/docs/zh-CN/claude-code-on-the-web)中，请改为读取 `CLAUDE_CODE_REMOTE_SESSION_ID` |

233| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | 设置为 `0` 可让 Claude Code 将 `0x08` 字节（也写作 `^H`）读作普通 Backspace，设置为 `1` 则读作 Ctrl+Backspace。任一值都会替换平台默认值。默认情况下，Claude Code 在 Windows 上将其读作 Ctrl+Backspace（`TERM_PROGRAM` 为 `mintty` 或 `TERM` 为 `cygwin` 时除外），在 macOS 和 Linux 上读作普通 Backspace。在 [Backspace 会删除整个单词](/docs/zh-CN/terminal-config#fix-backspace-deleting-a-whole-word-on-windows)的 Windows 终端中，请设置 `0` |233| `CLAUDE_CODE_BS_AS_CTRL_BACKSPACE` | 设置为 `0` 可使 Claude Code 将 `0x08` 字节（也写作 `^H`）读取为普通 Backspace，设置为 `1` 可将其读取为 Ctrl+Backspace。任一值都会替换平台默认行为。默认情况下，Claude Code 在 Windows 上将其读取为 Ctrl+Backspace（`TERM_PROGRAM` 为 `mintty` 或 `TERM` 为 `cygwin` 时除外），在 macOS 和 Linux 上将其读取为普通 Backspace。在 [Backspace 会删除整个单词](/docs/zh-CN/terminal-config#fix-backspace-deleting-a-whole-word-on-windows)的 Windows 终端中，请设置为 `0` |

234| `CLAUDE_CODE_CERT_STORE` | 用于 TLS 连接的 CA 证书来源的逗号分隔列表。`bundled` 是 Claude Code 附带的 Mozilla CA 集。`system` 是操作系统信任存储，仅在具有 `tls.getCACertificates` 的运行时上读取：原生二进制文件，或 npm 安装时的 Node 22.15 或更高版本。请参阅 [CA 证书存储](/docs/zh-CN/network-config#ca-certificate-store)。默认值为 `bundled,system` |234| `CLAUDE_CODE_CERT_STORE` | 以逗号分隔的 TLS 连接 CA 证书来源列表。`bundled` 是 Claude Code 附带的 Mozilla CA 集合。`system` 是操作系统信任存储，仅在具有 `tls.getCACertificates` 的运行时上读取：原生二进制文件，或 npm 安装时的 Node 22.15 或更高版本。请参阅 [CA 证书存储](/docs/zh-CN/network-config#ca-certificate-store)。默认值为 `bundled,system` |

235| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 通过 Bash、PowerShell 和 Monitor 工具、[hook](/docs/zh-CN/hooks) 命令和[状态栏](/docs/zh-CN/statusline)命令生成的子进程中设置为 `1`。不会为 stdio [MCP 服务器](/docs/zh-CN/mcp)子进程设置，因为这些子进程长期运行，生命周期超过生成它们的会话。与 `CLAUDECODE` 不同，此变量仅在 Claude Code 自身启动子进程时设置，IDE 扩展不会设置，因此它可以可靠地区分嵌套会话与在 IDE 集成终端中启动的顶层 `claude`。以这种方式启动的嵌套交互式 `claude` TUI 会自动从 `--resume`、`--continue`、向上箭头历史记录和 `claude agents` 列表中排除。非交互式 `claude -p` 会话仍会持久化。设置 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 可覆盖此排除。需要 Claude Code v2.1.172 或更高版本 |235| `CLAUDE_CODE_CHILD_SESSION` | 在 Claude Code 通过 Bash、PowerShell 和 Monitor 工具、[hook](/docs/zh-CN/hooks) 命令以及[状态栏](/docs/zh-CN/statusline)命令生成的子进程中设置为 `1`。不会为 stdio [MCP 服务器](/docs/zh-CN/mcp)子进程设置，因为这些子进程是长期存在的，其生命周期超过生成它们的会话。与 `CLAUDECODE` 不同，此变量仅由 Claude Code 本身在启动子进程时设置，IDE 扩展不会设置，因此它能够可靠地区分嵌套会话与在 IDE 集成终端中启动的顶层 `claude`。以这种方式启动的嵌套交互式 `claude` TUI 会自动从 `--resume`、`--continue`、上箭头历史记录和 `claude agents` 列表中排除。非交互式 `claude -p` 会话仍会持久保存。设置 `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1` 可覆盖此排除行为。需要 Claude Code v2.1.172 或更高版本 |

239| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 已在 v2.1.186 中移除，现在不起任何作用。以前用于为流式 API 请求的连接、TLS 和响应标头阶段设置单独的超时时间。请使用 `API_TIMEOUT_MS` 设置每个请求的超时时间。关于流式请求的响应标头阶段，请参阅 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |239| `CLAUDE_CODE_CONNECT_TIMEOUT_MS` | 已在 v2.1.186 中移除，现在不起任何作用。以前用于为流式 API 请求的连接、TLS 和响应标头阶段设置单独的超时时间。请使用 `API_TIMEOUT_MS` 设置每个请求的超时时间。关于流式请求的响应标头阶段，请参阅 `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` |

240| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆盖调试日志文件路径。尽管名称如此，这是文件路径，而不是目录。需要通过 `--debug`、`/debug` 或 `DEBUG` 环境变量单独启用调试模式：仅设置此变量不会启用日志记录。[`--debug-file`](/docs/zh-CN/cli-reference#cli-flags) 标志可同时完成这两项操作。默认为 `~/.claude/debug/<session-id>.txt` |240| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 覆盖调试日志文件路径。尽管名称如此，这是一个文件路径，而不是目录。需要通过 `--debug`、`/debug` 或 `DEBUG` 环境变量单独启用调试模式：仅设置此变量不会启用日志记录。[`--debug-file`](/docs/zh-CN/cli-reference#cli-flags) 标志可同时完成这两项。默认为 `~/.claude/debug/<session-id>.txt` |

241| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 写入调试日志文件的最低日志级别。可选值：`verbose`、`debug`（默认）、`info`、`warn`、`error`。设置为 `verbose` 可包含大量诊断信息，例如完整的状态栏命令输出；或提高到 `error` 以减少干扰 |241| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 写入调试日志文件的最低日志级别。取值：`verbose`、`debug`（默认）、`info`、`warn`、`error`。设置为 `verbose` 可包含大量诊断信息，例如完整的状态栏命令输出；或提高到 `error` 以减少干扰信息 |

242| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 设置为 `1` 可禁用 [1M 上下文窗口](/docs/zh-CN/model-config#extended-context)支持。设置后，模型选择器中将不提供 1M 模型变体，并且 Claude Code 会将使用原生 1M 窗口的模型（例如 [Sonnet 5.5](/docs/zh-CN/model-config#sonnet-5-5-and-sonnet-5-context-window) 和 Fable 模型）上的会话限制为 200K 窗口；有关如何强制执行此限制，请参阅[扩展上下文](/docs/zh-CN/model-config#extended-context)。适用于有合规要求的企业环境。关于它在为无法识别的 `[1m]` 模型 ID 修正窗口方面的作用，请参阅[为网关或自定义模型 ID 修正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |242| `CLAUDE_CODE_DISABLE_1M_CONTEXT` | 设置为 `1` 可关闭 [1M 上下文窗口](/docs/zh-CN/model-config#extended-context)支持。Claude Code 会从模型选择器中移除 `[1m]` 模型变体，并将默认以 1M 窗口运行的模型限制为 200K 窗口。请参阅[关闭 1M 上下文](/docs/zh-CN/model-config#turn-off-1m-context)。适用于有合规要求的企业环境。关于它在更正无法识别的 `[1m]` 模型 ID 的窗口方面的作用，请参阅[更正网关或自定义模型 ID 的窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id) |

243| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 设置为 `1` 可在 Opus 4.6 和 Sonnet 4.6 上禁用[自适应推理](/docs/zh-CN/model-config#adjust-effort-level)，并回退到由 `MAX_THINKING_TOKENS` 控制的固定思考预算。对 [Fable 模型](/docs/zh-CN/model-config#extended-thinking)、Sonnet 5 及更高版本、Haiku 5.5 或 Opus 4.7 及更高版本无效，这些模型始终使用自适应推理 |243| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 设置为 `1` 可在 Opus 4.6 和 Sonnet 4.6 上禁用[自适应推理](/docs/zh-CN/model-config#adjust-effort-level)，并回退到由 `MAX_THINKING_TOKENS` 控制的固定思考预算。对始终使用自适应推理的 [Fable 模型](/docs/zh-CN/model-config#extended-thinking)、Sonnet 5 及更高版本、Haiku 5.5 或 Opus 4.7 及更高版本不起作用 |

244| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | 设置为 `1` 可阻止 Claude Code 跨管理员来源按键合并[托管设置](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)的 `env` 块，从而像 v2.1.223 之前那样，只应用优先级最高的来源的整个 `env` 块。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置 `env` 块传递的副本。需要 Claude Code v2.1.223 或更高版本 |244| `CLAUDE_CODE_DISABLE_ADMIN_ENV_UNION` | 设置为 `1` 可阻止 Claude Code 跨管理员来源按键合并[托管设置](/docs/zh-CN/managed-settings#precedence-within-the-managed-tier)的 `env` 块，这样只有优先级最高的来源的整个 `env` 块生效，与 v2.1.223 之前相同。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置 `env` 块下发的副本。需要 Claude Code v2.1.223 或更高版本 |

245| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 设置为 `1` 可禁用 [advisor 工具](/docs/zh-CN/advisor)。`/advisor` 命令将不可用，任何已配置的 `advisorModel` 都会被忽略，`--advisor` 标志仍被接受但不起作用，因此传递该标志的现有脚本可以继续运行而不会出错 |245| `CLAUDE_CODE_DISABLE_ADVISOR_TOOL` | 设置为 `1` 可禁用 [advisor 工具](/docs/zh-CN/advisor)。`/advisor` 命令将不可用，任何已配置的 `advisorModel` 都会被忽略，`--advisor` 标志会被接受但不起作用，因此传递该标志的现有脚本可以继续正常运行而不会报错 |

246| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 设置为 `1` 可关闭[后台 Agent 和 Agent 视图](/docs/zh-CN/agent-view)：`claude agents`、`--bg`、`/background` 以及按需 supervisor。等同于 [`disableAgentView`](/docs/zh-CN/settings-reference#disableagentview) 设置 |246| `CLAUDE_CODE_DISABLE_AGENT_VIEW` | 设置为 `1` 可关闭[后台 Agent 和 Agent 视图](/docs/zh-CN/agent-view)：`claude agents`、`--bg`、`/background` 以及按需启动的 supervisor。等同于 [`disableAgentView`](/docs/zh-CN/settings-reference#disableagentview) 设置 |

247| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 设置为 `1` 可禁用[全屏渲染](/docs/zh-CN/fullscreen)并使用经典的主屏幕渲染器。对话保留在终端的原生回滚缓冲区中，因此 `Cmd+f` 和 tmux 复制模式照常工作。优先于 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/docs/zh-CN/settings-reference#tui) 设置。您也可以使用 `/tui default` 切换。不适用于从 [Agent 视图](/docs/zh-CN/agent-view)打开的后台会话，这些会话始终使用全屏渲染 |247| `CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN` | 设置为 `1` 可禁用[全屏渲染](/docs/zh-CN/fullscreen)并使用经典的主屏幕渲染器。对话会保留在终端的原生回滚缓冲区中，因此 `Cmd+f` 和 tmux 复制模式照常工作。优先于 `CLAUDE_CODE_NO_FLICKER` 和 [`tui`](/docs/zh-CN/settings-reference#tui) 设置。您也可以使用 `/tui default` 进行切换。不适用于从 [Agent 视图](/docs/zh-CN/agent-view)打开的后台会话，这些会话始终使用全屏渲染 |

248| `CLAUDE_CODE_DISABLE_ARTIFACT` | 设置为 `1` 可关闭 [Artifact](/docs/zh-CN/artifacts) 工具，该工具会将会话输出作为私有网页发布到 claude.ai 上。一旦设置，任何设置文件都无法重新启用该工具。如果要改为通过设置文件关闭该工具，请将 [`enableArtifact`](/docs/zh-CN/settings-reference#enableartifact) 设置为 `false`；已弃用的 [`disableArtifact`](/docs/zh-CN/settings-reference#disableartifact) 键也可将其关闭 |248| `CLAUDE_CODE_DISABLE_ARTIFACT` | 设置为 `1` 可关闭 [Artifact](/docs/zh-CN/artifacts) 工具，该工具会将会话输出作为 claude.ai 上的私有网页发布。一旦设置此变量，任何设置文件都无法重新启用该工具。若要改为通过设置文件关闭该工具，请将 [`enableArtifact`](/docs/zh-CN/settings-reference#enableartifact) 设置为 `false`；已弃用的 [`disableArtifact`](/docs/zh-CN/settings-reference#disableartifact) 键也可以关闭它 |

249| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | 设置为 `1` 可禁用附件处理。使用 `@` 语法的文件提及将作为纯文本发送，而不会展开为文件内容 |249| `CLAUDE_CODE_DISABLE_ATTACHMENTS` | 设置为 `1` 可禁用附件处理。使用 `@` 语法的文件引用会作为纯文本发送，而不会展开为文件内容。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略 |

250| `CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK` | 设置为 `1` 可让 Claude Code 进程自行运行其 [`gcpAuthRefresh`](/docs/zh-CN/settings-reference#gcpauthrefresh) 或 [`awsAuthRefresh`](/docs/zh-CN/settings-reference#awsauthrefresh) 命令，而不是在另一个进程运行该命令时等待。需要 Claude Code v2.1.286 或更高版本 |250| `CLAUDE_CODE_DISABLE_AUTH_REFRESH_LOCK` | 设置为 `1` 可使 Claude Code 进程自行运行其 [`gcpAuthRefresh`](/docs/zh-CN/settings-reference#gcpauthrefresh) 或 [`awsAuthRefresh`](/docs/zh-CN/settings-reference#awsauthrefresh) 命令，而不是在另一个进程运行该命令时等待。需要 Claude Code v2.1.286 或更高版本 |

251| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 设置为 `1` 可禁用[自动记忆](/docs/zh-CN/memory#auto-memory)。设置为 `0` 可强制启用自动记忆，即使 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-CN/settings-reference#automemoryenabled) 本会禁用它。禁用后，Claude 不会创建或加载自动记忆文件 |251| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 设置为 `1` 可禁用[自动记忆](/docs/zh-CN/memory#auto-memory)。设置为 `0` 可强制启用自动记忆，即使 `--bare` 模式或 [`autoMemoryEnabled: false`](/docs/zh-CN/settings-reference#automemoryenabled) 原本会禁用它。禁用后，Claude 不会创建或加载自动记忆文件 |

252| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 设置为 `1` 可禁用所有后台任务功能，包括 Bash 和子代理工具上的 `run_in_background` 参数、自动后台化以及 Ctrl+B 快捷键 |252| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 设置为 `1` 可禁用所有后台任务功能，包括 Bash 和子代理工具上的 `run_in_background` 参数、自动后台化以及 Ctrl+B 快捷键 |

253| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 设置为 `1` 可阻止 Claude Code 将缺少 `Content-Type` 标头或该标头为空的 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 流式响应视为 Amazon Bedrock 的二进制事件流。默认情况下，Claude Code 假定是网关从原本未经修改的响应中丢弃了该标头，因此它会解码响应体，流式输出可继续正常工作。仅当网关还会将流重新以服务器发送事件形式发出时才设置此变量；届时 Claude Code 会改为将无标头的响应体读作服务器发送事件。需要 Claude Code v2.1.239 或更高版本 |253| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_DEFAULT` | 设置为 `1` 可阻止 Claude Code 将缺少 `Content-Type` 标头或该标头为空的 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 流式响应视为 Amazon Bedrock 的二进制事件流。默认情况下，Claude Code 会假定是网关从一个原本未修改的响应中删除了该标头，因此会解码响应体，流式输出也能继续工作。仅当网关还会将流重新以服务器发送事件的形式发出时才设置此变量；此时 Claude Code 会将没有标头的响应体作为服务器发送事件读取。需要 Claude Code v2.1.239 或更高版本 |

254| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 设置为 `1` 可跳过对 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 流式响应是否带有 `application/vnd.amazon.eventstream` content-type 的检查。如果不设置此变量，当响应带有不同的 content-type 时，Claude Code 会使请求失败，并显示一条指出该类型的错误，这意味着[网关或代理正在转换响应](/docs/zh-CN/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。请配置网关原样转发 `Content-Type` 标头和响应体，而不是设置此变量。需要 Claude Code v2.1.208 或更高版本 |254| `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` | 设置为 `1` 可跳过对 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 流式响应是否携带 `application/vnd.amazon.eventstream` content-type 的检查。未设置此变量时，如果响应携带不同的 content-type，Claude Code 会使请求失败并给出指明该类型的错误，这表示[网关或代理正在转换响应](/docs/zh-CN/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。请将网关配置为原样转发 `Content-Type` 标头和响应体，而不是设置此变量。需要 Claude Code v2.1.208 或更高版本 |

255| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 设置为 `1` 可在 [supervisor](/docs/zh-CN/agent-view#the-supervisor-process) 停止、重启或更新[后台会话](/docs/zh-CN/agent-view)的进程时，停止该会话正在运行的后台 shell 命令、动态工作流以及（自 v2.1.198 起）后台子代理，而不是将它们移交给该会话的下一个进程。仅影响这一移交：使用 `←` 或 [`/background`](/docs/zh-CN/agent-view#from-inside-a-session) 将会话转入后台时，仍会延续正在进行的工作，而 `CLAUDE_DISABLE_ADOPT` 会同时关闭这两者。需要 Claude Code v2.1.196 或更高版本 |255| `CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF` | 设置为 `1` 后，当 [supervisor](/docs/zh-CN/agent-view#the-supervisor-process) 停止、重启或更新[后台会话](/docs/zh-CN/agent-view)的进程时，会停止该会话正在运行的后台 shell 命令、动态工作流以及（从 v2.1.198 起）后台子代理，而不是将它们移交给该会话的下一个进程。仅影响这种移交：使用 `←` 或 [`/background`](/docs/zh-CN/agent-view#from-inside-a-session) 将会话转入后台时仍会延续进行中的工作，而 `CLAUDE_DISABLE_ADOPT` 会同时关闭这两者。需要 Claude Code v2.1.196 或更高版本 |

256| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 设置为 `1` 可阻止 Claude Code 在内存压力下终止[后台 shell 命令](/docs/zh-CN/interactive-mode#background-bash-commands)。默认情况下，在 macOS 和 Linux 上，当操作系统报告严重内存压力，且会话已空闲 30 分钟、没有正在运行的轮次或子代理时，Claude Code 会终止后台 shell。Windows 没有内存压力信号，因此此变量在 Windows 上无效。需要 Claude Code v2.1.193 或更高版本 |256| `CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP` | 设置为 `1` 可阻止 Claude Code 在内存压力下终止[后台 shell 命令](/docs/zh-CN/interactive-mode#background-bash-commands)。默认情况下，在 macOS 和 Linux 上，当操作系统报告严重内存压力，且会话已空闲 30 分钟、没有正在运行的轮次或子代理时，Claude Code 会终止后台 shell。Windows 没有内存压力信号，因此此变量在 Windows 上不起作用。需要 Claude Code v2.1.193 或更高版本 |

257| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 设置为 `1` 可禁用 Claude Code 随附的 [skill](/docs/zh-CN/skills) 和工作流：随附的 skill 和工作流会被完全移除，而 `/init` 等内置命令仍可输入，但对模型隐藏。`/doctor` 与内置命令一样仍可输入；请改用 `DISABLE_DOCTOR_COMMAND` 将其隐藏。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 skill 不受影响。等同于 [`disableBundledSkills`](/docs/zh-CN/settings-reference#disablebundledskills) 设置 |257| `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` | 设置为 `1` 可禁用 Claude Code 附带的 [skill](/docs/zh-CN/skills) 和工作流：随附 skill 和工作流会被完全移除，而 `/init` 等内置命令仍可输入，但会对模型隐藏。`/doctor` 与内置命令一样仍可输入；请改用 `DISABLE_DOCTOR_COMMAND` 隐藏它。来自插件、`.claude/skills/` 和 `.claude/commands/` 的 skill 不受影响。等同于 [`disableBundledSkills`](/docs/zh-CN/settings-reference#disablebundledskills) 设置 |

258| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 设置为 `1` 可保留 [Claude in Chrome](/docs/zh-CN/chrome) 浏览器工具，同时省略系统提示词中的 Chrome 部分以及 `/claude-in-chrome` [随附 skill](/docs/zh-CN/skills#bundled-skills)。适用于嵌入 Claude Code 并提供自己的浏览器指导的宿主。需要 Claude Code v2.1.257 或更高版本 |258| `CLAUDE_CODE_DISABLE_CFC_PROMPT` | 设置为 `1` 可保留 [Claude in Chrome](/docs/zh-CN/chrome) 浏览器工具，同时省略系统提示词中的 Chrome 部分和 `/claude-in-chrome` [随附 skill](/docs/zh-CN/skills#bundled-skills)。适用于嵌入 Claude Code 并提供自己的浏览器指引的宿主。需要 Claude Code v2.1.257 或更高版本 |

260| `CLAUDE_CODE_DISABLE_CRON` | 设置为 `1` 可禁用[定时任务](/docs/zh-CN/scheduled-tasks)。`/loop` skill 和 cron 工具将不可用，任何已安排的任务都会停止触发，包括会话中途已在运行的任务 |260| `CLAUDE_CODE_DISABLE_CRON` | 设置为 `1` 可禁用[定时任务](/docs/zh-CN/scheduled-tasks)。`/loop` skill 和 cron 工具将不可用，任何已安排的任务都会停止触发，包括在会话中途已在运行的任务 |

261| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | 设置为 `1` 可关闭[关键路径删除](/docs/zh-CN/permission-modes#critical-paths)提示的时间限制。这样，在 `auto` 模式下，Claude Code 会改为将这些删除操作发送给分类器，而在 `bypassPermissions` 模式下，提示会等待您的回答。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置 `env` 块传递的副本。需要 Claude Code v2.1.281 或更高版本 |261| `CLAUDE_CODE_DISABLE_DANGEROUS_RM_TIMEOUT` | 设置为 `1` 可关闭[关键路径删除](/docs/zh-CN/permission-modes#critical-paths)提示的时间限制。此后在 `auto` 模式下，Claude Code 会将这些删除操作发送给分类器；在 `bypassPermissions` 模式下，提示会等待您的回答。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置 `env` 块下发的副本。需要 Claude Code v2.1.281 或更高版本 |

262| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 设置为 `1` 可从 API 请求中剥离预发布的 `anthropic-beta` 请求标头、与之配套的请求体字段，以及 `defer_loading` 和 `eager_input_streaming` 等 beta 工具架构字段。当代理网关以 `anthropic-beta` 标头的 `Unexpected value(s)` 错误或 `Extra inputs are not permitted` 错误拒绝请求时，请使用此选项。[禁用预发布功能](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities)列出了该变量移除的内容（包括 [MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)）以及 Claude Code 仍会发送的内容 |262| `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` | 设置为 `1` 可从 API 请求中去除预发布的 `anthropic-beta` 请求标头、与之配对的请求体字段，以及 `defer_loading` 和 `eager_input_streaming` 等 beta 工具 schema 字段。当代理网关因 `anthropic-beta` 标头报 `Unexpected value(s)` 错误或报 `Extra inputs are not permitted` 错误而拒绝请求时，请使用此变量。[禁用预发布功能](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities)列出了该变量会移除的内容（包括 [MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)）以及 Claude Code 仍会发送的内容 |

263| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 设置为 `1` 可禁用内置的 [Explore 和 Plan 子代理](/docs/zh-CN/sub-agents#built-in-subagents)。Claude 会改用其搜索工具或 general-purpose 子代理进行探索，[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)会直接读取文件，而不是启动 Explore 和 Plan Agent。名为 `Explore` 或 `Plan` 的自定义子代理不受影响。要在 Agent SDK 或非交互模式中移除所有内置子代理类型，请改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更高版本 |263| `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` | 设置为 `1` 可禁用内置的 [Explore 和 Plan 子代理](/docs/zh-CN/sub-agents#built-in-subagents)。Claude 会改用其搜索工具或通用子代理进行探索，[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)会直接读取文件，而不是启动 Explore 和 Plan Agent。名为 `Explore` 或 `Plan` 的自定义子代理不受影响。若要在 Agent SDK 或非交互模式中移除所有内置子代理类型，请改用 `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS`。需要 Claude Code v2.1.198 或更高版本 |

265| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 设置为 `1` 可禁用 "How is Claude doing?" 会话质量调查。当设置了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时，调查也会被禁用，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 重新选择启用。要设置采样率而不是直接禁用，请使用 [`feedbackSurveyRate`](/docs/zh-CN/settings-reference#feedbacksurveyrate) 设置。请参阅[会话质量调查](/docs/zh-CN/data-usage#session-quality-surveys) |265| `CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` | 设置为 `1` 可禁用"How is Claude doing?"会话质量调查。当设置了 `DISABLE_TELEMETRY`、`DO_NOT_TRACK` 或 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` 时，调查也会被禁用，除非 `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` 重新选择启用。若要设置采样率而不是直接禁用，请使用 [`feedbackSurveyRate`](/docs/zh-CN/settings-reference#feedbacksurveyrate) 设置。请参阅[会话质量调查](/docs/zh-CN/data-usage#session-quality-surveys) |

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

267| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 设置为 `1` 可从 Claude 的上下文中移除内置的提交和 PR 工作流指令以及 git 状态快照。在使用您自己的 git 工作流 skill 时很有用。设置后优先于 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions) 设置 |267| `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS` | 设置为 `1` 可从 Claude 的上下文中移除内置的提交和 PR 工作流指令以及 git 状态快照。适用于使用您自己的 git 工作流 skill 的情况。设置后优先于 [`includeGitInstructions`](/docs/zh-CN/settings-reference#includegitinstructions) 设置 |

268| `CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT` | 设置为 `1` 可阻止 Claude Code 读取通过 `-c` 传递给 shell 的脚本（例如 `bash -c 'rm -rf ~'`）来检查[关键路径](/docs/zh-CN/permission-modes#removals-inside-nested-commands-and-inline-scripts)删除操作。Claude Code 仍会检查这些脚本中的 shell 变量和位置参数目标，其他关键路径检查也会继续运行。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置 `env` 块传递的副本。需要 Claude Code v2.1.288 或更高版本 |268| `CLAUDE_CODE_DISABLE_INLINE_SHELL_RM_PROMPT` | 设置为 `1` 可阻止 Claude Code 读取通过 `-c` 传递给 shell 的脚本（例如 `bash -c 'rm -rf ~'`）来检查[关键路径](/docs/zh-CN/permission-modes#removals-inside-nested-commands-and-inline-scripts)删除。Claude Code 仍会检查这些脚本中的 shell 变量和位置参数目标，其他关键路径检查也会继续运行。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置 `env` 块下发的副本。需要 Claude Code v2.1.288 或更高版本 |

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

270| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | 设置为 `1` 可阻止 [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 在您的账户于会话中途失去对会话模型的访问权限时切换到较旧的模型；被拒绝的请求将立即失败。您配置的[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)仍会在该拒绝发生时切换，[启动模型检查](/docs/zh-CN/amazon-bedrock#startup-model-checks)仍会在启动时回退。需要 Claude Code v2.1.285 或更高版本 |270| `CLAUDE_CODE_DISABLE_MODEL_ACCESS_FALLBACK` | 设置为 `1` 可阻止 [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 在您的账户于会话中途失去对会话模型的访问权限时切换到较旧的模型；被拒绝的请求会立即失败。您配置的[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)仍会在该拒绝发生时切换，并且[启动模型检查](/docs/zh-CN/amazon-bedrock#startup-model-checks)仍会在启动时回退。需要 Claude Code v2.1.285 或更高版本 |

271| `CLAUDE_CODE_DISABLE_MOUSE` | 设置为 `1` 可在[全屏渲染](/docs/zh-CN/fullscreen)中禁用鼠标跟踪。使用 `PgUp` 和 `PgDn` 的键盘滚动仍然有效。使用此选项可保留终端原生的选中即复制行为 |271| `CLAUDE_CODE_DISABLE_MOUSE` | 设置为 `1` 可在[全屏渲染](/docs/zh-CN/fullscreen)中禁用鼠标跟踪。使用 `PgUp` 和 `PgDn` 的键盘滚动仍然有效。使用此变量可保留终端的原生选中即复制行为 |

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

273| `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 或更高版本 |273| `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 或更高版本 |

274| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 设置为任何非空值（例如 `1`）可禁用非必要的网络流量：自动更新、遥测、错误报告、`/feedback` 命令、[Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)、发行说明、[PR 和 MR 状态徽章](/docs/zh-CN/interactive-mode#pr-review-status)检查，以及[快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)检查等可用性检查。它还会停止[插件 `command` 来源的后台运行](/docs/zh-CN/plugins/loading#when-a-command-source-re-runs)，这些是本地命令而非网络流量，但它们可能会触发依赖安装。**将其设置为 `0` 或 `false` 仍会禁用此流量**，这与大多数开关变量不同；需取消设置该变量才能再次允许。还会禁用功能标志获取，这会使 [Remote Control](/docs/zh-CN/remote-control#requirements) 和其他[需要获取功能标志的功能](#features-that-need-feature-flag-fetching)不可用。官方插件市场的自动安装不在此范围内；请使用 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 禁用它。不影响[网关模型发现](/docs/zh-CN/llm-gateway-connect#add-gateway-models-to-the-model-picker)，后者有自己的选择启用机制 |274| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 设置为任何非空值（例如 `1`）可禁用非必要的网络流量：自动更新、遥测、错误报告、`/feedback` 命令、[Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)、发行说明、[PR 和 MR 状态徽章](/docs/zh-CN/interactive-mode#pr-review-status)检查，以及[快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)检查等可用性检查。它还会停止[插件 `command` 来源的后台运行](/docs/zh-CN/plugins/loading#when-a-command-source-re-runs)，这些是本地命令而不是网络流量，但它们可能会触发依赖安装。**与大多数开关类变量不同，将其设置为 `0` 或 `false` 仍会禁用此类流量**；取消设置该变量才能重新允许。还会禁用功能标志获取，这会使 [Remote Control](/docs/zh-CN/remote-control#requirements) 以及其他[需要功能标志获取的功能](#features-that-need-feature-flag-fetching)不可用。官方插件市场的自动安装不在此范围内；请使用 `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 禁用它。不影响[网关模型发现](/docs/zh-CN/llm-gateway-connect#add-gateway-models-to-the-model-picker)，后者有其自己的选择启用方式 |

276| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 设置为 `1` 可在您正在终端中输入或终端处于焦点时，仍然发送 `PushNotification` 工具的桌面通知。默认情况下，当该工具检测到最近的键盘活动或终端焦点时，会同时跳过桌面通知和[移动推送](/docs/zh-CN/remote-control#mobile-push-notifications)。此变量仅禁用该本地检查，因此当服务器检测到您处于活动状态时，仍可抑制移动推送。需要 Claude Code v2.1.193 或更高版本 |276| `CLAUDE_CODE_DISABLE_NOTIFICATION_PRESENCE_CHECK` | 设置为 `1` 可使 `PushNotification` 工具即使在您正在终端中输入或终端处于焦点时也发送桌面通知。默认情况下，当该工具检测到最近的键盘活动或终端焦点时，会同时跳过桌面通知和[移动推送](/docs/zh-CN/remote-control#mobile-push-notifications)。此变量仅禁用该本地检查，因此当服务器检测到您处于活动状态时，仍可以抑制移动推送。需要 Claude Code v2.1.193 或更高版本 |

277| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 设置为 `1` 可禁用官方插件市场的自动注册。Claude Code 在即将注册该市场时读取此变量，通常是在计算机首次交互式启动期间。如果此时设置了该变量，Claude Code 会永久跳过注册。之后取消设置该变量不会撤销此跳过。随时运行 `claude plugin marketplace add anthropics/claude-plugins-official` 即可注册该市场 |277| `CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` | 设置为 `1` 可禁用官方插件市场的自动注册。Claude Code 在即将注册该市场时读取此变量，通常是在机器首次交互式启动期间。如果此时设置了该变量，Claude Code 会永久跳过注册。之后取消设置该变量不会撤销此跳过。您可以随时运行 `claude plugin marketplace add anthropics/claude-plugins-official` 来注册该市场 |

278| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 设置为 `1` 可阻止 Claude Code 运行您的[针对未回答权限请求的 `Notification` hook](/docs/zh-CN/hooks#notification)，仅适用于 Claude Code 将这些请求发送到 Agent SDK 的 `canUseTool` 回调的会话，Claude Desktop 和 VS Code 扩展就是以这种方式托管 Claude Code 的。在终端会话中无效。需要 Claude Code v2.1.233 或更高版本 |278| `CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS` | 设置为 `1` 可阻止 Claude Code 在将未回答的权限请求发送到 Agent SDK 的 `canUseTool` 回调的会话中运行您的[针对未回答权限请求的 `Notification` hook](/docs/zh-CN/hooks#notification)，Claude Desktop 和 VS Code 扩展就是以这种方式托管 Claude Code 的。在终端会话中不起作用。需要 Claude Code v2.1.233 或更高版本 |

280| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | 设置为 `1` 可关闭 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)的一项检查，该检查会拒绝对[系统路径](/docs/zh-CN/permission-modes#remove-item-in-powershell)（例如驱动器根目录或您的主目录）使用 `cmd` 内置命令 `rd`、`rmdir`、`del` 和 `erase`。Claude Code 会忽略设置文件 `env` 块中的此变量。需要 Claude Code v2.1.283 或更高版本 |280| `CLAUDE_CODE_DISABLE_POWERSHELL_CMD_RM_DENY` | 设置为 `1` 可关闭 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)的一项检查，该检查会拒绝在[系统路径](/docs/zh-CN/permission-modes#remove-item-in-powershell)（例如驱动器根目录或您的主目录）上使用 `cmd` 内置命令 `rd`、`rmdir`、`del` 和 `erase`。Claude Code 会忽略设置文件 `env` 块中的此变量。需要 Claude Code v2.1.283 或更高版本 |

281| `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK` | 设置为 `1` 可关闭[安全分类器标记请求时的自动模型切换](/docs/zh-CN/model-config#automatic-model-fallback)，即 [`switchModelsOnFlag`](/docs/zh-CN/settings-reference#switchmodelsonflag) 设置所控制的行为 |281| `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK` | 设置为 `1` 可关闭[安全分类器标记请求时的自动模型切换](/docs/zh-CN/model-config#automatic-model-fallback)，即 [`switchModelsOnFlag`](/docs/zh-CN/settings-reference#switchmodelsonflag) 设置所控制的行为 |

282| `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS` | 设置为 `1` 可阻止 Claude Code 发送结构化输出的 `output_config.format` 字段以及与之配套的 `anthropic-beta` 值，适用于其上游会拒绝它们的 [LLM 网关](/docs/zh-CN/llm-gateway-protocol#feature-pass-through)。这会保留 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities) 所关闭的其他预发布功能。需要 Claude Code v2.1.288 或更高版本 |282| `CLAUDE_CODE_DISABLE_STRUCTURED_OUTPUTS` | 设置为 `1` 可阻止 Claude Code 发送结构化输出的 `output_config.format` 字段及与之配对的 `anthropic-beta` 值，适用于上游会拒绝这些内容的 [LLM 网关](/docs/zh-CN/llm-gateway-protocol#feature-pass-through)。这会保留 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS`](/docs/zh-CN/llm-gateway-protocol#disable-pre-release-capabilities) 所关闭的其他预发布功能。需要 Claude Code v2.1.288 或更高版本 |

283| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | 设置为 `1` 可关闭针对目标完全来自命令替换输出的递归 `rm`（例如 `rm -rf "$(pwd)"`）的[关键路径](/docs/zh-CN/permission-modes#critical-paths)检查。其他关键路径检查会继续运行。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置 `env` 块传递的副本。需要 Claude Code v2.1.281 或更高版本 |283| `CLAUDE_CODE_DISABLE_SUBSTITUTION_RM_PROMPT` | 设置为 `1` 可关闭对目标完全来自命令替换输出的递归 `rm`（例如 `rm -rf "$(pwd)"`）的[关键路径](/docs/zh-CN/permission-modes#critical-paths)检查。其他关键路径检查会继续运行。请在启动 Claude Code 的环境中设置它，因为 Claude Code 会忽略通过设置 `env` 块下发的副本。需要 Claude Code v2.1.281 或更高版本 |

284| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 设置为 `1` 可禁用基于对话上下文的自动终端标题更新。这也会跳过用于[生成会话标题](/docs/zh-CN/sessions#name-your-sessions)的后台小型/快速模型请求 |284| `CLAUDE_CODE_DISABLE_TERMINAL_TITLE` | 设置为 `1` 可禁用基于对话上下文的终端标题自动更新。这也会跳过用于[生成会话标题](/docs/zh-CN/sessions#name-your-sessions)的后台小型/快速模型请求 |

285| `CLAUDE_CODE_DISABLE_THINKING` | 设置为 `1` 可从 API 请求中完全省略 `thinking` 参数。这是针对会拒绝该参数的代理和网关的兼容性选项。在默认进行思考的模型上，省略该参数意味着模型仍可能进行思考。要在 Anthropic API 上明确禁用[扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，请改用 `MAX_THINKING_TOKENS=0`。这两个变量都无法在 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 模型上关闭思考，这些模型不支持关闭思考。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，`MAX_THINKING_TOKENS=0` 同样会省略该参数，因此这两个变量在那里的行为相同 |285| `CLAUDE_CODE_DISABLE_THINKING` | 设置为 `1` 可从 API 请求中完全省略 `thinking` 参数。这是为拒绝该参数的代理和网关提供的兼容性选项。在默认进行思考的模型上，省略该参数意味着模型仍可能进行思考。若要在 Anthropic API 上显式禁用[扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)，请改用 `MAX_THINKING_TOKENS=0`。这两个变量都无法在 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 模型上关闭思考，这些模型无法关闭思考。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，`MAX_THINKING_TOKENS=0` 同样会省略该参数，因此这两个变量在那里的行为相同 |

286| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 设置为 `1` 可在 Claude Code 无法识别模型 ID（例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名）时跳过主动[自动压缩](/docs/zh-CN/costs#reduce-token-usage)。如果不设置此变量，Claude Code 会按照它为该 ID 假定的上下文窗口进行压缩。`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 可以改为修正假定的窗口；有关各变量的适用情况，请参阅[为网关或自定义模型 ID 修正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。需要 Claude Code v2.1.223 或更高版本 |286| `CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT` | 设置为 `1` 可在 Claude Code 无法识别模型 ID（例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名）时跳过主动[自动压缩](/docs/zh-CN/costs#reduce-token-usage)。未设置此变量时，Claude Code 会按其为该 ID 假定的上下文窗口进行压缩。`CLAUDE_CODE_MAX_CONTEXT_TOKENS` 则可以更正假定的窗口；关于各变量的适用情况，请参阅[更正网关或自定义模型 ID 的窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。需要 Claude Code v2.1.223 或更高版本 |

287| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 设置为 `1` 可在[全屏渲染](/docs/zh-CN/fullscreen)中禁用虚拟滚动，并渲染会话记录中的每条消息。如果在全屏模式下滚动时，应显示消息的位置出现空白区域，请使用此选项 |287| `CLAUDE_CODE_DISABLE_VIRTUAL_SCROLL` | 设置为 `1` 可在[全屏渲染](/docs/zh-CN/fullscreen)中禁用虚拟滚动，并渲染会话记录中的每条消息。如果在全屏模式下滚动时，本应显示消息的位置出现空白区域，请使用此变量 |

288| `CLAUDE_CODE_DISABLE_WEB_FETCH` | 设置为 `1` 可关闭 [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior) 工具。[WebSearch](/docs/zh-CN/tools-reference#websearch-tool-behavior) 工具仍然可用。需要 Claude Code v2.1.285 或更高版本 |288| `CLAUDE_CODE_DISABLE_WEB_FETCH` | 设置为 `1` 可关闭 [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior) 工具。[WebSearch](/docs/zh-CN/tools-reference#websearch-tool-behavior) 工具仍然可用。需要 Claude Code v2.1.285 或更高版本 |

289| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | 设置为 `1` 可在 Windows 上直接启动 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)命令，而不是通过 `cmd.exe` 启动器启动。默认情况下，该启动器可让[在后台运行](/docs/zh-CN/tools-reference#background-commands)的 PowerShell 命令[延续到会话的下一个进程](/docs/zh-CN/agent-view#the-supervisor-process)，例如当您[将会话转入后台](/docs/zh-CN/agent-view#from-inside-a-session)时。如果设置此变量，转入后台的 PowerShell 命令会在会话进程退出时停止。Bash 命令不受影响。需要 Claude Code v2.1.269 或更高版本 |289| `CLAUDE_CODE_DISABLE_WINDOWS_SHELL_LAUNCHER` | 设置为 `1` 可在 Windows 上直接启动 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)命令，而不是通过 `cmd.exe` 启动器启动。默认情况下，该启动器使[在后台运行](/docs/zh-CN/tools-reference#background-commands)的 PowerShell 命令能够[延续到会话的下一个进程](/docs/zh-CN/agent-view#the-supervisor-process)，例如在您[将会话转入后台](/docs/zh-CN/agent-view#from-inside-a-session)时。如果设置了该变量，后台运行的 PowerShell 命令会在会话进程退出时停止。Bash 命令不受影响。需要 Claude Code v2.1.269 或更高版本 |

290| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 设置为 `1` 可禁用[工作流](/docs/zh-CN/workflows#turn-workflows-off)。等同于 [`disableWorkflows`](/docs/zh-CN/settings-reference#disableworkflows) 设置 |290| `CLAUDE_CODE_DISABLE_WORKFLOWS` | 设置为 `1` 可禁用[工作流](/docs/zh-CN/workflows#turn-workflows-off)。等同于 [`disableWorkflows`](/docs/zh-CN/settings-reference#disableworkflows) 设置 |

291| `CLAUDE_CODE_EFFORT_LEVEL` | 为支持的模型设置 effort 级别。可选值：`low`、`medium`、`high`、`xhigh`、`max`，或 `auto` 以使用模型默认值。可用级别取决于模型。优先于 `--effort`、`/effort` 以及 `modelSettings` 和 `effortLevel` 设置。[`maxEffortLevel`](/docs/zh-CN/settings-reference#maxeffortlevel) 上限仍然适用。请参阅[调整 effort 级别](/docs/zh-CN/model-config#adjust-effort-level) |291| `CLAUDE_CODE_EFFORT_LEVEL` | 为受支持的模型设置 effort 级别。取值：`low`、`medium`、`high`、`xhigh`、`max`，或 `auto` 以使用模型默认值。可用级别取决于模型。优先于 `--effort`、`/effort` 以及 `modelSettings` 和 `effortLevel` 设置。[`maxEffortLevel`](/docs/zh-CN/settings-reference#maxeffortlevel) 上限仍然适用。请参阅[调整 effort 级别](/docs/zh-CN/model-config#adjust-effort-level) |

292| `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS` | 设置为 `1` 可向消息流中添加携带会话状态的 [`session_state_changed`](/docs/zh-CN/agent-sdk/typescript#sdksessionstatechangedmessage) 消息。需要使用 [Agent SDK](/docs/zh-CN/agent-sdk/overview)，或者同时使用 `--print`、`--output-format stream-json` 和 `--verbose` |292| `CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS` | 设置为 `1` 可将携带会话状态的 [`session_state_changed`](/docs/zh-CN/agent-sdk/typescript#sdksessionstatechangedmessage) 消息添加到消息流中。需要使用 [Agent SDK](/docs/zh-CN/agent-sdk/overview)，或同时使用 `--print`、`--output-format stream-json` 和 `--verbose` |

293| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 为兼容旧版本而保留，不起任何作用。自动模式默认在所有提供商上可用，包括 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 以及已登录的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话。在 v2.1.158 至 v2.1.206 中，需要将其设置为 `1` 才能在这些提供商上使用[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) |293| `CLAUDE_CODE_ENABLE_AUTO_MODE` | 为兼容旧版本而保留，不产生任何效果。自动模式在所有提供商上默认可用，包括 Amazon Bedrock、Google Cloud's Agent Platform、Microsoft Foundry 以及已登录的 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话。在 v2.1.158 至 v2.1.206 中，需要将其设置为 `1` 才能在这些提供商上使用[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode) |

294| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆盖[会话回顾](/docs/zh-CN/interactive-mode#session-recap)的可用性。设置为 `0` 可强制关闭回顾，无论 `/config` 开关如何。设置为 `1` 可在 [`awaySummaryEnabled`](/docs/zh-CN/settings-reference#awaysummaryenabled) 为 `false` 时强制开启回顾。优先于该设置和 `/config` 开关 |294| `CLAUDE_CODE_ENABLE_AWAY_SUMMARY` | 覆盖[会话回顾](/docs/zh-CN/interactive-mode#session-recap)的可用性。设置为 `0` 可强制关闭回顾，无论 `/config` 开关如何。设置为 `1` 可在 [`awaySummaryEnabled`](/docs/zh-CN/settings-reference#awaysummaryenabled) 为 `false` 时强制开启回顾。优先于该设置和 `/config` 开关 |

295| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 设置为 `1` 可在[非交互模式](/docs/zh-CN/headless)下后台安装完成后，在轮次边界刷新插件状态。默认关闭，因为刷新会在会话中途更改系统提示词，从而使该轮次的[提示缓存](/docs/zh-CN/prompt-caching)失效 |295| `CLAUDE_CODE_ENABLE_BACKGROUND_PLUGIN_REFRESH` | 设置为 `1` 可在[非交互模式](/docs/zh-CN/headless)下后台安装完成后，于轮次边界刷新插件状态。默认关闭，因为刷新会在会话中途更改系统提示词，导致该轮次的[提示缓存](/docs/zh-CN/prompt-caching)失效 |

296| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 设置为 `1` 可在发往 Anthropic 的非必要流量被阻止时，将“How is Claude doing?”会话质量调查路由到您自己的 [OpenTelemetry collector](/docs/zh-CN/monitoring-usage)。调查评分仅作为 OTEL 事件发送到您配置的 collector。在此模式下不会向 Anthropic 发送任何调查数据。在设置了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 时适用，否则不起作用。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和组织产品反馈策略优先 |296| `CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL` | 设置为 `1` 可在发往 Anthropic 的非必要流量被阻止时，将 "How is Claude doing?" 会话质量调查路由到您自己的 [OpenTelemetry 收集器](/docs/zh-CN/monitoring-usage)。调查评分仅作为 OTEL 事件发送到您配置的收集器。在此模式下，不会向 Anthropic 发送任何调查数据。仅在设置了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY` 或 `DO_NOT_TRACK` 时适用，否则不产生任何效果。`CLAUDE_CODE_DISABLE_FEEDBACK_SURVEY` 和组织产品反馈策略优先 |

297| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具调用输入是否在 Claude 生成时从 API 流式传输。关闭后，大型工具输入（例如长文件写入）只有在 Claude 生成完毕后才会到达，看起来可能像是卡住了。在 Anthropic API 上默认启用。在 Amazon Bedrock 和 Google Cloud's Agent Platform 上，在已部署容器支持的模型上按模型启用。设置为 `0` 可选择退出。通过 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 经由代理路由时，设置为 `1` 可强制启用。在 Microsoft Foundry 和[网关](/docs/zh-CN/llm-gateway)连接上默认关闭 |297| `CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING` | 控制工具调用输入是否在 Claude 生成时从 API 流式传输。关闭时，较大的工具输入（例如长文件写入）只有在 Claude 完成生成后才会到达，这可能看起来像是卡住了。在 Anthropic API 上默认启用。在 Amazon Bedrock 和 Google Cloud's Agent Platform 上，在部署的容器支持的情况下按模型启用。设置为 `0` 可选择退出。通过 `ANTHROPIC_BASE_URL`、`ANTHROPIC_VERTEX_BASE_URL` 或 `ANTHROPIC_BEDROCK_BASE_URL` 经由代理路由时，设置为 `1` 可强制开启。在 Microsoft Foundry 和[网关](/docs/zh-CN/llm-gateway)连接上默认关闭 |

298| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 当 `ANTHROPIC_BASE_URL` 指向与 Anthropic 兼容的网关（例如 LiteLLM、Kong 或内部代理）时，设置为 `1` 可从网关的 `/v1/models` 端点填充 `/model` 选择器。默认关闭，因为否则由共享 API 密钥支持的网关会向每个用户显示该密钥可访问的所有模型。发现的模型仍会按会话收到的 [`availableModels`](/docs/zh-CN/settings-reference#availablemodels) 允许列表进行筛选；请通过 [MDM 或托管设置文件](/docs/zh-CN/managed-settings#delivery-mechanisms)下发该列表，因为[网关配置不支持服务器托管下发](/docs/zh-CN/server-managed-settings#platform-availability) |298| `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` | 当 `ANTHROPIC_BASE_URL` 指向与 Anthropic 兼容的网关（例如 LiteLLM、Kong 或内部代理）时，设置为 `1` 可从网关的 `/v1/models` 端点填充 `/model` 选择器。默认关闭，因为否则由共享 API 密钥支持的网关会向每个用户显示该密钥可访问的所有模型。发现的模型仍会经过会话收到的 [`availableModels`](/docs/zh-CN/settings-reference#availablemodels) 允许列表过滤；请通过 [MDM 或托管设置文件](/docs/zh-CN/managed-settings#delivery-mechanisms)下发该列表，因为[网关配置不支持服务器托管下发](/docs/zh-CN/server-managed-settings#platform-availability) |

300| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 设置为 `false` 可关闭提示词建议，即出现在输入框中的灰色预测内容。优先于 [`promptSuggestionEnabled`](/docs/zh-CN/settings-reference#promptsuggestionenabled) 设置，`/config` 中的 **Prompt suggestions** 开关写入的正是该设置。当您的账户接近或达到用量限制时，Claude Code 也会[暂停建议](/docs/zh-CN/interactive-mode#when-claude-code-skips-suggestions)。设置为 `true` 可使建议保持开启，直到达到限制。需要 Claude Code v2.1.238 或更高版本。请参阅[提示词建议](/docs/zh-CN/interactive-mode#prompt-suggestions) |300| `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION` | 设置为 `false` 可关闭提示词建议，即出现在输入框中的灰色预测内容。优先于 [`promptSuggestionEnabled`](/docs/zh-CN/settings-reference#promptsuggestionenabled) 设置，即 `/config` 中 **Prompt suggestions** 开关所写入的设置。当您的账户接近或达到用量限制时，Claude Code 也会[暂停建议](/docs/zh-CN/interactive-mode#when-claude-code-skips-suggestions)。设置为 `true` 可使建议保持开启，直到您达到限制。需要 Claude Code v2.1.238 或更高版本。请参阅[提示词建议](/docs/zh-CN/interactive-mode#prompt-suggestions) |

301| `CLAUDE_CODE_ENABLE_TASKS` | 选择 Claude Code 在[具备任务跟踪工具的会话](/docs/zh-CN/tools-reference#task-tool-availability)中提供哪些任务跟踪工具。默认情况下，Claude Code 提供 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 和 `TaskList`。设置为 `0` 可改用旧版 `TodoWrite` 工具。请参阅[任务列表](/docs/zh-CN/interactive-mode#task-list) |301| `CLAUDE_CODE_ENABLE_TASKS` | 选择 Claude Code 在[具备任务跟踪工具的会话](/docs/zh-CN/tools-reference#task-tool-availability)中提供哪种任务跟踪工具。默认情况下，Claude Code 提供 Task 工具 `TaskCreate`、`TaskUpdate`、`TaskGet` 和 `TaskList`。设置为 `0` 可改用旧版 `TodoWrite` 工具。请参阅[任务列表](/docs/zh-CN/interactive-mode#task-list) |

302| `CLAUDE_CODE_ENABLE_TELEMETRY` | 设置为 `1` 可启用用于指标和日志记录的 OpenTelemetry 数据收集。在配置 OTel 导出器之前必须设置。可在 shell、用户设置或托管设置中设置。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略。请参阅[监控](/docs/zh-CN/monitoring-usage) |302| `CLAUDE_CODE_ENABLE_TELEMETRY` | 设置为 `1` 可启用用于指标和日志记录的 OpenTelemetry 数据收集。配置 OTel 导出器之前必须设置。请在您的 shell、用户设置或托管设置中设置。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略。请参阅[监控](/docs/zh-CN/monitoring-usage) |

303| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 设置为 `1` 可在所有模型上获得任务跟踪工具。如果不设置，Claude Code 默认仅在 [Task 工具可用性](/docs/zh-CN/tools-reference#task-tool-availability)下列出的模型上提供这些工具。`CLAUDE_CODE_ENABLE_TASKS` 仍用于选择 Task 工具或 `TodoWrite`。需要 Claude Code v2.1.233 或更高版本 |303| `CLAUDE_CODE_ENABLE_TODO_TOOLS` | 设置为 `1` 可在所有模型上获得任务跟踪工具。未设置时，Claude Code 默认仅在 [Task 工具可用性](/docs/zh-CN/tools-reference#task-tool-availability)下列出的模型上提供这些工具。`CLAUDE_CODE_ENABLE_TASKS` 仍用于选择 Task 工具或 `TodoWrite`。需要 Claude Code v2.1.233 或更高版本 |

306| `CLAUDE_CODE_EXTRA_BODY` | 要合并到每个 API 请求正文顶层的 JSON 对象。适用于传递 Claude Code 未直接公开的提供商特定参数。在 shell 中导出的值也适用于您通过 `claude agents` 或 `--bg` 派发的[后台会话](/docs/zh-CN/agent-view)。在 v2.1.206 之前，后台会话会忽略 shell 导出的值，而使用后台监管进程所继承的副本 |306| `CLAUDE_CODE_EXTRA_BODY` | 要合并到每个 API 请求体顶层的 JSON 对象。适用于传递 Claude Code 未直接公开的特定于提供商的参数。在您的 shell 中导出的值也适用于您通过 `claude agents` 或 `--bg` 分派的[后台会话](/docs/zh-CN/agent-view)。在 v2.1.206 之前，后台会话会忽略 shell 导出的值，而使用后台监督进程继承的副本 |

308| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 设置为 `1` 可强制持久化会话记录、提示词历史并注册到 `claude agents`，即使该 `claude` 是从另一个 Claude Code 会话内部启动的。当继承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如来自 `screen` 会话，或最初由 Claude Code 的 Bash 工具启动的后台启动器）导致真正的顶层会话被误判为嵌套会话时使用。自 v2.1.178 起，Claude Code 会自动检测 tmux 的情况并忽略继承的标记，因此 tmux 不再需要此变量。在 v2.1.169 及更早版本中同样有效；在 v2.1.170 和 v2.1.171 中不起作用，因为这两个版本移除了它所覆盖的嵌套会话检测 |308| `CLAUDE_CODE_FORCE_SESSION_PERSISTENCE` | 设置为 `1` 可强制保留会话记录、提示词历史并进行 `claude agents` 注册，即使此 `claude` 是从另一个 Claude Code 会话内部启动的。当继承的 `CLAUDE_CODE_CHILD_SESSION` 值（例如来自 `screen` 会话，或最初由 Claude Code 的 Bash 工具启动的后台启动器）导致真正的顶层会话被误判为嵌套会话时使用。自 v2.1.178 起，Claude Code 会自动检测 tmux 的情况并忽略继承的标记，因此 tmux 不再需要此变量。在 v2.1.169 及更早版本中同样有效；在 v2.1.170 和 v2.1.171 中无效，因为这两个版本移除了它所覆盖的嵌套会话检测 |

309| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 设置为 `1` 可在终端支持但未被自动检测到时（例如通过 SSH 且未转发 `TERM_PROGRAM`），强制将 Claude 回复中的 `~~text~~` 渲染为删除线。如果不设置，未被检测到的终端会显示字面的 `~~` 标记，而不会将文本渲染为删除线。需要 Claude Code v2.1.186 或更高版本 |309| `CLAUDE_CODE_FORCE_STRIKETHROUGH` | 当您的终端支持删除线但未被自动检测到时（例如通过 SSH 且未转发 `TERM_PROGRAM`），设置为 `1` 可强制将 Claude 回复中的 `~~text~~` 渲染为删除线。如果不设置，未被检测到的终端会显示字面的 `~~` 标记，而不是将文本渲染为删除线。需要 Claude Code v2.1.186 或更高版本 |

310| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 设置为 `1` 可在终端支持但未被自动检测到时，强制启用 DEC 私有模式 2026 [同步输出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)。适用于 Emacs `eat` 等实现了 BSU/ESU 但不响应能力探测的终端模拟器。在 tmux 下不起作用。与切换到[全屏渲染](/docs/zh-CN/fullscreen)的 `CLAUDE_CODE_NO_FLICKER` 不同，此变量不会更改渲染器 |310| `CLAUDE_CODE_FORCE_SYNC_OUTPUT` | 当您的终端支持 DEC 私有模式 2026 [同步输出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)但未被自动检测到时，设置为 `1` 可强制启用。适用于实现了 BSU/ESU 但不响应能力探测的模拟器，例如 Emacs `eat`。在 tmux 下无效。与切换到[全屏渲染](/docs/zh-CN/fullscreen)的 `CLAUDE_CODE_NO_FLICKER` 不同，此变量不会更改渲染器 |

311| `CLAUDE_CODE_FORK_SUBAGENT` | 控制[分叉模式](/docs/zh-CN/sub-agents#turn-fork-mode-on-or-off)，该模式允许 Claude 自行生成[分叉子代理](/docs/zh-CN/sub-agents#fork-the-current-conversation)，默认仅在交互式会话中开启。设置为 `1` 可同时在 `claude -p` 和 Agent SDK 中开启，设置为 `0` 可在所有类型的会话中关闭。无论分叉模式是否开启，您都可以运行 `/subtask`。交互式会话中的默认开启需要 Claude Code v2.1.232 或更高版本；在更早的版本中，请将该变量设置为 `1` 以开启分叉模式 |311| `CLAUDE_CODE_FORCE_TERMINAL_IMAGES` | 当您的终端使用 Unicode 占位符绘制 kitty 图形协议图像但未被自动检测到时，设置为 `1` 可将 [mod `Image` 元素](/docs/zh-CN/plugins/mods/reference#elements)绘制为图片。请参阅 [Claude Code 会检测哪些终端](/docs/zh-CN/plugins/mods/gallery#image-and-client)，以及为什么它在 tmux 或 screen 中无效 |

312| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | 设置为 `1` 可在 `claude -p --output-format stream-json` 输出中发出[子代理](/docs/zh-CN/sub-agents)的文本和思考块，行为与 [`--forward-subagent-text`](/docs/zh-CN/cli-reference#cli-flags) 标志相同。当调用 `claude` 的框架无法自行传递该标志时，请使用此变量。该标志在非交互模式且使用 stream-json 输出之外会报错退出，而此变量在这些情况下会被忽略，因此在进程范围内设置它时，嵌套调用仍能正常工作。需要 Claude Code v2.1.211 或更高版本 |312| `CLAUDE_CODE_FORK_SUBAGENT` | 控制[分叉模式](/docs/zh-CN/sub-agents#turn-fork-mode-on-or-off)，该模式允许 Claude 自行生成[分叉子代理](/docs/zh-CN/sub-agents#fork-the-current-conversation)，默认仅在交互式会话中开启。设置为 `1` 可在 `claude -p` 和 Agent SDK 中也开启，设置为 `0` 可在所有类型的会话中关闭。无论分叉模式是否开启，您都可以运行 `/subtask`。交互式默认值需要 Claude Code v2.1.232 或更高版本；在更早的版本中，请将该变量设置为 `1` 以开启分叉模式 |

313| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 设置为 `1` 可在自定义代理或第三方提供商（例如 Amazon Bedrock 或 Claude Platform on AWS）上发送[网关提示标头](/docs/zh-CN/llm-gateway-protocol#gateway-hint-headers)，例如 `x-claude-code-request-class` 和 `x-claude-code-compaction`。设置为 `0` 可在所有连接上停止发送这些标头，包括直接连接到 Anthropic API 的情况，Claude Code 默认会在此类连接上发送它们。需要 Claude Code v2.1.273 或更高版本 |313| `CLAUDE_CODE_FORWARD_SUBAGENT_TEXT` | 设置为 `1` 可在 `claude -p --output-format stream-json` 输出中发出[子代理](/docs/zh-CN/sub-agents)文本和思考块，与 [`--forward-subagent-text`](/docs/zh-CN/cli-reference#cli-flags) 标志的行为相同。当调用 `claude` 的工具框架无法自行传递该标志时，请使用该变量。该标志在非交互模式且使用 stream-json 输出以外的情况下会报错退出，而该变量在这些情况下会被忽略，以便在进程范围内设置时嵌套调用仍能正常工作。需要 Claude Code v2.1.211 或更高版本 |

314| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | 由 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` 开启的[网关模型发现](/docs/zh-CN/llm-gateway-protocol#model-discovery)请求的超时时间（毫秒）（默认值：`3000`）。当您的网关在启动时需要超过三秒才能响应 `/v1/models` 时，请调高此值。仅接受纯数字；`0`、负值和其他写法将保留默认值。需要 Claude Code v2.1.269 或更高版本 |314| `CLAUDE_CODE_GATEWAY_HINT_HEADERS` | 设置为 `1` 可在自定义代理或第三方提供商（例如 Amazon Bedrock 或 Claude Platform on AWS）上发送[网关提示标头](/docs/zh-CN/llm-gateway-protocol#gateway-hint-headers)，例如 `x-claude-code-request-class` 和 `x-claude-code-compaction`。设置为 `0` 可在所有连接上停止发送这些标头，包括直接连接到 Anthropic API 的情况（Claude Code 默认在此情况下发送）。需要 Claude Code v2.1.273 或更高版本 |

315| `CLAUDE_CODE_GIT_BASH_PATH` | 仅限 Windows：Git Bash 可执行文件（`bash.exe`）的路径。当已安装 Git Bash 但其不在 PATH 中时使用。如果该路径不存在，或文件名不是 `bash.exe`、`sh.exe`、`bash` 或 `sh`，Claude Code 会忽略该变量并像未设置一样自动检测 Git Bash，同时记录一条可通过 `--debug` 查看的警告。在 v2.1.219 之前，路径不存在时 Claude Code 会在启动时退出，并且会将任何已存在的文件用作 shell，而不检查它是否为 bash 或 sh。请参阅 [Windows 设置](/docs/zh-CN/setup#set-up-on-windows) |315| `CLAUDE_CODE_GATEWAY_MODEL_DISCOVERY_TIMEOUT_MS` | 由 `CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY` 开启的[网关模型发现](/docs/zh-CN/llm-gateway-protocol#model-discovery)请求的超时时间（毫秒）（默认：`3000`）。当您的网关在启动时需要超过三秒才能响应 `/v1/models` 时，请调高该值。仅接受纯数字；`0`、负值及其他写法会保留默认值。需要 Claude Code v2.1.269 或更高版本 |

316| `CLAUDE_CODE_GIT_BASH_PATH` | 仅限 Windows：Git Bash 可执行文件（`bash.exe`）的路径。当 Git Bash 已安装但不在您的 PATH 中时使用。如果该路径不存在，或文件名不是 `bash.exe`、`sh.exe`、`bash` 或 `sh`，Claude Code 会忽略该变量并像未设置一样自动检测 Git Bash，同时记录一条使用 `--debug` 可见的警告。在 v2.1.219 之前，路径不存在时 Claude Code 会在启动时退出，并且会将任何现有文件用作 shell，而不检查它是否为 bash 或 sh。请参阅 [Windows 设置](/docs/zh-CN/setup#set-up-on-windows) |

316| `CLAUDE_CODE_GLOB_HIDDEN` | 设置为 `false` 可在 Claude 调用 [Glob 工具](/docs/zh-CN/tools-reference#glob-tool-behavior)时从结果中排除点文件。默认包含。不影响 `@` 文件自动补全、`ls`、Grep 或 Read |317| `CLAUDE_CODE_GLOB_HIDDEN` | 设置为 `false` 可在 Claude 调用 [Glob 工具](/docs/zh-CN/tools-reference#glob-tool-behavior)时从结果中排除点文件。默认包含。不影响 `@` 文件自动补全、`ls`、Grep 或 Read |

317| `CLAUDE_CODE_GLOB_NO_IGNORE` | 设置为 `false` 可使 [Glob 工具](/docs/zh-CN/tools-reference#glob-tool-behavior)遵循 `.gitignore` 模式。默认情况下，Glob 返回所有匹配的文件，包括被 gitignore 忽略的文件。不影响 `@` 文件自动补全，后者有自己的 [`respectGitignore` 设置](/docs/zh-CN/settings-reference#respectgitignore) |318| `CLAUDE_CODE_GLOB_NO_IGNORE` | 设置为 `false` 可让 [Glob 工具](/docs/zh-CN/tools-reference#glob-tool-behavior)遵循 `.gitignore` 模式。默认情况下，Glob 返回所有匹配的文件，包括被 gitignore 忽略的文件。不影响 `@` 文件自动补全，后者有自己的 [`respectGitignore` 设置](/docs/zh-CN/settings-reference#respectgitignore) |

319| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 后台工作可以让活动目标等待多少分钟，之后 Claude Code 会[请 Claude 检查该目标](/docs/zh-CN/goal#background-work-defers-evaluation)。默认值 `30`。设置为 `0` 可关闭检查。请以纯数字给出整分钟数，最大为 `10080`，即一周。Claude Code 会将任何其他值视为未设置并使用默认值。需要 Claude Code v2.1.234 或更高版本 |320| `CLAUDE_CODE_GOAL_CHECKIN_MINUTES` | 后台工作可以让活动目标等待多少分钟，之后 Claude Code 会[要求 Claude 检查它](/docs/zh-CN/goal#background-work-defers-evaluation)。默认 `30`。设置为 `0` 可关闭检查。请以纯数字给出整分钟数，最大为 `10080`，即一周。Claude Code 会将任何其他值视为未设置并使用默认值。需要 Claude Code v2.1.234 或更高版本 |

320| `CLAUDE_CODE_GZIP_REQUEST_BODIES` | 设置为 `0` 可关闭对发送到 `api.anthropic.com` 的 Claude API、遥测和 [Artifact](/docs/zh-CN/artifacts) 发布请求正文的 gzip 压缩。默认情况下，Claude Code 会在直接连接上压缩较大的请求正文，而在您通过代理发送请求、配置客户端证书或设置 `NODE_EXTRA_CA_CERTS` 时跳过压缩。如果 Claude Code 无法检测到的 [TLS 检查代理](/docs/zh-CN/network-config#ca-certificate-store)错误处理压缩请求，请使用 `0` |321| `CLAUDE_CODE_GZIP_REQUEST_BODIES` | 设置为 `0` 可关闭发送到 `api.anthropic.com` 的 Claude API、遥测和 [Artifact](/docs/zh-CN/artifacts) 发布请求体的 gzip 压缩。默认情况下，Claude Code 会在直接连接上压缩较大的请求体，而当您通过代理发送请求、配置客户端证书或设置 `NODE_EXTRA_CA_CERTS` 时会跳过压缩。如果 Claude Code 无法检测到的 [TLS 检查代理](/docs/zh-CN/network-config#ca-certificate-store)错误处理了压缩请求，请使用 `0` |

323| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 设置为 `1` 可跳过 IDE 扩展的自动安装。等同于将 [`autoInstallIdeExtension`](/docs/zh-CN/settings-reference#autoinstallideextension) 设置为 `false` |324| `CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL` | 设置为 `1` 可跳过 IDE 扩展的自动安装。等同于将 [`autoInstallIdeExtension`](/docs/zh-CN/settings-reference#autoinstallideextension) 设置为 `false` |

325| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 一个会话中可以同时运行多少个[子代理](/docs/zh-CN/sub-agents#concurrent-subagent-limit)，超过后 Agent 工具将拒绝再生成新的子代理（默认值：20）。接受以纯数字表示的正整数；其他任何值都会被忽略，因此该变量可以调整上限，但不能禁用上限。需要 Claude Code v2.1.217 或更高版本 |326| `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS` | 在 Agent 工具拒绝再生成一个子代理之前，一个会话中可以同时运行的[子代理](/docs/zh-CN/sub-agents#concurrent-subagent-limit)数量（默认：20）。接受纯数字形式的正整数；其他任何值都会被忽略，因此该变量可以调整上限，但不能禁用它。需要 Claude Code v2.1.217 或更高版本 |

326| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆盖 Claude Code 为当前模型假定的上下文窗口大小。自 v2.1.193 起，其应用方式取决于 Claude Code 如何解析模型 ID；请参阅[为网关或自定义模型 ID 更正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。当通过 `ANTHROPIC_BASE_URL` 路由到某个模型，而其上下文窗口与该名称对应的内置大小不匹配时使用 |327| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | 覆盖 Claude Code 为当前模型假定的上下文窗口大小。自 v2.1.193 起，其应用方式取决于 Claude Code 如何解析模型 ID；请参阅[为网关或自定义模型 ID 修正窗口](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。当通过 `ANTHROPIC_BASE_URL` 路由到某个模型，而其上下文窗口与其名称对应的内置大小不匹配时使用 |

327| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code 发送给模型的每个 MCP 工具描述和每个 MCP 服务器指令的最大长度（字符数）（默认值：2048）。Claude Code 会[截断更长的文本](/docs/zh-CN/mcp#for-mcp-server-authors)。接受以纯数字表示的正整数。其他任何值都会被忽略并应用默认值。需要 Claude Code v2.1.280 或更高版本 |328| `CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH` | Claude Code 发送给模型的每个 MCP 工具描述和每个 MCP 服务器指令的最大长度（字符数）（默认：2048）。Claude Code 会[截断更长的文本](/docs/zh-CN/mcp#for-mcp-server-authors)。接受纯数字形式的正整数。其他任何值都会被忽略并使用默认值。需要 Claude Code v2.1.280 或更高版本 |

328| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 设置大多数请求的最大输出 token 数。默认值和上限因模型而异；请参阅[最大输出 token](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。Claude Code 会将超过模型上限的值降至该上限。对于 Claude Code 无法解析为已知模型的模型 ID，默认值为 32000，上限为 128000。增大此值会减少触发[自动压缩](/docs/zh-CN/costs#reduce-token-usage)之前可用的有效上下文窗口 |329| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | 设置大多数请求的最大输出 token 数。默认值和上限因模型而异；请参阅[最大输出 token](https://platform.claude.com/docs/en/about-claude/models/overview#latest-models-comparison)。Claude Code 会将超过模型上限的值降至上限。对于 Claude Code 无法解析为已知模型的模型 ID，默认值为 32000，上限为 128000。增大此值会减少触发[自动压缩](/docs/zh-CN/costs#reduce-token-usage)之前可用的有效上下文窗口 |

329| `CLAUDE_CODE_MAX_RETRIES` | 覆盖失败 API 请求的重试次数（默认值：10）。自 v2.1.186 起上限为 15；自 v2.1.199 起，`CLAUDE_CODE_RETRY_WATCHDOG` 会提高默认值并移除上限。对于需要等待较长时间服务中断的无人值守会话，请改为设置 `CLAUDE_CODE_RETRY_WATCHDOG` |330| `CLAUDE_CODE_MAX_RETRIES` | 覆盖失败 API 请求的重试次数（默认：10）。自 v2.1.186 起上限为 15；自 v2.1.199 起，`CLAUDE_CODE_RETRY_WATCHDOG` 会提高默认值并移除上限。对于需要等待较长中断的无人值守会话，请改为设置 `CLAUDE_CODE_RETRY_WATCHDOG` |

330| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | 已在 v2.1.224 中移除，现在不起作用。以前用于限制 Claude 在一个会话中可通过 Agent 工具生成的[子代理](/docs/zh-CN/sub-agents)总数（默认值：200）；超过上限时生成会失败并显示 `Subagent spawn limit reached`。[并发子代理限制](/docs/zh-CN/sub-agents#concurrent-subagent-limit)和[深度限制](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents)仍然适用 |331| `CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION` | 已在 v2.1.224 中移除，现在不起任何作用。以前用于限制 Claude 在一个会话中可通过 Agent 工具生成的[子代理](/docs/zh-CN/sub-agents)总数（默认：200）；超出上限的生成会失败并显示 `Subagent spawn limit reached`。[并发子代理限制](/docs/zh-CN/sub-agents#concurrent-subagent-limit)和[深度限制](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents)仍然适用 |

331| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 主对话之下允许的[子代理层数](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents)（默认值：3）。在默认值下，子代理可以生成自己的子代理，而位于第三层的子代理不能再继续生成；设置为 `1` 可关闭嵌套。在 v2.1.217 至 v2.1.218 中，默认值为 1，因此除非您提高限制，否则子代理无法生成自己的子代理；v2.1.219 将默认值提高到 3。接受以纯数字表示的正整数；其他任何值都会被忽略，因此该限制可以调整但不能移除。需要 Claude Code v2.1.217 或更高版本 |332| `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH` | 主对话之下允许的[子代理层数](/docs/zh-CN/sub-agents#let-subagents-spawn-their-own-subagents)（默认：3）。在默认值下，子代理可以生成自己的子代理，而第三层的子代理不能再继续生成；设置为 `1` 可关闭嵌套。在 v2.1.217 至 v2.1.218 中，默认值为 1，因此除非您提高限制，否则子代理无法生成自己的子代理；v2.1.219 将默认值提高到 3。接受纯数字形式的正整数；其他任何值都会被忽略，因此该限制可以调整但不能移除。需要 Claude Code v2.1.217 或更高版本 |

333| `CLAUDE_CODE_MAX_TURNS` | 在未传递显式限制时，限制 agentic 轮次的数量。等同于传递 [`--max-turns`](/docs/zh-CN/cli-reference#cli-flags)，两者都设置时该标志优先。不是正整数的值会在启动时被拒绝并报错，而不会被视为无上限 |334| `CLAUDE_CODE_MAX_TURNS` | 在未传递显式限制时限制 agentic 轮次数。等同于传递 [`--max-turns`](/docs/zh-CN/cli-reference#cli-flags)，两者都设置时后者优先。非正整数的值会在启动时被拒绝并报错，而不会被视为无上限 |

334| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | 一个会话可以进行的 [WebSearch](/docs/zh-CN/tools-reference#websearch-tool-behavior) 调用总数上限（默认值：200）。当 Claude 达到上限时，后续的 WebSearch 调用会返回一条通知，告知它使用已收集的信息继续。接受没有上限的正整数。其他任何值都会被忽略并应用默认值，因此该上限可以提高但不能关闭。需要 Claude Code v2.1.212 或更高版本 |335| `CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION` | [WebSearch](/docs/zh-CN/tools-reference#session-search-limit) 调用次数上限（默认：200）。当 Claude 达到上限时，后续 WebSearch 调用会返回一条通知，告知它使用已收集的信息继续。接受没有上限的正整数。其他任何值都会被忽略并使用默认值，因此该上限可以提高但不能关闭。需要 Claude Code v2.1.212 或更高版本 |

336| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 仍在运行的 MCP 工具调用[转为后台任务](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls)之前经过的时间（毫秒）（默认值：120000，即 2 分钟）。设置为 `0` 可关闭自动转入后台。需要 Claude Code v2.1.212 或更高版本 |337| `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` | 仍在运行的 MCP 工具调用[转为后台任务](/docs/zh-CN/mcp#automatic-backgrounding-of-long-tool-calls)之前经过的时间（毫秒）（默认：120000，即 2 分钟）。设置为 `0` 可关闭自动转入后台。需要 Claude Code v2.1.212 或更高版本 |

337| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [非交互](/docs/zh-CN/headless)会话的第一个轮次等待仍在连接中的 MCP 服务器的时长（毫秒），用于替代默认的[首轮等待](/docs/zh-CN/agent-sdk/mcp#connection-timing)。设置后，等待将涵盖所有待连接的服务器。设置为 `0` 可跳过等待。无论取何值，[`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 服务器都会保留其自身的 `MCP_TIMEOUT` 等待。需要 Claude Code v2.1.274 或更高版本 |338| `CLAUDE_CODE_MCP_STARTUP_WAIT_MS` | [非交互](/docs/zh-CN/headless)会话的第一轮等待仍在连接中的 MCP 服务器的时长（毫秒），用于替代默认的[第一轮等待](/docs/zh-CN/agent-sdk/mcp#connection-timing)。设置后，等待涵盖所有待连接的服务器。设置为 `0` 可跳过等待。无论该值如何，[`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 服务器都会保留自己的 `MCP_TIMEOUT` 等待。需要 Claude Code v2.1.274 或更高版本 |

338| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 工具调用的空闲超时时间（毫秒）。当 stdio、HTTP、SSE、WebSocket 或 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) MCP 服务器在这段时间内既未发送响应也未发送进度通知时，工具调用会中止并报错，而不是等待整体的 `MCP_TOOL_TIMEOUT`。覆盖各传输方式的默认值：网络服务器为 300000（5 分钟），stdio 服务器为 1800000（30 分钟）。设置为 `0` 可禁用空闲检查。低于 1000 的值会提高到一秒，且该值以生效的 `MCP_TOOL_TIMEOUT` 为上限。`.mcp.json` 中至少为 1000 的单服务器 `timeout` 会将该服务器的空闲窗口提高到至少为该 `timeout` 值。不适用于 IDE 服务器或 SDK 进程内服务器。需要 Claude Code v2.1.187 或更高版本。在 v2.1.203 之前，stdio 服务器不受空闲超时限制 |339| `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` | MCP 工具调用的空闲超时时间（毫秒）。当 stdio、HTTP、SSE、WebSocket 或 [claude.ai 连接器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai) MCP 服务器在这段时间内未发送任何响应或进度通知时，工具调用会中止并报错，而不是等待整体的 `MCP_TOOL_TIMEOUT`。覆盖各传输方式的默认值：网络服务器为 300000（5 分钟），stdio 服务器为 1800000（30 分钟）。设置为 `0` 可禁用空闲检查。低于 1000 的值会被提高到一秒，并且该值的上限为有效的 `MCP_TOOL_TIMEOUT`。`.mcp.json` 中至少为 1000 的单服务器 `timeout` 会将该服务器的空闲窗口提高到至少 `timeout` 值。不适用于 IDE 服务器或 SDK 进程内服务器。需要 Claude Code v2.1.187 或更高版本。在 v2.1.203 之前，stdio 服务器不受空闲超时限制 |

339| `CLAUDE_CODE_MESSAGING_SOCKET` | 由 Claude Code 设置，而非由您设置：在绑定了[收件箱套接字](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket)的会话中，Claude Code 在绑定套接字时会将该套接字的路径导出给 hook 和 Bash 命令。在启动时即开启消息功能的会话中，Claude Code 会在任何 hook 运行之前绑定套接字。机器上的其他会话会将消息投递到此路径。每个会话导出自己的套接字，而不是从父会话继承的套接字，到达该套接字的消息会经过该会话的[入站控制](/docs/zh-CN/cross-session-messaging#control-inbound-messages)。设置文件中的 `env` 块无法设置它。需要 Claude Code v2.1.224 或更高版本 |340| `CLAUDE_CODE_MESSAGING_SOCKET` | 由 Claude Code 设置，而不是由您设置：在绑定了[收件箱套接字](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket)的会话中，Claude Code 在绑定套接字时会将该套接字的路径导出到 hook 和 Bash 命令。在启动时即开启消息传递的会话中，Claude Code 会在任何 hook 运行之前绑定套接字。本机上的其他会话会将消息投递到此路径。每个会话导出自己的套接字，而不是从父会话继承的套接字，到达该套接字的消息会经过会话的[入站控制](/docs/zh-CN/cross-session-messaging#control-inbound-messages)。设置中的 `env` 块无法设置它。需要 Claude Code v2.1.224 或更高版本 |

340| `CLAUDE_CODE_MESSAGING_TOKEN` | 由 Claude Code 设置，而非由您设置：在绑定了[收件箱套接字](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket)的会话中，Claude Code 会将此每会话令牌与 `CLAUDE_CODE_MESSAGING_SOCKET` 一起导出给 hook 和 Bash 命令。向套接字发送消息的脚本可以将 `{"type":"auth","token":"<token>"}` 作为第一行发送，以证明它属于该会话。在原生 Windows 上，Claude Code 要求必须有这一行，并会关闭任何未以有效的此行开头的连接。[自有子进程规则](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket)说明了 Claude Code 何时会查验该令牌。每个会话导出自己的令牌，绝不会继承父会话的令牌。设置文件中的 `env` 块无法设置它。需要 Claude Code v2.1.228 或更高版本 |341| `CLAUDE_CODE_MESSAGING_TOKEN` | 由 Claude Code 设置，而不是由您设置：在绑定了[收件箱套接字](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket)的会话中，Claude Code 会将此每会话令牌与 `CLAUDE_CODE_MESSAGING_SOCKET` 一起导出到 hook 和 Bash 命令。向套接字发送消息的脚本可以将 `{"type":"auth","token":"<token>"}` 作为第一行发送，以证明其属于该会话。在原生 Windows 上，Claude Code 要求必须发送此行，并会关闭任何未以有效此行开头的连接。[自有子进程规则](/docs/zh-CN/cross-session-messaging#the-sessions-inbox-socket)说明了 Claude Code 何时会参考该令牌。每个会话导出自己的令牌，绝不会是从父会话继承的令牌。设置中的 `env` 块无法设置它。需要 Claude Code v2.1.228 或更高版本 |

341| `CLAUDE_CODE_NATIVE_CURSOR` | 设置为 `1` 可在输入插入点显示终端自身的光标，而不是绘制的方块。该光标遵循终端的闪烁、形状和焦点设置。设置为 `0` 与不设置该变量效果相同，因此在终端自身光标已开启的会话中，它不会恢复绘制的方块 |342| `CLAUDE_CODE_NATIVE_CURSOR` | 设置为 `1` 可在输入插入点显示终端自身的光标，而不是绘制的方块。该光标遵循终端的闪烁、形状和焦点设置。设置为 `0` 与不设置该变量效果相同，因此在终端自身光标已开启的会话中，它不会恢复绘制的方块 |

342| `CLAUDE_CODE_NEW_INIT` | 设置为 `1` 可使 `/init` 运行交互式设置流程。该流程会先询问要生成哪些文件（包括 CLAUDE.md、skill 和 hook），然后再探索代码库并写入这些文件。如果不设置此变量，`/init` 会自动生成 CLAUDE.md 而不进行询问 |343| `CLAUDE_CODE_NEW_INIT` | 设置为 `1` 可让 `/init` 运行交互式设置流程。该流程会先询问要生成哪些文件（包括 CLAUDE.md、skill 和 hook），然后再探索代码库并写入这些文件。未设置此变量时，`/init` 会自动生成 CLAUDE.md 而不进行询问 |

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

344| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 限制 Claude Code 重新发送超时的[非流式请求](/docs/zh-CN/errors#streaming-response-ended-before-any-complete-data-was-received)的次数。设置为 `0` 时，请求会在首次超时时失败。默认未设置，因此由 `CLAUDE_CODE_MAX_RETRIES` 限制这些重新发送。有关超时时间，请参阅[调整重试行为](/docs/zh-CN/errors#tune-retry-behavior)。需要 Claude Code v2.1.285 或更高版本 |345| `CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES` | 限制 Claude Code 重新发送超时的[非流式请求](/docs/zh-CN/errors#streaming-response-ended-before-any-complete-data-was-received)的次数。设置为 `0` 时，请求会在第一次超时时失败。有关超时时间，请参阅[调整重试行为](/docs/zh-CN/errors#tune-retry-behavior)。需要 Claude Code v2.1.285 或更高版本 |

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

346| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | 用于 Claude.ai 身份验证的 OAuth 刷新令牌。设置后，`claude auth login` 会直接交换此令牌，而不是打开浏览器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。适用于在自动化环境中预配身份验证 |347| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | 用于 Claude.ai 身份验证的 OAuth 刷新令牌。设置后，`claude auth login` 会直接交换此令牌，而不是打开浏览器。需要 `CLAUDE_CODE_OAUTH_SCOPES`。适用于在自动化环境中配置身份验证 |

347| `CLAUDE_CODE_OAUTH_SCOPES` | 签发刷新令牌时使用的以空格分隔的 OAuth 作用域，例如 `"user:profile user:inference user:sessions:claude_code"`。设置 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 时必需 |348| `CLAUDE_CODE_OAUTH_SCOPES` | 签发刷新令牌时所用的 OAuth 作用域，以空格分隔，例如 `"user:profile user:inference user:sessions:claude_code"`。设置 `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` 时必需 |

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

349| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 已在 v2.1.160 中移除，现在不起作用。以前用于将[快速模式](/docs/zh-CN/fast-mode)固定到 Claude Opus 4.6，而不是当前的默认模型。Opus 4.6 不再支持快速模式 |350| `CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE` | 已在 v2.1.160 中移除，现在不起任何作用。以前用于将[快速模式](/docs/zh-CN/fast-mode)固定到 Claude Opus 4.6，而不是当前默认模型。Opus 4.6 已不再支持快速模式 |

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

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

352| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 刷新待处理 OpenTelemetry span 的超时时间（毫秒）（默认值：5000）。请参阅[监控](/docs/zh-CN/monitoring-usage) |353| `CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS` | 刷新待处理 OpenTelemetry span 的超时时间（毫秒）（默认：5000）。请参阅[监控](/docs/zh-CN/monitoring-usage) |

353| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新动态 OpenTelemetry 标头的间隔（毫秒）（默认值：1740000 / 29 分钟）。请参阅[动态标头](/docs/zh-CN/monitoring-usage#dynamic-headers) |354| `CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS` | 刷新动态 OpenTelemetry 标头的间隔（毫秒）（默认：1740000 / 29 分钟）。请参阅[动态标头](/docs/zh-CN/monitoring-usage#dynamic-headers) |

354| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 导出器在关闭时完成的超时时间（毫秒）（默认值：2000）。如果退出时指标丢失，请增大此值。请参阅[监控](/docs/zh-CN/monitoring-usage) |355| `CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS` | OpenTelemetry 导出器在关闭时完成的超时时间（毫秒）（默认：2000）。如果指标在退出时丢失，请调高该值。请参阅[监控](/docs/zh-CN/monitoring-usage) |

355| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 设置为 `1` 可让 Claude Code 在有新版本可用时于后台运行您的包管理器的升级命令。适用于 Homebrew 和 WinGet 安装。其他包管理器仍会显示升级命令而不运行它。请参阅[自动更新](/docs/zh-CN/setup#auto-updates) |356| `CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS` | 当 API 以 `529` 过载错误拒绝请求时，[自动重试](/docs/zh-CN/errors#tune-retry-behavior)之间指数退避的起始延迟（毫秒），用于替代默认的 500。当 API 容量已满时，调高该值可将重试分散到更长的时间窗口内。请以纯数字给出 500 到 32000 之间的整毫秒数；Claude Code 会将任何其他值视为未设置。当 `CLAUDE_CODE_RETRY_WATCHDOG` 设置为 `1`，或被拒绝的请求是在[快速模式](/docs/zh-CN/fast-mode#handle-rate-limits)下发送时，不产生任何效果。需要 Claude Code v2.1.292 或更高版本 |

356| `CLAUDE_CODE_PERFORCE_MODE` | 设置为 `1` 可启用感知 Perforce 的写保护。设置后，如果目标文件缺少所有者写入位，Edit、Write 和 NotebookEdit 会失败并给出 `p4 edit <file>` 提示；Perforce 会清除已同步文件的该位，直到 `p4 edit` 打开它们。这可以防止 Claude Code 绕过 Perforce 变更跟踪 |357| `CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE` | 设置为 `1` 可让 Claude Code 在有新版本可用时在后台运行您的包管理器的升级命令。适用于 Homebrew 和 WinGet 安装。其他包管理器仍会显示升级命令而不运行它。请参阅[自动更新](/docs/zh-CN/setup#auto-updates) |

358| `CLAUDE_CODE_PERFORCE_MODE` | 设置为 `1` 可启用感知 Perforce 的写保护。设置后，如果目标文件缺少所有者写入位（Perforce 会在同步的文件上清除该位，直到 `p4 edit` 将其打开），Edit、Write 和 NotebookEdit 会失败并给出 `p4 edit <file>` 提示。这可防止 Claude Code 绕过 Perforce 变更跟踪 |

358| `CLAUDE_CODE_PLUGIN_DIRS` | 要为会话加载的插件目录，每个目录的加载方式与 [`--plugin-dir`](/docs/zh-CN/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 标志的加载方式相同。在 Unix 上用 `:` 分隔多个路径，在 Windows 上用 `;` 分隔。每个路径请使用绝对路径或以 `~` 开头，因为 Claude Code 会跳过相对路径。需要 Claude Code v2.1.280 或更高版本。请参阅[为单个会话加载插件](/docs/zh-CN/plugins/create#load-a-directory-or-archive-for-one-session) |360| `CLAUDE_CODE_PLUGIN_DIRS` | 要为会话加载的插件目录，每个目录的加载方式与 [`--plugin-dir`](/docs/zh-CN/plugins/cli-reference#flags-that-load-a-plugin-for-one-session) 标志相同。在 Unix 上用 `:` 分隔多个路径，在 Windows 上用 `;` 分隔。每个路径都应为绝对路径或以 `~` 开头，因为 Claude Code 会跳过相对路径。需要 Claude Code v2.1.280 或更高版本。请参阅[为单个会话加载插件](/docs/zh-CN/plugins/create#load-a-directory-or-archive-for-one-session) |

359| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 控制当 [mod](/docs/zh-CN/plugins/mods/overview) 的文件发生变化时 Claude Code 是否重新加载该 mod。重新加载适用于您通过 `--plugin-dir` 从目录加载的 mod，在交互式会话中默认开启。设置为 `1` 可在非交互式会话中也开启，设置为 `0` 可在所有会话中关闭。需要 Claude Code v2.1.287 或更高版本。请参阅 [mod 设置和环境变量](/docs/zh-CN/plugins/mods/reference#settings-and-environment-variables) |361| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | 控制 Claude Code 是否在 [mod](/docs/zh-CN/plugins/mods/overview) 的文件发生变化时重新加载该 mod。重新加载适用于您使用 `--plugin-dir` 从目录加载的 mod，并且在交互式会话中默认开启。设置为 `1` 可在非交互式会话中也开启，设置为 `0` 可在所有会话中关闭。需要 Claude Code v2.1.287 或更高版本。请参阅 [mod 设置和环境变量](/docs/zh-CN/plugins/mods/reference#settings-and-environment-variables) |

360| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 克隆或刷新插件市场的超时时间（毫秒）（默认值：120000）。对于大型仓库或较慢的网络连接，请增大此值。请参阅 [Git clone timed out](/docs/zh-CN/plugins/troubleshooting#git-clone-timed-out-after-120s) |362| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 克隆或刷新插件市场的超时时间（毫秒）（默认：120000）。对于大型仓库或较慢的网络连接，请调高此值。请参阅 [Git 克隆超时](/docs/zh-CN/plugins/troubleshooting#git-clone-timed-out-after-120s) |

361| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 设置为 `1` 可在市场刷新无法连接到远程或无法通过远程身份验证时，跳过重新克隆尝试并继续使用现有的市场检出。适用于离线或隔离网络环境，在这些环境中重新克隆也会以同样的方式失败。请参阅[市场更新在离线环境中失败](/docs/zh-CN/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |363| `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE` | 设置为 `1` 可在市场刷新无法访问远程或无法通过远程身份验证时，跳过重新克隆尝试并继续使用现有的市场检出。适用于重新克隆会以同样方式失败的离线或隔离网络环境。请参阅[市场更新在离线环境中失败](/docs/zh-CN/plugins/troubleshooting#marketplace-updates-keep-failing-offline) |

362| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 设置为 `1` 可通过 HTTPS 而不是 SSH 克隆 GitHub `owner/repo` 简写源。适用于插件安装和更新，以及 `/plugin marketplace add` 和 `update`。适用于 CI 运行器、容器或任何未为 `github.com` 配置 SSH 密钥的环境 |364| `CLAUDE_CODE_PLUGIN_PREFER_HTTPS` | 设置为 `1` 可通过 HTTPS 而不是 SSH 克隆 GitHub `owner/repo` 简写来源。适用于插件安装和更新，以及 `/plugin marketplace add` 和 `update`。适用于 CI 运行器、容器或任何未为 `github.com` 配置 SSH 密钥的环境 |

363| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一个或多个只读插件种子目录的路径，在 Unix 上用 `:` 分隔，在 Windows 上用 `;` 分隔。用于将预填充的插件目录打包到容器镜像中。Claude Code 在启动时从这些目录注册市场，并使用预缓存的插件而无需重新克隆。请参阅[为容器预填充插件](/docs/zh-CN/plugins/org#seed-containers-and-ci) |365| `CLAUDE_CODE_PLUGIN_SEED_DIR` | 一个或多个只读插件种子目录的路径，在 Unix 上以 `:` 分隔，在 Windows 上以 `;` 分隔。使用它可将预填充的插件目录打包到容器镜像中。Claude Code 会在启动时从这些目录注册市场，并使用预缓存的插件而无需重新克隆。请参阅[为容器预填充插件](/docs/zh-CN/plugins/org#seed-containers-and-ci) |

364| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 设置为 `1` 可阻止 Claude Code 在为工具调用、hook 和状态栏命令生成 PowerShell 时传递 `-ExecutionPolicy Bypass`，转而遵循机器的有效执行策略。默认情况下，Claude Code 会在进程作用域绕过执行策略，以便 `.ps1` 脚本和模块导入能在默认为 Restricted 的 Windows 安装上正常工作。无论此设置如何，进程作用域的绕过都不会覆盖组策略 `MachinePolicy` 或 `UserPolicy` |366| `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY` | 设置为 `1` 可阻止 Claude Code 在为工具调用、hook 和状态栏命令启动 PowerShell 时传递 `-ExecutionPolicy Bypass`，转而遵循计算机的有效执行策略。默认情况下，Claude Code 会在进程作用域绕过执行策略，以便 `.ps1` 脚本和模块导入能在默认为 Restricted 的 Windows 安装上正常工作。无论此设置如何，进程作用域的绕过都不会覆盖组策略 `MachinePolicy` 或 `UserPolicy` |

365| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless#background-tasks-at-exit)下，最后一个轮次之后空闲等待后台工作（例如子代理和工作流）的上限（毫秒）。每当 Claude 用一个轮次处理后台结果时，空闲等待都会重新计时。默认值：`600000`，即 10 分钟。当空闲等待达到上限时，Claude Code 会停止等待剩余的后台任务并退出。设置为 `0` 可无限期等待。此上限独立于适用于普通后台 shell 的五秒宽限期。需要 Claude Code v2.1.182 或更高版本 |367| `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` | 在使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless#background-tasks-at-exit)下，最后一轮之后空闲等待后台工作（例如子代理和工作流）的上限（毫秒）。每当 Claude 用一轮来处理后台结果时，空闲等待都会重新开始计时。默认：`600000`，即 10 分钟。当空闲等待达到上限时，Claude Code 会停止等待剩余的后台任务。由主对话启动且正在运行的后台命令会使运行持续到上限之后。设置为 `0` 可无限期等待。需要 Claude Code v2.1.182 或更高版本 |

366| `CLAUDE_CODE_PROCESS_WRAPPER` | 通过以 argv 前缀形式给出的企业启动器（例如 `/opt/corp/launcher`）启动 Claude Code 从其自身二进制文件启动的进程，例如托管 [agent view](/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 或更高版本 |368| `CLAUDE_CODE_PROCESS_WRAPPER` | 通过以 argv 前缀形式给出的企业启动器（例如 `/opt/corp/launcher`）来启动 Claude Code 从其自身二进制文件启动的进程，例如托管 [agent view](/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 或更高版本 |

367| `CLAUDE_CODE_PROJECT_DIR_NAME` | 与 `CLAUDE_CONFIG_DIR` 一起设置，用于选择 Claude Code 存储该会话的会话记录和自动记忆所用的 `projects/` 目录名称，以替代根据工作目录路径派生的名称。例如，使用 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 启动 Claude Code 会将它们存储在 `/srv/tenant-a/projects/work/` 下。当 `CLAUDE_CONFIG_DIR` 未设置时，Claude Code 会忽略此变量，并且只从您启动 `claude` 的环境中读取它，绝不会从[设置文件的 `env` 块](#in-settings-files)中读取。请参阅[自行命名项目目录](/docs/zh-CN/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更高版本 |369| `CLAUDE_CODE_PROJECT_DIR_NAME` | 与 `CLAUDE_CONFIG_DIR` 一起设置，用于选择 Claude Code 存储该会话的会话记录和自动记忆的 `projects/` 目录名称，以替代从工作目录路径派生的名称。例如，使用 `CLAUDE_CONFIG_DIR=/srv/tenant-a CLAUDE_CODE_PROJECT_DIR_NAME=work claude` 启动 Claude Code 会将它们存储在 `/srv/tenant-a/projects/work/` 下。当 `CLAUDE_CONFIG_DIR` 未设置时，Claude Code 会忽略此变量，并且只从您启动 `claude` 的环境中读取它，绝不会从[设置文件 `env` 块](#in-settings-files)中读取。请参阅[自行命名项目目录](/docs/zh-CN/sessions#name-the-project-directory-yourself)。需要 Claude Code v2.1.234 或更高版本 |

368| `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 或更高版本 |370| `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 或更高版本 |

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

370| `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) |372| `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) |

372| `CLAUDE_CODE_REMOTE` | 当 Claude Code 作为[云端会话](/docs/zh-CN/claude-code-on-the-web)运行时自动设置为 `true`。可从 hook 或设置脚本中读取此值，以检测是否处于云端会话中 |374| `CLAUDE_CODE_REMOTE` | 当 Claude Code 作为[云端会话](/docs/zh-CN/claude-code-on-the-web)运行时自动设置为 `true`。可从 hook 或设置脚本中读取它，以检测您是否处于云端会话中 |

373| `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) |375| `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) |

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

375| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 设置为 `1` 可在上一个会话于轮次中途结束时自动恢复。用于 SDK 模式，使模型无需 SDK 重新发送提示词即可继续。要关闭此功能，请取消设置该变量或将其设置为 `0`。有关 VS Code 聊天面板，请参阅[重新加载后继续对话](/docs/zh-CN/vs-code#continue-conversations-after-a-reload) |377| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` | 设置为 `1` 可在上一个会话于轮次中途结束时自动恢复。在 SDK 模式下使用，使模型无需 SDK 重新发送提示词即可继续。要关闭此功能，请取消设置该变量或将其设置为 `0`。对于 VS Code 聊天面板，请参阅[重新加载后继续对话](/docs/zh-CN/vs-code#continue-conversations-after-a-reload) |

376| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 对于在轮次中途结束的会话，恢复时可自动继续所允许的最后一条会话记录消息的最大时长（毫秒）。当最后一条消息早于此界限时，Claude Code 会跳过 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 自动恢复及其 `CLAUDE_CODE_RESUME_PROMPT` 继续消息，会话以空闲状态启动，由您显式继续。未设置或为 `0` 表示无界限，但最后一个请求因 API 错误而失败的轮次，仅在该错误发生不足六小时时才会恢复。正值会限制所有轮次，包括这类轮次；负值或非数字值会应用一小时的界限。长时间运行的 Agent 的启动脚本可以设置此值，以免针对旧会话记录重启时重新运行过时的提示词。当 Claude Code 重启一个从交互式会话继承了对话的已崩溃 [agent view](/docs/zh-CN/agent-view) 会话时，它会自行设置一小时的界限。需要 Claude Code v2.1.211 或更高版本 |378| `CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS` | 对于在轮次中途结束的会话，恢复时自动继续所允许的最后一条会话记录消息的最大时长（毫秒）。当最后一条消息早于此界限时，Claude Code 会跳过 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 自动恢复及其 `CLAUDE_CODE_RESUME_PROMPT` 继续消息，会话以空闲状态启动，由您显式继续。未设置或为 `0` 表示无界限，但最后一个请求因 API 错误而失败的轮次仅在该错误发生不到六小时时才会恢复。正值会限制所有轮次，包括上述轮次；负值或非数字值会应用一小时的界限。长时间运行的 Agent 的启动脚本可以设置此项，以免针对旧会话记录重启时重新运行过时的提示词。当 Claude Code 重启一个从交互式会话继承对话的已崩溃 [agent view](/docs/zh-CN/agent-view) 会话时，会自行设置一小时的界限。需要 Claude Code v2.1.211 或更高版本 |

377| `CLAUDE_CODE_RESUME_PROMPT` | 覆盖 Claude Code 在 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 继续中断的轮次（而不是重新发送其提示词）时，或在您使用 `-p` 恢复[延迟的工具调用](/docs/zh-CN/hooks#defer-a-tool-call-for-later)时，发送给 Claude 的继续消息。默认为 `Continue from where you left off.`。空字符串会使用默认值 |379| `CLAUDE_CODE_RESUME_PROMPT` | 覆盖 Claude Code 发送给 Claude 的继续消息，适用于 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 继续被中断的轮次而不是重新发送其提示词时，或您使用 `-p` 恢复[延迟的工具调用](/docs/zh-CN/hooks#defer-a-tool-call-for-later)时。默认为 `Continue from where you left off.`。空字符串会使用默认值 |

378| `CLAUDE_CODE_RETRY_WATCHDOG` | 对于无人值守的会话（例如评估框架、CI 作业或远程工作进程），请设置为 `1`。无限期重试 `429` 和 `529` 容量错误，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次尝试后失败。当标准速度请求收到报告支出限额或使用额度耗尽的 `429` 时，Claude Code 会立即失败，即使该错误来自按计划重置的[网关支出上限](/docs/zh-CN/errors#spend-limit-reached)。在 v2.1.239 之前，看门狗会无限期重试这些错误。有关快速模式请求，请参阅[处理速率限制](/docs/zh-CN/fast-mode#handle-rate-limits)。看门狗在两次尝试之间最多退避 5 分钟，或者在响应带有速率限制重置时间时一直等到限制重置，因此达到用量限制的会话会等待剩余的时间窗口结束。在 v2.1.199 或更高版本中，它还会将其他暂时性错误（例如服务器错误、超时和连接中断）的默认重试次数提高到 300（大约三小时的退避时间），并在您显式设置 `CLAUDE_CODE_MAX_RETRIES` 时移除其 15 次的上限。需要 Claude Code v2.1.186 或更高版本 |380| `CLAUDE_CODE_RETRY_WATCHDOG` | 对于评估框架、CI 作业或远程工作器等无人值守会话，请设置为 `1`。会无限期重试 `429` 和 `529` 容量错误，而不是在 `CLAUDE_CODE_MAX_RETRIES` 次尝试后失败。当标准速度请求收到报告支出限额或使用额度耗尽的 `429` 时，Claude Code 会立即失败，即使它来自按计划重置的[网关支出上限](/docs/zh-CN/errors#spend-limit-reached)。在 v2.1.239 之前，watchdog 会无限期重试这些错误。对于快速模式请求，请参阅[处理速率限制](/docs/zh-CN/fast-mode#handle-rate-limits)。watchdog 在两次尝试之间最多退避 5 分钟，或者当响应包含速率限制重置时间时等到限制重置，因此遇到用量限制的会话会等待剩余的时间窗口结束。在 v2.1.199 或更高版本上，它还会将其他瞬态错误（例如服务器错误、超时和连接断开）的默认重试次数提高到 300，约合三小时的退避时间，并在您显式设置 `CLAUDE_CODE_MAX_RETRIES` 时移除其 15 次的上限。需要 Claude Code v2.1.186 或更高版本 |

379| `CLAUDE_CODE_SAFE_MODE` | 设置为 `1` 可在安全模式下启动：CLAUDE.md、skill、插件、hook、MCP 服务器、自定义命令和 Agent、输出样式、工作流、自定义主题、自定义快捷键、状态栏和文件建议命令、LSP 服务器以及自动记忆均不会加载，用于排除损坏配置的故障。托管设置策略仍然适用，包括策略配置的 hook、状态栏和文件建议命令；托管插件、托管 skill、托管 CLAUDE.md 和策略配置的 MCP 服务器则不会加载。等同于传递 [`--safe-mode`](/docs/zh-CN/cli-reference#cli-flags)。直接生成的子进程会继承该变量 |381| `CLAUDE_CODE_SAFE_MODE` | 设置为 `1` 可在安全模式下启动：CLAUDE.md、skill、插件、hook、MCP 服务器、自定义命令和 Agent、输出样式、工作流、自定义主题、自定义快捷键、状态栏和文件建议命令、LSP 服务器以及自动记忆均不会加载，用于对损坏的配置进行故障排除。托管设置策略仍然适用，包括策略配置的 hook、状态栏和文件建议命令；托管插件、托管 skill、托管 CLAUDE.md 和策略配置的 MCP 服务器则不会加载。等同于传递 [`--safe-mode`](/docs/zh-CN/cli-reference#cli-flags)。直接生成的子进程会继承该变量 |

380| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 对象，用于在设置了 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 时限制特定脚本在每个会话中可被调用的次数。键是与命令文本进行匹配的子字符串；值是整数调用次数限制。例如，`{"deploy.sh": 2}` 允许 `deploy.sh` 最多被调用两次。匹配基于子字符串，因此像 `./scripts/deploy.sh $(evil)` 这样的 shell 展开技巧仍会计入上限。无法检测通过 `xargs` 或 `find -exec` 进行的运行时扇出；这是一项纵深防御控制 |382| `CLAUDE_CODE_SCRIPT_CAPS` | 当设置了 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 时，用于限制特定脚本在每个会话中可被调用次数的 JSON 对象。键是与命令文本匹配的子字符串；值是整数调用上限。例如，`{"deploy.sh": 2}` 允许 `deploy.sh` 最多被调用两次。匹配基于子字符串，因此 `./scripts/deploy.sh $(evil)` 之类的 shell 展开技巧仍会计入上限。不会检测通过 `xargs` 或 `find -exec` 进行的运行时扇出；这是一项纵深防御控制 |

381| `CLAUDE_CODE_SCROLL_SPEED` | 设置[全屏渲染](/docs/zh-CN/fullscreen#mouse-wheel-scrolling)中的鼠标滚轮滚动倍数。接受不超过 20 的任何正值，包括小于 1 的小数值（例如 `0.5`），以便在已放大滚轮事件的终端中减慢加速的触控板和滚轮滚动。如果您的终端每格发送一个滚轮事件且不做放大，设置为 `3` 可与 `vim` 保持一致。在 JetBrains IDE 终端中会被忽略，Claude Code 在其中使用自己的滚动处理 |383| `CLAUDE_CODE_SCROLL_SPEED` | 设置[全屏渲染](/docs/zh-CN/fullscreen#mouse-wheel-scrolling)中的鼠标滚轮滚动倍数。接受不超过 20 的任意正值，包括低于 1 的小数值（例如 `0.5`），以便在已放大滚轮事件的终端中减慢加速的触控板和滚轮滚动。如果您的终端每格发送一个滚轮事件且不进行放大，请设置为 `3` 以与 `vim` 保持一致。在 JetBrains IDE 终端中会被忽略，Claude Code 在那里使用自己的滚动处理 |

382| `CLAUDE_CODE_SEND_FEEDBACK` | 设置为 `0` 可为会话关闭 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)。设置为 `1` 可在您的账户已有访问权限的情况下开启它；该变量本身无法授予访问权限，其他关闭反馈的开关（例如 `DISABLE_FEEDBACK_COMMAND` 和 [`feedbackDrafts`](/docs/zh-CN/settings-reference#feedbackdrafts) 设置的 `off` 值）仍然适用 |384| `CLAUDE_CODE_SEND_FEEDBACK` | 设置为 `0` 可为会话关闭[由 Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)。设置为 `1` 可在您的账户已具备访问权限的情况下开启；该变量本身无法授予访问权限，其他关闭反馈的开关（例如 `DISABLE_FEEDBACK_COMMAND` 和 [`feedbackDrafts`](/docs/zh-CN/settings-reference#feedbackdrafts) 设置的 `off` 值）仍然适用 |

383| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆盖 [SessionEnd](/docs/zh-CN/hooks#sessionend) hook 的时间预算（毫秒）。该值也是每个未设置自身 `timeout` 的 hook 的超时时间。适用于会话退出、`/clear` 以及通过交互式 `/resume` 切换会话。默认预算为 1.5 秒，会自动提高到设置文件中配置的最高单个 hook `timeout`，最多 60 秒。插件提供的 hook 上的超时时间不会提高预算 |385| `CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` | 覆盖 [SessionEnd](/docs/zh-CN/hooks#sessionend) hook 的时间预算（毫秒）。该值也是每个未设置自身 `timeout` 的 hook 的超时时间。适用于会话退出、`/clear` 以及通过交互式 `/resume` 切换会话。默认情况下预算为 1.5 秒，会自动提高到设置文件中配置的最高单个 hook `timeout`，最多 60 秒。插件提供的 hook 上的超时时间不会提高预算 |

384| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子进程、[hook 命令](/docs/zh-CN/hooks)子进程以及 stdio [MCP 服务器](/docs/zh-CN/mcp)子进程中自动设置为当前会话 ID。对于 Bash、PowerShell 和 hook，它与 hook JSON 输入中的 `session_id` 字段一致，并在 `/clear` 时更新。MCP 服务器子进程保留其生成时的 ID。使用 `--resume <session-id>` 时，它会收到恢复的 ID，与 hook 和 Bash 一致。使用 `--continue` 或不带显式 ID 的 `--resume` 时，它可能会收到初始启动 ID。用于将脚本和外部工具与启动它们的 Claude Code 会话关联起来 |386| `CLAUDE_CODE_SESSION_ID` | 在 Bash 和 PowerShell 工具子进程、[hook 命令](/docs/zh-CN/hooks)子进程以及 stdio [MCP 服务器](/docs/zh-CN/mcp)子进程中自动设置为当前会话 ID。对于 Bash、PowerShell 和 hook，它与 hook JSON 输入中的 `session_id` 字段一致，并在 `/clear` 时更新。MCP 服务器子进程会保留其启动时的 ID。使用 `--resume <session-id>` 时，它会收到恢复的 ID，与 hook 和 Bash 一致。使用不带显式 ID 的 `--continue` 或 `--resume` 时，它可能会收到初始启动 ID。用于将脚本和外部工具与启动它们的 Claude Code 会话关联起来 |

385| `CLAUDE_CODE_SHELL` | 设置 Claude Code 运行 Bash 工具命令所使用的 shell。接受 `bash` 或 `zsh` 二进制文件的路径，例如 `/opt/homebrew/bin/bash`。不支持 `fish` 等其他 shell。如果该值不是可用的 `bash` 或 `zsh` 路径，Claude Code 会忽略它并回退到自动检测。自动检测在 `$SHELL` 指向 `bash` 或 `zsh` 时使用它，否则会在 `PATH` 和标准安装位置中先选择找到的第一个可用 `zsh`，然后是 `bash` |387| `CLAUDE_CODE_SHELL` | 设置 Claude Code 用于运行 Bash 工具命令的 shell。接受 `bash` 或 `zsh` 二进制文件的路径，例如 `/opt/homebrew/bin/bash`。不支持 `fish` 等其他 shell。如果该值不是可用的 `bash` 或 `zsh` 路径，Claude Code 会忽略它并回退到自动检测。自动检测会在您的 `$SHELL` 指向 `bash` 或 `zsh` 时使用它，否则会在您的 `PATH` 和标准安装位置中先选择找到的第一个可用的 `zsh`，然后是 `bash` |

386| `CLAUDE_CODE_SHELL_PREFIX` | 包装 Claude Code 生成的 shell 命令的命令前缀：Bash 工具调用、[hook](/docs/zh-CN/hooks) 命令、[状态栏](/docs/zh-CN/statusline)命令以及 stdio [MCP 服务器](/docs/zh-CN/mcp)启动命令。PowerShell hook 和 exec 形式的 hook 运行时不带前缀。适用于日志记录或审计。设置一个单纯的可执行文件路径（例如 `/path/to/logger.sh`）会以 `/path/to/logger.sh '<command>'` 的形式运行每个命令。包装器在 `$1` 中以单个经 shell 引用的参数接收命令行，因此包装器必须用 shell 重新求值 `$1`，例如 `exec bash -c "$1"`。将 `$1` 视为单纯的可执行文件路径会导致传递 `npx -y <package>` 等参数的 stdio MCP 服务器出错。对于 Bash 工具调用，`$1` 包含 Claude Code 组装的完整 shell 调用（包括环境设置），而不仅是 Claude 运行的命令 |388| `CLAUDE_CODE_SHELL_PREFIX` | 包装 Claude Code 所启动的 shell 命令的命令前缀：Bash 工具调用、[hook](/docs/zh-CN/hooks) 命令、[状态栏](/docs/zh-CN/statusline)命令以及 stdio [MCP 服务器](/docs/zh-CN/mcp)启动命令。PowerShell hook 和 exec 形式的 hook 不使用该前缀运行。适用于日志记录或审计。设置诸如 `/path/to/logger.sh` 的裸可执行文件路径时，每个命令会以 `/path/to/logger.sh '<command>'` 的形式运行。包装器在 `$1` 中以单个经 shell 引用的参数形式接收命令行，因此包装器必须用 shell 重新求值 `$1`，例如 `exec bash -c "$1"`。将 `$1` 视为裸可执行文件路径会破坏传递诸如 `npx -y <package>` 之类参数的 stdio MCP 服务器。对于 Bash 工具调用，`$1` 包含 Claude Code 组装的完整 shell 调用，包括环境设置，而不仅仅是 Claude 运行的命令 |

387| `CLAUDE_CODE_SIMPLE` | 设置为 `1` 可使用精简的系统提示词运行，并仅提供 Bash、文件读取和文件编辑工具。来自 `--mcp-config` 的 MCP 工具仍然可用。禁用对 hook、skill、自定义命令、子代理、已安装插件、MCP 服务器、自动记忆和 CLAUDE.md 的自动发现。通过 `--add-dir` 传入的目录中的 skill 仍会加载。不会读取 OAuth 令牌和钥匙串凭据，因此 Anthropic 身份验证必须来自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同于传递 [`--bare`](/docs/zh-CN/headless#start-faster-with-bare-mode) |389| `CLAUDE_CODE_SIMPLE` | 设置为 `1` 可使用最小的系统提示词运行，并且只提供 Bash、文件读取和文件编辑工具。来自 `--mcp-config` 的 MCP 工具仍然可用。禁用对 hook、skill、自定义命令、子代理、已安装插件、MCP 服务器、自动记忆和 CLAUDE.md 的自动发现。您通过 `--add-dir` 传递的目录中的 skill 仍会加载。不会读取 OAuth 令牌和钥匙串凭据，因此 Anthropic 身份验证必须来自 `ANTHROPIC_API_KEY` 或 `--settings` 中的 `apiKeyHelper`。等同于传递 [`--bare`](/docs/zh-CN/headless#start-faster-with-bare-mode) |

388| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 设置为 `1` 可在任何模型上使用更短的系统提示词和简化的工具描述。设置为 `0`、`false`、`no` 或 `off` 可选择退出，即使在实验或服务器配置原本会启用它的模型上也是如此。完整的工具集、hook、MCP 服务器和 CLAUDE.md 发现仍保持启用 |390| `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT` | 在 Claude Code 的完整系统提示词与带有简略工具描述的较短系统提示词之间进行选择。未设置时，Haiku 4.5、Sonnet 5、Opus 4.7 以及这些系列中的更早模型默认使用完整提示词，更新的模型使用较短的提示词。设置为 `1` 可在任何模型上使用较短的提示词。设置为 `0`、`false`、`no` 或 `off` 可在任何模型上使用完整提示词，即使实验或服务器配置原本会选择较短的提示词。两种提示词都会保留完整的工具集、hook、MCP 服务器和 CLAUDE.md 发现 |

389| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 为 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 跳过客户端身份验证，适用于自行签署请求的网关 |391| `CLAUDE_CODE_SKIP_ANTHROPIC_AWS_AUTH` | 跳过 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 的客户端身份验证，适用于自行对请求签名的网关 |

390| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 设置为 `1` 可关闭对从 AWS 默认凭据提供程序链解析出的凭据的进程内缓存，使 Claude Code 在每个 API 请求时都解析该链。关闭缓存后，基于 SSO 的配置文件会在每个请求时向 IAM Identity Center 请求凭据。请参阅[凭据缓存和解析超时](/docs/zh-CN/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更高版本 |392| `CLAUDE_CODE_SKIP_AWS_CRED_CACHE` | 设置为 `1` 可关闭从 AWS 默认凭据提供程序链解析的凭据的进程内缓存，使 Claude Code 在每个 API 请求时都解析该链。关闭缓存后，基于 SSO 的配置文件会在每个请求时从 IAM Identity Center 请求凭据。请参阅[凭据缓存和解析超时](/docs/zh-CN/amazon-bedrock#credential-caching-and-resolution-timeout)。需要 Claude Code v2.1.207 或更高版本 |

392| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 设置为 `1` 可将失败的[快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性检查视为可用，适用于阻止该检查直接向 `api.anthropic.com` 发出请求的网络。Claude Code 仍会遵循“已被您的组织禁用”的响应 |394| `CLAUDE_CODE_SKIP_FAST_MODE_NETWORK_ERRORS` | 设置为 `1` 可将失败的[快速模式](/docs/zh-CN/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways)可用性检查视为可用，适用于阻止该检查直接请求 `api.anthropic.com` 的网络。Claude Code 仍会遵循 "disabled by your organization" 响应 |

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

394| `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 之前，除非同时设置了 API 密钥，否则此变量会导致 Microsoft Foundry 客户端无法发送请求 |396| `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 密钥 |

396| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 和 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 上的[启动模型检查](/docs/zh-CN/amazon-bedrock#startup-model-checks)会在本机上记住它们发现您的账户无法调用的模型，最长保留一天。设置为 `1` 可关闭这一记忆功能。需要 Claude Code v2.1.285 或更高版本 |398| `CLAUDE_CODE_SKIP_MODEL_ACCESS_MEMORY` | [Amazon Bedrock](/docs/zh-CN/amazon-bedrock) 和 [Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai) 上的[启动模型检查](/docs/zh-CN/amazon-bedrock#startup-model-checks)会在本机上记住它们发现您的账户无法调用的模型，最长保留一天。设置为 `1` 可关闭这一记忆。需要 Claude Code v2.1.285 或更高版本 |

397| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 设置为 `1` 可跳过将提示词历史和会话记录写入磁盘。设置此变量后启动的会话不会出现在 `--resume`、`--continue` 或上箭头历史中。适用于临时的脚本化会话 |399| `CLAUDE_CODE_SKIP_PROMPT_HISTORY` | 设置为 `1` 可跳过将提示词历史和会话记录写入磁盘。设置此变量后启动的会话不会出现在 `--resume`、`--continue` 或上箭头历史中。适用于临时的脚本化会话 |

399| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | 设置为 `1` 可让使用 `--output-format stream-json` 启动的会话，在原本仅以 stderr 输出结束的启动失败情况下，写入一条[说明 Claude Code 拒绝启动原因的结果消息](/docs/zh-CN/agent-sdk/typescript#startup_failure_reason)。需要 Claude Code v2.1.274 或更高版本 |401| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | 设置为 `1` 可让以 `--output-format stream-json` 启动的会话在遇到原本仅以 stderr 输出结束的启动失败时，写入一条[说明 Claude Code 拒绝启动原因的结果消息](/docs/zh-CN/agent-sdk/typescript#startup_failure_reason)。需要 Claude Code v2.1.274 或更高版本 |

400| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-CN/hooks#stop) 或 [SubagentStop](/docs/zh-CN/hooks#subagentstop) hook 可连续阻止轮次结束的最大次数，超过后 Claude Code 会覆盖它并仍然结束该轮次（默认值：8）。设置为 `0` 可禁用此上限。如果您的 hook 确实需要更多次迭代才能完成，请提高此值 |402| `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` | [Stop](/docs/zh-CN/hooks#stop) 或 [SubagentStop](/docs/zh-CN/hooks#subagentstop) hook 可连续阻止轮次结束的最大次数，超过后 Claude Code 会覆盖它并仍然结束该轮次（默认：8）。设置为 `0` 可禁用该上限。如果您的 hook 确实需要更多迭代才能解决，请调高此值 |

401| `CLAUDE_CODE_SUBAGENT_MODEL` | 未通过其他方式指定模型的[子代理](/docs/zh-CN/sub-agents#choose-a-model)、[agent team](/docs/zh-CN/agent-teams#specify-teammates-and-models) 队友和[工作流](/docs/zh-CN/workflows) Agent 的默认模型。接受 `haiku` 等别名或完整模型名称。有两个来源优先于它：Claude 在生成 Agent 时传递的模型，以及 Agent 定义中的 `model` 字段（包括 `inherit`）。要改变这一点，请设置 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model)。完整顺序请参阅[选择模型](/docs/zh-CN/sub-agents#choose-a-model)。将其设置为 `inherit` 与不设置相同。在 v2.1.251 之前，此变量会同时覆盖每次调用的模型和定义中的 `model` 字段 |403| `CLAUDE_CODE_SUBAGENT_MODEL` | 未通过其他方式分配模型的[子代理](/docs/zh-CN/sub-agents#choose-a-model)、[agent team](/docs/zh-CN/agent-teams#specify-teammates-and-models) 队友和[工作流](/docs/zh-CN/workflows) Agent 的默认模型。接受诸如 `haiku` 的别名或完整模型名称。有两个来源优先于它：Claude 生成 Agent 时传递的模型，以及 Agent 定义中的 `model` 字段（包括 `inherit`）。要改变这一点，请设置 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model)。有关完整顺序，请参阅[选择模型](/docs/zh-CN/sub-agents#choose-a-model)。将其设置为 `inherit` 与不设置相同。在 v2.1.251 之前，此变量会同时覆盖每次调用的模型和定义中的 `model` 字段 |

402| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 设置为 `1` 可强制子代理、队友和工作流 Agent 使用同一个模型。[让所有子代理使用同一个模型](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model)说明了具体使用哪个模型。需要 Claude Code v2.1.257 或更高版本 |404| `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` | 设置为 `1` 可将同一个模型强制用于子代理、队友和工作流 Agent。[让每个子代理使用同一模型](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model)说明了具体是哪个模型。需要 Claude Code v2.1.257 或更高版本 |

403| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | 设置为 `5m` 或 `1h`（Claude Code 仅接受这两个值），以选择主对话之外的请求（例如[子代理](/docs/zh-CN/sub-agents)、工作流和后台工作）的[提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime)。优先于 `subagentPromptCacheTtl` 设置和 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 会覆盖它。API 对 1 小时缓存写入按更高费率计费。需要 Claude Code v2.1.242 或更高版本 |405| `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL` | 设置为 `5m` 或 `1h`（Claude Code 仅接受这两个值），为主对话之外的请求（例如[子代理](/docs/zh-CN/sub-agents)、工作流和后台工作）选择[提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime)。优先于 `subagentPromptCacheTtl` 设置和 `ENABLE_PROMPT_CACHING_1H`，而 `FORCE_PROMPT_CACHING_5M` 会覆盖它。API 对 1 小时缓存写入按更高费率计费。需要 Claude Code v2.1.242 或更高版本 |

404| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 设置为 `1` 可从 Claude Code 启动的子进程（例如 Bash 命令、hook 和 stdio MCP 服务器）的环境中剥离凭据。清理会根据变量名或变量值识别凭据，并保留 GitHub 令牌和代理设置。请参阅[子进程环境清理会移除哪些内容](#what-the-subprocess-environment-scrub-removes)。配置了 `allowed_non_write_users` 时，`claude-code-action` 会自动设置此变量 |406| `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` | 设置为 `1` 可从 Claude Code 启动的子进程（例如 Bash 命令、hook 和 stdio MCP 服务器）的环境中剥离凭据。清理会通过变量名或变量值识别凭据，并保留 GitHub 令牌和代理设置。请参阅[子进程环境清理会移除哪些内容](#what-the-subprocess-environment-scrub-removes)。配置了 `allowed_non_write_users` 时，`claude-code-action` 会自动设置此项 |

405| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非交互模式（`-p` 标志）下设置为 `1`，可在第一个查询之前等待插件安装完成。否则，插件会在后台安装，可能在第一个轮次中不可用。可与 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 结合使用以限制等待时间 |407| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非交互模式下（`-p` 标志）设置为 `1`，可在第一次查询之前等待插件安装完成。如果不设置，插件会在后台安装，可能在第一轮中不可用。可与 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 结合使用以限制等待时间 |

406| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步插件安装的超时时间（毫秒）。超过后，Claude Code 会在没有插件的情况下继续运行并记录一条错误。没有默认值：如果不设置此变量，同步安装会一直等到完成 |408| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步插件安装的超时时间（毫秒）。超时后，Claude Code 会在没有插件的情况下继续并记录一条错误。无默认值：未设置此变量时，同步安装会一直等到完成 |

407| `CLAUDE_CODE_SYNC_SKILLS` | 在使用 `-p` 标志的非交互模式下设置为 `1`，可使 Claude Code 在该次运行中下载为您的 claude.ai 账户启用的 skill，并在运行第一次查询之前等待其列表，最长等待 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`。需要 claude.ai 身份验证。使用 claude.ai 账户登录的终端会话无需此变量即可[同步这些 skill](/docs/zh-CN/skills#where-synced-skills-load)，因此仅当 `-p` 运行需要在第一次查询时使用您当前的 skill 时才设置它 |409| `CLAUDE_CODE_SYNC_SKILLS` | 在使用 `-p` 标志的非交互模式下设置为 `1`，可让 Claude Code 在该次运行中下载为您的 claude.ai 账户启用的 skill，并在运行第一次查询之前等待获取其列表，最长等待 `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS`。需要 claude.ai 身份验证。使用 claude.ai 账户登录的终端会话无需此变量即可[同步这些 skill](/docs/zh-CN/skills#where-synced-skills-load)，因此仅当 `-p` 运行在第一次查询时就需要您当前的 skill 时才设置它 |

408| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 当基于 [Agent SDK](/docs/zh-CN/agent-sdk/typescript#query-object) 构建的应用重新加载 skill 时，会话中途运行的 skill 重新同步的超时时间（毫秒）（默认值：30000）。超过后，重新加载会使用已到达的 skill 继续，剩余的下载在后台完成 |410| `CLAUDE_CODE_SYNC_SKILLS_INSTALL_TIMEOUT_MS` | 当基于 [Agent SDK](/docs/zh-CN/agent-sdk/typescript#query-object) 构建的应用重新加载 skill 时，在会话中途运行的 skill 重新同步的超时时间（毫秒）（默认：30000）。超时后，重新加载会使用已到达的 skill 继续，剩余的下载会在后台完成 |

409| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 设置了 `CLAUDE_CODE_SYNC_SKILLS` 时，第一个查询等待初始 skill 列表的超时时间（毫秒）（默认值：5000）。超过后，第一个查询会使用已到达的 skill 运行。无论哪种情况，下载都会在后台完成，Claude 在调用某个 skill 时会等待该 skill 下载完成 |411| `CLAUDE_CODE_SYNC_SKILLS_WAIT_TIMEOUT_MS` | 设置 `CLAUDE_CODE_SYNC_SKILLS` 时，第一次查询等待初始 skill 列表的超时时间（毫秒）（默认：5000）。超时后，第一次查询会使用已到达的 skill 运行。无论哪种情况，下载都会在后台完成，并且 Claude 在调用某个 skill 时会等待该 skill 下载完成 |

410| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 设置为 `false` 可在 diff 输出中禁用语法高亮。当颜色干扰您的终端设置时很有用。要同时在代码块和文件预览中禁用高亮，请使用 [`syntaxHighlightingDisabled`](/docs/zh-CN/settings-reference#syntaxhighlightingdisabled) 设置 |412| `CLAUDE_CODE_SYNTAX_HIGHLIGHT` | 设置为 `false` 可禁用 diff 输出中的语法高亮。当颜色干扰您的终端设置时很有用。要同时禁用代码块和文件预览中的高亮，请使用 [`syntaxHighlightingDisabled`](/docs/zh-CN/settings-reference#syntaxhighlightingdisabled) 设置 |

411| `CLAUDE_CODE_TASK_LIST_ID` | 在会话之间共享任务列表。在[具备 Task 工具的会话](/docs/zh-CN/tools-reference#task-tool-availability)中，在多个 Claude Code 实例中设置相同的 ID，即可在共享任务列表上协作。请参阅[任务列表](/docs/zh-CN/interactive-mode#task-list) |413| `CLAUDE_CODE_TASK_LIST_ID` | 在会话之间共享任务列表。在多个 Claude Code 实例中设置相同的 ID，即可在[具备 Task 工具的会话](/docs/zh-CN/tools-reference#task-tool-availability)中协同使用共享任务列表。请参阅[任务列表](/docs/zh-CN/interactive-mode#task-list) |

412| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 覆盖非交互式会话在退出时等待其 [agent team](/docs/zh-CN/agent-teams) 完成拆除的时长（毫秒）。接受 1000 到 60000；超出范围的值会被忽略并应用默认值 10000。需要 Claude Code v2.1.206 或更高版本 |414| `CLAUDE_CODE_TEAM_TEARDOWN_PARK_TIMEOUT_MS` | 以毫秒为单位覆盖非交互式会话在退出时等待其 [agent team](/docs/zh-CN/agent-teams) 完成拆除的时长。接受 1000 到 60000；超出范围的值会被忽略，并使用默认值 10000。需要 Claude Code v2.1.206 或更高版本 |

413| `CLAUDE_CODE_TMPDIR` | 覆盖用于内部临时文件的临时目录。Claude Code 在 Unix 上会将 `/claude-{uid}/` 附加到此路径，在 Windows 上附加 `/claude/`。默认值：macOS 上为 `/tmp`，Linux 和 Windows 上为 `os.tmpdir()`。在 macOS 和 Linux 上，当您的覆盖值是较长路径时，[沙箱化](/docs/zh-CN/sandboxing)的 Bash 子进程会在系统默认位置下收到一个较短的备用 `$TMPDIR`，因为某些工具在临时路径过长时会失败。未沙箱化的 Bash 命令会在您的 shell 设置了 `$TMPDIR` 时继承它。在原生 Windows 上，当您的 shell 未设置 `$TMPDIR` 时，引用 `$TMPDIR` 的 Bash 命令会收到您的覆盖值，如果您未设置覆盖值，则收到 `%TEMP%`。Claude Code 自身的临时文件始终使用您的覆盖值。可在 shell、用户设置或托管设置中设置。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略 |415| `CLAUDE_CODE_TMPDIR` | 覆盖用于内部临时文件的临时目录。Claude Code 在 Unix 上会将 `/claude-{uid}/` 附加到此路径，在 Windows 上则附加 `/claude/`。默认：macOS 上为 `/tmp`，Linux 和 Windows 上为 `os.tmpdir()`。在 macOS 和 Linux 上，当您的覆盖值是较长路径时，[沙箱隔离](/docs/zh-CN/sandboxing)的 Bash 子进程会收到系统默认目录下一个较短的备用 `$TMPDIR`，因为某些工具在临时路径过长时会失败。未沙箱隔离的 Bash 命令会在您的 shell 设置了 `$TMPDIR` 时继承它。在原生 Windows 上，当您的 shell 未设置 `$TMPDIR` 时，引用 `$TMPDIR` 的 Bash 命令会收到您的覆盖值，或在您未设置覆盖值时收到 `%TEMP%`。Claude Code 自身的临时文件始终使用您的覆盖值。请在您的 shell、用户设置或托管设置中设置。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略 |

414| `CLAUDE_CODE_TMUX_TRUECOLOR` | 设置为任何非空值（例如 `1`）可允许在 tmux 中输出 24 位真彩色。**将其设置为 `0` 或 `false` 仍会允许真彩色**，这与大多数开/关变量不同；取消设置该变量可恢复 256 色限制。默认情况下，当设置了 `$TMUX` 时，Claude Code 会限制为 256 色，因为除非经过配置，否则 tmux 不会透传真彩色转义序列。请在将 `set -ga terminal-overrides ',*:Tc'` 添加到 `~/.tmux.conf` 之后设置此变量。有关其他 tmux 设置，请参阅[终端配置](/docs/zh-CN/terminal-config) |416| `CLAUDE_CODE_TMUX_TRUECOLOR` | 设置为任意非空值（例如 `1`）可允许在 tmux 中输出 24 位真彩色。**将其设置为 `0` 或 `false` 仍会允许真彩色**，这与大多数开关变量不同；取消设置该变量可恢复 256 色限制。默认情况下，当设置了 `$TMUX` 时，Claude Code 会限制为 256 色，因为除非进行配置，否则 tmux 不会透传真彩色转义序列。请在将 `set -ga terminal-overrides ',*:Tc'` 添加到您的 `~/.tmux.conf` 后设置此项。有关其他 tmux 设置，请参阅[终端配置](/docs/zh-CN/terminal-config) |

415| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | 在 Linux 和 WSL 上，设置为以逗号分隔的进程类型列表，Claude Code 会将这些类型的进程[排除在工具内存上限之外](/docs/zh-CN/tools-reference#memory-limit-on-linux-and-wsl)，例如 `mcp` 或 `lsp`。设置为 `none` 可对所有类型施加上限，设置为 `all-new` 则仅对 Bash、PowerShell 和 Monitor 工具命令施加上限。无论您列出什么，Claude Code 都会让 Bash、PowerShell 和 Monitor 工具命令受该上限约束。需要 Claude Code v2.1.246 或更高版本 |417| `CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE` | 在 Linux 和 WSL 上，设置为以逗号分隔的进程类型列表，Claude Code 会将这些类型的进程[排除在工具内存上限之外](/docs/zh-CN/tools-reference#memory-limit-on-linux-and-wsl)，例如 `mcp` 或 `lsp`。设置为 `none` 可对所有类型设置上限，设置为 `all-new` 则仅对 Bash、PowerShell 和 Monitor 工具命令设置上限。无论您列出什么，Claude Code 都会将 Bash、PowerShell 和 Monitor 工具命令保持在上限之下。需要 Claude Code v2.1.246 或更高版本 |

416| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | 在 Linux 和 WSL 上，设置为 `4G` 等大小可[限制 Bash 和 PowerShell 工具命令可使用的内存](/docs/zh-CN/tools-reference#memory-limit-on-linux-and-wsl)，在 v2.1.246 或更高版本中还包括 Monitor 工具命令。请用纯数字书写大小，单独的数字表示字节数，也可以带 `K`、`M`、`G` 或 `T` 后缀。设置为 `0` 或 `off` 可关闭上限。一旦 Claude Code 启动的第一个进程开启或关闭了上限，更改后的值将在您下次启动 `claude` 时生效。需要 Claude Code v2.1.233 或更高版本 |418| `CLAUDE_CODE_TOOL_MEMORY_LIMIT` | 在 Linux 和 WSL 上，设置为诸如 `4G` 的大小，以[限制 Bash 和 PowerShell 工具命令可使用的内存](/docs/zh-CN/tools-reference#memory-limit-on-linux-and-wsl)，在 v2.1.246 或更高版本上也包括 Monitor 工具命令。请以纯数字书写大小，单独使用表示字节数，或带上 `K`、`M`、`G` 或 `T` 后缀。设置为 `0` 或 `off` 可关闭上限。一旦 Claude Code 启动的第一个进程已开启或关闭上限，更改后的值将在您下次启动 `claude` 时生效。需要 Claude Code v2.1.233 或更高版本 |

417| `CLAUDE_CODE_TRANSCRIPT_LOCAL_GC` | 设置为 `1` 可限制长时间运行的 `-p` 或 Agent SDK 会话的[会话记录文件](/docs/zh-CN/sessions#where-transcripts-are-stored)的增长大小。每次压缩后，一旦文件超过 5 MB，Claude Code 会删除该次压缩之前的历史记录。无论文件是否被裁剪，恢复会话都会还原相同的对话。请在启动 Claude Code 的环境中设置它，因为设置文件的 `env` 块无法开启它。需要 Claude Code v2.1.287 或更高版本 |419| `CLAUDE_CODE_TRANSCRIPT_LOCAL_GC` | 设置为 `1` 可限制长时间运行的 `-p` 或 Agent SDK 会话的[会话记录文件](/docs/zh-CN/sessions#where-transcripts-are-stored)的增长大小。每次压缩后，一旦文件大于 5 MB，Claude Code 就会移除该次压缩之前的历史。无论文件是否被裁剪，恢复会话都会还原相同的对话。请在您启动 Claude Code 的环境中设置它，因为设置中的 `env` 块无法开启它。需要 Claude Code v2.1.287 或更高版本 |

418| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code 取消转发给远程客户端（例如 [Remote Control](/docs/zh-CN/remote-control) 或 SDK 宿主）的对话框，或取消[被暂扣的跨会话消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)的批准对话框之前的截止时间（毫秒）；权限提示和 `AskUserQuestion` 问题使用各自的流程，不受其约束。在 Claude Code v2.1.236 或更高版本中，它还会在可能无人值守运行的会话中限制会话中途出现的 [Fable 使用额度同意提示](/docs/zh-CN/model-config#fable-and-usage-credits)。[控制入站消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)和[非交互式会话](/docs/zh-CN/cross-session-messaging#non-interactive-sessions)涵盖了完整的暂扣消息过期规则，包括截止时间不适用的情况。覆盖 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 设置。`0` 或负值会禁用截止时间 |420| `CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS` | Claude Code 取消转发给远程客户端（例如 [Remote Control](/docs/zh-CN/remote-control) 或 SDK 宿主）的对话框，或取消[被暂扣的跨会话消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)的批准对话框之前的截止时间（毫秒）；权限提示和 `AskUserQuestion` 问题使用各自的流程，不受其约束。在 Claude Code v2.1.236 或更高版本上，它还会限制可能处于无人值守运行状态的会话中途出现的 [Fable 使用额度同意提示](/docs/zh-CN/model-config#fable-and-usage-credits)。[控制入站消息](/docs/zh-CN/cross-session-messaging#control-inbound-messages)和[非交互式会话](/docs/zh-CN/cross-session-messaging#non-interactive-sessions)涵盖了完整的暂扣消息过期规则，包括截止时间不适用的情况。覆盖 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 设置。`0` 或负值会禁用截止时间。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略 |

423| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 设置为 `1` 可使用 Node.js 文件 API 而不是 ripgrep 来发现自定义命令、子代理和输出样式。如果捆绑的 ripgrep 二进制文件在您的环境中不可用或被阻止，请设置此项。不影响 Grep 或文件搜索工具 |425| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 设置为 `1` 以使用 Node.js 文件 API 而非 ripgrep 来发现自定义命令、子代理和输出样式。如果捆绑的 ripgrep 二进制文件在您的环境中不可用或被阻止，请设置此项。不影响 Grep 或文件搜索工具 |

424| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在未安装 Git Bash 的 Windows 上，该工具会自动启用；设置为 `0` 可将其禁用。在已安装 Git Bash 的 Windows 上，该工具对 claude.ai 和 Console 账户默认开启；在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 会话中，设置为 `1` 可将其启用，设置为 `0` 可将其关闭。在 Linux、macOS 和 WSL 上，设置为 `1` 可将其启用，这要求 `PATH` 中存在 `pwsh`。在 Windows 上启用后，Claude 可以原生运行 PowerShell 命令，而无需通过 Git Bash 中转。参见 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool) |426| `CLAUDE_CODE_USE_POWERSHELL_TOOL` | 控制 PowerShell 工具。在未安装 Git Bash 的 Windows 上，该工具会自动启用；设置为 `0` 可将其禁用。在已安装 Git Bash 的 Windows 上，对于 claude.ai 和 Console 账户，该工具默认开启；设置为 `1` 可在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 会话中启用它，设置为 `0` 则将其关闭。在 Linux、macOS 和 WSL 上，设置为 `1` 可启用它，这需要 `PATH` 中有 `pwsh`。在 Windows 上启用后，Claude 可以原生运行 PowerShell 命令，而无需通过 Git Bash 路由。请参阅 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool) |

426| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | 设置 [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior) 将每个已获取 URL 的响应保留在缓存中的毫秒数。默认值为 `900000`，即 15 分钟。仅接受纯数字；`0`、小数或任何其他写法都会保留默认值。Claude Code 每次启动时只读取一次该值，因此在设置的 `env` 块中所做的更改会在您下次启动 `claude` 时生效。需要 Claude Code v2.1.233 或更高版本 |428| `CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS` | 设置为 [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior) 缓存每个已获取 URL 的响应的毫秒数。默认值为 `900000`，即 15 分钟。仅接受纯数字；`0`、小数或任何其他写法都会保持默认值。Claude Code 每次启动时读取一次该值，因此在设置的 `env` 块中所做的更改将在您下次启动 `claude` 时生效。需要 Claude Code v2.1.233 或更高版本 |

427| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior) 等待页面下载完成（包括其跟随的所有重定向）的最长时间上限，以毫秒为单位。到时仍未完成的下载会因截止时间错误而失败。默认值为 `300000`，即五分钟。设置为 `0` 可取消该限制。仅接受纯数字；小数或任何其他写法都会保留默认值。需要 Claude Code v2.1.268 或更高版本 |429| `CLAUDE_CODE_WEBFETCH_DEADLINE_MS` | [WebFetch](/docs/zh-CN/tools-reference#webfetch-tool-behavior) 等待页面下载（包括其跟随的任何重定向）的时长上限，以毫秒为单位。到时仍未完成的下载将因截止时间错误而失败。默认值为 `300000`，即五分钟。设置为 `0` 可取消该限制。仅接受纯数字；小数或任何其他写法都会保持默认值。需要 Claude Code v2.1.268 或更高版本 |

428| `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` | 当 `CLAUDE_AUTO_BACKGROUND_TASKS` 设置为 `1` 时，Claude Code 在每次提醒 Claude 检查仍在运行的[后台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)之前等待的时间。接受一个或多个以逗号分隔的等待时间，单位为整秒，范围为 `1` 到 `86400`，例如 `600` 或 `600,1800,3600`。每个值表示下一次提醒之前的等待时间，最后一个值会重复使用。仅接受纯数字；任何其他值或写法都视为未设置。未设置时不会发出提醒。需要 Claude Code v2.1.283 或更高版本 |430| `CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR` | 会话的 [WebSearch 限制](/docs/zh-CN/tools-reference#session-search-limit)的补充速率，以每小时调用次数计。在交互式终端会话中默认值为 `100`。在[非交互](/docs/zh-CN/headless)会话中默认值为 `0`，即关闭补充。仅接受纯数字；任何其他写法均视为未设置。需要 Claude Code v2.1.290 或更高版本 |

429| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | 单次[工作流](/docs/zh-CN/workflows)运行同时执行的 Agent 数量，范围为 `1` 到 `256`。默认情况下，一次运行最多同时执行 16 个 Agent，当 Claude Code 可用的 CPU 较少时会更少；排队的 `agent()` 调用会等待空闲槽位。每个正在运行的 Agent 的会话记录都保留在 Claude Code 的内存中，因此较高的值会增加内存使用量。仅接受纯数字；超出范围的值和其他写法都会保留默认值。需要 Claude Code v2.1.269 或更高版本 |431| `CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE` | 当 `CLAUDE_AUTO_BACKGROUND_TASKS` 设置为 `1` 时，Claude Code 在每次提醒 Claude 检查仍在运行的[后台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)之前等待的时长。接受一个或多个以逗号分隔的等待时间，以整秒为单位，范围为 `1` 到 `86400`，例如 `600` 或 `600,1800,3600`。每个值是下一次提醒之前的等待时间，最后一个值会重复使用。仅接受纯数字；任何其他值或写法均视为未设置。未设置时不会发送提醒。需要 Claude Code v2.1.283 或更高版本 |

430| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流](/docs/zh-CN/workflows) Agent 在发送自己的第一个请求之前，等待具有相同前缀的同级 Agent 的第一个响应开始的最长时间上限，以毫秒为单位。当一次扇出启动多个共享[提示缓存前缀](/docs/zh-CN/workflows#prompt-caching-in-a-fan-out)的 Agent 时，Claude Code 会让除第一个 Agent 之外的所有 Agent 最多等待这么长时间，以便其余 Agent 读取已缓存的前缀，而不是各自在无缓存的情况下处理该前缀。默认值为 `5000`。设置为 `0` 可禁用等待。设置了 `DISABLE_PROMPT_CACHING` 时，Agent 永远不会等待。需要 Claude Code v2.1.229 或更高版本 |432| `CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS` | 单次[工作流](/docs/zh-CN/workflows)运行同时执行的 Agent 数量，范围为 `1` 到 `256`。默认情况下，一次运行最多同时执行 16 个 Agent，当 Claude Code 可用的 CPU 较少时会更少；排队的 `agent()` 调用会等待空闲槽位。每个运行中 Agent 的会话记录都保留在 Claude Code 的内存中，因此较高的值会增加内存使用。仅接受纯数字；超出范围的值和其他写法会保持默认值。需要 Claude Code v2.1.269 或更高版本 |

431| `CLAUDE_CONFIG_DIR` | 覆盖配置目录（默认：`~/.claude`）。所有设置、会话历史和插件都存储在此路径下。关于凭据，请参见 [Claude Code 存储凭据的位置](/docs/zh-CN/authentication#credential-management)。适用于并行运行多个账户：例如 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。请在 shell、用户设置或托管设置中设置它。在设置文件中，请填写[绝对路径](#in-settings-files)。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略 |433| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流](/docs/zh-CN/workflows) Agent 在发送自己的第一个请求之前，等待具有相同前缀的同级 Agent 的第一个响应开始的时长上限，以毫秒为单位。当扇出启动多个共享[提示缓存前缀](/docs/zh-CN/workflows#prompt-caching-in-a-fan-out)的 Agent 时，Claude Code 会将除第一个之外的所有 Agent 最多保留这么长时间，以便其余 Agent 读取已缓存的前缀，而不是各自在未缓存的情况下处理它。默认值为 `5000`。设置为 `0` 可禁用等待。设置了 `DISABLE_PROMPT_CACHING` 时，Agent 从不等待。需要 Claude Code v2.1.229 或更高版本 |

432| `CLAUDE_DISABLE_ADOPT` | 设置为 `1` 后，当您按 `←` 或使用 [`/background`](/docs/zh-CN/agent-view#from-inside-a-session) 将会话转入后台时，会停止正在进行的后台工作，而不是将其延续下去。Claude Code 会在转入后台之前请您确认，然后停止原本会延续的任务。需要 Claude Code v2.1.195 或更高版本 |434| `CLAUDE_CONFIG_DIR` | 覆盖配置目录（默认：`~/.claude`）。所有设置、会话历史和插件都存储在此路径下。关于凭据，请参阅 [Claude Code 存储凭据的位置](/docs/zh-CN/authentication#credential-management)。适用于并行运行多个账户：例如 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。在您的 shell、用户设置或托管设置中设置它。在设置文件中，请写入[绝对路径](#in-settings-files)。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略 |

433| `CLAUDE_EFFORT` | 在 Bash 工具子进程和 hook 命令中自动设置为子进程启动时生效的 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。与传递给 [hook](/docs/zh-CN/hooks) 的 `effort.level` 字段一致。仅当当前模型支持 effort 参数时才会设置 |435| `CLAUDE_DISABLE_ADOPT` | 设置为 `1` 后，当您按 `←` 或使用 [`/background`](/docs/zh-CN/agent-view#from-inside-a-session) 将会话转入后台时，会停止正在进行的后台工作，而不是将其延续。Claude Code 会在转入后台前请您确认，然后停止原本会延续的任务。需要 Claude Code v2.1.195 或更高版本 |

434| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 设置为 `1` 可强制启用字节级流式空闲看门狗，设置为 `0` 可强制禁用。`0` 还会在运行[首字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs)的连接上关闭该截止时间。未设置时，该看门狗默认在直连 Anthropic API 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 的连接上启用，并在通过 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 访问的[网关](/docs/zh-CN/gateways)连接上对流式响应启用；在 v2.1.222 之前，它不会在这些网关连接上运行，因此即使仍有 keep-alive ping 到达，事件级看门狗也可能在这些连接上报告停滞。关于超时时间以及各计时器之间的相互作用，请参见[流式空闲看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |436| `CLAUDE_EFFORT` | 在 Bash 工具子进程和 hook 命令中自动设置为子进程启动时生效的 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。与传递给 [hook](/docs/zh-CN/hooks) 的 `effort.level` 字段一致。仅在当前模型支持 effort 参数时设置 |

435| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 设置为 `1` 可在 Amazon Bedrock `vnd.amazon.eventstream` 响应上启用字节级流式空闲看门狗，这也会在 Bedrock 流式请求上启用[首字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs)。默认关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时时间 |437| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 设置为 `1` 以强制启用字节级流式空闲看门狗，或设置为 `0` 以强制禁用它。`0` 还会在运行[首字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs)的连接上关闭该截止时间。未设置时，看门狗默认对直连 Anthropic API 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 的连接启用，也对通过 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 访问的[网关](/docs/zh-CN/gateways)连接上的流式响应启用；在 v2.1.222 之前，它不会在这些网关连接上运行，因此即使 keep-alive ping 正在到达，事件级看门狗也可能在那里报告停滞。关于超时以及各计时器如何相互作用，请参阅[流式空闲看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |

436| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 设置为 `0` 可强制禁用事件级流式空闲看门狗，设置为 `1` 可强制启用。未设置时，该看门狗对所有提供商默认开启。在 v2.1.196 之前，未设置时的默认值在直连 Anthropic API 上由服务器控制，在其他提供商上则为关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时时间；关于与其并行运行的其他停滞计时器，请参见[流式空闲看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |438| `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK` | 设置为 `1` 以在 Amazon Bedrock `vnd.amazon.eventstream` 响应上启用字节级流式空闲看门狗，这也会在 Bedrock 流式请求上启用[首字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs)。默认关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时时间 |

437| `CLAUDE_ENV_FILE` | shell 脚本的路径，Claude Code 会在每条 Bash 命令之前于同一 shell 进程中运行该脚本的内容，因此文件中的导出对命令可见。可用于在多条命令之间保持 virtualenv 或 conda 的激活状态。也会由 [SessionStart](/docs/zh-CN/hooks#persist-environment-variables)、[Setup](/docs/zh-CN/hooks#setup)、[CwdChanged](/docs/zh-CN/hooks#cwdchanged) 和 [FileChanged](/docs/zh-CN/hooks#filechanged) hook 动态填充 |439| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 设置为 `0` 以强制禁用事件级流式空闲看门狗，或设置为 `1` 以强制启用它。未设置时，看门狗对所有提供商默认开启。在 v2.1.196 之前，未设置时的默认值在直连 Anthropic API 上由服务器控制，在其他提供商上则为关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时时间；关于与此看门狗同时运行的其他停滞计时器，请参阅[流式空闲看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |

438| `CLAUDE_JOB_DIR` | 由 Claude Code 在每个[后台会话](/docs/zh-CN/agent-view)中设置为该会话的 `~/.claude/jobs/<id>` 目录。会话运行的 shell 命令会继承该变量。请将临时文件写入 [`$CLAUDE_JOB_DIR/tmp`](/docs/zh-CN/agent-view#where-state-is-stored)。Claude 在该目录中的 `Write` 和 `Edit` 调用不会提示请求权限，并且该目录会在会话被删除时一并移除 |440| `CLAUDE_ENV_FILE` | shell 脚本的路径，Claude Code 会在同一 shell 进程中于每个 Bash 命令之前运行其内容，因此文件中的导出对该命令可见。用于在命令之间保持 virtualenv 或 conda 的激活状态。也会由 [SessionStart](/docs/zh-CN/hooks#persist-environment-variables)、[Setup](/docs/zh-CN/hooks#setup)、[CwdChanged](/docs/zh-CN/hooks#cwdchanged) 和 [FileChanged](/docs/zh-CN/hooks#filechanged) hook 动态填充 |

439| `CLAUDE_PID` | Claude Code 会在其派生的子进程（Bash 和 PowerShell 工具命令以及 hook 命令）中将此变量设置为自身的进程 ID。在 Linux 上，Bash 工具的 shell 集成会用它来拒绝会匹配到 Claude Code 进程自身的 `pkill` 模式；请参见[错误参考](/docs/zh-CN/errors#pkill-pattern-matches-the-claude-code-process)。您可以在自己的脚本中读取它，以便有意地识别父 Claude Code 进程或向其发送信号。需要 Claude Code v2.1.214 或更高版本 |441| `CLAUDE_JOB_DIR` | 由 Claude Code 在每个[后台会话](/docs/zh-CN/agent-view)中设置为该会话的 `~/.claude/jobs/<id>` 目录。该会话运行的 shell 命令会继承它。请将临时文件写入 [`$CLAUDE_JOB_DIR/tmp`](/docs/zh-CN/agent-view#where-state-is-stored)。Claude 在该处的 `Write` 和 `Edit` 调用不会请求权限，并且该目录会在会话被删除时移除 |

440| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 未提供显式名称时，自动生成的 [Remote Control](/docs/zh-CN/remote-control) 会话名称的前缀。默认为您计算机的主机名，生成类似 `myhost-graceful-unicorn` 的名称。`--remote-control-session-name-prefix` CLI 标志可为单次调用设置相同的值 |442| `CLAUDE_PID` | Claude Code 在其生成的子进程（Bash 和 PowerShell 工具命令以及 hook 命令）中将此变量设置为其自身的进程 ID。在 Linux 上，Bash 工具的 shell 集成会使用它来拒绝会匹配 Claude Code 进程本身的 `pkill` 模式；请参阅[错误参考](/docs/zh-CN/errors#pkill-pattern-matches-the-claude-code-process)。您可以在自己的脚本中读取它，以有意识地识别父 Claude Code 进程或向其发送信号。需要 Claude Code v2.1.214 或更高版本 |

441| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | 在运行[首字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs)的连接上，流式请求首个响应字节的截止时间，以毫秒为单位。关于 Claude Code 如何限制该值、为大型请求体额外增加的时间，以及在您未设置该变量时如何选择截止时间，请参见 [No response from API](/docs/zh-CN/errors#no-response-from-api)。需要 Claude Code v2.1.242 或更高版本 |443| `CLAUDE_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 未提供显式名称时，自动生成的 [Remote Control](/docs/zh-CN/remote-control) 会话名称的前缀。默认为您机器的主机名，生成类似 `myhost-graceful-unicorn` 的名称。`--remote-control-session-name-prefix` CLI 标志可为单次调用设置相同的值 |

442| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件级和字节级流式空闲看门狗关闭停滞连接之前的超时时间，以毫秒为单位。当您显式设置此变量时，最小值为 `300000`（5 分钟）；较低的值会被静默提升到该下限，以吸收扩展思考的停顿和代理缓冲，并且字节级看门狗会将该值上限设为 30 分钟。对于字节级看门狗，`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 优先于此变量。关于每个看门狗在未设置时的默认值，请参见[流式空闲看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |444| `CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS` | 在运行[首字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs)的连接上，流式请求第一个响应字节的截止时间，以毫秒为单位。关于 Claude Code 如何限制该值、为大型请求体额外增加的时间，以及未设置时如何选择截止时间，请参阅 [No response from API](/docs/zh-CN/errors#no-response-from-api)。需要 Claude Code v2.1.242 或更高版本 |

443| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | 已在 v2.1.260 中移除，现在不起任何作用。以前用于限制由[子代理](/docs/zh-CN/sub-agents)启动的[后台 shell 命令](/docs/zh-CN/interactive-mode#background-bash-commands)可运行的时长，以毫秒为单位，默认值为 60 分钟。请参见[后台命令生命周期规则](/docs/zh-CN/tools-reference#background-commands) |445| `CLAUDE_STREAM_IDLE_TIMEOUT_MS` | 事件级和字节级流式空闲看门狗关闭停滞连接之前的超时时间，以毫秒为单位。显式设置此变量时，最小值为 `300000`（5 分钟）；较低的值会被静默提升，以容纳扩展思考的停顿和代理缓冲，字节级看门狗将该值上限设为 30 分钟。对于字节级看门狗，`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 优先于此变量。关于各看门狗在未设置时的默认值，请参阅[流式空闲看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |

444| `DEBUG` | 设置为 `1` 可启用调试模式，等同于使用 [`--debug`](/docs/zh-CN/cli-reference#cli-flags) 启动。调试日志会写入 `~/.claude/debug/<session-id>.txt`，或写入由 `CLAUDE_CODE_DEBUG_LOGS_DIR` 设置的路径。只有真值 `1`、`true`、`yes` 和 `on` 会启用调试模式，因此为其他工具设置的命名空间模式（如 `DEBUG=express:*`）不会触发它 |446| `CLAUDE_SUBAGENT_BG_SHELL_MAX_MS` | 已在 v2.1.260 中移除，现在不起任何作用。以前用于限制[子代理](/docs/zh-CN/sub-agents)启动的[后台 shell 命令](/docs/zh-CN/interactive-mode#background-bash-commands)可运行的时长，以毫秒为单位，默认值为 60 分钟。请参阅[后台命令生命周期规则](/docs/zh-CN/tools-reference#background-commands) |

445| `DISABLE_AUTOUPDATER` | 设置为 `1` 可禁用自动后台更新。手动执行 `claude update` 仍然有效。使用 `DISABLE_UPDATES` 可同时阻止两者 |447| `DEBUG` | 设置为 `1` 以启用调试模式，等同于使用 [`--debug`](/docs/zh-CN/cli-reference#cli-flags) 启动。调试日志写入 `~/.claude/debug/<session-id>.txt`，或写入 `CLAUDE_CODE_DEBUG_LOGS_DIR` 设置的路径。只有真值 `1`、`true`、`yes` 和 `on` 会启用调试模式，因此为其他工具设置的命名空间模式（如 `DEBUG=express:*`）不会触发它 |

446| `DISABLE_AUTO_COMPACT` | 设置为 `1` 可禁用接近上下文限制时的自动压缩。手动 `/compact` 命令仍然可用。适用于您希望显式控制何时进行压缩的情况。覆盖 [`autoCompactEnabled`](/docs/zh-CN/settings-reference#autocompactenabled) 设置 |448| `DISABLE_AUTOUPDATER` | 设置为 `1` 以禁用自动后台更新。手动 `claude update` 仍然有效。使用 `DISABLE_UPDATES` 可同时阻止两者 |

449| `DISABLE_DOCTOR_COMMAND` | 设置为 `1` 可隐藏 [`/doctor`](/docs/zh-CN/commands#all-commands) 设置检查 skill 及其 `/checkup` 别名。适用于不希望用户在会话中运行设置诊断的托管部署。不影响 `claude doctor` 终端命令。在 v2.1.205 之前，此变量会隐藏 `/doctor` 诊断界面命令 |451| `DISABLE_COST_WARNINGS` | 设置为 `1` 以禁用费用警告消息 |

450| `DISABLE_ERROR_REPORTING` | 设置为任意非空值（例如 `1`）可选择退出错误报告。与大多数开/关变量不同，**将其设置为 `0` 或 `false` 仍会选择退出**；取消设置该变量即可重新开启错误报告 |452| `DISABLE_DOCTOR_COMMAND` | 设置为 `1` 以隐藏 [`/doctor`](/docs/zh-CN/commands#all-commands) 环境配置检查 skill 及其 `/checkup` 别名。适用于用户不应在会话中运行环境配置诊断的托管部署。不影响 `claude doctor` 终端命令。在 v2.1.205 之前，此变量会隐藏 `/doctor` 诊断界面命令 |

452| `DISABLE_FEEDBACK_COMMAND` | 设置为 `1` 可禁用 `/feedback` 命令和 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)。还会禁用 `/bug` 和 `/share`，它们通过相同的途径进行报告；在 v2.1.212 之前，它们是 `/feedback` 的别名，因此该命令在所有名称下都会被禁用。也接受旧名称 `DISABLE_BUG_COMMAND` |454| `DISABLE_EXTRA_USAGE_COMMAND` | 设置为 `1` 以隐藏 `/usage-credits` 命令，该命令允许用户购买超出速率限制的额外用量 |

453| `DISABLE_GROWTHBOOK` | 设置为 `1` 或 `true` 可禁用 GrowthBook 功能标志获取，并对每个标志使用代码中的默认值。这会导致 [Remote Control](/docs/zh-CN/remote-control#requirements) 以及其他[需要获取功能标志的功能](#features-that-need-feature-flag-fetching)不可用。将其设置为 `0` 或 `false` 会保持获取开启。除非同时设置了 `DISABLE_TELEMETRY`，否则遥测事件日志记录仍保持开启 |455| `DISABLE_FEEDBACK_COMMAND` | 设置为 `1` 以禁用 `/feedback` 命令和 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)。还会禁用通过同一路径报告的 `/bug` 和 `/share`；在 v2.1.212 之前，它们是 `/feedback` 的别名，因此该命令在所有名称下都会被禁用。也接受旧名称 `DISABLE_BUG_COMMAND` |

454| `DISABLE_INSTALLATION_CHECKS` | 设置为 `1` 可禁用安装警告。仅在手动管理安装位置时使用，因为这可能会掩盖标准安装中的问题 |456| `DISABLE_GROWTHBOOK` | 设置为 `1` 或 `true` 以禁用 GrowthBook 功能标志获取，并对每个标志使用代码默认值。这会使 [Remote Control](/docs/zh-CN/remote-control#requirements) 和其他[需要获取功能标志的功能](#features-that-need-feature-flag-fetching)不可用。将其设置为 `0` 或 `false` 会保持获取开启。除非同时设置了 `DISABLE_TELEMETRY`，否则遥测事件日志记录保持开启 |

456| `DISABLE_INTERLEAVED_THINKING` | 设置为 `1` 可阻止发送 interleaved-thinking beta 标头。适用于您的 LLM 网关或提供商不支持[交错思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)的情况 |458| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 设置为 `1` 以隐藏 `/install-github-app` 命令。使用第三方提供商（Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry）时已隐藏 |

457| `DISABLE_LOGIN_COMMAND` | 设置为 `1` 可隐藏 `/login` 命令。适用于通过 API 密钥或 `apiKeyHelper` 在外部处理身份验证的情况 |459| `DISABLE_INTERLEAVED_THINKING` | 设置为 `1` 以阻止发送 interleaved-thinking beta 标头。当您的 LLM 网关或提供商不支持[交错思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)时很有用 |

464| `DISABLE_TELEMETRY` | 设置为任意非空值（例如 `1`）可选择退出遥测。与大多数开/关变量不同，**将其设置为 `0` 或 `false` 仍会选择退出**；取消设置该变量即可重新开启遥测。遥测事件不包含代码、文件路径或 Bash 命令等用户数据。还会禁用[功能标志获取](#features-that-need-feature-flag-fetching)。请参见[为您的组织关闭遥测](/docs/zh-CN/managed-settings#turn-telemetry-off-for-your-organization) |466| `DISABLE_PROMPT_CACHING_SONNET` | 设置为 `1` 以对[默认 Sonnet 模型](/docs/zh-CN/prompt-caching#disable-prompt-caching)禁用提示缓存 |

465| `DISABLE_UPDATES` | 设置为 `1` 可阻止所有更新，包括手动执行的 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更严格。适用于通过您自己的渠道分发 Claude Code 且用户不应自行更新的情况 |467| `DISABLE_TELEMETRY` | 设置为任意非空值（例如 `1`）以选择退出遥测。**与大多数开关变量不同，将其设置为 `0` 或 `false` 仍会选择退出**；取消设置该变量可重新开启遥测。遥测事件不包含用户数据，例如代码、文件路径或 Bash 命令。还会禁用[功能标志获取](#features-that-need-feature-flag-fetching)。请参阅[为您的组织关闭遥测](/docs/zh-CN/managed-settings#turn-telemetry-off-for-your-organization) |

467| `DO_NOT_TRACK` | 设置为 `1` 可选择退出遥测，效果与 `DISABLE_TELEMETRY` 相同，包括对[功能标志获取](#features-that-need-feature-flag-fetching)的影响。Claude Code 将此变量作为标准布尔值读取，因此 `0` 会保持遥测开启，并且会遵循这一被许多开发者 CLI 认可的跨工具约定 |469| `DISABLE_UPGRADE_COMMAND` | 设置为 `1` 以隐藏 `/upgrade` 命令 |

468| `ENABLE_BETA_TRACING_DETAILED` | 设置为 `1`，并将 `BETA_TRACING_ENDPOINT` 设置为您的 OTLP/HTTP 收集器端点，即可开启[详细 beta 追踪](/docs/zh-CN/monitoring-usage#traces-beta)，它会添加包含内容的 span 属性以及 `claude_code.hook` span。交互式 CLI 会话还要求您的组织已被列入该 beta 的允许列表。这两个变量在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中都会被忽略 |470| `DO_NOT_TRACK` | 设置为 `1` 以选择退出遥测，效果与 `DISABLE_TELEMETRY` 相同，包括对[功能标志获取](#features-that-need-feature-flag-fetching)的影响。Claude Code 将此变量作为标准布尔值读取，因此 `0` 会保持遥测开启；Claude Code 遵循此变量，是因为它是许多开发者 CLI 都认可的跨工具约定 |

469| `ENABLE_CLAUDEAI_MCP_SERVERS` | 设置为 `false` 可阻止 Claude Code 获取 [claude.ai MCP 服务器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)。对已登录用户默认启用。如需按项目或按组织禁用，请改为在设置中设置 [`disableClaudeAiConnectors`](/docs/zh-CN/settings-reference#disableclaudeaiconnectors) |471| `ENABLE_BETA_TRACING_DETAILED` | 设置为 `1`，并将 `BETA_TRACING_ENDPOINT` 设置为您的 OTLP/HTTP 收集器端点，以开启[详细 beta 追踪](/docs/zh-CN/monitoring-usage#traces-beta)，它会添加携带内容的 span 属性和 `claude_code.hook` span。交互式 CLI 会话还要求您的组织已被列入该 beta 的允许列表。这两个变量在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中都会被忽略 |

470| `ENABLE_PROMPT_CACHING_1H` | 设置为 `1` 可请求 1 小时的[提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime)，而不是默认的 5 分钟。适用于 API 密钥、[Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai)、[Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 用户。在包含用量范围内的订阅用户会在[主对话](/docs/zh-CN/prompt-caching#which-ttl-each-request-gets)上自动获得 1 小时 TTL。使用[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)的订阅用户可以设置此变量以保留 1 小时 TTL。1 小时缓存写入按更高费率计费。如需改为按请求类别选择 TTL，请使用 `CLAUDE_CODE_PROMPT_CACHE_TTL` 和 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`，它们优先于此变量 |472| `ENABLE_CLAUDEAI_MCP_SERVERS` | 设置为 `false` 以阻止 Claude Code 获取 [claude.ai MCP 服务器](/docs/zh-CN/mcp#use-mcp-servers-from-claude-ai)。对已登录用户默认启用。要按项目或按组织禁用，请改为在设置中设置 [`disableClaudeAiConnectors`](/docs/zh-CN/settings-reference#disableclaudeaiconnectors) |

473| `ENABLE_PROMPT_CACHING_1H` | 设置为 `1` 以请求 1 小时的[提示缓存 TTL](/docs/zh-CN/prompt-caching#cache-lifetime)，而不是默认的 5 分钟。适用于 API 密钥、[Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai)、[Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 用户。在包含用量范围内的订阅用户会在[主对话](/docs/zh-CN/prompt-caching#which-ttl-each-request-gets)上自动获得 1 小时 TTL。使用[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)的订阅用户可以设置此变量以保持 1 小时 TTL。1 小时缓存写入按更高费率计费。要改为按请求类别选择 TTL，请使用 `CLAUDE_CODE_PROMPT_CACHE_TTL` 和 `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`，它们优先于此变量 |

472| `ENABLE_TOOL_SEARCH` | 控制 [MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)。未设置时，Claude Code 默认延迟加载所有 MCP 工具。但在 Google Cloud's Agent Platform 上早于 Claude 4.5 代的模型、托管在 Azure 上的 Microsoft Foundry 部署，以及 `ANTHROPIC_BASE_URL` 指向非第一方主机时，它仍会预先加载这些工具。`true` 始终延迟加载并发送 beta 标头，但上述 Agent Platform 模型和 Microsoft Foundry 部署除外；在不支持 `tool_reference` 的代理上，请求会失败。`auto` 在工具定义占上下文不超过 10% 时预先加载。`auto:N` 设置自定义阈值，例如 `auto:5` 表示 5%。`false` 预先加载所有工具。设置了 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 时，您自行设置的值会被忽略。在 v2.1.221 之前，除非您将此变量设置为 `true`，否则 Claude Code 会为 Google Cloud's Agent Platform 上的所有模型禁用工具搜索 |475| `ENABLE_TOOL_SEARCH` | 控制 [MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)。未设置时，Claude Code 默认延迟加载所有 MCP 工具。但在早于 Claude 4.5 代的 Google Cloud's Agent Platform 模型上、在托管于 Azure 的 Microsoft Foundry 部署上，以及当 `ANTHROPIC_BASE_URL` 指向非第一方主机时，它仍会预先加载这些工具。`true` 始终延迟加载并发送 beta 标头，但上述 Agent Platform 模型和 Microsoft Foundry 部署除外；在不支持 `tool_reference` 的代理上，请求会失败。`auto` 会在工具定义占上下文 10% 以内时预先加载。`auto:N` 设置自定义阈值，例如 `auto:5` 表示 5%。`false` 会预先加载所有工具。设置了 `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` 时，您自行设置的值会被忽略。在 v2.1.221 之前，除非您将此变量设置为 `true`，否则 Claude Code 会对 Google Cloud's Agent Platform 上的所有模型禁用工具搜索 |

473| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 设置为任意非空值（例如 `1`）后，在未配置备用模型时，Claude Code 会对所有模型在反复出现过载错误时停止重试。与大多数开/关变量不同，**将其设置为 `0` 或 `false` 仍会启用此行为**；取消设置该变量即可恢复默认的重试行为。如果不设置，当您使用 API 密钥或[第三方提供商](/docs/zh-CN/third-party-integrations)而非 Claude 订阅进行身份验证时，Claude Code 仅会对其识别为 Opus、Fable 或 Mythos 的模型以这种方式停止重试。在 Claude Code v2.1.160 或更高版本中，任何主模型反复出现过载错误时，Claude Code 都会切换到您配置的[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)，因此此变量不影响切换到备用模型 |476| `FALLBACK_FOR_ALL_PRIMARY_MODELS` | 设置为任意非空值（例如 `1`），使 Claude Code 在未配置备用模型时，对所有模型在反复出现过载错误时停止重试。**与大多数开关变量不同，将其设置为 `0` 或 `false` 仍会启用此行为**；取消设置该变量可恢复默认重试行为。如果不设置，当您使用 API 密钥或[第三方提供商](/docs/zh-CN/third-party-integrations)而非 Claude 订阅进行身份验证时，Claude Code 仅对其识别为 Opus、Fable 或 Mythos 的模型以这种方式停止重试。在 Claude Code v2.1.160 或更高版本上，Claude Code 会在任何主模型反复出现过载错误时切换到您配置的[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)，因此此变量不影响切换到备用模型 |

475| `FORCE_HYPERLINK` | 当您的终端支持可点击的 OSC 8 超链接但未被自动检测到时，设置为 `1` 可启用它们，设置为 `0` 可禁用它们。未设置时，Claude Code 仅在检测到终端支持时才启用超链接。Claude Code 将此值解析为数字而非布尔值，因此 `false`、`no` 或 `off` 等值会启用超链接，而不是禁用。即使 Claude Code 无法检测到终端支持（例如通过 SSH 连接时），页脚的 [PR 或合并请求徽章](/docs/zh-CN/interactive-mode#pr-review-status)也会渲染为超链接。设置为 `0` 可将徽章渲染为纯文本 |478| `FORCE_HYPERLINK` | 设置为 `1` 以在终端支持但未被自动检测到时启用可点击的 OSC 8 超链接，或设置为 `0` 以禁用它们。未设置时，Claude Code 仅在检测到终端支持时启用超链接。Claude Code 将此值解析为数字而非布尔值，因此 `false`、`no` 或 `off` 等值会启用超链接而不是禁用它们。即使 Claude Code 无法检测到终端支持（例如通过 SSH 时），页脚的 [PR 或合并请求徽章](/docs/zh-CN/interactive-mode#pr-review-status)也会渲染为超链接。设置为 `0` 可将该徽章渲染为纯文本 |

476| `FORCE_PROMPT_CACHING_5M` | 设置为 `1` 可强制使用 5 分钟的提示缓存 TTL，即使原本会应用 1 小时 TTL。覆盖 `CLAUDE_CODE_PROMPT_CACHE_TTL`、`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`、`ENABLE_PROMPT_CACHING_1H` 以及 `promptCacheTtl` 和 `subagentPromptCacheTtl` 设置 |479| `FORCE_PROMPT_CACHING_5M` | 设置为 `1` 以强制使用 5 分钟提示缓存 TTL，即使原本会应用 1 小时 TTL。覆盖 `CLAUDE_CODE_PROMPT_CACHE_TTL`、`CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`、`ENABLE_PROMPT_CACHING_1H` 以及 `promptCacheTtl` 和 `subagentPromptCacheTtl` 设置 |

479| `IS_DEMO` | 设置为任意非空值（例如 `1`）可启用演示模式：在标题栏和 `/status` 输出中隐藏您的电子邮件和组织名称，并跳过新手引导。与大多数开/关变量不同，**将其设置为 `0` 或 `false` 仍会启用演示模式**；取消设置该变量即可将其关闭。适用于直播或录制会话时 |482| `IS_DEMO` | 设置为任意非空值（例如 `1`）以启用演示模式：在标题栏和 `/status` 输出中隐藏您的电子邮件和组织名称，并跳过新手引导。**与大多数开关变量不同，将其设置为 `0` 或 `false` 仍会启用演示模式**；取消设置该变量可将其关闭。在直播或录制会话时很有用 |

480| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具响应中允许的最大 token 数（默认：25000）。当输出超过 10,000 个 token 时，Claude Code 会显示警告。声明了 [`anthropic/maxResultSizeChars`](/docs/zh-CN/mcp#raise-the-limit-for-a-specific-tool) 的工具会改为对文本内容使用该字符限制，但这些工具返回的图像内容仍受此变量约束。对于没有该注解的工具，超过 50,000 个字符的成功文本结果会被[保存到文件](/docs/zh-CN/mcp#mcp-output-limits-and-warnings)，与此变量无关 |483| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具响应中允许的最大 token 数（默认：25000）。当输出超过 10,000 个 token 时，Claude Code 会显示警告。声明了 [`anthropic/maxResultSizeChars`](/docs/zh-CN/mcp#raise-the-limit-for-a-specific-tool) 的工具会改为对文本内容使用该字符限制，但这些工具的图像内容仍受此变量约束。对于没有该注解的工具，超过 50,000 个字符的成功文本结果无论此变量如何设置，都会被[保存到文件](/docs/zh-CN/mcp#mcp-output-limits-and-warnings) |

481| `MAX_STRUCTURED_OUTPUT_RETRIES` | 在使用 `-p` 标志的非交互模式下，当模型响应未通过 [`--json-schema`](/docs/zh-CN/cli-reference#cli-flags) 校验时，Claude Code 允许的尝试次数；在达到该次数的失败尝试且没有有效输出后，运行将失败。当[工作流](/docs/zh-CN/workflows)子代理的结构化输出未通过校验时，同样适用此上限。默认值为 5，即一次首次尝试加四次重试 |484| `MAX_STRUCTURED_OUTPUT_RETRIES` | 在使用 `-p` 标志的非交互模式下，当模型的响应未通过 [`--json-schema`](/docs/zh-CN/cli-reference#cli-flags) 验证时，Claude Code 允许的尝试次数；在失败尝试达到该次数且没有有效输出后，运行将失败。当[工作流](/docs/zh-CN/workflows)子代理的结构化输出未通过验证时，也适用相同的上限。默认为 5，即一次首次尝试加四次重试 |

482| `MAX_THINKING_TOKENS` | [扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)的固定 token 预算。Claude Code 会将其上限设为比请求的最大输出 token 数少一个 token，且绝不低于 1,024。关于该限制的设置方式，请参见 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`。未设置且已启用思考时，支持[自适应推理](/docs/zh-CN/model-config#adjust-effort-level)的模型会自行选择思考深度，其他模型则使用该上限。设置为 `0` 可在 Anthropic API 上禁用思考，但 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 模型除外，这些模型无法关闭思考。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，`0` 会改为省略 `thinking` 参数。在 Anthropic API 上关闭思考后，对于 Claude Code 已知[不接受该组合](/docs/zh-CN/errors#effort-isnt-available-with-thinking-turned-off)的模型（例如 Opus 5），Claude Code 会发送 effort `high`，而不是更高的级别。对于正值，Claude Code 在自适应推理模型上会忽略数值本身，除非 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 关闭了自适应推理 |485| `MAX_THINKING_TOKENS` | [扩展思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)的固定 token 预算。Claude Code 将其上限设为比请求的最大输出 token 数少一个 token，且不低于 1,024。关于该限制如何设置，请参阅 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`。未设置且启用思考时，具有[自适应推理](/docs/zh-CN/model-config#adjust-effort-level)的模型会自行选择思考深度，其他模型则使用该上限。设置为 `0` 可在 Anthropic API 上禁用思考，但 Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 模型除外，这些模型无法关闭思考。在[第三方提供商](/docs/zh-CN/third-party-integrations)上，`0` 会改为省略 `thinking` 参数。在 Anthropic API 上关闭思考时，对于 Claude Code 已知[不接受该组合](/docs/zh-CN/errors#effort-isnt-available-with-thinking-turned-off)的模型（例如 Opus 5），Claude Code 会发送 effort `high` 而不是更高的级别。对于正值，Claude Code 在自适应推理模型上会忽略该数字本身，除非 `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` 关闭了自适应推理 |

483| `MCP_CLIENT_SECRET` | 用于需要[预配置凭据](/docs/zh-CN/mcp#use-pre-configured-oauth-credentials)的 MCP 服务器的 OAuth 客户端密钥。使用 `--client-secret` 添加服务器时可避免交互式提示 |486| `MCP_CLIENT_SECRET` | 适用于需要[预配置凭据](/docs/zh-CN/mcp#use-pre-configured-oauth-credentials)的 MCP 服务器的 OAuth 客户端密钥。使用 `--client-secret` 添加服务器时可避免交互式提示 |

484| `MCP_CONNECTION_NONBLOCKING` | 控制启动时是否在第一次查询之前等待 MCP 服务器连接。MCP 启动默认是非阻塞的：服务器在后台连接，其工具在连接完成后即可使用。设置为 `0` 可让 Claude Code 在第一次查询之前等待服务器连接。配置了 [`alwaysLoad: true`](/docs/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器无论如何仍会让启动等待，除非它们由[发现缓存](/docs/zh-CN/mcp#server-status-detail)提供，因为构建第一个提示词时必须已存在它们的工具。在未使用 `--input-format stream-json` 的非交互模式（`-p`）下，无论此变量如何设置，Claude Code 也会在第一轮之前等待仍处于待定状态的服务器。当您显式传入 [`--mcp-config`](/docs/zh-CN/cli-reference#cli-flags) 时，等待的截止时间更长；关于已缓存服务器的例外情况，请参见该标志的条目 |487| `MCP_CONNECTION_NONBLOCKING` | 控制启动时是否在第一次查询之前等待 MCP 服务器连接。MCP 启动默认是非阻塞的：服务器在后台连接，其工具在连接完成后变为可用。设置为 `0` 可使 Claude Code 在第一次查询之前等待服务器连接。配置了 [`alwaysLoad: true`](/docs/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器无论如何仍会让启动等待，除非从[发现缓存](/docs/zh-CN/mcp#server-status-detail)提供，因为在构建第一个提示词时必须已存在其工具。在非交互模式（`-p`）下且未使用 `--input-format stream-json` 时，无论此变量如何设置，Claude Code 也会在第一个轮次之前等待仍处于等待中的服务器。当您显式传递 [`--mcp-config`](/docs/zh-CN/cli-reference#cli-flags) 时，等待的截止时间更长；有关已缓存服务器的例外情况，请参阅该标志的条目 |

485| `MCP_CONNECT_TIMEOUT_MS` | 阻塞式 MCP 启动在对工具列表进行快照之前等待连接批次的时长，以毫秒为单位（默认：5000）。在 `MCP_CONNECTION_NONBLOCKING=0` 时或对于标记了 [`alwaysLoad: true`](/docs/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器适用。到截止时间时仍处于待定状态的服务器会继续在后台连接。与 `MCP_TIMEOUT` 不同，后者限制的是单个服务器的连接尝试 |488| `MCP_CONNECT_TIMEOUT_MS` | 阻塞式 MCP 启动在对工具列表生成快照之前等待连接批次的时长，以毫秒为单位（默认：5000）。适用于 `MCP_CONNECTION_NONBLOCKING=0` 时或标记为 [`alwaysLoad: true`](/docs/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器。到达截止时间时仍处于等待中的服务器会继续在后台连接。与 `MCP_TIMEOUT` 不同，后者限制的是单个服务器的连接尝试 |

486| `MCP_DISCOVERY_CACHE` | 开启或关闭 [MCP 发现缓存](/docs/zh-CN/mcp#server-status-detail)。开启缓存后，您之前使用过的远程 HTTP 或 SSE 服务器可以显示 [`cached` 状态](/docs/zh-CN/mcp#server-status-detail)，并且 Claude Code 会在其第一次工具调用时而不是在启动时连接它。除非逐步推出已为您的账户启用该缓存，否则缓存默认关闭。设置为 `1` 可将其开启，设置为 `0` 可在推出已启用的情况下仍保持关闭。在 v2.1.238 之前，缓存默认开启。`cached` 状态需要 Claude Code v2.1.221 或更高版本 |489| `MCP_DISCOVERY_CACHE` | 开启或关闭 [MCP 发现缓存](/docs/zh-CN/mcp#server-status-detail)。缓存开启时，您之前使用过的远程 HTTP 或 SSE 服务器可以显示 [`cached` 状态](/docs/zh-CN/mcp#server-status-detail)，并且 Claude Code 会在其第一次工具调用时而不是在启动时连接它。除非逐步推出已为您的账户启用了缓存，否则缓存默认关闭。设置为 `1` 可将其开启，设置为 `0` 则即使逐步推出已启用也保持关闭。在 v2.1.238 之前，缓存默认开启。`cached` 状态需要 Claude Code v2.1.221 或更高版本 |

487| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [发现缓存](/docs/zh-CN/mcp#server-status-detail)条目的最长存在时间，以秒为单位（默认：14400，即 4 小时）。在启动时，如果条目早于此时长，Claude Code 会丢弃它并在启动时连接该服务器，与关闭缓存时的行为相同。Claude Code 将该值上限设为 7 天。在 v2.1.238 之前，默认值为 86400，即 24 小时，并且 Claude Code 不限制该值 |490| `MCP_DISCOVERY_CACHE_MAX_STALE_S` | [发现缓存](/docs/zh-CN/mcp#server-status-detail)条目的最长有效期，以秒为单位（默认：14400，即 4 小时）。在某次启动时，如果条目已超过该时长，Claude Code 会丢弃它并在启动时连接服务器，就像缓存关闭时一样。Claude Code 将该值上限设为 7 天。在 v2.1.238 之前，默认值为 86400，即 24 小时，且 Claude Code 不限制该值 |

488| `MCP_DISCOVERY_CACHE_STRIKES` | 在启动时，如果某个[发现缓存](/docs/zh-CN/mcp#server-status-detail)条目早于 `MCP_DISCOVERY_CACHE_TTL_S`，Claude Code 会在后台刷新它。此变量设置连续多少次刷新失败后，Claude Code 会丢弃该条目并改为在下次启动时连接该服务器（默认：1）。如果您的网络连接偶尔中断，请调高此值，以免一次刷新失败就丢弃条目。需要 Claude Code v2.1.238 或更高版本 |491| `MCP_DISCOVERY_CACHE_STRIKES` | 在某次启动时，如果[发现缓存](/docs/zh-CN/mcp#server-status-detail)条目已超过 `MCP_DISCOVERY_CACHE_TTL_S`，Claude Code 会在后台刷新它。此变量设置在 Claude Code 丢弃该条目并改为在下次启动时连接服务器之前，允许连续失败的刷新次数（默认：1）。如果您的网络连接偶尔中断，请调高此值，以免一次刷新失败就丢弃该条目。需要 Claude Code v2.1.238 或更高版本 |

489| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code 在不刷新的情况下使用[发现缓存](/docs/zh-CN/mcp#server-status-detail)条目的秒数（默认：900）。在启动时，如果条目早于此时长，Claude Code 仍会使用它，但会在后台刷新。一旦条目早于 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，Claude Code 会改为丢弃它。Claude Code 将该值上限设为 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，默认为 4 小时。在 v2.1.238 之前，Claude Code 不限制该值 |492| `MCP_DISCOVERY_CACHE_TTL_S` | Claude Code 在不刷新的情况下使用[发现缓存](/docs/zh-CN/mcp#server-status-detail)条目的秒数（默认：900）。在某次启动时，如果条目已超过该时长，Claude Code 仍会使用它，但会在后台刷新。一旦条目超过 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，Claude Code 会改为丢弃它。Claude Code 将该值上限设为 `MCP_DISCOVERY_CACHE_MAX_STALE_S`，其默认为 4 小时。在 v2.1.238 之前，Claude Code 不限制该值 |

490| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重定向回调的固定端口，在使用[预配置凭据](/docs/zh-CN/mcp#use-pre-configured-oauth-credentials)添加 MCP 服务器时可作为 `--callback-port` 的替代方案 |493| `MCP_OAUTH_CALLBACK_PORT` | OAuth 重定向回调的固定端口，可在使用[预配置凭据](/docs/zh-CN/mcp#use-pre-configured-oauth-credentials)添加 MCP 服务器时替代 `--callback-port` |

491| `MCP_PROTOCOL_NEGOTIATION` | 仅在 [v2 MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes)上，控制 Claude Code 是否探测服务器是否支持 MCP 协议修订版 2026-07-28。设置为 `auto` 可探测 HTTP、claude.ai 连接器和 stdio 服务器，设置为 `legacy` 则不探测任何服务器。未设置该变量时，Claude Code 会探测 [MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes)中所述的服务器。任何其他值都会被忽略，并在调试日志中记录警告。需要 Claude Code v2.1.221 或更高版本 |494| `MCP_PROTOCOL_NEGOTIATION` | 仅在 [v2 MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes)上生效，控制 Claude Code 是否探测服务器对 MCP 协议修订版 2026-07-28 的支持。设置为 `auto` 可探测 HTTP、claude.ai 连接器和 stdio 服务器，设置为 `legacy` 则不探测任何服务器。未设置该变量时，Claude Code 会探测 [MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes)中所述的服务器。任何其他值都会被忽略，并在调试日志中写入警告。需要 Claude Code v2.1.221 或更高版本 |

493| `MCP_SDK_GENERATION` | 固定此进程连接 MCP 服务器时所使用的 [MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes)：`v1` 基于 MCP TypeScript SDK 1.x 构建，`v2` 基于 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 构建。未设置该变量时，从该部分列出的版本开始，Claude Code 使用 v2。在 Claude Code v2.1.221 或更高版本中，v2 运行时会检查 MCP OAuth 服务器在其授权响应中返回的 issuer，如果不匹配，登录会失败并显示以 `Issuer mismatch in authorization response` 开头的错误。v1 运行时不执行此检查。如果您设置了无法识别的值，Claude Code 会忽略它并在调试日志中写入警告。Claude Code 每个进程只读取一次该值。需要 Claude Code v2.1.218 或更高版本 |496| `MCP_SDK_GENERATION` | 固定此进程用于连接 MCP 服务器的 [MCP 客户端运行时](/docs/zh-CN/mcp#mcp-client-runtimes)：`v1` 基于 MCP TypeScript SDK 1.x 构建，`v2` 基于 [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/) 构建。未设置该变量时，从该部分列出的版本开始，Claude Code 使用 v2。在 Claude Code v2.1.221 或更高版本上，v2 运行时会检查 MCP OAuth 服务器在其授权响应中返回的颁发者，不匹配时会以一个以 `Issuer mismatch in authorization response` 开头的错误使登录失败。v1 运行时不会执行此检查。如果您设置了无法识别的值，Claude Code 会忽略它并在调试日志中写入警告。Claude Code 每个进程读取一次该值。需要 Claude Code v2.1.218 或更高版本 |

496| `MCP_TOOL_TIMEOUT` | MCP 工具执行的超时时间，以毫秒为单位（默认：100000000，约 28 小时）。对于 HTTP、SSE 或 claude.ai 连接器服务器，每个请求默认还会在 60 秒后超时；将此变量或按服务器的 `timeout` 设置为大于 60000 可提高该单请求限制。较低的值仍会缩短整体工具执行超时时间，但单请求限制保持为 60 秒。Stdio 和 WebSocket 服务器没有单请求计时器。`.mcp.json` 中按服务器的 `timeout` 字段会为该服务器覆盖此值。至少为 1000 的按服务器 `timeout` 还会设置该服务器工具调用的最小空闲窗口，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 绝不会更早地中止它们；此下限需要 Claude Code v2.1.203 或更高版本。对于环境变量，低于 1000 的值会被提升为一秒；对于按服务器字段，低于 1000 的值会被忽略 |499| `MCP_TOOL_TIMEOUT` | MCP 工具执行的超时时间，以毫秒为单位（默认：100000000，约 28 小时）。对于 HTTP、SSE 或 claude.ai 连接器服务器，每个请求默认还会在 60 秒后超时；将此变量或按服务器的 `timeout` 设置为高于 60000 可提高该单请求限制。较低的值仍会缩短整体工具执行超时时间，但单请求限制保持为 60 秒。Stdio 和 WebSocket 服务器没有单请求计时器。`.mcp.json` 中按服务器的 `timeout` 字段会针对该服务器覆盖此变量。按服务器的 `timeout` 至少为 1000 时，还会设置该服务器工具调用的最小空闲窗口，因此 `CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT` 永远不会更早中止它们；此下限需要 Claude Code v2.1.203 或更高版本。对于环境变量，低于 1000 的值会被提升为一秒；对于按服务器的字段，低于 1000 的值会被忽略 |

498| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 标准 OpenTelemetry SDK 的属性值长度限制。Claude Code 会将包含内容的遥测属性上限设为此值与 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 中较小的一个，以使截断标记保持在 SDK 限制之内。Claude Code 以相同方式读取 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 和 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 变体，并且所设置的最小值适用于所有信号。需要 Claude Code v2.1.214 或更高版本。请参见[监控](/docs/zh-CN/monitoring-usage#common-configuration-variables) |501| `OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT` | 标准 OpenTelemetry SDK 对属性值长度的限制。Claude Code 将携带内容的遥测属性上限设为此值与 `CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 中的较小者，以使截断标记保持在 SDK 限制之内。Claude Code 以相同方式读取 `OTEL_LOGRECORD_ATTRIBUTE_VALUE_LENGTH_LIMIT` 和 `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` 变体，所有已设置值中最小的那个适用于所有信号。需要 Claude Code v2.1.214 或更高版本。请参阅[监控](/docs/zh-CN/monitoring-usage#common-configuration-variables) |

499| `OTEL_LOG_ASSISTANT_RESPONSES` | 设置为 `1` 可在 `assistant_response` OpenTelemetry 日志事件中包含模型的回复文本。未设置时，Claude Code 改为使用 `OTEL_LOG_USER_PROMPTS` 的值。设置为 `0` 可在设置了 `OTEL_LOG_USER_PROMPTS` 的情况下仍保持回复被脱敏。请在 shell、用户设置或托管设置中设置它。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略。需要 Claude Code v2.1.193 或更高版本。请参见[监控](/docs/zh-CN/monitoring-usage#assistant-response-event) |502| `OTEL_LOG_ASSISTANT_RESPONSES` | 设置为 `1` 以在 `assistant_response` OpenTelemetry 日志事件中包含模型的回复文本。未设置时，Claude Code 会改用 `OTEL_LOG_USER_PROMPTS` 的值。设置为 `0` 可在设置了 `OTEL_LOG_USER_PROMPTS` 时仍保持回复被隐去。在您的 shell、用户设置或托管设置中设置它。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略。需要 Claude Code v2.1.193 或更高版本。请参阅[监控](/docs/zh-CN/monitoring-usage#assistant-response-event) |

500| `OTEL_LOG_MANAGED_SETTINGS` | 设置为 `1` 可将脱敏后的托管设置以及脱敏前设置的 SHA-256 摘要添加到 `managed_settings_resolved` OpenTelemetry 日志事件中。默认禁用。请在 shell、用户设置或托管设置中设置它；项目设置或本地设置中的值不会将其开启。需要 Claude Code v2.1.274 或更高版本。请参见[监控](/docs/zh-CN/monitoring-usage#managed-settings-resolved-event) |503| `OTEL_LOG_MANAGED_SETTINGS` | 设置为 `1` 以将脱敏后的托管设置以及脱敏前设置的 SHA-256 摘要添加到 `managed_settings_resolved` OpenTelemetry 日志事件中。默认禁用。在您的 shell、用户设置或托管设置中设置它；项目或本地设置中的值不会开启它。需要 Claude Code v2.1.274 或更高版本。请参阅[监控](/docs/zh-CN/monitoring-usage#managed-settings-resolved-event) |

501| `OTEL_LOG_RAW_API_BODIES` | 将 Anthropic Messages API 请求和响应 JSON 作为 `api_request_body` / `api_response_body` 日志事件发出。设置为 `1` 可发出按内容限制截断的内联正文，设置为 `file:<dir>` 可将未截断的正文写入磁盘并改为发出 `body_ref` 路径。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 用于配置内容限制，默认为 60 KB。默认禁用；正文包含完整的对话历史。请在 shell、用户设置或托管设置中设置它。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略。请参见[监控](/docs/zh-CN/monitoring-usage#api-request-body-event) |504| `OTEL_LOG_RAW_API_BODIES` | 将 Anthropic Messages API 请求和响应 JSON 作为 `api_request_body` / `api_response_body` 日志事件发出。设置为 `1` 可内联发出在内容限制处截断的正文，或设置为 `file:<dir>` 将未截断的正文写入磁盘并改为发出 `body_ref` 路径。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` 用于配置内容限制，默认为 60 KB。默认禁用；正文包含完整的对话历史。在您的 shell、用户设置或托管设置中设置它。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略。请参阅[监控](/docs/zh-CN/monitoring-usage#api-request-body-event) |

502| `OTEL_LOG_TOOL_CONTENT` | 设置为 `1` 可在 `tool.output` OpenTelemetry span 事件中包含工具内容。span 属性在[各自的开关](/docs/zh-CN/monitoring-usage#new-context-gates)下携带工具内容。需要[追踪](/docs/zh-CN/monitoring-usage#traces-beta)。默认禁用以保护敏感数据。请在 shell、用户设置或托管设置中设置它。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略，该部分所述的关闭值除外。请参见[监控](/docs/zh-CN/monitoring-usage#tool-output-span-event) |505| `OTEL_LOG_TOOL_CONTENT` | 设置为 `1` 以在 `tool.output` OpenTelemetry span 事件中包含工具内容。span 属性在[各自的开关](/docs/zh-CN/monitoring-usage#new-context-gates)下携带工具内容。需要[追踪](/docs/zh-CN/monitoring-usage#traces-beta)。默认禁用以保护敏感数据。在您的 shell、用户设置或托管设置中设置它。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略，但该部分所述的关闭值除外。请参阅[监控](/docs/zh-CN/monitoring-usage#tool-output-span-event) |

503| `OTEL_LOG_TOOL_DETAILS` | 设置为 `1` 可在 OpenTelemetry 指标、追踪和日志中包含工具输入参数；MCP 服务器名称；用户编写的工作流名称；工具失败时的原始错误字符串；`api_refusal` 事件上的拒绝 `category`；[费用和 token 指标](/docs/zh-CN/monitoring-usage#cost-counter)上真实的 Agent、skill、插件和 MCP 服务器名称；以及其他工具详细信息。默认禁用以保护个人身份信息。请在 shell、用户设置或托管设置中设置它。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略，该部分所述的关闭值除外。请参见[监控](/docs/zh-CN/monitoring-usage) |506| `OTEL_LOG_TOOL_DETAILS` | 设置为 `1` 以在 OpenTelemetry 指标、追踪和日志中包含工具输入参数；MCP 服务器名称；用户编写的工作流名称；工具失败时的原始错误字符串；`api_refusal` 事件上的拒绝 `category`；[费用和 token 指标](/docs/zh-CN/monitoring-usage#cost-counter)上真实的 Agent、skill、插件和 MCP 服务器名称；以及其他工具详细信息。默认禁用以保护 PII。在您的 shell、用户设置或托管设置中设置它。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略，但该部分所述的关闭值除外。请参阅[监控](/docs/zh-CN/monitoring-usage) |

504| `OTEL_LOG_USER_PROMPTS` | 设置为 `1` 可在 OpenTelemetry 追踪和日志中包含用户提示词文本。默认禁用（提示词会被脱敏）。请在 shell、用户设置或托管设置中设置它。在[项目设置和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略，该部分所述的关闭值除外。请参见[监控](/docs/zh-CN/monitoring-usage) |507| `OTEL_LOG_USER_PROMPTS` | 设置为 `1` 以在 OpenTelemetry 追踪和日志中包含用户提示词文本。默认禁用（提示词会被隐去）。在您的 shell、用户设置或托管设置中设置它。在[项目和本地设置](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)中会被忽略，但该部分所述的关闭值除外。请参阅[监控](/docs/zh-CN/monitoring-usage) |

506| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 设置为 `true` 可在指标属性中包含会话入口点（默认：排除）。在 v2.1.152 中添加。请参见[监控](/docs/zh-CN/monitoring-usage) |509| `OTEL_METRICS_INCLUDE_ENTRYPOINT` | 设置为 `true` 以在指标属性中包含会话入口点（默认：排除）。在 v2.1.152 中添加。请参阅[监控](/docs/zh-CN/monitoring-usage) |

507| `OTEL_METRICS_INCLUDE_REPOSITORY` | 设置为 `true` 可为 OpenTelemetry 指标和事件添加标识会话所在仓库的 `vcs.*` 属性（默认：排除）。需要 Claude Code v2.1.269 或更高版本。请参见[仓库属性](/docs/zh-CN/monitoring-usage#repository-attributes) |510| `OTEL_METRICS_INCLUDE_REPOSITORY` | 设置为 `true` 以使用标识会话所在仓库的 `vcs.*` 属性标记 OpenTelemetry 指标和事件（默认：排除）。需要 Claude Code v2.1.269 或更高版本。请参阅[仓库属性](/docs/zh-CN/monitoring-usage#repository-attributes) |

508| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 从 v2.1.161 起，Claude Code 会将 `OTEL_RESOURCE_ATTRIBUTES` 键附加到指标数据点标签上。设置为 `false` 可将其排除（默认：包含）。请参见[监控](/docs/zh-CN/monitoring-usage#multi-team-organization-support) |511| `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES` | 从 v2.1.161 起，Claude Code 会将 `OTEL_RESOURCE_ATTRIBUTES` 键附加到指标数据点标签上。设置为 `false` 可排除它们（默认：包含）。请参阅[监控](/docs/zh-CN/monitoring-usage#multi-team-organization-support) |

511| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆盖向 [Skill 工具](/docs/zh-CN/skills#control-who-invokes-a-skill)显示的 skill 元数据的字符预算。该预算按上下文窗口的 1% 动态缩放，回退值为 8,000 个字符。保留旧名称是为了向后兼容 |514| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 覆盖向 [Skill 工具](/docs/zh-CN/skills#control-who-invokes-a-skill)显示的 skill 元数据的字符预算。该预算按上下文窗口的 1% 动态调整，备用值为 8,000 个字符。保留旧名称以实现向后兼容 |

512| `TASK_MAX_OUTPUT_LENGTH` | 已在 v2.1.277 中与其所限定大小的 `TaskOutput` 工具一起移除，现在不起任何作用。以前用于设置 `TaskOutput` 工具保留的[后台任务](/docs/zh-CN/tools-reference#background-commands)输出的最大字符数。Claude 现在改用 `Read` 读取后台任务的输出文件 |515| `TASK_MAX_OUTPUT_LENGTH` | 已在 v2.1.277 中移除，现在与其所限定大小的 `TaskOutput` 工具一同不再起任何作用。以前用于设置 `TaskOutput` 工具保留的[后台任务](/docs/zh-CN/tools-reference#background-commands)输出的最大字符数。Claude 现在改用 `Read` 读取后台任务的输出文件 |

534 537

535同样支持标准 OpenTelemetry 导出器变量（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 以及特定于信号的变体）。有关配置详情，请参见[监控](/docs/zh-CN/monitoring-usage)。538还支持标准 OpenTelemetry 导出器变量（`OTEL_METRICS_EXPORTER`、`OTEL_LOGS_EXPORTER`、`OTEL_EXPORTER_OTLP_ENDPOINT`、`OTEL_EXPORTER_OTLP_PROTOCOL`、`OTEL_EXPORTER_OTLP_HEADERS`、`OTEL_METRIC_EXPORT_INTERVAL`、`OTEL_RESOURCE_ATTRIBUTES` 以及特定于信号的变体）。有关配置详细信息，请参阅[监控](/docs/zh-CN/monitoring-usage)。

536 539

537请在 shell、用户设置或托管设置中设置 `CLAUDE_CODE_ENABLE_TELEMETRY`，以及用于开启导出、选择导出目标或捕获内容的 OpenTelemetry 变量。Claude Code [会在项目设置和本地设置中忽略它们](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)，该部分所述的关闭值除外。`OTEL_RESOURCE_ATTRIBUTES` 以及导出间隔、超时和压缩相关变量（例如 `OTEL_METRIC_EXPORT_INTERVAL`）在项目设置和本地设置中仍然生效。540请在您的 shell、用户设置或托管设置中设置 `CLAUDE_CODE_ENABLE_TELEMETRY` 以及用于开启导出、选择导出目标或捕获内容的 OpenTelemetry 变量。Claude Code [会在项目和本地设置中忽略它们](/docs/zh-CN/settings-reference#variables-claude-code-ignores-in-env)，但该部分所述的关闭值除外。`OTEL_RESOURCE_ATTRIBUTES` 以及导出间隔、超时和压缩变量（例如 `OTEL_METRIC_EXPORT_INTERVAL`）在项目和本地设置中仍然生效。

538 541

539<h2 id="what-the-subprocess-environment-scrub-removes">542<h2 id="what-the-subprocess-environment-scrub-removes">

540 子进程环境清理会移除哪些内容543 子进程环境清理会移除哪些内容

587* 使用 [advisor 工具](/docs/zh-CN/advisor#requirements)590* 使用 [advisor 工具](/docs/zh-CN/advisor#requirements)

588* 阅读或回复 [Artifact 上的评论](/docs/zh-CN/artifacts#collect-comments-on-an-artifact)591* 阅读或回复 [Artifact 上的评论](/docs/zh-CN/artifacts#collect-comments-on-an-artifact)

589* 让 Claude 读取[其他组织的公开 Artifact](/docs/zh-CN/artifacts#read-an-artifact-shared-with-you)592* 让 Claude 读取[其他组织的公开 Artifact](/docs/zh-CN/artifacts#read-an-artifact-shared-with-you)

590* 让 Claude Code 针对 [MCP 协议修订版 2026-07-28](/docs/zh-CN/mcp#mcp-client-runtimes) 探测 claude.ai 连接器服务器或 stdio 服务器，除非您设置了 `MCP_PROTOCOL_NEGOTIATION=auto`593* 让 Claude Code 针对 [MCP 协议修订版 2026-07-28](/docs/zh-CN/mcp#mcp-client-runtimes) 探测 claude.ai 连接器服务器，除非您设置了 `MCP_PROTOCOL_NEGOTIATION=auto`

591* 在安装了 Git Bash 的 Windows 上，为 claude.ai 和 Console 账户默认获得 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)；除非您设置了 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`，否则 Claude Code 会通过 Git Bash 执行 shell 命令。在未安装 Git Bash 的 Windows 上，该工具保持启用594* 在安装了 Git Bash 的 Windows 上，为 claude.ai 和 Console 账户默认获得 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)；除非您设置了 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`，否则 Claude Code 会通过 Git Bash 执行 shell 命令。在未安装 Git Bash 的 Windows 上，该工具保持启用

592* 获得 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)，该功能由 Claude Code 通过获取的标志启用595* 获得 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)，该功能由 Claude Code 通过获取的标志启用

593* 让 Claude [将大段粘贴内容视为粘贴而非键入的文本](/docs/zh-CN/terminal-config#how-claude-treats-pasted-text)；`[Pasted text #N]` 占位符背后的内容将以无标记形式传给 Claude596* 让 Claude [将大段粘贴内容视为粘贴而非键入的文本](/docs/zh-CN/terminal-config#how-claude-treats-pasted-text)；`[Pasted text #N]` 占位符背后的内容将以无标记形式传给 Claude

errors.md +27 −30

Details

436| :- | :- | :- |436| :- | :- | :- |

437| [`CLAUDE_CODE_MAX_RETRIES`](/docs/zh-CN/env-vars) | 10 | 重试尝试次数。从 v2.1.186 开始上限为 15；从 v2.1.199 开始 `CLAUDE_CODE_RETRY_WATCHDOG` 提高默认值并移除上限。降低它以在脚本中更快地显示故障。 |437| [`CLAUDE_CODE_MAX_RETRIES`](/docs/zh-CN/env-vars) | 10 | 重试尝试次数。从 v2.1.186 开始上限为 15；从 v2.1.199 开始 `CLAUDE_CODE_RETRY_WATCHDOG` 提高默认值并移除上限。降低它以在脚本中更快地显示故障。 |

438| [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/zh-CN/env-vars) | 未设置 | 在 CI 作业等无人值守会话中设置为 `1`，以无限期重试 `429` 和 `529` 容量错误，而不是在 `CLAUDE_CODE_MAX_RETRIES` 尝试后失败。当标准速度请求获得报告支出限制或耗尽使用额度的 `429` 时，Claude Code 立即失败，即使来自 [gateway spend cap](#spend-limit-reached) 的也是如此，该上限按计划重置。在 v2.1.239 之前，看门狗无限期重试这些。对于快速模式请求，请参阅 [Handle rate limits](/docs/zh-CN/fast-mode#handle-rate-limits)。在 v2.1.199 或更高版本上，它还为其他瞬时错误（例如服务器错误、超时和断开连接）提高默认重试计数至 300，大约三小时的退避，如果您明确设置该变量，则移除 `CLAUDE_CODE_MAX_RETRIES` 的 15 上限。 |438| [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/zh-CN/env-vars) | 未设置 | 在 CI 作业等无人值守会话中设置为 `1`，以无限期重试 `429` 和 `529` 容量错误，而不是在 `CLAUDE_CODE_MAX_RETRIES` 尝试后失败。当标准速度请求获得报告支出限制或耗尽使用额度的 `429` 时，Claude Code 立即失败，即使来自 [gateway spend cap](#spend-limit-reached) 的也是如此，该上限按计划重置。在 v2.1.239 之前，看门狗无限期重试这些。对于快速模式请求，请参阅 [Handle rate limits](/docs/zh-CN/fast-mode#handle-rate-limits)。在 v2.1.199 或更高版本上，它还为其他瞬时错误（例如服务器错误、超时和断开连接）提高默认重试计数至 300，大约三小时的退避，如果您明确设置该变量，则移除 `CLAUDE_CODE_MAX_RETRIES` 的 15 上限。 |

439| [`CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS`](/docs/zh-CN/env-vars) | 500 | 当 API 以 `529` 过载错误拒绝请求时，该请求各次重试之间退避的起始延迟（毫秒）。当 API 容量已满时，可将其提高（最高 32000），以便在更长的时间窗口内分散重试。当 `CLAUDE_CODE_RETRY_WATCHDOG` 设置为 `1`，或被拒绝的请求是在[快速模式](/docs/zh-CN/fast-mode#handle-rate-limits)下发送时，此变量无效。需要 Claude Code v2.1.292 或更高版本。 |

439| [`API_TIMEOUT_MS`](/docs/zh-CN/env-vars) | 600000 | 每个请求的超时（毫秒）。为慢速网络或代理提高它。它还限制 Claude Code 等待响应头的时间，在 [No response from API](#no-response-from-api) 中描述。 |440| [`API_TIMEOUT_MS`](/docs/zh-CN/env-vars) | 600000 | 每个请求的超时（毫秒）。为慢速网络或代理提高它。它还限制 Claude Code 等待响应头的时间，在 [No response from API](#no-response-from-api) 中描述。 |

440| [`CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES`](/docs/zh-CN/env-vars) | 未设置 | 超时的[非流式请求](#streaming-response-ended-before-any-complete-data-was-received)的重新发送次数限制。达到该限制时，请求失败。生成时间超过超时时间的 Claude 响应在每次重新发送时都会再次超时，因此请设置较低的数值（例如 `0`）以更快地失败。在本地会话中，每次非流式尝试在 300 秒后超时；当您为 `API_TIMEOUT_MS` 设置正值时，则在该值指定的时间后超时。需要 Claude Code v2.1.285 或更高版本。 |441| [`CLAUDE_CODE_NONSTREAMING_TIMEOUT_RETRIES`](/docs/zh-CN/env-vars) | 未设置 | 超时的[非流式请求](#streaming-response-ended-before-any-complete-data-was-received)的重新发送次数限制。达到该限制时，请求失败。生成时间超过超时时间的 Claude 响应在每次重新发送时都会再次超时，因此请设置较低的数值（例如 `0`）以更快地失败。在本地会话中，每次非流式尝试在 300 秒后超时；当您为 `API_TIMEOUT_MS` 设置正值时，则在该值指定的时间后超时。需要 Claude Code v2.1.285 或更高版本。 |

441| [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](/docs/zh-CN/env-vars) | 未设置 | 流式请求的第一个响应字节的截止时间（毫秒）。需要 Claude Code v2.1.242 或更高版本。对于当此未设置时 Claude Code 如何选择截止时间，请参阅 [No response from API](#no-response-from-api)。 |442| [`CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS`](/docs/zh-CN/env-vars) | 未设置 | 流式请求的第一个响应字节的截止时间（毫秒）。需要 Claude Code v2.1.242 或更高版本。对于当此未设置时 Claude Code 如何选择截止时间，请参阅 [No response from API](#no-response-from-api)。 |

703当速率限制、过载或服务器错误中断已经生成文本输出的前台子代理时，Claude 接收该部分输出标记为不完整，而不是此错误。仅输出为工具调用的子代理也会收到此错误；在 v2.1.199 中，该形状返回了空的部分结果。请参阅[子代理中的 API 错误](/docs/zh-CN/sub-agents#api-errors-in-subagents)。704当速率限制、过载或服务器错误中断已经生成文本输出的前台子代理时，Claude 接收该部分输出标记为不完整，而不是此错误。仅输出为工具调用的子代理也会收到此错误；在 v2.1.199 中，该形状返回了空的部分结果。请参阅[子代理中的 API 错误](/docs/zh-CN/sub-agents#api-errors-in-subagents)。

704 705

705<h2 id="usage-limits">706<h2 id="usage-limits">

706 使用限制707 用量限制

707</h2>708</h2>

708 709

709本部分中的大多数错误意味着与您的账户或计划相关的配额已达到。其中三个的工作方式不同：[`Server is temporarily limiting requests`](#server-is-temporarily-limiting-requests) 是与您的计划配额无关的服务器端限流，[`Usage credits required for 1M context`](#usage-credits-required-for-1m-context) 是权限检查而非配额耗尽，[`The prompt to confirm went unanswered`](#the-prompt-to-confirm-went-unanswered) 表示使用额度同意提示未被回答而关闭，无论是否达到配额。710本部分中的大多数错误意味着与您的账户或套餐相关的配额已达到。其中三个的工作方式不同：[`Server is temporarily limiting requests`](#server-is-temporarily-limiting-requests) 是与您的套餐配额无关的服务器端限流，[`Usage credits required for 1M context`](#usage-credits-required-for-1m-context) 是权限检查而非配额耗尽，[`The prompt to confirm went unanswered`](#the-prompt-to-confirm-went-unanswered) 表示使用额度同意提示未被回答而关闭，无论是否达到配额。

710 711

711<h3 id="youve-hit-your-session-limit">712<h3 id="youve-hit-your-session-limit">

712 You've hit your session limit713 You've hit your session limit

713</h3>714</h3>

714 715

715订阅计划包括滚动使用额度。当额度用完时，您会看到以下消息之一：716订阅套餐包括滚动用量额度。当额度用完时，您会看到以下消息之一：

716 717

717```text theme={null}718```text theme={null}

718You've hit your session limit · resets 3:45pm719You've hit your session limit · resets 3:45pm

732* 等待错误中显示的重置时间733* 等待错误中显示的重置时间

733* 在 [Desktop app](/docs/zh-CN/desktop) 的 Code 选项卡中，会话限制卡提供 **Auto-continue when limits reset** 复选框。周限制卡没有。选中后，Desktop app 会在重置后重试中断的轮次，并在卡上显示重试时间。Desktop 复选框和 CLI 中 `/config` 中的 **Continue automatically at usage limit** 设置是分开的，因此需要分别关闭每一个。734* 在 [Desktop app](/docs/zh-CN/desktop) 的 Code 选项卡中，会话限制卡提供 **Auto-continue when limits reset** 复选框。周限制卡没有。选中后，Desktop app 会在重置后重试中断的轮次，并在卡上显示重试时间。Desktop 复选框和 CLI 中 `/config` 中的 **Continue automatically at usage limit** 设置是分开的，因此需要分别关闭每一个。

734* 对于 Opus 或 Sonnet 限制，运行 `/model` 并切换到该系列之外的模型以继续工作。每个模型都有自己的提示缓存，因此下一个请求会重新读取整个对话，没有缓存命中；请参阅 [Switching models](/docs/zh-CN/prompt-caching#switching-models)735* 对于 Opus 或 Sonnet 限制，运行 `/model` 并切换到该系列之外的模型以继续工作。每个模型都有自己的提示缓存，因此下一个请求会重新读取整个对话，没有缓存命中；请参阅 [Switching models](/docs/zh-CN/prompt-caching#switching-models)

735* 运行 `/usage` 查看您的计划限制以及何时重置736* 运行 `/usage` 查看您的套餐限制以及何时重置

736* 运行 `/usage-credits` 在 Pro 和 Max 上购买额外使用，或在 Team 和 Enterprise 上向您的管理员请求。有关如何计费的信息，请参阅 [usage credits for paid plans](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。737* 运行 `/usage-credits` 在 Pro 和 Max 上购买额外用量，或在 Team 和 Enterprise 上向您的管理员请求。有关如何计费的信息，请参阅 [usage credits for paid plans](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)。

737* 要升级您的计划以获得更高的基础限制，请参阅 [claude.com/pricing](https://claude.com/pricing)738* 要升级您的套餐以获得更高的基础限制，请参阅 [claude.com/pricing](https://claude.com/pricing)

738 739

739在窗口用完之前，Claude Code 可以警告您已使用了大部分额度，显示类似 `You've used 85% of your session limit · resets 3:45pm` 的消息。要持续监视您的剩余额度，请将 `rate_limits` 字段添加到 [custom status line](/docs/zh-CN/statusline#rate-limit-usage)，或在 Desktop app 中单击模型选择器旁边的 [usage ring](/docs/zh-CN/desktop#check-usage)。740在窗口用完之前，Claude Code 可以警告您已使用了大部分额度，显示类似 `You've used 85% of your session limit · resets 3:45pm` 的消息。要持续监视您的剩余额度，请将 `rate_limits` 字段添加到 [custom status line](/docs/zh-CN/statusline#rate-limit-usage)，或在 Desktop app 中单击模型选择器旁边的 [usage ring](/docs/zh-CN/desktop#check-usage)。

740 741

742 Usage credits required for 1M context743 Usage credits required for 1M context

743</h3>744</h3>

744 745

745所选模型使用 1M 令牌扩展上下文窗口，您的计划仅通过使用额度包含它。746所选模型使用 1M token 扩展上下文窗口，而您的套餐仅通过使用额度包含它。

746 747

747```text theme={null}748```text theme={null}

748API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context749API Error: Usage credits required for 1M context · run /usage-credits to turn them on (they take effect after you restart Claude Code), or /model to switch to standard context

749```750```

750 751

751在 Claude Desktop app 运行的会话中，提示不命名任何命令：它指向 claude.ai 使用设置页面，或在 Team 和 Enterprise 计划上说在 claude.ai/admin-settings/usage 启用使用额度或向您的管理员请求。752在 Claude Desktop app 运行的会话中，提示不命名任何命令：它指向 claude.ai 用量设置页面，或在 Team 和 Enterprise 套餐上说在 claude.ai/admin-settings/usage 启用使用额度或向您的管理员请求。

752 753

753这是权限检查，而非配额耗尽。即使您的会话和周额度有剩余容量，它也会触发。有关哪些计划直接包含 1M 上下文以及哪些需要使用额度的信息，请参阅 [Extended context](/docs/zh-CN/model-config#extended-context)。754这是权限检查，而非配额耗尽。即使您的会话和周额度有剩余容量，它也会触发。有关哪些套餐直接包含 1M 上下文以及哪些需要使用额度的信息，请参阅 [Extended context](/docs/zh-CN/model-config#extended-context)。

754 755

755当此错误在对话中期出现，因为上下文增长超过 200K 令牌时，Claude Code 会自动将对话压缩回标准上下文限制以下，并之后将会话保持在该限制，因此无需采取任何操作。在 v2.1.172 之前的版本中，错误会在每个后续请求（包括 `/compact`）上重复；在这些版本上运行 `/clear` 以恢复。以下步骤适用于您明确选择 `[1m]` 模型的情况。756当此错误因上下文增长超过 200K token 而在对话中途出现时，Claude Code 会自动将对话压缩回标准上下文限制以下，并在之后将会话保持在该限制，因此无需采取任何操作。在 v2.1.172 之前的版本中，错误会在每个后续请求（包括 `/compact`）上重复；在这些版本上运行 `/clear` 以恢复。以下步骤适用于您明确选择 `[1m]` 模型的情况。

756 757

757**要做什么：**758**要做什么：**

758 759

780 781

781**要做什么：**782**要做什么：**

782 783

783* 在会话运行的地方，在终端或托管它的应用程序中，发送另一个提示并在它重新出现时回答同意提示。对于后台会话，首先从 [agents view](/docs/zh-CN/agent-view) 附加到它。从 Remote Control 客户端重新发送会再次显示此消息，因为客户端无法显示提示。784* 在会话运行的地方，在终端或托管它的应用程序中，发送另一个提示词并在同意提示重新出现时回答它。对于后台会话，首先从 [agents view](/docs/zh-CN/agent-view) 附加到它。从 Remote Control 客户端重新发送会再次显示此消息，因为客户端无法显示提示。

784* 运行 `/model` 切换到不计费使用额度的模型785* 运行 `/model` 切换到不计费使用额度的模型

785* 要给自己更多时间，请将 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 设置为更长的值或 `"never"`786* 要给自己更多时间，请将 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 设置为更长的值或 `"never"`

786 787

790 Server is temporarily limiting requests791 Server is temporarily limiting requests

791</h3>792</h3>

792 793

793API 应用了与您的计划配额无关的短期限流。794API 应用了与您的套餐配额无关的短期限流。

794 795

795```text theme={null}796```text theme={null}

796API Error: Server is temporarily limiting requests (not your usage limit)797API Error: Server is temporarily limiting requests (not your usage limit)

797```798```

798 799

799Claude Code 通过真实限制响应所携带的统一配额标头的缺失来区分这些。从 v2.1.199 开始，这是 [retried automatically](#automatic-retries) 带有退避，无论您如何进行身份验证。在早期版本中，使用 claude.ai 订阅登录的会话在第一次出现时失败轮次；只有 API 密钥和 Enterprise 登录重试了它。800Claude Code 通过真实限制响应所携带的统一配额标头的缺失来区分这些。从 v2.1.199 开始，无论您如何进行身份验证，此错误在显示之前都会以退避方式[自动重试](#automatic-retries)。在早期版本中，使用 claude.ai 订阅登录的会话在第一次出现时即使轮次失败；只有 API 密钥和 Enterprise 登录会重试它。

800 801

801**要做什么：**802**要做什么：**

802 803

819 820

820**要做什么：**821**要做什么：**

821 822

822* 运行 `/status` 并确认活跃凭证是您期望的。环境中的流浪 `ANTHROPIC_API_KEY` 可能会通过低层密钥而不是您的订阅路由请求。823* 运行 `/status` 并确认活跃凭据是您期望的。环境中残留的 `ANTHROPIC_API_KEY` 可能会通过低层级密钥而不是您的订阅路由请求。

823* 检查您的提供商控制台以了解活跃限制，如果需要请求更高的层级824* 检查您的提供商控制台以了解活跃限制，如果需要请求更高的层级

824* 对于 Anthropic API 密钥，请参阅 [rate limits reference](https://platform.claude.com/docs/en/api/rate-limits) 了解层级如何工作以及如何设置每个工作区的上限825* 对于 Anthropic API 密钥，请参阅 [rate limits reference](https://platform.claude.com/docs/en/api/rate-limits) 了解层级如何工作以及如何设置每个工作区的上限

825* 降低并发：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/docs/zh-CN/env-vars)，避免运行许多并行子代理，或使用 `/model` 为高容量脚本运行切换到更小的模型826* 降低并发：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/docs/zh-CN/env-vars)，避免运行许多并行子代理，或使用 `/model` 为高容量脚本运行切换到更小的模型

828 You've hit your monthly spend limit829 You've hit your monthly spend limit

829</h3>830</h3>

830 831

831您的计划包含的使用量无法覆盖此请求，而本应为其付款的 [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 已达到支出限制。这发生在您的计划的使用窗口之一用完时，或当请求是仅由使用额度支付的请求时，例如对 [bills to usage credits](/docs/zh-CN/model-config#fable-and-usage-credits) 的模型的请求。消息命名其限制阻止了您。`·` 后的文本说明如何增加该限制，并因您的计划和您是否管理计费而异：832您的套餐包含的用量无法覆盖此请求，而本应为其付款的 [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) 已达到支出限制。这发生在您的套餐的用量窗口之一用完时，或当请求是仅由使用额度支付的请求时，例如对 [bills to usage credits](/docs/zh-CN/model-config#fable-and-usage-credits) 的模型的请求。消息会指明是谁的限制阻止了您。`·` 后的文本说明如何增加该限制，并因您的套餐和您是否管理计费而异：

832 833

833```text theme={null}834```text theme={null}

834You've hit your monthly spend limit · raise it at claude.ai/settings/usage835You've hit your monthly spend limit · raise it at https://claude.ai/settings/usage?from=cc_cli_limit_message

835You've hit your individual spend limit · ask your admin for a higher limit836You've hit your individual spend limit · ask your admin for a higher limit

836You've hit your org's monthly spend limit · visit claude.ai/admin-settings/usage to raise it837You've hit your org's monthly spend limit · visit https://claude.ai/admin-settings/usage to raise it

837You've hit your team's shared budget · ask your admin to raise it at claude.ai/admin-settings/usage838You've hit your team's shared budget · ask your admin to raise it at https://claude.ai/admin-settings/usage

838You've hit your channel's monthly spend limit · an org owner or channel manager can raise it in the channel's Claude settings839You've hit your channel's monthly spend limit · an org owner or channel manager can raise it in the channel's Claude settings

839```840```

840 841

841`team's shared budget` 是管理员分配给您所属的组的汇总预算；消息不命名该组。`channel's monthly spend limit` 是会话运行的一个 Slack 频道的预算，因此您的组织可能在其外部仍有预算。842`team's shared budget` 是管理员分配给您所属的组的汇总预算；消息不命名该组。`channel's monthly spend limit` 是会话运行的一个 Slack 频道的预算，因此您的组织可能在其外部仍有预算。

842 843

843当您的计划的窗口之一用完时，消息也会说该窗口何时重置，例如 `· your session limit resets 3:45pm`，访问权限会在那时返回，无需任何人提高限制。在使用基于使用量的计费的组织中，消息说 `usage limit` 代替 `spend limit`，如 `You've hit your individual usage limit`。844当您的套餐的窗口之一用完时，消息也会说该窗口何时重置，例如 `· your session limit resets 3:45pm`，访问权限会在那时恢复，无需任何人提高限制。在使用基于用量计费的组织中，消息说 `usage limit` 代替 `spend limit`，如 `You've hit your individual usage limit`。

~~844~~

845在 v2.1.239 之前，消息没有命名计划窗口的重置时间。在 v2.1.268 之前，组的汇总预算产生 `individual spend limit` 消息而不是 `team's shared budget`。

846 845

847如果您通过 Claude apps gateway 连接并看到小写 `spend limit reached`，那是您的网关操作员的上限；请参阅 [Spend limit reached](#spend-limit-reached)。846如果您通过 Claude apps gateway 连接并看到小写 `spend limit reached`，那是您的网关操作员的上限；请参阅 [Spend limit reached](#spend-limit-reached)。

848 847

849**要做什么：**848**要做什么：**

850 849

851* 在 Pro 和 Max 上，在 claude.ai 的 [**Settings > Usage**](https://claude.ai/settings/usage) 中增加您的月度支出限制，或运行 `/usage-credits`850* 在 Pro 和 Max 上，在 claude.ai 的 [**Settings > Usage**](https://claude.ai/settings/usage) 中增加您的月度支出限制，或运行 `/usage-credits`

852* 在 Team 和 Enterprise 上，如果您管理计费，在 [**Organization settings > Usage**](https://claude.ai/admin-settings/usage) 中增加限制，或要求管理员这样做。`/usage-credits` 为您向您的管理员发送该请求851* 在 Team 和 Enterprise 上，如果您管理计费，在 [**Organization settings > Usage**](https://claude.ai/admin-settings/usage) 中增加限制，或要求管理员这样做。`/usage-credits` 会代您向管理员发送该请求

853* 对于频道的限制，要求组织所有者或频道的管理员在 claude.ai 上提高它。请参阅 Claude Tag 文档中的 [Per-channel limits](https://claude.com/docs/claude-tag/admins/set-spend-limit#per-channel-limits)852* 对于频道的限制，要求组织所有者或频道的管理员在 claude.ai 上提高它。请参阅 Claude Tag 文档中的 [Per-channel limits](https://claude.com/docs/claude-tag/admins/set-spend-limit#per-channel-limits)

854* 如果消息命名您的计划窗口的重置时间，您可以改为等待它853* 如果消息命名您的套餐窗口的重置时间，您可以改为等待它

855* 运行 `/usage` 查看您的计划窗口以及每个何时重置854* 运行 `/usage` 查看您的套餐窗口以及每个何时重置

856 855

857<h3 id="spend-limit-reached">856<h3 id="spend-limit-reached">

858 Spend limit reached857 Spend limit reached

885 884

886**要做什么：**885**要做什么：**

887 886

888* 如果您有 Pro、Max、Team 或 Enterprise 计划并看到这个，运行 `/status` 并检查 `API key` 行。环境中已批准的 `ANTHROPIC_API_KEY` 通过该密钥而不是您的订阅路由请求。在当前 shell 中取消设置它并从您的 shell 配置文件中删除它，然后重新启动 `claude`。如果您还没有使用您的订阅登录，运行 `/login`。887* 如果您有 Pro、Max、Team 或 Enterprise 套餐并看到这个，运行 `/status` 并检查 `API key` 行。环境中已批准的 `ANTHROPIC_API_KEY` 通过该密钥而不是您的订阅路由请求。在当前 shell 中取消设置它并从您的 shell 配置文件中删除它，然后重新启动 `claude`。如果您还没有使用您的订阅登录，运行 `/login`。

889* 在 [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing) 添加额度，并考虑在那里启用自动重新加载，以便余额在达到零之前重新填充888* 在 [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing) 添加额度，并考虑在那里启用自动充值，以便余额在达到零之前重新填充

890* 在 Console 中设置每个工作区的支出上限，以防止单个项目耗尽组织余额。请参阅 [Manage costs effectively](/docs/zh-CN/costs)。889* 在 Console 中设置每个工作区的支出上限，以防止单个项目耗尽组织余额。请参阅 [Manage costs effectively](/docs/zh-CN/costs)。

891 890

892<h3 id="could-not-update-your-spend-limit">891<h3 id="could-not-update-your-spend-limit">

2861 2860

2862如果消息包含 `` Details: `[reasoning_extraction]` `` 行，请参阅[保护措施标记了索取 Claude 推理过程的请求](#safeguards-flagged-a-request-for-claudes-reasoning)。2861如果消息包含 `` Details: `[reasoning_extraction]` `` 行，请参阅[保护措施标记了索取 Claude 推理过程的请求](#safeguards-flagged-a-request-for-claudes-reasoning)。

2863 2862

2864消息链接到[网络安全验证计划](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)，该计划为合法网络安全工作授予访问权限。在 Opus 5.5 和 Sonnet 5.5 上，消息改以 `<model>'s safeguards flagged this session` 开头。当标记的类别有可用的备用模型时，Claude Code [切换模型](/docs/zh-CN/model-config#automatic-model-fallback)而不是显示此错误。2863此消息链接到[网络安全验证计划](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)，该计划为合法网络安全工作授予访问权限。具有[自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)的模型会打印不同的消息，不含此链接；在 Opus 5.5 和 Sonnet 5.5 上，该消息以 `<model>'s safeguards flagged this session` 开头。该部分还介绍了 Claude Code 何时改为切换模型。

2865 2864

2866在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上，网络安全标记会改为产生[使用政策拒绝](#usage-policy-refusal)消息。2865在 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud 的 Agent Platform](/docs/zh-CN/google-vertex-ai) 和 [Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 上，网络安全标记会改为产生[使用政策拒绝](#usage-policy-refusal)消息。

2867 2866

4824This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.4823This session has no saved transcript — it was stopped before its first response finished. If it was backgrounded from another conversation, that one is still intact; `claude respawn <id>` starts this one fresh.

4825```4824```

4826 4825

4827在 [Agent 视图](/docs/zh-CN/agent-view)中打开相同会话的行会在列表下方显示 `Press enter again to restart this session fresh`，在该行上第二次按 `Enter` 会使用空对话重启会话。在 v2.1.212 之前，打开该行显示拒绝消息，无法从 Agent 视图重启。在 v2.1.211 之前，打开停止的会话会无声地启动该空白对话，并可能重新运行会话的原始提示词。4826在 [Agent 视图](/docs/zh-CN/agent-view)中打开相同会话的行则会在列表下方显示 `Press enter again to restart this session fresh`，在该行上第二次按 `Enter` 会使用空对话重启会话。

4828 4827

4829**要做什么：**4828**要做什么：**

4830 4829

4846* **`running in another terminal`**：终端持有对话，例如您使用 `claude --resume` 或 `/resume` 恢复它的终端。该行也显示 `Open in a terminal`。4845* **`running in another terminal`**：终端持有对话，例如您使用 `claude --resume` 或 `/resume` 恢复它的终端。该行也显示 `Open in a terminal`。

4847* **`already open in another running Claude session`**：另一个非交互式 Claude Code 进程持有它，例如相同对话的[后台会话](/docs/zh-CN/agent-view#the-supervisor-process)进程尚未退出。4846* **`already open in another running Claude session`**：另一个非交互式 Claude Code 进程持有它，例如相同对话的[后台会话](/docs/zh-CN/agent-view#the-supervisor-process)进程尚未退出。

4848 4847

4849Claude Code 保存您在打开行时键入的回复，并在会话下次启动时将其作为会话的下一个提示词发送。

~~4850~~

4851**要做什么：**4848**要做什么：**

4852 4849

4853* 在持有它的进程中继续对话，或退出该进程并再次打开该行4850* 在持有它的进程中继续对话，或退出该进程并再次打开该行

feature-availability.md +3 −4

Details

92 <td>✗</td>92 <td>✗</td>

93 <td>✓</td>93 <td>✓</td>

94 <td>参见注释 <sup><a href="#fn1">1</a></sup></td>94 <td>参见注释 <sup><a href="#fn1">1</a></sup></td>

~~95 <td>✓（[部署在 Anthropic 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)）</td>~~95 <td>✓</td>

96 </tr>96 </tr>

97 97

98 <tr>98 <tr>

200 <tr>200 <tr>

201 <td>[Server-managed settings](/docs/zh-CN/server-managed-settings)</td>201 <td>[Server-managed settings](/docs/zh-CN/server-managed-settings)</td>

202 <td>✓（Team 和 Enterprise）</td>202 <td>✓（Team 和 Enterprise）</td>

203 <td>✓（Team 和 Enterprise）</td>203 <td>参见[平台可用性](/docs/zh-CN/server-managed-settings#platform-availability)</td>

204 <td>✗</td>204 <td>✗</td>

205 <td>✗</td>205 <td>✗</td>

206 <td>✗</td>206 <td>✗</td>

283 **部分支持：**283 **部分支持：**

284 284

285 * [Desktop](/docs/zh-CN/desktop)：仅通过 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)285 * [Desktop](/docs/zh-CN/desktop)：仅通过 [Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/overview)

286 * [Web search](/docs/zh-CN/tools-reference#websearch-tool-behavior)：[部署在 Anthropic 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)仅

287 * [Auto mode](/docs/zh-CN/auto-mode-config)：仅 Sonnet 5 或更高版本、Opus 4.7 或更高版本、Haiku 5.5 以及 Fable 模型286 * [Auto mode](/docs/zh-CN/auto-mode-config)：仅 Sonnet 5 或更高版本、Opus 4.7 或更高版本、Haiku 5.5 以及 Fable 模型

288 * [Cross-session messaging](/docs/zh-CN/cross-session-messaging)：仅在此机器上的您的会话之间 <sup><a href="#fn5">5</a></sup>287 * [Cross-session messaging](/docs/zh-CN/cross-session-messaging)：仅在此机器上的您的会话之间 <sup><a href="#fn5">5</a></sup>

289 * [Zero Data Retention](/docs/zh-CN/zero-data-retention)：受您的 Azure 协议约束288 * [Zero Data Retention](/docs/zh-CN/zero-data-retention)：受您的 Azure 协议约束

294 <Tab title="Anthropic Console">293 <Tab title="Anthropic Console">

295 **不可用：** 所有[需要 Claude 订阅的功能](#features-that-require-a-claude-subscription)。294 **不可用：** 所有[需要 Claude 订阅的功能](#features-that-require-a-claude-subscription)。

296 295

297 [按提供商变化的 CLI 功能](#cli-capabilities-that-vary-by-provider)中的所有内容都可用，除了 [fast mode](/docs/zh-CN/fast-mode) 需要[预配置访问](/docs/zh-CN/fast-mode#enable-fast-mode-for-your-organization)。当您的 API 密钥属于 Team 或 Enterprise 组织时，[Server-managed settings](/docs/zh-CN/server-managed-settings) 也可用。296 [按提供商变化的 CLI 功能](#cli-capabilities-that-vary-by-provider)中的所有内容都可用，除了 [fast mode](/docs/zh-CN/fast-mode) 需要[预配置访问](/docs/zh-CN/fast-mode#enable-fast-mode-for-your-organization)。在 claude.ai Team 或 Enterprise 组织中配置的 [Server-managed settings](/docs/zh-CN/server-managed-settings) 不会作用于使用 Console API 密钥进行身份验证的会话。有关如何覆盖这些会话，请参阅[平台可用性](/docs/zh-CN/server-managed-settings#platform-availability)。

298 </Tab>297 </Tab>

299</Tabs>298</Tabs>

300 299

github-actions.md +2 −0

Details

140| 权限 | 访问 |140| 权限 | 访问 |

141| - | - |141| - | - |

142| Actions | 读写 |142| Actions | 读写 |

143| Administration | 读 |

143| Checks | 读写 |144| Checks | 读写 |

144| Contents | 读写 |145| Contents | 读写 |

145| Discussions | 读写 |146| Discussions | 读写 |

146| Issues | 读写 |147| Issues | 读写 |

147| Members | 读 |148| Members | 读 |

149| Merge queues | 读 |

148| Metadata | 读 |150| Metadata | 读 |

149| Pull requests | 读写 |151| Pull requests | 读写 |

150| Repository hooks | 读写 |152| Repository hooks | 读写 |

glossary.md +1 −1

Details

294 Output style294 Output style

295</h3>295</h3>

296 296

297一个配置，改变 Claude Code 给予 Claude 的指令，以设置响应行为、语气或格式。与 [CLAUDE.md](#claude-md) 不同，后者在 Claude Code 的默认指令旁添加项目上下文，自定义输出样式可以替换默认的软件工程指令。297一个配置，改变 Claude Code 给予 Claude 的指令，以设置回复行为、语气或格式。与 [CLAUDE.md](#claude-md) 不同，后者在 Claude Code 的默认指令旁添加项目上下文，自定义输出样式会添加自己的指令，并且可以省略默认的软件工程指令。

298 298

299了解更多：[Output styles](/docs/zh-CN/output-styles)299了解更多：[Output styles](/docs/zh-CN/output-styles)

300 300

google-vertex-ai.md +4 −2

Details

342 1M token context window342 1M token context window

343</h2>343</h2>

344 344

345Claude Sonnet 5、Opus 4.6 及更高版本以及 Sonnet 4.6 在 Google Cloud 的 Agent Platform 上支持 [1M token context window](https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows#context-window-sizes-by-model)。Sonnet 5 始终以 1M 窗口运行，没有 `[1m]` 变体可选择。对于其他模型，当您选择 1M 模型变体时，Claude Code 会自动启用扩展 context window。345Fable 模型、Sonnet 5 及更高版本以及 Opus 4.7 及更高版本在 Google Cloud 的 Agent Platform 上默认以 [1M token 上下文窗口](https://platform.claude.com/docs/zh-CN/build-with-claude/context-windows#context-window-sizes-by-model)运行，无需 `[1m]` 后缀。如需改为保留 200K 窗口，请设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-CN/model-config#turn-off-1m-context)。

346 346

347[设置向导](#sign-in-with-agent-platform)在固定模型时提供 1M context 选项。要为手动固定的模型启用它，请在模型 ID 后附加 `[1m]`。有关详细信息，请参阅[为第三方部署固定模型](/docs/zh-CN/model-config#pin-models-for-third-party-deployments)，包括如何在不更改固定的情况下使用 1M 窗口。347Opus 4.6 和 Sonnet 4.6 在您选择其 `[1m]` 变体时可使用 1M 窗口。[设置向导](#sign-in-with-agent-platform)在固定模型时提供 1M 上下文选项。如需改为为手动固定的模型启用它，请在模型 ID 后附加 `[1m]`。有关详细信息，请参阅[为第三方部署固定模型](/docs/zh-CN/model-config#pin-models-for-third-party-deployments)，包括如何在不更改固定的情况下使用 1M 窗口。

348

349在 v2.1.287 之前，Fable 模型以及 Opus 4.7 及更高版本在 Google Cloud 的 Agent Platform 上默认以 200K 窗口运行，并通过 `[1m]` 后缀使用 1M 窗口。

348 350

349<h2 id="troubleshooting">351<h2 id="troubleshooting">

350 故障排除352 故障排除

headless.md +9 −4

Details

78 退出时的后台任务78 退出时的后台任务

79</h3>79</h3>

80 80

81如果 Claude 在 `claude -p` 运行期间启动 [后台 Bash 任务](/docs/zh-CN/tools-reference#bash-tool-behavior)（例如开发服务器或监视构建），该 shell 将在 Claude 返回其最终结果并关闭 stdin 后约五秒钟被终止。宽限期允许在结果之后立即完成的任务仍然传递其输出。81在 Claude 完成其轮次且 stdin 关闭后，`claude -p` 运行可以保持打开状态，以等待 Claude 启动的后台工作。

82 82

~~83如果 Claude 启动后台 [subagent](/docs/zh-CN/sub-agents) 或工作流，`claude -p` 会改为保持打开状态，直到该工作完成，因为其结果是最终输出的一部分。~~83除非主对话启动的后台命令仍在运行，否则默认情况下，Claude Code 会在连续空闲等待 10 分钟后停止仍在运行的任何内容，并丢弃其部分结果。要更改 10 分钟上限，请设置 [`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`](/docs/zh-CN/env-vars)，或将其设置为 `0` 以在没有上限的情况下等待。

84 84

85默认情况下，等待在连续空闲等待 10 分钟后结束，因此卡住的 subagent 或工作流无法无限期地保持进程打开。此时 Claude Code 停止仍在运行的任何内容并丢弃其部分结果。要更改限制，请设置 [`CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`](/docs/zh-CN/env-vars)，或将其设置为 `0` 以无限期等待。85运行会等待后台工作，例如后台命令、子代理和工作流、Monitor 监视以及待处理的 `/loop` 唤醒：

86 86

87如果 Claude 在 `claude -p` 运行期间启动 [Monitor](/docs/zh-CN/tools-reference#monitor-tool) 监视，Claude Code 会等待监视直到它超时或十分钟的上限结束等待，以先发生者为准。在等待期间，Claude 继续响应监视报告的内容。默认情况下，监视在 Claude 启动后五分钟超时。87* **[后台命令](/docs/zh-CN/tools-reference#background-commands)**：对于主对话启动的命令（例如开发服务器或监视构建），运行会等待，直到该命令退出或达到其 [时间限制](/docs/zh-CN/tools-reference#time-limit-for-background-commands)。随后 Claude 会根据结果再进行一轮，该轮次的结果成为运行的最后结果，也就是 `text` 和 `json` 输出所打印的结果。在命令运行期间，10 分钟上限不会结束等待。

88* **后台[子代理](/docs/zh-CN/sub-agents)和工作流**：运行会保持打开状态，直到该工作完成，因为其结果是最终输出的一部分。

89* **[Monitor](/docs/zh-CN/tools-reference#monitor-tool) 监视**：运行会等待，直到监视超时或 10 分钟上限结束等待，以先发生者为准。在等待期间，Claude 会继续响应监视报告的内容。默认情况下，监视在 Claude 启动后五分钟超时。

90* **待处理的唤醒**：在以文本形式而非通过 `--input-format stream-json` 传递提示词的运行中，如果 Claude 已安排 [自定节奏的 `/loop` 唤醒](/docs/zh-CN/scheduled-tasks#let-claude-choose-the-interval)，运行会等待每次唤醒触发并执行其迭代，直到 [循环结束](/docs/zh-CN/scheduled-tasks#stop-a-loop)，即使超过 10 分钟上限也是如此。

92如果运行达到其 [`--max-budget-usd`](/docs/zh-CN/cli-reference#cli-flags) 上限，Claude Code 会停止剩余的后台工作，而不是继续等待。

88 93

89<h3 id="stop-a-run-with-sigterm">94<h3 id="stop-a-run-with-sigterm">

90 使用 SIGTERM 停止运行95 使用 SIGTERM 停止运行

hooks.md +711 −542

Details

757 Hook 输入和输出757 Hook 输入和输出

758</h2>758</h2>

759 759

760命令 hook 通过 stdin 接收 JSON 数据，并通过退出代码、stdout 和 stderr 传达结果。HTTP hook 接收与 POST 请求体相同的 JSON，并通过 HTTP 响应体传达结果。本节涵盖所有事件通用的字段和行为。[Hook 事件](#hook-events)下的每个事件部分包括其特定的输入架构和决策控制选项。760命令 hook 通过 stdin 接收 JSON 数据，并通过退出码、stdout 和 stderr 传达结果。HTTP hook 接收与 POST 请求体相同的 JSON，并通过 HTTP 响应体传达结果。本节涵盖所有事件通用的字段和行为。[Hook 事件](#hook-events)下的每个事件部分包括其特定的输入 schema 和决策控制选项。

761 761

762在 macOS 和 Linux 上，命令 hook 在没有控制终端的自己的会话中运行。hook 进程和任何子进程无法打开 `/dev/tty` 或直接向 Claude Code 界面发送转义序列。Windows 没有 `/dev/tty`。762在 macOS 和 Linux 上，命令 hook 在没有控制终端的自己的会话中运行。hook 进程和任何子进程无法打开 `/dev/tty` 或直接向 Claude Code 界面发送转义序列。Windows 没有 `/dev/tty`。

763 763

773| :- | :- |773| :- | :- |

775| `prompt_id` | 标识当前正在处理的用户提示词的 UUID。与 [OpenTelemetry 事件上的 `prompt.id` 属性](/docs/zh-CN/monitoring-usage#event-correlation-attributes)匹配，因此您可以将 hook 输出与单个提示词的遥测关联起来。在第一个用户输入之前不存在 |775| `prompt_id` | 标识当前正在处理的用户提示词的 UUID。与 [OpenTelemetry 事件上的 `prompt.id` 属性](/docs/zh-CN/monitoring-usage#event-correlation-attributes)匹配，因此您可以将 hook 输出与单个提示词的遥测关联起来。在第一个用户输入之前不存在 |

776| `transcript_path` | 对话 JSON 的路径。转录文件异步写入，可能滞后于内存中的对话，因此当 hook 触发时，它可能还不包括当前轮次的最新消息。需要当前轮次最终助手文本的 hook 应在 [Stop](#stop) 和 [SubagentStop](#subagentstop) 上使用 `last_assistant_message`，而不是读取转录 |776| `transcript_path` | 对话 JSON 的路径。会话记录文件异步写入，可能滞后于内存中的对话，因此当 hook 触发时，它可能还不包括当前轮次的最新消息。需要当前轮次最终助手文本的 hook 应在 [Stop](#stop) 和 [SubagentStop](#subagentstop) 上使用 `last_assistant_message`，而不是读取会话记录 |

777| `cwd` | 调用 hook 时的当前工作目录 |777| `cwd` | 调用 hook 时的当前工作目录 |

778| `scratchpad_dir` | 会话的 [scratchpad 目录](/docs/zh-CN/claude-directory#session-scratchpad-directory)的路径，Claude 在其中保存临时工作文件。当会话没有 scratchpad 或 temp 目录不可用时不存在。需要 Claude Code v2.1.257 或更高版本 |778| `scratchpad_dir` | 会话的 [scratchpad 目录](/docs/zh-CN/claude-directory#session-scratchpad-directory)的路径，Claude 在其中保存临时工作文件。当会话没有 scratchpad 或 temp 目录不可用时不存在。需要 Claude Code v2.1.257 或更高版本 |

779| `permission_mode` | 当前[权限模式](/docs/zh-CN/permissions#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。标记为**手动**的模式作为 `"default"` 到达，从不作为 `"manual"`，因此匹配 `"default"` 的脚本继续工作。并非所有事件都接收此字段。检查每个 [hook 事件](#hook-events)部分中的 JSON 示例 |779| `permission_mode` | 当前[权限模式](/docs/zh-CN/permissions#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。标记为**手动**的模式作为 `"default"` 到达，从不作为 `"manual"`，因此匹配 `"default"` 的脚本继续工作。并非所有事件都接收此字段。检查每个 [hook 事件](#hook-events)部分中的 JSON 示例 |

780| `effort` | 对象，其 `level` 字段保存 hook 运行时生效的[工作量级别](/docs/zh-CN/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。如果您设置了活跃模型不支持的级别，`level` 会报告 Claude Code 运行的级别；[调整工作量级别](/docs/zh-CN/model-config#adjust-effort-level)说明它如何选择该级别。该对象与[状态行](/docs/zh-CN/statusline#available-data) `effort` 字段匹配。对于在工具使用上下文中触发的事件（如 `PreToolUse`、`PostToolUse`、`Stop` 和 `SubagentStop`），当当前模型支持工作量参数时存在。该级别也可作为 `$CLAUDE_EFFORT` 环境变量供 hook 命令和 Bash 工具使用。 |780| `effort` | 对象，其 `level` 字段保存 hook 运行时生效的 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。如果您设置了活跃模型不支持的级别，`level` 会报告 Claude Code 实际运行的级别；[调整 effort 级别](/docs/zh-CN/model-config#adjust-effort-level)说明它如何选择该级别。该对象与[状态栏](/docs/zh-CN/statusline#available-data) `effort` 字段匹配。对于在工具使用上下文中触发的事件（如 `PreToolUse`、`PostToolUse`、`Stop` 和 `SubagentStop`），当当前模型支持 effort 参数时存在。该级别也可作为 `$CLAUDE_EFFORT` 环境变量供 hook 命令和 Bash 工具使用。 |

782 782

783使用 `--agent` 运行或在 subagent 内部时，包括两个额外字段：783使用 `--agent` 运行或在子代理内部时，包括两个额外字段：

784 784

785| 字段 | 描述 |785| 字段 | 描述 |

786| :- | :- |786| :- | :- |

788| `agent_type` | Agent 名称（例如，`"Explore"` 或 `"security-reviewer"`）。当会话使用 `--agent` 或 hook 在 subagent 内触发时存在。对于 subagent，subagent 的类型优先于会话的 `--agent` 值。请参阅 [SubagentStart](#subagentstart) 了解自定义和插件 subagent 报告的值以及如何针对插件范围的名称编写匹配器。 |788| `agent_type` | Agent 名称（例如，`"Explore"` 或 `"security-reviewer"`）。当会话使用 `--agent` 或 hook 在子代理内触发时存在。对于子代理，子代理的类型优先于会话的 `--agent` 值。请参阅 [SubagentStart](#subagentstart) 了解自定义和插件子代理报告的值以及如何针对限定于插件的名称编写匹配器。 |

789 789

790只有 [`SessionStart`](#sessionstart) hook 可以接收 `model` 字段，Claude Code 并不总是包括它。[`PreModelSwitch`](#premodelswitch) 和 [`PostModelSwitch`](#postmodelswitch) hook 改为接收 `from_model` 和 `to_model`，因此使用 PostModelSwitch hook 来跟踪模型在会话期间的变化。790只有 [`SessionStart`](#sessionstart) hook 可以接收 `model` 字段，Claude Code 并不总是包括它。[`PreModelSwitch`](#premodelswitch) 和 [`PostModelSwitch`](#postmodelswitch) hook 改为接收 `from_model` 和 `to_model`，因此使用 PostModelSwitch hook 来跟踪模型在会话期间的变化。

791 791

818`tool_name`、`tool_input` 和 `tool_use_id` 字段是事件特定的。每个 [hook 事件](#hook-events)部分记录该事件的额外字段。818`tool_name`、`tool_input` 和 `tool_use_id` 字段是事件特定的。每个 [hook 事件](#hook-events)部分记录该事件的额外字段。

819 819

820<h3 id="exit-code-output">820<h3 id="exit-code-output">

821 退出代码输出821 退出码输出

822</h3>822</h3>

823 823

824来自 hook 命令的退出代码告诉 Claude Code 该操作是否应继续、被阻止或被忽略。退出代码不单独起作用。Claude Code 从 stdout 读取[JSON 输出字段](#json-output)，无论退出代码是什么，对于使用标准决策模型的事件，通过架构验证的解析对象与代码一起生效。退出 2 的阻止是 JSON 无法覆盖的唯一结果。824来自 hook 命令的退出码告诉 Claude Code 该操作是否应继续、被阻止或被忽略。退出码不单独起作用。Claude Code 从 stdout 读取 [JSON 输出字段](#json-output)，无论退出码是什么（不仅仅是 0），对于使用标准决策模型的事件，通过 schema 验证的解析对象与退出码一起生效。退出 2 的阻止是 JSON 无法覆盖的唯一结果。

825 825

826两个表拥有每个事件的例外：[每个事件的退出代码 2 行为](#exit-code-2-behavior-per-event)说明退出代码对每个事件的作用，[决策控制](#decision-control)说明每个事件接受哪些决策字段。通用字段如 `systemMessage` 在大多数事件中工作，并在 [JSON 输出](#json-output)表中列出。826两个表负责说明每个事件的例外：[每个事件的退出码 2 行为](#exit-code-2-behavior-per-event)说明退出码对每个事件的作用，[决策控制](#decision-control)说明每个事件接受哪些决策字段。通用字段如 `systemMessage` 在大多数事件中工作，并在 [JSON 输出](#json-output)表中列出。

827 827

828<h4 id="exit-code-0">828<h4 id="exit-code-0">

829 退出代码 0829 退出码 0

830</h4>830</h4>

831 831

832退出 0 表示成功，是您打印 JSON 进行结构化控制时的预期退出代码。832退出 0 表示成功，是您打印 JSON 进行结构化控制时的预期退出码。

833 833

834对于大多数事件，Claude Code 将 stdout 写入调试日志，不在转录中显示。例外是 `UserPromptSubmit`、`UserPromptExpansion`、`SessionStart` 和 `PostModelSwitch`，其中 Claude Code 添加纯文本 stdout 作为 Claude 可以看到和作用的上下文。834对于大多数事件，Claude Code 将 stdout 写入调试日志，不在会话记录中显示。例外是 `UserPromptSubmit`、`UserPromptExpansion`、`SessionStart` 和 `PostModelSwitch`，其中 Claude Code 添加纯文本 stdout 作为 Claude 可以看到并据此行动的上下文。

835 835

836Claude Code 是否将您的 stdout 读取为 [JSON 输出](#json-output)或纯文本取决于它如何开始和结束，忽略周围的空格：836Claude Code 是否将您的 stdout 读取为 [JSON 输出](#json-output)或纯文本取决于它如何开始和结束，忽略周围的空白：

837 837

838* **以 `{` 开始并以 `}` 结束**：Claude Code 将其解析为 JSON。当输出是两行或更多行，每行本身都解析为 JSON，且没有行是设置字段的 [JSON 输出](#json-output)对象时，Claude Code 将整个输出视为纯文本。当其中一行确实设置了字段时，整个输出是解析失败，如下所述。838* **以 `{` 开始并以 `}` 结束**：Claude Code 将其解析为 JSON。当输出是两行或更多行，每行本身都解析为 JSON，且没有行是设置字段的 [JSON 输出](#json-output)对象时，Claude Code 将整个输出视为纯文本。当其中一行确实设置了字段时，整个输出是解析失败，如下所述。

839* **以 `{` 开始但不以 `}` 结束**：Claude Code 将其视为纯文本。839* **以 `{` 开始但不以 `}` 结束**：Claude Code 将其视为纯文本。

840* **以其他任何内容开始**：Claude Code 将其视为纯文本，即使它是 JSON 数组或带引号的 JSON 字符串也是如此。840* **以其他任何内容开始**：Claude Code 将其视为纯文本，即使它是 JSON 数组或带引号的 JSON 字符串也是如此。

841 841

842对于使用标准决策模型的事件，退出 0 且解析对象未通过架构验证是非阻止错误：操作继续，转录显示 `<hook name> hook error` 通知，带有验证消息。在任何退出代码（除 2 外）上都会发生相同情况，而[退出 2 仍然阻止](#exit-code-2)。842对于使用标准决策模型的事件，退出 0 且解析对象未通过 schema 验证是非阻止错误：操作继续，会话记录显示 `<hook name> hook error` 通知，带有验证消息。在除 2 以外的任何退出码上都会发生相同情况，而[退出 2 仍然阻止](#exit-code-2)。

843 843

844对于使用标准决策模型的事件，当 Claude Code 尝试将您的 stdout 解析为 JSON 且无法解析时，它在除 2 外的每个退出代码上报告非阻止错误。转录显示 `<hook name> hook error` 通知，带有解析消息。在添加纯文本 stdout 作为上下文的事件上，Claude Code 不添加文本。在 v2.1.248 之前，Claude Code 将该 stdout 视为纯文本。844对于使用标准决策模型的事件，当 Claude Code 尝试将您的 stdout 解析为 JSON 且无法解析时，它在除 2 外的每个退出码上报告非阻止错误。会话记录显示 `<hook name> hook error` 通知，带有解析消息。在添加纯文本 stdout 作为上下文的事件上，Claude Code 不添加文本。在 v2.1.248 之前，Claude Code 将该 stdout 视为纯文本。

845 845

846来自退出 0 的 hook 的 Stderr 仅进入调试日志，从不进入转录，Claude 从不看到它。要自己读取它，请启用[调试日志](#debug-hooks)。要从 `PostToolUse` 或 `PostToolUseFailure` hook 向 Claude 显示警告，请改为退出 2，以便[Claude 看到 stderr](#exit-code-2-behavior-per-event)，即使工具已经运行。846来自退出 0 的 hook 的 stderr 仅进入调试日志，从不进入会话记录，Claude 从不看到它。要自己读取它，请启用[调试日志](#debug-hooks)。要从 `PostToolUse` 或 `PostToolUseFailure` hook 向 Claude 显示警告，请改为退出 2，以便 [Claude 看到 stderr](#exit-code-2-behavior-per-event)，即使工具已经运行。

847 847

848<h4 id="exit-code-2">848<h4 id="exit-code-2">

849 退出代码 2849 退出码 2

850</h4>850</h4>

851 851

852退出 2 表示阻止错误。在[可以阻止的事件](#exit-code-2-behavior-per-event)上，退出 2 无论您是否打印 JSON 都会阻止：即使 JSON `permissionDecision` 为 `"allow"` 也无法覆盖它。Claude Code 仍然读取 stdout 上的任何有效 [JSON 输出](#json-output)。在 `Elicitation` 和 `ElicitationResult` 上，退出 2 hook 的 `hookSpecificOutput` 被忽略。852退出 2 表示阻止错误。在[可以阻止的事件](#exit-code-2-behavior-per-event)上，无论您是否打印 JSON，退出 2 都会阻止：即使 JSON `permissionDecision` 为 `"allow"` 也无法覆盖它。Claude Code 仍然读取 stdout 上的任何有效 [JSON 输出](#json-output)。在 `Elicitation` 和 `ElicitationResult` 上，退出 2 的 hook 的 `hookSpecificOutput` 被忽略。

853 853

854阻止消息是您的 JSON 的阻止决策的原因（当它做出一个时），否则是您的 stderr 文本。阻止做什么因事件而异：`PreToolUse` 阻止工具调用，`UserPromptSubmit` 拒绝提示，等等。[每个事件的退出代码 2 行为](#exit-code-2-behavior-per-event)列出每个事件的效果，每个事件的部分说明消息去向。854阻止消息是您的 JSON 阻止决策中的原因（如果它做出了阻止决策），否则是您的 stderr 文本。阻止的作用因事件而异：`PreToolUse` 阻止工具调用，`UserPromptSubmit` 拒绝提示词，等等。[每个事件的退出码 2 行为](#exit-code-2-behavior-per-event)列出每个事件的效果，每个事件的部分说明消息去向。

855 855

856退出 2 的 hook 同时打印 JSON 且未通过 [JSON 输出](#json-output)架构验证仍然阻止：Claude Code 使用 stderr 作为阻止原因，并在调试日志中记录验证失败。在 v2.1.214 之前，Claude Code 将该组合视为非阻止错误，操作继续。856退出 2 的 hook 同时打印未通过 [JSON 输出](#json-output) schema 验证的 JSON 时仍然阻止：Claude Code 使用 stderr 作为阻止原因，并在调试日志中记录验证失败。在 v2.1.214 之前，Claude Code 将该组合视为非阻止错误，操作继续。

857 857

858此脚本通过退出 2 阻止 `rm` 命令，并将所有其他命令留给正常权限流：858此脚本通过退出 2 阻止 `rm` 命令，并将所有其他命令留给正常权限流程：

859 859

860```bash theme={null}860```bash theme={null}

861#!/bin/bash861#!/bin/bash

872```872```

873 873

874<h4 id="other-exit-codes">874<h4 id="other-exit-codes">

875 其他退出代码875 其他退出码

876</h4>876</h4>

877 877

878任何其他退出代码对于大多数 hook 事件本身不会阻止。发生什么取决于您的 stdout：878对于大多数 hook 事件，任何其他退出码本身不会阻止。发生什么取决于您的 stdout：

879 879

880* 使用通过架构验证的解析对象，对于使用标准决策模型的事件，Claude Code 忽略退出代码，JSON 单独决定结果：880* 使用通过 schema 验证的解析对象时，对于使用标准决策模型的事件，Claude Code 忽略退出码，仅由 JSON 决定结果：

881 * 事件支持的每个字段都被接受，包括 `permissionDecision`、`additionalContext`、`updatedInput` 和 `systemMessage`，hook 不被报告为错误。881 * 事件支持的每个字段都会生效，包括 `permissionDecision`、`additionalContext`、`updatedInput` 和 `systemMessage`，hook 不被报告为错误。

882 * [决策控制](#decision-control)列出每个事件的决策字段；通用字段如 `systemMessage` 遵循 [JSON 输出](#json-output)表。882 * [决策控制](#decision-control)列出每个事件的决策字段；通用字段如 `systemMessage` 遵循 [JSON 输出](#json-output)表。

883* 使用未通过架构验证的解析对象，对于使用标准决策模型的事件，它与[退出 0 上](#exit-code-0)相同的非阻止错误：操作继续，`<hook name> hook error` 通知带有验证消息。883* 使用未通过 schema 验证的解析对象时，对于使用标准决策模型的事件，它与[退出 0 时](#exit-code-0)相同，是非阻止错误：操作继续，`<hook name> hook error` 通知带有验证消息。

884* 使用 Claude Code [尝试解析为 JSON](#exit-code-0)且无法解析的 stdout，Claude Code 报告与退出 0 上相同的非阻止错误，用于使用标准决策模型的事件。操作继续，通知带有解析消息。884* 使用 Claude Code [尝试解析为 JSON](#exit-code-0) 但无法解析的 stdout 时，对于使用标准决策模型的事件，Claude Code 报告与退出 0 时相同的非阻止错误。操作继续，通知带有解析消息。

885* 使用 Claude Code [视为纯文本](#exit-code-0)的 stdout，或使用空 stdout，对于大多数 hook 事件是非阻止错误：操作继续，转录显示 `<hook name> hook error` 通知，后跟 stderr 的第一行，前缀为 `Failed with non-blocking status code:`。要捕获完整 stderr，请启用[调试日志](#debug-hooks)。885* 使用 Claude Code [视为纯文本](#exit-code-0)的 stdout，或使用空 stdout 时，对于大多数 hook 事件是非阻止错误：操作继续，会话记录显示 `<hook name> hook error` 通知，后跟 stderr 的第一行，前缀为 `Failed with non-blocking status code:`。要捕获完整 stderr，请启用[调试日志](#debug-hooks)。

886 886

887标准决策模型之外的事件在[每个事件表](#exit-code-2-behavior-per-event)中保持自己的行：`WorktreeCreate` 在任何非零退出时失败创建，无论您的 JSON 说什么，事件丢弃 hook 输出（如 `StopFailure`）在每个退出代码上忽略您的 JSON，除了副作用字段如 `terminalSequence`，它仍然触发。887标准决策模型之外的事件在[每个事件表](#exit-code-2-behavior-per-event)中保留自己的行：`WorktreeCreate` 在任何非零退出时都会使创建失败，无论您的 JSON 说什么；完全丢弃 hook 输出的事件（如 `StopFailure`）在每个退出码上都忽略您的 JSON，但 `terminalSequence` 等副作用字段除外，它们仍会触发。

888 888

889无法启动的 hook 落入相同的非阻止桶。当脚本路径不存在或不可执行时，shell 以代码（如 127）退出，您看到相同的通知，带有解释器的消息，例如 `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`。对于大多数 hook 事件，操作继续。当您设置策略 hook 时，在其第一次运行时观察此通知：`settings.json` 中的拼写错误的路径使门无声地禁用。889无法启动的 hook 也归入相同的非阻止类别。当脚本路径不存在或不可执行时，shell 以某个代码（如 127）退出，您会看到相同的通知，带有解释器的消息，例如 `Failed with non-blocking status code: /bin/sh: /path/to/hook.sh: No such file or directory`。对于大多数 hook 事件，操作继续。当您设置策略 hook 时，请在其第一次运行时留意此通知：`settings.json` 中拼写错误的路径会使该关卡被悄无声息地禁用。

890 890

891<Warning>891<Warning>

892 对于大多数 hook 事件，退出代码 2 是唯一通过代码单独阻止的退出代码。没有 stdout 上的有效 JSON，Claude Code 将退出代码 1 视为非阻止错误并继续操作，即使 1 是传统的 Unix 失败代码。如果您的 hook 旨在强制执行策略，请使用 `exit 2`。worktree 事件不同：来自 `WorktreeCreate` 的任何非零退出代码中止 worktree 创建，来自 `WorktreeRemove` 的任何非零退出代码使 worktree 移除失败（如果目录仍然存在）。892 对于大多数 hook 事件，退出码 2 是唯一仅凭退出码即可阻止的退出码。如果 stdout 上没有有效 JSON，Claude Code 将退出码 1 视为非阻止错误并继续操作，即使 1 是传统的 Unix 失败代码。如果您的 hook 旨在强制执行策略，请使用 `exit 2`。worktree 事件不同：来自 `WorktreeCreate` 的任何非零退出码都会中止 worktree 创建，来自 `WorktreeRemove` 的任何非零退出码会在目录之后仍然存在时使 worktree 移除失败。

893</Warning>893</Warning>

894 894

895<h4 id="timeouts">895<h4 id="timeouts">

896 超时896 超时

897</h4>897</h4>

898 898

899除了您使用 [`async: true`](#run-hooks-in-the-background) 运行的命令 hook，Claude Code 取消达到其 [`timeout`](#common-fields) 的 `command`、`http` 或 `mcp_tool` hook，丢弃 hook 的输出，因此在大多数事件上超时的 hook 不呈现决策。899除了您使用 [`async: true`](#run-hooks-in-the-background) 运行的命令 hook 外，Claude Code 会取消达到其 [`timeout`](#common-fields) 的 `command`、`http` 或 `mcp_tool` hook，并丢弃 hook 的输出，因此在大多数事件上，超时的 hook 不会做出决策。

900 900

901在 [`PreModelSwitch`](#premodelswitch) 上，在其超时处取消的 hook 阻止模型切换。在 `PreToolUse` 上，两个 hook 系列不同：901在 [`PreModelSwitch`](#premodelswitch) 上，因超时被取消的 hook 会阻止模型切换。在 `PreToolUse` 上，两类 hook 的行为不同：

902 902

903* 超时的 `command`、`http` 或 `mcp_tool` hook 不阻止工具调用。调用通过正常[权限流](/docs/zh-CN/permissions)继续，因此不要指望停滞的 hook 充当门。903* 超时的 `command`、`http` 或 `mcp_tool` hook 不阻止工具调用。调用通过正常[权限流程](/docs/zh-CN/permissions)继续，因此不要指望停滞的 hook 充当关卡。

904* 超过其超时的 [Agent SDK 回调 hook](/docs/zh-CN/agent-sdk/hooks) [阻止工具调用](#pretooluse)。904* 超过其超时时间的 [Agent SDK 回调 hook](/docs/zh-CN/agent-sdk/hooks) 会[阻止工具调用](#pretooluse)。

905 905

906<h4 id="exit-code-2-behavior-per-event">906<h4 id="exit-code-2-behavior-per-event">

907 每个事件的退出代码 2 行为907 每个事件的退出码 2 行为

908</h4>908</h4>

909 909

910退出代码 2 是 hook 发出"停止，不要这样做"信号的方式。效果取决于事件，因为某些事件代表可以被阻止的操作（如尚未发生的工具调用），而其他事件代表已经发生或无法防止的事情。910退出码 2 是 hook 发出"停止，不要这样做"信号的方式。效果取决于事件，因为某些事件代表可以被阻止的操作（如尚未发生的工具调用），而其他事件代表已经发生或无法防止的事情。

911 911

913| :- | :- | :- |913| :- | :- | :- |

914| `PreToolUse` | 是 | 阻止工具调用 |914| `PreToolUse` | 是 | 阻止工具调用 |

915| `PermissionRequest` | 否 | 此事件不接受退出代码 2，权限流程保持不变。改为通过 [`decision` 对象](#permissionrequest-decision-control)拒绝 |915| `PermissionRequest` | 否 | 此事件不接受退出码 2，权限流程保持不变。改为通过 [`decision` 对象](#permissionrequest-decision-control)拒绝 |

916| `UserPromptSubmit` | 是 | 阻止提示，所以它永远不会到达 Claude。请参阅[被阻止的提示留下什么](#what-a-blocked-prompt-leaves-behind) |916| `UserPromptSubmit` | 是 | 阻止提示词，使其永远不会到达 Claude。请参阅[被阻止的提示词留下什么](#what-a-blocked-prompt-leaves-behind) |

917| `UserPromptExpansion` | 是 | 阻止扩展 |917| `UserPromptExpansion` | 是 | 阻止扩展 |

918| `Stop` | 是 | 防止 Claude 停止，继续对话 |918| `Stop` | 是 | 防止 Claude 停止，继续对话 |

919| `SubagentStop` | 是 | 防止 subagent 停止 |919| `SubagentStop` | 是 | 防止子代理停止 |

920| `TeammateIdle` | 是 | 防止队友空闲，因此它继续工作 |920| `TeammateIdle` | 是 | 防止队友空闲，因此它继续工作 |

921| `TaskCreated` | 是 | 回滚任务创建 |921| `TaskCreated` | 是 | 回滚任务创建 |

922| `TaskCompleted` | 是 | 防止任务被标记为已完成 |922| `TaskCompleted` | 是 | 防止任务被标记为已完成 |

923| `ConfigChange` | 是 | 阻止配置更改生效（除 `policy_settings` 外） |923| `ConfigChange` | 是 | 阻止配置更改生效（除 `policy_settings` 外） |

924| `StopFailure` | 否 | 输出和退出代码被忽略，除 `terminalSequence` 外 |924| `StopFailure` | 否 | 输出和退出码被忽略，除 `terminalSequence` 外 |

925| `PostToolUse` | 否 | 向 Claude 显示 stderr；工具已经运行 |925| `PostToolUse` | 否 | 向 Claude 显示 stderr；工具已经运行 |

926| `PostToolUseFailure` | 否 | 向 Claude 显示 stderr；工具已经失败 |926| `PostToolUseFailure` | 否 | 向 Claude 显示 stderr；工具已经失败 |

927| `PostToolBatch` | 是 | 在下一个模型调用之前停止代理循环 |927| `PostToolBatch` | 是 | 在下一次模型调用之前停止智能体循环 |

928| `PermissionDenied` | 否 | 退出代码和 stderr 被忽略，因为拒绝已经发生。使用 JSON `hookSpecificOutput.retry: true` 告诉模型它可能重试；Claude Code 对[无判决拒绝](#permissiondenied-decision-control)忽略 `retry: true` |928| `PermissionDenied` | 否 | 退出码和 stderr 被忽略，因为拒绝已经发生。使用 JSON `hookSpecificOutput.retry: true` 告诉模型它可以重试；Claude Code 对[无判决拒绝](#permissiondenied-decision-control)忽略 `retry: true` |

929| `Notification` | 否 | 退出代码和 stderr 被忽略 |929| `Notification` | 否 | 退出码和 stderr 被忽略 |

930| `SubagentStart` | 否 | 仅向用户显示 stderr |930| `SubagentStart` | 否 | 仅向用户显示 stderr |

931| `SessionStart` | 否 | 仅向用户显示 stderr |931| `SessionStart` | 否 | 仅向用户显示 stderr |

932| `Setup` | 否 | 退出代码和 stderr 被忽略 |932| `Setup` | 否 | 退出码和 stderr 被忽略 |

933| `SessionEnd` | 否 | 仅向用户显示 stderr |933| `SessionEnd` | 否 | 仅向用户显示 stderr |

934| `CwdChanged` | 否 | 仅向用户显示 stderr |934| `CwdChanged` | 否 | 仅向用户显示 stderr |

935| `DirectoryAdded` | 否 | Stderr 进入调试日志；目录已经添加 |935| `DirectoryAdded` | 否 | stderr 进入调试日志；目录已经添加 |

936| `FileChanged` | 否 | 仅向用户显示 stderr |936| `FileChanged` | 否 | 仅向用户显示 stderr |

937| `PreCompact` | 是 | 阻止压缩 |937| `PreCompact` | 是 | 阻止压缩 |

938| `PostCompact` | 否 | 仅向用户显示 stderr |938| `PostCompact` | 否 | 仅向用户显示 stderr |

939| `PreModelSwitch` | 是 | 阻止模型切换并向用户显示 stderr |939| `PreModelSwitch` | 是 | 阻止模型切换并向用户显示 stderr |

940| `PostModelSwitch` | 否 | 仅向用户显示 stderr；模型已经切换 |940| `PostModelSwitch` | 否 | 仅向用户显示 stderr；模型已经切换 |

941| `Elicitation` | 是 | 拒绝引出 |941| `Elicitation` | 是 | 拒绝该请求，且不显示对话框 |

942| `ElicitationResult` | 是 | 阻止响应（操作变为拒绝） |942| `ElicitationResult` | 是 | 阻止响应（操作变为拒绝） |

943| `WorktreeCreate` | 是 | 任何非零退出代码导致 worktree 创建失败 |943| `WorktreeCreate` | 是 | 任何非零退出码导致 worktree 创建失败 |

944| `WorktreeRemove` | 是 | 任何非零退出代码导致 worktree 移除失败（如果目录仍然存在）。请参阅 [WorktreeRemove](#worktreeremove) 了解目录发生什么 |944| `WorktreeRemove` | 是 | 任何非零退出码会在目录之后仍然存在时导致 worktree 移除失败。请参阅 [WorktreeRemove](#worktreeremove) 了解目录会发生什么 |

945| `InstructionsLoaded` | 否 | 退出代码被忽略 |945| `InstructionsLoaded` | 否 | 退出码被忽略 |

946| `MessageDisplay` | 否 | 显示原始文本 |946| `MessageDisplay` | 否 | 显示原始文本 |

947 947

948对于 `SessionStart`、`SubagentStart` 和 `PostModelSwitch`，Claude Code 在转录中呈现退出代码 2 stderr 作为 `<hook name> hook error` 通知，与呈现[非阻止错误](#exit-code-output)的方式相同。Claude 看不到它，会话或 subagent 继续。对于 `SubagentStart`，通知出现在 subagent 自己的转录中，而不是在父对话中。948对于 `SessionStart`、`SubagentStart` 和 `PostModelSwitch`，Claude Code 在会话记录中将退出码 2 的 stderr 呈现为 `<hook name> hook error` 通知，与呈现[非阻止错误](#exit-code-output)的方式相同。Claude 看不到它，会话或子代理继续。对于 `SubagentStart`，通知出现在子代理自己的会话记录中，而不是在父对话中。

949 949

950<h3 id="http-response-handling">950<h3 id="http-response-handling">

951 HTTP 响应处理951 HTTP 响应处理

952</h3>952</h3>

953 953

954HTTP hook 使用 HTTP 状态代码和响应体而不是退出代码和 stdout。下面的结果适用于大多数事件；在[每个事件表](#exit-code-2-behavior-per-event)中有自己的失败合约的事件（如 `WorktreeCreate`）将该合约应用于失败的 HTTP hook：954HTTP hook 使用 HTTP 状态码和响应体，而不是退出码和 stdout。下面的结果适用于大多数事件；在[每个事件表](#exit-code-2-behavior-per-event)中有自己失败约定的事件（如 `WorktreeCreate`）也会将该约定应用于失败的 HTTP hook：

955 955

956* **2xx 且空体**：成功，等同于退出代码 0 且无输出956* **2xx 且空响应体**：成功，等同于退出码 0 且无输出

957* **2xx 且 JSON 对象体**：使用与命令 hook 相同的 [JSON 输出](#json-output)架构解析。未通过架构验证的体是非阻止错误957* **2xx 且 JSON 对象响应体**：使用与命令 hook 相同的 [JSON 输出](#json-output) schema 解析。未通过 schema 验证的响应体是非阻止错误

958* **2xx 且任何其他体，如纯文本**：非阻止错误，处理方式与非 2xx 状态相同。Claude Code 不将文本添加到 Claude 的上下文958* **2xx 且任何其他响应体，如纯文本**：非阻止错误，处理方式与非 2xx 状态相同。Claude Code 不将文本添加到 Claude 的上下文

959* **非 2xx 状态**：非阻止错误，执行继续959* **非 2xx 状态**：非阻止错误，执行继续

960* **连接失败**：非阻止错误，执行继续960* **连接失败**：非阻止错误，执行继续

961* **超时**：hook 被取消，如 [Timeouts](#timeouts) 下所述961* **超时**：hook 被取消，如[超时](#timeouts)下所述

962 962

963与命令 hook 不同，HTTP hook 无法仅通过状态代码发出阻止错误信号。要阻止工具调用或拒绝权限，返回 2xx 响应，其 JSON 体包含适当的决策字段。963与命令 hook 不同，HTTP hook 无法仅通过状态码发出阻止错误信号。要阻止工具调用或拒绝权限，请返回 2xx 响应，其 JSON 响应体包含相应的决策字段。

964 964

965<h3 id="json-output">965<h3 id="json-output">

966 JSON 输出966 JSON 输出

967</h3>967</h3>

968 968

969退出代码只让您阻止或保持沉默，但 JSON 输出给您更细粒度的控制。与其退出代码 2 来阻止，不如退出 0 并将 JSON 对象打印到 stdout。Claude Code 从该 JSON 读取特定字段来控制行为，包括[决策控制](#decision-control)来阻止、允许或升级给用户。969退出码只能让您阻止或保持沉默，而 JSON 输出为您提供更细粒度的控制。与其以代码 2 退出来阻止，不如退出 0 并将 JSON 对象打印到 stdout。Claude Code 从该 JSON 读取特定字段来控制行为，包括用于阻止、允许或升级给用户的[决策控制](#decision-control)。

970 970

971<Note>971<Note>

972 每个 hook 选择一种方法：要么单独使用退出代码进行信号，要么退出 0 并打印 JSON 进行结构化控制。如果您混合它们，退出 2 保持其[阻止效果](#exit-code-2-behavior-per-event)，Claude Code 仍然读取 JSON 字段，除了 [Exit code 2](#exit-code-2) 下注明的一个引出例外。972 每个 hook 选择一种方法：要么仅使用退出码发出信号，要么退出 0 并打印 JSON 进行结构化控制。如果您混合使用，退出 2 保持其[阻止效果](#exit-code-2-behavior-per-event)，Claude Code 仍然读取 JSON 字段，但[退出码 2](#exit-code-2) 下注明的 elicitation 例外除外。

973</Note>973</Note>

974 974

975您的 hook 的 stdout 必须仅包含 JSON 对象。如果您的 shell 配置文件在启动时打印文本，它可能会干扰 JSON 解析。请参阅故障排除指南中的 [Hook JSON 无效](/docs/zh-CN/hooks-guide#hook-json-has-no-effect)。975您的 hook 的 stdout 必须仅包含 JSON 对象。如果您的 shell 配置文件在启动时打印文本，它可能会干扰 JSON 解析。请参阅故障排除指南中的 [Hook JSON 无效](/docs/zh-CN/hooks-guide#hook-json-has-no-effect)。

977hook 的 `additionalContext`、`systemMessage` 和 `initialUserMessage` 字符串，以及其纯 stdout，限制为 10,000 个字符：977hook 的 `additionalContext`、`systemMessage` 和 `initialUserMessage` 字符串，以及其纯 stdout，限制为 10,000 个字符：

978 978

979* **范围**：Claude Code 单独测量每个字符串，即使多个 hook 为同一事件运行。对于 JSON 输出，每个字段单独测量；纯 stdout 整体测量。979* **范围**：Claude Code 单独测量每个字符串，即使多个 hook 为同一事件运行。对于 JSON 输出，每个字段单独测量；纯 stdout 整体测量。

980* **超过限制**：Claude Code 将输出保存到会话目录中的文件，并用文件路径和最多前 2,000 个字符的预览替换它。大型有效 Bash 结果的处理方式相同，在 [Output limits](/docs/zh-CN/tools-reference#output-limits) 下描述。与该 Bash 上限不同，此上限没有设置或环境变量来提高它。980* **超过限制**：Claude Code 将输出保存到会话目录中的文件，并用文件路径和最多前 2,000 个字符的预览替换它。大型有效 Bash 结果的处理方式相同，在[输出限制](/docs/zh-CN/tools-reference#output-limits)下描述。与该 Bash 上限不同，此上限没有可提高它的设置或环境变量。

981* **读取文件**：Claude Code 不要求 Claude 读取文件，因此将 Claude 必须始终看到的任何内容保持在上限内。981* **读取文件**：Claude Code 不要求 Claude 读取文件，因此请将 Claude 必须始终看到的任何内容保持在上限内。

982 982

983JSON 对象支持三种字段：983JSON 对象支持三种字段：

984 984

985* **通用字段**如 `continue` 在下表中列出。每个事件都接受它们，但某些事件丢弃它们或将 `systemMessage` 传递到转录以外的地方。每个事件的部分说明这一点。`terminalSequence` 也在这些事件上工作，除了 [Emit terminal notifications](#emit-terminal-notifications) 下列出的例外。985* **通用字段**如 `continue` 在下表中列出。每个事件都接受它们，但某些事件会丢弃它们或将 `systemMessage` 传递到会话记录以外的地方。每个事件的部分会说明这一点。`terminalSequence` 也在这些事件上工作，但[发出终端通知](#emit-terminal-notifications)下列出的例外除外。

986* **顶级 `decision` 和 `reason`** 由某些事件用来阻止或提供反馈。986* **顶级 `decision` 和 `reason`** 由某些事件用来阻止或提供反馈。

987* **`hookSpecificOutput`** 是需要更丰富控制的事件的嵌套对象。它需要一个 `hookEventName` 字段设置为事件名称。987* **`hookSpecificOutput`** 是用于需要更丰富控制的事件的嵌套对象。它需要一个设置为事件名称的 `hookEventName` 字段。

988 988

989| 字段 | 默认 | 描述 |989| 字段 | 默认 | 描述 |

990| :- | :- | :- |990| :- | :- | :- |

992| `stopReason` | 无 | 当 `continue` 为 `false` 时向用户显示的消息。它保留在对话中，因此如果对话继续，Claude 会看到它 |992| `stopReason` | 无 | 当 `continue` 为 `false` 时向用户显示的消息。它保留在对话中，因此如果对话继续，Claude 会看到它 |

994| `systemMessage` | 无 | 向用户显示的警告消息。在 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 和 [`--output-format stream-json`](/docs/zh-CN/headless) 输出中，它可以作为 [`SDKInformationalMessage`](/docs/zh-CN/agent-sdk/typescript#sdkinformationalmessage) 到达 |994| `systemMessage` | 无 | 向用户显示的警告消息。在 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 和 [`--output-format stream-json`](/docs/zh-CN/headless) 输出中，它可以作为 [`SDKInformationalMessage`](/docs/zh-CN/agent-sdk/typescript#sdkinformationalmessage) 到达 |

995| `terminalSequence` | 无 | Claude Code 代表您发出的终端转义序列，如桌面通知、窗口标题或响铃。限制为 OSC `0`/`1`/`2`/`9`/`99`/`777` 和 BEL。如果值包含允许列表外的任何内容，字段被忽略。使用此而不是写入 `/dev/tty`，这对 hook 不可用 |995| `terminalSequence` | 无 | Claude Code 代表您发出的终端转义序列，如桌面通知、窗口标题或响铃。限制为 OSC `0`/`1`/`2`/`9`/`99`/`777` 和 BEL。如果值包含允许列表之外的任何内容，该字段被忽略。请使用此字段而不是写入 `/dev/tty`，后者对 hook 不可用 |

996 996

997要完全停止 Claude：997要完全停止 Claude：

998 998

1000{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }1000{ "continue": false, "stopReason": "Build failed, fix errors before continuing" }

1001```1001```

1002 1002

1003对于 `PreToolUse` 和 `PostToolUse` hook，停止适用，即使工具调用失败或在 Claude 仍在流式传输响应时完成。1003对于 `PreToolUse` 和 `PostToolUse` hook，即使工具调用在 Claude 仍在流式输出回复时失败或完成，停止也同样适用。

1004 1004

1005<h4 id="emit-terminal-notifications">1005<h4 id="emit-terminal-notifications">

1006 发出终端通知1006 发出终端通知

1007</h4>1007</h4>

1008 1008

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

1010 1010

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

1012 1012

1013* OSC `0`、`1`、`2`：窗口和图标标题1013* OSC `0`、`1`、`2`：窗口和图标标题

1014* OSC `9`：iTerm2、ConEmu、Windows Terminal 和 WezTerm 通知，包括 `9;4` 任务栏进度1014* OSC `9`：iTerm2、ConEmu、Windows Terminal 和 WezTerm 通知，包括 `9;4` 任务栏进度

1015* OSC `99`：Kitty 通知1015* OSC `99`：Kitty 通知

1016* OSC `777`：urxvt、Ghostty 和 Warp 通知1016* OSC `777`：urxvt、Ghostty 和 Warp 通知

1017* 裸 BEL1017* 单独的 BEL

1018 1018

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

1020 1020

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

1022 1022

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

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

1025 1025

1026下面的示例从 `Notification` hook 触发桌面通知。转义序列用 `printf` 八进制转义构建，因此控制字节从不出现在 shell 命令行上，`jq -n --arg` 构建 JSON 输出，因此通知消息中的引号、反斜杠和换行符被正确转义：1026下面的示例从 `Notification` hook 触发桌面通知。转义序列使用 `printf` 八进制转义构建，因此控制字节从不出现在 shell 命令行上，`jq -n --arg` 构建 JSON 输出，因此通知消息中的引号、反斜杠和换行符会被正确转义：

1027 1027

1028```bash theme={null}1028```bash theme={null}

1029#!/bin/bash1029#!/bin/bash

1035jq -nc --arg seq "$seq" '{terminalSequence: $seq}'1035jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

1036```1036```

1037 1037

1038`{ "terminalSequence": "..." }` 形状从任何 shell 或语言都相同。1038`{ "terminalSequence": "..." }` 的结构在任何 shell 或语言中都相同。

1039 1039

1040<h4 id="add-context-for-claude">1040<h4 id="add-context-for-claude">

1041 为 Claude 添加上下文1041 为 Claude 添加上下文

1042</h4>1042</h4>

1043 1043

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

1045 1045

1046在 `hookSpecificOutput` 中返回 `additionalContext` 以及事件名称：1046在 `hookSpecificOutput` 中将 `additionalContext` 与事件名称一起返回：

1047 1047

1048```json theme={null}1048```json theme={null}

1049{1049{

1056 1056

1057提醒出现的位置取决于事件：1057提醒出现的位置取决于事件：

1058 1058

1059* [SessionStart](#sessionstart) 和 [SubagentStart](#subagentstart)：在对话开始，在第一个提示之前1059* [SessionStart](#sessionstart) 和 [SubagentStart](#subagentstart)：在对话开始处，第一个提示词之前

1060* [UserPromptSubmit](#userpromptsubmit) 和 [UserPromptExpansion](#userpromptexpansion)：与提交的提示一起1060* [UserPromptSubmit](#userpromptsubmit) 和 [UserPromptExpansion](#userpromptexpansion)：与提交的提示词一起

1061* [PreToolUse](#pretooluse)、[PostToolUse](#posttooluse)、[PostToolUseFailure](#posttoolusefailure) 和 [PostToolBatch](#posttoolbatch)：在工具结果旁边1061* [PreToolUse](#pretooluse)、[PostToolUse](#posttooluse)、[PostToolUseFailure](#posttoolusefailure) 和 [PostToolBatch](#posttoolbatch)：在工具结果旁边

1062* [Stop](#stop) 和 [SubagentStop](#subagentstop)：在轮次末尾。对话继续，因此 Claude 可以对反馈采取行动。请参阅 [Stop decision control](#stop-decision-control)1062* [Stop](#stop) 和 [SubagentStop](#subagentstop)：在轮次末尾。对话继续，因此 Claude 可以根据反馈采取行动。请参阅 [Stop 决策控制](#stop-decision-control)

1063* [PostModelSwitch](#postmodelswitch)：与切换后的下一个请求一起。请参阅 [PostModelSwitch decision control](#postmodelswitch-decision-control) 了解时间1063* [PostModelSwitch](#postmodelswitch)：与切换后的下一个请求一起。请参阅 [PostModelSwitch 决策控制](#postmodelswitch-decision-control)了解时机

1064 1064

1065当多个 hook 为同一事件返回 `additionalContext` 时，Claude 接收所有值。1065当多个 hook 为同一事件返回 `additionalContext` 时，Claude 会接收所有值。

1066 1066

1067如果值超过 10,000 个字符，Claude Code 将文本写入会话目录中的文件，并改为传递 Claude 文件路径，带有最多前 2,000 个字符的预览。Claude 可以读取文件，但 Claude Code 不要求它。1067如果值超过 10,000 个字符，Claude Code 会将文本写入会话目录中的文件，并改为向 Claude 传递文件路径以及最多前 2,000 个字符的预览。Claude 可以读取该文件，但 Claude Code 不会要求它读取。

1068 1068

1069使用 `additionalContext` 获取 Claude 应该知道的关于您的环境当前状态或刚刚运行的操作的信息：1069使用 `additionalContext` 提供 Claude 应了解的有关您环境当前状态或刚刚运行的操作的信息：

1070 1070

1071* **环境状态**：当前分支、部署目标或活跃功能标志1071* **环境状态**：当前分支、部署目标或活跃的功能标志

1072* **条件项目规则**：哪个测试命令适用于刚编辑的文件，哪些目录在此 worktree 中是只读的1072* **条件项目规则**：哪个测试命令适用于刚编辑的文件，哪些目录在此 worktree 中是只读的

1073* **外部数据**：分配给您的开放问题、最近的 CI 结果、从内部服务获取的内容1073* **外部数据**：分配给您的未解决问题、最近的 CI 结果、从内部服务获取的内容

1074 1074

1075对于从不改变的说明，更喜欢 [CLAUDE.md](/docs/zh-CN/memory)。它加载而不运行脚本，是静态项目约定的标准位置。1075对于从不改变的指令，首选 [CLAUDE.md](/docs/zh-CN/memory)。它无需运行脚本即可加载，是存放静态项目约定的标准位置。

1076 1076

1077将文本写成事实陈述而不是命令式系统说明。措辞如"部署目标是生产"或"此 repo 使用 `bun test`"读作项目信息。框架为带外系统命令的文本可以触发 Claude 的提示注入防御，这导致 Claude 向您显示文本而不是将其视为上下文。1077将文本写成事实陈述，而不是命令式的系统指令。诸如"部署目标是生产环境"或"此 repo 使用 `bun test`"之类的措辞会被视为项目信息。以带外系统命令形式表述的文本可能会触发 Claude 的提示词注入防御，导致 Claude 将文本展示给您，而不是将其视为上下文。

1078 1078

1079Claude Code 在会话转录中保存注入的文本。对于 `PostToolUse` 或 `UserPromptSubmit` 等中期会话事件，当您使用 `--continue` 或 `--resume` 恢复时，Claude Code 重放保存的文本而不是为过去的轮次重新运行 hook，因此时间戳或提交 SHA 等值变得陈旧。`SessionStart` hook 在使用 `source` 设置为 `"resume"` 或 `"fork"`（如果您添加了 `--fork-session`）恢复时再次运行，因此它们可以刷新其上下文。1079Claude Code 在会话记录中保存注入的文本。对于 `PostToolUse` 或 `UserPromptSubmit` 等会话中途的事件，当您使用 `--continue` 或 `--resume` 恢复时，Claude Code 会重放保存的文本，而不是为过去的轮次重新运行 hook，因此时间戳或提交 SHA 等值会变得过时。`SessionStart` hook 在恢复时会再次运行，此时 `source` 设置为 `"resume"`，如果您添加了 `--fork-session` 则为 `"fork"`，因此它们可以刷新其上下文。

1080 1080

1081<h4 id="decision-control">1081<h4 id="decision-control">

1082 决策控制1082 决策控制

1083</h4>1083</h4>

1084 1084

1085并非每个事件都支持通过 JSON 阻止或控制行为。支持的事件各自使用不同的字段集来表达该决策。在编写 hook 之前，使用此表作为快速参考：1085并非每个事件都支持通过 JSON 阻止或控制行为。支持的事件各自使用不同的字段集来表达该决策。在编写 hook 之前，请将此表用作快速参考：

1086 1086

1087| 事件 | 决策模式 | 关键字段 |1087| 事件 | 决策模式 | 关键字段 |

1088| :- | :- | :- |1088| :- | :- | :- |

1089| UserPromptSubmit、UserPromptExpansion、PostToolUse、PostToolUseFailure、PostToolBatch、Stop、SubagentStop、ConfigChange、PreCompact | 顶级 `decision` | `decision: "block"`、`reason`。Stop 和 SubagentStop 也接受 `hookSpecificOutput.additionalContext` 用于[继续对话的非错误反馈](#stop-decision-control) |1089| UserPromptSubmit、UserPromptExpansion、PostToolUse、PostToolUseFailure、PostToolBatch、Stop、SubagentStop、ConfigChange、PreCompact | 顶级 `decision` | `decision: "block"`、`reason`。Stop 和 SubagentStop 也接受 `hookSpecificOutput.additionalContext` 用于[继续对话的非错误反馈](#stop-decision-control) |

1090| TeammateIdle、TaskCompleted | 退出代码或 `continue: false` | 退出代码 2 用 stderr 反馈阻止操作。JSON `{"continue": false, "stopReason": "..."}` 也完全停止队友，匹配 `Stop` hook 行为；[TaskCompleted 在 `TaskUpdate` 工具触发事件时忽略它](#taskcompleted-decision-control) |1090| TeammateIdle、TaskCompleted | 退出码或 `continue: false` | 退出码 2 阻止操作并提供 stderr 反馈。JSON `{"continue": false, "stopReason": "..."}` 也会完全停止队友，与 `Stop` hook 行为一致；[当 `TaskUpdate` 工具触发该事件时，TaskCompleted 会忽略它](#taskcompleted-decision-control) |

1093| PreModelSwitch | `hookSpecificOutput` 或顶级 `decision` | `permissionDecision`（allow/deny/ask）、`permissionDecisionReason`。`decision: "block"` 也[取消切换](#premodelswitch-decision-control) |1093| PreModelSwitch | `hookSpecificOutput` 或顶级 `decision` | `permissionDecision`（allow/deny/ask）、`permissionDecisionReason`。`decision: "block"` 也会[取消切换](#premodelswitch-decision-control) |

1097| WorktreeRemove | 退出代码 | 任何非零退出代码使移除失败（如果目录仍然存在）。JSON 输出被丢弃 |1097| WorktreeRemove | 退出码 | 任何非零退出码会在目录之后仍然存在时使移除失败。JSON 输出被丢弃 |

1100| MessageDisplay | `hookSpecificOutput` | `displayContent` 替换屏幕上显示的文本。仅显示：转录和 Claude 看到的保持原始 |

1101| SessionStart、SubagentStart、PostModelSwitch | 仅上下文 | `hookSpecificOutput.additionalContext` 为 Claude 添加上下文。SessionStart 也接受 [`initialUserMessage`、`watchPaths`、`sessionTitle` 和 `reloadSkills`](#sessionstart-decision-control)。无阻止或决策控制 |1100| SessionStart、SubagentStart、PostModelSwitch | 仅上下文 | `hookSpecificOutput.additionalContext` 为 Claude 添加上下文。SessionStart 也接受 [`initialUserMessage`、`watchPaths`、`sessionTitle` 和 `reloadSkills`](#sessionstart-decision-control)。无阻止或决策控制 |

1102| Setup、Notification、SessionEnd、PostCompact、InstructionsLoaded、StopFailure、CwdChanged、DirectoryAdded、FileChanged | 无 | 无决策控制。用于日志或清理等副作用 |1101| Setup、Notification、SessionEnd、PostCompact、InstructionsLoaded、StopFailure、CwdChanged、DirectoryAdded、FileChanged | 无 | 无决策控制。用于记录日志或清理等副作用 |

1103 1102

1104少数事件也可以重写内容而不仅仅允许或阻止它：1103少数事件还可以改写内容，而不仅仅是允许或阻止：

1105 1104

1106* `PreToolUse`：`updatedInput` 直接在 `hookSpecificOutput` 下替换工具的参数，然后它运行。请参阅 [PreToolUse decision control](#pretooluse-decision-control)1105* `PreToolUse`：直接位于 `hookSpecificOutput` 下的 `updatedInput` 会在工具运行前替换其参数。请参阅 [PreToolUse 决策控制](#pretooluse-decision-control)

1107* `PermissionRequest`：`updatedInput` 在 `decision` 对象内。请参阅 [PermissionRequest decision control](#permissionrequest-decision-control)1106* `PermissionRequest`：`updatedInput` 位于 `decision` 对象内。请参阅 [PermissionRequest 决策控制](#permissionrequest-decision-control)

1108* `PostToolUse`：`updatedToolOutput` 替换工具的结果。请参阅 [PostToolUse decision control](#posttooluse-decision-control)1107* `PostToolUse`：`updatedToolOutput` 替换工具的结果。请参阅 [PostToolUse 决策控制](#posttooluse-decision-control)

1109* `UserPromptSubmit`：无法替换提示；它仅在其旁边注入 `additionalContext`1108* `UserPromptSubmit`：无法替换提示词；它仅在其旁边注入 `additionalContext`

1110 1109

1111对于编辑或转换用例，在 `PreToolUse` 处拦截出站工具输入，在 `PostToolUse` 处拦截入站工具结果。1110对于脱敏或转换用例，请在 `PreToolUse` 处拦截出站工具输入，在 `PostToolUse` 处拦截入站工具结果。

1112 1111

1113以下是每种模式的实际示例：1112以下是每种模式的实际示例：

1114 1113

1115<Tabs>1114<Tabs>

1116 <Tab title="顶级 decision">1115 <Tab title="顶级 decision">

1117 `decision` 的唯一值是 `"block"`。要允许操作继续，从您的 JSON 中省略 `decision`，或退出 0 而不带任何 JSON：1116 `decision` 的唯一值是 `"block"`。要允许操作继续，请从您的 JSON 中省略 `decision`，或退出 0 且不输出任何 JSON：

1118 1117

1119 ```json theme={null}1118 ```json theme={null}

1120 {1119 {

1125 </Tab>1124 </Tab>

1126 1125

1127 <Tab title="PreToolUse">1126 <Tab title="PreToolUse">

1128 使用 `hookSpecificOutput` 进行更丰富的控制：允许、拒绝或升级给用户。您也可以在运行前修改工具输入或为 Claude 注入额外上下文。请参阅 [PreToolUse decision control](#pretooluse-decision-control) 了解完整的选项集。1127 使用 `hookSpecificOutput` 进行更丰富的控制：允许、拒绝或升级给用户。您也可以在工具运行前修改工具输入，或为 Claude 注入额外上下文。请参阅 [PreToolUse 决策控制](#pretooluse-decision-control)了解完整的选项集。

1129 1128

1130 ```json theme={null}1129 ```json theme={null}

1131 {1130 {

1139 </Tab>1138 </Tab>

1140 1139

1141 <Tab title="PermissionRequest">1140 <Tab title="PermissionRequest">

1142 使用 `hookSpecificOutput` 代表用户允许或拒绝权限请求。允许时，您也可以修改工具的输入或应用权限规则，以便用户不会再次被提示。请参阅 [PermissionRequest decision control](#permissionrequest-decision-control) 了解完整的选项集。1141 使用 `hookSpecificOutput` 代表用户允许或拒绝权限请求。允许时，您也可以修改工具的输入或应用权限规则，使用户不会再次被询问。请参阅 [PermissionRequest 决策控制](#permissionrequest-decision-control)了解完整的选项集。

1143 1142

1144 ```json theme={null}1143 ```json theme={null}

1145 {1144 {

1157 </Tab>1156 </Tab>

1158</Tabs>1157</Tabs>

1159 1158

1160有关扩展示例，包括 Bash 命令验证、提示过滤和自动批准脚本，请参阅指南中的 [What you can automate](/docs/zh-CN/hooks-guide#what-you-can-automate) 和 [Bash command validator reference implementation](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)。1159有关扩展示例，包括 Bash 命令验证、提示词过滤和自动批准脚本，请参阅指南中的[您可以自动化什么](/docs/zh-CN/hooks-guide#what-you-can-automate)和 [Bash 命令验证器参考实现](https://github.com/anthropics/claude-code/blob/main/examples/hooks/bash_command_validator_example.py)。

1161 1160

1162<h2 id="hook-events">1161<h2 id="hook-events">

1163 Hook 事件1162 Hook 事件

1164</h2>1163</h2>

1165 1164

1166每个事件都对应 Claude Code 生命周期中可以运行 hook 的一个时间点。以下各节按照生命周期的顺序排列：从会话设置开始，经过智能体循环，直到会话结束。每一节都会说明事件何时触发、支持哪些匹配器、接收什么 JSON 输入，以及如何通过输出控制行为。1165每个事件都对应 Claude Code 生命周期中可以运行 hook 的一个时间点。以下各节按照生命周期的顺序排列：从会话设置，到智能体循环，再到会话结束。每一节都会说明事件何时触发、支持哪些匹配器、接收的 JSON 输入，以及如何通过输出控制行为。

1167 1166

1168<h3 id="sessionstart">1167<h3 id="sessionstart">

1169 SessionStart1168 SessionStart

1170</h3>1169</h3>

1171 1170

1172在 Claude Code 启动新会话或恢复现有会话时运行。适用于加载开发上下文（例如现有 issue 或代码库的最近更改），或设置环境变量。对于不需要脚本的静态上下文，请改用 [CLAUDE.md](/docs/zh-CN/memory)。1171在 Claude Code 启动新会话或恢复现有会话时运行。适用于加载开发上下文（例如现有问题或代码库的最近更改），或设置环境变量。对于不需要脚本的静态上下文，请改用 [CLAUDE.md](/docs/zh-CN/memory)。

1173 1172

1174SessionStart 在每个会话中都会运行，因此请保持这些 hook 快速执行。仅支持 `type: "command"` 和 `type: "mcp_tool"` hook。有关 `mcp_tool` hook 何时运行，请参阅 [MCP 工具 hook 字段](#mcp-tool-hook-fields)。1173SessionStart 在每个会话中都会运行，因此请确保这些 hook 运行迅速。仅支持 `type: "command"` 和 `type: "mcp_tool"` hook。关于 `mcp_tool` hook 何时运行，请参阅 [MCP 工具 hook 字段](#mcp-tool-hook-fields)。

1175 1174

1176匹配器值对应于会话的启动方式：1175匹配器的值对应会话的启动方式：

1177 1176

1178| 匹配器 | 触发时机 |1177| 匹配器 | 触发时机 |

1179| :- | :- |1178| :- | :- |

1185 1184

1186在 v2.1.214 之前，分叉的会话报告的 source 为 `"resume"`。1185在 v2.1.214 之前，分叉的会话报告的 source 为 `"resume"`。

1187 1186

1188当您启动交互式会话、在启动时使用 `--continue` 或 `--resume` 恢复对话，或运行 `/clear` 时，SessionStart hook 会在后台运行。您可以立即输入，恢复的对话也会直接显示，无需等待 hook。Claude 的第一条回复仍会等待 hook 完成，以便其上下文能够传递给 Claude。1187当您启动交互式会话、在启动时使用 `--continue` 或 `--resume` 恢复对话，或运行 `/clear` 时，SessionStart hook 会在后台运行。您可以立即开始输入，恢复的对话也会直接显示，无需等待 hook。Claude 的第一次回复仍会等待 hook 完成，以便其上下文能传达给 Claude。

1189 1188

1190当您在会话中使用 `/resume` 切换对话时，切换操作则会等待 hook 完成。如果您在后台 hook 仍在运行时运行 `/clear` 或切换到其他对话，它们返回的任何内容都不会应用于该会话。1189当您在会话内使用 `/resume` 切换对话时，切换操作则会等待 hook 完成。如果您在后台 hook 仍在运行时运行 `/clear` 或切换到另一个对话，它们返回的任何内容都不会应用到该会话。

1191 1190

1192启动时也存在同样的等待，包括恢复的会话：在 SessionStart hook 仍在运行时发送的提示词，要等到它们完成后才会传递给 Claude。1191启动时（包括恢复的会话）也存在同样的等待：在 SessionStart hook 仍在运行时发送的提示词，要等它们完成后才会传达给 Claude。

1193 1192

1194在上述任一等待期间，按 `Esc` 可将提示词收回到输入框中而不发送。hook 会继续运行。1193在任一种等待期间，按 `Esc` 可将提示词收回输入框而不发送。hook 会继续运行。

1195 1194

1196<h4 id="sessionstart-input">1195<h4 id="sessionstart-input">

1197 SessionStart 输入1196 SessionStart 输入

1198</h4>1197</h4>

1199 1198

1200除了[通用输入字段](#common-input-fields)之外，SessionStart hook 还会接收 `source`，以及可选的 `model`、`agent_type` 和 `session_title`：1199除[通用输入字段](#common-input-fields)外，SessionStart hook 还会接收 `source`，以及可选的 `model`、`agent_type` 和 `session_title`：

1201 1200

1202| 字段 | 描述 |1201| 字段 | 描述 |

1203| :- | :- |1202| :- | :- |

1207| `session_title` | 会话的自定义标题，在已设置时出现，例如通过 `--name`、`/rename`、hook 的 `sessionTitle` 输出或 Agent SDK 的 `renameSession()` 设置。输出 `sessionTitle` 的 hook 可以先检查此字段，以避免覆盖现有的自定义标题 |1206| `session_title` | 会话的自定义标题，在已设置时存在，例如通过 `--name`、`/rename`、hook 的 `sessionTitle` 输出或 Agent SDK 的 `renameSession()` 设置。输出 `sessionTitle` 的 hook 可以先检查此字段，以避免覆盖现有的自定义标题 |

1208 1207

1209您未命名的会话仍可能拥有[自动生成的标题](/docs/zh-CN/sessions#name-your-sessions)。该标题不是自定义标题，不会出现在 `session_title` 中。1208未命名的会话仍可能有一个[自动生成的标题](/docs/zh-CN/sessions#name-your-sessions)。该标题不是自定义标题，不会出现在 `session_title` 中。

1210 1209

1211当 `source` 为 `"resume"` 或 `"fork"`，且会话记录中至少包含一条 Claude 的回复时，SessionStart hook 还会接收以下四个字段。您的 hook 可以使用它们在第一个请求之前报告恢复一个陈旧对话的成本，例如通过 [`systemMessage`](#json-output)。这些字段需要 Claude Code v2.1.251 或更高版本。1210当 `source` 为 `"resume"` 或 `"fork"`，且会话记录中至少包含一条 Claude 的回复时，SessionStart hook 还会接收下面四个字段。您的 hook 可以利用它们在第一个请求之前报告恢复一个陈旧对话的成本，例如通过 [`systemMessage`](#json-output)。这些字段需要 Claude Code v2.1.251 或更高版本。

1212 1211

1213| 字段 | 描述 |1212| 字段 | 描述 |

1214| :- | :- |1213| :- | :- |

1217| `prompt_cache_likely_expired` | 当最后一条回复早于会话的[提示缓存生命周期](/docs/zh-CN/prompt-caching#cache-lifetime)，或之后的压缩替换了已缓存的对话时为 `true` |1216| `prompt_cache_likely_expired` | 当最后一条回复早于会话的[提示缓存有效期](/docs/zh-CN/prompt-caching#cache-lifetime)，或之后的压缩替换了已缓存的对话时为 `true` |

1219 1218

1220以下示例展示了在最后一条回复 90 分钟后恢复的会话的输入：1219此示例展示了一个在最后一条回复 90 分钟后恢复的会话的输入：

1221 1220

1222```json theme={null}1221```json theme={null}

1223{1222{

1238 SessionStart 决策控制1237 SessionStart 决策控制

1239</h4>1238</h4>

1240 1239

1241Claude Code 会将其[视为纯文本](#exit-code-0)的 stdout 添加到 Claude 的上下文中。除了所有 hook 都可用的 [JSON 输出字段](#json-output)之外，您还可以返回以下特定于事件的字段：1240Claude Code 会将其[视为纯文本](#exit-code-0)的 stdout 添加到 Claude 的上下文中。除所有 hook 都可用的 [JSON 输出字段](#json-output)外，您还可以返回以下事件专属字段：

1242 1241

1243| 字段 | 描述 |1242| 字段 | 描述 |

1244| :- | :- |1243| :- | :- |

1245| `additionalContext` | 在对话开始时、第一个提示词之前添加到 Claude 上下文中的字符串。有关文本的传递方式以及应放入的内容，请参阅[为 Claude 添加上下文](#add-context-for-claude) |1244| `additionalContext` | 在对话开始时、第一个提示词之前添加到 Claude 上下文中的字符串。关于文本的传递方式以及应放入的内容，请参阅[为 Claude 添加上下文](#add-context-for-claude) |

1246| `initialUserMessage` | 用作会话第一条用户消息的字符串。适用于使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless)，此时即使未提供提示词，它也会成为第一轮。如果提供了提示词，则提示词作为下一轮紧随其后。与附加到现有轮次的 `additionalContext` 不同，此字段会创建轮次 |1245| `initialUserMessage` | 用作会话第一条用户消息的字符串。适用于使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless)，此时即使未提供提示词，它也会成为第一个轮次。如果提供了提示词，该提示词将作为下一个轮次跟随其后。与附加到现有轮次的 `additionalContext` 不同，此字段会创建轮次 |

1247| `sessionTitle` | 设置会话标题，效果与 `/rename` 相同。可用于根据启动文件夹、git 分支或 worktree 名称自动命名会话。在 `source` 为 `"startup"`、`"resume"` 或 `"fork"` 时生效；在 `"clear"` 和 `"compact"` 时被忽略 |1246| `sessionTitle` | 设置会话标题，效果与 `/rename` 相同。可用于根据启动文件夹、git 分支或 worktree 名称自动命名会话。当 `source` 为 `"startup"`、`"resume"` 或 `"fork"` 时生效；在 `"clear"` 和 `"compact"` 时被忽略 |

1249| `reloadSkills` | 布尔值。为 `true` 时，Claude Code 会在 SessionStart hook 完成后重新扫描 [skill](/docs/zh-CN/skills) 和命令目录，使 hook 安装的 skill 在同一会话中从第一个提示词开始即可使用 |1248| `reloadSkills` | 布尔值。为 `true` 时，Claude Code 会在 SessionStart hook 完成后重新扫描 [skill](/docs/zh-CN/skills) 和命令目录，使 hook 安装的 skill 在同一会话中（从第一个提示词开始）即可使用 |

1250 1249

1251```json theme={null}1250```json theme={null}

1252{1251{

1258}1257}

1259```1258```

1260 1259

1261由于对于此事件，纯 stdout 已经会传递给 Claude，因此仅加载上下文的 hook 可以直接打印到 stdout，无需构建 JSON。当您需要将上下文与 `sessionTitle` 等其他字段组合时，请使用 JSON 形式。1260由于对于此事件，纯 stdout 已经会传达给 Claude，因此仅加载上下文的 hook 可以直接打印到 stdout，而无需构建 JSON。当您需要将上下文与 `sessionTitle` 等其他字段结合使用时，请使用 JSON 形式。

1262 1261

1263当 SessionStart hook 安装或更新 skill 时，请使用 `reloadSkills`。skill 发现通常在 SessionStart hook 完成之前运行，因此 hook 写入 `~/.claude/skills/` 或 `.claude/skills/` 的文件原本只会在下一个会话中出现。以下示例同步一个共享的 skill 仓库并请求重新扫描：1262当 SessionStart hook 安装或更新 skill 时，请使用 `reloadSkills`。skill 发现通常在 SessionStart hook 完成之前运行，因此 hook 写入 `~/.claude/skills/` 或 `.claude/skills/` 的文件否则只会在下一个会话中出现。此示例同步一个共享的 skill 仓库并请求重新扫描：

1264 1263

1265```bash theme={null}1264```bash theme={null}

1266#!/bin/bash1265#!/bin/bash

1271echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'1270echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "reloadSkills": true}}'

1272```1271```

1273 1272

1274该仓库 URL 是一个占位符；请将其替换为您自己的 skill 仓库。使用占位符时，克隆会失败并向 stderr 打印一条 `fatal:` 消息。以 0 退出的 SessionStart hook 的 stderr 仅供参考，因此 `reloadSkills` 请求仍然生效。1273仓库 URL 只是一个占位符；请将其替换为您自己的 skill 仓库。使用占位符时，clone 会失败并向 stderr 打印一条 `fatal:` 消息。以 0 退出的 SessionStart hook 的 stderr 仅供参考，因此 `reloadSkills` 请求仍然有效。

1275 1274

1276<h4 id="persist-environment-variables">1275<h4 id="persist-environment-variables">

1277 持久化环境变量1276 持久化环境变量

1278</h4>1277</h4>

1279 1278

1280SessionStart hook 可以访问 `CLAUDE_ENV_FILE` 环境变量，该变量提供一个文件路径，您可以在其中为后续的 Bash 命令持久化环境变量。1279SessionStart hook 可以访问 `CLAUDE_ENV_FILE` 环境变量，该变量提供一个文件路径，您可以在其中持久化环境变量，供后续 Bash 命令使用。

1281 1280

1282要设置单个环境变量，请将 `export` 语句写入 `CLAUDE_ENV_FILE`。使用追加（`>>`）以保留其他 hook 设置的变量：1281要设置单个环境变量，请将 `export` 语句写入 `CLAUDE_ENV_FILE`。使用追加（`>>`）以保留其他 hook 设置的变量：

1283 1282

1293exit 01292exit 0

1294```1293```

1295 1294

1296要捕获设置命令产生的所有环境更改，请比较执行前后导出的变量：1295要捕获设置命令带来的所有环境更改，请比较执行前后导出的变量：

1297 1296

1298```bash theme={null}1297```bash theme={null}

1299#!/bin/bash1298#!/bin/bash

1313```1312```

1314 1313

1315<Note>1314<Note>

1316 `CLAUDE_ENV_FILE` 可用于 SessionStart、[Setup](#setup)、[CwdChanged](#cwdchanged) 和 [FileChanged](#filechanged) hook。其他类型的 hook 无法访问此变量。1315 `CLAUDE_ENV_FILE` 可用于 SessionStart、[Setup](#setup)、[CwdChanged](#cwdchanged) 和 [FileChanged](#filechanged) hook。其他 hook 类型无法访问此变量。

1317</Note>1316</Note>

1318 1317

1319<h3 id="setup">1318<h3 id="setup">

1320 Setup1319 Setup

1321</h3>1320</h3>

1322 1321

1323仅在您使用 `--init-only` 启动 Claude Code，或在使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless)下使用 `--init` 或 `--maintenance` 启动时触发。正常启动时不会触发。可将其用于从 CI 或脚本中显式触发的一次性依赖安装或定期清理，与正常的会话启动分开。对于每个会话的初始化，请改用 [SessionStart](#sessionstart)。1322仅当您使用 `--init-only` 启动 Claude Code，或在使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless)中使用 `--init` 或 `--maintenance` 启动时才会触发。正常启动时不会触发。可将其用于您从 CI 或脚本中显式触发的一次性依赖安装或定期清理，与正常的会话启动分开。对于每个会话的初始化，请改用 [SessionStart](#sessionstart)。

1324 1323

1325匹配器值对应于触发该 hook 的 CLI 标志：1324匹配器的值对应触发该 hook 的 CLI 标志：

1326 1325

1327| 匹配器 | 触发时机 |1326| 匹配器 | 触发时机 |

1328| :- | :- |1327| :- | :- |

1331 1330

1332当您运行 `claude --init-only` 时，Claude Code 会运行 Setup hook 以及带有 `startup` 匹配器的 `SessionStart` hook，然后退出，不会开始对话。1331当您运行 `claude --init-only` 时，Claude Code 会运行 Setup hook 和带有 `startup` 匹配器的 `SessionStart` hook，然后在不开始对话的情况下退出。

1333 1332

1334当您使用 `-p` 开始或继续对话时，还需要提供提示词，可以作为参数提供，也可以通过 stdin 管道传入。当 `SessionStart` hook 提供了 [`initialUserMessage`](#sessionstart-decision-control)，或者您恢复带有[延迟工具调用](#defer-a-tool-call-for-later)的会话时，可以省略提示词。1333当您使用 `-p` 开始或继续对话时，还需要提供一个提示词，作为参数或通过 stdin 管道传入。当 `SessionStart` hook 提供了 [`initialUserMessage`](#sessionstart-decision-control)，或者您恢复一个带有[推迟的工具调用](#defer-a-tool-call-for-later)的会话时，可以省略提示词。

1335 1334

1336成功时，`--init-only` 不会向终端打印任何内容。要确认 hook 已运行，请使用 `claude --debug-file <path> --init-only` 启动，将 `<path>` 替换为日志文件位置，然后在日志中检查 Setup 和 SessionStart hook 条目。1335成功时，`--init-only` 不会向终端打印任何内容。要确认 hook 已运行，请使用 `claude --debug-file <path> --init-only` 启动，将 `<path>` 替换为日志文件位置，然后在日志中查看 Setup 和 SessionStart hook 的条目。

1337 1336

1338由于 Setup 并非每次启动都会触发，需要安装依赖的插件不能仅依赖 Setup。实用的模式是在首次使用时检查依赖，缺失时再安装，例如由 hook 或 skill 检测 `${CLAUDE_PLUGIN_DATA}/node_modules`，若不存在则运行 `npm install`。有关存储已安装依赖的位置，请参阅[持久数据目录](/docs/zh-CN/plugins/components#path-variables-and-persistent-data)。如果您通过市场分发插件，则可能不需要此模式：Claude Code 在缓存插件时会[自动安装符合条件的 Node.js 包依赖](/docs/zh-CN/plugins/loading#node-js-package-dependencies)。1337由于 Setup 不会在每次启动时触发，需要安装依赖的插件不能仅依赖 Setup。实用的模式是在首次使用时检查依赖，缺失时再安装，例如使用一个 hook 或 skill 检测 `${CLAUDE_PLUGIN_DATA}/node_modules`，若不存在则运行 `npm install`。关于已安装依赖的存放位置，请参阅[持久数据目录](/docs/zh-CN/plugins/components#path-variables-and-persistent-data)。如果您通过市场分发插件，则可能不需要此模式：Claude Code 在缓存插件时会[自动安装符合条件的 Node.js 包依赖](/docs/zh-CN/plugins/loading#node-js-package-dependencies)。

1339 1338

1340<h4 id="setup-input">1339<h4 id="setup-input">

1341 Setup 输入1340 Setup 输入

1342</h4>1341</h4>

1343 1342

1344除了[通用输入字段](#common-input-fields)之外，Setup hook 还会接收一个 `trigger` 字段，其值为 `"init"` 或 `"maintenance"`：1343除[通用输入字段](#common-input-fields)外，Setup hook 还会接收一个 `trigger` 字段，其值为 `"init"` 或 `"maintenance"`：

1345 1344

1346```json theme={null}1345```json theme={null}

1347{1346{

1357 Setup 决策控制1356 Setup 决策控制

1358</h4>1357</h4>

1359 1358

1360Setup hook 无法阻止执行；无论退出码如何，执行都会继续。对于任何退出码，Claude Code 都会丢弃 Setup hook 的 [JSON 输出字段](#json-output)，例如 `systemMessage`、`continue` 和 `hookSpecificOutput.additionalContext`。使用 `-p` 时，只有在以 `--output-format stream-json --verbose` 启动时，Setup hook 的 stdout、stderr 和退出码才会作为 [`hook_response` 事件](/docs/zh-CN/headless#read-session-metadata)出现在运行输出中。1359Setup hook 无法阻止执行；无论退出码是什么，执行都会继续。无论退出码是什么，Claude Code 都会丢弃 Setup hook 的 [JSON 输出字段](#json-output)，例如 `systemMessage`、`continue` 和 `hookSpecificOutput.additionalContext`。使用 `-p` 时，只有在您使用 `--output-format stream-json --verbose` 启动的情况下，Setup hook 的 stdout、stderr 和退出码才会以 [`hook_response` 事件](/docs/zh-CN/headless#read-session-metadata)的形式出现在运行输出中。

1361 1360

1362Setup hook 可以访问 `CLAUDE_ENV_FILE`。写入该文件的变量会持久保留到该会话后续的 Bash 命令中，与 [SessionStart hook](#persist-environment-variables) 相同。只有 `type: "command"` hook 会在 `Setup` 上运行。`Setup` 上的 `type: "mcp_tool"` hook 始终会被跳过，如 [MCP 工具 hook 字段](#mcp-tool-hook-fields)中所述。1361Setup hook 可以访问 `CLAUDE_ENV_FILE`。写入该文件的变量会在会话的后续 Bash 命令中持久存在，与 [SessionStart hook](#persist-environment-variables) 相同。`Setup` 上只运行 `type: "command"` hook。`Setup` 上的 `type: "mcp_tool"` hook 始终会被跳过，详见 [MCP 工具 hook 字段](#mcp-tool-hook-fields)。

1363 1362

1364<h3 id="instructionsloaded">1363<h3 id="instructionsloaded">

1365 InstructionsLoaded1364 InstructionsLoaded

1366</h3>1365</h3>

1367 1366

1368当 `CLAUDE.md` 或 `.claude/rules/*.md` 文件被加载到上下文中时触发。此事件会在会话开始时为预先加载的文件触发，之后在文件被延迟加载时再次触发，例如当 Claude 访问包含嵌套 `CLAUDE.md` 的子目录时，或带有 `paths:` frontmatter 的条件规则匹配时。该 hook 不支持阻止或决策控制。它以异步方式运行，用于可观测性目的。1367当 `CLAUDE.md` 或 `.claude/rules/*.md` 文件被加载到上下文中时触发。此事件在会话开始时针对立即加载的文件触发，之后在文件被延迟加载时再次触发，例如当 Claude 访问包含嵌套 `CLAUDE.md` 的子目录时，或当带有 `paths:` frontmatter 的条件规则匹配时。该 hook 不支持阻止或决策控制。它以异步方式运行，用于可观测性目的。

1369 1368

1370当 Claude 通过 **Project instructions** 设置[直接读取 `AGENTS.md`](/docs/zh-CN/memory#agents-md) 时，此事件不会触发。当 `CLAUDE.md` 导入您的 `AGENTS.md` 时，此事件会触发，`load_reason` 与其他任何导入文件一样设置为 `include`；当 `CLAUDE.md` 是指向它的符号链接时，此事件也会作为普通的 `CLAUDE.md` 加载而触发。1369当 Claude 通过 **Project instructions** 设置[直接读取 `AGENTS.md`](/docs/zh-CN/memory#agents-md) 时，此事件不会触发。当 `CLAUDE.md` 导入您的 `AGENTS.md` 时，它会触发，`load_reason` 设置为 `include`，与任何其他被导入的文件相同；当 `CLAUDE.md` 是指向它的符号链接时，它也会作为一次普通的 `CLAUDE.md` 加载触发。

1371 1370

1372匹配器针对 `load_reason` 运行。例如，使用 `"matcher": "session_start"` 仅针对会话开始时加载的文件触发，或使用 `"matcher": "path_glob_match|nested_traversal"` 仅针对延迟加载触发。1371匹配器针对 `load_reason` 运行。例如，使用 `"matcher": "session_start"` 仅针对会话开始时加载的文件触发，或使用 `"matcher": "path_glob_match|nested_traversal"` 仅针对延迟加载触发。

1373 1372

1375 InstructionsLoaded 输入1374 InstructionsLoaded 输入

1376</h4>1375</h4>

1377 1376

1378除了[通用输入字段](#common-input-fields)之外，InstructionsLoaded hook 还会接收以下字段：1377除[通用输入字段](#common-input-fields)外，InstructionsLoaded hook 还会接收以下字段：

1379 1378

1380| 字段 | 描述 |1379| 字段 | 描述 |

1381| :- | :- |1380| :- | :- |

1384| `load_reason` | 文件被加载的原因：`"session_start"`、`"nested_traversal"`、`"path_glob_match"`、`"include"` 或 `"compact"`。`"compact"` 值在压缩事件后重新加载指令文件时触发 |1383| `load_reason` | 文件被加载的原因：`"session_start"`、`"nested_traversal"`、`"path_glob_match"`、`"include"` 或 `"compact"`。`"compact"` 值在压缩事件之后重新加载指令文件时触发 |

1388 1387

1389```json theme={null}1388```json theme={null}

1390{1389{

1402 InstructionsLoaded 决策控制1401 InstructionsLoaded 决策控制

1403</h4>1402</h4>

1404 1403

1405InstructionsLoaded hook 没有决策控制。它们无法阻止或修改指令加载。Claude Code 会丢弃它们的 [JSON 输出字段](#json-output)，例如 `systemMessage` 和 `continue`。可将此事件用于审计日志记录、合规跟踪或可观测性。1404InstructionsLoaded hook 没有决策控制。它们无法阻止或修改指令的加载。Claude Code 会丢弃它们的 [JSON 输出字段](#json-output)，例如 `systemMessage` 和 `continue`。可将此事件用于审计日志、合规跟踪或可观测性。

1406 1405

1407<h3 id="userpromptsubmit">1406<h3 id="userpromptsubmit">

1408 UserPromptSubmit1407 UserPromptSubmit

1409</h3>1408</h3>

1410 1409

1411在提交提示词时、Claude 处理它之前运行。这使您可以1410在提交提示词后、Claude 处理之前运行。这使您能够

1412根据提示词/对话添加额外的上下文、验证提示词，或1411根据提示词/对话添加额外的上下文、验证提示词，或

1413阻止某些类型的提示词。1412阻止某些类型的提示词。

1414 1413

1415`UserPromptSubmit` hook 不仅在您输入的提示词上触发。Claude Code 还会在以下情况下运行它们：1414`UserPromptSubmit` hook 不仅在您输入的提示词上触发。Claude Code 还会在以下情况下运行它们：

1416 1415

1417* [定时任务](/docs/zh-CN/scheduled-tasks)触发，包括 `/loop` 的每次迭代1416* [定时任务](/docs/zh-CN/scheduled-tasks)触发时，包括 `/loop` 的一次迭代

1418* [后台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)向启动它的会话回报1417* [后台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)向启动它的会话回报时

1419* [另一个会话发送的消息](/docs/zh-CN/cross-session-messaging)到达您的主对话1418* [另一个会话发送消息](/docs/zh-CN/cross-session-messaging)到您的主对话时

1420 1419

1421对于 `command`、`http` 和 `mcp_tool` 类型，`UserPromptSubmit` hook 的默认超时时间为 30 秒，短于这些类型在大多数其他事件上的 600 秒默认值。由于此 hook 在每个提示词之前运行，并会阻塞模型处理直到完成，卡住的 hook 会使会话停滞。如果您的 hook 需要更多时间，请在 hook 条目中设置 `timeout` 字段。1420对于 `command`、`http` 和 `mcp_tool` 类型，`UserPromptSubmit` hook 的默认超时时间为 30 秒，短于这些类型在大多数其他事件上 600 秒的默认值。由于此 hook 在每个提示词之前运行，并且在完成前会阻塞模型处理，卡住的 hook 会使会话停滞。如果您的 hook 需要更多时间，请在 hook 条目中设置 `timeout` 字段。

1422 1421

1423除了您使用 [`async: true`](#run-hooks-in-the-background) 运行的命令 hook 之外，达到超时的 `UserPromptSubmit` 命令、HTTP 或 MCP 工具 hook 会被取消，其输出（包括任何 `additionalContext`）会被丢弃。提示词仍会传递给 Claude，但不带该上下文。会话记录中会显示一条通知，指明该 hook、触发的超时时间，以及输出已被丢弃。1422除了使用 [`async: true`](#run-hooks-in-the-background) 运行的 command hook 外，达到超时的 `UserPromptSubmit` command、HTTP 或 MCP 工具 hook 会被取消，其输出（包括任何 `additionalContext`）会被丢弃。提示词仍会传达给 Claude，只是不带该上下文。会话记录中会显示一条通知，指明该 hook、触发的超时时间，以及输出已被丢弃。

1424 1423

1425`UserPromptSubmit` 上达到超时的 [Agent SDK 回调 hook](/docs/zh-CN/agent-sdk/hooks) 会阻止该提示词，并显示一条指明该 hook 和超时时间的消息，因为此处的回调可能充当不能在失败时放行的策略关卡。会话会继续。在 v2.1.208 之前，该事件上的回调超时会以执行错误结束该轮次。1424`UserPromptSubmit` 上的 [Agent SDK 回调 hook](/docs/zh-CN/agent-sdk/hooks) 达到超时时，会阻止该提示词，并显示一条指明该 hook 和超时时间的消息，因为此处的回调可能充当不能失败放行的策略关卡。会话会继续。在 v2.1.208 之前，该事件上的回调超时会以执行错误结束该轮次。

1426 1425

1427<h4 id="userpromptsubmit-input">1426<h4 id="userpromptsubmit-input">

1428 UserPromptSubmit 输入1427 UserPromptSubmit 输入

1429</h4>1428</h4>

1430 1429

1431除了[通用输入字段](#common-input-fields)之外，UserPromptSubmit hook 还会接收包含所提交文本的 `prompt` 字段。折叠为 `[Pasted text #N]` 占位符的粘贴内容会在原位置展开后传入。在 Claude Code [为 Claude 标记粘贴文本](/docs/zh-CN/terminal-config#how-claude-treats-pasted-text)的会话中，展开的内容位于 `<pasted_content id="…">` 行和 `</pasted_content id="…">` 行之间，因此如果您的 hook 解析提示词，请考虑这些行。1430除[通用输入字段](#common-input-fields)外，UserPromptSubmit hook 还会接收包含所提交文本的 `prompt` 字段。被折叠为 `[Pasted text #N]` 占位符的粘贴内容会在原处展开后传入。在 Claude Code [为 Claude 标记粘贴文本](/docs/zh-CN/terminal-config#how-claude-treats-pasted-text)的会话中，展开的内容位于 `<pasted_content id="…">` 行和 `</pasted_content id="…">` 行之间，因此如果您的 hook 需要解析提示词，请考虑这些行。

1432 1431

1433当会话具有自定义标题时，UserPromptSubmit hook 还会接收 `session_title`，其含义与 [SessionStart 的 `session_title` 字段](#sessionstart-input)相同。1432当会话有自定义标题时，UserPromptSubmit hook 还会接收 `session_title`，其含义与 [SessionStart 的 `session_title` 字段](#sessionstart-input)相同。

1434 1433

1435```json theme={null}1434```json theme={null}

1436{1435{

1447 UserPromptSubmit 决策控制1446 UserPromptSubmit 决策控制

1448</h4>1447</h4>

1449 1448

1450`UserPromptSubmit` hook 可以控制是否处理已提交的提示词，并添加上下文。所有 [JSON 输出字段](#json-output)均可用。1449`UserPromptSubmit` hook 可以控制是否处理提交的提示词，并添加上下文。所有 [JSON 输出字段](#json-output)均可用。

1451 1450

1452在退出码为 0 时，有两种方式向对话添加上下文：1451在退出码为 0 时，有两种方式可以向对话添加上下文：

1453 1452

1454* **纯文本 stdout**：Claude Code 会将其[视为纯文本](#exit-code-0)的 stdout 添加到 Claude 的上下文中1453* **纯文本 stdout**：Claude Code 会将其[视为纯文本](#exit-code-0)的 stdout 添加到 Claude 的上下文中

1455* **带有 `additionalContext` 的 JSON**：使用下面的 JSON 格式以获得更多控制。`additionalContext` 字段会作为上下文添加1454* **带有 `additionalContext` 的 JSON**：使用下面的 JSON 格式以获得更多控制。`additionalContext` 字段会作为上下文添加

1456 1455

1457这两种方式都不会在会话记录中产生可见条目。纯 stdout 和 `additionalContext` 值各自作为以 hook 名称开头的系统提醒注入；Claude 会读取两者。要确认是否已传递，请查看[调试日志](#debug-hooks)。1456两种方式都不会在会话记录中生成可见条目。纯 stdout 和 `additionalContext` 的值都会各自作为以 hook 名称开头的系统提醒注入；Claude 会读取两者。要确认已送达，请查看[调试日志](#debug-hooks)。

1458 1457

1459要阻止提示词，请返回一个 `decision` 设置为 `"block"` 的 JSON 对象：1458要阻止提示词，请返回一个 `decision` 设置为 `"block"` 的 JSON 对象：

1460 1459

1461| 字段 | 描述 |1460| 字段 | 描述 |

1462| :- | :- |1461| :- | :- |

1467| `suppressOriginalPrompt` | 如果在 hook 阻止提示词时为 `true`，则阻止消息中不包含提示词文本。请参阅[被阻止的提示词会留下什么](#what-a-blocked-prompt-leaves-behind) |1466| `suppressOriginalPrompt` | 如果在 hook 阻止提示词时为 `true`，则阻止消息中不包含提示词文本。请参阅[被阻止的提示词会留下什么](#what-a-blocked-prompt-leaves-behind) |

1468 1467

1469通过以退出码 2 退出来阻止的 hook，其处理方式与 `reason` 相同：阻止消息会向用户显示 stderr 文本，且不会添加到上下文中。1468通过以 2 退出来阻止的 hook，其处理方式与 `reason` 相同：阻止消息会向用户显示 stderr 文本，且不会添加到上下文中。

1470 1469

1471```json theme={null}1470```json theme={null}

1472{1471{

1485 被阻止的提示词会留下什么1484 被阻止的提示词会留下什么

1486</h4>1485</h4>

1487 1486

1488被阻止的提示词永远不会到达 Claude，但其文本并不会从所有地方移除。默认情况下，显示给用户的阻止消息以 `Original prompt:` 结尾，后跟所提交的文本，并且 Claude Code 会将该消息写入磁盘上的会话记录文件。要在消息中省略该文本，请在 `hookSpecificOutput` 中打印带有 `"suppressOriginalPrompt": true` 的 JSON。无论 hook 是通过 `decision: "block"` 还是以退出码 2 退出来阻止，此设置都有效。1487被阻止的提示词永远不会到达 Claude，但其文本并不会在所有地方被删除。默认情况下，向用户显示的阻止消息以 `Original prompt:` 结尾，后接所提交的文本，并且 Claude Code 会将该消息写入磁盘上会话的会话记录文件。要在消息中省略该文本，请在 `hookSpecificOutput` 中打印带有 `"suppressOriginalPrompt": true` 的 JSON。无论 hook 是通过 `decision: "block"` 还是通过以 2 退出来阻止，此方法均有效。

1489 1488

1490`suppressOriginalPrompt` 仅更改阻止消息。提交的文本仍可能出现在本地文件中，例如会话记录和您的提示词历史记录，因此阻止型 hook 并不是防止机密写入磁盘的方法。要限制或删除这些文件，请参阅[明文存储](/docs/zh-CN/claude-directory#plaintext-storage)和[清除本地数据](/docs/zh-CN/claude-directory#clear-local-data)。1489`suppressOriginalPrompt` 只会改变阻止消息。所提交的文本仍可能出现在本地文件中，例如会话记录和您的提示词历史记录，因此阻止型 hook 并不能让机密信息不落盘。要限制或删除这些文件，请参阅[明文存储](/docs/zh-CN/claude-directory#plaintext-storage)和[清除本地数据](/docs/zh-CN/claude-directory#clear-local-data)。

1491 1490

1492<h3 id="userpromptexpansion">1491<h3 id="userpromptexpansion">

1493 UserPromptExpansion1492 UserPromptExpansion

1494</h3>1493</h3>

1495 1494

1496在用户输入的命令展开为提示词、到达 Claude 之前运行。可用于阻止直接调用特定命令、为特定 skill 注入上下文，或记录用户调用了哪些命令。例如，匹配 `deploy` 的 hook 可以在不存在批准文件时阻止 `/deploy`，或者匹配某个审查 skill 的 hook 可以将团队的审查清单作为 `additionalContext` 追加。1495当用户输入的命令在到达 Claude 之前展开为提示词时运行。可用于阻止直接调用特定命令、为特定 skill 注入上下文，或记录用户调用了哪些命令。例如，匹配 `deploy` 的 hook 可以在不存在批准文件时阻止 `/deploy`，或者匹配某个审查 skill 的 hook 可以将团队的审查清单作为 `additionalContext` 附加。

1497 1496

1498此事件覆盖了 `PreToolUse` 未覆盖的路径：匹配 `Skill` 工具的 `PreToolUse` hook 只在 Claude 调用该工具时触发，而直接输入 `/skillname` 会绕过 `PreToolUse`。`UserPromptExpansion` 会在这条直接路径上触发。1497此事件覆盖了 `PreToolUse` 无法覆盖的路径：匹配 `Skill` 工具的 `PreToolUse` hook 只在 Claude 调用该工具时触发，但直接输入 `/skillname` 会绕过 `PreToolUse`。`UserPromptExpansion` 会在这条直接路径上触发。

1499 1498

1500针对 `command_name` 进行匹配。将匹配器留空可在每个提示词类型的命令上触发。1499匹配 `command_name`。将匹配器留空可在每个提示词类型的命令上触发。

1501 1500

1502<h4 id="userpromptexpansion-input">1501<h4 id="userpromptexpansion-input">

1503 UserPromptExpansion 输入1502 UserPromptExpansion 输入

1504</h4>1503</h4>

1505 1504

1506除了[通用输入字段](#common-input-fields)之外，UserPromptExpansion hook 还会接收 `expansion_type`、`command_name`、`command_args`、`command_source` 以及原始的 `prompt` 字符串。对于 skill 和自定义命令，`expansion_type` 字段为 `slash_command`；对于 MCP 服务器提示词，该字段为 `mcp_prompt`。1505除[通用输入字段](#common-input-fields)外，UserPromptExpansion hook 还会接收 `expansion_type`、`command_name`、`command_args`、`command_source` 以及原始的 `prompt` 字符串。对于 skill 和自定义命令，`expansion_type` 字段为 `slash_command`；对于 MCP 服务器提示词，则为 `mcp_prompt`。

1507 1506

1508```json theme={null}1507```json theme={null}

1509{1508{

1524 UserPromptExpansion 决策控制1523 UserPromptExpansion 决策控制

1525</h4>1524</h4>

1526 1525

1527`UserPromptExpansion` hook 可以阻止展开或添加上下文。所有 [JSON 输出字段](#json-output)均可使用。1526`UserPromptExpansion` hook 可以阻止展开或添加上下文。所有 [JSON 输出字段](#json-output)均可用。

1528 1527

1529| 字段 | 描述 |1528| 字段 | 描述 |

1530| :- | :- |1529| :- | :- |

1534 1533

1535通过以退出码 2 退出来阻止的 hook，其处理方式与 `reason` 相同：阻止消息会向用户显示 stderr 文本。1534通过以 2 退出来阻止的 hook，其处理方式与 `reason` 相同：阻止消息会向用户显示 stderr 文本。

1536 1535

1537```json theme={null}1536```json theme={null}

1538{1537{

1549 MessageDisplay1548 MessageDisplay

1550</h3>1549</h3>

1551 1550

1552在助手消息流式显示到屏幕上时运行。Claude Code 以增量方式显示消息：每当一批新完成的行准备好渲染时，hook 就会以这些行运行一次，Claude Code 会在原位置渲染 hook 的替换文本。长消息会产生多次调用；短消息可能只产生一次。1551在助手消息流式显示到屏幕上时运行。Claude Code 会分批显示消息：每当一批新完成的行准备好渲染时，hook 会使用这些行运行一次，Claude Code 会在原位置渲染 hook 返回的替换文本。长消息会产生多次调用；短消息可能只产生一次。

1553 1552

1554可使用 MessageDisplay 来：1553使用 MessageDisplay 可以：

1555 1554

1556* 去除 markdown 以实现极简显示1555* 去除 markdown 以获得极简显示

1557* 转换 Agent SDK 应用程序向其用户显示的文本1556* 转换 Agent SDK 应用向其用户显示的文本

1558* 从 Claude 的回复中编辑隐去 API 密钥或内部主机名1557* 从 Claude 的回复中隐去 API 密钥或内部主机名

1559 1558

1560Claude Code 会保留每一批内容直到您的 hook 返回，因此请保持 hook 快速执行。如果 hook 失败或超时，Claude Code 会显示原始文本。此事件的默认超时时间为 10 秒；如果您的 hook 需要更多时间，请在 hook 条目中设置 `timeout` 字段。1559Claude Code 会保留每一批内容，直到您的 hook 返回，因此请确保 hook 运行迅速。如果 hook 失败或超时，Claude Code 会显示原始文本。此事件的默认超时时间为 10 秒；如果您的 hook 需要更多时间，请在 hook 条目中设置 `timeout` 字段。

1561 1560

1562MessageDisplay 仅影响显示：替换文本只改变屏幕上渲染的内容。会话记录和 Claude 看到的内容保留原始文本，因此 Claude 永远看不到替换内容，详细模式也会显示原始文本。该 hook 仅接收助手消息文本，因此工具结果和您输入的文本会原样渲染。1561MessageDisplay 仅作用于显示：替换文本只会改变屏幕上渲染的内容。会话记录以及 Claude 看到的内容都保持原始文本，因此 Claude 永远看不到替换内容，详细模式也会显示原始文本。该 hook 只接收助手消息文本，因此工具结果和您输入的文本会原样渲染。

1563 1562

1564MessageDisplay 不支持匹配器，会针对每条流式输出文本的助手消息触发；不含文本的消息（例如仅包含工具调用的回复）不会触发它。1563MessageDisplay 不支持匹配器，并会针对每条流式输出文本的助手消息触发；不含文本的消息（例如仅包含工具调用的响应）不会触发它。

1565 1564

1566在非交互运行中（包括 Agent SDK 查询和 `claude -p`），MessageDisplay 对每条助手消息运行一次，而不是对每批行运行一次。这一次调用在消息完成后到达，并携带完整的消息文本：`index` 为 `0`，`final` 为 `true`，`delta` 包含整条消息。收集每条消息 `delta` 文本的 hook 在两种模式下收到的总文本相同。1565在非交互式运行中（包括 Agent SDK 查询和 `claude -p`），MessageDisplay 对每条助手消息只运行一次，而不是每批行运行一次。这唯一的一次调用在消息完成后到达，并携带完整的消息文本：`index` 为 `0`，`final` 为 `true`，`delta` 包含整条消息。收集每条消息 `delta` 文本的 hook 在两种模式下接收到的总文本相同。

1567 1566

1568<h4 id="messagedisplay-input">1567<h4 id="messagedisplay-input">

1569 MessageDisplay 输入1568 MessageDisplay 输入

1570</h4>1569</h4>

1571 1570

1572除了[通用输入字段](#common-input-fields)之外，MessageDisplay hook 还会接收轮次和消息的标识符、此次调用在消息中的位置，以及 `delta` 中的新文本。批次边界取决于文本的流式传输方式，因此请使用 `index` 和 `final` 跟踪消息的进度，而不要期望行以特定方式分组。1571除[通用输入字段](#common-input-fields)外，MessageDisplay hook 还会接收轮次和消息的标识符、此次调用在消息中的位置，以及 `delta` 中的新文本。批次边界取决于文本的流式传输方式，因此请使用 `index` 和 `final` 来跟踪消息的进度，而不要假定各行会以特定方式分组。

1573 1572

1574| 字段 | 描述 |1573| 字段 | 描述 |

1575| :- | :- |1574| :- | :- |

1580| `delta` | 自上一批次以来新完成的行，包含结尾的换行符。始终为完整的行，但最终批次可能在行中间结束。在交互运行中，当消息以换行符结尾时，最终批次的 delta 为空，因此请将 `final`（而非非空的 delta）视为消息结束的信号。在 Agent SDK 和 `claude -p` 运行中，单次调用携带整条消息 |1579| `delta` | 自上一批次以来新完成的行，包括结尾的换行符。始终是完整的行，但最终批次可能在行中间结束。在交互式运行中，当消息以换行符结尾时，最终批次的 delta 为空，因此请将 `final`（而不是非空的 delta）作为消息结束的信号。在 Agent SDK 和 `claude -p` 运行中，这唯一的一次调用携带整条消息 |

1581 1580

1582```json theme={null}1581```json theme={null}

1583{1582{

1597 MessageDisplay 输出1596 MessageDisplay 输出

1598</h4>1597</h4>

1599 1598

1600除了所有 hook 都可用的 [JSON 输出字段](#json-output)之外，MessageDisplay hook 还可以返回 `displayContent`，以在屏幕上替换 delta：1599除所有 hook 都可用的 [JSON 输出字段](#json-output)外，MessageDisplay hook 还可以返回 `displayContent`，以在屏幕上替换 delta：

1601 1600

1602| 字段 | 描述 |1601| 字段 | 描述 |

1603| :- | :- |1602| :- | :- |

1605 1604

1606MessageDisplay hook 没有决策控制。它们无法阻止消息，也无法更改存储在会话记录中或发送给 Claude 的内容。Claude Code 会处理其 JSON 输出中的 `displayContent`，并丢弃 `systemMessage` 和 `continue`。1605MessageDisplay hook 没有决策控制。它们无法阻止消息，也无法更改存储在会话记录中或发送给 Claude 的内容。Claude Code 会处理其 JSON 输出中的 `displayContent`，并丢弃 `systemMessage` 和 `continue`。

1607 1606

1608以下示例从 Claude 的回复中去除 markdown 格式，以实现纯文本显示。该脚本从 stdin 读取每一批内容，从 `delta` 中移除粗体标记和行内代码反引号，并将结果作为 `displayContent` 返回。1607此示例从 Claude 的回复中去除 markdown 格式，以实现纯文本显示。该脚本从 stdin 读取每一批内容，从 `delta` 中移除粗体标记和行内代码反引号，并将结果作为 `displayContent` 返回。

1609 1608

1610<Tabs>1609<Tabs>

1611 <Tab title="macOS/Linux">1610 <Tab title="macOS/Linux">

1612 在您的设置文件中为该事件注册一个命令 hook：1611 在您的设置文件中为该事件注册一个 command hook：

1613 1612

1614 ```json theme={null}1613 ```json theme={null}

1615 {1614 {

1638 </Tab>1637 </Tab>

1639 1638

1640 <Tab title="Windows (PowerShell)">1639 <Tab title="Windows (PowerShell)">

1641 注册一个通过 PowerShell 运行脚本的命令 hook：1640 注册一个通过 PowerShell 运行脚本的 command hook：

1642 1641

1643 ```json theme={null}1642 ```json theme={null}

1644 {1643 {

1664 }1663 }

1665 ```1664 ```

1666 1665

1667 `-NoProfile` 标志会跳过加载您的 PowerShell 配置文件，使 hook 快速启动；`-ExecutionPolicy Bypass` 则允许 PowerShell 运行本地脚本文件。1666 `-NoProfile` 标志会跳过加载您的 PowerShell 配置文件，使 hook 快速启动，`-ExecutionPolicy Bypass` 则允许 PowerShell 运行本地脚本文件。

1668 1667

1669 将此脚本保存到项目中的 `.claude/hooks/plain-display.ps1`：1668 将此脚本保存到项目中的 `.claude/hooks/plain-display.ps1`：

1670 1669

1681 </Tab>1680 </Tab>

1682</Tabs>1681</Tabs>

1683 1682

1684不含 markdown 的批次会原样通过。如果脚本失败（例如因为缺少 `jq`），Claude Code 会显示原始文本，并且仅在[调试输出](#debug-hooks)中记录该失败，而不会在会话中显示。1683不含 markdown 的批次会原样通过。如果脚本失败（例如因为缺少 `jq`），Claude Code 会显示原始文本，并且只在[调试输出](#debug-hooks)中记录该失败，而不会在会话中显示。

1685 1684

1686<h3 id="pretooluse">1685<h3 id="pretooluse">

1687 PreToolUse1686 PreToolUse

1688</h3>1687</h3>

1689 1688

1690在 Claude 创建工具参数之后、处理工具调用之前运行。可匹配除 `EndConversation` 以外的任何工具名称：内置工具，例如 `Bash`、`PowerShell`、`Edit`、`Write`、`Read`、`Glob`、`Grep`、`Agent`、`Workflow`、`WebFetch`、`WebSearch`、`AskUserQuestion` 和 `ExitPlanMode`，以及任何 [MCP 工具名称](#match-mcp-tools)。1689在 Claude 创建工具参数之后、处理工具调用之前运行。可匹配除 `EndConversation` 之外的任何工具名称：包括 `Bash`、`PowerShell`、`Edit`、`Write`、`Read`、`Glob`、`Grep`、`Agent`、`Workflow`、`WebFetch`、`WebSearch`、`AskUserQuestion` 和 `ExitPlanMode` 等内置工具，以及任何 [MCP 工具名称](#match-mcp-tools)。

1691 1690

1692要在特定文件于磁盘上发生更改时运行 hook（无论是什么写入的），请使用 [FileChanged](#filechanged)，而不是按名称匹配文件编辑工具。与 PreToolUse 不同，Claude Code 在更改之后运行 FileChanged hook，且它们没有决策控制，因此无法阻止写入。1691要在磁盘上某个特定文件发生变化时运行 hook（无论是谁写入的），请使用 [FileChanged](#filechanged)，而不是按名称匹配文件编辑工具。与 PreToolUse 不同，Claude Code 在更改发生后运行 FileChanged hook，并且它们没有决策控制，因此无法阻止写入。

1693 1692

1694<Warning>1693<Warning>

1695 PreToolUse 仅在 Claude 调用工具时运行。您[在提示词中使用 `@` 引用](/docs/zh-CN/common-workflows#reference-files-and-directories)的文件是在没有任何工具调用的情况下添加的：Claude Code 在构建提示词时插入其内容，因此不会为它们触发任何 PreToolUse hook，包括匹配 `Read` 的 hook。要阻止特定路径被 `@` 引用，请改用 [`Read` 拒绝规则](/docs/zh-CN/permissions#read-and-edit)。1694 PreToolUse 仅在 Claude 调用工具时运行。您[在提示词中使用 `@` 引用](/docs/zh-CN/common-workflows#reference-files-and-directories)的文件无需任何工具调用即可添加：Claude Code 在构建提示词时插入其内容，因此不会为它们触发任何 PreToolUse hook，包括匹配 `Read` 的 hook。要阻止通过 `@` 引用特定路径，请改用 [`Read` 拒绝规则](/docs/zh-CN/permissions#read-and-edit)。

1696 1695

1697 PreToolUse 也不会为 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 触发。1696 PreToolUse 也不会为 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 触发。

1698</Warning>1697</Warning>

1699 1698

1700使用 [PreToolUse 决策控制](#pretooluse-decision-control)来允许、拒绝、询问或延迟工具调用。1699使用 [PreToolUse 决策控制](#pretooluse-decision-control)来允许、拒绝、询问或推迟工具调用。

1701 1700

1702`PreToolUse` 上超过其超时时间的 [Agent SDK 回调 hook](/docs/zh-CN/agent-sdk/hooks) 会阻止该工具调用，Claude 会收到一个指明该超时的错误结果。其他 hook 返回的显式拒绝仍然优先。1701`PreToolUse` 上的 [Agent SDK 回调 hook](/docs/zh-CN/agent-sdk/hooks) 超过其超时时间时，会阻止该工具调用，Claude 会收到一个指明超时的错误结果。其他 hook 返回的显式拒绝仍然优先。

1703 1702

1704<h4 id="pretooluse-input">1703<h4 id="pretooluse-input">

1705 PreToolUse 输入1704 PreToolUse 输入

1706</h4>1705</h4>

1707 1706

1708除了[通用输入字段](#common-input-fields)之外，PreToolUse hook 还会接收 `tool_name`、`tool_input` 和 `tool_use_id`。1707除[通用输入字段](#common-input-fields)外，PreToolUse hook 还会接收 `tool_name`、`tool_input` 和 `tool_use_id`。

1709 1708

1710对于 [MCP 工具](#match-mcp-tools)，输入中还会携带 `mcp_server`，这是一个包含服务器 `name` 和 `source` 的对象，`source` 说明服务器定义的来源。`source` 的值包括 `plugin`、`sdk`，以及 `user` 和 `project` 等配置作用域。Agent SDK 参考中的 [`McpServerProvenance`](/docs/zh-CN/agent-sdk/typescript#mcpserverprovenance) 列出了所有值，并说明了如何处理无法识别的值。请基于 `source` 做出信任决策，而不是基于 `name` 或 `mcp__<server>__` 工具名称前缀。`mcp_server` 字段需要 Claude Code v2.1.274 或更高版本。1709对于 [MCP 工具](#match-mcp-tools)，输入中还会包含 `mcp_server`，这是一个对象，包含服务器的 `name`，以及说明服务器定义来源的 `source`。`source` 的值包括 `plugin`、`sdk`，以及 `user` 和 `project` 等配置作用域。Agent SDK 参考中的 [`McpServerProvenance`](/docs/zh-CN/agent-sdk/typescript#mcpserverprovenance) 列出了所有值，并说明了如何处理无法识别的值。请基于 `source` 而不是 `name` 或 `mcp__<server>__` 工具名前缀做出信任决策。`mcp_server` 字段需要 Claude Code v2.1.274 或更高版本。

1711 1710

1712对于文件工具 `Write`、`Edit` 和 `Read`，`tool_input.file_path` 始终是绝对路径：1711对于文件工具 `Write`、`Edit` 和 `Read`，`tool_input.file_path` 始终是绝对路径：

1713 1712

1714* Claude Code 会在 hook 运行之前展开 `~` 和相对路径，因此基于路径匹配的 hook 无法通过 `~` 或同一路径的相对写法被绕过1713* Claude Code 会在 hook 运行前展开 `~` 和相对路径，因此基于路径匹配的 hook 无法通过 `~` 或同一路径的相对写法被绕过

1715* 在 Windows 上，路径以反斜杠分隔符传入，即使您的 hook 在 Git Bash 下运行且 `$PWD` 看起来像 `/c/project`1714* 在 Windows 上，路径以反斜杠分隔符传入，即使您的 hook 在 Git Bash 下运行（其中 `$PWD` 看起来像 `/c/project`）也是如此

1716* 使用正斜杠编写的比较（例如 `/src/` 检查）永远不会匹配反斜杠路径，工具调用会像 hook 没有可阻止的内容一样继续进行1715* 使用正斜杠编写的比较（例如 `/src/` 检查）永远不会匹配反斜杠路径，工具调用会像 hook 没有任何需要阻止的内容一样继续进行

1717* 在比较之前规范化分隔符：Bash 中使用 `FILE_PATH="${FILE_PATH//\\//}"`，Python 中使用 `file_path.replace("\\", "/")`，然后匹配诸如 `/src/` 之类的路径片段，而不是用 `^` 锚定，因为路径是绝对路径1716* 比较之前请先规范化分隔符：在 Bash 中使用 `FILE_PATH="${FILE_PATH//\\//}"`，在 Python 中使用 `file_path.replace("\\", "/")`，然后匹配诸如 `/src/` 这样的路径片段，而不要用 `^` 锚定，因为路径是绝对路径

1718 1717

1719Windows 上的 `Write` 调用会传入：1718Windows 上的 `Write` 调用会传入：

1720 1719

1743| 字段 | 类型 | 示例 | 描述 |1742| 字段 | 类型 | 示例 | 描述 |

1744| :- | :- | :- | :- |1743| :- | :- | :- | :- |

1749 1748

1750当 Bash 命令更改 Git 仓库中的文件时，Claude Code 可以记录更改的内容。当 [`bashEditDiffEnabled`](/docs/zh-CN/settings-reference#basheditdiffenabled) 设置启用记录时，它会在所有权限模式下记录更改；该设置的条目说明了哪些文件可以设置它。否则，它仅在自动模式和 `bypassPermissions` 模式下记录，并且仅在 Claude Code 指示 Claude 通过 Bash 编辑文件时记录。将 `bashEditDiffEnabled` 设置为 `false` 可关闭记录。后台命令和只读命令不携带 diff。1749当 Bash 命令更改 Git 仓库中的文件时，Claude Code 可以记录更改的内容。当 [`bashEditDiffEnabled`](/docs/zh-CN/settings-reference#basheditdiffenabled) 设置启用记录时，它会在所有权限模式下记录更改；该设置的条目说明了哪些文件可以设置它。否则，它仅在自动模式和 `bypassPermissions` 模式下记录，并且仅在 Claude Code 指示 Claude 通过 Bash 编辑文件时记录。将 `bashEditDiffEnabled` 设置为 `false` 可关闭记录。后台命令和只读命令不携带 diff。

1751 1750

1752随后，您的 [PostToolUse hook](#posttooluse) 会在 `tool_response.bashEditDiff` 中接收更改的文件。该列表涵盖命令运行期间仓库下发生更改的内容。Git 忽略的文件和子模块中的文件不会列出。需要 Claude Code v2.1.269 或更高版本。1751随后，您的 [PostToolUse hook](#posttooluse) 会在 `tool_response.bashEditDiff` 中接收到已更改的文件。该列表涵盖命令运行期间仓库下发生的更改。Git 忽略的文件和子模块中的文件不会列出。需要 Claude Code v2.1.269 或更高版本。

1753 1752

1754<Note>1753<Note>

1755 该列表是尽力而为的，目前处于公测阶段。Claude Code 可能会遗漏更改、包含同时被另一个进程更改的文件，或在达到大小限制时停止。字段结构可能会发生变化。请使用该列表来确定需要审查的内容，而不要用它来执行策略。1754 该列表为尽力而为，目前处于公测阶段。Claude Code 可能会遗漏更改、包含同一时间被其他进程更改的文件，或在达到其大小限制时停止。字段结构可能会变化。请使用该列表来确定需要审查的内容，而不要用它来强制执行策略。

1756</Note>1755</Note>

1757 1756

1758`changedFiles` 和 `files` 列出命令更改的内容；其余字段说明该列表的完整程度和可靠程度。1757`changedFiles` 和 `files` 列出命令更改的内容；其余字段说明该列表的完整程度和可靠程度。

1759 1758

1760| 字段 | 类型 | 示例 | 描述 |1759| 字段 | 类型 | 示例 | 描述 |

1761| :- | :- | :- | :- |1760| :- | :- | :- | :- |

1763| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 最多 5 个已更改文件的 diff，用于显示。对于命令添加或删除的文件，`created` 或 `deleted` 为 `true` |1762| `files` | array | `[{"filePath": "/path/to/src/app.ts", "hunks": [...]}]` | 最多 5 个已更改文件的 diff，用于显示。对于命令新增或删除的文件，`created` 或 `deleted` 为 `true` |

1768 1767

1769<a id="powershell" />1768<a id="powershell" />

1770 1769

1772 PowerShell1771 PowerShell

1773</h5>1772</h5>

1774 1773

1775执行 PowerShell 命令。有关各平台的可用性，请参阅 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)。1774执行 PowerShell 命令。关于各平台的可用性，请参阅 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)。

1776 1775

1777字段与 Bash 工具相同，命令字符串位于 `command` 中：1776字段与 Bash 工具相同，命令字符串位于 `command` 中：

1778 1777

1779| 字段 | 类型 | 示例 | 描述 |1778| 字段 | 类型 | 示例 | 描述 |

1780| :- | :- | :- | :- |1779| :- | :- | :- | :- |

1785 1784

1786在检查 shell 命令的 hook 中匹配 `Bash|PowerShell`，以便同时覆盖这两个工具：1785在检查 shell 命令的 hook 中匹配 `Bash|PowerShell`，以便同时覆盖这两个工具：

1787 1786

1788* 在 Windows 上，只要启用了 PowerShell 工具，Claude 就会将 PowerShell 视为主 shell，并通过它执行 shell 命令。1787* 在 Windows 上，只要启用了 PowerShell 工具，Claude 就会将 PowerShell 视为主 shell，并通过它路由 shell 命令。

1789* 在没有 Git Bash 的 Windows 上，该工具会自动启用，且 Claude Code 根本不会注册 Bash 工具。1788* 在没有 Git Bash 的 Windows 上，该工具会自动启用，Claude Code 根本不会注册 Bash 工具。

1790* 仅匹配 `Bash` 的 hook 在那里永远不会触发。1789* 仅匹配 `Bash` 的 hook 在那里永远不会触发。

1791 1790

1792<h5 id="write">1791<h5 id="write">

1815 1814

1816<h5 id="read">1815<h5 id="read">

1817 Read1816 Read

1822| 字段 | 类型 | 示例 | 描述 |1821| 字段 | 类型 | 示例 | 描述 |

1823| :- | :- | :- | :- |1822| :- | :- | :- | :- |

1827 1826

1828<h5 id="glob">1827<h5 id="glob">

1829 Glob1828 Glob

1830</h5>1829</h5>

1831 1830

1832查找匹配 glob 模式的文件。1831查找与 glob 模式匹配的文件。

1833 1832

1834| 字段 | 类型 | 示例 | 描述 |1833| 字段 | 类型 | 示例 | 描述 |

1835| :- | :- | :- | :- |1834| :- | :- | :- | :- |

1836| `pattern` | string | `"**/*.ts"` | 用于匹配文件的 glob 模式 |1835| `pattern` | string | `"**/*.ts"` | 用于匹配文件的 glob 模式 |

1838 1837

1839<h5 id="grep">1838<h5 id="grep">

1840 Grep1839 Grep

1845| 字段 | 类型 | 示例 | 描述 |1844| 字段 | 类型 | 示例 | 描述 |

1846| :- | :- | :- | :- |1845| :- | :- | :- | :- |

1860| 字段 | 类型 | 示例 | 描述 |1859| 字段 | 类型 | 示例 | 描述 |

1861| :- | :- | :- | :- |1860| :- | :- | :- | :- |

1864 1863

1865<h5 id="websearch">1864<h5 id="websearch">

1866 WebSearch1865 WebSearch

1867</h5>1866</h5>

1868 1867

1869搜索网页。1868搜索网络。

1870 1869

1871| 字段 | 类型 | 示例 | 描述 |1870| 字段 | 类型 | 示例 | 描述 |

1872| :- | :- | :- | :- |1871| :- | :- | :- | :- |

1876 1875

1877<h5 id="agent">1876<h5 id="agent">

1878 Agent1877 Agent

1889 1888

1890当前台 Agent 调用完成时，您的 [PostToolUse hook](#posttooluse) 会在 `tool_response` 中接收子代理的结果和运行遥测数据。读取这些字段以检查运行情况；对于跨子代理的 token 和成本汇总，请使用按 `query_source` `"subagent"` 过滤的 [token 和成本计数器](/docs/zh-CN/monitoring-usage#token-counter)，因为 `totalTokens` 和 `usage` 仅涵盖最终请求：1889当前台 Agent 调用完成时，您的 [PostToolUse hook](#posttooluse) 会在 `tool_response` 中接收到子代理的结果和运行遥测数据。读取这些字段即可检查该次运行；如需汇总各子代理的 token 和成本，请使用按 `query_source` `"subagent"` 过滤的 [token 和成本计数器](/docs/zh-CN/monitoring-usage#token-counter)，因为 `totalTokens` 和 `usage` 只涵盖最后一个请求：

1891 1890

1892| 字段 | 类型 | 示例 | 描述 |1891| 字段 | 类型 | 示例 | 描述 |

1893| :- | :- | :- | :- |1892| :- | :- | :- | :- |

1896| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | 子代理的最终文本块；对于通过 `SubagentHandback` 提交报告的子代理，则改为一条关于该交回的简短说明 |1895| `content` | array | `[{"type": "text", "text": "Found 12 endpoints..."}]` | 子代理的最终文本块；对于通过 `SubagentHandback` 提交报告的子代理，则以一条关于该交回的简短说明代替 |

1902| `usage` | object | `{"input_tokens": 8320, ...}` | 最终 API 请求按类型划分的 token 明细：`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens` |1901| `usage` | object | `{"input_tokens": 8320, ...}` | 最后一次 API 请求按类型划分的 token 明细：`input_tokens`、`output_tokens`、`cache_creation_input_tokens`、`cache_read_input_tokens` |

1903 1902

1904在 Claude Code v2.1.271 或更高版本中，使用 [`SubagentHandback`](/docs/zh-CN/tools-reference) 工具（Claude Code 在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中提供）运行的子代理会通过该工具提交报告，而不是以文本形式返回。此时，其 `completed` 结果的 `content` 字段携带的是关于该交回的简短说明，而不是报告本身。要读取报告，请让 `PreToolUse` 或 `PostToolUse` hook 匹配 `SubagentHandback`，并读取 `tool_input.message`。1903在 Claude Code v2.1.271 或更高版本中，使用 [`SubagentHandback`](/docs/zh-CN/tools-reference) 工具（Claude Code 在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中提供）运行的子代理会通过该工具提交其报告，而不是以文本形式返回。此时其 `completed` 结果的 `content` 字段携带的是关于该交回的简短说明，而不是报告本身。要读取报告，请让 `PreToolUse` 或 `PostToolUse` hook 匹配 `SubagentHandback`，并读取 `tool_input.message`。

1905 1904

1906对于后台子代理，工具会在任务移至后台时返回，因此 `tool_response` 不携带用量字段：后台启动会立即返回，而被 Claude Code 在运行中途移至后台的前台任务会在该转换时返回。它包含 `status: "async_launched"`、`agentId`、`description`、`prompt`、`outputFile` 和 `resolvedModel`。1905对于后台子代理，工具会在任务转入后台时返回，因此 `tool_response` 不携带任何用量字段：后台启动会立即返回，而 Claude Code 在运行中途转入后台的前台任务会在转换时返回。它包含 `status: "async_launched"`、`agentId`、`description`、`prompt`、`outputFile` 和 `resolvedModel`。

1907 1906

1908在 `completed` 响应中，`resolvedModel` 指子代理启动时使用的模型，它可能与 `tool_input` 中的 `model` 值不同，例如在 `availableModels` 或其他覆盖生效时。在 `async_launched` 响应中，`resolvedModel` 指 Agent 移至后台时正在使用的模型，因此在移至后台之前发生的切换会反映在其中。`modelsUsed` 以及移至后台时的 `resolvedModel` 行为需要 Claude Code v2.1.212 或更高版本。1907在 `completed` 响应中，`resolvedModel` 表示子代理启动时使用的模型，它可能与 `tool_input` 中的 `model` 值不同，例如当 `availableModels` 或其他覆盖生效时。在 `async_launched` 响应中，`resolvedModel` 表示 Agent 转入后台时正在使用的模型，因此转入后台之前发生的模型更换会反映在其中。`modelsUsed` 以及转入后台时的 `resolvedModel` 行为需要 Claude Code v2.1.212 或更高版本。

1909 1908

1910<a id="askuserquestion" />1909<a id="askuserquestion" />

1911 1910

1913 AskUserQuestion1912 AskUserQuestion

1914</h5>1913</h5>

1915 1914

1916向用户提出一到四个多项选择题。1915向用户提出一到四个多选题。

1917 1916

1918| 字段 | 类型 | 示例 | 描述 |1917| 字段 | 类型 | 示例 | 描述 |

1919| :- | :- | :- | :- |1918| :- | :- | :- | :- |

1920| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false}]` | 要呈现的问题，每个问题包含一个 `question` 字符串、简短的 `header`、`options` 数组，以及可选的 `multiSelect` 标志 |1919| `questions` | array | `[{"question": "Which framework?", "header": "Framework", "options": [{"label": "React", "description": "Component library"}, {"label": "Vue", "description": "Progressive framework"}], "multiSelect": false}]` | 要呈现的问题，每个问题包含 `question` 字符串、简短的 `header`、`options` 数组以及可选的 `multiSelect` 标志 |

1921| `answers` | object | `{"Which framework?": "React"}` | 可选。将问题文本映射到所选选项的标签。多选答案以逗号连接标签。Claude 不会设置此字段；可通过 `updatedInput` 提供它以编程方式作答 |1920| `answers` | object | `{"Which framework?": "React"}` | 可选。将问题文本映射到所选选项的标签。多选答案用逗号连接各标签。Claude 不会设置此字段；如需以编程方式作答，请通过 `updatedInput` 提供 |

1922 1921

1923<h5 id="exitplanmode">1922<h5 id="exitplanmode">

1924 ExitPlanMode1923 ExitPlanMode

1925</h5>1924</h5>

1926 1925

1927在 Claude 离开[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)之前呈现计划并请求用户批准。Claude 会在调用该工具之前将计划写入磁盘上的文件，因此模型给出的原始 `tool_input` 通常为空。Claude Code 会在将输入传递给 hook 之前注入计划内容和文件路径。1926呈现一个计划，并在 Claude 离开[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)之前请求用户批准。Claude 在调用该工具之前会将计划写入磁盘上的文件，因此模型给出的原始 `tool_input` 通常为空。Claude Code 会在将输入传递给 hook 之前注入计划内容和文件路径。

1928 1927

1929| 字段 | 类型 | 示例 | 描述 |1928| 字段 | 类型 | 示例 | 描述 |

1930| :- | :- | :- | :- |1929| :- | :- | :- | :- |

1933| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | 已弃用。Claude Code 接受该字段但会忽略它。在 v2.1.205 之前，它携带 Claude 为实施计划而请求的基于提示词的权限 |1932| `allowedPrompts` | array | `[{"tool": "Bash", "prompt": "run tests"}]` | 已弃用。Claude Code 接受该字段但会忽略它。在 v2.1.205 之前，它携带 Claude 为实施计划而请求的基于提示词的权限 |

1934 1933

1935在 `PostToolUse` 中，`tool_response` 是一个对象，其中 `plan` 和 `filePath` 字段保存已批准的计划，另外还有内部状态标志。请读取 `tool_response.plan` 获取计划内容，而不要从磁盘重新读取文件。1934在 `PostToolUse` 中，`tool_response` 是一个对象，其 `plan` 和 `filePath` 字段包含已批准的计划，另外还有一些内部状态标志。请读取 `tool_response.plan` 获取计划内容，而不要从磁盘重新读取文件。

1936 1935

1937<h4 id="pretooluse-decision-control">1936<h4 id="pretooluse-decision-control">

1938 PreToolUse 决策控制1937 PreToolUse 决策控制

1939</h4>1938</h4>

1940 1939

1941`PreToolUse` hook 可以控制工具调用是否继续。与使用顶层 `decision` 字段的其他 hook 不同，PreToolUse 在 `hookSpecificOutput` 对象中返回其决策。这为其提供了更丰富的控制：四种结果（allow、deny、ask 或 defer），以及在执行前修改工具输入的能力。1940`PreToolUse` hook 可以控制工具调用是否继续。与使用顶层 `decision` 字段的其他 hook 不同，PreToolUse 在 `hookSpecificOutput` 对象中返回其决策。这为其提供了更丰富的控制能力：四种结果（允许、拒绝、询问或推迟），以及在执行前修改工具输入的能力。

1942 1941

1943| 字段 | 描述 |1942| 字段 | 描述 |

1944| :- | :- |1943| :- | :- |

1945| `permissionDecision` | `"allow"` 会跳过权限提示，但[任何模式都不会自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)以及 `AskUserQuestion` 和 `ExitPlanMode` 除外，后两者需要[与 `updatedInput` 搭配使用](#allow-with-updatedinput)。`"deny"` 会阻止工具调用。`"ask"` 会提示用户确认。`"defer"` 会正常退出，以便稍后恢复该工具。无论 hook 返回什么，[拒绝和询问规则](/docs/zh-CN/permissions#manage-permissions)仍会被评估 |1944| `permissionDecision` | `"allow"` 会跳过权限提示，但[任何模式都不会自动批准的操作](/docs/zh-CN/permission-modes#actions-no-mode-auto-approves)除外，`AskUserQuestion` 和 `ExitPlanMode` 也除外，它们需要[与 `updatedInput` 配合使用](#allow-with-updatedinput)。`"deny"` 会阻止工具调用。`"ask"` 会提示用户确认。`"defer"` 会正常退出，以便稍后恢复该工具。无论 hook 返回什么，[拒绝和询问规则](/docs/zh-CN/permissions#manage-permissions)仍会被评估 |

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

1947| `updatedInput` | 在执行前修改工具的输入参数。会替换整个输入对象，因此请将未更改的字段与修改后的字段一并包含。Claude Code 会针对您的 hook 返回的输入（而不是 Claude 发送的输入）评估权限规则以及 Bash 命令的[自动移至后台资格](/docs/zh-CN/tools-reference#foreground-commands-that-move-to-the-background)。与 `"allow"` 组合可自动批准，与 `"ask"` 组合可向用户显示修改后的输入。对于 `"defer"`，该字段被忽略 |1946| `updatedInput` | 在执行前修改工具的输入参数。会替换整个输入对象，因此请将未更改的字段与修改后的字段一并包含在内。Claude Code 会针对您的 hook 返回的输入（而不是 Claude 发送的输入）评估权限规则以及 Bash 命令的[自动转入后台资格](/docs/zh-CN/tools-reference#foreground-commands-that-move-to-the-background)。与 `"allow"` 结合可自动批准，与 `"ask"` 结合可向用户显示修改后的输入。对于 `"defer"` 会被忽略 |

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

1949 1948

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

1951 1950

1952通过以退出码 2 退出来阻止的 hook，其处理方式与 `"deny"` 相同：Claude 会将 stderr 消息视为拒绝原因。1951通过以 2 退出来阻止的 hook，其处理方式与 `"deny"` 相同：Claude 会将 stderr 消息视为拒绝原因。

1953 1952

1954当 hook 返回 `"ask"` 时，显示给用户的权限提示会包含一个标签，标明该 hook 的来源：来自任何设置文件或 Agent frontmatter 的 hook 标记为 `[settings]`，插件的 hook 标记为 `[plugin:<name>]`，来自 skill frontmatter 的 hook 标记为 `[skill]`。这有助于用户了解是哪个配置来源在请求确认。1953当 hook 返回 `"ask"` 时，向用户显示的权限提示中会包含一个标签，标明该 hook 的来源：来自任何设置文件或 Agent frontmatter 的 hook 为 `[settings]`，插件的 hook 为 `[plugin:<name>]`，来自 skill frontmatter 的 hook 为 `[skill]`。这有助于用户了解是哪个配置来源在请求确认。

1955 1954

1956hook 的 `"ask"` 在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中也会强制显示权限提示：分类器仍然可以拒绝该工具调用，但无法静默批准该调用。在 v2.1.211 之前，分类器可以批准在[沙箱](/docs/zh-CN/sandboxing)外运行的 Bash 命令，而不显示 hook 所请求的提示；分类器仍会对该命令应用其自身的安全规则，并且 hook 的 `"deny"` 始终会被遵守。1955hook 的 `"ask"` 在[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)中也会强制显示权限提示：分类器仍然可以拒绝该工具调用，但不能在不提示的情况下批准它。在 v2.1.211 之前，分类器可以在不显示 hook 所请求提示的情况下批准在[沙箱](/docs/zh-CN/sandboxing)外运行的 Bash 命令；分类器仍会对该命令应用其自身的安全规则，并且 hook 的 `"deny"` 始终会被遵守。

1957 1956

1958```json theme={null}1957```json theme={null}

1959{1958{

1970```1969```

1971 1970

1972<Note>1971<Note>

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

1974</Note>1973</Note>

1975 1974

1976<h4 id="allow-with-updatedinput">1975<h4 id="allow-with-updatedinput">

1977 需要用户交互的工具1976 需要用户交互的工具

1978</h4>1977</h4>

1979 1978

1980`AskUserQuestion` 和 `ExitPlanMode` 需要用户交互。在使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless)下，只有当运行具有接收提示的[权限宿主](/docs/zh-CN/headless#turn-off-permission-prompts-in-unattended-runs)（例如 Agent SDK 的 `canUseTool` 回调）时，Claude Code 才会提供它们。1979`AskUserQuestion` 和 `ExitPlanMode` 需要用户交互。在使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless)中，只有当运行具有可接收提示的[权限宿主](/docs/zh-CN/headless#turn-off-permission-prompts-in-unattended-runs)（例如 Agent SDK 的 `canUseTool` 回调）时，Claude Code 才会提供这些工具。

1981 1980

1982当 `PreToolUse` hook 执行以下操作时，即满足该要求：1981当 `PreToolUse` hook 执行以下操作时，即可满足该要求：

1983 1982

19841. 从 stdin 读取工具的输入19831. 从 stdin 读取工具的输入

19852. 通过您自己的 UI 收集答案19842. 通过您自己的 UI 收集答案

19863. 返回 `permissionDecision: "allow"` 以及包含答案的 `updatedInput`，使工具在不提示的情况下运行19853. 返回 `permissionDecision: "allow"`，并附带包含答案的 `updatedInput`，使工具无需提示即可运行

1987 1986

1988对于这些工具，仅返回 `"allow"` 是不够的。1987对于这些工具，仅返回 `"allow"` 是不够的。

1989 1988

1990对于 `AskUserQuestion`，请回传原始的 `questions` 数组，并添加一个 [`answers`](#askuserquestion) 对象，将每个问题的文本映射到所选答案。以下输出用 `React` 回答了一个问题：1989对于 `AskUserQuestion`，请原样回传原始的 `questions` 数组，并添加一个 [`answers`](#askuserquestion) 对象，将每个问题的文本映射到所选答案。以下输出用 `React` 回答了一个问题：

1991 1990

1992```json theme={null}1991```json theme={null}

1993{1992{

2009}2008}

2010```2009```

2011 2010

2012对于其服务器使用 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 标记的 MCP 工具，要求更为严格：hook 无法通过 `"allow"` 跳过其批准提示，无论是否带有 `updatedInput`，因为 Claude Code 无法确认 hook 是否收集了该工具所需的交互。2011其服务器使用 [`_meta["anthropic/requiresUserInteraction"]`](/docs/zh-CN/mcp#require-approval-for-a-specific-tool) 标记的 MCP 工具要求更严格：无论是否带有 `updatedInput`，hook 都无法通过 `"allow"` 跳过其批准提示，因为 Claude Code 无法确认 hook 已完成该工具所需的交互。

2013 2012

2014<h4 id="defer-a-tool-call-for-later">2013<h4 id="defer-a-tool-call-for-later">

2015 延迟工具调用以便稍后处理2014 推迟工具调用

2016</h4>2015</h4>

2017 2016

2018`"defer"` 适用于将 `claude -p` 作为子进程运行并读取其 JSON 输出的集成，例如 Agent SDK 应用或基于 Claude Code 构建的自定义 UI。它允许调用进程在工具调用处暂停 Claude，通过自己的界面收集输入，然后从中断处恢复。Claude Code 仅在使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless)下遵守此值。在交互式会话中，它会记录一条警告并忽略该 hook 结果。2017`"defer"` 适用于将 `claude -p` 作为子进程运行并读取其 JSON 输出的集成，例如 Agent SDK 应用或基于 Claude Code 构建的自定义 UI。它让调用进程能够在某个工具调用处暂停 Claude，通过自己的界面收集输入，然后从中断处继续。Claude Code 仅在使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless)中遵守此值。在交互式会话中，它会记录一条警告并忽略该 hook 结果。

2019 2018

2020`AskUserQuestion` 工具是典型场景：Claude 想向用户提问，但没有可以作答的终端。`-p` 运行只有在具有[权限宿主](/docs/zh-CN/headless#turn-off-permission-prompts-in-unattended-runs)（例如通过 `--permission-prompt-tool` 传入的 MCP 工具）时才会提供 `AskUserQuestion`，因此请使用权限宿主启动运行。完整的往返流程如下：2019`AskUserQuestion` 工具是典型场景：Claude 想向用户提问，但没有终端可供作答。`-p` 运行只有在具有[权限宿主](/docs/zh-CN/headless#turn-off-permission-prompts-in-unattended-runs)（例如您通过 `--permission-prompt-tool` 传入的 MCP 工具）时才会提供 `AskUserQuestion`，因此请带上一个权限宿主启动运行。整个往返流程如下：

2021 2020

20221. Claude 调用 `AskUserQuestion`。`PreToolUse` hook 触发。20211. Claude 调用 `AskUserQuestion`。`PreToolUse` hook 触发。

20232. hook 返回 `permissionDecision: "defer"`。工具不会执行。进程以 `stop_reason: "tool_deferred"` 退出，待处理的工具调用保留在会话记录中。20222. hook 返回 `permissionDecision: "defer"`。工具不执行。进程以 `stop_reason: "tool_deferred"` 退出，待处理的工具调用保留在会话记录中。

20243. 调用进程从 SDK 结果中读取 `deferred_tool_use`，在自己的 UI 中呈现问题，并等待答案。20233. 调用进程从 SDK 结果中读取 `deferred_tool_use`，在自己的 UI 中展示问题，并等待回答。

20254. 调用进程使用相同的权限宿主运行 `claude -p --resume <session-id>`。同一个工具调用会再次触发 `PreToolUse`。20244. 调用进程使用相同的权限宿主运行 `claude -p --resume <session-id>`。同一个工具调用再次触发 `PreToolUse`。

20265. hook 返回 `permissionDecision: "allow"`，并在 `updatedInput` 中提供答案。工具执行，Claude 继续。20255. hook 返回 `permissionDecision: "allow"`，并在 `updatedInput` 中附带答案。工具执行，Claude 继续。

2027 2026

2028`deferred_tool_use` 字段携带工具的 `id`、`name` 和 `input`。`input` 是 Claude 为该工具调用生成的参数，在执行之前捕获：2027`deferred_tool_use` 字段携带工具的 `id`、`name` 和 `input`。`input` 是 Claude 为该工具调用生成的参数，在执行前捕获：

2029 2028

2030```json theme={null}2029```json theme={null}

2031{2030{

2041}2040}

2042```2041```

2043 2042

2044没有超时或重试次数限制。会话会保留在磁盘上直到您恢复它，但受 [`cleanupPeriodDays`](/docs/zh-CN/settings-reference#cleanupperioddays) 保留期清理的约束，该清理默认在 30 天后删除会话文件，遵循[保留期清理规则](/docs/zh-CN/claude-directory#cleaned-up-automatically)。如果恢复时答案尚未就绪，hook 可以再次返回 `"defer"`，进程会以相同方式退出。调用进程通过最终从 hook 返回 `"allow"` 或 `"deny"` 来控制何时跳出该循环。2043没有超时或重试次数限制。会话会一直保留在磁盘上，直到您恢复它，但受 [`cleanupPeriodDays`](/docs/zh-CN/settings-reference#cleanupperioddays) 保留清理的约束，该清理默认会在 30 天后删除会话文件，并遵循[保留清理规则](/docs/zh-CN/claude-directory#cleaned-up-automatically)。如果恢复时答案尚未准备好，hook 可以再次返回 `"defer"`，进程会以相同方式退出。调用进程通过最终让 hook 返回 `"allow"` 或 `"deny"` 来控制何时结束循环。

2045 2044

2046`"defer"` 仅在 Claude 在该轮次中只进行单个工具调用时有效。如果 Claude 同时进行多个工具调用，`"defer"` 会被忽略并发出警告，工具将按正常权限流程继续。存在此限制是因为恢复时只能重新运行一个工具：无法在不让其他调用悬而未决的情况下延迟一批调用中的某一个。2045`"defer"` 仅在 Claude 在该轮次中只进行一次工具调用时有效。如果 Claude 同时进行多次工具调用，`"defer"` 会被忽略并发出警告，工具会经过正常的权限流程继续。存在此限制是因为恢复时只能重新运行一个工具：无法在推迟一批调用中的某一个的同时，不让其他调用处于未解决状态。

2047 2046

2048如果恢复时被延迟的工具已不可用，进程会在 hook 触发之前以 `stop_reason: "tool_deferred_unavailable"` 和 `is_error: true` 退出。当提供该工具的 MCP 服务器在恢复的会话中未连接时，就会发生这种情况。`deferred_tool_use` 数据仍会包含在内，以便您识别是哪个工具缺失了。2047如果恢复时被推迟的工具已不可用，进程会在 hook 触发之前以 `stop_reason: "tool_deferred_unavailable"` 和 `is_error: true` 退出。当提供该工具的 MCP 服务器在恢复的会话中未连接时，就会发生这种情况。`deferred_tool_use` 负载仍会包含在内，以便您确定缺失的是哪个工具。

2049 2048

2050<Note>2049<Note>

2051 要在计划模式下恢复被延迟的会话，请将 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 与 `--resume` 一起传入，以便 Claude Code 可以呈现计划供批准。如果您传入某些其他启动标志，恢复的运行不会返回计划模式；请参阅[使用 `-p` 在计划模式下恢复](/docs/zh-CN/sessions#resume-in-plan-mode-with-p)。需要 Claude Code v2.1.246 或更高版本。2050 要在计划模式下恢复被推迟的会话，请将 [`--permission-prompt-tool`](/docs/zh-CN/cli-reference#cli-flags) 与 `--resume` 一起传入，以便 Claude Code 可以呈现计划供批准。如果您传入了某些其他启动标志，恢复的运行将不会回到计划模式；请参阅[使用 `-p` 在计划模式下恢复](/docs/zh-CN/sessions#resume-in-plan-mode-with-p)。需要 Claude Code v2.1.246 或更高版本。

2052 2051

2053 当您使用 `-p` 恢复时，Claude Code 不会还原任何其他已存储的权限模式。它会以新的 `claude -p` 运行所使用的权限模式启动，因此如果被延迟的会话使用了 `--permission-mode` 或 `--dangerously-skip-permissions`，请再次传入。当您不带 `-p` 使用 `claude --resume <session-id>` 恢复时，Claude Code 会还原已存储的权限模式，但[恢复时的权限模式](/docs/zh-CN/sessions#permission-mode-on-resume)中列出的例外情况除外。2052 当您使用 `-p` 恢复时，Claude Code 不会还原任何其他已存储的权限模式。它会以新的 `claude -p` 运行所使用的权限模式启动，因此如果被推迟的会话使用了 `--permission-mode` 或 `--dangerously-skip-permissions`，请再次传入。当您不带 `-p` 使用 `claude --resume <session-id>` 恢复时，Claude Code 会还原已存储的权限模式，例外情况列于[恢复时的权限模式](/docs/zh-CN/sessions#permission-mode-on-resume)中。

2054</Note>2053</Note>

2055 2054

2056<h3 id="permissionrequest">2055<h3 id="permissionrequest">

2057 PermissionRequest2056 PermissionRequest

2058</h3>2057</h3>

2059 2058

2060在 Claude Code 即将请求您授予使用某个工具的权限时运行。在无法显示提示的会话中，例如[非交互模式](/docs/zh-CN/headless)下的后台子代理，Claude Code 仍会运行这些 hook，如果没有 hook 返回决策，它会拒绝该工具调用。对于到达 `--permission-prompt-tool` 或 Agent SDK 的 [`canUseTool` 回调](/docs/zh-CN/agent-sdk/permissions)的调用，hook 会与您的宿主并行运行，以先做出决策者为准。2059在 Claude Code 即将向您请求使用某个工具的权限时运行。在无法显示提示的会话中，例如[非交互模式](/docs/zh-CN/headless)下的后台子代理，Claude Code 仍会运行这些 hook，如果没有 hook 返回决策，它会拒绝该工具调用。对于到达 `--permission-prompt-tool` 或 Agent SDK 的 [`canUseTool` 回调](/docs/zh-CN/agent-sdk/permissions)的调用，hook 会与您的宿主并行运行，以先做出决策者为准。

2061使用 [PermissionRequest 决策控制](#permissionrequest-decision-control)代表用户允许或拒绝。2060使用 [PermissionRequest 决策控制](#permissionrequest-decision-control)代表用户允许或拒绝。

2062 2061

2063当您需要在 Claude 请求使用工具的权限时立即获得信号，请使用此事件。Claude Code 仅在提示等待约六秒后才会运行 `permission_prompt` 类型的 [Notification](#notification) hook。2062当您需要在 Claude 请求使用工具权限的那一刻获得信号时，请使用此事件。Claude Code 只有在提示已等待约六秒后，才会运行 `permission_prompt` 类型的 [Notification](#notification) hook。

2064 2063

2065对于沙箱中命令的[网络请求](/docs/zh-CN/sandboxing#network-isolation)，Claude Code 不会运行 PermissionRequest hook。要获得该提示的信号，请使用 `permission_prompt` 通知类型。2064对于沙箱中命令的[网络请求](/docs/zh-CN/sandboxing#network-isolation)，Claude Code 不会运行 PermissionRequest hook。要获取该提示的信号，请使用 `permission_prompt` 通知类型。

2066 2065

2067针对工具名称进行匹配，取值与 PreToolUse 相同。2066按工具名称匹配，取值与 PreToolUse 相同。

2068 2067

2069<h4 id="permissionrequest-input">2068<h4 id="permissionrequest-input">

2070 PermissionRequest 输入2069 PermissionRequest 输入

2071</h4>2070</h4>

2072 2071

2073PermissionRequest hook 会像 PreToolUse hook 一样接收 `tool_name` 和 `tool_input` 字段，但没有 `tool_use_id`。对于 MCP 工具，它们还会接收 [`mcp_server`](#pretooluse-input) 对象。可选的 `permission_suggestions` 数组包含 Claude Code 针对此请求建议的[权限更新](#permission-update-entries)，例如添加允许规则或更改权限模式。2072PermissionRequest hook 与 PreToolUse hook 一样接收 `tool_name` 和 `tool_input` 字段，但没有 `tool_use_id`。对于 MCP 工具，它们还会接收 [`mcp_server`](#pretooluse-input) 对象。可选的 `permission_suggestions` 数组包含 Claude Code 针对此请求建议的[权限更新](#permission-update-entries)，例如添加允许规则或更改权限模式。

2074 2073

2075`permission_suggestions` 数组并不是您所看到选项的精确列表，因为每个权限对话框都会构建自己的选项。有些对话框（例如用于文件编辑的对话框）根本不读取该数组，而是从请求本身派生其选项。读取该数组的对话框仍可能隐藏某个建议仍保留在数组中的选项，例如当 [`allowManagedPermissionRulesOnly`](/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly) 隐藏保存规则的选项时。它也可能提供没有对应建议条目的选项，例如 [**Yes, and switch to auto mode**](/docs/zh-CN/permission-modes#switch-permission-modes)，它直接更改权限模式，而不是通过权限更新。2074`permission_suggestions` 数组并不是您所看到选项的精确列表，因为每个权限对话框都会构建自己的选项。某些对话框（例如文件编辑的对话框）根本不读取该数组，而是根据请求本身得出选项。读取该数组的对话框仍可能隐藏某个建议仍保留在数组中的选项，例如当 [`allowManagedPermissionRulesOnly`](/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly) 隐藏保存规则的选项时。它也可能提供没有对应建议条目的选项，例如 [**Yes, and switch to auto mode**](/docs/zh-CN/permission-modes#switch-permission-modes)，该选项直接更改权限模式，而不是通过权限更新。

2076 2075

2077PreToolUse hook 在每次工具调用之前运行，无论是否需要权限。PermissionRequest hook 仅在 Claude Code 即将向您请求权限时运行，或在它原本会自动拒绝无法提示的调用时运行。这两个事件都不会为 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 触发。2076PreToolUse hook 在每次工具调用之前运行，无论该调用是否需要权限。PermissionRequest hook 仅在 Claude Code 即将向您请求权限时，或者在它原本会自动拒绝一个无法提示的调用时运行。这两个事件都不会为 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior) 触发。

2078 2077

2079```json theme={null}2078```json theme={null}

2080{2079{

2103 PermissionRequest 决策控制2102 PermissionRequest 决策控制

2104</h4>2103</h4>

2105 2104

2106`PermissionRequest` hook 可以允许或拒绝权限请求。除了所有 hook 都可用的 [JSON 输出字段](#json-output)之外，您的 hook 脚本还可以返回一个包含以下特定于事件字段的 `decision` 对象：2105`PermissionRequest` hook 可以允许或拒绝权限请求。除所有 hook 都可用的 [JSON 输出字段](#json-output)外，您的 hook 脚本还可以返回一个包含以下事件专属字段的 `decision` 对象：

2107 2106

2108| 字段 | 描述 |2107| 字段 | 描述 |

2109| :- | :- |2108| :- | :- |

2110| `behavior` | `"allow"` 授予权限，`"deny"` 拒绝权限。[拒绝和询问规则](/docs/zh-CN/permissions#manage-permissions)仍会被评估，因此返回 `"allow"` 的 hook 不会覆盖匹配的拒绝规则 |2109| `behavior` | `"allow"` 授予权限，`"deny"` 拒绝权限。[拒绝和询问规则](/docs/zh-CN/permissions#manage-permissions)仍会被评估，因此返回 `"allow"` 的 hook 不会覆盖匹配的拒绝规则 |

2115 2114

2116以退出码 2 退出但没有 `decision` 对象的 hook 不会改变权限流程，其 stderr 会被丢弃。只有 `decision` 对象才能授予或拒绝请求。2115以 2 退出但不带 `decision` 对象的 hook 不会改变权限流程，其 stderr 会被丢弃。只有 `decision` 对象才能授予或拒绝请求。

2117 2116

2118```json theme={null}2117```json theme={null}

2119{2118{

2133 权限更新条目2132 权限更新条目

2134</h4>2133</h4>

2135 2134

2136`updatedPermissions` 输出字段和 [`permission_suggestions` 输入字段](#permissionrequest-input)都使用相同的条目对象数组。每个条目都有一个决定其其他字段的 `type`，以及一个控制更改写入位置的 `destination`。2135`updatedPermissions` 输出字段和 [`permission_suggestions` 输入字段](#permissionrequest-input)都使用相同的条目对象数组。每个条目都有一个 `type`，它决定该条目的其他字段；还有一个 `destination`，它控制更改写入的位置。

2137 2136

2138| `type` | 字段 | 效果 |2137| `type` | 字段 | 效果 |

2139| :- | :- | :- |2138| :- | :- | :- |

2140| `addRules` | `rules`、`behavior`、`destination` | 添加权限规则。`rules` 是 `{toolName, ruleContent?}` 对象的数组。省略 `ruleContent` 可匹配整个工具。`behavior` 为 `"allow"`、`"deny"` 或 `"ask"` |2139| `addRules` | `rules`、`behavior`、`destination` | 添加权限规则。`rules` 是由 `{toolName, ruleContent?}` 对象组成的数组。省略 `ruleContent` 即匹配整个工具。`behavior` 为 `"allow"`、`"deny"` 或 `"ask"` |

2146 2145

2147<Note>2146<Note>

2148 只有当您启动会话时已经可以使用绕过模式，`setMode` 配合 `bypassPermissions` 才会生效：即使用了 `--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions`，或在[用户设置、`--settings` 或托管设置](/docs/zh-CN/settings-reference#permissions-defaultmode)中设置了 `permissions.defaultMode: "bypassPermissions"`。否则该更新不产生任何效果。当 [`permissions.disableBypassPermissionsMode`](/docs/zh-CN/permissions#managed-settings) 禁用了该模式，或会话以[受限模式](/docs/zh-CN/cli-reference#cli-flags)启动时，该更新同样不产生任何效果。2147 仅当您启动会话时 bypass 模式已可用，`setMode` 设为 `bypassPermissions` 才会生效：即使用了 `--dangerously-skip-permissions`、`--permission-mode bypassPermissions`、`--allow-dangerously-skip-permissions`，或在[用户设置、`--settings` 或托管设置](/docs/zh-CN/settings-reference#permissions-defaultmode)中设置了 `permissions.defaultMode: "bypassPermissions"`。否则该更新不起任何作用。当 [`permissions.disableBypassPermissionsMode`](/docs/zh-CN/permissions#managed-settings) 禁用了该模式，或会话以[受限模式](/docs/zh-CN/cli-reference#cli-flags)启动时，该更新同样不起作用。

2149 2148

2150 无论 `destination` 为何值，`bypassPermissions` 都不会被持久化为 `defaultMode`。2149 无论 `destination` 为何值，`bypassPermissions` 都不会被持久化为 `defaultMode`。

2151</Note>2150</Note>

2152 2151

2153每个条目上的 `destination` 字段决定该更改是仅保留在内存中，还是持久化到设置文件。2152每个条目上的 `destination` 字段决定更改是仅保留在内存中，还是持久化到设置文件。

2154 2153

2156| :- | :- |2155| :- | :- |

2169 2168

2170按工具名称匹配，取值与 PreToolUse 相同。2169按工具名称匹配，取值与 PreToolUse 相同。

2171 2170

2172当工具名称不是合适的过滤条件时，可以进行更宽泛的匹配：2171当工具名称不是合适的过滤条件时，可以更宽泛地匹配：

2173 2172

2174* 要在任意工具成功完成后运行 hook，请省略 `matcher` 或将其设为 `"*"`。然后您的 hook 可以自行发现发生了哪些更改，例如运行 `git status --porcelain`，它还会列出 `git diff` 遗漏的未跟踪文件。对于失败的工具调用，请在 [PostToolUseFailure](#posttoolusefailure) 下添加相同的 hook。2173* 要在任何工具成功完成后运行 hook，请省略 `matcher` 或将其设为 `"*"`。然后您的 hook 可以自行发现发生了哪些更改，例如运行 `git status --porcelain`，它还会列出 `git diff` 遗漏的未跟踪文件。对于失败的工具调用，请在 [PostToolUseFailure](#posttoolusefailure) 下添加相同的 hook。

2175* 要在特定文件在磁盘上发生更改时运行 hook（无论是由什么写入的），请使用 [FileChanged](#filechanged)。当 `Bash` 命令或 Claude Code 之外的进程重写同一文件时，Claude Code 不会运行匹配 `Edit|Write` 的 `PostToolUse` hook。2174* 要在特定文件在磁盘上发生更改时运行 hook（无论由谁写入），请使用 [FileChanged](#filechanged)。当 `Bash` 命令或 Claude Code 之外的进程重写同一文件时，Claude Code 不会运行匹配 `Edit|Write` 的 `PostToolUse` hook。

2176 2175

2177<h4 id="posttooluse-input">2176<h4 id="posttooluse-input">

2178 PostToolUse 输入2177 PostToolUse 输入

2179</h4>2178</h4>

2180 2179

2181`PostToolUse` hook 在工具已成功执行后触发。输入同时包含 `tool_input`（发送给工具的参数）和 `tool_response`（工具返回的结果）。两者的确切 schema 取决于具体工具。文件工具的 `tool_input` 路径格式与 [PreToolUse](#pretooluse-input) 相同：始终为绝对路径，使用平台原生分隔符，因此在 Windows 上为反斜杠。对于 MCP 工具，输入还会携带 [`mcp_server`](#pretooluse-input) 对象。2180`PostToolUse` hook 在工具已成功执行后触发。输入同时包含 `tool_input`（发送给工具的参数）和 `tool_response`（工具返回的结果）。两者的确切 schema 取决于具体工具。文件类工具的 `tool_input` 路径格式与 [PreToolUse](#pretooluse-input) 相同：始终为绝对路径，使用平台原生分隔符，因此在 Windows 上为反斜杠。对于 MCP 工具，输入还包含 [`mcp_server`](#pretooluse-input) 对象。

2182 2181

2183```json theme={null}2182```json theme={null}

2184{2183{

2203 2202

2204| 字段 | 描述 |2203| 字段 | 描述 |

2205| :- | :- |2204| :- | :- |

2207 2206

2208<h4 id="posttooluse-decision-control">2207<h4 id="posttooluse-decision-control">

2209 PostToolUse 决策控制2208 PostToolUse 决策控制

2210</h4>2209</h4>

2211 2210

2212`PostToolUse` hook 可以在工具执行后向 Claude 提供反馈。除了所有 hook 都可用的 [JSON 输出字段](#json-output)之外，您的 hook 脚本还可以返回以下特定于事件的字段：2211`PostToolUse` hook 可以在工具执行后向 Claude 提供反馈。除了所有 hook 均可使用的 [JSON 输出字段](#json-output)外，您的 hook 脚本还可以返回以下事件特定字段：

2213 2212

2214| 字段 | 描述 |2213| 字段 | 描述 |

2215| :- | :- |2214| :- | :- |

2219| `classifierContext` | 关于本次调用结果的简短说明，供[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器而非 Claude 使用。请参阅[为自动模式分类器注释结果](#annotate-a-result-for-the-auto-mode-classifier)。需要 Claude Code v2.1.236 或更高版本 |2218| `classifierContext` | 关于此次调用结果的简短说明，提供给[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器而非 Claude。请参阅[为自动模式分类器注释结果](#annotate-a-result-for-the-auto-mode-classifier)。需要 Claude Code v2.1.236 或更高版本 |

2222 2221

2238```2237```

2239 2238

2240<Warning>2239<Warning>

2241 `updatedToolOutput` 只会改变 Claude 看到的内容。hook 触发时工具已经运行，因此任何已写入的文件、已执行的命令或已发送的网络请求都已生效。OpenTelemetry 工具 span 和分析事件等遥测数据也会在 hook 运行之前捕获原始输出。要在工具调用运行之前阻止或修改它，请改用 [PreToolUse](#pretooluse) hook。2240 `updatedToolOutput` 只会改变 Claude 看到的内容。hook 触发时工具已经运行完毕，因此任何已写入的文件、已执行的命令或已发送的网络请求都已生效。诸如 OpenTelemetry 工具 span 和分析事件之类的遥测数据也会在 hook 运行之前捕获原始输出。要在工具调用运行之前阻止或修改它，请改用 [PreToolUse](#pretooluse) hook。

2242 2241

2243 替换值必须与工具的输出结构相匹配。内置工具返回的是结构化对象，而不是纯字符串。例如，`Bash` 返回一个包含 `stdout`、`stderr`、`interrupted` 和 `isImage` 字段的对象。对于内置工具，与工具输出 schema 不匹配的值会被忽略，并使用原始输出。MCP 工具的输出会直接传递，不进行 schema 验证。删除 Claude 需要的错误详细信息可能会导致它基于错误的假设继续执行。2242 替换值必须与工具的输出结构相匹配。内置工具返回的是结构化对象，而非纯字符串。例如，`Bash` 返回一个包含 `stdout`、`stderr`、`interrupted` 和 `isImage` 字段的对象。对于内置工具，与工具输出 schema 不匹配的值会被忽略，并使用原始输出。MCP 工具的输出会直接传递，不进行 schema 验证。删除 Claude 所需的错误详情可能会导致它基于错误的假设继续操作。

2244</Warning>2243</Warning>

2245 2244

2246<h4 id="annotate-a-result-for-the-auto-mode-classifier">2245<h4 id="annotate-a-result-for-the-auto-mode-classifier">

2247 为自动模式分类器注释结果2246 为自动模式分类器注释结果

2248</h4>2247</h4>

2249 2248

2250返回 `classifierContext`，可以将关于工具调用结果的简短说明发送给[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器，而不是发送给 Claude。分类器[从不接收工具结果本身](/docs/zh-CN/permission-modes#how-the-classifier-evaluates-actions)，因此该字段是在分类器审查后续操作之前，告知它某次调用返回内容的受支持方式。该字段需要 Claude Code v2.1.236 或更高版本。2249返回 `classifierContext`，即可将关于工具调用结果的简短说明发送给[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)分类器，而不是发送给 Claude。分类器[从不接收工具结果本身](/docs/zh-CN/permission-modes#how-the-classifier-evaluates-actions)，因此在它审查后续操作之前，此字段是告知它某次调用返回内容的受支持方式。该字段需要 Claude Code v2.1.236 或更高版本。

2251 2250

2252以下示例告诉分类器某次查询的输出来自何处：2251以下示例告知分类器某个查询输出的来源：

2253 2252

2254```json theme={null}2253```json theme={null}

2255{2254{

2260}2259}

2261```2260```

2262 2261

2263分类器对该说明的重视程度取决于您在何处配置了该 hook：2262分类器对该说明的重视程度取决于您配置 hook 的位置：

2264 2263

2265* **在 Claude Code 中配置的 hook**：对于来自设置文件、插件、skill 和 Agent frontmatter 的 hook，分类器将该说明视为未经验证的、由应用程序提供的上下文。该说明永远不能确立用户意图；如果它声称您批准或请求了某事，分类器会将该声明与您在对话中发送的消息进行核对2264* **在 Claude Code 中配置的 hook**：对于来自设置文件、插件、skill 和 Agent frontmatter 的 hook，分类器将该说明视为未经验证的、由应用程序提供的上下文。该说明永远不能确立用户意图；如果它声称您批准或请求了某事，分类器会将该声明与您在对话中发送的消息进行核对

2266* **进程内 Agent SDK 回调**：当嵌入 Claude Code 的应用程序将该 hook 注册为 [TypeScript SDK 回调](/docs/zh-CN/agent-sdk/hooks)并在实时会话期间返回该说明时，分类器可能会将说明中转述的用户陈述视为用户意图。此类陈述可以满足分类器原本会从您发送的消息中接受的同意要求，但它永远不能解除您自己的消息也无法解除的阻止。会话恢复后，Claude Code 会将恢复的说明视为未经验证的上下文。当两类 hook 都对同一调用添加注释时，分类器会将合并后的说明视为未经验证的内容2265* **进程内 Agent SDK 回调**：当嵌入 Claude Code 的应用程序将 hook 注册为 [TypeScript SDK 回调](/docs/zh-CN/agent-sdk/hooks)，并在实时会话期间返回该说明时，分类器可能会将说明中转述的用户陈述视为用户意图。这样的陈述可以满足分类器本会从您发送的消息中接受的同意要求，但它永远不能解除您自己的消息也无法解除的阻止。会话恢复后，Claude Code 会将恢复的说明视为未经验证的上下文。当两组中的 hook 都对同一调用进行注释时，分类器会将合并后的说明视为未经验证的内容

2267 2266

2268Claude Code 在传递说明时会应用以下限制：2267Claude Code 在传递该说明时会应用以下限制：

2269 2268

2270* **长度**：Claude Code 将单次工具调用的说明上限设为 2,000 个字符，并截断其余部分。该上限由响应该调用的所有 hook 共享2269* **长度**：Claude Code 将单次工具调用的说明上限设为 2,000 个字符，并截断其余部分。该上限由响应该调用的所有 hook 共享

2271* **仅限同步响应**：对于[在后台运行](#run-hooks-in-the-background)的 hook，Claude Code 会忽略其响应中的该字段，因为该响应在 Claude Code 记录工具结果之后才到达2270* **仅限同步响应**：对于[在后台运行](#run-hooks-in-the-background)的 hook，Claude Code 会忽略其响应中的该字段，因为该响应在 Claude Code 记录工具结果之后才到达

2272* **分类器不记录的调用**：分类器的会话记录会省略只读查找，例如文件读取和搜索。附加到这些调用上的说明会被 Claude Code 丢弃2271* **分类器不记录的调用**：分类器的会话记录会省略只读查找，例如文件读取和搜索。Claude Code 会丢弃附加在这类调用上的说明

2273* **与重写的交互**：当说明描述的是您正在用 `updatedToolOutput` 替换的输出时，请在同一个 hook 响应中同时返回这两个字段。如果该重写被拒绝或被另一个 hook 的重写替换，Claude Code 会丢弃该说明。即使另一个 hook 重写了输出，Claude Code 仍会传递您在没有重写的情况下返回的说明2272* **与重写的交互**：当说明描述的是您要用 `updatedToolOutput` 替换的输出时，请在同一个 hook 响应中返回这两个字段。如果该重写被拒绝，或被另一个 hook 的重写替换，Claude Code 会丢弃该说明。即使另一个 hook 重写了输出，Claude Code 仍会传递您在没有重写的情况下返回的说明

2274 2273

2275<Warning>2274<Warning>

2276 分类器会将您放入 `classifierContext` 的内容视为来自托管该会话的应用程序的信息，因此请勿将不受信任的工具输出或第三方文本复制到其中。请将说明限定为关于这一次调用的简短断言，例如关于其来源的事实或用户对它的陈述；不要使用该字段传递无关消息或事件流。2275 分类器会将您放入 `classifierContext` 的内容视为来自托管该会话的应用程序的信息，因此不要将不受信任的工具输出或第三方文本复制到其中。请将说明保持为关于这一次调用的简短断言，例如关于其来源的事实或用户对其的陈述；不要使用该字段传递无关消息或事件流。

2277</Warning>2276</Warning>

2278 2277

2279<h3 id="posttoolusefailure">2278<h3 id="posttoolusefailure">

2280 PostToolUseFailure2279 PostToolUseFailure

2281</h3>2280</h3>

2282 2281

2283当已开始执行的工具失败时运行：工具抛出了错误，或 MCP 工具返回了错误结果。可用于记录失败、发送警报或向 Claude 提供纠正性反馈。2282当已开始执行的工具失败时运行：工具抛出错误，或 MCP 工具返回错误结果。可用于记录失败、发送警报或向 Claude 提供纠正性反馈。

2284 2283

2285按工具名称匹配，取值与 PreToolUse 相同。2284按工具名称匹配，取值与 PreToolUse 相同。

2286 2285

2287<Note>2286<Note>

2288 对于在执行前被拒绝的工具调用，此事件不会触发：包括未知的工具名称、未通过 schema 或工具特定验证的输入，以及权限拒绝。验证拒绝会以 `tool_use_error` 结果返回，并且发生在 hook 运行之前，因此既不会触发 `PreToolUse`，也不会触发 `PostToolUseFailure`。权限拒绝会触发 `PreToolUse`，但不会触发此事件；请参阅 [PermissionDenied](#permissiondenied)。2287 对于在执行前被拒绝的工具调用，此事件不会触发：未知的工具名称、未通过 schema 或工具特定验证的输入，或权限拒绝。验证拒绝会作为 `tool_use_error` 结果返回，且发生在 hook 运行之前，因此既不会触发 `PreToolUse`，也不会触发 `PostToolUseFailure`。权限拒绝会触发 `PreToolUse`，但不会触发此事件；请参阅 [PermissionDenied](#permissiondenied)。

2289</Note>2288</Note>

2290 2289

2291<h4 id="posttoolusefailure-input">2290<h4 id="posttoolusefailure-input">

2292 PostToolUseFailure 输入2291 PostToolUseFailure 输入

2293</h4>2292</h4>

2294 2293

2295PostToolUseFailure hook 接收与 PostToolUse 相同的 `tool_name` 和 `tool_input` 字段，以及作为顶层字段的错误信息。对于 MCP 工具，它们还会接收 [`mcp_server`](#pretooluse-input) 对象。例如，一次失败的 `npm test` 命令可能会传递：2294PostToolUseFailure hook 接收与 PostToolUse 相同的 `tool_name` 和 `tool_input` 字段，以及作为顶层字段的错误信息。对于 MCP 工具，它们还会接收 [`mcp_server`](#pretooluse-input) 对象。例如，一个失败的 `npm test` 命令可能会传递：

2296 2295

2297```json theme={null}2296```json theme={null}

2298{2297{

2315 2314

2316| 字段 | 描述 |2315| 字段 | 描述 |

2317| :- | :- |2316| :- | :- |

2321 2320

2322`error` 字符串通常与 Claude 作为失败工具结果收到的文本相同。其格式因工具和失败类型而异。请让您的 hook 基于 `tool_name`、`is_interrupt` 以及第一行的 `Exit code N` 进行判断；将字符串的其余部分视为显示文本，而非稳定的格式。2321`error` 字符串通常与 Claude 作为失败工具结果收到的文本相同。其格式因工具和失败情况而异。请让您的 hook 依据 `tool_name`、`is_interrupt` 以及 `Exit code N` 首行进行判断；将字符串的其余部分视为显示文本，而非稳定格式。

2323 2322

2324* 对于 Bash 和 PowerShell，已运行并退出的命令会生成第一行 `Exit code N`，随后是命令产生的所有输出，作为一个整体块，其中 stdout 和 stderr 交错排列2323* 对于 Bash 和 PowerShell，已运行并退出的命令会产生首行 `Exit code N`，随后是命令产生的所有输出，stdout 和 stderr 交错合并为一个块

2325* 当 Claude Code 无法启动 shell 进程本身时，负载也可能只携带一条没有退出码行的失败消息2324* 当 Claude Code 无法启动 shell 进程本身时，数据中也可能只携带一条不含退出码行的失败消息

2326* Claude Code 会对长字符串进行中间截断，并插入 `... [N characters truncated] ...` 标记，还可能插入自己的行，例如 `Command timed out after 2m 0s`2325* Claude Code 会在 `... [N characters truncated] ...` 标记周围对长字符串进行中间截断，并可能插入其自身的行，例如 `Command timed out after 2m 0s`

2327 2326

2328<h4 id="posttoolusefailure-decision-control">2327<h4 id="posttoolusefailure-decision-control">

2329 PostToolUseFailure 决策控制2328 PostToolUseFailure 决策控制

2330</h4>2329</h4>

2331 2330

2332`PostToolUseFailure` hook 可以在工具失败后向 Claude 提供上下文。除了所有 hook 都可用的 [JSON 输出字段](#json-output)之外，您的 hook 脚本还可以返回以下特定于事件的字段：2331`PostToolUseFailure` hook 可以在工具失败后向 Claude 提供上下文。除了所有 hook 均可使用的 [JSON 输出字段](#json-output)外，您的 hook 脚本还可以返回以下事件特定字段：

2333 2332

2334| 字段 | 描述 |2333| 字段 | 描述 |

2335| :- | :- |2334| :- | :- |

2348 PostToolBatch2347 PostToolBatch

2349</h3>2348</h3>

2350 2349

2351在一批中的每个工具调用都已完成后、Claude Code 向模型发送下一个请求之前运行一次。`PostToolUse` 对每个工具触发一次，这意味着当 Claude 进行并行工具调用时它会并发触发。`PostToolBatch` 针对整个批次只触发一次，因此适合注入依赖于已运行工具集合而非单个工具的上下文。此事件没有匹配器。2350在一批工具调用全部完成后运行一次，时机在 Claude Code 向模型发送下一个请求之前。`PostToolUse` 对每个工具触发一次，这意味着当 Claude 进行并行工具调用时它会并发触发。`PostToolBatch` 针对整批调用恰好触发一次，因此适合注入依赖于所运行工具集合（而非任何单个工具）的上下文。此事件没有匹配器。

2352 2351

2353<h4 id="posttoolbatch-input">2352<h4 id="posttoolbatch-input">

2354 PostToolBatch 输入2353 PostToolBatch 输入

2355</h4>2354</h4>

2356 2355

2357除了[通用输入字段](#common-input-fields)之外，PostToolBatch hook 还会接收 `tool_calls`，这是一个描述批次中每个工具调用的数组：2356除了[通用输入字段](#common-input-fields)外，PostToolBatch hook 还会接收 `tool_calls`，这是一个描述该批次中每个工具调用的数组：

2358 2357

2359```json theme={null}2358```json theme={null}

2360{2359{

2380}2379}

2381```2380```

2382 2381

2383`tool_response` 包含的内容与模型在对应 `tool_result` 块中收到的内容相同。该值是序列化字符串或内容块数组，与工具发出的完全一致。对于 `Read`，这意味着是带行号前缀的文本，而不是原始文件内容。响应可能很大，因此请只解析您需要的字段。2382`tool_response` 包含模型在对应 `tool_result` 块中收到的相同内容。该值是序列化字符串或内容块数组，与工具发出的完全一致。对于 `Read`，这意味着它是带行号前缀的文本，而不是原始文件内容。响应可能很大，因此只解析您需要的字段。

2384 2383

2385<Note>2384<Note>

2386 `tool_response` 的结构与 `PostToolUse` 的不同。`PostToolUse` 传递的是工具的结构化 `Output` 对象，例如 `Write` 的 `{filePath: "...", type: "create"}`；`PostToolBatch` 传递的是模型看到的序列化 `tool_result` 内容。2385 `tool_response` 的结构与 `PostToolUse` 的不同。`PostToolUse` 传递的是工具的结构化 `Output` 对象，例如 `Write` 的 `{filePath: "...", type: "create"}`；`PostToolBatch` 传递的是模型看到的序列化 `tool_result` 内容。

2390 PostToolBatch 决策控制2389 PostToolBatch 决策控制

2391</h4>2390</h4>

2392 2391

2393`PostToolBatch` hook 可以为 Claude 注入上下文。除了所有 hook 都可用的 [JSON 输出字段](#json-output)之外，您的 hook 脚本还可以返回以下特定于事件的字段：2392`PostToolBatch` hook 可以为 Claude 注入上下文。除了所有 hook 均可使用的 [JSON 输出字段](#json-output)外，您的 hook 脚本还可以返回以下事件特定字段：

2394 2393

2395| 字段 | 描述 |2394| 字段 | 描述 |

2396| :- | :- |2395| :- | :- |

2398 2397

2399```json theme={null}2398```json theme={null}

2400{2399{

2405}2404}

2406```2405```

2407 2406

2408返回 `decision: "block"` 或 `continue: false` 会在下一次模型调用之前停止智能体循环。阻止消息来自 JSON 中的 `reason` 或 `stopReason`，或退出码 2 时的 stderr。您会在会话记录中看到它显示为警告，并且它会保留在对话中，因此当对话继续时 Claude 会看到它。2407返回 `decision: "block"` 或 `continue: false` 会在下一次模型调用之前停止智能体循环。阻止消息来自 JSON 中的 `reason` 或 `stopReason`，或在退出码为 2 时来自 stderr。您会在会话记录中看到一条警告，并且它会保留在对话中，因此对话继续时 Claude 也能看到它。

2409 2408

2410<h3 id="permissiondenied">2409<h3 id="permissiondenied">

2411 PermissionDenied2410 PermissionDenied

2412</h3>2411</h3>

2413 2412

2414当[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)拒绝工具调用时运行，包括在没有分类器判定的情况下拒绝——原因是[独立于自动模式的安全检查拒绝了分类器自身的请求](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)，或其响应无法解析。此 hook 仅在自动模式下触发：当您手动拒绝权限对话框、`PreToolUse` hook 阻止调用或 `deny` 规则匹配时，它不会运行。可用于记录拒绝、调整配置，或告诉模型它可以重试该工具调用。2413当[自动模式](/docs/zh-CN/permission-modes#eliminate-prompts-with-auto-mode)拒绝工具调用时运行，包括在没有分类器裁定的情况下拒绝的情形，原因可能是[独立于自动模式的安全检查拒绝了分类器自身的请求](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)，或分类器的响应无法解析。此 hook 仅在自动模式下触发：当您手动拒绝权限对话框、`PreToolUse` hook 阻止调用或 `deny` 规则匹配时，它不会运行。可用于记录拒绝情况、调整配置，或告知模型可以重试该工具调用。

2415 2414

2416按工具名称匹配，取值与 PreToolUse 相同。2415按工具名称匹配，取值与 PreToolUse 相同。

2417 2416

2419 PermissionDenied 输入2418 PermissionDenied 输入

2420</h4>2419</h4>

2421 2420

2422除了[通用输入字段](#common-input-fields)之外，PermissionDenied hook 还会接收 `tool_name`、`tool_input`、`tool_use_id` 和 `reason`。对于 MCP 工具，它们还会接收 [`mcp_server`](#pretooluse-input) 对象。2421除了[通用输入字段](#common-input-fields)外，PermissionDenied hook 还会接收 `tool_name`、`tool_input`、`tool_use_id` 和 `reason`。对于 MCP 工具，它们还会接收 [`mcp_server`](#pretooluse-input) 对象。

2423 2422

2424```json theme={null}2423```json theme={null}

2425{2424{

2440 2439

2441| 字段 | 描述 |2440| 字段 | 描述 |

2442| :- | :- |2441| :- | :- |

2443| `reason` | 拒绝原因。对于分类器判定，在大多数会话中它会用方括号标出匹配的规则，例如 `[Data Exfiltration]`；其他形式请参阅[查看拒绝](/docs/zh-CN/auto-mode-config#review-denials)。对于[无判定拒绝](#permissiondenied-decision-control)，它以 `Auto mode could not evaluate this action and is blocking it for safety` 开头。对于因分类器模型不可用而导致的拒绝，它是固定文本 `Classifier unavailable` |2442| `reason` | 拒绝原因。对于分类器裁定，在大多数会话中它会用方括号注明所匹配的规则，例如 `[Data Exfiltration]`；其他形式请参阅[审查拒绝](/docs/zh-CN/auto-mode-config#review-denials)。对于[无裁定拒绝](#permissiondenied-decision-control)，它以 `Auto mode could not evaluate this action and is blocking it for safety` 开头。对于因分类器模型不可用而产生的拒绝，它是固定文本 `Classifier unavailable` |

2444 2443

2445<h4 id="permissiondenied-decision-control">2444<h4 id="permissiondenied-decision-control">

2446 PermissionDenied 决策控制2445 PermissionDenied 决策控制

2447</h4>2446</h4>

2448 2447

2449PermissionDenied hook 可以告诉模型它可以重试被拒绝的工具调用。返回一个 `hookSpecificOutput.retry` 设为 `true` 的 JSON 对象：2448PermissionDenied hook 可以告知模型可以重试被拒绝的工具调用。返回一个将 `hookSpecificOutput.retry` 设为 `true` 的 JSON 对象：

2450 2449

2451```json theme={null}2450```json theme={null}

2452{2451{

2457}2456}

2458```2457```

2459 2458

2460当 `retry` 为 `true` 时，Claude Code 会向对话中添加一条消息，告诉模型它可以重试该工具调用。Claude Code 本身不会撤销该拒绝。如果您的 hook 没有返回 JSON，或返回 `retry: false`，拒绝将保持有效，模型会收到原始的拒绝消息。2459当 `retry` 为 `true` 时，Claude Code 会在对话中添加一条消息，告知模型可以重试该工具调用。Claude Code 本身不会撤销拒绝。如果您的 hook 不返回 JSON，或返回 `retry: false`，则拒绝保持有效，模型会收到原始的拒绝消息。

2461 2460

2462当分类器[未对该操作作出判定](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)时（其响应无法解析，或独立于自动模式的安全检查拒绝了分类器自身的请求），Claude Code 会忽略 `retry: true`。对于这些拒绝，Claude Code 已经在拒绝消息中告诉模型是稍后重试还是继续其他工作。2461当分类器[未对该操作作出裁定](/docs/zh-CN/errors#auto-mode-cannot-determine-the-safety-of-an-action)时（其响应无法解析，或独立于自动模式的安全检查拒绝了分类器自身的请求），Claude Code 会忽略 `retry: true`。对于这类拒绝，Claude Code 已在拒绝消息中告知模型是稍后重试还是继续其他工作。

2463 2462

2464<h3 id="notification">2463<h3 id="notification">

2465 Notification2464 Notification

2466</h3>2465</h3>

2467 2466

2468当 Claude Code 发送通知时运行。按通知类型匹配。省略匹配器即可为所有通知类型运行 hook。2467在 Claude Code 发送通知时运行。按通知类型匹配。省略匹配器即可为所有通知类型运行 hook。

2469 2468

2470即使关闭了桌面通知，您也会收到这些 hook 事件：`preferredNotifChannel` 设置（包括 `notifications_disabled`）只改变提醒您的方式，而不影响您的 hook 是否运行。2469即使关闭了桌面通知，您仍会收到这些 hook 事件：`preferredNotifChannel` 设置（包括 `notifications_disabled`）只会改变提醒您的方式，而不会影响您的 hook 是否运行。

2471 2470

2472| 匹配器 | 触发时机 |2471| 匹配器 | 触发时机 |

2473| :- | :- |2472| :- | :- |

2481| `agent_needs_input` | 当 [agent view](/docs/zh-CN/agent-view) 在终端中打开时，某个后台会话开始等待您的输入。当终端会话向您显示 [agent team 队友的终端设置问题](/docs/zh-CN/agent-teams#choose-a-display-mode)或自动模式关于[分类器请求费用](/docs/zh-CN/auto-mode-classifier-billing)的提示，且您约六秒未输入任何内容时，也会触发 |2480| `agent_needs_input` | 在终端中打开 [Agent 视图](/docs/zh-CN/agent-view)期间，某个后台会话开始等待您的输入。当终端会话向您显示 [agent team 队友的终端设置问题](/docs/zh-CN/agent-teams#choose-a-display-mode)或自动模式关于[分类器请求费用](/docs/zh-CN/auto-mode-classifier-billing)的通知，且您约六秒没有输入时，也会触发 |

2483| `quota_auto_resume_fired` | 在 claude.ai 用量限制暂停您的任务后，Claude Code 继续执行该任务：在限制重置时，或者在等待期间您在 Claude Code 中执行的某些操作（例如添加使用额度、升级套餐或切换模型）使用量再次可用时提前继续，但存在[模型设置例外](/docs/zh-CN/interactive-mode#wait-for-a-usage-limit-to-reset) |2482| `quota_auto_resume_fired` | 在 claude.ai 用量限制暂停您的任务后，Claude Code 继续执行该任务：在重置时，或者当您在等待期间在 Claude Code 中执行的某些操作（例如添加使用额度、升级套餐或切换模型）使用量再次可用时提前继续，[模型设置例外](/docs/zh-CN/interactive-mode#wait-for-a-usage-limit-to-reset)除外 |

2484| `quota_auto_resume_stale` | claude.ai 用量限制在您的计算机休眠超过约 30 分钟期间重置。Claude Code 会等待您按 `Enter`，而不是继续执行。如果休眠时间较短，它会继续执行并改为触发 `quota_auto_resume_fired` |2483| `quota_auto_resume_stale` | 在您的计算机休眠超过约 30 分钟期间，claude.ai 用量限制已重置。Claude Code 会等待您按 `Enter`，而不是继续执行。休眠时间较短时，它会继续执行并改为触发 `quota_auto_resume_fired` |

2485| `quota_auto_resume_disabled` | Claude Code 结束了对 claude.ai 用量限制的等待，但没有继续您的任务：[`autoContinueAtUsageLimit`](/docs/zh-CN/settings-reference#autocontinueatusagelimit) 被关闭，或在 Claude Code 自行开始的等待期间重置时间推迟到 24 小时以后，或继续执行的任务反复触及限制，或继续执行在到达模型之前被阻止。当您按 `Esc` 或 `Ctrl+C`，或选择 **Don't continue automatically** 时不会触发 |2484| `quota_auto_resume_disabled` | Claude Code 结束对 claude.ai 用量限制的等待而未继续您的任务：在 Claude Code 自行发起的等待期间，[`autoContinueAtUsageLimit`](/docs/zh-CN/settings-reference#autocontinueatusagelimit) 被关闭或重置时间推迟到 24 小时以后；继续执行的任务不断触及限制；或继续执行在到达模型之前被阻止。当您按 `Esc` 或 `Ctrl+C`，或选择 **Don't continue automatically** 时不会触发 |

2486 2485

2487`quota_auto_resume_fired`、`quota_auto_resume_stale` 和 `quota_auto_resume_disabled` 类型需要 Claude Code v2.1.234 或更高版本。2486`quota_auto_resume_fired`、`quota_auto_resume_stale` 和 `quota_auto_resume_disabled` 类型需要 Claude Code v2.1.234 或更高版本。

2488 2487

2489在终端会话中，针对沙箱化命令网络请求的 `permission_prompt` 需要 Claude Code v2.1.246 或更高版本。2488在终端会话中，针对沙箱命令网络请求的 `permission_prompt` 需要 Claude Code v2.1.246 或更高版本。

2490 2489

2491针对队友终端设置问题的 `agent_needs_input` 需要 Claude Code v2.1.248 或更高版本。2490针对队友终端设置问题的 `agent_needs_input` 需要 Claude Code v2.1.248 或更高版本。

2492 2491

2493<Note>2492<Note>

2494 `permission_prompt`、`idle_prompt`、`elicitation_dialog` 和 `elicitation_url_dialog` 类型与桌面通知共享计时方式，因此在终端会话中，只有当您看起来已离开终端时才会看到它们：2493 `permission_prompt`、`idle_prompt`、`elicitation_dialog` 和 `elicitation_url_dialog` 类型与桌面通知共享计时方式，因此在终端会话中，只有当您看起来已离开终端时才会看到它们：

2495 2494

2496 * 当您约六秒未输入任何内容时，预期会出现 `permission_prompt`。计时器在权限提示出现时开始，每次按键都会推迟它。要在 Claude 请求使用工具的权限时立即运行 hook，请改用 [PermissionRequest](#permissionrequest)。2495 * 在您约六秒没有输入后，预计会触发 `permission_prompt`。计时器在权限提示出现时开始，每次按键都会推迟它。要在 Claude 请求使用工具的权限时立即运行 hook，请改用 [PermissionRequest](#permissionrequest)。

2497 * 预期 `idle_prompt` 会在 Claude 完成回复约 60 秒后出现，并且仅当您此后未输入任何内容且没有后台 Agent（例如后台[子代理](/docs/zh-CN/sub-agents)）仍在运行时才会出现。在等待 claude.ai 用量限制重置期间，Claude Code 不会发送 `idle_prompt`。当等待自行结束时，会改为触发某个 `quota_auto_resume_*` 类型。2496 * 在 Claude 完成回复约 60 秒后，预计会触发 `idle_prompt`，前提是此后您没有输入，且没有后台 Agent（例如后台[子代理](/docs/zh-CN/sub-agents)）仍在运行。Claude Code 在等待 claude.ai 用量限制重置期间不会发送 `idle_prompt`。当等待自行结束时，会改为触发某个 `quota_auto_resume_*` 类型。

2498 * 对于 elicitation 表单预期会出现 `elicitation_dialog`，对于浏览器 URL 请求预期会出现 `elicitation_url_dialog`，前提是您约六秒未输入任何内容。两者与 `permission_prompt` 共享相同的六秒门槛：计时器在对话框出现时开始，每次按键都会推迟它。2497 * 对于信息征询表单，预计会触发 `elicitation_dialog`；对于浏览器 URL 请求，预计会触发 `elicitation_url_dialog`，二者都在您约六秒没有输入后触发。两者与 `permission_prompt` 共享相同的六秒门槛：计时器在对话框出现时开始，每次按键都会推迟它。

2499 2498

2500 在另一个对话框显示在屏幕上时到达的权限请求或 elicitation 同样适用六秒门槛，从请求到达时开始计时。其通知可能会在请求仍排在已打开对话框之后等待时就送达您。2499 在另一个对话框显示期间到达的权限请求或信息征询，仍适用相同的六秒门槛，从请求到达时开始计时。即使该请求仍在已打开的对话框后面等待，它的通知也可能已经送达您。

2501</Note>2500</Note>

2502 2501

2503在 Claude Code 将权限请求发送给 Agent SDK 的 [`canUseTool` 回调](/docs/zh-CN/agent-sdk/user-input)的会话中（Claude Desktop 和 VS Code 扩展就是以这种方式托管 Claude Code 的），Claude Code 对 `permission_prompt` 的计时方式有所不同：2502在 Claude Code 将权限请求发送到 Agent SDK 的 [`canUseTool` 回调](/docs/zh-CN/agent-sdk/user-input)的会话中（Claude Desktop 和 VS Code 扩展就是以这种方式托管 Claude Code 的），Claude Code 对 `permission_prompt` 的计时方式不同：

2504 2503

2505* 预期 `permission_prompt` 会在 Claude 请求权限约六秒后出现。在您输入时，Claude Code 不会推迟它。2504* 预计在 Claude 请求权限约六秒后触发 `permission_prompt`。Claude Code 不会因您输入而推迟它。

2506* 如果您或 [PermissionRequest](#permissionrequest) hook 提前作出回应，Claude Code 不会运行 `permission_prompt`。2505* 如果您或 [PermissionRequest](#permissionrequest) hook 更早作出回应，Claude Code 不会运行 `permission_prompt`。

2507* 将 [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/zh-CN/env-vars) 设为 `1`，即可在这些会话中关闭 `permission_prompt`。2506* 将 [`CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS`](/docs/zh-CN/env-vars) 设为 `1`，即可在这些会话中关闭 `permission_prompt`。

2508 2507

2509在 v2.1.233 之前，`permission_prompt` 不会在这些会话中触发。2508在 v2.1.233 之前，`permission_prompt` 在这些会话中不会触发。

2510 2509

2511使用不同的匹配器，可以根据通知类型运行不同的处理程序。以下配置会在 Claude 需要权限批准时触发一个专门用于权限的警报脚本，在 Claude 处于空闲状态时触发另一个通知：2510使用不同的匹配器，可根据通知类型运行不同的处理程序。以下配置在 Claude 需要权限批准时触发一个专用于权限的提醒脚本，在 Claude 空闲时触发另一个通知：

2512 2511

2513```json theme={null}2512```json theme={null}

2514{2513{

2541 Notification 输入2540 Notification 输入

2542</h4>2541</h4>

2543 2542

2544除了[通用输入字段](#common-input-fields)之外，Notification hook 还会接收包含通知文本的 `message`、可选的 `title`，以及指示触发了哪种类型的 `notification_type`。2543除了[通用输入字段](#common-input-fields)外，Notification hook 还会接收包含通知文本的 `message`、可选的 `title`，以及指示触发类型的 `notification_type`。

2545 2544

2546```json theme={null}2545```json theme={null}

2547{2546{

2555}2554}

2556```2555```

2557 2556

2558Notification hook 无法阻止或修改通知。Claude Code 会丢弃它们的 `systemMessage` 和 `continue` 字段，但仍会发出 [`terminalSequence`](#emit-terminal-notifications)，桌面通知示例正是依赖于此。Notification hook 旨在用于副作用，例如将通知转发到外部服务。2557Notification hook 无法阻止或修改通知。Claude Code 会丢弃它们的 `systemMessage` 和 `continue` 字段，但仍会发出 [`terminalSequence`](#emit-terminal-notifications)，桌面通知示例正是依赖于此。Notification hook 适用于产生副作用，例如将通知转发到外部服务。

2559 2558

2560<h3 id="subagentstart">2559<h3 id="subagentstart">

2561 SubagentStart2560 SubagentStart

2562</h3>2561</h3>

2563 2562

2564当 Claude 使用 Agent 工具生成子代理、当 Claude [恢复子代理](/docs/zh-CN/sub-agents#resume-subagents)，以及每次进程内 [agent team](/docs/zh-CN/agent-teams) 队友处理新消息时运行。支持使用匹配器按 Agent 类型名称进行过滤。对于内置 Agent，这是 Agent 名称，例如 `general-purpose`、`Explore` 或 `Plan`。对于[自定义子代理](/docs/zh-CN/sub-agents)，这是 Agent frontmatter 中的 `name` 字段，而不是文件名。2563当 Claude 使用 Agent 工具生成子代理、当 Claude [恢复子代理](/docs/zh-CN/sub-agents#resume-subagents)，以及每次进程内 [agent team](/docs/zh-CN/agent-teams) 队友处理新消息时运行。支持使用匹配器按 Agent 类型名称过滤。对于内置 Agent，这是诸如 `general-purpose`、`Explore` 或 `Plan` 之类的 Agent 名称。对于[自定义子代理](/docs/zh-CN/sub-agents)，这是 Agent frontmatter 中的 `name` 字段，而非文件名。

2565 2564

2566对于由[插件](/docs/zh-CN/plugins/overview)提供的子代理，Agent 类型是插件范围的标识符，例如 `my-plugin:reviewer`，而不是单纯的 frontmatter 名称。冒号会使插件范围的名称走正则表达式匹配路径，因此请用 `^` 和 `$` 锚定匹配器以进行精确匹配：`^my-plugin:reviewer$`。2565对于由[插件](/docs/zh-CN/plugins/overview)提供的子代理，Agent 类型是插件作用域的标识符，例如 `my-plugin:reviewer`，而不是单纯的 frontmatter 名称。冒号会使插件作用域的名称走正则表达式路径，因此请用 `^` 和 `$` 锚定匹配器以实现精确匹配：`^my-plugin:reviewer$`。

2567 2566

2568<h4 id="subagentstart-input">2567<h4 id="subagentstart-input">

2569 SubagentStart 输入2568 SubagentStart 输入

2570</h4>2569</h4>

2571 2570

2572除了[通用输入字段](#common-input-fields)之外，SubagentStart hook 还会接收包含子代理唯一标识符的 `agent_id`，以及包含匹配器所过滤的 Agent 名称的 `agent_type`。2571除了[通用输入字段](#common-input-fields)外，SubagentStart hook 还会接收包含子代理唯一标识符的 `agent_id`，以及包含匹配器所过滤的 Agent 名称的 `agent_type`。

2573 2572

2574```json theme={null}2573```json theme={null}

2575{2574{

2582}2581}

2583```2582```

2584 2583

2585SubagentStart hook 无法阻止子代理的创建，但可以向子代理注入上下文。除了所有 hook 都可用的 [JSON 输出字段](#json-output)之外，您还可以返回：2584SubagentStart hook 无法阻止子代理的创建，但可以向子代理注入上下文。除了所有 hook 均可使用的 [JSON 输出字段](#json-output)外，您还可以返回：

2586 2585

2587| 字段 | 描述 |2586| 字段 | 描述 |

2588| :- | :- |2587| :- | :- |

2597}2596}

2598```2597```

2599 2598

2600当 hook 针对同一子代理再次运行时，仅当子代理的上下文中尚未包含先前运行注入的副本时，Claude Code 才会注入返回的上下文。启动时注入的副本会保留在原位，从而使子代理的[提示缓存](/docs/zh-CN/prompt-caching#subagents-and-the-cache)保持完整。在[自动压缩](/docs/zh-CN/sub-agents#auto-compaction)丢弃该副本后，Claude Code 会再次注入下一次运行的上下文。2599当 hook 针对同一子代理再次运行时，仅当子代理的上下文中尚未包含先前运行注入的副本时，Claude Code 才会注入返回的上下文。启动时注入的副本会保留在原位，从而保持子代理的[提示缓存](/docs/zh-CN/prompt-caching#subagents-and-the-cache)不变。在[自动压缩](/docs/zh-CN/sub-agents#auto-compaction)丢弃该副本后，Claude Code 会再次注入下一次运行的上下文。

2601 2600

2602<h3 id="subagentstop">2601<h3 id="subagentstop">

2603 SubagentStop2602 SubagentStop

2604</h3>2603</h3>

2605 2604

2606当 Claude Code 子代理完成回复时运行。按 Agent 类型匹配，取值与 SubagentStart 相同。2605在 Claude Code 子代理完成回复时运行。按 Agent 类型匹配，取值与 SubagentStart 相同。

2607 2606

2608<h4 id="subagentstop-input">2607<h4 id="subagentstop-input">

2609 SubagentStop 输入2608 SubagentStop 输入

2610</h4>2609</h4>

2611 2610

2612除了[通用输入字段](#common-input-fields)之外，SubagentStop hook 还会接收 `stop_hook_active`、`agent_id`、`agent_type`、`agent_transcript_path` 和 `last_assistant_message`。`agent_type` 字段是用于匹配器过滤的值。`transcript_path` 是主会话的会话记录，而 `agent_transcript_path` 是存储在嵌套 `subagents/` 文件夹中的子代理自身的会话记录。`last_assistant_message` 字段包含子代理最终回复的文本内容，因此 hook 无需解析会话记录文件即可访问它。2611除了[通用输入字段](#common-input-fields)外，SubagentStop hook 还会接收 `stop_hook_active`、`agent_id`、`agent_type`、`agent_transcript_path` 和 `last_assistant_message`。`agent_type` 字段是用于匹配器过滤的值。`transcript_path` 是主会话的会话记录，而 `agent_transcript_path` 是子代理自身的会话记录，存储在嵌套的 `subagents/` 文件夹中。`last_assistant_message` 字段包含子代理最终回复的文本内容，因此 hook 无需解析会话记录文件即可访问它。

2613 2612

2614并非每个 SubagentStop 事件都来自 Claude 生成的子代理。Claude Code 还会为其自身的某些功能运行内部 Agent，例如[提示词建议](/docs/zh-CN/interactive-mode#prompt-suggestions)和 [`/btw` 旁支问题](/docs/zh-CN/interactive-mode#side-questions-with-%2Fbtw)，当这些 Agent 之一完成时，SubagentStop 也会触发。对于这些事件，`agent_type` 是会话本身运行所用的 Agent 名称，例如通过 [`--agent`](/docs/zh-CN/cli-reference#cli-flags) 或 [`agent` 设置](/docs/zh-CN/settings-reference#agent)设定的名称；当会话未使用 Agent 运行时则为空字符串。2613并非每个 SubagentStop 事件都来自 Claude 生成的子代理。Claude Code 还会为其自身的某些功能运行内部 Agent，例如[提示词建议](/docs/zh-CN/interactive-mode#prompt-suggestions)和 [`/btw` 附带问题](/docs/zh-CN/interactive-mode#side-questions-with-%2Fbtw)，这些内部 Agent 完成时也会触发 SubagentStop。对于这些事件，`agent_type` 是会话本身运行所用的 Agent 名称，例如通过 [`--agent`](/docs/zh-CN/cli-reference#cli-flags) 或 [`agent` 设置](/docs/zh-CN/settings-reference#agent)设定的名称；当会话未使用 Agent 运行时，它为空字符串。

2615 2614

2616指定了 Agent 类型的 `matcher` 不会匹配空的 `agent_type`。匹配器被省略、为 `""` 或 `"*"`，或者是能匹配空字符串的正则表达式的 hook，也会针对 `agent_type` 为空的事件运行。2615指定了 Agent 类型的 `matcher` 不会匹配空的 `agent_type`。匹配器被省略、为 `""` 或 `"*"`，或者是能匹配空字符串的正则表达式的 hook，也会针对 `agent_type` 为空的事件运行。

2617 2616

2618在 Claude Code v2.1.271 或更高版本中，使用 [`SubagentHandback`](/docs/zh-CN/tools-reference) 工具运行的子代理会在停止之前通过该工具传递其报告。此时 `last_assistant_message` 字段保存的是子代理的结束文本（如果有），而不是所传递的报告。报告是该调用的 `message` 输入，匹配 `SubagentHandback` 的 `PreToolUse` 或 `PostToolUse` hook 会以 `tool_input.message` 的形式收到它。2617在 Claude Code v2.1.271 或更高版本中，使用 [`SubagentHandback`](/docs/zh-CN/tools-reference) 工具运行的子代理会在停止前通过该工具传递其报告。此时 `last_assistant_message` 字段保存的是子代理的结束文本（如有），而不是所传递的报告。报告是该调用的 `message` 输入，匹配 `SubagentHandback` 的 `PreToolUse` 或 `PostToolUse` hook 会以 `tool_input.message` 的形式接收它。

2619 2618

2620SubagentStop hook 还会接收 [Stop 输入](#stop-input)中描述的 `background_tasks` 和 `session_crons` 数组。这两个数组的范围是父会话，而不是子代理。2619SubagentStop hook 还会接收 [Stop 输入](#stop-input)中所述的 `background_tasks` 和 `session_crons` 数组。这两个数组的作用域都是父会话，而不是子代理。

2621 2620

2622```json theme={null}2621```json theme={null}

2623{2622{

2636}2635}

2637```2636```

2638 2637

2639SubagentStop hook 使用与 [Stop hook](#stop-decision-control) 相同的决策控制格式，包括将 `hookEventName` 设为 `"SubagentStop"` 的 `hookSpecificOutput.additionalContext`，用于提供让子代理继续运行的非错误反馈。返回带有 `reason` 的 `decision: "block"` 会让子代理继续运行，并将 `reason` 作为下一条指令传递给子代理。通过退出码 2 进行阻止的 hook 会以同样方式传递其 stderr 消息。要在子代理返回后向父会话注入上下文，请改为在 `Agent` 工具上使用 [`PostToolUse`](#posttooluse) hook。2638SubagentStop hook 使用与 [Stop hook](#stop-decision-control) 相同的决策控制格式，包括将 `hookEventName` 设为 `"SubagentStop"` 的 `hookSpecificOutput.additionalContext`，用于提供让子代理继续运行的非错误反馈。返回带有 `reason` 的 `decision: "block"` 会让子代理继续运行，并将 `reason` 作为下一条指令传递给子代理。通过以退出码 2 退出来阻止的 hook 会以相同方式传递其 stderr 消息。要在子代理返回后向父会话注入上下文，请改为在 `Agent` 工具上使用 [`PostToolUse`](#posttooluse) hook。

2640 2639

2641<h3 id="taskcreated">2640<h3 id="taskcreated">

2642 TaskCreated2641 TaskCreated

2643</h3>2642</h3>

2644 2643

2645当通过 `TaskCreate` 工具创建任务时运行。可用于强制执行命名约定、要求提供任务描述或阻止创建某些任务。在[没有 Task 工具的会话](/docs/zh-CN/tools-reference#task-tool-availability)中，此事件不会触发。2644在通过 `TaskCreate` 工具创建任务时运行。可用于强制执行命名约定、要求提供任务描述，或阻止创建某些任务。在[不含 Task 工具的会话](/docs/zh-CN/tools-reference#task-tool-availability)中，此事件不会触发。

2646 2645

2647TaskCreated hook 不支持匹配器，每次发生时都会触发。2646TaskCreated hook 不支持匹配器，每次发生时都会触发。

2648 2647

2650 TaskCreated 输入2649 TaskCreated 输入

2651</h4>2650</h4>

2652 2651

2653除了[通用输入字段](#common-input-fields)之外，TaskCreated hook 还会接收 `task_id`、`task_subject`，以及可选的 `task_description`、`teammate_name` 和 `team_name`。2652除了[通用输入字段](#common-input-fields)外，TaskCreated hook 还会接收 `task_id`、`task_subject`，以及可选的 `task_description`、`teammate_name` 和 `team_name`。

2654 2653

2655```json theme={null}2654```json theme={null}

2656{2655{

2675| `agent_id` | 在此事件中，该[通用输入字段](#common-input-fields)标识正在创建任务的子代理或[进程内队友](/docs/zh-CN/agent-teams#choose-a-display-mode)。可能不存在。需要 Claude Code v2.1.290 或更高版本 |

2676 2676

2677<h4 id="taskcreated-decision-control">2677<h4 id="taskcreated-decision-control">

2678 TaskCreated 决策控制2678 TaskCreated 决策控制

2702 TaskCompleted2702 TaskCompleted

2703</h3>2703</h3>

2704 2704

2705当任务被标记为已完成时运行。它会在两种情况下触发：任何 Agent 通过 TaskUpdate 工具显式将任务标记为已完成时，或 [agent team](/docs/zh-CN/agent-teams) 队友在仍有进行中任务的情况下结束其轮次时。可用于在任务关闭之前强制执行完成标准，例如测试通过或 lint 检查通过。2705在任务被标记为已完成时运行。它在两种情况下触发：任何 Agent 通过 TaskUpdate 工具显式将任务标记为已完成时，或 [agent team](/docs/zh-CN/agent-teams) 队友在仍有进行中任务的情况下结束其轮次时。可用于在任务关闭前强制执行完成标准，例如测试通过或 lint 检查通过。

2706 2706

2707TaskCompleted hook 不支持匹配器，每次发生时都会触发。2707TaskCompleted hook 不支持匹配器，每次发生时都会触发。

2708 2708

2710 TaskCompleted 输入2710 TaskCompleted 输入

2711</h4>2711</h4>

2712 2712

2713除了[通用输入字段](#common-input-fields)之外，TaskCompleted hook 还会接收 `task_id`、`task_subject`，以及可选的 `task_description`、`teammate_name` 和 `team_name`。2713除了[通用输入字段](#common-input-fields)外，TaskCompleted hook 还会接收 `task_id`、`task_subject`，以及可选的 `task_description`、`teammate_name` 和 `team_name`。

2714 2714

2715```json theme={null}2715```json theme={null}

2716{2716{

2737| `agent_id` | 在此事件中，该[通用输入字段](#common-input-fields)标识正在完成任务的子代理或[进程内队友](/docs/zh-CN/agent-teams#choose-a-display-mode)。可能不存在。需要 Claude Code v2.1.290 或更高版本 |

2737 2738

2738<h4 id="taskcompleted-decision-control">2739<h4 id="taskcompleted-decision-control">

2739 TaskCompleted 决策控制2740 TaskCompleted 决策控制

2741 2742

2742TaskCompleted hook 支持两种控制任务完成的方式：2743TaskCompleted hook 支持两种控制任务完成的方式：

2743 2744

2744* **退出码 2**：任务不会被标记为已完成，stderr 消息会作为反馈传回给模型。2745* **退出码 2**：任务不会被标记为已完成，stderr 消息会作为反馈回传给模型。

2745* **JSON `{"continue": false, "stopReason": "..."}`**：当事件由队友结束其轮次触发时，完全停止该队友，与 `Stop` hook 的行为一致。`stopReason` 会显示给用户。当事件由 `TaskUpdate` 工具触发时，Claude Code 会忽略 `continue: false`；退出码 2 仍会阻止完成。2746* **JSON `{"continue": false, "stopReason": "..."}`**：当事件由队友结束其轮次触发时，完全停止该队友，与 `Stop` hook 的行为一致。`stopReason` 会显示给用户。当事件由 `TaskUpdate` 工具触发时，Claude Code 会忽略 `continue: false`；退出码 2 仍会阻止完成。

2746 2747

2747以下示例运行测试，如果测试失败则阻止任务完成：2748以下示例运行测试，并在测试失败时阻止任务完成：

2748 2749

2749```bash theme={null}2750```bash theme={null}

2750#!/bin/bash2751#!/bin/bash

2764 Stop2765 Stop

2765</h3>2766</h3>

2766 2767

2767当主 Claude Code Agent 完成回复时运行。如果停止是由用户中断导致的，则不会运行。API 错误会改为触发2768在主 Claude Code Agent 完成回复时运行。如果停止是由用户中断引起的，则不会运行。API 错误会改为触发

2768[StopFailure](#stopfailure)。2769[StopFailure](#stopfailure)。

2769 2770

2770<Tip>2771<Tip>

2771 [`/goal`](/docs/zh-CN/goal) 命令是会话范围内基于提示词的 Stop hook 的内置快捷方式。当您希望 Claude 朝着某个条件持续工作而无需编写 hook 配置时，请使用它。2772 [`/goal`](/docs/zh-CN/goal) 命令是会话作用域的、基于提示词的 Stop hook 的内置快捷方式。当您希望 Claude 持续朝某个条件努力而无需编写 hook 配置时，可以使用它。

2772</Tip>2773</Tip>

2773 2774

2774<h4 id="stop-input">2775<h4 id="stop-input">

2775 Stop 输入2776 Stop 输入

2776</h4>2777</h4>

2777 2778

2778除了[通用输入字段](#common-input-fields)之外，Stop hook 还会收到 `stop_hook_active`、`last_assistant_message`、`background_tasks` 和 `session_crons`。当 Claude Code 已经因 stop hook 而在继续运行时，`stop_hook_active` 字段为 `true`。请检查此值或处理会话记录，以避免因永远无法满足的条件而持续阻止。2779除了[通用输入字段](#common-input-fields)外，Stop hook 还会接收 `stop_hook_active`、`last_assistant_message`、`background_tasks` 和 `session_crons`。当 Claude Code 已经因 stop hook 而继续运行时，`stop_hook_active` 字段为 `true`。请检查此值或处理会话记录，以避免因一个永远无法满足的条件而持续阻止。

2779 2780

2780Claude Code 设有连续 8 次继续的上限：在 stop hook 已连续八次让轮次继续之后，Claude Code 会覆盖下一次阻止并结束该轮次。每当 Claude 调用工具时，连续继续的计数都会重置。要提高上限，请设置 [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/zh-CN/env-vars)。2781Claude Code 设有连续 8 次继续的上限：在 stop hook 连续八次让轮次继续后，Claude Code 会覆盖下一次阻止并结束该轮次。每次 Claude 调用工具时，连续继续的计数都会重置。要提高该上限，请设置 [`CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`](/docs/zh-CN/env-vars)。

2781 2782

2782`last_assistant_message` 字段包含 Claude 最终回复的文本内容，因此 hook 无需解析会话记录文件即可访问它。对于需要处理刚完成的轮次的 hook（例如朗读或通知 hook），请使用此字段，而不是读取 `transcript_path`：在所有版本中，并不能保证会话记录文件在 Stop 时已包含最终消息。2783`last_assistant_message` 字段包含 Claude 最终回复的文本内容，因此 hook 无需解析会话记录文件即可访问它。对于作用于刚刚完成的轮次的 hook（例如朗读或通知 hook），请使用此字段而不是读取 `transcript_path`：并非所有版本都能保证在 Stop 时会话记录文件中已包含最终消息。

2783 2784

2784`background_tasks` 和 `session_crons` 数组让 hook 能够区分"会话已完成"和"会话已暂停，正在等待后台工作将其重新唤醒"。当任务注册表可访问时，这两个数组都会存在；当没有正在进行或已计划的内容时，它们为空。2785`background_tasks` 和 `session_crons` 数组使 hook 能够区分"会话已完成"和"会话已暂停，正在等待后台工作将其唤醒"。当任务注册表可访问时，这两个数组都会存在；当没有正在进行或已计划的内容时，它们为空。

2785 2786

2786`background_tasks` 中的每个条目描述一个正在进行的任务，并使用以下字段：2787`background_tasks` 中的每个条目描述一个正在进行的任务，并使用以下字段：

2787 2788

2788| 字段 | 描述 |2789| 字段 | 描述 |

2789| :- | :- |2790| :- | :- |

2790| `id` | 任务标识符 |2791| `id` | 任务标识符 |

2791| `type` | 易读的任务类型标签，例如 `shell`、`subagent`、`monitor`、`workflow`、`teammate`、`cloud session` 或 `MCP task`。每个标签标识了创建该任务的 Claude Code 功能。对于无法识别的类型，回退为原始判别值 |2792| `type` | 友好的任务类型标签，例如 `shell`、`subagent`、`monitor`、`workflow`、`teammate`、`cloud session` 或 `MCP task`。每个标签标识创建该任务的 Claude Code 功能。对于无法识别的类型，回退为原始判别值 |

2799 2800

2800`session_crons` 中的每个条目描述一个会话范围内的计划唤醒，来源于 `CronCreate`、`ScheduleWakeup` 和 `/loop`：2801`session_crons` 中的每个条目描述一个会话作用域的计划唤醒，来源为 `CronCreate`、`ScheduleWakeup` 和 `/loop`：

2801 2802

2802| 字段 | 描述 |2803| 字段 | 描述 |

2803| :- | :- |2804| :- | :- |

2804| `id` | Cron 任务标识符 |2805| `id` | Cron 任务标识符 |

2808 2809

2809以下示例展示了一个包含一个正在进行的 shell 任务和一个周期性 cron 的 Stop 输入：2810以下示例展示了一个包含一个正在进行的 shell 任务和一个周期性 cron 的 Stop 输入：

2810 2811

2841 Stop 决策控制2842 Stop 决策控制

2842</h4>2843</h4>

2843 2844

2844`Stop` 和 `SubagentStop` hook 可以控制 Claude 是否继续。除了所有 hook 都可用的 [JSON 输出字段](#json-output)之外，您的 hook 脚本还可以返回以下特定于事件的字段：2845`Stop` 和 `SubagentStop` hook 可以控制 Claude 是否继续。除了所有 hook 均可使用的 [JSON 输出字段](#json-output)外，您的 hook 脚本还可以返回以下事件特定字段：

2845 2846

2846| 字段 | 描述 |2847| 字段 | 描述 |

2847| :- | :- |2848| :- | :- |

2850| `hookSpecificOutput.additionalContext` | 给 Claude 的非错误反馈。对话会继续，以便 Claude 据此采取行动，但与 `decision: "block"` 不同，它在会话记录中显示为 hook 反馈，而不是 hook 错误 |2851| `hookSpecificOutput.additionalContext` | 给 Claude 的非错误反馈。对话会继续，以便 Claude 据此采取行动，但与 `decision: "block"` 不同，它在会话记录中显示为 hook 反馈而非 hook 错误 |

2851 2852

2852通过退出码 2 进行阻止的 hook 与 `reason` 的传递方式相同：Claude 会收到 stderr 消息，作为它应该继续的原因说明。2853通过以退出码 2 退出来阻止的 hook，其路由方式与 `reason` 相同：Claude 会将 stderr 消息作为它应继续的原因说明接收。

2853 2854

2854```json theme={null}2855```json theme={null}

2855{2856{

2858}2859}

2859```2860```

2860 2861

2861当 hook 按设计正常工作并为 Claude 提供指导时（例如"完成前运行测试套件"），请使用 `additionalContext`。它通过与 `decision: "block"` 相同的循环保护机制（即 `stop_hook_active` 输入和 8 次连续继续上限）让对话继续，但会话记录会将其标记为 `Stop hook feedback`，并且不会显示 hook 错误通知：2862当 hook 按设计正常工作并为 Claude 提供指导时（例如"在完成之前运行测试套件"），请使用 `additionalContext`。它通过与 `decision: "block"` 相同的循环保护机制（即 `stop_hook_active` 输入和连续 8 次继续的上限）让对话继续进行，但会话记录会将其标记为 `Stop hook feedback`，且不会显示 hook 错误通知：

2862 2863

2863```json theme={null}2864```json theme={null}

2864{2865{

2873 StopFailure2874 StopFailure

2874</h3>2875</h3>

2875 2876

2876当轮次因 API 错误而结束时，代替 [Stop](#stop) 运行。除 [`terminalSequence`](#emit-terminal-notifications) 外，Claude Code 会忽略该 hook 的输出和退出码。当 Claude 由于速率限制、身份验证问题或其他 API 错误而无法完成回复时，可用于记录失败、发送警报或采取恢复措施。2877当轮次因 API 错误而结束时，代替 [Stop](#stop) 运行。除 [`terminalSequence`](#emit-terminal-notifications) 外，Claude Code 会忽略该 hook 的输出和退出码。当 Claude 因速率限制、身份验证问题或其他 API 错误而无法完成回复时，可用于记录失败、发送警报或执行恢复操作。

2877 2878

2878<h4 id="stopfailure-input">2879<h4 id="stopfailure-input">

2879 StopFailure 输入2880 StopFailure 输入

2880</h4>2881</h4>

2881 2882

2882除了[通用输入字段](#common-input-fields)之外，StopFailure hook 还会接收 `error`、可选的 `error_details` 和可选的 `last_assistant_message`。`error` 字段标识错误类型，并用于匹配器过滤。2883除了[通用输入字段](#common-input-fields)外，StopFailure hook 还会接收 `error`、可选的 `error_details` 和可选的 `last_assistant_message`。`error` 字段标识错误类型，并用于匹配器过滤。

2883 2884

2884| 字段 | 描述 |2885| 字段 | 描述 |

2885| :- | :- |2886| :- | :- |

2886| `error` | 错误类型：`rate_limit`、`overloaded`、`authentication_failed`、`oauth_org_not_allowed`、`account_on_hold`、`billing_error`、`invalid_request`、`model_not_found`、`server_error`、`max_output_tokens`、`cloud_credential_error` 或 `unknown` |2887| `error` | 错误类型：`rate_limit`、`overloaded`、`authentication_failed`、`oauth_org_not_allowed`、`account_on_hold`、`billing_error`、`invalid_request`、`model_not_found`、`server_error`、`max_output_tokens`、`cloud_credential_error` 或 `unknown` |

2888| `last_assistant_message` | 在对话中显示的渲染后错误文本。与 `Stop` 和 `SubagentStop` 中该字段保存 Claude 的对话输出不同，对于 `StopFailure`，它包含 API 错误字符串本身，例如 `"API Error: Rate limit reached"` |2889| `last_assistant_message` | 对话中显示的渲染后错误文本。与 `Stop` 和 `SubagentStop`（此字段保存 Claude 的对话输出）不同，对于 `StopFailure`，它包含 API 错误字符串本身，例如 `"API Error: Rate limit reached"` |

2889 2890

2890```json theme={null}2891```json theme={null}

2891{2892{

2899}2900}

2900```2901```

2901 2902

2902StopFailure hook 没有决策控制。它们仅用于通知和日志记录目的。2903StopFailure hook 没有决策控制。它们仅用于通知和日志记录。

2903 2904

2904<h3 id="teammateidle">2905<h3 id="teammateidle">

2905 TeammateIdle2906 TeammateIdle

2906</h3>2907</h3>

2907 2908

2908当 [agent team](/docs/zh-CN/agent-teams) 队友在结束其轮次后即将进入空闲状态时运行。可用于在队友停止工作之前强制执行质量关卡，例如要求 lint 检查通过或验证输出文件是否存在。2909当 [agent team](/docs/zh-CN/agent-teams) 队友在结束其轮次后即将进入空闲状态时运行。可用于在队友停止工作前强制执行质量关卡，例如要求 lint 检查通过或验证输出文件是否存在。

2909 2910

2910TeammateIdle hook 不支持匹配器，每次发生时都会触发。2911TeammateIdle hook 不支持匹配器，每次发生时都会触发。

2911 2912

2913 TeammateIdle 输入2914 TeammateIdle 输入

2914</h4>2915</h4>

2915 2916

2916除了[通用输入字段](#common-input-fields)之外，TeammateIdle hook 还会接收 `teammate_name` 和 `team_name`。2917除了[通用输入字段](#common-input-fields)外，TeammateIdle hook 还会接收 `teammate_name` 和 `team_name`。

2917 2918

2918```json theme={null}2919```json theme={null}

2919{2920{

2931| :- | :- |2932| :- | :- |

2935| `agent_id` | 在此事件中，该[通用输入字段](#common-input-fields)标识即将进入空闲状态的[进程内队友](/docs/zh-CN/agent-teams#choose-a-display-mode)。可能不存在。需要 Claude Code v2.1.290 或更高版本 |

2934 2936

2935<h4 id="teammateidle-decision-control">2937<h4 id="teammateidle-decision-control">

2936 TeammateIdle 决策控制2938 TeammateIdle 决策控制

2938 2940

2939TeammateIdle hook 支持两种控制队友行为的方式：2941TeammateIdle hook 支持两种控制队友行为的方式：

2940 2942

2941* **退出码 2**：队友会收到 stderr 消息作为反馈，并继续工作而不是进入空闲状态。2943* **退出码 2**：队友会将 stderr 消息作为反馈接收，并继续工作而不是进入空闲状态。

2942* **JSON `{"continue": false, "stopReason": "..."}`**：完全停止该队友，与 `Stop` hook 的行为一致。`stopReason` 会显示给用户。2944* **JSON `{"continue": false, "stopReason": "..."}`**：完全停止该队友，与 `Stop` hook 的行为一致。`stopReason` 会显示给用户。

2943 2945

2944以下示例在允许队友进入空闲状态之前检查构建产物是否存在：2946以下示例在允许队友进入空闲状态之前检查构建产物是否存在：

2958 ConfigChange2960 ConfigChange

2959</h3>2961</h3>

2960 2962

2961当会话期间配置文件发生更改时运行。可用于审计设置更改、强制执行安全策略，或阻止对配置文件的未经授权的修改。2963在会话期间配置文件发生更改时运行。可用于审计设置更改、强制执行安全策略，或阻止对配置文件的未授权修改。

2962 2964

2963当设置文件、托管策略文件或 skill 文件发生更改时，Claude Code 会运行 ConfigChange hook。对于托管策略，仅当 `managed-settings.json` 或 `managed-settings.d/` 中的文件发生更改时才会运行。对于[服务器托管设置](/docs/zh-CN/server-managed-settings)以及 macOS 托管偏好设置或 Windows 注册表策略的更改，Claude Code 会直接应用而不运行这些 hook。在启用了 [`wslInheritsWindowsSettings`](/docs/zh-CN/settings-reference#wslinheritswindowssettings) 的 WSL 上，它在策略轮询时也会直接应用已更改的 Windows 端托管设置文件，而不运行这些 hook。2965当设置文件、托管策略文件或 skill 文件发生更改时，Claude Code 会运行 ConfigChange hook。对于托管策略，仅当 `managed-settings.json` 或 `managed-settings.d/` 中的文件发生更改时才会运行它们。它会应用[服务器托管设置](/docs/zh-CN/server-managed-settings)以及对 macOS 托管偏好设置或 Windows 注册表策略的更改，而不运行这些 hook。在启用了 [`wslInheritsWindowsSettings`](/docs/zh-CN/settings-reference#wslinheritswindowssettings) 的 WSL 上，它还会在策略轮询时应用已更改的 Windows 端托管设置文件，同样不运行这些 hook。

2964 2966

2965匹配器按配置来源进行过滤：2967匹配器按配置来源过滤：

2966 2968

2967| 匹配器 | 触发时机 |2969| 匹配器 | 触发时机 |

2968| :- | :- |2970| :- | :- |

2974 2976

2975以下示例记录所有配置更改以进行安全审计：2977以下示例记录所有配置更改以用于安全审计：

2976 2978

2977```json theme={null}2979```json theme={null}

2978{2980{

2996 ConfigChange 输入2998 ConfigChange 输入

2997</h4>2999</h4>

2998 3000

2999除了[通用输入字段](#common-input-fields)之外，ConfigChange hook 还会接收 `source` 和可选的 `file_path`。`source` 字段指示哪种配置类型发生了更改，`file_path` 提供被修改的具体文件的路径。3001除了[通用输入字段](#common-input-fields)外，ConfigChange hook 还会接收 `source` 和可选的 `file_path`。`source` 字段指示哪种配置类型发生了更改，`file_path` 提供被修改的具体文件的路径。

3000 3002

3001```json theme={null}3003```json theme={null}

3002{3004{

3017 3019

3018| 字段 | 描述 |3020| 字段 | 描述 |

3019| :- | :- |3021| :- | :- |

3022 3024

3023```json theme={null}3025```json theme={null}

3024{3026{

3027}3029}

3028```3030```

3029 3031

3030`policy_settings` 更改无法被阻止。当机器上的托管设置文件发生更改时，hook 仍会针对 `policy_settings` 来源触发，因此您可以使用它们记录这些编辑，但任何阻止决策都会被忽略。这确保了企业托管设置始终生效。当[服务器托管设置](/docs/zh-CN/server-managed-settings)到达或刷新时，Claude Code 不会运行 `ConfigChange` hook。3032`policy_settings` 更改无法被阻止。当机器上的托管设置文件发生更改时，hook 仍会针对 `policy_settings` 来源触发，因此您可以用它们记录这些编辑，但任何阻止决策都会被忽略。这可确保企业托管设置始终生效。当[服务器托管设置](/docs/zh-CN/server-managed-settings)到达或刷新时，Claude Code 不会运行 `ConfigChange` hook。

3031 3033

3032Claude Code 会根据 ConfigChange hook JSON 输出中的阻止决策采取行动，并丢弃 `systemMessage` 和 `continue`。无论您是通过 `reason` 还是通过退出码 2 时的 stderr 进行阻止，被阻止的更改都不会向您或 Claude 显示任何消息。Claude Code 只会在调试日志中写入一行。3034Claude Code 会根据 ConfigChange hook JSON 输出中的阻止决策采取行动，并丢弃 `systemMessage` 和 `continue`。被阻止的更改不会向您或 Claude 显示任何消息，无论您是通过 `reason` 还是通过退出码 2 时的 stderr 进行阻止。Claude Code 只会向调试日志写入一行。

3033 3035

3034<h3 id="cwdchanged">3036<h3 id="cwdchanged">

3035 CwdChanged3037 CwdChanged

3036</h3>3038</h3>

3037 3039

3038当主对话中的 shell 命令更改了工作目录时运行，例如 Claude 执行 `cd` 命令时。可用于响应目录更改：重新加载环境变量、激活特定于项目的工具链，或自动运行设置脚本。可与 [FileChanged](#filechanged) 配合使用，以支持 [direnv](https://direnv.net/) 等管理每目录环境的工具。3040当主对话中的 shell 命令更改了工作目录时运行，例如当 Claude 执行 `cd` 命令时。可用于响应目录更改：重新加载环境变量、激活项目特定的工具链，或自动运行设置脚本。可与 [FileChanged](#filechanged) 搭配使用，以支持 [direnv](https://direnv.net/) 等按目录管理环境的工具。

3039 3041

3040CwdChanged hook 可以访问 [`CLAUDE_ENV_FILE`](#persist-environment-variables)。写入该文件的变量会在后续 Bash 命令中持续有效，直到下一个 CwdChanged 事件时由 Claude Code 清除。3042CwdChanged hook 可以访问 [`CLAUDE_ENV_FILE`](#persist-environment-variables)。写入该文件的变量会持续作用于后续的 Bash 命令，直到下一个 CwdChanged 事件发生，届时 Claude Code 会清除它们。

3041 3043

3042CwdChanged 不支持匹配器，每次发生时都会触发。3044CwdChanged 不支持匹配器，每次发生时都会触发。

3043 3045

3045 CwdChanged 输入3047 CwdChanged 输入

3046</h4>3048</h4>

3047 3049

3048除了[通用输入字段](#common-input-fields)之外，CwdChanged hook 还会接收 `old_cwd` 和 `new_cwd`。3050除了[通用输入字段](#common-input-fields)外，CwdChanged hook 还会接收 `old_cwd` 和 `new_cwd`。

3049 3051

3050```json theme={null}3052```json theme={null}

3051{3053{

3062 CwdChanged 输出3064 CwdChanged 输出

3063</h4>3065</h4>

3064 3066

3065除了所有 hook 都可用的 [JSON 输出字段](#json-output)之外，CwdChanged hook 还可以返回 `watchPaths`，以动态设置 [FileChanged](#filechanged) 监视哪些文件路径：3067除了所有 hook 均可使用的 [JSON 输出字段](#json-output)外，CwdChanged hook 还可以返回 `watchPaths`，以动态设置 [FileChanged](#filechanged) 监视的文件路径：

3066 3068

3067| 字段 | 描述 |3069| 字段 | 描述 |

3068| :- | :- |3070| :- | :- |

3070 3072

3071CwdChanged hook 没有决策控制。它们无法阻止目录更改。3073CwdChanged hook 没有决策控制。它们无法阻止目录更改。

3072 3074

3073Claude Code 会从其 JSON 输出中读取 `watchPaths` 和 `systemMessage`，并丢弃 `continue`。在交互式会话中，它会将 `systemMessage` 显示为简短的终端通知。该消息不会进入 SDK 消息流。3075Claude Code 会从其 JSON 输出中读取 `watchPaths` 和 `systemMessage`，并丢弃 `continue`。在交互式会话中，它会将 `systemMessage` 显示为简短的终端通知。该消息不会到达 SDK 消息流。

3074 3076

3075<h3 id="directoryadded">3077<h3 id="directoryadded">

3076 DirectoryAdded3078 DirectoryAdded

3077</h3>3079</h3>

3078 3080

3079在您于会话中途使用 `/add-dir` 命令添加工作目录之后，或在 SDK 客户端通过 `register_repo_root` 控制请求添加工作目录之后运行。可用于准备新添加的仓库，例如安装其依赖。3081在您于会话中途使用 `/add-dir` 命令添加工作目录后，或 SDK 客户端使用 `register_repo_root` 控制请求添加工作目录后运行。可用于准备新添加的仓库，例如安装其依赖。

3080 3082

3081在以下情况下，Claude Code 不会触发此事件：3083在以下情况下，Claude Code 不会触发此事件：

3082 3084

3083* 您通过 `--add-dir` 启动标志传入目录；这些目录由 [SessionStart](#sessionstart) 覆盖3085* 您通过 `--add-dir` 启动标志传入目录；这些目录由 [SessionStart](#sessionstart) 处理

3084* 您在 `/permissions` 的 Workspace 选项卡上添加目录3086* 您在 `/permissions` 的 Workspace 选项卡上添加目录

3085* 您添加的目录已经是工作目录或位于某个工作目录内3087* 您添加的目录已经是工作目录或位于某个工作目录内

3086 3088

3087Claude Code 会在刷新沙箱和权限状态之后触发 DirectoryAdded，因此当您的 hook 运行时，沙箱化工具已经能看到新目录。hook 命令本身在沙箱之外运行。3089Claude Code 会在刷新沙箱和权限状态之后触发 DirectoryAdded，因此当您的 hook 运行时，沙箱中的工具已经可以看到新目录。hook 命令本身在沙箱之外运行。

3088 3090

3089Claude Code 不会等待该 hook：添加操作会立即完成，hook 在后台运行，使用 600 秒的默认超时时间。3091Claude Code 不会等待该 hook：添加操作会立即完成，hook 在后台运行，默认超时时间为 600 秒。

3090 3092

3091匹配器按目录的添加方式进行过滤：3093匹配器按目录的添加方式过滤：

3092 3094

3093| 匹配器 | 触发时机 |3095| 匹配器 | 触发时机 |

3094| :- | :- |3096| :- | :- |

3097 3099

3098<h4 id="directoryadded-input">3100<h4 id="directoryadded-input">

3099 DirectoryAdded 输入3101 DirectoryAdded 输入

3100</h4>3102</h4>

3101 3103

3102除了[通用输入字段](#common-input-fields)之外，DirectoryAdded hook 还会接收 `directory` 和 `source`。3104除了[通用输入字段](#common-input-fields)外，DirectoryAdded hook 还会接收 `directory` 和 `source`。

3103 3105

3104| 字段 | 描述 |3106| 字段 | 描述 |

3105| :- | :- |3107| :- | :- |

3108 3110

3109```json theme={null}3111```json theme={null}

3110{3112{

3119 3121

3120DirectoryAdded hook 没有决策控制。它们无法阻止添加操作，因为 hook 运行时添加已经完成。Claude Code 会丢弃其 JSON 输出中的 `continue` 字段，并根据来源以不同方式呈现其余内容：3122DirectoryAdded hook 没有决策控制。它们无法阻止添加操作，因为 hook 运行时添加已经完成。Claude Code 会丢弃其 JSON 输出中的 `continue` 字段，并根据来源以不同方式呈现其余内容：

3121 3123

3122* `slash_command`：Claude Code 会在下一个对话轮次中将 hook 的 `systemMessage` 作为上下文传递给 Claude，而不是向您显示。失败 hook 的数量会显示在会话记录中。完整的失败输出会写入调试日志3124* `slash_command`：Claude Code 会在下一个对话轮次中将 hook 的 `systemMessage` 作为上下文传递给 Claude，而不是向您显示。会话记录中会显示失败 hook 的数量。完整的失败输出会写入调试日志

3123* `register_repo_root`：Claude Code 仅将 `systemMessage` 输出和失败输出写入调试日志3125* `register_repo_root`：Claude Code 仅将 `systemMessage` 输出和失败输出写入调试日志

3124 3126

3125<h3 id="filechanged">3127<h3 id="filechanged">

3128 3130

3129当被监视的文件在磁盘上发生更改时运行。Claude Code 通过文件系统监视器而非检查工具调用来检测更改，因此无论是什么更改了文件，它都会运行该 hook：`Edit` 或 `Write` 工具调用、Claude 通过 `Bash` 运行的脚本，或完全在 Claude Code 之外的进程。一个常见用途是在项目配置文件更改时重新加载环境变量。3131当被监视的文件在磁盘上发生更改时运行。Claude Code 通过文件系统监视器而非检查工具调用来检测更改，因此无论是什么更改了文件，它都会运行该 hook：`Edit` 或 `Write` 工具调用、Claude 通过 `Bash` 运行的脚本，或完全在 Claude Code 之外的进程。一个常见用途是在项目配置文件更改时重新加载环境变量。

3130 3132

3131此事件的 `matcher` 有两个作用：3133此事件的 `matcher` 承担两个角色：

3132 3134

3133* **构建监视列表**：该值按 `|` 拆分，每个片段都被注册为工作目录中的字面文件名，因此 `".envrc|.env"` 恰好监视这两个文件。正则表达式模式在这里没有用处：像 `^\.env` 这样的值会监视一个字面名为 `^\.env` 的文件。3135* **构建监视列表**：该值按 `|` 拆分，每个片段都被注册为工作目录中的一个字面文件名，因此 `".envrc|.env"` 恰好监视这两个文件。正则表达式模式在这里没有用处：像 `^\.env` 这样的值会监视一个字面名为 `^\.env` 的文件。

3134* **过滤运行哪些 hook**：当被监视的文件发生更改时，同一个值会按照标准[匹配器规则](#matcher-patterns)，针对已更改文件的基本名称过滤运行哪些 hook 组。3136* **过滤要运行的 hook**：当被监视的文件发生更改时，同一个值会按照标准[匹配器规则](#matcher-patterns)，针对已更改文件的基本名称过滤要运行的 hook 组。

3135 3137

3136以下示例会在 `data.csv` 发生任何更改后（包括 `Bash` 命令或外部脚本重写该文件）规范化其行尾：3138以下示例会在 `data.csv` 发生任何更改（包括由 `Bash` 命令或外部脚本重写文件）后规范化其行尾：

3137 3139

3138```json theme={null}3140```json theme={null}

3139{3141{

3153}3155}

3154```3156```

3155 3157

3156该 hook 从 stdin 上 [JSON 输入](#filechanged-input)的 `file_path` 字段读取已更改文件的绝对路径。它的 `grep` 守卫检查的正是 `perl` 要删除的内容，即行尾的 CR，因此规范化之后的那次运行会直接退出而不触碰文件。较宽松的守卫会导致无限循环，因为即使没有替换任何内容，`perl -i` 也会重写文件，而 Claude Code 在每次重写后都会再次运行该 hook。请将此脚本保存到 `/path/to/normalize-line-endings.sh` 并使其可执行：3158该 hook 从 stdin 上 [JSON 输入](#filechanged-input)的 `file_path` 字段中读取已更改文件的绝对路径。其 `grep` 守卫检测的正是 `perl` 要移除的内容，即行尾的 CR，因此规范化之后的那次运行会直接退出而不触碰文件。更宽松的守卫会导致无限循环，因为即使没有替换任何内容，`perl -i` 也会重写文件，而 Claude Code 在每次重写后都会再次运行该 hook。将此脚本保存到 `/path/to/normalize-line-endings.sh` 并使其可执行：

3157 3159

3158```bash theme={null}3160```bash theme={null}

3159#!/bin/bash3161#!/bin/bash

3163fi3165fi

3164```3166```

3165 3167

3166要确认 hook 是否正常工作，请让 Claude 使用 `Bash` 命令向 `data.csv` 追加一行 CRLF。Claude Code 会运行该 hook，文件最终将使用 LF 行尾。3168要确认该 hook 正常工作，请让 Claude 使用 `Bash` 命令向 `data.csv` 追加一行 CRLF。Claude Code 会运行该 hook，文件最终会使用 LF 行尾。

3167 3169

3168要监视无法预先命名的文件，请从 hook 返回 [`watchPaths`](#filechanged-output) 以动态更新监视列表。只有当有内容指定了要监视的文件时，Claude Code 才会启动监视器，因此请用一个匹配器至少指定了一个文件的 FileChanged 组，或一个返回 `watchPaths` 的 [SessionStart](#sessionstart-decision-control) 或 [CwdChanged](#cwdchanged) hook 来初始化该列表。当被监视的文件发生更改时，匹配器仍会过滤运行哪些 hook 组，因此请为处理动态路径的组省略匹配器，这样它会匹配每个被监视的文件，且不会向监视列表添加任何内容。`"*"` 匹配器同样匹配每个文件，但 Claude Code 会像处理其他值一样将其注册到监视列表中，作为一个字面名为 `*` 的文件。3170要监视无法预先命名的文件，请从 hook 中返回 [`watchPaths`](#filechanged-output) 以动态更新监视列表。Claude Code 仅在有内容指定了要监视的文件时才会启动监视器，因此请用一个匹配器至少指定一个文件的 FileChanged 组，或用一个返回 `watchPaths` 的 [SessionStart](#sessionstart-decision-control) 或 [CwdChanged](#cwdchanged) hook 来初始化列表。当被监视的文件发生更改时，匹配器仍会过滤要运行的 hook 组，因此请为处理动态路径的组省略匹配器，这样它会匹配所有被监视的文件，且不会向监视列表添加任何内容。`"*"` 匹配器同样匹配所有文件，但 Claude Code 会像对待其他值一样将其注册到监视列表中，作为一个字面名为 `*` 的文件。

3169 3171

3170FileChanged hook 可以访问 [`CLAUDE_ENV_FILE`](#persist-environment-variables)。写入该文件的变量会在后续 Bash 命令中持续有效，直到下一个 [CwdChanged](#cwdchanged) 事件时由 Claude Code 清除。3172FileChanged hook 可以访问 [`CLAUDE_ENV_FILE`](#persist-environment-variables)。写入该文件的变量会持续作用于后续的 Bash 命令，直到下一个 [CwdChanged](#cwdchanged) 事件发生，届时 Claude Code 会清除它们。

3171 3173

3172<h4 id="filechanged-input">3174<h4 id="filechanged-input">

3173 FileChanged 输入3175 FileChanged 输入

3174</h4>3176</h4>

3175 3177

3176除了[通用输入字段](#common-input-fields)之外，FileChanged hook 还会接收 `file_path` 和 `event`。3178除了[通用输入字段](#common-input-fields)外，FileChanged hook 还会接收 `file_path` 和 `event`。

3177 3179

3178| 字段 | 描述 |3180| 字段 | 描述 |

3179| :- | :- |3181| :- | :- |

3195 FileChanged 输出3197 FileChanged 输出

3196</h4>3198</h4>

3197 3199

3198除了所有 hook 都可用的 [JSON 输出字段](#json-output)之外，FileChanged hook 还可以返回 `watchPaths`，以动态更新监视哪些文件路径：3200除了所有 hook 均可使用的 [JSON 输出字段](#json-output)外，FileChanged hook 还可以返回 `watchPaths`，以动态更新被监视的文件路径：

3199 3201

3200| 字段 | 描述 |3202| 字段 | 描述 |

3201| :- | :- |3203| :- | :- |

3203 3205

3204FileChanged hook 没有决策控制。它们无法阻止文件更改的发生。3206FileChanged hook 没有决策控制。它们无法阻止文件更改的发生。

3205 3207

3206Claude Code 会从其 JSON 输出中读取 `watchPaths` 和 `systemMessage`，并丢弃 `continue`。在交互式会话中，它会将 `systemMessage` 显示为简短的终端通知。该消息不会进入 SDK 消息流。3208Claude Code 会从其 JSON 输出中读取 `watchPaths` 和 `systemMessage`，并丢弃 `continue`。在交互式会话中，它会将 `systemMessage` 显示为简短的终端通知。该消息不会到达 SDK 消息流。

3207 3209

3208<h3 id="worktreecreate">3210<h3 id="worktreecreate">

3209 WorktreeCreate3211 WorktreeCreate

3210</h3>3212</h3>

3211 3213

3212在创建 worktree 时运行，无论是来自 `claude --worktree`、来自[使用 `isolation: "worktree"` 的子代理](/docs/zh-CN/sub-agents#choose-the-subagent-scope)，还是用于 Claude Code 隔离在其自身 worktree 中的[后台会话](/docs/zh-CN/agent-view#how-file-edits-are-isolated)。默认情况下，Claude Code 使用 `git worktree` 创建隔离的工作副本。配置 WorktreeCreate hook 会替换该默认 git 行为，让您可以使用 SVN、Perforce 或 Mercurial 等其他版本控制系统。3214在创建 worktree 时运行，无论是通过 `claude --worktree`、通过[使用 `isolation: "worktree"` 的子代理](/docs/zh-CN/sub-agents#choose-the-subagent-scope)，还是为 Claude Code 隔离在其自身 worktree 中的[后台会话](/docs/zh-CN/agent-view#how-file-edits-are-isolated)创建。默认情况下，Claude Code 使用 `git worktree` 创建隔离的工作副本。配置 WorktreeCreate hook 会替换此默认的 git 行为，让您可以使用其他版本控制系统，例如 SVN、Perforce 或 Mercurial。

3213 3215

3214由于该 hook 完全替换了默认行为，因此不会处理 [`.worktreeinclude`](/docs/zh-CN/worktrees#copy-gitignored-files-into-worktrees)。如果您需要将 `.env` 等本地配置文件复制到新的 worktree 中，请在您的 hook 脚本中完成。3216由于该 hook 完全替换了默认行为，因此不会处理 [`.worktreeinclude`](/docs/zh-CN/worktrees#copy-gitignored-files-into-worktrees)。如果需要将 `.env` 等本地配置文件复制到新的 worktree 中，请在 hook 脚本中完成。

3215 3217

3216该 hook 必须返回所创建 worktree 目录的路径。Claude Code 将此路径用作隔离会话的工作目录。有关每种 hook 类型如何返回路径，请参阅 [WorktreeCreate 输出](#worktreecreate-output)。3218该 hook 必须返回所创建 worktree 目录的路径。Claude Code 将此路径用作隔离会话的工作目录。有关每种 hook 类型如何返回路径，请参阅 [WorktreeCreate 输出](#worktreecreate-output)。

3217 3219

3218Claude Code 会根据 hook 的成功状态和返回的路径采取行动，并丢弃 `systemMessage` 和 `continue`。3220Claude Code 依据 hook 是否成功以及返回的路径执行操作，并丢弃 `systemMessage` 和 `continue`。

3219 3221

3220以下示例创建一个 SVN 工作副本，并打印路径供 Claude Code 使用。请将仓库 URL 替换为您自己的 URL：3222此示例创建一个 SVN 工作副本，并打印路径供 Claude Code 使用。请将仓库 URL 替换为您自己的 URL：

3221 3223

3222```json theme={null}3224```json theme={null}

3223{3225{

3236}3238}

3237```3239```

3238 3240

3239该 hook 从 stdin 上的 JSON 输入中读取 worktree 的 `name`，将全新副本检出到新目录中，并打印目录路径。最后一行的 `echo` 就是 Claude Code 读取为 worktree 路径的内容。请将任何其他输出重定向到 stderr，以免干扰该路径。3241该 hook 从 stdin 上的 JSON 输入中读取 worktree 的 `name`，将一个全新副本检出到新目录中，并打印目录路径。最后一行的 `echo` 就是 Claude Code 读取为 worktree 路径的内容。请将其他所有输出重定向到 stderr，以免干扰路径。

3240 3242

3241<h4 id="worktreecreate-input">3243<h4 id="worktreecreate-input">

3242 WorktreeCreate 输入3244 WorktreeCreate 输入

3243</h4>3245</h4>

3244 3246

3245除了[通用输入字段](#common-input-fields)之外，WorktreeCreate hook 还会接收 `name` 字段。这是新 worktree 的 slug 标识符，由用户指定或自动生成，例如 `bold-oak-a3f2`。3247除[通用输入字段](#common-input-fields)外，WorktreeCreate hook 还会接收 `name` 字段。这是新 worktree 的 slug 标识符，由用户指定或自动生成，例如 `bold-oak-a3f2`。

3246 3248

3247```json theme={null}3249```json theme={null}

3248{3250{

3258 WorktreeCreate 输出3260 WorktreeCreate 输出

3259</h4>3261</h4>

3260 3262

3261WorktreeCreate hook 不使用标准的允许/阻止决策模型，而是由 hook 的成功或失败决定结果。hook 必须返回所创建的 worktree 目录的路径：3263WorktreeCreate hook 不使用标准的允许/阻止决策模型，而是由 hook 的成功或失败决定结果。该 hook 必须返回所创建 worktree 目录的路径：

3262 3264

3263* **命令 hook**（`type: "command"`）：将路径作为 stdout 的最后一个非空行打印。Claude Code 在读取该行之前会去除 ANSI 转义码，因此在您的 `echo` 之前打印的 shell 启动横幅会被忽略。请将其他任何 hook 输出重定向到 stderr。3265* **命令 hook**（`type: "command"`）：将路径作为 stdout 的最后一个非空行打印。Claude Code 在读取该行之前会去除 ANSI 转义码，因此在 `echo` 之前打印的 shell 启动横幅会被忽略。请将 hook 的其他所有输出重定向到 stderr。

3264* **HTTP hook**（`type: "http"`）：在响应体中返回 `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }`。3266* **HTTP hook**（`type: "http"`）：在响应正文中返回 `{ "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } }`。

3265 3267

3266如果 hook 失败或未生成路径，worktree 创建将失败并报错。3268如果 hook 失败或未生成路径，worktree 创建将失败并报错。

3267 3269

3268Claude Code 会相对于 hook 运行所在的目录解析相对路径，并折叠其中的任何 `.` 或 `..` 段。如果解析得到的路径不是 Claude Code 可以进入的目录，会话会打印一条指明该路径的错误，并以代码 1 退出。3270Claude Code 会相对于 hook 运行时所在的目录解析相对路径，并折叠其中的 `.` 或 `..` 段。如果生成的路径不是 Claude Code 可以进入的目录，会话会打印一条指明该路径的错误，并以退出码 1 退出。

3269 3271

3270Claude Code 会拒绝包含 `.` 或 `..` 段的绝对路径，以及任何经过仓库根目录下符号链接的路径，因为提交到仓库中的符号链接可能会将 worktree 重定向到仓库之外。错误信息会指明被拒绝的路径组成部分。请返回一个规范化的、不经过仓库内符号链接的路径。在 v2.1.216 之前，worktree 创建会直接采用 hook 返回的路径，不进行此项检查。3272Claude Code 会拒绝包含 `.` 或 `..` 段的绝对路径，以及任何经过仓库根目录下符号链接的路径，因为提交到仓库中的符号链接可能会将 worktree 重定向到仓库之外。错误信息会指明被拒绝的路径组成部分。请返回一个规范化的、不经过仓库内符号链接的路径。在 v2.1.216 之前，worktree 创建会直接使用 hook 返回的路径，不进行此项检查。

3271 3273

3272<h3 id="worktreeremove">3274<h3 id="worktreeremove">

3273 WorktreeRemove3275 WorktreeRemove

3274</h3>3276</h3>

3275 3277

3276当 Claude Code 清理由您的 [`WorktreeCreate`](#worktreecreate) hook 创建的 worktree 时运行。该事件在以下情况下触发：3278在 Claude Code 清理由您的 [`WorktreeCreate`](#worktreecreate) hook 创建的 worktree 时运行。该事件在以下情况下触发：

3277 3279

3278* 您退出交互式 [worktree 会话](/docs/zh-CN/worktrees#start-claude-in-a-worktree)，并在 Claude Code 提示时选择删除该 worktree3280* 您退出交互式 [worktree 会话](/docs/zh-CN/worktrees#start-claude-in-a-worktree)，并在 Claude Code 提示时选择删除该 worktree

3279* 您退出一个尚未[命名](/docs/zh-CN/sessions#name-your-sessions)的交互式 worktree 会话，Claude Code 未发现已更改或未跟踪的文件，并在不提示您的情况下删除该 worktree3281* 您退出一个尚未[命名](/docs/zh-CN/sessions#name-your-sessions)的交互式 worktree 会话，Claude Code 未发现已更改或未跟踪的文件，并在不提示的情况下删除该 worktree

3280* 您删除在该 worktree 中运行的[后台会话](/docs/zh-CN/agent-view#what-deleting-a-session-removes)3282* 您删除一个在该 worktree 中运行的[后台会话](/docs/zh-CN/agent-view#what-deleting-a-session-removes)

3281 3283

3282Claude Code 使用 git 查找已更改或未跟踪的文件，因此对于不是 git checkout 或不在 git checkout 内的 worktree，即使目录中有未提交的工作，它也找不到任何文件。请在 WorktreeRemove hook 删除任何内容之前检查这类工作。3284Claude Code 使用 git 查找已更改或未跟踪的文件，因此对于不是 git 检出或不位于 git 检出内的 worktree，即使目录中有未提交的工作，它也找不到任何内容。请在 WorktreeRemove hook 删除任何内容之前检查此类工作。

3283 3285

3284对于基于 git 的 worktree，Claude Code 会使用 `git worktree remove` 自动处理清理。如果您配置了 WorktreeCreate hook，请搭配一个 WorktreeRemove hook，以控制其所创建的 worktree 的清理：3286对于基于 git 的 worktree，Claude Code 会使用 `git worktree remove` 自动处理清理。如果您配置了 WorktreeCreate hook，请将其与 WorktreeRemove hook 配对使用，以控制对其所创建 worktree 的清理：

3285 3287

3286* **没有 WorktreeRemove hook**：当 Claude Code 在您退出 worktree 会话时删除该 worktree，它会回退到对 WorktreeCreate hook 返回的路径执行 `git worktree remove --force`，因此 git 能识别的 worktree 会被删除。git 无法识别的 worktree（例如您的 hook 使用非 git 版本控制系统创建的 worktree）会保留在磁盘上。关于删除[后台会话](/docs/zh-CN/agent-view#what-deleting-a-session-removes)时如何处理由 hook 创建的 worktree，请参阅 agent view 的删除规则。3288* **没有 WorktreeRemove hook**：当您退出 worktree 会话、Claude Code 删除该 worktree 时，它会回退为对您的 WorktreeCreate hook 返回的路径执行 `git worktree remove --force`，因此 git 能识别的 worktree 会被删除。git 无法识别的 worktree（例如您的 hook 使用非 git 版本控制系统创建的 worktree）会保留在磁盘上。有关删除[后台会话](/docs/zh-CN/agent-view#what-deleting-a-session-removes)时如何处理由 hook 创建的 worktree，请参阅 agent view 的删除规则。

3287* **Hook 以 0 退出**：该 worktree 视为已移除。Claude Code 不会从 hook 读取其他任何内容，因此请确保您的 hook 已删除该目录。3289* **Hook 以 0 退出**：该 worktree 被视为已删除。Claude Code 不会从 hook 读取其他任何内容，因此请确保您的 hook 已删除该目录。

3288* **Hook 以非零值退出**：如果 `worktree_path` 处的目录在之后仍然存在，则移除失败，worktree 保留在磁盘上，且不会回退到 git。在以非零值退出之前已删除目录的 hook 视为已移除。关于失败的报告方式，请参阅 [WorktreeRemove 输入](#worktreeremove-input)。3290* **Hook 以非零值退出**：如果之后 `worktree_path` 处的目录仍然存在，则删除失败，worktree 保留在磁盘上，且不会回退到 git。在以非零值退出之前已删除目录的 hook 被视为已删除。有关如何报告失败，请参阅 [WorktreeRemove 输入](#worktreeremove-input)。

3289 3291

3290Claude Code 从不删除属于 hook 创建的 worktree 的分支，因为它只知道您的 WorktreeCreate hook 返回的路径。如果您的 WorktreeCreate hook 创建了分支，请在 WorktreeRemove hook 中删除该分支。3292Claude Code 永远不会删除属于由 hook 创建的 worktree 的分支，因为它只知道您的 WorktreeCreate hook 返回的路径。如果您的 WorktreeCreate hook 创建了分支，请在 WorktreeRemove hook 中删除它。

3291 3293

3292Claude Code 会丢弃 WorktreeRemove hook 的 [JSON 输出字段](#json-output)，例如 `systemMessage` 和 `continue`。3294Claude Code 会丢弃 WorktreeRemove hook 的 [JSON 输出字段](#json-output)，例如 `systemMessage` 和 `continue`。

3293 3295

3294对于后台会话的删除，Claude Code 会在运行 hook 之前验证存储的 worktree 路径，并拒绝本身是符号链接或经过仓库根目录下符号链接的路径。对于仍包含文件的 worktree，只有当您在 [Agent 视图](/docs/zh-CN/agent-view#what-deleting-a-session-removes)中确认删除时，hook 才会运行；对于这类 worktree，[`claude rm`](/docs/zh-CN/agent-view#manage-sessions-from-the-shell) 会保留会话和 worktree。在 v2.1.216 之前，hook 会直接在存储的路径上运行，不进行这些检查。3296对于后台会话删除，Claude Code 会在运行 hook 之前验证存储的 worktree 路径，并拒绝本身是符号链接或经过仓库根目录下符号链接的路径。对于仍包含文件的 worktree，只有当您在 [agent view](/docs/zh-CN/agent-view#what-deleting-a-session-removes) 中确认删除时，hook 才会运行；对于此类 worktree，[`claude rm`](/docs/zh-CN/agent-view#manage-sessions-from-the-shell) 会保留会话和 worktree。在 v2.1.216 之前，hook 会在未经这些检查的情况下对存储的路径运行。

3295 3297

3296Claude Code 会将 WorktreeCreate 返回的路径作为 hook 输入中的 `worktree_path` 传入。以下示例读取该路径并删除该目录：3298Claude Code 会将 WorktreeCreate 返回的路径作为 hook 输入中的 `worktree_path` 传递。此示例读取该路径并删除目录：

3297 3299

3298```json theme={null}3300```json theme={null}

3299{3301{

3316 WorktreeRemove 输入3318 WorktreeRemove 输入

3317</h4>3319</h4>

3318 3320

3319除[通用输入字段](#common-input-fields)外，WorktreeRemove hook 还会接收 `worktree_path` 字段，即正在移除的 worktree 的绝对路径。3321除[通用输入字段](#common-input-fields)外，WorktreeRemove hook 还会接收 `worktree_path` 字段，即要删除的 worktree 的绝对路径。

3320 3322

3321```json theme={null}3323```json theme={null}

3322{3324{

3328}3330}

3329```3331```

3330 3332

3331WorktreeRemove hook 的退出码决定结果。当 hook 以非零值退出且 `worktree_path` 处的目录之后仍然存在时，移除失败：3333WorktreeRemove hook 的退出码决定结果。当 hook 以非零值退出，且之后 `worktree_path` 处的目录仍然存在时，删除失败：

3332 3334

3333* worktree 保留在磁盘上，hook 的命令和 stderr 会写入[调试日志](#debug-hooks)。3335* worktree 保留在磁盘上，hook 的命令和 stderr 会写入[调试日志](#debug-hooks)。

3334* 如果您正在删除后台会话，该会话也会保留。[Agent 视图](/docs/zh-CN/agent-view#what-deleting-a-session-removes)中的拒绝消息会报告 hook 的结束方式（例如 `exited 1`），引用其 stderr 的开头部分，并说明再次删除该会话是否仍会移除该目录。3336* 如果您正在删除后台会话，该会话也会保留。[agent view](/docs/zh-CN/agent-view#what-deleting-a-session-removes) 中的拒绝消息会报告 hook 的结束方式（例如 `exited 1`），引用其 stderr 的开头部分，并说明再次删除该会话是否仍会删除该目录。

3335 3337

3336<h3 id="precompact">3338<h3 id="precompact">

3337 PreCompact3339 PreCompact

3339 3341

3340在 Claude Code 即将执行压缩操作之前运行。3342在 Claude Code 即将执行压缩操作之前运行。

3341 3343

3342匹配器值表示压缩是手动触发还是自动触发：3344匹配器值表示压缩是手动触发还是自动触发的：

3343 3345

3344| 匹配器 | 触发时机 |3346| 匹配器 | 触发时机 |

3345| :- | :- |3347| :- | :- |

3348 3350

3349以代码 2 退出可阻止压缩。对于手动 `/compact`，stderr 消息会显示给用户。您也可以通过返回带有 `"decision": "block"` 的 JSON 来阻止。3351以退出码 2 退出可阻止压缩。对于手动 `/compact`，stderr 消息会显示给用户。您也可以通过返回包含 `"decision": "block"` 的 JSON 来阻止。

3350 3352

3351阻止自动压缩的效果取决于其触发时机。如果压缩是在达到上下文限制之前主动触发的，Claude Code 会跳过压缩，对话在未压缩的情况下继续。如果压缩是为了从 API 已返回的上下文限制错误中恢复而触发的，底层错误会显示出来，当前请求失败。3353阻止自动压缩的效果取决于其触发时机。如果压缩是在达到上下文限制之前主动触发的，Claude Code 会跳过它，对话在未压缩的情况下继续。如果压缩是为了从 API 已返回的上下文限制错误中恢复而触发的，则底层错误会显示出来，当前请求失败。

3352 3354

3353Claude Code 会丢弃 PreCompact hook 的 `systemMessage` 和 `continue` 字段。3355Claude Code 会丢弃 PreCompact hook 的 `systemMessage` 和 `continue` 字段。

3354 3356

3356 PreCompact 输入3358 PreCompact 输入

3357</h4>3359</h4>

3358 3360

3359除[通用输入字段](#common-input-fields)外，PreCompact hook 还会接收 `trigger` 和 `custom_instructions`。对于 `manual`，`custom_instructions` 包含用户传给 `/compact` 的内容，用户未传入任何内容时为 `null`。对于 `auto`，`custom_instructions` 为 `null`。3361除[通用输入字段](#common-input-fields)外，PreCompact hook 还会接收 `trigger` 和 `custom_instructions`。对于 `manual`，`custom_instructions` 包含用户传入 `/compact` 的内容，未传入任何内容时为 `null`。对于 `auto`，`custom_instructions` 为 `null`。

3360 3362

3361```json theme={null}3363```json theme={null}

3362{3364{

3373 PostCompact3375 PostCompact

3374</h3>3376</h3>

3375 3377

3376在 Claude Code 完成压缩操作后运行。使用此事件对压缩后的新状态作出响应，例如记录生成的摘要或更新外部状态。Claude Code 会丢弃 PostCompact hook 的 `systemMessage` 和 `continue` 字段。3378在 Claude Code 完成压缩操作后运行。使用此事件对新的压缩状态作出响应，例如记录生成的摘要或更新外部状态。Claude Code 会丢弃 PostCompact hook 的 `systemMessage` 和 `continue` 字段。

3377 3379

3378适用与 `PreCompact` 相同的匹配器值：3380适用与 `PreCompact` 相同的匹配器值：

3379 3381

3405 PreModelSwitch3407 PreModelSwitch

3406</h3>3408</h3>

3407 3409

3408在 Claude Code 应用您或客户端请求的模型切换之前运行。可用于阻止切换、要求确认，或在切换发生前显示切换的成本。3410在 Claude Code 应用由您或客户端请求的模型切换之前运行。可用于阻止切换、要求确认，或在切换发生前显示切换的成本。

3409 3411

3410PreModelSwitch 需要 Claude Code v2.1.251 或更高版本。Claude Code 会针对以下请求运行它：3412PreModelSwitch 需要 Claude Code v2.1.251 或更高版本。Claude Code 会针对以下请求运行它：

3411 3413

3412* `/model <name>` 和 `/model` 选择器3414* `/model <name>` 和 `/model` 选择器

3413* `Option+P` 或 `Alt+P` 模型选择器3415* `Option+P` 或 `Alt+P` 模型选择器

3414* `/config` 中的 Model 设置3416* `/config` 中的 Model 设置

3415* 启用[快速模式](/docs/zh-CN/fast-mode)且这会改变会话的模型时3417* 启用[快速模式](/docs/zh-CN/fast-mode)且这会更改会话的模型时

3416* 来自 [Agent SDK](/docs/zh-CN/agent-sdk/typescript#query-object) 宿主或 [Remote Control](/docs/zh-CN/remote-control) 的 `set_model` 请求，或 `apply_flag_settings` 请求中的模型更改3418* 来自 [Agent SDK](/docs/zh-CN/agent-sdk/typescript#query-object) 宿主或 [Remote Control](/docs/zh-CN/remote-control) 的 `set_model` 请求，或 `apply_flag_settings` 请求中的模型更改

3417 3419

3418对于 Claude Code 自行进行的切换，例如[自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)或在您恢复会话时恢复模型，Claude Code 不会运行 PreModelSwitch hook。这些更改只会触发 [PostModelSwitch](#postmodelswitch)。3420对于 Claude Code 自行执行的切换，例如[自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)或恢复会话时还原模型，Claude Code 不会运行 PreModelSwitch hook。这些更改只会触发 [PostModelSwitch](#postmodelswitch)。

3419 3421

3420Claude Code 会将匹配器与会话要切换到的模型的规范名称进行比较，忽略任何 `[1m]` 后缀。别名（如 `opus`）、带日期的模型 ID 以及特定于提供商的 ID（如 Amazon Bedrock 模型 ID）都会匹配它们所解析到的同一个规范名称，因此 `claude-opus-5` 涵盖 Opus 5 的所有写法。3422Claude Code 会将匹配器与会话要切换到的模型的规范名称进行比较，并忽略任何 `[1m]` 后缀。别名（如 `opus`）、带日期的模型 ID 以及特定提供商的 ID（如 Amazon Bedrock 模型 ID）都会匹配它们所解析到的同一个规范名称，因此 `claude-opus-5` 涵盖 Opus 5 的所有写法。

3421 3423

3422当 Claude Code 无法确定目标的规范名称时，例如只有您的 [LLM 网关](/docs/zh-CN/llm-gateway)才知道的自定义模型 ID，它会运行所有 PreModelSwitch hook，无论匹配器如何。因此，执行阻止的 hook 应检查其输入中的 `to_model`，而不是仅依赖匹配器。3424当 Claude Code 无法确定目标的规范名称时（例如只有您的 [LLM 网关](/docs/zh-CN/llm-gateway)知道的自定义模型 ID），它会运行所有 PreModelSwitch hook，无论匹配器为何。因此，用于阻止的 hook 应检查其输入中的 `to_model`，而不是仅依赖匹配器。

3423 3425

3424匹配器可以写为确切名称、以 `|` 分隔的列表（如 `claude-opus-4-6|claude-opus-5`），或正则表达式（如 `.*opus.*`）。以下示例使用确切名称匹配器，同时检查 hook 输入中的 `to_model`，因此它会通过以代码 2 退出来拒绝切换到 Opus 4.6，并允许切换到任何其他目标：3426匹配器可以写成精确名称、以 `|` 分隔的列表（如 `claude-opus-4-6|claude-opus-5`），或正则表达式（如 `.*opus.*`）。此示例使用精确名称匹配器，同时检查 hook 输入中的 `to_model`，因此它通过以退出码 2 退出来拒绝切换到 Opus 4.6，并允许切换到任何其他目标：

3425 3427

3426<Tabs>3428<Tabs>

3427 <Tab title="macOS/Linux">3429 <Tab title="macOS/Linux">

3474 }3476 }

3475 ```3477 ```

3476 3478

3477 将以下脚本保存到项目中的 `.claude/hooks/block-opus-46.ps1`：3479 将此脚本保存到项目中的 `.claude/hooks/block-opus-46.ps1`：

3478 3480

3479 ```powershell theme={null}3481 ```powershell theme={null}

3480 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json3482 $hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json

3487 </Tab>3489 </Tab>

3488</Tabs>3490</Tabs>

3489 3491

3490要确认 hook 是否生效，请在运行其他模型的会话中运行 `/model claude-opus-4-6`。Claude Code 会保留当前模型，并报告 PreModelSwitch hook 阻止了切换，同时将您的消息作为原因。3492要确认 hook 是否生效，请在运行其他模型的会话中运行 `/model claude-opus-4-6`。Claude Code 会保留当前模型，并报告 PreModelSwitch hook 阻止了切换，以您的消息作为原因。

3491 3493

3492<h4 id="premodelswitch-input">3494<h4 id="premodelswitch-input">

3493 PreModelSwitch 输入3495 PreModelSwitch 输入

3494</h4>3496</h4>

3495 3497

3496除[通用输入字段](#common-input-fields)外，PreModelSwitch hook 还会接收下表中的字段。最后五个字段描述将对话重新发送给新模型的成本，以便 hook 在切换发生之前显示该数值。3498除[通用输入字段](#common-input-fields)外，PreModelSwitch hook 还会接收下表中的字段。最后五个字段描述将对话重新发送到新模型的成本，以便 hook 可以在切换发生之前显示该数字。

3497 3499

3498| 字段 | 类型 | 描述 |3500| 字段 | 类型 | 描述 |

3499| :- | :- | :- |3501| :- | :- | :- |

3503| `source` | string | 请求的来源：`"command"` 表示 `/model <name>`、`/config` 中的 Model 设置或启用快速模式；`"picker"` 表示模型选择器；`"sdk"` 表示来自 Agent SDK 宿主或 Remote Control 的 `set_model` 请求，或 `apply_flag_settings` 请求中的模型更改 |3505| `source` | string | 请求的来源：`"command"` 表示 `/model <name>`、`/config` 中的 Model 设置或启用快速模式；`"picker"` 表示模型选择器；`"sdk"` 表示来自 Agent SDK 宿主或 Remote Control 的 `set_model` 请求，或 `apply_flag_settings` 请求中的模型更改 |

3508| `pricing` | string | Claude Code 为 `estimated_cache_write_usd` 定价的方式：`"configured"` 表示按您的组织已配置的自有费率，`"catalog"` 表示按标价，`"default"` 表示 `to_model` 没有已知价格，Claude Code 采用了默认费率 |3510| `pricing` | string | Claude Code 如何为 `estimated_cache_write_usd` 定价：`"configured"` 表示在您的组织已配置费率时按其自有费率计算，`"catalog"` 表示按标价计算，`"default"` 表示 `to_model` 没有已知价格、Claude Code 采用了默认费率 |

3509 3511

3510以下示例展示在运行 Sonnet 5 的会话中执行 `/model opus` 时的输入：3512此示例显示在运行 Sonnet 5 的会话中执行 `/model opus` 时的输入：

3511 3513

3512```json theme={null}3514```json theme={null}

3513{3515{

3531 PreModelSwitch 决策控制3533 PreModelSwitch 决策控制

3532</h4>3534</h4>

3533 3535

3534`PreModelSwitch` hook 可以取消切换、请用户确认切换，或允许切换继续。退出码 2 或顶层的 `decision: "block"` 会取消切换。3536`PreModelSwitch` hook 可以取消切换、请用户确认，或让切换继续进行。退出码 2 或顶层 `decision: "block"` 会取消切换。

3535 3537

3536如需更精细的控制，请在 `hookSpecificOutput` 对象中返回 `permissionDecision` 和 `permissionDecisionReason`，与 [PreToolUse](#pretooluse-decision-control) 相同。`PreModelSwitch` 接受 `"allow"`、`"deny"` 和 `"ask"`。它不接受 `"defer"`、`updatedInput` 或 `additionalContext`。下表描述这两个字段：3538如需更精细的控制，请在 `hookSpecificOutput` 对象中返回 `permissionDecision` 和 `permissionDecisionReason`，与 [PreToolUse](#pretooluse-decision-control) 相同。`PreModelSwitch` 接受 `"allow"`、`"deny"` 和 `"ask"`，不接受 `"defer"`、`updatedInput` 或 `additionalContext`。下表描述了这两个字段：

3537 3539

3538| 字段 | 描述 |3540| 字段 | 描述 |

3539| :- | :- |3541| :- | :- |

3540| `permissionDecision` | `"allow"` 继续切换，并跳过[提示缓存处于预热状态时 Claude Code 显示的确认](/docs/zh-CN/prompt-caching#switching-models)。`"deny"` 取消切换。`"ask"` 提示用户进行确认 |3542| `permissionDecision` | `"allow"` 继续切换，并跳过[提示缓存处于热状态时 Claude Code 显示的确认](/docs/zh-CN/prompt-caching#switching-models)。`"deny"` 取消切换。`"ask"` 提示用户确认 |

3542 3544

3543只有交互式会话中的 `/model` 才能显示 `"ask"` 提示。在其他所有使用入口上，包括使用 `-p` 标志的非交互模式、`/config` 和 `set_model` 请求，Claude Code 都会将 `"ask"` 视为拒绝。3545只有交互式会话中的 `/model` 才能显示 `"ask"` 提示。在其他所有使用入口上，包括使用 `-p` 标志的非交互模式、`/config` 和 `set_model` 请求，Claude Code 都会将 `"ask"` 视为拒绝。

3544 3546

3545以下示例请用户确认，并引用 `context_tokens` 中的 token 数：3547此示例请用户确认，并引用 `context_tokens` 中的 token 数：

3546 3548

3547```json theme={null}3549```json theme={null}

3548{3550{

3556 3558

3557当多个 PreModelSwitch hook 返回不同的决策时，优先级为 `deny` > `ask` > `allow`。3559当多个 PreModelSwitch hook 返回不同的决策时，优先级为 `deny` > `ask` > `allow`。

3558 3560

3559无论决策如何，Claude Code 都会向用户显示 hook 返回的任何 `systemMessage`，因此成本报告 hook 可以返回 `{"systemMessage": "..."}` 并以 0 退出。3561无论决策如何，Claude Code 都会向用户显示您的 hook 返回的任何 `systemMessage`，因此用于报告成本的 hook 可以返回 `{"systemMessage": "..."}` 并以 0 退出。

3560 3562

3561在超时前未响应的 PreModelSwitch hook 会阻止切换。相比之下，在 [PreToolUse](#timeouts) 上，超时的命令 hook 会让工具调用继续。此事件的默认超时时间为 30 秒。`PreModelSwitch` 仅运行 `command`、`http` 和 `mcp_tool` hook，因此 `prompt` 和 `agent` 的默认值不适用。3563未在超时时间内响应的 PreModelSwitch hook 会阻止切换。相比之下，在 [PreToolUse](#timeouts) 上，超时的命令 hook 会让工具调用继续进行。此事件的默认超时时间为 30 秒。`PreModelSwitch` 仅运行 `command`、`http` 和 `mcp_tool` hook，因此 `prompt` 和 `agent` 的默认值不适用。

3562 3564

3563以 0 或 2 以外的代码退出且未打印 JSON 决策的 hook 不会阻止切换：Claude Code 会显示其 stderr 并应用切换，如[其他退出码](#other-exit-codes)中所述。3565以 0 或 2 以外的代码退出且未打印 JSON 决策的 hook 不会阻止切换：Claude Code 会显示其 stderr 并应用切换，如[其他退出码](#other-exit-codes)中所述。

3564 3566

3566 PostModelSwitch3568 PostModelSwitch

3567</h3>3569</h3>

3568 3570

3569在会话的模型更改后运行。可用于向 Claude 提供特定于模型的指导，而无需编辑每个 CLAUDE.md，例如适用于某些模型的组织级指令。3571在会话的模型更改后运行。可用于在不编辑每个 CLAUDE.md 的情况下为 Claude 提供特定于模型的指导，例如适用于某些模型的全组织范围指令。

3570 3572

3571PostModelSwitch 需要 Claude Code v2.1.251 或更高版本。它无法阻止，因为模型已经更改。Claude Code 会在以下任何更改后运行 PostModelSwitch hook：3573PostModelSwitch 需要 Claude Code v2.1.251 或更高版本。它无法阻止，因为模型已经更改。Claude Code 会在以下任一更改之后运行 PostModelSwitch hook：

3572 3574

3573* 您或客户端请求的切换3575* 您或客户端请求的切换

3574* [自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)，它会更改会话的模型3576* [自动模型回退](/docs/zh-CN/model-config#automatic-model-fallback)，这会更改会话的模型

3575* [`opusplan`](/docs/zh-CN/model-config#opusplan-model-setting) 等设置在进入或退出计划模式时3577* 诸如 [`opusplan`](/docs/zh-CN/model-config#opusplan-model-setting) 之类的设置进入或离开计划模式

3576* 您恢复会话时 Claude Code 恢复模型3578* 恢复会话时 Claude Code 还原模型

3577 3579

3578当[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)中的模型为某一轮次提供服务时，Claude Code 不会运行 PostModelSwitch hook，因为这种替换只持续一轮，会话的模型保持不变。3580当[备用模型链](/docs/zh-CN/model-config#fallback-model-chains)中的某个模型服务于某一轮次时，Claude Code 不会运行 PostModelSwitch hook，因为该替换仅持续一轮，且不会更改会话的模型。

3579 3581

3580匹配器遵循与 [PreModelSwitch](#premodelswitch) 相同的规则：Claude Code 将其与会话所切换到的模型的规范名称进行比较。3582匹配器遵循与 [PreModelSwitch](#premodelswitch) 相同的规则：Claude Code 会将其与会话切换到的模型的规范名称进行比较。

3581 3583

3582以下示例在会话的模型更改为任何 Opus 模型时添加指导：3584此示例在会话的模型更改为任何 Opus 模型时添加指导：

3583 3585

3584```json theme={null}3586```json theme={null}

3585{3587{

3599}3601}

3600```3602```

3601 3603

3602要确认 hook 是否生效，请在运行其他模型的会话中切换到 Opus 模型，例如在 Sonnet 会话中运行 `/model opus`，然后询问 Claude 它对当前模型有哪些指导。3604要确认 hook 是否生效，请在运行其他模型的会话中切换到 Opus 模型，例如在 Sonnet 会话中运行 `/model opus`，然后询问 Claude 它对当前模型有什么指导。

3603 3605

3604<h4 id="postmodelswitch-input">3606<h4 id="postmodelswitch-input">

3605 PostModelSwitch 输入3607 PostModelSwitch 输入

3606</h4>3608</h4>

3607 3609

3608PostModelSwitch hook 接收与 [PreModelSwitch](#premodelswitch-input) 相同的字段，其中 `hook_event_name` 设置为 `"PostModelSwitch"`，并增加两个 `source` 值：`"auto"` 表示自动回退或 Claude Code 自行进行的其他更改，`"resume"` 表示您恢复会话时恢复的模型。3610PostModelSwitch hook 接收与 [PreModelSwitch](#premodelswitch-input) 相同的字段，其中 `hook_event_name` 设置为 `"PostModelSwitch"`，并且 `source` 多两个值：`"auto"` 表示自动回退或 Claude Code 自行做出的其他更改，`"resume"` 表示恢复会话时还原的模型。

3609 3611

3610当 `source` 为 `"auto"` 时，`requested_model` 为 `null`。当 `source` 为 `"resume"` 时，它是 Claude Code 恢复的已保存模型设置。3612当 `source` 为 `"auto"` 时，`requested_model` 为 `null`。当 `source` 为 `"resume"` 时，它是 Claude Code 还原的已保存模型设置。

3611 3613

3612<h4 id="postmodelswitch-decision-control">3614<h4 id="postmodelswitch-decision-control">

3613 PostModelSwitch 决策控制3615 PostModelSwitch 决策控制

3614</h4>3616</h4>

3615 3617

3616Claude Code 会在退出码为 0 时获取 hook 的[纯文本 stdout](#exit-code-0)，或获取 JSON 输出中的 `additionalContext`，并在切换后随下一个请求将其传递给 Claude。除所有 hook 均可用的 [JSON 输出字段](#json-output)外，您还可以返回：3618Claude Code 会在退出码为 0 时获取 hook 的[纯文本 stdout](#exit-code-0)，或从 JSON 输出中获取 `additionalContext`，并在切换后的下一个请求中将其传递给 Claude。除所有 hook 均可使用的 [JSON 输出字段](#json-output)外，您还可以返回：

3617 3619

3618| 字段 | 描述 |3620| 字段 | 描述 |

3619| :- | :- |3621| :- | :- |

3621 3623

3622如果在您发送下一个提示词后五秒内 hook 仍未完成，Claude Code 会在不含该输出的情况下发送该请求，并改为将输出附加到再下一个请求。如果模型在下一个请求之前更改了多次，Claude Code 只会传递最后一次切换的目标模型对应的输出。3624如果在您发送下一个提示词后五秒内 hook 仍未完成，Claude Code 会在不附带该输出的情况下发送该请求，并将输出附加到后续请求中。如果在下一个请求之前模型更改了多次，Claude Code 只会传递针对最后一次切换目标模型的输出。

3623 3625

3624<h3 id="sessionend">3626<h3 id="sessionend">

3625 SessionEnd3627 SessionEnd

3641 3643

3642<h4 id="sessionend-input">3644<h4 id="sessionend-input">

3643 SessionEnd 输入3645 SessionEnd 输入

3644</h4>3646</h4>

3645 3647

3646除[通用输入字段](#common-input-fields)外，SessionEnd hook 还会接收表示会话结束原因的 `reason` 字段。有关所有取值，请参阅上方的[原因表](#sessionend)。3648除[通用输入字段](#common-input-fields)外，SessionEnd hook 还会接收一个 `reason` 字段，表示会话结束的原因。有关所有值，请参阅上方的[原因表](#sessionend)。

3647 3649

3648```json theme={null}3650```json theme={null}

3649{3651{

3657 3659

3658SessionEnd hook 没有决策控制。它们无法阻止会话终止，但可以执行清理任务。Claude Code 会丢弃它们的 [JSON 输出字段](#json-output)，例如 `systemMessage`。3660SessionEnd hook 没有决策控制。它们无法阻止会话终止，但可以执行清理任务。Claude Code 会丢弃它们的 [JSON 输出字段](#json-output)，例如 `systemMessage`。

3659 3661

3660SessionEnd hook 的默认超时时间为 1.5 秒。它适用于您退出、运行 `/clear` 或通过交互式 `/resume` 切换会话时。您可以通过两种方式为 hook 提供更多时间：3662SessionEnd hook 的默认超时时间为 1.5 秒。该超时适用于您退出、运行 `/clear` 或通过交互式 `/resume` 切换会话时。您可以通过两种方式为 hook 提供更多时间：

3661 3663

3662* **单个 hook 的 `timeout`**：在该 hook 的配置中设置 `timeout`。总体时间预算会自动提高，以匹配您的设置文件中最大的单个 hook `timeout`，最长 60 秒。如果以这种方式提高预算，未设置自身 `timeout` 的 hook 仍保持默认值。在插件提供的 hook 上设置的超时时间不会提高预算。3664* **每个 hook 的 `timeout`**：在该 hook 的配置中设置 `timeout`。总体时间预算会自动提高，以匹配您设置文件中最高的单个 hook `timeout`，最长 60 秒。如果以这种方式提高预算，没有自己 `timeout` 的 hook 仍保持默认值。在插件提供的 hook 上设置的超时时间不会提高预算。

3663* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**：以毫秒为单位设置此环境变量，以显式覆盖预算。您设置的值也会成为每个未设置自身 `timeout` 的 hook 的超时时间。3665* **`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS`**：以毫秒为单位设置此环境变量，以显式覆盖预算。您设置的值也会成为每个没有自己 `timeout` 的 hook 的超时时间。

3664 3666

3665以下示例将预算设置为 5 秒：3667此示例将预算设置为 5 秒：

3666 3668

3667```bash theme={null}3669```bash theme={null}

3668CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude3670CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

3669```3671```

3670 3672

3671在 v2.1.268 之前，`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` 只会提高总体预算，未设置自身 `timeout` 的 hook 仍会在 1.5 秒后被取消。3673在 v2.1.268 之前，`CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS` 只会提高总体预算，没有自己 `timeout` 的 hook 仍会在 1.5 秒后被取消。

3672 3674

3673<h3 id="elicitation">3675<h3 id="elicitation">

3674 Elicitation3676 Elicitation

3675</h3>3677</h3>

3676 3678

3677在 MCP 服务器于任务执行过程中请求用户输入时运行。默认情况下，Claude Code 会显示一个交互式对话框供用户响应。hook 可以拦截此请求并以编程方式响应，完全跳过对话框。3679在 MCP 服务器于任务中途请求用户输入时运行。默认情况下，Claude Code 会显示一个交互式对话框供用户响应。hook 可以拦截此请求并以编程方式响应，完全跳过对话框。

3680

3681有关包含设置条目和脚本的完整 hook，请参阅[通过脚本回答表单请求](#answer-a-form-request-from-a-script)。

3678 3682

3679matcher 字段与 MCP 服务器名称进行匹配。3683matcher 字段与 MCP 服务器名称进行匹配。

3680 3684

3704}3708}

3705```3709```

3706 3710

3707对于 URL 模式的 elicitation（用于基于浏览器的身份验证）：3711对于用于基于浏览器的身份验证的 URL 模式 elicitation：

3708 3712

3709```json theme={null}3713```json theme={null}

3710{3714{

3723 Elicitation 输出3727 Elicitation 输出

3724</h4>3728</h4>

3725 3729

3726要在不显示对话框的情况下以编程方式响应，请返回带有 `hookSpecificOutput` 的 JSON 对象：3730Elicitation hook 可以代替用户回答请求、拒绝或取消请求，或将其交给对话框处理。要回答、拒绝或取消，请以 0 退出并打印一个带有 `action` 的 `hookSpecificOutput` 对象。服务器会收到您的回答，并且不会出现对话框。下表的每一行显示某一结果应返回的内容以及 MCP 服务器收到的内容：

3731

3732| 目的 | 返回 | 服务器收到 |

3733| :- | :- | :- |

3734| 代替用户回答 | `"action": "accept"`，并在 `content` 中提供表单字段值 | `accept` 以及您的 `content` |

3735| 拒绝请求 | `"action": "decline"` | `decline` |

3736| 取消请求 | `"action": "cancel"` | `cancel` |

3737| 将请求交给用户 | 无输出，退出码为 0 | 用户在[对话框](/docs/zh-CN/mcp#respond-to-mcp-elicitation-requests)中的回答 |

3738

3739此输出回答了 [Elicitation 输入](#elicitation-input)中所示的表单模式请求。`content` 中的键是该请求的 `requested_schema` 中的属性名称：

3727 3740

3728```json theme={null}3741```json theme={null}

3729{3742{

3737}3750}

3738```3751```

3739 3752

3740| 字段 | 取值 | 描述 |3753此输出拒绝请求：

3741| :- | :- | :- |3754

3742| `action` | `accept`、`decline`、`cancel` | 接受、拒绝还是取消该请求 |3755```json theme={null}

3743| `content` | object | 要提交的表单字段值。仅在 `action` 为 `accept` 时使用 |3756{

3757 "hookSpecificOutput": {

3758 "hookEventName": "Elicitation",

3759 "action": "decline"

3760 }

3761}

3762```

3763

3764在对话框中，选择 **Decline** 会发送 `decline`，按 `Esc` 会发送 `cancel`，因此请返回您希望服务器看到的那个值。

3765

3766对于 URL 模式请求，返回 `accept` 的 hook 会跳过对话框，因此该 URL 永远不会打开。

3767

3768无论您返回哪个 `action`，Claude Code 都会丢弃 Elicitation hook JSON 输出中的 `reason`、`systemMessage` 和 `continue`。

3769

3770<h4 id="other-ways-to-decline-an-elicitation">

3771 拒绝 elicitation 的其他方式

3772</h4>

3773

3774您的 hook 还可以通过以下方式拒绝。服务器收到的 `decline` 与 `"action": "decline"` 相同：

3775

3776* **以退出码 2 退出**：Claude Code 会忽略同一 hook 打印的 `hookSpecificOutput`

3777* **打印顶层 `"decision": "block"`**：该阻止会覆盖同一输出中的 `action`

3778

3779当多个 hook 匹配同一请求时，其中一个 hook 的拒绝会覆盖另一个 hook 的 `accept` 或 `cancel`。

3780

3781此脚本拒绝 URL 模式请求，并将表单请求交给对话框处理：

3782

3783```bash theme={null}

3784#!/bin/bash

3785if [ "$(jq -r '.mode')" = "url" ]; then

3786 exit 2

3787fi

3788```

3789

3790用户和服务器都看不到您的 hook 拒绝的原因，因为 Claude Code 不会显示您的 stderr 或 `reason`。

3744 3791

3745退出码 2 会拒绝该 elicitation。Claude Code 不会在任何地方显示您的 stderr 消息。3792从 v2.1.105 起直到 v2.1.284 中的修复之前，Claude Code 会忽略来自 `Elicitation` 和 `ElicitationResult` hook 的顶层 `decision`。

3746 3793

3747Claude Code 会处理 Elicitation hook JSON 输出中的 `hookSpecificOutput`，并丢弃 `systemMessage` 和 `continue`。3794<h4 id="answer-a-form-request-from-a-script">

3795 通过脚本回答表单请求

3796</h4>

3797

3798此示例代替用户回答一个反复出现的问题。名为 `issue-tracker` 的 MCP 服务器在表单中请求项目键，hook 会填入 `DOCS`。当 `project_key` 是表单的唯一字段时，脚本会接受。对于任何其他请求，它不打印任何内容，因此会显示对话框。

3799

3800<Tabs>

3801 <Tab title="macOS/Linux">

3802 在您的设置文件中为该事件注册一个命令 hook，并将服务器名称作为匹配器：

3803

3804 ```json theme={null}

3805 {

3806 "hooks": {

3807 "Elicitation": [

3808 {

3809 "matcher": "issue-tracker",

3810 "hooks": [

3811 {

3812 "type": "command",

3813 "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.sh",

3814 "args": []

3815 }

3816 ]

3817 }

3818 ]

3819 }

3820 }

3821 ```

3822

3823 将此脚本保存到项目中的 `.claude/hooks/answer-project-key.sh`，并使用 `chmod +x` 使其可执行：

3824

3825 ```bash theme={null}

3826 #!/bin/bash

3827 input=$(cat)

3828 fields=$(jq -c '.requested_schema.properties // {} | keys' <<<"$input")

3829

3830 if [ "$fields" = '["project_key"]' ]; then

3831 jq -n '{hookSpecificOutput: {hookEventName: "Elicitation", action: "accept", content: {project_key: "DOCS"}}}'

3832 fi

3833 ```

3834 </Tab>

3835

3836 <Tab title="Windows (PowerShell)">

3837 注册一个通过 PowerShell 运行脚本的命令 hook，并将服务器名称作为匹配器：

3838

3839 ```json theme={null}

3840 {

3841 "hooks": {

3842 "Elicitation": [

3843 {

3844 "matcher": "issue-tracker",

3845 "hooks": [

3846 {

3847 "type": "command",

3848 "command": "powershell.exe",

3849 "args": [

3850 "-NoProfile",

3851 "-ExecutionPolicy",

3852 "Bypass",

3853 "-File",

3854 "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.ps1"

3855 ]

3856 }

3857 ]

3858 }

3859 ]

3860 }

3861 }

3862 ```

3863

3864 将此脚本保存到项目中的 `.claude/hooks/answer-project-key.ps1`：

3865

3866 ```powershell theme={null}

3867 $request = [Console]::In.ReadToEnd() | ConvertFrom-Json

3868 $fields = @($request.requested_schema.properties.PSObject.Properties.Name)

3869

3870 if ($fields.Count -eq 1 -and $fields[0] -eq 'project_key') {

3871 @{

3872 hookSpecificOutput = @{

3873 hookEventName = "Elicitation"

3874 action = "accept"

3875 content = @{ project_key = "DOCS" }

3876 }

3877 } | ConvertTo-Json -Depth 3

3878 }

3879 ```

3880 </Tab>

3881</Tabs>

3882

3883要确认 hook 是否生效，请使用 `claude --debug` 启动 Claude Code，并给 Claude 一个会让服务器请求项目键的任务。不会出现对话框，并且[调试日志](#debug-hooks)中会有一行以 `Elicitation resolved by hook: {"action":"accept","content":{"project_key":"DOCS"}}` 结尾。

3748 3884

3749<h3 id="elicitationresult">3885<h3 id="elicitationresult">

3750 ElicitationResult3886 ElicitationResult

3752 3888

3753在用户响应 MCP elicitation 后运行。hook 可以在响应发回 MCP 服务器之前观察、修改或阻止该响应。3889在用户响应 MCP elicitation 后运行。hook 可以在响应发回 MCP 服务器之前观察、修改或阻止该响应。

3754 3890

3891当 [Elicitation](#elicitation) hook 回答了请求时，Claude Code 会将该回答发送给服务器，而不运行 ElicitationResult hook。

3892

3755matcher 字段与 MCP 服务器名称进行匹配。3893matcher 字段与 MCP 服务器名称进行匹配。

3756 3894

3757<h4 id="elicitationresult-input">3895<h4 id="elicitationresult-input">

3769 "mcp_server_name": "my-mcp-server",3907 "mcp_server_name": "my-mcp-server",

3770 "action": "accept",3908 "action": "accept",

3771 "content": { "username": "alice" },3909 "content": { "username": "alice" },

3772 "mode": "form",3910 "mode": "form"

3773 "elicitation_id": "elicit-123"

3774}3911}

3775```3912```

3776 3913

3778 ElicitationResult 输出3915 ElicitationResult 输出

3779</h4>3916</h4>

3780 3917

3781要覆盖用户的响应，请返回带有 `hookSpecificOutput` 的 JSON 对象：3918ElicitationResult hook 可以让用户的响应通过、更改其值或阻止它。要更改或阻止响应，请以 0 退出并打印一个带有 `action` 的 `hookSpecificOutput` 对象。下表的每一行显示某一结果应返回的内容以及 MCP 服务器收到的内容：

3919

3920| 目的 | 返回 | 服务器收到 |

3921| :- | :- | :- |

3922| 让响应通过 | 无输出，退出码为 0 | 用户的响应，未经更改 |

3923| 更改提交的值 | `"action": "accept"`，并在 `content` 中提供新值 | `accept` 以及您的 `content`，替代用户的值 |

3924| 阻止响应 | `"action": "decline"` | `decline`，不含用户的值 |

3925| 取消请求 | `"action": "cancel"` | `cancel`，以及用户提交的值。要隐去这些值，请返回 `"decline"` |

3926

3927此输出更改了 [ElicitationResult 输入](#elicitationresult-input)中所示的响应，因此在用户提交 `alice` 的位置，服务器收到的是 `alice@example.com`：

3782 3928

3783```json theme={null}3929```json theme={null}

3784{3930{

3785 "hookSpecificOutput": {3931 "hookSpecificOutput": {

3786 "hookEventName": "ElicitationResult",3932 "hookEventName": "ElicitationResult",

3787 "action": "decline",3933 "action": "accept",

3788 "content": {}3934 "content": {

3935 "username": "alice@example.com"

3936 }

3789 }3937 }

3790}3938}

3791```3939```

3792 3940

3793| 字段 | 取值 | 描述 |3941您的 `content` 会替换用户的整个 `content` 对象，因此请包含您未更改的字段。请同时返回 `action`，因为 Claude Code 会忽略没有 `action` 的 `hookSpecificOutput`。

3794| :- | :- | :- |3942

3795| `action` | `accept`、`decline`、`cancel` | 覆盖用户的操作 |3943当用户拒绝或取消时，ElicitationResult hook 也会运行，并且您的 `action` 会替换用户的 `action`。在返回 `accept` 之前，请检查输入的 `action` 是否为 `accept`，否则您的 hook 会将已拒绝的请求变为已接受的请求。此脚本在用户接受时进行相同的更改，保留其他字段，否则不打印任何内容：

3796| `content` | object | 覆盖表单字段值。仅在 `action` 为 `accept` 时有意义 |3944

3945```bash theme={null}

3946#!/bin/bash

3947input=$(cat)

3797 3948

3798退出码 2 会阻止该响应，将实际生效的操作更改为 `decline`。Claude Code 不会在任何地方显示您的 stderr 消息。3949if [ "$(jq -r '.action' <<<"$input")" = "accept" ]; then

3950 jq '{hookSpecificOutput: {hookEventName: "ElicitationResult", action: "accept", content: (.content + {username: (.content.username + "@example.com")})}}' <<<"$input"

3951fi

3952```

3799 3953

3800Claude Code 会处理 ElicitationResult hook JSON 输出中的 `hookSpecificOutput`，并丢弃 `systemMessage` 和 `continue`。3954此输出阻止响应：

3955

3956```json theme={null}

3957{

3958 "hookSpecificOutput": {

3959 "hookEventName": "ElicitationResult",

3960 "action": "decline"

3961 }

3962}

3963```

3964

3965退出码 2 和顶层 `"decision": "block"` 也会阻止响应。[拒绝 elicitation 的其他方式](#other-ways-to-decline-an-elicitation)介绍了当 hook 组合使用这些方式时哪一种生效、用户会看到什么，以及哪些版本会忽略 `decision`。

3966

3967无论您返回哪个 `action`，Claude Code 都会丢弃 ElicitationResult hook JSON 输出中的 `reason`、`systemMessage` 和 `continue`。

3801 3968

3802<h2 id="prompt-based-hooks">3969<h2 id="prompt-based-hooks">

3803 基于提示的 hooks3970 基于提示的 hooks

3861 4028

3862将 `type` 设置为 `"prompt"` 并提供 `prompt` 字符串而不是 `command`。使用 `$ARGUMENTS` 占位符将 hook 的 JSON 输入数据注入到您的提示文本中。4029将 `type` 设置为 `"prompt"` 并提供 `prompt` 字符串而不是 `command`。使用 `$ARGUMENTS` 占位符将 hook 的 JSON 输入数据注入到您的提示文本中。

3863 4030

4031在提示词 hook 或 [Agent hook](#agent-based-hooks) 中，您可以将 `prompt` 写成关于阻止或允许什么的规则，例如"阻止任何读取 `.env` 文件的 Bash 命令"，也可以写成必须成立的条件，例如"所有单元测试都通过"。

4032

3864此 `Stop` hook 要求 LLM 在允许 Claude 完成之前评估是否应该停止：4033此 `Stop` hook 要求 LLM 在允许 Claude 完成之前评估是否应该停止：

3865 4034

3866```json theme={null}4035```json theme={null}

keybindings.md +49 −0

Details

68| `EffortSlider` | 由 `/effort` 打开的工作量滑块 |68| `EffortSlider` | 由 `/effort` 打开的工作量滑块 |

69| `Select` | 通用选择/列表组件 |69| `Select` | 通用选择/列表组件 |

70| `Plugin` | Plugin 对话框（浏览、发现、管理） |70| `Plugin` | Plugin 对话框（浏览、发现、管理） |

71| `AbovePrompt` | [输入框上方的区域](#above-prompt-actions)或其中的按钮获得键盘焦点 |

72| `AbovePromptInput` | 输入框上方区域或 mod 窗格中的输入字段获得键盘焦点 |

73| `AbovePromptSelect` | 输入框上方区域或 mod 窗格中的选择框获得键盘焦点 |

71| `Pane` | 由 [mod](/docs/zh-CN/plugins/mods/interface#know-which-keys-your-mod-can-receive) 绘制的窗格获得键盘焦点 |74| `Pane` | 由 [mod](/docs/zh-CN/plugins/mods/interface#know-which-keys-your-mod-can-receive) 绘制的窗格获得键盘焦点 |

72| `PaneField` | mod 窗格中的输入字段或选择框获得键盘焦点 |75| `PaneField` | mod 窗格中的输入字段或选择框获得键盘焦点 |

73| `Agents` | [Agent 视图](/docs/zh-CN/agent-view)（`claude agents`） |76| `Agents` | [Agent 视图](/docs/zh-CN/agent-view)（`claude agents`） |

442| `plugin:install` | I | 安装选定的插件 |445| `plugin:install` | I | 安装选定的插件 |

443| `plugin:favorite` | F | 收藏选定的插件，使其在"已安装"标签页附近排序 |446| `plugin:favorite` | F | 收藏选定的插件，使其在"已安装"标签页附近排序 |

444 447

448<h3 id="above-prompt-actions">

449 Above-prompt 操作

450</h3>

451

452用于输入框上方区域的操作，该区域是 [mod](/docs/zh-CN/plugins/mods/interface#pick-where-to-draw) 绘制按钮、输入字段和选择框的共享条带。`abovePrompt:toggle` 和 `abovePrompt:focus` 在 `Chat` 上下文中适用。其他操作在该区域或窗格中拥有键盘焦点的元素所在的 [上下文](#contexts) 中适用。

453

454| 操作 | 默认 | 描述 |

455| :- | :- | :- |

456| `abovePrompt:toggle` | Ctrl+X Ctrl+A | 将该区域折叠为一行提示，或再次展开 |

457| `abovePrompt:focus` | Ctrl+X Tab | 将键盘焦点移入该区域，然后依次移到每个打开的 [窗格](#pane-actions)，并从最后一个窗格回到输入框 |

458| `abovePrompt:next` | Tab | 聚焦下一个控件 |

459| `abovePrompt:previous` | Shift+Tab | 聚焦上一个控件 |

460| `abovePrompt:press` | Enter | 按下获得焦点的按钮、提交获得焦点的输入字段，或在选择框中选取突出显示的选项 |

461| `abovePrompt:leave` | Escape | 将键盘焦点返回到输入框 |

462| `abovePrompt:highlightNext` | Down | 在获得焦点的选择框中突出显示下一个选项 |

463| `abovePrompt:highlightPrevious` | Up | 在获得焦点的选择框中突出显示上一个选项 |

464

465有两个上下文默认将更多键绑定到这些操作：

466

467* **`AbovePrompt`**：Right 和 Left 也会运行 `abovePrompt:next` 和 `abovePrompt:previous`，Space 也会运行 `abovePrompt:press`

468* **`AbovePromptInput`**：Down 和 Up 也会运行 `abovePrompt:next` 和 `abovePrompt:previous`

469

470`AbovePrompt` 上下文还将 Up、Down、PageUp、PageDown、Home 和 End 绑定到 [窗格滚动操作](#pane-actions) `pane:scrollUp` 至 `pane:bottom`，因此要为该区域更改其中某个键，请在 `AbovePrompt` 块中绑定相应的滚动操作。

471

472<h3 id="pane-actions">

473 Pane 操作

474</h3>

475

476用于由 [mod](/docs/zh-CN/plugins/mods/interface#know-which-keys-your-mod-can-receive) 绘制的窗格的操作。滚动、调整大小和关闭操作在 `Pane` [上下文](#contexts) 中适用。`pane:close` 也在 `PaneField` 上下文中适用，因此当窗格的某个字段拥有焦点时它也能生效。当打开的窗格多于一个时，`pane:next` 和 `pane:previous` 在 `Global` 上下文中适用。

477

478| 操作 | 默认 | 描述 |

479| :- | :- | :- |

480| `pane:scrollUp` | Up | 当窗格的行数超出其可显示的范围时向上滚动窗格 |

481| `pane:scrollDown` | Down | 当窗格的行数超出其可显示的范围时向下滚动窗格 |

482| `pane:pageUp` | PageUp | 将窗格向上滚动一页 |

483| `pane:pageDown` | PageDown | 将窗格向下滚动一页 |

484| `pane:top` | Home | 跳到窗格顶部 |

485| `pane:bottom` | End | 跳到窗格底部 |

486| `pane:grow` | Ctrl+X Left, Ctrl+X Up | 为窗格提供更多空间：位于会话记录旁边时增加宽度，位于输入框上方时增加高度 |

487| `pane:shrink` | Ctrl+X Right, Ctrl+X Down | 为窗格提供更少空间：位于会话记录旁边时减小宽度，位于输入框上方时减小高度 |

488| `pane:close` | Ctrl+X X | 关闭窗格 |

489| `pane:next` | (未绑定) | 显示下一个打开的窗格 |

490| `pane:previous` | (未绑定) | 显示上一个打开的窗格 |

491

492`Pane` 上下文还将 Tab、Shift+Tab、Enter 和 Escape 绑定到与该区域相同的 [Above-prompt 操作](#above-prompt-actions)，窗格中的输入字段和选择框使用 `AbovePromptInput` 和 `AbovePromptSelect` 上下文。[键盘焦点和快捷键](/docs/zh-CN/plugins/mods/interface#know-which-keys-your-mod-can-receive) 列出了每个键在窗格中的作用。

493

445<h3 id="settings-actions">494<h3 id="settings-actions">

446 Settings 操作495 Settings 操作

447</h3>496</h3>

llm-gateway-protocol.md +1 −1

Details

200 200

201| 头部 | 返回内容及原因 |201| 头部 | 返回内容及原因 |

202| :- | :- |202| :- | :- |

203| `content-type` | 在流式 Anthropic Messages 格式响应上返回 `text/event-stream`，在 Amazon Bedrock 格式响应上返回 `application/vnd.amazon.eventstream`（不做修改），其中[不同的类型会导致请求失败](/docs/zh-CN/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)。[流式传输](#streaming)列出了哪些连接在这些流上运行停滞检测 |203| `content-type` | 在流式 Anthropic Messages 格式响应上返回 `text/event-stream`，在 Amazon Bedrock 格式响应上返回 `application/vnd.amazon.eventstream`（不做修改），其中[不同的类型会导致请求失败](/docs/zh-CN/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy) |

204| `retry-after` | 返回整数秒而不是 HTTP 日期。Claude Code 在下一次[自动重试](/docs/zh-CN/errors#automatic-retries)之前至少等待该时长，在 [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/zh-CN/env-vars) 会话之外，超过 60 的值会停止重试并立即显示错误 |204| `retry-after` | 返回整数秒而不是 HTTP 日期。Claude Code 在下一次[自动重试](/docs/zh-CN/errors#automatic-retries)之前至少等待该时长，在 [`CLAUDE_CODE_RETRY_WATCHDOG`](/docs/zh-CN/env-vars) 会话之外，超过 60 的值会停止重试并立即显示错误 |

205| `x-should-retry` | 原样转发上游的值。Claude Code 在决定是否重试失败的请求时将此头部作为一个输入来读取：`true` 标记响应可重试，`false` 标记响应不可重试。有关重试次数、退避和 Claude Code 重试的失败情况，请参阅[自动重试](/docs/zh-CN/errors#automatic-retries) |205| `x-should-retry` | 原样转发上游的值。Claude Code 在决定是否重试失败的请求时将此头部作为一个输入来读取：`true` 标记响应可重试，`false` 标记响应不可重试。有关重试次数、退避和 Claude Code 重试的失败情况，请参阅[自动重试](/docs/zh-CN/errors#automatic-retries) |

206| `anthropic-ratelimit-unified-*` | 在每个响应上原样转发上游的值。Claude Code 在成功响应上读取它们以向使用 claude.ai 登录的开发人员显示针对计划限制的使用情况，在 `429` 上读取它们以区分计划限制或支出上限与临时限流；请参阅[使用限制](/docs/zh-CN/errors#usage-limits) |206| `anthropic-ratelimit-unified-*` | 在每个响应上原样转发上游的值。Claude Code 在成功响应上读取它们以向使用 claude.ai 登录的开发人员显示针对计划限制的使用情况，在 `429` 上读取它们以区分计划限制或支出上限与临时限流；请参阅[使用限制](/docs/zh-CN/errors#usage-limits) |

managed-settings.md +2 −2

Details

154 154

155Claude Code 按此顺序检查源，优先级最高的优先：155Claude Code 按此顺序检查源，优先级最高的优先：

156 156

1571. 远程设置，从 claude.ai 作为 [服务器管理的设置](/docs/zh-CN/server-managed-settings) 或通过 [Claude 应用网关](/docs/zh-CN/claude-apps-gateway) 交付。Claude Code 仅在会话使用 [符合条件的登录或密钥](/docs/zh-CN/server-managed-settings#platform-availability) 直接向 Anthropic 的 API 进行身份验证，或使用 `/login` 登录网关时才获取此源。在其他提供商上，或当 `ANTHROPIC_BASE_URL` 指向 Anthropic 的 API 以外的地方时，它从下一个源开始1571. 远程设置，从 claude.ai 作为 [服务器管理的设置](/docs/zh-CN/server-managed-settings) 或通过 [Claude 应用网关](/docs/zh-CN/claude-apps-gateway) 交付。Claude Code 仅在会话使用 [符合条件的凭据](/docs/zh-CN/server-managed-settings#platform-availability) 直接向 Anthropic 的 API 进行身份验证，或使用 `/login` 登录网关时才获取此源。在其他提供商上，或当 `ANTHROPIC_BASE_URL` 指向 Anthropic 的 API 以外的地方时，它从下一个源开始

1582. MDM 或操作系统级策略：macOS plist 或 HKLM 注册表键1582. MDM 或操作系统级策略：macOS plist 或 HKLM 注册表键

1593. 托管设置文件，`managed-settings.d/*.json` 和 `managed-settings.json` 合并在一起1593. 托管设置文件，`managed-settings.d/*.json` 和 `managed-settings.json` 合并在一起

1604. HKCU 注册表，在 Windows 上，以及在 WSL 上一旦 HKLM 注册表或 Windows 托管设置文件打开 [`wslInheritsWindowsSettings`](/docs/zh-CN/settings-reference#wslinheritswindowssettings) 并且 HKCU 值也设置它时。Claude Code 仅在 [其上方没有存在的管理员文档](#present-admin-documents) 且没有 [主机提供的父设置](#let-an-embedding-host-add-policy) 提供限制性键时才读取它1604. HKCU 注册表，在 Windows 上，以及在 WSL 上一旦 HKLM 注册表或 Windows 托管设置文件打开 [`wslInheritsWindowsSettings`](/docs/zh-CN/settings-reference#wslinheritswindowssettings) 并且 HKCU 值也设置它时。Claude Code 仅在 [其上方没有存在的管理员文档](#present-admin-documents) 且没有 [主机提供的父设置](#let-an-embedding-host-add-policy) 提供限制性键时才读取它

385 385

386* `null` 删除该密钥。386* `null` 删除该密钥。

387* 无效的 `disableAllHooks`，即使是带引号的布尔值，也会被丢弃并带有警告，因为强制执行 `true` 也会卸载您自己的托管设置部署的 hook。387* 无效的 `disableAllHooks`，即使是带引号的布尔值，也会被丢弃并带有警告，因为强制执行 `true` 也会卸载您自己的托管设置部署的 hook。

388* 对于规则涵盖的每个其他布尔密钥，字符串 `"true"` 或 `"false"` 读取为该布尔值，在 `/status` 中带有通知，要求您删除引号。388* 对于规则涵盖的每个其他布尔设置项，字符串 `"true"` 或 `"false"` 读取为该布尔值，在 `/status` 中带有通知，要求您删除引号。

389 389

390Claude Code 按字段而不是整体修复 `permissions`、`autoMode`、`worktree` 和 `attribution` 块：390Claude Code 按字段而不是整体修复 `permissions`、`autoMode`、`worktree` 和 `attribution` 块：

391 391

mcp.md +40 −18

Details

142```142```

143 143

144<Note>144<Note>

~~145 **重要：用 `--` 分隔服务器参数**~~

~~146~~

147 对于 stdio 服务器，`--`（双破折号）将 Claude 自己的选项（例如 `--transport`、`--env` 和 `--scope`）与运行服务器的命令和参数分开。`--` 之后的所有内容都原封不动地传递给服务器。145 对于 stdio 服务器，`--`（双破折号）将 Claude 自己的选项（例如 `--transport`、`--env` 和 `--scope`）与运行服务器的命令和参数分开。`--` 之后的所有内容都原封不动地传递给服务器。

148 146

149 例如：147 例如：

275* `✘ Rejected (see disabledMcpjsonServers in settings)`：由 [`disabledMcpjsonServers`](/docs/zh-CN/settings-reference#disabledmcpjsonservers) 条目拒绝的 `.mcp.json` 服务器。Claude Code 仅在 `claude mcp get <name>` 中显示它。273* `✘ Rejected (see disabledMcpjsonServers in settings)`：由 [`disabledMcpjsonServers`](/docs/zh-CN/settings-reference#disabledmcpjsonservers) 条目拒绝的 `.mcp.json` 服务器。Claude Code 仅在 `claude mcp get <name>` 中显示它。

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` 面板重新打开服务器。274* `⊘ Disabled for this project (re-enable via /mcp)`：项目的 [`disabledMcpServers`](#disable-a-server-without-removing-it) 列表命名的服务器。Claude Code 在 `claude mcp list` 和 `claude mcp get <name>` 中都显示它。从 `/mcp` 面板重新打开服务器。

277 275

278WebSocket 服务器不出现在 `claude mcp list` 输出中。使用 `claude mcp get <name>` 或 `/mcp` 面板检查它们。

~~279~~

280<h4 id="project-server-approvals-and-workspace-trust">276<h4 id="project-server-approvals-and-workspace-trust">

281 项目服务器批准和工作区信任277 项目服务器批准和工作区信任

282</h4>278</h4>

371 367

372在 v2 上，Claude Code 还会：368在 v2 上，Claude Code 还会：

373 369

374* 询问 HTTP 服务器是否支持较新的修订版，并与支持的服务器一起使用它。在获取功能标志的会话中，它还会询问 claude.ai 连接器服务器；在 Claude Code v2.1.285 或更高版本上，随着 Anthropic 逐步推出该更改，它还会询问 stdio 服务器。要让它在每个会话中都询问连接器服务器和 stdio 服务器，请设置 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 为 `auto`。它与 v1 一样连接到其他所有服务器。370* 询问 HTTP 和 stdio 服务器是否支持较新的修订版，并与支持的服务器一起使用它。在获取功能标志的会话中，它还会询问 claude.ai 连接器服务器。它与 v1 一样连接到其他所有服务器。

375* 通过 [它保持打开的流](#notification-streams-on-the-v2-runtime) 从使用较新修订版的服务器接收 `list_changed` 通知。371* 通过 [它保持打开的流](#notification-streams-on-the-v2-runtime) 从使用较新修订版的服务器接收 `list_changed` 通知。

376* 不注册在较新修订版上连接的 [频道](#push-messages-with-channels) 服务器，因为该修订版无法携带频道消息。372* 不注册在较新修订版上连接的 [频道](#push-messages-with-channels) 服务器，因为该修订版无法携带频道消息。

377* 当授权响应指明意外的发行者时，使 [MCP OAuth 登录](#authenticate-with-remote-mcp-servers) 失败。373* 当授权响应指明意外的发行者时，使 [MCP OAuth 登录](#authenticate-with-remote-mcp-servers) 失败。

458 454

459在 [v2 运行时](#mcp-client-runtimes) 上，协商 MCP 协议修订版 2026-07-28 的频道服务器无法传递频道消息，因此 Claude Code 不将其注册为频道。不支持该修订版的频道服务器会在较早的握手上连接，并像以前一样注册。455在 [v2 运行时](#mcp-client-runtimes) 上，协商 MCP 协议修订版 2026-07-28 的频道服务器无法传递频道消息，因此 Claude Code 不将其注册为频道。不支持该修订版的频道服务器会在较早的握手上连接，并像以前一样注册。

460 456

461当您设置 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 为 `auto` 时，Claude Code 会向 stdio 服务器询问该修订版。对于 Claude Code v2.1.285 或更高版本，Anthropic 还在 Claude Code [获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching) 的会话中默认启用此行为。要将 stdio 频道服务器保持在较早的握手上，请将 `MCP_PROTOCOL_NEGOTIATION` 设置为 `legacy`，这会将所有服务器都保持在较早的握手上。457Claude Code 默认会向 stdio 服务器询问该修订版。要将 stdio 频道服务器保持在较早的握手上，请将 [`MCP_PROTOCOL_NEGOTIATION`](/docs/zh-CN/env-vars) 设置为 `legacy`，这会将所有服务器都保持在较早的握手上。

462 458

463<Tip>459<Tip>

464 提示：460 提示：

509 插件提供的 MCP 服务器505 插件提供的 MCP 服务器

510</h3>506</h3>

511 507

512[插件](/docs/zh-CN/plugins/overview) 可以捆绑 MCP 服务器，在您启用插件时提供工具和集成。插件 MCP 服务器的工作方式与用户配置的服务器相同。508[插件](/docs/zh-CN/plugins/overview) 可以捆绑 MCP 服务器，在您启用插件时提供工具和集成。

513 509

514**插件 MCP 服务器如何工作**：510**插件 MCP 服务器如何工作**：

515 511

1400 MCP 输出限制和警告1396 MCP 输出限制和警告

1401</h2>1397</h2>

1402 1398

1403当 MCP 工具产生大量输出时，Claude Code 会帮助管理令牌使用情况，以防止压倒您的对话上下文：1399当 MCP 工具产生大量输出时，Claude Code 会帮助管理 token 使用情况，以防止压倒您的对话上下文：

1404 1400

1405* **输出警告阈值**：当任何 MCP 工具输出超过 10,000 个令牌时，Claude Code 会显示警告1401* **输出警告阈值**：当任何 MCP 工具输出超过 10,000 个 token 时，Claude Code 会显示警告

1406* **可配置限制**：您可以使用 `MAX_MCP_OUTPUT_TOKENS` 环境变量调整允许的最大 MCP 输出令牌数1402* **可配置限制**：您可以使用 `MAX_MCP_OUTPUT_TOKENS` 环境变量调整允许的最大 MCP 输出 token 数

1407* **默认限制**：默认最大值为 25,000 个令牌1403* **默认限制**：默认最大值为 25,000 个 token

1408* **范围**：环境变量适用于未声明自己限制的工具。设置了 [`anthropic/maxResultSizeChars`](#raise-the-limit-for-a-specific-tool) 的工具会对文本内容使用该值，而不管 `MAX_MCP_OUTPUT_TOKENS` 设置为什么。返回图像数据的工具仍然受 `MAX_MCP_OUTPUT_TOKENS` 限制1404* **范围**：环境变量适用于未声明自己限制的工具。设置了 [`anthropic/maxResultSizeChars`](#raise-the-limit-for-a-specific-tool) 的工具会对文本内容使用该值，而不管 `MAX_MCP_OUTPUT_TOKENS` 设置为什么。返回图像数据的工具仍然受 `MAX_MCP_OUTPUT_TOKENS` 限制

1409* **超过限制**：当没有图像内容的成功结果超过 token 限制时，Claude Code 会将其保存到文件中，并在对话中用一条消息替换它，该消息指定文件路径，以便 Claude 在需要内容时读取该文件。该文件位于会话的 `tool-results` 目录中，在 [`~/.claude/projects/`](/docs/zh-CN/claude-directory#cleaned-up-automatically) 下。1405* **超过限制**：当没有图像内容的成功结果超过 token 限制时，Claude Code 会将其保存到文件中，并在对话中用一条消息替换它，该消息指定文件路径，以便 Claude 在需要内容时读取该文件。该文件位于会话的 `tool-results` 目录中，在 [`~/.claude/projects/`](/docs/zh-CN/claude-directory#cleaned-up-automatically) 下。

1406* **来自 HTTP 和 SSE 服务器的响应大小**：一旦某个 JSON 响应体或事件流中的某个事件在解压后超过 16 MB，Claude Code 就会停止读取来自 [HTTP](#option-1-add-a-remote-http-server) 或 [SSE](#option-2-add-a-remote-sse-server) 服务器的响应。该响应所对应的请求会失败。如果您负责维护该服务器，请减少每个响应返回的数据量以保持在限制之内，例如对结果进行分页

1410 1407

1411已被 Claude Code [移至后台任务](#automatic-backgrounding-of-long-tool-calls)的调用会通过任务通知报告其结果。对于在前台完成的调用，还有另外两项限制：1408已被 Claude Code [移至后台任务](#automatic-backgrounding-of-long-tool-calls)的调用会通过任务通知报告其结果。对于在前台完成的调用，还有另外两项限制：

1412 1409

1438}1435}

1439```1436```

1440 1437

1441该注释对文本内容独立于 `MAX_MCP_OUTPUT_TOKENS` 应用，因此用户不需要为声明它的工具提高环境变量。返回图像数据的工具仍然受令牌限制。1438该注释对文本内容独立于 `MAX_MCP_OUTPUT_TOKENS` 应用，因此用户不需要为声明它的工具提高环境变量。返回图像数据的工具仍然受 token 限制。

~~1442~~

1443<Warning>

1444 如果您经常遇到特定 MCP 服务器的输出警告，而您无法控制这些服务器，请考虑增加 `MAX_MCP_OUTPUT_TOKENS` 限制。您也可以要求服务器作者添加 `anthropic/maxResultSizeChars` 注释或对其响应进行分页。该注释对返回图像内容的工具无效；对于这些工具，提高 `MAX_MCP_OUTPUT_TOKENS` 是唯一的选择。

1445</Warning>

1446 1439

1447<h3 id="images-in-tool-results">1440<h3 id="images-in-tool-results">

1448 工具结果中的图像1441 工具结果中的图像

1604 1597

1605要更改会话中每个 MCP 服务器的限制，请将 [`CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH`](/docs/zh-CN/env-vars#variables) 设置为字符数。此变量需要 Claude Code v2.1.280 或更高版本。1598要更改会话中每个 MCP 服务器的限制，请将 [`CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH`](/docs/zh-CN/env-vars#variables) 设置为字符数。此变量需要 Claude Code v2.1.280 或更高版本。

1606 1599

1600<h4 id="per-tool-alwaysload">

1601 将工具标记为预先加载或保持延迟

1602</h4>

1603

1604要控制服务器中某个工具的加载方式，请在该工具的 `_meta` 对象中设置 `"anthropic/alwaysLoad"`。将您的服务器添加到 Claude Code 的人也可以在其配置中为整个服务器设置 [`alwaysLoad`](#exempt-a-server-from-deferral)，并且其设置可以覆盖您的设置：

1605

1606| 您的工具的值 | 结果 |

1607| :- | :- |

1608| `true` | 该工具预先加载。启动不会因为此值而等待您的服务器。配置您的服务器的人仍然可以[延迟其所有工具](#defer-a-servers-tools) |

1609| `false` | 当其配置设置了 `"alwaysLoad": true` 时，该工具保持延迟。这适用于通过 [`--mcp-config`](/docs/zh-CN/cli-reference#cli-flags) 传入、由 [Agent SDK 应用程序](/docs/zh-CN/agent-sdk/mcp#in-code)提供或由[插件](#plugin-provided-mcp-servers)提供的服务器。在其他服务器上，该工具预先加载。需要 Claude Code v2.1.285 或更高版本 |

1610

1611以下 `tools/list` 条目请求预先加载一个工具：

1612

1613```json theme={null}

1614{

1615 "name": "search_tickets",

1616 "description": "Searches the ticket tracker by keyword",

1617 "_meta": {

1618 "anthropic/alwaysLoad": true

1619 }

1620}

1621```

1622

1607<h3 id="configure-tool-search">1623<h3 id="configure-tool-search">

1608 配置工具搜索1624 配置工具搜索

1609</h3>1625</h3>

1655 豁免服务器不延迟1671 豁免服务器不延迟

1656</h3>1672</h3>

1657 1673

1658如果服务器的工具应该始终对 Claude 可见而无需搜索步骤，请在该服务器的配置中将 `alwaysLoad` 设置为 `true`。来自该服务器的每个工具都会在会话开始时加载到上下文中，无论 `ENABLE_TOOL_SEARCH` 设置如何。对于 Claude 在每个回合都需要的少量工具使用此选项，因为每个预先加载的工具会消耗本来可用于您的对话的上下文。1674如果服务器的工具应该始终对 Claude 可见而无需搜索步骤，请在该服务器的配置中将 `alwaysLoad` 设置为 `true`。之后，该服务器的工具会加载到上下文中，无论 `ENABLE_TOOL_SEARCH` 设置如何。对于 Claude 在每一轮都需要的少量工具使用此选项，因为每个预先加载的工具会消耗本来可用于您的对话的上下文。

1659 1675

1660以下 `.mcp.json` 条目豁免一个 HTTP 服务器，同时保持其他服务器延迟：1676以下 `.mcp.json` 条目豁免一个 HTTP 服务器，同时保持其他服务器延迟：

1661 1677

1671}1687}

1672```1688```

1673 1689

1674`alwaysLoad` 字段在所有服务器类型上都可用。MCP 服务器也可以通过在工具的 `_meta` 对象中包含 `"anthropic/alwaysLoad": true` 来标记单个工具为始终加载，这对该工具只有相同的效果。1690`alwaysLoad` 字段在所有服务器类型上都可用。

1675 1691

1676设置 `alwaysLoad: true` 也会使启动等待服务器的工具，上限为标准 5 秒连接超时，因为它们必须在构建第一个提示时存在。具有有效 [`cached` 条目](#server-status-detail) 的远程服务器从缓存提供其工具而无需连接，因此它不会延迟启动。其他服务器默认在后台连接；设置 [`MCP_CONNECTION_NONBLOCKING=0`](/docs/zh-CN/env-vars) 也使启动等待它们。1692设置 `alwaysLoad: true` 也会使启动等待服务器的工具，上限为标准 5 秒连接超时，因为它们必须在构建第一个提示时存在。具有有效 [`cached` 条目](#server-status-detail) 的远程服务器从缓存提供其工具而无需连接，因此它不会延迟启动。其他服务器默认在后台连接；设置 [`MCP_CONNECTION_NONBLOCKING=0`](/docs/zh-CN/env-vars) 也使启动等待它们。

1677 1693

1694<h3 id="defer-a-servers-tools">

1695 延迟服务器的工具

1696</h3>

1697

1698要让服务器的所有工具都保持在工具搜索之后，请在 MCP 配置中该服务器的条目里设置 `"alwaysLoad": false`。这包括服务器作者已[标记为预先加载](#per-tool-alwaysload)的工具。如果您省略 `alwaysLoad`，这些已标记的工具会预先加载。需要 Claude Code v2.1.287 或更高版本。

1699

1678<h2 id="use-mcp-prompts-as-commands">1700<h2 id="use-mcp-prompts-as-commands">

1679 将 MCP 提示用作命令1701 将 MCP 提示用作命令

1680</h2>1702</h2>

memory.md +5 −3

Details

161 161

162所有发现的文件被连接到上下文中，而不是相互覆盖。在目录树中，内容从文件系统根目录向下排序到您的工作目录。对于 `foo/bar/` 示例，`foo/CLAUDE.md` 在上下文中出现在 `foo/bar/CLAUDE.md` 之前，因此更接近您启动 Claude 的位置的指令最后读取。在每个目录中，`CLAUDE.local.md` 附加在 `CLAUDE.md` 之后，因此您的个人笔记是 Claude 在该级别读取的最后一件事。162所有发现的文件被连接到上下文中，而不是相互覆盖。在目录树中，内容从文件系统根目录向下排序到您的工作目录。对于 `foo/bar/` 示例，`foo/CLAUDE.md` 在上下文中出现在 `foo/bar/CLAUDE.md` 之前，因此更接近您启动 Claude 的位置的指令最后读取。在每个目录中，`CLAUDE.local.md` 附加在 `CLAUDE.md` 之后，因此您的个人笔记是 Claude 在该级别读取的最后一件事。

163 163

164Claude 还发现当前工作目录下子目录中的 `CLAUDE.md` 和 `CLAUDE.local.md` 文件。它们不是在启动时加载，而是在 Claude 对这些子目录中的文件使用 [Read](/docs/zh-CN/tools-reference#read-tool-behavior)、[Write](/docs/zh-CN/tools-reference#write-tool-behavior) 或 [Edit](/docs/zh-CN/tools-reference#edit-tool-behavior) 工具时由 Claude Code 包含。如果 Claude 已经对某个子目录的 `CLAUDE.md` 本身使用过这些工具之一，则不会以这种方式加载该文件，因为 Claude Code 将其视为已在对话中。对于 `.claude/worktrees/` 下 worktree 中的文件，请参阅 [使用 worktree 隔离子代理](/docs/zh-CN/worktrees#isolate-subagents-with-worktrees)。164Claude 还发现当前工作目录下子目录中的 `CLAUDE.md` 和 `CLAUDE.local.md` 文件。它们不会在启动时加载，而是在 Claude 读取、写入或编辑该子目录中的其他文件时，由 Claude Code 逐个加载。读取包括使用[算作读取](/docs/zh-CN/tools-reference#edit-tool-behavior)的 Bash 命令查看文件，例如对单个文件使用 `cat` 或 `head`。对于 `.claude/worktrees/` 下 worktree 中的文件，请参阅 [使用 worktree 隔离子代理](/docs/zh-CN/worktrees#isolate-subagents-with-worktrees)。

165 165

166如果您在大型 monorepo 中工作，其中其他团队的 CLAUDE.md 文件被拾取，请使用 [`claudeMdExcludes`](#exclude-specific-claude-md-files) 跳过它们。有关根目录和每目录 CLAUDE.md 文件和规则的完整布局，请参阅 [Monorepos 和大型仓库](/docs/zh-CN/large-codebases)。166如果您在大型 monorepo 中工作，其中其他团队的 CLAUDE.md 文件被拾取，请使用 [`claudeMdExcludes`](#exclude-specific-claude-md-files) 跳过它们。有关根目录和每目录 CLAUDE.md 文件和规则的完整布局，请参阅 [Monorepos 和大型仓库](/docs/zh-CN/large-codebases)。

167 167

232- Include OpenAPI documentation comments232- Include OpenAPI documentation comments

233```233```

234 234

235没有 `paths` 字段的规则无条件加载并适用于所有文件。路径范围规则在 Claude 对与模式匹配的文件使用 Read、Write 或 Edit 工具时触发，而不是在每次工具使用时。当 Claude 通过项目目录的符号链接路径到达文件时，匹配也有效，例如在符号链接检出中。235没有 `paths` 字段的规则无条件加载并适用于所有文件。当 Claude 对匹配的文件使用 Read、Write 或 Edit 工具时，路径范围规则会加载。当 Claude 使用[算作读取](/docs/zh-CN/tools-reference#edit-tool-behavior)的 Bash 命令查看匹配的文件时（例如对单个文件使用 `cat` 或 `head`），该规则也会加载。当 Claude 通过项目目录的符号链接路径到达文件时，匹配也有效，例如在符号链接检出中。

236 236

237在 `paths` 字段中使用 glob 模式按扩展名、目录或任何组合匹配文件：237在 `paths` 字段中使用 glob 模式按扩展名、目录或任何组合匹配文件：

238 238

278 278

279`.claude/rules/` 目录支持符号链接，因此您可以维护一组共享规则并将它们链接到多个项目中。循环符号链接被检测并妥善处理。279`.claude/rules/` 目录支持符号链接，因此您可以维护一组共享规则并将它们链接到多个项目中。循环符号链接被检测并妥善处理。

280 280

281Claude Code 将其目标在工作目录外的符号链接视为 [external import](#import-additional-files)。链接的规则不加载，直到您批准项目的外部导入，之后仅加载没有 [`paths` 字段](#path-specific-rules) 的规则。Claude Code 仅当项目记忆文件使用 `@path` 导入工作目录外的文件时才要求该批准，而不是仅针对符号链接。要加载共享规则而不需要该批准，请将它们保存在 [`~/.claude/rules/`](#user-level-rules) 中，它们适用于您机器上的每个项目。281Claude Code 将其目标在工作目录外的符号链接视为 [external import](#import-additional-files)。链接的规则不加载，直到您批准项目的外部导入，之后仅加载没有 [`paths` 字段](#path-specific-rules) 的规则。

282

283Claude Code 会针对每个项目请求一次该批准，方式是在交互式会话开始时显示一个对话框。该对话框会列出链接的规则文件以及任何外部 `@path` 导入。要加载共享规则而不需要该批准，请将它们保存在 [`~/.claude/rules/`](#user-level-rules) 中，它们适用于您机器上的每个项目。

282 284

283此示例链接共享目录和单个文件：285此示例链接共享目录和单个文件：

284 286

microsoft-foundry.md +45 −11

Details

116 2) 配置 Azure 凭据116 2) 配置 Azure 凭据

117</h3>117</h3>

118 118

119Claude Code 支持三种 Microsoft Foundry 身份验证方法。选择最适合您安全要求的方法。119Claude Code 支持三种 Microsoft Foundry 身份验证方法。选择最适合您安全要求的方法：

120 120

121**选项 A：API 密钥身份验证**121* [API 密钥](#use-an-api-key)：从 Microsoft Foundry 门户复制密钥，并将其设置为 `ANTHROPIC_FOUNDRY_API_KEY`

122* [Microsoft Entra ID](#use-microsoft-entra-id)：Claude Code 通过 Azure SDK 默认凭据链获取令牌，例如从 `az login` 会话中获取，因此无需存储 API 密钥

123* [Bearer 令牌](#use-a-bearer-token)：由另一个进程获取 Microsoft Entra ID 访问令牌，然后您通过 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 传入

124

125<Note>

126 使用 Microsoft Foundry 时，`/logout` 命令不可用，因为身份验证通过 Azure 凭据处理。

127</Note>

128

129<h4 id="use-an-api-key">

130 使用 API 密钥

131</h4>

132

133从 Microsoft Foundry 门户复制密钥，然后将其设置为环境变量：

122 134

1231. 在 Microsoft Foundry 门户中导航到您的资源1351. 在 Microsoft Foundry 门户中导航到您的资源

1242. 转到**端点和密钥**部分1362. 打开**端点和密钥**部分

1253. 复制 **API 密钥**1373. 复制 **API 密钥**

1264. 设置环境变量，将 `your-azure-api-key` 替换为您复制的密钥：1384. 设置环境变量，将 `your-azure-api-key` 替换为您复制的密钥：

127 139

129export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key141export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key

130```142```

131 143

132**选项 B：Microsoft Entra ID 身份验证**144<h4 id="use-microsoft-entra-id">

145 使用 Microsoft Entra ID

146</h4>

133 147

134当未设置 `ANTHROPIC_FOUNDRY_API_KEY` 和 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 时，Claude Code 会自动使用 Azure SDK [默认凭据链](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview)。148不要设置 `ANTHROPIC_FOUNDRY_API_KEY` 和 `ANTHROPIC_FOUNDRY_AUTH_TOKEN`。这样 Claude Code 就会使用 Azure SDK [默认凭据链](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview)。

135这支持多种方法来验证本地和远程工作负载。149这支持多种方法来验证本地和远程工作负载。

136 150

137在本地环境中，您通常可以使用 Azure CLI：151在本地计算机上，使用 Azure CLI 登录：

138 152

139```bash theme={null}153```bash theme={null}

140az login154az login

141```155```

142 156

143**选项 C：Bearer 令牌身份验证**157有关您的身份所需的角色，请参阅 [Azure RBAC 配置](#azure-rbac-configuration)。

158

159<h4 id="use-a-bearer-token">

160 使用 Bearer 令牌

161</h4>

144 162

145Claude Code 在每个请求中将 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 的值作为 `Authorization: Bearer` 标头发送。当另一个进程（例如主机应用程序或登录脚本）已经为您获取了访问令牌时，请使用此选项。需要 Claude Code v2.1.203 或更高版本。163Claude Code 在每个请求中将 `ANTHROPIC_FOUNDRY_AUTH_TOKEN` 的值作为 `Authorization: Bearer` 标头发送。当另一个进程（例如主机应用程序或登录脚本）已经为您获取了访问令牌时，请使用此选项。需要 Claude Code v2.1.203 或更高版本。

146 164

152 170

153`ANTHROPIC_FOUNDRY_AUTH_TOKEN` 优先于 `ANTHROPIC_FOUNDRY_API_KEY` 和默认凭据链。171`ANTHROPIC_FOUNDRY_AUTH_TOKEN` 优先于 `ANTHROPIC_FOUNDRY_API_KEY` 和默认凭据链。

154 172

155<Note>

156 使用 Microsoft Foundry 时，`/logout` 命令不可用，因为身份验证通过 Azure 凭据处理。

157</Note>

~~158~~

159<h3 id="3-configure-claude-code">173<h3 id="3-configure-claude-code">

160 3. 配置 Claude Code174 3. 配置 Claude Code

161</h3>175</h3>

240 254

241有关详情，请参阅 [Microsoft Foundry RBAC 文档](https://learn.microsoft.com/en-us/azure/ai-foundry/concepts/rbac-azure-ai-foundry)。255有关详情，请参阅 [Microsoft Foundry RBAC 文档](https://learn.microsoft.com/en-us/azure/ai-foundry/concepts/rbac-azure-ai-foundry)。

242 256

257<h2 id="1m-token-context-window">

258 1M token 上下文窗口

259</h2>

260

261在 Microsoft Foundry 上，当 Claude Code 能够识别您的部署所服务的模型时，Fable 模型、Sonnet 5 及更高版本以及 Opus 4.7 及更高版本默认使用 [1M token 上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)，无需添加 `[1m]` 后缀。Claude Code 从模型变量中的部署名称读取模型。请使用模型 ID 命名每个部署，例如 `claude-opus-4-8`，或者使用 [`modelOverrides`](/docs/zh-CN/model-config#override-model-ids-per-version) 将模型映射到您的部署名称。对于无法匹配到模型的部署名称，Claude Code 会假定使用 200K 窗口，除非您[声明其他窗口大小](/docs/zh-CN/model-config#correct-the-window-for-a-gateway-or-custom-model-id)。

262

263以下 `settings.json` 条目告知 Claude Code，名为 `team-opus-prod` 的部署服务于 Opus 4.8：

264

265```json theme={null}

266{

267 "modelOverrides": {

268 "claude-opus-4-8": "team-opus-prod"

269 }

270}

271```

272

273如需改为保持 200K 窗口，请设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-CN/model-config#turn-off-1m-context)。

274

275当您在 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 中的部署名称后附加 `[1m]` 时，Opus 4.6 和 Sonnet 4.6 可使用 1M 窗口，如[为第三方部署固定模型](/docs/zh-CN/model-config#pin-models-for-third-party-deployments)中所述。在 v2.1.287 之前，Fable 模型以及 Opus 4.7 及更高版本在 Microsoft Foundry 上同样需要该后缀，否则默认使用 200K 窗口。

276

243<h2 id="troubleshooting">277<h2 id="troubleshooting">

244 故障排除278 故障排除

245</h2>279</h2>

model-config.md +154 −144

Details

10 可用模型10 可用模型

11</h2>11</h2>

12 12

~~13对于 Claude Code 中的 `model` 设置，你可以配置以下任一项：~~13对于 Claude Code 中的 `model` 设置，您可以配置以下任一项：

14 14

15* 一个**模型别名**15* 一个**模型别名**

16* 一个**模型名称**16* 一个**模型名称**

19 * Microsoft Foundry：部署名称19 * Microsoft Foundry：部署名称

20 * Google Cloud 的 Agent Platform：版本名称20 * Google Cloud 的 Agent Platform：版本名称

21 21

22有关哪种模型和工作量级别适合不同类型工作的指导，请参阅博客上的 [Choosing a Claude model and effort level in Claude Code](https://claude.com/blog/claude-model-and-effort-level-in-claude-code)。22有关哪种模型和 effort 级别适合不同类型工作的指导，请参阅博客上的 [Choosing a Claude model and effort level in Claude Code](https://claude.com/blog/claude-model-and-effort-level-in-claude-code)。

23 23

24<Note>24<Note>

~~25 `ANTHROPIC_BASE_URL` 改变请求发送的位置，而不是哪个模型回答它们。要通过 LLM 网关路由 Claude，请参阅 [LLM gateways](/docs/zh-CN/llm-gateway)。~~25 `ANTHROPIC_BASE_URL` 改变的是请求发送的位置，而不是由哪个模型回答。要通过 LLM 网关路由 Claude，请参阅 [LLM gateways](/docs/zh-CN/llm-gateway)。

26</Note>26</Note>

27 27

28<h3 id="model-aliases">28<h3 id="model-aliases">

33 33

34| 模型别名 | 行为 |34| 模型别名 | 行为 |

35| - | - |35| - | - |

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 时无效 |42| **`sonnet[1m]`** | 为长会话使用具有 [100 万 token 上下文窗口](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 万 token 上下文窗口](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) 的 Opus。当 `opus` 已解析到具有原生 1M 窗口的 Opus 4.7 或更高版本时无效 |

45 45

46`opus`、`sonnet` 和 `haiku` 别名在 Anthropic API 上解析到最新版本，在其他一些提供商上解析到较早的版本：46`opus`、`sonnet` 和 `haiku` 别名在 Anthropic API 上解析到最新版本，在其他一些提供商上解析到较早的版本：

47 47

54 54

55<span id="fable-alias-resolution" />55<span id="fable-alias-resolution" />

56 56

57除非你设置 `ANTHROPIC_DEFAULT_FABLE_MODEL`，否则 `fable` 别名解析到 Fable 5.1，除了在 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话中，其中 `fable` 和 `best` 解析到 Fable 5。57除非您设置 `ANTHROPIC_DEFAULT_FABLE_MODEL`，否则 `fable` 别名解析到 Fable 5.1，但在 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话中除外，其中 `fable` 和 `best` 解析到 Fable 5。

58 58

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

60 60

62 62

63较早的版本将这些别名解析到较旧的模型。有关每个别名更改的版本，请参阅[版本历史](#version-history)。63较早的版本将这些别名解析到较旧的模型。有关每个别名更改的版本，请参阅[版本历史](#version-history)。

64 64

65别名指向你的提供商的推荐版本，并随时间更新。要固定到特定版本，请使用完整模型名称，例如 `claude-opus-5-5`，或设置相应的环境变量，如 `ANTHROPIC_DEFAULT_OPUS_MODEL`。65别名指向您的提供商的推荐版本，并随时间更新。要固定到特定版本，请使用完整模型名称，例如 `claude-opus-5-5`，或设置相应的环境变量，如 `ANTHROPIC_DEFAULT_OPUS_MODEL`。

66 66

67<Note>67<Note>

68 Sonnet 5.5 需要 Claude Code v2.1.284 或更高版本，Opus 5.5 需要 v2.1.280 或更高版本。如果从较旧版本对其中某个模型的请求失败，请参阅 [Claude Code does not support this model](/docs/zh-CN/errors#claude-code-does-not-support-this-model)。使用 Haiku 5.5 时请使用 v2.1.293 或更高版本。运行 `claude update` 进行升级。68 Sonnet 5.5 需要 Claude Code v2.1.284 或更高版本，Opus 5.5 需要 v2.1.280 或更高版本。如果从较旧版本对其中某个模型的请求失败，请参阅 [Claude Code does not support this model](/docs/zh-CN/errors#claude-code-does-not-support-this-model)。使用 Haiku 5.5 时请使用 v2.1.293 或更高版本。运行 `claude update` 进行升级。

72 使用 Fable72 使用 Fable

73</h3>73</h3>

74 74

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

76 76

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

78 78

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

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

81 81

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

83 83

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

85 85

86要充分利用 Fable：86要充分利用 Fable：

87 87

~~88* **描述结果，而不是步骤**：给它你想要的结果，让它规划路径。要保持它朝着该结果工作，[设置一个目标](/docs/zh-CN/goal)。~~88* **描述结果，而不是步骤**：告诉它您想要的结果，让它规划路径。要让它持续朝着该结果工作，请[设置一个目标](/docs/zh-CN/goal)。

~~89* **给它模糊的问题**：根本原因调查、中断调试和架构决策是额外调查和验证发挥作用的地方。~~89* **交给它模糊的问题**：根本原因调查、故障调试和架构决策正是额外调查和验证发挥作用的地方。

~~90* **跳过验证提醒**：它用更少的提示验证自己的工作，所以测试或检查的提醒通常是不必要的。~~90* **省去验证提醒**：它无需太多提示就会验证自己的工作，因此通常不必提醒它测试或检查。

~~91* **规划更大的任务**：给它你通常会分成几部分的工作。它能够维持长时间的会话而不失去思路。~~91* **交给它更大的任务**：把您通常会拆分成几部分的工作交给它。它能够维持长时间的会话而不失去思路。

92 92

93<Note>93<Note>

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

95</Note>95</Note>

96 96

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

98 98

99<h4 id="fable-and-usage-credits">99<h4 id="fable-and-usage-credits">

100 Fable 和使用额度100 Fable 和使用额度

101</h4>101</h4>

102 102

103根据你的计划和座位等级，Fable 使用可以计入[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，而不是从你的计划的包含限制中扣除。当它这样做时，`/model` 选择器在 Fable 行上显示"需要使用额度"。要管理使用额度，请参阅 [Add usage credits to your subscription](/docs/zh-CN/costs#add-usage-credits-to-your-subscription)。103根据您的套餐和席位等级，Fable 的使用可能计入[使用额度](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans)，而不是从您套餐包含的限额中扣除。在这种情况下，`/model` 选择器会在 Fable 行上显示"Requires usage credits"。要管理使用额度，请参阅 [Add usage credits to your subscription](/docs/zh-CN/costs#add-usage-credits-to-your-subscription)。

104 104

105在交互式会话中，Claude Code 在 Fable 请求计入使用额度之前显示同意提示。企业计划的成员（具有组织计费）不会看到该提示。你可以继续使用 Fable 使用额度或切换到你的默认模型。你也可以关闭提示：105在交互式会话中，Claude Code 会在 Fable 请求计入使用额度之前显示同意提示。使用组织计费的企业套餐成员不会看到该提示。您可以选择使用使用额度继续使用 Fable，或切换到您的默认模型。您也可以关闭提示：

106 106

107* 在 `/model` 选择器中，你保持当前模型。107* 当您使用 `/model` 选择 Fable 模型时，将保持当前模型。

108* 在会话中途，Claude Code 继续在你的默认模型上进行该轮。108* 在会话中途，Claude Code 会在您的默认模型上继续该轮次。

109 109

110在你选择继续使用 Fable 使用额度后，Claude Code 不会再显示该提示。110在您选择使用使用额度继续使用 Fable 后，Claude Code 不会再显示该提示。

111 111

112在与 [Remote Control](/docs/zh-CN/remote-control) 连接的会话中、[后台会话](/docs/zh-CN/agent-view)中或[代理团队](/docs/zh-CN/agent-teams)队友的会话中，可能没有人在终端，所以 Claude Code 会将中途同意提示保持到 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 截止时间，默认为五分钟。如果到截止时间没有人回答，Claude Code 会结束该轮而不发送请求，并在记录中添加通知，Remote Control 客户端也会显示该通知。你的模型选择保持不变，Claude Code 会在你的下一条消息上再次请求同意。112在连接了 [Remote Control](/docs/zh-CN/remote-control) 的会话、[后台会话](/docs/zh-CN/agent-view)或 [agent team](/docs/zh-CN/agent-teams) 队友的会话中，终端前可能没有人，因此 Claude Code 会将会话中途的同意提示保留到 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 截止时间，默认为五分钟。如果到截止时间仍无人回答，Claude Code 会结束该轮次而不发送请求，并在会话记录中添加通知，Remote Control 客户端也会显示该通知。您的模型选择保持不变，Claude Code 会在您发送下一条消息时再次请求同意。

113 113

114提示等待时你能做什么取决于会话：114提示等待期间您可以执行的操作取决于会话：

115 115

116* 连接了 Remote Control 或在队友的会话中，在终端按任意键取消截止时间，Claude Code 会等待你的答案。116* 在连接了 Remote Control 的会话或队友的会话中，在终端按任意键可取消截止时间，Claude Code 会等待您的回答。

117* 在后台会话中，在截止时间前回答。117* 在后台会话中，请在截止时间前回答。

118* 如果你在远程客户端发送新消息之前没有人在终端输入，Claude Code 会以相同的方式结束该轮，你的新消息开始下一轮。在有人在终端输入后，Claude Code 继续等待答案并将你的新消息排队在其后面。118* 如果在有人在终端输入之前，您从远程客户端发送了新消息，Claude Code 会以相同的方式结束该轮次，您的新消息将开始下一轮。在有人在终端输入之后，Claude Code 会继续等待回答，并将您的新消息排在其后。

119 119

120在通过 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 托管的应用中，提示是否出现取决于该应用。如果它出现，并且在相同的 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 截止时间前没有人回答，Claude Code 会结束该轮而不发送请求。120在由其他应用通过 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 托管的会话中，是否显示提示由该应用决定。如果显示了提示，并且在相同的 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 截止时间前无人回答，Claude Code 会结束该轮次而不发送请求。

121 121

122在带有 `-p` 标志的[非交互模式](/docs/zh-CN/headless)中以及在不显示提示的 Agent SDK 应用中，Claude Code 永远不会请求同意。当 Fable 请求在那里会计入使用额度时，Claude Code 会在不询问的情况下计入。122在使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless)中，以及在不显示提示的 Agent SDK 应用中，Claude Code 永远不会请求同意。当其中的 Fable 请求会计入使用额度时，Claude Code 会直接计费而不询问。

123 123

124<h3 id="setting-your-model">124<h3 id="setting-your-model">

125 设置你的模型125 设置您的模型

126</h3>126</h3>

127 127

128你可以通过多种方式配置你的模型，按优先级顺序列出：128您可以通过多种方式配置模型，按优先级顺序列出：

129 129

1301. **在会话期间**：使用 `/model <alias|name>` 立即切换，或运行不带参数的 `/model` 打开选择器。参阅 [when Claude Code asks you to confirm the switch](/docs/zh-CN/prompt-caching#switching-models)1301. **在会话期间**：使用 `/model <alias|name>` 立即切换，或运行不带参数的 `/model` 打开选择器。参阅 [when Claude Code asks you to confirm the switch](/docs/zh-CN/prompt-caching#switching-models)

1312. **在启动时**：使用 `claude --model <alias|name>` 启动1312. **在启动时**：使用 `claude --model <alias|name>` 启动

1323. **环境变量**：设置 `ANTHROPIC_MODEL=<alias|name>`1323. **环境变量**：设置 `ANTHROPIC_MODEL=<alias|name>`

1334. **设置**：使用 `model` 字段在你的设置文件中永久配置1334. **设置**：使用 `model` 字段在设置文件中永久配置

1345. **[新会话的默认值](#set-a-default-model-for-new-sessions)**：设置 `ANTHROPIC_DEFAULT_MODEL=<alias|name>`1345. **[新会话的默认值](#set-a-default-model-for-new-sessions)**：设置 `ANTHROPIC_DEFAULT_MODEL=<alias|name>`

135 135

136`/model` 通过在你的用户设置中写入 `model` 字段，将你的选择保存为新会话的默认值。在选择器中：136`/model` 通过在您的用户设置中写入 `model` 字段，将您的选择保存为新会话的默认值。在选择器中：

137 137

138* `Enter`：切换模型并保存为你的默认值138* `Enter`：切换模型并保存为默认值

139* `s`：仅为此会话切换模型，保持你的默认值不变。要使用不同的键，重新绑定 [`modelPicker:thisSessionOnly`](/docs/zh-CN/keybindings#model-picker-actions)139* `s`：仅为此会话切换模型，保持默认值不变。要使用其他按键，请重新绑定 [`modelPicker:thisSessionOnly`](/docs/zh-CN/keybindings#model-picker-actions)

140 140

141直接输入 `/model <name>` 的行为类似于 `Enter`。要仅为此会话切换，使用 `/model` 打开选择器，然后在模型的行上按 `s`。141直接输入 `/model <name>` 的行为与 `Enter` 相同。要仅为此会话切换，请使用 `/model` 打开选择器，然后在该模型的行上按 `s`。

142 142

143在企业计划上，当你使用你的 claude.ai 账户登录并使用 `/model` 保存默认值时，Claude Code 也会在该账户上记录该选择。这需要 Claude Code v2.1.280 或更高版本。143在企业套餐上，当您使用 claude.ai 账户登录并使用 `/model` 保存默认值时，Claude Code 也会在该账户上记录该选择。这需要 Claude Code v2.1.280 或更高版本。

144 144

145* 当你的管理员没有设置[组织默认模型](#organization-default-model)时，[Default 选项](#default-model-setting)可以解析为记录的模型，当它这样做时，选择器的 Default 行显示该模型的名称。145* 当您的管理员未设置[组织默认模型](#organization-default-model)时，[Default 选项](#default-model-setting)可以解析为记录的模型，此时选择器的 Default 行会显示该模型的名称。

146* 如果[模型限制](#restrict-model-selection)排除记录的模型或它对你的账户不可用，并且你的管理员没有设置组织默认模型，Default 选项解析如同没有记录任何内容。146* 如果[模型限制](#restrict-model-selection)排除了记录的模型，或该模型对您的账户不可用，并且您的管理员未设置组织默认模型，则 Default 选项会按未记录任何内容的情况解析。

147* 如果你在 `/model` 中选择 Default 或 `opusplan`，记录的选择不会改变。147* 如果您在 `/model` 中选择 Default 或 `opusplan`，记录的选择不会改变。

148 148

149如果你使用 `/model` 切换模型，该切换也会到达[继承主对话模型的子代理](/docs/zh-CN/sub-agents#choose-a-model)，因为 Claude Code 在 Claude 启动它们时从你的会话正在使用的模型解析它们的模型。在 Claude 将研究或测试运行委托给其中一个之前切换到 Opus，该工作也会在 Opus 上运行。要保持自定义子代理在较小的模型上，在其定义中设置 `model`。149如果您使用 `/model` 切换模型，该切换也会影响[继承主对话模型的子代理](/docs/zh-CN/sub-agents#choose-a-model)，因为 Claude Code 会在 Claude 启动它们时根据会话正在使用的模型解析它们的模型。在 Claude 将研究或测试运行委派给其中某个子代理之前切换到 Opus，该工作也会在 Opus 上运行。要让自定义子代理保持使用较小的模型，请在其定义中设置 `model`。

150 150

151如果你在[非交互模式](/docs/zh-CN/headless)中使用 `-p` 标志在 `/model` 中设置模型，你的选择仅适用于当前会话，不会保存为你的默认值；该模式中的 `/model` 需要 Claude Code v2.1.205 或更高版本。项目和托管设置仍然优先，并在下次启动时重新应用。你的管理员配置的[组织默认模型](#organization-default-model)以覆盖用户选择也会在下次启动时重新应用。151如果您在使用 `-p` 标志的[非交互模式](/docs/zh-CN/headless)中通过 `/model` 设置模型，您的选择仅适用于当前会话，不会保存为默认值；该模式中的 `/model` 需要 Claude Code v2.1.205 或更高版本。项目和托管设置仍然优先，并在下次启动时重新应用。您的管理员配置为覆盖用户选择的[组织默认模型](#organization-default-model)也会在下次启动时重新应用。

152 152

153在 v2.1.144 到 v2.1.152 中，`/model` 仅适用于当前会话，选择器中的 `d` 保存默认值。153在 v2.1.144 到 v2.1.152 中，`/model` 仅适用于当前会话，在选择器中按 `d` 可保存默认值。

154 154

155`--model` 标志和 `ANTHROPIC_MODEL` 环境变量仅适用于你使用它们启动的会话。要同时在不同的终端中运行不同的模型，使用各自的 `--model` 标志启动每个，而不是使用 `/model` 切换。155`--model` 标志和 `ANTHROPIC_MODEL` 环境变量仅适用于使用它们启动的会话。要同时在不同的终端中运行不同的模型，请分别使用各自的 `--model` 标志启动，而不是使用 `/model` 切换。

156 156

157当 Claude Code 与 Anthropic API 通信时（直接或通过代理它的 [LLM 网关](/docs/zh-CN/llm-gateway)），`/model` 选择器中的价格会出现，行上的价格是该行选择的模型的价格。在[第三方提供商](/docs/zh-CN/third-party-integrations)（如 Amazon Bedrock）和 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 上，你的提供商或网关决定你支付的费用，所以选择器行不显示价格。价格仅是显示标签；它不影响行选择哪个模型或你的提供商计费的内容。在 v2.1.206 之前，[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和网关会话显示 Anthropic 列表价格，行可能显示与其选择的模型不同的模型的价格。157当 Claude Code 直接或通过代理 Anthropic API 的 [LLM 网关](/docs/zh-CN/llm-gateway)与 Anthropic API 通信时，`/model` 选择器中会显示价格，每行的价格即该行所选模型的价格。在[第三方提供商](/docs/zh-CN/third-party-integrations)（如 Amazon Bedrock）和 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 上，由您的提供商或网关决定您支付的费用，因此选择器行不显示价格。价格仅是显示标签；它不影响某行选择哪个模型，也不影响提供商的计费。在 v2.1.206 之前，[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和网关会话显示 Anthropic 标价，且某行可能显示与其所选模型不同的模型的价格。

158 158

159使用 `claude --resume`、`--continue` 或 `/resume` 选择器启动的恢复会话会保持保存会话记录时所使用的模型。如果恢复的模型已被停用或被 [`availableModels`](#restrict-model-selection) 排除，会话会回退到正常的优先级顺序。在使用提供商特定部署 ID 而不是 Anthropic 模型 ID 的提供商上，如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry，完全不会恢复会话记录中的模型，会话会通过正常的优先级顺序解析其模型。159使用 `claude --resume`、`--continue` 或 `/resume` 选择器启动的恢复会话会保持保存会话记录时所使用的模型。如果恢复的模型已被停用或被 [`availableModels`](#restrict-model-selection) 排除，会话会回退到正常的优先级顺序。在使用提供商特定部署 ID 而不是 Anthropic 模型 ID 的提供商上，如 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry，完全不会恢复会话记录中的模型，会话会通过正常的优先级顺序解析其模型。

160 160

161如果您的 `model` 设置为 `haiku`，在 Haiku 模型上保存的会话会在 `haiku` 当前解析到的模型上恢复。例如，当 `haiku` 解析到 Haiku 5.5 后，在 Haiku 4.5 上保存的会话会在 Haiku 5.5 上恢复。161如果您的 `model` 设置为 `haiku`，在 Haiku 模型上保存的会话会在 `haiku` 当前解析到的模型上恢复。例如，当 `haiku` 解析到 Haiku 5.5 后，在 Haiku 4.5 上保存的会话会在 Haiku 5.5 上恢复。

162 162

163你为新启动使用 `--model` 或 `ANTHROPIC_MODEL` 选择的模型仍然优先于恢复的模型。从 v2.1.195 开始，[`ANTHROPIC_DEFAULT_OPUS_MODEL`](#environment-variables) 系列变量也是如此。[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions) 也可以，在其部分中列出的条件下。163您在新启动时通过 `--model` 或 `ANTHROPIC_MODEL` 选择的模型仍然优先于恢复的模型。从 v2.1.195 开始，[`ANTHROPIC_DEFAULT_OPUS_MODEL`](#environment-variables) 系列变量也是如此。[`ANTHROPIC_DEFAULT_MODEL`](#set-a-default-model-for-new-sessions) 在其章节所列条件下也可以优先。

164 164

165当启动时的活跃模型来自项目或托管设置而不是你自己的选择时，启动标题显示哪个设置文件设置了它。运行 `/model` 覆盖；项目或托管设置在下次启动时重新应用。在嵌入 Claude Code 并设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 的平台上，主机的模型配置优先于托管模型设置，而托管 `availableModels` 允许列表保持有效，除非主机提供自己的；[Exceptions to managed settings precedence](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence) 说明主机覆盖哪些键和变量。165当启动时的活动模型来自项目或托管设置而不是您自己的选择时，启动标题会显示是哪个设置文件设置了它。运行 `/model` 可覆盖；项目或托管设置会在下次启动时重新应用。在嵌入 Claude Code 并设置 [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/zh-CN/env-vars) 的平台上，主机的模型配置优先于托管模型设置，而托管的 `availableModels` 允许列表仍然有效，除非主机提供自己的允许列表；[Exceptions to managed settings precedence](/docs/zh-CN/settings#exceptions-to-managed-settings-precedence) 说明主机会覆盖哪些键和变量。

166 166

167如果你或你的组织配置 [PreModelSwitch hooks](/docs/zh-CN/hooks#premodelswitch)，它们在请求的切换应用之前运行，可以阻止它或要求你确认。167如果您或您的组织配置了 [PreModelSwitch hook](/docs/zh-CN/hooks#premodelswitch)，它们会在请求的切换生效之前运行，并可以阻止切换或要求您确认。

168 168

169当 Claude Code 无法判断你的组织的[托管插件](/docs/zh-CN/settings-reference#enabledplugins)提供哪些 PreModelSwitch hooks 时，例如因为托管插件加载失败，它拒绝切换而不是应用它，并在每次新尝试时再次检查。参阅 [Model switch was blocked by a PreModelSwitch hook](/docs/zh-CN/errors#model-switch-was-blocked-by-a-premodelswitch-hook) 了解消息和恢复。169当 Claude Code 无法判断您组织的[托管插件](/docs/zh-CN/settings-reference#enabledplugins)提供了哪些 PreModelSwitch hook 时（例如因为某个托管插件加载失败），它会拒绝切换而不是在未经检查的情况下应用，并在每次新尝试时再次检查。有关消息和恢复方法，请参阅 [Model switch was blocked by a PreModelSwitch hook](/docs/zh-CN/errors#model-switch-was-blocked-by-a-premodelswitch-hook)。

170 170

171当你通过 [Agent SDK](/docs/zh-CN/agent-sdk/overview) `setModel()` 方法、通过应用（如 [Desktop app](/docs/zh-CN/desktop)）或从通过 [Remote Control](/docs/zh-CN/remote-control) 连接的设备切换模型时，Claude Code 会检查该值在切换时：171当您通过 [Agent SDK](/docs/zh-CN/agent-sdk/overview) 的 `setModel()` 方法、通过应用（如 [Desktop app](/docs/zh-CN/desktop)）或从通过 [Remote Control](/docs/zh-CN/remote-control) 连接的设备切换模型时，Claude Code 会在切换时检查该值：

172 172

173* **Agent SDK 或应用**：使用 Claude Code v2.1.268 或更高版本，除非 Claude Code 在本地接受模型 ID（如它对你的[自定义模型选项](#add-a-custom-model-option)所做的那样），它在会话首次切换到它时与你的提供商确认该 ID。确认在每个提供商上运行，你的提供商不提供的 ID 在切换时被拒绝，而不是在你的下一个请求时失败。173* **Agent SDK 或应用**：使用 Claude Code v2.1.268 或更高版本时，除非 Claude Code 在本地接受该模型 ID（如对您的[自定义模型选项](#add-a-custom-model-option)所做的那样），否则它会在会话首次切换到该 ID 时向您的提供商确认。该确认在所有提供商上都会运行，您的提供商不提供的 ID 会在切换时被拒绝，而不是在您的下一个请求时失败。

174* **Remote Control**：在 Anthropic API 上，Claude Code 在本地检查该值并不发送请求。174* **Remote Control**：在 Anthropic API 上，Claude Code 在本地检查该值，不发送请求。

175 175

176参阅 [Model is not a recognized model id](/docs/zh-CN/errors#model-is-not-a-recognized-model-id) 和 [Model not found](/docs/zh-CN/errors#model-not-found) 了解消息。176有关这些消息，请参阅 [Model is not a recognized model id](/docs/zh-CN/errors#model-is-not-a-recognized-model-id) 和 [Model not found](/docs/zh-CN/errors#model-not-found)。

177 177

178如果你使用 `--model` 标志、`ANTHROPIC_MODEL` 环境变量或 `model` 设置设置模型，Claude Code 不会提前检查它，拼写错误的值会在第一个请求时产生 [There's an issue with the selected model](/docs/zh-CN/errors#theres-an-issue-with-the-selected-model)。178如果您使用 `--model` 标志、`ANTHROPIC_MODEL` 环境变量或 `model` 设置来设置模型，Claude Code 不会预先检查，拼写错误的值会在第一个请求时产生 [There's an issue with the selected model](/docs/zh-CN/errors#theres-an-issue-with-the-selected-model)。

179 179

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

181 181

182例如，在 Opus 上启动会话：182例如，在 Opus 上启动会话：

183 183

185claude --model opus185claude --model opus

186```186```

187 187

188然后从会话内切换模型：188然后在会话内切换模型：

189 189

190```text theme={null}190```text theme={null}

191/model sonnet191/model sonnet

206 为新会话设置默认模型206 为新会话设置默认模型

207</h4>207</h4>

208 208

209设置 `ANTHROPIC_DEFAULT_MODEL=<alias|name>` 来选择你的会话默认启动的模型。需要 Claude Code v2.1.236 或更高版本。209设置 `ANTHROPIC_DEFAULT_MODEL=<alias|name>` 来选择会话默认启动的模型。需要 Claude Code v2.1.236 或更高版本。

210 210

211Claude Code 仅在以下都没有选择模型时在变量的模型上启动新会话：211仅当以下各项都未选择模型时，Claude Code 才会在该变量的模型上启动新会话：

212 212

213* `--model` 标志213* `--model` 标志

214* `ANTHROPIC_MODEL`214* `ANTHROPIC_MODEL`

215* 任何设置文件中的 `model` 值，包括你使用 `/model` 保存的选择215* 任何设置文件中的 `model` 值，包括您使用 `/model` 保存的选择

216* [组织默认模型](#organization-default-model)216* [组织默认模型](#organization-default-model)

217 217

218你使用 `/model` 保存的选择在后续启动时也优先于变量。设置 `ANTHROPIC_MODEL` 代替，Claude Code 在下次启动时返回到该变量的模型，无论你使用 `/model` 保存了什么。218您使用 `/model` 保存的选择在后续启动时也优先于该变量。如果改为设置 `ANTHROPIC_MODEL`，无论您使用 `/model` 保存了什么，Claude Code 都会在下次启动时回到该变量的模型。

219 219

220Claude Code 也将 Default 选项解析为变量的模型，除非应用了组织默认模型。当 Default 选项解析为变量的模型时，`/model` 选择器中的 Default 行显示标签 Set by ANTHROPIC\_DEFAULT\_MODEL。220除非应用了组织默认模型，Claude Code 也会将 Default 选项解析为该变量的模型。当 Default 选项解析为该变量的模型时，`/model` 选择器中的 Default 行会显示标签 Set by ANTHROPIC\_DEFAULT\_MODEL。

221 221

222Claude Code 在这些情况下忽略变量，Default 选项解析如同你没有设置它：222在以下情况下，Claude Code 会忽略该变量，Default 选项会按未设置该变量的情况解析：

223 223

224* 你将其设置为 `default`、`inherit`、`opusplan` 或 `haiku`224* 您将其设置为 `default`、`inherit`、`opusplan` 或 `haiku`

225* [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 已打开225* [`enforceAvailableModels`](#enforce-the-allowlist-for-the-default-model) 已启用

226* 你的组织的[模型限制](#restrict-model-selection)排除该模型226* 您组织的[模型限制](#restrict-model-selection)排除了该模型

227* 该模型对你的账户不可用227* 该模型对您的账户不可用

228 228

229当新会话将在变量的模型上启动时，你使用 `claude --resume`、`--continue` 或 `/resume` 选择器恢复的会话也会在其上启动。Claude Code 不会恢复该会话的记录中保存的模型。否则 Claude Code 在你[恢复会话](#setting-your-model)时不使用变量。229当新会话会在该变量的模型上启动时，您使用 `claude --resume`、`--continue` 或 `/resume` 选择器恢复的会话也会在该模型上启动。Claude Code 不会恢复该会话的会话记录中保存的模型。在其他情况下，Claude Code 在您[恢复会话](#setting-your-model)时不使用该变量。

230 230

231<h4 id="a-new-session-starts-on-a-different-model-than-you-picked">231<h4 id="a-new-session-starts-on-a-different-model-than-you-picked">

232 新会话在与你选择的不同的模型上启动232 新会话在与您所选不同的模型上启动

233</h4>233</h4>

234 234

235当你使用 `/model` 选择模型，你的下一个会话在其他东西上启动时，这些是常见原因：235当您使用 `/model` 选择了模型，但下一个会话却在其他模型上启动时，常见原因如下：

236 236

237* **你为一个会话选择了它。** 在选择器中按 `s`、使用 `--model` 启动和在非交互模式中运行 `/model` 都仅适用于当前会话，保持你的保存默认值不变。237* **您只为一个会话选择了它。** 在选择器中按 `s`、使用 `--model` 启动以及在非交互模式中运行 `/model` 都仅适用于当前会话，不会改变已保存的默认值。

238* **优先级更高的东西设置了模型。** 项目或托管设置中的 `model` 值、你的 shell 中的 `ANTHROPIC_MODEL` 或你的管理员设置的[组织默认值](#organization-default-model)以覆盖用户选择在每次启动时再次应用。你的 `/model` 选择仍然被保存；它被超越。当项目或托管设置设置模型时，启动标题命名该文件。238* **优先级更高的项设置了模型。** 项目或托管设置中的 `model` 值、shell 中的 `ANTHROPIC_MODEL`，或管理员设置为覆盖用户选择的[组织默认值](#organization-default-model)，会在每次启动时再次生效。您的 `/model` 选择仍然已保存，只是优先级较低。当项目或托管设置设置了模型时，启动标题会指明该文件。

239* **Claude Code 无法保存你的选择。** `/model` 写入 `~/.claude/settings.json`。如果你无法写入该文件，例如因为另一个工具生成它或将其链接到只读副本，你选择的模型持续该会话，下次启动读取旧值。在生成文件的工具中设置 `model`，或使文件可写。参阅 [A change you made in Claude Code is lost in new sessions](/docs/zh-CN/settings#a-change-you-made-in-claude-code-is-lost-in-new-sessions)。239* **Claude Code 无法保存您的选择。** `/model` 会将 `model` 写入 `~/.claude/settings.json`。如果您无法写入该文件（例如因为另一个工具生成了该文件，或将其链接到只读副本），您所选的模型仅在当前会话中有效，下次启动时会读取旧值。请在生成该文件的工具中设置 `model`，或使该文件可写。参阅 [A change you made in Claude Code is lost in new sessions](/docs/zh-CN/settings#a-change-you-made-in-claude-code-is-lost-in-new-sessions)。

240* **你恢复了一个会话。** 你使用 `claude --resume` 或 `--continue` 恢复的会话通常[保持它使用的模型](#setting-your-model)而不是你的当前默认值。240* **您恢复了一个会话。** 使用 `claude --resume` 或 `--continue` 恢复的会话通常会[保持其原先使用的模型](#setting-your-model)，而不是当前的默认值。

241 241

242<h2 id="restrict-model-selection">242<h2 id="restrict-model-selection">

243 限制模型选择243 限制模型选择

310* [Claude Tag](https://claude.com/docs/claude-tag/overview) 会话在云环境中运行，但不接收服务器管理设置；在[自托管环境](/docs/zh-CN/self-hosted-environments)中，它们仍然读取运行器镜像中的托管设置文件。要为这些会话设置模型，请参阅 Claude Tag 管理员指南中的[为作用域选择模型](https://claude.com/docs/claude-tag/admins/customize#choose-the-model-for-a-scope)。310* [Claude Tag](https://claude.com/docs/claude-tag/overview) 会话在云环境中运行，但不接收服务器管理设置；在[自托管环境](/docs/zh-CN/self-hosted-environments)中，它们仍然读取运行器镜像中的托管设置文件。要为这些会话设置模型，请参阅 Claude Tag 管理员指南中的[为作用域选择模型](https://claude.com/docs/claude-tag/admins/customize#choose-the-model-for-a-scope)。

311* Cowork（Claude 桌面应用中的 Agent 式工作选项卡）在 Claude Code 上运行其会话，但按设计不从 claude.ai 管理控制台接收服务器管理设置。当您的服务器管理设置中的 `availableModels` 列表非空且用户选择列表外的模型时，服务器拒绝该模型用于远程 Cowork 会话。当托管设置文件存在于会话运行的地方时，它适用于 Cowork 会话；远程 Cowork 会话在 Anthropic 管理的 VM 上运行，其中不存在设备部署的文件。311* Cowork（Claude 桌面应用中的 Agent 式工作选项卡）在 Claude Code 上运行其会话，但按设计不从 claude.ai 管理控制台接收服务器管理设置。当您的服务器管理设置中的 `availableModels` 列表非空且用户选择列表外的模型时，服务器拒绝该模型用于远程 Cowork 会话。当托管设置文件存在于会话运行的地方时，它适用于 Cowork 会话；远程 Cowork 会话在 Anthropic 管理的 VM 上运行，其中不存在设备部署的文件。

312* [第三方提供商](/docs/zh-CN/server-managed-settings#platform-availability)（如 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws)）上的会话不接收服务器管理设置，因此通过 MDM 或托管设置文件在那里交付允许列表。312* [第三方提供商](/docs/zh-CN/server-managed-settings#platform-availability)（如 Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry 和 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws)）上的会话不接收服务器管理设置，因此通过 MDM 或托管设置文件在那里交付允许列表。

313* 服务器管理交付还需要会话使用[符合条件的登录或密钥](/docs/zh-CN/server-managed-settings#platform-availability)进行身份验证。仅通过 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本生成密钥的舰队应通过 MDM 或托管设置文件交付允许列表。313* 来自管理控制台的交付还要求会话使用登录到您组织的[符合条件的登录](/docs/zh-CN/server-managed-settings#platform-availability)或为您组织签发的 OAuth 令牌来获取设置。对于使用 API 密钥进行身份验证的设备群（无论是直接配置的，还是由 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本生成的），请通过 MDM 或托管设置文件交付允许列表。

314* 桌面代码选项卡还托管 [SSH 会话](/docs/zh-CN/desktop#ssh-sessions)，它们从运行的远程主机读取托管设置文件。请参阅[桌面托管设置](/docs/zh-CN/desktop#managed-settings)。314* 桌面代码选项卡还托管 [SSH 会话](/docs/zh-CN/desktop#ssh-sessions)，它们从运行的远程主机读取托管设置文件。请参阅[桌面托管设置](/docs/zh-CN/desktop#managed-settings)。

315* claude.ai 和桌面应用中的模型选择器隐藏或灰显您的组织的允许列表排除的模型。选择器状态是用户的便利；它不强制执行允许列表。315* claude.ai 和桌面应用中的模型选择器隐藏或灰显您的组织的允许列表排除的模型。选择器状态是用户的便利；它不强制执行允许列表。

316 316

562 562

563本部分涵盖来自 Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 的基于内容的回退。关于模型过载或不可用时的基于可用性的回退，请参阅[备用模型链](#fallback-model-chains)。563本部分涵盖来自 Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 的基于内容的回退。关于模型过载或不可用时的基于可用性的回退，请参阅[备用模型链](#fallback-model-chains)。

564 564

565Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 运行安全分类器，最常标记网络安全和生物学内容。当分类器标记请求且标记的类别有备用模型时，Claude Code 在该模型上重新运行请求并在会话记录中显示通知。对于这两个类别，备用模型取决于哪个模型拒绝：565Fable 模型、Opus 5.5、Sonnet 5.5 和 Opus 5 运行安全分类器，最常标记网络安全和生物学内容。对于这两个类别，备用模型取决于哪个模型拒绝：

566 566

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

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

570 570

571在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，Claude Code 通过您的部署的模型 ID 解析这些目标。请参阅[在 Bedrock、Agent Platform 和 Foundry 上启用回退](#enable-fallback-on-bedrock-agent-platform-and-foundry)。571在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，Claude Code 通过您的部署的模型 ID 解析这些目标。请参阅[在 Bedrock、Agent Platform 和 Foundry 上启用回退](#enable-fallback-on-bedrock-agent-platform-and-foundry)。

572 572

573当 Claude Code 将被标记的请求切换到其类别对应的备用模型时，它会在该模型上重新运行请求。在您的主对话中，它会在会话记录中显示通知。如果希望先被询问，请参阅[切换前询问](#ask-before-switching)。

574

573回退后，会话继续在备用模型上。要返回到您的原始模型，运行 [`/model`](#setting-your-model)。575回退后，会话继续在备用模型上。要返回到您的原始模型，运行 [`/model`](#setting-your-model)。

574 576

575基于类别的回退需要 Claude Code v2.1.219 或更高版本。在 v2.1.219 之前，每个标记的 Fable 5 请求都在您提供商的默认 Opus 模型上重新运行，Opus 5 不是回退源。577基于类别的回退需要 Claude Code v2.1.219 或更高版本。在 v2.1.219 之前，每个标记的 Fable 5 请求都在您提供商的默认 Opus 模型上重新运行，Opus 5 不是回退源。

580 回退后的 effort 级别582 回退后的 effort 级别

581</h4>583</h4>

582 584

583当 Claude Code 将您的会话切换到备用模型时，它会保留被标记请求运行时的 effort 级别，而不是使用该模型的默认 effort。例如，在 Opus 5.5 上以其默认 `medium` 运行的会话回退到 Opus 4.8 后仍保持 `medium`，尽管 Opus 4.8 默认为 `high`。585当 Claude Code 将您的会话切换到备用模型时，它会保留被标记请求运行时的 effort 级别。例如，在 Opus 5.5 上以其默认 `medium` 运行的会话回退到 Opus 4.8 后仍保持 `medium`，尽管 Opus 4.8 默认为 `high`。

584 586

585在以下情况下会应用不同的级别：587在以下情况下会应用不同的级别：

586 588

587* **设置或组织默认值**：您的设置中适用于备用模型的级别，或您的组织为其设置的默认 effort，会改为生效。

588* **您自己的更改**：一旦您选择了 effort 级别、在 `/model` 中选择了模型或稍后恢复会话，被标记请求的级别就不再沿用。589* **您自己的更改**：一旦您选择了 effort 级别、在 `/model` 中选择了模型或稍后恢复会话，被标记请求的级别就不再沿用。

589* **Skill effort**：skill 的 `effort` frontmatter 为被标记请求设置的级别适用于该轮次，后续轮次以 [effort 解析顺序](#adjust-effort-level)为备用模型给出的级别运行。590* **Skill effort**：skill 的 `effort` frontmatter 为被标记请求设置的级别适用于该轮次，后续轮次以 [effort 解析顺序](#adjust-effort-level)为备用模型给出的级别运行。

590 591

591会话标题在模型名称旁边显示当前生效的级别。要更改它，在会话中运行 `/effort`。592在会话中，运行 `/effort status` 查看当前生效的级别，或运行 `/effort` 更改它。

592 593

593<h4 id="check-what-triggered-fallback">594<h4 id="check-what-triggered-fallback">

594 检查触发回退的原因595 检查触发回退的原因

602 切换前询问603 切换前询问

603</h4>604</h4>

604 605

605要决定每次请求被标记时发生什么，而不是自动切换，运行 `/config` 并关闭 **Switch models when a message is flagged**，或在您的设置文件中将 [`switchModelsOnFlag`](/docs/zh-CN/settings-reference#switchmodelsonflag) 设置为 `false`。标记的请求然后暂停会话，有两个选项：切换到备用模型，或编辑提示词并在当前模型上重试。606要决定每次请求被标记时发生什么，运行 `/config`，选择 **Switch models when a message is flagged**，然后选择 **Ask each time**。您也可以在设置文件中将 [`switchModelsOnFlag`](/docs/zh-CN/settings-reference#switchmodelsonflag) 设置为 `false`。之后，Claude Code 会在将要切换模型的标记请求处暂停，并为您提供两个选项：切换到备用模型，或编辑提示词并重试。

607

608在交互式会话中，第一次有标记的请求将要切换模型时，Claude Code 可能会询问今后是否自动切换。仅当您尚未设置 `switchModelsOnFlag` 时它才会询问，并将您的选择作为该键保存到您的用户设置中。

606 609

607某些情况的行为不同：610如果您选择保留在当前模型上，保存的值为 `false`，与 **Ask each time** 相同。如果您关闭该询问，Claude Code 不保存任何内容，并在下次有标记的请求将要切换模型时再次询问。

611

612当您选择了 **Ask each time** 时，某些情况的行为不同：

608 613

609* 当标记的类别没有备用模型时，例如 Opus 5 或 Sonnet 5.5 上的生物学标记，Claude Code 不显示提示，请求以拒绝结束。614* 当标记的类别没有备用模型时，例如 Opus 5 或 Sonnet 5.5 上的生物学标记，Claude Code 不显示提示，请求以拒绝结束。

610* 如果两个模型都标记相同的请求，您可以编辑提示词并重试，或启动新会话。615* 如果两个模型都标记相同的请求，您可以编辑提示词并重试，或启动新会话。

611* 在移动应用上的[云端会话](/docs/zh-CN/claude-code-on-the-web)中，不支持编辑和重试。切换模型，或从桌面浏览器或桌面应用继续会话。616* 在移动应用上的[云端会话](/docs/zh-CN/claude-code-on-the-web)中，不支持编辑和重试。切换模型，或从桌面浏览器或桌面应用继续会话。

612* 在[非交互模式](/docs/zh-CN/cli-reference#cli-flags)和无法显示提示的 SDK 集成中，标记的请求以拒绝结束轮次。617* 在[非交互模式](/docs/zh-CN/cli-reference#cli-flags)和无法显示提示的 SDK 集成中，标记的请求以拒绝结束轮次。

618* 在[子代理](/docs/zh-CN/sub-agents)中，Claude Code 不显示提示，将要切换模型的标记请求会在备用模型上重新运行。

613* 当回退目标被 [`availableModels`](#restrict-model-selection) 阻止时，Claude Code 不显示提示。标记的请求以拒绝结束，与目标被阻止时的自动回退相同。619* 当回退目标被 [`availableModels`](#restrict-model-selection) 阻止时，Claude Code 不显示提示。标记的请求以拒绝结束，与目标被阻止时的自动回退相同。

614 620

615<h4 id="enable-fallback-on-bedrock-agent-platform-and-foundry">621<h4 id="enable-fallback-on-bedrock-agent-platform-and-foundry">

628* **每个源模型**：将 `ANTHROPIC_DEFAULT_OPUS_MODEL` 设置为 Opus 模型 ID 以打开回退并为标记的类别提供目标。命名 Opus 系列外的模型或拒绝的模型的固定值会使拒绝成立。634* **每个源模型**：将 `ANTHROPIC_DEFAULT_OPUS_MODEL` 设置为 Opus 模型 ID 以打开回退并为标记的类别提供目标。命名 Opus 系列外的模型或拒绝的模型的固定值会使拒绝成立。

629* **Sonnet 5.5**：除了 Opus 固定值外，设置 `ANTHROPIC_DEFAULT_SONNET_MODEL` 或在提供商的模型列表中保留 Sonnet 5 条目以提供请求重新运行的模型。命名 Sonnet 系列外的模型或 Sonnet 5.5 本身的 Sonnet 固定值会使拒绝成立。635* **Sonnet 5.5**：除了 Opus 固定值外，设置 `ANTHROPIC_DEFAULT_SONNET_MODEL` 或在提供商的模型列表中保留 Sonnet 5 条目以提供请求重新运行的模型。命名 Sonnet 系列外的模型或 Sonnet 5.5 本身的 Sonnet 固定值会使拒绝成立。

630 636

637备用模型的上下文窗口还必须至少与会话的上下文窗口一样大，否则 Claude Code 不会切换，标记的请求会以相同的拒绝结束。在这些提供商上，源模型默认运行 [1M 上下文窗口](#extended-context)。请固定一个同样如此的模型，例如在 `ANTHROPIC_DEFAULT_OPUS_MODEL` 中固定 Opus 4.8，或在 `ANTHROPIC_DEFAULT_SONNET_MODEL` 中固定 Sonnet 5，并使用 Claude Code [能够匹配到该模型](#pin-models-for-third-party-deployments)的 ID。

638

631<h4 id="security-research-and-biology-workloads">639<h4 id="security-research-and-biology-workloads">

632 安全研究和生物学工作负载640 安全研究和生物学工作负载

633</h4>641</h4>

634 642

635进攻性安全或生物学中的工作负载，包括渗透测试、Capture the Flag (CTF) 练习和生物学相邻代码库，经常触发回退，通常在第一个请求上。对于 Fable 5.1、Fable 5 或 Opus 5.5 上的实质性生物学工作，Claude Code 在第一个标记的请求处将会话移动到 Opus 5，后来的生物学标记请求在那里以拒绝结束，因为 Opus 5 没有生物学回退。在 Opus 5 和 Sonnet 5.5 上，您从第一个标记的请求获得这些拒绝。643进攻性安全或生物学中的工作负载，包括渗透测试、Capture the Flag (CTF) 练习和生物学相邻代码库，经常触发回退，通常在第一个请求上。对于 Fable 5.1、Fable 5 或 Opus 5.5 上的实质性生物学工作，第一个切换模型的标记请求会将会话移动到 Opus 5，后来的生物学标记请求在那里以拒绝结束，因为 Opus 5 没有生物学回退。在 Opus 5 和 Sonnet 5.5 上，您从第一个标记的请求获得这些拒绝。

636 644

637这是这些域的预期路由，不是账户标记。如果您的组织需要 Fable 级别的能力来完成这项工作，请向您的 Anthropic 账户团队询问受信任的访问计划。645这是这些域的预期路由，不是账户标记。如果您的组织需要 Fable 级别的能力来完成这项工作，请向您的 Anthropic 账户团队询问受信任的访问计划。

638 646

656 664

6571. 明确选择：[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars#variables) 环境变量、使用 `--effort` 启动或会话中的 `/effort`（[非交互式 `/effort` 的效果更窄](#non-interactive-effort)）6651. 明确选择：[`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars#variables) 环境变量、使用 `--effort` 启动或会话中的 `/effort`（[非交互式 `/effort` 的效果更窄](#non-interactive-effort)）

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

6593. 模型的默认 effort：在支持 effort 的每个模型上为 `high`，除了 Opus 5.5、Sonnet 5.5 和 Haiku 5.5 默认为 `medium`、Opus 4.7 默认为 `xhigh`，当您的组织为其[组织默认模型](#organization-default-model)设置默认 effort 级别时，当您运行该模型时该级别是默认值。自动模型回退后适用的级别，请参阅[回退后的 effort 级别](#effort-level-after-a-fallback)。6673. 模型的默认 effort：在支持 effort 的每个模型上为 `high`，除了 Opus 5.5、Sonnet 5.5 和 Haiku 5.5 默认为 `medium`、Opus 4.7 默认为 `xhigh`，当您的组织为其[组织默认模型](#organization-default-model)设置默认 effort 级别时，当您运行该模型时该级别是默认值

668

669自动模型回退后适用的级别，请参阅[回退后的 effort 级别](#effort-level-after-a-fallback)。

660 670

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

662 672

777 787

778<a id="extended-context-with-1m" />788<a id="extended-context-with-1m" />

779 789

790<span id="sonnet-5-5-and-sonnet-5-context-window" />

791

780<h3 id="extended-context">792<h3 id="extended-context">

781 扩展上下文793 扩展上下文

782</h3>794</h3>

783 795

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

785 797

786在 Anthropic API 上，Fable 5.1、Fable 5、Sonnet 5 及更高版本、Haiku 5.5 和 Opus 4.7 及更高版本在每个套餐上运行 1M 窗口，包括 Pro。您不需要为这些模型上的 1M 窗口选择 `[1m]` 变体或打开使用额度。Fable 使用本身可以在某些套餐上计费到使用额度；请参阅[Fable 和使用额度](#fable-and-usage-credits)。798Fable 5.1、Fable 5、Sonnet 5 及更高版本、Haiku 5.5 和 Opus 4.7 及更高版本默认运行 1M 窗口，无需 `[1m]` 后缀。这包括 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上的会话，以及 [Claude apps gateway](/docs/zh-CN/claude-apps-gateway) 会话。要改为以 200K 窗口运行它们，请参阅[关闭 1M 上下文](#turn-off-1m-context)。

787 799

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

789 801

795 807

796Claude 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]`。808Claude 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]`。

797 809

798<span id="context-window-behind-a-gateway" />810在 Anthropic API 上，1M 上下文窗口使用标准模型定价，超过 200K 的 token 没有溢价，但 Haiku 5.5 除外，它[在提示词超过 100K token 时费用更高](#haiku-5-5-context-window-and-pricing)。对于扩展上下文包含在您的订阅中的套餐，使用仍由您的订阅覆盖。对于通过使用额度访问扩展上下文的套餐，token 计费到使用额度。

~~799~~

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

~~801~~

802要关闭 1M 上下文，设置 `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`。Claude Code 从模型选择器中删除 1M 模型变体。在具有原生 1M 窗口的模型上，例如 Sonnet 5 和 Fable 模型，它也将模型视为具有 200K 上下文窗口：

~~803~~

804* 启用自动压缩时，会话在 200K 边界处通过[自动压缩](#set-the-auto-compact-window)进行压缩。将自动压缩窗口设置在 200K 以上不会解除该限制，因为 Claude Code 将该窗口限制为模型的上下文窗口。

805* 禁用自动压缩时，会话在 200K 边界处停止，出现[上下文限制错误](/docs/zh-CN/errors#prompt-is-too-long)，而不是压缩。

806 811

807在 v2.1.223 之前，Claude Code 仅将 Sonnet 5、Opus 4.8 和 Opus 5 会话限制在 200K。请参阅[环境变量](/docs/zh-CN/env-vars)。812<h4 id="select-1m-context-for-opus-4-6-or-sonnet-4-6">

~~808~~ 813 为 Opus 4.6 或 Sonnet 4.6 选择 1M 上下文

8091M 上下文窗口使用标准模型定价，超过 200K 的 token 没有溢价，但 Haiku 5.5 除外，它[在提示词超过 100K token 时费用更高](#haiku-5-5-context-window-and-pricing)。对于扩展上下文包含在您的订阅中的套餐，使用仍由您的订阅覆盖。对于通过使用额度访问扩展上下文的套餐，token 计费到使用额度。814</h4>

~~810~~

811如果您的账户支持 1M 上下文，该选项会出现在最新版本的 Claude Code 的 `/model` 选择器中。如果您看不到它，请重新启动您的会话，在第三方提供商上检查您的部署是否使用 `ANTHROPIC_DEFAULT_*_MODEL` 变量[固定了模型](#pin-models-for-third-party-deployments)。

812 815

813您也可以使用 `[1m]` 后缀与模型别名或完整模型名称：816要按名称选择 1M 变体，请在模型别名或完整模型名称后附加 `[1m]` 后缀：

814 817

815```text theme={null}818```text theme={null}

816# Use the opus[1m] or sonnet[1m] alias819# Append [1m] to a full model name

817/model opus[1m]820/model claude-opus-4-6[1m]

818/model sonnet[1m]821/model claude-sonnet-4-6[1m]

819 822

820# Or append [1m] to a full model name823# Or to an alias: the suffix applies to the model the alias resolves to

821/model claude-opus-4-8[1m]824/model opus[1m]

822```825```

823 826

824<h4 id="sonnet-5-5-and-sonnet-5-context-window">827<span id="context-window-behind-a-gateway" />

825 Sonnet 5.5 和 Sonnet 5 上下文窗口828

829<h4 id="context-window-behind-an-llm-gateway">

830 LLM 网关后面的上下文窗口

826</h4>831</h4>

827 832

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

829 834

830Claude Code 在 [LLM 网关](/docs/zh-CN/llm-gateway)或另一个自定义 `ANTHROPIC_BASE_URL` 后面给 Sonnet 5.5 和 Sonnet 5 相同的 1M 窗口。如果您的网关强制更低的限制，请参阅[网关后面的上下文窗口](#context-window-behind-a-gateway)。835<h4 id="turn-off-1m-context">

836 关闭 1M 上下文

837</h4>

831 838

832此设置将窗口预算为 200K：839要将会话保持在 200K 窗口，请在您的 shell 或[设置文件](/docs/zh-CN/env-vars#set-environment-variables)中设置 `CLAUDE_CODE_DISABLE_1M_CONTEXT=1`。Claude Code 从模型选择器中删除 `[1m]` 模型变体。在默认运行 1M 窗口的模型上，例如 Fable 模型、Sonnet 5 及更高版本和 Opus 4.7 及更高版本，它也将模型视为具有 200K 上下文窗口：

833 840

834* **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`**：将具有原生 1M 窗口的每个模型上的会话限制在 200K 窗口；请参阅[扩展上下文](#extended-context)了解该限制如何被强制执行。对于需要限制上下文的部署很有用。841* 启用自动压缩时，会话在 200K 边界处通过[自动压缩](#set-the-auto-compact-window)进行压缩。将自动压缩窗口设置在 200K 以上不会解除该限制，因为 Claude Code 将该窗口限制为模型的上下文窗口。

842* 禁用自动压缩时，会话在 200K 边界处停止，出现[上下文限制错误](/docs/zh-CN/errors#prompt-is-too-long)，而不是压缩。

835 843

836<h4 id="haiku-5-5-context-window-and-pricing">844<h4 id="haiku-5-5-context-window-and-pricing">

837 Haiku 5.5 上下文窗口和定价845 Haiku 5.5 上下文窗口和定价

857 865

858* **对于当前模型，在此会话及以后的会话中**：运行 `/autocompact` 命令并指定一个值，例如 `/autocompact 500k`。Claude Code 将其保存到您的用户设置中 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 下的当前模型条目，并将其应用于当前会话。如果更高优先级的[设置作用域](/docs/zh-CN/settings#settings-precedence)（例如托管设置）为该模型或所有模型设置了自己的窗口，该命令会保存您的值，但会话会保持该作用域的窗口，命令会说明这一点。运行 `/autocompact auto` 以返回为您的模型调整的窗口。在 v2.1.288 之前，该命令会为所有模型保存同一个窗口，即顶层的 `autoCompactWindow`。866* **对于当前模型，在此会话及以后的会话中**：运行 `/autocompact` 命令并指定一个值，例如 `/autocompact 500k`。Claude Code 将其保存到您的用户设置中 [`modelSettings`](/docs/zh-CN/settings-reference#modelsettings) 下的当前模型条目，并将其应用于当前会话。如果更高优先级的[设置作用域](/docs/zh-CN/settings#settings-precedence)（例如托管设置）为该模型或所有模型设置了自己的窗口，该命令会保存您的值，但会话会保持该作用域的窗口，命令会说明这一点。运行 `/autocompact auto` 以返回为您的模型调整的窗口。在 v2.1.288 之前，该命令会为所有模型保存同一个窗口，即顶层的 `autoCompactWindow`。

859* **对于所有模型**：在设置文件中设置 [`autoCompactWindow`](/docs/zh-CN/settings-reference#autocompactwindow)，例如在 `~/.claude/settings.json` 中设置 `"autoCompactWindow": 200000`。对于某个模型，您使用 `/autocompact` 为该模型保存的窗口优先于同一文件中的此键。867* **对于所有模型**：在设置文件中设置 [`autoCompactWindow`](/docs/zh-CN/settings-reference#autocompactwindow)，例如在 `~/.claude/settings.json` 中设置 `"autoCompactWindow": 200000`。对于某个模型，您使用 `/autocompact` 为该模型保存的窗口优先于同一文件中的此键。

860* **对于一次启动**：启动 Claude Code 时传递 [`--autocompact`](/docs/zh-CN/cli-reference#cli-flags)。该标志会为该次启动覆盖您保存的设置，而不会更改它，`claude --autocompact auto` 会以调整的窗口运行会话，即使您保存的设置有一个值。与 `/autocompact` 不同，该标志不会被更高优先级的设置范围（例如托管设置）抢占。868* **对于一次启动**：启动 Claude Code 时传递 [`--autocompact`](/docs/zh-CN/cli-reference#cli-flags)。该标志会为该次启动覆盖您保存的设置，而不会更改它，`claude --autocompact auto` 会以调整的窗口运行会话，即使您保存的设置有一个值。与 `/autocompact` 不同，该标志不会被更高优先级的设置作用域（例如托管设置）抢占。

861* **在脚本和云环境中**：设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/zh-CN/env-vars)。设置后，它优先于命令、标志和设置，`/autocompact` 会报告该覆盖而不是更改窗口。869* **在脚本和云环境中**：设置 [`CLAUDE_CODE_AUTO_COMPACT_WINDOW`](/docs/zh-CN/env-vars)。设置后，它优先于命令、标志和设置，`/autocompact` 会报告该覆盖而不是更改窗口。

862 870

863命令和标志接受 100K 到 1M 令牌的窗口大小，采用以下任何形式：871命令和标志接受 100K 到 1M token 的窗口大小，采用以下任何形式：

864 872

865* 纯令牌计数，例如 `200000`873* 纯 token 计数，例如 `200000`

866* `k` 或 `M` 后缀，例如 `500k` 或 `1M`874* `k` 或 `M` 后缀，例如 `500k` 或 `1M`

867* 100 到 1000 之间的裸数字，表示千位，所以 `200` 设置 200,000875* 100 到 1000 之间的裸数字，表示千位，所以 `200` 设置 200,000

868 876

869环境变量仅接受纯令牌计数。Claude Code 将窗口限制在模型的上下文窗口。877环境变量仅接受纯 token 计数。Claude Code 将窗口限制在模型的上下文窗口。

870 878

871<h3 id="default-auto-compact-thresholds">879<h3 id="default-auto-compact-thresholds">

872 默认自动压缩阈值880 默认自动压缩阈值

874 882

875如果您没有设置自动压缩窗口，Claude Code 会在对话达到模型的上下文限制时进行压缩，除了以下会话：883如果您没有设置自动压缩窗口，Claude Code 会在对话达到模型的上下文限制时进行压缩，除了以下会话：

876 884

877* [云会话](/docs/zh-CN/claude-code-on-the-web)在对话接近模型限制时进行压缩885* [云端会话](/docs/zh-CN/claude-code-on-the-web)在对话接近模型限制时进行压缩

878* Sonnet 4.6 和 Opus 4.6（不带[扩展上下文](#extended-context)）在 200K 边界处进行压缩，Opus 4.8 和更高版本在使用 200K 上下文窗口运行时也是如此，例如在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上886* Sonnet 4.6 和 Opus 4.6（不带[扩展上下文](#extended-context)）在 200K 边界处进行压缩

879* 当您设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-CN/env-vars) 时，具有原生 1M 窗口的模型（例如 Sonnet 5 和 Fable 模型）在 200K 边界处进行压缩887* 当您设置 [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/zh-CN/env-vars) 时，具有原生 1M 窗口的模型（例如 Sonnet 5 和 Fable 模型）在 200K 边界处进行压缩

880* 使用原生 1M 窗口运行的模型在窗口填满之前进行压缩，默认情况下约为 967K token。在 Anthropic API 上，这些包括 Sonnet 5、Haiku 5.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)888* 使用原生 1M 窗口运行的模型在窗口填满之前进行压缩，默认情况下约为 967K token。这些模型包括 Fable 模型、Sonnet 5 及更高版本、Haiku 5.5 以及 Opus 4.7 及更高版本。在自定义 `ANTHROPIC_BASE_URL` 后面，请参阅[网关后面的上下文窗口](#context-window-behind-a-gateway)

881* 在 Claude Code 不识别的模型 ID（例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名）上的会话在 Claude Code 为该 ID 假设的上下文窗口处进行压缩；请参阅[为网关或自定义模型 ID 更正窗口](#correct-the-window-for-a-gateway-or-custom-model-id)889* 在 Claude Code 不识别的模型 ID（例如 [LLM 网关](/docs/zh-CN/llm-gateway)别名）上的会话在 Claude Code 为该 ID 假设的上下文窗口处进行压缩；请参阅[为网关或自定义模型 ID 更正窗口](#correct-the-window-for-a-gateway-or-custom-model-id)

882 890

883<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">891<h3 id="correct-the-window-for-a-gateway-or-custom-model-id">

886 894

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

888 896

889变量的应用方式取决于 ID。当 Claude Code 不以 `claude-`（任何大小写）开头时，或当它携带 Claude Code 在读取 ID 时剥离的后缀（例如 Google Cloud 的 Agent Platform 上使用的 `@YYYYMMDD` 日期）时，Claude Code 将 ID 视为提供商或自定义拼写。在 v2.1.259 之前，Claude Code 没有计算剥离的后缀，所以带有日期后缀的无法识别的 `claude-` ID 被视为裸 `claude-` 名称。897变量的应用方式取决于 ID。当 ID 不以 `claude-`（任何大小写）开头时，或当它携带 Claude Code 在读取 ID 时剥离的后缀（例如 Google Cloud 的 Agent Platform 上使用的 `@YYYYMMDD` 日期）时，Claude Code 将 ID 视为提供商或自定义拼写。在 v2.1.259 之前，Claude Code 没有计算剥离的后缀，所以带有日期后缀的无法识别的 `claude-` ID 被视为裸 `claude-` 名称。

890 898

891无法识别的提供商或自定义拼写、相同拼写加上 `[1m]` 和所有其他 ID 是三种不同的情况：899无法识别的提供商或自定义拼写、相同拼写加上 `[1m]` 和所有其他 ID 是三种不同的情况：

892 900

947| 环境变量 | 描述 |955| 环境变量 | 描述 |

948| - | - |956| - | - |

949| `ANTHROPIC_DEFAULT_FABLE_MODEL` | 用于 `fable` 的模型，以及 Claude Code 识别为 Fable 模型的模型 ID，用于[第三方提供商上的自动模型回退](#automatic-model-fallback) |957| `ANTHROPIC_DEFAULT_FABLE_MODEL` | 用于 `fable` 的模型，以及 Claude Code 识别为 Fable 模型的模型 ID，用于[第三方提供商上的自动模型回退](#automatic-model-fallback) |

953| `CLAUDE_CODE_SUBAGENT_MODEL` | [subagents](/docs/zh-CN/sub-agents#choose-a-model)、[agent team](/docs/zh-CN/agent-teams#specify-teammates-and-models) 队友和[工作流](/docs/zh-CN/workflows)代理的默认模型，这些代理没有以其他方式分配模型。接受别名（如 `haiku`）或完整模型名称。每次调用的模型或定义的 `model` 字段（包括 `inherit`）优先。要更改该设置，请设置 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model) |961| `CLAUDE_CODE_SUBAGENT_MODEL` | [子代理](/docs/zh-CN/sub-agents#choose-a-model)、[agent team](/docs/zh-CN/agent-teams#specify-teammates-and-models) 队友和[工作流](/docs/zh-CN/workflows) Agent 的默认模型，适用于未以其他方式分配模型的情况。接受别名（如 `haiku`）或完整模型名称。每次调用的模型或定义的 `model` 字段（包括 `inherit`）优先。要改变这一点，请设置 [`CLAUDE_CODE_SUBAGENT_MODEL_FORCE`](/docs/zh-CN/sub-agents#run-every-subagent-on-one-model) |

954 962

955在第三方提供商上，[自定义固定模型显示和功能](#customize-pinned-model-display-and-capabilities)描述了固定模型在 `/model` 选择器中的行显示的内容。963在第三方提供商上，[自定义固定模型显示和功能](#customize-pinned-model-display-and-capabilities)描述了固定模型在 `/model` 选择器中的行显示的内容。

956 964

962 970

963当通过 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai)、[Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 或 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 部署 Claude Code 时，在向用户推出前固定模型版本。971当通过 [Amazon Bedrock](/docs/zh-CN/amazon-bedrock)、[Google Cloud's Agent Platform](/docs/zh-CN/google-vertex-ai)、[Microsoft Foundry](/docs/zh-CN/microsoft-foundry) 或 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 部署 Claude Code 时，在向用户推出前固定模型版本。

964 972

965不固定模型，Claude Code 会使用模型别名（如 `fable`、`opus`、`sonnet` 和 `haiku`），这些别名会解析为每个提供商的内置默认模型 ID。该默认值可能滞后于最新的 Anthropic 版本，并且它指向的模型可能尚未在用户账户中启用。当默认值不可用时，Amazon Bedrock 和 Google Cloud's Agent Platform 用户会看到通知并回退到该默认模型的早期版本，或当默认值是 Opus 模型且没有 Opus 版本可用时回退到默认 Sonnet 模型。Microsoft Foundry 用户会看到错误，因为 Microsoft Foundry 没有等效的启动检查。973不固定模型，Claude Code 会使用模型别名（如 `fable`、`opus`、`sonnet` 和 `haiku`），这些别名会解析为每个提供商的内置默认模型 ID。该默认值可能滞后于最新的 Anthropic 版本，并且它指向的模型可能尚未在用户账户中启用。当默认值不可用时，Amazon Bedrock 和 Google Cloud's Agent Platform 用户会看到通知，会话会回退到该默认模型的早期版本，或当默认值是 Opus 模型且没有 Opus 版本可用时回退到默认 Sonnet 模型。Microsoft Foundry 用户则会看到错误，因为 Microsoft Foundry 没有等效的启动检查。

966 974

967在 Amazon Bedrock 和 Google Cloud's Agent Platform 上，以特定 Sonnet 或 Opus 版本启动会话的用户（例如使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 设置），会将该版本固定为会话的默认值，用于匹配的别名：启动检查会跳过它替换的内置默认值，并且不显示回退通知。在 v2.1.211 之前，即使会话模型被显式配置，检查也会运行并可能显示通知。975在 Amazon Bedrock 和 Google Cloud's Agent Platform 上，以特定 Sonnet 或 Opus 版本启动会话的用户（例如使用 `--model`、`ANTHROPIC_MODEL` 或 `model` 设置），会将该版本固定为会话的默认值，用于匹配的别名：启动检查会跳过它替换的内置默认值，并且不显示回退通知。在 v2.1.211 之前，即使会话模型被显式配置，检查也会运行并可能显示通知。

968 976

980 988

981对 `ANTHROPIC_DEFAULT_FABLE_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 应用相同的模式。有关所有提供商的当前和旧版模型 ID，请参阅[模型概览](https://platform.claude.com/docs/en/about-claude/models/overview)。要将用户升级到新模型版本，请更新这些环境变量并重新部署。989对 `ANTHROPIC_DEFAULT_FABLE_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL` 应用相同的模式。有关所有提供商的当前和旧版模型 ID，请参阅[模型概览](https://platform.claude.com/docs/en/about-claude/models/overview)。要将用户升级到新模型版本，请更新这些环境变量并重新部署。

982 990

983要为固定模型启用[扩展上下文](#extended-context)，请在 `ANTHROPIC_DEFAULT_OPUS_MODEL`、`ANTHROPIC_DEFAULT_SONNET_MODEL` 或 `ANTHROPIC_DEFAULT_FABLE_MODEL` 中的模型 ID 后附加 `[1m]`：991具有原生 1M 窗口的固定模型（如 Opus 4.8 或 Sonnet 5），当 Claude Code 能够将固定 ID 与该模型匹配时，无需任何后缀即可以 [1M 上下文窗口](#extended-context)运行。当 ID 包含该模型的 Anthropic API ID（例如 `us.anthropic.claude-opus-4-8` 包含 `claude-opus-4-8`），或 [`modelOverrides`](#override-model-ids-per-version) 条目将该模型映射到该 ID 时，即视为匹配。对于 Claude Code 无法与模型匹配的固定 ID，会话默认以 200K 窗口运行，除非该 ID 带有 `[1m]` 后缀。

992

993对于通过其 `[1m]` 变体达到 1M 的模型（如 Opus 4.6 或 Sonnet 4.6），请在 `ANTHROPIC_DEFAULT_OPUS_MODEL` 或 `ANTHROPIC_DEFAULT_SONNET_MODEL` 中的模型 ID 后附加 `[1m]` 以启用扩展上下文：

984 994

985```bash theme={null}995```bash theme={null}

986export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8[1m]'996export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-6[1m]'

987```997```

988 998

989使用 `[1m]` 后缀，1M 上下文窗口适用于固定别名的所有使用，包括 [`opusplan`](#opusplan-model-setting) 的 plan-mode Opus 阶段和 `model` frontmatter 命名别名的 [subagents](/docs/zh-CN/sub-agents#choose-a-model)。999使用 `[1m]` 后缀，1M 上下文窗口适用于固定别名的所有使用，包括 [`opusplan`](#opusplan-model-setting) 的计划模式 Opus 阶段和 `model` frontmatter 指定该别名的[子代理](/docs/zh-CN/sub-agents#choose-a-model)。

990 1000

991* Claude Code 在将模型 ID 发送到您的提供商之前会删除该后缀。1001* Claude Code 在将模型 ID 发送到您的提供商之前会删除该后缀。

992* 仅当底层模型[支持 1M 上下文](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)时才附加 `[1m]`。1002* 仅当底层模型[支持 1M 上下文](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model)时才附加 `[1m]`。

993* 该后缀按变量读取，而不是按模型读取。在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，一个变量中没有 `[1m]` 的模型 ID 使用 200K 上下文，即使另一个变量使用相同的模型和后缀。Sonnet 5 在这些提供商上始终以 1M 窗口运行，从不需要该后缀。1003* 该后缀按变量读取，而不是按模型读取。在 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry 上，一个变量中没有 `[1m]` 的 Opus 4.6 或 Sonnet 4.6 ID 使用 200K 上下文，即使另一个变量使用相同的模型和后缀。

994 1004

995当您设置 `ANTHROPIC_DEFAULT_*_MODEL` 变量时，`/model` 选择器会显示该模型的一行来替代该家族的内置行，包括任何 1M 上下文行。要在不向该变量添加后缀的情况下到达 1M 窗口，您的用户运行 `/model opus[1m]`，Claude Code 会将后缀应用于该变量命名的模型。`/model sonnet[1m]` 的工作方式相同。1005当您设置 `ANTHROPIC_DEFAULT_*_MODEL` 变量时，`/model` 选择器会显示该模型的一行来替代该家族的内置行，包括任何 1M 上下文行。要在不向该变量添加后缀的情况下到达 1M 窗口，您的用户运行 `/model opus[1m]`，Claude Code 会将后缀应用于该变量命名的模型。`/model sonnet[1m]` 的工作方式相同。

996 1006

1013 1023

1014Claude Code 也可能无法识别固定模型支持的功能。您可以自己设置显示名称和描述，并为每个固定模型使用伴随环境变量声明功能。1024Claude Code 也可能无法识别固定模型支持的功能。您可以自己设置显示名称和描述，并为每个固定模型使用伴随环境变量声明功能。

1015 1025

1016这些变量在第三方提供商（如 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry）上生效。`_NAME` 和 `_DESCRIPTION` 变量在 `ANTHROPIC_BASE_URL` 指向 [LLM gateway](/docs/zh-CN/llm-gateway) 时也生效。当直接连接到 `api.anthropic.com` 时无效。1026这些变量在第三方提供商（如 Amazon Bedrock、Google Cloud's Agent Platform 和 Microsoft Foundry）上生效。`_NAME` 和 `_DESCRIPTION` 变量在 `ANTHROPIC_BASE_URL` 指向 [LLM 网关](/docs/zh-CN/llm-gateway) 时也生效。当直接连接到 `api.anthropic.com` 时无效。

1017 1027

1018| 环境变量 | 描述 |1028| 环境变量 | 描述 |

1019| - | - |1029| - | - |

1023 1033

1024相同的 `_NAME`、`_DESCRIPTION` 和 `_SUPPORTED_CAPABILITIES` 后缀可用于 `ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_DEFAULT_FABLE_MODEL` 和 `ANTHROPIC_CUSTOM_MODEL_OPTION`。1034相同的 `_NAME`、`_DESCRIPTION` 和 `_SUPPORTED_CAPABILITIES` 后缀可用于 `ANTHROPIC_DEFAULT_SONNET_MODEL`、`ANTHROPIC_DEFAULT_HAIKU_MODEL`、`ANTHROPIC_DEFAULT_FABLE_MODEL` 和 `ANTHROPIC_CUSTOM_MODEL_OPTION`。

1025 1035

1026Claude Code 通过将模型 ID 与已知模式匹配来启用[工作量级别](#adjust-effort-level)和[扩展思考](#extended-thinking)等功能。提供商特定的 ID（如 Amazon Bedrock ARN 或自定义部署名称）通常与这些模式不匹配，导致支持的功能被禁用。设置 `_SUPPORTED_CAPABILITIES` 以告诉 Claude Code 模型实际支持的功能：1036Claude Code 通过将模型 ID 与已知模式匹配来启用 [effort 级别](#adjust-effort-level)和[扩展思考](#extended-thinking)等功能。提供商特定的 ID（如 Amazon Bedrock ARN 或自定义部署名称）通常与这些模式不匹配，导致支持的功能被禁用。设置 `_SUPPORTED_CAPABILITIES` 以告诉 Claude Code 模型实际支持的功能：

1027 1037

1028| 功能值 | 启用 |1038| 功能值 | 启用 |

1029| - | - |1039| - | - |

1036 1046

1037设置 `_SUPPORTED_CAPABILITIES` 时，列出的功能对匹配的固定模型启用，未列出的功能被禁用。未设置变量时，Claude Code 回退到基于模型 ID 的内置检测。1047设置 `_SUPPORTED_CAPABILITIES` 时，Claude Code 会为匹配的固定模型启用列出的功能，并禁用未列出的功能。未设置该变量时，Claude Code 回退到基于模型 ID 的内置检测。

1038 1048

1039此示例将 Opus 固定到 Amazon Bedrock 自定义模型 ARN，设置友好名称，并声明其功能：1049此示例将 Opus 固定到 Amazon Bedrock 自定义模型 ARN，设置友好名称，并声明其功能：

1040 1050

1077 1087

1078当您通过 `--model`、`ANTHROPIC_MODEL` 环境变量或 `ANTHROPIC_DEFAULT_*_MODEL` 环境变量直接传递 Anthropic 模型 ID 时，覆盖也适用。在 Amazon Bedrock、Google Cloud's Agent Platform 和 [Mantle](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint) 上，没有 `modelOverrides` 条目的 Anthropic 模型 ID 解析为与该版本的 `/model` 选择器行相同的提供商特定 ID（当提供商支持该版本时）。Mantle 支持版本的子集。对于该子集之外的 Anthropic 模型 ID，Claude Code 将原始 ID 发送到 Mantle 而不进行映射，除非 `modelOverrides` 条目覆盖它。在 v2.1.200 之前，`--model` 和环境变量值直接到达提供商，不经过覆盖映射。1088当您通过 `--model`、`ANTHROPIC_MODEL` 环境变量或 `ANTHROPIC_DEFAULT_*_MODEL` 环境变量直接传递 Anthropic 模型 ID 时，覆盖也适用。在 Amazon Bedrock、Google Cloud's Agent Platform 和 [Mantle](/docs/zh-CN/amazon-bedrock#use-the-mantle-endpoint) 上，没有 `modelOverrides` 条目的 Anthropic 模型 ID 解析为与该版本的 `/model` 选择器行相同的提供商特定 ID（当提供商支持该版本时）。Mantle 支持版本的子集。对于该子集之外的 Anthropic 模型 ID，Claude Code 将原始 ID 发送到 Mantle 而不进行映射，除非 `modelOverrides` 条目覆盖它。在 v2.1.200 之前，`--model` 和环境变量值直接到达提供商，不经过覆盖映射。

1079 1089

1080`modelOverrides` 与 `availableModels` 一起工作。允许列表针对 Anthropic 模型 ID 进行评估，而不是覆盖值，因此 `availableModels` 中的条目（如 `"opus"`）即使在 Opus 版本映射到 ARN 时也会继续匹配。当在托管设置中设置 `enforceAvailableModels` 时，强制执行的默认值通过 `modelOverrides` 从[托管设置](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)解析。管理员的映射（如固定到推理配置文件 ARN 的版本）在强制执行的默认值中得到遵守。来自用户或项目设置的覆盖不会影响它。1090`modelOverrides` 与 `availableModels` 一起工作。允许列表针对 Anthropic 模型 ID 进行评估，而不是覆盖值，因此 `availableModels` 中的条目（如 `"opus"`）即使在 Opus 版本映射到 ARN 时也会继续匹配。当在托管设置中设置 `enforceAvailableModels` 时，强制执行的默认值仅通过来自[托管设置](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)的 `modelOverrides` 解析。管理员的映射（如固定到推理配置文件 ARN 的版本）在强制执行的默认值中得到遵守。来自用户或项目设置的覆盖不会影响它。

1081 1091

1082当 `availableModels` 在[托管设置](/docs/zh-CN/managed-settings)中设置时，仅来自托管设置的 `modelOverrides` 适用于通过 `--model` 或上述环境变量直接传递的 Anthropic 模型 ID。Claude Code 忽略用户或项目设置中针对这些 ID 的覆盖，并且永远不会通过任何设置源的 `modelOverrides` 解析托管列表排除的 ID。此托管源限制需要 Claude Code v2.1.200 或更高版本。有关如何处理被阻止的 ID，请参阅[限制模型选择](#restrict-model-selection)。1092当 `availableModels` 在[托管设置](/docs/zh-CN/managed-settings)中设置时，仅来自托管设置的 `modelOverrides` 适用于通过 `--model` 或上述环境变量直接传递的 Anthropic 模型 ID。Claude Code 忽略用户或项目设置中针对这些 ID 的覆盖，并且永远不会通过任何设置源的 `modelOverrides` 解析托管列表排除的 ID。此托管源限制需要 Claude Code v2.1.200 或更高版本。有关如何处理被阻止的 ID，请参阅[限制模型选择](#restrict-model-selection)。

1083 1093

1084<h3 id="prompt-caching-configuration">1094<h3 id="prompt-caching-configuration">

1085 Prompt caching 配置1095 提示缓存配置

1086</h3>1096</h3>

1087 1097

1088Claude Code 自动使用 [prompt caching](/docs/zh-CN/prompt-caching) 来优化性能并降低成本。您可以全局禁用 prompt caching 或针对特定模型层级禁用：1098Claude Code 自动使用[提示缓存](/docs/zh-CN/prompt-caching)来优化性能并降低成本。您可以全局禁用提示缓存或针对特定模型层级禁用：

1089 1099

1090| 环境变量 | 描述 |1100| 环境变量 | 描述 |

1091| - | - |1101| - | - |

1093| `DISABLE_PROMPT_CACHING_HAIKU` | 设置为 `1` 以仅禁用[默认 Haiku 模型](/docs/zh-CN/prompt-caching#disable-prompt-caching)的 prompt caching |1103| `DISABLE_PROMPT_CACHING_HAIKU` | 设置为 `1` 以禁用[默认 Haiku 模型](/docs/zh-CN/prompt-caching#disable-prompt-caching)的提示缓存 |

1094| `DISABLE_PROMPT_CACHING_SONNET` | 设置为 `1` 以仅禁用[默认 Sonnet 模型](/docs/zh-CN/prompt-caching#disable-prompt-caching)的 prompt caching |1104| `DISABLE_PROMPT_CACHING_SONNET` | 设置为 `1` 以禁用[默认 Sonnet 模型](/docs/zh-CN/prompt-caching#disable-prompt-caching)的提示缓存 |

1097 1107

1098要为主对话和 subagents 分别选择缓存 TTL，请参阅[自己选择 TTL](/docs/zh-CN/prompt-caching#choose-the-ttl-yourself)。有关什么会触发缓存未命中，请参阅 [Claude Code 如何使用 prompt caching](/docs/zh-CN/prompt-caching)。1108要为主对话和子代理分别选择缓存 TTL，请参阅[自己选择 TTL](/docs/zh-CN/prompt-caching#choose-the-ttl-yourself)。有关什么会触发缓存未命中，请参阅 [Claude Code 如何使用提示缓存](/docs/zh-CN/prompt-caching)。

1099 1109

1100<h2 id="version-history">1110<h2 id="version-history">

1101 版本历史1111 版本历史

monitoring-usage.md +4 −4

Details

551* **服务器管理的设置**：将它们添加到您组织的[服务器管理的设置](/docs/zh-CN/server-managed-settings)的 `env` 块中。Claude Code 在启动时会在[服务器管理的设置适用](/docs/zh-CN/model-config#surface-coverage)的任何地方获取这些设置，这包括您用户的机器和除 Claude Tag 频道会话外的云会话。Claude Tag 会话不会接收您的服务器管理的设置，因此此路由不会配置它们。551* **服务器管理的设置**：将它们添加到您组织的[服务器管理的设置](/docs/zh-CN/server-managed-settings)的 `env` 块中。Claude Code 在启动时会在[服务器管理的设置适用](/docs/zh-CN/model-config#surface-coverage)的任何地方获取这些设置，这包括您用户的机器和除 Claude Tag 频道会话外的云会话。Claude Tag 会话不会接收您的服务器管理的设置，因此此路由不会配置它们。

552* **环境的变量**：将它们添加到云环境的[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)中，以仅配置在该环境中运行的会话。这是到达 Claude Tag 会话的路由。552* **环境的变量**：将它们添加到云环境的[环境变量](/docs/zh-CN/cloud-environments#set-environment-variables)中，以仅配置在该环境中运行的会话。这是到达 Claude Tag 会话的路由。

553 553

554任何使用环境的人都可以读取其变量，因此不要在其中放置凭据，例如 `OTEL_EXPORTER_OTLP_HEADERS` 中的收集器令牌。环境上的[网络密钥](/docs/zh-CN/cloud-environments#add-api-credentials)也无济于事，因为 Claude Code 自己的遥测导出是[从不获得该密钥的请求](/docs/zh-CN/cloud-environments#requests-that-never-get-the-credential)之一。如果您的收集器需要凭据，请改为通过服务器管理的设置配置整个导出，因为当您在那里设置凭据时，[Claude Code 会删除在托管设置外设置的端点变量](#how-managed-settings-lock-the-otlp-destination)。554任何使用环境的人都可以读取其变量，因此不要在其中放置凭据，例如 `OTEL_EXPORTER_OTLP_HEADERS` 中的收集器令牌。环境上的[网络密钥](/docs/zh-CN/cloud-environments#add-network-secrets)也无济于事，因为 Claude Code 自己的遥测导出是[从不获得该密钥的请求](/docs/zh-CN/cloud-environments#requests-that-never-get-the-credential)之一。如果您的收集器需要凭据，请改为通过服务器管理的设置配置整个导出，因为当您在那里设置凭据时，[Claude Code 会删除在托管设置外设置的端点变量](#how-managed-settings-lock-the-otlp-destination)。

555 555

556在为云会话配置遥测时，请记住这些约束：556在为云会话配置遥测时，请记住这些约束：

557 557

1314* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述1314* `event.sequence`：用于排序事件的每进程计数器，在[事件关联属性](#event-correlation-attributes)下描述

1315* `plugin_id`：`<name>@<marketplace>` 形式的插件标识符1315* `plugin_id`：`<name>@<marketplace>` 形式的插件标识符

1316* `hook_event`：发出指标的钩子事件类型1316* `hook_event`：发出指标的钩子事件类型

1317* 最多 20 个插件发出的指标键。名称匹配 `^[a-z][a-z0-9_]{0,39}$`。值是布尔值或数字。1317* 最多 20 个由插件发出的指标键。名称匹配 `^[a-z][a-z0-9_]{0,39}$`。值为 Boolean 或数字。

1318 1318

1319<h4 id="compaction-event">1319<h4 id="compaction-event">

1320 压缩事件1320 压缩事件

1382* `appearance_id`：链接为一个调查实例发出的事件的唯一 ID1382* `appearance_id`：链接为一个调查实例发出的事件的唯一 ID

1383* `survey_type`：哪个调查产生了事件。`"session"` 是"Claude 做得怎么样？"评分提示1383* `survey_type`：哪个调查产生了事件。`"session"` 是"Claude 做得怎么样？"评分提示

1384* `response`：用户在 `responded` 事件上的选择1384* `response`：用户在 `responded` 事件上的选择

1385* `enabled_via_override`：当设置了 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/zh-CN/env-vars) 时为 `true`。作为布尔值而不是字符串发出。存在于 `session` 调查事件上。在此属性上过滤以确认覆盖在整个舰队中应用1385* `enabled_via_override`：设置了 [`CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL`](/docs/zh-CN/env-vars) 时为 `true`。以布尔值而非字符串形式发出。存在于 `session` 调查事件中。可按此属性筛选，以确认覆盖已在整个设备群中生效

1386 1386

1387<h4 id="retention-sweep-event">1387<h4 id="retention-sweep-event">

1388 保留扫描事件1388 保留扫描事件

1473 例如，具有 `apiKeyHelper`、两个 `env` 变量和拒绝规则的管理设置导出为 `{"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}`.1473 例如，具有 `apiKeyHelper`、两个 `env` 变量和拒绝规则的管理设置导出为 `{"apiKeyHelper":"[REDACTED]","env":{"HTTPS_PROXY":"[REDACTED]","CLAUDE_CODE_ENABLE_TELEMETRY":"[REDACTED]"},"permissions":{"deny":["Read([REDACTED])"]}}`.

1474 1474

1475 Claude Code 在 8 KB UTF-8 处切割值，切割值不是有效的 JSON1475 Claude Code 在 8 KB UTF-8 处切割值，切割值不是有效的 JSON

1476* `managed_settings.settings_truncated`（当 `managed_settings.settings` 存在时）：当 Claude Code 在 8 KB 处切割 `managed_settings.settings` 时为 `true`，否则为 `false`。作为布尔值而不是字符串发出1476* `managed_settings.settings_truncated`（当存在 `managed_settings.settings` 时）：当 Claude Code 在 8 KB 处截断了 `managed_settings.settings` 时为 `true`，否则为 `false`。以布尔值而非字符串形式发出

1477 1477

1478<h2 id="interpret-metrics-and-events-data">1478<h2 id="interpret-metrics-and-events-data">

1479 解释指标和事件数据1479 解释指标和事件数据

network-config.md +1 −1

Details

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

210| 首字节截止时间 | Claude Code 发送请求后没有响应头到达 | 直接 Anthropic API 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws)，包括通过 HTTPS 代理，但不包括当 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 通过 [gateway](/docs/zh-CN/gateways) 路由时。在 Amazon Bedrock 上可选，使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`；不在 Google Cloud 的 Agent Platform 或 Microsoft Foundry 上运行 | 直接 Anthropic API 上为 180 秒，其他地方为 300 秒，加上每 32KB 请求体一秒 |210| 首字节截止时间 | Claude Code 发送请求后没有响应头到达 | 直接 Anthropic API 和 [Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws)，包括通过 HTTPS 代理，但不包括当 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 通过 [gateway](/docs/zh-CN/gateways) 路由时。在 Amazon Bedrock 上可选，使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`；不在 Google Cloud 的 Agent Platform 或 Microsoft Foundry 上运行 | 直接 Anthropic API 上为 180 秒，其他地方为 300 秒，加上每 32KB 请求体一秒 |

211| 事件级监视器 | 没有响应事件解析。在字节级监视器运行在 Amazon Bedrock 以外的连接上的情况下，到达的字节（包括保活 ping）也会重置此监视器，最多约五分钟内没有解析的事件 | 每个提供商 | 300 秒 |211| 事件级监视器 | 没有响应事件解析。在字节级监视器运行在 Amazon Bedrock 以外的连接上的情况下，到达的字节（包括保活 ping）也会重置此监视器，最多约五分钟内没有解析的事件 | 每个提供商 | 300 秒 |

212| 字节级监视器 | 线路上没有字节到达，包括 SSE 保活 ping | 直接 Anthropic API、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和 [gateway](/docs/zh-CN/gateways) 连接，包括自定义 `ANTHROPIC_BASE_URL`。在 Amazon Bedrock `vnd.amazon.eventstream` 响应上可选，使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`；不在 Google Cloud 的 Agent Platform 或 Microsoft Foundry 上运行 | 直接 Anthropic API 上为 180 秒，其他地方为 300 秒 |212| 字节级监视器 | 线路上没有字节到达，包括 SSE 保活 ping | 直接 Anthropic API、[Claude Platform on AWS](/docs/zh-CN/claude-platform-on-aws) 和 [网关](/docs/zh-CN/gateways) 连接，包括自定义 `ANTHROPIC_BASE_URL`。在 Amazon Bedrock `vnd.amazon.eventstream` 响应上可选，使用 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`；不在 Google Cloud 的 Agent Platform 或 Microsoft Foundry 上运行 | 直接 Anthropic API 上为 180 秒。通过自定义 `ANTHROPIC_BASE_URL` 时，如果 Claude Code 已[获取功能标志](/docs/zh-CN/env-vars#features-that-need-feature-flag-fetching)则为 180 秒，未获取则为 300 秒。其他地方为 300 秒 |

214 214

215如果设置 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`，字节级监视器会在 Bedrock 上替换主体空闲超时，而不是与其并行运行。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 随后也会控制 Bedrock 流在 Claude Code 将连接视为死连接之前可以保持沉默多长时间，在下面列出的限制范围内。到达的字节仍然不会在 Bedrock 上重置事件级监视器。启用调试日志后，每个 Bedrock 流随后会记录一条以 `wire-heartbeat: _chunkTimes absent` 开头的调试消息。215如果设置 `CLAUDE_ENABLE_BYTE_WATCHDOG_BEDROCK=1`，字节级监视器会在 Bedrock 上替换主体空闲超时，而不是与其并行运行。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` 随后也会控制 Bedrock 流在 Claude Code 将连接视为死连接之前可以保持沉默多长时间，在下面列出的限制范围内。到达的字节仍然不会在 Bedrock 上重置事件级监视器。启用调试日志后，每个 Bedrock 流随后会记录一条以 `wire-heartbeat: _chunkTimes absent` 开头的调试消息。

output-styles.md +3 −3

Details

183| :- | :- | :- |183| :- | :- | :- |

184| `name` | 否 | 输出样式的名称，在 `/config` 选择器中显示。默认值：文件名 |184| `name` | 否 | 输出样式的名称，在 `/config` 选择器中显示。默认值：文件名 |

185| `description` | 否 | 输出样式的描述，在 `/config` 选择器中显示 |185| `description` | 否 | 输出样式的描述，在 `/config` 选择器中显示 |

186| `keep-coding-instructions` | 否 | 设置为 `true` 以在你的样式旁边保留 Claude Code 的内置软件工程说明。默认值：`false` |186| `keep-coding-instructions` | 否 | 设置为 `true` 以在您的样式之外保留 Claude Code 的内置软件工程说明部分（只有完整的系统提示词包含该部分）。请参阅[输出样式的工作原理](#how-output-styles-work)。默认值：`false` |

187| `force-for-plugin` | 否 | 仅限 Plugin 输出样式。设置为 `true` 以在启用 plugin 时自动应用此样式，无需要求用户选择它。覆盖用户的 `outputStyle` 设置。如果多个启用的 plugin 设置了此项，Claude Code 使用第一个加载的。默认值：`false` |187| `force-for-plugin` | 否 | 仅限 Plugin 输出样式。设置为 `true` 以在启用 plugin 时自动应用此样式，无需要求用户选择它。覆盖用户的 `outputStyle` 设置。如果多个启用的 plugin 设置了此项，Claude Code 使用第一个加载的。默认值：`false` |

188 188

189<span id="comparisons-to-related-features" />189<span id="comparisons-to-related-features" />

214输出样式改变 Claude Code 给予 Claude 的指令。214输出样式改变 Claude Code 给予 Claude 的指令。

215 215

216* Claude Code 在每个请求中发送活跃样式的指令。216* Claude Code 在每个请求中发送活跃样式的指令。

217* 自定义输出样式会省略 Claude Code 的内置软件工程指令，例如如何限定更改范围、编写注释和验证工作，除非 `keep-coding-instructions` 设置为 `true`。217* 在完整系统提示词中，自定义输出样式会省略 Claude Code 的内置软件工程指令部分，例如如何限定更改范围、编写注释和验证工作，除非 `keep-coding-instructions` 设置为 `true`。较短的系统提示词不包含该部分，因此该字段在那里不起作用。若要依赖该字段，请将 [`CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT`](/docs/zh-CN/env-vars#variables) 设置为 `0`，这样在任何模型上都会选用完整提示词。

218 218

219输出样式适用于主对话和[分支](/docs/zh-CN/sub-agents#fork-the-current-conversation)，分支继承父级的完整对话和系统提示。其他[子代理运行自己的系统提示](/docs/zh-CN/sub-agents#what-loads-at-startup)，因此样式不会改变它们的响应方式。219输出样式适用于主对话和[分支](/docs/zh-CN/sub-agents#fork-the-current-conversation)，分支继承父级的完整对话和系统提示词。其他[子代理运行自己的系统提示词](/docs/zh-CN/sub-agents#what-loads-at-startup)，因此样式不会改变它们的回复方式。

220 220

221令牌使用情况取决于样式。样式的指令会增加输入令牌，尽管提示缓存在会话中的第一个请求之后会降低这个成本。221令牌使用情况取决于样式。样式的指令会增加输入令牌，尽管提示缓存在会话中的第一个请求之后会降低这个成本。

222 222

overview.md +1 −1

Details

46 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd46 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

47 ```47 ```

48 48

49 安装程序完成后，打开一个新的终端窗口并运行 `claude --version`。正常的安装会打印一个版本号。如果您的 shell 显示找不到 `claude` 或无法识别，说明安装目录还不在您的 PATH 中：请参阅[修复您的 PATH](/docs/zh-CN/troubleshoot-install#command-not-found-claude-after-installation)。49 安装命令在下载 Claude Code 期间不会显示进度。安装程序完成后，打开一个新的终端窗口并运行 `claude --version`。正常的安装会打印一个版本号。如果您的 shell 显示找不到 `claude` 或无法识别，说明安装目录还不在您的 PATH 中：请参阅[修复您的 PATH](/docs/zh-CN/troubleshoot-install#command-not-found-claude-after-installation)。

50 50

51 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。51 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。

52 52

permissions.md +1 −1

Details

700权限和[沙箱](/docs/zh-CN/sandboxing)是互补的安全层：700权限和[沙箱](/docs/zh-CN/sandboxing)是互补的安全层：

701 701

702* **权限**控制 Claude Code 可以使用哪些工具以及它可以访问哪些文件或域。它们适用于 Bash、Read、Edit、WebFetch、MCP 和其他所有工具，除了 deny 或 ask 规则无法阻止 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior)，而任何其他工具仍然存在。702* **权限**控制 Claude Code 可以使用哪些工具以及它可以访问哪些文件或域。它们适用于 Bash、Read、Edit、WebFetch、MCP 和其他所有工具，除了 deny 或 ask 规则无法阻止 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior)，而任何其他工具仍然存在。

703* **沙箱**提供 OS 级别的强制执行，限制 shell 命令的文件系统和网络访问。它仅适用于 Bash、PowerShell 和 [Monitor](/docs/zh-CN/tools-reference#monitor-tool) 命令及其子进程。703* **沙箱隔离**提供 OS 级别的强制执行，限制 shell 命令的文件系统和网络访问。它适用于 Bash、PowerShell 和 [Monitor](/docs/zh-CN/tools-reference#monitor-tool) 工具命令及其子进程。

704 704

705使用两者进行深度防御，因为即使提示注入绕过 Claude 的决策制定，沙箱限制仍然适用。来自沙箱设置和权限规则的路径和域被[合并到最终沙箱配置](/docs/zh-CN/sandboxing#permission-rules)中。705使用两者进行深度防御，因为即使提示注入绕过 Claude 的决策制定，沙箱限制仍然适用。来自沙箱设置和权限规则的路径和域被[合并到最终沙箱配置](/docs/zh-CN/sandboxing#permission-rules)中。

706 706

plugin-evals.md +26 −5

Details

335* **替换**：使用 `{{input.<field>}}` 从调用的输入插入字段，使用 `{{file:fixtures/{input.<field>}.json}}` 插入 mock 旁边的 fixture 文件的内容。335* **替换**：使用 `{{input.<field>}}` 从调用的输入插入字段，使用 `{{file:fixtures/{input.<field>}.json}}` 插入 mock 旁边的 fixture 文件的内容。

336* **`expect:`**：`expect:` 块保护输入。如果调用违反它，运行以分数 0 中止并记录原因，以便用例可以断言你的插件要求服务器执行的操作。336* **`expect:`**：`expect:` 块保护输入。如果调用违反它，运行以分数 0 中止并记录原因，以便用例可以断言你的插件要求服务器执行的操作。

337* **`error: true`**：设置 `error: true` 以将正文作为工具错误返回。337* **`error: true`**：设置 `error: true` 以将正文作为工具错误返回。

338* **`type: agent`**：设置 `type: agent`，让评判模型根据正文中的指令以服务器身份回答。338* **`type: agent`**：设置 `type: agent`，让评判模型根据正文中的指令以服务器身份回答。对 Agent mock 的调用共享一个[每次运行的预算](#mock-call-budget-exceeded)，其值为用例 `max_turns` 的四倍，超出预算的调用会以分数 0 中止运行。

339 339

340[mock 文件参考](#mock-files)列出了每个键和 `_server.md` 和 `_tools.json` 文件。340[mock 文件参考](#mock-files)列出了每个键和 `_server.md` 和 `_tools.json` 文件。

341 341

370| :- | :- |370| :- | :- |

373| 已安装的插件（按名称），`name` 或 `name@marketplace` | 已安装副本的 eval 目录中的用例，加载已安装的副本。结果写入当前目录下的 `./evals/results/`，或使用 `--eval-dir` 时写入 `./<dir>/results/` |373| 已安装的插件（按名称），`name` 或 `name@marketplace` | 该插件及其 eval 目录中的用例，[就地读取或从已安装的副本读取](/docs/zh-CN/plugins/loading#in-place-and-copied-plugins)。结果写入当前目录下的 `./evals/results/`，或使用 `--eval-dir` 时写入 `./<dir>/results/` |

375| 省略 | 当前目录作为路径 |375| 省略 | 当前目录作为路径 |

376 376

505| `cases[].arms.with[].aborted` | 当[mock](#mock-mcp-servers) 的 `expect:` 或 `abort_when` 停止运行时出现，带有 `server`、`tool` 和 `reason`。运行分数为 0，`error` 保持 `null` |505| `cases[].arms.with[].aborted` | 当 [mock](#mock-mcp-servers) 通过 `expect:`、`abort_when` 或 [agent-mock 调用预算](#mock-call-budget-exceeded)停止运行时出现，带有 `server`、`tool` 和 `reason`。运行分数为 0，`error` 保持 `null` |

508 508

654| 键 | 默认 | 目的 |654| 键 | 默认 | 目的 |

655| :- | :- | :- |655| :- | :- | :- |

657| `expect` | 未设置 | 从点分输入路径到类型名称（例如 `string`、`number`、`boolean`、`array` 或 `object`）、`/regex/`、文字或允许的文字列表的映射。违反它的调用以分数 0 中止运行，并报告为 `aborted`，带有服务器、工具和原因 |657| `expect` | 未设置 | 从点分输入路径到类型名称（例如 `string`、`number`、`boolean`、`array` 或 `object`）、[`/regex/`](#expect-patterns)、字面值或允许的字面值列表的映射。违反它的调用会以分数 0 中止运行，并报告为 `aborted`，附带服务器、工具和原因 |

659| `abort_when` | 未设置 | `agent` 仅。散文列出代理可能中止运行的唯一条件 |659| `abort_when` | 未设置 | `agent` 仅。散文列出代理可能中止运行的唯一条件 |

660 660

661两个可选文件位于服务器目录中的工具文件旁边：661两个可选文件位于服务器目录中的工具文件旁边：

662 662

663* **`_server.md`**：单个 `type: agent` mock，在其 `tools:` frontmatter 键中列出的几个工具回答。相同工具的 `<tool>.md` 优先。在单个 `<tool>.md` 上放置 `expect:` 保护，不在这里663* **`_server.md`**：单个 `type: agent` mock，回答其 `tools:` frontmatter 键中列出的多个工具。同一工具的 `<tool>.md` 优先于它。在这里放置 `expect:` 保护会导致加载错误，除非 `tools:` 只列出一个工具，因此请将保护放在单独的 `<tool>.md` 上

664* **`_tools.json`**：来自真实服务器的保存 `tools/list` 响应，所以 mocked 工具携带其真实描述和输入架构，而不是宽松的占位符664* **`_tools.json`**：来自真实服务器的保存 `tools/list` 响应，所以 mocked 工具携带其真实描述和输入架构，而不是宽松的占位符

665 665

666用例自己的 `mocks/` 目录使用相同的布局并逐文件覆盖套件的 mocks。666用例自己的 `mocks/` 目录使用相同的布局并逐文件覆盖套件的 mocks。

667 667

668<h4 id="expect-patterns">

669 expect 中的正则表达式模式

670</h4>

671

672`expect:` 中的 `/regex/` 值使用一种小型方言，Claude Code 会在加载套件时对其进行检查：

673

674* 字面字符、`.`、转义序列（如 `\d`）以及字符类（如 `[a-z]`）

675* 量词 `*`、`+`、`?` 以及 `{m,n}` 形式，每个都作用于单个字符、转义序列或字符类

676* 开头可选的 `^` 和结尾可选的 `$`

677* 仅限标志 `i` 和 `s`

678

679超出该方言的模式，例如包含分组、交替、反向引用、环视或其他标志的模式，会导致用例无法加载：该用例得分为 0，其错误信息会指明该模式。要允许多个确切值，请编写字面值列表，而不是使用交替。

680

681每个模式只检查不超过某个最大长度的值，更长的值会被视为违规。量词会降低该长度，而开头的 `^` 会提高该长度，因此请用 `^` 锚定模式并尽量少用量词。

682

668<h2 id="troubleshooting">683<h2 id="troubleshooting">

669 故障排除684 故障排除

670</h2>685</h2>

773 788

774如果你的账户在套件运行时达到了计划的使用限制或 API 速率限制，每个后续运行都会以该错误结束，根据它生成的内容进行评分，通常评分为 0。套件仍然完成，不会标记为 `partial`，所以结果看起来像是一个回归。在信任评分之前，检查 `NOTES` 列或 JSON 中的 `cases[].arms.with[].error` 中的限制消息，然后在限制重置后重新运行，如果你需要保持在限制内，使用 `--runs 1` 或 `--case` 过滤器。789如果你的账户在套件运行时达到了计划的使用限制或 API 速率限制，每个后续运行都会以该错误结束，根据它生成的内容进行评分，通常评分为 0。套件仍然完成，不会标记为 `partial`，所以结果看起来像是一个回归。在信任评分之前，检查 `NOTES` 列或 JSON 中的 `cases[].arms.with[].error` 中的限制消息，然后在限制重置后重新运行，如果你需要保持在限制内，使用 `--runs 1` 或 `--case` 过滤器。

775 790

791<h3 id="mock-call-budget-exceeded">

792 "mock call budget exceeded"

793</h3>

794

795一次运行中的每个 `type: agent` [模拟](#mock-mcp-servers)都共用一个调用预算，该预算为案例 `max_turns` 的四倍，在默认值 10 下即为 40 次调用。由 `.replay/` 录制内容应答的调用同样计入，案例的 `mock budget` 进度行会打印该预算。超出预算的调用会中止运行，评分为 0 并给出此原因，因此对于会大量调用 Agent 模拟的 skill，请在案例中提高 `max_turns`。

796

776<h3 id="runs-time-out-or-hit-the-turn-cap">797<h3 id="runs-time-out-or-hit-the-turn-cap">

777 运行超时或达到轮次上限798 运行超时或达到轮次上限

778</h3>799</h3>

plugins/cli-reference.md +39 −17

Details

129 129

130使用错误（例如无效的 `--scope`）不会打印结果行，而是以 `1` 退出，并在 stderr 上给出原因。130使用错误（例如无效的 `--scope`）不会打印结果行，而是以 `1` 退出，并在 stderr 上给出原因。

131 131

132<h4 id="json-result-for-marketplace-commands">

133 市场命令的 JSON 结果

134</h4>

135

136在 `plugin marketplace add`、`plugin marketplace remove` 和 `plugin marketplace update` 上，`--json` 会在 stdout 的最后一行打印一个 JSON 对象，包含 `command`、`outcome` 和 `message` 字段。以下是 `claude plugin marketplace remove your-marketplace --json` 的结果：

137

138```json theme={null}

139{"command":"marketplace-remove","outcome":"ok","marketplace":"your-marketplace","message":"Successfully removed marketplace: your-marketplace"}

140```

141

142`command` 的值为 `marketplace-add`、`marketplace-remove` 或 `marketplace-update`。以下字段仅在适用时出现：

143

144* `marketplace`：命令所作用的市场名称

145* `failureCode`：表示命令失败原因的代码，例如 `invalid_source`

146

147当参数为[保留名称](/docs/zh-CN/plugins/marketplace-reference#reserved-names) `anthropic-plugin-directory` 时，`plugin marketplace add` 和 `plugin marketplace remove` 可能不打印结果行，因此对于该名称请检查退出码。

148

132<h4 id="accept-a-displayed-install-command">149<h4 id="accept-a-displayed-install-command">

133 接受显示的安装命令150 接受显示的安装命令

134</h4>151</h4>

672* `target`：Claude Code 验证的解析后路径689* `target`：Claude Code 验证的解析后路径

673* `manifest`：清单自身的结果，对于没有清单的运行为 `null`690* `manifest`：清单自身的结果，对于没有清单的运行为 `null`

674* `contents`：每个文件的结果，各自指明其 `file`，并携带 `errors`、`warnings` 和 `notes` 数组691* `contents`：每个文件的结果，各自指明其 `file`，并携带 `errors`、`warnings` 和 `notes` 数组

692 * `gatingHooks`：每个可以拒绝操作的 [mod](/docs/zh-CN/plugins/mods/overview) hook（例如 `tool.call` hook）是否具有 [`.catch` 处理程序](/docs/zh-CN/plugins/mods/events#handle-a-hook-that-fails)。每一项给出 `module`、`pattern`、`hook` 和 `hasCatch`。需要 Claude Code v2.1.290 或更高版本

675 693

676以 `2` 退出时，命令不向 stdout 写入任何内容。错误消息输出到 stderr。694以 `2` 退出时，命令不向 stdout 写入任何内容。错误消息输出到 stderr。

677 695

679 claude plugin marketplace 命令697 claude plugin marketplace 命令

680</h2>698</h2>

681 699

682从你的 shell 运行 `claude plugin marketplace <subcommand>` 来添加、列出、刷新和移除你安装插件的市场。700从您的 shell 运行 `claude plugin marketplace <subcommand>` 来添加、列出、刷新和移除您安装插件的市场。

683 701

684* **退出代码**：这些子命令遵循插件命令的[退出代码约定](#claude-plugin-commands)702* **退出码**：这些子命令遵循插件命令的[退出码约定](#claude-plugin-commands)

685* **作用域**：它们的 `--scope` 标志没有 `-s` 短形式703* **作用域**：它们的 `--scope` 标志没有 `-s` 短形式

686 704

687关于市场是什么以及 Claude Code 如何缓存它，请参阅[插件加载参考](/docs/zh-CN/plugins/loading)。705关于市场是什么以及 Claude Code 如何缓存它，请参阅[插件加载参考](/docs/zh-CN/plugins/loading)。

692 710

693从 GitHub 仓库、git URL、托管的 `marketplace.json` 或本地路径添加市场，并在设置文件中声明它。711从 GitHub 仓库、git URL、托管的 `marketplace.json` 或本地路径添加市场，并在设置文件中声明它。

694 712

695添加后，Claude Code 会安装你已安装的插件缺失的任何[依赖项](/docs/zh-CN/plugins/dependencies)。713添加后，Claude Code 会安装您已安装的插件缺失的任何[依赖项](/docs/zh-CN/plugins/dependencies)。

696 714

697```bash theme={null}715```bash theme={null}

698claude plugin marketplace add <source> [options]716claude plugin marketplace add <source> [options]

705| `--claudeai` | 将参数读取为[托管在 claude.ai 上的市场](/docs/zh-CN/plugins/install#add-from-claude-ai)的名称，而不是源。需要 Claude Code v2.1.273 或更高版本 |723| `--claudeai` | 将参数读取为[托管在 claude.ai 上的市场](/docs/zh-CN/plugins/install#add-from-claude-ai)的名称，而不是源。需要 Claude Code v2.1.273 或更高版本 |

724| `--json` | 以 [JSON 结果格式](#plugin-json-result)在 stdout 的最后一行以一个 JSON 对象打印命令是否成功及其消息。与 `--claudeai` 一起使用时无效。需要 Claude Code v2.1.287 或更高版本 |

706 725

707`<source>` 采用下表中的任何形式，其形式决定了源类型以及 Claude Code 如何获取市场。关于生成的源对象，请参阅[市场参考](/docs/zh-CN/plugins/marketplace-reference)。726`<source>` 采用下表中的任何形式，其形式决定了源类型以及 Claude Code 如何获取市场。关于生成的源对象，请参阅[市场参考](/docs/zh-CN/plugins/marketplace-reference)。

708 727

709| 你输入的 | 源类型 | Claude Code 如何获取它 |728| 您输入的 | 源类型 | Claude Code 如何获取它 |

710| :- | :- | :- |729| :- | :- | :- |

712| `user@host:path[.git][#ref]` | `git` | 通过 SSH 克隆 |731| `user@host:path[.git][#ref]` | `git` | 通过 SSH 克隆 |

728 747

729Claude Code 打印 `Successfully added marketplace: your-marketplace (declared in project settings)`，使用市场自己清单中的 `name`。重复添加或无效源会改为打印以下结果之一：748Claude Code 打印 `Successfully added marketplace: your-marketplace (declared in project settings)`，使用市场自己清单中的 `name`。重复添加或无效源会改为打印以下结果之一：

730 749

731* **市场已在磁盘上**：输出为 `Marketplace 'your-marketplace' already on disk — declared in project settings`，退出代码为 `0`750* **市场已在磁盘上**：输出为 `Marketplace 'your-marketplace' already on disk — declared in project settings`，退出码为 `0`

732* **无法识别的源**：输出为 `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`，退出代码为 `1`751* **无法识别的源**：输出为 `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`，退出码为 `1`

733* **裸主机，如 `gitlab.example.com/team/plugins`**：添加失败，作为无效的 `owner/repo` 简写，消息告诉你添加 `https://` 或使用本地路径752* **裸主机，如 `gitlab.example.com/team/plugins`**：添加失败，作为无效的 `owner/repo` 简写，消息告诉您添加 `https://` 或使用本地路径

734 753

735通过 `claude plugin marketplace list` 的 `From claude.ai:` 部分中打印的名称添加[托管在 claude.ai 上的市场](/docs/zh-CN/plugins/install#add-from-claude-ai)：754通过 `claude plugin marketplace list` 的 `From claude.ai:` 部分中打印的名称添加[托管在 claude.ai 上的市场](/docs/zh-CN/plugins/install#add-from-claude-ai)：

736 755

738claude plugin marketplace add --claudeai claudeai-organization-library757claude plugin marketplace add --claudeai claudeai-organization-library

739```758```

740 759

741使用 `--claudeai` 时，命令拒绝 `--scope` 和 `--sparse`。市场为你的账户托管，未在设置文件中声明，因此你无法通过项目的 `.claude/settings.json` 共享它。760使用 `--claudeai` 时，命令拒绝 `--scope` 和 `--sparse`。市场为您的账户托管，未在设置文件中声明，因此您无法通过项目的 `.claude/settings.json` 共享它。

742 761

743<h3 id="plugin-marketplace-list">762<h3 id="plugin-marketplace-list">

744 plugin marketplace list763 plugin marketplace list

745</h3>764</h3>

746 765

747列出你添加的每个市场及其源。766列出您添加的每个市场及其源。

748 767

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

750claude plugin marketplace list [options]769claude plugin marketplace list [options]

770 789

771添加的 [claude.ai 市场](/docs/zh-CN/plugins/install#add-from-claude-ai)没有本地克隆，因此其条目在 `installLocation` 的位置携带其 claude.ai 标识符 `marketplaceId` 和 `organizationUuid`。它也在记录时携带 `scope` 和 `status`。790添加的 [claude.ai 市场](/docs/zh-CN/plugins/install#add-from-claude-ai)没有本地克隆，因此其条目在 `installLocation` 的位置携带其 claude.ai 标识符 `marketplaceId` 和 `organizationUuid`。它也在记录时携带 `scope` 和 `status`。

772 791

773如果你的终端会话[从你的 claude.ai 账户同步插件](/docs/zh-CN/plugins/loading#synced-plugins)，文本列表以 `From claude.ai:` 部分结尾。该部分命名 claude.ai 为你的账户列出的市场，你还没有添加的，包括基于 git 的和托管的。它需要 Claude Code v2.1.273 或更高版本。792如果您的终端会话[从您的 claude.ai 账户同步插件](/docs/zh-CN/plugins/loading#synced-plugins)，文本列表以 `From claude.ai:` 部分结尾。该部分列出 claude.ai 为您的账户列出但您尚未添加的市场，包括基于 git 的和托管的。它需要 Claude Code v2.1.273 或更高版本。

774 793

775要从该部分添加市场，请参阅[从 claude.ai 添加市场](/docs/zh-CN/plugins/install#add-from-claude-ai)。794要从该部分添加市场，请参阅[从 claude.ai 添加市场](/docs/zh-CN/plugins/install#add-from-claude-ai)。

776 795

780 plugin marketplace remove799 plugin marketplace remove

781</h3>800</h3>

782 801

783从你的设置中移除市场的声明。`rm` 是 `remove` 的别名。802从您的设置中移除市场的声明。`rm` 是 `remove` 的别名。

784 803

785<Warning>804<Warning>

786 当你从最后一个声明市场的作用域中移除市场时，Claude Code 也会删除其缓存并卸载你从中安装的每个插件。它也会删除它们保存的[选项和密钥](/docs/zh-CN/plugins/manifest-reference#user-configuration)和[数据](/docs/zh-CN/plugins/components#path-variables-and-persistent-data)（如果可以的话）。805 当您从最后一个声明市场的作用域中移除市场时，Claude Code 也会删除其缓存并卸载您从中安装的每个插件。它也会删除它们保存的[选项和密钥](/docs/zh-CN/plugins/manifest-reference#user-configuration)和[数据](/docs/zh-CN/plugins/components#path-variables-and-persistent-data)（如果可以的话）。

787 806

788 要在不丢失其插件的情况下刷新市场，请改为运行 `plugin marketplace update`。807 要在不丢失其插件的情况下刷新市场，请改为运行 `plugin marketplace update`。

789</Warning>808</Warning>

792claude plugin marketplace remove <name> [options]811claude plugin marketplace remove <name> [options]

793```812```

794 813

795`<name>` 是 `plugin marketplace list` 显示的市场名称，而不是你传递给 `add` 的源。814`<name>` 是 `plugin marketplace list` 显示的市场名称，而不是您传递给 `add` 的源。

796 815

797| 标志 | 描述 |816| 标志 | 描述 |

798| :- | :- |817| :- | :- |

819| `--json` | 以 [JSON 结果格式](#plugin-json-result)在 stdout 的最后一行以一个 JSON 对象打印命令是否成功及其消息。需要 Claude Code v2.1.287 或更高版本 |

800 820

801从每个作用域中移除市场：821从每个作用域中移除市场：

802 822

806 826

807Claude Code 打印 `Successfully removed marketplace: your-marketplace`。当命令卸载插件时，输出在诸如 `Also uninstalled 2 plugins from this marketplace:` 的行下列出它们。要再次使用其中一个，请添加市场并重新安装插件。827Claude Code 打印 `Successfully removed marketplace: your-marketplace`。当命令卸载插件时，输出在诸如 `Also uninstalled 2 plugins from this marketplace:` 的行下列出它们。要再次使用其中一个，请添加市场并重新安装插件。

808 828

809如果你限定作用域到不声明市场的设置文件，命令失败，显示 `Marketplace 'your-marketplace' is not declared in project settings. Omit --scope to remove it from all scopes.`829如果您限定作用域到不声明市场的设置文件，命令失败，显示 `Marketplace 'your-marketplace' is not declared in project settings. Omit --scope to remove it from all scopes.`

810 830

811<h3 id="plugin-marketplace-update">831<h3 id="plugin-marketplace-update">

812 plugin marketplace update832 plugin marketplace update

815从其源刷新一个市场或每个市场，以获取新插件和版本。使用分支或标签 `ref` 添加的市场更新到该 ref 的最新提交，而不是仓库的默认分支。835从其源刷新一个市场或每个市场，以获取新插件和版本。使用分支或标签 `ref` 添加的市场更新到该 ref 的最新提交，而不是仓库的默认分支。

816 836

817```bash theme={null}837```bash theme={null}

818claude plugin marketplace update [name]838claude plugin marketplace update [name] [options]

819```839```

820 840

821该命令除了 `--help` 外不接受任何标志。841| 标志 | 描述 |

842| :- | :- |

843| `--json` | 以 [JSON 结果格式](#plugin-json-result)在 stdout 的最后一行以一个 JSON 对象打印命令是否成功及其消息。未提供名称时，命令拒绝 `--json` 并以 `1` 退出。需要 Claude Code v2.1.287 或更高版本 |

822 844

823刷新一个市场：845刷新一个市场：

824 846

826claude plugin marketplace update your-marketplace848claude plugin marketplace update your-marketplace

827```849```

828 850

829Claude Code 打印 `Successfully updated marketplace: your-marketplace`。当你省略名称时，它打印计数，如 `Successfully updated 2 marketplaces`。没有添加市场时，它打印 `No marketplaces configured` 并退出 `0`。851Claude Code 打印 `Successfully updated marketplace: your-marketplace`。当您省略名称时，它打印计数，如 `Successfully updated 2 marketplaces`。

830 852

831<h2 id="plugin-in-a-session">853<h2 id="plugin-in-a-session">

832 会话中的 /plugin854 会话中的 /plugin

plugins/components.md +1 −1

Details

1034]1034]

1035```1035```

1036 1036

1037命令在 shell 中运行，在会话启动的工作目录中。1037命令在 shell 中运行，位于会话的当前工作目录中。它以您的完整用户权限运行，并且在 [沙箱](/docs/zh-CN/sandboxing) 之外运行。

1038 1038

1039monitor 的命令在其启动位置和可以引用的内容方面受到限制：1039monitor 的命令在其启动位置和可以引用的内容方面受到限制：

1040 1040

plugins/marketplace-reference.md +4 −1

Details

52* **Claude Code 用于不来自 marketplace 的插件的名称**：`inline` 用于使用 [`--plugin-dir`](/docs/zh-CN/cli-reference) 加载的插件，`builtin` 用于内置插件，`skills-dir` 用于从 [`.claude/skills/`](/docs/zh-CN/skills) 自动加载的插件，`synced` 用于从你的 claude.ai 账户同步的插件。`claude-plugin-test` 也被保留。`skills-dir` 也显示为 `{"source": "skills-dir"}`，在 `strictKnownMarketplaces` 和 `blockedMarketplaces` 中，如 [仅在策略列表中有效的源值](#source-values-valid-only-in-policy-lists) 下所述。52* **Claude Code 用于不来自 marketplace 的插件的名称**：`inline` 用于使用 [`--plugin-dir`](/docs/zh-CN/cli-reference) 加载的插件，`builtin` 用于内置插件，`skills-dir` 用于从 [`.claude/skills/`](/docs/zh-CN/skills) 自动加载的插件，`synced` 用于从你的 claude.ai 账户同步的插件。`claude-plugin-test` 也被保留。`skills-dir` 也显示为 `{"source": "skills-dir"}`，在 `strictKnownMarketplaces` 和 `blockedMarketplaces` 中，如 [仅在策略列表中有效的源值](#source-values-valid-only-in-policy-lists) 下所述。

53* **`npm`、`pip`、`uv`、`cargo`、`github` 和 `gh`**：以任何大小写保留。此检查需要 Claude Code v2.1.275 或更高版本。53* **`npm`、`pip`、`uv`、`cargo`、`github` 和 `gh`**：以任何大小写保留。此检查需要 Claude Code v2.1.275 或更高版本。

54* **以 `claudeai-` 开头的名称**：为托管在 claude.ai 上的 marketplace 保留。`claude plugin marketplace add` 拒绝任何其他使用一个的 marketplace，错误为 `Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai`。54* **以 `claudeai-` 开头的名称**：为托管在 claude.ai 上的 marketplace 保留。`claude plugin marketplace add` 拒绝任何其他使用一个的 marketplace，错误为 `Cannot add marketplace "<name>": names starting with "claudeai-" are reserved for marketplaces hosted on claude.ai`。

55* **已注册 GitHub 市场的下载文件夹名称 `<owner>-<repo>`**：对于从 `github` 源（例如 `acme/x-tools`）添加的市场，无论该市场自身的 `name` 是什么，Claude Code 都会通过名为 `acme-x-tools` 的文件夹下载它。当该市场以 `acme-x-tools` 以外的名称注册时，`claude plugin marketplace add` 会在下载另一个名为 `acme-x-tools` 的市场后拒绝它，并报告 `Can't use the marketplace name "acme-x-tools"`。此检查需要 Claude Code v2.1.290 或更高版本。

55 56

56当已注册的 marketplace 因其名称模仿官方名称而停止加载时，`claude plugin list` 和 `/plugin` 报告 `Claude Code refuses the marketplace name "<name>"`。该消息告诉你删除该 marketplace。删除它也会卸载其插件并删除其保存的数据。此命名拒绝消息需要 Claude Code v2.1.282 或更高版本。57当已注册的 marketplace 因其名称模仿官方名称而停止加载时，`claude plugin list` 和 `/plugin` 报告 `Claude Code refuses the marketplace name "<name>"`。该消息告诉你删除该 marketplace。删除它也会卸载其插件并删除其保存的数据。此命名拒绝消息需要 Claude Code v2.1.282 或更高版本。

57 58

498| `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` |499| `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` |

499| `Duplicate plugin name "x" found in marketplace` | 错误 | 两个条目共享一个 `name` |500| `Duplicate plugin name "x" found in marketplace` | 错误 | 两个条目共享一个 `name` |

500| `plugins.i.source: Invalid input` | 错误 | 该条目的 `source` 与任何类型都不匹配。请参阅 [Invalid input on a source](#invalid-input-on-a-source) |501| `plugins.i.source: Invalid input` | 错误 | 该条目的 `source` 与任何类型都不匹配。请参阅 [Invalid input on a source](#invalid-input-on-a-source) |

502| `plugins.i.source: Invalid string: must start with "./"` | 错误 | 缺少开头 `./` 的相对路径 `source`。在 v2.1.285 之前，此错误会改为打印 `Invalid input` |

501| `plugins[i].source: Path contains "..": <path>` | 错误 | 转义 marketplace 根目录的相对 `source` |503| `plugins[i].source: Path contains "..": <path>` | 错误 | 转义 marketplace 根目录的相对 `source` |

502| `source.source: 'unsupported' is a parse-time placeholder and cannot be authored` | 错误 | `plugins[i].source` |504| `source.source: 'unsupported' is a parse-time placeholder and cannot be authored` | 错误 | `plugins[i].source` |

503| `Plugin "x" sets headersHelper but is not "strict": false` | 错误 | `plugins[i].headersHelper`，在 `archive` 条目上 |505| `Plugin "x" sets headersHelper but is not "strict": false` | 错误 | `plugins[i].headersHelper`，在 `archive` 条目上 |

524 526

525`source` 上的 `Invalid input` 意味着该对象与任何源类型都不匹配。检查这些原因：527`source` 上的 `Invalid input` 意味着该对象与任何源类型都不匹配。检查这些原因：

526 528

527* 不以 `./` 开头的相对路径，除了 `"."` 或 [`metadata.pluginRoot` 下的裸名称](#relative-path-plugin-source)

528* 包含 `..` 的 `npm` `package`529* 包含 `..` 的 `npm` `package`

529* 不是 [plugin sources](#plugin-sources) 之一的 `source` 类型530* 不是 [plugin sources](#plugin-sources) 之一的 `source` 类型

530* 已知类型缺少必需字段或字段类型错误，例如没有 `repo` 的 `github`531* 已知类型缺少必需字段或字段类型错误，例如没有 `repo` 的 `github`

531 532

533不以 `./` 开头的相对路径（`"."` 或 [`metadata.pluginRoot` 下的裸名称](#relative-path-plugin-source) 除外）会失败并显示 `Invalid string: must start with "./"`。在 v2.1.285 之前，它会像上述原因一样打印 `Invalid input`。

534

532<h3 id="failures-that-validation-doesn’t-catch">535<h3 id="failures-that-validation-doesn’t-catch">

533 验证未捕获的失败536 验证未捕获的失败

534</h3>537</h3>

plugins/mods/admin.md +56 −56

Details

22</Note>22</Note>

23 23

24<h2 id="stop-user-installed-mods-from-loading">24<h2 id="stop-user-installed-mods-from-loading">

~~25 停止用户安装的 mods 加载~~25 停止用户安装的 mod 加载

26</h2>26</h2>

27 27

28要防止用户带来的每个 mod 加载，请在[内置保护](#know-what-happens-by-default)上设置 `allowManagedModsOnly` 选项，这是一个策略 mod，Claude Code 在用户安装的每个 mod 之前加载。该选项位于 `pluginConfigs` 下的托管设置中，由 `cc-plugin-sec-default@builtin` 键入：28要阻止用户带来的每个 mod 运行其 hook，请在[内置守卫](#know-what-happens-by-default)上设置 `allowManagedModsOnly` 选项。内置守卫是一个策略 mod，Claude Code 会在用户安装的每个 mod 之前加载它。该选项位于托管设置的 `pluginConfigs` 下，以 `cc-plugin-sec-default@builtin` 为键：

29 29

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

31{31{

39}39}

40```40```

41 41

~~42设置了托管设置中的选项后：~~42在托管设置中设置该选项后：

43 43

44* **用户带来的任何 mod 都不会加载**：这包括用户安装的插件中的 mod、使用 `--plugin-dir` 加载的 mod 以及[Claude 在会话期间编写的](/docs/zh-CN/plugins/mods/create#ask-claude-for-a-mod) mod44* **用户带来的任何 mod 都不会运行其 hook**：这包括用户安装的插件中的 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。45* **您组织的 mod 仍然运行**：[计为您组织的](#install-your-organizations-mods) mod 不会被检查。所有其他 mod 都计为用户的 mod，并会被拒绝。这包括您从 GitHub 或其他远程市场启用的插件中的 mod，以及您的组织为其成员在 claude.ai 上启用的 mod。如果没有任何 mod 计为您组织的，则所有已安装的 mod 都不会运行其 hook。

46* **用户无法撤销它**：保护程序仅从托管设置读取选项，因此用户、项目或本地设置文件中的相同条目，或使用 `--settings` 传递的文件中的条目不会改变任何内容46* **用户无法撤销它**：守卫仅从托管设置读取该选项，因此用户、项目或本地设置文件中的相同条目，或使用 `--settings` 传递的文件中的条目都不会改变任何内容

47* **文件或 MDM 策略涵盖每个提供商**：当您以文件形式或通过 MDM 提供选项时，它在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 上的工作方式相同。对于从 claude.ai 管理控制台的交付，请参阅[平台可用性](/docs/zh-CN/server-managed-settings#platform-availability)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` 不受影响~~48* **用户的其他自定义保持工作**：他们[设置文件中的 hook](/docs/zh-CN/hooks) 和插件 `hooks/hooks.json` 中的 hook、状态栏以及 `/goal` 均不受影响

~~49* **内置 mods 继续运行**：内置于 Claude Code 的 mods，例如 `AGENTS.md` 支持，各有[自己的开关](/docs/zh-CN/plugins/mods/overview#mods-built-into-claude-code)~~49* **内置 mod 继续运行**：内置于 Claude Code 的 mod，例如 `AGENTS.md` 支持，各有[自己的开关](/docs/zh-CN/plugins/mods/overview#mods-built-into-claude-code)

50 50

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)。51要在用户机器上确认该选项，请在该机器上使用 `--plugin-dir` 和包含 mod 的目录路径启动 Claude Code，例如 `claude --plugin-dir ./first-mod`。该 mod 的 hook 不会运行，会话记录和调试日志中会出现[守卫的消息](/docs/zh-CN/plugins/mods/troubleshoot#messages-from-the-built-in-guard)，其中会指明该 mod 和 `allowManagedModsOnly`。如果没有出现该消息，请参阅[检查策略是否生效](/docs/zh-CN/managed-settings#check-that-a-policy-is-in-force)以及[决定选项是否生效的规则](#set-options-on-the-built-in-guard)。

52 52

53如果您在早期访问期间将 `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` 设置为 `0`，请将其替换为此选项。Claude Code v2.1.287 及更高版本在任何值下都会忽略该变量，因此那里的 `0` 会使 mods 保持开启。53如果您在早期访问期间将 `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` 设置为 `0`，请将其替换为此选项。Claude Code v2.1.287 及更高版本在任何值下都会忽略该变量，因此那里的 `0` 会使 mod 保持开启。

54 54

55<h2 id="know-what-happens-by-default">55<h2 id="know-what-happens-by-default">

56 了解默认情况下会发生什么56 了解默认情况下会发生什么

117claude plugin validate ./some-mod117claude plugin validate ./some-mod

118```118```

119 119

120输出中的两行描述了 mod 的代码：120输出中的 `hooks:` 和 `calls:` 行描述了 mod 的代码：

121 121

122```text theme={null}122```text theme={null}

123 ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}123 ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}

146 选择允许的程度146 选择允许的程度

147</h2>147</h2>

148 148

149Mod 策略的范围从根本没有已安装的 mods 到用户选择的任何 mod，以及您自己的 mod 检查其他 mods，每一个都是几个托管设置。在第一列中找到您想要的策略，并设置第二列命名的内容。[部署托管设置](/docs/zh-CN/managed-settings)涵盖托管设置的位置。149Mod 策略的范围从根本没有已安装的 mod 到用户选择的任何 mod，以及由您自己的 mod 检查其他 mod，每一种都只需几个托管设置。在第一列中找到您想要的策略，并设置第二列列出的内容。[部署托管设置](/docs/zh-CN/managed-settings)介绍了托管设置的存放位置。

150 150

151| 您想要什么 | 设置 |151| 您想要什么 | 设置 |

152| :- | :- |152| :- | :- |

155| 仅您组织的 mods | 设置保护程序的 [`allowManagedModsOnly` 选项](#stop-user-installed-mods-from-loading)，并[安装您的 mods](#install-your-organizations-mods) 以便它们计为您的 |155| 仅您组织的 mod | 设置守卫的 [`allowManagedModsOnly` 选项](#stop-user-installed-mods-from-loading)，并[安装您的 mod](#install-your-organizations-mods) 以便它们计为您的 |

156| 来自您批准的市场的任何 mod | 保持您的[市场限制](/docs/zh-CN/plugins/org#restrict-what-users-can-install)，并将 `disableSideloadFlags` 设置为 `true` |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` 一起列出它 |157| 任何 mod，由您自己的 mod 检查其他 mod | [安装您的 mod](#install-your-organizations-mods)，并在 `prependPlugins` 中将它与 `sec-default@builtin` 一起列出 |

158 158

159每个设置的作用：159每个设置的作用：

160 160

161* **`allowManagedModsOnly`**：内置保护程序上的选项。用户自己的 mods 不加载，他们的设置 hooks、状态行和 `/goal` 继续工作。[停止用户安装的 mods 加载](#stop-user-installed-mods-from-loading)列出了它涵盖的内容。161* **`allowManagedModsOnly`**：内置守卫上的一个选项。Claude Code 会拒绝用户自己的 mod，因此他们的 hook 都不会运行。用户的设置 hook、状态栏和 `/goal` 继续工作。[停止加载用户安装的 mod](#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)。162* **`allowManagedHooksOnly`**：范围更广的设置。仅[您组织的 mod](#install-your-organizations-mods) 和内置于 Claude Code 的 mod 会加载。用户自己安装的 mod 不会加载。该设置还会阻止用户自己的设置文件中的 hook。在设置之前，请阅读[`allowManagedHooksOnly` 下运行什么](/docs/zh-CN/settings-reference#what-runs-under-allowmanagedhooksonly)。

163* **`disableAllHooks`**：最广泛的设置。在托管设置中，它停止每个已安装插件中的 mods，包括您的，并关闭设置文件中的每个 hook，因此您的托管设置中的 `PreToolUse` hook 不再阻止任何内容。自定义状态行和 `/goal` 也停止工作。在设置之前，请阅读[`disableAllHooks`](/docs/zh-CN/settings-reference#disableallhooks)。163* **`disableAllHooks`**：范围最广的设置。在托管设置中，它会停止每个已安装插件中的 mod（包括您的），并关闭设置文件中的每个 hook，因此您的托管设置中的 `PreToolUse` hook 不再阻止任何内容。自定义状态栏和 `/goal` 也会停止工作。在设置之前，请阅读[`disableAllHooks`](/docs/zh-CN/settings-reference#disableallhooks)。

164* **`disableSideloadFlags`**：在启动时拒绝 `--plugin-dir` 和 `--plugin-url`，并防止 Claude 在会话期间编写的 mods 加载。该设置还拒绝 `--agents` 和 `--mcp-config`。在设置之前，请阅读[`disableSideloadFlags`](/docs/zh-CN/settings-reference#disablesideloadflags)。164* **`disableSideloadFlags`**：在启动时拒绝 `--plugin-dir` 和 `--plugin-url`，并阻止 Claude 在会话期间编写的 mod 加载。该设置还会拒绝 `--agents` 和 `--mcp-config`。在设置之前，请阅读[`disableSideloadFlags`](/docs/zh-CN/settings-reference#disablesideloadflags)。

165 165

166内置于 Claude Code 的 Mods，例如 `AGENTS.md` 支持，不受这些设置的影响。每个都有[自己的开关](/docs/zh-CN/plugins/mods/overview#mods-built-into-claude-code)。166内置于 Claude Code 的 mod，例如 `AGENTS.md` 支持，不受这些设置的影响。每个都有[自己的开关](/docs/zh-CN/plugins/mods/overview#mods-built-into-claude-code)。

167 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` 的行。168如果用户的 mod 被拒绝或未加载，用户可以在其调试日志中找到原因。[拒绝消息](/docs/zh-CN/plugins/mods/troubleshoot#refusal-messages)列出了 `allowManagedHooksOnly` 和 `disableAllHooks` 对应的日志行，[来自内置守卫的消息](/docs/zh-CN/plugins/mods/troubleshoot#messages-from-the-built-in-guard)包含 `allowManagedModsOnly` 对应的日志行。

169 169

170<h3 id="allow-only-your-organization’s-mods">170<h3 id="allow-only-your-organization’s-mods">

171 仅允许您组织的 mods171 仅允许您组织的 mod

172</h3>172</h3>

173 173

174要运行您组织的 mods 并阻止用户带来的 mods，请部署[策略表](#choose-how-much-to-allow)中 **仅您组织的 mods** 一行的设置，再加上 `disableSideloadFlags`。使用以下完整的 `managed-settings.json`，Claude Code 会拒绝用户自己的 mods，因此他们的 hooks 都不会运行，而您的策略 mod 会先于其他 mods 运行：174要运行您组织的 mod 并阻止用户带来的 mod，请部署[策略表](#choose-how-much-to-allow)中 **仅您组织的 mod** 一行的设置，再加上 `disableSideloadFlags`。使用以下完整的 `managed-settings.json`，Claude Code 会拒绝用户自己的 mod，因此他们的 hook 都不会运行，而您的策略 mod 会先于其他 mod 运行：

175 175

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

177{177{

193 193

194每组键各负责一项工作：194每组键各负责一项工作：

195 195

196* **`extraKnownMarketplaces`、`enabledPlugins` 和 `prependPlugins`**：安装您的 mod 以便它计为您的，并让它首先运行，保护程序紧随其后。[安装您组织的 mods 并设置顺序](#install-your-organizations-mods)涵盖这些键所指向的目录。196* **`extraKnownMarketplaces`、`enabledPlugins` 和 `prependPlugins`**：安装您的 mod 以便它计为您的，并让它首先运行，守卫紧随其后。[安装您组织的 mod 并设置顺序](#install-your-organizations-mods)介绍了这些键所指向的目录。

197* **`pluginConfigs`**：设置保护程序的 `allowManagedModsOnly` 选项，因此 Claude Code 会拒绝用户自己的 mods。他们的设置 hooks、状态栏和 `/goal` 继续工作。197* **`pluginConfigs`**：设置守卫的 `allowManagedModsOnly` 选项，因此 Claude Code 会拒绝用户自己的 mod。他们的设置 hook、状态栏和 `/goal` 继续工作。

198* **`disableSideloadFlags`**：有关它在启动时拒绝的标志，请参阅 [`disableSideloadFlags`](/docs/zh-CN/settings-reference#disablesideloadflags)198* **`disableSideloadFlags`**：有关它在启动时拒绝的标志，请参阅 [`disableSideloadFlags`](/docs/zh-CN/settings-reference#disablesideloadflags)

199 199

200要在测试机器上确认该策略，请在您的 shell 中使用 `claude --debug` 启动会话并阅读调试日志：200要在测试机器上确认该策略，请在您的 shell 中使用 `claude --debug` 启动会话并阅读调试日志：

201 201

202* **您的 mod**：其 `hooks module` 行带有 `tier prepend`202* **您的 mod**：其 `hooks module` 行带有 `tier prepend`

203* **用户安装的 mod**：有一行显示 `refused by cc-plugin-sec-default: mods are limited to your organization's by policy (allowManagedModsOnly)`。更早的一行会显示该 mod 的 hooks module 已 `loaded`，因此请查找拒绝信息。203* **用户安装的 mod**：有一行显示 `refused by cc-plugin-sec-default: mods are limited to your organization's by policy (allowManagedModsOnly)`。更早的一行会显示该 mod 的 hook 模块已 `loaded`，因此请查找拒绝信息。

204* **插件目录**：`claude --plugin-dir ./any-mod` 会退出，并显示以 `--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)` 开头的消息204* **插件目录**：`claude --plugin-dir ./any-mod` 会退出，并显示以 `--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)` 开头的消息

205 205

206要同时限制用户可以添加哪些市场，请将此文件与您的[市场限制](/docs/zh-CN/plugins/org#restrict-what-users-can-install)结合使用。206要同时限制用户可以添加哪些市场，请将此文件与您的[市场限制](/docs/zh-CN/plugins/org#restrict-what-users-can-install)结合使用。

207 207

208<h3 id="apply-your-plugin-controls-to-mods">208<h3 id="apply-your-plugin-controls-to-mods">

209 将您的插件控制应用于 mods209 将您的插件控制应用于 mod

210</h3>210</h3>

211 211

212mod 就是插件，因此您[为组织管理插件](/docs/zh-CN/plugins/org)的方式同样适用于包含 mod 的插件：212mod 就是插件，因此您[为组织管理插件](/docs/zh-CN/plugins/org)的方式同样适用于包含 mod 的插件：

216* **为某个群组（例如试点群组）提供不同的策略**：[为托管设置无法强制执行的内容做好规划](/docs/zh-CN/plugins/org#plan-for-what-managed-settings-can’t-enforce)216* **为某个群组（例如试点群组）提供不同的策略**：[为托管设置无法强制执行的内容做好规划](/docs/zh-CN/plugins/org#plan-for-what-managed-settings-can’t-enforce)

217* **检查哪些应用和会话类型会应用插件键**：[各使用入口何时应用插件键](/docs/zh-CN/plugins/org#when-each-surface-applies-the-plugin-keys)217* **检查哪些应用和会话类型会应用插件键**：[各使用入口何时应用插件键](/docs/zh-CN/plugins/org#when-each-surface-applies-the-plugin-keys)

218* **设置 CI 和容器**：[为容器和 CI 预置内容](/docs/zh-CN/plugins/org#seed-containers-and-ci)218* **设置 CI 和容器**：[为容器和 CI 预置内容](/docs/zh-CN/plugins/org#seed-containers-and-ci)

219* **提供用户可以安装的 mods**：[托管市场](/docs/zh-CN/plugins/host-marketplace)。Claude Code 从 GitHub、git、URL 或 npm 源复制的 mod 计为用户的，而不是[您组织的](#install-your-organizations-mods)。219* **提供用户可以安装的 mod**：[托管市场](/docs/zh-CN/plugins/host-marketplace)。Claude Code 从 GitHub、git、URL 或 npm 源复制的 mod 计为用户的，而不是[您组织的](#install-your-organizations-mods)。

220 220

221<h3 id="set-options-on-the-built-in-guard">221<h3 id="set-options-on-the-built-in-guard">

222 在内置保护程序上设置选项222 在内置守卫上设置选项

223</h3>223</h3>

224 224

225内置保护程序接受选项。在托管设置中的 `pluginConfigs` 下设置它们，由 `cc-plugin-sec-default@builtin` 键入，如[停止用户安装的 mods 加载](#stop-user-installed-mods-from-loading)中的示例所示。225内置守卫接受选项。在托管设置中的 `pluginConfigs` 下设置它们，以 `cc-plugin-sec-default@builtin` 为键，如[停止加载用户安装的 mod](#stop-user-installed-mods-from-loading)中的示例所示。

226 226

227该表给出了您的用户在每个选项未设置和设置为 `true` 时获得的内容：227该表给出了每个选项未设置和设置为 `true` 时您的用户获得的结果：

228 228

229| 选项 | 未设置 | `true` |229| 选项 | 未设置 | `true` |

230| :- | :- | :- |230| :- | :- | :- |

231| `allowManagedModsOnly` | 用户自己的 mods 加载 | 仅[您组织的 mods](#install-your-organizations-mods) 和内置于 Claude Code 的 mods 加载。Claude Code 拒绝所有其他 mods，包括用户安装的或使用 `--plugin-dir` 命名的。 |231| `allowManagedModsOnly` | 用户自己的 mod 会运行 | 仅[您组织的 mod](#install-your-organizations-mods) 和内置于 Claude Code 的 mod 会运行其 hook。Claude Code 会拒绝所有其他 mod，包括用户安装的或使用 `--plugin-dir` 指定的 mod。 |

233 233

234这些规则决定选项是否生效：234这些规则决定选项是否生效：

235 235

236* **id 在这里只有一种形式**：Claude Code 仅在 `cc-plugin-sec-default@builtin` 下读取选项。`prependPlugins` 也接受 `sec-default@builtin`，而 `pluginConfigs` 不接受。236* **id 在这里只有一种形式**：Claude Code 仅在 `cc-plugin-sec-default@builtin` 下读取选项。`prependPlugins` 也接受 `sec-default@builtin`，而 `pluginConfigs` 不接受。

237* **仅托管设置计数**：用户、项目或本地设置文件中的相同条目，或使用 `--settings` 传递的文件中的相同条目既不设置选项也不放松选项237* **仅托管设置有效**：用户、项目或本地设置文件中的相同条目，或使用 `--settings` 传递的文件中的相同条目，既不会设置选项，也不会放宽选项

238* **保护程序必须加载**：如果您设置 `prependPlugins`，[在列表中命名保护程序](#install-your-organizations-mods)。保护程序不加载的地方，两个选项都不适用。238* **守卫必须加载**：如果您设置了 `prependPlugins`，请[在列表中指定守卫](#install-your-organizations-mods)。守卫未加载时，两个选项都不适用。

239* **保护程序失败关闭**：如果保护程序无法读取托管设置，它会拒绝每个用户的 mod 加载。如果它无法检查用户的 mod 批准的调用的拒绝规则，它会拒绝该调用。239* **守卫以失败即关闭方式运行**：如果守卫无法读取托管设置，它会在加载时拒绝每个用户的 mod。如果它无法针对用户的 mod 所批准的调用检查拒绝规则，它会拒绝该调用。

240 240

241[来自内置保护程序的消息](/docs/zh-CN/plugins/mods/troubleshoot#messages-from-the-built-in-guard)是您的用户在任一选项适用时看到的内容。241[来自内置守卫的消息](/docs/zh-CN/plugins/mods/troubleshoot#messages-from-the-built-in-guard)是任一选项生效时您的用户看到的内容。

242 242

243<h2 id="run-your-organization’s-own-mods">243<h2 id="run-your-organization’s-own-mods">

244 运行您组织自己的 mods244 运行您组织自己的 mod

245</h2>245</h2>

246 246

247您可以将自己的 mods 部署给每个用户，选择它们相对于用户 mods 的运行位置，并使用一个来强制执行策略。247您可以将自己的 mod 部署给每个用户，选择它们相对于用户 mod 的运行位置，并使用一个来强制执行策略。

248 248

249<h3 id="install-your-organizations-mods">249<h3 id="install-your-organizations-mods">

250 安装您组织的 mods 并设置顺序250 安装您组织的 mod 并设置顺序

251</h3>251</h3>

252 252

253您组织的 mods 在用户 mods 无法加载的地方加载，并且可以在用户 mods 之前运行，因此 Claude Code 必须能够判断 mod 是否来自您。只有当以下所有条件都为真时，它才会将 mod 视为您组织的：253您组织的 mod 在用户 mod 无法加载的地方加载，并且可以在用户 mod 之前运行，因此 Claude Code 必须能够判断 mod 是否来自您。只有当以下所有条件都为真时，它才会将 mod 视为您组织的：

254 254

255* 托管的 `enabledPlugins` 将 mod 的插件设置为 `true`255* 托管的 `enabledPlugins` 将 mod 的插件设置为 `true`

256* 托管设置通过绝对路径将插件的[市场](/docs/zh-CN/plugins/create-marketplace)指定为用户机器上的目录。`extraKnownMarketplaces` 条目可以做到这一点，并且也会为用户注册该市场。256* 托管设置通过绝对路径将插件的[市场](/docs/zh-CN/plugins/create-marketplace)指定为用户机器上的目录。`extraKnownMarketplaces` 条目可以做到这一点，并且也会为用户注册该市场。

285}285}

286```286```

287 287

288Claude Code 复制到其缓存中的插件计为用户的，即使托管的 `enabledPlugins` 启用了它。这涵盖了来自 GitHub、git、URL 或 npm 源的每个插件。其 mod 在用户 mods 中运行，`prependPlugins` 和 `appendPlugins` 会跳过它，并且它不会在 `allowManagedModsOnly` 或 `allowManagedHooksOnly` 下加载。用户的调试日志中有一行以插件的 id 和 `is enabled by managed settings, but` 开头。288Claude Code 复制到其缓存中的插件计为用户的，即使托管的 `enabledPlugins` 启用了它。这涵盖了来自 GitHub、git、URL 或 npm 源的每个插件。其 mod 在用户 mod 中运行，`prependPlugins` 和 `appendPlugins` 会跳过它，`allowManagedModsOnly` 会拒绝它，`allowManagedHooksOnly` 会阻止它加载。用户的调试日志中有一行以插件的 id 和 `is enabled by managed settings, but` 开头。

289 289

290Claude Code 每次即将采取行动（例如运行工具）时都会触发一个事件，并依次将其传递给每个 mod。计为您的 mod [在用户 mods 之前运行](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in)，即使您没有在任何地方列出它。要设置其位置，请在两个设置之一中列出其 id。id 是插件的名称、`@` 和市场的名称，例如 `acme-guard@acme-tools`。290Claude Code 每次即将采取行动（例如运行工具）时都会触发一个事件，并依次将其传递给每个 mod。计为您的 mod [在用户 mod 之前运行](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in)，即使您没有在任何地方列出它。要设置其位置，请在两个设置之一中列出其 id。id 是插件的名称、`@` 和市场的名称，例如 `acme-guard@acme-tools`。

291 291

292* **`prependPlugins`**：您的 mod 在任何用户 mod 之前看到每个事件，并在之后看到每个结果。它可以更改事件、拒绝事件或跳过用户 mods。292* **`prependPlugins`**：您的 mod 在任何用户 mod 之前看到每个事件，并在之后看到每个结果。它可以更改事件、拒绝事件或跳过用户 mod。

293* **`appendPlugins`**：您的 mod 在每个用户 mod 之后运行，因此它只看到这些 mods 传递的事件，并以它们传递的形式看到293* **`appendPlugins`**：您的 mod 在每个用户 mod 之后运行，因此它只看到这些 mod 传递的事件，并以它们传递的形式看到

294 294

295此示例在 `/opt/acme/claude-plugins` 声明 `acme-tools` 市场，启用来自它的 `acme-guard`，并首先运行该 mod，内置保护在其后：295此示例在 `/opt/acme/claude-plugins` 声明 `acme-tools` 市场，启用来自它的 `acme-guard`，并首先运行该 mod，内置守卫在其后：

296 296

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

298{298{

310 310

311* **`extraKnownMarketplaces`**：指定保存 `acme-tools` 市场的目录。`path` 是包含 `.claude-plugin/marketplace.json` 的目录的绝对路径。311* **`extraKnownMarketplaces`**：指定保存 `acme-tools` 市场的目录。`path` 是包含 `.claude-plugin/marketplace.json` 的目录的绝对路径。

312* **`enabledPlugins`**：为接收这些托管设置的每个用户启用 `acme-guard`312* **`enabledPlugins`**：为接收这些托管设置的每个用户启用 `acme-guard`

313* **`prependPlugins`**：将 `acme-guard` 放在第一位，内置保护放在第二位，都在用户安装的任何 mod 之前。Claude Code 遵循您列出的顺序。313* **`prependPlugins`**：将 `acme-guard` 放在第一位，内置守卫放在第二位，都在用户安装的任何 mod 之前。Claude Code 遵循您列出的顺序。

314 314

315要确认用户的机器收到了设置，请参阅[检查策略是否生效](/docs/zh-CN/managed-settings#check-that-a-policy-is-in-force)。315要确认用户的机器收到了设置，请参阅[检查策略是否生效](/docs/zh-CN/managed-settings#check-that-a-policy-is-in-force)。

316 316

321 321

322这些规则决定了两个列表中哪些 id 生效：322这些规则决定了两个列表中哪些 id 生效：

323 323

324* **列表替换默认值**：当您在托管设置中设置 `prependPlugins` 时，请在其中列出 `sec-default@builtin` 以保留内置保护。该保护是内置的，不需要 `enabledPlugins` 条目。324* **列表替换默认值**：当您在托管设置中设置 `prependPlugins` 时，请在其中列出 `sec-default@builtin` 以保留内置守卫。该守卫是内置的，不需要 `enabledPlugins` 条目。

325* **您自己的 id 必须计为您的**：在托管设置中，Claude Code 会跳过其插件不满足组织 mod 条件的 id325* **您自己的 id 必须计为您的**：在托管设置中，Claude Code 会跳过其插件不满足组织 mod 条件的 id

326* **仓库无法设置它们**：Claude Code 从托管设置读取这两个设置，从不从仓库的设置文件读取。用户可以在 `~/.claude/settings.json` 中设置它们来对自己的 mods 排序，但仅限于没有托管设置的机器，并且仅当他们未使用 Team 或 Enterprise 计划登录时。在其他任何情况下，Claude Code 都会忽略用户设置中的这两个键。那里的列表既不添加也不删除内置保护。326* **仓库无法设置它们**：Claude Code 从托管设置读取这两个设置，从不从仓库的设置文件读取。用户可以在 `~/.claude/settings.json` 中设置它们来对自己的 mod 排序，但仅限于没有托管设置的机器，并且仅当他们未使用 Team 或 Enterprise 计划登录时。在其他任何情况下，Claude Code 都会忽略用户设置中的这两个键。那里的列表既不添加也不删除内置守卫。

327 327

328<h3 id="enforce-a-policy-with-a-mod-of-your-own">328<h3 id="enforce-a-policy-with-a-mod-of-your-own">

329 使用您自己的 mod 强制执行策略329 使用您自己的 mod 强制执行策略

330</h3>330</h3>

331 331

332要阻止每个用户的 mod，您不需要自己的 mod。设置 [`allowManagedModsOnly`](#stop-user-installed-mods-from-loading) 即可。当您想允许某些用户的 mods 并拒绝其他的，或记录 mods 的行为时，请编写策略 mod。332要阻止每个用户的 mod，您不需要自己的 mod。设置 [`allowManagedModsOnly`](#stop-user-installed-mods-from-loading) 即可。当您想允许某些用户的 mod 并拒绝其他的，或记录 mod 的行为时，请编写策略 mod。

333 333

334每次另一个 mod 即将加载时，您的 mod 会在名为 [`plugin.register`](/docs/zh-CN/plugins/mods/reference#other-mods) 的事件中收到 `claude plugin validate` 打印的列表。`prependPlugins` 中的 mod 可以读取该列表并拒绝该 mod。它也可以[按名称处理任何 mods API 调用](/docs/zh-CN/plugins/mods/api#reach-files-processes-and-the-network)，以便针对每个其他 mod 记录或拒绝该调用。名称是去掉 `$.` 的方法，因此 `fs.write` 上的 hook 会看到每个 `$.fs.write` 调用。334每次另一个 mod 即将加载时，您的 mod 会在名为 [`plugin.register`](/docs/zh-CN/plugins/mods/reference#other-mods) 的事件中收到 `claude plugin validate` 打印的列表。`prependPlugins` 中的 mod 可以读取该列表并拒绝该 mod。它也可以[按名称处理任何 mods API 调用](/docs/zh-CN/plugins/mods/api#reach-files-processes-and-the-network)，以便针对每个其他 mod 记录或拒绝该调用。名称是去掉 `$.` 的方法，因此 `fs.write` 上的 hook 会看到每个 `$.fs.write` 调用。

335 335

381 381

382要将审计行发送到调试日志以外的地方，请从相同的 hook 中调用 `$.http.fetch`。382要将审计行发送到调试日志以外的地方，请从相同的 hook 中调用 `$.http.fetch`。

383 383

384会话可以在没有您的 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，包括您的。384会话可以在没有您的 mod 的情况下运行。如果运行已安装 mod 的工作线程[崩溃三次](/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 的用户运行时不会加载已安装的 mod，包括您的。

385 385

386[创建 mod](/docs/zh-CN/plugins/mods/create) 介绍 mod 需要的文件。[测试策略 mod](/docs/zh-CN/plugins/mods/test#test-a-mod-that-judges-other-mods) 提供此策略 mod 的测试文件。386[创建 mod](/docs/zh-CN/plugins/mods/create) 介绍 mod 需要的文件。[测试策略 mod](/docs/zh-CN/plugins/mods/test#test-a-mod-that-judges-other-mods) 提供此策略 mod 的测试文件。

387 387

388<h4 id="refuse-mods-when-your-check-fails">388<h4 id="refuse-mods-when-your-check-fails">

389 当您的检查失败时拒绝 mods389 当您的检查失败时拒绝 mod

390</h4>390</h4>

391 391

392如果您的 `plugin.register` hook 抛出异常或超过其时间限制，Claude Code 会跳过该 hook，因此检查以放行方式失败，正在被检查的 mod 会加载。要以拒绝方式失败并拒绝用户 mods，请将检查移到命名函数中，并添加返回拒绝的 `.catch` 处理程序。此版本的文件仅显示 `plugin.register` hook，因此请在 `register` 中保留第一个版本的两个审计 hook：392如果您的 `plugin.register` hook 抛出异常或超过其时间限制，Claude Code 会跳过该 hook，因此检查以放行方式失败，正在被检查的 mod 会加载。要以拒绝方式失败并拒绝用户 mod，请将检查移到命名函数中，并添加返回拒绝的 `.catch` 处理程序。此版本的文件仅显示 `plugin.register` hook，因此请在 `register` 中保留第一个版本的两个审计 hook：

393 393

394```javascript acme-guard/hooks/register.js theme={null}394```javascript acme-guard/hooks/register.js theme={null}

395const BLOCKED_CALLS = ['process.run', 'process.spawn']395const BLOCKED_CALLS = ['process.run', 'process.spawn']

414}414}

415```415```

416 416

417处理程序就位后，如果检查在处理某个 mod 时抛出异常或超时，该 mod 不会加载，拒绝行会带有第二个原因，例如 `refused by acme-guard: Acme policy check failed, so this mod was not loaded`。处理程序将 `user` 层以外的每个 mod 传递给 `next(e)`，因此失败的检查不会阻止您组织列出的 mods。[处理失败的 hook](/docs/zh-CN/plugins/mods/events#handle-a-hook-that-fails) 介绍其他事件的 `.catch`。417处理程序就位后，如果检查在处理某个 mod 时抛出异常或超时，该 mod 不会加载，拒绝行会带有第二个原因，例如 `refused by acme-guard: Acme policy check failed, so this mod was not loaded`。处理程序将 `user` 层以外的每个 mod 传递给 `next(e)`，因此失败的检查不会阻止您组织列出的 mod。[处理失败的 hook](/docs/zh-CN/plugins/mods/events#handle-a-hook-that-fails) 介绍其他事件的 `.catch`。

418 418

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

420 后续步骤420 后续步骤

plugins/mods/api.md +12 −3

Details

71 71

72当您询问工单时，Claude 可以使用其 id 调用 `mcp__my-mod__ticket`。第二个 hook 获取工单并返回响应体，Claude 将其作为工具的结果读取。当服务器以错误状态回答时，Claude 读取 `Lookup failed with status` 和数字。72当您询问工单时，Claude 可以使用其 id 调用 `mcp__my-mod__ticket`。第二个 hook 获取工单并返回响应体，Claude 将其作为工具的结果读取。当服务器以错误状态回答时，Claude 读取 `Lookup failed with status` 和数字。

73 73

74<Tip>

75 当 [MCP 工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)延迟加载某个已注册的工具时，Claude 能看到其名称，但在搜索该工具之前看不到其描述。如果 Claude 应在每一轮都考虑该工具，请在注册中添加 [`isDeferred: false`](/docs/zh-CN/plugins/mods/reference#tools)，以[预先加载完整工具](/docs/zh-CN/mcp#exempt-a-server-from-deferral)。该字段需要 Claude Code v2.1.293 或更高版本，早期版本会忽略它。

76</Tip>

74<h2 id="call-a-model">78<h2 id="call-a-model">

75 调用模型79 调用模型

76</h2>80</h2>

187 访问文件、进程和网络191 访问文件、进程和网络

188</h2>192</h2>

189 193

190mod 通过 mods API 访问文件系统、进程和网络，具有与运行 Claude Code 的用户相同的权限。hooks 模块本身没有 Node.js API、没有计时器全局变量（如 `setTimeout`），也没有自己的网络或文件访问。标准 JavaScript 和 Web API（如 `URL`、`TextEncoder`、`AbortController` 和 `crypto.subtle`）可用。下面的每个命名空间涵盖一种访问：194mod 通过 mods API 访问文件系统、进程和网络，具有与运行 Claude Code 的用户相同的权限。hook 模块本身没有 Node.js API、没有计时器全局变量（如 `setTimeout`），也没有自己的网络或文件访问。标准 JavaScript 和 Web API（如 `URL`、`TextEncoder`、`AbortController` 和 `crypto.subtle`）可用。下面的每个命名空间涵盖一种访问：

191 195

192| 命名空间 | 它做什么 |196| 命名空间 | 它做什么 |

193| :- | :- |197| :- | :- |

198| `$.env` | `get` 和 `set` 环境变量。将名称写为文字字符串。 |202| `$.env` | `get` 和 `set` 环境变量。将名称写为文字字符串。 |

200| `$.session` | `messages()` 将成绩单作为 `{ role, text, toolUses }` 列表返回。还有工作目录、模型等。[`usage()`](/docs/zh-CN/plugins/mods/reference#mods-api-methods) 返回上下文窗口使用和计划限制。 |204| `$.session` | `messages()` 将会话记录作为 `{ role, text, toolUses }` 列表返回。还有工作目录、模型等。[`usage()`](/docs/zh-CN/plugins/mods/reference#mods-api-methods) 返回上下文窗口使用和计划限制。 |

201| `$.mcp` | `call` 连接的 MCP 服务器上的工具 |205| `$.mcp` | `call` 连接的 MCP 服务器上的工具 |

202 206

203文件和进程有一些自己的规则：207文件和进程有一些自己的规则：

204 208

205* **路径**：相对路径相对于会话的工作目录进行解析209* **路径**：相对路径相对于会话的工作目录进行解析

206* **`$.fs.list`**：将一个目录的条目作为 `{ name, kind, size, isLink }` 返回，不进行递归210* **`$.fs.list`**：将一个目录的条目作为 `{ name, kind, size, isLink }` 返回，不进行递归

207* **`$.process.run`**：接受参数列表，不使用 shell。它解析为 `{ exitCode, stdout, stderr }`，无论退出代码如何。如果程序无法启动或在超时时仍在运行，它会拒绝，默认为 30 秒，因此将其包装在 `try` 和 `catch` 中。211* **`$.process.run`**：接受参数列表，不使用 shell。它解析为 `{ exitCode, stdout, stderr }`，无论退出码如何。如果程序无法启动或在超时时仍在运行，它会拒绝，默认为 30 秒，因此将其包装在 `try` 和 `catch` 中。

208 212

209这些调用中的每一个本身都是一个事件，以其命名空间和方法命名，不带 `$.`，例如 `fs.read` 用于 `$.fs.read`。[链中较早的](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in) mod 可以观察、重写或拒绝您的调用，这是组织限制 mod 到达的方式。213这些调用中的每一个本身都是一个事件，以其命名空间和方法命名，不带 `$.`，例如 `fs.read` 用于 `$.fs.read`。[链中较早的](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in) mod 可以观察、重写或拒绝您的调用，这是组织限制 mod 到达的方式。

210 214

215mod 可以在命令已产生输出或已退出之后拒绝您的 `$.process.spawn` 调用，且该命令已执行的任何操作都不会被撤销。此时该调用会拒绝，并返回一条以下列字符串之一加上拒绝方 mod 的原因结尾的消息：

216

217* **`$.process.spawn started, and a plugin withheld its result:`**：拒绝方 mod 尚未将命令的输出读取到末尾。如果命令仍在运行，Claude Code 会将其停止。

218* **`$.process.spawn ran, and a plugin withheld its result:`**：拒绝方 mod 已将命令的输出读取到末尾，因此命令已经退出

219

211<h2 id="next-steps">220<h2 id="next-steps">

212 后续步骤221 后续步骤

213</h2>222</h2>

plugins/mods/create.md +1 −1

Details

316✔ Validation passed316✔ Validation passed

317```317```

318 318

319`hooks:` 行列出你的模块 hook 的事件，每个都带有其在大括号中的过滤器。`calls:` 行列出它调用的每个 mods API 方法。读取或设置环境变量的模块也会获得 `env reads:` 和 `env writes:` 行，使用 [`$.state`](/docs/zh-CN/plugins/mods/interface#keep-state) 的模块会获得 `state reads:` 和 `state writes:`。319在 `hooks:` 行中查看您的模块 hook 的事件，每个事件的过滤器都显示在大括号中；在 `calls:` 行中查看它调用的每个 mods API 方法。如果您的模块读取或设置环境变量，还请查看 `env reads:` 和 `env writes:` 行；如果它使用 [`$.state`](/docs/zh-CN/plugins/mods/interface#keep-state)，还请查看 `state reads:` 和 `state writes:` 行。对于每个可以拒绝操作的 hook，您还会看到一行，例如 `gating hook without .catch: tool.call`，它表明该 hook 是否有 [`.catch` 处理程序](/docs/zh-CN/plugins/mods/events#handle-a-hook-that-fails)。

320 320

321如果您打算处理的某个事件未出现在第一行中，Claude Code 也不会调用该 hook。常见原因是事件名称拼写错误，该命令会将其报告为错误，例如 `"tool.calls" is not an event`。321如果您打算处理的某个事件未出现在第一行中，Claude Code 也不会调用该 hook。常见原因是事件名称拼写错误，该命令会将其报告为错误，例如 `"tool.calls" is not an event`。

322 322

plugins/mods/events.md +30 −14

Details

245 245

246当您发送诸如 `open a PR for this change` 之类的提示词时，您的消息在会话记录中看起来不变，而 Claude 还会在其后读取诸如 `Current branch: feature/auth` 的一行。未提及 Pull Request 的提示词会原样通过，且不会运行 `git`。246当您发送诸如 `open a PR for this change` 之类的提示词时，您的消息在会话记录中看起来不变，而 Claude 还会在其后读取诸如 `Current branch: feature/auth` 的一行。未提及 Pull Request 的提示词会原样通过，且不会运行 `git`。

247 247

248要阻止提示词，请在不调用 `next` 的情况下返回 `{ drop: 'the reason' }`。如果您的 hook 在其 `next(e)` 调用已放行提示词之后返回 `drop`，轮次仍会运行，并且该 hook 会[失败](#handle-a-hook-that-fails)，错误消息中包含 `a drop after its next() was answered`。

249

248[其他事件](/docs/zh-CN/plugins/mods/reference#prompts-and-what-claude-reads)涵盖了 Claude 读取的其余内容：`prompt.section` 用于系统提示词的每个部分，`prompt.context` 用于随第一条消息发送的上下文，`skill.prompt` 用于 skill 的文本。这些 hook 产生的文本如果在请求之间发生变化，会[使提示缓存失效](/docs/zh-CN/prompt-caching)。250[其他事件](/docs/zh-CN/plugins/mods/reference#prompts-and-what-claude-reads)涵盖了 Claude 读取的其余内容：`prompt.section` 用于系统提示词的每个部分，`prompt.context` 用于随第一条消息发送的上下文，`skill.prompt` 用于 skill 的文本。这些 hook 产生的文本如果在请求之间发生变化，会[使提示缓存失效](/docs/zh-CN/prompt-caching)。

249 251

250<h3 id="follow-a-turn">252<h3 id="follow-a-turn">

308 mod 运行的顺序310 mod 运行的顺序

309</h3>311</h3>

310 312

311同一事件上的 hooks 形成一个中间件链。每个 mod 的 `next` 调用以下 mod 的 hook，最后的 `next` 到达 Claude Code 自己的行为。第一个 mod 是最外层的：它在其他 mod 之前看到事件，在它们之后看到结果，并决定其他 mod 是否运行。后续 mod 无法阻止早期 mod 看到事件。313同一事件上的 hook 形成一个中间件链。每个 mod 的 `next` 调用下一个 mod 的 hook，最后的 `next` 到达 Claude Code 自己的行为。第一个 mod 是最外层的：它在其他 mod 之前看到事件，在它们之后看到结果，并决定其他 mod 是否运行。后续 mod 无法阻止早期 mod 看到事件。

312 314

313Claude Code 按每个 mod 的来源对链进行排序：315Claude Code 按每个 mod 的来源对链进行排序：

314 316

3151. 内置保护 `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` 中3171. 内置守卫 `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，然后是任何其他算作您的组织的、且不在 `appendPlugins` 中的 mod

3162. 你安装的 mod3182. 您安装的 mod

3173. 你的组织在 `appendPlugins` 中列出的 mod3193. 您的组织在 `appendPlugins` 中列出的 mod

3184. 其他内置于 Claude Code 的 mod3204. 其他内置于 Claude Code 的 mod

319 321

320在你安装的 mod 中，mod 在它在清单中的 `dependencies` 下列出的 mod 之前运行。在一个模块中，hooks 按 `register` 调用 `on` 的顺序运行。322在您安装的 mod 中，mod 在它在清单中的 `dependencies` 下列出的 mod 之前运行。在一个模块中，hook 按 `register` 调用 `on` 的顺序运行。

321 323

322<h4 id="where-settings-hooks-run-in-the-order">324<h4 id="where-settings-hooks-run-in-the-order">

323 设置 hooks 在顺序中运行的位置325 设置 hook 在顺序中运行的位置

324</h4>326</h4>

325 327

326在设置文件中配置的 `PreToolUse` hooks 也在工具调用期间运行，在 mod 链中的固定点：328在设置文件中配置的 `PreToolUse` hook 也在工具调用期间运行，位于 mod 链中的固定点：

327 329

328* **来自托管设置的 `PreToolUse` hooks**：在第一个 mod 的 `tool.call` hook 之前运行，其中任一 hook 的阻止都是最终决定，因此没有 mod 看到调用。330* **来自托管设置的 `PreToolUse` hook**：在第一个 mod 的 `tool.call` hook 之前运行，其中任一 hook 的阻止都是最终决定，因此没有 mod 看到调用。

329* **来自每个其他设置文件和插件的 `hooks/hooks.json` 的 `PreToolUse` hooks**：在最后一个 mod 调用 `next` 后运行，作为 Claude Code 自己的行为的一部分。回答 `tool.call` 而不调用 `next` 的 mod 会阻止它们运行，调用 `next` 的 mod 在它返回的结果中看到它们的决定。331* **来自每个其他设置文件和插件的 `hooks/hooks.json` 的 `PreToolUse` hook**：在最后一个 mod 调用 `next` 后运行，作为 Claude Code 自己的行为的一部分。回答 `tool.call` 而不调用 `next` 的 mod 会阻止它们运行，调用 `next` 的 mod 在它返回的结果中看到它们的决定。

330 332

331[`tool.check`](#approve-or-refuse-a-tool-call-before-the-user-is-asked) 在这些 hook 和权限规则做出决定后触发，因此其上的 hook 可以批准第二组中的 hook 所阻止的调用。333[`tool.check`](#approve-or-refuse-a-tool-call-before-the-user-is-asked) 在这些 hook 和权限规则做出决定后触发，因此其上的 hook 可以批准第二组中的 hook 所阻止的调用。

332 334

334 处理失败的 hook336 处理失败的 hook

335</h3>337</h3>

336 338

337失败的 hook 不会破坏会话，你可以决定接下来会发生什么。当没有 `.catch` 处理程序的 hook 抛出、超时或返回错误形状的结果时，接下来会发生什么取决于它是否调用了 `next`：339失败的 hook 不会破坏会话，您可以决定接下来会发生什么。当没有 `.catch` 处理程序的 hook 抛出、超时或返回错误形状的结果时，接下来会发生什么取决于它是否调用了 `next`：

338 340

339* **它在调用 `next` 之前失败**：Claude Code 跳过它，下一个处理程序代替运行341* **它在调用 `next` 之前失败**：Claude Code 跳过它，下一个处理程序代替运行

340* **它在 `next` 解析后失败**：该结果成立，没有任何东西运行第二次342* **它在 `next` 解析后失败**：该结果成立，没有任何东西运行第二次

341 343

342一行命名 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)所述。344一行内容会指明 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)所述。

343 345

344要使阻止调用的 hook 失败关闭，请添加一个 `.catch` 错误处理程序来代替回答。这里，`guard` 是你的 hook 函数：346要使阻止调用的 hook 失败关闭，请添加一个 `.catch` 错误处理程序来代替回答。这里，`guard` 是您的 hook 函数，处理程序检查 [`next.called`](/docs/zh-CN/plugins/mods/reference#the-hook-function) 来判断 `guard` 在失败时是否已经调用了 `next`：

345 347

346```javascript theme={null}348```javascript theme={null}

347// on 返回一个注册，.catch 将处理程序附加到该 hook349// on 返回一个注册，.catch 将处理程序附加到该 hook

348on('tool.call', { tool: 'Bash' }, guard).catch(async ($, e, next) => {350on('tool.call', { tool: 'Bash' }, guard).catch(async ($, e, next) => {

349 // next.error.kind 是 'throw' 或 'timeout'，说明 guard 如何失败351 // guard 已经调用了 next，因此返回得到的结果

352 if (next.called) return next(e)

353 // next.error.kind 说明调用处理程序的原因，例如 'throw' 或 'timeout'

350 return { deny: 'The command guard failed, so this command was not run: ' + next.error.kind }354 return { deny: 'The command guard failed, so this command was not run: ' + next.error.kind }

351})355})

352```356```

353 357

354当 `guard` 工作时，处理程序永远不会运行。当 `guard` 在 Bash 调用上抛出或超时时，Claude Code 使用相同的事件调用处理程序。处理程序返回 `{ deny }`，所以命令不会运行，Claude 读取末尾带有 `throw` 或 `timeout` 的文本。没有处理程序，Claude Code 会跳过 `guard` 并运行命令。处理程序自身有更短的[时间限制](/docs/zh-CN/plugins/mods/reference#limits)。358当 `guard` 在 Bash 调用上抛出或超时时，Claude Code 使用相同的事件调用处理程序：

359

360* **`guard` 在调用 `next` 之前失败**：命令不会运行，Claude 读取末尾带有该类型的 `deny` 文本

361* **`guard` 在调用 `next` 之后失败**：处理程序的 `next(e)` 解析为 `guard` 的调用所产生的结果，而不会再次运行命令，Claude 读取该结果

362

363处理程序自身有更短的[时间限制](/docs/zh-CN/plugins/mods/reference#limits)。如果处理程序本身抛出或超时，Claude Code 会像该 hook 没有处理程序一样跳过它。如果 `guard` 尚未调用 `next`，命令随后会像没有该 mod 时一样继续执行。

364

365同样的处理程序形式也适用于 `prompt.submit` 或 `config.set` 上的守卫。当 `next.called` 为 false 时，返回[事件参考](/docs/zh-CN/plugins/mods/reference#events)为该事件列出的拒绝：`prompt.submit` 使用 `{ drop: 'the reason' }`，`config.set` 使用 `{ deny: 'the reason' }`。

366

367在 `tool.check` 和 `plugin.register` 中，在 `next` 解析后返回的拒绝仍然有效，因此无需检查 `next.called`，直接返回即可：

368

369* **`tool.check`**：返回 `{ decision: 'deny', reason: 'the reason' }`

370* **`plugin.register`**：返回 `{ refuse: 'the reason' }`，如[在检查失败时拒绝 mod](/docs/zh-CN/plugins/mods/admin#refuse-mods-when-your-check-fails) 所示

355 371

356<h2 id="next-steps">372<h2 id="next-steps">

357 后续步骤373 后续步骤

plugins/mods/gallery.md +8 −0

Details

415 415

416另有两个元素在此没有示例。`Image` 在终端中绘制 PNG 或原始像素。`Client` 是由您的另一个文件负责绘制的区域，用于动画和指针输入。[元素参考](/docs/zh-CN/plugins/mods/reference#elements)列出了它们的 props。416另有两个元素在此没有示例。`Image` 在终端中绘制 PNG 或原始像素。`Client` 是由您的另一个文件负责绘制的区域，用于动画和指针输入。[元素参考](/docs/zh-CN/plugins/mods/reference#elements)列出了它们的 props。

417 417

418除非 Claude Code 检测到终端能够绘制使用 Unicode 占位符的 kitty 图形协议图像，否则用户看到的将是以暗色显示的 `Image` 的 `alt` 文本，而不是图片。请编写能够独立表达含义的 `alt` 文本。检测在启动时运行：在 kitty 0.28 或更高版本以及 Ghostty 中，一旦终端响应了 Claude Code 的图形查询，检测即会成功；在以下情况下检测会失败：

419

420* **其他终端**：不属于上述两者的任何终端，或不响应该查询的终端。

421* **tmux 和 screen**：在任何终端（包括 kitty 和 Ghostty）中运行于 tmux 或 screen 内的会话。

422* **后台会话**：每个[后台会话](/docs/zh-CN/agent-view)，无论从哪个终端连接。

423

424如果您的 mod 的用户在确实能够绘制这些占位符图像的终端中看到了暗色文本，可以将 [`CLAUDE_CODE_FORCE_TERMINAL_IMAGES`](/docs/zh-CN/env-vars) 设置为 `1`，以跳过检测。在 tmux 或 screen 中这样做并无帮助：`alt` 文本会消失，而 Claude Code 发送图片时不会为 tmux 或 screen 直通对其进行包装。

425

418<h2 id="see-where-a-mod-can-draw">426<h2 id="see-where-a-mod-can-draw">

419 了解 mod 可以在哪里绘制427 了解 mod 可以在哪里绘制

420</h2>428</h2>

plugins/mods/interface.md +21 −0

Details

443 443

444在使用 `--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` 并带有相同的原因。会话中没有其他内容出现，所以当绘制不显示时，请检查该行或日志。444在使用 `--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` 并带有相同的原因。会话中没有其他内容出现，所以当绘制不显示时，请检查该行或日志。

445 445

446<h3 id="link-in-the-desktop-app">

447 桌面应用中的 `Link`

448</h3>

449

450在桌面应用中，除非 `Link` 的 `href` 满足以下要求，否则它会绘制为纯文本：

451

452* **协议和主机**：`https:` URL，或 `http://localhost` URL，例如 `http://localhost:3000`

453* **不含 `@`**：将路径或查询中的 `@` 写为 `%40`

454* **写法**：与 `new URL(href).href` 返回的内容一致，主机后缺少的 `/` 除外。这排除了大写主机、空格以及 `https:` URL 上的 `:443`。

455

456在终端中，这些要求不适用。

457

458<h3 id="when-a-client-fails">

459 当 `Client` 失败时

460</h3>

461

462在终端中，当 `Client` 运行的文件失败时，一行暗色文本（例如 `my-mod: Client client/spinner.js: boom`）会取代 `Client` 的位置，而您绘制的其余部分仍会显示。

463

464如果您的 mod 处理 [`ui.fault`](/docs/zh-CN/plugins/mods/reference#interface)，Claude Code 随后会[再次绘制该站点](#when-claude-code-redraws-without-being-asked)。

465

446<h3 id="draw-a-grid-of-colored-cells">466<h3 id="draw-a-grid-of-colored-cells">

447 绘制彩色单元格网格467 绘制彩色单元格网格

448</h3>468</h3>

806以下规则适用于代码：826以下规则适用于代码：

807 827

808* **将 `plugin` 和 `key` 写成字面字符串**：`claude plugin validate` 从您的源代码中读取它们828* **将 `plugin` 和 `key` 写成字面字符串**：`claude plugin validate` 从您的源代码中读取它们

829* **将每个 `atom` 调用的结果保存在 `const` 中**：如果您用 `let` 声明 `count`，验证失败，出现 `takes a source the scan can read`

809* **在类型声明文件中声明每个值**：否则验证失败，出现 `hello-tabs.count is not declared`830* **在类型声明文件中声明每个值**：否则验证失败，出现 `hello-tabs.count is not declared`

810* **从回调或另一个事件的 hook 中写入**：`ui.render` hook 可以读取状态，但不能写入它，因此请从 `onPress`、`onSubmit` 或另一个事件的 hook 中写入831* **从回调或另一个事件的 hook 中写入**：`ui.render` hook 可以读取状态，但不能写入它，因此请从 `onPress`、`onSubmit` 或另一个事件的 hook 中写入

811 832

plugins/mods/overview.md +1 −1

Details

113mod 默认处于打开状态。在终端中，请使用 Claude Code v2.1.287 或更高版本。Desktop 应用包含其自带的 Claude Code 副本，mod 从 v2.1.286 起即可在其中使用。请在您使用 mod 的地方检查版本：113mod 默认处于打开状态。在终端中，请使用 Claude Code v2.1.287 或更高版本。Desktop 应用包含其自带的 Claude Code 副本，mod 从 v2.1.286 起即可在其中使用。请在您使用 mod 的地方检查版本：

114 114

115* **终端**：在您的 shell 中运行 `claude --version`。如果您的版本较旧，请[更新 Claude Code](/docs/zh-CN/setup#update-claude-code)。115* **终端**：在您的 shell 中运行 `claude --version`。如果您的版本较旧，请[更新 Claude Code](/docs/zh-CN/setup#update-claude-code)。

116* **Desktop 应用**：在 Code 选项卡的本地会话中输入 `/status`，查看 **Claude Code** 一行，其中会显示 `2.1.286` 之类的版本号。如果您的版本较旧，请更新 Desktop 应用。116* **Desktop 应用**：在 Code 选项卡的本地会话中输入 `/status`，查看 **Claude Code** 一行，其中会显示 `2.1.286` 之类的版本号。如果您的版本较旧，请[更新 Desktop 应用](/docs/zh-CN/desktop#claude-code-version-in-the-code-tab)。

117 117

118要关闭 mods，选择要停止多少个，以及停止多长时间。要重新打开它们，撤销相同的更改：118要关闭 mods，选择要停止多少个，以及停止多长时间。要重新打开它们，撤销相同的更改：

119 119

plugins/mods/reference.md +20 −6

Details

43| `next.origin` | 触发该事件者的 `{ plugin, tier }`。Claude Code 自身为 `{ plugin: 'engine', tier: 'core' }`。mod 的 `tier` 是它在 [mod 运行顺序](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in)中的优先级组：`prepend`、`user`、`append` 或 `builtin`。 |43| `next.origin` | 触发该事件者的 `{ plugin, tier }`。Claude Code 自身为 `{ plugin: 'engine', tier: 'core' }`。mod 的 `tier` 是它在 [mod 运行顺序](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in)中的优先级组：`prepend`、`user`、`append` 或 `builtin`。 |

44| `next.budget` | hook 的时间限制（以毫秒为单位）：`next.budget.ms` 是总限制，`next.budget.remainingMs` 是当前剩余时间 |44| `next.budget` | hook 的时间限制（以毫秒为单位）：`next.budget.ms` 是总限制，`next.budget.remainingMs` 是当前剩余时间 |

45| `next.to(e, tier)` | 跳到后面的层级，即 `append`、`builtin` 或 `core`。`next.to(e, 'append')` 会跳过用户安装的 mod。只有 `prependPlugins` 或 `appendPlugins` 中的 mod 才能调用它。 |45| `next.to(e, tier)` | 跳到后面的层级，即 `append`、`builtin` 或 `core`。`next.to(e, 'append')` 会跳过用户安装的 mod。只有 `prependPlugins` 或 `appendPlugins` 中的 mod 才能调用它。 |

46| `next.error`, `next.called` | 仅在 `.catch` 处理程序中可用。`next.error.kind` 为 `throw` 或 `timeout`，`next.error.message` 是错误文本；当失败的 hook 已调用 `next` 时，`next.called` 为 `true`。 |46| `next.error` | 仅在 `.catch` 处理程序中可用。hook 失败时，`kind` 为 `throw` 或 `timeout`，`message` 是错误文本。当 hook 因事件来自其自身某个 mods API 调用内部而被跳过时，`kind` 为 `re-entry`；如果触发该事件的是另一个 mod 添加到 mods API 的方法，则 `cause` 为 `lent`。`re-entry` 和 `cause` 需要 Claude Code v2.1.292 或更高版本。 |

47| `next.called` | 仅在 `.catch` 处理程序中可用。当 hook 已调用 `next` 时为 `true`。 |

47 48

48<h2 id="events">49<h2 id="events">

49 事件50 事件

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

66| `tool.describe` | 每个工具一次，在其描述首次发送给 Claude 时 | `{ description }`，可选择将 `isDeferred` 设为 `true` 以将该工具置于[工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)之后，或设为 `false` 以预先加载它 |67| `tool.describe` | 每个工具一次，在其描述首次发送给 Claude 时 | `{ description }`，可选择将 `isDeferred` 设为 `true` 以将该工具置于[工具搜索](/docs/zh-CN/mcp#scale-with-mcp-tool-search)之后，或设为 `false` 以预先加载它 |

67 68

69<h4 id="agent-and-organization-fields-on-tool-check">

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

71</h4>

73在 `tool.check` hook 中，读取以下字段可区分子代理的调用与主对话的调用，并查看您的组织是否要求对某个连接器工具进行批准：

75* **`e.agentId`**：当[子代理](/docs/zh-CN/sub-agents)或[进程内队友](/docs/zh-CN/agent-teams#choose-a-display-mode)发出调用时设置，由主对话发出调用时则不存在

76* **`e.ceiling`**：对于您的组织设为 `ask` 的连接器工具，其值为 `ask`，适用于[该设置能传达到 Claude Code 的会话](/docs/zh-CN/mcp#organization-controls-on-connector-tools)

78在 `tool.check` 上，`e.agentId` 和 `e.ceiling` 需要 Claude Code v2.1.290 或更高版本。

68<h3 id="prompts-and-what-claude-reads">80<h3 id="prompts-and-what-claude-reads">

69 提示词以及 Claude 读取的内容81 提示词以及 Claude 读取的内容

70</h3>82</h3>

258| [`Box`](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) | `key`、flex 布局、`gap`、`padding`、`margin`、`width`、`height`、[`borderStyle`](#box-border-styles)、`backgroundColor`、`position`、`hover` | ✓ | ✓ |270| [`Box`](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) | `key`、flex 布局、`gap`、`padding`、`margin`、`width`、`height`、[`borderStyle`](#box-border-styles)、`backgroundColor`、`position`、`hover` | ✓ | ✓ |

259| [`Text`](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) | `color`、`backgroundColor`、`bold`、`italic`、`underline`、`dimColor`、`inverse`、`wrap` | ✓ | ✓ |271| [`Text`](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) | `color`、`backgroundColor`、`bold`、`italic`、`underline`、`dimColor`、`inverse`、`wrap` | ✓ | ✓ |

260| [`Button`](/docs/zh-CN/plugins/mods/interface#respond-to-presses-and-typing) | `key`、`label`、`onPress`、`hotkey`、`plain`、`dimColor`、`autoFocus`、`action` | ✓ | ✓ |272| [`Button`](/docs/zh-CN/plugins/mods/interface#respond-to-presses-and-typing) | `key`、`label`、`onPress`、`hotkey`、`plain`、`dimColor`、`autoFocus`、`action` | ✓ | ✓ |

261| `Link` | `href`、`label` | ✓ | ✓ |273| [`Link`](/docs/zh-CN/plugins/mods/interface#link-in-the-desktop-app) | `href`、`label`。请参阅[限制](#limits)。 | ✓ | ✓ |

262| `Code` | 代码 | ✓ | ✓ |274| [`Code`](/docs/zh-CN/plugins/mods/gallery#show-code-and-changes) | `source`、`language`、`path`、`startLine`、`format`、`wrap` | ✓ | ✓ |

263| `Markdown` | `text`、`key`、`dimColor`、`onLinkPress`、`pressableLinks` | ✓ | ✓ |275| `Markdown` | `text`、`key`、`dimColor`、`onLinkPress`、`pressableLinks` | ✓ | ✓ |

264| [`Input`](/docs/zh-CN/plugins/mods/interface#take-typed-input-and-draw-a-row-for-each-item) | `key`、`label`、`placeholder`、`value`、`submitLabel`、`onSubmit`、`onInput`、`autoFocus` | ✓ | ✓ |276| [`Input`](/docs/zh-CN/plugins/mods/interface#take-typed-input-and-draw-a-row-for-each-item) | `key`、`label`、`placeholder`、`value`、`submitLabel`、`onSubmit`、`onInput`、`autoFocus` | ✓ | ✓ |

265| `Select` | `key`、`label`、`options`、`value`、`onSelect`、`autoFocus` | ✓ | ✓ |277| `Select` | `key`、`label`、`options`、`value`、`onSelect`、`autoFocus` | ✓ | ✓ |

266| `Svg` | 一个 SVG 文档，最多 131,072 个字符 | | ✓ |278| `Svg` | 一个 SVG 文档，最多 131,072 个字符 | | ✓ |

267| [`Client`](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) | `module`、`key` | ✓ | ✓ |279| [`Client`](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) | `module`、`key` | ✓ | ✓ |

268| [`Raster`](/docs/zh-CN/plugins/mods/interface#draw-a-grid-of-colored-cells) | `key`、`columns`（最多 512）、`rows`（最多 256）、`cells`。请参阅[绘制彩色单元格网格](/docs/zh-CN/plugins/mods/interface#draw-a-grid-of-colored-cells)。 | ✓ | |280| [`Raster`](/docs/zh-CN/plugins/mods/interface#draw-a-grid-of-colored-cells) | `key`、`columns`（最多 512）、`rows`（最多 256）、`cells`。请参阅[绘制彩色单元格网格](/docs/zh-CN/plugins/mods/interface#draw-a-grid-of-colored-cells)。 | ✓ | |

269| `Image` | 最多 2 MiB 的 PNG 或 RGBA 字节，或文件路径 | ✓ | |281| `Image` | 最多 2 MiB 的 PNG 或 RGBA 字节，或文件路径，`columns` 和 `rows`（最多 255），以及 `alt` 文本。 | ✓ | |

270 282

271更多 `Button` 规则：`action` 指定 Claude Code 自身的某个[快捷键操作](/docs/zh-CN/keybindings)，当用户为该操作设置的绑定是组合键或带修饰键的按键时，该绑定会按下此按钮。当用户在空的输入框中只输入某个数字并停顿时，横栏中设置了该数字 `hotkey` 的按钮也会触发。当同一次绘制中的两个按钮指定相同的 `hotkey` 时，由后一个按钮获得它。`autoFocus` 在任何控件上都只接受 `true`，因此要关闭它，请省略该 prop。283更多 `Button` 规则：`action` 指定 Claude Code 自身的某个[快捷键操作](/docs/zh-CN/keybindings)，当用户为该操作设置的绑定是组合键或带修饰键的按键时，该绑定会按下此按钮。当用户在空的输入框中只输入某个数字并停顿时，横栏中设置了该数字 `hotkey` 的按钮也会触发。当同一次绘制中的两个按钮指定相同的 `hotkey` 时，由后一个按钮获得它。`autoFocus` 在任何控件上都只接受 `true`，因此要关闭它，请省略该 prop。

272 284

295 限制307 限制

296</h2>308</h2>

297 309

298hook 和 mods API 调用受时间和大小限制。Claude Code 会跳过超出时间限制的 hook，并拒绝超出大小限制的调用。310hook 和 mods API 调用受时间和大小限制。Claude Code 会跳过超出时间限制的 hook。

299 311

300| 限制 | 值 |312| 限制 | 值 |

301| :- | :- |313| :- | :- |

308| 单个树中的文本 | 仅绘制前 100,000 个字符 |320| 单个树中的文本 | 仅绘制前 100,000 个字符 |

321| `Code` 的 `language` 或 `path`、`Select` 选项的 `value`，或 `Client` 的 `module` | 10,000 个字符。如果其中任何一项超出此长度，Claude Code 会[在该位置绘制其自身的版本](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements)。 |

322| `Link` 的 `href` | 2,048 个字符。更长的 `href` 会导致整个树无法绘制。 |

327| `prependPlugins`, `appendPlugins` | 托管设置。仅在没有托管设置的机器上、且用户未使用 Team 或 Enterprise 套餐登录时，才可在用户设置中使用。 | 插件 id 列表，例如 `acme-guard@acme-tools`。`prependPlugins` 中的 mod 在用户安装的每个 mod 之前运行，`appendPlugins` 中的 mod 在之后运行，均按列出的顺序。请参阅 [mod 运行顺序](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in)。 |341| `prependPlugins`, `appendPlugins` | 托管设置。仅在没有托管设置的机器上、且用户未使用 Team 或 Enterprise 套餐登录时，才可在用户设置中使用。 | 插件 id 列表，例如 `acme-guard@acme-tools`。`prependPlugins` 中的 mod 在用户安装的每个 mod 之前运行，`appendPlugins` 中的 mod 在之后运行，均按列出的顺序。请参阅 [mod 运行顺序](/docs/zh-CN/plugins/mods/events#the-order-mods-run-in)。 |

328| `allowManagedModsOnly` | 托管设置，作为[内置守卫的选项](/docs/zh-CN/plugins/mods/admin#set-options-on-the-built-in-guard) | 只加载[算作您组织的](/docs/zh-CN/plugins/mods/admin#install-your-organizations-mods) mod 以及 Claude Code 内置的 mod。用户的设置 hook 会继续运行。 |342| `allowManagedModsOnly` | 托管设置，作为[内置守卫的选项](/docs/zh-CN/plugins/mods/admin#set-options-on-the-built-in-guard) | 只有[算作您组织的](/docs/zh-CN/plugins/mods/admin#install-your-organizations-mods) mod 以及 Claude Code 内置的 mod 会运行其 hook。用户的设置 hook 会继续运行。 |

plugins/mods/test.md +3 −1

Details

107 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:` 开头的块，每个错误都出现在那里：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 109

110* `returned neither { value } nor { deny }`：mods API 调用的 stub 返回了一个裸值110* `returned neither { value } nor { deny }`：mods API 调用的 stub 返回了一个裸值，这会导致测试失败

111* `no implementation for` 后跟一个名称：您的 mod 进行了该调用，没有 stub 回答它111* `no implementation for` 后跟一个名称：您的 mod 进行了该调用，没有 stub 回答它

112 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) 所做的那样。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) 所做的那样。

198 198

199`expect` 有断言 `toBe`、`toEqual`、`toMatch`、`toMatchObject`、`toContain`、`toBeDefined`、`toBeUndefined` 和 `toThrow`，以及任何之前的 `.not`。199`expect` 有断言 `toBe`、`toEqual`、`toMatch`、`toMatchObject`、`toContain`、`toBeDefined`、`toBeUndefined` 和 `toThrow`，以及任何之前的 `.not`。

200 200

201当 `expect` 在您以普通函数（而非异步生成器）形式传给 `on` 的 stub 或 hook 中失败时，测试会失败。引擎会跳过该 hook，失败输出会指出其名称，例如 `in the test's store.set hook`。

202

201<h2 id="test-a-timer">203<h2 id="test-a-timer">

202 测试计时器204 测试计时器

203</h2>205</h2>

plugins/mods/troubleshoot.md +43 −11

Details

6 6

7> 了解为什么 Claude Code mod 不起作用：将症状或消息与其原因匹配，查找拒绝消息，并阅读调试日志。7> 了解为什么 Claude Code mod 不起作用：将症状或消息与其原因匹配，查找拒绝消息，并阅读调试日志。

8 8

9当 mod 的模块或其中一个 hooks 失败时，Claude Code 会跳过它，会话继续进行，因此损坏的 mod 看起来像什么都不做的 mod。首先检查 Claude Code 从 mod 读取了什么以及它在哪里报告问题，然后找到您遇到的症状或消息。9当 mod 的模块或其中一个 hook 失败时，Claude Code 会跳过它，会话继续进行，因此损坏的 mod 看起来像什么都不做的 mod。首先检查 Claude Code 从 mod 读取了什么以及它在哪里报告问题，然后找到您遇到的症状或消息。

10 10

11<h2 id="find-out-why-a-mod-does-nothing">11<h2 id="find-out-why-a-mod-does-nothing">

12 找出为什么 mod 不起作用12 找出为什么 mod 不起作用

30| :- | :- |30| :- | :- |

31| `no hooks module to load` | Mod 可以加载。该命令在此目录中找不到要测试的 mod。 |31| `no hooks module to load` | Mod 可以加载。该命令在此目录中找不到要测试的 mod。 |

32| `hooks modules are turned off here` | 一个设置正在阻止您的 mod：您自己的设置中的 `disableAllHooks`，或您的组织的策略 |32| `hooks modules are turned off here` | 一个设置正在阻止您的 mod：您自己的设置中的 `disableAllHooks`，或您的组织的策略 |

34| `hooks modules are turned off in this process: the rollout switch was saved off by an earlier session` | 该命令使用了之前某个会话保存的值，该值可能已过时。请启动一次 `claude` 以刷新该值，然后再次运行该命令。 |

34 35

35组织还可以设置 `allowManagedModsOnly` 以仅允许其自己的 mod，此命令不会报告。在这种情况下，您安装的 mod 不会加载，[消息会说明原因](/docs/zh-CN/plugins/mods/troubleshoot#messages-from-the-built-in-guard)。36组织还可以设置 `allowManagedModsOnly` 以仅允许其自己的 mod，此命令不会报告。在这种情况下，Claude Code 会拒绝您安装的 mod，并且[会有消息说明原因](/docs/zh-CN/plugins/mods/troubleshoot#messages-from-the-built-in-guard)。

36 37

37<h2 id="the-mod-doesn’t-load">38<h2 id="the-mod-doesn’t-load">

38 mod 不加载39 mod 不加载

72 73

73| 消息开头 | 这意味着什么 |74| 消息开头 | 这意味着什么 |

74| :- | :- |75| :- | :- |

77| `hooks modules are turned off for installed plugins in this process: the rollout switch was saved off by an earlier session` | 该会话使用了先前会话保存的值，该值可能已过时。请重新启动 Claude Code 以刷新该值。 |

76| `disableAllHooks in managed settings` | 您的组织关闭了来自已安装插件的 hooks |78| `disableAllHooks in managed settings` | 您的组织关闭了来自已安装插件的 hooks |

77| `only managed plugins and built-in plugins run` | 设置了 `allowManagedHooksOnly`，或在托管设置以外的设置文件中设置了 `disableAllHooks` |79| `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 |80| `installed plugins that are not managed load no hooks module in this mode (--bare)` | 您使用 `--bare` 启动了 Claude Code |

86 88

88| :- | :- | :- |90| :- | :- | :- |

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) 中的成绩单 |91| `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` 运行中，仅调试日志。 |92| `tried to lift a deny rule in your settings` | 您的 mod 的 [`tool.check`](/docs/zh-CN/plugins/mods/reference#tools) hook 批准了 `deny` 规则拒绝的调用。该调用保持被拒绝。 | 成绩单和调试日志，会话中每个 mod 一次。在 `claude -p` 运行中，仅调试日志。 |

92 94

163 165

164修复 hook。166修复 hook。

165 167

168<h3 id="its-session-start-ran-again-in-a-fresh-copy">

169 `its session.start ran again in a fresh copy`

170</h3>

171

172该行以 mod 的名称开头，并指出一个 `$.prompt.submit`、`$.command.run` 或 `$.agent.spawn` 调用，如 `first-mod: its session.start ran again in a fresh copy; the $.prompt.submit call it had already made was not made again`。Claude Code 再次加载了该 mod 的模块（例如在 hooks worker 崩溃并被替换之后），新副本的 [`session.start`](/docs/zh-CN/plugins/mods/reference#session) hook 运行了。该行指出的调用以其首次运行的结果完成，而没有再次运行，因此您的 mod 不会重复提交提示词、运行命令或启动子代理。hook 的其余部分照常运行。

173

174无需修复。

175

176在 v2.1.292 之前，该调用会再运行一次，因此提示词会被提交两次、命令会被运行两次，或子代理会被启动两次。

177

166<h3 id="mods-that-run-in-the-hooks-worker-are-off-for-this-session">178<h3 id="mods-that-run-in-the-hooks-worker-are-off-for-this-session">

167 `mods that run in the hooks worker are off for this session`179 `mods that run in the hooks worker are off for this session`

168</h3>180</h3>

203 窗格或带为空或显示 Claude Code 的常规内容215 窗格或带为空或显示 Claude Code 的常规内容

204</h3>216</h3>

205 217

206您的 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` 带有相同的原因。218您的 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` 及相同的原因。

207 219

208读取该行上的原因。常见原因是元素不接受的 prop 和应用没有的元素。220读取该行上的原因。常见原因是元素不接受的 prop 和应用没有的元素。

209 221

222<h3 id="a-ui-render-line-says-threw-while-drawn">

223 `ui.render` 行显示 `threw while drawn`

224</h3>

225

226该行会指明[渲染位置](/docs/zh-CN/plugins/mods/reference#render-sites)，然后显示 `threw while drawn:` 及错误，如 `first-mod: ui.render (ToolUse) threw while drawn: <error>; the engine drew its own`。Claude Code 在绘制您的 [`ui.render`](/docs/zh-CN/plugins/mods/reference#interface) hook 返回的树时，或在根据[您的 hook 传递给 `next` 的 `props`](/docs/zh-CN/plugins/mods/interface#change-what-claude-code-already-draws) 绘制该位置时，遇到了该错误。结尾的 `the engine drew its own` 表示该位置显示 Claude Code 的常规内容。

227

228读取该错误，并修复您的 hook 中导致该错误的值。

229

230在 v2.1.289 之前，会话记录行中出现此错误会导致会话以 [`Claude Code exited after an unrecoverable interface error`](/docs/zh-CN/errors#exited-after-an-unrecoverable-interface-error) 结束。

231

232<h3 id="the-module-failed-without-a-message">

233 `the module failed without a message`

234</h3>

235

236某个 [`Client`](/docs/zh-CN/plugins/mods/interface#when-a-client-fails) 因一个没有消息的错误而失败，例如 `throw new Error()`。在其位置显示的行类似 `my-mod: Client client/spinner.js: the module failed without a message`。

237

238在您的 `Client` 代码中找到该 throw，并为该错误提供消息。该行随后会显示该消息。

239

240在 v2.1.289 之前，该行改为显示 `Error` 作为原因。

241

210<h3 id="$-ui-open-runs-and-no-pane-appears">242<h3 id="$-ui-open-runs-and-no-pane-appears">

211 `$.ui.open` 运行且没有窗格出现243 `$.ui.open` 运行且没有窗格出现

212</h3>244</h3>

227 绘图在终端中有效，在桌面应用中无效259 绘图在终端中有效，在桌面应用中无效

228</h3>260</h3>

229 261

230该网站或元素在那里不可用。262该位置或元素在那里不可用。

231 263

232检查 [渲染网站](/docs/zh-CN/plugins/mods/reference#render-sites) 和 [元素](/docs/zh-CN/plugins/mods/reference#elements) 表。264检查 [渲染位置](/docs/zh-CN/plugins/mods/reference#render-sites) 和 [元素](/docs/zh-CN/plugins/mods/reference#elements) 表。

233 265

234<h2 id="an-edit-or-a-value-is-lost">266<h2 id="an-edit-or-a-value-is-lost">

235 编辑或值丢失267 编辑或值丢失

265 阅读调试日志297 阅读调试日志

266</h2>298</h2>

267 299

268调试日志对 Claude Code 加载或拒绝的每个模块、每个失败的 hook 以及它拒绝的每个结果都有一行，因此当成绩单显示无内容时，这是查看的地方。要写入一个，在您的 shell 中使用 `--debug` 启动 Claude Code，或使用 `--debug-file <path>` 选择它的位置：300调试日志对 Claude Code 加载或拒绝的每个模块、每个失败的 hook 以及它拒绝的每个结果都有一行，因此当会话记录中没有任何显示时，这是查看的地方。要写入一个，在您的 shell 中使用 `--debug` 启动 Claude Code，或使用 `--debug-file <path>` 选择它的位置：

269 301

270```bash theme={null}302```bash theme={null}

271claude --debug-file ./mod-debug.log --plugin-dir ./first-mod303claude --debug-file ./mod-debug.log --plugin-dir ./first-mod

283hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render315hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render

284```316```

285 317

286未验证的绘图计为被拒绝的结果，也会获得一行。要在日志中写入您自己的行，请调用 [`$.ui.log`](/docs/zh-CN/plugins/mods/api#show-something-without-starting-a-turn)，带有第二个参数，如 `$.ui.log('message', { to: 'debug' })`。没有第二个参数，`$.ui.log` 会在成绩单中添加一条暗行。318未验证的绘图计为被拒绝的结果，也会获得一行。要在日志中写入您自己的行，请调用 [`$.ui.log`](/docs/zh-CN/plugins/mods/api#show-something-without-starting-a-turn)，带有第二个参数，如 `$.ui.log('message', { to: 'debug' })`。没有第二个参数，`$.ui.log` 会在会话记录中添加一条暗行。

287 319

288当您编辑使用 `--plugin-dir` 加载的 mod 时，成绩单为每次重新加载显示一行，命名 mod 并列出其 hooks。如果保存破坏了模块，该行说 `reload failed, the previous version stays loaded:` 带有原因，最后一个工作版本继续运行。320当您编辑使用 `--plugin-dir` 加载的 mod 时，会话记录为每次重新加载显示一行，命名 mod 并列出其 hook。如果保存破坏了模块，该行会显示 `reload failed, the previous version stays loaded:` 及原因，最后一个可用版本会继续运行，直到 Claude Code 下次重新加载插件，例如当您运行 `/reload-plugins` 时。

289 321

290<h2 id="next-steps">322<h2 id="next-steps">

291 后续步骤323 后续步骤

plugins/org.md +1 −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| [`allowManagedModsOnly`](/docs/zh-CN/plugins/mods/admin#stop-user-installed-mods-from-loading) | 阻止每个不[算作您组织所有](/docs/zh-CN/plugins/mods/admin#install-your-organizations-mods)的已安装 [mod](/docs/zh-CN/plugins/mods/overview) 运行其 hook | 不停止包含 mod 的插件安装。为此，使用此表中的市场键 |

216 216

217表中的每个键都是托管设置，除了 `enabledPlugins`、`syncClaudeAiPlugins`、`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 和 `allowManagedModsOnly`：217表中的每个键都是托管设置，除了 `enabledPlugins`、`syncClaudeAiPlugins`、`CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL` 和 `allowManagedModsOnly`：

218 218

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* **Monitors**：插件的 [monitors](/docs/zh-CN/plugins/components#monitors) 作为后台 shell 命令运行，Claude Code 会在会话开始时、您重新加载插件时，或某个指定的 skill 首次运行时自行启动它们。

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)。33* **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)。

33* **MCP 和 LSP 服务器**：Claude Code 连接到启用的插件声明的 [MCP 服务器](/docs/zh-CN/mcp)，并为 Claude 提供它们的工具。stdio MCP 服务器作为 Claude Code 在您的机器上启动的进程运行。Claude Code 也启动插件声明的语言服务器。34* **MCP 和 LSP 服务器**：Claude Code 连接到启用的插件声明的 [MCP 服务器](/docs/zh-CN/mcp)，并为 Claude 提供它们的工具。stdio MCP 服务器作为 Claude Code 在您的机器上启动的进程运行。Claude Code 也启动插件声明的语言服务器。

34* **`bin/` 目录**：Claude Code 将每个启用的插件的 `bin/` 目录添加到 Bash 工具 shell 的 `PATH` 中，所以 Claude 的 Bash 命令可以运行那里的任何可执行文件。35* **`bin/` 目录**：Claude Code 将每个启用的插件的 `bin/` 目录添加到 Bash 工具 shell 的 `PATH` 中，所以 Claude 的 Bash 命令可以运行那里的任何可执行文件。

37 38

38Claude Code 的[权限规则](/docs/zh-CN/permissions)和[沙箱](/docs/zh-CN/sandboxing)涵盖 Claude 进行的工具调用，而不是插件自己运行的代码：39Claude Code 的[权限规则](/docs/zh-CN/permissions)和[沙箱](/docs/zh-CN/sandboxing)涵盖 Claude 进行的工具调用，而不是插件自己运行的代码：

39 40

40* **Hooks 和服务器进程**：命令 hooks 使用您的完整用户权限执行 shell 命令。Claude Code 在沙箱外运行 hook、MCP 服务器以及 [mod](/docs/zh-CN/plugins/mods/overview#what-a-mod-can-reach) 启动的进程。41* **Hooks、monitors 和服务器进程**：命令 hook 和 monitors 是使用您的完整用户权限运行的 shell 命令。Claude Code 在沙箱外运行 hook、monitors、MCP 服务器、LSP 服务器以及 [mod](/docs/zh-CN/plugins/mods/overview#what-a-mod-can-reach) 启动的进程。

41* **Claude 的工具调用**：对插件的 MCP 工具之一的调用，以及运行插件 `bin/` 中的可执行文件的 Bash 命令，都是工具调用，所以您的权限规则适用于它们。关于 mod 对工具调用可以做什么，请参阅[决定是否信任 mod](/docs/zh-CN/plugins/mods/overview#decide-whether-to-trust-a-mod)。42* **Claude 的工具调用**：对插件的 MCP 工具之一的调用，以及运行插件 `bin/` 中的可执行文件的 Bash 命令，都是工具调用，所以您的权限规则适用于它们。关于 mod 对工具调用可以做什么，请参阅[决定是否信任 mod](/docs/zh-CN/plugins/mods/overview#decide-whether-to-trust-a-mod)。

42 43

43安装插件也会启用它，除非其清单或市场条目设置了 [`defaultEnabled: false`](/docs/zh-CN/plugins/install#choose-an-install-scope)，并且您自己没有启用它。44安装插件也会启用它，除非其清单或市场条目设置了 [`defaultEnabled: false`](/docs/zh-CN/plugins/install#choose-an-install-scope)，并且您自己没有启用它。

quickstart.md +16 −14

Details

57 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd57 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

58 ```58 ```

59 59

60 安装程序完成后，打开一个新的终端窗口并运行 `claude --version`。正常的安装会打印一个版本号。如果您的 shell 显示找不到 `claude` 或无法识别，说明安装目录还不在您的 PATH 中：请参阅[修复您的 PATH](/docs/zh-CN/troubleshoot-install#command-not-found-claude-after-installation)。60 安装命令在下载 Claude Code 期间不会显示进度。安装程序完成后，打开一个新的终端窗口并运行 `claude --version`。正常的安装会打印一个版本号。如果您的 shell 显示找不到 `claude` 或无法识别，说明安装目录还不在您的 PATH 中：请参阅[修复您的 PATH](/docs/zh-CN/troubleshoot-install#command-not-found-claude-after-installation)。

61 61

62 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。62 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。

63 63

233 步骤 7：试用其他常见工作流233 步骤 7：试用其他常见工作流

234</h2>234</h2>

235 235

236您可以通过多种方式与 Claude 协作：236再尝试几个提示词。您可以让 Claude 重构代码、编写测试、更新文档或审查您的更改：

~~237~~

238**重构代码**

239 237

240```text wrap theme={null}238```text wrap theme={null}

241refactor the authentication module to use async/await instead of callbacks239refactor the authentication module to use async/await instead of callbacks

242```240```

243 241

244**编写测试**

~~245~~

246```text wrap theme={null}242```text wrap theme={null}

247write unit tests for the calculator functions243write unit tests for the calculator functions

248```244```

249 245

250**更新文档**

~~251~~

252```text wrap theme={null}246```text wrap theme={null}

253update the README with installation instructions247update the README with installation instructions

254```248```

255 249

256**代码审查**

~~257~~

258```text wrap theme={null}250```text wrap theme={null}

259review my changes and suggest improvements251review my changes and suggest improvements

260```252```

267 基本命令259 基本命令

268</h2>260</h2>

269 261

270以下是日常使用中最重要的命令。Shell 命令从您的终端运行以启动或恢复 Claude Code。会话命令在 Claude Code 启动后在其内部运行。262以下是日常使用中最重要的命令，按运行位置分组。

271 263

272**Shell 命令**264<h3 id="shell-commands">

265 Shell 命令

266</h3>

267

268从终端运行这些命令以启动或恢复 Claude Code。

273 269

274| 命令 | 功能 | 示例 |270| 命令 | 功能 | 示例 |

275| - | - | - |271| - | - | - |

281 277

282**会话命令**278有关完整的 shell 命令列表，请参阅 [CLI 参考](/docs/zh-CN/cli-reference)。

279

280<h3 id="session-commands">

281 会话命令

282</h3>

283

284在 Claude Code 启动后，在其内部运行这些命令。

283 285

284| 命令 | 功能 | 示例 |286| 命令 | 功能 | 示例 |

285| - | - | - |287| - | - | - |

289 291

290有关完整的 shell 命令列表，请参阅 [CLI 参考](/docs/zh-CN/cli-reference)，有关完整的会话命令列表，请参阅 [命令参考](/docs/zh-CN/commands)。292有关完整的会话命令列表，请参阅 [命令参考](/docs/zh-CN/commands)。

291 293

292<h2 id="pro-tips-for-beginners">294<h2 id="pro-tips-for-beginners">

293 初学者专业提示295 初学者专业提示

remote-control.md +2 −2

Details

201* **`false`**：关闭自动连接，尽管来自[托管设置](/docs/zh-CN/managed-settings)的 `true` 会优先，因为 Claude Code 将选择保存到您的用户设置。项目或本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中的 `false` 即使在托管 `true` 上也会关闭自动连接。201* **`false`**：关闭自动连接，尽管来自[托管设置](/docs/zh-CN/managed-settings)的 `true` 会优先，因为 Claude Code 将选择保存到您的用户设置。项目或本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中的 `false` 即使在托管 `true` 上也会关闭自动连接。

202* **`default`**：清除您的选择并遵循您组织的管理员默认值（如果已设置），否则遵循 Claude Code 的当前默认值。202* **`default`**：清除您的选择并遵循您组织的管理员默认值（如果已设置），否则遵循 Claude Code 的当前默认值。

203 203

204相同的切换出现在 CLI 之外：204VS Code 扩展和 Desktop 应用也有自动连接开关：

205 205

206* **Desktop 应用**：**设置 > Claude Code > 将新会话连接到远程控制**。

207* **VS Code 扩展**：[命令菜单](/docs/zh-CN/vs-code#use-the-prompt-box)的设置部分中的**为所有会话启用远程控制**。206* **VS Code 扩展**：[命令菜单](/docs/zh-CN/vs-code#use-the-prompt-box)的设置部分中的**为所有会话启用远程控制**。

207* **Desktop 应用**：**Settings > Claude Code > Connect new sessions to Remote Control**。请参阅[控制哪些会话出现在您的其他设备上](/docs/zh-CN/desktop#control-which-sessions-appear-on-your-other-devices)。

208 208

209要改为从设置文件打开自动连接，请在您的用户 `~/.claude/settings.json` 或[托管设置](/docs/zh-CN/managed-settings)中将 [`remoteControlAtStartup`](/docs/zh-CN/settings-reference#remotecontrolatstartup) 设置为 `true`。在项目或本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中，Claude Code 遵守 `false` 并为该存储库关闭自动连接，但忽略 `true`，因此已检入的文件无法为打开存储库的每个人打开远程控制。209要改为从设置文件打开自动连接，请在您的用户 `~/.claude/settings.json` 或[托管设置](/docs/zh-CN/managed-settings)中将 [`remoteControlAtStartup`](/docs/zh-CN/settings-reference#remotecontrolatstartup) 设置为 `true`。在项目或本地设置（`.claude/settings.json`、`.claude/settings.local.json`）中，Claude Code 遵守 `false` 并为该存储库关闭自动连接，但忽略 `true`，因此已检入的文件无法为打开存储库的每个人打开远程控制。

210 210

routines.md +1 −1

Details

93 为例程选择一个 [cloud environment](/docs/zh-CN/cloud-environments)。环境控制云会话可以访问的内容：93 为例程选择一个 [cloud environment](/docs/zh-CN/cloud-environments)。环境控制云会话可以访问的内容：

94 94

95 * **Network access**：设置每次运行期间可用的互联网访问级别95 * **Network access**：设置每次运行期间可用的互联网访问级别

96 * **Environment variables**：提供 Claude 在每次运行期间可以使用的值。它们[对使用该环境的任何人都可见](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)，因此在 Pro 和 Max 计划上，请改为将 Claude 在运行期间调用的 API 的密钥存储为[网络密钥](/docs/zh-CN/cloud-environments#add-api-credentials)。该部分还列出了永远不会获得密钥的请求96 * **Environment variables**：提供 Claude 在每次运行期间可以使用的值。它们[对使用该环境的任何人都可见](/docs/zh-CN/cloud-environments#what-carries-over-from-your-setup)，因此在 Pro 和 Max 计划上，请改为将 Claude 在运行期间调用的 API 的密钥存储为[网络密钥](/docs/zh-CN/cloud-environments#add-network-secrets)。该部分还列出了永远不会获得密钥的请求

97 * **Setup script**：安装例程需要的依赖项和工具。结果是 [cached](/docs/zh-CN/cloud-environments#environment-caching)，因此脚本不会在每个会话上重新运行97 * **Setup script**：安装例程需要的依赖项和工具。结果是 [cached](/docs/zh-CN/cloud-environments#environment-caching)，因此脚本不会在每个会话上重新运行

98 98

99 提供了一个 **Default** 环境，具有 **Trusted** 网络访问，允许仅通过会话网络的 [default allowlist](/docs/zh-CN/cloud-environments#default-allowed-domains) 的包注册表、云提供商 API、容器注册表和常见开发域。您添加到例程的 Connectors 通过 Anthropic 的服务器到达其服务，因此不需要更改允许列表。如果您的例程需要直接到达您自己的服务或该列表之外的域，请在运行前编辑环境的 [network access](/docs/zh-CN/cloud-environments#network-access)。要使用单独的环境，请先 [create one](/docs/zh-CN/cloud-environments#configure-your-environment)。99 提供了一个 **Default** 环境，具有 **Trusted** 网络访问，允许仅通过会话网络的 [default allowlist](/docs/zh-CN/cloud-environments#default-allowed-domains) 的包注册表、云提供商 API、容器注册表和常见开发域。您添加到例程的 Connectors 通过 Anthropic 的服务器到达其服务，因此不需要更改允许列表。如果您的例程需要直接到达您自己的服务或该列表之外的域，请在运行前编辑环境的 [network access](/docs/zh-CN/cloud-environments#network-access)。要使用单独的环境，请先 [create one](/docs/zh-CN/cloud-environments#configure-your-environment)。

sandbox-environments.md +3 −3

Details

22 22

23| 方法 | 隔离的内容 | 需要 Docker | 设置工作量 |23| 方法 | 隔离的内容 | 需要 Docker | 设置工作量 |

24| :- | :- | :- | :- |24| :- | :- | :- | :- |

~~25| [Sandboxed Bash tool](#sandboxed-bash-tool) | Bash、PowerShell 和 Monitor 命令及其子进程 | 否 | macOS 上最少；Linux 和 WSL2 上较少 |~~25| [Sandboxed Bash tool](#sandboxed-bash-tool) | Bash、PowerShell 和 Monitor 工具命令及其子进程 | 否 | macOS 上最少；Linux 和 WSL2 上较少 |

26| [Sandbox runtime](#sandbox-runtime) | 整个 Claude Code 进程，包括文件工具、MCP 服务器和 hooks | 否 | 较少 |26| [Sandbox runtime](#sandbox-runtime) | 整个 Claude Code 进程，包括文件工具、MCP 服务器和 hooks | 否 | 较少 |

27| [Dev container](#dev-containers) | 完整开发环境 | 是 | 中等 |27| [Dev container](#dev-containers) | 完整开发环境 | 是 | 中等 |

28| [Custom container](#custom-container) | 完整开发环境 | 是 | 中等到高 |28| [Custom container](#custom-container) | 完整开发环境 | 是 | 中等到高 |

76 此选项不支持本机 Windows。在 Windows 主机上，使用 WSL2 或下面的容器或虚拟机方法之一。76 此选项不支持本机 Windows。在 Windows 主机上，使用 WSL2 或下面的容器或虚拟机方法之一。

77</Note>77</Note>

78 78

~~79Sandboxed Bash tool 内置于 Claude Code 中。它使用操作系统原语来限制 Claude 运行的每个 Bash、PowerShell 或 Monitor 命令的文件系统和网络访问。~~79Sandboxed Bash tool 内置于 Claude Code 中。它使用操作系统原语来限制 Claude 运行的 Bash、PowerShell 和 Monitor 工具命令的文件系统和网络访问。

80 80

81运行 `/sandbox` 命令打开沙箱面板并选择一个模式。[Sandboxing](/docs/zh-CN/sandboxing) 指南涵盖批准模式、默认边界以及如何扩大或缩小它。81运行 `/sandbox` 命令打开沙箱面板并选择一个模式。[Sandboxing](/docs/zh-CN/sandboxing) 指南涵盖批准模式、默认边界以及如何扩大或缩小它。

82 82

83按命令沙箱不涵盖会话中运行的所有内容：83按命令沙箱不涵盖会话中运行的所有内容：

84 84

85* 其他 [built-in tools](/docs/zh-CN/tools-reference)（如 Read、Edit 和 WebFetch）在 Claude Code 进程内运行，不会生成任意代码。[Permission rules](/docs/zh-CN/permissions) 用于路径或域来控制它们。85* 其他 [built-in tools](/docs/zh-CN/tools-reference)（如 Read、Edit 和 WebFetch）在 Claude Code 进程内运行，不会生成任意代码。[Permission rules](/docs/zh-CN/permissions) 用于路径或域来控制它们。

~~86* [MCP](/docs/zh-CN/mcp) 服务器和 [command hooks](/docs/zh-CN/hooks#command-hook-fields) 是在主机上无约束运行的单独进程。~~86* [MCP](/docs/zh-CN/mcp) 服务器、[命令 hook](/docs/zh-CN/hooks#command-hook-fields) 和[插件监视器](/docs/zh-CN/plugins/components#monitors)是在主机上无约束运行的单独进程。有关以这种方式运行的其他进程，请参阅[哪些内容在沙箱外运行](/docs/zh-CN/sandboxing#what-runs-outside-the-sandbox)。

87 87

88要将内置工具、MCP 服务器和 hooks 都放在一个操作系统边界后面，请在 [sandbox runtime](#sandbox-runtime)、[dev container](#dev-containers) 或 [custom container](#custom-container) 内运行整个 Claude Code 进程。88要将内置工具、MCP 服务器和 hooks 都放在一个操作系统边界后面，请在 [sandbox runtime](#sandbox-runtime)、[dev container](#dev-containers) 或 [custom container](#custom-container) 内运行整个 Claude Code 进程。

89 89

sandboxing.md +1 −1

Details

698权限规则和沙箱隔离控制不同的事项：698权限规则和沙箱隔离控制不同的事项：

699 699

700* **权限规则**控制 Claude Code 可以使用哪些工具，并在任何工具运行之前进行评估。它们适用于每个工具：Bash、Read、Edit、WebFetch、MCP 和其他工具，除了拒绝或询问规则无法阻止 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior)，而任何其他工具仍然存在。700* **权限规则**控制 Claude Code 可以使用哪些工具，并在任何工具运行之前进行评估。它们适用于每个工具：Bash、Read、Edit、WebFetch、MCP 和其他工具，除了拒绝或询问规则无法阻止 [`EndConversation`](/docs/zh-CN/tools-reference#endconversation-tool-behavior)，而任何其他工具仍然存在。

701* **沙箱隔离**提供操作系统级别的强制执行，限制 shell 命令在文件系统和网络级别可以访问的内容。它仅适用于 Bash、PowerShell 和 [Monitor](/docs/zh-CN/tools-reference#monitor-tool) 命令及其子进程。701* **沙箱隔离**提供操作系统级别的强制执行，限制 shell 命令在文件系统和网络级别可以访问的内容。它适用于 Bash、PowerShell 和 [Monitor](/docs/zh-CN/tools-reference#monitor-tool) 工具的命令及其子进程。

702 702

703这两个层级在强制执行方式上也有所不同。Claude Code 在命令运行之前根据命令字符串和在自动模式下单独分类器对命令是否安全的判断来评估权限决策。操作系统在运行的进程上强制执行沙箱边界，因此无论模型选择运行什么，即使允许的命令执行的操作超出其名称所示，它也会保持有效。703这两个层级在强制执行方式上也有所不同。Claude Code 在命令运行之前根据命令字符串和在自动模式下单独分类器对命令是否安全的判断来评估权限决策。操作系统在运行的进程上强制执行沙箱边界，因此无论模型选择运行什么，即使允许的命令执行的操作超出其名称所示，它也会保持有效。

704 704

server-managed-settings.md +6 −1

Details

348 348

349由 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本返回的密钥和 [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 凭证都不会触发设置获取。349由 [`apiKeyHelper`](/docs/zh-CN/settings-reference#apikeyhelper) 脚本返回的密钥和 [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) 凭证都不会触发设置获取。

350 350

351会话接收的是其身份验证所用凭据所属组织的托管设置。来自 [Claude Console](https://platform.claude.com) 的 API 密钥属于创建它的 Console 组织，该组织与您的 claude.ai Team 或 Enterprise 组织是相互独立的组织。因此，您在 claude.ai Admin Settings 中配置的设置不会到达使用该密钥进行身份验证的会话，例如使用您公司 Console API 密钥的 CI 作业。要将这些设置应用于该作业，请使用以下选项之一。OAuth 令牌选项不适用于使用 [`--bare`](/docs/zh-CN/headless#start-faster-with-bare-mode) 运行的作业，因为 bare 模式不会读取 `CLAUDE_CODE_OAUTH_TOKEN`。

352

353* **OAuth 令牌**：使用 [`claude setup-token`](/docs/zh-CN/authentication#generate-a-long-lived-token) 生成令牌，为您的 Team 或 Enterprise 组织授权该令牌，并在作业环境中将其设置为 `CLAUDE_CODE_OAUTH_TOKEN`。从该环境中删除任何[优先于](/docs/zh-CN/authentication#authentication-precedence)该令牌的凭据，例如 `ANTHROPIC_API_KEY`。

354* **端点管理的设置**：将[托管设置文件](/docs/zh-CN/managed-settings#delivery-mechanisms)部署到运行该作业的机器上。

355

351在 Claude Desktop 应用中的 [Cowork](https://claude.com/docs/cowork/overview) 会话中，即使用户使用 Team 或 Enterprise 账户登录，Claude Code 也不会从 claude.ai 管理控制台获取服务器管理的设置。[策略应用的位置和时间](/docs/zh-CN/managed-settings#where-and-when-a-policy-applies) 涵盖了哪些策略到达用户机器上的 Cowork 会话和远程 Cowork 会话。claude.ai 在 Cowork 用户从 git 存储库或从 Cowork 标签中的**自定义**添加市场时，仍然会应用您的 [`strictKnownMarketplaces`](/docs/zh-CN/settings-reference#strictknownmarketplaces) 和 [`blockedMarketplaces`](/docs/zh-CN/settings-reference#blockedmarketplaces) 列表。[限制如何工作](/docs/zh-CN/plugins/org#restrict-what-users-can-install) 描述了该检查。356在 Claude Desktop 应用中的 [Cowork](https://claude.com/docs/cowork/overview) 会话中，即使用户使用 Team 或 Enterprise 账户登录，Claude Code 也不会从 claude.ai 管理控制台获取服务器管理的设置。[策略应用的位置和时间](/docs/zh-CN/managed-settings#where-and-when-a-policy-applies) 涵盖了哪些策略到达用户机器上的 Cowork 会话和远程 Cowork 会话。claude.ai 在 Cowork 用户从 git 存储库或从 Cowork 标签中的**自定义**添加市场时，仍然会应用您的 [`strictKnownMarketplaces`](/docs/zh-CN/settings-reference#strictknownmarketplaces) 和 [`blockedMarketplaces`](/docs/zh-CN/settings-reference#blockedmarketplaces) 列表。[限制如何工作](/docs/zh-CN/plugins/org#restrict-what-users-can-install) 描述了该检查。

352 357

353如果您在 shell 中导出 `CLAUDE_CODE_USE_*` 提供商变量或非默认的 `ANTHROPIC_BASE_URL`，Claude Code 将跳过您的会话的设置获取。[`claude doctor` 和 `/status` 报告跳过的获取及其原因](#verify-settings-delivery)。358如果您在 shell 中导出 `CLAUDE_CODE_USE_*` 提供商变量或非默认的 `ANTHROPIC_BASE_URL`，Claude Code 将跳过您的会话的设置获取。[`claude doctor` 和 `/status` 报告跳过的获取及其原因](#verify-settings-delivery)。

379| 用户运行修改的 Claude Code 二进制文件 | 能够运行修改的客户端的用户可以绕过任何客户端控制 |384| 用户运行修改的 Claude Code 二进制文件 | 能够运行修改的客户端的用户可以绕过任何客户端控制 |

380| 用户运行较旧的 Claude Code 版本 | 早于服务器管理设置的版本不会获取或应用它们 |385| 用户运行较旧的 Claude Code 版本 | 早于服务器管理设置的版本不会获取或应用它们 |

381| API 不可用 | 如果可用，缓存的设置应用，但 Claude Code 在获取成功前暂扣的[值](#fetch-and-caching-behavior)除外。没有缓存的情况下，Claude Code 在下次成功获取前不强制执行任何服务器管理的设置，但仍然在设备上应用任何[端点管理的设置](/docs/zh-CN/managed-settings#delivery-mechanisms)。使用 `forceRemoteSettingsRefresh: true` 时，CLI 退出而不是继续，但[`claude auth` 子命令](#enforce-fail-closed-startup)除外。通过[Claude 应用网关](#platform-availability)登录的客户端在启动时退出而没有该设置，具有相同的 `claude auth` 豁免 |386| API 不可用 | 如果可用，缓存的设置应用，但 Claude Code 在获取成功前暂扣的[值](#fetch-and-caching-behavior)除外。没有缓存的情况下，Claude Code 在下次成功获取前不强制执行任何服务器管理的设置，但仍然在设备上应用任何[端点管理的设置](/docs/zh-CN/managed-settings#delivery-mechanisms)。使用 `forceRemoteSettingsRefresh: true` 时，CLI 退出而不是继续，但[`claude auth` 子命令](#enforce-fail-closed-startup)除外。通过[Claude 应用网关](#platform-availability)登录的客户端在启动时退出而没有该设置，具有相同的 `claude auth` 豁免 |

382| 用户使用不同的组织进行身份验证 | 不为托管组织外的账户传递设置 |387| 用户使用不同的组织进行身份验证 | 不为托管组织外的账户传递设置，包括使用 [Console API 密钥](#platform-availability)进行身份验证的会话 |

383| 用户配置[第三方模型提供商](#platform-availability) | 服务器管理的设置被绕过。这包括设置 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_MANTLE`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY`、`CLAUDE_CODE_USE_ANTHROPIC_AWS` 或非默认的 `ANTHROPIC_BASE_URL` |388| 用户配置[第三方模型提供商](#platform-availability) | 服务器管理的设置被绕过。这包括设置 `CLAUDE_CODE_USE_BEDROCK`、`CLAUDE_CODE_USE_MANTLE`、`CLAUDE_CODE_USE_VERTEX`、`CLAUDE_CODE_USE_FOUNDRY`、`CLAUDE_CODE_USE_ANTHROPIC_AWS` 或非默认的 `ANTHROPIC_BASE_URL` |

384| 网络流量被拦截或重定向 | 禁用的 TLS 验证或拦截的流量可以改变客户端接收的设置 |389| 网络流量被拦截或重定向 | 禁用的 TLS 验证或拦截的流量可以改变客户端接收的设置 |

385 390

settings-reference.md +20 −9

Details

1399 1399

1400选择当[安全分类器标记请求](/docs/zh-CN/model-config#automatic-model-fallback)时会发生什么：切换到备用模型并继续，或暂停以便您可以在切换和编辑提示之间选择。1400选择当[安全分类器标记请求](/docs/zh-CN/model-config#automatic-model-fallback)时会发生什么：切换到备用模型并继续，或暂停以便您可以在切换和编辑提示之间选择。

1401 1401

1402* **Scope**: [`Any file`](#scopes)。在 `/config` 中显示为**消息被标记时切换模型**。1402* **Scope**: [`Any file`](#scopes)。在 `/config` 中显示为 **Switch models when a message is flagged**，选项为 **Switch automatically** 和 **Ask each time**。

1403* **Type**: Boolean1403* **Type**: Boolean

1404 * `true`: Claude Code 切换到备用模型并继续1404 * `true`: Claude Code 切换到备用模型并继续

1405 * `false`: 在交互式会话中，Claude Code 暂停以便您可以在切换和编辑提示之间选择；在无法显示对话框的地方，如 `-p` 运行，标记的请求以错误结束1405 * `false`: 在交互式会话中，Claude Code 暂停以便您可以在切换和编辑提示之间选择；在无法显示对话框的地方，如 `-p` 运行，标记的请求以错误结束

1406* **Default**: `true`，自动切换1406* **Default**: 未设置。Claude Code 会自动切换，但在交互式会话中可能会[先询问](/docs/zh-CN/model-config#ask-before-switching)

1407 1407

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

1409{1409{

3130 3130

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

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

3133 * 设置未应答对话框计时器的变量：[`CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS`、`CLAUDE_AFK_TIMEOUT_MS` 和 `CLAUDE_AFK_COUNTDOWN_MS`](/docs/zh-CN/env-vars#variables)。

3134 * [`CLAUDE_CODE_DISABLE_ATTACHMENTS`](/docs/zh-CN/env-vars#variables)，它会关闭附件处理。

3133 3135

3134 在 v2.1.251 之前，项目和本地设置也可以设置此列表中选择 Claude Code 写入其文件位置或导出会话内容的变量，除了 `HOME` 和 `XDG_CONFIG_HOME`。3136 在 v2.1.251 之前，项目和本地设置也可以设置此列表中选择 Claude Code 写入其文件位置或导出会话内容的变量，除了 `HOME` 和 `XDG_CONFIG_HOME`。在 v2.1.290 之前，它们还可以设置对话框计时器变量和 `CLAUDE_CODE_DISABLE_ATTACHMENTS`。

3135* Claude Code 的托管环境拥有的身份变量，例如 `CLAUDE_CODE_REMOTE` 和 `CLAUDE_CODE_ACCOUNT_UUID`，从每个文件中被忽略。3137* Claude Code 的托管环境拥有的身份变量，例如 `CLAUDE_CODE_REMOTE` 和 `CLAUDE_CODE_ACCOUNT_UUID`，从每个文件中被忽略。

3136* [`CLAUDE_CODE_MESSAGING_SOCKET` 和 `CLAUDE_CODE_MESSAGING_TOKEN`](/docs/zh-CN/env-vars#variables)，Claude Code 自己导出的，从每个文件中被忽略。忽略套接字变量需要 Claude Code v2.1.224 或更高版本，忽略令牌需要 v2.1.228 或更高版本。3138* [`CLAUDE_CODE_MESSAGING_SOCKET` 和 `CLAUDE_CODE_MESSAGING_TOKEN`](/docs/zh-CN/env-vars#variables)，Claude Code 自己导出的，从每个文件中被忽略。忽略套接字变量需要 Claude Code v2.1.224 或更高版本，忽略令牌需要 v2.1.228 或更高版本。

3137* [`CLAUDE_CODE_PROJECT_DIR_NAME`](/docs/zh-CN/sessions#name-the-project-directory-yourself)，Claude Code 仅从启动环境读取，从每个文件中被忽略；需要 v2.1.234 或更高版本。3139* [`CLAUDE_CODE_PROJECT_DIR_NAME`](/docs/zh-CN/sessions#name-the-project-directory-yourself)，Claude Code 仅从启动环境读取，从每个文件中被忽略；需要 v2.1.234 或更高版本。

3164 `plansDirectory`3166 `plansDirectory`

3165</h3>3167</h3>

3166 3168

3167选择 Claude Code 在[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)中写入的计划文件的存储位置。Claude Code 相对于项目根目录解析路径，当路径解析到项目外时保持默认值。3169选择 Claude Code 在[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)中写入的计划文件的存储位置。Claude Code 相对于项目根目录解析路径。

3168 3170

3169* **Scope**: [`Any file`](#scopes)3171* **Scope**: [`Any file`](#scopes)

3170* **Type**: 字符串，相对于项目根目录的路径3172* **Type**: 字符串，相对于项目根目录的路径

3176}3178}

3177```3179```

3178 3180

3181在以下情况下，Claude Code 会将计划存储在 `~/.claude/plans` 中，而不是您设置的目录中：

3182

3183* **位于项目根目录之外**：路径解析到项目根目录之外，例如 `"../plans"`。

3184* **在 macOS、Linux 和 WSL 上包含反斜杠**：解析后的路径包含反斜杠，例如 Windows 风格的 `"docs\\plans"`。请写成 `"docs/plans"`，它在 Windows 上同样适用。

3185

3179<h3 id="skilllistingbudgetfraction">3186<h3 id="skilllistingbudgetfraction">

3180 `skillListingBudgetFraction`3187 `skillListingBudgetFraction`

3181</h3>3188</h3>

4434在 Claude Code 的生命周期中的某些点（例如在工具调用之前或会话启动时）运行您自己的命令、提示、代理、HTTP 请求或 MCP 工具作为 [hooks](/docs/zh-CN/hooks)；[hooks 参考](/docs/zh-CN/hooks#hook-events) 列出每个事件、其有效负载和其退出代码。每个事件映射到匹配器组列表，每个组列出在匹配器应用时运行的处理程序。4441在 Claude Code 的生命周期中的某些点（例如在工具调用之前或会话启动时）运行您自己的命令、提示、代理、HTTP 请求或 MCP 工具作为 [hooks](/docs/zh-CN/hooks)；[hooks 参考](/docs/zh-CN/hooks#hook-events) 列出每个事件、其有效负载和其退出代码。每个事件映射到匹配器组列表，每个组列出在匹配器应用时运行的处理程序。

4435 4442

4436* **作用域**: [`任何文件`](#scopes)。Hooks 在文件中合并而不是相互替换，来自托管设置的 hooks 无法从其他文件中删除。4443* **作用域**: [`任何文件`](#scopes)。Hooks 在文件中合并而不是相互替换，来自托管设置的 hooks 无法从其他文件中删除。

4437* **类型**: 由 [hook 事件](/docs/zh-CN/hooks#hook-events) 键入的对象；每个值是 `{ "matcher", "hooks" }` 组的数组，其 `hooks` 条目的 `type` 为 `"command"`、`"prompt"`、`"agent"`、`"http"` 或 `"mcp_tool"`4444* **类型**: 以 [hook 事件](/docs/zh-CN/hooks#hook-events) 为键的对象；每个值是 `{ "matcher", "hooks" }` 组的数组，其 `hooks` 条目的 `type` 为 `"command"`、`"prompt"`、`"agent"`、`"http"` 或 `"mcp_tool"`

4438* **默认值**: 未设置，因此没有 hooks 运行4445* **默认值**: 未设置，因此没有 hooks 运行

4439 4446

4440此示例在每个 Bash 工具调用之前运行脚本：4447此示例在每个 Bash 工具调用之前运行脚本：

5416从托管设置向每个用户提供远程 MCP 服务器。用户保留他们自己添加的服务器，无法编辑或删除您提供的服务器。需要 Claude Code v2.1.259 或更高版本。5423从托管设置向每个用户提供远程 MCP 服务器。用户保留他们自己添加的服务器，无法编辑或删除您提供的服务器。需要 Claude Code v2.1.259 或更高版本。

5417 5424

5418* **作用域**: [`Managed`](#scopes)。Claude Code 在用户、项目和本地设置中使用警告删除该密钥，并且不在 Claude Desktop 应用的代码选项卡中读取它（在第三方部署上）或在应用的 Cowork 会话中读取它，其中 Claude Desktop 提供并锁定这些会话的 MCP 服务器。5425* **作用域**: [`Managed`](#scopes)。Claude Code 在用户、项目和本地设置中使用警告删除该密钥，并且不在 Claude Desktop 应用的代码选项卡中读取它（在第三方部署上）或在应用的 Cowork 会话中读取它，其中 Claude Desktop 提供并锁定这些会话的 MCP 服务器。

5419* **类型**: 按服务器名称键入的对象。每个条目都具有 `http` 或 `sse` 服务器的 `.mcp.json` 形状：必需的 `https://` `url`，以及可选的 `headers`、`oauth` 和其他 HTTP 和 SSE 选项。Claude Code 删除验证失败的条目，[条目可以包含的内容](/docs/zh-CN/managed-mcp#what-an-entry-can-contain)列出了条件5426* **类型**: 以服务器名称为键的对象。每个条目都具有 `http` 或 `sse` 服务器的 `.mcp.json` 形状：必需的 `https://` `url`，以及可选的 `headers`、`oauth` 和其他 HTTP 和 SSE 选项。Claude Code 删除验证失败的条目，[条目可以包含的内容](/docs/zh-CN/managed-mcp#what-an-entry-can-contain)列出了条件

5420* **默认值**: 未设置，因此托管设置不提供任何服务器5427* **默认值**: 未设置，因此托管设置不提供任何服务器

5421 5428

5422此示例提供一个名为 `search` 的 HTTP 服务器：5429此示例提供一个名为 `search` 的 HTTP 服务器：

5768 5775

5769在[桌面应用](/docs/zh-CN/desktop#local-sessions-on-managed-devices)中关闭在设备上运行的 Code 会话，用于开发人员应该通过 SSH 在远程机器上工作的部署。在 Code 选项卡中，**本地**环境保留在环境下拉列表中，但呈灰显状态且无法选择，工具提示显示你的组织已关闭它；在 Windows 上，WSL 条目以相同方式呈灰显，尽管 WSL 会话是否在托管设备上运行[由单独管理](/docs/zh-CN/admin-setup#wsl-sessions-in-claude-code-desktop)。新会话默认为第一个[SSH 连接](/docs/zh-CN/desktop#ssh-sessions)（如果已配置），应用拒绝在设备上启动或恢复会话，包括返回同一机器的 SSH 连接。到其他主机的 SSH 会话和云会话不受影响。桌面应用读取此键；终端 CLI 忽略它。需要 Claude Desktop v1.37937.0 或更高版本。5776在[桌面应用](/docs/zh-CN/desktop#local-sessions-on-managed-devices)中关闭在设备上运行的 Code 会话，用于开发人员应该通过 SSH 在远程机器上工作的部署。在 Code 选项卡中，**本地**环境保留在环境下拉列表中，但呈灰显状态且无法选择，工具提示显示你的组织已关闭它；在 Windows 上，WSL 条目以相同方式呈灰显，尽管 WSL 会话是否在托管设备上运行[由单独管理](/docs/zh-CN/admin-setup#wsl-sessions-in-claude-code-desktop)。新会话默认为第一个[SSH 连接](/docs/zh-CN/desktop#ssh-sessions)（如果已配置），应用拒绝在设备上启动或恢复会话，包括返回同一机器的 SSH 连接。到其他主机的 SSH 会话和云会话不受影响。桌面应用读取此键；终端 CLI 忽略它。需要 Claude Desktop v1.37937.0 或更高版本。

5770 5777

5771* **作用域**: [`托管`](#scopes)5778* **作用域**: [`托管`](#scopes)。默认情况下，桌面应用从[一个托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)读取此键。

5772* **类型**: 布尔值；仅 JSON 布尔值 `true` 生效5779* **类型**: 布尔值；仅 JSON 布尔值 `true` 生效

5773 * `true`: 桌面应用不提供设备上的 Code 会话；现有本地会话保留在列表中但无法继续5780 * `true`: 桌面应用不提供设备上的 Code 会话；现有本地会话保留在列表中但无法继续

5774 * `false`: 本地会话保持可用5781 * `false`: 本地会话保持可用

5915 5922

5916将 SSH 连接添加到[桌面](/docs/zh-CN/desktop#pre-configure-ssh-connections-for-your-team)环境下拉列表。管理员使用它向团队分发共享连接。你在托管设置中定义的连接显示为托管，因此用户可以选择它们，但无法在应用中编辑或删除它们。5923将 SSH 连接添加到[桌面](/docs/zh-CN/desktop#pre-configure-ssh-connections-for-your-team)环境下拉列表。管理员使用它向团队分发共享连接。你在托管设置中定义的连接显示为托管，因此用户可以选择它们，但无法在应用中编辑或删除它们。

5917 5924

5918* **作用域**: [`用户或托管`](#scopes)。桌面应用读取此键。5925* **作用域**: [`用户或托管`](#scopes)。桌面应用读取此键。默认情况下，它从[一个托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)读取托管连接。

5919* **类型**: 对象数组，每个都有必需的 `id`、`name` 和 `sshHost` 以及可选的 `sshPort` 和 `sshIdentityFile`5926* **类型**: 对象数组，每个都有必需的 `id`、`name` 和 `sshHost` 以及可选的 `sshPort` 和 `sshIdentityFile`

5920* **默认值**: 未设置5927* **默认值**: 未设置

5921 5928

5939 5946

5940限制[桌面 SSH 会话](/docs/zh-CN/desktop#restrict-which-ssh-hosts-users-can-connect-to)可以连接到的主机。仅桌面应用读取此键；CLI 不读取。模式不区分大小写：`*` 匹配任何主机，`*.example.com` 匹配 `example.com` 和每个子域，其他任何内容都是针对 `~/.ssh/config` 解析后的主机名的精确匹配。空数组关闭 SSH 会话。5947限制[桌面 SSH 会话](/docs/zh-CN/desktop#restrict-which-ssh-hosts-users-can-connect-to)可以连接到的主机。仅桌面应用读取此键；CLI 不读取。模式不区分大小写：`*` 匹配任何主机，`*.example.com` 匹配 `example.com` 和每个子域，其他任何内容都是针对 `~/.ssh/config` 解析后的主机名的精确匹配。空数组关闭 SSH 会话。

5941 5948

5942* **作用域**: [`托管`](#scopes)5949* **作用域**: [`托管`](#scopes)。默认情况下，桌面应用从[一个托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)读取此键。

5943* **类型**: 主机名模式数组5950* **类型**: 主机名模式数组

5944* **默认值**: 未设置，因此允许任何主机5951* **默认值**: 未设置，因此允许任何主机

5945 5952

5951}5958}

5952```5959```

5953 5960

5961桌面应用无法读取为主机列表的值（例如 `true` 或对象）在您更正之前会被视为空数组，但 `null` 除外，它被视为未设置。需要 Claude Desktop v2.26454.0 或更高版本。

5962

5963如果您在优先级最高的源中将 [`managedSourcesBehavior`](#managedsourcesbehavior) 设置为 `"merge"`，桌面应用会合并来自每个[管理员源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)的列表，并允许与其中任意一个列表匹配的主机。如果您在某个源中设置了空数组，对于另一个源列出的主机，SSH 会话仍保持开启。

5964

5954<span id="authentication-and-login" />5965<span id="authentication-and-login" />

5955 5966

5956<h2 id="authentication-and-providers">5967<h2 id="authentication-and-providers">

setup.md +12 −8

Details

63 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd63 curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

64 ```64 ```

65 65

66 安装程序完成后，打开一个新的终端窗口并运行 `claude --version`。正常的安装会打印一个版本号。如果您的 shell 显示找不到 `claude` 或无法识别，说明安装目录还不在您的 PATH 中：请参阅[修复您的 PATH](/docs/zh-CN/troubleshoot-install#command-not-found-claude-after-installation)。66 安装命令在下载 Claude Code 期间不会显示进度。安装程序完成后，打开一个新的终端窗口并运行 `claude --version`。正常的安装会打印一个版本号。如果您的 shell 显示找不到 `claude` 或无法识别，说明安装目录还不在您的 PATH 中：请参阅[修复您的 PATH](/docs/zh-CN/troubleshoot-install#command-not-found-claude-after-installation)。

67 67

68 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。68 如果您看到 `The token '&&' is not a valid statement separator`，说明您在 PowerShell 中，而不是 CMD。如果您看到 `'irm' is not recognized as an internal or external command`，说明您在 CMD 中，而不是 PowerShell。

69 69

119 119

120| 选项 | 需要 | [沙箱](/docs/zh-CN/sandboxing) | 何时使用 |120| 选项 | 需要 | [沙箱](/docs/zh-CN/sandboxing) | 何时使用 |

121| - | - | - | - |121| - | - | - | - |

122| 原生 Windows | 无；[Git for Windows](https://git-scm.com/downloads/win) 是可选的 | 不支持 | Windows 原生项目和工具 |122| [原生 Windows](#install-on-native-windows) | 无；[Git for Windows](https://git-scm.com/downloads/win) 是可选的 | 不支持 | Windows 原生项目和工具 |

123| WSL 2 | WSL 2 已启用 | 支持 | Linux 工具链或沙箱命令执行 |123| [WSL 2](#install-in-wsl) | WSL 2 已启用 | 支持 | Linux 工具链或沙箱命令执行 |

124| WSL 1 | WSL 1 已启用 | 不支持 | 如果 WSL 2 不可用 |124| [WSL 1](#install-in-wsl) | WSL 1 已启用 | 不支持 | 如果 WSL 2 不可用 |

125 125

126**选项 1：原生 Windows**126<h4 id="install-on-native-windows">

127 在原生 Windows 上安装

128</h4>

127 129

128从 PowerShell 或 CMD 运行安装命令。您无需以管理员身份运行。安装 [Git for Windows](https://git-scm.com/downloads/win) 是可选的。它提供 Git Bash，[Bash 工具](/docs/zh-CN/tools-reference#bash-tool-behavior)和 [Monitor 工具](/docs/zh-CN/tools-reference#monitor-tool)需要用到它。130从 PowerShell 或 CMD 运行[安装命令](#install-claude-code)。您无需以管理员身份运行。安装 [Git for Windows](https://git-scm.com/downloads/win) 是可选的。它提供 Git Bash，[Bash 工具](/docs/zh-CN/tools-reference#bash-tool-behavior)和 [Monitor 工具](/docs/zh-CN/tools-reference#monitor-tool)需要用到它。

129 131

130无论您从 PowerShell 还是 CMD 安装，只会影响您运行的安装命令。您的提示在 PowerShell 中显示为 `PS C:\Users\YourName>`，在 CMD 中显示为 `C:\Users\YourName>`（不带 `PS`）。如果您是终端新手，[终端指南](/docs/zh-CN/terminal-guide#windows)会逐步讲解每个步骤。132无论您从 PowerShell 还是 CMD 安装，只会影响您运行的安装命令。您的提示在 PowerShell 中显示为 `PS C:\Users\YourName>`，在 CMD 中显示为 `C:\Users\YourName>`（不带 `PS`）。如果您是终端新手，[终端指南](/docs/zh-CN/terminal-guide#windows)会逐步讲解每个步骤。

131 133

144 146

145安装 Git for Windows 后，PowerShell 工具可与 Bash 一起使用：在 claude.ai 和 Console 账户上默认启用，在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 会话中使用 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` 启用。将其设置为 `0` 以关闭该工具。有关设置和限制，请参阅 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)。147安装 Git for Windows 后，PowerShell 工具可与 Bash 一起使用：在 claude.ai 和 Console 账户上默认启用，在 Amazon Bedrock、Google Cloud 的 Agent Platform 和 Microsoft Foundry 会话中使用 `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` 启用。将其设置为 `0` 以关闭该工具。有关设置和限制，请参阅 [PowerShell 工具](/docs/zh-CN/tools-reference#powershell-tool)。

146 148

147**选项 2：WSL**149<h4 id="install-in-wsl">

150 在 WSL 中安装

151</h4>

148 152

149打开您的 WSL 发行版并从上面的[安装说明](#install-claude-code)中运行 Linux 安装程序。您在 WSL 终端内安装和启动 `claude`，而不是从 PowerShell 或 CMD。153打开您的 WSL 发行版并按照[安装说明](#install-claude-code)运行 Linux 安装程序。您在 WSL 终端内安装和启动 `claude`，而不是从 PowerShell 或 CMD。

150 154

151<h3 id="alpine-linux-and-musl-based-distributions">155<h3 id="alpine-linux-and-musl-based-distributions">

152 Alpine Linux 和基于 musl 的发行版156 Alpine Linux 和基于 musl 的发行版

skills.md +15 −0

Details

36 36

37捆绑技能与内置命令一起列在[命令参考](/docs/zh-CN/commands)中，在"目的"列中标记为**技能**。37捆绑技能与内置命令一起列在[命令参考](/docs/zh-CN/commands)中，在"目的"列中标记为**技能**。

38 38

39<h3 id="check-your-setup-with-/doctor">

40 使用 `/doctor` 检查您的设置

41</h3>

43在 Claude Code 输入框中运行 `/doctor`，进行设置检查，诊断问题并可以修复它们。Claude 会先报告其发现，并在更改任何内容之前请求确认。检查涵盖以下方面：

45* **安装健康状况**：重复或残留的安装、`PATH` 问题、无法解析的设置文件，以及您的[发布渠道](/docs/zh-CN/setup#configure-release-channel)上是否有更新版本可用

46* **扩展**：未使用的 skill、MCP 服务器和插件与其上下文成本的对比，以及缓慢的 [hook](/docs/zh-CN/hooks)

47* **`CLAUDE.md` 文件**：与已签入文件重复的本地 `CLAUDE.md` 文件、已签入的 [Claude 可以从代码库推导出的 `CLAUDE.md` 内容](/docs/zh-CN/memory#my-claude-md-is-too-large)，以及其余始终加载的指导内容，Claude 会提议将其迁移到按需加载的 skill 和嵌套 `CLAUDE.md` 文件中

48* **权限**：提议将[自动模式](/docs/zh-CN/permissions#permission-modes)设为您的默认权限模式，并[预先批准](/docs/zh-CN/permissions)您经常拒绝的只读命令

50如需在不启动会话的情况下进行只读安装诊断，请改为在终端中运行 `claude doctor`。

52要审核您的指令而不是您的设置，请在 Claude Code 输入框中运行 `/doctor prompt-audit`。Claude 会[检查您的 `CLAUDE.md` 文件、skill 和其他配置](/docs/zh-CN/memory#audit-your-instruction-files)中是否存在过时或相互冲突的指令，而不是运行设置检查。`prompt-audit` 子命令需要 Claude Code v2.1.283 或更高版本。

39<h3 id="run-and-verify-your-app">54<h3 id="run-and-verify-your-app">

40 运行并验证您的应用55 运行并验证您的应用

41</h3>56</h3>

statusline.md +105 −56

Details

143</Steps>143</Steps>

144 144

145<h2 id="how-status-lines-work">145<h2 id="how-status-lines-work">

146 状态行如何工作146 状态栏如何工作

147</h2>147</h2>

148 148

149Claude Code 运行你的脚本，通过 stdin 向其传输 [JSON 会话数据](#available-data)，并显示脚本打印到 stdout 的任何内容。149Claude Code 运行您的脚本，通过 stdin 向其传输 [JSON 会话数据](#available-data)，并显示脚本打印到 stdout 的任何内容。

150 150

151**何时更新**151<Note>状态栏在本地运行，不消耗 API token。在某些 UI 交互期间，它会临时隐藏，包括帮助菜单和权限提示。</Note>

152 152

153你的脚本在会话启动时运行一次，包括当你恢复一个会话时。之后，它在以下情况下再次运行：153<h3 id="when-the-status-line-updates">

154 状态栏何时更新

155</h3>

156

157脚本在会话启动时运行一次，包括恢复会话时。之后，它在以下情况下再次运行：

154 158

155* 新的助手消息到达159* 新的助手消息到达

156* `/compact` 完成160* `/compact` 完成

157* 权限模式更改161* 权限模式更改

158* Vim 模式切换162* Vim 模式切换

159* 你在 `statusLine` 设置中更改 `command`163* 您在 `statusLine` 设置中更改 `command`

160* 如果你设置了 [`refreshInterval`](#manually-configure-a-status-line)，计时器会经过164* 如果您设置了 [`refreshInterval`](#manually-configure-a-status-line)，其计时器到期

161* 你的脚本最后接收的数据中的 [速率限制窗口](#rate-limit-usage) 到达其 `resets_at` 时间165* 脚本最后接收的数据中的[速率限制窗口](#rate-limit-usage)到达其 `resets_at` 时间

162* 你的脚本最后接收的数据中的 [预热提示缓存](#prompt-cache-fields) 到达其 `expires_at` 时间166* 脚本最后接收的数据中的预热[提示词缓存](#prompt-cache-fields)到达其 `expires_at` 时间

163 167

164Claude Code 在 300ms 处对更新进行防抖，因此快速更改会批处理在一起，你的脚本在更改停止后运行一次。对 `command` 本身的更改会跳过防抖：Claude Code 立即运行新命令。如果在你的脚本仍在运行时触发新的更新，Claude Code 会取消正在进行的脚本。如果你编辑你的脚本，更改会在下次更新触发重新运行它时出现。168Claude Code 以 300ms 对更新进行防抖，因此快速更改会批处理在一起，脚本在更改停止后运行一次。对 `command` 本身的更改会跳过防抖：Claude Code 立即运行新命令。如果在脚本仍在运行时触发新的更新，Claude Code 会取消正在进行的脚本。如果您编辑了脚本，更改会在下次更新触发重新运行它时出现。

165 169

166当主会话空闲时，事件驱动的触发器可能会安静，例如当协调器等待后台子代理时。为了在空闲期间保持基于时间或外部来源的段的最新状态，设置 [`refreshInterval`](#manually-configure-a-status-line) 以也在固定计时器上重新运行命令。170当主会话空闲时，事件驱动的触发器可能会停止触发，例如当协调器等待后台子代理时。为了在空闲期间保持基于时间或外部来源的片段为最新状态，请设置 [`refreshInterval`](#manually-configure-a-status-line)，以便同时按固定计时器重新运行命令。

171

172<h3 id="what-your-script-can-output">

173 脚本可以输出什么

174</h3>

167 175

168**你的脚本可以输出什么**176脚本可以打印的不仅仅是单行纯文本：

169 177

170* **多行**：每个 `echo` 或 `print` 语句显示为单独的行。请参阅[多行示例](#display-multiple-lines)。178* **多行**：每个 `echo` 或 `print` 语句显示为单独的行。请参阅[多行示例](#display-multiple-lines)。

171* **颜色**：使用 [ANSI 转义码](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors)，如 `\033[32m` 表示绿色（终端必须支持它们）。请参阅 [git 状态示例](#git-status-with-colors)。179* **颜色**：使用 [ANSI 转义码](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors)，如 `\033[32m` 表示绿色（终端必须支持它们）。请参阅 [git 状态示例](#git-status-with-colors)。

172* **链接**：使用 [OSC 8 转义序列](https://en.wikipedia.org/wiki/ANSI_escape_code#OSC) 使文本可点击（macOS 上为 Cmd+click，Windows/Linux 上为 Ctrl+click）。需要支持超链接的终端，如 iTerm2、Kitty 或 WezTerm。请参阅[可点击链接示例](#clickable-links)。180* **链接**：使用 [OSC 8 转义序列](https://en.wikipedia.org/wiki/ANSI_escape_code#OSC) 使文本可点击（macOS 上为 Cmd+click，Windows/Linux 上为 Ctrl+click）。需要支持超链接的终端，如 iTerm2、Kitty 或 WezTerm。请参阅[可点击链接示例](#clickable-links)。

173 181

174**调整输出大小以适应终端**182<h3 id="size-output-to-the-terminal">

~~175~~ 183 调整输出大小以适应终端

176Claude Code 捕获你的脚本输出而不是直接将其连接到终端，因此 `tput cols` 和语言级宽度检测无法从脚本内部读取终端大小。改为读取 `COLUMNS` 和 `LINES` 环境变量。Claude Code 在运行你的脚本之前将这些设置为当前终端尺寸。184</h3>

177 185

178<Note>状态行在本地运行，不消耗 API 令牌。在某些 UI 交互期间，它会临时隐藏，包括帮助菜单和权限提示。</Note>186Claude Code 捕获脚本的输出而不是直接将其连接到终端，因此 `tput cols` 和语言级宽度检测无法从脚本内部读取终端大小。请改为读取 `COLUMNS` 和 `LINES` 环境变量。Claude Code 在运行脚本之前会将这些变量设置为当前终端尺寸。

179 187

180<h2 id="available-data">188<h2 id="available-data">

181 可用数据189 可用数据

1168}1176}

1169```1177```

1170 1178

1171该命令在每个刷新周期运行一次，所有可见的子代理行作为单个 JSON 对象传递到 stdin。输入包括[基本钩子字段](/docs/zh-CN/hooks#common-input-fields)、`columns` 字段（可用行宽）和 `tasks` 数组。每个任务有 `id`、`name`、`type`、`status`、`description`、`label`、`startTime`、`model`、`effort`、`contextWindowSize`、`tokenCount`、`tokenSamples` 和 `cwd`。1179该命令在每个刷新周期运行一次，所有可见的子代理行作为单个 JSON 对象通过 stdin 传入。输入包括[基本 hook 字段](/docs/zh-CN/hooks#common-input-fields)、表示可用行宽的 `columns` 字段，以及每行对应一个条目的 `tasks` 数组，详见[任务字段](#task-fields)。

~~1172~~

1173每个任务的 `model` 字段是任务运行的已解析模型 ID。`contextWindowSize` 是该模型的上下文窗口（以令牌计），计算方式与主状态行的 `context_window.context_window_size` 相同，因此你可以从 `tokenCount` 呈现每行百分比。这两个字段需要 Claude Code v2.1.205 或更高版本，对于模型尚未解析的任务会被省略。

~~1174~~

1175每个任务的 `effort` 字段是为该子代理设置的推理 effort，在其[定义 frontmatter](/docs/zh-CN/sub-agents#supported-frontmatter-fields) 中或在单次调用时设置。该值要么是 effort 级别字符串 `low`、`medium`、`high`、`xhigh` 或 `max` 之一，要么是数字 token 预算。该字段按原样报告所配置的值：如果模型不支持该级别，Claude Code 实际应用的 effort 可能会有所不同。该字段需要 Claude Code v2.1.214 或更高版本，当未为该子代理设置级别时不存在。

1176 1180

1177将一个 JSON 行写入 stdout，用于你想覆盖的每一行，形式为 `{"id": "<task id>", "content": "<row body>"}` 。`content` 字符串按原样呈现，包括 ANSI 颜色和 OSC 8 超链接。省略任务的 `id` 以保持该行的默认呈现；发出空 `content` 字符串以隐藏它。1181将一个 JSON 行写入 stdout，用于你想覆盖的每一行，形式为 `{"id": "<task id>", "content": "<row body>"}` 。`content` 字符串按原样呈现，包括 ANSI 颜色和 OSC 8 超链接。省略任务的 `id` 以保持该行的默认呈现；发出空 `content` 字符串以隐藏它。

1178 1182

1179适用于 `statusLine` 的相同信任、`disableAllHooks` 和 [`allowManagedHooksOnly`](/docs/zh-CN/settings-reference#allowmanagedhooksonly) 门控也适用于此处。插件可以在其[`settings.json`](/docs/zh-CN/plugins/manifest-reference#standard-layout)中提供默认的 `subagentStatusLine`，但与钩子不同，即使插件在托管设置 `enabledPlugins` 中被强制启用，插件值也不会在 `allowManagedHooksOnly` 下运行。1183适用于 `statusLine` 的相同信任、`disableAllHooks` 和 [`allowManagedHooksOnly`](/docs/zh-CN/settings-reference#allowmanagedhooksonly) 门控也适用于此处。插件可以在其[`settings.json`](/docs/zh-CN/plugins/manifest-reference#standard-layout)中提供默认的 `subagentStatusLine`，但与钩子不同，即使插件在托管设置 `enabledPlugins` 中被强制启用，插件值也不会在 `allowManagedHooksOnly` 下运行。

1180 1184

1185<h3 id="task-fields">

1186 任务字段

1187</h3>

1188

1189`tasks` 数组中的每个条目使用以下字段描述一个子代理行。标记为可选的字段在没有值时会被省略，因此请在脚本中处理其缺失的情况。

1190

1191| 字段 | 类型 | 描述 |

1192| :- | :- | :- |

1193| `id` | string | 任务的标识符。在为该行写回的行中将其作为 `id` 原样返回 |

1194| `name` | string，可选 | 子代理的[称呼名称](/docs/zh-CN/sub-agents#subagent-names)（如果有） |

1195| `type` | string | 任务类型：`local_agent` |

1196| `agentType` | string | 任务运行所用的子代理类型，例如内置的 [`Explore`](/docs/zh-CN/sub-agents#built-in-subagents) 或自定义的 `code-reviewer`。其值与 hook 接收到的 [`agent_type`](/docs/zh-CN/hooks#subagentstart) 相同。需要 Claude Code v2.1.293 或更高版本 |

1197| `status` | string | 任务状态，例如 `running`、`completed`、`failed` 或 `killed` |

1198| `description` | string | 任务的简短描述，例如 Claude 在生成该子代理时给出的描述 |

1199| `label` | string | Claude Code 提供的任务简短进度摘要（如果有），否则与 `description` 文本相同 |

1200| `startTime` | number | 任务开始时间，以自 Unix 纪元以来的毫秒数表示 |

1201| `model` | string，可选 | 任务运行所用的已解析模型 ID。在模型解析之前省略。需要 Claude Code v2.1.205 或更高版本 |

1202| `effort` | string 或 number，可选 | 在子代理的[定义 frontmatter](/docs/zh-CN/sub-agents#supported-frontmatter-fields) 中或单次调用时为其设置的推理 effort：`low`、`medium`、`high`、`xhigh`、`max` 或数字 token 预算。这是所配置的值，当模型不支持该级别时，Claude Code 实际应用的 effort 可能会有所不同。未设置 effort 时省略。需要 Claude Code v2.1.213 或更高版本 |

1203| `contextWindowSize` | number，可选 | `model` 的上下文窗口（以 token 计），计算方式与主状态栏的 [`context_window.context_window_size`](#context-window-fields) 相同，因此您可以根据 `tokenCount` 渲染每行百分比。当 `model` 被省略时也会省略。需要 Claude Code v2.1.205 或更高版本 |

1204| `tokenCount` | number | 子代理的累计 token 数，即默认行中显示的数值 |

1205| `tokenSamples` | array of numbers | 最近最多 16 个 `tokenCount` 读数，每个刷新周期一个，按从旧到新排列，最后一个为当前值 |

1206| `cwd` | string | 子代理的工作目录：如果子代理在自己的目录（例如隔离的 worktree）中运行，则为该目录，否则为会话的工作目录 |

1207

1181<h2 id="tips">1208<h2 id="tips">

1182 提示1209 提示

1183</h2>1210</h2>

1192 故障排除1219 故障排除

1193</h2>1220</h2>

1194 1221

1195**状态行未出现**1222如果状态栏为空白，请先查看[状态栏未出现](#status-line-not-appearing)。尚未信任的文件夹以及运行失败的脚本也会导致状态栏为空白，具体请参见[需要工作区信任](#workspace-trust-required)和[脚本错误或挂起](#script-errors-or-hangs)。

1196 1223

1197* 验证你的脚本是可执行的：`chmod +x ~/.claude/statusline.sh`1224<h3 id="status-line-not-appearing">

1198* 检查你的脚本输出到 stdout，而不是 stderr1225 状态栏未出现

1199* 手动运行你的脚本以验证它产生输出1226</h3>

1200* 在安装了 Git Bash 的 Windows 上，`command` 路径中的反斜杠可能在脚本运行前被当作转义字符消耗。在路径中使用正斜杠。参见 [Windows 配置](#windows-configuration)。

1201* 如果在应用 [设置优先级](/docs/zh-CN/hooks#disable-or-remove-hooks) 后 `disableAllHooks` 在托管设置之外为 `true`，Claude Code 仅运行来自托管设置的 `statusLine`，如果没有托管 `statusLine`，状态行将被禁用。删除该设置，或在设置它的文件中将其设置为 `false` 以重新启用。参见 [`disableAllHooks`](/docs/zh-CN/settings-reference#disableallhooks)。

1202* 如果你的组织在托管设置中设置了 `allowManagedHooksOnly`，你的自定义状态行会无警告地消失：你只能从那些托管设置中的 `statusLine` 值获得状态行。参见 [在 `allowManagedHooksOnly` 下运行的内容](/docs/zh-CN/settings-reference#what-runs-under-allowmanagedhooksonly) 了解完整行为，并询问你的管理员此设置是否适用于你。

1203* 运行 `claude --debug` 以在每次状态行调用时记录你的脚本的 stderr，以及在会话中第一次调用时的退出代码

1204* 要求 Claude 读取你的设置文件并直接执行 `statusLine` 命令以显示错误

1205 1227

~~1206**状态行显示 `--` 或空值**~~1228如果您已配置状态栏，但界面底部没有任何显示，请逐项进行以下检查：

1207 1229

1208* 在第一次 API 响应完成之前，字段可能为 `null`1230* 验证您的脚本是可执行的：`chmod +x ~/.claude/statusline.sh`

1209* 在你的脚本中使用回退处理 null 值，如 jq 中的 `// 0`1231* 检查您的脚本输出到 stdout，而不是 stderr

1210* 如果值在多条消息后仍然为空，请重新启动 Claude Code1232* 手动运行您的脚本以验证它产生输出

1233* 在安装了 Git Bash 的 Windows 上，`command` 路径中的反斜杠可能在脚本运行前被当作转义字符消耗。请在路径中使用正斜杠。参见 [Windows 配置](#windows-configuration)。

1234* 如果在应用[设置优先级](/docs/zh-CN/hooks#disable-or-remove-hooks)后 `disableAllHooks` 在托管设置之外为 `true`，Claude Code 仅运行来自托管设置的 `statusLine`，如果没有托管 `statusLine`，状态栏将被禁用。删除该设置，或在设置它的文件中将其设置为 `false` 以重新启用。参见 [`disableAllHooks`](/docs/zh-CN/settings-reference#disableallhooks)。

1235* 如果您的组织在托管设置中设置了 `allowManagedHooksOnly`，您的自定义状态栏会无警告地消失：您只能从那些托管设置中的 `statusLine` 值获得状态栏。参见[在 `allowManagedHooksOnly` 下运行的内容](/docs/zh-CN/settings-reference#what-runs-under-allowmanagedhooksonly)了解完整行为，并询问您的管理员此设置是否适用于您。

1236* 运行 `claude --debug` 以在每次状态栏调用时记录您的脚本的 stderr，以及在会话中第一次调用时的退出码

1237* 要求 Claude 读取您的设置文件并直接执行 `statusLine` 命令以显示错误

1211 1238

1212**上下文百分比显示意外值**1239<h3 id="status-line-shows-or-empty-values">

1240 状态栏显示 `--` 或空值

1241</h3>

1213 1242

1214* 使用 `used_percentage` 获得最简单的准确上下文状态1243在第一次 API 响应完成之前，字段可能为 `null`，因此请在脚本中使用回退处理 null 值，如 jq 中的 `// 0`。如果值在多条消息后仍然为空，请重新启动 Claude Code。

1215* 状态行报告来自最后一次 API 响应的计数，而 `/context` 添加了自该响应以来添加的消息的估计值，因此 `/context` 可以读取更高的值，直到下一次响应

1216 1244

1217**OSC 8 链接不可点击**1245<h3 id="context-percentage-shows-unexpected-values">

1246 上下文百分比显示意外值

1247</h3>

1248

1249状态栏报告来自最后一次 API 响应的计数，而 `/context` 添加了自该响应以来新增消息的估计值，因此在下一次响应之前，`/context` 的读数可能更高。使用 `used_percentage` 获得最简单的准确上下文状态。有关 `used_percentage` 背后的计算公式，请参见[上下文窗口字段](#context-window-fields)。

1250

1251<h3 id="osc-8-links-not-clickable">

1252 OSC 8 链接不可点击

1253</h3>

1254

1255链接是否可点击取决于您的终端、Claude Code 是否在其中检测到超链接支持、SSH 或 tmux 是否剥离了转义序列，以及您的脚本如何打印它：

1218 1256

1219* 验证你的终端支持 OSC 8 超链接（iTerm2、Kitty、WezTerm）1257* 验证您的终端支持 OSC 8 超链接（iTerm2、Kitty、WezTerm）

1220 1258

1221* Terminal.app 不支持可点击链接1259* Terminal.app 不支持可点击链接

1222 1260

1223* 如果链接文本出现但不可点击，Claude Code 可能未检测到你的终端中的超链接支持。在启动 Claude Code 之前设置 `FORCE_HYPERLINK` 环境变量以覆盖检测：1261* 如果链接文本出现但不可点击，Claude Code 可能未检测到您的终端中的超链接支持。在启动 Claude Code 之前设置 `FORCE_HYPERLINK` 环境变量以覆盖检测：

1224 1262

1225 ```bash theme={null}1263 ```bash theme={null}

1226 FORCE_HYPERLINK=1 claude1264 FORCE_HYPERLINK=1 claude

1234 1272

1235* SSH 和 tmux 会话可能根据配置剥离 OSC 序列1273* SSH 和 tmux 会话可能根据配置剥离 OSC 序列

1236 1274

1237* 如果转义序列显示为文字文本，如 `\e]8;;`，使用 `printf '%b'` 而不是 `echo -e` 以获得更可靠的转义处理1275* 如果转义序列显示为文字文本，如 `\e]8;;`，请使用 `printf '%b'` 而不是 `echo -e` 以获得更可靠的转义处理

1276

1277<h3 id="display-glitches-with-escape-sequences">

1278 转义序列显示故障

1279</h3>

1280

1281复杂的转义序列（ANSI 颜色、OSC 8 链接）如果与其他 UI 更新重叠，偶尔会导致输出混乱。带有转义码的多行状态栏比单行纯文本更容易出现渲染问题。

1282

1283如果您看到损坏的文本，请尝试将脚本简化为纯文本输出。

1238 1284

1239**转义序列显示故障**1285<h3 id="workspace-trust-required">

1286 需要工作区信任

1287</h3>

1240 1288

1241* 复杂的转义序列（ANSI 颜色、OSC 8 链接）如果与其他 UI 更新重叠，偶尔会导致输出混乱1289在您接受工作区信任对话框之前，状态栏会保持空白。因为 `statusLine` 执行 shell 命令，Claude Code 在与[设置文件中的 hook 相同的工作区信任规则](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder)下运行它。接受该文件夹的对话框，或接受其信任扩展到它的父目录，就足够了。

1242* 如果你看到损坏的文本，尝试简化你的脚本为纯文本输出

1243* 带有转义码的多行状态行比单行纯文本更容易出现渲染问题

1244 1290

1245**工作区信任需要**1291在此之前，`claude --debug` 会记录 `Status line command skipped: workspace trust not accepted`。重新启动 Claude Code 并接受信任对话框以启用它。

1246 1292

1247* 因为 `statusLine` 执行 shell 命令，Claude Code 在与 [设置文件中的 hooks 相同的工作区信任规则](/docs/zh-CN/permissions#what-runs-before-you-trust-a-folder) 下运行它。接受该文件夹的对话框，或接受其信任扩展到它的父目录，就足够了。1293<h3 id="script-errors-or-hangs">

1248* 在此之前，状态行保持空白，`claude --debug` 记录 `Status line command skipped: workspace trust not accepted`。重新启动 Claude Code 并接受信任对话框以启用它。1294 脚本错误或挂起

1295</h3>

1249 1296

1250**脚本错误或挂起**1297Claude Code 仅在脚本以代码 0 退出后才显示其输出：

1251 1298

1252* 以非零代码退出或不产生输出的脚本会导致状态行变为空白1299* 以非零代码退出或不产生输出的脚本会导致状态栏变为空白

1253* 慢速脚本会阻止状态行更新，直到它们完成。保持脚本快速以避免陈旧输出。1300* 慢速脚本会阻止状态栏更新，直到它们完成。保持脚本快速以避免陈旧输出。

1254* 如果在慢速脚本运行时触发新的更新，正在进行的脚本会被取消1301* 如果在慢速脚本运行时触发新的更新，正在进行的脚本会被取消

1255* 在配置之前使用模拟输入独立测试你的脚本1302* 在配置之前使用模拟输入独立测试您的脚本

1256 1303

1257**通知共享状态行行**1304<h3 id="notifications-share-the-status-line-row">

1305 通知与状态栏共享同一行

1306</h3>

1258 1307

1259在 [全屏渲染](/docs/zh-CN/fullscreen) 之外，Claude Code 在与你的状态行相同的行上显示通知。在全屏渲染中，Claude Code 为通知提供自己的行。1308在[全屏渲染](/docs/zh-CN/fullscreen)之外，Claude Code 在与您的状态栏相同的行上显示通知。在全屏渲染中，Claude Code 会为通知提供单独的一行。

1260 1309

1261* 系统通知，如 MCP 服务器错误和自动更新，显示在行的右侧。临时通知，如上下文低警告，也会循环通过此区域。1310* 系统通知，如 MCP 服务器错误和自动更新，显示在该行的右侧。临时通知，如上下文不足警告，也会在此区域轮流显示。

1262* 启用详细模式会向此区域添加令牌计数器1311* 启用详细模式会向此区域添加 token 计数器

1263* 在窄终端上，这些通知可能会截断你的状态行输出1312* 在窄终端上，这些通知可能会截断您的状态栏输出

sub-agents.md +12 −2

Details

323| `memory` | 否 | [Persistent memory scope](#enable-persistent-memory)：`user`、`project` 或 `local`。启用跨会话学习 |323| `memory` | 否 | [Persistent memory scope](#enable-persistent-memory)：`user`、`project` 或 `local`。启用跨会话学习 |

324| `background` | 否 | 设置为 `true` 以即使 Claude 要求在前台运行也保持此 subagent 在后台。其中 [fork mode](#turn-fork-mode-on-or-off) 打开时，Claude Code 已经在 [background](#run-subagents-in-foreground-or-background) 中运行 Claude 生成的 subagents |324| `background` | 否 | 设置为 `true` 以即使 Claude 要求在前台运行也保持此 subagent 在后台。其中 [fork mode](#turn-fork-mode-on-or-off) 打开时，Claude Code 已经在 [background](#run-subagents-in-foreground-or-background) 中运行 Claude 生成的 subagents |

325| `omitClaudeMd` | 否 | 设置为 `true` 以启动此 subagent 而不使用用户、项目和本地 CLAUDE.md 文件；[managed policy files](/docs/zh-CN/memory#how-claude-md-files-load) 仍然加载，除了 [managed subagents](#choose-the-subagent-scope)。对于从 [delegation prompt](#what-loads-at-startup) 获取所需一切的 subagents 使用它。当代理通过 `--agent` 或 `agent` 设置作为主会话代理运行时被忽略。需要 Claude Code v2.1.271 或更高版本 |325| `omitClaudeMd` | 否 | 设置为 `true` 以启动此 subagent 而不使用用户、项目和本地 CLAUDE.md 文件；[managed policy files](/docs/zh-CN/memory#how-claude-md-files-load) 仍然加载，除了 [managed subagents](#choose-the-subagent-scope)。对于从 [delegation prompt](#what-loads-at-startup) 获取所需一切的 subagents 使用它。当代理通过 `--agent` 或 `agent` 设置作为主会话代理运行时被忽略。需要 Claude Code v2.1.271 或更高版本 |

326| `effort` | 否 | 此子代理活跃时的 effort 级别。覆盖会话的 effort 级别，但不覆盖 [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars#variables) 环境变量。选项：`low`、`medium`、`high`、`xhigh`、`max`；可用级别取决于模型 |326| `effort` | 否 | 此子代理活跃时的 effort 级别。覆盖会话的 effort 级别，但不覆盖 [`CLAUDE_CODE_EFFORT_LEVEL`](/docs/zh-CN/env-vars#variables) 环境变量。选项：`low`、`medium`、`high`、`xhigh`、`max`；可用级别取决于模型。请参阅[选择 effort 级别](#choose-an-effort-level) |

327| `isolation` | 否 | 设置为 `worktree` 以在临时 [git worktree](/docs/zh-CN/worktrees) 中运行 subagent，为其提供存储库的隔离副本，默认从您的 [default branch](/docs/zh-CN/worktrees#choose-the-base-branch) 分支，而不是父会话的 `HEAD`。如果 subagent 不进行任何更改，worktree 会自动清理 |327| `isolation` | 否 | 设置为 `worktree` 以在临时 [git worktree](/docs/zh-CN/worktrees) 中运行 subagent，为其提供存储库的隔离副本，默认从您的 [default branch](/docs/zh-CN/worktrees#choose-the-base-branch) 分支，而不是父会话的 `HEAD`。如果 subagent 不进行任何更改，worktree 会自动清理 |

328| `color` | 否 | Subagent 在任务列表和转录中的显示颜色。接受 `red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink` 或 `cyan` |328| `color` | 否 | Subagent 在任务列表和转录中的显示颜色。接受 `red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink` 或 `cyan` |

329| `initialPrompt` | 否 | 当此代理作为主会话代理运行时（通过 `--agent` 或 `agent` 设置），自动提交为第一个用户轮次。[Commands](/docs/zh-CN/commands) 和 [skills](/docs/zh-CN/skills) 被处理。前置于任何用户提供的提示。对于 [plugin subagents](#choose-the-subagent-scope) 被忽略 |329| `initialPrompt` | 否 | 当此代理作为主会话代理运行时（通过 `--agent` 或 `agent` 设置），自动提交为第一个用户轮次。[Commands](/docs/zh-CN/commands) 和 [skills](/docs/zh-CN/skills) 被处理。前置于任何用户提供的提示。对于 [plugin subagents](#choose-the-subagent-scope) 被忽略 |

3793. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/zh-CN/model-config#environment-variables) 环境变量，当您将其设置为模型别名或模型 ID 时3793. [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/zh-CN/model-config#environment-variables) 环境变量，当您将其设置为模型别名或模型 ID 时

3804. 主对话的模型3804. 主对话的模型

381 381

382如果已安装的 [mod](/docs/zh-CN/plugins/mods/overview) 在其 [`agent.spawn`](/docs/zh-CN/plugins/mods/reference#subagents) hook 中设置了模型，Claude Code 会使用该模型来代替每次调用的参数。

383

382在两种情况下，家族别名（例如 frontmatter 或每次调用的参数中的 `opus`）解析到主对话的模型，而不是 [alias points to](/docs/zh-CN/model-config#model-aliases) 的版本：384在两种情况下，家族别名（例如 frontmatter 或每次调用的参数中的 `opus`）解析到主对话的模型，而不是 [alias points to](/docs/zh-CN/model-config#model-aliases) 的版本：

383 385

384* **主对话的模型属于该家族**：subagent 在主对话的确切模型上运行，包括任何 `[1m]` 后缀，因此它获得与主对话相同的 [extended context](/docs/zh-CN/model-config#extended-context) 窗口。386* **主对话的模型属于该家族**：subagent 在主对话的确切模型上运行，包括任何 `[1m]` 后缀，因此它获得与主对话相同的 [extended context](/docs/zh-CN/model-config#extended-context) 窗口。

399 401

400在交互式会话中，Claude Code 显示一个警告，命名请求的模型和 subagent 运行的模型，对于任一替换。402在交互式会话中，Claude Code 显示一个警告，命名请求的模型和 subagent 运行的模型，对于任一替换。

401 403

402要检查 subagent 运行的模型，运行 [`/tasks`](/docs/zh-CN/commands)。Claude Code 在 subagent 的行上命名模型，并在 subagent 的定义或它分叉的技能设置 [`effort`](#supported-frontmatter-fields) 时添加 [effort level](/docs/zh-CN/model-config#adjust-effort-level)。需要 Claude Code v2.1.242 或更高版本。404要检查子代理运行在哪个模型上，请运行 [`/tasks`](/docs/zh-CN/commands)。Claude Code 会在子代理所在行显示模型名称，并在为该子代理设置了 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)时一并显示。需要 Claude Code v2.1.242 或更高版本。

403 405

404每次调用的 `model` 参数也适用于 subagent 何时 [resumed or sent a follow-up message](#resume-subagents)，因此 subagent 保持在该模型上。在 v2.1.211 之前，恢复删除了每次调用的值，subagent 恢复到其定义的 `model` 字段或，没有一个，主对话的模型。406每次调用的 `model` 参数也适用于 subagent 何时 [resumed or sent a follow-up message](#resume-subagents)，因此 subagent 保持在该模型上。在 v2.1.211 之前，恢复删除了每次调用的值，subagent 恢复到其定义的 `model` 字段或，没有一个，主对话的模型。

405 407

432* 一个 [fork](#fork-the-current-conversation)434* 一个 [fork](#fork-the-current-conversation)

433* 一个 [skill that runs in a subagent](/docs/zh-CN/skills#run-skills-in-a-subagent)，带有 `model: inherit`435* 一个 [skill that runs in a subagent](/docs/zh-CN/skills#run-skills-in-a-subagent)，带有 `model: inherit`

434 436

437<h3 id="choose-an-effort-level">

438 选择 effort 级别

439</h3>

440

441要让子代理以其自身的 [effort 级别](/docs/zh-CN/model-config#adjust-effort-level)运行，请在其定义中设置 [`effort`](#supported-frontmatter-fields) 字段。

442

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

444

435<h3 id="control-subagent-capabilities">445<h3 id="control-subagent-capabilities">

436 控制 subagent 能力446 控制 subagent 能力

437</h3>447</h3>

tools-reference.md +21 −11

Details

187| 有效 | 内联最多约 30,000 个字符（默认）；超过该值，为保存到会话目录的文件的路径（文件超过 64 MiB 的部分会被截断），加上最多前 2,000 个字符的预览，Claude 在需要其余部分时读取或搜索该文件 |187| 有效 | 内联最多约 30,000 个字符（默认）；超过该值，为保存到会话目录的文件的路径（文件超过 64 MiB 的部分会被截断），加上最多前 2,000 个字符的预览，Claude 在需要其余部分时读取或搜索该文件 |

188| 失败 | 内联最多约 10,000 个字符；超过该值，从读回窗口中切割的该大小的头尾摘录，没有文件路径 |188| 失败 | 内联最多约 10,000 个字符；超过该值，从读回窗口中切割的该大小的头尾摘录，没有文件路径 |

189 189

190退出代码为 1 的命令仅当 Claude Code 识别退出代码 1 为该命令的良性结果时，才计为 Bash 工具的有效结果：`grep`、`rg`、`egrep`、`fgrep`、`find`、`diff`、`test` 和 `[`，加上 `git diff` 和 `git grep`。退出代码为 1 的所有其他命令都计为失败，即使退出 1 是良性信息结果：`pgrep` 和 `jq -e` 没有匹配项，`cmp` 的文件不同。190退出码为 1 的命令仅当 Claude Code 识别退出码 1 为该命令的良性结果时，才计为 Bash 工具的有效结果：`grep`、`rg`、`egrep`、`fgrep`、`find`、`diff`、`test` 和 `[`，加上 `git diff` 和 `git grep`。退出码为 1 的所有其他命令都计为失败，即使退出 1 是良性信息结果：`pgrep` 和 `jq -e` 没有匹配项，`cmp` 的文件不同。

191 191

192[`BASH_MAX_OUTPUT_LENGTH`](/docs/zh-CN/env-vars) 设置 Claude Code 从工作文件读回到命令结果中的输出字符数：默认 30,000，最多 150,000。当您的命令经常溢出该窗口时（例如详细的构建或完整的测试套件日志），请提高它。提高它会扩大读回窗口，这也是失败命令的摘录被切割的窗口。它不会提高内联上限：超过内联上限的有效结果作为文件路径加预览到达，无论此变量如何。192[`BASH_MAX_OUTPUT_LENGTH`](/docs/zh-CN/env-vars) 设置 Claude Code 从工作文件读回到命令结果中的输出字符数：默认 30,000，最多 150,000。当您的命令经常溢出该窗口时（例如详细的构建或完整的测试套件日志），请提高它。提高它会扩大读回窗口，这也是失败命令的摘录被切割的窗口。它不会提高内联上限：超过内联上限的有效结果作为文件路径加预览到达，无论此变量如何。

193 193

203 后台命令何时停止203 后台命令何时停止

204</h4>204</h4>

205 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)。206[前台子代理](/docs/zh-CN/sub-agents#run-subagents-in-foreground-or-background)启动的命令在该子代理的运行结束时停止，无论它是完成、失败还是被中断。主对话或后台子代理启动的命令在最终响应后继续运行，直到它退出、被停止或达到其[时间限制](#time-limit-for-background-commands)。

207

208当主对话启动的命令仍在运行时，使用 `-p` 标志的非交互模式运行会[在其结果之后保持打开](/docs/zh-CN/headless#background-tasks-at-exit)，直到该命令退出或达到其时间限制。后台子代理启动的命令会在运行退出时被停止。

207 209

208<h4 id="time-limit-for-background-commands">210<h4 id="time-limit-for-background-commands">

209 后台命令的时间限制211 后台命令的时间限制

218* Claude 在后台启动的命令获得 30 分钟，或 Claude 使用 `run_in_background` 传递的 `timeout`，最多 2 小时220* Claude 在后台启动的命令获得 30 分钟，或 Claude 使用 `run_in_background` 传递的 `timeout`，最多 2 小时

219* 在前台启动然后移到后台的命令，例如在其超时时，从移动时获得 30 分钟221* 在前台启动然后移到后台的命令，例如在其超时时，从移动时获得 30 分钟

220 222

223在使用 `-p` 标志且以文本形式（而不是使用 `--input-format stream-json`）传递提示词的运行中，两个默认值都是 10 分钟而不是 30 分钟，因为该运行会[在其结果之后等待后台命令](/docs/zh-CN/headless#background-tasks-at-exit)。

224

221当后台命令达到其时间限制时，Claude Code 停止它并告诉 Claude 原因，Claude 可以使用更长的 `timeout` 重新启动命令，如果工作仍然需要的话。停止通知读作 `Background command "<description>" was stopped after reaching its background time limit`。225当后台命令达到其时间限制时，Claude Code 停止它并告诉 Claude 原因，Claude 可以使用更长的 `timeout` 重新启动命令，如果工作仍然需要的话。停止通知读作 `Background command "<description>" was stopped after reaching its background time limit`。

222 226

223<h4 id="raise-the-time-limit-for-background-commands">227<h4 id="raise-the-time-limit-for-background-commands">

224 提高后台命令的时间限制228 提高后台命令的时间限制

225</h4>229</h4>

226 230

227两个[环境变量](/docs/zh-CN/env-vars)提高这些限制，对于 Bash 和 PowerShell 命令都是如此。两者都采用毫秒，都不能缩短限制：较低的值保留 30 分钟的默认值和 2 小时的最大值。231两个[环境变量](/docs/zh-CN/env-vars)提高这些限制，对于 Bash 和 PowerShell 命令都是如此。两者都采用毫秒，都不能缩短限制：较低的值保留默认值和 2 小时的最大值。

228 232

229* 将 `BASH_DEFAULT_TIMEOUT_MS` 设置为高于 `1800000` 以用该值替换 30 分钟的默认值，既适用于 Claude 启动的没有 `timeout` 的命令，也适用于移动的命令233* 将 `BASH_DEFAULT_TIMEOUT_MS` 设置为高于 `1800000` 以用该值替换 30 分钟的默认值，既适用于 Claude 启动的没有 `timeout` 的命令，也适用于移动的命令。在以文本形式传递提示词的 `-p` 运行中，任何高于 `600000` 的值都会替换其 10 分钟的默认值

230* 将 `BASH_MAX_TIMEOUT_MS` 设置为高于 `7200000` 以将 2 小时的最大值提高到该值。将 `BASH_DEFAULT_TIMEOUT_MS` 设置为高于 `7200000` 以相同方式提高最大值234* 将 `BASH_MAX_TIMEOUT_MS` 设置为高于 `7200000` 以将 2 小时的最大值提高到该值。将 `BASH_DEFAULT_TIMEOUT_MS` 设置为高于 `7200000` 以相同方式提高最大值

231 235

232<h4 id="foreground-commands-that-move-to-the-background">236<h4 id="foreground-commands-that-move-to-the-background">

256 260

257Claude Code 也可以将它启动的其他类型的进程计入同一限制。设置 [`CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE`](/docs/zh-CN/env-vars#variables) 为逗号分隔的类型列表以豁免上限；Claude Code 对不在您列表中的每种类型应用上限。设置为 `none` 以限制每种类型，或设置为 `all-new` 以仅限制 Bash、PowerShell 和 Monitor 工具命令。需要 Claude Code v2.1.246 或更高版本。您可以命名的类型：261Claude Code 也可以将它启动的其他类型的进程计入同一限制。设置 [`CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE`](/docs/zh-CN/env-vars#variables) 为逗号分隔的类型列表以豁免上限；Claude Code 对不在您列表中的每种类型应用上限。设置为 `none` 以限制每种类型，或设置为 `all-new` 以仅限制 Bash、PowerShell 和 Monitor 工具命令。需要 Claude Code v2.1.246 或更高版本。您可以命名的类型：

258 262

259* `mcp`: 本地 [MCP servers](/docs/zh-CN/mcp)263* `mcp`: 本地 [MCP 服务器](/docs/zh-CN/mcp)

260* `lsp`: [language servers](#lsp-tool-behavior)264* `lsp`: [language servers](#lsp-tool-behavior)

261* `hooks`: [hook](/docs/zh-CN/hooks) 命令265* `hooks`: [hook](/docs/zh-CN/hooks) 命令

262* `plugin`: [plugins](/docs/zh-CN/plugins/overview) 运行的命令266* `plugin`: [插件](/docs/zh-CN/plugins/overview)运行的命令

263* `helper`: Claude Code 自己的辅助命令，例如 `git`267* `helper`: Claude Code 自己的辅助命令，例如 `git`

264* `agent`: 子 Claude Code 进程，例如 [agent teammates](/docs/zh-CN/agent-teams)268* `agent`: 子 Claude Code 进程，例如 [agent teammates](/docs/zh-CN/agent-teams)

265 269

267 271

268* **未知名称**：Claude Code 忽略它不识别的名称272* **未知名称**：Claude Code 忽略它不识别的名称

269* **变量未设置**：Claude Code 从 Anthropic 从服务器传递的配置中获取其他限制类型的集合，该集合可能随时间变化，因此当您需要不变的集合时设置变量273* **变量未设置**：Claude Code 从 Anthropic 从服务器传递的配置中获取其他限制类型的集合，该集合可能随时间变化，因此当您需要不变的集合时设置变量

270* **权限门控 hooks**：即使每种类型都受限，Claude Code 也会从上限中排除可以阻止或更改操作结果的 hook，以及任何此类 hook 调用的 MCP 服务器，因此内核杀死权限门控 hook 不能允许它阻止的操作274* **权限门控 hook**：即使每种类型都受限，Claude Code 也会从上限中排除可以阻止或更改操作结果的 hook，以及任何此类 hook 调用的 MCP 服务器，因此内核杀死权限门控 hook 不能允许它阻止的操作

271 275

272<h2 id="edit-tool-behavior">276<h2 id="edit-tool-behavior">

273 Edit 工具行为277 Edit 工具行为

285 289

286使用 Bash 查看文件也满足编辑前读取要求，当命令是 `cat`、`nl`、`bat`、`batcat`、`head`、`tail`、`sed -n 'X,Yp'`、`grep`、`egrep`、`fgrep` 或 `rg` 在单个文件上且没有管道或重定向时。管道输出和其他 Bash 命令不计入编辑前读取检查。290使用 Bash 查看文件也满足编辑前读取要求，当命令是 `cat`、`nl`、`bat`、`batcat`、`head`、`tail`、`sed -n 'X,Yp'`、`grep`、`egrep`、`fgrep` 或 `rg` 在单个文件上且没有管道或重定向时。管道输出和其他 Bash 命令不计入编辑前读取检查。

287 291

288使用 Bash 查看文件仅影响编辑资格，不影响权限。请参阅 [Read 和 Edit 权限规则](/docs/zh-CN/permissions#read-and-edit)，了解您的 `Read` 和 `Edit` 拒绝规则涵盖哪些 Bash 命令。292当 Claude 以这种方式查看文件时，Claude Code 还会加载适用于该文件的任何[子目录 `CLAUDE.md`](/docs/zh-CN/memory#how-claude-md-files-load) 和[路径范围规则](/docs/zh-CN/memory#path-specific-rules)。请参阅 [Read 和 Edit 权限规则](/docs/zh-CN/permissions#read-and-edit)，了解您的 `Read` 和 `Edit` 拒绝规则涵盖哪些 Bash 命令。

289 293

290<h2 id="endconversation-tool-behavior">294<h2 id="endconversation-tool-behavior">

291 EndConversation 工具行为295 EndConversation 工具行为

709搜索后端不可配置。要使用不同的提供商进行搜索，请添加一个[MCP 服务器](/docs/zh-CN/mcp)来公开搜索工具。713搜索后端不可配置。要使用不同的提供商进行搜索，请添加一个[MCP 服务器](/docs/zh-CN/mcp)来公开搜索工具。

710 714

711<Note>715<Note>

712 WebSearch 在 Claude API 和 [AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 上可用。在 Microsoft Foundry 上，它需要[部署在 Anthropic 上](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)：部署在 Azure 上的部署不支持服务器端工具，因此 WebSearch 调用失败。在 Google Cloud 的 Agent Platform 上，它适用于 Claude 4 及更高版本的模型，包括 Opus、Sonnet 和 Haiku。Amazon Bedrock 不公开服务器端网络搜索工具。716 WebSearch 在 Claude API、[AWS 上的 Claude Platform](/docs/zh-CN/claude-platform-on-aws) 和 Microsoft Foundry 上可用。在 Google Cloud 的 Agent Platform 上，它适用于 Claude 4 及更高版本的模型，包括 Opus、Sonnet 和 Haiku。Amazon Bedrock 不公开服务器端网络搜索工具。

713</Note>717</Note>

714 718

715<h3 id="session-search-limit">719<h3 id="session-search-limit">

716 会话搜索限制720 会话搜索限制

717</h3>721</h3>

718 722

719一个会话最多可以进行 200 次 WebSearch 调用，计数跨越主对话和它生成的每个[子代理](/docs/zh-CN/sub-agents)，因此并行研究扇出进行的搜索计入同一限制。该限制需要 Claude Code v2.1.212 或更高版本。当 Claude 达到限制时，进一步的调用会返回一个通知，告诉 Claude 继续使用它已经收集的信息，而不是会邀请重试的错误。您看不到该通知：受限的调用在对话中显示为未执行任何操作的搜索，如果 Claude 需要更多搜索，该通知会告诉它要求您提高限制。723一个交互式终端会话最多可以进行 200 次 WebSearch 调用。来自主对话和[子代理](/docs/zh-CN/sub-agents)的搜索（例如并行研究扇出）计入同一限制。该限制需要 Claude Code v2.1.212 或更高版本。

724

725当会话达到限制时，搜索在对话中显示为未执行任何操作的调用。Claude 会收到一个通知，告诉它继续使用已经收集的信息，如果需要更多搜索，则要求您提高限制。

726

727要获得更多搜索次数，请提高上限、等待限制恢复，或开始新的对话：

720 728

721设置 [`CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION`](/docs/zh-CN/env-vars) 环境变量来更改上限；它接受正整数，因此上限可以提高但不能关闭。运行 [`/clear`](/docs/zh-CN/commands#all-commands) 会重置计数。如果仍然可以生成[子代理](/docs/zh-CN/sub-agents)的工作（例如正在运行的工作流）在清除后继续存在，计数会改为继续。729* **提高上限**：将 [`CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION`](/docs/zh-CN/env-vars#variables) 环境变量设置为正整数，例如 `500`。上限可以提高但不能关闭。

730* **等待恢复**：在 Claude Code v2.1.290 或更高版本中，交互式终端会话的限制大约每小时恢复 100 次调用。要更改该速率，请将 [`CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR`](/docs/zh-CN/env-vars#variables) 设置为每小时的调用次数，例如 `50`。

731* **开始新的对话**：在 Claude Code 提示符处运行 [`/clear`](/docs/zh-CN/commands#all-commands) 也会重置计数。如果仍然可以生成子代理的工作（例如正在运行的工作流）在清除后继续存在，计数会改为继续累计。

722 732

723<h2 id="write-tool-behavior">733<h2 id="write-tool-behavior">

724 Write tool 行为734 Write tool 行为

vs-code.md +2 −1

Details

602| `archiveInactiveSessions` | `14` | 在无活动的这么多天后[自动存档会话](#resume-past-conversations)：`1`、`2`、`7` 或 `14`。设置为 `0` 以关闭。需要 Claude Code v2.1.265 或更高版本 |602| `archiveInactiveSessions` | `14` | 在无活动的这么多天后[自动存档会话](#resume-past-conversations)：`1`、`2`、`7` 或 `14`。设置为 `0` 以关闭。需要 Claude Code v2.1.265 或更高版本 |

623* **Claude 的回复**：该扩展在每条回复完成时宣布一次，在文本流入时保持沉默。您的屏幕阅读器将代码块读作行数摘要，按标签读取链接，逐个单元格读取表格；完整回复在记录中保持可读。623* **Claude 的回复**：该扩展在每条回复完成时宣布一次，在文本流入时保持沉默。您的屏幕阅读器将代码块读作行数摘要，按标签读取链接，逐个单元格读取表格；完整回复在记录中保持可读。

624* **权限请求和问题**：当权限提示出现时，该扩展会宣布请求，并命名 Claude 想要使用的工具。当 Claude 向您提问以及当 Claude 完成计划并等待您审查时，它以相同方式宣布。624* **权限请求和问题**：当权限提示出现时，该扩展会宣布请求，并命名 Claude 想要使用的工具。当 Claude 向您提问以及当 Claude 完成计划并等待您审查时，它以相同方式宣布。

625* **状态更改**：当 Claude 开始工作、Claude 准备好接收您的输入以及 Claude Code 开始压缩对话时，该扩展会宣布。625* **状态更改**：当 Claude 开始工作、Claude 准备好接收您的输入以及 Claude Code 开始压缩对话时，该扩展会宣布。

626* **排队的消息**：当您在 Claude 工作时发送消息，该扩展会为该消息宣布"Message queued."。

626* **错误和模型提示**：该扩展宣布对话中的错误，并在 [使用额度同意提示](/docs/zh-CN/model-config#fable-and-usage-credits) 或 [标记请求提示](/docs/zh-CN/model-config#ask-before-switching) 出现时宣布。627* **错误和模型提示**：该扩展宣布对话中的错误，并在 [使用额度同意提示](/docs/zh-CN/model-config#fable-and-usage-credits) 或 [标记请求提示](/docs/zh-CN/model-config#ask-before-switching) 出现时宣布。

627 628

628当 Claude 工作时，您的屏幕阅读器会读取一个文本标签来代替进度旋转器的动画。629当 Claude 工作时，您的屏幕阅读器会读取一个文本标签来代替进度旋转器的动画。

web-quickstart.md +1 −1

Details

12 12

13云会话在云基础设施上运行 Claude Code，而不是在您的机器上，默认由 Anthropic 管理。此快速入门从浏览器中的 [claude.ai/code](https://claude.ai/code) 启动一个会话。您也可以从 Claude 移动应用、Desktop 应用或终端使用 `claude --cloud` 启动一个会话。13云会话在云基础设施上运行 Claude Code，而不是在您的机器上，默认由 Anthropic 管理。此快速入门从浏览器中的 [claude.ai/code](https://claude.ai/code) 启动一个会话。您也可以从 Claude 移动应用、Desktop 应用或终端使用 `claude --cloud` 启动一个会话。

14 14

15您需要一个 GitHub 仓库来[开始使用](#connect-github)。Claude 将其克隆到隔离的虚拟机中，进行更改，并为您推送一个分支以供审查。会话在设备间持久化，因此您在笔记本电脑上开始的任务稍后可以从手机上审查。15您需要一个 GitHub 仓库来[开始使用](#connect-github)。Claude 将其克隆到隔离的虚拟机中，进行更改，并为您推送一个分支以供审查。会话在设备间持久化，因此您在笔记本电脑上开始的任务稍后可以从手机上审查。每个会话都会与您的其他 Claude 和 Claude Code 用量一起计入您计划的用量限制，云端虚拟机不会单独收费。

16 16

17云会话适用于：17云会话适用于：

18 18

Documentation 2026-10-07 23:59 UTC to 2026-10-08 22:58 UTC