此文件控制什么
USER.md 告诉你的智能体它在为谁服务。没有这个文件，智能体每次会话都会把每个用户当作陌生人——不了解角色、目标、沟通偏好或权限级别。结果就是通用的、千篇一律的回复，浪费时间在不必要的解释上，或者更糟糕的是，以错误的详细程度提供信息。
USER.md 是 OpenClaw 和 Hermes 运行时都支持的仅有的三个文件之一（另外两个是 SOUL.md 和 MEMORY.md）。运行时在启动序列中加载它，并将内容注入系统提示词的用户上下文部分，使智能体从第一条消息起就能个性化每次交互。
五个字段涵盖了用户的身份（userName、userRole）、目标（userGoals）、沟通偏好（userPrefs）和权限级别（userAccess）。对于团队部署，USER.md 可以按个人用户配置，也可以作为共享的团队配置文件——但在单个文件中混合个人用户和团队范围的配置会造成混乱。对于拥有超过 5 个不同用户档案的组织，建议使用带 RBAC 模板变量的动态用户上下文。
为什么重要： Without USER.md, your agent treats you like a stranger every session.
逐字段详解
定义智能体行为的 5 个字段
userName必填The name of the primary user or team.
userRole必填The user's role within the organisation.
userGoals必填What the user is trying to achieve with this agent.
userPrefs可选Communication style and format preferences.
userAccess必填What data and actions the user can access through the agent.
实际配置示例
## 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.常见错误
将 userGoals 视为静态不变的
目标会随着业务优先级的变化而演变。过期的目标会导致建议偏差——智能体在为上个季度的优先级做优化。每月或在任何战略变化后审查 userGoals。
过度授予 userAccess 权限
当'中等'权限就够用时却设为'高'，违反了最小权限原则。智能体会执行本应需要人类确认的自主操作，从而产生风险。
userPrefs 过于模糊
'简洁一点'对不同的人意味着不同的事情。指定可量化的偏好：字数限制、格式要求、语言风格和特定于平台的惯例。
多个用户共用一个 USER.md
当一个文件服务于整个团队时，智能体无法个性化回复。每个用户都得到通用输出。对于 3 人以上的团队，使用单独的用户配置文件或动态 RBAC 模板变量。
SetupClaw 如何处理
USER.md 在入职流程中按命名用户进行配置。我们的专家会访谈每位主要用户，捕捉他们实际的工作偏好——不是理想中的偏好——并将其转化为可操作的配置。
为最多 3 位命名用户配置目标、偏好和权限级别
以上全部 + 基于真实交互模式的 30 天偏好审查
以上全部 + 大型团队的动态 RBAC 模板 + 季度用户上下文刷新
- 每位用户的全部 5 个字段已配置
- 权限级别与组织角色匹配
- 偏好已对照实际沟通模式验证
- 与 SOUL.md vibe 交叉引用以确保一致性
- 已记录权限设置理由以供审计
入职期间配置（第 1-2 天）。第 30 天进行偏好审查（Standard+）。
进阶主题
使用 RBAC 模板变量的动态用户上下文
对于服务超过 5 位不同用户的部署，静态 USER.md 文件变得难以管理。使用 RBAC 模板变量，在运行时根据已认证用户的身份进行解析。OpenClaw 运行时从你的身份提供商替换 {{user.role}} 和 {{user.access}} 等变量，使单个 USER.md 模板能够服务整个组织。
## userName
{{user.displayName}}
## userRole
{{user.jobTitle}}, {{user.department}}
## userAccess
{{#if user.isAdmin}}High{{else if user.isManager}}Medium{{else}}Low{{/if}}配置示例
Persona A — Meridian首席参谋
# 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 (增长黑客)
# 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 (科研人员)
# 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 (内容创作者)
# 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 (首席工程师)
# 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