節點

節點是一個伴隨裝置（macOS/iOS/Android/headless），透過 role: "node" 連接到 Gateway 的 WebSocket（與操作員使用同一埠），並透過 node.invoke 公開指令介面（如 canvas.*、camera.*、device.*、notifications.*、system.*）。通訊協定詳情：Gateway 通訊協定。

舊版傳輸方式：Bridge 通訊協定（TCP JSONL；已棄用/移除）。

macOS 也可以節點模式運作：選單列應用程式連接到 Gateway 的 WS 伺服器，將本機 canvas/camera 指令作為節點公開（因此 openclaw nodes … 可對此 Mac 操作）。

注意：

  • 節點是周邊設備，不是 gateway。它們不執行 gateway 服務。
  • Telegram/WhatsApp 等訊息傳入的是 gateway，而非節點。
  • 疑難排解指南：/nodes/troubleshooting

配對與狀態

WS 節點使用裝置配對。 節點在 connect 時提供裝置身分；Gateway 為 role: node 建立裝置配對請求。透過裝置 CLI（或 UI）核准。

快速 CLI：

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>
openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

注意：

  • nodes status 在裝置配對角色包含 node 時，標示節點為已配對。
  • node.pair.*（CLI：openclaw nodes pending/approve/reject）是 gateway 擁有的獨立節點配對儲存；它不會控制 WS connect 握手。

遠端節點主機（system.run）

當你的 Gateway 在一台機器上執行，但想在另一台機器上執行指令時，可以使用節點主機。模型仍然與 gateway 溝通；gateway 在選擇 host=node 時，將 exec 呼叫轉發到節點主機。

各部分的執行位置

  • Gateway 主機：接收訊息、執行模型、路由工具呼叫。
  • 節點主機：在節點機器上執行 system.run/system.which。
  • 核准機制：透過節點主機的 ~/.openclaw/exec-approvals.json 執行。

核准注意事項：

  • 核准支援的節點執行會綁定確切的請求上下文。
  • 對於直接的 shell/runtime 檔案執行，OpenClaw 也會盡力綁定一個具體的本機檔案運算元，若該檔案在執行前被修改則拒絕執行。
  • 如果 OpenClaw 無法確定直譯器/runtime 指令中恰好一個具體的本機檔案，核准支援的執行會被拒絕，而非假裝涵蓋完整的 runtime 範圍。如需更廣泛的直譯器語意，請使用沙箱、獨立主機，或明確的信任允許清單/完整工作流程。

啟動節點主機（前景）

在節點機器上：

openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

透過 SSH 隧道連接遠端 Gateway（loopback 繫結）

如果 Gateway 繫結到 loopback（gateway.bind=loopback，本機模式的預設值），遠端節點主機無法直接連線。建立 SSH 隧道並將節點主機指向隧道的本機端。

範例（節點主機 → gateway 主機）：

# Terminal A（持續執行）：將本機 18790 轉發到 gateway 127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# Terminal B：匯出 gateway token 並透過隧道連線
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

注意：

  • openclaw node run 支援 token 或密碼驗證。
  • 建議使用環境變數：OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD。
  • 設定檔退回值為 gateway.auth.token / gateway.auth.password。
  • 本機模式下，節點主機刻意忽略 gateway.remote.token / gateway.remote.password。
  • 遠端模式下，gateway.remote.token / gateway.remote.password 依遠端優先規則可用。
  • 如果設定了使用中的本機 gateway.auth.* SecretRef 但無法解析，節點主機驗證會安全失敗。
  • 舊版 CLAWDBOT_GATEWAY_* 環境變數在節點主機驗證解析中被刻意忽略。

啟動節點主機（服務）

openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw node restart

配對與命名

在 gateway 主機上：

openclaw devices list
openclaw devices approve <requestId>
openclaw nodes status

命名方式：

  • openclaw node run / openclaw node install 的 --display-name（儲存在節點的 ~/.openclaw/node.json）。
  • openclaw nodes rename --node <id|name|ip> --name "Build Node"（gateway 端覆寫）。

設定允許指令清單

執行核准是按節點主機個別設定的。從 gateway 新增允許清單項目：

openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"

核准資料儲存在節點主機的 ~/.openclaw/exec-approvals.json。

將 exec 指向節點

設定預設值（gateway 設定）：

openclaw config set tools.exec.host node
openclaw config set tools.exec.security allowlist
openclaw config set tools.exec.node "<id-or-name>"

或按工作階段設定：

