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

# 故障排查

查找 Convai Troubleshooter 窗口，以及 Unity SDK 中安装、API、音频和调试工具的故障排查指南。

本节介绍 SDK 层面的问题——这些问题会在连接 Convai 之前或连接过程中出现，与您使用哪些功能无关。请先打开 Convai Troubleshooter 窗口：它会列出导致 `ConvaiCharacter` 无法正常工作的原因，并在每项检查结果旁提供修复方法，让您无需查看任何 Console 日志行就能排查问题。如果 SDK 已成功连接，但 Actions、Emotion 或 Vision 等特定功能未按预期工作，请先查看相应功能章节中的故障排除页面。本节还涵盖三类常见问题：软件包安装与导入、API 密钥与连接故障、音频与麦克风问题，以及完整的内置诊断工具集。

{% hint style="info" %}
**不确定从哪里开始？** 打开 `Convai → Troubleshooter`，选择角色并查看报告内容——大多数设置错误都会在此处显示，并提供一键修复。如果问题不在角色本身，请打开 Unity Console，查找第一个带有 `[Convai]`标记的错误或警告。如果消息包含点分隔格式的错误代码，例如 `connection.connect_invalid_api_key` 或 `audio.mic_permission_denied` ，请直接前往与其前缀对应的页面。如果看到来自 `Convai Bootstrapper`的普通英文消息，请从“安装与软件包问题”开始排查。
{% endhint %}

### 故障排除分类

<table data-view="cards"><thead><tr><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Convai Troubleshooter</strong><br>此编辑器窗口会按模块报告导致角色无法正常工作的原因，并在每项检查结果旁提供修复方法。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/convai-troubleshooter.md">Convai Troubleshooter</a></td></tr><tr><td><strong>安装与软件包问题</strong><br>软件包导入失败、缺少依赖项、找不到 ConvaiSettings，以及启动时出现的 API 密钥警告。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/installation-and-package-issues.md">安装与包问题</a></td></tr><tr><td><strong>连接与 API 问题</strong><br>API 密钥被拒绝、找不到角色、超时、速率限制、传输错误、重试行为以及运行时诊断。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/connection-and-api-issues.md">连接与 API 问题</a></td></tr><tr><td><strong>音频与麦克风问题</strong><br>麦克风权限失败、设备不可用、音频发布错误，以及 Android、iOS 和 WebGL 的平台特定设置。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/audio-and-microphone-issues.md">音频和麦克风问题</a></td></tr><tr><td><strong>调试工具参考</strong><br>日志配置、日志类别、各模块的编辑器窗口、会话诊断、延迟指标以及自定义日志接收器。</td><td><a href="https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/debug-tools-reference.md">调试工具参考</a></td></tr></tbody></table>

### 特定功能的故障排除

成功连接后出现的问题——即 SDK 正在运行，但某项特定功能表现异常——请参阅各功能章节中的相关文档。

| 功能    | 故障排除页面                                                         |
| ----- | -------------------------------------------------------------- |
| 动作    | `features/character-actions/debugging-and-troubleshooting.md`  |
| 情绪    | `embodiment/emotion/troubleshooting-and-diagnostics.md`        |
| 长期记忆  | `features/long-term-memory/troubleshooting-and-diagnostics.md` |
| 动态上下文 | `features/dynamic-context/troubleshoot-dynamic-context.md`     |
| 叙事设计  | `features/narrative-design/troubleshooting-and-diagnostics.md` |
| 视觉    | `features/vision/troubleshooting-and-diagnostics.md`           |
| 场景元数据 | `features/scene-metadata/troubleshooting-and-diagnostics.md`   |
| 角色化身  | `embodiment/troubleshooting.md`                                |
| 注视    | `embodiment/gaze/troubleshooting.md`                           |
| 身体动画  | `embodiment/body-animation/troubleshooting.md`                 |
| 肢体语言  | `embodiment/body-language/troubleshooting.md`                  |
| 对话流程  | `embodiment/conversation-flow/troubleshooting.md`              |

### 后续步骤

如果问题排查工具无法解释你看到的现象，请使用调试工具。为特定类别启用详细日志记录并查看 `ConvaiRoomManager` 运行时状态，可以缩小大多数剩余问题的排查范围。

{% content-ref url="/pages/683b1f80f2d09bf9f43b94fabdbf62b3dd4466aa" %}
[Convai Troubleshooter](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/convai-troubleshooter.md)
{% endcontent-ref %}

{% content-ref url="/pages/41fb22d336940f24c4bfbf2655c6122580016b9b" %}
[调试工具参考](https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/debug-tools-reference.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/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.
