NemoClawのAPI連携ガイド｜外部サービスとの接続方法

NemoClawのAPI連携概要

NemoClawは3つの主要な連携手段を提供しており、既存システムやSaaSサービスとの統合が柔軟に行えます。

連携先ごとに最適な方式が異なります。本ガイドでは各方式の設定手順と実装例を順に解説します。

REST API連携の実装

NemoClawのREST APIは https://localhost:8765/v1/ で公開されており（デフォルト）、外部サービスから直接呼び出せます。

認証設定（APIキーとJWT）

REST APIへのアクセスには blueprint.yaml でAPIキー認証またはJWT認証を設定します。

# blueprint.yaml - API認証設定
api:
  host: "0.0.0.0"
  port: 8765
  auth:
    mode: "api_key"           # "api_key" | "jwt" | "none"
    api_key: "${NEMOCLAW_API_KEY}"
    # JWT使用時
    # mode: "jwt"
    # jwt_secret: "${JWT_SECRET}"
    # jwt_algorithm: "HS256"

呼び出し側（外部サービス）はヘッダーにAPIキーを含めます。

# REST APIへのリクエスト例
curl -X POST https://your-server:8765/v1/agent/run \
  -H "Authorization: Bearer ${NEMOCLAW_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "session-abc123",
    "message": "月次売上レポートを作成してください",
    "context": {
      "user_id": "u-001",
      "role": "analyst"
    }
  }'

レート制限の設定

企業環境ではレート制限を必ず設定してください。API濫用を防ぎ、コストを制御できます。

# blueprint.yaml - レート制限
api:
  rate_limit:
    enabled: true
    requests_per_minute: 60    # セッション全体
    requests_per_user: 10      # ユーザーごと（context.user_idベース）
    burst: 5                   # バースト許容数
    on_exceed: "429"           # 超過時: "429" | "queue" | "drop"

レート制限に引っかかった場合、APIは HTTP 429 Too Many Requests と Retry-After ヘッダーを返します。

# 429レスポンス例
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json

{
  "error": "rate_limit_exceeded",
  "message": "レート制限に達しました。30秒後に再試行してください。",
  "retry_after": 30
}

エラーハンドリングの実装

NemoClawのREST APIは標準的なHTTPステータスコードとJSON形式のエラーを返します。呼び出し側で適切にハンドリングしてください。

# Python - エラーハンドリング実装例
import httpx
import time

def call_nemoclaw(message: str, retries: int = 3) -> dict:
    url = "https://your-server:8765/v1/agent/run"
    headers = {"Authorization": f"Bearer {NEMOCLAW_API_KEY}"}
    payload = {"session_id": "s-001", "message": message}

    for attempt in range(retries):
        try:
            resp = httpx.post(url, json=payload, headers=headers, timeout=30)
            resp.raise_for_status()
            return resp.json()
        except httpx.HTTPStatusError as e:
            if e.response.status_code == 429:
                retry_after = int(e.response.headers.get("Retry-After", 30))
                time.sleep(retry_after)
            elif e.response.status_code >= 500:
                time.sleep(2 ** attempt)  # 指数バックオフ
            else:
                raise  # 4xxは即エラー
    raise RuntimeError("最大リトライ回数を超えました")

Webhook連携の実装

NemoClawはエージェントの実行完了・エラー・ポリシー違反などのイベントをWebhookでリアルタイムに通知できます。

Webhookエンドポイントの設定

# blueprint.yaml - Webhook設定
webhooks:
  enabled: true
  endpoints:
    - url: "https://your-app.example.com/nemoclaw/webhook"
      secret: "${WEBHOOK_SECRET}"        # HMAC-SHA256署名用
      events:
        - "agent.run.completed"          # 実行完了
        - "agent.run.failed"             # 実行失敗
        - "policy.violation"             # ポリシー違反
        - "rate_limit.exceeded"          # レート制限超過
      timeout_seconds: 10
      retry:
        max_attempts: 3
        backoff: "exponential"           # "linear" | "exponential"

Webhook署名の検証

セキュリティ上、必ずWebhookリクエストの署名を検証してください。NemoClawはHMAC-SHA256でリクエストボディに署名を付与します。

