ホーム チュートリアル カテゴリ Skills サイトについて
ZH EN JA KO
スキル・プラグイン

OpenClaw Skillによる外部API連携完全チュートリアル

· 21 分で読了

はじめに

外部 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

認証方式

方式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 によるページネーションを使用：
- デフォルトは1ページあたり30件
- リクエストパラメータ：`?page=1&per_page=50`
- レスポンスヘッダー `Link` に次ページの URL を含む

処理戦略：
- デフォルトでは最初のページのみ取得
- ユーザーがさらに見たい場合、次のページを取得
- Token 消費を抑えるため最大3ページまで

エラーハンドリング

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 (Free) 60回/分 無料プラン
Notion 3回/秒 インテグレーションごと
Jira Cloud プランに依存 同時接続数による
Google APIs 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 を見せて」または「オープンなバグは何がある？」

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}

実践事例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 の3つの実践事例を、他の API 統合 Skill を開発する際のリファレンステンプレートとしてご活用ください。

OpenClawは無料のオープンソースAIアシスタント。WhatsApp、Telegram、Discordなど多数のプラットフォームに対応
他のチュートリアル Skillsダウンロード

関連チュートリアル

OpenClawのカスタムSkillを開発する方法
OpenClawツールチェーン処理パイプライン詳解
OpenClawシステムプロンプトのカスタマイズと動的構築