ℹ️ Purpose of this doc: Plain-English explanation of what "multiple agents" actually means in OpenClaw — how the gateway works, what separates agents, how memory is (not) shared, and what your cleanest setup would look like for managing multiple projects.

PART 1 — The Core Mental Model

One Gateway. Possibly Many Agents.

Think of it like a building:

┌──────────────────────────────────────────────┐ │ GATEWAY (the building) │ │ One running process on Mac Mini │ │ Manages all connections, routing, channels │ │ │ │ ┌──────────────┐ ┌──────────────────────┐ │ │ │ Agent: main │ │ Agent: coding │ │ │ │ Your brain │ │ A second brain │ │ │ │ (Chief) │ │ (project-focused) │ │ │ │ │ │ │ │ │ │ SOUL.md │ │ SOUL.md (different) │ │ │ │ MEMORY.md │ │ No personal memory │ │ │ │ workspace/ │ │ workspace-coding/ │ │ │ │ sessions │ │ sessions (separate) │ │ │ └──────────────┘ └──────────────────────┘ │ │ │ │ One Telegram bot ─► routed by chat/group │ │ OR two Telegram bots ─► one per agent │ └──────────────────────────────────────────────┘

The key insight

You don't need multiple gateways. One gateway on Mac Mini handles everything. What you're choosing is whether you want one agent (one brain, all contexts) or multiple agents (separate brains, separate memory, separate sessions). The gateway just routes incoming messages to the right agent.

PART 2 — What "An Agent" Actually Is

Each agent has completely isolated:

Component	What it means	Lives where
Workspace	SOUL.md, AGENTS.md, USER.md, MEMORY.md, all project files	~/.openclaw/workspace-{agentId}/
Session history	Every conversation, message by message — never shared with other agents	~/.openclaw/agents/{agentId}/sessions/
Auth profiles	API keys, Google auth, Telegram tokens — not shared by default	~/.openclaw/agents/{agentId}/agent/auth-profiles.json
Persona	Different SOUL.md = different personality, instructions, and tone	Per-workspace
Skills	Can be shared globally or per-agent	Global: ~/.openclaw/skills/

⚠️ Memory is NOT shared between agents. MEMORY.md lives inside each agent's workspace. If you want Agent A to know something Agent B knows, you have to explicitly write it to a shared file or pass it manually. This is intentional isolation — it's a feature.

PART 3 — Telegram Groups = Session Isolation (without multiple agents)

Here's the thing you may not have realized: you already get session isolation just by using different Telegram groups — even with one agent.

OpenClaw keys sessions by chat ID. So:

Your DM with Chief bot ──────► Session key: agent:main:telegram:direct:8447049886 (your current main session) Telegram Group "Fraud Work" ──► Session key: agent:main:telegram:group:-1009876543 (completely separate message history) Telegram Group "EHI Ignite" ──► Session key: agent:main:telegram:group:-1001234567 (another completely separate message history)

What this means practically

If you create a Telegram group called "Fraud Detection" and add the Chief bot, every message in that group = a separate thread. The bot remembers the full history of that group independently from your DM and from every other group. No extra setup needed. The isolation already exists.

What you DON'T get with this approach: the agent loads the same context files (MEMORY.md, SOUL.md, etc.) in every group. So Chief brings your personal memory into the fraud detection group. That's usually fine — but if you want truly isolated context loading (no personal memory, different project files), that's when you'd want a second agent.

PART 4 — When to Use Multiple Agents vs. Multiple Groups

Scenario	Multiple Telegram Groups (one agent)	Multiple Agents
Separate conversation history per project	✅ Works	✅ Works
No context bleed between project threads	✅ Works	✅ Works
Different SOUL/persona per context	✗ Same personality	✅ Works
Keep personal memory OUT of code sessions	✗ Always loads MEMORY.md	✅ Separate workspace
Different tools/permissions per context	✗ Same toolset	✅ Per-agent tool policy
Setup complexity	Minimal — create group, add bot	More setup — new bot, config change
Sharing files between contexts	Easy — same filesystem	Manual — different workspaces

✅ Honest recommendation for you right now: Start with multiple Telegram groups, one agent. Create groups for each active project thread. You get separate histories immediately, no config changes needed. If you later want true context isolation (no personal memory in your coding sessions), we can add a second agent then.

PART 5 — If/When You Add a Second Agent

The "Coding Agent" Setup

This is what a second agent would look like for Blake's setup:

Agent: main (Chief) ─────── Your current bot Workspace: ~/.openclaw/workspace/ Has: MEMORY.md, personal context, ALL projects Good for: personal logistics, strategy, cross-project thinking Agent: coding ───────────── New bot (separate BotFather token) Workspace: ~/.openclaw/workspace-coding/ Has: CLAUDE.md files per project, server configs, NO personal memory Good for: writing code, server management, deploys, technical deep-dives

How the Gateway Routes Messages

You'd add 4 lines to openclaw.json:

agents: {
  list: [
    { id: "main" },                                        // Chief — already exists
    { id: "coding", workspace: "~/.openclaw/workspace-coding" }  // New
  ]
},
bindings: [
  { agentId: "main",   match: { channel: "telegram", accountId: "default" } },
  { agentId: "coding", match: { channel: "telegram", accountId: "coding" } }
]
channels: {
  telegram: {
    accounts: {
      default: { botToken: "YOUR_EXISTING_TOKEN" },
      coding:  { botToken: "NEW_BOT_TOKEN_FROM_BOTFATHER" }
    }
  }
}

Memory Between Agents

Three options:

No sharing (default) — each agent has its own MEMORY.md. Clean isolation. Coding agent knows nothing about your personal life.
Read-only shared facts — put a SHARED-CONTEXT.md in a neutral location both workspaces can read. Contains project locations, server IPs, repo names — just the facts both agents need.
Agent-to-agent messaging — OpenClaw supports explicitly enabling this, but it's overkill for now.

Simplest shared memory pattern

Create ~/.openclaw/shared/PROJECT-MAP.md with just: project names, repo paths, server IPs, and current status. Both agents read it. Chief keeps his full MEMORY.md private. Coding agent has no personal info but knows the technical landscape.

PART 6 — What "Multiple Gateways" Means (You Probably Don't Need This)

A second gateway = a completely separate running process with its own port, config, state dir. This is for:

Running a rescue/debug bot that can fix the main bot if it breaks
Total infrastructure isolation (different server entirely)
Two completely separate users on the same machine with zero sharing

You don't need this. One gateway handles multiple agents just fine. The only reason you'd run two gateways is if you needed one to be a safety net for the other, or if two separate people (not just two contexts for you) needed completely isolated setups on the same machine.

PART 7 — Blake's Recommended Path Forward

Phase	What to do	Complexity
Now	Create Telegram groups for active projects: "Fraud Detection", "EHI Ignite", etc. Add Chief bot. Done.	Zero config changes
Soon	During environment session: add project-specific context files to workspace so Chief loads the right project notes when working in each group.	File organization only
Later	When coding sessions feel polluted by personal context, add the coding agent: new BotFather bot, 4-line config change, separate workspace.	30 min setup
Never (probably)	Second gateway. Unnecessary for your use case.	Overkill

OpenClaw Multi-Agent Explainer · Chief · March 8, 2026 · Source: openclaw/docs/concepts/multi-agent.md + gateway/multiple-gateways.md

🧠 OpenClaw Multi-Agent Architecture