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

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 在容器启动后安装依赖；
- 或构建预装工具的自定义沙箱镜像。

七、ClawHub：技能发现与生命周期管理

ClawHub 是 OpenClaw 官方技能注册中心，支持：

clawhub install <skill-slug>：安装技能至当前工作区 ./skills
clawhub update --all：批量更新已安装技能
clawhub sync --all：扫描本地变更并发布到远程仓库

安装后的技能自动被 OpenClaw 识别为工作区技能，享有最高优先级。

八、性能与安全考量

提示词开销

每启用一个技能，系统提示词将增加约 97 字符 + 字段长度（经 XML 转义）。大量技能可能显著增加 token 消耗。

安全原则

第三方技能 = 不可信代码：使用前务必审查 SKILL.md 及关联脚本。
路径限制：工作区与额外目录中的技能，其真实路径必须严格位于配置根目录内，防止路径穿越。
权限最小化：高风险操作应强制在沙箱中执行，并限制网络与文件系统访问。

热重载机制

默认开启技能文件监听（skills.load.watch: true），修改 SKILL.md 后 250ms 内自动刷新会话技能列表，无需重启服务。

九、高级场景支持

远程 macOS 节点：Linux 网关可识别已连接 macOS 节点上的二进制，并将 macOS 专属技能标记为可用（通过 nodes.run 调度执行）。
技能快照：会话启动时冻结技能列表，保证多轮对话一致性；新会话或热重载后生效变更。

总结

OpenClaw 的技能系统通过分层加载、精细配置、安全隔离与生态集成，实现了工具能力的灵活扩展与可靠管控。无论是内置基础工具、团队共享脚本，还是从 ClawHub 获取的社区技能，都能在统一框架下安全、高效地服务于智能爬虫与自动化任务。

更多详情请参考：OpenClaw 官方技能配置文档

posted @ 2026-03-15 15:08 JackYang 阅读(44) 评论(0) 收藏举报

刷新页面返回顶部