OPENCLAW 2026
POST_INSTALL_
GATEWAY_
PATH_FORCE.

在 macOS 或遠端 Mac 執行 npm install -g openclaw 或官方腳本後，終端機沒有明顯錯誤，但 openclaw ask 卡住、出現 openclaw-gateway: command not found，或 openclaw gateway status 顯示二進位未註冊——這通常不是模型故障，而是 npm 全域前綴與 PATH 漂移、Gateway 註冊步驟被略過、Node 22 多版本命中錯誤、或 launchd 與互動式 shell 環境不一致。本文提供症狀—證據—動作矩陣、五步首跑 Runbook、可引用門檻與 FAQ；並與站內《install.sh 零到生產》《LaunchAgent 與 gateway token》《Chrome Relay 18792》《v2026.5.x 分層維運》交叉閱讀。若需要乾淨對照節點，可把本 Runbook 複製到 MACGPU 遠端 Mac 執行。

1. 痛點拆解：為何「安裝完成」仍像失敗？

1）npm 全域前綴與 PATH：執行檔落在 ~/.npm-global/bin 或 nvm shims，但 shell 未載入對應 PATH。2）Gateway 註冊被跳過：僅下載套件卻未執行 openclaw gateway install。3）Node 22 門檻：系統舊 Node 被優先命中。4）遠端 Mac 的 launchd：SSH 互動環境與 LaunchAgent 非同一套變數。請勿先用 API 限流解釋全部現象。

補充第五類常見誤區：把「安裝日誌沒有 ERROR」等同於「執行時閉環完成」。許多套件在 postinstall 階段只負責下載資產，真正的服務註冊仍需要管理員在正確的 shell 內執行後續指令；若把 CI 的成功徽章直接貼到生產節點卻沒有跑冷啟動探針，夜間仍可能爆雷。第六類則是權限與屬主不一致：以 A 使用者安裝、卻以 B 使用者啟動 launchd，或把執行檔放在 A 的家目錄卻在 plist 內硬寫 B 的路徑，都會造成「看得到檔案卻永遠跑不起來」的假性成功。第七類是企業代理與憑證攔截：npm 下載成功但二進位簽章驗證被攔下，症狀可能延遲到第一次執行才爆；此時應把代理白名單與離線鏡像策略納入維運清單，而不是只在聊天室互相轉發錯誤截圖。

2. 症狀—證據矩陣

現象	優先懷疑	證據
command not found	PATH	which openclaw、npm prefix -g
gateway status 未安裝	註冊缺失	openclaw gateway install --force 前後
互動 OK、launchd 失敗	plist 環境	EnvironmentVariables
僅遠端必現	非登入 shell	ssh -t、家目錄一致性

3. 五步首跑 Runbook

Step 1 凍結執行時三元組

記錄 node -v（須 22+）、which node 絕對路徑。

Step 2 驗證前綴與 PATH

確認全域 bin 已寫入 ~/.zshrc；避免 sudo npm 造成權限分裂。

Step 3 明確註冊 Gateway

維護窗內執行 openclaw gateway install，必要時 --force 並與 token 稿對齊 LaunchAgent 變數。

Step 4 連接埠與健康檢查

區回本機迴圈與 SSH 轉送語意，對照 Chrome Relay 稿的 18792 探針。

Step 5 冷啟動與日誌切片

完整退出後再啟動，匯出固定時間窗的 openclaw logs 分三段附檔。

4. 三道門檻

門檻一：which openclaw-gateway 非空。門檻二：openclaw gateway status 未健康前不切生產流量。門檻三：遠端 Mac 未通過非互動 launchd 冷啟動前，不把筆電隧道當唯一依賴。 建議在門檻二通過後，再追加一次刻意登出所有互動式 SSH 工作階段的驗證，確認沒有人類工程師「順手幫忙 export PATH」造成假陽性；此動作應列入每次重大升級的強制檢核項目。

5. 深度案例

某團隊 2026 年 5 月在遠端 Mac mini 7×24 執行 OpenClaw：工程師登入時 profile 會注入 nvm 與 npm 前綴，導致誤判；夜間 launchd 以最小環境啟動，Gateway 從未穩定註冊。修復為：plist 寫入 Node 22 絕對路徑、補齊 PATH、openclaw gateway install --force，並在維護窗跑 channels probe。此後首包穩定，工單強制附冷啟動證據。對照 v2026.5.x 稿可知：上層外掛與啟動語義再怎麼變，二進位是否在 PATH、服務是否被 launchd 繼承環境仍是底座。

若日誌目錄落在唯讀或網路掛載，安裝程式可能「表面成功」卻反覆崩潰；除 PATH 外亦需檢查 StandardOutPath 與檔案屬主。並行多位同事在同一維護窗執行全域 npm/pnpm 會造成 which 競態，共享自動化帳號尤甚，應串行化並於工單加鎖。

