Codex Python SDK 0.154.0：ExternalMessage 进 turn，不带用户授权

2026 年 9 月 10 日，OpenAI 发布 Codex Python SDK 0.154.0（GitHub tag python-v0.154.0）。同步和异步的 run() / turn() 都接上 ExternalMessage：外部内容可以开启一轮，也可以加入正在进行的一轮，权限是 tool-level，并不授予 user authorization。同版本还为 reasoning effort 增加 max 和 ultra，resume/fork 增加 include_turns。Python 要求 3.10+，运行时要匹配 openai-codex-cli-bin==0.154.0。

编辑绘制：Codex Python SDK 0.154.0 的 ExternalMessage、effort 新值和兼容要点 — 编辑绘制：0.154.0 三项可核验改动。依据 GitHub Release python-v0.154.0。

把 Codex 嵌进服务时，最烦的一步往往不是模型，而是“谁可以把一段外部输入送进正在跑的 turn”。以前要么让人在终端打字，要么自己伪造用户消息。本文只写 SDK 这一层：外部消息进 turn 之后，事件流、授权和升级断裂点分别在哪。CLI 0.154.0 的实验性 worktree 是另一件事，不在本文。

AI Coding 交流群

如果你也在用 AI 写代码，或者正在研究 Cursor、Claude Code 这些工具，欢迎加入以下交流群。群里平时会聊一些 AI 编程的实际用法、开发工作流，还有各种新工具和新玩法。

发生了什么

安装方式写在 Release 上：pip install --upgrade openai-codex==0.154.0。Changelog 把同一条记在 2026-09-10。tag 对应 commit 9fd29df。

ExternalMessage（PR #44086）接到同步和异步的 run() 与 turn()。官方句子有三层含义：外部内容可以开始一轮，也可以加入正在进行的常规 turn；它带的是 tool-level authority，不授予 user authorization；消费者拿到独立事件流。也就是说，CI、bot 或编排器可以把观察结果送进 Codex，但不因此获得用户点过的那张批准单。

同版本还加了这些可编程接口（PR #44084、#39662、#44032、#44400）：

reasoning effort 取值增加 max 和 ultra。
resume/fork 增加 include_turns；新开启的单次 turn 可设 turn_service_tier；增加 source 元数据。
历史筛选只改返回给你的响应，不改模型上下文。省略这些选项则保持旧默认。
协议模型与通知重新生成。到达 turn-start 之前的 completion 事件会被保留，避免开局丢事件。

自定义 codex_bin 若要使用 ExternalMessage 以及新的历史/单 turn 选项，需要 CLI 0.151.0 及以上。生产安装仍应让 SDK 与 openai-codex-cli-bin==0.154.0 对齐，而不是只升其中一个。

一次完整工作场景

假设你用 Python 把 Codex 嵌进内部机器人：测试失败时把日志送进正在跑的修复 turn，而不是另开一个“用户说请看日志”的会话。输入是测试 runner 的失败输出，操作是 SDK 的 ExternalMessage，交付是修复 turn 的工具调用，反馈是编排器自己的事件流。

把 SDK 升到 0.154.0，确认旁边的 CLI 二进制也是 0.154.0；若你覆盖了 codex_bin，至少 0.151.0。
用 run() 或 turn() 开一轮常规修复。人的授权仍按原审批流走——ExternalMessage 不会替你点同意。Release 写得很硬：它不授予 user authorization。
测试 runner 把失败日志作为 ExternalMessage 送入：可以开新 turn，也可以加入仍在进行的 turn。编排器订阅它自己的事件流，不要假设能看到用户侧那条流的全部历史。
若你是中途 attach 的 handle：Release 写明，迟到或手组的 turn handle 只从挂载点开始收事件，不回放更早输出。turn 已经结束后再 attach，可能抛 TransportClosedError。要读保存的历史，用 thread.read(include_turns=True)。由 thread.turn(...) 返回的 handle 会保留从请求发出时起的事件。
需要更强推理时，给新 turn 设 effort 为 max 或 ultra，或设 turn_service_tier。不要指望筛选历史就能让模型“没看见”那些 turn——官方写的是历史选择不改模型上下文。

