> 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 角色，并在进入播放模式之前确认所需组件已存在。

进入 Play Mode 前，请使用 Convai Troubleshooter 和场景级验证器检查角色。两者回答的问题不同：Troubleshooter 会报告哪些问题会导致所选角色上的模块无法运行，而验证器会确认基本场景连接是否已就绪—— `ConvaiManager`, `ConvaiCharacter`, `ConvaiPlayer`，以及 Character ID 字段。请同时运行两者。

### 使用 Troubleshooter 检查角色

打开 **Convai > Troubleshooter**。窗口会加载当前选中的角色；或者，切换到 `ConvaiCharacter` 模式后，会列出场景中的所有 **This Scene** 。

对于选中的角色，Troubleshooter 会按模块逐行报告检查结果。每条结果都会显示严重程度；如果有可执行的操作，还会显示修复按钮、一个 **Show Me** 按钮（用于选中相关对象），或一个 **Open** 按钮（用于打开相关编辑器窗口）。进行更改后，请使用 **Re-check** 重新检查，或者使用 **Fix Everything That Can Be Fixed** 一次性应用所有一键修复。

并非每一行都提供相同的帮助。Actions 行带有可在窗口中应用的修复。具身模块对应的行——Gaze、Body Animation、Body Language、Emotion 以及具身设置本身——会报告检查结果，但不提供修复或定位按钮，因此需要在各模块自己的编辑器窗口中处理。只有当某个模块能提供与角色相关的信息时，才会显示对应行；因此，没有该模块的角色不会显示该模块的行。

Actions 适用于每个 `ConvaiCharacter`，因此，即使是刚完成连接、尚未添加其他模块的角色，也会显示 Actions 行。对于尚未配置任何动作的角色，该行仅提供信息：它表示角色会说话但不会执行动作，并不代表出了问题。

Troubleshooter 检查的是模块设置，而非场景的基础连接。缺少 `ConvaiManager` 或 Character ID 为空的问题，会由下方的场景验证器检测出来。

### 运行场景验证器

Scene Validator 会检查场景中是否缺少组件、必填字段是否为空，以及是否存在常见配置错误。开发过程中的任何阶段都可以运行，不必等到最后。

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

随后会弹出一个对话框，其中列出了 **Errors** （必须修复）、 **Warnings** （建议处理）以及 **Next Steps** （建议采取的操作）。

### 验证器检查项

#### Errors — 必须修复

这些问题会导致场景无法连接到 Convai。

| 错误                                    | 原因                                                                                                         | 解决方法                                                                                                |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| 场景中未找到 `ConvaiManager` SDK 尚未初始化      | 运行                                                                                                         | GameObject > Convai > Setup Required Components **GameObject > Convai > Setup Required Components** |
| 否 `ConvaiRoomManager` 在场景中找到          | 缺少房间连接组件                                                                                                   | GameObject > Convai > Setup Required Components **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 游戏对象                                                                    |
| `ConvaiCharacter` 没有 Character ID     | 必填字段为空                                                                                                     | 输入 Convai 控制面板中的 Character ID                                                                       |
| 否 `ConvaiPlayer` 在场景中找到               | 缺少 Player 组件                                                                                               | GameObject > Convai > Setup Required Components **GameObject > Convai > Setup Required Components** |

#### 警告 — 建议处理

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

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

验证器仅根据 **未配置 API 密钥** 从 `ConvaiSettings.HasApiKey` 得出；它不会检查 `ConvaiSettings.HasValidAuthConfig`，后者会考虑项目的 `AuthMode`。以 Auth Token 模式运行的项目无需 API 密钥，因此即使身份验证配置正确，也可能出现此警告。如果项目使用 Auth Token 模式，请将此警告视为预期情况，并在 [身份验证](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/authentication.md) 页面验证设置，而不要添加 API 密钥。

{% hint style="success" %}
当验证器显示错误和警告均为零时，场景即可进入播放模式。
{% endhint %}

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

验证器检查通过后，进入播放模式，并按顺序留意控制台中的以下日志行。

* [ ] `[ConvaiRuntime] Started successfully` — SDK 已初始化所有内部服务
* [ ] `[RoomConnectionRuntimeAdapter] Room connection succeeded (mode=create).` — 房间已连接
* [ ] 如果存在聊天记录 UI，它会在对话开始后显示消息——连接成功时不会记录任何日志，因此请查看 UI 本身，而不是控制台。
* [ ] 角色 `IsCharacterReady` 会在 `true` ，即 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] Started successfully` 未出现在控制台中 | `ConvaiManager` 缺失或启动失败                   | 请检查 `ConvaiManager` 是否位于场景中。查看控制台中更早出现的错误。                                                               |
| 房间始终无法连接 — 没有角色已连接的日志                           | API 密钥无效或缺失；存在网络问题                        | 在 **Convai > Settings > Credentials**中验证 API 密钥。检查防火墙规则，确保允许通过 WebSocket/HTTPS 连接到 `live.convai.com`.    |
| 聊天记录 UI 未显示消息                                   | 尚未为 `ChatTranscriptUI`                    | 分配必需的 UI 引用 `在控制台中查找` 或 `scrollRect is not assigned - auto-scroll will not work`，然后在 Inspector 中分配缺失的引用。 |
| 角色 `IsCharacterReady` 一直保持 `false`              | 角色 ID 错误，或该角色不存在于你的帐户中                    | 请确认角色 ID 与 Convai 控制面板中显示的内容完全一致。                                                                        |
| 麦克风无法开启——角色听不到任何声音                              | 已启用按键通话模式，且麦克风初始处于静音状态                    | 在 `ConvaiRoomManager`中，确认 **Mode** 为 `HandsFree`；如果使用按键通话模式，请按 **T** 。                                   |
| 角色语音正常播放，但 Blend Shape 不会动                      | `ConvaiLipSyncComponent` 未配置，或配置文件 ID 不匹配 | 将 `ConvaiLipSyncComponent` 添加到角色上。确认 `_lockedProfileId` 与角色的传输格式匹配。指定目标 `SkinnedMeshRenderer`。           |
| 示例场景中的材质呈粉色                                     | 渲染管线不匹配（内置渲染管线与 URP）                      | 通过以下菜单转换材质： **编辑 > 渲染 > 材质 > 将所有内置材质转换为 URP**，或者手动重新指定 URP 着色器。                                          |

### 设置完成

现在，你的场景中包含：

* 已安装并连接到 Convai 的 SDK，以及有效的 API 密钥
* 包含以下对象的场景： `ConvaiManager`, `ConvaiRoomManager`, `ConvaiCharacter`和 `ConvaiPlayer`
* 场景验证器和故障排查工具均未报告错误
* 能够连接并就绪，且能响应语音输入的角色

### 后续步骤

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

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

或者前往“功能”部分，为角色添加动作、情绪、长期记忆或视觉功能。

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

查看“核心概念”，深入了解会话生命周期和事件系统。

{% content-ref url="/pages/b20dffbec401e06e9fe4168f409ab42a87fa327b" %}
[核心概念](https://docs.convai.com/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.
