Gateway 主導的配對（Option B）

在 Gateway 主導的配對模式中，Gateway 是決定哪些節點可以加入的權威來源。UI 端（macOS app、未來的用戶端）只是負責核准或拒絕待處理請求的介面。

重要： WS 節點在 connect 時使用裝置配對（角色 node）。node.pair.* 是一套獨立的配對儲存機制，不會影響 WS 交握流程。只有明確呼叫 node.pair.* 的用戶端才會走這個流程。

概念

待處理請求：某個節點請求加入，需要核准。
已配對節點：已核准的節點，擁有一組發行的認證 token。
傳輸層：Gateway WS 端點負責轉送請求，但不決定成員資格。（舊版 TCP bridge 支援已淘汰/移除。）

配對流程

節點連線到 Gateway WS 並請求配對。
Gateway 儲存一筆待處理請求並發出 node.pair.requested 事件。
你核准或拒絕此請求（透過 CLI 或 UI）。
核准後，Gateway 發行一組新 token（重新配對時 token 會輪替）。
節點使用該 token 重新連線，正式成為「已配對」狀態。

待處理請求在 5 分鐘後自動過期。

CLI 操作流程（適合無介面環境）

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

nodes status 會顯示已配對/已連線的節點及其能力。

API 介面（gateway protocol）

事件：

node.pair.requested — 有新的待處理請求時發出。
node.pair.resolved — 請求被核准/拒絕/過期時發出。

方法：

node.pair.request — 建立或重用待處理請求。
node.pair.list — 列出待處理和已配對的節點。
node.pair.approve — 核准待處理請求（發行 token）。
node.pair.reject — 拒絕待處理請求。
node.pair.verify — 驗證 { nodeId, token }。

注意事項：

node.pair.request 對同一節點具有冪等性：重複呼叫會回傳相同的待處理請求。
核准時一律產生新 token；node.pair.request 不會回傳任何 token。
請求可包含 silent: true 作為自動核准流程的提示。

自動核准（macOS app）

macOS app 可以選擇嘗試靜默核准，條件是：

請求標記為 silent，且
app 能透過相同使用者的 SSH 連線驗證 gateway 主機。

如果靜默核准失敗，會退回一般的「核准/拒絕」提示。

儲存（本機、私有）

配對狀態儲存在 Gateway 狀態目錄下（預設 ~/.openclaw）：

~/.openclaw/nodes/paired.json
~/.openclaw/nodes/pending.json

如果你覆寫了 OPENCLAW_STATE_DIR，nodes/ 資料夾會跟著搬移。

安全注意事項：

Token 屬於機密資訊，請將 paired.json 視為敏感檔案。
輪替 token 需要重新核准（或刪除該節點的條目）。

傳輸層行為

傳輸層是無狀態的，不會儲存成員資格。
如果 Gateway 離線或配對功能停用，節點將無法配對。
如果 Gateway 處於 remote 模式，配對仍然是對遠端 Gateway 的儲存進行操作。