后台 Exec + Process 工具

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

exec 工具

主要参数:

  • command(必需)
  • yieldMs(默认 10000):超过这个延迟后自动转入后台
  • background(布尔值):立即转入后台
  • timeout(秒,默认 1800):超时后终止进程
  • elevated(布尔值):如果启用/允许提升模式,则在主机上运行
  • 需要真实的 TTY?设置 pty: true
  • workdir、env

行为说明:

  • 前台运行会直接返回输出
  • 转入后台时(显式指定或超时),工具会返回 status: "running" + sessionId 以及一小段输出尾部
  • 输出会保存在内存中,直到 Session 被轮询或清除
  • 如果 process 工具被禁用,exec 会同步运行并忽略 yieldMs/background 参数

子进程桥接

当在 exec/process 工具之外启动长时间运行的子进程时(例如 CLI 重启或 Gateway 辅助进程),需要附加子进程桥接辅助器,这样终止信号才能被转发,监听器也会在退出/错误时分离。这样可以避免在 systemd 上产生孤儿进程,并保持跨平台的关闭行为一致性。

环境变量覆盖:

  • PI_BASH_YIELD_MS:默认 yield 时间(毫秒)
  • PI_BASH_MAX_OUTPUT_CHARS:内存输出上限(字符数)
  • OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS:每个流的待处理 stdout/stderr 上限(字符数)
  • PI_BASH_JOB_TTL_MS:已完成 Session 的 TTL(毫秒,限制在 1 分钟到 3 小时之间)

配置(推荐):

  • tools.exec.backgroundMs(默认 10000)
  • tools.exec.timeoutSec(默认 1800)
  • tools.exec.cleanupMs(默认 1800000)
  • tools.exec.notifyOnExit(默认 true):当后台 exec 退出时,将系统事件加入队列并请求 Heartbeat

process 工具

操作:

  • list:列出运行中和已完成的 Session
  • poll:获取 Session 的新输出(同时报告退出状态)
  • log:读取聚合输出(支持 offset + limit)
  • write:发送 stdin(data,可选 eof)
  • kill:终止后台 Session
  • clear:从内存中移除已完成的 Session
  • remove:如果正在运行则终止,如果已完成则清除

注意事项:

  • 只有后台 Session 会被列出/保存在内存中
  • Session 在进程重启后会丢失(不会持久化到磁盘)
  • Session 日志只有在你运行 process poll/log 且工具结果被记录时,才会保存到聊天历史中
  • process 的作用域是每个 Agent;它只能看到该 Agent 启动的 Session
  • process list 包含一个派生的 name(命令动词 + 目标),方便快速扫描
  • process log 使用基于行的 offset/limit(省略 offset 可获取最后 N 行)

示例

运行长任务并稍后轮询:

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

立即在后台启动:

{ "tool": "exec", "command": "npm run build", "background": true }

发送 stdin:

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