跳到主要内容

Skills 开发

教 AI 智能体如何使用工具

7.1 什么是 Skills？​

Skills 是兼容 AgentSkills 规范的文件夹，用于教智能体如何使用工具。每个 Skill 是一个包含 SKILL.md 的目录。

Skills vs 工具​

  • 工具 (Tools)：OpenClaw 内置的执行能力（读写文件、执行命令等）
  • Skills：告诉智能体何时和如何使用这些工具的说明书

7.2 Skills 存放位置​

Skills 从三个位置加载，优先级如下：

<workspace>/skills（最高）→ ~/.openclaw/skills → 内置 Skills（最低）
位置说明
<workspace>/skills单智能体专用 Skills
~/.openclaw/skills共享 Skills（所有智能体可用）
内置 Skills随 OpenClaw 一起发布

7.3 SKILL.md 格式​

每个 Skill 目录必须包含 SKILL.md 文件：

---
name: my-skill-name
description: What this skill does
metadata:
  {"openclaw": {"requires": {"bins": ["curl"], "env": ["API_KEY"]}}}

Skill 说明

Describe when and how to use this skill...

使用示例​

When the user asks to [scenario], use this skill like:

some-tool --arg value

必需字段​

  • name：Skill 名称
  • description：简短描述

可选 metadata 字段​

---
name: my-skill
description: Description here
metadata:
  {
    "openclaw": {
      "requires": {
        "bins": ["curl"],        # 必须存在的二进制文件
        "env": ["API_KEY"],      # 必须存在的环境变量
        "config": ["browser.enabled"]  # 必须为真的配置项
      },
      "os": ["darwin", "linux"],  # 支持的操作系统
      "emoji": "🔧",              # UI 显示的表情
      "homepage": "https://..."   # 文档链接
    }
  }
---

7.4 通过 ClawHub 安装 Skills​

ClawHub 是 OpenClaw 的公共 Skills 注册表。

常用命令​

# 安装 Skills 到工作区
clawhub install <skill-name>

# 更新所有已安装的 Skills
clawhub update --all

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

浏览 Skills​

访问 https://clawhub.com 发现更多 Skills。

7.5 配置 Skills​

编辑 ~/.openclaw/openclaw.json：

{
  "skills": {
    "entries": {
      "my-skill": {
        "enabled": true,
        "apiKey": "xxx",  // 便捷字段，对应 primaryEnv
        "env": {
          "API_KEY": "xxx"
        },
        "config": {
          "endpoint": "https://api.example.com"
        }
      },
      "another-skill": {
        "enabled": false  // 禁用
      }
    },
    "load": {
      "watch": true,           // 监视文件变化
      "watchDebounceMs": 250,  // 防抖延迟
      "extraDirs": ["/path/to/extra/skills"]
    }
  }
}

7.6 工具组（简写）​

在配置中可以使用工具组：

组名包含的工具
group:runtimeexec, bash, process
group:fsread, write, edit, apply_patch
group:sessionssessions_list, sessions_history, sessions_send
group:memorymemory_search, memory_get
group:webweb_search, web_fetch
group:uibrowser, canvas
group:automationcron, gateway
group:messagingmessage
group:nodesnodes

示例：

{
  "tools": {
    "allow": ["group:fs", "group:web"]
  }
}

7.7 工具配置文件（Profile）​

使用 tools.profile 设置基础工具允许列表：

Profile说明
minimal仅 session_status
codinggroup:fs, group:runtime, group:sessions, group:memory, image
messaginggroup:messaging, sessions_*, session_status
full无限制

示例：

{
  "tools": {
    "profile": "coding",
    "deny": ["group:runtime"]  // 拒绝执行命令
  }
}

7.8 按提供商限制工具​

{
  "tools": {
    "profile": "coding",
    "byProvider": {
      "google-antigravity": { "profile": "minimal" },
      "openai/gpt-5.2": { "allow": ["group:fs", "sessions_list"] }
    }
  }
}

7.9 门控（加载时过滤）​

OpenClaw 使用 metadata 在加载时过滤 Skills：

---
name: gemini-cli
description: Use Gemini CLI for coding assistance
metadata:
  {
    "openclaw": {
      "requires": { "bins": ["gemini"] },
      "os": ["darwin", "linux"]
    }
  }
---

门控条件​

  • requires.bins：所有列出的二进制必须在 PATH 中
  • requires.anyBins：至少一个存在即可
  • requires.env：环境变量必须存在
  • requires.config：配置项必须为真值
  • os：仅在指定操作系统上启用

7.10 安装器​

Skills 可以自带安装器：

---
name: gemini
description: Gemini CLI integration
metadata:
  {
    "openclaw": {
      "requires": { "bins": ["gemini"] },
      "install": [
        {
          "id": "brew",
          "kind": "brew",
          "formula": "gemini-cli",
          "bins": ["gemini"],
          "label": "Install Gemini CLI (brew)"
        }
      ]
    }
  }
---

支持的安装器类型：

  • brew — Homebrew
  • node — npm/pnpm/yarn
  • go — Go
  • download — 直接下载

7.11 环境变量注入​

当智能体运行时，OpenClaw 会：

  1. 读取 Skills 元数据
  2. 将 skills.entries.*.env 应用到 process.env
  3. 使用有资格的 Skills 构建系统提示
  4. 运行结束后恢复原始环境

这是智能体运行范围内的，不是全局 shell 环境。

7.12 Skills 监视器​

默认情况下，OpenClaw 监视 Skills 文件夹，更改时自动刷新：

{
  "skills": {
    "load": {
      "watch": true,
      "watchDebounceMs": 250
    }
  }
}

7.13 内置 Skills​

OpenClaw 捆绑了多个内置 Skills：

Skill说明
apple-notes管理 Apple Notes
blogwatcher监控 RSS/博客更新
feishu-doc飞书文档操作
feishu-drive飞书云盘管理
feishu-perm飞书权限管理
feishu-wiki飞书知识库
githubGitHub 操作
gh-issuesGitHub Issues 管理
healthcheck主机安全检查
node-connect节点连接诊断
obsidianObsidian 笔记操作
skill-creator创建/编辑 Skills
summarize总结 URL/文件内容
weather天气查询
xurlX (Twitter) API 操作

7.14 安全注意事项​

  • 将第三方 Skills 视为不受信任的代码
  • 启用前请阅读 Skills 内容
  • 对于高风险工具，优先使用沙箱隔离
  • skills.entries.*.env 和 apiKey 会注入到宿主机进程