> 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 运行——没有离线或局域网模式。准备企业网络、验证防火墙允许列表，或确认 Play 模式会话是否到达正确的 LiveKit 房间时，请使用本页。

### 所需的出站访问

运行时会话会使用两个 Convai 端点以及连接响应中返回的 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 接受连接请求后，SDK 会使用 `room_url` 和 `token` 从响应中加入 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 回退 |

客户端机器上不需要任何入站端口。有关完整的 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` 自连接响应，并将其传递给传输层。它不会硬编码 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 房间令牌

每个成功的连接响应都包含一个临时的 `token`。SDK 会在加入房间时把此令牌传给 LiveKit。该令牌有效期很短，只授予对该房间的访问权限。请像对待密码一样对待它——不要在公开论坛、支持工单或版本控制中共享。

### 在日志中查找连接详情

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

1. 打开 **Edit > Project Settings > Convai SDK > Diagnostics**.
2. 设置 **全局日志级别** 为 `调试`，或展开 **类别覆盖** 并添加一个覆盖项，值为 **类别** `传输` 和 **级别** `调试`.
3. 进入 Play 模式并启动一个角色会话。
4. 打开 Unity 控制台并按 `传输`.

筛选。你应该会看到以下某种日志形式：

```
[Debug][Transport]: 已收到房间详细信息：{"token":"...","room_name":"...","session_id":"...","room_url":"..."}
```

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

```
[Debug][Transport]: Token: ...; 房间名称: ...; 房间 URL: ...; 会话 ID: ...; 角色会话 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. 将 `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 模式，启用 **传输** 日志在 **调试**，并确认 `已收到房间详细信息` 或 `Token:` 行出现，且带有 `wss://` `room_url`.
6. 确认角色到达 **已连接** 状态并对语音或文本输入作出响应。

如果步骤 5 或 6 以 `transport.ice_failed` 或 `transport.signal_disconnected`的 SDK 方法，请参阅 [连接和 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`             | 会话达到 `已连接` state                           |
| `transport.ice_failed` 或 `transport.peer_connection_failed` | LiveKit UDP 或 TURN 主机被阻止  | 请从本页添加 LiveKit 最低规则和可选的直连媒体路径                                                                  | `已收到房间详细信息` 日志出现；角色在 Play 模式中有响应           |
| 没有 `已收到房间详细信息` 日志行                                          | 下方的传输日志 **调试**            | 打开 **诊断** 在项目设置中；将 **传输** 类别覆盖设为 **调试**                                                        | 可读 `Token:` 行出现在控制台中                       |
| 连接成功后，LiveKit 连接测试失败                                        | UDP 媒体或 TURN 回退路径被阻止      | 允许 UDP `50000`–`60000`、UDP `3478` 为 `*.host.livekit.cloud`和 TCP `443` 为 `*.turn.livekit.cloud` | LiveKit 连接测试在记录的情况下成功 `Room URL` 和 `Token` |
| `connection.connect_invalid_api_key`                        | 无效或已撤销的 API 密钥            | 从 [Convai 仪表板](https://convai.com) 复制一个新密钥到项目设置中                                               | 连接错误不再触发                                   |
| 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
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=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.