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

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

Convai Unity SDK 在运行时需要外发互联网访问。语音、语言理解和文本转语音通过 Convai 经由 HTTPS 和 LiveKit WebRTC 运行——没有离线或 LAN 模式。准备企业网络、验证防火墙允许列表，或确认 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: POST /connect with API key
    Convai-->>Unity: session_id, room_url, room_name, token
    Unity->>LiveKit: Join room at room_url with token
    LiveKit-->>Unity: Audio, video, and data streams
```

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

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

除非定义了 `CONVAI_DEBUG_LOGGING` ，否则调试日志调用会在非开发构建中被编译移除。默认情况下，调试传输日志会出现在 Unity Editor 和 Development Builds 中。有关日志记录配置，请参见 [调试工具参考](/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. 将 `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` 移动到 <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** 日志在 **调试**，并确认出现 `Room details received` 或 `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`           | TCP 上的 Convai 端点被阻止 `443` | 允许 <code class="expression">space.vars.live\_server\_url</code> 和 `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 仪表板](https://convai.com) 复制一个新的密钥到项目设置中                                                  | Connect 错误不再触发                              |
| 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, and the optional `goal` 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>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.