Guide

OpenClaw isolation: when to use separate sessions, agents, or workspaces

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

Published May 21, 2026 · OpenClawBlog Team

A single OpenClaw agent is easy to start. The trouble begins when one person moves from private notes to work files, or when two people use the same assistant and assume their conversations are private. At that point, the practical question is not whether OpenClaw supports more agents. It is which part of the system needs to be separate.

OpenClaw gives you several boundaries. A session separates conversation context. An agent owns a broader set of identity, files, credentials, skills, model choices, and session state. A workspace gives the agent its working directory and bootstrap context. Sandboxing and separate Gateways handle stronger tool and trust boundaries.

The short answer

Choose	Use it when	It separates	It does not solve by itself
New session	The same person starts a different job and the agent should not carry the old conversation into it.	Conversation history and the current model context.	Shared files, credentials, tools, shared workspace memory, or access to other sessions.
Separate agent	A person, role, project, provider account, or permission set needs its own operating scope.	Workspace, agent state, auth profiles, model registry, skills, and session store.	The wider authority of a shared Gateway or its administrators.
Separate workspace	Files and instructions for one agent should have a different home from another agent.	Default working directory and workspace context.	Host filesystem access unless sandboxing is enabled, or configuration and credentials outside the workspace.
Separate Gateway or host	People with different trust levels must not share sessions, tools, credentials, or files.	The operator and infrastructure trust boundary.	Extra operational work: another service, backup path, monitoring plan, and routing map.

This is an editorial decision rule based on the documented architecture. The smallest boundary is usually easier to operate, but a small boundary that protects the wrong thing is only reassuring on paper.

Start with the asset you need to protect

Before changing the configuration, name the asset at risk. Is it an old conversation? A repository? A provider account? A tool that can send messages or modify files? Or the identity of the person allowed to operate the system?

For conversation context, start with a session.
For a different persona, file set, provider account, skill set, or model policy, use an agent.
For tool reach, add a sandbox and choose its workspace access deliberately.
For people who must not share authority, use a separate Gateway or host.

These choices can be combined. A work agent may have its own workspace and an agent-scoped sandbox. Each of its users may still need separate sessions. The labels are useful only when they map to a real boundary.

When a new session is enough

OpenClaw routes an inbound message into a session based on where it came from. The upstream session documentation describes direct messages as sharing one main session by default, while groups and rooms are isolated by default. That default suits a single operator who wants continuity across direct chats. It is a poor default for unrelated people.

For one person, a fresh session is a sensible boundary between jobs such as planning a trip and reviewing a code change. The agent can keep the same model, tools, workspace, and credentials while starting with a cleaner conversation. A manual /new or /reset works for a deliberate break; daily and idle reset policies are available when freshness should happen automatically.

The session key is the conversation bucket selected by routing and isolation. The session-key reference also distinguishes ordinary conversations from cron and webhook sessions. That makes a session useful for keeping a background job from appearing inside a personal chat.

For several people using one agent, inspect session.dmScope. The documented choices include main, per-peer, per-channel-peer, and per-account-channel-peer. The latter options keep direct-message histories apart by sender, channel, or account. If the same person contacts the agent through multiple channels, identityLinks can intentionally join those identities.

Groups and rooms have a similar choice through session.groupScope. The default per-group keeps each group or channel in its own context. Routing one room into main can be useful for a deliberate shared team conversation, but it should be a conscious exception. The channel routing documentation notes that session-key selection does not replace mention gating, delivery rules, or the originating room.

A reset is a context boundary, not a deletion guarantee. The Gateway still owns session records and transcripts, and shared workspace files may remain available. If the reason for the split is privacy or access control, stop treating a new session as sufficient.

When to create a separate agent

Use a separate agent when the job needs a different operating identity. OpenClaw's multi-agent documentation describes an agent as the full per-persona scope. Each agent can have its own workspace, agent state directory, authentication profiles, model registry, skills, and SQLite-backed session store.

That makes an agent the better fit for boundaries such as personal work versus company work, customer support versus repository maintenance, or a low-risk research role versus a role allowed to change production files. The difference is not the name in the sidebar. It is the state and authority attached to that name.

Agent routing is also the right place to keep a channel account tied to the intended role. Bindings select an agent for an inbound channel, account, or peer. The matched agent then determines which workspace and session store receive the conversation. A useful starting point from the documented CLI is:

openclaw agents add work --workspace ~/.openclaw/workspace-work --non-interactive
openclaw agents list --bindings

This is a documentation-derived setup shape, not a test performed for this article. Use an explicit workspace path, give the agent a purpose that can be explained in one sentence, and verify the resulting bindings before sending real messages.

Keep the agent state directory unique. The multi-agent documentation warns against reusing agentDir across agents because auth and session state can collide. A second workspace with a shared agent directory is not the separation you intended. Skills also deserve a check: shared roots can remain available, while explicit per-agent skill entries can replace the defaults.

What a separate workspace does, and does not do