/exec host=node security=allowlist node=<id-or-name>

設定完成後，任何 host=node 的 exec 呼叫都會在節點主機上執行（受節點允許清單/核准控制）。

相關文件：

執行指令

低階（原始 RPC）：

openclaw nodes invoke --node <idOrNameOrIp> --command canvas.eval --params '{"javaScript":"location.href"}'

常見的「提供 agent 一個 MEDIA 附件」工作流程有更高階的輔助工具。

螢幕擷取（canvas 快照）

如果節點正在顯示 Canvas（WebView），canvas.snapshot 會回傳 { format, base64 }。

CLI 輔助工具（寫入暫存檔並輸出 MEDIA:<path>）：

openclaw nodes canvas snapshot --node <idOrNameOrIp> --format png
openclaw nodes canvas snapshot --node <idOrNameOrIp> --format jpg --max-width 1200 --quality 0.9

Canvas 控制

openclaw nodes canvas present --node <idOrNameOrIp> --target https://example.com
openclaw nodes canvas hide --node <idOrNameOrIp>
openclaw nodes canvas navigate https://example.com --node <idOrNameOrIp>
openclaw nodes canvas eval --node <idOrNameOrIp> --js "document.title"

注意：

  • canvas present 接受 URL 或本機檔案路徑（--target），可選 --x/--y/--width/--height 進行定位。
  • canvas eval 接受內嵌 JS（--js）或位置參數。

A2UI（Canvas）

openclaw nodes canvas a2ui push --node <idOrNameOrIp> --text "Hello"
openclaw nodes canvas a2ui push --node <idOrNameOrIp> --jsonl ./payload.jsonl
openclaw nodes canvas a2ui reset --node <idOrNameOrIp>

注意：

  • 僅支援 A2UI v0.8 JSONL（v0.9/createSurface 會被拒絕）。

拍照與錄影（節點相機）

拍照（jpg）：

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # 預設：前後鏡頭（2 行 MEDIA）
openclaw nodes camera snap --node <idOrNameOrIp> --facing front

錄影（mp4）：

openclaw nodes camera clip --node <idOrNameOrIp> --duration 10s
openclaw nodes camera clip --node <idOrNameOrIp> --duration 3000 --no-audio

注意：

  • 節點必須在前景才能使用 canvas.* 和 camera.*（背景呼叫回傳 NODE_BACKGROUND_UNAVAILABLE）。
  • 錄影長度有上限（目前 <= 60s），避免 base64 payload 過大。
  • Android 會在可能時提示 CAMERA/RECORD_AUDIO 權限；拒絕權限會以 *_PERMISSION_REQUIRED 失敗。

螢幕錄製（節點）

支援的節點公開 screen.record（mp4）。範例：

openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10
openclaw nodes screen record --node <idOrNameOrIp> --duration 10s --fps 10 --no-audio

注意：

  • screen.record 的可用性取決於節點平台。
  • 螢幕錄製上限為 <= 60s。
  • --no-audio 可在支援的平台上停用麥克風擷取。
  • 使用 --screen <index> 可在多螢幕環境中選擇顯示器。

定位（節點）

節點在設定中啟用定位後，會公開 location.get。

CLI 輔助工具：

openclaw nodes location get --node <idOrNameOrIp>
openclaw nodes location get --node <idOrNameOrIp> --accuracy precise --max-age 15000 --location-timeout 10000

注意：

  • 定位功能預設關閉。
  • 「始終」模式需要系統權限；背景取得為盡力而為。
  • 回應包含經緯度、精度（公尺）和時間戳記。

SMS（Android 節點）

Android 節點可在使用者授予 SMS 權限且裝置支援通話功能時，公開 sms.send。

低階呼叫：

openclaw nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"Hello from OpenClaw"}'

注意：

  • 必須先在 Android 裝置上接受權限提示，才會公告此功能。
  • 僅有 Wi-Fi 且無通話功能的裝置不會公告 sms.send。

Android 裝置與個人資料指令

Android 節點可在啟用對應功能後公告額外的指令群組。

可用群組：

  • device.status、device.info、device.permissions、device.health
  • notifications.list、notifications.actions
  • photos.latest
  • contacts.search、contacts.add
  • calendar.events、calendar.add
  • motion.activity、motion.pedometer

呼叫範例：

openclaw nodes invoke --node <idOrNameOrIp> --command device.status --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command notifications.list --params '{}'
openclaw nodes invoke --node <idOrNameOrIp> --command photos.latest --params '{"limit":1}'

