Unlocking the Codex Harness: How We Built the App Server

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

源

SOURCE · CODEX APP SERVER · OpenAI · JSON-RPC over stdio

Unlocking the Codex Harness

Bidirectional JSON-RPC over stdio — one protocol drives CLI / IDE / Web / Desktop

Session primitives nest three deep: Thread (persistent container, forkable/archivable) ⊃ Turn (one full input-to-output round) ⊃ Item (atomic I/O with lifecycle)

THREAD · persistent container

create / resume / fork / archive

TURN · one round

user input → agent finishes output

ITEM · atomic unit

user msgagent msgtool execapprovaldiff

lifecycle · started → delta → completed

Surface

Integration

IDE / Desktop

Bundled platform binary · long-lived child process + stdio

Web

App Server launched in container · HTTP + SSE

TUI / CLI

Refactored as a standard App Server client

→ 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