Multi-Agent Architecture

When Do You Need Multiple Agents?

A single agent handles most workflows. Multi-agent setups shine when you need separate contexts (e.g., one agent per Discord channel), parallel execution, or different model/tool configurations per task.

This guide covers single vs multi-agent patterns, channel strategy, agent communication, and how to manage visibility and credentials across agents.

Jump to Section

Single vs Multi-Agent Channel Strategy Agent-to-Agent Communication File Visibility & Isolation Agent Autonomy & Decision Rules Credential Management

Single vs Multi-Agent Deployment

Pattern	Best For	Complexity
Single agent, multiple channels	Most use cases — one agent responds on Discord, Telegram, Slack	Low
Single agent + sub-agents	Parallel tasks — main agent spawns workers via sessions_spawn	Medium
Multiple agent directories	Separate identities — each agent has its own config, memory, and personality	High
Multiple gateways	Full isolation — agents cannot see each other at all	Very High

Recommendation

Start with a single agent + sub-agents pattern. Only move to separate agent directories when you need completely different identities, models, or tool configurations.

Channel Strategy

One Channel Per Sub-Agent

Assign each sub-agent its own dedicated channel (e.g., #agent-research, #agent-coding). This prevents message collision and makes debugging easier.

Spawn a sub-agent with channel binding

# In your agent chat, instruct it:
Spawn a sub-agent with task "research latest Node.js releases".
Have it report results to the discord channel #agent-research.

Shared Channel (Use with Caution)

Multiple agents can share a channel, but they may respond to each other's messages, creating loops. Use allowFrom filters to prevent this.

Agent Loop Prevention

If two agents share a Discord channel, they may endlessly respond to each other. Set channels.discord.ignoreOwnMessages: true and use distinct bot user IDs in allowFrom filters.

Agent-to-Agent Communication

Agents communicate via the sessions_send tool. The parent agent spawns a sub-agent, and the sub-agent reports back when done.

Agent-to-agent communication pattern

# Parent agent spawns a worker:
# Use sessions_spawn with task description:
"Research the topic X. When done, use sessions_send to message
 session 'agent:main:default' with your findings."

# Parent checks on sub-agent:
# Use sessions_list to see active sub-agents
# Use sessions_history to read sub-agent messages

For Discord-based agent-to-agent communication, agents can also communicate by posting in a shared channel that the other agent monitors. This is simpler but less reliable.

File Visibility & Isolation

"Can both agents see all my files?" — this depends on the deployment pattern:

Sub-agents (sessions_spawn)

Shared

Share the same agent directory. They CAN see the same files and memory. Use separate agentDir if you need isolation.

Separate agent directories

Isolated

Each agent has its own ~/.openclaw/agents/<name>/ directory. Files and memory are isolated by default.

Sandbox mode

Isolated

When sandbox.mode is on, agents run in Docker containers with only mounted volumes visible. Host files are not accessible unless explicitly mounted.

Agent Autonomy & Decision Rules

If your agent keeps asking for confirmation instead of acting autonomously, or vice versa, adjust the decision rules in the system prompt:

Configure agent autonomy level

# In your identity.md or system prompt:
# High autonomy (for cron/background agents):
"Execute tasks without asking for confirmation.
Only stop if you encounter an error you cannot resolve."

# Low autonomy (for user-facing chatbots):
"Always confirm before executing shell commands,
deleting files, or sending messages to channels."

Why the Agent Keeps Asking

Agents default to cautious behavior. If your agent asks "Should I proceed?" for every action, add explicit autonomy instructions to the system prompt: "You have full autonomy to complete tasks without asking for permission."

Credential & Endpoint Management

When using multiple agent directories, each agent needs its own API credentials:

Copy credentials to a sub-agent directory

# Sub-agents in different agentDir don't inherit credentials
cp ~/.openclaw/agents/main/agent/auth-profiles.json \
   ~/.openclaw/agents/worker/agent/auth-profiles.json

# Or share via environment variables (all agents inherit)
export OPENAI_API_KEY="sk-..."
export ANTHROPIC_API_KEY="sk-ant-..."

Auth Profiles Not Inherited

A common error: All models failed: No API key found for provider. This happens when a sub-agent in a different agentDir can't find the main agent's auth-profiles.json. Copy it manually.

Related Guides

Architecture and session management: