> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 節點配對

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

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

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

## 能力核准的運作方式

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

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

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`。待處理
要求會由閘道本身在節點連線期間建立，而它們所服務的獨立節點權杖
已不復存在；節點驗證使用裝置配對權杖。

注意事項：

* 使用未變更介面重新連線時，會重複使用待處理要求；重複的
  要求會重新整理儲存的節點中繼資料，以及最新列入允許清單的
  宣告命令快照，供操作員查看。
* 操作員範圍層級和核准時檢查摘要請參閱
  [操作員範圍](/zh-TW/gateway/operator-scopes)。
* `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`

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

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

## 節點命令控管（2026.3.31+）

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

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

這表示：

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

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

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

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

持久性節點存在狀態更新遵循相同的身分邊界：
只有經過驗證的節點裝置工作階段才會接受 `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"`，而其首次宣告的
能力介面會在同一步驟中獲得核准——金鑰相符已證明
該節點是在操作員所擁有機器上的操作員帳號下執行，這與
手動能力核准所確認的主張相同。後續的介面升級仍會
顯示提示。

強化或停用：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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
選擇加入：

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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 驗證](/zh-TW/gateway/trusted-proxy-auth)。

## 儲存空間（本機、私密）

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

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

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

安全性注意事項：

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

## 傳輸行為

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

## 相關內容

* [頻道配對](/zh-TW/channels/pairing)
* [節點命令列介面](/zh-TW/cli/nodes)
* [裝置命令列介面](/zh-TW/cli/devices)