OpenClaw Skill外部API集成完全指南

前言

外部 API 是 OpenClaw Skill 的能力倍增器。通过集成各种 REST API，你的 AI 助手可以查询实时数据、操作第三方服务、自动化业务流程。本教程系统讲解 API 集成的完整方法论，并提供多个实战案例。

API集成架构

在 OpenClaw 中，Skill 通过 MCP Server（具体来说是 HTTP Fetch 工具）来调用外部 API：

用户消息 → Skill 被触发 → AI 决定调用 API
                              │
                              ▼
                    MCP http_fetch 工具
                              │
                              ▼
                    外部 REST API 服务
                              │
                              ▼
                    返回 JSON 响应
                              │
                              ▼
                    AI 解析并格式化
                              │
                              ▼
                    回复用户

基础配置

配置HTTP Fetch MCP Server

在 ~/.config/openclaw/openclaw.json5 中：

{
  mcp: {
    servers: {
      "http-fetch": {
        command: "npx",
        args: ["-y", "@openclaw-mcp/http-fetch"],
        env: {
          // 默认请求超时时间（毫秒）
          HTTP_TIMEOUT: "30000",
          // 允许访问的域名白名单（可选，增强安全性）
          ALLOWED_DOMAINS: "api.github.com,api.openweathermap.org,api.notion.com"
        }
      }
    }
  }
}

HTTP Fetch工具提供的方法

方法	用途	参数
`http_get`	GET 请求	`url`, `headers`
`http_post`	POST 请求	`url`, `headers`, `body`
`http_put`	PUT 请求	`url`, `headers`, `body`
`http_patch`	PATCH 请求	`url`, `headers`, `body`
`http_delete`	DELETE 请求	`url`, `headers`

认证方式

方式一：API Key认证

最常见的认证方式——在请求头或查询参数中携带密钥。

将 API 密钥安全地存储在 OpenClaw 配置中：

{
  // 集中管理 API 密钥
  secrets: {
    GITHUB_TOKEN: "ghp_xxxxxxxxxxxx",
    OPENWEATHER_KEY: "abcdef1234567890",
    NOTION_TOKEN: "secret_xxxxxxxxxxxx",
    JIRA_TOKEN: "base64_encoded_token"
  },

  mcp: {
    servers: {
      "http-fetch": {
        command: "npx",
        args: ["-y", "@openclaw-mcp/http-fetch"],
        env: {
          // 将密钥传递给 MCP Server
          GITHUB_TOKEN: "${secrets.GITHUB_TOKEN}",
          OPENWEATHER_KEY: "${secrets.OPENWEATHER_KEY}"
        }
      }
    }
  }
}

在 SKILL.md 中引用：

## API Authentication

调用 GitHub API 时，使用以下请求头：
- `Authorization: Bearer {GITHUB_TOKEN}`
- `Accept: application/vnd.github.v3+json`

调用 OpenWeatherMap API 时，在 URL 中添加参数：
- `appid={OPENWEATHER_KEY}`

方式二：OAuth 2.0认证

对于需要 OAuth 的 API（如 Google、Microsoft），流程更复杂：

{
  secrets: {
    GOOGLE_CLIENT_ID: "xxxxx.apps.googleusercontent.com",
    GOOGLE_CLIENT_SECRET: "xxxxx",
    GOOGLE_REFRESH_TOKEN: "1//xxxxx"
  }
}

在 Skill 中处理 OAuth Token 刷新：

## OAuth Token Management

1. 使用 refresh_token 获取新的 access_token：
   POST https://oauth2.googleapis.com/token
   Body: {
     client_id: {GOOGLE_CLIENT_ID},
     client_secret: {GOOGLE_CLIENT_SECRET},
     refresh_token: {GOOGLE_REFRESH_TOKEN},
     grant_type: "refresh_token"
   }

2. 使用返回的 access_token 进行后续 API 调用
3. Token 有效期通常为 1 小时

方式三：Basic Auth

部分 API（如 Jira）使用 Basic Auth：

## Authentication

使用 HTTP Basic Authentication：
- Header: `Authorization: Basic {base64(email:api_token)}`

响应解析

JSON响应解析

大多数 API 返回 JSON。在 SKILL.md 中指导 AI 如何解析：

## Response Parsing

GitHub API 返回的 Issue 列表格式：

```json
[
  {
    "number": 123,
    "title": "Bug: login failed",
    "state": "open",
    "labels": [{"name": "bug"}],
    "user": {"login": "username"},
    "created_at": "2026-03-28T10:00:00Z"
  }
]

提取以下字段：

number → Issue 编号
title → 标题
state → 状态（open/closed）
labels[].name → 标签列表
user.login → 创建者
created_at → 创建时间（转换为本地时区显示）


### 分页处理

很多 API 返回分页结果：

```markdown
## Pagination

