先在启动失败页点击“重试”。如果问题持续出现，打开“错误详情”复制错误信息，再点击“打开日志文件夹”。不要公开发送 API Key、.credentials.yaml、完整会话内容或未经脱敏的日志。
- 确认网络能访问 Node.js 与 npm。默认自动下载策略会先尝试官方地址，再回退镜像；也可在
config.json中设置download_source。 - 取消安装后，点击“重新安装”。取消是正常流程，不需要退出应用。
- 检查
logs/dshbox.log与logs/dsh.log中最早出现的错误。后续错误往往只是同一问题的连锁结果。 - 不要直接删除
node/、dsh/、.part、*-old或事务标记。DSHBox 会在下次启动时尝试恢复被中断的更新。
- 若提示存在未完成的插件操作，先重启 DSHBox，让启动恢复流程检查并收敛该次增删。
- 不要手工删除插件事务标记或修改 dsh profile 的
package.json；这会丢失精确恢复所需的原始 manifest 和目标包信息。 - 恢复后仍失败时，保留
state.json、dsh profile 的package.json、logs/dshbox.log与logs/dsh.log进行排查。
- 查看系统托盘。关闭按钮默认把窗口隐藏到托盘；托盘菜单中的“打开 DSHBox”可恢复窗口。
- 设置为“仅驻托盘”后，手动启动也不会显示主窗口。可从托盘菜单打开“设置”改回“显示窗口”。
- 重复启动不会创建第二个实例，而是唤醒已经运行的 DSHBox。
config.json中的port只是本地服务首选值。被占用或被 Windows 保留时，DSHBox 会让系统分配可用端口；无需手工扩大端口范围。- 发现端口
3080或首选端口已有 dsh 时，启动页会询问连接现有服务还是启动本地服务。连接外部服务后，凭据、模型、插件和 dsh 更新应回到原服务环境管理。 - 已记住的外部服务断开时，先确认原命令或部署仍在运行，再点“重试”。若不再使用它，点“改用本地服务”；DSHBox 不会擅自结束或替换外部进程。首次启动时若曾因连接外部服务而跳过本地设置，切换后会补充显示一次。
- 外部服务身份发生变化时会重新询问。这是因为当前 dsh API 不提供可验证的
DSH_HOME或实例 ID，不能仅凭端口推断数据目录。
- 在“设置 → 服务管理 → DeepSeek API Key”中填写以
sk-开头的密钥。 - 环境变量的优先级高于凭据文件。若设置页显示由环境变量管理，请修改
DSH_BOX_API_KEY或DEEPSEEK_API_KEY，然后重启应用。 - 瞬时网络错误会保留上一次余额并标记刷新失败；无效或缺失的密钥不会继续显示旧余额。
- 缺少或版本过旧的 WebView2 Runtime 时，按应用提示安装微软官方运行时。
- SmartScreen 拦截未签名程序时，先核对下载来源和文件名，再使用系统提供的放行入口。
- 安装 WebView2 或更新应用可能触发 UAC。只在操作由 DSHBox 主动发起且来源可信时确认。
当前产物未签名。若 Gatekeeper 拦截，在 Finder 中按住 Control 点击应用并选择“打开”，或前往“系统设置 → 隐私与安全性”允许本次运行。
需要 WebKitGTK 4.1 及 Tauri 所需系统库。Ubuntu 22.04、Debian 12 或等价环境可按发行版方式安装依赖。dsh 的 Landlock 需要 Linux 5.13+；较旧内核由 dsh 自行降级。
普通故障可提交 issue，并附上：
- DSHBox 版本、操作系统和架构；
- 最小复现步骤；
- 错误详情；
- 已脱敏的相关日志片段。
安全问题请使用仓库的私密漏洞报告入口，具体要求见 SECURITY.md。