演讲背景与Codex App Server的核心定位

本次分享由OpenAI负责Codex开发者体验的Dominik Kundel主讲，旨在降低构建自定义Agent界面的门槛。演讲开篇通过互动指出许多开发者对搭建Agent Harness感到畏惧，因此重点介绍如何基于Codex Harness（代码库）进行开发。核心概念是App Server协议，它包裹在Codex Harness之上，类似于Agent Client Protocol (ACP)，允许开发者直接深度集成到Harness中。与通用协议不同，App Server和Codex Harness均为开源项目（Apache 2许可证）。这意味着开发者可以自由Fork、修改甚至将其连接到任何支持Responses API的模型提供商，包括LM Studio或Ollama等本地工具。

"The app server is actually the protocol that wraps the Codex harness."

这种开放性不仅限于OpenAI自家产品。目前，Xcode、JetBrains IDEs、T3 Code、Remote X以及Cloud Code插件等第三方或第一方界面，底层均通过同一套App Server协议驱动。例如，Cloud Code用户可通过插件将任务传递给Codex处理，其背后调用的正是相同的Harness架构。这种统一性确保了无论使用何种客户端，都能获得一致的底层能力支持。

App Server协议机制与实时事件交互

App Server采用JSON-RPC风格协议，通过客户端（开发者构建的应用）与服务器端（Codex App Server）之间的消息传递来执行操作并接收事件。为了直观展示这一过程，演讲者演示了一个拦截Codex App与Server之间所有事件的Inspector工具。当在App中发送消息时，开发者可以看到一系列真实发生的事件流。

这些事件涵盖了从线程启动、配置读取到数据Delta流式传输的全过程。协议的核心优势在于其灵活性，它暴露了App中的几乎所有关键功能。目前已有超过120种不同的客户端消息类型，且仍在持续增加。这些能力包括初始化配置、线程修改与轮次管理（经典对话功能）、设置目标模式（Goal Mode）、列出插件，甚至包括文件搜索与文件系统修改。这种细粒度的控制使得开发者能够构建出功能完备的自定义客户端，而不仅仅是简单的聊天窗口。

深度定制能力：开发者指令与工具集成

在自定义Agent方面，App Server提供了比ACP更细致的控制权限。主要定制点包括开发者指令（Developer Instructions）和工具集成。通过设置开发者指令，开发者可以在Codex的系统提示词（System Prompt）基础上追加内容。虽然系统提示本身是保密的，但开发者可以在仓库中查看其结构，并在此基础上增强Agent的行为。此外，集成自定义工具也是关键功能之一。

另一个备受关注的特性是身份验证与订阅整合。使用App Server协议的客户端支持通过ChatGPT进行登录。这意味着最终用户可以使用自己的ChatGPT订阅账户，从而消耗其个人的Codex使用额度。这一设计极大地降低了第三方应用开发者的运营负担，同时也提升了用户体验的一致性。例如，使用T3 Code等工具时，用户即是在利用自己的订阅资源进行计算。

"We can actually give you more control over the individual parts of the harness as well through the protocol."

综上所述，Codex Harness与App Server不仅提供了强大的底层能力，还通过开源协议和灵活的集成方式，赋予了开发者构建多样化Agent界面的自由。无论是追求极致控制的本地部署场景，还是希望利用现有订阅的SaaS应用，这套架构都提供了坚实的技术基础。

利用开发者指令与动态工具定制代理行为

在构建基于 Codex Harness 的应用时，官方强烈建议通过开发者指令（Developer Instructions）来扩展系统提示词。这种做法的核心优势在于，它允许开发者在保留 OpenAI 针对特定模型精心调优的基础提示词工作的同时，灵活地根据具体用例进行自定义。例如，Codex App 与 IDE 扩展或 CLI 工具在功能侧重上有所不同，通过这种方式可以确保提示词适配特定的应用场景。此外，动态工具（Dynamic Tools）的引入进一步增强了代理的能力，开发者可以暴露额外的函数供代理使用。这既可以通过 MCP 或类似 Agent Client Protocol 的方式实现，也可以直接定义工具。

