# Multi-Agent Workflows

Canonical: https://clawdocx.com/docs/multi-agent-workflows
Author: Theo Marsh
Difficulty: ADVANCED
Published: 2026-02-24
Updated: 2026-09-19

> An advanced guide to running multiple OpenClaw agents: per-agent workspaces, agent-to-agent communication, and integrating multi-agent setups with Claude Code.

## 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.

> **Note**
>
> Multi-agent setups are an advanced feature. Make sure you are comfortable with single-agent OpenClaw before attempting this. Get one agent running perfectly first, then expand.

---

## 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`

```text
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.

```bash
openclaw --profile work setup
```

```bash
openclaw --profile personal setup
```

`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:

```bash
openclaw agents add work --workspace ~/.openclaw/workspace-work
```

### 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`):
```json5
{
  gateway: {
    bind: "loopback",
    port: 18789,
  },
  agents: {
    entries: {
      work: {
        name: "Work Assistant",
        workspace: "~/.openclaw-work/workspace",
      },
    },
  },
}
```

**Personal agent** (`~/.openclaw-personal/openclaw.json`):
```json5
{
  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):**

```bash
openclaw gateway install
```

```bash
openclaw --profile personal gateway install --port 19789
```

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.

```ini
# ~/.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
```

```ini
# ~/.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:

```bash
systemctl --user enable --now openclaw-work.service
```
```bash
systemctl --user enable --now openclaw-personal.service
```

---

## 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.

```bash
openclaw --profile work health
```

```bash
openclaw --profile personal health
```

```bash
openclaw --profile work skills list
```

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:

```bash
openclaw --profile personal logs --follow
```

### Set Up Aliases

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

```bash
# ~/.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:

```bash
oc-work health
```
```bash
oc-personal skills list
```
```bash
oc-research gateway restart
```

### 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:

```bash
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".

```json5
{
  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":

```json5
{
  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:

```json5
{
  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".

```markdown
---
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`."

```json5
{
  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

````markdown
---
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.
````

> **Warning**
>
> Claude Code integration requires Claude Code to be installed separately (`npm install -g @anthropic-ai/claude-code`). It uses its own API key and billing, separate from OpenClaw's configuration.

---

## 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:

| Agents | Estimated RAM | Recommended Hardware |
|--------|--------------|---------------------|
| 1-2 | 300-500 MB | 8 GB system RAM |
| 3-5 | 750 MB - 1.25 GB | 16 GB system RAM |
| 5-10 | 1.25-2.5 GB | 24+ GB system RAM |

### 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:

```bash
lsof -i :18789 -i :19789 -i :20789
```

### 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:

```bash
openclaw agents list --bindings
```

```bash
openclaw agent --agent research --message "Summarize logs"
```

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](/docs/skills-explained)** — Skills fundamentals for each agent
- **[Cost Optimization](/docs/cost-optimization)** — Manage costs across multiple agents
- **[Security Hardening](/docs/security-hardening)** — Secure inter-agent communication
- **[Troubleshooting](/docs/troubleshooting)** — Fix common multi-agent issues

## Sources

- [OpenClaw: Agent workspace](https://docs.openclaw.ai/concepts/agent-workspace)
- [OpenClaw: Environment variables](https://docs.openclaw.ai/help/environment)
- [OpenClaw: CLI reference](https://docs.openclaw.ai/cli)
- [OpenClaw: Agents](https://docs.openclaw.ai/cli/agents)
- [OpenClaw: Setup CLI](https://docs.openclaw.ai/cli/setup)
- [OpenClaw: Onboard](https://docs.openclaw.ai/cli/onboard)
- [OpenClaw: Skills](https://docs.openclaw.ai/tools/skills)
- [OpenClaw: Agent](https://docs.openclaw.ai/cli/agent)
- [OpenClaw: Health](https://docs.openclaw.ai/cli/health)
- [OpenClaw: Skills CLI](https://docs.openclaw.ai/cli/skills)
- [OpenClaw: Logs](https://docs.openclaw.ai/cli/logs)
- [OpenClaw: Gateway](https://docs.openclaw.ai/cli/gateway)
- [OpenClaw: Multiple gateways](https://docs.openclaw.ai/gateway/multiple-gateways)
- [OpenClaw: Multi-agent routing](https://docs.openclaw.ai/concepts/multi-agent)
- [OpenClaw: Sessions](https://docs.openclaw.ai/cli/sessions)
- [OpenClaw: Configuration: per-agent entries and multi-agent routing](https://docs.openclaw.ai/gateway/config-agents/entries-and-multi-agent)
- [OpenClaw: Configuration: cross-agent, session, and subagent tools](https://docs.openclaw.ai/gateway/config-tools/sessions-and-subagents)
- [OpenClaw: Configuration: agent runtime and CLI backends](https://docs.openclaw.ai/gateway/config-agents/runtime-and-cli-backends)
- [OpenClaw: Configuration: gateway](https://docs.openclaw.ai/gateway/config-gateway)