> 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/getting-started/configure-your-api-key.md).

# 配置你的 API 密钥

通过 Convai 编辑器窗口登录以存储你的 API 密钥，并允许插件向 Convai 发送已认证请求。

Convai Unreal Engine 插件使用与您的 Convai 账户关联的 API 密钥对每个会话进行身份验证。在 UE 5.2 及更高版本中，通过 Convai 编辑器窗口登录——密钥会存储在 `UConvaiSettings.API_Key` 中，并在运行时自动使用。在 UE 5.0 和 5.1 中，请将密钥添加到 `Config/DefaultEngine.ini` 中，因为这些引擎版本不提供 Convai 编辑器窗口，而且项目设置中的 **API Key** 字段为只读。

{% hint style="info" %}
Convai 编辑器窗口需要 **Unreal Engine 5.2 或更高版本**。如果您使用的是 UE 5.0 或 5.1，请跳转至 [UE 5.0 和 5.1 的备用方案](#ue-5-0-and-5-1-fallback).
{% endhint %}

### 通过 Convai 编辑器窗口登录（UE 5.2+）

启用插件并重启编辑器后，Convai 编辑器窗口会自动打开。按照该窗口中的登录流程操作——除非窗口没有出现，否则无需手动打开。

{% stepper %}
{% step %}

#### 完成自动登录提示

编辑器重新打开后，Convai 编辑器窗口会显示登录表单。使用您的 Convai 账户凭据登录。如果您还没有账户，请前往 [convai.com](https://convai.com).
{% endstep %}

{% step %}

#### 确认身份验证

身份验证完成后，Convai 编辑器窗口会显示您的账户仪表板。API 密钥会自动存储——无需另行保存。
{% endstep %}

{% step %}

#### 在项目设置中验证密钥

打开 **编辑 > 项目设置 > 插件 > Convai** 并确认 **API Key** 字段中已填入密钥。此只读字段会显示 Convai 编辑器窗口写入的密钥。
{% endstep %}
{% endstepper %}

{% hint style="success" %}
您的 API 密钥现已存储。Convai 编辑器窗口会显示您的账户仪表板——您已通过身份验证，可以开始使用该插件。
{% endhint %}

如果重启后 Convai 编辑器窗口没有打开，请点击工具栏中的 **Convai 编辑器** 按钮，或选择 **窗口 > Convai > 打开 Convai 编辑器**.

### API 密钥在本地的存储位置

通过 Convai 编辑器窗口登录并不会仅将 API 密钥保存在内存中。插件会将密钥保存到磁盘上的项目中。

| 项目    | 位置                                            |
| ----- | --------------------------------------------- |
| 配置文件  | `Config/DefaultEngine.ini` （位于 Unreal 项目文件夹中） |
| 配置节   | `[/Script/Convai.ConvaiSettings]`             |
| 字段名称  | `API_Key`                                     |
| 运行时对象 | `UConvaiSettings.API_Key` （从该配置节加载）           |

在 UE 5.2+ 中登录后，Convai 编辑器窗口会自动将密钥写入 `DefaultEngine.ini` 。 **API Key** 字段位于 **编辑 > 项目设置 > 插件 > Convai** 下方，为只读字段——它显示保存在该文件中的值。

以下是 `Config/DefaultEngine.ini`:

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

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

{% endcode %}

在 UE 5.0 和 5.1 中手动添加密钥时，也会使用相同的文件和节。如果之后使用身份验证令牌，插件也可以将 `AuthToken` 持久化到此节中。

请勿将包含 API 密钥的 `Config/DefaultEngine.ini` 提交到公共代码仓库。有关版本控制的指导，请参阅 [连接和 API 密钥问题](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/connection-and-api-key-issues.md) 。

### 移除或清除 API 密钥

切换 Convai 账户、从共享项目中移除 Convai，或准备不应包含已存储 API 密钥的构建版本时，请清除密钥。

{% tabs %}
{% tab title="Convai 编辑器窗口（UE 5.2+）" %}
{% stepper %}
{% step %}

#### 打开账户菜单

在 Convai 编辑器窗口中，点击右上角的账户控件（显示账户名称中的两个字母）。
{% endstep %}

{% step %}

#### 退出登录

选择 **退出登录**。插件会清除 `API_Key`, `AuthToken`以及此项目的缓存账户详细信息，并将空值写回 `Config/DefaultEngine.ini`.
{% endstep %}

{% step %}

#### 确认密钥已移除

打开 **编辑 > 项目设置 > 插件 > Convai** 并确认 **API 密钥** 字段为空。需要重新连接 Convai 账户时，请再次登录。
{% endstep %}
{% endstepper %}

有关完整的退出登录流程，请参阅 [登录并管理账户](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/editor-window/sign-in-and-manage-your-account.md) 。
{% endtab %}

{% tab title="DefaultEngine.ini（所有 UE 版本）" %}
{% stepper %}
{% step %}

#### 关闭编辑器

编辑 `Config/DefaultEngine.ini` 之前，请先关闭 Unreal Editor，以免文件在关闭时被覆盖。
{% endstep %}

{% step %}

#### 清除凭据字段

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

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

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

{% endcode %}
{% endstep %}

{% step %}

#### 重新启动编辑器

重新启动 Unreal Editor。打开 **Edit > Project Settings > Plugins > Convai** 并确认 **API Key** 字段为空。
{% endstep %}
{% endstepper %}

UE 5.0 和 5.1，或需要在不打开 Convai 编辑器窗口的情况下移除密钥时，请使用此方法。
{% endtab %}
{% endtabs %}

对于打包后的应用， `DefaultEngine.ini` 会包含在构建中。如果运行时改用 `API_Key` 个人访问令牌 [，请在打包前清除此项。](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/advanced-topics/personal-access-token.md) 。

### 验证密钥是否有效

若要确认 API 密钥是否正常工作，请继续执行 [添加你的第一个 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) 并完成对话测试。

### 为生产环境准备身份验证

上述 API 密钥流程是在编辑器中验证插件以及在早期开发阶段进行测试的最快方式。发布 **打包后的应用**时，请避免将真实 API 密钥嵌入构建中——打包后的项目文件和配置可能会被检查。

对于生产构建，请改用 **个人访问令牌** 流程：由后端存储真实 API 密钥，生成一个短期有效的 `apiAuthToken`，并由 Unreal 项目在 Convai 会话开始前于运行时设置该令牌。请勿在打包构建中附带真实 API 密钥。

{% content-ref url="/pages/136ee5d4e230ae7a3080e60ffdf751abe96f1cb8" %}
[使用个人访问令牌](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/advanced-topics/personal-access-token.md)
{% endcontent-ref %}

### UE 5.0 和 5.1 的备用方法

UE 5.0 或 5.1 不提供 Convai 编辑器窗口。请将 API 密钥添加到 `DefaultEngine.ini`:

{% stepper %}
{% step %}

#### 将密钥添加到 DefaultEngine.ini

在项目文件夹中打开 `Config/DefaultEngine.ini` 。在 `[/Script/Convai.ConvaiSettings]` 部分中添加或更新从 [convai.com](https://convai.com):

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

获取的 API 密钥。
{% endstep %}

{% step %}

#### 在项目设置中验证密钥

编辑文件后，重新启动编辑器。 **Edit > Project Settings > Plugins > Convai**。 **API Key** 字段应显示你设置的值。在 UE 5.0 和 5.1 中，此字段为只读状态——请编辑 `DefaultEngine.ini` 以更改密钥。
{% endstep %}
{% endstepper %}

### 故障排查

#### 登录后 API 密钥为空

**症状：** 请求失败，且 `UConvaiSettings.API_Key` 在 **Edit > Project Settings > Plugins > Convai 中为空**.

**原因：** 登录未完成，或密钥从未保存。

**解决方法：** 在 UE 5.2 及更高版本中，通过 Convai 编辑器窗口重新登录。在 UE 5.0/5.1 中，编辑 `Config/DefaultEngine.ini` （如上所述），然后重启编辑器。

**验证：** 打开 **项目设置 > 插件 > Convai** 并确认 `API Key` 字段已填写，然后通过 [添加你的第一个 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 账户未激活或已被暂停。

**解决方法：** 登录 [convai.com](https://convai.com) 并确认账户状态。

**验证：** 通过 Convai 编辑器窗口重试登录。

#### 网络访问受阻

**症状：** 登录或运行时请求超时。

**原因：** 编辑器无法通过 HTTPS 连接到 Convai。

**解决方法：** 确认出站 HTTPS 访问正常。请参阅 [网络访问](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/prerequisites.md#network-access).

**验证：** 恢复网络访问后重试登录。

### 后续步骤

{% content-ref url="/pages/47cd8b5064f2e1f1738f08d50b1097ad47ed212c" %}
[添加你的第一个 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)
{% 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/getting-started/configure-your-api-key.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.
