SpyBara
Go Premium

code-mode.md 2026-11-12 23:02 UTC to 2026-11-13 23:02 UTC

This page contains 224 additions and 0 deletions.

2026
Fri 13 23:02

使用 Code Mode 通过代码运行工具调用

试用 Code Mode，这是一项实验性功能，Claude 会在其中编写 JavaScript，在一个步骤中进行多次工具调用。

Code Mode 改变了 Claude 使用其工具的方式。不使用 Code Mode 时，Claude 会直接请求 Bash、Read 或 Edit 等工具调用，并在决定下一步操作之前读取每个结果。使用 Code Mode 时，Claude 会编写一段 JavaScript 来进行这些工具调用，然后由 Claude Code 在您的会话中运行这段代码。

[!NOTE]

Code Mode 是一项实验性功能，默认处于关闭状态。它可能会在任何版本中发生变化或被移除。如需分享反馈，请运行 /feedback。

Code Mode 的工作原理

在 Code Mode 会话中，您仍然通过提示词描述任务，Claude 会编写 JavaScript 来执行该任务。一段代码可以并行运行命令、在下一次调用中使用上一次的结果，并返回 Claude 需要读取的那部分输出。

例如，如果您让 Claude 提高重试次数上限，Claude 可能会编写以下代码来查找文件、编辑文件并运行测试。最后一行将文件路径和测试输出返回给 Claude：

const files = await $`rg -l "function retryPolicy" src`.text();
const target = files.trim().split("\n")[0];
await edit(target, "maxAttempts: 3", "maxAttempts: 5");
({ edited: target, tests: $`npm test -- retryPolicy`.nothrow() });

在对话中，您看到的是工具调用（例如编辑的 diff），而不是代码。要阅读代码，请按 Ctrl+O 打开会话记录查看器。每段代码在其中显示为一个折叠的 Code 行，并附有如何展开的提示。

何时使用 Code Mode

对于需要大量相关工具调用的任务，可以尝试使用 Code Mode，例如：

  • 需要在许多文件中重复进行的更改
  • 需要在 Claude 读取之前先过滤结果的搜索
  • 可以同时运行的多个独立命令

Code Mode 的限制

在启用 Code Mode 之前，请确认您可以接受以下限制：

要求

  • 版本：Claude Code v2.1.323 或更高版本，任一发布频道均可。旧版本会在不启用 Code Mode 的情况下启动，可能附带也可能不附带原因 it isn't open to your account yet
  • 账户：Claude 订阅或 Console 账户。无法通过网关、Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 使用 Code Mode
  • 组织：您的组织未使用 HIPAA 配置或零数据保留
  • 模型：Claude Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 5.2
  • 使用入口：终端中的交互式 claude 会话。Code Mode 不适用于 -p、Agent SDK、VS Code 面板、Desktop 应用或云端会话
  • 安装：Claude Code 的原生构建版本
  • Windows：已安装 Git for Windows

此外，在某些设置开启时也无法启动 Code Mode，例如 API 密钥助手、agent team、OpenTelemetry 导出或 DISABLE_TELEMETRY。有关每种情况的解决方法，请参阅 Code Mode 无法启动。

试用 Code Mode

启用 Code Mode，给 Claude 一个任务，然后查看 Claude 编写的代码。

1. 检查您的版本

运行 claude --version。如果版本低于 v2.1.323，请运行 claude update。如果您使用的是 stable 频道，且更新后未达到 v2.1.323，请等待 stable 跟进，或切换到 latest。

2. 在开启 Code Mode 的情况下启动 Claude Code

将 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE 环境变量设置为 1。如需试用 Code Mode，请在 shell 中设置它。如需为每个新会话启用 Code Mode，请在用户设置中设置它。

[tab] macOS, Linux, WSL

CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude

[tab] Windows PowerShell

$env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1"
claude

[tab] settings.json

将此 env 块保存到 ~/.claude/settings.json 中，然后启动 claude：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
  }
}

