上周三公司项目要从 GPT-4o 升级到 GPT-5.5，老板的原话是"新模型出了就上，别等"。我花了大半天把 API 接进来，结果旧代码一跑全是 400，三个坑踩了个遍。这篇把我踩过的坑和最终跑通的配置完整记录一下——GPT-5.5 的 model 字段命名规则变了、max_tokens 参数被废弃改成了 max_completion_tokens、response_format 的 JSON Schema 校验比 GPT-4o 时代更严格，旧代码不改必挂。

这篇适合谁

• 已经在用 GPT-4o API，准备升级 GPT-5.5 的后端/全栈开发者
• 用 Cursor / Codex CLI / Cline 等工具想切到 GPT-5.5 模型的独立开发者
• 之前写了 structured output（JSON mode）代码，升级后突然全报 400 的人
• 想了解 GPT-5.5 和 GPT-4o 在 API 层面到底有哪些 breaking change 的人

整体流程

1. 安装或升级 openai SDK（pip install --upgrade openai）
2. 确认 API 通道可用（直连或通过聚合网关）
3. 修改 model 字段为正确的命名格式
4. 把 max_tokens 替换为 max_completion_tokens
5. 修复 response_format 的 JSON Schema 严格校验问题
6. 在 Cursor / Codex CLI 中配置新模型

先说结论

变更项	GPT-4o 时代	GPT-5.5 现在	不改的后果
model 字段	gpt-4o	gpt-5.5-preview-2026-05-06	返回 model does not exist
token 上限参数	max_tokens	max_completion_tokens	静默忽略或 400
response_format strict 模式	支持但非强制（GPT-4o 2024-08-06 起已支持 strict: true）	强制严格模式，多余字段直接拒绝	400 Invalid schema
openai SDK 最低版本	v1.x 可用	建议 v1.x 最新版（如 v1.84.x+）	部分参数不支持

graph LR
 A[你的代码] -->|修改 model + params| B{API 网关}
 B -->|直连| C[api.openai.com]
 B -->|聚合平台| D[OpenRouter 等]
 C --> E[GPT-5.5]
 D --> E

前提：确认 API 通道

GPT-5.5 目前是 preview 状态，通过 OpenAI 官方直连需要你的账户在 Tier 3 以上。如果你跟我一样懒得折腾账户升级，可以走聚合 API 网关——OpenRouter 这类平台已经接入了 GPT-5.5 preview 通道，改个 base_url 就行。使用前建议先调 /v1/models 端点确认该平台确实已上线对应模型。

先确认通道能通（以 OpenRouter 为例）：

from openai import OpenAI

client = OpenAI(
    api_key="your-key",
    base_url="https://openrouter.ai/api/v1"
)

跑一下 client.models.list() 看返回里有没有 gpt-5.5 开头的模型名，确认后再继续后面的步骤。

第一个坑：model name 格式变了

GPT-4o 时代你写 model="gpt-4o" 就完事了。GPT-5.5 不行——直接写 gpt-5.5 会收到这个：

openai.error.InvalidRequestError: The model `gpt-5.5`
does not exist or you do not have access to it.

折腾半天发现，GPT-5.5 的 model 字段必须带日期后缀或者用 preview 标记。以 OpenAI 官方及已上线该模型的平台为准，目前可用的命名格式为：

# 锁定日期快照（生产环境推荐）
model = "gpt-5.5-preview-2026-05-06"
# 常青池别名，自动指向最新 preview 快照
model = "gpt-5.5-preview"

gpt-5.5-preview 是常青池（evergreen）别名，自动指向最新的 preview 快照。生产环境建议锁定日期版本，防止模型行为突然变。使用前请先通过 /v1/models 确认你所用平台支持的具体 model ID，以平台实际返回为准。

第二个坑：max_tokens 被废弃了

这个坑更隐蔽。我原来的代码：

response = client.chat.completions.create(
    model="gpt-5.5-preview-2026-05-06",
    messages=messages,
    max_tokens=4096
)

跑起来不报错，但输出经常在很短的地方就截断了。查了半天日志才发现——GPT-5.5 的 API 已经把 max_tokens 标记为 deprecated，实际生效的参数改成了 max_completion_tokens。

旧参数在某些 SDK 版本里会被静默忽略，某些版本直接返回 400。改法很简单：

response = client.chat.completions.create(
    model="gpt-5.5-preview-2026-05-06",
    messages=messages,
    max_completion_tokens=4096
)

一字之差，但不改就是不生效。需要说明的是，max_tokens 在 Chat Completions API 中历来也只控制输出 token，max_completion_tokens 的语义与之相同——这次改动本质上是参数重命名以统一命名规范，而非控制范围的变化。别同时传两个参数，行为是 undefined，统一用新参数就好。

第三个坑：structured output 的 JSON Schema 严格校验

这个坑让我人傻了。我有一段用了大半年的 structured output 代码，GPT-4o 跑得好好的，换到 GPT-5.5 直接 400：

