前言¶

ChatGPT 里的应用不再只是「对话里塞一段文本」。用 Apps SDK，你可以同时提供 MCP（Model Context Protocol）工具和内嵌 Widget：模型负责调用工具、叙述结果，Widget 在对话里用 iframe 渲染可交互界面。对开发者来说，真正难的往往不是写几行 HTML，而是对齐当前文档里的资源注册、工具元数据、MCP Apps bridge、CSP，以及本地隧道联调这一整套流程。

OpenAI 在官方 Skills 仓库里提供了精选 Skill chatgpt-apps，专门教 Agent 如何按文档优先的方式脚手架、改造和排错这类应用。本文基于该 Skill 的 SKILL.md 与 OpenAI 开发者文档，说明它是什么、能做什么，以及如何安装启用。

这是什么¶

chatgpt-apps 是 OpenAI 维护的 Agent Skill（目录位于 openai/skills 的 skills/.curated/chatgpt-apps）。它面向「ChatGPT Apps SDK 应用」：把 MCP 服务器 和 Widget UI 绑在一起，用于设计工具、注册 UI 资源、接入 MCP Apps bridge 或 ChatGPT 兼容 API、补齐 Apps SDK 元数据 / CSP / 域名配置，并产出与文档一致的项目骨架。

Skill 的定位可以概括成一句话：在写代码之前先拉最新 Apps SDK 文档，再按固定工作流分类应用形态、选上游示例、搭服务器与 Widget，最后按「最小可运行仓库契约」做校验。

它依赖的文档侧能力也写在 agents/openai.yaml 里：默认关联 OpenAI Developer Docs MCP（https://developers.openai.com/mcp），并鼓励与 $openai-docs 一起使用。

核心功能与亮点¶

根据官方 SKILL.md，这个 Skill 会推动 Agent 产出或完成这些事：

应用原型分类：在写代码前先定一个主形态，例如 tool-only、vanilla-widget、react-widget、interactive-decoupled、submission-ready，再据此选示例和校验重点。
工具方案先行：规划工具名、schema、注解（如 readOnlyHint、destructiveHint）与输出；连接器 / 只读类场景优先标准 search + fetch，而不是随意发明只读工具。
上游示例优先：绿地上手顺序是官方 OpenAI 示例 → 版本匹配的 @modelcontextprotocol/ext-apps 示例 → 本地兜底脚本 scripts/scaffold_node_ext_apps.mjs。能抄近邻示例就不从零造大脚手架。
MCP 服务器脚手架：注册 MIME 为 text/html;profile=mcp-app 的 Widget 资源（或使用 SDK 常量 RESOURCE_MIME_TYPE），注册工具，并有意识地返回 structuredContent、content、_meta。
Widget 脚手架：默认走 MCP Apps bridge（JSON-RPC over postMessage），例如监听 ui/notifications/tool-result、用 tools/call 发起调用；window.openai 只作为 ChatGPT 兼容层与扩展能力（文件、模态、显示模式等）。
安全与提交元数据：配置 _meta.ui.csp、_meta.ui.domain 等；公开目录上架时再走部署与 submission 文档。
本地联调步骤：本地 /mcp、HTTPS 隧道、ChatGPT Developer Mode 里创建远程 MCP 应用，以及改完工具后刷新应用以重新加载描述符。

和「随便让 Agent 写个 MCP demo」相比，它的价值主要在约束流程：docs-first、example-first、契约校验，减少跟过期仓库模式或错误 API 面扯皮。

安装与启用¶

该 Skill 遵循通用 SKILL.md 格式，可在支持 Agent Skills 标准的工具中使用。不同宿主的安装目录不同，以各自官方说明为准。

Codex CLI / ChatGPT 桌面端中的 Codex¶

OpenAI 文档说明：可用内置的 $skill-installer 安装精选 Skill。例如：

$skill-installer chatgpt-apps

安装后 Skill 会出现在 $CODEX_HOME/skills/（默认 ~/.codex/skills）。Codex 会自动发现变更；若列表未更新，重启 Codex。

也可在提示词里显式调用，例如用 $ 提及 Skill，或通过 /skills 选择。

需要临时禁用而不删除时，可在 ~/.codex/config.toml 中配置：

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

修改后需重启 Codex。

Cursor¶

Cursor 会自动从以下目录加载 Skill（项目级或用户级）：

.agents/skills/、.cursor/skills/
~/.agents/skills/、~/.cursor/skills/
兼容目录：.claude/skills/、.codex/skills/ 及对应用户级路径

手动安装时，把官方目录放到例如：

.cursor/skills/chatgpt-apps/SKILL.md

也可连同 references/、scripts/、agents/ 一并拷贝，保留相对引用。Agent 聊天中可用 /chatgpt-apps 显式调用，或依赖 description 做隐式匹配。

Cursor 文档还支持从 GitHub 以 Remote Rule 方式导入仓库中的 Skill；仓库地址可使用：

https://github.com/openai/skills

具体路径为 skills/.curated/chatgpt-apps。

直接从 GitHub 获取¶

