The OpenClaw USER.md File: A Complete Guide With Real Examples

Why USER.md Matters More Than You Think

If you have set up OpenClaw and started chatting with your agent, you have probably noticed something: every session starts cold. The agent does not know your name, your business, your priorities, or how you prefer to be talked to. You end up re-explaining the same context over and over.

That is what USER.md solves. It is a markdown file that lives in your OpenClaw workspace and gets loaded automatically at the start of every session. The agent reads it. It now knows who you are. The cold-start problem is gone.

USER.md is one of eight workspace files OpenClaw auto-loads on every session. Of those eight, USER.md is arguably the most important — because it is the only one that defines you. Everything else (SOUL.md, AGENTS.md, TOOLS.md, etc.) describes the agent. USER.md describes the human the agent works for.

This article walks through what USER.md is, what it should contain, what to leave out, and shows a real production USER.md being used to manage five businesses simultaneously.

The Eight Workspace Files

Before we dig into USER.md specifically, here is the cast of characters. OpenClaw auto-loads exactly these files from your workspace folder at the start of every session:

USER.md — Information about you (the human). Preferences, context, background.
SOUL.md — The agent's personality, tone, and persona.
IDENTITY.md — Who the agent is and how it presents itself.
AGENTS.md — Operating instructions, standing orders, authority boundaries.
TOOLS.md — When and how the agent should use its tools.
MEMORY.md — Long-term durable memory (decisions, preferences, facts).
HEARTBEAT.md — Checklist for proactive scheduled runs.
BOOT.md — Instructions to run on gateway startup.

USER.md sits in this stack as the answer to "who am I working for?" Without it, the agent has no context. With it, every session starts already knowing your timezone, your businesses, your communication preferences, and what good work looks like.

What USER.md Should Contain

USER.md is freeform markdown. There is no required schema. But based on real-world use across hundreds of OpenClaw deployments, the most effective USER.md files share a common structure.

1. Identity

The basics. Your name, what to call you (formal vs. nickname), pronouns, and timezone. This is the bare minimum that prevents the agent from greeting you as "User" or assuming Pacific Time when you are on the East Coast.

## Identity
- Name: Alex Smith
- Call me: Alex
- Pronouns: He/him
- Timezone: East Coast USA (ET)

Why timezone matters: any agent that schedules things, references "today," or talks about deadlines needs to know what time zone "today" means. Without this, you will get notifications at 3 AM and meeting suggestions for 9 PM.

2. Communication Style

This is where USER.md earns its keep. Tell the agent how you want to be talked to. Direct or detailed? Concise or thorough? Formal or casual? Should it skip pleasantries? Should it push back on bad ideas?

## Communication Style
- Be direct and concise. I do not need preamble.
- Skip the pleasantries. Get to the point.
- When you have an opinion, say it. Do not just list options neutrally.
- Prefer doing over asking. If you can act and report back, do that.
- If you are genuinely unsure, ask once — do not ask five clarifying questions.

The difference between an agent that has read your communication preferences and one that has not is enormous. Without it, the AI defaults to being verbose, hedging, and over-cautious. With it, you get an agent that matches your working style.

3. Working Relationship

This is meta. It tells the agent how to relate to you. Is it a tool you use, or a thinking partner? Are you giving it strict instructions or expecting it to use judgment? Where are the boundaries of its authority?

## How We Work Together
This is a business partnership, not a tool relationship. I treat you as
a thinking partner — someone who understands the businesses, has context,
uses judgment, and takes initiative within agreed boundaries. You are
expected to think ahead, flag problems before they become problems, and
suggest things I have not thought to ask yet.

This single paragraph reshapes how the agent approaches every task. An agent that is "a tool" waits for instructions. An agent that is "a thinking partner" volunteers ideas, raises concerns, and notices things you missed.

4. Context About Your Work

The agent needs to know what you actually do. If you have one job, describe it. If you run multiple businesses, describe each one. Include enough detail that the agent can talk about them intelligently without needing to look things up.

## The Businesses

### EventCo.com
Speed dating company based in New York City. Running since 2007 — this is
the flagship, established business. Runs live in-person events in NYC.
I know this business inside out; the agent's job here is execution and
growth support, not education.

### LaunchProduct.com
BYOK (Bring Your Own Keys) SMS and email platform — users connect their own
Twilio and AWS SES accounts. Currently in development.
Official launch: May 1st.

Notice the meta-context: "I know this business inside out; the agent's job here is execution and growth support, not education." That tells the agent how to engage. For the established business, do not waste time explaining what speed dating is. For the new launch, focus on planning and execution.

5. Current Priorities

What matters right now, in rough order. This is the difference between an agent that tries to help with everything equally and one that knows what to prioritize when forced to choose.

## Current Priorities (in rough order)
1. LaunchProduct launch prep (May 1st deadline)
2. EventCo — ongoing operations, growth, social media
3. MediaSite — distribution automation
4. RegionalPlatform — lead generation
5. PublishingOp — daily idea reports, new book concepts

Update this every few weeks. Priorities change. An out-of-date priority list is worse than no priority list — the agent will optimize for things you stopped caring about three months ago.

6. What You Help With (Active vs. Building)

Distinguish ongoing work from things you are still figuring out. The agent treats them differently — ongoing work is execution mode, building work is planning mode.

## What You Help With

### Active / Ongoing
- Email responses across all businesses
- Social media content creation and scheduling
- Daily idea reports for PublishingOp
- Posting MediaSite stories to X, Truth Social, and other platforms

### Building Toward
- LaunchProduct affiliate program — finding YouTube creators, researching
  contact info, outreach for 20 percent commission partnership
- Marketplace lead gen — finding contacts in target market

7. Compliance and Constraints

If your work touches anything with legal implications — privacy law, financial regulation, platform terms of service, healthcare, etc. — call it out. Tell the agent you are aware of these issues and how you want them flagged.

## Compliance Awareness
Some planned activities (contact acquisition, automated outreach, scraping)
have legal and platform TOS considerations — CAN-SPAM, GDPR, platform
rules. I am aware of this. Flag concerns once when relevant, then help
plan compliant execution. Do not repeat the warning every time.

The "do not repeat the warning every time" line is critical. Without it, every email-related task will get a CAN-SPAM lecture, every scraping task will get a TOS warning, and every outreach task will get a GDPR reminder. With it, the agent flags the concern once and then helps you do the work properly.

8. What Good Looks Like

End with a section that defines success. This is your performance review for the agent, written in advance. It tells the agent what behaviors you want it to optimize for.

## What Good Looks Like
- You remember context across conversations and businesses
- You proactively surface things I should know or act on
- You treat deadlines as real constraints
- You bring ideas, not just responses
- You know when to act and when to check first

This single section, more than any other, determines whether the agent feels useful or annoying.

What to Leave Out

USER.md is loaded into context on every single session. It costs tokens. It takes space. So be deliberate about what you put in it — and what you leave out.

Things That Belong Elsewhere

Long lists of past tasks — these go in memory/YYYY-MM-DD.md daily files, not USER.md
Decisions and durable facts — these belong in MEMORY.md, which is for long-term memory
Tool-specific instructions — these go in TOOLS.md or in specific SKILL.md files
Agent personality — that is SOUL.md's job
Standing orders and authority limits — those go in AGENTS.md
API keys, credentials, secrets — never. These go in environment variables, not markdown files

Things That Are Tempting But Useless

Your life story — the agent does not need your biography. It needs working context.
Hopes and dreams — vague aspirations do not help the agent make decisions today.
Long lists of "do not do this" — keep negatives short and important. Long forbidden-action lists waste tokens.
Detailed technical specs of your projects — those belong in CLAUDE.md or project READMEs, not USER.md.