GitHub API 使用 Link Header 分页：
- 默认每页 30 条
- 请求参数：`?page=1&per_page=50`
- 响应头 `Link` 包含下一页 URL

处理策略：
- 默认只获取第一页
- 如果用户要求查看更多，获取下一页
- 最多获取 3 页以控制 Token 消耗

错误处理

HTTP状态码处理

在 SKILL.md 中定义错误处理策略：

## Error Handling

根据 HTTP 状态码处理错误：

| 状态码 | 含义 | 处理方式 |
|--------|------|----------|
| 200-299 | 成功 | 正常解析响应 |
| 400 | 请求参数错误 | 检查参数并友好提示用户 |
| 401 | 认证失败 | 提示用户 API 密钥可能已过期 |
| 403 | 权限不足 | 提示用户缺少相关权限 |
| 404 | 资源不存在 | 提示用户检查输入是否正确 |
| 429 | 频率限制 | 告知用户稍后再试 |
| 500+ | 服务器错误 | 告知用户服务暂时不可用 |

所有错误情况下，不要展示原始错误信息给用户，
而是用友好的中文说明问题和建议的解决方法。

超时处理

## Timeout Handling

- API 请求超时设为 15 秒
- 如果超时，告知用户："该服务响应较慢，请稍后重试"
- 不要自动重试（避免重复扣费或重复操作）

重试策略

{
  mcp: {
    servers: {
      "http-fetch": {
        command: "npx",
        args: ["-y", "@openclaw-mcp/http-fetch"],
        env: {
          // 最大重试次数（仅 GET 请求）
          MAX_RETRIES: "2",
          // 重试间隔（毫秒）
          RETRY_DELAY: "1000"
        }
      }
    }
  }
}

频率限制管理

了解API限制

常见 API 的频率限制：

API	限制	备注
GitHub	5000 次/小时	使用 Token 认证时
OpenWeatherMap（免费版）	60 次/分钟	免费套餐
Notion	3 次/秒	每个 integration
Jira Cloud	按套餐不同	基于并发
Google APIs	视具体 API 而定	参考各 API 文档

在Skill中处理频率限制

## Rate Limiting

- 检查响应头中的频率限制信息：
  - `X-RateLimit-Remaining`：剩余配额
  - `X-RateLimit-Reset`：配额重置时间
- 当剩余配额低于 10% 时，提醒用户
- 当收到 429 状态码时，从 `Retry-After` 头获取等待时间

实战案例一：GitHub集成

创建 ~/.openclaw/skills/github.SKILL.md：

---
name: github
version: 1.0.0
description: GitHub 仓库管理和信息查询
triggers:
  - github
  - issue
  - PR
  - pull request
  - 仓库
  - repo
  - commit
mcp_tools:
  - http_fetch
---

# GitHub 集成技能

## Description

查询和管理 GitHub 仓库，包括 Issue、PR、代码搜索等功能。

## API Configuration

- Base URL: `https://api.github.com`
- Auth Header: `Authorization: Bearer {GITHUB_TOKEN}`
- Accept Header: `Accept: application/vnd.github.v3+json`

## Supported Commands

### 查看仓库 Issue
用户说："查看 owner/repo 的 issue" 或 "有什么开放的 bug"

API: `GET /repos/{owner}/{repo}/issues?state=open&per_page=10`

### 查看 PR
用户说："查看 owner/repo 的 PR" 或 "待合并的 PR"

API: `GET /repos/{owner}/{repo}/pulls?state=open&per_page=10`

### 搜索代码
用户说："在 owner/repo 中搜索 xxx"

API: `GET /search/code?q={keyword}+repo:{owner}/{repo}`

### 仓库信息
用户说："查看 owner/repo 的信息"

API: `GET /repos/{owner}/{repo}`

## Output Format

### Issue 列表

📋 {owner}/{repo} 开放的 Issue（共 {total} 个）

#	标题	标签	创建者	创建时间
{number}	{title}	{labels}	@{user}	{date}

显示 1-{n} 条，共 {total} 条


### PR 列表

🔀 {owner}/{repo} 待合并的 PR（共 {total} 个）

#	标题	作者	分支	更新时间
{number}	{title}	@{user}	{head}→{base}	{date}

实战案例二：Jira集成

创建 ~/.openclaw/skills/jira.SKILL.md：

---
name: jira
version: 1.0.0
description: Jira 项目管理集成
triggers:
  - jira
  - 工单
  - ticket
  - sprint
  - 迭代
mcp_tools:
  - http_fetch
---

# Jira 集成技能

## API Configuration

