连接和 API 密钥问题

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

使用此页面来解决 Convai 插件无法通过身份验证或与 Convai 建立会话的问题。安装问题请参见 安装和插件问题.

项目设置中的 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:

Config/DefaultEngine.ini

[/Script/Convai.ConvaiSettings]
API_Key=YOUR_API_KEY_HERE

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

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

症状： 进入播放模式后，玩家说话或发送文本，但角色没有产生任何响应。输出日志在 ConvaiChatbotComponentLog.

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

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

修复： 登录 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 是否已填充。

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

会话未自动启动

症状： 该 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.

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

在蓝图中处理连接错误

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

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

要在蓝图中绑定 On Failure ：

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

On Failure 不带参数触发。要查看错误详情，请在 ConvaiChatbotComponentLog 下查看事件触发时的输出日志——紧邻失败事件之前的日志条目包含错误字符串。

完整诊断参考请参见 诊断和日志导出.

快速参考

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

下一步

音频和麦克风问题诊断与日志导出