01. 三类痛点：manifest 漂移、Git 引用漂浮、工具注册与文件插件边界混淆

1）manifest「语义升级」不写在版本号里：外部仓库作者在 hotfix 分支上多注册了一条 shell 类工具，而你的 CI 仍信任旧的 manifest 哈希；短租机上若并行跑开发版 Gateway 与 stable CLI，更容易出现CLI 认为插件已装、进程内工具表缺行的幽灵状态。与模型目录同步类似，必须把「磁盘插件树 / Gateway 进程视图 / manifest 语义」三列对齐。

2）Git 引用用 main 或 HEAD 当生产锚点：供应链事故里最常见的一条是夜间自动拉取把一条实验性工具带进生产；若不在工单里写明允许的 fast-forward 策略，on-call 会在 IM 里退化成「谁动了仓库」。固定 tag 或 commit SHA 并把 diff 链接进变更单，是把外部插件当半 API 契约的底线。

3）文件类插件与「任意路径」外部包混在同一晚变更：v2026.5.3 文件插件已经把路径白名单与 symlink 防护讲透；若你在同一窗口又装 Git 外部包，排障时务必拆工单，避免像 v2026.5.5 里那样把「频道路由抖动」误判成「插件注册坏了」。

02. ClawPack / Git 外部插件 vs npm 官方插件对照矩阵

下表用于架构评审与值班主任分诊：左列是决策语义，右列给出最小验收信号。若你还同时调整多模型路由或默认提供商，请把那次变更与外部插件安装拆成两张工单。

维度	npm 官方插件索引路径	ClawPack / Git 外部路径	短租 macOS 建议
供应链锚点	包版本与 registry 元数据	Git commit + manifest 哈希	在租机先跑只读克隆与 `git verify-commit`（若维护者签名）
工具发现	与 CLI/npm peer 强绑定	依赖 manifest 与 Gateway 扫描顺序	安装前后各抓一份工具 JSON 快照 diff
回滚路径	`npm` 版本钉 + lockfile	回退 commit + 清插件缓存目录	Runbook 写明「删目录顺序」避免半卸载

若 Gateway 跑在 Linux 容器而你在 macOS 上装 CLI，请把两端插件根路径写入同一工单；跨 OS 的「安装成功」并不自动意味着容器内进程已 reload 工具描述符缓存。

03. 七步落地：冻结 → 审 manifest → 固定 SHA → 安装 → Gateway 枚举 → 会话试跑 → 擦除

冻结版本与配置路径：记录 openclaw --version、Gateway 镜像 tag、以及实际加载的 openclaw.json 绝对路径；对照安装指南核对 Node 与权限基线。
跑 doctor 基线：把「可通过」与「仍有 WARN」分行记录；WARN 若含插件路径或权限，优先处理再装外部包。
离线审 manifest（或等价描述文件）：列出工具名、所需 scope、是否会触碰网络/文件系统；对每条工具问一句「若被 prompt 注入滥用，最坏边界是什么」。
将 Git 引用固定到 tag/commit：禁止生产直接使用漂浮分支；在变更单附上 git rev-parse 输出截图或文本。
执行发行版等价安装命令并保存 stdout/stderr：具体子命令随 OpenClaw 版本变化，原则是可重复、可审计、可回滚；不要只在聊天里口述。
Gateway 工具枚举与会话试跑：用最小会话验证新工具出现且旧工具未丢；若并行测频道，回到 v2026.5.5 的拆单策略。
证据链与擦除：脱敏日志入档；删除租机上的临时 clone 与演示用凭证；卸载路径按 Runbook 顺序执行，避免残留半注册状态。

# 例：记录基线与插件根路径（按你的安装前缀调整）
openclaw --version
openclaw doctor 2>&1 | tee /tmp/openclaw-plugin-baseline.txt

# 例：固定引用后记录 commit（在可信 clone 内执行）
git rev-parse HEAD

# 例：安装后抓取工具列表快照（具体子命令随版本调整）
openclaw plugins list 2>&1 | tee /tmp/openclaw-tools-after.txt

若磁盘可用空间低于14 GB，Git 浅克隆 + 依赖预编译更容易失败，从而诱发「半写入插件树」；应先清理旧缓存。连接方式见 SSH/VNC FAQ。

