2026 加拿大雲 Mac M4 無頭 OpenClaw CI：install-cli.sh、--no-onboard 與 Mac mini 託管 launchd 探針

平台團隊把 OpenClaw 遷到加拿大遠端 Mac M4 時，常見誤區是照搬桌面 playbook：開啟螢幕共享、跑完整 openclaw onboard，再指望 SSH 斷線後 Gateway 仍存活。CI 與批次工作負載需要的是另一套契約——以官方 install-cli.sh 搭配 --no-onboard 的無頭（headless）安裝路徑、預先注入的配置，以及 launchd 健康探針，而不是向導式互動。本文只回答一個問題：如何在 雲 Mac / Mac mini 雲 構建席位上落地可復現的無頭 OpenClaw CI。它不會重述 SSH 隧道 vs 直連 Gateway 的選型（見 OpenClaw 加拿大 M4：SSH 閘道、18789 Token 與 launchd），也不展開互動式 onboard 的 7×24 日誌 playbook（見 遠端 Mac 安裝 onboard 與 LaunchDaemon 24/7 跑穩）。若同一台 Mac mini hosting 還要跑 GitHub Actions runner，請依 雲 Mac 自建 macOS runner 分 Unix 使用者與 launchd 標籤，避免 Node 版本與連接埠 18789 互搶。

1. 何時必須用無頭 --no-onboard，而非互動 onboard

互動式 openclaw onboard 適合在有真實 GUI 工作階段的 Mac 上，由操作員核准 TCC（輔助使用、自動化、螢幕錄製）。這是開發者筆電首次部署的正確體驗。當目標是僅能透過 SSH 或自建 runner 觸達的 雲 Mac CI 專線，且配置已由內部模板產生時，繼續呼叫向導會阻塞 pipeline，並製造無法從 Git 重建的「雪花主機」。

無頭契約如下：

• 透過 install-cli.sh 固定 Node LTS 與全域 openclaw CLI semver。
• 傳入 --no-onboard，從 Secrets 管理同步配置目錄（路徑依上游文件，常見 ~/.openclaw）。
• 僅在 agent 仍需瀏覽器自動化且需 TCC 時，安排一次性螢幕共享視窗；之後純靠 launchd 運維。

相較我們的「遠端 Mac 跑穩」筆記，本文交付的是可版本化的 CI Runbook 與探針腳本——不是桌面操作員手冊。若團隊仍在每台新席位手打 onboard 答案，尚未達到無頭成熟度。

2. 無頭 install-cli.sh vs 完整 onboard：如何選擇

向 Mac mini 雲 供應商新購席位時，先跑無頭 smoke pipeline。團隊若「手動 onboard 一次」，常會在數週後發現無法在一小時內災備恢復 Gateway。

3. 無頭佈建 Runbook：install-cli.sh 與配置注入

以下範例假設專用系統使用者 openclaw-ci，與 VNC 管理員帳號隔離。在 加拿大 M4 雲 Mac 上，Node 建議 pin 到 LTS（2026 年 22.x 是合理基線），並與 runner 使用者的 nvm shim 分離——launchd job 不會載入互動式 shell profile。

# 以 openclaw-ci 使用者 SSH 登入雲 Mac
export OPENCLAW_CONFIG_DIR="$HOME/.openclaw"
curl -fsSL https://example.openclaw.dev/install-cli.sh | bash -s -- --no-onboard

# 從 CI Secrets 還原 config——勿把 Token 提交到 Git
install -d -m 700 "$OPENCLAW_CONFIG_DIR"
echo "$OPENCLAW_CONFIG_JSON" > "$OPENCLAW_CONFIG_DIR/config.json"

# 若支援，安裝 Gateway launchd 服務
openclaw gateway install-daemon
openclaw doctor --non-interactive

區分業餘安裝與生產 雲 Mac 專線的運維要點：

1. 冪等性：workflow 必須容忍重跑。良好腳本在已安裝時應 no-op 或收斂版本。
2. Semver 鎖：在 Runbook 記錄 openclaw --version 與 config schema 版本；升級走變更窗並準備回滾。
3. 磁碟布局：npm/pnpm 快取放在可獨立清空的 path；若同機還建 iOS 產物，與 Derived Data 分區。
4. Checksum：生產環境 pin 安裝腳本 digest；裸 curl | bash 無校驗是供應鏈事故候選。

