OpenClaw USER.md Guide — Teach Your Agent Who You Are

USER.md is one of the most underrated files in your OpenClaw workspace. Where SOUL.md defines your agent's personality and MEMORY.md stores what happened, USER.md defines who your agent is working for. A well-written USER.md means your agent never needs to ask basic questions about you — it already knows.

What USER.md Is

USER.md is a plain text Markdown file in your workspace root that your agent reads at the start of every session. It describes you: your preferences, role, goals, communication style, and anything else your agent should know to work effectively on your behalf.

Think of it as the onboarding document you'd give a new executive assistant on their first day — except this one never forgets it.

Where It Lives

~/.openclaw/workspace/USER.md

Basic USER.md Structure

# USER.md - About You

## Who You Are
- Name: [Your name]
- Role: [Your job title and company]
- Timezone: [e.g., EST, PST, IST]
- Preferred name: [What to call you]

## Work Context
- Currently working on: [main projects or focus areas]
- Tools I use: [Slack, Jira, GitHub, etc.]

## Communication Preferences
- I prefer: [concise responses / detailed explanations / bullet points]
- Don't ask me about: [things your agent should not prompt you for]
- Always check with me before: [sensitive actions]

## Goals
- Short-term: [what you're trying to accomplish this quarter]
- Long-term: [your bigger goals]

What Makes a Good USER.md

Be specific, not vague. Instead of "I'm a developer", write "I'm a backend engineer at a fintech startup, primarily working in Go and Postgres. Our main product is a payment orchestration API with 200+ enterprise clients."

Include your constraints. What are the boundaries your agent should respect? What should it never do without checking? Put them here.

Document your quirks. Do you hate bullet points? Prefer direct recommendations without caveats? Want your agent to challenge your assumptions? Say so.

Advanced: Role-Specific USER.md Additions

For product managers:

## PM Context
- Current roadmap focus: [Q2 priorities]
- Key stakeholders: [names and their priorities]
- My north star metric: [e.g., user activation rate]
- Decision-making style: I prefer data over intuition — always show me numbers.

For developers:

## Dev Context
- Primary stack: [languages, frameworks, tools]
- Current projects: [repo names and what they do]
- Code review preferences: [be blunt about issues]
- Never auto-commit — always show me diffs first.

Keeping USER.md Fresh

Your USER.md should evolve as your situation changes. When you change jobs, shift focus, or develop new preferences — update the file. Your agent adapts immediately in the next session.

A stale USER.md is worse than no USER.md — it gives your agent confidently wrong context. Review it quarterly at minimum.

What USER.md Is Not

USER.md is not where you put your credentials, API keys, or private information you wouldn't want in a prompt. Keep sensitive data in separate files or use environment variables.

Ready to go deeper? The OpenClaw Playbook covers this in detail — grab your copy for $9.99.