vrr/openclaw
2
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-10-04 02:00:10 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 32
openclaw/docs/tools/subagents.md
Peter Steinberger 6652f7eac8
refactor: remove Tasks and TaskFlow runtime (#159179) 
Remove Tasks and TaskFlow runtime, APIs, CLI, SDK surfaces and panels after the Cron, session, native execution and media completion ownership cutovers. Preserve stored rows and import provable legacy native assignments through Doctor; ambiguous ownership stays untouched with a warning.

Follows #158221, #158217, #158225, #158222, #158702 and #158776. Related: #156532. Task-specific public APIs retire immediately; retained responsibilities use their existing owners.

Maintainer-authorized administrative landing after full CI run 36312986498 attempt 2 passed on 274595e2, with subsequent actual conflicts reviewed and focused checks passing. Current PR CI preflight hits the 64 KiB changed-path metadata limit before tests (run 36335042695); its duplicate security-review status mirrors that planning failure. Review and scoped proof are recorded in the PR. Published 9.4 native import is proven; remaining native completion and 9.4 rollback witnesses are explicitly unproven.
2026-09-27 10:40:29 -07:00

12 KiB
Raw Blame History

summary read_when title sidebarTitle
Index of the OpenClaw sub-agent documentation, one page per reader job
You want background or parallel work via the agent
You are changing sessions_spawn or sub-agent tool policy
You are implementing or troubleshooting thread-bound subagent sessions
You are looking for the sub-agent page that matches your task
Sub-agents Sub-agents

Sub-agents are background agent runs spawned from an existing agent run. Each one runs in its own session (agent:<agentId>:subagent:<uuid>) and, by default, announces its result back to the requester for review. Subagent runs are tracked by the native subagent lifecycle owner.

Goals:

  • Parallelize research, long tasks, and slow tool work without blocking the main run.
  • Keep sub-agents isolated by default (session separation, optional sandboxing).
  • Keep the tool surface hard to misuse: sub-agents do not get session or message tools by default.
  • Support configurable nesting depth for orchestrator patterns.
**Cost note:** each sub-agent has its own context and token usage by default. For heavy or repetitive tasks, set a cheaper model for sub-agents and keep your main agent on a higher-quality model via `agents.defaults.subagents.model` or per-agent overrides. When a child genuinely needs the requester's current transcript, spawn it with `context: "fork"`. Thread-bound subagent sessions default to `context: "fork"` because they branch the current conversation into a follow-up thread.

A subagent run ends; a session does not. When you open a subagent run in the Control UI, its transcript is view-only. Use Open parent session in the composer area to continue the conversation with the parent. You can still use Stop when the Gateway reports an abortable run. Persistent sessions created with visible: true are ordinary sessions in the session tree: they keep their parent for navigation and completion announcements, and you can always type in them and steer them like any other session.

Use ordinary subagents for internal QA, research, coding, review, and test lanes, with results returning to the parent task. Create a persistent visible session only when the user requests a separate session or needs to return to and steer that work independently. A PR or report, a long run, or an isolated worktree alone does not make a worker a separate user-facing task. Asking for subagents does not ask for new sidebar sessions or categories.

This page is an index. Sub-agents are documented on seven pages, one per reader job. Open the page that matches your task.

Page Read it when
Sub-agent slash command You want to inspect a run from chat, or need the completion-delivery rules.
Sub-agent tool reference You are calling sessions_spawn, sessions_yield, or subagents and need parameters.
Thread-bound sub-agent sessions You are binding a sub-agent to a channel thread, or need allowlist and archive rules.
Nested sub-agents and authentication You are building an orchestrator and need depth caps, the announce chain, or auth.
Sub-agent announce You are debugging how a child result reaches the requester.
Sub-agent tool policy You need the tools a sub-agent always loses, or want to narrow them further.
Sub-agent concurrency, recovery, and stopping You are tuning concurrency, recovering after a restart, or stopping a child tree.

Where each section moved

Every section heading, accordion, step, and parameter id from the previous single-page version keeps its anchor here, so an existing link such as /tools/subagents#thread-bound-sessions still resolves. Each entry points at the page that now holds the content.

Related