Claude Code 前不久加了一个实验开关,叫 Code Mode。
打开以后,Claude 干活的方式变了:不再一次调一个工具,而是先写一段 JavaScript,让代码去调工具。
这篇我想把它讲透:为什么会有它,原理是什么,一个真实任务怎么走完,怎么打开、怎么管住它。再用我自己跑的 24 轮对照实验,看它到底省了什么、没省什么。
先交代依据:机制部分以 Claude Code 官方文档《Run tool calls from code with Code Mode》和环境变量文档为准;实测数据全部来自我们自己的实验。
一、为什么会出现:一次调一个工具的三笔开销
先看没有 Code Mode 时,Claude Code 是怎么干活的。
它手里有一组工具:Bash、Read、Edit、Grep 等等。每一步,模型发出一个工具调用,Claude Code 执行,把结果原样交回去,模型读完再决定下一步。
这一来一回,叫一个回合。一个任务往往要十几、几十个回合。
这个模式很稳,但有三笔开销。
第一笔,结果回灌。 每一步的输出,不管有用没用,都进了上下文。一次 grep 可能返回几百行,模型真正要的只有两三行。
第二笔,每轮重发。 每个回合,都要把前面整段对话再发给模型一次。有缓存,单价便宜,但仍然计费,而且上下文越来越长。
第三笔,开局占用。 每个工具的说明,从第一句话起就躺在上下文里。工具越多,占得越多;接的 MCP 服务越多,这笔越重。
MCP:Model Context Protocol,一种让 AI 接入外部服务和工具的协议。接一个 MCP 服务,就多一组工具说明进上下文。
Code Mode 要解决的,就是这三件事。


二、原理:把一组工具,换成一个能跑代码的工具
Code Mode 的做法,一句话:把一大组工具,换成一个执行代码的工具,叫 REPL。
REPL 是 Read-Eval-Print Loop 的缩写,可以理解成一个一直开着、随时能接着写代码的运行环境。在 Code Mode 里,它是一个整场会话都在运行的 JavaScript 环境。
原来的工具,在里面都变成了函数。从我们实验会话记录里模型实际写的代码看:跑命令是一个反引号模板 $,读文件是 file,改文件是 edit,写文件是 write。官方文档的示例里也出现了 $ 和 edit。

工具变成函数,带来四个变化。
1. 一段代码可以调很多次工具。 原来要十个回合的事,现在一个回合就能发出去。
2. 中间结果留在变量里。 上一步的结果直接交给下一步,不必先回到对话、让模型读一遍。变量整场会话都在,下一段代码还能接着用。
3. 可以并行。 互相独立的命令,可以在同一段代码里同时跑。
4. 只交回需要的。 代码结尾那个表达式的值,才是模型读到的东西。前面可以先过滤、计数、截取,把几百行压成几行再交回。
还有一个工程细节:代码跑得久怎么办?
默认是前台执行,模型等代码跑完,上限十分钟。在 auto 或 bypass 权限模式下,代码可以转到后台跑,上限两个小时。这期间你可以继续和它说话,模型再用一个叫 Poll 的工具去取结果。
把这些拼在一起,我的理解是:
Code Mode 把「调用、读结果、再决定」这个循环,从模型的回合里,搬进了代码里。 模型少走回合,上下文里少装中间产物。
对照三笔开销看:结果回灌,被「只交回需要的」挡掉一大半;每轮重发,因为回合少了而少发几轮;开局占用,因为一组工具说明换成了一个 REPL,起步就轻。
三、一个任务怎么走完:同一个活,开和关各走一遍
原理听起来不复杂。但它实际怎么走、代码长什么样,跑一遍才看得清。
我拿同一个开发任务,开和关各走一遍。任务是:给开源项目 Flask 的 routes 命令加一个 --json 输出选项,要兼容已有的排序和 --all-methods 参数,没有路由时输出 [];补上测试和文档,再跑一遍全量测试。
关着的时候,模型一步一步来:grep 找命令,看函数,看测试和文档,改源码,改测试,跑测试。十次左右工具调用,每次结果都回到对话里。我录下来的那一轮(关闭第 1 轮),一共 11 次 Bash 调用。
开着的时候,第一段代码就把三件事打包了。下面是模型在实验里实际写的代码(节选自会话记录,原样未改):
js
const src = await $`grep -n "routes" -n src/flask/cli.py | head -30; grep -rn "flask routes\|routes_command\|test_routes\|class TestRoutes" tests docs | head -30`.text();
const fn = await $`awk '/^@click.command\("routes"/,/^cli = /' src/flask/cli.py`.text();
({src, fn})
三行,做了三件事:grep 源码,grep 测试和文档,用 awk 截出整个 routes 函数。结果装进变量 src 和 fn,末行 ({src, fn}) 把两段打成一个对象,一次交回模型。
这就是前面说的「多次调用」加「只交回需要的」。
又看了几段测试和文档之后,模型写了一段更长的代码,把改动一口气做完(节选,「...」处为省略):
js
const cli = 'src/flask/cli.py';
await edit(cli, [
['import inspect\n', 'import inspect\nimport json\n'],
...
]);
await edit('tests/test_cli.py', [
...
]);
await edit('docs/cli.rst', ...);
await edit('CHANGES.rst', ...);
const r = await $`.venv/bin/python -m pytest -q 2>&1 | tail -15`.nothrow();
r.output
一段代码里改了源码、测试、文档和更新日志四个文件,接着跑全量测试,只把测试输出的末尾 15 行交回。跑测试这一步转到了后台,模型用 Poll 把结果取回来。

