> 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/installation-and-plugin-issues.md).

# 安装和插件问题

修复 Convai Unreal Engine 插件中的插件未找到错误、模块加载失败、仅 Blueprint 项目限制和 Android 打包错误。

使用此页面解决安装过程中出现的问题，或插件无法在 Unreal 编辑器中加载的问题。插件加载后出现的问题（例如 API 密钥或音频错误）请参阅其他故障排除页面。

### 初步检查

调查具体症状之前，请先完成以下三项检查。这些检查可确认 Unreal 是否能够发现插件并加载运行时模块。

{% stepper %}
{% step %}

#### 确认插件是否显示在 Plugins 列表中

打开 **编辑 > 插件** 并搜索 `Convai`。插件条目必须显示且处于启用状态（复选框已勾选）。如果未显示，说明文件夹结构不正确——请参阅 [插件未显示在 Plugins 列表中](#plugin-does-not-appear-in-the-plugins-list).
{% endstep %}

{% step %}

#### 在输出日志中检查 LogConvai 条目

打开 **窗口 > 输出日志** 并在搜索栏中输入 `LogConvai` 。原生库加载失败时会显示 `Failed to load %s from %s`。如果未出现任何 Convai 日志类别，Unreal 可能没有发现该插件。
{% endstep %}

{% step %}

#### 检查插件文件夹结构

对于项目级安装，插件根目录必须位于 `<YourProject>/Plugins/Convai/` 并且必须包含 `ConvAI.uplugin`。对于引擎级安装，插件根目录位于引擎的 `Engine/Plugins/Marketplace/Convai/` 文件夹下。
{% endstep %}
{% endstepper %}

### 插件未显示在 Plugins 列表中

**症状：** 将插件文件夹复制到项目或引擎后，Convai 条目未显示在 **编辑 > 插件**.

**原因 — 安装位置或文件夹结构不正确：** 解压后的文件夹中，插件根目录下没有 `ConvAI.uplugin` ，或者该文件夹被放在 Unreal 不会扫描的位置。

**解决方法：** 将解压后的插件文件夹移至以下任一受支持的位置，然后重启 Unreal 编辑器：

| 安装类型  | 文件夹                                                 |
| ----- | --------------------------------------------------- |
| 项目级安装 | `<YourProject>/Plugins/Convai/`                     |
| 引擎级安装 | `<UnrealEngine>/Engine/Plugins/Marketplace/Convai/` |

所选文件夹的根目录下必须包含 `ConvAI.uplugin` 。

**验证：** 打开 **编辑 > 插件**，搜索 `Convai`，并确认该条目已显示。如果尚未启用，请启用它，然后在提示时重启编辑器。

***

**原因 — Fab 或 Marketplace 安装尚未生效：** 如果插件是通过 [Fab](https://www.fab.com/listings/ba3145af-d2ef-434a-8bc3-f3fa1dfe7d5c)获取的，Epic Games Launcher 必须先将其安装到引擎中，编辑器才能检测到它。

**修复方法：** 打开 Epic Games Launcher，前往“库”，找到 Convai 插件条目，然后点击 **安装到引擎** ，并选择你正在使用的引擎版本。

**验证：** 重新启动 Unreal Editor。插件应该会显示在 **编辑 > 插件** 下的 **运行时** 类别中。

### 插件已启用，但编辑器无法正常重启

**症状：** 启用 Convai 插件并点击 **立即重启**后，编辑器崩溃，或在重启时显示编译对话框。

**原因 — C++ 项目需要重新编译：** 添加项目级源代码插件时，Unreal Engine 可能会重新编译项目代码。如果编译失败，编辑器将无法启动。

**修复方法：** 在 Visual Studio（或你配置的 IDE）中打开项目，选择 **生成 > 生成解决方案**，解决所有编译错误，然后重新启动编辑器。

**验证：** 编辑器能够打开，且不会显示编译对话框；编辑蓝图时，Convai 组件会显示在 **添加组件** 菜单中。

### 仅蓝图项目无法加载插件

**症状：** 插件已正确安装，但编辑器在重启时崩溃，或显示无法编译模块的对话框。你使用的是没有 C++ 源文件的仅蓝图项目。

**原因：** 项目级源代码插件可能需要 Unreal Build Tool 编译诸如 `Convai`, `ConvaiEditor`和 `ConvaiVisionBase`等模块。仅蓝图项目没有生成的 C++ 目标，因此 Unreal 无法编译项目级源代码插件。

{% hint style="warning" %}
仅蓝图项目应通过 Fab 或引擎级安装方式安装 Convai 插件。只有项目具备 C++ 构建目标时，才使用项目级安装方式。
{% endhint %}

**修复方法 — 选项 A（推荐）：转换为 C++ 项目**

在 Unreal Editor 中，选择 **文件 > 新建 C++ 类**，接受默认的 `None` 父类和默认文件名，然后点击 **创建类**。这会生成项目文件并设置构建环境。IDE 打开后，生成解决方案，然后重新启动编辑器。

**修复方法 — 选项 B：引擎级安装**

将插件安装到引擎目录，而不是项目目录。将插件文件夹放在：

```
C:\Program Files\Epic Games\UE_5.x\Engine\Plugins\Marketplace\Convai\
```

将 `5.x` 替换为你的引擎版本。引擎已具备构建环境，因此引擎级插件无需按项目单独编译。

**验证：** 构建完成后，编辑器可以正常重启。Convai 组件会显示在 **添加组件** 菜单中。

### `ConvaiEditor` 模块不可用

**症状：** 在 Unreal Engine 5.1 或更早版本中，Convai 编辑器窗口不会显示。输出日志中会显示 `ConvaiEditor: Editor UI disabled - requires UE 5.2 or later`.

**原因：**  `ConvaiEditor`  模块需要使用属性绑定编辑器功能，而 UE 5.1 及更早版本不提供此功能。该模块在这些引擎版本中会有意禁用。

**解决方法：** 升级到 Unreal Engine 5.2 或更高版本以使用 Convai 编辑器窗口。在 UE 5.1 及更早版本中，可通过在 `API_Key` 中 `Config/DefaultEngine.ini` 的 `[/Script/Convai.ConvaiSettings]` 节下设置 API 密钥。

**验证：** 在配置文件中设置密钥后，打开 **编辑 > 项目设置 > 插件 > Convai** 并确认 `API Key` 字段显示你设置的值。

插件版本 <code class="expression">space.vars.unreal\_plugin\_version</code> 支持从 5.0 起的所有 Unreal Engine 5.x 版本； `ConvaiEditor` 是唯一需要 5.2 或更高版本的组件。

### `AudioCapture` 插件依赖缺失

**症状：** 编辑器显示一条错误，指出缺少 `AudioCapture` 模块，或者插件因依赖错误而无法加载。

**原因：**  `AudioCapture`  引擎插件是必需的依赖项。它可能已在项目的插件配置中被禁用。

**解决方法：** 打开 **编辑 > 插件**，搜索 `Audio Capture`，并启用它。重启编辑器。

**验证：** Convai 插件加载时没有错误。检查启动时的输出日志，查看是否有 `LogConvai` 消息——不应出现模块缺失错误。

### 插件在 Windows 上可以加载，但在 Android 上无法加载

**症状：** 插件在 Windows 编辑器和 Windows 打包版本中可以正常工作，但在打包 Android 目标时无法加载或导致错误。

**原因 — 缺少 Android SDK 或 NDK 配置：** 如果未配置 Android NDK 或 SDK 路径，或者项目中禁用了 `AndroidPermission` 插件依赖项，则可能导致打包失败。

**修复方法：**

1. 确认已在 **编辑 > 项目设置 > 平台 > Android SDK**.
2. 中设置 Android NDK 和 SDK 路径。 **打开**，搜索 `Android Permission`，然后启用它。
3. 为 Android 目标重新构建项目。

**验证：** 打包日志顺利完成，且没有提示找不到 `Convai` 或 `ConvaiVisionBase`.

***

**原因 — APK 中缺少原生库：** 该插件的 Android APL 会将 `libconvai_client.so`, `、`和 `libwebrtc.jar` 复制到 Android 构建中。如果自定义打包步骤移除了这些文件，设备上的实时连接可能会失败。

**修复方法：** 插件会通过其 `Convai_AndroidAPL.xml`自动处理此问题。如果遇到原生库加载失败，请确认：

1. 插件的 `Convai_AndroidAPL.xml` 文件位于 `Plugins/Convai/Source/Convai/` ，且未被移除或修改。
2. ProGuard 或 R8 配置没有覆盖插件插入的保留规则。APL 包含针对 WebRTC JNI 类和原生方法的规则：

```proguard
-keepattributes Signature
-dontskipnonpubliclibraryclassmembers
-keep class **.jni_zero.** { *; }
-keep class **.webrtc.** { *; }
-keepclasseswithmembernames class * {
    native <methods>;
}
```

**验证：** 运行 `adb shell ls /data/app/<your.package.name>/lib/arm64/` 安装 APK 后。你应该会看到 `libconvai_client.so` 和 `libconvai_http_helper.so` 列在其中。

{% hint style="danger" %}
删除 `Intermediate/` 和 `Binaries/` 文件夹会强制执行完整重新编译，并可能解决损坏的构建状态问题，但这应作为最后手段。删除这些文件夹前，请关闭编辑器和 IDE，因为打开的文件句柄可能导致删除失败，或使项目处于未完全清理的状态。重新启动编辑器前，请先从 IDE 重新构建。
{% endhint %}

### 后续步骤

{% content-ref url="/pages/f1b3d71c37ea498f3d6d84fdf60594d3020ae6bf" %}
[连接和 API 密钥问题](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/connection-and-api-key-issues.md)
{% endcontent-ref %}

{% 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/installation-and-plugin-issues.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.
