OpenClaw Multi-Agent Setup: Build a Manager and Worker Team

Short answer: a reliable OpenClaw multi-agent setup gives each persistent agent its own workspace, agent directory, session history, tools, and routing rule. Start with one manager plus two narrowly defined workers. Route messages deterministically, deny tools that a worker does not need, and use temporary subagents for bounded parallel work rather than creating a permanent agent for every task.

The tempting design is a crowd of general-purpose agents that can all read the same files and call the same tools. It looks flexible on a diagram. In production it creates ambiguous ownership: two agents answer one message, credentials spread across workspaces, and nobody knows which session contains the real decision.

A smaller team is easier to operate. In this guide, the manager owns intake and final answers, a research worker gathers evidence, and an implementation worker changes code. The exact names are not important. The boundaries are.

Contents

• Persistent agents or subagents?
• Create the three-agent team
• Route channels and accounts
• Set workspace and tool boundaries
• Design handoffs that do not lose context
• Verify the setup

Persistent agents and subagents solve different problems

A top-level OpenClaw agent is a durable identity. It has its own workspace, agent directory, credentials, and SQLite session history. Use one when work needs a stable channel binding, long-lived memory, a distinct security policy, or an operator who can address it directly.

A subagent is a background session spawned for one bounded assignment. It reports its result back to the requesting session and then becomes history. Use subagents for independent research, review, or a test run. They are useful capacity, but they are not a substitute for deliberate routing and ownership.

Rule of thumb: if a role needs its own inbox, secrets, memory, or policy, make it a persistent agent. If it only needs a task and a deadline, spawn a subagent.

Step 1: create a manager and two workers

Use the CLI so OpenClaw creates the required directories and updates configuration consistently. Pick explicit paths; do not reuse one agent directory for two agents.

openclaw agents add manager \
  --workspace /srv/openclaw/manager \
  --agent-dir /srv/openclaw/agents/manager \
  --model openai/gpt-5

openclaw agents add research \
  --workspace /srv/openclaw/research \
  --agent-dir /srv/openclaw/agents/research \
  --model openai/gpt-5

openclaw agents add implementer \
  --workspace /srv/openclaw/implementer \
  --agent-dir /srv/openclaw/agents/implementer \
  --model openai/gpt-5

Model IDs are examples, not a requirement. Choose models your provider exposes and your budget supports. More importantly, keep each workspace purposeful. The research worker needs source notes and search tools; it does not need deployment keys. The implementer needs the target repository and test commands; it may not need access to marketing accounts.

Write one job contract per agent

Put a short role contract in each workspace. State what the agent owns, what it may change, what evidence it must return, and when it must stop for approval. A useful contract is concrete enough to reject work that belongs elsewhere.

# Research worker
Owns: source discovery, fact checks, comparison notes.
Returns: claims with URLs, dates, and uncertainty.
May not: edit repositories, publish content, or send messages.
Escalates: missing primary source, paid-data limit, conflicting evidence.

A vague role such as “help with research and coding” defeats the point. If two roles share a verb, decide which one owns the final artifact.

Step 2: make routing deterministic

Bindings decide which top-level agent receives an inbound message. Bind the public channel or default account to the manager. Give a worker a direct binding only when people truly need to contact that worker without the manager.

The exact account and peer fields depend on the channel adapter, so inspect the generated configuration and the current OpenClaw binding reference before copying a production rule. The design should still be simple:

{
  "bindings": [
    { "agentId": "manager", "match": { "channel": "telegram", "accountId": "main" } },
    { "agentId": "research", "match": { "channel": "telegram", "accountId": "research-bot" } }
  ]
}

Avoid two equally specific rules for the same source. If routing looks surprising, inspect the resolved bindings instead of guessing:

openclaw agents list --bindings
openclaw channels status --probe

Step 3: narrow workspace and tool access

A workspace is the agent’s default working directory, not a security boundary by itself. Without sandboxing, an agent may still reach absolute paths that the operating-system user can read. Enable sandbox controls where isolation matters, and pair them with tool policy.

Start from what each worker needs. A research worker can often work with web fetch, search, and read-only notes. An implementer may need read, write, patch, command execution, and a repository. A reviewer needs read access and test output, but usually no write or deployment tools.

Tool denials are cumulative. A per-agent rule can further restrict an earlier policy; it cannot resurrect a tool already denied at a higher level. Also remember that command execution can write files even when dedicated write tools are disabled. For a genuinely read-only role, deny execution and process tools or mount the workspace read-only.

