閘道擁有配對

閘道擁有配對（選項 B）

在閘道擁有配對中，閘道是判斷允許哪些節點加入的來源事實。UI（macOS 應用程式、未來的客戶端）只是用來批准或拒絕待處理請求的前端介面。

重要提示： WS 節點在 connect 期間使用 裝置配對（角色 node）。 node.pair.* 是一個獨立的配對存儲，並不對 WS 握手進行閘道控制。只有明確呼叫 node.pair.* 的客戶端才會使用此流程。

概念

待處理請求：節點請求加入；需要批准。
已配對節點：已獲批准並發有驗證權杖的節點。
傳輸：閘道 WS 端點轉發請求但不決定成員資格。（舊版 TCP 橋接支援已棄用/移除。）

配對運作方式

節點連線至閘道 WS 並請求配對。
閘道儲存待處理請求並發出 node.pair.requested。
您批准或拒絕請求（CLI 或 UI）。
批准後，閘道會發出新權杖（權杖會在重新配對時輪替）。
節點使用權杖重新連線，此時即為「已配對」。

待處理請求會在 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 表面（閘道通訊協定）

事件：

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

方法：

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

備註：

node.pair.request 對於每個節點是等冪的：重複呼叫會傳回相同的待處理請求。
對同一待處理節點的重複請求也會重新整理儲存的節點中繼資料，以及最新的允許清單宣告指令快照，以供操作員檢視。
核准一律會產生新的令牌；絕不會從 node.pair.request 傳回任何令牌。
請求可能包含 silent: true 作為自動核准流程的提示。

重要提示：

節點配對是一個信任/身分流程以及令牌發行程序。
它並不會針對每個節點鎖定即時節點指令介面。
即時節點指令來自於節點在連線時所宣告的內容，並套用閘道的全域節點指令政策 (gateway.nodes.allowCommands / denyCommands) 之後。
針對個別節點的 system.run 允許/詢問政策存在於節點的 exec.approvals.node.* 中，而非配對記錄內。

節點指令閘道 (2026.3.31+)

當節點首次連線時，會自動請求配對。在配對請求獲得核准之前，來自該節點的所有待處理節點指令都會被過濾且不會執行。一旦透過配對核准建立起信任，節點宣告的指令就會變為可用，但仍受限於一般指令政策的規範。

這意味著：

先前僅依靠裝置配對來公開指令的節點，現在必須完成節點配對。
在配對核准前排入佇列的指令會被捨棄，而非延後執行。

節點事件信任邊界 (2026.3.31+)

節點起始的摘要及相關工作階段事件僅限於預期的信任介面。先前依賴更廣泛主機或工作階段工具存取的通知驅動或節點觸發流程可能需要調整。此強化措施確保節點事件無法提升至超出節點信任邊界允許範圍的主機層級工具存取權。

自動核准 (macOS 應用程式)

在以下情況下，macOS 應用程式可以選擇嘗試 靜默核准：

請求被標記為 silent，且
應用程式可以使用同一個使用者驗證到閘道主機的 SSH 連線。

如果自動審核失敗，則會回退到正常的「審核/拒絕」提示。

儲存（本機，私有）

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

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

如果您覆寫 OPENCLAW_STATE_DIR，nodes/ 資料夾也會隨之移動。

安全性注意事項：

權杖是機密；請將 paired.json 視為敏感資料。
輪替權杖需要重新審核（或刪除節點條目）。

傳輸行為

傳輸層是無狀態的；它不儲存成員資格。
如果閘道離線或配對已停用，節點將無法配對。
如果閘道處於遠端模式，配對仍然會針對遠端閘道的儲存庫進行。