# PHP - Webhook署名検証
function verifyNemoClawWebhook(string $payload, string $signature, string $secret): bool {
    $expected = "sha256=" . hash_hmac("sha256", $payload, $secret);
    return hash_equals($expected, $signature);
}

// 受信処理
$payload   = file_get_contents("php://input");
$signature = $_SERVER["HTTP_X_NEMOCLAW_SIGNATURE"] ?? "";

if (!verifyNemoClawWebhook($payload, $signature, WEBHOOK_SECRET)) {
    http_response_code(403);
    exit("Invalid signature");
}

$event = json_decode($payload, true);
switch ($event["type"]) {
    case "agent.run.completed":
        // 完了処理
        processAgentResult($event["data"]);
        break;
    case "policy.violation":
        // セキュリティアラート
        notifySecurityTeam($event["data"]);
        break;
}

MCP（Model Context Protocol）連携

MCPはNemoClawがOpenClaw経由で外部ツールを呼び出す際の標準プロトコルです。自社のAPIや社内システムをMCPサーバーとして公開することで、NemoClawエージェントがそれらを直接利用できるようになります。

MCPサーバーの実装例

Node.jsで社内の顧客データAPIをMCPサーバーとして公開する例を示します。

// mcp-crm-server.js - 社内CRM連携MCPサーバー
const { MCPServer, Tool } = require("@anthropic-ai/mcp");

const server = new MCPServer({
  name: "crm-connector",
  version: "1.0.0",
});

// ツール定義: 顧客検索
server.addTool(new Tool({
  name: "search_customers",
  description: "顧客名またはメールで顧客を検索します",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "検索クエリ（名前またはメール）" },
      limit: { type: "number", description: "取得件数（最大50）", default: 10 },
    },
    required: ["query"],
  },
  handler: async ({ query, limit = 10 }) => {
    const results = await crmApi.searchCustomers(query, limit);
    return { content: [{ type: "text", text: JSON.stringify(results) }] };
  },
}));

server.start();

# blueprint.yaml - MCPサーバー登録
mcp_servers:
  - name: "crm-connector"
    command: "node"
    args: ["./mcp-servers/mcp-crm-server.js"]
    env:
      CRM_API_KEY: "${CRM_API_KEY}"
      CRM_BASE_URL: "${CRM_BASE_URL}"

MCPサーバーのセキュリティ設定

MCPサーバーはNemoClawのサンドボックス内で実行されますが、外部APIへの通信が発生するため追加のセキュリティ設定を推奨します。

# blueprint.yaml - MCPサーバーへのポリシー適用
mcp_servers:
  - name: "crm-connector"
    command: "node"
    args: ["./mcp-servers/mcp-crm-server.js"]
    policy:
      allow_network: ["crm.your-company.internal"]  # アクセス許可ホスト限定
      allow_tools:                                   # 使用可能ツール限定
        - "search_customers"
        - "get_customer_detail"
      deny_tools:
        - "delete_customer"                          # 削除操作は禁止
        - "update_payment_info"                      # 決済情報変更は禁止

連携状態の監視とデバッグ

API連携が正常に動作しているかを継続的に監視するための設定を解説します。

# blueprint.yaml - 連携監視設定
observability:
  api_calls:
    log_requests: true       # リクエストをログに記録
    log_responses: false     # レスポンスは機密情報を含む可能性があるため無効推奨
    slow_threshold_ms: 2000  # 2秒超をスロークエリとしてアラート
  mcp_tools:
    log_invocations: true
    log_results: false
  webhooks:
    log_deliveries: true
    log_failures: true

接続状態はNemoClawのヘルスチェックAPIで確認できます。

# ヘルスチェックAPI
curl https://your-server:8765/v1/health

# 出力例
{
  "status": "healthy",
  "version": "0.3.2",
  "inference_engine": "ready",
  "mcp_servers": {
    "crm-connector": "connected",
    "slack-connector": "connected"
  },
  "api": "ready",
  "webhook_queue": 0
}

API連携のベストプラクティス

NemoClawと外部サービスを安全・安定して連携させるために、以下の原則を守ってください。