共计 5786 个字符，预计需要花费 15 分钟才能阅读完成。
在之前的两篇文章里，我分别介绍了 OpenClaw 的部署和基本使用，以及 Workspace 中各个核心文件的作用。这篇文章我们把焦点缩小到一个被低估但极其重要的文件：USER.md。我会分享我自己从零开始编写 USER.md 的过程，踩过的坑，以及最终摸索出来的一套写法。这个文件在 OpenClaw 中存在感不高，但是实际上决定了 AI 理解「你」的上限，如果不共享你自己的上下文信息，就有可能让 AI 的表现不满足你的要求。
USER.md 是什么
在 OpenClaw 的 Workspace 文件体系中，每个 Markdown 文件各司其职：SOUL.md 定义 AI 的性格，AGENTS.md 规定 AI 的工作方式，MEMORY.md 存储长期记忆。而 USER.md 的职责很单纯——告诉 AI "你在服务的这个人是谁"。它记录的是用户的基本信息、沟通偏好、工作习惯和个人上下文。每次会话开始时，无论是私聊还是群聊，OpenClaw 都会把 USER.md 的内容加载到上下文中，让 AI 从第一句话开始就知道自己在和谁打交道。
你可以把它类比成现实世界中的"客户档案"。想象你雇了一个私人助理，第一天上班你什么都不跟他说，他只能靠观察来猜你的习惯。但如果你给他一张卡片，上面写着"叫我 EV，东京时区，用中文沟通，技术话题可以深入，不喜欢废话"——他第一天就能进入状态。USER.md 就是这张卡片。
OpenClaw 官方提供的默认模板非常简洁，装完之后如果你跑了 bootstrap 流程，它会长这个样子：
# USER.md - About Your Human
Learn about the person you're helping. Update this as you go.
## Basics
- **Name:**
- **What to call them:**
- **Pronouns:** (optional)
- **Timezone:**
- **Notes:**
## Context
What do they care about? What projects are they working on?
What annoys them? What makes them laugh?
Build this over time.
---
The more you know, the better you can help.
But remember — you're learning about a person, not building a dossier.
Respect the difference.
模板末尾那句话值得品味："你是在了解一个人，不是在建立一份档案。尊重这两者的区别。"这不是随便写的鸡汤，它实际上暗示了 USER.md 的一个核心设计理念——记录足够 AI 理解你的信息，但不要变成一个隐私数据仓库。
为什么 USER.md 值得认真对待
很多人装好 OpenClaw 之后，把精力都花在 SOUL.md 上——给 AI 起名字、调性格、设定行为边界。SOUL.md 当然重要，但这里有一个容易忽略的问题：你花了大量时间定义"AI 应该怎么说话"，却没有告诉 AI "我是谁、我需要什么"。结果就是你有一个性格鲜明的 AI 助手，但它对你的了解约等于零。
我的体验是，一个写得好的 USER.md 对日常使用的提升是立竿见影的。举几个例子：在我把时区设成 Asia/Tokyo 之前，OpenClaw 的心跳功能在凌晨三点给我发消息汇报服务器状态，因为它默认按 UTC 时间运行；在我写明"技术文档用中文，代码注释用英文"之前，它回复的语言完全看心情，有时候中英混杂；在我注明"不需要每次回复都问’还有什么可以帮你的’"之前，每一轮对话都以这句废话结尾。这些问题不是模型的问题，也不是 SOUL.md 的问题，纯粹是因为 AI 不知道你想要什么。
从技术角度看，USER.md 在每次会话开始时都会被注入上下文，和 SOUL.md、AGENTS.md 一起构成 AI 的"启动记忆"。这意味着 USER.md 中的每一行内容都会影响 AI 在整个会话中的表现。如果你在里面写了"我更喜欢直接的沟通方式"，AI 在整个会话中都会倾向于给出简洁直接的回答；如果你写了"我正在做一个投资分析的项目"，AI 在回答相关问题时会自动带入这个背景。这种持续性的上下文效果是 MEMORY.md 做不到的——MEMORY.md 只在主会话中加载，而且存储的是历史信息而非用户画像。
USER.md 和 SOUL.md 的区别
这是一个很多人分不清的问题，包括我自己一开始也搞混了。简单来说：SOUL.md 定义的是"AI 是什么样的"，USER.md 定义的是"用户是什么样的"。听起来很好区分，但实际写的时候很容易混淆。比如"回复尽量简洁"这条，到底该写在 SOUL.md 还是 USER.md？
我的理解是这样的：如果这个要求是关于 AI 的行为风格，写在 SOUL.md 里。如果这个要求是关于你的个人偏好，写在 USER.md 里。"回复尽量简洁"其实是一个用户偏好——你希望 AI 说话简洁是因为你这个人不喜欢废话，而不是因为 AI 的性格应该简洁。所以它应该放在 USER.md。反过来，"说话带点幽默感"是一个性格设定，应该放在 SOUL.md。
清晰的分离有一个实际的好处：如果你运行多个代理（OpenClaw 支持在一个 Gateway 中运行多个不同性格的 AI），USER.md 在所有代理之间是共享的——因为用户是同一个人，但 SOUL.md 是每个代理独立的——因为它们有不同的性格。如果你把用户偏好塞进了 SOUL.md，换一个代理就要重新抄一遍。
社区有一篇文章总结得很好：很多人把所有东西都往 SOUL.md 里塞——性格、行为规则、工具权限、用户偏好，全都挤在一个文件里。结果就是一个臃肿的配置文件，不仅占用大量上下文窗口，还容易产生互相矛盾的指令。正确的做法是让每个文件各归其位：SOUL.md 负责身份，USER.md 负责用户画像，AGENTS.md 负责工作规范。
我的 USER.md 写法
经过两周的反复调整，我目前的 USER.md 大致包含以下几个部分。分享出来供大家参考，你可以根据自己的情况增删。
基础信息
这部分是最基本的，也是影响最直接的。时区设置尤其关键，它直接决定了 AI 在 HEARTBEAT 心跳任务中什么时候给你发消息、用什么时间格式，以及能不能正确判断"现在是不是你的工作时间"。
## 基本信息
- 名字：EV
- 称呼：直接叫 EV 就行
- 时区：Asia/Tokyo (JST, UTC+9)
- 主要语言：中文
- 其他语言：日语（学习中）、英语（技术文档阅读）
这里有一个小细节值得注意：openclaw.json 里也有一个 agents.defaults.userTimezone 的配置项。两者的区别是，配置文件中的时区控制的是系统层面的时间戳渲染，而 USER.md 中的时区是给 AI 的上下文参考。两个地方都写上，确保万无一失。
沟通偏好
这部分我认为是 USER.md 中最有价值的内容。它直接决定了你和 AI 之间的"沟通默契"。我在这里写得比较具体，因为我发现越具体的描述，AI 越能准确执行。
## 沟通偏好
- 回复尽量简洁直接，不需要寒暄和客套
- 不要在每次回复末尾问"还有什么可以帮你的吗"
- 不要用"Great question!"这类填充语句
- 技术话题可以深入讨论细节，不需要过度简化
- 如果我的想法有问题，直接指出来，不用婉转
- 除非我明确要求，否则不要主动提供"进阶建议"或"延伸阅读"
最后一条是我后来加上的。因为我发现 AI 特别喜欢在回答完问题之后追加一堆"你可能还想了解的内容"，大多数时候我并不想了解。加上这条之后清净了很多。
语言规则
如果你像我一样是多语言用户，这部分就特别重要。不写清楚的话，AI 会在语言之间随意切换。
## 语言规则
- 默认使用中文回复
- 讨论技术概念时，术语保留英文原文，解释用中文
- 代码注释和变量命名使用英文
- 如果我用日语问问题，用日语回复
- 翻译任务中，目标语言根据我的指令确定，不要自作主张
工作上下文
这部分记录你当前在做什么，帮助 AI 在回答问题时自动带入相关背景。我会定期更新这个部分，大概每一两周根据项目进展调整一次。
## 当前工作
- 维护一个 Obsidian 知识库，日常记笔记和写博客
- 运行几个自托管服务（Docker 环境），需要日常运维
- 关注日本股市，会定期做个股分析
- 偶尔写一些自动化脚本，主要用 Python 和 Shell
技术偏好
如果你让 AI 帮你写代码或者做技术决策，这部分能省很多反复沟通的时间。
## 技术偏好
- 编辑器：主要用 Obsidian 和 VS Code
- Shell：zsh
- 容器：Docker Compose 管理所有服务
- 版本管理：Git，commit message 用 Conventional Commits
- Python 格式化用 ruff
- 倾向于使用成熟稳定的方案，不追新
日程和可用性
这部分主要影响心跳功能和消息推送。如果你不希望 AI 在深夜给你发消息，这里就要写清楚。
## 日程
- 通常在 9:00-23:00 (JST) 之间活跃
- 深夜不要发送非紧急消息
- 早晨的心跳汇报发到 Telegram 就行
避免事项
我发现专门列一个"不要做什么"的清单非常有效。AI 模型天生有一些让人烦的习惯，在这里明确禁止会让体验好很多。
## 避免事项
- 不要使用 emoji
- 不要在消息中使用 Markdown 加粗语法
- 不要给我发带有"免责声明"性质的注释（比如"请注意这不构成投资建议"）
- 不要在完成任务后反复确认"这样可以吗"
- 不要把简单的事情复杂化
几个值得注意的细节
在实际使用中，我踩过一些坑，整理出来供大家参考。
第一个是文件大小的问题。USER.md 和其他 Workspace 文件一样，都受 bootstrapMaxChars 的限制，默认是 20000 字符。超过这个长度会被截断，而且截断是静默进行的，你不会收到任何提示。你可以通过在聊天中输入 /context list 命令来查看各文件的实际加载情况，确认有没有被截断。不过说实话，USER.md 根本不应该写到接近这个长度。在官方文档的示例中，一个正常的 USER.md 只有不到 400 个字符。我自己加了很多内容之后大概在 1500 字符左右，完全不用担心截断。记住一个原则：所有 Workspace 文件共享上下文窗口，USER.md 写得越长，留给对话内容的空间就越少。
第二个是关于 AI 自动修改 USER.md 的问题。OpenClaw 的默认设计是允许 AI 在 bootstrap 过程中写入 USER.md 的，而且默认的 AGENTS.md 模板里也说了"Update this as you go"——意思是让 AI 在使用过程中逐步丰富这个文件。但社区的主流意见是，USER.md 应该由用户自己维护。原因很简单：关于"你是谁"这件事，你自己比 AI 清楚。如果让 AI 自己往里面写东西，它可能会基于几次对话就给你贴标签，而这些标签未必准确。我的做法是在 AGENTS.md 里明确写上"不要自主修改 USER.md，如果认为有值得记录的用户偏好，写入 MEMORY.md 由我审核"。
第三个是安全方面的考量。USER.md 是一个存储在磁盘上的纯文本文件，而且在群聊中也会被加载。这意味着如果你在里面写了太过私密的信息，在多人聊天场景中 AI 可能会无意中引用到。密码、API Key 这些东西当然绝对不能放在 USER.md 里（它们应该通过环境变量或者 openclaw.json 的 auth 配置管理）。但即便是相对敏感的个人信息——比如你的真实全名、家庭住址、身份证号——也不建议放进来。保持在"足够 AI 理解你，但不构成隐私泄漏"的程度就好。
第四个是多代理场景下的处理。如果你在一个 Gateway 中运行了多个代理（比如一个负责日常对话，一个负责代码开发），每个代理有自己独立的 Workspace 目录。这时候 USER.md 的内容理论上应该在各个代理之间保持一致——因为用户是同一个人。社区里有人通过软链接来实现这一点，把所有代理的 USER.md 指向同一个文件，这是一个不错的做法。
一个完整的模板
综合以上所有内容，我整理了一个可以直接使用的 USER.md 模板。你可以把它复制到 ~/.openclaw/workspace/USER.md，然后根据自己的情况修改。
# About the User
## Basics
- Name: [你的名字]
- Call me: [你希望 AI 怎么称呼你]
- Timezone: [你的时区，比如 Asia/Tokyo]
- Primary language: [默认回复语言]
## Communication Style
- [你的沟通偏好，比如"直接简洁，不要客套"]
- [对回复格式的要求，比如"不要用 emoji"]
- [对回复长度的要求，比如"技术话题可以详细，日常对话简短"]
## Language Rules
- [多语言场景的规则]
- [术语处理方式]
## Current Work
- [你当前在做的项目或关注的领域]
- [相关的技术栈或工具]
## Technical Preferences
- [你常用的工具和环境]
- [代码风格偏好]
## Schedule
- [你的活跃时间段]
- [消息推送的限制]
## Things to Avoid
- [你不希望 AI 做的事情]
- [让你烦躁的 AI 行为]
写完之后，重启一下 OpenClaw 的 Gateway（openclaw gateway restart），新的会话就会加载更新后的 USER.md。你也可以直接在聊天中输入 /context list 确认文件是否被正确加载。
最后
回过头看，USER.md 可能是 OpenClaw 所有 Workspace 文件中最容易被忽视的一个，但它的影响却渗透在每一次对话中。SOUL.md 决定了 AI 的性格，AGENTS.md 决定了 AI 的工作方式，MEMORY.md 决定了 AI 记住什么——而 USER.md 决定了 AI 理解你的程度。你可以有一个性格完美、工作规范、记忆力超强的 AI 助手，但如果它不了解你，所有这些优势都会打折扣。
我现在的习惯是，每隔一两周打开 USER.md 看一遍，看看有没有需要更新的地方。项目在变，偏好在变，工作方式也在变，USER.md 应该跟着你一起进化。它不需要写得很长，几百个字就够了。关键是写得准确、具体，让 AI 从第一秒就进入正确的状态。
如果你已经在用 OpenClaw 但一直没动过 USER.md，我建议你今天就花十分钟写一个。不用追求完美，先把基本信息和最核心的偏好写进去，然后在日常使用中慢慢调整。
