rg -l \"function retryPolicy\" src`.text();\nconst target = files.trim().split(\"\\n\")[0];\nawait edit(target, \"maxAttempts: 3\", \"maxAttempts: 5\");\n({ edited: target, tests: Claude Code 的 Code Mode 到底改了什么 - RouterHub npm test -- retryPolicy`.nothrow() });\n```\n\n这段代码体现了三个实际变化。第一,筛选逻辑可以在工具结果返回后立即运行,不需要把所有候选文件逐个交给模型再判断。第二,多个工具调用可以在同一段代码里表达依赖关系,只有真正依赖前一步的调用才等待前一步。第三,代码最后可以只返回路径、测试结果或错误摘要,减少把无关的原始输出重新塞回会话。\n\n但这不等于工具权限消失了。Code Mode 仍然在 Claude Code 会话中执行,工具调用仍然受到权限模式和 hook 影响。官方文档特别说明,自动模式下的分类器审查的是整段代码,而不是代码里的每一个工具调用;当代码并发运行、后续调用需要额外判断时,可能出现倒计时权限提示。`PreToolUse` hook 也可能让代码中的某次调用被拒绝或超时。因此,Code Mode 是把编排批量化,不是把审批模型改成无条件放行。\n\n## 先核对支持边界\n\n要判断一台机器是否能使用 Code Mode,可以按下面顺序排查。顺序很重要,因为只设置环境变量而忽略账号和运行面,最终看到的往往只是“功能不可用”,却不知道是哪一层不满足。\n\n第一步确认版本。官方文档要求 Claude Code v2.1.323 或更高版本。可以先运行:\n\n```bash\nclaude --version\n```\n\n如果版本低于要求,先更新;如果使用 `stable` 发布通道仍没有拿到该版本,文档建议等待通道追上,或切换到 `latest`。版本满足后,再在用户设置或 shell 中设置:\n\n```bash\nexport CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1\nclaude\n```\n\n第二步确认认证方式和上游。Code Mode 只对 Anthropic API 工作。官方文档明确列出,网关、自定义 `ANTHROPIC_BASE_URL`、Amazon Bedrock、Google Cloud Agent Platform 和 Microsoft Foundry 都不支持。也就是说,使用中转或企业云适配层时,即使普通 Claude Code 请求可以正常返回,Code Mode 也可能仍然显示不可用。这个区别需要在接入文档里写清楚,不能把“普通消息能通”当成“Code Mode 也兼容”。\n\n第三步确认会话表面。支持的是原生安装的交互式 `claude` 终端会话。`claude -p`、Agent SDK、VS Code 面板、桌面应用、云会话、Remote Control 和后台会话都不在官方支持范围内。GitHub 上已经有开发者请求把 Code Mode 扩展到 Agent SDK 会话,这个 issue 的存在反过来印证了当前文档的边界:把 `CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1` 写进设置文件,并不会让 SDK 客户端获得相同能力。\n\n第四步确认模型和组织设置。官方列出的模型包括 Claude Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.2;组织还可以通过托管设置禁用 Code Mode。HIPAA 配置、零数据保留配置、API key helper、部分遥测设置、Agent Teams、检查工具调用的 mod,以及限制 `REPL` 的工具配置,也可能使它无法启动。遇到不可用时,应该先看会话启动处的原因,或者运行 `/status`,而不是反复重试同一个变量。\n\n## 适合哪些工作流\n\nCode Mode 最有价值的地方是“中间数据需要处理,但最终只需要少量结论”的任务。比如在大型仓库里搜索多个候选文件,再按路径、内容或测试状态筛选;对一组格式相同的文件做相同替换,然后集中运行测试;并行读取多个独立配置,最后只汇总不一致项。这些任务本来就有程序化的控制流,放进一段由模型生成的 JavaScript 后,表达更接近开发者写脚本的方式。\n\n它也适合需要在工具之间传值的任务。普通模式通常需要模型从工具结果中提取文件名、行号或命令输出,再把这些值重新作为下一次工具调用的参数。Code Mode 可以直接在执行环境里保存变量,先用 `rg` 找到目标,再把筛选后的路径传给编辑函数,最后把测试命令的退出状态返回。这里的收益不是“模型变聪明了”,而是把确定性的胶水逻辑交给了执行环境。\n\n不过,涉及高风险副作用时不能只因为调用次数减少就放宽流程。删除文件、修改依赖、提交代码、推送分支、访问网络服务等动作,仍然应该使用明确的权限规则和 hook。Code Mode 让一段代码能够组织多个动作,也让一次分类判断覆盖更大的动作集合;如果组织策略要求每个副作用都由人确认,就不应该把这些操作无差别塞进同一个代码块。实践上可以先允许只读搜索和测试编排,再对编辑、提交和网络访问保留更严格的审批。\n\n## 失败时怎么定位\n\n如果启动后完全没有 Code Mode 提示,先检查版本和变量是否真的进入当前进程。不要只修改一个 shell 配置文件后继续复用旧会话,因为文档要求重新启动会话;也要确认没有在 `--settings` 文件里把同一个变量设成 `0`。如果出现“只支持 Anthropic API”之类的原因,检查 `ANTHROPIC_BASE_URL`、云厂商路由和网关配置;这不是模型名称错误,换模型不会解决认证路径不符合的问题。\n\n如果提示需要从 Anthropic 下载功能设置,检查是否设置了会关闭功能标记获取的变量,例如 `DISABLE_TELEMETRY`。如果提示 OpenTelemetry 已启用,检查 `CLAUDE_CODE_ENABLE_TELEMETRY` 和 `ENABLE_BETA_TRACING_DETAILED`。如果提示与 mod 或 Agent Teams 冲突,则需要关闭相关 mod 或取消 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`,然后启动新会话。官方文档为这些原因分别给出了处理方式,排查时应按实际提示逐项修改,不要把所有设置一次性删除。\n\n如果代码已经开始执行,但某个工具调用被拒绝,重点看 hook 错误。文档把常见情况分成 hook 启动失败、退出状态不允许、HTTP 错误、输出格式无效和执行超时;这些情况下,调用可能在 Code Mode 内部被拒绝,即使普通工具调用原本可以通过。对于明确允许失败后继续的 `command` 或 `http` hook,可以使用 `onFailure: \"continue\"`,但这会改变安全策略,只适用于已经评估过的非关键检查。对权限审批 hook,更稳妥的做法是修复启动路径、超时和输出协议,而不是把所有失败都改成继续。\n\n还要注意长任务。官方文档说明,不能放到后台运行的长时间代码会等待完成,并在十分钟后停止;Code Mode 也不支持 Remote Control 和后台会话。因此,若任务需要长时间构建、持续服务或远程无人值守执行,应该回到普通工具调用、明确的后台命令或适合该场景的 Agent SDK,而不是把 Code Mode 当作通用任务运行器。\n\n## 对工具链设计的影响\n\nCode Mode 给编码代理带来的直接启发,是把工具接口分成“高价值原子动作”和“适合组合的低风险动作”。搜索、读取、解析、测试结果采集这类操作适合被组合,因为它们常常有清晰的输入输出,失败后也容易重新运行。提交、推送、修改权限、调用外部系统这类操作则需要保留更清楚的边界,让审计日志能看出哪一个动作改变了外部状态。\n\n如果团队把 Claude Code 接入内部网关或自建客户端,还应把“不支持 Code Mode”作为能力矩阵的一项,而不是把它隐藏在普通 Anthropic 兼容性描述里。可以在接入检查中分别记录:普通消息是否可用、原生工具调用是否可用、Code Mode 是否可用、Agent SDK 是否可用。官方 issue 已经说明,Code Mode 在终端可用并不代表 Agent SDK 自动获得支持;这类表面相似、运行面不同的能力,必须分别验收。\n\nRouterHub 的[平台目录](/platforms)和[Claude Code 网关排障文章](/blogs/claude-code-tool-search-gateway-fallback)可以作为接入信息的补充入口,但具体能力仍应以 Claude Code 的版本、认证方式和官方文档为准。尤其是中转场景,不能因为一个渠道能转发普通请求,就推断它能提供依赖 Anthropic 原生运行环境的 Code Mode。\n\n归纳起来,Code Mode 的一句话变化是:Claude Code 可以先写一段 JavaScript,在宿主环境里批量、并行、带条件地调用工具,再把压缩后的结果交回模型。它对开发者的实际影响是:适合把重复的工具胶水逻辑程序化,但同时把版本、认证、会话表面、模型和权限治理变成了硬前提。理解这两个方面,才不会把一次实验性终端能力误当成所有 API 接入都能复用的通用协议。\n\n## 参考来源\n\n- [Claude Code v2.1.323 发布说明](https://github.com/anthropics/claude-code/releases/tag/v2.1.323)\n- [Claude Code 官方 Code Mode 文档](https://code.claude.com/docs/en/code-mode)\n- [GitHub issue:Support Code Mode in Agent SDK sessions](https://github.com/anthropics/claude-code/issues/109679)","authorUserId":2,"authorNameSnapshot":"muchacha","status":"published","isPinned":0,"viewCount":0,"commentCount":0,"createdAt":"2026-11-16 02:22:37","updatedAt":"2026-11-16 02:22:38","publishedAt":"2026-11-16 02:22:38"}
RH
RouterHub AI API 中转站导航与平台推荐
博客

