2026 年 OpenClaw Gateway 內建健康探針（/health、/ready）與負載均衡：遠端實體 Mac 裸機、Docker Compose 與 Kubernetes 的對齊驗收、路徑 Shadowing 與誤報未就緒的可複現 Runbook（設定片段 + FAQ）

2. 三類痛點：語意漂移、路徑遮蔽、網路命名空間錯位

1. 語意漂移：團隊把重量級依賴檢查塞進 /health，導致探針逾時或被誤判為需要重啟；或把「可接受降級」塞進 /ready，造成滾動更新時全隊列流量被摘除。應固定：/health＝行程存活；/ready＝願意接客。
2. 路徑遮蔽（shadowing）：API 閘道或 Web 框架的萬用字元路由先於內建探針匹配，LB 收到 404／HTML 錯誤頁卻仍以為後端活著（若只檢查 TCP）或相反。需在 Nginx、Caddy、Traefik 或 Ingress 註明 精確 path 優先。
3. 網路命名空間錯位：容器內 curl 127.0.0.1 成功，但 kubelet 從 Pod IP 探測失敗；或閘道只綁回環而 Service 轉發不到。對照 bind=lan／0.0.0.0 與 targetPort 是否一致。

3. 決策矩陣：裸機、Compose、K8s 探針與 LB 對齊

下表用於變更單與事故復盤：每一列都應能在三軌找到對應設定或等價行為。

4. 七步落地驗收與可貼上設定片段

步驟 1：凍結契約

在 README 或內部 wiki 寫明：GET /health 回 200 且 body 可選；GET /ready 在依賴未就緒時回 503（或團隊選定的非 200），並禁止在這兩個 path 上掛認證中介層。

步驟 2：本機冒煙（三軌共用）

curl -fsS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:18789/health
curl -fsS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:18789/ready

將埠號替換為實際閘道埠；若使用 TLS 終止於上游，加上 -k 或正確 CA 僅限於排錯環境。

步驟 3：Docker Compose healthcheck

services:
  openclaw-gateway:
    image: your-registry/openclaw-gateway:@sha256:...
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:18789/ready || exit 1"]
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 40s

start_period 應覆蓋模型索引或遠端憑證載入的最壞情況，避免啟動期誤判。

步驟 4：Kubernetes 探針

startupProbe:
  httpGet:
    path: /ready
    port: http
  failureThreshold: 30
  periodSeconds: 2
readinessProbe:
  httpGet:
    path: /ready
    port: http
  periodSeconds: 5
  timeoutSeconds: 2
  failureThreshold: 3
livenessProbe:
  httpGet:
    path: /health
    port: http
  periodSeconds: 10
  timeoutSeconds: 2
  failureThreshold: 3

若曾發生「就緒後才暴露埠」的競態，優先加長 startupProbe 而非放寬 readinessProbe，以免長期掩蓋性能退化。

步驟 5：Ingress 路徑優先（防 shadowing）

以 NGINX Ingress 為例，確保 /health 與 /ready 使用精確匹配並排在萬用 path 之前；若使用正則路由，請把探針 path 放在更高 priority。

步驟 6：誤報未就緒分診

若 kubelet 成功而 LB 失敗：比對 Host 標頭、TLS 終止與 重定向鏈；若兩者皆失敗但本機成功：檢查是否只綁 127.0.0.1。可暫時以 TCP Socket 探測隔離 HTTP 層，定位後再切回 HTTP。

步驟 7：簽字歸檔

匯出滾動更新視窗內的 探針成功率、5xx 比例與 P95 啟動時間；附上代理與閘道設定雜湊，並註明回滾觸發條件（例如連續 N 次 /ready 非 200）。

5. 可引用閾值與參數

• readinessProbe.failureThreshold 預設為 3：在 periodSeconds: 5 時約 15 秒內連續失敗才會從 Service 摘除，適合作為變更風險溝通數字。
• 雲負載均衡健康檢查間隔常見設定為 5–30 秒：過密會放大閘道日誌與 CPU；過疏會拉長故障檢知時間。
• Compose start_period建議先取閘道冷啟動 P95×1.5，再在新版本發佈後用實測收窄，避免與 K8s startupProbe 預算脫節。

6. FAQ