節點配對

節點配對分為兩層，兩者都儲存在閘道的 SQLite 狀態資料庫中已配對裝置的記錄上：

• 裝置配對（角色 node）負責控管 connect 交握。請參閱下方的 受信任 CIDR 裝置自動核准 和頻道配對。
• 節點能力核准（node.pair.*）負責控管已連線節點可公開哪些宣告的 能力／命令。閘道是唯一事實來源；UI（macOS 應用程式、控制介面）是用來核准或 拒絕待處理要求的前端。

先前獨立的節點配對儲存區（nodes/paired.json，包含每個節點各自的 權杖，已於 2026 年 1 月從連線路徑中淘汰）現已移除：閘道會在啟動時一次性將 任何剩餘資料列併入裝置記錄，並以 .migrated 後綴封存舊版 檔案。舊版 TCP 橋接支援也已移除。

​

能力核准的運作方式

1. 節點連線至閘道 WS（裝置配對負責控管此步驟）。
2. 閘道會比較宣告的能力／命令介面與已核准的介面；新增或擴大的介面會在 裝置記錄上儲存一筆待處理要求，並發出 node.pair.requested。
3. 你核准或拒絕該要求（透過命令列介面或 UI）。
4. 在核准前，節點命令會持續被篩除；核准後會公開已宣告的 介面，但仍受一般命令原則約束。

待處理要求會在節點上次重試的 5 分鐘後自動到期——持續主動重新連線的節點會維持 同一筆待處理要求有效，而不會在每次嘗試時產生新的要求（及核准提示）。

​

命令列介面工作流程（適合無頭環境）

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

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

​

API 介面（閘道通訊協定）

事件：

• node.pair.requested - 建立新的待處理要求時發出。
• node.pair.resolved - 要求獲得核准、遭到拒絕或 到期時發出。

方法：

• node.pair.list - 列出待處理和已配對的節點（operator.pairing）。
• node.pair.approve - 核准待處理要求。
• node.pair.reject - 拒絕待處理要求。
• node.pair.remove - 移除已配對的節點。這會在已配對裝置儲存區中撤銷該裝置的 node 角色，同時移除已核准的節點介面，並使該裝置具節點角色的工作階段失效／中斷連線。混合角色 裝置（例如同時也具備 operator 的裝置）會保留其資料列，且只會 失去 node 角色；僅具節點角色的裝置資料列則會被刪除。授權： operator.pairing 可移除非操作員節點資料列；使用裝置權杖的呼叫端若要在混合角色裝置上 撤銷其自身的節點角色，還需要 operator.admin。
• node.rename - 重新命名已配對節點供操作員查看的顯示名稱。

已於 2026.7 移除：node.pair.request 和 node.pair.verify。待處理 要求會由閘道本身在節點連線期間建立，而它們所服務的獨立節點權杖 已不復存在；節點驗證使用裝置配對權杖。

注意事項：

• 使用未變更介面重新連線時，會重複使用待處理要求；重複的 要求會重新整理儲存的節點中繼資料，以及最新列入允許清單的 宣告命令快照，供操作員查看。
• 操作員範圍層級和核准時檢查摘要請參閱 操作員範圍。
• node.pair.approve 會使用待處理要求所宣告的命令來強制執行 額外的核准範圍：
  • 不含命令的要求：operator.pairing
  • 一般命令要求：operator.pairing + operator.write
  • 包含 system.run、system.run.prepare、 system.which、browser.proxy、fs.listDir 或 system.execApprovals.get/set 的管理員敏感要求：operator.pairing + operator.admin

節點配對核准會記錄受信任的能力介面。它不會針對每個節點固定即時節點命令介面。

• 即時節點命令來自節點連線時的宣告，並由 閘道的全域節點命令原則（gateway.nodes.commands.allow 和 gateway.nodes.commands.deny）篩選。
• 每個節點的 system.run 允許和詢問原則位於 exec.approvals.node.* 中的節點上，而非配對記錄中。

​

節點命令控管（2026.3.31+）

**重大變更：**自 2026.3.31 起，在節點配對獲得核准前，節點命令會停用。僅有裝置配對已不足以公開宣告的節點命令。

節點第一次連線時，系統會自動提出配對要求。 在該要求獲得核准前，來自該節點的所有待處理節點命令都會 被篩除且不會執行。配對獲得核准後，節點宣告的 命令便可使用，但仍受一般命令原則約束。

這表示：

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

​

節點事件信任邊界（2026.3.31+）

**重大變更：**源自節點的執行現在會維持在縮減後的受信任介面內。

源自節點的摘要和相關工作階段事件僅限於 預期的受信任介面。先前依賴較廣泛主機或工作階段工具存取權的 通知驅動或節點觸發流程可能需要調整。 此強化措施可防止節點事件升級取得超出 節點信任邊界所允許的主機層級工具存取權。

持久性節點存在狀態更新遵循相同的身分邊界： 只有經過驗證的節點裝置工作階段才會接受 node.presence.alive 事件，而且只有在裝置／節點身分已配對時，才會更新配對中繼資料。 自行宣告的 client.id 值不足以寫入 最後出現狀態。

​

SSH 驗證的裝置自動核准（預設）

當閘道能夠透過 SSH 證明機器所有權時，來自私人／CGNAT 位址的首次 role: node 裝置配對會自動獲得核准：閘道會 反向連線至配對主機（BatchMode、StrictHostKeyChecking=yes）， 在該處執行 openclaw node identity --json，且只有遠端 裝置 ID 和公開金鑰與待處理要求完全相符時才會核准。金鑰相符 是確保安全的關鍵：僅能連線絕不會觸發核准，因此 NAT 共用租戶、 共用主機上的其他使用者以及區域網路偽造都會轉入一般 提示流程。

預設啟用。觸發條件如下：

• 閘道程序使用者（或 sshVerify.user）能以非互動方式透過 SSH 連線至節點主機 （金鑰／代理程式；Tailscale SSH 也適用），而且該主機金鑰 已受信任。
• openclaw 可在遠端 PATH 上解析，以供非互動式 sh -lc 使用。
• 連線 IP 是直接的（未經 Proxy、非迴路）私人、ULA、 連結本機或 CGNAT 位址，或在設定 sshVerify.cidrs 時與其相符。
• 適用資格下限與受信任 CIDR 核准相同：僅限不含範圍的新節點 配對；升級、瀏覽器、控制介面和 WebChat 一律顯示提示。

探查執行期間，節點用戶端會收到持續重試 （wait_then_retry）的指示，而不會暫停等待手動核准；若探查 失敗，下一次嘗試會轉回一般提示流程。失敗的目標 會進入短暫冷卻期（金鑰不相符後 5 分鐘）。

獲核准的裝置會記錄 approvedVia: "ssh-verified"，而其首次宣告的 能力介面會在同一步驟中獲得核准——金鑰相符已證明 該節點是在操作員所擁有機器上的操作員帳號下執行，這與 手動能力核准所確認的主張相同。後續的介面升級仍會 顯示提示。

強化或停用：

{
  gateway: {
    nodes: {
      pairing: {
        // 完全停用：
        sshVerify: false,
        // ...或限制／調整探查：
        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },
      },
    },
  },
}

​

自動核准（macOS 應用程式）

在下列情況下，macOS 應用程式可嘗試無提示核准節點能力要求：

• 要求標記為 silent（當裝置配對以非互動方式獲得核准時，閘道會將第一個能力 介面標記為無提示），而且
• 應用程式可使用同一 使用者驗證與閘道主機的 SSH 連線。

如果無提示核准失敗，就會轉回一般的 Approve/Reject 提示。

​

受信任 CIDR 裝置自動核准

role: node 的 WS 裝置配對預設仍需手動進行。對於閘道已信任 網路路徑的私人節點網路，操作員可以使用明確的 CIDR 或確切 IP 選擇加入：

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

安全邊界：

• 未設定 gateway.nodes.pairing.autoApproveCidrs 時停用。
• 不存在涵蓋整個區域網路或私人網路的自動核准模式；上述經 SSH 驗證的 自動核准需要密碼學裝置金鑰完全相符，絕不會 僅以網路位置為依據。
• 只有不要求任何範圍的新 role: node 裝置配對要求 符合資格。
• 操作員、瀏覽器、控制介面和 WebChat 用戶端仍需手動核准。
• 角色、範圍、中繼資料和公開金鑰升級仍需手動核准。
• 同一主機的迴路受信任 Proxy 標頭路徑不符合資格，因為 本機呼叫端可以偽造該路徑。

​

無提示配對取代清理

