OpenClaw injects a recognized set of markdown bootstrap files from each agent workspace. AGENTS.md defines operating instructions, SOUL.md shapes the assistant's identity, and USER.md provides user context. Other standard files cover tools, identity, heartbeat tasks, and first-run setup; arbitrary .md files are not automatically injected.
The Complete Guide to OpenClaw Configuration Files (.md Files)
OpenClaw uses recognized markdown files in the configured agent workspace to assemble bootstrap context. The standard names include AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, and BOOTSTRAP.md; MEMORY.md is optional. Each filename has a defined role, so use the documented name instead of inventing persona.md, tasks.md, or skills.md files and expecting them to load automatically.
Last fact-checked against the OpenClaw agent workspace documentation on July 15, 2026.
Which OpenClaw .md files are injected from the agent workspace?
| File | Purpose | Priority | Guide |
|---|---|---|---|
SOUL.md | Personality, voice, values, ethical constraints | Must-have | Full Guide |
AGENTS.md | Operating rules, security boundaries, session behavior | Must-have | Full Guide |
USER.md | Your personal context, role, business details | Must-have | Full Guide |
IDENTITY.md | Agent name, emoji, creature type, avatar | Recommended | Full Guide |
TOOLS.md | Environment info, SSH hosts, installed tools | Optional | Full Guide |
MEMORY.md | Long-term memories, learned context, preferences | Recommended | Full Guide |
HEARTBEAT.md | Scheduled tasks, periodic check-ins, recurring actions | Optional | Full Guide |
BOOTSTRAP.md | First-run instructions for a new workspace | Optional | Full Guide |
Quick Start — Your First 3 Files
You only need three files to get a fully configured OpenClaw agent. Start with these, then add optional files as your needs grow. The entire process takes under 10 minutes.
1Create SOUL.md — Your Agent's Personality
SOUL.md defines who your agent is — its values, communication style, and behavioral constraints. This is the most important configuration file because it shapes every response your agent generates. Write it in plain English, describing the personality you want.
# SOUL
## Core Truths
- I am a helpful AI assistant focused on productivity and clarity
- I value accuracy over speed — I verify before I answer
- I respect user privacy and never share personal information
## Boundaries
- I never fabricate data, statistics, or citations
- I clearly state when I'm uncertain about something
- I ask for clarification rather than making assumptions
## Vibe
- Professional but approachable
- Concise — I get to the point quickly
- I use examples to illustrate complex concepts
## Continuity
- If you change this file, tell the user — it's your soul, and they should know
- This file is yours to evolve as you learn the user's preferences2Create AGENTS.md — Operating Rules and Security
AGENTS.md sets the guardrails for what your agent can and cannot do. It defines security rules, session startup behavior, and operating procedures. AGENTS.md takes priority over SOUL.md for security matters — if there is a conflict, AGENTS.md wins. This ensures your safety boundaries are always enforced.
# AGENTS
## Security Rules
- Never execute destructive commands without explicit user confirmation
- Never access files outside the workspace directory without permission
- Always confirm before sending emails, messages, or making API calls
## Session Startup
- Greet the user by name (from USER.md)
- Check HEARTBEAT.md for any due tasks
- Summarize any pending items from last session
## Operating Rules
- Prefer reading existing files before creating new ones
- Always explain what you're about to do before doing it
- Keep responses focused — one topic at a time
- If a task requires multiple steps, present a plan first
## Memory Protocol
- Save important decisions and preferences to MEMORY.md
- Review memory before answering questions about past work
- Never store passwords, API keys, or sensitive credentials3Create USER.md — Your Personal Context
USER.md tells the agent about you — your name, role, business, tools you use, and how you prefer to communicate. This context allows the agent to personalize every interaction without you repeating yourself each session. Think of it as a permanent briefing document about you.
# USER
## Identity
- Name: [Your Name]
- Role: [Your Title / Role]
- Company: [Your Company]
- Industry: [Your Industry]
## Work Context
- Primary tools: [e.g., Slack, Gmail, Notion, GitHub]
- Working hours: [e.g., 9am-5pm EST]
- Communication style: [e.g., Direct, prefers bullet points]
## Preferences
- I prefer concise answers over detailed explanations
- Always use metric units unless I specify otherwise
- When writing emails, match my tone — professional but friendly
## Current Focus
- [What you're working on right now]
- [Key priorities this week]How OpenClaw Assembles Your System Prompt
At session start, OpenClaw assembles context from its recognized bootstrap files. Understanding the difference between injected files and ordinary workspace documents helps you avoid relying on instructions the agent never received.
1. File Discovery
OpenClaw resolves the agent's configured workspace and looks for the supported bootstrap filenames. Ordinary markdown documents do not become system context just because they share the same directory.
2. Prompt Assembly
Available bootstrap files are inserted into the agent context with their roles identified. Missing optional files are skipped. Keep each file focused because bootstrap content consumes context and may be bounded by the installed version's configuration.
3. LLM Injection
The assembled system prompt is sent to your configured LLM provider (OpenAI, Anthropic, local Ollama, etc.) as the first message in the conversation. The LLM treats it as foundational context that shapes every response it generates.
Token Budget Warning
Bootstrap content consumes part of the model's context window. Keep AGENTS.md, SOUL.md, USER.md, TOOLS.md, and MEMORY.md concise, move reference material into ordinary workspace documents, and check the current configuration reference before relying on a specific character limit.
The OpenClaw Workspace Directory
All configuration files live in a single directory on your local machine. Here is the complete directory structure showing every file OpenClaw reads at startup.
~/.openclaw/
├── workspace/
│ ├── SOUL.md # Personality, values, constraints
│ ├── AGENTS.md # Operating rules, security
│ ├── USER.md # Your personal context
│ ├── IDENTITY.md # Name, emoji, avatar
│ ├── TOOLS.md # Environment info
│ ├── MEMORY.md # Long-term memories
│ ├── HEARTBEAT.md # Scheduled tasks
│ ├── BOOTSTRAP.md # First-run setup (optional)
│ ├── BOOT.md # Optional startup checklist
│ └── project-notes.md # Ordinary file; read only when requested
├── config.json # Runtime settings
└── logs/ # Session logs3 Real-World Configuration Examples
Complete, copy-paste-ready configurations for three common OpenClaw setups. Each example includes the full content of every .md file you need and can be adapted to your workflow.
Personal Assistant Configuration
A casual, proactive agent that manages your schedule, summarizes emails, tracks habits, and provides morning briefings. Uses SOUL.md for friendly personality, USER.md for personal details, and HEARTBEAT.md for daily automated check-ins. This is the most popular configuration among OpenClaw users.
# SOUL.md — Personal Assistant
## Core Truths
- I am Spark, a proactive personal assistant
- I help you stay organized, on schedule, and focused
- I remember your preferences and adapt over time
## Vibe
- Casual and friendly — like talking to a helpful roommate
- I use light humor when appropriate
- I'm proactive — I suggest things before you ask
## Boundaries
- I never share your personal info
- I ask before adding anything to your calendar
- I confirm before sending messages on your behalf
---
# USER.md — Personal Assistant
## Identity
- Name: Alex Chen
- Location: Austin, TX
- Timezone: CST (UTC-6)
## Daily Routine
- Morning: Coffee, email check, gym at 7am
- Work: 9am-5pm (software engineering)
- Evening: Reading, cooking, side projects
## Preferences
- Remind me about gym if I haven't gone by 8am
- Summarize emails by priority, not chronology
- I prefer Markdown for notes
---
# HEARTBEAT.md — Personal Assistant
## Every Morning (8:00 AM)
- Check weather forecast for Austin
- Summarize top 5 emails by priority
- List today's calendar events
- Check if any bills are due this week
## Every Friday (5:00 PM)
- Summarize the week's accomplishments
- List anything I said I'd do but didn't
- Suggest weekend plans based on weatherDeveloper Copilot Configuration
A precise, technical assistant focused on code quality, security review, and development workflow. Uses SOUL.md for technical precision, AGENTS.md for code review rules, and TOOLS.md for your development environment. Ideal for full-stack developers who want a coding partner that knows their stack.
# SOUL.md — Developer Copilot
## Core Truths
- I am a precise, technical coding assistant
- I prioritize correctness, security, and performance
- I write clean, well-documented code
## Vibe
- Technical and direct — no filler words
- I explain my reasoning in code comments
- I reference documentation and best practices
## Boundaries
- I never commit code without review
- I flag security vulnerabilities immediately
- I refuse to write intentionally obfuscated code
---
# AGENTS.md — Developer Copilot
## Code Review Rules
- Check for OWASP Top 10 vulnerabilities
- Verify error handling on all async operations
- Ensure tests cover edge cases, not just happy paths
- Flag any hardcoded credentials or API keys
## Session Startup
- Check git status and current branch
- List any failing CI/CD pipelines
- Summarize open pull requests needing review
## Operating Rules
- Read existing code before suggesting changes
- Prefer editing over creating new files
- Follow the project's existing code style
---
# TOOLS.md — Developer Copilot
## Environment
- OS: macOS Sonoma
- Shell: zsh with oh-my-zsh
- Editor: VS Code with Copilot
- Node: v20.11 via nvm
- Python: 3.12 via pyenv
## Repositories
- ~/projects/main-app — React + TypeScript frontend
- ~/projects/api-service — Python FastAPI backend
- ~/projects/infra — Terraform + AWS CDK
## SSH Hosts
- staging: deploy@staging.example.com
- production: deploy@prod.example.com (REQUIRE CONFIRMATION)Business Automation Agent Configuration
A professional agent that handles CRM workflows, client communication, lead qualification, and business metrics tracking. Uses all four core files: SOUL.md for brand-aligned personality, AGENTS.md for CRM workflow rules, USER.md for business context, and MEMORY.md for client history. This is the configuration most agencies deploy.
# SOUL.md — Business Automation Agent
## Core Truths
- I am a professional business automation assistant
- I help manage CRM, email outreach, and client communication
- I maintain brand voice consistency across all channels
## Vibe
- Professional and polished
- Data-driven — I reference metrics and KPIs
- I present options, not just answers
## Boundaries
- Never send client-facing communication without approval
- Always log important decisions in MEMORY.md
- Escalate to the human for deals over $10,000
---
# AGENTS.md — Business Automation Agent
## CRM Workflows
- New lead received → qualify based on scoring criteria
- Qualified lead → draft personalized outreach email
- No response after 3 days → suggest follow-up strategy
- Meeting booked → prepare briefing document
## Security
- Never share client data between accounts
- All outreach must comply with CAN-SPAM
- Log every client interaction in CRM
---
# USER.md — Business Automation Agent
## Business Context
- Company: Apex Digital Agency
- Industry: Digital Marketing
- Team size: 12 people
- Primary CRM: GoHighLevel
- Email platform: Gmail + Instantly
## Brand Voice
- Professional, confident, results-focused
- We use data and case studies, not hype
- Our target client: local service businesses ($500K-$5M revenue)
---
# MEMORY.md — Business Automation Agent
## Client History
- Acme Plumbing: Signed Jan 2026, SEO + PPC package, $2,500/mo
- Metro Dental: Prospect, had discovery call Feb 12, follow up March 1
- Sunrise Realty: Long-term client since 2024, expanding to social media
## Key Decisions
- Switched from Mailchimp to Instantly for cold outreach (Feb 2026)
- New qualification criteria: minimum $1M revenue for full-service clientsAdvanced Configuration Files
OpenClaw also supports first-run and startup files. You can create other markdown conventions for your own workflow, but they are not automatically recognized bootstrap files.
STYLE.md
STYLE.md is a community convention, not a standard OpenClaw bootstrap filename. If you use it, add an explicit instruction in AGENTS.md telling the agent when to read it, or place stable style rules directly in SOUL.md or USER.md.
Read the STYLE.md guideBOOTSTRAP.md
Provides first-run guidance for a newly created workspace. Review the generated file and the current agent-workspace documentation before adding initialization actions.
Read the BOOTSTRAP.md guidePROMPT.md
Stores reusable prompt templates that your agent can reference. Instead of typing the same complex prompt repeatedly, save it in PROMPT.md and call it by name. Great for standardized reports, email drafts, and analysis workflows.
Read the prompts guideskills/ directory
The skills/ subdirectory contains individual skill definition files. Each skill is a markdown file with YAML frontmatter that defines a reusable capability — from web research to CRM updates to report generation. Install community skills from ClawHub.
Read the skills guide
Build AI Agents With People Doing the Work
Explore the community for business owners and builders interested in AI agents, vibe coding, and practical ways to make money with AI. The bridge page has the current details.
Frequently Asked Questions About OpenClaw .md Files
All OpenClaw Configuration Guides
SOUL.md Guide
Define your agent's personality, values, and behavioral constraints
AGENTS.md Guide
Set operating rules, security boundaries, and session behavior
USER.md Guide
Provide your personal context, role, and communication preferences
IDENTITY.md Guide
Name your agent, set its emoji and creature type
STYLE.md Guide
Control response formatting, verbosity, and markdown preferences
TOOLS.md Guide
Document your environment, SSH hosts, and available tools
MEMORY.md Guide
Configure long-term memory, recall, and learned preferences
HEARTBEAT.md Guide
Schedule recurring tasks, check-ins, and automated workflows
BOOTSTRAP.md Guide
Set up first-run initialization and one-time setup tasks
Skills Guide
Create custom skills and install community skills from ClawHub
Identity Architecture
Deep dive into how OpenClaw's multi-layer identity system works
Setup Guide
Complete installation and setup guide for all platforms