故障排查

排查 Apps SDK 应用中的问题

当出现问题时 – component 无法渲染、发现遗漏提示、认证循环 – 首先隔离负责的层次:服务器、component 还是 ChatGPT 客户端。

按层次划分的故障排查清单

服务器端问题

• 验证服务器正在运行并连接到 /mcp 端点
• 确认工具响应具有正确的元数据和 HTML 资源
• 确保架构与公布的输出匹配
• 对慢速后端调用进行性能分析和缓存

Widget 问题

• 检查浏览器控制台是否有 CSP 违规
• 使用 window.openai.setWidgetState 验证 widget 状态持久化
• 使用 window.openai.displayMode 调整移动端布局

发现问题

• 使用 "Use this when..." 措辞改进工具描述
• 为相似工具添加澄清细节
• 刷新目录元数据

认证挑战

• 为 401 错误包含 WWW-Authenticate 标头
• 验证 OAuth 发行者 URL 和受众声明
• 检查动态客户端注册设置

部署注意事项

• 确保稳定的托管和健康检查
• 验证代理/CDN 与流式响应的兼容性

升级建议

如果问题持续存在:

1. 收集全面的日志
2. 记录特定提示和交互
3. 与 OpenAI 合作伙伴联系人分享详细的重现步骤

该指南强调跨不同系统层次的系统化调查,以诊断和解决 Apps SDK 集成问题。