技能是什么

OpenClaw 使用 AgentSkills 兼容的技能文件夹来教 Agent 如何使用工具。每个技能是一个目录，包含一个带有 YAML frontmatter 和指令的 SKILL.md 文件。

技能通过在系统提示词中注入上下文和约束，让 Agent 在具体场景下知道何时、如何、用什么参数调用工具。

技能加载位置与优先级

技能从三个地方加载：

  1. 内置技能（bundled）：随安装发布（npm 包或 OpenClaw.app）
  2. 托管/本地技能：~/.openclaw/skills
  3. Workspace 技能：<workspace>/skills

如果技能名冲突，优先级为：

<workspace>/skills（最高）→ ~/.openclaw/skills → 内置技能（最低）

此外，还可以通过 skills.load.extraDirs 配置额外技能文件夹（优先级最低）。

多 Agent 场景下的技能

在多 Agent 设置中，每个 Agent 有自己的 workspace。这意味着：

  • Per-agent 技能：在 <workspace>/skills，仅该 Agent 可用
  • 共享技能：在 ~/.openclaw/skills（托管/本地），同一机器上所有 Agent 可见
  • 共享文件夹：也可通过 skills.load.extraDirs 添加，供多个 Agent 共用

SKILL.md 格式

SKILL.md 必须至少包含：

---
name: image-lab
description: Generate or edit images via a provider-backed image workflow
---

可选 frontmatter 字段

字段 说明
homepage 在 macOS Skills UI 中显示为"Website"的 URL
user-invocable `true
disable-model-invocation `true
command-dispatch 设为 tool 时，斜杠命令绕过模型直接定向到工具
command-tool 当 command-dispatch: tool 时，要调用的工具名

技能条件加载（Gating）

OpenClaw 在加载时通过 metadata 过滤技能（单行 JSON）：

---
name: gemini
metadata:
  {"openclaw": {"requires": {"bins": ["gemini"], "env": ["GEMINI_API_KEY"]}}}
---

支持的过滤条件：

  • always: true：始终包含（跳过其他过滤）
  • os：平台列表（darwin、linux、win32）
  • requires.bins：PATH 上必须存在的二进制列表
  • requires.anyBins：至少有一个存在的二进制
  • requires.env：必须存在或已在配置中提供的环境变量
  • requires.config：必须为真的 openclaw.json 路径列表

沙箱注意：requires.bins 在技能加载时在主机检查。如果 Agent 被沙箱化，二进制也必须存在于容器内。

技能 + 插件

插件可以通过在 openclaw.plugin.json 中列出 skills 目录来打包自己的技能。插件技能在插件启用时加载，参与正常的技能优先级规则。

ClawHub：公共技能市场

ClawHub 是 OpenClaw 的公共技能注册表。可以用原生 openclaw skills 命令发现/安装/更新技能：

# 安装技能到 workspace
openclaw skills install <skill-slug>

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

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

安全注意事项

⚠️ 把第三方技能视为不受信任的代码。启用前先阅读。

  • 优先对不受信任输入和风险工具使用沙箱运行
  • Workspace 和 extra-dir 技能发现只接受技能根目录和 SKILL.md 文件，其解析的 realpath 必须在配置的根目录内
  • skills.entries.*.env 和 skills.entries.*.apiKey 将 secrets 注入主机进程（不是沙箱）。避免在提示词和日志中包含 secrets
  • 建议：在启用任何第三方技能前，先用 openclaw security audit 做安全审计

编写自己的技能

技能本质上是结构化的系统提示词增强文件。编写步骤：

  1. 确定 Agent 需要在什么场景下做什么
  2. 写 SKILL.md：包含 name、description、metadata
  3. 详细描述：Agent 应该在什么情况下调用相关工具、参数怎么填、结果怎么用
  4. 添加条件加载（如果需要）：通过 metadata 控制技能在什么环境下加载
  5. 测试：验证 Agent 在相关场景下能正确使用工具

好的技能应该是场景化的，不是通用指导——告诉 Agent 在特定情况下怎么做，而不是泛泛而谈。

推荐技能来源

  • ClawHub（clawhub.com）：官方技能市场，经过 VirusTotal 扫描
  • 官方内置技能：随 OpenClaw 发布，质量有保证
  • 社区贡献：GitHub 上开源的 OpenClaw 技能

本指南编译自 OpenClaw 技能文档