Claude不再逐个调用工具:写一段JS并行跑
用 Code Mode 从代码中运行工具调用
Code Mode 改变了 Claude 使用工具的方式。没有 Code Mode 时,Claude 直接请求 Bash、Read、Edit 等工具调用,并在每次调用后读取结果,再决定下一步做什么。开启 Code Mode 后,Claude 会写一段 JavaScript 来发起工具调用,由 Claude Code 在你的会话中运行这段代码。
Code Mode 如何工作
在 Code Mode 会话中,你仍然用提示词描述任务,Claude 编写 JavaScript 来执行它。同一段代码可以并行运行命令、把一次调用的结果用于下一次调用,并只返回 Claude 需要读取的那部分输出。
例如,你让 Claude 调高重试上限,Claude 可能写一段代码来找到文件、编辑它并运行测试。最后一行把文件路径和测试输出返回给 Claude。
在对话中,你看到的是工具调用(例如编辑的 diff),而不是代码。要读代码,按 Ctrl+O 打开转录查看器。每段代码在那里显示为折叠的 Code 行,并附有展开提示。
何时使用 Code Mode
适合需要大量相关工具调用的任务,例如:
- 同一处改动要在许多文件中重复
- 搜索结果需要先过滤,再由 Claude 读取
- 多条彼此独立、可以同时运行的命令
Code Mode 的限制
开启 Code Mode 前,先确认你能接受这些限制:
- 恢复会话:只能在终端中恢复 Code Mode 会话,并且 Code Mode 必须处于开启状态
- 自动模式:auto 模式的分类器审查的是代码,而不是每一次工具调用
- 长时间运行的代码:除非代码能在后台运行,否则你需要等它结束,而且它会在十分钟后停止
- Hooks:当 PreToolUse hook 没有完成(例如超时)时,你会看到工具调用被拒绝
- 不可用功能:不能使用 Remote Control、Claude in Chrome 或 computer use
- 移动会话:不能把会话移到 Desktop 应用,或把它变成后台会话,/fork 也不能启动后台副本
环境要求
- 版本:Claude Code v2.1.323 或更高版本,任一发布通道均可。较旧版本启动时不会带 Code Mode,无论是否提示原因
- 账户:Claude 订阅账户或 Console 账户。不能通过网关、Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry 或 Claude Models on Google Cloud(Anthropic managed)使用 Code Mode
- 组织:你所在组织没有使用 HIPAA 配置或零数据保留
- 模型:Claude Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 5.2
- 运行环境:终端中的交互式 claude 会话。Code Mode 不适用于 VS Code 面板、Desktop 应用或云端会话
- 代理团队:要在开启代理团队的情况下使用 Code Mode,需要 v2.1.326 或更高版本。队友在默认的进程内显示模式下运行 Code Mode,在分屏模式下启动时则不带 Code Mode
- 安装方式:Claude Code 的原生构建
- Windows:已安装 Git for Windows
另外,某些设置开启时也无法启动 Code Mode,例如 API key helper、OpenTelemetry 导出或 DISABLE_TELEMETRY。各自的修复方法见下文“Code Mode 无法启动”。
试用 Code Mode
1. 开启 Code Mode。在 shell 或 ~/.claude/settings.json 中把 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE 设为 1,然后新开一个会话。
2. 给 Claude 一个任务。
3. 查看 Claude 写的代码。
关闭 Code Mode
从 shell 和 ~/.claude/settings.json 中移除 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE,然后新开会话。也可以保留这个变量,把两处的值改为 0。只要有一处为 0,即使另一处设为 1,Code Mode 也会保持关闭。
为组织禁用 Code Mode
在 managed settings 中加入值为 0 的 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE,组织内任何人都无法使用 Code Mode:
已经在 Code Mode 会话中的用户会一直留在其中,直到退出或重启 Claude Code。之后用户启动时不会带 Code Mode,而且在 0 生效期间无法恢复 Code Mode 会话。你不能通过 managed settings 为用户开启 Code Mode。
权限与长时间运行的代码
你的权限模式决定 Claude 写的代码如何被检查,以及代码运行时你能否与 Claude 对话。
权限检查
在 auto 和 bypassPermissions 模式下,代码可以全程运行而无需权限提示。有些调用仍会提示你,例如任何模式都不会自动批准的操作。
代码中的每个工具调用都会以该工具的常规名称(例如 Bash 或某个 MCP 工具名)经过你的 deny 和 ask 权限规则以及 PreToolUse hook。除规则和 hook 外,auto 模式下分类器还会审查代码;在会询问的模式下,由你回答提示:
- Auto 模式:分类器在每段代码运行前审查代码整体,而不是逐个工具调用。它看不到运行时计算出的值,例如从搜索输出中得到的路径,所以对必须控制的调用,保留规则或 hook。有些调用仍可能提示你,例如你在分类器多次拦截后自行批准的代码中的调用
- 其他权限模式:凡是在该模式下会提示你的工具调用,都会逐个提示
如果你的 PreToolUse hook 负责允许或阻止 shell 命令,要让它像 Bash 规则那样检查命令的每一部分。在 Code Mode 下,名为 app 的文件夹中的 git push 可能以 cd 'app' && git push 的形式到达你的 hook。
要检查代码本身,写一个匹配 REPL(运行代码的工具)的 PreToolUse hook,从 tool_input.code 读取 JavaScript。要检查代码返回什么,见下文“用 hook 检查代码输出”。
为某条命令要求审批
要在 auto 或 bypassPermissions 模式下看到某条特定命令的提示,为它添加一条 ask 规则。规则匹配到的命令形式会提示你。要以 git push 开头的命令收到提示,在 ~/.claude/settings.json 中为这类命令保存一条 ask 规则。
测试规则:在 auto 模式下、在一个没有 remote 的仓库里新开会话,让 Claude 运行 git push origin main。你会看到针对该命令的提示。
先审批每一段代码
要在代码运行前阅读并批准它,为 REPL(运行代码的工具)添加一条 ask 规则。把这条规则保存到 ~/.claude/settings.json。
测试规则:新开一个会话,给 Claude 一个任务。你会看到一个不含代码的提示。回答前想读代码,按 Ctrl+O,展开 Code 行,再按 Ctrl+O 返回。从主对话中,该视图看不到子代理的代码。
如果你在 auto 模式批准,即使分类器本会阻止,代码也会启动,其项目编辑和只读命令无需提示即可运行。如果 Claude 报告代码无法启动子代理,移除该规则。
代码运行时回答权限提示
要在代码的某个工具调用提示处停下代码,回答 No 且不带评论。以下结果适用于未标记为来自子代理的提示:
- No 或 Esc:代码停止,已经完成的调用所做的更改保留
- No 并带评论:该调用被拒绝,代码可以继续执行其他调用
用沙箱限制 shell 命令
你的沙箱设置适用于代码运行的 shell 命令。JavaScript 本身及其文件、web 和 MCP 工具调用在沙箱之外运行。要连 JavaScript 和这些调用一起隔离,把 Claude Code 运行在容器或虚拟机中。
当代码请求以非沙箱方式运行命令时,要让命令仍留在沙箱内,开启严格沙箱模式。在 auto 模式下,分类器审查发起请求的代码,命令本身没有单独审查。
长时间运行的代码
代码运行耗时的构建或测试时,Claude 要么等待,要么让它在后台继续:
- 等待:Claude 在代码结束后回答,代码十分钟后停止。在 Manual 和 acceptEdits 模式下,你花在工具权限提示上的时间不计入这十分钟。v2.1.328 之前,这段时间计入
- 后台:你可以继续与 Claude 对话,代码最多运行两小时
对后台代码,以 auto 或 bypassPermissions 模式启动会话。如果 Claude 仍在等待,检查当前模式和会话的启动方式:
- 你切换到了其他模式:按 Shift+Tab,直到回到启动时的模式
- 你以其他模式启动:如果 auto 模式对你可用,退出,然后在 Code Mode 开启的情况下运行 claude --continue --permission-mode auto
- 你用的是 v2.1.328 之前的版本,并且从 claude --resume 列表里选择了会话:退出、更新 Claude Code,然后在 Code Mode 开启的情况下运行同样的 claude --resume 命令。要留在当前版本,把 --resume 换成 --continue
- 你给 --tools 传了工具名:不带该标志,以 auto 模式重新启动
停止运行中的代码
要在 Claude 正在响应或正在等待代码时停止代码,按 Esc。要在 Claude 结束响应后停止后台代码,在会话中运行 /tasks,选中正在运行的任务,按 x。
停止代码后,用 /tasks 检查代码启动且仍在运行的子代理、shell 命令和 MCP 调用。要停止其中一个,选中它并按 x。
用 hook 检查代码输出
要在 Claude 读取前检查或脱敏代码返回的内容,写一个匹配 REPL(运行代码的工具)的 PostToolUse hook。后台代码结束以及代码抛出错误时,同一个 hook 也会运行。
在 hook 中读取代码输出
在 PostToolUse hook 中,从 tool_response 读取输出,它包含这些字段:code、stdout、stderr、error、result。
脱敏代码输出
要隐藏部分输出,返回修改过的 tool_response 副本作为 updatedToolOutput,并按以下方式构建副本:
- 改文本:脱敏 result、stdout、stderr 和 error。处理 result 缺失或为 null 的情况,并注意只有代码失败或被停止时才会有 error
- 保持形状:code、stdout、stderr 返回字符串,error 返回字符串或省略。如果形状不对,Claude 拿到的是原始输出
- 移除图片和 PDF:如果副本中有要隐藏的图片或文档,把该字段设为 []
要隐藏 notes.txt 结果中的部署令牌,输出类似这样的 JSON(示例按上述字段要求构造):
{
"updatedToolOutput": {
"code": 0,
"stdout": "deploy token: [REDACTED]",
"stderr": "",
"result": "notes.txt: deploy token: [REDACTED]"
}
}
测试 hook:创建一个包含会被 hook 脱敏的值的文件,然后启动 Code Mode 会话,让 Claude 读取并引用该文件。输入路径时不要带 @,检查 Claude 的回复是否显示你的替换文本。
hook 阻止或出错时也要脱敏
即使 hook 阻止调用或出错,也要返回修改过的 tool_response 副本作为 updatedToolOutput:
- hook 阻止:把脱敏副本与 "decision": "block" 放在同一个 JSON 中输出。没有副本,Claude 仍会读到原始输出
- hook 出错:捕获错误,输出一个在要脱敏的字段中带占位文本的副本。如果 hook 崩溃、超时或输出无效 JSON,Claude 拿到的是原始输出
把检查从 UserPromptSubmit hook 移走
如果你在 UserPromptSubmit hook 中检查代码输出,把该检查移到 PostToolUse hook。在 v2.1.328 及以后,UserPromptSubmit hook 不再接收代码输出,即使管理员在 managed settings 中设置了它们。
故障排查
Code Mode 无法启动
会话顶部附近出现 “Code Mode (experimental) isn't available”,表示 Claude Code 启动时没有 Code Mode。原因会显示在同一行后面,/status 也会显示。在下表中找到你的原因,做出相应更改,然后新开会话。原因不在表中时,检查上面的环境要求。
- 原因包含 “it isn't open to your account in this version” 或 “it isn't open to your account yet”:版本低于 v2.1.323 就更新。否则检查网络连接后重试。原因仍在,换一天再试
- 原因包含 “it only works directly with the Anthropic API” 或 “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 the plugin”:在会话中运行 /plugin,禁用原因中点名的每个插件。如果是组织开启的,请管理员关闭
- 原因包含 “it doesn't yet work with an installed mod”:关闭检查工具调用的 mod
- 原因包含 “it can't be used together with agent teams yet”:要保留代理团队,把 Claude Code 更新到 v2.1.326 或更高。要留在当前版本,取消 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”:向管理员询问相关 managed setting
如果完全看不到关于 Code Mode 的行,运行 claude --version。版本低于 v2.1.323 就更新。然后确认 shell 或用户设置中 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE 为 1,并从这些位置以及任何 --settings 文件中移除 0。
带倒计时的权限提示
在 auto 模式下,如果你在分类器多次拦截后自行批准代码,可能会被问及该代码中以及仍在运行的更早代码中的工具调用。在没有连接 IDE 时,提示可能显示倒计时:
在倒计时结束前回答。否则该调用被拒绝,之后本会显示倒计时的调用会被无提示直接拒绝。要重新看到提示,给 Claude 发一条消息。
在 v2.1.327 之前,Claude 启动新代码后,即使分类器允许新代码,你也可能被问及运行中代码的剩余调用。要减少这些提示,把 Claude Code 更新到 v2.1.327 或更高版本。
工具调用被 hook 拒绝
如果 Claude 报告工具调用被拒绝,向它要错误文本。以下错误表示你的 PreToolUse hook 没有给出决定:
- “the hook did not finish”:hook 超时,或 agent hook 未给出决定就结束。超时后提高 hook 的超时时间。对不给决定的 agent hook,把检查移到 command hook。这个错误可能出现在来自代码的调用上,也可能出现在 Claude 在会话中运行代码之后的其他工具调用上
- “the hook failed”:对来自代码的调用,hook 无法启动、被杀死、以 126、127 或大于 128 的退出码退出,或返回 HTTP 错误或无效输出。修复 hook。这个错误在 v2.1.329 之前可见,之后版本很少见:一个原因是会话中功能开关获取在 Claude 运行代码后关闭
在 v2.1.329 或更高版本上,除 “the hook did not finish” 之外的 hook 失败后,来自代码的调用默认会运行。要选择调用是否运行,使用 command 或 http hook 并在其上设置 onFailure:
- 超时或失败后停止调用:设置 "onFailure": "block"。用于守护调用的 hook
- 超时或失败后允许调用运行:设置 "onFailure": "continue"
代码输出被 hook 扣留
如果你预期代码有输出,却在 Claude 的回复中看到 “UserPromptSubmit operation blocked by hook”,说明你的 UserPromptSubmit hook 把输出当作提示接收并阻止了。如果 Claude 只报告 hook 的原因,让它引用收到的消息。
在 v2.1.328 及以后,UserPromptSubmit hook 不再接收代码输出。要在更早版本放行输出,更新 Claude Code 或修改 hook:
- 更新:如果依赖该 hook 检查代码输出,先把检查移到 PostToolUse hook,再把 Claude Code 更新到 v2.1.328 或更高
- 留在当前版本:修改 hook,使其在输入中 source 为 poll_event 时不阻止