OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Agent coordination

Sub-agent slash command

Slash command

/subagents inspects sub-agent runs for the current session:

text
/subagents list/subagents log <id|#> [limit] [tools]/subagents info <id|#>

/subagents info shows run metadata (status, timestamps, session id, transcript path, cleanup). /subagents log prints recent chat turns for a run; add the tools token to include tool-call/result messages (omitted by default). Use sessions_history for a bounded, safety-filtered recall view from within an agent turn, or inspect the transcript path on disk for the raw full transcript.

In the Control UI, parent sessions with recent child runs have an expandable sidebar row. The nested rows show child status and runtime, and selecting one opens that child's chat while preserving the parent hierarchy. Failed or timed-out children retain a bounded failure reason, including failures during worktree preparation before any model reply. The child's transcript includes a durable failure notice when no assistant reply was recorded for that run. A later successful run clears the previous failure reason.

Thread binding controls

These commands work on channels with persistent thread bindings. See Thread supporting channels.

text
/session unbind/agents/session idle <duration|off>/session max-age <duration|off>

Spawn behavior

Agents start background sub-agents with the sessions_spawn tool. Follow the completion path described in the accepted receipt:

  • Ordinary announcing runs return an internal completion event to the requester, which reviews the result and decides whether a user-facing update is needed.
  • Swarm collectors return results through explicit collection, not completion notifications; reserve them for large parallel fan-out (several similar children, about five or more), and use ordinary spawns for one or a few.
  • Thread-bound session runs with a deliverable bound route reply directly to that thread, without a separate parent announcement.
  • Caller-managed quiet runs send no completion notification.

When execution identity auditing is enabled, each native or ACP child receives a new immutable identity context. Its lineage links the exact parent context/run when available and records bounded references for the parent grant, local policy, runtime assurance, and target policy that constrained the spawn. Neither the private identity token nor task text appears in the tool schema, result, transcript-derived evidence, or public plugin API. External ACP-native actions without a callback remain explicitly unsupported even though the ACP spawn and child are observable.

Non-blocking, push-based completion
  • sessions_spawn returns a run id after startup is accepted, without waiting for the child task to finish. Spawns from an OpenClaw cloud worker can first wait for child provisioning and node enrollment.
  • Announcing sub-agents report back to the parent/requester session on completion.
  • Agent turns that need those announced results should call sessions_yield when available. That ends the current turn and lets the completion event arrive as the next model-visible message. Collectors instead require explicit result collection.
  • Announced completion is push-based. Once spawned, do not poll /subagents list, sessions_list, or sessions_history in a loop just to wait for it to finish; check status on-demand only when debugging.
  • Child output is a report/evidence for the requester agent to synthesize. It is not user-authored instruction text and cannot override system, developer, or user policy.
  • A child run ending does not by itself complete the requester's user-facing goal. The requester compares the result with the requested outcome and continues in-scope work, including review findings and failed checks, before replying. Persistent child sessions can be continued with sessions_send.
  • Report the overall goal as blocked only when continuation requires new user authority or an unavailable external decision. Ordinary fixable findings are continuation work, not a terminal blocker.
  • On completion, OpenClaw best-effort closes tracked browser tabs/processes opened by that sub-agent session before the announce cleanup flow continues.
Completion delivery
  • OpenClaw hands completions back to the requester session through an agent turn with a stable idempotency key.
  • If the requester run is still active, OpenClaw first tries to wake/steer that run instead of starting a second visible reply path.
  • If an active requester cannot accept steering, including a busy CLI run, the handoff waits in the same session lane and starts after the current turn releases its claim. A failed wake does not start a competing turn or discard the completion.
  • A successful in-session parent handoff completes sub-agent delivery even when the parent decides no visible user update is needed. External completion delivery requires a confirmed send, not merely an answer saved in the requester transcript.
  • Native sub-agents do not get the message tool. They return plain assistant text to the parent/requester agent; human-visible replies stay owned by the parent/requester agent's normal delivery policy.
  • Queue acceptance is not delivery. If direct handoff cannot be used, delivery falls back to queue routing; the completion remains session_queued, rather than delivered, until the durable queue settles.
  • Automatic completion delivery retries for up to 30 minutes, starting around 15 seconds and capping the backoff at 5 minutes. Permanent failure or deadline expiry leaves the successful child task visibly blocked instead of discarding its result.
  • Missing or empty external delivery receipts remain unconfirmed and follow that bounded retry policy. An adapter-reported unconfirmed send remains ambiguous, never intentional suppression. Empty requester output still uses the existing completion fallback; it is not an outbound-hook cancellation. A confirmed message-tool send to the requester still counts as delivery.
  • If an outbound hook intentionally suppresses a completion, the child can remain completed while its task delivery is marked failed with the suppression reason. OpenClaw does not retry or start another requester turn to bypass that decision. Inspect the task error and hook policy before manually retrying.
  • Blocked canonical results are retained for 7 days. Operators can retry or intentionally dismiss them from the Tasks page or with openclaw tasks retry / openclaw tasks dismiss; retry can duplicate a visible result after an ambiguous provider acknowledgement.
  • Delivery keeps the resolved requester route: thread-bound or conversation-bound completion routes win when available. If the completion origin only provides a channel, OpenClaw fills the missing target/account from the requester session's recorded delivery context so direct delivery still works.
Completion handoff metadata

The completion handoff to the requester session is runtime-generated internal context (not user-authored text) and includes:

  • Result — the latest visible assistant reply text from the child. Tool/toolResult output is not promoted into child results. Terminal failed runs do not reuse captured reply text.
  • Model route change — when the terminal producer proves that fallback changed the requested model, one bounded and redacted route fact is carried separately from Result. Local and nested parents preserve it in their update. External channel parents keep it as private orchestration context, and raw direct-delivery fallback sends only Result.
  • Status — completed; ready for parent review / failed / timed out / unknown.
  • Compact runtime/token stats.
  • A review instruction telling the requester agent to verify the result before deciding whether the original task is done.
  • Follow-up guidance telling the requester agent to continue the task or record a follow-up when the child result leaves more action.
  • A final-update instruction for the no-more-action path, written in normal assistant voice without forwarding raw internal metadata.
Modes and ACP runtime
  • --model and --thinking override defaults for that specific run.
  • Use info/log to inspect details and output after completion.
  • For persistent thread-bound sessions, use sessions_spawn with thread: true and mode: "session".
  • If the requester channel does not support thread bindings, use mode: "run" instead of retrying an impossible thread-bound combination.
  • For ACP harness sessions (Claude Code, Gemini CLI, OpenCode, or explicit Codex ACP/acpx), use sessions_spawn with runtime: "acp" when the tool advertises that runtime. See ACP delivery model when debugging completions or agent-to-agent loops. When the codex plugin is enabled, Codex chat/thread control should prefer /codex ... over ACP unless the user explicitly asks for ACP/acpx.
  • OpenClaw hides runtime: "acp" until ACP is enabled, the requester is not sandboxed, and a backend plugin such as acpx is loaded. runtime: "acp" expects an external ACP harness id, or an agents.entries.* entry with runtime.type="acp"; use the default sub-agent runtime for normal OpenClaw config agents from agents_list.
Was this useful?
On this page

On this page