Claude Code 会忽略项目设置文件中的此变量，因此您克隆的仓库无法替您启用 Code Mode。

3. 确认您要使用 Code Mode

在您的第一个 Code Mode 会话之前，Claude Code 会要求您确认。选择 Yes, turn on Code Mode。Claude Code 会重新启动，并在会话顶部附近显示以下这行内容：

Code Mode (experimental) is on · this session can be resumed only with Code Mode on

如果您看到的是其他内容或没有看到这行内容，请参阅 Code Mode 无法启动。

4. 给 Claude 一个需要大量工具调用的任务

在您熟悉的项目中，发送如下提示词：

Read every Markdown file in this project and list the links that point to local files that don't exist.

5. 阅读 Claude 编写的代码

按 Ctrl+O 并展开一个 Code 行，查看工具调用背后的 JavaScript。再次按 Ctrl+O 返回对话。

[!WARNING]

如需稍后恢复 Code Mode 会话，请在运行 claude --continue 或 claude --resume 时保持 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE 设置为 1。如果 Code Mode 处于关闭状态，Claude Code 会拒绝恢复该会话。在未启用 Code Mode 的情况下启动的会话，即使设置了该变量，也会在不启用 Code Mode 的情况下恢复。

关闭 Code Mode

从 shell 和 ~/.claude/settings.json 中移除 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE，然后启动新会话。您也可以保留该变量，并在任一位置将其值改为 0。只要其中一处为 0，即使另一处设置为 1，Code Mode 也会保持关闭。

为您的组织禁用 Code Mode

将值为 0 的 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE 添加到您的托管设置中，这样您组织中的任何人都无法使用 Code Mode：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "0"
  }
}

正处于 Code Mode 会话中的用户会继续留在该会话中，直到他们退出或重新启动 Claude Code。此后，用户将在不启用 Code Mode 的情况下启动，并且在 0 生效期间无法恢复其 Code Mode 会话。您无法通过托管设置为用户启用 Code Mode。

权限与长时间运行的代码

您的权限模式决定了 Claude 的代码如何被检查，以及代码运行期间您能否与 Claude 交谈。

权限检查

Claude 的代码进行的每个工具调用都会经过您的 deny 和 ask 权限规则以及您的 PreToolUse hook。您无需为 Bash 等工具更改规则或匹配器。除了规则和 hook 之外，在自动模式下，分类器会审查代码；在会进行询问的模式下，您需要回复提示：

如需检查代码本身，请编写一个匹配 REPL（运行 Claude 代码的工具）的 PreToolUse hook，并从 tool_input.code 中读取 JavaScript。

[!WARNING]

Bash 规则匹配的是命令文本，因此无论是否使用 Code Mode，Claude 都可以以规则不匹配的形式运行被拒绝的命令。如需不依赖命令文本的限制，请参阅沙箱隔离。

长时间运行的代码

当代码运行耗时较长的构建或测试时，Claude 要么等待它完成，要么让它在后台继续运行：

  • 等待：Claude 在代码完成后才回复，代码会在十分钟后停止，这包括您在权限提示上花费的时间
  • 后台：您可以继续与 Claude 交谈，代码最多可以运行两个小时

如需在后台运行代码，请以自动模式或 bypassPermissions 模式启动会话。如果 Claude 仍然在等待，请检查您当前的模式以及启动会话的方式：

  • 您切换到了其他模式：按 Shift+Tab，直到回到您启动时所用的模式
  • 您以其他模式启动，或从 claude --resume 列表中选择了该会话：如果您可以使用自动模式，请退出，然后在 Code Mode 开启的情况下运行 claude --continue --permission-mode auto
  • 您向 --tools 传递了工具名称：以自动模式重新启动，不使用该标志

故障排除

Code Mode 无法启动