注意：

  • 動作指令受可用感測器的功能限制。

系統指令（節點主機 / Mac 節點）

macOS 節點公開 system.run、system.notify 和 system.execApprovals.get/set。 Headless 節點主機公開 system.run、system.which 和 system.execApprovals.get/set。

範例：

openclaw nodes run --node <idOrNameOrIp> -- echo "Hello from mac node"
openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"

注意：

  • system.run 在 payload 中回傳 stdout/stderr/exit code。
  • system.notify 會遵循 macOS 應用程式的通知權限狀態。
  • 無法辨識的節點 platform / deviceFamily metadata 使用保守的預設允許清單，排除 system.run 和 system.which。如果需要在未知平台上使用這些指令，請透過 gateway.nodes.allowCommands 明確新增。
  • system.run 支援 --cwd、--env KEY=VAL、--command-timeout 和 --needs-screen-recording。
  • 對於 shell 包裝器（bash|sh|zsh ... -c/-lc），請求範圍的 --env 值會縮減為明確的允許清單（TERM、LANG、LC_*、COLORTERM、NO_COLOR、FORCE_COLOR）。
  • 在允許清單模式下的 allow-always 決策中，已知的分派包裝器（env、nice、nohup、stdbuf、timeout）會持久化內部可執行檔路徑而非包裝器路徑。如果解除包裝不安全，則不會自動持久化允許清單項目。
  • 在 Windows 節點主機的允許清單模式下，透過 cmd.exe /c 的 shell 包裝器執行需要核准（僅有允許清單項目不會自動允許包裝器形式）。
  • system.notify 支援 --priority <passive|active|timeSensitive> 和 --delivery <system|overlay|auto>。
  • 節點主機忽略 PATH 覆寫，並過濾危險的啟動/shell 相關鍵值（DYLD_*、LD_*、NODE_OPTIONS、PYTHON*、PERL*、RUBYOPT、SHELLOPTS、PS4）。如需額外的 PATH 項目，請設定節點主機服務環境（或將工具安裝在標準位置），而非透過 --env 傳遞 PATH。
  • macOS 節點模式下，system.run 受 macOS 應用程式中的 exec 核准控制（設定 → Exec 核准）。Ask/allowlist/full 行為與 headless 節點主機相同；拒絕的提示回傳 SYSTEM_RUN_DENIED。
  • Headless 節點主機上，system.run 受 exec 核准控制（~/.openclaw/exec-approvals.json）。

Exec 節點綁定

當有多個節點可用時，可以將 exec 綁定到特定節點。 這會設定 exec host=node 的預設節點（可按 agent 覆寫）。

全域預設：

openclaw config set tools.exec.node "node-id-or-name"

按 agent 覆寫：

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

取消設定以允許任意節點：

openclaw config unset tools.exec.node
openclaw config unset agents.list[0].tools.exec.node

權限對應表

節點可在 node.list / node.describe 中包含 permissions 對應表，以權限名稱為鍵（如 screenRecording、accessibility），布林值表示是否已授權（true = 已授權）。

Headless 節點主機（跨平台）

OpenClaw 可以執行 headless 節點主機（無 UI），連接到 Gateway WebSocket 並公開 system.run / system.which。適用於 Linux/Windows 或在伺服器旁執行最小節點的場景。

啟動：

openclaw node run --host <gateway-host> --port 18789

注意：

  • 仍需配對（Gateway 會顯示裝置配對提示）。
  • 節點主機將 node id、token、顯示名稱及 gateway 連線資訊儲存在 ~/.openclaw/node.json。
  • Exec 核准透過 ~/.openclaw/exec-approvals.json 在本機執行（參見 Exec 核准）。
  • macOS 上，headless 節點主機預設在本機執行 system.run。設定 OPENCLAW_NODE_EXEC_HOST=app 可透過伴隨應用程式的 exec 主機路由 system.run；加上 OPENCLAW_NODE_EXEC_FALLBACK=0 則要求應用程式主機可用，否則安全失敗。
  • Gateway WS 使用 TLS 時，加上 --tls / --tls-fingerprint。

Mac 節點模式

  • macOS 選單列應用程式以節點身分連接到 Gateway WS 伺服器（因此 openclaw nodes … 可對此 Mac 操作）。
  • 遠端模式下，應用程式會為 Gateway 埠開啟 SSH 隧道並連接到 localhost。
arrow_back
上一頁
Auth Monitoring
下一頁
Troubleshooting
arrow_forward