1
0

OpenClaw🦞 从"能用"到"好用"

2026-05-10

导语:在 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 的性格档案

文件

侧重点

内容类型

AGENTS.md

功能性

做什么、怎么做、优先级

SOUL.md

人格性

是谁、什么风格、怎么反应

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 的协同

文件

层面

类比

AGENTS.md

任务层面

岗位职责和规则

TOOLS.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 表现出"我记得你说过……"的能力

两层记忆结构

层级

文件

用途

工作记忆

memory/YYYY-MM-DD.md

按天滚动的原始记录

长期知识

MEMORY.md

整理后的稳定知识


八、skills/ 目录:按需加载的能力包

Skills 是什么

Skills 可以理解成 OpenClaw 能力体系里的**"模块化零件"**。如果说 Agent 是一个人,tools 是它的手脚,那 skills 就是它的工作手册。

SKILL.md 的典型结构

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

Skills 的三个层次

  1. 内置 skills:跟系统一起装进来的

  2. 共享 skills:放在 ~/.openclaw/skills/,所有 Agent 都能访问

  3. 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 字段说明

字段

含义

示例

id

Agent 的唯一标识

"main" / "seo-specialist"

workspace

工作区目录路径

"~/.openclaw/workspace"

agentDir

运行状态目录路径

"~/.openclaw/agents/main/agent"


十、多 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

然后测试:"介绍一下你自己,以及你主要能帮我做什么"


十二、最常踩的六个坑

问题

解决方案

坑一

AGENTS.md 越写越长

学会"剪枝",300-500字最佳

坑二

SOUL.md 和 AGENTS.md 重叠

性格特质放 SOUL,工作规则放 AGENTS

坑三

多 Agent 共用 workspace

每个 Agent 一套完整 workspace

坑四

改了目录,忘了改 openclaw.json

每次修改后运行 openclaw doctor

坑五

SKILL.md 触发条件太宽

描述清楚特定场景和关键词

坑六

memory/ 积累大量无用记忆

定期清理,该记就记、过期就删


十三、一张图总结: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 官方文档及社区最佳实践整理,转载请注明出处。

评论