一文讲透：OpenClaw多Agent模式下Skills的分层调用机制

AI指南

概述

在多Agent架构中，Skills（技能）是Agent感知和使用工具的核心媒介。OpenClaw作为一套成熟的Agent运行时框架，设计了一套分层调用机制：从技能发现、优先级判定、加载过滤到Agent级别的可见性控制，每一层都有明确的规则。

本文将深入剖析OpenClaw Skills系统的分层架构，帮助开发者和运维人员理解技能是如何被加载、过滤和调用的。

一、什么是Skills？

在OpenClaw中，每个Skill是一个包含SKILL.md文件的目录。SKILL.md由YAML frontmatter和Markdown指令组成，用于告诉Agent何时以及如何使用特定工具。

一个典型的Skill结构如下：

skills/
  github/
    SKILL.md
  weather/
    SKILL.md
  wp-post-from-outline/
    SKILL.md
    scripts/

当Agent启动时，OpenClaw会扫描所有已注册的技能目录，将符合条件的Skill注入到系统提示中，Agent即可在对话中调用这些技能。

二、六层技能加载优先级

OpenClaw从多个来源加载Skills，当同名技能出现在不同位置时，优先级最高的来源获胜。加载顺序（从高到低）：

第1层：Workspace Skills（工作区技能）
路径：<workspace>/skills/
每个Agent拥有独立的工作区，此目录下的技能仅对该Agent可见。优先级最高，用于覆盖任何同名技能。

第2层：Project Agent Skills（项目级Agent技能）
路径：<workspace>/.agents/skills/
属于工作区级别的共享技能，仅对该工作区的Agent可见。

第3层：Personal Agent Skills（个人Agent技能）
路径：~/.agents/skills/
机器级别的个人技能，对所有Agent可见。

第4层：Managed/Local Skills（托管/本地技能）
路径：~/.openclaw/skills/
用于本地覆盖或打补丁，所有Agent共享。

第5层：Bundled Skills（内置技能）
随OpenClaw安装包一起分发，优先级最低。

第6层：Extra Skill Folders（额外技能目录）
通过skills.load.extraDirs配置，优先级最低。

这种分层设计确保了：Agent级别的定制永远优先于全局默认，同时保留了灵活的共享机制。

三、多Agent模式下的技能隔离

在单Agent模式下，所有技能对唯一的Agent可见。但在多Agent模式下，每个Agent拥有：

  • 独立的工作区（workspace）：包含AGENTS.md、SOUL.md、USER.md和skills/
  • 独立的认证配置（agentDir）：每个Agent有自己的auth profiles
  • 独立的会话存储（sessions）：互不干扰

技能加载时，OpenClaw会先合并所有来源（同名技能按优先级去重），然后再应用Agent级别的可见性过滤。这意味着：

  • 位置/优先级决定哪个副本获胜
  • Agent allowlist决定哪些技能可见
  • 两者是独立的控制维度

四、Agent技能白名单机制

OpenClaw通过agents.defaults.skills和agents.list[].skills实现技能可见性的精细控制：

{
  "agents": {
    "defaults": {
      "skills": ["github", "weather"]
    },
    "list": [
      { "id": "writer" },
      { "id": "docs", "skills": ["docs-search"] },
      { "id": "locked-down", "skills": [] }
    ]
  }
}

规则：

  • 省略agents.defaults.skills → 所有技能默认可用
  • 省略agents.list[].skills → 继承defaults
  • 设置agents.list[].skills: [] → 该Agent无任何技能
  • 非空列表是最终集合，不与defaults合并

这种设计让团队可以为不同角色的Agent分配不同的技能集：例如，客服Agent只能使用weather和search，而运维Agent可以使用github和healthcheck。

五、技能门控（Gating）机制

即使技能在允许列表中，OpenClaw还会在加载时进行运行时过滤。通过SKILL.md中的metadata.openclaw字段，可以定义技能的前置条件：

