AI 2026年3月22日 3 分钟阅读

OpenClaw skills 技能配置完全指南：打造你的专属 AI 助手

tinyash 0 条评论

文章信息

发布时间 2026年3月22日
作者 tinyash
阅读时长 3 分钟阅读

摘要：OpenClaw 的技能系统让你可以轻松扩展 AI 助手的能力。本文将带你从零开始，学习如何配置、创建和管理 OpenClaw 技能，打造真正懂你的 AI 管家。

一、什么是 OpenClaw 技能？

OpenClaw 使用 AgentSkills 兼容的技能文件夹结构来扩展 AI 助手的能力。每个技能本质上是一个包含 SKILL.md 文件的目录，这个文件定义了：

技能的元数据（名称、描述、图标等）
技能的触发条件（环境变量、二进制文件、配置项等）
技能的具体行为指令（AI 如何执行任务）

简单来说，技能就是教你的 AI 助手”如何做某件事”的说明书。

二、技能加载机制：三层优先级

OpenClaw 从三个位置加载技能，优先级从高到低：

1. <workspace>/skills          ← 你的工作区技能（最高优先级）
2. ~/.openclaw/skills          ← 本地管理技能
3.  bundled skills             ← 安装包内置技能（最低优先级）

这意味着什么？

你可以在工作区创建自定义技能，覆盖任何内置技能
同名技能中，工作区版本优先
内置技能作为默认值，只有没有被覆盖时才会生效

额外技能目录：你还可以在配置中添加更多技能目录：

// ~/.openclaw/openclaw.json
{
  skills: {
    load: {
      extraDirs: ["~/Projects/my-skills", "~/Projects/shared-skills"]
    }
  }
}

三、SKILL.md 文件结构

每个技能的核心是 SKILL.md 文件。它由两部分组成：

1. YAML Frontmatter（元数据）

---
name: my-custom-skill
description: 我的自定义技能描述
homepage: https://example.com
metadata:
  {
    "openclaw": {
      "emoji": "🔧",
      "requires": {
        "bins": ["node", "npm"],
        "env": ["MY_API_KEY"],
        "config": ["browser.enabled"]
      },
      "primaryEnv": "MY_API_KEY",
      "os": ["linux", "darwin"]
    }
  }
---

关键字段说明：

字段	说明
`name`	技能名称（唯一标识，建议用短横线分隔）
`description`	技能描述（会显示在技能列表中）
`homepage`	技能主页 URL（可选）
`metadata.openclaw.emoji`	技能图标 emoji
`metadata.openclaw.requires.bins`	需要的二进制文件（必须在 PATH 中）
`metadata.openclaw.requires.env`	需要的环境变量
`metadata.openclaw.requires.config`	需要的配置项（必须为 true）
`metadata.openclaw.primaryEnv`	主环境变量名（用于 apiKey 配置）
`metadata.openclaw.os`	支持的平台（darwin/linux/win32）

2. 技能指令（Markdown 正文）

Frontmatter 之后是技能的详细指令，告诉 AI 如何执行任务：

# 技能名称

## 触发条件

当用户请求 XXX 时，执行以下步骤：

1. 第一步做什么
2. 第二步做什么
3. ...

## 注意事项

- 安全提示
- 边界条件
- 错误处理

最佳实践：

指令要具体明确，避免模糊描述
包含错误处理和边界情况
如果涉及外部 API，说明认证方式
考虑安全性，避免命令注入风险

四、技能配置：openclaw.json

技能的全局配置在 ~/.openclaw/openclaw.json 的 skills 字段下：

