前言

        看了很多介绍Openclaw Skills自定义、安装和Skills加载机理的文章，发现除了概念性的记忆，对于Skills的加载机制仍旧很模糊。

        今天在官方网站扒了一番，梳理了一下，从实际场景出发，带你彻底理解 OpenClaw 的目录架构和 Skill 加载机制，看完这篇，相信你对Skills的加载机制就能真正的了然于胸了。以后，你至少能在群里装懂三分钟。

一、核心概念：Agent 与 Workspace

       OpenClaw 的所有配置都围绕1个核心概念展开——Agent ，而要研究Agent，自然离不开它的工作台——Workspace。下面主要从这两个概念进行展开。

Agent 是实际执行任务的 AI 助手。它可以是日常跟你唠嗑的主助手，也可以是专门写代码的 coder、专门写文章的 writer。每个 Agent 都有独立的身份和职责，就像公司里的不同岗位。

Workspace 决定了 Agent 是谁——它的性格、行为规则、可用 Skill 都在这个目录里配置。Workspace 里的 SOUL.md 定义 Agent 的性格（是严肃还是活泼），AGENTS.md 定义行为规则（什么能做什么不能做），skills/ 目录存放可用 Skill（会干什么活）。

核心关系：每个 Agent 绑定一个独立的 workspace。这是实现 Skill 隔离和人格独立的基础。说白了，你不能让一个写代码的 Agent 用写文章的 workspace，就像不能让程序员去干运营的活——虽然都是打工，但技能树不一样。

基于这两个核心概念，我们来看 OpenClaw 的完整目录结构。

二、OpenClaw 完整目录架构

2.1 标准目录结构

以 多Agent协作的场景为例：1 个主 Agent + 2 个子 Agent（coder、writer），完整目录结构长这样：

~/.openclaw/│├── openclaw.json         # 总控配置（定义 Agent ↔ Workspace 绑定）│├── workspace/            # 【工作区 A】主 Agent 专属│   ├── SOUL.md          # 主 Agent 性格设定│   ├── AGENTS.md        # 主 Agent 行为规则│   ├── USER.md          # 用户信息│   ├── skills/          # ★ 主 Agent 专属 Skill│   └── .agents/skills/  # ★ 共用此 workspace 的 Agent 共享│├── coder-agent/          # 【工作区 B】Coder Agent 专属│   ├── SOUL.md          # Coder 性格（严谨、技术范）│   ├── AGENTS.md        # Coder 职责（写代码、review）│   ├── skills/          # ★ Coder 专属 Skill│   └── .agents/skills/  # ★ 共用此 workspace 的 Agent 共享│├── writer-agent/        # 【工作区 C】Writer Agent 专属│   ├── SOUL.md          # Writer 性格（有创意、文笔好）│   ├── AGENTS.md        # Writer 职责（写文章、排版）│   ├── skills/          # ★ Writer 专属 Skill│   └── .agents/skills/  # ★ 共用此 workspace 的 Agent 共享│├── agents/                # 【运行态数据】系统自动管理│   ├── main/             # 主 Agent 的会话记录│   │   └── sessions/    # 会话记录（*.jsonl）│   ├── coder/            # Coder Agent 的会话记录│   │   └── sessions/│   └── writer/           # Writer Agent 的会话记录│       └── sessions/│├── skills/                # 【全局共享】本机所有 Agent 可用│   ├── web-search/│   ├── image-gen/│   └── pdf-tools/│└── subagents/              # 【临时子代理】sessions_spawn 临时任务数据

看着有点复杂？其实就三块：

1. openclaw.json
    — 总控配置，告诉系统哪个 Agent 用哪个 workspace
2. 各个 workspace 目录
    — 每个 Agent 的独立工作区
3. agents/ 和 skills/
    — 系统自动管理的运行数据和全局共享 Skill

2.2 配置绑定关系（openclaw.json）

目录中的每个 workspace 通过配置文件与 Agent 绑定：

{  "agents": {    "list": [      {        "id": "main",        "workspace": "~/.openclaw/workspace"      },      {        "id": "coder",        "workspace": "~/.openclaw/coder-agent"      },      {        "id": "writer",        "workspace": "~/.openclaw/writer-agent"      }    ]  }}

