Multi-Agent Setup

Run multiple OpenClaw agents on one gateway, each with its own identity, its own Telegram bot, and its own MemoryRouter vault. Memory separation depends on distinct keys and correct routing; agents resolving to the same fallback key share a vault.

How It Works

OpenClaw supports multiple agents on a single gateway. Each agent gets:

Its own workspace (identity, memory files, skills)
Its own session store (conversation history)
Its own Telegram bot (separate chat interface)
Its own MemoryRouter vault (persistent memory)

One gateway process handles routing, sending messages to the right agent based on bindings.

Prerequisites

Start with a working OpenClaw integration, permission to edit the gateway configuration, and a separate MemoryRouter key for each isolation boundary. Back up the configuration before changing bindings. Telegram bots are one example interface, not a requirement for memory itself.

Step 1: Create Agents

openclaw agents add rex
openclaw agents add mika

This creates isolated workspaces:

~/.openclaw/workspace/          ← main agent
~/.openclaw/workspace-rex/      ← rex
~/.openclaw/workspace-mika/     ← mika

Each workspace has its own IDENTITY.md, USER.md, MEMORY.md, etc.

Step 2: Create Telegram Bots

Each agent needs its own Telegram bot. Go to @BotFather and create one per agent:

/newbot → name it → get the token
Repeat for each agent

Step 3: Wire Up Config

Add agents, bindings, and bot tokens to your openclaw.json:

{
  "agents": {
    "list": [
      { "id": "main", "workspace": "~/.openclaw/workspace" },
      { "id": "rex", "workspace": "~/.openclaw/workspace-rex" },
      { "id": "mika", "workspace": "~/.openclaw/workspace-mika" }
    ]
  },
  "bindings": [
    { "agentId": "main", "match": { "channel": "telegram", "accountId": "default" } },
    { "agentId": "rex", "match": { "channel": "telegram", "accountId": "rex" } },
    { "agentId": "mika", "match": { "channel": "telegram", "accountId": "mika" } }
  ],
  "channels": {
    "telegram": {
      "accounts": {
        "default": { "botToken": "MAIN_BOT_TOKEN" },
        "rex": { "botToken": "REX_BOT_TOKEN" },
        "mika": { "botToken": "MIKA_BOT_TOKEN" }
      }
    }
  }
}

Step 4: Restart and Verify

openclaw gateway restart
openclaw agents list --bindings

Step 5: Give Each Agent Its Own Memory

Create a separate memory key for each agent at app.memoryrouter.ai. Then set up each agent individually.

Configure the explicit agentKeys map

If you prefer managing all keys in one place, use the agentKeys config map:

{
  "plugins": {
    "entries": {
      "mr-memory": {
        "enabled": true,
        "config": {
          "key": "mk_main_key",
          "agentKeys": {
            "rex": "mk_rex_key",
            "mika": "mk_mika_key"
          }
        }
      }
    }
  }
}

How it works:

Every hook resolves the key per-request from ctx.workspaceDir
workspace-rex → looks up agentKeys.rex → hits Rex's vault
If an agent isn't in the map, falls back to the global key
Single-agent setups: zero behavior change

Requires mr-memory v3.4.0+.

Uploading Agent History

Use the --key flag to upload data to any agent's vault from the main terminal:

# Upload Rex's conversation history
openclaw mr upload --key mk_rex_key --brain ~/.openclaw/agents/rex/sessions/

# Upload Rex's workspace files
openclaw mr upload --key mk_rex_key --workspace ~/.openclaw/workspace-rex/

# Check Rex's vault
openclaw mr status --key mk_rex_key

# Clear Rex's vault
openclaw mr delete --key mk_rex_key

The --key flag targets a specific vault without changing your own config. Use it any time you need to upload, check status, delete, or search another agent's vault from the main terminal.

Managing Agent Settings

The plugin's CLI writes gateway plugin configuration. Running a command from an agent chat does not prove it is scoped to that agent. In a shared gateway, manage the explicit agentKeys map centrally and use --key on the commands that support it when targeting status, search, upload, or deletion.

The current density commands are openclaw mr low, openclaw mr medium, and openclaw mr high. They update the shared plugin settings, not an isolated per-agent setting. Review config changes and restart the gateway when necessary.

Key Points

One gateway, multiple agents: one process handles all agents, routing messages based on bindings
Each agent = separate Telegram bot: they show up as different bots to chat with
Isolation is built in: each agent gets its own workspace, session store, and auth
Verify memory isolation: distinct mapped keys separate vaults; missing mappings can fall back to the global key
Bindings are deterministic: most specific match wins (peer > account > channel > default)
You can split by channel: e.g., WhatsApp → fast Sonnet agent, Telegram → Opus deep work agent

Cross-session isolation proof

Give Rex and Mika different keys. In Rex's direct chat, store the synthetic fact "Rex's demo release phrase is ORCHID-7419." Start a fresh Rex conversation and ask for that phrase without supplying it; confirm recall. In Mika's fresh chat, ask the same question and inspect the actual memory search result: it must not contain Rex's fact.

Also test any custom workspace names. The plugin derives map keys from the workspace directory name (workspace-rex becomes rex), not simply from the Telegram bot name. Repeat the proof after routing changes.

Limitations and troubleshooting

If both agents recall the fact, inspect agentKeys, the workspace basename, and fallback key resolution before sharing private data.
Separate Telegram bots or sessions do not automatically create separate MemoryRouter vaults.
A fresh model answer alone is not an isolation test: inspect the retrieval result, with synthetic data only.
A key is a credential for a vault. Anyone or any tool with that key can access the allowed data; keep it out of repositories and chat logs.
This recipe is an OpenClaw deployment guide, not a separate MemoryRouter protocol or automatic tenant-provisioning feature.

Next steps

View the integration · Create an account · All integrations

Multi-Agent Setup

On this page