> 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 之前或期间发生的问题——无论你正在使用哪些功能。如果 SDK 已成功连接，但某个特定功能（如 Actions、Emotion 或 Vision）未按预期工作，请先查看该功能章节中的故障排除页面。这里的页面涉及四类常见问题：包安装与导入、API 密钥和连接失败、音频和麦克风问题，以及完整的一套内置诊断工具。

{% hint style="info" %}
**不确定从哪里开始？** 打开 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>安装和包问题</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>日志配置、日志类别、ConvaiActionDebugProbe、会话诊断、延迟指标以及自定义日志接收端。</td><td><a href="/pages/41fb22d336940f24c4bfbf2655c6122580016b9b">/pages/41fb22d336940f24c4bfbf2655c6122580016b9b</a></td></tr></tbody></table>

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

在成功连接后出现的问题——也就是 SDK 正在运行，但某个特定功能行为不正确——都会记录在各自功能的章节中。

| 功能     | 故障排除页面                                                       |
| ------ | ------------------------------------------------------------ |
| 动作     | `features/actions/troubleshooting.md`                        |
| 情绪     | `features/emotion/troubleshooting.md`                        |
| 长期记忆   | `features/long-term-memory/troubleshooting.md`               |
| 动态上下文  | `features/dynamic-context/troubleshooting.md`                |
| 叙事设计   | `features/narrative-design/troubleshooting.md`               |
| 视觉     | `features/vision/troubleshooting.md`                         |
| 场景元数据  | `features/scene-metadata/troubleshooting-and-diagnostics.md` |
| 对话动画   | `utilities/dialogue-animation/troubleshooting.md`            |
| 凝视与注意力 | `utilities/gaze-and-attention/troubleshooting.md`            |

### 下一步

当一个问题仅凭单条错误消息很难诊断时，请先使用调试工具。为某个特定类别启用详细日志，并读取 `ConvaiRoomManager` 运行时状态，通常可以在几分钟内缩小大多数问题的范围。

{% 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:

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

The question should be specific, self-contained, and written in natural language.
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.