> 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 密钥** 在这些引擎版本中，项目设置中的字段是只读的。

{% 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 %}

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

打开 **Edit > Project Settings > Plugins > Convai** 并确认 **API 密钥** 字段已填充。该只读字段反映了 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 密钥** 字段中，在 **Edit > Project Settings > Plugins > 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 中手动添加密钥时，也使用相同的文件和节。如果您以后使用 auth token，插件也可以将 `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 %}

#### 确认密钥已移除

打开 **Edit > Project Settings > Plugins > 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。打开 **Edit > Project Settings > Plugins > 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]` 节，并填入来自 [convai.com](https://convai.com):

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

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

{% step %}

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

打开 **Edit > Project Settings > Plugins > Convai**.  **API 密钥** 字段应显示您设置的值。在 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 密钥` 字段已填充，然后从 [添加你的第一个 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 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.