Claude Code Code Mode 上手:让 Claude 写 JS 批量调工具

Claude Code 2.1.323 加了一个实验开关 Code Mode:打开后,Claude 不再一次只调一个工具,而是先写一段 JavaScript,把搜索、改文件、跑测试串成一步,由 Claude Code 在你的会话里执行。紧接着的 2.1.325 又把沙箱里 Bash 命令的免审批默认关掉了。这篇按官方 Code Mode 文档、沙箱文档和更新日志整理:怎么打开、怎么看它写的代码、权限规则和 hooks 要不要改,以及升级后自动化任务卡在审批上该补哪一行配置。
Code Mode 改的是 Claude 调工具的方式
平时 Claude 调一次 Bash、Read 或 Edit,读完结果再决定下一步,十个相关的小动作就是十个来回。Code Mode 下你照常用自然语言提需求,Claude 写一段代码去调这些工具:几条命令可以并行跑,上一个结果能直接喂给下一个调用,最后只把需要读的那部分返回给自己。官方文档里的例子是把重试次数从 3 改到 5:
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() });
界面上你看到的还是一个个工具调用,比如 edit 的 diff,代码本身默认折叠。这和 API 侧的程序化工具调用是同一个思路,原理和 Cloudflare 的做法见站内教程 Agent Code Mode 是什么;这次的区别是它进了 Claude Code 终端版,不用自己搭沙箱。
| 对比项 | 普通会话 | Code Mode 会话 |
|---|---|---|
| Claude 怎么调工具 | 一次一个,读完结果再下一步 | 写一段 JS,一步里调多个工具 |
| 界面显示 | 工具调用 | 工具调用;代码在 Ctrl+O 里 |
deny/ask 规则、PreToolUse hook | 逐个工具调用检查 | 代码里的每个工具调用照样逐个检查 |
| 自动模式分类器 | 审每个工具调用 | 审整段代码,看不到运行时算出的值 |
| 单次运行时长 | 按命令自身 | 前台等待最多 10 分钟;后台最多 2 小时 |
| 恢复会话 | 随意 | 只能在终端、且 Code Mode 开着时恢复 |
前置条件
- Claude Code v2.1.323 或更新,且是原生安装版(native build)。
stable通道还没到这个版本的,等它跟上或切到latest。 - Claude 订阅或 Console 账号。走网关、Amazon Bedrock、Claude Platform on AWS、Google Cloud 的 Agent Platform、Microsoft Foundry 的都用不了;组织开了 HIPAA 配置或零数据保留也不行。
- 模型是 Claude Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 5.2。
- 在终端里开交互式
claude。-p、Agent SDK、VS Code 面板、桌面端和云端会话都不支持。Windows 上要装 Git for Windows。 - 没开这些设置:
apiKeyHelper、agent teams、OpenTelemetry 导出、DISABLE_TELEMETRY。
第一步:查版本,打开开关
claude --version
claude update # 低于 2.1.323 时
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude
想每个新会话都默认打开,就写进用户设置 ~/.claude/settings.json:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
}
}
写进项目的 .claude/settings.json 没用,Claude Code 会忽略项目设置里的这个变量,别人的仓库没法替你打开 Code Mode。第一次启动会弹确认,选 Yes, turn on Code Mode,重启后会话顶部出现这一行就算开好了:
Code Mode (experimental) is on · this session can be resumed only with Code Mode on
第二步:给一个要调很多次工具的任务,再看代码
官方建议拿这三类任务试:同一处改动要改很多文件;搜索结果要先过滤再给 Claude 读;几条互不相关、能同时跑的命令。在熟悉的项目里发一句:
Read every Markdown file in this project and list the links that point to local files that don't exist.
跑完按 Ctrl+O 打开记录查看器,每段代码是一行折叠的 Code,展开就能看到 JavaScript,再按一次 Ctrl+O 回到对话。头几次建议每段都展开,看它怎么拆任务、返回了哪些字段,再决定这类任务以后要不要交给 Code Mode。
第三步:核对权限规则和 hooks
现有规则不用改,代码里的每个工具调用都会经过你的 deny、ask 规则和 PreToolUse hook,Bash 的规则和 matcher 照旧生效。变化在两处:
- 自动模式:分类器在每段代码运行前审一次整段代码,不再逐个审工具调用。它看不到运行时才算出来的值,比如从搜索结果里取出的路径。必须拦住的调用,要靠规则或 hook 兜底。
- 其他模式:代码直接开跑,原本会弹确认的工具调用照样逐个问你。
想审代码本身,就写一个 matcher 为 REPL 的 PreToolUse hook,从 tool_input.code 里读 JavaScript。写 hook 的基本做法见站内 Claude Code Hooks 教程。官方文档还提醒,Bash 规则匹配的是命令文本,换个写法就可能绕过,开不开 Code Mode 都一样,真要硬边界得用沙箱。
自动模式下分类器只看代码文本,看不到运行时从搜索结果里拿到的路径。不能出错的调用,留给 deny 规则和 hook。
第四步:2.1.325 之后补沙箱配置
2.1.325 的更新日志写明:沙箱里的 Bash 命令默认改走正常审批流程。设置参考页给的默认值是 false,v2.1.324 之前是 true。原来靠「开了沙箱就免确认」跑的定时任务,升级后可能停在审批上。要保持原样,在 sandbox 里把两个键都写上:
{
"sandbox": {
"enabled": true,
"autoAllowBashIfSandboxed": true
}
}
沙箱是用托管设置统一开的,要把这个键写进优先级最高的托管来源。同一版本还有三处改动会影响自动化:
- 定时任务和
/loop在运行声明了allowed-tools或 hooks 的 Skill 前会先问,要无人值守就在permissions.allow里加Skill(name)。 - 在不是本项目、也没被信任的仓库里,只读 git 命令也要先问。用
--add-dir把那个仓库加进来,写在additionalDirectories设置里不算。 - 沙箱拒绝写入附加目录里的
.claude设置、skills、agents、commands 和 hooks,和启动目录的规则一致。
权限配置的整体写法可以对照 Claude Code 权限设置教程。
常见坑
- 顶部显示 isn't available:原因写在同一行,
/status里也有。最常见的是it only works with the Anthropic API(设了网关或自定义ANTHROPIC_BASE_URL)和it doesn't work with an API key helper(要去掉apiKeyHelper、ANTHROPIC_AUTH_TOKEN,改为登录或设ANTHROPIC_API_KEY)。开了 agent teams 的,先 unsetCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS。 - 恢复会话被拒:Code Mode 会话用
claude --continue或--resume时,变量必须还是1。反过来,没开 Code Mode 时建的会话,设了变量恢复也不会进 Code Mode。 - 跑长构建卡住:前台代码最多跑 10 分钟,停在权限确认上的时间也算在内。想让代码转后台(最多 2 小时)同时继续聊天,会话要以 auto 或
bypassPermissions模式启动;传过--tools的,去掉这个参数,用 auto 模式重开。 - 带倒计时的确认框:自动模式下前一段代码还在跑、又起了新代码,前一段剩下的调用会失去分类器审查,转成问你。没连 IDE 时会显示 1:59 的倒计时,超时就拒绝这次调用,之后同类调用不再弹窗直接拒绝;给 Claude 发一条消息能恢复弹窗。
- 调用被 hook 拒绝:报
the hook failed是 hook 没起来、被杀,或以 126、127、大于 128 的码退出;报the hook did not finish是超时,调大 hook 的timeout。想让command或http类 hook 出错、超时时放行,给它设"onFailure": "continue"。
完成标准
- 会话顶部出现
Code Mode (experimental) is on,Ctrl+O里能展开看到一段 Code。 - 已经在自动模式下确认:自己最在意的几条 deny 规则或 hook 在 Code Mode 里照样拦得住。
- 升级到 2.1.325 后,靠沙箱免审批的定时任务已经补上
autoAllowBashIfSandboxed,要无人值守的 Skill 已加进permissions.allow。 - 团队不打算用的,已经在托管设置里把
CLAUDE_CODE_EXPERIMENTAL_CODE_MODE设成0。
最后
先找一个要改十几个文件的重复改动,用 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude 开一个会话跑一遍,按 Ctrl+O 读完它写的代码,再决定要不要写进用户设置。版本更新的完整清单见站内快讯 Claude Code 2.1.325:Code Mode 与沙箱权限。