掌握 Gateway 配對：管理 Node 加入的正確姿勢

處理分散式系統中的裝置授權總是很麻煩。當你有多個 Node 想要加入網路時，手動管理權限和 Token 往往會變成開發者的噩夢。你可能只是想簡單地核准一個新裝置，而不是在複雜的設定檔中迷失。

在 Gateway-owned pairing 模式中，Gateway 就是 Node 是否允許加入的「唯一事實來源」。不論是 macOS App 還是未來的客戶端，都只是用來核准或拒絕請求的前端介面。

需要準備的東西

• Gateway WS endpoint
• OpenClaw CLI 工具

快速開始

要在 5 分鐘內完成 Node 配對，請跟著以下步驟：

1. 發起請求：Node 連接到 Gateway WS 並要求配對。
2. 查看狀態：在終端機輸入 openclaw nodes pending 查看待處理的請求。
3. 核准加入：執行 openclaw nodes approve <requestId>。
4. 自動重連：Node 會取得新的 Token 並自動重新連線，完成配對。

請注意，待處理的請求會在 5 分鐘後 自動過期。

核心概念

在開始操作前，你需要理解這幾個關鍵點：

• Pending request：Node 發出的加入申請，需要你手動核准。
• Paired node：已核准的 Node，擁有 Gateway 核發的專屬 Auth Token。
• Transport：Gateway WS endpoint 只負責轉發請求，不決定成員資格。
• Storage：配對狀態儲存在 Gateway 的狀態目錄中（預設為 ~/.openclaw）。

重要提醒：WS Node 在 connect 時使用的是 device pairing（role 為 node）。node.pair.* 是一套獨立的配對儲存機制，並不會攔截 WS 握手過程。只有明確呼叫 node.pair.* 的客戶端才會進入這個流程。

CLI 工作流

如果你偏好在終端機操作，這些指令是你最常會用到的：

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

你可以透過 nodes status 隨時查看已配對或已連線的 Node 及其具備的功能。

API 介面詳解

如果你要開發自己的前端介面，可以利用 Gateway protocol 提供的 API：

Events

• node.pair.requested — 當有新的待處理請求建立時發送。
• node.pair.resolved — 當請求被核准、拒絕或過期時發送。

Methods

• node.pair.request — 建立或重用一個待處理請求。此方法具有冪等性（Idempotent），重複呼叫會回傳同一個請求。
• node.pair.list — 列出所有待處理與已配對的 Node。
• node.pair.approve — 核准請求並核發新的 Token。
• node.pair.reject — 拒絕請求。
• node.pair.verify — 驗證 { nodeId, token } 的合法性。

開發筆記：核准操作「一定」會產生新的 Token。node.pair.request 永遠不會回傳 Token。

自動核准機制 (macOS)

macOS App 在滿足以下兩個條件時，會嘗試進行 silent approval（靜默核准）：

1. 請求標記為 silent: true。
2. App 能透過同一個使用者帳號驗證與 Gateway 主機的 SSH 連線。

如果靜默核准失敗，系統會退回到標準的「核准/拒絕」提示視窗。

安全與儲存

配對資料預設儲存在 ~/.openclaw/nodes/ 下的 paired.json 與 pending.json。如果你設定了 OPENCLAW_STATE_DIR 環境變數，資料夾會隨之遷移。

請記住，Token 屬於敏感資訊，請妥善保護 paired.json。如果你想更換 Token，就必須重新執行核准流程或刪除該 Node 記錄。

疑難排解

• 找不到配對請求：請確認 Node 是否已連線至 Gateway。如果 Gateway 離線或配對功能被停用，Node 將無法發起配對。
• 請求消失了：待處理請求只有 5 分鐘有效期，逾時請重新發起請求。
• 遠端模式問題：當 Gateway 處於 remote mode 時，配對行為仍會針對遠端 Gateway 的儲存區進行操作。
• Token 失效：一旦執行核准操作，舊的 Token 就會失效。請確保 Node 使用的是最新的 Token 重新連線。

想要更快速地完成設定嗎？試試我們的 AI Setup Assistant。

下一步

• Node Lifecycle API
• Gateway Configuration Reference