解锁 Codex 框架：我们如何构建 App Server | OpenAI

来源: https://openai.com/index/unlocking-the-codex-harness/ 抓取时间: 2026-07-21 16:20:57

2026 年 2 月 4 日
工程

解锁 Codex 框架：我们如何构建 App Server

作者：Celia Chen，技术人员
加载中……

• App Server 的起源

• Codex 框架内部

• 会话原语

• 与客户端集成

  • 本地应用程序和 IDE
  • Codex Web
  • TUI/Codex CLI

• 选择正确的协议

  • JSON-RPC 协议
    • Codex 作为 MCP 服务器
    • 跨提供商智能体框架协议
    • Codex App Server
  • 其他嵌入 Codex 的方式

• 未来展望

• App Server 的起源

• Codex 框架内部

• 会话原语

• 与客户端集成

  • 本地应用程序和 IDE
  • Codex Web
  • TUI/Codex CLI

• 选择正确的协议

  • JSON-RPC 协议
    • Codex 作为 MCP 服务器
    • 跨提供商智能体框架协议
    • Codex App Server
  • 其他嵌入 Codex 的方式

• 未来展望

OpenAI 的编码智能体 Codex 存在于许多不同的界面中：Web 应用程序⁠（在新窗口中打开）、CLI⁠（在新窗口中打开）、IDE 扩展⁠（在新窗口中打开） 和 新的 Codex macOS 应用程序。在幕后，它们都由同一个 Codex 框架提供支持——构成所有 Codex 体验基础的智能体循环和逻辑。它们之间的关键链接？Codex App Server⁠（在新窗口中打开），一个客户端友好的双向 JSON-RPC¹ API。

在这篇文章中，我们将介绍 Codex App Server；我们将分享迄今为止关于将 Codex 的功能引入您的产品以帮助您的用户增强其工作流程的最佳方法的学习经验。我们将介绍 App Server 的架构和协议，以及它如何与不同的 Codex 界面集成，以及利用 Codex 的技巧，无论您想将 Codex 变成代码审查员、SRE 智能体还是编码助手。

App Server 的起源

在深入探讨架构之前，了解 App Server 的背景故事会很有帮助。最初，App Server 是一种在产品中重用 Codex 框架的实用方式，逐渐演变为我们的标准协议。

Codex CLI 最初是一个 TUI（终端用户界面），这意味着 Codex 是通过终端访问的。当我们构建 VS Code 扩展（一种更 IDE 友好的与 Codex 智能体交互的方式）时，我们需要一种方法来使用相同的框架，以便从 IDE UI 驱动相同的智能体循环，而无需重新实现它。这意味着支持请求/响应之外的丰富交互模式，例如探索工作区、在智能体推理时流式传输进度，以及发布差异。我们首先尝试将 Codex 暴露为 MCP 服务器⁠（在新窗口中打开），但以对 VS Code 有意义的方式维护 MCP 语义被证明是困难的。相反，我们引入了一个镜像 TUI 循环的 JSON-RPC 协议，这成为了 App Server 的 非官方第一版⁠（在新窗口中打开）。当时，我们没有想到其他客户端会依赖 App Server，所以它不是作为稳定 API 设计的。

随着接下来几个月 Codex 的采用增长，内部团队和外部合作伙伴希望能够将相同的框架嵌入到他们自己的产品中，以加速其用户的软件开发工作流程。例如，JetBrains 和 Xcode 需要 IDE 级别的智能体体验，而 Codex 桌面应用程序需要并行编排许多 Codex 智能体。这些需求促使我们设计一个平台界面，我们的产品和合作伙伴集成都可以随着时间的推移安全地依赖它。它需要易于集成和向后兼容，这意味着我们可以在不破坏现有客户端的情况下发展协议。

接下来，我们将介绍我们如何设计架构和协议，以便不同的客户端可以使用相同的框架。

Codex 框架内部

首先，让我们放大 Codex 框架内部的内容，以及 Codex App Server 如何将其暴露给客户端。在我们上一篇 Codex 博客中，我们分解了编排用户、模型和工具之间交互的核心智能体循环。这是 Codex 框架的核心逻辑，但完整的智能体体验还有更多：

1. 线程生命周期和持久性。线程是用户与智能体之间的 Codex 对话。Codex 创建、恢复、分叉和归档线程，并持久化事件历史，以便客户端可以重新连接并渲染一致的时间线。

2. 配置和身份验证。Codex 加载配置、管理默认值，并运行身份验证流程，如"使用 ChatGPT 登录"，包括凭据状态。

3. 工具执行和扩展。Codex 在沙箱中执行 Shell/文件工具，并连接 MCP 服务器和技能等集成，以便它们可以在一致的策略模型下参与智能体循环。

我们在此提到的所有智能体逻辑，包括核心智能体循环，都位于 Codex CLI 代码库中称为"Codex 核心⁠（在新窗口中打开）"的部分。Codex 核心既是所有智能体代码所在的库，也是一个可以启动以运行智能体循环并管理一个 Codex 线程（对话）的持久性的运行时。

为了有用，Codex 框架需要对客户端可访问。这就是 App Server 的用武之地。

App Server 既是客户端与服务器之间的 JSON-RPC 协议，也是托管 Codex 核心线程的长期运行的进程。从上图中我们可以看出，App Server 进程有四个主要组件：stdio 读取器、Codex 消息处理器、线程管理器和核心线程。线程管理器为每个线程启动一个核心会话，然后 Codex 消息处理器直接与每个核心会话通信以提交客户端请求和接收更新。

一个客户端请求可能会导致许多事件更新，这些详细事件使我们能够在 App Server 之上构建丰富的 UI。此外，stdio 读取器和 Codex 消息处理器充当客户端和 Codex 核心线程之间的转换层。它们将客户端 JSON-RPC 请求转换为 Codex 核心操作，监听 Codex 核心的内部事件流，然后将这些低级事件转换为一小组稳定的、UI 就绪的 JSON-RPC 通知。

客户端与 App Server 之间的 JSON-RPC 协议是完全双向的。典型的线程有一个客户端请求和多个服务器通知。此外，当智能体需要输入（如批准）时，服务器可以发起请求，然后暂停回合直到客户端响应。

会话原语

接下来，我们将分解会话原语——App Server 协议的构建块。为智能体循环设计 API 很棘手，因为用户/智能体交互不是简单的请求/响应。一个用户请求可能会展开为客户端需要忠实表示的结构化操作序列：用户输入、智能体的增量进度、沿途产生的工件（例如差异）。为了使该交互流易于集成并在各种 UI 中具有弹性，我们确定了三个核心原语，它们具有清晰的边界和生命周期：

1. Item： Item 是 Codex 中输入/输出的原子单元。Item 是有类型的（例如用户消息、智能体消息、工具执行、批准请求、差异），每个都有明确的生命周期：

