开源Runtime：让Codex和Claude Code的Subagent工作流真正可控

最近做 AI 编程助手落地的人，几乎都会撞上同一个问题：Codex 和 Claude Code 这类工具，单线程跑简单任务挺顺手，一旦进入多文件改造、跨模块重构、需要并行验证的真实项目，就明显吃力。你让它“先改 A 模块，再根据结果改 B 模块”，它经常改着改着就丢了上下文，或者在一个子任务里反复绕圈。

很多人第一反应是“模型不够聪明”，于是去换更强的模型。但从工程视角看，真正卡脖子的往往不是模型，而是工具的执行框架——官方客户端把任务链路写死了，你很难干预子任务的拆分、调度、上下文传递和结果回收。

这也是最近“开源 runtime”这个方向突然热起来的原因。所谓 better Codex and Claude subagent experience，并不是又出了一款聊天客户端，而是有人在尝试把 Agent 的“运行时”从黑盒里解放出来。这篇文章就从实际使用者的角度，拆解这个思路到底解决了什么问题、运行时在 Agent 体系里处于什么位置、以及你自己怎么基于这类项目搭出一套可维护的 subagent 工作流。

1. 先搞清楚大家吐槽的 subagent 体验到底是什么

如果你没有深度用过 Codex 或 Claude Code，可能觉得“subagent 体验不好”是一句很虚的话。这里先用一个最常见的真实场景说明。

假设你有一个 Spring Boot 项目，里面有 20 个接口类、10 个数据库表、还有一堆历史遗留的 XML 配置。你给 Codex 下了一个任务：“把用户模块从单库逻辑改造成读写分离，老逻辑保留兼容，并补充单元测试。”

这个任务在 IDE 里看起来是一句话，但对 Agent 而言，它需要拆成多个子任务：

• 先扫描用户模块的代码结构；
• 确定哪些 DAO 走了写库，哪些走了读库；
• 修改数据源路由配置；
• 改写 Service 层注解或事务边界；
• 生成或修改测试用例；
• 最后跑一遍全部相关测试，确认没有污染其他模块。

问题来了：官方客户端在执行这种长链路任务时，如果某个子任务失败，经常直接整体报错，或者模型把“失败原因”理解错，在错误路径上反复重试。你没办法只重跑“改数据源配置”这一步，也没办法在中间注入你自己的约束，比如“不要动 order 模块的代码”。

这就是 subagent 体验差的核心：缺少可控的、可观测的、可编排的运行时。模型本身不是不能写代码，而是没有一个好的执行环境来管理它的每一步动作。

从架构角度讲，现在的多 Agent 设计里，主流模式是“主从模式”。主 Agent 负责任务意图理解和全局规划，把大任务拆成若干 step，然后分发给 subagent 去执行。最新设计里出现了一个很关键的转变：本质上将 subagent 视为一种另类的 tool 进行调用。也就是说，主 Agent 不关心 subagent 内部怎么干，只关心它的输入输出契约是什么、执行是否成功、结果是否可用。

这个转变意味着，只要你能控制 subagent 的调度和通信方式，你就能极大改善整体的任务完成率。而“控制调度和通信方式”这件事，恰恰是 runtime 该干的活。

2. Runtime 在 Agent 体系里扮演什么角色

“Runtime”这个词很容易被误解。有人一看到“Open-sourced runtime”，以为是又一个容器运行时，还有人以为是类似 Java 虚拟机的东西。放在 Agent 场景里，runtime 更准确的定位是：管理 Agent 生命周期、工具调用、子任务调度、上下文传递、错误恢复的一组执行基础设施。

类比一下。你写后端服务时，不会自己用 socket 去实现 HTTP 协议，而是用 Tomcat、Undertow 这类 Web 容器，它帮你处理连接、线程池、请求分发、超时控制。Agent 也一样。模型是一颗“大脑”，但它不能自己去终端执行命令、不能自己翻文件、不能自己决定何时重试。它需要一套基础设施来承载这些动作。