不依赖安装器时，可从以下地址查看或克隆源文件：

https://github.com/openai/skills/tree/main/skills/.curated/chatgpt-apps

目录大致包含：

chatgpt-apps/
├── SKILL.md
├── LICENSE.txt
├── agents/
│   └── openai.yaml
├── references/          # 原型分类、文档工作流、仓库契约等
└── scripts/
    └── scaffold_node_ext_apps.mjs

典型用法示例¶

Skill 文档给出的推荐提示词模式，是把 $chatgpt-apps 与 $openai-docs 成对使用，避免脚手架落后于当前文档。

脚手架一个带 MCP 服务器和 Widget 的应用：

Use $chatgpt-apps with $openai-docs to scaffold a ChatGPT app for <use-case> with a MCP server and widget.

基于最接近的官方示例改造：

Use $chatgpt-apps with $openai-docs to adapt the closest official Apps SDK example into a ChatGPT app for <use-case>.

把演示项目整理成更接近生产的结构：

Use $chatgpt-apps and $openai-docs to refactor this Apps SDK demo into a production-ready structure with tool annotations, CSP, and URI versioning.

先规划工具再生成代码：

Use $chatgpt-apps with $openai-docs to plan tools first, then generate the MCP server and widget code.

编码前，Skill 会要求 Agent 尽量补齐或推断：用例与主流程、只读还是会改数据、演示还是生产、是否公开目录提交、后端语言与 UI 栈、鉴权、CSP 外域、托管与本地开发方式等。

本地接到 ChatGPT 调试时，Skill 约定的大致步骤是：

本地启动 MCP，路径形如 http://localhost:<port>/mcp
用 ngrok 等工具暴露为公网 HTTPS，并把隧道 URL 加上 /mcp 填进 ChatGPT
在 ChatGPT 中打开 Settings → Apps & Connectors → Advanced settings，启用 Developer Mode
新建远程 MCP 应用并粘贴公网 MCP URL
修改工具或元数据后刷新应用，让 ChatGPT 重新加载描述符

Apps SDK 侧的 UI 约定与官方文档一致：新应用优先 _meta.ui.resourceUri 与 ui/* bridge；ChatGPT 仍兼容 _meta["openai/outputTemplate"] 与 window.openai 扩展。具体 API 以 Build your MCP server 与 Build your ChatGPT UI 为准。

适用场景与注意事项¶

适合这些情况：

要从零搭一个 ChatGPT App（MCP 工具 + 内嵌 Widget）
已有演示仓库，需要按当前文档补注解、CSP、URI 版本、解耦的 data/render 工具
排错联调：描述符对不上、Widget 不渲染、bridge / window.openai 混用
准备公开目录提交前的结构与检查清单（仅在明确要上架时走 submission 流程）

使用时注意：

先文档后代码：Skill 强制 docs-first；没有 $openai-docs 时应用 Developer Docs MCP 的 search/fetch，或直接打开 canonical Apps SDK 页面，不要因搜索失败就停工瞎写。
不要默认从零大脚手架：有接近的官方或 ext-apps 示例时，应复制最小相关文件再改。
API 面不要教错：仓库示例里的 app.sendMessage() 一类封装是便利层；对外说明应回到 bridge 或文档中的 window.openai.*。
公开提交是可选路径：内部 / 私有应用继续用 Developer Mode 即可，不要默认生成整套上架材料。
事实以一手文档为准：Apps SDK 与 MCP Apps 仍在演进，Skill 自身也要求「文档与旧仓库模式冲突时以当前文档为准」。

小结¶

chatgpt-apps 把 ChatGPT Apps 开发收成一套可复用的 Agent 工作流：分类形态、规划工具、选上游示例、搭 MCP 与 Widget、按契约校验，并给出 Developer Mode 联调步骤。若你正在用 Codex、Cursor 等支持 Agent Skills 的工具做 Apps SDK 项目，把它和 $openai-docs 一起用，比单靠通用提示更不容易偏离官方模式。

官方地址：

Skill 源码：https://github.com/openai/skills/tree/main/skills/.curated/chatgpt-apps
Codex Skills 说明：https://developers.openai.com/codex/skills
Apps SDK 文档入口可从 https://developers.openai.com/apps-sdk/ 查阅（MCP server、ChatGPT UI、reference 等）

用 chatgpt-apps Skill 搭建 ChatGPT Apps：MCP 服务器 + Widget UI

前言¶

这是什么¶

核心功能与亮点¶

安装与启用¶

Codex CLI / ChatGPT 桌面端中的 Codex¶

Cursor¶

直接从 GitHub 获取¶

典型用法示例¶

适用场景与注意事项¶

小结¶

精选优惠券

用 chatgpt-apps Skill 搭建 ChatGPT Apps：MCP 服务器 + Widget UI

前言¶

这是什么¶

核心功能与亮点¶

安装与启用¶

Codex CLI / ChatGPT 桌面端中的 Codex¶

Cursor¶

直接从 GitHub 获取¶

典型用法示例¶

适用场景与注意事项¶

小结¶

精选优惠券

相关文章