Lego-RL 是一套面向 Coding Agent 的强化学习训练框架，也是 LegoX 系列的最新工作，由华为与香港中文大学联合团队完成。

论文：https://arxiv.org/abs/2608.17393
代码：https://github.com/LegoX/Lego-RL
文档：https://lego-rl.pages.dev
模型：https://huggingface.co/collections/Lego-X/lego-rl
数据：https://huggingface.co/datasets/Lego-X/Lego-RL-2699
主页：https://legox.net

TLDR

Coding Agent 强化学习，难点在哪里？ harness 会在运行时改写对话历史，模型可能绕过任务直接拿分；训练一旦出问题，我们还得先判断究竟是策略退化，还是 Infra 故障。Lego-RL 从三个方面解决这些问题：Faithful（保真优化）、Reliable（可靠执行）和 Observable（可观测训练）。

Lego-RL 不需要修改 OpenHands SDK、Claude Code 或 OpenCode 的任何一行代码，就能把它们直接接入强化学习，基于 Qwen3.5-35B-A3B，三个 harness 上的 SWE-bench Verified 分数分别从 64.0 / 62.4 / 57.2 提升到 70.4 / 68.2 / 66.6。

为什么要在原生 Agent harness 上训练 Coding Agent？

常见做法是先把 Agent 改造成训练框架能接受的样子：重写初始化，换成框架自带的工具集，再补一套终止逻辑。这样确实能训，但优化目标也变了。策略是在“改造后的控制流”里学到最优解，放回用户真正部署的 harness 后，未必还一样好用。

Harness 的影响到底有多大？把同一份 Qwen3.5-35B-A3B 权重放进三个 harness，在同一套 SWE-bench Verified 上，分数分别是 64.0 / 62.4 / 57.2。只换 harness，差距就接近 7 分，甚至超过不少后训练方法本身带来的增益。

SWE-bench Verified（%），统一配置实测：temperature 0.7、200 turns、200k context。

Lego-RL 通过保持训推的 harness 一致，在三个 harness 上都拿到最高分。 这比下一代 Qwen3.6-35B-A3B 分别高 3.0 / 4.8 / 6.0 分。作为对照，Qwen3.6 换代本身带来的提升只有 3.4 / 1.0 / 3.4 分。也就是说，一套合适的 RL 训练框架，收益可能比直接换一代 base 模型更大。

Lego-RL 直接在未经修改的 harness 上训练。三次实验使用同一 checkpoint、同一批 2,699 条任务和 200k 上下文，各训练 3 个 epoch（126 个 step）。三条 reward 曲线都稳定上升，策略熵也没有坍缩——在保留原生控制流的前提下，训练本身是稳的：harness 在运行时不断改写自己的历史，并没有让优化跑偏。

但三条曲线的形态明显不同。平均响应长度在 OpenHands SDK 上几乎翻倍（43.5k → 90.9k token），在 Claude Code 上只从 41k 增至 51k。同样的起点、同样的任务、同样的上下文预算，训练出来的行为却不一样：前者学会了用更长的探索与自验证换分数，后者只能在更紧的预算里提高单位 token 的收益。

合理的猜测是 harness 各自的上下文管理策略（OpenHands 的 history compaction、Claude Code 的 <system-reminder> 与裁剪规则）决定了“变长”这件事的代价，精确归因还需要单独的消融。

结论层面可以确定的是：RL 学到的不是一个与 harness 无关的“想得更久”，而是一套针对当前 harness 控制流的具体策略。 这正好回到前面那 7 分的差距——harness 属于环境，最优策略随 harness 而变，所以训练必须发生在部署时真正使用的那套 harness 上。

对比现有的 agentic RL 框架，Lego-RL 可以同时支持黑盒 harness、反作弊防护、训练可观测等特性。

代表性 agentic RL 框架对比（论文 Table 1）。✓ 支持；△ 部分/有条件支持；– 未见报告。前四列对应 Faithful（保真），中间三列对应 Reliable（执行与奖励），末列对应 Observable（可观测）；R3 指 rollout 路由 replay。

(a)–(d) 依次展示 training reward、held-out 验证分、策略熵和平均响应长度。蓝 / 橙 / 绿分别对应 OpenHands SDK、Claude Code、OpenCode。起点相同，三条曲线后续却走出了明显不同的轨迹。

整体架构：多种harness基建共用

Trainer 构建在 verl 之上，沙箱执行构建在 Harbor 之上。两边的分工很清楚：

