openai-docs

OpenAI 文档

通过 developers.openai.com MCP 服务，提供权威且最新的 OpenAI 开发者文档指南。“Docs MCP”指 mcp__openaiDeveloperDocs__search_openai_docs 和 mcp__openaiDeveloperDocs__fetch_openai_doc；对于 API 参考、架构、参数或必填字段相关问题，还要在可用时使用 mcp__openaiDeveloperDocs__get_openapi_spec。只有在这些工具不可用或无法提供帮助后，才使用官方域名网页搜索作为后备方案。宽泛的 Codex 问题应先使用手册辅助工具，再使用 Docs MCP。此技能还负责模型选择、API 模型迁移和提示词升级指南。

工作流配置

来源优先级

• 对于 Codex 自身相关知识，使用下文中的 Codex 来源路径；该路径负责决定何时使用手册辅助工具、Docs MCP，或对不确定内容作有限说明。
• 对于非 Codex 的 OpenAI 文档问题，使用 mcp__openaiDeveloperDocs__search_openai_docs 查找最相关的文档页面。
• 对于非 Codex 的 OpenAI 文档问题，在回答前，使用 mcp__openaiDeveloperDocs__fetch_openai_doc 获取相关页面。如果搜索结果杂乱，使用 Docs MCP 进行更精准的搜索；如果已知或找到任何可能相关的官方 OpenAI 文档 URL，应先尝试通过 Docs MCP 获取该 URL，再依赖网页搜索内容。
• 对于 API 参考、架构、参数或必填字段相关问题，在可用时使用 mcp__openaiDeveloperDocs__get_openapi_spec，并结合相关指南或参考页面核实 API 结构。
• 只有在需要浏览或查找没有明确查询词的非 Codex 页面时，才使用 mcp__openaiDeveloperDocs__list_openai_docs。
• 对于模型选择、“最新模型”或默认模型相关问题，先获取 https://developers.openai.com/api/docs/guides/latest-model.md。如果无法获取，则加载 references/latest-model.md。
• 只有在目标为最新、当前或默认模型，或未指定目标时，才运行 node scripts/resolve-latest-model-info.js 来处理模型升级或提示词升级；否则保留明确指定的目标。
• 保留明确的目标要求：如果用户指定了目标模型，例如“迁移到 GPT-5.4”，即使 latest-model.md 指出了更新的模型，也要保留该目标。可将更新的指南作为可选信息提及。
• 如果需要当前的远程指南，应直接获取返回的迁移指南和提示词指南 URL。如果直接获取失败，则使用 MCP／搜索作为后备方案；若仍无法获取，则使用内置的后备参考资料，并说明使用了后备资料。

OpenAI 产品概览

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

Codex 自身知识

有关 Codex 本身的问题，请使用此路径，包括配置、扩展、操作、故障排除、本地状态、产品界面，或 Codex 行为应归属何处。仅仅是代码库提到了插件、技能、钩子、MCP 服务、浏览器或自动化，并不足以适用此路径。对于通用软件任务，直接完成该软件任务；如果用户询问是否适用 Codex 自身知识，请简要回答这个元问题，然后继续完成所请求的内容。

来源路径

Codex 手册是综合了解 Codex 的首要来源。请将手册和 Docs MCP 视为不同的来源路径，而不是可以互换的官方文档来源。对于面向已发布用户的 Codex 产品问题，来源路径完整，包括手册、本路径要求时使用的 Docs 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 <cache-dir>。在 Windows 上，辅助工具会自动检查 %TEMP% 和 %TMP%；在 PowerShell 中，$env:TEMP\\openai-docs-cache 是常见的显式覆盖路径。

只有明确的只读／无 Shell 策略或实际命令结果，才能证明辅助工具不可用。仅凭猜测沙箱限制或猜测辅助工具失败，不足以改用 Docs MCP 或网页查询；辅助工具命令实际失败后，请继续使用以下范围最窄的官方来源。

