1. 痛點拆解：容器「能 curl」不代表 CLI 走對了網絡卡
（1）WS 迴環誤配：CLI 預設指向 ws://127.0.0.1:18789 在宿主機成立，但在另一容器或 CI job 裡會指向自己；Gateway 實際監聽在 openclaw-gateway 服務名上時，仍寫 127.0.0.1 等於永遠自環。（2）配對與 Token 兩條線混談：pairing required 是會話未授權；unauthorized / token mismatch 是金鑰不一致；混在一起改只會越改越亂。（3）環境變數覆蓋配置檔案：Compose 裡一行 OPENCLAW_GATEWAY_TOKEN 可能與掛載卷裡的 gateway.auth.token 衝突，表現為「改檔案不生效」。（4）遠端 Mac 雙棧邊界：launchd 起的程序與 compose 起的容器若共享同一埠宣告，或同一資料目錄被兩例項讀寫，會出現間歇性「看似線上卻不回」。
2. 症狀—根因矩陣（先分層再改配置）
| 現象 / 日誌關鍵詞 | 優先假設 | 第一動作 |
|---|---|---|
1006 / 連線被重置 |
WS URL 指錯主機或埠被佔用 | 在發起 CLI 的同一網路名稱空間裡 nc -vz 目標主機:埠 |
1008 pairing required |
未完成控制面配對 | 開啟 Gateway 控制面生成配對碼；CLI 執行配對命令 |
token mismatch / unauthorized |
環境變數與配置檔案不一致 | docker compose exec 列印相關 env；與卷內 JSON 對齊 |
| 偶發成功、多數失敗 | 雙例項爭用資料目錄或 token 輪換競態 | docker ps + 卷掛載表；先縮為單例項 |
3. 落地五步走：把「能 ping 通」推進到「能完成一次 probe」
- 凍結網路名稱空間：明確 CLI 從宿主機、sidecar 容器還是 CI runner 發起；把「誰連誰」畫成一條箭頭。
- 顯式 WS Base：在對應環境寫入
OPENCLAW_GATEWAY_URL（或專案文件規定的等價項），指向openclaw-gateway:18789或釋出到宿主機的埠對映，而不是預設死寫 127.0.0.1。 - 配對門禁：先完成 pairing，再測業務頻道；把「未配對」與「Token 錯」分兩頁臺賬記錄。
- Token 單一真源：選擇「只信環境變數」或「只信配置檔案」之一作為團隊規範；另一項必須與之相等或刪除。
- 驗收用
channels probe：在相同環境下跑通一次 probe，把日誌片段與 compose 片段一併歸檔到工單。
4. Compose 對齊：何時考慮 network_mode: "service:openclaw-gateway"
當 CLI 與 Gateway 必須共享同一網路棧（例如避免預設橋接下服務名解析不一致）時，可將 CLI 容器掛到 Gateway 所在 network namespace。代價是埠與 localhost 語義更繞，必須在 README 畫拓撲。另一種更常見做法是：CLI 仍在宿主機，僅 Gateway 在容器，此時應把 WS URL 指到對映後的宿主機埠，並在防火牆與反向代理層對齊 TLS 終止點。
5. 可引用閾值（評審向）：寫進值班 Runbook 的三個數字
下列為討論用量級，須用你的映象與拓撲復測後替換：
- 若從 CLI 名稱空間到 Gateway 埠的TCP 建連成功率低於 97%（100 次取樣），先停功能排查，優先處理DNS/服務名/對映埠，不要先改模型路由。
- 若在單次配對視窗期內連續出現 3 次以上
token mismatch，應預設存在雙真源（env 與檔案），必須收斂為單一來源後再試。 - 當遠端 Mac 上 Gateway 與宿主機 CLI 併發寫同一狀態目錄導致鎖等待超過 2.5s 出現在 p95 日誌中，應拆分資料卷或把 CLI 遷入專用 sidecar。
6. openclaw logs 分層讀法：從 transport 到 channel
先過濾 transport / websocket 相關行，再過濾 auth / pairing，再進入具體 channel。把三層截圖附在工單裡，比口頭「我這邊不行」更快收斂。與站內《官方 install.sh》連讀時，可把「安裝順序」與「網路對齊」分成兩次驗收，而不是混在一次會議裡口頭透過。
| 層次 | 你要回答的問題 | 透過標準（示例） |
|---|---|---|
| L1 傳輸 | WS 是否握手成功 | 無 1006/1008 或已解釋的預期關閉碼 |
| L2 鑑權 | Token / pairing 是否一致 | 配對完成後無 unauthorized 迴圈 |
| L3 業務頻道 | 渠道是否線上 | channels probe 對目標渠道返回可解釋狀態 |
7. 遠端 Mac：launchd 與 Docker 的埠與目錄邊界
在遠端 Mac 常駐時，常見組合是「Gateway 容器 + 宿主機 launchd 健康檢查指令碼」。必須寫清：誰持有 18789、狀態目錄是 bind mount 還是命名卷、升級時先停誰。與《SSH / VNC 遠端 Mac》連讀時，把「遠端桌面人機操作」與「無人值守 compose」分開排班，避免運維在 VNC 會話裡手改檔案而 CI 同時滾動升級。
8. FAQ
問：能不能只靠改 extra_hosts 解決？有時可以，但若根因是 token 雙真源，改 hosts 只會把失敗變成另一種間歇失敗。
問：要不要把 Gateway 綁到 0.0.0.0？先讀《Gateway 暴露面》做最小暴露；公網直連不是預設答案。
問：和 install.sh 路徑衝突嗎？不衝突但易混：install.sh 偏「從零到 probe」順序；本文偏「已在 Docker 裡」網路與鑑權對齊；兩者應對照閱讀。
9. 深度案例：「能 docker logs 看到 Gateway 已 listen」但仍 1008
2026 年社群反饋裡，一類高頻問題是：Gateway 在容器 A 正常 listen，但使用者在容器 B 裡跑 CLI，仍寫 ws://127.0.0.1。這類問題在紙面上「顯然」，但在多倉庫、多 compose 疊加時極難靠口頭傳承。工程上應把「發起 openclaw 的網路名稱空間」寫進 README 的第一行，並在 CI 裡用同一映象跑一條 smoke：從 runner 容器 exec 一次 probe。
第二類問題是 OPENCLAW_GATEWAY_TOKEN 在 override 檔案中被重複定義：本地開發者為了「臨時試一把」加了一行 env，隨後忘記刪除，導致配置檔案裡的 token 永遠不被讀取。治理策略是：env 與檔案二選一，並在 PR 模板裡檢查 diff 是否出現 token 相關 env。
第三類問題發生在遠端 Mac：Time Machine 或同步盤把狀態目錄同步到第二臺機器，兩臺機器各起一個 Gateway，表現為「頻道偶發雙應答」或「token 被輪換」。應明確狀態目錄不參與跨機同步，或改用集中式遠端節點。
與《遷移與重配對》連讀時，可把「換機」與「Docker 重建」分成兩次演練：前者關心 workspace 與金鑰備份；後者關心 compose 版本與卷 schema。混談會導致回滾路徑不清。
最後，Docker 不是「更省事」，而是更強約束下的可重複交付。當你能在工單裡同時附上 compose 片段、env 列印、nc 結果與三層日誌截圖，團隊才真正具備討論「要不要上遠端 Mac 專用節點」的資格。
10. 與 n8n / Webhook 整合時的額外注意
若你把 OpenClaw 與 n8n 串聯，Webhook 入口往往在另一個容器或宿主機埠。此時「誰發起回呼」與「誰持有 Gateway token」必須一致；參閱站內 n8n Runbook 的分層退避段落，把 HTTP 與 WS 的故障分開記錄，而不是把 502 與 1008 混在同一工單標題裡。
11. 升級與回滾：先縮單例項再談 feature
當上遊釋出帶鑑權或 Gateway 協議變更的版本時，優先把環境縮成單 Gateway 單 CLI驗證，再恢復多例項。雙例項並行升級最容易製造「一半容器讀新 schema、一半讀舊卷」的半一致狀態；與《OpenClaw 升級 breaking》類文章連讀時，把 doctor 輸出附在變更單上。
12. 收束：Docker 負責可重複，遠端 Mac 負責可承諾
（1）當前方案的客觀限制：Docker 拓撲把問題收斂為網路與卷，但團隊若不在 README 固定「發起 CLI 的名稱空間」，排障成本會指數上升；token 雙真源會讓「改配置」變成玄學。
（2）為什麼遠端 Mac 節點常常更省心：專用節點可把 Gateway、卷與 launchd 健康檢查固化成映象與 compose 版本對；與本機開發環境解耦，減少「我這邊能連」式差異。
（3）與 MACGPU 場景的銜接：若你希望低門檻試用已對齊 compose 與埠的遠端 Mac 作為 7×24 Gateway 承載，而不是讓同事的筆記本當臨時伺服器，MACGPU 提供可租賃節點與幫助入口；下文 CTA 直達首頁套餐與幫助（無需登入）。
（4）最後一道自檢：對外宣稱「已上線 OpenClaw」前，必須附上 channels probe 成功片段與 compose/env/token 對齊證明。
13. 實戰補充：與 install.sh 與三棧對照的銜接
若你尚未跑通官方 install.sh 順序，請先讀對應文章建立基線；若已跑通但仍卡在 Docker，請回到本文矩陣從 L1 傳輸層重走。三棧對照文幫助你選擇「CLI 放宿主機還是放容器」，避免為了追新而把 CLI 隨意塞進 sidecar。