节点执行
命令允许列表¶
执行审批是按节点主机进行的。从网关添加允许列表条目:
openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/uname"
openclaw approvals allowlist add --node <id|name|ip> "/usr/bin/sw_vers"
审批信息保存在节点主机的
~/.openclaw/state/openclaw.sqlite#exec_approvals_config 中。
将 exec 指向节点¶
配置默认值(网关配置):
openclaw config set tools.exec.host node
openclaw config set tools.exec.mode allowlist
openclaw config set tools.exec.node "<id-or-name>"
或按会话:
设置完成后,任何带有 host=node 的 exec 调用都会在节点主机上运行(受节点允许列表/审批约束)。
host=auto 不会自行隐式选择节点。只有在没有沙箱运行时处于活动状态时,才允许从 auto 发起显式的按调用 host=node 请求;当沙箱运行时处于活动状态时,auto 会拒绝该请求。若要从沙箱会话在节点上运行,或要将节点 exec 设为会话默认值,请显式设置 tools.exec.host=node 或 /exec host=node ...。
相关:
通道和子代理上下文¶
通告 system.run.execution-context.v1 的节点会在 system.run.prepare 和 system.run 上接收可选的
executionContext。它仅包含 senderId、chatId(非空字符串)和 subagent(存在时为 true)字段。
节点会将包含发送者/聊天身份 JSON 的 OPENCLAW_CHANNEL_CONTEXT 以及
OPENCLAW_SUBAGENT_EXEC=1 注入子进程环境。这些路由提示不会授予会话、轮次或命令审批权限,也不会修改已批准的 argv。
当上下文存在时,它会替换两个路由标记,包括继承的值。省略的字段不会保留先前的通道或子代理提示。未携带类型化上下文的请求将保持其现有环境行为。
自定义 env 覆盖仍遵循节点现有的限制。支持此上下文不会在拒绝任意环境覆盖的 Windows 伴随节点上启用任意环境覆盖。节点必须先在其准备、审批和启动路径中支持该上下文,然后才能通告此能力。
请同时更新 Gateway 和节点以使用此传输方式,并在重新连接后如果系统要求,在 设备 中批准更新后的节点能力面。旧版 Gateway 会继续通过
env 发送这些标记;新版 Gateway 对不具备该能力的节点也会这样做。该兼容性路径会保留现有行为,包括旧版 Windows 伴随节点上的
custom-env-not-supported。Gateway 不会省略标记以绕过该拒绝。不支持的上下文请求会在分发前被拒绝;重新连接不具备该能力的节点不会静默降级已准备好的请求。无需更改协议版本或配置。
对于连接到远程 Gateway 的 openclaw agent --local,CLI 还会检查 Gateway 通告的能力。即使节点已更新,旧版 Gateway 也会选择现有的 env
传输方式。发现后 Gateway 降级会在分发前拒绝类型化请求,而不是丢弃其上下文。
调用命令¶
低层(原始 RPC):
nodes invoke 会阻止 system.run 和 system.run.prepare;这些命令只能通过带有 host=node 的 exec 工具运行(见上文)。针对常见的“为代理提供 MEDIA 附件”工作流(摄像头、屏幕、位置:参见节点设备命令),存在更高层级的辅助命令。
长时间运行的流式节点命令使用增量式 node.invoke.progress
事件。每个事件携带 invoke ID、从零开始的序列号以及有界的 UTF-8 文本块;Gateway 会在将块交付给调用方之前对它们排序。现有的 node.invoke.result 仍然是唯一的终止响应。流式调用方可以设置一个不活动截止时间,它从第一个进度事件开始,并在后续进度后重置,同时在审批和执行期间保留该 invoke 的独立硬超时。结果、硬超时、不活动超时和节点断开连接都会丢弃待处理的流状态。调用方取消会发出带有已发布的
NodeInvokeCancelEvent 负载(invokeId 和 nodeId)的 node.invoke.cancel;随后节点主机会终止匹配的进程树。现有的请求/响应命令保持不变。
节点上的 Codex 会话¶
使用 Codex 运行时的会话主机还需要在节点主机的 OpenClaw 配置中安装并启用 codex 插件。仅使用 --session-host 不会安装或启用此插件。在节点上,如果缺失请安装它,然后启用它:
如果你在前景中运行 openclaw node run,请改为停止并重启该进程。节点重新连接后,批准其更新后的命令面。Gateway 还必须在 gateway.nodes.commands.allow 中允许 codex.exec-server.stdio.v1,且没有匹配的 deny 条目。Codex 执行保留其独立的放置审批;启用插件不会授予该审批。
当节点未通告该命令、等待配对审批或被 Gateway 策略阻止时,带有 runtimeId: "codex" 的 environments.list 会报告 requiredNodeCommand 状态和可操作的 message。缺少节点通告需要在节点上安装并启用插件;仅更改 Gateway 允许列表无法添加它。有关安装来源,参见安装插件。
参见 Codex 配对设备放置。
Exec 节点绑定¶
在未设置节点目标时,exec host=node 会选择唯一已配对、已连接且支持 system.run 的节点。其他已配对设备不会使选择变得不明确。如果连接了多个可执行节点,请为每次调用选择目标,或将 exec 绑定到特定节点;活动的 Canvas 目标不会选择 exec 主机。已绑定或显式指定的目标如果离线或无法执行命令,会被拒绝,而不是重定向到另一个节点。
绑定为 exec host=node 设置默认节点,并且可以按 agent 覆盖。
全局默认:
按 agent 覆盖:
openclaw config get agents.entries
openclaw config set 'agents.entries.main.tools.exec.node' "node-id-or-name"
取消绑定以使用唯一符合条件的节点;或者当多个符合条件的节点已连接时,按调用选择目标:
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw