> 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 故障排查器窗口开始：它会列出是什么在阻止一个 `ConvaiCharacter` 正常工作，并在每个发现项旁边给出修复方法，然后再去看一条 Console 日志。如果 SDK 已成功连接，但某个特定功能（如 Actions、Emotion 或 Vision）没有按预期工作，请先查看该功能章节中的故障排查页面。这里的页面还涵盖三类常见问题：包的安装和导入、API 密钥和连接失败、音频和麦克风问题，以及内置诊断工具的完整套件。

{% hint style="info" %}
**不知道从哪里开始？** 打开 `Convai → 故障排查器`，选择角色，并查看它报告的内容——大多数设置错误都会在那里暴露出来，并附带一键修复。如果问题不在角色上，请打开 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 故障排查器</strong><br>该编辑器窗口会按模块报告是什么在阻止角色工作，并在每个发现项旁边提供修复方法。</td><td><a href="/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="/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="/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="/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="/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](/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting/convai-troubleshooter.md)
{% endcontent-ref %}

{% content-ref url="/pages/41fb22d336940f24c4bfbf2655c6122580016b9b" %}
[调试工具参考](/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.