{
  skills: {
    // 内置技能白名单（可选）
    allowBundled: ["gemini", "peekaboo", "sag"],
    
    // 技能加载配置
    load: {
      extraDirs: ["~/Projects/my-skills"],
      watch: true,              // 自动监听技能文件变化
      watchDebounceMs: 250      // 防抖时间（毫秒）
    },
    
    // 安装器配置
    install: {
      preferBrew: true,         // 优先使用 Homebrew
      nodeManager: "npm"        // Node 包管理器（npm/pnpm/yarn/bun）
    },
    
    // 单个技能配置
    entries: {
      "my-custom-skill": {
        enabled: true,
        apiKey: "sk-xxxxxxxx",  // 或者使用 SecretRef
        env: {
          MY_API_KEY: "xxxxx",
          CUSTOM_VAR: "value"
        },
        config: {
          customEndpoint: "https://api.example.com"
        }
      },
      "builtin-skill": {
        enabled: false  // 禁用内置技能
      }
    }
  }
}

apiKey 的两种写法

方式一：明文（不推荐用于生产环境）

apiKey: "sk-xxxxxxxx"

方式二：SecretRef（推荐）

apiKey: {
  source: "env",
  provider: "default",
  id: "MY_API_KEY"
}

五、技能 Gating 机制

OpenClaw 会在加载时根据技能元数据过滤技能，只有满足所有条件的技能才会被激活。

Gating 条件类型

条件类型	字段	说明
二进制文件	`requires.bins`	所有列出的二进制必须存在于 PATH
任意二进制	`requires.anyBins`	至少一个二进制存在即可
环境变量	`requires.env`	环境变量必须存在（或通过 config 提供）
配置项	`requires.config`	openclaw.json 中的配置必须为 true
操作系统	`requires.os`	仅在指定平台生效
强制启用	`always: true`	跳过所有 gating 检查

Gating 示例

---
name: macos-automation
description: macOS 自动化技能
metadata:
  {
    "openclaw": {
      "requires": {
        "bins": ["osascript"],
        "os": ["darwin"]
      }
    }
  }
---

这个技能只在 macOS 上激活，因为：

需要 osascript 二进制（macOS 特有）
os 限制为 darwin

六、安装和管理技能

方式一：使用 ClawHub（推荐）

ClawHub 是 OpenClaw 的官方技能市场：https://clawhub.com

# 安装技能
clawhub install <skill-slug>

# 更新所有技能
clawhub update --all

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

方式二：手动创建

# 创建技能目录
mkdir -p ~/.openclaw/workspace/skills/hello-world

# 创建 SKILL.md
cat > ~/.openclaw/workspace/skills/hello-world/SKILL.md << 'EOF'
---
name: hello-world
description: 一个简单的问候技能
---

# Hello World

当用户说"你好"或"打招呼"时，回复：
"你好！我是你的 AI 助手，有什么可以帮你的吗？"
EOF

方式三：从 Git 仓库克隆

cd ~/.openclaw/workspace/skills
git clone https://github.com/username/my-skill.git

七、技能开发实战：创建一个天气查询技能

步骤 1：创建目录结构

mkdir -p ~/.openclaw/workspace/skills/weather-query
cd ~/.openclaw/workspace/skills/weather-query

步骤 2：编写 SKILL.md

---
name: weather-query
description: 查询实时天气和预报
homepage: https://wttr.in
metadata:
  {
    "openclaw": {
      "emoji": "🌤️",
      "requires": {
        "bins": ["curl"]
      }
    }
  }
---

# 天气查询技能

## 功能

使用 wttr.in 服务查询全球任意城市的天气信息。

## 使用方法

当用户询问天气时：

1. 提取用户提到的城市名
2. 如果未指定城市，使用用户所在时区推断（或询问）
3. 执行命令：`curl wttr.in/<城市名>?format=%C+%t+%h+%w`
4. 将结果翻译成自然语言回复

## 输出格式示例

- 晴天：☀️ 北京 晴 25°C 湿度 45% 风速 10km/h
- 多云：☁️ 上海 多云 22°C 湿度 60% 风速 5km/h
- 雨天：🌧️ 广州 小雨 20°C 湿度 85% 风速 15km/h

## 注意事项

- 城市名使用拼音或英文（wttr.in 不支持中文城市名）
- 如果查询失败，告知用户并重试一次
- 可以提供 3 天预报：`curl wttr.in/<城市名>+3`

步骤 3：配置环境变量（可选）