• verl 负责“学”：actor 训练与权重同步（FSDP / Megatron-LM / VeOmni 三套后端）、PPO / GRPO / GSPO 目标函数、vLLM rollout 池，以及同步 / 全异步 / partial rollout 的调度。
• Harbor 负责“跑”：把「问题描述 + 仓库快照 + 可执行 verifier」封装成统一的任务格式，并管住一条 trial 的完整生命周期——起沙箱、跑 Agent、跑任务自带的测试脚本得到 0/1 reward、回收环境。沙箱后端本身是可替换的一层：生产用 Kubernetes（一条轨迹一个 pod），小规模用本地或远端 Docker（一条轨迹一个容器）。

两者中间是这套框架真正补上的部分：

• AgentLoopWorker：Trainer 每步把一批任务交给一组并发 worker，每个 worker 负责一条 trial 的全过程——在新沙箱里拉起未修改的 harness、把它的 base URL 指向 proxy、让它按自己的控制流跑完多轮，最后收回 verifier 的 reward 和 token 级轨迹。单条 trial 有九成时间不在 GPU 上，并发度因此是吞吐的主要杠杆。
• 进程内 proxy：同时提供 OpenAI 与 Anthropic 两套接口，是 harness 与策略之间唯一的通道。token id、response mask、logprob 和 MoE 专家路由都在生成时就地记录（详见 Faithful 一节）。
• 任务环境侧的防护：反作弊与分阶段网络策略放在沙箱里，而不是放在 harness 里——因为 harness 不能改（详见 Reliable 一节）。

所以接一个新 harness 只需要一个轻量 Adapter：启动 Agent、指向推理服务、传回交互数据，其余链路全部共用。目前 OpenHands SDK、Claude Code、OpenCode 三个 harness 已端到端验证；任何能说 OpenAI 或 Anthropic 协议的 harness，实现一个 adapter 类并在配置里选中即可，轨迹捕获、负载均衡、R3 路由回放这些能力都是自动继承的，不需要为它单独改一遍。

未经修改的 harness 运行在 per-trial 沙箱中。每次模型调用都会经过进程内 proxy，转发到推理服务，再写入 Trainer 消费的 buffer。整套系统只有沙箱这一层需要感知具体的 harness。

再往外是一套完整闭环：任务构造与筛选负责提供输入；启动前先检查配置和资源；训练期间由 Live UI 实时展示 run 状态；看到的问题和结果，又会直接影响下一轮实验。

整个流程分为五个 stage：数据准备 → Run 校验 → 训练 → 实时可观测 → 人工复盘。Agent Plugin 是横跨 stage 2 到 4 的控制面。

优化目标：形式化定义

一个任务实例 x = (q_x, R_x, V_x) 包含问题描述、初始化完成的仓库环境，以及任务专属的可执行 verifier。这里，harness \mathcal{H} 属于环境，而不是策略：第 t 轮中，它把交互与仓库状态 s_t 映射为上下文 c_t = \mathcal{H}(s_t)，策略生成 a_t \sim \pi_\theta(\cdot \mid c_t)，再由 harness 执行工具动作并得到 s_{t+1}。一条 rollout，就是模型 API 实际交换过的那串 prompt / response 对；verifier 最终只输出一个 bit：

只有策略生成的 token 参与训练。记 \mathcal{M}(\tau) 为这些位置，则：

要注意，每一轮的条件都是 harness 给出的 c_t，而不是原始历史。训练目标是最大化期望 verifier reward。每个任务采样 G 条轨迹，并计算 group-relative advantage \hat{A}_i = (r_i - \bar{r}) / (\mathrm{std}(r_{1:G}) + \delta)。三次生产训练都使用 GSPO 的序列级 surrogate：

