OpenClaw background exec and the process tool

Long-running work is where a shell tool either becomes useful or becomes a liability. OpenClaw's answer is to background the command, hand back a session id, and give the agent a separate tool to poll, feed and kill it. The details worth knowing are the ones that decide whether output survives, whether the process survives, and what the agent should do instead of sleeping.

Backgrounding and retention

• A foreground run returns retained output directly and discloses when earlier output exceeded the aggregate cap; when the command is backgrounded, explicitly or by passing the yield delay, the tool returns a running status, a session id and a short tail, and backgrounded runs still inherit the configured exec timeout unless the call passes its own.
• Returning a session id does not stop the process timeout: for a persistent service on the gateway or in a sandbox, background the command with the timeout disabled and stop it later with the kill action, while host and worker lifecycle limits still apply.
• Output stays in memory up to the per-session aggregate cap until the session is polled or cleared; finished sessions expire on a lifetime measured from completion, each exec capturing its agent's retention setting when admitted, and the registry keeps at most 50 finished sessions and two million retained characters, evicting oldest first while the newest completed session keeps its capped aggregate.
• The knobs exist as config keys rather than environment variables: the background delay defaults to ten seconds, the per-call timeout to 1800 seconds, the cleanup lifetime to 30 minutes, exit notification is on by default and enqueues a system event plus a heartbeat request, and an extra setting can also notify for successful runs that produced no output.

Polling is for on-demand status, not wait-loop scheduling. If the work should happen later, use cron.

Workers, cleanup and the process tool

On a paired-node or node-backed cloud worker, background processes belong to the session's environment: finishing or cancelling a turn leaves already-backgrounded commands running, a later turn in the same environment can poll, feed or stop them, and foreground commands still stop when their turn is cancelled. The retained worker occupies one node worker slot, reusing it needs no additional slot, and once a turn finishes with no live background commands the worker exits. Moving or retiring the environment, replacing its ownership or stopping the node also stops its processes, and handles do not survive a worker or node restart. Cleanup is deliberately conservative elsewhere too: for owned process groups it waits for the operating system to confirm the group disappeared, a completed command or a closed output pipe alone does not prove descendants stopped, and forced termination without confirmed cleanup stays uncertain rather than being reported as a clean shutdown.

The nine actions

• List shows running and finished sessions with a derived name, poll drains new output and reports exit status, log reads aggregated output with line-based paging and input-recovery hints, and the three of them flag a session as waiting for input only when stdin is still writable and it has been idle past the threshold.
• Write sends stdin with an optional end marker, send-keys sends explicit key tokens or bytes to a terminal-backed session, submit sends a carriage return, and paste sends literal text wrapped in bracketed paste by default; kill terminates a running session, clear removes a finished one, and remove does whichever applies.
• Only backgrounded sessions are listed and persisted, in memory and never on disk, so they are lost on a restart; the tool is scoped per agent and sees only that agent's sessions, a live background session blocks cooperative suspension and safe gateway restart until exit is confirmed, and a poll timeout above 30 seconds is clamped.

The OpenClaw exec tool is the tool that starts these sessions and OpenClaw background tasks the ledger that shows them while they run.

What to do instead of sleeping

The docs are blunt about the anti-pattern: do not emulate reminders or delayed follow-ups with sleep loops or repeated polling. For work that starts now, start it once and rely on automatic completion wake when it is enabled and the command emits output or fails, then use the process tool for logs, status, input or intervention. For work that should happen later or on a schedule, the scheduler is the right surface. Reading the log before recovering an interactive command is the other habit worth keeping, because the transcript, the stdin state and the input-wait hint are only visible together there. OpenClaw automations covers the scheduler and OpenClaw sandboxing explained where these commands actually run.

On Diali

On Diali the assistant runs in its own runtime with state on a persistent volume, so a background command belongs to that customer runtime alone; daily snapshots and one-click restore are available through the Backups add-on (included on Max). Hosted OpenClaw on Diali describes the hosted assistant and Diali security the boundary around what it may run.

• Past the yield delay a command returns a session id, not a wall of output.
• Memory only: sessions are lost on restart, capped and expiring.
• Completion wake beats polling; the scheduler beats sleeping.