JQOpenClaw Node Invoker

快速流程

• 确定目标 nodeId （用户给定优先）。

• 调用 node.describe 检查节点在线状态，并按“节点识别规则”确认是否为 JQOpenClawNode。

• 若命令未声明或被网关策略拦截，先输出阻断原因，再给修复建议。

• 按 references/command-spec.md 构造 node.invoke 请求。

• 每次调用使用新的 idempotencyKey （UUID）。

• 输出结果时先给结论，再给关键字段，不直接堆原始 JSON。

节点识别规则

• 先读 node.describe 返回的 modelIdentifier 、commands 、displayName 、nodeId 。

• 强匹配（可直接判定为 JQOpenClawNode）：

• modelIdentifier 非空，且满足以下任一条件：

• 等于 JQOpenClawNode 。

• 以 JQOpenClawNode 开头（如 JQOpenClawNode(Qt/C++) ）。

• 弱匹配（仅在 modelIdentifier 为空时使用）：

• commands 同时包含：file.read 、file.write 、process.exec 、process.manage 、system.run 、process.which 、system.info 、system.screenshot 、system.notify 、system.clipboard 、system.input 、node.selfUpdate 。

• 且 displayName 或 nodeId 包含 JQOpenClaw 。

• 拒绝匹配：

• modelIdentifier 明确存在但不匹配 JQOpenClawNode* ，即使命令集合相似也不按本技能处理。

• 不确定处理：

• 若仅满足部分条件，先明确告知“节点类型不确定”，并要求用户指定目标 nodeId 或修正节点 modelIdentifier 后再执行。

命令映射

• 文件读取：file.read

• 文件写入/移动/删除/目录增删：file.write

• 进程执行（program/arguments/detached）：process.exec

• 进程管理（枚举/搜索/终止）：process.manage

• 远程进程执行（OpenClaw 标准参数）：system.run

• 可执行命令探测：process.which

• 系统基础信息：system.info

• 屏幕截图：system.screenshot

• 系统弹窗：system.notify

• 系统剪贴板：system.clipboard

• 输入控制：system.input

• 节点自更新：node.selfUpdate

调用规则

• 统一使用 node.invoke 。

• params 必须是对象，字段类型严格匹配。

• 节点侧仅接受 node.invoke.request.payload.paramsJSON ，且 paramsJSON 必须解析为对象。

• paramsJSON 缺失或 null 时按空对象处理；若存在但不是字符串、为空字符串、或解析后不是对象，按 INVALID_PARAMS 处理。

• file.write 必须显式传 allowWrite=true 才允许执行；未显式授权时应返回阻断提示。

• timeoutMs 需按任务复杂度设置：

• file.read / file.write ：5000-30000

• process.exec ：5000-120000（detached=false 时生效）

• process.manage ：5000-30000（kill 场景应确保 timeoutMs >= waitMs ）

• system.run ：5000-120000

• process.which ：5000-15000

• system.info ：30000

• system.screenshot ：60000

• system.notify ：5000-15000（仅参数校验与弹窗投递，弹窗异步展示）

• system.clipboard ：5000-15000（读写系统剪贴板文本）

• system.input ：5000-15000（仅参数校验与入队，动作异步执行）

• node.selfUpdate ：30000-300000（下载+校验+脚本启动；成功后节点会退出重启）

• 调用 node.selfUpdate 时，md5 为必填（32 位十六进制）；缺失或格式错误按 INVALID_PARAMS 处理。

• node.invoke.timeoutMs 可省略；若传入，必须为非负整数（毫秒），否则按 INVALID_PARAMS 处理。其中 0 视为立即超时。

• node.invoke.timeoutMs 会参与请求预算裁剪；当前节点会将 system.run.params.timeoutMs 、process.exec.params.timeoutMs （detached=false ）与 file.read(operation=rg) 的内部超时裁剪到该预算内（取更小值）。

• 即便省略 node.invoke.timeoutMs ，网关/调用端仍有等待超时（当前 OpenClaw 常见默认约 30000ms ，CLI openclaw nodes invoke 默认 15000ms ）。

