> 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/connection-and-api-key-issues.md).

# 连接和 API 密钥问题

修复 Convai Unreal Engine 插件中的身份验证失败、缺少 API 密钥错误、会话超时和防火墙问题。

请使用此页面解决 Convai 插件无法与 Convai 进行身份验证或建立会话的问题。安装问题请参见 [安装和插件问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/installation-and-plugin-issues.md).

### 项目设置中的 API 密钥字段为空

**症状：** **Edit > Project Settings > Plugins > Convai** 显示 `API 密钥` 字段为空，并且角色在运行时没有响应。

**原因——API 密钥未通过 Convai 编辑器窗口保存：** 该 `API_Key` 字段在 `UConvaiSettings` 由 Convai 编辑器窗口自动管理。在项目设置面板中手动设置它不会产生任何效果。

**修复：** 打开 Convai 编辑器窗口（**Window > Open Convai Editor**），使用您的 Convai 账户登录，窗口会将密钥写入 `Config/DefaultEngine.ini` ，自动。

**验证：** 登录后，打开 **Edit > Project Settings > Plugins > Convai** 并确认 `API 密钥` 现在包含您的密钥。该密钥存储在 `[/Script/Convai.ConvaiSettings]` 部分的 `Config/DefaultEngine.ini`.

***

**原因——UE 5.1 或更早版本（ConvaiEditor 已禁用）：** 在 UE 5.1 及更早版本中，无法使用 Convai 编辑器窗口，因此不会运行自动写入密钥的流程。

**修复：** 直接将密钥添加到 `Config/DefaultEngine.ini`:

{% code title="Config/DefaultEngine.ini" %}

```ini
[/Script/Convai.ConvaiSettings]
API_Key=YOUR_API_KEY_HERE
```

{% endcode %}

**验证：** 启动编辑器并打开 **Edit > Project Settings > Plugins > Convai**.  `API 密钥` 字段应显示您设置的值。

### 角色没有响应——没有音频或文本输出

**症状：** 进入播放模式后，玩家说话或发送文本，但角色没有任何响应。输出日志在以下项下显示连接错误： `ConvaiChatbotComponentLog`.

**原因——无效的 API 密钥、无效的 `CharacterID`，或被阻止的连接：** 连接管理器无法创建可用会话。会话设置失败时，插件会记录以下消息之一：

* `角色 [%s]：无法建立连接——请检查您的 API 密钥、网络连接，以及 CharacterID 是否有效`
* `角色 [%s]：无法初始化会话代理——提供的 ConnectionInterface 可能无效`

