OpenClaw 技能开发：从零创建你的第一个 AI 技能

很多人第一次接触 OpenClaw，最先感受到的是“它能帮我自动做很多事”。

但如果你继续往下用，很快就会碰到一个问题：

默认能力不一定刚好覆盖你的真实需求。

比如你可能会想让它：

• 查询你常用系统里的业务数据
• 操作你自己的文件结构
• 连接某个内部 API
• 把一段固定流程封装成一条命令

这时候，OpenClaw 的“技能（Skill）”机制就真正体现价值了。

技能本质上就是：把一个明确能力，封装成 AI 助手可以调用的模块。

这篇文章不讲空概念，直接带你从零写出第一个能跑起来的 OpenClaw 技能。

一、什么是 OpenClaw 技能？

你可以把技能理解成 OpenClaw 的“能力插件”。

它解决的是一个核心问题：

怎么让 AI 助手不只是会聊天，而是真的会做某一类事情？

比如，一个天气技能可以：

• 接收“查询上海天气”的请求
• 调用天气 API
• 返回结构化结果

一个文件整理技能可以：

• 接收“把下载目录里的 PDF 分类归档”的请求
• 扫描本地文件
• 执行重命名和移动

一个团队协作技能可以：

• 接收“汇总今天 Slack 里的待办”
• 读取指定消息源
• 提炼并输出结论

从这个角度看，技能不是“给 AI 加设定”，而是给 AI 增加真实的执行能力。

二、为什么要自己写技能？

因为越往真实场景走，越需要定制化。

默认能力通常适合通用需求，但你自己的工作流往往有很多个性化细节：

• 你有自己的接口
• 你有自己的数据格式
• 你有自己的目录结构
• 你有自己的业务规则

这些东西不可能全靠通用能力覆盖。

所以，只要你想让 OpenClaw 更贴近自己的工作方式，最终都会走到技能开发这一步。

三、写第一个技能前，要先想清楚什么？

不要一上来就写复杂逻辑。

第一个技能最重要的不是“功能很多”，而是“边界清晰”。

你最好先用一句话定义它：

这个技能到底负责解决哪一类问题？

例如：

• 查询天气
• 创建待办
• 整理文件
• 获取日报数据

一个好技能通常有三个特征：

1. 输入明确

用户要给它什么参数？

例如：

• 城市名
• 日期
• 文件路径
• 任务标题

2. 输出明确

它最后应该返回什么结果？

例如：

• 一段天气摘要
• 一个成功/失败状态
• 一个文件列表
• 一份结构化 JSON

3. 责任明确

它只做这一件事，不顺手承担别的职责。

第一个技能一定要小。

技能越小，越容易调通；越容易调通，你越容易继续写下一个。

四、一个典型技能的目录结构

如果你从零开始，建议先用一个最简单的结构：

my-first-skill/
├── SKILL.md
├── package.json
├── src/
│   └── index.js
└── examples/
    └── demo.md

各文件职责可以这样理解：

• SKILL.md：技能说明，告诉 OpenClaw 这个技能做什么、什么时候用
• package.json：依赖配置
• src/index.js：技能主逻辑
• examples/：示例输入输出，方便你调试

如果技能更复杂，再继续拆分模块，不要一开始就搞太重。

五、先做一个最小可运行版本

下面我们以“天气查询技能”为例。

目标非常简单：

• 输入一个城市名
• 返回这个城市的天气描述

你可以先写一个假实现，别急着接 API。

export async function getWeather(city) {
  return {
    city,
    condition: '晴',
    temperature: '26C',
    advice: '适合出门，注意补水'
  };
}

然后加一个调用入口：

import { getWeather } from './weather.js';

async function main() {
  const city = process.argv[2] || '上海';
  const result = await getWeather(city);

  console.log(`${result.city}天气：${result.condition}`);
  console.log(`温度：${result.temperature}`);
  console.log(`建议：${result.advice}`);
}

main().catch(console.error);

这样做的好处是：

• 你先验证技能结构有没有问题
• 再验证调用链路有没有问题
• 最后再接真实 API

这个顺序非常重要。

很多人第一个技能写不动，不是因为不会写代码，而是一上来把“架构、接口、部署、调试”全搅在一起了。

六、怎么把逻辑写得更像一个“技能”？

技能和普通脚本的区别，在于它最终是给 AI 助手调用的。

所以你写的时候，要特别注意两件事：

1. 输入要可预测

不要让技能的输入太随意。

比如：

async function createTodo(title, deadline) {
  if (!title) throw new Error('缺少待办标题');
  return { success: true, title, deadline };
}

比起“什么都能传，靠内部猜”，这种明确输入更适合技能系统。

2. 输出要结构化

不要只返回一大段难以处理的自然语言。

更好的做法是：

return {
  success: true,
  city,
  weather: condition,
  temperature,
  advice
};

结构化输出更容易：

• 被后续步骤继续使用
• 被其他技能组合
• 被 OpenClaw 在多轮流程里引用

七、调试第一个技能时，最容易踩哪些坑？

这是新手最常见的几个问题。

1. 技能边界太大

一开始就想做“万能工具”，结果什么都没调通。

2. 输入格式不稳定

用户一句话里有很多自然语言变化，结果你的技能根本不知道该接什么参数。

3. 错误处理缺失

一旦 API 超时、路径不存在、字段为空，整个技能直接崩掉。

4. 输出不适合复用

写成了人类读得懂、机器不好接的格式，后续很难接到自动化工作流里。

调试建议很简单：

• 先用假数据跑通
• 再接真实数据
• 每一步都打印清楚输入和输出
• 先保证稳定，再追求优雅

八、写完后怎么让它真正能用？

写完技能代码，不等于技能已经“好用”。

你至少还要确认下面几件事：

1. 文档写清楚

SKILL.md 里要说明：

• 这个技能做什么
• 什么时候调用
• 需要什么参数
• 输出是什么

2. 示例要能跑

至少准备 2 到 3 个真实例子。

例如：

• 查询上海天气
• 查询北京天气
• 不传城市时走默认值

3. 错误场景要覆盖

比如：

• 输入为空
• API 返回失败
• 请求超时

这些都应该有明确处理。

九、什么时候该写第二个技能？

当你第一个技能能稳定完成一件小事时，就可以继续扩展了。

我建议第二个技能优先从下面三类里选：

• 文件处理类
• API 查询类
• 提醒/待办类

原因很简单：

• 需求明确
• 结果直观
• 很容易和实际工作结合

一旦你连续写出两个能真用的技能，对 OpenClaw 的理解就会发生变化。

它不再只是“一个 AI 助手”，而是开始变成“一个可扩展的自动化平台”。

十、结语：第一个技能，不求复杂，只求跑通

很多技术文章都喜欢把“从零开始”写得很宏大。

但真正落地时，第一步从来不需要宏大。

你第一个 OpenClaw 技能的目标，应该只是：

• 能接收输入
• 能执行逻辑
• 能稳定返回结果

只要这一步成功了，后面的 API 接入、文件操作、工作流编排，都会顺很多。

技能开发真正重要的，不是一次写出多厉害的东西，而是建立起一种习惯：

发现一个重复问题，就把它封装成一个可复用能力。

当你开始这样使用 OpenClaw，它就不再只是一个会回答问题的 AI，而会慢慢变成你真正能扩展、能协作、能接入业务的助手平台。

---

如果你愿意，我下一篇可以继续写：
《OpenClaw 技能开发实战：做一个可查询天气的真实技能》，从假数据版本一步升级到调用真实 API 的版本。