Claude Code 的 Code Mode 到底改了什么

Code Mode 把多次工具调用收束为一次 JavaScript 执行,但它只在特定终端、账号、模型和认证条件下成立。

muchacha 2026-11-16 02:22:38

正文

先说结论

Claude Code 2.1.323 引入的 Code Mode,真正改变的不是“多了一个工具”,而是工具调用的编排位置:普通模式下,模型发起一次 Bash、Read 或 Edit,等结果返回后再决定下一步;Code Mode 下,模型先生成一段 JavaScript,由 Claude Code 在当前会话里执行多个工具调用,再把挑选后的结果返回给模型。于是,搜索、筛选、编辑、测试这类有明确数据流的工作,可以在一次代码执行中完成,独立调用可以并行,前一步的结果也能直接决定后一步的参数。

这项能力的适用面比名称看起来窄。官方文档把它定义为实验功能,默认关闭;它要求 Claude Code v2.1.323 或更高版本、原生安装、交互式终端会话、Anthropic API,以及指定模型。通过网关、Amazon Bedrock、Google Cloud 的 Agent Platform、Microsoft Foundry、Agent SDK、-p、VS Code 面板、桌面应用或云会话启动时,不能把设置变量当成开关强行打开。对正在做工具链集成的开发者来说,第一步不是复制示例,而是先确认自己的运行面属于支持矩阵。

