> 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 内置验证器并验证播放模式启动顺序。本页涵盖验证器执行的每一项检查、成功时预期的控制台输出，以及常见失败的故障排除表。

### 运行场景验证器

场景验证器会检查你的场景中是否缺少组件、必需字段是否为空，以及常见的配置错误。开发过程中的任何阶段都可以运行它——不必等到最后。

在 Unity 编辑器菜单栏中，选择 **GameObject > Convai > 验证场景设置**.

会出现一个对话框，其中列出 **错误** （必须修复）， **警告** （建议），以及 **后续步骤** （建议操作）。

### 验证器检查

#### 错误 — 必须修复

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

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

#### 警告 — 建议

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

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

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

### 播放模式启动检查清单

验证器通过后，进入播放模式并按顺序观察控制台中的这些日志行。

* [ ] `[ConvaiRuntime] 启动成功` — SDK 已初始化所有内部服务
* [ ] `[RoomConnectionRuntimeAdapter] 角色 <character-id> 已成功连接（mode=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("角色已准备好进行对话。");
}
```

### 故障排除

| 症状                                  | 可能原因                                      | 修复                                                                                                    |
| ----------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `[ConvaiRuntime] 启动成功` 未在 Console 中 | `ConvaiManager` 缺失或引导启动失败                 | 检查 `ConvaiManager` 已在场景中。请查看 Console 中更早的错误。                                                          |
| 房间始终无法连接 — 没有角色连接日志                 | API 密钥无效或缺失；网络问题                          | 在以下位置验证你的 API 密钥 **Convai > 设置 > 凭据**。检查防火墙规则是否允许 WebSocket/HTTPS 连接到 `live.convai.com`.              |
| `[ChatTranscriptUI] 依赖未注入...`       | `ConvaiManager` 在 UI 启动时未找到               | 确保 `ConvaiManager` 已在场景中。其执行顺序（-1100）保证它最先运行。                                                         |
| 角色 `IsCharacterReady` 保持 `false`    | Character ID 错误，或者该角色不存在于你的账户中            | 验证 Character ID 与你的 Convai 仪表板上显示的内容完全一致。                                                             |
| 麦克风始终不打开 — 角色什么也听不到                 | 按键通话模式已开启，麦克风默认静音启动                       | 在 `ConvaiRoomManager`，确认 **模式** 为 `免提`，或者按 **T** 如果你使用按键通话。                                           |
| 角色语音已播放，但 BlendShape 未动画            | `ConvaiLipSyncComponent` 未配置，或配置文件 ID 不匹配 | 添加 `ConvaiLipSyncComponent` 到角色上。验证 `_lockedProfileId` 与角色的传输格式匹配。分配目标 `SkinnedMeshRenderer`（多个）。     |
| 示例场景中的材质显示为粉色                       | 渲染管线不匹配（内置 vs 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, and the optional `goal` 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>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.