OpenClaw 技能系统详解：从加载机制到安全管理

jack.yang

发布于 2026-03-16 11:24:12

1.8K0

OpenClaw 采用 AgentSkills 兼容的技能（Skill）体系，通过模块化目录结构赋予智能体使用各类工具的能力。每个技能是一个独立文件夹，包含描述其功能与调用方式的 SKILL.md 文件。本文将系统阐述 OpenClaw 的技能加载机制、优先级规则、配置方法、安全模型及与 ClawHub 生态的集成方式。

一、技能加载路径与优先级

OpenClaw 从四个位置加载技能，按从高到低的优先级排序如下：

工作区技能（Workspace Skills） 路径：<当前代理的工作目录>/skills → 仅对该代理生效，适用于任务专属工具。
本地管理技能（Managed/Local Skills） 路径：~/.openclail/skills → 对本机所有代理可见，适合团队共享或自定义覆盖。
插件附带技能（Plugin Skills） 由启用的插件通过 openclaw.plugin.json 声明，加载时参与正常优先级竞争。
内置技能（Bundled Skills） 随 OpenClaw 安装包（npm 或 OpenClaw.app）分发，作为基础能力集。

冲突处理：同名技能以工作区 > 本地 > 插件 > 内置的顺序覆盖。 扩展路径：可通过 ~/.openclaw/openclaw.json 中的 skills.load.extraDirs 添加额外技能目录（优先级最低）。

二、多代理环境下的技能隔离

在多代理（Multi-Agent）场景中：

每个代理拥有独立的工作目录，其下的 skills 文件夹仅对该代理可见。
~/.openclaw/skills 和 extraDirs 中的技能为全局共享，所有本机代理均可使用。
若多个来源存在同名技能，仍遵循上述优先级规则，确保工作区定制优先。

三、技能格式与元数据规范

每个技能必须包含 SKILL.md，其头部使用 YAML Frontmatter 定义元信息：

---
name: nano-banana-pro
description: 通过 Gemini 3 Pro 生成或编辑图像
metadata:
  {
    "openclaw": {
      "requires": {
        "bins": ["uv"],
        "env": ["GEMINI_API_KEY"],
        "config": ["browser.enabled"]
      },
      "primaryEnv": "GEMINI_API_KEY",
      "emoji": "🎨",
      "homepage": "https://example.com/skill"
    }
  }
---

核心字段说明：

name：技能唯一标识（用于配置与调用）。
description：简要功能说明。
metadata.openclaw（可选）：控制加载条件与 UI 展示。
- requires.bins：要求主机 PATH 中存在指定二进制。
- requires.env：依赖的环境变量（可由配置注入）。
- requires.config：需在 openclaw.json 中启用对应配置项。
- os：限定操作系统平台（如 ["darwin"]）。
- install：提供一键安装指令（支持 brew/npm/go/下载等）。

注意：Frontmatter 仅支持单行 JSON，且 metadata 必须为合法 JSON 对象。

四、技能调用与用户交互

技能可通过两种方式触发：

模型自动调用（默认）：技能描述注入系统提示词，由大模型决定是否使用。
用户显式调用：通过斜杠命令（如 /nano-banana-pro）直接触发。

可通过以下元数据控制行为：

user-invocable: false：隐藏斜杠命令。
disable-model-invocation: true：禁止模型自动调用，仅允许用户触发。
command-dispatch: tool + command-tool：绕过模型，直接调用指定工具。

五、运行时配置与密钥管理

在 ~/.openclaw/openclaw.json 中可对技能进行细粒度控制：

{
  "skills": {
    "entries": {
      "nano-banana-pro": {
        "enabled": true,
        "apiKey": "your-api-key-here",
        "env": { "GEMINI_API_KEY": "xxx" },
        "config": { "model": "nano-pro" }
      }
    }
  }
}

enabled: false 可禁用任意技能（包括内置技能）。
apiKey 为声明了 primaryEnv 的技能提供便捷密钥注入。
env 和 config 在每次代理运行前临时注入进程环境，运行结束后恢复原状，避免污染全局状态。

安全提示：密钥仅注入主机进程，不会传递至沙箱容器。若技能在沙箱中执行，需确保容器内已配置相应凭证。

六、沙箱环境中的技能执行

当代理启用 Docker 沙箱 时：

主机上的 requires.bins 检查仅验证主机环境。
若技能需在沙箱内运行（如调用 CLI 工具），容器内也必须存在对应二进制。
解决方案：
- 使用 agents.defaults.sandbox.docker.setupCommand 在容器启动后安装依赖；
- 或构建预装工具的自定义沙箱镜像。