> 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).

# 安装和插件问题

使用此页面来解决安装期间或插件在 Unreal 编辑器中无法加载时出现的问题。插件加载后出现的问题——例如 API 密钥或音频错误——请参见其他故障排除页面。

### 第一步检查

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

{% stepper %}
{% step %}

#### 确认插件出现在 Plugins 列表中

打开 **Edit > Plugins** 并搜索 `Convai`。插件条目必须出现并已启用（复选框已勾选）。如果未出现，则文件夹结构不正确——请参见 [插件未出现在 Plugins 列表中](#plugin-does-not-appear-in-the-plugins-list).
{% endstep %}

{% step %}

#### 检查 Output Log 中是否有 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 条目不会出现在 **Edit > Plugins**.

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

**修复：** 将解压后的插件文件夹移动到受支持的位置，然后重新启动 Unreal Editor：

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

所选文件夹必须包含 `ConvAI.uplugin` 位于其根目录。

**验证：** 打开 **Edit > Plugins**，搜索 `Convai`，并确认条目出现。如果尚未启用，请启用它，然后在提示时重新启动编辑器。

***

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

**修复：** 打开 Epic Games Launcher，进入你的 Library，找到 Convai 插件条目，并单击 **Install to Engine** ，以安装到你正在使用的引擎版本。

**验证：** 重新启动 Unreal Editor。插件应出现在 **Edit > Plugins** 在 **运行时** 类别下。

### 插件已启用，但编辑器未能正常重启

**症状：** 你启用 Convai 插件并单击 **Restart Now**，但编辑器崩溃或在重启时显示编译对话框。

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

**修复：** 在 Visual Studio（或你配置的 IDE）中打开项目，选择 **Build > Build Solution**，解决所有编译错误，然后再次启动编辑器。

**验证：** 编辑器打开时不会出现编译对话框，并且 Convai 组件会出现在 **添加组件** 菜单中，在编辑蓝图时可见。

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

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

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

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

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

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

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

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

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

Replace `5.x` 与你的引擎版本相匹配的位置。引擎本身已经具备构建环境，因此引擎级插件不需要按项目进行编译步骤。

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

### `ConvaiEditor` 模块不可用

**症状：** 在 Unreal Engine 5.1 或更早版本中，Convai 编辑器窗口不会出现。Output Log 显示 `ConvaiEditor：编辑器 UI 已禁用 - 需要 UE 5.2 或更高版本`.

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

**修复：** 升级到 Unreal Engine 5.2 或更高版本以使用 Convai 编辑器窗口。在 UE 5.1 及更早版本中，请通过设置手动配置 API 密钥 `API_Key` 在 `Config/DefaultEngine.ini` 在 `[/Script/Convai.ConvaiSettings]` 部分开始。

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

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

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

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

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

**修复：** 打开 **Edit > Plugins**，搜索 `Audio Capture`，并启用它。重新启动编辑器。

**验证：** Convai 插件可无错误加载。检查 Output Log 中是否有 `LogConvai` 启动消息——不应有缺失模块错误。

### 插件可在 Windows 上加载，但在 Android 上不能

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

**原因——缺少 Android SDK 或 NDK 配置：** 当未配置 Android NDK 或 SDK 路径，或者当 `AndroidPermission` 插件依赖在项目中被禁用时，可能会发生打包失败。

**修复：**

1. 确认 Android NDK 和 SDK 路径已在 **Edit > Project Settings > Platforms > Android SDK**.
2. 打开 **Edit > Plugins**，搜索 `Android Permission`，并启用它。
3. 为 Android 目标重新构建项目。

**验证：** 打包日志完成，且没有针对以下内容的模块未找到错误： `Convai` 或 `ConvaiVisionBase`.

***

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

**修复：** 这会由插件的 `Convai_AndroidAPL.xml`自动处理。如果你看到原生加载失败，请确认：

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

```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 密钥问题](/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" %}
[诊断和日志导出](/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:

```
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>
```

The question should be specific, self-contained, and written in natural language.
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.