您可以捐助,支持我们的公益事业。

1元 10元 50元





认证码:  验证码,看不清楚?请点击刷新验证码 必填



  求知 文章 文库 Lib 视频 iPerson 课程 认证 咨询 工具 讲座 Model Center 汽车系统工程   模型库
    学习助手
会员   
   
AI 赋能办公高效化实战案例分析
11月24-25日 北京+在线
AI赋能产品管理实战
12月10-11日 北京+在线
国产化数据库设计&优化
12月24-25日 北京+在线
     
   
 订阅
万字长文 | 深度解读 Codex Harness 源码
 
作/译者: 阿甘兄
  31   次浏览      1 次
 2026-11-19
 
编辑推荐:
本文从一次模型调用如何变成可持续运行、可观察、可打断的 Agent 出发,沿源码逐层拆解 OpenAI 开源的 Codex Harness:梳理 Model、Harness 与 Host 三层职责,Thread、Turn、Step、Item 四个核心抽象,以及仓库结构、主循环 run_turn、工具调度、沙箱与审批、历史压缩与恢复、app-server 控制面和 MCP 扩展机制,最后给出设计原则、接入方式与适用场景判断,帮助读者理解 Agent 发动机的完整工程实现。
本文来自于微信公众号阿甘兄,由火龙果软件Alice编辑、推荐。

继 DeepSeek 开源 DSH 之后,OpenAI 也发布了《Codex as a platform: build on the open agent harness》文章,并宣布开源 Codex Harness。那么:

Codex 是怎样把模型输出变成一个可持续运行、可观察、可打断的 Agent 的?

这篇文章,我们就沿着源码一路往下拆,看看 OpenAI 是如何把一次次模型调用,组织成一个真正可运行、可控制、可观察的 Agent。

01 Harness 是什么?

在阅读本文前,有几个概念需要先了解。

1.1 Model、Harness 与 Host

讨论 Agent 时最常见的混乱,是把这三层揉成一个词,先把边界画清楚,后面的源码就不会看得很吃力:

Host:可以理解为外壳,Codex CLI 是 Host,IDE 扩展是 Host,未来你在业务系统中嵌入的 “帮我排查异常” 面板也可以是 Host。

Harness:是可复用的中间层,它不拥有业务页面,但让 Host 获得一个能工作的 Agent。

Model:输出只是“建议说什么、调用什么工具”,没有 Harness,模型无法可靠地把建议转为真实动作。

官方文章把这种分工描述为:应用负责产品上下文、业务规则和工具,Codex app-server 提供 Agent loop 和受控执行。

1.2 Thread、Turn、Step 与 Item

源码里几乎所有对象都围绕着 Thread、Turn、Step、Item 这四种不同粒度的 “上下文” 展开,按时间尺度来分层如下:

可以这样去理解 → Thread 像项目文件夹,Turn 像一次工单,Step 像一次思考,Item 像工单日志。

这里需要补一个容易混淆、却很重要的源码边界:

  • Thread 是 app-server 协议层对外暴露的长期对象;
  • Core 内真正保存活动状态、输入队列和历史的运行时对象叫 Session。

为什么要额外有 Step ?

一个 Turn 往往要让模型思考很多次,例如先检索、再读文件、再修改、再跑测试,至少要经历四到五次模型采样,每次采样的工具可用性和上下文窗口都可能不同,所以 Step 是一个必须存在的中间快照。

1.3 模型调用工具闭环

严格说,模型不会直接运行 shell,也不会直接写本地文件,它会在响应流中产生 FunctionCall、CustomToolCall 等结构化 Item。

harness 读取到这个 Item 后,再根据当前 Step 的 ToolRouter 找到对应实现、执行、收集结果,并生成 FunctionCallOutput 写回模型历史。

因此,工具调用的一次完整闭环是:

“模型拥有工具”只是对体验的简写,从源码视角看,真正的所有者是 Harness,模型只是一个被授予了有限调用权的决策者。

02 项目结构

仓库克隆到本地后,目录如下:

虽然仓库包含 CLI、TUI、SDK、MCP、应用服务器等多种组件,理解 harness 时主要还是先看如下几层:

其中 app-server README 明确把核心对象定义为Thread → Turn → Item:

  • Thread 是长期对话
  • Turn 是一次任务,
  • Item 是这一轮中可持久化的用户消息、推理、命令、文件编辑等事实,这决定了 harness 如何保存和恢复工作。

2.1 根目录

仓库根目录大致如下(这里省略了构建缓存、三方依赖和大量支撑 crate):

codex/
├── codex-cli/               # Node.js 包装层、分发入口
├── codex-rs/                # 真正的 Rust 工作区:Harness 主体在这里
│   ├── cli/                 # 命令行前端
│   ├── tui/                 # 终端 UI
│   ├── core/                # 会话、Turn、Agent loop、工具与上下文
│   ├── app-server/          # 给桌面端/IDE/自建应用使用的 JSON-RPC 服务
│   ├── app-server-protocol/ # app-server 对外协议
│   ├── protocol/            # Core 内部 Thread/Turn/Item/事件协议
│   ├── tools/               # 工具定义与相关运行时能力
│   ├── sandboxing/          # 沙箱能力
│   ├── exec-server/         # 命令执行服务
│   ├── rollout/             # 任务记录、恢复相关能力
│   ├── thread-store/        # Thread 持久化存储
│   └── codex-mcp/           # MCP 连接与管理
├── sdk/                     # Python / TypeScript SDK
├── docs/                    # 用户和贡献文档
├── scripts/                 # 安装、打包、测试脚本
└── bazel/                   # Bazel 构建规则与平台支持

这里的 codex-rs crate(包) 特别多,这是正常的,因为它并不是把 “一次聊天”拆碎了,而是在把不同的系统边界拆开:协议、存储、沙箱、MCP、前端、执行器都可以独立演进。

真正回答 “Harness 怎么工作” 的主线,仍然集中在 core、tools、protocol 和 app-server 四处。

2.2 Core 的关键入口

codex-rs/core/src 是本文最重要的目录,特别需要关注的是下列文件和子目录:

core/src/
├── session/
│   ├── turn_input.rs      # 用户输入是启动、插话还是拒绝
│   ├── turn.rs            # run_turn:Agent 主循环
│   ├── turn_context.rs    # 本轮任务的固定上下文
│   ├── step_context.rs    # 一次模型采样的快照
│   ├── input_queue.rs     # 任务执行时收到的新输入
│   ├── inject.rs          # 将 Item 写回历史
│   └── mcp*.rs            # MCP 解析、预热与刷新
├── tasks/                 # RegularTask 等后台任务生命周期
├── tools/
│   ├── spec_plan.rs       # 生成本轮工具计划
│   ├── router.rs          # ToolRouter:可见工具与真实 handler 的映射
│   ├── parallel.rs        # 工具并发、独占与取消
│   └── handlers/          # exec、apply_patch、MCP 等具体 handler
├── context_manager/       # 模型可见上下文管理
├── compact*.rs            # 上下文压缩
├── exec_policy/           # 命令策略
└── sandboxing/            # 沙箱接入

