> 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).

# 验证你的设置

使用 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。

| Error                             | 原因                                                                                                           | 修复方法                                                         |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| 没有 `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-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication.md) 页面上验证你的配置，而不是添加 API 密钥。

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

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

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

* [ ] `[ConvaiRuntime] Started successfully` — SDK 已初始化所有内部服务
* [ ] `[RoomConnectionRuntimeAdapter] Room connection succeeded (mode=create).` — 房间已连接
* [ ] 如果存在聊天记录 UI，它会在对话开始后开始显示消息——连接成功时它不会记录任何内容，因此请关注 UI 本身而不是 Console
* [ ] Character `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] 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。

{% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
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=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.