当前位置：首页 > news >正文

OpenClaw开源贡献：为Qwen3.5-9B编写自定义技能开发指南

news 2026/8/1 9:58:53

OpenClaw开源贡献：为Qwen3.5-9B编写自定义技能开发指南

1. 为什么我们需要自定义技能

去年冬天，我在整理个人项目时发现一个痛点：每天需要手动查询多个城市的天气情况来规划出差行程。作为一个技术爱好者，我本能地思考能否用自动化解决这个问题。当时OpenClaw刚刚发布，我决定尝试为其开发一个天气查询技能。

这个决定让我意外地走进了开源贡献的世界。通过为OpenClaw开发技能，我不仅解决了自己的需求，还学会了如何将个人工具转化为社区共享资源。本文将分享我从零开始创建天气查询技能的全过程，包括踩过的坑和最终验证通过的方案。

2. 开发前的准备工作

2.1 环境配置

首先需要确保开发环境就绪。我使用的是macOS系统，通过以下命令安装了OpenClaw开发套件：

npm install -g @openclaw/cli @openclaw/devkit

验证安装是否成功：

clawdev --version # 应输出类似：@openclaw/devkit 1.2.3

2.2 技能项目初始化

创建一个新的技能项目非常简单：

clawdev init weather-query cd weather-query

这会生成一个标准的技能项目结构：

weather-query/ ├── package.json ├── src/ │ ├── index.ts # 主入口文件 │ └── types.ts # 类型定义 ├── tool.json # 工具描述文件 └── README.md

3. 定义天气查询工具

3.1 编写tool.json

这是技能的核心描述文件，告诉OpenClaw这个工具能做什么。我的weather-query/tool.json内容如下：

{ "name": "weather_query", "description": "查询指定城市的当前天气情况", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "需要查询的城市名称，如'北京'或'New York'" }, "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "description": "温度单位，默认为摄氏度(celsius)", "default": "celsius" } }, "required": ["city"] } }

这个定义明确表示：工具需要城市名称作为必填参数，温度单位是可选的（默认为摄氏度）。

3.2 实现处理函数

在src/index.ts中，我们需要实现实际的天气查询逻辑。我选择了和风天气API作为数据源（免费版足够个人使用）：

import { Tool } from '@openclaw/core'; interface WeatherParams { city: string; unit?: 'celsius' | 'fahrenheit'; } export const weatherQuery: Tool<WeatherParams> = async ({ city, unit = 'celsius' }) => { // 这里应该替换为你自己的API Key const API_KEY = process.env.HEFENG_API_KEY; if (!API_KEY) { throw new Error('请先设置HEFENG_API_KEY环境变量'); } // 获取城市地理位置编码 const locationRes = await fetch( `https://geoapi.qweather.com/v2/city/lookup?location=${encodeURIComponent(city)}&key=${API_KEY}` ); const locationData = await locationRes.json(); if (locationData.code !== '200' || !locationData.location?.length) { return { error: `找不到城市: ${city}` }; } const locationId = locationData.location[0].id; // 查询实时天气 const weatherRes = await fetch( `https://devapi.qweather.com/v7/weather/now?location=${locationId}&key=${API_KEY}` ); const weatherData = await weatherRes.json(); if (weatherData.code !== '200') { return { error: '获取天气数据失败' }; } // 处理温度单位 let temp = weatherData.now.temp; if (unit === 'fahrenheit') { temp = (temp * 9/5) + 32; } return { city: locationData.location[0].name, temperature: temp, unit, condition: weatherData.now.text, humidity: weatherData.now.humidity, wind: weatherData.now.windDir + ' ' + weatherData.now.windScale + '级' }; };

4. 本地测试与调试

4.1 注册技能到本地OpenClaw

在项目目录下运行：

clawdev link

这会在本地OpenClaw安装目录创建符号链接，使修改能即时生效。

4.2 测试技能

可以通过OpenClaw CLI直接测试：

openclaw tools execute weather_query --city 北京

也可以在OpenClaw Web控制台输入自然语言指令测试，如： "查询北京的当前天气"

4.3 调试技巧

开发过程中我遇到了几个典型问题：

API密钥管理：最初我将API密钥硬编码在代码中，后来改为环境变量更安全
城市匹配：发现部分城市名有歧义（如"Washington"可能匹配多个地点），增加了错误处理
单位转换：最初忘记处理华氏度转换，导致返回数据不准确

调试时我大量使用了OpenClaw的日志功能：

openclaw gateway --log-level debug

5. 提交贡献到ClawHub

5.1 完善项目文档

在提交前，我确保README.md包含以下关键信息：

技能功能描述
必要的环境变量
API申请指引（和风天气免费API）
使用示例

5.2 创建GitHub仓库

将代码推送到GitHub个人账号下：

git init git add . git commit -m "初始提交: 天气查询技能" git remote add origin https://github.com/<你的用户名>/weather-query.git git push -u origin main

5.3 提交到ClawHub

ClawHub是OpenClaw的技能市场，提交PR的流程如下：

Fork ClawHub仓库（https://github.com/openclaw/clawhub）
在skills目录下创建新文件夹weather-query
添加一个metadata.json文件描述你的技能：

{ "name": "weather-query", "displayName": "天气查询", "description": "查询全球城市实时天气信息", "keywords": ["weather", "查询", "工具"], "repository": "https://github.com/<你的用户名>/weather-query", "author": "你的名字 <你的邮箱>" }

提交Pull Request并等待审核

6. 与Qwen3.5-9B的适配优化

Qwen3.5-9B作为支持128K上下文的强大模型，能为技能提供更好的自然语言理解能力。我在开发过程中发现几个优化点：

工具描述优化：更详细的参数描述能帮助模型更好地理解何时调用该工具
错误处理增强：清晰的错误信息能让模型更好地向用户解释问题
结果格式化：结构化的返回数据便于模型生成用户友好的回复

例如，我调整了返回数据的结构：

return { summary: `${city}当前天气: ${weatherData.now.text}`, details: { temperature: `${temp}${unit === 'celsius' ? '°C' : '°F'}`, humidity: `${weatherData.now.humidity}%`, wind: `${weatherData.now.windDir} ${weatherData.now.windScale}级`, feelsLike: `${weatherData.now.feelsLike}°C` } };

这种结构既保留了原始数据供模型分析，又提供了可直接使用的摘要信息。