> 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 Troubleshooter 和全场景验证器检查你的角色。二者回答的是不同的问题：Troubleshooter 会报告哪些问题会阻止某个模块在所选角色上工作，而验证器则确认基本的场景连线—— `ConvaiManager`, `ConvaiCharacter`, `ConvaiPlayer`，以及 Character ID 字段——是否就位。两者都运行。

### 使用 Troubleshooter 检查角色

打开 **Convai > Troubleshooter**。窗口打开时会载入你当前选中的角色，或者列出每个 `ConvaiCharacter` 场景中的角色，当你切换到 **此场景** 模式。

对于所选角色，Troubleshooter 会按模块逐行报告发现。每条发现都会显示严重性，并且当有可处理项时，会提供一个修复按钮、一个 **显示给我** 按钮，用于选中其所指对象，或者一个 **打开** 按钮，用于打开相关编辑器窗口。使用 **重新检查** 在做出更改后，或者 **修复所有可修复项** 一次性应用所有一键修复。

并非每一行都提供相同的帮助。Actions 行带有可在窗口中应用的修复。化身模块——Gaze、Body Animation、Body Language、Emotion，以及化身设置本身——对应的行会报告它们发现的问题，但不会提供修复或定位按钮，因此应在各自模块的编辑器窗口中处理。只有当模块对角色有话可说时，才会出现对应行，所以没有该模块的角色不会为它生成行。

Actions 适用于每个 `ConvaiCharacter`角色

Troubleshooter 检查的是模块设置，而不是原始场景连线。缺少 `ConvaiManager` 或者空的 Character ID 会由下面的场景验证器捕获。

### 运行场景验证器

Scene Validator 会检查场景中是否缺少组件、必填字段是否为空，以及常见的配置错误。请在开发过程中的任何时候运行它，而不仅仅是在最后。

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

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

### 验证器检查

#### 错误——必须修复

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

| 错误                                   | 原因                                                                                                      | 修复方法                                                         |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| 场景中没有 `ConvaiManager` 找到             | SDK 未初始化                                                                                                | 运行 **GameObject > Convai > Setup Required Components**       |
| 场景中没有 `ConvaiRoomManager` 找到         | 缺少房间连接组件                                                                                                | 运行 **GameObject > Convai > Setup Required Components**       |
| 未导入 TextMesh Pro Essential Resources | Convai 的 UI 预制件和字体引用了 TextMesh Pro 的运行时着色器和默认字体，而这些是 Unity 按项目导入而非随包提供的。包含 Convai UI 的场景如果没有它们，在打开时会报错。 | 选择 **Window > TextMeshPro > Import TMP Essential Resources** |
| 场景中没有 `ConvaiCharacter` 找到           | 未注册任何角色                                                                                                 | 添加 `ConvaiCharacter` 到你的 NPC GameObject                      |
| `ConvaiCharacter` 没有 Character ID    | 必填字段为空                                                                                                  | 请输入来自 Convai 仪表板的 Character ID                               |
| 场景中没有 `ConvaiPlayer` 找到              | 缺少玩家组件                                                                                                  | 运行 **GameObject > Convai > Setup Required Components**       |

#### 警告——建议

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

| 警告                     | 原因                                                                                                       | 修复方法                                                |
| ---------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| API key not configured | `ConvaiSettings.HasApiKey` 返回 false                                                                      | 打开 **Convai > Settings > Credentials** 并输入你的 API 密钥 |
| 视频模式已启用，但未找到视觉源        | 房间的 `ConvaiRoomManager` 层级中没有 `IVisionPublisher` 组件，也没有 `IVisionFrameSource` 组件，或者两者都没有，而房间的有效连接类型是 `视频` | 添加一个视觉发布器和一个帧源组件，或者切换到 `音频` 模式                      |

验证器只根据 **API key not configured** 来自 `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] 启动成功` — SDK 已初始化所有内部服务
* [ ] `[RoomConnectionRuntimeAdapter] 房间连接成功（模式=create）。` — 房间已连接
* [ ] 如果存在聊天记录 UI，它会在对话开始后开始显示消息——成功连接时它不会记录任何内容，因此请关注 UI 本身而不是 Console
* [ ] 角色 `IsCharacterReady` 变为 `是` 在 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 密钥无效或缺失；网络问题                           | 在 **Convai > Settings > Credentials**中验证你的 API 密钥。检查防火墙规则是否允许到 `live.convai.com`.                     |
| 聊天记录 UI 不显示任何消息                     | 所需的 UI 引用未分配到 `ChatTranscriptUI`           | 检查 Console 中的 `chatContainer 未分配 - 消息将不会显示` 或 `scrollRect 未分配 - 自动滚动将无法工作`，并在 Inspector 中分配缺失的引用。     |
| 角色 `IsCharacterReady` 保持 `否`        | 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`
* 场景验证器和 Troubleshooter 都报告零错误
* 一个能够连接、变为就绪并响应语音输入的角色

### 下一步

继续入门路径以配置输入模式、音频和 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.