diff --git a/docs/multi-agent-setup-telegram.md b/docs/multi-agent-setup-telegram.md new file mode 100644 index 000000000..41a737a2e --- /dev/null +++ b/docs/multi-agent-setup-telegram.md @@ -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 +![Multi-Agent Flow](./multi_agent_flow.md) + +### 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 + } + } + } + } +} +```