> 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/troubleshooting/convai-debug-overlay.md).

# 使用 Convai 调试覆盖层检查角色

开启游戏内覆盖层，查看 Convai 角色当前拥有的上下文、事实、周边文本和动作队列。

当角色忽略指令、走向错误的物体，或像从未收到你发送的某个事实一样作答时，最快找出原因的方法不是看你自己的 Blueprint 图，而是看角色实际知道什么。Convai 调试叠加层是一个游戏内面板，它会实时显示角色收到的每个上下文状态、事实和环境句子，以及其当前行动队列。本页将向你展示如何将其开启、选择角色，并结合一个真实问题来读取这些面板。

### 先决条件

* Convai Unreal Engine 插件已安装，并且至少有一个 `UConvaiChatbotComponent` 被放置在关卡中。
* 你正在运行编辑器、在编辑器中运行（PIE），或开发版构建。除非你启用 **允许在 Shipping 构建中使用** （参见 [Convai Debug Overlay 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay-reference.md)).

### 启用叠加层

按 **Ctrl+Alt+K** 在 Play In Editor 或开发版构建中。如果某个文本字段当前拥有键盘焦点，该组合键会被忽略——请先点击视口。

你也可以通过控制台切换叠加层：

```
Convai.DebugOverlay
```

按键组合和控制台命令都会打开同一个叠加层，任意一种方式再次触发都可将其关闭。

{% hint style="info" %}
默认按键是 **K**。如需使用其他按键，或允许在 Shipping 构建中显示叠加层，请打开 **项目设置 > 插件 > Convai** 并修改 **切换键（配合 Ctrl+Alt）** 或 **允许在 Shipping 构建中使用** 在以下位置 **调试覆盖层**。叠加层本身没有单独的开关——切换按键和控制台命令就是全部界面。
{% endhint %}

未选择角色时，标题显示 `Convai 调试 — 无角色`。一旦选择角色，标题会显示它的名称、它是在说话还是空闲，以及它正在看什么，例如 `守卫 · 正在说话 · 正在看向 Crate_03`.

### 选择要检查的角色或对象

叠加层会跟踪每个已注册角色以及每个已注册 `UConvaiObjectComponent` 在关卡中的目标，并在世界空间中用每个角色或对象上方的 ◆ 以及每个已命名、已启用的移动点上方的 ◇ 进行标记。

使用键盘循环选择：

* **PgUp** / **PgDn** — 切换到上一个或下一个项目。
* **Shift** + **PgUp** / **PgDn** — 在循环角色和循环对象之间切换。

所选角色的面板会填充在左侧，其行动队列和结果横幅会在其上方的世界空间中显示。

### 围绕一个问题阅读这些面板

每个面板都回答关于角色所知内容的不同问题。例如，要找出角色在被要求时为什么没有走到箱子旁：

1. 选择角色并检查 **周围环境** 箱子的条目。 `— 已到达` 表示角色上一次前往它的移动已完成； `— 无路径` 表示导航系统找不到路径； `（待刷新）` 表示更新仍在批处理中，尚未发送到 Convai。
2. 检查箱子所在行，查看角色接收到的关于它的原文句子——这是逐字的环境文本，不是摘要，因此你可以准确看到 AI 被告知了什么。
3. 检查角色上方的行动队列。一个 `▶` 表示当前正在执行的动作， `·` 表示其后的排队动作，而 `■ 正在取消 ·` 表示一个正在被取消的动作。动作完成后会显示 2.5 秒的结果横幅，内容为 `<action> — 完成`, `<action> — 失败（<note>）`，或 `<action> — 中止（<note>）`.
4. 检查 **上下文状态** 和 **事实** 查找任何本应影响该决策的状态或事实。每个上下文状态行都有一个脉冲点：红色表示该状态已设置为响应 **总是**，琥珀色表示 **Auto**，灰色表示 **从不** ——某个状态呈灰色脉冲，就解释了为什么角色从未对它作出反应。

**事实** 和 **事件** 在没有内容可显示时会自动折叠，因此它们未出现在面板中本身就很有信息。 **事件** 列出最近六个已提交事件，以及为下一次刷新暂存的内容或作为一次性发送的内容。

有关面板、标签和图形符号的完整列表，请参见 [Convai Debug Overlay 参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay-reference.md).

### 验证叠加层正在显示实时数据

触发你正在调试的行为——发送上下文更新、移动角色，或等待一个动作完成——并确认相关面板会在一两秒内更新。

{% hint style="success" %}
当你触发事件时会更新的面板，说明叠加层读取的是所选角色的实时状态，而不是缓存快照。
{% endhint %}

### 故障排查

#### 叠加层未出现

**症状：** 按下 **Ctrl+Alt+K** 或运行 `Convai.DebugOverlay` 没有任何反应。

**原因：** 你当前处于 Shipping 或 Test 构建，并且 **允许在 Shipping 构建中使用** 处于关闭状态，或者某个文本字段当前拥有键盘焦点并吞掉了该按键组合。

**解决方法：** 点击视口以清除文本字段焦点，然后再试一次该组合键。如果你正在测试 Shipping 或 Test 构建，请启用 **允许在 Shipping 构建中使用** 在以下位置 **项目设置 > 插件 > Convai > 调试叠加层** 并重新打包。

**验证：** 标题行 `Convai 调试 — 无角色` （或角色名称）出现在屏幕上。

#### 某个面板始终为空

**症状：** **事实** 或 **事件** 从未在所选角色上出现。

**原因：** 当没有内容可显示时，这两个面板都会折叠——该角色确实还没有任何事实或已提交事件。

**解决方法：** 向角色发送一个事实或上下文事件，并在其有内容后确认面板是否出现。

**验证：** 更新生效后，面板标题会出现在其各行上方。

### 下一步

{% content-ref url="/pages/61a7a55de479c504fcaf2d229f7ccf1970d311e4" %}
[Convai 调试覆盖层参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay-reference.md)
{% endcontent-ref %}

{% content-ref url="/pages/2c318643919de48c794a1f4b6b1eb25b6e0ed166" %}
[故障排查](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting.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, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.