OpenClaw Agent Workspace: Keep Files, State, and Context Under Control

An AI agent gets sloppy when its home gets sloppy. In OpenClaw, that home is the agent workspace.

The docs define the workspace as the agent's home and the only working directory used for file tools and workspace context. That sentence is doing more work than it looks like. The workspace is where operating instructions, persona, local tool notes, and memory files live. It is also the default current working directory for file tools. If you treat it like a random downloads folder, the agent will eventually confuse durable state, transient output, and prompt context.

For an operator, the goal is simple: keep the workspace boring, private, small enough to inspect, and explicit enough that a fresh session can reassemble the right operating picture without guessing.

The workspace is home, not the whole house

The default workspace path is ~/.openclaw/workspace. If OPENCLAW_PROFILE is set and is not "default", the default becomes ~/.openclaw/workspace-<profile>. Current OpenClaw docs show the workspace override under agents.defaults.workspace in ~/.openclaw/openclaw.json.

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}

That does not mean everything OpenClaw owns belongs inside the workspace. The docs separate the workspace from ~/.openclaw/, which stores config, credentials, and sessions. That split matters. The workspace is what the agent reads as operating memory. ~/.openclaw/ is where sensitive runtime machinery lives. Do not blur those together in git, docs, or prompts.

There is one safety detail I want every operator to remember: the workspace is the default cwd, not a hard sandbox. Relative paths resolve against the workspace, but absolute paths can still reach elsewhere on the host unless sandboxing is enabled. If sandboxing is enabled and workspaceAccess is not "rw", tools operate inside a sandbox workspace under ~/.openclaw/sandboxes, not the host workspace.

So the workspace is a control surface, not a containment guarantee. Use it for clarity. Use sandboxing and tool policy for isolation.

Keep one active workspace unless you have a reason

OpenClaw warns about extra workspace directories because multiple active-looking homes create state drift. Older installs may have created ~/openclaw. The docs recommend keeping a single active workspace, archiving old folders if you no longer use them, and making sure agents.defaults.workspace points to the intended one if you deliberately keep more than one.

This is not just cleanup advice. If an agent reads one AGENTS.md, writes memory in another folder, and stores config somewhere else, you get the worst kind of bug: the agent appears to remember something, but the next run cannot find the same truth.

My rule is blunt: one agent, one active workspace, one obvious memory tree. If you need profiles, make the profile boundary deliberate and visible.

Know what each workspace file is for

The standard workspace files are not decoration. AGENTS.md holds operating instructions. SOUL.md holds persona and boundaries. USER.md tells the agent who it is helping. IDENTITY.md names the agent. TOOLS.md stores local tool conventions; it does not control tool availability. HEARTBEAT.md is an optional small checklist. BOOT.md is an optional startup checklist when internal hooks are enabled. BOOTSTRAP.md is for first run only and should go away after that ritual.

Memory belongs in files such as memory/YYYY-MM-DD.md for daily logs and, optionally, MEMORY.md for curated long-term facts. The docs are explicit that detailed logs should stay in daily memory so memory tools can retrieve them later without injecting everything into every prompt.

That is the operator pattern: durable instructions at the top, topic memory in files, daily notes in daily files, and generated junk somewhere else. If you want your agent to behave consistently for months, stop making every file equally important.

If you manage workspace files yourself, OpenClaw lets you disable bootstrap file creation:

{ agents: { defaults: { skipBootstrap: true } } }

Use that only when you actually own the file discipline. Otherwise the default bootstrap behavior is helpful: setup commands create the workspace and seed missing bootstrap files.

Context is not memory

This is where a lot of agent setups get confused. OpenClaw's context docs define context as everything sent to the model for a run, bounded by the model's context window. It includes the system prompt, conversation history, tool calls and results, attachments, compaction summaries, pruning artifacts, and provider wrappers you may not see.

Memory is different. Memory can be stored on disk and reloaded later. Context is what is inside the model window right now. A memory file can exist for years and still be absent from a particular model call if nothing loads it. A giant tool result can be in context for one turn and never become durable memory.

That distinction is the difference between an agent that operates and an agent that hoards text.

/status
/context list
/context detail
/context map
/usage tokens
/compact

/status gives a quick view of how full the window is. /context list shows what is injected and rough sizes. /context detail breaks down files, tool schemas, skills, and system prompt size. /context map can render a treemap image from the latest cached run report. /usage tokens appends token usage. /compact summarizes older history to free room.

