grahama1970/openai-docs

OpenAI 文档

使用 developers.openai.com MCP 服务器提供来自 OpenAI 开发者文档的权威、最新指导。“文档 MCP”指的是 mcp__openaiDeveloperDocs__search_openai_docs 和 mcp__openaiDeveloperDocs__fetch_openai_doc；对于 API 参考、模式、参数或必填字段的问题，在可用时也使用 mcp__openaiDeveloperDocs__get_openapi_spec。官方域名的网页搜索是这些工具不可用或无效时的回退方案。广泛的 Codex 问题在文档 MCP 之前使用手册助手。此技能还负责模型选择、API 模型迁移和提示升级指导。

API 密钥设置

对于构建、运行、配置、调试或实现 API 支持的应用、脚本、CLI、生成器或工具的请求，在可用时首先使用 openai-platform-api-key。在该凭据门控解决后，根据需要返回此处获取最新文档。

直接使用此技能处理纯文档问题、引用、模型/API 指导、概念性解释以及不需要构建或运行 API 支持工件的示例。

对于最新/当前/默认/未指定模型的迁移或提示指导请求，在 API 密钥凭据门控之前，先完成只读的最新模型解析器和指南获取。凭据门控仍然阻止编辑、测试和 API 支持的实现，直到解决为止；它不阻止只读获取当前模型、迁移或提示指导。

最新模型变更的首要操作

在读取内存、检查仓库、获取文档或检查 API 凭据之前，对请求进行分类：

• 最新/当前提示指导，或请求的变更 + 最新/当前/最新/推荐/默认/旗舰/未指定目标： 立即使用下面的平台特定命令运行解析器，并检查其 JSON 输出。这包括询问如何提示最新模型、更改提示、模型选择器、模型引用、SDK 集成、用“当前模型”替换旧的命名模型，或询问“我应该迁移/升级到哪个模型？”。不要直接为此分支获取 latest-model.md。
• 纯模型选择问题，不涉及提示指导或请求的变更： 直接获取 https://developers.openai.com/api/docs/guides/latest-model.md；不要运行解析器。
• 请求的变更 + 明确的目标模型： 保留该目标；不要运行最新模型解析器。对于明确的 GPT-5.6 Sol 或 GPT-5.6 系列迁移，获取实时的 GPT-5.6 模型指导页面，并读取 references/upgrading-to-gpt-5p6-sol.md 以获取特定技能迁移判断。
• 针对明确命名的 GPT-5 系列模型的提示或迁移指导： 通过文档 MCP 获取 https://developers.openai.com/api/docs/guides/model-guidance?model=<请求的模型>，并提取相关的迁移部分或从 ## 提示最佳实践 部分到下一个二级标题的内容。不要用最新模型指导替代。

运行解析器时，不依赖文件系统的可执行位：

• POSIX shell：sh <skill-dir>/scripts/resolve-latest-model-info
• Windows：使用 Node.js 18 或更新版本运行 CommonJS 实现：node <skill-dir>\scripts\resolve-latest-model-info.cjs。如果 node 不可用或版本过旧，并且 load_workspace_dependencies 可用，则使用它返回的 Node.js 可执行文件来运行此命令。不要在 Windows 上直接尝试执行无扩展名的 POSIX 包装器。

对于解析器分支，不要抑制或重定向其标准输出。成功需要包含 model、migrationGuideUrl 和 promptingGuideUrl 的 JSON；如果命令退出时缺少这三个字段中的任何一个，则在回退之前再运行一次。

源优先级

