Complete Guide to External API Integration in OpenClaw Skills

Introduction

External APIs are force multipliers for OpenClaw Skills. By integrating various REST APIs, your AI assistant can query real-time data, operate third-party services, and automate business processes. This tutorial systematically covers the complete methodology of API integration and provides multiple hands-on examples.

API Integration Architecture

In OpenClaw, Skills call external APIs through MCP Servers (specifically the HTTP Fetch tool):

User message → Skill triggered → AI decides to call API
                              │
                              ▼
                    MCP http_fetch tool
                              │
                              ▼
                    External REST API service
                              │
                              ▼
                    Returns JSON response
                              │
                              ▼
                    AI parses and formats
                              │
                              ▼
                    Reply to user

Basic Configuration

Configuring the HTTP Fetch MCP Server

In ~/.config/openclaw/openclaw.json5:

{
  mcp: {
    servers: {
      "http-fetch": {
        command: "npx",
        args: ["-y", "@openclaw-mcp/http-fetch"],
        env: {
          // Default request timeout (milliseconds)
          HTTP_TIMEOUT: "30000",
          // Allowed domain whitelist (optional, enhances security)
          ALLOWED_DOMAINS: "api.github.com,api.openweathermap.org,api.notion.com"
        }
      }
    }
  }
}

Methods Provided by the HTTP Fetch Tool

Method	Purpose	Parameters
`http_get`	GET requests	`url`, `headers`
`http_post`	POST requests	`url`, `headers`, `body`
`http_put`	PUT requests	`url`, `headers`, `body`
`http_patch`	PATCH requests	`url`, `headers`, `body`
`http_delete`	DELETE requests	`url`, `headers`

Authentication Methods

Method 1: API Key Authentication

The most common authentication method — include the key in request headers or query parameters.

Store API keys securely in the OpenClaw configuration:

{
  // Centralized API key management
  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: {
          // Pass keys to the MCP Server
          GITHUB_TOKEN: "${secrets.GITHUB_TOKEN}",
          OPENWEATHER_KEY: "${secrets.OPENWEATHER_KEY}"
        }
      }
    }
  }
}

Reference them in SKILL.md:

## API Authentication

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

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

Method 2: OAuth 2.0 Authentication

For APIs requiring OAuth (such as Google or Microsoft), the flow is more involved:

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

Handle OAuth token refresh in the Skill:

## 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 小时

Method 3: Basic Auth

Some APIs (like Jira) use Basic Auth:

## Authentication

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

Response Parsing

JSON Response Parsing

Most APIs return JSON. Guide the AI on how to parse it in your SKILL.md:

## 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 → 创建时间（转换为本地时区显示）


### Pagination Handling

Many APIs return paginated results:

```markdown
## Pagination

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

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

Error Handling

HTTP Status Code Handling

Define error handling strategies in your SKILL.md:

## Error Handling

根据 HTTP 状态码处理错误：

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

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

Timeout Handling

## Timeout Handling

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

Retry Strategy

{
  mcp: {
    servers: {
      "http-fetch": {
        command: "npx",
        args: ["-y", "@openclaw-mcp/http-fetch"],
        env: {
          // Maximum retry count (GET requests only)
          MAX_RETRIES: "2",
          // Retry interval (milliseconds)
          RETRY_DELAY: "1000"
        }
      }
    }
  }
}

Rate Limit Management

Understanding API Limits

Common API rate limits:

API	Limit	Notes
GitHub	5000 requests/hour	With token authentication
OpenWeatherMap (Free)	60 requests/minute	Free tier
Notion	3 requests/second	Per integration
Jira Cloud	Plan-dependent	Based on concurrency
Google APIs	Varies by API	See individual API docs

Handling Rate Limits in Skills

## Rate Limiting

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

Hands-On Example 1: GitHub Integration

Create ~/.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}

Hands-On Example 2: Jira Integration

Create ~/.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-encoded `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}

Hands-On Example 3: Notion Integration

Create ~/.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 Key Security Management

Using Environment Variables

The most secure approach is passing keys through environment variables, avoiding writing them in configuration files:

# Set in ~/.bashrc or ~/.zshrc
export OPENCLAW_GITHUB_TOKEN="ghp_xxxxx"
export OPENCLAW_NOTION_TOKEN="secret_xxxxx"
export OPENCLAW_JIRA_TOKEN="xxxxx"

Then reference them in the configuration:

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

Key Rotation

Rotate API keys periodically:

# After updating the key, restart
export OPENCLAW_GITHUB_TOKEN="new_token_here"
openclaw restart

Debugging API Calls

# View all API call logs
openclaw logs --level verbose --filter http_fetch

# Typical output
[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

Best Practices Checklist

[ ] Manage API keys via environment variables — never hardcode in configuration
[ ] Clearly define all possible error scenarios in SKILL.md
[ ] Set reasonable request timeouts
[ ] Handle pagination but limit the maximum number of pages
[ ] Monitor rate limits to avoid triggering 429 errors
[ ] Use domain whitelists to restrict accessible APIs
[ ] Add confirmation steps for POST/PUT/DELETE operations
[ ] Rotate API keys periodically

Summary

External API integration is one of the most powerful capabilities of OpenClaw Skills. Through the MCP HTTP Fetch tool, you can enable your AI assistant to interact with virtually any REST API service. The key is proper authentication management, error handling, and rate limit awareness to ensure stable and reliable integrations. The GitHub, Jira, and Notion examples provided in this tutorial can serve as reference templates for building other API integration Skills.