OpenClaw 创建技能(Skills) 的详细指南

meiyouruguo · 发表于昨天 17:41

# OpenClaw 创建技能(Skills) 详细指南

## 一、技能是什么？

技能(Skill) 是一个包含 `SKILL.md` 文件的目录，用于给 AI 智能体添加新能力。可以选择性地包含脚本或其他资源文件。

---

## 二、技能加载优先级

| 优先级 | 路径 | 说明 |
|--------|------|------|
| 最高 | `<workspace>/skills/` | 工作区级技能 |
| 中 | `~/.openclaw/skills/` | 用户级技能，所有 agent 共享 |
| 最低 | 内置 Skills | 随安装包自带 |

额外目录可通过 `skills.load.extraDirs` 配置添加。

---

## 三、创建技能步骤

### 1. 创建技能目录

```bash
mkdir -p ~/.openclaw/workspace/skills/my-skill
```

### 2. 编写 SKILL.md

`SKILL.md` 使用 **YAML frontmatter + Markdown** 格式：

```markdown
---
name: hello_world
description: A simple skill that says hello.
---

# Hello World Skill

When the user asks for a greeting, use the `echo` tool to say "Hello from your custom skill!".
```

### 3. SKILL.md Frontmatter 可用字段

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `name` | string | 必填 | 技能唯一标识 |
| `description` | string | 必填 | 技能描述 |
| `homepage` | string | 可选 | 网站 URL |
| `user-invocable` | boolean | `true` | 是否作为斜杠命令 `/skill-name` 暴露 |
| `disable-model-invocation` | boolean | `false` | 是否从模型提示中排除 |
| `command-dispatch` | string | 可选 | 设为 `"tool"` 时绕过模型直接调用工具 |
| `command-tool` | string | 可选 | 直接调用的工具名称 |
| `command-arg-mode` | string | `"raw"` | 参数转发模式 |

### 4. 元数据 Gating（条件加载）

在 frontmatter 中可以用单行 JSON 控制技能的加载条件：

```json
{
  "openclaw": {
"requires": {
   "bins": ["ffmpeg"],
   "env": ["MY_API_KEY"],
   "config": ["path.to.config"]
},
"primaryEnv": "MY_API_KEY",
"emoji": "🎬",
"os": ["darwin", "linux", "win32"]
  }
}
```

**requires 字段说明：**

- **bins** — 必须存在于 PATH 中的可执行文件
- **anyBins** — 至少有一个存在即可
- **env** — 必须设置的环境变量
- **config** — `openclaw.json` 中必须为真值的配置路径
- **os** — 限制运行平台（`win32`、`darwin`、`linux`）

### 5. 刷新技能

创建完成后，让 agent 刷新或重启网关：

```bash
# 方法1：通过 agent 命令
openclaw agent --message "refresh skills"

# 方法2：重启网关
openclaw gateway restart
```

---

## 四、自定义工具定义（高级）

如果需要在技能中定义自定义工具，可以通过插件方式注册：

```typescript
import { Type } from "@sinclair/typebox";

api.registerTool({
  name: "my_custom_tool",
  description: "自定义工具描述",
  parameters: Type.Object({
query: Type.String(),
count: Type.Optional(Type.Number()),
  }),
  async execute(_id, params) {
// 处理逻辑
const result = `处理: ${params.query}`;
return {
   content: [{
      type: "text",
      text: result
   }]
};
  },
});
```

**返回格式：** `{ content: [{ type: "text", text: "结果" }] }`

**注意事项：**
- 工具名不得与核心工具重名
- 涉及副作用或需额外依赖的工具建议设置 `optional: true`
- 参数定义支持 `@sinclair/typebox` 库或标准 JSON Schema

---

## 五、技能配置（openclaw.json）

在 `~/.openclaw/openclaw.json` 中可以对每个技能单独配置：

```json5
{
  "skills": {
"load": {
   "extraDirs": ["/path/to/extra/skills"],
   "watch": true,
   "watchDebounceMs": 250
},
"install": {
   "nodeManager": "npm"  // 可选: npm, pnpm, yarn, bun
},
"entries": {
   "my-skill": {
      "enabled": true,
      "env": {
      "MY_API_KEY": "your-key-here"
      },
      "apiKey": {
      "source": "env",
      "id": "MY_API_KEY"
      },
      "config": {
      "customField": "value"
      }
   }
}
  }
}
```

**配置字段说明：**

| 字段 | 说明 |
|------|------|
| `load.extraDirs` | 额外的技能扫描目录 |
| `load.watch` | 是否启用技能目录监视（默认 true） |
| `load.watchDebounceMs` | 文件监视防抖间隔（默认 250ms） |
| `install.nodeManager` | 依赖管理器选择（npm/pnpm/yarn/bun） |
| `entries.<name>.enabled` | 启用/禁用技能 |
| `entries.<name>.env` | 注入环境变量（仅主机运行时） |
| `entries.<name>.apiKey` | API 密钥配置 |
| `entries.<name>.config` | 自定义配置字段 |

---

## 六、测试技能

```bash
# 本地测试
openclaw agent --message "use my new skill"
```

---

## 七、从 ClawHub 安装社区技能

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

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

# 同步所有技能
clawhub sync --all
```

默认安装到 `./skills` 或配置的 OpenClaw 工作区。

---

## 八、最佳实践

1. **简洁明了** — 告诉模型做什么，不要教它如何"成为 AI"
2. **安全第一** — 如果技能使用 bash，确保防范命令注入
3. **本地测试** — 发布前用 `openclaw agent --message` 测试
4. **第三方技能** — 将第三方技能视为不受信任的代码，启用前先阅读
5. **工具命名** — 自定义工具名不得与核心工具重名

---

## 九、参考链接

- 创建 Skills（中文）：https://docs.openclaw.ai/zh-CN/tools/creating-skills
- Creating Skills（英文）：https://docs.openclaw.ai/tools/creating-skills
- Skills Config：https://docs.openclaw.ai/tools/skills-config
- Skills 概览：https://docs.openclaw.ai/tools/skills
- Plugin Agent Tools：https://docs.openclaw.ai/plugins/agent-tools
- ClawHub：https://docs.openclaw.ai/tools/clawhub

		自动登录	找回密码
密码			立即注册

OpenClaw 创建技能(Skills) 的详细指南

突出会员

丹神