大数跨境
首页
>
OpenClaw Nodes
>

OpenClaw Nodes

OpenClaw Nodes 苏哲管理咨询
2026-09-26
16
导读：OpenClaw 节点是跨平台配套终端设备，以 node 角色连接网关，通过 node.invoke 暴露设备、系统、媒体等命令能力，分为 macOS 可视化节点与 Linux/Windows 无头节

编者摘要：OpenClaw 节点是跨平台配套终端设备，以 node 角色连接网关，通过 node.invoke 暴露设备、系统、媒体等命令能力，分为 macOS 可视化节点与 Linux/Windows 无头节点主机。核心作用是承接网关转发的远程执行指令，实现跨设备命令运行、本地模型推理、会话托管等能力。节点需完成设备配对方可授权，支持 SSH 自动审批、可信网段白名单审批两种免手动审批模式。所有系统执行命令受节点本地 SQLite 执行白名单管控，审批后固化执行计划，禁止篡改参数。支持节点托管 MCP 服务、本地技能、Claude/Codex 会话能力，可开启容器隔离会话运行。部署分为前台临时运行与后台系统服务两种模式，网关升级需遵循先网关、后节点的顺序。高危相机、录屏、短信等能力需网关配置显式白名单开启，保障设备调用安全可控。

10个主要问题问与答

Q1：OpenClaw 节点和网关的核心区别？A：网关负责消息路由、模型运行、权限管控；节点是外设终端，仅负责执行网关转发的命令，不运行网关服务。

Q2：Mac 设备能否同时运行菜单栏节点和CLI无头节点？A：不能。Mac 菜单栏App已内置节点运行时，双开将生成两个设备身份，引发连接冲突。

Q3：节点配对的三种审批方式是什么？A：手动CLI审批、网关SSH校验自动审批、配置可信CIDR网段自动审批（仅首次配对生效）。

Q4：为什么审批后修改命令参数执行失效？A：审批会固化 systemRunPlan 执行计划，后续修改命令、工作目录等参数不会生效，保障执行安全。

Q5：无头节点主机的核心使用场景？A：用于 Linux/Windows 服务器、编译机、NAS 等无UI设备，实现远程命令执行与自动化部署。

Q6：节点托管MCP服务的配置要点？A：MCP配置写在节点openclaw.json，无需网关配置，修改后重启节点生效，无需重新配对。

Q7：节点系统执行命令的权限控制逻辑？A：双重校验：节点本地白名单放行 + 网关命令策略允许，高危能力需手动配置开启。

Q8：网关与节点的正确升级顺序？A：先升级网关，再批量升级节点，仅支持N-1版本兼容，老旧版本需离线升级。

Q9：如何实现节点工作会话的安全隔离？A：开启容器隔离模式，会话独立容器运行，仅挂载必要工作目录，隔离主机资源。

Q10：节点离线后重新连接需要重新配对吗？A：不需要。配对信息持久化存储，仅撤销节点角色、令牌不匹配时才需重新配对。

附录 OpenClaw Nodes and Media 文档

  • Node
    节点
  • Gateway
    网关
  • Pairing
    设备配对
  • node‑invoke
    节点调用 RPC
  • node host
    节点主机（执行远端命令的运行实例）
  • MCP
    Model Context Protocol
  • worker session
    工作会话


NODES AND MEDIA｜节点与媒体

Nodes｜节点

节点是配套设备（macOS /iOS/watchOS / Android / 无 UI 无头实例），以role: "node"角色连接网关，通过node.invoke对外暴露命令接口（例如camera.*、device.*、notifications.*、system.*）。绝大多数节点通过网关操作端口的 WebSocket 通信；Apple Watch 直连节点为适配 watchOS 系统限制，使用同端口下带签名的 HTTPS 轮询。 协议详情：https://docs.openclaw.ai/gateway/protocol

macOS 也可运行节点模式：菜单栏 App 作为一个节点连接网关 WebSocket 服务，因此可以直接用openclaw nodes …操作本机。该 App 原生提供小组件面板、相机、屏幕、通知、设备控制命令，与openclaw node run复用同一套节点命令面。