辅助工具会验证内容是否为最新版本，写入 codex-manual.md，并生成 codex-manual.outline.md。大纲会将源页面和标题对应到行范围；请用它选择相关手册章节，然后阅读或搜索针对性的手册章节，以查找 Codex 产品事实。使用技能目录定位并运行辅助工具；辅助工具成功后，请使用其返回的手册和大纲路径作为搜索范围，查找 Codex 产品事实并检查术语覆盖情况。

后续的 Codex 问题请重复使用同一会话中的手册和大纲路径。如果手册获取时间超过约一天、路径不可用、路径来自其他会话或来源不确定，或者缺少可能已过时的现行信息，请先刷新。

如果问题是询问手册目前是否足够新、可以作为依据，请在允许使用临时缓存时运行辅助工具，并根据其返回的状态、手册路径和大纲路径作答。

如果手册解决了某项 Codex 声明，请依据手册作答，并停止为该声明扩展来源；如果文档查询只是用户更广泛任务中的一个依赖项，则继续完成该任务。对于手册涵盖的内容，手册源页面和已知锚点足以作为引文依据。

如果因会话为只读、无法执行 Shell 或没有获准使用的临时缓存而跳过辅助工具，下一来源是 Docs MCP：先调用 mcp__openaiDeveloperDocs__search_openai_docs，再对相关结果调用 mcp__openaiDeveloperDocs__fetch_openai_doc，然后才能使用网页备用来源。 如果用户提到某个术语或模式，而最新手册中没有使用该说法，请在手册中搜索明显相关的概念，然后说明手册未记录该确切术语，并使用最接近的已记录术语作答。如果提示词询问该术语如何对应 Codex 的行为，请根据手册中相关章节确定对应关系。如果查阅手册后该确切术语仍然重要或可能是最新信息，请使用一次范围明确的 Docs MCP 搜索/抓取，然后再给出有限度的不确定说明；否则，关于该术语或对应关系的来源查证到此为止。

仅当手册不可用、辅助工具失败、不允许临时缓存、缺少其他重要声明或相关信息可能已过时，或者用户明确需要针对具体页面的引文时，才使用范围最窄的官方后续来源。优先进行一次针对特定内容的 Docs MCP 搜索；如果返回的页面明显相关，再抓取一次。对于尚未解决的 Codex 功能名称、缩写、调度术语或确切错误文本，下一步应先使用 Docs MCP，然后再进行网页搜索。完成手册查阅以及任何获准的 Docs MCP 补充查证后，对仍未解决的问题给出有限度的不确定说明。只有在这条 Docs MCP 查证路径不可用或没有帮助时，才回退到官方域名网页。如果声明仍未得到证实，就停止查证并给出有限度的不确定说明。如果官方文档/手册与当前会话中已显示、可调用的功能相冲突，请说明这种冲突，并以当前环境中已验证的行为为准。

对于未记录或看起来像私有信息的模型代号、产品模式标签、权益标签、账户访问途径或发布阶段名称，应依据当前公开文档和有限度的不确定说明作答。这些标签并不构成偏离公开来源查证路径的理由。

对于支持类诊断，优先依据手册按层次作答，而不是查询特定提供商的网页：已安装/已启用的插件、捆绑应用或连接器授权、MCP 设置、工作区/管理员策略、重启或新建会话的要求；如果问题仍未解决，再联系支持团队或提交反馈。

如果来源查证仍无法证实某项声明，应给出有限度的不确定说明，或建议联系支持团队、管理员或产品反馈渠道，而不是扩大查证范围。

对于尚未解决的产品术语，应依据手册及获准使用的官方后续来源作答。如果这些来源无法确认该术语，应基于这些来源给出有限度的不确定说明。

使用场景对照

当 Codex 的名词或持久化指令载体的适用范围重叠时，推荐与其范围最匹配的最小载体：

