2026 在 Mac VPS 上用 Docker 跑通 OpenClaw：Gateway Token、CLI 容器網絡與「配對死鎖」排障 Runbook
Compose 搬到 7×24 Mac VPS 後常見 token mismatch、1008 pairing、CLI 127.0.0.1:18789 拒絕連接。本文面向分容器託管網關與 CLI 的讀者：五條根因、症狀對照表、五步 Runbook（Token 凍結、雙源對齊、網絡縫合、配對出口、healthz+launchd），並鏈 Compose 7×24 與 網關 ladder。
本文要點
1. 痛點拆解：雙源 Token、127 迴路、配對死鎖與卷權限
上遊 Docker 文檔與 docker-setup.sh 默認假設「人與腳本在同一網絡命名空間內點下一步」，Mac VPS 上無人值守時最常見的五類斷裂如下：
- 環境變量靜默覆蓋配置文件：容器內若存在
OPENCLAW_GATEWAY_TOKEN，其優先級可能覆蓋openclaw.json中gateway.auth.token，表現為 UI 粘貼「看起來對」的 token 仍報 mismatch。 - CLI 與網關分容器時的 127.0.0.1 誤連：
openclaw-cli默認嘗試ws://127.0.0.1:18789，但該地址指向CLI 容器自身的迴環，而非網關容器；日誌常見ECONNREFUSED或1006異常關閉。 - 配對死鎖：網關綁定
lan後，控制面與 CLI 互相要求對方先被批准，若文檔未給出「先用帶 token 的 dashboard URL 或 CLIdevices approve」的明確順序，會在 1008 上循環。 - bind 模式與 Docker 網橋語義混用：
gateway.bind=loopback與「跨容器訪問」目標衝突；切到lan後若未同步調整 CLI 的可達 URL，會出現「網關日誌已 listen，但外部握手仍失敗」。 - 卷權限與 uid 1000：鏡像內進程常以 node uid 1000 寫入掛載目錄；宿主機若用 root 生成文件，會在 Mac VPS 上表現為間歇性寫入失敗，進一步放大 token 持久化失敗。
2. 對照表：症狀、根因與首選命令
下表可直接貼進值班手冊「首屏 triage」；與站內 生產加固：暴露面與 Token 對照閱讀可補齊長期策略。
| 症狀（日誌/CLI） | 高概率根因 | 首選動作（可審計） |
|---|---|---|
| token mismatch | 環境變量與 json 雙源不一致 | grep 對齊；setup 前固定 hex token |
| 127.0.0.1:18789 拒絕 | CLI 與 gateway 分命名空間 | network_mode: service:openclaw-gateway 或 GATEWAY_URL 指服務名 |
| 1008 配對循環 | 互等批准 | dashboard --no-open；devices approve |
| 健康檢查飄紅 | 未探埠 | HTTP 探 /healthz 與 /readyz |
| 寫入又丟 | 卷或 uid | bind 到 VPS 盤；chown -R 1000:1000 |
單一真源原則：在 Mac VPS 上首次部署前執行
export OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)，將同一字符串寫入 .env、Compose 的 gateway 與 CLI 環境塊，並在 onboarding 全過程中只粘貼這一份；禁止在排障中途讓腳本重新生成第二份 token。
3. 五步 Runbook：從預置 Token 到可值班驗收
- 凍結 token：在任意管理終端生成 hex，寫入版本庫外的
.env.production，並在變更單記錄「鏡像 tag + token 指紋（前 8 位）」。 - 對齊雙源：啟動前用只讀命令確認
gateway.auth.token與OPENCLAW_GATEWAY_TOKEN完全一致；若使用多階段 compose，檢查 CLI service 是否繼承了同名環境變量。 - 修正網絡：若必須分容器，優先讓 CLI
network_mode: service:openclaw-gateway；否則為 CLI 設置GATEWAY_URL=ws://openclaw-gateway:18789並保證 DNS 在 compose 網絡內可解析。 - 打破配對環：在網關容器內執行
openclaw dashboard --no-open，用列印的 URL 完成控制面；再於 CLI 側devices approve；全程保留審計日誌片段。 - 探活與 launchd：主機側用
curl -fsS http://127.0.0.1:18789/healthz與readyz寫入 plist 的SuccessfulExit判定；與站內 Compose 7×24 文對齊restart與資源上限，避免「網關進程在但 WS 未就緒」的假綠。
Compose 片段示例（僅示意網絡縫合，生產請按官方倉庫模板合併）：
services:
openclaw-gateway:
image: ghcr.io/openclaw/openclaw:latest
environment:
OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
ports:
- "18789:18789"
openclaw-cli:
network_mode: "service:openclaw-gateway"
environment:
OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN}
4. 可引用技術信息：埠、UID 與探活路徑
- 埠：默認網關 WebSocket/控制面監聽
18789；任何健康檢查腳本應命中真實監聽地址而非僅docker ps狀態。 - UID：官方鏡像常見運行用戶 uid
1000；Mac VPS 宿主機目錄權限應與之對齊，避免「配置已寫入但容器重啟後丟失」的假性修復。 - 探活：
/healthz表示進程存活，/readyz更貼近可接受 WS 的就緒語義；值班手冊應寫明先後次序與超時。
5. 與 Compose 7×24 與原生網關 Runbook 的閱讀順序
Compose 語言先讀 7×24；網關/CLI 真相源分歧再讀 ladder。筆記本演示在無 UI 的 Mac VPS上會放大雙源 token 與分容器網絡成本。Docker 比 launchd 多一層排障心智；要獨佔 Apple Silicon、固定出口、可預期並發承載網關，租賃 VPSMAC M4 Mac 雲更易把卷、plist 與 Compose 寫進同一手冊。開通自動化見 90 秒 API 文。