2026-05-06 OpenClaw 雙閘道：連接埠、OPENCLAW_STATE_DIR 與 nginx 上游灰度（租用 Apple Silicon 雲端 Mac，香港／東京／首爾／新加坡／美國）
不少團隊希望在同一台租用的 Mac mini M4上並行兩套 OpenClaw 閘道：一套正式、一套灰度模型白名單，或 staging 與正式 Webhook 簽章輪替節奏不同。若做錯——連接埠重複、共用 ~/.openclaw、nginx 權重在請求中途跳動——會出現看似「模型掛了」的502 風暴，實則全是管線問題。本 2026-05-06 指南依序說明互不衝突的回環連接埠、彼此獨立的 OPENCLAW_STATE_DIR 目錄樹、帶 slow_start 的 nginx upstream，以及健康探測，讓你在香港、東京、首爾、新加坡、美國機房 drain 流量而不靠 SSH 臨場發揮。銜接 nginx 反向代理與 Webhook 入口、健康探測與就緒、launchd 環境變數優先順序，並在多倉讀盤情境配合 檔案工具與分塊紀律，避免兩套助理踩同一工作副本。
什麼時候值得為複雜度買單
預算允許時優先第二台 Mac作旁路——見 定價 評估 witness 節點。若財務堅持單機，雙閘道仍有價值：
- 模型白名單在受監管流量與試驗流量之間必須硬隔離。
- Webhook 簽章金鑰在 staging 與 prod 輪替週期不同。
- 無法做 CPU pinning，但仍希望灰度與正式工作階段的爆炸半徑分開。
拓撲：並排 active/active 與主備
並排 active/active 適合你能隨機化客戶端或完全掌控 nginx 權重的情境；主備適合需要確定性除錯、同一時間只有一套閘道對共用 git 鏡像做重度寫入的團隊。把選擇與 launchctl 標籤寫進同一份 README，避免交接時口頭傳說。
| 模式 | 優點 | 代價 |
|---|---|---|
| Active / active | 吞吐高；可在真實並發下 soak | 需要冪等 Webhook 與去重副作用 |
| Primary / standby | 日誌較簡單；回滾路徑短 | 備機閒置 CPU，除非跑合成探測 |
連接埠、綁定位址與 launchd 標籤
不要只靠一次 lsof「猜連接埠」——寫進 plist 與 nginx。範例（依你的語意化版本調整）：
export OPENCLAW_GATEWAY_PORT_PRIMARY=18789
export OPENCLAW_GATEWAY_PORT_CANARY=18890
兩套都綁定 127.0.0.1，公網 0.0.0.0:443 交給 nginx。若灰度綁 ::1 而 upstream 只寫 IPv4，會出現「幽靈連線重設」——位址族策略請對齊 出站 DNS/TLS 韌性 一文。
狀態目錄：為何禁止共用 ~/.openclaw
每套閘道需要獨立 OPENCLAW_STATE_DIR（例如 /var/lib/openclaw-prod 與 /var/lib/openclaw-canary）。共享主目錄會在其中一套輪替 API key 時污染工作階段與快取。若 launchd 用同一 UID 跑兩套作業，也必須目錄隔離——不要共享 sqlite 或工作階段根。
rsync + launchctl kickstart，而不是重裝故事。
nginx upstream：權重、slow_start、max_fails
從 反向代理指南 複製已驗證的 server 區塊，再複製 upstream：
upstream openclaw_primary { server 127.0.0.1:18789 max_fails=3 fail_timeout=20s; }
upstream openclaw_canary { server 127.0.0.1:18890 max_fails=1 fail_timeout=10s slow_start=30s; }
使用 split_clients 或與風險偏好一致的加權 proxy_pass。proxy_read_timeout 仍要對齊你允許的最長模型往返——拆閘道不會縮短 LLM 延遲。reload 時記得 worker_connections 與 keepalive 池是 per-worker：upstream 翻倍卻不抬上限，會在 Webhook 突發重播時頂滿吞吐。能採集 stub_status 就採；否則從 access log 拆上游回應時間——若 reload 後 p95 立刻跳 35%+，多半是 worker 餓死而非 OpenClaw 配錯。TLS 重負載時讓 staging 與 prod 的 cipher 套件一致，避免灰度鏈 accidentally 走更慢路徑。務必把可回滾的 nginx tarball與 OpenClaw 狀態快照放一起；很多人只快照 Node 樹不快照 nginx，兩行 map $http_x_forwarded_proto 筆誤會讓兩套閘道一起 parser fail closed。
健康探測：切流量前先證明兩套都綠
把 就緒探測 裡的 curl 矩陣分別打到兩個本機連接埠，reload 後再打經 nginx 的路徑。HTTP 狀態、上游連線耗時、TLS 握手耗時分開記日誌，才能區分 nginx 迴歸與 OpenClaw 迴歸。
八步割接清單
- 快照 plist、nginx 與兩棵狀態目錄。
- 安裝第二套閘道，二進位或 npm pin 與正式完全一致。
- 分別在每棵樹跑
openclaw doctor獨立驗證。 - nginx 先把灰度權重設為 0（就緒前黑洞）。
- 用 staging 合成 Webhook 重播冒煙。
- 把灰度切片調到 5–12%。
- 觀察 48h錯誤預算。
- 依文件化權重晉升或回滾。
逾時、Webhook 重試與重複投遞
雙閘道放大重複投遞風險：若上游在 TCP 閒置視窗內 aggressive 重試，業務必須辨識冪等鍵，並把去重標記落在正確的狀態目錄下。proxy_read_timeout 要與供應商 idle 限制對齊——重試表見 Webhook 投遞與簽章。
| SLO 訊號 | 閾值 | 動作 |
|---|---|---|
| 本機上游連線 p95 | > 120 ms（至 localhost） | 暫停調權；查 launchd 限流 |
| 5xx 占比 | > 0.5%（15 分鐘視窗） | 灰度權重歸零 |
| 佇列積壓 | > 200 待處理作業 | 加第二台 Mac 或降並發，不要疊第三套閘道 |
SLO：何謂「健康的雙閘道」
把雙閘道當成迷你服務網格：每一跳單獨度量。若正式綠、灰度紅，先修灰度設定，而不是盲調 nginx。對內面板建議每套閘道四條線：程序 RSS、CPU%、nginx 日誌裡的在途 HTTP 數、失敗上游連線數。同權重下若灰度 RSS 比正式偏離 18%+，多半是外掛記憶體外洩或 Node semver 不一致——暫停 rollout，對比兩套 OPENCLAW_STATE_DIR 下 npm ls --depth=0。跳過這步的團隊常把週末燒在「模型品質回退」上，實際是同一 skill bundle 在灰度被載入了兩次。每季演練整 nginx 掛掉：故意 stop nginx，確認 launchd 仍保活兩套回環閘道，並確認告警能叫到對的人——目標是雙閘道提高可用性，而不是讓 pager 翻倍。
常見問題：TLS、DNS 與金鑰
| 問題 | 實務答案（2026-05-06） |
|---|---|
| 兩套閘道要兩套 TLS 憑證嗎？ | 通常不需要——在 nginx 終止一次 TLS；閘道只走回環。 |
| API key 能共用嗎？ | 不建議——獨立輪替以縮小爆炸半徑；模式見 閘道升級與回滾。 |
為何裸金屬 Mac mini M4 仍能簡化雙閘道混亂
雙閘道同時壓測 CPU、磁碟 與 launchd 台帳。MacXCode 節點上帶 1–2 TB NVMe 的租用 Mac mini M4 讓 nginx→OpenClaw 回環延遲可預期，統一記憶體也足以並行兩套 Node 圖而不搶 nightly xcodebuild 鄰居車道的核心。可預期性才是權重灰度「可度量」的前提。向維運解釋為何需要專用第二節點而非在忙主機上疊第三套閘道時，用 區域定價；需要在新 TLS 信任錨上走 VNC 證據鏈時，用 說明文件 與 VNC 說明。
