后台运行（Exec / 进程）

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

主要参数：

• command（必须）
• yieldMs（默认 10000）：这个延迟后自动后台化
• background（bool）：即时后台化
• timeout（秒、默认 1800）：超时后进程结束
• elevated (bool): run on host if elevated mode is enabled/allowed
• Need a real TTY? Set pty: true.
• workdir、env

挙動：

• 前台运行直接返回输出。
• 当后台运行（显式或超时）时，工具返回 status: "running" + sessionId 和简短的尾部输出。
• 输出保存在内存中，直到会话被轮询或清除。
• process 工具但允许未被場合、exec 是同步运行在那里 yieldMs/background 忽略执行。

When spawning long-running child processes outside the exec/process tools (for example, CLI respawns or gateway helpers), attach the child-process bridge helper so termination signals are forwarded and listeners are detached on exit/error. This avoids orphaned processes on systemd and keeps shutdown behavior consistent across platforms.

环境变量在的上写机：

• PI_BASH_YIELD_MS：默认 yield（ms）
• PI_BASH_MAX_OUTPUT_CHARS：内存上的输出上限（文字数）
• OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS: pending stdout/stderr cap per stream (chars)
• PI_BASH_JOB_TTL_MS: TTL for finished sessions (ms, bounded to 1m–3h)

设置（推荐）：

• tools.exec.backgroundMs（默认 10000）
• tools.exec.timeoutSec（默认 1800）
• tools.exec.cleanupMs（默认 1800000）
• tools.exec.notifyOnExit (default true): enqueue a system event + request heartbeat when a backgrounded exec exits.

行动：

• list：実行中 + 完成会话
• poll：新输出 drain（结束状态也報告）
• log：集約输出読无（offset + limit 対応）
• write: send stdin (data, optional eof)
• kill：后台会话结束
• clear：完成会话内存从删除
• remove: kill if running, otherwise clear if finished

注意：

• 只有后台会话会被列出/持久化在内存中。
• 会话在进程重启后会丢失（没有磁盘持久化）。
• 只有当您运行 process poll/log 并记录工具结果时，会话日志才会保存到聊天历史中。
• process is scoped per agent; it only sees sessions started by that agent.
• process list includes a derived name (command verb + target) for quick scans.
• process log uses line-based offset/limit (omit offset to grab the last N lines).

运行长时间任务并稍后轮询：

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