为了优化上下文窗口的利用率，开发者可以将这些工具标记为延迟加载（Deferred Loading）。这意味着工具不会直接注入到系统提示词中，而是允许 Codex 通过工具搜索（Tool Search）机制来发现和使用它们。这种方式有效避免了将大量工具描述污染整体上下文窗口，从而保持提示词的简洁性。在每线程（per-thread）的基础上，开发者还可以对代理的其他配置进行细粒度控制，例如切换不同的模型提供商、选择特定版本的模型，甚至精确设定沙箱环境的网络访问权限和文件修改范围。这种灵活性使得代理能够适应从简单脚本到复杂系统交互的各种需求。

App Server 的部署机制与协议支持

Codex App Server 并非独立的软件包，而是作为 Codex CLI的一部分分发。这意味着如果系统中已安装 Codex CLI，用户可以直接使用该二进制文件启动 App Server。在应用分发方面，Codex App 将 CLI 的二进制文件打包在其应用程序 bundle 中，每次应用更新都会同步升级后端的 CLI 版本。特别是在 Windows平台上，安装包中包含了两个版本的二进制文件：一个是 Linux 编译版，另一个是 Windows 原生版。这种设计是为了支持 WSL（Windows Subsystem for Linux）模式，当在 WSL 模式下加载应用时调用 Linux 版本，而在其他情况下则启动 Windows 原生版本的 App Server。

为了应对协议频繁变更的问题，App Server 提供了生成对应版本 TypeScript 绑定或 JSON Schema的功能。由于协议在不同版本间可能发生变化，官方建议开发者将 App Server 捆绑在自己的应用程序中，以便完全控制所依赖版本的功能集。在通信协议方面，App Server 支持两种模式：通过 STDIO（标准输入输出）或WebSockets。选择哪种方式取决于具体的用例，开发者可以通过实际测试或与 Codex 交互来确定最适合的方案。这种双协议支持确保了 App Server 能够灵活集成到各种类型的应用架构中，无论是本地命令行工具还是基于浏览器的复杂界面。

集成路径：从 Python SDK 到自主开发

对于希望快速集成的开发者，官方提供了经过重新发布的 Python SDK。该 SDK 自动化了生命周期管理，无需开发者手动处理复杂的连接和维护逻辑。它还简化了与 ChatGPT 的集成流程，并提供了一个熟悉的使用接口，非常适合希望快速上手或构建标准代理应用的场景。然而，对于具备工程能力的开发者（如参加 AI 工程师会议的受众），更推荐直接通过提示 Codex 来实现协议集成。Codex 在实现此类协议方面表现出色，开发者通常只需指向相关文档即可让 Codex 生成所需的代码。在某些情况下，甚至不需要额外提示，Codex 也能准确理解需求。

这种集成方式极大地降低了开发门槛。开发者可以结合使用各种插件，例如快速构建 macOS 应用，或者进行更具创意的尝试。演讲者分享了一个极端案例：他使用 Codex 通过 Visual Basic构建了一个真正的 Windows 原生客户端应用，且大部分代码在单次交互中完成。这表明，借助 Codex 的强大能力，开发者可以在短时间内构建出令人印象深刻的应用程序，而无需深入掌握代理开发的每一个细微技术细节。这种“以代码生成代码”的模式不仅提高了效率，还激发了开发者在界面设计和交互逻辑上的创造力。

突破传统：将 Codex 嵌入 Doom 游戏引擎的演示

App Server 最引人注目的特性在于它不受限于传统的代理聊天界面。开发者可以充分发挥创意，将 Codex 集成到各种非典型场景中，例如后台运行、嵌入现有 UI，甚至部署在特殊的硬件设备上。演讲者展示了一个极具创意的案例：将 Codex 运行在游戏 Doom中，而不是在 Codex 环境中运行 Doom。为了实现这一点，他构建了一个基于 Electron的应用程序，该应用利用 Cloudflare 的 Doom WASM 渲染器。游戏引擎本身主要由 C 语言实现，并加载了 FreeDoom 游戏内容。

在这个演示中，演讲者通过 Electron IPC（进程间通信）协议将游戏内的交互传递给 App Server。当用户在游戏界面中输入“hello”时，Codex（使用版本 5.5）能够实时响应。更有趣的是动态工具在游戏环境中的应用。代理可以通过调用暴露的工具获取游戏中的护甲、生命值以及武器弹药信息。此外，由于 App Server 实际上运行在本地机器上，代理还可以执行系统级命令，例如通过 Z shell（zsh）获取当前工作目录。演示中还展示了代理能够识别其独立的工作空间，甚至允许在游戏环境中直接编写代码（尽管官方建议仍使用标准的 Codex App 进行此类操作）。这一案例生动地证明了将 AI 代理嵌入实时渲染环境和游戏引擎的可行性与趣味性。

