乐于分享
好东西不私藏
当前位置：夜雨聆风 > 技术教程 > 软件教程 > OpenClaw Skill 属性配置文档

OpenClaw Skill 属性配置文档

当前时间： 2026-04-10 08:46:14 更新时间： 2026-04-10 分类：软件教程 评论(0)

OpenClaw Skill 属性配置文档

📦 1. Skill 系统概述

OpenClaw Skill 是 OpenClaw 智能体框架的核心扩展机制，其本质是“教智能体如何使用工具”的模块化功能单元。每个 Skill 是一个包含带有 YAML frontmatter 元数据和 Markdown 说明文件的目录，遵循 AgentSkills 开放规范。

Skill 的核心价值在于：将通用大语言模型转变为具备特定领域专业知识的智能体，通过注入操作指令、工具集成和领域知识，让智能体能够完成文件处理、API 调用、自动化操作等复杂任务。

如果将 OpenClaw 智能体比作“大脑”，Skill 就是为其配备的“经验 + 行动指南”。两者是互补的架构模式：Agent 读取 Skill 获得领域知识，进而能够调用工具完成实际工作。

📁 2. Skill 目录结构与 SKILL.md 格式

🗂️ 2.1 标准目录结构

每个 Skill 的最小单元是一个包含必要文件的目录，结构如下：

skill-name/├── SKILL.md           # 必需：YAML 元数据 + Markdown 指令├── scripts/           # 可选：可执行代码（Python/Bash 等）├── references/        # 可选：按需加载的参考文档└── assets/            # 可选：输出用的资源文件（模板、图标等）

📄 2.2 SKILL.md 文件格式

SKILL.md 是 Skill 的核心文件，由两部分组成：

  1. 1. YAML frontmatter（前置元数据） ：定义 Skill 的标识、描述和准入规则，以 --- 开头和结尾
  2. 2. Markdown body（正文） ：提供给智能体的操作指令和说明

重要格式约束：OpenClaw 内嵌的智能体解析器仅支持单行 frontmatter 键值，以保证与 Pi Agent 运行时的兼容性。metadata 字段必须是一个单行 JSON 对象，不能使用多行 YAML 缩进写法。

✅ 正确写法示例

---name:hello_worlddescription:Asimpleskillthatsayshello.metadata: {"openclaw": {"requires": {"bins": ["echo"]}}}---# Hello World SkillWhentheuserasksforagreeting,usethe`echo`tooltosay"Hello from your custom skill!"

在 Markdown 正文中可使用 {baseDir} 占位符来引用 Skill 文件夹路径，便于引用 scripts/ 目录下的脚本。

🔧 3. 核心属性详解

📋 3.1 YAML Frontmatter 属性参考

SKILL.md 的 YAML frontmatter 支持以下字段。除 metadata 为单行 JSON 外，其余字段均为普通字符串值。

字段
必填
类型
说明
name
✅
string
Skill 的唯一标识符（推荐 snake_case）
description
✅
string
单行描述，智能体在 prompt 构建时用来判断是否触发该 Skill
metadata
❌
string（JSON）
单行 JSON 对象，内含 openclaw 命名空间下的扩展属性（见下表）
user-invocable
❌
boolean
是否暴露为用户斜杠命令，默认 true
disable-model-invocation
❌
boolean
设为 true 时从模型 prompt 中排除，仅用户手动触发，默认 false
command-dispatch
❌
string
设为 tool 时斜杠命令直接分派给工具
command-tool
❌
string
 command-dispatch: tool

 时调用的工具名
command-arg-mode
❌
string
工具分派时的参数模式，默认 raw

metadata JSON 对象内可包含以下 openclaw 子属性：

字段
说明
metadata.openclaw.os
操作系统过滤数组，如 ["darwin", "linux"]
metadata.openclaw.requires.bins
全部必须存在的二进制文件列表
metadata.openclaw.requires.anyBins
至少一个存在的二进制文件列表
metadata.openclaw.requires.env
必须存在或通过 skills.entries.<skillKey>.env 配置提供的环境变量列表
metadata.openclaw.requires.config
必须存在的配置键列表
metadata.openclaw.requires.always
设为 true 跳过所有准入检查，始终纳入候选（不推荐，不会覆盖 enabled: false）
metadata.openclaw.install
安装器规格数组，支持 brew/node/go/uv/download
metadata.openclaw.skillKey
自定义 Skill 配置键，覆盖默认的 name 映射
metadata.openclaw.primaryEnv
指定 apiKey 对应的环境变量名，与配置中的 apiKey 配合使用
metadata.openclaw.homepage
在 macOS Skills UI 中展示为“网站”链接
metadata.openclaw.emoji
macOS Skills UI 的图标 emoji

