网络和 API 要求

说明 Unity 项目在通过互联网连接到 Convai 之前必须允许哪些网络主机、端口和防火墙规则。

Convai Unity SDK 在运行时需要外发互联网访问。语音、语言理解和文本转语音通过 Convai 经由 HTTPS 和 LiveKit WebRTC 运行——没有离线或 LAN 模式。准备企业网络、验证防火墙允许列表，或确认 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 会从 connect 响应中读取 room_url 并将其传递给传输层。它不会硬编码 LiveKit 主机名。示例主机 convai-technologies-lfslae7c.livekit.cloud 是一个 Convai 部署；你的日志可能会随时间显示不同的 room_url ，但属于同一账户。

身份验证

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

API 密钥

你的项目 API 密钥用于对 Convai 请求进行身份验证。请将其存储在 Edit > Project Settings > 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. 打开 Edit > Project Settings > Convai SDK > Diagnostics.
2. 设置 Global Log Level 移动到 调试，或者展开 Category Overrides 并添加一个覆盖项，使用 类别 Transport 和 级别 调试.
3. 进入 Play 模式并启动一个角色会话。
4. 打开 Unity Console，并按 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 Editor 和 Development Builds 中。有关日志记录配置，请参见 调试工具参考 。

测试 LiveKit 连接

使用 LiveKit 连接测试 当你需要确认受限网络是否可以到达 Convai 返回的房间时，请使用它。

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

连接测试字段	来自 Convai 日志的值
LiveKit URL	room_url / Room URL
Room Token	token / 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 日志在 调试，并确认出现 Room details received 或 Token: 行，且带有 wss:// room_url.
6. 确认角色到达 已连接 状态，并对语音或文本输入做出响应。

如果步骤 5 或 6 失败并出现 transport.ice_failed 或 transport.signal_disconnected，请参见 连接和 API 问题.

故障排查

症状	可能原因	修复方法	验证
connection.network_error 或 connection.timeout	TCP 上的 Convai 端点被阻止 443	允许 https://live.convai.com 和 api.convai.com	会话达到 已连接 state
transport.ice_failed 或 transport.peer_connection_failed	LiveKit UDP 或 TURN 主机被阻止	从本页添加 LiveKit 最低规则和可选的直接媒体路径	Room details received 日志出现；角色在 Play 模式中响应
否 Room details received 日志行	下方的传输日志记录 调试	打开 诊断 在项目设置中；将 Transport 类别覆盖设置为 调试	可读 Token: 行出现在 Console 中
Connect 成功后 LiveKit 连接测试失败	UDP 媒体或 TURN 回退路径被阻止	允许 UDP 50000–60000、UDP 3478 移动到 *.host.livekit.cloud和 TCP 443 移动到 *.turn.livekit.cloud	使用已记录的 Room URL 和 Token
connection.connect_invalid_api_key	无效或已撤销的 API 密钥	从 Convai 仪表板 复制一个新的密钥到项目设置中	Connect 错误不再触发
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 问题