Agents vs Sub-Agents

Fresh OpenClaw

Use persistent agents for ownership and sub-agents for focused bursts of parallel work.

Visual breakdown of spawning patterns, session lifecycle, memory isolation, and real examples from a multi-agent fleet.

---

Two different tools for two different jobs. Here is how they actually work.

• Agent - a persistent brain with its own everything.
• Sub-Agent - a temporary worker, spawned for one task.

From the official docs

"An agent is a fully scoped brain with its own workspace, its own state directory, and its own session store."

"Spawn a sub-agent run in an isolated session. Sub-agents default to the full tool set minus session tools."

The analogy

An agent is like hiring a new employee. They get their own desk, their own computer, their own login credentials, their own filing cabinet. Nothing shared unless you explicitly set it up.

A sub-agent is like handing a sticky note to your employee: "go do this thing and come back." They use YOUR desk, finish the job, hand you the result, and the sticky note goes in the trash.

Workspace structure

Agent workspace (~/.openclaw/workspace-gary/):

SOUL.md       - personality & voice
IDENTITY.md   - name, role, emoji
USER.md       - who they serve
AGENTS.md     - behavior rules
TOOLS.md      - available tools
MEMORY.md     - long-term memory
HEARTBEAT.md  - periodic checks
memory/       - daily logs
skills/       - agent-specific skills

~/.openclaw/agents/gary/
  agent/      - auth profiles, config
  sessions/   - chat history

Sub-agent workspace uses the parent agent's workspace. It has no own SOUL.md, IDENTITY.md, USER.md, AGENTS.md, TOOLS.md, MEMORY.md, HEARTBEAT.md, daily logs, or session store. Instead it:

• Gets a temporary session ID
• Can read the parent's workspace files
• Auto-archives the session after roughly one hour

Key characteristics

Agent (persistent):

• Own workspace - separate folder with its own SOUL.md, MEMORY.md, and all identity files. Isolated from other agents.
• Own session store - chat history lives at ~/.openclaw/agents/<id>/sessions/, completely separate from other agents.
• Own auth profiles - each agent reads from its own auth-profiles.json. Main agent credentials are NOT shared automatically.
• Own skills - per-agent skills via the workspace skills/ folder, plus shared skills from ~/.openclaw/skills.
• Own channel bindings - routed via bindings in openclaw.json. Can have its own Telegram bot, Discord bot, or WhatsApp number.
• Grows over time - memory files accumulate, identity evolves. The agent remembers what it did yesterday, last week, last month.

Sub-agent (temporary):

• Spawned via sessions_spawn - created on-demand by a parent agent. Gets a task prompt, does the work, reports back.
• No own workspace - runs inside the parent agent's workspace. No separate SOUL.md, MEMORY.md, or identity files.
• Auto-archived - session gets a throwaway UUID key and is automatically archived. No persistence between spawns.
• No session tools - can't spawn its own sub-agents, can't list or send messages to other sessions. No nesting.
• Task-scoped - designed for one-off jobs: research, write a draft, run a calculation, generate a report.
• Auto-announces - when done, the result is automatically announced back to the parent's chat channel.

Session key format:

agent:gary:main
agent:main:subagent:a3f7c...

Real examples (Clearmud org)

Persistent roles:

• Gary - CMO, marketing strategy & content
• Elon - CTO, engineering & infrastructure
• Warren - CRO, revenue & growth
• Clay - Discord community bot

One-off tasks:

• "Write the Ep.2 script" - spawned by Gary, done in 5 min
• "Research competitor channels" - spawned by Muddy, auto-archived
• "Fix the CSS bug on line 42" - spawned by Elon, result returned
• "Generate morning brief" - spawned by cron, delivered to chat

When to use which

Use an agent when:

• It needs a persistent identity & personality
• It must remember things between sessions
• It maintains its own files over time
• It has its own communication channel
• It is a role, not a task

Use a sub-agent when:

• The job has a clear start and end
• It does not need to remember anything tomorrow
• You want to stay available while it works
• It is a task, not a role
• You would write it on a sticky note

Side-by-side comparison

	Agent	Sub-Agent