Codex 和 Claude Code 的官方实现里，这套基础设施是内嵌的。好处是开箱即用，坏处是使用者无法干预。当模型被内置调度器带着走时，你只能接受它的决策，哪怕你知道它在某个子任务上方向错了。

开源 runtime 的思路，就是把这一层抽出来，做成可替换、可编程、可观测的组件。你能看到当前 Agent 在执行哪个子任务，能手动终止跑偏的子任务，能让某个固定流程（比如“先跑 lint 再提交代码”）强制插入到调度逻辑里。这对于做工程化落地的团队来说，价值远大于换一个更强但依然黑盒的模型。

从社区讨论看，当前比较有代表性的工具方向有三类：

• 一类是重写执行循环，给 Codex CLI 或 Claude Code 增加外部驱动能力，让它们可以作为 subagent 被调用；
• 一类是提供进程级和会话级的隔离，让多个子任务并行时不会互相污染文件状态；
• 还有一类是强化事件流和日志输出，把 Agent 内部决策暴露成可订阅的事件，方便外部系统接入监控和告警。

这些方向并不互斥。很多开源 runtime 项目是三者兼做，只是侧重点不同。

3. 开源 Runtime 的核心价值：让 Subagent 变成可编程组件

前面提到“subagent 本质上是 tool 调用”，听起来只是视角变化，但落到工程上，会带来四个非常实际的变化。

第一，可替换性。如果 subagent 只是“另一个 tool”，那么主 Agent 就可以根据任务类型，选择不同的 subagent 后端：简单文件修改任务交给 Codex，复杂架构分析任务交给 Claude Code，甚至可以让同一个主 Agent 同时调用多个不同模型家族的 subagent，按需取长补短。这在官方一体化客户端里很难实现，因为官方工具通常只绑定单一模型生态。

第二，可编程的上下文注入。官方客户端的 prompt 构造逻辑是封闭的。开源 runtime 允许你在 subagent 被唤起前，注入项目规范、代码风格约束、禁止修改文件列表、必须遵守的测试命令等上下文。也就是说，你可以把团队的工程规范固化到 runtime 层，而不是每次都在任务描述里重复强调。

第三，子任务级错误恢复。没有 runtime 时，一个子任务失败，整个任务链可能垮掉。有了 runtime，主 Agent 可以捕获 subagent 的退出码和输出摘要，然后决定是重试、换一个 subagent、还是带着错误信息继续执行后续步骤。很多看起来“Agent 变聪明了”的体验，其实是多了这一层容错机制。

第四，可观测性。开源 runtime 一般会把事件流暴露出来，比如 subagent_started、tool_call_finished、context_window_warning 等。有了这些事件，你就能在 CI/CD 里做 Agent 任务的监控，知道哪一步耗时最长、哪个工具调用失败率最高。这也是官方客户端当前最欠缺的能力。

需要强调的一点是，这套思路的关键并不是“用开源工具替代官方客户端”，而是把官方客户端变成服务端能力，把决策权收回到你的工作流里。国内开发者常说的“套壳”，在 Agent runtime 这里有了完全不同的含义——壳本身决定了任务执行的上限。

4. 为什么说主从模式是当前多 Agent 设计的最优解

看最新的多 Agent 设计讨论，一个高频共识是：主从模式远比“多个 Agent 自由协作”可靠。所谓主从模式，就是有一个主 Agent（orchestrator）负责任务规划和结果验收，多个 subagent 只负责执行特定子任务，相互之间不直接通信，所有上下文都通过主 Agent 中转。

这种模式在工程上几乎完美契合 code review 和批量重构的诉求，原因有三点。

首先，上下文可控。自由协作模式下，Agent A 和 Agent B 各自维护一份上下文，彼此不知道对方改了什么，很容易产生冲突。主从模式里，主 Agent 持有全局上下文，subagent 每次只拿到最小必要上下文，做完就交回结果。这样既省 token，又减少幻觉。

