openai-python 3.15 / 3.16 与 openai-node 7.18 / 7.19 更新解读：缓存预热、Webhook 管理与 connector_id 弃用

OpenAI 官方 SDK 在 2026-09-18 一天发了六版：openai-python v3.15.0 / v3.16.0 / v3.16.1 / v3.16.2 与 openai-node v7.18.0 / v7.19.0。与上一批（3.14.x / 7.16–7.17）的"可靠性"主题不同，这一批以功能为主：prompt cache 有了预热开关、Webhook 端点第一次有了管理 REST 面、MCP 工具的 connector_id 正式标弃、WebSocket 连接补上会话层。本文逐项对应 PR 与类型源码拆解（全部基于 2026-09-19 当日经 GitHub API 重抓的 release notes、PR diff 与 v3.16.2 tag 源文件核对），示例代码取自官方 README 与类型定义。

1. 版本时间线

节奏看点：python 与 node 这次几乎成对发布——四大功能（agent session 设置、audio-mini、WS 会话、prewarm）落在 python v3.15.0 与 node v7.18.0，webhook 管理与 connector_id 弃用落在 python v3.16.0 与 node v7.19.0。两包版本号依旧不一一对应，同一功能在两边的落点版本不同是常态。

2. prompt-cache 预热：prewarm

prompt_cache_options 新增 prewarm（布尔，默认 false）。官方文档字符串原文："Prepares the prompt cache without generating output. Defaults to false. When set to true, overrides the generate field to false."——准备缓存但不生成输出。

它解决的问题：长会话在真正发起大请求之前，把系统提示、工具定义这些稳定前缀先写进缓存，让后续正式请求直接命中缓存。典型姿势是配 WebSocket 的 warmup 模式：先发一个 generate: false 的 response.create 事件准备状态、不产出模型输出，再发正式请求——官方 README 把这称为 warmup 模式；而 prewarm: true 落在 prompt_cache_options 里，按其文档字符串置 true 时会强制覆盖 generate 为 false。

response = client.responses.create(
    model="gpt-5.6-terra",
    input=[
        # 长而稳定的系统提示与工具定义
    ],
    prompt_cache_options={
        "mode": "implicit",
        "ttl": "30m",
        "prewarm": True,
    },
)

两个既有约束不变：prompt_cache_options 仅支持 gpt-5.6 及之后的模型；ttl 仍只有 30m 一档。对应的诊断面（prompt_cache_diagnostics）可用来验证预热后正式请求是否命中（本站此前有专文拆解）。

3. Webhook 端点管理：client.webhooks

新顶层资源 client.webhooks，REST 面是完整的端点生命周期：

另有子资源 client.webhooks.event_types.list() 拉取可用事件类型。可订阅的事件枚举共 18 个值，七个族：batch.*（completed / failed / expired / cancelled）、response.*（completed / failed / cancelled / incomplete）、eval.run.*（succeeded / failed / canceled）、fine_tuning.job.*（succeeded / failed / cancelled）、realtime.call.incoming、video.*（completed / failed）、safety.alert.created。

endpoint = client.webhooks.create(
    event_types=["response.completed", "safety.alert.created"],
    name="prod-responses",
    url="https://example.com/hooks/openai",
)
save_secret_somewhere_safe(endpoint.signing_secret)  # 仅此一次明文

密钥安全模型要记住一条：signing_secret 明文只在创建与轮换两个时机返回；其余场合只有 signing_secret_hint（掩码提示）。另外 updated_at 字段的官方注释写明：测试与未变更的更新不会推进它——用它判断端点配置是否真被改过是可靠的。

4. MCP connector_id 弃用：两条迁移路径

MCP 工具的 connector_id 字段在 OpenAPI 规范里标了 deprecated: true，官方文档字符串原文："This field is deprecated for models released after September 1, 2026. Use server_url to connect to a remote MCP server, or tunnel_id to connect through a Secure MCP Tunnel."

拆开读三个限定：其一，弃用对象是 connector_id 这种"服务连接器直连"方式，不是 MCP 工具本身；其二，生效口径按模型划线——2026-09-01 之后发布的模型，此前发布的模型不在弃用表述内；其三，迁移路径两条：server_url（连你自己的远程 MCP 服务器）或 tunnel_id（Secure MCP Tunnel 隧道）。

Responses / beta / Realtime 各形态的 MCP 工具类型（Mcp、RealtimeResponseCreateMcpTool 等）同步标注。如果你的代码还在用 connector_id 直连 Dropbox / Gmail 这类服务连接器，而模型列表可能换到 9-01 之后的版本，升级前先迁到 server_url 或 tunnel_id。MCP 侧的协议层知识不受影响——本站 MCP 频道的规范拆解仍然适用。

5. managed Responses WebSocket sessions：lane 路由与最终响应收集

client.responses.connect() 裸连接的老问题：一条连接上并发多个响应时，事件是混在一起的，路由要自己拼 stream_id、收尾要自己判断终态。这批在两个语言里各加了一个会话层（官方叫 managed sessions），思路相同、API 不同名。

python 侧是 openai.lib.responses_websocket 模块（需要 openai[realtime] extra）：

from openai import AsyncOpenAI
from openai.lib.responses_websocket import AsyncResponsesWebSocketSession

async with AsyncOpenAI() as client:
    async with client.responses.connect() as connection:
        async with AsyncResponsesWebSocketSession(connection) as session:
            lane = session.lane("conversation")          # 注册命名 lane
            await lane.send({                             # 自动加 stream_id
                "type": "response.create",
                "model": "gpt-5.6-luna",
                "input": "Say hello.",
            })
            response = await lane.get_final_response()   # 消费完剩余事件，返回终态 Response

