OpenClaw Node 22 2026.05.21

2026 年雲端 Mac 安裝 OpenClaw 全流程： Node 22 環境、onboard 守護行程與 TCC 權限設定清單

JEX
JEXCLOUD 工程團隊
· 2026年5月21日 · 約 12 分鐘閱讀

剛在 JEXCLOUD 拿到一台「空」的雲端 Mac，卻卡在 OpenClaw 裝不上、onboard 半途失敗、Gateway 起不來？2026 年最常見的原因不是「指令敲錯」，而是Node 版本低於 22、無頭環境未開 TCC、launchd 讀不到 gateway.auth.token 這三類前置缺口。本文面向首次在租用 Mac 上部署 OpenClaw 的開發者與 AI 自動化團隊，給出 Homebrew / npm / 原始碼選型矩陣、Node 22+ 預檢、六步 onboard + 守護行程驗收、VNC 下的 TCC 勾選清單（安裝細節可參考 OpenClaw 官方 onboarding）。

讀完你應能回答三件事：① 你的流水線該用 brew 還是 npm 裝 CLI；② openclaw onboard --install-daemon 之後如何用 doctor 斷言 Gateway 已監聽 127.0.0.1:18789；③ 權限彈窗無人值守時，如何透過 VNC 一次性授權再進入遠端 Gateway 配對階段。

01 2026 雲端 Mac + OpenClaw：空機部署場景與五大痛點

與多節點選型與 launchd 排障不同，本篇聚焦「執行個體剛交付、尚未安裝 OpenClaw」的 0→1 路徑：你只有 SSH（必要時 VNC），沒有公司內網 Golden Image，也沒有同事機器上的 ~/.openclaw 可拷貝。

在評審會上，這五類痛點最容易被低估：

  • Node 版本漂移：系統自帶 Node 18/20，Gateway 執行時要求 Node 22 LTS（22.16+）或 Node 24，導致 openclaw onboard 在相依性解析階段直接退出。
  • 安裝通道選錯：CI 映像習慣 npm 全域，維運習慣 Homebrew；混用會導致 PATH 上存在兩個 openclaw，doctor 報版本不一致。
  • TCC 無人應答：自動化、輔助使用、螢幕錄製等權限在純 SSH 下無法點擊「允許」，Gateway 或通道探測會間歇失敗。
  • Token 寫入方式錯誤：2026 年設定鍵為 gateway.auth.token（非舊版 gateway.token）；僅寫在 .zshrc 而 launchd 未繼承時，會出現「Gateway auth is set to token, but no token is configured」迴圈。
  • 記憶體與儲存低估：多 Agent + 本地模型快取時，M4 16GB 易觸發 swap；大儲存庫建議提前評估 1TB/2TB 擴容 或 M4 Pro（見文末選型）。

記憶口訣：「先 Node 22，再 CLI 單一路徑，再 TCC，最後 onboard + daemon」。跳過任一步，後面配對與隧道排障都會變成小時級返工。

02 Homebrew、npm 還是原始碼：OpenClaw 雲端 Mac 安裝路徑決策矩陣

OpenClaw 在 macOS 上支援多種安裝入口；在僅 SSH 的雲端 Mac上，應優先選「可重複、可腳本化、與團隊 CI 一致」的那一種。

OpenClaw CLI 安裝路徑對照（2026 雲端 Mac 生產視角）
維度 Homebrew npm 全域 原始碼建置
適用團隊 Mac 維運、希望與 brew 生態統一 Node 流水線、已有 pnpm/npm 快取 需 pin commit、打私有修補
前置相依 brew 已裝；Apple Silicon 用 /opt/homebrew Node 22+、npm 10+ git、pnpm、Xcode CLT
升級方式 brew upgrade openclaw npm update -g openclaw 拉 tag + 重新 build
PATH 風險 低（brew link） 中（與 nvm/fnm 衝突） 高（需手動 symlink）
JEXCLOUD 推薦 個人/小團隊快速開通 與 GitHub Actions 腳本同構 僅在有合規 pin 需求時

無論選哪條路徑，安裝後都應執行 which -a openclaw 確保僅一條可執行路徑，並 symlink 到 /opt/homebrew/bin 或 /usr/local/bin，避免 launchd 的 ProgramArguments 指向互動式 shell 裡的臨時 PATH。

03 Node 22 環境預檢：版本、架構與磁碟餘量

在執行 openclaw onboard 之前，用非互動指令斷言環境，避免半夜 on-call 才發現「裝到一半」。

preflight-openclaw.sh 
node -v | grep -E 'v22\.(1[6-9]|[2-9][0-9])|v24\.' || exit 1
uname -m | grep -q arm64
df -h / | awk 'NR==2{gsub(/%/,"",$5); if($5>85) exit 1}'
xcode-select -p || xcode-select --install

