跳轉到主要內容

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.

「配對」是 OpenClaw 的明確存取核准步驟。 它用於兩個地方：
  1. DM 配對（誰被允許與 bot 對話）
  2. Node 配對（哪些裝置/Node 被允許加入 Gateway 網路）
安全情境：安全性

​
1) DM 配對（傳入聊天存取）

當頻道設定了 DM 政策 pairing 時，未知寄件者會取得一組短代碼，且其訊息在你核准前不會被處理。 預設 DM 政策記錄於：安全性 只有在有效 DM 允許清單包含 "*" 時，dmPolicy: "open" 才是公開的。 設定與驗證要求公開開放設定必須使用該萬用字元。如果現有 狀態包含 open 與具體的 allowFrom 項目，執行時仍只允許 那些寄件者，且配對儲存區核准不會擴大 open 存取範圍。 配對碼：
  • 8 個字元、大寫，沒有容易混淆的字元（0O1I）。
  • 1 小時後過期。bot 只會在建立新請求時傳送配對訊息（約每位寄件者每小時一次）。
  • 預設每個頻道的待處理 DM 配對請求上限為 3；額外請求會被忽略，直到其中一個過期或被核准。

​
核准寄件者

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>
如果尚未設定命令擁有者，核准 DM 配對碼也會將 commands.ownerAllowFrom 啟動設定為已核准的寄件者，例如 telegram:123456789。 這會為首次設定提供一個明確的擁有者，用於特權命令與執行 核准提示。擁有者存在後，後續配對核准只會授予 DM 存取；它們不會新增更多擁有者。 支援的頻道：discord、feishu、googlechat、imessage、irc、line、matrix、mattermost、msteams、nextcloud-talk、nostr、openclaw-weixin、signal、slack、synology-chat、telegram、twitch、whatsapp、zalo、zalouser。

​
可重複使用的寄件者群組

當同一組受信任寄件者應套用到多個訊息頻道，或同時套用到 DM 與群組允許清單時，請使用頂層 accessGroups。 靜態群組使用 type: "message.senders"，並從頻道允許清單以 accessGroup:<name> 參照： 
{
  accessGroups: {
    operators: {
      type: "message.senders",
      members: {
        discord: ["discord:123456789012345678"],
        telegram: ["987654321"],
        whatsapp: ["+15551234567"],
      },
    },
  },
  channels: {
    telegram: { dmPolicy: "allowlist", allowFrom: ["accessGroup:operators"] },
    whatsapp: { groupPolicy: "allowlist", groupAllowFrom: ["accessGroup:operators"] },
  },
}
存取群組的詳細文件在此：存取群組

​
狀態儲存位置

儲存在 ~/.openclaw/credentials/ 下：
  • 待處理請求：<channel>-pairing.json
  • 已核准允許清單儲存區：
    • 預設帳戶：<channel>-allowFrom.json
    • 非預設帳戶：<channel>-<accountId>-allowFrom.json
帳戶範圍行為：
  • 非預設帳戶只讀寫其範圍限定的允許清單檔案。
  • 預設帳戶使用頻道範圍、未限定範圍的允許清單檔案。
請將這些視為敏感資料（它們控管對你助理的存取）。
配對允許清單儲存區用於 DM 存取。群組授權是分開的。 核准 DM 配對碼不會自動允許該寄件者執行群組 命令或在群組中控制 bot。首次擁有者啟動是 commands.ownerAllowFrom 中的另一個設定狀態，而群組聊天傳遞仍遵循 頻道的群組允許清單（例如 groupAllowFrom、groups，或依頻道而定的每群組 或每主題覆寫）。

​
2) Node 裝置配對（iOS/Android/macOS/headless Node）

Node 會以 role: node 的裝置身分連線到 Gateway。Gateway 會建立必須核准的裝置配對請求。

​
透過 Telegram 配對（建議用於 iOS）

如果你使用 device-pair Plugin，可以完全從 Telegram 進行首次裝置配對：
  1. 在 Telegram 中，傳訊息給你的 bot：/pair
  2. bot 會回覆兩則訊息：一則指示訊息，以及一則獨立的設定碼訊息（在 Telegram 中易於複製/貼上）。
  3. 在你的手機上，開啟 OpenClaw iOS app → Settings → Gateway。
  4. 掃描 QR code 或貼上設定碼並連線。
  5. 回到 Telegram：/pair pending（檢閱請求 ID、角色與範圍），然後核准。
設定碼是 base64 編碼的 JSON payload，內容包含：
  • url：Gateway WebSocket URL（ws://... 或 wss://...）
  • bootstrapToken：用於初始配對握手的短效單一裝置啟動 token
該啟動 token 攜帶內建的配對啟動 profile：
  • 主要交接的 node token 保持 scopes: []
  • 任何交接的 operator token 仍受限於啟動允許清單： operator.approvals、operator.read、operator.talk.secrets、operator.write
  • 啟動範圍檢查以角色為前綴，而不是單一扁平範圍池： operator 範圍項目只滿足 operator 請求，且非 operator 角色 仍必須在自己的角色前綴下請求範圍
  • 後續 token 輪替/撤銷仍同時受限於裝置已核准的 角色合約與呼叫者 session 的 operator 範圍
設定碼有效期間，請將其視為密碼。 對於 Tailscale、公開或其他遠端行動裝置配對，請使用 Tailscale Serve/Funnel 或另一個 wss:// Gateway URL。明文 ws:// 設定碼只接受 loopback、私人 LAN 位址、.local Bonjour 主機，以及 Android emulator host。Tailnet CGNAT 位址、.ts.net 名稱與公開主機仍會 在 QR/setup-code 發行前以失敗關閉方式拒絕。

​
核准 Node 裝置

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
當明確核准遭拒，原因是執行核准的已配對裝置 session 以僅限配對範圍開啟時，CLI 會以 operator.admin 重試相同請求。這讓現有具 admin 能力的已配對裝置可以復原新的 Control UI/瀏覽器配對，而不必手動編輯 devices/paired.json。Gateway 仍會驗證重試的連線；無法以 operator.admin 驗證的 token 仍會被封鎖。 如果同一裝置以不同 auth 詳細資料重試（例如不同 角色/範圍/公開金鑰），先前的待處理請求會被取代，並建立新的 requestId。
已配對裝置不會無聲取得更廣泛的存取。如果它重新連線並要求更多範圍或更廣泛的角色，OpenClaw 會讓現有核准維持原樣，並建立新的待處理升級請求。核准前，請使用 openclaw devices list 比較目前已核准的存取與新請求的存取。

​
選用的受信任 CIDR Node 自動核准

裝置配對預設仍為手動。對於嚴格控管的 Node 網路， 你可以選擇以明確 CIDR 或精確 IP 啟用首次 Node 自動核准： 
{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}
這只套用於沒有請求 範圍的新 role: node 配對請求。Operator、瀏覽器、Control UI 與 WebChat 用戶端仍需要手動 核准。角色、範圍、中繼資料與公開金鑰變更仍需要手動 核准。

​
Node 配對狀態儲存

儲存在 ~/.openclaw/devices/ 下：
  • pending.json（短效；待處理請求會過期）
  • paired.json（已配對裝置 + token）

​
注意事項

  • 舊版 node.pair.* API（CLI：openclaw nodes pending|approve|reject|remove|rename）是 另一個由 gateway 擁有的配對儲存區。WS Node 仍需要裝置配對。
  • 配對記錄是已核准角色的持久真實來源。有效 裝置 token 仍受限於該已核准角色集合；已核准角色之外的零散 token 項目 不會建立新的存取。

​
相關文件