4. launchd 健康檢查：程序、連接埠與日誌三角

無頭模式下，「Gateway 似乎在线」常意味著有人在 PATH 完整的 SSH 工作階段跑過一次 curl。生產探針應同時驗證 launchd 狀態、監聽位址與日誌關鍵字。建議每五分鐘以 cron 或排程 GHA workflow 執行：

#!/bin/bash
set -euo pipefail
LABEL="ai.openclaw.gateway"
launchctl print "gui/$(id -u)/$LABEL" | grep -q 'state = running'
lsof -nP -iTCP:18789 -sTCP:LISTEN | grep -q openclaw
curl -sf -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/health | grep -q '"ok":true'
tail -n 50 ~/Library/Logs/openclaw/gateway.log | grep -Ei 'sharp|EADDRINUSE|401' && exit 1 || true

plist 必須以絕對路徑呼叫 openclaw，並在 EnvironmentVariables 中明確設定 PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin。launchd 不讀互動式 ~/.zprofile。這種不匹配是租用 雲 Mac 上「SSH 手動能跑、daemon 立刻退出」的首要原因。

建議擴展探針時序指標：追蹤 /health p95 延遲，冷啟動超過 workflow 超時預算時告警。互動式四秒回應、launchd 下卻需三十秒的 Gateway，仍可能讓重試次數緊的 CI job 失敗。

5. 探針結果矩陣：綠、黃、紅如何處置

黃色持續超過二十四小時應視為發布阻塞。無頭 CI 假設 Gateway 行為可預測；間歇性認證或延遲失敗會在 agent 側放大為整批超時，且無 VNC 時除錯成本很高。

6. Apple Silicon 雲 Mac 上的 sharp 原生模組除錯

OpenClaw 依賴圖包含 sharp（libvips 綁定）。在 M4 arm64 主機上，Node 大版本不一致或安裝使用者混用，會出現 Cannot find module '../build/Release/sharp.node' 或執行期架構不匹配。無頭 CI 不能在首次失敗 job 才發現——應在 golden image 或 post-install hook 中烘焙 sharp 驗證。

6.1 常見失敗模式與修復

• 使用者不一致：root 安裝全域 CLI，openclaw-ci 跑 daemon——以服務使用者重裝 sharp 或 CLI。
• Node 升級未重建： bump Node 後執行 npm rebuild sharp 或重裝 openclaw CLI 套件。
• Rosetta 混用：plist 與 CLI 必須皆 arm64；file $(which node) 應回報 arm64。
• 離線快取：在頻寬受限的 Mac mini 雲 主機預取 sharp 二進位，避免 CI 每 job 打 GitHub releases。
• 多 Node 管理器：避免 daemon 用 Homebrew Node、互動 shell 用 nvm——選一種故事並寫入 plist。

node -p "process.arch + ' ' + process.version"
npm ls sharp --global 2>/dev/null || true
npm rebuild sharp --foreground-scripts
openclaw doctor 2>&1 | tee /tmp/openclaw-doctor.log
grep -i sharp /tmp/openclaw-doctor.log && exit 1 || echo "sharp OK"

若 doctor 仍報 sharp，先從同一 install-cli.sh 產物對齊 Node 與 CLI 安裝渠道，再追應用層 bug。Homebrew Node 混 npm 全域 CLI 且 plist PATH 未修，是我們在 Mac mini hosting 工單中最常見的 sharp 邊緣案例。

7. CI 中 Gateway 18789 邊界與 Token 輪換

無頭 pipeline 應以 Bearer Token 呼叫本機 Gateway 127.0.0.1:18789——切勿把連接埠暴露到公網介面。Token 存於 CI Secrets（如 OPENCLAW_GATEWAY_TOKEN）。輪換流程：把新 Token 寫入 config、reload daemon、探針全綠，再廢舊 Secret。回環存取在 runner 與 Gateway 共用一台 雲 Mac 時延遲最低；跨主機呼叫請回到上文 SSH 閘道筆記。

workflow 應設明確超時與有限重試。重開機後冷啟動可能需十到三十秒；探針失敗應先 launchctl kickstart 一次，再考慮破壞性重裝。記錄此行為，避免 on-call 在 macOS 修補後的短暫 boot storm 中清掉可用 config。