How to Update USER.md (And When)

USER.md is not a one-time file. It is a living document. Update it when:

Your priorities change (every few weeks at minimum)
You finish a major project and start a new one
You notice the agent doing something annoying or missing context — fix it in USER.md so you do not have to correct it again
You add a new business or channel
You change how you want to be communicated with

The easiest way to update USER.md is to ask the agent to do it for you. Tell it what you want changed, ask it to update USER.md, then verify the change. This is one of the rare cases where it is fine to let the agent edit its own context files — but always read the diff before saving.

A Real Production Example

Below is a real USER.md being used to manage five separate businesses through OpenClaw. It demonstrates every principle in this article. Note how short it is — under 600 words — and how every section earns its place.

# USER.md — About Your Human

## Identity
- Name: Alex Smith
- Call me: Alex
- Pronouns: He/him
- Timezone: East Coast USA (ET)

## How We Work Together
This is a business partnership, not a tool relationship. Alex treats
you as a thinking partner — someone who understands the businesses,
has context, uses judgment, and takes initiative within agreed
boundaries. You are expected to think ahead, flag problems before
they become problems, and suggest things Alex has not thought to
ask yet.

## Communication Style
- Be direct and concise. Alex does not need preamble.
- Skip the pleasantries. Get to the point.
- When you have an opinion, say it. Do not just list options neutrally.
- If something has a compliance or legal consideration, flag it clearly
  but do not be preachy about it — Alex is aware.
- Prefer doing over asking. If you can act and report back, do that.
  If you are genuinely unsure, ask once — do not ask five clarifying
  questions.
- Alex works across multiple businesses simultaneously. Context-switch
  cleanly and keep track of which business a conversation is about.

## The Businesses

### EventCo.com
Speed dating company based in New York City. Running since 2007 — this
is the flagship, established business. Runs live in-person events in
NYC. Alex knows this business inside out; the agent's job here is
execution and growth support, not education.

### LaunchProduct.com
BYOK (Bring Your Own Keys) SMS and email platform — users connect
their own Twilio and AWS SES accounts. Currently in development.
Official launch: May 1st. This is active build mode — needs planning,
marketing prep, affiliate outreach, and launch execution support.

### RegionalPlatform.com
Job board serving Latin America. Operates in Spanish and Portuguese.
Focus: connecting employers with workers across the region. Lead
generation and BD outreach to HR contacts in Latin America is a
current priority.

### PublishingOp Publishers
KDP publishing operation. Focuses on coloring books, public domain
classics, and annotated editions. Content strategy centers on curated
thematic collections sourced from Project Gutenberg.

### MediaSite.com
AI-powered news site with source attribution. Distribution is a
current focus — posting stories to X, Truth Social, and other
platforms.

## Current Priorities (in rough order)
1. LaunchProduct launch prep (May 1st deadline)
2. EventCo — ongoing operations, growth, social media
3. MediaSite — distribution automation
4. RegionalPlatform — lead generation
5. PublishingOp — daily idea reports, new book concepts

## Compliance Awareness
Some planned activities have legal and platform TOS considerations
— CAN-SPAM, GDPR, platform rules. Alex is aware of this. Flag
concerns once when relevant, then help plan compliant execution.
Do not repeat the warning every time.

## What Good Looks Like
- You remember context across conversations and businesses
- You proactively surface things Alex should know or act on
- You treat deadlines (like May 1st) as real constraints
- You bring ideas, not just responses
- You know when to act and when to check first

That is it. Less than one page. Loaded automatically into every session. The agent that reads this file knows who Alex is, what he is working on, how he wants to be talked to, what he is prioritizing, and what success looks like. It can context-switch between five businesses without missing a beat. It does not need to ask "which business?" every time — it can usually figure it out from the conversation and confirm only when ambiguous.

Common Mistakes

Mistake 1: Leaving It Empty

