How to Add a Second Agent with Its Own Telegram Bot

One Gateway, two agents, two Telegram bots — each with its own personality, workspace, and conversation history. And the best part? Your existing agent does all the heavy lifting.

What You'll End Up With

Agent 1 (your existing agent) → Your current Telegram bot
Agent 2 (new agent) → A brand new Telegram bot
Both run on the same machine, same Gateway process
Completely isolated: separate workspaces, sessions, and personas

Step 1: Create a New Telegram Bot

This is the only manual step:

Open Telegram and search for @BotFather
Send /newbot
Choose a display name (e.g. "My Research Agent")
Choose a username (e.g. my_research_agent_bot)
Copy the bot token — you'll need it in Step 2

Step 2: Tell Your Agent to Set It Up

Open a chat with your existing OpenClaw agent (Telegram, TUI, or webchat) and tell it what you want. For example:

"I want to add a second agent called Research Agent. Here's the new Telegram bot token: 8207035398:AAFpWzPmvU6VlHWySY4MDATy0YvaS5WNLrY"

Your agent will:

Add the new agent to agents.list in your config with its own workspace
Convert your Telegram config from a single bot token to multi-account
Add bindings so each Telegram bot routes to the correct agent
Restart the Gateway to apply changes

You'll see it work through the config patch and confirm when the restart is complete.

Step 3: Pair with Your New Bot

Open Telegram
Search for your new bot's username
Send /start
If dmPolicy is set to "pairing" (the default), you'll need to approve the pairing from your main agent or Gateway logs

Step 4: Customize Your New Agent

Ask your main agent to help set up the new agent's personality, or do it yourself. The new agent has its own workspace (e.g. ~/.openclaw/workspace-research/). Create these files there:

SOUL.md — Who is this agent? Its personality and tone.
AGENTS.md — Operating instructions and conventions.
USER.md — Info about you (the human) for context.

The new agent starts with a blank slate — no shared memory or context with your main agent.

What Happens Under the Hood

For the curious, here's what your agent changes in ~/.openclaw/openclaw.json:

Adds the agent:

"agents": {
  "list": [
    { "id": "main", "default": true, "name": "My Assistant", "workspace": "~/.openclaw/workspace" },
    { "id": "research", "name": "Research Agent", "workspace": "~/.openclaw/workspace-research" }
  ]
}

Converts Telegram to multi-account:

"channels": {
  "telegram": {
    "dmPolicy": "pairing",
    "groupPolicy": "allowlist",
    "streamMode": "partial",
    "accounts": {
      "default": { "botToken": "YOUR_EXISTING_TOKEN" },
      "research": { "botToken": "YOUR_NEW_TOKEN" }
    }
  }
}

Adds routing bindings:

"bindings": [
  { "agentId": "main", "match": { "channel": "telegram", "accountId": "default" } },
  { "agentId": "research", "match": { "channel": "telegram", "accountId": "research" } }
]

Tips

Each agent is fully isolated. They don't share conversations, memory, or workspace files.
You can add more than two. Just ask your agent to add another one and provide a new bot token.
Auto-start is handled. If your Gateway starts on boot (launchd/systemd), all agents and bots come up automatically.
Different models per agent. Ask your agent to set a specific model for the new agent (e.g. "Use Sonnet for the research agent").
Agent-to-agent messaging is off by default. Ask your agent to enable it if you want them to talk to each other.

Troubleshooting

Bot not responding? Ask your main agent to check openclaw status or Gateway logs
Pairing not working? Make sure dmPolicy is "pairing" — ask your agent to verify
Old bot stopped working? The original token may not have been moved to accounts.default correctly — ask your agent to check the config
Config issues? Ask your agent to run openclaw doctor

Example Conversation

Here's roughly how it looks in practice:

You: I want to set up a second agent with its own Telegram bot. I created a new bot via BotFather.

Agent: Nice! Send me the bot token and tell me what you want to call the agent.

You: Token is 0000000000:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX. Call it "Dashboard Builder".

Agent: ✅ Config updated and gateway restarting. Go find your new bot in Telegram and send it /start.

That's it. Your agent handles the config, bindings, and restart.

bdennis-dev/guide-add-second-agent-telegram.md

Select an option

No results found