常见问题排查

先记录当前页面、OmniStudio 版本、操作系统、模型名称和最近一次明确错误，再决定是否重试。连续重复点击可能掩盖原始原因。

首次启动停在“检查本机推理环境”

Windows 和 Apple Silicon macOS 正式包已经包含基础后端，正常情况下不应重新从 GitHub 下载这两个小型后端。

1. 等待页面显示当前阶段，而不是只看动画。
2. 打开 Developer Logs，确认是在检查、部署内置后端、启动服务还是发生错误。
3. 如果日志显示缺失或校验失败，提交日志；不要从未知网站手工替换 runtime 文件。

“Finding a model”持续很久

推荐模型与下载是两个阶段。推荐阶段会读取设备能力和模型目录，不会显示下载字节；真正下载后，全局下载中心会显示文件、速度和剩余时间。

超过合理时间仍没有结果时，检查网络、模型目录接口和 Developer Logs。不要把推荐动画当成后台下载已经开始。

下载百分比在主模型完成后变化

视觉模型还需要 mmproj。较早版本可能先按主权重计算进度，进入 Vision projector 后重新计算完整总量，因此百分比会调整；这不是重新下载主模型。打开下载中心核对当前阶段和总字节，等待整个 bundle 完成。

下载失败或速度为零

• 确认磁盘空间大于 Total download，并为临时文件留出余量。
• 根据网络情况切换 Hugging Face 访问源，或使用 ModelScope / OmniCore。
• 使用 Pause / Resume 保留断点，不要重复创建同一任务。
• 权限错误时在设置中改到有写权限的模型目录。

模型已安装但无法发送

1. 在 Model → Installed 确认模型仍存在。
2. 视觉模型确认 mmproj 已安装。
3. 回到聊天页重新选择模型并等待加载完成。
4. 在 Developer 中确认 Local Server Online，并查看 Runtime Models 与最近错误。

Local Server Offline

点击 Start Server。如果仍失败：

• 检查配置端口是否被其他程序占用。
• 确认旧 OmniInfer 进程没有残留。
• 检查安装和数据目录权限。
• 保留 Developer Logs 中的启动阶段与底层错误。

Windows 拦截安装包

当前 Windows 包未完成 Authenticode 签名，SmartScreen 可能显示未知发布者。如果 Defender 报告具体威胁，请不要关闭防护、添加排除项或恢复隔离文件；保留威胁名称、版本和官网下载地址并提交反馈。

macOS 无法打开

当前正式 DMG 应通过 Developer ID 签名、Apple 公证和 Gatekeeper。请确认从官网下载并拖入 Applications。不要通过删除 quarantine 属性或关闭 Gatekeeper 绕过；保留系统原始提示并提交反馈。

仍未解决：提交反馈。