Background exec and process tool

​

exec tool

• 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.
• Finished sessions expire after their configured TTL. The registry also retains at most 50 finished sessions and 2,000,000 total output characters, evicting the oldest records first. The newest completed session retains its full output even if it exceeds the aggregate 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.
• 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

​

process tool

• 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.
• 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

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

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

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

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

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

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

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

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

​

Related

• Exec tool
• Exec approvals