🤝 Multi-Agent Team with OpenClaw

You might already use one OpenClaw assistant for chat, research, or automation. But what if you could run several—each with its own role, memory, and schedule—that coordinate like a team? That’s what a multi-agent setup is about. This guide walks you through the ideas and steps so you can replicate it yourself.

If you’re thinking “can’t I just run multiple OpenClaw instances?”—yes. That’s the core idea. One Gateway, multiple sessions. Each session is one “agent” with its own identity. This page shows you how to design and run that kind of squad.

Single assistants are great, but they often lack continuity. Every conversation can feel like a reset. The research from last week? Buried in a thread. The task you delegated? No shared view of who’s doing what.

With multiple agents you get:

• Continuity — Each agent has its own conversation history and memory, so context carries over.
• Roles — One agent can be your “researcher,” another your “writer,” another “analyst.” Constraints help each one stay focused.
• Coordination — When agents share a task list or workspace, they can hand off work and you see progress in one place.
• Efficiency — You can wake agents on a schedule (e.g. every 15 minutes) instead of leaving them always-on, which helps with cost and focus.

Think of it as turning one powerful assistant into a small team that knows its roles and checks in regularly.

Agents don't wake on schedule: Check that cron is actually running (e.g. openclaw cron jobs or system crontab). Stagger heartbeats so they don't all fire at once—that can overload the Gateway or your LLM quota.

Agents can't see the shared task list: If you're using Convex, Notion, or files, make sure the workspace path or API access is correct and that each agent's prompt (e.g. AGENTS.md) tells it where to look. A typo in the path is a common mistake.

Too expensive or too slow: Use a cheaper model for heartbeat "check and report" steps; reserve the expensive model for real work. Also consider longer intervals (e.g. 30 minutes instead of 15) if cost is an issue.

OpenClaw’s sessions are the building block. Each session is a persistent conversation with its own context. So “multiple agents” really means “multiple sessions,” each with a distinct identity and (optionally) its own workspace and personality.

The Gateway runs as a single process. It routes messages to the right session, runs cron jobs, and keeps everything in sync. You don’t need ten separate OpenClaw installs—you configure multiple session keys and point them at different roles.

Each agent needs a unique session key so the Gateway knows where to route messages. Session keys follow a pattern like agent:role:main. For example:

• agent:main:main — Your primary coordinator (e.g. “Jarvis”)
• agent:researcher:main — Research specialist
• agent:writer:main — Content or copy specialist
• agent:analyst:main — Data or SEO analyst

When you send a message to a specific session, only that agent sees it. Histories stay separate, so each agent keeps its own context. You can define these in your config and use the CLI to send messages to a given session (see CLI Reference for sessions send and related commands).

An agent that’s “good at everything” often ends up generic. Giving each one a clear role and tone focuses them. Many users do this with a SOUL file (or similar) in the workspace: who the agent is, what they’re good at, and how they should behave. Soul shapes behavior more than skills or memory: memory is documentation; soul is who the agent is. To change how the agent acts, change the soul—and put it first in the system prompt so the model actually weights it (see Soul & Agent Identity). Describe roles experientially ("I’ve learned that… because…") rather than as flat rules; that tends to produce more consistent, expert-like output.

Example idea for a “Researcher” agent:

• Role: find and summarize information, cite sources.
• Personality: thorough, skeptical, evidence-first.
• Scope: research and reports only; no creative writing or final decisions.

When you spawn sub-agents (e.g. for a one-off task), don't give them a full identity—give them values and a precise task. "Values inherit, identity does not." For example: "You are a code security auditor. Apply these standards: [list]. Your task: review this module." A shared AGENTS.md can describe where files live, how memory works, and how to use the shared task system so every agent follows the same operating rules. For more on memory and workspace layout, see Memory and Memory Management.

