Documentation 2026-10-07 23:59 UTC to 2026-10-08 18:01 UTC

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 

547| **管理** | 在文件系统上 | CLI + 文件 | 在代码中 | 在代码中 |547| **管理** | 在文件系统上 | CLI + 文件 | 在代码中 | 在代码中 |

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

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

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

551| **版本控制** | 与项目一起 | 是 | 与代码一起 | 与代码一起 |551| **版本控制** | 与项目一起 | 是 | 与代码一起 | 与代码一起 |

552| **范围** | 项目特定 | 用户或项目 | 代码会话 | 代码会话 |552| **范围** | 项目特定 | 用户或项目 | 代码会话 | 代码会话 |

553 553 

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 类型

2788 "model": "sonnet" | "opus" | "haiku" | "fable" | None, # 此 Agent 的模型覆盖2788 "model": "sonnet" | "opus" | "haiku" | "fable" | None, # 此 Agent 的模型覆盖

2789 "run_in_background": bool | None, # Agent 默认在后台运行；设置为 False 以同步运行2789 "effort": "low" | "medium" | "high" | "xhigh" | "max" | 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 的名称

2792 "mode": "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan" | None, # 已弃用；被忽略。子代理继承规则决定子代理的权限模式2792 "team_name": str | None, # 已弃用；会被忽略

2793 "isolation": "worktree" | "remote" | None, # Agent 更改的隔离模式2793 "mode": "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan" | None, # 已弃用；会被忽略。子代理的权限模式由子代理继承规则决定

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 编码的图像数据

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

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{

3265 "mode": "content" | "files_with_matches" | "count" | None, # 使用的输出模式3266 "mode": "content" | "files_with_matches" | "count" | None, # 所使用的输出模式

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 

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` 在此顺序中排在第一位。

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 

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.`

296 298 

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

298 300 

876 878 

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

878 880 

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

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

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

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

1093| 版本 | 更改 |1095| 版本 | 更改 |

1094| - | - |1096| - | - |

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

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

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

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

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

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

206 

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

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

174 209 

175**选项 E：Amazon Bedrock API 密钥**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 

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

6 6 

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

8 8 

9<Info>

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

11 

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

13 

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

15</Info>

16 

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>

23 

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>

81 

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

83 

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

86 

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

88 

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

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">

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 

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、插件、连接器和工具引入线程

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" />

97 

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">