# openclaw-qweather

> Query weather via QWeather Enterprise API with automatic JWT auth + geo resolution, and Open-Meteo fallback for current conditions.

- Author: Murphy
- Repository: murphys7017/openclaw-qweather
- Version: 20260208021228
- Stars: 2
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/murphys7017/openclaw-qweather
- Web: https://mule.run/skillshub/@@murphys7017/openclaw-qweather~openclaw-qweather:20260208021228

---

---
name: openclaw-qweather
description: Query weather via QWeather Enterprise API with automatic JWT auth + geo resolution, and Open-Meteo fallback for current conditions.
user-invocable: true
metadata: { "openclaw": { "emoji": "☀️" } }
---

# openclaw-qweather 天气查询 Skill

## 你能用它做什么

本 Skill 面向「对话/代理」提供结构化天气查询能力：

- 实时天气（当前温度、体感、湿度、风等）
- 天气预报（日预报 3/7/15 天）
- 逐小时预报（24/72/168 小时）
- 分钟级降水（未来 2 小时，每 5 分钟）
- 气象预警
- 生活指数（穿衣、洗车、运动、紫外线等）

### 重要说明：调用方不需要关心 JWT 和位置解析

对外调用只需要传 `location`（城市名 / 经纬度 / locationId）。
Skill 内部会自动完成：

1) 获取并缓存企业 API JWT（Ed25519 / JWT）  
2) 将输入位置解析为 QWeather 可用的 `locationId`（必要时提取经纬度）  
3) 请求对应天气接口  
4) 对 `weather_now`：当企业 API 异常时自动回退到 Open-Meteo（保证实时天气可用）

> 这符合 OpenClaw Skill 的设计：对外暴露的是“能力”，不是“实现步骤”。  
> 并且 Skill 文档建议在正文中使用 `{baseDir}` 引用技能目录路径。 :contentReference[oaicite:1]{index=1}

---

## 输入约定（Input）

所有查询 action 通用输入：

- `location`（可选）
  - 城市名：`"北京"`
  - 经纬度：`"116.4,39.9"`（建议使用 `lon,lat`）
  - 位置 ID：`"101010100"`
  - 未传入时使用默认位置（由配置决定）

---

## 可用 Actions（对外能力）

> 说明：以下 actions 代表“你应该从用户意图映射到哪种查询”，而不是要求你显式调用 JWT/Geo。

### 1 `weather_now` 实时天气（含回退）

**适用**：用户问“现在XX天气怎样/多少度/风大吗/要不要带伞（当前）”。  
**特性**：企业 API 失败时自动回退 Open-Meteo。

**输入**
- `{ location? }`

**输出（成功）**
- `success: true`
- `source: "QWeather Enterprise API" | "Open-Meteo (free tier)"`
- `now: { temp, feelsLike, text, humidity?, windDir?, windScale?, obsTime? }`
- `fxLink?`

---

### 2 `weather_forecast` 日预报（3/7/15 天）

**适用**：用户问“未来几天/本周天气趋势”。  
**输入**
- `{ location?, days? }`，days 推荐值：`3 | 7 | 15`

**输出（成功）**
- `success: true`
- `forecast: [{ date, tempMax, tempMin, textDay, textNight, precip? }]`

---

### 3 `weather_hourly` 逐小时预报（24/72/168 小时）

**适用**：用户需要“今天每小时温度/降水概率变化”。  
**输入**
- `{ location?, hours? }`，hours：`"24h" | "72h" | "168h"`

**输出（成功）**
- `success: true`
- `hourly: [{ time, temp, text, humidity?, precip?, pop?, windDir?, windScale?, windSpeed?, ... }]`

---

### 4 `weather_minutely_precipitation` 分钟级降水（2 小时）

**适用**：短时决策（是否马上会下雨、是否要带伞、临近出门提醒）。  
**输入**
- `{ location? }`（内部会自动保证获得经纬度）

**输出（成功）**
- `success: true`
- `precipitation: { summary, updateTime, fxLink?, minutely: [{ time, precip, type }] }`

---

### 5 `weather_warning` 气象预警

**适用**：安全风险（暴雨、大风、高温、寒潮等）。  
**输入**
- `{ location? }`

**输出（成功）**
- `success: true`
- `warning: { updateTime, fxLink?, alerts: [...] }`

---

### 6 `weather_indices` 生活指数（1d / 3d）

**适用**：穿衣/洗车/运动/紫外线/感冒等建议。  
**输入**
- `{ location?, days?, type? }`
- `days: "1d" | "3d"`
- `type: "all"` 或具体指数类型

**输出（成功）**
- `success: true`
- `indices: [{ date, type, name, level, category, text }]`

---

## 使用示例（Usage Examples）

> 注意：示例只演示“天气 action 的调用方式”。  
> JWT 和 Geo 解析会在这些 action 内部自动完成。

### 示例 1：实时天气（含回退）

```js
const { weather_now } = require("{baseDir}/lib/qweather_weather_tool");

(async () => {
  const r = await weather_now({ location: "北京" });
  console.log(r);
})();
```
### 示例 2：日预报（7 天）
```js
const { weather_forecast } = require("{baseDir}/lib/qweather_weather_tool");

(async () => {
  const r = await weather_forecast({ location: "上海", days: 7 });
  console.log(r);
})();
```
###  示例 3：逐小时预报（72h）
```js
const { weather_hourly } = require("{baseDir}/lib/qweather_hourly_tool");

(async () => {
  const r = await weather_hourly({ location: "广州", hours: "72h" });
  console.log(r);
})();
```
###  示例 4：分钟级降水（2 小时）
```js
const { weather_minutely_precipitation } = require("{baseDir}/lib/qweather_precipitation_tool");

(async () => {
  const r = await weather_minutely_precipitation({ location: "杭州" });
  console.log(r);
})();
```
###  示例 5：气象预警
```js
const { weather_warning } = require("{baseDir}/lib/qweather_warning_tool");

(async () => {
  const r = await weather_warning({ location: "成都" });
  console.log(r);
})();
```
###  示例 6：生活指数（全部）
```js
const { weather_indices } = require("{baseDir}/lib/qweather_indices_tool");

(async () => {
  const r = await weather_indices({ location: "南京", days: "1d", type: "all" });
  console.log(r);
})();
```
## 失败与可靠性（Reliability Notes）

- weather_now：具备 Open-Meteo 回退，增强可用性（企业 API 异常时仍返回基础实时天气）。

- 其他 action：以企业 API 为主；失败时返回 success:false 并附带错误信息（不回退）。

- 分钟级降水：底层依赖经纬度；若无法从位置解析获得坐标，将返回失败。



## 配置与安全（Configuration & Security）

### 配置来源（固定文件，不由 OpenClaw 注入）

本 Skill 的企业 API 配置 **不通过 OpenClaw 的 env/apiKey 机制注入**，也不期望 OpenClaw 读取或管理该配置。

- 配置文件：`{baseDir}/lib/qweather_config.js`
- 私钥文件路径：由 `qweather_config.js` 内的 `PRIVATE_KEY_PATH` 指定（技能内部读取本地文件）

也就是说：部署者需要在技能目录中自行准备好配置与私钥文件，确保运行时可读。

### 安全建议

- 不要把私钥内容直接写入仓库（建议仅保存路径并通过部署流程落盘）
- 确保私钥文件权限最小化（仅运行该 Skill 的进程用户可读）
- 避免在日志中输出完整 JWT 或私钥内容（调试时仅在本地环境开启）