从一次任务理解 Codex Harness：52 次函数调用背后的 Agent 工作环境
当我第一次在 Codex 的聊天框里输入「请帮我详细解释 Codex open source 中 harness 是如何实现的」时，我以为会得到一段漂亮的总结。结果 Codex 给了我完全不同的东西——它直接开始「干活」了。
打开对应的 rollout 文件后，我被震撼到了。这一个看似简单的问题，背后实际发生了 52 个 function_call 和 49 个 function_call_output。Codex 没有凭空回答，它真的去把整个 openai/codex 仓库拉下来，搜索代码路径，读取核心文件，最后才给出分析。
这让我瞬间明白了：Harness 不是模型的能力，而是模型得以「真正工作」的整个环境。
Codex 在这个任务里到底做了什么？
Codex 使用的核心工具非常务实：
exec_command：运行各种 shell 命令，包括git、curl、rg（ripgrep）、sed、jq等write_stdin：处理长时间运行命令的持续输出，比如git clone过程中的分段返回
它先确认仓库的官方来源，判断目标是 openai/codex 这个仓库；然后使用 sparse checkout 只拉取和 harness 相关的目录；再通过代码搜索找到所有与 harness 实现相关的关键路径，最后逐个打开核心文件进行阅读和分析。
整个过程像一个真正有「手脚」的工程师，而不是只会说话的咨询师。
六阶段拆解：一次任务的完整 rollout
从 rollout 记录来看，整个任务可以清晰拆成六个阶段：
1. 确认官方来源
Codex 先运行 git ls-remote 和 GitHub API，确认目标仓库身份和 codex-rs 目录结构，避免分析到 fork 或镜像仓库。
2. 精准拉取源码
使用 Git sparse checkout，只拉取与 harness 相关的 Rust 代码和配置文件，大幅减少不必要的数据传输。
3. 代码搜索与路径定位
通过 rg（ripgrep）快速搜索 “harness” 相关关键词，定位核心实现文件，避免大海捞针。
4. 深度阅读核心文件
逐个打开关键文件，理解 harness 的结构设计、工具注册机制、执行流程和安全边界。
5. 交叉验证与分析
结合多个文件的内容，进行逻辑梳理，理解 harness 如何为 Agent 提供工具调用、状态管理、权限控制等能力。
6. 基于事实生成回答
所有结论都有真实代码和执行记录作为支撑，而不是模型的「幻觉」。
这个过程让我第一次如此直观地看到：模型只是大脑，Harness 才是身体和操作系统。
Harness 到底是什么？
用一个最直白的公式来说：
Harness = Agent – Model
模型负责思考和生成，而 Harness 提供的是：
- 一张桌子：让 Agent 有地方工作，而不是每次从零开始搭环境
- 一套工具：
exec_command、read_file、search_code等真实可执行的能力 - 一份进度表：状态管理，让长任务不会断片
- 一些不能越过的边界：权限控制、安全规则、验证机制
- 一个会说「不算完成」的反馈系统：防止 Agent 自我感觉良好地胡乱宣布任务结束
它既给 Agent 自由，也给 Agent 限制。没有 Harness，Agent 只能「说」；有了 Harness，Agent 才能「做」。
从一次任务看 Harness Engineering 的本质
这次任务让我真正理解了 Harness Engineering 的意义。
它不是在模型之外再叠加一个「工程系统」这么抽象的概念，而是在解决一个非常具体的问题：
如何让 Agent 不必每次从零开始，也不能随便宣布完成？
- 旧的错误要能变成下一次的约束
- 反复出现的操作要能沉淀为 Skill
- 重要的判断边界要能固化到环境中
- 完成的标准不能由 Agent 自己说了算
当入口、上下文、工具、状态、反馈、边界这些元素连成一个系统时，Agent 的能力就不再依赖于单次对话的提示词长度，而是有了真正的「工作记忆」和「工作习惯」。
为什么这个理解很重要？
在国内使用 Codex 的最大障碍，其实不是模型本身，而是「怎么把模型安放在一个合适的工作环境里」。当我们把 Harness 和模型解耦后，就获得了极大的灵活性——可以用 Kimi、DeepSeek、GLM 等国产模型作为「大脑」，但依然使用成熟的 Harness 作为「身体」。
这也解释了为什么越来越多的开发者开始研究 Harness Engineering。它不是一个新概念，而是一个迟到的认知：真正决定 Agent 上限的，往往不是模型多聪明，而是它的工作环境有多完善。
你现在使用 Codex 或者其他 Coding Agent 时，不妨也做一次类似的实验。
随便找一个你想深入了解的概念，让它「解释自己」。然后去看看它的 rollout。你会发现，真正厉害的不是它说了什么，而是它为了回答这个问题，悄悄干了多少「看不见的活」。
这些看不见的活，才是 Harness 的全部意义。
（本文基于真实 Codex rollout 分析撰写，欢迎关注 Harness Engineering 系列，持续拆解 Agent 的平台层与工程实践。）