如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题
概览 智能体访问 ChatGPT 与 Codex 用户文档 使用场景

故障排查

排查插件工具和可选用户界面的问题。

如何定位问题

如果组件无法渲染、发现过程中找不到提示词,或身份验证陷入循环,请先确定问题出在服务器、组件还是 ChatGPT 客户端。以下清单列出了最常见的问题及其解决方法。

服务器、工具和发现机制的检查项适用于 ChatGPT 和 Codex 中的插件。本页有关用户界面、小组件状态和客户端身份验证的检查项针对 ChatGPT 的行为。

服务器端问题

  • 工具列表为空: 确认服务器正在运行,并且您连接的是 /mcp 端点。如果您更改了端口,请更新 MCP 服务器 URL 并重启 MCP Inspector。
  • 只有结构化内容,未显示组件: 确认工具描述符中的 _meta.ui.resourceUri 指向已注册的 HTML 资源,且该资源设置了 mimeType: "text/html;profile=mcp-app"(为兼容现有配置,ChatGPT 也支持使用 _meta["openai/outputTemplate"] 作为别名)。确认资源能正常加载,且不会触发 CSP 错误。
  • 模式不匹配错误: 确认您的 Python 或 TypeScript 模型与 outputSchema 中声明的模式一致。更改后请重新生成类型。
  • 响应缓慢: 如果工具调用耗时超过几百毫秒,组件就会显得迟缓。请分析服务器调用的耗时,并尽可能缓存结果。

小组件问题

  • 小组件无法加载: 打开浏览器控制台(或查看 MCP Inspector 日志),检查是否有违反 CSP 的情况或缺失的打包文件。确保 HTML 包含编译后的 JavaScript,并且打包文件包含所有依赖项。
  • 拖放或编辑后的更改未保存: 如果您依赖 ChatGPT 保存小组件状态,请在每次更新后调用 window.openai.setWidgetState,并在小组件挂载时从 window.openai.widgetState 恢复状态。
  • 移动设备上的布局异常: 如果您依赖 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,并且新创建的客户端已启用至少一个登录连接。
  • 现有 MCP 服务器连接返回 invalid_client: 确认动态注册的 OAuth 客户端仍然存在。如果该客户端有客户端密钥,请确认授权服务器仍接受该密钥。ChatGPT 会重复使用这些凭据,因此请恢复原有凭据,无需创建新客户端。如果是访问令牌已过期,则需要采用其他解决方法。

部署问题

  • ngrok 隧道超时: 重启隧道,并在分享 URL 前确认本地服务器正在运行。在生产环境中,请选择服务稳定且提供健康检查的托管服务商。
  • 经过代理时流式传输中断: 确保负载均衡器或 CDN 允许传输服务器发送事件或流式 HTTP 响应,并且不会缓冲这些内容。

何时寻求进一步支持

如果您已逐项核对上述内容,但问题仍然存在,请按以下步骤操作:

  1. 收集服务器日志、组件控制台日志、ChatGPT 工具调用记录以及屏幕截图。
  2. 记下您提交的提示词和收到的所有确认消息。
  3. 将这些信息提供给您的 OpenAI 合作伙伴联系人,以便他们在内部复现问题。

清晰简洁的故障排查记录有助于缩短问题处理时间,让您的 MCP 服务器持续为用户提供可靠的服务。