> 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-unreal-engine-plugin/compatibility-and-requirements/network-and-api-requirements.md).

# 网络和 API 要求

Convai Unreal Engine 插件网络访问参考，包括 Convai 和 LiveKit 主机、防火墙规则、认证以及会话日志检查。

Convai Unreal Engine 插件在运行时需要出站互联网访问。会话设置使用 Convai HTTPS 端点，实时音频和数据则通过由捆绑 WebRTC 客户端管理的 LiveKit 房间传输。准备企业网络、验证防火墙允许列表，或确认编辑器内运行能否成功连接 Convai 时，请使用本页面。

### 所需的出站访问

运行时会话使用 Convai HTTPS 端点以及会话设置后使用的 LiveKit 主机。请允许运行 Unreal Engine 的计算机向以下主机发起出站流量。

#### Convai 端点

| 主机                        | 端口    | 协议    | 用途                                                      |
| ------------------------- | ----- | ----- | ------------------------------------------------------- |
| `realtime-api.convai.com` | `443` | HTTPS | 实时连接 — 默认 URL `https://realtime-api.convai.com/connect` |
| `api.convai.com`          | `443` | HTTPS | 角色数据、REST API 和编辑器网络诊断                                  |

通过以下方式覆盖实时端点 **编辑 > 项目设置 > 插件 > Convai > 自定义 URL**，或者使用以下参数启动编辑器 `-ConvaiStreamURL=` 在针对非默认连接 URL 测试时。

#### LiveKit 最低要求

Convai 接受连接请求后，原生 WebRTC 客户端会加入 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 回退 |

客户端计算机不需要入站端口。公开的 Unreal 插件源代码不提供单独的 TURN、STUN、WSS 或 UDP 设置 — 捆绑的 `ConvaiWebRTC` 客户端会在连接后选择传输路径。有关完整的 LiveKit 防火墙参考，请参阅 [配置防火墙](https://docs.livekit.io/deploy/admin/firewall/) 在 LiveKit 文档中。

### 实时会话如何连接

每个角色会话都遵循以下流程：

```mermaid
sequenceDiagram
    参与者 Unreal 作为 Unreal 插件
    participant Convai as Convai
    participant LiveKit as LiveKit room

    Unreal->>Convai：使用 API 密钥进行 HTTPS 连接
    Convai-->>Unreal：session_id、room_url、room_name、token
    Unreal->>LiveKit：原生 WebRTC 客户端加入房间
    LiveKit-->>Unreal：音频和数据流
```

Connect API 返回与以下文档中相同的房间字段： [Connect API](/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md):

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

Unreal 插件会在内部将连接凭据传递给原生 WebRTC 客户端。公开插件源代码不会读取或记录 `room_url`, `room_name`，或 `token` 直接 — 这些值在内部处理 `ConvaiWebRTC` 在 HTTPS 连接步骤完成后。示例主机 `convai-technologies-lfslae7c.livekit.cloud` 是一个 Convai 部署；您的会话可能会收到不同的 `room_url` 随着时间推移。

### 身份验证

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

#### API 密钥

您的项目 API 密钥用于验证对 Convai 的请求。请通过 Convai 编辑器窗口（**窗口 > 打开 Convai 编辑器**）进行配置。该密钥存储在 `UConvaiSettings.API_Key` 中，并显示在 **编辑 > 项目设置 > 插件 > Convai > API 密钥**.

| 请求类型                         | 标头               | 用于                                                                |
| ---------------------------- | ---------------- | ----------------------------------------------------------------- |
| HTTPS REST（`api.convai.com`) | `CONVAI-API-KEY` | 角色元数据、长期记忆以及其他 REST 调用                                            |
| 实时连接                         | `X-API-Key`      | 启动实时会话 — 子系统会重新映射 `CONVAI-API-KEY` 为 `X-API-Key` 然后再调用 WebRTC 客户端 |

当 `API_Key` 为空且已在以下位置配置个人访问令牌时 `UConvaiSettings.AuthToken`，实时连接会改用 `API-AUTH-TOKEN` 。请参阅 [个人访问令牌](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/advanced-topics/personal-access-token.md).

#### LiveKit 房间令牌

每个成功的连接响应都包含一个临时的 `token`。原生 WebRTC 客户端使用此令牌加入 LiveKit 房间。该令牌有效期很短，且仅授予访问该房间的权限。请将其视为密码 — 不要在公共论坛、支持工单或版本控制系统中分享。

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

公开的 Unreal 插件源代码不会在输出日志中打印 `token`, `room_url`，或 `room_name` 。房间加入详情由原生 WebRTC 客户端在内部处理。请使用以下日志确认 Convai 已接受该会话。

#### 确认实时连接 URL

连接时，子系统会在以下日志类别下记录流 URL 和角色 ID： `ConvaiSubsystemLog`:

```
StreamURL: https://realtime-api.convai.com/connect
```

在输出日志中搜索 `StreamURL` ，以确认插件使用了哪个连接端点。

#### 确认连接后的会话 ID

当 WebRTC 客户端成功连接时，子系统会记录 Convai 会话标识符：

```
已调用 OnConnectedToServer，SessionID：<session_id>，CharSessionID：<character_session_id>
```

| 日志值             | 含义                        |
| --------------- | ------------------------- |
| `SessionID`     | 用于实时会话的 Convai 会话 ID      |
| `CharSessionID` | 用于保持对话连续性的 Convai 角色会话 ID |

启用 **详细** 为以下项启用日志记录： `ConvaiClientLog` 以显示通过以下项转发的其他原生 WebRTC 客户端消息： `OnLog`.

{% hint style="danger" %}
请勿公开分享 LiveKit 房间令牌。尽管 Unreal 插件不会在公开源代码中记录 `token` ，但支持导出内容可能包含敏感会话数据。将日志发布到组织外部之前，请对凭据进行脱敏处理。
{% endhint %}

有关完整的诊断导出步骤，请参阅 [诊断和日志导出](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/diagnostics-and-log-export.md).

### 测试 LiveKit 连接

使用 [LiveKit 连接测试](https://livekit.com/webrtc/connection-test) ，以便确认受限网络能否访问特定的 LiveKit 房间。

| 连接测试字段          | 要使用的值                     |
| --------------- | ------------------------- |
| **LiveKit URL** | `room_url` 来自 Convai 连接响应 |
| **Room Token**  | `token` 来自 Convai 连接响应    |

公开的 Unreal 插件日志不会打印 `room_url` 或 `token`。如果您从支持诊断、自定义诊断构建或其他可信内部来源获取这些值，请粘贴 `room_url` 到 **LiveKit URL**，粘贴 `token` 到 **Room Token**，然后选择 **运行测试**。此测试会验证该临时房间的 LiveKit 信令和 WebRTC 连接。它不会验证您的 Convai API 密钥、 `api.convai.com`，或 `CharacterID` 配置。

### 防火墙验证清单

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

1. 确认出站 TCP `443` 为 `realtime-api.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. 进入编辑器内运行并确认 `已调用 OnConnectedToServer，SessionID：` 出现在以下输出日志类别中： `ConvaiSubsystemLog`.
6. 调用 **获取聊天机器人连接状态** 在 `Convai 聊天机器人` 组件，并确认状态变为 `已连接`.

如果第 5 步或第 6 步失败，请参阅 [连接和 API 密钥问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/connection-and-api-key-issues.md).

### 故障排除

| 症状                           | 可能原因                      | 修复方法                                                                                           | 验证                                         |
| ---------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------ |
| 所有请求均超时                      | Convai 端点在 TCP 上被阻止 `443` | 允许 `realtime-api.convai.com` 和 `api.convai.com`                                                | **获取聊天机器人连接状态** 返回 `已连接`                   |
| `无法建立连接` 使用有效的 API 密钥        | 连接后 LiveKit 主机被阻止         | 请从本页添加 LiveKit 最低规则和可选的直连媒体路径                                                                  | `OnConnectedToServer` 日志出现；角色在 Play 模式中有响应 |
| `未在以下时间内收到 bot-ready` 超时     | 网络缓慢或 WebRTC 路径被阻止        | 确认 LiveKit 防火墙规则；验证 `CharacterID` 在仪表板上                                                        | 会话在客户端就绪超时期限内变为就绪                          |
| 没有 `OnConnectedToServer` 日志行 | 会话从未到达 WebRTC 层           | 通过 Convai 编辑器窗口确认 API 密钥；验证 `CharacterID` 在 `Convai 聊天机器人` 组件                                  | 开始运行后出现日志行                                 |
| 项目设置中的 API 密钥字段为空            | 未通过 Convai 编辑器窗口保存密钥      | 打开 **窗口 > 打开 Convai 编辑器**，登录并保存密钥                                                              | `API 密钥` 项目设置中的字段已填充                       |
| 使用有效房间详情时 LiveKit 连接测试失败     | UDP 媒体或 TURN 回退路径被阻止      | 允许 UDP `50000`–`60000`、UDP `3478` 为 `*.host.livekit.cloud`和 TCP `443` 为 `*.turn.livekit.cloud` | 使用相同房间详情时 LiveKit 连接测试成功                   |

{% hint style="warning" %}
阻止或检查 HTTPS 流量的代理服务器可能会妨碍会话设置或 REST API 请求。当您的环境使用企业代理时，请允许向 Convai 端点发起出站 HTTPS 流量，并将 LiveKit 主机名排除在 TLS 检查之外。
{% endhint %}

### 下一步

确认网络要求后，请安装插件或查看连接故障排除。

{% content-ref url="/pages/1e7f8ff5f6dd180c804dba754f19c21a745be07f" %}
[安装 Convai 插件](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/install-the-convai-plugin.md)
{% endcontent-ref %}

{% content-ref url="/pages/f1b3d71c37ea498f3d6d84fdf60594d3020ae6bf" %}
[连接和 API 密钥问题](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/connection-and-api-key-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-unreal-engine-plugin/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.