> 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 调试覆盖层参考](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unreal-engine-plugin/troubleshooting/convai-debug-overlay-reference.md)).

### 启用覆盖层

按 **Ctrl+Alt+K** 在编辑器内运行或开发版本中使用。如果某个文本字段当前拥有键盘焦点，则该组合键会被忽略——请先单击视口。

你也可以通过控制台使用以下命令切换覆盖层：

```
Convai.DebugOverlay
```

这个组合键和控制台命令都会打开同一个覆盖层，任意一种方式再次使用都会将其关闭。

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

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

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

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

使用键盘循环切换选择：

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

所选角色的各个面板会显示在左侧，而它的动作队列和结果横幅会以世界空间方式显示在其上方。

### 结合一个问题来解读这些面板

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

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

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

有关面板、标签和符号的完整列表，请参见 [Convai 调试覆盖层参考](/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 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.