如何调用外部 API 并处理响应

很多技能需要调用外部 API 获取数据或发送请求。本文教你在 OpenClaw 技能中正确调用外部 API 并处理响应。

使用 Node.js 内置 https 模块

Node.js 自带 https 模块，可以直接用，不需要安装依赖：

const https = require('https');

function getJson(url) {
  return new Promise((resolve, reject) => {
    https.get(url, (res) => {
      let data = '';
      res.on('data', (chunk) => data += chunk);
      res.on('end', () => {
        try {
          const result = JSON.parse(data);
          resolve(result);
        } catch (e) {
          reject(e);
        }
      });
    });
    res.on('error', (e) => reject(e));
  });
}

// 使用
const data = await getJson('https://api.example.com/data');

这是最简单的方式，适合 GET 请求。

使用 axios 库（更方便）

如果需要 POST 请求或者更多功能，可以使用 axios：

安装：

cd your-skill
npm install axios

使用：

const axios = require('axios');

async function getData() {
  try {
    const response = await axios.get('https://api.example.com/data');
    return response.data;
  } catch (error) {
    console.error(error);
    return {error: error.message};
  }
}

axios 自动处理 JSON，比 https 模块更方便。

完整示例：调用和风天气 API

const axios = require('axios');

const API_KEY = process.env.QWEATHER_API_KEY;

async function getCurrentWeather(city) {
  try {
    // 第一步：查询城市 ID
    const locationResponse = await axios.get(
      'https://geoapi.qweather.com/v2/city/lookup',
      { params: { location: city, key: API_KEY } }
    );
    
    if (locationResponse.data.code !== '200') {
      return {error: `城市查询失败: ${locationResponse.data.message}`};
    }
    
    const locationId = locationResponse.data.location[0].id;
    
    // 第二步：查询天气
    const weatherResponse = await axios.get(
      'https://devapi.qweather.com/v7/weather/now',
      { params: { location: locationId, key: API_KEY } }
    );
    
    if (weatherResponse.data.code !== '200') {
      return {error: `天气查询失败: ${weatherResponse.data.message}`};
    }
    
    // 返回结构化数据
    return {
      city: locationResponse.data.location[0].name,
      temp: weatherResponse.data.now.temp,
      text: weatherResponse.data.now.text
    };
    
  } catch (error) {
    // 捕获网络错误
    return {error: `请求失败: ${error.message}`};
  }
}

错误处理最佳实践

一定要捕获错误

// ✅ 好
try {
  const response = await axios.get(url);
  return response.data;
} catch (error) {
  return {error: error.message};
}

// ❌ 不好
const response = await axios.get(url);
return response.data;

如果出错了，返回 {error: "错误信息"}，AI 能理解并告诉你哪里错了。

检查 API 返回码

if (result.code !== '200') {
  return {error: `API 返回错误: ${result.message}`};
}

很多 API 返回 200 HTTP 状态码但业务上是错误，一定要检查。

认证方式

1. Query 参数

const response = await axios.get(url, {
  params: { key: API_KEY }
});

这是最常见的方式，比如和风天气。

2. Header 认证

const response = await axios.get(url, {
  headers: { Authorization: `Bearer ${ACCESS_TOKEN}` }
});

3. Basic Auth

const response = await axios.get(url, {
  auth: {
    username: 'username',
    password: 'password'
  }
});

POST 请求示例

async function createPost(title, content) {
  try {
    const response = await axios.post(
      'https://api.example.com/posts',
      { title, content },
      { headers: { Authorization: `Bearer ${TOKEN}` } }
    );
    return {success: true, id: response.data.id};
  } catch (error) {
    return {error: error.message};
  }
}

处理不同类型的响应

JSON 响应（最常见）

axios 自动解析 JSON：

const data = response.data;

纯文本响应

const response = await axios.get(url, {responseType: 'text'});
const text = response.data;

二进制数据（图片等）

const response = await axios.get(url, {responseType: 'arraybuffer'});
// 保存到文件
fs.writeFileSync('image.jpg', response.data);

总结

在 OpenClaw 技能中调用 API：

1. 简单 GET 请求 → 用内置 https 模块，不需要依赖
2. 复杂请求 → 用 axios，更方便
3. 永远要做错误处理，捕获异常，返回结构化错误
4. API Key 放在环境变量，不要硬编码
5. 返回 JSON 给 AI，方便 AI 解析

按照这个模式，你可以轻松开发调用任何外部 API 的技能！