> 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-unreal-engine-plugin/getting-started/validate-your-setup.md).

# 验证你的设置

通过插件、组件、音频和 API 密钥检查清单，确认你的 Convai Unreal Engine 设置在添加功能之前已正常工作。

在继续添加功能之前，请使用此页面确认 Convai 设置的各个部分均正常运行。按顺序完成每个部分的检查。任何步骤失败通常都指向一个具体问题，且有明确的解决方法。

### 插件检查

| 检查项     | 验证方法                                                  |
| ------- | ----------------------------------------------------- |
| 插件已启用   | 前往 **编辑 > 插件**，搜索 `Convai`，并确认 **已启用** 复选框已勾选。        |
| 工具栏图标可见 | 插件加载后，Convai 图标会出现在 Unreal Editor 工具栏中。               |
| 无加载错误   | 编辑器启动时， **输出日志** 中没有涉及 `Convai` 或 `AudioCapture` 的错误。 |

### API 密钥检查

| 检查项   | 验证方法                                                                 |
| ----- | -------------------------------------------------------------------- |
| 已登录   | 打开 Convai 编辑器窗口（点击工具栏中的 Convai 图标），确认显示了你的账户详情。                      |
| 密钥已存储 | `UConvaiSettings.API_Key` 已填写，可在以下位置查看： **编辑 > 项目设置 > 插件 > Convai**. |

如果尚未登录，请参阅 [配置 API 密钥](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md).

### 组件检查

| 检查项                    | 验证方法                                                           |
| ---------------------- | -------------------------------------------------------------- |
| 角色具有 Convai 聊天机器人组件    | 打开角色蓝图，确认 `UConvaiChatbotComponent` 出现在 **组件** 面板中。            |
| 角色 ID 已设置              | 选择 **Convai 聊天机器人** 组件，确认 **角色 ID** 字段不为空，且与控制面板中的某个角色匹配。      |
| 玩家 Pawn 具有 Convai 玩家组件 | 打开玩家 Pawn 蓝图，确认 `UConvaiPlayerComponent` 出现在 **组件** 面板中。       |
| 已添加面部同步组件（如果使用唇形同步）    | 确认 `UConvaiFaceSyncComponent` 已添加到角色蓝图中，且 **唇形同步模式** 适合你的骨骼绑定。 |

### 音频检查

| 检查项            | 验证方法                                                                                                                             |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| 麦克风可用          | 在游玩模式下按 **F10** 打开设置面板，然后查看并测试可用的麦克风设备。也可以在运行时调用 `GetAvailableCaptureDeviceNames()` （位于 `UConvaiPlayerComponent` 中），并确认返回的列表不为空。 |
| 默认设备可以打开       | 进入游玩模式，触发按键通话或启用免提模式后，确认 `GetIsStreaming()` 返回 `true` 。                                                                          |
| 已授予 Android 权限 | 在 Android 上，确认在开始对话前已请求并获得 `android.permission.RECORD_AUDIO` 权限。                                                                 |

### 对话检查

所有其他检查通过后，再执行此检查。

{% stepper %}
{% step %}

#### 进入游玩模式

点击 Unreal Editor 工具栏中的 **游玩** 按钮。
{% endstep %}

{% step %}

#### 开始对话

按住按键通话键（默认为 **T**），说一句简短的话，然后松开。也可以在聊天控件中输入消息并按 **回车键**.
{% endstep %}

{% step %}

#### 观察角色状态

角色说话时， `GetIsTalking()` （“正在说话”）位于 `UConvaiChatbotComponent` 中，返回 `true`。会话处于活动状态时， `IsInConversation()` 中，返回 `true`.

在蓝图中添加 **打印字符串** 节点并将其连接到这些函数，以便在视口中观察状态变化。 `IsListening()` 和 `IsProcessing()` 在 Blueprint 中可用，但目前在插件源代码中返回 `false` 。
{% endstep %}

{% step %}

#### 确认音频输出

角色会说出可听见的回应。如果已配置口型同步，角色的嘴部会随语音同步动作。
{% endstep %}
{% endstepper %}

{% hint style="success" %}
验证通过后，角色会以音频回应，并在已配置的情况下启用口型同步。接下来请参阅各项功能页面，了解如何添加动作、情绪、动态上下文及其他功能。
{% endhint %}

### 常见故障点

#### 角色完全没有回应

**症状：** 角色始终不对语音或文本输入生成回应。

**原因：** 未设置 API 密钥，或缺少 Character ID。

**解决方法：** 请参阅 [配置 API 密钥](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md)；确认 Chatbot 组件上的 **Character ID** 字段。

**验证：** 进入 Play 模式并发送一段简短语句。角色会说出可听见的回应。

#### 角色没有音频

**症状：** 角色似乎正在处理输入，但没有语音音频输出。

**原因：** 音频输出设备问题，或会话尚未启动。

**解决方法：** 确认 Chatbot 组件上的 `bAutoInitializeSession` 设置为 `true` ，或者手动调用 `StartSession()` 。

**验证：** `GetIsTalking()` 在角色回应时会返回 `true` 。

#### 角色听不到玩家

**症状：** 角色始终不会对麦克风输入作出反应。

**原因：** 未采集麦克风音频，或缺少 Player 组件。

**解决方法：** 确认 `UConvaiPlayerComponent` 已添加到 pawn 上；请参阅 [配置麦克风](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-the-microphone.md).

**验证：** `GetIsStreaming()` 会 `true` 在按下通话键或 VAD 激活后返回此值。

#### 口型同步不播放

**症状：** 音频正常播放，但角色的嘴巴没有动作。

**原因：** 缺少 Face Sync 组件，或口型同步模式设置错误。

**修复方法：** 添加 `UConvaiFaceSyncComponent` 并为你的绑定设置正确的 `LipSyncMode` 。

**验证：** 进入 Play 模式，确认角色说话时嘴巴会动。

#### OnFailureEvent 触发

**症状：** 在对话期间， `OnFailureEvent` 委托会触发。

**原因：** 网络错误或 Character ID 无效。

**修复方法：** 查看 **输出日志** 了解详情；检查网络连接和 Character ID。

**验证：** 修复报告中的错误后重试。

### 后续步骤

{% content-ref url="/pages/ddab80eff30a95a57bb3cec04bc4566233e30263" %}
[配置麦克风](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-the-microphone.md)
{% endcontent-ref %}

{% content-ref url="/pages/2f681ae01ba11fe882d6b331cca0444e0a06402d" %}
[配置角色音频](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-character-audio.md)
{% endcontent-ref %}

{% content-ref url="/pages/9b983ed32e78e3fecceef1f1ca84663abe05edca" %}
[配置对话输入](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-conversation-input.md)
{% endcontent-ref %}

{% content-ref url="/pages/16dba40249f8c38f0e33f50c10a68569851148b6" %}
[添加聊天 UI](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/add-the-chat-ui.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-unreal-engine-plugin/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.
