OpenClaw 天气查询Skill开发Demo

本文以xcweather天气查询Skill 为实操Demo，完整讲解OpenClaw Skill的开发、安装、配置与基础验证流程，严格遵循OpenClaw技能规范及Agent Skills开放标准（https://agentskills.io/），所有操作基于Windows环境实现，技能代码已开源至Gitee openclaw-demo。

一、OpenClaw Skill 核心认知

OpenClaw的技能体系基于Agent Skills开放标准 构建，Agent Skills是由Anthropic提出的开源格式，通过指令、脚本、资源组成的独立文件夹，为智能体赋予可按需加载的流程化知识与专属能力，让智能体能更精准、高效地完成具体任务。

在OpenClaw框架中，每个Skill是独立的功能模块，需包含代码实现、元数据配置、技能说明 三大核心部分（仅技能说明 是必须内容），遵循统一的目录与规范定义，确保框架能自动识别、调度和执行。本次开发的xcweather技能，核心通过天气API（tianqiapi.com）实现指定城市的天气查询，包含实时空气质量、未来3天预报等数据，是轻量的OpenClaw Skill开发参考Demo。

二、xcweather 技能开发全流程

2.1 开发前准备

1. 环境依赖 ：提前安装Python3.8+、uv，安装API请求依赖requests，执行命令：uv add requests；
2. API账号申请 ：注册天气API（tianqiapi.com）账号，获取WEATHER_API_APPID和WEATHER_API_APPSECRET，作为API调用的核心凭证；
3. 本地代理配置（可选） ：配置该代理的核心目的是验证xcweather技能是否被真实调用 ，而非直接访问公网API。具体操作：通过Nginx配置本地域名代理，将yktq.com.xc.lo映射至tianqiapi.com官方地址，同时修改本地hosts文件绑定该域名与本地IP，后续可通过代理日志/抓包确认技能是否发起了API调用请求；
4. 框架环境 ：确保Windows环境中已正确安装OpenClaw，可通过openclaw --version验证安装状态。

2.2 技能目录结构

遵循OpenClaw与Agent Skills的目录规范（https://agentskills.io/），xcweather为独立文件夹，所有文件按固定层级组织，放入OpenClaw的核心skills目录即可被框架识别，**Windows环境下固定目录** ：C:\Users\你的用户名\.openclaw\workspace\skills\

xcweather/
├── scripts/          # 核心代码目录，存放技能执行脚本
│   └── main.py       # 天气查询核心实现代码，处理API请求与数据格式化
├── _meta.json        # OpenClaw核心元数据配置文件，框架识别技能的关键
└── SKILL.md          # 技能说明文档，声明依赖、执行方式、使用规范

2.3 核心文件实现

（1）脚本代码：scripts/main.py

技能功能的核心载体，实现天气API调用、数据格式化、异常处理、日志记录，关键实现要点：

• 日志配置：兼容Windows系统，将日志写入Downloads/logs目录，记录技能调用参数与运行状态；
• 环境变量读取：从OpenClaw全局配置中获取API凭证，避免硬编码，符合Agent Skills的安全规范；
• API请求：构造tianqiapi.com的标准请求参数，设置5秒超时，捕获请求异常；
• 数据处理：格式化返回结果，展示城市、更新时间、空气质量及未来3天天气预报，包含温度、风向、降水量等核心信息；
• 异常兜底：捕获所有运行异常，返回友好错误提示，确保技能执行不崩溃，适配OpenClaw的调度逻辑。

（2）元数据配置：_meta.json

OpenClaw框架识别技能的核心配置文件，需严格定义技能标识、运行时、执行命令、入参等信息（遵循https://agentskills.io/规范），框架通过该文件实现技能的自动化调度，无多余配置，仅保留核心必要项：

{
  "name": "xcweather",
  "version": "0.1.0",
  "description": "天气查询技能",
  "runtime": "python",
  "command": ["uv", "run", "scripts/main.py"],
  "env": {
    "WEATHER_API_APPID": "天气 API（tianqiapi.com）的应用 ID",
    "WEATHER_API_APPSECRET": "天气 API（tianqiapi.com）的应用密钥"
  },
  "parameters": {
    "city": {
      "type": "string",
      "description": "城市名称",
      "required": true
    }
  }
}

关键配置项说明：

• name：技能唯一标识，遵循语义化版本规范；
• runtime：技能运行环境，本次为python；
• command：框架执行技能的固定命令，使用uv启动保证环境隔离；
• parameters：技能唯一必选入参city，定义类型与描述，与脚本传参逻辑一致。

