Multi-Agents in OpenClaw: Sub-Agents + Telegram Setup

If you are new to OpenClaw, we recommend starting with our first OpenClaw installation guide. It covers the simplest possible setup to get you “on board” quickly: install OpenClaw on a VM and create your first agent.

Start here: our first OpenClaw installation guide.

In this article, we share how we run OpenClaw with multiple agents, sub-agents, and Telegram bots. This is not “the right way” to do it, it is simply our approach at CDNsun. If you like it, feel free to copy it. If you do it differently, that is perfectly fine.

One reason we are writing this: from what we see in our social media feeds, more and more technical people are moving from “AI curiosity” to “AI workflows”, and OpenClaw comes up a lot in that transition. It feels like the start of a broader agentic boom: not because one tool magically changes everything, but because it makes a previously abstract idea practical. The fact that OpenClaw is open source helps a lot here, it lowers friction for experimentation and makes it easier for the community to share and iterate.

This post is focused on the multi-agent layer: using a main agent as a conductor, and delegating work to specialist sub-agents.

Definitions (so we do not overload words)

Before we use terms like “agent”, “sub-agent”, and “session”, here is what we mean in concrete terms.

Agent

An agent basically means:

a workspace directory: workspace-AGENTNAME/
a directory in .openclaw/agents/AGENTNAME/ with access information for the LLM API and a sessions directory
a bit of config in .openclaw/openclaw.json

When we say “config” in this article, we always mean:

.openclaw/openclaw.json

Session

A session is the conversation history on disk (a text file). For example, the main agent’s sessions live under something like .openclaw/agents/main/sessions/. This is extremely useful for debugging, especially because “agentic programming” can be harder to reason about than traditional code. When output changes and you feel like you “did not change anything”, the session file lets you inspect what actually happened, including the prompts and the chain of messages that led to the result.

Sub-agent

A sub-agent is an agent spawned by another agent (typically the main agent) to do a specific task. A sub-agent is not a special entity, it is just a normal OpenClaw agent running in a delegated role.

Binding

A binding connects an inbound channel/account (for example Telegram) to a specific agentId. In other words: bindings decide which agent receives which messages.

Our topology: main + coder + tester

In our setup we use three agents:

main (the one we talk to most of the time)
coder (implementation work)
tester (validation, edge cases, second opinions)

coder and tester are intended to be sub-agents of main. We can still chat with all agents directly (including over Telegram), but operationally we want the main agent to behave like a conductor: it delegates, collects results, and decides what to do next.

One rule that keeps the system stable:

coder and tester do not communicate with each other directly
if they need to coordinate, the main agent is the relay

This keeps the graph simple and makes debugging much easier.

Creating agents fast (and checking the model)

To bootstrap a new agent, we typically use:

openclaw agents add AGENTNAME

That command creates the on-disk structure and adds a config entry. After that, we check .openclaw/openclaw.json to confirm which model is configured for each agent.

Example:

{
  "id": "tester",
  "name": "tester",
  "workspace": "/home/david/.openclaw/workspace-tester",
  "agentDir": "/home/david/.openclaw/agents/tester/agent",
  "model": "openai/gpt-5.2"
},
{
  "id": "coder",
  "name": "coder",
  "workspace": "/home/david/.openclaw/workspace-coder",
  "agentDir": "/home/david/.openclaw/agents/coder/agent",
  "model": "openai/gpt-5.2"
}

Note: you may see a username like david in example paths. Substitute your own.

Required config: agent-to-agent, session visibility, and sub-agent spawning

Multi-agent setups usually fail for two boring reasons: the agents cannot talk to each other, or the main agent is not allowed to spawn sub-agents. We enable both explicitly.

Let agents communicate (and optionally see sessions)

If we want agent-to-agent communication, and if we want the main agent to be able to inspect other agents’ sessions (useful for debugging), we use this in .openclaw/openclaw.json:

"tools": {
  "profile": "full",
  "sessions": {
    "visibility": "all"
  },
  "agentToAgent": {
    "enabled": true,
    "allow": [
      "*"
    ]
  }
}

Operational note: we show "*" for simplicity in the example. In a stricter production setup, we recommend allowlisting only the specific agent IDs that should be able to talk to each other.

