Codex CLI 0.154.0 与 SDK 0.154.0 发布解读：worktree、ExternalMessage 与 ultra 推理档

Codex CLI 0.154.0 是 2026-09-09 发布的稳定版命令行代理，Python SDK openai-codex 0.154.0 与 TypeScript SDK @openai/codex-sdk 0.154.0 在次日跟上。这一对版本的核心叙事只有一句：GPT-6-Astra 首次进入可选面（详见《GPT-6-Astra 落地：进入 Codex 模型选择器与 Amazon Bedrock 目录》）；但版本本身携带的改动远不止模型——worktree、内联问答、Windows 后台 server、SDK 的 max/ultra 推理档与 ExternalMessage，都是会改变日常用法的东西。

本文事实全部来自 2026-09-15 当日可加载的 GitHub release notes、PR 正文与 tag 源码；语音运行时一节特别强调"构建侧披露"与"已上线功能"的边界。

1. 概述：两张改动清单

CLI 0.154.0（2026-09-09T22:35 UTC 发布）的 New Features 六条、Bug Fixes 六条、Chores 一条；SDK 0.154.0（2026-09-10T19:51 UTC 发布）功能四条加迁移注意三段。按影响面重新归类：

2. CLI 0.154.0：值得记住的六个改动

2.1 实验性 worktree：--worktree 与 /worktree

官方描述：为新会话或 fork 创建隔离检出（isolated checkouts），入口是命令行 --worktree 或会话内 /worktree，创建后可以浏览并恢复这些 worktree 会话。标注为实验性。此前用裸 git worktree 手动搭建的多任务并行流程（见《Codex 团队协作最佳实践：worktree、审查与 CI 集成》）从此有了官方入口。

2.2 任务进行中的内联问答

Codex 继续干活时，你可以直接插进去问一句——用建议选项（suggested choices）或自定义文本，不打断主草稿（without losing your main draft）。这对"长任务跑着，顺手问一下进度/改一下需求"的场景是实打实的体验改进。

2.3 Windows：共享后台 server

Windows 会话现在可以共享一个后台 Codex server，配 daemon 生命周期命令与托管更新（managed updates）。配合本版的 Windows sandbox 供给协议系列改动（#42337 / #42341 / #42348 / #42351 / #42353 等一整批 changelog 条目），Windows 侧的支持在本版密集落地。

2.4 MCP 与安全修复

• MCP OAuth：连接现在协调 OAuth token 刷新；刷新失败时弹出登录挑战，并且不自动重放被拒的工具调用（#42413 / #42552）。
• 启动信任：工作区信任建立前不再运行 workspace 控制的 PATH helper（#42324）；macOS sandbox 拦截终端输入注入（#42590）。
• 插件热刷新：外部插件升级或回滚后，既有会话能拾取新装的工具并刷新 skills 与 hooks（#42284 / #42593 / #42990）。
• 审批上下文：自动审批审查在压缩（compaction）后更好地保留授权上下文，并拒绝被新指令或新回答作废的审批（#42844 / #42852 / #43442）。
• 远端恢复：remote resume / fork 保留已存权限；在另一应用里打开的会话，恢复时呈现只读转录并保留草稿（#43253）。

2.5 codex mcp-server 入口移除

已弃用的 codex mcp-server 入口在本版彻底不可用（#42993）。如果你的脚本还在调用它，升级前先改。MCP 服务端的标准做法（stdio / Streamable HTTP 传输）不受影响——本站 MCP 频道的指南仍然适用。

2.6 编辑器细节

Vim 编辑新增 R 替换模式（带 undo 与 dot-repeat，legacy 终端的 Escape 处理也更可靠）；复制响应到富文本应用时保留格式，/copy 可以复制状态输出或单个会话字段。

3. SDK 0.154.0：推理档补齐与外部消息

Python 侧 pip install --upgrade openai-codex==0.154.0（Python 3.10+，含配套 openai-codex-cli-bin==0.154.0 运行时）；TypeScript 侧 @openai/codex-sdk 0.154.0 为 npm latest（2026-09-15 经 registry 核对）。

3.1 max 与 ultra：阶梯补到七档

PR #39662（2026-08-20 合入，随本版发布）把两档新推理档写进 SDK 类型。TypeScript 侧的完整类型（PR diff，修改前是 minimal 到 xhigh 五值）：

export type ModelReasoningEffort =
  | "minimal"
  | "low"
  | "medium"
  | "high"
  | "xhigh"
  | "max"
  | "ultra";

注意 TypeScript 这套七值里没有 none——而 Python 官方示例（13_model_select_and_turn_params，python-v0.154.0 tag）的 REASONING_RANK 字典同时容纳 none 与 minimal，把九个档位名排成 0-7 的梯度：

REASONING_RANK = {
    "none": 0,
    "minimal": 1,
    "low": 2,
    "medium": 3,
    "high": 4,
    "xhigh": 5,
    "max": 6,
    "ultra": 7,
}

