A step-by-step guide covering:
- 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.
This commit is contained in:
Andrejs Shorstkin
parent
e4518d2271
commit
da1e40df23
285
docs/multi-agent-setup-telegram.md
Normal file
285
docs/multi-agent-setup-telegram.md
Normal file
@ -0,0 +1,285 @@
|
||||
# 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
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
Loading…
Reference in New Issue
Block a user