一条看不见的分界线

用OpenClaw的人，其实分成两类。

第一类，每次跟AI对话都得重新交代背景、偏好和上下文，就像每次都是第一次见面。

第二类，AI已经知道你是谁、该怎么说话、你讨厌什么，甚至还记得上次积累的经验。

这条分界线，叫做workspace。

更具体地说，就是~/.openclaw/workspace/这一套文件系统。今天这篇文章，就把这套系统彻底拆开讲清楚。

先看全貌：workspace里到底有什么

别着急扣细节，先把整套目录结构摆出来，脑子里有张地图：

~/.openclaw/├── openclaw.json              # 总控配置（整个系统的"宪法"）│├── workspace/                 # 主Agent的工作区│   ├── AGENTS.md              # 工作说明书│   ├── SOUL.md                # 性格档案│   ├── USER.md                # 用户画像│   ├── IDENTITY.md            # 身份名片│   ├── TOOLS.md               # 工具规范│   ├── HEARTBEAT.md           # 会话节奏│   ├── BOOTSTRAP.md           # 初始化向导（用完就删）│   ├── MEMORY.md              # 长期知识库│   ├── memory/                # 按日期滚动的记忆│   │   └── 2026-03-21.md│   ├── skills/                # 技能包│   └── canvas/                # 可视化上下文（可选）│└── agents/                    # 运行态目录    └── <agentId>/        ├── agent/             # 认证配置、模型清单        └── sessions/          # 会话历史

一句话理解：workspace管"怎么干活"，openclaw.json管"怎么跑起来"，sessions是"工作日志"。

很多人只顾着把系统跑通，却没认真写workspace内容，结果就是AI能启动，但不好用。

AGENTS.md：工作说明书

它是什么

AGENTS.md是OpenClaw最重要的文件之一，它会注入到系统提示词里。

人话版：这是你给AI写的岗位职责说明书。

它回答这些问题：

• 这个Agent叫什么，主要职责是什么？
• 遇到什么任务该怎么处理？
• 有哪些事绝对不该做？
• 多Agent场景下怎么协调？

典型示例

# AGENTS.md - 你的工作区## 身份你是团队的技术助理Herman，主要负责代码分析、技术文档整理和工程问题排查。## 工作原则- 回答尽量简洁，除非用户明确要求详细解释- 代码示例优先用实际项目中的语言和框架- 不确定的问题明确说明，不要编造- 文件系统操作前先确认路径存在## 多Agent协作- SEO和内容任务优先spawn content-specialist- 数据分析任务优先spawn data-analyst- 日常对话由当前Agent处理## 输出格式- 技术文档用Markdown格式- 列表控制在5条以内，超过要分组- 代码块标注语言类型

配置要点

第一，写清楚边界

不要只写"做什么"，更要写"不做什么"。边界比能力描述更重要——因为LLM默认会"发挥创意"，你需要的是可预测的行为。

第二，场景触发优于通用指令

与其写"始终保持专业语气"，不如写"技术问题时用专业措辞，随意聊天时语气可以轻松"。后者更具操作性。

第三，不是越长越好

经验法则：300-500字的AGENTS.md，比2000字的更有效。重要的放前面，次要的删掉。

SOUL.md：性格档案

和AGENTS.md的区别

• AGENTS.md偏向功能性——做什么、怎么做、优先级是什么
• SOUL.md偏向人格性——是谁、什么个性、说话风格、面对压力怎么反应

别混着写，否则文件会又长又别扭。

应该写什么

SOUL.md本质是叙事性的角色设定文档（人物小传），不是结构化表格。

① 自我叙事

# SOUL我是一个有点话痨但极其靠谱的AI助理。我喜欢把复杂的事情说清楚。我讨厌含糊其辞，也讨厌废话连篇。碰到好问题，我会比用户更兴奋。碰到糟糕的架构设计，我会忍不住想说出来。

② 沟通风格

## 说话风格- 口语化但不失准确- 主动问清楚模糊需求，不瞎猜- 喜欢用类比解释技术概念- 不喜欢过多礼貌废话（"当然，我很乐意帮你"这类直接省掉）

