Agent Workspace

The Agent Workspace is the directory where the agent runs, stores files, and manages its “home”. It serves as the persistent filesystem for the agent across restarts.

Default Location

By default, the workspace is located at:

Linux/macOS: ~/.openclaw/workspace
Windows: %USERPROFILE%\.openclaw\workspace

You can verify the location by running:

openclaw config get agent.workspace

Configuration

You can override the workspace location in your config.json (or via environment variables).

{
  agent: {
    // Custom workspace path
    workspace: "/var/lib/openclaw/workspace"
  }
}

Environment Variables

OPENCLAW_WORKSPACE: Overrides the workspace path.

Structure

A typical workspace contains:

workspace/
├── .git/               # (Optional) Git history for backup
├── memories/           # Vector store or memory files
├── sessions/           # Session-specific data
├── skills/             # Local skills/tools
├── storage/            # General file storage for agents
└── temp/               # Temporary scratch space

File Map & Access

Agents usually have read/write access to this directory.

Read: The agent can read any file in the workspace.
Write: The agent can create or modify files here.

Security Note

The agent is sandboxed to this directory (logically). While the underlying process might have OS-level permissions, the OpenClaw runtime restricts high-level file operations to the workspace to prevent accidental modification of system files.

Backup Strategy

Since the workspace contains all your agent’s state (memories, custom skills, session logs), it is crucial to back it up.

Git Backup

OpenClaw has built-in support for using Git to version the workspace.

Initialize a git repo in the workspace:
Terminal window
```
cd ~/.openclaw/workspace
git init
```

Configure a remote (e.g., private GitHub repo):

git remote add origin git@github.com:username/my-agent-workspace.git

OpenClaw can be configured to auto-commit changes (feature availability depends on version).

Manual Backup

Simply archive the directory:

tar -czvf openclaw-backup.tar.gz ~/.openclaw/workspace

Moving to a New Machine

To migrate your agent:

Stop the OpenClaw service.
Copy the entire workspace directory to the new machine.
Install OpenClaw on the new machine.
Point the config to the copied workspace.
Start the service.