从零构建OpenClaw天气查询技能

前言

构建自己的 OpenClaw 技能既有趣又有成就感。本教程将带你从零开始创建一个天气查询技能。完成这个实战项目后，你将掌握技能开发的核心概念和完整工作流程。

技能基础知识

OpenClaw 技能本质上是一个 SKILL.md 文件，使用自然语言定义 AI 助手在特定场景下的行为方式。技能文件存放在 ~/.openclaw/skills/ 目录中。

一个技能由以下关键组件构成：

组件	说明	是否必需
名称和描述	技能的标识信息	是
触发条件	何时应该激活技能	是
行为定义	激活后应该做什么	是
输出格式	回复的格式和风格	建议
MCP 工具	需要调用的外部工具	按需

SKILL.md 文件结构

标准的 SKILL.md 文件结构如下：

---
name: skill-name
version: 1.0.0
description: Brief description of the skill
triggers:
  - keyword1
  - keyword2
mcp_tools:
  - tool_name
---

# Skill Title

## Description
Detailed description of what this skill does.

## Behavior
Instructions for how the AI should behave when this skill is activated.

## Output Format
How the response should be formatted.

第一步：规划天气技能

在编写任何代码之前，先规划技能的功能：

功能：查询指定城市的天气信息（当前天气 + 未来预报）
触发词：天气、weather、气温、温度、下雨
数据来源：通过 MCP 工具调用 OpenWeatherMap API
输出：格式化的天气信息卡片

第二步：配置 MCP 天气工具

在使用天气 API 之前，需要在 OpenClaw 设置中配置 MCP 工具。编辑 ~/.config/openclaw/openclaw.json5：

{
  mcp: {
    servers: {
      "weather-api": {
        // 使用 HTTP 类型的 MCP 服务
        command: "npx",
        args: ["-y", "@openclaw-mcp/http-fetch"],
        env: {
          // OpenWeatherMap API key
          OPENWEATHER_API_KEY: "your-api-key-here"
        }
      }
    }
  }
}

如果你还没有 OpenWeatherMap API key，可以在 https://openweathermap.org/api 免费注册获取。

第三步：编写 SKILL.md

在 ~/.openclaw/skills/ 目录下创建 weather.SKILL.md 文件：

---
name: weather
version: 1.0.0
description: 查询全球城市天气信息，支持当前天气和未来预报
triggers:
  - 天气
  - weather
  - 气温
  - 温度
  - 下雨
  - 下雪
  - 预报
  - forecast
mcp_tools:
  - http_fetch
---

# 天气查询技能

## Description

这是一个天气查询技能，当用户询问任何与天气相关的问题时激活。
支持查询全球任意城市的当前天气和未来天气预报。

## Behavior

当用户询问天气信息时，按以下步骤执行：

1. **提取城市名称**：从用户消息中识别出目标城市。如果用户没有指定城市，
   询问用户想查询哪个城市的天气。

2. **调用天气 API**：使用 http_fetch 工具调用 OpenWeatherMap API：
   - 当前天气：`https://api.openweathermap.org/data/2.5/weather?q={city}&appid={OPENWEATHER_API_KEY}&units=metric&lang=zh_cn`
   - 未来预报：`https://api.openweathermap.org/data/2.5/forecast?q={city}&appid={OPENWEATHER_API_KEY}&units=metric&lang=zh_cn&cnt=24`

3. **解析数据**：从 API 返回的 JSON 中提取关键信息。

4. **格式化输出**：按照下方输出格式模板返回结果。

## Data Parsing

从 API 响应中提取以下字段：

- `main.temp` - 当前温度（摄氏度）
- `main.feels_like` - 体感温度
- `main.humidity` - 湿度百分比
- `weather[0].description` - 天气描述
- `wind.speed` - 风速（m/s）
- `main.temp_min` - 最低温度
- `main.temp_max` - 最高温度
- `sys.sunrise` - 日出时间（Unix时间戳，转换为当地时间）
- `sys.sunset` - 日落时间

## Output Format

使用以下格式回复用户：

### 当前天气查询

🌤️ {城市名} 天气

📍 当前天气：{天气描述} 🌡️ 温度：{当前温度}°C（体感 {体感温度}°C） 📊 温度范围：{最低温}°C ~ {最高温}°C 💧 湿度：{湿度}% 💨 风速：{风速} m/s 🌅 日出：{日出时间} 🌇 日落：{日落时间}


### 未来预报查询

📅 {城市名} 未来天气预报

