通常,Claude Code 会直接请求每一次工具调用,读取结果后再决定下一步。Code Mode 于 2026 年 11 月 12 日在 2.1.323 版本 中加入,它让 Claude 编写一小段 JavaScript,在一步之内完成多次工具调用。本指南将介绍如何开启它、在真实任务中试用、阅读 Claude 写的代码,以及如何再次关闭。
截至 2026 年 11 月 15 日,Code Mode 仍处于实验阶段,默认关闭。Anthropic 的文档称,它可能在任何版本中更改或被移除。
Code Mode 能做什么
在普通会话中,Claude 会直接请求 Bash、Read 或 Edit 等工具,并在下一步之前读取每个结果。在 Code Mode 会话中,你仍然用自然语言输入提示,但 Claude 会编写 JavaScript 来完成任务。一段代码可以并行运行命令,把一个结果传给下一次调用,并只返回 Claude 需要读取的那部分输出。
Anthropic 的 Code Mode 文档 给出了这个例子:当被要求提高重试上限时,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。
文档建议在需要大量相关工具调用的任务中试用:
- 在许多文件中重复进行的同一处修改;
- 结果需要先过滤再交给 Claude 阅读的搜索;
- 可以同时运行的多个独立命令。
先了解限制
Code Mode 有实实在在的取舍。开启之前,先确认你能接受这些:
- 恢复会话:Code Mode 会话只能在终端中恢复,并且需要开启 Code Mode。
- 长时间运行的代码:除非代码可以在后台运行(见第 6 步),否则你需要等待,而且十分钟后它会停止。
- 缺少的功能:Remote Control、Claude in Chrome 和 computer use 在 Code Mode 会话中无法使用,你也不能把会话转到 Desktop 应用。
你需要准备什么
- Claude Code v2.1.323 或更高版本,使用原生版本(native build)安装。
- Claude 订阅或 Claude Console 账户。Code Mode 无法通过网关、Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform 或 Microsoft Foundry 使用。
- 以下模型之一:Claude Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 5.2。
- 在终端中运行的交互式
claude会话。它不支持-p、Agent SDK、VS Code 面板、Desktop 应用或云端会话。 - 在 Windows 上,需要安装 Git for Windows。
- 所在组织没有使用 HIPAA 配置或零数据保留(zero data retention)。
第 1 步:检查版本
claude --version
如果版本号低于 2.1.323,请更新:
claude update
如果你使用的是 stable 发布渠道,而更新还没有到 2.1.323,文档建议等待 stable 跟上,或切换到 latest。
第 2 步:开启 Code Mode 启动 Claude Code
Code Mode 由一个环境变量控制:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE。如果只想试一次,可以只在单次启动时设置这个变量。
macOS、Linux 或 WSL:
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude
Windows PowerShell:
$env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1"
claude
如果想在每个新会话中都开启,请在用户设置文件 ~/.claude/settings.json 中添加一个 env 块:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
}
}
Claude Code 会忽略项目设置文件中的这个变量,因此你克隆的仓库无法替你开启 Code Mode。
第 3 步:确认提示
在你的第一次 Code Mode 会话之前,Claude Code 会要求你确认。选择 Yes, turn on Code Mode(是,开启 Code Mode)。Claude Code 会重启,并在会话顶部附近显示这一行:
Code Mode (experimental) is on · this session can be resumed only with Code Mode on
如果你看到的是另一行,或者什么都没有,请跳到下面的错误部分。
第 4 步:给 Claude 一个需要大量工具调用的任务
在一个你熟悉的项目中,试试文档里的提示:
Read every Markdown file in this project and list the links that point to local files that don't exist.
另一个符合这种模式的提示:
Run the linter, the type checker and the unit tests at the same time, then summarize only the failures.
预期结果:Claude 像往常一样回答,你能看到它进行的工具调用。
第 5 步:阅读 Claude 写的代码
按 Ctrl+O 打开对话记录查看器。每段代码都显示为一行折叠的 Code。展开一行即可看到工具调用背后的 JavaScript,然后再按一次 Ctrl+O 返回对话。
第 6 步:处理权限和长时间任务
你现有的安全设置仍然有效。代码发起的每次工具调用都会经过你的 deny 和 ask 权限规则以及 PreToolUse hooks,你也不需要为 Bash 这样的工具修改任何规则。
变化在于代码的审查方式:
- 在 auto 模式下,分类器会在每段代码运行前对其进行审查,而不是审查每次工具调用。它看不到代码运行过程中算出的值,比如从搜索结果中取得的路径。凡是你必须掌控的内容,请保留规则或 hooks。
- 在其他权限模式下,代码会不经审查直接启动,凡是平时会弹出提示的工具调用,你都会收到提示。
对于耗时较长的构建或测试,Claude 要么等待代码运行,十分钟后停止;要么让它在后台继续运行,最长可达两小时,期间你可以继续对话。后台代码需要以 auto 模式或 bypassPermissions 模式启动的会话。如果你可以使用 auto 模式,文档给出了这样重新启动进入该模式的方法:
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude --continue --permission-mode auto
如果想用自己的脚本检查代码本身,可以编写一个匹配 REPL(运行 Claude 代码的工具)的 PreToolUse hook,并从 tool_input.code 读取 JavaScript。
第 7 步:恢复会话,或将其关闭
如果以后想回到某个 Code Mode 会话,恢复时请保持该变量处于设置状态:
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude --continue
如果 Code Mode 已关闭,Claude Code 会拒绝恢复该会话。未开启 Code Mode 时启动的会话,即使设置了变量,恢复后也不会开启它。
要关闭 Code Mode,请从 shell 和 ~/.claude/settings.json 中删除 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE,然后启动新会话。你也可以把它的值设为 0。只要有一处为 0,即使另一处为 1,Code Mode 也会保持关闭。
管理员可以在托管设置(managed settings)中放入相同的 env 块并将值设为 "0",从而为整个组织禁用它。托管设置只能禁用 Code Mode,不能为用户开启它。
常见错误及解决方法
如果会话以 Code Mode (experimental) isn't available 开头,原因会显示在同一行,/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 | 使用受支持的模型启动,例如 claude --model opus |
it needs settings that Claude Code downloads from Anthropic | 取消设置会关闭功能开关(feature flag)获取的变量,例如 DISABLE_TELEMETRY |
your organization's settings don't allow it | 向管理员询问相关托管设置 |
其他问题:
- 完全没有关于 Code Mode 的提示行:检查版本,确认 shell 或用户设置中的变量为
1,并删除所有0。 - 出现带倒计时的权限提示:在 auto 模式下,如果之前的代码仍在运行时 Claude 又启动了新代码,系统可能会就之前代码剩余的调用询问你。请在倒计时结束前回答,否则该调用会被拒绝。
- Claude 报告工具调用被拒绝:某个
PreToolUsehook 失败或超时。修复该 hook 或提高它的timeout。
总结
如果你的会话中有大量重复的搜索、编辑和测试运行,Code Mode 值得一试。用环境变量为单个会话开启它,交给它一个多步骤任务,再用 Ctrl+O 阅读代码。在实验阶段,它还会不断变化。
如果你正在完善自己的 Claude Code 配置,我们关于 Claude Code 中的 agent skills 和 用 Chrome DevTools MCP 给你的智能体配一个真正的浏览器 的指南值得接着读。
资料来源
链接最后检查于 2026 年 11 月 15 日。





写评论