（示例改编自官方 README，模型名按本站现行家族替换；README 原示例还演示了用 ResponsesWebSocketLimits(max_lanes=8, max_events_per_lane=128, ...) 设六项预算。）

要点摘自官方 README 原文：lane.send 会给 response.create 自动加 stream_id 并拒绝冲突的路由元数据；get_final_response() 消费剩余事件并返回终态 Response（含 failed / incomplete），重复调用返回缓存结果、直到该 lane 上出现更新的 response.created；未注册路由的事件、未知事件与连接级错误都进默认 lane（session.default）——用命名 lane 时要盯着它消费；预算溢出抛 ResponsesWebSocketBufferError 并关闭所辖连接（宁可断也不静默丢事件）；lane 预算直到物理重连才释放。README 还给了 warmup（generate=False）、工具回合、fork 与 compaction 在 WS 上的标准姿势。

node 侧是 openai/lib/responses/responses-websocket-session 的 ResponsesWebSocketSession：lane.create(request) 发起、lane.receive({ signal }) 收原始事件、lane.finalResponse({ signal, maxResponseBytes }) 收终态；预算参数是 maxLanes / maxBufferedEvents / maxBufferedBytes，超预算时失败并排水最大积压（按字节优先，其次条数），嵌套 API 错误事件抛带原事件的 WebSocketError。

6. 其余改动速览

• agent session 模型设置（python #3882 / node #2755）：client.beta.agents.sessions.update(id, agent={...})，落在 POST /v1/agents/sessions/{id}。可改三项——model（字符串）、reasoning.effort（枚举 none / minimal / low / medium / high / xhigh / max）、service_tier（auto / default / flex / priority / fast）。官方文档字符串的语义限定要划重点："Model settings for subsequent turns. Omitted fields stay unchanged."——只影响后续 turn，省略的字段保持不变。
• Responses 接受音频模型（python #3886 / node #2759）：Responses model 联合新增 gpt-audio-mini 与 gpt-audio-mini-2025-12-15；Chat Completions 侧的 ChatModel 枚举里 gpt-5.1-mini 挪到表尾 legacy 区。注意这两个音频模型属于本站弃用日历里的 legacy 音频家族（2027-01-20 迁移窗口），选项开放不改变其生命周期定位。
• python v3.15.0 补齐压缩进度事件（#3866）：ResponseCompactionCompactingEvent（beta 变体带可选 agent.agent_name），字段 type / item_id / output_index / sequence_number，与 node v7.17.0 完全对齐——上一篇拆解的跨包差异就此收掉。
• python 两个修复版：v3.16.1 首次使用某 API 资源前不再加载无关资源（#3898，缩短启动路径）；v3.16.2 parse_response 去掉 TextFormatT 参数化修内存泄漏（#3084 / #3088）——长驻进程建议直接上 v3.16.2。
• 零散修复：python v3.15.0 保留 chat 流的审核结果（#3864）、澄清入站 SIP call ID 用法（#3885）、更新图像请求示例（#3889）；node v7.18.0 校验 WebSocket 结果并保留 header 默认值（#2763）。

7. 升级注意事项与常见错误

• 从 v3.14.x 直接升 v3.16.2、从 v7.16/v7.17 升 v7.19.0 即可，两批改动不冲突。
• prewarm 不生效：先确认模型是 gpt-5.6 及之后（prompt_cache_options 整体的前提）、再确认没有同时传 generate: true 的 WS 事件（prewarm 会覆盖它）、最后用 prompt_cache_diagnostics 验证命中。
• webhook signing_secret 丢了：没有第二次明文获取机会，只能 rotate_secret 重置（注意 keep_old_secret_active_for_24_hours 默认行为与你的灰度窗口匹配）。
• connector_id 调用报错/被弃：按模型版本对照弃用划线（2026-09-01 之后发布的模型），改 server_url 或 tunnel_id。
• WS 会话收到"不属于任何 lane"的事件：那是默认 lane 的职责（未注册路由、未知事件、连接级错误），用命名 lane 时记得消费 session.default。
• 升级后启动变快但资源属性访问报错：v3.16.1 起资源懒加载，若代码依赖 client.resources 的隐式全量加载行为需要自查（官方修复说明：avoid loading unrelated API resources on first use）。

8. 下一步

• Responses API 压缩进度事件解读：response.compaction.compacting、compaction_trigger 与长会话上下文压缩——本文第 6 节收掉的跨包差异，事件语义的完整拆解在那边。
• openai-python 3.14.x 与 openai-node 7.16 / 7.17 更新解读：流式错误规范化、WebSocket 背压与 SSE 兜底——上一批的可靠性主题，本文这批 WS 会话层建立在它的背压机制之上。
• openai-python 3.9 / 3.10 与 openai-node 7.11 / 7.12 更新解读：prompt cache 诊断、API key 过期与 GPT Image 2.5——prompt_cache_diagnostics 与 prompt_cache_options 的来龙去脉，验证 prewarm 命中要用到。
• gpt-6-astra 现身 OpenAI SDK：ChatModel 枚举新模型 ID 与 Safety Alerts API 解读——webhook 事件枚举里的 safety.alert.created 对应的 Safety Alerts 体系。
• Codex CLI 0.154.0 与 SDK 0.154.0 发布解读：worktree、ExternalMessage 与 ultra 推理档——同在 9 月的 Codex 侧发布解读；CLI 0.155.x 的解读见本站最新文章。