{
  "agents": {
    "list": [
      {
        "id": "research",
        "workspace": "/srv/openclaw/research",
        "tools": { "deny": ["exec", "process", "write", "edit"] }
      },
      {
        "id": "implementer",
        "workspace": "/srv/openclaw/implementer",
        "tools": { "deny": ["message", "cron"] }
      }
    ]
  }
}

Treat this as a pattern and validate field names against your installed OpenClaw version. Configuration evolves; the security objective does not. The research worker must not acquire a shell by accident, and the implementer must not be able to announce or schedule work unless that is part of its contract.

Watch the skills replacement rule

Global skills can be set under agents.defaults.skills. An agent-specific agents.list[].skills value replaces that list; it does not merge with it. If a worker suddenly loses a common capability, check whether its local skills array replaced the defaults.

Step 4: pass artifacts, not conversational fog

The manager should send a bounded brief: objective, inputs, output format, constraints, and a definition of done. The worker should return an artifact or compact evidence packet. Do not forward an entire chat transcript when five lines and two file paths will do.

Objective: compare three queue libraries for our Node service.
Inputs: package.json, workload-notes.md.
Return: comparison.md with source links and a recommendation.
Constraints: no repository edits; use maintained releases only.
Done: latency, retry model, observability, license, and migration cost covered.

Use a subagent when the manager can wait for a report. The spawned session is isolated and reports back to the requester. It does not accept arbitrary delivery-channel parameters, so the parent remains responsible for the user-facing reply.

Keep approval boundaries with the manager. A worker may prepare a patch, draft a campaign, or assemble a release plan. It should not perform a high-impact external action unless its role and the current request explicitly authorize that action.

Step 5: test the team before giving it real work

Run one cheap, observable task per boundary. Testing only the happy path proves that prompts work; it does not prove that isolation works.

1. Routing: send one message through every bound source and record the receiving agent ID.
2. Workspace: have each agent print its current working directory and identify its role file.
3. Denied tools: ask the research worker to run a harmless command. The policy should block it.
4. Session separation: give two workers different temporary facts, then verify neither can recall the other’s fact.
5. Handoff: ask the manager to delegate a source check and include the returned evidence in its final answer.
6. Failure path: remove one channel credential or point a binding at a test account, then confirm diagnostics identify the broken route without affecting others.

openclaw agents list --bindings
openclaw channels status --probe
openclaw doctor

Common multi-agent setup mistakes

Sharing one agent directory

Agent directories contain identity and credential state. Reusing one can mix sessions or authentication material. Give every top-level agent a unique directory.

Calling a workspace a sandbox

The workspace controls default context and the usual working directory. It does not automatically block absolute filesystem access. Use sandbox and operating-system permissions when a real boundary is required.

Making every worker user-facing

Direct bindings create more inboxes and more ways to answer twice. Keep specialist workers behind the manager unless a separate human-facing route has a clear owner.

Giving the manager every credential

Coordination does not require universal access. The manager can request a bounded operation from a worker that owns the necessary secret.

Using more agents to fix a vague process

Parallelism magnifies ambiguity. Define ownership and artifacts first. Add another agent only after a queue or permission boundary is visible in real work.

Production checklist

• Each top-level agent has a unique workspace and agent directory.
• One agent owns every inbound source.
• Bindings are listed and probed after configuration changes.
• Role contracts name allowed outputs and approval boundaries.
• Tool access follows least privilege.
• Read-only agents cannot write through command execution.
• Secrets live with the worker that needs them.
• Subagents handle bounded temporary work, not permanent identity.
• Handoffs use explicit artifacts and definitions of done.
• Routing, isolation, denial, handoff, and failure paths have all been tested.

Where to go next

Once the three-agent team is stable, add observability before adding headcount. Track which agent received each request, which worker was delegated, what tools ran, how long the handoff took, and where approval stopped the workflow. For untrusted execution, pair agent-specific policies with gVisor sandboxing. For durable tool telemetry, use OpenTelemetry for AI agents. If you need a managed worker with its own browser, terminal, files, memory, schedules, and scoped secrets, create a GolemWorkers AI agent.

Sources

• OpenClaw Multi-Agent Routing — agent isolation, bindings, workspaces, and account routing.
• OpenClaw agents CLI — creating agents and inspecting bindings.
• Multi-Agent Sandbox and Tools — per-agent sandbox and tool-policy behavior.
• OpenClaw Subagents — background session lifecycle and reporting.
• Gateway Agent Configuration — defaults and agent-specific configuration.