前言¶

用 Cursor、Codex 或 Claude Code 寫 OpenAI 相關代碼時，最常見的一類翻車不是語法錯，而是參數名、模型 ID、接口形態和文檔對不上。模型訓練數據有截止時間，API 又迭代很快：Responses API、Realtime、Apps SDK、Codex 配置項一變，助手仍按舊記憶往外編，代碼看起來能跑，一調就報錯。

OpenAI 官方爲此提供了兩件配套能力：只讀的 Developer Docs MCP 服務，以及指導助手「先查官方文檔再回答」的 Agent Skill——openai-docs。Skill 負責路由與引用紀律，MCP 負責把 developers.openai.com 等站點上的最新頁面拉進上下文。兩者一起用，纔是官方推薦的組合。

本文基於 OpenAI 倉庫中 curated 版 openai-docs 的 SKILL.md，以及官方 Docs MCP 說明交叉覈實後整理。

這是什麼¶

openai-docs 是 OpenAI 維護的 Agent Skill（通用 SKILL.md 格式），定位很明確：在用戶詢問 OpenAI 產品/API 用法、Codex 自身能力與界面選型、需要帶引用的最新官方文檔、模型選型或模型/提示詞升級時，優先通過官方 Docs MCP 取證，再組織回答。

倉庫路徑：

https://github.com/openai/skills/tree/main/skills/.curated/openai-docs

它依賴的 Docs MCP 服務端點爲：

https://developers.openai.com/mcp

官方說明見：https://developers.openai.com/learn/docs-mcp

該 MCP 只讀文檔，不會替你調用 OpenAI API，覆蓋站點包括 developers.openai.com、platform.openai.com、learn.chatgpt.com。

Skill 包大致結構如下：

openai-docs/
├── SKILL.md
├── agents/openai.yaml      # 聲明依賴 openaiDeveloperDocs MCP
├── assets/
├── references/             # 模型選型/升級/提示詞的本地兜底參考
│   ├── latest-model.md
│   ├── upgrade-guide.md
│   └── prompting-guide.md
└── scripts/
    ├── fetch-codex-manual.mjs
    └── resolve-latest-model-info.js

核心功能與亮點¶

根據 SKILL.md 與 agents/openai.yaml，該 Skill 主要做這幾件事：

1. 官方文檔優先檢索與引用
   對非 Codex 的 OpenAI 文檔問題，先用 Docs MCP 的 search_openai_docs 找頁，再用 fetch_openai_doc 拉取正文後再答；API 形態、schema、參數、必填字段等問題，在可用時還會走 get_openapi_spec 覈對接口形狀。需要瀏覽發現頁面時才用 list_openai_docs。

2. Codex 自知識單獨走手冊鏈路
   關於 Codex 配置、擴展、Skills/Plugins/MCP/Hooks、AGENTS.md、各端界面等「Codex 自己是什麼」的問題，優先運行 skill 內腳本拉最新 Codex manual（並生成本地 outline），而不是一上來就當普通網頁搜。手冊不夠或 helper 不可用時，再窄範圍走 Docs MCP，最後才允許限定在官方域名的網頁回退。

3. 模型選型與升級/提示詞遷移
   「最新模型」「默認用哪個」「遷到某模型」「提示詞怎麼改」這類問題由該 Skill 接管：優先拉取遠程 latest-model.md；動態「最新/當前」升級會跑 resolve-latest-model-info.js；遠端不可用時才用 references/ 裏的兜底文件，並要求披露使用了 fallback。用戶若明確說「遷到 GPT-5.x」之類目標，應保留該目標，只把更新的官方指引當作可選說明。

4. 來源紀律：少猜、可追溯
   以官方文檔爲真相來源；文檔衝突要同時引用；查不到就說查不到；網頁回退僅限 developers.openai.com、platform.openai.com 等官方域。這正好對準「胡編參數、過時示例」的痛點。

安裝與啓用¶

Skill 與 MCP 是兩層：Skill 告訴助手怎麼查；MCP 提供查得到。官方 Docs MCP 頁也寫明：使用 Skills 時，應把 Docs MCP 與 OpenAI Docs Skill 配對。

1. 配置 Docs MCP（必做）¶

Codex（CLI / IDE 共用配置）

codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
codex mcp list

或寫入 ~/.codex/config.toml：

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

若希望 Codex 更穩定地主動走 MCP，官方建議在項目 AGENTS.md 中加一句引導，例如：需要 OpenAI API / plugins / ChatGPT / Codex 相關信息時，始終優先使用 OpenAI developer documentation MCP，而不必每次口頭提醒。

Cursor
在 MCP 設置中增加指向 https://developers.openai.com/mcp 的 HTTP/streamable 服務，名稱建議用 openaiDeveloperDocs（與 Skill 聲明一致）。

Claude Code

claude mcp add --transport http openaiDeveloperDocs https://developers.openai.com/mcp

Skill 內還規定：若會話裏 MCP 工具不可用，助手應先自行嘗試執行上述 codex mcp add ...；權限/沙箱失敗則提權重試；仍失敗再讓用戶安裝並重啓後再查文檔。

2. 安裝 openai-docs Skill¶

