Claude Code 的 Code Mode 怎么开?使用条件、批量调用与权限边界

曲速指南2026-11-16发布 WarpEdit
303 0 0

Code Mode 是 Claude Code 在 2.1.323 版加入的实验功能:Claude 可以把多项工具调用写进一段 JavaScript,串联结果或并行处理独立步骤,再把需要的输出交回模型读取。它适合“一次要搜很多文件、改很多处、再跑测试”的任务;日常改一两行的小活没必要开。它默认关闭,只能在终端交互会话里用,桌面版、VS Code 面板和 -p 都不支持,权限检查的方式也跟着变了,开之前最好先弄清这几条。

Claude Code 的 Code Mode 概念封面:JavaScript 纸卷收拢工具,标注实验功能

Code Mode 到底改变了什么

普通调用中,Claude 直接请求工具并读取结果;Code Mode 则让它把多步操作写成代码,交给 Claude Code 在当前会话执行。区别是这些步骤可以由代码衔接,中间结果不必逐项交回模型读取。一段代码可以并行跑命令、用前一个结果驱动下一个调用,最后只返回 Claude 需要读的那部分输出。

官方文档以“把重试次数上限调高”为例,展示 Claude 可能生成的代码。这里的 $ 与 edit 由 Code Mode 执行环境提供;这不是直接粘进 Node.js 就能运行的通用脚本,搜索词和测试命令也依赖具体项目:

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

搜索、改文件、跑测试一气呵成,最后一行把改了哪个文件和测试输出交回给 Claude。对话里你看到的仍是具体的工具调用(比如改动的 diff),代码本身默认折叠;按 Ctrl+O 打开对话记录查看器,展开 Code 行就能读到 Claude 写的 JavaScript。

Code Mode 概念流程图:模型写 JavaScript 串起读文件、改文件与测试,再返回必要结果,工具权限仍生效
Code Mode 调用方式的概念示意,非终端截图:一段 JavaScript 可以串起多项工具操作,工具权限规则仍生效。图中步骤仅用于解释工作方式。来源:Claude Code 官方文档。

开之前先确认能不能用

以下条件按 2026 年 11 月 16 日的官方文档核对。版本够新仍不代表账号、组织与当前启动方式都满足要求:

条件 要求
版本 v2.1.323 或更高,latest 和 stable 渠道都可以;stable 还没跟上时可以等,或切到 latest
账号 包含 Claude Code 访问权的订阅或 Console 账号,免费 Claude.ai 计划不包含 Claude Code;Code Mode 不能经网关、Amazon Bedrock、Claude Platform on AWS、Google Cloud、Microsoft Foundry 等第三方平台使用
组织 没有启用 HIPAA 配置或零数据保留(ZDR)
模型 Opus 5.5、Sonnet 5.5、Haiku 5.5 或 Fable 5.2
使用方式 只支持终端里的交互式 claude 会话;-p、Agent SDK、VS Code 面板、桌面版和云端会话都不行
安装方式 官方原生构建版
Windows 需要装 Git for Windows
其他设置 开着 API key helper、agent teams、OpenTelemetry 导出或 DISABLE_TELEMETRY 时无法启动

开启后还有几项功能会用不了:Remote Control、Claude in Chrome、computer use 都不能用;会话不能转到桌面版或变成后台会话;恢复会话也只能在终端里、并且保持 Code Mode 开启。

中国大陆读者要多注意一点:Anthropic 新版支持地区政策已于 11 月 12 日生效,账号本身的可用性比 Code Mode 的门槛更先决定能不能用,具体情况见站内的 Claude 支持地区政策解读。

怎么开、怎么关、团队怎么禁用

开启

  1. 运行 claude --version 核对实际版本,claude doctor 可检查安装与配置。原生自更新安装可用 claude update;Homebrew、WinGet 等安装按对应包管理器更新。若 stable 更新后仍未到 2.1.323,可以等待;允许切换的原生安装可在 /config → Auto-update channel 选择 latest,Homebrew 的渠道则由所安装 cask 决定,不能只改该设置。安装和更新入口见文末官方指南。
  2. 把环境变量 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE 设为 1 再启动。只想试一次,在 shell 里临时设置:
    # macOS / Linux / WSL
    CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 claude
    
    # Windows PowerShell
    $env:CLAUDE_CODE_EXPERIMENTAL_CODE_MODE = "1"
    claude

    上面 macOS/Linux 的单行赋值只用于这次启动;PowerShell 的 $env: 赋值会保留在当前终端窗口。想让新会话默认开启,可把下面的 env 项合并进用户设置 ~/.claude/settings.json,保留已有其他键,不用整份示例覆盖原文件:

    {
      "env": {
        "CLAUDE_CODE_EXPERIMENTAL_CODE_MODE": "1"
      }
    }
  3. 第一次进入时,Claude Code 会显示实验功能确认,选择 Yes, turn on Code Mode。重启后会话顶部出现 Code Mode (experimental) is on · this session can be resumed only with Code Mode on,就说明开好了。

