节点

​

配对 + 状态

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

• nodes status 会在节点的设备配对角色包含 node 时将其标记为 paired。
• 已连接的原生 Mac 可以选择接收来自 设置 -> 权限 -> 活跃电脑检测 的合并物理输入活动。还需要启用辅助功能权限。网关会将最新的、符合条件的 Mac 标记为 active，为代理提供稳定的 node-id 提示，并在延迟回退之前将节点连接提醒路由到那里。有关设置、隐私、时序和故障排查，请参见 活跃电脑状态。
• 设备配对记录是持久化的已批准角色契约。令牌轮换始终发生在该契约之内；它不能将已配对节点升级为配对批准未曾授予的角色。
• node.pair.*（CLI：openclaw nodes pending/approve/reject/remove/rename）是一个独立的、由网关拥有的节点配对存储，用于跟踪节点在重新连接期间已批准的命令/能力范围。它不会控制传输认证——设备配对才会控制。
• openclaw nodes remove --node <id|name|ip> 会移除一个节点配对。对于由设备支持的节点，它会撤销已配对设备存储中的该设备 node 角色，并断开该设备的 node-role 会话：混合角色设备会保留其记录行，只会失去 node 角色，而仅节点设备的记录行会被删除。它还会清除独立节点配对存储中的任何匹配条目。operator.pairing 可以移除其他设备上的非 operator 节点记录；设备令牌调用方若要撤销其在混合角色设备上的自身 node 角色，则还需要 operator.admin。
• 批准范围遵循待处理请求中声明的命令：
  • 无命令请求：operator.pairing
  • 非 exec 节点命令：operator.pairing + operator.write
  • system.run / system.run.prepare / system.which：operator.pairing + operator.admin

​

版本偏移与升级顺序

​

远程节点主机（system.run）

• 基于批准的 node 运行会绑定精确的请求上下文。exec 路径会在批准前准备一个规范化的 systemRunPlan；一旦获批，gateway 会转发该已存储的计划，而不是后续调用者编辑过的命令/cwd/session 字段，并且会在运行前重新验证工作目录。
• 对于直接的 shell/运行时文件执行，OpenClaw 还会尽最大努力绑定一个具体的本地文件操作数，并在执行前如果该文件发生变化则拒绝运行。
• 如果 OpenClaw 无法为解释器/运行时命令精确识别出一个具体的本地文件，则会拒绝基于批准的执行，而不是假装覆盖了完整的运行时语义。对于更广泛的解释器语义，请使用沙箱、独立主机，或显式受信任的允许列表/完整工作流。

​

启动 node 主机（前台）

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

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

​

通过 SSH 隧道连接远程 gateway（回环绑定）

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

# 终端 B：导出 gateway 令牌并通过隧道连接
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "构建节点"

• openclaw node run 支持令牌或密码认证。
• 优先使用环境变量：OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD。
• 配置回退项是 gateway.auth.token / gateway.auth.password。
• 在本地模式下，node 主机会刻意忽略 gateway.remote.token / gateway.remote.password。
• 在远程模式下，gateway.remote.token / gateway.remote.password 按远程优先级规则可用。
• 如果已配置但未解析的活动本地 gateway.auth.* SecretRefs，node 主机认证会失败关闭。
• node 主机认证解析只接受 OPENCLAW_GATEWAY_* 环境变量。

​

启动 node 主机（服务）

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

​

配对 + 命名

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

• --display-name on openclaw node run / openclaw node install（会与客户端实例 ID 和网关连接元数据一起持久保存到共享的 node_host_config SQLite 行中）。
• openclaw nodes rename --node <id|name|ip> --name "构建节点"（网关覆盖）。

​

节点托管的 MCP 服务器

{
  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}",
          },
        },
      },
    },
  },
}

​

节点托管技能

​

无头身份状态

• ~/.openclaw/state/openclaw.sqlite（node_host_config）：客户端实例 ID、显示名称以及 Gateway 连接元数据。
• ~/.openclaw/state/openclaw.sqlite（device_identities，键 primary）：已签名的设备密钥对以及派生出的加密设备 ID。
• ~/.openclaw/state/openclaw.sqlite（device_auth_tokens）：按加密设备 ID 和角色键控的已配对设备认证令牌。

​

允许命令加入白名单

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

​

将 exec 指向 node

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>

• Node 主机 CLI
• Exec 工具
• Exec 审批

​

本地模型推理

​

Codex 会话和转录

​

Claude 会话和转录

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

​

OpenCode 和 Pi 会话

​

终端文件上传

​

调用命令

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

​

命令策略

1. 该节点必须在其经过身份验证的连接元数据（connect.commands）中声明该命令。
2. 网关基于平台和审批得出的允许列表必须包含该已声明的命令。

​

