--- name: "openai-docs" description: "当用户询问如何使用 OpenAI 产品或 API 构建、询问 Codex 本身或如何选择 Codex 界面、需要带有引用的最新官方文档、需要帮助为用例选择最新模型，或需要模型升级和提示升级指导时使用；非 Codex 文档问题使用 OpenAI 文档 MCP 工具，广泛的 Codex 自身知识问题优先使用 Codex 手册助手，回退浏览限制为官方 OpenAI 域。" --- # OpenAI 文档 使用 developers.openai.com MCP 服务器从 OpenAI 开发者文档提供权威、最新的指导。"文档 MCP" 指 `mcp__openaiDeveloperDocs__search_openai_docs` 和 `mcp__openaiDeveloperDocs__fetch_openai_doc`；对于 API 参考、模式（schema）、参数或必填字段问题，在可用时还应使用 `mcp__openaiDeveloperDocs__get_openapi_spec`。官方域名的 Web 搜索仅在上述工具不可用或无帮助之后作为回退。广泛的 Codex 问题在使用文档 MCP 之前先使用手册助手。此技能还负责模型选择、API 模型迁移和提示升级指导。 ## API 密钥设置 对于构建、运行、配置、调试或实现由 API 支持的应用、脚本、CLI、生成器或工具的请求，在可用时优先使用 `openai-platform-api-key`。解决该凭据前置条件后，再按需返回此处查阅当前文档。 对于仅涉及文档查询、引用、模型/API 指导、概念解释，以及不需要构建或运行 API 支撑产出物的示例，直接使用此技能即可。 ## 工作流程配置 ### 来源优先级 - 对于 Codex 自身知识问题，使用下方的 Codex 来源路径；它决定何时使用手册助手、文档 MCP，或采用有边界的不确定性表述。 - 对于非 Codex 的 OpenAI 文档问题，使用 `mcp__openaiDeveloperDocs__search_openai_docs` 查找最相关的文档页面。 - 对于非 Codex 的 OpenAI 文档问题，在回答之前使用 `mcp__openaiDeveloperDocs__fetch_openai_doc` 获取相关页面。如果搜索结果嘈杂，运行更精确的文档 MCP 搜索；当已知或找到任何可能相关的官方 OpenAI 文档 URL 时，在依赖 Web 搜索内容之前先尝试通过文档 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`。 - 对于模型升级或提示升级，仅当目标是 latest/current/default 或未指定时才运行 `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：一个统一的端点，专为代理工作流程中的有状态、多模态、工具使用交互而设计。 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：一个用于构建代理应用程序的工具包，模型可以在其中使用工具和上下文、移交给其他代理、流式传输部分结果并保留完整的跟踪。 ## Codex 自身知识 将此路径用于关于 Codex 本身的问题：配置、扩展、操作、故障排查、本地状态、产品界面，或 Codex 行为应该放在哪里。代码库仅仅提到插件、技能、hook、MCP 服务器、浏览器或自动化，并不足以判定为此类问题。对于通用软件任务，直接回答该软件任务；如果被问及是否适用 Codex 自身知识，简要回答该元问题后继续完成所请求的产出物。 ### 来源路径 Codex 手册是广泛 Codex 综合性问题的首选来源。将手册和文档 MCP 视为不同的通道，而非可互换的官方文档来源。对于面向已发布用户的 Codex 产品问题，来源路径是完整的：手册、本路径要求时的文档 MCP、官方 OpenAI Web 回退，以及当前会话中已暴露的可调用能力（当问题涉及该能力时）。developers.openai.com 之外的知识库不在此公开产品问答路径的范围内。 对于广泛的 Codex 行为、设置、自定义、技能、插件、MCP、hook、`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 的代理前缀。将 `` 解析为此技能的实际目录；在复制的本地评估工作目录中，通常是 `.codex/skills/openai-docs`： ```bash node /scripts/fetch-codex-manual.mjs ``` 如果需要覆盖缓存目录，传入 `--cache-dir `。在 Windows 上，助手会自动检查 `%TEMP%` 和 `%TMP%`；在 PowerShell 中，`$env:TEMP\\openai-docs-cache` 是典型的显式覆盖方式。 将助手的可用性视为由明确的只读/无 shell 策略或实际的命令结果所确立。猜测的沙盒限制或猜测的助手失败不足以让你切换到文档 MCP 或 Web 查询；在实际的助手命令失败之后，继续使用下方最窄范围的官方下一来源。 助手会验证新鲜度，写入 `codex-manual.md`，并生成 `codex-manual.outline.md`。大纲将来源页面和标题映射到行范围；使用它来选择相关的手册章节，然后阅读或搜索目标手册章节以获取 Codex 产品事实。使用技能目录来定位并运行助手；助手成功后，将返回的手册和大纲路径用作 Codex 产品事实和术语覆盖检查的搜索范围。 对于后续的 Codex 问题，复用同一线程的手册和大纲路径。当手册的获取时间超过约一天、路径不可用、路径来自其他线程或来源不确定，或很可能当前的信息缺失且陈旧性是合理的时，先刷新。 对于"手册是否足够新以可靠依赖"这类问题，在允许临时缓存时运行助手，并根据其返回的状态、手册路径和大纲路径来作答。 如果手册解决了某个 Codex 相关的主张，就据此作答并停止为该主张扩展来源；如果文档查询只是用户更大任务中的一个依赖项，则继续完成用户更广泛的任务。手册来源页面和已知锚点对手册已覆盖的内容而言是足够的引用支持。 如果因会话为只读、无法执行 shell，或没有允许的临时缓存而跳过了助手，下一来源是文档 MCP：在任何 Web 回退之前，调用 `mcp__openaiDeveloperDocs__search_openai_docs`，然后针对相关结果调用 `mcp__openaiDeveloperDocs__fetch_openai_doc`。 如果用户提到了一个新鲜手册中未使用的 Codex 术语或模式，先在手册中搜索明显相关的概念，然后回答该确切术语未被记录，并使用最接近的已记录术语。如果提示询问该术语如何映射到 Codex 行为，从相邻的手册章节中解析该映射。如果在此手册检索之后，该确切术语仍然重要或可能是当前的，在采用有边界的不确定性表述之前先进行一次精确的文档 MCP 搜索/获取；否则，该术语或映射主张的来源查询就已完成。 仅当手册不可用、助手失败、不允许临时缓存、缺失其他重要主张或很可能陈旧，或用户明确需要特定页面的引用时，才使用最窄范围的官方下一来源。优先进行一次具体的文档 MCP 搜索，如果返回明显相关的页面，再进行一次获取；对于未解决的 Codex 能力名称、缩写、调度术语或确切错误文本，此文档 MCP 步骤是 Web 搜索之前的下一来源。在手册加上任何被允许的文档 MCP 补缺之后，将剩余的空白解析为有边界的不确定性。仅当该文档 MCP 路径不可用或无帮助之后，才使用官方域名的 Web 回退。如果该主张仍未被确立，就以有边界的不确定性结束。如果官方文档/手册与当前会话中已暴露的可调用能力冲突，说明该冲突，并针对该环境优先采用已验证的当前会话行为。 对于未被记录或看起来私有的模型标识、产品模式标签、权限标签、账户访问路径或发布名称，从当前公开文档和有边界的不确定性中作答。这些标签本身不是脱离公开来源路径的理由。 对于支持类诊断问题，优先从手册中逐层作答，而非依赖特定提供商的 Web 查询：已安装/启用的插件、捆绑的应用或连接器授权、MCP 设置、工作区/管理员策略、重启或新线程的预期，若仍未解决则最后转向支持或反馈渠道。 如果来源路径仍未能确立某个主张，返回有边界的不确定性，或转向支持、管理员或产品反馈，而不是扩大调查范围。 对于未解决的产品术语，从手册加上被允许的官方下一来源中作答。如果这些来源未能确立该术语，就基于这些来源以有边界的不确定性作答。 ### 界面映射 当 Codex 名词或持久性指令的载体存在重叠时，推荐与范围最匹配的最小载体： - 提示词或线程上下文 -> 一次性任务约束。 - `AGENTS.md` -> 持久的仓库约定、命令、验证步骤和评审预期；更靠近子目录的嵌套文件在其子树下生效。 - 项目 `.codex/config.toml` -> 受信任仓库的 Codex 设置，例如沙盒、MCP、hook、模型或推理默认值。 - 全局配置或全局指导 -> 跨仓库的个人默认设置。 - 技能 -> 带有引用或脚本的可复用任务工作流。 - 插件 -> 包含技能加命令、工具、MCP 配置、hook、资源、应用或市场元数据的可安装包。 - MCP 服务器或应用连接器 -> 实时外部数据/操作，或已授权的私有应用/工作区数据。对私有的 Google Docs、日历、Slack、GitHub、Notion 等数据使用连接器，而不是 Web 搜索或模型记忆。 - 自动化 -> 定时检查、提醒、监控或后续工作；当需要在现有线程中保持连续性时使用线程心跳。 - Hook -> 围绕工具调用、命令或文件编辑的生命周期强制执行。 拆分混合范围的请求，而不是强行给出一个答案。例如："始终做 X，但仅限本次 PR" 默认对当前运行使用提示词/线程上下文；仅当它应该持久化时才使用 `AGENTS.md` 或项目配置，仅在机械式强制执行时使用 hook，仅在定时或后续工作时使用自动化。 需要时使用这份快速产品地图：CLI 是以终端为先的本地仓库工作；IDE 扩展是编辑器内嵌的编码；Codex 应用是桌面端的规划、评审和交互式工作；云端/Web 是托管的并行/卸载工作；Browser Use/应用内浏览器是 Codex 控制的 Web 测试；Chrome 扩展使用用户的 Chrome 配置文件；Computer Use 控制桌面应用和操作系统 UI。将 `config.toml` 默认值、`requirements.toml` 约束和受管理/管理员策略区分开来。 ### 边界与输出 - API 密钥认证并不意味着拥有 ChatGPT、云任务或连接器访问权限。对于插件/应用/认证失败，在作答之前先检查包的可用性、插件的安装/启用状态、连接器/应用授权、MCP 设置、重启/刷新预期、工作区策略以及各界面的可用性。 - 沙盒或网络拒绝需要有明确理由的范围化升级请求。破坏性命令、工作区外的写入或范围广泛的访问变更需要明确批准。 - 记忆可以提供用户偏好或上下文，但明确的提示指令优先，且记忆不能作为当前外部事实的来源。 - 对于肯定性的界面选择答案，使用这种结构：推荐、原因、应避免的事项，以及所使用的手册/来源证据。 - 当确实需要针对特定页面的 Codex 引用时，以下锚点通常适用：`AGENTS.md` 对应 `concepts/customization#agents-guidance`，技能对应 `concepts/customization#skills`，插件对应 `plugins/build#plugin-structure`，MCP 对应 `concepts/customization#mcp`，hook 对应 `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. 保留历史文档、示例、评估基线、fixture、提供商比较、提供商注册表、定价表、别名默认值、低成本回退路径和模糊的旧模型使用方式，除非用户明确要求升级它们。 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、hook、`AGENTS.md`、自动化和界面行为；通常在允许临时缓存时通过助手路径和目标文件读取来访问。 - `references/latest-model.md` -> 模型选择和"最佳/最新/当前模型"问题的捆绑回退。 - `references/upgrade-guide.md` -> 模型升级和升级规划请求的捆绑回退。 - `references/prompting-guide.md` -> 提示重写和提示行为升级的捆绑回退。 ## 质量规则 - 将 OpenAI 文档视为真实来源；避免推测。 - 对于 Codex 自身知识问题，遵循上面的来源路径，而不是依赖记忆中的行为。 - 保持迁移更改范围狭窄并保留行为。 - 尽可能优先使用仅提示的升级。 - 不要编造定价、可用性、参数、API 更改或破坏性更改。 - 保持引用简短并在政策限制内；更喜欢带有引用的改写。 - 如果多个页面不同，请指出差异并引用两者。 - 如果官方文档和已验证的当前会话可调用行为不一致，在做出广泛的主张或编辑之前说明该冲突。 - 如果文档未涵盖用户的需求，请说明并提供后续步骤。 ## 工具说明 - 对于 OpenAI 相关的 markdown 文档，在 Web 搜索之前使用 MCP 文档工具。Codex 手册流程是例外：对于广泛的 Codex 综合性问题，遵循 Codex 自身知识来源流程。 - 如果 MCP 服务器已安装但没有返回有意义的结果，则使用 Web 搜索作为回退。 - 回退到 Web 搜索时，限制为官方 OpenAI 域（developers.openai.com、platform.openai.com）并引用来源。