Node Connect（節點連線除錯）是做什麼的？

目標：針對一個特定的客戶端與一個特定的閘道器（Gateway）修正連線問題，然後證明該客戶端可以建立全新的連線。

1. 鎖定目標

在進行任何變更之前，記錄目標環境/設定檔、OpenClaw 二進位檔、設定/狀態根目錄、閘道器 URL/連接埠及服務。

針對每個 config、log、service、device 及 node 命令，使用指定的部署包裝器/設定檔。
絕不漂移到 bare openclaw、測試環境或名稱相似的部署。
如果全域執行檔已過時，請透過其擁有者呼叫目標。
驗證 status、config、logs 及 process identity 描述的是同一個閘道器。

在變更配對或認證之前，先識別目標閘道器。

2. 分類客戶端

在選擇命令之前，先根據請求和閘道器日誌進行分類：

Control UI 瀏覽器： 使用者提到 browser、dashboard、Control UI 或 webchat；日誌顯示 client=openclaw-control-ui 或 mode=webchat。
原生行動裝置/節點： 官方應用程式顯示 Connect、Scan QR 或 setup code；日誌/請求中繼資料顯示原生客戶端或 role=node。

手機可以是任一種客戶端。請勿對手機瀏覽器使用 openclaw qr 或 openclaw nodes status；那些命令屬於原生行動裝置/節點配對。

3. 觀察失敗嘗試

透過鎖定的目標執行以下命令：

openclaw gateway status --deep
openclaw logs --follow --json
openclaw devices list
openclaw config get gateway.mode
openclaw config get gateway.bind
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.allowTailscale
openclaw config get gateway.tailscale.mode

讓客戶端在日誌即時輸出時重試一次。關聯其 client ID、mode、platform、address、auth result、device ID、user 及 close code。忽略其他已配對的裝置。

解讀第一個失敗的轉換：

沒有符合的閘道器嘗試：路由、DNS、TLS、來源或代理問題。
token_missing、password_missing、不符或 Tailscale 身份識別失敗：認證在配對前失敗，因此預期 pending 清單為空。
pairing required：路由和認證成功；請核准確切的 pending 請求。
authenticated user connected / webchat connected：比對確切的客戶端；如果隨後出現 1006，請保留認證/配對並檢查生命週期、傳輸、代理或重新連線。
沒有伴隨任何應用層級連線日誌的 1006 並不證明認證/配對成功；請檢查較早的交握轉換。

4. 證明路由

選擇一種拓撲：同一台機器、LAN、Tailnet 或公有反向代理。請勿混合使用。

瀏覽器 Control UI 需要 HTTPS 或 localhost 以獲得瀏覽器裝置身份。遠端純文字 HTTP Tailnet/LAN URL 不是有效的替代方案。
gateway.tailscale.mode=off 表示 OpenClaw 並未管理 Serve/Funnel。這並不證明 Tailscale 或外部管理的 Serve 路由不存在。
當涉及 Tailscale 時，請檢查即時狀態，而不是從 OpenClaw 設定推斷：

tailscale status --json
tailscale serve status --json

將客戶端的 URL 與到達鎖定閘道器的監聽器/代理路由進行比對。

5A. Control UI 瀏覽器通道

在尋找配對請求之前，先恢復瀏覽器認證：

對於 token/password 認證，請在 Control UI 設定中輸入憑證。切勿將永久機密放入聊天、日誌或 URL 中。
優先使用 Gateway 主機上的 openclaw dashboard 進行一次性簽署的交握。僅在操作員可以擷取該主機的剪貼簿時使用 --no-open，並將主機瀏覽器/剪貼簿保持在代理工具範圍之外。切勿擷取 dashboard --json：它可能暴露交握資訊和共享憑證。切勿中繼、改寫或將回送交握 URL 傳送到遠端手機。
對於 Tailscale Serve，請驗證即時路由和轉發的身份。僅在預期的信任邊界內啟用 gateway.auth.allowTailscale。經過驗證的 Tailscale Control UI 認證加上瀏覽器裝置身份可以跳過配對。

認證成功後：

重試；切勿從預先認證的嘗試推斷配對。Token/password 認證可能顯示 pairing required；經過驗證的 Tailscale 身份可以跳過它。
如果日誌顯示 pairing required，重新列出裝置並核准確切的請求 ID。
成功的經過驗證的 Tailscale 連線可能正確地不會產生任何 pending 或 paired-device 列。
在重複出現 1006 之後，保留認證/配對並檢查重新連線的證據。

5B. 原生行動裝置/節點通道

透過鎖定的目標檢查原生路由，而不暴露設定憑證：

openclaw qr --json | jq '{gatewayUrl, gatewayUrls, auth, access, accessDowngraded, urlSource}'

對於控制遠端閘道器的 CLI，請在 --json 之前加入 --remote；它會選擇 gateway.remote.url 和遠端憑證。如果無法使用遮罩過濾器，請勿在代理可見的輸出中執行未經處理的 QR JSON。

驗證 gatewayUrl 和 urlSource。設定碼等同於密碼：請操作員從 Control UI → Devices → Pair device 複製，或在代理工具範圍外的終端機中執行 openclaw qr --setup-code-only，然後直接貼到官方應用程式中。切勿透過代理/聊天/工具輸出中繼。在 URL/認證修復或過期後產生新的代碼。

如果應用程式回報 pairing required：

openclaw devices list
openclaw devices approve --latest   # 僅預覽；不核准即退出
openclaw devices approve <requestId>
openclaw nodes status

--latest 僅預覽當前請求；切勿將其視為核准。在執行確切 ID 命令之前立即重新列出，因為重試可能會取代該請求。切勿根據位置、時間或相似性進行核准。

6. 關聯與完成

在核准之前，比對可用的請求、裝置/公鑰、客戶端、模式/角色、平台、位址、使用者和重試時間的事實。

僅在最終變更後進行的新嘗試證明所有適用的檢查通過時，才宣告成功：

確切的客戶端到達鎖定的閘道器；
預期的認證成功；
瀏覽器完成初始請求，或原生節點出現在 openclaw nodes status 中；
核准使用了確切的請求 ID；以及
後續沒有立即發生認證、配對或重新連線失敗。

QR/設定碼、啟動的瀏覽器、空的 pending 清單、核准、已配對裝置計數或 Tailscale ping 僅證明一個轉換。

報告診斷結果、選擇的路由/認證通道、確切客戶端的證據，以及任何剩餘的失敗轉換。

Node Connect（節點連線除錯）