Claude Code Code Mode 怎么开:36 条修复与 2 小时后台

一句话结论:Claude Code 的 Code Mode 从 2.1.323 版本开始提供,让模型用一段 JavaScript 代替逐个工具调用,一次跑完查找、编辑、测试这类多步操作,代价是只能在终端交互式会话里用,且从 2.1.323 到 2.1.328 这 5 个版本里官方为它改了 36 条。

传统工具调用模式下,模型要读一次文件就等一次结果,想清楚下一步再发起下一次调用。链条越长,来回等待占用的时间越多。Code Mode 换了一种做法,模型直接写一段 JavaScript,由 Claude Code 在你的会话里执行这段代码,代码自己串联起工具调用,只把需要的那部分结果交回给模型看。

Code Mode 的工作方式:一段代码顶掉多次调用

官方文档给了一个能说明问题的例子。任务是修改重试次数并跑测试,模型写出的代码先用一条命令找出定义该函数的文件,再取出第一行路径作为目标文件,调用编辑函数改掉数值,最后执行测试并把文件路径和测试输出组装成一个对象返回。

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()})

这段代码里有三段式的能力,解释了 Code Mode 存在的理由。一段代码可以并行发起多个命令,上一个调用算出的结果可以喂给下一个调用,返回值可以只保留模型真正需要读的那部分。前面两次查找与编辑属于工具调用,最后一行把测试结果包成结构化对象,这是普通工具调用模式下拿不到的。

界面上的差别也很实际。对话里显示的仍然是工具调用,比如那次编辑的 diff,而不是代码本身。要看代码得按 Ctrl+O 打开 transcript 视图,每段代码在那里是一个可展开的 Code 行。

适用场景可以概括成一句话,需要大量相关工具调用的活。官方列了三种典型情形,同一个改动要在很多文件里重复出现,搜索结果需要先过滤一遍再让模型读,以及几个互不依赖的命令可以同时跑。

怎么开启:四个步骤与一条环境变量

开启过程分成四步。第一步确认版本,跑 claude –version,低于 2.1.323 就先执行 claude update,如果用的是 stable 通道而更新还没跟上,可以等 stable 追平或者切到 latest 通道。

第二步设置环境变量 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE 的值为 1。想只试一次就写在自己的 shell 里,想每个新会话都生效就写进用户设置文件 ~/.claude/settings.json 的 env 块。这个变量有一个刻意的设计,Claude Code 会忽略项目级设置文件里的这个变量,所以你克隆下来的一个仓库无法替你打开 Code Mode。

第三步是确认。Claude Code 会在第一个 Code Mode 会话前问你一次,选 Yes, turn on Code Mode 之后会重启,并在会话顶部显示一行 Code Mode (experimental) is on · this session can be resumed only with Code Mode on。看到这行才算真正进入。

第四步是验证效果。在一个你熟悉的项目里发一个需要多次工具调用的任务,比如让模型读完项目里所有 Markdown 文件并列出指向不存在本地文件的链接,然后按 Ctrl+O 看它写了什么。

要关掉就把变量从 shell 和用户设置里删掉,或者把值改成 0。这两处只要有一处是 0,Code Mode 就是关闭的,哪怕另一处写了 1 也不生效。给整个组织禁用则在托管设置里把值设为 0,用户之后启动会话不会再进入 Code Mode,也无法恢复之前的 Code Mode 会话。

门槛与限制:六项硬条件

Code Mode 是实验特性,默认关闭,且可以随时被改掉或移除。它对运行环境的要求相当具体。

维度 要求
版本 Claude Code 2.1.323 或更高,stable 与 latest 两条通道都可以
账号 Claude 订阅或 Console 账号。不支持网关、Amazon Bedrock、Claude Platform on AWS、Google Cloud Agent Platform、Microsoft Foundry 以及 Anthropic 托管的 Claude Models on Google Cloud
模型 Claude Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 5.2
运行界面 终端里的交互式 claude 会话。不支持 -p、Agent SDK、VS Code 面板、桌面应用与云端会话
组织配置 组织不能启用 HIPAA 配置或零数据保留
Agent 协作 要配合 agent teams 使用需要 2.1.326 或更高版本,且队友只在默认的进程内显示模式下运行 Code Mode

