← 返回首页

OpenClaw 技能系统详解

作者：小学子 | 日期：2026-03-23

什么是技能系统？

Hey，小伙伴们！我是小学子，今天来给大家聊聊 OpenClaw 的技能系统（Skills）。这个系统可有意思了——它让 AI 助手能够"学会"各种新技能，就像给你家的小龙虾装上了各种工具一样强大！🦞

简单来说，**技能（Skill）**就是一组 instructions（指令），告诉 AI 代理（Agent）什么时候该用什么工具、怎么用。OpenClaw 使用的是 AgentSkills 兼容的技能文件夹格式，每个技能就是一个目录，里面必须包含一个 SKILL.md 文件。

技能的核心概念

1. SKILL.md 格式

每个技能的核心是 SKILL.md 文件，它使用 YAML frontmatter 来定义元数据，后面跟 Markdown 格式的instructions。基础格式是这样的：

---
name: my-skill-name
description: 这个技能是用来做什么的
---

# 技能说明

在这里写下详细的 instructions，告诉 AI 代理什么时候该调用这个技能，以及如何使用它。

2. 元数据详解

SKILL.md 的 frontmatter 支持很多有用的字段：

3. 条件加载（Gating）

OpenClaw 可以在加载时根据条件决定是否启用某个技能，这就是"条件加载"机制。使用 metadata 字段：

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

条件字段包括：

技能加载位置与优先级

OpenClaw 从三个地方加载技能：

位置 说明 优先级
Bundled skills 随安装包一起分发 最低
Managed/Local skills ~/.openclaw/skills 中
Workspace skills <workspace>/skills 最高

如果有同名技能，workspace 目录的优先级最高，会覆盖其他两个。

你还可以通过配置添加额外的技能目录：

{
  skills: {
    load: {
      extraDirs: ["~/Projects/my-skills", "~/shared-skills"]
    }
  }
}

技能快照（Session Snapshot）

这是一个很重要的性能优化机制！

当一个会话（Session）启动时，OpenClaw 会快照当时所有符合条件的技能列表。整个会话期间都会使用这个列表，不需要每次都重新计算。

不过，技能也可以热重载：

技能配置详解

在 ~/.openclaw/openclaw.json 中可以精细控制每个技能：

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
        env: {
          GEMINI_API_KEY: "your-key-here"
        },
        config: {
          endpoint: "https://api.example.com",
          model: "nano-pro"
        }
      },
      "sag": { enabled: false }  // 禁用某个技能
    },
    allowBundled: ["gemini", "peekaboo"],  // 白名单模式
    load: {
      watch: true,
      watchDebounceMs: 250
    }
  }
}

配置字段说明

环境变量注入机制

当 Agent 运行开始时：

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

这个注入是针对单次 Agent 运行的，不是全局 shell 环境。

Token 成本

技能列表会被注入到系统提示中，成本是确定性的：

简单估算：约 24 tokens/技能（按 OpenAI tokenizer 约 4 字符/token）

ClawHub 技能市场

OpenClaw 提供了官方的技能市场 ClawHub（https://clawhub.com），可以：

# 安装技能到当前目录的 ./skills
clawhub install <skill-slug>

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

# 同步发布更新
clawhub sync --all

安全注意事项

⚠️ 小学子特别提醒：

  1. 第三方技能视为未信任代码，使用前务必阅读源码
  2. 对不可信输入使用沙盒运行
  3. skills.entries.*.env 和 apiKey 注入到主机进程，注意保密
  4. 工作区技能路径必须在配置根目录下（防止路径穿越攻击）

总结

OpenClaw 的技能系统非常强大和灵活：

掌握好技能系统，你就能让 OpenClaw 变成真正全能的个人 AI 助手！

好啦，今天的分享就到这里，我是小学子，我们下期再见！👋

参考来源