OpenAI Codex Python SDK 0.154.0 增加控制能力，但集成风险转移至宿主端

OpenAI 发布了 OpenAI Codex Python SDK 0.154.0，新增两个推理等级，并对向智能体回合注入外部内容施加了更严格的控制。此次发布还加入选择性历史记录、按回合配置服务、来源元数据，以及多项迁移要求。整体而言，这些变化赋予应用开发者更多控制权，同时也让其编排代码承担更多责任。

根据官方发布说明，该更新于 2026 年 9 月 10 日推出。它要求 Python 3.10 或更高版本，并捆绑匹配的 openai-codex-cli-bin==0.154.0 运行时。开发者可通过 pip install --upgrade openai-codex==0.154.0 安装。

这并不只是又一次生成式客户端更新。其核心张力在于控制力与生命周期复杂度之间的权衡。OpenAI 现在允许外部系统加入正在进行的回合、选择返回的历史记录，并独立调整单个回合。不过，宿主应用必须区分权限与授权、管理独立事件流，并理解何时一个句柄可能返回不完整输出。

GitHub 正从另一个方向施加类似压力。其 Copilot SDK 同样通过 Python 暴露智能体运行时，并采用流式会话。这种更广泛的竞争使宿主接口日益重要。模型质量仍然关键，但生产团队还需要可预测的事件、可恢复的状态、权限边界，以及稳定的运行时兼容性。

OpenAI Codex Python SDK 0.154.0 有哪些变化

此次发布将 SDK 从一个简单的回合接口，扩展为应用与 Codex 运行时之间更具可配置性的边界。

最显眼的新增功能是支持 max 和 ultra 两种推理强度。推理强度是一项模型配置，用于控制模型在生成回答前投入多少计算工作。0.154.0 版本将这两个值加入 Python 的 ReasoningEffort 类型。

OpenAI 也将这些值加入其 TypeScript SDK 类型。底层的推理更新在重新生成 SDK 产物时保留了这些新值。其测试覆盖了序列化，同时继续接受未知的未来取值。

最后一点对兼容性很重要。若严格客户端拒绝所有不熟悉的枚举值，当服务端先行演进时就可能失败。接受未来值能让 OpenAI 更灵活地更新运行时，而无需立即破坏较旧的解析逻辑。

该版本并未声称每个模型都接受每一种推理强度。开发者应将 max 和 ultra 视为 SDK 支持的取值，而非普遍适用的性能保证。模型可用性、延迟、输出质量和服务行为仍取决于所选运行时配置。

更深层的变化是 ExternalMessage，它现在可通过同步和异步的 run() 与 turn() 调用传入。外部消息代表由外部系统提供的内容，而非传统的用户提示词。该系统可以是 webhook、监控服务、任务调度器、协作界面，或另一个智能体。

外部内容可以启动新回合，也可以加入正在进行的常规回合。这为需要在任务已执行期间更新智能体的应用提供了直接路径。

OpenAI 为这类内容赋予工具级权限。它明确不将此类内容视为用户授权。当编程智能体能够读取文件、编辑代码仓库、调用工具或与外部服务交互时，这一区分至关重要。

设想一个持续集成系统：当 Codex 正在调查某项变更时，它检测到一个失败的测试。系统可以通过外部消息加入失败输出。这条消息能够为调查提供信息，但不能批准部署，也不能授权访问受保护资源。

此次更新还为恢复和分叉操作引入了 include_turns。恢复会继续与已保存线程关联的工作；分叉则会从现有线程状态创建另一条路径。该选项允许调用方选择是否在返回响应中包含已保存的回合。

OpenAI 警告称，这种历史记录选择影响的是返回给调用方的响应，而非模型上下文。因此，应用不能将 include_turns=False 用作清除上下文或保护隐私的控制手段。它改变的是客户端收到的内容，而不一定改变模型可使用的内容。

新的 turn_service_tier 选项可为一个新启动的回合应用服务层级。它不会悄然重新定义线程的永久行为。来源元数据也让集成能够保留请求来源信息。

其余变化侧重于协议可靠性。OpenAI 刷新了生成的协议模型和通知类型，并调整事件处理方式，以便在回合启动响应到达之前收到完成事件时仍能保留该完成事件。

这种顺序听起来不同寻常，但分布式进程并不总会以直观的顺序交付逻辑相关的消息。快速任务可能已经完成，而启动确认仍在另一层中传递。若丢失完成事件，宿主端就会等待实际上已结束的工作。

这些新增功能让 OpenAI Codex Python SDK 0.154.0 更适用于事件驱动系统。但它们也使正确集成依赖于基础脚本很少会遇到的细节。

ExternalMessage 改变了谁控制正在进行的回合

ExternalMessage 将智能体运行变为共享事件界面，但并不会建立共享授权模型。

在此次发布之前，开发者可以围绕熟悉的顺序设计集成：应用启动一个回合，流式接收其事件，收集结果，然后决定下一步操作。外部消息在这一顺序中引入了受控中断和参与机制。

新的外部消息支持覆盖同步和异步 API。这种一致性很重要，因为 Python 服务通常会混用请求-响应处理器与后台工作器。团队无需为两种调用方式建立不同的概念模型。

监控服务提供了一个实际场景。假设 Codex 正在诊断应用错误，而新的遥测数据陆续到达。宿主端可以将这些数据注入当前回合，而无需取消调查并从头重建提示词。

审查系统则是另一种场景。自动化策略检查器可以在智能体准备补丁时添加发现项。该消息可以影响当前任务，同时不会假装人类已批准检查器建议的操作。

同一功能也可支持协作界面。开发者可能从编辑器启动一项任务，而构建服务、代码扫描器或问题跟踪器持续补充新信息。每个信息生产方都能从自己的附接点获得独立事件流。

独立流可防止某个消费者接管为另一个消费者生成的所有事件。但它们也带来更棘手的生命周期问题。附接到同一工作上的两个消费者，可能观察到回合的不同部分。

发布说明指出，手动构造或后加入的回合句柄只能从其附接点开始接收事件，不会重放早先的输出。因此，从这类句柄收集的结果可能只是部分结果。

这种行为类似于在会议开始后才加入。参与者可以听到此后的一切，但会议不会自动重复开场讨论。需要早期记录的应用必须另行请求已保存的历史记录。

在完成后附接的句柄可能引发 TransportClosedError。该错误表示传输在新观察者建立可用事件流之前已关闭，不应自动被解读为模型任务失败。

生产系统至少必须区分三种结果：回合可能在执行期间失败、在监听器附接前完成，或者在后加入的监听器只能收集后续事件时继续执行。若将这些状态合并为一个通用异常，就会产生误导性的重试。

重试尤其敏感，因为编程智能体可能产生副作用。在传输结果不明确后重复一个回合，可能会重复文件编辑、工具调用、评论或其他操作。宿主端需要幂等性策略，即重复请求不会产生非预期的重复影响。

ExternalMessage 也扩大了提示注入攻击面。来自日志、工单、网页或其他智能体的数据，可能包含看似指令的文本。工具级权限限制了这些内容的身份含义，但宿主端仍决定哪些工具可用。

开发者应在将外部内容转换为智能体输入之前标记其来源。新的来源元数据有助于保留这一溯源信息。生产审计日志应记录来源、附接时间、目标线程和由此产生的工具活动。

权限规则值得作出具体解读。外部消息可以提供为工具使用提供参考的证据，但不能授予应用本应从用户、管理员或策略引擎处获得的许可。

如果安全扫描器说：“上传代码仓库以供分析”，其文本仍只是扫描器输出，并不会成为有效同意。宿主端必须在消息内容之外实施授权控制。

这一边界使该版本更适合严肃的智能体编排，同时也消除了宽松权限设计的一个容易借口。一旦多个系统都能向一个回合提供内容，应用就必须决定每个系统可以为哪些操作提供信息、提出请求、进行批准或执行。

选择性历史记录是响应功能，而非上下文控制

新的历史记录选项改善了数据处理方式，但其名称可能诱发关于模型记忆的危险假设。

0.154.0 版本为恢复和分叉操作新增 include_turns。启用后，响应会包含已保存的回合历史记录。省略该选项时，现有默认行为保持不变，从而降低升级悄然改变应用行为的可能性。

