Introduction
Once you've configured multiple chat platforms in OpenClaw, a critical question arises: how should messages from different platforms, different users, and different conversations be routed and isolated? If all messages are mixed together, the AI's responses will inevitably become confused.
OpenClaw solves this problem elegantly through its multi-Agent routing and session isolation mechanism. Each Agent has its own independent session space, sessions are persisted in JSONL format, and tree-structured branching and compaction are supported. This article provides an in-depth look at how this mechanism works and how to configure it.
Multi-Agent Routing Architecture
OpenClaw's core design philosophy is "route by conversation". When you've configured multiple platforms (Telegram, Discord, Slack, etc.), the system doesn't simply dump all messages into a single processing pipeline. Instead, it maintains an isolated session context for each independent conversation.
User A (Telegram DM) ──→ Agent-1 ──→ Session A-001
User A (Discord #general) ──→ Agent-2 ──→ Session A-002
User B (Telegram DM) ──→ Agent-1 ──→ Session B-001
User B (Slack group) ──→ Agent-3 ──→ Session B-002
As you can see, even the same user's conversations on different platforms are routed to different Agents with completely isolated sessions. This design ensures that contexts don't contaminate each other.
Session Storage: JSONL and Tree Structure
OpenClaw's session data is stored in JSONL (JSON Lines) format, with each session file containing a series of message records. The storage path follows a unified directory structure:
~/.openclaw/agents/<agentId>/sessions/
├── session-a001.jsonl
├── session-a002.jsonl
├── session-b001.jsonl
└── session-b002.jsonl
Each message record includes id and parentId fields, forming a tree structure:
{"id":"msg_001","parentId":null,"role":"user","content":"Hello","timestamp":1710000000}
{"id":"msg_002","parentId":"msg_001","role":"assistant","content":"Hello! How can I help you?","timestamp":1710000001}
{"id":"msg_003","parentId":"msg_002","role":"user","content":"Help me write some Python code","timestamp":1710000010}
{"id":"msg_004","parentId":"msg_002","role":"user","content":"What's the weather like today","timestamp":1710000015}
Note that msg_003 and msg_004 share the same parentId, meaning the conversation branched after msg_002. The tree structure allows OpenClaw to maintain a complete record of all conversation branch paths, not just a linear chat log. This is especially important when users re-edit previous messages or when the system performs auto-compaction.
Per-Channel-Type History Limits
Different types of chat channels have different usage scenarios, and OpenClaw applies differentiated history length limits accordingly.
DM (Direct Message) Channels
DM scenarios are typically deep one-on-one conversations where users expect the AI to remember longer context. Therefore, DM channels retain more historical messages by default:
{
agents: {
"personal-assistant": {
history: {
dm: {
maxMessages: 100, // Keep the last 100 messages
maxTokens: 32000, // Maximum token count
},
},
},
},
}
Group Channels
In group scenarios, message volume is high and topics change frequently — retaining too much history introduces noise. OpenClaw applies stricter limits to group channels by default:
{
agents: {
"group-bot": {
history: {
group: {
maxMessages: 30, // Keep only the last 30 messages
maxTokens: 8000, // Smaller token window
},
},
},
},
}
This per-channel-type design saves token costs while ensuring the best experience for different scenarios.
Auto-Compaction on Context Overflow
When conversation history exceeds the model's context window limit, OpenClaw doesn't simply truncate old messages. Instead, it triggers an auto-compaction mechanism.
The auto-compaction workflow:
- Detects that the current session's token count is about to exceed the model's context limit
- Sends the older conversation content to the model to generate a compressed summary
- Replaces the original historical messages with the summary, significantly reducing token usage
- Creates a new compaction node in the JSONL file while the original messages are preserved in old branches of the tree
{"id":"compact_001","parentId":null,"role":"system","type":"compaction","content":"[Session Summary] The user discussed Python web scraping development, including requests library usage, anti-scraping strategies, data parsing methods...","timestamp":1710001000}
{"id":"msg_050","parentId":"compact_001","role":"user","content":"Tell me more about the Scrapy framework","timestamp":1710001001}
The compaction operation is completely transparent to users. The AI can still understand previous conversation context based on the summary while significantly reducing token consumption per request.
You can adjust compaction behavior through configuration:
{
agents: {
"my-agent": {
compaction: {
enabled: true,
// Token usage ratio at which compaction is triggered (0-1)
threshold: 0.85,
// Maximum tokens for the compaction summary
summaryMaxTokens: 1024,
// Number of recent messages to preserve from compaction
preserveRecent: 10,
},
},
},
}
Session Persistence and Branch Management
JSONL format combined with tree structure gives OpenClaw powerful session persistence capabilities. Even after a service restart, all session states can be fully restored.
Branching Scenarios
The tree structure comes into play in the following scenarios:
- User edits a message: When a user modifies a previous message and resends it, OpenClaw doesn't overwrite the original conversation path. Instead, it creates a new branch from the edited node
- Auto-compaction branches: Compaction creates new summary nodes while the original conversation is preserved as an old branch, ensuring no data is lost
- Conversation rollback: Administrators can view the complete conversation history of any branch through the Dashboard
Viewing Session Data
You can directly view raw session files:
# List all sessions for an Agent
ls ~/.openclaw/agents/my-agent/sessions/
# View a session's contents
cat ~/.openclaw/agents/my-agent/sessions/session-xxx.jsonl | jq .
Provider-Agnostic Model Switching
OpenClaw's multi-Agent architecture brings another important advantage: each Agent can independently specify its model provider and model name without affecting others.
{
agents: {
// Agent 1: Uses Claude for Telegram DMs
"telegram-dm": {
model: {
provider: "claude",
name: "claude-sonnet-4-20250514",
},
channels: ["telegram"],
scope: "dm",
},
// Agent 2: Uses Ollama local model for Discord group chats
"discord-group": {
model: {
provider: "ollama",
name: "llama3.1:70b",
},
channels: ["discord"],
scope: "group",
},
// Agent 3: Uses GPT-4o for Slack work channels
"slack-work": {
model: {
provider: "openai",
name: "gpt-4o",
},
channels: ["slack"],
scope: "all",
},
},
}
This provider-agnostic design means you can switch models for any Agent at any time without affecting other Agents' operation. For example, you can switch a cost-sensitive group chat Agent from Claude to a local Ollama model while keeping the DM Agent on a high-quality commercial model.
Routing Rules Summary
OpenClaw's multi-Agent routing follows this priority chain:
- Platform matching: Which chat platform the message comes from (Telegram / Discord / Slack, etc.)
- Channel type matching: Whether the message is from a DM or a group
- Agent assignment: Route the message to the corresponding Agent based on match results
- Session lookup or creation: Find an existing session in the Agent's session directory, or create a new one
- History loading: Load the appropriate length of context based on the channel type's history limits
- Model invocation: Process the message using the model configured for that Agent
The entire process is fully automatic, requiring no user intervention.
Conclusion
OpenClaw's multi-Agent routing and session isolation mechanism is one of the most core designs in its architecture. Through per-conversation routing for complete context isolation, JSONL tree structures for persistence and branch management, differentiated per-channel-type history limits balancing cost and experience, and auto-compaction for handling context overflow — this mechanism lets you confidently deploy multiple Agents across multiple platforms, each running stably and efficiently in its own session space.