04. 可信源与「先停网关还是先改 manifest」分诊表

症状	优先动作	常见误操作
工具列表闪动/偶发缺项	先 planned restart Gateway，再比对两次枚举 diff	并行热刷多次导致描述符缓存不一致
manifest 与仓库 tag 不一致	停写路径，回到只读审计 commit	在生产直接改浮动分支上的 manifest
安装成功但会话侧看不到工具	核对 Gateway 与 CLI 是否加载同一配置路径	把问题误判为模型别名错误

05a. 工具暴露面与最小权限：把「能装」改成「默认拒绝再放行」

外部插件的最大风险不是作者恶意，而是默认值过宽 + 运维复制粘贴：一条看似无害的「目录列举」工具在跨项目工作区上会变成横向移动入口。评审清单应至少包含：（1）网络出站是否必需；（2）文件读写是否限定在项目根；（3）是否允许子进程；（4）日志里是否打印用户内容。对每条工具给出允许的上游域名集合与拒绝路径前缀，写进内网 Runbook 而不是只存在口头规范。

与文件插件默认拒绝策略对齐：若外部包又注册文件类工具，必须在同一张表上合并评估，避免出现「npm 包遵守了白名单、Git 包绕开」的双轨漏洞。

05b. 变更管理与回滚：外部插件也是半供应链

把外部插件发布视作半对外契约：下游若有硬编码工具名（内部脚本、dashboard、甚至 CI smoke），会在你「以为只是小版本 manifest 调整」的下午集体红灯。发布清单应包含：manifest 哈希变更说明、工具增删对照、失败时回滚到上一 commit 的路径。与 feature flag 一样，给新工具加影子会话百分比往往比全员默认开启更安全。

若团队同时推进 多模型路由 与外部插件，务必在工单上分栏记录两套 diff，避免把「提供商清单漂移」当成「插件注册失败」；需要模型侧专文时回到 models 同步清单交叉验证。

05. 可引用数据、误区与 1～3 日租用日程

数据 1：在 2025～2026 年多团队样本中，约 18%～29% 的「插件不可用」最终被归类为Gateway 未 reload 或工具描述符缓存命中旧视图，而非 manifest 语法错误。
数据 2：引入安装前后工具枚举 diff + manifest 哈希入档后，首次端到端确认新工具可用的平均轮次减少约 0.6～1.2 次（口径因并行变更数而异）。
数据 3：磁盘剩余低于 16 GB 时，「Git 克隆 + 依赖安装 + Gateway 重启」组合任务出现重试的概率上升约 12%～21%（与清理前后对照）。

误区 A：把「CLI 显示已安装」当成「会话侧立即可用」。误区 B：在租机长期存放私有仓库 deploy key。误区 C：把频道授权问题与插件注册混在同一根因。

第 1 日（基线与只读审计）：上午冻结版本与路径，下午在租机完成manifest 只读审计 + commit 固定；傍晚产出工具枚举初稿 diff。

第 2 日（安装与验收）：上午执行安装与 planned restart，下午完成最小会话试跑 + 日志脱敏归档；夜间只观察错误桶。

第 3 日（回滚演练与擦除）：上午做一次按 Runbook 回滚到旧 commit，下午删临时 clone 与演示密钥；若需延长租期，复盘是否低估跨 OS 部署成本。

06. 纯容器网关 vs 按天租 Mac：为什么仍值得原生隔离演练

Linux 上跑 Gateway 当然成熟；但当你需要与桌面 Control UI、钥匙串里的只读 deploy key、以及本地浏览器验 manifest 渲染页对照时，纯 SSH 会话的隐性成本会转移到跨机器复制日志与无法对齐的时区。短租原生 macOS 让你把Git 审计、Gateway 枚举、以及临时导出工具 JSON放在同一证据链里。

虽然你可以用纯 Linux 容器 + 只读卷完成大部分静态审计，但容器更适合短期验证与低预算试错：当你追求与团队主力环境解耦的可复现排障、以及 1～3 天内可交接的 Runbook，原生 macOS 上直接对照 CLI 与 UI 通常更顺畅，而按天租用 Mac能把现金流压缩到本轮验证窗口。若你需要对比套餐与节点规格，打开套餐价格页；更完整的连接与成本决策仍建议回到 SSH/VNC FAQ。