workflow-completed／job-completed 時將 JSON POST 到遠端 Mac上的 OpenClaw 閘道（通常經反向代理或隧道對接到 127.0.0.1）。閘道驗證 circleci-signature 後，於隔離目錄淺克隆觸發提交，執行 lockfile 漂移掃描（git diff、npm ci --dry-run 等），再把建置摘要回傳 Slack／Discord／自建 API。自動化流水線中，閘道把「事件入口、簽章校驗、本機工具鏈、出站通知」收斂到單一常駐服務，利於審計與重試。站內可對照 GitHub Checks × lockfile與 Jenkins Generic Webhook 預檢。對齊 docs.openclaw.ai 與 CircleCI Outbound webhooks 官方說明。
前置條件（Node／openclaw CLI、令牌與最小權限）
1）Node 與 openclaw CLI：2026 主線建議 Node 22.16+ 或統一 24 LTS；擇一以官方腳本或 npm i -g openclaw 安裝，勿混兩套全域路徑。執行 openclaw onboard 與 openclaw doctor，確認憑證、代理與埠占用。
2）閘道與令牌分桶：HTTP 服務綁 127.0.0.1，對外僅經 TLS 終止或隧道；閘道 Bearer、CircleCI Signing secret、出站摘要 API 的令牌分開存放（環境變數或權限 600 檔），避免一鍵外洩全線失守。
3）執行身分：守護程序帳號只需讀設定、寫日誌、git clone 暫存目錄與呼叫套件管理器；勿給 sudo。launchd 的 PATH 須與互動 SSH 一致，必要時明寫 NODE_EXTRA_CA_CERTS。
- 每輪掃描使用
mktemp -d，結束刪目錄，避免並行 workflow 互相覆寫工作樹。 - 監控每 60 秒請求
/health，閘道異常時告警，避免 Webhook 靜默失敗。
# 閘道健康（替換 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 與 CircleCI CLI（若用）版號，升級前在複本機跑通同一 handler。
最小權限：僅在需要寫入 Checks／PR 註解時才發 PAT；純 lockfile 掃描＋出站 Webhook 多數只需讀倉庫與出站 HTTPS。
祕鑰注入：Mac 側用 launchd EnvironmentVariables 或 security find-generic-password 拉取，勿把 secret 寫進版本庫。
CircleCI Webhook 與校驗配置步驟
於 CircleCI Web App：組織 → Projects → 專案⋯ → Project Settings → 側欄 Webhooks → Add Webhook。每專案最多 五個 Outbound Webhook，新增／刪除需組織管理員權限。請勾選至少一種事件，實務上常以 workflow-completed 做門檻判定，或以 job-completed 對單一 job 回傳摘要。
官方傳輸要點：POST、application/json；若填了 Secret token，請求帶 circleci-signature，內為逗號分隔 v1=<hex>（只驗 v1）。v1 即以 secret 對原始 body做 HMAC-SHA256 的 hex，比對請用常數時間。接收端須在短逾時內回 2xx（約十秒級），否則重送；同一事件可能重複傳遞，以 payload id 去重。
- 接收 URL 已具備有效 TLS（正式環境勿關閉憑證校驗）。
- 反向代理把
circleci-signature、circleci-event-type原樣轉發至 OpenClaw。 - Handler 先解析
circleci-event-type與 workflow／job 狀態，再決定是否進入 lockfile 掃描。 - 已用 Test Ping 驗證端到端，並在日誌中留存去重鍵與處理耗時。
| 項目 | 說明 |
|---|---|
user-agent | 含 CircleCI-Webhook/1.0，可輔助防火牆規則 |
circleci-event-type | 如 workflow-completed、job-completed |
circleci-signature | v1=<hmac-sha256-hex>，對未改動的 body驗簽 |
payload id | 事件去重與稽核主鍵 |
OpenClaw 技能／腳本模板（解析 lockfile、生成摘要）
建議處理順序：① 驗證 circleci-signature v1；② 解析 JSON 取得倉庫 URL、revision（或 pipeline 關聯 SHA）；③ git clone --depth 1 到暫存目錄並 git fetch／checkout 目標 SHA；④ 依專案類型執行下列唯讀或 dry-run；⑤ 將 stdout／stderr 末段與狀態欄位組成 JSON，供下一節 POST。若掃描可能超過 CircleCI 的短回應窗口，應先快速回 2xx，再把重活丟入本機佇列（與閘道「自動化匯流排」角色一致）。
# 範例：偵測 lockfile 是否相對預設分支漂移（於 CI 觸發 SHA 的工作樹內）
BASE_REF="${BASE_REF:-main}"
git fetch origin "$BASE_REF" --depth=1 2>/dev/null || true
for f in package-lock.json pnpm-lock.yaml yarn.lock Cargo.lock Gemfile.lock; do
[ -f "$f" ] || continue
if git diff --name-only "origin/${BASE_REF}"...HEAD -- "$f" | grep -q .; then
echo "DRIFT:$f"
fi
done
# Node：有 package-lock 時的乾跑（不寫 node_modules）
npm ci --dry-run 2>&1 | tail -n 60
OpenClaw 技能可把上列步驟封裝為參數化動作（repo、sha、base_ref），輸出 { drift, logs, duration_ms } 再決定是否呼叫出站 Webhook。矩陣 workflow 宜由彙總 job觸發一次，避免重試風暴。
- 為子程序設
timeout（如 120～300s），防止長時間佔滿閘道 worker。 - 日誌落盤並輪替，方便與 CircleCI 重送請求對照同一
id。
建置摘要回傳（HTTP／Webhook）與失敗重試
掃描完成後，以 curl 對企業狀態 API、Slack／Discord Incoming Webhook（可對照站內 Discord 摘要文）或第二個自動化端點送出 JSON：建議含 pipeline_number、workflow、status、lockfile_drift（布林或檔名列表）、summary（截斷約 2KB）、circle_event_id（去重）。務必設定 --connect-timeout 與 --max-time；非 2xx 時採 2／4／8 秒指數退避，最多三至五輪。
# 摘要回傳示例（替換 URL、TOKEN、欄位）
STATUS=success
EVENT_ID="wf-123"
SUMMARY="$(tail -n 40 /tmp/lockfile-scan.log | sed 's/"/\\"/g')"
curl -sS -X POST "$CALLBACK_URL" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $CALLBACK_TOKEN" \
--data "{\"status\":\"$STATUS\",\"circle_event_id\":\"$EVENT_ID\",\"summary\":\"$SUMMARY\"}" \
--connect-timeout 5 --max-time 25 \
--retry 3 --retry-delay 2 --retry-all-errors
常見報錯（簽章／逾時／權限）排查 FAQ
circleci-signature 驗簽總是失敗？
確認使用建立 Webhook 時的 Signing secret；HMAC 輸入為原始 body 字串而非美化 JSON；從標頭解析 v1= 後與本地計算的 hex 做常數時間比對；注意祕鑰尾端無多餘換行。
CircleCI 控制台顯示傳遞失敗或反覆重試？
多數為未在短逾時內回 2xx。將驗簽與 ACK 壓在數百毫秒內完成，lockfile 掃描改非同步；或縮小 clone 深度、略過不必要事件。亦檢查 TLS 鏈與防火牆是否擋住 CircleCI 出口。
權限不足或無法新增 Webhook？
確認帳號具組織管理員；專案未超過五個 Webhook 上限。若僅能讀倉庫而不能寫外部狀態，請改以唯讀 clone＋出站只讀 API 令牌。
npm／git 在 launchd 下找不到？
在 plist 寫死 PATH；勿只依賴登入 shell 的 nvm；以 which git、openclaw doctor 驗證；跨境時設好 GIT_HTTP_LOW_SPEED_LIMIT 等逾時環境變數。
與 CI 拉取場景的銜接
lockfile 掃描通過後，實際建置仍受Git／registry 拉取影響。請在 CircleCI 與遠端 Mac 上對齊同一組鏡像與快取路徑（例如 NPM_CONFIG_REGISTRY、GOPROXY、Composer 鏡像），並參考站內 跨境 Git／npm／brew 鏡像與 CI 優化 調整逾時與退避。閘道節點若與 Runner 地理一致，可顯著降低「掃描無漂移、但建置拉包失敗」的假陰性。
延續常見做法：早期 job 先暖快取，Webhook 觸發的 OpenClaw 僅做輕量檢查；重拉與編譯留在 CircleCI 或 Mac Runner，避免閘道成為瓶頸。版本凍結與預拉參數見站內同系列專文。