> 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).

# 故障排查

本节涵盖在 SDK 层面发生的问题——无论你使用哪些功能，都会在连接到 Convai 之前或连接过程中出现。请先查看 Convai 故障排查器窗口：它会列出正在阻止一个 `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 启动器`的纯英文消息，请从安装与包问题开始。
{% 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="/pages/683b1f80f2d09bf9f43b94fabdbf62b3dd4466aa">/pages/683b1f80f2d09bf9f43b94fabdbf62b3dd4466aa</a></td></tr><tr><td><strong>安装与包问题</strong><br>包导入失败、缺少依赖项、找不到 ConvaiSettings，以及启动时的 API 密钥警告。</td><td><a href="/pages/e10ea397187f53bca813a256eac60d9e5c816b9a">/pages/e10ea397187f53bca813a256eac60d9e5c816b9a</a></td></tr><tr><td><strong>连接和 API 问题</strong><br>API 密钥被拒绝、找不到角色、超时、速率限制、传输错误、重试行为以及运行时诊断。</td><td><a href="/pages/07c0ce6cfe225bcb17f8209c5187483d2497d1a4">/pages/07c0ce6cfe225bcb17f8209c5187483d2497d1a4</a></td></tr><tr><td><strong>音频和麦克风问题</strong><br>麦克风权限失败、设备不可用、音频发布错误，以及 Android、iOS 和 WebGL 的平台特定设置。</td><td><a href="/pages/748d5aef4b035086919756d0ceedf7f3497a0117">/pages/748d5aef4b035086919756d0ceedf7f3497a0117</a></td></tr><tr><td><strong>调试工具参考</strong><br>日志配置、日志类别、按模块划分的编辑器窗口、会话诊断、延迟指标以及自定义日志接收端。</td><td><a href="/pages/41fb22d336940f24c4bfbf2655c6122580016b9b">/pages/41fb22d336940f24c4bfbf2655c6122580016b9b</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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.convai.com/api-docs/zh/cha-jian-yu-ji-cheng/convai-unity-sdk/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.