参考资料

window.openai 组件桥接接口

ChatGPT 提供 window.openai，用于兼容性别名和可选的 ChatGPT 扩展。开发新 UI 时，只要共享规范提供了等效功能， 就应使用 MCP Apps 桥接接口，仅在需要 ChatGPT 专用能力时 使用 window.openai。

有关具体实现步骤，请参阅构建 ChatGPT UI。

如果您的工具需要确认，初始 toolInput 缺失属于正常情况。 ChatGPT 不会在审批通过前将需要审批的参数加载到小组件的值中； 而是在用户批准调用后，由主机通过 ui/notifications/tool-input 传递这些参数。

能力

useOpenAiGlobal 辅助函数

许多 ChatGPT UI 项目会将对 window.openai 的访问封装在小型辅助函数中， 以保持视图的可测试性。此示例辅助函数会监听主机的 openai:set_globals 事件， 让 React 组件能够订阅单个全局值：

export function useOpenAiGlobal<K extends keyof WebplusGlobals>(
  key: K
): WebplusGlobals[K] {
  return useSyncExternalStore(
    (onChange) => {
      const handleSetGlobal = (event: SetGlobalsEvent) => {
        const value = event.detail.globals[key];
        if (value === undefined) {
          return;
        }

        onChange();
      };

      window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal, {
        passive: true,
      });

      return () => {
        window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handleSetGlobal);
      };
    },
    () => window.openai[key]
  );
}

关闭 UI

调用 window.openai.requestClose()，请求 ChatGPT 关闭当前 UI。

请求其他显示模式

使用 window.openai.requestDisplayMode 请求内嵌、画中画 或全屏显示：

await window.openai?.requestDisplayMode({ mode: "fullscreen" });
// On mobile, picture-in-picture may be presented as fullscreen.

打开模态窗口

使用 window.openai.requestModal 打开由主机控制的模态窗口。 提供同一 MCP 服务器注册的另一个 UI 模板的 URI， 或省略 template 以打开当前模板：

await window.openai.requestModal({
  template: "ui://widget/checkout.html",
});

文件 API

ChatGPT 支持文件上传和下载辅助函数， 这些函数作为可选的 window.openai 扩展提供。

ChatGPT 文件库是一项可选功能，可能并非对所有用户开放。 当此辅助函数可用时，window.openai.selectFiles() 返回的文件 已获授权，可供当前插件使用。将返回的 fileId 用于 window.openai.getFileDownloadUrl({ fileId })，或将其用于采用 文件参数的工具输入。

上传用户选择的文件：

const { fileId } = await window.openai.uploadFile(file, {
  library: true,
});

选择用户已上传到 ChatGPT 的文件：

if (window.openai?.selectFiles) {
  const files = await window.openai.selectFiles();
  // [{ fileId, fileName, mimeType }]
}

请检测 window.openai.selectFiles 是否可用，并在文件库不可用时回退到 window.openai.uploadFile。

请求临时下载 URL：

const { downloadUrl } = await window.openai.getFileDownloadUrl({ fileId });

定义文件输入

要让 ChatGPT 向工具传递文件，请在 _meta["openai/fileParams"] 中列出每个顶层文件输入。列出的每个字段都必须解析为文件对象或 文件对象数组。

每个文件对象模式都必须声明全部四个受支持的属性：

mime_type 和 file_name 的值是可选的，但您必须在模式中 声明这两个属性。如果文件模式存在以下任一情况， 扫描工具 步骤和插件提交都会拒绝该模式： 遗漏四个属性中的任意一个；未将 download_url 和 file_id 设为必填；将任一可选属性设为必填；或 将 download_url 和 file_id 以外的属性设为必填。您可以声明 额外的可选属性。

以下完整的工具描述符接受一个必填的文件输入：