Allow the main agent to spawn sub-agents

Spawning is disabled by default. We allow it by allowlisting which agents the main agent may spawn.

In the agents section:

{
  "id": "main",
  "subagents": {
    "allowAgents": [
      "coder",
      "tester"
    ]
  }
}

We also tune global sub-agent limits when needed:

"maxConcurrent": 4,
"subagents": {
  "maxConcurrent": 8,
  "maxSpawnDepth": 2,
  "maxChildrenPerAgent": 8,
  "runTimeoutSeconds": 900
}

Notably, you want maxSpawnDepth > 1 to be able to spawn sub-agents.

A precise warning about sub-agent context

Be aware that sub-agents, by default, may not load all personality files (SOUL.md, USER.md, IDENTITY.md, TOOLS.md, MEMORY.md, AGENTS.md). Sub-agents also have their own sessions. If you want the main agent to see sessions of other agents (mostly for debugging purposes), you need session visibility in config (as shown above).

In practice: do not assume a sub-agent “knows what the main agent knows” unless you intentionally share that context.

Telegram: one bot per agent + bindings

We will not go through Telegram basics here (creating a Telegram bot via @BotFather, finding your Telegram ID via @IDBot, etc.).

For multi-agent Telegram, we do this:

one Telegram bot token per agent
one OpenClaw Telegram account entry per agent under telegram.accounts
bindings that map agentId to the Telegram accountId

Example shape:

"telegram": {
  "accounts": {
    "main": {
      "dmPolicy": "allowlist",
      "botToken": "secretstring from @BotFather",
      "allowFrom": [
        "YOUR TELEGRAM ID"
      ],
      "groupAllowFrom": [
        "YOUR TELEGRAM ID"
      ],
      "groupPolicy": "allowlist",
      "streaming": "off"
    },
    "tester": {
      "dmPolicy": "allowlist",
      "botToken": "secretstring from @BotFather",
      "allowFrom": [
        "YOUR TELEGRAM ID"
      ],
      "groupAllowFrom": [
        "YOUR TELEGRAM ID"
      ],
      "groupPolicy": "allowlist",
      "streaming": "off"
    }
  }
}

And bindings:

"bindings": [
  {
    "agentId": "main",
    "match": {
      "channel": "telegram",
      "accountId": "main"
    }
  },
  {
    "agentId": "tester",
    "match": {
      "channel": "telegram",
      "accountId": "tester"
    }
  }
]

With this in place, you effectively get multiple Telegram “inboxes”, one per agent.

Personality files: where most long-term value comes from

Once the multi-agent wiring works, most of the real work is not JSON. It is the personality files:

SOUL.md
USER.md
IDENTITY.md
TOOLS.md
MEMORY.md
AGENTS.md

OpenClaw takes the Markdown hierarchy seriously. Use clean sections and subsections, and treat those files as real configuration.

In our setup we keep some files shared across agents, and some intentionally different:

shared: AGENTS.md, SOUL.md, USER.md
per-agent: IDENTITY.md, TOOLS.md, MEMORY.md

When a snippet contains a name like USER-david.md, read it as an example naming convention, not as a requirement.

Our helper tool: openclaw-multi-agent-tool

Because we wanted a good overview and a clean way to propagate shared personality files, we built openclaw-multi-agent-tool.

You can keep it in .openclaw/personality-files/ alongside files like AGENTS-all.md, SOUL-all.md, and USER-david.md.

The scripts compare personality files across agents and can push the shared ones into sub-agent workspaces, so you do edits in one place and propagate them. We tried symlinks first, but in our testing OpenClaw ended up ignoring some of the files, so we switched back to explicit copies.

Wrap-up: how do you run OpenClaw?

That is the full picture of our current multi-agent setup: a main agent acting as a conductor, specialist sub-agents, and optional Telegram access per agent.

We are curious how other teams run OpenClaw in practice:

Do you use sub-agents who talk with each other?
Or do they only talk with the master (main agent), like in our setup?
Or do you just have multiple agents and they all talk only to you?

And by the way: we operate a Content Delivery Network at CDNsun. If you want to accelerate your website or stream content faster, you can sign up for a free trial.

Multi-agents in OpenClaw: sub-agents and Telegram