Multi-Agent Workflows

#Why Multiple Agents?

A single OpenClaw agent handles most personal use cases well. But as your automation needs grow, you may find that one agent trying to do everything leads to:

• Context overload — Too many skills and responsibilities dilute the agent's focus
• Conflicting personalities — A professional work agent should not also be your casual gaming buddy
• Security boundaries — Your personal agent should not have access to work credentials
• Specialization — A dedicated research agent performs differently than a task management agent

Multi-agent workflows solve these problems by letting you run separate agents, each with its own SOUL.md, skills, configuration, and communication channels.

#Architecture Overview

OpenClaw documents two shapes for this. One Gateway can already host several agents, "each with its own workspace, state directory (agentDir), and SQLite-backed session history", with inbound messages routed by bindings. Separate Gateways are the stronger form, and the docs scope them narrowly: "Most setups need one Gateway - a single Gateway handles multiple messaging connections and agents. Run separate Gateways with isolated profiles/ports only when you need stronger isolation or redundancy (e.g., a rescue bot)."

This guide takes the second shape, one named profile per agent. Each instance then has its own:

• State directory: a separate ~/.openclaw-{name}/ directory, which keeps that agent's workspace at ~/.openclaw-{name}/workspace
• SOUL.md — Unique personality and identity
• Skills — Different skills for different purposes
• API keys — Can use different providers or billing accounts
• Messaging channels — Separate bots or shared channels with routing
• Port — Each Gateway binds to a different port
• Service: its own managed Gateway service, installed with openclaw gateway install

Agent 1: "Work Assistant"
  ~/.openclaw-work/
  Port: 18789
  Channels: Slack, Email
  Model: Claude Sonnet 4.6
Agent 2: "Personal Assistant"
  ~/.openclaw-personal/
  Port: 19789
  Channels: Telegram, iMessage
  Model: Claude Sonnet 4.6
Agent 3: "Research Agent"
  ~/.openclaw-research/
  Port: 20789
  Channels: Dashboard only
  Model: Claude Opus 4.6

#Setting Up Multiple Agents

#Create Agent Workspaces

openclaw setup does take --workspace <dir>, but it is a "Workspace proposal; existing fleets require classic confirmation and are preserved noninteractively", which sets one workspace for the install rather than standing up a separate instance. There is no --name flag: the documented spelling is --agent-name <name>, the "Name for the first agent (default: main)."

Isolation is the global --profile <name> flag, which will "Isolate state under ~/.openclaw-<name> (OPENCLAW_STATE_DIR/OPENCLAW_CONFIG_PATH)". Run setup once per profile. Each run "writes everything into a separate profile", so the instance gets its own config file, state directory, workspace, managed service name and base port.

openclaw setup "runs onboarding on a profile that is not configured yet", and openclaw --profile work onboard runs the same flow again on a profile that already exists. Each profile gets its own SOUL.md, configuration, and skills.

If you would rather keep one Gateway, add agents to it instead. openclaw agents add takes --workspace <dir> for the new agent's workspace:

#Configure Different Ports

Each Gateway binds to its own port. The documented key is gateway.port, the "local Gateway bind port, multiplexing WS + HTTP", resolved in the order "--port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789". There is no gateway.host key: the listener is selected with gateway.bind (loopback by default, or lan, tailnet, auto, custom) and, for custom, gateway.customBindHost. Keep the numbers far apart, because other ports are derived from the base: "Leave at least 120 ports between base ports so derived browser/CDP ports never collide."

The config file is JSON5, and an agent's display name belongs to its entry under agents.entries, not to a root agent key.

Work agent (~/.openclaw-work/openclaw.json):

{
  gateway: {
    bind: "loopback",
    port: 18789,
  },
  agents: {
    entries: {
      work: {
        name: "Work Assistant",
        workspace: "~/.openclaw-work/workspace",
      },
    },
  },
}

Personal agent (~/.openclaw-personal/openclaw.json):

{
  gateway: {
    bind: "loopback",
    port: 19789,
  },
  agents: {
    entries: {
      personal: {
        name: "Personal Assistant",
        workspace: "~/.openclaw-personal/workspace",
      },
    },
  },
}

#Install Daemons for Each Agent

There is no top-level --install-daemon flag and no --daemon-name option. The managed service is a gateway subcommand: openclaw gateway install "installs and starts the service". Service identity follows the profile, which is why each instance needs one: "OPENCLAW_STATE_DIR alone does not isolate a managed Gateway service. Service names follow the profile, not the state directory."

macOS and Linux (managed service):

The second form is the documented pattern for an extra instance, and openclaw gateway status --deep "catches stale launchd/systemd/schtasks services from older installs."

Linux (systemd, self-managed):

If you write your own unit instead, run the Gateway in the foreground. gateway start has no --foreground flag and no --workspace flag; the foreground form is openclaw gateway run, and the profile picks the instance.

