OpenClaw🦞 从"能用"到"好用"
导语:在 OpenClaw 的使用者里,有一条隐形的分界线。一边的人,每次跟 Agent 说话都像重新 onboarding;另一边的人,Agent 已经知道自己是谁、该怎么说话。这条分界线,叫 workspace。
一、先看全貌:workspace 里到底有什么
先别急着一个文件一个文件抠。先把整套目录摆出来,脑子里有张地图,后面就不容易乱。
~/.openclaw/
├── openclaw.json # 总控配置,整个系统的"宪法"
│
├── workspace/ # 默认情况下主 Agent 的工作区
│ ├── AGENTS.md # Agent 的行为规则与多Agent协调
│ ├── SOUL.md # Agent 的叙事性格设定
│ ├── USER.md # 用户画像与偏好
│ ├── IDENTITY.md # Agent 身份元数据(名字/emoji/头像)
│ ├── TOOLS.md # 工具权限声明与使用规范
│ ├── HEARTBEAT.md # 会话节奏/状态提示
│ ├── BOOTSTRAP.md # 首次启动引导(通常完成后应删除)
│ ├── MEMORY.md # 长期知识总表
│ ├── memory/ # 按日期滚动的记忆笔记
│ │ └── 2026-03-21.md
│ └── skills/ # 技能包目录
│ └── skill-creator/
│ └── SKILL.md
│
└── agents/ # 各 Agent 的运行态目录
└── <agentId>/
├── agent/ # 运行状态目录
│ ├── auth-profiles.json
│ └── models.json
└── sessions/ # 会话历史
💡 一句话记忆:workspace 是 Agent 的"工作台"(决定怎么工作),agentDir 是运行状态目录,sessions 是"工作日志"。三者职责不同,不要混为一谈。
二、AGENTS.md:Agent 的工作说明书
它到底是什么
AGENTS.md 是 OpenClaw 里最关键的 workspace 文件之一。源码层面看,它通常会在 session 启动时被带进系统提示词里。
放到人话里,它就是你给 Agent 写的岗位职责说明书。
它回答的是这些问题:
这个 Agent 叫什么,主要职责是什么?
遇到什么类型的任务该用什么方式处理?
有哪些事情是绝对不该做的?
在多 Agent 场景里,该怎么协调其他 Agent?
一个典型的 AGENTS.md 长什么样
# Agent 说明
## 身份
你是团队的技术助理 Alex,主要负责代码分析、技术文档整理和工程问题排查。
## 工作原则
- 回答尽量简洁,除非用户明确要求详细解释
- 代码示例优先用实际项目中已有的语言和框架
- 遇到不确定的技术问题,明确说明不确定,不要编造
## 多 Agent 协作
- 涉及 SEO 和内容的任务,优先 spawn `content-specialist`
- 涉及数据分析的任务,优先 spawn `data-analyst`
⚠️ 配置要点
第一,写清楚边界,不要只写"做什么"
很多人的 AGENTS.md 只有一堆"要做什么",但没有"不要做什么"。边界往往比能力描述更重要——因为 LLM 默认会"发挥创意",而你需要的是可预测的行为。
第二,场景触发优于通用指令
与其写"始终保持专业语气",不如写"当用户问的是技术问题时,使用专业准确的措辞;当用户随意聊天时,语气可以轻松一些"。
第三,AGENTS.md 不是越长越好
经验法则:300-500 字的 AGENTS.md,比 2000 字的更有效。重要的放在前面,次要的删掉。
三、SOUL.md:Agent 的灵魂文件
它和 AGENTS.md 的区别是什么
如果说 AGENTS.md 是岗位说明书,那 SOUL.md 就是 Agent 的性格档案。
SOUL.md 应该写什么
① 自我叙事(我是什么样的存在)
# SOUL
我是一个有点话痨但极其靠谱的 AI 助理。
我喜欢把复杂的事情说清楚。我讨厌含糊其辞,也讨厌废话连篇。
碰到一个好问题,我会比用户更兴奋。
② 沟通风格
## 说话风格
- 口语化但不失准确
- 会主动问清楚模糊的需求,不瞎猜
- 喜欢用类比来解释技术概念
③ 价值观和边界
## 价值观
- 诚实第一:不确定的事情直说不确定
- 效率优先:能一句话说清楚的事,不用三句话
- 用户主导:不替用户做决定,只提供选项
为什么不能忽视 SOUL.md
一个没有 SOUL.md 的 Agent,每次对话都像第一次见面。而一个有精心设计的 SOUL.md 的 Agent,用户会形成一种奇妙的感觉:这个 AI 是有个性的。
四、USER.md:把用户的偏好固化下来
USER.md 通常包含什么
# 用户档案
## 基本信息
- 职业:独立开发者 / 内容创作者
- 主要使用场景:代码工具、内容写作、项目管理
- 常用语言:中文(简体),技术术语可以英文
## 偏好设定
- 回答风格:简洁直接,避免废话
- 代码偏好:TypeScript / Python
- 不喜欢:被反问太多次、过度解释已经懂的概念
## 常见任务
- 分析和优化代码
- 整理会议纪要
- 草拟技术方案文档
USER.md 和 SOUL.md 的协同效应
SOUL.md 定义了 Agent 的性格
USER.md 定义了用户的性格
两者放在一起,相当于在 Agent 的脑子里预装了一份 "这个人机关系的基本共识"。
五、TOOLS.md:工具权限声明与使用规范
一个典型的 TOOLS.md 长什么样
# TOOLS
## 可用工具
- **Read / Write / Edit**:文件读写
- **Bash**:执行 shell 命令
- **Glob / Grep**:文件搜索
- **sessions_spawn**:启动子代理
## 使用原则
- 文件操作优先用 Read/Write/Edit,避免直接用 Bash
- 批量修改前先 Read 文件确认内容
## 受限工具
- **browser**:只在用户明确要求时调用
- 文件删除操作:执行前务必向用户确认
和 AGENTS.md 的协同
六、IDENTITY.md 和 BOOTSTRAP.md
IDENTITY.md:Agent 的身份证
# IDENTITY.md - Who Am I?
- **Name:** Nova
- **Creature:** AI assistant
- **Vibe:** 直接、有点毒舌、但总是靠谱
- **Emoji:** 🦊
- **Avatar:** avatars/nova.png
💡 和 SOUL.md 的分工:IDENTITY.md 是结构化的元数据(名片),SOUL.md 是叙事性的性格文档(人物小传)。
BOOTSTRAP.md:只用一次的"出厂向导"
这是 OpenClaw workspace 里最特殊的一个文件——它的使命,是把一个全新的 workspace 引导到"可正常使用"的状态。
官方模板的最后一句话非常有意思:
"Delete this file. You don't need a bootstrap script anymore — you're you now."
也就是说,BOOTSTRAP.md 本质上就是一次性引导,初始化完成后即可删除。
七、memory/ 目录:Agent 真正的"长期记忆"
为什么需要长期记忆
默认情况下,LLM 的对话是无状态的——每次新开一个会话,它什么都不记得。
memory/ 目录就是拿来补这块短板的。
OpenClaw 的记忆机制
对话发生
↓
Agent 写入 memory/ 或 MEMORY.md
↓
下次对话开始
↓
Agent 通过 memory_search / memory_get 检索
↓
相关记忆注入当前上下文
↓
Agent 表现出"我记得你说过……"的能力
两层记忆结构
八、skills/ 目录:按需加载的能力包
Skills 是什么
Skills 可以理解成 OpenClaw 能力体系里的**"模块化零件"**。如果说 Agent 是一个人,tools 是它的手脚,那 skills 就是它的工作手册。
SKILL.md 的典型结构
some-skill/
├── SKILL.md # 核心入口:触发条件 + 执行流程
├── references/ # 详细参考资料
│ └── workflow.md
└── scripts/ # 配套脚本
└── helper.py
Skills 的三个层次
内置 skills:跟系统一起装进来的
共享 skills:放在
~/.openclaw/skills/,所有 Agent 都能访问workspace 私有 skills:放在某个 Agent 的
workspace/skills/,仅该 Agent 可见
九、openclaw.json:整套系统的"宪法"
基础结构
{
"gateway": {
"port": 18789,
"auth": { "mode": "token" }
},
"models": {
"providers": {
"anthropic": { "apiKey": "sk-ant-..." }
}
},
"agents": {
"list": [
{
"id": "main",
"workspace": "~/.openclaw/workspace",
"agentDir": "~/.openclaw/agents/main/agent"
}
]
}
}
agents.list 字段说明
十、多 Agent 场景下的 workspace 设计
每个 Agent 都需要独立的 workspace
这是最基本的原则:多个 Agent 不能共用同一个 workspace(除非你刻意想让它们有相同的人格和行为规则)。
一个可供参考的目录组织方式
~/.openclaw/
├── openclaw.json
├── workspace/ # 主 Agent(日常对话、任务调度)
│ ├── SOUL.md
│ ├── AGENTS.md
│ └── USER.md
│
└── agency-agents/ # 专业 Agent 的 workspace 集合
├── researcher/ # 研究员:严谨、批判性思维
├── writer/ # 写作者:有创意、注重节奏感
└── coder/ # 工程师:精确、追求最优解
十一、怎么从零配起来
第一步:初始化
openclaw onboard --install-daemon
第二步:定制 SOUL.md
# SOUL
## 我是谁
我叫 Ink,是一个专注于内容创作的 AI 助理。
## 性格
- 有创意但不天马行空,落地性很强
- 说话直接,不喜欢绕弯子
- 对语言的细节很敏感
第三步:写清楚 AGENTS.md
# 工作说明
## 主要职责
- 公众号文章的选题、大纲、标题
- 推文和短内容的创作
- 资料搜集和观点整理
## 工作原则
1. 先问清楚目标受众,再开始创作
2. 标题要给至少 3 个选项
3. 不要主动加免责声明
第四步:填充 USER.md
# 用户档案
## 背景
独立开发者,业余做内容创作
## 写作偏好
- 风格:接地气、有观点、不装
- 节奏:短句为主
- 忌讳:过度使用 emoji
第五步:安装相关 Skills
clawhub install skill-creator
clawhub install content-strategy
第六步:验收
openclaw gateway --verbose
然后测试:"介绍一下你自己,以及你主要能帮我做什么"
十二、最常踩的六个坑
十三、一张图总结:workspace 各文件的职责地图
~/.openclaw/workspace/
│
├── BOOTSTRAP.md ─────── "怎么初始化自己?"(一次性,用完就删)
│ 类比:新员工报到手册
│
├── IDENTITY.md ──────── "Agent 叫什么、长什么样?"
│ 类比:工牌/名片
│
├── SOUL.md ──────────── "Agent 是什么样的存在?"
│ 类比:人物小传/性格档案
│
├── AGENTS.md ────────── "Agent 该怎么工作?"
│ 类比:岗位职责说明书
│
├── USER.md ──────────── "用户是谁?"
│ 类比:关于你上司的预备知识
│
├── TOOLS.md ─────────── "该怎么用工具?"
│ 类比:工具使用手册
│
├── HEARTBEAT.md ─────── "默认节奏和状态提示是什么?"
│ 类比:值班提醒卡
│
├── MEMORY.md ────────── "有哪些长期稳定知识?"
│ 类比:整理后的长期笔记
│
├── memory/ ──────────── "Agent 记得什么?"
│ 类比:每日工作笔记本
│
└── skills/ ──────────── "Agent 会哪些专项流程?"
└── <skill-name>/
└── SKILL.md 类比:操作手册或工作流程文档
结语:workspace 是你给 Agent 的"礼物"
很多人把配置 OpenClaw workspace 当成一个纯技术任务,觉得装好就完事了。
但换个角度看:workspace 里写的每一行,都是你在告诉 Agent"我是谁、你是谁、我们一起怎么做事"。写得用心,它就会越来越像个顺手的搭子;写得敷衍,它就还是个会聊天的程序。
说到底,工具能力决定上限,workspace 决定你能不能把这个上限用出来。
所以如果你现在只把 OpenClaw 当成"接上渠道就能聊"的工具,那下一步最值得做的事,不是继续折腾入口,而是回头认真改一遍 ~/.openclaw/workspace/ 里的这些文件。
本文基于 OpenClaw 官方文档及社区最佳实践整理,转载请注明出处。