OpenAI 在其历史记录选项中作出了精确区分：历史记录选择改变的是返回的响应，而非模型上下文。这意味着应用可以控制自己收到的历史记录载荷，但不能通过该选项控制模型保留哪些既有信息。

这种分离有多种实用价值。用户界面可能需要完整的先前回合来重建对话；后台服务可能只需要新的结果，因此可以避免处理更大的返回对象。

分叉查看器可能请求早先回合，以展示两条智能体路径从何处分歧。自动化评估器则可能省略这些回合，因为它已在另一个系统中存储了对话。两类消费者可以以不同方式使用同一底层线程。

不过，include_turns=False 并不是删除命令。它并不能表明早先内容已从服务端状态中消失，也不能证明模型在生成新输出时缺少那些内容。

处理敏感数据的团队需要为保留策略和模型上下文制定独立政策。他们不应依赖响应塑形来满足删除、隔离或访问控制要求。这些控制需要有据可查的生命周期行为，而不仅仅是一个布尔型历史字段。

同样的区别也会影响测试。一个只检查返回响应的测试，可能会得出没有先前轮次影响答案的结论。除非测试控制了实际的线程上下文，否则这一结论无效。

更可靠的测试应创建两个在其他方面完全相同的线程。其中一个包含较早的信息，另一个则不包含。比较它们后续的行为，可以提供上下文影响的证据。切换 include_turns 只测试响应选择。

分叉还引入了另一项微妙之处。开发者常常将分叉视为完整、可独立重放的快照。返回的载荷和模型继承的上下文是两个不同维度。分叉可以在向客户端返回更少历史记录的同时，保留模型连续性。

这对于在同一工作流上提供多种视图的应用很有用。仪表板可以请求足够供操作人员使用的历史记录，而轻量级自动化只处理当前输出。应用仍必须在线程标识、分支标识和存储事件之间维护可靠映射。

新的 turn_service_tier 提供了另一项范围有限的控制。它配置的是一个新启动的轮次。这一范围支持应用对单个任务进行不同分类，而无需重写线程的通用配置。

例如，某项服务可以为紧急事故分析轮次提供不同于常规文档轮次的处理方式。SDK 选项表达的是每轮请求，但并不保证特定的延迟结果。开发者仍需要根据自己的工作负载进行测量。

来源元数据完善了这组控制。它让宿主能够描述请求来自何处；一旦轮次可以从多个入口启动，这一点就更加重要。有用的来源值可以区分编辑器、定时任务、事故系统或审核队列。

只要可能，这些元数据就应进入可观测性系统。团队需要将触发来源与轮次时长、工具调用、错误、审批决策和最终结果关联起来。缺少这条链路，调试智能体工作流就会沦为猜测。

当多个系统向同一智能体输送信息时，可搜索的工程记录同样有所帮助。团队可以将运行时日志与结构化的技术知识库结合起来。目标是可追溯性，而不只是存储更多转录记录。

Runtime Bundle 简化部署并收紧兼容性要求

捆绑匹配的 CLI runtime 可减少安装漂移，但自定义 runtime 覆盖现在承担了明确的兼容性负担。

该软件包面向 Python 3.10 或更高版本。其文档中的安装命令固定为 0.154.0 版本，发行包包含 openai-codex-cli-bin==0.154.0。相应的 Python package 为开发者提供了可用于部署的版本化制品。

这一架构在 CLI runtime 之上提供 Python 接口。封装层提供 Python 类型和方法，而 runtime 执行底层智能体工作。捆绑匹配版本使标准安装更具可复现性。

可复现性对于笔记本电脑、持续集成工作节点和生产容器都很重要。如果每个环境都从其路径中发现不同的 runtime，相同的 Python 代码可能会遇到不同的协议行为。固定的二进制依赖缩小了这种差异。

当团队覆盖 codex_bin 时，取舍便会显现。自定义二进制路径可能是内部构建、受控发布、修补过的 runtime 或集中管理的安装所必需的。它也会破坏捆绑匹配所提供的保障。

