Designing Your Agent Hierarchy

Why You Need a Hierarchy

The default OpenClaw setup gives you a single agent. It handles everything — your messages, your tasks, your cron jobs. For the first week, that's fine.

Then you start asking it to do more. Research a competitor. Draft a marketing email. Check your server logs. Write a blog post. And you notice: the agent starts losing context. It forgets what you told it yesterday. It mixes up instructions from different tasks. The context window fills up and older information gets compacted away.

A single agent doing everything is like a startup where one person is the CEO, CTO, CMO, and accountant. It works until it doesn't. The breaking point comes faster than you'd expect.

The fix is the same one that works in organizations: specialization with clear ownership.

The CEO Model

My setup runs four agents. One CEO agent owns the mandate and delegates to three direct reports, each with a specific domain.

Bob's Mandate: $100K ARR

The most important design decision is giving your CEO agent a measurable mandate. Not “help me with stuff.” Not “be a useful assistant.” A specific, quantifiable target with a deadline.

Bob's mandate is $100K ARR for SearcherOS by December 2026. Every decision he makes — every task he delegates, every priority he sets — filters through that number. When Riker proposes a marketing initiative, Bob evaluates it against the ARR target. When Bill suggests a feature, Bob asks: does this move the number?

This works because it mirrors how good executives operate. The mandate creates focus. Without it, the agent sprawls — doing a little bit of everything, finishing nothing.

Weekly OKRs

Every Monday, Bob sets weekly OKRs for each direct report. These go into a shared STATUS.md file that all agents can read. Friday, Bob reviews progress against the OKRs and adjusts the following week's priorities.

The OKR cycle does two things. First, it creates accountability — each agent knows exactly what it's supposed to deliver this week. Second, it creates a cadence that prevents drift. Without it, agents tend to fixate on whatever the last instruction was and lose sight of the bigger picture.

Persistent Agents vs. Sub-Agents

OpenClaw supports two types of agents, and understanding when to use each is critical to a clean architecture.

Persistent Agents

These are always-on agents bound to a channel or bot account. Bob, Bill, Riker, and Bridget are all persistent agents. Each has:

• Its own workspace under ~/.openclaw/agents/<agentId>
• Its own SOUL.md defining personality and behavioral rules
• Its own AGENTS.md defining how it interacts with other agents
• Its own memory files and context
• Its own tool permissions (allow/deny lists)

Persistent agents maintain state across sessions. When you message Bill about a bug on Tuesday, he remembers the conversation when you follow up on Thursday (assuming memory is configured correctly — see the Memory & Context Optimization guide).

Sub-Agents

Sub-agents are spawned for a specific task and auto-archived when done. Think of them as contractors: they come in, do the job, deliver the output, and leave.

Use sub-agents when:

• The task is self-contained and doesn't need ongoing context (research a topic, generate a report, analyze a dataset)
• You want to parallelize — the orchestrator spawns multiple sub-agents working on different aspects simultaneously
• The task involves untrusted content and you want sandbox isolation

Use persistent agents when:

• The domain requires accumulated knowledge over time
• The agent needs to maintain relationships (with messaging channel users, for example)
• The role is ongoing and recurring (marketing, product development, operations)

The Workspace Files Every Agent Reads

Every time an agent starts a session, OpenClaw loads its workspace files into the context window. These files are the agent's operating system — they determine how it thinks, what it knows, and how it interacts with you and other agents.

Auto-Created (Always Loaded)

Optional (Loaded When Present)

Plus openclaw.json for configuration (security, LLM provider, memory settings, channel bindings) and memory/YYYY-MM-DD.md daily logs. All bootstrap files consume context window tokens — missing files trigger an injector notification, and large files are truncated at the bootstrapMaxChars limit (default: 20,000 characters).

The quality of these files directly determines the quality of your agents. A vague SOUL.md produces a vague agent. A structured AGENTS.md produces an agent that knows its lane.

Setting Up Your Agents

Agent Workspace Structure

Each persistent agent gets its own directory with its own copy of the core files. Never reuse agentDir across agents — this causes auth and session collisions.

~/.openclaw/agents/
  bob/            # CEO
    SOUL.md       # Personality, mandate, behavioral rules
    AGENTS.md     # Operating instructions, delegation rules
    USER.md       # Owner identity and preferences
    IDENTITY.md   # Agent name, vibe, emoji
    TOOLS.md      # Notes about available tools
    MEMORY.md     # Curated knowledge
    HEARTBEAT.md  # Cron job checklist
    memory/       # Daily logs (YYYY-MM-DD.md)
  bill/           # CTO
    SOUL.md
    AGENTS.md
    USER.md
    IDENTITY.md
    TOOLS.md
    MEMORY.md
    memory/
  riker/          # CMO
    ...
  bridget/        # CCO
    ...
  _shared/        # Shared context across all agents
    STATUS.md     # Weekly OKRs, current priorities
    ROADMAP.md    # Product roadmap
    METRICS.md    # Key business metrics

SOUL.md: The Most Important File You'll Write

Each agent's SOUL.md defines who it is and how it behaves. This is the personality bootstrap — it shapes every response the agent gives. It's also the single biggest leverage point in your entire setup.

Let the AI Interview You

Don't write your SOUL.md in a text editor. Let the agent interview you. Tell it: “I need you to help me write your SOUL.md. Ask me questions about how I want you to behave, what matters to me, how I make decisions, and what tone I expect.”

Go deep. The more specific and honest you are in this interview, the better the agent performs. Tell it about your communication style, your pet peeves, how you handle conflict, what “good work” looks like to you, and what makes you lose trust in an assistant. The AI will synthesize this into a structured personality file that's far more effective than anything you'd write from scratch.

This interview process typically takes 30–60 minutes. It's the single highest-ROI hour you'll spend on OpenClaw.

The Context Window Tradeoff

Here's the tension: a richer SOUL.md produces a better agent, but every word costs context window space. A 2,000-word SOUL.md loaded into every session means less room for the actual conversation and tool results.

The solution is a two-tier approach:

• One reference SOUL.md with everything — your full voice, values, decision-making frameworks, communication preferences, humor calibration, everything the AI extracted from the interview. This is the master document. Keep it in your _shared/ directory.
• Per-agent SOUL.md files that are 60–80% of the reference. Each agent gets the core personality traits plus only the domain-specific instructions it needs. Bob (CEO) gets the decision-making framework and delegation rules. Bill (CTO) gets the quality standards and technical ownership rules. Riker (CMO) gets the brand voice and content guidelines.

The parts that every agent shares: your communication style, core values, how you want to be addressed, your timezone and availability. The parts that vary: domain-specific instructions, tool usage preferences, escalation paths.

For Bob (CEO), the per-agent SOUL.md includes:

• The mandate: $100K ARR by December 2026
• Decision-making framework: evaluate everything against the ARR target
• Communication style: direct, concise, data-driven
• Delegation rules: don't do the work yourself, assign it to the right direct report
• Accountability rules: track OKR progress, flag blockers early

For Bill (CTO), the SOUL.md focuses on:

• Technical ownership: SearcherOS codebase, deployment, monitoring
• Quality standards: test before deploying, document decisions
• Escalation rules: when to flag issues to Bob vs. handle independently

AGENTS.md: Put Critical Instructions at the Top

The AGENTS.md file defines how each agent relates to the others — who it can delegate to, who it reports to, and what it owns. This file is loaded into context every session alongside SOUL.md.

OpenClaw reads this file top-down. If the context window gets tight and compaction kicks in, content at the bottom is more likely to get trimmed. So structure your AGENTS.md with the most critical instructions first:

# AGENTS.md — Bob (CEO)

## CRITICAL RULES (read first)
- You are the CEO. Your mandate is $100K ARR by Dec 2026.
- NEVER do the work yourself. Delegate to the right agent.
- Before starting any task, check STATUS.md for current OKRs.
- Write daily logs before every long session ends.

## Direct Reports
- Bill (CTO): Product development, technical infrastructure
- Riker (CMO): Go-to-market, content, distribution
- Bridget (CCO): Long-form content, brand voice

## Delegation Rules
- Technical tasks → Bill
- Marketing/growth tasks → Riker
- Content creation tasks → Bridget
- Strategy/cross-functional → Handle directly

## Weekly Cadence
- Monday: Set OKRs in STATUS.md
- Friday: Review progress, adjust next week
- Daily: Check in with each report via their channel

Shared Context Between Agents

Agents need to share information without losing their individual context. OpenClaw handles this through two mechanisms:

Symlinked Shared Directory

Create a _shared/ directory and symlink it into each agent's workspace:

mkdir -p ~/.openclaw/agents/_shared
ln -s ~/.openclaw/agents/_shared ~/.openclaw/agents/bob/_shared
ln -s ~/.openclaw/agents/_shared ~/.openclaw/agents/bill/_shared
ln -s ~/.openclaw/agents/_shared ~/.openclaw/agents/riker/_shared
ln -s ~/.openclaw/agents/_shared ~/.openclaw/agents/bridget/_shared

Now any agent can read and write to _shared/STATUS.md, _shared/ROADMAP.md, or any other shared file. When Bob sets weekly OKRs, he writes them to the shared STATUS.md. When Bill checks his priorities, he reads from the same file.

Memory Search Extra Paths

For agents that need to search each other's memories (not just shared files), configure memorySearch.extraPaths:

// In each agent's config:
"memorySearch": {
  "extraPaths": [
    "~/.openclaw/agents/_shared"
  ]
}

This indexes the shared directory's Markdown files into the agent's semantic search. Only .md files are indexed.

The Mistake Everyone Makes

Too many agents too early. I see people in the OpenClaw community spinning up 6, 8, 10 agents in their first week. Each one with a vague role. None of them with a clear mandate.

The result: agents step on each other, context gets fragmented across too many workspaces, and the orchestration overhead becomes a full-time job. You spend more time managing agents than getting work done.

Here's the progression I recommend:

• Week 1: One agent. Learn the tool. Build confidence with the single-agent loop.
• Week 2–3: Add a second agent for your most time-consuming domain (for me, that was marketing). Let the CEO delegate to one direct report.
• Month 2: Add a third agent if the workload justifies it. By now you have a feel for where the bottlenecks are.
• Beyond: Add agents only when you have a clear mandate that can't be handled by an existing agent. If you can't articulate the mandate in one sentence, you don't need the agent yet.

Monitoring at Scale

With 2–4 agents, monitoring is manageable through STATUS.md and your messaging channels. Each agent reports through its own channel, and the CEO agent summarizes status.

At 5+ agents, you need more structure. The community is split between custom dashboards (React + real-time backends) and plug-and-play tools like LobsterBoard. My take: the most useful monitoring features are cost tracking, cron job visibility, and stale-agent alerts — not Kanban boards.

For most people, a Telegram forum channel setup where each agent has its own thread covers 70% of what a dashboard would give you. Start there.

Next Steps

Your agent hierarchy is only as good as its memory. Agents that forget their mandate, lose context mid-conversation, or can't recall last week's decisions will underperform regardless of how well you structure the org chart.

Read the Memory & Context Optimization guide to learn how to configure MEMORY.md, daily logs, pre-compaction flushes, and hybrid search for maximum recall.