Adventure 3 - 用 API 教 AI 新技能

1 / 32
Adventure 3 - 用 API 教 AI 新技能
欢迎来到目前为止最酷的一段编程冒险。今天，你要教 AI 几招超能力：查天气、讲笑话、探索互联网。不需要魔法——只需要一组叫 API 的小聪明。
openclaw agent --local --agent main --session-id fresh-001 --message "tell me the current working directory"
Adventure 1
2 / 32
悬念挑战
本节大问题
天气 app 是怎么知道明天会下雨的？翻译软件是怎么瞬间就把语言换掉的？OpenClaw 没改一行代码，怎么就越变越聪明的？
答案是： API  —— 把互联网上一切东西连起来的那个秘密配方。
🤔 想一想：你常用的哪一个 app，看起来像是「凭空」就知道了来自别处的信息？
Adventure 1
3 / 32
API 究竟是什么？
餐厅类比
想象你在餐厅吃饭。你不需要：
走进厨房
懂怎么做菜
了解配方机密
你只是看一眼 菜单，点你想要的，再等它端到桌上。
API 也是一样的逻辑
API 就是给计算机用的菜单。你的程序不需要知道另一边的服务是怎么实现的——只需要知道要点什么、怎么点。
API 会把你点的东西原样端回来。
Adventure 1
4 / 32
三个主要角色
你（顾客）
你的程序或 app，需要某些信息
API（菜单）
可点的请求列表，以及怎么点的说明
服务器（厨房）
处理你的请求、再把数据送回来的那台计算机
你发起一次 API 请求，本质上是在说：「服务器你好，能不能把这一条具体的信息给我？」服务器处理完请求，再把你要的数据送回去。
Adventure 1
5 / 32
动手试几个真的 API！
该让 API 跑起来了。打开浏览器，访问下面这几个有趣又免费的 API，看看你「从菜单上点单」时会发生什么。
🌤️ 天气 API
https://wttr.in/Beijing
试试把「Beijing」换成你所在的城市。
😄 冷笑话 API
https://icanhazdadjoke.com/
每刷新一次都是一个新笑话
📍 IP 信息 API
https://ipinfo.io/json
查看你这次上网的地理位置信息
Adventure 1
6 / 32
看懂 HTTP GET 请求
返回响应
服务器处理
请求在路上
浏览器 GET
当你在浏览器里输入一个 URL，其实就是在发送一个 GET 请求。这是最常见的一种 API 请求，意思就是：「请把这条信息 GET（取）回来给我。」
把它想成举手提问：你在请求信息，服务器给出回答。
Adventure 1
7 / 32
暗号般的语言：JSON
JSON = JavaScript Object Notation（JavaScript 对象表示法）
API 之间说的是一种叫 JSON 的特殊语言。第一眼看着有点怪，搞懂之后，你会发现整张互联网到处都在用它。
JSON 用一种结构化的方式组织信息：花括号 {}、方括号 []、还有键值对。把它想成一个高度有序的文件柜，每样东西都有自己固定的位置。
Adventure 1
8 / 32
JSON：俄罗斯套娃式比喻
JSON 是怎么工作的
想象俄罗斯套娃：
最外层的盒子 = 那对大的花括号 {}
里面的小盒子 = 更多的 {} ，装着相关的数据
深处的宝物 = 你真正想要的那条信息
每一个「盒子」都有一张标签（叫做 键），盒子里装着内容（叫做 值).
{

  "weather": {

    "temperature": "22°C",

    "condition": "sunny",

    "wind": {

      "speed": "10 km/h"

    }

  }

}
Adventure 1
9 / 32
动手做 1
探索天气 JSON 数据
亲手玩玩真实的 JSON 吧！打开终端，输入这条命令：
curl https://wttr.in/Beijing?format=j1
你会看到一坨嵌套的数据。你的任务：从这份 JSON 输出里找出下面三条信息。
1
当前温度
找类似「temp_C」或「temperature」的字段
2
天气描述
找像「sunny」「cloudy」「rainy」这样的词
3
风速
搜索「wind」或「windspeed」相关的字段
⏱️ 时间：5–7 分钟。卡住了就和同伴一起做。
Adventure 1
10 / 32
像侦探一样读 JSON
从最外层的花括号开始
找到那对最大的 {} ，把所有东西都包在里面的那一对
找熟悉的词
键通常会说明值是什么：「temperature」「wind」等等
顺着路径走
从外层盒子一层层钻进去，直到找到你要的数据
取走值
冒号后面的内容 : 就是你要的。
Adventure 1
11 / 32
快速核对
几道题：测一下你的理解
问题 1： 如果 API 像餐厅菜单，那你点了菜单上没有的东西会怎样？
问题 2： 你觉得计算机为什么要用 JSON，而不是直接用普通句子？
问题 3： 你能想到三个大概率在通过 API 获取信息的场景吗？
和同桌讨论 3 分钟，之后我们一起分享。
Adventure 1
12 / 32
关键概念揭晓
API 连接一切
它让不同程序彼此对话、共享信息
API 守住安全边界
你能拿到数据，但不会直接接触到背后的数据库或「厨房」
JSON 让标准统一
大家说同一种数据语言，交换起来才容易
GET 请求足够简单
用一个 URL 提出你要的内容，服务器就会回应
Adventure 1
13 / 32
酷的部分来了：教 OpenClaw！
你已经知道 API 是什么、怎么工作。激动人心的部分来了 —— 我们要教 OpenClaw 怎么使用 API。
就像你看说明学新技能一样，我们也给 OpenClaw 写一份「技能手册」，教它怎么去取天气信息。
Adventure 1
14 / 32
SKILL.md 是什么？
想想培训新员工
新人入职时，你会给他一本手册或培训资料，对吧？
SKILL.md 就是 OpenClaw 的培训手册。
一份 SKILL.md 文件会告诉 AI：
什么时候 该使用这个技能（触发词）
要做什么 步骤
怎么做 处理回来的信息
怎么做 回应用户
用的是人类和 AI 都看得懂的简洁语言。
Adventure 1
15 / 32
创建你的第一个技能：天气预报员
01
为技能建一个文件夹
进入 skills 目录，新建一个名为 weather 的文件夹
02
创建 SKILL.md 文件
这个文件会装下天气技能所需的全部说明
03
写入指令
把要做的事一步一步告诉 OpenClaw
04
测试你的新技能
重启 OpenClaw，向它问问天气试试。
Adventure 1
16 / 32
第 1 步与第 2 步：把文件夹建好
打开终端，仔细输入下面这几条命令：
which openclaw