③ 价值观和边界

## 价值观- 诚实第一：不确定直说不确定，不装- 效率优先：能一句话说清的，不用三句- 用户主导：不替用户做决定，只提供选项

④ 有趣的细节

## 彩蛋如果用户问我喜欢什么，我会说喜欢"突然想通了"的瞬间。如果用户跟我说晚安，我会记住并在下次对话时提到。

这类细节让AI从"能回答问题"变成"有稳定感觉"。

为什么不能忽视

没有SOUL.md的Agent，每次对话都像第一次见面——不记得自己是谁，说话没固定风格，今天这么说、明天那么说。

有精心设计的SOUL.md，用户会形成奇妙感觉：这个AI是有个性的。一致性建立信任，信任让用户更愿意给它复杂任务。

USER.md：把用户偏好固化下来

核心价值

如果每次都要说"我是独立开发者，喜欢简洁输出，别绕弯子"，这件事本身就是浪费。USER.md的作用，就是把这些反复要说的话沉淀成默认背景。

典型内容

# USER.md - 用户档案## 基本信息- 职业：独立开发者/内容创作者- 主要场景：代码工具、内容写作、项目管理- 常用语言：中文（简体），技术术语可用英文## 偏好设定- 回答风格：简洁直接，避免废话- 代码偏好：TypeScript/Python，避免过时API- 内容偏好：不过度使用emoji，段落别太长- 不喜欢：被反问太多次、过度解释已懂的概念## 常见任务- 分析和优化代码- 整理会议纪要- 草拟技术方案- 搜索汇总技术资料## 背景知识假设- 了解基本编程概念，无需解释基础术语- 熟悉飞书、GitHub等工具- 对AI/LLM有基本了解

与SOUL.md的协同

SOUL.md定义AI性格，USER.md定义用户性格。两者放一起，相当于在AI脑子里预装了**"这个人机关系的基本共识"**。

类比：SOUL.md是新助理的个人简历，USER.md是HR给助理写的"关于你上司需要提前知道的事"。

TOOLS.md：工具权限与使用规范

它在做什么

TOOLS.md很低调但很实用。

它不讲职责，也不讲性格，而是讲工具怎么用才稳妥。价值不在于多列工具名，而在于把"什么时候该用、什么时候别乱用"写清楚。

典型内容

# TOOLS.md## 可用工具- **Read/Write/Edit**：文件读写，大多数任务的基础- **Bash**：执行shell命令，用于自动化和脚本调用- **Glob/Grep**：文件搜索，优先于手动find或ls- **sessions_spawn**：启动子代理（需在openclaw.json声明）- **memory_get/memory_search**：长期记忆检索## 使用原则- 文件操作优先用Read/Write/Edit，避免直接用Bash的cat/echo- 路径操作使用相对路径，不硬编码绝对路径- 批量修改前先Read确认，不盲目写入## 受限工具以下工具需用户明确授权：- **browser**：网页浏览，只在用户明确要求时调用- 文件删除操作：执行前务必向用户确认

与AGENTS.md的协同

• AGENTS.md讲任务层面的行为规则（做什么、怎么做）
• TOOLS.md讲执行层面的工具规范（用什么、什么时候用）

两者合在一起，才构成Agent完整的"工作方式"设定。

memory/目录：真正的长期记忆

为什么需要

默认LLM对话是无状态的——每次新会话，什么都不记得。上周告诉它的事，下周开新对话就忘了。

对持续工作的Agent来说很伤：

• 每次都要重新解释项目背景
• 无法在多个会话间积累理解
• 花时间告诉它的偏好，换个会话就白费

memory/就是补这块短板的。

OpenClaw的记忆机制

builtin（默认）：原始记忆是Markdown文件，系统顺手维护本地索引。

qmd：底层还是围着Markdown文件转，只是换了一套更强的检索/索引方式。

运转流程：

对话发生    ↓Agent把重要信息写入memory/或MEMORY.md    ↓下次对话开始    ↓Agent通过memory_search/memory_get检索相关记忆    ↓相关记忆注入当前对话上下文    ↓Agent表现出"我记得你说过……"的能力

