共计 2296 个字符，预计需要花费 6 分钟才能阅读完成。

天气 skill 的应用价值

天气查询是最常见的生活服务类技能之一。通过语音或文本交互快速获取天气信息，能显著提升智能设备的使用体验。商业场景中，可与出行 APP、智能家居系统联动，例如：

• 根据天气自动调节空调温度
• 结合降雨概率推荐出行路线
• 为外卖平台优化配送调度

新手开发三大痛点

1. API 调用混乱

openclaw 的 API 文档包含多个版本和认证方式，新手常因混淆 v1/v2 接口导致 401 错误。关键点：

• 必须使用 Authorization: Bearer {API_KEY} 头
• 当前稳定版本为 v2.1（2023 年更新）

2. 数据解析错误

原始响应包含数十个字段，直接返回会给用户造成信息过载。典型问题：

• 未处理温度单位转换（开尔文转摄氏度）
• 遗漏降水概率的百分比格式化

3. 异常处理缺失

90% 的线上故障源于未处理：

• 第三方 API 超时（默认 3 秒无响应）
• 无效地理位置编码
• 免费套餐的 QPS 限制

技术实现详解

API 调用示例（Python）

import requests
from datetime import datetime

# 配置常量
API_ENDPOINT = "https://api.openclaw.io/v2.1/weather"
API_KEY = "your_api_key_here"  # 替换为实际 key

# 封装请求函数
def fetch_weather(location: str):
    headers = {"Authorization": f"Bearer {API_KEY}",
        "Accept": "application/json"
    }
    params = {
        "location": location,
        "units": "metric"  # 使用公制单位
    }

    try:
        response = requests.get(
            API_ENDPOINT, 
            headers=headers, 
            params=params,
            timeout=3  # 设置 3 秒超时
        )
        response.raise_for_status()  # 自动处理 4xx/5xx 错误
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"API 请求失败: {str(e)}")
        return None

数据解析最佳实践

建议提取核心字段并结构化为语音友好格式：

def format_weather(raw_data: dict) -> str:
    if not raw_data:
        return "暂时无法获取天气信息"

    current = raw_data.get("current", {})
    return (f"当前温度{current.get('temp',' 未知 ')}℃,"
        f"体感温度{current.get('feels_like',' 未知 ')}℃。"
        f"{current.get('weather', [{}])[0].get('description',' 无描述 ')},"
        f"湿度{current.get('humidity',' 未知 ')}%。"
    )

错误处理四层防护

1. 网络层：requests 自带超时控制
2. 业务层：检查 HTTP 状态码
3. 数据层 ：使用 dict.get() 避免 KeyError
4. 降级处理：返回默认提示信息

性能优化策略

缓存实现方案

使用内存缓存避免重复请求：

from functools import lru_cache
import time

# 缓存 30 分钟（1800 秒）@lru_cache(maxsize=100)
def get_cached_weather(location: str):
    return fetch_weather(location)

# 定时清除缓存
def clear_cache():
    while True:
        time.sleep(1800)
        get_cached_weather.cache_clear()

并发控制要点

• 使用 Semaphore 限制并发数
• 推荐 QPS≤5（免费套餐限制）
• 异步请求示例（Node.js 版）：

const {Semaphore} = require('async-mutex');
const semaphore = new Semaphore(5);

async function safeFetch(location) {const [value, release] = await semaphore.acquire();
  try {return await fetchWeather(location);
  } finally {release();
  }
}

避坑指南 Top5

1. 时区问题：openclaw 返回 UTC 时间，需转换为本地时区

   from pytz import timezone
   datetime.utcfromtimestamp(ts).astimezone(timezone('Asia/Shanghai'))

2. 单位混淆：美国地区默认使用华氏度，强制指定units=metric

3. 缓存击穿：对同一地点的高频请求添加随机过期时间（30±5 分钟）

4. 异常日志：记录原始错误信息但不要返回给用户

5. 测试陷阱：沙箱环境与实际 API 存在差异，务必进行线上验证

扩展思考：IoT 设备集成

1. 语音交互优化：
2. 为智能音箱设计简短播报模板

3. 添加空气质量等扩展信息（需用户授权）

4. 上下文记忆：

5. 存储用户常用地点

6. 实现 ” 和昨天相比 ” 这类对比查询

7. 硬件联动：

8. 雨天自动关闭窗户（需 IoT 平台支持）
9. 高温预警触发风扇

建议采用分层架构：

[设备端] ←HTTP→ [Skill 服务层] ←API→ [openclaw]
                  ↑
               [Redis 缓存]

通过本次实践，我们不仅实现了基础天气查询，还建立了可扩展的架构框架。下一步可以探索结合用户画像的个性化天气提醒，这将大幅提升技能的商业价值。