cd ~/.openclaw/workspace

mkdir weather

vim weather/SKILL.md
这会在 skills 目录里建一个叫「weather」的新文件夹，然后打开一个文本编辑器，让你在里面写技能说明。
💡 小贴士：不熟悉 vim 也没关系，可以用 nano 或者任何你顺手的编辑器。
Adventure 1
17 / 32
第 3 步：写下天气技能
把下面的内容复制到你的 SKILL.md 文件里。每一节都在告诉 OpenClaw 一件重要的事。
# Weather Query Skill



## Trigger Words

User mentions "weather", "temperature", "rain", "forecast"



## Steps

1. Get the city name from the user's question

2. Call: curl https://wttr.in/{city}?format=j1

3. Parse the JSON response

4. Tell the user in a friendly way



## Example

User: "What's the weather in Tokyo?"

Response: "It's currently 18°C in Tokyo with partly cloudy skies!"
保存文件并退出编辑器。（:wq 回车）
Adventure 1
18 / 32
动手做 2
测试你的天气技能！
看看你的「培训」成功没。运行下面这几条命令，重启 OpenClaw 并测试新技能：
openclaw gateway restart

openclaw agents

openclaw agent --agent main --message "tell me a joke in english"

openclaw agent --agent main --message "y=x^2+3x+6, x=3,y=?"

openclaw agent --agent main --message "weather in las vegas"



openclaw configure --section web

