QClaw安装卡顿的五大原因及解决步骤：一、检查资源与磁盘空间；二、关闭杀毒软件拦截；三、清除残留进程与缓存；四、更换网络或使用离线安装包；五、验证WSL2/Rosetta等系统兼容性。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 免费无限量使用 DeepSeek R1 模型☜☜☜
如果您在安装 QClaw 过程中出现进度条停滞、界面无响应或长时间停留在“正在检测环境”“正在安装 Node.js”等环节，则可能是由于网络中断、系统权限限制、杀毒软件拦截或磁盘空间不足所致。以下是解决此问题的步骤：
一、检查并释放系统资源与磁盘空间
QClaw 安装过程需临时解压大量依赖包并写入缓存，若内存低于 6GB 或剩余磁盘空间少于 8GB，安装程序可能因 I/O 阻塞而卡死。该步骤旨在确保基础运行条件满足。
1、打开任务管理器（Windows）或活动监视器（macOS），查看内存与磁盘使用率是否持续高于 90%。
2、关闭非必要后台程序，特别是浏览器多标签页、视频播放器、大型 IDE 等高内存占用应用。
3、清理系统临时文件：Windows 用户可运行 diskcleanup.exe；macOS 用户可前往「访达」→「前往」→「前往文件夹」输入 ~/Library/Caches 并清空内容。
4、确认安装目标盘（默认为 C: 或 Macintosh HD）剩余空间 ≥10GB。
二、关闭第三方安全软件拦截
部分国产杀毒软件（如火绒、360安全卫士、腾讯电脑管家旧版）会将 QClaw 安装包中的 Docker Desktop 或 Node.js 启动进程误判为风险行为并强制终止，导致安装流程中断。
1、右键点击任务栏右下角杀毒软件图标，选择「退出」或「暂时禁用实时防护」。
2、在 Windows 设置 → 隐私和安全性 → Windows 安全中心 → 病毒和威胁防护 → 管理设置中，临时关闭「实时保护」。
3、重新双击 QClaw 安装包运行，观察是否跳过卡顿节点。
4、安装成功后，再重新启用安全软件防护功能。
三、手动清除残留安装进程与缓存
若此前安装失败但未完全退出，QClaw 的后台服务进程（如 qclaw-installer、dockerd、node）可能仍在后台静默运行，占用端口与文件锁，造成重复安装时冲突。
1、Windows 用户按 Ctrl+Shift+Esc 打开任务管理器，在「详细信息」页签中查找并结束以下进程：qclaw-installer.exe、dockerd.exe、node.exe。
2、macOS 用户打开终端，依次执行：ps aux | grep -i "qclaw\|docker\|node" 查找进程 ID，再执行 kill -9 [PID] 强制终止。
3、删除残留缓存目录：Windows 路径为 %LOCALAPPDATA%\QClaw\cache；macOS 路径为 ~/Library/Caches/QClaw。
四、更换安装源与离线重试
QClaw 安装程序需从 CDN 下载 Node.js、Docker Desktop 及模型运行时组件，若当前网络无法稳定访问腾讯云 COS 源（如企业内网策略限制、DNS 污染），会导致下载超时并假死。
1、断开当前 Wi-Fi，切换至手机热点或其他网络环境。
2、Windows 用户可尝试以管理员身份运行安装包：右键 QClaw-Windows-Setup.exe → 「以管理员身份运行」。
3、macOS 用户在安装前先执行：xattr -rd com.apple.quarantine /path/to/QClaw-Mac.dmg 解除隔离属性。
4、若仍失败，前往 GitHub QClaw Release 页面下载带 offline 标识的完整离线安装包（如 QClaw-Windows-Offline-1.2.0.exe），该包已内置全部依赖，无需联网下载。
五、验证系统兼容性与基础组件状态
QClaw 安装脚本会自动检测 Windows Subsystem for Linux（WSL2）或 macOS Rosetta 2 状态，若系统未启用或版本不匹配，可能导致 Docker 初始化失败并卡在“配置 Docker…”阶段。
1、Windows 用户打开 PowerShell（管理员），运行：wsl -l -v，确认输出中包含 WSL2 发行版且状态为 Running；若无输出，需启用 WSL：wsl --install。
2、macOS 用户打开终端，运行：arch，确认返回 arm64（M系列芯片）或 i386（Intel芯片）；若为 M 系列且提示 Rosetta 未安装，需前往「启动台」→「实用工具」→「终端」右键「显示简介」→勾选「使用 Rosetta 打开」。
3、重启电脑后，再次运行安装包。
