AI Know · 技术研究笔记
Codex 的 harness 首次以 API 形式对外开放
单次调用即可托管运行 Agent 全流程；输入、执行、评测三段全部云端托管；开发者不必自建沙箱与调度层
听书暂不可用，请阅读正文。
三分钟读懂
先看结论，再决定是否深读
- Codex 的 harness 首次以 API 形式对外开放
- 单次调用即可托管运行 Agent 全流程
- 输入、执行、评测三段全部云端托管
- 开发者不必自建沙箱与调度层
- 公测阶段能力与配额仍有边界
核心原理
过去一年多，Agent 的工程难点从来不在"模型会不会规划"，而在"规划之后谁来执行"。文件系统、进程隔离、超时控制、重试、上下文压缩、工具调用的错误恢复，这些脏活构成了一个 harness。OpenAI 在 Codex 上打磨出的正是这套东西——它让一个模型可以在真实仓库里读文件、跑测试、改代码、再跑测试，直到任务收敛。
这次 Agents API 公测版的意义，是把这套 harness 连同它背后的基础设施封装成一个云端端点。开发者不再需要自己拼装沙箱、写调度循环、管理会话生命周期，只需一次 API 调用，就能把"给一个目标、让它自己迭代到完成"这件事托管出去。换句话说，OpenAI 卖的不再只是推理能力，而是"推理 + 执行 + 环境"的整套运行时。
这个转变值得重视：它把 Agent 从"框架问题"变成了"服务问题"。以前你要选 LangGraph 还是自己写状态机，现在多了一个选项——直接调 API。代价是控制权外移，收益是上线速度。
技术细节
输入侧。 调用方提交的是任务描述加环境上下文：目标指令、可用的工具集合、初始文件或仓库快照、以及约束条件（比如允许写哪些路径、单步超时多久）。关键设计在于 harness 把"环境"当成一等公民——你给的不是一段 prompt，而是一个可操作的工作区。上下文压缩、历史裁剪由服务端负责，开发者不必手工管理 token 预算。
推理与执行侧。 云端 harness 负责把任务拆成步骤，逐步调用工具、观察结果、修正计划。执行发生在隔离沙箱内，文件读写、命令执行、网络访问都受策略约束。这一层是 Codex 积累最深的部分：失败重试、循环检测、上下文溢出时的摘要回退，都是工程细节而非模型能力。对开发者而言，这一层是黑盒，只能通过配置项和观测输出间接影响。
输出与评测侧。 返回的不只是最终答案，而是完整轨迹：每一步的动作、观察、耗时，以及最终产物（补丁、文件、结构化结果）。这使评测成为可能——你可以按任务成功率、步数、token 消耗、墙钟时间四个维度打分，也可以对轨迹做回归比对。轨迹可见是这套 API 相对"黑盒 Agent"的最大优势，它让调试从猜测变成读日志。
工程实践
建议一：先把任务边界写死。 别一上来就给它开放式目标。选定一类高重复、可验证的任务，比如"修复失败的测试"或"按模板生成迁移脚本"，用明确的完成条件约束它。可验证性是 Agent 能收敛的前提，没有测试或校验步骤的任务，失败率会高得离谱。
建议二：把评测跑在接入之前。 用返回的轨迹建立基线：同一批任务跑三次，记录成功率与方差。方差大说明任务描述有歧义，而不是模型不行。先修 prompt 和环境，再考虑换模型或加工具。建议用下表做最小评测框架。
| 维度 | 观测指标 | 用途 |
|---|---|---|
| 效果 | 任务成功率 | 判断能力是否够用 |
| 稳定 | 多次运行方差 | 识别描述歧义 |
| 成本 | token 与步数 | 控制预算上限 |
| 时延 | 端到端耗时 | 判断能否进交互链路 |
建议三：权限最小化 + 全程留痕。 沙箱能写哪些路径、能调哪些外部接口，按最小必要授予。同时把每次调用的轨迹落盘归档，出问题时能回溯是哪一步越了界。别把生产密钥直接塞进环境。
风险边界
成本。 Agent 是多次推理的串联，单次任务可能触发几十步调用。token 消耗随步数线性增长，遇到不收敛的任务会持续烧钱。必须设置步数上限与预算熔断，否则一个死循环就能吃掉整月配额。
幻觉。 轨迹可见不等于轨迹正确。模型可能"自信地"声称某个测试通过了，而实际命令返回的是失败。凡是关键结论，都要在 harness 之外做独立校验，不能只信它自己汇报的结果。
越权调用。 Agent 会主动寻找达成目标的路径，这包括你没预料到的路径。如果沙箱策略过宽，它可能删除不该删的文件、调用不该碰的接口。权限边界必须由平台侧强制，而非依赖提示词约束。
长尾输入与延迟。 超大仓库、非标准构建系统、需要交互式输入的命令，都会让 Agent 卡住或超时。这类长尾场景在 demo 里见不到，在生产里占比却很高。上线前应准备降级路径：超时即回退到人工，而不是无限等待。
公测版的价值在于验证流程，而非直接扛生产流量。先把一类任务跑通、跑稳、跑便宜，再谈扩展。