跳转至

后台执行与进程工具

OpenClaw 通过 exec 工具运行 shell 命令,并将长时间运行的任务保存在内存中。process 工具管理这些后台会话。

exec 工具

参数:

参数 说明
command 必填。要运行的 shell 命令。
workdir 工作目录;省略则使用默认 cwd。
env 为命令提供的额外环境变量。
yieldMs 普通命令返回句柄前的等待毫秒数(默认 10000)。
background 立即启动一个有意独立运行的服务。
timeoutSeconds 超时秒数(默认 tools.exec.timeoutSeconds);超时后终止进程。设置 timeoutSeconds: 0 可为该调用禁用 exec 进程超时。
pty 在可用时于伪终端中运行(需要 TTY 的 CLI、编码智能体)。
elevated 如果已启用/允许提升模式,则在沙箱外运行(默认为 gateway;当 exec 目标为 node 时则为 node)。
host exec 目标:auto、sandbox、gateway 或 node。
node 节点 ID/名称,与 host: "node" 配合使用。

行为:

  • 前台运行直接返回保留的输出,并在之前的输出超过总上限时予以说明。
  • 当需要命令结果来完成当前任务时,设置 awaitResults: true。该调用会作为受拥有的工具调用一直保持到进程结算和终端收集,而不会返回未收集的后台句柄。这适用于 notifyOnExit=false;不启用完成通知。awaitResults: true 不能与 background: true 组合,后者明确选择独立运行的服务。运行、工具和流程的截止时间仍然适用。在 OpenClaw Code Mode 中,单元格会保留必要的调用,并在其结算时恢复,而无需模型轮询。
  • 当转入后台(显式或通过 yieldMs 超时)时,工具返回 status: "running" 和 sessionId 以及一段简短的输出末尾。在 Gateway 及其沙箱中,yield 出的句柄并不会使普通命令独立:浏览器的 Stop 按钮和输入的 /stop 会取消所选请求的命令。Stop 会等待进程清理,并在无法确认清理完成时报告。已完成的输出仍然可用,已取消的命令不会发出新的完成通知。托管的 worker 保留下文所述的独立行为。
  • 仅在需要有意独立运行的服务时使用 background: true。请求 Stop 会让该服务继续运行;请使用其进程句柄单独停止它。正常回合结束也会保留仍在运行的普通命令。
  • 启动失败会返回操作系统错误,并且即使没有启动任何进程,也会释放 worker 清理。
  • 托管的沙箱工作区最终化会将每个容器检查、暂停和恢复命令限制为 30 秒。失败或超时的操作会保留其恢复回执,而不会将不确定的暂停或恢复视为成功。
  • 后台运行和 yieldMs 运行会继承 tools.exec.timeoutSeconds,除非调用显式传入 timeoutSeconds。
  • 启用 secret egress proxy 后,每个由 Gateway 托管的命令都会在多个回合之间保留自己的代理访问权限。进程退出、取消、超时或 Gateway 关闭都会撤销该访问权限并关闭其连接。使用 process kill 可同时停止后台命令及其代理访问权限。
  • 返回后台会话 ID 并不会停止进程超时。对于 gateway 或沙箱中的持久服务,请使用 background: true 和 timeoutSeconds: 0,完成后使用 process 动作 kill 停止它。Host 和 worker 的生命周期限制仍然适用。
  • 输出会保留在内存中,最高不超过每会话的总上限,直到该会话被轮询或清除。
  • 已完成的会话会在其配置的 TTL 之后过期,TTL 从完成时开始计算。每个 exec 在准入时会捕获其所属智能体的保留设置;使用另一个智能体的 process 工具不会改变已有结果的生命周期。注册表最多保留 50 个已完成会话和总共 2,000,000 个保留的输出字符,并首先淘汰最旧的记录。最新的已完成会话会保留其受限的每会话总输出,即使该记录单独超过全局限制。
  • 如果 process 工具被禁用,exec 将同步运行并忽略 yieldMs/background。
  • 生成的 exec 命令会接收 OPENCLAW_SHELL=exec,以应用上下文感知的 shell/profile 规则。
  • 对于现在开始的长时间运行工作:只启动一次,并依赖自动完成唤醒(如果已启用)。当命令产生输出或失败时,唤醒会触发;在聊天频道中,当命令无输出干净退出时也会触发。
  • 完成唤醒允许智能体继续未完成的工作;它不需要新的聊天消息。智能体被指示报告尚未交付的请求结果、有意义的结果变化或新的可处理失败,并对常规、重复、已被取代或已恢复的结果保持沉默。没有捕获输出的完成(例如将输出重定向到文件的命令)也会以同样方式继续,因此智能体可以读取该文件并报告。这是模型指令,不是确定性的通知过滤器,并且不会禁用完成回合。
  • 原始的 exec 完成通知保留在智能体的转录中,但从 Control UI 的聊天历史和实时消息更新中隐藏。智能体面向用户的回复仍然可见。
  • 在聊天对话中启动的 host 命令会通过该对话中的普通执行完成:完成回合会使用其会话历史运行,任何回复都会回到所捕获的账户、聊天和主题。它会等待该会话中已有的工作之后,与心跳频率、活跃时间和投递设置无关。在自动静默运行中启动的命令在完成时也会保留该限制。当前会话的权限和工具限制可以在执行前收紧所捕获的权限。
  • 失败的后台命令会唤醒其发起会话,即使其他会话或自动化正在忙碌。如果该会话仍在运行,完成会一直等待直到其空闲。这也适用于 watcher 在其所监视的工作完成之前退出的情况。
  • 当命令没有产生任何输出时,超时也会唤醒会话。完成内容包含重试安全指导:重试前请验证任何外部副作用。
  • 手动取消的命令不会触发完成通知,即使它们产生了输出。保留的输出仍可通过 process poll 或 process log 获取。来自 process kill 的清理失败仍会通知;请求 Stop 会通过其错误响应报告清理失败,而不会启动完成回合。
  • 请求 Stop 还会撤销普通命令已排队或正在运行的完成回合,即使在其保留的进程输出过期之后也是如此。已停止的续作无法延迟回复或自行重试。不相关的排队事件和之后的人类请求仍然可以运行。
  • 如果自动完成唤醒不可用,或者你需要静默成功确认(空成功不会唤醒,tools.exec.notifyOnExitEmptySuccess),请使用 process 轮询。
  • 后台 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 true 退出时,在其源会话中通过普通轮次继续已后台化的主机 exec。
