Use this file to discover all available pages before exploring further.

Background exec and process tool

Background Exec + Process Tool

OpenClaw runs shell commands through the

text

exec

tool and keeps long‑running tasks in memory. The

text

process

tool manages those background sessions.

exec tool

Key parameters:

text
command
(required)
text
yieldMs
(default 10000): auto‑background after this delay
text
background
(bool): background immediately
text
timeout
(seconds, default
text
tools.exec.timeoutSec
): kill the process after this timeout; set
text
timeout: 0
only to disable the exec process timeout for that call
text
elevated
(bool): run outside the sandbox if elevated mode is enabled/allowed (
text
gateway
by default, or
text
node
when the exec target is
text
node
)
Need a real TTY? Set
text
pty: true
.
text
workdir
,
text
env

Behavior:

Foreground runs return output directly.
When backgrounded (explicit or timeout), the tool returns
text
status: "running"
+
text
sessionId
and a short tail.
Background and
text
yieldMs
runs inherit
text
tools.exec.timeoutSec
unless the call provides an explicit
text
timeout
.
Output is kept in memory until the session is polled or cleared.
If the
text
process
tool is disallowed,
text
exec
runs synchronously and ignores
text
yieldMs
/
text
background
.
Spawned exec commands receive
text
OPENCLAW_SHELL=exec
for context-aware shell/profile rules.
For long-running work that starts now, start it once and rely on automatic completion wake when it is enabled and the command emits output or fails.
If automatic completion wake is unavailable, or you need quiet-success confirmation for a command that exited cleanly without output, use
text
process
to confirm completion.
Do not emulate reminders or delayed follow-ups with
text
sleep
loops or repeated polling; use cron for future work.

Child process bridging

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.

Environment overrides:

text
PI_BASH_YIELD_MS
: default yield (ms)
text
PI_BASH_MAX_OUTPUT_CHARS
: in‑memory output cap (chars)
text
OPENCLAW_BASH_PENDING_MAX_OUTPUT_CHARS
: pending stdout/stderr cap per stream (chars)
text
PI_BASH_JOB_TTL_MS
: TTL for finished sessions (ms, bounded to 1m–3h)

Config (preferred):

text
tools.exec.backgroundMs
(default 10000)
text
tools.exec.timeoutSec
(default 1800)
text
tools.exec.cleanupMs
(default 1800000)
text
tools.exec.notifyOnExit
(default true): enqueue a system event + request heartbeat when a backgrounded exec exits.
text
tools.exec.notifyOnExitEmptySuccess
(default false): when true, also enqueue completion events for successful backgrounded runs that produced no output.

process tool

Actions:

text
list
: running + finished sessions
text
poll
: drain new output for a session (also reports exit status)
text
log
: read the aggregated output (supports
text
offset
+
text
limit
)
text
write
: send stdin (
text
data
, optional
text
eof
)
text
send-keys
: send explicit key tokens or bytes to a PTY-backed session
text
submit
: send Enter / carriage return to a PTY-backed session
text
paste
: send literal text, optionally wrapped in bracketed paste mode
text
kill
: terminate a background session
text
clear
: remove a finished session from memory
text
remove
: kill if running, otherwise clear if finished

Notes:

Only backgrounded sessions are listed/persisted in memory.
Sessions are lost on process restart (no disk persistence).
Session logs are only saved to chat history if you run
text
process poll/log
and the tool result is recorded.
text
process
is scoped per agent; it only sees sessions started by that agent.
Use
text
poll
/
text
log
for status, logs, quiet-success confirmation, or completion confirmation when automatic completion wake is unavailable.
Use
text
write
/
text
send-keys
/
text
submit
/
text
paste
/
text
kill
when you need input or intervention.
text
process list
includes a derived
text
name
(command verb + target) for quick scans.
text
process log
uses line-based
text
offset
/
text
limit
.
When both
text
offset
and
text
limit
are omitted, it returns the last 200 lines and includes a paging hint.
When
text
offset
is provided and
text
limit
is omitted, it returns from
text
offset
to the end (not capped to 200).
Polling is for on-demand status, not wait-loop scheduling. If the work should happen later, use cron instead.

Examples

Run a long task and poll later:


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


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

Start immediately in background:


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

Send stdin:


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

Send PTY keys:


json
{ "tool": "process", "action": "send-keys", "sessionId": "<id>", "keys": ["C-c"] }

Submit current line:


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

Paste literal text:


json
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }