OpenClaw 🦞

Background Exec and Process Tool

Background Exec + Process Tool

OpenClaw 通过 exec tool 运行 shell commands，并将 long-running tasks 保存在内存中。process tool 管理这些 background sessions。

exec tool

Key parameters：

  • command（required）
  • yieldMs（default 10000）：在此 delay 后 auto-background
  • background（bool）：立即 background
  • timeout（seconds，default 1800）：在此 timeout 后 kill process
  • elevated（bool）：如果 elevated mode 启用/允许，在 host 上运行
  • 需要 real TTY？设置 pty: true。
  • workdir、env

Behavior：

  • Foreground runs 直接返回 output。
  • 当 backgrounded（explicit 或 timeout）时，tool 返回 status: "running" + sessionId 和 short tail。
  • Output 保存在内存中，直到 session 被 polled 或 cleared。
  • 如果 process tool 不被允许，exec 同步运行并忽略 yieldMs/background。
  • Spawned exec commands 接收 OPENCLAW_SHELL=exec 用于 context-aware shell/profile rules。

Child process bridging

当在 exec/process tools 之外 spawning long-running child processes 时（例如 CLI respawns 或 gateway helpers），附加 child-process bridge helper，以便 termination signals 被转发，并在 exit/error 时 detach listeners。这避免了在 systemd 上出现 orphaned processes，并保持 shutdown behavior 跨 platforms 一致。

Environment overrides：

  • PI_BASH_YIELD_MS：default yield（ms）
  • PI_BASH_MAX_OUTPUT_CHARS：in-memory output cap（chars）
  • OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS：每个 stream 的 pending stdout/stderr cap（chars）
  • PI_BASH_JOB_TTL_MS：finished sessions 的 TTL（ms，bounded to 1m–3h）

Config（preferred）：

  • tools.exec.backgroundMs（default 10000）
  • tools.exec.timeoutSec（default 1800）
  • tools.exec.cleanupMs（default 1800000）
  • tools.exec.notifyOnExit（default true）：当 backgrounded exec exit 时，enqueue system event + request heartbeat。
  • tools.exec.notifyOnExitEmptySuccess（default false）：当为 true 时，也为没有 output 的 successful backgrounded runs enqueue completion events。

process tool

Actions：

  • list：running + finished sessions
  • poll：drain session 的 new output（也报告 exit status）
  • log：读取 aggregated output（支持 offset + limit）
  • write：发送 stdin（data，optional eof）
  • kill：terminate background session
  • clear：从内存中 remove finished session
  • remove：如果 running 则 kill，否则如果 finished 则 clear

Notes：

  • 只有 backgrounded sessions 被 listed/persisted 在内存中。
  • Sessions 在 process restart 时丢失（无 disk persistence）。
  • 只有当你运行 process poll/log 且 tool result 被记录时，session logs 才会保存到 chat history。
  • process 是 per-agent scoped；它只看到该 agent 启动的 sessions。
  • process list 包括 derived name（command verb + target）用于 quick scans。
  • process log 使用 line-based offset/limit。
  • 当 offset 和 limit 都省略时，它返回最后 200 行并包括 paging hint。
  • 当提供 offset 但省略 limit 时，它返回从 offset 到 end 的内容（不 capped to 200）。

Examples

运行 long task 并稍后 poll：

{ "tool": "exec", "command": "sleep 5 && echo done", "yieldMs": 1000 }

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

立即在 background 中启动：

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

发送 stdin：

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