会话顶部附近出现 Code Mode (experimental) isn't available 表示 Claude Code 在未启用 Code Mode 的情况下启动。原因显示在同一行中，/status 也会显示该原因。在下表中找到对应原因，进行相应更改，然后启动新会话。如果原因未在表中列出，请检查要求。

原因包含 解决方法
it isn't open to your account yet 如果您的版本低于 v2.1.323，请更新。否则，请检查网络连接并重新启动。如果该原因仍然存在，请改日再试
it only works with the Anthropic API 移除通过云提供商、网关或自定义 ANTHROPIC_BASE_URL 路由请求的设置
it doesn't work with an API key helper 移除 apiKeyHelper、ANTHROPIC_AUTH_TOKEN，以及 ANTHROPIC_CUSTOM_HEADERS 中的任何 Authorization 或 X-Api-Key 标头。然后登录或设置 ANTHROPIC_API_KEY
it only works with Opus 5.5, Sonnet 5.5 and later models 使用受支持的模型启动，例如使用 --model opus。Haiku 5.5 和 Fable 5.2 也可以使用
it doesn't work in background jobs 在前台启动，不使用 --remote-control
it needs settings that Claude Code downloads from Anthropic 取消设置关闭功能标志获取的变量，例如 DISABLE_TELEMETRY
OpenTelemetry is on 如果您不需要 OpenTelemetry 导出，请取消设置 CLAUDE_CODE_ENABLE_TELEMETRY 和 ENABLE_BETA_TRACING_DETAILED
it doesn't yet work with an installed mod 关闭检查工具调用的 mod
it can't be used together with agent teams yet 取消设置 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
this launch's tool options 不使用 --restricted 启动，将 REPL 添加到 --tools，并从 --disallowedTools 和您的 deny 规则中移除 REPL
couldn't save your answer 使 ~/.claude.json 可写
your organization's settings don't allow it 向您的管理员咨询相关托管设置

如果您没有看到任何关于 Code Mode 的行，请运行 claude --version。如果您的版本低于 v2.1.323，请进行更新。然后检查 shell 或用户设置中的 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE 是否为 1，并从这些位置以及任何 --settings 文件中移除所有 0。

带倒计时的权限提示

在自动模式下，如果先前的代码仍在运行时 Claude 又启动了新代码，先前的代码将失去分类器审查。随后，Claude Code 会就先前代码中剩余的、需要审查的调用询问您。在未连接 IDE 的情况下，提示会显示倒计时：

Claude Code will automatically block this request in 1:59, to avoid holding up an unattended session

请在倒计时结束前作答。否则该调用将被拒绝，并且之后本应显示倒计时的调用将在不提示的情况下被拒绝。如需再次看到这些提示，请向 Claude 发送一条消息。

工具调用被 hook 拒绝

如果 Claude 报告工具调用被拒绝，请让它提供错误文本。以下错误表示 PreToolUse hook 未给出决定，即使未设置 onFailure，这也会拒绝该调用：

  • the hook failed：对于来自 Claude 代码的调用，您的 hook 无法启动、被终止、以 126、127 或大于 128 的代码退出，或者返回了 HTTP 错误或无效输出。请修复该 hook
  • the hook did not finish：您的 hook 在处理来自 Claude 代码的调用时超时，或者在 Claude 已在会话中运行过代码后，在处理任何其他工具调用时超时。请增大该 hook 的 timeout

如需在 command 或 http hook 失败或超时时允许调用继续进行，请在该 hook 上设置 "onFailure": "continue"。如果 command hook 以 1 等普通代码退出，调用会继续进行，除非您设置了 "onFailure": "block"。

代码输出被 hook 拦截

如果在您预期看到 Claude 代码输出的地方，Claude 报告了某个 hook 的阻止原因，请检查您的 UserPromptSubmit hook。当代码可以在后台运行时，该事件上的 command、http 和 mcp_tool hook 也会在代码输出上运行。如需让输出通过，请修改该 hook，使其在输入中的 source 为 poll_event 时不进行阻止。

相关资源