2026 常見閘道部署：Node 版本、埠與 Bearer
1）Node：建議 22 LTS 或 24 LTS；以 node -v 與 openclaw doctor 對齊發行說明。
2）閘道埠：openclaw doctor 會列出本機 HTTP 埠（常見如 18789，實際以輸出為準）；僅綁 127.0.0.1，由企業 TLS 或 SSH 反向轉發對外。
3）守護程序：launchd plist 寫死 NODE_BINARY、PATH、NODE_EXTRA_CA_CERTS；閘道管理 API 使用窄用途 Bearer，與 Azure 入站 Basic 祕鑰、PAT 分桶。
- 痛點一：筆電休眠導致 Webhook 逾時。
- 痛點二：PAT 範圍過大難通過稽核。
- 痛點三：未驗 Basic 祕鑰即執行預拉，易被偽造事件觸發。
# 閘道健康（將 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
決策矩陣：誰適合承載 CI 前置節點
| 面向 | 筆電或臨時 VM | MacPull 遠端 Mac |
|---|---|---|
| 可用性 | 休眠易斷 | 機房常駐、Webhook 穩 |
| 稽核 | 帳號混用 | 專用節點與日誌集中 |
| 管線對齊 | 環境漂移 | 固定 Node 對齊 ADO Agent 池 |
Azure DevOps 觸發器欄位、Webhook 祕鑰與 PAT 最小權限
於 Project Settings → Service hooks → Create subscription 選 Web Hooks，事件例如 Build completed；資源可篩特定管線。Azure 對 Web 掛鉤常見做法為 HTTP Basic：使用者名稱留空、密碼欄填長隨機 Webhook 祕鑰；OpenClaw handler 應解碼 Authorization 後比對密碼，而非僅信任來源 IP。
| 欄位 | 建議填寫 | 備註 |
|---|---|---|
| Payload URL | HTTPS 反代至閘道路徑 | 與閘道路由完全一致 |
| API version | 與文件一致（如 1.0） | 影響 JSON 形狀 |
| Filters | 限定專案／管線／分支 | 降低噪音觸發 |
| Basic 密碼 | 長隨機祕鑰 | 即 Webhook secret 校驗 |
| PAT（出站） | 僅 Build 讀寫所需 | 寫標籤或呼叫 REST |
Handler：Webhook 祕鑰校驗與依賴預拉取
流程：驗 Basic 密碼與可選閘道 Bearer → 解析 resourceContainers／resource 取得 buildId、repository、commitId → 於 mktemp -d 淺克隆該提交 → 執行 npm ci --dry-run 或自訂 pod install／xcodebuild -resolvePackageDependencies 等預拉指令 → 將末段日誌與狀態寫入暫存 JSON。
# 依賴乾跑（示例；於暫存目錄執行） git fetch --depth 1 origin COMMIT_SHA && git checkout --detach FETCH_HEAD npm ci --dry-run 2>&1 | tee /tmp/prefetch.log | tail -n 80
- 以
timeout包住預拉，避免 Service hook 逾時拖滿。 - 多管線並行時限制同時預拉數，保護磁碟與網路。
摘要回傳、日誌 JSON 模板與二四八秒重試
先將摘要寫成單檔 JSON，再以 curl -u :$ADO_PAT 呼叫 dev.azure.com REST（例如建置標籤）；api-version 須與文件一致。非 2xx 時以二四八秒指數退避至多五輪，並保留 /tmp/ado-callback.log。
# 日誌回傳 JSON 模板（寫入 /tmp/ado-summary.json 後可再 POST 至內部觀測或管線工件）
cat > /tmp/ado-summary.json <<'EOF'
{"schema":"macpull.openclaw.ado.summary.v1","buildId":BUILD_ID,"status":"prefetch_ok","durationSec":0,"tailLines":["replace-with-tail-of-log"]}
EOF
# 建置標籤（範例；替換 ORG、PROJ、BUILD_ID、PAT）
for s in 2 4 8 16 32; do
code=$(curl -sS -o /tmp/ado.tag.rsp -w '%{http_code}' -X PUT \
"https://dev.azure.com/ORG/PROJ/_apis/build/builds/BUILD_ID/tags/openclaw-prefetch-ok?api-version=7.1" \
-u ":$ADO_PAT" --connect-timeout 5 --max-time 25)
[ "$code" -ge 200 ] && [ "$code" -lt 300 ] && break
sleep "$s"
done
最小可複現步驟清單
openclaw doctor無紅字；閘道僅127.0.0.1且 health 回200。- Service hook 測試傳送：Mac 端收到並寫入 requestId／訂閱識別。
- 刻意錯誤 Basic 密碼時 handler 回
401且不執行預拉。 - 正確事件下暫存目錄可完成乾跑，磁碟剩餘高於內部閾值。
- 標籤或 REST 回寫成功，且重試迴圈於 2xx 提前結束。
- PAT 僅具 Build 相關最小範圍，無法修改原始碼庫設定。
常見報錯排查 FAQ
Azure 顯示 Webhook 已送達但 Mac 無紀錄？
核對反代 upstream 埠是否等於 doctor 所列；URL 路徑是否含版本前綴；若閘道另要求 Authorization: Bearer，請在反代注入。
回寫 REST 回 401／403？
確認 PAT 勾選範圍含目標專案與 Build；api-version 與 URL 中組織／專案 slug 正確；勿將 PAT 寫入可由管線列印的變數。
Basic 祕鑰比對總失敗？
確認以原始位元組解 Base64；密碼欄不含換行；中介層未剝除 Authorization；與 Service hook 儲存格內密碼一致。