有一个设计值得点赞:Claude Code 会忽略项目设置文件中的这个变量,项目本身不能仅靠该设置替用户开启 Code Mode。

上手可以先用官方给的测试任务:让 Claude 读完项目里所有 Markdown 文件,列出指向不存在本地文件的链接。这种“读很多、筛一遍”的活最能看出区别。

关闭

从 shell 和 ~/.claude/settings.json 移除这个变量,或把值改为 0,再开新会话。PowerShell 当前窗口可用 Remove-Item Env:\CLAUDE_CODE_EXPERIMENTAL_CODE_MODE 移除先前的赋值;这不会自动修改设置文件。只要任一处是 0,另一处写了 1 也不会开。注意:用 Code Mode 开始的会话,之后 --continue 或 --resume 时必须保持变量为 1,否则 Claude Code 会拒绝恢复。

团队整体禁用

管理员在托管设置(managed settings)的 env 里把 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE 设为 "0",组织里就没人能用。已经在 Code Mode 会话里的人,退出或重启前不受影响;之后既不能新开,也不能恢复旧的 Code Mode 会话。反过来,托管设置不能替用户强制开启。

权限检查会变成什么样

这是开之前最该想清楚的一点。Claude 代码里发起的每个工具调用,仍然会经过你的 deny、ask 权限规则和 PreToolUse hook,已有规则仍按原匹配方式工作。额外变化在于分类器与交互确认怎样参与:

  • 自动模式(auto mode):分类器在代码运行前审查整段代码,而不是逐个审查工具调用。它看不到运行时才算出来的值,比如从搜索结果里取出的文件路径。所以必须管住的调用,仍要靠规则或 hook 兜底。
  • 其他需要确认的模式:代码直接开始跑,遇到在该模式下本来就要问你的工具调用时,再逐个弹出确认。

想审查代码本身,可以写一个匹配 REPL(执行 Claude 代码的那个工具)的 PreToolUse hook,从 tool_input.code 读到完整 JavaScript。官方还提醒了一句老问题:Bash 规则是按命令文本匹配的,换个写法就可能绕过,这和开不开 Code Mode 无关;需要真正不依赖命令文本的限制,要用沙箱。

如果工具调用被拒,先区分权限规则和 hook 错误。Code Mode 下,PreToolUse hook 无法启动或超时,可能使调用被拒;若应有的代码输出没有回来,也要检查 UserPromptSubmit hook 是否拦住了 source=poll_event 的输出事件。按具体错误修复 hook 或超时配置,不要把所有拒绝都当成网络故障。

自动模式下还有一个小坑:前一段代码还在跑时 Claude 又启动了新代码,前一段会失去分类器审查,剩下需要审查的调用改为问你,没有连接 IDE 时还会带倒计时(文档示例显示 1:59)。倒计时结束没回答,这个调用就被拒绝,之后同类调用也会直接被拒,给 Claude 发条消息才能恢复提示。

跑得久的代码怎么办

代码跑长时间的构建或测试时,有两种情况:

  • 等待:Claude 等代码跑完再回复,代码最多运行 10 分钟,你在权限提示上花的时间也算在内。
  • 后台:你可以继续和 Claude 对话,代码最长可以跑 2 小时。

这里后台运行的是当前终端会话中的代码,不是把整个会话转成后台会话。官方文档列出的前提是会话从 auto 或 bypassPermissions 模式启动;使用自己获准的权限模式即可,不要只为了两小时运行上限而跳过权限检查。如果 Claude 还是在等,多半是中途切过模式(按 Shift+Tab 切回启动时的模式),或者会话是从 claude --resume 列表里挑的。文档还列出 --tools 会影响后台运行:能用自动模式的,可退出后在保持 Code Mode 变量开启的前提下,用 claude --continue --permission-mode auto 进入,并按需要去掉该启动限制;组织要求固定工具集时,应保留要求并接受等待运行的限制。

哪些任务值得开

官方推荐的场景是三类:同一种改动要在很多文件里重复、搜索结果需要先过滤再给 Claude 读、几条互不相关的命令可以同时跑。按这个思路,结合上面的限制,可以这样判断:

