如何给 OpenClaw 添加 Skill：目录结构、配置、/skill 调用（以 browser-use 为例）

摘要（先看结论）

• 一个 Skill 就是一个目录，目录里至少有一个 SKILL.md；OpenClaw 扫描到它就能加载。
• Skills 有 3 个来源：当前 OpenClaw 工作区的 <workspace>/skills（项目内/最高优先级）、本机个人目录 ~/.openclaw/skills（全局可用/中优先级）、以及随安装包提供的 bundled skills（最低优先级）。同名 skill 会按这个顺序覆盖：workspace > ~/.openclaw/skills > bundled。
• 最通用的调用方式是 /skill <name> [input]；技能不生效时优先看 Missing requirements（本机缺依赖）。如果你启用了 bundled 白名单机制（skills.allowBundled），还需要额外关注 Blocked by allowlist。

1）把 Skill 放到哪里

这里的 <workspace> 指 OpenClaw 当前运行时的工作区目录（通常就是你在用的项目目录/Workspace 根目录）。

OpenClaw 会从这些位置加载 skills：

• Workspace skills：<workspace>/skills（最高优先级，适合放到仓库里）
• Managed/Local skills：~/.openclaw/skills（适合个人全局技能）
• Bundled skills：随安装包提供（最低优先级）

同名 skill 覆盖规则：

<workspace>/skills > ~/.openclaw/skills > bundled skills

你也可以在配置里增加额外扫描目录（最低优先级）。不配置就不会扫描额外目录，只扫描默认的三处（workspace、本机、bundled）：

skills.load.extraDirs

权限与可达性注意：

• OpenClaw 是本机进程，能否扫描到这些目录取决于运行 OpenClaw 的用户是否对目录有读取权限（目录存在、可读、可遍历）。
• extraDirs 建议填“skills 根目录”（里面包含多个 <skillName>/SKILL.md），不要直接指向某个 SKILL.md。
• 额外目录的优先级最低；如果同名 skill 在 workspace 或 ~/.openclaw/skills 已存在，会覆盖 extraDirs 里的同名版本。
• 如果你启用了 Docker 沙箱：技能进程运行在容器内，默认看不到 host 文件系统；但“技能发现/加载目录”发生在 host 侧。沙箱模式下的文件可达性问题通常出现在 skill 执行阶段（容器内访问不到 host 路径），而不是扫描阶段。

示例（写到 ~/.openclaw/openclaw.json）：

{
  "skills": {
    "load": {
      "extraDirs": [
        "~/Projects/agent-scripts/skills",
        "~/Projects/oss/some-skill-pack/skills"
      ],
      "watch": true
    }
  }
}

2）一个 Skill 最小长什么样

目录结构要求非常简单：

skills/
  my-skill/
    SKILL.md

SKILL.md 必须以 YAML frontmatter 开头，至少包含 name 和 description：

---
name: my-skill
description: Do something useful.
---

# Skill Instructions

写清楚触发时要做什么、输出什么格式、需要用哪些工具。

3）为什么会出现 “Missing requirements”

Skill 可以在 metadata 里声明加载门槛（例如必须存在某个 CLI、必须有某个 env、必须开启某个 config）。当门槛不满足时，skill 在加载阶段就会被过滤掉，表现为 “Missing requirements”。

排查优先级：

1. 本机是否缺少 skill 依赖的命令行工具（最常见）
2. 必需 env 是否配置（host 注入与沙箱环境变量是两套逻辑）
3. 必需 config 是否开启

4）用 openclaw.json 管控 skills（启用、白名单、覆写）

skills 相关配置都在 ~/.openclaw/openclaw.json 的 skills 下。常用的几项：

• skills.entries.<skillName>.enabled：显式启用/禁用单个 skill
• skills.allowBundled：bundled skills 白名单（可选；不配置时 bundled 通常默认可用，一旦配置就只允许列表内的 bundled；不影响你自己写在 workspace/本机目录里的 skill）
• skills.load.extraDirs：额外扫描的 skills 目录（最低优先级）
• skills.load.watch：监听 skills 变更并自动刷新

最小示例：

{
  "skills": {
    "load": {
      "watch": true
    }
  }
}

5）怎么调用 Skill：/skill

最通用的调用方式是发送一条以 /skill 开头的消息：

/skill my-skill 这里是输入

是否能注册成“原生 slash command”取决于你所在渠道与 commands 配置，但不影响文本 /skill ... 的可用性。

6）示例：启用并使用 browser-use 这个 Skill

browser-use 的特点是：它通常不是你自己写的 workspace skill，而是一个 bundled skill + 外部依赖（例如 browser-use CLI）。所以它最容易遇到两类问题：白名单没放行、依赖没装好。

6.1 看它到底卡在哪：Ready / Blocked / Missing

用 OpenClaw 自带的技能检查命令定位状态：

• openclaw skills list
• openclaw skills check
• openclaw skills info browser-use

常见状态含义：

• Ready to use：可以直接用
• Blocked by allowlist：你启用了 bundled 白名单机制，但没把它加进 skills.allowBundled
• Missing requirements：本机缺依赖（最常见就是 browser-use 这个 CLI 没装好或不可执行）

6.2 browser-use 怎么用

你可以用两种方式使用它：

1）通过 OpenClaw 触发（推荐，最像“对话式自动化”）：

/skill browser-use 打开 https://example.com ，然后把页面主标题文本复制出来

建议的稳定操作套路是：

• open 打开页面
• 每次交互前先 state，基于 state 返回的 index 决定点击/输入目标
• 执行 click/input/keys/scroll 等动作
• 每次交互后再 state 验证页面是否进入预期状态
• 最后 screenshot 留证或便于排障

2）直接用 browser-use CLI（适合你想自己精确控制每一步）：

browser-use open "https://example.com"
browser-use state
browser-use click 12
browser-use input 18 "hello"
browser-use keys "Enter"
browser-use screenshot
browser-use close

浏览器/登录态相关常用选项：

• --browser chromium --headed：用 Chromium 打开可视化窗口
• --browser real --profile "Default"：复用真实 Chrome 的用户目录与登录态

7）最短排障清单

• Skill 不出现：确认目录是否是 skills/<name>/SKILL.md，以及是否被更高优先级同名 skill 覆盖。
• Blocked by allowlist：仅当你启用了 skills.allowBundled 时会出现；把 skill 名加入 skills.allowBundled（只针对 bundled）。
• Missing requirements：按技能要求安装缺失的 CLI/env/config；browser-use 最常见是 CLI 不可用。
• 配置不生效：确认 skills.load.watch 是否开启；否则重启 Gateway 再试。