Skip to main content
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 output directly.
  • When backgrounded (explicit or via yieldMs timeout), the tool returns status: "running" + sessionId and a short output tail.
  • Backgrounded and yieldMs runs inherit tools.exec.timeoutSeconds unless the call passes an explicit timeout.
  • Output stays in memory until the session is polled or cleared.
  • 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.
  • If automatic completion wake is unavailable, or you need quiet-success confirmation for a command that exits cleanly with no output, poll with process.
  • 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)

Child process bridging

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/error. This avoids orphaned processes on systemd and keeps shutdown consistent across platforms.

process tool

Actions: Notes:
  • Only backgrounded sessions are listed/persisted — in memory only, not on disk. Sessions are lost on process restart.
  • 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.
  • 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).
  • 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.

Examples

Run a long task and poll later:
Inspect an interactive session before sending input:
Start immediately in background:
Send stdin:
Send PTY keys:
Submit current line:
Paste literal text: