---
read_when:
    - 在沒有 macOS 使用者介面的情況下實作節點配對核准
    - 新增核准遠端節點的命令列介面流程
    - 使用節點管理擴充閘道通訊協定
summary: 節點能力核准：裝置配對後，節點如何取得命令公開權限
title: 節點配對
x-i18n:
    generated_at: "2026-07-11T21:23:35Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 753b01681fa9be17df853b63210f54374d054a6dde37746a3b5fda69073af71d
    source_path: gateway/pairing.md
    workflow: 16
---

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

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

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

## 能力核准的運作方式

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

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

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

```bash
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` 請求：
    `operator.pairing` + `operator.admin`

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

- 即時節點命令來自節點連線時宣告的內容，並由
  閘道的全域節點命令政策（`gateway.nodes.allowCommands` 和
  `denyCommands`）進行篩選。
- 各節點的 `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 驗證的裝置自動核准（預設）

當來自私人／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 本機性宣告失效，
配對路徑將要求明確核准，而不會默默將要求視為同一主機的連線。關於操作者驗證的
對應規則，請參閱[受信任的代理驗證](/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)