---
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)
