---
title: "用 Codex 升级 API 接入"
description: "说明 OpenAI API 升级时如何用 Codex 盘点现状、做最小迁移，并用 evals 验证行为没有退化。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

OpenAI API 升级通常不只是把 model name 改掉。API 参数、prompt 写法、tool 假设、response shape 和模型行为都可能变化。

> [!WARNING]
> 模型、推荐参数和迁移细节变化快。升级前必须实时查官方 docs，不能按旧教程硬改 model name。

<Cards>
  <Card title="API migrations" href="https://developers.openai.com/codex/use-cases/api-integration-migrations">
    官方 Codex API 集成迁移场景。
  </Card>
  <Card title="OpenAI docs" href="https://developers.openai.com/learn/docs-mcp">
    用官方 docs MCP / skill 查当前模型和 API guidance。
  </Card>
  <Card title="Evals" href="https://developers.openai.com/api/docs/guides/evals">
    升级后用 evals 验证业务行为没有退化。
  </Card>
</Cards>

## 推荐流程

```mermaid
flowchart LR
    Inventory["inventory"] --> Docs["official docs"]
    Docs --> Plan["minimal migration plan"]
    Plan --> Change["code / prompt / tools"]
    Change --> Evals["tests / evals"]
    Evals --> Review["human review"]
```

适合 Codex 的 API 升级任务：

- 盘点仓库里所有 OpenAI 调用点。
- 查当前官方模型、API 和 prompt guidance。
- 找到最小迁移方案。
- 更新代码、prompt、tool assumptions 和 response parsing。
- 标出需要人工 review 的行为变化。
- 构建 evals pipeline。

不适合：

- 只把 model string 换成“最新版”。
- 不看 response shape 就改解析逻辑。
- 不跑测试和 evals 就上线。
- 把迁移期间的行为变化当成“模型更聪明”而不记录。

## 起始提示词

```text
请使用 OpenAI 官方 docs，把这个 OpenAI integration 升级到当前受支持、适合本项目的模型和 API 能力。

要求：
- 先盘点仓库里当前使用的 models、endpoints、tools、response parsing 和 prompts
- 查当前官方 model guidance、prompt guidance 和 migration notes
- 制定最小迁移方案
- 除非新 API 或新模型明确要求，否则保持现有业务行为不变
- 标出需要人工 review 的 prompt、tool 或 response-shape 变化
- 跑现有 tests，并建议最小 evals 集合
```

这个 prompt 的核心是先查官方文档，再看仓库现状。不要直接说“换成最新模型”。

## 为什么不能只改 model name

模型升级经常牵动三类变化：

- API 变化：参数、tool calling、streaming、structured output 或 response shape 可能不同。
- 行为变化：输出偏好、推理深度、tool 使用方式可能不同。
- prompt 变化：旧 prompt 在新模型上可能还能跑，但不一定仍是推荐写法。

因此迁移时至少要同时看代码、prompt、tool assumptions 和评估结果。

## 盘点内容

让 Codex 先列出：

- OpenAI SDK 版本。
- endpoint / API surface。
- model names。
- temperature、reasoning、response format 等参数。
- function / tool schemas。
- system、developer、user prompts。
- response parsing。
- retry、timeout、rate limit 策略。
- tests 和 evals 覆盖情况。

盘点结果保存成短报告，作为 migration diff 的依据。

## 推荐迁移顺序

1. 盘点调用点和行为契约。
2. 查当前官方 docs 和 migration guidance。
3. 写最小迁移计划。
4. 修改 API 参数和模型调用。
5. 更新 prompt，但保留业务目标和输出契约。
6. 标出 prompt、tool、response shape 变化。
7. 运行现有测试。
8. 增加或运行 evals。
9. 对失败样例做差异分析。
10. 人工 review 行为变化后再扩大 rollout。

## Evals pipeline

每次改集成都应该跑一次 evals，确认关键 workflow 没有行为退化。

最小 evals 覆盖：

- 代表性输入。
- 期望输出或评分标准。
- tool calling 是否仍按预期发生。
- response shape 是否兼容下游解析。
- 关键业务场景是否保持质量。
- 失败样例是否能解释。

没有 evals 的模型升级，很容易变成“代码能跑，但业务行为变了”。

## 验收清单

- 官方 docs 已核对，链接记录在迁移说明里。
- 所有调用点、prompts、tools、response parsing 已盘点。
- 改动是最小迁移，不是顺手重构。
- 测试和 evals 已运行。
- 行为变化和未验证项写清。
- 回滚路径明确。

## 官方资料

- [Codex: API integration migrations](https://developers.openai.com/codex/use-cases/api-integration-migrations)
- [Latest model guide](https://developers.openai.com/api/docs/guides/latest-model)
- [Prompt guidance](https://developers.openai.com/api/docs/guides/prompt-guidance)
- [OpenAI Docs MCP](https://developers.openai.com/learn/docs-mcp)
- [Evals guide](https://developers.openai.com/api/docs/guides/evals)
