用途与实际影响
这项功能怎样使用
为什么需要它
OpenClaw 的日常设置和工作区，与官方归档保存的应用状态不同。配置损坏时先找对材料、暂存检查，再决定是否激活，免得把仍可用的网关盖掉。
举个实际例子
我说“OpenClaw配置改坏了，先帮我找一份能检查的恢复材料”。先取某次config/workspace快照；若要还原原生状态，先校验官方归档并解到全新暂存目录。当前网关保持不动，检查版本、工作区和登录后再明确执行离线激活。
最后我会得到什么
得到按日期分开的设置和工作区副本，或在全新目录里可检查的官方归档副本。当前网关不会因“文件已解开”就自动切换；登录、模型与消息链另验。
正常时
日常副本各自核对；官方归档先验完整并解到空目录，只报告这一层完成。
发现问题时
云端失败保留本地副本；官方归档没有工作区时另从日常副本找。
入口不可用或证据不足时
材料不齐或目标目录不为空时停止恢复，不覆盖当前网关。
从哪里开始
在已接入的 AI 对话中说明 OpenClaw 是配置损坏、工作区丢失还是需要官方状态归档恢复。
需要准备什么
- 目标 OpenClaw 环境
- 日常快照或官方归档
- 当前网关是否仍运行
从开始到拿到结果
- 1
选对恢复材料
日常配置/工作区快照与官方原生归档分别查，不用小文件冒充完整状态。
- 2
先解到新暂存目录
官方归档先验证再恢复到空目录，保留当前环境及其路径。
- 3
决定是否激活并验消息
核对版本、认证、网关、模型与渠道后才离线激活；暂存成功或任务退出码不足以证明真实消息可用。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
定时G与私有Git元数据已读；官方归档与暂存沿用旧验收，未激活恢复关键规则与设计选择
定时脚本只选择openclaw.json、auth-profiles.json、config.yml和.env，不是config_root全量镜像。
workspace排除node_modules、.git、.openclaw-repair、.clawhub及package-lock.json；依赖和被排除材料另行恢复。
官方backup-config.ps1使用--no-include-workspace；要完整恢复工作体验，必须分别确认工作区与官方状态材料。
restore-config.ps1只暂存，不停止网关、不覆盖当前配置、不自动激活。当前没有四套工具统一的一键恢复器。
本模块用到的名词
- staging-only（只恢复到暂存区）
- 生成一个可检查的恢复副本，当前运行配置和网关没有被切换。
- include_workspace=false
- 官方归档显式不包含工作区，不能用它的验证结果替代工作区副本。
专业定义
日常文件快照与官方状态归档互补；先验证材料和暂存副本，再决定是否激活。
解决什么
防止把普通文件复制、官方归档校验、暂存恢复和现役激活混成一项成功。
当前怎样实现
- backup-openclaw.ps1读取openclaw组六个路径键；先验证配置根、工作区根和私有Git，再把四类存在的配置文件复制到config，workspace用过滤后的robocopy生成本地快照。
- 本地/G各轮换30份，G以文件长度和SHA-256核对。云端先检查main与远端状态，然后严格从已经完成的configSnapshot/workspaceSnapshot复制；配置文件在本轮快照缺失时清除云端对应旧文件，workspace按同一快照镜像。
- backup-config.ps1调用openclaw backup create --output <archive> --no-include-workspace --verify --json，要求verified=true、includeWorkspace=false、assets非空、返回归档位于指定目录且真实存在。
- restore-config.ps1先调用官方backup verify，再以backup restore --target <新目录>恢复；目标必须尚不存在，恢复后检查非空文件集，返回openclaw_restore_stage_result.v1、activation_performed=false、activation_required=true。
- 官方归档可包含私人配置和凭据，保存于原私人归档根；页面不读取它们。完整离线激活按同版本官方恢复流程独立处理，不能把文件名清单当作已验证认证可用。
执行流程
- 1
选择日常config/workspace快照或官方状态归档。
- 2
日常备份先完成本地/G，再从同一快照更新私有Git。
- 3
官方恢复先verify，要求全新目录，再还原并核对非空结果。
- 4
检查版本、工作区、路径、依赖及认证，保留当前环境后才决定离线激活。
- 5
独立核对网关、模型、渠道与真实消息结果，不以暂存成功代替。
边界
- 不展示配置正文、账号、令牌、私有端点或真实归档。
- 没有重新创建备份、还原真实材料、激活网关或发送消息。
- 自动恢复登录、原消息和完整原生状态需按官方归档及应用实测，不由四个配置文件或定时任务0保证。
失败与恢复
- robocopy退出码>=8或本地快照为空
- 停止对应备份，不向云端发布假成功。
- 归档校验失败或目标已存在
- 拒绝暂存恢复；不覆盖当前网关或现有目录。
- 暂存完成但激活未执行
- 明确返回activation_required=true，应用恢复保持未验。
真实入口
E:\Projects\Tools\OpenClawGateway\tools\backup-openclaw.ps1四配置文件、工作区选择与同快照三层分发
tools/backup-config.ps1 / restore-config.ps1官方无工作区归档、校验和只暂存恢复
tools/test_backup_config.ps1 / test_restore_config.ps1归档/新目标与不激活的隔离合同测试
如何验证
- 9月9日22:08Z G元数据186文件、2840710字节与实际目录计数/字节一致，保存点仍为9月1日03:20Z；同内容可复用旧点。私有Git本地/远端同9359383c62008bc59e96d5891496b738c950a7b1、工作树干净为05:05Z独立历史观察。
- 9月3日224287339字节官方归档和全新暂存恢复保留历史通过证据；未进行本轮真实恢复或激活。
与其他模块的关系
网关、渠道、模型和运行修复仍由OpenClawGateway负责；这里解释备份文件与恢复材料，任务和源仓库保持独立。