none 与 minimal 两个底档名在 Codex 生态并存，写代码时以你所用语言的类型定义为准，别跨语言照抄档位字符串。ultra 在 gpt-6-astra 捆绑元数据里的描述是 "Maximum reasoning with automatic task delegation"（自动任务委托），语义展开见 Astra 一文。

3.2 ExternalMessage：以工具权威注入外部内容

这是本版 SDK 最重要的新能力。动机（PR #44086 原文）：应用需要投递来自其他 agent、工具或服务的内容，赋予其工具级权威（tool-level authority），既不当作用户输入、也不授予用户授权。官方示例（16_external_message/sync.py，python-v0.154.0 tag）：

from openai_codex import Codex, ExternalMessage, Sandbox

with Codex(config=runtime_config()) as codex:
    thread = codex.thread_start(sandbox=Sandbox.read_only)
    thread.run(
        "When deployment notifications arrive, summarize their status and suggest "
        "what I should check. Do not change files or deploy anything."
    )

    # External content has tool authority; it does not supply user permission.
    result = thread.run(
        ExternalMessage(
            tool_name="notifications",
            namespace="slack",
            content="Staging deployment failed: the health check returned HTTP 503.",
        ),
        source="slack_notification",
    )

语义边界三条：外部内容可作为函数输出留在历史里；外部消息与用户输入列表、steer(...) 分开处理；需要 CLI 0.151.0 或更新（自定义 codex_bin 的部署注意版本门槛）。

3.3 include_turns、turn_service_tier 与 source

PR #44084 补齐历史与单 turn 选项：include_turns 挂在 resume/fork 上（省略保持服务器默认；False 跳过响应历史加载且不改变模型上下文）；turn_service_tier 覆盖单个新 turn 的服务档；source 是附带元数据。捆绑运行时依赖锁到 0.153.4，SDK 打包时会拒绝不支持的运行时版本。

3.4 升级迁移注意（官方 release notes 三条）

• HookMetadata 包了一层 .root：hook.command 改成 hook.root.command，先看 hook.root.handler_type 再读 handler 专属字段。
• 部分未知通知有了 typed payload：读命名字段，别再读 .params；未知或非法 payload 仍走 UnknownNotification。
• turn handle 附着语义：手动构造或晚加入的 handle 从附着点开始收事件，此前输出不回放——收集的结果可能不完整；attach 在完成之后可能抛 TransportClosedError，读存档历史用 thread.read(include_turns=True)。thread.turn(...) 直接返回的 handle 不受影响（从请求发出即保留事件）。

4. 语音运行时：构建侧信号，不是已上线功能

0.154.0 的 changelog 里藏着一组条目：macOS voice runtime projection（#42204）、GNU Linux voice runtime preparation（#42208）、Windows voice runtime preparation（#42209）、prepared runtimes 与 voice host 打包（#42332）。次日还有一个 prerelease voice-cygwin-*：为 Windows 原生语音发布提供离线构建输入——103 个 pinned Cygwin 二进制包加签名包索引、83 个对应源码包、每个二进制包到源码包的 SHA-512 映射，release 正文明确写着这些归档不包含在 Codex 用户包里。

结论：三平台语音运行时在准备中，证据都在构建层；没有任何"语音功能已可用"的用户面声明。写 Roadmap 引用时请保持这个口径。

5. 版本状态与安装

# Python SDK（含捆绑 CLI 运行时）
pip install --upgrade openai-codex==0.154.0

# TypeScript SDK（npm latest，2026-09-15 核对）
npm install @openai/[email protected]

# CLI 二进制跟随 0.154.x 稳定线；0.155.0 处于 alpha（alpha.4，2026-09-14）

6. 常见错误与排查

• 升级后 hook 全部失灵：九成是 HookMetadata 的 .root 包装——按 3.4 第一条改访问路径。
• ExternalMessage 报运行时不兼容：需要 CLI 0.151.0+；自定义 codex_bin 的环境检查版本，SDK 会在发送新选项时做运行时兼容检查。
• 给 turn handle 收不到早期事件：后加入的 handle 从附着点起收——不是 bug，是官方明确的语义；要完整历史用 thread.read(include_turns=True)。
• codex mcp-server 命令消失：本版移除，先迁移再升级。
• MCP OAuth 刷新失败后工具不重试：本版起不自动重放被拒调用——按官方设计，重新登录后手动重试。
• 把 voice changelog 条目当功能发布：见第 4 节，构建侧披露而已。

7. 下一步

• 《GPT-6-Astra 落地：进入 Codex 模型选择器与 Amazon Bedrock 目录》：本批最大新闻的完整拆解。
• 《OpenAI Codex CLI 入门：从零配置到日常编码流》：新手上路第一篇。
• 《Codex 团队协作最佳实践：worktree、审查与 CI 集成》：原生 worktree 之前的手动实践，思路仍通用。
• 《Codex CLI vs IDE 扩展 vs Codex Cloud：三种形态怎么选》：选形态看这篇。
• 《OpenAI 模型更新日志（2026 持续更新）》：全模型时间线。