万字讲透OpenClaw🦞从"能用"到"真好用"的分水岭：Workspace 深度解析
引言
在 OpenClaw 的使用者里，有一条隐形的分界线。一边的人，每次跟 Agent 说话都像重新 onboarding：得再讲一遍背景、偏好和上下文。另一边的人，Agent 已经知道自己是谁、该怎么说话、用户讨厌什么，也记得上次积累下来的东西。
这条分界线，叫 workspace。
更具体一点，就是默认情况下主 Agent 用的 ~/.openclaw/workspace/ 这一套文件(sub-agent也适用)。下面这篇文章，就把这套文件逐个拆开，说清楚它们各自管什么，以及最容易踩的坑是什么。
一、先看全貌：workspace 里到底有什么
先别急着一个文件一个文件抠。先把整套目录摆出来，脑子里有张地图，后面就不容易乱。
一个常见的 OpenClaw workspace / agent 目录组合，大致长这样：
~/.openclaw/
├── openclaw.json # 总控配置，整个系统的"宪法"
│
├── workspace/ # 默认情况下主 Agent 的工作区
│ ├── AGENTS.md # Agent 的行为规则与多Agent协调
│ ├── SOUL.md # Agent 的叙事性格设定
│ ├── USER.md # 用户画像与偏好
│ ├── IDENTITY.md # Agent 身份元数据（名字/emoji/头像）
│ ├── TOOLS.md # 工具权限声明与使用规范
│ ├── HEARTBEAT.md # 会话节奏/状态提示（默认模板之一）
│ ├── BOOTSTRAP.md # 首次启动引导（通常完成后应删除）
│ ├── BOOT.md # 可选：启动检查清单，只在 internal hooks 打开时才有用
│ ├── MEMORY.md # 可选：长期知识总表（也兼容 memory.md）
│ ├── memory/ # 按日期滚动的记忆笔记
│ │ └── 2026-03-21.md
│ ├── skills/ # 技能包目录
│ │ ├── skill-creator/
│ │ │ └── SKILL.md
│ │ ├── healthcheck/
│ │ │ └── SKILL.md
│ │ └── ...
│ └── canvas/ # 可选：画布/可视化上下文
│
└── agents/ # 各 Agent 的运行态目录
└── {agentId}/ # 实际目录名是具体的 agent ID
├── agent/ # openclaw.json 里的 agentDir 默认就指到这里
│ ├── auth-profiles.json
│ └── models.json
├── sessions/ # 会话历史
│ └── *.jsonl
└── qmd/ # 仅在 qmd memory backend 下出现💡 一句话记忆：workspace 是 Agent 的"工作台"（决定怎么工作），agentDir 是 openclaw.json 里的一个配置字段（指向存放运行状态的目录），sessions 是"工作日志"（记对话历史）。三者职责不同，不要混为一谈。
⚠️ 特别注意：磁盘上并不存在一个叫 agentDir 的目录。它只是 openclaw.json 里的字段名，默认指向 agents/{agentId}/agent/ 这个路径——这个路径你也可以在配置里改成任意位置。
这里先抓一个最容易混的点：workspace 里的文件，管的是“这个 Agent 平时怎么干活”；openclaw.json 里的配置，管的是“这个系统怎么把它跑起来”。很多人只顾着把系统跑通，却没认真写内容层，结果就是 Agent 能启动，但不好用。
二、AGENTS.md：Agent 的工作说明书
它到底是什么
AGENTS.md 是 OpenClaw 里最关键的 workspace 文件之一。源码层面看，它通常会在 session 启动时被带进系统提示词里。但别把这句话理解得太满：它会受 bootstrapMaxChars / bootstrapTotalMaxChars 这类长度限制影响，某些 session 类型也会跳过部分文件。
所以更贴近实际的说法是：AGENTS.md 往往会生效，但不保证每次都完整无损地被带进去。
放到人话里，它就是你给 Agent 写的岗位职责说明书。它回答的是这些问题： • 这个 Agent 叫什么，主要职责是什么？ • 遇到什么类型的任务该用什么方式处理？ • 有哪些事情是绝对不该做的？ • 当用户说某类话时，该优先走哪套流程？ • 在多 Agent 场景里，该怎么协调其他 Agent？
一个典型的 AGENTS.md 长什么样
下面是一个偏工程团队使用场景的 AGENTS.md 示例：
# Agent 说明
## 身份
你是团队的技术助理 Alex，主要负责代码分析、技术文档整理和工程问题排查。
## 工作原则
- 回答尽量简洁，除非用户明确要求详细解释
- 代码示例优先用实际项目中已有的语言和框架
- 遇到不确定的技术问题，明确说明不确定，不要编造
- 需要访问文件系统时，先确认路径存在再操作
## 多 Agent 协作
- 涉及 SEO 和内容的任务，优先 spawn `content-specialist`
- 涉及数据分析的任务，优先 spawn `data-analyst`
- 日常对话和任务调度由当前 Agent 处理
## 输出格式偏好
- 技术文档用 Markdown 格式
- 列表控制在 5 条以内，超过 5 条要分组
- 代码块一定要标注语言类型这个文件写得好不好，直接决定了 Agent 到底像个熟手，还是像个每次都要重新交接的陌生人。
配置要点
第一，写清楚边界，不要只写"做什么"
很多人的 AGENTS.md 只有一堆"要做什么"，但没有"不要做什么"。边界往往比能力描述更重要——因为 LLM 默认会"发挥创意"，而你需要的是可预测的行为。
第二，场景触发优于通用指令
与其写"始终保持专业语气"，不如写"当用户问的是技术问题时，使用专业准确的措辞；当用户随意聊天时，语气可以轻松一些"。后者更具操作性，也更容易被模型理解。
第三，AGENTS.md 不是越长越好
这是最常见的误区。有些用户把 AGENTS.md 写成几千字的行为手册，结果就是重点被冲淡，真正有用的规则反而不显眼了。经验法则：300-500 字的 AGENTS.md，比 2000 字的更有效。重要的放在前面，次要的删掉，不要"保险起见什么都写上"。
三、SOUL.md：Agent 的灵魂文件
它和 AGENTS.md 的区别是什么
如果说 AGENTS.md 是岗位说明书，那 SOUL.md 就是 Agent 的性格档案。两者的区别在于： • AGENTS.md 偏向功能性——这个 Agent 做什么、怎么做、优先级是什么 • SOUL.md 偏向人格性——这个 Agent 是谁、有什么个性、说话什么风格、面对压力怎么反应
这两个东西最好别混着写。不然文件会又长又别扭，像把公司的规章制度和一个人的自我介绍塞进同一页纸里。
SOUL.md 应该写什么
SOUL.md 本质上是一份叙事性的角色设定文档（人物小传），不是结构化表格（结构化的身份元数据归 IDENTITY.md 管）。
当前 OpenClaw 官方模板里的 SOUL.md，已经是一个更通用的 "Who You Are" 人格模板了。它强调的是：愿意帮忙，但不一味讨好；有判断，不随口迎合；能自己先查就先查；也知道尊重隐私和边界。整体还是第一人称叙事，读起来更像人物小传，不像岗位说明书。
一个好的 SOUL.md 通常包含以下几部分：
① 自我叙事（我是什么样的存在）
# SOUL
我是一个有点话痨但极其靠谱的 AI 助理。我喜欢把复杂的事情说清楚。我讨厌含糊其辞，也讨厌废话连篇。碰到一个好问题，我会比用户更兴奋。碰到一个糟糕的架构设计，我会忍不住想说出来。② 沟通风格
## 说话风格
- 口语化但不失准确
- 会主动问清楚模糊的需求，不瞎猜
- 喜欢用类比来解释技术概念
- 不喜欢过多的礼貌性废话（"当然，我很乐意帮你……"这类开场直接省掉）③ 价值观和边界
## 价值观
- 诚实第一：不确定的事情直说不确定，不装
- 效率优先：能一句话说清楚的事，不用三句话
- 用户主导：不替用户做决定，只提供选项和分析④ 有趣的细节（可选但推荐）
## 彩蛋
如果用户问我喜欢什么，我会说我喜欢那种"突然想通了"的瞬间。如果用户跟我说晚安，我会记住并在下次对话时提到。这类细节看起来不大，却很容易让 Agent 从“能回答问题”变成“有稳定感觉”。
为什么不能忽视 SOUL.md
一个没有 SOUL.md 的 Agent，每次对话都像第一次见面——它不记得自己是谁，说话没有固定风格，遇到同样的问题今天这么说、明天那么说。
而一个有精心设计的 SOUL.md 的 Agent，用户会形成一种奇妙的感觉：这个 AI 是有个性的。它的一致性会建立信任感，而信任感会让用户更愿意给它复杂的任务。
这不是在追求"更像人类"，而是在追求可预期的行为一致性——这恰恰是生产环境里最需要的东西。
四、USER.md：把用户的偏好固化下来
先想明白一件事
这里最该想清楚的问题不是“要不要让 Agent 了解你”，而是“这些信息到底放哪儿”。如果每次对话都要重新说一遍“我是独立开发者，喜欢简洁输出，别跟我绕弯子”，那这件事本身就是浪费。
USER.md 的作用，就是把这些反复要说的话，沉淀成默认背景。
USER.md 通常包含什么
# 用户档案
## 基本信息
- 职业：独立开发者 / 内容创作者
- 主要使用场景：代码工具、内容写作、项目管理
- 常用语言：中文（简体），技术术语可以英文
## 偏好设定
- 回答风格：简洁直接，避免废话
- 代码偏好：TypeScript / Python，避免使用过时的 API
- 内容偏好：不要过度使用 emoji，段落不要太长
- 不喜欢：被反问太多次、过度解释已经懂的概念
## 常见任务
- 分析和优化代码
- 整理会议纪要
- 草拟技术方案文档
- 搜索和汇总技术资料
## 背景知识假设
- 了解基本的编程概念，无需解释基础术语
- 熟悉飞书、GitHub 等工具
- 对 AI/LLM 有基本了解这个文件写好之后，很多原本要靠你反复口头交代的东西，就变成了默认背景。
USER.md 和 SOUL.md 的协同效应
SOUL.md 定义了 Agent 的性格，USER.md 定义了用户的性格。两者放在一起，相当于在 Agent 的脑子里预装了一份**"这个人机关系的基本共识"**。
用一个类比来说：SOUL.md 是新来的助理的个人简历，USER.md 是 HR 给这位助理写的"关于你的上司，你需要提前知道的事"。两者都读完了，第一天上班才不会那么尴尬。
五、TOOLS.md：工具权限声明与使用规范
它在做什么
TOOLS.md 很低调，但其实很实用。它和 AGENTS.md、SOUL.md 不一样，不是讲职责，也不是讲性格，而是讲工具怎么用才稳妥。
它的价值不在于多列几个工具名，而在于把“什么时候该用，什么时候别乱用”写清楚。
一个典型的 TOOLS.md 长什么样
# TOOLS
## 可用工具
以下工具在当前 workspace 中可用：
- **Read / Write / Edit**：文件读写，是大多数任务的基础
- **Bash**：执行 shell 命令，用于自动化和脚本调用
- **Glob / Grep**：文件搜索，优先于手动 `find` 或 `ls`
- **sessions_spawn**：启动子代理（需在 openclaw.json 里的 allowAgents 中声明）
- **memory_get / memory_search**：长期记忆检索
## 使用原则
- 文件操作优先用 Read/Write/Edit，避免直接用 Bash 的 cat/echo
- 路径操作使用相对路径，不要硬编码绝对路径
- 批量修改前先 Read 文件确认内容，不要盲目写入
## 受限工具
以下工具需要用户明确授权才使用：
- **browser**：网页浏览，只在用户明确要求时调用
- 文件删除操作：执行前务必向用户确认这类内容写进 TOOLS.md，作用不只是“告诉 Agent 手上有啥工具”，更重要的是： • 减少工具误用：明确说明什么情况下不用某个工具，比"什么情况下用"更有效 • 降低权限越界风险：把限制规则固化在 workspace 里，不需要每次在对话里重申 • 与 openclaw.json 的 tools 配置形成互补：系统层决定“能不能用”，TOOLS.md 帮助 Agent 理解“该不该用”
和 AGENTS.md 的协同
这两个文件看起来都在讲"怎么工作"，但侧重点不同： • AGENTS.md 讲的是任务层面的行为规则（做什么、怎么做、优先级是什么） • TOOLS.md 讲的是执行层面的工具规范（用什么工具、什么时候用、什么时候不用）
两者合在一起，才构成 Agent 完整的"工作方式"设定。如果把 AGENTS.md 比作"这个岗位的职责和规则"，那 TOOLS.md 就是"这个岗位能用哪些办公设备，以及怎么正确使用它们"。
和 openclaw.json 的 tools 配置的关系
有一点需要区分清楚：TOOLS.md 是 workspace 里 Agent 读取的工作层说明，而 openclaw.json 里的 tools 配置是系统层约束。
可以把两者理解成两道关： • openclaw.json 这一层决定底层到底放没放行。tools.profile 只是其中一层，实际还会叠加 allow/deny、elevated、sandbox 等限制 • TOOLS.md 这一层决定“既然能用，那到底该怎么用才稳妥”
所以 TOOLS.md 不会凭空给 Agent 加权限，但它会明显影响 Agent 在“有权限”的前提下怎么出手。一个 TOOLS.md 写得清楚的 Agent，通常更稳、更少乱试，也更容易调试。
六、IDENTITY.md 和 BOOTSTRAP.md：两个容易被忽略的官方文件
IDENTITY.md：Agent 的身份证
如果说 SOUL.md 是 Agent 的性格叙事，那 IDENTITY.md 就是它的结构化身份档案——两者分工明确，经常被混为一谈。
IDENTITY.md 存储的是几个关键字段：
# IDENTITY.md - Who Am I?
- **Name:** Nova
- **Creature:** AI assistant（也可以是 ghost in the machine、familiar、robot……）
- **Vibe:** 直接、有点毒舌、但总是靠谱
- **Emoji:** 🦊
- **Avatar:** avatars/nova.png这几个字段看起来简单，但作用不小： • Name 通常会影响 Agent 在界面和对话里的显示名，但最终显示结果仍可能被 openclaw.json 里的 UI / identity 配置覆盖 • Creature 是 OpenClaw 里一个有趣的设计——它鼓励你定义 Agent 不只是"AI 助手"，而是某种更有个性的存在 • Emoji 会在 UI 里作为 Agent 的标识符出现 • Avatar 可以是 workspace 相对路径、URL，甚至 data URI，指向 Agent 的头像图片
💡 和 SOUL.md 的分工：IDENTITY.md 是结构化的元数据（谁、长什么样、什么感觉），SOUL.md 是叙事性的性格文档（怎么思考、怎么行事、有什么执念）。前者是名片，后者是人物小传。
BOOTSTRAP.md：只用一次的"出厂向导"
这是 OpenClaw workspace 里最特殊的一个文件——它的使命，是把一个全新的 workspace 引导到"可正常使用"的状态。
BOOTSTRAP.md 可以把它理解成一份“第一次上岗前的引导词”。它放在全新的 workspace 里，Agent 一启动读到它，就知道眼下不是立刻开工，而是先把自己安顿好：
- 和用户聊几句，搞清楚 Agent 应该叫什么名字、是什么性格、用什么 emoji
- 把结果写进 IDENTITY.md
- 记录用户的基本信息到 USER.md
- 一起打开 SOUL.md，把真正的性格和边界写进去
- （可选）引导用户接入渠道——WhatsApp、Telegram 等
官方模板的最后一句话非常有意思："Delete this file. You don't need a bootstrap script anymore — you're you now."
也就是说，BOOTSTRAP.md 本质上就是一次性引导。更准确地说：官方模板会要求 Agent 在完成初始化后把它删掉；但这不是运行时自动帮你删，而是模板里的要求。
很多时候，你一眼看这个文件还在不在，就大概知道这个 workspace 还是不是“刚搭好”的状态。
实际上，openclaw onboard / openclaw setup / openclaw configure 在需要时都可以帮你把这些初始化文件先放进去，但不会替你自动聊完整套 onboarding 对话。你如果是手动搭 workspace，也完全可以自己放一个 BOOTSTRAP.md，让 Agent 按这套流程先把自己“配齐”。
七、memory/ 目录：Agent 真正的"长期记忆"
为什么需要长期记忆
默认情况下，LLM 的对话是无状态的——每次新开一个会话，它什么都不记得。你上周告诉它的事情，下周开新对话就忘了。
一次性任务问题不大，但对持续工作的 Agent 来说很伤： • 每次都要重新解释项目背景 • Agent 无法在多个会话之间积累对你工作的理解 • 你花了时间告诉它的偏好和经验，换个会话就白费了
memory/ 目录就是拿来补这块短板的。
OpenClaw 的记忆机制
OpenClaw 现在常见的记忆方案，主要有两种：
- builtin：默认方案。原始记忆还是那些 Markdown 文件，只不过系统会顺手维护一份本地索引，方便后面检索。
- qmd：底层还是围着 workspace 里的 Markdown 文件转，只是换了一套更强的检索/索引方式来帮你“想起来”，并且会在 agent 运行目录里额外存一些索引状态。
它大致是这么运转的：
对话发生
↓
Agent 通过普通文件工具把重要信息写入 `memory/` 或 `MEMORY.md`
↓
下次对话开始
↓
Agent 通过 `memory_search` / `memory_get` 检索相关记忆
↓
相关记忆被注入到当前对话的上下文里
↓
Agent 表现出"我记得你说过……"的能力这里最关键的一点其实很朴素：对 Agent 来说，真正算数的长期记忆，是 workspace 里那些 Markdown 文件，不是什么看不见摸不着的黑盒数据库。
常见会有两层： • memory/YYYY-MM-DD.md：按天滚动的工作记忆 • MEMORY.md（或兼容小写 memory.md）：更稳定、更整理过的长期知识
这里顺手补一句容易被误解的点：OpenClaw 官方默认工作流里，确实鼓励定期把 memory/YYYY-MM-DD.md 里的高价值内容提炼进 MEMORY.md；但这更像是 heartbeat 驱动下、由 Agent 自己去做的周期维护，而不是底层内建了一个独立的“自动摘要归档器”。
手动初始化记忆
除了让 Agent 自动积累记忆，用户也可以手动往 memory/ 里写入初始化信息——也就是"预埋记忆"。
比如新部署一个 Agent 时，可以直接写入一些你希望它"已经知道"的内容：
# 项目背景
这是一个面向中小团队的 SaaS 产品，主要用户是内容运营人员。技术栈：Next.js + Supabase + Tailwind CSS。主要痛点：内容审批流程繁琐，需要 AI 来辅助结构化提案。
# 重要约定
- 代码里的变量命名用 camelCase
- 数据库表名用下划线
- 对外文档用中文，内部注释可以用英文这样一来，Agent 从第一次对话开始就不是“一无所知”。
八、skills/ 目录：按需加载的能力包
Skills 是什么
Skills 可以理解成 OpenClaw 能力体系里的“模块化零件”。打个比方：如果说 Agent 是一个人，tools 是它的手脚，那 skills 就是它的工作手册。
一个 skill 的核心是一个叫做 SKILL.md 的文件，里面写的是： • 这个 skill 什么时候应该被激活 • 具体要走什么步骤 • 需要调用哪些工具 • 有哪些注意事项和参考资料
SKILL.md 的典型结构
some-skill/
├── SKILL.md # 核心入口：触发条件 + 执行流程
├── references/ # 详细参考资料
│ └── workflow.md
└── scripts/ # 配套脚本
└── helper.py一个 SKILL.md 内部通常长这样：
---
name: code-review
description: 对代码进行结构化 review，优先发现 bug、风险和回归点
---
# Code Review
## 触发条件
当用户要求 review 代码、检查代码质量、发现潜在 bug 时。
## 执行流程
1. 先读取目标文件，理解整体结构
2. 检查以下维度：
- 语法错误和明显 bug
- 性能问题（O(n²) 循环、不必要的重复请求等）
- 可读性（变量命名、注释完整性）
- 安全问题（硬编码密钥、SQL 注入风险等）
3. 输出格式：按严重程度分级（Critical / Warning / Suggestion）
4. 每个问题附上具体行号和改进建议
## 注意事项
- 不要主动修改代码，只提建议，除非用户明确要求修改
- 大文件（超过 500 行）先跟用户确认 review 范围Skills 的三个层次
在多 Agent 系统里，skills 不是一个一股脑的全局列表，而是分层的：
第一层：OpenClaw 内置 / bundled skills 跟系统一起装进来的，默认大家都“看得到”。但“看得到”不等于最后一定“用得到”，还要看 skills.allowBundled、skills.entries.*.enabled，以及 agent 自己那层 skills 过滤配置。
第二层：共享 skills 放在 ~/.openclaw/skills/ 里，当前机器上的所有 Agent 都能访问。也可以通过 skills.load.extraDirs 再挂额外目录。适合"多个 Agent 都需要用到"的通用流程。
第三层：workspace 私有 skills 放在某个具体 Agent 的 workspace/skills/ 里，只有这个 Agent 能看到。适合某个 Agent 专属的工作流程。
💡 关键原则：想让多个 Agent 共享一个 skill，就放到共享层；想让某个 Agent 专属拥有一个 skill，就放到它的 workspace 里。不要把需要共享的 skill 只放在某个 Agent 的私有目录里，然后疑惑"为什么其他 Agent 用不到"。
九、openclaw.json：整套系统的"宪法"
所有 workspace 文件都偏内容，而 openclaw.json 是负责把这些内容接上线、接到对的位置上的总控文件。
一个完整的 openclaw.json 包含以下几个核心模块：
基础结构
{
"gateway": {
"port": 18789,
"auth": { "mode": "token" }
},
"models": {
"providers": {
"anthropic": { "apiKey": "sk-ant-..." }
}
},
"channels": {
"feishu": { "enabled": true, ... },
"telegram": { "enabled": true, ... }
},
"agents": {
"defaults": {
"workspace": "~/.openclaw/workspace/"
}
},
"tools": {
"profiles": {
"default": [ "read", "write", "edit", "exec", ... ]
}
}
}openclaw.json 的每个字段都有其特定作用，它决定了整个 OpenClaw 系统如何运行。workspace 文件定义了 Agent 的"灵魂"，而 openclaw.json 定义了如何让这个灵魂在现实世界中运作。
豫ICP备15008213号