看到这里,读源码的入口就确定了:从 session/turn_input.rs 接住一句话,走到session/turn.rs:run_turn,再下钻 tools/。

注意:这里不是从 CLI 参数、TUI 渲染或某一个具体 shell handler 开始。

如果一上来打开 core/src/session/turn.rs,会看到数千行 Rust、异步流、遥测、hooks 和 feature gate,很容易迷失,比较适合的路线是:

app-server/README.md
↓  先理解协议与生命周期
session/turn_input.rs
↓  看输入如何启动/转向一个 Turn
tasks/regular.rs + tasks/mod.rs
↓  看后台任务如何获得取消与完成生命周期
session/turn.rs::run_turn
↓  看主循环如何反复采样
tools/spec_plan.rs + tools/router.rs + tools/parallel.rs
↓  看工具计划、分派与并发控制
session/mod.rs::request_*_approval
↓  看人工审批怎样卡住真实执行

03 一条任务如何运行?

这里以“修复登录接口偶发 500,并运行测试”这条任务为例子,把源码中的对象和事件放进同一张时间线,流程图如下:

这张图里有两个比较重要的点:

  • 同一个用户 Turn 对应多次模型请求模型先决定读什么,读完再决定改什么,改完再决定跑什么测试,每一次工具结果都是下一次“思考”的输入。
  • UI 从不需要等最终答案才知道发生了什么app-server 以事件形式连续发出 Turn 开始、Item 开始/完成、文本增量、工具进度和审批请求,对宿主应用来说,harness 像一个持续产生事件的任务引擎。

下面开始进入源码入口。

3.1 接收任务:启动一个 Turn

描述:一句话如何变成一个后台 Turn? 对应源码: codex-rs/core/src/session/turn_input.rs中的 start_or_steer 与 start_if_idle;

以 app-server 为例,宿主应用先发送 turn/start ,它不会直接“调用模型然后等待答案”,而是快速创建 Turn 并异步执行,app-server 对外提供的生命周期是:

initialize
  → thread/start 或 thread/resume
  → turn/start
  → 持续接收 item/* 与 delta 事件
  → turn/completed

这也是为什么 Codex 的界面可以一边显示文字、一边展示工具调用和文件修改。

在Core内部,session/turn_input.rs 的 start_or_steer 会先判断输入到底应该:

  • 启动新 Turn;
  • 注入给正在运行的 Turn(steer,类似“中途补充要求”);
  • 或因状态不允许而拒绝。

若当前没有活跃任务,它会构造 TurnContext,整理附加上下文,随后调用 session.spawn_task(...),这一步非常关键:模型请求从此不是 UI 线程里的一个阻塞函数,而是一个带取消令牌的后台 SessionTask。

直觉上,可以把 TurnContext 看作“本次任务的工作身份证和基础配置”,但不要把它误解成所有设置永远不变。

真正固定一次模型请求的,是后面会讲的 StepContext:它捕获这一请求的有效设置、环境和工具路由,让已发出的请求不会在执行中途换规则。

3.1.1 任务准入:Start、Steer 与 StartIfIdle

用户看来都是 “发一条新消息”,但运行时必须做不同处理。

turn_input.rs 代码开头有这样一段注释:

Core 在一个地方决定输入是启动、转向,还是拒绝,它先回答请求已被接受到哪种状态,而不是等模型、hooks、持久化、采样全部结束后才回复,这样 UI 才能立即把发送按钮、取消按钮和运行状态更新正确。

如果只写一个 chat(prompt) 函数,很难支持这种能力,第二条消息该排队、打断、还是与第一条并行?若命令正在等审批,能不能再插一条消息?Codex 把这些问题收敛到 “Turn admission(回合准入)” 上。

3.1.2 请求快照: TurnContext 与 StepContext

谁负责长期身份,谁负责一次请求的冻结?

TurnContext 保存的是 "本次任务的长期身份和基础事实"(例如 Turn ID、来源、环境快照、输出约束、扩展数据、遥测状态,以及初始设置),它同时保有 “下一步可采用的当前设置”,因此,设置可以在安全的边界上为后续 Step 更新。

StepContext 是“在请求准备前捕获的一份不可变设置版本”,一次采样真正应以它为准,包含有效模型/服务等级/审批设置、环境与 ToolRouter。

因此更准确的关系是:

TurnContext:本次任务是谁、从哪里来、长期共享什么状态
  │
  └── StepContext:这一次模型请求看到并可执行什么

这带来关键工程属性:设置变化可以影响后续 Step 或后续 Turn,但不应让一个已经按旧 Step 发出的工具调用,在执行瞬间换了一套规则。

Arc 的意义也不只是 Rust 写法方便,而是让模型流、工具任务、审批等待和事件发送共享同一份任务身份。

决定一次动作权限的设置,则由对应的 StepContext 固定。

3.1.3 任务生命周期:SessionTask

让不同工作流共享一个任务生命周期

tasks/mod.rs 中的 SessionTask trait 抽象了会话内的异步任务,常规对话是 RegularTask,但同一个机制也能容纳压缩、审查、用户 shell 命令等工作流,它们共享的能力包括:

  • 后台 Tokio task 的启动与完成;
  • 统一的取消;
  • 统一的开始、完成、失败、被中断事件;
  • 通过同一个 Session 访问会话状态、事件发送和遥测。

持久化本身仍由 Session、history mode 和 thread store 等一起协作完成, SessionTask trait 并不是单一职责。

这种分工比在 CLI、TUI、IDE 中各自写一套“发请求、跑工具、处理取消”的逻辑更可靠。

UI 是可替换的,SessionTask 的生命周期才是 Agent 的生命线。

3.2 运行主循环:run_turn

描述:一句话真正开始被执行 源码位置: codex-rs/core/src/session/turn.rs 的 run_turn

源码注释已经把它的契约说得非常清楚:模型每次采样后,要么给出 function call,要么给出 assistant message,前者执行并把结果放回下一次采样,后者则意味着本轮可以结束。

把数百行关键调度逻辑压缩成伪代码,大致是:

async fn run_turn(...) {
    预先压缩过长上下文;
    解析本轮需要的 MCP / 技能 / 插件;
    记录用户输入和上下文注入;

    loop {         取出用户在运行期间追加的输入;         捕获一个 StepContext;         从 Session 的会话历史生成本次 prompt;         let result = run_sampling_request(prompt).await;
        if 需要继续 {             如有必要则压缩上下文;             continue;         }         break;     } }

3.2.1 三个关键机制

StepContext:一次采样的“快照”,不是全局可变配置

每次向模型请求前,run_turn 会捕获 StepContext,它把这一时刻的上下文、环境与工具路由器固定下来。源码注释强调:

同一个 request view 要同时用于上下文、向模型公布的工具,以及实际发生的工具调用。

这避免了一个很危险的竞态:模型根据工具 A 的说明发起调用,但执行时配置刚好刷新,工具 A 已被替换或权限已不同,以 StepContext 为边界,模型“看见什么”与运行时“允许什么”保持一致。

历史不是简单拼接,而是受控的模型输入

调用前会从 sess.clone_history() 取历史,再按模型支持的输入模态生成 prompt。

工具执行结果、用户中途追加的指令、插件/技能注入内容也会变成 ResponseItem 写回历史。

因此下一轮不是靠程序员手动拼一句“刚才命令输出是……”,而是由 harness 把事实按协议持续累积。

上下文满了不是直接失败,而是压缩后继续

run_turn 在采样前会检查,在循环中也会根据 token 状态决定是否 run_auto_compact,压缩后的内容仍作为历史的一部分继续参与后续工作。

官方文章也特别指出,保留推理与上下文压缩是 harness 会显著影响 Agent 表现的地方,这正是“模型很强”仍不等于“Agent 好用”的一个原因。

3.2.2 一次 Turn 的七个阶段

可以把 run_turn 主循环按源码顺序拆成七个阶段:

最值得注意的是第 4、5 步的顺序。

用户输入并不是仅存在于“前端聊天气泡”里,它要被写成模型可见的历史 Item。

工具输出也是一样,因此不管是正常结束、故障重试,还是下次恢复 Thread,都不会依赖前端还保有某段临时变量。

问题一:needs_follow_up主循环为什么知道还要不要再问模型?

答:模型的单次响应结束,并不等于用户的任务结束,SamplingRequestResult 中的 needs_follow_up 是一个很关键的控制信号。它可能来自:

  • 此次响应里启动了工具,工具结果需要交回模型解释;
  • 服务端明确表示 end_turn: false;
  • 用户在模型执行期间插入了新的输入;
  • stop hook 要求模型继续完成某个检查;
  • 上下文压缩完成后,任务需要在精简后的历史上续跑。

因此 run_turn 不以“收到 assistant 文本”作为唯一结束条件,而是组合模型、工具、输入队列和 hook 的状态来判断,这正是 Agent loop 与普通 streaming chat loop 的区别。

问题二:Hooks 为什么也属于 Harness?

从 run_turn 可看到 session start、turn stop、after agent 等 hook 的处理,它们说明 harness 不仅负责模型与工具,也为宿主的策略扩展留出了明确的生命周期点。

例如:一个团队可以在任务开始前注入仓库规则,在任务结束前检查测试是否真正运行,或在工具输出后附加审计信息,关键是这些机制由 runtime 在正确阶段调用,而不是要求模型“记得遵守”。

当然,hook 也是执行代码,生产中应把它视为需要审计的扩展面,而不是无限信任的提示词附件。

3.3 汇合模型、工具与 UI 事件

run_sampling_request 会创建 ToolCallRuntime,然后通过 client_session.stream(...) 获得模型的流式事件,它不是只监听 token 文本,而是分发多种 ResponseEvent:

  • OutputTextDelta:把增量文字推给前端;
  • ReasoningSummaryDelta:推送可展示的推理摘要;
  • OutputItemAdded:一个新的响应项开始,例如工具调用;
  • OutputItemDone:一个响应项完成,必要时启动工具;
  • Completed:本次模型响应结束,记录 token 使用情况并决定是否要继续。

所以 Codex 界面上的 “正在分析”“执行命令”“命令结果”“最终回答”不是前端猜出来的进度条,而是 harness 对模型流、工具流和会话生命周期做的统一事件化。

模型流 ResponseEvent
 │
 ├─ 文本 delta ──► AgentMessageContentDeltaEvent ──► UI
 ├─ 工具项完成 ──► ToolCallRuntime ──► 工具执行
 └─ response completed ──► 判断本轮结束/续跑/压缩

这也解释了为什么 app-server 对产品集成很重要。

CLI、IDE、桌面应用可以拥有完全不同的界面,但只要都消费同一组 Thread/Turn/Item 事件,就能复用同一个 Agent loop。

官方文章所说的 “应用拥有界面、业务上下文和工具,Codex 提供 agent loop 与受控执行”,在源码中就是这一层分工。

问题一:为什么不能只等response.completed再处理?

答:因为工具调用本身会改变下一步的上下文,try_run_sampling_request 一边从响应流 next() 读取事件,一边维护:

  • 当前正在显示的 Item;
  • 文本解析器与增量输出;
  • 正在执行的工具 future 集合;
  • 是否需要继续采样;
  • 当前工具参数的增量消费者;
  • token、模型信息与安全元数据。

遇到 OutputItemDone 时,harness 会调用 handle_output_item_done。

如果该 Item 是一次工具调用,它返回一个 tool_future,随后被放进 FuturesOrdered。

流结束后,drain_in_flight 会等待这些工具 future,把每个结果记录到会话历史中。

用一句话概括:模型流负责“提出动作”,工具 future 负责“完成动作”,harness 负责在两者之间搭一个不会丢结果的桥。

问题二:Item 生命周期如何帮助 UI 正确渲染?

答:同一条文本或同一项工具,通常会经历:

item/started → 若干 delta → item/completed

而 Turn 生命周期则是:

turn/started → 若干 Item 生命周期 → turn/completed / interrupted / failed

这两个层级不能混为一谈,一个 Turn 内可以有几十个 Item。

一个工具失败并不一定令 Turn 失败,因为模型可能读到错误结果后选择替代方案。

反过来,某个文本 Item 已完成也不代表 Turn 完成,因为它后面可能还有工具调用或用户追加输入。

这种事件模型对于 IDE 特别友好:侧边栏可显示当前任务状态,终端面板可绑定命令 Item,diff 视图可绑定文件编辑 Item,聊天面板只消费文本 delta,它们都来自同一条运行时事实流,而不是几套彼此不同的前端状态机。

问题三:为什么代码里还要处理“工具参数的 delta”?

答:某些自定义工具的参数也会被流式生成,Codex 不必等一大段参数 JSON 完整生成后才让 UI 有反馈,ToolArgumentDiffConsumer 可以把参数增量翻译成面向客户端的事件。

这在可视化场景尤其有意义,比如模型正在构造计划、填写复杂表单,或逐步准备一项动态工具调用时,界面可以展示“正在准备什么”,而不是突然跳到“已执行”,但真正开始执行仍要等待完整、已验证的调用 Item,这保留了安全边界。

问题四:流式体验与事实持久化是两条线

答:再强调一个很容易误解的点:delta 是为了低延迟展示;最终的 Item 才是用于恢复和后续推理的事实。

前者可以被 UI 选择性忽略,后者必须被完整记录,这样即使某个客户端断线或没有显示中间输出,Thread 仍能从已完成 Item 重建合理历史。

3.4 调度工具:从调用到回填

很多 Agent Demo 的工具调用很简单:模型输出 JSON,程序 if name == "search" 就执行,但 Codex 的工具层要处理更多问题,例如工具有哪些、模型是否可见、是否可并发、如何取消、结果怎样归档、失败怎样反馈给模型。

3.4.1 工具路由:ToolRouter

工具目录与执行目录必须对得上

ToolRouter 同时保存:

  • model_visible_specs:发送给模型的工具说明;
  • ToolRegistry:真正能执行的 handler;
  • tool mode、命名空间、代码模式工具名等元数据。

它的角色像机场塔台:不是直接开飞机,但负责保证 “塔台允许起飞的航班” 与“跑道上真的能起飞的航班” 是一组。

前文的 StepContext 会持有这个 router,确保本次调用与本次广告给模型的工具清单一致。

3.4.2 并发、独占与取消:ToolCallRuntime

描述:把并发、独占与取消包进一次调用 源码位置 /codex-rs/core/src/tools/parallel.rs:74 与 /codex-rs/core/src/tools/parallel.rs:155。

模型决定调用某工具后,ToolCallRuntime::handle_tool_call 将其转交给路由器。源码并没有盲目并发,它先询问 router.tool_supports_parallel(&call),然后使用 Tokio 的 RwLock:

  • 可并行工具获取读锁,彼此可以同时进行;
  • 必须独占的工具获取写锁,会等待其他并行工具完成。

这比“永远串行”更快,也比“全部并行”更稳。需要特别严谨地说:

源码并不会自动从“这是读操作/写操作”推断并发安全性,而是由每个工具运行时声明supports_parallel_tool_calls,多个检索工具通常可能声明可并行,有共享状态的工具通常应声明独占,但这属于工具实现者给出的契约,而非这一把锁自动识别文件读写后的结论。

更重要的是它监听 CancellationToken,用户中断 Turn 时,尚未完成的工具任务会被取消,并产生一个可写回模型上下文的“已中止”结果,而不是悄悄消失,这样模型至少知道工具没有成功完成,下一步不会建立在错误假设上。

3.4.3 一次工具调用的四层形态

从 “模型决定调用工具” 到 “模型看到结果”,同一次动作会以四种形态出现:

层次 形态 例子
模型协议层 ResponseItem::FunctionCall exec_command({ cmd: "rg login" })
路由层 ToolCall 解析工具名、call id 和参数内容
执行层 handler / runtime 选择 shell、MCP 或 apply_patch 的真正实现
回填层 FunctionCallOutput stdout、错误信息、结构化结果

这样分层的一个直接收益是:

  • 工具实现失败时,不一定要让整个 runtime 崩溃;
  • ToolCallRuntime::handle_tool_call 区分 fatal 错误与普通工具错误;
  • 后者会包装为模型可读的失败结果,给模型继续决策的机会;
  • 只有 runtime 不可继续的 fatal 情况才会向上冒泡。

这很符合真实工作流:rg 没找到文件、测试命令退出码非零、MCP 服务暂时不可用,都不代表任务必然失败,模型应该有机会解释、重试或换路径。

3.4.4 工具层的关键问题

问题一:为什么 ToolRouter 同时保存“可见规格”和“可执行实现”?

答:这是一条很重要的安全不变量:

 本次发给模型的工具 schema ≈ 本次运行时允许分派的实现 

如果只维护一个工具名称字符串,很容易出现两类问题:

  1. 前端或模型以为某工具可用,运行时却没有 handler;
  2. 运行时悄悄保留了模型根本没被告知的工具,造成不可解释的越权执行面。

ToolRouter 和本次的 StepContext 共同避免了这种“广告与实际商品不一致”,工具还可以有命名空间、延迟发现(tool search)、code mode 内嵌工具等不同暴露方式,因此源码没有把它设计成一个朴素的 HashMap。

问题二:并发控制的真实含义:不是“快”,而是“可预测”

答:parallel_execution 使用读写锁的思路值得单独说。多个被标记为可并发的工具可以持有读锁,需要独占的工具取得写锁。它实现的不是“尽可能把所有任务同时跑”,而是把能并行的只读或互不影响操作与应当串行的有状态操作区分开。

例如,三个代码检索任务并行通常没有问题,但两个依赖同一终端状态的操作、两个可能改同一文件的操作,若随意并行,模型收到的结果顺序可能与真实状态不一致,对 Agent 来说,可预测性往往比理论并发度更重要。

问题三:工具结果为什么必须回填而不能只展示给用户?

假设模型执行了测试,UI 看到了失败日志,但模型没有把日志放入下一轮上下文,此时模型下一次“思考”会忘记测试失败的原因,只能重复尝试或胡乱总结。

因此每个工具结果既是面向用户的可见反馈,也是面向模型的新证据。

这就是 harness 的核心闭环:它不是一台“命令执行器”,而是一台“把行动后果转化为下一次推理证据的机器”。

3.5 执行前的安全边界

描述:按策略审批,审批通道失效时中止 源码位置: /codex-rs/core/src/session/mod.rs:2596 、 /codex-rs/core/src/session/mod.rs:2689、/codex-rs/core/src/tools/sandboxing.rs:64、/codex-rs/core/src/tools/handlers/unified_exec/exec_command.rs:302

“需要确认”若只是 UI 上一个弹窗,安全性并不可靠,真正的保证必须在执行路径上。

并非每条命令和每个补丁都会进入审批,是否需要审批由当前权限与审批策略决定,一旦执行器决定请求审批,Codex 使用下面这个异步等待模式:

工具准备执行命令
      │
      ▼
Session 创建 oneshot channel,并以 approval_id 登记等待者
      │
      ▼
发送 ExecApprovalRequest 事件给 UI/宿主应用
      │
      ▼
工具 await 用户决策
      │
      ├─ 批准:继续执行
      ├─ 拒绝:产生拒绝结果
      └─ Turn 被中断/连接结束:默认为 Abort

Session::request_command_approval 先把 oneshot 的发送端放入活跃 Turn 的待审批表,再发出事件,最后 await 接收端,没有决策就不能继续。

文件修改也有相同模式的 request_patch_approval,特别值得注意的是,如果等待者被清理,unwrap_or(ReviewDecision::Abort) 会把它当成中止,而不是偷偷放行。

这就是 harness 与 “让模型自己在 prompt 里承诺谨慎” 之间的本质区别:prompt 是建议,审批通道是执行控制。

3.5.1 沙箱、策略与审批

很多介绍把它们都写成 “安全机制”,但两者职责不同:

机制 它回答的问题 典型结果
沙箱(sandbox) 这个进程客观上能访问什么? 读写范围、网络、系统调用被限制
执行策略(exec policy) 这个命令是否符合预先规则? 自动放行、要求确认、拒绝
审批(approval) 这次具体动作是否有人允许? 暂停等待、批准、拒绝、终止
工具 schema 模型被告知能调用什么? 模型侧可见能力边界

最安全的设计不是只依赖其中任意一层,而是叠加防线。

模型即使错误地产生了危险命令,工具 schema 可能不让它请求,策略可能拒绝,沙箱也可能让命令实际失败,即便可以执行,也可以在有副作用前等待用户批准。

3.5.2 审批机制的关键问题

问题一:审批请求里为什么有 call_id、approval_id、cwd ?

答:审批不能只是一个全局布尔值“用户刚才点过允许”,源码里的 ExecApprovalRequestEvent 包含调用 ID、可选审批 ID、Turn ID、环境 ID、命令、cwd、原因、网络相关上下文及可选的策略修订建议。

这些字段解决的是并发场景的身份问题:

  • 哪个 Turn 在等批准?
  • 哪一次工具调用在等?
  • 用户批准的是哪条命令、在哪个目录执行?
  • 如果有多个子命令或 stdin 写入,回包应唤醒谁?

因此,Session 先把 oneshot 发送端插入当前 Turn 的待审批表,再发事件,顺序不能反过来,否则 UI 极快地回复时,运行时尚未登记等待者,就会出现“批准丢失”的竞态。

问题二:为什么断线和中断默认是 Abort?

答:安全系统的一个基本原则是 fail closed(失败时关闭),当用户中断 Turn、审批通道被清理,或接收端没有决策,源码把结果归为 ReviewDecision::Abort,这比 “因为用户没反对,所以继续”更保守。

对于 Agent 尤其重要:它可能处于长时间工具调用中,UI 崩溃、网络波动或线程切换都不应等同于用户授权。

Harness 在执行链路上把这种不确定性转换为显式中止结果,交给模型或用户重新决定。

问题三:文件修改审批与命令审批为什么分开?

答:命令审批关心的是可执行命令、环境、网络或额外权限。补丁审批关心的是具体文件变更及写入范围。

源码分别提供 request_command_approval 和 request_patch_approval,这让宿主 UI 可以按风险呈现不同界面:

  • 命令可以展示解释后的 argv、cwd、网络访问请求;
  • patch 可以展示文件列表、diff、写入根目录和理由。

从产品角度看,这比只弹一个 “是否允许 Agent 继续?” 更透明,从 runtime 角度看,这使批准信息始终绑定实际操作对象,而不是绑定抽象的模型意图。

问题四:一个需要避免的误解

答:审批不是把所有决定都甩给用户,恰恰相反,harness 的职责是用策略和沙箱自动处理低风险、可预测的路径,只把有意义的边界升级给人。若每个 ls 都弹窗,系统虽然“安全”,却不可用,若所有写入都静默,系统虽方便却失控。

合适的 harness 要把 “用户何时必须介入” 做成可配置的运行时策略。

3.6 保存任务事实:历史、压缩与恢复

一个 Agent 真正难的地方,往往不是“第一次请求模型”,而是“第十次之后还能不能记住正确的事情”。

Codex 的源码里,历史并非前端临时数组,而是一套会话状态与 rollout 持久化共同维护的事实记录。

3.6.1 两类历史

两类历史分为 “给模型的历史” 与 “给人/系统的记录”,它们会重叠,但不完全相同:

内容 是否通常进入模型上下文 为什么要保存
用户消息、工具调用、工具结果、助手消息 是 让下一步推理建立在真实事实之上
Turn 开始/结束、token、错误等事件 视情况 让 UI、诊断和恢复知道发生过什么
TurnContext、环境和策略快照 主要供恢复与审计 解释过去这次任务为何能/不能做某动作
文本 delta 不作为最终事实 只用于低延迟展示

这就是 Item 模型的价值:一条历史不是只有“用户说了什么、助手答了什么”,还包括 Agent 做过什么以及看到过什么。

3.6.2 工具结果如何写回历史?

把结果变成下一轮的依据

工具 future 完成后,drain_in_flight 会将响应包交给 record_annotated_conversation_items。

下一次 clone_history().for_prompt(...) 时,这些结果就会参与生成 prompt,也就是说,模型不依赖隐式内存,而是通过被正式记录的 Item 获得过去的证据。

这会形成一个工程上极其重要的闭环:

执行命令 → 得到 stdout/stderr → 记录为 Item → 下次采样可见 → 决定后续动作

如果你在自研 Agent 时遇到 “它刚看过日志却马上忘了”,大概率是工具结果只显示给用户而没有以一致格式写回模型上下文,或历史被截断时没有正确总结。

3.6.3 Rollout:恢复、分叉与审计

为什么 Thread 可以恢复、分叉和审计?

仓库中多处使用 RolloutItem、RolloutRecorder 和 InitialHistory。

从测试和 session 实现可看到,rollout 能记录响应 Item、TurnContext、压缩记录、token 使用和事件,恢复 Thread 时,运行时读取这些记录,重建初始历史和必要状态;分叉 Thread 时,则复制相应历史前缀。

所以 “继续这个任务” 不是把上一轮 final answer 重新塞给模型,而是恢复一串足以解释当前状态的工作事实,更严谨地说:

record_conversation_items 先保证 Core 的模型工作历史完整; 是否以及如何写入可恢复的 Thread 存储,还取决于当前 history mode 与 thread store。

桌面端能显示历史、SDK 能继续 thread、app-server 能 fork,背后依赖的正是这两层记录模型。

3.6.4 上下文压缩

上下文压缩不是简单摘要

当 token 预算逼近限制时,run_turn 触发自动 compact。

它的目标不只是把文字缩短,而是以压缩后的历史替代部分旧上下文,同时保持后续任务仍能工作,源码还会区分压缩发生在本轮前还是本轮中,并记录原因和阶段。

这与 “把整段聊天交给另一个模型总结一下”相比,工程要求更高:压缩必须与历史持久化、上下文窗口、下一次 prompt 构造和错误恢复配合。

错误的压缩会让模型忘记已经修改了哪些文件、测试为何失败,或者重复执行副作用动作。

3.6.5 Harness 作为外部记忆

描述: 一个实用的理解:Harness 是 Agent 的外部记忆管理器 源码位置: /codex-rs/core/src/session/inject.rs:110、/codex-rs/core/src/session/mod.rs:3305、/codex-rs/core/src/session/turn.rs:1198。

模型在一次请求中的上下文窗口有限,Harness 则管理跨请求、跨 Turn 乃至可恢复会话的外部记忆,它决定哪些事实必须精确保留,哪些可以总结,哪些只给 UI 看,哪些要进入审计记录。

这个层的质量,直接决定长任务会不会“越做越忘”。

3.7 处理运行中的变化:取消、失败、重试与插话

Harness 的价值恰恰在于它把这些“非理想情况”变成明确的状态转换,而不是随机卡死。

真实 Agent 不会总是顺利完成:模型流可能断开,工具可能报错,用户可能临时改变主意,上下文可能用尽,MCP 服务也可能没有启动。

3.7.1 三种停止方式

情况 谁触发 对模型/历史的意义
正常完成 模型没有后续动作且无待处理输入 记录最终消息,Turn complete
工具失败 命令、MCP 或 patch 失败 写回失败结果,通常可让模型继续
用户中断 UI/Host 请求 interrupt 取消当前任务,避免新副作用继续发生

其中“工具失败”不等于“Turn 失败”,例如测试失败常常正是模型需要分析的证据。

只有流无法恢复、配置不合法、上下文无法处理等更高层故障,才会走 Turn error 生命周期。

3.7.2 异常处理的关键问题

问题一:取消为什么要沿整条调用链传播?

答:run_turn、run_sampling_request 和 ToolCallRuntime 都接收或派生 CancellationToken,这是为了让用户点击停止后,模型流、工具 task、审批等待不再各自悬挂。

尤其是在 ToolCallRuntime 中,源码以 tokio::select! 同时等待工具结果和取消信号。

如果取消先到,会中止调度任务、发送工具中止通知,并构造中止结果。

它避免了一个危险场景:UI 已显示“已停止”,后台命令却还在继续改文件。

问题二:模型流失败时,为什么还要有重试状态?

答:run_sampling_request 周围有 ResponsesStreamRetryState 和 provider 给出的最大重试次数。网络抖动、可重试的上游错误不应立即摧毁一个已经运行很久的任务。但重试也必须有上限,并复用本 Turn 的客户端会话状态,避免随意换路由或重复写入历史。

可以注意到,工具结果在正确时机记录、请求输入有清晰的 original_input 处理,这都是为了让“重试一次模型流”不会误把已完成的工具当成应重复执行的动作。

问题三:中途插话(steer)如何不打乱当前任务?

答:当用户在 Agent 工作时补充消息,输入会进入 input_queue。

主循环每次采样前会决定是否可以 drain pending input,并把它写进历史再形成下一次 request。这个设计让“中途插话”成为可控的调度行为,而不是粗暴地杀掉当前任务后重开一个。

当然,不是任何时机都立即插入,源码在新 Turn 的起始和自动压缩等情形会暂缓 drain,优先保证当前模型/工具连续性。

这里体现了 harness 的取舍:既响应用户,又不让正在回填的工具结果和新指令产生乱序。

问题四:背压为什么出现在 app-server README?

答:app-server 采用有界队列连接传输入口、请求处理和外发写入,当入口饱和时返回明确的可重试过载错误,它看起来离“Agent 智能”很远,但实际上决定了高频 UI 或多个集成客户端能否稳定使用 harness。

没有背压,慢客户端可能把内存不断堆满,没有明确错误,调用方会误以为请求已执行。

好 harness 设计不仅要会处理模型不确定性,也要会处理 I/O 不确定性。

3.8 app-server:Harness 的控制面

源码位置 /codex-rs/app-server/README.md:66

app-server 把核心运行时包装成了稳定的、本地的双向协议,它使用 JSON-RPC,客户端发 thread/start、turn/start、turn/interrupt 等请求,服务端持续反向推送 item/started、文本 delta、工具进度和 turn/completed。

因此可以把责任划分成下面这样:

应用自己负责 Codex harness 负责
页面、编辑器、任务列表、业务字段 采样循环和上下文延续
哪些业务数据值得提供 工具描述、调用、结果回填
哪些业务动作应由人确认 沙箱、权限策略与审批等待
如何展示运行进度 把统一运行状态变成事件流

这正是官方文章强调的集成价值:不要把所有业务迁入一个通用聊天框,而是把 Agent 放入用户本来就在使用的仪表盘、IDE、工单系统或操作台。

对产品开发者来说,最实用的理解是:app-server 不是另一个聊天接口,它是 harness 的远程控制面板。

它还使用有界队列处理传输、请求处理和向外写入之间的背压,队列饱和时会明确返回可重试的过载错误,这说明开源 harness 还承担了运行时工程问题,而不止是模型调用编排。

3.8.1 app-server、SDK 与 codex exec

官方文章给出的分层很实用,也与仓库的组织一致:

需求 更合适的接入层 原因
一次性脚本、CI、后台定时任务 codex exec 任务边界清晰,只需取最终/结构化结果
程序里发起、等待或流式消费任务 SDK 少写进程和协议管理代码
你有自己的复杂界面、审批流、长期 Thread app-server 直接控制 Thread、Turn、事件和审批生命周期

不要因为 app-server 名字里有 “server”就误以为它只适合云端部署,它本质是本地 Codex 进程向宿主界面暴露的控制协议,桌面端、IDE 扩展、或本地业务工具都可以连接它。

3.8.2 为什么采用双向 JSON-RPC

Agent 在运行中既要不断向 UI 推事件,也要随时接收 UI 的新控制:批准、拒绝、追加输入、中断、更新设置、恢复或分叉 Thread。

SSE 擅长单向推送,但难以自然描述“服务器请求用户批准,用户再回一个精确决定”的交互。

双向 JSON-RPC 让 app-server 同时成为:

  • 客户端发起 turn/start、turn/steer、turn/interrupt 的命令入口;
  • Harness 推送 Item 与 Turn 生命周期事件的事件源;
  • Harness 发起审批/elicitation 请求、客户端回复决策的双向通道。

从协议设计上看,这正是把 Agent 装进现有产品所需的能力:产品不需要让步成一个纯聊天页面,Agent 也不需要放弃自己的控制和安全回路。

3.8.3 事件驱动集成的基本模式

下面并非可直接运行的 SDK 代码,只展示宿主应用要遵守的控制节奏:

注意这里 “展示工具 Item” 和 “回复审批” 都是业务应用自己的 UI 决定;harness 只提供事实和控制接口,这也是它能适配 CLI、IDE 与复杂内部系统的原因。

3.9 扩展能力:MCP、Skills、Plugins 与多 Agent

这几个词经常一起出现,但在 harness 中承担的职责并不相同。

3.9.1 MCP:接入外部能力

MCP 的核心价值不是“让模型访问更多东西”,而是给 harness 一个标准化的工具和资源接入点。

run_turn 会先根据用户输入识别所需 MCP server,在捕获 StepContext 时确保当前请求视图包含它们,模型调用 MCP 工具后,结果同样会成为 Item,进入下一次推理。

例如:你的运维平台可将“查询告警”“读取服务日志”“创建变更单”做成 MCP 工具,Harness 仍负责工具选择、事件、失败结果和审批,应用仍负责业务身份、真实数据和最终写操作边界。

所以 MCP 不是绕开 harness 的后门,而是 harness 管理外部能力的一种标准接口。

3.9.2 Skills:加载工作方法

从 run_turn 的 build_skills_and_plugins、明确 skill invocation 等调用可看出,Skills 主要贡献的是受控注入的指令与依赖信息。

可以把它理解为按需装载的专业操作手册,处理表格时告诉模型应遵循怎样的流程,处理某个团队的部署时告诉它相关规范和工具前置条件。

Skills 与普通用户 prompt 的区别在于:harness 知道它们来自哪里、何时注入、大小需要受限,也会把它们纳入本轮上下文规划,它们扩展了模型的工作方法,但不等于自动获得任意系统权限。

3.9.3 Plugins:交付扩展能力

Plugins 往往把 Skills、MCP、资源或其他扩展能力组织成可发现、可启用的包 ,当前输入中若明确提到插件,run_turn 会参与构造相应注入和工具选择。

对模型而言,这让它得到适合任务的指令与能力,对 Host 而言,则多了一层管理安装、启用、权限与来源的机制。

可以用一句话区分:MCP 更像能力插座,Skill 更像操作手册,Plugin 更像把插座、说明书和相关资源一起交付的扩展包。

3.9.4 多 Agent:在同一运行时内协作

多 Agent 很容易被误解成 “主模型写个 prompt 再调用几个子模型”。

Codex 的源码把子 Agent 管理也暴露为工具/运行时能力,父/根 Turn 关联会被记录,并且运行时会对模型、设置与审批边界施加约束。

具体哪些设置可继承或覆盖,会随多 Agent 版本、fork 方式和启动选项而变化,不能把它简单理解为 “子任务天然拥有父任务的一切权限”。

这很关键:若子 Agent 的权限与父任务脱钩,主任务原本受限的工作区可能被子任务绕过,让多 Agent 仍运行在同一套 Thread/Turn、工具路由、审批与事件体系下,才能让并行分工不破坏安全和可观察性。

无论是 MCP、Skill、Plugin 还是多 Agent,它们都不应该跳过下面这条主链:

被选择/加载 → 纳入 StepContext → 模型可见 → Router/策略验证 → 执行 → Item 回填 → 事件可见

只要仍在这条链上,扩展就能共享日志、取消、审批、持久化与恢复,一旦绕过它,系统会重新回到 “各自运行、难以审计” 的脚本拼接状态。

04 Harness 为什么这样设计?

前面按时间顺序追了一遍 “一句话” 如何被接收、思考、调用工具、等待批准和保存结果,若只停在函数调用关系,仍然很难判断 Codex 为什么要写成现在这样。

下面把代码背后的几条设计思想单独拎出来。

4.1 从单次调用到可控任务

普通聊天接口的抽象非常简单(请求进来,响应出去),但 Agent 任务的真实形态是:请求进来后,模型需要先观察环境,再采取一个行动,再阅读行动结果,再决定下一步,而且这个过程可能持续数分钟甚至更久。

因此 Codex 没有把核心写成一个 ask_model(prompt) 函数,而是把一次工作建模为 Thread、Turn、Step 和 Item:

run_turn 的循环、工具结果回填和 needs_follow_up,都是这一思想的直接结果,没有这层 runtime,模型只能“提议怎么做”,不能稳定地把工作推进到结束。

4.2 StepContext:让决策与执行保持一致

Codex 在每次采样前捕获 StepContext,不是为了增加抽象层,而是为了避免 Agent 最危险的一类问题:模型根据旧的工具列表或旧权限作出决定,执行时环境却已改变。

所以一个 Step 同时固定:本次 prompt、模型可见工具、实际 ToolRouter、环境和设置,可以把它看作一次“交易快照”——在模型决定和工具执行的这一小段时间里,规则保持一致。

这条思想对所有生产 Agent 都很重要:不要只在 UI 或配置层维护权限;执行器必须拿到与模型决策同源的、可验证的快照。

4.3 Item:让行动结果成为下一步证据

人类在排查问题时会自然记住 “刚才测试失败,因为端口被占用”,模型不会自动拥有这种跨调用记忆。

Codex 会把用户输入、工具调用、工具结果、助手输出等写入模型工作历史,下一次采样再从历史中重建 prompt。

在支持持久化的 Thread/history mode 下,相应记录还会成为恢复与审计的依据。

这正是 harness 最值得复用的洞见之一:行动不是推理的终点,行动结果是下一步推理的输入。

因此,命令输出、MCP 查询结果和 patch 结果不该只显示在屏幕上,若它们没有写回一致的模型历史,Agent 就会出现“刚做完就忘了”的现象,长任务也无法可靠恢复。

4.4 状态机:承接运行中的不确定性

模型流会断,工具会失败,用户会插话,审批会被拒,网络会慢,若所有异常都靠提示词要求模型“请自行妥善处理”,系统的行为将不可验证。

Codex 选择把这些情况编码成 runtime 状态:重试状态、输入队列、取消令牌、审批通道、完成/中断/错误事件以及有界队列,也就是:

  • 提示词负责:在已给定事实与能力下,建议下一步。
  • 状态机负责:事实何时生效、能力是否可用、异常如何收敛

这也是为什么 Harness 不能被简化成一段很长的 system prompt,Prompt 可以引导行为,无法替代并发控制、权限校验和持久化语义。

4.5 分层安全:为行动划定边界

一个常见误解是有审批和沙箱,模型就“不自由”,从 Harness 视角,更准确的说法是:模型可以在明确边界内高效行动,越过边界时必须把决定交还给人。

Codex 的工具 schema、ToolRouter、沙箱、执行策略和审批共同形成分层边界,它们允许低风险操作自动完成,也能在文件修改、网络访问或额外权限等节点要求确认。

这里的目标不是让模型“什么都不能做”,而是让每一步都可解释、可审计、可中断。

4.6 UI:订阅事实,而非保存状态

CLI、TUI、IDE 和桌面端都能驱动同一个 Harness,原因不是它们长得像,而是它们都可以订阅同样的 Thread/Turn/Item 事件。

UI 负责展示和交互,运行时负责事实和生命周期。

这条边界让产品层可以大胆变化:你可以把 Agent 放进代码编辑器、告警面板或工单系统,而不用在每个界面里重写一套工具调度、审批等待和取消逻辑。

4.7 放回一条真实任务中理解

把上面六条合起来,就是 Codex Harness 的价值

从这个视角看,Codex Harness 不是一个 “帮模型调工具的辅助库”,而是 Agent 在现实环境中工作的操作系统雏形。

假设用户说:“修复登录接口偶发的 500,并跑测试” ,Harness 实际做的不是一次生成,而更像下面的过程:

1. 提示词负责在已给定事实与能力下,建议下一步。

2. 状态机负责事实何时生效、能力是否可用、异常如何收敛app-server,接收 turn/start,Core 创建TurnContext,并为首次采样捕获包含 cwd、模型、审批策略和可用工具的StepContext;

3. run_turn 将用户要求、仓库指令、历史和工具说明送入模型;

4. 模型请求 rg、读取代码,harness 执行并把输出作为 Item 记入历史;

5. 模型根据结果请求修改文件,若策略要求确认,执行器等待用户批准;

6. 修改结果和diff进入历史,模型再请求运行测试;

7. 测试失败,输出再次进入历史,模型继续定位;

8. 模型最终输出总结,且没有待执行工具,Turn 完成。

在这个过程中,模型负责“下一步应做什么”,harness 负责“这一步能否做、如何做、结果如何保存、如何让人看见、何时停止”。

05 如何把 Harness 接入产品?

5.1 产品与 Harness 的职责边界

如果你要把 Codex harness 接入一个已有产品,建议采用下面的职责分层:

例如,在客服系统中,用户点击“分析这个升级案例”时,产品把当前客户、最近工单、日志范围作为业务上下文提供给 Agent。

Agent 经由 MCP 查询最新信息。

需要向客户发送邮件时,系统把它设计成需审批的工具调用。

用户批准后,系统执行真实发送动作并刷新自己的记录。

这里最重要的原则是:业务系统仍是系统记录(system of record),Harness 不是你的数据库。

Harness 管理 Agent 的推理和动作闭环;业务系统继续拥有业务状态、鉴权、数据一致性和最终写入规则。

5.2 五个接入要点

产品集成时,最容易漏掉的五件事:

  • 【把业务上下文结构化地给出来】:不要只把整页 HTML 或数十页日志塞进 prompt,应提供当前对象 ID、可用字段、关联资源和受控查询工具。
  • 【把写操作设计成显式工具】: “请模型直接拼一个 HTTP 请求”不如提供 create_draft_ticket、rebook_shipment 这类带 schema 和审批语义的工具。
  • 【在 UI 中展示 Item,而不只展示最终回答】:用户需要看到 Agent 查了什么、改了什么、卡在什么审批上,才能真正信任它。
  • 【保留取消与重连语义】:长任务不可避免会被用户中断或客户端断开,不要把任务状态只存在浏览器内存中。
  • 【先定义风险边界,再调整模型提示词】:哪些文件可写、哪些工具只读、哪些动作需要批准,应由权限和策略承载,不要只写一句“请小心”。

5.3 哪些场景需要 Harness

注意也要避免过度设计。若场景只是“把一段文本转成 JSON”或“对单份文档做一次摘要”,直接调用模型通常更简单、成本更低,Harness 的价值在于下面的信号出现时:

  • 任务需要多步观察—行动—再观察;
  • 需要调用外部工具或改动真实状态;
  • 用户需要实时看到过程或能在中途介入;
  • 任务可能很长,需要压缩、恢复、取消或重试;
  • 需要明确的权限、审计和审批机制。

换句话说,Harness 不是让每个 prompt 都变复杂,而是当“模型输出要进入现实世界”时,给这个过程加上工程化护栏。

06 常见问题

问题一:Harness 是不是就是 ReAct?

不是。ReAct 可以描述“推理—行动—观察”的模式;Harness 是把这种模式落到生产运行时的完整工程系统。它还要处理流式输出、并发、取消、上下文预算、持久化、沙箱、审批、协议和 UI 集成。

问题二:Harness 会让模型更聪明吗?

它不会改变模型权重,但会显著影响模型能否在长任务中拿到正确上下文、使用正确工具、避免重复动作,并在失败后继续。这就是为什么官方文章强调 harness 设计会影响 Agent 结果。OpenAI 官方说明

问题三:Codex 的开源仓库是不是包含模型?

不是本文讨论的这一层。开源仓库主要公开的是 CLI、核心运行时、app-server、SDK 和相关集成表面;模型访问和托管服务是独立部分。官方文章也明确区分了开源 harness/integration surface 与模型访问、托管服务。

问题四:最核心的源码入口到底是哪一个?

若目标是理解“Agent 怎么跑起来”,从 session/turn.rs::run_turn 开始;若目标是理解“产品如何控制 Agent”,从 app-server 的 turn/start 生命周期开始;若目标是理解“为什么工具安全”,从 ToolRouter 和 request_command_approval 开始。

至此可以给 Codex harness 一个完整但不神秘的定义:它是一套把模型的下一步决策,转换为带上下文、工具、权限、人工控制、事件和持久化的真实任务执行过程的运行时。

07 总结

如果只记住三句话,我建议是:

  • 它是循环,不是单次调用: run_turn 持续把模型输出、工具结果和新输入编排成下一次采样。
  • 它是运行时,不是提示词模板: ToolRouter、并发闸门、取消令牌、沙箱与审批把“会说”变成“能安全地做”。
  • 它是集成层,不是固定 UI: Thread/Turn/Item 和 app-server 事件协议,使 CLI、IDE 或业务系统可以共享同一个 Agent 内核。

从这个角度再看 Codex,CLI、桌面端和 IDE 扩展只是不同外壳,真正可复用的部分是中间那台“Agent 发动机”。

模型给出决策,harness 负责让决策在现实环境中可执行、可控制、可恢复、可观察。最值得记住的一张脑图:

如果把这张图装进脑子,再看各个文件时就容易判断它们属于哪一层:

  • 看到 run_turn,想到“采样循环”;
  • 看到 StepContext,想到“这次请求的固定快照”;
  • 看到 ToolRouter,想到“模型可见能力与真实执行器的对应”;
  • 看到 CancellationToken,想到“停止必须传播到模型、工具和审批等待”;
  • 看到 RolloutItem,想到“让任务可以恢复和审计的事实记录”;
  • 看到 app-server,想到“让任何 UI 驾驶这台发动机的控制协议”。

本文至此结束,感谢大家的阅读!

 

   
31   次浏览       1 次
相关文章

基于图卷积网络的图深度学习
自动驾驶中的3D目标检测
工业机器人控制系统架构介绍
项目实战:如何构建知识图谱
 
相关文档

5G人工智能物联网的典型应用
深度学习在自动驾驶中的应用
图神经网络在交叉学科领域的应用研究
无人机系统原理
相关课程

FDE(前沿部署工程师)实践指南
AI辅助软件开发案例与实践
基于大模型的Agent技术应用开发
知识库+大模型+知识图谱

最新活动计划
AI时代的需求分析师培养 11-4[北京]
MBSE(基于模型的系统工程) 11-11[北京]
FDE(前沿部署工程师)实践 11-12[北京]
OCSMP 认证培训 11-19[在线]
UAF架构体系与实践 11-24[北京]
AI赋能产品管理实战 12-10[在线]
国产化数据库设计&优化 12-24[北京]
 
 
最新文章
AIGC技术与应用全解析
详解知识图谱的构建全流程
大模型升级与设计之道
自动驾驶和辅助驾驶系统
ROS机器人操作系统底层原理
最新课程
人工智能,机器学习和深度学习
人工智能与机器学习应用实战
人工智能-图像处理和识别
人工智能、机器学习& TensorFlow+Keras框架实践
人工智能+Python+大数据
成功案例
某综合性科研机构 人工智能与机器学习
某银行 人工智能+Python+大数据
北京 人工智能、机器学习& TensorFlow
某领先数字地图提供商 Python数据分析
中国移动 人工智能、机器学习和深度学习