OpenClaw Skill 完全指南：让 AI 助手从"裸奔"到"满配"

用比米云搜索 Skill 为例，手把手教你理解、编写、发布 OpenClaw Skill

---

一、OpenClaw 很强，但它也会"裸奔"

想象一下，你雇了一个过目不忘的学霸。他精通 Python、Go、Java、SQL，能写代码、做推理、翻译八国语言。但——

他没连网。

你问他：“帮我搜一下今天 AI 圈有什么大事？”

他说：“抱歉，我上次联网的时候还是 GPT-3.5。”

这就叫 AI 裸奔。本事大，但使不出来。

OpenClaw Skill 就是给这个学霸接上一根网线。 有了 Skill，它就能搜索网页、查询天气、调用各种 API——从一个"知识渊博但两耳不闻窗外事"的学霸，变成一个"能干活、能办事"的实干派。

---

二、Skill 到底是什么？

一句话定义：

Skill 就是一个文件夹，里面有一份"说明书"（SKILL.md）和一个"干活的脚本"。它告诉 OpenClaw：“当你遇到某类任务时，运行这个脚本，把结果拿给我。”

Skill 能干什么？

• 搜索：联网搜网页、新闻、论文
• 查询：查天气、查股票、查汇率
• 操作：发邮件、创建 Jira ticket、发 Slack 消息
• 转换：把 PDF 转文本、把图片转 Markdown
• 任何你能用脚本做的事

本质上，Skill 就是把"你自己手动跑脚本"这件事自动化了。以前你需要打开终端、敲命令、看结果、复制给 AI；现在你说句话，AI 帮你跑。

---

三、Skill 是怎么工作的？

整个过程可以分成四步，我们用一个真实场景串起来：

用户：“帮我搜一下如何学习 Go 语言”

第一步：触发（“这个活归我管”）

OpenClaw 拿到用户的话后，会扫描所有已安装的 Skill，逐个看它们的 description 字段。

比米云搜索的 description 大概这么写的：

当用户需要搜索网页信息、查找特定主题的资料、说出"搜索"、“查找”、“搜索一下”、“帮我搜”、"查一下"等关键词时……

“搜索”——命中。OpenClaw 一拍大腿：“这个活归 bimiyun-search 管。”

这里的 trick 是：description 写得越详细、覆盖的关键词越多，触发就越准。 只写"搜索 API"是不够的，要把用户可能说的各种说法全列上——“搜一下”、“查查”、“帮我找找”，这些都是用户的自然表达。

第二步：加载（“让我看看需要什么工具”）

锁定目标后，OpenClaw 会读取 SKILL.md 的全部内容，并检查 metadata 里声明的依赖：

metadata: {"openclaw":{"emoji":"🔍","requires":{"bins":["python"],"env":["BIMIYUN_API_KEY"]}}}

翻译一下：

• bins: ["python"] —— 我需要 Python 能跑
• env: ["BIMIYUN_API_KEY"] —— 我需要 API Key 才能调用接口

如果 Python 没装、API Key 没配，OpenClaw 会直接告诉你，而不是傻乎乎地去跑然后报错。

第三步：执行（“干活了”）

OpenClaw 按照 SKILL.md 里写的使用说明，实际运行脚本：

用户："帮我搜一下如何学习Go语言"
         ↓
OpenClaw 匹配到 bimiyun-search Skill
         ↓
检查 Python 是否可用、API Key 是否已配
         ↓
运行命令：python scripts/bimiyun_search.py --query "如何学习Go语言"
         ↓
脚本 POST 请求到 https://search.bimiyun.com/api/web
         ↓
API 返回 JSON 格式的搜索结果
         ↓
脚本将结果转成 Markdown 格式，输出到 stdout
         ↓
OpenClaw 读取输出内容

整个流程里，OpenClaw 就是个聪明的调度员——它不干脏活，脏活是脚本干的。脚本跑完，stdout 吐出来的结果就是 OpenClaw 能看懂的"原材料"。

第四步：返回（“交差了”）

脚本输出什么，OpenClaw 就看到什么。

