如何进行故障分类
当出现问题（例如组件无法渲染、发现功能缺失提示词、身份验证循环等）时，请先从隔离层面入手，确定问题出在服务器、组件还是 ChatGPT 客户端。以下清单涵盖了最常见的问题及其解决方案。
服务器端问题
- 未列出工具 – 请确认您的服务器正在运行，并且您已连接到
/mcp端点。如果您更改了端口，请更新连接器 URL 并重启 MCP Inspector。 - 仅显示结构化内容，无组件 – 请确认工具描述符将
_meta.ui.resourceUri设置为已注册的 HTML 资源，且其mimeType为"text/html;profile=mcp-app"（ChatGPT 将_meta["openai/outputTemplate"]视作可选的兼容性别名），并确认该资源加载时没有 CSP 错误。 - 模式 (Schema) 不匹配错误 – 确保您的 Pydantic 或 TypeScript 模型与
outputSchema中声明的模式匹配。进行更改后，请重新生成类型。 - 响应缓慢 – 当工具调用耗时超过几百毫秒时，组件会感到迟钝。请对后端调用进行性能分析，并尽可能缓存结果。
组件 (Widget) 问题
- 组件加载失败 – 请查看浏览器控制台（或 MCP Inspector 日志），检查是否有 CSP 冲突或缺失的资源包。确保 HTML 内联了编译后的 JS，并且所有依赖项都已打包。
- 拖拽或编辑状态无法持久保存 – 如果您依赖 ChatGPT 的组件状态持久化功能（可选），请验证在每次更新后是否调用了
window.openai.setWidgetState，并在挂载 (mount) 时通过window.openai.widgetState进行恢复 (rehydrate)。 - 移动端布局问题 – 如果您依赖 ChatGPT 的布局信号（可选），请检查
window.openai.displayMode和window.openai.maxHeight以调整布局。避免使用固定高度或仅限悬停触发的交互。
发现与入口点问题
- 工具无法触发 – 回顾您的元数据。使用“当……时使用此工具”的措辞重写描述，更新启动提示词，并使用您的基准测试提示词集重新测试。
- 选错工具 – 为相似工具添加更明确的细节，或在描述中注明禁止使用的场景。考虑将大型工具拆分为多个功能单一的小型工具。
- 启动器排名异常 – 刷新您的目录元数据，并确保应用图标和描述符合用户的预期。
身份验证问题
- 401 错误 – 在错误响应中包含
WWW-Authenticate头部，以便 ChatGPT 知道重新开始 OAuth 流程。请仔细检查颁发者 URL 和受众声明。 - 客户端注册失败 – 如果您使用 CIMD，请确认您的授权服务器元数据包含
client_id_metadata_document_supported: true，并且能够获取 ChatGPT 的客户端元数据文档。对于private_key_jwt，请确认您的授权服务器能够获取 ChatGPT 的公共 JWKS 并验证签名的客户端断言。如果您使用 DCR，请确认您的授权服务器暴露了registration_endpoint，并且新创建的客户端至少启用了登录连接。
部署问题
- Ngrok 隧道超时 – 在共享 URL 之前，请重启隧道并验证本地服务器是否正在运行。对于生产环境，请使用具备健康检查功能的稳定托管服务提供商。
- 流式传输在代理后断开 – 确保您的负载均衡器或 CDN 允许服务器发送事件 (SSE) 或流式 HTTP 响应，且不会进行缓存。
何时升级问题优先级
如果您已验证上述所有点，但问题依然存在：
- 收集日志（服务器日志、组件控制台日志、ChatGPT 工具调用记录）和屏幕截图。
- 记录您输入的提示词以及出现的任何确认对话框。
- 将详细信息分享给您的 OpenAI 合作伙伴联系人，以便他们能够在内部重现该问题。
一份清晰的排查日志可以缩短处理时间，并保持连接器对用户的可靠性。