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

Convai 编辑器窗口需要 Unreal Engine 5.2 或更高版本。如果你使用的是 UE 5.0 或 5.1，请跳到 UE 5.0 和 5.1 备用方案.

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

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

1

完成自动登录提示

当编辑器重新打开时，Convai 编辑器窗口会显示登录表单。使用你的 Convai 账户凭据登录。如果你还没有账户，请在以下地址创建一个： convai.com.

2

确认身份验证

身份验证完成后，Convai 编辑器窗口会显示你的账户仪表板。你的 API 密钥会自动保存——无需单独执行保存步骤。

3

在项目设置中验证密钥

打开 编辑 > 项目设置 > 插件 > Convai 并确认 API 密钥 字段已填充。此只读字段反映的是由 Convai 编辑器窗口写入的密钥。

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

如果重启后 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:

Config/DefaultEngine.ini

[/Script/Convai.ConvaiSettings]
API_Key=your_api_key_here

当你在 UE 5.0 和 5.1 中手动添加密钥时，也会使用同一个文件和节。如果你之后使用身份验证令牌，该插件还可以将 AuthToken 保存到此节中。

不要提交 Config/DefaultEngine.ini 当其中包含你的 API 密钥时，不要提交到公共仓库。参见 连接和 API 密钥问题 以获取版本控制指导。

移除或清除 API 密钥

在切换 Convai 账户、从共享项目中移除 Convai，或准备一个不应随构建发布已存储 API 密钥的版本时，请清除该密钥。

Convai 编辑器窗口（UE 5.2+）

1

打开账户菜单

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

2

注销

选择 注销。插件会清除 API_Key, AuthToken以及此项目的缓存账户信息，并将空值写回 Config/DefaultEngine.ini.

3

确认密钥已移除

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

参见 登录并管理你的账户 以查看完整的注销流程。

DefaultEngine.ini（所有 UE 版本）

对于打包应用， DefaultEngine.ini 会包含在构建中。请在打包前清除 API_Key 如果你使用的是 个人访问令牌 并在运行时使用它替代。

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

要确认你的 API 密钥是否正常工作，请前往 添加你的第一个 Convai 角色 并完成对话测试。

为生产环境准备身份验证

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

对于生产构建，请使用 个人访问令牌 流程替代：你的后端存储真实的 API 密钥，并生成一个短期有效的 apiAuthToken，然后 Unreal 项目在 Convai 会话开始前于运行时设置该令牌。不要在打包构建中发布真实的 API 密钥。

使用个人访问令牌

UE 5.0 和 5.1 备用方案

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

1

将密钥添加到 DefaultEngine.ini

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

[/Script/Convai.ConvaiSettings]
API_Key=your_api_key_here

编辑文件后请重启编辑器。

2

在项目设置中验证密钥

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

故障排查

登录后 API 密钥为空

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

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

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

验证： 打开 项目设置 > 插件 > Convai 并确认 API 密钥 字段已填充，然后从 添加你的第一个 Convai 角色.

账户未激活

症状： 登录失败，或请求被拒绝。

原因： Convai 账户未激活或已被暂停。

修复： 登录 convai.com 并确认你的账户状态。

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

网络被阻止

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

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

修复： 确认出站 HTTPS 访问。参见 网络访问.

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

下一步

添加你的第一个 Convai 角色