调用模型发生了什么变化

普通工具调用的基本流程是“模型决定调用工具,宿主执行工具,模型读取结果”。假设任务是找出所有重试策略文件、修改最大重试次数并运行对应测试,模型可能先调用搜索,再读取文件,再编辑,最后运行测试。每一次工具结果都要回到模型上下文,模型也要重新决定下一次调用。这个流程容易理解,权限判断粒度也比较细,但重复的中间结果会进入上下文,多个互不依赖的读取操作也可能被串起来。

Code Mode 把这层编排改成了模型生成 JavaScript。官方示例使用模板字符串调用命令,并通过 await 把搜索结果交给后续编辑,还可以用 Promise 风格的并发组织多个独立任务。示意代码如下:

const files = await 

  
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    Claude Code 的 Code Mode 到底改了什么 - RouterHub
    
    
    
    
    
    
      
      
      
      
      
      
    
    
    
    
    
      
      
      
      
      
  rg -l \"function retryPolicy\" src`.text();\nconst target = files.trim().split(\"\\n\")[0];\nawait edit(target, \"maxAttempts: 3\", \"maxAttempts: 5\");\n({ edited: target, tests: 

  
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    Claude Code 的 Code Mode 到底改了什么 - RouterHub
    
    
    
    
    
    
      
      
      
      
      
  npm test -- retryPolicy`.nothrow() });\n```\n\n这段代码体现了三个实际变化。第一,筛选逻辑可以在工具结果返回后立即运行,不需要把所有候选文件逐个交给模型再判断。第二,多个工具调用可以在同一段代码里表达依赖关系,只有真正依赖前一步的调用才等待前一步。第三,代码最后可以只返回路径、测试结果或错误摘要,减少把无关的原始输出重新塞回会话。\n\n但这不等于工具权限消失了。Code Mode 仍然在 Claude Code 会话中执行,工具调用仍然受到权限模式和 hook 影响。官方文档特别说明,自动模式下的分类器审查的是整段代码,而不是代码里的每一个工具调用;当代码并发运行、后续调用需要额外判断时,可能出现倒计时权限提示。`PreToolUse` hook 也可能让代码中的某次调用被拒绝或超时。因此,Code Mode 是把编排批量化,不是把审批模型改成无条件放行。\n\n## 先核对支持边界\n\n要判断一台机器是否能使用 Code Mode,可以按下面顺序排查。顺序很重要,因为只设置环境变量而忽略账号和运行面,最终看到的往往只是“功能不可用”,却不知道是哪一层不满足。\n\n第一步确认版本。官方文档要求 Claude Code v2.1.323 或更高版本。可以先运行:\n\n```bash\nclaude --version\n```\n\n如果版本低于要求,先更新;如果使用 `stable` 发布通道仍没有拿到该版本,文档建议等待通道追上,或切换到 `latest`。版本满足后,再在用户设置或 shell 中设置:\n\n```bash\nexport CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1\nclaude\n```\n\n第二步确认认证方式和上游。Code Mode 只对 Anthropic API 工作。官方文档明确列出,网关、自定义 `ANTHROPIC_BASE_URL`、Amazon Bedrock、Google Cloud Agent Platform 和 Microsoft Foundry 都不支持。也就是说,使用中转或企业云适配层时,即使普通 Claude Code 请求可以正常返回,Code Mode 也可能仍然显示不可用。这个区别需要在接入文档里写清楚,不能把“普通消息能通”当成“Code Mode 也兼容”。\n\n第三步确认会话表面。支持的是原生安装的交互式 `claude` 终端会话。`claude -p`、Agent SDK、VS Code 面板、桌面应用、云会话、Remote Control 和后台会话都不在官方支持范围内。GitHub 上已经有开发者请求把 Code Mode 扩展到 Agent SDK 会话,这个 issue 的存在反过来印证了当前文档的边界:把 `CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1` 写进设置文件,并不会让 SDK 客户端获得相同能力。\n\n第四步确认模型和组织设置。官方列出的模型包括 Claude Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.2;组织还可以通过托管设置禁用 Code Mode。HIPAA 配置、零数据保留配置、API key helper、部分遥测设置、Agent Teams、检查工具调用的 mod,以及限制 `REPL` 的工具配置,也可能使它无法启动。遇到不可用时,应该先看会话启动处的原因,或者运行 `/status`,而不是反复重试同一个变量。\n\n## 适合哪些工作流\n\nCode Mode 最有价值的地方是“中间数据需要处理,但最终只需要少量结论”的任务。比如在大型仓库里搜索多个候选文件,再按路径、内容或测试状态筛选;对一组格式相同的文件做相同替换,然后集中运行测试;并行读取多个独立配置,最后只汇总不一致项。这些任务本来就有程序化的控制流,放进一段由模型生成的 JavaScript 后,表达更接近开发者写脚本的方式。\n\n它也适合需要在工具之间传值的任务。普通模式通常需要模型从工具结果中提取文件名、行号或命令输出,再把这些值重新作为下一次工具调用的参数。Code Mode 可以直接在执行环境里保存变量,先用 `rg` 找到目标,再把筛选后的路径传给编辑函数,最后把测试命令的退出状态返回。这里的收益不是“模型变聪明了”,而是把确定性的胶水逻辑交给了执行环境。\n\n不过,涉及高风险副作用时不能只因为调用次数减少就放宽流程。删除文件、修改依赖、提交代码、推送分支、访问网络服务等动作,仍然应该使用明确的权限规则和 hook。Code Mode 让一段代码能够组织多个动作,也让一次分类判断覆盖更大的动作集合;如果组织策略要求每个副作用都由人确认,就不应该把这些操作无差别塞进同一个代码块。实践上可以先允许只读搜索和测试编排,再对编辑、提交和网络访问保留更严格的审批。\n\n## 失败时怎么定位\n\n如果启动后完全没有 Code Mode 提示,先检查版本和变量是否真的进入当前进程。不要只修改一个 shell 配置文件后继续复用旧会话,因为文档要求重新启动会话;也要确认没有在 `--settings` 文件里把同一个变量设成 `0`。如果出现“只支持 Anthropic API”之类的原因,检查 `ANTHROPIC_BASE_URL`、云厂商路由和网关配置;这不是模型名称错误,换模型不会解决认证路径不符合的问题。\n\n如果提示需要从 Anthropic 下载功能设置,检查是否设置了会关闭功能标记获取的变量,例如 `DISABLE_TELEMETRY`。如果提示 OpenTelemetry 已启用,检查 `CLAUDE_CODE_ENABLE_TELEMETRY` 和 `ENABLE_BETA_TRACING_DETAILED`。如果提示与 mod 或 Agent Teams 冲突,则需要关闭相关 mod 或取消 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`,然后启动新会话。官方文档为这些原因分别给出了处理方式,排查时应按实际提示逐项修改,不要把所有设置一次性删除。\n\n如果代码已经开始执行,但某个工具调用被拒绝,重点看 hook 错误。文档把常见情况分成 hook 启动失败、退出状态不允许、HTTP 错误、输出格式无效和执行超时;这些情况下,调用可能在 Code Mode 内部被拒绝,即使普通工具调用原本可以通过。对于明确允许失败后继续的 `command` 或 `http` hook,可以使用 `onFailure: \"continue\"`,但这会改变安全策略,只适用于已经评估过的非关键检查。对权限审批 hook,更稳妥的做法是修复启动路径、超时和输出协议,而不是把所有失败都改成继续。\n\n还要注意长任务。官方文档说明,不能放到后台运行的长时间代码会等待完成,并在十分钟后停止;Code Mode 也不支持 Remote Control 和后台会话。因此,若任务需要长时间构建、持续服务或远程无人值守执行,应该回到普通工具调用、明确的后台命令或适合该场景的 Agent SDK,而不是把 Code Mode 当作通用任务运行器。\n\n## 对工具链设计的影响\n\nCode Mode 给编码代理带来的直接启发,是把工具接口分成“高价值原子动作”和“适合组合的低风险动作”。搜索、读取、解析、测试结果采集这类操作适合被组合,因为它们常常有清晰的输入输出,失败后也容易重新运行。提交、推送、修改权限、调用外部系统这类操作则需要保留更清楚的边界,让审计日志能看出哪一个动作改变了外部状态。\n\n如果团队把 Claude Code 接入内部网关或自建客户端,还应把“不支持 Code Mode”作为能力矩阵的一项,而不是把它隐藏在普通 Anthropic 兼容性描述里。可以在接入检查中分别记录:普通消息是否可用、原生工具调用是否可用、Code Mode 是否可用、Agent SDK 是否可用。官方 issue 已经说明,Code Mode 在终端可用并不代表 Agent SDK 自动获得支持;这类表面相似、运行面不同的能力,必须分别验收。\n\nRouterHub 的[平台目录](/platforms)和[Claude Code 网关排障文章](/blogs/claude-code-tool-search-gateway-fallback)可以作为接入信息的补充入口,但具体能力仍应以 Claude Code 的版本、认证方式和官方文档为准。尤其是中转场景,不能因为一个渠道能转发普通请求,就推断它能提供依赖 Anthropic 原生运行环境的 Code Mode。\n\n归纳起来,Code Mode 的一句话变化是:Claude Code 可以先写一段 JavaScript,在宿主环境里批量、并行、带条件地调用工具,再把压缩后的结果交回模型。它对开发者的实际影响是:适合把重复的工具胶水逻辑程序化,但同时把版本、认证、会话表面、模型和权限治理变成了硬前提。理解这两个方面,才不会把一次实验性终端能力误当成所有 API 接入都能复用的通用协议。\n\n## 参考来源\n\n- [Claude Code v2.1.323 发布说明](https://github.com/anthropics/claude-code/releases/tag/v2.1.323)\n- [Claude Code 官方 Code Mode 文档](https://code.claude.com/docs/en/code-mode)\n- [GitHub issue:Support Code Mode in Agent SDK sessions](https://github.com/anthropics/claude-code/issues/109679)","authorUserId":2,"authorNameSnapshot":"muchacha","status":"published","isPinned":0,"viewCount":0,"commentCount":0,"createdAt":"2026-11-16 02:22:37","updatedAt":"2026-11-16 02:22:38","publishedAt":"2026-11-16 02:22:38"}
      
  
  
    rg -l "function retryPolicy" src`.text();
const target = files.trim().split("\n")[0];
await edit(target, "maxAttempts: 3", "maxAttempts: 5");
({ edited: target, tests: 

  
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    Claude Code 的 Code Mode 到底改了什么 - RouterHub
    
    
    
    
    
    
      
      
      
      
      
      
    
    
    
    
    
      
      
      
      
      
  rg -l \"function retryPolicy\" src`.text();\nconst target = files.trim().split(\"\\n\")[0];\nawait edit(target, \"maxAttempts: 3\", \"maxAttempts: 5\");\n({ edited: target, tests: 

  
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    Claude Code 的 Code Mode 到底改了什么 - RouterHub
    
    
    
    
    
    
      
      
      
      
      
  npm test -- retryPolicy`.nothrow() });\n```\n\n这段代码体现了三个实际变化。第一,筛选逻辑可以在工具结果返回后立即运行,不需要把所有候选文件逐个交给模型再判断。第二,多个工具调用可以在同一段代码里表达依赖关系,只有真正依赖前一步的调用才等待前一步。第三,代码最后可以只返回路径、测试结果或错误摘要,减少把无关的原始输出重新塞回会话。\n\n但这不等于工具权限消失了。Code Mode 仍然在 Claude Code 会话中执行,工具调用仍然受到权限模式和 hook 影响。官方文档特别说明,自动模式下的分类器审查的是整段代码,而不是代码里的每一个工具调用;当代码并发运行、后续调用需要额外判断时,可能出现倒计时权限提示。`PreToolUse` hook 也可能让代码中的某次调用被拒绝或超时。因此,Code Mode 是把编排批量化,不是把审批模型改成无条件放行。\n\n## 先核对支持边界\n\n要判断一台机器是否能使用 Code Mode,可以按下面顺序排查。顺序很重要,因为只设置环境变量而忽略账号和运行面,最终看到的往往只是“功能不可用”,却不知道是哪一层不满足。\n\n第一步确认版本。官方文档要求 Claude Code v2.1.323 或更高版本。可以先运行:\n\n```bash\nclaude --version\n```\n\n如果版本低于要求,先更新;如果使用 `stable` 发布通道仍没有拿到该版本,文档建议等待通道追上,或切换到 `latest`。版本满足后,再在用户设置或 shell 中设置:\n\n```bash\nexport CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1\nclaude\n```\n\n第二步确认认证方式和上游。Code Mode 只对 Anthropic API 工作。官方文档明确列出,网关、自定义 `ANTHROPIC_BASE_URL`、Amazon Bedrock、Google Cloud Agent Platform 和 Microsoft Foundry 都不支持。也就是说,使用中转或企业云适配层时,即使普通 Claude Code 请求可以正常返回,Code Mode 也可能仍然显示不可用。这个区别需要在接入文档里写清楚,不能把“普通消息能通”当成“Code Mode 也兼容”。\n\n第三步确认会话表面。支持的是原生安装的交互式 `claude` 终端会话。`claude -p`、Agent SDK、VS Code 面板、桌面应用、云会话、Remote Control 和后台会话都不在官方支持范围内。GitHub 上已经有开发者请求把 Code Mode 扩展到 Agent SDK 会话,这个 issue 的存在反过来印证了当前文档的边界:把 `CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1` 写进设置文件,并不会让 SDK 客户端获得相同能力。\n\n第四步确认模型和组织设置。官方列出的模型包括 Claude Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.2;组织还可以通过托管设置禁用 Code Mode。HIPAA 配置、零数据保留配置、API key helper、部分遥测设置、Agent Teams、检查工具调用的 mod,以及限制 `REPL` 的工具配置,也可能使它无法启动。遇到不可用时,应该先看会话启动处的原因,或者运行 `/status`,而不是反复重试同一个变量。\n\n## 适合哪些工作流\n\nCode Mode 最有价值的地方是“中间数据需要处理,但最终只需要少量结论”的任务。比如在大型仓库里搜索多个候选文件,再按路径、内容或测试状态筛选;对一组格式相同的文件做相同替换,然后集中运行测试;并行读取多个独立配置,最后只汇总不一致项。这些任务本来就有程序化的控制流,放进一段由模型生成的 JavaScript 后,表达更接近开发者写脚本的方式。\n\n它也适合需要在工具之间传值的任务。普通模式通常需要模型从工具结果中提取文件名、行号或命令输出,再把这些值重新作为下一次工具调用的参数。Code Mode 可以直接在执行环境里保存变量,先用 `rg` 找到目标,再把筛选后的路径传给编辑函数,最后把测试命令的退出状态返回。这里的收益不是“模型变聪明了”,而是把确定性的胶水逻辑交给了执行环境。\n\n不过,涉及高风险副作用时不能只因为调用次数减少就放宽流程。删除文件、修改依赖、提交代码、推送分支、访问网络服务等动作,仍然应该使用明确的权限规则和 hook。Code Mode 让一段代码能够组织多个动作,也让一次分类判断覆盖更大的动作集合;如果组织策略要求每个副作用都由人确认,就不应该把这些操作无差别塞进同一个代码块。实践上可以先允许只读搜索和测试编排,再对编辑、提交和网络访问保留更严格的审批。\n\n## 失败时怎么定位\n\n如果启动后完全没有 Code Mode 提示,先检查版本和变量是否真的进入当前进程。不要只修改一个 shell 配置文件后继续复用旧会话,因为文档要求重新启动会话;也要确认没有在 `--settings` 文件里把同一个变量设成 `0`。如果出现“只支持 Anthropic API”之类的原因,检查 `ANTHROPIC_BASE_URL`、云厂商路由和网关配置;这不是模型名称错误,换模型不会解决认证路径不符合的问题。\n\n如果提示需要从 Anthropic 下载功能设置,检查是否设置了会关闭功能标记获取的变量,例如 `DISABLE_TELEMETRY`。如果提示 OpenTelemetry 已启用,检查 `CLAUDE_CODE_ENABLE_TELEMETRY` 和 `ENABLE_BETA_TRACING_DETAILED`。如果提示与 mod 或 Agent Teams 冲突,则需要关闭相关 mod 或取消 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`,然后启动新会话。官方文档为这些原因分别给出了处理方式,排查时应按实际提示逐项修改,不要把所有设置一次性删除。\n\n如果代码已经开始执行,但某个工具调用被拒绝,重点看 hook 错误。文档把常见情况分成 hook 启动失败、退出状态不允许、HTTP 错误、输出格式无效和执行超时;这些情况下,调用可能在 Code Mode 内部被拒绝,即使普通工具调用原本可以通过。对于明确允许失败后继续的 `command` 或 `http` hook,可以使用 `onFailure: \"continue\"`,但这会改变安全策略,只适用于已经评估过的非关键检查。对权限审批 hook,更稳妥的做法是修复启动路径、超时和输出协议,而不是把所有失败都改成继续。\n\n还要注意长任务。官方文档说明,不能放到后台运行的长时间代码会等待完成,并在十分钟后停止;Code Mode 也不支持 Remote Control 和后台会话。因此,若任务需要长时间构建、持续服务或远程无人值守执行,应该回到普通工具调用、明确的后台命令或适合该场景的 Agent SDK,而不是把 Code Mode 当作通用任务运行器。\n\n## 对工具链设计的影响\n\nCode Mode 给编码代理带来的直接启发,是把工具接口分成“高价值原子动作”和“适合组合的低风险动作”。搜索、读取、解析、测试结果采集这类操作适合被组合,因为它们常常有清晰的输入输出,失败后也容易重新运行。提交、推送、修改权限、调用外部系统这类操作则需要保留更清楚的边界,让审计日志能看出哪一个动作改变了外部状态。\n\n如果团队把 Claude Code 接入内部网关或自建客户端,还应把“不支持 Code Mode”作为能力矩阵的一项,而不是把它隐藏在普通 Anthropic 兼容性描述里。可以在接入检查中分别记录:普通消息是否可用、原生工具调用是否可用、Code Mode 是否可用、Agent SDK 是否可用。官方 issue 已经说明,Code Mode 在终端可用并不代表 Agent SDK 自动获得支持;这类表面相似、运行面不同的能力,必须分别验收。\n\nRouterHub 的[平台目录](/platforms)和[Claude Code 网关排障文章](/blogs/claude-code-tool-search-gateway-fallback)可以作为接入信息的补充入口,但具体能力仍应以 Claude Code 的版本、认证方式和官方文档为准。尤其是中转场景,不能因为一个渠道能转发普通请求,就推断它能提供依赖 Anthropic 原生运行环境的 Code Mode。\n\n归纳起来,Code Mode 的一句话变化是:Claude Code 可以先写一段 JavaScript,在宿主环境里批量、并行、带条件地调用工具,再把压缩后的结果交回模型。它对开发者的实际影响是:适合把重复的工具胶水逻辑程序化,但同时把版本、认证、会话表面、模型和权限治理变成了硬前提。理解这两个方面,才不会把一次实验性终端能力误当成所有 API 接入都能复用的通用协议。\n\n## 参考来源\n\n- [Claude Code v2.1.323 发布说明](https://github.com/anthropics/claude-code/releases/tag/v2.1.323)\n- [Claude Code 官方 Code Mode 文档](https://code.claude.com/docs/en/code-mode)\n- [GitHub issue:Support Code Mode in Agent SDK sessions](https://github.com/anthropics/claude-code/issues/109679)","authorUserId":2,"authorNameSnapshot":"muchacha","status":"published","isPinned":0,"viewCount":0,"commentCount":0,"createdAt":"2026-11-16 02:22:37","updatedAt":"2026-11-16 02:22:38","publishedAt":"2026-11-16 02:22:38"}
      
  
  
    npm test -- retryPolicy`.nothrow() });

这段代码体现了三个实际变化。第一,筛选逻辑可以在工具结果返回后立即运行,不需要把所有候选文件逐个交给模型再判断。第二,多个工具调用可以在同一段代码里表达依赖关系,只有真正依赖前一步的调用才等待前一步。第三,代码最后可以只返回路径、测试结果或错误摘要,减少把无关的原始输出重新塞回会话。

但这不等于工具权限消失了。Code Mode 仍然在 Claude Code 会话中执行,工具调用仍然受到权限模式和 hook 影响。官方文档特别说明,自动模式下的分类器审查的是整段代码,而不是代码里的每一个工具调用;当代码并发运行、后续调用需要额外判断时,可能出现倒计时权限提示。PreToolUse hook 也可能让代码中的某次调用被拒绝或超时。因此,Code Mode 是把编排批量化,不是把审批模型改成无条件放行。

先核对支持边界

要判断一台机器是否能使用 Code Mode,可以按下面顺序排查。顺序很重要,因为只设置环境变量而忽略账号和运行面,最终看到的往往只是“功能不可用”,却不知道是哪一层不满足。

第一步确认版本。官方文档要求 Claude Code v2.1.323 或更高版本。可以先运行:

claude --version

如果版本低于要求,先更新;如果使用 stable 发布通道仍没有拿到该版本,文档建议等待通道追上,或切换到 latest。版本满足后,再在用户设置或 shell 中设置:

export CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1
claude

第二步确认认证方式和上游。Code Mode 只对 Anthropic API 工作。官方文档明确列出,网关、自定义 ANTHROPIC_BASE_URL、Amazon Bedrock、Google Cloud Agent Platform 和 Microsoft Foundry 都不支持。也就是说,使用中转或企业云适配层时,即使普通 Claude Code 请求可以正常返回,Code Mode 也可能仍然显示不可用。这个区别需要在接入文档里写清楚,不能把“普通消息能通”当成“Code Mode 也兼容”。

第三步确认会话表面。支持的是原生安装的交互式 claude 终端会话。claude -p、Agent SDK、VS Code 面板、桌面应用、云会话、Remote Control 和后台会话都不在官方支持范围内。GitHub 上已经有开发者请求把 Code Mode 扩展到 Agent SDK 会话,这个 issue 的存在反过来印证了当前文档的边界:把 CLAUDE_CODE_EXPERIMENTAL_CODE_MODE=1 写进设置文件,并不会让 SDK 客户端获得相同能力。

第四步确认模型和组织设置。官方列出的模型包括 Claude Opus 5.5、Sonnet 5.5、Haiku 5.5 和 Fable 5.2;组织还可以通过托管设置禁用 Code Mode。HIPAA 配置、零数据保留配置、API key helper、部分遥测设置、Agent Teams、检查工具调用的 mod,以及限制 REPL 的工具配置,也可能使它无法启动。遇到不可用时,应该先看会话启动处的原因,或者运行 /status,而不是反复重试同一个变量。

适合哪些工作流

Code Mode 最有价值的地方是“中间数据需要处理,但最终只需要少量结论”的任务。比如在大型仓库里搜索多个候选文件,再按路径、内容或测试状态筛选;对一组格式相同的文件做相同替换,然后集中运行测试;并行读取多个独立配置,最后只汇总不一致项。这些任务本来就有程序化的控制流,放进一段由模型生成的 JavaScript 后,表达更接近开发者写脚本的方式。

它也适合需要在工具之间传值的任务。普通模式通常需要模型从工具结果中提取文件名、行号或命令输出,再把这些值重新作为下一次工具调用的参数。Code Mode 可以直接在执行环境里保存变量,先用 rg 找到目标,再把筛选后的路径传给编辑函数,最后把测试命令的退出状态返回。这里的收益不是“模型变聪明了”,而是把确定性的胶水逻辑交给了执行环境。

不过,涉及高风险副作用时不能只因为调用次数减少就放宽流程。删除文件、修改依赖、提交代码、推送分支、访问网络服务等动作,仍然应该使用明确的权限规则和 hook。Code Mode 让一段代码能够组织多个动作,也让一次分类判断覆盖更大的动作集合;如果组织策略要求每个副作用都由人确认,就不应该把这些操作无差别塞进同一个代码块。实践上可以先允许只读搜索和测试编排,再对编辑、提交和网络访问保留更严格的审批。

失败时怎么定位

如果启动后完全没有 Code Mode 提示,先检查版本和变量是否真的进入当前进程。不要只修改一个 shell 配置文件后继续复用旧会话,因为文档要求重新启动会话;也要确认没有在 --settings 文件里把同一个变量设成 0。如果出现“只支持 Anthropic API”之类的原因,检查 ANTHROPIC_BASE_URL、云厂商路由和网关配置;这不是模型名称错误,换模型不会解决认证路径不符合的问题。

如果提示需要从 Anthropic 下载功能设置,检查是否设置了会关闭功能标记获取的变量,例如 DISABLE_TELEMETRY。如果提示 OpenTelemetry 已启用,检查 CLAUDE_CODE_ENABLE_TELEMETRY 和 ENABLE_BETA_TRACING_DETAILED。如果提示与 mod 或 Agent Teams 冲突,则需要关闭相关 mod 或取消 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS,然后启动新会话。官方文档为这些原因分别给出了处理方式,排查时应按实际提示逐项修改,不要把所有设置一次性删除。

如果代码已经开始执行,但某个工具调用被拒绝,重点看 hook 错误。文档把常见情况分成 hook 启动失败、退出状态不允许、HTTP 错误、输出格式无效和执行超时;这些情况下,调用可能在 Code Mode 内部被拒绝,即使普通工具调用原本可以通过。对于明确允许失败后继续的 command 或 http hook,可以使用 onFailure: "continue",但这会改变安全策略,只适用于已经评估过的非关键检查。对权限审批 hook,更稳妥的做法是修复启动路径、超时和输出协议,而不是把所有失败都改成继续。

还要注意长任务。官方文档说明,不能放到后台运行的长时间代码会等待完成,并在十分钟后停止;Code Mode 也不支持 Remote Control 和后台会话。因此,若任务需要长时间构建、持续服务或远程无人值守执行,应该回到普通工具调用、明确的后台命令或适合该场景的 Agent SDK,而不是把 Code Mode 当作通用任务运行器。

对工具链设计的影响

Code Mode 给编码代理带来的直接启发,是把工具接口分成“高价值原子动作”和“适合组合的低风险动作”。搜索、读取、解析、测试结果采集这类操作适合被组合,因为它们常常有清晰的输入输出,失败后也容易重新运行。提交、推送、修改权限、调用外部系统这类操作则需要保留更清楚的边界,让审计日志能看出哪一个动作改变了外部状态。

如果团队把 Claude Code 接入内部网关或自建客户端,还应把“不支持 Code Mode”作为能力矩阵的一项,而不是把它隐藏在普通 Anthropic 兼容性描述里。可以在接入检查中分别记录:普通消息是否可用、原生工具调用是否可用、Code Mode 是否可用、Agent SDK 是否可用。官方 issue 已经说明,Code Mode 在终端可用并不代表 Agent SDK 自动获得支持;这类表面相似、运行面不同的能力,必须分别验收。

RouterHub 的平台目录和Claude Code 网关排障文章可以作为接入信息的补充入口,但具体能力仍应以 Claude Code 的版本、认证方式和官方文档为准。尤其是中转场景,不能因为一个渠道能转发普通请求,就推断它能提供依赖 Anthropic 原生运行环境的 Code Mode。

归纳起来,Code Mode 的一句话变化是:Claude Code 可以先写一段 JavaScript,在宿主环境里批量、并行、带条件地调用工具,再把压缩后的结果交回模型。它对开发者的实际影响是:适合把重复的工具胶水逻辑程序化,但同时把版本、认证、会话表面、模型和权限治理变成了硬前提。理解这两个方面,才不会把一次实验性终端能力误当成所有 API 接入都能复用的通用协议。

参考来源