网络与 API 要求

Convai Unreal Engine 插件网络访问参考，包括 Convai 和 LiveKit 主机、防火墙规则、身份验证和会话日志检查。

Convai Unreal Engine 插件在运行时需要出站互联网访问。会话设置使用 Convai HTTPS 端点，实时音频和数据通过由随附的 WebRTC 客户端管理的 LiveKit 房间传输。在准备企业网络、验证防火墙允许列表或确认 Play In Editor 能成功连接 Convai 时，请使用本页。

所需出站访问

运行时会话使用 Convai HTTPS 端点以及会话设置后使用的 LiveKit 主机。请允许运行 Unreal Engine 的机器向以下主机发出出站流量。

Convai 端点

主机	端口	协议	用途
realtime-api.convai.com	443	HTTPS	实时连接 — 默认 URL https://realtime-api.convai.com/connect
api.convai.com	443	HTTPS	角色数据、REST API 和编辑器网络诊断

通过以下方式覆盖实时端点 编辑 > 项目设置 > 插件 > Convai > 自定义 URL，或者启动编辑器时使用 -ConvaiStreamURL= ，当测试非默认连接 URL 时。

LiveKit 最低要求

Convai 接受连接请求后，本地 WebRTC 客户端会加入一个 LiveKit 房间。LiveKit Cloud 连接的最小出站规则：

主机	端口	协议	用途
convai-technologies-lfslae7c.livekit.cloud	443	TCP	Convai LiveKit 信令端点
*.livekit.cloud	443	TCP	LiveKit WebSocket 信令
*.turn.livekit.cloud	443	TCP	UDP 被阻止时的 TURN/TLS 备用通道

可选的直连媒体路径

LiveKit 文档说明了这些路径用于直接 WebRTC 媒体和 TCP 备用。当您的网络策略允许 UDP，或者 LiveKit 连接测试显示最低 TCP 规则不够时，请添加这些路径。

主机	端口	协议	用途
*.host.livekit.cloud	3478	UDP	TURN/UDP 连接
所有 LiveKit 主机	50000–60000	UDP	WebRTC 媒体传输
所有 LiveKit 主机	7881	TCP	WebRTC TCP 备用

客户端机器不需要任何入站端口。公开的 Unreal 插件源码不会暴露单独的 TURN、STUN、WSS 或 UDP 设置——随附的 ConvaiWebRTC 客户端会在连接后选择传输路径。完整的 LiveKit 防火墙参考，请参见 配置防火墙 在 LiveKit 文档中。

实时会话如何连接

每个角色会话都遵循以下顺序：

Connect API 返回的房间字段与下文文档中说明的相同 Connect API:

Connect 响应字段	运行时用途
session_id	用于实时会话的 Convai 会话 ID
character_session_id	断线重连后的对话连续性
room_url	LiveKit WebSocket 端点——例如 wss://convai-technologies-lfslae7c.livekit.cloud
room_name	客户端加入的 LiveKit 房间名称
token	用于加入房间的临时 LiveKit 房间令牌

Unreal 插件会在内部将连接凭据传递给本地 WebRTC 客户端。公开的插件源码不会直接读取或记录 room_url, room_name，或 token ——这些值是在 ConvaiWebRTC HTTPS 连接步骤完成后在内部处理的。示例主机 convai-technologies-lfslae7c.livekit.cloud 是 Convai 的一个部署；您的会话可能会接收到不同的 room_url 并且会随时间变化。

身份验证

运行时会话涉及两种凭据类型。

API 密钥

您的项目 API 密钥用于对 Convai 的请求进行身份验证。请通过 Convai 编辑器窗口（窗口 > 打开 Convai 编辑器）进行配置。该密钥存储在 UConvaiSettings.API_Key 中，并显示在 编辑 > 项目设置 > 插件 > Convai > API 密钥.

请求类型	标头	用于
HTTPS REST（api.convai.com)	CONVAI-API-KEY	角色元数据、长期记忆以及其他 REST 调用
实时连接	X-API-Key	开始实时会话时——子系统会在调用 WebRTC 客户端之前重新映射 CONVAI-API-KEY 到 X-API-Key 在调用 WebRTC 客户端之前

当 API_Key 为空且已在 UConvaiSettings.AuthToken中配置了个人访问令牌，则实时连接会改用 API-AUTH-TOKEN 。参见 个人访问令牌.

LiveKit 房间令牌

每个成功的 connect 响应都包含一个临时的 token。本地 WebRTC 客户端使用此令牌加入 LiveKit 房间。令牌有效期很短，仅授予对该房间的访问权限。请将其视为密码——不要在公开论坛、支持工单或版本控制中共享。