• 提示词或线程上下文 -> 一次性任务约束。
• AGENTS.md -> 持久化的仓库约定、命令、验证步骤和审查预期；更靠近目标的嵌套文件适用于其子树。
• 项目 .codex/config.toml -> 受信任仓库的 Codex 设置，例如沙箱、MCP、钩子、模型或推理默认值。
• 全局配置或全局指导 -> 适用于多个仓库的个人默认设置。
• 技能 -> 带有参考资料或脚本的可复用任务工作流。
• 插件 -> 可安装的捆绑包，包含技能以及命令、工具、MCP 配置、钩子、资源、应用或市场元数据。
• MCP 服务或应用连接器 -> 实时外部数据/操作，或经授权的私有应用/工作区数据。对于私有 Google Docs、Calendar、Slack、GitHub、Notion 等数据，应使用连接器，而不是网络搜索或模型记忆。
• 自动化 -> 定时检查、提醒、监控或后续工作；如果需要在现有线程中保持连续性，请使用线程心跳。
• 钩子 -> 对工具调用、命令或文件编辑进行生命周期管控。

应拆分适用范围混杂的请求，而不是强行给出单一答案。例如：“始终执行 X，但仅限于此 PR”默认应将提示词/线程上下文用于本次运行；只有在需要持久生效时，才使用 AGENTS.md 或项目配置；仅在需要机械式管控时使用钩子；仅在需要定时或后续工作时使用自动化。

需要时，可参考以下快速产品对照：CLI 用于以终端为先的本地仓库工作；IDE 扩展用于在编辑器中编写代码；Codex 应用用于桌面端规划、审查和交互式工作；云端/网页用于托管的并行/卸载工作；Browser Use/应用内浏览器用于由 Codex 控制的网页测试；Chrome 扩展使用用户的 Chrome 配置文件；Computer Use 用于控制桌面应用和操作系统界面。请将 config.toml 默认值、requirements.toml 约束和托管/管理员策略分开处理。

边界与输出

• API 密钥身份验证并不意味着可访问 ChatGPT、云端任务或连接器。对于插件/应用/身份验证故障，在作答前检查捆绑包是否可用、插件是否已安装/启用、连接器/应用是否已授权、MCP 设置、重启/刷新要求、工作区策略以及各载体的可用性。
• 沙箱或网络访问被拒绝时，需要在明确说明理由的前提下申请范围有限的权限提升。破坏性命令、工作区外的写入或大范围访问权限变更，都需要明确批准。
• 记忆可以提供用户偏好或上下文，但明确的提示词指令优先；记忆也不能作为当前外部事实的来源。
• 对于肯定的载体选择类回答，请采用以下结构：建议、理由、应避免的做法，以及所用的手册/来源证据。
• 确实需要引用特定 Codex 页面时，以下锚点通常适用：concepts/customization#agents-guidance 对应 AGENTS.md，concepts/customization#skills 对应技能，plugins/build#plugin-structure 对应插件，concepts/customization#mcp 对应 MCP，config-advanced#hooks 对应钩子，app/automations#thread-automations 对应线程自动化，config-reference#configtoml 对应配置。

如果缺少 MCP 服务

如果 MCP 工具不可用，或没有可用的 OpenAI 文档资源：

1. 自行运行安装命令：codex mcp add openaiDeveloperDocs --url https://developers.openai.com/mcp
2. 如果因权限/沙箱限制失败，立即在提升权限后重试同一命令，并附上一句申请批准的理由。
3. 只有在提升权限后的尝试也失败时，才请用户运行安装命令。
4. 请用户重启 Codex。
5. 重启后重新运行文档搜索/获取操作。

工作流