🧩 3.2 属性详细说明

🏷️ name 与 description

name 和 description 是智能体用来确定是否触发该 Skill 的唯一字段，因此清晰、全面地描述 Skill 的功能和使用场景至关重要。

🚦 metadata.openclaw.requires（准入门控）

通过 requires 字段，OpenClaw 在加载时根据环境、配置和二进制文件存在情况对 Skill 进行过滤。requires.env 检查的是环境变量存在或已通过 skills.entries.<skillKey>.env 在配置中提供，并非仅检查系统环境变量。

metadata: {"openclaw": {"requires": {"bins": ["gh", "git"], "anyBins": ["jq", "yq"], "env": ["GITHUB_TOKEN"], "config": ["github.username"], "os": ["darwin", "linux"]}}}

OpenClaw 使用 evaluateEntryRequirementsForCurrentPlatform 函数检查当前平台上的 OS 兼容性、必需二进制文件的存在性以及必要的环境变量。

📦 metadata.openclaw.install（自动安装）

定义 Skill 依赖的自动安装方式，支持五种安装器类型：

安装器
说明
示例
brew
Homebrew 公式
 {"type": "brew", "formula": "gh"}
node
Node 包管理器
 {"type": "node", "package": "axios"}
go
Go 模块安装
 {"type": "go", "module": "github.com/xxx/yyy@latest"}
uv
Python uv 工具
 {"type": "uv", "package": "ruff"}
download
直接下载文件/归档
支持 url、archive、extract、stripComponents、targetDir 等子属性

Gateway 网关会根据 install.preferBrew 配置优先选择安装器，在可用时优先使用 brew。

⚙️ 4. Skill 配置属性（skills.* schema）

所有 Skill 加载器和安装配置位于 ~/.openclaw/openclaw.json 中的 skills 键下。

🗃️ 4.1 完整配置 Schema

{"skills":{"allowBundled":["gemini","peekaboo"],"load":{"extraDirs":["~/Projects/agent-scripts/skills"],"watch":true,"watchDebounceMs":250},"install":{"preferBrew":true,"nodeManager":"npm"},"entries":{"nano-banana-pro":{"enabled":true,"apiKey":{"source":"env","provider":"default","id":"GEMINI_KEY_HERE"},"env":{"GEMINI_API_KEY":"your-key-here"},"config":{"endpoint":"https://example.invalid","model":"nano-pro"}}}}}

📑 4.2 配置属性详解

属性
类型
默认值
说明
allowBundled
string[]
—
内置 Skill 白名单。设置后仅列表中内置 Skill 可用，托管/工作区 Skill 不受影响
load.extraDirs
string[]
—
额外 Skill 扫描目录（最低优先级）
load.watch
boolean
true
是否监视 Skill 文件夹并刷新快照
load.watchDebounceMs
number
250
Skill 监视器事件防抖时间（毫秒）
install.preferBrew
boolean
true
可用时优先使用 brew 安装器
install.nodeManager
string
 "npm"
Node 安装器偏好（npm | pnpm | yarn | bun）
entries.<skillKey>.enabled
boolean
—
设为 false 以禁用特定 Skill
entries.<skillKey>.env
object
—
为智能体轮次注入的环境变量（仅在尚未设置时）
entries.<skillKey>.apiKey
string | SecretRef
—
主 API 密钥的便捷字段。支持明文 string 或 SecretRef 对象 { source: "env", provider: "default", id: "..." }
entries.<skillKey>.config
object
—
自定义 per-skill 配置字段，供 Skill 内部读取使用

注意：entries 下的键默认映射到 Skill 名称。如果 Skill 定义了 metadata.openclaw.skillKey，则使用该键。

🔄 5. 加载优先级与作用域

📊 5.1 加载层级

OpenClaw 从多个层级加载 Skill，同名冲突时高优先级覆盖低优先级：

位置
优先级
作用域
<workspace>/skills/
最高
单智能体
~/.openclaw/skills/
中
共享（所有智能体）
内置（随安装包发布）
最低
全局
skills.load.extraDirs
最低
自定义共享文件夹

此外，插件 Skills 是一种特殊来源：插件通过 openclaw.plugin.json 的 skills 目录附带 Skill，参与正常的优先级规则，位于工作区 Skill 之后、共享 Skill 之前。

🧑‍💻 5.2 单智能体 vs 共享 Skill

  • • 单智能体 Skill：位于 <workspace>/skills，仅供该智能体使用
  • • 共享 Skill：位于 ~/.openclaw/skills，对同一机器上的所有智能体可见
  • • 额外目录：通过 skills.load.extraDirs 添加共享文件夹（最低优先级）

🎯 5.3 智能体 Skill 白名单

使用 Agent 配置来控制每个智能体可见的 Skill 集合：

{"agents":{"defaults":{"skills":["github","weather"]},"list":[{"id":"writer"},// 继承 defaults{"id":"docs","skills":["docs-search"]},// 替换 defaults{"id":"locked-down","skills":[]}// 无 Skill]}}

规则：

  • • agents.defaults.skills：共享基线白名单
  • • 省略 agents.defaults.skills：默认无限制
  • • agents.list[].skills：该智能体的最终 Skill 集合，不与 defaults 合并，而是完全替换

🧭 6. Skill 生命周期与门控规则

⏳ 6.1 加载时过滤

OpenClaw 在加载 Skill 时根据以下条件进行过滤：

  • • 操作系统兼容性（metadata.openclaw.os）
  • • 必需二进制文件的存在性（bins 全部存在，anyBins 至少一个存在）
  • • 必需环境变量是否设置或已通过配置提供
  • • 配置键是否存在
  • • 智能体 Skill 白名单
  • • allowBundled 白名单

📡 6.2 状态查询

skills.status（Gateway 网关）返回所有 Skill 及其资格状态和缺失的要求，包括内置 Skill 的允许列表阻止情况。

🔁 6.3 热加载与监视

OpenClaw 在会话开始时对 eligible skills 进行快照，后续轮次复用该快照。启用监视器（load.watch: true）后，Skill 文件夹的更改会在下一个智能体轮次被自动获取，无需重启 Gateway。但变更需新会话或 watcher 触发刷新才能生效。

🔐 7. 环境变量与密钥管理

💉 7.1 环境变量注入

环境变量可通过多种方式注入 Skill：

  1. 1. 配置文件注入：通过 skills.entries.<skillKey>.env 在 ~/.openclaw/openclaw.json 中配置
  2. 2. API 密钥便捷字段：skills.entries.<skillKey>.apiKey 作为主环境变量的便捷声明方式，支持明文值或 SecretRef 对象
  3. 3. 运行时注入：skills.update 命令更新 enabled、apiKey 和 env

🧪 7.2 沙箱隔离注意事项

当会话处于沙箱隔离状态时，Skill 进程在 Docker 内运行，沙箱不会继承宿主机的 process.env。解决方案：

  • • 使用 agents.defaults.sandbox.docker.env（或单智能体的 agents.list[].sandbox.docker.env）
  • • 将环境变量烘焙到自定义沙箱镜像中

全局 env 和 skills.entries.<skill>.env/apiKey 仅适用于宿主机运行。

🖥️ 8. 远程 macOS 节点支持

当 Gateway 运行在 Linux 上但连接了 macOS node 时，macOS-only 的 Skill（metadata.openclaw.os: ["darwin"]）也可以变为 eligible，通过 nodes.run 在远程 macOS 节点上执行。这为跨平台部署提供了灵活性。

📈 9. Token 开销分析

Skill 注入到模型 prompt 会产生 token 消耗，精确开销公式如下：

  • • 基础开销：当至少 1 个 skill 被激活时，注入 195 个字符的固定前缀
  • • 单个 skill 开销：97 字符 + name + description + location 的 XML 转义长度

开发者可通过控制 name 和 description 长度来优化上下文窗口占用。

🛡️ 10. 安全属性与最佳实践

⚠️ 10.1 安全注意事项

  • • 将第三方 Skill 视为不受信任的代码：启用前请仔细阅读 Skill 内容
  • • 使用沙箱隔离：对于不受信任的输入和高风险工具，优先使用沙箱隔离运行
  • • 密钥保护：skills.entries.*.env 和 skills.entries.*.apiKey 为该智能体轮次将秘密注入到宿主机进程中，需确保秘密不进入提示词和日志
  • • 端口隔离：建议不将 OpenClaw 默认端口暴露到公网，不使用管理员权限运行

🧱 10.2 路径遍历防护

工作区和额外目录的 skill 发现只接受解析后的真实路径保持在配置根目录内的 Skill，有效防止通过符号链接逃逸到任意文件系统位置。

早期版本（< 2026.2.14）曾存在沙箱 skill 镜像的路径遍历漏洞（CVE-2026-28457），通过未净化的 skill frontmatter name 参数导致，已在后续版本修复。

🎭 10.3 权限模型

Skill 本身不具备独立权限，仅调用已开启的 Tools。若未开启对应 Tools，Skill 无法生效。官方 bundled Skills 会随系统自动启用，需手动设置白名单限制。

💡 10.4 开发最佳实践

  • • 简洁原则：上下文窗口是公共资源，只添加智能体尚未具备的上下文，优先使用简洁的示例而非冗长的解释
  • • 设置适当自由度：将详细程度与任务的脆弱性和可变性相匹配（高自由度指令 → 中等自由度伪代码 → 低自由度特定脚本）
  • • 本地测试：发布前使用 openclaw agent --message "..." 进行测试
  • • 使用 Skill Creator：OpenClaw 提供 Skill Creator 技能，它本身就是技能创建的最佳实践示例，遵循 agentskills 开放规范

⌨️ 11. 相关命令与 API

💻 11.1 CLI 命令

OpenClaw 提供两套独立的 CLI 命令集：

命令
归属
说明
openclaw skills list
OpenClaw CLI
列出已加载的 Skill
openclaw skills install <slug>
OpenClaw CLI
从 ClawHub 安装 Skill 到 workspace
openclaw skills update --all
OpenClaw CLI
更新所有已安装 Skill
openclaw gateway restart
OpenClaw CLI
重启 Gateway 以应用配置变更
clawhub login
ClawHub CLI
浏览器认证流程
clawhub publish <path>
ClawHub CLI
发布 Skill 到 ClawHub 注册表
clawhub sync --all
ClawHub CLI
扫描本地 Skill 并发布更新

🌐 11.2 Gateway API

OpenClaw Gateway 提供 REST API（默认监听 http://127.0.0.1:18789），可用于查询 Skill 状态和触发操作：

  • • skills.status：返回所有 Skill 及其资格状态
  • • skills.install：在 Gateway 主机上运行 Skill 安装器
  • • skills.update：更新 enabled、apiKey 和 env 配置

📝 12. 示例：完整 Skill 定义

以下是一个符合单行 JSON 格式要求的完整 Skill 定义：

SKILL.md

---name:github_pr_managerdescription:ManageGitHubpullrequests,includingcreation,review,andmerging.metadata: {"openclaw": {"os": ["darwin", "linux"], "requires": {"bins": ["gh", "git"], "env": ["GITHUB_TOKEN"], "config": ["github.username"]}, "install": [{"type":"brew", "formula":"gh"}, {"type":"node", "package":"@octokit/rest"}], "skillKey":"github", "primaryEnv":"GITHUB_TOKEN", "emoji":"🐙", "homepage":"https://cli.github.com"}}user-invocable:truedisable-model-invocation:false---# GitHub Pull Request ManagerThisskillenablestheagenttomanageGitHubpullrequestsusingthe`gh`CLItool.## When to Use-UseraskstocreateaPR-UserwantstoreviewormergeaPR-UserneedstolistopenPRsinarepository## Commands1. List PRs:`ghprlist--repo<owner>/<repo>`2. Create PR:`ghprcreate--title"..."--body"..."--basemain`3. Merge PR:`ghprmerge<pr-number>--merge`## EnvironmentEnsure`GITHUB_TOKEN`issetwithappropriatereposcopes.

对应配置文件（~/.openclaw/openclaw.json）

{"skills":{"entries":{"github":{"enabled":true,"apiKey":{"source":"env","provider":"default","id":"GITHUB_TOKEN"},"env":{"GITHUB_TOKEN":"your-github-token-here"}}}},"agents":{"defaults":{"skills":["github","weather"]}}}