該 Skill 採用通用 Agent Skills 目錄約定，可在支持 SKILL.md 的工具間複用。目錄名需與 frontmatter 中的 name 一致：openai-docs。

在 Codex 中（官方 skills 倉庫說明）
curated 技能可用 $skill-installer 按名稱安裝，例如：

$skill-installer openai-docs

安裝後需重啓 Codex 以加載新 Skill。倉庫 README 還提到：.system 下的部分技能會隨較新版本的 Codex 自動安裝；本文介紹的是 .curated/openai-docs 這一份公開 curated 包，以倉庫內該目錄與 SKILL.md 爲準。

在 Cursor 中
將整個 openai-docs 文件夾放到項目或用戶技能目錄，例如：

# 從倉庫檢出後拷貝（路徑按你本地 clone 位置調整）
cp -r skills/.curated/openai-docs .cursor/skills/openai-docs

Cursor 還會掃描 .agents/skills/、~/.cursor/skills/、~/.agents/skills/，以及兼容路徑 .claude/skills/、.codex/skills/。也可在 Agent 對話裏用 /openai-docs 手動喚起（若客戶端支持按名調用）。

在 Claude Code 中

mkdir -p .claude/skills
cp -r skills/.curated/openai-docs .claude/skills/openai-docs

個人全局目錄則爲 ~/.claude/skills/openai-docs/。

拷貝後確認目錄內至少有 SKILL.md，以及 scripts/、references/（Codex 手冊拉取與模型兜底依賴這些文件）。

典型用法示例¶

下面幾類提示，最容易觸發該 Skill 的設計路徑（表述可按你的工具習慣微調）：

查 API / 參數（走 Docs MCP）

Responses API 裏 tool 調用相關字段以當前官方文檔爲準，
先用 OpenAI Docs MCP 搜索並 fetch 對應頁面，再給出可運行的最小示例，並附文檔鏈接。

覈對 OpenAPI / 必填字段

創建某個 Responses 請求時，哪些字段是必填？
請用 get_openapi_spec（若可用）對照官方 reference，不要憑記憶編參數名。

模型選型

做一個需要較強多步工具調用的代理任務，按官方 latest-model 指南推薦當前模型，
並說明選型依據來自哪一頁文檔。

模型字符串 / 提示詞升級（窄變更）

把項目裏默認的 OpenAI API 模型遷到官方當前推薦版本，
只改模型默認值與直接相關的提示詞；歷史文檔、評測基線、定價表等不要動。

Codex 自身怎麼配

我想給倉庫加持久約定和 MCP，應該用 AGENTS.md、項目 .codex/config.toml，
還是 Skill/Plugin？請按 openai-docs 的 Codex 手冊路徑回答，並給出依據。

助手側（由 Skill 約束）對文檔類問題的大致流程是：澄清問題類型 → Codex 問題先跑 node <skill-dir>/scripts/fetch-codex-manual.mjs → 其它文檔問題用短查詢（約 2–6 個關鍵詞）搜索並 fetch 精確章節 → 回答時帶簡潔引用。

適用場景與注意事項¶

適合

• 日常集成 OpenAI API（Chat Completions、Responses、Realtime、Agents SDK、Apps SDK 等）時，需要可引用的最新文檔。
• 選型或遷移模型、按官方指引收緊提示詞改動範圍。
• 在 Codex 生態裏問「該寫在 AGENTS.md 還是 config / Skill / Hook」這類產品面問題。
• 團隊希望 AI 助手少幻覺、回答可回溯到官方頁。

注意

1. 只有 Skill 沒有 MCP：助手可能只剩本地 references/ 或官方域網頁回退，時效與覆蓋會打折；官方明確建議兩者一起配。
2. MCP 只讀文檔：不能代替真實 API 調用、計費查詢或賬號權限操作。
3. 升級要保持窄範圍：Skill 要求默認只動活躍的模型默認值與直接相關提示；SDK/IDE/鑑權環境遷移、歷史示例與 eval 基線等，除非用戶明確要求，否則不動。
4. 查不到就停：對未公開的模型 slug、內測開關、私有權益路徑，應按公開文檔回答並標明不確定，而不是擴大搜索麪硬猜。
5. 倉庫狀態：openai/skills 倉庫 README 已提示該示例倉偏向歷史歸檔，新的 Codex plugin/skill 發佈路徑可關注 OpenAI Plugins 與 Codex 文檔；但 curated 目錄下的 openai-docs 與 Docs MCP 官方頁仍互相引用，按當前 SKILL.md 與 Docs MCP 頁配置即可。

小結¶

openai-docs 把「先查官方、再開口」寫成可複用的 Agent 流程，Docs MCP 則把最新文檔變成可調用工具。對寫 OpenAI / Codex 相關代碼的人來說，這相當於給編程助手加了一層權威知識外掛，專門壓制過時記憶和編造參數。

官方入口：

• Skill：https://github.com/openai/skills/tree/main/skills/.curated/openai-docs
• Docs MCP：https://developers.openai.com/learn/docs-mcp
• Skills 在 API 中的用法參考：https://developers.openai.com/cookbook/examples/skills_in_api