OpenClaw Multi-Agent Collaboration: A Field Report on Pitfalls & Solutions 🦞

📋 Project Background

The goal was to build a collaborative system of four specialized AI assistants:

However, the path to getting them working together was filled with unexpected bugs. Here is a实录 (field record) of the pitfalls we encountered and how we fixed them.

💥 The Pitfalls We Encountered

Pitfall 1: Identity Chaos
Phenomenon: All bots claimed to be "Fugui." Their identities were completely confused.
Root Cause: All four agents shared the same workspace directory, meaning they were all reading the exact same SOUL.md file.
❌ Lesson: Never share workspaces between distinct agents!
Pitfall 2: @Mentions Ignored
Phenomenon: When Fugui tried to @mention other bots in the group chat, they remained completely unresponsive.
Root Cause:
  • The @ sent by Fugui was plain text, not a valid Telegram mention entity.
  • Telegram Platform Limitation: Bots generally cannot see messages sent by other bots.
  • Bots with Privacy Mode ENABLED only receive messages where they are explicitly mentioned by a human user.
❌ Lesson: Bot-to-bot communication via Telegram messages is impossible in this architecture!
Pitfall 3: agentToAgent Failure
Phenomenon: Enabled the agentToAgent configuration, but Fugui still couldn't invoke other agents.
Root Cause:
  • agentToAgent is designed for a Single-Bot, Multi-Agent architecture.
  • We were running a Multi-Bot architecture (4 independent Telegram bots).
  • Functions like sessions_spawn or sessions_send cannot cross bot boundaries.
❌ Lesson: Understand your architecture before configuring features!
Pitfall 4: Allowlist Rigidity
Phenomenon: Set groupPolicy: "allowlist", but new groups couldn't use the bots.
Root Cause: The allowlist requires pre-configuring specific Group IDs, which is inflexible for dynamic usage.
❌ Lesson: Just use groupPolicy: "open" for flexibility!

✅ The Final Working Solution

Architecture Design

4 Independent Telegram Bots
⬇️
4 Agents + 4 Independent Workspaces
⬇️
Shared: knowledge_hub + memory + skills

Core Configuration Steps

1. Independent Workspaces (Critical!)
Each bot must have its own directory to maintain its unique identity (SOUL.md).

{ "id": "code", "workspace": "/path/to/workspace-code", // Unique path "agentDir": "/path/to/agent-code" }

2. Shared Knowledge Base
To enable collaboration, create symbolic links (symlinks) to a central knowledge hub.

ln -s /path/to/central/knowledge_hub /path/to/workspace-code/knowledge_hub ln -s /path/to/central/knowledge_hub /path/to/workspace-analyst/knowledge_hub

3. Privacy Mode Configuration

  • Coordinator Bot (Fugui): Set to DISABLED. It needs to see all messages to orchestrate.
  • Specialist Bots: Set to ENABLED. They should only wake up when explicitly mentioned by a human.

New Collaboration Workflow

Instead of real-time bot-to-bot messaging (which doesn't work), we use Shared Knowledge Base Collaboration:

  • Yamei (Analyst) → Analyzes data → Writes results to fraud_detection/
  • Code (Coder) → Develops tools → Saves scripts to tools/
  • Soros (Vision) → Recognizes charts → Saves insights to visuals/
  • Fugui (Coordinator) → Reads all folders → Synthesizes and reports to the user.

🎯 Best Practices Summary

✅ Keep Independent

workspace directories and SOUL.md files. This prevents identity confusion.

✅ Share Resources

knowledge_hub, memory, and skills. Use symlinks to connect them.

✅ Collaborate via Files

Rely on reading/writing to the shared knowledge base rather than trying to force real-time bot-to-bot calls.

🏁 Conclusion

The correct posture for a Multi-Bot OpenClaw architecture is simple:

  1. Give every bot its own independent workspace to avoid personality clashes.
  2. Enable collaboration through a shared knowledge base, bypassing Telegram's bot-messaging restrictions.
  3. Let each specialist do their job, save the results, and let the Coordinator aggregate the findings.

With this configuration, our four AI assistants now collaborate perfectly, with zero identity confusion!