> 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 和编辑器网络诊断                                  |

通过以下位置覆盖实时端点： **Edit > Project Settings > Plugins > Convai > Custom URL**；或者在测试非默认连接 URL 时，使用以下参数启动编辑器： `-ConvaiStreamURL=` 。

#### 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 防火墙的完整参考，请参阅 LiveKit 文档中的 [配置防火墙](https://docs.livekit.io/deploy/admin/firewall/) 。

### 实时会话的连接方式

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

```mermaid
sequenceDiagram
    participant Unreal as Unreal plugin
    参与方 Convai，作为 Convai
    参与方 LiveKit，作为 LiveKit 房间

    Unreal->>Convai: HTTPS connect with API key
    Convai-->>Unreal: session_id, room_url, room_name, token
    Unreal->>LiveKit: Native WebRTC client joins room
    LiveKit-->>Unreal: Audio and data streams
```

Connect API 返回的房间字段与 [Connect API](https://docs.convai.com/api-docs/zh/api-can-kao/core-api-reference/live-apis-beta/connect-api.md):

| 连接响应字段                 | 运行时用途                                                                      |
| ---------------------- | -------------------------------------------------------------------------- |
| `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` ；这些值会在 HTTPS 连接步骤完成后由 `ConvaiWebRTC` 内部处理。示例主机 `convai-technologies-lfslae7c.livekit.cloud` 是 Convai 的一个部署实例；您的会话可能会随时间推移获得不同的 `room_url` 。

### 身份验证

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

#### API 密钥

项目 API 密钥用于验证发往 Convai 的请求。请在 Convai 编辑器窗口中配置该密钥（**Window > Open Convai Editor**）。密钥存储在 `UConvaiSettings.API_Key` 中，并显示在 **Edit > Project Settings > Plugins > Convai > API Key**.

| 请求类型                         | 标头               | 用途                                                               |
| ---------------------------- | ---------------- | ---------------------------------------------------------------- |
| 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` 。请参阅 [个人访问令牌](https://docs.convai.com/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

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

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

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

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

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

```
OnConnectedToServer called SessionID: <session_id>, CharSessionID: <character_session_id>
```

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

启用 **详细** 级别日志记录，以便在 `ConvaiClientLog` 中查看通过 `OnLog`.

{% hint style="danger" %}
转发的其他原生 WebRTC 客户端消息。 `token` 公开分享 LiveKit 房间令牌。尽管 Unreal 插件的公开源代码不会记录
{% endhint %}

支持导出的日志可能包含敏感会话数据。在组织外发布日志前，请对凭据进行脱敏。 [诊断与日志导出](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/diagnostics-and-log-export.md).

### 测试 LiveKit 连接

当需要确认受限网络能否连接到特定 LiveKit 房间时，请使用 [LiveKit 连接测试](https://livekit.com/webrtc/connection-test) 。

| 连接测试字段          | 要使用的值                     |
| --------------- | ------------------------- |
| **LiveKit URL** | `room_url` 来自 Convai 连接响应 |
| **房间令牌**        | `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. 进入“在编辑器中运行”（Play In Editor），并确认 `OnConnectedToServer called SessionID:` 显示在“输出日志”的 `ConvaiSubsystemLog`.
6. 调用 **获取聊天机器人的连接状态** 在 `Convai Chatbot` 组件上，并确认状态变为 `Connected`.

如果步骤 5 或 6 失败，请参阅 [连接和 API 密钥问题](https://docs.convai.com/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`                                                    | **获取聊天机器人连接状态** 返回 `Connected`             |
| `Failed to establish connection` 使用有效的 API 密钥 | 连接后 LiveKit 主机被阻止          | 添加本页中的 LiveKit 最低规则以及可选的直接媒体传输路径                                                                   | `OnConnectedToServer` 日志出现；角色在 Play 模式下有响应 |
| `bot-ready not received within` 超时            | 网络较慢或 WebRTC 通道受阻          | 确认 LiveKit 防火墙规则；验证 `CharacterID` 在仪表板上                                                            | 会话在客户端就绪超时时间内变为就绪状态                        |
| 否 `OnConnectedToServer` 日志行                   | 会话从未到达 WebRTC 层            | 通过 Convai 编辑器窗口确认 API 密钥；验证 `CharacterID` 上的 `Convai Chatbot` 组件                                   | 开始运行后会出现日志行                                |
| 项目设置中的 API 密钥字段为空                             | 未通过 Convai 编辑器窗口保存密钥       | 打开 **Window > Open Convai Editor**，登录并保存密钥                                                         | `API Key` 字段已在项目设置中填入                      |
| 使用有效的房间信息时，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 插件](https://docs.convai.com/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 密钥问题](https://docs.convai.com/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.
