Documentation 2026-10-28 23:57 UTC to 2026-10-29 23:57 UTC

75| :- | :- | :- |75| :- | :- | :- |

76| `"project"` | 项目 `settings.json` 和 hooks；项目 CLAUDE.md 和 `.claude/rules/*.md`；项目 skills、commands 和 subagents | `<cwd>/.claude/` 用于 `settings.json` 和 hooks；`<cwd>` 和每个父目录用于 CLAUDE.md 和规则；`<cwd>` 和每个父目录直到存储库根目录用于 skills、commands 和 subagents，加上您通过 `additionalDirectories` 或 `add_dirs` 选项传递的每个目录的 `.claude/skills/`、`.claude/commands/` 和 `.claude/agents/` 文件夹，SDK 将其作为 [`--add-dir`](https://code.claude.com/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) 传递给 Claude Code |76| `"project"` | 项目 `settings.json` 和 hooks；项目 CLAUDE.md 和 `.claude/rules/*.md`；项目 skills、commands 和 subagents | `<cwd>/.claude/` 用于 `settings.json` 和 hooks；`<cwd>` 和每个父目录用于 CLAUDE.md 和规则；`<cwd>` 和每个父目录直到存储库根目录用于 skills、commands 和 subagents，加上您通过 `additionalDirectories` 或 `add_dirs` 选项传递的每个目录的 `.claude/skills/`、`.claude/commands/` 和 `.claude/agents/` 文件夹，SDK 将其作为 [`--add-dir`](https://code.claude.com/docs/zh-CN/permissions#additional-directories-grant-file-access-not-configuration) 传递给 Claude Code |

77| `"user"` | 用户 `settings.json`；用户 CLAUDE.md 和 `~/.claude/rules/*.md`；用户 skills、commands 和 subagents | `~/.claude/` 用于 `settings.json`、CLAUDE.md 和规则；`~/.claude/skills/`、`~/.claude/commands/` 和 `~/.claude/agents/` 用于 skills、commands 和 subagents |77| `"user"` | 用户 `settings.json`；用户 CLAUDE.md 和 `~/.claude/rules/*.md`；用户 skills、commands 和 subagents | `~/.claude/` 用于 `settings.json`、CLAUDE.md 和规则；`~/.claude/skills/`、`~/.claude/commands/` 和 `~/.claude/agents/` 用于 skills、commands 和 subagents |

78| `"local"` | CLAUDE.local.md、`.claude/settings.local.json` | `<cwd>/.claude/` 用于 `settings.local.json`；`<cwd>` 和每个父目录用于 CLAUDE.local.md |78| `"local"` | CLAUDE.local.md、`.claude/settings.local.json` | `<cwd>/.claude/` 用于 `settings.local.json`，当 `<cwd>` 位于 git 仓库内时，该文件[也可以从仓库根目录加载](https://code.claude.com/docs/zh-CN/settings.md#where-claude-code-keeps-the-local-file-in-a-git-repository)；`<cwd>` 和每个父目录用于 CLAUDE.local.md |

79 79 

80省略 `settingSources` 等同于 `["user", "project", "local"]`。80省略 `settingSources` 等同于 `["user", "project", "local"]`。

81 81 

82`cwd` 选项确定 SDK 查找项目级输入的位置。项目 `settings.json` 和 hooks 仅从 `<cwd>/.claude/` 加载，没有父目录回退。82`cwd` 选项确定 SDK 查找项目级输入的位置。项目 `settings.json` 从 `<cwd>/.claude/` 加载，没有父目录回退。

83 83 

84### settingSources 不控制的内容84### settingSources 不控制的内容

85 85 

3322 3322 

3323### TaskStop3323### TaskStop

3324 3324 

3325**工具名称：** `TaskStop`。先前的名称 `KillShell` 和 `KillBash` 仍作为别名被接受。3325**工具名称：** `TaskStop`。您仍然可以在权限规则、hook 匹配器以及 `tools`、`allowed_tools` 和 `disallowed_tools` 选项中使用先前的名称 `KillShell` 和 `KillBash`。

3326 3326 

3327**输入：**3327**输入：**

3328 3328 

258 258 

259### 双写架构259### 双写架构

260 260 

261Claude Code 子进程始终首先将每批转录条目写入本地磁盘，然后 SDK 将同一批转发到您的存储的 `append()`，因此存储是本地转录的镜像而不是替代品。哪个副本在运行后保留取决于运行的启动方式：261Claude Code 子进程始终首先将每批会话记录条目写入本地磁盘，然后 SDK 将同一批转发到您的存储的 `append()`，因此存储是本地会话记录的镜像而不是替代品。哪个副本在运行后保留取决于运行的启动方式：

262 262 

263* **新会话，或当存储对该会话没有任何内容时的恢复**：您配置目录下的本地转录在运行后保留，存储接收一个副本。263* **新会话，或当存储对该会话没有任何内容时的恢复**：您配置目录下的本地会话记录在运行后保留，存储接收一个副本。

264* **从存储[恢复的运行](#resume-from-the-store)**：本地副本在运行结束时被删除，因此存储持有唯一的持久副本。264* **从存储[恢复的运行](#resume-from-the-store)**：本地副本在运行结束时被删除，因此存储持有唯一的持久副本。

265 265 

266如果您不希望新会话在本地磁盘上留下转录，请在 `options.env` 中将 `CLAUDE_CONFIG_DIR` 设置为临时目录。从存储恢复的运行已经删除其本地副本，因此不需要此类设置。在 TypeScript 中，也将 `process.env` 展开到 `env` 中，因为 [`env` 选项](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#options) 替换子进程环境。266如果您不希望新会话在本地磁盘上留下会话记录，请在 `options.env` 中将 `CLAUDE_CONFIG_DIR` 设置为一个新的私有临时目录。从存储恢复的运行已经删除其本地副本，因此不需要此类设置。在 TypeScript 中，也将 `process.env` 展开到 `env` 中，因为 [`env` 选项](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#options) 替换子进程环境。

267 267 

268如果您的应用通过配置目录中的文件进行登录，例如 OAuth 凭证或用户 `settings.json` 中的 `apiKeyHelper`，请先将这些文件复制到临时目录中，或改为在 `env` 中设置 `ANTHROPIC_API_KEY`。否则运行失败并显示 `Not logged in`。268如果您将 `CLAUDE_CONFIG_DIR` 设置为临时目录，并通过 [claude.ai 登录](https://code.claude.com/docs/zh-CN/authentication.md#credential-management)或用户 `settings.json` 中的 [`apiKeyHelper`](https://code.claude.com/docs/zh-CN/settings-reference#apikeyhelper) 进行登录，运行将失败并显示 `Not logged in`。要对运行进行身份验证，请设置长期令牌、设置 API 密钥或复制您的配置文件：

269 

270* **长期令牌**：如果您使用自己的 Claude 订阅亲自运行 Agent，请在 `env` 中将 `CLAUDE_CODE_OAUTH_TOKEN` 设置为通过 [`claude setup-token`](https://code.claude.com/docs/zh-CN/authentication#generate-a-long-lived-token) 获取的令牌。该令牌只能用于发出模型请求，因此您的 [claude.ai 连接器](https://code.claude.com/docs/zh-CN/mcp.md#use-mcp-servers-from-claude-ai)在该运行中不可用。

271* **API 密钥**：在 `env` 中设置 `ANTHROPIC_API_KEY`。

272* **配置文件**：如果您通过常用配置目录中的文件登录，例如 OAuth 凭据或用户 `settings.json` 中的 `apiKeyHelper`，请将这些文件复制到临时目录中。

269 273 

270两个选项与镜像冲突，如果您将其中任何一个与存储结合，SDK 会在启动时抛出异常：274两个选项与镜像冲突，如果您将其中任何一个与存储结合，SDK 会在启动时抛出异常：

271 275 

272* **`persistSession: false`** 在 TypeScript 中：关闭镜像所基于的本地写入。Python SDK 没有等效选项。276* **`persistSession: false`** 在 TypeScript 中：关闭镜像所基于的本地写入。Python SDK 没有等效选项。

273* **文件检查点**，TypeScript 中的 `enableFileCheckpointing` 或 Python 中的 `enable_file_checkpointing`：将其文件备份直接写入本地磁盘，SDK 不会将其镜像到存储。277* **文件检查点功能**，TypeScript 中的 `enableFileCheckpointing` 或 Python 中的 `enable_file_checkpointing`：将其文件备份直接写入本地磁盘，SDK 不会将其镜像到存储。

274 278 

275### 从存储恢复279### 从存储恢复

276 280 

277当您传递 `resume`，或 TypeScript 中的 `continue: true` 或 Python 中的 `continue_conversation=True`，以及存储时，SDK 在生成子进程之前向存储请求转录：281当您传递 `resume`，或 TypeScript 中的 `continue: true` 或 Python 中的 `continue_conversation=True`，以及存储时，SDK 在生成子进程之前向存储请求会话记录：

278 282 

279* **`resume`**：SDK 请求您传递的会话 ID 的会话。283* **`resume`**：SDK 请求您传递的会话 ID 的会话。

280* **`continue: true`** 或 **`continue_conversation=True`**：SDK 请求存储的最新会话。284* **`continue: true`** 或 **`continue_conversation=True`**：SDK 请求存储的最新会话。

281 285 

282当存储返回转录时，SDK 将其写入临时配置目录，运行子进程时 `CLAUDE_CONFIG_DIR` 指向该目录，并在运行结束时删除该目录。该运行写入的本地转录随之被删除，这就是为什么存储在此路径上持有唯一的持久副本的原因。286当存储返回会话记录时，SDK 将其写入临时配置目录，运行子进程时 `CLAUDE_CONFIG_DIR` 指向该目录，并在运行结束时删除该目录。该运行写入的本地会话记录随之被删除，这就是为什么存储在此路径上持有唯一的持久副本的原因。

283 287 

284SDK 还使用来自您真实配置目录的文件为临时目录提供种子。它复制的内容因语言而异：288SDK 还使用来自您真实配置目录的文件为临时目录提供种子。它复制的内容因语言而异：

285 289 

286* **TypeScript**：凭证、`.claude.json` 和您的用户 `settings.json`。从 `settings.json` 中，它删除在临时配置目录下表现不佳的键：`enabledPlugins`、`extraKnownMarketplaces`、其 [`additionalMarketplaces`](https://code.claude.com/docs/zh-CN/settings-reference#extraknownmarketplaces) 别名，以及文件 `env` 块中的任何 `CLAUDE_CONFIG_DIR`。在 Agent SDK v0.3.232 之前，SDK 没有删除别名。在设置中配置的身份验证，例如 [`apiKeyHelper`](https://code.claude.com/docs/zh-CN/settings-reference#apikeyhelper)，在从存储恢复时有效。在 Agent SDK v0.3.222 之前，TypeScript SDK 仅复制凭证和 `.claude.json`。290* **TypeScript**：凭据、`.claude.json` 和您的用户 `settings.json`。从 `settings.json` 中，它删除在临时配置目录下表现不佳的键：`enabledPlugins`、`extraKnownMarketplaces`、其 [`additionalMarketplaces`](https://code.claude.com/docs/zh-CN/settings-reference#extraknownmarketplaces) 别名，以及文件 `env` 块中的任何 `CLAUDE_CONFIG_DIR`。在 Agent SDK v0.3.232 之前，SDK 没有删除别名。在设置中配置的身份验证，例如 [`apiKeyHelper`](https://code.claude.com/docs/zh-CN/settings-reference#apikeyhelper)，在从存储恢复时有效。在 Agent SDK v0.3.222 之前，TypeScript SDK 仅复制凭据和 `.claude.json`。

287* **Python**：仅凭证和 `.claude.json`，因此通过用户 `settings.json` 中的 `apiKeyHelper` 进行身份验证的应用在从存储恢复时失败并显示 `Not logged in`。托管或项目设置中的 `apiKeyHelper` 仍然有效，因为 Claude Code 从 `CLAUDE_CONFIG_DIR` 不影响的位置读取这些文件。291* **Python**：仅凭据和 `.claude.json`，因此通过用户 `settings.json` 中的 `apiKeyHelper` 进行身份验证的应用在从存储恢复时失败并显示 `Not logged in`。托管或项目设置中的 `apiKeyHelper` 仍然有效，因为 Claude Code 从 `CLAUDE_CONFIG_DIR` 不影响的位置读取这些文件。

288 292 

289当存储对该会话没有任何内容时，SDK 改为在您的真实配置目录下运行，结果取决于您传递的选项：293当存储对该会话没有任何内容时，SDK 改为在您的真实配置目录下运行，结果取决于您传递的选项：

290 294 

291* **`resume`**：两个 SDK 都将 ID 传递给子进程，子进程恢复本地转录，完全如同没有存储的 `resume` 一样。295* **`resume`**：两个 SDK 都将 ID 传递给子进程，子进程恢复本地会话记录，完全如同没有存储的 `resume` 一样。

292* **TypeScript 中的 `continue: true`**：SDK 启动新会话。296* **TypeScript 中的 `continue: true`**：SDK 启动新会话。

293* **Python 中的 `continue_conversation=True`**：SDK 从最新的本地会话继续。297* **Python 中的 `continue_conversation=True`**：SDK 从最新的本地会话继续。

294 298 

296 300 

297如果 `append()` 拒绝，SDK 会以短退避重试该批次最多两次，总共最多三次尝试。超时的调用不会重试，因为原始调用可能仍然会成功。如果批次仍然失败，SDK 记录错误，向迭代器发出 `{ type: "system", subtype: "mirror_error" }` 消息，丢弃批次，并继续查询。因为重试的批次可以重新传递已经成功的条目，请在您的 `append()` 实现中按 `entry.uuid` 进行去重。301如果 `append()` 拒绝，SDK 会以短退避重试该批次最多两次，总共最多三次尝试。超时的调用不会重试，因为原始调用可能仍然会成功。如果批次仍然失败，SDK 记录错误，向迭代器发出 `{ type: "system", subtype: "mirror_error" }` 消息，丢弃批次，并继续查询。因为重试的批次可以重新传递已经成功的条目，请在您的 `append()` 实现中按 `entry.uuid` 进行去重。

298 302 

299存储中断不会中断代理，因为子进程首先在本地写入。如果您需要检测存储数据丢失，请监视 `mirror_error`。在[从存储恢复](#resume-from-the-store)的运行上，丢弃的批次在运行结束后没有幸存的副本。303存储中断不会中断 Agent，因为子进程首先在本地写入。如果您需要检测存储数据丢失，请监视 `mirror_error`。在[从存储恢复](#resume-from-the-store)的运行上，丢弃的批次在运行结束后没有幸存的副本。

300 304 

301### `getSessionMessages` 返回后压缩链305### `getSessionMessages` 返回后压缩链

302 306 

303`getSessionMessages({ sessionStore })` 返回代理在恢复时会看到的链接消息链。自动压缩后，早期的轮次被摘要替换，因此存储中包含 503 个原始条目的会话可能从 `getSessionMessages` 返回 18 条消息。对于完整的原始历史记录，包括压缩前的轮次和元数据条目，直接调用 `store.load(key)`。307`getSessionMessages({ sessionStore })` 返回 Agent 在恢复时会看到的链接消息链。自动压缩后，早期的轮次被摘要替换，因此存储中包含 503 个原始条目的会话可能从 `getSessionMessages` 返回 18 条消息。对于完整的原始历史记录，包括压缩前的轮次和元数据条目，直接调用 `store.load(key)`。

304 308 

305### `forkSession` 不是字节副本309### `forkSession` 不是字节副本

306 310 

307`forkSession({ sessionStore })` 读取源条目，重写每个 `sessionId` 字段并重新映射消息 UUID，然后在新键下追加转换后的条目。适配器级别的副本或 `CopyObject` 快捷方式会产生仍然引用旧会话 ID 的转录，因此 SDK 不使用它。311`forkSession({ sessionStore })` 读取源条目，重写每个 `sessionId` 字段并重新映射消息 UUID，然后在新键下追加转换后的条目。适配器级别的副本或 `CopyObject` 快捷方式会产生仍然引用旧会话 ID 的会话记录，因此 SDK 不使用它。

308 312 

309### 子代理转录313### 子代理会话记录

310 314 

311子代理转录在 `subpath: "subagents/agent-<id>"` 下镜像。`listSubagents({ sessionStore })` 要求适配器实现 `listSubkeys`；`getSubagentMessages({ sessionStore })` 在可用时使用它，但在未定义时回退到直接子路径。恢复也调用 `listSubkeys` 来恢复子代理文件；没有它，仅实现主转录。315子代理会话记录在 `subpath: "subagents/agent-<id>"` 下镜像。`listSubagents({ sessionStore })` 要求适配器实现 `listSubkeys`；`getSubagentMessages({ sessionStore })` 在可用时使用它，但在未定义时回退到直接子路径。恢复也调用 `listSubkeys` 来恢复子代理文件；没有它，仅实现主会话记录。

312 316 

313### 保留317### 保留

314 318 

315SDK 永远不会自行从您的存储中删除。保留是适配器的责任：根据您的合规要求实现 TTL、S3 生命周期策略或计划清理。`CLAUDE_CONFIG_DIR` 下的本地转录由 `cleanupPeriodDays` 设置独立清理，遵循[保留清理规则](https://code.claude.com/docs/zh-CN/claude-directory.md#cleaned-up-automatically)。[从存储恢复](#resume-from-the-store)的运行不留下本地转录，因此对于这些运行，您的存储保留是唯一的保留。319SDK 永远不会自行从您的存储中删除。保留是适配器的责任：根据您的合规要求，使用您后端的过期或生命周期机制，或运行计划清理。

320 

321`CLAUDE_CONFIG_DIR` 下的本地会话记录由 `cleanupPeriodDays` 设置独立清理，遵循[保留清理规则](https://code.claude.com/docs/zh-CN/claude-directory.md#cleaned-up-automatically)。[从存储恢复](#resume-from-the-store)的运行不留下本地会话记录，因此对于这些运行，您的存储保留是唯一的保留。

316 322 

317## 支持的功能323## 支持的功能

318 324 

730 730 

731只有部分键会在会话中途生效：731只有部分键会在会话中途生效：

732 732 

733* **在下一轮生效**：`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。切换 `agent` 还会在下一轮应用该 Agent 的模型覆盖和 hook。其系统提示词在下一轮生效；或者，在[复用已记录系统提示词](https://code.claude.com/docs/zh-CN/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session)的会话中，在会话被压缩后生效。733* **在下一轮生效**：`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。切换 `agent` 还会在下一轮应用该 Agent 的模型覆盖和 hook。其系统提示词在下一轮生效。在[复用已记录系统提示词](https://code.claude.com/docs/zh-CN/agent-sdk/modifying-system-prompts.md#change-the-prompt-of-an-existing-session)的会话中，它会在会话被压缩后生效。

734* **在当前轮次生效**：`model`。如果您在 Claude 处理某一轮时切换 `model`，Claude 正在生成的回复会使用旧模型完成，而该轮的其余部分（从 Claude Code 对模型发起的下一次调用开始）会使用新模型。子代理保留各自的模型。在 v2.1.212 之前，轮次中途的切换会等到下一轮才生效。734* **在当前轮次生效**：`model`。如果您在 Claude 处理某一轮时切换 `model`，Claude 正在生成的回复会使用旧模型完成，而该轮的其余部分（从 Claude Code 对模型发起的下一次调用开始）会使用新模型。子代理保留各自的模型。在 v2.1.212 之前，轮次中途的切换会等到下一轮才生效。

735* **最迟在下一轮生效**：`effortLevel`。该级别从 Claude Code 对模型的下一次调用开始生效。如果[更改 effort 会保留提示缓存](https://code.claude.com/docs/zh-CN/prompt-caching.md#changing-effort-level)（例如在使用 API 密钥或 Claude 订阅的 Claude Opus 5.5 上），则预计会在下一轮生效。

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

736 737 

737`effortLevel` 接受一个 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)名称。它还接受 `"ultracode"`，表示请求 `xhigh` effort 并开启 [ultracode](https://code.claude.com/docs/zh-CN/workflows.md#let-claude-decide-with-ultracode)。`applyFlagSettings()` 声明的 `effortLevel` 不包含该值，因此在 TypeScript 中请传递 `{ ultracode: true, effortLevel: "xhigh" }` 以获得相同效果，或者单独传递 [`ultracode`](https://code.claude.com/docs/zh-CN/settings-reference#ultracode) 键，以在会话当前的 effort 级别下开启 ultracode。`ultracode` 值需要 Claude Code v2.1.203 或更高版本，并且只被 `applyFlagSettings()` 接受，设置文件中的 `effortLevel` 键不接受该值。在 v2.1.284 之前，单独传递 `ultracode` 键也会将级别设置为 `xhigh`。738`effortLevel` 接受一个 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)名称。它还接受 `"ultracode"`，表示请求 `xhigh` effort 并开启 [ultracode](https://code.claude.com/docs/zh-CN/workflows.md#let-claude-decide-with-ultracode)。`applyFlagSettings()` 声明的 `effortLevel` 不包含该值，因此在 TypeScript 中请传递 `{ ultracode: true, effortLevel: "xhigh" }` 以获得相同效果，或者单独传递 [`ultracode`](https://code.claude.com/docs/zh-CN/settings-reference#ultracode) 键，以在会话当前的 effort 级别下开启 ultracode。`ultracode` 值需要 Claude Code v2.1.203 或更高版本，并且只被 `applyFlagSettings()` 接受，设置文件中的 `effortLevel` 键不接受该值。在 v2.1.284 之前，单独传递 `ultracode` 键也会将级别设置为 `xhigh`。

738 739 

739这些值会写入标志设置层，合并在 `query()` 的内联 `settings` 选项于启动时设置的值之上。这与[本页优先级部分](#settings-precedence)所称的编程选项属于同一层级。740这些值会写入标志设置层，合并覆盖在启动时 `query()` 的内联 `settings` 选项所设置的内容之上。这与[本页优先级章节](#settings-precedence)中所称的编程选项属于同一层级。`effortLevel` 是个例外：如 [effort 解析顺序](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)所示，您传递的级别会替换来自 `--effort` 或设置（包括托管设置）的级别。

740 741 

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

742 743 

13272. 项目设置（`.claude/settings.json`）13282. 项目设置（`.claude/settings.json`）

13283. 用户设置（`~/.claude/settings.json`）13293. 用户设置（`~/.claude/settings.json`）

1329 1330 

1330`agents`、`allowedTools` 和 `settings` 等编程选项会覆盖用户、项目和本地文件系统设置。托管策略设置优先于编程选项。1331`agents`、`allowedTools` 和 `settings` 等编程选项会覆盖用户、项目和本地文件系统设置。如果托管策略设置和编程选项设置了相同的键，则以托管值为准，但存在例外，例如传给 [`applyFlagSettings()`](#applyflagsettings) 的 `effortLevel`。

1331 1332 

1332### `PermissionMode`1333### `PermissionMode`

1333 1334 

2095`terminal_slash_commands` 命名 `slash_commands` 中的条目，其接口绑定到本地终端，例如 `exit`。您可以像 `slash_commands` 中的任何其他条目一样发送它们；该字段存在以便远程或移动客户端可以从其命令菜单中隐藏它们。该字段仅在非空时存在，需要 Agent SDK v0.3.229 或更高版本。2096`terminal_slash_commands` 命名 `slash_commands` 中的条目，其接口绑定到本地终端，例如 `exit`。您可以像 `slash_commands` 中的任何其他条目一样发送它们；该字段存在以便远程或移动客户端可以从其命令菜单中隐藏它们。该字段仅在非空时存在，需要 Agent SDK v0.3.229 或更高版本。

2096 2097 

2097* `source` 在每个 `mcp_servers` 条目上：服务器定义的来源，与 [`McpServerStatus`](#mcpserverstatus) 的 `source` 值相同。需要 Agent SDK v0.3.274 或更高版本。2098* `source` 在每个 `mcp_servers` 条目上：服务器定义的来源，与 [`McpServerStatus`](#mcpserverstatus) 的 `source` 值相同。需要 Agent SDK v0.3.274 或更高版本。

2098* `effort`：Claude Code 在会话的下一个请求上发送的 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)，或当它不发送任何时为 `null`。Claude Code 仅在它发送到 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 客户端的初始化消息上设置该字段，并从您的应用程序读取的初始化消息中省略它。需要 Agent SDK v0.3.234 或更高版本。2099* `effort`：为会话下一轮次设置的 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)，当 Claude Code 不发送任何级别时为 `null`。Claude Code 仅在发送给 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 客户端的 init 消息上设置该字段，并在您的应用读取的 init 消息中省略它。需要 Agent SDK v0.3.234 或更高版本。

2099 2100 

2100`capabilities` 数组命名此 CLI 实现的协议行为，因此您可以进行功能检测而不是比较 `claude_code_version` 字符串。这是一个开放集：忽略您不认识的值，并检查您依赖其行为的特定功能。该字段需要 Claude Code v2.1.205 或更高版本，在早期 CLI 上不存在。2101`capabilities` 数组命名此 CLI 实现的协议行为，因此您可以进行功能检测而不是比较 `claude_code_version` 字符串。这是一个开放集：忽略您不认识的值，并检查您依赖其行为的特定功能。该字段需要 Claude Code v2.1.205 或更高版本，在早期 CLI 上不存在。

2101 2102 

369| 要求 | 可用时间 |369| 要求 | 可用时间 |

370| :- | :- |370| :- | :- |

371| 计划 | Pro、Max、Team 或 Enterprise。在 Pro 和 Max 计划上，artifacts 仅对您私有，直到您共享它们，不适用任何管理员管理。在 Team 和 Enterprise 计划上，artifacts 默认启用，Owner 可以在 claude.ai 管理设置中 [关闭它们](#manage-artifacts-for-your-organization)。 |371| 计划 | Pro、Max、Team 或 Enterprise。在 Pro 和 Max 计划上，artifacts 仅对您私有，直到您共享它们，不适用任何管理员管理。在 Team 和 Enterprise 计划上，artifacts 默认启用，Owner 可以在 claude.ai 管理设置中 [关闭它们](#manage-artifacts-for-your-organization)。 |

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

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

374| 组织策略 | 客户管理的加密密钥 (CMEK)、HIPAA 和 [零数据保留](https://code.claude.com/docs/zh-CN/zero-data-retention.md) 未为组织启用。 |374| 组织策略 | 客户管理的加密密钥 (CMEK)、HIPAA 和 [零数据保留](https://code.claude.com/docs/zh-CN/zero-data-retention.md) 未为组织启用。 |

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

353 353 

354| 功能 | 它做什么 | 适合 |354| 功能 | 它做什么 | 适合 |

355| - | - | - |355| - | - | - |

356| [网络上的 Claude Code](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md) | 在新的云沙箱中运行任务，从 GitHub 克隆 | 委派您稍后检查的自包含异步工作 |356| [云端会话](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md) | 在新的云沙箱中运行任务，从 GitHub 克隆 | 委派您稍后检查的自包含异步工作 |

357| [Slack 中的 Claude](https://code.claude.com/docs/zh-CN/slack.md) | 从频道或线程中的 `@Claude` 提及生成网络会话 | 直接从团队对话上下文启动任务 |357| [Slack 中的 Claude](https://code.claude.com/docs/zh-CN/slack.md) | 从频道或线程中的 `@Claude` 提及生成云端会话 | 直接从团队对话上下文启动任务 |

358| 标准 [MCP 服务器](https://code.claude.com/docs/zh-CN/mcp.md) | Claude 在任务期间查询它；没有任何内容被推送到会话 | 给 Claude 按需访问以读取或查询系统 |358| 标准 [MCP 服务器](https://code.claude.com/docs/zh-CN/mcp.md) | Claude 在任务期间查询它；没有任何内容被推送到会话 | 给 Claude 按需访问以读取或查询系统 |

359| [远程控制](https://code.claude.com/docs/zh-CN/remote-control.md) | 您从 claude.ai 或 Claude 移动应用程序驱动您的本地会话 | 在离开您的办公桌时指导进行中的会话 |359| [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) | 您从 claude.ai 或 Claude 移动应用程序驱动您的本地会话 | 在离开您的办公桌时指导进行中的会话 |

360 360 

361Channels 通过将来自非 Claude 源的事件推送到您已经运行的本地会话中，填补了该列表中的空白。361Channels 通过将来自非 Claude 源的事件推送到您已经运行的本地会话中，填补了该列表中的空白。

362 362 

368一旦您有一个 channel 运行，请探索这些相关功能：368一旦您有一个 channel 运行，请探索这些相关功能：

369 369 

370* [构建您自己的 channel](https://code.claude.com/docs/zh-CN/channels-reference.md)，用于尚未有插件的系统370* [构建您自己的 channel](https://code.claude.com/docs/zh-CN/channels-reference.md)，用于尚未有插件的系统

371* [远程控制](https://code.claude.com/docs/zh-CN/remote-control.md)，从您的手机驱动本地会话，而不是将事件转发到其中371* [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md)，从您的手机驱动本地会话，而不是将事件转发到其中

372* [会话范围的定时任务](https://code.claude.com/docs/zh-CN/scheduled-tasks.md)，按计时器轮询而不是对推送事件做出反应372* [会话范围的定时任务](https://code.claude.com/docs/zh-CN/scheduled-tasks.md)，按计时器轮询而不是对推送事件做出反应

107>107>

108> 默认启用 Chrome 会增加上下文使用量，因为浏览器工具及其说明会始终被加载。如果您注意到上下文消耗增加，请关闭该设置，仅在需要时连接：在 CLI 中使用 `--chrome`，或在 VS Code 输入框中输入 [`@browser`](https://code.claude.com/docs/zh-CN/vs-code#automate-browser-tasks-with-chrome)。108> 默认启用 Chrome 会增加上下文使用量，因为浏览器工具及其说明会始终被加载。如果您注意到上下文消耗增加，请关闭该设置，仅在需要时连接：在 CLI 中使用 `--chrome`，或在 VS Code 输入框中输入 [`@browser`](https://code.claude.com/docs/zh-CN/vs-code#automate-browser-tasks-with-chrome)。

109 109 

110### 回答启动对话框

111 

112如果启动 `claude` 时出现“Claude in Chrome extension detected”对话框，您的回答会更改[**默认启用**设置](#enable-chrome-by-default)：

113 

114* **Yes, use my browser**：启用该设置并连接本次会话

115* **No, keep browser tools off** 或 Esc：关闭该设置，Claude Code 将不再提供设置 Chrome 的选项

116 

117如需为以后的会话更改您的回答，请运行 `/chrome`。

118 

110### 管理站点权限119### 管理站点权限

111 120 

112站点级权限继承自 Chrome 扩展程序。在 Chrome 扩展程序设置中管理权限，以控制 Claude 可以在哪些站点上浏览、点击和输入。在[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)下，当自动模式分类器本身批准了对某个站点的浏览器调用时，扩展程序会跳过该调用的逐站点检查，除非您的权限规则拒绝 Claude in Chrome 访问任何站点。121站点级权限继承自 Chrome 扩展程序。在 Chrome 扩展程序设置中管理权限，以控制 Claude 可以在哪些站点上浏览、点击和输入。在[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)下，当自动模式分类器本身批准了对某个站点的浏览器调用时，扩展程序会跳过该调用的逐站点检查，除非您的权限规则拒绝 Claude in Chrome 访问任何站点。

35* **遥测**：每个配置的目标接收[OpenTelemetry Protocol (OTLP) 指标](https://code.claude.com/docs/zh-CN/monitoring-usage.md)，默认包含 token 计数、模型、用户身份和延迟，日志和跟踪作为按目标的选择加入。35* **遥测**：每个配置的目标接收[OpenTelemetry Protocol (OTLP) 指标](https://code.claude.com/docs/zh-CN/monitoring-usage.md)，默认包含 token 计数、模型、用户身份和延迟，日志和跟踪作为按目标的选择加入。

36* **上游路由**：客户端向网关发送 Anthropic Messages API，网关为每个上游进行转换，无论是 Amazon Bedrock、[AWS 上的 Claude Platform](https://code.claude.com/docs/zh-CN/claude-platform-on-aws.md)、Google Cloud 的 Agent Platform、Microsoft Foundry 还是 Anthropic API，并在它们之间进行故障转移。您可以更改区域、提供商或故障转移顺序，而开发人员无需注意或重新配置。36* **上游路由**：客户端向网关发送 Anthropic Messages API，网关为每个上游进行转换，无论是 Amazon Bedrock、[AWS 上的 Claude Platform](https://code.claude.com/docs/zh-CN/claude-platform-on-aws.md)、Google Cloud 的 Agent Platform、Microsoft Foundry 还是 Anthropic API，并在它们之间进行故障转移。您可以更改区域、提供商或故障转移顺序，而开发人员无需注意或重新配置。

37 37 

38![显示 Claude Code 客户端和 Claude Desktop 的 Chat、Cowork 和 Code 选项卡通过 HTTPS 和持有者令牌连接到基础设施内自托管的 Claude apps gateway 的图表，网关通过您的 IdP 让用户登录，在 PostgreSQL 中存储身份验证状态，将遥测转发到您的 OTLP 收集器，并将推理转发到 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud、Microsoft Foundry 或 Anthropic API](https://mintcdn.com/claude-code/VbyXug8hBU9UK6oT/images/claude-gateway-architecture.svg?fit=max\&auto=format\&n=VbyXug8hBU9UK6oT\&q=85\&s=9e4f1190fc56718144190a3db61c63af)38![显示 Claude Code 客户端和 Claude Desktop 通过 HTTPS 和持有者令牌连接到您基础设施内自托管的 Claude apps gateway 的图表，网关通过您的 IdP 让用户登录，在 PostgreSQL 中存储身份验证状态，将遥测中继到您的 OTLP 收集器，并将推理转发到 Amazon Bedrock、AWS 上的 Claude Platform、Google Cloud、Microsoft Foundry 或 Anthropic API](https://mintcdn.com/claude-code/VbyXug8hBU9UK6oT/images/claude-gateway-architecture.svg?fit=max\&auto=format\&n=VbyXug8hBU9UK6oT\&q=85\&s=9e4f1190fc56718144190a3db61c63af)

39 39 

40> [!NOTE]40> [!NOTE]

41>41>

350 350 

351### 向 Claude Desktop 会话传递策略351### 向 Claude Desktop 会话传递策略

352 352 

353Claude Desktop 在嵌入式 Claude Code 会话上运行其 Cowork 和 Code 标签页（以及在您启用时的 Chat 标签页），并通过网关发送这些会话的模型请求。它会向每个这样的会话传递策略，该策略基于网关在 `/user/bootstrap` 提供给它的配置构建：模型允许列表、已禁用的工具，以及从匹配策略的 `cli` 或 `code` 块派生的出站允许列表，外加 [`desktop` 覆盖层](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#claude-desktop-overlay)。353Claude Desktop 的 Cowork 和 Code 标签页（以及启用后的 Chat）运行在嵌入式 Claude Code 会话之上，并通过网关发送其模型请求。它会向每个这样的会话传递策略，这些策略基于网关在 `/user/bootstrap` 处提供给它的配置构建：即从匹配策略的 `cli` 或 `code` 块派生出的模型允许列表、禁用的工具和出站允许列表，外加 [`desktop` 覆盖层](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#claude-desktop-overlay)。

354 354 

355该块中的其他键，例如 hook、`env` 以及 `Bash(npm *)` 这类限定范围的权限规则，会到达通过 `/login` 登录的客户端。在 `code` 下，当满足 [Code 标签页的条件](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config.md#apply-code-settings-in-the-code-tab)时，它们也会到达 Code 标签页的会话。它们不会到达 Cowork 或 Chat 会话。Claude Desktop 从其自身的托管配置中读取网关 URL，并使用自己的流程登录，与[设置网关 URL](#set-the-gateway-url) 中的 `forceLoginMethod` 和 `forceLoginGatewayUrl` 键无关。355该块中的其他键，例如 hook、`env` 以及 `Bash(npm *)` 这类限定范围的权限规则，会到达通过 `/login` 登录的客户端。在 `code` 下，当满足 [Code 标签页的条件](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config.md#apply-code-settings-in-the-code-tab)时，它们也会到达 Code 标签页的会话。它们不会到达 Cowork 或 Chat 会话。Claude Desktop 从其自身的托管配置中读取网关 URL，并使用自己的流程登录，与[设置网关 URL](#set-the-gateway-url) 中的 `forceLoginMethod` 和 `forceLoginGatewayUrl` 键无关。

356 356 

480 480 

481Claude Desktop 通过网关的身份提供商、使用相同的浏览器 SSO 步骤让开发人员登录，然后从网关而不是从 Anthropic 获取其配置。模型访问和策略遵循与 CLI 相同的按组规则。同时使用 CLI 和 Claude Desktop 的开发人员需要分别登录两者；网关会话不会在它们之间共享。481Claude Desktop 通过网关的身份提供商、使用相同的浏览器 SSO 步骤让开发人员登录，然后从网关而不是从 Anthropic 获取其配置。模型访问和策略遵循与 CLI 相同的按组规则。同时使用 CLI 和 Claude Desktop 的开发人员需要分别登录两者；网关会话不会在它们之间共享。

482 482 

483连接后，Claude Desktop 会通过网关发送来自每个已启用标签页的模型请求。它默认显示 Cowork 和 Code 标签页。要同时启用 Chat 标签页，请在 Claude Desktop 的[托管配置](https://claude.com/docs/third-party/claude-desktop/configuration)中将 `chatTabEnabled` 设置为 `true`，或者在运行 Claude Code v2.1.227 或更高版本的网关上，在策略的 [`desktop` 块](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#claude-desktop-overlay)中进行设置。483连接后，Claude Desktop 会通过网关发送来自每个已启用标签页的模型请求。它默认显示 Cowork 和 Code 标签页。要同时提供 Chat，请在运行 Claude Code v2.1.227 或更高版本的网关上，在策略的 [`desktop` 块](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#claude-desktop-overlay)中将 `chatTabEnabled` 设置为 `true`。开启 Cowork 时，Claude Desktop 随后会在一个标签页中同时显示 Chat 和 Cowork。

484 484 

485### CI 流水线和远程机器485### CI 流水线和远程机器

486 486 

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

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

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

526| Claude Desktop | 可用（需要选择加入） | 网关在 `/user/bootstrap` 处为 Claude Desktop 的配置提供服务，一旦策略[使用 `desktop` 密钥选择加入](https://code.claude.com/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 | 可用（需要选择加入） | 一旦策略[使用 `desktop` 键选择加入](https://code.claude.com/docs/zh-CN/claude-apps-gateway-config#claude-desktop-overlay)，网关就会在 `/user/bootstrap` 处提供 Claude Desktop 的配置，并且 Claude Desktop 会通过网关发送其模型请求。要启用 Chat，请参阅[连接 Claude Desktop](#connect-claude-desktop)。需要网关服务器上的 Claude Code v2.1.203 或更高版本。 |

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

528| OIDC 身份提供商 | 可用 | 任何符合 OIDC 的 IdP；网关运行标准 OIDC 发现和授权代码流。请参阅[身份提供商设置](https://code.claude.com/docs/zh-CN/claude-apps-gateway-deploy.md#identity-provider-setup)了解每个 IdP 的配置 |528| OIDC 身份提供商 | 可用 | 任何符合 OIDC 的 IdP；网关运行标准 OIDC 发现和授权代码流。请参阅[身份提供商设置](https://code.claude.com/docs/zh-CN/claude-apps-gateway-deploy.md#identity-provider-setup)了解每个 IdP 的配置 |

529| 按用户和按组支出限制 | 可用 | 请参阅[支出限制](https://code.claude.com/docs/zh-CN/claude-apps-gateway-spend-limits.md) |529| 按用户和按组支出限制 | 可用 | 请参阅[支出限制](https://code.claude.com/docs/zh-CN/claude-apps-gateway-spend-limits.md) |

201 201 

202使用以下任何方法将云会话拉入您的终端：202使用以下任何方法将云会话拉入您的终端：

203 203 

204* **使用 `--teleport`**：从命令行运行 `claude --teleport` 以获得交互式会话选择器，或 `claude --teleport <session-id>` 以直接恢复特定会话。如果您有未提交的更改，系统会提示您先隐藏它们。204* **使用 `--teleport`**：从命令行运行 `claude --teleport` 以获得交互式会话选择器，或 `claude --teleport <session-id>` 以直接恢复特定会话。如果您有未提交的更改，系统会提示您先隐藏它们。[`--resume`](https://code.claude.com/docs/zh-CN/sessions#resume-a-session) 从此机器的本地历史记录重新打开对话，不列出云端会话。

205* **使用 `/teleport`**：在现有 CLI 会话内，运行 `/teleport` 或 `/tp` 以打开相同的会话选择器，无需重启 Claude Code。205* **使用 `/teleport`**：在现有 CLI 会话内，运行 `/teleport` 或 `/tp` 以打开相同的会话选择器，无需重启 Claude Code。

206* **从 `/tasks`**：运行 `/tasks` 以查看您的后台会话，然后按 `t` 以 teleport 到其中一个。206* **从 `/tasks`**：运行 `/tasks` 以查看您的后台会话，然后按 `t` 以 teleport 到其中一个。

207* **从 claude.ai/code**：从会话菜单中选择 **Open in > Terminal** 以复制可以粘贴到终端的命令。207* **从 claude.ai/code**：从会话菜单中选择 **Open in > Terminal** 以复制可以粘贴到终端的命令。

208* **从云会话内部**：键入 `/teleport`，Claude Code 会回复该会话的确切 `claude --teleport <session-id>` 命令，准备从存储库的检出运行。需要会话环境中的 Claude Code v2.1.223 或更高版本。208* **从云会话内部**：键入 `/teleport`，Claude Code 会回复该会话的确切 `claude --teleport <session-id>` 命令，准备从存储库的检出运行。需要会话环境中的 Claude Code v2.1.223 或更高版本。

209 209 

210当您 teleport 会话时，Claude 验证您在正确的存储库中，从云会话获取并检出分支，并将完整的对话历史记录加载到您的终端。终端获得会话的自己的副本：那里的新工作保持本地，不会出现在 claude.ai 上的云会话或 Claude 移动应用中。在 teleport 后继续从您的手机引导，在本地会话中启动 [`/remote-control`](https://code.claude.com/docs/zh-CN/remote-control)。210当您 teleport 会话时，Claude 验证您在正确的仓库中，从云端会话获取并检出分支，并将对话加载到您的终端。

211 211 

212`--teleport` 与 `--resume` 不同。`--resume` 从此机器的本地历史记录重新打开对话，不列出云会话；`--teleport` 拉取云会话及其分支。212> [!NOTE]

213>

214> 如果 Claude Code 已对云端会话进行了[压缩](https://code.claude.com/docs/zh-CN/context-window.md#what-survives-compaction)（在较长的会话中会自动进行），则被其汇总的较早消息不会复制到您的终端。Claude 会从摘要继续。要阅读原始消息，请在 claude.ai 或 Claude 移动应用的云端会话中向上滚动。

215 

216终端获得会话的自己的副本：那里的新工作保持本地，不会出现在 claude.ai 上的云端会话或 Claude 移动应用中。要在 teleport 后继续从您的手机引导，请在本地会话中启动 [`/remote-control`](https://code.claude.com/docs/zh-CN/remote-control)。

213 217 

214#### Teleport 要求218#### Teleport 要求

215 219 

495* **速率限制**：云端会话与您账户内所有其他 Claude 和 Claude Code 使用共享速率限制。并行运行多个任务会按比例消耗更多速率限制。499* **速率限制**：云端会话与您账户内所有其他 Claude 和 Claude Code 使用共享速率限制。并行运行多个任务会按比例消耗更多速率限制。

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

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

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

503 * **自托管环境**：对于托管在其他 git 平台上的仓库，请参阅[使用 `--environment` 启动会话的要求](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy#start-a-session-on-a-repository-outside-github)。

499* **组织 IP 允许列表**：云端会话从 Anthropic 管理的基础设施（而非您的网络）调用 Anthropic API，而[自托管环境](https://code.claude.com/docs/zh-CN/self-hosted-environments)中的会话则从您自己的网络调用它。如果您的组织启用了 [IP 允许列表](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting)，每个 Anthropic 托管的云端会话都会因身份验证错误而失败。504* **组织 IP 允许列表**：云端会话从 Anthropic 管理的基础设施（而非您的网络）调用 Anthropic API，而[自托管环境](https://code.claude.com/docs/zh-CN/self-hosted-environments)中的会话则从您自己的网络调用它。如果您的组织启用了 [IP 允许列表](https://support.claude.com/en/articles/13200993-restrict-access-to-claude-with-ip-allowlisting)，每个 Anthropic 托管的云端会话都会因身份验证错误而失败。

500 * **Code Review 和定时任务**：这同样适用于 [Code Review](https://code.claude.com/docs/zh-CN/code-review.md) 以及在 Anthropic 托管环境中运行的[云端定时任务](https://code.claude.com/docs/zh-CN/routines.md)。路由到自托管环境的定时任务会从您自己的网络调用 API。505 * **Code Review 和定时任务**：这同样适用于 [Code Review](https://code.claude.com/docs/zh-CN/code-review.md) 以及在 Anthropic 托管环境中运行的[云端定时任务](https://code.claude.com/docs/zh-CN/routines.md)。路由到自托管环境的定时任务会从您自己的网络调用 API。

501 * **获取豁免**：请联系 [Anthropic 支持](https://support.claude.com/)，将 Anthropic 托管的服务从您组织的 IP 允许列表中豁免。506 * **获取豁免**：请联系 [Anthropic 支持](https://support.claude.com/)，将 Anthropic 托管的服务从您组织的 IP 允许列表中豁免。

8 8 

9Claude Code 从您的项目目录和主目录中的 `~/.claude` 读取指令、设置、skills、subagents 和内存。将项目文件提交到 git 以与您的团队共享；`~/.claude` 中的文件是个人配置，适用于您的所有项目。9Claude Code 从您的项目目录和主目录中的 `~/.claude` 读取指令、设置、skills、subagents 和内存。将项目文件提交到 git 以与您的团队共享；`~/.claude` 中的文件是个人配置，适用于您的所有项目。

10 10 

11在 Windows 上，`~/.claude` 解析为 `%USERPROFILE%\.claude`。如果您设置了 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-CN/env-vars)，此页面上的每个 `~/.claude` 路径都将位于该目录下。11在 Windows 上，`~/.claude` 解析为 `%USERPROFILE%\.claude`。如果您设置了 [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/zh-CN/env-vars)，此页面上的每个 `~/.claude` 路径都将位于该目录下。这同样适用于 `.claude.json`，否则它位于 `~/.claude.json`。

12 12 

13大多数用户只编辑 `CLAUDE.md` 和 `settings.json`。如果您的仓库已经有一个供其他编码 Agent 使用的 `AGENTS.md`，Claude Code [可以读取它](https://code.claude.com/docs/zh-CN/memory.md#agents-md)来代替 `CLAUDE.md`。目录的其余部分是可选的：根据需要添加 skill、规则或子代理。13大多数用户只编辑 `CLAUDE.md` 和 `settings.json`。如果您的仓库已经有一个供其他编码 Agent 使用的 `AGENTS.md`，Claude Code [可以读取它](https://code.claude.com/docs/zh-CN/memory.md#agents-md)来代替 `CLAUDE.md`。目录的其余部分是可选的：根据需要添加 skill、规则或子代理。

14 14 

76| [`agents/*.md`](#ce-agents) | 项目和全局 | ✓ | Subagent 定义及其自己的提示和工具 | [Subagents](https://code.claude.com/docs/zh-CN/sub-agents.md) |76| [`agents/*.md`](#ce-agents) | 项目和全局 | ✓ | Subagent 定义及其自己的提示和工具 | [Subagents](https://code.claude.com/docs/zh-CN/sub-agents.md) |

77| [`workflows/*.js`](#ce-workflows) | 项目和全局 | ✓ | 由 Claude 编写并从 `/workflows` 保存的动态工作流脚本；每个文件都成为一个 `/<name>` 命令 | [动态工作流](https://code.claude.com/docs/zh-CN/workflows.md) |77| [`workflows/*.js`](#ce-workflows) | 项目和全局 | ✓ | 由 Claude 编写并从 `/workflows` 保存的动态工作流脚本；每个文件都成为一个 `/<name>` 命令 | [动态工作流](https://code.claude.com/docs/zh-CN/workflows.md) |

78| [`agent-memory/<name>/`](#ce-agent-memory) | 项目和全局 | ✓ | Subagents 的持久内存 | [持久内存](https://code.claude.com/docs/zh-CN/sub-agents.md#enable-persistent-memory) |78| [`agent-memory/<name>/`](#ce-agent-memory) | 项目和全局 | ✓ | Subagents 的持久内存 | [持久内存](https://code.claude.com/docs/zh-CN/sub-agents.md#enable-persistent-memory) |

79| [`~/.claude.json`](#ce-claude-json) | 仅全局 | | 应用状态、账户详情、UI 切换、个人 MCP 服务器 | [全局配置](https://code.claude.com/docs/zh-CN/settings-reference.md#global-config-settings) |79| [`~/.claude.json`](#ce-claude-json) | 仅全局 | | 应用状态、账户详情、UI 切换、个人 MCP 服务器。如果该文件不存在，Claude Code 会在您启动会话或运行 `claude auth status` 等子命令时创建它，但运行 `--version` 或 `--help` 时不会创建。 | [全局配置](https://code.claude.com/docs/zh-CN/settings-reference.md#global-config-settings) |

80| [`projects/<project>/memory/`](#ce-global-projects) | 仅全局 | | 自动内存：Claude 在会话间对自己的笔记 | [自动内存](https://code.claude.com/docs/zh-CN/memory.md#auto-memory) |80| [`projects/<project>/memory/`](#ce-global-projects) | 仅全局 | | 自动内存：Claude 在会话间对自己的笔记 | [自动内存](https://code.claude.com/docs/zh-CN/memory.md#auto-memory) |

81| [`keybindings.json`](#ce-keybindings) | 仅全局 | | 自定义快捷键 | [快捷键](https://code.claude.com/docs/zh-CN/keybindings.md) |81| [`keybindings.json`](#ce-keybindings) | 仅全局 | | 自定义快捷键 | [快捷键](https://code.claude.com/docs/zh-CN/keybindings.md) |

82| [`themes/*.json`](#ce-themes) | 仅全局 | | 自定义颜色主题 | [自定义主题](https://code.claude.com/docs/zh-CN/terminal-config.md#create-a-custom-theme) |82| [`themes/*.json`](#ce-themes) | 仅全局 | | 自定义颜色主题 | [自定义主题](https://code.claude.com/docs/zh-CN/terminal-config.md#create-a-custom-theme) |

411 411 

412项目比单个会话更快地使用您的限制，特别是在 Pro 计划上，您应该期望在运行一个的日子里更快地达到您的限制。项目的这些部分使用您的计划：412项目比单个会话更快地使用您的限制，特别是在 Pro 计划上，您应该期望在运行一个的日子里更快地达到您的限制。项目的这些部分使用您的计划：

413 413 

414* **运行线程**：每个都是一个完整的会话，多个可以同时运行。没有固定数字；Claude 启动工作需要的尽可能多，您[要求](#tune-how-claude-runs-a-project)的限制是偏好而不是上限。强制限制是每天跨您的项目 200 个新线程。414* **运行线程**：每个都是一个完整的会话，多个可以同时运行。没有固定数字；Claude 启动工作需要的尽可能多，您[要求](#tune-how-claude-runs-a-project)的限制是偏好而不是上限。强制限制是每天跨您的项目 500 个新线程。

415* **对话**：Claude 使用自己的令牌读取线程报告的内容并决定下一步做什么。415* **对话**：Claude 使用自己的令牌读取线程报告的内容并决定下一步做什么。

416* **线程监视拉取请求**：当 CI 失败或审查评论到达其拉取请求时，空闲线程唤醒并再次使用您的计划。要停止这个，请在线程中要求它停止监视拉取请求。416* **线程监视拉取请求**：当 CI 失败或审查评论到达其拉取请求时，空闲线程唤醒并再次使用您的计划。要停止这个，请在线程中要求它停止监视拉取请求。

417 417 

25 25 

26> [!NOTE]26> [!NOTE]

27>27>

28> [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 会话将网页和移动界面连接到您自己机器上的会话，该会话使用您机器的网络和文件，而不是云环境。Claude Tag 频道会话仅使用组织级别的环境，即[共享环境](#organization-shared-environments)或[自托管环境](https://code.claude.com/docs/zh-CN/self-hosted-environments)。28> [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md) 会话将网页和移动界面连接到您自己机器上的会话，该会话使用您机器的网络和文件，而不是云环境。要选择 Claude Tag 频道使用的环境，请参阅[设置 Claude Tag 频道使用的环境](#set-the-environment-a-claude-tag-channel-uses)。

29 29 

30## Default 环境30## Default 环境

31 31 

64| PRs reviewed | 所选时间范围内每天审查的 Pull Request 数量 |64| PRs reviewed | 所选时间范围内每天审查的 Pull Request 数量 |

65| Code Review cost | 本月截至目前的 Code Review 支出 |65| Code Review cost | 本月截至目前的 Code Review 支出 |

66| Feedback | 因开发者解决了问题而被自动标记为已解决的审查评论数量 |66| Feedback | 因开发者解决了问题而被自动标记为已解决的审查评论数量 |

67| Code Review findings | 所选时间范围内 Claude 发布的审查中，每天[按严重级别划分的发现](https://code.claude.com/docs/zh-CN/code-review-pull-requests.md#severity-levels)数量 |

67| Repository breakdown | 每个仓库的已审查 PR 数、已解决评论数和审查运行次数，以及估算费用和按 PR 的视图 |68| Repository breakdown | 每个仓库的已审查 PR 数、已解决评论数和审查运行次数，以及估算费用和按 PR 的视图 |

68 69 

69仅当选择当前月份时，Code Review cost 卡片才会显示金额。分析中的费用数据可能与您的发票不同。Repository breakdown 中的费用按标价估算，未计入任何折扣或额度，并且仅涵盖 Claude 在 Pull Request 上发布的审查。如需与发票一致的支出数据，请参阅您的 Anthropic 账单。70仅当选择当前月份时，Code Review cost 卡片才会显示金额。分析中的费用数据可能与您的发票不同。Repository breakdown 中的费用按标价估算，未计入任何折扣或额度，并且仅涵盖 Claude 在 Pull Request 上发布的审查。如需与发票一致的支出数据，请参阅您的 Anthropic 账单。

111| `/mcp [reconnect (<server>\|all)\|enable\|disable [<server>\|all]]` | 管理 MCP 服务器连接和 OAuth 身份验证。不带参数运行可打开交互式列表，或传递 `reconnect`、`enable` 或 `disable` 以及服务器名称或 `all`，可在不打开列表的情况下更改连接状态。`reconnect all` 会[重试每个失败或需要身份验证的服务器](https://code.claude.com/docs/zh-CN/mcp.md#retry-failed-servers-yourself)。在非交互模式（`-p`）中，不带参数运行会输出服务器状态的文本摘要，而不是打开列表 |111| `/mcp [reconnect (<server>\|all)\|enable\|disable [<server>\|all]]` | 管理 MCP 服务器连接和 OAuth 身份验证。不带参数运行可打开交互式列表，或传递 `reconnect`、`enable` 或 `disable` 以及服务器名称或 `all`，可在不打开列表的情况下更改连接状态。`reconnect all` 会[重试每个失败或需要身份验证的服务器](https://code.claude.com/docs/zh-CN/mcp.md#retry-failed-servers-yourself)。在非交互模式（`-p`）中，不带参数运行会输出服务器状态的文本摘要，而不是打开列表 |

112| `/memory` | 编辑 `CLAUDE.md` 文件，启用或禁用[自动记忆](https://code.claude.com/docs/zh-CN/memory.md#auto-memory)，并查看自动记忆条目 |112| `/memory` | 编辑 `CLAUDE.md` 文件，启用或禁用[自动记忆](https://code.claude.com/docs/zh-CN/memory.md#auto-memory)，并查看自动记忆条目 |

113| `/mobile` | 显示用于下载 Claude 移动应用的二维码。别名：`/ios`、`/android` |113| `/mobile` | 显示用于下载 Claude 移动应用的二维码。别名：`/ios`、`/android` |

114| `/model [model]` | 切换 AI 模型并将其保存为新会话的默认模型。对于支持的模型，使用左/右箭头[调整 effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)。不带参数时，打开选择器；在某一行上按 `s` 可仅为当前会话切换。请参阅 [Claude Code 何时会要求您确认切换](https://code.claude.com/docs/zh-CN/prompt-caching.md#switching-models)。一旦您确认切换（如果 Claude Code 询问），Claude Code 会应用更改，而无需等待当前回复完成。在 v2.1.242 之前，Claude Code 会根据从 Anthropic 获取的功能标志来决定是在轮次中途运行该命令，还是将其排队直到轮次结束，并且在不[获取功能标志](https://code.claude.com/docs/zh-CN/env-vars.md#features-that-need-feature-flag-fetching)的会话中（例如在[第三方提供商](https://code.claude.com/docs/zh-CN/third-party-integrations.md)上）始终将其排队。也可在非交互模式（`-p`）中通过模型参数（而非选择器）使用，此时仅应用于当前会话，不会保存为默认模型；需要 Claude Code v2.1.205 或更高版本 |114| `/model [model]` | 切换 AI 模型并将其保存为新会话的默认模型。对于支持的模型，使用左/右箭头[调整 effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)。不带参数时，打开选择器；在某一行上按 `s` 可仅为当前会话切换。请参阅[新模型何时生效](https://code.claude.com/docs/zh-CN/interactive-mode.md#when-claude-code-sends-what-you-queued)。在 v2.1.242 之前，切换可能需要等待。使用 `-p` 时，请传递模型参数，该参数不会保存为默认模型；需要 v2.1.205 或更高版本 |

115| `/output-style [style]` | 列出[输出样式](https://code.claude.com/docs/zh-CN/output-styles.md)或切换到其中一种，例如 `/output-style concise`。请参阅[更改输出样式](https://code.claude.com/docs/zh-CN/output-styles.md#change-your-output-style)。需要 Claude Code v2.1.269 或更高版本 |115| `/output-style [style]` | 列出[输出样式](https://code.claude.com/docs/zh-CN/output-styles.md)或切换到其中一种，例如 `/output-style concise`。请参阅[更改输出样式](https://code.claude.com/docs/zh-CN/output-styles.md#change-your-output-style)。需要 Claude Code v2.1.269 或更高版本 |

116| `/passes` | 与朋友分享一周免费的 Claude Code。仅在您的账户符合条件时可见 |116| `/passes` | 与朋友分享一周免费的 Claude Code。仅在您的账户符合条件时可见 |

117| `/permissions` | 管理工具权限的允许、询问和拒绝规则。打开交互式对话框，您可以在其中按作用域查看规则、添加或删除规则、管理工作目录，以及查看[最近的自动模式拒绝记录](https://code.claude.com/docs/zh-CN/auto-mode-config.md#review-denials)。您还可以从对话框的 **Auto mode** 选项卡查看和编辑[自动模式分类器规则](https://code.claude.com/docs/zh-CN/auto-mode-config.md#edit-rules-from-permissions)。如果在 Claude 回复时运行此命令，Claude Code 会立即打开对话框，并从 Claude 在同一轮次中的下一次工具调用开始应用您的更改。在 v2.1.234 之前，Claude Code 会将该命令排队，直到该轮次结束。别名：`/allowed-tools` |117| `/permissions` | 管理工具权限的允许、询问和拒绝规则。打开交互式对话框，您可以在其中按作用域查看规则、添加或删除规则、管理工作目录，以及查看[最近的自动模式拒绝记录](https://code.claude.com/docs/zh-CN/auto-mode-config.md#review-denials)。您还可以从对话框的 **Auto mode** 选项卡查看和编辑[自动模式分类器规则](https://code.claude.com/docs/zh-CN/auto-mode-config.md#edit-rules-from-permissions)。如果在 Claude 回复时运行此命令，Claude Code 会立即打开对话框，并从 Claude 在同一轮次中的下一次工具调用开始应用您的更改。在 v2.1.234 之前，Claude Code 会将该命令排队，直到该轮次结束。别名：`/allowed-tools` |

130| `/remote-control` | 使此会话可通过 claude.ai 进行 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md)。在未登录时运行，会输出 Remote Control 需要 claude.ai 订阅的提示，并告诉您如何登录。别名：`/rc` |130| `/remote-control` | 使此会话可通过 claude.ai 进行 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md)。在未登录时运行，会输出 Remote Control 需要 claude.ai 订阅的提示，并告诉您如何登录。别名：`/rc` |

131| `/remote-env` | 为您从 CLI 启动的云端会话选择默认[云环境](https://code.claude.com/docs/zh-CN/cloud-environments.md#select-an-environment-from-the-cli) |131| `/remote-env` | 为您从 CLI 启动的云端会话选择默认[云环境](https://code.claude.com/docs/zh-CN/cloud-environments.md#select-an-environment-from-the-cli) |

132| `/rename [name]` | 重命名当前会话并在提示栏上显示名称。不提供名称时，根据对话历史自动生成一个名称。也可在非交互模式（`-p`）中使用。在所有重命名入口（包括 claude.ai 和桌面应用）中，Claude Code 都会将新名称中的控制字符和不可见字符替换为空格，并将名称长度上限设为 200 个字符。如果移除不可见字符后名称为空，Claude Code 会拒绝该名称并显示 `That name is empty once invisible characters are removed. Usage: /rename <name>`。字符替换和长度上限需要 Claude Code v2.1.221 或更高版本 |132| `/rename [name]` | 重命名当前会话并在提示栏上显示名称。不提供名称时，根据对话历史自动生成一个名称。也可在非交互模式（`-p`）中使用。在所有重命名入口（包括 claude.ai 和桌面应用）中，Claude Code 都会将新名称中的控制字符和不可见字符替换为空格，并将名称长度上限设为 200 个字符。如果移除不可见字符后名称为空，Claude Code 会拒绝该名称并显示 `That name is empty once invisible characters are removed. Usage: /rename <name>`。字符替换和长度上限需要 Claude Code v2.1.221 或更高版本 |

133| `/restart` | 重启 Claude Code 并恢复此会话，从而应用已安装的更新。在更新安装后页脚提供此选项时运行它。需要 Pro 或 Max 套餐，以及在 macOS 或 Linux（非 WSL）上的原生安装。需要 Claude Code v2.1.288 或更高版本。别名：`/update` |

133| `/resume [session]` | 通过 ID 或名称恢复对话，或打开会话选择器。[后台会话](https://code.claude.com/docs/zh-CN/agent-view.md)在选择器中以 `bg` 标记显示。恢复仍在运行的后台会话时（无论是从选择器还是通过 ID 或名称），会[打开该会话](https://code.claude.com/docs/zh-CN/sessions.md#resume-a-running-background-session)：您当前的对话会移到后台，此终端会附加到正在运行的会话。在空输入框中按 `←` 可返回 Agent 视图，其中也会列出您离开的对话。在 v2.1.285 之前，Claude Code 会拒绝并告诉您使用 `claude attach` 打开该会话，或先停止它。别名：`/continue` |134| `/resume [session]` | 通过 ID 或名称恢复对话，或打开会话选择器。[后台会话](https://code.claude.com/docs/zh-CN/agent-view.md)在选择器中以 `bg` 标记显示。恢复仍在运行的后台会话时（无论是从选择器还是通过 ID 或名称），会[打开该会话](https://code.claude.com/docs/zh-CN/sessions.md#resume-a-running-background-session)：您当前的对话会移到后台，此终端会附加到正在运行的会话。在空输入框中按 `←` 可返回 Agent 视图，其中也会列出您离开的对话。在 v2.1.285 之前，Claude Code 会拒绝并告诉您使用 `claude attach` 打开该会话，或先停止它。别名：`/continue` |

134| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | [`/code-review`](https://code.claude.com/docs/zh-CN/code-review-local) 的别名：审查当前 diff，或您传递的 PR 编号、分支或路径（例如 `/review 1234`），并接受相同的 effort 级别和标志。未指定级别时，审查会沿用您上次输入的 `low` 到 `max` 级别；有关确切规则，请参阅[使用 `/code-review` 在本地审查](https://code.claude.com/docs/zh-CN/code-review-local)。要进行深度云端审查，请使用 [`/code-review ultra`](https://code.claude.com/docs/zh-CN/ultrareview)。在 v2.1.223 之前，`/review` 是一个单独的命令，按编号对 GitHub Pull Request 运行单次只读审查，不带参数运行时会列出打开的 PR 供选择；从 v2.1.186 到 v2.1.201，它运行与 `/code-review medium` 相同的多 Agent 引擎 |135| `/review [low\|medium\|high\|xhigh\|max\|ultra] [--fix] [--comment] [--max-findings n\|all\|default] [pr#\|branch\|path]` | [`/code-review`](https://code.claude.com/docs/zh-CN/code-review-local) 的别名：审查当前 diff，或您传递的 PR 编号、分支或路径（例如 `/review 1234`），并接受相同的 effort 级别和标志。未指定级别时，审查会沿用您上次输入的 `low` 到 `max` 级别；有关确切规则，请参阅[使用 `/code-review` 在本地审查](https://code.claude.com/docs/zh-CN/code-review-local)。要进行深度云端审查，请使用 [`/code-review ultra`](https://code.claude.com/docs/zh-CN/ultrareview)。在 v2.1.223 之前，`/review` 是一个单独的命令，按编号对 GitHub Pull Request 运行单次只读审查，不带参数运行时会列出打开的 PR 供选择；从 v2.1.186 到 v2.1.201，它运行与 `/code-review medium` 相同的多 Agent 引擎 |

135| `/rewind` | 将对话和/或代码回退到之前的某个时间点，或从选定的消息开始总结。请参阅[检查点功能](https://code.claude.com/docs/zh-CN/checkpointing.md)。别名：`/checkpoint`、`/undo` |136| `/rewind` | 将对话和/或代码回退到之前的某个时间点，或从选定的消息开始总结。请参阅[检查点功能](https://code.claude.com/docs/zh-CN/checkpointing.md)。别名：`/checkpoint`、`/undo` |

375 375 

376## 后台令牌使用376## 后台令牌使用

377 377 

378Claude Code 即使在空闲时也会为某些后台功能使用令牌：378会话回顾和空闲压缩可能会在您空闲时使用 token。有关各自的运行时机以及如何关闭，请参阅[会话回顾](https://code.claude.com/docs/zh-CN/interactive-mode.md#session-recap)和[空闲压缩](https://code.claude.com/docs/zh-CN/settings-reference.md#idlecompaction)。

379 

380* **对话总结**：为 `claude --resume` 功能总结以前对话的后台作业

381* **命令处理**：某些命令（如 `/usage`）可能会生成请求以检查状态

382 

383这些后台进程即使没有活跃交互也会消耗少量令牌（通常每个会话不到 \$0.04）。

384 379 

385启用提示建议时，Claude Code 在 Claude 响应后还会向您的会话使用的模型发送一个简短请求，以[建议您的下一个提示](https://code.claude.com/docs/zh-CN/interactive-mode.md#prompt-suggestions)。该请求重用对话的提示缓存，因此主要是缓存读取加上少量输出令牌。当您的账户接近或达到使用限制时，Claude Code [会跳过这些请求](https://code.claude.com/docs/zh-CN/interactive-mode.md#when-claude-code-skips-suggestions)。要停止这些请求，[关闭提示建议](https://code.claude.com/docs/zh-CN/interactive-mode.md#turn-prompt-suggestions-off)。380启用提示建议时，Claude Code 在 Claude 响应后还会向您的会话使用的模型发送一个简短请求，以[建议您的下一个提示](https://code.claude.com/docs/zh-CN/interactive-mode.md#prompt-suggestions)。该请求重用对话的提示缓存，因此主要是缓存读取加上少量输出令牌。当您的账户接近或达到使用限制时，Claude Code [会跳过这些请求](https://code.claude.com/docs/zh-CN/interactive-mode.md#when-claude-code-skips-suggestions)。要停止这些请求，[关闭提示建议](https://code.claude.com/docs/zh-CN/interactive-mode.md#turn-prompt-suggestions-off)。

386 381 

108 108 

109### 从 shell 打开链接109### 从 shell 打开链接

110 110 

111你也可以从 shell 脚本、别名或自动化中打开深链接，而不是通过点击它。使用链接作为参数调用你的操作系统的 URL 打开命令。这些命令依赖于 Claude Code [在你在机器上发送交互式会话的第一个提示时注册的](#registration-and-supported-platforms)处理程序。111您也可以从 shell 脚本、别名或自动化中打开深链接，而不是通过点击它。使用链接作为参数调用您的操作系统的 URL 打开命令。这些命令依赖于 Claude Code 在机器上[注册](#registration-and-supported-platforms)的处理程序。

112 112 

113**macOS**113**macOS**

114 114 

148 148 

149## 注册和支持的平台149## 注册和支持的平台

150 150 

151在 macOS、Linux 和 Windows 上，当您在交互式会话中发送第一个提示词时，Claude Code 会向您的操作系统注册 `claude-cli://` 处理程序。启动 `claude` 并在不发送提示词的情况下退出不会注册处理程序。您不需要运行单独的安装命令。注册仅写入用户级位置：151在 macOS、Linux 和 Windows 上，当您执行以下任一操作时，Claude Code 会向您的操作系统注册 `claude-cli://` 处理程序：

152 

153* 向交互式 `claude` 会话发送任何内容，例如一条消息或 `/help`。仅启动会话而不发送任何内容不会注册处理程序。

154* 在您已[信任](https://code.claude.com/docs/zh-CN/permissions.md#project-allow-rules-and-workspace-trust)的文件夹中以 [Agent 视图](https://code.claude.com/docs/zh-CN/agent-view.md)启动 Claude Code，例如使用 `claude agents`

155 

156您不需要运行单独的安装命令。注册仅写入用户级位置：

152 157 

153| 平台 | 处理程序位置 |158| 平台 | 处理程序位置 |

154| - | - |159| - | - |

172 177 

173### 点击链接没有反应178### 点击链接没有反应

174 179 

175处理程序可能还没有注册。注册发生在你发送交互式会话的第一个提示时，而不是在会话启动时。在该机器上启动一个交互式 `claude` 会话，发送任何提示，退出，然后再试一次链接。如果你在没有桌面环境的 Linux 上，`xdg-open` 可能没有东西可以分派。180处理程序可能还没有注册。在交互式会话中，注册发生在您发送内容时，而不是在会话启动时。在该机器上启动一个交互式 `claude` 会话，发送任意提示词，退出，然后再试一次链接。如果您在没有桌面环境的 Linux 上，`xdg-open` 可能没有东西可以分派。

176 181 

177### 在 Linux 上找不到 xdg-open182### 在 Linux 上找不到 xdg-open

178 183 

1930* **Windows**：通过 `SOFTWARE\Policies\Claude` 处的注册表配置1930* **Windows**：通过 `SOFTWARE\Policies\Claude` 处的注册表配置

1931* **Linux**：通过位于 `/etc/claude-desktop/managed-settings.json` 的 root 所有的文件配置，该文件以 JSON 对象形式保存策略键。如果除 root 之外的任何人可以写入该文件或其所在文件夹，Desktop 将拒绝使用该文件。它与 Claude Code 的[托管设置文件](https://code.claude.com/docs/zh-CN/managed-settings.md)是不同的文件。1931* **Linux**：通过位于 `/etc/claude-desktop/managed-settings.json` 的 root 所有的文件配置，该文件以 JSON 对象形式保存策略键。如果除 root 之外的任何人可以写入该文件或其所在文件夹，Desktop 将拒绝使用该文件。它与 Claude Code 的[托管设置文件](https://code.claude.com/docs/zh-CN/managed-settings.md)是不同的文件。

1932 1932 

1933#### 将登录限制为您的组织

1934 

1935要限制哪些 claude.ai 组织可以登录 Claude Desktop，请在 Claude Desktop 策略中设置 `forceLoginOrgUUID`。

1936 

1937该键需要 Claude Desktop v1.2581.0 或更高版本。

1938 

1939在 Linux 上，仅设置此键的策略文件如下：

1940 

1941```json /etc/claude-desktop/managed-settings.json theme={null}

1942{

1943 "forceLoginOrgUUID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

1944}

1945```

1946 

1947将占位符替换为您的 claude.ai 组织 ID，该 ID 显示在 [claude.ai 管理员设置](https://claude.ai/admin-settings/organization)中。它与 Claude Code 的 [`forceLoginOrgUUID`](https://code.claude.com/docs/zh-CN/settings-reference#forceloginorguuid) 设置所采用的 ID 相同。有关设置此键的 macOS 和 Windows 示例，请参阅面向 HIPAA 就绪组织的 Cowork 指南中的[部署 Claude Desktop 策略](https://claude.com/docs/cowork/hipaa-setup#deploy-the-claude-desktop-policy)。

1948 

1949如果您在 Claude Code 的[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)中设置 `forceLoginMethod` 和 `forceLoginOrgUUID`，并不会改变 Claude Desktop 的登录屏幕。

1950 

1933### 网络访问要求1951### 网络访问要求

1934 1952 

1935Desktop 从 Anthropic CDN 主机加载其应用程序代码和用户内容。1953Desktop 从 Anthropic CDN 主机加载其应用程序代码和用户内容。

428| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流](https://code.claude.com/docs/zh-CN/workflows.md) Agent 在发送自己的第一个请求之前，等待具有相同前缀的同级 Agent 的第一个响应开始的时间上限（毫秒）。当扇出启动多个共享同一[提示缓存前缀](https://code.claude.com/docs/zh-CN/workflows.md#prompt-caching-in-a-fan-out)的 Agent 时，Claude Code 会让除第一个 Agent 之外的所有 Agent 最多等待这么长时间，以便其余 Agent 读取已缓存的前缀，而不是各自在未缓存的情况下处理它。默认值为 `5000`。设置为 `0` 可禁用等待。设置了 `DISABLE_PROMPT_CACHING` 时，Agent 从不等待。需要 Claude Code v2.1.229 或更高版本 |428| `CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS` | [工作流](https://code.claude.com/docs/zh-CN/workflows.md) Agent 在发送自己的第一个请求之前，等待具有相同前缀的同级 Agent 的第一个响应开始的时间上限（毫秒）。当扇出启动多个共享同一[提示缓存前缀](https://code.claude.com/docs/zh-CN/workflows.md#prompt-caching-in-a-fan-out)的 Agent 时，Claude Code 会让除第一个 Agent 之外的所有 Agent 最多等待这么长时间，以便其余 Agent 读取已缓存的前缀，而不是各自在未缓存的情况下处理它。默认值为 `5000`。设置为 `0` 可禁用等待。设置了 `DISABLE_PROMPT_CACHING` 时，Agent 从不等待。需要 Claude Code v2.1.229 或更高版本 |

429| `CLAUDE_CODE_YOU_SHOULD_KNOW_DEBUG` | 设置为 `1` 可在输入框上方为 [You should know mod](https://code.claude.com/docs/zh-CN/interactive-mode.md#you-should-know-suggestions) 在本会话中进行的最近三次检查各显示一行。用于在没有出现任何备注时确认该 mod 正在进行检查。需要 Claude Code v2.1.287 或更高版本 |429| `CLAUDE_CODE_YOU_SHOULD_KNOW_DEBUG` | 设置为 `1` 可在输入框上方为 [You should know mod](https://code.claude.com/docs/zh-CN/interactive-mode.md#you-should-know-suggestions) 在本会话中进行的最近三次检查各显示一行。用于在没有出现任何备注时确认该 mod 正在进行检查。需要 Claude Code v2.1.287 或更高版本 |

430| `CLAUDE_CONFIG_DIR` | 覆盖配置目录（默认：`~/.claude`）。所有设置、会话历史和插件都存储在此路径下。关于凭据，请参阅 [Claude Code 存储凭据的位置](https://code.claude.com/docs/zh-CN/authentication.md#credential-management)。适用于同时运行多个账户：例如 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。请在 shell、用户设置或托管设置中设置它。在设置文件中，请写入[绝对路径](#in-settings-files)。在[项目和本地设置](https://code.claude.com/docs/zh-CN/settings-reference.md#variables-claude-code-ignores-in-env)中被忽略 |430| `CLAUDE_CONFIG_DIR` | 覆盖配置目录（默认：`~/.claude`）。所有设置、会话历史和插件都存储在此路径下。关于凭据，请参阅 [Claude Code 存储凭据的位置](https://code.claude.com/docs/zh-CN/authentication.md#credential-management)。适用于同时运行多个账户：例如 `alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'`。请在 shell、用户设置或托管设置中设置它。在设置文件中，请写入[绝对路径](#in-settings-files)。在[项目和本地设置](https://code.claude.com/docs/zh-CN/settings-reference.md#variables-claude-code-ignores-in-env)中被忽略 |

431| `CLAUDE_EFFORT` | 在 Bash 工具子进程和 hook 命令中自动设置为子进程启动时生效的 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)：`low`、`medium`、`high`、`xhigh` 或 `max`。与传递给 [hook](https://code.claude.com/docs/zh-CN/hooks.md) 的 `effort.level` 字段一致。仅在当前模型支持 effort 参数时设置 |431| `CLAUDE_EFFORT` | 在 Bash 工具子进程和 hook 命令中自动设置为子进程启动时的 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)设置：`low`、`medium`、`high`、`xhigh` 或 `max`。与传递给 [hook](https://code.claude.com/docs/zh-CN/hooks.md) 的 `effort.level` 字段一致。仅在当前模型支持 effort 参数时设置 |

432| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 设置为 `1` 可强制启用字节级流式空闲看门狗，设置为 `0` 可强制禁用它。`0` 还会在运行[首字节截止时间](https://code.claude.com/docs/zh-CN/network-config.md#streaming-idle-watchdogs)的连接上关闭该截止时间。未设置时，该看门狗默认在直连 Anthropic API 和 [Claude Platform on AWS](https://code.claude.com/docs/zh-CN/claude-platform-on-aws.md) 的连接上启用，并对通过 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 访问的[网关](https://code.claude.com/docs/zh-CN/gateways.md)连接上的流式响应启用；在 v2.1.222 之前，它不会在这些网关连接上运行，因此即使 keep-alive ping 持续到达，事件级看门狗也可能在那里报告停滞。关于超时时间以及各计时器如何相互作用，请参阅[流式空闲看门狗](https://code.claude.com/docs/zh-CN/network-config.md#streaming-idle-watchdogs) |432| `CLAUDE_ENABLE_BYTE_WATCHDOG` | 设置为 `1` 可强制启用字节级流式空闲看门狗，设置为 `0` 可强制禁用它。`0` 还会在运行[首字节截止时间](https://code.claude.com/docs/zh-CN/network-config.md#streaming-idle-watchdogs)的连接上关闭该截止时间。未设置时，该看门狗默认在直连 Anthropic API 和 [Claude Platform on AWS](https://code.claude.com/docs/zh-CN/claude-platform-on-aws.md) 的连接上启用，并对通过 `ANTHROPIC_BASE_URL` 或 `ANTHROPIC_AWS_BASE_URL` 访问的[网关](https://code.claude.com/docs/zh-CN/gateways.md)连接上的流式响应启用；在 v2.1.222 之前，它不会在这些网关连接上运行，因此即使 keep-alive ping 持续到达，事件级看门狗也可能在那里报告停滞。关于超时时间以及各计时器如何相互作用，请参阅[流式空闲看门狗](https://code.claude.com/docs/zh-CN/network-config.md#streaming-idle-watchdogs) |

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

434| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 设置为 `0` 可强制禁用事件级流式空闲看门狗，设置为 `1` 可强制启用它。未设置时，该看门狗对所有提供商默认开启。在 v2.1.196 之前，未设置时的默认值在直连 Anthropic API 上由服务器控制，在其他提供商上为关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时时间；关于与其同时运行的其他停滞计时器，请参阅[流式空闲看门狗](https://code.claude.com/docs/zh-CN/network-config.md#streaming-idle-watchdogs) |434| `CLAUDE_ENABLE_STREAM_WATCHDOG` | 设置为 `0` 可强制禁用事件级流式空闲看门狗，设置为 `1` 可强制启用它。未设置时，该看门狗对所有提供商默认开启。在 v2.1.196 之前，未设置时的默认值在直连 Anthropic API 上由服务器控制，在其他提供商上为关闭。使用 `CLAUDE_STREAM_IDLE_TIMEOUT_MS` 配置超时时间；关于与其同时运行的其他停滞计时器，请参阅[流式空闲看门狗](https://code.claude.com/docs/zh-CN/network-config.md#streaming-idle-watchdogs) |

575* 在 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md#requirements) 不可用时[向本机以外的会话发送消息](https://code.claude.com/docs/zh-CN/cross-session-messaging.md#message-sessions-on-other-machines)。关闭获取后，本机上会话之间的消息传递仍可正常工作575* 在 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md#requirements) 不可用时[向本机以外的会话发送消息](https://code.claude.com/docs/zh-CN/cross-session-messaging.md#message-sessions-on-other-machines)。关闭获取后，本机上会话之间的消息传递仍可正常工作

576* 运行 [`claude import` 或 `/import` 命令](https://code.claude.com/docs/zh-CN/cli-reference#cli-commands)576* 运行 [`claude import` 或 `/import` 命令](https://code.claude.com/docs/zh-CN/cli-reference#cli-commands)

577* 运行 [`/skill-doctor`](https://code.claude.com/docs/zh-CN/skills#find-unused-skills) 或在 `/plugin` 的 **Stats** 选项卡中打开其报告577* 运行 [`/skill-doctor`](https://code.claude.com/docs/zh-CN/skills#find-unused-skills) 或在 `/plugin` 的 **Stats** 选项卡中打开其报告

578* 在 Pro 和 Max 计划中运行 [`/restart`](https://code.claude.com/docs/zh-CN/commands)

578* 将您的 claude.ai 账户中启用的 [skill](https://code.claude.com/docs/zh-CN/skills.md#where-synced-skills-load) 和[插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#synced-plugins)同步到终端会话中579* 将您的 claude.ai 账户中启用的 [skill](https://code.claude.com/docs/zh-CN/skills.md#where-synced-skills-load) 和[插件](https://code.claude.com/docs/zh-CN/plugins/loading.md#synced-plugins)同步到终端会话中

579* 启用 [You should know mod](https://code.claude.com/docs/zh-CN/interactive-mode.md#you-should-know-suggestions)580* 启用 [You should know mod](https://code.claude.com/docs/zh-CN/interactive-mode.md#you-should-know-suggestions)

580* 使用 [advisor 工具](https://code.claude.com/docs/zh-CN/advisor.md#requirements)581* 使用 [advisor 工具](https://code.claude.com/docs/zh-CN/advisor.md#requirements)

277| `Windows reported an error (EBADF) when Claude Code read this session's transcript file` | [命令行错误](#windows-reported-an-error-ebadf) |277| `Windows reported an error (EBADF) when Claude Code read this session's transcript file` | [命令行错误](#windows-reported-an-error-ebadf) |

278| `Cannot switch renderers in this session` | [命令行错误](#cannot-switch-renderers-in-this-session) |278| `Cannot switch renderers in this session` | [命令行错误](#cannot-switch-renderers-in-this-session) |

279| `Cannot switch renderers while work is running in the background` | [命令行错误](#cannot-switch-renderers-in-this-session) |279| `Cannot switch renderers while work is running in the background` | [命令行错误](#cannot-switch-renderers-in-this-session) |

280| `Can't restart while work is running in the background — wait for it to finish (or stop it via /tasks), then try again.` | [命令行错误](#cant-restart-while-work-is-running-or-remote-control-is-connected) |

281| `Can't restart while Remote Control is connected. To use the installed version, exit and start Claude Code again, then run /resume.` | [命令行错误](#cant-restart-while-work-is-running-or-remote-control-is-connected) |

280| `Claude Code couldn't restart` | [命令行错误](#claude-code-couldnt-restart) |282| `Claude Code couldn't restart` | [命令行错误](#claude-code-couldnt-restart) |

281| `Couldn't open Claude Desktop` | [命令行错误](#couldnt-open-claude-desktop) |283| `Couldn't open Claude Desktop` | [命令行错误](#couldnt-open-claude-desktop) |

282| `Failed to open Claude Desktop. Please try opening it manually.` | [命令行错误](#couldnt-open-claude-desktop) |284| `Failed to open Claude Desktop. Please try opening it manually.` | [命令行错误](#couldnt-open-claude-desktop) |

858 860 

859### The prompt to confirm went unanswered861### The prompt to confirm went unanswered

860 862 

861如果您的账户需要 [Fable usage-credits consent](https://code.claude.com/docs/zh-CN/model-config.md#fable-and-usage-credits)，Claude Code 会在 Fable 请求计费使用额度之前要求您确认。当同意提示关闭且没有人回答时，Claude Code 会以以下消息之一结束轮次：863当 [Fable usage-credits consent prompt](https://code.claude.com/docs/zh-CN/model-config.md#fable-and-usage-credits) 在无人回答的情况下关闭时，Claude Code 会以以下消息之一结束轮次：

862 864 

863```text theme={null}865```text theme={null}

864Fable limit reached · continuing on Fable 5.1 uses usage credits, and the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change866Fable limit reached · continuing on Fable 5.1 uses usage credits, and the prompt to confirm went unanswered — nothing was sent · answer it where this session is running, or /model to change

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

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

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

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

3302 3304 

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

3304 3306 

3590 3592 

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

3592 3594 

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

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

3595 3597 

3596**解决方法：**3598**解决方法：**

3597 3599 

3744 3746 

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

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

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

3748 3750 

3749**解决方法：**3751**解决方法：**

3750 3752 

3974 3976 

3975* 在不带这些限制启动的会话中运行 `/tui fullscreen`，或运行 `/tui default` 切换回来。Claude Code 会在那里保存 [`tui` 设置](https://code.claude.com/docs/zh-CN/settings-reference#tui)3977* 在不带这些限制启动的会话中运行 `/tui fullscreen`，或运行 `/tui default` 切换回来。Claude Code 会在那里保存 [`tui` 设置](https://code.claude.com/docs/zh-CN/settings-reference#tui)

3976 3978 

3979### Can't restart while work is running or Remote Control is connected

3980 

3981Claude Code 没有重启，您的会话会保持原样继续运行。请按照消息中的修复方法操作。

3982 

3977### Claude Code couldn't restart3983### Claude Code couldn't restart

3978 3984 

3979当此消息表示您的对话已保存时，对话已存储在磁盘上，您可以从中断处继续。Claude Code 正在重启自身，例如在您运行 [`/tui`](https://code.claude.com/docs/zh-CN/fullscreen#enable-fullscreen-rendering) 后切换到全屏渲染或从全屏渲染切换回来，但无法启动新进程，因此以状态 1 退出：3985当此消息表示您的对话已保存时，对话已存储在磁盘上，您可以从中断处继续。Claude Code 正在重启自身，例如在您运行 [`/tui`](https://code.claude.com/docs/zh-CN/fullscreen#enable-fullscreen-rendering) 后切换到全屏渲染或从全屏渲染切换回来，但无法启动新进程，因此以状态 1 退出：

168 168 

169> [!WARNING]169> [!WARNING]

170>170>

171> Claude Code 在使用小型快速模型的任何地方都会读取 `ANTHROPIC_DEFAULT_HAIKU_MODEL`，不仅仅是用于 `/goal` 评估。当你设置它时，Claude Code 也会将 [`haiku` 别名](https://code.claude.com/docs/zh-CN/model-config#model-aliases)解析为该模型，并在其上运行[后台功能](https://code.claude.com/docs/zh-CN/costs.md#background-token-usage)，例如对话摘要。171> Claude Code 在使用小型快速模型的任何地方都会读取 `ANTHROPIC_DEFAULT_HAIKU_MODEL`，不仅仅是用于 `/goal` 评估。当您设置它时，Claude Code 也会将 [`haiku` 别名](https://code.claude.com/docs/zh-CN/model-config#model-aliases)解析为该模型，并在其上运行会话标题生成和其他一些后台任务。

172 172 

173评估器在你的会话配置的任何提供商上运行。它不调用工具，所以它只能判断 Claude 已经在对话中呈现的内容。173评估器在你的会话配置的任何提供商上运行。它不调用工具，所以它只能判断 Claude 已经在对话中呈现的内容。

174 174 

26 26 

27| 时间 | 操作内容 |27| 时间 | 操作内容 |

28| :- | :- |28| :- | :- |

29| 应用配置之前 | [准备计算机](#prepare-computers-before-the-hipaa-configuration-is-applied)：检查开发人员的连接方式、更新应用、允许网络访问并部署托管设置 |29| 应用配置之前 | [准备计算机](#prepare-computers-before-the-hipaa-configuration-is-applied)：检查开发人员的连接方式、更新应用、允许网络访问、部署托管设置，并限制 Claude Desktop 登录 |

30| 应用配置之后 | Code 标签页处于关闭状态，直到所有者将其重新打开。[在计算机上确认配置](#confirm-the-configuration-on-a-computer) |30| 应用配置之后 | Code 标签页处于关闭状态，直到所有者将其重新打开。[在计算机上确认配置](#confirm-the-configuration-on-a-computer) |

31| 持续进行 | [管理本地会话数据](#manage-local-session-data) |31| 持续进行 | [管理本地会话数据](#manage-local-session-data) |

32 32 

161 161 

162要了解您的 BAA 是否涵盖在没有 HIPAA 配置的情况下运行的会话，请参阅[在符合 HIPAA 要求的 Enterprise 计划中使用 Claude Code（本地模式）和 Cowork（本地模式）](https://support.claude.com/en/articles/17318731)。162要了解您的 BAA 是否涵盖在没有 HIPAA 配置的情况下运行的会话，请参阅[在符合 HIPAA 要求的 Enterprise 计划中使用 Claude Code（本地模式）和 Cowork（本地模式）](https://support.claude.com/en/articles/17318731)。

163 163 

164### 限制 Claude Desktop 登录

165 

166如果开发人员使用 Claude Desktop 的 Code 标签页，还需按照[将登录限制为您的组织](https://code.claude.com/docs/zh-CN/desktop.md#restrict-sign-in-to-your-organization)中的说明，在 Claude Desktop 策略中设置 `forceLoginOrgUUID`。在托管设置中部署 `forceLoginMethod` 和 `forceLoginOrgUUID` 不会改变 Claude Desktop 的登录界面。

167 

164## 在计算机上确认配置168## 在计算机上确认配置

165 169 

166在为您的组织应用配置后，请在一台托管计算机上运行此检查。170在为您的组织应用配置后，请在一台托管计算机上运行此检查。

735| `cwd` | 调用 hook 时的当前工作目录 |735| `cwd` | 调用 hook 时的当前工作目录 |

736| `scratchpad_dir` | 会话的 [scratchpad 目录](https://code.claude.com/docs/zh-CN/claude-directory.md#session-scratchpad-directory)的路径，Claude 在其中保存临时工作文件。当会话没有 scratchpad 或 temp 目录不可用时不存在。需要 Claude Code v2.1.257 或更高版本 |736| `scratchpad_dir` | 会话的 [scratchpad 目录](https://code.claude.com/docs/zh-CN/claude-directory.md#session-scratchpad-directory)的路径，Claude 在其中保存临时工作文件。当会话没有 scratchpad 或 temp 目录不可用时不存在。需要 Claude Code v2.1.257 或更高版本 |

737| `permission_mode` | 当前[权限模式](https://code.claude.com/docs/zh-CN/permissions.md#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。标记为**手动**的模式作为 `"default"` 到达，从不作为 `"manual"`，因此匹配 `"default"` 的脚本继续工作。并非所有事件都接收此字段。检查每个 [hook 事件](#hook-events)部分中的 JSON 示例 |737| `permission_mode` | 当前[权限模式](https://code.claude.com/docs/zh-CN/permissions.md#permission-modes)：`"default"`、`"plan"`、`"acceptEdits"`、`"auto"`、`"dontAsk"` 或 `"bypassPermissions"`。标记为**手动**的模式作为 `"default"` 到达，从不作为 `"manual"`，因此匹配 `"default"` 的脚本继续工作。并非所有事件都接收此字段。检查每个 [hook 事件](#hook-events)部分中的 JSON 示例 |

738| `effort` | 对象，其 `level` 字段保存 hook 运行时生效的 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。如果您设置了活跃模型不支持的级别，`level` 会报告 Claude Code 实际运行的级别；[调整 effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)说明它如何选择该级别。该对象与[状态栏](https://code.claude.com/docs/zh-CN/statusline.md#available-data) `effort` 字段匹配。对于在工具使用上下文中触发的事件（如 `PreToolUse`、`PostToolUse`、`Stop` 和 `SubagentStop`），当当前模型支持 effort 参数时存在。该级别也可作为 `$CLAUDE_EFFORT` 环境变量供 hook 命令和 Bash 工具使用。 |738| `effort` | 对象，其 `level` 为 hook 运行时的 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)设置，包括 skill、子代理或 `ultrathink` 的级别：`"low"`、`"medium"`、`"high"`、`"xhigh"` 或 `"max"`。在支持 effort 的模型上，对于 `PreToolUse`、`PostToolUse`、`Stop`、`SubagentStop` 以及其他具有工具使用上下文的事件存在。如果模型不支持您的级别，`level` 为实际运行的级别。您更改的级别可能会在其[生效](https://code.claude.com/docs/zh-CN/model-config.md#when-a-new-effort-level-starts)之前就显示在此处。`$CLAUDE_EFFORT` 保存相同的级别。 |

739| `hook_event_name` | 触发的事件的名称 |739| `hook_event_name` | 触发的事件的名称 |

740 740 

741`agent_id` 和 `agent_type` 告诉您的脚本 hook 是在哪个 Agent 中触发的，例如子代理、[进程内队友](https://code.claude.com/docs/zh-CN/agent-teams.md#choose-a-display-mode)，或您通过 `--agent` 选择的 Agent：741`agent_id` 和 `agent_type` 告诉您的脚本 hook 是在哪个 Agent 中触发的，例如子代理、[进程内队友](https://code.claude.com/docs/zh-CN/agent-teams.md#choose-a-display-mode)，或您通过 `--agent` 选择的 Agent：

1898| `query` | string | `"react hooks best practices"` | 搜索查询 |1898| `query` | string | `"react hooks best practices"` | 搜索查询 |

1899| `allowed_domains` | array | `["docs.example.com"]` | 可选：仅包含来自这些域名的结果 |1899| `allowed_domains` | array | `["docs.example.com"]` | 可选：仅包含来自这些域名的结果 |

1900| `blocked_domains` | array | `["spam.example.com"]` | 可选：排除来自这些域名的结果 |1900| `blocked_domains` | array | `["spam.example.com"]` | 可选：排除来自这些域名的结果 |

1901| `mode` | string | `"extended"` | 可选：搜索类型。`"standard"` 请求较轻量的搜索，`"extended"` 请求完整搜索。某些会话不会发送 `mode`，不带该字段的调用会执行完整搜索。需要 Claude Code v2.1.282 或更高版本 |

1901 1902 

1902##### Agent1903##### Agent

1903 1904 

1968 1969 

1969当 hook 返回 `"ask"` 时，显示给用户的权限提示会包含一个标签，标明该 hook 的来源：来自任何设置文件或 Agent frontmatter 的 hook 为 `[settings]`，插件的 hook 为 `[plugin:<name>]`，来自 skill frontmatter 的 hook 为 `[skill]`。这有助于用户了解是哪个配置来源在请求确认。1970当 hook 返回 `"ask"` 时，显示给用户的权限提示会包含一个标签，标明该 hook 的来源：来自任何设置文件或 Agent frontmatter 的 hook 为 `[settings]`，插件的 hook 为 `[plugin:<name>]`，来自 skill frontmatter 的 hook 为 `[skill]`。这有助于用户了解是哪个配置来源在请求确认。

1970 1971 

1971在[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)下，hook 的 `"ask"` 也会强制显示权限提示：分类器仍然可以拒绝该工具调用，但无法静默批准该调用。

1972 

1973```json theme={null}1972```json theme={null}

1974{1973{

1975 "hookSpecificOutput": {1974 "hookSpecificOutput": {

1988>1987>

1989> PreToolUse 以前使用顶层的 `decision` 和 `reason` 字段，但这些字段在此事件中已弃用。请改用 `hookSpecificOutput.permissionDecision` 和 `hookSpecificOutput.permissionDecisionReason`。已弃用的值 `"approve"` 和 `"block"` 分别映射到 `"allow"` 和 `"deny"`。PostToolUse 和 Stop 等其他事件继续使用顶层 `decision` 和 `reason` 作为其当前格式。1988> PreToolUse 以前使用顶层的 `decision` 和 `reason` 字段，但这些字段在此事件中已弃用。请改用 `hookSpecificOutput.permissionDecision` 和 `hookSpecificOutput.permissionDecisionReason`。已弃用的值 `"approve"` 和 `"block"` 分别映射到 `"allow"` 和 `"deny"`。PostToolUse 和 Stop 等其他事件继续使用顶层 `decision` 和 `reason` 作为其当前格式。

1990 1989 

1990#### 自动模式下的 PreToolUse `ask` 决策

1991 

1992在[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)下，PreToolUse hook 返回的 `"ask"` 通常会将工具调用发送到权限提示，[分类器](https://code.claude.com/docs/zh-CN/permission-modes.md#how-the-classifier-evaluates-actions)不会对其做出决定。某些调用会走不同的路径：

1993 

1994* **Claude Code 自身检查也会标记的调用**：包括写入[受保护路径](https://code.claude.com/docs/zh-CN/permission-modes.md#protected-paths)以及请求[在沙箱外运行](https://code.claude.com/docs/zh-CN/sandboxing.md#the-unsandboxed-retry-escape-hatch)的命令。分类器可以在任何提示出现之前拒绝此类调用。如果分类器批准，该调用通常仍会进入提示。

1995* **`SubagentHandback` 调用**：此工具用于提交子代理的报告。它不会出现任何提示，即使分类器反对，调用也会运行。

1996 

1997要阻止 `SubagentHandback` 调用，请返回 `"deny"`。随后 Claude Code 会最多三次告知子代理其报告未送达，并要求它再次调用该工具。如果您的 hook 持续拒绝，子代理将在未通过此工具提交报告的情况下结束，而等待它的对话会收到一条说明此情况的提示。

1998 

1991#### 需要用户交互的工具1999#### 需要用户交互的工具

1992 2000 

1993`AskUserQuestion` 和 `ExitPlanMode` 需要用户交互。在使用 `-p` 标志的[非交互模式](https://code.claude.com/docs/zh-CN/headless.md)下，只有当运行具有接收提示的[权限宿主](https://code.claude.com/docs/zh-CN/headless.md#turn-off-permission-prompts-in-unattended-runs)（例如 Agent SDK 的 `canUseTool` 回调）时，Claude Code 才会提供这些工具。2001`AskUserQuestion` 和 `ExitPlanMode` 需要用户交互。在使用 `-p` 标志的[非交互模式](https://code.claude.com/docs/zh-CN/headless.md)下，只有当运行具有接收提示的[权限宿主](https://code.claude.com/docs/zh-CN/headless.md#turn-off-permission-prompts-in-unattended-runs)（例如 Agent SDK 的 `canUseTool` 回调）时，Claude Code 才会提供这些工具。

395 395 

396Claude Code 在您发送某些命令时立即运行它们，而不是排队它们，其中包括 `/model`、`/effort` 和 `/fast`。这三个命令各改变一个设置：模型、effort 级别或快速模式。Claude Code 是将新设置应用于 Claude 已在处理的轮次，还是仅从您的下一轮次应用，因命令而异：396Claude Code 在您发送某些命令时立即运行它们，而不是排队它们，其中包括 `/model`、`/effort` 和 `/fast`。这三个命令各改变一个设置：模型、effort 级别或快速模式。Claude Code 是将新设置应用于 Claude 已在处理的轮次，还是仅从您的下一轮次应用，因命令而异：

397 397 

398* [`/model`](https://code.claude.com/docs/zh-CN/model-config#setting-your-model)：一旦您确认[缓存警告](https://code.claude.com/docs/zh-CN/prompt-caching.md#switching-models)（如果 Claude Code 显示），Claude Code 会将您的更改应用于该轮次中它发出的下一个请求398* [`/model`](https://code.claude.com/docs/zh-CN/model-config#setting-your-model)：一旦您确认[缓存警告](https://code.claude.com/docs/zh-CN/prompt-caching.md#switching-models)（如果 Claude Code 显示），Claude Code 会从该轮次中它发出的下一个请求开始使用新模型

399* `/effort`：您发送的下一条消息将以新级别运行。要[在 Claude 已在处理的轮次中启用新级别](https://code.claude.com/docs/zh-CN/model-config.md#when-a-new-effort-level-starts)，请在 Claude 运行工具调用时排队一条消息399* `/effort`：您发送的下一条消息将以新级别运行。要[在 Claude 已在处理的轮次中启用新级别](https://code.claude.com/docs/zh-CN/model-config.md#when-a-new-effort-level-starts)，请在 Claude 运行工具调用时排队一条消息

400* [`/fast`](https://code.claude.com/docs/zh-CN/fast-mode#toggle-fast-mode)：Claude Code 保持轮次开始时活跃的快速模式设置，因此您的速度更改从您的下一轮次应用。如果您当前的模型不支持快速模式，打开它也会[切换您的模型](https://code.claude.com/docs/zh-CN/prompt-caching.md#turning-on-fast-mode)，Claude Code 会在该轮次中从其下一个请求使用新模型400* [`/fast`](https://code.claude.com/docs/zh-CN/fast-mode#toggle-fast-mode)：Claude Code 保持轮次开始时活跃的快速模式设置，因此您的速度更改从您的下一轮次应用。如果您当前的模型不支持快速模式，打开它也会[切换您的模型](https://code.claude.com/docs/zh-CN/prompt-caching.md#turning-on-fast-mode)，Claude Code 会在该轮次中从其下一个请求使用新模型

401 401 

761 761 

762* **您发送提示词**：Claude Code 发送您的提示词而不是等待。如果您的提示词也达到了限制，它会保留在对话中，并且 Claude Code 会重新开始等待。762* **您发送提示词**：Claude Code 发送您的提示词而不是等待。如果您的提示词也达到了限制，它会保留在对话中，并且 Claude Code 会重新开始等待。

763* **您退出 Claude Code**：当您恢复会话时，等待不会重新启动。763* **您退出 Claude Code**：当您恢复会话时，等待不会重新启动。

764* **对话转手**：您使用 `/login` 切换账户、清除或倒带对话、`/resume` 另一个会话、使用 `/teleport` 拉取一个会话、使用 `/tui` 重新启动，或将会话交给 Claude Desktop、后台会话或云端。764* **对话转手**：您使用 `/login` 切换账户、清除或倒带对话、`/resume` 另一个会话、使用 `/teleport` 拉取一个会话、使用 `/tui` 或 [`/restart`](https://code.claude.com/docs/zh-CN/commands#all-commands) 重新启动，或将会话移至 Claude Desktop、后台会话或云端。

765* **设置关闭，或重置超过 24 小时**：这仅结束 Claude Code 自动启动的等待。您从 `/rate-limit-options` 中选择的等待会继续倒计时。765* **设置关闭，或重置超过 24 小时**：这仅结束 Claude Code 自动启动的等待。您从 `/rate-limit-options` 中选择的等待会继续倒计时。

766* **继续被阻止**：一个阻止继续提示的 [`UserPromptSubmit` hook](https://code.claude.com/docs/zh-CN/hooks#userpromptsubmit)，或在到达模型之前的失败，会结束等待。Claude Code 会告诉您继续没有运行。发送提示以继续。766* **继续被阻止**：一个阻止继续提示的 [`UserPromptSubmit` hook](https://code.claude.com/docs/zh-CN/hooks#userpromptsubmit)，或在到达模型之前的失败，会结束等待。Claude Code 会告诉您继续没有运行。发送提示以继续。

767 767 

92 92 

93根据您的套餐和席位等级，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](https://code.claude.com/docs/zh-CN/costs.md#add-usage-credits-to-your-subscription)。93根据您的套餐和席位等级，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](https://code.claude.com/docs/zh-CN/costs.md#add-usage-credits-to-your-subscription)。

94 94 

95在交互式会话中，Claude Code 会在 Fable 请求计入使用额度之前显示同意提示。使用组织计费的企业套餐成员不会看到该提示。您可以选择使用使用额度继续使用 Fable，或切换到您的默认模型。您也可以关闭提示：95在交互式会话中，Claude Code 可能会显示 Fable 使用额度同意提示。使用组织计费的企业套餐成员不会看到该提示。您可以选择使用使用额度继续使用 Fable，或切换到您的默认模型。您也可以关闭提示：

96 96 

97* 当您使用 `/model` 选择 Fable 模型时，将保持当前模型。97* 当您使用 `/model` 选择 Fable 模型时，将保持当前模型。

98* 在会话中途，Claude Code 会在您的默认模型上继续该轮次。98* 在会话中途，Claude Code 会在您的默认模型上继续该轮次。

544* **您自己的更改**：一旦您选择了 effort 级别、在 `/model` 中选择了模型或稍后恢复会话，被标记请求的级别就不再沿用。544* **您自己的更改**：一旦您选择了 effort 级别、在 `/model` 中选择了模型或稍后恢复会话，被标记请求的级别就不再沿用。

545* **为单个轮次设置的 effort**：如果您使用 `ultrathink` 提升了被标记的轮次，或 skill 的 `effort` frontmatter 设置了其级别，该级别适用于该轮次。后续轮次以 [effort 解析顺序](#adjust-effort-level)为备用模型给出的级别运行。545* **为单个轮次设置的 effort**：如果您使用 `ultrathink` 提升了被标记的轮次，或 skill 的 `effort` frontmatter 设置了其级别，该级别适用于该轮次。后续轮次以 [effort 解析顺序](#adjust-effort-level)为备用模型给出的级别运行。

546 546 

547在会话中，运行 `/effort status` 查看当前生效的级别，或运行 `/effort` 更改它。547要查看回退后为您的会话设置的级别，请运行 `/effort status`。要更改它，请运行 `/effort`。

548 548 

549#### 检查触发回退的原因549#### 检查触发回退的原因

550 550 

607 607 

608Claude Code 按此顺序解析会话的 effort 级别，采用首先适用的：608Claude Code 按此顺序解析会话的 effort 级别，采用首先适用的：

609 609 

6101. 明确选择：[`CLAUDE_CODE_EFFORT_LEVEL`](https://code.claude.com/docs/zh-CN/env-vars#variables) 环境变量、使用 `--effort` 启动或会话中的 `/effort`（[非交互式 `/effort` 的效果更窄](#non-interactive-effort)）6101. [`CLAUDE_CODE_EFFORT_LEVEL`](https://code.claude.com/docs/zh-CN/env-vars#variables) 环境变量

6112. 您的设置：您为模型保存的级别或 [`effortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#effortlevel) 键，在 [`modelSettings`](https://code.claude.com/docs/zh-CN/settings-reference#modelsettings) 中说明它们之间和跨设置文件的优先级6112. 您在会话中选择的级别，例如通过 `/effort`、`/model` 选择器或 [`applyFlagSettings()`](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#applyflagsettings)

6123. 模型的默认 effort：在支持 effort 的每个模型上为 `high`，除了 Opus 5.5、Sonnet 5.5 和 Haiku 5.5 默认为 `medium`、Opus 4.7 默认为 `xhigh`，当您的组织为其[组织默认模型](#organization-default-model)设置默认 effort 级别时，当您运行该模型时该级别是默认值6123. 使用 `--effort` 启动

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

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

613 615 

614自动模型回退后适用的级别，请参阅[回退后的 effort 级别](#effort-level-after-a-fallback)。616自动模型回退后适用的级别，请参阅[回退后的 effort 级别](#effort-level-after-a-fallback)。

615 617 

687您可以通过以下任何方式更改 effort：689您可以通过以下任何方式更改 effort：

688 690 

689* **`/effort`**：运行 `/effort` 不带参数以打开交互式滑块，`/effort` 后跟级别名称以直接设置它，或 `/effort auto` 以清除活动模型的保存级别691* **`/effort`**：运行 `/effort` 不带参数以打开交互式滑块，`/effort` 后跟级别名称以直接设置它，或 `/effort auto` 以清除活动模型的保存级别

690* **在 `/model` 中**：选择模型时使用左/右箭头键调整 effort 滑块692* **在 `/model` 中**：选择模型时使用左/右箭头键调整 effort 滑块。新级别最迟从您的下一条消息开始生效。在此之前，Claude 可能继续以旧级别工作，即使是在新模型上。当[优先级高于您所选级别的来源](#adjust-effort-level)（例如 `CLAUDE_CODE_EFFORT_LEVEL`）适用时，Claude 改为以该来源的级别工作。

691* **`--effort` 标志**：启动 Claude Code 时传递级别名称以为单个会话设置它693* **`--effort` 标志**：启动 Claude Code 时传递级别名称以为单个会话设置它

692* **环境变量**：将 `CLAUDE_CODE_EFFORT_LEVEL` 设置为级别名称。要让 Claude Code [不发送 effort 级别](#send-no-effort-level)，请改为将其设置为 `auto` 或 `unset`694* **环境变量**：将 `CLAUDE_CODE_EFFORT_LEVEL` 设置为级别名称。要让 Claude Code [不发送 effort 级别](#send-no-effort-level)，请改为将其设置为 `auto` 或 `unset`

693* **设置**：在 [`modelSettings`](https://code.claude.com/docs/zh-CN/settings-reference#modelsettings) 中设置每个模型的级别，或将 [`effortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#effortlevel) 设置为 `low`、`medium`、`high` 或 `xhigh` 作为没有级别的模型的默认值。`max` 在任一键中都不被接受为级别，`ultracode` 有其自己的 [`ultracode`](https://code.claude.com/docs/zh-CN/settings-reference#ultracode) 键695* **设置**：在 [`modelSettings`](https://code.claude.com/docs/zh-CN/settings-reference#modelsettings) 中设置每个模型的级别，或将 [`effortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#effortlevel) 设置为 `low`、`medium`、`high` 或 `xhigh` 作为没有级别的模型的默认值。`max` 在任一键中都不被接受为级别，`ultracode` 有其自己的 [`ultracode`](https://code.claude.com/docs/zh-CN/settings-reference#ultracode) 键

694* **从连接的设备**：在 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md#what-connected-devices-see) 会话中，从您的手机或浏览器上的 effort 控件中选择级别。该级别仅适用于当前会话。需要 Claude Code v2.1.234 或更高版本696* **从连接的设备**：在 [Remote Control](https://code.claude.com/docs/zh-CN/remote-control.md#what-connected-devices-see) 会话中，从您的手机或浏览器上的 effort 控件中选择级别。该级别仅适用于当前会话。需要 Claude Code v2.1.234 或更高版本

695* **Skill 和子代理 frontmatter**：在 [skill](https://code.claude.com/docs/zh-CN/skills.md#frontmatter-reference) 或[子代理](https://code.claude.com/docs/zh-CN/sub-agents.md#supported-frontmatter-fields) markdown 文件中设置 `effort` 以在该 skill 或子代理运行时覆盖 effort 级别697* **Skill 和子代理 frontmatter**：在 [skill](https://code.claude.com/docs/zh-CN/skills.md#frontmatter-reference) 或[子代理](https://code.claude.com/docs/zh-CN/sub-agents.md#supported-frontmatter-fields) markdown 文件中设置 `effort` 以在该 skill 或子代理运行时覆盖 effort 级别

696 698 

697Frontmatter effort 在该 skill 或子代理活跃时应用，覆盖会话级别但不覆盖环境变量。一个 [`maxEffortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#maxeffortlevel) 或[组织 effort 上限](#organization-effort-limits)仍然限制 skill 或子代理运行的级别。699skill 的 `effort` 在其运行所在的轮次结束前一直适用；使用 `context: fork` 时，则在分叉出的子代理运行期间适用。子代理的 `effort` 在子代理运行期间适用，除非[其调用覆盖了它](https://code.claude.com/docs/zh-CN/sub-agents.md#choose-an-effort-level)。当其中任一项适用时，skill 或子代理都以其级别运行，无论您启动时使用、保存或选择的是什么级别。如果设置了 `CLAUDE_CODE_EFFORT_LEVEL`，则改为应用该级别。

698 700 

699如果您在[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)中设置 `effortLevel`，Claude Code 在 [effort 解析顺序](#adjust-effort-level)的设置步骤处应用它，用户仍然可以使用 `/effort` 或 `--effort` 更改级别。要将用户保持在或低于某个级别，设置 [`maxEffortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#maxeffortlevel)。701[`maxEffortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#maxeffortlevel) 或[组织 effort 上限](#organization-effort-limits)仍然限制 skill 或子代理运行的级别。如果您在[托管设置](https://code.claude.com/docs/zh-CN/managed-settings.md)中设置 `effortLevel`，Claude Code 在 [effort 解析顺序](#adjust-effort-level)的设置步骤处应用它，用户仍然可以使用 `/effort` 或 `--effort` 更改级别。要将用户保持在或低于某个级别，设置 [`maxEffortLevel`](https://code.claude.com/docs/zh-CN/settings-reference#maxeffortlevel)。

700 702 

701#### 检查您设置的 effort 级别703#### 检查您设置的 effort 级别

702 704 

703选择支持的模型时，effort 滑块会出现在 `/model` 中。会话标题中显示的级别（例如"with low effort"）来自您的 effort 设置，即使 Claude [仍在以旧级别工作](#when-a-new-effort-level-starts)。页脚也会在启动时和级别更改时简要显示 effort 级别。705选择支持的模型时，effort 滑块会出现在 `/model` 中。会话标题中显示的级别（例如"with low effort"）来自您的 effort 设置，即使 Claude [仍在以旧级别工作](#when-a-new-effort-level-starts)。在启动时以及您更改级别时，页脚也会简要显示为您的会话设置的级别。

704 706 

705#### 新 effort 级别何时生效707#### 新 effort 级别何时生效

706 708 

556在为云会话配置遥测时，请记住这些约束：556在为云会话配置遥测时，请记住这些约束：

557 557 

558* **让会话到达收集器**：Claude Code 通过会话的网络发送导出，因此它是否到达您的 `OTEL_EXPORTER_OTLP_ENDPOINT` 中的主机取决于环境的[网络访问级别](https://code.claude.com/docs/zh-CN/cloud-environments.md#access-levels)。如果会话无法在您选择的级别上到达收集器的域，请[将域添加到环境的允许列表](https://code.claude.com/docs/zh-CN/cloud-environments.md#allow-specific-domains)，因为没有服务器管理的设置会将域添加到环境的网络允许列表。558* **让会话到达收集器**：Claude Code 通过会话的网络发送导出，因此它是否到达您的 `OTEL_EXPORTER_OTLP_ENDPOINT` 中的主机取决于环境的[网络访问级别](https://code.claude.com/docs/zh-CN/cloud-environments.md#access-levels)。如果会话无法在您选择的级别上到达收集器的域，请[将域添加到环境的允许列表](https://code.claude.com/docs/zh-CN/cloud-environments.md#allow-specific-domains)，因为没有服务器管理的设置会将域添加到环境的网络允许列表。

559* **Claude Tag 频道使用组织级别的环境**：频道会话在组织级别的环境中运行，而不是成员的个人环境中，因此请在[共享环境](https://code.claude.com/docs/zh-CN/cloud-environments.md#organization-shared-environments)上进行允许列表和任何环境变量更改，该环境设置为您组织的默认环境或固定到频道。559* **Claude Tag 频道**：请在设置为您组织默认环境或固定到频道的[共享环境](https://code.claude.com/docs/zh-CN/cloud-environments.md#organization-shared-environments)上进行允许列表和任何环境变量更改。

560* **Cowork 单独配置**：如[表面覆盖表](https://code.claude.com/docs/zh-CN/model-config.md#surface-coverage)所示，Cowork 会话不会接收服务器管理的设置，因此服务器管理的 `env` 块不会配置其遥测。560* **Cowork 单独配置**：如[表面覆盖表](https://code.claude.com/docs/zh-CN/model-config.md#surface-coverage)所示，Cowork 会话不会接收服务器管理的设置，因此服务器管理的 `env` 块不会配置其遥测。

561 561 

562### 将遥测属性分配给云会话562### 将遥测属性分配给云会话

1467* `result`：清理已运行时为 `"complete"`，Claude Code 暂停清理时为 `"skipped"`1467* `result`：清理已运行时为 `"complete"`，Claude Code 暂停清理时为 `"skipped"`

1468* `period_days`：合并后设置中的 `cleanupPeriodDays` 值（以天为单位），如果没有任何来源设置该值，则为 `30`。在 skipped 事件中，为清理本应使用的值，根据 Claude Code 能够读取的设置来源计算得出1468* `period_days`：合并后设置中的 `cleanupPeriodDays` 值（以天为单位），如果没有任何来源设置该值，则为 `30`。在 skipped 事件中，为清理本应使用的值，根据 Claude Code 能够读取的设置来源计算得出

1469* `used_default`：没有可读取的设置来源设置 `cleanupPeriodDays` 时为 `"true"`，否则为 `"false"`。在 complete 事件中，`"true"` 表示应用了 30 天的默认值1469* `used_default`：没有可读取的设置来源设置 `cleanupPeriodDays` 时为 `"true"`，否则为 `"false"`。在 complete 事件中，`"true"` 表示应用了 30 天的默认值

1470* `skip_reason`：Claude Code 暂停清理的原因。仅在 `result` 为 `"skipped"` 时存在：1470* `skip_reason`：Claude Code 暂停清理的原因。仅当 `result` 为 `"skipped"` 时存在：

1471 * `"user_source_disabled"`：用户设置被排除（例如通过 [`--setting-sources`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 标志或 SDK 的 [`settingSources`](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#options) 选项），且没有已启用的来源提供 `cleanupPeriodDays`1471 * `"user_source_disabled"`：用户设置被排除（例如通过 [`--setting-sources`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 标志或 SDK 的 [`settingSources`](https://code.claude.com/docs/zh-CN/agent-sdk/typescript#options) 选项），且没有启用的来源提供 `cleanupPeriodDays`

1472 * `"settings_unknowable"`：某个设置文件无法读取或解析，因此 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 可能被设置为 Claude Code 无法看到的值1472 * `"settings_unknowable"`：某个设置文件无法读取或解析，因此 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays` 可能被设置为 Claude Code 看不到的值

1473 * `"settings_invalid_key_set"`：设置存在验证错误，且显式设置了 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays`，因此回退到默认值可能会违背该设置删除或保留文件1473 * `"settings_invalid_key_set"`：设置存在验证错误，且显式设置了 `cleanupPeriodDays` 或 `desktopSessionCleanupPeriodDays`，因此回退到默认值可能会违背该设置删除或保留文件

1474 * `"remote_settings_unknowable"`：第三方部署上 Claude Desktop 的 Code 选项卡中的某个会话请求了[服务器托管设置](https://code.claude.com/docs/zh-CN/server-managed-settings.md)。它没有收到可用的响应，因此 `cleanupPeriodDays` 可能被设置为 Claude Code 看不到的值

1474* `transcripts_deleted`：清理删除的会话记录数量，即顶层的 `~/.claude/projects/*/*.jsonl` 文件1475* `transcripts_deleted`：清理删除的会话记录数量，即顶层的 `~/.claude/projects/*/*.jsonl` 文件

1475* `transcripts_exempted_desktop`：已超过保留期限、但清理根据 [Claude Desktop 和 Cowork 规则](https://code.claude.com/docs/zh-CN/claude-directory.md#cleaned-up-automatically)予以保留的会话记录数量。这些不计入 `files_past_cutoff`。需要 Claude Code v2.1.248 或更高版本1476* `transcripts_exempted_desktop`：已超过保留期限、但清理根据 [Claude Desktop 和 Cowork 规则](https://code.claude.com/docs/zh-CN/claude-directory.md#cleaned-up-automatically)予以保留的会话记录数量。这些不计入 `files_past_cutoff`。需要 Claude Code v2.1.248 或更高版本

1476* `session_files_deleted`：会话文件清理删除的文件数量：会话记录加上每个会话的配套文件，例如附属文件、录制文件和工具结果1477* `session_files_deleted`：会话文件清理删除的文件数量：会话记录加上每个会话的配套文件，例如附属文件、录制文件和工具结果

338| 使用 CronCreate 等工具安排、在用户下一次输入之前到期的周期性作业 | 此时不启动轮次。该作业会错过这次运行，并保留其计划。 | 无需处理 |338| 使用 CronCreate 等工具安排、在用户下一次输入之前到期的周期性作业 | 此时不启动轮次。该作业会错过这次运行，并保留其计划。 | 无需处理 |

339| 来自您的 mod 启动的监视器的事件 | 监视器继续运行。监视器在用户下一次输入之前触发的事件会被丢弃，但监视器结束的通知除外，该通知会在该输入之后到达。 | 无法处理 |339| 来自您的 mod 启动的监视器的事件 | 监视器继续运行。监视器在用户下一次输入之前触发的事件会被丢弃，但监视器结束的通知除外，该通知会在该输入之后到达。 | 无法处理 |

340| 您的 mod 生成并随后通过 `$.session.send` 恢复、在用户下一次输入之前完成的子代理 | 其完成通知会等待，并在该输入之后到达对话 | 无需处理 |340| 您的 mod 生成并随后通过 `$.session.send` 恢复、在用户下一次输入之前完成的子代理 | 其完成通知会等待，并在该输入之后到达对话 | 无需处理 |

341| 来自 `$.tool.call`、在用户停止轮次时已在运行、并在用户下一次输入之前达到超时的前台 Bash 或 PowerShell 命令 | 在超时时被停止，而不是[移至后台](https://code.claude.com/docs/zh-CN/tools-reference.md#foreground-commands-that-move-to-the-background)。调用解析时会设置 `isError`，输出中包含以下行：`Ended instead of moving to the background: plugins' input is held, by a Stop or by the host's limits.` | 在用户下一次输入之后，按照[重试被拒绝或被丢弃的调用](#retry-a-refused-or-dropped-call)所示再次运行 |

341 342 

342当计划作业到期或监视器在用户下一次输入之前触发事件时，用户可能会看到 [`Stopped:` toast](https://code.claude.com/docs/zh-CN/plugins/mods/troubleshoot#stopped-type-a-message-to-continue)。343当计划作业到期或监视器在用户下一次输入之前触发事件时，用户可能会看到 [`Stopped:` toast](https://code.claude.com/docs/zh-CN/plugins/mods/troubleshoot#stopped-type-a-message-to-continue)。

343 344 

94 94 

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

96 96 

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

98 98 

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

100 100 

565 565 

566在 macOS 上，当被拒绝的路径经过符号链接时（例如 `~/.claude` 是一个指向 dotfiles 仓库的链接），沙箱也会拒绝该路径的真实位置。这涵盖沙箱自身的拒绝，以及您按字面写出的 `denyWrite` 和 `denyRead` 条目。566在 macOS 上，当被拒绝的路径经过符号链接时（例如 `~/.claude` 是一个指向 dotfiles 仓库的链接），沙箱也会拒绝该路径的真实位置。这涵盖沙箱自身的拒绝，以及您按字面写出的 `denyWrite` 和 `denyRead` 条目。

567 567 

568对于包含 `*`、`?` 或 `[` 的 `denyWrite` 条目，当这些字符中第一个出现之前的某个文件夹是符号链接时，同样适用。例如，`~/.claude/*.json` 在 `~/.claude` 的真实位置下也会被拒绝。

569 

568### 网络隔离570### 网络隔离

569 571 

570沙箱化的命令没有直接通往网络的路径：572沙箱化的命令没有直接通往网络的路径：

40* **零数据保留和 HIPAA**：对于启用了[零数据保留](https://code.claude.com/docs/zh-CN/zero-data-retention.md)或应用了 [HIPAA 配置](https://code.claude.com/docs/zh-CN/hipaa-setup.md)的组织不可用。40* **零数据保留和 HIPAA**：对于启用了[零数据保留](https://code.claude.com/docs/zh-CN/zero-data-retention.md)或应用了 [HIPAA 配置](https://code.claude.com/docs/zh-CN/hipaa-setup.md)的组织不可用。

41* **模型推理**：会话使用 Anthropic API，除非您将 runner 配置为[将模型请求发送到 Amazon Bedrock 或 Google Cloud 的 Agent Platform](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration.md#send-model-requests-to-bedrock-or-agent-platform)。在这两种情况下，会话内容都会发送给 Anthropic。在以这种方式配置的 runner 上，来自 claude.ai 的[服务器托管设置](https://code.claude.com/docs/zh-CN/server-managed-settings.md)和组织策略不会作用于会话。41* **模型推理**：会话使用 Anthropic API，除非您将 runner 配置为[将模型请求发送到 Amazon Bedrock 或 Google Cloud 的 Agent Platform](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration.md#send-model-requests-to-bedrock-or-agent-platform)。在这两种情况下，会话内容都会发送给 Anthropic。在以这种方式配置的 runner 上，来自 claude.ai 的[服务器托管设置](https://code.claude.com/docs/zh-CN/server-managed-settings.md)和组织策略不会作用于会话。

42* **使用入口**：从 [claude.ai/code](https://claude.ai/code)、移动和桌面应用、[云端定时任务](https://code.claude.com/docs/zh-CN/routines.md)以及终端启动的会话，带有 [`claude --cloud`](https://code.claude.com/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud) 或 [`--environment` 调度](https://code.claude.com/docs/zh-CN/self-hosted-environments-testing#run-the-test-loop)，可以在自托管环境中运行。[Claude Tag](https://claude.com/docs/claude-tag/overview) 会话也可以在其中运行，但 Claude 还不能在这些会话中使用[访问包](https://claude.com/docs/claude-tag/concepts/glossary#access-bundle)。[Claude Security](https://code.claude.com/docs/zh-CN/claude-security.md) 和 [Code Review](https://code.claude.com/docs/zh-CN/code-review.md) 会话还不能路由到它们。对这两个使用入口的支持将单独跟进。42* **使用入口**：从 [claude.ai/code](https://claude.ai/code)、移动和桌面应用、[云端定时任务](https://code.claude.com/docs/zh-CN/routines.md)以及终端启动的会话，带有 [`claude --cloud`](https://code.claude.com/docs/zh-CN/claude-code-on-the-web#from-terminal-to-cloud) 或 [`--environment` 调度](https://code.claude.com/docs/zh-CN/self-hosted-environments-testing#run-the-test-loop)，可以在自托管环境中运行。[Claude Tag](https://claude.com/docs/claude-tag/overview) 会话也可以在其中运行，但 Claude 还不能在这些会话中使用[访问包](https://claude.com/docs/claude-tag/concepts/glossary#access-bundle)。[Claude Security](https://code.claude.com/docs/zh-CN/claude-security.md) 和 [Code Review](https://code.claude.com/docs/zh-CN/code-review.md) 会话还不能路由到它们。对这两个使用入口的支持将单独跟进。

43* **存储库**：会话从 GitHub 检出存储库；请参阅 [GitHub 身份验证选项](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md#github-authentication-options)。对于 GitHub Enterprise Server 主机，请参阅其[网络要求](https://code.claude.com/docs/zh-CN/github-enterprise-server.md#network-requirements)。43* **仓库**：会话从 GitHub 或 GitHub Enterprise Server 检出仓库。通过 `--environment` 调度启动的会话还可以使用其他 git 主机：

44 * **GitHub**：请参阅 [GitHub 身份验证选项](https://code.claude.com/docs/zh-CN/claude-code-on-the-web.md#github-authentication-options)。

45 * **GitHub Enterprise Server**：请参阅其[网络要求](https://code.claude.com/docs/zh-CN/github-enterprise-server.md#network-requirements)。

46 * **其他 git 主机**：请参阅[使用 `--environment` 启动会话的要求](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy#start-a-session-on-a-repository-outside-github)。

44* **计费**：自托管环境中的会话消耗您的组织的 Claude Code 使用情况，与 Anthropic 托管环境中的会话相同。47* **计费**：自托管环境中的会话消耗您的组织的 Claude Code 使用情况，与 Anthropic 托管环境中的会话相同。

45 48 

46## 为什么选择自托管49## 为什么选择自托管

113 116 

114* **控制平面**：运行器轮询 `api.anthropic.com` 以获取工作并发布设置进度和失败事件，全部出站 HTTPS。轮询充当运行器的心跳。117* **控制平面**：运行器轮询 `api.anthropic.com` 以获取工作并发布设置进度和失败事件，全部出站 HTTPS。轮询充当运行器的心跳。

115* **Git**：运行器通过 HTTPS 或 SSH 从您的 git 主机克隆和推送，使用您的部署提供的凭据进行身份验证。请参阅[配置 git](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#configure-git)了解各选项，包括每个会话铸造的凭据。使用 [Anthropic git 代理](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy)时，github.com 上仓库的 git 流量改为经由 `api.anthropic.com` 传输。118* **Git**：运行器通过 HTTPS 或 SSH 从您的 git 主机克隆和推送，使用您的部署提供的凭据进行身份验证。请参阅[配置 git](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#configure-git)了解各选项，包括每个会话铸造的凭据。使用 [Anthropic git 代理](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy)时，github.com 上仓库的 git 流量改为经由 `api.anthropic.com` 传输。

116* **会话子进程**：子 Claude Code 进程将会话的事件流保持到 `api.anthropic.com`，并为模型推理和会话期间运行的 git 命令进行自己的出站调用。在使用 [Anthropic 托管 git](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy) 的会话中，子进程通过其打开到 `api.anthropic.com` 的 WebSocket 连接发送 github.com 的 `git` 和 `gh` 流量。119* **会话子进程**：子 Claude Code 进程保持与 `api.anthropic.com` 之间的会话事件流，并自行发起出站调用，用于模型推理以及会话期间运行的 git 命令。在使用 [Anthropic 托管 git](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy) 的会话中，子进程会打开一个到 `api.anthropic.com` 的 WebSocket 连接，该连接承载来自 `git` 和 `gh` 的 github.com 流量。

117* **SCM 连接器**：可选的编排器 [SCM 连接器](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference.md#scm-connector-flags)不可用，因此其隧道不会打开。该隧道是到 `api.anthropic.com` 的 WebSocket 连接。120* **SCM 连接器**：可选的编排器 [SCM 连接器](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference.md#scm-connector-flags)不可用，因此其隧道不会打开。该隧道是到 `api.anthropic.com` 的 WebSocket 连接。

118 121 

119请参阅[网络要求](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#network-requirements)了解完整的出站列表。[上面的图](#how-self-hosted-environments-work)显示了这些路径，但可选的 SCM 连接器和 Anthropic 托管的 git 连接除外。122请参阅[网络要求](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#network-requirements)了解完整的出站列表。[上面的图](#how-self-hosted-environments-work)显示了这些路径，但可选的 SCM 连接器和 Anthropic 托管的 git 连接除外。

42| `CLAUDE_CODE_REMOTE_MCP_CONFIG` | 指向 `CLAUDE_CONFIG_DIR` 中某个文件的路径，该文件保存 Anthropic 控制平面为此会话交付的 MCP 服务器定义。如果您的包装脚本重建子进程的环境，请携带此变量。如果缺少此变量，当控制平面更新交付的服务器时，子进程会关闭您的包装脚本通过 [`--mcp-config`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 添加但不在更新中的任何 stdio、HTTP 或 SSE 服务器。需要 Claude Code v2.1.299 或更高版本。 |42| `CLAUDE_CODE_REMOTE_MCP_CONFIG` | 指向 `CLAUDE_CONFIG_DIR` 中某个文件的路径，该文件保存 Anthropic 控制平面为此会话交付的 MCP 服务器定义。如果您的包装脚本重建子进程的环境，请携带此变量。如果缺少此变量，当控制平面更新交付的服务器时，子进程会关闭您的包装脚本通过 [`--mcp-config`](https://code.claude.com/docs/zh-CN/cli-reference#cli-flags) 添加但不在更新中的任何 stdio、HTTP 或 SSE 服务器。需要 Claude Code v2.1.299 或更高版本。 |

43| `ANTHROPIC_BASE_URL` | 子进程将使用的 API 基础 URL，由控制平面按会话交付，通常为 `https://api.anthropic.com`。不要覆盖它：会话的推理凭据是 Anthropic 颁发的 OAuth 令牌，其他提供者不接受。 |43| `ANTHROPIC_BASE_URL` | 子进程将使用的 API 基础 URL，由控制平面按会话交付，通常为 `https://api.anthropic.com`。不要覆盖它：会话的推理凭据是 Anthropic 颁发的 OAuth 令牌，其他提供者不接受。 |

44| `CLAUDE_CODE_OAUTH_TOKEN` | 子进程用于模型推理的短期 OAuth 访问令牌，生命周期约为 30 分钟。运行器在过期前重新生成它，并通过子进程的 stdin 交付轮换，因此不 [keep stdin attached](#keep-stdin-and-file-descriptor-3-attached) 的包装脚本只看到初始值。不要依赖您的组织 IP 允许列表来限制此令牌的使用：将其视为持有者凭据，如果泄露，大约 30 分钟内仍可使用，不要记录它、写入磁盘或在会话容器外转发它。 |44| `CLAUDE_CODE_OAUTH_TOKEN` | 子进程用于模型推理的短期 OAuth 访问令牌，生命周期约为 30 分钟。运行器在过期前重新生成它，并通过子进程的 stdin 交付轮换，因此不 [keep stdin attached](#keep-stdin-and-file-descriptor-3-attached) 的包装脚本只看到初始值。不要依赖您的组织 IP 允许列表来限制此令牌的使用：将其视为持有者凭据，如果泄露，大约 30 分钟内仍可使用，不要记录它、写入磁盘或在会话容器外转发它。 |

45| `CLAUDE_RUNNER_ALIVE_EVERY_MS` | 当[轮次在子进程初始化之前开始](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference.md#session-startup-timeout)时，运行器通过此变量设置子进程报告自身存活的频率（以毫秒为单位）。如果您的包装脚本重建子进程的环境，请携带此变量，否则运行器可能会在该轮次期间释放会话并记录 `no child output for <n> — releasing`。需要运行器和子进程均为 v2.1.309 或更高版本。 |

45 46 

46包装脚本还继承子进程的其余托管环境，包括任何服务器提供的环境变量。`exec` 自动传播所有内容；如果您的包装脚本以其他方式生成子进程，请转发完整环境。47包装脚本还继承子进程的其余托管环境，包括任何服务器提供的环境变量。`exec` 自动传播所有内容；如果您的包装脚本以其他方式生成子进程，请转发完整环境。

47 48 

307| `CLAUDE_RUNNER_ATTEMPT` | 用于日志记录的按会话计数器。它不是重试次数，也不是请求次数。对于预热请求为 `0`，但针对某个会话的请求也可能携带 `0`。 |308| `CLAUDE_RUNNER_ATTEMPT` | 用于日志记录的按会话计数器。它不是重试次数，也不是请求次数。对于预热请求为 `0`，但针对某个会话的请求也可能携带 `0`。 |

308| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | 来自轮询响应的 HTTP `Date` 标头的服务器时间。当 hook 验证工作单 JWT 的 `exp` 时，与此值进行比较而不是本地时钟，以容忍时钟偏差。当网关省略标头时为空。 |309| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | 来自轮询响应的 HTTP `Date` 标头的服务器时间。当 hook 验证工作单 JWT 的 `exp` 时，与此值进行比较而不是本地时钟，以容忍时钟偏差。当网关省略标头时为空。 |

309| `CLAUDE_RUNNER_POOL_ID` | 新运行器应加入的环境的 ID，采用 `ccpool_...` 形式 |310| `CLAUDE_RUNNER_POOL_ID` | 新运行器应加入的环境的 ID，采用 `ccpool_...` 形式 |

310| `CLAUDE_RUNNER_ACCOUNT_ID` | 排队会话的帐户的标记 ID。请将其用于按帐户路由、配额或费用分摊，而不要用作去重密钥。当不可用时为空，对于 Claude Tag 频道会话始终为空，这些会话没有帐户排队。 |311| `CLAUDE_RUNNER_ACCOUNT_ID` | 排队会话的帐户的标记 ID。请将其用于按帐户路由、配额或费用分摊，而不要用作去重密钥。当不可用时为空。 |

311| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | 排队会话的帐户的电子邮件。当不可用时为空。将电子邮件视为个人可识别信息，不要记录它。 |312| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | 排队会话的帐户的电子邮件。当不可用时为空。将电子邮件视为个人可识别信息，不要记录它。 |

312| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | 会话的第一个 git 源的 URL，用于路由到已预热该仓库的运行器。当会话没有 git 源时为空。 |313| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | 会话的第一个 git 源的 URL，用于路由到已预热该仓库的运行器。当会话没有 git 源时为空。 |

313| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | 会话的第一个 git 源的修订版本：分支、SHA、标签或完整引用名称。当未指定时为空。 |314| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | 会话的第一个 git 源的修订版本：分支、SHA、标签或完整引用名称。当未指定时为空。 |

381 382 

382| 标志及示例值 | 传递给 | 作用 |383| 标志及示例值 | 传递给 | 作用 |

383| :- | :- | :- |384| :- | :- | :- |

384| `--release-idle-session-min 30` | 您的 hook 启动的每个运行器 | 运行器在空闲达到该分钟数后释放其会话，然后以 0 退出。当会话的用户发送下一条消息时，会话会恢复，但[其尚未推送的工作将会丢失](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#additional-limitations)。对于会话遗留的仍在运行的进程，请[保留会话](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#keep-an-idle-session-while-its-processes-run)。 |385| `--release-idle-session-min 30` | 您的 hook 启动的每个运行器 | 运行器在空闲达到该分钟数后释放其会话，然后以 0 退出。当会话的用户发送下一条消息时，会话会恢复，但[其尚未推送的工作将会丢失](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#resumed-sessions-lose-unpushed-work)。对于会话遗留的仍在运行的进程，请[保留会话](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#keep-an-idle-session-while-its-processes-run)。 |

385| `--kill-session-after-min 480` | 您的 hook 启动的每个运行器 | 将每个会话限制为该分钟数，作为[不计为空闲的会话](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#some-sessions-don’t-count-as-idle)的兜底措施，因此请将其设置为高于您预期的最长会话时长 |386| `--kill-session-after-min 480` | 您的 hook 启动的每个运行器 | 将每个会话限制为该分钟数，作为[不计为空闲的会话](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#some-sessions-don’t-count-as-idle)的兜底措施，因此请将其设置为高于您预期的最长会话时长 |

386| `--exit-if-unused-min 60` | 待命运行器，即您的 hook 为预热请求启动的运行器 | 从未接收会话的待命运行器会在该分钟数后退出。如果您设置了 [`--min-idle`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#orchestrator-cli-flags)，除非该待命运行器是多余的，否则您会获得替代运行器，因此请使用远高于启动时间的值。 |387| `--exit-if-unused-min 60` | 待命运行器，即您的 hook 为预热请求启动的运行器 | 从未接收会话的待命运行器会在该分钟数后退出。如果您设置了 [`--min-idle`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#orchestrator-cli-flags)，除非该待命运行器是多余的，否则您会获得替代运行器，因此请使用远高于启动时间的值。 |

387 388 

761 762 

762* **git 身份**：在运行器镜像中设置 `user.name` 和 `user.email`，或使用 [`--configure-git`](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy#let-the-runner-configure-git) 启动运行器763* **git 身份**：在运行器镜像中设置 `user.name` 和 `user.email`，或使用 [`--configure-git`](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy#let-the-runner-configure-git) 启动运行器

763* **推送凭据**：使用 [Anthropic 托管的 git](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy)，或按照[在镜像中提供 git 配置](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#ship-git-config-in-your-image)中的说明提供凭据764* **推送凭据**：使用 [Anthropic 托管的 git](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#use-the-anthropic-git-proxy)，或按照[在镜像中提供 git 配置](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#ship-git-config-in-your-image)中的说明提供凭据

764* **对于恢复的会话**：在环境中的每个运行器上设置 [`--push-outcome-on-release`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags)。这样，恢复的会话将从 Claude 推送到该会话分支的提交开始。有关该标志的限制，请参阅[恢复的会话会丢失未推送的工作](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#additional-limitations)。765* **对于恢复的会话**：在环境中的每个运行器上设置 [`--push-outcome-on-release`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags)。这样，恢复的会话将从 Claude 推送到该会话分支的提交开始。有关该标志的限制，请参阅[恢复的会话会丢失未推送的工作](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#resumed-sessions-lose-unpushed-work)。

765 766 

766Stop hook 每个轮次最多提示一次。如果提交或推送失败，该轮次仍会结束。请在会话中查找 git 的错误信息，并修复其中指出的问题。767Stop hook 每个轮次最多提示一次。如果提交或推送失败，该轮次仍会结束。请在会话中查找 git 的错误信息，并修复其中指出的问题。

767 768 

63 63 

64| 主机 | 端口 | 何时需要 |64| 主机 | 端口 | 何时需要 |

65| :- | :- | :- |65| :- | :- | :- |

66| `api.github.com` | 443 | 无论是否设置 `--use-anthropic-git-proxy`，当运行器镜像包含 [GitHub CLI](#github-api-access-with-the-github-cli) 且您为会话提供 github.com 凭据（例如 `GH_TOKEN`）时 |

66| `downloads.claude.ai` | 443 | 在安装时，当您使用本机安装程序在主机上安装或更新 Claude Code 时；`install.sh` 脚本本身从 `claude.ai` 提供。在会话运行时，仅当会话从官方 Anthropic 市场安装插件时。 |67| `downloads.claude.ai` | 443 | 在安装时，当您使用本机安装程序在主机上安装或更新 Claude Code 时；`install.sh` 脚本本身从 `claude.ai` 提供。在会话运行时，仅当会话从官方 Anthropic 市场安装插件时。 |

67| `storage.googleapis.com` | 443 | 在会话运行时，用于 `/plugin` 中显示的插件安装计数和元数据。 |68| `storage.googleapis.com` | 443 | 在会话运行时，用于 `/plugin` 中显示的插件安装计数和元数据。 |

68| `code.claude.com` 和 `claude.com` | 443 | 内置 claude-code-guide 代理的文档查找和会话期间预批准的 WebFetch 请求。阻止这些主机仅影响文档查找。 |69| `code.claude.com` 和 `claude.com` | 443 | 内置 claude-code-guide 代理的文档查找和会话期间预批准的 WebFetch 请求。阻止这些主机仅影响文档查找。 |

167 168 

168* 运行器设置 `GIT_TERMINAL_PROMPT=0`，所以 git 不要求用户名或密码。169* 运行器设置 `GIT_TERMINAL_PROMPT=0`，所以 git 不要求用户名或密码。

169* 运行器使用 `BatchMode=yes` 运行 SSH，如果您设置了一个，则附加到您的 `GIT_SSH_COMMAND`，所以 SSH 不要求密码短语或主机确认。170* 运行器使用 `BatchMode=yes` 运行 SSH，如果您设置了一个，则附加到您的 `GIT_SSH_COMMAND`，所以 SSH 不要求密码短语或主机确认。

170* 运行器设置 `GCM_INTERACTIVE=never`，所以 Git Credential Manager 不打开登录对话框。171* 运行器设置 `GCM_INTERACTIVE=never`，所以 Git Credential Manager 不打开登录对话框。在 v2.1.229 之前，仓库准备可能会因 Git Credential Manager 提示而挂起。

171* 运行器清除 `core.askPass`，所以如果您使用 askpass 助手，改为通过 `GIT_ASKPASS` 环境变量设置它。172* 运行器清除 `core.askPass`，所以如果您使用 askpass 助手，改为通过 `GIT_ASKPASS` 环境变量设置它。

172 173 

173如果您的 git 主机拒绝凭证，或您没有配置凭证，运行器重试几次然后失败存储库准备（当存储库是会话推送结果的存储库时）。对于会话仅从中读取的存储库，[故障排除](#troubleshooting)涵盖运行器何时改为跳过它。运行器不会将这些设置传递到会话的环境中。174如果您的 git 主机拒绝凭证，或您没有配置凭证，运行器重试几次然后失败存储库准备（当存储库是会话推送结果的存储库时）。对于会话仅从中读取的存储库，[故障排除](#troubleshooting)涵盖运行器何时改为跳过它。运行器不会将这些设置传递到会话的环境中。

287* **`jq`**：如果您希望 `--jq` 可用，请在镜像中安装 `jq`288* **`jq`**：如果您希望 `--jq` 可用，请在镜像中安装 `jq`

288* **[`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/zh-CN/env-vars)**：如果会话环境设置了它，Claude Code 不会提供内置 `gh`，会话也就没有 `gh`289* **[`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/zh-CN/env-vars)**：如果会话环境设置了它，Claude Code 不会提供内置 `gh`，会话也就没有 `gh`

289 290 

290当镜像包含 GitHub CLI 时，会话使用它。291#### 使用 GitHub CLI 访问 GitHub API

292 

293如果您的运行器镜像包含供会话使用的 GitHub CLI，请让您的[包装脚本](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration.md#provision-credentials-scoped-to-the-session-creator)按会话为会话创建者铸造一个短期、最小范围的 `GH_TOKEN`。当 `gh` 位于 Claude Code 启动时所用的 `PATH` 上时，会话使用该 `gh`，而没有[内置 `gh`](#github-api-access-without-the-github-cli)。借助该令牌，该 `gh` 以令牌授予的任何访问权限、在 Anthropic 管理的 git 之外访问 GitHub，因此请允许 [`api.github.com`](#network-requirements)。

294 

295使用 Anthropic 管理的 git 时，请勿在镜像中包含 GitHub CLI，以改用内置 `gh`。

291 296 

292#### 使用 Anthropic 管理的 git 信任专用证书颁发机构297#### 使用 Anthropic 管理的 git 信任专用证书颁发机构

293 298 

343 348 

344主机重写首先运行，因此如果您需要两者，请在 `--git-ssh-rewrite` 中列出内部主机名。为了完全控制检出，使用 [`checkout` 生命周期钩子](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#checkout)。349主机重写首先运行，因此如果您需要两者，请在 `--git-ssh-rewrite` 中列出内部主机名。为了完全控制检出，使用 [`checkout` 生命周期钩子](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#checkout)。

345 350 

351### 在 GitHub 之外的仓库上启动会话

352 

353要在 GitHub 以外的 git 主机上的仓库中运行会话，请从终端在该仓库的检出中启动会话。首先检查运行器的 git 凭据、网络和 git 代理、仓库地址以及您的分支：

354 

355* **Git 凭据和网络**：为运行器克隆的地址 `https://<host>/<owner>/<name>` [提供](#ship-git-config-in-your-image)[无需提示即可工作](#git-must-work-without-a-prompt)的凭据，并按照[网络要求](#network-requirements)所列，允许运行器访问您的 git 主机。对于仅接受 SSH 的 git 主机，请参阅 [`--git-ssh-rewrite`](#rewrite-git-urls-for-private-networks)。

356* **Git 代理**：如果该环境的运行器使用 Anthropic git 代理，请[将其关闭](#turn-the-anthropic-git-proxy-off)。

357* **仓库地址**：检查检出的 `origin` 远程。其主机必须是域名，例如 `git.example.com`，其路径必须采用 `<owner>/<name>` 形式。诸如 `group/subgroup/name` 的嵌套路径无法通过。

358* **分支**：将您当前所在的分支推送到您的 git 主机，因为运行器会克隆该分支。

359 

360在检出中，按照[从 CI 进行身份验证](https://code.claude.com/docs/zh-CN/self-hosted-environments-testing.md#authenticate-from-ci)中的说明登录 claude.ai 后，使用 [`--environment`](https://code.claude.com/docs/zh-CN/self-hosted-environments-testing#run-the-test-loop) 和您环境的 `ccpool_...` ID 运行 `claude -p`：

361 

362```bash theme={null}

363claude -p "Fix the login bug" --environment ccpool_abc123 --output-format json

364```

365 

366创建会话后，该命令会打印一行以 `{"ok":true` 开头的 JSON。如果 `origin` 远程不符合要求，命令会失败并显示 `requires a git source, but no GitHub remote was detected`。

367 

368在您的 git 主机上审查并合并会话[推送](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work)的分支。

369 

346## 构建运行器镜像370## 构建运行器镜像

347 371 

348Anthropic 不发布预构建的运行器镜像。围绕 `claude` 二进制文件构建您自己的，分层您的存储库需要的任何工具链：语言运行时、编译器、包管理器和 [MCP](https://code.claude.com/docs/zh-CN/mcp.md) 边车。372Anthropic 不发布预构建的运行器镜像。围绕 `claude` 二进制文件构建您自己的，分层您的存储库需要的任何工具链：语言运行时、编译器、包管理器和 [MCP](https://code.claude.com/docs/zh-CN/mcp.md) 边车。

617 641 

618### 在重启前让正在运行的轮次完成642### 在重启前让正在运行的轮次完成

619 643 

620若要在滚动重启前让正在运行的轮次完成，请设置 `--drain-wait-sec`，并将停止超时时间提高到至少该等待时间加 80 秒。在默认等待时间为 `0` 的情况下，重启会中断任何仍在运行的轮次，会话将在另一个运行器上恢复，但不包含其[未推送的工作](#additional-limitations)。644若要在滚动重启前让正在运行的轮次完成，请设置 `--drain-wait-sec`，并将停止超时时间提高到至少该等待时间加 80 秒。在默认等待时间为 `0` 的情况下，重启会中断任何仍在运行的轮次，会话将在另一个运行器上恢复，但不包含其[未推送的工作](#resumed-sessions-lose-unpushed-work)。

621 645 

622* **`--drain-wait-sec`**：大致设为您希望等待完成的轮次和后台任务所需的时长。这是一个上限：如果它们先完成，等待会提前结束。646* **`--drain-wait-sec`**：大致设为您希望等待完成的轮次和后台任务所需的时长。这是一个上限：如果它们先完成，等待会提前结束。

623* **您的停止超时时间**：Kubernetes 中的 `terminationGracePeriodSeconds`，Docker Compose 中的 `stop_grace_period`。例如，使用 `--drain-wait-sec 120` 时，将 [Kubernetes](#kubernetes) 或 [Docker Compose](#docker-compose) 配方中的 `90` 替换为 `200`。647* **您的停止超时时间**：Kubernetes 中的 `terminationGracePeriodSeconds`，Docker Compose 中的 `stop_grace_period`。例如，使用 `--drain-wait-sec 120` 时，将 [Kubernetes](#kubernetes) 或 [Docker Compose](#docker-compose) 配方中的 `90` 替换为 `200`。

735 759 

736要释放空闲会话，请使用 [`--release-idle-session-min`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags) 及以分钟为单位的该时间启动每个运行器，例如 `--release-idle-session-min 30`。之后，运行器会释放任何空闲达到该时长的会话，无论该会话是由定时任务还是由人启动的，除非您[为其遗留运行的进程保留该会话](#keep-an-idle-session-while-its-processes-run)。760要释放空闲会话，请使用 [`--release-idle-session-min`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags) 及以分钟为单位的该时间启动每个运行器，例如 `--release-idle-session-min 30`。之后，运行器会释放任何空闲达到该时长的会话，无论该会话是由定时任务还是由人启动的，除非您[为其遗留运行的进程保留该会话](#keep-an-idle-session-while-its-processes-run)。

737 761 

738* **未推送的工作**：被释放的会话会在收到下一条消息时恢复，但不包含其尚未推送的工作。要保留其提交，请参阅[恢复的会话会丢失未推送的工作](#additional-limitations)。762* **未推送的工作**：被释放的会话会在收到下一条消息时恢复，但不包含其尚未推送的工作。要保留其提交，请参阅[恢复的会话会丢失未推送的工作](#resumed-sessions-lose-unpushed-work)。

739* **运行器退出**：释放其最后一个会话的运行器会开始[正常退出](#when-the-runner-exits)。请让您的监管程序在全新的文件系统上重新启动它，如[加固您的部署](#harden-your-deployment)所述。763* **运行器退出**：释放其最后一个会话的运行器会开始[正常退出](#when-the-runner-exits)。请让您的监管程序在全新的文件系统上重新启动它，如[加固您的部署](#harden-your-deployment)所述。

740* **从不进入空闲的会话**：还需设置 [`--kill-session-after-min`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags)，因为[某些会话不计为空闲](#some-sessions-don’t-count-as-idle)764* **从不进入空闲的会话**：还需设置 [`--kill-session-after-min`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags)，因为[某些会话不计为空闲](#some-sessions-don’t-count-as-idle)

741 765 

811* 如果转向仍在运行，运行器等待转向完成，或会话下一次等待其用户，然后释放它。835* 如果转向仍在运行，运行器等待转向完成，或会话下一次等待其用户，然后释放它。

812* 如果会话在宽限窗口结束时仍在运行器上，运行器终止它，任何运行转向的工作丢失。等待从运行中工具调用内请求的批准的转向是会话超过窗口的一种方式。836* 如果会话在宽限窗口结束时仍在运行器上，运行器终止它，任何运行转向的工作丢失。等待从运行中工具调用内请求的批准的转向是会话超过窗口的一种方式。

813 837 

814释放的会话从新克隆恢复，所以它未推送的工作无论如何都消失了；请参阅[恢复的会话丢失未推送的工作](#additional-limitations)。在 v2.1.260 之前，运行器在限制处终止每个会话，最多等待宽限窗口以完成运行转向。838释放的会话从新克隆恢复，所以它未推送的工作无论如何都消失了；请参阅[恢复的会话丢失未推送的工作](#resumed-sessions-lose-unpushed-work)。在 v2.1.260 之前，运行器在限制处终止每个会话，最多等待宽限窗口以完成正在运行的轮次。

815 839 

816将该标志设置为高于您预期的最长会话时长，例如 `--kill-session-after-min 480` 为 8 小时。要从空闲的对话释放槽，改用 `--release-idle-session-min`。840将该标志设置为高于您预期的最长会话时长，例如 `--kill-session-after-min 480` 为 8 小时。要从空闲的对话释放槽，改用 `--release-idle-session-min`。

817 841 

842### 恢复的会话丢失未推送的工作

843 

844在新运行器上恢复的会话会丢失其未推送的工作，因为该运行器会从其起始分支重新克隆仓库。

845 

846要保留已提交的工作，请在环境中的每个运行器上设置 [`--push-outcome-on-release`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags)。设置了该标志的运行器会在释放之前尽力推送会话的结果分支，恢复的会话将从这些提交开始。未设置该标志的运行器会从起始分支恢复会话。推送使用运行器主机自身的 git 凭据，在使用 [Anthropic 托管 git](#use-the-anthropic-git-proxy) 的运行器上也是如此。

847 

848> [!WARNING]

849>

850> 设置该标志之前，请限制谁可以推送到源远程上的 `claude/*` refs。在恢复时，运行器会获取之前推送的分支，而不验证是谁推送的。

851 

852即使设置了该标志，也请通过其他方式保存以下工作：

853 

854* **未提交的更改**：这些更改仍会丢失。请参阅[提示会话推送其工作](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work)。

855* **通过 [`checkout` 生命周期 hook](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#checkout) 检出的仓库**：这些仓库不会被推送。请从 [`post-session` hook](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#post-session) 对其进行快照。

856* **在被某人归档或删除的会话中，或其运行器被某人从会话菜单中释放的会话中的提交**：不要依赖该标志的推送。要保存这些提交，请从 [`post-session` hook](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#post-session) 将 `HEAD` 推送到一个救援分支。那里的示例仅在创建快照提交之后才推送，因此请让您的 hook 在没有任何未提交内容时也执行推送。

857 

818### 其他限制858### 其他限制

819 859 

820* **恢复的会话丢失未推送的工作**：新的运行器会从其起始分支重新克隆仓库，因此会话未推送的工作会丢失。

821 * **要保留已提交的工作**：在环境中的每个运行器上设置 [`--push-outcome-on-release`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags)，因为未设置该标志的运行器会从起始分支恢复会话。设置了该标志的运行器会在释放之前尽力推送会话的结果分支，恢复的会话将从这些提交开始。推送使用运行器主机自身的 git 凭据，在使用 [Anthropic 托管 git](#use-the-anthropic-git-proxy) 的运行器上也是如此。

822 * **使用 `checkout` hook 时**：通过 [`checkout` 生命周期 hook](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#checkout) 检出的仓库不会被推送。请改为从 [`post-session` hook](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#post-session) 对其进行快照。

823 * **启用该标志之前**：限制谁可以推送到源远程上的 `claude/*` refs。在恢复时，运行器会获取之前推送的分支，而不验证是谁推送的。

824 * **未提交的更改仍会丢失**：要提示 Claude 在完成响应时提交并推送，请参阅[提示会话推送其工作](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration.md#prompt-sessions-to-push-their-work)

825* **因运行器丢失而中断的命令可能会再次运行**：当会话在另一个运行器上恢复时，Claude 会看到被中断的工具调用，其结果表明该调用的执行结果未知。860* **因运行器丢失而中断的命令可能会再次运行**：当会话在另一个运行器上恢复时，Claude 会看到被中断的工具调用，其结果表明该调用的执行结果未知。

826* **会话中途添加的仓库可能无法克隆**：Claude 通过 HTTPS 使用 `git clone` 克隆它。在未启用 [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy) 的运行器上，如果主机上没有任何内容能够读取该仓库，克隆会因 git 身份验证错误而失败。如有可能，请在创建会话时选择会话所需的每个仓库。861* **会话中途添加的仓库可能无法克隆**：Claude 通过 HTTPS 使用 `git clone` 克隆它。在未启用 [`--use-anthropic-git-proxy`](#use-the-anthropic-git-proxy) 的运行器上，如果主机上没有任何内容能够读取该仓库，克隆会因 git 身份验证错误而失败。如有可能，请在创建会话时选择会话所需的每个仓库。

827 * **会话恢复时**：[`checkout` hook](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#checkout) 也会为添加的仓库运行，此时 [`CLAUDE_RUNNER_REPO_REF`](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#checkout) 为空，因此请确保您的 hook 能够处理这种情况。862 * **会话恢复时**：[`checkout` hook](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#checkout) 也会为添加的仓库运行，此时 [`CLAUDE_RUNNER_REPO_REF`](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#checkout) 为空，因此请确保您的 hook 能够处理这种情况。

828* **某些连接器不出现在自托管会话中**：您在 claude.ai Settings 中尚未连接的连接器不在自托管会话中列出，会话不会提示您连接它。首先在 Settings 中连接它，然后启动新会话。向已运行的会话添加连接器也不会使其工具对 Claude 可用；启动新会话以获取新添加的连接器。863* **某些连接器不出现在自托管会话中**：您在 claude.ai Settings 中尚未连接的连接器不在自托管会话中列出，会话不会提示您连接它。首先在 Settings 中连接它，然后启动新会话。向已运行的会话添加连接器也不会使其工具对 Claude 可用；启动新会话以获取新添加的连接器。

829* **当有人归档或删除会话，或从会话菜单中释放其运行器时**：不要依赖 [`--push-outcome-on-release`](https://code.claude.com/docs/zh-CN/self-hosted-environments-reference#runner-cli-flags) 的推送。要在这些情况下保存提交，请从 [`post-session` hook](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#post-session) 将 `HEAD` 推送到一个救援分支。如果您以那里的示例为基础，请让它在没有任何未提交内容时也执行推送，因为该示例仅在创建快照提交之后才推送。

830 864 

831### 报告问题865### 报告问题

832 866 

84 84 

85**7. 读取身份**85**7. 读取身份**

86 86 

87创建者的用户身份位于 `act` 声明中：`act.sub` 是其 Anthropic 用户 ID，采用带前缀的形式 `user:<id>`；`act.email`（当创建会话的使用入口记录了该信息时）是其电子邮件地址。由您组织的服务身份创建的会话（包括 Claude Tag 频道会话）则携带 `agent:` 主体，因此，仅当 `act.sub` 带有 `user:` 前缀时才将会话视为用户创建，而不是通过检测身份声明是否缺失来判断。有关完整结构和扁平的重复声明，请参阅[声明参考](#claims-reference)。87创建者的用户身份位于 `act` 声明中。`act.sub` 是其 Anthropic 用户 ID，采用带前缀的形式 `user:<id>`；`act.email`（当创建会话的使用入口记录了该信息时）是其电子邮件地址。由您组织的服务身份创建的会话则携带 `agent:` 主体。仅当 `act.sub` 带有 `user:` 前缀时才将会话视为用户创建，而不是通过检测身份声明是否缺失来判断。

88 

89有关完整结构和扁平的重复声明，请参阅[声明参考](#claims-reference)。

88 90 

89这些检查可以直接对应到标准 JWT 库。以下示例分别在 Node.js 中使用 [`jose`](https://www.npmjs.com/package/jose)（它负责 JWKS 的获取、缓存和 `kid` 选择），以及在 Python 中使用 [`PyJWT`](https://pyjwt.readthedocs.io/) 及其内置的 JWKS 客户端，实现了完整的检查流程。91这些检查可以直接对应到标准 JWT 库。以下示例分别在 Node.js 中使用 [`jose`](https://www.npmjs.com/package/jose)（它负责 JWKS 的获取、缓存和 `kid` 选择），以及在 Python 中使用 [`PyJWT`](https://pyjwt.readthedocs.io/) 及其内置的 JWKS 客户端，实现了完整的检查流程。

90 92 

185 187 

186## 声明参考188## 声明参考

187 189 

188下表列出了与验证相关的会话令牌声明。从 `ccr:*` 命名空间和 `act` 链读取身份；平面 `account_email`、`organization_uuid` 和 `account_uuid` 声明是可能被删除的向后兼容性重复项。您组织的服务身份创建的会话（包括 Claude Tag 频道会话）在 `act.sub` 中携带 `agent:` 主题，并省略 `act.email`、`ccr:account_id`、`account_email` 和 `account_uuid`。两个电子邮件声明对于用户创建的会话也是可选的：Anthropic 仅在创建请求的凭证携带电子邮件时在会话创建时记录它们，从 CLI 分派的会话可能两者都缺少，因此根据 `act.sub` 或 `ccr:account_id` 而不是电子邮件来确定身份。令牌也可以携带此表之外的其他声明；忽略您不认识的声明。190从 `ccr:*` 命名空间和 `act` 链读取身份；平面 `account_email`、`organization_uuid` 和 `account_uuid` 声明是可能被删除的向后兼容性重复项。您组织的服务身份创建的会话在 `act.sub` 中携带 `agent:` 主题，并省略 `act.email`、`ccr:account_id`、`account_email` 和 `account_uuid`。

191 

192两个电子邮件声明对于用户创建的会话也是可选的。Anthropic 仅在创建请求的凭据携带电子邮件时才会在会话创建时记录它们，从 CLI 分派的会话可能两者都缺少。请根据 `act.sub` 或 `ccr:account_id` 而不是电子邮件来确定身份。令牌也可以携带此表之外的其他声明；忽略您不认识的声明。下表列出了与验证相关的会话令牌声明。

189 193 

190| 声明 | 类型 | 描述 |194| 声明 | 类型 | 描述 |

191| :- | :- | :- |195| :- | :- | :- |

211 215 

212| 路径 | 描述 |216| 路径 | 描述 |

213| :- | :- |217| :- | :- |

214| `act.sub` | 创建用户的 Anthropic 用户 ID，形式为 `user:<id>`，或当您组织的服务身份创建会话时为 `agent:<id>`，就像它对 Claude Tag 频道会话所做的那样。 |218| `act.sub` | 创建用户的 Anthropic 用户 ID，形式为 `user:<id>`，或当您组织的服务身份创建会话时为 `agent:<id>`。 |

215| `act.email` | 创建用户的电子邮件地址，当在会话创建时记录了一个时。不要求它；根据 `act.sub` 确定身份。 |219| `act.email` | 创建用户的电子邮件地址，当在会话创建时记录了一个时。不要求它；根据 `act.sub` 确定身份。 |

216| `act.attested_by` | 保留用于上游身份提供程序对创建用户的证明。预期它不存在，请勿依赖它。根据 `act.sub` 确定身份。如果您需要地址，请在 `act.email` 存在时读取它。 |220| `act.attested_by` | 保留用于上游身份提供程序对创建用户的证明。预期它不存在，请勿依赖它。根据 `act.sub` 确定身份。如果您需要地址，请在 `act.email` 存在时读取它。 |

217| `act.act` | 生成会话的运行程序。`act.act.sub` 是 `ccr:runner:<runner_id>`。 |221| `act.act` | 生成会话的运行程序。`act.act.sub` 是 `ccr:runner:<runner_id>`。 |

48| `--post-session-hook-timeout-sec <n>` | `SELF_HOSTED_RUNNER_POST_SESSION_HOOK_TIMEOUT_MS` | `60` | 每次会话结束时（包括 runner 关闭时）[`post-session` hook](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#post-session) 的时间预算 |48| `--post-session-hook-timeout-sec <n>` | `SELF_HOSTED_RUNNER_POST_SESSION_HOOK_TIMEOUT_MS` | `60` | 每次会话结束时（包括 runner 关闭时）[`post-session` hook](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#post-session) 的时间预算 |

49| `--proxy-authorization-command <command>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_COMMAND` | 未设置 | runner 在每次连接您的出口代理时运行的 shell 命令，其去除首尾空白后的 stdout 用作 `Proxy-Authorization` 标头值。需要 `HTTPS_PROXY` 或 `HTTP_PROXY`，且不能与 `--proxy-authorization-file` 同时使用。请参阅[向出口代理进行身份验证](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#authenticate-to-an-egress-proxy)。需要 Claude Code v2.1.238 或更高版本。 |49| `--proxy-authorization-command <command>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_COMMAND` | 未设置 | runner 在每次连接您的出口代理时运行的 shell 命令，其去除首尾空白后的 stdout 用作 `Proxy-Authorization` 标头值。需要 `HTTPS_PROXY` 或 `HTTP_PROXY`，且不能与 `--proxy-authorization-file` 同时使用。请参阅[向出口代理进行身份验证](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#authenticate-to-an-egress-proxy)。需要 Claude Code v2.1.238 或更高版本。 |

50| `--proxy-authorization-file <path>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_FILE` | 未设置 | runner 在每次连接您的出口代理时读取的文件，其去除首尾空白后的内容用作 `Proxy-Authorization` 标头值。对于由其他进程原地轮换的令牌，请使用此标志。要求与 `--proxy-authorization-command` 相同，且不能与其同时使用。请参阅[向出口代理进行身份验证](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#authenticate-to-an-egress-proxy)。需要 Claude Code v2.1.238 或更高版本。 |50| `--proxy-authorization-file <path>` | `SELF_HOSTED_RUNNER_PROXY_AUTHORIZATION_FILE` | 未设置 | runner 在每次连接您的出口代理时读取的文件，其去除首尾空白后的内容用作 `Proxy-Authorization` 标头值。对于由其他进程原地轮换的令牌，请使用此标志。要求与 `--proxy-authorization-command` 相同，且不能与其同时使用。请参阅[向出口代理进行身份验证](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#authenticate-to-an-egress-proxy)。需要 Claude Code v2.1.238 或更高版本。 |

51| `--push-outcome-on-release` | `SELF_HOSTED_RUNNER_PUSH_OUTCOME_ON_RELEASE` | 关闭 | 在 runner 因排空或空闲释放等原因主动结束会话时，在删除工作区之前将跟踪的结果分支推送到 `origin`，以便进行中的提交在重启后得以保留。尽力而为；会为关闭预算增加 30 秒，且需要 git 2.29 或更高版本才能从推送的分支恢复。启用前请限制谁可以推送到 `claude/*` 引用；请参阅[恢复的会话会丢失未推送的工作](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#additional-limitations)。通过 `checkout` 生命周期 hook 检出的仓库不会被推送；请改为在 [`post-session` hook](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#post-session) 中为其创建快照。 |51| `--push-outcome-on-release` | `SELF_HOSTED_RUNNER_PUSH_OUTCOME_ON_RELEASE` | 关闭 | 在 runner 因排空或空闲释放等原因主动结束会话时，runner 会在删除工作区之前，将包含新提交的主会话分支推送到 `origin`。尽力而为；会为关闭预算增加 30 秒。需要 git 2.29 或更高版本才能从这些分支恢复。请将推送权限限制在 `claude/*` 引用；请参阅[恢复的会话会丢失未推送的工作](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#resumed-sessions-lose-unpushed-work)。`checkout` hook 检出的仓库不会被推送；请在 [`post-session` hook](https://code.claude.com/docs/zh-CN/self-hosted-environments-configuration#post-session) 中为其创建快照。 |

52| `--release-idle-session-min <n>` | `SELF_HOSTED_RUNNER_SESSION_IDLE_MS` | `0` | 在轮次结束或会话等待用户操作后，若不活动达 N 分钟，则释放会话槽位。[某些会话不计为空闲](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#some-sessions-don’t-count-as-idle)，因此请搭配 `--kill-session-after-min` 使用。已完成的后台任务会使会话保持忙碌状态，最长不超过 [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings) 窗口。要推迟释放，请设置 [`--hold-idle-file`](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy#keep-an-idle-session-while-its-processes-run)。`0` 表示禁用。 |52| `--release-idle-session-min <n>` | `SELF_HOSTED_RUNNER_SESSION_IDLE_MS` | `0` | 在轮次结束或会话等待用户操作后，若不活动达 N 分钟，则释放会话槽位。[某些会话不计为空闲](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#some-sessions-don’t-count-as-idle)，因此请搭配 `--kill-session-after-min` 使用。已完成的后台任务会使会话保持忙碌状态，最长不超过 [`SELF_HOSTED_RUNNER_BG_RESULT_GRACE_MS`](#environment-variable-only-settings) 窗口。要推迟释放，请设置 [`--hold-idle-file`](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy#keep-an-idle-session-while-its-processes-run)。`0` 表示禁用。 |

53| `--remove-session-state [bool]` | `SELF_HOSTED_RUNNER_REMOVE_SESSION_STATE` | 关闭 | 当会话在此 runner 上结束时，无论结果如何，都删除该会话在 `<base-dir>/_sessions/` 下的每会话目录。[复用预热的检出](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#reuse-a-pre-warmed-checkout)介绍了这些目录保存的内容，以及它们保留时谁可以读取。删除是尽力而为的：如果 runner 在清理运行之前被终止或到达其排空截止时间，每会话目录将保留原位。启用该标志后，失败或中断的会话的调试日志不会保留在磁盘上。需要 Claude Code v2.1.268 或更高版本。 |53| `--remove-session-state [bool]` | `SELF_HOSTED_RUNNER_REMOVE_SESSION_STATE` | 关闭 | 当会话在此 runner 上结束时，无论结果如何，都删除该会话在 `<base-dir>/_sessions/` 下的每会话目录。[复用预热的检出](https://code.claude.com/docs/zh-CN/self-hosted-environments-deploy.md#reuse-a-pre-warmed-checkout)介绍了这些目录保存的内容，以及它们保留时谁可以读取。删除是尽力而为的：如果 runner 在清理运行之前被终止或到达其排空截止时间，每会话目录将保留原位。启用该标志后，失败或中断的会话的调试日志不会保留在磁盘上。需要 Claude Code v2.1.268 或更高版本。 |

54| `--retire-at <epoch-seconds>` | `SELF_HOSTED_RUNNER_RETIRE_AT` | 未设置 | 在以秒为单位的绝对 Unix 时间戳处让 runner 退役，适用于会在已知时间终止 runner 的基础设施；[Runner 生命周期](https://code.claude.com/docs/zh-CN/self-hosted-environments#runner-lifecycle)介绍了释放顺序以及如何确定余量。早于 2001 年或晚于 5138 年的值会被该标志拒绝，并被该环境变量忽略。 |54| `--retire-at <epoch-seconds>` | `SELF_HOSTED_RUNNER_RETIRE_AT` | 未设置 | 在以秒为单位的绝对 Unix 时间戳处让 runner 退役，适用于会在已知时间终止 runner 的基础设施；[Runner 生命周期](https://code.claude.com/docs/zh-CN/self-hosted-environments#runner-lifecycle)介绍了释放顺序以及如何确定余量。早于 2001 年或晚于 5138 年的值会被该标志拒绝，并被该环境变量忽略。 |

294 294 

295#### 权限规则组合方式与您预期不同295#### 权限规则组合方式与您预期不同

296 296 

297* **您在权限提示上选择了"是的，不要再问"但仍然为相同的工具获得提示。** 该选择将 `allow` 规则保存到您的本地文件，本地的 `allow` 规则不优先于项目或托管文件中的 `ask` 规则；[权限规则如何组合](https://code.claude.com/docs/zh-CN/permissions.md#settings-precedence)解释顺序。在 VS Code 扩展中，批准卡让您选择目标文件，包括项目的共享文件，这改变了每个人的规则；在 CLI 中，Claude Code 仅写入您的本地文件。297* **您在权限提示上选择了"Yes, and don't ask again"但仍然为相同的工具获得提示。** 该选择将 `allow` 规则保存到您的本地文件，本地的 `allow` 规则不优先于项目或托管文件中的 `ask` 规则；[权限规则如何组合](https://code.claude.com/docs/zh-CN/permissions.md#settings-precedence)解释顺序。在 VS Code 扩展中，批准卡让您选择目标文件，包括项目的共享文件，这改变了每个人的规则；在 CLI 中，Claude Code 仅写入您的本地文件。

298* **您的组织的允许规则仍然与您的一起应用。** 这是预期的：Claude Code 跨作用域合并 [`permissions.allow`](https://code.claude.com/docs/zh-CN/settings-reference#permissions-allow)，除非您的组织设置 [`allowManagedPermissionRulesOnly`](https://code.claude.com/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly)。298* **您的组织的允许规则仍然与您的一起应用。** 这是预期的：Claude Code 跨作用域合并 [`permissions.allow`](https://code.claude.com/docs/zh-CN/settings-reference#permissions-allow)，除非您的组织设置 [`allowManagedPermissionRulesOnly`](https://code.claude.com/docs/zh-CN/settings-reference#allowmanagedpermissionrulesonly)。

299 299 

300### 托管设置优先级的例外300### 托管设置优先级的例外

4846 4846 

4847### `disableDeepLinkRegistration`4847### `disableDeepLinkRegistration`

4848 4848 

4849阻止 Claude Code 向操作系统注册 `claude-cli://` 协议处理程序；否则，Claude Code 会在您发送交互式会话的第一条提示词后进行注册。[深度链接](https://code.claude.com/docs/zh-CN/deep-links.md)允许外部工具打开带有预填提示词的 Claude Code 会话。在协议处理程序注册受限或单独管理的环境中设置此项。4849阻止 Claude Code 向操作系统注册 `claude-cli://` 协议处理程序。[深度链接](https://code.claude.com/docs/zh-CN/deep-links.md)允许外部工具打开带有预填提示词的 Claude Code 会话。在协议处理程序注册受限或单独管理的环境中设置此项。

4850 4850 

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

4852* **类型**：字符串 `"disable"`4852* **类型**：字符串 `"disable"`

5801 5801 

5802在每个交互式 CLI 会话启动时开启 [Chrome 集成](https://code.claude.com/docs/zh-CN/chrome.md)，无需每次都传入 `--chrome`。如果您运行 [`claude remote-control`](https://code.claude.com/docs/zh-CN/remote-control)，它为您的某个[项目](https://code.claude.com/docs/zh-CN/claude-projects.md)线程启动的会话也会遵循此键，`bypassPermissions` 模式除外。在 Claude Code v2.1.287 或更高版本中，此键也适用于 [VS Code 扩展](https://code.claude.com/docs/zh-CN/vs-code.md#automate-browser-tasks-with-chrome)中的会话：请参阅[默认启用 Chrome](https://code.claude.com/docs/zh-CN/chrome.md#enable-chrome-by-default)。5802在每个交互式 CLI 会话启动时开启 [Chrome 集成](https://code.claude.com/docs/zh-CN/chrome.md)，无需每次都传入 `--chrome`。如果您运行 [`claude remote-control`](https://code.claude.com/docs/zh-CN/remote-control)，它为您的某个[项目](https://code.claude.com/docs/zh-CN/claude-projects.md)线程启动的会话也会遵循此键，`bypassPermissions` 模式除外。在 Claude Code v2.1.287 或更高版本中，此键也适用于 [VS Code 扩展](https://code.claude.com/docs/zh-CN/vs-code.md#automate-browser-tasks-with-chrome)中的会话：请参阅[默认启用 Chrome](https://code.claude.com/docs/zh-CN/chrome.md#enable-chrome-by-default)。

5803 5803 

5804运行 `/chrome` 并选择 **Enabled by default** 会自动设置此键。此项在 `/config` 中显示为 **Claude in Chrome enabled by default**。5804运行 `/chrome` 并选择 **Enabled by default** 会自动设置此键，回应 [“Claude in Chrome extension detected” 对话框](https://code.claude.com/docs/zh-CN/chrome.md#answer-the-startup-dialog)也会设置此键。此项在 `/config` 中显示为 **Claude in Chrome enabled by default**。

5805 5805 

5806* **作用域**：[`Global config`](#scopes)5806* **作用域**：[`Global config`](#scopes)

5807* **类型**：Boolean5807* **类型**：Boolean

39 39 

40**macOS、Linux、WSL：**40**macOS、Linux、WSL：**

41 41 

42```bash theme={null}42```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

43curl -fsSL https://claude.ai/install.sh | bash43curl -fsSL https://claude.ai/install.sh | bash

44```44```

45 45 

47 47 

48**Windows PowerShell：**48**Windows PowerShell：**

49 49 

50```powershell theme={null}50```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

51irm https://claude.ai/install.ps1 | iex51irm https://claude.ai/install.ps1 | iex

52```52```

53 53 

54**Windows CMD：**54**Windows CMD：**

55 55 

56```batch theme={null}56```batch theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

57curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd57curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

58```58```

59 59 

71 71 

72**Homebrew**72**Homebrew**

73 73 

74```bash theme={null}74```bash theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

75brew install --cask claude-code75brew install --cask claude-code

76```76```

77 77 

83 83 

84**WinGet**84**WinGet**

85 85 

86```powershell theme={null}86```powershell theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null} theme={null}

87winget install Anthropic.ClaudeCode87winget install Anthropic.ClaudeCode

88```88```

89 89 

458 458 

459### 使用 npm 安装459### 使用 npm 安装

460 460 

461> [!NOTE]

462>

463> 如果在您的 shell 中 `npm --version` 打印的版本以 `12` 开头，请改为按照[修复 npm 12 安装](https://code.claude.com/docs/zh-CN/troubleshoot-install.md#fix-an-npm-12-install)进行操作。不要使用 `sudo` 安装。Claude Code 在自我更新时运行 npm 不使用 `sudo`，因此需要 `sudo` 的安装无法自动更新。

464 

461您也可以将 Claude Code 安装为全局 npm 包。npm 包需要 [Node.js 22 或更高版本](https://nodejs.org/en/download)。在较旧的 Node.js 版本上，npm 在安装期间打印 `EBADENGINE` 警告而不是失败；安装完成，`claude` 仍然运行，因为该包下载了在运行时不使用您的 Node.js 的原生二进制文件。465您也可以将 Claude Code 安装为全局 npm 包。npm 包需要 [Node.js 22 或更高版本](https://nodejs.org/en/download)。在较旧的 Node.js 版本上，npm 在安装期间打印 `EBADENGINE` 警告而不是失败；安装完成，`claude` 仍然运行，因为该包下载了在运行时不使用您的 Node.js 的原生二进制文件。

462 466 

463```bash theme={null}467```bash theme={null}

404| `allowed-tools` | 否 | 在调用此 skill 的轮次中，Claude 无需请求权限即可使用的工具。当您发送下一条消息时，该授予即被清除。接受以空格或逗号分隔的字符串，或 YAML 列表。请参阅[为 skill 预先批准工具](#pre-approve-tools-for-a-skill)。 |404| `allowed-tools` | 否 | 在调用此 skill 的轮次中，Claude 无需请求权限即可使用的工具。当您发送下一条消息时，该授予即被清除。接受以空格或逗号分隔的字符串，或 YAML 列表。请参阅[为 skill 预先批准工具](#pre-approve-tools-for-a-skill)。 |

405| `disallowed-tools` | 否 | 在此 skill 处于活动状态时，从 Claude 可用工具池中移除的工具。适用于永远不应调用某些工具的自主 skill，例如对后台循环禁用 `AskUserQuestion`。接受以空格或逗号分隔的字符串，或 YAML 列表。当您发送下一条消息时，该限制即被清除。与拒绝规则一样，只要还有其他工具存在，该字段就无法移除 [`EndConversation`](https://code.claude.com/docs/zh-CN/tools-reference#endconversation-tool-behavior)。 |405| `disallowed-tools` | 否 | 在此 skill 处于活动状态时，从 Claude 可用工具池中移除的工具。适用于永远不应调用某些工具的自主 skill，例如对后台循环禁用 `AskUserQuestion`。接受以空格或逗号分隔的字符串，或 YAML 列表。当您发送下一条消息时，该限制即被清除。与拒绝规则一样，只要还有其他工具存在，该字段就无法移除 [`EndConversation`](https://code.claude.com/docs/zh-CN/tools-reference#endconversation-tool-behavior)。 |

406| `model` | 否 | 此 skill 处于活动状态时使用的模型。该覆盖适用于当前轮次的剩余部分，且不会保存到设置中。当您发送下一个提示词时，会话模型即恢复。接受与 [`/model`](https://code.claude.com/docs/zh-CN/model-config) 相同的值，或使用 `inherit` 保留当前活动的模型。被组织的 [`availableModels`](https://code.claude.com/docs/zh-CN/model-config#restrict-model-selection) 允许列表排除的值不会被使用，会话将保留其当前模型。在[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)下，以及在[分类器审查命令时的计划模式](https://code.claude.com/docs/zh-CN/permission-modes.md#analyze-before-you-edit-with-plan-mode)下，自动模式不支持的模型同样不会被使用，会话将保留其当前模型。使用 `context: fork` 时，该值改为设置[分叉子代理的模型](#run-skills-in-a-subagent)，被排除的值遵循[与子代理模型覆盖相同的规则](https://code.claude.com/docs/zh-CN/model-config.md#restrict-model-selection)。 |406| `model` | 否 | 此 skill 处于活动状态时使用的模型。该覆盖适用于当前轮次的剩余部分，且不会保存到设置中。当您发送下一个提示词时，会话模型即恢复。接受与 [`/model`](https://code.claude.com/docs/zh-CN/model-config) 相同的值，或使用 `inherit` 保留当前活动的模型。被组织的 [`availableModels`](https://code.claude.com/docs/zh-CN/model-config#restrict-model-selection) 允许列表排除的值不会被使用，会话将保留其当前模型。在[自动模式](https://code.claude.com/docs/zh-CN/permission-modes.md#eliminate-prompts-with-auto-mode)下，以及在[分类器审查命令时的计划模式](https://code.claude.com/docs/zh-CN/permission-modes.md#analyze-before-you-edit-with-plan-mode)下，自动模式不支持的模型同样不会被使用，会话将保留其当前模型。使用 `context: fork` 时，该值改为设置[分叉子代理的模型](#run-skills-in-a-subagent)，被排除的值遵循[与子代理模型覆盖相同的规则](https://code.claude.com/docs/zh-CN/model-config.md#restrict-model-selection)。 |

407| `effort` | 否 | 此 skill 处于活动状态时的 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)。覆盖会话的 effort 级别。省略该字段时，级别由 [effort 解析顺序](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)决定。选项：`low`、`medium`、`high`、`xhigh`、`max`；可用级别取决于模型。 |407| `effort` | 否 | 当前轮次剩余部分的 [effort 级别](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)。覆盖会话的 effort 级别，但不会覆盖 [`CLAUDE_CODE_EFFORT_LEVEL`](https://code.claude.com/docs/zh-CN/env-vars#variables) 环境变量。使用 `context: fork` 时，该值改为设置分叉子代理的 effort 级别。省略该字段时，级别由 [effort 解析顺序](https://code.claude.com/docs/zh-CN/model-config.md#adjust-effort-level)决定。选项：`low`、`medium`、`high`、`xhigh`、`max`；可用级别取决于模型。 |

408| `context` | 否 | 设置为 `fork` 可在分叉的子代理上下文中运行。请参阅[在子代理中运行 skill](#run-skills-in-a-subagent)。 |408| `context` | 否 | 设置为 `fork` 可在分叉的子代理上下文中运行。请参阅[在子代理中运行 skill](#run-skills-in-a-subagent)。 |

409| `agent` | 否 | 设置 `context: fork` 时使用的子代理类型。 |409| `agent` | 否 | 设置 `context: fork` 时使用的子代理类型。 |

410| `background` | 否 | 仅在使用 `context: fork` 时适用。设置为 `false` 可在调用该 skill 的轮次中等待分叉子代理的结果，而不是[在后台运行它](#run-skills-in-a-subagent)。默认值：`true`。 |410| `background` | 否 | 仅在使用 `context: fork` 时适用。设置为 `false` 可在调用该 skill 的轮次中等待分叉子代理的结果，而不是[在后台运行它](#run-skills-in-a-subagent)。默认值：`true`。 |

200 200 

201### 来自 Claude Tag 频道的会话启动失败201### 来自 Claude Tag 频道的会话启动失败

202 202 

203此条目适用于使用 [Claude Tag](https://claude.com/docs/claude-tag/overview) 的工作区，其中 Claude 在频道中作为您组织的共享身份工作，而不是作为任何成员的账户。如果您在 [claude.ai/code](https://claude.ai/code) 创建了频道的云环境，它属于您的个人账户，Claude 无法在个人环境中启动频道会话。Claude Code 会立即使会话失败，重试也无法帮助。203此条目适用于使用 [Claude Tag](https://claude.com/docs/claude-tag/overview) 的工作区。如果您在 [claude.ai/code](https://claude.ai/code) 创建了频道的云环境，它属于您的个人账户，Claude 无法在个人环境中启动频道会话。Claude Code 会立即使会话失败，重试也无法帮助。

204 204 

205如果您是所有者且环境是您自己的，请从环境选择器中[与组织共享](https://code.claude.com/docs/zh-CN/cloud-environments.md#organization-shared-environments)。否则，所有者可从[管理设置](https://claude.ai/admin-settings)中的**云环境**页面将其重新创建为组织共享环境。205如果您是所有者且环境是您自己的，请从环境选择器中[与组织共享](https://code.claude.com/docs/zh-CN/cloud-environments.md#organization-shared-environments)。否则，所有者可从[管理设置](https://claude.ai/admin-settings)中的**云环境**页面将其重新创建为组织共享环境。

206 206 

188| `context_window.current_usage` | 上一次 API 调用的 token 数，详见[上下文窗口字段](#context-window-fields) |188| `context_window.current_usage` | 上一次 API 调用的 token 数，详见[上下文窗口字段](#context-window-fields) |

189| `exceeds_200k_tokens` | 最近一次 API 响应的 token 总数（输入、缓存和输出 token 之和）是否超过 200k。这是一个固定阈值，与实际上下文窗口大小无关。 |189| `exceeds_200k_tokens` | 最近一次 API 响应的 token 总数（输入、缓存和输出 token 之和）是否超过 200k。这是一个固定阈值，与实际上下文窗口大小无关。 |

190| `fast_mode` | 会话是否启用了[快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md) |190| `fast_mode` | 会话是否启用了[快速模式](https://code.claude.com/docs/zh-CN/fast-mode.md) |

191| `effort.level` | 当前推理努力程度（`low`、`medium`、`high`、`xhigh` 或 `max`）。反映会话的实时值，包括会话中途通过 `/effort` 进行的更改。当前模型不支持 effort 参数时不存在 |191| `effort.level` | 为会话设置的推理 effort 级别（`low`、`medium`、`high`、`xhigh` 或 `max`），而不是由 skill、子代理或 `ultrathink` 设置的级别。如果您设置了模型不支持的级别，此处显示 Claude Code 实际运行时使用的级别。您更改的级别即使在[生效](https://code.claude.com/docs/zh-CN/model-config.md#when-a-new-effort-level-starts)之前也会显示在此处。如果在 `CLAUDE_CODE_EFFORT_LEVEL` 中设置了级别，此处显示该级别。当前模型不支持 effort 参数时不存在 |

192| `thinking.enabled` | 会话是否启用了扩展思考 |192| `thinking.enabled` | 会话是否启用了扩展思考 |

193| `rate_limits.five_hour.used_percentage`、`rate_limits.seven_day.used_percentage` | 5 小时或 7 天速率限制的已用百分比，范围为 0 到 100 |193| `rate_limits.five_hour.used_percentage`、`rate_limits.seven_day.used_percentage` | 5 小时或 7 天速率限制的已用百分比，范围为 0 到 100 |

194| `rate_limits.five_hour.resets_at`、`rate_limits.seven_day.resets_at` | 5 小时或 7 天速率限制窗口重置的时间（Unix 纪元秒） |194| `rate_limits.five_hour.resets_at`、`rate_limits.seven_day.resets_at` | 5 小时或 7 天速率限制窗口重置的时间（Unix 纪元秒） |

72 72 

73当 Claude 完成任务或暂停以等待权限提示，且您似乎离开了终端时，它会触发通知事件。请参阅[每种通知类型何时触发](https://code.claude.com/docs/zh-CN/hooks.md#notification)以了解确切的时间。将其显示为终端铃声或桌面通知可让您在长任务运行时切换到其他工作。73当 Claude 完成任务或暂停以等待权限提示，且您似乎离开了终端时，它会触发通知事件。请参阅[每种通知类型何时触发](https://code.claude.com/docs/zh-CN/hooks.md#notification)以了解确切的时间。将其显示为终端铃声或桌面通知可让您在长任务运行时切换到其他工作。

74 74 

75默认情况下，Claude Code 仅在 Ghostty、Kitty 和 iTerm2 中发送桌面通知。在其他终端中，将 [`preferredNotifChannel`](https://code.claude.com/docs/zh-CN/settings-reference#preferrednotifchannel) 设置为 `"terminal_bell"` 以改为响铃终端铃声，或配置[通知 hook](#play-a-sound-with-a-notification-hook) 以获得自定义声音或命令。以下设置条目打开终端铃声：75默认情况下，Claude Code 在某些终端中发送桌面通知，在其他终端中则发送铃声字符或不发送任何内容：

76 

77* **Ghostty、Kitty 和 iTerm2**：发送桌面通知，其中 iTerm2 仅在您启用其警报设置后才会显示。

78* **Apple Terminal**：没有声音；当 Claude Code 发现最前方 Terminal 窗口的描述文件中"Audible bell"已关闭时，发送静音铃声字符，否则不发送任何内容。如果该描述文件的"Visual bell"或 Dock 弹跳选项已启用，该铃声字符会显示为窗口闪烁，或在 Terminal 处于后台时显示为 Dock 图标弹跳。

79* **其他终端**：不发送任何内容。

80 

81若要让 Claude Code 无论使用何种终端或描述文件都发送铃声字符，请将 [`preferredNotifChannel`](https://code.claude.com/docs/zh-CN/settings-reference#preferrednotifchannel) 设置为 `"terminal_bell"`。在 Apple Terminal 中，还需在 **Settings > Profiles > Advanced** 下启用 **Audible bell** 才能听到铃声。以下设置条目用于设置该通道：

76 82 

77```json ~/.claude/settings.json theme={null}83```json ~/.claude/settings.json theme={null}

78{84{

995 995 

996### WSL 中的 npm 安装错误996### WSL 中的 npm 安装错误

997 997 

998如果您在 WSL 内使用 `npm install -g` 安装了 Claude Code，这些问题适用。如果您使用了[本机安装程序](https://code.claude.com/docs/zh-CN/setup.md)，请跳过本部分。998如果您在 WSL 内使用 `npm install -g` 安装了 Claude Code，这些问题适用。如果您使用了[本机安装程序](https://code.claude.com/docs/zh-CN/setup.md)，请跳过本部分。在 npm 12 上，请按照[修复 npm 12 安装](#fix-an-npm-12-install)中的说明进行安装。

999 999 

1000**OS 或平台检测问题。** 如果 npm 在安装期间报告平台不匹配，WSL 可能正在选择 Windows `npm`。首先运行 `npm config set os linux`，然后使用 `npm install -g @anthropic-ai/claude-code --force` 安装。不要使用 `sudo`。1000**OS 或平台检测问题。** 如果 npm 在安装期间报告平台不匹配，WSL 可能正在选择 Windows `npm`。首先运行 `npm config set os linux`，然后使用 `npm install -g @anthropic-ai/claude-code --force` 安装。不要使用 `sudo`。

1001 1001 

1037 1037 

1038### npm 安装后找不到本机二进制文件1038### npm 安装后找不到本机二进制文件

1039 1039 

1040`@anthropic-ai/claude-code` npm 包下载本机二进制文件作为每个平台的可选依赖项，例如 `@anthropic-ai/claude-code-darwin-arm64`。npm 然后运行包的 postinstall 脚本，将该二进制文件复制到位作为 `claude` 命令；在它运行之前，`claude` 是一个占位符脚本。如果下载或 postinstall 步骤被跳过，占位符保留在位，在 macOS 和 Linux 上运行 `claude` 打印：1040`@anthropic-ai/claude-code` npm 包将本机二进制文件作为每个平台的可选依赖项下载，例如 `@anthropic-ai/claude-code-darwin-arm64`。在 `@anthropic-ai/claude-code` 包的 postinstall 步骤运行并用该二进制文件替换占位符之前，`claude` 是一个占位符脚本。如果下载或 postinstall 步骤被跳过，占位符保留在位，在 macOS 和 Linux 上运行 `claude` 打印：

1041 1041 

1042```text theme={null}1042```text theme={null}

1043Error: claude native binary not installed.1043Error: claude native binary not installed.

1056 1056 

1057检查以下原因：1057检查以下原因：

1058 1058 

1059* **npm 12 默认跳过 postinstall 步骤。** 当您使用 npm 12 安装或更新 Claude Code 时，npm 仍会在不运行该步骤的情况下完成安装。请参阅[修复 npm 12 安装](#fix-an-npm-12-install)。

1059* **可选依赖项被禁用。** 从您的 npm install 命令中删除 `--omit=optional`，从 pnpm 中删除 `--no-optional`，或从 yarn 中删除 `--ignore-optional`，并检查 `.npmrc` 不设置 `optional=false`。然后重新安装。本机二进制文件仅作为可选依赖项交付，因此如果跳过它，没有 JavaScript 回退，再次运行 `install.cjs` 无法放置从未下载的二进制文件。1060* **可选依赖项被禁用。** 从您的 npm install 命令中删除 `--omit=optional`，从 pnpm 中删除 `--no-optional`，或从 yarn 中删除 `--ignore-optional`，并检查 `.npmrc` 不设置 `optional=false`。然后重新安装。本机二进制文件仅作为可选依赖项交付，因此如果跳过它，没有 JavaScript 回退，再次运行 `install.cjs` 无法放置从未下载的二进制文件。

1060* **安装脚本被禁用。** `--ignore-scripts` 和某些 pnpm 配置跳过 postinstall 步骤但仍然下载平台包。运行 `node node_modules/@anthropic-ai/claude-code/install.cjs`，如消息所示，或不使用该标志重新安装。如果 postinstall 在您的环境中根本无法运行，`node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs` 找到下载的包并启动它，代价是每次启动时额外的 Node 进程。如果包装器改为打印 `Could not find native binary package`，平台包从未被下载，因此首先修复上面的可选依赖项原因。1061* **安装脚本被禁用。** `--ignore-scripts` 和某些 pnpm 配置跳过 postinstall 步骤但仍然下载平台包。运行 `node node_modules/@anthropic-ai/claude-code/install.cjs`，如消息所示，或不使用该标志重新安装。如果 postinstall 在您的环境中根本无法运行，`node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs` 找到下载的包并启动它，代价是每次启动时额外的 Node 进程。如果包装器改为打印 `Could not find native binary package`，平台包从未被下载，因此首先修复上面的可选依赖项原因。

1061* **不支持的平台。** 为 `darwin-arm64`、`darwin-x64`、`linux-x64`、`linux-arm64`、`linux-x64-musl`、`linux-arm64-musl`、`win32-x64` 和 `win32-arm64` 发布预构建二进制文件。Claude Code 不为其他平台提供二进制文件；请参阅[系统要求](https://code.claude.com/docs/zh-CN/setup.md#system-requirements)。在 FreeBSD 上，安装程序将平台报告为不支持。在 v2.1.205 之前，它将 FreeBSD 视为 Linux 并下载了无法运行的二进制文件。1062* **不支持的平台。** 为 `darwin-arm64`、`darwin-x64`、`linux-x64`、`linux-arm64`、`linux-x64-musl`、`linux-arm64-musl`、`win32-x64` 和 `win32-arm64` 发布预构建二进制文件。Claude Code 不为其他平台提供二进制文件；请参阅[系统要求](https://code.claude.com/docs/zh-CN/setup.md#system-requirements)。在 FreeBSD 上，安装程序将平台报告为不支持。在 v2.1.205 之前，它将 FreeBSD 视为 Linux 并下载了无法运行的二进制文件。

1062* **公司 npm 镜像缺少平台包。** 确保您的注册表除了元包外还镜像所有八个 `@anthropic-ai/claude-code-*` 平台包。1063* **公司 npm 镜像缺少平台包。** 确保您的注册表除了元包外还镜像所有八个 `@anthropic-ai/claude-code-*` 平台包。

1063 1064 

1065#### 修复 npm 12 安装

1066 

1067如果 `claude` 在 npm 安装或更新后打印 `Error: claude native binary not installed.`，或者在 Windows 上 shell 无法运行它，请运行 `npm --version`。以 `12` 开头的版本意味着，除非您的 npm 配置允许，否则 npm 跳过了 Claude Code 的 postinstall 步骤，而该步骤负责将二进制文件放置到位。对于任何其他版本，请检查[其他原因](#native-binary-not-found-after-npm-install)。

1068 

1069要修复 npm 12 安装，请切换到本机安装程序或允许该步骤：

1070 

1071* **切换到本机安装程序**：[使用本机安装程序安装](https://code.claude.com/docs/zh-CN/setup.md#install-claude-code)，然后[卸载 npm 包](https://code.claude.com/docs/zh-CN/setup.md#uninstall-with-npm)。之后更新不再使用 npm，因此该错误不会再出现。

1072* **继续使用 npm**：对于全局 npm 安装，请将 Claude Code 添加到用户 npm 配置中的 `allow-scripts`。之后 npm 会在以后的每次安装和更新中运行 Claude Code 的安装脚本，在 `package.json` 未设置 `allowScripts` 的项目安装中也是如此。

1073 

1074 对于 `~/.claude/local` 中的本地安装，请使用本机安装程序。如果您的 `package.json` 脚本调用 `npm install`，并且您使用 pnpm 9、pnpm 10、Yarn 1 或其他会将此设置传递给它们的工具运行这些脚本，也请使用本机安装程序。在 npm 12.1 及更高版本上，一旦保存该设置，这些安装可能会因 `EALLOWSCRIPTS` 而失败。

1075 

1076 1. 如果 `npm --version` 打印的是 12.0.x，请将 npm 更新到 12.1 或更高版本，例如使用 `npm install -g npm@latest`。在 12.0.x 上，一旦保存该设置，由 `npx` 工具或 `npm run` 脚本启动的项目安装可能会因 `EALLOWSCRIPTS` 而失败。

1077 

1078 2. 运行 `npm config get allow-scripts` 并记下它列出的所有包，因为下一条命令会替换整个值。保存设置时将这些包放在引号内，例如 `"allow-scripts=@anthropic-ai/claude-code,<package>"`：

1079 

1080 ```bash theme={null}

1081 npm config set "allow-scripts=@anthropic-ai/claude-code" --location=user

1082 ```

1083 

1084 3. 重新安装：

1085 

1086 ```bash theme={null}

1087 npm install -g @anthropic-ai/claude-code

1088 ```

1089 

1090 如果此命令或第 1 步因 `EACCES` 失败，请切换到本机安装程序，而不是使用 `sudo` 重新运行。Claude Code 在自我更新时不使用 `sudo` 运行 npm，因此自动更新也会以同样的方式失败。

1091 

1092 4. 如果 `claude --version` 没有打印版本号，请检查[其他原因](#native-binary-not-found-after-npm-install)。

1093 

1094 要撤销，请在不包含 `@anthropic-ai/claude-code` 的情况下重新设置该列表，或使用 `npm config delete allow-scripts --location=user` 删除整个列表。在 npm 12 上，该错误会在您下次更新后再次出现。

1095 

1064### npm `ENOTEMPTY` 更新或重新安装期间的错误1096### npm `ENOTEMPTY` 更新或重新安装期间的错误

1065 1097 

1066当您在现有安装上运行 `npm install -g @anthropic-ai/claude-code` 时，npm 在移动旧包目录时可能会失败：1098当您在现有安装上运行 `npm install -g @anthropic-ai/claude-code` 时，npm 在移动旧包目录时可能会失败：

1094Remove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"1126Remove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"

1095```1127```

1096 1128 

1097然后重新安装：1129然后重新安装。在 npm 12 上，请按照[修复 npm 12 安装](#fix-an-npm-12-install)操作。否则，请运行：

1098 1130 

1099```bash theme={null}1131```bash theme={null}

1100npm install -g @anthropic-ai/claude-code1132npm install -g @anthropic-ai/claude-code

133 133 

134## 跟踪正在运行的审查134## 跟踪正在运行的审查

135 135 

136审查通常需要 15 到 25 分钟。审查作为后台任务运行，因此您可以继续在会话中工作或启动其他命令。如果您选择了[将发现发布到拉取请求](#post-findings-to-the-pull-request)，请保持会话打开直到审查完成；如果会话先结束，Claude Code 将不会发布任何内容。136审查通常需要 5 到 15 分钟。审查作为后台任务运行，因此您可以继续在会话中工作或启动其他命令。如果您选择了[将发现发布到拉取请求](#post-findings-to-the-pull-request)，请保持会话打开直到审查完成；如果会话先结束，Claude Code 将不会发布任何内容。

137 137 

138使用 `/tasks` 查看正在运行和已完成的审查、打开审查的详细视图或停止正在进行的审查。如果您停止审查，Claude Code 会存档云会话，不会返回部分发现。138使用 `/tasks` 查看正在运行和已完成的审查、打开审查的详细视图或停止正在进行的审查。如果您停止审查，Claude Code 会存档云会话，不会返回部分发现。

139 139 

211| 目标 | 您的工作差异、pull request、分支或路径 | 您的工作差异或 pull request |211| 目标 | 您的工作差异、pull request、分支或路径 | 您的工作差异或 pull request |

212| 运行位置 | 在您的会话中本地运行 | 在云沙箱中运行 |212| 运行位置 | 在您的会话中本地运行 | 在云沙箱中运行 |

213| 深度 | 随着 effort 参数扩展 | 具有独立验证的多代理队列 |213| 深度 | 随着 effort 参数扩展 | 具有独立验证的多代理队列 |

214| 持续时间 | 几秒到几分钟 | 大约 15 到 25 分钟 |214| 持续时间 | 几秒到几分钟 | 大约 5 到 15 分钟 |

215| 成本 | 计入正常使用量 | 免费运行，然后大约 \$5 到 \$25 每次审查作为使用额度 |215| 成本 | 计入正常使用量 | 免费运行，然后大约 \$5 到 \$25 每次审查作为使用额度 |

216| 最适合 | 迭代时的快速反馈 | 合并前对重大更改的信心 |216| 最适合 | 迭代时的快速反馈 | 合并前对重大更改的信心 |

217 217