環境清單 · doctor 診斷 · 報錯對照表 · 可復現部署
正在裝機或剛接 Channel 的開發者最常卡在「Gateway 起不來」而不是模型不夠強：Node 版本、目錄權限、.env 與 YAML 拼寫、端口佔用、代理與 DNS，任意一項都會在日誌裏放大成一整頁紅字。本文給你裝機前環境清單、最小安裝 vs 多通道增量對照表、六步診斷流程（含 openclaw doctor 思路）、高頻報錯對照表，以及遷到始終在線節點前的檢查項。需要把常駐與 pm2 口徑一次寫全時，可對照站內 OpenClaw 全天候雲端部署；若要一併規劃遠程算力與下單路徑，可打開 租賃價格說明。
OpenClaw 的安裝腳本通常不複雜，真正耗時的是把運行假設寫清楚：誰在什麼用戶下啓動 Gateway、配置文件從哪裡讀取、日誌默認落在哪、哪些端口必須空閒、代理與 DNS 由誰維護。很多「Gateway 起不來」在根因上並不是 OpenClaw 本身，而是 Node 生態與 macOS 權限模型的組合題。下面五個缺口在 2026 年的社區討論裏反覆出現，把它們寫進 Runbook，能顯著減少「重裝三遍才發現是 PATH 問題」的挫敗感。
如果你計劃後續接 Slack、Telegram 等多通道，更要提前約定密鑰輪換與最小權限目錄，否則第一次接通道成功、第二次改 Token 時就會因爲歷史環境變量殘留而排查困難。
Node 與包管理器版本漂移：OpenClaw 依賴現代 Node LTS；若機器上並存 nvm、fnm 與系統自帶 node，很容易出現「終端裏 node -v 正確、守護進程裏卻是舊版本」。裝機前鎖一條黃金命令行，並在 doctor 輸出裏核對實際進程使用的二進制路徑。
工作目錄與權限邊界不清：把倉庫 clone 到桌面或 iCloud 同步目錄，可能觸發權限或文件鎖問題；生產路徑應落在固定用戶家目錄下的專用子樹，並明確哪些目錄允許 AgentSkills 寫入。
端口與防火牆默認假設：Dashboard 與 Gateway 監聽端口若與本地其他服務衝突，進程會直接退出；Corporate 代理或本機防火牆也可能阻斷出站 LLM API。裝機前用一條端口掃描與一次 curl 出站自測寫進清單。
配置文件多重來源：.env、shell Profile、launchd/pm2 環境塊、YAML 覆蓋層同時存在時，「以爲改了其實沒生效」極常見。約定單一真源：要麼以 .env 爲主並禁止 Profile 覆蓋關鍵變量，要麼以 YAML 爲主並在文檔寫明優先級。
日誌與可觀測性空白：沒有標準輸出落盤路徑、沒有輪轉策略，會在第一次長時間運行就把磁盤打滿或把真正錯誤刷沒。裝機階段就指定日誌目錄與保留天數，比事後補監控便宜一個數量級。
把上述清單勾完，再進入下一節的安裝路徑選擇，你會更清楚自己是「只要一個最小 Gateway」還是「要接多通道的生產拓撲」。
很多團隊第一次部署就把 Slack、郵件、Webhook 全部打開，結果排障矩陣爆炸。更穩妥的路徑通常是：先讓 Gateway 在最小配置下穩定啓動並寫出健康日誌，再逐個增加 Channel Adapter，每次只改一個變量，失敗時能快速回滾。下表對比兩種常見第一階段拓撲，便於你在評審會上對齊預期。
| 維度 | 最小安裝（Gateway + 單通道或僅 CLI） | 多通道增量（2 個以上 Adapter） |
|---|---|---|
| 目標 | 驗證進程、配置解析、LLM 出站與基礎技能 | 驗證消息路由、Token 輪換、並發會話隔離 |
| 配置面 | 環境變量少、YAML 層級淺 | 多份 Webhook/Token/籤名密鑰，錯誤面顯著擴大 |
| 排障順序 | 先看 Gateway 日誌與 doctor，再看模型 API | 需區分 Channel 層錯誤與 Agent 層錯誤 |
| 回滾成本 | 低：注釋一條通道即可對照 | 高：需保留分通道配置快照 |
| 適用人羣 | 首次接觸 OpenClaw 的個人與小團隊 | 已有 Runbook、準備接生產的團隊 |
先讓「空載 Gateway」穩定，再接通道；順序反了，你會在日誌裏同時看到三類錯誤，永遠不知道哪一條是根因。
下列步驟刻意與「通道連不上」區分開：本節只解決進程級失敗（啓動即退出、配置無法解析、端口佔用）。若進程已穩定運行而消息進不來，應在確認 Gateway 健康後再看各 Adapter 的 Webhook 與 Token。社區裏常見的 openclaw doctor（或等價自檢子命令）用於聚合環境與配置檢查——若你的發行版命令名不同，把下面佔位命令替換成官方 CLI 即可。
凍結復現命令：記錄你是用 npm script、全局 CLI 還是 pm2 拉起；把完整命令與當前工作目錄寫進工單，避免「我明明換過目錄但忘了」。
跑環境與配置自檢：執行 openclaw doctor（或官方文檔中的 doctor/fix 變體），保存完整輸出；重點圈出 Node 路徑、權限拒絕、缺失依賴與配置文件校驗失敗行。
分層驗證配置文件：先用只讀方式校驗 YAML/JSON 語法，再核對環境變量是否被 shell Profile 注入舊值；單一真源策略在這裡能省掉一半玄學問題。
檢查監聽端口與佔用：用系統工具確認 Dashboard 與 Gateway 端口未被其他進程佔用；Corporate VPN 有時會劫持本地迴環策略，需要單獨記錄。
抓取啓動後前 200 行日誌：從第一次出現 ERROR 的行向上追溯上下文，而不是只截最後一行；很多根因在更早的警告裡已被提示。
做最小回滾實驗：臨時禁用非必要 Channel 與第三方 AgentSkills，僅保留官方示例技能，確認能否啓動；若可啓動，再二分法逐個恢復插件定位元兇。
cd /path/to/openclaw node -v npm -v openclaw doctor openclaw doctor --fix npm run start 2>&1 | tee /tmp/openclaw-boot.log lsof -nP -iTCP -sTCP:LISTEN | grep -E '3000|8787'
提示：doctor --fix 會改寫本地配置；在生產節點執行前先做文件備份或走變更工單，避免自動修復與你的 intentionally 配置衝突。
下表覆蓋安裝與啓動階段最常見的「看起來像隨機失敗」的組合。請把表格當作一線值班速查卡：先按症狀定位行，再執行優先動作；若三輪動作後仍失敗，再回到第三節做完整日誌抓取與二分回滾。
| 症狀 | 可能原因 | 優先動作 |
|---|---|---|
| 啓動立即退出，終端無棧 | Node 版本不滿足或二進制路徑不一致 | 對齊 nvm/pm2 使用的 node；重跑 doctor 核對 PATH |
| 提示無法讀取配置或 YAML 報錯 | 縮進/編碼/合併衝突殘留 | 語法校驗；對比單一真源；從備份恢復最小配置 |
| 端口已被佔用 | 舊進程未退出或其他服務佔用 | lsof 查佔用；改端口或結束殭屍進程後重啓 |
| LLM 請求超時或 TLS 錯誤 | 代理、DNS、公司 MITM 證書 | curl 出站自測；配置 HTTPS_PROXY；導入信任鏈 |
| Channel 校驗失敗但進程存活 | Token 過期或 Webhook URL 不一致 | 輪換密鑰；對照官方回調地址；勿與 Gateway 啓動問題混排 |
| AgentSkill 執行報 EACCES | 目錄權限或沙箱策略 | 修正目錄屬主；審查技能腳本是否需要額外授權 |
注意：不要在未確認進程模型的情況下反覆執行 sudo npm install -g；全局包與項目本地依賴混用會讓 doctor 報告「已安裝」但運行時仍解析到錯誤路徑。
安裝排障與長期運行是兩件相鄰但不相同的事：前者追求可復現的最小路徑，後者追求崩潰可恢復與可審計。下面三條參數常用於評審材料與值班交接，它們不替代官方文檔，但能把「感覺不穩定」翻譯成可測指標。
當你確認本地或辦公室環境無法滿足無人值守與彈窗零容忍時，遷雲前的自檢應額外包括：進程守護是否已驗證重啓策略、Dashboard 是否默認關閉公網、日誌輪轉是否啓用。更完整的 pm2 與端口口徑可直接復用站內 OpenClaw 全天候雲端部署 一文中的生產條目。
安全提醒：即便只是安裝階段，也不要在公共聊天裡粘貼完整 .env；用一次性密文通道或密鑰管理器交付，並在 Runbook 寫明吊銷流程。
相比在個人筆記本上反覆處理休眠、系統更新與多人共用會話帶來的隨機性，獨佔、可按地區部署的雲 Mac 節點更容易把「裝得起來」推進到「天天裝得起來」。本地或借用設備在籤名隔離與長期可用性上往往存在隱性天花板；對於要把 OpenClaw 與自動化工作流寫進交付標準的團隊，VpsMesh 的 Mac Mini 雲端租賃通常是更優解：Apple Silicon 原生環境、7×24 在線、按周期彈性租用，讓你把精力放回 Gateway 配置與業務邏輯而不是機器狀態。