OpenClaw Gateway 出問題時，最常見其實不是「平台壞掉」，而是連接埠衝突、環境變數漏設、反向代理誤配。這篇用可重現流程，把你在值班時最常遇到的 90% 異常一次拆解，搭配官方文件 docs.openclaw.ai 做交叉驗證。
若你正要把服務正式上線，先看部署入口 ../yuancheng-mac-openclaw-shicao-meidong-meixi/yuancheng-mac-openclaw-shicao-meidong-meixi.html，再把 OpenHuman 與 Runner 的角色拆乾淨（../openhuman-memory-tree-yunduan-mac-openclaw/openhuman-memory-tree-yunduan-mac-openclaw.html、../github-actions-ios-ci-mac-man-self-hosted-runner-jia-su-dian/github-actions-ios-ci-mac-man-self-hosted-runner-jia-su-dian.html），可顯著降低互相搶資源造成的閘道抖動。
1. 先分型：你遇到的是哪一類閘道異常？
先把現象歸類，才能快速縮小排查範圍。以下矩陣可當值班 SOP 的第一步。
| 症狀 | 常見根因 | 第一個動作 |
|---|---|---|
| 啟動後立刻退出 | 連接埠已被佔用、設定檔語法錯誤 | 先跑 doctor，再查 listen socket |
| 本機可通、外部不可達 | 防火牆或安全群組未放行 | 對照實際綁定位址與開放連接埠 |
| 偶發 502 / timeout | 上游延遲、健康檢查過於嚴苛 | 拉健康探針與上游日誌時間線 |
| TLS 握手失敗 | 憑證鏈不完整、SNI 主機名不符 | 先做 openssl 連線驗證 |
2. 五分鐘快篩：先跑 doctor 再看程序狀態
OpenClaw 官方建議先跑診斷工具，再對照服務狀態與設定值。文件入口：Gateway Troubleshooting 與 Gateway Doctor。
openclaw gateway doctor --verbose # Look for: config path, bind address, upstream checks, TLS warnings
ps aux | rg "openclaw|gateway" lsof -nP -iTCP -sTCP:LISTEN | rg ":(3000|8080|8443)" netstat -an | rg "LISTEN|3000|8080|8443"
| doctor 訊號 | 意義 | 建議處置 |
|---|---|---|
| config file not found | 部署路徑或掛載錯誤 | 修正設定檔路徑，再重啟 |
| bind failed | 連接埠衝突或權限不足 | 改連接埠或釋放占用程序 |
| upstream unhealthy | 後端服務未就緒 | 先修上游，再調整重試策略 |
| tls chain invalid | 憑證鏈不完整 | 補中繼憑證並驗證 fullchain |
3. 連接埠衝突：最常見、也最容易忽略
同一台機器同時跑 Gateway、Runner 與其他代理時，最常見就是預設連接埠重疊。尤其是臨時手動啟動過一次服務後，舊程序沒清乾淨。
PORT=8080 lsof -nP -iTCP:$PORT -sTCP:LISTEN sudo kill -15 <PID> sleep 2 lsof -nP -iTCP:$PORT -sTCP:LISTEN || echo "port released"
| 角色 | 建議連接埠 | 備註 |
|---|---|---|
| OpenClaw Gateway | 8080 或 8443 | 正式環境建議固定，不要頻繁改 |
| 內部管理介面 | 3000 | 僅綁定 localhost |
| Runner callback | 9090+ | 避免與 Gateway 重疊 |
| 本地開發服務 | 5173 / 3001 | 避免借用正式連接埠 |
如果你要跨區部署，建議把香港節點的網路策略與延遲基準獨立管理（../japan-vs-hong-kong-yuancheng-mac-ci/japan-vs-hong-kong-yuancheng-mac-ci.html），不要直接複製美區防火牆規則。
4. Doctor 深入判讀：哪些 warning 一定要修？
doctor 不是只看 pass/fail。很多 warning 雖然不會立刻炸，但會在流量上升時變成事故。以下是實戰中最值得優先修復的欄位。
| 診斷項目 | 可忽略？ | 建議 |
|---|---|---|
| Clock skew > 3s | 否 | 先校時，避免 token 驗證間歇失敗 |
| DNS fallback | 否 | 固定 resolver，降低偶發解析超時 |
| Retry budget low | 否 | 調整上游 timeout 與重試上限 |
| Deprecated key | 視情況 | 排進近期變更窗口，不要拖版本 |
mkdir -p ./diag
openclaw gateway doctor --format json > ./diag/doctor-$(date +%F-%H%M).json
jq '.checks[] | {name,status,message}' ./diag/doctor-*.json
5. 日誌與健康檢查：把「偶發」變成可量化
不要只看單點錯誤，請拉 15 分鐘窗口做對時分析。把 Gateway access log、error log、upstream log 對齊，才能知道誰先出問題。
| 觀測指標 | 告警門檻 | 處置方向 |
|---|---|---|
| p95 upstream latency | > 1.5s | 先檢查上游容量與連線池 |
| 5xx ratio | > 1% | 按 status code 分流根因 |
| healthcheck flaps | > 3 次/10 分鐘 | 放寬探針 timeout 或降低頻率 |
| TLS handshake errors | 持續上升 | 檢查 SNI、憑證鏈、到期日 |
6. 網路與 TLS：避免「內網正常、外網失敗」
許多團隊在內網測試都成功，上線後卻失敗，關鍵在於對外路徑多了 WAF、LB、CDN 或額外 TLS 終止層。請逐層驗證，不要一次改三個元件。
curl -Iv https://gateway.example.com/health openssl s_client -connect gateway.example.com:443 -servername gateway.example.com dig +short gateway.example.com traceroute gateway.example.com
更多網路檢查可參考 OpenClaw Gateway Networking。
7. 部署模式：單機、分離、跨區該怎麼選
在資源有限的情況下，先決定部署拓樸。拓樸錯誤，後續優化幾乎都只是補洞。
| 模式 | 適用情境 | 風險 |
|---|---|---|
| 單機整合 | PoC、低流量 | 連接埠/記憶體互搶最明顯 |
| Gateway 與 Runner 分離 | 中流量、CI 頻繁 | 需要額外監控與網路規劃 |
| 跨區雙閘道 | 多地使用者、低延遲要求 | 設定一致性與權杖同步更複雜 |
| Gateway + OpenHuman 分離 | Agent 與記憶工作負載並行 | 初期成本增加，但穩定性高 |
若你在估算成本，可用 ../../../mac-mini-jiage.html 先做月費與風險預算，避免故障後才臨時擴容。
結論：先把可預防的 90% 問題標準化
OpenClaw Gateway 的排障關鍵不是「更會猜」，而是把快篩、連接埠管理、doctor 判讀、日誌對時與網路驗證做成固定流程。只要流程一致，90% 的故障都能在第一輪定位並修復。
建議把本文流程寫進你的值班手冊，並對照官方文件 Gateway Configuration 做版本化維護。
Q1：doctor 全部綠燈，為何還是 timeout？
doctor 主要驗設定與基本連線；尖峰時的上游容量問題仍可能造成 timeout，請加看 latency 與連線池。
Q2：可以把 Gateway 與 Runner 放同一台嗎？
可以，但要固定連接埠映射、限制資源上限，並避免高峰期同時跑大規模 CI 任務。
Q3：連接埠改掉就一定比較安全嗎？
不一定。安全重點是 ACL、TLS、憑證與最小權限，不是只換成冷門連接埠。
Q4：為什麼重啟後偶爾恢復、過一陣子又壞？
通常是根因未解（例如 DNS 或衝突程序），重啟只是短暫清空狀態。
Q5：香港與台灣節點要共用同一組設定嗎？
建議共用 baseline，但保留區域化覆寫（DNS、防火牆、上游端點）以降低跨區風險。
Q6：TLS 錯誤最先要看哪裡？
先看憑證到期與 fullchain，再看 SNI 主機名是否一致。
Q7：何時該做藍綠部署？
當你需要零停機升級、且流量已高到不能接受重啟窗口時，就應導入藍綠切換。
Q8：排障資料要留多久？
至少保留 14~30 天，才能比對版本升級前後與週期性故障模式。
正式上線前，先完成部署路徑 ../yuancheng-mac-openclaw-shicao-meidong-meixi/yuancheng-mac-openclaw-shicao-meidong-meixi.html，並把 OpenHuman 與 Runner 的負載角色拆分（../openhuman-memory-tree-yunduan-mac-openclaw/openhuman-memory-tree-yunduan-mac-openclaw.html、../github-actions-ios-ci-mac-man-self-hosted-runner-jia-su-dian/github-actions-ios-ci-mac-man-self-hosted-runner-jia-su-dian.html）。跨區團隊可另外評估香港方案 ../japan-vs-hong-kong-yuancheng-mac-ci/japan-vs-hong-kong-yuancheng-mac-ci.html 與整體費率 ../../../mac-mini-jiage.html，讓穩定性與成本同時可控。