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 도구에서 제공하는 메서드

인증 방식

방식 1: API Key 인증

가장 일반적인 인증 방식으로, Key를 요청 헤더 또는 쿼리 매개변수에 넣습니다.

OpenClaw 설정에서 API Key를 안전하게 저장합니다:

{
  // 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}`

방식 2: 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시간

방식 3: 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의 빈도 제한:

Skill에서 빈도 제한 처리

## Rate Limiting

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

실전 사례 1: 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} 个）

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

### PR 列表

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

실전 사례 2: 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 (`email:api_token` 的 Base64 编码)
- 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}

실전 사례 3: 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. 📄 {页面标题1} 最后编辑：{日期} | 📁 {所在位置}

2. 📄 {页面标题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 개발의 참고 템플릿으로 활용하실 수 있습니다.