2026 OpenClaw：官方安裝指令稿與 npm 全域路徑（pin、代理備援）

約 14 分鐘閱讀 · MACCOME

適用對象：在新筆電、WSL2、Linux 伺服器或 Windows 主機上佈建 OpenClaw 的工程師，預設採用官方 curl 或 PowerShell 一行指令，卻遇到企業代理、自簽 CA、執行原則或 PATH 缺口，導致指令稿「跑完」但找不到 openclaw。預期收斂：把三平台安裝指南當地圖，把本文當雙軌安裝與 pin 的 Runbook：指令稿路徑通時走快路；不通時改 npm install -g 並鎖明確版本。進doctor 與裝後分診前先確認 Node 與 PATH。版面：六類誤判、對照表、片段、六步 Runbook、三項 KPI、收尾指引。

2026 年為何離開碼為 0，OpenClaw 安裝仍可能已損壞

官方安裝程式會偵測 Node、抓取開機邏輯並註冊全域 CLI，但非互動 shell與企業 TLS常讓「成功」停在下載前：二進位落在使用者前綴，CI 服務帳戶的 PATH 卻看不到；或 npm 全域已裝好，非登入 shell 略過會改 PATH 的 rc。以下六種誤讀最常見。

  1. 忽略文件化的 Node 主版本下限：較舊 LTS 可能仍能跑部分指令，但 Gateway 啟動失敗；以 node -v 對照官方需求表，而非「npm 能跑就好」。
  2. 混用指令稿軌與 npm 軌來源：兩條都跑過後 which openclaw 可能指向不同前綴；除錯設定前務必印出解析路徑。
  3. 代理放行 registry 卻擋指令稿主機：重跑 curl 往往無濟於事；改軌並在資安審核後設定 HTTPS_PROXY、npm config set cafile 或內部 registry 鏡像。
  4. Windows 執行原則與設定檔缺口：PowerShell 顯示成功，但該工作階段缺少 npm 全域 bin；或原則擋下未簽署的遠端指令稿—改用組織核可的包裝或 npm。
  5. 沒有 pin 與變更紀錄：大家用 @latest，Gateway 行為隔夜漂移；常與Gateway 無回覆分診裡「通道看似正常」的情境連動。
  6. 未取指紋就跳到上線：在遠端 Mac 上安裝使用者與常駐程式使用者不一致會變成「裝了但 HOME 不對」；在 systemd／launchd 與Docker 生產 Runbook前先完成本文檢查。

軌道選擇應綁在三平台指南的拓撲：互動開發可偏指令稿快路；無人值守的建置主機應偏利於 pin 的 npm 或內部成品，並把 Node 與 CLI 版號寫進變更單。

若標準是 pnpm／corepack，原則不變：只允許已稽核的進入點，systemd／launchd 的 Environment 須與互動 shell 一致。公開文件仍寫 latest 而內部基線已 pin semver 時，要文件化遷移。

多個 Node 專案共用主機時，把 OpenClaw 執行時主版本與應用程式執行時分離，避免升級連鎖—與多專案集區文章同一套隔離思維，套在 Node 上。

對照表：官方指令稿軌 vs npm 全域軌

依指令稿主機可達性、稽核需求與無人值守營運評分，而非個人偏好。

面向curl／bash 或 PowerShell 軌npm／pnpm 全域軌
首次安裝速度在乾淨網路通常步驟最少須先備妥 Node 與套件管理程式
企業代理契合度依指令稿網域與憑證鏈而定，失敗訊息較吵可拆分 registry、cafile、strict-ssl 與 pin，較利稽核
可重現性最新標籤如未管控的 npm 般漂移明確 [email protected] 可對齊內部 lockfile
無人值守／CI需要非互動保證與 PATH 契約較易 bake 進黄金映像或基底容器
回滾依移除程式的語意而定可依文件順序重裝先前 semver

可執行片段：安裝後三行指紋

輸出貼到工單或 Wiki；在遠端 Mac 上以與未來常駐程式相同的登入脈絡執行。

