ARTICLE · 1342302

03 · Harness 与 App Server 平台化

发布时间：2026-11-11 07:45:21 最近访问：2026-11-11 07:45:22

上一篇把循环放在了主控的位置。这一篇展开 harness 的四块内容，以及不同入口怎么接进同一个内核。

harness 的四块内容

Codex 有 Web、CLI、IDE、桌面 App 四种入口，背后却是同一套架构 [3]。串起它们的是 OpenAI 称为 Codex harness（运行框架）的东西 [1]。它包住模型，接管推理之外的全部动作。

OpenAI 自己拆解过 harness 内部的四块内容 [1]：

1. 核心 Agent Loop，协调用户、模型、工具三者交互的主循环，也就是第二篇讲的「循环」 [2]。

2. 线程生命周期与持久化（Thread lifecycle & persistence）。一次对话就是一个 thread，系统能创建、恢复、派生、归档它，并保存事件历史，让客户端断线重连后还能续上。

3. 配置与鉴权（Config & auth），负责加载配置、管理默认项、跑「用 ChatGPT 登录」这类鉴权流程。

4. 工具执行与扩展（Tool execution & extensions），在沙箱里执行 shell 和文件工具，并接上 MCP 服务器、skills 等扩展。

承载这些逻辑的代码放在一个叫 Codex core 的模块里。OpenAI 对它的描述是：既是一个存放所有智能体代码的库，也是一个可以启动的运行时，用来跑 Agent Loop 并管理一个 thread 的持久化 [1]。

App Server：一份双向协议，一个长驻进程

不同入口要复用同一套内核，需要一个稳定的接口。这个接口就是 Codex App Server [1]。

它做两件事。

一份协议：客户端与服务器之间用 JSON-RPC over stdio（JSONL）通信，而且是全双向的。一个用户请求会引出一串服务器通知，服务器也能主动发请求，比如「需要你批准」，并暂停这一轮直到你回应。

一个长驻进程：它托管 Codex core 的线程。一个 App Server 进程内部有四个组件，分别是 stdio reader（读客户端请求）、message processor（翻译请求与事件）、thread manager（为每个 thread 起一个 core 会话），以及 core threads（真正跑 Loop 的会话）[1]。

图 1　App Server 接入路径：客户端经 JSON-RPC 进入消息处理，再到 core threads 与沙箱

一条 JSON-RPC 消息就是一行 JSON。下面这段是示意，方法名用于说明交互形态，并非官方公开的确切清单。可以看到客户端发请求、服务器回事件，服务器还能反向要批准：

--> {"jsonrpc":"2.0","id":1,"method":"send_message","params":{"thread_id":"t1","text":"修一下登录 500"}}<-- {"jsonrpc":"2.0","method":"event","params":{"type":"tool_call","name":"shell","command":"npm test"}}<-- {"jsonrpc":"2.0","method":"request_approval","params":{"thread_id":"t1","reason":"需访问网络"}}--> {"jsonrpc":"2.0","id":2,"method":"approve","params":{"thread_id":"t1","decision":"approve"}}

中间那条「服务器反向要批准」是这套协议的特点：服务器能主动打断客户端、要你点头，权限反转在协议层就体现出来了。第六篇展开。有了这套双向接口，VS Code、桌面 App，乃至你自己写的脚本，才能共享同一个内核。

图 2　一次请求的双向时序：服务器可主动发「需批准」并暂停这一轮

三种入口，同一协议

OpenAI 公开了三种接入模式 [1]。

本地 App 与 IDE 会把平台对应的 App Server 二进制打包进来，作为长驻子进程启动，保持一条双向 stdio 通道。VS Code 扩展和桌面 App 都是这么做的。连 Xcode 这类发布周期慢的伙伴，也用「客户端稳定、指向更新的 App Server 二进制」来解耦版本。

Codex Web 把 harness 跑在容器里。worker 给一个装好代码仓的容器，在里面启动 App Server，浏览器通过 HTTP/SSE 拉事件流。因为网页会关、网络会断，状态存在服务器端，标签页关了任务也继续跑。

TUI / CLI 最早是「原生客户端」，和 Agent Loop 同进程。现在它也走 App Server：服务端随 Codex CLI 二进制一起分发，桌面 App 捆绑对应版本，另有 Python SDK 和按版本生成的 TypeScript 绑定、JSON Schema 可用 [1][5]。这样 TUI 能连远程机器上的 Codex，笔记本合盖也能继续干活。

关于协议与生态的几个事实

开源与 Apache 2 协议：harness 和协议都能 fork，也能接任何暴露 Responses 兼容 API 的模型，包括 LM Studio、Ollama 本地模型 [5]。
120+ 客户端消息：协议暴露了线程管理、目标设定、插件、文件搜索、文件系统修改等 app 级能力，比更通用的 Agent Client Protocol 粒度更细 [5]。
向后兼容设计：协议演进不破坏旧客户端，伙伴能直接获得服务器端改进，比如更好的自动压缩、新的配置键 [1][4]。
codex exec
另作他途：脚本化、非交互的任务（如 CI 里自动修 PR）走 codex exec，全控客户端走 App Server [5]。

# 在 CI 里让 Codex 自动修一个失败的测试（非交互、脚本化、结构化输出）codex exec --sandbox workspace-write --json -o result.txt \  "修复 CI 里失败的单元测试，不要改测试以外的逻辑"

exec 本身不弹交互确认，--json 输出 JSONL 事件流给流水线解析，-o 把最终结论写进文件，--sandbox workspace-write 指定可写但受限的沙箱档 [6]。若你的版本仍要求显式指定审批策略，再补 -a never，这一项只在隔离的 CI 环境里用，第六篇会讲清风险。