> 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 HTTPS 端点，实时音频和数据通过由随附的 WebRTC 客户端管理的 LiveKit 房间传输。在准备企业网络、验证防火墙允许列表或确认 Play In Editor 能成功连接 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`      | 开始实时会话时——子系统会在调用 WebRTC 客户端之前重新映射 `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 房间令牌

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

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

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

#### 确认实时连接 URL

在连接时，子系统会在 `ConvaiSubsystemLog`:

```
下记录流 URL 和角色 ID
```

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

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

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

```
OnConnectedToServer 调用 SessionID: <session_id>, CharSessionID: <character_session_id>
```

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

启用 **详细** 日志记录 `ConvaiClientLog` 以显示通过 `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 连接响应 |
| **房间令牌**        | `token` 来自 Convai 连接响应    |

公开的 Unreal 插件日志不会打印 `room_url` 或 `token`。 `room_url` 到 **LiveKit URL**，粘贴 `token` 到 **房间令牌**，然后选择 **运行测试**。 `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. 进入 Play In Editor 并确认 `OnConnectedToServer called SessionID:` 在输出日志中的 `ConvaiSubsystemLog`.
6. 调用 **Get Chatbot Connection State** 在 `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`                                                | **Get Chatbot Connection State** 返回 `已连接`  |
| `连接建立失败` 使用有效 API 密钥         | 连接后 LiveKit 主机被阻止         | 从本页添加 LiveKit 最低规则和可选直连媒体路径                                                                      | `OnConnectedToServer` 日志出现；角色在 Play 模式下有响应 |
| `bot-ready 未在` 超时内收到         | 网络缓慢或 WebRTC 路径被阻止        | 确认 LiveKit 防火墙规则；验证 `CharacterID` 在控制面板上                                                         | 会话在客户端就绪超时内变为就绪                            |
| 没有 `OnConnectedToServer` 日志行 | 会话从未到达 WebRTC 层           | 通过 Convai 编辑器窗口确认 API 密钥；验证 `CharacterID` 在 `Convai 聊天机器人` 组件                                    | 在开始 Play 之后出现日志行                           |
| 项目设置中的 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 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-unreal-engine-plugin/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.