OpenClaw Skills 系统深度解析：加载机制、条件门控与 ClawHub 技能市场

OpenClaw 使用 AgentSkills 兼容的技能文件夹来扩展 Agent 能力。每个 Skill 是一个包含 SKILL.md 的目录，文件头部有 YAML frontmatter 和使用说明。本文深度解析 OpenClaw 的 Skills 系统。

Skills 加载位置与优先级#

Skills 从三个位置加载，优先级从高到低：

1. Workspace Skills：<workspace>/skills（最高优先级）
2. Managed/Local Skills：~/.openclaw/skills
3. Bundled Skills：随 OpenClaw 安装包内置（最低优先级）

额外来源可通过 skills.load.extraDirs 配置（最低优先级）。

同名 Skill 存在冲突时，Workspace 覆盖 Managed，Managed 覆盖 Bundled。

多 Agent 环境中的 Skills 管理#

在多 Agent 配置中：

• 每个 Agent 专属 Skills：放在 <workspace>/skills，仅对该 Agent 可见
• 所有 Agent 共享 Skills：放在 ~/.openclaw/skills，机器上所有 Agent 都可访问
• 共享包：通过 skills.load.extraDirs 配置（多 Agent 公用）

ClawHub：技能市场#

ClawHub 是 OpenClaw 的公共技能注册表，网址：https://clawhub.com

常用操作：

# 安装技能到当前工作区
clawhub install <skill-slug>

# 更新所有已安装技能
clawhub update --all

# 同步（扫描 + 发布更新）
clawhub sync --all

默认安装到当前目录下的 ./skills，OpenClaw 下次 Session 时会自动识别。

SKILL.md 格式规范#

最简结构（至少需要以下内容）：

---
name: my-skill
description: 这个技能的简要描述
---

## 使用说明
在这里写 Agent 如何使用这个工具...

可选的 frontmatter 字段：

条件门控（Gating）#

这是 Skills 系统的核心功能——在加载时过滤不满足条件的技能：

---
name: my-gemini-skill
description: 使用 Gemini CLI 进行编码辅助
metadata:
  {
    "openclaw":
      {
        "requires": {
          "bins": ["gemini"],
          "env": ["GEMINI_API_KEY"],
          "config": ["browser.enabled"]
        },
        "primaryEnv": "GEMINI_API_KEY"
      }
  }
---

metadata.openclaw 支持的字段：

自动安装配置示例#

---
name: gemini
description: Gemini CLI 编码助手
metadata:
  {
    "openclaw":
      {
        "emoji": "♊️",
        "requires": { "bins": ["gemini"] },
        "install": [
          {
            "id": "brew",
            "kind": "brew",
            "formula": "gemini-cli",
            "bins": ["gemini"],
            "label": "Install Gemini CLI (brew)"
          }
        ]
      }
  }
---

支持的安装器类型：brew、node、go、uv、download

配置文件覆盖#

在 ~/.openclaw/openclaw.json 中控制内置技能：

{
  "skills": {
    "entries": {
      "my-gemini-skill": {
        "enabled": true,
        "apiKey": { "source": "env", "provider": "default", "id": "GEMINI_API_KEY" },
        "env": {
          "GEMINI_API_KEY": "your-key-here"
        },
        "config": {
          "endpoint": "https://example.com",
          "model": "gemini-pro"
        }
      },
      "unwanted-skill": { "enabled": false }
    }
  }
}

• enabled: false：禁用该技能（即使是内置的）
• env：仅当该变量不存在于进程时注入
• apiKey：方便为声明了 primaryEnv 的技能提供 API Key

Skills 自动刷新#

OpenClaw 默认监视技能文件夹，SKILL.md 变更时自动更新技能快照：

{
  "skills": {
    "load": {
      "watch": true,
      "watchDebounceMs": 250
    }
  }
}

刷新是热重载：变更会在下一个 Agent 对话轮次生效，无需重启。

Token 消耗说明#

当有 Skill 被激活时，OpenClaw 会在系统提示中注入一段紧凑的 XML 技能列表，消耗 Token 的公式：

粗估：每个 Skill 约消耗 24+ Token（取决于名称和描述长度）。

安全注意事项#

• 将第三方 Skills 视为不可信代码，启用前务必审查
• 推荐在沙箱环境中运行不可信输入和高风险工具
• Workspace 和 extraDir 中的 Skills 发现只接受 realpath 在配置根目录内的文件
• skills.entries.*.env 注入到宿主进程，不是沙箱——请勿将密钥放入提示或日志

远程 macOS 节点上的 Skills#

如果 Gateway 运行在 Linux 但连接了一个 macOS 节点（且允许 system.run），OpenClaw 可将 macOS 专用技能标记为可用，Agent 通过 nodes 工具调用。

原文：Skills - OpenClaw | 来源：OpenClaw 官方文档