{
  "name": "analyze_file",
  "title": "Analyze file",
  "description": "Analyzes a user-provided file without modifying it.",
  "inputSchema": {
    "type": "object",
    "$defs": {
      "OpenAIFile": {
        "type": "object",
        "properties": {
          "download_url": { "type": "string" },
          "file_id": { "type": "string" },
          "mime_type": { "type": "string" },
          "file_name": { "type": "string" }
        },
        "required": ["download_url", "file_id"],
        "additionalProperties": false
      }
    },
    "properties": {
      "file": { "$ref": "#/$defs/OpenAIFile" }
    },
    "required": ["file"]
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": false,
    "destructiveHint": false
  },
  "_meta": {
    "openai/fileParams": ["file"]
  }
}

要接受多个文件，请将顶层字段定义为数组，并在 items 中使用相同的文件对象模式。工具可以将顶层文件字段设为必填， 这一设置与每个文件对象内部的必填属性相互独立。

运行时，ChatGPT 传递的文件值使用蛇形命名法命名的字段：

{
  "download_url": "https://...",
  "file_id": "file_...",
  "mime_type": "image/png",
  "file_name": "input.png"
}

ChatGPT 始终包含 download_url 和 file_id，但可能省略 mime_type 和 file_name。当小组件需要新的临时下载 URL 时， 请将 file_id 作为 fileId 的值， 用于 window.openai.getFileDownloadUrl({ fileId })。

持久化小组件状态时，如果您希望模型在后续对话轮次中看到图像 ID，请使用结构化格式（modelContent、privateContent、imageIds）。

主机支持的导航

沙盒运行时会将 iframe 中的导航历史同步到 ChatGPT 的 UI。 使用 React Router 等标准路由 API， 主机就会让其导航控件与您的 UI 保持同步。

使用 React Router 的 BrowserRouter 设置路由：

export default function PizzaListRouter() {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<PizzaListPlugin />}>
          <Route path="place/:placeId" element={<PizzaListPlugin />} />
        </Route>
      </Routes>
    </BrowserRouter>
  );
}

编程式导航：

const navigate = useNavigate();

function openDetails(placeId: string) {
  navigate(`place/${placeId}`, { replace: false });
}

function closeDetails() {
  navigate("..", { replace: true });
}

工具描述符参数

默认情况下，工具描述应包含此处列出的字段。

请为所有返回 structuredContent 的工具声明 outputSchema。 该模式应准确描述工具返回的对象，以便客户端 验证结果，并让模型能够对后续工具调用进行推理。

工具描述符上的 _meta 字段

在工具描述符上使用以下 _meta 字段。将工具关联到 UI 模板时，优先使用 MCP Apps 标准 键 _meta.ui.resourceUri。ChatGPT 支持 OpenAI 专用元数据，用于兼容性支持和可选扩展。

示例：

import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";

registerAppTool(
  server,
  "search",
  {
    title: "Public Search",
    description: "Search public documents.",
    inputSchema: { q: z.string() },
    outputSchema: {
      results: z.array(
        z.object({
          id: z.string(),
          title: z.string(),
          url: z.string(),
        })
      ),
    },
    securitySchemes: [
      { type: "noauth" },
      { type: "oauth2", scopes: ["search.read"] },
    ],
    _meta: {
      securitySchemes: [
        { type: "noauth" },
        { type: "oauth2", scopes: ["search.read"] },
      ],
      ui: { resourceUri: "ui://widget/story.html" },
      // Optional compatibility alias (ChatGPT only):
      // "openai/outputTemplate": "ui://widget/story.html",
      "openai/toolInvocation/invoking": "Searching…",
      "openai/toolInvocation/invoked": "Results ready",
    },
  },
  async ({ q }) => {
    const results = await performSearch(q);

    return {
      structuredContent: { results },
      content: [{ type: "text", text: `Found ${results.length} results.` }],
    };
  }
);

注解

要将工具标记为“只读”，请使用以下 ToolAnnotations 字段 来配置工具描述符：

这些提示仅影响 ChatGPT 或 Codex 向用户说明工具调用的方式；服务器仍须执行自身的授权逻辑。

示例：

import { z } from "zod";

