> 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/troubleshooting.md).

# 故障排查

本节涵盖插件级别出现的问题：安装、身份验证、会话启动、麦克风采集、基础唇形同步设置以及诊断。如果 Convai Unreal Engine 插件已成功连接，但某个功能表现异常，请先查看该功能的故障排查页面。

{% hint style="info" %}
**不知道从哪里开始？** 打开 Unreal Editor 输出日志（**窗口 > 输出日志**）并查找第一个 Convai 错误或警告。使用日志类别作为路径： `LogConvai` 或 `LogConvaiEditor` → 安装和插件问题； `ConvaiConnectionManagerLog`, `ConvaiSubsystemLog`，或 `ConvaiChatbotComponentLog` → 连接和 API 密钥问题； `ConvaiAudioLog`, `ConvaiAudioStreamerLog`，或 `ConvaiPlayerLog` → 音频和麦克风问题； `ConvaiFaceSyncLog` → 唇形同步和动画问题。如果没有出现任何 Convai 类别，请从安装和插件问题开始。
{% endhint %}

### 故障排查类别

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>安装和插件问题</strong><br>找不到插件、模块加载失败、仅蓝图项目的限制，以及 Android 打包错误。</td><td><a href="/pages/34f887e298987790d23b0121952c3cb99a98019f">/pages/34f887e298987790d23b0121952c3cb99a98019f</a></td></tr><tr><td><strong>连接和 API 密钥问题</strong><br>身份验证失败、API 密钥缺失、会话超时错误以及防火墙配置。</td><td><a href="/pages/f1b3d71c37ea498f3d6d84fdf60594d3020ae6bf">/pages/f1b3d71c37ea498f3d6d84fdf60594d3020ae6bf</a></td></tr><tr><td><strong>音频和麦克风问题</strong><br>没有音频输入、采集设备错误、Android 权限失败以及音频播放错误。</td><td><a href="/pages/162be7d038eafe64dac814c14bb82a2b2ad8b2e3">/pages/162be7d038eafe64dac814c14bb82a2b2ad8b2e3</a></td></tr><tr><td><strong>唇形同步和动画问题</strong><br>没有口部动作、混合形状曲线错误、帧不足，以及打包构建中的动画失败。</td><td><a href="/pages/aade7c9244e67877d732705a3f1075d5958e0a22">/pages/aade7c9244e67877d732705a3f1075d5958e0a22</a></td></tr><tr><td><strong>诊断和日志导出</strong><br>日志类别、详细程度控制、配置默认值、蓝图诊断节点，以及用于支持的日志文件导出。</td><td><a href="/pages/76a35097e5aafc7db6e701235cba4c330c02ad3a">/pages/76a35097e5aafc7db6e701235cba4c330c02ad3a</a></td></tr><tr><td><strong>使用 Convai 调试覆盖层检查角色</strong><br>查看角色在运行时实际知道什么：其上下文状态、事实、周围语句和动作队列。</td><td><a href="/pages/1ed7761971047e9936d8725a20f0087277c2bd4b">/pages/1ed7761971047e9936d8725a20f0087277c2bd4b</a></td></tr><tr><td><strong>Convai Debug Overlay 参考</strong><br>覆盖层响应的每个面板、图标和按键，以及控制它的设置。</td><td><a href="/pages/61a7a55de479c504fcaf2d229f7ccf1970d311e4">/pages/61a7a55de479c504fcaf2d229f7ccf1970d311e4</a></td></tr></tbody></table>

### 功能特定故障排查

插件成功连接后出现的问题——即某个特定功能表现异常——都记录在各自功能的章节中。

| 功能    | 故障排查页面                                                                                                                                 |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 角色动作  | [排查角色动作问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/character-actions/troubleshoot-character-actions.md) |
| 动态上下文 | [动态上下文故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/dynamic-context/troubleshoot-dynamic-context.md)    |
| 情绪    | [情绪故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/emotion/troubleshoot-emotion.md)                       |
| 长期记忆  | [长期记忆故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/long-term-memory/troubleshoot-long-term-memory.md)   |
| 叙事设计  | [叙事设计故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/narrative-design/troubleshoot-narrative-design.md)   |
| 场景元数据 | [场景元数据故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/scene-metadata/troubleshoot-scene-metadata.md)      |
| 视觉    | [视觉故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/vision/troubleshoot-vision.md)                         |
| 注视注意  | [凝视注意力故障排除](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/gaze-attention/troubleshoot-gaze-attention.md)      |
| 唇形同步  | [唇形同步故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/features/lip-sync/troubleshoot-lip-sync.md)                   |

### 下一步

当仅凭一条错误消息难以诊断问题时，请为相关类别启用详细日志记录并检查 Output Log。诊断页面还说明了 Unreal 将日志写入何处，以及如何从 Convai 编辑器窗口创建可共享的支持包。

{% content-ref url="/pages/76a35097e5aafc7db6e701235cba4c330c02ad3a" %}
[诊断和日志导出](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/diagnostics-and-log-export.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-unreal-engine-plugin/troubleshooting.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.