前言
龙虾上手已经两月了，期间经历了无数次了重装、修复、踩坑、调整等操作，针对龙虾的Workspace目录总结一直没来及记录，今天让龙虾协助我来完善🦞，防止后续 因为新鲜感过了后，再捡起来一脸懵😂
Workspace
在 OpenClaw 的使用中，存在一条隐形的分界线。一边是每次对话都像重新入职的“新手” Agent；另一边是懂你偏好、有稳定性格的“熟手” Agent。这条分界线就是 Workspace。
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/ # openclaw.json 里的 agentDir 默认就指到这里
│ ├── auth-profiles.json
│ └── models.json
├── sessions/ # 会话历史
│ └── *.jsonl
└── qmd/ # 仅在 qmd memory backend 下出现
🗺️ Workspace 核心文件职责地图
理解这些文件的分工，是配置好 Agent 的第一步。我们可以将它们类比为现实工作中的不同文档。
| 文件名 | 核心职责 | 形象类比 | 关键说明 |
|---|---|---|---|
BOOTSTRAP.md | 首次启动向导 | 新员工报到手册 | 初始化后通常删除，使命是引导配置。 |
IDENTITY.md | 身份元数据 | 工牌/名片 | 定义名字、Emoji、头像和基本气质。 |
SOUL.md | 叙事性格设定 | 人物小传 | 决定 Agent 是谁、价值观、说话风格。 |
AGENTS.md | 行为规则与职责 | 岗位说明书 | 定义能做什么、边界在哪、多 Agent 协作。 |
USER.md | 用户画像 | 上司简介 | 记录用户的背景、偏好、职业和常用工具。 |
TOOLS.md | 工具使用规范 | 工具手册 | 规定工具的使用原则、优先级和受限操作。 |
HEARTBEAT.md | 会话节奏/状态 | 值班提醒卡 | 控制默认的提示频率和状态检查逻辑。 |
MEMORY.md | 长期知识总表 | 整理后的笔记 | 存放高价值、可复用的长期记忆（非每日）。 |
memory/ | 按日滚动记忆 | 工作笔记本 | 按日期记录的原始对话和上下文记忆。 |
skills/ | 专项技能包 | 操作手册 | 模块化的任务流程（如代码审查、调研）。 |
🧩 核心文件深度解析
1. AGENTS.md：岗位说明书
这是最关键的文件之一，但它不是越长越好。
- 核心作用：定义职责、规则、边界和多 Agent 协作逻辑。
避坑指南：
- 边界 > 能力：明确写出“不该做什么”比“能做什么”更重要，防止 LLM 过度发挥。
- 场景触发：优于通用指令。例如“当用户问技术问题时...”比“始终保持专业”更有效。
- 精简为王：300-500 字通常比 2000 字更有效，重点不要被淹没。
2. SOUL.md：性格档案
这是 Agent 的“灵魂”，让它从“程序”变成“搭子”。
与 AGENTS 的区别：
AGENTS.md是功能性的（怎么做工作）。SOUL.md是人格性的（是谁、怎么思考、怎么面对压力）。
- 关键要素：自我叙事、沟通风格（如：讨厌废话）、价值观（如：诚实第一）、有趣的细节（彩蛋）。
3. USER.md：用户偏好固化
不要每次对话都重复交代背景。
- 作用：将用户的背景（如职业、常用语言）、偏好（如回答风格、代码偏好）和常见任务固化下来。
- 协同效应：
SOUL.md（助理性格）+USER.md（老板性格）= 预装了“人机关系共识”。
4. TOOLS.md：工具规范
- 作用：不仅是工具列表，更是使用规范。明确何时该用、何时禁用（如删除操作需确认）。
与配置文件的区别：
openclaw.json决定能不能用（系统层权限）。TOOLS.md决定该不该用（工作层规范）。
5. 记忆机制 (memory/ 与 MEMORY.md)
OpenClaw 的记忆是基于文件的，而非黑盒数据库。
memory/YYYY-MM-DD.md：每日工作记忆，按天滚动。MEMORY.md：长期知识库，需要定期将高价值信息从每日记忆中提炼进去。- 原则：文字比脑内记忆更可靠。想记住什么，就写进文件里。
6. IDENTITY.md 和 BOOTSTRAP.md
两个容易被忽略的官方文件。
IDENTITY.md：Agent 的身份证
如果说 SOUL.md 是 Agent 的性格叙事，那 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 按这套流程先把自己“配齐”。
7.skills/ 目录：按需加载的能力包
Skills 可以理解成 OpenClaw 能力体系里的“模块化零件”。
打个比方：如果说 Agent 是一个人，tools 是它的手脚，那 skills 就是它的工作手册。
一个 skill 的核心是一个叫做 SKILL.md 的文件，里面写的是：
- 触发条件：这个 skill 什么时候应该被激活
- 执行流程：具体要走什么步骤
- 工具依赖：需要调用哪些工具
- 约束与上下文：有哪些注意事项和参考资料
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 范围
在多 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 专属的工作流程。
扫描顺序
- 插件提供的 skill
- 内置 skill
- 托管 skill (~/.openclaw/skills/)
- 个人 skill (~/.agents/skills/)
- 项目 skill ({workspace}/.agents/skills/)
- Workspace skill ({workspace}/skills/)
优先级说明:
Workspace skill > 项目 skill > 个人 skill > 托管 skill > 内置 skill > 插件 skill
⚙️ 多 Agent 场景下的架构
在多 Agent 系统中，Workspace 的设计至关重要：
- 独立性：每个 Agent 应该有独立的 Workspace。研究员和写作者的性格（
SOUL.md）和职责（AGENTS.md）应该完全不同。 - 共享策略：如果多个 Agent 需要共享某些背景信息（如项目背景），建议将其做成公共 Skill 或放在共享目录中，避免重复维护。
多个 Agent 不能共用同一个 workspace（除非你刻意想让它们有相同的人格和行为规则）。原因很简单：workspace 里的 SOUL.md 决定了 Agent 的性格，AGENTS.md 决定了它的工作方式。
一个负责写文案的 Agent 和一个负责写代码的 Agent，这两份文件应该完全不同。如果共用 workspace，它们就失去了分工的意义。
一个可供参考的目录组织方式
~/.openclaw/
├── openclaw.json
├── workspace/ # 主 Agent（日常对话、任务调度）
│ ├── SOUL.md
│ ├── AGENTS.md
│ └── USER.md
│
└── agency-agents/ # 专业 Agent 的 workspace 集合
├── researcher/
│ ├── SOUL.md # 研究员性格：严谨、批判性思维
│ ├── AGENTS.md # 研究员职责：搜索、汇总、引用来源
│ └── skills/
│ └── web-research/
│ └── SKILL.md
│
├── writer/
│ ├── SOUL.md # 写作者性格：有创意、注重节奏感
│ ├── AGENTS.md # 写作者职责：内容创作、风格一致性
│ └── skills/
│ └── content-strategy/
│ └── SKILL.md
│
└── coder/
├── SOUL.md # 工程师性格：精确、追求最优解
├── AGENTS.md # 工程师职责：代码实现、review、测试
└── skills/
└── code-review/
└── SKILL.md
🚀 配置六坑避雷指南
- 📜 文件过长：
AGENTS.md越写越长，重点被冲淡。解法：定期剪枝，保留核心。 - 🔀 职责混淆：
SOUL.md和AGENTS.md内容重叠。解法：性格归性格，工作归工作。 - 👯 共用 Workspace：多个 Agent 共用一套配置，导致分工失效。解法：每个 Agent 独立配置。
- 🔗 路径未更新：改了目录但忘了改
openclaw.json。解法：修改后运行openclaw doctor检查。 - 🎣 触发过宽：Skill 的触发条件太模糊，导致上下文膨胀。解法：写具体场景，精准触发。
- 🗑️ 记忆污染：
memory/积累大量过时信息。解法：定期清理，养成“该记就记、过期就删”的习惯。
💡 进阶思维：动态维护
- 活文档：Workspace 文件不是静态的。允许 Agent 在权限范围内更新
USER.md或MEMORY.md，实现“越用越懂你”。 - 版本管理：建议将 Workspace 目录纳入 Git 管理。一旦改坏，能快速回滚到正常状态。
总结
Workspace 里写的每一行，都是在告诉 Agent “我是谁、你是谁、我们一起怎么做事”。工具决定了上限，而 Workspace 决定了你能否触达这个上限。
PS:
Q：龙虾会根据日常对话自动更新Workspace里面的这些文件吗？
A：会，但不一定，但是我们最好显式提醒它！！！
参考文章：
https://bytedance.larkoffice.com/docx/MFK7dDFLFoVlOGxWCv5cTXKmnMh
https://bytedance.larkoffice.com/docx/MFK7dDFLFoVlOGxWCv5cTXKmnMh
https://mp.weixin.qq.com/s/7GQpp2TzkF6GLeKOuOeF6Q