其次，权限可控。主 Agent 可以把 subagent 限定在特定目录、特定文件甚至特定函数内。subagent 没有权限碰全局配置，即使它产生错误修改，影响面也有限。这在命令执行、文件写入这类高风险操作上尤其重要。

最后，责任可追溯。主从模式的日志天然呈现一棵树：主任务拆成哪些子任务，每个子任务由谁执行、耗时多久、成功还是失败，全部有记录。相比单个 Agent 把几十步动作混在一起的大日志，这种结构化日志对排错友好得多。

如果你看过一些开源 runtime 的调度器实现，会发现它本质上就是一个状态机：plan → dispatch → collect → verify → replan。这个状态机把 Agent 从“一次性的对话补全”变成了“可重复执行的工作流节点”。这也是为什么现在很多人开始把 runtime 层称为“Agent 操作系统”——它管的是进程、资源、调度和生命周期，模型只是其中一个计算单元。

5. 环境准备与基础安装

这类开源 runtime 的形态变化很快，不同项目安装方式差异很大。这里不针对某个具体版本写死命令，而是梳理一套共性的安装和验证路径，你拿到任何一个同类项目时都能快速上手。

无论用哪个项目，通常都需要准备以下环境：

• 操作系统：macOS 或 Linux 最省心。Windows 可以用 WSL2，但涉及进程管理和文件监听时，行为可能和原生环境有差异；
• Node.js：大部分 runtime 基于 Node 或 Bun 实现，建议安装 Node.js 18 以上版本；
• Python 3.10 以上：Claude Code 的运行依赖 Python，部分 runtime 也会用 Python 做脚本扩展；
• Git：拉取项目、查看源码、管理补丁都需要；
• Codex CLI 或 Claude Code：需要先安装并登录官方账号，runtime 通常通过命令行的方式调用这两个工具；
• API Key 或官方登录凭证：如果使用第三方模型网关，还需要准备对应的 Base URL 和 Key。

基础检查命令如下：

node --version npm --version python3 --version git --version codex --version claude --version

如果你是第一次安装 Claude Code，通常会卡在“无法将‘claude’项识别为 cmdlet、函数、脚本文件”这个问题上。在 Windows 上这多半是全局路径没配好。以 macOS 或 Linux 为例，安装完官方 CLI 后，需要确认二进制路径已经加入 PATH：

npm install -g @anthropic-ai/claude-code export PATH="$PATH:$(npm prefix -g)/bin" source ~/.zshrc

Codex 的安装也类似。安装完成后，先单独测试两个 CLI 能否独立完成任务，再接入 runtime。如果 CLI 本身无法正常工作，不要继续排查 runtime。

codex "输出 hello" claude "输出 hello"

跑通这两个命令后，说明底层执行环境没有问题。接下来再克隆你感兴趣的开源 runtime 项目：

git clone <project-runtime-repo> cd <project-dir> npm install cp .env.example .env

在 .env 文件里，一般需要配置的变量是 Codex CLI 路径、Claude CLI 路径、工作目录白名单、默认模型、事件回调地址等。注意，不要把 API Key 明文提交到 Git 仓库。

6. 核心功能拆解：配置调度规则和上下文策略

安装完成后，最值得花时间研究的是配置文件，而不是源码。因为这类项目好不好用，基本取决于你能否把调度规则和上下文策略配明白。

以常见的 runtime 配置为例，会涉及几个核心字段。第一个是 agent 注册表，也就是声明当前 runtime 能唤起哪些 subagent。例如：

{ "agents": { "codex": { "command": "codex", "cwd": "/workspace/repo", "timeout": 300000, "env": { "OPENAI_API_KEY": "${CODEX_API_KEY}" } }, "claude": { "command": "claude", "cwd": "/workspace/repo", "timeout": 300000, "env": { "ANTHROPIC_API_KEY": "${CLAUDE_API_KEY}" } } } }

