OpenClaw 節點設定指南：連接 macOS 與行動裝置

一個 node 是一個附屬裝置（macOS/iOS/Android/headless），它以 role: "node" 連接到 Gateway WebSocket（與 operators 使用相同的連接埠），並透過 node.invoke 公開指令介面（例如 canvas.*, camera.*, device.*, notifications.*, system.*）。協定細節請參考：Gateway protocol。

舊版傳輸方式：Bridge protocol（TCP JSONL；目前的 nodes 已棄用或移除）。

macOS 也可以在 node mode 下執行：選單列應用程式會連接到 Gateway 的 WS 伺服器，並將其本地的 canvas/camera 指令作為 node 公開（因此 openclaw nodes … 可以針對這台 Mac 運作）。

注意：

Nodes 是外圍設備，而不是 gateways。它們不執行 gateway 服務。
Telegram/WhatsApp/等訊息會降落在 gateway 上，而不是 nodes 上。
故障排除指南：/nodes/troubleshooting

配對與狀態

WS nodes 使用裝置配對。 Nodes 在 connect 期間會提供裝置身份；Gateway 會為 role: node 建立裝置配對請求。你可以透過 devices CLI（或 UI）進行核准。

快速 CLI：

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

如果 node 使用變更後的驗證詳細資訊（role/scopes/public key）重試，之前的待處理請求會被取代，並建立新的 requestId。在核准前請重新執行 openclaw devices list。

注意：

當裝置配對角色包含 node 時，nodes status 會將該 node 標記為 paired。
node.pair.*（CLI：openclaw nodes pending/approve/reject）是一個獨立的 gateway 擁有的 node 配對儲存區；它不會限制 WS connect 的握手過程。

遠端 Node 主機 (system.run)

當你的 Gateway 執行在一台機器上，而你希望指令在另一台機器上執行時，請使用 node host。模型仍然與 gateway 通訊；當選擇 host=node 時，gateway 會將 exec 呼叫轉發給 node host。

運作位置

Gateway host：接收訊息、執行模型、路由 tool calls。
Node host：在 node 機器上執行 system.run/system.which。
核准 (Approvals)：透過 ~/.openclaw/exec-approvals.json 在 node host 上強制執行。

核准注意事項：

經核准支援的 node 執行會綁定精確的請求上下文。
對於直接的 shell/runtime 檔案執行，OpenClaw 也會盡力綁定一個具體的本地檔案操作數，如果該檔案在執行前發生變更，則拒絕執行。
如果 OpenClaw 無法為解釋器/runtime 指令識別出精確的一個具體本地檔案，則會拒絕經核准支援的執行，而不是假裝擁有完整的 runtime 覆蓋。對於更廣泛的解釋器語義，請使用沙箱、獨立主機或明確的信任白名單/完整工作流。

啟動 node host (前景執行)

在 node 機器上：

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

透過 SSH 隧道連接遠端 Gateway (Loopback 綁定)

如果 Gateway 綁定到 loopback（gateway.bind=loopback，本地模式下的預設值），遠端 node hosts 無法直接連接。請建立 SSH 隧道並將 node host 指向隧道的本地端。

範例（node host -> gateway host）：

# Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# Terminal B: export the gateway token and connect through the tunnel
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。
在本地模式下，node host 會刻意忽略 gateway.remote.token / gateway.remote.password。
在遠端模式下，根據遠端優先級規則，gateway.remote.token / gateway.remote.password 是符合條件的。
如果設定了作用中的本地 gateway.auth.* SecretRefs 但未解析，node-host 驗證將失敗並關閉。
Node-host 驗證解析僅遵循 OPENCLAW_GATEWAY_* 環境變數。

啟動 node host (服務模式)

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

配對與命名

在 gateway host 上：

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

如果 node 使用變更後的驗證詳細資訊重試，請重新執行 openclaw devices list 並核准目前的 requestId。

命名選項：

在 openclaw node run / openclaw node install 使用 --display-name（會持久化在 node 的 ~/.openclaw/node.json 中）。
openclaw nodes rename --node <id|name|ip> --name "Build Node"（gateway 覆蓋設定）。

將指令加入白名單

執行核准是針對每個 node host 的。從 gateway 加入白名單項目：

openclaw approvals allowlist add --node &lt;id|name|ip&gt; "/usr/bin/uname"
openclaw approvals allowlist add --node &lt;id|name|ip&gt; "/usr/bin/sw_vers"

核准資訊儲存在 node host 的 ~/.openclaw/exec-approvals.json。

將 exec 指向 node

設定預設值（gateway 設定）：

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

或針對每個 session 設定：

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

設定完成後，任何帶有 host=node 的 exec 呼叫都會在 node host 上執行（受 node 白名單/核准限制）。

呼叫指令

低階（原始 RPC）：

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

對於常見的「提供 agent MEDIA 附件」工作流，存在更高階的輔助工具。

螢幕截圖 (Canvas 快照)

如果 node 正在顯示 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 會被拒絕）。

照片與影片 (node camera)

照片 (jpg)：

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>            # default: both facings (2 MEDIA lines)
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

注意：

Node 必須處於 foregrounded（前景）狀態才能執行 canvas.* 和 camera.*（背景呼叫會回傳 NODE_BACKGROUND_UNAVAILABLE）。
影片長度會被限制（目前為 <= 60s），以避免 base64 payload 過大。
Android 會在可行時提示 CAMERA/RECORD_AUDIO 權限；若權限被拒絕，則會失敗並顯示 *_PERMISSION_REQUIRED。

