Agent Workspace Isolation

+15 Mana ✨
OpenClaw Agent Workspaces(DOCUMENTATION)

Introduction

Each agent in a multi-agent OpenClaw gateway operates in its own isolated workspace. This means separate configuration files, state directories, authentication profiles, and session stores. Understanding the boundaries between agentId, accountId, and binding is critical for designing clean multi-agent architectures.

Key Concepts

  • agentId: A unique identifier for an agent definition. Each agentId has its own workspace directory, bootstrap files, and configuration.
  • accountId: Identifies a specific account on a channel (e.g., a WhatsApp phone number or Discord bot token). One agent can be bound to multiple accounts.
  • Binding: The mapping between a message context and an agent. Bindings connect accountIds and channels to agentIds.
  • Workspace Directory: Each agent's workspace lives at ~/.openclaw/agents/<agentId>/workspace/, containing SOUL.md, AGENTS.md, MEMORY.md, and other bootstrap files.

Real World Context

A consulting firm runs three agents: one for each client project. Each agent has its own SOUL.md (different tone per client), its own MEMORY.md (project-specific knowledge), and its own session store (client conversations never mix). The workspace isolation ensures that Agent A's memory about Client A never leaks into Agent B's responses to Client B.

Deep Dive

The directory structure for a multi-agent gateway looks like this:

bash
~/.openclaw/
├── openclaw.json          # Main gateway config
├── agents/
│   ├── code-reviewer/
│   │   ├── workspace/
│   │   │   ├── SOUL.md
│   │   │   ├── AGENTS.md
│   │   │   └── MEMORY.md
│   │   ├── sessions/
│   │   │   ├── session-abc.jsonl
│   │   │   └── session-def.jsonl
│   │   └── auth/
│   │       └── profiles.json
│   ├── deployer/
│   │   ├── workspace/
│   │   │   ├── SOUL.md
│   │   │   └── AGENTS.md
│   │   ├── sessions/
│   │   └── auth/
│   └── general/
│       ├── workspace/
│       ├── sessions/
│       └── auth/

This tree shows three agents, each with completely separate workspace, session, and auth directories. The code-reviewer's SOUL.md defines a code-focused persona, while the deployer's SOUL.md defines an operations-focused persona. Their session stores are independent, so conversations never cross-contaminate.

The relationship between these identifiers is:

  • agentId identifies the agent definition (e.g., code-reviewer)
  • accountId identifies a channel account (e.g., whatsapp:+1234567890)
  • binding connects them: "messages from accountId X go to agentId Y"

One agent can handle multiple accounts, and one account can only be bound to one agent at a time.

json
{
  "agents": {
    "support-bot": {
      "bindings": [
        { "type": "account", "accountId": "whatsapp:+1111111111" },
        { "type": "account", "accountId": "whatsapp:+2222222222" }
      ]
    }
  }
}

This configuration binds two WhatsApp numbers to the same support-bot agent. Both numbers share the same workspace, memory, and session store. Messages from either number are handled by the same agent personality.

Common Pitfalls

  1. Assuming agents share memory — Each agent has its own MEMORY.md. Information stored by one agent is not visible to another unless you explicitly set up shared paths.
  2. Binding one account to multiple agents — An accountId can only be bound to one agent. If you define conflicting bindings, the first match wins and the second is silently ignored.

Best Practices

  1. Name agentIds descriptively — Use names like code-reviewer or support-us-east rather than agent1 or bot2.
  2. Back up workspace directories — Each agent's workspace contains irreplaceable data (memory, session history). Include these in your backup strategy.

Summary

  • Each agentId has a fully isolated workspace with its own bootstrap files, sessions, and auth
  • agentId identifies the agent, accountId identifies a channel account, bindings connect them
  • One agent can handle multiple accounts, but one account maps to exactly one agent
  • Workspaces live at ~/.openclaw/agents/<agentId>/workspace/
  • Agent isolation prevents memory leaks and conversation cross-contamination between agents
✓ Completed