故障排除

查找 Convai Unity SDK 中有关安装错误、API 问题、音频故障和调试工具的故障排查指南。

本节涵盖 SDK 层级发生的问题——在连接到 Convai 之前或期间发生的问题——无论你正在使用哪些功能。如果 SDK 已成功连接，但某个特定功能（如 Actions、Emotion 或 Vision）未按预期工作，请先查看该功能章节中的故障排除页面。这里的页面涉及四类常见问题：包安装与导入、API 密钥和连接失败、音频和麦克风问题，以及完整的一套内置诊断工具。

不确定从哪里开始？ 打开 Unity Console，查找第一个带有以下标签的错误或警告： [Convai]。如果消息包含点号格式的错误代码——例如 connection.connect_invalid_api_key 或 audio.mic_permission_denied ——请直接进入与其前缀匹配的页面。如果你看到来自 Convai Bootstrapper的纯英文消息，请从“安装与包问题”开始。

故障排除类别

安装和包问题 包导入失败、缺少依赖项、找不到 ConvaiSettings，以及启动时的 API 密钥警告。

连接和 API 问题 API 密钥被拒绝、未找到角色、超时、速率限制、传输错误、重试行为以及运行时诊断。

音频和麦克风问题 麦克风权限失败、设备不可用、音频发布错误，以及 Android、iOS 和 WebGL 的平台特定设置。

调试工具参考 日志配置、日志类别、ConvaiActionDebugProbe、会话诊断、延迟指标以及自定义日志接收端。

特定功能的故障排除

在成功连接后出现的问题——也就是 SDK 正在运行，但某个特定功能行为不正确——都会记录在各自功能的章节中。

功能	故障排除页面
动作	features/actions/troubleshooting.md
情绪	features/emotion/troubleshooting.md
长期记忆	features/long-term-memory/troubleshooting.md
动态上下文	features/dynamic-context/troubleshooting.md
叙事设计	features/narrative-design/troubleshooting.md
视觉	features/vision/troubleshooting.md
场景元数据	features/scene-metadata/troubleshooting-and-diagnostics.md
对话动画	utilities/dialogue-animation/troubleshooting.md
凝视与注意力	utilities/gaze-and-attention/troubleshooting.md

下一步

当一个问题仅凭单条错误消息很难诊断时，请先使用调试工具。为某个特定类别启用详细日志，并读取 ConvaiRoomManager 运行时状态，通常可以在几分钟内缩小大多数问题的范围。

调试工具参考