这里的关键参数是 timeout。subagent 执行 task 时，如果超过 timeout 还没有返回，runtime 应该主动终止并回到主 Agent，而不是无限等待。实际使用中，代码生成类任务往往会超过模型默认的 max_tokens，但进程级 timeout 必须由你掌控。

另一个重要配置是目录白名单。也就是 runtime 只允许 subagent 在哪些目录下执行写操作。假设一个微服务仓库里包含多个服务，你想让 Claude 只改 user-service，那就可以这样限制：

{ "permissions": { "read": ["/workspace/repo"], "write": ["/workspace/repo/user-service"] } }

这样即使模型在生成代码时“想”去改其它模块，runtime 也会在文件系统层直接拒绝，而不是等代码生成完再靠 review 去发现问题。对团队协作来说，这一条比任何 system prompt 都管用。

context 策略是更进阶的能力。开源 runtime 允许你定义 subagent 上线文应该包含哪些内容。比如，每次启动 subagent 前，自动读取项目根的 CLAUDE.md 或 AGENTS.md，注入代码规范说明：

{ "context_strategy": { "auto_include": ["./AGENTS.md", "./docs/architecture.md"], "max_context_tokens": 16000 } }

我建议在 AGENTS.md 里维护一份精简的团队规范，比如“禁止修改 pom.xml 版本号”“运行测试前必须先执行 mvn compile”“不要使用 System.out 打印日志”这类规则。比你在每个 prompt 里重复写一百遍要可靠得多，因为 runtime 会在每次 subagent 启动时自动注入，不会遗漏。

7. 一个完整示例：用 Runtime 驱动 Codex 完成代码重构

下面用一个接近真实工作的场景，对比“直接用 Codex CLI”和“通过 runtime 驱动 Codex subagent”的差别。

目标任务：在某个 Java 项目中，把UserService里所有直接操作JdbcTemplate的代码替换为基于UserMapper的 MyBatis 写法，并且不影响OrderService的实现。

先看直接用官方 Codex CLI 的写法：

codex "重构 UserService，把 JdbcTemplate 改成 UserMapper，保持 OrderService 不动"

这条命令会启动一个交互式会话，Codex 自己决定改哪些文件。执行过程中，它会读取整个项目结构，然后按照自己的理解修改。它确实可能完成任务，但你无法保证它不会顺手把OrderService里某些引用的方法签名改掉，也无法限制它只在user-service模块内操作。

再看通过 runtime 的写法。你可以在工作流文件里描述更精确的任务边界：

workflow: name: user-module-refactor agent: codex pre_steps: - git checkout -b refactor/user-service-mybatis dispatch: prompt: | 重构 user-service 模块中的 UserService， 将 JdbcTemplate 直连操作替换为 UserMapper。 约束： 1. 禁止修改 order-service 模块任何文件； 2. 不要改变 UserController 对外暴露的接口签名； 3. 完成后执行 mvn -pl user-service test； 4. 如果测试失败，汇总错误信息并回滚本次修改。 allowed_dirs: - /workspace/repo/user-service - /workspace/repo/user-service/src/test post_steps: - git diff --stat

当你启动这个 workflow 时，runtime 会先把任务拆成“分析 UserService 结构→扫描数据库访问点→生成 Mapper 代码→修改 Service→执行测试”几个阶段，然后交给 Codex 作为 subagent 去执行。

关键在于：runtime 不只是把 prompt 透传给模型，还会在上游拦截操作。如果 Codex 尝试访问order-service目录，runtime 的allowed_dirs规则会直接拒绝；如果 Codex 在子任务里没有运行测试就声称完成，runtime 的 post_steps 会强制补齐验证环节。

假设 Codex 生成的 Mapper 代码有误，测试阶段必然失败。此时 runtime 不会简单地把整个任务标记失败，而会把测试错误输出作为上下文的一部分，重新唤起 Codex 的“修复子任务”。修复子任务仍然遵守目录白名单约束，不会越界修改。

运行命令可能长这样：

