使用个人访问令牌

在你的后端生成一个短期令牌，并将其传递给 Unreal 插件，这样生产构建就不必随包携带真实 API 密钥。

默认情况下，Convai Unreal Engine 插件会将你的 API 密钥存储在 UConvaiSettings.API_Key — 在 UE 5.2+ 中通过 Convai 编辑器窗口，或者在 Config/DefaultEngine.ini 中（适用于 UE 5.0 和 5.1）。这种流程适合编辑器测试和早期原型。在 打包应用程序中，任何检查该构建的人都可以读取已存储的 API 密钥，并将其用于你的 Convai 账户。

个人访问令牌（PAT） 可避免这种暴露。你的真实 API 密钥会保留在 后端 — 你控制的服务端应用（Node.js、Python、.NET、AWS Lambda 等）。后端会调用 Convai 生成一个短期 apiAuthToken （有效期约一小时），并在运行时将其返回给你的 Unreal 项目。插件会在会话开始时发送该令牌。如果令牌被截获，它会在一小时内过期。

我应该使用这个吗？ 本地编辑器测试请使用常规 配置您的 API 密钥 流程。发布打包构建且绝不能嵌入真实 API 密钥时，请使用个人访问令牌。

先决条件

• 已安装 Convai Unreal Engine 插件，并且你已使用常规 API 密钥完成一次成功的对话测试。请参见 配置您的 API 密钥 是位于 添加您的第一个 Convai 角色.
• 一个你控制的后端，它可以将真实的 Convai API 密钥作为服务端机密进行存储。
• 从后端到 https://api.convai.com.

令牌流程如何工作

PAT 流程中有三个参与方：

角色	它持有什么	作用
后端	真实的 Convai API 密钥	调用 Convai 令牌端点；绝不会将密钥暴露给 Unreal 构建。
Convai	你的账户和角色	返回一个短期 apiAuthToken.
Unreal 项目	该 apiAuthToken 仅	在会话开始前将令牌设置到插件中。

Unreal 项目必须 绝不能 调用 https://api.convai.com/user/connect 直接调用。该端点需要真实 API 密钥——将其嵌入客户端会使 PAT 的目的失效。

在你的后端生成令牌

所有令牌端点都针对 https://api.convai.com 并且需要在 CONVAI-API-KEY header。请只从你的后端发起这些调用。

生成令牌

POST https://api.convai.com/user/connect

Header	值
Content-Type	application/json
CONVAI-API-KEY	你的 Convai API 密钥

请求体： {}

响应：

{
  "apiAuthToken": "eyJhbGciOi...",
  "expirationTime": "2024-01-15T14:30:00Z"
}

字段	说明
apiAuthToken	要交付给 Unreal 项目的短期令牌。
expirationTime	UTC 过期时间戳——大约是生成后一小时。

当当前令牌仍然有效时，你可以生成一个新令牌。生成新令牌不会使之前的令牌失效。

后端示例（Python）：

import requests

def get_api_auth_token(api_key: str) -> str:
    url = "https://api.convai.com/user/connect"
    headers = {
        "CONVAI-API-KEY": api_key,
        "Content-Type": "application/json",
    }
    response = requests.post(url, headers=headers, json={})
    response.raise_for_status()
    return response.json()["apiAuthToken"]

延长令牌

POST https://api.convai.com/user/extend-token

头部：与“生成”相同。

{
  "apiAuthToken": "eyJhbGciOi..."
}

重置现有令牌的过期计时，但不会使其失效。

撤销令牌

POST https://api.convai.com/user/revoke-token

头部：与“生成”相同。

{
  "apiAuthToken": "eyJhbGciOi..."
}

会立即使令牌失效。请在注销时或令牌不再需要时调用此操作。最好通过你的后端代理撤销流程，这样真实 API 密钥就永远不会随客户端一起发布。

在 Unreal Engine 中使用该令牌

插件通过以下方式读取凭据 UConvaiUtils::GetAuthHeaderAndKey()。当 UConvaiSettings.API_Key 为 不为空时，插件会使用 API 密钥及 CONVAI-API-KEY header。当 API_Key 为空，且 AuthToken 已设置时，插件会改为使用带有 API-AUTH-TOKEN header 的令牌。

生产环境 PAT 流程需要 两个独立步骤：在打包前从磁盘上的项目中移除 API 密钥 在打包之前，然后在运行时设置一个新的令牌 之前 开始会话。跳过打包步骤会导致 API_Key 仍然包含在发布的构建中，即使你在编辑器的运行时清除了它。

组件	当自动初始化运行时	何时设置令牌
UConvaiChatbotComponent	BeginPlay 当 Auto Initialize Session 已启用	在该组件的 BeginPlay 完成之前——例如从 GameMode 或更早启动的 Actor 中。
UConvaiPlayerComponent	当全局连接达到 已连接	在子系统报告 已连接 之前——不一定是在 BeginPlay.

打包前清除 API 密钥

当你通过 Convai 编辑器窗口登录时，插件会写入 API_Key 到 Config/DefaultEngine.ini。Unreal Engine 会在打包构建中包含该文件。如果 API_Key 如果你在打包时它仍然存在，那么真实密钥会随构建一起发布——运行时的 PAT 无法事后修复这种暴露。

完成此步骤 之前 你创建发布构建。请使用下面的方法之一。

注销（UE 5.2+）

1

打开账户菜单

在 Convai 编辑器窗口中，单击右上角的账户控件。

2

退出登录

选择 退出登录。插件会清除 API_Key 是位于 AuthToken 来自 Config/DefaultEngine.ini.