配置（openclaw.json）

{
  gateway: {
    nodes: {
      // 从受信任网络（CIDR 列表）自动批准首次节点配对。
      // 未设置时禁用。仅适用于无请求 scopes 的首次 role:node 请求；
      // 不会自动批准升级。
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
        // SSH 验证的自动批准（默认：启用）。
        // 通过 SSH 读回的设备密钥精确匹配，批准首次节点配对。
        sshVerify: true,
      },
      // 信任由已配对节点发布、代理可见的插件工具（默认：true）。
      pluginTools: {
        enabled: true,
      },
      // 持久启用危险／高度涉及隐私的节点命令。
      commands: {
        allow: ["camera.snap", "desktop.stream", "screen.record"],
        // 即使默认值或 commands.allow 包含精确命令名称，也会阻止它们。
        deny: ["camera.clip"],
      },
    },
  },
  tools: {
    exec: {
      // 默认 exec 主机："node" 将所有 exec 调用路由到已配对的节点。
      host: "node",
      // 节点 exec 的安全模式：仅允许已批准/已加入允许列表的命令。
      security: "allowlist",
      // 将 exec 固定到特定节点（id 或 name）。省略则允许任意节点。
      node: "build-node",
    },
  },
}

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

​

截图（canvas 快照）

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 进行定位。Linux Canvas 接受 HTTP(S) URL 或其内置的 A2UI 渲染器。
• 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>

• 移动端和 Linux 桌面节点使用一个内置的、由应用拥有的 A2UI 页面来进行支持操作的渲染。
• 仅支持 A2UI v0.8 JSONL（v0.9/createSurface 会被拒绝）。
• iOS 和 Android 渲染远程 Gateway Canvas 页面，但 A2UI 按钮操作只会从内置的、由应用拥有的 A2UI 页面分发。在这些移动客户端上，Gateway 托管的 HTTP/HTTPS A2UI 页面仅用于渲染。
• macOS 可以从应用选择的、精确按能力范围隔离的 Gateway A2UI 页面分发操作。其他 HTTP/HTTPS 页面仍然仅用于渲染。
• Linux 仅从内置的 A2UI 页面分发操作。其他 HTTP/HTTPS 页面仍然仅用于渲染，而且没有桌面应用的无头 Linux 节点不会公开 Canvas。

​

照片 + 视频（节点摄像头）

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 # 先前置再后置（保存 2 个路径）
openclaw nodes camera snap --node <idOrNameOrIp> --device-id <id> --max-width 1200 --quality 0.9 --delay-ms 2000

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

• 节点必须处于前台才能使用 canvas.* 和 camera.*（后台调用将返回 NODE_BACKGROUND_UNAVAILABLE）。
• 节点会限制片段时长，以保持 base64 负载可管理（关于各平台的具体限制，请参见 摄像头捕获）。nodes 代理工具在转发调用前也会将请求的 durationMs 上限设为 300000（5 分钟）；节点本身会应用更严格的限制。
• 在可能的情况下，Android 会提示请求 CAMERA/RECORD_AUDIO 权限；如果权限被拒绝，将失败并返回 *_PERMISSION_REQUIRED。

​

屏幕录制（节点）

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

• screen.record 的可用性取决于节点平台。
• nodes 代理工具会将请求的 durationMs 上限限制为 300000（5 分钟）；节点可能会施加更严格的限制，以约束返回的负载大小。
• --no-audio 会在受支持的平台上禁用麦克风采集。
• 当可用多个屏幕时，使用 --screen <index> 选择显示器（0 = 主屏幕）。

​

位置（节点）

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

• 位置默认处于关闭状态。
• “始终”需要系统权限；后台获取尽力而为。
• 响应包含纬度/经度、精度（米）和时间戳。
• 完整的参数/响应结构和错误代码： 位置命令。

​

SMS（Android 节点）

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

openclaw nodes invoke --node <idOrNameOrIp> --command sms.send --params '{"to":"+15555550123","message":"来自 OpenClaw 的问候"}'

• sms.search 可以在授予 READ_SMS 之前声明，因此一次调用可能会返回权限诊断；读取消息仍然需要该 Android 权限。
• 仅支持 Wi-Fi、没有电话功能的设备不会公布 sms.send。
• requires explicit gateway.nodes.commands.allow opt-in 错误表示手机已经声明了该命令，但 Gateway 操作员尚未授权。

​

设备和个人数据命令

