{
  "title": "Background Exec + Process Tool",
  "content": "OpenClaw runs shell commands through the `exec` tool and keeps long‑running tasks in memory. The `process` tool manages those background sessions.\n\n* `command` (required)\n* `yieldMs` (default 10000): auto‑background after this delay\n* `background` (bool): background immediately\n* `timeout` (seconds, default 1800): kill the process after this timeout\n* `elevated` (bool): run on host if elevated mode is enabled/allowed\n* Need a real TTY? Set `pty: true`.\n* `workdir`, `env`\n\n* Foreground runs return output directly.\n* When backgrounded (explicit or timeout), the tool returns `status: \"running\"` + `sessionId` and a short tail.\n* Output is kept in memory until the session is polled or cleared.\n* If the `process` tool is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.\n\n## Child process bridging\n\nWhen 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.\n\nEnvironment overrides:\n\n* `PI_BASH_YIELD_MS`: default yield (ms)\n* `PI_BASH_MAX_OUTPUT_CHARS`: in‑memory output cap (chars)\n* `OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS`: pending stdout/stderr cap per stream (chars)\n* `PI_BASH_JOB_TTL_MS`: TTL for finished sessions (ms, bounded to 1m–3h)\n\n* `tools.exec.backgroundMs` (default 10000)\n* `tools.exec.timeoutSec` (default 1800)\n* `tools.exec.cleanupMs` (default 1800000)\n* `tools.exec.notifyOnExit` (default true): enqueue a system event + request heartbeat when a backgrounded exec exits.\n\n* `list`: running + finished sessions\n* `poll`: drain new output for a session (also reports exit status)\n* `log`: read the aggregated output (supports `offset` + `limit`)\n* `write`: send stdin (`data`, optional `eof`)\n* `kill`: terminate a background session\n* `clear`: remove a finished session from memory\n* `remove`: kill if running, otherwise clear if finished\n\n* Only backgrounded sessions are listed/persisted in memory.\n* Sessions are lost on process restart (no disk persistence).\n* Session logs are only saved to chat history if you run `process poll/log` and the tool result is recorded.\n* `process` is scoped per agent; it only sees sessions started by that agent.\n* `process list` includes a derived `name` (command verb + target) for quick scans.\n* `process log` uses line-based `offset`/`limit` (omit `offset` to grab the last N lines).\n\nRun a long task and poll later:\n\nStart immediately in background:",
  "code_samples": [
    {
      "code": "",
      "language": "unknown"
    },
    {
      "code": "Start immediately in background:",
      "language": "unknown"
    },
    {
      "code": "Send stdin:",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "exec tool",
      "id": "exec-tool"
    },
    {
      "level": "h2",
      "text": "Child process bridging",
      "id": "child-process-bridging"
    },
    {
      "level": "h2",
      "text": "process tool",
      "id": "process-tool"
    },
    {
      "level": "h2",
      "text": "Examples",
      "id": "examples"
    }
  ],
  "url": "llms-txt#background-exec-+-process-tool",
  "links": []
}