> 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/advanced-topics/personal-access-token.md).

# 使用个人访问令牌

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

默认情况下，Convai Unreal Engine 插件会将你的 API 密钥存储在 `UConvaiSettings.API_Key` 中——UE 5.2 及更高版本可通过 Convai 编辑器窗口设置，UE 5.0 和 5.1 则存储在 `Config/DefaultEngine.ini` 中。这种方式适用于编辑器测试和早期原型开发。在 **打包后的应用程序**中，任何检查构建产物的人都能读取其中存储的 API 密钥，并将其用于访问你的 Convai 账户。

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

{% hint style="info" %}
**我应该使用这种方式吗？** 本地编辑器测试时，请使用常规的 [配置 API 密钥](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md) 流程。发布打包版本且不能在其中嵌入真实 API 密钥时，请使用个人访问令牌。
{% endhint %}

### 前提条件

* 你已安装 Convai Unreal Engine 插件，并使用常规 API 密钥成功完成了对话测试。请参阅 [配置 API 密钥](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md) 和 [添加你的第一个 Convai 角色](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/add-your-first-convai-character.md).
* 由你控制的后端，可将真实的 Convai API 密钥作为服务器端密钥存储。
* 后端可通过出站 HTTPS 连接访问 `https://api.convai.com`.

### 令牌流程的工作原理

PAT 流程涉及三个角色：

| 角色            | 持有的内容                | 功能说明                                |
| ------------- | -------------------- | ----------------------------------- |
| **后端**        | 真实的 Convai API 密钥    | 调用 Convai 令牌端点；绝不向 Unreal 构建产物暴露密钥。 |
| **Convai**    | 你的账户和角色              | 返回一个短期 `apiAuthToken`.              |
| **Unreal 项目** | 仅持有 `apiAuthToken` 。 | 会话开始前，将令牌设置到插件中。                    |

```mermaid
graph TD
    后端["你的后端\n（持有真实 API 密钥）"]
    ConvaiAPI["Convai\nPOST /user/connect"]
    UnrealApp["Unreal 项目\n（接收 apiAuthToken）"]
    Session["Convai 会话\n（WebRTC）"]

    后端 -->|"CONVAI-API-KEY 标头"| ConvaiAPI
    ConvaiAPI -->|"apiAuthToken（约 1 小时）"| 后端
    后端 -->|"在运行时交付"| UnrealApp
    UnrealApp -->|"在 Start Session 之前调用 SetAuthToken"| Session
```

Unreal 项目 **绝不能** 调用 `https://api.convai.com/user/connect` 。该端点需要真实的 API 密钥——将其嵌入客户端会违背 PAT 的设计初衷。

### 在后端生成令牌

所有令牌端点都以 `https://api.convai.com` 为目标地址，并要求在 `CONVAI-API-KEY` 请求头中提供真实的 API 密钥。请仅从后端发起这些调用。

#### 生成令牌

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

| 请求头              | 值                  |
| ---------------- | ------------------ |
| `Content-Type`   | `application/json` |
| `CONVAI-API-KEY` | 你的 Convai API 密钥   |

**请求正文：** `{}`

**响应：**

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

| 字段               | 说明                        |
| ---------------- | ------------------------- |
| `apiAuthToken`   | 要传递给 Unreal 项目的短期令牌。      |
| `expirationTime` | 过期时间的 UTC 时间戳——大约在生成后一小时。 |

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

**后端示例（Python）：**

```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"]
```

#### 延长令牌有效期

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

请求头：与生成令牌时相同。

```json
{
  "apiAuthToken": "eyJhbGciOi..."
}
```

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

#### 撤销令牌

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

请求头：与生成令牌时相同。

```json
{
  "apiAuthToken": "eyJhbGciOi..."
}
```

立即使令牌失效。请在用户登出或不再需要令牌时调用此端点。建议通过后端代理撤销操作，避免将真实 API 密钥发送到客户端。

### 在 Unreal Engine 中使用令牌

插件通过 `UConvaiUtils::GetAuthHeaderAndKey()`读取凭据。当 `UConvaiSettings.API_Key` 不 **为空**时，插件会在 `CONVAI-API-KEY` 请求头中使用 API 密钥。当 `API_Key` 为空时，并且 `AuthToken` 设置后，插件会改为通过 `API-AUTH-TOKEN` 标头发送令牌。

生产环境中的 PAT 流程需要 **两个独立步骤**：先从磁盘上的项目中移除 API 密钥， **再进行打包**，然后在运行时设置新的令牌 **，并且要在** `Start Session`之前执行。跳过打包步骤会导致 `API_Key` 留在已发布的构建中，即使你在编辑器运行时将其清除也无济于事。