编辑绘制：ExternalMessage 从输入、权限、事件流到人接管的四步 — 编辑绘制：外部消息进入 turn 的权限边界。依据 Release 原文：tool-level，不授予用户授权。

为什么这会改变工作流

被改掉的是程序化会话的输入通道。以前要把外部系统接到 Codex，你得假装那是用户打的字，于是授权、审计和事件流缠在一起。现在外部输入有名字、有独立事件流，并且被明确降权到 tool-level。CI 可以往 turn 里塞失败上下文，审批仍停在原来的人机边界。

这也逼你把“读历史”和“看直播”分开。attach 晚了就看不到更早的 token；完成后不能再挂。产品化时要先 thread.read(include_turns=True) 拿快照，再决定要不要加入进行中的 turn。独立事件流意味着监控面板应订阅编排器那条流，而不是去复用用户会话的 transcript API 当直播源。

effort 的 max / ultra 把“这一轮要想多久”从全局默认里拆出来，可以按 turn 设。它改变的是单次 turn 的推理强度，不是 ExternalMessage 的权限。两者常被一起升级，但不要写成互为前提。source 元数据则让你在日志里标出这段输入来自测试系统还是人工会话，方便事后对账。

升级清单可以写成四步：先对齐 SDK 与 CLI 二进制版本，再改 hook 读 .root，再把监控从“复用用户 transcript”改成订阅独立事件流，最后才把测试失败日志接进 ExternalMessage。顺序反了，你会分不清是权限问题、事件回放问题，还是二进制太旧。Release 也写了：这些新选项省略时保持旧默认，所以可以先升级包，再逐项打开 ExternalMessage 和 include_turns。

限制与人接管点

人必须接管的第一件事是 ACL。SDK 不决定谁可以发 ExternalMessage。你的服务鉴权如果把任意内部任务暴露成可写 turn，tool-level 只表示它不是用户授权，不表示它不能触发工具。工具调用仍走原审批；人要决定的是：哪些服务账号允许往进行中的 turn 写外部内容。

升级有断裂点。Release 写明 HookMetadata 把处理器包进 .root，例如先看 hook.root.handler_type 再读 hook.root.command。一部分原先未知的通知现在有具名字段，不要再走 .params；未知或非法的仍映射为 UnknownNotification。漏改 hook 的服务会在升级后读到空字段，表现为“hook 没跑”，其实是路径变了。

自定义二进制过旧会让 ExternalMessage 和新的历史/单 turn 选项不可用。Python 版本低于 3.10 不在支持范围。0.155.0 的 alpha 标签在 9 月 14 日附近出现，但那是预发布，Release 页没有完整说明；稳定说明仍以 0.154.0 为准。

CLI 0.154.0 的 --worktree / /worktree 是隔离检出，已有独立稿。本文事件是 Python SDK 的输入通道和 effort 取值，不要把两件事拼成一次升级清单。GPT-6-Astra 进入 CLI 模型选择器和 Bedrock 目录也属于 0.154.0 CLI 发行说明，不是 Python SDK 这次的接口变化。

如何试用

在 Python 3.10+ 环境执行 pip install --upgrade openai-codex==0.154.0，并安装匹配的 openai-codex-cli-bin==0.154.0。写一个最小脚本：先 turn() 开一轮，再从第二条任务把 ExternalMessage 加进去，分别打印两条事件流。然后故意在 turn 结束后 attach，确认是否看到 TransportClosedError；再用 thread.read(include_turns=True) 读保存历史。把 hook 回调改成读 .root。若你覆盖 codex_bin，先核对 CLI 版本。

验证完就停在 0.154.0 稳定版，不要把 9 月 14 日的 alpha 标签写进生产依赖。若你只是在终端里用 Codex CLI 做隔离检出，去看 worktree 那篇，而不是把 SDK 的 ExternalMessage 理解成 /worktree 的 Python 版。