从 Codex App Server 理解 Agent Harness:模型之外还有什么
2026 年 OpenAI 介绍的 Codex App Server 将编码 Agent 的核心能力通过双向 JSON-RPC 暴露给不同客户端。同一个 Agent 既能出现在终端,也能出现在 IDE:关键不是每个界面各自实现模型调用,而是共享负责会话、工具和审批的运行层。
Harness 的职责
一个工程化的 Agent 循环至少包括:接收用户目标、收集上下文、调用模型、解析工具请求、执行工具、返回结果、决定是否继续。运行层还要维护线程状态、处理取消与超时、控制工具权限,并把进度和 diff 增量推送给界面。
这种设计带来一个重要边界:模型决定“想做什么”,执行器决定“允许做什么”。即使模型输出合法的工具调用,文件访问、网络访问和危险命令仍应由独立策略检查。UI 中的“批准”必须对应具体操作与参数,不能将一次批准扩展为不受限的永久授权。
如果自己做一个最小版本
先定义事件:message、tool_requested、approval_required、tool_finished、completed。每条事件带会话 ID 和单调序号,以便断线重连后恢复。长任务支持显式取消;执行器记录退出码、截断后的输出及耗时,不能只显示模型的自然语言总结。
不要把模型输出当成执行结果:补丁是否生效,应该通过文件 diff、测试退出码和审查记录验证。对于重试与并发操作,设计幂等键和状态机,防止“超时重试”重复提交。