本页内容

本页内容

网关

后台 exec 和 process 工具

OpenClaw 通过 exec 工具运行 shell 命令,并将长时间运行的任务保留在内存中。 process 工具管理来自网关、沙箱和工作人员本地执行的后台会话。远程 host=node 调用使用同步 system.run 并且永远不会创建进程会话,即使启用了 process 也是如此。

exec 工具

参数:

参数 描述
command 必需。要运行的 Shell 命令。
workdir 工作目录;省略则使用默认 cwd。
env 为命令设置的额外环境变量。
yieldMs 返回普通命令句柄之前的毫秒数(默认 10000)。
background 立即启动刻意独立的服务。
timeoutSeconds 超时以秒为单位(默认tools.exec.timeoutSeconds);到期时终止进程。设置 timeoutSeconds: 0 以禁用该调用的 exec 进程超时。
pty 如果可用,则在伪终端中运行(TTY- 需要 CLI、编码代理)。
elevated 如果提升模式为 enabled/allowed(默认情况下为 gateway,或者当执行目标为 node 时为 node),则在沙箱外部运行。
host Exec 目标:auto、sandbox、gateway 或 node。
node Node id/name,与host: "node"配合使用。

行为:

  • 前台运行会直接返回保留的输出,并在更早的输出超过聚合上限时予以说明。
  • 放awaitResults: true当需要命令结果来完成任务时。它通过流程结算和终端收集来保持自有工具调用,而不是返回未收集的后台句柄。这适用于notifyOnExit=false;未启用完成通知。awaitResults: true不能与background: true,它显式选择一个独立运行的服务。运行、工具和流程的截止日期仍然适用。在OpenClaw代码模式,单元保留所需的呼叫并恢复其结算,而无需模型轮询。
  • 当后台运行时(显式或通过 yieldMs 超时),该工具返回 status: "running" + sessionId 和一个短输出尾部。在网关及其沙箱中,生成的句柄不会使普通命令独立:浏览器的 Stop 按钮和键入的 /stop 会取消所选请求的命令。停止等待进程清理并在无法确认清理时报告。已完成的输出仍然可用,并且取消的命令不会发出新的完成通知。受管理的工作人员保留下述单独行为。
  • 仅将 background: true 用于故意独立的服务。请求停止使该服务继续运行;使用其进程句柄单独停止它。正常转弯完成还保留仍在运行的普通命令。
  • Launch 失败会返回操作系统错误并释放工作线程清理,即使没有进程启动也是如此。
  • Native Windows 命令 shell 在使用替换环境(包括在 ARM64 上)启动时保留 SystemRoot。其他省略的变量不存在,并且显式提供的 SystemRoot 优先。
  • 托管沙箱工作区最终确定将每个容器检查、暂停和恢复命令限制为 30 秒。失败或超时的操作会保留其恢复收据,而不是将不确定的暂停或恢复视为成功。
  • 后台运行和 yieldMs 运行会继承 tools.exec.timeoutSeconds,除非此次调用传入了明确的 timeoutSeconds。
  • 启用 秘密出口代理 后,每个网关托管的命令都会保留其自己的跨轮代理访问权限。进程退出、取消、超时或网关关闭会撤销该访问并关闭其连接。使用 process kill 一起停止后台命令及其代理访问。
  • 返回后台会话ID不会停止进程超时。对于网关上或沙箱中的持久服务,请将 background: true 与 timeoutSeconds: 0 结合使用,然后在完成后使用 process 操作 kill 停止它。主机和工作线程生命周期限制仍然适用。
  • 输出会一直保存在内存中,直到会话被轮询或清除,但受每个会话的聚合上限限制。
  • Finished 会话在其配置的 TTL 后过期(从完成开始测量)。每个执行人员在被接纳时都会捕获其代理的保留设置;使用另一个代理的处理工具不会改变现有结果的生命周期。注册表还最多保留 50 个已完成的会话和总共 2,000,000 个保留的输出字符,首先驱逐最旧的记录。即使该记录本身就超过了全局限制,最新完成的会话仍会保留其上限的每会话总数。
  • Remote host=node 执行会忽略 background/yieldMs. 显式 background: true 或 yieldMs 请求会在执行结果中生成警告,而不是在等待批准时生成警告。该调用返回没有进程的输出 sessionId。
  • 如果不允许process工具,则本地exec也同步运行并忽略yieldMs/background.
  • Spawned exec 命令接收上下文感知 shell/profile 规则的 OPENCLAW_SHELL=exec。
  • 对于现在开始的长时间运行的工作:启动一次并依赖自动完成唤醒(启用时)。当命令发出输出或失败时,唤醒会触发;在聊天频道上,当命令完全退出而没有输出时,也会触发唤醒。
  • A完成唤醒让代理继续出色的工作;它不需要新的聊天消息。指示代理报告尚未交付的请求结果、有意义的结果更改或新的可操作故障,并对常规、重复、被取代或已恢复的结果保持沉默。没有捕获输出的完成(例如将其输出重定向到文件的命令)会以相同的方式继续,因此代理可以读取该文件并报告。这是模型指令,而不是基于规则的通知过滤器,并且它不会禁用完成轮。
  • Raw 执行完成通知保留在代理的记录中,但隐藏在 Control UI 的聊天历史记录和实时消息更新中。代理面向用户的回复仍然可见。
  • A 在聊天对话中启动的主机命令通过该对话中的普通执行来完成:完成轮及其会话历史记录运行,并且任何回复都会返回到捕获的帐户、聊天和主题。它在该会话中的现有工作之后等待,独立于心跳节奏、活动时间和交付设置。在自动静默运行中启动的命令在完成时会保留该限制。当前会话权限和工具限制可以收紧执行前捕获的权限。
  • Isolated cron exec 完成保留在原始运行的会话中,包括 delivery.mode: "announce" 的作业。他们永远不会唤醒代理主会话。一旦原始运行结束,其待完成的任务就无法开始另一个回合或提供回复;保留的输出仍然可以通过 process poll 或 process log 获得。 cron 作业的正常公告传递没有变化。
  • A 失败的后台命令会唤醒其原始会话,即使其他会话或自动化正忙。如果该会话仍在运行,则完成会等到它空闲为止。当观察者在其正在观察的工作完成之前退出时,这也适用。
  • Gateway 托管的后台进程仍以网关结束。重新启动后,符合条件的拥有会话会收到一个丢失进程完成回合:结果未知,代理必须在重新运行任何内容之前检查副作用或保存的状态。不会重播任何命令或输出。重置或存档会话、隐身会话、子代理、结束的 cron 运行和禁用的完成通知不会收到重新启动唤醒。保持物理进程处于活动状态需要一个单独的进程主机。
  • 当命令没有产生输出时,Timeouts 也会唤醒会话。完成包括重试安全指南:在重试之前验证任何外部副作用。
  • 手动取消的命令不会触发完成通知,即使它们产生输出也是如此。保留的输出仍然可以通过 process poll 或 process log 获得。 process kill 的清理失败仍会通知;请求停止通过其错误响应报告清理失败,而不启动完成轮。
  • Request Stop 还会停用普通命令的排队或运行完成轮次,包括在其保留的进程输出到期之后。已停止的延续无法提供迟到的回复或自行重试。不相关的排队事件和后来的人工请求仍然有资格运行。
  • 如果自动完成唤醒不可用,或者您需要静默成功确认(其中空成功不会唤醒(tools.exec.notifyOnExitEmptySuccess)),请使用 process 进行轮询。
  • Background exec 不会自动唤醒子代理会话。子代理必须在没有其他完成源的情况下屈服之前,使用 process poll 收集其命令结果。请求的停止还需要收集其最终结果。
  • 具有未过期执行限额的安静前台命令被报告为长时间运行。一旦该限额到期,停滞的会话恢复就可以中止拥有运行。重复 process poll 或 process log 调用,且循环检测的输出计数不变;仅仅流逝的空闲时间并不是进步。
  • 不要使用 sleep 循环或重复轮询来模拟提醒或延迟后续操作——应使用 cron 处理未来的任务。

环境变量覆盖

变量 作用
OPENCLAW_BASH_YIELD_MS 后台运行前的默认等待时间(毫秒)。默认 10000,限制在 10–120000 之间。
OPENCLAW_BASH_MAX_OUTPUT_CHARS 内存中的总输出字符上限。默认 200000,限制在 1000–200000 之间。
OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS 每个流的待定 stdout/stderr 上限。默认30000,限制1000-200000,受总上限限制。
OPENCLAW_BASH_JOB_TTL_MS TTL 表示已完成的会话(毫秒),限制为 1m-3h。
OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS 可写后台会话在被标记为可能正在等待输入前的无输出空闲阈值。默认 15000。

配置(优先于环境变量覆盖)

键 默认值 作用
tools.exec.backgroundMs 10000 与 OPENCLAW_BASH_YIELD_MS 相同。
tools.exec.timeoutSeconds 1800 每次调用的默认超时时间。
tools.exec.cleanupMs 1800000 与 OPENCLAW_BASH_JOB_TTL_MS 相同。
tools.exec.notifyOnExit 真的 退出时,通过其原始会话中的普通轮流继续后台主机执行。
tools.exec.notifyOnExitEmptySuccess 错误的 还将成功的后台运行的完成事件排入队列,但没有输出。聊天频道默认为 true。