| 组件                        | 自动初始化运行时                      | 何时设置令牌                                                       |
| ------------------------- | ----------------------------- | ------------------------------------------------------------ |
| `UConvaiChatbotComponent` | `BeginPlay` 当 **自动初始化会话** 启用时 | 在该组件的 `BeginPlay` 完成之前，例如在 `GameMode` 中设置，或在更早启动的 Actor 中设置。 |
| `UConvaiPlayerComponent`  | 全局连接达到 `Connected`            | 在子系统报告 `Connected` 之前设置——不一定要在 `BeginPlay`.                  |

### 打包前清除 API 密钥

通过 Convai 编辑器窗口登录时，插件会将 `API_Key` 写入 `Config/DefaultEngine.ini`。Unreal Engine **会将此文件包含在打包构建中**。如果打包时 `API_Key` 仍有设置，真实密钥就会随构建一起发布——事后在运行时使用 PAT 无法消除此泄露风险。

请完成此步骤 **然后再** 创建正式发布构建。请使用以下任一方法。

{% tabs %}
{% tab title="退出登录（UE 5.2+）" %}
{% stepper %}
{% step %}

#### 打开账户菜单

在 Convai 编辑器窗口中，点击右上角的账户控件。
{% endstep %}

{% step %}

#### 退出登录

选择 **退出登录**。插件会清除 `API_Key` 和 `AuthToken` 中的 `Config/DefaultEngine.ini`.
{% endstep %}

{% step %}

#### 确认文件已清除

打开 `Config/DefaultEngine.ini` 并确认 `API_Key` 行（位于 `[/Script/Convai.ConvaiSettings]` 下方）为空或已删除。 **API 密钥** 字段（位于 **编辑 > 项目设置 > 插件 > Convai** 中）也应为空。
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="编辑 DefaultEngine.ini（适用于所有 UE 版本）" %}
{% stepper %}
{% step %}

#### 关闭编辑器

编辑文件前请先关闭虚幻编辑器，以免关闭时更改被覆盖。
{% endstep %}

{% step %}

#### 清除 API\_Key 和 AuthToken

打开 `Config/DefaultEngine.ini` （位于项目文件夹中）。在 `[/Script/Convai.ConvaiSettings]`下，删除 `API_Key` 行，或将其设为空值。如果存在，也以相同方式清除 `AuthToken` 。

{% code title="Config/DefaultEngine.ini" %}

```ini
[/Script/Convai.ConvaiSettings]
API_Key=
AuthToken=
```

{% endcode %}
{% endstep %}

{% step %}

#### 打包前确认

重启编辑器，然后打开 **编辑 > 项目设置 > 插件 > Convai**。确认 **API 密钥** 为空，然后创建打包版本。
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}

