> 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 插件中的安装、API 密钥、音频、口型同步和连接问题的修复方法，以及日志导出和诊断指南。

本节介绍插件层面出现的问题：安装、身份验证、会话启动、麦克风采集、唇形同步的常规设置以及诊断。如果 Convai Unreal Engine 插件已成功连接，但某项功能运行异常，请先查看该功能对应的故障排查页面。

{% hint style="info" %}
**不确定从哪里开始？** 打开 Unreal Editor 输出日志（**Window > Output Log**），并查找第一条 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="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/installation-and-plugin-issues.md">安装和插件问题</a></td></tr><tr><td><strong>连接和 API 密钥问题</strong><br>身份验证失败、缺少 API 密钥、会话超时错误，以及防火墙配置。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/connection-and-api-key-issues.md">连接和 API 密钥问题</a></td></tr><tr><td><strong>音频和麦克风问题</strong><br>没有音频输入、采集设备错误、Android 权限失败，以及音频播放错误。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/audio-and-microphone-issues.md">音频和麦克风问题</a></td></tr><tr><td><strong>唇形同步和动画问题</strong><br>嘴部没有动作、混合形状曲线错误、帧数据不足，以及打包版本中的动画故障。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/lip-sync-and-animation-issues.md">口型同步和动画问题</a></td></tr><tr><td><strong>诊断和日志导出</strong><br>日志类别、详细程度控制、配置默认值、蓝图诊断节点，以及供支持人员使用的日志文件导出。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/diagnostics-and-log-export.md">诊断和日志导出</a></td></tr><tr><td><strong>使用 Convai 调试叠加层检查角色</strong><br>查看角色在运行时实际掌握的信息：其上下文状态、事实、周围环境描述句以及动作队列。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay.md">使用 Convai 调试覆盖层检查角色</a></td></tr><tr><td><strong>Convai 调试叠加层参考</strong><br>叠加层中的每个面板、图标及其响应的按键，以及控制叠加层的设置。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay-reference.md">Convai 调试覆盖层参考</a></td></tr></tbody></table>

### 特定功能的故障排查

插件成功连接后出现的问题（即特定功能运行异常）记录在各功能对应的章节中。

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

### 后续步骤

如果难以根据单条错误消息诊断问题，请为相关类别启用详细日志记录并检查输出日志。诊断页面还会说明 Unreal 将日志写入何处，以及如何在 Convai 编辑器窗口中创建可共享的支持包。

{% content-ref url="/pages/76a35097e5aafc7db6e701235cba4c330c02ad3a" %}
[诊断和日志导出](https://docs.convai.com/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 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/troubleshooting.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.