⚠️ 不要在同一台 Mac 再启动第二个 CLI 节点：App 内部已经运行节点主机运行时，独占网关连接与节点身份。

节点属于外设终端，不是网关：节点本身不运行网关服务；Telegram、WhatsApp 等消息通道全部运行在网关，不在节点上。

故障排查手册：https://docs.openclaw.ai/nodes/troubleshooting

Pairing + status｜配对与状态

节点使用设备配对机制。节点连接时出示签名设备身份，网关生成role: node的设备配对请求。可通过 CLI/UI 完成审批。 Apple Watch 直连模式使用管理员生成的短期专用设置码完成审批，仅开放受限安全命令集；后续扩展能力仍需要正常配对审批流程。

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

openclaw nodes status
openclaw nodes describe --node <idOrNameOrIp>

待处理配对请求，在设备最后一次重试 5 分钟后过期；设备持续重连会保持同一个待处理请求与requestId，不会反复生成新请求。完整配对生命周期：https://docs.openclaw.ai/gateway/pairing。

如果节点重连时变更鉴权信息（角色 / 作用域 / 公钥），旧待处理请求会被取代，生成全新requestId；旧请求触发device.pair.resolved事件，审批前务必重新执行openclaw devices list。

当设备配对记录包含node角色，nodes status标记节点状态为paired（已配对）。

原生 Mac 节点可在「设置 → 权限 → 活跃计算机检测」开启聚合物理输入检测，需要开启系统辅助功能权限。网关将最新活跃的 Mac 标记为active，给智能体稳定节点 ID 提示，优先向该节点推送连接告警，超时后再降级兜底。 参考：https://docs.openclaw.ai/nodes/presence

设备配对记录是持久化的角色授权契约。令牌轮换在契约内部完成，不能通过令牌轮换把节点提升为配对未授予的角色。

node.pair.*（CLI：openclaw nodes pending/approve/reject/remove/rename）管理该配对设备记录上节点允许的命令与能力集合。传输鉴权、节点能力集合全部由设备配对体系管理，不存在独立的节点配对存储。

openclaw nodes remove --node <id|name|ip>：在配对设备存储中撤销该设备的node角色并断开节点会话。

  • 混合角色设备：保留设备条目，仅删除 node 角色；
  • 仅 node 角色设备：整条记录删除。
  • operator.pairing
    权限可以删除其他设备的 node 角色；设备自身撤销本机 node 角色，若该设备是混合角色，还需要operator.admin权限。

审批权限范围，由待处理请求声明的命令决定：

  1. 无命令请求：operator.pairing
  2. 普通非执行类节点命令：operator.pairing+ operator.write
  3. system.run
    / system.run.prepare/ system.which：operator.pairing+ operator.admin

Version skew and upgrade order｜版本差异与升级顺序

网关 WebSocket 支持 N‑1 协议窗口的已认证节点客户端。例如 v4 网关，可以接受 v3 节点连接，前提连接声明role: "node"与client.mode: "node"；操作员、UI 会话必须使用当前最新协议。

集群升级顺序：先升级网关，再逐个升级节点。 N‑1 版本旧节点升级期间仍然可见、可管理；网关输出日志legacy node protocol accepted并提示升级。配对、设备鉴权、命令白名单、执行审批继续生效；插件能力命令对旧节点隐藏，必须升级到当前协议版本才会暴露。比 N‑1 更老的节点，必须离线升级后才能重连。

Apple Watch HTTPS 直连传输强制要求当前协议版本；启用直连模式前，手表 App 必须和网关同步更新。

Remote node host (system.run)｜远程节点主机（命令执行）

网关运行在一台机器，希望命令在另一台机器执行，就使用节点主机。模型仍然和网关交互；当选定host=node时，网关把 exec 调用转发给节点主机。

角色
职责
网关主机
接收消息、运行模型、路由工具调用
节点主机
在节点机器执行system.run/ system.which
审批控制
在节点主机本地 SQLite：~/.openclaw/state/openclaw.sqlite#exec_approvals_config强制执行

