openclaw/docs/multi-agent-setup-telegram.md

Multi-Agent System Setup Guide (Telegram)

This guide provides a comprehensive, step-by-step walkthrough to setting up a Multi-Agent Moltbot system from scratch, using Telegram as the interface.

1. Prerequisites

Before you begin, ensure you have:

1. Node.js 18+ installed.
2. Moltbot repository cloned and dependencies installed (npm install).
3. Two Telegram Bot Tokens:
   • Talk to @BotFather on Telegram.
   • Create two separate bots (e.g., my_support_bot and my_sales_bot).
   • Save their tokens.
4. Telegram User IDs:
   • Talk to @userinfobot to get your numeric ID (e.g., 12345678).
   • Get the IDs for any other users you want to allow.
5. LLM API Keys:
   • OpenAI API Key (if using GPT-4o).
   • Google Gemini API Key (if using Gemini).

2. Configuration Steps

All configuration happens in your ~/.moltbot/config.json5 file (or config.json5 in the project root).

Tip

: You can also edit this configuration directly in the Moltbot UI by switching to Raw Mode in the settings.

Step 1: Define Global Defaults

Set up your default models so you don't have to repeat them for every agent.

agents: {
  defaults: {
    model: {
      primary: "google/gemini-3-flash-preview",
      fallbacks: ["openai/gpt-5-nano"]
    }
  }
}

Step 2: Create Agents

Define the "brains" of your system. Each agent gets its own workspace and memory.

agents: {
  list: [
    { id: "agent_1", name: "User 1 Assistant" },
    { id: "agent_2", name: "User 2 Assistant" }
  ]
}

Step 3: Configure Telegram Accounts

Add your bot tokens. Use allowFrom to restrict who can talk to which bot.

channels: {
  telegram: {
    enabled: true,
    accounts: {
      bot_one: { // Internal alias for the first bot
        botToken: "YOUR_FIRST_BOT_TOKEN",
        dmPolicy: "allowlist",
        allowFrom: ["USER_1_TELEGRAM_ID"]
      },
      bot_two: { // Internal alias for the second bot
        botToken: "YOUR_SECOND_BOT_TOKEN",
        dmPolicy: "allowlist",
        allowFrom: ["USER_2_TELEGRAM_ID"]
      }
    }
  }
}

Step 4: Bind Agents to Bots

Connect the brains (Agents) to the bodies (Bots).

bindings: [
  // Route messages from "bot_one" to "agent_1"
  {
    agentId: "agent_1",
    match: { channel: "telegram", accountId: "bot_one" }
  },
  // Route messages from "bot_two" to "agent_2"
  {
    agentId: "agent_2",
    match: { channel: "telegram", accountId: "bot_two" }
  }
]

3. Running the System

Start the gateway:

clawdbot gateway --port 18789

• Status Check: The logs will show both agents initializing. You should see output similar to this:

16:29:09 [gateway] agent model: google/gemini-3-flash-preview
16:29:09 [gateway] listening on ws://127.0.0.1:18789
16:29:10 [hooks] loaded 3 internal hook handlers
16:29:10 [telegram] [user1_bot] starting provider (@User1_Assistant_Bot)
16:29:11 [telegram] [user2_bot] starting provider (@User2_Assistant_Bot)

• Memory: Upon the first message, Moltbot will create ~/clawd/agents/agent_1/MEMORY.md and ~/clawd/agents/agent_2/MEMORY.md.

4. Architecture & Isolation

Visual Flow

Privacy Model

• Memory: ISOLATED. Agent 1 cannot see Agent 2's memory files. They live in separate folders.
• Cron Jobs: SHARED VISAIBILITY. Agents can see the global schedule of tasks but ISOLATED EXECUTION. A job scheduled by Agent 1 executes as Agent 1.

5. Complete Configuration Example

Here is a complete, configuration file based on a working setup. Copy this and replace the placeholder values.

{
    "meta": {
        "lastTouchedVersion": "2026.1.24-3",
        "lastTouchedAt": "2026-01-27T15:46:51.393Z"
    },
    "wizard": {
        "lastRunAt": "2026-01-27T15:46:51.384Z",
        "lastRunVersion": "2026.1.24-3",
        "lastRunCommand": "onboard",
        "lastRunMode": "local"
    },
    "auth": {
        "profiles": {
            "google:default": {
                "provider": "google",
                "mode": "api_key"
            }
        }
    },
    "agents": {
        "defaults": {
            "model": {
                "fallbacks": [
                    "openai/gpt-5-nano"
                ],
                "primary": "google/gemini-3-flash-preview"
            },
            "models": {
                "google/gemini-3-flash-preview": {
                    "alias": "gemini"
                },
                "openai/gpt-5-nano": {}
            },
            "workspace": "/home/clawbot/clawd",
            "maxConcurrent": 4,
            "subagents": {
                "maxConcurrent": 8
            }
        },
        "list": [
            {
                "id": "agent_1",
                "name": "User 1 Assistant"
            },
            {
                "id": "agent_2",
                "name": "User 2 Assistant"
            }
        ]
    },
    "bindings": [
        {
            "agentId": "agent_1",
            "match": {
                "channel": "telegram",
                "accountId": "user1_bot"
            }
        },
        {
            "agentId": "agent_2",
            "match": {
                "channel": "telegram",
                "accountId": "user2_bot"
            }
        }
    ],
    "messages": {
        "ackReactionScope": "all"
    },
    "commands": {
        "native": "auto",
        "nativeSkills": "auto"
    },
    "channels": {
        "telegram": {
            "enabled": true,
            "streamMode": "off",
            "accounts": {
                "user1_bot": {
                    "botToken": "REPLACE_WITH_USER_1_BOT_TOKEN",
                    "dmPolicy": "allowlist",
                    "allowFrom": [
                        "REPLACE_WITH_USER_1_ID"
                    ],
                    "groupPolicy": "allowlist"
                },
                "user2_bot": {
                    "botToken": "REPLACE_WITH_USER_2_BOT_TOKEN",
                    "dmPolicy": "allowlist",
                    "allowFrom": [
                        "REPLACE_WITH_USER_1_ID",
                        "REPLACE_WITH_USER_2_ID"
                    ],
                    "groupPolicy": "allowlist"
                }
            }
        }
    },
    "gateway": {
        "port": 18789,
        "mode": "local",
        "bind": "loopback",
        "auth": {
            "mode": "token",
            "token": "REPLACE_WITH_YOUR_GATEWAY_TOKEN"
        },
        "tailscale": {
            "mode": "off",
            "resetOnExit": false
        }
    },
    "skills": {
        "install": {
            "nodeManager": "npm"
        },
        "entries": {
            "nano-banana-pro": {
                "enabled": true,
                "apiKey": "REPLACE_WITH_YOUR_API_KEY"
            },
            "clawdhub": {
                "enabled": true
            },
            "coding-agent": {
                "enabled": false
            },
            "goplaces": {
                "enabled": true,
                "apiKey": "REPLACE_WITH_YOUR_API_KEY"
            },
            "skill-creator": {
                "enabled": true
            }
        }
    },
    "plugins": {
        "entries": {
            "telegram": {
                "enabled": true
            }
        }
    },
    "hooks": {
        "internal": {
            "enabled": true,
            "entries": {
                "session-memory": {
                    "enabled": true
                },
                "command-logger": {
                    "enabled": true
                },
                "boot-md": {
                    "enabled": true
                }
            }
        }
    }
}