OpenClaw workspace files explained: what matters daily and who owns each change

By OpenClawBlog Team · Published May 20, 2026

An OpenClaw assistant can appear to forget a preference, follow an old personality, or ignore a local rule for a simple reason: the file was placed in the wrong workspace, has been replaced by a newer source of truth, or was never a supported runtime file.

The useful question is not only which files exist. It is which files are read at session startup, which ones are optional, which ones contain private memory, and who is accountable when one changes.

This guide separates documented OpenClaw behavior from suggested operator practice. The ownership register is a convention you can adopt; it is not an OpenClaw configuration schema.

The first boundary: workspace, state, and execution folder

OpenClaw describes the workspace as the agent's home: the working directory used for file tools and workspace context. It is separate from ~/.openclaw/, which contains configuration, credentials, session data, and other runtime state. The usual default is ~/.openclaw/workspace, but profiles, OPENCLAW_WORKSPACE_DIR, agents.defaults.workspace, and per-agent workspace settings can change the path. The Agent workspace guide documents those resolution rules.

That directory is also the default working directory for tools. It is not automatically a hard sandbox. A tool using an absolute path may still reach another location on the host unless sandboxing is enabled. If the assistant handles personal files or credentials, document the sandbox decision beside the workspace path rather than assuming that the word workspace provides isolation.

A second path can confuse matters. When an agent runs from a project or managed worktree, that folder is the execution workspace. The system prompt reference says an execution folder's AGENTS.md can be added as project context, but OpenClaw does not load SOUL.md, IDENTITY.md, USER.md, MEMORY.md, or BOOTSTRAP.md from that execution folder. The configured agent workspace remains the source for those bootstrap files.

A small configuration example makes the distinction visible:

agents: {
  defaults: { workspace: '~/.openclaw/workspace' },
  entries: {
    research: { workspace: '~/.openclaw/workspace-research' }
  }
}

In a multi-agent setup, do not describe the parent directory as if it were the agent's workspace. Record the resolved path for each agentId.

The files that matter in daily operation

The current workspace map identifies a small group of user-editable files. They do different jobs, and combining them into one large instruction file makes later review harder.

File or folder	What it is for	What to remember
`AGENTS.md`	Operating instructions, priorities, and memory conventions.	It is loaded at session startup. Its `## Tools` section is guidance, not a mechanism that grants or removes tools.
`SOUL.md`	Persona, tone, and behavioral boundaries.	Keep style here. Do not hide access-control rules in prose that is difficult to review.
`IDENTITY.md`	Agent name, vibe, emoji, and optional avatar.	Configured identity fields take precedence when they are set. The file is a fallback and a readable record.
`USER.md`	Stable user preferences and profile facts written as directives.	Use dated active or superseded entries. The workspace guide gives it a separate 4,000-character budget.
`MEMORY.md`	Curated long-term facts, decisions, and short summaries.	It is optional and belongs to the root of the configured workspace. Current guidance limits it to the main private session.
`memory/YYYY-MM-DD.md`	Detailed daily notes and working context.	These files are useful for retrieval but are not injected into every prompt. Keep raw logs here only when their retention is justified.
`BOOT.md` and `BOOTSTRAP.md`	Startup checklist or one-time first-run ritual.	`BOOT.md` needs the boot hook. `BOOTSTRAP.md` is for a new workspace and should disappear after setup.
`skills/`	Workspace-specific skills.	This location has higher precedence than several lower-level skill folders, so adding a skill is a behavior change worth reviewing.

The agent runtime reference confirms the bootstrap set and explains that missing required files produce a marker rather than silently changing the rest of the prompt. Blank files are skipped, and large files can be trimmed.

Two names from older setups need special treatment. TOOLS.md is retired: current local tool and environment notes belong in the ## Tools section of AGENTS.md. The TOOLS.md migration page says openclaw doctor --fix can archive the old file and merge its customized content. HEARTBEAT.md is retired too. The current heartbeat reference says heartbeat instructions now live in system-owned monitor scratch rather than a workspace file.

What gets injected, and what does not

OpenClaw injects workspace bootstrap content into the system prompt's Project Context at the start of a new session. That does not mean every file is equally present on every turn. Optional USER.md and MEMORY.md can be absent. The memory overview says daily notes are indexed for memory tools but are not placed into the bootstrap prompt on every turn.

There are size limits. The workspace guide lists a general per-file default of 20,000 characters and a total bootstrap default of 60,000 characters, with a separate 4,000-character budget for USER.md. A long AGENTS.md can therefore be technically present while the most important paragraph is outside the injected context. Keep durable rules short and move detailed procedures into linked documents that can be read when needed.

Memory is also not enforcement. The memory overview recommends recording authority, timing, expiry, and ownership when those details affect future action, but it states that memory does not enforce policy. Use approvals, tool policy, scheduled-task controls, and sandboxing for hard boundaries.

A short preflight before editing files

Before changing a workspace, answer these questions:

Which machine runs the Gateway, and which operating-system account owns the process?
Which agentId is receiving the work?
What path does that agent actually use?
Is the workspace shared, per-agent, or inside a sandbox?
Which human reviews changes to behavior, identity, memory, and skills?

The documented CLI surface gives you a starting point:

openclaw agents list --json
openclaw agents list --bindings

Use the output to confirm the agent and its routing before editing a file. The agents CLI reference also documents per-agent workspace selection and identity handling. If several agents are configured, give each one a distinct workspace and never reuse an agentDir; the multi-agent routing guide warns that shared agent directories cause authentication and session-state collisions.

For a path change, stop treating similarly named folders as interchangeable. Older installations may leave extra workspace directories behind, but OpenClaw uses one resolved workspace for an agent. Record the active path, then archive an unused directory only after checking which files and memories it contains.

Document ownership in the workspace itself

OpenClaw's documentation explains file purpose and runtime location. It does not give you a universal ownership manifest. I would add a short register to AGENTS.md, with a link to a longer private document if the setup needs one. Keeping the summary in AGENTS.md makes it part of the context an operator is likely to see; a custom file such as WORKSPACE-OWNERSHIP.md is not a special bootstrap file.

## Workspace ownership
- Agent ID: main
- Configured workspace: ~/.openclaw/workspace
- Gateway host and OS account: <host> / <user>
- Human owner: <person or team>
- Reviewer for behavior files: <person or team>
- Versioned source of truth: private repository <name>
- Allowed data: <short classification>
- Never store: credentials, raw private transcripts, or sensitive attachments
- Change rule: behavior and access changes require human review
- Last path check: YYYY-MM-DD

Use ownership to mean accountability, not permission granted to the model. The human or team owns the decision. The agent may write a daily note or propose a change, but it should not silently approve a new boundary for itself.

A practical division looks like this:

AGENTS.md and SOUL.md: reviewed by the person responsible for the agent's operating behavior.
IDENTITY.md: reviewed by the person who owns the visible agent identity. Check configuration too, because configured identity fields can override the file.
USER.md: reviewed by the user or service owner. Supersede changed preferences instead of leaving contradictory active directives.
MEMORY.md and daily notes: maintained by the workflow, with a human review step before a sensitive or consequential fact becomes durable.
skills/: reviewed by whoever owns the tool and supply-chain boundary. A workspace skill can outrank another installed copy.

Put a review date beside changes that can alter future behavior. Also record the source of truth. If a field is really controlled by openclaw.json, say so. If a note is copied from a channel message, mark it as unverified until someone checks it.

Keep the backup boundary honest

The workspace guide recommends a private Git repository for workspace files because the directory contains the assistant's memory and operating instructions. That repository is a backup for the workspace, not automatically a backup of the installation. The same guide says not to commit API keys, OAuth tokens, passwords, anything under ~/.openclaw/, or raw chat dumps.

The runtime state outside the workspace includes configuration, credential stores, agent databases, session rows, transcripts, and managed skills. A cloned workspace can restore instructions and memory files while leaving the agent logged out or without its session history. Handle that state through the supported backup or migration path, and keep it out of ordinary source control.

Do not use a workspace .env file as a general secret store. The secrets and storage guide says workspace-local environment files can load for agents and tools, but provider credential variables and the OPENCLAW_* namespace are blocked from untrusted workspace files. Put credentials in the Gateway environment, the state directory's environment file, the configuration environment block, or the supported login-shell path.

Failure paths and limits

The assistant keeps the old persona

Check the resolved agent workspace first. Then check whether identity fields are already configured. The file may be correct and still lose to configuration precedence. Also confirm that the running Gateway is using the same profile and host that you inspected.

A local rule has no effect

Look for truncation, a missing-file marker, or an instruction placed in the execution folder instead of the configured workspace. A project-level AGENTS.md can add project context, but a project-level SOUL.md is not a substitute for the agent workspace file.

An old automation file is ignored

Do not keep repairing TOOLS.md or HEARTBEAT.md by trial and error. Move tool notes into AGENTS.md. For heartbeat behavior, inspect the current monitor and automation configuration. The retired files are migration inputs, not current control surfaces.

The agent reaches more files than expected

That is the workspace boundary working as documented: it sets a default working directory, not a complete host sandbox. Enable and verify sandboxing when the task needs isolation. A path register should state whether absolute paths and host tools are allowed.

Two agents begin sharing state

Check for a reused agentDir, a shared workspace path, or a binding that points to the wrong agent. Separate workspaces keep persona and local notes distinct, but they do not remove every cross-agent or shared-Gateway risk. If users do not share one trust boundary, use separate gateways, credentials, or hosts.

The decision rule is simple. If a file changes behavior, identity, or durable context, keep it in the documented workspace map and assign a human owner. If it contains credentials, session history, or runtime state, keep it outside the workspace repository and protect it as private operational data. That small distinction makes daily fixes easier to review and failed recoveries easier to explain.

Sources

Agent workspace - OpenClaw — workspace paths, file map, injection limits, sandbox boundary, Git backup, and excluded runtime state.
Agent runtime - OpenClaw repository — bootstrap files, missing-file behavior, truncation, tools guidance, and skill precedence.
System prompt - OpenClaw — configured workspace files versus the execution folder.
Memory overview - OpenClaw — USER.md, MEMORY.md, daily notes, retrieval, and policy limits.
Multi-agent routing - OpenClaw — per-agent workspaces, agent directories, session stores, and trust boundaries.
Agents - OpenClaw — agent listing, workspace selection, bindings, and identity precedence.
Secrets, storage, and logs - OpenClaw — credential locations, permissions, workspace environment files, and transcript risks.
AGENTS.md template - OpenClaw — memory conventions, tool notes, directives, and red lines.
TOOLS.md retired - OpenClaw — migration of tool notes into AGENTS.md.
Retired HEARTBEAT.md workspace file - OpenClaw — current monitor-scratch boundary.