验证你的设置
使用 Troubleshooter 窗口检查 Convai 角色,并在进入播放模式之前确认所需组件已存在。
在进入播放模式之前,请使用 Convai 故障排查器和全场景验证器检查你的角色。这两者回答的是不同的问题:故障排查器会报告是什么会阻止某个模块在所选角色上工作,而验证器则确认基本的场景连接是否就绪—— ConvaiManager, ConvaiCharacter, ConvaiPlayer以及 Character ID 字段——是否已就绪。两个都要运行。
使用故障排查器检查角色
打开 Convai > 故障排除。窗口会加载你当前选中的角色,或者列出场景中的每个 ConvaiCharacter 当你切换到 此场景 模式。
对于所选角色,故障排查器会按每个模块一行显示检查结果。每条结果都会显示严重性,并在需要处理时提供一个修复按钮,一个 显示给我看 按钮,用于选中其所指的对象,或者一个 打开 按钮,用于打开相关的编辑器窗口。使用 重新检查 在做出更改后,或使用 修复所有可修复项 一次性应用所有一键修复。
并非每一行都提供相同的帮助。Actions 行带有可直接在窗口中应用的修复项。用于具身模块——Gaze、Body Animation、Body Language、Emotion 以及具身设置本身——的行会报告它们发现的内容,但不会带有修复或定位按钮,因此需要在各自模块的编辑器窗口中处理。只有当某个模块对角色有可说明的内容时才会出现对应的行,因此没有该模块的角色不会为它生成一行。
Actions 适用于每个 ConvaiCharacter,因此即使是一个刚刚接好且没有其他模块的角色,也会显示一行 Actions。对于尚未配置任何 actions 的角色,这一行只是信息提示:它告诉你该角色可以说话,但不会执行动作,并不表示出了问题。
故障排查器检查的是模块配置,而不是原始场景接线。缺少 ConvaiManager 或空的 Character ID 会由下面的场景验证器捕获。
运行场景验证器
场景验证器会检查你的场景中是否缺少组件、必填字段是否为空,以及常见的错误配置。请在开发过程中任何阶段运行它,而不只是最后。
在 Unity 编辑器菜单栏中,选择 GameObject > Convai > Validate Scene Setup.
会出现一个对话框,其中列出 错误 (必须修复)、 警告 (建议)以及 后续步骤 (建议的操作)。
验证器检查项
错误 — 必须修复
这些问题会阻止场景连接到 Convai。
没有 ConvaiManager 在场景中找到
SDK 尚未初始化
运行 GameObject > Convai > Setup Required Components
没有 ConvaiRoomManager 在场景中找到
缺少房间连接组件
运行 GameObject > Convai > Setup Required Components
未导入 TextMesh Pro 必需资源
Convai 的 UI 预制体和字体引用了 TextMesh Pro 的运行时着色器和默认字体,而 Unity 会按项目分别导入这些内容,并不会随包一起提供。没有它们时,包含 Convai UI 的场景打开就会报错。
选择 Window > TextMeshPro > Import TMP Essential Resources
没有 ConvaiCharacter 在场景中找到
未注册任何角色
添加 ConvaiCharacter 到你的 NPC GameObject
ConvaiCharacter 没有 Character ID
必填字段为空
请输入 Convai 控制面板中的 Character ID
没有 ConvaiPlayer 在场景中找到
缺少 Player 组件
运行 GameObject > Convai > Setup Required Components
警告 — 建议
这些不会阻止连接,但可能会影响功能。
API 密钥未配置
ConvaiSettings.HasApiKey 返回 false
打开 Convai > Settings > Credentials 并输入你的 API 密钥
视频模式已启用,但未找到视觉源
房间的 ConvaiRoomManager 层级中没有 IVisionPublisher 组件,也没有 IVisionFrameSource 组件,或者两者都没有,而房间的实际连接类型是 视频
添加一个视觉发布器和一个帧源组件,或者切换到 音频 模式
验证器仅根据 API 密钥未配置 来自 ConvaiSettings.HasApiKey 来推断;它不会检查 ConvaiSettings.HasValidAuthConfig,它会考虑项目的 AuthMode。以 Auth Token 模式运行的项目不要求拥有 API 密钥,因此即使身份验证配置正确,这个警告也可能出现。如果你的项目使用 Auth Token 模式,请将此警告视为预期现象,并在 身份验证 页面上验证你的配置,而不是添加 API 密钥。
播放模式启动检查清单
在验证器通过后,进入播放模式,并按顺序观察 Console 中的这些日志行。
要在 IsCharacterReady 运行时检查:
故障排除
[ConvaiRuntime] Started successfully 而不是在 Console 中
ConvaiManager 缺失或引导失败
检查 ConvaiManager 是否在场景中。查看 Console 中更早的错误。
房间始终未连接 — 没有角色已连接日志
API 密钥无效或缺失;网络问题
在 Convai > Settings > Credentials中验证你的 API 密钥。检查防火墙规则是否允许 WebSocket/HTTPS 访问 live.convai.com.
聊天记录 UI 不显示任何消息
必需的 UI 引用未在 ChatTranscriptUI
检查 Console 中的 chatContainer 未分配 - 消息将不会显示 或 scrollRect 未分配 - 自动滚动将无法工作,并在 Inspector 中分配缺失的引用。
Character IsCharacterReady 保持 false
Character ID 错误,或者该角色在你的账号中不存在
请确认 Character ID 与 Convai 控制面板上显示的内容完全一致。
麦克风始终不打开 — 角色什么也听不到
按键通话模式已开启,并且麦克风初始为静音
在 ConvaiRoomManager,请确认 模式 是 HandsFree,或者按 T 如果使用按键通话。
角色语音会播放,但 BlendShape 不会播放动画
ConvaiLipSyncComponent 未配置或配置文件 ID 不匹配
添加 ConvaiLipSyncComponent 已分配给角色。请验证 _lockedProfileId 与角色的传输格式匹配。分配目标 SkinnedMeshRenderer(们)。
示例场景中的材质显示为粉色
渲染管线不匹配(Built-in 与 URP)
通过以下方式转换材质 Edit > Rendering > Materials > Convert All Built-in Materials to URP,或者手动重新分配 URP 着色器。
设置完成
你的场景现在具有:
已安装并使用有效 API 密钥连接到 Convai 的 SDK
一个包含
ConvaiManager,ConvaiRoomManager,ConvaiCharacter,以及ConvaiPlayer场景验证器和故障排查器都报告零错误
一个可连接、可就绪并能响应语音输入的角色
下一步
继续入门路径,配置输入模式、音频和 UI。
或者浏览 Features 部分,为你的角色添加 Actions、Emotion、Long-Term Memory 或 Vision。
查看 Core Concepts,以更深入理解会话生命周期和事件系统。
最后更新于
这有帮助吗?