1. 确认请求是查询常规文档、选择模型、升级模型字符串、获取提示词升级指导，还是更广泛的 API／提供方迁移。
2. 对于 Codex 自身知识相关请求，遵循上文的 Codex 自身知识来源流程。
3. 对于模型选择或升级请求，如果用户询问最新／当前／默认指导，优先查阅最新的远程文档，而非捆绑参考资料。
   • 获取 https://developers.openai.com/api/docs/guides/latest-model.md。
   • 查找最新模型 ID，以及明确的迁移或提示词指导链接。
   • 优先使用最新模型页面中的明确链接，而非推导出的 URL。
   • 对于明确指定模型的请求，保留用户要求的模型目标。仅将更新的远程指导作为可选信息提及。
   • 对于动态的最新／当前／默认模型升级，运行 node scripts/resolve-latest-model-info.js，然后尽可能直接获取返回的两个指南 URL。
   • 如果无法直接获取指南，请使用开发者文档 MCP 工具，或通过官方 OpenAI 域名搜索找到相同的指南内容。
   • 如果无法访问远程文档，请使用捆绑的备用参考资料，并说明使用了备用指导。
4. 对于模型升级，保持改动范围狭窄：仅在安全的情况下更新当前使用的 OpenAI API 模型默认值及直接相关的提示词。
5. 除非用户明确要求升级，否则不要改动历史文档、示例、评估基线、测试夹具、提供方比较、提供方注册表、定价表、别名默认值、低成本备用路径以及含义不明确的旧模型用法。
6. 除非用户明确要求，否则不要在模型和提示词升级中涉及 SDK、工具链、IDE、插件、Shell、身份验证及提供方环境的迁移。
7. 如果升级需要更改 API 表面、重新连接架构、修改工具处理程序，或涉及超出直接替换模型字符串和编辑提示词的实现工作，则报告为受阻或需要确认。
8. 对于常规文档查询，使用简洁、类似标题且包含 2–6 个核心词的搜索查询。不要把完整用户问题转换成关键词列表。获取最相关页面和所需的准确章节，并附上简洁引用作答。

参考资料索引

只阅读所需内容：

• https://developers.openai.com/api/docs/guides/latest-model.md -> 当前模型选择以及“最佳／最新／当前模型”相关问题。
• scripts/fetch-codex-manual.mjs -> 获取当前 Codex 手册、验证内容、本地临时缓存及生成大纲。
• https://developers.openai.com/codex/codex-manual.md -> 当前 Codex 自身知识综合内容，包括设置、自定义、技能、插件、MCP、钩子、AGENTS.md、自动化及界面行为；通常应通过辅助程序路径访问，并在临时缓存可用时按需读取文件。
• references/latest-model.md -> 模型选择及“最佳／最新／当前模型”问题的捆绑备用资料。
• references/upgrade-guide.md -> 模型升级及升级规划请求的捆绑备用资料。
• references/prompting-guide.md -> 提示词改写及提示词行为升级的捆绑备用资料。

质量规则

• 以 OpenAI 文档为准；避免推测。
• 对于 Codex 自身知识请求，遵循上述来源路径，不要依赖记忆中的行为。
• 保持迁移改动范围狭窄，并尽量不改变行为。
• 尽可能优先只升级提示词。
• 避免臆造定价、可用性、参数、API 变更或破坏性变更。
• 引用应简短且符合政策限制；优先转述并附上引用。
• 如果多个页面内容不同，应指出差异并引用两个页面。
• 如果官方文档与经验证的当前会话可调用行为不一致，应先说明冲突，再作出宽泛声明或编辑。
• 如果文档未涵盖用户需求，应说明情况并提供后续步骤。

工具使用说明

• 对于 OpenAI 相关的 Markdown 文档，请先使用 MCP 文档工具，再进行网页搜索。Codex 手册流程除外：进行广泛的 Codex 综合时，请遵循 Codex 自我知识来源流程。
• 如果已安装 MCP 服务，但未返回有意义的结果，则使用网页搜索作为备用方案。
• 改用网页搜索时，仅限搜索 OpenAI 官方域名（developers.openai.com、platform.openai.com），并引用来源。