除这六项之外还有一批功能在 Code Mode 下不可用,包括 Remote Control、Claude in Chrome 与 computer use,会话也不能转到桌面应用或变成后台会话,/fork 无法启动后台副本。Windows 用户还需要装好 Git for Windows。

还有一类限制来自设置本身。API key helper、OpenTelemetry 导出以及 DISABLE_TELEMETRY 这几项设置存在时,Code Mode 起不来,官方文档为每一种都给了对应的排查步骤。

权限怎么审:审的是代码,不是每一次调用

这一节是 Code Mode 与既有权限体系的差别所在,也是安全上最需要留意的地方。

在 auto 与 bypassPermissions 模式下,代码可以从头跑到尾不弹权限提示。但每一次工具调用依然要过 deny 与 ask 权限规则,以及 PreToolUse 钩子,走的还是工具的常规名字,比如 Bash 或者某个 MCP 工具名。

超出规则和钩子之外还有一道分类器。auto 模式下分类器审查的是每一整段代码,而不是代码里的每一次调用。这里有个关键差别,分类器看不到运行时才算出来的值,比如从搜索结果里取出的某个路径。所以真正需要控制的调用,仍然要靠规则或钩子兜底。

官方还提醒了钩子的写法差异。因为 Bash 规则是按命令文本匹配的,一段 git push 在名为 app 的目录里运行时,到达钩子的形态可能是 cd ‘app’ && git push。如果你的 PreToolUse 钩子负责放行或拦截 shell 命令,需要像 Bash 规则那样逐段检查,而不是只匹配开头。

想直接检查代码本身,就写一个匹配 REPL 的 PreToolUse 钩子。REPL 是执行这段代码的工具名,JavaScript 内容在 tool_input.code 字段里。想检查代码返回了什么,则用 PostToolUse 钩子读 tool_response,里面有 code、result、stdout、stderr 以及 toolsUsed 这些字段。需要遮蔽输出时返回 updatedToolOutput,官方文档给了把部署令牌替换成 REDACTED 的完整 JSON 例子。

钩子这条线有几个必须提前规划的边界。返回 updatedToolOutput 时即使钩子阻断了动作也要返回,否则 Claude 仍会读到原始输出;钩子崩溃、超时或输出非法 JSON 时,Claude 拿到的是原始输出;被拒绝的调用其输入不在这个钩子的遮蔽范围内,refusedCalls 字段会重复那段输入且内容不变。还有一条版本相关的差异,从 2.1.328 起 UserPromptSubmit 钩子不再接收代码输出,即使管理员在托管设置里开启也一样。

长任务的两种跑法:10 分钟与 2 小时

代码跑长构建或测试时,有两种跑法。

等待模式下 Claude 等代码跑完才回答,代码跑满 10 分钟会被停掉。在 Manual 与 acceptEdits 模式里,你停在权限提示上的时间不计入这 10 分钟,这个行为是 2.1.328 才改的,之前那段时间是计入的。

后台模式下你可以一边跟 Claude 说话一边让代码继续跑,最长 2 小时。要用后台模式,会话必须在 auto 或 bypassPermissions 模式下启动。如果发现 Claude 还是在等,按几种情况排查:中途切过模式就按 Shift+Tab 切回起始模式;起始模式不对就退出后用 claude –continue –permission-mode auto 恢复;版本早于 2.1.328 又从 –resume 列表里选的会话,先更新再重跑,或者把 –resume 换成 –continue;启动时用 –tools 传了工具名的话,去掉这个参数重新开始。

停止的路径有两条。Claude 正在回答或还在等代码时按 Esc。Claude 已经回答完但后台代码还在跑,就在会话里执行 /tasks,选中运行中的任务按 x。停掉之后记得再查一次 /tasks,代码可能已经启动了子智能体、shell 命令和 MCP 调用,这些也要单独停掉。

