需备份沙盒目录、策略快照、Connector凭证，冻结并导出工作流与技能状态，再执行停服、卸载旧版（保留沙盒）、安装新版、回灌配置的三段式升级流程。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您正在将QoderWake升级至新版本，但希望保留旧版本中已配置的数字员工实例、Connector凭证、工作流规则及本地技能参数，则需避免直接覆盖式安装或未备份就执行自动更新。以下是实现配置保留与平滑迁移的关键操作路径：
一、备份核心配置目录与策略快照
QoderWake的运行时配置、岗位声明、Connector绑定状态及权限策略均集中存储于本地沙盒目录与云端策略快照中。迁移前必须完整备份这两类数据源，防止升级过程因路径覆盖或服务重置导致配置丢失。
1、打开终端，切换至QoderWake沙盒根目录：cd /var/lib/qoder/sandbox。
2、执行压缩备份命令，保留完整目录结构与权限位：sudo tar -czf ~/qoderwake-sandbox-backup-$(date +%Y%m%d).tar.gz . --exclude='./cache' --exclude='./logs'。
3、登录QoderWake管理控制台(admin.qoderwake.aliyun.com)，进入「部署管理 > 版本策略」，定位当前生效策略快照，点击「导出为JSON」并保存至本地安全路径。
4、在「集成中心 > 已启用连接器」页面，对每个Connector点击「导出凭证」，生成加密凭证包（文件名含connector-id与时间戳）。
二、冻结本地工作流与技能状态
部分企业用户在本地部署了非同步托管的工作流模板、自定义防腐规则或经调优的技能参数集，这些内容默认不参与云端策略同步，需在升级前显式冻结其运行态并导出元数据，避免新版本加载机制误判为冲突项而自动禁用。
1、在旧设备QoderWake CLI中执行命令：qoderwake workflow freeze --all --output /backup/workflow-frozen.json。
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
2、导出全部已安装技能的当前激活状态与参数快照：qoderwake skills export --stateful --to /backup/skills-state-20260522.yaml。
3、检查输出文件中是否存在硬编码绝对路径（如/home/olduser/scripts/），若有，使用sed命令批量替换为环境变量引用格式：sed -i 's|/home/olduser|${HOME_USER_PATH}|g' /backup/skills-state-20260522.yaml。
4、将上述两个文件与/backup/目录下所有导出内容整体复制至新设备对应路径，确保文件权限为600且属主为qoder-sandbox用户。
三、分阶段执行升级与配置回灌
QoderWake新版本启动时会自动校验本地配置兼容性。若检测到旧版字段结构或参数命名变更，将拒绝加载并报错。因此必须采用“先停服、再替换、后回灌”的三段式流程，确保配置语义完整性。
1、在旧设备执行平滑停服：qoderwake gateway stop --graceful --timeout 120，等待所有Agent完成当前任务并释放资源。
2、卸载旧版客户端但保留沙盒目录：npm uninstall -g qoderwake && rm -rf ~/.qoderwake/cli，严禁执行rm -rf /var/lib/qoder。
3、安装新版QoderWake核心包后，立即执行配置回灌命令：qoderwake config import --from ~/qoderwake-sandbox-backup-20260522.tar.gz --preserve-cache。
4、导入策略快照与凭证包：qoderwake policy import --file /backup/policy-snapshot-v1.2.7.json && qoderwake connector import --file /backup/connector-creds-slack-20260522.enc。