8. 託管 Mac 席位上無頭 OpenClaw 的安全基線

• 專用使用者：openclaw-ci 無 admin、無 VNC 登入。
• Secrets：config 與 Token 僅來自 vault；磁碟開啟 FileVault。
• 網路：入站僅 SSH 或 Tailscale；勿在 LAN 廣播 18789。
• 供應鏈：校驗安裝腳本 checksum；生產禁止未審計的 pipe-to-bash。
• 審計：gateway.log 保留十四天；把 401 與 sharp 關鍵字送到日誌棧。
• 爆炸半徑：agent tools profile 遵循最小權限；不可信 fork PR 不得觸達生產 Gateway 主機。

無頭自動化提升交付速度，也移除了「人眼掃一眼可疑安裝 URL」的緩衝。請把安裝腳本 URL 與 checksum 與生產 TLS 憑證同等嚴格對待。

9. 將無頭 OpenClaw 接入 GHA 或內部 CI

Gateway 探針全綠後，再透過受控步驟暴露 OpenClaw 給 pipeline：

1. 從 GitHub Environments 匯出 OPENCLAW_GATEWAY_TOKEN，生產環境設必要審批人。
2. agent job 使用 runs-on: [self-hosted, macos-m4-canada, openclaw] 標籤，與簽名或 archive job 分離。
3. 在昂貴 LLM 或瀏覽器步驟前，先跑與 cron 相同的 shell 探針，快速失敗。
4. 失敗時把 openclaw doctor 輸出存為 workflow artifact，供非同步審閱。

記憶體規劃：在 24GB Mac mini 雲 席位上，若同晚還要跑 xcodebuild archive，統一記憶體壓力超過八成時應暫停 OpenClaw agent 批次。佇列深度告警可避免把「GitHub 變慢」誤當根因，而實際是主機過載。

10. 加拿大 M4 專機首週檢查清單

1. 選定 Mac mini hosting 方案（CI + Gateway 建議 24GB RAM、512GB SSD 起）。
2. 建立 openclaw-ci，通過 install-cli.sh --no-onboard smoke 測試。
3. 注入 config 與 Token；確保 openclaw doctor --non-interactive 乾淨。
4. 安裝 launchd，部署綠/黃/紅探針與分頁告警。
5. 預驗證 sharp；在 Runbook 鎖定 Node 與 CLI 版本。
6. 若共用 GHA runner，驗證分使用者且無連接埠衝突。
7. 文件化重建：新 雲 Mac 席位應在三十分鐘內達到相同 Gateway 行為。

11. FAQ

--no-onboard 後還需要 VNC 嗎？

若 agent 需要瀏覽器自動化或 TCC 權限，安排一次性圖形工作階段。純 CLI 或 API Gateway 工作負載在 launchd 穩定後可無 VNC 長期運行。

install-cli.sh vs 完整 install.sh？

CI 只需 CLI 加 Gateway 時用 install-cli.sh。附選單列 App 的完整安裝包不適合重複無頭 runner 部署。

探針回 401 但程序在跑？

通常是 Token 輪換漂移或 workflow 仍送舊 Secret。對齊磁碟 config 與 Authorization 標頭；檢查注入過期 Token 的代理。

sharp 在 launchd 下失敗、SSH 正常？

幾乎總是 PATH 或使用者環境差異。並排比對 launchctl print 環境區塊與互動 env 輸出。

能在 macOS 上用 Docker 跑 OpenClaw Gateway 嗎？

Mac 上 Docker 無法取代原生 TCC 與 GUI 自動化需求。Gateway 應跑在原生 launchd；容器僅適合周邊工具。

如何在一台主機上排程 OpenClaw 與 GitHub Actions？

agent 批次避開 archive 高峰；記憶體壓力超過八成時暫停 agent。標籤與並發指引見 自建 runner 一文。

Hashvps 加拿大節點適合無頭 OpenClaw 嗎？

適合需要專用 IPv4、裸機 M4 與常駐 SSH 的團隊。承諾前確認磁碟檔位能否容納 npm 快取與輪轉 gateway 日誌。

標準 CLI 升級流程是什麼？

維護窗：launchctl bootout，經 install-cli 收斂版本，npm rebuild sharp，doctor，探針全綠，再恢復流量。