（3）技能说明：SKILL.md

遵循Agent Skills开放标准（https://agentskills.io/）编写，清晰声明技能的元数据、依赖、执行方式，为框架调度和开发者使用提供明确说明，顶部通过`---`定义OpenClaw专属元数据，核心内容如下：

---
name: xcweather
version: 0.1.0
description: A skill to fetch weather information for a specified city using tianqiapi.com API.
metadata:
  {
    "openclaw":
      {
        "requires": 
          { 
            "bins": ["uv", "python"], 
            "env": ["WEATHER_API_APPID","WEATHER_API_APPSECRET"], 
            "config": ["browser.enabled"] 
          },
        "primaryEnv": "WEATHER_API_APPID",
        "verify_method": "可通过本地Nginx代理（yktq.com.xc.lo映射至tianqiapi.com）验证技能是否被真实调用"
      }
  }
---
## Overview
This skill enables the agent to retrieve current weather data for a given city by calling tianqiapi.com API. The script handles the API request and returns formatted weather information.

## Environment Variables
此技能需要配置以下环境变量才能正常运行：
- `WEATHER_API_APPID`: 天气 API（tianqiapi.com）的应用 ID
- `WEATHER_API_APPSECRET`: 天气 API（tianqiapi.com）的应用密钥

## Execution
To execute this skill and query weather for a city:
```bash
cd C:\Users\你的用户名\.openclaw\workspace\skills\xcweather
uv run scripts/main.py <city_name>

三、OpenClaw Skill 安装与管理（Windows环境）

3.1 本地技能安装

本地开发的xcweather Skill通过目录复制完成安装，为Windows环境下最便捷的方式，步骤如下：

1. 克隆开源技能仓库至本地：

git clone https://gitee.com/impl/openclaw-demo.git

2. 进入仓库的skills目录，将xcweather文件夹完整复制至OpenClaw固定skills目录 ：C:\Users\你的用户名\.openclaw\workspace\skills\；
3. 验证目录结构：确保xcweather文件夹下包含scripts、_meta.json、SKILL.md，且文件无缺失、路径无错误。

3.2 环境变量配置：OpenClaw 框架全局配置

xcweather依赖WEATHER_API_APPID和WEATHER_API_APPSECRET作为API调用凭证，仅通过OpenClaw框架全局配置 管理，Windows环境下全局配置文件固定路径为：C:\Users\你的用户名\.openclaw\openclaw.json。

3.2.1 配置技能专属环境变量

打开openclaw.json配置文件，在根节点下新增/修改skills节点，为xcweather配置专属环境变量，完整配置示例（其他原有配置项保留，仅新增skills节点）：

{
  "skills": {
    "entries": {
      "xcweather": {
        "enabled": true,  // 启用xcweather技能
        "env": {          // 配置天气API的核心凭证
          "WEATHER_API_APPID": "你从tianqiapi.com获取的APPID",
          "WEATHER_API_APPSECRET": "你从tianqiapi.com获取的APPSECRET"
        }
      }
    }
  }
}

配置说明：enabled: true表示启用该技能，框架会自动加载；env节点下为技能运行所需的专属环境变量，与SKILL.md中声明的环境变量一致。

3.3 技能本地调试

在Windows环境下，直接在技能目录执行命令，验证技能是否能正常读取框架全局配置、调用API并返回结果，快速排查代码和配置问题，步骤如下：

1. 打开CMD/PowerShell，进入xcweather技能目录：

cd C:\Users\你的用户名\.openclaw\workspace\skills\xcweather

2. 执行技能命令，传入城市名称（如北京）测试：

uv run scripts/main.py 北京

3. 正常运行结果示例（格式化返回天气信息）：

   城市: 北京
   更新时间: 2025-10-20 14:30:00
   空气质量: 良 (AQI: 65)

   天气预报:
   2025-10-20: 晴 温度: 12°C ~ 22°C
   风向: 北 3-4级
   2025-10-21: 多云 温度: 10°C ~ 20°C
   风向: 东北 2-3级
   2025-10-22: 阴转小雨 温度: 8°C ~ 18°C
   风向: 东 2-3级
   降水量: 5.2mm

3.4 技能管理

OpenClaw框架中仅需通过固定命令查看技能状态，确认xcweather是否被框架正确识别并处于可用状态，Windows环境下执行命令：

openclaw skills list

执行后查看输出结果，若xcweather技能后标注ready状态，说明技能已被框架正确识别、配置生效，可被智能体正常调度使用。

四、问题记录

在xcweather技能开发与调试过程中，遇到两个问题，耗费较多时间排查，现将问题现象及临时解决/规避方式记录如下（原因分析及解决思路仅为实操总结，不保证完全准确）：

4.1 问题1：Qwen-Plus 不调用 Skill，DeepSeek-Chat 正常

现象

相同的技能配置、用户查询指令（如"北京今天天气怎么样"）下：

• DeepSeek-Chat能正常触发并调用xcweather技能，Nginx代理可捕获到API调用请求，返回Skill格式化的天气数据；
• Qwen-Plus始终不调用Skill，无Nginx代理请求记录，仅返回大模型原生的天气相关回答。

临时解决思路

4.2 问题2：SKILL.md 中 description 含引号导致框架无法识别

现象

初期编写SKILL.md时，在description字段冒号后的文本中使用了引号（如description: A skill to fetch "weather" information...），导致OpenClaw框架执行openclaw skills list时，无法识别该技能。

临时解决思路

删除SKILL.md中description字段冒号后文本内的所有引号（单引号、双引号均需删除），仅保留纯文本描述，示例：

• 错误写法：description: "A skill to fetch weather information for a specified city using tianqiapi.com API."
• 正确写法：description: A skill to fetch weather information for a specified city using tianqiapi.com API.

修改后重启OpenClaw，框架可正常识别skill。

五、OpenClaw 官方文档核心知识点总结

本章节基于OpenClaw官方文档Skills模块和ClawHub模块进行核心知识点提炼，为Skill开发、管理、部署提供标准依据。

5.1 Skills 模块核心总结

OpenClaw的Skills完全兼容AgentSkills标准，是教智能体使用工具的核心载体，核心知识点如下：

1. 技能加载位置与优先级
   技能从三个位置加载，优先级从高到低 ：工作区Skills（<workspace>/skills）→ 托管/本地Skills（~/.openclaw/skills）→ 内置Skills（安装包自带）；可通过openclaw.json的skills.load.extraDirs配置额外技能文件夹（最低优先级）。
2. 单智能体与共享Skills
   • 单智能体技能：存于<workspace>/skills，仅当前智能体可用；
   • 共享技能：存于~/.openclaw/skills，同一机器所有智能体可见；
     名称冲突时遵循上述优先级规则。
3. 环境变量注入规则
   智能体运行开始时，框架将skills.entries中的环境变量注入process.env，运行结束后恢复原始环境，仅作用于本次智能体运行，不影响全局shell环境。

5.2 ClawHub 模块核心总结

ClawHub是OpenClaw的公共Skills注册中心，提供Skills的查找、安装、更新、发布、备份等能力，所有Skills均为开源公开，核心知识点如下：

1. CLI 安装方式
   需先安装ClawHub的命令行工具，任选其一即可：

   npm i -g clawhub
   # 或
   pnpm add -g clawhub

2. 核心功能与常用命令
   ClawHub支持语义化版本管理、向量搜索、星标评论等功能，常用CLI命令：

   • 搜索：clawhub search "查询关键词"
   • 安装：clawhub install <skill-slug>（安装到当前工作区/OpenClaw配置工作区）
   • 更新：clawhub update <skill-slug> / clawhub update --all
   • 发布：clawhub publish <技能路径>（将自定义技能发布到注册中心）
   • 同步：clawhub sync --all（扫描本地技能并发布更新，实现备份）

3. Skills 安装路径规则
   默认安装到当前工作目录的./skills，若配置了OpenClaw工作区则回退到工作区；安装的技能属于工作区Skills，优先级高于托管/本地和内置技能。

4. 版本与锁文件管理

   • 技能遵循语义化版本规则，标签（如latest）可指向指定版本，支持版本回滚；
   • 已安装技能的信息记录在工作目录的.clawhub/lock.json中，更新时通过内容哈希对比本地与注册中心版本。

5. 认证与环境变量

   • 认证：通过clawhub login（浏览器/令牌方式）完成登录，令牌存储在CLI配置文件中；
   • 自定义环境变量：可通过CLAWHUB_WORKDIR、CLAWHUB_REGISTRY等变量覆盖默认配置，CLAWHUB_DISABLE_TELEMETRY=1可禁用遥测功能。