OpenClaw을 API 게이트웨이로 활용하기: HTTP 인터페이스 호출 가이드

서문

OpenClaw은 단순한 챗봇 프레임워크가 아닙니다. 본질적으로 AI Agent 게이트웨이입니다. Telegram, Discord 등 채팅 플랫폼을 통한 AI 상호작용 외에도, OpenClaw은 완전한 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은 두 가지 인증 방식을 지원합니다:

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: {
      // 분당 최대 요청 수
      maxRequestsPerMinute: 60,
      // 일일 최대 Token 소비량
      maxTokensPerDay: 1000000,
      // API Key별 독립 계산
      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의 능력을 표준화된 인터페이스로 노출하여 모든 기술 스택에 OpenClaw을 통합할 수 있게 합니다. 웹 애플리케이션, 모바일, 자동화 스크립트, 기업 내부 시스템 등 어디에서든 사용 가능합니다. 스트리밍 응답, 세션 관리, OpenAI 호환 모드를 결합하여 OpenClaw은 간단한 채팅부터 복잡한 워크플로까지 다양한 API 게이트웨이 시나리오에 활용할 수 있습니다.