> 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-unity-sdk/embodiment/gaze/troubleshooting.md).

# 排查视线问题

修复 Convai Gaze 角色中静止的眼睛、不会转动的头部、未选中的视线目标以及被拒绝的脚本视线。

从角色本身开始诊断： `ConvaiGazeController` 检查器中的 **设置** 部分和 **Convai > 凝视编辑器**的 **设置** 选项卡会报告相同的骨架检查结果——哪些骨骼已解析、当前使用哪个眼部后端，以及朝向检查结果——这些都可以在按下 Play 之前查看。本页介绍报告中未说明的症状，以及下文列出的运行时行为。

### 症状、原因和解决方法

| 症状                                 | 可能原因                                                                                                                      | 解决方法                                                                                                                             | 验证                                                                                                 |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| 眼睛始终不动，只有头部会转动                     | 未找到眼部骨骼，也未解析出完整的 `EyeLook*` 混合形状集合，因此凝视控制退回到仅头部运动                                                                         | 为骨架映射 `LeftEye`/`RightEye` 骨骼，或提供全部四个水平方向的 `EyeLook*` 形状（`EyeLookInLeft`, `EyeLookOutLeft`, `EyeLookInRight`, `EyeLookOutRight`) | 设置选项卡中的 **眼部后端** 行会显示骨骼或混合形状数量，而不是仅头部运动警告                                                          |
| 头部和眼睛始终停留在动画设置的位置                  | 角色上没有 `ConvaiGazeController` ，或者未解析出语义头部骨骼                                                                                | 添加 `ConvaiGazeController` (**添加组件 > Convai > 具身化 > 凝视**）；对于 Generic 或不带动画器的骨架，添加 **Convai > 具身化 > 角色骨架** 并指定 Head                | 控制台中指出缺少 Head 骨骼的警告消失，检查器显示 **就绪**                                                                 |
| 始终不会选择世界中的物体作为凝视目标                 | 物体没有 `ConvaiGazeTarget`，或者其优先级（默认 `5`）始终不高于玩家锚点的 `10`                                                                     | 添加 `ConvaiGazeTarget` (**添加组件 > Convai > 凝视 > 目标**）；提高 **优先级** 至高于 `10` 优先级高于玩家                                                  | 选中时，对象会显示线框操纵器，并会作为当前目标显示在 Gaze Editor 的 **实时** 选项卡中                                               |
| `GazeAt`/`GlanceAt` 调用不会产生可见效果     | `GazeFocusFidelity.Exact` 处于活动状态，且启用了 `AllowScriptedOverridesDuringExactFocus` 关闭，或者 `LockBlocksGlances` 在眼神接触锁定期间吸收了一次瞥视 | 启用 `AllowScriptedOverridesDuringExactFocus` 如果脚本请求必须优先于 Exact 焦点，则在控制器上启用 `LockBlocksGlances` 如果瞥视应中断锁定，而不是被纳入其中，则将其关闭           | `GazeHandle.Outcome` 读取 `Taken` 而不是 `Interrupted` 或 `HeldEyeContactInstead`，并且 `Settled` 完成 `true` |
| 本应符合已知规范的设备框架却显示为 Custom 或 Generic | 未匹配到 ARKit/CC3/CC4 Extended/MetaHuman 命名规范，因此骨骼是按名称解析为候选项，而非根据已编写的映射进行解析                                                  | 添加 `StandardRigBinding` (**Convai > Embodiment > Character Rig**) 并验证 Head/Eye 分配，或者为非标准命名规范编写 `CustomRigConventionMap` 。        | Setup 选项卡会显示已编写的映射，而不是 Info 级别的“候选项”发现项                                                            |
| 角色始终不会从玩家身后转过身体面向玩家                | Head & Body 阶梯中的脚部阶段始终不会激活，或者重复的绑定会阻止骨架解析                                                                                 | 确认恰好有一个 `StandardRigBinding` 位于角色的 `EmbodimentContext` 根节点下；检查配置文件中的 **头部和身体** 脚部设置                                              | 当玩家在角色头部/视线范围之外与其交谈时，角色会转向玩家                                                                       |

### 头部转动时，眼睛保持静止

眼睛运动取决于已解析的眼睛后端，而后端的选择具有确定性：一对 `LeftEye`/`RightEye` 骨骼映射优先，其次是完整的双眼 `EyeLook*` Blendshape 集（包含全部四个 `EyeLookInLeft`, `EyeLookOutLeft`, `EyeLookInRight`, `EyeLookOutRight`），否则注视会平滑降级为仅头部运动。不会单独驱动仅解析到的一根眼部骨骼或不完整的方向集合——Setup 选项卡会报告 `Only one eye bone resolved and no complete binocular EyeLook* backend was found, so gaze safely uses the head-only backend` （若出现这种情况），或者 `No eye bones and no EyeLook* blendshapes were found — the eye stage will gracefully use head-only gaze` （若两者均未解析到）。映射缺失的眼部骨骼，或创建完整的四个形状，然后重新检查 Setup 选项卡。

如果配置文件的 **Eye Actuation Mode** 被强制设为特定后端，而不是保持为 **Auto**，则当强制模式与绑定实际支持的功能不匹配时，会记录 `Eye backend forced to Bones but no LeftEye/RightEye bone pair was resolved` 或 `Eye backend forced to Blendshapes but no EyeLook* shapes were resolved` ——将模式切回 **Auto** ，或修正绑定映射。

### 头部不会转向目标

如果完全未解析到语义绑定， `ConvaiGazeController` 会记录 `No semantic rig binding could be resolved. Add StandardRigBinding to the character root and map Head (plus optional Neck/Eyes); gaze stays inert until a binding exists.` 如果存在 `StandardRigBinding` 但其 Head 字段为空，则消息会改为 `Rig binding has no semantic Head mapping. Assign Head in StandardRigBinding or use a recognized bone name; head/eye gaze stays inert until Head resolves.` Gaze Inspector 的 Setup 选项卡会在进入 Play 模式前报告同样的情况： `No Head bone is mapped — head/eye gaze stays inert until it exists`。无论是哪种情况，都请在 **Convai > Embodiment > Character Rig**中指定 Head，或确认绑定使用了可识别的骨骼名称，以便通过名称回退机制找到它。缺少 Neck 骨骼不会造成阻碍——头部会独自完成全部转动，动作会稍显僵硬——且只会产生一条提示信息。

### 始终无法选中目标

在考虑相关性或距离之前，目标会先按优先级分层竞争：玩家锚点发布的优先级为 `10`，其他 Convai 角色为 `7`，而 `ConvaiGazeTarget`/`WorldObjectGazeTargetProvider` 世界物体的默认优先级为 `5`。角色正在对话时，优先级低于玩家层级的世界物体不会胜出——这是预期行为，并非错误。请确认物体确实挂有 `ConvaiGazeTarget` （拖放即可，无需其他设置），位于其配置的 **Max Distance**范围内，并确认其 **Base Relevance** 大于零。提高 **优先级** 以上 `10` 仅当对象应完全压过玩家时使用（即“关注这里”式的故事情境）。如果角色上完全没有目标提供器，且 **自动创建玩家锚点** 处于关闭状态，设置选项卡会显示 `No target provider exists and auto-creation is off — the character will only show ambient idle life`；请启用该开关，或手动添加目标提供器。

### 脚本控制的注视被拒绝或吸收

`GazeAt` 和 `GlanceAt` 请求与眼神接触锁定的交互方式有意不同。在 `GazeFocusFidelity.Exact`模式下，显式的 `GazeAt` 会被直接拒绝，其 `GazeHandle` 会立即以 `Outcome == Interrupted` 完成，除非启用了 `AllowScriptedOverridesDuringExactFocus` ——这是为信息亭和演示者场景有意设计的，这些场景必须始终保持注视焦点。在 `GazeFocusFidelity.Social`, `GazeAt` 模式下仍会抢占锁定，因此此时请求被拒绝说明原因另有所在（目标始终未能解析，或请求立即被后续请求取代）。

`GlanceAt` 遵循单独的标志：当眼神接触锁定处于活动状态且 `LockBlocksGlances` 已开启（默认值）时，扫视请求会被吸收——其句柄会以 `Outcome == HeldEyeContactInstead` 完成，但扫视实际上不会发生，因为角色选择与对方保持眼神接触，而不是看向该物体。关闭 `LockBlocksGlances` 此选项即可让扫视改为中断锁定。

### 未检测到骨架惯例

`ConvaiGazeController` 通过 `StandardRigBinding`解析骨骼；如果失败，则回退到 Humanoid Avatar 映射，再回退到内置的通用名称列表。如果既没有手动设置的绑定，也没有 Humanoid Avatar，设置选项卡会将已解析的骨骼标记为 **候选** 而非已验证的映射——这表示找到了可识别的名称，但尚未确认。请添加 **Convai > Embodiment > Character Rig**，使用 **捕获已解析的映射** 作为起点，并在发布前验证每项 Head/Eye（头部/眼睛）分配。角色的 `StandardRigBinding` 下方应当恰好有一个 `EmbodimentContext` 根对象：如果存在重复组件，系统会拒绝并显示 `Multiple Character Rig components exist under this character. Keep exactly one on the Embodiment Context root`，因为根对象绑定具有权威性；系统会拒绝含糊不清的设置，而不会自行猜测。

如果骨架的头部骨骼未将局部 +Z 设为角色的视觉前方、+Y 设为上方，那么无论匹配到哪种惯例，角色都会朝侧面瞄准。请使用设置选项卡中的骨架报告测量角度，并在发布前通过场景视图中编辑模式下的前向射线辅助图标确认修复效果。

### 身体不会转动

全身转动是头部与身体阶梯式转向的最后阶段——只有当头部和胸部都已尽可能分担转向后，双脚才会参与。因此，目标若处于头部、眼睛或胸部的可及范围内，就根本不会带动身体；这是预期行为。如果目标确实需要身体转向，但角色没有转动，请确认角色当前没有处于行走途中：移动时，角色朝向由移动系统控制，注视驱动的身体转向会有意暂停，以避免两个系统争夺同一旋转。如果存在 Body Animation 模块，身体转向会使用原地转向动画片段，并且需要 **启用原地转身** 在其配置中启用；如果没有该模块，或该模块拒绝执行，则会自动改用程序化根节点转身，并且只记录一次回退日志。如果目标位于头部和眼睛转动身体后仍无法触及的范围之外，跟踪日志会记录 `Gaze cannot fully reach '<target>' — sustained N° residual (target outside the head/eye envelope)` 在 `State` 详细级别下显示。这是可诊断的目标不可达情况，而非静默失败。

### 了解角色正在注视谁

ConvaiGazeController `检查器的` 实时 **部分、** 标签页中的 **部分、** Convai > Gaze Editor **，以及**Convai.DiagnoseGaze `MCP 工具都会报告相同的两项事实，因此这三者中的任意一个都能回答“为什么它没看着我”：` 目标偏离

* **表示眼睛实际注视方向与当前目标之间的角度，单位为度。几度以内的小数值属于正常的扫视和注视噪声；持续偏大的数值则说明目标超出角色实际可触及的范围，或者目标始终未能解析。** 跟随对话
* **会指出角色因** 正在注视谁，或指出阻止其注视某位潜在说话者的门控条件——例如“超出注意距离”“位于该角色身后太远”或“对方未发布注视目标”。如果角色本应转向正在说话的同事却没有这样做，它会指出阻止转向的门控条件，而不是对失败保持沉默。 `AttendToSpeaker`，或指出阻止其注视某位潜在说话者的门控条件——例如“超出注意距离”“位于该角色身后太远”或“对方未发布注视目标”。如果角色本应转向正在说话的同事却没有这样做，它会指出阻止转向的门控条件，而不是对失败保持沉默。

### 后续步骤

{% content-ref url="/pages/9c0e7e779a031a76bbc0834723ae50337d8d6836" %}
[视线](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze.md)
{% endcontent-ref %}

{% content-ref url="/pages/864133eda5776302d8f8f9afeef2de62388e08bc" %}
[视线目标与提供器](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/targets-and-providers.md)
{% endcontent-ref %}

{% content-ref url="/pages/0c6914a280e6fc584ecfe676625883fc201033e3" %}
[脚本控制的视线](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/gaze/scripted-gaze.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-unity-sdk/embodiment/gaze/troubleshooting.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.