有关本地凭据存储的完整说明，请参阅 [移除或清除 API 密钥](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md#remove-or-clear-the-api-key) 。

### 在运行时设置令牌

确保打包版本中未存储 API 密钥后，每次启动时都从后端获取新的 `apiAuthToken` ，并在调用 `Start Session`.

{% tabs %}
{% tab title="蓝图" %}
{% stepper %}
{% step %}

#### 从后端获取令牌

玩家登录时（或应用程序启动时），调用后端端点。使用你自己的应用会话对该请求进行身份验证（例如，使用登录系统提供的 bearer 令牌）。后端会返回 `apiAuthToken` 字符串。

请勿从 Blueprint 或任何客户端图表中调用 `https://api.convai.com/user/connect` 。
{% endstep %}

{% step %}

#### 清除内存中的 API 密钥

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

你还必须先完成 [打包前清除 API 密钥](#clear-the-api-key-before-packaging) ，以确保随应用发布的 `API_Key` 不会出现在 `DefaultEngine.ini`.
{% endstep %}

{% step %}

#### 设置身份验证令牌

调用 **设置身份验证令牌** (`Convai|Settings`）。将后端响应中的 `apiAuthToken` 值连接到 **身份验证令牌** 输入引脚。
{% endstep %}

{% step %}

#### 启动或重新连接会话

如果 **自动初始化会话** 已启用，请在自动初始化触发前设置令牌：对于聊天机器人组件，在 `BeginPlay` 中设置；对于玩家组件，则在全局连接达到 `Connected` 状态之前设置。如果无法确定时机，请禁用 **自动初始化会话** ，并在设置令牌后手动调用 **启动会话** 。

有关手动控制会话，请参阅 [会话生命周期](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/session-lifecycle.md) 。
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="C++" %}
包含 `ConvaiUtils.h` ，并在 Convai 会话启动前设置令牌。调用 `UConvaiUtils::SetAPI_Key(TEXT(""))` 以清除运行时加载到内存中的任何密钥。

请先完成 [打包前清除 API 密钥](#clear-the-api-key-before-packaging) ，以确保随应用发布的 `DefaultEngine.ini` 不包含 `API_Key`.

{% code title="Source/MyProject/Private/PatSessionBootstrap.cpp" %}

```cpp
#include "ConvaiUtils.h"

void ApplyPersonalAccessToken(const FString& ApiAuthToken)
{
    // API_Key takes precedence when non-empty — clear it for PAT-only production builds.
    UConvaiUtils::SetAPI_Key(TEXT(""));
    UConvaiUtils::SetAuthToken(ApiAuthToken);
}
```

{% endcode %}

调用 `ApplyPersonalAccessToken` 在后端 HTTP 请求完成后、 `StartSession` 在聊天机器人或玩家组件上执行之前调用。如果启用了 **自动初始化会话** ，请在启动早期应用令牌：对于聊天机器人，在 `GameMode` 或玩家控制器的 `BeginPlay` 中应用；对于玩家组件，则在全局连接达到 `Connected` 之前应用。
{% endtab %}
{% endtabs %}

{% hint style="danger" %}
切勿从 Unreal 项目中调用 `https://api.convai.com/user/connect` ，因为这需要在客户端构建中包含真实 API 密钥。请勿在打包构建中将 `apiAuthToken` 持久化到磁盘；每次启动时都应从后端获取新令牌。对于短期运行时令牌，优先使用 `UConvaiUtils::SetAuthToken()` 而不是 `UConvaiSettings::SetAuthToken()` 。
{% endhint %}

### 选择 Blueprint 或 C++

这两种方式都会写入同一个 `UConvaiSettings.AuthToken` 字段。设置令牌后，插件的行为完全相同。

| 项目类型                    | 推荐方式                                                                              |
| ----------------------- | --------------------------------------------------------------------------------- |
| 仅使用 Blueprint           | **设置身份验证令牌** 和 **设置 API 密钥** 节点，位于 \`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 密钥、设置令牌并开始对话。

```cpp
// PatKioskBootstrap.cpp — 伪代码模式
void APatKioskBootstrap::OnLearnerSignedIn(const FString& LmsSessionBearer)
{
    Backend->FetchConvaiToken(LmsSessionBearer, [this](const FString& ApiAuthToken)
    {
        UConvaiUtils::SetAPI_Key(TEXT(""));
        UConvaiUtils::SetAuthToken(ApiAuthToken);
        // 应用令牌后，在播放器/聊天机器人组件上调用 StartSession。
    });
}
```

退出登录时，后端可以调用 `/user/revoke-token` 这样 PAT 就无法在共享设备上重复使用。

### 故障排查

| 症状                          | 可能原因                                                    | 解决方法                                                                                                                                                                                                                                                                           |
| --------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 连接立即失败                      | `apiAuthToken` 为 null——后端获取失败                           | 请检查后端 URL、身份验证标头，并确认后端返回了非空的令牌字符串。                                                                                                                                                                                                                                             |
| `401` 连接时出现身份验证错误           | 令牌在 **开始会话**                                            | 在开始会话前立即获取新令牌。                                                                                                                                                                                                                                                                 |
| PAT 被忽略；仍在使用 API 密钥         | `UConvaiSettings.API_Key` 仍在 `Config/DefaultEngine.ini` | 中有值 **从 Convai 编辑器窗口退出登录，在运行时调用** 并传入空字符串，或者在 `API_Key` 中清除该值 `Config/DefaultEngine.ini` ，并在打包前完成。请参阅 [配置 API 密钥](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md#remove-or-clear-the-api-key). |
| 令牌在编辑器中有效，但在打包后的构建中失败       | 打包后的构建仍包含已存储的 API 密钥，或者启动时未获取 PAT                       | 确认运行时令牌获取在自动初始化前完成；从发布配置中清除内嵌密钥。                                                                                                                                                                                                                                               |
| `apiAuthToken` 在后端响应中为 null | 后端调用缺少 `CONVAI-API-KEY` 标头，或请求正文格式错误                    | 确保请求正文为 `{}` ，并且包含该标头。记录后端响应的原始内容。                                                                                                                                                                                                                                             |

### 后续步骤

{% content-ref url="/pages/d6af0b14fc209017d2d18543ad38076bb0efe8f6" %}
[配置你的 API 密钥](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/configure-your-api-key.md)
{% endcontent-ref %}

{% content-ref url="/pages/a8878427b216a80d6b385f1a342c440aa9b398c9" %}
[会话生命周期](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/core-concepts/session-lifecycle.md)
{% endcontent-ref %}

{% content-ref url="/pages/54960e661fc090cc4ab31a059146f22c63a84ad3" %}
[Convai 工具函数](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/blueprint-reference/convai-utility-functions.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/advanced-topics/personal-access-token.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.