# ~/.config/systemd/user/openclaw-work.service
[Unit]
Description=OpenClaw Work Assistant
After=network-online.target
[Service]
Type=simple
ExecStart=/usr/bin/env openclaw --profile work gateway run --port 18789
Restart=always
RestartSec=10
[Install]
WantedBy=default.target

# ~/.config/systemd/user/openclaw-personal.service
[Unit]
Description=OpenClaw Personal Assistant
After=network-online.target
[Service]
Type=simple
ExecStart=/usr/bin/env openclaw --profile personal gateway run --port 19789
Restart=always
RestartSec=10
[Install]
WantedBy=default.target

Enable both services:

#Managing Multiple Agents

#CLI Commands per Profile

There is no global --workspace flag. The CLI reference's global table lists --profile <name> instead, and notes that "Global options such as --profile can precede the command." --workspace <dir> is a per-command option, documented on commands including openclaw setup, openclaw onboard, openclaw agents add, openclaw agents set-identity and openclaw sessions export-trajectory, and openclaw agents team create takes the related --workspace-root <dir>. Every one of them names a workspace directory; none of them selects an instance.

There is no openclaw gateway logs either. Logs are a top-level command that will "Tail Gateway file logs over RPC", and the docs show the profile form directly:

#Set Up Aliases

To avoid typing --profile constantly, add aliases to your shell profile:

# ~/.zshrc or ~/.bashrc
alias oc-work="openclaw --profile work"
alias oc-personal="openclaw --profile personal"
alias oc-research="openclaw --profile research"

Now you can use:

#Monitoring All Agents

There is no --all-workspaces flag. Within one Gateway, openclaw health --verbose "forces a live probe of each channel account" and "expands human-readable output across all configured accounts and agents, instead of just the default agent". Across separate profiles, ask each instance in turn, which is the check the multiple-gateways page prescribes:

openclaw health --verbose
openclaw gateway status --deep
openclaw --profile personal gateway status --deep
openclaw --profile personal status

A gateway probe warning such as multiple reachable gateway identities detected "is expected" when "You intentionally run more than one isolated gateway".

#Agent-to-Agent Communication

Agents reach each other through OpenClaw's cross-agent session tools, which is what makes one agent able to hand work to another.

#Enable Inter-Agent Communication

No inter_agent block, trusted_agents list or agent-to-agent api_port is documented, and the docs describe no channel between two separate Gateways. What they do document is cross-agent access between agents inside one Gateway: "Cross-agent access is on by default", gated by tools.agentToAgent, whose allow "lists the agent ids or * patterns that may take part in a cross-agent call".

{
  tools: {
    agentToAgent: {
      allow: ["home", "work"],
    },
  },
}

"Both the requesting agent and the target agent must match an entry", and enabled: false turns cross-agent access off entirely. The reach of the session tools themselves is tools.sessions.visibility, which defaults to all.

#Communication Patterns

1. Delegation

A coordinator agent can hand a research task to a specialist. Delegation is per-agent config under subagents, where allowAgents is the "allowlist of configured agent ids for explicit sessions_spawn.agentId targets":

{
  agents: {
    entries: {
      coordinator: {
        subagents: {
          allowAgents: ["researcher", "writer", "reviewer"],
          delegationMode: "prefer",
        },
      },
      researcher: { subagents: { allowAgents: [] } },
    },
  },
}

"prefer" "guides the coordinator to delegate suitable work; it is prompt guidance", not a scheduler. openclaw agents team create writes exactly this wiring for a chief of staff plus a researcher, writer and reviewer.

2. Notification Relay

No routing_rules key exists, and no condition-based forwarding between agents is documented. Inbound traffic is routed by bindings, which map a channel account to one agent:

{
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

3. Specialization Pipeline

Set up a pipeline where agents hand off work:

User request -> Work Agent (triage)
  |-> Simple task: Handle directly
  |-> Research needed: Delegate to Research Agent
  |-> Personal matter: Forward to Personal Agent

#Example: Research Delegation Skill

Create this skill for your work agent. A SKILL.md carries very little frontmatter: "Every skill needs at minimum a name and description in the frontmatter", and the documented optional keys are homepage, user-invocable, disable-model-invocation, command-dispatch, command-tool, command-arg-mode and metadata.openclaw. There is no version, author, tools or triggers field, so the phrases that should reach the skill and the tools it uses belong in the description and the body, and the skills reference asks you to "Keep descriptions short and descriptive to minimize prompt overhead".

---
name: research-delegator
description: Delegate a research question to the research agent and summarize the result.
---
# Research Delegator
When the user asks for in-depth research, delegate to the
research-agent:
1. Formulate a clear research question
2. Spawn it on the research agent with the sessions_spawn tool
3. Wait for the response (timeout: 5 minutes)
4. Summarize the research agent's findings
5. Present to the user with your own analysis added
If the research agent is unavailable, fall back to doing
the research yourself using web_search.

#Use Cases for Multi-Agent Setups

#Work/Personal Separation

Work Agent:

• Connected to Slack and work email
• Has access to work documents and repositories
• Uses company API keys
• Skills: meeting scheduler, code reviewer, project tracker
• SOUL.md: Professional, formal, task-focused

Personal Agent:

• Connected to Telegram and iMessage
• Has access to personal calendar and files
• Uses personal API keys
• Skills: weather, news, reminders, entertainment
• SOUL.md: Casual, friendly, conversational

#Specialized Research Team

General Agent (coordinator):

• Receives all user requests
• Routes tasks to specialized agents
• Synthesizes results

Technical Research Agent:

• Focused on code, architecture, technical papers
• Uses Claude Opus 4.6 for deep reasoning
• Larger context window
• No messaging channels (dashboard only)

Market Research Agent:

• Focused on business, competitors, trends
• Web search optimized skills
• Summarization-focused

#Home Automation Hub

Smart Home Agent:

• Connected to Home Assistant
• Skills for lighting, HVAC, security
• Responds to voice commands via dedicated channel

Family Agent:

• Family-friendly personality
• Shared calendar management
• Multiple family members have access
• Content filtering enabled

#Claude Code Integration

OpenClaw can integrate with Claude Code (Anthropic's coding CLI) for development-focused workflows. This is not multi-agent in the traditional sense, but it extends your agent's capabilities with a specialized coding tool.

#How It Works

When your agent encounters a coding task that would benefit from Claude Code's specialized capabilities (file editing, codebase search, test running), it can invoke Claude Code as a tool.

#Configuration

No integrations block is documented, so there are no claude_code, auto_approve, project_directories or timeout_seconds keys to set. What the docs do describe is running a Claude CLI as the harness behind a model: "the bundled Anthropic plugin provides the claude-cli CLI backend", selected with model-scoped runtime policy, and "Runtime policy decides which harness executes a model run. It lives on providers and models, not on agents.defaults."

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-5": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}

Whole-agent runtime keys do not work for this: "agents.defaults.agentRuntime, agents.entries.*.agentRuntime, session runtime pins, and OPENCLAW_AGENT_RUNTIME are ignored by runtime selection."

#Example Workflow

1. You message your agent: "Can you fix the failing tests in my-app?"
2. The agent invokes Claude Code on the ~/Projects/my-app directory
3. Claude Code analyzes the test failures, identifies the issues, and proposes fixes
4. The agent presents the changes for your approval
5. You approve, and Claude Code applies the fixes
6. The agent runs the tests again to verify

#Creating a Claude Code Skill

---
name: claude-code-bridge
description: Bridge coding work to Claude Code for deep codebase tasks.
---
# Claude Code Bridge
For coding tasks that require deep codebase understanding,
invoke Claude Code with the exec tool, and read files back
with the read tool:
```bash
claude --project ~/Projects/my-app --message "Fix failing tests"
```
Present Claude Code's output to the user. If Claude Code
suggests file changes, summarize them and ask for approval
before applying.

#Resource Considerations

Running multiple agents increases resource usage on your host machine.

#Memory

Each Gateway instance uses approximately 150-250 MB of RAM. Plan accordingly:

#API Costs

Each agent has its own heartbeat cycle. Three agents with 15-minute heartbeats means 3x the heartbeat cost. Optimize aggressively:

• Use Haiku 4 or Gemini 3 Flash for heartbeats on all agents
• Stagger active hours if possible (research agent only needs heartbeat during work hours)
• Disable heartbeat on agents that only need to respond to messages

#Network

Each agent maintains connections to its messaging platforms and LLM APIs. Bandwidth impact is minimal, but connection counts can be relevant for firewall and proxy configurations.

#Multi-Agent Best Practices

1. Start with two agents (work + personal) before adding more
2. Give each agent a distinct identity in SOUL.md — agents should not be interchangeable
3. Minimize skill overlap — if two agents have the same skill, their responses may conflict
4. Use separate API keys when possible for clearer cost tracking
5. Monitor all agents regularly with openclaw health --verbose per profile
6. Document your architecture — Keep notes on which agent does what
7. Test inter-agent communication before relying on it for critical workflows
8. Set up alerts for each agent independently

#Troubleshooting Multi-Agent Issues

#Port Conflicts

If two agents try to bind to the same port, one will fail to start. Check for conflicts:

#Agent Cannot Reach Another Agent

There is no openclaw inter-agent command group and no documented ping subcommand. Confirm the roster and its routing, then send a turn to the other agent by id:

Check that:

• Both agents are configured, which openclaw agents list reports
• Cross-agent access is on, which is the default for tools.agentToAgent
• tools.agentToAgent.allow, when set, names both the requesting agent and the target
• tools.sessions.visibility has not been narrowed below all for a cross-agent call

#Shared Resource Conflicts

If agents access the same files or directories, race conditions can occur. Use separate directories per agent, or implement locking mechanisms in your skills.

#Next Steps

• Understanding Skills — Skills fundamentals for each agent
• Cost Optimization — Manage costs across multiple agents
• Security Hardening — Secure inter-agent communication
• Troubleshooting — Fix common multi-agent issues