#background job for long running tasks

1 messages · Page 1 of 1 (latest)

keen ember
#

We're building an upgrade skill that involves long-running tasks — docker build, backup creation, diagnostic snapshot. Rather than keeping an agent session open for the full duration, is there a native way in OpenClaw to run a skill as a background job and have the agent notify the user when it's done? running 2026.4.20

gritty skyBOT
ruby forumBOT
#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> âś… Mark Solution

gritty skyBOT
boreal ledgeBOT
#

Yes, kind of, but the native shape is not “background a skill” directly.

For 2026.4.20, the built-in options are:

  • Best fit: sessions_spawn / subagents

    • Runs the work in a child agent session
    • Creates a background task
    • When it finishes, OpenClaw announces back to the original chat/thread
    • Default notify policy is done_only

  • For a single long shell command: exec with yieldMs or background:true

    • The command keeps running after the turn ends
    • With tools.exec.notifyOnExit: true (default), OpenClaw queues an exec completion wake so the agent can reply when it exits
    • Caveat: process state is in memory only, so it is less durable than task-backed runs

  • If it should run later / on a schedule: isolated cron

    • Creates task records too
#
  • Can announce or webhook on completion

So for your upgrade flow (backup + docker build + diagnostics), I’d recommend:

  1. Start a subagent for the whole upgrade job
  2. Let that subagent use exec internally for the heavy shell work
  3. Let OpenClaw push the final result back when done

That gives you native tracking plus completion notification, without keeping the original turn hanging open.

Docs:

If you want, I can sketch the exact pattern for an “upgrade skill” implementation.

keen ember
#

sure.. that would be helpful

boreal ledgeBOT
#

Yep, on 2026.4.20 I’d build it like this:

Recommended pattern

Parent skill

  1. Validate inputs
  2. Spawn a subagent with sessions_spawn
  3. Immediately tell the user “started, I’ll report back here”
  4. Let the child do the heavy work and finish with a clean summary

Child subagent

  • Runs backup, diagnostics, docker build, verification
  • Uses exec for the real shell steps
  • When it finishes, OpenClaw posts the completion back to the original chat

Why this is the best fit

#

If you only do exec background=true in the main skill, it works, but:

  • it is not a first-class background task record
  • process state is in memory only
  • it is less ideal for multi-step upgrade workflows

For “backup + build + snapshot + report back”, sessions_spawn is the cleaner native path.

Minimal shape

Parent skill logic:

If the requested upgrade flow will take more than ~1 minute or has multiple phases:
- call sessions_spawn
- label it clearly
# 
- set a generous runTimeoutSeconds
- do not wait in a poll loop
- reply that the upgrade job has started and completion will be posted here

Example spawn:

{
  "task": "Run the upgrade workflow for this project. Steps: (1) create a backup, (2) collect a diagnostic snapshot, (3) run docker build, (4) verify health, (5) report final status back to the user with key logs/artifacts. Use exec for shell commands. Stop on fatal errors, but still summarize partial progress.",
  "label": "upgrade-job",
  "mode": "run",
  "cleanup": "keep",
  "runTimeoutSeconds": 7200
}
#

Then reply something like:

Started the upgrade job. I’ll post the result here when it finishes.

Nice extras

  • Users can inspect active jobs with /tasks or openclaw tasks list
  • If you want more than final completion, switch notify policy to state_changes
  • If you want a dedicated follow-up thread/session, use thread: true and mode: "session"

Practical rule of thumb

  • One long shell command → exec with yieldMs / background:true
  • Multi-step workflow with completion notification → sessions_spawn
  • Run later / on schedule → cron

Docs: