常见错误
AI 莫名断开 / 中途停止
现象：对话过程中 AI 突然停止响应，没有报错信息。
原因：底层 Claude Code 在遇到某些模型返回异常时，会直接终止，未做容错处理。使用开源模型或第三方代理时更常见。
解决方法：
- 点击界面上的**「继续」**按钮，Halo 会自动发送继续指令
- 或在输入框中手动发送：
继续
Prompt is too long（提示词过长）
现象：出现 Prompt is too long 报错，对话无法继续。
原因：Claude Code 内部触发了上下文长度限制。通常是因为 AI 在执行过程中调用了某个返回大量内容的命令（如读取大文件），导致上下文急剧膨胀，而 CC 没有做自动过滤。
解决方法：
- 发送
/compact尝试压缩上下文（部分情况有效） - 如已无效，复制当前对话的关键内容，新开一个空间，粘贴历史记录后继续。
复制完整对话历史
用鼠标拖拽选中所有对话气泡内容，粘贴到新对话，并说：「上面是历史记录，请继续执行。」
图片上传后报错
现象：上传图片后 AI 报错，后续对话也无法正常使用。
原因：当前使用的模型不支持图片输入（非多模态模型）。
解决方法：
- 必须新开对话，因为包含图片参数的上下文已经损坏
- 切换到支持多模态的模型（如 Claude 4.5、GPT-4o），再重新上传
WARNING
上传图片前，请先确认当前模型支持视觉能力。设置 → AI 模型 中可查看当前使用的模型。
上下文过长 / 超出模型限制
现象：对话过长后出现上下文超限报错。
说明：Claude 官方模型支持约 200K token 上下文。第三方代理或开源模型的上限可能更低。
解决方法：
- 发送
/compact让 CC 自动压缩摘要 - 新开空间继续
Windows 无法执行命令
现象：在 Windows 上，AI 尝试执行 Shell 命令时失败或报错。
原因：Windows 上的 Claude Code 命令执行依赖 Git Bash，如未安装则无法运行。
解决方法：
- 下载并安装 Git for Windows
- 安装完成后重启 Halo
在无外网环境（如企业 VDI）中，需要提前下载安装包，通过内网传输后手动安装。
远程访问无法连接
| 症状 | 解决方法 |
|---|---|
| 密码错误提示 | 确认密码输入正确，注意区分大小写 |
| 局域网访问失败 | 确保两端设备在同一 WiFi 网络下 |
| 公网访问失败 | 等待约 10 秒 DNS 解析完成后重试 |
| 开启后无法获取地址 | 检查网络连接，重试开启隧道 |
AI 无响应 / 卡住
- 进入 设置 → 系统 → 诊断
- 查看进程状态和服务状态
- 先尝试**「重置 AI 引擎」**（S2）
- 如仍无效，点击**「重启应用」**（S3）
其他问题 / 崩溃 / 兼容性
前往 设置 → 系统 → 打开日志文件夹，将日志文件发送给开发者，有助于快速定位问题。
日志文件包含运行时信息，不含你的对话内容或 API Key。
提交 Bug
欢迎在 GitHub Issues 提交 Bug 报告，附上日志文件和复现步骤。