2026 OpenClaw Gateway 配對與 Token 衝突實務：onboarding 卡住、1006/1008 與環境變數覆寫設定檔的分步對照清單

約 15 分鐘閱讀 · MACCOME

誰會遇到：已用 Docker 或本機安裝 OpenClaw，但 openclaw CLI 在首次配對、onboarding 或容器內執行時反覆出現 WebSocket 1006/1008，或日誌顯示 token mismatch，改設定檔也不生效。本文結論：把環境變數覆寫、CLI 實際連線的 ws URL、配對狀態機三件事對齊到同一張對照表，再銜接 openclaw doctor 與 Docker 網路篇。結構：六類誤判、症狀矩陣、指紋指令、六步 Runbook、三 KPI、選型收束。

為什麼「改了 gateway.auth.token 仍是 mismatch」？六類常見誤判

OpenClaw Gateway 在 2025–2026 社群排障裡，配對與驗證常與「網路斷線」混為一談：日誌同時出現關閉碼與模型錯誤，容易誤判成上游 LLM 掛點。以下六條建議與《裝後 doctor 與 Gateway 健康檢查》一併列在 Wiki 首頁。

  1. OPENCLAW_GATEWAY_TOKEN 靜默覆寫設定檔：容器或 launchd 單元注入的環境變數優先權更高，檔案裡的 gateway.auth.token 已改但行程仍讀舊值，表現成「改完重啟仍 mismatch」。
  2. 容器內 CLI 預設連 127.0.0.1：Compose 未把 CLI 的 Gateway URL 指到 openclaw-gateway 服務名時，握手階段即失敗，日誌可能只給 1006/1008 而看不到應用層錯誤，與《Docker 網路分診清單》症狀重疊。
  3. 配對流程未完成卻開始跑重工作：onboarding 需明確確認或寫入狀態的步驟被腳本化流水線跳過，Gateway 已監聽但連線層尚未就緒，CLI 側表現為「偶發連上、立刻斷線」。
  4. 多份設定路徑混淆：使用者目錄與專案目錄各有一份 .openclaw 或等價設定，CLI 實際載入路徑與編輯器開啟的不是同一個檔案。
  5. 舊 token 殘留在 CI 密鑰：輪換 Gateway token 後，GitHub Actions／GitLab CI 變數未同步，夜間 job 把錯誤 token 打滿日誌，掩蓋真正要修的 Runner 標籤問題。
  6. 把 1006 一律當「網路抖一下」：未區分「協定正常關閉」與「驗證／子協定失敗」兩類語意，導致在網路篇與配對篇之間來回而不收斂。

與《官方安裝指令稿與 npm 全域路徑》的關係：安裝篇保證「二進位與 Node 版本在 PATH」；本篇保證「CLI 與 Gateway 對同一 token、同一 ws 端點說話」。兩者應在同一「首次上線 Runbook」裡依序引用。

表 1：症狀 → 優先懷疑堆疊 → 下一步（先配對，後網路，再模型）

下列矩陣用於第一次分診：若某列命中，請先把對應檢查做到「可複現的指令輸出」再進下一層；避免同時改 token、改 Compose、改反向代理三處。

你看到的表面症狀優先懷疑堆疊立刻做的檢查下一步文件
日誌：token mismatch 且改檔無效環境變數覆寫／多設定檔列印行程環境裡的 OPENCLAW_GATEWAY_*；對照實際載入路徑本文 §3 指紋指令稿；裝後 doctor 篇
僅容器內失敗，宿主機成功迴環位址／服務名稱／DNS在容器裡 curl 或 nc 探活 Gateway 連接埠；核對 ws URL 主機名Docker 網路分診清單
1008＋401/403 語意或驗證失敗字樣驗證設定、反向代理剝除標頭loopback 直連複現；對照反代前後回應標頭Nginx／Caddy 反向代理與 WebSocket 篇
1006 頻繁、無明顯驗證錯誤閒置斷線、探針誤殺、版本不一致對齊 CLI 與 Gateway 版本；看閘道日誌是否主動回收連線Gateway 無回應與 doctor 篇
onboarding UI／CLI 卡住不動狀態機未完成／連接埠被佔檢查監聽連接埠衝突；重跑配對前依官方指引清理暫態官方 Troubleshooting；本文 Runbook
重裝後「第一次就連上」但隨即斷線舊 token 注入層仍在檢查 systemd drop-in、shell profile、CI 變數安裝指令稿篇的 pin 與代理備援節

可執行片段：列印「誰覆寫了 token」與「CLI 實際連哪裡」

把輸出貼到工單；佔位路徑請替換為你的設定根目錄。與《Docker 持久化卷與權限》一起檢視時，確認掛載沒有把舊設定目錄蓋在新卷之上。

bash
# A) 目前 shell 可見的環境變數（注意大小寫與前綴）
env | sort | grep -i OPENCLAW || true

# B) 僅範例：若使用 systemd 管理 gateway，查看 drop-in 是否注入 token
# systemctl show openclaw-gateway --property=Environment 2>/dev/null || true

