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

# 排查具身化问题

诊断 Convai 具身化系统中的骨骼检测、预设槽位、模块 Tick 和面部合成问题，并提供修复与验证步骤。

当角色的骨骼绑定未被正确检测到、具身预设未按预期应用、模块似乎始终不更新，或两个模块似乎争用同一种面部表情时，请使用此页面。请先打开 [具身编辑器窗口](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/embodiment-editor.md) ——其中的 `Setup` 选项卡和 `Presets` 选项卡可直接处理大多数此类问题；如果有一键修复选项，也会在此提供。

### 故障排除表

| 症状                                                                                | 可能原因                                                                      | 解决方法                                                                                                            | 验证                                                                   |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| 具身编辑器中的骨骼绑定区域显示 `Not Set Up`                                                      | 未选择任何角色，或所选 `GameObject` 没有 `ConvaiCharacter` 组件                          | 在 Hierarchy 中选择该角色，或将 `ConvaiCharacter` 添加到其 `GameObject`                                                       | 该 `设置` 选项卡的 `骨架` 分区标题更改为 `就绪` 或 `需要注意`                               |
| 骨架分区显示 `需要注意`: "无动画器（可选）" 或 "骨架不是人形"                                              | 该角色没有 `Animator`，或者其骨架未设置为 `Humanoid`                                     | 如果角色不需要骨骼身体动作，可跳过此项；否则，请在模型的导入设置中将骨架类型设为 `Humanoid` 。                                                           | 此问题会被替换为一条 `Ok` 提示，或针对以下对象的骨骼解析提示 `Head`/`LeftEye`/`RightEye`        |
| 骨架部分显示 `需要注意`："无法识别面部骨架"                                                          | `StandardRigBinding.DetectedConvention` 解析为 `未知` ——面部网格与任何已知的混合变形命名约定都不匹配 | 在 `Convention Override` 上 `StandardRigBinding` 组件上手动设置，或分配一个 `CustomRigConventionMap`                           | 此发现会替换为一个 `Ok` 发现，指出所用的约定                                            |
| Rig 部分显示 `Needs Attention`: `…but only just`                                      | `DetectionConfidence` 低于 `50%`                                            | 检查表情和口型同步是否正确；如果不正确，请手动设置约定，而不要依赖自动检测                                                                           | `DetectionConfidence` 由 `StandardRigBinding` 高于 `50%`，或者手动设置约定       |
| “头部”“左眼”或“右眼”骨骼发现显示警告                                                             | 该语义没有映射到骨骼，或该 Rig 不是 Humanoid 类型                                          | 在模型的导入设置中将 Rig 类型设为 `Humanoid` ，或在 `StandardRigBinding`                                                         | `StandardRigBinding.TryGetBone` 对该骨骼返回 `true`，相应警告便不会再出现在控制台中        |
| 每次操作角色时，控制台都会重复显示 Rig 骨骼或混合形状警告                                                   | 首次未找到时出现警告属正常情况——这是 Rig 缺失，并非 Bug                                         | 补齐缺失项（参见上方两行），如果未使用依赖该项的功能，也可以忽略                                                                                | 每个组件生命周期内只记录一次警告，而不是每帧记录，因此状态未改变时不应再次出现                              |
| 一个 `ConvaiEmbodimentPreset` 在 Embodiment Editor 的 `Not Set Up` 中显示为 `Presets` 选项卡 | 预设包含重复的模块 ID、未选择模块的槽位，或指向错误配置文件类型的槽位                                      | 打开预设，并使用发现项的修复按钮，例如 `Remove Duplicate` 或 `Clear Settings`                                                       | 预设在 `Presets` 选项卡中的状态会变为 `Ready` 或 `需要注意`                            |
| 模块的设置与分配给它的预设要求不一致                                                                | `保留缺失槽位` 已启用，且预设中没有该模块的槽位，因此模块保留了通过检查器分配给它的配置文件                           | 在预设中为该模块添加槽位，或禁用 `保留缺失槽位` 如果你希望所有未列出的模块改用其默认配置文件                                                                | 控制台中该角色的预设诊断消息不再将此模块列在“没有预设槽位的活动接收器”下                                |
| 模块似乎从未更新——其状态在运行时始终不变                                                             | 该组件与 `GameObject` 不在同一层级中， `ConvaiCharacter`因此该组件已自行禁用                    | 将该组件移至角色的 `GameObject` 上，或移至其某个子对象上                                                                             | 进入播放模式后，不再出现点名该组件并提示“is not on a Convai character”的控制台错误，且该组件会保持启用状态 |
| 模块正常更新一段时间后，突然停止，且没有任何提示                                                          | 模块的 tick 引发了异常；系统报告一次后便会跳过该模块                                             | 检查控制台中是否有“threw during its embodiment tick”消息，并修复该模块中导致异常的问题                                                    | 修正引发异常的代码并重新进入场景后，模块便会恢复更新                                           |
| 两个模块似乎在争夺同一个面部表情                                                                  | 两个模块正在同一面部区域驱动混合形状，但使用了相互冲突的权重                                            | 检查角色的 `ConvaiFacialCompositionProfile` 中各区域的权重，而不是禁用其中任何一个模块——面部输出是 Emotion、LipSync 和 Custom 图层按区域加权混合的结果，并非互斥锁 | 该区域的混合形状会稳定为一致的表情，而不是明显地来回振荡                                         |