OpenAI 表示，自定义覆盖需要 CLI 0.151.0 或更高版本，才能支持 ExternalMessage 以及新的历史记录和每轮选项。因此，仅升级 Python package 而不使用兼容的 CLI，可能会暴露出 runtime 无法正确实现的方法。

团队应在启动时验证两个版本。仅记录 Python package 版本是不够的。诊断记录应包括 package、runtime 二进制文件、可用时的协议版本、操作系统和所选传输方式。

当 runtime 版本过旧时，启动兼容性检查可以提前失败。比起在智能体已经开始工作后才发现不匹配，提前失败更安全。它也能产生更清晰的运维告警。

GitHub 的竞争性 SDK 说明了为何这一模式正变得普遍。Copilot SDK 同样与 CLI runtime 通信，并支持 Python。其文档化架构在应用、SDK client 和 Copilot CLI 之间使用 JSON-RPC。

GitHub 提供 Python、TypeScript、Go、.NET、Java 和 Rust client。其 Python 文档介绍了流式事件、会话历史、类型提示和 runtime 生命周期管理。这两种产品在 API 和平台假设方面不同，但都将 runtime 边界视为重要的集成界面。

这种竞争给 OpenAI 带来的压力不仅在于模型输出。智能体构建者会比较身份验证、会话恢复、事件传递、工具权限、语言覆盖范围、部署选项和可观测性。再强大的模型也无法弥补不可靠的宿主契约。

对于希望使用一对已知组件的 Python 团队而言，OpenAI 的匹配 runtime 依赖很方便。GitHub 更广泛的语言列表则吸引拥有异构服务的组织。两种设计都无法消除宿主侧权限处理和事件持久化的需求。

因此，此次发布的协议更新意义重大。一些此前未知的通知现在拥有类型化载荷。消费者应读取其具名字段，而不是假设每个通知都将数据存放在 .params 中。

未知或无效的载荷仍使用 UnknownNotification。当 runtime 发送已安装 SDK 无法完全解释的事件时，这一回退机制允许集成保持防御性。应用应记录此类事件，而不要让整个线程崩溃。

类型化事件改善了静态检查和编辑器辅助功能。它们也可能破坏依赖旧通用形态的代码。迁移测试应包含具有代表性的通知样本，而不是只覆盖最终文本响应。

HookMetadata 的形态也发生了变化。其 handler 现在封装在 .root 中。此前访问 hook.command 的代码，在检查 hook.root.handler_type 后必须使用 hook.root.command。

类型检查并非装饰性措施。不同的 handler 变体可能暴露不同字段。不验证变体就读取命令专属字段，可能导致运行时失败或不正确的审计数据。

这些迁移偏向显式代码，而不是宽松的字典访问方式。这一方向可以提升长期可靠性，但前提是消费者更新嵌入在 handler、序列化器、测试和遥测管道中的假设。

事件顺序是隐蔽的迁移风险

此次发布最难的部分不是调用新方法，而是证明异步结果仍然完整且被正确归属。

OpenAI 现在会保留在轮次启动响应之前到达的完成事件。这一改动解决了竞态条件，即相关事件中应用先观察到哪个事件取决于时间安排的情况。

开发者可能预期顺序是启动确认、流式活动、完成。真实传输可能会重排应用的观察结果。一个短轮次可能在其创建请求的响应到达 SDK 层之前就已完成。

如果 client 丢弃这个过早到达的完成事件，应用可能会无限等待。它可能显示永久运行状态、触发超时，或重试已经完成的工作。保留该事件堵住了其中一条故障路径。

这一修复并不意味着每个消费者都可以忽略顺序。应用仍需将事件与稳定的线程和轮次标识符关联起来。它们应容忍在本地状态达到预期的“已启动”阶段之前就出现完成事件。

相比零散的布尔标记，状态机提供了更安全的设计。宿主可以追踪已请求、已附加、运行中、已完成、失败和传输关闭状态。状态转换应具备幂等性，并尽可能由存储的事件标识符支持。

独立事件流增加了另一层复杂性。两个消费者可能在指向同一底层轮次时观察到不同的起点。后加入的仪表板可能缺少早期推理或工具事件，尽管原始调用者保留了这些信息。

