> 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 Debug Overlay 是一个游戏内面板，可实时显示角色收到的所有上下文状态、事实和环境描述句，以及当前的动作队列。本页将介绍如何启用它、选择角色，并结合一个实际问题查看各个面板。

### 前提条件

* 已安装 Convai Unreal Engine 插件，并且关卡中至少放置了一个 `UConvaiChatbotComponent` 。
* 你正在运行编辑器、Play In Editor (PIE) 或 Development 构建版本。除非启用 **Allow In Shipping Builds** （参见 [Convai Debug Overlay 参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay-reference.md)).

### 启用叠加层

在 Play In Editor 或 Development 构建版本中按 **Ctrl+Alt+K** 。如果当前键盘焦点位于文本字段中，则该快捷键组合会被忽略——请先点击视口。

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

```
Convai.DebugOverlay
```

快捷键组合和控制台命令都会打开同一个叠加层，且再次使用其中任意一种方式都可将其关闭。

{% hint style="info" %}
默认按键为 **K**。若要使用其他按键，或允许在 Shipping 构建版本中使用叠加层，请打开 **Project Settings > Plugins > Convai** 并更改 **Toggle Key (with Ctrl+Alt)** 或 **Allow In Shipping Builds** （位于 **Debug Overlay**下）。叠加层本身没有单独的开关——快捷键和控制台命令就是全部的操作方式。
{% endhint %}

未选择角色时，标题栏显示 `Convai Debug — no character`。选择角色后，标题栏会显示其名称、正在交谈还是空闲，以及它正在注视的对象，例如 `Guard · TALKING · looking at Crate_03`.

### 选择要检查的角色或物体

叠加层会追踪关卡中所有已注册的角色和 `UConvaiObjectComponent` ，并在世界空间中标记每个角色或物体上方的 ◆，以及每个已命名且启用的移动点上方的 ◇。

使用键盘切换选择项：

* **PgUp** / **和** —切换到上一项或下一项。
* **按住 Shift** + **再按 PgUp** / **或 PgDn** —在切换角色和切换物体之间切换。

所选角色的面板会显示在左侧，其动作队列和结果栏则会显示在角色上方的世界空间中。

### 结合问题查看面板

每个面板都回答一个关于角色所知信息的问题。例如，若要查明角色在被要求走向板条箱时为何没有移动：

1. 选择角色并查看 **SURROUNDINGS** 中是否有该板条箱的条目。 `— reached` 表示角色上一次移动到该处已完成； `— 无路径` 表示导航系统未能找到路线； `（等待刷新）` 表示更新仍处于批处理中，尚未发送到 Convai。
2. 查看 crate 对应的行，了解角色收到的关于它的确切句子——这是原样的周边环境文本，而非摘要，因此你可以准确看到 AI 收到了什么信息。
3. 查看角色上方的操作队列。 `▶` 表示当前正在执行的操作， `·` 表示其后的排队操作，而 `■ cancelling ·` 表示正在取消的操作。操作完成后会显示 2.5 秒的结果提示，内容为 `<action> — done`, `<action> — failed (<note>)`或 `<action> — aborted (<note>)`.
4. 查看 **上下文状态** 和 **事实** ，确认是否存在本应影响该决策的状态或事实。每个上下文状态行都有一个脉冲指示点：红色表示该状态设置为 **始终**响应，琥珀色表示 **自动**响应，灰色表示 **从不** 响应——状态指示点呈灰色，说明角色为何从未对此作出反应。

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

有关面板、标签和图标的完整列表，请参阅 [Convai 调试叠加层参考](https://docs.convai.com/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 构建，且 **Allow In Shipping Builds** 已关闭；或者文本字段当前拥有键盘焦点，拦截了该快捷键组合。

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

**验证：** 标题行 `Convai Debug — no character` （或角色名称）会显示在屏幕上。

#### 面板为空

**症状：** **事实** 或 **事件** 从未显示在已选角色的面板中。

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

**解决方法：** 向角色发送一条事实或上下文事件，并确认面板在有内容后会显示。

**验证：** 更新生效后，面板标题会显示在其条目上方。

### 后续步骤

{% content-ref url="/pages/61a7a55de479c504fcaf2d229f7ccf1970d311e4" %}
[Convai 调试覆盖层参考](https://docs.convai.com/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" %}
[故障排查](https://docs.convai.com/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 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/troubleshooting/convai-debug-overlay.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.