agent-runtime run workflow.yaml --target ./repo

看到最终输出时，你会得到一个结构化报告：

Workflow finished. Subtask summary: 1. analysis: SUCCESS (2 files read) 2. codegen: SUCCESS (3 files written) 3. build: FAILED (3 test cases failed) 4. fix: SUCCESS (1 file modified) 5. final-test: SUCCESS (all tests passed) Diff scope: modified: user-service/src/main/java/.../UserService.java modified: user-service/src/main/java/.../UserMapper.java modified: user-service/src/test/java/.../UserServiceTest.java

这个报告的价值在于：你可以直接知道“这次改动经历了哪些波折”，而不是面对一个笼统的成功或失败信息。如果 fix 阶段反复失败，那大概率是模型对某个业务逻辑理解有误，你应该介入检查而不是让它无限重试。

8. 事件流与日志：Subagent 运行可观测性的关键

代码生成工具最大的问题之一，是过程不透明。开源 runtime 在这方面比官方客户端有优势，因为它把 Agent 的关键动作发布成事件流。你可以通过订阅这些事件，实时掌握系统状态，甚至在事件里触发自己的逻辑。

一个典型的事件订阅实现，注意这段代码用于演示事件机制，实际运行时项目可能用不同语言和框架实现：

// file: events/logging-listener.ts import { RuntimeClient } from '@your-runtime/client'; const client = new RuntimeClient({ endpoint: process.env.RUNTIME_ENDPOINT }); client.on('subagent.started', (event) => { console.log(`[${new Date().toISOString()}] subagent ${event.agent} started`); }); client.on('subagent.step', (event) => { console.log(`[${new Date().toISOString()}] step ${event.stepName}`); console.log(` status: ${event.stepStatus}`); console.log(` tools used: ${event.toolCalls.join(', ')}`); }); client.on('subagent.failed', (event) => { console.error(`subagent failed: ${event.errorMessage}`); // 这里可以接入你的企业微信、钉钉或者飞书机器人告警 }); client.on('dispatch.paused', (event) => { console.log(`dispatch paused at ${event.reason}`); });

如果你在真实项目里落地这个监听，会发现非常有用的一个应用场景：超时和不合理循环的发现。有时候模型会陷入“改代码→跑测试→出错→再改”的循环，每次循环都要消耗几分钟。通过事件流，你可以在 dispatch 循环超过 N 次时，主动通知维护者介入。

let loopCount = 0; client.on('subagent.step', (event) => { if (event.stepName === 'build' && event.stepStatus === 'running') { loopCount += 1; if (loopCount > 3) { console.warn('build step retried more than 3 times, possible infinite loop'); client.control.pause(); } } });

可观测性的收益并不只是“方便看日志”，它能让 Agent 执行从“不可预测的黑盒”变成“可以调度的分布式任务”。这对生产环境落地是非常关键的一道闸门。你会很自然地希望每个 Codex subagent 跑完代码后，自动把 diff 发到代码评审系统；或者每次 Claude subagent 需要访问敏感配置时，通知管理员审批。这些能力都依赖事件流。

9. 常见问题与排查思路

开源 runtime 项目迭代很快，遇到的问题也五花八门。下面从社区高频问题里筛选出最有共性的几个，按“现象→原因→排查→解决”的格式整理成一张速查表。

这里最常被忽略的一条是：runtime 调用官方 CLI 时，两者之间可能存在版本兼容问题。如果你使用的是最新版 Claude Code，但 runtime 项目已经停更半年，可能出现参数解析错误或指令不兼容。我的建议是：在 CI 环境里固定 Codex 和 Claude Code 的版本号，不要每次都用 latest。官方客户端更新频繁，而 runtime 的适配往往有滞后。

10. 在工程团队落地的四条建议

第一，小步试点，先跑通一个非核心模块。不要第一个任务就让 runtime 去重构整个旧系统。选一个业务逻辑不复杂、测试覆盖较全的模块，用 runtime 跑一个可验证的小任务。观察任务完成率、耗时、上下文消耗，再逐步扩大范围。

