前言¶

用 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