Background Exec + Process Tool

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

exec tool

关键参数：

• command（必填）
• yieldMs（默认 10000）：超过该延迟后自动转入后台
• background（bool）：立即后台运行
• timeout（秒，默认 1800）：超过该超时后杀掉进程
• elevated（bool）：当 elevated mode 已启用/被允许时，在宿主机上运行
• 需要真实 TTY？设置 pty: true。
• workdir、env

行为：

• 前台运行会直接返回输出。
• 转入后台后（显式或超时触发），tool 返回 status: "running" + sessionId，以及一段简短的 tail。
• 输出保存在内存里，直到你轮询或清理该会话。
• 如果 process tool 被 policy 禁用，exec 将同步执行并忽略 yieldMs/background。

子进程桥接（child process bridging）

当你在 exec/process 之外生成长时间运行的子进程（例如 CLI 重新拉起自身、或 gateway helper 进程）时，应当附加 child-process bridge helper，以便：终止信号能正确转发、并且在退出/错误时拆除 listeners。这能避免在 systemd 下出现孤儿进程，并让跨平台的关闭行为更一致。

环境变量覆盖：

• PI_BASH_YIELD_MS：默认 yield（毫秒）
• PI_BASH_MAX_OUTPUT_CHARS：内存中输出上限（字符数）
• OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS：每个 stdout/stderr 流的 pending 上限（字符数）
• PI_BASH_JOB_TTL_MS：已完成会话的 TTL（毫秒，限制在 1m–3h）

配置（推荐）：

• tools.exec.backgroundMs（默认 10000）
• tools.exec.timeoutSec（默认 1800）
• tools.exec.cleanupMs（默认 1800000）
• tools.exec.notifyOnExit（默认 true）：当后台 exec 退出时，入队一个 system event 并请求一次 heartbeat。

process tool

Actions：

• list：运行中 + 已结束的会话
• poll：拉取某会话的新输出（同时报告退出状态）
• log：读取聚合后的输出（支持 offset + limit）
• write：向 stdin 写入（data，可选 eof）
• kill：终止后台会话
• clear：从内存中移除已结束会话
• remove：如果在运行则 kill，否则如果已结束则 clear

备注：

• 只有进入后台的会话才会被列出/保存在内存中。
• 进程重启后会话会丢失（不落盘）。
• 只有你执行 process poll/log 且 tool result 被记录时，会话日志才会进入聊天历史。
• process 按 agent 作用域隔离；它只看到该 agent 启动的会话。
• process list 会提供一个派生的 name（命令动词 + 目标）便于快速扫描。
• process log 使用按行的 offset/limit（省略 offset 可抓取最后 N 行）。

示例

运行一个长任务，稍后再 poll：

{ "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" }