tools.exec.notifyOnExitEmptySuccess false 也会为没有输出的成功后台运行入队完成事件。对于聊天渠道默认为 true。

禁用自动完成轮次

后台 exec 完成通知默认启用。即使 agents.defaults.heartbeat.every 为 "0m",它们也可能运行标记为 [OpenClaw exec completion] 的模型轮次:该设置禁用的是周期性轮询,而不是完成后续处理。

要让后台命令在没有自动完成轮次的情况下继续运行,请设置:

openclaw config set tools.exec.notifyOnExit false

某个 agent 的 agents.entries.<id>.tools.exec.notifyOnExit 会覆盖全局设置。也请将该项覆盖设置为 false,或者移除它以继承全局值。新启动的命令会使用更新后的设置;已在运行的命令会保留其启动时的设置。使用 process poll 或 process log 按需收集它们的结果。这会禁用完成事件及其自动模型调用,但不会禁用 background: true 或 process 工具。

Worker 环境

在配对节点或基于节点的云 worker 上,后台进程属于会话的环境。完成或取消一个轮次时,已后台化的命令会继续运行。同一环境中的后续轮次可以使用 process 轮询、发送输入或停止它们;前台命令仍会在其轮次被取消时停止。

保留的 worker 占用一个节点 worker 槽位。复用它不需要额外槽位。如果命令在轮次之间完成,其保留的输出仍可供下一个轮次使用,但受常规进程输出限制和 TTL 约束。一旦某个轮次在没有存活后台命令的情况下结束,worker 会退出,除非协商的空闲保留使其保持就绪以等待后续操作。有关空闲限制和驱逐,请参阅 节点会话托管。移动或退役环境、替换其所有权或停止节点也会停止其进程。进程句柄无法在 worker 或节点重启后保留。

如果节点的配对被撤销,或其提供商不再识别该租约,则会话放置会失败。物理清理可能保持待定,直到 OpenClaw 确认确切的 worker 已停止;未确认的停止不会释放其所有权记录。

Worker 完成目前不会自动唤醒 Gateway 会话;请在后续轮次中使用 process poll 检查结果。关闭 portal 会关闭其代理,而不是开发服务器:使用 process kill 停止服务器。

控制界面

聊天侧边栏通过其 + 菜单和聊天标题栏的 面板 菜单提供单独的 进程 选项卡。子代理 仍保持为独立选项卡。进程 显示当前对话的后台 exec 命令和保留的已完成记录,包括状态、持续时间、退出信息和最近输出。读取输出不会排空待处理的 agent 输出,也不会确认完成通知。停止 请求终止所观察到的确切进程实例。

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

子进程桥接

在主机 exec 命令完成后,OpenClaw 会在报告完成之前释放其保留的进程作用域。由 shell 后台化(&)留下的子进程会随该作用域一起停止。为了在轮次之间继续常规工作,请让长时间运行的命令通过 yieldMs 让出一个句柄,并使用 process 收集其结果。请求 Stop 仍会在 Gateway 或其沙箱中取消它。将 background: true 保留给有意独立的服务。每个命令的进程作用域会保持归属,直到其完成;沙箱运行时生命周期仍由沙箱后端管理。

