# 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 호출

```bash
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 호환)

```json
{
  "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` | 사용량 대시보드 |

## 환경 변수

```env
# 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           # 대화 모니터링
```