QClaw跨系统迁移需通过导出状态包、安装空实例、结构化注入、完整性验证及手动补全不可序列化项五步完成。导出含配置、技能、对话等的ZIP包；目标系统跳过部署直接导入；自动适配路径与权限；指令校验四类元数据；最后补全计划任务、辅助功能授权及硬件加速标识。
如果您已完成qclaw本地部署，但需将当前项目（含配置、技能包、对话记录、模型偏好等）从一台设备迁移至另一台不同操作系统（如从windows迁移到macos，或反向操作），则需绕过系统依赖差异，采用状态导出与结构化还原机制。以下是实现跨系统迁移的具体操作方法：
一、导出全量项目状态包
该步骤旨在将当前QClaw实例中所有可序列化的运行时状态打包为平台无关的归档文件，包括用户配置、技能启用状态、历史任务快照、微信关联元数据（不含敏感凭证明文）、模型路由规则等。导出过程不依赖操作系统底层路径或注册表，确保后续可在任意支持平台解包还原。
1、启动已部署完成的QClaw应用，确保处于登录且微信已授权状态。
2、点击主界面左上角菜单栏中的“设置” → “高级选项” → “导出项目状态”。
3、在弹出窗口中确认勾选“包含技能包启用状态”、“保留对话时间线索引”、“同步模型切换历史”三项。
4、点击“生成状态包”，等待进度条完成；生成文件默认命名为qclaw-state-export-YYYYMMDD-HHMMSS.zip，保存于用户文档目录下的QClaw/exports/子路径。
二、在目标系统安装并初始化空QClaw实例
此步骤确保目标系统具备干净、兼容的运行环境，避免残留配置干扰迁移结果。QClaw官方安装包已内置跨平台适配层，同一版本安装器可自动识别Windows/macOS/Linux内核并加载对应驱动模块，无需手动选择。
1、前往QClaw官方下载页，根据目标系统类型（Windows/macOS）下载对应安装包，**无需卸载原系统上的OpenClaw或其他AI代理工具**。
2、双击运行安装程序，全程保持默认选项，完成安装后**不点击“一键部署”按钮**。
3、首次启动新安装的QClaw，在欢迎界面选择“跳过初始部署，等待导入状态”，进入空白待机状态。
三、执行结构化状态注入
该方法利用QClaw内建的状态解析引擎，将导出包中JSON/YAML混合结构的数据映射至目标系统抽象路径层，自动适配文件系统差异（如Windows盘符与macOS挂载点）、权限模型（ACL vs Unix mode）及服务注册方式（Windows Service vs launchd），实现零手工路径修正。
1、将上一步导出的.zip文件复制至目标系统任意位置（如桌面）。
2、在目标系统QClaw主界面，点击右下角悬浮按钮“导入状态包”。
3、选择该.zip文件，系统将自动校验签名并解压；弹窗提示“检测到跨平台迁移请求，将启用路径抽象层”，点击确认。
4、等待状态注入完成，界面显示“技能包重载完成”、“微信会话通道已重建”、“模型路由表同步就绪”三行绿色状态提示。
四、验证迁移完整性
本步骤通过预设校验点触发轻量级运行时比对，不启动完整AI推理链路，仅校验关键元数据一致性，避免因模型加载延迟导致误判。所有验证动作均在本地内存中完成，不产生网络请求或日志上报。
1、在QClaw主界面输入指令：“/verify-migration-integrity”（注意斜杠不可省略）。
2、系统立即返回四行校验结果：第一行为“配置哈希匹配：PASS”，第二行为“技能启用矩阵一致：PASS”，第三行为“最近72小时任务ID连续性：PASS”，第四行为“微信消息通道握手成功：PASS”。
3、若任一行为FAIL，界面将高亮显示具体偏差字段名（如model_preference.openai.api_base），此时应返回步骤三重新执行注入。
五、手动补全不可序列化项
部分系统级绑定资源无法被自动化导出，包括Windows平台的计划任务触发器、macOS的Accessibility权限授权状态、特定硬件加速器（如NPU）的驱动绑定标识。这些项目需在目标系统上单独确认并启用，不影响主体功能运行，但关系到后台常驻与低功耗唤醒能力。
1、Windows目标系统：打开“任务计划程序”，检查是否存在名为“QClaw-Background-Invoker”的任务，若不存在，则点击QClaw设置页中的“修复后台唤醒”按钮。
2、macOS目标系统：进入“系统设置 → 隐私与安全性 → 辅助功能”，确认“QClaw Helper”已勾选；若未出现，重启QClaw并等待10秒后再次检查。
3、通用操作：在QClaw设置页中，点击“重置硬件加速标识”，系统将自动探测当前GPU/NPU型号并写入适配标记，无需用户选择型号。