在 exec/process 工具之外生成长时间运行的子进程(CLI 重启、Gateway 辅助程序)时,附加子进程桥接辅助程序,以便终止信号能够转发,并且监听器在退出/关闭时分离。这可避免 systemd 上的孤立进程,并保持跨平台关闭一致性。

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

标准凭据读取器也使用代理。如果它确认某个读取器从未启动,读取会回退一次到使用原始环境和工作目录的本地进程。取消、超时、不确定的启动和清理失败不会触发重试。基于快照的凭据读取器保留其本地进程传输。

受监督命令的超时还覆盖启动,包括被阻止的私有输入投递。超时结果可以在清理继续时返回。作用域退役和 Gateway 关闭会分别等待清理属主;当该属主报告不确定时,它们报告失败,而不是将超时视为命令已停止的证明。

Linux 上 Node 的受管 exec 和协商工作器工作区命令使用专用子回收进程。它在启动前获取内核子进程所有权,接管孤立的子孙进程,并停止和回收它们,即使它们创建了另一个进程组或会话。完成需要内核报告没有剩余子进程、匹配的属主回执以及输出排空。它不单独依赖面向进程组的信号、进程表清点或继承管道关闭。

可移植工作器使用其已准入 Node 主机提供的原生辅助程序;可移植归档不会获取原生依赖。在禁止进程组信号的环境中,使用匹配的当前主机和工作器构建。不受支持的所有权契约会在启动前失败,而不是降级为仅传输层清理。源码安装必须构建其进程辅助程序;具有独立子回收器的源码加载器不能共享此所有权。

node 日志将 Linux 子孙进程消亡与旧的血缘回执分开记录。幸存属主可以在其主机停止后发布该事实。重启后,缺失证书或不确定的属主身份会保留物理保留;重启不能证明旧子孙进程已停止。旧构建不会将新证书重新解释为血缘完成。

macOS 和保留的 Bun 进程组属主仍需要内核组消失。权限拒绝检查永远不能证明不存在。仅命令完成或输出管道关闭不足以证明其子孙进程已停止。本地 TUI shell 关闭对其自身命令使用相同的清理属主。如果主机繁忙,清理进程会在报告超时之前排队原生完成事件。

一次性工具清理会保持已配置沙箱运行时处于其会话、代理或共享生命周期。它加入该命令的本地命令传输和后端清理。它不会停止共享沙箱,也不会声称所有远程子孙进程都已退出。主机命令(包括来自沙箱会话的提升命令)仍需要由属主负责的进程树清理。

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

process 工具

Actions:

Action Effect
list 运行中 + 已完成的会话。
poll 排空会话的新输出(同时报告退出状态)。
log 读取聚合输出和输入恢复提示。支持 offset + limit。
write 发送 stdin(data,可选 eof)。
send-keys 向基于 PTY 的会话发送显式按键令牌或字节。
submit 向基于 PTY 的会话发送回车/换行。
paste 发送字面文本,可选地包裹在括号粘贴模式中。
kill 终止后台会话。
clear 从内存中移除已完成的会话。
remove 如果正在运行则终止,否则如果已完成则清除。

Notes:

  • 仅后台会话会被列出/持久化——仅在内存中,不在磁盘上。进程重启时会丢失会话。
  • 重置或删除会话只会清除其已完成的后台进程;其他会话、显式共享作用域和正在运行的进程不受影响。
  • 存活的后台会话会阻止协作式主机挂起和安全 Gateway 重启,直到进程属主确认其实际退出。
  • process remove 可以在请求终止后立即隐藏正在运行的会话;挂起和重启在退出确认之前仍保持阻止。
  • 只有当你运行 process poll/log 且工具结果被记录时,会话日志才会保存到聊天历史。
  • process 按代理作用域划分;它只能看到由该代理启动的会话。
  • 在显式 kill 或任务取消后,poll 和 log 会将已确认的请求停止报告为完成的观察,并保留进程的终止信号和取消原因。意外终止、超时和清理失败仍为错误。进程列表保留底层终止状态。
  • 当自动完成唤醒不可用时,使用 poll/log 获取状态、日志或完成确认。
  • 在恢复交互式 CLI 之前使用 log,以便当前转录、stdin 状态和输入等待提示一起可见。
  • 当你需要输入或干预时,使用 write/send-keys/submit/paste/kill。
  • process list 包含派生的 name(命令动词 + 目标),便于快速扫描。
  • process list、poll 和 log 仅在会话仍有可写 stdin 且空闲时间超过输入等待阈值(默认 15000 ms,OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS)时报告 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 包含请求的日志页面,包括分页、 保留和输入恢复提示。失败的 process 操作会包含 error 消息,并伴随 status: "failed",以便代理可以选择下一个操作。

示例

运行一个长于默认 10000 ms 让出窗口的任务,稍后再轮询:

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

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

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

在一秒后让出常规构建:

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

发送 stdin:

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

发送 PTY 按键:

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

提交当前行:

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

粘贴字面文本:

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

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw