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