Mid-run operator check: if your agent is getting expensive, forgetful, or weirdly overconfident, inspect context before rewriting personality files. Want the complete operating checklist? Get ClawKit — $9.99.

Keep bootstrap files sharp because they are injected

The system prompt is rebuilt by OpenClaw each run. The docs say it includes tool descriptions, skill metadata, workspace location, time, runtime metadata, and injected workspace bootstrap files under Project Context. Skills are listed by metadata and loaded on demand; their full instructions are not injected by default.

That has two practical consequences. First, a bloated TOOLS.md or AGENTS.md can tax every run even when today's task is simple. Second, pushing every detail into static bootstrap files is not the same as reliable recall. It is just prompt weight.

Current docs show per-file and total bootstrap injection caps, and /context reports raw versus injected sizes and truncation. If a file is truncated, the model may see the beginning and the end but miss the exact middle detail you assumed was loaded. That is a miserable failure mode because the agent sounds informed while operating from partial instructions.

My preference: bootstrap files should route the agent to the right topic files. Topic files should hold detail. Daily logs should hold chronology. The model should load what it needs instead of carrying the entire company in every reply.

The context engine decides what reaches the model

OpenClaw ships with the built-in legacy context engine and uses it by default. Most users should leave that alone. A context engine controls context assembly: which messages to include, how to summarize older history, and how to manage context across subagent boundaries.

openclaw doctor
cat ~/.openclaw/openclaw.json | jq '.plugins.slots.contextEngine'

The lifecycle is documented as ingest, assemble, compact, and after turn. The assemble step can return messages plus an optional system prompt addition. Compaction runs when the context window is full or when the user runs /compact. OpenClaw also documents optional subagent lifecycle hooks for preparing child runs and cleaning up when subagents end.

If you do select a plugin context engine, the active slot is plugins.slots.contextEngine. The docs say the slot is exclusive at run time; other enabled context-engine plugins can load, but only the selected registered engine id is resolved when OpenClaw needs context assembly or compaction.

{
  plugins: {
    slots: {
      contextEngine: "legacy",
    },
  },
}

One warning is worth repeating: if a plugin engine fails to register, or the selected engine id cannot be resolved, OpenClaw does not automatically fall back. Runs fail until you fix the plugin or switch the slot back to "legacy". That is good fail-closed behavior, but it means context-engine experiments belong in controlled setups, not your only production operator at 9 p.m.

Transcript hygiene is runtime repair, not a memory strategy

Transcript hygiene is the quiet plumbing that keeps provider payloads acceptable. The docs describe provider-specific fixes applied before a run while building model context. Most are in-memory adjustments. A separate session-file repair pass may rewrite malformed stored JSONL before load, but ordinary provider-specific hygiene is not a license to treat transcripts as a trash can.

The global rules include image sanitization, dropping malformed assistant tool-call blocks that have neither input nor arguments, and tagging inter-session routed prompts with provenance. The provider matrix varies: OpenAI/Codex gets image sanitization and reasoning cleanup behavior; Google-style providers have stricter tool-call and turn-shape repairs; other providers receive their own fixups.

The buyer/operator lesson is simple. Transcript hygiene keeps the engine from crashing on replay shape. It does not decide what your business should remember. If a decision matters, write it to the right memory file. If a giant tool result is temporary, do not promote it. If a message came from another session, respect the provenance marker instead of pretending it was the end user.

A sane workspace operating loop

Here is the loop I trust:

1. Keep the workspace private. It contains operating memory and user context. Back it up to a private repo if you use git, but do not commit credentials or raw sensitive dumps.
2. Separate durable memory from prompt context. Write decisions to files. Use /context to inspect what the current run actually sees.
3. Keep bootstrap files lean. Put routing rules and stable identity there. Move detail into topic files the agent can load on demand.
4. Use compaction deliberately. Long sessions need summaries, but summaries are not audits. Preserve important results in memory files before relying on compaction.
5. Treat context-engine changes as infrastructure. Check with openclaw doctor, understand the selected slot, and avoid plugin experiments in production without a rollback.

This is not glamorous, but it is how you make an agent feel less haunted. Files hold durable truth. Context holds the current working set. The context engine decides assembly. Transcript hygiene keeps provider replay sane. The workspace gives all of that a home.

If you remember one thing, remember this: do not confuse “the agent can read it” with “the model saw it this turn” or “the system will remember it next week.” Those are three different contracts. Keep them separate and OpenClaw becomes much easier to operate.

Want the complete guide? Get ClawKit — $9.99