• device.status、device.info — iOS、Android、Windows。
• device.permissions、device.health — 仅 Android。
• device.apps — Android、macOS 和无头 mac 节点。Android 需要在设置中启用已安装应用共享，并默认返回启动器可见的应用。TypeScript 节点宿主默认关闭共享，并接受 query、limit 和 includeSystem；macOS 结果包含 label、bundleId、path 和 system。
• notifications.list、notifications.actions — 仅 Android。
• photos.latest — iOS、Android。
• contacts.search — iOS、Android（默认只读）；contacts.add 是危险操作，需要 gateway.nodes.commands.allow。
• calendar.events — iOS、Android（默认只读）；calendar.add 是危险操作，需要 gateway.nodes.commands.allow。
• reminders.list — iOS、Android（默认只读）；reminders.add 是危险操作，需要 gateway.nodes.commands.allow。
• callLog.search — 仅 Android。
• motion.activity、motion.pedometer — iOS、Android；由可用传感器能力控制。

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}'

​

系统命令（node host / mac node）

openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "网关已就绪"
openclaw nodes invoke --node <idOrNameOrIp> --command system.which --params '{"bins":["git"]}'

• system.run 会在负载中返回 stdout/stderr/退出代码。
• Shell 执行现在通过带有 host=node 的 exec 工具进行；对于显式节点命令，nodes 仍然是直接 RPC 接口。
• nodes invoke 不会公开 system.run 或 system.run.prepare；它们仅保留在 exec 路径上。
• exec 路径会在审批前准备规范化的 systemRunPlan。审批获准后，网关会转发已存储的计划，而不是调用方之后编辑的 command/cwd/session 字段。
• system.notify 会遵循 macOS 应用中的通知权限状态；支持 --priority <passive|active|timeSensitive> 和 --delivery <system|overlay|auto>。
• 未识别的节点 platform / deviceFamily 元数据会使用保守的默认允许列表，其中排除 system.run 和 system.which。如果确实需要在未知平台上使用这些命令，请通过 gateway.nodes.commands.allow 显式添加。
• system.run 请求支持 cwd、env 映射、timeoutMs 和 needsScreenRecording —— 这些是由 exec 路径传递的请求负载字段（见上文），而不是 nodes invoke CLI 标志。
• 对于 Shell 包装器（bash|sh|zsh ... -c/-lc），请求作用域内的 env 值会被缩减为显式允许列表（TERM、LANG、LC_*、COLORTERM、NO_COLOR、FORCE_COLOR）。
• 对于允许列表模式下的始终允许决策，已知的分发包装器（env、flock、nice、nohup、stdbuf、timeout）会持久化内部可执行文件路径，而不是包装器路径。如果解除包装不安全，则不会自动持久化允许列表条目。
• 在处于允许列表模式的 Windows 节点主机上，通过 cmd.exe /c 运行 Shell 包装器需要审批（仅允许列表条目不会自动允许该包装器形式）。
• 节点主机会忽略 env 对象中的 PATH 覆盖，并在运行命令前移除一组规模较大且经过维护的解释器/Shell 启动变量（例如 NODE_OPTIONS、PYTHONPATH、BASH_ENV、DYLD_*、LD_*）。如果需要额外的 PATH 条目，请配置节点主机服务环境（或将工具安装到标准位置），而不要通过 env 传递 PATH。
• 在 macOS 节点模式下，system.run 受 macOS 应用中的 exec 审批控制（设置 → Exec approvals）。Ask/allowlist/full 的行为与无头节点主机相同；被拒绝的提示会返回 SYSTEM_RUN_DENIED。
• 在无头节点主机上，system.run 受本地 SQLite exec approvals 行控制；具体 macOS 情况请参阅下方无头节点主机中的 exec 主机路由环境变量。

​

Exec 节点绑定

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

openclaw config get agents.entries
openclaw config set 'agents.entries.main.tools.exec.node' "node-id-or-name"

openclaw config unset tools.exec.node
openclaw config unset 'agents.entries.main.tools.exec.node'

​

权限映射

​

无界面节点宿主（跨平台）

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

• 仍然需要配对（Gateway 将显示设备配对提示）。
• 客户端实例元数据、已签名的设备身份以及配对认证使用独立的状态记录；请参见 无界面身份状态。
• 执行审批会在本地强制执行，位于 ~/.openclaw/state/openclaw.sqlite#exec_approvals_config（参见 执行审批）。
• 在 macOS 上，无界面节点宿主默认会在本地执行 system.run。设置 OPENCLAW_NODE_EXEC_HOST=app 可将 system.run 路由到配套应用的执行宿主；再添加 OPENCLAW_NODE_EXEC_FALLBACK=0 可要求必须使用应用宿主，并在其不可用时直接失败。
• 当 Gateway WS 使用 TLS 时，添加 --tls / --tls-fingerprint。

​

Mac 节点模式

• macOS 菜单栏应用作为节点连接到 Gateway WS 服务器（因此 openclaw nodes … 可以作用于这台 Mac）。
• 在远程模式下，应用会为 Gateway 端口打开 SSH 隧道并连接到 localhost。