夜雨聆风
OpenClaw Workspace 深度解析：从"能用"到"真好用"的分水岭
在 OpenClaw 的使用者里，有一条隐形的分界线。
一边的人，每次跟 Agent 说话都像重新 onboarding——得再讲一遍背景、偏好和上下文。另一边的人，Agent 已经知道自己是谁、该怎么说话、用户讨厌什么，也记得上次积累下来的东西。
这条分界线，叫 workspace。
很多人只顾着把系统跑通，却没认真写内容层，结果就是 Agent 能启动，但不好用。这篇就一个目标：把 workspace 里的每个文件拆开，说清楚它管什么、怎么写、最容易踩什么坑。
先看全景：workspace 里到底有什么？
先别急着一个文件一个文件抠。先把整套目录摆出来，脑子里有张地图，后面就不容易乱。
你可以把整个 workspace 想象成一张办公桌——桌上摆的每样东西，都在告诉 Agent「你是谁、帮谁干活、怎么干活」。
而 openclaw.json 是 HR 系统，负责把这张桌分配给对的人、接上对的线路。桌上的东西管内容，HR 系统管调度。两者别混。
第一层：三个定义"人设"的文件
AGENTS.md —— 岗位说明书
它回答的问题很直接：这个 Agent 做什么、不做什么、遇到什么情况走什么流程。
但最容易写错的地方恰恰是：只写了"做什么"，没写"不做什么"。
LLM 默认会"发挥创意"，而你需要的是可预测的行为。边界往往比能力描述更重要。
三条配置原则：
- 写清边界
——"不要主动修改已定稿的内容"比"帮我做内容创作"有用十倍。 - 场景触发优于通用指令
——与其写"始终保持专业语气"，不如写"技术问题用专业措辞，闲聊可以轻松"。后者更具操作性。 - 300-500 字比 2000 字更有效
——文件越长，重点越容易被冲淡。重要的放前面，次要的删掉，不要"保险起见什么都写上"。
SOUL.md —— 人物小传
如果 AGENTS.md 是岗位说明书，SOUL.md 就是性格档案。
两者的区别在于：AGENTS.md 偏功能——做什么、怎么做；SOUL.md 偏人格——是谁、什么风格、面对压力怎么反应。这两个东西最好别混着写， 不然文件会又长又别扭，像把公司的规章制度和一个人的自我介绍塞进同一页纸里。
一个好的 SOUL.md 通常包含四块：
- 自我叙事
——"我是一个有点话痨但极其靠谱的 AI 助理" - 沟通风格
——"口语化但不失准确，不喜欢过多礼貌性废话" - 价值观和边界
——"不确定的事情直说不确定，不装" - 有趣的细节（可选但推荐）
——"如果用户跟我说晚安，我会记住并在下次提到"
这类细节看起来不大，却很容易让 Agent 从"能回答问题"变成"有稳定感觉"。
一个没有 SOUL.md 的 Agent，每次对话都像第一次见面。 它不记得自己是谁，说话没有固定风格，今天这么说、明天那么说。而一个有 SOUL.md 的 Agent，用户会形成一种奇妙的感觉：这个 AI 是有个性的。一致性建立信任，信任让用户愿意给它更复杂的任务。
USER.md —— 上司简介
如果每次对话都要重新说一遍"我是独立开发者，喜欢简洁输出，别跟我绕弯子"，那这件事本身就是浪费。USER.md 就是把这些反复要说的话沉淀成默认背景。
职业、使用场景、回答风格、代码偏好、忌讳项、背景知识假设——写进去之后，Agent 就不再需要你每次口头交代。
用一个类比来说：SOUL.md 是新来的助理的个人简历，USER.md 是 HR 给这位助理写的"关于你的上司，你需要提前知道的事"。两者都读完了，第一天上班才不会尴尬。
第二层：两个管"怎么执行"的文件
TOOLS.md —— 工具使用手册
它和 AGENTS.md、SOUL.md 不一样，不讲职责也不讲性格，而是讲工具怎么用才稳妥。
价值不在于多列几个工具名，而在于把"什么时候该用，什么时候别乱用"写清楚。比如：文件操作优先用 Read/Write，避免直接用 Bash 的 cat/echo；文件删除执行前务必向用户确认。
它和 openclaw.json 的 tools 配置形成两道关：
- openclaw.json 决定底层放没放行
——能不能用 - TOOLS.md 决定既然能用，该怎么用才稳妥
——该不该用
TOOLS.md 不会凭空给 Agent 加权限，但它会明显影响 Agent 在"有权限"的前提下怎么出手。
IDENTITY.md —— 工牌
如果 SOUL.md 是人物小传，IDENTITY.md 就是名片。几个结构化字段：Name、Creature、Vibe、Emoji、Avatar。看起来简单，但名字会影响显示，Emoji 会在 UI 里作为标识符出现。
分工很清楚：IDENTITY.md 管"叫什么、长什么样"，SOUL.md 管"怎么思考、怎么行事"。
第三层：记忆系统——让 Agent 跨会话"记住你"
LLM 默认无状态——新开会话什么都不记得。一次性任务问题不大，但对持续工作的 Agent 来说很伤：每次都要重新解释项目背景，花时间告诉它的偏好换个会话就白费了。
memory/ 目录就是补这块短板的。
两层记忆
memory/YYYY-MM-DD.md：按天滚动的工作记忆，像每日工作笔记
MEMORY.md：更稳定、更整理过的长期知识，像精炼后的长期笔记本
Agent 通过 memory_search / memory_get 在新会话中检索相关记忆，注入上下文，表现出"我记得你说过……"的能力。
最关键的一点其实很朴素： 真正算数的长期记忆是 workspace 里那些 Markdown 文件，不是什么看不见摸不着的黑盒数据库。如果你真想让它记住什么，就写到文件里。
你也可以手动往 memory/ 里预埋初始信息——项目背景、技术栈、命名约定——让 Agent 从第一次对话就不是一无所知。
第四层：Skills——按需加载的能力包
如果 Agent 是一个人，tools 是它的手脚，那 skills 就是它的操作手册。
一个 skill 的核心是 SKILL.md，定义触发条件、执行步骤、注意事项。不是"逮谁都触发"的通用指令，而是针对特定场景的专项流程。
三个层次
想共享就放共享层，想专属就放私有目录。 不要把需要共享的 skill 只放在某个 Agent 的私有目录里，然后疑惑"为什么其他 Agent 用不到"。
第五层：openclaw.json——HR 系统
所有 workspace 文件都偏内容，而 openclaw.json 负责把这些内容接上线、接到对的位置。
agents.list 里每个 Agent 至少得有一个 id；workspace 和 agentDir 可以自己写死，也可以让 OpenClaw 按默认规则补。
OpenClaw 认的是这份配置，不是目录名字长什么样。 你把 workspace 放在 /home/my-cool-agents/bob/ 也完全可以，只要配置里写对了路径。
多 Agent 场景中，每个 Agent 需要独立 workspace。共用 workspace = 失去分工意义。共享信息（项目背景、用户偏好）做成公共 skill 放 ~/.openclaw/skills/，改一处全局同步。
最容易踩的六个坑
坑一：AGENTS.md 越写越长，效果越来越差LLM 的注意力也是预算。解法：定期剪枝，关键规则放前面，300-500 字 > 2000 字。
坑二：SOUL.md 和 AGENTS.md 大量重叠一句话判断法——描述的是性格特质（→SOUL.md）还是工作规则（→AGENTS.md）？"内向谨慎"是性格，"做出结论前先列证据"是规则。
坑三：多 Agent 共用同一套 workspace研究员和写手连 SOUL.md 都一样，分工就成了摆设。每个 Agent 一套完整 workspace，哪怕只有几行差别。
坑四：改了目录，忘了改 openclaw.json改了半天没效果——因为 Agent 还在用老的 workspace。每次改完跑一遍 openclaw doctor。
坑五：SKILL.md 触发条件太宽"只要用户有写作需求就触发"≈ 每次对话都触发 ≈ 上下文膨胀。触发条件要具体到场景和关键词。
坑六：memory/ 堆积无用记忆两个月前过时的信息还在被引用 = 记忆污染。定期清理，该记就记，过期就删。
进阶：workspace 不是配一次就完事的静态设置
Agent 可以自己更新 workspace。 这是"越用越懂你"的核心机制：让它把新偏好写入 USER.md、把验证有效的流程写成新 SKILL.md、把重要结论追加到记忆里。
用 Git 管理 workspace。 SOUL.md 改偏了往往不是立刻发现，而是过几轮对话才觉得"它怎么突然不对劲了"。有版本记录就能快速回滚。
工具能力决定上限，workspace 决定你能不能把上限用出来。
与其继续折腾入口，不如回头认真改一遍 ~/.openclaw/workspace/ 里的这些文件。
OpenClaw Workspace 深度解析：从"能用"到"真好用"的分水岭
在 OpenClaw 的使用者里，有一条隐形的分界线。
一边的人，每次跟 Agent 说话都像重新 onboarding——得再讲一遍背景、偏好和上下文。另一边的人，Agent 已经知道自己是谁、该怎么说话、用户讨厌什么，也记得上次积累下来的东西。
这条分界线，叫 workspace。
这条分界线，叫 workspace。
很多人只顾着把系统跑通，却没认真写内容层，结果就是 Agent 能启动，但不好用。这篇就一个目标：把 workspace 里的每个文件拆开，说清楚它管什么、怎么写、最容易踩什么坑。
先看全景：workspace 里到底有什么？
先别急着一个文件一个文件抠。先把整套目录摆出来，脑子里有张地图，后面就不容易乱。
你可以把整个 workspace 想象成一张办公桌——桌上摆的每样东西，都在告诉 Agent「你是谁、帮谁干活、怎么干活」。
而 openclaw.json 是 HR 系统，负责把这张桌分配给对的人、接上对的线路。桌上的东西管内容，HR 系统管调度。两者别混。
第一层：三个定义"人设"的文件
AGENTS.md —— 岗位说明书
它回答的问题很直接：这个 Agent 做什么、不做什么、遇到什么情况走什么流程。
但最容易写错的地方恰恰是：只写了"做什么"，没写"不做什么"。
LLM 默认会"发挥创意"，而你需要的是可预测的行为。边界往往比能力描述更重要。
三条配置原则：
- 写清边界
——"不要主动修改已定稿的内容"比"帮我做内容创作"有用十倍。 - 场景触发优于通用指令
——与其写"始终保持专业语气"，不如写"技术问题用专业措辞，闲聊可以轻松"。后者更具操作性。 - 300-500 字比 2000 字更有效
——文件越长，重点越容易被冲淡。重要的放前面，次要的删掉，不要"保险起见什么都写上"。
- 写清边界
——"不要主动修改已定稿的内容"比"帮我做内容创作"有用十倍。 - 场景触发优于通用指令
——与其写"始终保持专业语气"，不如写"技术问题用专业措辞，闲聊可以轻松"。后者更具操作性。 - 300-500 字比 2000 字更有效
——文件越长，重点越容易被冲淡。重要的放前面，次要的删掉，不要"保险起见什么都写上"。
SOUL.md —— 人物小传
如果 AGENTS.md 是岗位说明书，SOUL.md 就是性格档案。
两者的区别在于：AGENTS.md 偏功能——做什么、怎么做；SOUL.md 偏人格——是谁、什么风格、面对压力怎么反应。这两个东西最好别混着写， 不然文件会又长又别扭，像把公司的规章制度和一个人的自我介绍塞进同一页纸里。
一个好的 SOUL.md 通常包含四块：
- 自我叙事
——"我是一个有点话痨但极其靠谱的 AI 助理" - 沟通风格
——"口语化但不失准确，不喜欢过多礼貌性废话" - 价值观和边界
——"不确定的事情直说不确定，不装" - 有趣的细节（可选但推荐）
——"如果用户跟我说晚安，我会记住并在下次提到"
这类细节看起来不大，却很容易让 Agent 从"能回答问题"变成"有稳定感觉"。
一个没有 SOUL.md 的 Agent，每次对话都像第一次见面。 它不记得自己是谁，说话没有固定风格，今天这么说、明天那么说。而一个有 SOUL.md 的 Agent，用户会形成一种奇妙的感觉：这个 AI 是有个性的。一致性建立信任，信任让用户愿意给它更复杂的任务。
USER.md —— 上司简介
如果每次对话都要重新说一遍"我是独立开发者，喜欢简洁输出，别跟我绕弯子"，那这件事本身就是浪费。USER.md 就是把这些反复要说的话沉淀成默认背景。
职业、使用场景、回答风格、代码偏好、忌讳项、背景知识假设——写进去之后，Agent 就不再需要你每次口头交代。
用一个类比来说：SOUL.md 是新来的助理的个人简历，USER.md 是 HR 给这位助理写的"关于你的上司，你需要提前知道的事"。两者都读完了，第一天上班才不会尴尬。
第二层：两个管"怎么执行"的文件
TOOLS.md —— 工具使用手册
它和 AGENTS.md、SOUL.md 不一样，不讲职责也不讲性格，而是讲工具怎么用才稳妥。
价值不在于多列几个工具名，而在于把"什么时候该用，什么时候别乱用"写清楚。比如：文件操作优先用 Read/Write，避免直接用 Bash 的 cat/echo；文件删除执行前务必向用户确认。
它和 openclaw.json 的 tools 配置形成两道关：
- openclaw.json 决定底层放没放行
——能不能用 - TOOLS.md 决定既然能用，该怎么用才稳妥
——该不该用
TOOLS.md 不会凭空给 Agent 加权限，但它会明显影响 Agent 在"有权限"的前提下怎么出手。
IDENTITY.md —— 工牌
如果 SOUL.md 是人物小传，IDENTITY.md 就是名片。几个结构化字段：Name、Creature、Vibe、Emoji、Avatar。看起来简单，但名字会影响显示，Emoji 会在 UI 里作为标识符出现。
分工很清楚：IDENTITY.md 管"叫什么、长什么样"，SOUL.md 管"怎么思考、怎么行事"。
第三层：记忆系统——让 Agent 跨会话"记住你"
LLM 默认无状态——新开会话什么都不记得。一次性任务问题不大，但对持续工作的 Agent 来说很伤：每次都要重新解释项目背景，花时间告诉它的偏好换个会话就白费了。
memory/ 目录就是补这块短板的。
两层记忆
memory/YYYY-MM-DD.md：按天滚动的工作记忆，像每日工作笔记
MEMORY.md：更稳定、更整理过的长期知识，像精炼后的长期笔记本
Agent 通过 memory_search / memory_get 在新会话中检索相关记忆，注入上下文，表现出"我记得你说过……"的能力。
最关键的一点其实很朴素： 真正算数的长期记忆是 workspace 里那些 Markdown 文件，不是什么看不见摸不着的黑盒数据库。如果你真想让它记住什么，就写到文件里。
你也可以手动往 memory/ 里预埋初始信息——项目背景、技术栈、命名约定——让 Agent 从第一次对话就不是一无所知。
第四层：Skills——按需加载的能力包
如果 Agent 是一个人，tools 是它的手脚，那 skills 就是它的操作手册。
一个 skill 的核心是 SKILL.md，定义触发条件、执行步骤、注意事项。不是"逮谁都触发"的通用指令，而是针对特定场景的专项流程。
三个层次
想共享就放共享层，想专属就放私有目录。 不要把需要共享的 skill 只放在某个 Agent 的私有目录里，然后疑惑"为什么其他 Agent 用不到"。
第五层：openclaw.json——HR 系统
所有 workspace 文件都偏内容，而 openclaw.json 负责把这些内容接上线、接到对的位置。
agents.list 里每个 Agent 至少得有一个 id；workspace 和 agentDir 可以自己写死，也可以让 OpenClaw 按默认规则补。
OpenClaw 认的是这份配置，不是目录名字长什么样。 你把 workspace 放在 /home/my-cool-agents/bob/ 也完全可以，只要配置里写对了路径。
多 Agent 场景中，每个 Agent 需要独立 workspace。共用 workspace = 失去分工意义。共享信息（项目背景、用户偏好）做成公共 skill 放 ~/.openclaw/skills/，改一处全局同步。
最容易踩的六个坑
坑一：AGENTS.md 越写越长，效果越来越差LLM 的注意力也是预算。解法：定期剪枝，关键规则放前面，300-500 字 > 2000 字。
坑二：SOUL.md 和 AGENTS.md 大量重叠一句话判断法——描述的是性格特质（→SOUL.md）还是工作规则（→AGENTS.md）？"内向谨慎"是性格，"做出结论前先列证据"是规则。
坑三：多 Agent 共用同一套 workspace研究员和写手连 SOUL.md 都一样，分工就成了摆设。每个 Agent 一套完整 workspace，哪怕只有几行差别。
坑四：改了目录，忘了改 openclaw.json改了半天没效果——因为 Agent 还在用老的 workspace。每次改完跑一遍 openclaw doctor。
坑五：SKILL.md 触发条件太宽"只要用户有写作需求就触发"≈ 每次对话都触发 ≈ 上下文膨胀。触发条件要具体到场景和关键词。
坑六：memory/ 堆积无用记忆两个月前过时的信息还在被引用 = 记忆污染。定期清理，该记就记，过期就删。
进阶：workspace 不是配一次就完事的静态设置
Agent 可以自己更新 workspace。 这是"越用越懂你"的核心机制：让它把新偏好写入 USER.md、把验证有效的流程写成新 SKILL.md、把重要结论追加到记忆里。
用 Git 管理 workspace。 SOUL.md 改偏了往往不是立刻发现，而是过几轮对话才觉得"它怎么突然不对劲了"。有版本记录就能快速回滚。
工具能力决定上限，workspace 决定你能不能把上限用出来。
与其继续折腾入口，不如回头认真改一遍 ~/.openclaw/workspace/ 里的这些文件。
