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 +57 −47

Details

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`

3198};3202};

3199```3203```

3200 3204

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

3202 3206

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

3204 AskUserQuestion3208 AskUserQuestion

3262 3266

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

3264 3268

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

3266 3270

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

3268 3272

3381};3385};

3382```3386```

3383 3387

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

3385 3389

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

3387 NotebookEdit3391 NotebookEdit

3450};3454};

3451```3455```

3452 3456

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

3454 3458

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

3456| - | - | - |3460| - | - | - |

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

3578};3582};

3579```3583```

3580 3584

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

3582 3586

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

3584 ListMcpResources3588 ListMcpResources

3622};3626};

3623```3627```

3624 3628

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

3626 3630

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

3628 ExitWorktree3632 ExitWorktree

3649type EnterPlanModeInput = {};3653type EnterPlanModeInput = {};

3650```3654```

3651 3655

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

3653 3657

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

3655 CronCreate3659 CronCreate

3666};3670};

3667```3671```

3668 3672

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

3670 3674

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

3672 3676

3712};3716};

3713```3717```

3714 3718

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)。3719安排一次性唤醒，在延迟后触发给定的提示词。此工具支持自定步调的 `/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 3720

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

3718 RemoteTrigger3722 RemoteTrigger

3740};3744};

3741```3745```

3742 3746

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

3744 3748

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

3746 3750

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

3748 3752

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 之前，仅关闭例程切换的会话仍然显示该工具，服务器拒绝其调用。3753此工具仅在会话使用启用了 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 3754

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

3752 PushNotification3756 PushNotification

3767 REPL3771 REPL

3768</h3>3772</h3>

3769 3773

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

3771 3775

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

3773 ReportFindings3777 ReportFindings

3797 3801

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

3799 3803

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

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

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

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

3828};3832};

3829```3833```

3830 3834

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

3832 3836

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

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

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

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

3837 3841

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

3839 3843

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

3841 3845

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

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

3844 3847

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

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

3850

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

3846 3852

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

3848 Projects3854 Projects

3867};3873};

3868```3874```

3869 3875

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

3871 3877

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

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

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

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

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

3877 3883

3914type ShowOnboardingRolePickerInput = {};3920type ShowOnboardingRolePickerInput = {};

3915```3921```

3916 3922

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

3918 3924

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

3920 McpInput3926 McpInput

3928};3934};

3929```3935```

3930 3936

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

3932 3938

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

3934 工具输出类型3940 工具输出类型

3935</h2>3941</h2>

3936 3942

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

3938 3944

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

3940 `ToolOutputSchemas`3946 `ToolOutputSchemas`

4059 };4065 };

4060```4066```

4061 4067

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

4063 4069

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

4065 4071

4198};4204};

4199```4205```

4200 4206

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

4202 4208

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

4204 Read4210 Read

4310};4316};

4311```4317```

4312 4318

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

4314 4320

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

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

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

4318 4324

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

4320 Glob4326 Glob

4426 4432

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

4428 4434

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

4430 4436

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

4432 WebSearch4438 WebSearch

4477 4483

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

4479| - | - | - |4485| - | - | - |

4491 4497

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

4625};4631};

4626```4632```

4627 4633

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

4629 4635

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

4631 ListMcpResources4637 ListMcpResources

4714};4720};

4715```4721```

4716 4722

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

4718 4724

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

4720 CronCreate4726 CronCreate

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

4877 }>;4883 }>;

4878 truncated?: boolean;4884 truncated?: boolean;

4885 total?: number;

4886 total_at_least?: true;

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

4880 };4888 };

4881```4889```

4882 4890

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

4892

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

4884 4894

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

4886 Projects4896 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 +1 −1

Details

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

393| 组织策略 | 客户管理的加密密钥 (CMEK)、HIPAA 和 [零数据保留](/docs/zh-CN/zero-data-retention) 未为组织启用。 |393| 组织策略 | 客户管理的加密密钥 (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) 时。 |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 服务器上下文中默认关闭；当您从自己的终端或脚本中使用 [`-p`](/docs/zh-CN/headless) 运行 Claude Code 时，以及设置了 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/zh-CN/env-vars) 时，也默认关闭。 |

395 395

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

397 397

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 +286 −284

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 控制台中生成。以 `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` | 要包含在 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 订阅 |

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` 在计划模式激活时使用的模型。请参阅[模型配置](/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` 在计划模式未激活时使用的模型。请参阅[模型配置](/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`。需要 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` 不会关闭超时，而是会立即关闭对话框。在 v2.1.198 和 v2.1.199 中，自动继续默认启用，超时时间为 `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) 键也可以将其关闭 |

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 假定是网关从原本未修改的响应中删除了该标头，因此会解码响应体，使流式响应继续正常工作。仅当网关还将流重新以服务器发送事件（server-sent events）形式发出时才设置此变量；此时 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 会改用其搜索工具或 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 或更高版本 |

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 为检查[关键路径](/docs/zh-CN/permission-modes#removals-inside-nested-commands-and-inline-scripts)删除而读取通过 `-c` 传递给 shell 的脚本，例如 `bash -c 'rm -rf ~'`。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` 回调的会话中，阻止 Claude Code 运行您的[针对未回答权限请求的 `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)的后台 small/fast 模型请求 |

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` 开关如何。当 [`awaySummaryEnabled`](/docs/zh-CN/settings-reference#awaysummaryenabled) 为 `false` 时，设置为 `1` 可强制开启回顾。优先于该设置和 `/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` 值（例如来自最初由 Claude Code 的 Bash 工具启动的 `screen` 会话或后台启动器）导致真正的顶层会话被误判为嵌套会话时使用。从 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` | 当终端支持但未被自动检测到时，设置为 `1` 可强制启用 DEC 私有模式 2026 [同步输出](https://gist.github.com/christianparpart/d8a62cc1ab659194337d73e399004036)。适用于实现了 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` | 一个会话中可同时运行的[子代理](/docs/zh-CN/sub-agents#concurrent-subagent-limit)数量上限，超过后 Agent 工具将拒绝再生成子代理（默认：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` | 在未传递显式限制时限制 Agent 轮次数。等同于传递 [`--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 控制模式窗格或停滞的 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_PACKAGE_MANAGER_AUTO_UPDATE` | 设置为 `1` 可让 Claude Code 在有新版本可用时在后台运行您的包管理器的升级命令。适用于 Homebrew 和 WinGet 安装。其他包管理器仍会显示升级命令而不运行它。请参阅[自动更新](/docs/zh-CN/setup#auto-updates) |

356| `CLAUDE_CODE_PERFORCE_MODE` | 设置为 `1` 可启用感知 Perforce 的写保护。设置后，如果目标文件缺少所有者写入位，Edit、Write 和 NotebookEdit 会失败并给出 `p4 edit <file>` 提示；Perforce 会清除已同步文件的该位，直到 `p4 edit` 打开它们。这可以防止 Claude Code 绕过 Perforce 变更跟踪 |357| `CLAUDE_CODE_PERFORCE_MODE` | 设置为 `1` 可启用感知 Perforce 的写保护。设置后，如果目标文件缺少所有者写入位，Edit、Write 和 NotebookEdit 会失败并给出 `p4 edit <file>` 提示；Perforce 会清除已同步文件的该位，直到 `p4 edit` 打开它们。这可以防止 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) |359| `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) |360| `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) |

360| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 克隆或刷新插件市场的超时时间（毫秒）（默认值：120000）。对于大型仓库或较慢的网络连接，请增大此值。请参阅 [Git clone timed out](/docs/zh-CN/plugins/troubleshooting#git-clone-timed-out-after-120s) |361| `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS` | 克隆或刷新插件市场的超时时间（毫秒，默认：120000）。对于大型仓库或较慢的网络连接，请调高此值。请参阅 [Git clone timed out](/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) |362| `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 密钥的环境 |363| `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) |364| `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` |365| `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 或更高版本 |366| `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 或更高版本 |367| `CLAUDE_CODE_PROCESS_WRAPPER` | 通过以 argv 前缀形式给出的企业启动器（如 `/opt/corp/launcher`）来启动 Claude Code 从自身二进制文件启动的进程，例如承载 [Agent 视图](/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 或更高版本 |368| `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 或更高版本 |369| `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) |370| `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) |

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) |371| `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 或设置脚本中读取此值，以检测是否处于云端会话中 |373| `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) |374| `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 或更高版本 |375| `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) |376| `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 或更高版本 |377| `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 视图](/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.`。空字符串会使用默认值 |378| `CLAUDE_CODE_RESUME_PROMPT` | 覆盖当 `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` 继续中断的轮次而不是重新发送其提示词时，或者当您使用 `-p` 恢复[延迟的工具调用](/docs/zh-CN/hooks#defer-a-tool-call-for-later)时，Claude Code 发送给 Claude 的继续消息。默认为 `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 或更高版本 |379| `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 或更高版本 |

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)。直接生成的子进程会继承该变量 |380| `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` 进行的运行时扇出；这是一项纵深防御控制 |381| `CLAUDE_CODE_SCRIPT_CAPS` | JSON 对象，用于在设置了 `CLAUDE_CODE_SUBPROCESS_ENV_SCRUB` 时限制特定脚本在每个会话中可被调用的次数。键是与命令文本匹配的子字符串；值是整数调用次数限制。例如，`{"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 在其中使用自己的滚动处理 |382| `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` 值）仍然适用 |383| `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 上的超时时间不会提高预算 |384| `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 会话关联起来 |385| `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 会话关联起来 |

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` |386| `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 运行的命令 |387| `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) |388| `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 发现仍保持启用 |389| `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) 跳过客户端身份验证，适用于自行签署请求的网关 |390| `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 或更高版本 |391| `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 仍会遵循“已被您的组织禁用”的响应 |393| `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 仍会遵循"已被您的组织禁用"的响应 |

393| `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_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 客户端无法发送请求 |395| `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_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_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` 或上箭头历史中。适用于临时的脚本化会话 |398| `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 或更高版本 |400| `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` | 设置为 `1` 可使使用 `--output-format stream-json` 启动的会话在启动失败时写入一条[说明 Claude Code 拒绝启动原因的结果消息](/docs/zh-CN/agent-sdk/typescript#startup_failure_reason)，否则这些启动失败只会以 stderr 输出结束。需要 Claude Code v2.1.274 或更高版本 |

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 确实需要更多次迭代才能完成，请提高此值 |401| `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` 字段 |402| `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 或更高版本 |403| `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 或更高版本 |404| `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` 会自动设置此变量 |405| `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` 结合使用以限制等待时间 |406| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL` | 在非交互模式（`-p` 标志）下设置为 `1`，可在第一次查询之前等待插件安装完成。否则，插件会在后台安装，可能在第一轮中不可用。可与 `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` 结合使用以限制等待时间 |

406| `CLAUDE_CODE_SYNC_PLUGIN_INSTALL_TIMEOUT_MS` | 同步插件安装的超时时间（毫秒）。超过后，Claude Code 会在没有插件的情况下继续运行并记录一条错误。没有默认值：如果不设置此变量，同步安装会一直等到完成 |407| `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 时才设置它 |408| `CLAUDE_CODE_SYNC_SKILLS` | 在使用 `-p` 标志的非交互模式下设置为 `1`，可使 Claude Code 在该次运行中下载为您的 claude.ai 账户启用的 skill，并在运行第一次查询之前等待获取这些 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 继续，剩余的下载在后台完成 |409| `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 下载完成 |410| `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) 设置 |411| `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) |412| `CLAUDE_CODE_TASK_LIST_ID` | 在会话之间共享任务列表。在[具有 Task 工具的会话](/docs/zh-CN/tools-reference#task-tool-availability)中，在多个 Claude Code 实例中设置相同的 ID，即可在共享的任务列表上协同工作。请参阅[任务列表](/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 或更高版本 |413| `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)中会被忽略 |414| `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) |415| `CLAUDE_CODE_TMUX_TRUECOLOR` | 设置为任意非空值（例如 `1`）可允许在 tmux 中输出 24 位真彩色。**设置为 `0` 或 `false` 仍会允许真彩色**，这与大多数开关型变量不同；取消设置该变量可恢复 256 色限制。默认情况下，当设置了 `$TMUX` 时，Claude Code 会限制为 256 色，因为除非经过配置，否则 tmux 不会透传真彩色转义序列。请在向 `~/.tmux.conf` 添加 `set -ga terminal-overrides ',*:Tc'` 之后设置此变量。有关其他 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 或更高版本 |416| `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 或更高版本 |417| `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 或更高版本 |418| `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` 或负值会禁用截止时间 |419| `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` 或负值会禁用截止时间 |

423| `CLAUDE_CODE_USE_NATIVE_FILE_SEARCH` | 设置为 `1` 可使用 Node.js 文件 API 而不是 ripgrep 来发现自定义命令、子代理和输出样式。如果捆绑的 ripgrep 二进制文件在您的环境中不可用或被阻止，请设置此项。不影响 Grep 或文件搜索工具 |424| `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) |425| `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` 可启用它，这需要 `pwsh` 位于您的 `PATH` 中。在 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 或更高版本 |427| `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 或更高版本 |428| `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 或更高版本 |429| `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 或更高版本 |430| `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 或更高版本 |431| `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)中会被忽略 |432| `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_DISABLE_ADOPT` | 设置为 `1` 后，当您按 `←` 或使用 [`/background`](/docs/zh-CN/agent-view#from-inside-a-session) 将会话转入后台时，会停止正在进行的后台工作，而不是将其延续下去。Claude Code 会在转入后台之前请您确认，然后停止原本会延续的任务。需要 Claude Code v2.1.195 或更高版本 |433| `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)中会被忽略 |

434| `CLAUDE_DISABLE_ADOPT` | 设置为 `1` 后，当您按 `←` 或使用 [`/background`](/docs/zh-CN/agent-view#from-inside-a-session) 将会话转入后台时，会停止正在进行的后台工作，而不是将其延续。Claude Code 会在转入后台之前请您确认，然后停止原本会延续的任务。需要 Claude Code v2.1.195 或更高版本 |

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_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 参数时才会设置 |

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_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) |

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_BEDROCK` | 设置为 `1` 可在 Amazon Bedrock `vnd.amazon.eventstream` 响应上启用字节级流式空闲看门狗，这也会在 Bedrock 流式请求上启用[首字节截止时间](/docs/zh-CN/network-config#streaming-idle-watchdogs)。默认关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时时间 |

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_STREAM_WATCHDOG` | 设置为 `0` 可强制禁用事件级流式空闲看门狗，设置为 `1` 可强制启用它。未设置时，看门狗默认对所有提供商启用。在 v2.1.196 之前，未设置时的默认值在直接 Anthropic API 上由服务器控制，在其他提供商上则为关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时时间；有关与此看门狗一同运行的其他停滞计时器，请参阅[流式空闲看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |

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_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 动态填充 |

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_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` 调用不会请求权限，并且该目录会在会话被删除时移除 |

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_PID` | Claude Code 在其生成的子进程中将此变量设置为自身的进程 ID：包括 Bash 和 PowerShell 工具命令以及 hook 命令。在 Linux 上，Bash 工具的 shell 集成会用它拒绝会匹配 Claude Code 进程自身的 `pkill` 模式；请参阅[错误参考](/docs/zh-CN/errors#pkill-pattern-matches-the-claude-code-process)。可在您自己的脚本中读取它，以有意识地识别父 Claude Code 进程或向其发送信号。需要 Claude Code v2.1.214 或更高版本 |

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_REMOTE_CONTROL_SESSION_NAME_PREFIX` | 未提供显式名称时，自动生成的 [Remote Control](/docs/zh-CN/remote-control) 会话名称的前缀。默认为您机器的主机名，生成类似 `myhost-graceful-unicorn` 的名称。`--remote-control-session-name-prefix` CLI 标志可为单次调用设置相同的值 |

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_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 或更高版本 |

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_IDLE_TIMEOUT_MS` | 事件级和字节级流式空闲看门狗关闭停滞连接之前的超时时间，以毫秒为单位。显式设置此变量时，最小值为 `300000`（5 分钟）；较低的值会被静默提升到该值，以容纳扩展思考停顿和代理缓冲，并且字节级看门狗会将该值的上限设为 30 分钟。对于字节级看门狗，`CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS` 优先于此变量。有关各看门狗未设置时的默认值，请参阅[流式空闲看门狗](/docs/zh-CN/network-config#streaming-idle-watchdogs) |

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_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) |

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| `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_AUTO_COMPACT` | 设置为 `1` 可在接近上下文限制时禁用自动压缩。手动 `/compact` 命令仍然可用。当您希望明确控制何时进行压缩时使用。覆盖 [`autoCompactEnabled`](/docs/zh-CN/settings-reference#autocompactenabled) 设置 |

449| `DISABLE_DOCTOR_COMMAND` | 设置为 `1` 可隐藏 [`/doctor`](/docs/zh-CN/commands#all-commands) 设置检查 skill 及其 `/checkup` 别名。适用于不希望用户在会话中运行设置诊断的托管部署。不影响 `claude doctor` 终端命令。在 v2.1.205 之前，此变量会隐藏 `/doctor` 诊断界面命令 |451| `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_FEEDBACK_COMMAND` | 设置为 `1` 可禁用 `/feedback` 命令和 [Claude 起草的反馈](/docs/zh-CN/tools-reference#sendfeedback-tool-behavior)。同时禁用 `/bug` 和 `/share`，它们通过相同路径报告；在 v2.1.212 之前，它们是 `/feedback` 的别名，因此该命令在所有名称下都会被禁用。也接受旧名称 `DISABLE_BUG_COMMAND` |

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_GROWTHBOOK` | 设置为 `1` 或 `true` 可禁用 GrowthBook 功能标志获取，并对每个标志使用代码中的默认值。这会使 [Remote Control](/docs/zh-CN/remote-control#requirements) 以及其他[需要获取功能标志的功能](#features-that-need-feature-flag-fetching)不可用。设置为 `0` 或 `false` 则保持获取开启。除非同时设置了 `DISABLE_TELEMETRY`，否则遥测事件日志记录保持开启 |

455| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 设置为 `1` 可隐藏 `/install-github-app` 命令。使用第三方提供商（Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry）时已默认隐藏 |457| `DISABLE_INSTALL_GITHUB_APP_COMMAND` | 设置为 `1` 可隐藏 `/install-github-app` 命令。使用第三方提供商（Amazon Bedrock、Google Cloud's Agent Platform 或 Microsoft Foundry）时该命令已被隐藏 |

456| `DISABLE_INTERLEAVED_THINKING` | 设置为 `1` 可阻止发送 interleaved-thinking beta 标头。适用于您的 LLM 网关或提供商不支持[交错思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)的情况 |458| `DISABLE_INTERLEAVED_THINKING` | 设置为 `1` 可阻止发送交错思考 beta 请求头。当您的 LLM 网关或提供商不支持[交错思考](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#interleaved-thinking)时很有用 |

461| `DISABLE_PROMPT_CACHING_HAIKU` | 设置为 `1` 可为[默认 Haiku 模型](/docs/zh-CN/prompt-caching#disable-prompt-caching)禁用提示缓存，无论它在何处运行 |463| `DISABLE_PROMPT_CACHING_HAIKU` | 设置为 `1` 可为[默认 Haiku 模型](/docs/zh-CN/prompt-caching#disable-prompt-caching)禁用提示缓存，无论其在何处运行 |

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_TELEMETRY` | 设置为任意非空值（例如 `1`）可选择退出遥测。**设置为 `0` 或 `false` 仍会选择退出**，这与大多数开关变量不同；取消设置该变量可重新启用遥测。遥测事件不包含代码、文件路径或 Bash 命令等用户数据。同时禁用[功能标志获取](#features-that-need-feature-flag-fetching)。请参阅[为您的组织关闭遥测](/docs/zh-CN/managed-settings#turn-telemetry-off-for-your-organization) |

465| `DISABLE_UPDATES` | 设置为 `1` 可阻止所有更新，包括手动执行的 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更严格。适用于通过您自己的渠道分发 Claude Code 且用户不应自行更新的情况 |467| `DISABLE_UPDATES` | 设置为 `1` 可阻止所有更新，包括手动执行的 `claude update` 和 `claude install`。比 `DISABLE_AUTOUPDATER` 更严格。当您通过自己的渠道分发 Claude Code 且用户不应自行更新时使用 |

467| `DO_NOT_TRACK` | 设置为 `1` 可选择退出遥测，效果与 `DISABLE_TELEMETRY` 相同，包括对[功能标志获取](#features-that-need-feature-flag-fetching)的影响。Claude Code 将此变量作为标准布尔值读取，因此 `0` 会保持遥测开启，并且会遵循这一被许多开发者 CLI 认可的跨工具约定 |469| `DO_NOT_TRACK` | 设置为 `1` 可选择退出遥测，效果与 `DISABLE_TELEMETRY` 相同，包括对[功能标志获取](#features-that-need-feature-flag-fetching)的影响。Claude Code 将此变量作为标准布尔值读取，因此 `0` 会保持遥测开启；Claude Code 遵循它，是因为它是许多开发者 CLI 认可的跨工具约定 |

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| `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)中都会被忽略 |

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_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) |

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_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 上的所有模型禁用工具搜索 |474| `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)，因此此变量不影响切换到备用模型 |475| `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` 可将徽章渲染为纯文本 |477| `FORCE_HYPERLINK` | 设置为 `1` 可在您的终端支持但未被自动检测到时启用可点击的 OSC 8 超链接，设置为 `0` 可禁用它们。未设置时，Claude Code 仅在检测到终端支持时启用超链接。Claude Code 将此值解析为数字而不是布尔值，因此 `false`、`no` 或 `off` 等值会启用超链接而不是禁用。页脚中的 [PR 或合并请求徽章](/docs/zh-CN/interactive-mode#pr-review-status)即使在 Claude Code 无法检测到终端支持时（例如通过 SSH）也会渲染为超链接。设置为 `0` 可将该徽章渲染为纯文本 |

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` 设置 |478| `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` 仍会启用演示模式**；取消设置该变量即可将其关闭。适用于直播或录制会话时 |481| `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)，与此变量无关 |482| `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，即一次首次尝试加四次重试 |483| `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` 关闭了自适应推理 |484| `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` 添加服务器时可避免交互式提示 |485| `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) 时，等待的截止时间更长；关于已缓存服务器的例外情况，请参见该标志的条目 |486| `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) 时，等待的截止时间更长；有关已缓存服务器的例外情况，请参阅该标志的条目 |

485| `MCP_CONNECT_TIMEOUT_MS` | 阻塞式 MCP 启动在对工具列表进行快照之前等待连接批次的时长，以毫秒为单位（默认：5000）。在 `MCP_CONNECTION_NONBLOCKING=0` 时或对于标记了 [`alwaysLoad: true`](/docs/zh-CN/mcp#exempt-a-server-from-deferral) 的服务器适用。到截止时间时仍处于待定状态的服务器会继续在后台连接。与 `MCP_TIMEOUT` 不同，后者限制的是单个服务器的连接尝试 |487| `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 或更高版本 |488| `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 不限制该值 |489| `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 或更高版本 |490| `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 不限制该值 |491| `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` 的替代方案 |492| `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 或更高版本 |493| `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 或更高版本 |495| `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 的值会被忽略 |498| `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 的值会被忽略 |

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) |500| `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) |501| `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) |502| `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) |503| `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) |504| `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) |505| `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) |506| `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) |508| `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) |509| `OTEL_METRICS_INCLUDE_REPOSITORY` | 设置为 `true` 可为 OpenTelemetry 指标和事件添加标识会话所在仓库的 `vcs.*` 属性（默认：排除）。需要 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) |510| `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 个字符。保留旧名称是为了向后兼容 |513| `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` 读取后台任务的输出文件 |514| `TASK_MAX_OUTPUT_LENGTH` | 已在 v2.1.277 中移除，现在不起任何作用，与其所限定大小的 `TaskOutput` 工具一同移除。以前用于设置 `TaskOutput` 工具保留的[后台任务](/docs/zh-CN/tools-reference#background-commands)输出的最大字符数。Claude 现改用 `Read` 读取后台任务的输出文件 |

534 536

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)。537还支持标准 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 538

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`）在项目设置和本地设置中仍然生效。539请在您的 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 540

539<h2 id="what-the-subprocess-environment-scrub-removes">541<h2 id="what-the-subprocess-environment-scrub-removes">

540 子进程环境清理会移除哪些内容542 子进程环境清理会移除哪些内容

587* 使用 [advisor 工具](/docs/zh-CN/advisor#requirements)589* 使用 [advisor 工具](/docs/zh-CN/advisor#requirements)

588* 阅读或回复 [Artifact 上的评论](/docs/zh-CN/artifacts#collect-comments-on-an-artifact)590* 阅读或回复 [Artifact 上的评论](/docs/zh-CN/artifacts#collect-comments-on-an-artifact)

589* 让 Claude 读取[其他组织的公开 Artifact](/docs/zh-CN/artifacts#read-an-artifact-shared-with-you)591* 让 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`592* 让 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 上，该工具保持启用593* 在安装了 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 通过获取的标志启用594* 获得 [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]` 占位符背后的内容将以无标记形式传给 Claude595* 让 Claude [将大段粘贴内容视为粘贴而非键入的文本](/docs/zh-CN/terminal-config#how-claude-treats-pasted-text)；`[Pasted text #N]` 占位符背后的内容将以无标记形式传给 Claude

errors.md +26 −30

Details

703当速率限制、过载或服务器错误中断已经生成文本输出的前台子代理时，Claude 接收该部分输出标记为不完整，而不是此错误。仅输出为工具调用的子代理也会收到此错误；在 v2.1.199 中，该形状返回了空的部分结果。请参阅[子代理中的 API 错误](/docs/zh-CN/sub-agents#api-errors-in-subagents)。703当速率限制、过载或服务器错误中断已经生成文本输出的前台子代理时，Claude 接收该部分输出标记为不完整，而不是此错误。仅输出为工具调用的子代理也会收到此错误；在 v2.1.199 中，该形状返回了空的部分结果。请参阅[子代理中的 API 错误](/docs/zh-CN/sub-agents#api-errors-in-subagents)。

704 704

705<h2 id="usage-limits">705<h2 id="usage-limits">

706 使用限制706 用量限制

707</h2>707</h2>

708 708

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) 表示使用额度同意提示未被回答而关闭，无论是否达到配额。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 710

711<h3 id="youve-hit-your-session-limit">711<h3 id="youve-hit-your-session-limit">

712 You've hit your session limit712 You've hit your session limit

713</h3>713</h3>

714 714

715订阅计划包括滚动使用额度。当额度用完时，您会看到以下消息之一：715订阅套餐包括滚动用量额度。当额度用完时，您会看到以下消息之一：

716 716

717```text theme={null}717```text theme={null}

718You've hit your session limit · resets 3:45pm718You've hit your session limit · resets 3:45pm

732* 等待错误中显示的重置时间732* 等待错误中显示的重置时间

733* 在 [Desktop app](/docs/zh-CN/desktop) 的 Code 选项卡中，会话限制卡提供 **Auto-continue when limits reset** 复选框。周限制卡没有。选中后，Desktop app 会在重置后重试中断的轮次，并在卡上显示重试时间。Desktop 复选框和 CLI 中 `/config` 中的 **Continue automatically at usage limit** 设置是分开的，因此需要分别关闭每一个。733* 在 [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)734* 对于 Opus 或 Sonnet 限制，运行 `/model` 并切换到该系列之外的模型以继续工作。每个模型都有自己的提示缓存，因此下一个请求会重新读取整个对话，没有缓存命中；请参阅 [Switching models](/docs/zh-CN/prompt-caching#switching-models)

735* 运行 `/usage` 查看您的计划限制以及何时重置735* 运行 `/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)。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* 要升级您的计划以获得更高的基础限制，请参阅 [claude.com/pricing](https://claude.com/pricing)737* 要升级您的套餐以获得更高的基础限制，请参阅 [claude.com/pricing](https://claude.com/pricing)

738 738

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)。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 740

742 Usage credits required for 1M context742 Usage credits required for 1M context

743</h3>743</h3>

744 744

745所选模型使用 1M 令牌扩展上下文窗口，您的计划仅通过使用额度包含它。745所选模型使用 1M token 扩展上下文窗口，而您的套餐仅通过使用额度包含它。

746 746

747```text theme={null}747```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 context748API 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```749```

750 750

751在 Claude Desktop app 运行的会话中，提示不命名任何命令：它指向 claude.ai 使用设置页面，或在 Team 和 Enterprise 计划上说在 claude.ai/admin-settings/usage 启用使用额度或向您的管理员请求。751在 Claude Desktop app 运行的会话中，提示不命名任何命令：它指向 claude.ai 用量设置页面，或在 Team 和 Enterprise 套餐上说在 claude.ai/admin-settings/usage 启用使用额度或向您的管理员请求。

752 752

753这是权限检查，而非配额耗尽。即使您的会话和周额度有剩余容量，它也会触发。有关哪些计划直接包含 1M 上下文以及哪些需要使用额度的信息，请参阅 [Extended context](/docs/zh-CN/model-config#extended-context)。753这是权限检查，而非配额耗尽。即使您的会话和周额度有剩余容量，它也会触发。有关哪些套餐直接包含 1M 上下文以及哪些需要使用额度的信息，请参阅 [Extended context](/docs/zh-CN/model-config#extended-context)。

754 754

755当此错误在对话中期出现，因为上下文增长超过 200K 令牌时，Claude Code 会自动将对话压缩回标准上下文限制以下，并之后将会话保持在该限制，因此无需采取任何操作。在 v2.1.172 之前的版本中，错误会在每个后续请求（包括 `/compact`）上重复；在这些版本上运行 `/clear` 以恢复。以下步骤适用于您明确选择 `[1m]` 模型的情况。755当此错误因上下文增长超过 200K token 而在对话中途出现时，Claude Code 会自动将对话压缩回标准上下文限制以下，并在之后将会话保持在该限制，因此无需采取任何操作。在 v2.1.172 之前的版本中，错误会在每个后续请求（包括 `/compact`）上重复；在这些版本上运行 `/clear` 以恢复。以下步骤适用于您明确选择 `[1m]` 模型的情况。

756 756

757**要做什么：**757**要做什么：**

758 758

780 780

781**要做什么：**781**要做什么：**

782 782

783* 在会话运行的地方，在终端或托管它的应用程序中，发送另一个提示并在它重新出现时回答同意提示。对于后台会话，首先从 [agents view](/docs/zh-CN/agent-view) 附加到它。从 Remote Control 客户端重新发送会再次显示此消息，因为客户端无法显示提示。783* 在会话运行的地方，在终端或托管它的应用程序中，发送另一个提示词并在同意提示重新出现时回答它。对于后台会话，首先从 [agents view](/docs/zh-CN/agent-view) 附加到它。从 Remote Control 客户端重新发送会再次显示此消息，因为客户端无法显示提示。

784* 运行 `/model` 切换到不计费使用额度的模型784* 运行 `/model` 切换到不计费使用额度的模型

785* 要给自己更多时间，请将 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 设置为更长的值或 `"never"`785* 要给自己更多时间，请将 [`dialogExpiry`](/docs/zh-CN/settings-reference#dialogexpiry) 设置为更长的值或 `"never"`

786 786

790 Server is temporarily limiting requests790 Server is temporarily limiting requests

791</h3>791</h3>

792 792

793API 应用了与您的计划配额无关的短期限流。793API 应用了与您的套餐配额无关的短期限流。

794 794

795```text theme={null}795```text theme={null}

796API Error: Server is temporarily limiting requests (not your usage limit)796API Error: Server is temporarily limiting requests (not your usage limit)

797```797```

798 798

799Claude Code 通过真实限制响应所携带的统一配额标头的缺失来区分这些。从 v2.1.199 开始，这是 [retried automatically](#automatic-retries) 带有退避，无论您如何进行身份验证。在早期版本中，使用 claude.ai 订阅登录的会话在第一次出现时失败轮次；只有 API 密钥和 Enterprise 登录重试了它。799Claude Code 通过真实限制响应所携带的统一配额标头的缺失来区分这些。从 v2.1.199 开始，无论您如何进行身份验证，此错误在显示之前都会以退避方式[自动重试](#automatic-retries)。在早期版本中，使用 claude.ai 订阅登录的会话在第一次出现时即使轮次失败；只有 API 密钥和 Enterprise 登录会重试它。

800 800

801**要做什么：**801**要做什么：**

802 802

819 819

820**要做什么：**820**要做什么：**

821 821

822* 运行 `/status` 并确认活跃凭证是您期望的。环境中的流浪 `ANTHROPIC_API_KEY` 可能会通过低层密钥而不是您的订阅路由请求。822* 运行 `/status` 并确认活跃凭据是您期望的。环境中残留的 `ANTHROPIC_API_KEY` 可能会通过低层级密钥而不是您的订阅路由请求。

823* 检查您的提供商控制台以了解活跃限制，如果需要请求更高的层级823* 检查您的提供商控制台以了解活跃限制，如果需要请求更高的层级

824* 对于 Anthropic API 密钥，请参阅 [rate limits reference](https://platform.claude.com/docs/en/api/rate-limits) 了解层级如何工作以及如何设置每个工作区的上限824* 对于 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` 为高容量脚本运行切换到更小的模型825* 降低并发：降低 [`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`](/docs/zh-CN/env-vars)，避免运行许多并行子代理，或使用 `/model` 为高容量脚本运行切换到更小的模型

828 You've hit your monthly spend limit828 You've hit your monthly spend limit

829</h3>829</h3>

830 830

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) 的模型的请求。消息命名其限制阻止了您。`·` 后的文本说明如何增加该限制，并因您的计划和您是否管理计费而异：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 832

833```text theme={null}833```text theme={null}

834You've hit your monthly spend limit · raise it at claude.ai/settings/usage834You'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 limit835You'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 it836You'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/usage837You'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 settings838You've hit your channel's monthly spend limit · an org owner or channel manager can raise it in the channel's Claude settings

839```839```

840 840

841`team's shared budget` 是管理员分配给您所属的组的汇总预算；消息不命名该组。`channel's monthly spend limit` 是会话运行的一个 Slack 频道的预算，因此您的组织可能在其外部仍有预算。841`team's shared budget` 是管理员分配给您所属的组的汇总预算；消息不命名该组。`channel's monthly spend limit` 是会话运行的一个 Slack 频道的预算，因此您的组织可能在其外部仍有预算。

842 842

843当您的计划的窗口之一用完时，消息也会说该窗口何时重置，例如 `· your session limit resets 3:45pm`，访问权限会在那时返回，无需任何人提高限制。在使用基于使用量的计费的组织中，消息说 `usage limit` 代替 `spend limit`，如 `You've hit your individual usage limit`。843当您的套餐的窗口之一用完时，消息也会说该窗口何时重置，例如 `· 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 844

847如果您通过 Claude apps gateway 连接并看到小写 `spend limit reached`，那是您的网关操作员的上限；请参阅 [Spend limit reached](#spend-limit-reached)。845如果您通过 Claude apps gateway 连接并看到小写 `spend limit reached`，那是您的网关操作员的上限；请参阅 [Spend limit reached](#spend-limit-reached)。

848 846

849**要做什么：**847**要做什么：**

850 848

851* 在 Pro 和 Max 上，在 claude.ai 的 [**Settings > Usage**](https://claude.ai/settings/usage) 中增加您的月度支出限制，或运行 `/usage-credits`849* 在 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` 为您向您的管理员发送该请求850* 在 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)851* 对于频道的限制，要求组织所有者或频道的管理员在 claude.ai 上提高它。请参阅 Claude Tag 文档中的 [Per-channel limits](https://claude.com/docs/claude-tag/admins/set-spend-limit#per-channel-limits)

854* 如果消息命名您的计划窗口的重置时间，您可以改为等待它852* 如果消息命名您的套餐窗口的重置时间，您可以改为等待它

855* 运行 `/usage` 查看您的计划窗口以及每个何时重置853* 运行 `/usage` 查看您的套餐窗口以及每个何时重置

856 854

857<h3 id="spend-limit-reached">855<h3 id="spend-limit-reached">

858 Spend limit reached856 Spend limit reached

885 883

886**要做什么：**884**要做什么：**

887 885

888* 如果您有 Pro、Max、Team 或 Enterprise 计划并看到这个，运行 `/status` 并检查 `API key` 行。环境中已批准的 `ANTHROPIC_API_KEY` 通过该密钥而不是您的订阅路由请求。在当前 shell 中取消设置它并从您的 shell 配置文件中删除它，然后重新启动 `claude`。如果您还没有使用您的订阅登录，运行 `/login`。886* 如果您有 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) 添加额度，并考虑在那里启用自动重新加载，以便余额在达到零之前重新填充887* 在 [platform.claude.com/settings/billing](https://platform.claude.com/settings/billing) 添加额度，并考虑在那里启用自动充值，以便余额在达到零之前重新填充

890* 在 Console 中设置每个工作区的支出上限，以防止单个项目耗尽组织余额。请参阅 [Manage costs effectively](/docs/zh-CN/costs)。888* 在 Console 中设置每个工作区的支出上限，以防止单个项目耗尽组织余额。请参阅 [Manage costs effectively](/docs/zh-CN/costs)。

891 889

892<h3 id="could-not-update-your-spend-limit">890<h3 id="could-not-update-your-spend-limit">

2861 2859

2862如果消息包含 `` Details: `[reasoning_extraction]` `` 行，请参阅[保护措施标记了索取 Claude 推理过程的请求](#safeguards-flagged-a-request-for-claudes-reasoning)。2860如果消息包含 `` Details: `[reasoning_extraction]` `` 行，请参阅[保护措施标记了索取 Claude 推理过程的请求](#safeguards-flagged-a-request-for-claudes-reasoning)。

2863 2861

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)而不是显示此错误。2862此消息链接到[网络安全验证计划](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 2863

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)消息。2864在 [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 2865

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.4822This 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```4823```

4826 4824

4827在 [Agent 视图](/docs/zh-CN/agent-view)中打开相同会话的行会在列表下方显示 `Press enter again to restart this session fresh`，在该行上第二次按 `Enter` 会使用空对话重启会话。在 v2.1.212 之前，打开该行显示拒绝消息，无法从 Agent 视图重启。在 v2.1.211 之前，打开停止的会话会无声地启动该空白对话，并可能重新运行会话的原始提示词。4825在 [Agent 视图](/docs/zh-CN/agent-view)中打开相同会话的行则会在列表下方显示 `Press enter again to restart this session fresh`，在该行上第二次按 `Enter` 会使用空对话重启会话。

4828 4826

4829**要做什么：**4827**要做什么：**

4830 4828

4846* **`running in another terminal`**：终端持有对话，例如您使用 `claude --resume` 或 `/resume` 恢复它的终端。该行也显示 `Open in a terminal`。4844* **`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)进程尚未退出。4845* **`already open in another running Claude session`**：另一个非交互式 Claude Code 进程持有它，例如相同对话的[后台会话](/docs/zh-CN/agent-view#the-supervisor-process)进程尚未退出。

4848 4846

4849Claude Code 保存您在打开行时键入的回复，并在会话下次启动时将其作为会话的下一个提示词发送。

~~4850~~

4851**要做什么：**4847**要做什么：**

4852 4848

4853* 在持有它的进程中继续对话，或退出该进程并再次打开该行4849* 在持有它的进程中继续对话，或退出该进程并再次打开该行

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 +2 −0

Details

3861 3861

3862将 `type` 设置为 `"prompt"` 并提供 `prompt` 字符串而不是 `command`。使用 `$ARGUMENTS` 占位符将 hook 的 JSON 输入数据注入到您的提示文本中。3862将 `type` 设置为 `"prompt"` 并提供 `prompt` 字符串而不是 `command`。使用 `$ARGUMENTS` 占位符将 hook 的 JSON 输入数据注入到您的提示文本中。

3863 3863

3864在提示词 hook 或 [Agent hook](#agent-based-hooks) 中，您可以将 `prompt` 写成关于阻止或允许什么的规则，例如"阻止任何读取 `.env` 文件的 Bash 命令"，也可以写成必须成立的条件，例如"所有单元测试都通过"。

3865

3864此 `Stop` hook 要求 LLM 在允许 Claude 完成之前评估是否应该停止：3866此 `Stop` hook 要求 LLM 在允许 Claude 完成之前评估是否应该停止：

3865 3867

3866```json theme={null}3868```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 +8 −15

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 提示：

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 工具结果中的图像

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 +9 −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="when-a-client-fails">

447 当 `Client` 失败时

448</h3>

449

450在终端中，当 `Client` 运行的文件失败时，一行暗色文本（例如 `my-mod: Client client/spinner.js: boom`）会取代 `Client` 的位置，而您绘制的其余部分仍会显示。

451

452如果您的 mod 处理 [`ui.fault`](/docs/zh-CN/plugins/mods/reference#interface)，Claude Code 随后会[再次绘制该站点](#when-claude-code-redraws-without-being-asked)。

453

446<h3 id="draw-a-grid-of-colored-cells">454<h3 id="draw-a-grid-of-colored-cells">

447 绘制彩色单元格网格455 绘制彩色单元格网格

448</h3>456</h3>

806以下规则适用于代码：814以下规则适用于代码：

807 815

808* **将 `plugin` 和 `key` 写成字面字符串**：`claude plugin validate` 从您的源代码中读取它们816* **将 `plugin` 和 `key` 写成字面字符串**：`claude plugin validate` 从您的源代码中读取它们

817* **将每个 `atom` 调用的结果保存在 `const` 中**：如果您用 `let` 声明 `count`，验证失败，出现 `takes a source the scan can read`

809* **在类型声明文件中声明每个值**：否则验证失败，出现 `hello-tabs.count is not declared`818* **在类型声明文件中声明每个值**：否则验证失败，出现 `hello-tabs.count is not declared`

810* **从回调或另一个事件的 hook 中写入**：`ui.render` hook 可以读取状态，但不能写入它，因此请从 `onPress`、`onSubmit` 或另一个事件的 hook 中写入819* **从回调或另一个事件的 hook 中写入**：`ui.render` hook 可以读取状态，但不能写入它，因此请从 `onPress`、`onSubmit` 或另一个事件的 hook 中写入

811 820

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 +7 −5

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 事件

259| [`Text`](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) | `color`、`backgroundColor`、`bold`、`italic`、`underline`、`dimColor`、`inverse`、`wrap` | ✓ | ✓ |260| [`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` | ✓ | ✓ |261| [`Button`](/docs/zh-CN/plugins/mods/interface#respond-to-presses-and-typing) | `key`、`label`、`onPress`、`hotkey`、`plain`、`dimColor`、`autoFocus`、`action` | ✓ | ✓ |

261| `Link` | `href`、`label` | ✓ | ✓ |262| `Link` | `href`、`label` | ✓ | ✓ |

262| `Code` | 代码 | ✓ | ✓ |263| [`Code`](/docs/zh-CN/plugins/mods/gallery#show-code-and-changes) | `source`、`language`、`path`、`startLine`、`format`、`wrap` | ✓ | ✓ |

263| `Markdown` | `text`、`key`、`dimColor`、`onLinkPress`、`pressableLinks` | ✓ | ✓ |264| `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` | ✓ | ✓ |265| [`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` | ✓ | ✓ |266| `Select` | `key`、`label`、`options`、`value`、`onSelect`、`autoFocus` | ✓ | ✓ |

266| `Svg` | 一个 SVG 文档，最多 131,072 个字符 | | ✓ |267| `Svg` | 一个 SVG 文档，最多 131,072 个字符 | | ✓ |

267| [`Client`](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements) | `module`、`key` | ✓ | ✓ |268| [`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)。 | ✓ | |269| [`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 字节，或文件路径 | ✓ | |270| `Image` | 最多 2 MiB 的 PNG 或 RGBA 字节，或文件路径，`columns` 和 `rows`（最多 255），以及 `alt` 文本。 | ✓ | |

270 271

271更多 `Button` 规则：`action` 指定 Claude Code 自身的某个[快捷键操作](/docs/zh-CN/keybindings)，当用户为该操作设置的绑定是组合键或带修饰键的按键时，该绑定会按下此按钮。当用户在空的输入框中只输入某个数字并停顿时，横栏中设置了该数字 `hotkey` 的按钮也会触发。当同一次绘制中的两个按钮指定相同的 `hotkey` 时，由后一个按钮获得它。`autoFocus` 在任何控件上都只接受 `true`，因此要关闭它，请省略该 prop。272更多 `Button` 规则：`action` 指定 Claude Code 自身的某个[快捷键操作](/docs/zh-CN/keybindings)，当用户为该操作设置的绑定是组合键或带修饰键的按键时，该绑定会按下此按钮。当用户在空的输入框中只输入某个数字并停顿时，横栏中设置了该数字 `hotkey` 的按钮也会触发。当同一次绘制中的两个按钮指定相同的 `hotkey` 时，由后一个按钮获得它。`autoFocus` 在任何控件上都只接受 `true`，因此要关闭它，请省略该 prop。

272 273

295 限制296 限制

296</h2>297</h2>

297 298

298hook 和 mods API 调用受时间和大小限制。Claude Code 会跳过超出时间限制的 hook，并拒绝超出大小限制的调用。299hook 和 mods API 调用受时间和大小限制。Claude Code 会跳过超出时间限制的 hook。

299 300

300| 限制 | 值 |301| 限制 | 值 |

301| :- | :- |302| :- | :- |

308| 单个树中的文本 | 仅绘制前 100,000 个字符 |309| 单个树中的文本 | 仅绘制前 100,000 个字符 |

310| `Code` 的 `language` 或 `path`、`Select` 选项的 `value`，或 `Client` 的 `module` | 10,000 个字符。如果其中任何一项超出此长度，Claude Code 会[在该位置绘制其自身的版本](/docs/zh-CN/plugins/mods/interface#build-a-tree-from-elements)。 |

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)。 |329| `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 会继续运行。 |330| `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 +33 −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="the-module-failed-without-a-message">

223 `the module failed without a message`

224</h3>

225

226某个 [`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`。

227

228在您的 `Client` 代码中找到该 throw，并为该错误提供消息。该行随后会显示该消息。

229

230在 v2.1.289 之前，该行改为显示 `Error` 作为原因。

231

210<h3 id="$-ui-open-runs-and-no-pane-appears">232<h3 id="$-ui-open-runs-and-no-pane-appears">

211 `$.ui.open` 运行且没有窗格出现233 `$.ui.open` 运行且没有窗格出现

212</h3>234</h3>

227 绘图在终端中有效，在桌面应用中无效249 绘图在终端中有效，在桌面应用中无效

228</h3>250</h3>

229 251

230该网站或元素在那里不可用。252该位置或元素在那里不可用。

231 253

232检查 [渲染网站](/docs/zh-CN/plugins/mods/reference#render-sites) 和 [元素](/docs/zh-CN/plugins/mods/reference#elements) 表。254检查 [渲染位置](/docs/zh-CN/plugins/mods/reference#render-sites) 和 [元素](/docs/zh-CN/plugins/mods/reference#elements) 表。

233 255

234<h2 id="an-edit-or-a-value-is-lost">256<h2 id="an-edit-or-a-value-is-lost">

235 编辑或值丢失257 编辑或值丢失

265 阅读调试日志287 阅读调试日志

266</h2>288</h2>

267 289

268调试日志对 Claude Code 加载或拒绝的每个模块、每个失败的 hook 以及它拒绝的每个结果都有一行，因此当成绩单显示无内容时，这是查看的地方。要写入一个，在您的 shell 中使用 `--debug` 启动 Claude Code，或使用 `--debug-file <path>` 选择它的位置：290调试日志对 Claude Code 加载或拒绝的每个模块、每个失败的 hook 以及它拒绝的每个结果都有一行，因此当会话记录中没有任何显示时，这是查看的地方。要写入一个，在您的 shell 中使用 `--debug` 启动 Claude Code，或使用 `--debug-file <path>` 选择它的位置：

269 291

270```bash theme={null}292```bash theme={null}

271claude --debug-file ./mod-debug.log --plugin-dir ./first-mod293claude --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.render305hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render

284```306```

285 307

286未验证的绘图计为被拒绝的结果，也会获得一行。要在日志中写入您自己的行，请调用 [`$.ui.log`](/docs/zh-CN/plugins/mods/api#show-something-without-starting-a-turn)，带有第二个参数，如 `$.ui.log('message', { to: 'debug' })`。没有第二个参数，`$.ui.log` 会在成绩单中添加一条暗行。308未验证的绘图计为被拒绝的结果，也会获得一行。要在日志中写入您自己的行，请调用 [`$.ui.log`](/docs/zh-CN/plugins/mods/api#show-something-without-starting-a-turn)，带有第二个参数，如 `$.ui.log('message', { to: 'debug' })`。没有第二个参数，`$.ui.log` 会在会话记录中添加一条暗行。

287 309

288当您编辑使用 `--plugin-dir` 加载的 mod 时，成绩单为每次重新加载显示一行，命名 mod 并列出其 hooks。如果保存破坏了模块，该行说 `reload failed, the previous version stays loaded:` 带有原因，最后一个工作版本继续运行。310当您编辑使用 `--plugin-dir` 加载的 mod 时，会话记录为每次重新加载显示一行，命名 mod 并列出其 hook。如果保存破坏了模块，该行会显示 `reload failed, the previous version stays loaded:` 及原因，最后一个可用版本会继续运行，直到 Claude Code 下次重新加载插件，例如当您运行 `/reload-plugins` 时。

289 311

290<h2 id="next-steps">312<h2 id="next-steps">

291 后续步骤313 后续步骤

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 +17 −8

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{

3164 `plansDirectory`3164 `plansDirectory`

3165</h3>3165</h3>

3166 3166

3167选择 Claude Code 在[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)中写入的计划文件的存储位置。Claude Code 相对于项目根目录解析路径，当路径解析到项目外时保持默认值。3167选择 Claude Code 在[计划模式](/docs/zh-CN/permission-modes#analyze-before-you-edit-with-plan-mode)中写入的计划文件的存储位置。Claude Code 相对于项目根目录解析路径。

3168 3168

3169* **Scope**: [`Any file`](#scopes)3169* **Scope**: [`Any file`](#scopes)

3170* **Type**: 字符串，相对于项目根目录的路径3170* **Type**: 字符串，相对于项目根目录的路径

3176}3176}

3177```3177```

3178 3178

3179在以下情况下，Claude Code 会将计划存储在 `~/.claude/plans` 中，而不是您设置的目录中：

3180

3181* **位于项目根目录之外**：路径解析到项目根目录之外，例如 `"../plans"`。

3182* **在 macOS、Linux 和 WSL 上包含反斜杠**：解析后的路径包含反斜杠，例如 Windows 风格的 `"docs\\plans"`。请写成 `"docs/plans"`，它在 Windows 上同样适用。

3183

3179<h3 id="skilllistingbudgetfraction">3184<h3 id="skilllistingbudgetfraction">

3180 `skillListingBudgetFraction`3185 `skillListingBudgetFraction`

3181</h3>3186</h3>

4434在 Claude Code 的生命周期中的某些点（例如在工具调用之前或会话启动时）运行您自己的命令、提示、代理、HTTP 请求或 MCP 工具作为 [hooks](/docs/zh-CN/hooks)；[hooks 参考](/docs/zh-CN/hooks#hook-events) 列出每个事件、其有效负载和其退出代码。每个事件映射到匹配器组列表，每个组列出在匹配器应用时运行的处理程序。4439在 Claude Code 的生命周期中的某些点（例如在工具调用之前或会话启动时）运行您自己的命令、提示、代理、HTTP 请求或 MCP 工具作为 [hooks](/docs/zh-CN/hooks)；[hooks 参考](/docs/zh-CN/hooks#hook-events) 列出每个事件、其有效负载和其退出代码。每个事件映射到匹配器组列表，每个组列出在匹配器应用时运行的处理程序。

4435 4440

4436* **作用域**: [`任何文件`](#scopes)。Hooks 在文件中合并而不是相互替换，来自托管设置的 hooks 无法从其他文件中删除。4441* **作用域**: [`任何文件`](#scopes)。Hooks 在文件中合并而不是相互替换，来自托管设置的 hooks 无法从其他文件中删除。

4437* **类型**: 由 [hook 事件](/docs/zh-CN/hooks#hook-events) 键入的对象；每个值是 `{ "matcher", "hooks" }` 组的数组，其 `hooks` 条目的 `type` 为 `"command"`、`"prompt"`、`"agent"`、`"http"` 或 `"mcp_tool"`4442* **类型**: 以 [hook 事件](/docs/zh-CN/hooks#hook-events) 为键的对象；每个值是 `{ "matcher", "hooks" }` 组的数组，其 `hooks` 条目的 `type` 为 `"command"`、`"prompt"`、`"agent"`、`"http"` 或 `"mcp_tool"`

4438* **默认值**: 未设置，因此没有 hooks 运行4443* **默认值**: 未设置，因此没有 hooks 运行

4439 4444

4440此示例在每个 Bash 工具调用之前运行脚本：4445此示例在每个 Bash 工具调用之前运行脚本：

5416从托管设置向每个用户提供远程 MCP 服务器。用户保留他们自己添加的服务器，无法编辑或删除您提供的服务器。需要 Claude Code v2.1.259 或更高版本。5421从托管设置向每个用户提供远程 MCP 服务器。用户保留他们自己添加的服务器，无法编辑或删除您提供的服务器。需要 Claude Code v2.1.259 或更高版本。

5417 5422

5418* **作用域**: [`Managed`](#scopes)。Claude Code 在用户、项目和本地设置中使用警告删除该密钥，并且不在 Claude Desktop 应用的代码选项卡中读取它（在第三方部署上）或在应用的 Cowork 会话中读取它，其中 Claude Desktop 提供并锁定这些会话的 MCP 服务器。5423* **作用域**: [`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)列出了条件5424* **类型**: 以服务器名称为键的对象。每个条目都具有 `http` 或 `sse` 服务器的 `.mcp.json` 形状：必需的 `https://` `url`，以及可选的 `headers`、`oauth` 和其他 HTTP 和 SSE 选项。Claude Code 删除验证失败的条目，[条目可以包含的内容](/docs/zh-CN/managed-mcp#what-an-entry-can-contain)列出了条件

5420* **默认值**: 未设置，因此托管设置不提供任何服务器5425* **默认值**: 未设置，因此托管设置不提供任何服务器

5421 5426

5422此示例提供一个名为 `search` 的 HTTP 服务器：5427此示例提供一个名为 `search` 的 HTTP 服务器：

5768 5773

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 或更高版本。5774在[桌面应用](/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 5775

5771* **作用域**: [`托管`](#scopes)5776* **作用域**: [`托管`](#scopes)。默认情况下，桌面应用从[一个托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)读取此键。

5772* **类型**: 布尔值；仅 JSON 布尔值 `true` 生效5777* **类型**: 布尔值；仅 JSON 布尔值 `true` 生效

5773 * `true`: 桌面应用不提供设备上的 Code 会话；现有本地会话保留在列表中但无法继续5778 * `true`: 桌面应用不提供设备上的 Code 会话；现有本地会话保留在列表中但无法继续

5774 * `false`: 本地会话保持可用5779 * `false`: 本地会话保持可用

5915 5920

5916将 SSH 连接添加到[桌面](/docs/zh-CN/desktop#pre-configure-ssh-connections-for-your-team)环境下拉列表。管理员使用它向团队分发共享连接。你在托管设置中定义的连接显示为托管，因此用户可以选择它们，但无法在应用中编辑或删除它们。5921将 SSH 连接添加到[桌面](/docs/zh-CN/desktop#pre-configure-ssh-connections-for-your-team)环境下拉列表。管理员使用它向团队分发共享连接。你在托管设置中定义的连接显示为托管，因此用户可以选择它们，但无法在应用中编辑或删除它们。

5917 5922

5918* **作用域**: [`用户或托管`](#scopes)。桌面应用读取此键。5923* **作用域**: [`用户或托管`](#scopes)。桌面应用读取此键。默认情况下，它从[一个托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)读取托管连接。

5919* **类型**: 对象数组，每个都有必需的 `id`、`name` 和 `sshHost` 以及可选的 `sshPort` 和 `sshIdentityFile`5924* **类型**: 对象数组，每个都有必需的 `id`、`name` 和 `sshHost` 以及可选的 `sshPort` 和 `sshIdentityFile`

5920* **默认值**: 未设置5925* **默认值**: 未设置

5921 5926

5939 5944

5940限制[桌面 SSH 会话](/docs/zh-CN/desktop#restrict-which-ssh-hosts-users-can-connect-to)可以连接到的主机。仅桌面应用读取此键；CLI 不读取。模式不区分大小写：`*` 匹配任何主机，`*.example.com` 匹配 `example.com` 和每个子域，其他任何内容都是针对 `~/.ssh/config` 解析后的主机名的精确匹配。空数组关闭 SSH 会话。5945限制[桌面 SSH 会话](/docs/zh-CN/desktop#restrict-which-ssh-hosts-users-can-connect-to)可以连接到的主机。仅桌面应用读取此键；CLI 不读取。模式不区分大小写：`*` 匹配任何主机，`*.example.com` 匹配 `example.com` 和每个子域，其他任何内容都是针对 `~/.ssh/config` 解析后的主机名的精确匹配。空数组关闭 SSH 会话。

5941 5946

5942* **作用域**: [`托管`](#scopes)5947* **作用域**: [`托管`](#scopes)。默认情况下，桌面应用从[一个托管源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)读取此键。

5943* **类型**: 主机名模式数组5948* **类型**: 主机名模式数组

5944* **默认值**: 未设置，因此允许任何主机5949* **默认值**: 未设置，因此允许任何主机

5945 5950

5951}5956}

5952```5957```

5953 5958

5959桌面应用无法读取为主机列表的值（例如 `true` 或对象）在您更正之前会被视为空数组，但 `null` 除外，它被视为未设置。需要 Claude Desktop v2.26454.0 或更高版本。

5960

5961如果您在优先级最高的源中将 [`managedSourcesBehavior`](#managedsourcesbehavior) 设置为 `"merge"`，桌面应用会合并来自每个[管理员源](/docs/zh-CN/managed-settings#how-claude-code-combines-managed-sources)的列表，并允许与其中任意一个列表匹配的主机。如果您在某个源中设置了空数组，对于另一个源列出的主机，SSH 会话仍保持开启。

5962

5954<span id="authentication-and-login" />5963<span id="authentication-and-login" />

5955 5964

5956<h2 id="authentication-and-providers">5965<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 +2 −0

Details

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) 窗口。

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 +1 −0

Details

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 20:59 UTC