### 未检测到绑定，或置信度较低

Embodiment Editor 的 `Setup` 选项卡会显示角色的 `StandardRigBinding` 在 `Rig` 部分中的状态。如果角色尚未添加该组件，选项卡会显示“将自动处理绑定”——Convai 会在角色启动时立即解析绑定，因此这本身并不是问题。 `StandardRigBinding` 一旦存在

StandardRigBinding `（手动添加，或通过` 按钮添加），其 **设置此角色** 的 `DetectedConvention` 和 `DetectionConfidence` 取决于对角色面部网格的检查。低于 `50%` 的检测置信度会被视为值得核实的猜测：

```
检测到面部绑定为 <convention>，但置信度不高
```

如果完全没有匹配到已知规范， `DetectedConvention` 仍为 `Unknown` ，且选项卡显示：

```
无法识别面部骨架
```

在这两种情况下，请直接在 `约定覆盖` 所在的 `StandardRigBinding` 组件上设置该项；对于不符合任何内置约定的骨架，也可以提供一个 `CustomRigConventionMap` 。完整的检测模型请参阅 [角色骨架设置](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/character-rig-setup.md) 。

缺少骨骼或混合形状时，控制台会在组件的生命周期内记录一次警告：

```
[<character name>] This rig has no '<bone>' bone, so anything that needs it stays inactive. Assign it under Custom Rig Setup on the Character Rig component, or use a rig whose humanoid avatar maps that bone.
```

```
[<character name>] No mesh on this character has a '<blendshape>' blendshape, so anything that drives it stays inactive. Add the blendshape to the face mesh, or map its actual name under Custom Convention Map.
```

这两条消息分别来自 `StandardRigBinding.TryGetBone` 和 `TryGetBlendshape`。相应的骨骼或混合形状被解析到后，或者显式指定覆盖值后，这些消息就不再重复出现。

### 预设槽位不匹配

一个 `ConvaiEmbodimentPreset` 将模块 ID 映射到配置文件资源。预设资源本身可能存在以下两种问题：

* **重复的模块 ID。** 如果预设中同一个模块列出了两次，则只使用第一个匹配的槽位。控制台会记录：

  ```
  Duplicate module profile slots: <ids>. First matching slot is used.
  ```

  在 Embodiment Editor 的 `预设` 选项卡中打开该预设，并移除重复的条目。
* **槽位指定了项目中未安装的模块**、槽位未选择模块，或槽位分配的配置文件类型与模块不匹配。这些问题分别显示在 `预设` 选项卡中，并附有用于移除或清除问题槽位的修复按钮。

此外， `ConvaiEmbodimentPresetBinding` 会将预设与角色上实际存在的模块进行比较，并在发现问题时记录一条综合诊断消息：

```
[ConvaiEmbodimentPresetBinding] Preset '<preset name>' diagnostics on '<character name>': <report>
```

其中 `<report>` 部分可能包含以下任意内容：

* `Profile slots without an active receiver: <ids>.` ——预设配置了角色上不存在的模块。
* `Profile slots with null profiles: <ids>.` ——槽位存在，但未分配配置文件资源。
* `Active receivers without a preset slot; inspector profiles will be preserved: <ids>.` ——在 `保留缺失的槽位` 已启用：没有匹配槽位的模块会保留其自身组件上分配的配置文件。
* `Active receivers without a preset slot; null profiles will be applied: <ids>.` — 在以下情况下显示 `Preserve Missing Slots` 已禁用：没有匹配槽位的模块会回退到 `null`，这会解析为模块内置的默认配置文件。
* `Blank profile slot indices: <indices>.` — 槽位条目完全没有模块 ID。

如果模块的行为与预设所预期的不符，请先检查 `Preserve Missing Slots` 是否已在 `ConvaiEmbodimentPresetBinding` 中启用——它决定未列出的模块是保留自身设置，还是重置为默认值。

### 模块没有运行 Tick

每个具身模块都会在 `OnEnable` 中通过 `EmbodimentContext.RegisterTickable`向角色的 Tick 调度器注册。两种不同的故障看起来相似，但原因不同。

**组件根本没有注册。** 当组件不在与 `GameObject` 相同的层级中时，就会发生这种情况： `ConvaiCharacter`。组件会自行禁用，控制台会记录：

```
[<ComponentType>] '<GameObject name>' 不在 Convai 角色上，因此没有可驱动的对象。请将此组件移到带有 Convai Character 组件的对象上（或其子对象上）。
```

将组件移到角色的 `GameObject` 上，或移到它的某个子对象上，然后重新启用组件。

**组件已注册，但其 Tick 抛出了异常。** 调度器会捕获任一模块 Tick 中的异常，仅报告一次，并继续正常运行其他所有模块的 Tick：

```
[EmbodimentTickScheduler] '<GameObject name>' 上的 <ComponentType> 在具身 Tick 期间抛出了异常，此异常只会报告一次。此角色上的其他模块不受影响。
```

由于每个模块在每次会话中只报告一次，如果某个模块看起来“停止工作”且控制台不再输出任何信息，通常就是这种情况。请从源头修复异常，然后重新进入 Play 模式——修复后模块便会恢复运行。

如果这两条消息都没有出现，但模块看起来仍然毫无反应，请确认场景处于 Play 模式：Tick 调度器只会在运行时创建，因此在 Edit 模式下不会运行任何 Tick，具身编辑器的 `Live` 选项卡除外。

### 模块之间的面部输出冲突

面部 BlendShape 并非由单个模块独占。相反，每个 BlendShape 区域（嘴部、眉毛、眼睛、脸颊/鼻子、下颌及其他区域）都会按照角色的 `ConvaiFacialCompositionProfile`中为各区域设置的权重，将 Emotion、LipSync 和 Custom 图层混合在一起，并分别处理静止和说话状态。

明显的冲突——表情闪烁或过度变化，无法稳定下来——通常意味着两个图层以相近的权重对同一区域提供了相互冲突的值，而不代表某个模块损坏。请检查 `ConvaiFacialCompositionProfile` 中的区域权重，而不是禁用其中一个模块：降低该区域中某个图层的权重，或调整 BlendShape 的名称模式，将其移至其他区域，都可以解决冲突，同时保留模块的其他输出。有关完整的区域权重模型，请参阅 [面部合成](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/facial-composition.md) 。

### 后续步骤

{% content-ref url="/pages/526da9bf1ae481254ffde1d02128e23947af7af5" %}
[具身化编辑器窗口](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/embodiment-editor.md)
{% endcontent-ref %}

{% content-ref url="/pages/dddb9a87015e6befbe3c15caf6aa6b2df224fa33" %}
[角色骨架设置](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/character-rig-setup.md)
{% endcontent-ref %}

{% content-ref url="/pages/260c8f480c6e05ba6ea9db729322298e970606cc" %}
[具身化预设](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/embodiment/embodiment-presets.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/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.