审批绑定请求上下文：执行流程会先生成不可修改的systemRunPlan；审批通过后网关转发这份已经固化的计划，不会使用后续调用方修改后的命令、工作目录、会话参数；执行前会二次校验工作目录。 对于直接文件执行，OpenClaw 会尽力绑定一个本地文件；如果执行前文件发生变更，则拒绝运行。 如果无法唯一确定本地文件，直接拒绝审批执行，而不是假装完整解释器支持。需要宽泛解释器能力，建议使用沙箱、独立主机、显式可信白名单或完整工作流。

Gateway deployments that cannot host nodes｜网关无法承载节点的部署场景

网关浏览器访问可以正常工作，但节点接入会失败。部署节点前执行openclaw doctor做前置检查：

  1. 机器身份认证
    Tailscale 身份头不能用于节点角色鉴权。网关gateway.auth.mode: "trusted‑proxy"模式下，节点不能复用代理身份头。要使用共享 token，切换为 token 模式，配置gateway.auth.token引用密钥；trusted‑proxy 模式禁止混合 token 配置。trusted‑proxy 网关仅允许回环 / 直调用方使用gateway.auth.password。 文档：https://docs.openclaw.ai/gateway/trusted-proxy-auth#mixed-token-configuration
  2. 节点接入 URL
    网关绑定gateway.bind: "loopback"时，必须提前配置 Tailscale Serve、gateway.remote.url或plugins.entries.device‑pair.config.publicUrl，否则openclaw devices join‑code报错Gateway is only bound to loopback。 修复：设置gateway.bind=lan/ 开启 tailscale serve / 配置 publicUrl。
  3. 节点配对插件
    接入码、openclaw connect依赖内置device‑pair插件；如果被禁用，设置plugins.entries.device‑pair.enabled: true，重启网关。
  4. 设备会话运行时
    配对设备运行时支持内置 OpenClaw 运行时、显式授权的 Codex 远程执行；ACPX 路由不能调度到配对设备。Codex 需要配置codex.exec‑server.stdio.v1写入gateway.nodes.commands.allow，同时满足配对与调用审批。运行时策略写在 provider/model 路由，不要写在 agent 全局运行时配置。多智能体部署需要设置agents.ownership: "explicit"。 参考：https://docs.openclaw.ai/plugins/codex-harness#run-codex-on-a-paired-devicehttps://docs.openclaw.ai/gateway/config‑agents#runtime‑policy
  5. 边缘反向代理
    反向代理 / 访问边缘前置网关时，节点在接入码请求、主网关 WebSocket、worker WebSocket 都要通过边缘鉴权。/__openclaw__/worker必须开启 WebSocket 升级。也可以将/j/*、/__openclaw__/worker跳过边缘身份鉴权，这两个路由自带短期凭证校验。 文档：https://docs.openclaw.ai/gateway/protocol#worker‑role‑and‑closed‑protocol

Cloudflare Access 前置网关示例

  1. 在 Cloudflare Zero Trust 创建 Access 服务令牌，复制 Client ID、Client Secret
  2. 在保护网关的 Access 应用上添加 Service Auth 策略；如果/j/*、/__openclaw__/worker是独立应用，两处都配置策略
  3. 节点侧环境变量连接： 
export CF_ACCESS_CLIENT_ID="<client-id>"
export CF_ACCESS_CLIENT_SECRET="<client-secret>"
openclaw connect https://gateway.example/j/<code> --service

网关配置字段：gateway.cloudflareAccess.clientId、gateway.cloudflareAccess.clientSecret，接收密钥引用。环境变量会作为 SecretRef 密钥引用保存，不会明文存储。节点服务配置写入托管环境文件，不会硬编码进 launchd/systemd/ 任务计划。凭证绑定网关域名，不跟随重定向。明文http://、ws://会直接拒绝配对；本机回环、私有网络明文不受限制。

Start a node host (foreground)｜前台启动节点主机

节点机器执行：

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

一键粘贴配对：在控制 UI 设备页面生成节点主机设置链接，复制命令在节点执行：

openclaw node run --pair "oc-pair://<setup-code>"

链接单次有效，10 分钟过期，自带端点、启动令牌、TLS、证书指纹。显式网关参数优先级高于--pair。

⚠️配对不会预先批准命令执行；第一次system.run仍然走正常待审批 / SSH 校验流程。 文档：https://docs.openclaw.ai/gateway/pairing#one‑paste‑node‑pairing

node run支持参数：--pair、--context‑path网关 WebSocket 路径、--tls、--tls‑fingerprint <sha256>、--node‑id（仅修改客户端实例 ID，不重置配对）。 macOS：--share‑installed‑apps开启device.apps能力，默认关闭；--no‑share‑installed‑apps关闭。

Remote gateway via SSH tunnel (loopback bind)｜SSH 隧道访问回环绑定网关

网关使用gateway.bind=loopback（本地默认），外部节点不能直连，需要 SSH 隧道转发。

示例：节点主机 → 网关主机

# 终端A（保持运行）本地18790转发到网关127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# 终端B：设置网关token，通过隧道连接
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

说明：

  1. openclaw node run
    支持 token /password 鉴权；优先读取环境变量OPENCLAW_GATEWAY_TOKEN/ OPENCLAW_GATEWAY_PASSWORD；其次读取配置文件。
  2. 本地模式节点主机忽略gateway.remote.token/password；远程模式按远程优先级规则读取。
  3. 如果配置的 SecretRef 密钥无法解析，节点主机鉴权直接失败。
  4. 节点主机鉴权只识别OPENCLAW_GATEWAY_*系列环境变量。

Start a node host (service)｜以系统服务启动节点主机

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

node install支持：--context‑path、--tls、--tls‑fingerprint、--node‑id、--share‑installed‑apps/ --no‑share‑installed‑apps、--runtime <node|bun>（默认 node；bun 需要≥1.4 版本，显式开启）、--force重装。 配套命令：node status、node stop、node uninstall。

Pair + name｜配对与命名

网关主机执行：

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

节点重连变更鉴权信息，务必重新 list 再审批新 requestId。

两种命名方式：

  1. 启动参数--display‑name：持久化写入 SQLite 机器状态，跟随客户端实例、网关连接元数据。
  2. 网关侧重命名：openclaw nodes rename --node <id|name|ip> --name "Build Node"

Node‑hosted MCP servers｜节点侧托管 MCP 服务

MCP 配置写在节点机器的 openclaw.json，不是网关配置

{
  nodeHost: {
    mcp: {
      servers: {
        localDocs: {
          command: "npx",
          args: ["-y", "@modelcontextprotocol/server-filesystem", "/srv/docs"],
          toolFilter: {
            include: ["read_*", "search"],
          },
        },
        internalApi: {
          url: "https://mcp.internal.example/mcp",
          transport: "streamable‑http",
          headers: {
            Authorization: "Bearer ${INTERNAL_MCP_TOKEN}",
          },
        },
      },
    },
  },
}

无头节点主机启动 MCP 服务，上报工具描述；工具调用通过mcp.tools.call.v1回传到节点，网关不需要 MCP 配置与 JS 插件。v1 路径不支持 OAuth 类型 MCP 服务。

即使没有配置 MCP 服务，新版节点配对时也会声明mcp.tools.call.v1命令族；旧版本节点升级后需要一次能力升级审批。增删改 MCP 服务不需要重新配对，命令族不变。修改配置后重启节点进程才生效，节点不会监听配置文件变更。

MCP 服务工具列表变更会实时更新节点工具目录；传输断开 / 会话过期，节点撤回对应工具，带退避重连；失败调用不会自动重放，重连发布工具后新调用可正常执行。

网关全局开关：

  • gateway.nodes.pluginTools.enabled: false
    ：完全忽略所有节点上报的插件工具；
  • gateway.nodes.commands.deny: ["mcp.tools.call.v1"]
    ：直接拒绝该命令执行。

Node‑hosted skills｜节点托管技能

技能文件放置节点机器技能目录：默认~/.openclaw/skills；环境变量OPENCLAW_HOME、OPENCLAW_STATE_DIR、OPENCLAW_CONFIG_PATH修改路径；OPENCLAW_STATE_DIR优先级最高。

无头节点主机连接后发布合法SKILL.md；仅当节点在线，网关才把技能纳入智能体快照。技能目录名必须和 SKILL.md frontmatter 中 name 字段完全一致。

节点初始 node 角色配对已经授权技能发布；增删修改技能文件不需要重新配对，修改后重启节点主机生效，节点不监听目录变更。

节点技能定位使用node://.../SKILL.md；file_fetch不支持 node:// 定位符，可以通过exec host=node+ workdir 读取。执行要求节点拥有system.run审批，智能体 exec 策略允许host=node，否则技能不会进入快照。

节点本地关闭技能发布：nodeHost.skills.enabled: false网关全局关闭所有节点技能：gateway.nodes.allowSkills: false

Headless identity state｜无头节点身份存储

无头节点在 SQLite 中维护 3 套独立状态（~/.openclaw/state/openclaw.sqlite）

  1. config_machine_state
    ，key=nodeHost.config：客户端实例 ID、显示名、网关连接元数据
  2. device_identities
    ，key=primary：签名设备密钥对、加密设备 ID
  3. device_auth_tokens
    ：按加密设备 ID + 角色存储配对鉴权令牌

网关使用加密设备 ID做配对和路由；--node‑id只是连接元数据，修改它不会重置配对。 旧版文件identity/device.json、identity/device‑auth.json为迁移遗留；停止节点，运行openclaw doctor --fix导入数据并删除旧文件。 文档：https://docs.openclaw.ai/cli/node#identity‑and‑pairing‑state

Allowlist the commands｜执行命令白名单配置

exec 审批按节点主机独立存储。在网关侧添加白名单：

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

白名单持久化存储在节点主机 SQLite：~/.openclaw/state/openclaw.sqlite#exec_approvals_config

Point exec at the node｜将 exec 执行指向节点

网关全局配置默认：

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

单次会话覆盖：

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

设置完成后，host=node的 exec 调用会在节点主机执行，受节点白名单、审批控制。

host=auto不会自动选中节点；沙箱运行时开启时 auto 禁止隐式切到 node；沙箱环境下要使用节点执行，必须显式指定host=node或修改全局 tools.exec.host。

参考文档： https://docs.openclaw.ai/cli/node https://docs.openclaw.ai/tools/exechttps://docs.openclaw.ai/tools/exec‑approvals

Local model inference｜节点本地模型推理

桌面 / 服务器节点上运行 Ollama 服务，节点对外暴露模型；智能体通过 Ollama 插件node_inference工具访问，网关不需要网络直连 Ollama。 文档：https://docs.openclaw.ai/providers/ollama#node‑local‑inference

Codex sessions and transcripts｜Codex 会话与会话记录

codex 插件可在无头节点 /macOS 节点暴露非归档 Codex 会话目录。supervision.enabled不再控制目录注册，仅控制智能体侧监控工具。插件配置sessionCatalog.enabled: false关闭目录，不关闭 provider/harness。插件必须两端都启用；仅网关开启，不能读取远端节点 Codex 状态。

节点对外提供只读命令：codex.appServer.threads.list.v1、codex.appServer.thread.turns.list.v1；本机存在 Codex CLI 会追加codex.terminal.resume.v1。新命令出现时需要做一次配对能力升级审批。

UI 会话侧边栏出现 Codex 分组；默认按项目文件夹分组；可使用 UI 按钮扁平化展示。选中会话读取历史使用分页游标，不会一次性加载全部记录。可以在节点本机终端恢复会话；终端 PTY 中继是 codex 插件受控能力，不是任意节点命令执行。

会话继续聊天能力需要全套命令 +operator.admin；仅具备读命令只能查看会话，不能继续对话。配对节点不支持归档。网关本机会话可以创建模型隔离的聊天分支；归档操作要确认无其他客户端占用；活跃会话不能分支归档。 文档：https://docs.openclaw.ai/plugins/codex‑supervision

Claude sessions and transcripts｜Claude 会话与记录

内置 anthropic 插件默认发现网关、配对节点上未归档 Claude CLI / Claude Desktop 会话。配置plugins.entries.anthropic.config.sessionCatalog.enabled: false关闭目录功能，不关闭模型能力。

macOS 节点对外：anthropic.claude.sessions.list.v1、anthropic.claude.sessions.read.v1；本机有 Claude CLI 则追加anthropic.claude.terminal.resume.v1，支持在节点本机终端恢复会话。新命令需要配对升级审批。

目录合并 CLI 项目索引、JSONL 回退解析；Desktop 元数据优先级高于 CLI。读取大会话使用字节偏移游标分页，不会一次性全量加载。

权限控制：

  • sessions.catalog.list/read
    ：operator.read
  • sessions.catalog.continue/archive
    ：operator.write

多用户网关：非 admin 用户仅能看到创建者 ID 匹配自己网关档案的会话；无归属的主机会话对普通用户隐藏。> 这是可信域内权限隔离，不是敌对用户强隔离；强隔离需要独立网关 / 独立 agent。 文档：https://docs.openclaw.ai/concepts/multi‑user

网关本机 Claude CLI 会话支持聊天面板导入，使用--fork‑session保留原始记录。

无头节点开启 Claude 会话继续能力（节点本地配置，网关不能远程开启）

{
  nodeHost: {
    agentRuns: {
      claude: { enabled: true },
    },
  },
}

开启后节点发布agent.cli.claude.run.v1；仍然受节点 exec 审批策略约束。

v1 限制：不继承网关 MCP、网关技能；不支持附件图片；macOS 菜单栏节点暂不支持该能力，只能查看会话。

Host OpenClaw sessions｜节点托管 OpenClaw 工作会话

macOS 菜单栏 App、无头节点主机可以开启节点本地会话托管：

{
  nodeHost: {
    workerRuns: { enabled: true },
  },
}

⚠️警告：只能在可信机器开启；该配置绑定设备，不是绑定个人账号；原有会话鉴权逻辑不变。 修改配置后重启 App / 节点服务。同一 Mac 不要同时运行菜单栏 App 和第二个 CLI 节点。

会话调度逻辑：

  1. 第一次会话派发，节点从网关下载密封 worker 制品，校验哈希；制品自带全部 JS 依赖，不 npm 安装包。后续复用上不变的制品。
  2. 也可以一键启用服务 + 会话托管：openclaw connect --service --session‑host
  3. UI 新建会话时，操作员可以选择设备或 Auto 自动调度；网关创建会话专属工作树，设备上线后才下发第一轮请求。不会自动浏览节点文件系统。

设备元数据展示网关下发 worker 版本；制品校验失败显示worker missing告警，新建会话重新拉取。 旧版本节点可见，但会话选择器置灰不可用；升级 OpenClaw，重启节点。

并发槽位：默认每个 CPU 核心一个 worker 槽位；配置nodeHost.workerRuns.capacity修改。槽位满时新会话等待最多 10 秒，老会话、状态查询、取消不受影响。

会话选择器逻辑：

  • 只有已配对、在线、workerRuns 可用、有空闲槽位的设备才可以选中；
  • Codex 远程执行不占用 worker 槽位，只要求命令在 invocableCommands；
  • 设备离线、版本过低、满载，UI 显示明确原因。

Auto自动调度：worker 会话优先选空闲槽最多的设备；不消耗槽位的运行时选择 deviceID 最小设备。选中设备不可用会重试最多 3 台备选主机；全部失败返回明确错误。

节点断开后：配对记录保留上一次 v6 托管许可；离线设备 UI 标记unavailable；网关重启后显示设备离线，节点重连后恢复可用。设备断开 14 天后，旧 worker 环境视为失效，会话做环境回收；配对关系保留，重连重新分配环境。删除 node 角色会销毁会话环境。

UI 行为：设备离线默认等待，不放弃会话 / 工作区；Continue on Gateway…是破坏性操作，网关侧继续执行，设备上未同步文件、运行中任务会丢失。 文档：https://docs.openclaw.ai/providers/anthropic#claude‑sessions‑across‑computers

Isolate hosted worker sessions in containers｜容器隔离 worker 会话

节点本地配置，网关无法静默降级绕过隔离：

{
  nodeHost: {
    workerRuns: {
      enabled: true,
      isolation: "container",
      // containerImage: "registry.example.com/openclaw/node:22‑slim",
    },
  },
}
  • 默认isolation: "none"直接进程运行；
  • 容器隔离支持 Linux/macOS；Windows 不支持；
  • 节点需要 Docker/Podman 引擎；节点启动、创建容器前都会校验引擎；引擎异常直接启动失败，不会降级裸进程。
  • 默认镜像node:22‑slim；离线环境提前预拉镜像。镜像必须内置 Node.js≥22。

容器挂载：仅两个只读 / 读写挂载：worker 制品根目录（只读）、会话工作目录（读写），使用主机绝对路径。不会挂载其他主机目录。容器使用主机网络，网关地址不能写 127.0.0.1（容器内部回环），要使用容器网络可达地址。自定义 CA 证书文件必须放在已挂载路径内。浏览器相关能力在容器隔离模式不可用。

取消会话会直接销毁容器；节点异常退出容器可能残留；使用 systemd 等守护进程保持节点持续运行，下次启动自动清理标签匹配的孤儿容器。

OpenCode and Pi sessions｜OpenCode、Pi 会话目录

内置 OpenCode、ACPX 插件同样可以在网关、配对节点读取会话目录。

  • 安装 opencode CLI，节点发布opencode.sessions.list.v1/ opencode.sessions.read.v1；
  • Pi 会话目录存在，节点发布acpx.pi.sessions.list.v1/ acpx.pi.sessions.read.v1； 本机存在对应 CLI 追加 terminal.resume 终端恢复命令，使用受控 PTY 中继，不暴露任意命令执行。新命令需要配对升级审批。 目录开关在 WebUI 配置‑插件。

Terminal file uploads｜终端文件上传

UI 可以拖拽文件到配对节点终端。节点对外提供管理员权限命令terminal.upload，需要配对升级审批。

  • 单文件上限 16MiB；上传到节点临时目录；返回 shell 可引用路径，不会自动执行。
  • 支持 POSIX shell、PowerShell、Windows Git Bash；不支持无法推断引号规则的 shell；cmd.exe 路径含%、!会拒绝。Windows 原生 cmd 限制建议使用 WSL 节点主机。

Invoking commands｜命令调用

底层原始 RPC 调用示例：

openclaw nodes invoke --node <idOrNameOrIp> --command device.info --params '{}'

nodes invoke禁止直接调用system.run、system.run.prepare；系统执行必须走exec host=node工具链路。

长流式节点命令使用增量node.invoke.progress事件；携带 invokeID、序列号、UTF‑8 片段；网关保证顺序投递；最终返回node.invoke.result。支持非活动超时、硬超时；调用方取消发出node.invoke.cancel，节点终止对应进程树。

Command policy｜节点命令策略

节点命令调用必须过两道关卡：

  1. 节点连接元数据connect.commands声明该命令；
  2. 网关基于平台 + 审批的允许列表包含该命令。

网关策略是权限上限；节点 App 本身也要实现该命令，才真正可用。Android 移动 UI 命令需要无障碍权限；桌面computer.act需要电脑控制权限。macOS 官方菜单栏 App 不会开启全部 macOS 平台默认命令。

高危隐私命令，即使节点声明，也需要网关显式配置gateway.nodes.commands.allow才能启用： camera.snap、camera.clip、camera.ptz.control、desktop.stream、screen.record、contacts.add、calendar.add、reminders.add、health.summary、sms.send、sms.search。 gateway.nodes.commands.deny优先级最高，覆盖 allow 与平台默认。

节点修改自身声明命令集合后，需要重连；查看openclaw nodes pending，执行openclaw nodes approve <requestId>完成能力升级持久化。

Config (openclaw.json)｜节点相关网关配置示例

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
        sshVerify: true,
      },
      pluginTools: {
        enabled: true,
      },
      commands: {
        allow: ["camera.snap", "desktop.stream", "screen.record"],
        deny: ["camera.clip"],
      },
    },
  },
  tools: {
    exec: {
      host: "node",
      security: "allowlist",
      node: "build-node",
    },
  },
}

单智能体覆盖 exec 节点配置：

{
  agents: {
    entries: {
      main: {
        default: true,
        tools: { exec: { node: "build-node" } },
      },
    },
  },
}

macOS widget panel｜macOS 小组件画布

openclaw nodes canvas present --node <idOrNameOrIp>
openclaw nodes canvas hide --node <idOrNameOrIp>
openclaw nodes canvas navigate "/__openclaw__/canvas/documents/<document-id>/index.html" --node <idOrNameOrIp>
  • canvas present
    支持--x/--y/--width/--height位置参数；
  • agent 侧工具路径：https://docs.openclaw.ai/tools/show‑widget，presentation.target: "node_panel"；
  • A2UI 仪表盘走 Web 页面，不走 canvas 节点命令。

Photos + videos (node camera)｜节点相机拍照录像

拍照（jpg）

openclaw nodes camera list --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp>
openclaw nodes camera snap --node <idOrNameOrIp> --facing front
openclaw nodes camera snap --node <idOrNameOrIp> --facing both
openclaw nodes camera snap --node <idOrNameOrIp> --device-id <id> --max-width 1200 --quality 0.9 --delay-ms 2000

视频（mp4）

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

⚠️相机调用节点必须在前台；后台调用返回NODE_BACKGROUND_UNAVAILABLE。平台会限制最大时长；agent 工具侧上限 5 分钟，节点本身会施加更严格限制。Android 需要相机、录音权限。

Screen recordings (nodes)｜屏幕录制

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

支持--screen <index>选择多显示器；同样时长上限 5 分钟，受平台限制。

Location (nodes)｜定位

节点设置开启定位才暴露location.get

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

默认关闭；需要系统位置权限；后台获取尽力而为；返回经纬度、精度、时间戳。

SMS (Android nodes)｜安卓节点短信

短信相关命令属于高危，必须网关配置 allow 才可以调用，App 权限和网关策略相互独立。 仅读取搜索：

{
  gateway: {
    nodes: {
      commands: { allow: ["sms.search"] },
    },
  },
}

发送短信需要额外加入sms.send到 allow。

底层调用示例：

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

Device and personal data commands｜设备与个人数据命令集

iOS/Android 提供大量只读设备、联系人、日历、照片、运动传感器命令；部分写入命令需要网关 allow。 macOS headless 节点默认不开启device.apps，需要--share‑installed‑apps开启。

示例调用：

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

System commands (node host /mac node)｜系统执行命令

macOS 节点、无头节点主机暴露system.run.prepare、system.run、system.which；macOS 额外有system.notify。

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

重要：nodes invoke不能调用 system.run；全部走 exec 工具链路。exec 会固化systemRunPlan，审批后不会使用后续修改的参数。 shell 执行时环境变量会做严格过滤；PATH 不能通过 env 传入，需要配置节点服务环境。Windows allowlist 模式下 cmd.exe 包装调用需要单独审批。 macOS 菜单栏 App 的 system.run 在 App 设置的执行审批页面控制；无头节点走本地 SQLite。 macOS 无头节点默认本地执行；环境变量OPENCLAW_NODE_EXEC_HOST=app强制走菜单栏 App 执行。

Exec node binding｜绑定 exec 到固定节点

多节点场景，可以全局 / 单 agent 绑定默认 exec 节点；绑定节点离线直接报错，不会自动故障转移到其他节点。

# 设置全局默认
openclaw config set tools.exec.node "node-id-or-name"
# 取消绑定
openclaw config unset tools.exec.node
openclaw config unset 'agents.entries.main.tools.exec.node'

Permissions map｜权限映射

node.list/node.describe返回permissions字段，key 为权限名，布尔值代表是否授予（screenRecording、accessibility、location 等）。

Headless node host (cross‑platform)｜跨平台无头节点主机

无头节点主机无 UI，连接网关 WebSocket，提供 system.run 执行，适合 Linux/Windows 服务部署。

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

仍然需要配对；身份、客户端实例、鉴权 token 为三套独立存储；exec 审批存储本地 SQLite；TLS 网关使用--tls --tls‑fingerprint。

Mac node mode｜Mac 节点模式

Mac 菜单栏 App 作为节点连接网关 WebSocket，openclaw nodes命令直接操作本机。远程模式下 App 自动建立 SSH 隧道，连接本机localhost。

【声明】内容源于网络
0
0
苏哲管理咨询
为企业及组织提供AI+战略、数智化转型咨询及观点、建议等
内容 2245
粉丝 0
苏哲管理咨询 为企业及组织提供AI+战略、数智化转型咨询及观点、建议等
总阅读50.3k
粉丝0
内容2.2k