The agent workspace documentation calls the workspace the agent's home: the default working directory and a source of workspace context such as instruction and identity files. In a multi-agent setup, each agent resolves one workspace. Extra folders do not automatically merge their persona files or memory into the active agent.

This is useful when two roles should see different project notes, bootstrap files, or repository checkouts. It is also a reason to make the path explicit. An operator should be able to answer which workspace an agent uses before approving a write.

A workspace is not a hard sandbox. Relative paths resolve inside it, but absolute paths can reach other locations on the host unless sandboxing is enabled. A new folder therefore separates the agent's normal working context, not every path the process might access. It also does not, by itself, move configuration, credentials, or session storage into a different trust boundary.

For tool access, use the documented workspace access controls. With workspaceAccess: none, tools use an isolated sandbox workspace and cannot see the agent workspace. With ro, the agent workspace is mounted read-only. With rw, tools can write to it. The permissions page describes agent scope as the normal sandbox boundary and session scope as a stricter per-session option; shared puts multiple runs in one container or workspace.

Do not describe rw as protection. It is access. Do not assume the same setting controls a remote SSH or OpenShell host; the workspace reference says remote shell execution relies on the remote host's policy. If the job needs a filesystem boundary, check the actual execution backend.

A worked example for two people and three jobs

Consider a hypothetical setup. Alice uses OpenClaw for private planning. Bob handles a work channel. A shared team room contains documents that both are allowed to discuss. The right design depends on whether Alice and Bob are trusted with the same tools, files, and provider accounts.

If they are trusted operators of one shared agent, use DM isolation so a direct conversation does not collapse into one shared history. A channel-and-peer scope is a reasonable starting point when the same channel has more than one account or identity. Keep groups per group unless a specific room really belongs in the main conversation. In this design, both people still operate the same agent. They should be comfortable with that agent's tool and file permissions.

If Bob needs different instructions, a different repository, a separate model account, or a different skill allowlist, create a work agent with its own workspace and agent directory. A simplified JSON5 shape is:

{
  agents: {
    entries: {
      personal: { default: true, workspace: '~/.openclaw/workspace-personal' },
      work: { workspace: '~/.openclaw/workspace-work' },
    },
  },
  bindings: [
    { agentId: 'work', match: { channel: 'slack', teamId: 'T123' } },
  ],
}

The example gives the work route a different agent and workspace. It does not make the Gateway private, and it does not prove that Bob cannot inspect another session. Those are separate questions.

If Alice and Bob must not access each other's sessions, tools, credentials, or files, use a separate Gateway or host trust boundary. OpenClaw's multi-user guidance is direct on this point: ownership labels, presence, and sidebar filters help people coordinate, but they are not security boundaries.

Failure paths to plan for

A new session still sees old private material

Sessions control conversation history, but shared workspace memory can have its own behavior. The session documentation says optional cross-conversation recall and shared files such as MEMORY.md or memory/*.md are separate from session-key selection. If private information must not cross a boundary, review memory ownership and file access, then test with synthetic data. A reset alone is not enough.

A separate agent shares credentials unexpectedly

Check the agent directory before checking the model. Reusing an agentDir can create auth and session collisions. If a fully independent provider account is required, sign in for the intended agent and verify the stored profile. A different display name or workspace path does not prove that credentials are separate.

A workspace split does not stop a host-file read

Check whether sandboxing is enabled, which workspace access mode is active, and whether elevated execution is allowed. The tool and agent permissions reference describes elevated execution as an escape hatch outside the sandbox. Remote shell paths need their own host policy as well.

Separate agents still expose a shared Gateway

A shared Gateway can retain broad operator authority. The permissions documentation notes that session visibility is Gateway-wide and agent-to-agent messaging is enabled by default, while the multi-user documentation says an authenticated administrator can manage automation created by another person. Narrow session and agent-to-agent policies where appropriate. If the administrator boundary itself must be separate, move the agents to separate Gateways or hosts.

The route reaches the wrong session

Check the channel account, peer identity, DM scope, group scope, and binding precedence together. A default DM scope of main can make separate people appear to share context. A binding that joins one room to main can also be intentional, which is why the operator should document the reason rather than infer it from the resulting chat.

A practical preflight

Proposed check, not a test run for this article. Before connecting real accounts, write the expected result for each route. Record the channel or peer, selected agent, expected session key, workspace path, sandbox mode, and allowed tools. Then inspect the configuration with the documented commands:

openclaw agents list --bindings
openclaw sessions --json
openclaw status
openclaw security audit

Send synthetic messages through each route and confirm that the response lands in the intended session. Ask the agent to identify its working directory without exposing private files. Test a denied operation as well as an allowed one. Finally, repeat the check after a Gateway restart or a configuration reload. These are proposed operator checks; this article does not claim that they were run against a live installation.

Choose a new session when the problem is stale context. Choose a separate agent when the problem is identity, state, files, or policy. Add a sandbox when the problem is tool reach. Choose a separate Gateway or host when the problem is trust between operators. That sequence keeps the decision tied to the boundary that needs protection.

Sources

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