禁用自动完成转弯

默认情况下启用后台执行完成通知。即使 agents.defaults.heartbeat.every 是 "0m",他们也可以运行标记为 [OpenClaw exec completion] 的模型转:该设置禁用重复轮询,而不是完成后续操作。

要保持后台命令运行而不自动完成轮流,请设置:

bash
openclaw config set tools.exec.notifyOnExit false

代理的 agents.entries.<id>.tools.exec.notifyOnExit 会覆盖全局设置。也将该覆盖设置为 false,或删除它以继承全局值。新启动的命令使用更新的设置;已运行的命令保留其开始时的设置。重新启动唤醒还会检查当前设置,因此禁用通知会抑制任何挂起的丢失进程唤醒。使用 process poll 或 process log 按需收集结果。这将禁用完成事件及其自动模型调用,而无需禁用 background: true 或 process 工具。

工作环境

对于配对设备上的托管后台工作,请启用 会话托管 并选择该设备进行 OpenClaw 会话。当会话工具和执行策略允许时,将工作线程的本地 exec 与 background: true 及其 process 工具一起使用。这会在设备上运行会话,而不是发送单独的远程 host=node 命令。

在配对节点或节点支持的云工作线程上,后台进程属于会话环境。完成或取消转弯会使后台命令继续运行。稍后在相同环境中可以使用 process 来轮询、发送输入或停止它们;当其轮次被取消时,前台命令仍然停止。

保留的worker占用一个节点worker槽位。重复使用它不需要额外的插槽。如果命令在回合之间完成,则其保留的输出仍可用于下一回合,但须遵守正常过程输出限制和 TTL。一旦轮次结束且没有实时后台命令,工作人员就会退出,除非协商的空闲保留使其为后续操作做好准备。有关空闲限制和驱逐,请参阅 节点会话托管。移动或淘汰环境、更换其所有权或停止节点也会停止其进程。进程句柄在工作线程或节点重新启动后不会继续存在。

如果节点的配对被撤销或其提供者不再识别租约,则会话放置失败。物理清理可以保持待处理状态,直到 OpenClaw 确认确切的工作人员已停止;未经确认的止损不会释放其所有权记录。

Worker 完成当前不会自动唤醒 Gateway 会话;稍后使用 process poll 检查结果。关闭门户会关闭其代理,而不是开发服务器:使用 process kill 停止服务器。

Control UI

聊天侧面板通过其 + 菜单和聊天标题的 Panels 菜单提供单独的 Processes 选项卡。 Subagents 保留其自己的选项卡。进程显示当前对话的后台执行命令和保留的完成记录,包括状态、持续时间、退出信息和最近的输出。读取输出不会耗尽挂起的代理输出或确认完成通知。 Stop 请求终止确切观察到的流程实例。

该列表是有界的,对正在运行的进程进行优先级排序,并遵循现有的内存保留限制。可见时刷新;断开连接或不可用的工作人员会显示错误而不是空列表。它不提供交互式终端或枚举不相关的操作系统进程。

