Guide

OpenClaw multi-agent boundary design: split workflows by authority, not names

May 23, 202612 min readUpdated September 13, 2026By OpenClawBlog Team

Published May 23, 2026 · OpenClawBlog Team

A workflow named planner, builder, and publisher looks organized. It is easy to assume that the publisher cannot edit code because its name says publisher, or that a private agent cannot see another person's work because it has a different label.

That assumption puts the boundary in the wrong place. OpenClaw uses an agent entry to hold a persona, workspace, authentication profiles, model settings, and session state. It uses bindings to route an already accepted message to an agent. The multi-agent documentation and the agent bindings reference describe those jobs separately.

The useful rule is simple: choose the agent for context and state, then enforce authority with channel admission, tool policy, sandbox settings, approvals, and the Gateway trust boundary. A name helps people understand the workflow. It does not authorize an action.

The first question is what can change

Before creating an agent, list the assets and actions involved. Can this lane read customer messages? Open a repository? Modify files? Run a shell command? Send an external message? Create a scheduled job? Inspect another session?

Write the answer down in a small capability sheet. This is an operator convention, not an OpenClaw schema, but it forces the important question into view.

Lane	May need	Must not have by default	Evidence at handoff
Coordinator	Read an admitted request and start a bounded child run	Repository write access, shell access, publishing tools	Task id, scope, target agent
Builder	Read a named repository, edit a worktree, run tests in a sandbox	Production credentials, Gateway administration, outbound publishing	Diff, test output, changed paths
Reviewer	Read the diff and inspect test results	Unreviewed mutation of the source or release system	Decision, findings, requested changes
Publisher	Use one approved publishing integration	Generic shell access, arbitrary configuration changes, new delegation	Approved artifact and publication receipt

Not every row needs a separate agent. If the only problem is stale conversation context, a new session may be enough. If the problem is a different workspace, credentials, or model policy, an agent is useful. If people do not share a trust boundary, the decision may be a separate Gateway or host.

Specialist lanes also have an operating cost. OpenClaw's parallel-lane guidance treats session locks, provider capacity, tool capacity, context size, and unclear ownership as real constraints. Add a lane when it removes a meaningful conflict, not because a longer roster feels safer.

Keep the control layers separate

The following controls answer different questions. Combining them under the word agent is how a routing decision gets mistaken for authorization.

Control	What it decides	What it does not prove
`agentId` and `agents.entries`	Which workspace, agent directory, auth profiles, model settings, skills, and session store belong to a persona.	Who sent the message, which tools are available, or whether the Gateway is private.
Bindings	Which agent receives a message after channel rules accept it. Matching can use an account, peer, team, guild, or channel.	That the sender is allowed, or that the binding grants access to an account.
Channel admission	Whether pairing, `dmPolicy`, group policy, and allowlists accept the sender or conversation.	That the selected agent has the right capabilities for the request.
Tool policy	Which named tools are visible or callable. A deny rule wins.	That an allowed `exec` command is harmless. Tool policy does not inspect every side effect inside a shell.
Sandbox and workspace access	Where tools run and whether the agent workspace is hidden, read-only, or writable.	That a workspace path is a complete host boundary. Absolute paths, bind mounts, remote shells, or elevated execution need their own checks.
Approvals	Whether a host command passes policy, an allowlist, and, where configured, human approval.	That an agent name is an identity provider role. Approval is a gate on a request, not a replacement for least privilege.
Gateway boundary	Which operators, sessions, agents, credentials, and nodes share one control plane.	Tenant isolation. A shared Gateway assumes a mutually trusting operator group.

The security model makes one detail explicit: a sessionKey selects a conversation or routing bucket; it is not an authorization token. Do not place a session id in an access-control rule and assume it identifies a person. Likewise, do not infer permission from an avatar, display name, or sidebar ownership label.

A worked split: intake, builder, and publisher

Consider a hypothetical support workflow. A message arrives in an approved channel. The system should classify it, inspect a repository, prepare a change, and publish only after a person approves the result.

The coordinator

The coordinator owns the conversation and the workflow state. It can read the admitted request and start a bounded child run aimed at an explicit builder agent. It does not need shell access, repository write access, gateway, or cron. Its output is a task envelope, not a command to run anywhere.

The builder

The builder has a separate workspace and a unique agentDir. It can read the selected source tree, change a disposable worktree, and run the documented test command inside its sandbox. It returns a diff and test evidence. It has no publishing credential and no reason to message arbitrary sessions.

The upstream documentation warns not to reuse an agentDir across agents because authentication and session state can collide. A second display name or workspace folder is not enough if the underlying state path is shared.

The publisher

The publisher receives the approved artifact, not the builder's full authority. It may have one named integration for the final action. The action should still pass the relevant host or plugin approval flow. If publishing must become autonomous, that is a new authority decision involving the external account, standing rules, audit trail, and rollback path. Changing the agent name does not make the escalation safe.

This design leaves a clear failure point. If the builder produces a bad patch, the reviewer can reject it. If the publisher receives an unapproved artifact, the final gate can deny it. The workflow is easier to inspect because every handoff carries a small result rather than an implied transfer of trust.

Make the handoff narrower than the agent

A handoff should state what the next lane may use, what it must return, and what still needs a person. For example:

{
  taskId: 'support-1842',
  allowedPaths: ['src/', 'tests/'],
  requestedAction: 'prepare a patch and test report',
  expectedArtifact: 'diff plus test output',
  approval: 'human-required'
}