- Base URL: `https://{your-domain}.atlassian.net/rest/api/3`
- Auth: Basic Auth (Base64 编码的 `email:api_token`)
- Content-Type: `application/json`

## Supported Commands

### 查看当前 Sprint
用户说："当前 sprint 的任务" 或 "这个迭代的进度"

API: `GET /board/{boardId}/sprint?state=active`
然后: `GET /sprint/{sprintId}/issue`

### 搜索工单
用户说："搜索关于xxx的工单"

API: `GET /search?jql=text~"{keyword}" ORDER BY updated DESC&maxResults=10`

### 创建工单
用户说："创建一个工单：xxx"

API: `POST /issue`
Body: {
  "fields": {
    "project": {"key": "{projectKey}"},
    "summary": "{title}",
    "issuetype": {"name": "Task"},
    "description": {...}
  }
}

## Output Format

### Sprint 概览

🏃 Sprint: {sprintName} 📅 {startDate} → {endDate}

进度：{completed}/{total} ({percent}%) ▓▓▓▓▓▓▓░░░ {percent}%

待办： • {KEY-123} {title} (@{assignee}) • {KEY-124} {title} (@{assignee})

进行中： • {KEY-125} {title} (@{assignee})

已完成： ✓ {KEY-126} {title}

实战案例三：Notion集成

创建 ~/.openclaw/skills/notion.SKILL.md：

---
name: notion
version: 1.0.0
description: Notion 页面和数据库操作
triggers:
  - notion
  - 笔记
  - note
  - 文档
  - 知识库
mcp_tools:
  - http_fetch
---

# Notion 集成技能

## API Configuration

- Base URL: `https://api.notion.com/v1`
- Auth Header: `Authorization: Bearer {NOTION_TOKEN}`
- Notion-Version: `2022-06-28`
- Content-Type: `application/json`

## Supported Commands

### 搜索页面
用户说："在 Notion 中搜索 xxx"

API: `POST /search`
Body: {"query": "{keyword}", "page_size": 10}

### 查询数据库
用户说："查看 xxx 数据库"

API: `POST /databases/{database_id}/query`

### 创建页面
用户说："在 Notion 记录：xxx"

API: `POST /pages`

## Output Format

### 搜索结果

🔍 Notion 搜索结果："{keyword}"

📄 {页面标题1} 最后编辑：{日期} | 📁 {所在位置}
📄 {页面标题2} 最后编辑：{日期} | 📁 {所在位置}

共找到 {N} 个结果

API密钥安全管理

使用环境变量

最安全的方式是通过环境变量传递密钥，避免将密钥写入配置文件：

# 在 ~/.bashrc 或 ~/.zshrc 中设置
export OPENCLAW_GITHUB_TOKEN="ghp_xxxxx"
export OPENCLAW_NOTION_TOKEN="secret_xxxxx"
export OPENCLAW_JIRA_TOKEN="xxxxx"

然后在配置中引用：

{
  secrets: {
    GITHUB_TOKEN: "${env.OPENCLAW_GITHUB_TOKEN}",
    NOTION_TOKEN: "${env.OPENCLAW_NOTION_TOKEN}",
    JIRA_TOKEN: "${env.OPENCLAW_JIRA_TOKEN}"
  }
}

密钥轮换

定期轮换 API 密钥：

# 更新密钥后重启
export OPENCLAW_GITHUB_TOKEN="new_token_here"
openclaw restart

调试API调用

# 查看所有 API 调用日志
openclaw logs --level verbose --filter http_fetch

# 典型输出
[VERBOSE] http_fetch.http_get -> GET https://api.github.com/repos/owner/repo/issues
[VERBOSE] Request headers: {Authorization: "Bearer ghp_***"}
[VERBOSE] Response: 200 OK (234ms, 12.3KB)
[VERBOSE] Rate limit: 4982/5000 remaining, resets in 52m

最佳实践清单

[ ] 通过环境变量管理 API 密钥——不要硬编码在配置中
[ ] 在 SKILL.md 中清晰定义所有可能的错误场景
[ ] 设置合理的请求超时时间
[ ] 处理分页但限制最大获取页数
[ ] 关注频率限制，避免触发 429 错误
[ ] 使用域名白名单限制可访问的 API
[ ] 对 POST/PUT/DELETE 操作增加确认步骤
[ ] 定期轮换 API 密钥

总结

外部 API 集成是 OpenClaw Skill 最强大的能力之一。通过 MCP HTTP Fetch 工具，你可以让 AI 助手对接几乎任何 REST API 服务。关键是做好认证管理、错误处理和频率限制感知，确保集成稳定可靠。本教程提供的 GitHub、Jira、Notion 案例可以作为参考模板，帮你快速开发其他 API 集成 Skill。