# C) CLI 版本與 doctor（先淺後深，避免在正式環境盲目 --fix）
openclaw --version || true
openclaw doctor 2>/dev/null | sed -n '1,40p' || true

# D) 列印 CLI 側設定的 gateway URL（子指令依安裝版本為準）
# openclaw config get gateway.remoteUrl  # 範例名稱，佔位

# E) Docker：進入執行 CLI 的容器核對 ws 目標不是誤設的 127.0.0.1:18789
# docker compose exec cli sh -lc 'env | grep -i OPENCLAW; getent hosts openclaw-gateway || true'
info

提示：社群 issue 常見「環境變數裡的 token 與檔案不一致」導致 onboarding 長時間卡住；先把 A／B 兩步輸出貼齊，再討論是否改 Compose。

六步 Runbook：從「連不上」到「可複現的配對結論」

  1. 凍結版本指紋：記錄 CLI、Gateway 映像 tag 或 npm 全域版本；與《安裝指令稿篇》的 pin 策略對齊，避免一邊排錯一邊自動升級。
  2. 分層複現：loopback 直連 → 同主機不同網路命名空間（容器）→ 反向代理；每一層留下日誌片段，證明失敗發生在哪一層。
  3. 清空覆寫來源：逐項移除 OPENCLAW_GATEWAY_TOKEN 等注入，確認行程重啟後環境乾淨，再寫回設定檔中的單一真源。
  4. 校正 ws URL：在容器場景明確使用服務名稱與正確連接埠；與 Docker 網路篇的「禁止預設 127.0.0.1 誤指」條款對照。
  5. 重跑配對並截圖狀態：依官方 onboarding 順序執行；若支援 doctor --deep，在變更視窗內使用並保存輸出。
  6. 寫回歸測試：把最小複現寫成 CI 裡的 smoke（僅連 health，不跑重模型），防止後續 Compose 合併又引入 token 雙軌。

三條應寫進儀表板與變更單的「硬核」口徑

  1. Token 真源計數：統計環境變數、設定檔、金鑰管理注入三路的 token 片段（雜湊前綴即可）；大於 1 即違規，須先收斂。
  2. 配對重試率：記錄 onboarding 重試次數／成功次數；短期飆升通常意味雙軌 token 或錯誤 ws 主機，而不是「模型慢」。
  3. 1006／1008 分類占比：按週聚合關閉碼與相鄰日誌關鍵字；若 1008 與驗證關鍵字同漲，優先查反向代理與標頭，而不是加 CPU。

工程對齊說明（非實驗室跑分，僅社群與維運側經驗區間）：在公開 issue 討論中，token 雙軌與容器內迴環誤指長期佔據「首次部署失敗」類問題的前列；把環境變數稽核寫進變更範本後，平均排障輪次通常可明顯下降。更重要的是，這類問題與機型 GHz 關係不大，換更大記憶體未必解決握手失敗。

若 Gateway 需要 7×24 上線且避免與個人筆電搶電、搶睡眠，應把「穩定獨佔執行面」與「配對／升級視窗」寫進同一份 SRE 文件；這與企業在遠端 Mac 上常駐 Agent 閘道的實務相一致。

為什麼「筆電隨手跑 Gateway」難撐正式配對節奏

個人裝置上的 Gateway 易受睡眠、VPN 切換與企業憑證更新影響，配對狀態機更難做可稽核回放；一旦 token 輪換涉及多人 CI，筆電場景也缺少固定主機名與穩定迴環邊界，排障日誌碎片化。

把 Gateway 放在可隨時重啟、磁碟與日誌可預測、且與團隊 Runner 同網的獨佔遠端 Mac，通常比在多台個人機之間漂移更有利於收斂 onboarding 問題；需要 Apple Silicon 常駐、並與 CI 金鑰模型一致交付的團隊而言，MACCOME 的 Mac mini M4／M4 Pro 多地區節點與彈性租期，能把「配對排障」與「執行面穩定」放在同一帳單與變更節奏裡。建議先閱讀公開租賃價格說明，再把遠端機納入與《遠端 Mac 常駐維運清單》一致的維運表。

試點建議：選一台與主 CI 同區的遠端機，僅部署 Gateway＋最小 smoke job，以雙週複盤跑滿本節六步 Runbook，再決定是否把互動式開發也遷到同一拓樸。

常見問題

應該先跑 doctor 還是先改 token？

先依本文表 1 做「配對／token」分流；若已確認是網路層再並行 doctor 的網路檢查項。公開價格與區域說明見 雲端 Mac 租賃價格說明。

1006 一定比 1008「更不嚴重」嗎？

不一定。應結合相鄰日誌列與是否可穩定複現；把關閉碼當標籤而非結論，避免跳過驗證排查。

可以在正式容器裡長期 export token 嗎？

不建議。較穩妥的是由編排器注入短期憑證或使用機密管理 sidecar，並把「真源」收斂到一處；否則輪換時極易出現雙軌。