2026 OpenClaw 實戰：Discord Webhook 與 CI 建置摘要

先把執行環境對齊，再談 Webhook；否則「設定寫了但沒進程」會浪費大量排錯時間。

• Node 版本：以 OpenClaw 當前文件為準，2026 主線多要求 Node 22.16+，團隊可統一 24 LTS；執行 node -v，並確認 launchd、互動 SSH 與 CI job 使用同一 PATH。
• 安裝入口擇一：官方 curl … | bash 類 install 與 npm i -g openclaw 不要混裝兩套全域 CLI；裝完後 which openclaw 應指向預期前綴。
• 向導與自檢：openclaw onboard 完成初始目錄與守護程序（若文件支援 --install-daemon 可一併註冊）；openclaw doctor 檢查設定搜尋路徑、埠與相依版本。
• 閘道綁定：生產預設讓 HTTP 服務聽 127.0.0.1，由 Nginx／Caddy 終止 TLS 後轉發；對外管理 API 使用 Authorization: Bearer <GATEWAY_TOKEN>（實際標頭名以文件為準），與 Discord Webhook URL 分開存放。
• 最小權限：Discord 端僅建立「單一頻道、僅發訊」的 Webhook；OpenClaw 進程帳號僅需讀寫設定目錄與寫日誌，祕鑰不放進 Git。

# 閘道健康（埠、標頭、TOKEN 請替換）
curl -sS -o /dev/null -w '%{http_code}\n' \
  -H 'Authorization: Bearer YOUR_GATEWAY_TOKEN' \
  --max-time 10 http://127.0.0.1:PORT/health

Discord 的 Incoming Webhook 沒有 OAuth scope 細分：完整 URL 即能力邊界，外洩等同可對該頻道發文。請用伺服器設定中的「整合／Webhooks」建立，並限制知悉範圍。

# 最小校驗（將 WEBHOOK_URL 換成完整 https://discord.com/api/webhooks/...）
curl -sS -X POST "$DISCORD_WEBHOOK_URL" \
  -H 'Content-Type: application/json' \
  --data '{"content":"OpenClaw／CI webhook smoke test ✅"}' \
  -w '\nHTTP %{http_code}\n' --max-time 15

收不到訊息時：先確認回應碼與回應本文；再檢查頻道權限、是否為論壇頻道需指定 thread、以及公司代理是否攔截 discord.com。閘道轉發情境下再加查 OpenClaw 日誌與出站 DNS。

純文字 content 最簡，但長日誌易超長度；實務上多用 embeds 把分支、提交、狀態、耗時、連結分欄，方便手機閱讀。

# 以 jq 組裝 embed（避免手拼 JSON 轉義錯誤；變數依 CI 平台替換）
TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
COLOR=3066993; test "${CI_JOB_STATUS:-success}" = "failed" && COLOR=15158332
PAYLOAD="$(jq -n \
  --arg title "Build ${CI_PROJECT_NAME:-app}" \
  --arg desc "分支 ${CI_COMMIT_REF_NAME:-main} · ${CI_COMMIT_SHORT_SHA:-unknown}" \
  --arg job "${CI_JOB_NAME:-build}" \
  --arg dur "${CI_JOB_DURATION:-n/a}" \
  --argjson color "$COLOR" \
  --arg ts "$TS" \
  '{username:"CI Bot", embeds:[{title:$title, description:$desc, color:$color, timestamp:$ts, fields:[{name:"Job",value:$job,inline:true},{name:"耗時",value:$dur,inline:true}]}]}')"
curl -sS -X POST "$DISCORD_WEBHOOK_URL" -H 'Content-Type: application/json' -d "$PAYLOAD" --max-time 20

實作上建議用 jq -n 依變數組裝物件，並對 description 做長度截斷（例如 1800 字內），避免觸發 Discord 本文上限。若需經 OpenClaw 聚合多 job，可在閘道側合併為單則 embed 再送出，降低 429 風險。

Discord Incoming Webhook 沒有類似 Slack 的簽章標頭可驗證來源；安全邊界是URL 保密＋網路 ACL。若經由自有閘道轉發，可在閘道入口驗證 Authorization 或 HMAC，再向 Discord 出站。

• 限流：同一 Webhook 在尖峰併發時易遇 429；回應可能帶 retry_after 或 Retry-After 標頭，腳本應睡眠後再試，並避免十幾個 job 同秒推送。
• curl 重試：curl --retry 3 --retry-delay 2 --retry-all-errors 搭配 --max-time 20；自訂迴圈可用 2／4／8 秒指數退避，最多 3～5 次。
• 冪等：對同一 pipeline 使用固定 dedup_key 寫入狀態檔，避免「重跑 step」重複刷頻道；失敗時將 body 落盤到 artifact 供人工轉貼。

• 403 Forbidden：Webhook 已刪、URL 複製不全、或環境變數被截斷；重新建立 Webhook 並全量更新祕鑰。若走代理，確認未把 POST 改寫到錯誤 upstream。
• 429 Too Many Requests：減少並行通知、合併 embed、讀取退避時間後重試；矩陣 build 可只向主 job 回報一次摘要。
• 逾時／連線重設：調高 --max-time 與 DNS 快取穩定性；檢查遠端 Mac 與 Runner 的出口防火牆；勿在關鍵 path 上無限阻塞，應 fail-open 到 artifact。
• 400／invalid form body：JSON 未轉義、embed 超長、或 Content-Type 非 application/json；用 jq 產生 payload 並在本地 curl 復現。

與 OpenClaw 安裝循環、埠占用相關的問題見安裝排錯指南。