Brave API Key: BSAdZ3Xo8AjGyuUqIlUmrCd3GU_eA6t
成功了吗？ 庆祝一下！你刚刚教会 AI 一项新技能。 🎉
报错了？ 别担心，紧接着的排错章节就来救场。
Adventure 1
19 / 32
常见错误与修复方法
❌ 错误：文件夹位置不对
修复： 确认你当前在 ~/clawd/skills/ 目录里。可以用 pwd 查看你现在的位置。
❌ 错误：API URL 拼错了
修复： 原样复制粘贴 URL。错一个字符就全废了。
❌ 错误：忘了重启 OpenClaw
修复： 新建或编辑技能后，一定要运行 openclaw restart.
❌ 错误：触发词对不上
修复： 测试时，使用的触发词要和 SKILL.md 里写的完全一致。
Adventure 1
20 / 32
更多排错提示
检查语法
确认所有花括号 {} 和方括号 [] 都成对闭合。JSON 在这一点上很挑剔。
单独测一下 API
在加进 SKILL.md 之前，先在浏览器里访问一下这个 URL，确认它能正常工作。
认真读报错信息
错误信息通常会精确告诉你哪里有问题。留意行号和关键词。
和能跑通的例子做对比
看一眼能跑通的天气技能，逐行和你新写的技能对比，找差异。
Adventure 1
21 / 32
头脑风暴
OpenClaw 还能学会哪些技能？
现在你已经知道怎么教 OpenClaw 新技能，可能性无穷无尽。我们一起来头脑风暴。
📚 知识类 API
维基百科摘要
翻译服务
词典释义
历史小知识
🎮 娱乐类 API
NASA 天文照片
随机猫片
励志金句
电影资料
🔧 实用类 API
货币汇率
新闻头条
股票行情
时区换算
Adventure 1
22 / 32
两人一组活动
设计你的梦想 API 技能
1
第 1 步：选一个 API（3 分钟）
和搭档从头脑风暴清单里挑一个有意思的 API，或者自己上网找一个免费的。
2
第 2 步：规划技能（5 分钟）
把 SKILL.md 的结构勾出来：用哪些触发词？有哪些步骤？OpenClaw 该怎么回应？
3
第 3 步：跟全班分享（每组 2 分钟）
把你们的想法讲给大家听。这个技能解决了什么问题？为什么有用？
Adventure 1
23 / 32
去哪儿找免费 API
想再探索更多 API？下面这几个网站是寻找免费、免注册 API 的好去处：
🔗 public-apis.io
按分类整理的庞大免费 API 目录
🔗 rapidapi.com/hub
上千个 API 的市集，很多都有免费套餐
🔗 github.com/public-apis
GitHub 上一个精选的公共 API 列表
💡 小贴士：找标着「No Auth」的——它们不用注册、也不用 API key。
Adventure 1
24 / 32
关键收获：今天学到了什么
API 连接整张互联网
它让不同程序高效、安全地共享信息
JSON 是通用语言
一种结构化的数据格式，人和机器都看得懂
GET 请求负责取数据
向 API 索取信息的最简单方式
SKILL.md 教会 AI
用文字写下的说明，给 AI 添新本事
Adventure 1
25 / 32
成就解锁！
100%
天气预报员
掌握了如何获取并展示天气数据
100%
笑话大师
通过笑话 API，让 AI 学会了幽默
100%
API 召唤师
理解了如何连上外部服务
Adventure 1
26 / 32
现实中的应用
你今天学的这些技能，专业开发者每天都在用。下面看看 API 是如何驱动现代互联网的：
手机 App
你手机上的 app 同时在调用几十个 API ——地图、支付、社交、天气，全部通过 API 连接。
电商
你在网上购物时，商家用的是支付 API（比如 PayPal、Stripe）来安全完成交易。
社交媒体
跨平台分享、嵌入推文、用 Google 登录 ——全都靠 API。
Adventure 1
27 / 32
使用 API 的几条最佳实践
永远先读文档
每个 API 都有说明。下手写代码之前认真读一遍。
小步小测
别一口气把所有东西写完。先把 API 调用跑通，再叠加复杂度。
优雅地处理错误
API 会失败、也会返回意料之外的数据。永远要替「出问题」那一刻先想好后路。
尊重速率限制
很多 API 会限制你单位时间内能发多少请求。别去刷它。
API key 保密
如果 API 需要 key，永远不要公开分享，也不要 commit 到 GitHub。
Adventure 1
28 / 32
小测验时间！
检验你的掌握情况：5 道题
看看你记住了多少。先自己作答，之后我们一起对答案。
✏️ 答案写在纸上或文档里，等下一起核对。
Adventure 1
29 / 32
测验题目
1
API 是什么的缩写？
A）Advanced Programming Interface
B）Application Programming Interface
C）Automated Process Integration
D）Application Process Interface
2
JSON 是什么的缩写？
A）JavaScript Object Notation
B）Java Standard Object Notation
C）JavaScript Online Network
D）Just Simple Object Names
3
GET 请求用来做什么？
A）向服务器发送数据
B）删除数据
C）从服务器获取数据
D）更新已有数据
Adventure 1
30 / 32
测验题目（续）
1
用什么文件来教 OpenClaw 学新技能？
A）SKILLS.txt
B）SKILL.md
C）openclaw.config
D）api_instructions.json
2
在餐厅类比里，API 对应的是什么？
A）厨房
B）顾客
C）菜单
D）食物
做完了吗？我们一起对答案。
Adventure 1
31 / 32
反思时间
离堂作业：今天你学到了什么？
下课前，花 5 分钟回顾一下今天的冒险，认真回答下面几个问题：
🌟 一件让你意外的事
今天关于 API，哪一点出乎你意料、或让你格外感兴趣？
💪 一件让你自豪的事
今天的哪一项技能或成就让你觉得很爽？
❓ 一个你还想问的问题
你还想更深入理解、或者再去探索什么？
🚀 一个你会怎样用上它的设想
在未来的某个项目或想法里，你会怎么用上 API？
Adventure 1
32 / 32
下一段冒险预告：移动 AI！
即将到来：Adventure 4
觉得学 API 已经够酷了？下一节会更酷。
📱 移动开发
学会把 AI 装进手机，走到哪带到哪
🎤 语音控制
用语音命令和 OpenClaw 对话，双手解放
🔔 推送通知
从 AI 那里实时收到提醒和更新
今天表现超棒，未来的开发者们！你已经把 AI 技能升了一档，准备好迎接更大的挑战了。下次见！ 🚀
Adventure 1
Join more than 7M pro shoppers
