后台执行 + 进程工具

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

exec 工具

关键参数:

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

行为:

• 前台运行直接返回输出。
• 当后台运行时(显式或超时),工具返回 status: "running" + sessionId 和简短的尾部。
• 输出保留在内存中,直到会话被轮询或清除。
• 如果 process 工具被禁用,exec 同步运行并忽略 yieldMs/background。

子进程桥接

当在 exec/process 工具之外生成长时间运行的子进程时(例如,CLI 重新生成或网关助手),附加子进程桥接助手,以便转发终止信号并在退出/错误时分离监听器。这避免了 systemd 上的孤立进程,并使跨平台的关闭行为保持一致。

环境覆盖:

• PI_BASH_YIELD_MS:默认让步时间 (ms)
• PI_BASH_MAX_OUTPUT_CHARS:内存输出上限 (字符)
• OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS:每个流的待处理 stdout/stderr 上限 (字符)
• PI_BASH_JOB_TTL_MS:已完成会话的 TTL (ms,限制在 1m–3h)

配置(首选):

• tools.exec.backgroundMs (默认 10000)
• tools.exec.timeoutSec (默认 1800)
• tools.exec.cleanupMs (默认 1800000)
• tools.exec.notifyOnExit (默认 true):当后台执行退出时,将系统事件入队 + 请求心跳。

process 工具

操作:

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

注意事项:

• 只有后台会话会在内存中列出/持久化。
• 进程重启时会话会丢失(无磁盘持久化)。
• 只有在运行 process poll/log 并记录工具结果时,会话日志才会保存到聊天历史记录中。
• process 的作用域限定在每个代理;它只能看到该代理启动的会话。
• 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" }