非互動式核准會將其來源記錄在已配對裝置資料列上： 同一主機的本機原則核准記為 silent，受信任 CIDR 節點核准記為 trusted-cidr，SSH 驗證的節點核准記為 ssh-verified。狀態目錄為暫時性的用戶端（暫存家目錄、 容器、每次執行各自獨立的沙箱）會在每次執行時產生新的裝置金鑰組，且每次 執行都會以全新裝置的身分無提示地重新配對——若不清理，已配對清單 每次執行都會增加一筆過時資料列。

當閘道無提示核准本機裝置配對時，會淘汰 屬於同一用戶端叢集（clientId、clientMode 和顯示名稱皆相符）且目前 未連線的舊版 silent 核准記錄。本機用戶端是在閘道主機本身執行，因此叢集金鑰 不可能與其他機器相符。淘汰的資料列會立即失去其權杖； 任何相符的舊版節點配對項目都會被清除，並廣播 node.pair.resolved 移除事件。

邊界：

• 只有最新核准屬於同主機本機（silent）的記錄， 才能作為觸發端與目標端。受信任 CIDR 與經 SSH 驗證的配對會跨越不同主機， 而顯示中繼資料並不代表機器身分，因此絕不會自動移除這些配對——請使用 Control UI 清理功能或 openclaw nodes remove 來處理。
• 由擁有者核准以及透過 QR／設定碼（啟動程序）建立的配對， 絕不會自動移除。在來源資訊機制建立前核准的記錄仍受保護， 即使同一裝置 ID 後來再次經過靜默核准亦然。
• 目前已連線的裝置會略過，因此使用不同狀態目錄的並行本機工作階段， 在連線期間會保留其權杖。最近一分鐘內核准的記錄也會略過， 因此同時進行的配對交握不會在連線完成登記前彼此撤銷。
• 受影響的用戶端依設計皆為本機，因此會在下次連線時靜默重新配對。

​

中繼資料升級自動核准

當已配對的裝置重新連線，且只有非敏感中繼資料發生變更 （例如顯示名稱或用戶端平台提示）時，OpenClaw 會將其視為 metadata-upgrade。靜默自動核准的適用範圍很窄：僅適用於受信任、非瀏覽器的 本機重新連線，且該連線先前已證明持有本機或共用認證資訊； 這包括作業系統版本中繼資料變更後，同主機原生應用程式的重新連線。 瀏覽器／Control UI 用戶端與遠端用戶端仍使用明確的重新核准流程。 範圍升級（從讀取升級至寫入／管理員）與公開金鑰變更 不符合中繼資料升級自動核准資格；這些情況仍會保留為明確的重新核准要求。

​

QR 配對輔助工具

/pair qr 會將配對承載資料呈現為結構化媒體，讓行動裝置與 瀏覽器用戶端可直接掃描。

刪除裝置時，也會清除該裝置 ID 所有過期的待處理配對要求， 因此撤銷後，nodes pending 不會顯示孤立的資料列。

​

本機性與轉送標頭

只有原始通訊端與任何上游 Proxy 證據都一致時，閘道配對才會將連線視為回送連線。 如果要求透過回送介面抵達，但帶有 Forwarded、任何 X-Forwarded-* 或 X-Real-IP 標頭證據，該轉送標頭證據便會使 回送本機性宣告失效；配對路徑將要求明確核准，而不會靜默地將要求視為 同主機連線。操作者驗證的對等規則請參閱 受信任 Proxy 驗證。

​

儲存空間（本機、私密）

配對狀態位於已配對裝置記錄中，儲存在閘道狀態目錄下的共用 SQLite 狀態資料庫（預設為 ~/.openclaw）：

• ~/.openclaw/state/openclaw.sqlite（已配對裝置及其裝置驗證、 已核准的節點介面、待處理的介面要求、待處理的裝置配對要求， 以及啟動權杖）

如果覆寫 OPENCLAW_STATE_DIR，資料庫也會隨之移動。從使用 JSON 儲存區的 舊版本升級的閘道，會在啟動時匯入這些資料，並保留 devices/*.json.migrated 與 nodes/*.json.migrated 封存檔。

安全性注意事項：

• 裝置權杖屬於密鑰；請將狀態資料庫視為敏感資料。
• 輪替裝置權杖會使用 openclaw devices rotate / device.token.rotate。

​

傳輸行為

• 傳輸層為無狀態；不會儲存成員關係。
• 如果閘道離線或已停用配對，節點便無法配對。
• 在遠端模式下，配對會使用遠端閘道的儲存區。

​

相關內容

• 頻道配對
• 節點命令列介面
• 裝置命令列介面