若 Node 不達標，推薦用 fnm 或官方 pkg 安裝 Node 22 LTS，並在登入 shell 與 launchd 環境保持一致：對守護行程更穩妥的做法是把 Token 寫入 ~/.openclaw/openclaw.json 的 gateway.auth.token，而不是只 export 在 .zprofile。

  • 可引用：Node 最低版本 — Gateway 執行時要求 Node 22.16+ 或 Node 24（以官方 onboarding 文件為準）。
  • 可引用：預設 Gateway 連接埠 — 18789，安裝後 lsof -i :18789 應僅見 127.0.0.1。
  • 可引用：磁碟建議 — 除系統卷外，建議至少預留 30 GB 給相依快取與日誌；多 Agent 並行時考慮 512 GB→1 TB 擴容。

04 雲端 Mac 安裝 OpenClaw 六步：SSH 接入到 onboard 守護行程驗收

  1. SSH 接入與基礎工具：按 說明中心 設定金鑰登入；確認 sw_vers 為 macOS 14+，時鐘同步正常（TLS 與 Token 校驗依賴系統時間）。
  2. 安裝 Node 22 與 CLI 單一路徑：示例 brew install node@22 && brew link --overwrite node@22，或 npm install -g openclaw@latest；執行 openclaw --version。
  3. 執行 onboard：openclaw onboard 按精靈選擇 Gateway；需要背景常駐時加 --install-daemon，會註冊 LaunchAgent ai.openclaw.gateway。
  4. 寫入 gateway.auth.token：openclaw doctor --generate-gateway-token 或手動編輯設定；chmod 600 ~/.openclaw/openclaw.json；若 launchd 不讀 shell，執行 launchctl setenv OPENCLAW_GATEWAY_TOKEN '…' 後 launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway。
  5. doctor 驗收：依序執行 openclaw status、openclaw gateway status、openclaw doctor；健康輸出應含 Runtime running、RPC probe ok；curl 本機 /health 回傳 200。
  6. 登記維運基線：將日誌目錄納入輪替；在 定價頁 評估是否升級 M4 Pro 或並聯第二台建置機；準備進入本機 App 遠端配對階段。
驗收指令（雲端 Mac） 
openclaw onboard --install-daemon
openclaw doctor
lsof -nP -iTCP:18789 -sTCP:LISTEN
TOKEN=$(openclaw config get gateway.auth.token)
curl -sf -H "Authorization: Bearer $TOKEN" http://127.0.0.1:18789/health

若 openclaw gateway restart 由 Agent 自動觸發後無法恢復，社群常見修復是 openclaw gateway install --force（見 openclaw#40306）；勿在未完成 doctor 驗收前反覆卸載重裝。

05 TCC 權限清單：VNC 下一次性授權與可引用參數

雲端 Mac 常處於無實體顯示器狀態；macOS 隱私（TCC）彈窗必須透過 VNC / 螢幕共享 由真人或值班同學點擊。下表按任務勾選，避免過度授權。

OpenClaw 相關 TCC 權限勾選建議（2026）
系統設定項 何時需要 未授權時的典型現象
自動化 (Automation) Gateway 驅動本機 App / 腳本 通道 probe 失敗、權限被拒日誌
輔助使用 (Accessibility) UI 自動化、部分通道外掛 onboard 卡在權限步
螢幕錄製 截圖/視覺類 Agent 工具 工具呼叫回傳空圖或逾時
完整磁碟存取 僅當工作流讀受保護目錄 讀取 Desktop/Documents 失敗

授權完成後，建議鎖定 VNC 僅內網或 SSH 隧道存取，並在變更紀錄中註明授權時間與操作者，滿足稽核要求。

06 安裝 FAQ、Token 排障與 JEXCLOUD 配置收束

OpenClaw 雲端 Mac 首次安裝常見報錯
報錯 / 現象 優先檢查 處理動作
onboard 憑證 / 模型失敗 網路、系統時間、代理 校時；設定企業代理；重跑 onboard
token_missing_config loop launchd 未繼承 Token 寫入 openclaw.json；launchctl setenv；kickstart gateway
command not found: openclaw PATH、多版本 CLI which -a；統一 brew 或 npm；symlink 到標準 bin
連接埠 18789 占用 舊 Gateway 行程 lsof 查 PID；gateway install --force

把 OpenClaw 裝在家用 Mac 或不穩定 Wi‑Fi 筆電上，常因睡眠與自動更新導致 Gateway 半夜掉線；裝在超賣 VPS 或非 macOS 環境則無法通過 Apple 通道與 TCC 合規路徑。對需要數小時內完成 0→1 安裝、Node 22 可重複、裸金屬獨占算力的團隊，在 JEXCLOUD 多區域雲端 Mac 上按本文六步落地，再銜接節點選型與遠端配對文章，通常是更省心的路徑：約 120 秒交付、可按專案升級 M4 Pro 與 1TB/2TB 儲存。套餐見 JEXCLOUD 定價頁。

返回博客列表
標籤： OpenClaw Node 22 onboard TCC