server.registerTool(
  "list_saved_recipes",
  {
    title: "List saved recipes",
    description: "Returns the user’s saved recipes without modifying them.",
    inputSchema: {},
    outputSchema: {
      recipes: z.array(
        z.object({
          id: z.string(),
          title: z.string(),
        })
      ),
    },
    annotations: { readOnlyHint: true },
  },
  async () => ({
    structuredContent: { recipes: await fetchSavedRecipes() },
  })
);

组件资源的 _meta 字段

在提供组件的资源模板（registerResource）上设置这些键。它们帮助 ChatGPT 描述渲染出的 iframe 并确定其展示方式，同时不会向其他客户端泄露元数据。

ChatGPT 支持旧版兼容键 _meta["openai/widgetCSP"]，其字段名称采用以下 snake_case 形式：

• connect_domains: string[]
• resource_domains: string[]
• frame_domains?: string[]
• redirect_domains?: string[]。用于指定 window.openai.openExternal 重定向目标的 ChatGPT 扩展。

新 UI 通常应优先使用标准 _meta.ui.csp 对象，该对象支持以下字段：

• connectDomains: string[]。小组件可通过 fetch/XHR 访问的域名。
• resourceDomains: string[]。静态资源（图像、字体、脚本、样式）使用的域名。
• frameDomains?: string[]。允许通过 iframe 嵌入的源列表（可选）。默认情况下，小组件无法渲染子框架。插件可以按照 iframe 政策嵌入自身域名下的内容，包括现有的编辑器和管理界面。提交时必须说明理由，使用 iframe 可能需要额外审查，或导致审批时间延长。

不过，_meta.ui.csp 不支持为 window.openai.openExternal(...) 链接设置 redirect_domains。要将重定向目标加入允许列表，您仍须设置 _meta["openai/widgetCSP"].redirect_domains。

工具结果

工具结果可以包含以下字段。重点如下：

只有 structuredContent 和 content 会出现在对话记录中。主机会将 _meta 转发给组件，让您可以向 UI 填充数据，而不向模型暴露这些数据。

主机提供的工具结果元数据：

示例：

import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";

registerAppTool(
  server,
  "get_zoo_animals",
  {
    title: "get_zoo_animals",
    inputSchema: { count: z.number().int().min(1).max(20).optional() },
    outputSchema: {
      animals: z.array(
        z.object({
          id: z.string(),
          name: z.string(),
          species: z.string(),
        })
      ),
    },
    _meta: { ui: { resourceUri: "ui://widget/widget.html" } },
  },
  async ({ count = 10 }) => {
    const animals = generateZooAnimals(count);

    return {
      structuredContent: { animals },
      content: [{ type: "text", text: `Here are ${animals.length} animals.` }],
      _meta: {
        allAnimalsById: Object.fromEntries(
          animals.map((animal) => [animal.id, animal])
        ),
      },
    };
  }
);

包含错误的工具结果

要在工具结果中返回错误，请使用以下 _meta 键：

客户端提供的 _meta 字段

操作阶段的 _meta["openai/userAgent"] 和 _meta["openai/userLocation"] 仅供参考；服务器绝不能依赖它们做出授权决策，并且必须能够处理它们缺失的情况。应将 _meta["openai/userAgent"] 视为可选且尽力提供的元数据，而不能将其作为可靠判断哪个宿主界面正在调用您的服务器的依据。

示例：

import { z } from "zod";

server.registerTool(
  "recommend_cafe",
  {
    title: "Recommend a cafe",
    inputSchema: {},
    outputSchema: {
      cafes: z.array(
        z.object({
          name: z.string(),
          address: z.string(),
        })
      ),
    },
  },
  async (_args, { _meta }) => {
    const locale = _meta?.["openai/locale"] ?? "en";
    const location = _meta?.["openai/userLocation"]?.city;
    const cafes = await findNearbyCafes(location);

    return {
      content: [{ type: "text", text: formatIntro(locale, location) }],
      structuredContent: { cafes },
    };
  }
);