6. 產業觀察

2026 年代理程式普遍套件化：單次 npm 成功不再等於閉環。相較盲目加記憶體或換機，更可複製的槓桿是可稽核清單、維護窗冷啟動、以及變數更少的黃金對照機。若主開發環境在 Windows 或 Linux，要在會議中證明「Gateway 未註冊而非網路抖動」，macOS 對照節點通常更快收斂。對跨時區團隊而言，把「互動式 SSH 驗收」與「LaunchAgent 冷啟動驗收」拆成兩張檢核表，能顯著降低夜班誤判；把 PATH、Node 絕對路徑、stdout/stderr 目錄與屬主寫進變更單，則能把個人經驗轉成可交接資產。

另一個常被忽略的維度是儲存裝置與頻寬：遠端 Mac 若掛載網路磁碟作為快取或日誌根目錄，安裝程式可能在網路瞬断時寫入半套 metadata，表面成功但 Gateway 反覆退出；此時除 PATH 外，應把磁碟本機性與 fsync 行為納入門檻。再者，企業 MDM 或防毒掃描可能拖長首次掃描目錄時間，使「冷啟動 90 秒」門檻必須結合實際安全政策調整，並在文件中註記例外核准流程，避免值班在半夜無法判讀是否該回滾。

Windows 或 Linux 自建 Gateway 可行，但桌面工作階段與瀏覽器工具鏈變數較多；若需要與生產 macOS 對齊的第二現場，遠端 Apple Silicon 仍是低摩擦選項。若希望降低自建成本並取得可寫日誌與穩定供電的獨佔節點，可租賃 MACGPU 遠端 Mac，將五步與三道門檻固化為上線範本。語氣基於可重現排錯，而非品牌教條。

7. 可引用數字門檻

① 冷啟動至健康 gateway status：>90 秒 觸發架構審查。② 首次本機迴圈 ask 探針 >25 秒 無回覆先查 Gateway。③ 同一維護窗 gateway install --force 超過 2 次需人工 diff。④ plist PATH 少於 3 個關鍵路徑預設不合格，直到文件另有規定。

⑤ 維護窗內若同時進行系統更新（Xcode CLT、Rosetta 政策變更）與 npm 全域覆寫，應把作業系統層級變更與套件層級變更拆開兩張變更單，並在第二張單附上第一張單的結案連結，避免事後無法判讀「哪一刀造成 PATH 漂移」。⑥ 對採用 nvm 的節點，建議在 plist 內直接使用 which node 解析出的絕對路徑而非呼叫 nvm 的 shell function，因為 launchd 不會載入互動式 function；此規則應寫進內部標準作業程序，並在 onboarding 時由資深同仁做一次 pair review，降低新同事複製貼上錯誤範本的機率。

⑦ 若組織採用「共享自動化帳號」跑排程，建議為該帳號建立獨立的家目錄與 npm 前綴，並禁止與人類工程師共用同一組全域套件目錄；當出現「剛剛 which 得到、幾分鐘後又消失」的現象時，優先檢查是否有並行 job 觸發全域解除安裝或覆寫。⑧ 對於需要合規稽核的團隊，可把本段門檻直接映射到變更管理系統的必填欄位，讓每次 Gateway 升級都留下可搜尋的證據鏈，而不是只留在聊天室紀錄裡。

8. FAQ

問：doctor 全綠還要 which 嗎？答：要；doctor 驗的是設定語意，which 驗的是同一個 shell 是否看得到執行檔。 問：與 token_mismatch 怎麼分？答：token 問題常伴隨 401／未授權訊息；若程序根本未啟動，應先完成本篇五步再進 token 稿。 問：sudo npm？答：不建議；會把 root 與使用者前綴拆成兩套世界。 問：Relay 紅、gateway 綠？答：走 Chrome Relay 稿，不要回到安裝層重灌。

問：install.sh 與 npm 混用？答：易雙源元資料，請擇一並寫進工單。 問：五步後仍失敗？答：開啟 WebSocket 與 v2026.5.x 稿，但保留本篇附檔作底座證據。 問：要不要先升級硬體？答：在 which 與 gateway status 未綠之前，升級記憶體多半無法縮短排錯時間。 問：遠端 Mac 與筆電差異？答：筆電合蓋睡眠會改變回圈與隧道語意；遠端常駐應以 launchd 冷啟動為準。 問：能否把 Gateway 裝在容器內再掛到主機？答：可行但變數更多；若目標是先證明「註冊與 PATH」無誤，建議先在裸機或單一使用者前綴跑通，再談容器化。