OpenAI Codex 应用服务器架构与集成

OpenAI 已发布 Codex 应用服务器，这是一种标准化的 JSON-RPC 协议和长期运行的进程，旨在向各种客户端应用公开 Codex 代理框架。该架构使开发者能够将高保真代理循环——包括工作区探索、实时进度流式传输和差异生成——集成到 IDE、桌面应用和网页环境中，而无需重新实现核心代理逻辑。

Codex 应用服务器架构

Codex 应用服务器充当客户端与 “Codex 核心” 之间的翻译层，后者包含代理循环、工具执行逻辑和线程管理。

核心组件

Stdio Reader: 处理传入的通信通道。
Codex Message Processor: 将客户端的 JSON-RPC 请求转换为 Codex 核心操作，并将内部事件流转换为稳定、可用于 UI 的通知。
Thread Manager: 管理核心会话的生命周期，为每个线程启动一个核心会话。
Core Threads: 代理循环实际执行的运行时实例。

Codex 框架

除了代理循环，应用服务器还公开完整的 Codex 框架，其中包括：

Thread Lifecycle and Persistence: 能够创建、恢复、分叉和归档对话，确保客户端重新连接时拥有一致的时间线。
Configuration and Authentication: 管理默认设置和认证流程，例如 “Sign in with ChatGPT”。
Tool Execution and Extensions: 为 shell 和文件工具提供的沙箱环境，以及与 MCP 服务器和技能的集成。

对话原语

为处理代理交互的非线性特性，应用服务器协议使用三种核心原语，以确保弹性并便于在不同用户界面之间集成。

1. 项目

项目是输入和输出的原子单元。每个项目（例如用户消息、工具执行、差异）遵循特定的生命周期：

item/started：项目开始。
item/*/delta：内容以增量方式流式传输（针对流式类型）。
item/completed：项目以其最终负载完成。

2. 回合

回合表示由用户输入触发的单个代理工作单元。它包含一系列项目，代表代理产生的中间步骤和最终输出。

3. 线程

线程是会话的持久容器。它保存多个回合，使客户端能够重新连接到会话并渲染历史记录，而无需重新构建状态。

客户端集成模式

应用服务器使用基于 stdio（JSONL）的 JSON-RPC，支持包括 Go、Python、TypeScript、Swift 和 Kotlin 在内的多语言客户端绑定。

本地应用和 IDE

本地客户端（如 VS Code 扩展和 Codex Desktop App）将平台特定的应用服务器二进制文件打包为子进程。一些合作伙伴，例如 Xcode，通过独立指向更新的应用服务器二进制文件来解耦发布周期，从而在不需要完整客户端更新的情况下采用服务器端的改进和错误修复。

Codex Web

在容器化环境中，工作节点会准备带有工作区的容器并启动应用服务器二进制文件。Web 应用通过 HTTP 和 SSE 与 Codex 后端通信，SSE 从工作节点流式传输事件。这确保即使浏览器标签页关闭，长时间运行的任务仍能继续。

TUI 与 Codex CLI

虽然 TUI 最初直接与 Rust 核心类型交互，但正在重构为使用应用服务器协议。这使得 TUI 能够连接到远程 Codex 服务器，将代理保持在计算资源附近，同时提供本地更新。

集成方式比较

OpenAI 推荐使用应用服务器来满足完整框架需求，但也根据具体使用场景提供其他选项：

方式	最佳使用场景	权衡
Codex App Server	完整框架、稳定的 UI 友好事件流以及认证管理。	需要构建客户端侧的 JSON-RPC 绑定。
MCP Server	现有基于 MCP 的工作流，其中 Codex 作为可调用工具。	受限于 MCP 语义；缺乏诸如差异更新等丰富的会话特性。
Cross-provider Protocols	协调来自不同模型提供商的多个代理。	通常仅限于通用能力子集，缺少提供商特定的语义。
CLI Mode	一次性任务、CI/CD 流水线以及非交互式自动化。	非交互式；设计用于单命令完成。
TypeScript Library	在 TypeScript 应用中对本地代理进行编程控制。	目前支持的语言更少，功能覆盖面也小于应用服务器。

应用服务器的源代码可在开源的 Codex CLI 仓库中获取。