3

确认文件已清空

打开 Config/DefaultEngine.ini 并确认 API_Key 位于以下路径下的行 [/Script/Convai.ConvaiSettings] 为空或已移除。 API 密钥 中的字段 Edit > Project Settings > Plugins > Convai 也应为空。

编辑 DefaultEngine.ini（所有 UE 版本）

请参见 移除或清除 API 密钥 了解本地凭据存储的完整参考。

在运行时设置令牌

在打包构建不再包含任何已存储的 API 密钥后，请在每次启动时从你的后端获取一个新的 apiAuthToken ，并在会话开始前将其应用 开始会话.

蓝图

1

从你的后端获取令牌

当玩家登录时——或在应用启动时——调用你的后端端点。使用你自己的应用会话对该请求进行身份验证（例如，来自登录系统的 bearer token）。你的后端返回 apiAuthToken 字符串。

不要在 https://api.convai.com/user/connect ，可通过 Blueprint 或任何客户端图形调用。

2

清除任何内存中的 API 密钥

在同一个 Blueprint 图中，调用 Set API Key (Convai|Settings）并传入空字符串。这样会清除运行时仍加载在内存中的任何密钥。

你还必须完成 打包前清除 API 密钥 这样 API_Key 就不会出现在发布的 DefaultEngine.ini.

3

设置认证令牌

调用 Set Auth Token (Convai|Settings）。将 apiAuthToken 来自后端响应的值连接到 Auth Token 输入引脚。

4

启动或重新连接会话

如果 Auto Initialize Session 已启用，请在自动初始化触发前设置令牌——在 BeginPlay 用于 chatbot 组件，或者在全局连接达到 已连接 用于 player 组件。若时机不确定，请禁用 Auto Initialize Session 并调用 开始会话 在设置令牌后手动执行。

请参见 会话生命周期 用于手动会话控制。

C++

切勿直接从 Unity 应用调用 https://api.convai.com/user/connect 从 Unreal 项目中——这需要在客户端构建中包含真实的 API 密钥。不要将 apiAuthToken 写入打包构建中的磁盘；每次启动时都从你的后端获取一个新令牌。优先使用 UConvaiUtils::SetAuthToken() 而不是 UConvaiSettings::SetAuthToken() 来处理短期运行时令牌。

选择 Blueprint 或 C++

两条路径都会写入同一个 UConvaiSettings.AuthToken 字段。设置令牌后，插件行为完全相同。

项目类型	推荐路径
仅 Blueprint	Set Auth Token 是位于 Set API Key 位于 `Convai
C++ 或混合 C++/Blueprint	UConvaiUtils::SetAuthToken() 是位于 UConvaiUtils::SetAPI_Key() 来自 ConvaiUtils.h

选择与你的登录或会话引导已经所在位置相匹配的路径即可。仅 Blueprint 的项目通常不需要为了 PAT 设置而使用 C++。

令牌过期与会话

一旦 Convai WebRTC 会话开始，在该会话期间不会再次检查令牌。会话中途过期的令牌不会断开玩家连接。PAT 会在连接时被消耗。

场景	行为
令牌在以下操作之前过期 开始会话	连接失败——从你的后端获取一个新令牌并重试。
令牌在活动会话期间过期	会话会持续到自然结束。
令牌过期后重新启动应用	在启动时获取一个新令牌——不要在多个启动之间重复使用缓存的令牌。

你的后端可以调用 /user/extend-token ，或者在玩家开始新会话之前生成一个新令牌。

使用示例：企业培训终端

一个企业安全培训终端通过 LMS 后端验证每个学员。当学员登录时，后端会连同 LMS 会话数据一起返回一个 Convai PAT。Unreal 项目会清除任何嵌入的 API 密钥，设置该令牌，并开始对话。

// PatKioskBootstrap.cpp — 伪代码模式
void APatKioskBootstrap::OnLearnerSignedIn(const FString& LmsSessionBearer)
{
    Backend->FetchConvaiToken(LmsSessionBearer, [this](const FString& ApiAuthToken)
    {
        UConvaiUtils::SetAPI_Key(TEXT(""));
        UConvaiUtils::SetAuthToken(ApiAuthToken);
        // 在 token 应用后，在 player/chatbot 组件上调用 StartSession。
    });
}

注销时，后端可以调用 /user/revoke-token 这样 PAT 就无法在共享设备上被重复使用。

故障排查

症状	可能原因	修复
连接立即失败	apiAuthToken 为 null——后端获取失败	请验证你的后端 URL、身份验证头，以及后端是否返回了非空令牌字符串。
401 连接时身份验证错误	令牌在 开始会话	在开始会话前立即获取一个新令牌。
PAT 被忽略；仍在使用 API 密钥	UConvaiSettings.API_Key 仍然填充在 Config/DefaultEngine.ini	从 Convai 编辑器窗口注销，在运行时调用 Set API Key 并传入空字符串，或者清除 API_Key 在 Config/DefaultEngine.ini 在打包前。请参见 配置您的 API 密钥.
令牌在编辑器中有效，但在打包构建中失败	打包构建仍然包含已存储的 API 密钥，或者启动时没有获取 PAT	确认运行时令牌获取在自动初始化前完成；从发布配置中清除嵌入的密钥。
apiAuthToken 在后端响应中为 null	缺少 CONVAI-API-KEY header 或后端调用的正文格式错误	请确保正文为 {} 并且 header 存在。记录原始后端响应。

下一步

配置你的 API 密钥会话生命周期Convai 实用函数连接和 API 密钥问题