- name
- jqopenclaw-node-invoker
- description
- 统一通过 Gateway 的 node.invoke 调用 JQOpenClawNode 能力（file.read、file.write、process.exec、process.manage、system.run、process.which、system.info、system.screenshot、system.notify、system.clipboard、system.input、node.selfUpdate）。当用户需要远程文件读写、文件移动/删除、目录创建/删除、进程管理（列表/搜索/终止）、远程进程执行、命令可执行性探测、系统信息整理、截图整理、系统弹窗、系统剪贴板读写、输入控制（鼠标/键盘）、节点自更新、节点命令可用性排查或修复 node.invoke 参数错误时使用。
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，CLIopenclaw 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