Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.claw-link.dev/llms.txt

Use this file to discover all available pages before exploring further.

OpenClaw overview illustration This is a particularly cursed failure mode because it gives you just enough evidence that something happened somewhere, but not enough to feel confident that the workflow actually succeeded. If an agent appears to start working, but the final result never reaches the parent session, you are usually dealing with a handoff problem rather than a total failure to start. That means one of these is often true:
  • the child or background workflow started, but never returned a final result
  • the result was produced, but not surfaced back into the parent session/channel
  • the current session expected a different runtime path than the one actually used
  • the workflow stalled in a waiting or approval state
  • the wrong session is being inspected, so the work exists but you are looking in the wrong place
This guide is about narrowing down that gap.
Monitor icon Useful framing: this class of bug is usually about result return, routing, or session linkage — not just whether the agent started at all.

​
Wrench icon At a glance

  • First confirm whether the child workflow actually ran to completion.
  • Check whether the result is missing because of routing, waiting state, or wrong-session debugging.
  • Reduce the test to one small reproducible workflow before changing config.

​
What this usually looks like

Users usually describe one of these:
  • “It started doing the work, but nothing ever came back.”
  • “I can see that the agent/session ran, but the parent chat never got the result.”
  • “The child session looks active, but the original request is still hanging.”
  • “The workflow worked in the background, but the answer never showed up where I expected.”
That is a different problem from:
  • tools never appearing
  • OpenClaw never starting the work
  • the model only replying conversationally
Here, something often did start. The problem is the return path.

​
First: separate start failure from return failure

Before debugging anything else, answer this question:
did the child/agent/background workflow actually begin?
If the answer is no, you may be in a more basic issue like:
  • stale session
  • missing tool/runtime path
  • approval never completed
  • plugin/runtime setup mismatch
If the answer is yes, this page is probably the right one.

​
Fast troubleshooting flow

​
1) Reproduce with one small task

Do not debug this with a giant multi-step workflow first. Use one exact task that should clearly return a result. Examples:
  • one child session that reads a file and summarizes it
  • one delegated coding task with a small output
  • one background flow that should report completion back to the parent
You want something where success or failure is obvious.

​
2) Check whether the child session is still running or waiting

A lot of “never came back” reports are actually one of these:
  • the child is still running
  • the child is blocked on approval
  • the child reached a waiting state
  • the result is not missing, just not finished yet
If the workflow supports session/task inspection, check whether it is:
  • active
  • waiting
  • completed
  • failed
If it is still active, this is a timing/waiting problem. If it is complete but the parent never got the result, this is more likely a routing/return-path problem.

​
3) Make sure you are looking at the right session

This sounds obvious, but it is not. A lot of confusion comes from debugging:
  • the parent session only
  • while the useful evidence exists in the child session
  • or vice versa
If work was delegated or spawned elsewhere, inspect that exact session rather than assuming the parent chat contains the full story.

​
4) Check whether the workflow depends on ACP or another bridged runtime path

If the work ran through:
  • an ACP-backed session
  • an external runtime path
  • a delegated child flow
  • a bridge that has to return results upstream
…then the issue may be in the session linkage rather than in the execution itself. That is why these bugs often feel like:
“the work happened, but the parent never heard about it.”

​
5) Rule out approval/waiting-state issues

Sometimes the result is not missing. It is blocked. Common causes:
  • approval still needed
  • an external confirmation step never completed
  • the workflow paused waiting for user input
  • the child session needs intervention before it can finalize
From the parent side, that looks identical to a lost result until you inspect the child state.

​
6) Check general OpenClaw/gateway health

Run: 
openclaw status
Then: 
openclaw gateway status
And if available: 
openclaw gateway status --json
You are looking for broader runtime trouble like:
  • unhealthy gateway
  • plugin/runtime load issues
  • configuration drift
  • session plumbing problems introduced by updates or rollbacks

​
Common root causes

​
Root cause 1: child workflow never actually finished

Symptoms:
  • child appears active for a long time
  • no final result yet
  • parent looks stuck
Fix:
  • verify whether it is still running, waiting, or blocked

​
Root cause 2: result produced, but not routed back cleanly

Symptoms:
  • child looks complete
  • parent never receives final output
Fix:
  • inspect the child session directly
  • narrow down where the return path breaks

​
Root cause 3: wrong session is being inspected

Symptoms:
  • parent looks empty or stale
  • useful output exists elsewhere
Fix:
  • check the actual child/delegated session

​
Root cause 4: approval or waiting state masquerading as failure

Symptoms:
  • workflow looks half-done
  • parent never updates
  • child is waiting on something
Fix:
  • complete the required approval/input step

​
Root cause 5: runtime/session linkage mismatch

Symptoms:
  • issue appears mostly in ACP/delegated/background flows
  • work starts but handoff feels unreliable
Fix:
  • reduce to one reproducible flow
  • verify the runtime path and session linkage behavior

​
Practical checklist

Use this order:

​
1. Reproduce with one small task

​
2. Check whether the child session is active, waiting, failed, or complete

​
3. Inspect the actual child session, not just the parent

​
4. Rule out approval/input blocking

​
5. Check openclaw status

​
6. Check openclaw gateway status --json

​
7. Re-test after narrowing the exact break point

​
How to tell whether this is really a return-path problem

It probably is if:
  • the work seems to begin elsewhere
  • child activity exists but parent output is missing
  • the issue appears mainly in delegated/session-based workflows
  • the same pattern repeats across similar handoff flows
It probably is not if:
  • the work never started at all
  • the tools are missing in the current session
  • the assistant only talked about acting without any actual execution

​
Common mistakes

​
Debugging only the parent session

That hides half the evidence.

​
Assuming “no result yet” means “result is lost”

Sometimes it is just still running or waiting.

​
Testing with huge workflows first

That makes it much harder to find the actual break point.

​
Mixing startup issues with return-path issues

Different bug class. Different fix.

​
Final thought

When the agent responds but the result never reaches the parent session, the question is usually not:
“Did anything happen?”
It is:
“Where did the result path stop?”
Find that boundary first — child completion, waiting state, session linkage, or return routing — and the debugging gets much less haunted.
  • Why OpenClaw Says It Will Act but Doesn’t Complete the Task
  • ACP Agent Configuration in OpenClaw: What Actually Needs to Be Wired
  • How ACP Sessions Work in OpenClaw
  • OpenClaw Not Responding After an Update? Start Here