OpenClawをAPIゲートウェイとして活用：HTTP APIガイド

はじめに

OpenClaw は単なるチャットボットフレームワークではなく、本質的に AI Agent ゲートウェイです。Telegram や Discord などのチャットプラットフォーム経由で AI とやり取りするだけでなく、完全な HTTP API インターフェースを公開しており、任意のアプリケーション、スクリプト、サービスからプログラム的に AI Agent を呼び出すことができます。

本記事では、OpenClaw の HTTP API アーキテクチャ、認証方式、主要なエンドポイント、および実際の統合シナリオを体系的に紹介します。

API ゲートウェイの有効化

デフォルトでは、OpenClaw の起動時に HTTP サーバーも同時に起動されます。openclaw.json5 でゲートウェイのパラメータを設定できます。

{
  gateway: {
    // HTTP サービスのリスニングポート
    port: 3000,
    // リスニングアドレス、0.0.0.0 は外部アクセスを許可
    host: "0.0.0.0",
    // API インターフェースの有効化
    apiEnabled: true,
    // API キー認証
    apiKeys: [
      "sk-openclaw-xxxxxxxxxxxx",
      "sk-openclaw-yyyyyyyyyyyy"
    ],
    // CORS 設定
    cors: {
      origins: ["https://your-app.com"],
      methods: ["GET", "POST", "PUT", "DELETE"]
    }
  }
}

有効にすると、API ゲートウェイが指定されたポートで RESTful インターフェースを提供します。

認証方式

すべての API リクエストには認証情報が必要です。OpenClaw は2種類の認証方式をサポートしています。

Bearer Token 認証

curl -X POST http://localhost:3000/api/v1/chat \
  -H "Authorization: Bearer sk-openclaw-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"message": "こんにちは"}'

クエリパラメータ認証

curl "http://localhost:3000/api/v1/agents?api_key=sk-openclaw-xxxxxxxxxxxx"

API キーが URL ログに残らないよう、Bearer Token 方式の使用を推奨します。

主要な API エンドポイント

1. メッセージ送信

最も頻繁に使用されるエンドポイントで、指定された Agent にメッセージを送信し、AI の応答を取得します。

POST /api/v1/chat

リクエストボディ：

{
  "agentId": "my-agent",
  "sessionId": "session-001",
  "message": "ソートアルゴリズムを書いてください",
  "stream": false
}

レスポンスボディ：

{
  "status": "ok",
  "response": {
    "content": "AIの応答内容がここに入ります...",
    "messageId": "msg_abc123",
    "model": "claude-sonnet-4-20250514",
    "usage": {
      "inputTokens": 150,
      "outputTokens": 320
    }
  }
}

2. ストリーミングレスポンス

長い応答の場合は、Server-Sent Events (SSE) モードでストリーミング出力を取得することをお勧めします。

POST /api/v1/chat/stream

curl -N -X POST http://localhost:3000/api/v1/chat/stream \
  -H "Authorization: Bearer sk-openclaw-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"agentId": "my-agent", "message": "クイックソートを詳しく説明して"}'

返される SSE イベントストリーム：

data: {"type":"start","messageId":"msg_def456"}

data: {"type":"text","content":"クイックソート"}
data: {"type":"text","content":"（Quick Sort）"}
data: {"type":"text","content":"は効率的なソートアルゴリズムで..."}

data: {"type":"tool_use","name":"run_code","input":{"code":"..."}}
data: {"type":"tool_result","output":"ソート結果: [1, 2, 3, 5, 8]"}

data: {"type":"end","usage":{"inputTokens":85,"outputTokens":540}}

3. セッション管理

# 特定Agentのすべてのアクティブセッションを一覧表示
GET /api/v1/agents/{agentId}/sessions

# セッション詳細の取得（メッセージ履歴を含む）
GET /api/v1/agents/{agentId}/sessions/{sessionId}

# セッションの削除
DELETE /api/v1/agents/{agentId}/sessions/{sessionId}

# セッションの履歴メッセージをクリア
POST /api/v1/agents/{agentId}/sessions/{sessionId}/clear

4. Agent 情報の照会

# すべてのAgentを一覧表示
GET /api/v1/agents

# 特定のAgent詳細を取得
GET /api/v1/agents/{agentId}

# Agentのツールリストを取得
GET /api/v1/agents/{agentId}/tools

5. システムステータス

# ヘルスチェック
GET /api/v1/health

# システムメトリクス
GET /api/v1/metrics

実際の統合例

Python 統合

import requests

class OpenClawClient:
    def __init__(self, base_url, api_key):
        self.base_url = base_url
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }

    def chat(self, agent_id, message, session_id=None):
        resp = requests.post(
            f"{self.base_url}/api/v1/chat",
            headers=self.headers,
            json={
                "agentId": agent_id,
                "sessionId": session_id,
                "message": message
            }
        )
        return resp.json()["response"]["content"]

client = OpenClawClient("http://localhost:3000", "sk-openclaw-xxx")
reply = client.chat("my-agent", "今日の天気はどうですか？")
print(reply)

Node.js 統合

const response = await fetch("http://localhost:3000/api/v1/chat", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk-openclaw-xxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    agentId: "my-agent",
    message: "このコードを分析してください"
  })
});

const data = await response.json();
console.log(data.response.content);

フロントエンドアプリケーションとの統合

OpenClaw のストリーミング API を使用して、カスタムチャットインターフェースを構築できます。

const eventSource = new EventSource(
  "http://localhost:3000/api/v1/chat/stream?" +
  "agentId=my-agent&message=こんにちは&api_key=sk-openclaw-xxx"
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.type === "text") {
    appendToChat(data.content);
  }
};

レート制限とクォータ

API ゲートウェイにはレート制限機能が組み込まれており、不正利用を防止します。

{
  gateway: {
    rateLimit: {
      // 1分あたりの最大リクエスト数
      maxRequestsPerMinute: 60,
      // 1日あたりの最大Token消費量
      maxTokensPerDay: 1000000,
      // APIキーごとに個別計算
      perKey: true
    }
  }
}

制限を超えた場合、API は 429 Too Many Requests ステータスコードを返します。

OpenAI 互換モード

OpenClaw は OpenAI 互換の API エンドポイントを提供しており、OpenAI SDK で直接 OpenClaw に接続できます。

POST /api/v1/openai/chat/completions

これにより、OpenAI API をサポートするあらゆるクライアントツールが OpenClaw にシームレスに接続でき、base_url を OpenClaw ゲートウェイのアドレスに向けるだけで済みます。

まとめ

OpenClaw の HTTP API ゲートウェイは、AI Agent の能力を標準化されたインターフェースとして公開し、Web アプリケーション、モバイル端末、自動化スクリプト、企業内部システムなど、あらゆる技術スタックに OpenClaw を統合できるようにします。ストリーミングレスポンス、セッション管理、OpenAI 互換モードを組み合わせることで、OpenClaw はシンプルなチャットから複雑なワークフローまで、さまざまな API ゲートウェイシナリオに対応できます。