故障排除¶
先记录启动页面、活动中心或对话框显示的完整错误。在确定失败边界前，不要删除项目或缓存数据。
Koharu 无法完成启动¶
原生运行时初始化后，项目浏览器才可交互。首次启动请确认能够访问 GitHub Release 资源，并等待下载结束。
反复失败时，关闭所有 Koharu 进程，更新 GPU 驱动并重启电脑，在稳定网络上重试，然后保存完整初始化错误。进程仍可能加载 DLL 或共享库时，不要移除运行时目录。
模型下载失败¶
确认能够访问对应 Hugging Face 仓库且缓存磁盘空间充足。代理、地区限制、认证、杀毒扫描或中断都可能阻止解析。重试同一模型一次；若仍在同一文件失败，请报告仓库、文件名和完整错误。
回退到 CPU¶
Koharu 在 Apple 芯片上使用 Metal，并按条件尝试 CUDA、ROCm/HIP 和 Vulkan。检测到 GPU 仍需要兼容驱动与运行时包。请在资源监视器和启动日志中确认实际选择的后端。
检测或 OCR 质量差¶
确认页面方向和清晰度，检查是否生成了正确检测区域，在多页上保守调整阈值。日文原稿可尝试漫画专用 OCR，并在重新翻译前手工修正原文。
图像修复破坏画面¶
使用更小的手工移除蒙版，避开气泡边框和线稿。重型生成模型前先试直接模型。手工修补应保存在独立手工栅格层。
翻译服务失败¶
在设置 -> 服务商检查凭据、基础 URL 与专用字段，然后刷新模型选择器。OpenAI 兼容服务器需要按实际接口配置聊天端点和视觉能力。
智能体无法登录或运行¶
同一时间只能有一个设备登录或智能体请求。取消现有尝试，确认浏览器在正确 ChatGPT 账号上完成授权，再重试。智能体登录与 OpenAI 服务凭据相互独立。
文本缺失或变形¶
Koharu 只渲染译文。确认图层包含译文、可见、不透明度非零，并能解析覆盖目标文字的字体。大幅修改文字后重置自动适配。
详细日志¶
# macOS / Linux
RUST_LOG=debug koharu
# Windows PowerShell
$env:RUST_LOG='debug'
koharu.exe