如果输出是 Markdown，OpenClaw 可以直接展示给用户，或者加点自己的话包装一下：

我帮你搜了一下，找到以下几篇关于 Go 语言学习的内容：

1. Go 语言入门教程 - 菜鸟教程
   https://example.com/go-tutorial
   • 这是一篇适合初学者的完整教程…

如果输出是 JSON，OpenClaw 会解析后组织成更易读的形式。

对用户来说，感觉就像 OpenClaw"自己"上网搜了一样。 其实背后跑的是你的脚本，但用户不需要知道——这就是 Skill 的魅力。

---

四、目录结构：简单就是美

我的比米云搜索 Skill，目录结构极简：

bimiyun-search/
├── SKILL.md                  # 说明书：什么时候用、怎么用
└── scripts/
    └── bimiyun_search.py     # 干活的：发请求、处理结果

就两个文件。没有花里胡哨的配置，没有几十个 JSON 互相引用。能跑就行。

SKILL.md —— 灵魂所在

---
name: bimiyun-search
description: "比米云搜索：快速检索网络信息并返回LLM友好的数据..."
metadata: {"openclaw":{"emoji":"🔍","requires":{"bins":["python"],"env":["BIMIYUN_API_KEY"]}}}
---

frontmatter 就三个字段：

字段	作用	一句话解释
name	唯一标识	别跟别人的 Skill 重名
description	触发条件	最重要的字段——写不好就触发不了
metadata	环境依赖	需要什么工具、什么密钥

下面就是正常的 Markdown 使用说明：怎么拿 API Key、怎么配、快速开始、参数说明。既是给 AI 看的，也是给人看的。

scripts/bimiyun_search.py —— 苦力担当

这个脚本做了四件事：

1. load_key() / load_endpoint() —— 从环境变量或 .env 文件加载配置。优先级：环境变量 > .env 文件
2. BimiyunSearch.search() —— 核心方法。拼 payload、发 POST、解析 JSON 响应
3. to_markdown() —— 把 API 返回的 {"organic": [...]} 转成人能读的 Markdown 列表
4. main() —— 命令行入口，用 argparse 解析参数，支持 --query、--format、--max-results 等选项

关键设计：只用 Python 标准库。 urllib + json，没有任何第三方依赖。用户拿到就能跑，不用 pip install，不用等下载。这才是好 Skill 该有的样子。

---

五、编写 Skill 的避坑指南

坑一：description 写得太短

反面教材：

description: "A search tool."

OpenClaw 看到这句话的反应：“然后呢？什么时候用？用户会怎么说？”

正面教材：

description: "当用户需要搜索网页信息、查找资料、说出'搜索'、'查找'、'搜索一下'、
'帮我搜'、'查一下'、'需要查找'、'搜索内容'、'搜索资料'等关键词时，以及需要从互联网
获取答案的任何情况。"

区别就是：前者像个敷衍的产品简介，后者像个贴心的使用手册。

坑二：脚本输出不够干净

反面教材：

print("正在搜索...")
print(f"搜索词：{query}")
print("搜索完成！")
print(json.dumps(results))

OpenClaw 拿到的是四行文本，前三行是废话，只有最后一行是数据。它还得自己解析。

正面做法：

# 只输出结果，一行多余的 print 都没有
sys.stdout.buffer.write(output.encode('utf-8'))

记住一条：脚本的 stdout 是给 OpenClaw 吃的，不是给用户看的。 干净的数据 = 好的回答质量。

坑三：密钥硬编码

反面教材：

API_KEY = "ak-123456789abcdef"

这代码一提交到 GitHub，你的 Key 就暴露了。十分钟后，别人的爬虫就把它扒走开始消费你的额度。

正面做法：

key = os.environ.get("BIMIYUN_API_KEY")
if not key and os.path.exists(".env"):
    # 从 .env 文件读取
    ...
if not key:
    raise ValueError("BIMIYUN_API_KEY 未找到，请先配置 API Key")

坑四：网络请求不设超时

反面教材：

resp = urllib.request.urlopen(req)  # 没有 timeout

