pipeline/OPENCLAW_INTEGRATION.md

OpenClaw 멀티 에이전트 AI 통합

개요

Pipeline 프로젝트에 OpenClaw 멀티 에이전트 AI 플랫폼을 빌트인으로 통합했습니다. Pipeline UI에서 에이전트 생성/관리, API 키 발급, 대화 모니터링, 사용량 추적이 가능하며, 외부 서비스에서 Pipeline이 발급한 API 키로 에이전트를 사용할 수 있습니다.

아키텍처

외부 서비스 (ERP, MES, 물류 등)
  │ POST /api/ai/v1/chat/completions
  │ Authorization: Bearer sk-pipe-xxxxx
  ▼
Pipeline Backend (:8080)
  ├── 인증 (JWT 또는 API Key)
  ├── Rate Limit 체크
  ├── 프록시 → OpenClaw Gateway (:18789)
  ├── 응답 로깅 (토큰, 비용)
  └── DB 저장 (PostgreSQL)
       ▼
OpenClaw Gateway (내장 프로세스)
  ├── Agent A (데이터 분석)
  ├── Agent B (보고서 작성)
  ├── Agent C (모니터링)
  └── LLM: Claude / GPT / Ollama

DB 테이블

테이블	용도
ai_agents	에이전트 정의 (이름, 모델, 시스템프롬프트, 도구, 상태)
ai_agent_api_keys	외부 서비스용 API 키 (해시 저장, 사용량 제한)
ai_agent_conversations	대화 세션
ai_agent_messages	대화 메시지
ai_agent_usage_logs	토큰 사용량, 비용, 응답시간 로그
ai_llm_providers	LLM API 키 관리 (암호화 저장)

API 엔드포인트

에이전트 관리 (Pipeline JWT 인증)

GET    /api/ai-agents              에이전트 목록
GET    /api/ai-agents/:id          에이전트 상세
POST   /api/ai-agents              에이전트 생성
PUT    /api/ai-agents/:id          에이전트 수정
DELETE /api/ai-agents/:id          에이전트 삭제

API 키 관리 (Pipeline JWT 인증)

GET    /api/ai-agents/keys/list    키 목록
POST   /api/ai-agents/keys         키 발급 (sk-pipe-xxx 형태, 한 번만 노출)
DELETE /api/ai-agents/keys/:id     키 폐기

LLM 프로바이더 관리 (Pipeline JWT 인증)

GET    /api/ai-agents/providers/list    프로바이더 목록
POST   /api/ai-agents/providers         프로바이더 추가 (API 키 암호화 저장)
PUT    /api/ai-agents/providers/:id     프로바이더 수정
DELETE /api/ai-agents/providers/:id     프로바이더 삭제

대화 모니터링 (Pipeline JWT 인증)

GET    /api/ai-agents/conversations/list    대화 목록 (페이징)
GET    /api/ai-agents/conversations/:id     대화 + 메시지 상세

사용량 (Pipeline JWT 인증)

GET    /api/ai-agents/usage/summary    요약 (오늘/이번달 토큰, 비용)
GET    /api/ai-agents/usage/logs       상세 로그 (페이징)
GET    /api/ai-agents/usage/daily      일별 차트 데이터

외부 서비스용 프록시 (API Key 인증)

POST   /api/ai/v1/chat/completions    OpenAI 호환 채팅 (스트리밍 지원)
GET    /api/ai/v1/models              사용 가능 모델 목록
GET    /api/ai/v1/health              Gateway 상태

외부 서비스에서 사용하기

1. API 키 발급

Pipeline 관리자 화면 > AI 에이전트 > API 키 관리에서 키를 발급합니다. sk-pipe-xxxxxxxx 형태의 키가 생성되며, 최초 1회만 노출됩니다.

2. 채팅 API 호출

curl -X POST https://pipeline.example.com/api/ai/v1/chat/completions \
  -H "Authorization: Bearer sk-pipe-xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "messages": [
      {"role": "user", "content": "매출 데이터를 분석해줘"}
    ]
  }'

3. 응답 형태 (OpenAI 호환)

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "claude-sonnet-4-20250514",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "매출 데이터 분석 결과..." },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 200,
    "total_tokens": 215
  }
}

프론트엔드 관리 화면

경로	기능
/admin/aiAssistant/agents	에이전트 CRUD (카드형 목록)
/admin/aiAssistant/providers	LLM API 키 등록/관리
/admin/aiAssistant/conversations	대화 모니터링 (메시지 열람)
/admin/aiAssistant/api-keys	외부 서비스용 API 키 발급
/admin/aiAssistant/usage	사용량 대시보드

환경 변수

# OpenClaw Gateway 포트 (기본: 18789)
OPENCLAW_GATEWAY_PORT=18789

# OpenClaw 활성화 여부 (기본: true)
OPENCLAW_ENABLED=true

파일 구조

backend-node/src/
├── controllers/aiAgentController.ts     # 에이전트/키/프로바이더/대화/사용량 컨트롤러
├── services/
│   ├── aiAgentService.ts                # 에이전트 CRUD
│   ├── aiAgentApiKeyService.ts          # API 키 발급/검증
│   ├── aiAgentProviderService.ts        # LLM 프로바이더 관리
│   ├── aiAgentConversationService.ts    # 대화 로깅
│   └── aiAgentUsageService.ts           # 사용량 추적
├── routes/
│   ├── aiAgentRoutes.ts                 # 관리 API 라우트
│   └── openClawProxyRoutes.ts           # 외부 서비스 프록시
├── middleware/
│   └── aiApiKeyAuthMiddleware.ts        # API 키 인증
├── utils/startOpenClaw.ts               # Gateway 프로세스 관리
├── types/aiAgent.ts                     # TypeScript 타입
└── db/migrations/
    └── 300_create_openclaw_tables.sql   # 마이그레이션

frontend/
├── lib/api/aiAgent.ts                   # API 클라이언트
└── app/(main)/admin/aiAssistant/
    ├── agents/page.tsx                  # 에이전트 관리
    ├── providers/page.tsx               # 프로바이더 관리
    └── conversations/page.tsx           # 대화 모니터링