用途与实际影响
这项功能怎样使用
为什么需要它
带占位符的模板若被直接安装，会制造半配置系统；先安装再校验也可能在失败前已经改变机器。
举个实际例子
我可以说：“先预演把公开模板部署到私人目录；还有任何配置没填就停，不要安装软件或注册任务。”系统会在实际写入前交回缺项和计划。
最后我会得到什么
预演时没有副作用；正式运行时得到已校验配置、写后校验与可回退旧副本，可选再显式注册 Gateway（网关）。
正常时
私人配置已填完整且预检通过，正式写入后再确认生效；是否常驻另有明确选择。
发现问题时
缺依赖时先说明会安装什么，注册常驻任务前再次说明所需权限。
入口不可用或证据不足时
模板仍有占位值、配置损坏或写后验证失败时停止并保留可恢复旧副本。
从哪里开始
从公开模板复制到私人配置位置，填入真实工作区、模型与渠道；先运行 bootstrap/setup.ps1 -WhatIf，确认后再正式部署。
需要准备什么
- 要安装到哪台电脑
- 希望使用的工作区、模型和渠道
- 需要的私人凭据由本人在本地配置
从开始到拿到结果
- 1
准备私人配置
公开模板只说明结构；本人在私人位置填写工作区、模型和渠道条件，不把凭据交给网页。
- 2
先看预演结果
工具检查还没填的项目、配置是否有效以及准备改什么；缺项就不写入。
- 3
正式部署再读回
成功写入后检查真实配置；是否登记网关常驻要另选，并再看能否响应。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
模板、预检、原子写入和回退合同已测试；全新 Windows 实装未验关键规则与设计选择
公开模板的渠道默认 disabled（停用）、allowlist（允许列表）为空、Gateway loopback（网关仅本机回环）、自动更新关闭。
模板不预设 Gateway 密码或模型秘密；认证走官方 models auth（模型认证）或私人 ConfigSource。
-WhatIf 不安装、不写配置、不注册、不启动。
全新 Windows 安装、依赖安装和真实 -RegisterGateway（注册网关）本轮未执行。
本模块用到的名词
- ConfigSource（配置来源）
- 已在私人位置填写完成的 OpenClaw JSON（结构化配置）；不能直接指向正在使用的现役文件。
- WhatIf（预演）
- 运行所有必要预检并显示副作用，但不真正执行。
- atomic replace（原子替换）
- 候选完整写好并可解析后，一次性替换目标，减少半文件风险。
专业定义
bootstrap（部署引导）负责让一份私人配置安全落地，不替用户在公开仓库里填写账号和秘密。
解决什么
避免把脱敏示例误当可运行配置，也避免失败的 bootstrap 留下半安装机器。
当前怎样实现
- Test-BootstrapConfig（部署配置检查器）递归查找 __REPLACE_WITH_*__，且必须在任何 effect（副作用）前运行。
- 候选配置通过 OPENCLAW_CONFIG_PATH（OpenClaw 配置路径）送入 official config validate（官方配置校验）。
- Install-BootstrapConfigAtomically（原子部署配置）用同目录临时文件替换；有旧配置时保留 rollback（回退副本），后验失败时恢复。
- 注册调用 guardian（常驻核对器）-Repair，不再生成仓库内 VBS（隐藏启动脚本）或写机器级密码环境变量。
执行流程
- 1
复制公开模板到私人位置。
- 2
填写 workspace（工作区）、模型、渠道与必要私人值。
- 3
运行 -WhatIf，检查占位符与候选 schema（数据结构）。
- 4
正式运行，原子写配置并做生效后验。
- 5
需要常驻时再显式 -RegisterGateway，并独立读 RPC（远程过程调用）/health（健康检查）/任务。
边界
- 不把私人 ConfigSource 或 secret（秘密）提交 PUBLIC（公开）。
- 不在占位符未填时产生任何副作用。
- 不把脚本测试写成全新 Windows 安装通过。
失败与恢复
- ConfigSource 仍含占位符
- 在安装、写入、注册和启动前非零退出。
- 写后 config validate（配置校验）失败
- 恢复旧配置；原先不存在则删除新目标。
- RegisterGateway（注册网关）无管理员权限
- 停止注册，保留已明确完成的前序结果。
真实入口
bootstrap/openclaw.template.json公开脱敏结构模板
bootstrap/setup.ps1预检、原子安装与回退
docs/DEPLOY.md从模板到渠道和 Gateway 验收层级
如何验证
- test-bootstrap.ps1 用隔离夹具验证预检先于副作用、WhatIf（只读预演） 和回退。
- 34 个 PowerShell 文件解析 0 错包含当前 bootstrap。
- 没有在全新 Windows 10/11 完成从依赖安装到真实消息的端到端验收。
与其他模块的关系
bootstrap 建立运行基础；guardian 负责可选常驻注册，渠道与模型需要各自继续私人配置和 Live（真实运行）验收。