本文给一套可在 clustervps 多台物理 Mac 上排练的最小步骤：安装目录、编排顺序、排错信号。姊妹篇里按可用区拆网关与队列广播见OpenClaw 多 AZ 网关与 Webhook 实战；产物扇出与 rsync 参数矩阵见跨区并联决策矩阵；全站索引见技术博客首页。
导语：当你要把「租户 A 的回调」「租户 B 的 Doctor」「共享控制面」放在不同机器上时，先统一目录语义与版本锁，再让负载均衡只打一个 JSON 就绪端点；Webhook 失败走摘要广播而不是原始日志刷屏，令牌轮换用重叠窗口盖住最长重试链。
痛点（多节点编排）
- 巨石配置：一次 diff 牵动所有租户，回滚像拆炸弹。
- 探针分裂：LB、Sidecar、人手各 curl 一套脚本，半绿半红的「薛定谔健康」。
- 令牌周末事件：全集群同时换密钥，重试风暴把网关 TLS 打满。
拓扑与配置形态决策矩阵
| 形态 | 何时选 | 主要风险 |
|---|---|---|
| 单网关 + 单文件 | PoC、流量极低、单人维护。 | 任意磁盘抖动或 TLS 升级会连带所有租户。 |
| 租户片段 + 共享控制面 | 多数生产：按客户 drop-in，控制面聚合策略。 | 需严格目录约定与变更流水线，否则漂移难查。 |
| 网关与通知器拆分 | Webhook 体量大或合规留痕重。 | 时钟与队列水位要一起进探针，否则误判健康。 |
步骤清单（可打印）
- 冻结租户 ID 命名空间与主机角色表（GW / Worker / Notifier）。
- 在三台样例 Mac 上镜像同一相对路径，先空目录校验 launchd 路径与权限。
- 提交版本锁文件（OpenClaw 构建哈希 + CLI），CI 拒绝无锁合并。
- 实现合并就绪端点：Doctor 不变量、磁盘、队列深度、Webhook 摘要四段布尔。
- Notifier 节点开启五分钟窗口去重，失败只广播关联 ID 与 HTTP 状态。
- 金丝雀网关双令牌注入，跑一轮真实出站回调再抬权重。
- 全局切换后观察两轮健康轮询再吊销旧密钥。
- 把以上步骤写入 帮助中心 同结构的内部 runbook，换班可读。
可引用信息
- ① 建议片段根：
/etc/openclaw/tenants/<id>/{gateway,doctor,webhook}.d/（示例路径，按发行版调整）。 - ② 合并探针超时预算：对外聚合接口总耗时 ≤ LB 健康检查间隔的 60%。
- ③ 令牌重叠期 ≥ 下游最长重试链（含供应商退避）+ 2× 轮询周期。
目录约定
每台 clustervps Mac 使用相同相对布局，才能把「复制 launchd plist + 环境文件」写成幂等脚本。租户级片段只放差分：上游 URL、队列名、回调 HMAC、Doctor 阈值；共享基线留在 common.d。安装阶段用只读校验：sha256sum 清单比对，编排阶段再 launchctl bootstrap。排错时若路径漂移，优先 diff 两台机器的 符号链接与 Include 顺序，而不是先重启服务。
版本锁
把 OpenClaw 二进制与随附工具链版本写进仓库里的 openclaw.lock（或等价文件），并在部署脚本里拒绝静默升级。多租户合并演练时，用同一把锁在金丝雀与生产各跑一遍 Doctor；若哈希不一致，控制面应拒绝聚合「就绪」为 true。升级流程固定为：拉新制品 → 并行安装到 staging 目录 → 金丝雀节点切换软链 → 全量抬版本号 → 记录变更单。
健康探针合并
负载均衡与同伴节点只应请求一个 HTTPS 或本地 HTTP 就绪端点，其 JSON 内并列返回：Doctor 不变量、磁盘/APFS 压力、队列深度、出站 TLS 探测结果，以及来自 Notifier 的 Webhook 失败摘要行（已按租户与状态码折叠）。这样 on-call 打开一面板即可判断「是网关坏了还是回调伙伴限流」，避免五个 curl 脚本互相打架。若摘要通道本身失败，磁盘上保留单调递增计数器作为兜底信号，防止静默丢告警。
令牌轮换
在密钥管理系统生成影子令牌，先注入金丝雀网关，验证出站 Webhook 全绿一个工作日；随后用配置修订号把影子令牌推广到所有网关，Worker 通过原子 rename 读取密钥文件，避免半写状态。旧令牌仅在连续两轮合并探针全绿后吊销，并记录操作者与工单号。公网回调路径建议月度轮换；纯内网网格可季度执行。
FAQ
片段冲突谁优先？ 以 *.d 字典序与显式 zz-override 前缀约定为准，并在 Doctor 里加一条「解析结果指纹」防漂移。
合并探针会暴露敏感 body 吗？ 不应；摘要层只传状态码、重试次数、截断错误与关联 ID，完整载荷留在受控队列供授权节点拉取。
需要多少台 Mac 才能排练？ 最少三台：两台区域网关 + 一台 Notifier；若预算紧，可用一台 Worker 兼 Notifier，但要在矩阵里标明单点。