有明确边界的脚本、CI Job 或一次性后台任务，优先使用 codex exec。应用代码需要启动、继续或恢复 Codex 编程线程时，使用 Codex SDK。如果 Agent 本身就是产品的一部分，并且你的界面需要直接处理线程、流式事件、中断、工具和审批，再评估 codex app-server。
这是 OpenAI 在 Codex 平台说明中给出的实用区别。三种接口以不同层级暴露 Codex harness；它们不是三个不同模型，控制能力最多的选项也不一定最适合你的任务。
先看结论
如果还没确定自己需要的是模型 API 还是完整执行循环，先看 Agent harness 和模型的区别。本文假设你已经决定集成 Codex harness。
三种 Codex 接口分别负责什么
Codex harness 管理的不只是一个 Prompt。OpenAI 把它描述为负责延续对话状态、流式输出执行过程、使用工具、执行已配置的沙箱与审批规则，以及让工作跨 Turn 继续的那一层。
集成方式决定了外围的宿主应用需要直接控制多少生命周期：
exec给宿主一个可以运行的命令和可以消费的输出；- SDK 给应用代码一个更高层的 Codex Thread 编程接口；
- app-server 暴露底层 Client Protocol，让应用参与 Agent 生命周期。
模型、计费路径和托管服务仍是分开的决定。选择 app-server 不会获得另一个模型，选择 SDK 也不会自动决定代码仓库或用户界面放在哪里。
MCP 是另一个独立层级：它为 Codex 扩展外部工具与上下文，却不会替你选择集成接口。需要这项能力时，应为 Codex 配置 MCP Server，并核对 Transport、作用域、凭据、工具与审批规则。
有边界的自动化优先选 codex exec
OpenAI 的非交互模式文档把 codex exec 定位为脚本和自动化入口。它可以通过 --json 输出 JSON Lines 事件流，也可以返回最后一条消息，或根据 Schema 生成结构化结果供下一步使用。
适合的场景包括：
- 总结 CI 失败；
- 在受控 Runner 中审查代码仓库；
- 生成结构化发布信息；
- 定时执行一个范围清楚的维护任务；
- 把一个 Agent 步骤放进 Shell Pipeline。
当任务有明确开始和结束时，进程边界是一项优势。如果产品需要长期对话、交互审批，或者展示每个进行中 Item 的细节，这种方式会不够方便。
安全配置仍然重要。官方文档称 codex exec 默认使用只读沙箱，并建议只授予自动化所需的最小权限。更宽的沙箱应该只在隔离、受控的环境里使用。
程序化 Agent 工作流优先选 SDK
官方 Codex SDK 文档把它描述为控制本地 Codex Agent 的服务端 Library。TypeScript Library 可以启动、继续和恢复线程；OpenAI 也提供了通过 JSON-RPC 控制本地 app-server 的 Python SDK 文档。
以下需求适合 SDK：
- 由应用事件创建一个编程任务；
- 用新指令继续同一个线程；
- 之后恢复一个已知线程；
- 把 Codex 集成到内部工具或服务；
- 用普通应用代码保留业务编排逻辑。
与自己实现 app-server Protocol 相比，SDK 提供的编程界面更简单。但外围应用仍要负责 Job 记录、权限、重试、日志，以及业务对象与 Codex Thread 之间的映射。
Thread resume 很有用，但不是完整的持久化设计。除了对话 ID，还要决定文件、进程、凭证和 Review 状态如何保存。持久化 Coding Agent Session 指南对这些层级做了拆分。
Agent 成为产品的一部分时评估 app-server
如果用户通过你自己的产品界面与 Agent 交互，可以评估 app-server。OpenAI 的 app-server 文档提供双向 JSON-RPC Client Protocol，用来管理线程、Turn、流式 Item、错误、审批、用户输入、工具和配置。但截至 2026-08-31，官方仍把 app-server command 标为 experimental，并明确不支持生产工作负载；在状态变化前，应把它视作原型和评估路径。
当产品需要以下能力时，这一层更合适：
- 不等最终结果，而是实时渲染 Agent 活动；
- 中断一个正在运行的 Turn；
- 在自己的 UI 中展示命令或文件修改审批；
- 把事件归属到正确的 Thread 和 Turn；
- 暴露应用自己的工具并处理结果；
- 在特定业务流程中持续保持 Agent 对话。
默认 stdio Transport 使用换行分隔的 JSON，WebSocket 是另一种 experimental Transport。改用 stdio 并不会让实验性的 app-server command 变成 production-supported。不要因为更换 Transport，就假设接口的官方支持状态或远程安全属性已经改变。
app-server 给产品团队更多控制，也带来更多责任：Protocol 版本、重连、事件顺序、等待中的审批、过载处理、Telemetry，以及让用户理解高影响操作的界面。
避免过度设计的迁移路径
从能满足任务的最小层级开始：
- 先用
codex exec和机器可读输出来证明一个有边界的工作流； - 当应用代码需要复用线程或更丰富的编排时，迁移到 SDK；
- 只有产品确实需要直接控制生命周期和用户体验时，才用 app-server 做原型；在官方支持状态变化前，不把它当作生产接口。
这不是强制升级路线。以 Agent 为核心的产品可以直接从 app-server 原型开始，成熟的 CI 工作流也可能一直停留在 exec。判断标准是额外控制能不能解决一个已命名的需求，同时不越过官方标注的生产支持边界。
在不同层级之间迁移时，保留同一组代表任务和验收标准。比较工具结果、文件改动、审批、失败处理、延迟和运维负担，而不只是最终文字看起来是否相似。
做决定前的安全与运维问题
无论使用哪种接口，上生产前都要回答：
- 谁的身份启动 Agent，它能访问哪个代码仓库？
- 默认沙箱是什么，谁可以扩大权限？
- 哪些命令、文件修改、网络操作或工具需要审批？
- Thread ID、事件日志和最终结果保留在哪里？
- 运维人员如何取消、重试或恢复工作，同时避免重复产生副作用？
- 宿主进程、app-server 或网络连接失败时会怎样？
- SDK、CLI 和 Protocol 版本如何在上线前测试？
用 Coding Agent Workspace 安全清单把这些问题变成明确边界。然后选择能够提供足够控制、又不会让团队承担多余 Protocol 和用户体验成本的接口。
有边界的任务从 codex exec 开始；程序化 Thread 工作流使用 SDK；Agent 嵌入产品时评估 app-server。你还可以单独查看 Agent.Space 当前可用的 Agent 入口，不要把这项产品选择与 Codex 集成层混为一谈。