前言¶

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 產出或完成這些事：

1. 應用原型分類：在寫代碼前先定一個主形態，例如 tool-only、vanilla-widget、react-widget、interactive-decoupled、submission-ready，再據此選示例和校驗重點。
2. 工具方案先行：規劃工具名、schema、註解（如 readOnlyHint、destructiveHint）與輸出；連接器 / 只讀類場景優先標準 search + fetch，而不是隨意發明只讀工具。
3. 上游示例優先：綠地上手順序是官方 OpenAI 示例 → 版本匹配的 @modelcontextprotocol/ext-apps 示例 → 本地兜底腳本 scripts/scaffold_node_ext_apps.mjs。能抄近鄰示例就不從零造大腳手架。
4. MCP 服務器腳手架：註冊 MIME 爲 text/html;profile=mcp-app 的 Widget 資源（或使用 SDK 常量 RESOURCE_MIME_TYPE），註冊工具，並有意識地返回 structuredContent、content、_meta。
5. Widget 腳手架：默認走 MCP Apps bridge（JSON-RPC over postMessage），例如監聽 ui/notifications/tool-result、用 tools/call 發起調用；window.openai 只作爲 ChatGPT 兼容層與擴展能力（文件、模態、顯示模式等）。
6. 安全與提交元數據：配置 _meta.ui.csp、_meta.ui.domain 等；公開目錄上架時再走部署與 submission 文檔。
7. 本地聯調步驟：本地 /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 約定的大致步驟是：

1. 本地啓動 MCP，路徑形如 http://localhost:<port>/mcp
2. 用 ngrok 等工具暴露爲公網 HTTPS，並把隧道 URL 加上 /mcp 填進 ChatGPT
3. 在 ChatGPT 中打開 Settings → Apps & Connectors → Advanced settings，啓用 Developer Mode
4. 新建遠程 MCP 應用並粘貼公網 MCP URL
5. 修改工具或元數據後刷新應用，讓 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 等）