5 个版本 36 条修复:这个特性还在快速迭代

Code Mode 从 2.1.323 首发到 2.1.328,官方在 5 个版本里为它写了 36 条变更条目,其中 2.1.328 一个版本就占了 22 条。这个密度说明它还处在高频打磨期。

版本 Code Mode 相关条目 代表性改动
2.1.323 1 首发,提供实验性开关
2.1.325 3 修复 worktree 路径被写错、权限提示中的输入丢失、恢复会话后 Claude 自启动
2.1.326 7 支持与 agent teams 同时开启,权限检查更严,$ shell 助手对部分输入报错
2.1.327 3 auto 模式下新脚本不再打断旧脚本的权限流程,装了 mod 时不再拒绝启动
2.1.328 22 移除多数脚本后的 0.75 秒停顿,缩短工具描述省 token,后台与 MCP 连接修复

2.1.328 这 22 条集中在稳定性上。脚本因权限提示停留超过 10 分钟而被停的问题修了,auto 与 bypass 模式下脚本调不到中途连上的 MCP 服务器修了,resume 选择器里选的会话脚本不在后台跑修了,同时开多个脚本时技能、钩子上下文和审批备注丢失修了。有一段改动值得单独留意,Code Mode 从 2.1.328 起不再对脚本输出执行 UserPromptSubmit 钩子,官方给出的替代方案是用 PostToolUse 钩子的 updatedToolOutput 做脱敏。

还有一条效率改动是可量化的。2.1.328 移除了多数脚本之后的 0.75 秒停顿,同时把工具描述写得更短以降低 token 消耗,同时给带 MCP 服务器的新 Code Mode 会话做了提示缓存优化。这几项叠加起来的效果就是,Code Mode 在多次工具调用的场景里比早期版本少花时间也少花 token。

常见问题

Code Mode 怎么打开?

先确认版本在 2.1.323 以上,然后把 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE 设为 1,写在 shell 里或 ~/.claude/settings.json 的 env 块中。启动后选 Yes, turn on Code Mode,会话顶部出现 Code Mode (experimental) is on 这行才算成功。这个变量在项目级设置文件里不生效。

什么任务适合用 Code Mode,什么任务不适合?

适合的是需要多次相关工具调用的任务,比如同一改动要落到很多文件、搜索结果需要先过滤再读、几个独立命令可以并行。不适合的是单次工具调用就能完成的任务,多写一段 JavaScript 反而是额外开销。另外 Code Mode 不能用在 -p、Agent SDK、VS Code 面板、桌面应用和云端会话里,脚本化场景无法使用。

Code Mode 起不来,提示里写的原因怎么读?

Code Mode (experimental) is not available 这行后面就是原因,/status 里也会显示。版本太老就更新,它 isn’t open to your account 就检查网络再试,it only works directly with the Anthropic API 就把走云厂商或网关的设置去掉,it doesn’t work with an API key helper 就删掉 apiKeyHelper 与 ANTHROPIC_AUTH_TOKEN,it needs settings that Claude Code downloads from Anthropic 就取消 DISABLE_TELEMETRY,OpenTelemetry is on 就取消 CLAUDE_CODE_ENABLE_TELEMETRY。看到这行提示但完全没提到 Code Mode,就是版本太老或者环境变量没设成 1。

小结

Code Mode 解决的是一个具体问题,工具调用链条越长,来回等待和上下文往返的成本越高。它把这段链条压缩成一段由模型自己写的 JavaScript,官方在文档里直接写明这是实验特性且可以随时移除。当前版本仍有一批硬门槛,尤其是账号、模型和运行界面三项同时受限,脚本化与后台会话也用不上。

真正需要留意的是权限审查对象变了。分类器审的是整段代码而不是每一次调用,运行时才计算出来的路径它看不到。对需要严格管控的企业环境,这意味着规则和钩子不能省,Bash 规则的逐段检查写法也要跟着调整。

全部文章归档与模型专题