How to Run Multiple OpenClaw Agents in One Gateway

Running multiple OpenClaw agents in one Gateway lets you separate personas, route the right traffic to the right skill set, and keep failures contained. This guide shows you how to structure agent directories, configure isolation in openclaw.json, bind channels cleanly, and monitor everything without cross-talk.

OpenClaw supports this pattern natively. The multi-agent concepts in the official docs (see https://docs.openclaw.ai/concepts/multi-agent) describe the routing model; this guide turns those concepts into a production playbook with files, commands, and operational checks.

Why run multiple agents in OpenClaw

Multiple agents pay off when you need specialization, clean separation, or stricter safety.

• Specialize personas so prompts stay short: research, drafting, QA, support, on-call SRE.
• Route channels by account: one WhatsApp number per agent, one Telegram bot per persona, distinct webchat widgets.
• Reduce blast radius: config mistakes or prompt drift stay inside one agentDir.
• Optimize cost: pin lightweight models on utility agents and reserve premium models for hard tasks.
• Simplify approvals: dmPolicy/groupPolicy stay agent-specific, so risky actions never leak across personas.
• Improve observability: each agent keeps its own logs, metrics, and audit notes.
• Increase uptime: if one agent fails health checks, reroute only the affected channels while others keep running.
• Keep compliance clean: isolate logs and secrets so audit trails map to a single persona.

If your workload spans research, writing, QA, submission, and monitoring, splitting into multiple agents prevents a single monolith from bloating context and breaking under mixed intents.

Prereqs and workspace setup

Set up structure and defaults before you add bindings.

• Create one folder per agent under ~/.openclaw/agents/<agent_name>/ with its own SOUL.md, USER.md, AGENTS.md, and openclaw.json.
• Enforce isolation defaults in every openclaw.json:
• sandbox.mode = on
• dmPolicy = allowlist
• groupPolicy = allowlist
• features.lossless_claw = true
• features.context_engine = true
• Minimal tool profile unless the role requires more.
• Keep shared assets outside agentDir (e.g., /home/ocazurewinvps2/.openclaw/shared/), and mount read-only when possible.
• Version configs: commit each agentDir to git or snapshot after major changes so you can roll back per-agent.
• Ensure host dependencies exist once (Gateway, Python runtime, Node where needed); agents themselves stay lean.
• Lay down a base agent first so patterns are consistent. If you need a refresher, follow the deploy an OpenClaw AI agent guide, then clone and adjust per persona.
• Secret management: store provider keys in environment variables or a vault; never hardcode keys per agentDir.
• Permissions: ensure each agent process runs with the least privileges needed to read its own directory and shared read-only paths.

If you deploy on a VPS, confirm base hardening and systemd units so agents come back on reboot. Use the running on a VPS guide for OS prep and Gateway service wiring.

Create and configure multiple agents

Use consistent scaffolding so every agent is predictable.

• Add agents via CLI or manual folders:
• openclaw agents add <name> to scaffold with defaults; or
• manual mkdir + copy template SOUL/USER/AGENTS/openclaw.json files.
• Define each agent’s purpose in SOUL.md and keep instructions tight. Avoid overloading one agent with unrelated duties.
• Pin providers and models in each openclaw.json under models.providers. Set lighter defaults for utility agents; reserve frontier models for premium flows.
• Configure tools per persona. Example: research agent gets browser + search skills; QA agent only needs markdown lint and link audit.
• Lock safety rules per agent. Approval-required commands should live in agent-specific allowlists so a draft agent cannot perform production changes.
• Document shared conventions in AGENTS.md at the workspace root. Call out isolation rules and naming conventions to prevent accidental overlap.
• Create health scripts per agent (simple live/ready checks) to plug into monitoring.
• Use a consistent JSON scaffold to avoid drift:
  json
{
"dmPolicy": "allowlist",
"groupPolicy": "allowlist",
"sandbox": { "mode": "on" },
"features": { "lossless_claw": true, "context_engine": true },
"models": {
"default": "claude",
"providers": {
"claude": { "apiKey": "$env:OPENCLAW_CLAUDE_API_KEY", "model": "claude-3.5-sonnet" },
"gemini": { "apiKey": "$env:OPENCLAW_GEMINI_API_KEY", "model": "gemini-1.5-pro" },
"ollama": { "endpoint": "http://localhost:11434", "model": "qwen2.5:14b" }
}
}
}
• When you inherit skills across agents, pin versions and document why each skill is enabled.
• Keep an agent registry describing purpose, channels bound, model tier, and approval policy so operators know who owns what.

If you already run orchestration, link to it as a reference pattern. See the multi-agent orchestration article for deeper design tradeoffs.

Bind channels and routing rules

Bindings connect channels/accounts to the right agent. Plan routing before going live.

• Map one channel per agent where possible: distinct WhatsApp numbers, Telegram bots, webchat widgets, or email inboxes per persona.
• For shared channels, add keyword or intent routing. Examples:
• Prefix commands (“/draft”, “@qa”) to steer messages.
• Route by language or topic when you detect it reliably.
• In gateway.json (or your bindings file), define per-binding fields:
• agent: target agent name
• channel: provider + account ID
• filters: keyword allow/deny, rate limits
• kill_switch: boolean or env flag to disable quickly
• Keep bindings declarative and versioned; avoid ad-hoc edits on the host.
• Test routing with dry runs: send test messages from each channel and verify the agent receives and responds.
• Log routing decisions. Enable request logging with agent tags so you can trace which binding fired.
• Example binding block:
  json
{
"agent": "draft_bot",
"channel": { "type": "telegram", "bot_token": "$env:DRAFT_BOT_TOKEN" },
"filters": { "allow": ["/draft", "draft"], "deny": [] },
"kill_switch": "$env:DRAFT_BOT_DISABLED",
"rate_limit_per_min": 30
}
• Keep a rollback plan: store previous bindings and be able to revert quickly if routing misfires.

For conceptual grounding, see the community doc at https://open-claw.bot/docs/concepts/multi-agent/ and the mirror at https://openclaws.io/docs/concepts/multi-agent for diagrams. They outline how the Gateway decides which agent handles a message. For a step-by-step tutorial, review https://lumadock.com/tutorials/openclaw-multi-agent-setup to see a full setup run-through.

Run, monitor, and recover

Operations keep multi-agent setups healthy. Standardize these checks.

• Start sequence:
• Boot dependencies (databases, caches, storage mounts).
• Start Gateway with all agents enabled.
• Verify bindings loaded and no errors in startup logs.
• Health checks:
• Per-agent heartbeat: can it read/write its workspace, access required tools, and reach models?
• Channel probes: scheduled pings through each bound channel to confirm delivery and response.
• Model probes: quick completion per provider to catch auth or rate-limit issues.
• Observability:
• Separate logs per agentDir; avoid shared log files.
• Tag logs with channel, binding, and agent to trace misroutes.
• Collect metrics: request counts, latency per provider, error codes.
• Backups and restores:
• Snapshot each agentDir and shared assets on a schedule.
• Test restore on a staging host to ensure paths and permissions survive.
• Restart strategy:
• Prefer rolling restarts: restart one agent at a time to keep service alive.
• Keep a fallback model configured so degraded mode still replies.
• Security and approvals:
• Keep API keys in environment or secret store, never in repo.
• Validate dmPolicy and groupPolicy on every agent after updates.
• Restrict tool access per agent so drafts cannot run shell commands meant for SRE.
• Incident response:
• Define ownership per agent so alerts route to the right human.
• Keep a short runbook per agent: restart steps, known failure modes, and log locations.
• Record every production change in a changelog for later audits.
• Resource guardrails:
• Set CPU/memory limits per agent to prevent noisy neighbors.
• Throttle outbound calls per provider to avoid global rate-limit collisions.
• Context hygiene:
• Enable the context engine configuration guidance so long-term memory stays clean.
• Purge stale scratch files and rotate tokens regularly.

As you add more agents, watch for shared resource bottlenecks (CPU, memory, rate limits). Add quotas per agent to avoid noisy neighbors.

Advanced multi-agent patterns

Once basics work, add patterns that reduce toil and increase safety.

• Subagents vs siblings:
• Use subagents for scoped, ephemeral tasks with inherited policies.
• Use sibling agents when the persona is long-lived and needs its own files.
• Shared skills with guardrails:
• Keep shared skills in a read-only path; pin versions to avoid surprise upgrades.
• Use capability flags so only authorized agents call sensitive tools.
• Data boundaries:
• Store long-term context per agent; share only sanitized summaries.
• Avoid pointing two agents at the same storage bucket unless you enforce per-agent prefixes.
• Approval workflows:
• Keep risky commands behind explicit owner approval per agent.
• Log every approval with timestamp and operator.
• Routing resilience:
• Add fallback bindings that reroute traffic to a backup agent when health checks fail.
• Rate-limit high-chatter channels to protect core agents.
• Upgrade playbook:
• Stage upgrades in a clone agentDir; cut over bindings after verification.
• Roll back by swapping bindings back to the previous agentDir if issues appear.
• Cost controls:
• Tier models: cheap defaults, premium for critical flows, local models for background tasks.
• Set per-agent request ceilings to stop runaway loops.
• Compliance and audit:
• Keep per-agent audit trails with log retention policies.
• Separate PII handling agents from general-purpose ones; redact before handing off.
• Cross-agent workflows:
• Use queues to hand off work between agents instead of sharing files directly.
• When an agent escalates, include channel, intent, and routing metadata so the next agent has context.

Use practical examples from deep reference articles like https://deepwiki.com/openclaw/openclaw/4.3-multi-agent-configuration to troubleshoot advanced routing edge cases.

Conclusion

Running multiple OpenClaw agents is the safest way to keep personas clean, routing predictable, and operations sane. Build isolated agentDirs, pin safety defaults, define bindings carefully, and monitor each agent like its own service. If you follow these steps, you get clear ownership, easier audits, and fewer surprises when traffic spikes or a provider fails.

Download the multi-agent routing checklist, adapt it to your environment, and rehearse the restart plus failover steps before going live.

FAQ

How many agents should I start with? Start with two to three: one research/drafting agent, one QA or review agent, and one on-call ops agent. Expand when you see clear role drift or overloaded prompts.

Can I mix local and cloud models across agents? Yes. Pin local models for background tasks and reserve cloud frontier models for complex reasoning. Keep provider keys per agent so outages or limits in one provider do not stop others.

Do I need separate channels for each agent? Prefer separate channels (unique numbers or bots). If you must share, enforce strong keyword routing and rate limits so the wrong persona never answers.

How do I prevent cross-contamination of context? Keep context files per agent, enable features.context_engine = true, and avoid shared writable storage. Share only sanitized summaries or read-only artifacts when needed.

When should I use subagents instead of new agents? Use subagents for short, scoped tasks that can inherit the parent’s policies. Use new agents when the persona is long-lived, needs its own files, or should have distinct approvals.