子进程桥接

主机执行命令完成后,OpenClaw 在报告完成之前释放其保留的进程范围。 shell 后台 (&) 留下的子项将在该范围内停止。要继续轮流进行普通工作,请让长时间运行的命令生成一个带有 yieldMs 的句柄,并使用 process 来收集其结果。请求停止仍然会在网关或其沙箱中取消它。保留 background: true 以用于特意独立的服务。每个命令的进程范围在其完成之前一直保持所属状态;沙箱运行时生命周期仍保留在沙箱后端。

当在 exec/process 工具外部生成长时间运行的子进程时(CLI 重生,网关帮助程序),请附加子进程桥帮助程序,以便转发终止信号并在 exit/close. 上分离侦听器,这可以避免 systemd 上的孤立进程并保持跨平台关闭一致。

在具有默认 Node 运行时的 Linux 上,网关在加载其主运行时之前启动一个小型生成代理。如果初始代理启动失败,网关会记录失败原因和运行时入口路径,然后对网关进程的其余部分使用进程内生成。新的网关进程再次尝试代理。当代理准备就绪时,执行命令、shell 快照捕获和验证以及使用共享命令运行程序的帮助程序将从其中生成,因此 Linux 不会为每个命令复制网关的页表。现有的进程管理器和服务中继仍然拥有取消、输出和清理功能。在代理首次准备就绪后,代理丢失会导致受影响的命令失败,而不是重新运行它们;后面的命令使用重新启动的代理。一次性 CLI 命令、本机文件描述符输入和独立启动的应用程序保留其本地进程传输,Bun、macOS 和 Windows 也是如此。代理有自己的进程组,网关在代理丢失时终止该进程组;服务中继还保留自己的父丢失清理功能。分离的子级可以在报告其 PID 之前在代理崩溃中幸存下来,与网关崩溃时直接生成的子级的现有残差相匹配。

存储凭证的读取者也使用代理。如果确认读取器从未启动,则读取会回退到具有原始环境和工作目录的本地进程。取消、超时、不确定的启动和清理失败不会触发重试。支持快照的凭证读取器保留其本地进程传输。

受监督命令的超时还涵盖启动,包括阻止私人输入传递。当清理继续时,超时结果可能会返回。范围退役和网关关闭分别等待清理所有者;当该所有者报告不确定性时,他们报告失败,而不是将超时视为命令已停止的证据。

Linux 上的托管 exec 和协商工作工作区命令与 Node 使用专用的子子收割器。它在启动前获取内核子进程所有权,采用孤立的后代,并停止并获取它们,即使它们创建了另一个进程组或会话。完成要求内核报告没有剩余的子进程、匹配的所有者收据和输出消耗。它不依赖于组定向信号、进程表普查或单独的继承管道关闭。

便携式工作人员使用其认可的 Node 主机提供的本机助手;可移植存档不获取本机依赖项。在禁止进程组信号的环境中使用匹配的当前主机和工作线程构建。不受支持的所有权合同在启动前失败,而不是降级为仅传输清理。源安装必须构建其进程助手;具有独立子收割机的源加载器无法共享此所有权。

节点日志记录 Linux 后代灭绝与较早的谱系收据分开。幸存的所有者可以在其主机停止后发布该事实。重启后,证书丢失或所有者身份不确定会保留物理预留;重新开始并不能证明老子孙已经停止了。较旧的版本不会将新证书重新解释为沿袭完成。

macOS 和保留的 Bun 进程组所有者仍然要求内核组消失。拒绝许可的检查永远不会证明不存在。单独完成的命令或关闭的输出管道并不能确定其后代已停止。本地 TUI shell 关闭对其自己的命令使用相同的清理所有者。如果主机繁忙,清理进程会在报告超时之前对本机完成事件进行排队。

一次性工具清理将配置的沙箱运行时保留在其 会话、代理或共享生命周期 上。它加入了该命令的本地命令传输和后端清理。它不会停止共享沙箱或声明每个远程后代都已退出。主机命令,包括来自沙盒会话的提升命令,仍然需要清理拥有的进程树。