• item/started 当 Item 开始时
• 可选的 item/*/delta 事件，随着内容的流入（用于流式 Item 类型）
• item/completed 当 Item 最终确定其终端有效负载时

此生命周期允许客户端在 started 时立即开始渲染，在 delta 上流式传输增量更新，并在 completed 时最终确定。

2. Turn： Turn 是由用户输入发起的一个智能体工作单元。它从客户端提交输入（例如"运行测试并总结失败"）时开始，到智能体完成为该输入生成输出时结束。Turn 包含一系列 Item，这些 Item 表示中间步骤和沿途产生的输出。

3. Thread： Thread 是用户与智能体之间持续的 Codex 会话的持久容器。它包含多个 Turn。线程可以被创建、恢复、分叉和归档。线程历史被持久化，以便客户端可以重新连接并渲染一致的时间线。

现在，让我们看一下客户端与智能体之间的简化对话，其中对话由原语表示：

在对话开始时，客户端和服务器需要建立 initialize 握手。客户端必须在任何其他方法之前发送单个 initialize 请求，服务器用响应确认。这使服务器有机会宣传功能，并让双方在实际工作开始之前就协议版本、功能标志和默认值达成一致。以下是 OpenAI 的 VS Code 扩展的示例有效负载：

JSON

{
  "method": "initialize",
  "id": 0,
  "params": {
    "clientInfo": {
      "name": "codex_vscode",
      "title": "Codex VS Code Extension",
      "version": "0.1.0"
    }
  }
}

这是服务器返回的内容：

JSON

{
  "id": 0,
  "result": {
    "userAgent": "codex_vscode/0.94.0-alpha.7 (Mac OS 26.2.0; arm64) vscode/2.4.22 (codex_vscode; 0.1.0)"
  }
}

当客户端发出新请求时，它将首先创建一个线程，然后创建一个 Turn。服务器将发回进度通知（thread/started 和 turn/started）。它还会发回它注册为 Item 的输入，例如这里的用户消息。

工具调用也作为 Item 发回给客户端。此外，服务器可能会在运行操作之前询问客户端批准，方法是发送服务器请求。批准将暂停 Turn，直到客户端回复"允许"或"拒绝"。这是 VS Code 扩展中批准流的样子：

最后，服务器发送智能体消息，然后用 turn/completed 结束 Turn。智能体消息增量事件流式传输消息的各个部分，直到消息以 item/completed 最终确定。

为了可读性，图表中的消息已简化。如果您想查看完整 Turn 的 JSON，您可以从 Codex CLI 存储库运行测试客户端：

Bash

codex debug app-server send-message-v2 "run tests and summarize failures"

与客户端集成

现在，让我们看看不同的客户端界面如何通过 App Server 嵌入 Codex。我们将介绍三种模式：本地应用程序和 IDE、Codex Web 运行时和 TUI。

在所有三者中，传输是基于 stdio 的 JSON-RPC（JSONL）。JSON-RPC 使得用您选择的语言构建客户端绑定变得简单明了。Codex 界面和合作伙伴集成已经用包括 Go、Python、TypeScript、Swift 和 Kotlin 在内的语言实现了 App Server 客户端。对于 TypeScript，您可以通过运行以下命令直接从 Rust 协议生成定义：

Bash

codex app-server generate-ts

对于其他语言，您可以生成 JSON Schema 包，并通过运行以下命令将其输入您首选的代码生成器：

Bash

codex app-server generate-json-schema

本地应用程序和 IDE

本地客户端通常捆绑或获取特定平台的 App Server 二进制文件，将其作为长期运行的子进程启动，并保持双向 stdio 通道打开以进行 JSON-RPC。例如，在我们的 VS Code 扩展和桌面应用程序中，发布的工件包含特定平台的 Codex 二进制文件，并固定到测试版本，以便客户端始终运行我们验证的确切代码。

并非每个集成都能频繁发布客户端更新。一些合作伙伴（如 Xcode）通过保持客户端稳定并允许它在需要时指向更新的 App Server 二进制文件来解耦发布周期。这样，他们可以采用服务器端改进（例如，Codex 核心中更好的自动压缩或新支持的配置键）并推出错误修复，而无需等待客户端发布。App Server 的 JSON-RPC 界面设计为向后兼容，因此旧客户端可以安全地与新服务器通信。

Codex Web

Codex Web 使用 Codex 框架，但在容器环境中运行。工作器用已检出的工作区配置容器，在其中启动 App Server 二进制文件，并维护基于 stdio² 的长期 JSON-RPC 通道。Web 应用程序（在用户的浏览器选项卡中运行）通过 HTTP 和 SSE 与 Codex 后端通信，SSE 流式传输工作器产生的任务事件。这使得浏览器端 UI 保持轻量级，同时仍为我们提供跨桌面和 Web 的一致运行时。

由于 Web 会话是短暂的（选项卡关闭、网络断开），Web 应用程序不能成为长期运行任务的真实来源。将状态和进度保持在服务器上意味着即使选项卡消失，工作也会继续。流式协议和已保存的线程会话使新会话能够轻松重新连接、从中断的地方继续并赶上进度，而无需在客户端重建状态。

TUI/Codex CLI

历史上，TUI 是一个"原生"客户端，它与智能体循环在同一进程中运行，并直接与 Rust 核心类型通信，而不是与 App Server 协议通信。这使得早期迭代很快，但也使 TUI 成为一个特殊情况的界面。

现在 App Server 已经存在，我们计划 重构 TUI⁠（在新窗口中打开） 以使用它，使其行为像任何其他客户端一样：启动 App Server 子进程、通过 stdio 进行 JSON-RPC 通信，并渲染相同的流式事件和批准。这解锁了 TUI 可以连接到在远程机器上运行的 Codex 服务器的工作流程，使智能体保持在计算附近，即使笔记本电脑睡眠或断开连接，工作也会继续，同时仍在本地提供实时更新和控制。

选择正确的协议

Codex App Server 将是我们未来维护的一流集成方法，但也有其他功能更有限的方法。默认情况下，我们建议客户端使用 Codex App Server 与 Codex 集成，但值得看一下不同的集成方法并了解它们的优缺点。以下是驱动 Codex 的最常见方法以及每种方法何时可能合适。

JSON-RPC 协议

Codex 作为 MCP 服务器

运行 codex mcp-server⁠（在新窗口中打开） 并从任何支持 stdio 服务器的 MCP 客户端连接（例如 OpenAI Agents SDK⁠（在新窗口中打开））。如果您已经有基于 MCP 的工作流程并希望将 Codex 作为可调用工具调用，这是一个很好的选择。缺点是您只能获得 MCP 暴露的内容，因此依赖更丰富会话语义的 Codex 特定交互（例如差异更新）可能无法通过 MCP 端点清晰映射。

跨提供商智能体框架协议

一些生态系统提供了可以针对多个模型提供商和运行时的可移植接口。如果您想要一个协调多个智能体的抽象，这可能是一个很好的选择。权衡是这些协议通常会收敛到功能的公共子集，这可能使得更丰富的交互更难表示，特别是当特定于提供商的工具和会话语义很重要时。这个空间正在快速发展，我们预计随着我们找出代表现实世界智能体工作流程的最佳原语，会出现更多通用标准（skills⁠（在新窗口中打开） 就是一个很好的例子）。

Codex App Server

当您希望将完整的 Codex 框架暴露为稳定的、UI 友好的事件流时，请选择 App Server。您不仅获得智能体循环的完整功能，还获得其他支持功能，如使用 ChatGPT 登录、模型发现和配置管理。主要成本是集成工作，因为您需要用您的语言构建客户端 JSON-RPC 绑定。然而，实际上，如果您将 JSON Schema 和文档提供给 Codex，它能够完成大量繁重的工作。我们合作过的许多团队能够使用 Codex 快速实现可行的集成。

其他嵌入 Codex 的方式

Codex Exec⁠（在新窗口中打开）

一种轻量级、可脚本化的 CLI 模式，用于一次性任务和 CI 运行。当您希望单个命令以非交互方式运行到完成、流式传输日志的结构化输出，并以清晰的成功或失败信号退出时，它非常适合自动化和管道。

Codex SDK⁠（在新窗口中打开）

一个 TypeScript 库，用于从您自己的应用程序中以编程方式控制本地 Codex 智能体。当您想要用于服务器端工具和工作流程的原生库接口而无需构建单独的 JSON-RPC 客户端时，它是最佳选择。由于它比 App Server 更早发布，目前它支持更少的语言和更小的界面。如果有开发者兴趣，我们可能会添加额外的 SDK 来包装 App Server 协议，以便团队可以覆盖更多框架表面，而无需编写 JSON-RPC 绑定。

未来展望

在这篇文章中，我们分享了我们如何设计一个新的与智能体交互的标准，以及如何将 Codex 框架转变为稳定的、客户端友好的协议。我们介绍了 App Server 如何暴露 Codex 核心、让客户端驱动完整的智能体循环，并为包括 TUI、本地 IDE 集成和 Web 运行时在内的广泛界面提供支持。

如果这激发了您将 Codex 集成到您自己的工作流程中的想法，值得尝试一下 App Server。所有源代码都位于 Codex CLI 开源 存储库⁠（在新窗口中打开）中。欢迎分享您的反馈和功能请求。我们很高兴收到您的来信，并继续让智能体对每个人都更易于访问。

• Codex
• 2026

作者

Celia Chen

致谢

特别感谢 Michael Bolin、Owen Lin、Eric Traut 和 Rasmus Rygaard，他们为这篇文章做出了贡献，并感谢整个致力于 App Server 的 Codex 团队。

脚注

1. 1
   我们使用"JSON-RPC lite"变体：它保留了请求/响应/通知的形状，但省略了 "jsonrpc": "2.0" 头，并被框架为基于 stdio 的 JSONL 而不是严格的 JSON-RPC 2.0。

2. 2
   "stdio"指的是容器内 app-server 的 stdin/stdout。在托管设置中，这些流通常通过持久网络连接（例如类似 WebSocket 的）隧道传输到容器运行时——所以即使它不是字面意义上的本地管道，它的行为也像 stdio。

继续阅读

查看全部

核心转储流行病学：修复 18 年前的错误工程 2026 年 6 月 30 日