OpenClaw 閘道 npm ci、package-lock.json、可重現安裝與租用雲端 Mac 上的乾淨重建紀律（2026-05-09）
2026 年的社群 issue 流反覆呈現同一種故障模式：閘道停留在仍持有檔案控制代碼的狀態下，操作員卻執行 npm install -g openclaw@latest，留下半重新命名的目錄樹、欠缺的插件執行時相依性，以及餓死 Telegram 長輪詢的重啟迴圈。 在香港、日本、韓國、新加坡與美國交付自動化的 MacLogin 租戶應把閘道視作與其他生產二進位同級：提交鎖檔、用 npm ci 語意驅動安裝、先停 launchd，並在模組解析快取說謊時演練雙重重啟緩解。 這份 2026 年 5 月維運手冊固化決策矩陣、停止順序、九步 CI、可觀測性檢查與 FAQ，讓 OpenClaw 在 Apple Silicon 租約上保持可預測。
可與 同伴相依性漂移與乾淨重建、Doctor 診斷手冊 及 macOS 應用程式與 CLI 交接 對照閱讀。專題：OpenClaw 專題索引。另見 說明 與 定價。
即便 OpenClaw 看似「CLI 極簡」，鎖檔仍然重要
閘道為傳輸層、插件與模型介接器打包遞移相依性。若沒有固定的相依圖，兩台 semver 範圍相同的機器也可能在 registry 發布後悄然分叉——這正是可重現 CI 要消滅的惡夢。
package-lock.json；應透過受控升級與程式碼審查重新產生。npm ci 對照 npm install（決策矩陣）
| 命令 | 閘道上何時使用 | 若跳過會怎樣 |
|---|---|---|
npm ci | CI 映像、全新工作區、重建流水線 | 確定性安裝；鎖與 package 不一致時快速失敗 |
npm install | 有意改動鎖檔的探索式升級 | 若未重新提交，日本與美國節點之間漂移 |
npm install --package-lock-only | 準備在不執行指令碼的 PR 中更新鎖 | 仍需審閱遞移相依跳動 |
將 Node.js 與 npm 與閘道版本一併固定
在 CMDB 記錄三元組 (node -v, npm -v, openclaw --version)。使用 Volta、asdf 或 MacPorts 釘版本，並與 OpenClaw 專題 中的 Node 版本指引對齊，使 CI 與租用 mini 執行相同引擎。
NODE_OPTIONS 與插件路徑，重啟即可繼承釘死的工具鏈。碰觸 npm 全域路徑前先停 launchd
launchctl bootout gui/$UID/ai.openclaw.gateway（依你的 plist 調整標籤）。- 透過
pgrep -fl openclaw確認沒有殘留node子程序。 - 至此才執行 npm 變更。
doctor 報告局部目錄樹時的乾淨重建流程
遵循同伴漂移文章的精神：刪除 node_modules，用 npm ci 重裝，重跑 openclaw doctor，並把 stdout 打進支援包。全域安裝則鏡像社群變通：重裝前先移除損壞的 prefix 路徑。
閘道升級的九步 CI 維運手冊
- 快照目前 plist、校驗和與健康 JSON。
- 分支在 Git 中以語義版本標籤管理鎖檔更新。
- 建置使用
npm ci的暫時 CI macOS runner。 - 測試 doctor、合成 webhook 與模型 ping。
- 暫存帶不可變版本的構件到物件儲存。
- 停止生產閘道（依 launchd 政策）。
- 安裝來自暫存構件（不要用漂浮的 latest）。
- 引導若健康抖動則執行兩次（雙重重啟緩解）。
- 發布發行說明與回滾 tarball 位置。
針對陳舊模組解析的雙重重啟緩解
健康檢查通過但執行時仍引用舊雜湊時，短暫休眠後立即第二次執行 launchctl kickstart -k。記錄症狀，以免後繼工程師把它誤判為 TLS 或代理故障。
交叉連結：同伴相依性漂移文章對照本篇鎖檔文章
漂移指南聚焦引爆相依圖；本文聚焦鎖住相依圖。兩者並用：日常建置上鎖，上游發布衝突同伴而需要應急重建時再打開漂移文章。
跨區域閘道推廣的構件快取
香港與美西租戶在同一小時升級時，從公共 registry 拉兩份相同 tarball 容易觸發限速與抖動。把不可變構件提升到自有物件儲存桶（S3 相容、Artifactory 或 GitHub Release 資源），讓每台租約按內容定址 URL 拉取。在變更工單記錄 SHA256，並與 package-lock.json 的 git SHA 並列，便於稽核證明日本與新加坡節點執行了相同位元組。
| 區域 | 建議快取 | 回退 |
|---|---|---|
| HK / SG | 亞太桶複本 | 安裝並發限制為每分鐘 2 次 |
| JP / KR | 東京鄰近邊緣快取 | 傾向夜間視窗安裝 |
| US | 美東主 + 西岸鏡像 | tarball 已快取時使用 npm ci --prefer-offline |
npm ci 前校驗簽章——2026 年的供應鏈事件讓校驗和紀律不再是可選項。常見問題
還能用 install.sh 嗎？ 把指令碼 curl 視為一次性引導——任何重複場景都應過渡到已提交的鎖。
氣隙安裝怎麼辦？ 用 npm pack 產物打包供應商 tarball，在 npm ci --offline 前校驗 SHA256。
哪裡租隔離閘道？ 對照 定價，把日本池與美國池拆開以隔離嘈雜升級。
Dependabot 應自動合併 OpenClaw 升級嗎？ 僅當 CI 已門檻 doctor、webhook echo 與插件圖——否則仍以每週人工審閱為佳。
OpenClaw 專題、說明與區域容量
把鎖檔政策發布在 OpenClaw 專題 的內部版塊，讓每個區域繼承相同的停止順序清單。首爾團隊若需要與新加坡不同的插件集合，應拆分租約而不是在同一鎖圖上硬拗。