其中，\theta_{k'} 是生成这一组轨迹时的策略版本。w(\tau_i) \in \{0,1\} 会把因基础设施故障终止的轨迹置零。如果把 \sigma_i 换成逐 token 比值，目标就退化为 PPO / GRPO，Trainer 同样支持。

这个目标函数直接带来两点工程约束。第一，组内 reward 完全相同时 \hat{A}_i \equiv 0，这一组不会贡献梯度，所以任务池必须始终匹配当前策略的能力。第二，r 来自真实代码执行，因此学习信号有多可信，取决于沙箱和 verifier 有多可靠。式子之外还有一个现实问题：Agent harness 在训练过程中仍会不断改写自己的状态。

核心特性一：Faithful —— 保真优化

难题：存档的对话记录 ≠ 采样时的 token 序列

最直接的做法，是保存 transcript，再在训练时重新 tokenize。对 SFT 来说这通常够用，但 on-policy RL 需要的是采样当时真实生成的 token 及其 logprob。根据 transcript 重算，得到的已经不是同一个量。更麻烦的是，harness 确实会不断改写历史：

• Claude Code 会中途插入 <system-reminder>；
• OpenHands 会在窗口占满后做 history compaction；
• 工具调用参数会被重新序列化，连 key 顺序都可能变；
• sub-agent 还会与 parent agent 共用 session。

这些变化都不会报错，却会让 importance sampling ratio 持续产生偏差。

解法一：在推理侧增加 proxy

proxy 同时支持 Anthropic 和 OpenAI 两套协议，对 harness 来说，只是换了一个 base URL。token id、response mask、logprob 和 MoE 专家路由都会在生成时立即记录，之后再逐轮对齐上下文。工具调用按 id 匹配，不依赖重新序列化后的参数；sub-agent 的 session 也彼此隔离，不会和 parent 的轨迹混在一起。

解法二：replay MoE 的专家路由

MoE 还有额外要求：token id 一致仍然不够。同一个 token，如果 vLLM 采样时路由到专家 {3, 17}，训练 forward 时却选了 {3, 41}，两边计算的就不是同一个概率。把 rollout 的路由决策 replay 回训练（R3）后，训练/推理相关性从 0.9946 提升到 0.9993，平均 logprob 偏差从 0.0062 降至 0.0025。

这些问题最麻烦的地方，是它们不会主动报错。我们遇到过 replay 路由整体错一位，结果比完全不开 replay 还差（Pearson 0.750 对 0.995）；也遇到过 capture buffer 容量低估约 4 倍，越界内容被静默写成 0，覆盖率一度跌到 24%。排查时没有捷径，只能把记录下来的路由与模型当场选择的专家逐 token 对齐检查。

这里需要区分两件事。异步训练导致的策略滞后，是有界的 off-policyness，importance sampling ratio 会对它进行修正；但路由一旦记错，训练时重算的 logprob 就无法对应采样值，也没有其他机制可以补救。

因此，保真必须单独作为一项核心能力。三次生产训练中，rollout 与 training 的 logprob 中位相关性都不低于 0.998，任何一步都没有低于 0.989。

核心特性二：Reliable —— 可靠执行

reward 是否可信，先取决于任务和轨迹是否有效；还能产生多少梯度，则取决于一批任务对当前策略是否仍有区分度。再往下，才是如何并发调度数千个容器，同时不让 Trainer 被阻塞。下面分三层来看。

第一层：Reward 完整性——堵住“不解题也能得分”的路径

奖励直接来自任务自带的测试脚本：解决计 1.0，否则计 0.0。这里没有 reward model，自然也没有 reward model 漂移；但模型所有可能绕过任务拿分的路径，都必须由环境堵住。

防御上线前，我们统计到几类典型作弊方式：从本地 git 历史直接读取修复（4.6%~20.5%，git log -p 等指令，靠黑名单堵不完）、修改测试文件让结果“自洽”通过（2.4%~19.4%）、联网下载参考 patch（约 1.9%）。还有约 2.5% 的任务，判分脚本本身就会把参考 patch 应用上去。

这些防御都放在任务环境内部，并按执行阶段区分。默认原则很简单：Agent 阶段拿不到的资源，到了判分阶段仍可正常使用。

第二层：任务难度是“相对于当前策略”的

每个任务采样 8 条 rollout。若这些轨迹全对或全错，组内没有方差，也就没有梯度。因此，固定任务池的训练价值会随策略变化。

OpenHands SDK 上，零方差组占比从 44.7% 升到 51.4%：全对组增长得比全错组下降得更快，到后期约一半任务已经不再提供学习信号。OpenCode 的全对组增长较慢，零方差占比则一直在 43.3% 左右。

(a)–(c) 横轴是「8 次 rollout 里成功几次」，浅色 epoch 1、深色 epoch 3；柱顶 ±N pp 是 0/8、8/8 两端的百分点变化。(d) 零方差组 = 全错（0/8）+ 全对（8/8），这两头都没有组内梯度。

筛选从 36,884 条 OpenSWE 候选任务开始。经过规则过滤、构建和判分校验后，我们用 Qwen3.6-27B 在 OpenHands SDK 上进行 rollout 难度筛选：四次尝试中解出 1~3 次的任务才会保留。筛选阶段只使用了这一个模型-harness 组合，但得到的任务池换到 Claude Code 和 OpenCode 后同样有效。

蓝色为保留、灰色为被过滤掉的部分，三级过滤对应正文的规则过滤、构建与判分校验、难度筛选。可执行池中只有 12.4% 进入训练；训练集与 SWE-bench Verified 在仓库、实例两级严格不相交。

我们还单独做了难度筛选消融：四个任务池各含 951 条任务，其余配置保持一致。完整难度带（1–3/4，4 次中解出 1～3 次）和上半段（2–3/4）都有提升，warmup 后验证均分分别为 0.671 / 0.670；下半段（1–2/4）只有 0.640。

未筛选的随机池（random）则全程没有提升，其中 72.7% 的任务一次都没解出，13.4% 每次都能解出，真正能产生组内方差的任务不足六分之一。

图例按筛选时 4 次尝试解出几次划分：1–3/4 是完整难度带，1–2/4 / 2–3/4 是它的下半段和上半段，random 是未筛选随机池。(a) held-out 验证，(b) training reward。

单条轨迹也需要检查。因基础设施故障终止的轨迹，例如超时或环境未启动，会从 advantage 和 policy loss 中移除，占比分别为 Claude Code 7.1%、OpenHands SDK 2.4%、OpenCode 6.4%。如果轨迹只是达到轮数或 token 上限，但过程本身有效，判分结果仍会保留。

色块是未正常完成的部分：max turns 撞轮数上限，over-length 超 context，timeout 超时，environment setup 环境没起来；右侧灰色是 completed 占比。同一套沙箱栈，Claude Code 以超时为主，OpenCode 以环境准备失败为主。入 loss 时屏蔽的是后两类。

第三层：单条 trial 中 91% 的时间是 Agent 在执行

SWE 任务的一条 rollout，需要启动沙箱，跑几十轮“读代码 → 改文件 → 执行命令”，最后再判分。我们统计了 3,699 条 OpenHands SDK trial：平均每条耗时 920.4 秒，其中 91.3%（840.5 秒）都花在 Agent 执行上。

生成和工具执行在这段时间里交替进行，并不是系统闲着。沙箱启动只占 2.3%，判分占 3.9%，但长尾很明显，判分的 p99 达到 928 秒。

所以，优化重点不是让 optimizer 再快一点，而是尽量别让 Trainer 干等 rollout。同步执行总会被最慢的轨迹拖住。在同一套栈的离线同步筛选中，最慢的 10% 轨迹占了 24.5% 的总工作时间。我们识别到 31 次批次边界停顿，中位时长 38.7 分钟，最长达到 135.9 分钟。

橙段是等 rollout，灰段是 optimizer 在算。同样 7.5 小时，同步走完 3 步、异步走完 7 步，单步快 2.5×；校正两组 GPU 的 optimizer 吞吐差后为 1.9 对 1.0 小时（staleness = 1）。

切到异步后，rollout slot 的空闲中位数降到 0，但 Trainer 仍有 40.8%（OpenHands SDK）/ 66.1%（Claude Code）的时间在等待 rollout。瓶颈仍在生成侧，而且轨迹越长越明显。

Partial rollout 解决了另一个浪费：权重同步时，不必丢掉已经跑了十几分钟的 trial。系统会中断 vLLM 生成、加载新权重，再从断点 token 在同一 replica 上继续，前缀 KV cache 也会保留。

对 harness 来说，这仍然只是一次普通的 HTTP 请求。

剩下 2%~4% 的开销看似不多，却会决定一个包含 512 条 trial 的 step 能不能顺利启动：

逐阶段配对消融。最后一行是故意留着的开销：判分工具链打进镜像，换 reward 可复现。

镜像懒加载的中位加速只有 1.7×，真正明显的是尾部收益：同批 100 张镜像的最差延迟降低 23×，网络流量从 21.6 GB 降到 1.59 GB，磁盘写入从 65.6 GB 降到 5.29 GB。代价是无缓存时，容器内读取吞吐会略微下降。

核心特性三：Observable —— 可观测训练

失败归因：快速区分“策略问题”和“基础设施问题”

一次 run 在第 3 步失败。排查后发现，tool-call parser 被配成了 hermes，而不是 qwen3_coder，一整天的集群时间因此作废。另一次验证 reward 从 0.556 跌到 0.150，看起来很像策略退化，但 172 条轨迹中只有 60 条真正进入判分，问题其实出在环境准备。还有一次 run 崩溃后，我们通过轨迹级分析补出了 early-stop 条件，理论上可以比实际终止提前 8 步告警。

(a) 逐步终止原因：environment setup 在 step 12 冲到 38%，对应一次镜像/环境故障，reward 从 0.69 掉到 0.47。(b) 崩溃 run 的辅助分析——模型不再调工具，改成直接写一段话；mean turns 跌破 3 时应 early-stop，比实际终止早 8 步。

要快速完成这类定位，Live UI 必须把每个判分结果追溯到具体来源：为什么终止、对应哪项任务、调用过哪些工具，以及训练与推理概率是否一致。下图截自 Claude Code run 的第 103 步，当时训练仍在进行。

上：逐步终止原因分解，截图时 34,816 条 rollout 中 94.1% 正常完成。下：训练/推理一致性——log-ratio 尖峰或有效样本量下降，往往比 reward 异常更早出现。

除了常规曲线，面板还加入了几项 Agentic RL 专用能力：轨迹查看器会展示完整 transcript、reward 和终止原因；in-batch 分布说明究竟有多少组在驱动更新；验证失败清单会按执行阶段归类；辅助分析面板则先由语言模型列出候选解释，再交给人工确认。

上面两张截图都取自真实的生产 run，这里是一个可以直接点开的公开样例页：https://lego-rl-dashboard.pages.dev。

训练到底改变了什么？行为层面的证据

平均 reward 上升，只能说明模型整体做得更好了，却回答不了它具体学会了什么。为此，我们从 OpenHands SDK 生产 run 的开头和结尾各抽取 420 条轨迹，做了一次行为分析。

① 效应最强的是自我验证行为：

这三项指标一起上涨，而且幅度明显高于其他行为。换句话说，模型逐渐养成了一个更稳的习惯：先检查，再动手，改完以后主动验证。

② 错误恢复几乎没有变化。对于中途出现过命令失败的轨迹，最终解决率只从 63.9% 提升到 66.8%。这与奖励设计一致：terminal binary reward 只看最终是否成功，不会单独奖励中途纠错。

③ 增益主要来自执行更稳，而不是覆盖更多任务。pass@8 提高 4.7pp（83.2 → 87.9），pass⁸（八次全部解出）提高 11.1pp（28.3 → 39.4），格式错误的工具调用从 1.07% 降到 0.15%。模型在原本就能解决的任务上变得更可靠，但新增的可解任务相对有限。

④ 响应变长，主要是因为交互轮数增加。平均轮数上升 78%（46.6 → 83.1），单轮 token 只增加 17%。复现时如果只扩大 context 预算，却没有同步放宽 turn limit，中后期会有大量轨迹因为达到轮数上限而被截断。

(a) 每题平均工具轮数，蓝 OpenHands SDK、橙 Claude Code。(b) 训练结束时各类工具调用占比，黑色竖线是第一 epoch 的位置。两边共同的趋势：测试相关调用变多，malformed call 变少。

小结

Lego-RL 保留了原生控制流，同时把 OpenHands SDK、Claude Code 和 OpenCode 接入可扩展的策略梯度优化。背后依靠的是沙箱化执行与判分、token 级保真记录、全异步训练、reward 完整性防护和轨迹级可观测。同一份 Qwen3.5-35B-A3B，在三个 harness 上分别提升 +6.4 / +5.8 / +9.4。

这些实验让我们更确定一件事：要继续 scaling Coding Agent RL，只扩展 optimizer 还不够。执行环境必须可靠，轨迹必须保真记录，反馈机制也得跟着 Agent 一起演进。接下来，我们会继续探索超长 horizon 任务、混合任务池，以及一个策略跨多个 harness 的联合训练；相关数据和模型也会持续开源。

Lego-RL 是 LegoX 系列的一部分。同系列还包括 SWE-Lego（SFT 配方）、Terminal-Lego（轨迹质量筛选）和 SWE-Review（推理时的 generate-review-revise）。如果这项工作对你有帮助，欢迎交流，也欢迎 Star。

作者：Yiming Du*, Yuxin Jiang*, Tao Yuan*, Jianbo Dai, Shaowei Wang, Jierun Chen, Chaofan Tao, Xianzhi Yu, Lifeng Shang, Kam-Fai Wong, Xiaohui Li†, Haoli Bai† ｜ 华为技术有限公司、香港中文大学。*共同一作，†通讯作者。