任务 建议 理由
跨很多文件重复改同一种写法(改 API 名、换导入路径) 适合尝试 搜索、修改与测试可在一段代码里衔接,减少模型反复读取中间输出;实际耗时仍取决于任务
全项目检索后筛选(找死链、找未使用的导出) 适合尝试 只把筛完的结果交给 Claude,不用让它读全部原始输出
同时跑 lint、类型检查和测试 适合尝试 互不依赖的命令可以并行
单个文件里改几行、修一个明确的 bug 不必 普通模式就够,开了反而多了恢复会话等限制
删除数据、改生产配置等需要逐步确认的操作 不建议 自动模式下审的是整段代码,看不到运行时才确定的目标
要用 Remote Control、Claude in Chrome、桌面版或 VS Code 面板 不能开 这些场景官方明确不支持
团队有严格审计要求 先评估 核对现有规则与日志是否满足要求;需要检查整段代码时可用匹配 REPL 的 hook,不满足组织要求时由管理员决定是否禁用

如果关心把检查要求放进代码审查流程,可以延伸阅读站内的 Open Code Review。Code Mode 这里的代码由模型生成,不应据此把它当成预先固定好的审查规则。同时管着好几个编程代理的,也可以看看 T3 Code,不过它是多代理界面,和 Code Mode 解决的不是同一个问题。

版本时间线和已修的坑

  • 2.1.323(npm 发布于 2026-11-12 20:29 UTC,北京时间 11 月 13 日 04:29):加入 Code Mode,标注为实验性、需手动开启。
  • 2.1.325(2026-11-13 20:07 UTC,北京时间 11 月 14 日 04:07):修复了几处 Code Mode 问题,包括脚本无视 EnterWorktree 进入的工作树、把 ~ 路径写进项目、MCP 服务器登录过期后 /mcp 仍显示已连接;在权限对话框或计划确认里随“Yes”输入的文字传不到 Claude;恢复一个在 Code Mode 脚本运行中结束的会话时,Claude 会自己开始干活(现在会等你的下一条消息)。

官方文档写明,Code Mode 是实验功能,任何版本都可能修改或移除。用了遇到问题,可以运行 /feedback 反馈。如果你用 2.1.323 或 2.1.324,优先更新到包含这些修复的 2.1.325 或更新版本,再按当前文档确认支持范围。npm 发布时间只用于记录版本历史,不代表所有原生安装渠道或账号在同一时刻可用。

开不起来时先查这几条

会话顶部出现 Code Mode (experimental) isn't available,同一行会写原因,/status 里也能看到。最常见的几种:

  • it isn't open to your account yet:版本低于 2.1.323 就先更新;版本够了,检查网络后重开,还不行就隔天再试。
  • it only works with the Anthropic API:当前请求经第三方云平台或网关,Code Mode 不支持这条路径。有获准的直连账号时,再按自己的配置说明切换;必须使用组织网关的用户继续用普通模式。
  • it needs settings that Claude Code downloads from Anthropic:检查是否有 DISABLE_TELEMETRY 等变量阻止所需设置下载。若这些设置承担组织或个人的既定要求,保留它们并使用普通模式,不为试用功能盲目取消。
  • your organization's settings don't allow it:管理员禁用了,找管理员。

完全没有出现 Code Mode 相关提示,就先看版本,再确认变量在 shell 或用户设置里是 1,并检查自己能管理的其他位置(包括 --settings 指定文件)是否有 0;托管设置中的禁用应由管理员处理。更完整的兼容原因表见官方 Code Mode 文档。API key helper、OpenTelemetry、agent teams 或检查工具调用的 mod 也可能冲突,应根据界面给出的具体原因处理。更多 Claude Code 的功能与入口,可以看站内的 Claude Code 条目。

资料来源

  • Claude Code 官方文档「Run tool calls from code with Code Mode」(2026-11-16 查阅):https://code.claude.com/docs/en/code-mode
  • Claude Code 官方安装、版本渠道与更新说明:https://code.claude.com/docs/en/setup
  • Anthropic 支持地区政策(2026-11-12 生效):https://www.anthropic.com/supported-countries
  • Claude Code CHANGELOG(2.1.323 加入 Code Mode,2.1.325 修复项):Claude Code CHANGELOG
  • npm 包 @anthropic-ai/claude-code 版本发布时间(2.1.323:2026-11-12 20:29 UTC;2.1.325:2026-11-13 20:07 UTC):https://registry.npmjs.org/@anthropic-ai/claude-code
© 版权声明

相关文章

暂无评论

您必须登录才能参与评论!
立即登录
none
暂无评论...