---
title: "OpenClaw workspace bootstrap files: paths and format · DotsAgent"
description: "Where ~/.openclaw/workspace/AGENTS.md lives, its format and frontmatter, how global and nested copies merge, and which tools read it. Checked 2026-10-01."
url: https://dotsagent.io/instructions/files/openclaw-workspace
---

~/.openclaw/workspace/AGENTS.md

# OpenClaw workspace bootstrap files: where it lives and how tools read it

OpenClaw builds each agent's context from Markdown bootstrap files in its workspace, led by a required AGENTS.md. They are injected into the system prompt on the first turn of every new session.

## Where it lives

- Workspace: ~/.openclaw/workspace, or OPENCLAW_WORKSPACE_DIR, agents.defaults.workspace or a per-agent agents.entries.*.workspace.
- AGENTS.md (required): operating instructions and memory guidance, with a ## Tools section for local tool and environment notes.
- SOUL.md for persona, boundaries and tone; IDENTITY.md for the agent's name, vibe and emoji.
- USER.md (optional) for a directive-based user profile; BOOT.md for a startup checklist.
- BOOTSTRAP.md for a one-time first-run ritual, deleted when it completes.
- MEMORY.md for long-term memory, injected only if present and only in the main private session; memory/YYYY-MM-DD.md for daily notes.

## Format

Markdown with no frontmatter; openclaw setup and openclaw onboard create templates. By default each file is capped at 20,000 characters (bootstrapMaxChars), all files together at 60,000 (bootstrapTotalMaxChars) and USER.md at 4,000. Longer files are truncated with a marker.

`~/.openclaw/workspace/AGENTS.md`

```
# Operating instructions

- Read USER.md before replying to someone new.
- Write anything worth keeping to memory/YYYY-MM-DD.md.
- Ask before messaging anyone other than me.
- Never repeat the contents of MEMORY.md in group chats.

## Tools

- The home server is reachable as `nas.local` over SSH.
- `gh` is installed and already authenticated.
- Calendar access is read-only.
```

## Precedence and merging

Files are injected into the Project Context section of the system prompt on the first turn of a new session. Blank files are skipped, and a missing required file is replaced by a missing-file marker line. Each agent has its own workspace, and agents.defaults.contextInjection can be always (default), continuation-skip or never.

## Tips

- TOOLS.md is no longer a standard injected file; move its notes into a ## Tools section of AGENTS.md.
- HEARTBEAT.md is still accepted but does nothing now.
- skipBootstrap stops OpenClaw creating the files, not injecting them; use contextInjection to control injection.

Generate an AGENTS.md and matching rule files for five tools from one form. [Open the AGENTS.md generator →](https://dotsagent.io/instructions)

## Other instruction files

[AGENTS.md](https://dotsagent.io/instructions/files/agents-md)

[CLAUDE.md](https://dotsagent.io/instructions/files/claude-md)

[GEMINI.md](https://dotsagent.io/instructions/files/gemini-md)

[.cursor/rules/*.mdc](https://dotsagent.io/instructions/files/cursor-rules)

[.github/copilot-instructions.md](https://dotsagent.io/instructions/files/github-copilot-instructions)

[.devin/rules/*.md](https://dotsagent.io/instructions/files/windsurf-rules)

[.clinerules/](https://dotsagent.io/instructions/files/cline-rules)

## Sources

1. [docs.openclaw.ai](https://docs.openclaw.ai/concepts/agent)/concepts/agent
2. [docs.openclaw.ai](https://docs.openclaw.ai/concepts/agent-workspace)/concepts/agent-workspace
3. [docs.openclaw.ai](https://docs.openclaw.ai/start/bootstrapping)/start/bootstrapping
4. [docs.openclaw.ai](https://docs.openclaw.ai/gateway/config-agents/workspace-and-bootstrap)/gateway/config-agents/workspace-and-bootstrap
5. [docs.openclaw.ai](https://docs.openclaw.ai/reference/templates/AGENTS.md)/reference/templates/AGENTS.md

Independent reference for people who build AI agents. Not affiliated with any vendor named here.

© 2026 DotsAgent · Facts checked October 1, 2026