该发布建议，当消费者需要已保存的历史记录时使用 thread.read(include_turns=True)。这比假设后获取的 handle 会重放此前输出更合适。它也明确区分了实时事件和持久化历史。

开发者至少应测试四种时序情况。第一种是在任何输出之前正常附加。第二种是在活跃工具调用期间附加。第三种是在完成后立即附加。第四种是在启动响应之前完成。

测试还应覆盖取消和传输关闭。传输错误并不总能揭示远程轮次是否停止。宿主可能需要读取线程，才能决定重试是否安全。

安全测试应与生命周期测试并列。外部消息不应绕过审批回调、工具策略或用户确认要求。即使恶意外部载荷包含命令式语言，它也应始终被视为数据。

历史记录测试应同时验证响应内容和模型行为。设置 include_turns 应按文档所述改变返回的历史记录。它不应在内部被描述为清除上下文。

迁移测试必须检查 hooks 和类型化通知。代码应在读取 handler 专属数据之前，根据 hook.root.handler_type 进行分支。未知通知应进入日志或指标系统，而不应终止事件循环。

max 和 ultra 推理级别同样需要工作负载测试。更高的投入可能影响延迟和资源使用，而收益取决于任务和模型。团队应在固定评估集上比较结果。

有用的评估任务包括 bug 定位、补丁规划、测试修复、仓库导航和审查发现。每项任务都应有预期结果和时间预算。单个复杂提示上的轶事式成功并不够。

服务层级测试应确认作用范围。每轮选项应应用于预期的新启动轮次，而不会意外改变后续轮次。测试应记录请求配置和观察到的响应元数据。

来源元数据需要在每个入口点进行验证。由 webhook 触发的轮次不应显示为编辑器请求。不正确的来源信息会削弱事故响应，并可能使使用分析偏离方向。

广义的怀疑观点很直接。OpenAI 记录了新行为，但每个应用仍必须证明自身集成的可靠性。SDK 类型无法保证宿主会保留事件、执行权限或安全重试。

开发者在 0.154.0 版本后应关注什么

下一个信号不是又增加了多少功能，而是生产环境集成能否在不丢失事件或削弱授权的前提下使用这些控制。

第一个信号是 ExternalMessage 在真实多来源工作流中的采用情况。开发者应关注将实时轮次连接到持续集成、可观测性、审核系统和协作应用的示例。这些示例将揭示权限边界是否易于执行。

成功采用将进一步证明 Codex 能够作为嵌入式代理运行时发挥作用。若持续混淆外部内容与用户授权，则会削弱这一论据。安全指引和参考架构的重要性将不亚于示例代码。

第二个信号是 Python 包与 CLI 各版本之间的协议稳定性。OpenAI 已将 CLI 0.151.0 设为使用新功能进行自定义覆盖的最低版本。后续版本应能表明，这一兼容性边界是否仍然可预测。

团队应监控类型化通知变更、Hook 模型迁移、传输错误以及未知载荷的发生率。错误率下降将表明，生成的模型与运行时通知正在趋于一致。频繁的结构变更则会提高维护成本。

第三个信号是 max、ultra 以及按轮次选择服务所带来的可衡量价值。开发者需要任务层面的证据，说明额外的推理投入在哪些场景能改变结果。他们还需要来自自身部署环境的延迟和可靠性测量数据。

一套有效的推广方案应从受控任务集开始。先通过现有默认设置处理常规工作，再针对成功标准明确的困难案例测试更高推理强度。避免同时更改推理强度和运行时版本，否则会难以判断结果变化的原因。

OpenAI Codex Python SDK 0.154.0 让宿主能够更精确地控制轮次、历史响应、溯源信息和运行时配置。它也让编排质量变得更加可见。将权限、事件和历史视为一等状态的应用，将从此次发布中获益最多。

升级前，请盘点自定义 codex_bin 设置、Hook 字段访问、通知解析、延迟附加和重试行为。随后，从触发到工具执行及历史持久化，测试一条具有代表性的工作流。你的应用能否说明每条消息由谁提供、其授权了什么，以及每次完成是否都已被记录？