当主机命令需要清理进程树时,pty 请求会在启动本机 PTY 之前回退到子进程路径并报告警告。在该后备条件下,需要终端的命令可能会失败。清理失败仍然不确定,而不是被报告为干净关闭。

process 工具

行动:

操作 作用
list 运行中 + 已完成的会话。
poll 提取某个会话的新输出(也会报告退出状态)。
log 读取汇总输出和输入恢复提示。支持 offset + limit。
write 发送 stdin(data,可选 eof)。
send-keys 将显式密钥令牌或字节发送到 PTY- 支持的会话。
submit 将 Enter/carriage 返回到 PTY- 支持的会话。
paste 发送字面文本,可选择包裹在 bracketed paste 模式中。
kill 终止后台会话。
clear 从内存中移除已完成的会话。
remove 如果正在运行则终止,否则如果已完成则清除。

注意:

  • Only 后台会话是 listed/persisted — 仅在内存中,不在磁盘上。进程重新启动时会话会丢失。
  • 重置或删除会话只会清除已完成的后台进程;其他会话、显式共享作用域以及正在运行的进程不受影响。
  • 正在运行的后台会话会阻止协作式主机挂起和安全的 Gateway 重启,直到进程所有者确认其确实已退出。
  • process remove 可以在请求终止后立即隐藏正在运行的会话;在确认进程退出之前,挂起和重启仍会被阻止。
  • 只有运行 process poll/log 且工具结果被记录后,会话日志才会保存到聊天记录中。
  • process 按代理划分作用域;它只能看到由该代理启动的会话。
  • 在显式 kill 或任务取消后,poll 和 log 报告确认的请求停止作为已完成的观察,保留进程的信号和取消原因。意外终止、超时和清理失败仍然是错误。进程列表保留底层终端状态。
  • 当自动完成唤醒不可用时,使用 poll/log 获取状态、日志或完成确认。
  • 恢复交互式 CLI 之前使用 log,以便同时查看当前记录、stdin 状态和输入等待提示。
  • 需要输入或干预时,使用 write/send-keys/submit/paste/kill。
  • process list 会包含一个派生的 name(命令动词 + 目标),便于快速扫描。
  • 仅当会话仍具有可写 stdin 并且空闲时间超过输入等待阈值(默认 15000 毫秒,OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS)时,process list、poll 和 log 才报告 waitingForInput。
  • process log 使用基于行的 offset/limit. 当两者都被省略时,它返回带有分页提示的最后 200 行。当 offset 已设置且 limit 未设置时,它从 offset 返回到末尾(不上限为 200)。
  • process poll 和 process log 会区分因聚合保留上限而丢弃的输出,以及仅因待处理缓冲区或保留尾部而被省略的输出。被丢弃的输出无法恢复;分页日志只能查看保留的部分。
  • poll 的 timeout 最多等待指定的毫秒数后返回;超过 30000 的值会被限制为 30000。
  • 轮询用于按需获取状态,而不是用于循环等待调度。如果工作应在稍后执行,请使用 cron。

在Code Mode中,process直接返回其结构化详细信息。对于 action: "log",output 包含请求的日志页,包括分页、保留和输入恢复提示。失败的流程操作包括 error 消息和 status: "failed",因此代理可以选择下一个操作。

示例

运行长于默认 10000 毫秒产量窗口的任务并稍后轮询:

json
{ "tool": "exec", "command": "sleep 30 && echo done" }
json
{ "tool": "process", "action": "poll", "sessionId": "<id>" }

在发送输入前检查一个交互式会话:

json
{ "tool": "process", "action": "log", "sessionId": "<id>" }

一秒后生成普通构建:

json
{ "tool": "exec", "command": "npm run build", "yieldMs": 1000 }

发送 stdin:

json
{ "tool": "process", "action": "write", "sessionId": "<id>", "data": "y\n" }

发送 PTY 按键:

json
{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }

提交当前行:

json
{ "tool": "process", "action": "submit", "sessionId": "<id>" }

粘贴字面文本:

json
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

相关内容

本页有帮助吗?