**修复：** 登录到 [convai.com](https://convai.com)，进入您的账户并复制当前 API 密钥。通过 Convai 编辑器窗口重新输入，以便将其写入配置文件。然后确认 `CharacterID` 在 `Convai Chatbot` 组件与 Convai 控制面板中的角色 ID 一致。

**验证：** 进入播放模式并调用 `获取聊天机器人连接状态` 在 `Convai Chatbot` 组件。状态应变为 `已连接`.

***

**原因—— `CharacterID` 未在聊天机器人组件上设置：** `UConvaiChatbotComponent` 需要一个有效的 `CharacterID` 以从 Convai 加载角色数据。空的或错误的 ID 会导致连接尝试失败。

**修复：** 在关卡或 Blueprint 编辑器中选择角色 Actor。在 **详情** 面板，找到 `Convai Chatbot` 组件中设置 `CharacterID` 为 Convai 控制面板中的角色 ID。

**验证：** 将 `在角色数据加载完成时` 事件绑定到 `Convai Chatbot` 组件上，或检查 `CharacterName` 在开始播放后是否已填充。

{% hint style="warning" %}
该 `CharacterID` 字段区分大小写，必须与 Convai 控制面板上显示的 ID 完全一致。ID 不匹配会产生相同的 `无法建立连接` 错误，与无效的 API 密钥相同。
{% endhint %}

### 会话不会自动启动

**症状：** 该 `Convai Chatbot` 组件已在场景中，但在显式调用之前不会建立会话，即使预期应自动启动也是如此。

**原因—— `bAutoInitializeSession` 已禁用：** 该 `bAutoInitializeSession` 上的属性 `UConvaiChatbotComponent` 控制组件是否会在以下时自动建立会话： `BeginPlay`。禁用后，必须通过 Blueprint 或 C++ 代码启动会话。

**修复：** 选择 `Convai Chatbot` 角色 Blueprint 中的组件，打开 **详情** 面板，并启用 `bAutoInitializeSession`。如果需要手动控制，请调用 `开始会话` ，从相应的 Blueprint 事件中调用。

**验证：** 进入播放模式并调用 `获取聊天机器人连接状态`。使用有效密钥并启用 `CharacterID`，状态应从 `连接中` 到 `已连接` 而无需手动 `开始会话` 调用。

### 在角色响应前会话超时

**症状：** 会话已启动，但角色始终未准备就绪。输出日志显示：

```
在 %.0fs 内未收到 bot-ready；停止 client-ready 握手
```

**原因—— `bot-ready` 已超过超时：** 插件建立连接后，会等待 Convai 发送 `bot-ready` 信号。默认超时时间为 `45.0` 秒，通过 `ClientReadyTimeoutSecs` 连接参数设置。如果信号未到达，插件将停止 client-ready 握手。

**修复：**

1. 确认 `CharacterID` 有效并已发布到 Convai 控制面板。
2. 检查机器是否可以访问 `https://realtime-api.convai.com/connect`.
3. 重新进入播放模式以创建新会话。

**验证：** 再次进入播放模式。如果超时是暂时性的，会话应在播放开始后的几秒内建立。

### 网络请求失败——防火墙或代理环境

**症状：** 插件已加载且 API 密钥有效，但所有请求都超时，或在输出日志中因网络错误而失败。

**原因：** 到 Convai 的出站连接可能被企业防火墙、VPN 或代理阻止。源代码在运行时和编辑器诊断中使用以下 Convai 端点：

| 端点                                        | 协议    | 端口  | 作用                  |
| ----------------------------------------- | ----- | --- | ------------------- |
| `https://realtime-api.convai.com/connect` | HTTPS | 443 | 实时会话连接              |
| `https://api.convai.com`                  | HTTPS | 443 | Convai API 请求和编辑器诊断 |

**修复：** 确认端口上的出站 HTTPS 流量 `443` 可被这两个域名允许。如果您的组织需要代理，请通过常用网络工具验证 Unreal Engine 的 HTTP 流量。

**验证：** 调整网络设置后，进入播放模式并调用 `获取聊天机器人连接状态`。状态应变为 `已连接`.

{% hint style="warning" %}
不要提交 `Config/DefaultEngine.ini` 到公共仓库，如果其中包含您的 API 密钥。添加 `Config/DefaultEngine.ini` 到 `.gitignore`，或者使用特定于环境的配置文件，以避免将密钥纳入版本控制。
{% endhint %}

### 在 Blueprint 中处理连接错误

该 `Convai Chatbot` 组件提供可供 Blueprint 调用的状态节点和可分配的 Blueprint 事件，帮助您在运行时处理失败。

| 事件             | 在以下情况触发：          | 用途                            |
| -------------- | ----------------- | ----------------------------- |
| **失败时**        | 发生任何连接或会话错误时      | 显示错误消息、禁用对话 UI 或重试逻辑          |
| **在角色数据加载完成时** | 角色元数据加载完成并报告 `成功` | 确认身份验证成功并 `CharacterName` 已填充 |
| **中断时**        | 当前语音轮次被中断         | 更新 UI 以显示角色已停止说话              |

要绑定到 **失败时** 在 Blueprint 中：

1. 选择 `Convai Chatbot` 角色 Blueprint 中的组件。
2. 在 **详情** 面板，找到 **事件** 部分，并点击 **+** 旁边的按钮 **失败时**.
3. 一个新的事件节点会添加到事件图中。将其连接到您的错误处理逻辑——例如，打印到屏幕上或禁用按键说话按钮。

**失败时** 会在没有参数的情况下触发。要查看错误详情，请读取以下项下的输出日志： `ConvaiChatbotComponentLog` 在事件触发时——失败事件之前紧接着的日志条目包含错误字符串。

完整的诊断参考请参见 [诊断和日志导出](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/diagnostics-and-log-export.md).

### 快速参考

| 症状                         | 要检查的日志类别                                   | 可能原因                                 |
| -------------------------- | ------------------------------------------ | ------------------------------------ |
| 项目设置中的 API 密钥字段为空          | `LogConvaiEditor` 或 `LogTemp`              | 密钥未通过 Convai 编辑器窗口写入                 |
| 角色没有响应，没有日志条目              | `ConvaiChatbotComponentLog`                | `CharacterID` 未设置或会话未启动              |
| `无法建立连接`                   | `ConvaiConnectionManagerLog`               | 无效的 API 密钥、无效的 `CharacterID`，或被阻止的网络 |
| `无法初始化会话代理`                | `ConvaiConnectionManagerLog`               | 会话代理无法初始化                            |
| `在 %.0fs 内未收到 bot-ready`   | `ConvaiSubsystemLog`                       | client-ready 握手超时                    |
| 所有请求都超时                    | `LogConvai` 或 `ConvaiConnectionManagerLog` | 出站 HTTPS 流量被阻止                       |
| 会话可手动启动，但不会在 BeginPlay 时启动 | `ConvaiChatbotComponentLog`                | `bAutoInitializeSession` 已禁用         |
| 密钥有效，角色已设置，但没有响应           | `ConvaiSubsystemLog`                       | 连接已建立，但会话未就绪                         |

### 下一步

{% content-ref url="/pages/162be7d038eafe64dac814c14bb82a2b2ad8b2e3" %}
[音频和麦克风问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/audio-and-microphone-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 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/connection-and-api-key-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.