网络和 API 要求

Convai Unity SDK 网络访问参考，包括 Convai 和 LiveKit 主机、防火墙规则、身份验证，以及基于日志的连接检查。

Convai Unity SDK 在运行时需要出站互联网访问。语音、语言理解和文本转语音通过 HTTPS 上的 Convai 和 LiveKit WebRTC 运行——没有离线或局域网模式。在准备企业网络、验证防火墙允许列表，或确认 Play 模式会话已到达正确的 LiveKit 房间时，请使用本页。

所需出站访问

运行时会话使用两个 Convai 端点以及 connect 响应中返回的 LiveKit 主机。请允许运行 Unity 的机器向以下主机发起出站流量。

Convai 端点

主机	端口	协议	用途
https://live.convai.com	443	HTTPS	Connect API——会话设置和房间凭据
api.convai.com	443	HTTPS	角色元数据、REST API 和 WebGL 情绪预检

LiveKit 最低要求

在 Convai 接受 connect 请求后，SDK 将使用以下内容加入 LiveKit 房间 room_url 是位于 token 响应中的。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 备用

客户端机器上不需要任何入站端口。有关完整的 LiveKit 防火墙参考，请参阅 配置防火墙 在 LiveKit 文档中。

实时会话如何连接

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

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

SDK 读取 room_url connect 响应中的内容并将其传递给传输层。它不会硬编码 LiveKit 主机名。示例主机 convai-technologies-lfslae7c.livekit.cloud 是一个 Convai 部署；您的日志可能会显示不同的 room_url 在同一账户下，随着时间推移会变化。

身份验证

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

API 密钥

您的项目 API 密钥用于验证对 Convai 的请求。请将其存储在 编辑 > 项目设置 > Convai SDK.

请求类型	标头	用于
Connect (/connect)	X-API-Key	开始实时会话
REST (api.convai.com)	CONVAI-API-KEY	角色元数据、长期记忆以及其他 REST 调用

SDK 会自动发送 API 密钥。您无需手动将密钥粘贴到 connect 载荷中。

LiveKit 房间令牌

每个成功的 connect 响应都包含一个临时的 token。SDK 在加入房间时会将此令牌传递给 LiveKit。该令牌生命周期很短，仅授予对该房间的访问权限。请将其视为密码——不要在公开论坛、支持工单或版本控制中分享。

在日志中查找连接详情

会话开始时，SDK 会在 调试 级别记录房间凭据，位于 Transport 类别下。在搜索这些行之前，请启用详细的传输日志记录。

1. 打开 编辑 > 项目设置 > Convai SDK > 诊断.
2. 设置 全局日志级别 到 调试，或者展开 类别覆盖 并添加一个覆盖项，使用 类别 Transport 是位于 级别 调试.
3. 进入 Play 模式并启动角色会话。
4. 打开 Unity 控制台并按 Transport.

您应当看到以下某种日志格式：

[Debug][Transport]: Room details received: {"token":"...","room_name":"...","session_id":"...","room_url":"..."}

如果 JSON 行难以阅读，请搜索 Token: ——SDK 还会输出一个可读摘要：

[Debug][Transport]: Token: ...; Room Name: ...; Room URL: ...; Session ID: ...; Character Session ID: ...

日志字段	含义
token	LiveKit 房间令牌
room_name	LiveKit 房间名称 / 房间 ID
room_url	LiveKit URL / WebSocket 端点
session_id	Convai 会话 ID
角色会话 ID	用于对话连续性的 Convai 角色会话 ID

不要公开分享房间令牌。它是临时的，并授予对 LiveKit 房间的访问权限。请在发布 token 到支持渠道或公开问题跟踪器之前先处理这些值。

调试日志调用会从非开发版本中编译移除，除非 CONVAI_DEBUG_LOGGING 已定义。调试传输行默认会显示在 Unity 编辑器和开发版构建中。请参阅 调试工具参考 以了解日志配置。

测试 LiveKit 连接

使用 LiveKit 连接测试 当您需要确认受限网络是否能够访问 Convai 返回的房间时。

1. 启动 Unity 会话并找到 Token: 日志行。
2. 复制 房间 URL 的值到 LiveKit URL.
3. 复制 令牌 的值到 房间令牌.
4. 选择 运行测试.

连接测试字段	来自 Convai 日志的值
LiveKit URL	room_url / 房间 URL
房间令牌	token / 令牌

该测试会验证该临时房间的 LiveKit 信令和 WebRTC 连接。它不会验证您的 Convai API 密钥， api.convai.com，也不会验证角色配置。

防火墙验证清单

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

1. 确认出站 TCP 443 到 https://live.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 模式，启用 Transport 日志级别为 调试，并确认 已收到房间详情 或 Token: 行会显示带有 wss:// room_url.
6. 确认角色达到 已连接 状态并响应语音或文本输入。

如果第 5 或第 6 步出现以下错误： transport.ice_failed 或 transport.signal_disconnected，请参阅 连接和 API 问题.

故障排查

症状	可能原因	修复	验证
connection.network_error 或 connection.timeout	Convai 端点在 TCP 上被阻止 443	允许 https://live.convai.com 是位于 api.convai.com	会话到达 已连接 状态
transport.ice_failed 或 transport.peer_connection_failed	LiveKit UDP 或 TURN 主机被阻止	从本页添加 LiveKit 最低规则和可选直连媒体路径	已收到房间详情 日志出现；角色在 Play 模式下有响应
没有 已收到房间详情 日志行	下方的传输日志记录 调试	打开 诊断 在项目设置中；将 Transport 类别覆盖为 调试	可读 Token: 行会出现在控制台中
在 connect 成功后，LiveKit 连接测试失败	UDP 媒体或 TURN 备用路径被阻止	允许 UDP 50000–60000，UDP 3478 到 *.host.livekit.cloud，以及 TCP 443 到 *.turn.livekit.cloud	通过日志中的 LiveKit 连接测试成功 房间 URL 是位于 令牌
connection.connect_invalid_api_key	无效或已撤销的 API 密钥	从以下位置复制一个新密钥： https://convai.com 到项目设置中	连接错误不再触发
WebGL 麦克风不可用	构建通过 HTTP 提供	请通过 HTTPS 或从以下位置提供该构建： localhost	浏览器中出现麦克风权限提示

对 HTTPS 或 WSS 流量执行 TLS 检查的代理服务器可能会破坏 LiveKit 信令。当您的环境使用企业代理时，请将 Convai 和 LiveKit 主机名排除在 TLS 检查之外。

WebGL 部署

WebGL 构建必须通过 HTTPS 或从以下位置提供： localhost。由于浏览器安全策略，HTTP 部署会阻止麦克风访问。WebGL 使用与桌面构建相同的 Convai 和 LiveKit 端点。请参阅 平台支持矩阵 以及 WebGL 部署指南 了解浏览器特定限制。

下一步

确认网络要求后，请安装 SDK 或查看连接错误代码。

安装 Convai Unity SDK连接与 API 问题