在日志中查找连接详情

公开的 Unreal 插件源码不会打印 token, room_url，或 room_name 到输出日志中。房间加入详情是在本地 WebRTC 客户端内部处理的。请使用以下日志确认 Convai 已接受该会话。

确认实时连接 URL

在连接时，子系统会在 ConvaiSubsystemLog:

下记录流 URL 和角色 ID

在输出日志中搜索 StreamURL ，如果您需要确认插件使用了哪个连接端点。

连接后确认会话 ID

当 WebRTC 客户端成功连接后，子系统会记录 Convai 会话标识符：

OnConnectedToServer 调用 SessionID: <session_id>, CharSessionID: <character_session_id>

日志值	含义
SessionID	用于实时会话的 Convai 会话 ID
CharSessionID	用于对话连续性的 Convai 角色会话 ID

启用 详细 日志记录 ConvaiClientLog 以显示通过 OnLog.

不要公开共享 LiveKit 房间令牌。虽然 Unreal 插件不会在公开源码中记录 token ，但支持导出可能包含敏感会话数据。请在组织外发布日志之前先遮盖凭据。

完整的诊断导出步骤，请参见 诊断和日志导出.

测试 LiveKit 连接

使用 LiveKit 连接测试 ，当您需要确认受限网络是否可以访问特定 LiveKit 房间时。

连接测试字段	要使用的值
LiveKit URL	room_url 来自 Convai 连接响应
房间令牌	token 来自 Convai 连接响应

公开的 Unreal 插件日志不会打印 room_url 或 token。 room_url 到 LiveKit URL，粘贴 token 到 房间令牌，然后选择 运行测试。 api.convai.com，或 CharacterID 配置。

防火墙验证清单

在部署到受限环境之前，请与您的网络或 IT 团队一起完成此清单。

1. 确认出站 TCP 443 到 realtime-api.convai.com 是位于 api.convai.com.
2. 确认出站 TCP 443 到 convai-technologies-lfslae7c.livekit.cloud, *.livekit.cloud，以及 *.turn.livekit.cloud.
3. 当允许 UDP 时，请允许 UDP 3478 到 *.host.livekit.cloud 以及出站 UDP 50000–60000.
4. 如果您的代理对 HTTPS 或 WSS 流量执行中间人解密，请将 Convai 和 LiveKit 主机名排除在 TLS 检查之外。
5. 进入 Play In Editor 并确认 OnConnectedToServer called SessionID: 在输出日志中的 ConvaiSubsystemLog.
6. 调用 Get Chatbot Connection State 在 Convai 聊天机器人 组件，并确认状态变为 已连接.

如果步骤 5 或 6 失败，请参见 连接和 API 密钥问题.

故障排查

症状	可能原因	修复	验证
所有请求都超时	Convai 端点在 TCP 上被阻止 443	允许 realtime-api.convai.com 是位于 api.convai.com	Get Chatbot Connection State 返回 已连接
连接建立失败 使用有效 API 密钥	连接后 LiveKit 主机被阻止	从本页添加 LiveKit 最低规则和可选直连媒体路径	OnConnectedToServer 日志出现；角色在 Play 模式下有响应
bot-ready 未在 超时内收到	网络缓慢或 WebRTC 路径被阻止	确认 LiveKit 防火墙规则；验证 CharacterID 在控制面板上	会话在客户端就绪超时内变为就绪
没有 OnConnectedToServer 日志行	会话从未到达 WebRTC 层	通过 Convai 编辑器窗口确认 API 密钥；验证 CharacterID 在 Convai 聊天机器人 组件	在开始 Play 之后出现日志行
项目设置中的 API 密钥字段为空	未通过 Convai 编辑器窗口保存密钥	打开 窗口 > 打开 Convai 编辑器，登录并保存密钥	API 密钥 字段已在项目设置中填充
使用有效房间详情时 LiveKit 连接测试失败	UDP 媒体或 TURN 备用路径被阻止	允许 UDP 50000–60000，UDP 3478 到 *.host.livekit.cloud，以及 TCP 443 到 *.turn.livekit.cloud	使用相同房间详情时 LiveKit 连接测试成功

阻止或检查 HTTPS 流量的代理服务器可能会阻止会话设置或 REST API 请求。请允许到 Convai 端点的出站 HTTPS 流量，并在您的环境使用企业代理时将 LiveKit 主机名排除在 TLS 检查之外。

下一步

确认网络要求后，安装插件或查看连接故障排除。

安装 Convai 插件连接和 API 密钥问题