如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题
Codex

Codex 使用场景

将您的应用接入 ChatGPT

针对具体使用场景,构建专注于特定任务的 ChatGPT 应用。

难度 Advanced
时间跨度 1h

围绕用户要完成的一项具体任务,构建一个 ChatGPT 应用。先定义工具,为 MCP 服务器和可选的小组件搭建骨架,再将应用接入 ChatGPT,反复测试和调整,直到核心流程跑通。

最适合

  • 围绕用户要完成的一项任务,规划您的首个 ChatGPT 应用
  • 搭建 MCP 服务器骨架,定义工具元数据,按需添加小组件,避免过度设计
  • 从本地 HTTPS 测试到在 ChatGPT 中验证自定义 MCP 服务器,快速迭代

目录

    ← 所有使用场景

    将您的应用接入 ChatGPT

    针对具体使用场景,构建专注于特定任务的 ChatGPT 应用。

    围绕用户要完成的一项具体任务,构建一个 ChatGPT 应用。先定义工具,为 MCP 服务器和可选的小组件搭建骨架,再将应用接入 ChatGPT,反复测试和调整,直到核心流程跑通。

    Advanced
    1h

    围绕用户要完成的一项具体任务,构建一个 ChatGPT 应用。先定义工具,为 MCP 服务器和可选的小组件搭建骨架,再将应用接入 ChatGPT,反复测试和调整,直到核心流程跑通。

    Advanced
    1h

    最适合

    • 围绕用户要完成的一项任务,规划您的首个 ChatGPT 应用
    • 搭建 MCP 服务器骨架,定义工具元数据,按需添加小组件,避免过度设计
    • 从本地 HTTPS 测试到在 ChatGPT 中验证自定义 MCP 服务器,快速迭代

    技能与插件

    • 按照当前的 ChatGPT 应用开发流程规划工具、接入 MCP 资源。
    • 在 Codex 编写代码或提出架构建议之前,获取最新的 Apps SDK 官方指南。
    • 通过精选技能和 Vercel 官方 MCP 服务器,在 Codex 中使用 Vercel 生态系统的开发指南。
    技能 使用理由
    ChatGPT Apps 按照当前的 ChatGPT 应用开发流程规划工具、接入 MCP 资源。
    OpenAI Docs 在 Codex 编写代码或提出架构建议之前,获取最新的 Apps SDK 官方指南。
    Vercel 通过精选技能和 Vercel 官方 MCP 服务器,在 Codex 中使用 Vercel 生态系统的开发指南。

    起始提示词

    结合使用 $chatgpt-apps 和 $openai-docs,在此代码仓库中为 [use case] 规划一个 ChatGPT 应用。 要求: - 先明确用户要完成的一项核心任务。 - 提出 3 至 5 个工具,为每个工具起一个清晰的名称,并说明其用途、输入和输出。 - 评估首个版本是否需要小组件,或能否先只提供数据,并给出建议。 - MCP 服务器优先使用 TypeScript,小组件优先使用 React。 - 明确身份验证、部署和测试要求。 输出: - 工具设计方案 - 建议的文件树 - 一组用于验证预期行为的基准提示词 - 风险和待解决的问题
    结合使用 $chatgpt-apps 和 $openai-docs,在此代码仓库中为 [use case] 规划一个 ChatGPT 应用。 要求: - 先明确用户要完成的一项核心任务。 - 提出 3 至 5 个工具,为每个工具起一个清晰的名称,并说明其用途、输入和输出。 - 评估首个版本是否需要小组件,或能否先只提供数据,并给出建议。 - MCP 服务器优先使用 TypeScript,小组件优先使用 React。 - 明确身份验证、部署和测试要求。 输出: - 工具设计方案 - 建议的文件树 - 一组用于验证预期行为的基准提示词 - 风险和待解决的问题

    您将构建什么

    每个基于 MCP 的插件都包含三个部分:

    • MCP 服务器负责定义工具、返回数据、执行访问控制,并告知 ChatGPT 从哪里加载所需的界面资源。
    • 可选的 Web 组件,在 ChatGPT 的 iframe 中渲染。您可以使用 React,也可以直接使用 HTML、CSS 和 JavaScript 来构建它。
    • 模型根据您提供的元数据,决定何时调用插件的工具。

    开发这些部分时,最适合交给 Codex 的是重复性的工程工作:

    • 规划要提供的工具及其元数据。
    • 搭建服务器和小组件的初始框架。
    • 配置本地运行脚本。
    • 分阶段添加身份验证功能和调整部署配置,每次专注于一项改动。
    • 编写可重复执行的验证流程,确认插件能在 ChatGPT 中正常工作。

    为什么适合使用 Codex

    • 基于 MCP 的插件可以清晰地划分为服务器、可选界面和由模型驱动的工具调用三个部分。
    • 当提示词明确说明任务、限定范围,且结果易于验证时,Codex 的表现最好。插件开发正符合这些条件。
    • 技能和 AGENTS.md 为 Codex 提供可复用的指令和项目规则,使其在开发过程中有据可依。

    有关如何安装和使用技能,请参阅技能文档。

    使用方法

    准备工作

    • 先确定用户最需要完成的一件事,避免一开始就尝试将整个产品迁移到聊天界面。
    • 提前选定技术栈:服务器使用 TypeScript 或 Python,小组件使用 React,或直接使用 HTML、CSS 和 JavaScript。
    • 确定开发期间如何通过 HTTPS 访问服务器,例如使用 ngrok 或 Cloudflare Tunnel。
    • 部分设置仍使用旧称来指代 MCP 服务器连接。本地测试时,这些标签指的都是已注册的服务器。
    1. 先为插件设定一个范围明确的目标,请 Codex 提出三到五个工具,并清楚列出各工具的名称、描述、输入和输出。
    2. 确定首版是否只需返回数据,还是需要小组件。添加依赖项之前,先沿用代码仓库的现有模式,搭建 MCP 服务器和可选小组件的初始框架。
    3. 在本地运行 MCP 服务器,使其可通过 HTTPS 访问。在 ChatGPT 中通过添加自定义 MCP 服务器连接服务器,然后用一小组提示词进行测试,覆盖直接请求、间接请求和不应调用工具的情形。
    4. 反复调整元数据、状态处理逻辑以及 structuredContent 和 _meta 载荷,直到核心读取流程能在 ChatGPT 中稳定运行。
    5. 仅在访问用户专属数据或执行写入操作需要授权时添加 OAuth 2.1,避免让匿名或只读流程变得复杂。
    6. 准备一个提供稳定 /mcp 端点的托管预览环境,验证流式响应和界面资源托管是否正常,并在分享或提交插件前逐项核对上线清单。

    推荐提示词

    适合这一工作流程的提示词通常包含以下要素:

    • 明确的目标:说明插件应帮助用户在 ChatGPT 中完成什么。
    • 具体的技术栈:说明您希望服务器使用 TypeScript 还是 Python,以及小组件应使用 React 还是采用轻量实现。
    • 清晰的工具职责:请 Codex 规划或构建少量工具,每个工具只负责一项任务。
    • 身份验证要求:说明首版是否支持匿名使用,还是需要关联账户并执行写入操作。
    • 本地开发方式:说明在 ChatGPT 中通过 HTTPS 测试时,您打算使用哪种隧道或托管方案。
    • 验证步骤:告诉 Codex 要运行哪些命令、测试哪些提示词,以及需要提供哪些结果供您核验。

    避免用一条提示词要求 Codex 一次完成规划、实现、身份验证、部署、提交和完善工作。请将工作拆分为更小的阶段。

    先规划插件,再搭建框架

    结合使用 $chatgpt-apps 和 $openai-docs,在此代码仓库中为 [use case] 规划一个基于 MCP 的插件。 要求: - 先确定用户要完成的一项核心任务。 - 提出 3 至 5 个工具,清楚列出各工具的名称、描述、输入和输出。 - 就首版是否需要小组件给出建议,并说明能否先只返回数据。 - MCP 服务器优先使用 TypeScript,小组件优先使用 React。 - 明确列出身份验证、部署和测试要求。 输出: - 工具设计方案 - 建议的文件目录结构 - 一组基准测试提示词 - 风险和待解决的问题

    搭建首个可运行版本

    结合使用 $chatgpt-apps 和 $openai-docs,搭建这个基于 MCP 的插件的首个版本。 技术栈: - 使用 TypeScript 编写 MCP 服务器 - 使用 React 构建小组件 - 使用 Vite 构建项目 - 通过 ngrok 提供本地 HTTPS 访问 约束: - 限定插件范围:只实现一个读取流程,最多实现一个写入流程。 - 为模型返回精简的 structuredContent,将仅供小组件使用的数据放在 _meta 中。 - 确保工具处理函数具有幂等性。 - 添加依赖项之前,先复用代码仓库的现有模式。 验证: - 启动本地服务器 - 说明如何在 ChatGPT 中通过“添加自定义 MCP 服务器”连接 MCP 服务器 - 逐条列出测试时要输入的提示词

    核心流程运行正常后再添加身份验证

    结合使用 $chatgpt-apps 和 $openai-docs,为此插件的 MCP 服务器添加身份验证。 要求: - 尽可能让只读工具支持匿名访问。 - 仅针对用户专属数据或写入操作添加 OAuth 2.1。 - 使用现有的身份提供商,例如 Auth0 或 Stytch。 - 在文档中说明授权范围、令牌校验方式,以及在 ChatGPT 中测试自定义 MCP 服务器的流程。 输出: - 身份验证流程概述 - 服务器改动 - 所需的环境变量 - 端到端测试计划

    准备部署插件并进行审查

    结合使用 $chatgpt-apps、$openai-docs 和 @vercel,为此插件准备托管预览环境。 要求: - 通过 HTTPS 提供稳定的 /mcp 端点。 - 确保 /mcp 端点仍可正常返回流式响应。 - 正确托管小组件资源。 - 添加上线检查清单,涵盖元数据、工具使用提示、隐私和测试提示词。 输出: - 部署计划 - 预览 URL 或托管步骤 - 审查清单 - 尚存的风险

    上线前检查

    • 插件只解决一个具体问题,用户能理解它的用途。
    • 工具数量少,每个工具的元数据、输入和输出都有明确定义。
    • MCP 服务器在端到端流程中运行正常,返回精简的 structuredContent,并将仅供小组件使用的数据放在 _meta 中。
    • 如果需要小组件,它能在 ChatGPT 中正确渲染。
    • 在 ChatGPT 中连接自定义 MCP 服务器后,可以通过 HTTPS 反复进行本地测试。
    • 用一小组提示词测试直接请求、间接请求和不应调用工具的情形,所有测试均通过,对话流程和工具载荷符合预期。
    • 仅在访问用户专属数据或执行写入操作需要验证身份的环节添加身份验证。
    • 在分享或提交插件前,部署计划和上线审查均已涵盖元数据、工具使用提示、隐私和测试提示词。

    常见误区

    • 要求 Codex 将整个产品迁移到 ChatGPT。更好的做法是聚焦用户的一项核心任务,请 Codex 设计三到五个工具和一个功能单一的小组件。
    • 一开始就用一条提示词要求实现全部功能。请将工作分为规划、搭建框架、添加身份验证、部署和审查几个阶段。
    • 工具接口约定尚不明确就开始编写界面。请先规划要提供的工具和响应模式,再构建小组件。
    • 开发时未以官方文档为依据。请结合使用 $chatgpt-apps 和 $openai-docs,按照最新的插件开发指南搭建框架,让官方指导落实到代码中。
    • 把元数据留到最后才处理。请尽早编写工具描述和参数文档,然后用同一组提示词重新测试,检验这些说明是否有效。
    • 尚未验证匿名或只读流程就添加身份验证。请先确保核心工具流程正常运行,再为确实需要授权的工具添加 OAuth。
    • 还没在 ChatGPT 中测试就认定插件已完成。请在 ChatGPT 中连接自定义 MCP 服务器,检查工具载荷,并验证实际的对话流程。

    技术栈

    需求

    小组件框架

    默认选项

    React

    为什么需要

    构建需要管理状态的小组件时,可优先选用 React,尤其是当界面需要筛选控件、表格或多步交互时。

    需求

    托管服务

    默认选项

    Vercel

    为什么需要

    Vercel 支持快速部署,提供预览环境,自动启用 HTTPS,也方便您部署和托管 MCP 端点。

    需求 默认选项 为什么需要
    小组件框架 React 构建需要管理状态的小组件时,可优先选用 React,尤其是当界面需要筛选控件、表格或多步交互时。
    托管服务 Vercel Vercel 支持快速部署,提供预览环境,自动启用 HTTPS,也方便您部署和托管 MCP 端点。

    相关使用场景