Managing Background Tasks with OpenClaw

I have spent too much time waiting for a terminal to return control after running a heavy script. It is frustrating when a task takes longer than expected and you lose track of the output or can’t interact with the process anymore. I found that managing these long-running tasks doesn’t have to be a headache.

In OpenClaw, I use the exec and process tools to handle these scenarios. The exec tool runs the command, and the process tool helps me keep track of everything happening in the background.

What You’ll Need

• OpenClaw environment with exec tool access.
• process tool enabled for session management.

Quick Start

I usually follow these four steps to handle long-running tasks:

1. Start the task: Use exec with the background parameter set to true to get a sessionId immediately.

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

2. Check progress: Use the poll action in the process tool to see the latest output.

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

3. Interact if needed: If the process asks for input, I use the write action.

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

4. Clean up: Once the task is done, I use clear to remove it from memory.

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

Tool Details

The exec Tool

When I run a command, exec handles the execution. If I don’t set it to background immediately, it stays in the foreground for a bit. The yieldMs parameter (defaulting to 10000) determines how long it waits before automatically moving the task to the background.

I also use these parameters often:

• timeout: Kills the process after a set time (default is 1800 seconds).
• pty: I set this to true if I need a real TTY.
• elevated: Runs on the host if I have the right permissions.
• workdir and env: Sets the working directory and environment variables.

The process Tool

This tool is my dashboard for everything running in the background. It is scoped per agent, so I only see the sessions I started.

• list: I use this to see all running and finished sessions.
• log: This is great for reading specific parts of the output using offset and limit.
• kill: Stops a session immediately.
• remove: Kills the process if it is running, or clears it if it is already finished.

Troubleshooting

The exec tool ignores yieldMs and runs synchronously I have seen this happen when the process tool is disallowed. If the agent cannot use the process tool, it cannot manage background sessions, so it forces everything to run in the foreground.

I lost my background sessions Sessions are kept in memory and are lost if the process restarts. There is no disk persistence for these sessions.

I can’t see sessions from another agent The process tool is scoped per agent. You will only see the sessions started by the specific agent you are currently using.

For more help setting this up, check out the AI Setup Assistant.

What’s Next

• Configuring Tool Timeouts
• Advanced Shell Environments
• Agent Scoping and Permissions
• System Events and Notifications