整个任务下来,模型的回合数,三次平均从十个左右降到七八个(关闭三轮分别是 12、9、9,开启三轮是 7、6、10)。
跑完对照,有两点是我原本没想到的。
一是「只交回需要的」,要看模型怎么写。 另一个任务是读完 FastAPI 的 fastapi/security/ 目录,整理成一张表。模型的第一段代码是这样的(原样):
js
const files = (await $`ls fastapi/security/`.text()).trim().split('\n');
const out = {};
for (const f of files) if (f.endsWith('.py')) out[f] = await file('fastapi/security/'+f).text();
out
它读了七个文件,然后把全文原样交回了。机制允许你只交回需要的,但模型不一定每次都这么做。
二是并行。 24 轮生成的代码里,没有出现 Promise.all,基本是按顺序一条条执行。这次的收益,主要来自合并回合,而不是同时跑。
四、怎么用,怎么管住它
开启
版本要 2.1.323 以上,把这个环境变量设成 1:
bash
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude
带在命令行前,只管这一次。想每次都开,写进用户级设置 ~/.claude/settings.json:
json
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
}
}
注意:写在项目设置里无效。这是有意的设计,防的是你克隆来的仓库替你把它打开。
它目前只支持终端里的交互会话。-p 模式、Agent SDK、VS Code、桌面应用、云端会话都不支持;也不能和 Remote Control、Claude in Chrome、computer use 同时用。
确认和看代码
第一次启动会弹一页说明,选 Yes 之后重启,顶部会出现已开启的提示。
开启后,对话里的代码默认是折叠的。想看模型写了什么,按 Ctrl+O 打开记录,展开 Code 那一行。
我的建议是,头几次用的时候多按几次 Ctrl+O。看它写的代码,比看任何介绍都直观。


权限:两层,要分清
这是我觉得用之前必须想清楚的一节。
第一层,每次调用照旧过规则。 代码里的每一次工具调用,仍然按原来的工具名,走你配置的允许、拒绝规则和 PreToolUse hook。代码里调了 $ 跑一条命令,这条命令照样按 Bash 的规则判断。
第二层,auto 模式的分类器只审一次。 auto 模式下有一个安全分类器替你判断能不能放行。开了 Code Mode 后,它在运行前审一次整段代码,看不到运行时才算出来的值。比如一条命令的参数是从上一步结果里拼出来的,分类器审代码时并不知道它会是什么。
所以,真正要管住的命令,得写成明确的规则或 hook,别只指望分类器。
想先看代码再放行,就给 REPL 加一条 ask 规则:
json
{
"permissions": {
"ask": ["REPL"]
}
}
这样每段代码执行前都会弹窗。选 No,整段代码停下;选 No 并附上理由,只拒掉这一次调用,模型会按你的理由调整。