Leaving every agent always-on can be expensive and noisy. A common pattern is heartbeats: a cron job that wakes an agent every N minutes, has it check for new tasks or @mentions, do work if needed, then “go back to sleep.”

You schedule this with OpenClaw’s cron (or your system cron calling the CLI). For example, “every 15 minutes” for a given session, with a message like: “You are [Agent Name]. Check the shared task list and your WORKING.md. If there’s nothing urgent, reply HEARTBEAT_OK.”

Stagger the times so not all agents wake at once (e.g. one at :00, one at :05, one at :10). That spreads load and avoids API spikes. Use a cheaper model for these routine checks if you can; save stronger models for real creative or complex work.

Independent agents only become a team when they share context. Builders often add a simple “mission control” layer:

• Shared task list — Inbox, in progress, review, done. Can be a Notion board, a Convex/DB table, a spreadsheet, or even markdown files in a shared folder.
• Comments or activity feed — So agents (and you) can see what’s happening and who said what.
• @mentions or notifications — So you can ping a specific agent (“@Researcher check this”) and they see it on their next heartbeat.

OpenClaw doesn’t ship this out of the box—it gives you the sessions, cron, and tools. The “shared brain” (task DB, UI, notifications) is something you add with any stack you like: Convex, Notion API, Airtable, or simple files that agents read and write. One concrete pattern that works well is a single shared directory symlinked into every agent’s workspace so they all read and write the same files (priorities, agent outputs, feedback). No agent-to-agent messaging—just one folder, same inode. Step-by-step: Shared context for multi-agent teams. For high-stakes decisions, use multi-soul review: route important outputs through a second agent (or session) with a different soul that critiques or validates the first—see Soul & Agent Identity.

Agents that wake on a schedule need to remember what they were doing. “Mental notes” in chat don’t survive restarts; only files do. Common patterns:

• WORKING.md — Current task, status, next steps. The agent updates it and reads it on wake.
• Daily notes — e.g. memory/2026-02-03.md for a simple log of what happened that day.
• Long-term memory — A MEMORY.md or similar for stable facts and decisions.

If you want an agent to remember something, have it write to a file. For full details, see Memory and Memory Management.

You have two main options:

1. Direct session messaging — Use the CLI to send a message from one “agent” to another’s session (e.g. “Vision, can you review this?”). The recipient sees it in their next wake or when they’re active.
2. Shared database or board — Agents post comments and updates to a shared task/comment system. Everyone reads from the same place; no need to message each session directly.

Many setups use both: a shared board for tasks and comments, plus occasional direct messages for urgent pings.

A practical path:

1. Install and run OpenClaw — Follow Installation and Getting Started. Get one Gateway running and one channel (e.g. Telegram) connected.
2. Create two agents first — One coordinator (your main chat), one specialist (e.g. researcher or writer). Define two session keys and give each a small SOUL/role description in the workspace.
3. Add heartbeat crons — Schedule the specialist to wake every 15 minutes (or so), with a message that tells them to check a shared task list or WORKING.md and report back.
4. Introduce a shared task system — Even a simple list (Notion, spreadsheet, or markdown) where you assign tasks and agents update status. Once that works, you can add more agents and stagger their heartbeats.

As you add agents, keep heartbeats staggered, consider a simple UI for the task board, and add @mentions or notifications when you need to direct work to a specific agent. For a deeper dive on sessions and routing, see Sessions & Multi-Agent Routing; for cron and automation, see Automation and Task Automation.

People who run multi-agent setups often suggest:

• Start with 2–3 agents — Get the flow right before scaling to many.
• Use cheaper models for heartbeats — Routine “check and report” work doesn’t need the most expensive model.
• Put important state in files — If it’s not in a file, it may not survive the next restart.
• Let roles be specific — “The skeptical tester” or “the writer who cares about voice” often works better than “generalist.”

The tech is only part of it. Treating each agent as a team member with a clear role, memory, and a shared view of work tends to make the system much more useful.