What This File Controls
USER.md tells your agent who it is serving. Without this file, the agent treats every user like a stranger every session — no context about role, goals, communication preferences, or access level. The result is generic, one-size-fits-all responses that waste time with unnecessary explanations or, worse, provide information at the wrong level of detail.
USER.md is one of only three files (alongside SOUL.md and MEMORY.md) supported by both the OpenClaw and Hermes runtimes. The runtime loads it during the boot sequence and injects the contents into the user context section of the system prompt, allowing the agent to personalise every interaction from the first message.
The five fields cover the user’s identity (userName, userRole), objectives (userGoals), communication preferences (userPrefs), and permission level (userAccess). For team deployments, USER.md can be configured per individual user or as a shared team profile — but mixing per-user and team-wide configuration in a single file creates confusion. For organisations with more than 5 distinct user profiles, consider using dynamic user context with RBAC template variables.
Why it matters: Without USER.md, your agent treats you like a stranger every session.
Field-by-Field Breakdown
5 fields that shape your agent
userNameRequiredThe name of the primary user or team.
userRoleRequiredThe user's role within the organisation.
userGoalsRequiredWhat the user is trying to achieve with this agent.
userPrefsOptionalCommunication style and format preferences.
userAccessRequiredWhat data and actions the user can access through the agent.
Real-World Examples
## userName
Sarah Whitfield
## userRole
Senior Partner, Whitfield & Associates. 15 years in UK tax practice. Manages 4 associates and oversees all client engagements.
## userGoals
- Reduce time spent on routine HMRC guidance lookups by 60%
- Ensure associates have a reliable first-line research resource
- Never miss a filing deadline for any client
## userPrefs
- British English, formal tone
- Show the source (statute or HMRC guidance reference) for every answer
- Lead with the practical recommendation, then provide the legal basis
- Keep responses under 300 words unless asked for detail
## userAccess
Medium — act on routine research queries; ask before taking any action that affects client files or sends communications.Common Mistakes
Treating userGoals as static
Goals evolve as business priorities shift. Stale goals lead to misaligned recommendations — the agent optimises for last quarter’s priorities. Review userGoals monthly or after any strategic change.
Over-granting userAccess
Setting access to ‘High’ when ‘Medium’ is appropriate violates the principle of least privilege. The agent takes autonomous actions that should require human confirmation, creating risk.
Leaving userPrefs vague
‘Be concise’ means different things to different people. Specify measurable preferences: word count limits, formatting requirements, language register, and platform-specific conventions.
Using a single USER.md for multiple users
When one file serves an entire team, the agent cannot personalise responses. Each user gets generic output. For teams of 3+, use separate user profiles or dynamic RBAC template variables.
How SetupClaw Handles This
USER.md is configured per named user during the onboarding process. Our specialist interviews each primary user to capture their actual working preferences — not aspirational ones — and translates them into actionable configuration.
Configuration for up to 3 named users with goals, preferences, and access levels
All above + 30-day preferences review based on real interaction patterns
All above + dynamic RBAC templates for large teams + quarterly user context refresh
- All 5 fields configured per user
- Access levels matched to organisational role
- Preferences validated against actual communication patterns
- Cross-referenced with SOUL.md vibe for consistency
- Documented access justification for audit trail
Configured during onboarding (day 1–2). Preferences review at day 30 (Standard+).
Advanced Topics
Dynamic user context with RBAC template variables
For deployments serving more than 5 distinct users, static USER.md files become unmanageable. Use RBAC template variables that resolve at runtime based on the authenticated user’s identity. The OpenClaw runtime substitutes variables like {{user.role}} and {{user.access}} from your identity provider, allowing a single USER.md template to serve the entire organisation.
## userName
{{user.displayName}}
## userRole
{{user.jobTitle}}, {{user.department}}
## userAccess
{{#if user.isAdmin}}High{{else if user.isManager}}Medium{{else}}Low{{/if}}Example Configurations
Persona A — MeridianChief of Staff
# USER.md -- User Profile
## userName
Alex
## userRole
CEO/Founder, Series B, 80 people
## userGoals
- Force multiplier: reduce context-switching overhead
- Clear the critical path for high-leverage decisions
- Surface risks before they become crises
## userPrefs
- Bottom-line-up-front (BLUF) format
- Tables and bullet hierarchies preferred
- No filler language or unnecessary caveats
## userAccess
Medium — act on routine, ask for criticalPersona B — Axiom (Veteran Growth Hacker)
# USER.md -- User Profile
## userName
Jordan
## userRole
Head of Growth, B2B SaaS, £1.6M ARR
## userGoals
- Reach £8M in 18 months
- Ruthless prioritisation of growth levers
- Build a self-improving experimentation engine
## userPrefs
- ICE framework for all recommendations
- Data tables with period-over-period comparisons
- Skip context — assume domain fluency
## userAccess
High — act autonomously, notify afterPersona C — Lumen (Scientific Researcher)
# USER.md -- User Profile
## userName
Dr. Priya
## userRole
Principal Investigator, biotech
## userGoals
- Research assistant at PhD-student standards
- Never miss a relevant publication
- Structured evidence synthesis for grant applications
## userPrefs
- Academic register with appropriate hedging
- Always include confidence levels and effect sizes
- Structured report format by default
## userAccess
Low — always ask before actingPersona D — Narrative (Senior Content Creator)
# USER.md -- User Profile
## userName
Casey
## userRole
Director of Content, B2B fintech
## userGoals
- Scale from 4 to 12 pieces/month without quality loss
- Build an evergreen content library
- Improve organic traffic by 3x in 6 months
## userPrefs
- Editorial brief format for all recommendations
- Platform-specific formatting (LinkedIn, blog, email)
- Always connect recommendations to business outcomes
## userAccess
High — act autonomously, notify afterPersona E — Architect (Chief Engineer)
# USER.md -- User Profile
## userName
Sam
## userRole
CTO, 25-person engineering team
## userGoals
- Principal-level adviser catching architectural mistakes
- Reduce unplanned tech debt accumulation
- Ensure no security vulnerabilities ship to production
## userPrefs
- Diagrams and pseudocode preferred
- ADR format for significant decisions
- Challenge weak assumptions directly
## userAccess
Medium — act on routine, ask for critical