> 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 建立会话的问题。安装问题请参阅 [安装和插件问题](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/installation-and-plugin-issues.md).

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

**症状：** **编辑 > 项目设置 > 插件 > Convai** 中的 `API 密钥` 字段为空，且角色在运行时没有响应。

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

**解决方法：** 打开 Convai 编辑器窗口（**窗口 > 打开 Convai 编辑器**），使用 Convai 账户登录，窗口会自动将密钥写入 `Config/DefaultEngine.ini` 。

**验证：** 登录后，打开 **编辑 > 项目设置 > 插件 > 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 %}

**验证：** 启动编辑器并打开 **编辑 > 项目设置 > 插件 > Convai**。 `API 密钥` 字段应显示你设置的值。

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

**症状：** 开始运行后，玩家说话或发送文本，但角色没有任何响应。输出日志中显示了以下日志类别的连接错误： `ConvaiChatbotComponentLog`.

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

* `Character [%s]: Failed to establish connection — check your API key, network connectivity, and that the CharacterID is valid`
* `Character [%s]: Failed to initialize session proxy — the provided ConnectionInterface may be invalid`

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

**验证：** 进入 Play 模式，并在 `Get Chatbot Connection State` 组件上调用 `Convai Chatbot` 。状态应变为 `Connected`.

***

**原因 — `CharacterID` 未在聊天机器人组件上设置：** `UConvaiChatbotComponent` 需要有效的 `CharacterID` ，才能从 Convai 加载角色数据。ID 为空或不正确会导致连接尝试失败。

**修复方法：** 在关卡或蓝图编辑器中选择角色 Actor。在 **细节** 面板中，找到 `Convai Chatbot` 组件并将 `CharacterID` 设置为 Convai 控制面板中的角色 ID。

**验证：** 绑定 `On Character Data Loaded` 事件（位于 `Convai Chatbot` 组件上），或检查 Play 开始后是否已填充 `CharacterName` 。

{% hint style="warning" %}
CharacterID `字段区分大小写，必须与 Convai 控制面板中显示的 ID 完全一致。ID 不匹配会产生与 API 密钥无效相同的` 错误： `Failed to establish connection` 。
{% endhint %}

### 会话未自动启动

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

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

**修复方法：** 在角色 Blueprint 中选择 `Convai Chatbot` 组件，打开 **细节** 面板，然后启用 `bAutoInitializeSession`。如果需要手动控制，请在相应的 Blueprint 事件中调用 `Start Session` 。

**验证：** 进入 Play 模式并调用 `Get Chatbot Connection State`。使用有效的密钥和 `CharacterID`时，状态应从 `Connecting` 变为 `Connected` ，无需手动调用 `Start Session` 。

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

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

```
bot-ready not received within %.0fs; stopping client-ready handshake
```

**原因 — `bot-ready` 信号超时：** 插件建立连接后，会等待 Convai 发送 `bot-ready` 信号。默认超时时间为 `45.0` 秒，由连接参数 `ClientReadyTimeoutSecs` 指定。如果未收到该信号，插件会停止客户端就绪握手。

**修复方法：**

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

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

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

**症状：** 插件已加载且 API 密钥有效，但所有请求均超时，或在 Output Log 中显示网络错误。

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

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

**修复方法：** 确认允许发往这两个域名的出站 HTTPS 流量通过端口  `443` 。如果您的组织要求使用代理，请使用常用的网络工具检查 Unreal Engine 的 HTTP 流量。

**验证：** 调整网络设置后，进入 Play 模式并调用  `Get Chatbot Connection State`。状态应变为  `Connected`.

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

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

该  `Convai Chatbot`  组件提供可从 Blueprint 调用的状态节点和可在 Blueprint 中绑定的事件，帮助您处理运行时故障。

| 事件                           | 触发时机                    | 用途                              |
| ---------------------------- | ----------------------- | ------------------------------- |
| **On Failure**               | 发生任何连接或会话错误时            | 显示错误消息、禁用对话界面或执行重试逻辑            |
| **On Character Data Loaded** | 角色元数据加载完成并报告  `Success` | 确认身份验证成功且  `CharacterName`  已填充 |
| **On Interrupted**           | 当前语音轮次被中断               | 更新界面，显示角色已停止说话                  |

要在 Blueprint 中绑定  **On Failure** ：

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

**失败时** 触发时不带参数。若要查看错误详情，请在事件触发时查看 `ConvaiChatbotComponentLog` 下的输出日志——失败事件前一条日志记录中包含错误字符串。

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

### 快速参考

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

### 后续步骤

{% content-ref url="/pages/162be7d038eafe64dac814c14bb82a2b2ad8b2e3" %}
[音频和麦克风问题](https://docs.convai.com/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" %}
[诊断和日志导出](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/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.