螢幕錄影 (nodes)

支援的 node 會提供 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 是否可用取決於 node 平台。
螢幕錄影限制在 <= 60s。
--no-audio 會在支援的平台上停用麥克風收音。
當有多個螢幕可用時，使用 --screen <index> 來選擇顯示器。

位置 (nodes)

當設定中的 Location 開啟時，node 會提供 location.get。

CLI 小幫手：

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

注意：

位置功能 預設為關閉。
「一律允許」需要系統權限；背景抓取則是盡力而為 (best-effort)。
回傳內容包含經緯度 (lat/lon)、精確度（公尺）以及時間戳記。

簡訊 (Android nodes)

當使用者授予 SMS 權限且裝置支援通訊功能時，Android node 可以提供 sms.send。

低階呼叫方式：

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

注意：

在該功能被公開之前，必須先在 Android 裝置上接受權限提示。
沒有通訊功能的純 Wi-Fi 裝置不會提供 sms.send。

Android 裝置與個人資料指令

當你啟用了對應的功能（capabilities）時，Android nodes 可以提供額外的指令家族（command families）。

可用的家族包含：

device.status, device.info, device.permissions, device.health
notifications.list, notifications.actions
photos.latest
contacts.search, contacts.add
calendar.events, calendar.add
callLog.search
sms.search
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}'

注意事項：

Motion 指令受限於裝置是否有對應的感應器。

系統指令 (node host / mac node)

macOS node 會開放 system.run、system.notify 以及 system.execApprovals.get/set。無介面（headless）的 node host 則會開放 system.run、system.which 和 system.execApprovals.get/set。

範例：

openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
openclaw nodes invoke --node <idOrNameOrIp> --command system.which --params '{"name":"git"}'

注意事項：

system.run 會在 payload 中回傳 stdout、stderr 和 exit code。
Shell 執行現在會透過 exec 工具搭配 host=node 進行；nodes 則維持作為明確 node 指令的直接 RPC 介面。
nodes invoke 不會開放 system.run 或 system.run.prepare；這些指令僅保留在 exec 路徑中。
system.notify 會遵循 macOS app 上的通知權限狀態。
無法辨識的 node platform 或 deviceFamily 中繼資料會使用保守的預設允許清單（allowlist），排除 system.run 和 system.which。如果你在未知的平台上確實需要這些指令，請透過 gateway.nodes.allowCommands 明確加入。
system.run 支援 --cwd、--env KEY=VAL、--command-timeout 以及 --needs-screen-recording。
對於 shell wrappers（如 bash|sh|zsh ... -c/-lc），request-scoped 的 --env 數值會被縮減至特定的允許清單（TERM, LANG, LC_*, COLORTERM, NO_COLOR, FORCE_COLOR）。
在允許清單模式下進行「永遠允許」的決定時，已知的 dispatch wrappers（env, nice, nohup, stdbuf, timeout）會保留內部的執行檔路徑而非 wrapper 路徑。如果拆解 wrapper 不安全，則不會自動建立允許清單項目。
在允許清單模式下的 Windows node hosts，透過 cmd.exe /c 執行的 shell-wrapper 需要經過核准（單純的允許清單項目不會自動允許 wrapper 形式）。
system.notify 支援 --priority <passive|active|timeSensitive> 和 --delivery <system|overlay|auto>。
Node hosts 會忽略 PATH 覆寫，並移除危險的啟動或 shell 鍵值（DYLD_*, LD_*, NODE_OPTIONS, PYTHON*, PERL*, RUBYOPT, SHELLOPTS, PS4）。如果你需要額外的 PATH 項目，請設定 node host 服務的環境變數（或將工具安裝在標準位置），而不是透過 --env 傳遞 PATH。
在 macOS node 模式下，system.run 受 macOS app 中的執行核准（Settings → Exec approvals）控管。詢問（Ask）、允許清單（allowlist）與完全允許（full）的行為與 headless node host 相同；被拒絕的提示會回傳 SYSTEM_RUN_DENIED。
在 headless node host 上，system.run 受執行核准控管（路徑為 ~/.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 映射。這個映射會以權限名稱作為 key（例如 screenRecording、accessibility），並使用布林值來表示（true 表示已獲得授權）。

無介面節點主機 (跨平台)

OpenClaw 可以執行無介面節點主機 (headless node host，沒有 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。
執行授權會在本地透過 ~/.openclaw/exec-approvals.json 強制執行（參考 Exec approvals）。
在 macOS 上，無介面節點主機預設會在本地執行 system.run。你可以設定 OPENCLAW_NODE_EXEC_HOST=app 讓 system.run 透過 companion app 執行；加上 OPENCLAW_NODE_EXEC_FALLBACK=0 則會強制要求使用 app host，如果無法使用則會直接失敗。
當 Gateway WS 使用 TLS 時，請加上 --tls / --tls-fingerprint。

Mac 節點模式

macOS 選單列 app 會作為節點連線到 Gateway WS 伺服器（因此 openclaw nodes … 可以對這台 Mac 運作）。
在遠端模式下，app 會為 Gateway 連接埠開啟 SSH 隧道並連線到 localhost。

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。