配置的核心逻辑很简单：workspace 字段内容决定 Agent 的人格和知识的存放位置。workspace就像给员工分配办公桌，桌子在哪，人就在哪干活。

2.3 官方推荐每个 Agent间独立 workspace

看到这儿你可能有个想法：多个 Agent 共用同一个 workspace 行不行？ 这样不是更省事儿吗？

理论上可以，但实际上会出两个问题：

1：Skill 无法隔离

workspace/skills/ 目录里的 Skill，所有共用这个 workspace 的 Agent 都会加载。如果你想让某个 Skill 只被特定 Agent 使用，共用 workspace 就实现不了。就好比程序员的 IDE 里装了写代码的工具，结果不懂技术的运营同事也能拿着瞎用，容易出乱子。

2：人格、个性无法区分

SOUL.md、AGENTS.md 共用，意味着所有 Agent 的性格和行为规则都一样。那你还分什么 coder 和 writer？干脆就叫"通用助手"得了。

所以，OpenClaw 官方推荐每个 Agent 独立 workspace。这也是后续 Skill 加载机制的基础。

三、Skill 加载机制：6 种来源与优先级

Workspace 确定后，下一个关键问题是：OpenClaw 如何加载每个 Agent 可用的 Skill？

3.1 Skill 加载路径及优先级

OpenClaw 由于不同场景工作空间的隔离关系，支持从 6 个路径位置加载 Skill，优先级由高到低顺序如下：

1. <workspace>/skills/              ← 当前 Agent 专属2. <workspace>/.agents/skills/      ← 共用此 workspace 的所有 Agent 共享3. ~/.agents/skills/                ← 本机所有 Agent 共享4. ~/.openclaw/skills/              ← 本机所有 Agent 共享5. 内置 Bundled Skills              ← 本机所有 Agent 共享6. skills.load.extraDirs            ← 本机所有 Agent 共享

看一个实际场景：现在 3 个 Agent 都要加载 code-review Skill，code-review skill 配置的位置如下，加载逻辑会是怎样的呢？

Skill 存在位置：├── workspace/skills/code-review/       ← main 加载这个（优先级 1）├── coder-agent/skills/code-review/      ← coder 加载这个（优先级 1）├── writer-agent/ (没有 code-review)    ← writer 继续往下找├── ~/.openclaw/skills/code-review/     ← writer 加载这个（优先级 4）└── (内置)/skills/code-review/    ← 如果上面都没有，用这个（优先级 5）

加载结果：

每个 Agent 优先加载自己 workspace 的专属 Skill，如果没有，再逐级向下查找全局共享 Skill。就像程序员优先用自己的 IDE 配置，没有的话再用公司统一的。

核心原则：越靠近 Agent 的 workspace，优先级越高；同名 Skill，高优先级覆盖低优先级。

说白了就是：专属的优先，共享的靠后。

3.2 Skills加载目录详解

3.2.1 Agent 专属 Skill：<workspace>/skills/

这是优先级最高的 Skill 来源，也是每个 Agent 的专属 Skill 目录。

示例：

workspace/skills/code-review/      → 只有 main Agent 能用coder-agent/skills/unit-test/      → 只有 coder Agent 能用writer-agent/skills/publish/       → 只有 writer Agent 能用

这个目录用于存放某个 Agent 独有的工作流程。比如代码 review Skill 只给 coder Agent 用，文章发布 Skill 只给 writer Agent 用。你要是把发布 Skill 给 coder，它可能反手给你写个单元测试出来。

3.2.2 Workspace 内共享 Skill：<workspace>/.agents/skills/

这个目录的存在经常让人困惑。在官方推荐的独立 workspace 架构下，它的意义非常有限。

分析：

# 独立 workspace 场景（推荐）workspace-main/├── skills/          ← main 独享└── .agents/skills/  ← 也是 main 独享（跟 skills/ 没啥区别）workspace-coder/├── skills/          ← coder 独享└── .agents/skills/  ← 也是 coder 独享（跟 skills/ 没啥区别）

  说实话，个人觉得 <workspace>/skills/ 和 <workspace>/.agents/skills/ 当前是完全等价的，在官方推荐的独立 workspace 架构下，<workspace>/.agents/skills/的意义非常有限。