时间	天气	温度	湿度
{时间1}	{天气1}	{温度1}°C	{湿度1}%
{时间2}	{天气2}	{温度2}°C	{湿度2}%
...


## Additional Instructions

- 如果城市名称不明确（如"长安"可能指西安），列出可能的选项让用户选择
- 如果 API 返回错误或城市不存在，友好地告知用户并建议检查城市名称
- 温度使用摄氏度，风速使用 m/s
- 根据天气情况给出简短的生活建议（如带伞、防晒、添衣等）
- 时间显示使用 24 小时制

第四步：测试技能

方法一：本地测试

重启 OpenClaw 并测试：

# 重启以加载新技能
openclaw restart

# 确认技能已加载
openclaw skill list

然后在任意已连接的聊天渠道中发送测试消息：

北京今天天气怎么样？

方法二：使用调试模式

OpenClaw 提供了调试模式来辅助技能开发：

# 开启详细日志
openclaw logs --level debug

调试日志会展示技能的触发和执行过程：

[DEBUG] Message received: "北京今天天气怎么样？"
[DEBUG] Skill matching: checking triggers...
[DEBUG] Skill 'weather' matched by trigger: "天气"
[DEBUG] Activating skill: weather
[DEBUG] MCP tool call: http_fetch -> openweathermap API
[DEBUG] API response: 200 OK
[DEBUG] Skill 'weather' execution complete

方法三：直接调用 Gateway API 测试

绕过聊天渠道，直接调用 Gateway API：

curl -X POST http://localhost:18789/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "上海明天会下雨吗？",
    "context": []
  }'

第五步：完善输出

添加生活建议逻辑

在 SKILL.md 的 Behavior 部分添加基于天气的建议规则：

## Weather Advice Rules

根据天气数据给出对应建议：

- 温度 > 35°C：提醒防暑降温，多饮水
- 温度 < 0°C：提醒注意保暖，路面可能结冰
- 湿度 > 80%：可能会感觉闷热
- 天气描述包含"雨"：建议携带雨具
- 天气描述包含"雪"：注意出行安全
- 风速 > 10 m/s：注意防风
- UV 指数 > 6：建议涂防晒霜

支持模糊查询

在触发条件中添加更多自然语言模式：

triggers:
  - 天气
  - 要不要带伞
  - 穿什么衣服
  - 会不会下雨
  - 冷不冷
  - 热不热

第六步：添加多语言支持

让技能能够根据用户的语言自动切换输出语言。

在 SKILL.md 中添加以下内容：

## Multilingual Support

- 检测用户消息的语言
- 如果用户使用中文提问，用中文回复
- 如果用户使用英文提问，用英文回复
- API 调用时使用对应的 `lang` 参数：
  - 中文：`lang=zh_cn`
  - 英文：`lang=en`
  - 日文：`lang=ja`

最终文件检查清单

开发完成后，你的项目结构应该如下所示：

~/.openclaw/skills/
└── weather.SKILL.md       # 技能定义文件

~/.config/openclaw/
└── openclaw.json5          # 包含 MCP 天气工具配置

发布到 ClawHub

如果你对技能满意，可以将其发布到 ClawHub 市场：

# 创建发布目录
mkdir ~/weather-skill && cd ~/weather-skill

# 复制技能文件
cp ~/.openclaw/skills/weather.SKILL.md ./SKILL.md

# 创建元数据
cat > clawhub.json << 'EOF'
{
  "name": "weather-forecast-cn",
  "version": "1.0.0",
  "description": "中英文天气查询技能，支持全球城市",
  "author": "your-username",
  "license": "MIT",
  "keywords": ["weather", "forecast", "天气"],
  "category": "信息查询"
}
EOF

# 验证并发布
npx clawhub@latest validate
npx clawhub@latest publish

常见问题

API 调用失败

检查 API key 是否正确配置：

# 测试 API key
curl "https://api.openweathermap.org/data/2.5/weather?q=Beijing&appid=YOUR_KEY"

技能没有被触发

确认触发词列表中包含用户消息中出现的关键词
检查是否有其他技能的触发词冲突
查看调试日志中的匹配详情

输出格式不理想

SKILL.md 中的输出格式是对 AI 的指令而非刚性模板——AI 会理解意图但可能不会完全照搬。尝试在格式描述中更加具体，或者添加示例输出。

总结

通过本教程，你已经完成了一个功能完整的天气查询技能。核心收获包括结构化的 SKILL.md 编写方法、MCP 工具的配置与调用、触发条件设计以及输出格式优化。这些技巧可以迁移到任何其他类型的技能开发中。