> For the complete documentation index, see [llms.txt](https://docs.convai.com/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/validate-your-setup.md).

# 验证你的设置

在部署或分享你的场景之前，请运行 SDK 内置的验证器，并确认 Play Mode 的启动顺序。本页涵盖验证器执行的所有检查、成功时预期的控制台输出，以及常见失败的故障排查表。

### 运行场景验证器

场景验证器会检查你的场景是否存在缺失组件、必填字段为空以及常见的错误配置。请在开发过程中的任何时候运行它——不必等到最后。

在 Unity Editor 菜单栏中，选择 **GameObject > Convai > Validate Scene Setup**.

会出现一个对话框，其中包含以下列表： **错误** （必须修复）、 **警告** （建议处理）和 **后续步骤** （建议操作）。

### 验证器检查

#### 错误 — 必须修复

这些问题会阻止场景连接到 Convai。

| 错误                                | 原因           | 修复                                                     |
| --------------------------------- | ------------ | ------------------------------------------------------ |
| 没有 `ConvaiManager` 在场景中找到         | SDK 未初始化     | 运行 **GameObject > Convai > Setup Required Components** |
| 没有 `ConvaiCharacter` 在场景中找到       | 未注册任何角色      | 添加 `ConvaiCharacter` 到你的 NPC GameObject                |
| `ConvaiCharacter` 没有 Character ID | 必填字段为空       | 输入你在 Convai 仪表板中的 Character ID                         |
| 没有 `ConvaiPlayer` 在场景中找到          | 缺少 Player 组件 | 运行 **GameObject > Convai > Setup Required Components** |

#### 警告 — 建议处理

这些问题不会阻止连接，但可能会影响功能。

| 警告              | 原因                                                             | 修复                                   |
| --------------- | -------------------------------------------------------------- | ------------------------------------ |
| API 密钥未配置       | `ConvaiSettings.HasApiKey` 返回 false                            | 打开 **Convai > Account** 并输入你的 API 密钥 |
| 视频模式已启用，但未找到视觉源 | `_connectionType` 为 `AudioVideo` 但没有 `IVisionFrameSource` 组件存在 | 添加帧源组件，或切换到 `音频` 模式                  |

{% hint style="success" %}
当验证器显示零错误且零警告时，你的场景就已准备好进入 Play Mode。
{% endhint %}

### Play 模式启动检查清单

验证器通过后，进入 Play Mode，并按顺序观察 Console 中是否出现以下日志行。

* [ ] `[ConvaiRuntime] 启动成功` — SDK 已初始化所有内部服务
* [ ] `[RoomConnectionRuntimeAdapter] Character <character-id> 连接成功（模式=create）。` — 角色已连接到 Convai
* [ ] `[ChatTranscriptUI] 依赖项已通过显式初始化注入` — 记录 UI 已连接（如果存在）
* [ ] 角色 `IsCharacterReady` 变为 `true` 在 30 秒内——Convai 已确认该角色

{% hint style="info" %}
角色就绪信号可能会在房间连接后 2–10 秒到达，具体取决于服务器负载。如果它未在以下时间内到达 `_characterReadyTimeoutSeconds` （默认：30 秒），SDK 会记录超时警告。
{% endhint %}

要在 `IsCharacterReady` 运行时检查：

```csharp
void Start()
{
    var character = FindFirstObjectByType<ConvaiCharacter>();
    character.OnCharacterReady += () => Debug.Log("Character is ready to converse.");
}
```

### 故障排查

| 症状                                  | 可能原因                                     | 修复                                                                                                    |
| ----------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `[ConvaiRuntime] 启动成功` 不在 Console 中 | `ConvaiManager` 缺失或启动失败                  | 检查 `ConvaiManager` 是否在场景中。查看 Console 中更早的错误。                                                          |
| 房间从未连接——没有角色已连接日志                   | API 密钥无效或缺失；网络问题                         | 在以下位置验证你的 API 密钥 **Convai > Account**。检查防火墙规则是否允许到以下地址的 WebSocket/HTTPS： `live.convai.com`.           |
| `[ChatTranscriptUI] 依赖项未注入……`       | `ConvaiManager` 在 UI 启动时未找到              | 确保 `ConvaiManager` 在场景中。其执行顺序（-1100）保证它最先运行。                                                          |
| 角色 `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 着色器。 |

### 设置完成

你的场景现在具备：

* 已安装 SDK，并使用有效 API 密钥连接到 Convai
* 一个包含 `ConvaiManager`, `ConvaiRoomManager`, `ConvaiCharacter`，以及 `ConvaiPlayer`
* 验证器通过且零错误
* 一个可连接、变为就绪并响应语音输入的角色

### 下一步

继续入门流程，配置输入模式、音频和 UI。

{% content-ref url="/pages/26b817b7abe1379d0e73ce3dc01f1e053df39b56" %}
[配置对话输入模式](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/configure-conversation-input-mode.md)
{% endcontent-ref %}

或者浏览 Features 部分，为你的角色添加 Actions、Emotion、Long-Term Memory 或 Vision。

{% content-ref url="/pages/8c561f7c198c46628ed5818040fdaa9af3397caf" %}
[功能](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/features.md)
{% endcontent-ref %}

查看 Core Concepts，以更深入了解会话生命周期和事件系统。

{% content-ref url="/pages/b20dffbec401e06e9fe4168f409ab42a87fa327b" %}
[核心概念](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/core-concepts.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/validate-your-setup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.