da1e40df23
- Architecture overview with improved diagram referencing. - Configuration of multiple independent agents (User 1 & User 2). - Setup of dual Telegram bots with strict allow-list security. - Explanation of Bindings to route specific bots to specific agents. - Detailed breakdown of isolation models (Memory vs. Cron). - A complete, copy-pasteable anonymized [config.json5]. This guide aims to simplify the onboarding process for users deploying Moltbot in a multi-user, multi-agent environment.
286 lines
7.7 KiB
Markdown
286 lines
7.7 KiB
Markdown
# 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](https://t.me/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](https://t.me/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.
|
|
|
|
```json5
|
|
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.
|
|
|
|
```json5
|
|
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.
|
|
|
|
```json5
|
|
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).
|
|
|
|
```json5
|
|
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:
|
|
```bash
|
|
clawdbot gateway --port 18789
|
|
```
|
|
|
|
* **Status Check**: The logs will show both agents initializing. You should see output similar to this:
|
|
|
|
```text
|
|
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.**
|
|
|
|
```json5
|
|
{
|
|
"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
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|