实用建议：普通用户可以忽略这个目录，平常用 skills/ 和 ~/.openclaw/skills/ 就够了。

3.2.3 用户级手工 Skill ~/.agents/skills/

         这是第一个全局共享的 Skill 目录，所有 Agent 都能访问。

适用场景：

• 自己写的私有 Skill
• 公司内部 Skill（不公开）
• 开发测试中的 Skill
• 修改官方 Skill 的定制版

管理命令：

# 手动创建mkdir -p ~/.agents/skills/my-skillcp ./my-skill/* ~/.agents/skills/my-skill/# 手动删除rm -rf ~/.agents/skills/my-skill/

3.2.4 全局托管 Skill ~/.openclaw/skills/

这是最常用的全局共享 Skill 目录，也是 clawhub install 的默认安装位置。

适用场景：

• 从 ClawHub 安装的官方/社区 Skill
• 长期使用的公开 Skill
• 需要自动更新的 Skill

管理命令：

# 安装 Skillclawhub install tavily# 更新 Skillclawhub update --all# 删除 Skillclawhub uninstall tavily# 查看已安装clawhub list

3.2.5 内置 Bundled Skill — 官方自带 Skill

这是 OpenClaw 安装时自带的 Skill，无需额外安装。

位置：node_modules/openclaw-cn/skills/

禁用方式（在 openclaw.json 中）：

{  "skills": {    "entries": {      "gemini": { "enabled": false },      "sag": { "enabled": false }    }  }}

3.2.6 配置额外目录 skills.load.extraDirs

这是优先级最低的 Skill 来源，用于加载用户配置的额外 Skill 目录。

配置示例：

{  "skills": {    "load": {      "extraDirs": [        "~/Projects/my-skills",        "~/Downloads/skill-pack"      ]    }  }}

适用场景：开发中的 Skill、临时测试的 Skill 包。

四、多 Agent 协作架构与机制

        在上述的目录架构和 Skill 加载机制下，多个 Agent 之间是如何协作的呢？

流程步骤：

子 Agent 启动时，会读取自己独立 workspace 的配置，使用自己的专属 Skill，而不是继承 main Agent 的配置。就像你派程序员去写代码，他用的是自己的 IDE 配置，不是你的。

五、Openclaw主要目录介绍

5.1 Openclaw核心目录介绍

5.2 会话记录管理

位置：~/.openclaw/agents/<agentId>/sessions/*.jsonl

说明：

• 每次会话自动生成一个 jsonl 文件
• 永久保存，不会自动清理
• 可手动删除释放空间
• 不要手动编辑，可能导致会话历史损坏

清理建议：

# 查看会话文件大小du -sh ~/.openclaw/agents/*/sessions/# 删除旧会话（谨慎操作）rm ~/.openclaw/agents/main/sessions/2025-*.jsonl

六、最佳实践建议

6.1 Skills管理使用建议

6.2 多 Agent 配置建议

{  "agents": {    "list": [      {        "id": "main",        "workspace": "~/.openclaw/workspace"      },      {        "id": "coder",        "workspace": "~/.openclaw/coder-agent"      },      {        "id": "writer",        "workspace": "~/.openclaw/writer-agent"      }    ],    "defaults": {      "subagents": {        "maxConcurrent": 8      }    }  }}

核心原则：

1. 每个 Agent 独立 workspace
2. 专属 Skill 放 workspace/skills/
3. 共享 Skill 放 ~/.openclaw/skills/
4. 不要在共用 workspace 上纠结 Skill 隔离

一句话总结

每个 Agent 独立 workspace，专属 Skill 放 workspace，共享 Skill 放 ~/.openclaw/skills。

彩蛋

AI 时代来了，有人焦虑，有人观望，有人已经在用多 Agent 协作解决实际问题。你能读到这里，说明你真的想搞懂 ，这份耐心，比任何工具都珍贵，你就已经走在了前面。

• AI Coding，前端转全栈，是效率提升还是内卷新游戏
• AI Coding之OpenSpec + Claude Code + Java 实战全记录
• openclaw.json 解读攻略：读完这篇，你比 90% 人更懂OpenClaw 配置