hooks
hook 是 Claude Code 在工具调用前后自动执行的脚本。和 Code Mode 相关的有三点:
- hook 可以匹配 REPL,在 PreToolUse 里读
tool_input.code,拿到整段 JS 再判断; - 用 PostToolUse hook 返回
updatedToolOutput,可以在模型读到输出之前先打码,比如把密钥、手机号替换掉; - 代码里的 Bash 命令到 hook 时,可能带上 cd 前缀,形如
cd 'app' && git push。写 hook 时要按片段判断,别只匹配整条命令的开头。
沙箱:只管 shell
Claude Code 的沙箱只管 shell 命令。JS 代码本身,以及它发起的文件、网络、MCP 调用,都在沙箱之外。
需要真正隔离的场景,用容器或虚拟机。

关闭
删掉这个变量,或者设成 0。命令行和设置里有一处是 0,就是关。
还有一点:用 Code Mode 开的会话,只能在开着 Code Mode 的终端里恢复。
我的用法
- 先只在命令行前带变量,单独开一个会话试,不急着写进设置;
- 敏感的仓库,给 REPL 加 ask;
- 要拦的命令写成规则或 hook,不依赖 auto 模式的分类器;
- 头几次多按 Ctrl+O,看它到底写了什么。
五、24 轮实测:它到底省了什么
机制讲完了,用数据验证一下。
实验怎么做的
- 环境:单独的临时目录,每轮用全新的仓库副本;Claude Code 2.1.329,以安全模式启动,排除插件和个人配置的干扰,auto 权限模式。
- 仓库:FastAPI 和 Flask 两个开源项目。
- 四类任务 :大范围搜索(统计全仓库没有 docstring 的函数)、简单读取(读 README 回答三个问题)、多文件阅读(读完
fastapi/security/整理成表)、真实开发(上面那个--json任务)。 - 重复:每类开、关各 3 遍,共 24 轮。模型统一用 Opus 5.5,默认推理强度。
- 计量:token 全部从会话记录里每次请求的 usage 字段加总。
- 验对错:搜索题先用 AST 算好标准答案;开发题除了原有测试,另写了一套模型看不到的验收测试(原始仓库跑这套测试全部失败)。
下面数字都是三次平均。
开局:35.7K → 21.1K
第一次请求的上下文,从 35.7K token 降到 21.1K,少了约 14.6K。
这就是「开局占用」那笔:一整套工具说明,换成了一个 REPL。这笔省在每一次请求上,回合越多,累计越多。
读取:少了三到五成
模型读进去的 token(输入 + 缓存写入 + 缓存读取),四类任务分别是:
| 任务 | 关闭 | 开启 | 变化 |
|---|---|---|---|
| 大范围搜索 | 109K | 66K | −39% |
| 简单读取 | 128K | 85K | −34% |
| 多文件阅读 | 257K | 124K | −52% |
| 真实开发 | 414K | 209K | −50% |
搜索和读取两类,开和关的请求数一样,都是 3 次。原因是 Opus 5.5 在普通模式下,也会自己写一个脚本一次算完。所以这两类省下的,主要是开局那笔固定开销乘以请求次数。
真正多步的任务,差别才拉开:多文件阅读和开发都少了一半左右。开发任务会话结束时的上下文,从 45.3K 降到 32.8K。
上下文涨得慢,同样一个窗口能多干不少活,才会碰到压缩。
速度:小任务反而慢
- 简单读取:11 秒 → 14 秒,反而慢了。从记录看,开启的三轮都多了一次 Poll,多了一来一回;
- 大范围搜索:19 秒 → 20 秒,基本持平;
- 多文件阅读:50 秒 → 45 秒;
- 真实开发:64 秒 → 58 秒。
多步任务快了一成左右。
质量:24/24
24 轮全部做对。搜索 6 轮答案都和 AST 标准答案一致;开发 6 轮全部通过原有的 499 项测试和 4 项隐藏验收测试;多文件阅读两种模式产出的表格基本一致。
开和关,在质量上没有差别。

