带 API 的 Skill 开发
普通 Skill 是"龙虾的常用动作脚本"。带 API 的 Skill 是龙虾跟外部世界沟通的神经——查询数据、调外部服务、推送结果，都靠它。
这篇讲怎么用对话让龙虾帮你写一个带 API 调用的 Skill——你只说诉求，龙虾负责生成代码、配置 manifest、测试、调试。你看懂产物长啥样就行，不用自己敲。
前置条件
- 读完 指挥中枢模式，理解"龙虾决策、外挂执行"的分工
- 有一个想集成的 API（任何 REST API 都行，例子用"天气 API"）
一、Skill 的本质
Skill 不是黑魔法，就是两样东西：
- 一段可执行代码（Python / bash / Node，随便）
- 一份 manifest（声明这个名字、接受什么参数、在哪里找代码）
龙虾收到指令时，按 manifest 找到对应 skill，把参数传进去执行，把 stdout 当返回值。就这样。
Skill 的目录结构长这样：
~/.openclaw/skills/
weather/
skill.yaml ← manifest
main.py ← 实际代码
requirements.txt ← Python 依赖（可选）二、用对话让龙虾帮你写一个 Skill
对龙虾说：
帮我写一个 Skill，功能是"查询某城市的当前天气"。
需求：
- 输入：城市名（中文或拼音都行）
- 数据源：wttr.in（https://wttr.in/<city>?format=j1）
- 输出：JSON 格式，含城市、温度（摄氏度）、湿度、天气描述
- 错误处理：网络超时 10 秒；API 失败时返回 {"ok": false, "error": "..."}
- 密钥管理：从环境变量读 WEATHER_API_KEY（虽然 wttr 不需要，但留个 hook 备以后换 provider）
请：
1. 在 ~/.openclaw/skills/weather/ 下创建 skill.yaml 和 main.py
2. 写完后立刻在命令行跑一次"python3 main.py --city 北京"验证能返回 JSON
3. 把测试输出贴给我看
4. 如果有报错，自己先尝试修复，修不好再问我龙虾会做什么
龙虾会按指令一步步执行。你可以让它展示产物确认：
把生成好的 skill.yaml 和 main.py 完整展示给我看一下。龙虾会贴出类似这样的产物：
skill.yaml（manifest，告诉龙虾这个 skill 叫什么、怎么调）：
name: weather
description: 查询某城市的当前天气
parameters:
- name: city
type: string
description: 城市名（中文或拼音），例如 "北京" 或 "beijing"
required: true
command: python3 {{skill_dir}}/main.py --city "{{city}}"main.py（实际代码，调 API + 返回 JSON）：
import argparse
import json
import os
import sys
import urllib.request
def main():
parser = argparse.ArgumentParser()
parser.add_argument("--city", required=True)
args = parser.parse_args()
url = f"https://wttr.in/{args.city}?format=j1"
try:
with urllib.request.urlopen(url, timeout=10) as resp:
data = json.loads(resp.read())
except Exception as e:
print(json.dumps({"ok": False, "error": f"weather API failed: {e}"}))
sys.exit(1)
current = data["current_condition"][0]
print(json.dumps({
"ok": True,
"city": args.city,
"temp_c": current["temp_C"],
"humidity": current["humidity"],
"desc": current["weatherDesc"][0]["value"],
}))
if __name__ == "__main__":
main()你看一眼产物对不对，对就让龙虾正式启用。
三、密钥管理：不要硬编码
新手最常犯的错——把 API key 写死在 main.py 里。问题：① key 会随 skill 同步/分享出去；② 改 key 要改代码；③ git 里留痕。
正确做法——在对话里明确：
Skill 里的密钥必须从环境变量读，绝不能硬编码。具体：
- 代码里用 os.environ.get("XXX_API_KEY") 读
- 如果环境变量没设置，返回 {"ok": false, "error": "XXX_API_KEY env not set"}
- 把要用的密钥名告诉我，我加到 ~/.openclaw/.env 里密钥进龙虾上下文的风险
如果你的 skill 把 API key 打印到 stdout（比如调试时 print(f"using key: {API_KEY}")），key 会进入龙虾的对话记忆，后续可能在其他对话里漏出来。
铁律：密钥永远不打印。如果调试需要，写到 stderr 或日志文件，不要 stdout。
在对话里强调这一点：
注意：密钥永远不打印到 stdout。如果调试要看，写日志到 ~/.openclaw/logs/xxx.log。四、错误处理：3 条规则
让龙虾写 skill 时，把这 3 条规则写进对话：
规则 1：永远返回 JSON
不管成功失败，stdout 必须是合法 JSON。这样龙虾能稳定解析。
成功返回 {"ok": true, "data": ...}，失败返回 {"ok": false, "error": "...", "code": "..."} 并 exit 1。规则 2：区分"业务失败"和"系统失败"
错误分两类，用不同的 exit code：
- 业务失败（如"城市不存在"、"无权限"）：exit 1，不需要重试
- 系统失败（如"API 超时"、"网络断开"）：exit 2，可以重试规则 3：网络请求必须超时
所有网络请求必须有 timeout 参数（建议 5-10 秒），不要用默认无超时。
龙虾等 skill 的默认超时是 60 秒，skill 内部超时要比这个小。五、入参/出参 Schema
入参：在 manifest 里声明
skill.yaml 的 parameters 字段，每个参数要写清楚：
- name：参数名
- type：类型（string / integer / boolean）
- description：人类可读的描述（这个很重要，龙虾根据 description 决定什么时候用这个 skill）
- required：是否必填
- default：默认值（可选）description 重要——龙虾根据它判断什么时候用这个 skill、传什么参数。写得越具体，龙虾调用越准。
出参：约定一个稳定结构
所有 skill 的 stdout 统一结构：
成功：{"ok": true, "data": {...}, "metadata": {"latency_ms": ..., "provider": ...}}
失败：{"ok": false, "error": "...", "code": "...", "retry_after_seconds": 60}
retry_after_seconds 是可选的——告诉调用方"60 秒后再试"。六、调试
1. 让龙虾自己测
请测试一下 weather skill：
1. 直接跑 python3 ~/.openclaw/skills/weather/main.py --city 北京
2. 把 stdout 完整贴给我
3. 如果失败，先自己排查（看错误信息、对照代码、尝试修复）
4. 修好了再测，修不好告诉我具体卡在哪2. 让龙虾解释为什么失败
weather skill 调用失败了，错误是"timeout"。
请帮我分析：
- 是 wttr.in 服务慢？
- 是我们这边的网络问题？
- 是代码里的 timeout 设太短？
- 给我修复建议3. 日志独立写
帮 weather skill 加日志：
- 用 Python logging 模块
- 日志写到 ~/.openclaw/logs/weather.log
- 记录每次调用的输入、latency、结果摘要（不要记敏感字段）
- 这样调试时跟龙虾主日志分离，单独看七、发布与共享
自己用
放到 ~/.openclaw/skills/〈name〉/ 下，龙虾立刻能用。
团队/社区共享
帮我把 weather skill 打包发布到 clawhub。
发布前检查：
- [ ] manifest 的 description 写清楚
- [ ] 没有硬编码密钥
- [ ] 依赖写进 requirements.txt
- [ ] 错误返回都是合法 JSON
- [ ] 网络请求都带超时
- [ ] 加一份简短的 README.md 说明用法
全部 OK 再发布。其他人就能通过 openclaw skill install weather 装上。
八、下一步
- 集成常见外部系统的 cookbook：外挂集成 Cookbook
- 主 agent + 多 skill + 外挂的协同模式：多 Agent + 外挂协同
- 生产环境部署：生产部署实战