App Server 与 Codex Exec 的核心差异及适用场景

在构建基于 AI Agent 的应用时，开发者常混淆 Codex Exec 与 App Server 的用途。Codex Exec 是一个非交互式命令行工具，专为脚本化任务设计。如果你正在构建 CI/CD 流程，例如需要自动修复 Pull Request（PR），Codex Exec 是理想选择。然而，当需求升级为构建更复杂的客户端应用时，其局限性便显现出来。

"If you're trying to build like a more comprehensive client... or if you're trying to do something where you're spinning up a bunch of different Codex threads at the same time."

App Server 的优势在于提供对 Harness（测试/执行框架）的完全控制权。特别是在需要并行处理多个任务时，例如运行自定义评估（eval harness）或使用 /goal 命令，App Server 允许开发者直接管理线程调度。相比之下，依赖 Codex Exec 意味着你需要自行解决并行化问题，通过发送大量新线程事件来启动任务。这种底层控制力使得 App Server 成为构建大规模并发 Agent 应用的首选方案，避免了重复造轮子。

最佳实践一：独立分发 Harness 版本

为了确保应用的稳定性和兼容性，开发者应自行打包并分发自己的 Harness 版本。依赖用户本地安装的 CLI 会带来诸多隐患，尤其是当 OpenAI 推出实验性功能或发生破坏性更新（breaking changes）时。

如果依赖用户环境，你将面临两个主要问题：一是无法保证用户已更新至包含所需最新功能的版本；二是需要额外开发机制去提示或强制用户更新。通过将 Harness 作为应用的一部分进行分发，你可以消除这些不确定性。这不仅确保了所有用户运行的是经过测试的特定版本，还避免了因依赖外部 CLI 状态而导致的不可预测行为。这是一种以空间换稳定性的策略，能显著减少后期维护中的头痛问题。

最佳实践二：使用 Deferred Functions 扩展接口能力

在构建应用界面时，应积极暴露新的函数供 Agent 调用，例如用于控制自身自动化流程的功能。然而，直接将这些新函数添加到系统提示中会污染上下文窗口（Context Window）。

正确的做法是将这些新增函数标记为 Deferred Functions。这种方式允许 Agent 在需要时调用这些功能，而无需将它们全部加载到当前的上下文中。这既保持了 Agent 对扩展能力的访问权限，又避免了因信息过载导致的混淆或性能下降。例如在 Codex App 中，这种机制被用于让 Agent 能够自主启动自动化任务。通过隔离非必要上下文信息，开发者可以在不牺牲模型推理效率的前提下，极大地扩展应用的功能边界。

最佳实践三：谨慎修改系统提示词（System Prompt）

许多开发者倾向于通过重写 System Prompt 来定制 Agent 行为，但这往往是一个陷阱。OpenAI 建议优先通过添加 Developer Instructions（开发者指令）来调整行为，而非直接修改 Base Instructions（基础指示）。

"You're losing out on all of that if you're actually jumping in and like writing your own system prompt."

基础提示词经过精心调优，以确保 Agent 在分布内（in-distribution）表现良好。随意重写系统提示词可能导致性能下降或行为偏离预期。开发者指令提供了一种更安全的定制方式，它允许你在不破坏底层模型优化逻辑的前提下注入特定约束。这种分层策略确保了核心推理能力的稳定性，同时提供了足够的灵活性以满足定制化需求。

最后，开发者可以通过扫描 QR 码获取相关幻灯片资料。演讲者将在 OpenAI 展位停留约 15 分钟，以便回答关于 App Server 使用的具体问题。

结论

Codex Harness与App Server通过开源协议和细粒度控制，显著降低了构建自定义Agent界面的门槛。其核心优势在于支持深度定制（如开发者指令、动态工具）、多客户端统一架构及身份验证整合，并能灵活嵌入非典型场景（如游戏引擎）。相比仅适用于脚本化任务的Codex Exec，App Server提供了对执行框架的完全控制权，适合构建大规模并发应用。

然而，开发者需遵循最佳实践以规避风险：应自行打包Harness版本以确保稳定性，使用延迟加载机制优化上下文窗口利用率，并通过追加开发者指令而非重写系统提示来定制行为。这套架构在提供强大灵活性的同时，要求开发者具备相应的工程能力以正确集成和维护。