OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

節點配對

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

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

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

能力核准的運作方式

  1. 節點連線至閘道 WS（此步驟受裝置配對管控）。
  2. 閘道會比較已宣告的能力／命令範圍與 已核准範圍；新的或擴大的範圍會在 裝置記錄中儲存一筆待處理請求，並發出 node.pair.requested。
  3. 你可以核准或拒絕該請求（透過命令列介面或使用者介面）。
  4. 在核准之前，節點命令會持續受到篩選；核准後會公開已宣告的 範圍，但仍受一般命令政策約束。

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

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

bash
openclaw nodes pendingopenclaw nodes approve <requestId>openclaw nodes reject <requestId>openclaw nodes statusopenclaw 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 請求： operator.pairing + operator.admin

節點命令管控（2026.3.31+）

節點首次連線時，系統會自動提出配對請求。 在該請求獲得核准前，來自該節點的所有待處理節點命令都會 遭到篩除，且不會執行。配對獲得核准後，該節點宣告的 命令即會可用，但仍受一般命令政策約束。

這表示：

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

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

源自節點的摘要及相關工作階段事件僅限於 預定的受信任範圍。先前依賴更廣泛主機或工作階段工具存取權的 通知驅動或節點觸發流程可能需要調整。 這項強化措施可防止節點事件突破節點信任邊界所允許的範圍， 提升至主機層級的工具存取權。

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

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

當來自私人／CGNAT 位址的 role: node 裝置首次配對時， 若閘道可透過 SSH 證明機器擁有權，便會自動核准：閘道會 反向連線至配對主機（BatchMode、StrictHostKeyChecking=yes）， 在該處執行 openclaw node identity --json，且僅在遠端 裝置 ID 與公開金鑰完全符合待處理請求時才予以核准。金鑰相符 正是此機制安全的原因：僅能連線絕不會導致核准，因此共用 NAT 的其他租戶、 共用主機上的其他使用者，以及區域網路偽裝，全都會回退至一般 提示流程。

預設啟用。觸發此機制的要求：

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

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

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

強化或停用：

json5
{  gateway: {    nodes: {      pairing: {        // Disable entirely:        sshVerify: false,        // ...or scope/tune the probe:        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },      },    },  },}

自動核准（macOS 應用程式）

在以下情況下，macOS 應用程式可嘗試靜默核准節點能力請求：

  • 請求標記為 silent（當裝置配對以非互動方式獲准時，閘道會將首次能力 範圍標記為靜默），且
  • 應用程式可使用同一 使用者驗證與閘道主機的 SSH 連線。

若靜默核准失敗，便會回退至一般的核准／拒絕提示。

受信任 CIDR 裝置自動核准

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

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

安全邊界：

  • 未設定 gateway.nodes.pairing.autoApproveCidrs 時停用。
  • 不存在概括性的區域網路或私人網路自動核准模式；上述經 SSH 驗證的 自動核准要求密碼學裝置金鑰相符，絕不會 僅依賴網路位置。
  • 僅全新的 role: node 裝置配對請求且未要求任何權限範圍時 才符合資格。
  • 操作員、瀏覽器、控制介面和 WebChat 用戶端仍需手動處理。
  • 角色、權限範圍、中繼資料及公開金鑰升級仍需手動處理。
  • 同主機 local loopback 的受信任代理標頭路徑不符合資格，因為該 路徑可由本機呼叫者偽造。

靜默配對取代清理

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

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

邊界：

  • 僅最新核准來源為同主機本機（silent）的記錄 才能作為觸發者及目標。受信任 CIDR 與經 SSH 驗證的配對 會跨越主機，而顯示中繼資料並非機器身分，因此 絕不會自動移除——請使用控制介面清理功能或 openclaw nodes remove 移除這些記錄。
  • 擁有者核准及 QR／設定碼（啟動程序）配對絕不會 自動移除。在來源記錄機制存在之前核准的記錄會持續受到保護， 即使相同裝置 ID 後續再次獲得靜默核准亦然。
  • 目前已連線的裝置會被略過，因此使用不同狀態目錄的並行本機工作階段 在連線期間可保留其權杖。一分鐘內核准的記錄 也會被略過，以避免同時進行的配對交握 在連線登記前互相淘汰。
  • 受影響的用戶端依其性質必定是本機用戶端，因此會在 下次連線時再次靜默配對。

中繼資料升級自動核准

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

QR 配對輔助工具

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

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

本機性與轉送標頭

只有在原始通訊端與任何上游代理證據皆一致時，閘道配對才會將連線視為 local loopback。 如果要求經由 local loopback 傳入，但帶有 Forwarded、任何 X-Forwarded-* 或 X-Real-IP 標頭證據，這些轉送標頭證據會使 local loopback 本機性宣告失效， 配對路徑將要求明確核准，而不會默默將要求視為同一主機的連線。關於操作者驗證的 對應規則，請參閱受信任的代理驗證。

儲存空間（本機、私密）

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

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

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

安全性注意事項：

  • 裝置權杖是機密資料；請將狀態資料庫視為敏感資料。
  • 輪替裝置權杖時，請使用 openclaw devices rotate / device.token.rotate。

傳輸行為

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

相關內容

Was this useful?
On this page

On this page