• 实际可用执行时长取决于最先触发的超时层：调用端/网关等待超时、node.invoke.timeoutMs （若传入）、能力内部超时。

• process.manage 当前仅支持 Windows；非 Windows 环境调用会返回 PROCESS_MANAGE_FAILED 。

• process.manage ：

• operation=list/search/kill ，默认 list 。

• search 必须提供 query （或 keyword ）与 pid 之一。

• kill 必须提供 pid ，可选 waitMs 范围 [0, 30000] 与 force （默认 true ）；force=false 为非强杀退出请求（仅对具有顶层窗口的进程生效）；waitMs 当前不会被 node.invoke.timeoutMs 自动裁剪。

• kill 默认拒绝终止关键进程（critical process）；仅当目标 PID 为当前节点进程时允许。

• process.exec 使用 program + arguments ，支持 detached ；用于兼容历史调用方。

• system.run 对齐 OpenClaw：仅使用 command （argv 数组）、rawCommand 、cwd 、env 、timeoutMs 、needsScreenRecording 。

• process.which 支持 program （单个）或 programs （数组）探测；未命中返回 found=false ，不作为命令失败。

• file.read 支持 operation=read/lines/list/rg/stat/md5 。大文件建议使用 read + offsetBytes + maxBytes 分块读取（maxBytes 上限 2097152 ）；按行区间读取使用 lines + startLine/endLine ；目录遍历可用 list + recursive + glob ；元信息查询使用 stat ；文件指纹可用 md5 。

• file.write 默认禁用；需显式 allowWrite=true 。开启后默认 operation=write ；移动用 operation=move （配 destinationPath /toPath ）；删除用 operation=delete （走回收站删除）；目录创建用 operation=mkdir ；目录删除用 operation=rmdir 。

网关阻断处理

• command not allowlisted ：

• 说明这是 Gateway 策略拦截。

• 提示管理员在 Gateway 配置添加 gateway.nodes.allowCommands （如 file.read 、file.write 、process.exec 、process.manage 、system.run 、process.which 、system.notify 、system.clipboard 、system.input 、node.selfUpdate ）。

• command not declared by node / node did not declare commands ：

• 先看 node.describe.commands 。

• 要求节点端先声明命令再调用。

错误处理规范

• INVALID_PARAMS ：参数缺失、类型不匹配或超出范围（含 file.read / file.write / process.exec / process.manage / system.run / process.which / system.notify / system.clipboard / system.input / node.selfUpdate 的参数校验失败，例如 node.selfUpdate 缺失必填 md5 ）。指出具体字段问题并给出可直接重试的参数。

• TIMEOUT ：可能为网关等待超时，或显式传入 timeoutMs=0 触发立即超时。建议增大 timeoutMs 或缩小任务范围。

• FILE_READ_FAILED / FILE_WRITE_FAILED ：用于非参数类失败。输出失败原因并给路径、权限、目录存在性、回收站可用性等排查建议。

• PROCESS_MANAGE_FAILED ：用于非参数类失败（目标进程不存在、权限不足、非 Windows 平台、命中关键进程保护、终止或等待过程失败）。输出节点返回错误并给 PID、权限、平台和进程存活状态排查建议。

• PROCESS_EXEC_FAILED ：用于 process.exec 的非参数类失败（程序不存在、权限不足、启动失败等无法产出结构化执行结果）。输出节点返回错误并给 program 、workingDirectory 、权限排查建议。

• SYSTEM_RUN_FAILED ：用于 system.run 的非参数类失败（命令非法、程序不存在、权限不足、启动失败等无法产出结构化执行结果）。输出节点返回错误并给 command 、cwd 、权限、目标进程状态排查建议。

• PROCESS_WHICH_FAILED ：用于非参数类失败（探测流程内部异常）。输出节点返回错误并建议重试或检查节点日志。

• SYSTEM_INFO_FAILED ：系统信息采集失败。建议检查节点系统命令可用性与权限。

• SCREENSHOT_CAPTURE_FAILED / SCREENSHOT_UPLOAD_FAILED ：截图采集或上传失败。建议检查显示环境、file-server-uri 、file-server-token 与网络连通性。

• SYSTEM_INPUT_FAILED ：system.input 投递或平台能力失败。建议检查平台是否为 Windows、线程池状态与节点日志。

• SYSTEM_NOTIFY_FAILED ：system.notify 投递失败。建议检查应用实例状态与 UI 线程分发日志。

• SYSTEM_CLIPBOARD_FAILED ：system.clipboard 执行失败。建议检查节点应用实例、图形环境与剪贴板访问能力。

• NODE_SELF_UPDATE_FAILED ：node.selfUpdate 执行失败（下载失败、HTTP 状态异常、落盘失败、脚本启动失败等）。建议检查下载地址可达性、磁盘空间与杀毒拦截。

• NODE_SELF_UPDATE_MD5_MISMATCH ：node.selfUpdate 下载成功但 MD5 校验不匹配。建议核对必填 md5 与发布包内容。

• COMMAND_NOT_SUPPORTED ：改用已声明命令或升级节点版本。

输出规范

• 成功时：

• 先一句话结论。

• 再列关键字段（例如 bytesWritten 、exitCode 、timedOut 、url ）。

• 对 process.manage ，优先展示 operation 、pid 、returnedCount/totalMatched 、waitResult 、resultClass 等字段。

• 对 system.run / process.exec ，若 timedOut=true 或 resultClass=timeout ，按“命令超时”给出失败结论与重试建议（即使 node.invoke 本身返回成功结构）。

• 失败时：

• 先给 error.code 、error.message 。

• 再给一条可执行的下一步操作。

安全边界

• file.write 、process.exec 、process.manage 、system.run 与 process.which 默认按最小必要原则执行。

• 对可能破坏状态的操作（删除、覆盖、重置、停服务、终止进程）先征得用户明确确认。

• 不自行提升权限，不绕过网关策略。

system.notify

• 命令名：system.notify

• 用途：弹出系统消息提示框。

• 参数：

• message ：必填字符串，非空，长度范围 [1, 4000]

• title ：可选字符串，默认 JQOpenClaw ，长度上限 120

• 返回字段：operation=notify 、title 、message 、shown=true 、async=true 、ok=true

• 错误处理：

• 参数错误返回 INVALID_PARAMS

• 投递失败返回 SYSTEM_NOTIFY_FAILED

system.clipboard

• 命令名：system.clipboard

• 用途：读取当前系统剪贴板文本，或写入文本到系统剪贴板。

• 参数：

• operation ：可选字符串，read|write ，默认 read

• text ：当 operation=write 时必填字符串

• 返回字段（operation=read ）：operation=read 、text 、length 、hasText 、ok=true

• 返回字段（operation=write ）：operation=write 、written=true 、length 、hasText 、ok=true

• 错误处理：

• 参数错误返回 INVALID_PARAMS

• 执行失败返回 SYSTEM_CLIPBOARD_FAILED

system.input

• 命令名：system.input

• 用途：按顺序执行输入动作数组，支持鼠标、键盘和延迟混排。

• 执行语义：参数校验通过后异步入队；node.invoke 立即返回。

• 调度策略：latest-wins。若新请求到达，会取消旧请求尚未完成的剩余动作；已执行动作不会回滚。

• 使用建议：keyboard.down / keyboard.up 尽量在同一请求内闭合配对，或优先使用 keyboard.tap 。

• 入参要求：

• params.actions 必须为数组，长度 [1, 1000]

• 每个动作对象必须包含 type

• 支持 mouse.move 、mouse.click 、mouse.scroll 、mouse.drag 、keyboard.down 、keyboard.up 、keyboard.tap 、keyboard.text 、delay

• 关键校验：

• mouse.move.mode ：absolute|relative

• mouse.click.button ：left|right

• mouse.scroll ：delta 或 deltaY 二选一必填，可选 deltaX

• mouse.drag ：mode=absolute|relative ，可选 button=left|right

• keyboard.text.text ：非空字符串

• delay.ms ：[0, 60000]

• 错误处理：

• 参数错误返回 INVALID_PARAMS

• 投递失败返回 SYSTEM_INPUT_FAILED

参考

• references/command-spec.md