如果技能需要 API Key，在 openclaw.json 中添加：

{
  skills: {
    entries: {
      "weather-query": {
        enabled: true,
        env: {
          WEATHER_API_KEY: "your-key-here"
        }
      }
    }
  }
}

步骤 4：测试技能

# 重启 Gateway 或等待自动刷新
openclaw gateway restart

# 测试技能
openclaw agent --message "北京今天天气怎么样？"

八、多 Agent 场景下的技能管理

在多 Agent 设置中，每个 Agent 有自己的工作区：

Agent 专属技能：放在 <agent-workspace>/skills
共享技能：放在 ~/.openclaw/skills（所有 Agent 可见）

技能冲突处理：

如果同名技能存在于多个位置，优先级为：

Agent 工作区 > 本地管理 (~/.openclaw/skills) > 内置技能

九、安全注意事项

⚠️ 重要：第三方技能视为不可信代码

审查技能代码：安装前仔细阅读 SKILL.md 和任何脚本
沙箱运行：对涉及外部输入的技能使用沙箱模式
最小权限：只授予技能必要的权限和环境变量
敏感操作确认：涉及删除、外部写入、数据导出的操作必须人工确认

沙箱配置示例

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          enabled: true,
          image: "node:22-alpine",
          setupCommand: "apk add --no-cache curl git"
        }
      }
    }
  }
}

十、技能性能与 Token 开销

技能列表会注入到系统提示中，产生固定的 Token 开销：

计算公式：

总字符数 = 195 + Σ(97 + name 长度 + description 长度 + location 长度)
Token 估算 ≈ 总字符数 / 4

示例：10 个技能，平均名称 20 字符、描述 50 字符、路径 80 字符

总字符数 = 195 + 10 × (97 + 20 + 50 + 80) = 195 + 2470 = 2665
Token 估算 ≈ 2665 / 4 ≈ 666 tokens

优化建议：

保持技能描述简洁（但要有信息量）
禁用不常用的技能
使用 allowBundled 白名单限制内置技能

十一、故障排查

技能不显示

检查 SKILL.md 的 YAML frontmatter 格式是否正确
确认 gating 条件是否满足（二进制、环境变量、配置项）
查看 Gateway 日志：openclaw gateway logs
尝试重启 Gateway：openclaw gateway restart

技能执行失败

检查所需的环境变量是否正确配置
确认二进制文件在 PATH 中：which <binary>
查看技能指令是否有语法错误
检查沙箱配置（如果启用了沙箱）

配置不生效

确认修改的是正确的配置文件（~/.openclaw/openclaw.json）
JSON5 格式是否正确（注意逗号、引号）
配置变更需要新会话才会生效（技能快照在会话开始时创建）

十二、进阶技巧

1. 使用 `{baseDir}` 引用技能目录

在技能指令中，可以用 {baseDir} 表示技能文件夹的绝对路径：

运行脚本：`{baseDir}/scripts/run.sh`

2. 技能安装器定义

在 frontmatter 中定义安装器，让用户可以一键安装依赖：

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

3. 用户可调用技能

通过 frontmatter 控制技能是否对用户可见：

---
name: admin-task
description: 管理员任务
user-invocable: false  // 用户不能直接调用
---

4. 命令直接分发到工具

---
name: quick-command
command-dispatch: tool
command-tool: system_exec
command-arg-mode: raw
---

十三、总结

OpenClaw 的技能系统是一个强大而灵活的扩展机制：

✅ 三层加载：工作区 > 本地 > 内置，灵活覆盖
✅ Gating 机制：根据环境自动过滤技能
✅ ClawHub 市场：一键安装社区技能
✅ 安全沙箱：隔离风险操作
✅ 多 Agent 支持：专属技能 + 共享技能

下一步行动：

浏览 ClawHub 发现有趣技能
尝试修改一个现有技能，理解结构
创建你的第一个自定义技能
分享你的技能到 ClawHub 社区

参考资料：

本文基于 OpenClaw 2026.3.12 版本编写，配置格式可能随版本更新而变化。

AI AI 工具