同一个模型,在不同 agent harness 里的得分差异,可能比换模型还大。Hugging Face FineEnvs 团队(Lewis Tunstall、Leandro von Werra 等)的长文 The ultimate guide to multi-harness RL 把这件事讲透了:agentic RL 训久了,模型学会的不是「怎么解题」,而是「怎么在这个 harness 的接口习惯下解题」。他们的解法是让 harness 以为自己连的是模型服务,把 rollout 全程录进 GRPO 训练。这篇把技术路线和训练配方拆开读。
为什么 harness 影响这么大
先把术语钉死:harness 是模型和任务之间那层软件——它构造模型看到的上下文、中转工具调用、校验输出、决定何时重试或停止。对训练者来说,harness 是别人写的、改不动的程序。同一个政策(policy,即被训的模型权重),在不同 harness 里表现完全不同:
- 换 harness 比换模型影响大。zhang2026stopcomparing 在 100 道 SWE-bench Verified 任务上,固定任务对比 GLM-5.1 / GPT-5.4 / Kimi K2.6 三个模型 × 三档 harness 配置(Minimal 繁冗工具无压缩无重试 → Improved 加压缩重试 → Full 再加自检与回滚):换 harness 让 GLM-5.1 移动 13 分,而同一 harness 里换模型只动 2.5–5 分。
- 模型卡都开始标注 harness 来源。Kimi K2 的 Terminal-Bench 报了两个数:Terminus 下 25.0,自家框架下 30.0。GLM-4.7 的模型卡直接写「在 Claude Code、Cline 等主流 agent 框架下有显著提升」。
- 同一权重,榜单 vs 实战差 10 个点。Claude Opus 4.5 在 Scale 的 SEAL 榜单 SWE-bench Pro 上 45.9%,在 Claude Code 里 55.4%。
Orchard 论文把这种迁移代价量化得很刺眼:OpenSWE-32B 从 OpenHands 挪到 Mini-SWE-Agent 掉 7.5 分,挪到 Kimi-CLI 直接掉 58.8 分,SWE-bench Verified 只剩 3.6%,Terminal-Bench 2.0 是 0。而 Orchard 自己用多 harness 轨迹微调 + Mini-SWE-Agent 里 RL 的模型,在三个 harness 下稳定在 45.0–64.3。KwaiKAT 把病因说得直白:「模型学到的不是怎么解题,而是怎么在那个 harness 的接口约定下解题。」过拟合分三种:对动作格式(工具名、参数名,换个 harness 直接拒调)、对上下文结构(压缩方式不同)、对控制流(依赖原 harness 的重试与停止条件)。所以 Poolside 的 Laguna 报告里,训练数据刻意混入 OpenHands、OpenCode、Mini-SWE-Agent 的轨迹——头部实验室已经在「harness 缩放」了。
白盒与黑盒:谁拥有 rollout
关键分野是谁驱动 rollout 循环:
- 白盒环境:训练者拥有循环。采样动作 → 调 env.step() → 读观测 → 再采样,每个 token 都已经在训练者手里。TRL 的 GRPOTrainer 期待的就是这种接口。
- 黑盒环境:harness 拥有循环。它在沙箱里跑自己的循环、调自己的工具、压自己的上下文、自己决定何时停。训练者在盒子外面,能看到的只有打到模型 endpoint 上的一串 LLM 请求-响应对。
Agent Lightning 的定义:「传统 agentic RL 里训练引擎拥有环境交互循环;harnessed agentic RL 里 harness 拥有循环,训练引擎只观察一串请求-响应对。」四个主流 harness(Claude Code、Codex、OpenCode、Mini-SWE-Agent)全是黑盒。但有一个接口保证存在于 harness 之外——模型 API 本身。harness 内部千差万别(OpenAI chat、OpenAI Responses、Anthropic Messages、Google Gemini 四种方言,是否用 tool calling、怎么压上下文、控制流让给模型多少),可它总要调模型。这个唯一接口就是训练者能站的地方,整篇长文的架构就是围绕它搭的。注意别和 KAT-Coder 报告里另一套白盒/黑盒用法混淆:那边说的是上下文压缩策略(Mini-SWE-Agent 无压缩所以白盒,Claude Code 等压缩重组所以黑盒),和「谁拥有循环」是两条独立的轴。
三块架构:OpenEnv、Harbor 与 TRL
框架分三块,各管一段:
| 组件 | 角色 | 要点 |
|---|---|---|
| OpenEnv | 标准 RL 环境接口 + capture proxy | Gymnasium 式 reset/step/state,typed action/observation,打包成 Docker。capture proxy 是核心机关 |
| Harbor | 任务 + 沙箱 | 容器化任务集,每个 rollout 一个 E2B/Daytona 沙箱,harness 和沙箱按 rollout 选 |
| TRL Async GRPO | 训练引擎 | 生成与训练异步解耦:一张 H100 训,另一张用 vLLM 服务策略并持续产出 rollout,训练不等最慢的 agent |
capture proxy 的机关:harness 找 proxy 的方式和找任何模型供应商一样——base URL + API key,只不过这个 key 是按 rollout 签发的 capture session id,这样一个 proxy 一个端口就能服务所有并发 rollout,拿着没注册过的 key 来调用直接 401。proxy 靠路径、header、body 形状识别请求属于哪种方言,再用从 NVIDIA Polar gateway 移植的 converter 统一转成 chat completions,答完再按调用方自己的格式回放。训练者要的是每个采样 token 的 token id 和 logprob,proxy 向引擎要这些,外加全分布采样。
两个工程细节值得抄:
- 不做流式。proxy 对引擎的调用从不 stream:等完整 completion 存下来,再回放给 harness 当 stream。比晚一点吐出第一个 token 多花不了什么,省掉了 partial delta 解析的全部麻烦。
- logprob 必须 top_p=1.0。截断分布(top_p/top_k)会把策略自己会采的 token 偏走,这是 RL 里已知的熵塌缩路径;而且 vLLM 的 processed_logprobs 在截断之后才算,logprob 对不上策略。他们的实测:top_p 调到 1.0,importance ratio 从 0.985–0.993 提到 0.9984–0.9999。vLLM 侧要两个 flag:
1 | vllm serve <model> --return-tokens-as-token-ids --logprobs-mode processed_logprobs |
安装有个版本坑:typed TrainingTrace 要 OpenEnv 0.7.0+,harbor extra 必须 Python 3.12——3.10/3.11 上 openenv[harbor] 根本不装 Harbor 依赖。harbor_env 包在仓库 envs/ 目录里,不在 wheel 里:
1 | git clone --depth 1 --branch main https://github.com/openenv/OpenEnv.git |
异步的代价要清楚:rollout 来自的权重通常落后 2 个优化步,最多落后 4 步。
训练配方与结果
正式跑的是 Liquid AI 的 LFM2.5-2.6B(早期 Qwen3.5-2B 的实验用来定配方)。任务用 SmolDataEnvs——从真实 Kaggle notebook 做的一套数据分析任务:1000 个训练任务(400 medium + 600 hard,固定顺序),250 个无重叠测试任务。对照两个 run:只在 OpenCode 里训,和四 harness 混训(OpenCode / Claude Code / Codex / Mini-SWE-Agent,每个 GRPO 8-rollout 组用其中一个)。
reward 设计是这篇里最实用的部分:正确性(对 1 错 0)+ 工具效率加成(最多 0.1,答对且调用更少才有)。Qwen 早期 run 只给正确性 reward,结果 rollout 的工具调用从 13 次爬到 41 次——模型没有任何理由在答对后停止探索。0.1 的加成看着小,但 GRPO 学的是组内对比:8 个 rollout 全对时,正确性完全无法区分它们,效率加成是唯一信号。审计数据:OpenCode-only 组 17.5%(97/555)、多 harness 组 22.6%(155/686)里,所有可计分 rollout 全对但工具数不同——全靠加成提供 reward 对比。
硬件与时长:每 run 2×H100(一张训、一张 vLLM 服务)+ 每 rollout 一个 1 CPU / 4 GB 的 E2B 沙箱。OpenCode-only 训 32 小时,多 harness 训 46 小时(不含评估、排队与重启)。
结果:
| 指标 | OpenCode-only | 多 harness 混训 |
|---|---|---|
| 测试集 pass@1(总) | 52.3% | 54.2% |
| OpenCode 下 | 58% | 50% |
| Claude Code 下 | 42% | 49% |
| Codex 下 | 43% | 54% |
训练前的基线就暴露了问题:同一份 LFM 权重,Mini-SWE-Agent 下解 62%,Claude Code 下只有 33%。训练后两个 run 都涨 10–12 个点,大部分增益在前 200 步。结论很清晰:多 harness 混训用自家长 harness 下 8 个点的代价,换来了跨 harness 的泛化;OpenCode-only 模型学到的「少调工具」只部分迁移到了 Codex。另外工具调用曲线在训练集和测试集上方向相反——训练时多 harness run 调用更多(因为 Claude Code/Codex 本来就比 OpenCode 话多),测试集上两个模型在所有 harness 下调用都比训练前少。
评估方法也值得抄:每个 cell 只跑一次,相邻 checkpoint 差 1–2 个点就是噪声,要信跨 checkpoint 的趋势,不要信单点。
对 xcoder 的启示
这条路能不能用在自己的 xcoder 上,卡点一句话:RL 要动权重,checkpoint 必须在你手里。
- xcoder 是闭源部署/网关路由(模型 ID 形如推理服务路由而非自持 checkpoint):做不了 RL,唯一路径是把各 harness 下的真实轨迹采回来做 SFT/蒸馏——Orchard 和 Poolside 都是这么混的。这条路和已有的 SFT 打包批次经验直接衔接,不用碰权重。
- 有可编辑权重(或训一个 2–7B 开源小模型当执行端):照 FineEnvs 的
05-multi-harness-rl/train/multi_harness.py配方直接抄——vLLM 两个 flag、OpenEnv proxy 夹在 harness 与 vLLM 之间、TRL Async GRPO、双卡 H100、单 run 30–50 小时。reward 用「正确性 + 效率加成」,别只给正确性。评估按四 harness 全跑、看趋势不看单点。
对闭源主模型还有一个副产品:harness 混训的价值不止在泛化分数,capture proxy 顺手记录的 token id + logprob 全轨迹,本身就是一套现成的多 harness 轨迹采集器——即使最终不做 RL,这套录下来的数据也够 SFT 蒸馏用了。
参考链接
- 长文:https://huggingface.co/spaces/FineEnvs/multi-harness-rl
- 可复现训练代码:https://github.com/adithya-s-k/FineEnvs (05-multi-harness-rl/,含 REPRODUCE.md)
- OpenEnv:https://github.com/openenv/OpenEnv
- TRL Async GRPO + Harbor 示例:https://github.com/huggingface/trl/tree/main/examples/async_grpo_harbor
- 任务集 SmolDataEnvs:HF collection FineEnvs/smoldataenvs