BadRequestError: 400 Invalid schema: additionalProperties
must be set to false for all objects in the schema

背景说明：strict: true 的 Structured Outputs 功能从 GPT-4o（2024-08-06 版本起）就已经支持，但彼时是可选的，不传 strict 也能走宽松校验。GPT-5.5 的变化在于：严格模式变成强制的，不再允许宽松校验——schema 里每一层 object 都必须显式声明 additionalProperties: false，而且 required 数组必须包含所有属性。

之前能跑的代码：

response_format = {
    "type": "json_schema",
    "json_schema": {
        "name": "user_info",
        "schema": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "age": {"type": "integer"}
            }
        }
    }
}

现在必须改成：

response_format = {
    "type": "json_schema",
    "json_schema": {
        "name": "user_info",
        "strict": True,
        "schema": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "age": {"type": "integer"}
            },
            "required": ["name", "age"],
            "additionalProperties": False
        }
    }
}

关键变化三处：加 "strict": True，加 "required" 列出所有字段，每层 object 加 "additionalProperties": False。嵌套对象的话每一层都要加，挺烦人的。

在 Cursor / Codex CLI 中配置

Cursor 配置

Cursor Settings → Models → 添加自定义模型：

• Model Name: gpt-5.5-preview-2026-05-06（或你所用平台支持的具体 model ID）
• API Base URL: 你所用平台的 API 地址
• API Key: 你的 key

Codex CLI 配置

Codex CLI 的配置字段名因版本而异，部分版本使用 baseURL，部分版本通过环境变量 OPENAI_BASE_URL 配置，建议以你所安装版本的官方文档为准。以下为参考示例：

# ~/.codex/config.yaml（字段名请以官方文档为准）
model: gpt-5.5-preview-2026-05-06
api_key: your-key

或通过环境变量：

export OPENAI_BASE_URL="https://your-gateway/v1"
export OPENAI_API_KEY="your-key"

--model flag 在部分版本的 Codex CLI 中可用，使用前请确认你的版本支持：

codex --model gpt-5.5-preview-2026-05-06 "重构这个函数"

不同场景怎么选

个人开发者 / Side Project：直接用 gpt-5.5-preview 常青池别名，省心。个人项目模型行为变一点无所谓。

生产环境后端服务：锁定 gpt-5.5-preview-2026-05-06 日期版本。等 stable 版出来再切，preview 的行为可能每周都在变。

Cursor / Cline 等编程助手：用 preview 就行，编程场景对输出一致性要求没那么高。

已有大量 structured output 代码的项目：先别急着升级。把所有 response_format 的 schema 过一遍，确保每层都有 additionalProperties: false 和完整的 required，再切模型。我们项目有 17 个 schema，改了一下午。

常见问题 FAQ

Q: GPT-5.5 preview 和 stable 有什么区别？什么时候出 stable？

Preview 是抢先体验版，模型权重可能每周更新，输出行为不保证一致。Stable 版目前没有明确日期，生产环境如果对输出一致性要求高，建议先观望。

Q: openai Python SDK 需要升级到什么版本？

建议升级到 v1.x 系列的最新版本（截至目前为 v1.84.x 左右）。低版本的 SDK 可能不认 max_completion_tokens 参数，也可能缺少 strict schema 的类型定义。pip install --upgrade openai 一把梭，装完用 pip show openai 确认版本号。

Q: 用了聚合平台还是报 model does not exist 怎么办？

检查两个地方：一是 model 名字有没有拼对（是 gpt-5.5-preview 不是 gpt5.5 也不是 gpt-5.5），二是你用的聚合平台是否已经上线了这个模型——不是所有平台都第一时间同步。先调 /v1/models 端点确认列表，以平台实际返回的 model ID 为准。

Q: max_tokens 和 max_completion_tokens 能同时传吗？

别这么干。同时传的行为是 undefined——有的版本以 max_completion_tokens 为准忽略另一个，有的版本直接 400。统一用新参数。

Q: structured output 的 strict 模式能关掉吗？

在 GPT-5.5 上目前没找到关闭的方法，严格模式是强制的。GPT-4o 可以不传 strict 走宽松校验，GPT-5.5 不再支持这种用法。如果你的 schema 确实需要灵活字段，可以把 response_format 改回 {"type": "json_object"} 然后自己在 prompt 里约束格式——但这样就没有 schema 保证了，属于降级方案。

小结

三个坑：model name 带后缀、token 参数换名字、schema 必须严格声明。改动量不大但不改就是全线 400，属于那种"知道了 5 分钟搞定、不知道能折腾一天"的问题。

SDK 升到 v1.x 最新版，把这三处改完，基本就能跑了。Cursor 和 Codex CLI 配好对应的 base_url 之后体验还是很顺畅的，GPT-5.5 的代码生成质量确实比 4o 好了一截——尤其是长上下文的理解能力，这个后面单独写一篇聊。