• 对于 Codex 自知识，使用下面的 Codex 源路径；它决定何时使用手册助手、文档 MCP 或有界不确定性。
• 对于非 Codex 的 OpenAI 文档问题，使用 mcp__openaiDeveloperDocs__search_openai_docs 查找最相关的文档页面。
• 对于非 Codex 的 OpenAI 文档问题，在回答前使用 mcp__openaiDeveloperDocs__fetch_openai_doc 获取相关页面。如果搜索噪音大，运行更窄的文档 MCP 搜索；当任何看似合理的官方 OpenAI 文档 URL 已知或找到时，在依赖网页搜索内容之前，尝试通过文档 MCP 获取该 URL。
• 对于 API 参考、模式、参数或必填字段的问题，在可用时使用 mcp__openaiDeveloperDocs__get_openapi_spec 来验证 API 形状，同时参考相关指南或参考页面。
• 仅在需要浏览或发现非 Codex 页面但没有明确查询时，才使用 mcp__openaiDeveloperDocs__list_openai_docs。
• 对于最新/当前的提示指导、模型升级或提示升级，应用上述的首要操作分类器，并使用其平台特定的解析器命令。在 POSIX 上，包装器使用来自 $NODE、PATH 或捆绑/系统回退的兼容 Node.js 18+ 运行时。在 Windows 上，使用兼容的 Node.js 可执行文件直接运行 .cjs 实现。如果没有可用的兼容运行时，则在可用时调用 load_workspace_dependencies，并使用返回的 Node.js 可执行文件重试一次相应的命令。
• 对于纯文档类型的模型选择问题（不要求更改应用、项目、仓库、模型配置或提示），首先获取 https://developers.openai.com/api/docs/guides/latest-model.md。如果该页面不可用，则加载 references/latest-model.md。
• 保留明确的目标请求：如果用户命名了目标模型，例如“迁移到 GPT-5.4”，即使 latest-model.md 命名了更新的模型，也要保留该请求的目标。仅将更新版本的指导作为可选项提及。
• 如果需要当前的远程指导，则将返回的迁移和提示指导 URL 视为不透明的，并直接获取这些确切的 URL。不要派生、替换或向其附加模型查询。如果提示指导 URL 解析为组合的模型指导页面，则仅提取从 ## 提示最佳实践 部分到下一个二级标题的内容。如果获取的指南仅包含标题或没有实质性内容，则通过 MCP/搜索回退重试确切的 Markdown URL；如果仍然失败，则使用捆绑的回退引用并披露回退。

OpenAI 产品快照

1. Apps SDK：通过提供 Web 组件 UI 和一个向 ChatGPT 公开应用工具的 MCP 服务器来构建 ChatGPT 应用。
2. Responses API：一个统一的端点，专为在 agentic 工作流中进行有状态、多模态、工具使用的交互而设计。
3. Chat Completions API：从构成对话的消息列表中生成模型响应。
4. Codex：OpenAI 的软件开发编码代理，能够编写、理解、审查和调试代码。
5. gpt-oss：在 Apache 2.0 许可证下发布的开源权重 OpenAI 推理模型（gpt-oss-120b 和 gpt-oss-20b）。
6. Realtime API：构建低延迟、多模态的体验，包括自然的语音到语音对话。
7. Agents SDK：一个用于构建 agentic 应用的工具包，其中模型可以使用工具和上下文，将任务移交给其他代理，流式传输部分结果，并保留完整的追踪。

Codex 自知识

使用此路径处理关于 Codex 本身的问题：配置、扩展、操作、故障排除、本地状态、产品界面或 Codex 行为应归属的位置。仅仅一个代码库提到了插件、技能、钩子、MCP 服务器、浏览器或自动化是不够的。对于通用软件任务，直接回答软件任务；如果被问及 Codex 自知识是否适用，简要回答这个元问题，然后继续请求的工件。

源路径

Codex 手册是广泛 Codex 综合信息的首要来源。将手册和文档 MCP 视为不同的车道，而不是可互换的官方文档来源。对于已发布的用户 Codex 产品答案，源路径是完整的：手册、当此路径需要时的文档 MCP、官方 OpenAI 网页回退，以及在当前会话中暴露的可调用能力（当问题涉及该能力时）。developers.openai.com 之外的知识库不在该路径的公共产品答案范围内。

对于广泛的 Codex 行为、设置、自定义、技能、插件、MCP、钩子、AGENTS.md、自动化、界面、本地状态或系统地图问题：

1. 当同一线程的手册和概要路径仍然新鲜时，重用它们。
2. 否则，在正常的可写会话中首先运行技能本地辅助脚本。仅在会话明确为只读、shell 执行不可用或可见策略未允许临时缓存时，才跳过而不尝试。
3. 默认情况下，辅助脚本按此顺序选择第一个可用的临时缓存目录：$TMPDIR/openai-docs-cache、%TEMP%\openai-docs-cache、%TMP%\openai-docs-cache、/private/tmp/openai-docs-cache，然后 /tmp/openai-docs-cache。仅为工作区的写入权限不足以为此临时缓存提供支持。
4. 直接运行辅助脚本，除非需要覆盖缓存目录。当原生 fetch 不可用或存在代理环境变量时，辅助脚本回退到 curl，因此不需要特定 shell 的代理前缀。将 <skill-dir> 解析为此技能的实际目录；在复制的本地评估工作目录中，这通常是 .codex/skills/openai-docs：

