> 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-unity-sdk/compatibility-and-requirements/network-and-api-requirements.md).

# 网络和 API 要求

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

### 所需出站访问

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

#### Convai 端点

| 主机                                                           | 端口    | 协议    | 用途                          |
| ------------------------------------------------------------ | ----- | ----- | --------------------------- |
| <code class="expression">space.vars.live\_server\_url</code> | `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 防火墙参考，请参阅 [配置防火墙](https://docs.livekit.io/deploy/admin/firewall/) 在 LiveKit 文档中。

### 实时会话如何连接

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

```mermaid
sequenceDiagram
    participant Unity as Unity SDK
    participant Convai as Convai
    participant LiveKit as LiveKit room

    Unity->>Convai: 使用 API 密钥发送 POST /connect
    Convai-->>Unity: session_id、room_url、room_name、token
    Unity->>LiveKit: 使用 token 在 room_url 加入房间
    LiveKit-->>Unity: 音频、视频和数据流
```

| 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    |

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

调试日志调用会从非开发版本中编译移除，除非 `CONVAI_DEBUG_LOGGING` 已定义。调试传输行默认会显示在 Unity 编辑器和开发版构建中。请参阅 [调试工具参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/debug-tools-reference.md) 以了解日志配置。

### 测试 LiveKit 连接

使用 [LiveKit 连接测试](https://livekit.com/webrtc/connection-test) 当您需要确认受限网络是否能够访问 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` 到 <code class="expression">space.vars.live\_server\_url</code> 是位于 `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 问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/connection-and-api-issues.md).

### 故障排查

| 症状                                                          | 可能原因                      | 修复                                                                                               | 验证                                      |
| ----------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------- |
| `connection.network_error` 或 `connection.timeout`           | Convai 端点在 TCP 上被阻止 `443` | 允许 <code class="expression">space.vars.live\_server\_url</code> 是位于 `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 密钥            | 从以下位置复制一个新密钥： <code class="expression">space.vars.dashboard\_url</code> 到项目设置中                   | 连接错误不再触发                                |
| WebGL 麦克风不可用                                                | 构建通过 HTTP 提供              | 请通过 HTTPS 或从以下位置提供该构建： `localhost`                                                               | 浏览器中出现麦克风权限提示                           |

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

### WebGL 部署

WebGL 构建必须通过 HTTPS 或从以下位置提供： `localhost`。由于浏览器安全策略，HTTP 部署会阻止麦克风访问。WebGL 使用与桌面构建相同的 Convai 和 LiveKit 端点。请参阅 [平台支持矩阵](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/compatibility-and-requirements/platform-support-matrix.md) 以及 [WebGL 部署指南](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/platform-guides/webgl.md) 了解浏览器特定限制。

### 下一步

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

{% content-ref url="/pages/f1f8700aca8f1ecef5696ae3f482c57ceae1064c" %}
[安装 Convai Unity SDK](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/getting-started/installation.md)
{% endcontent-ref %}

{% content-ref url="/pages/07c0ce6cfe225bcb17f8209c5187483d2497d1a4" %}
[连接与 API 问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/connection-and-api-issues.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-unity-sdk/compatibility-and-requirements/network-and-api-requirements.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.