Background exec and process tool

OpenClaw runs shell commands through the exec tool and keeps long-running tasks in memory. The process tool manages those background sessions.

exec tool

Parameters:

Behavior:

• Foreground runs return retained output directly and disclose when earlier output exceeded the aggregate cap.
• When backgrounded (explicit or via yieldMs timeout), the tool returns status: "running" + sessionId and a short output tail.
• Launch failures return the operating-system error and release worker cleanup even when no process starts.
• Backgrounded and yieldMs runs inherit tools.exec.timeoutSeconds unless the call passes an explicit timeoutSeconds.
• With the secret egress proxy enabled, each Gateway-hosted command retains its own proxy access across turns. Process exit, cancellation, timeout, or Gateway shutdown revokes that access and closes its connections. Use process kill to stop a background command and its proxy access together.
• Returning a background session ID does not stop the process timeout. For a persistent service on the gateway or in a sandbox, use background: true with timeoutSeconds: 0, then stop it with process action kill when finished. 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 after their configured TTL, measured from completion. Each exec captures its agent's retention setting when admitted; using another agent's process tool does not change existing results' lifetimes. The registry also retains at most 50 finished sessions and 2,000,000 total retained output characters, evicting the oldest records first. The newest completed session retains its capped per-session aggregate even when that record alone exceeds the global limit.
• If the process tool is disallowed, exec runs synchronously and ignores yieldMs/background.
• Spawned exec commands receive 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 enabled) once the command emits output or fails.
• A failed background command wakes its originating session even when other sessions or automations are busy. If that session is still running, the completion waits until it is free. This also applies when a watcher exits before the work it was watching finishes.
• Manually canceled commands do not trigger completion notifications, even when they produced output. Retained output remains available through process poll or process log. Cleanup failures still notify.
• If automatic completion wake is unavailable, or you need quiet-success confirmation for a command that exits cleanly with no output, poll with process.
• Background exec does not automatically wake subagent sessions. A subagent must collect its command result with process poll before yielding without another completion source. A requested stop also needs its terminal result collected.
• Don't emulate reminders or delayed follow-ups with sleep loops or repeated polling — use cron for future work.

Env overrides

Config (preferred over env overrides)

Disable automatic completion turns

Background exec completion notifications are enabled by default. They can run a model turn marked [OpenClaw exec completion] even when agents.defaults.heartbeat.every is "0m": that setting disables recurring polls, not completion follow-ups.

To keep background commands running without automatic completion turns, set:

openclaw config set tools.exec.notifyOnExit false

An agent's agents.entries.<id>.tools.exec.notifyOnExit overrides the global setting. Set that override to false too, or remove it to inherit the global value. Newly started commands use the updated setting; commands already running retain the setting they started with. Use process poll or process log to collect their results on demand. This disables the completion event and its automatic model call without disabling background: true or the process tool.

Worker environments

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 use process to poll, send input, or stop them; foreground commands still stop when their turn is cancelled.

The retained worker occupies one node worker slot. Reusing it needs no additional slot. If a command finishes between turns, its retained output remains available to the next turn, subject to the normal process output limits and TTL. 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. Process handles do not survive a worker or node restart.

If the node's pairing is revoked or its provider no longer recognizes the lease, the session placement fails. Physical cleanup can remain pending until OpenClaw confirms that the exact worker has stopped; an unconfirmed stop does not release its ownership record.

Worker completion does not currently wake the Gateway session automatically; use process poll in a later turn to inspect the result. Closing a portal closes its proxy, not the development server: stop the server with process kill.

Child process bridging

After a host exec command finishes, OpenClaw releases its retained service-child group before reporting completion. Children left behind by shell backgrounding (&) are stopped with that group. To continue work across turns, start the long-running command with background: true and use process to collect its result. Its group stays owned until the command finishes; sandbox runtime lifetimes remain with the sandbox backend.

When spawning long-running child processes outside the exec/process tools (CLI respawns, gateway helpers), attach the child-process bridge helper so termination signals forward and listeners detach on exit/close. This avoids orphaned processes on systemd and keeps shutdown consistent across platforms.