费用:只差一成左右
按 Opus 5.5 的 API 价格折算,四类任务的费用变化是:
| 任务 | 关闭 | 开启 | 变化 |
|---|---|---|---|
| 大范围搜索 | $0.103 | $0.092 | −10% |
| 简单读取 | $0.163 | $0.153 | −6% |
| 多文件阅读 | $0.280 | $0.306 | +9% |
| 真实开发 | $0.299 | $0.279 | −7% |
读取少了一半,钱只差一成左右,多文件阅读还贵了 9%。
原因要看钱花在哪。按 Anthropic 官方定价页,Opus 5.5 每百万 token:输入 4,缓存读取 0.20,一小时缓存写入 8,输出 20。缓存读取只有输入价的二十分之一。
Claude Code 每次请求,绝大部分输入走的是缓存读取。Code Mode 省下的,大多正是这部分便宜的 token。真正花钱的是写缓存和输出,这两项没怎么变。
拿开发任务算。关闭时一轮平均约 0.30:缓存读取 0.080,占 27%;缓存写入 0.122,约占四成;输出 0.096,约占三成多。
开启后,缓存读取降到 0.038,砍掉一半多;但缓存写入是 0.137,输出是 $0.104,都略有上升。一减一加,整根条只短了一小截。
多文件阅读为什么反而贵?模型写的代码、跑出来的整段结果,都是对话里的新内容,要写进缓存。这一项缓存写入从 0.148 涨到 0.206,前面说的「七个文件全文交回」就在其中。

所以要分清两个口径:读取 token 和账单。这次实验里,前者少一半,后者只差一成左右。这里算的是 API 价格。
这次实验的边界
一个模型,每组 3 次,单个任务在十来次请求以内。没测 MCP,也没测一小时以上的长任务。结论只在这个范围里成立。
六、结论:特点、优势和适合的场景
它的特点
Code Mode 的本质,是把工具调用的循环从模型的回合搬进代码,让中间结果留在变量里,只把需要的部分交回对话。
它的优势在上下文,不在账单
开局更轻,少了约 14.6K;上下文涨得更慢;多步任务回合更少;质量不打折。
为了省钱专门打开它,在 Opus 5.5 上不值得:读取省一半,账单只差一成左右,有时还更贵。
还有一点:模型本来就会把几条命令串进一次 Bash。模型越会省回合,这个开关的边际收益越小。
适合的场景
按机制推,下面这些场景收益会更明显:
- 同一个改动要改很多文件。 一段代码改完再跑测试,像上面的开发任务;
- 搜索结果要先过滤再看。 在代码里先筛、先数,只交回几行;
- 几条独立命令可以同时跑。 机制上支持并行,不过这次实验里模型没怎么用;
- 接了多个 MCP,要在几个服务之间倒数据。 中间数据在变量里流转,不用每次都经过对话。这一条我这次没测,是按机制推的;
- 长会话。 上下文涨得慢,碰到压缩就晚。
先别开的场景
- 一两步就能完成的简单任务,写代码本身就是额外开销,读取任务还慢了 3 秒;
- 要用桌面应用、VS Code、Remote Control、Chrome 插件或 computer use 的工作流;
- 对审计要求高、需要逐个调用审批的环境。

我的建议是:别只看任何人的数字,包括我的。拿你自己的活,开和关各跑几次,从会话记录里把缓存读取、缓存写入、输出分开加总,再按价格算一遍。
Code Mode 还在实验阶段,等它变了,我再测一轮。
你在什么场景下用过 Code Mode?体验和我测的一样吗?
依据:机制以 Claude Code 官方文档《Run tool calls from code with Code Mode》、环境变量文档为准;价格以 Anthropic 官方定价页和 Prompt Caching 文档为准。实测数据来自我们自己的 24 轮对照实验(Claude Code 2.1.329,Opus 5.5,2026-11-20 跑完),文中代码节选自实验会话记录中模型实际写的代码,未作改动。
本文由作者在 AI 辅助下完成。