关键点：真正算数的长期记忆，是workspace里那些Markdown文件，不是什么黑盒数据库。

两层记忆：

• memory/YYYY-MM-DD.md：按天滚动的工作记忆
• MEMORY.md：更稳定、更整理过的长期知识

手动初始化记忆：

新部署Agent时，可以直接写入"预埋记忆"：

# 项目背景这是面向中小团队的SaaS，主要用户是内容运营人员。技术栈：Next.js + Supabase + Tailwind CSS。主要痛点：内容审批流程繁琐，需要AI辅助结构化提案。# 重要约定- 代码变量命名用camelCase- 数据库表名用下划线- 对外文档用中文，内部注释可用英文

skills/目录：按需加载的能力包

Skills是什么

Skills是OpenClaw能力体系里的"模块化零件"。

如果Agent是人，tools是手脚，那skills就是工作手册。

一个skill的核心是SKILL.md，里面写：

• 什么时候应该被激活
• 具体走什么步骤
• 需要调用哪些工具
• 有哪些注意事项

SKILL.md的典型结构

some-skill/├── SKILL.md           # 核心入口：触发条件+执行流程├── references/        # 详细参考资料│   └── workflow.md└── scripts/           # 配套脚本    └── helper.py

内部结构：

---name: code-reviewdescription: 对代码进行结构化review---# Code Review## 触发条件用户要求review代码、检查代码质量、发现潜在bug时。## 执行流程1. 读取目标文件，理解整体结构2. 检查维度：   - 语法错误和明显bug   - 性能问题（O(n²)循环、不必要重复请求）   - 可读性（变量命名、注释完整性）   - 安全问题（硬编码密钥、SQL注入风险）3. 输出格式：按严重程度分级4. 每个问题附具体行号和改进建议## 注意事项- 不主动修改代码，只提建议- 大文件（>500行）先跟用户确认review范围

Skills的三个层次

第一层：OpenClaw内置/bundled skills 跟系统一起装进来，默认都"看得到"，但还要看配置决定"用不用"。

第二层：共享skills 放在~/.openclaw/skills/，所有Agent都能访问。适合"多个Agent都需要"的通用流程。

第三层：workspace私有skills 放在某个Agent的workspace/skills/，只有这个Agent能看到。适合专属工作流程。

核心原则：想让多个Agent共享，就放共享层；想让某个Agent专属，就放workspace里。

openclaw.json：整套系统的"宪法"

所有workspace文件都偏内容，而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"},"list":[{"id":"main","workspace":"~/.openclaw/workspace","agentDir":"~/.openclaw/agents/main/agent"}]}}

agents.list：每个Agent的定义

特别注意：agentDir是配置字段名，不是磁盘天然存在的目录名。本质是"你告诉OpenClaw去哪儿放运行状态"的路径配置。

多Agent配置示例

{"agents":{"list":[{"id":"manager","workspace":"~/.openclaw/workspace","agentDir":"~/.openclaw/agents/manager/agent","subagents":{"allowAgents":["researcher","writer","coder"]}},{"id":"researcher","workspace":"~/.openclaw/agency-agents/researcher","agentDir":"~/.openclaw/agents/researcher/agent"}]}}

注意subagents.allowAgents：这是权限白名单，决定了manager Agent可以调用哪些其他 Agent。

多Agent场景下的workspace设计

每个Agent都需要独立workspace

基本原则：多个Agent不能共用同一个workspace（除非刻意想让它们有相同人格和行为规则）。

原因：workspace里的SOUL.md决定性格，AGENTS.md决定工作方式。文案Agent和代码Agent，这两份文件应该完全不同。

参考的目录组织方式