如果 API 挂了，这行代码会永远等下去。OpenClaw 会一直转圈圈，用户以为它卡死了。

正面做法：

resp = urllib.request.urlopen(req, timeout=30)  # 30 秒超时

---

六、发布到各平台：一次编写，到处发布

OpenClaw Skill 的好处是——你只要写好了 SKILL.md + 脚本，就能发到一堆地方。下面是各个平台的特点：

6.1 GitHub：老家

这是 Skill 的"根"，所有其他平台都从这里拉代码。

注意事项：

• README 写清楚：干什么的、怎么装、要什么依赖
• .env 绝对不能提交，但放一个 .env.example 当模板
• .gitignore 加上 __pycache__/、.env、*.pyc
• 加 LICENSE，推荐 MIT
• 如果用了第三方库，放 requirements.txt

发布步骤就四行：

echo -e ".env\n__pycache__/\n*.pyc" > .gitignore
echo "BIMIYUN_API_KEY=your-key-here" > .env.example
git init && git add . && git commit -m "Initial commit: bimiyun-search skill"
git push -u origin main

6.2 skills.sh：一条命令安装

用户只需要：

npx skills add https://github.com/你的用户名/bimiyun-search-skill

注意事项：如果需要 npm 生态支持，加一个 package.json，main 指向入口文件就行。

6.3 clawhub：OpenClaw 的"应用商店"

这是 OpenClaw 生态的核心 Skill 市场。

注意事项：

• name 必须全局唯一，发布前去 clawhub 搜一下有没有重名
• 描述第一句话就要抓人——用户扫一眼就要知道这 Skill 干啥的
• 标注免费额度、是否有付费方案
• 版本号遵循 semver，每次更新改版本号

6.4 skill-cn / skillhub.tencent：中文用户的主场

面向国内开发者的 Skill 分发平台。

注意事项：

• 文档用中文，或者中英双语
• 错误信息也写中文——用户看到中文报错好排查
• 如果 API 有国内节点，文档中标出来
• 合规要求：安全搜索默认开启，别搞花里胡哨的默认关闭

6.5 多平台发布清单

发布前过一遍，不翻车：

• name 全局唯一（去各平台搜过了吗？）
• .env 不在仓库里（git status 看过了吗？）
• LICENSE 有了吗？
• README / SKILL.md 使用说明写清楚了吗？
• 入口文件路径对吗？
• 版本号更新了吗？

---

七、常见问题

Q：我的 Skill 没被触发怎么办？

去 description 里加关键词。OpenClaw 靠语义 + 关键词匹配，description 写得越像用户会说的话，触发越准。

Q：脚本执行报错？

OpenClaw 能看到 stderr。确认三件事：环境变量配了没、Python 能不能跑、依赖装了没。

Q：一个 Skill 能不能调用另一个？

别这么干。每个 Skill 应该独立、自包含。需要组合功能？写到一个脚本里。

Q：怎么本地调试？

export BIMIYUN_API_KEY=your-key
python scripts/bimiyun_search.py --query "测试搜索" --format md

能直接看到 Markdown 输出，就说明脚本没问题。

Q：脚本用第三方库行不行？

行，但不推荐。用户还得先 pip install，门槛高了一层。能用标准库就用标准库，实在不行在 SKILL.md 里醒目地写上安装步骤。

---

八、总结

写一个 OpenClaw Skill，说复杂也复杂，说简单也就三件事：

1. SKILL.md —— 告诉 OpenClaw"我是什么、什么时候用我、怎么用我"。这是灵魂。
2. 脚本 —— 实现功能，输出干净数据。这是苦力。
3. 发布 —— 推到 GitHub，让各平台来拉。这是广而告之。

比米云搜索就是一个很好的起点：两个文件、零依赖、能跑、好用。从这里出发，你的下一个 Skill 可能就是一个天气查询、一个翻译工具、一个代码审查助手——只要你能写成脚本，就能变成 Skill。

动手试试吧，给你的 OpenClaw 装上新技能。毕竟，谁会喜欢一个"裸奔"的 AI 呢？