Lifecycle	Persistent, lives forever	Temporary, auto-archives
Workspace	Own, isolated folder	None, uses parent's
Memory files	Own SOUL.md, MEMORY.md, etc.	None, no persistence
Session store	Own, full history	None, throwaway UUID
Auth profiles	Own, per-agent auth	None, inherits parent's
Can spawn others	Yes, full session tools	No, session tools disabled
Configured in	openclaw.json	sessions_spawn()
Session key	agent:gary:main	agent:main:subagent:uuid

Workflow: how requests flow through agents and sub-agents

Real example from the Clearmud org: what happens when a frontend bug report comes in.

Scenario: "Fix the dashboard CSS bug on the Ops page"

flowchart TD
    H[Human Marcelo - Telegram] --> M[Muddy AGENT - COO]
    M -->|sessions_send| E[Elon AGENT - CTO]
    E -->|sessions_spawn| P[Pixel Sub-Agent - frontend]
    P -->|result announced| E
    E --> M
    M -->|reports completion| H

1. Human (Marcelo) sends a Telegram message: "Fix the CSS bug on the Ops dashboard sidebar." The Telegram binding routes it to the main agent.
2. Muddy (COO agent) identifies it as engineering work: "This is frontend work. Elon handles engineering. I'll delegate." Calls sessions_send to Elon's agent session.
3. Elon (CTO agent) reads from his own workspace, identifies the frontend task. He has his own SOUL.md, MEMORY.md, and engineering skills. Routes to Pixel by calling sessions_spawn with a task prompt.
4. Pixel (temporary sub-agent, frontend specialist) uses Elon's workspace, reads the codebase, edits OpsChat.css, tests the fix, and returns the result to Elon.
5. The result is auto-announced back up the chain. Muddy reports completion to the human via Telegram. The sub-agent session is archived, Elon's memory is updated, and Muddy closes the loop.

Key distinction:

• Agent-to-agent = sessions_send (persistent sessions, both have their own workspace)
• Agent-to-sub-agent = sessions_spawn (temporary, uses the parent's workspace)

Scenario: "Research what competitors posted this week"

Here Muddy spawns directly with no department hop: the human messages Muddy, Muddy calls sessions_spawn directly, a research sub-agent browses competitor channels and returns findings, and the result is announced to Telegram. Muddy stays available the entire time and the sub-agent is archived when done.

Agents + skills: where the real power lives

Skills are reusable instruction sets that give agents (and their sub-agents) specialized capabilities.

Skills on agents live in the agent's workspace/skills/ folder. They are loaded on every session and available to the agent AND any sub-agents it spawns.

~/workspace-elon/skills/
  deploy-checklist/   used by Elon on every deploy
  security-audit/     available to Sentry sub-agent
  nightly-build/      used by cron, runs as sub-agent

• Persistent context - the agent reads the skill every session. It becomes part of how the agent thinks and operates.
• Inherited by sub-agents - when Elon spawns Pixel, Pixel can read skills from Elon's workspace.
• Shared skills too - skills in ~/.openclaw/skills/ are available to ALL agents on the server.

Skills for sub-agents: sub-agents do not have their own skills folder, but you can create skills designed for sub-agent use and reference them in the spawn prompt.

~/workspace-elon/skills/
  frontend-patterns/   Pixel reads this on spawn
  backend-patterns/    Anvil reads this on spawn
  security-audit/      Sentry reads this on spawn

• Prompt instructs the skill - "Read skill X, then do the task." The sub-agent follows the skill instructions for that run.
• Consistent quality - every time Pixel spawns, it reads the same frontend patterns. No drift, no forgotten conventions.
• Update once, all spawns benefit - change the skill file and every future sub-agent spawn picks up the update.

When to create a skill for an agent vs a sub-agent

Agent-level skill when the agent uses it across many sessions, it defines how the agent operates (e.g. morning brief, exec sync), it involves ongoing process rather than a one-shot task, or multiple sub-agents might reference it. Example: an executive-briefing skill on Muddy, used every morning by cron, defining the entire brief format, delivery channels, and QA checks.

Sub-agent specialist skill when it codifies how a specific type of task should be done, it is referenced in the sessions_spawn prompt, different sub-agents need different instructions, or you want repeatability without the overhead of a full agent. Example: a frontend-patterns skill in Elon's workspace that Pixel reads on every spawn, containing component conventions, CSS rules, and testing requirements.