The single biggest mistake is not writing one at all. Every OpenClaw install creates an empty USER.md by default. Most people leave it that way. Do not be most people. Five minutes of writing saves hours of repetition.

Mistake 2: Making It Too Long

USER.md is loaded into context on every session. Every session. Every token. If your USER.md is 5,000 words, you are paying for those tokens on every conversation. Aim for under 1,000 words. Be ruthless. If a section is not earning its place, move it elsewhere or delete it.

Mistake 3: Confusing USER.md with MEMORY.md

USER.md is for stable facts about you. MEMORY.md is for accumulating facts the agent has learned over time. If you are tempted to add "decision made on March 15: switched email provider to AWS SES" to USER.md, that belongs in MEMORY.md instead. USER.md should be relatively static — it changes when your situation changes, not every day.

Mistake 4: Putting Personality There

USER.md is about you. SOUL.md is about the agent. If you want the agent to be sarcastic, witty, or formal — that is SOUL.md territory. If you want the agent to use terse responses with you specifically — that is USER.md communication style. Easy to mix these up.

Mistake 5: Not Updating It

An out-of-date USER.md is worse than a missing one. An out-of-date priority list will have the agent optimizing for last quarter's goals. An out-of-date business list will have it referencing companies you sold. Treat USER.md like any other living document — review it monthly.

Mistake 6: Dumping API Keys In It

Never. USER.md is markdown. It might get committed to git. It might get backed up. It might get shared. API keys, passwords, and tokens go in environment variables (loaded via systemd overrides for OpenClaw services), not in markdown files. Same goes for personal information you do not want leaking — your home address, phone number, etc. Put them in USER.md only if you genuinely need the agent to know them, and understand the risk.

How USER.md Interacts With Other Files

USER.md does not exist in isolation. It is part of a system. Here is how the eight workspace files work together when an agent session starts:

BOOT.md runs first — gateway startup instructions
SOUL.md, IDENTITY.md, AGENTS.md, TOOLS.md, USER.md, MEMORY.md get assembled into the system prompt
HEARTBEAT.md runs on scheduled intervals (if heartbeat is enabled)
The session begins with all of the above already in context

The total token cost of these files is your "always-on context budget." It is what the agent knows before you say anything. Every token spent here is a token not available for the conversation. So be efficient — only put things in workspace files that need to be loaded every time.

Things that do not belong in any of the eight files:

Project-specific code conventions — those go in CLAUDE.md files in each project directory
One-time research — that goes in memory/YYYY-MM-DD.md or in MEMORY.md if it is a durable finding
Detailed how-to guides for specific tools — those go in skills/<skill-name>/SKILL.md

Putting It Into Practice

If you are setting up OpenClaw for the first time, here is the order:

Open the auto-generated USER.md in your workspace folder
Use the structure in this article (Identity, Communication Style, How We Work Together, Context, Priorities, Compliance, What Good Looks Like)
Fill in each section honestly. Do not write what you think the agent wants to read — write what you actually want it to know.
Save it. Restart your gateway service so the new context loads.
Open a fresh session and ask: "Tell me what you know about me." The agent should give you a clean summary of your USER.md content. If it does not, your file did not load — check the path and restart.
Iterate. Every time the agent does something annoying or misses context, ask yourself: should this be in USER.md? Often the answer is yes.

Final Thoughts

USER.md is the smallest, simplest, highest-leverage file in your OpenClaw workspace. It takes 30 minutes to write the first version. It takes 5 minutes a month to keep it current. And it transforms the agent from a stateless chatbot that re-asks the same questions every session into a real working partner that knows who you are and what you are doing.

If you take only one thing away from this article, take this: do not leave your USER.md empty. Even a 200-word version is better than nothing. Even the basic identity section pays for itself the first time the agent correctly references your timezone or addresses you by your preferred name.

Your AI agent should know who you are. USER.md is how you tell it.