技能开发进阶：为Qwen3-32B添加自定义API工具调用

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

去年我在尝试用OpenClaw自动化处理公司内部数据报表时，发现现有的技能库无法满足特定需求。每次都要手动调用第三方API，既低效又容易出错。这让我意识到：掌握自定义技能开发能力，才能真正释放OpenClaw的潜力。

自定义技能的本质是将任意API封装成自然语言可调用的工具。比如把"查询最近订单"这句话，转换成对电商平台API的实际调用。通过本文，你将学会如何为Qwen3-32B模型开发一个完整的API调用技能，包含OAuth2.0鉴权等企业级功能。

2. 开发环境准备

2.1 基础工具链

我的开发环境是macOS + VS Code，但以下工具跨平台通用：

# 确认Node.js版本（需要v18+）
node -v
# 安装OpenClaw开发套件
npm install -g @openclaw/cli @openclaw/devkit

建议在项目目录初始化技能模板：

mkdir weather-skill && cd weather-skill
claw init skill --template=api-consumer

这会生成标准目录结构：

├── package.json
├── src
│   ├── index.ts       # 技能主逻辑
│   ├── auth.ts        # 鉴权模块
│   └── types.ts       # 类型定义
├── claw.skill.json    # 技能元数据
└── README.md

2.2 对接Qwen3-32B模型

在claw.skill.json中声明模型兼容性：

{
  "runtime": {
    "models": ["qwen3-32b"],
    "minContextWindow": 32768
  }
}

关键参数说明：

• minContextWindow：确保模型有足够上下文理解复杂API文档
• models数组可同时支持多个模型版本

3. 实现API调用核心逻辑

以天气查询API为例，我们来看具体实现。我选择心知天气API作为示例，因为它同时支持密钥和OAuth2.0两种鉴权方式。

3.1 基础请求封装

在src/index.ts中创建核心功能类：

import axios from 'axios';
import { AuthManager } from './auth';

export class WeatherService {
  private auth: AuthManager;

  constructor() {
    this.auth = new AuthManager();
  }

  async getCurrentWeather(location: string): Promise<WeatherData> {
    const token = await this.auth.getToken();
    const response = await axios.get(
      `https://api.seniverse.com/v3/weather/now.json`,
      {
        params: {
          key: token,
          location,
          language: 'zh-Hans'
        }
      }
    );
    return this.parseWeather(response.data);
  }

  private parseWeather(raw: any): WeatherData {
    // 转换API响应为标准格式
    return {
      temperature: raw.now.temperature,
      condition: raw.now.text,
      lastUpdate: new Date(raw.last_update)
    };
  }
}

开发中我踩过一个坑：没有处理API限流。后来增加了自动重试逻辑：

async getWithRetry(url: string, maxRetry = 3) {
  let lastError;
  for (let i = 0; i < maxRetry; i++) {
    try {
      return await axios.get(url);
    } catch (err) {
      lastError = err;
      if (err.response?.status === 429) {
        await new Promise(r => setTimeout(r, 1000 * (i + 1)));
      } else {
        break;
      }
    }
  }
  throw lastError;
}

4. 处理OAuth2.0鉴权

企业级API通常需要OAuth2.0鉴权。我在项目中实现了完整的授权码模式：

4.1 授权流程封装

src/auth.ts核心代码：

export class AuthManager {
  private credentials: Credentials;

  async getToken(): Promise<string> {
    if (this.isTokenValid()) {
      return this.credentials.access_token;
    }
    return this.refreshToken();
  }

  private async refreshToken(): Promise<string> {
    const response = await axios.post(
      'https://auth.seniverse.com/oauth2/token',
      {
        client_id: process.env.CLIENT_ID,
        client_secret: process.env.CLIENT_SECRET,
        grant_type: 'refresh_token',
        refresh_token: this.credentials.refresh_token
      }
    );
    this.saveCredentials(response.data);
    return response.data.access_token;
  }

  async startAuthFlow(): Promise<string> {
    // 生成授权页面URL
    const authUrl = new URL('https://auth.seniverse.com/oauth2/authorize');
    authUrl.searchParams.append('response_type', 'code');
    authUrl.searchParams.append('client_id', process.env.CLIENT_ID);
    authUrl.searchParams.append('redirect_uri', 'http://localhost:18789/callback');
    authUrl.searchParams.append('scope', 'weather');
    return authUrl.toString();
  }
}

4.2 在OpenClaw中集成鉴权

在技能入口文件中添加授权处理：

import { OpenClawSkill } from '@openclaw/skill-sdk';

export default new OpenClawSkill()
  .command('weather', async (args, ctx) => {
    if (!ctx.auth.isAuthenticated()) {
      const authUrl = await authManager.startAuthFlow();
      return {
        type: 'oauth_redirect',
        url: authUrl,
        callback: '/weather-callback'
      };
    }
    // ...正常业务逻辑
  });

这里有个实践细节：授权回调地址需要提前在API平台注册。我建议使用OpenClaw网关地址（默认18789端口）作为开发环境回调地址。

5. 编写技能描述文档

OpenClaw通过claw.skill.json理解技能能力。这是我为天气技能编写的完整描述：

{
  "name": "weather",
  "version": "1.0.0",
  "description": "查询实时天气数据，支持全球3000+城市",
  "entry": "./dist/index.js",
  "commands": [
    {
      "name": "weather",
      "description": "获取指定地点的当前天气",
      "parameters": {
        "location": {
          "type": "string",
          "description": "城市名称，如'北京'或'New York'",
          "required": true
        }
      },
      "returns": {
        "temperature": "number",
        "condition": "string"
      }
    }
  ],
  "auth": {
    "type": "oauth2",
    "flows": {
      "authorizationCode": {
        "authorizationUrl": "https://auth.seniverse.com/oauth2/authorize",
        "tokenUrl": "https://auth.seniverse.com/oauth2/token",
        "scopes": {
          "weather": "访问天气数据API"
        }
      }
    }
  }
}

关键字段说明：

• commands：定义自然语言触发的命令结构
• parameters：声明参数类型和约束条件
• auth：让OpenClaw知道需要处理OAuth流程

6. 测试与发布

6.1 本地测试技巧

我习惯用claw dev命令启动开发服务器：

claw dev --port 8080

这会提供：

• 自动重载：修改代码后立即生效
• 调试控制台：查看模型与技能的交互细节
• 测试界面：http://localhost:8080/playground

测试时建议使用真实场景语句，比如：

• "上海现在天气怎么样？"
• "帮我看看纽约的温度"

6.2 发布到ClawHub

首先构建生产版本：

claw build

然后发布到技能市场：

claw publish --access public

发布后其他用户可以通过以下方式安装：

clawhub install weather-skill

或者在OpenClaw对话中直接说："安装天气查询技能"

7. 进阶开发建议

在实际项目中，我总结了几个提升技能质量的技巧：

1. 错误处理：为API定义明确的错误类型，帮助模型理解如何恢复。例如区分"位置不存在"和"服务不可用"。

2. 结果缓存：对频繁查询的数据添加本地缓存，减少API调用。但要注意标注数据时效性。

3. 参数校验：在技能入口处验证参数，比依赖API返回错误更友好。比如提前检测位置是否包含非法字符。

4. 多语言支持：在描述文档中添加多语言字段，让技能可以被不同语言的模型调用。

5. 版本兼容：使用语义化版本控制，当API有重大变更时通过版本号隔离。

开发过程中最耗时的部分是处理各种边界情况。我的经验是：先用简单用例验证核心流程，再逐步添加错误处理和优化。

---

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。