openclaw onboard／doctor、僅回環閘道與儀表板 Bearer 令牌為主軸；並以 /health 做存活探針。站內延伸：閘道健康與 LaunchAgent、失敗恢復與重試、閘道安全硬化。對齊 docs.openclaw.ai。
環境與最小權限準備
1）Node 與 CLI 單一路徑：擇一使用官方 curl 安裝或 npm i -g openclaw，勿混兩套全域二進位；launchd plist 與互動 SSH 的 PATH 必須一致。
2）閘道面：HTTP 服務建議只聽 127.0.0.1，對外由反向代理或隧道終止 TLS；閘道 API 用窄用途 Bearer，與 Jenkins 觸發用 token／HMAC 祕鑰分桶存放。
3）工作目錄：每次預檢使用獨立暫存目錄（mktemp -d），結束刪除，避免並行 job 互相覆寫 vendor 或 node_modules。
- 執行
openclaw doctor，確認憑證、代理與埠占用；必要時設NODE_EXTRA_CA_CERTS。 - 以排程或監控每 60 秒打
/health，異常時告警而非靜默當機。
# 閘道健康（替換 PORT、GATEWAY_TOKEN）
curl -sS -o /dev/null -w '%{http_code}\n' \
-H 'Authorization: Bearer YOUR_GATEWAY_TOKEN' \
--connect-timeout 3 --max-time 10 \
http://127.0.0.1:PORT/health
凍結版本：在節點上記錄 node -v 與 OpenClaw 套件版號，升級前先在複本機驗證。
帳號權限：守護程序帳號僅需讀設定、寫日誌與存取暫存目錄，勿給 sudo。
祕鑰：Jenkins 側用「認證／Secret text」注入，Mac 側用 launchd EnvironmentVariables 或檔案權限 600。
Jenkins Generic Webhook 與簽名校驗參數
於流水線或 Job 啟用 Generic Webhook Trigger：產生含隨機路徑 token的 URL（等同第一道共享祕鑰），POST 內文為 JSON；以 JSONPath 或 Optional Filter 取出 job、build、git_url、sha 等欄位再決定是否觸發下游。若需第二道驗證，可約定自訂標頭攜帶 HMAC-SHA256（對原始 body計算），或由 Nginx／API Gateway 先驗簽再轉發至 127.0.0.1。
| 項目 | 建議值／行為 | 目的 |
|---|---|---|
| URL token | 長隨機字串，僅寫入 Jenkins 與 OpenClaw 設定 | 防掃描與誤觸發 |
| Content-Type | application/json | 與 handler 解析一致 |
| HMAC 標頭（選用） | 例如 X-Webhook-Signature: sha256=<hex> | 防偽造 body |
| Silent response | 依需求開啟，避免 Jenkins 等待過長 | 預檢重時先 ACK 再非同步 |
| Restrict／白名單 | 限定來源 IP 或內網 | 邊界防護 |
OpenClaw 側接收、呼叫 composer／npm 等預檢命令模板
Handler 流程：驗 token／HMAC → 解析 JSON → git clone --depth 1 至暫存目錄並 git checkout 指定 SHA → 依專案類型執行下列唯讀或 dry-run指令 → 將 stdout／stderr 末段裁切為摘要。矩陣建置建議由上游聚合 job呼叫一次閘道，避免重試風暴。
# PHP／Composer（專案根目錄） composer validate --no-check-publish composer install --dry-run --no-interaction --no-ansi # Node／npm（有 package-lock 時） npm ci --dry-run # 併行記錄（示例） ( composer validate --no-check-publish && composer install --dry-run --no-interaction ) 2>&1 | tail -n 80
- 超時：為每道子程序設
timeout或gtimeout（例如 300s），避免 Jenkins 端一直等不到回應。 - 鏡像：跨境時於同一節點設定
COMPOSER_MIRROR_PATH_REPOS、NPM_CONFIG_REGISTRY，並與站內 PHP／Composer CI 矩陣專文參數對齊。
建置摘要回傳（HTTP／Webhook）與失敗重試
預檢結束後，以 curl 對Jenkins 通知 URL、自建狀態 API 或第二個 Generic Webhook送出 JSON：含 status（success／failed）、job、build、duration_ms、summary（截斷至約 2KB）。務必設定 --connect-timeout 與 --max-time；非 2xx 時採 2／4／8 秒指數退避，最多三至五輪（與前節失敗恢復文一致）。
# 摘要回傳示例（替換 URL 與 TOKEN）
STATUS=success
SUMMARY="$(tail -n 40 /tmp/preflight.log | sed 's/"/\\"/g')"
curl -sS -X POST "$CALLBACK_URL" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $CALLBACK_TOKEN" \
--data "{\"status\":\"$STATUS\",\"summary\":\"$SUMMARY\"}" \
--connect-timeout 5 --max-time 25 \
--retry 3 --retry-delay 2 --retry-all-errors
常見報錯排查 FAQ
Jenkins 顯示已送達但 OpenClaw 無日誌？
核對 URL 路徑 token、代理是否轉發到正確本機埠；若閘道要求 Authorization，需在 Jenkins HTTP Request 或前置代理補標頭。
簽章驗證總是失敗？
確認雙方對原始 body 位元組計算 HMAC，而非格式化後 JSON；祕鑰尾端空白、編碼 UTF-8 與 Jenkins 外掛選項需一致。
composer／npm 在守護程序裡找不到？
在 launchd 寫死 PATH、COMPOSER_HOME；勿只依賴登入 shell 的 nvm；以 which 與 openclaw doctor 驗證。
回傳摘要逾時或 502？
縮短摘要長度、改非同步 ACK；檢查企業代理對 Jenkins 內網 URL；失敗時把 body 落盤待下一輪 job 重送。