> 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 Unreal Engine 插件使用与您的 Convai 账户绑定的 API 密钥来验证每个会话。在 UE 5.2 及更高版本中，请通过 Convai 编辑器窗口登录——该密钥存储在 `UConvaiSettings.API_Key` 中，并在运行时自动使用。在 UE 5.0 和 5.1 中，请将密钥添加到 `Config/DefaultEngine.ini` ，因为 Convai 编辑器窗口不可用，而且 **API 密钥** 字段在这些引擎版本的项目设置中是只读的。

{% 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 密钥** 字段已填充。此只读字段反映的是由 Convai 编辑器窗口写入的密钥。
{% endstep %}
{% endstepper %}

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

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

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

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

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

在 UE 5.2+ 中登录后，Convai 编辑器窗口会将密钥写入 `DefaultEngine.ini` ，自动完成。 **API 密钥** 下的 **编辑 > 项目设置 > 插件 > 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` 保存到此节中。

不要提交 `Config/DefaultEngine.ini` 当其中包含你的 API 密钥时，不要提交到公共仓库。参见 [连接和 API 密钥问题](/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 %}

参见 [登录并管理你的账户](/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 %}

#### 关闭编辑器

编辑前先关闭 Unreal Editor `Config/DefaultEngine.ini` ，以免在关闭时覆盖该文件。
{% 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。打开 **编辑 > 项目设置 > 插件 > Convai** 并确认 **API 密钥** 字段为空。
{% endstep %}
{% endstepper %}

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

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

### 验证密钥是否处于活动状态

要确认你的 API 密钥是否正常工作，请前往 [添加你的第一个 Convai 角色](/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" %}
[使用个人访问令牌](/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 备用方案

Convai 编辑器窗口在 UE 5.0 或 5.1 中不可用。请将你的 API 密钥添加到 `DefaultEngine.ini`:

{% stepper %}
{% step %}

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

打开 `Config/DefaultEngine.ini` 位于你的项目文件夹中。添加或更新 `[/Script/Convai.ConvaiSettings]` 中的配置节，使用你的 API 密钥。 [convai.com](https://convai.com):

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

编辑文件后请重启编辑器。
{% endstep %}

{% step %}

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

打开 **编辑 > 项目设置 > 插件 > Convai**。 **API 密钥** 字段应显示你设置的值。在 UE 5.0 和 5.1 中，此字段是只读的——请编辑 `DefaultEngine.ini` 以更改密钥。
{% endstep %}
{% endstepper %}

### 故障排查

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

**症状：** 请求失败，并且 `UConvaiSettings.API_Key` 在 **编辑 > 项目设置 > 插件 > Convai**.

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

**修复：** 在 UE 5.2+ 中，请通过 Convai 编辑器窗口重新登录。在 UE 5.0/5.1 中，请编辑 `Config/DefaultEngine.ini` ，按上述说明操作并重启编辑器。

**验证：** 打开 **项目设置 > 插件 > Convai** 并确认 `API 密钥` 字段已填充，然后从 [添加你的第一个 Convai 角色](/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 访问。参见 [网络访问](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/getting-started/prerequisites.md#network-access).

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

### 下一步

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