node <skill-dir>/scripts/fetch-codex-manual.mjs

如果需要覆盖缓存目录，则传递 --cache-dir <缓存目录>。在 Windows 上，辅助脚本会自动检查 %TEMP% 和 %TMP%；在 PowerShell 中，$env:TEMP\openai-docs-cache 是典型的显式覆盖路径。

将辅助脚本的可用性视为由明确的只读/无 shell 策略或实际的命令结果确立。猜测的沙箱或猜测的辅助脚本失败不足以切换到文档 MCP 或网页查找；在实际的辅助脚本命令失败后，继续到下面最窄的官方下一个源。

辅助脚本验证新鲜度，写入 codex-manual.md，并生成 codex-manual.outline.md。概要地图将源页面和标题映射到行范围；使用它来选择相关的手册部分，然后读取或搜索目标手册部分以获取 Codex 产品事实。使用技能目录来定位和运行辅助脚本；在辅助脚本成功后，使用返回的手册和概要路径作为搜索范围，用于 Codex 产品事实和术语覆盖检查。

为后续的 Codex 问题重用同一线程的手册和概要路径。当手册超过大约一天前获取、路径不可用、路径来自其他线程或不确定来源、或者缺少可能最新的信息且过时是合理的时，请先刷新。

对于手册现在是否足够新以至于可以依赖的问题，在允许临时缓存时运行辅助脚本，并根据其返回的状态、手册路径和概要路径来回答。

如果手册解决了一个 Codex 声明，则从中回答，并停止为该声明扩展来源；如果文档查找只是其中一个依赖项，则继续用户的更广泛任务。手册源页面和已知锚点足以支持手册涵盖的材料。

如果辅助脚本因会话是只读的、没有 shell 执行或没有允许的临时缓存而被跳过，则下一个源是文档 MCP：调用 mcp__openaiDeveloperDocs__search_openai_docs，然后在任何网页回退之前调用 mcp__openaiDeveloperDocs__fetch_openai_doc 获取相关命中结果。

如果用户命名了一个新的手册未使用的 Codex 术语或模式，则搜索手册中明显的相邻概念，然后回答该确切术语没有文档记录，并使用最近的文档化术语。如果提示询问该术语如何映射到 Codex 行为，则从相邻的手册部分解析映射。如果在手册遍之后，该确切术语仍然是实质性的或可能是最新的，则在有界不确定性之前进行一次窄的文档 MCP 搜索/获取；否则，该术语或映射声明的源查找就完成了。

仅当手册不可用、辅助脚本失败、临时缓存不被允许、其他实质性声明缺失或可能过时、或者用户明确需要特定页面的引用时，才使用最窄的官方下一个源。首选一次特定的文档 MCP 搜索，如果它返回一个明显相关的页面，则进行一次获取；对于未解决的 Codex 能力名称、首字母缩略词、调度术语或确切的错误文本，此文档 MCP 步骤是网页搜索之前的下一源。在手册加上任何允许的文档 MCP 补缺之后，将剩余空白解决为有界不确定性。仅在该文档 MCP 路径不可用或无效之后，使用官方域名网页回退。如果声明仍未建立，则停止并带有有界不确定性。如果官方文档/手册与已在当前会话中暴露的可调用能力冲突，则声明冲突，并倾向于针对该环境的已验证的当前会话行为。

对于未记录或看似私有的模型标识符、产品模式标签、权利标签、账户访问路径或版本名称，请根据当前的公共文档和有界不确定性来回答。这些标签不是离开公共源路径的理由。

对于支持风格的诊断，首选基于手册的逐层回答，而非特定提供商的网页查找：已安装/启用的插件、捆绑的应用或连接器授权、MCP 设置、工作区/管理员策略、重启或新线程的期望，然后如果仍未解决，则支持或反馈。

如果源路径仍未能确立一个声明，则返回有界不确定性，或将其路由到支持、管理员或产品反馈，而不是扩大调查范围。

对于未解决的产品术语，根据手册和允许的官方下一个源来回答。如果这些源未确立该术语，则根据这些源以有界不确定性回答。

界面地图

当 Codex 名词或持久指令界面重叠时，推荐与范围匹配的最小界面：

• 提示或线程上下文 -> 一次性任务约束。
• AGENTS.md -> 持久的仓库约定、命令、验证步骤和审查期望；更接近的嵌套文件在其子树下应用。
• 项目的 .codex/config.toml ->

…

[为翻译而截断]