---
name: image-lab
description: Generate images via provider
metadata: {"openclaw": {"requires": {"bins": ["uv"], "env": ["GEMINI_API_KEY"], "config": ["browser.enabled"]}}}
---

支持的门控类型：

  • requires.bins：必需的二进制程序（在PATH中）
  • requires.anyBins：至少一个二进制程序存在
  • requires.env：必需的环境变量
  • requires.config：必需的OpenClaw配置项
  • os：限定操作系统（darwin/linux/win32）

只有所有条件都满足的技能才会被注入到Agent的上下文中。这避免了Agent看到无法使用的技能而报错。

六、插件与技能的集成

OpenClaw的插件系统可以自带技能。插件在openclaw.plugin.json中声明skills目录，插件启用时技能自动加载。

例如，browser插件自带browser-automation技能，用于指导Agent如何进行多步骤浏览器控制。插件技能的优先级与skills.load.extraDirs相同，可以被工作区或内置技能覆盖。

这种设计实现了能力自包含：插件安装后，相关的操作指南自动可用，无需额外配置。

七、环境注入与安全边界

当Agent运行时，OpenClaw按以下顺序处理：

  1. 读取技能元数据
  2. 应用skills.entries.<key>.env和apiKey到process.env
  3. 构建系统提示（仅包含符合条件的技能）
  4. 运行结束后恢复原始环境

环境注入是作用域隔离的——仅在该Agent运行期间生效，不影响全局Shell。对于沙箱环境，技能进程在容器内运行，不继承宿主process.env，需通过agents.defaults.sandbox.docker.env单独配置。

八、快照与热更新

OpenClaw在会话启动时对符合条件的技能进行快照，同一会话内的后续轮次复用该快照。技能变更在下一个新会话生效。

两种情况下支持会话内热更新：

  • 启用了技能监视器（skills.load.watch: true，默认开启）
  • 新的远程macOS节点出现

技能监视器通过SKILL.md文件变更事件触发快照刷新，debounce默认250ms。

九、Token开销评估

当技能符合条件时，OpenClaw会以紧凑的XML列表注入到系统提示中。Token开销是确定性的：

  • 基础开销（≥1个技能时）：195字符
  • 每个技能：97字符 + XML转义后的name、description、location长度

公式：total = 195 + Σ(97 + len(name) + len(description) + len(location))

按OpenAI估算，约4字符/token，每个技能约24个token的基础开销加上字段内容。合理控制技能数量有助于降低上下文成本。

十、实战：多Agent技能配置示例

假设一个团队需要三个Agent：

  • main：日常助手，使用通用技能
  • coding：代码助手，使用GitHub和编码技能
  • family：家庭助手，技能受限

配置如下：

{
  "agents": {
    "defaults": {
      "skills": ["weather", "search", "summarizer"]
    },
    "list": [
      {
        "id": "main",
        "workspace": "~/.openclaw/workspace-main"
      },
      {
        "id": "coding",
        "workspace": "~/.openclaw/workspace-coding",
        "skills": ["github", "coding-agent", "summarizer"]
      },
      {
        "id": "family",
        "workspace": "~/.openclaw/workspace-family",
        "skills": ["weather"],
        "sandbox": { "mode": "all" }
      }
    ]
  }
}

这样，三个Agent共享同一台机器和Gateway进程，但技能可见性完全隔离，family Agent甚至被限制在沙箱中运行。

总结

OpenClaw的Skills分层调用机制可以概括为三个层次：

  • 发现层：六层优先级目录，同名技能最高优先级获胜
  • 过滤层：门控机制（bins/env/config/os）确保技能可运行
  • 可见性层：Agent白名单实现精细的权限控制

这种设计既保证了灵活性（每层可独立配置），又确保了安全性（沙箱隔离、白名单控制）。对于多Agent部署场景，理解这套机制是构建可靠Agent基础设施的关键。

标签：OpenClaw, Agent, Skills, 多Agent, 技能系统

滚动至顶部