On Linux with the default Node runtime, the Gateway starts a small spawn broker before loading its main runtime. If initial broker startup fails, the Gateway logs the failure reason and runtime entry path, then uses in-process spawning for the rest of that Gateway process. A new Gateway process tries the broker again. When the broker is ready, exec commands, shell-snapshot capture and validation, and helpers using the shared command runner spawn from it, so Linux does not copy the Gateway's page tables for each command. The existing process supervisors and service relays still own cancellation, output, and cleanup. After the broker first becomes ready, broker loss fails affected commands rather than rerunning them; later commands use the restarted broker. One-shot CLI commands, native file-descriptor inputs, and independently launched applications keep their local process transport, as do Bun, macOS, and Windows. The broker has its own process group, which the Gateway terminates on broker loss; service relays also retain their own parent-loss cleanup. A detached child can survive a broker crash before its PID is reported, matching the existing residual for directly spawned children when the Gateway crashes.

Canonical credential readers also use the broker. If it confirms that a reader never started, the read falls back once to a local process with the original environment and working directory. Cancellation, timeouts, uncertain launches, and cleanup failures do not trigger a retry. Snapshot-backed credential readers keep their local process transport.

A supervised command's timeout also covers startup, including blocked private-input delivery. The timeout result can return while cleanup continues. Scope retirement and Gateway shutdown wait for the cleanup owner separately; when that owner reports uncertainty, they report failure instead of treating the timeout as proof that the command has stopped.

For owned POSIX process groups, cleanup also waits for the operating system to confirm that the group has disappeared after graceful shutdown. A completed command or closed output pipe alone does not establish that its descendants have stopped. Forced termination without confirmed cleanup remains uncertain. Local TUI shell shutdown uses the same cleanup owner for its own commands. Permission-denied group probes still count as present; cleanup continues waiting within its original deadline for confirmed disappearance. If the host was busy, cleanup processes queued native completion events before reporting a timeout.

One-shot tool cleanup keeps configured sandbox runtimes on their session, agent, or shared lifetime. It joins the local command transport and backend cleanup for that command. It does not stop a shared sandbox or claim that every remote descendant has exited. Host commands, including elevated commands from sandboxed sessions, still require owned process-tree cleanup.

When a host command requires process-tree cleanup, a pty request falls back to the child-process path before starting a native PTY and reports a warning. Commands that require a terminal may fail under that fallback. Cleanup failures remain uncertain rather than being reported as a clean shutdown.

process tool

Actions:

Notes:

• Only backgrounded sessions are listed/persisted — in memory only, not on disk. Sessions are lost on process restart.
• Resetting or deleting a session clears only its completed background processes; other sessions, explicit shared scopes, and running processes remain unaffected.
• A live background session blocks cooperative host suspension and safe Gateway restart until the process owner confirms its actual exit.
• process remove can hide a running session immediately after requesting termination; suspension and restart remain blocked until exit confirmation.
• Session logs are only saved to chat history if you run process poll/log and the tool result is recorded.
• process is scoped per agent; it only sees sessions started by that agent.
• After an explicit kill or task cancellation, poll and log report a confirmed requested stop as a completed observation, retaining the process's signal and cancellation reason. Unexpected termination, timeouts, and cleanup failures remain errors. The process list retains the underlying terminal status.
• Use poll/log for status, logs, or completion confirmation when automatic completion wake is unavailable.
• Use log before recovering an interactive CLI, so the current transcript, stdin state, and input-wait hint are visible together.
• Use write/send-keys/submit/paste/kill when you need input or intervention.
• process list includes a derived name (command verb + target) for quick scans.
• process list, poll, and log report waitingForInput only when the session still has writable stdin and has been idle longer than the input-wait threshold (default 15000 ms, OPENCLAW_PROCESS_INPUT_WAIT_IDLE_MS).
• process log uses line-based offset/limit. When both are omitted, it returns the last 200 lines with a paging hint. When offset is set and limit isn't, it returns from offset to the end (not capped to 200).
• process poll and process log distinguish output discarded at the aggregate retention cap from output merely omitted by the pending buffer or retained tail. Discarded output cannot be recovered; paged logs can inspect only the retained portion.
• poll's timeout waits up to that many milliseconds before returning; values above 30000 are clamped to 30000.
• Polling is for on-demand status, not wait-loop scheduling. If the work should happen later, use cron.

In Code Mode, process returns its structured details directly. For action: "log", output contains the requested log page, including paging, retention, and input-recovery hints. Failed process actions include an error message alongside status: "failed", so the agent can choose the next action.

Examples

Run a long task and poll later:

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

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

Inspect an interactive session before sending input:

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

Start immediately in background:

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

Send stdin:

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

Send PTY keys:

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

Submit current line:

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

Paste literal text:

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

Related

• Exec tool
• Exec approvals