openclaw-workspaces

openclaw-workspaces is a workspace switcher for OpenClaw, built around symlink-based isolation.

It keeps real workspace directories under ~/.openclaw-workspaces/ and makes OpenClaw see exactly one active workspace through ~/.openclaw.

Why It Is Not A Plugin

This project does not modify OpenClaw and does not require OpenClaw plugin hooks, lifecycle integration, runtime interception, or workspace-root support.

The user switches the workspace first:

ocws use billing-v2

Then runs OpenClaw normally. OpenClaw does not need to know this project exists.

Directory Model

Real workspace storage:

~/.openclaw-workspaces/
  registry.json
  .active
  billing-v2/
    data/
    meta.json
  docs-ingestion/
    data/
    meta.json

OpenClaw entry path:

~/.openclaw -> ~/.openclaw-workspaces/<id>

~/.openclaw-workspaces/registry.json is the index layer. It stores the current workspace id and minimal metadata for each workspace:

{
  "version": 1,
  "current": "billing-v2",
  "workspaces": {
    "billing-v2": {
      "createdAt": "2026-04-22T00:00:00.000Z",
      "source": "create",
      "host": "host-name",
      "path": "billing-v2"
    }
  }
}

~/.openclaw-workspaces/.active is still written as a compatibility marker. The registry is the primary index for v0.2.

Each workspace has a lightweight meta.json:

{
  "id": "billing-v2",
  "createdAt": "2026-04-22T00:00:00.000Z",
  "source": "create",
  "host": "host-name",
  "openclawVersion": "",
  "note": ""
}

Install

Clone this repository, make the command executable, and put bin/ on PATH:

chmod +x bin/ocws
export PATH="$PWD/bin:$PATH"

Shortest Path

Adopt an existing OpenClaw directory:

ocws adopt main

This safely moves the existing ~/.openclaw real directory to ~/.openclaw-workspaces/main/data, then recreates ~/.openclaw as a symlink to the workspace root:

Adopted + Activated: main
Existing OpenClaw data moved to: /home/user/.openclaw-workspaces/main/data
/home/user/.openclaw -> /home/user/.openclaw-workspaces/main

Create the first workspace:

ocws create billing-v2

Because .active is missing or empty on first use, this also activates it:

Created + Activated: billing-v2

Create another workspace:

ocws create docs-ingestion

Because a workspace is already active, this creates only the directory:

Created: docs-ingestion (Current: billing-v2)

Switch workspaces:

ocws use docs-ingestion

Check the current workspace:

ocws current

List workspaces:

ocws list

Example output:

* docs     (current)
  main     (adopted)
  billing  (created)

Inspect one workspace:

ocws info docs

Delete safely:

ocws delete docs --dry-run
ocws delete docs

ocws delete <id> refuses to delete the current workspace unless --force is provided.

Pack and import a workspace:

ocws pack docs
scp docs.ocws.tar.gz target:/tmp/
ocws import /tmp/docs.ocws.tar.gz

Imports never overwrite an existing workspace. If the id already exists, the import is renamed, for example docs-2.

Pack all workspaces:

ocws pack --all

Minimal Test Path

Use a temporary HOME so the test does not touch your real OpenClaw state:

tmp="$(mktemp -d)"
HOME="$tmp" ocws create alpha
HOME="$tmp" ocws current
HOME="$tmp" ocws create beta
HOME="$tmp" ocws use beta
HOME="$tmp" ocws current

Expected behavior:

• First create prints Created + Activated: alpha.
• Second create prints Created: beta (Current: alpha).
• use beta points $tmp/.openclaw at $tmp/.openclaw-workspaces/beta.
• current prints Current: beta.
• Each created workspace contains data/ and meta.json.

Broken symlink recovery:

rm "$tmp/.openclaw"
ln -s "$tmp/missing-target" "$tmp/.openclaw"
HOME="$tmp" ocws use beta

This should replace the broken symlink and keep .active as beta.

Existing real directory adoption:

adopt_tmp="$(mktemp -d)"
mkdir "$adopt_tmp/.openclaw"
printf 'keep me\n' > "$adopt_tmp/.openclaw/state.txt"
HOME="$adopt_tmp" ocws create legacy
HOME="$adopt_tmp" ocws adopt legacy
HOME="$adopt_tmp" ocws current
test -f "$adopt_tmp/.openclaw-workspaces/legacy/data/state.txt"

The first create legacy must stop with a clear instruction to run ocws adopt legacy. adopt legacy must move the existing data under ~/.openclaw-workspaces/legacy/data, make ~/.openclaw a symlink, and print Adopted + Activated: legacy.

Current Boundaries

v0.2 implements:

• ocws adopt <id>
• ocws create <id>
• ocws list
• ocws current
• ocws info <id>
• ocws use <id>
• ocws delete <id> [--dry-run] [--force]
• ocws pack <id>
• ocws pack --all
• ocws import <file> [--activate]

It does not promise hot switching while OpenClaw is running.

It also does not provide daemon processes, plugin integration, containers, workspace sync, copy-based switching, process orchestration, port isolation, or network isolation.

License

MIT