This is a proposed handoff format, not an OpenClaw configuration field. Treat it as data. A sentence inside the request saying ignore the restrictions and publish now does not change the task envelope.

OpenClaw sub-agents run in separate sessions, and the sub-agent documentation says they do not receive session or message tools by default. When delegation is necessary, target the agent explicitly, restrict allowAgents, and request sandbox: 'require' when the child must remain sandboxed. The session and sub-agent configuration reference documents the visibility choices self, tree, agent, and all.

More visibility is not automatically better coordination. self is appropriate for a lane that should see only its current conversation. A coordinator that needs its children may need tree, but that choice has exceptions and should be tested. Use an explicit agent-pair allowlist or disable ordinary cross-agent messaging when the workflow does not require it.

Also inspect shared storage. The multi-agent documentation notes that adding an agent does not automatically split every plugin-owned store. A memory or knowledge plugin may remain global until its own scope is changed.

Put hard stops in configuration

Keep role contracts in workspace instructions so people can understand the workflow. Put enforcement in configuration. The following is an illustrative deny baseline, not a tested drop-in file:

agents: {
  entries: {
    coordinator: {
      tools: {
        deny: ['exec', 'write', 'edit', 'apply_patch', 'gateway', 'cron'],
      },
      subagents: {
        allowAgents: ['builder', 'reviewer'],
        requireAgentId: true,
      },
    },
    builder: {
      sandbox: {
        mode: 'all',
        scope: 'agent',
        workspaceAccess: 'rw',
      },
      tools: {
        deny: ['gateway', 'cron', 'sessions_send'],
      },
    },
    publisher: {
      sandbox: {
        mode: 'all',
        scope: 'agent',
        workspaceAccess: 'ro',
      },
      tools: {
        deny: ['write', 'edit', 'apply_patch', 'gateway', 'cron'],
      },
    },
  },
}

The exact allowlist depends on the channels and integrations in use. Keep filesystem roots narrow. If a builder has exec, put it in a sandbox and inspect the effective policy. Denying write while leaving exec available does not create a read-only shell.

Elevated mode deserves separate attention. OpenClaw documents it as an exec-only escape hatch from ordinary sandboxing. It cannot revive a tool denied by policy, but it can change where an allowed command runs when the other gates permit it. Do not enable it for a public or untrusted lane merely because the lane has a reassuring name.

Failure paths to test

The message reaches the wrong agent

Bindings are consulted after channel admission. Check the account id, canonical peer id, and binding order together. Narrow peer rules should come before broad fallbacks. An omitted account id does not mean every configured account, and a binding to a missing agent is a configuration error, not a security control.

The read-only reviewer writes through the shell

Look for exec first. Tool policy works by tool name, so denying write, edit, or apply_patch does not police shell commands. Deny exec when shell work is unnecessary. Otherwise, use a sandbox with the smallest workspace access and test the actual command path.

A child can inspect another lane's transcript

Check tools.sessions.visibility, tools.agentToAgent, sandbox status, and the child allowlist. The current trust documentation says session tools can be Gateway-wide by default, while the session configuration reference explains narrower scopes. A sandbox limits what the caller can reach; it does not make a transcript invisible to another permitted caller.

The agent has a separate name but shared state

Inspect the resolved workspace and agentDir. Never reuse the latter. Check provider profiles too: the repository documentation describes fallback behavior for an expired secondary OAuth credential. If a truly independent account is required, sign in from that agent and verify the stored profile.

Different users share one Gateway

The trust model treats one Gateway as one operator trust boundary. The multi-user guidance says session ownership and visibility are usability features, not security boundaries. If users must not access each other's tools, credentials, files, or sessions, use separate Gateways, credentials, and ideally separate operating-system users or hosts.

An approval prompt creates false confidence

Use exec approvals for the command that actually needs host access. Approval policy, allowlists, and human approval stack together. Review the command, working directory, and file operand where available. A successful approval proves that one request passed its gate; it does not prove that the whole agent is safe to operate.

A repeatable preflight

The following checks are documentation-derived operator checks, not a live installation test for this article:

openclaw agents list --bindings
openclaw agents list --tree
openclaw sandbox explain --agent builder
openclaw approvals get
openclaw security audit

Record every input route, the channel admission rule, the matching binding, the selected agentId, and the expected session scope.
Confirm that every agent has a distinct workspace and agentDir. Check that credentials and plugin stores are scoped as intended.
For each lane, list allowed tools and denied tools. Attempt one operation that should work and one that should fail.
Verify the effective sandbox mode, workspace access, bind mounts, and elevated gates. Do not rely on the configured value alone.
Send synthetic requests through each route. Confirm that the response, handoff artifact, and session appear where expected.
Run the publisher path with a harmless artifact. Cancel the approval once, change the approved input once, and confirm that neither action is silently executed.
Keep the route map, policy output, audit result, and approval receipt together. Repeat the review after configuration or version changes.

Use the name to explain a lane's purpose. Use configuration to limit its tools. Use a sandbox to limit where those tools run. Use approval for consequential execution. Use separate Gateways when the people operating the system do not share trust. That is the boundary design a multi-agent workflow can actually defend.

Sources

All sources were accessed on 2026-09-13. The official documentation pages do not state publication dates, so the publication-date fields are empty in the source record.