> 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 插件无法通过身份验证或与 Convai 建立会话的问题。安装问题请参见 [安装和插件问题](/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`无效，或连接被阻止：** 连接管理器无法创建可用会话。会话设置失败时，插件会记录以下消息之一：

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

**修复：** 登录 [convai.com](https://convai.com)，进入你的账户并复制当前 API 密钥。通过 Convai 编辑器窗口重新输入，它将被写入配置文件。然后确认 `CharacterID` 在 `Convai 聊天机器人` 组件与 Convai 仪表板中的角色 ID 相匹配。

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

***

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

**修复：** 在关卡或蓝图编辑器中选择角色 Actor。在 **详细信息** 面板中，找到 `Convai 聊天机器人` 组件并将 `CharacterID` 设置为 Convai 仪表板中该角色的 ID。

**验证：** 绑定 `On Character Data Loaded` 事件到 `Convai 聊天机器人` 组件，或检查在开始播放后 `CharacterName` 是否已填充。

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

### 会话未自动启动

**症状：** 该 `Convai 聊天机器人` 组件已在场景中，但直到显式调用之前不会建立会话，即使期望自动启动也是如此。

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

**修复：** 选择 `Convai 聊天机器人` 组件，在角色蓝图中打开 **详细信息** 面板，并启用 `bAutoInitializeSession`。如果需要手动控制，请从相应的蓝图事件调用 `Start Session` 。

**验证：** 进入播放模式并调用 `获取聊天机器人连接状态`。在拥有有效密钥和 `CharacterID`的情况下，状态应从 `连接中` 到 `Connected` 在没有手动 `Start Session` 调用设置。

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

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

```
在 %.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 流量。

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

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

### 在蓝图中处理连接错误

该 `Convai 聊天机器人` 组件公开了可供蓝图调用的状态节点和可由蓝图绑定的事件，可帮助你在运行时处理失败。

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

要在蓝图中绑定 **On Failure** ：

1. 选择 `Convai 聊天机器人` 在角色蓝图中找到
2. 在 **详细信息** 面板中，找到 **事件** 部分并点击 **+** 按钮旁边的 **On Failure**.
3. 会向事件图中添加一个新的事件节点。将其连接到你的错误处理逻辑——例如，在屏幕上打印或禁用按键说话按钮。

**On Failure** 不带参数触发。要查看错误详情，请在 `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 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/connection-and-api-key-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.