Codex Harness 最近在开发者圈子里成了热点。OpenAI 把用于评估 Codex 的 harness 工程公开后社区里出现了两种声音有人觉得 Agent 评测终于进入规范化阶段也有人引用 OpenAI 负责 Codex 相关工作的工程师观点说“Codex 这样的 harness也就再火俩月”。这两种判断并不冲突前者说的是工程价值后者说的是热度周期。真正值得关注的是中间那段为什么一个评测框架会引起这么大的讨论它里面到底有哪些可以迁移到日常 Agent 开发中的设计。这篇文章不追热点也不替 Codex 刷榜。目标是把“Harness 工程”这件事讲清楚它解决什么问题、核心模块如何配合、怎么在本地跑通 Codex 的基础流程、遇到常见报错往哪查以及如何借鉴这套思路搭建一个轻量级 Agent 评测环境。读完以后你应该能对“Agent 评测为什么难”形成一个整体判断并且手里有一份可复用的排查清单。1. 先搞清楚 Codex Harness 到底在解决什么问题1.1 Harness 不是跑分脚本而是一整套 Agent 考试系统通俗地说Harness 就是“给 Agent 准备的考试系统”。给模型出题谁都会难的是让每个考生在同一套环境里完成操作记录下完整过程然后用同一套标准打分。在 Agent 场景里Harness 的技术定义是一套自动化评估框架它负责把任务描述、代码仓库、运行时环境、Agent 执行入口、日志采集和结果评判组合起来。一个完整的 Harness 至少回答三个问题Agent 在什么环境里执行任务。Agent 每一步做了什么产生了什么结果。最终结果用什么标准来认定成功或失败。很多普通 Benchmark 只做输入输出判分不会管 Agent 在中间执行了多少条命令、改了多少个文件、失败重试了几次。Codex Harness 的不同之处在于它把“完整执行链路”作为评测对象Agent 需要自己在仓库里读代码、改文件、跑测试再根据报错信息调整方案。这已经不是单纯的模型能力测试而是“模型 工具 环境”的综合评估。1.2 SWE-bench 类基准覆盖不到的细节SWE-bench 这类基准在 Agent 评测里很常见它从真实 GitHub Issue 中抽取任务要求模型生成 patch然后用隐藏测试判断是否修复问题。优点是数据真实、评分简单但也有明显局限。第一它偏向“一次性 patch”的判定不关心 Agent 是否真的把环境跑起来过。模型只要生成一个看起来合理的 diff就有机会得分但实际工程里 patch 能不能应用、测试能不能通过、会不会破坏别的模块完全是另一回事。第二它缺少多轮反馈。真实开发中Agent 写完代码后要跑测试测试失败后要读日志改完再跑。SWE-bench 类任务往往一次提交就结束Agent 没有机会在真实 shell 里完成“编码—运行—调试—再编码”的闭环。第三这类基准容易被数据污染。公开题目一旦进入训练语料模型可能记住答案而不是学会调试。Codex Harness 强调真实运行 Agent、让 Agent 自己接管命令执行正是为了把评测重点从“记答案”拉回到“做工程”。普通 Benchmark 与 Harness 的核心差异可以这样对比对比维度普通 BenchmarkAgent Harness考察对象模型生成的文本或 patchAgent 的完整执行过程环境通常是静态输入输出代码仓库、沙箱、命令入口反馈一次评分多次执行、失败重试、日志回放主要风险数据污染、过拟合环境不稳定、日志不完整工程成本低较高1.3 “也就再火俩月”到底在表达什么这段话在网上流传很广但它的背景不能简单理解为“Harness 没价值”。更合理的理解是如果热度指榜单分数、演示视频、新工具发布带来的短期关注任何 Harness 都会迅速降温。因为模型迭代、评测集更新、工具链变化都会让一套具体的评测环境快速过时。热度会降温但方法论会沉淀。Codex Harness 真正留下的是三类东西任务集设计如何把真实开发任务转化成可执行的评估任务。环境工程如何用 Docker 等方式构建干净、可重复的运行环境。日志和评分协议如何记录 Agent 行为让失败可以回放、可以归因。所以“再火俩月”这句话对普通开发者的提醒不是“别学 Harness”而是“不要围观热度要拆解机制”。下一部分就进入 Harness 自身的工作原理。2. 拆解 Harness 工程的核心运行逻辑2.1 从模型能力切换到环境工程很多人在评估 Agent 时默认把成绩差异等同于模型能力强弱。但在真实 Harness 场景里环境对结果的影响往往比模型本身更大。同一个模型在 Python 3.10 和 Python 3.12 环境里跑同一个任务可能因为某个库不兼容而得到完全不同的结果。同一个任务在允许联网和禁止联网的沙箱里执行Agent 选择的路径也会不同。再比如依赖安装超时、测试用例顺序不稳定、磁盘空间不足都会让所谓“模型能力”的分数失真。这就是为什么 Harness 工程会更强调“环境快照”。评测时不仅要记录模型名称和 Prompt还要记录镜像版本、依赖锁文件、操作系统版本、环境变量、命令执行序列。否则一个高分任务过了两周就无法复现这个评测体系也就失去了意义。学习环境里可以接受“能跑就行”但 Harness 的主要应用场景是回归评估每次修改 Prompt、工具链或模型后都要重新跑同一批任务并对比结果。如果环境不稳定对比就没有意义所以环境工程是 Harness 的底座。2.2 一个最小 Harness 的四个模块从一个最小实现来看Harness 通常由四个模块组成模块职责主要产物任务定义描述仓库、问题、验收标准任务清单、Issue 描述沙箱提供隔离的代码运行环境Docker 镜像、依赖锁文件Agent 执行驱动 Agent 完成操作Command 序列、文件修改记录评分器判断结果是否符合预期结构化评测报告任务定义使用 JSON 描述会非常清晰一个最小任务可以长这样{ task_id: fix-login-race-condition, repository: https://github.com/example/auth-service.git, branch: main, instruction: 修复登录接口在并发请求下出现 token 覆盖的问题并补充回归测试。, expected_test_commands: [ go test ./internal/auth/... ], timeout_seconds: 1800 }任务定义里最容易被忽略的是“验收标准”。如果不写清楚测试命令和边界条件评分时就会出现“看着改对了但测试全红”的争议。沙箱模块在开源评测框架里普遍采用 Docker目的是把依赖、系统库、环境变量都固定在镜像里。Agent 执行模块负责把任务指令交给 Agent CLI同时采集标准输出、标准错误、退出码和文件变更。评分器最后读取这些记录执行预期测试输出通过率和不通过项。2.3 日志与可复现性设计Harness 与普通脚本最大的区别在于日志密度。普通脚本只关心最终是否成功Harness 要关心每一步是否可回放。一个合格的 Harness 日志至少记录以下信息任务 ID 和任务描述。环境快照镜像 ID、依赖版本、启动时间。Agent 执行的完整命令列表。每次命令的退出码和关键输出。Agent 修改的文件以及 diff。测试执行结果和测试日志。模型、Prompt 模板、工具版本号。有了这些字段排查一次失败才能做到“先复现再定位”。遇到一个问题时不要直接怀疑模型能力先检查环境是否一致再回放 Agent 当时的命令序列看它在哪一步偏离了预期。这个排查顺序会贯穿整个 Harness 使用过程。注意不要只验证程序能启动还要验证输入、输出、异常分支和日志是否符合预期。Harness 的价值不在“跑完”而在“跑完还能讲清楚发生了什么”。3. 本地跑通 Codex 基础流程3.1 环境准备与版本确认在本地使用 Codex先确认操作系统和依赖。Codex CLI 通常运行在 macOS 或 Linux 环境Windows 下更适合通过 WSL 使用。是否安装 Docker取决于你要不要运行官方评测 Harness如果只是用 Codex 处理本地仓库可以先不装。下面是一份环境检查清单检查项推荐做法说明系统版本macOS/LinuxWindows 用 WSL避免文件路径和 shell 兼容性问题Node.js确认 LTS 版本Codex CLI 常见安装方式依赖 NodePython按任务仓库需求准备评测 Python 项目时版本要严格对齐Docker跑 Harness 前安装用于沙箱隔离和依赖复现代码仓库准备一个干净的测试仓库不要在重要生产仓库里直接试命令不同版本的 Codex CLI 参数差异较大落地前要先阅读官方 README不要照抄网上命令。下面示例用于说明思路实际项目要结合自己的包名、路径和版本调整。3.2 安装与鉴权安装 Codex CLI 的常见方式是通过 Node.jsnpm install -g openai/codex codex --version如果 npm 没有找到对应包名以官方仓库github.com/openai/codex的 README 为准。安装完成后需要完成登录鉴权常见方式有浏览器登录和 API Key 两种codex login登录成功后CLI 会在本地保存凭据。之后执行任务时它会携带身份信息请求 OpenAI 的服务。这里要强调API Key 属于敏感凭据不要写进仓库、不要贴到公开文章也不要随意用第三方分享的 Key。3.3 用 Codex 执行一个最小任务基础流程可以先用一个小任务验证。比如让 Codex 对一个空目录初始化 Git 仓库并生成一个说明文件mkdir -p ~/codex-demo cd ~/codex-demo git init codex exec 创建一个 README.md内容说明这个目录是 Codex 最小示例并提交这次文件变更执行后你会在终端看到 Codex 分析任务、生成命令、执行命令的过程输出。最终检查点有两个一是README.md文件是否确实存在二是git log是否出现一次提交记录。ls -la README.md git log --oneline这一步跑通说明安装、登录、基础执行链路都是通的。如果卡在这一步问题通常出在环境变量、PATH 或鉴权状态而不是任务本身太复杂。3.4 接入团队内部模型网关或兼容接口Codex 本身支持配置不同的模型提供方。社区的常见做法是把 Codex 接到 DeepSeek 或其他兼容 OpenAI 协议的内部模型服务上。这个思路对团队很有价值你不需要依赖某一个模型厂商的账号体系而是可以针对不同任务切换模型再用同一套 Harness 做对比。在 Codex 的配置文件里通常会声明一个 model provider类似这样model deepseek-chat model_provider internal-gateway [model_providers.internal-gateway] name Internal Model Gateway base_url https://internal-gateway.example.com/v1 env_key INTERNAL_GATEWAY_API_KEY wire_api responses配置里的base_url指向团队内部部署的兼容服务env_key对应环境变量中的密钥。配置完成后用codex exec跑一次最小任务确认请求能到达内网服务并返回结果。要注意的是不同服务对wire_api和模型名的支持不同。如果服务端只支持chat协议而客户端配置成了responses启动阶段不会报错但请求时会收到协议不支持的错误。这类兼容性问题属于配置层面的问题是排查链路里优先级很高的环节。4. 自己实现一个轻量 Harness 的切入路径4.1 为什么值得自己做官方 Harness 功能完整但直接上手会面临两个问题一是任务集是面向公开 Benchmark 设计的不一定贴合你的业务二是官方仓库通常带有复杂的环境编排会分散学习精力。自己写一个最小 Harness目的不是替代官方工具而是把原理内化。当你亲手设计了任务 JSON 格式、写好沙箱脚本、定义评分规则后再回头读官方源码理解速度会明显加快。真实团队做 Agent 回归测试时也往往需要一套贴合自己仓库的轻量评估脚本。4.2 任务集、沙箱和评分三件套最小 Harness 可以用三部分组织任务集文件、运行脚本、评分逻辑。任务集文件描述“要测什么”{ tasks: [ { name: fix-failing-test, repo: ./sample-repo, prompt: 修复 tests/test_math.py 中失败的加法测试并保证所有测试通过。, check_commands: [pytest tests/test_math.py -q] } ] }运行脚本负责“怎么跑”。常见组合是 Python 脚本驱动 Docker 容器docker run --rm \ -v $PWD/sample-repo:/workspace \ -v $PWD/agent-output:/output \ -e CODEX_API_KEY$CODEX_API_KEY \ codex-runner \ codex exec 修复 tests/test_math.py 中失败的加法测试评分逻辑不只看最后退出码还要记录命令输出和文件变更。一个简单方案是执行check_commands解析测试框架输出判定通过和失败用例数。4.3 从“通过/失败”升级到过程指标早期 Harness 可以只输出pass/fail但生产评估会需要更多指标否则很难定位问题。建议至少记录任务耗时衡量 Agent 效率。命令执行次数判断是否出现无效重试。文件改动规模diff 行数异常大时可能引入无关修改。测试通过率最终测试通过但过程反复失败的场景值得关注。Token 消耗衡量成本。这些指标可以输出成 JSON 或 Markdown 报告方便和上一轮结果对比。{ task: fix-failing-test, status: pass, duration_seconds: 92, commands_run: 14, diff_lines_added: 32, diff_lines_removed: 8, token_usage: 18400, test_results: { passed: 12, failed: 0 } }4.4 与真实业务结合的落地顺序直接照搬完整 Harness 容易失败建议按以下顺序推进第一步从过去两周内手动执行过的 Agent 任务里挑出 5 到 10 条覆盖改代码、修测试、写文档等不同场景。第二步为每条任务准备干净的仓库快照确保每次运行前代码状态一致。第三步先手动运行一条任务记录 Agent 行为再逐步加入自动评分。第四步维护一套基线结果任何 Prompt 或工具链变更后重跑对比。这个路径成本很低但能帮你积累出第一套属于自己的 Agent 回归资产。注意在这里不建议直接在生产环境跑评测任务先把最小样本集放通再扩大到完整任务集。评测过程会产生文件修改和命令执行隔离不当时可能污染正在开发的代码库。5. 常见报错与排查链路5.1 找不到 codex cli binary使用 ChatGPT 桌面端或 IDE 插件时经常看到类似报错Unable to locate the codex cli binary. Set codex_cli_path or ensure the executable is in PATH.这个报错本质是宿主应用找不到codex可执行文件。先检查命令行是否能定位command -v codex codex --version如果命令行可以运行但插件报错说明插件的 PATH 环境与终端不同。排查路径是确认 codex 安装位置在插件的配置项里设置codex_cli_path然后重启插件。如果命令行本身找不到回到安装步骤检查 npm 全局安装路径是否加入了 PATH。5.2 local proxy 与 endpoint 类报错还有一类报错形如cc switch local proxy failed while handling codex endpoint /responses. ...这类报错多与本地代理、内网网关或服务端端点不可达有关。排查顺序很重要确认是否开启了会影响本地请求的代理服务。检查配置文件中的base_url是否可以访问。检查服务端日志确认请求是否到达服务。检查本地端口占用和证书配置。这里要特别提醒不要一看到“proxy”就认为是网络代理问题。在工程语境里local proxy 也可能是本地服务组件、IDE 插件内部的转发进程。先看完整报错后半段再决定排查方向。5.3 模型不被支持使用新模型名时可能遇到The gpt-5.6-sol model is not supported when using codex with a ...这个报错表示客户端请求里携带的模型名在当前协议或服务端配置中不可用。检查方式包括确认模型名是否正确、确认服务端是否支持该模型、确认wire_api是否匹配。团队自建网关时要同步更新网关支持的模型列表不能只改客户端配置。5.4 多轮评测结果不稳定Harness 运行同一任务多次得分却不同这是最影响信任度的问题。常见原因有问题现象常见原因检查方式处理建议同一任务两次结果不同镜像版本或依赖版本漂移检查镜像 ID 和 lock 文件固定镜像版本使用锁文件依赖安装偶尔超时网络波动或镜像源不稳定查看安装日志调整超时时间使用内网镜像Agent 行为随机性大模型采样参数差异检查温度等参数配置固定采样参数多次取中位数文件状态未清空仓库残留上轮修改对比 git diff每次运行前重建仓库快照建立稳定基线后把所有任务结果存成表格或 JSON才能有效跟踪 Agent 在版本迭代中的真实变化。6. 把“火不火”放在一边留下可复用的评估资产6.1 哪些场景值得引入完整 Harness如果你的 Agent 要真的改代码、执行命令、跑测试、处理长任务并且你会在内部反复调 Prompt、换模型、换工具链那就值得引入完整 Harness。它提供的不是“一次跑分”而是一套回归机制任何变更都能重新触发一轮评估对比前后差距。团队有一定工程资源时Harness 还能承担更细的任务比如筛选哪个模型适合代码修复、哪个 Prompt 模板更稳定、哪种工具调用方式成本更低。这些都是普通 Benchmark 无法回答的问题。6.2 哪些场景不要急着投入如果当前场景只是问答、文档生成、单轮文本处理Harness 的收益很低用普通执行结果验证就够。如果任务类型太杂没有统一验收标准强行建立评测集只会让脚本本身成为维护负担。如果团队没有维护评测环境的精力也要谨慎。Harness 不是一次性脚本它需要镜像维护、任务集更新、失败案例标注。闲置三周后镜像依赖过期、任务数据过时重新收拾的成本会很高。6.3 三条可以立即执行的练习第一抽取你自己的 5 个历史任务给每个任务写清楚验收命令。第二用 30 分钟设计一个任务 JSON 结构不用写代码只画字段。第三把一次 Agent 运行过程中的完整输出保存下来试着自己做失败归因。这三件事都不需要官方仓库不需要 Docker却能快速建立对 Harness 的基本感觉。6.4 后续可以继续深入的方向常见方向包括阅读主流开源评测框架的源码、研究 Docker 沙箱的依赖缓存策略、尝试把 Harness 接入 CI 流程以及在团队内建立一个“Agent 回归报告”的固定页面。真正成熟后Harness 会成为 Agent 工程的基础设施不再是一个被人讨论热度的新鲜词。回到开头那句话。Codex Harness 的热度可能会变但“给 Agent 建立可复现的考试环境”这件事会一直留在 Agent 工程的工具箱里。与其争论它还能火多久不如把它拆开看一遍再在自己的项目里写下第一个任务 JSON。