← Knowledge Atlas · 源头

Unlocking the Codex Harness: How We Built the App Server

Codex App Server 架构：threads/turns/items 会话原语、双向 JSON-RPC、多表面集成

源

源头 · CODEX APP SERVER · OpenAI · JSON-RPC over stdio

解锁 Codex Harness

双向 JSON-RPC over stdio · 统一驱动 CLI / IDE / Web / Desktop

会话原语三层嵌套：Thread（持久容器，可 fork/归档）⊃ Turn（一次完整输入-输出）⊃ Item（原子 I/O 带生命周期）

THREAD · 持久容器

create / resume / fork / archive

TURN · 一轮

user input → agent 完成输出

ITEM · 原子单元

user msgagent msgtool execapprovaldiff

生命周期 · started → delta → completed

表面

集成方式

IDE / Desktop

捆绑平台二进制 · 长驻子进程 + stdio

Web

容器内启动 App Server · HTTP + SSE

TUI / CLI

重构为标准 App Server 客户端

→ codex · implicit-loop-architecture · harness-engineering · mcpopenai.com/index

Unlocking the Codex Harness: How We Built the App Server

来源: sources/openai_official/unlocking-codex-harness.md
URL: https://openai.com/index/unlocking-the-codex-harness/
作者: Celia Chen (OpenAI)

概述

本文介绍 Codex App Server——将 Codex harness 暴露为稳定 API 的协议层。核心设计：双向 JSON-RPC over stdio，统一驱动 CLI、IDE、Web、桌面等多个客户端表面。

核心架构

会话原语

三层嵌套结构：

Thread（线程）：持久容器，一个 user-agent 会话，可创建/恢复/fork/归档
Turn（轮次）：一次用户输入 → agent 完成输出的完整过程
Item（项）：原子 I/O 单元，带类型（user message、agent message、tool execution、approval request、diff）和生命周期（started → delta → completed）

App Server 内部

四个组件：stdio reader → Codex message processor → thread manager → core threads。每个 thread 对应一个 core session，message processor 负责 client JSON-RPC ↔ core 事件流的翻译。

集成模式

表面	集成方式
本地 IDE/Desktop	捆绑平台特定二进制，长驻子进程 + stdio
Web	容器内启动 App Server，浏览器通过 HTTP+SSE 与后端通信
TUI/CLI	重构为标准 App Server 客户端（进行中）

协议选择

App Server（JSON-RPC）：完整 harness 功能 + UI-ready 事件流
MCP Server：已有 MCP 工作流时使用，但功能子集
Codex Exec：CI/脚本场景的轻量非交互模式
Codex SDK：TypeScript 库，编程控制本地 agent

与其他概念的关联

Codex — App Server 是 Codex harness 的协议暴露层
Implicit loop architecture — threads/turns/items 是隐式循环的会话表达
MCP — 作为替代集成方式被比较
Harness engineering — App Server 本身是 harness 工程的产物

References

sources/openai_official/unlocking-codex-harness.md