第二，把 runtime 放在 CI 环境，而不是本地 IDE。很多人误以为 Agent runtime 是 IDE 插件，一开始就在本地跑。但正式落地时，CI 环境的收益远大于本地。因为 CI 环境有干净的临时目录、确定性的环境变量、权限可控的脚本入口，还有执行记录。你可以在 CI 里为每个任务创建独立分支，跑完自动建 Merge Request。这是团队协作的最佳姿势。

第三，维护一份高质量的 AGENTS.md 文件。runtime 再强，也只是执行框架，它执行什么，取决于你给它什么上下文。花时间写一份清晰的规范文件，把“这个项目的模块边界”“代码风格偏好”“禁止修改清单”“测试命令”组织好。它能显著提高 subagent 首次执行成功率。团队有人总结过一条规律：AGENTS.md 写得模糊时，Agent 的发挥像实习生；写清楚后，基本像熟练工。

第四，为所有高风险操作设置“人工审批节点”。例如，subagent 如果要执行 git push 到主干、修改数据库迁移文件、删除文件等动作，应该触发审批事件。部分 runtime 的客户端库已经提供dispatch.paused这类事件，你可以对接企业内部审批系统。这个习惯能帮你避免很多麻烦。

11. 适用边界与选型判断

写到这里，有必要泼一盆冷水：runtime 不是万能的，它有明确适用边界。

适合用 runtime 的场景，是任务边界清楚、需要可重复执行、有回归验证手段的工程任务。比如批量接口改造、代码风格统一、存量代码迁移、单测补充等等。这些任务本质上适合脚本化，而 runtime 其实是在“脚本”之上加了一层智能拆解和执行控制。

不适合用 runtime 的场景，是需求本身模糊、上下文极度依赖实时对话的项目。比如产品一开始只有一句“把这个页面做好看点”，你怎么在 runtime 里定义 subagent 的验收标准？这种任务更适合在交互式 CLI 里一步步讨论着做。

选型时也不要被“开源”两个字迷惑。开源项目的问题往往不在功能，而在维护热度。有的 runtime 仓库很新，issues 丰富，但可能三个月后无人维护。建议观察三个指标：最近 commit 时间、issue 响应速度、官方文档是否覆盖了升级迁移路径。如果你的团队会改动 runtime 源码，还要考察项目的代码结构和测试覆盖度。

如果你只是个人开发者，想改善日常的 Codex 和 Claude Code 体验，不一定要马上搭一套完整 runtime。可以先从自定义脚本开始，把固定的 pre_steps 和 post_steps 用 shell 脚本封装起来，手动驱动官方 CLI。当你发现脚本里的分支逻辑越来越多，再引入专门的开源 runtime 也不迟。这套演进路径，比一上来就追求“全自动多 Agent”，要稳妥得多。

另外，模型和 API 适配也是需要考虑的变数。Codex 和 Claude 的官方 API 都在快速迭代，某些模型名和参数隔几个月就会变化。如果你的 runtime 运行在比较关键的任务链路上，建议把模型名、API 版本号这些配置全部抽到环境变量里，升级时只需要改一处。社区里经常有人遇到 “the model is not supported when using codex with a” ，本质上就是配置版本没跟上服务端更新。这个问题在 runtime 环境里会更容易发生，因为同一套 runtime 可能调度不同厂商的模型，某个模型下线或改名后，调度配置不会自动更新。

从更宏观的视野看，Codex、Claude 这类工具的下一轮竞争，很可能不会再停留在“谁的代码生成质量高一点”，而是切换到“谁的运行时更能承载复杂工程任务”。模型的代码能力会越来越趋同，但能不能让 Agent 在大型仓库里按团队规范稳定地产出，能不能让每次改动都可审计、可回滚，这才是工程化落地的分水岭。开源 runtime 项目的涌现，恰好说明这个阶段已经来了。