OpenClaw: config breakdown from first bot to multi-agent system in Telegram

OpenClaw allows you to spin up an AI agent in Telegram in literally one evening: the `openclaw onboard` command configures the Gateway and launches your first bot. Most guides stop right there. A new detailed tutorial closes the next level: how the entire configuration works under the hood, how to move from one demo bot to a proper production system with multiple agents and without unnecessary token burn.

What's inside openclaw.json

The openclaw.json config file is the central control file for the entire system. The official OpenClaw documentation covers it fragmentarily, so a section-by-section breakdown with live examples is especially valuable.

Key config sections:

• gateway — address and port for incoming requests to agents
• agents — list of agents with system prompts and bindings to language models
• bindings — routing rules: which agent should receive each incoming message
• session_policy — memory management: when to reset context and how long to keep history
• workspace — path to working files that get loaded into the agent's context

A subtle point about workspace: not everything in the directory automatically gets into context. The agent only sees what's explicitly declared in the config. This is one of the most common sources of confusion — when an agent "doesn't know" the required context even though the files are physically there.

In the agents section, it's important to explicitly set the model and its parameters for each agent — otherwise the Gateway's default configuration applies, which in a production environment can lead to unexpected behavior.

Heartbeat without idle token burn

Heartbeat is a mechanism for periodic agent wake-up. It allows tasks to run autonomously, without an incoming message: monitor events, send digests, check external service status.

A typical trap is to enable heartbeat with a short interval without activation conditions. The agent starts generating hundreds of empty requests to the language model and wastes tokens pointlessly.

A working configuration includes three mandatory elements:

• reasonable interval — usually no shorter than 5–10 minutes for most scenarios
• activation condition — only when there are new events or data to process
• separate heartbeat prompt — not mixed with the agent's main system prompt

"Heartbeat without guard conditions — that's a token generator, not a feature," — from

OpenClaw community discussions.

A properly configured heartbeat works silently and only activates when there's a real task.

Multi-agent: bindings and topics

The transition from one bot to multiple agents is the most non-trivial part of the configuration. OpenClaw supports several distribution schemes: separate chats (each agent gets its own chat_id in Telegram), topics within a single group chat, or combined — some agents in direct messages, others in group chats.

The `bindings` section handles routing. It links the message source (chat_id + topic_id) to a specific agent. If binding isn't set — the message goes to the default agent, which in a multi-agent scheme almost always breaks the workflow logic.

Session_policy in group configurations requires explicit scope specification. Without it, context from different users in the same chat can get mixed — the agent will start "remembering" data from the wrong people.

What this means

OpenClaw handles quick launch well, but the path to production architecture requires detailed config understanding. The tutorial fills the gap between the first working bot and a proper multi-agent system — with a breakdown of all key sections, working examples, and explanations of pitfalls.

Useful for everyone building AI infrastructure in Telegram who has already outgrown a single demo bot.