bash
node -v
command -v openclaw
openclaw --version 2>/dev/null || openclaw version 2>/dev/null || true

# npm 軌範例（semver 換成內部基線）
# npm install -g [email protected]
# npm config get registry
# npm config get cafile
warning

注意：勿把內部 .npmrc 機密貼進公開儲存庫；文件用占位符，憑證放秘密管理服務。

六步 Runbook：從「已安裝」到可快速回滾的基線

  1. 鎖定 Node 基線：以 fnm／nvm 或作業系統套件安裝文件要求的主版本；CI 映像對齊同一 digest pin。
  2. 帶日誌試指令稿軌：使用文件中的官方 curl／bash 或 PowerShell 進入點；失敗時保存完整 TLS 錯誤。
  3. 備援到 npm：套用代理與 cafile 後執行 npm install -g openclaw@<pin>；以 npm ls -g --depth=0 確認只剩一個版本。
  4. 修 PATH 契約：不只互動 rc，還要把全域 bin 注入 systemd／launchd 的 Environment 或 Runner 環境。
  5. doctor 前檢查：安裝使用者須與 Gateway 使用者一致，再開裝後分診表。
  6. 記錄回滾：保留前一個 semver 與移除順序，數分鐘內可還原。

Ansible／Salt 任務須具冪等性：重跑不得默默升到 latest。Windows 資產先把執行原則與 npm 全域路徑寫進 GPO 備註與試點 OU，再全機推廣。

週檢視用的三項 KPI

  1. 安裝到首次通過 openclaw doctor 的延遲：拉長多半代表 PATH、權限或代理，而非模型旋鈕。
  2. 全域重複計數：自動檢查應強制建置主機上只有一個 OpenClaw semver。
  3. 依區域統計的指令稿下載失敗率：區域突增時先查 DNS／MITM，再調模型參數。

現場備註（非基準測試）：2025–2026 企業推廣中，「無 pin 的指令稿軌」跨數十台主機更容易在一夜之間產生漂移工單；「npm 軌＋明確 pin＋變更窗口」差距在可重現性，而非尖峰 CPU。

OpenClaw 與 iOS 建置共用遠端 Mac 時，將 Node／OpenClaw 升級與大型 Xcode 跳版至少錯開一個維護週期，二分搜尋才有意義。

唯讀建置主機可把三行指紋附在 job 摘要（遮罩機密）並對齊 Gateway 啟動時間戳；指紋穩定但行為變了時，優先調模型配額或通道設定，少做重裝迴圈—把無回覆一文的四層分流落到營運。

筆電上快的指令稿，不代表生產常駐程式就穩

互動機器容許試錯；生產需要可稽核軌道、pin 版號、與常駐程式對齊的 PATH 契約。總是拉 @latest 的短命雲端主機會把分診變成猜上游發行。要在遠端 Mac 上以可預測外向流量、磁碟與紀錄維持 Gateway 在線的團隊，多半選具彈性租賃條款的專用 Apple Silicon，而非不停輪換的拋棄式虛擬機。MACCOME 提供多地區 Mac mini M4／M4 Pro 與公開租賃方案，讓 OpenClaw 基線與建置主機採同一套區域策略。

水平擴張前先用單機跑通本 Runbook；對齊失敗指紋與無回覆分診樹，減少重複工。

每季檢視安裝程式網域與 npm registry 允許清單，比在聊天裡事後挖代理紀錄便宜。

把本 Runbook 綁進內部變更範本，讓新叢集預設繼承 pin 與 PATH。

FAQ

與三平台安裝指南的邊界？

指南涵蓋情境與路徑；本文涵蓋雙軌、代理備援與 pin。價格脈絡：雲端租賃價格。

可以略過本機安裝只用 Docker 嗎？

可以，但主機仍須一致的 CLI 與資料卷權限—見 Docker 生產 Runbook。本文仍說明主機上 Node 與 CLI 版號從何而來。

WSL2 與原生 Linux 差異？

systemd 有無、路徑對應、繼承的 Windows 代理皆不同；失敗時優先在 WSL 內用 npm，並設定 WSL 專用的代理與 cafile。