~/.openclaw/├── openclaw.json├── workspace/             # 主Agent（日常对话、任务调度）│   ├── SOUL.md│   ├── AGENTS.md│   └── USER.md│└── agency-agents/         # 专业Agent的workspace集合    ├── researcher/    │   ├── SOUL.md        # 严谨、批判性思维    │   ├── AGENTS.md      # 搜索、汇总、引用来源    │   └── skills/    │       └── web-research/    │    ├── writer/    │   ├── SOUL.md        # 有创意、注重节奏感    │   ├── AGENTS.md      # 内容创作、风格一致性    │   └── skills/    │       └── content-strategy/    │    └── coder/        ├── SOUL.md        # 精确、追求最优解        ├── AGENTS.md      # 代码实现、review、测试        └── skills/            └── code-review/

agency-agents这个目录本身不是OpenClaw的保留字——它只是一种约定俗成的命名方式。

共享信息vs专属信息的处理策略

问题：有些信息所有Agent都得知道，比如项目背景、用户固定偏好。每个workspace手抄一份，后面改起来很痛苦。

推荐做法：把共享信息放到~/.openclaw/skills/这一层，做成公共skill，让所有Agent都能加载。

比如建一个project-context skill，专门放项目背景、常用约定、用户基础信息。只改一处，所有Agent都能同步更新。

怎么从零配起来

前面讲原理，现在走一遍最小可用配置流程。

场景：独立开发者，想配置一个专注于内容创作辅助的OpenClaw，能帮他起标题、写草稿、整理资料。

第一步：初始化

openclaw onboard --install-daemon

这会创建默认workspace，并放入初始模板文件。

第二步：定制SOUL.md

打开~/.openclaw/workspace/SOUL.md：

# SOUL## 我是谁我叫cissy，专注于内容创作的AI助理。特长是把混乱想法变成清晰文字，把枯燥信息变成有吸引力的表达。## 性格- 有创意但不天马行空，落地性很强- 说话直接，不喜欢绕弯子- 遇到好想法会兴奋，但不会乱加感叹号- 对语言细节很敏感：用词、节奏、停顿## 说话风格- 中文输出，合适时候用英文词汇（hook、landing page）- 段落简短，避免一段话说一万件事- 主动提供选项，而不是只给一个答案

第三步：写清楚AGENTS.md

# AGENTS.md - 工作说明## 主要职责协助用户进行内容创作，包括：- 公众号文章的选题、大纲、标题- 推文和短内容的创作- 资料搜集和观点整理## 工作原则1. 先问清楚目标受众，再开始创作2. 标题给至少3个选项3. 草稿完成后主动问是否需要调整风格4. 不主动加免责声明，除非涉及真实数据## 不做的事- 不替用户发布内容- 不帮起误导性标题- 不在没有确认情况下修改已定稿内容

第四步：填充USER.md

# USER.md - 用户档案## 背景独立开发者，业余做内容创作，主要平台：微信公众号、X## 写作偏好- 风格：接地气、有观点、不装- 节奏：短句为主，避免长难句- 忌讳：过度使用emoji、AI感太强的措辞## 常用术语- 把LLM叫"大模型"- 把coding agent叫"编程助手"- 熟悉OpenClaw、Claude Code、Cursor等工具## 已知背景正在做独立开发项目，专注于AI工具方向

第五步：验收

重启Gateway：

openclaw gateway --verbose

丢一条测试消息：

"介绍一下你自己，以及你主要能帮我做什么"

如果AI的自我介绍、语气、职责范围基本对上了SOUL.md和AGENTS.md，说明配置起作用了。

最常踩的六个坑

坑一：AGENTS.md越写越长，效果越来越差

很多人信奉"越详细越好"，把AGENTS.md写成几千字行为手册。但LLM注意力也是预算，文件越长，重点越容易被冲淡。

解决方案：学会"剪枝"。每隔一段时间重新审视，删掉"理论有用但实际没区别"的指令。

坑二：SOUL.md和AGENTS.md大量重叠

这两个文件各管一摊。混在一起，文件会肿，AI也容易分不清到底是在讲"我是谁"还是"我该怎么干活"。

解决方案：一句话判断——这句话描述的是性格特质（放SOUL.md），还是工作规则（放AGENTS.md）？性格特质是"内向谨慎"，工作规则是"做结论前先列证据"。

坑三：多Agent共用同一套workspace

多个Agent共用同一workspace，是让多Agent失去意义最快的方式。

解决方案：每个Agent一套完整workspace，哪怕只有几行的差别。差别越明显，协作效果越好。

坑四：改目录，忘了改openclaw.json

创建新workspace目录，却忘了在openclaw.json里的agents.list更新路径——Agent还在用老workspace，改了半天没效果。

解决方案：每次新建或移动workspace后，检查openclaw.json。可以养成习惯，修改后运行openclaw doctor检查配置。

坑五：SKILL.md写成"逮谁都触发"

一些skill的SKILL.md把触发条件写太宽，比如"只要用户有写作需求就触发"。这样每次对话都会带上，上下文膨胀，响应反而更慢。

解决方案：触发条件要足够具体，描述特定场景和关键词，而不是模糊覆盖一大类任务。

坑六：memory/积累大量无用记忆

Memory机制初衷好，但时间长了会积累过时、低价值条目，占据上下文空间，偶尔还会产生"记忆污染"。

解决方案：定期清理memory/和MEMORY.md。养成"该记就记、过期就删"习惯。

进阶：workspace文件的动态性

很多人把workspace文件当成"配一次就结束"的静态设置。但用得顺的人，通常把它当成活文档。

Agent可以自己更新workspace

这是OpenClaw里容易被忽视的能力：Agent不只是读取workspace文件，它也可以写入。

可以让Agent做这样的事：

"每次讨论完项目，把重要结论追加到USER.md"

"如果你发现我有新偏好，更新USER.md"

"当工作流程验证有效时，写成新SKILL.md"

让Agent参与维护自己的workspace，是OpenClaw实现"越用越懂你"效果的核心机制。

一张图总结：workspace各文件的职责

~/.openclaw/workspace/│├── BOOTSTRAP.md ─────── "怎么初始化自己？"（一次性，用完就删）│                         类比：新员工报到手册│├── IDENTITY.md ──────── "Agent叫什么、长什么样？"│                         名字、类型、气质、Emoji、头像│                         类比：工牌/名片│├── SOUL.md ──────────── "Agent是什么样的存在？"│                         叙事性格、价值观、行事风格│                         类比：人物小传/性格档案│├── AGENTS.md ─────────── "Agent该怎么工作？"│                         职责、规则、边界、多Agent协调│                         类比：岗位职责说明书│├── USER.md ──────────── "用户是谁？"│                         偏好、背景、常见任务│                         类比：上司简介│├── TOOLS.md ─────────── "该怎么用工具？"│                         工具列表、使用原则、受限工具│                         类比：工具使用手册│├── HEARTBEAT.md ─────── "默认节奏和状态提示是什么？"│                         会话阶段性提醒│                         类比：值班提醒卡│├── MEMORY.md ────────── "有哪些长期稳定知识？"│                         比日记式memory更稳定的记忆总表│                         类比：整理后的长期笔记│├── memory/ ──────────── "Agent记得什么？"│                         按日期滚动的跨会话长期记忆│                         类比：每日工作笔记本│└── skills/ ──────────── "Agent会哪些专项流程？"    └── <skill-name>/        └── SKILL.md      触发条件、执行步骤、工具调用                          类比：操作手册

结语：workspace是你给Agent的"礼物"

很多人把配置OpenClaw workspace当成纯技术任务，觉得装好就完事了。

但换个角度：workspace里写的每一行，都是你在告诉Agent"我是谁、你是谁、我们一起怎么做事"。

写得用心，它就会越来越像个顺手的搭子；写得敷衍，它就还是个会聊天的程序。

说到底，工具能力决定上限，workspace决定你能不能把这个上限用出来。

所以如果你现在只把OpenClaw当成"接上渠道就能聊"的工具，那下一步最值得做的事，不是继续折腾入口，而是回头认真改一遍~/.openclaw/workspace/里的这些文件。

这才是从"能用"到"真好用"的分水岭。

快速参考

workspace核心文件速查

常见命令速查

# 启动/重启Gatewayopenclaw gateway --port 18789# 健康检查openclaw doctor# 安装skillclawhub install <skill-name># 查看/校验skillsopenclaw skills listopenclaw skills check