OpenClaw 지식베이스 및 RAG 검색 증강 튜토리얼

서문

기본적으로 AI 모델은 학습 데이터와 현재 대화 컨텍스트만을 기반으로 질문에 답변합니다. 하지만 실제 시나리오에서는 AI가 회사 문서, 제품 매뉴얼 또는 개인 노트를 참조하여 답변하기를 원하는 경우가 많습니다. RAG(Retrieval-Augmented Generation, 검색 증강 생성) 기술이 바로 이 문제를 해결하는 핵심입니다. 본 글에서는 OpenClaw를 위한 지식베이스 시스템을 단계별로 구축하는 방법을 안내합니다.

1. RAG 원리 간략 소개

1.1 RAG란 무엇인가

RAG의 작동 흐름은 다음과 같습니다:

사용자 질문
  │
  ├── ① 질문을 벡터로 변환 (Embedding)
  │
  ├── ② 벡터 데이터베이스에서 가장 관련성 높은 문서 조각 검색
  │
  ├── ③ 관련 문서 조각을 컨텍스트로 프롬프트에 주입
  │
  └── ④ AI 모델이 컨텍스트를 기반으로 답변 생성

1.2 RAG vs 파일 직접 업로드

대부분의 팀에게 RAG는 가성비가 가장 높은 방안입니다.

2. 지식베이스 디렉토리 설정

2.1 기본 설정

// ~/.config/openclaw/openclaw.json5
{
  "knowledgeBase": {
    "enabled": true,
    // 지식베이스 문서 디렉토리 (복수 지원)
    "directories": [
      {
        "path": "/data/knowledge/company-docs",
        "name": "회사 문서",
        "description": "회사 정책, 프로세스, 규범 등"
      },
      {
        "path": "/data/knowledge/product-docs",
        "name": "제품 문서",
        "description": "제품 사용 매뉴얼, API 문서 등"
      },
      {
        "path": "/home/user/notes",
        "name": "개인 노트",
        "description": "개인 학습 노트 및 메모"
      }
    ],
    // 파일 변경 모니터링
    "watchChanges": true,
    // 변경 후 자동 재인덱싱
    "autoReindex": true
  }
}

2.2 지식베이스 디렉토리 생성

# 문서 디렉토리 생성
sudo mkdir -p /data/knowledge/company-docs
sudo mkdir -p /data/knowledge/product-docs
sudo chown -R $USER:$USER /data/knowledge

# 문서 추가
cp ~/Documents/회사규정.pdf /data/knowledge/company-docs/
cp ~/Documents/API문서.md /data/knowledge/product-docs/
cp -r ~/Documents/기술규범/ /data/knowledge/company-docs/

3. 지원 파일 형식

3.1 파일 형식 지원 목록

3.2 파일 형식 설정

{
  "knowledgeBase": {
    "fileTypes": {
      "include": [".md", ".txt", ".pdf", ".docx", ".html", ".csv"],
      "exclude": [".tmp", ".bak", ".log"],
      // 단일 파일 최대 크기
      "maxFileSize": "10MB",
      // 무시할 디렉토리
      "ignoreDirs": ["node_modules", ".git", "__pycache__"]
    }
  }
}

3.3 PDF 처리 최적화

# PDF 처리 의존성 설치 (PDF 파싱 문제 발생 시)
sudo apt install -y poppler-utils

# PDF 추출 테스트
pdftotext /data/knowledge/company-docs/규정.pdf -

4. 벡터 저장소 설정

4.1 내장 벡터 저장소 (기본)

OpenClaw는 중소 규모 지식베이스에 적합한 경량 벡터 저장 엔진을 내장하고 있습니다:

{
  "knowledgeBase": {
    "vectorStore": {
      "type": "builtin",
      "storagePath": "/var/lib/openclaw/vectors",
      // 벡터 차원 (Embedding 모델에 따라 결정)
      "dimensions": 1536,
      // 유사도 알고리즘
      "similarityMetric": "cosine"
    }
  }
}

4.2 ChromaDB 사용

더 대규모 지식베이스의 경우 ChromaDB를 권장합니다:

# ChromaDB 설치
docker run -d \
  --name chromadb \
  --restart=always \
  -p 8000:8000 \
  -v chroma-data:/chroma/chroma \
  chromadb/chroma:latest

{
  "knowledgeBase": {
    "vectorStore": {
      "type": "chroma",
      "url": "http://localhost:8000",
      "collection": "openclaw_knowledge"
    }
  }
}

4.3 Qdrant 사용

Qdrant는 더 강력한 필터링 및 검색 기능을 제공합니다:

# Qdrant 설치
docker run -d \
  --name qdrant \
  --restart=always \
  -p 6333:6333 \
  -v qdrant-data:/qdrant/storage \
  qdrant/qdrant:latest

{
  "knowledgeBase": {
    "vectorStore": {
      "type": "qdrant",
      "url": "http://localhost:6333",
      "collection": "openclaw_knowledge"
    }
  }
}

4.4 벡터 저장소 비교

5. 청킹 전략

문서를 적절한 크기의 작은 조각(Chunk)으로 분할해야 효과적으로 인덱싱하고 검색할 수 있습니다.

5.1 청킹 매개변수 설정

{
  "knowledgeBase": {
    "chunking": {
      // 청킹 전략
      "strategy": "recursive",
      // 각 청크의 목표 크기 (문자 수)
      "chunkSize": 1000,
      // 인접 청크의 중복 크기
      "chunkOverlap": 200,
      // 구분자 우선순위 (높은 순서에서 낮은 순서)
      "separators": ["\n## ", "\n### ", "\n\n", "\n", "。", ".", " "],
      // 문서 메타데이터 보존
      "preserveMetadata": true
    }
  }
}

5.2 청킹 전략 설명

5.3 청크 크기 선택

청크가 너무 큰 경우 (> 2000자):
  ✗ 검색 정확도 낮음, 무관한 내용 포함
  ✗ 컨텍스트 윈도우 많이 차지

청크가 너무 작은 경우 (< 200자):
  ✗ 컨텍스트 부족, 정보 불완전
  ✗ 검색 횟수 증가

권장 범위: 500-1500자, 중복 100-300자

6. Embedding 모델 설정

6.1 Embedding 모델 선택

{
  "knowledgeBase": {
    "embedding": {
      // OpenAI Embedding 사용
      "provider": "openai",
      "model": "text-embedding-3-small",
      "dimensions": 1536,
      "batchSize": 100
    }
  }
}

6.2 각 Embedding 모델 비교

6.3 로컬 Embedding 사용 (Ollama)

# Embedding 모델 다운로드
ollama pull nomic-embed-text

{
  "knowledgeBase": {
    "embedding": {
      "provider": "ollama",
      "model": "nomic-embed-text",
      "dimensions": 768,
      "baseUrl": "http://localhost:11434"
    }
  }
}

7. 인덱스 관리

7.1 인덱스 구축

# 최초 지식베이스 인덱스 구축
openclaw knowledge index

# 출력 예시:
# 디렉토리 스캔: /data/knowledge/company-docs
# 파일 발견: 45개
# 처리 중... ████████████████████ 100%
# 벡터 생성: 1,234개 문서 청크
# 인덱싱 완료! 소요 시간: 2분 15초

# 인덱스 업데이트 (변경된 파일만 처리)
openclaw knowledge index --update

# 인덱스 재구축 (초기화 후 전체 재구축)
openclaw knowledge index --rebuild

7.2 인덱스 상태 확인

# 지식베이스 상태 확인
openclaw knowledge status

# 출력 예시:
# ┌──────────────────┬────────┬──────────┬──────────────┐
# │ 지식베이스        │ 파일 수 │ 문서 청크 │ 마지막 업데이트 │
# ├──────────────────┼────────┼──────────┼──────────────┤
# │ 회사 문서         │ 45     │ 892      │ 2026-04-09   │
# │ 제품 문서         │ 23     │ 342      │ 2026-04-08   │
# │ 개인 노트         │ 67     │ 234      │ 2026-04-09   │
# ├──────────────────┼────────┼──────────┼──────────────┤
# │ 합계             │ 135    │ 1,468    │              │
# └──────────────────┴────────┴──────────┴──────────────┘

7.3 검색 효과 테스트

# 검색 테스트
openclaw knowledge search "연차 정책은 무엇인가요"

# 검색된 관련 문서 조각과 유사도 점수 출력
# [0.92] company-docs/직원핸드북.pdf (제3장)
#   "정규직 입사 1년 후 5일의 유급 연차를 사용할 수 있습니다..."
# [0.87] company-docs/HR정책.md
#   "연차 신청은 3영업일 전에..."

8. 검색 최적화

8.1 쿼리 최적화 설정

{
  "knowledgeBase": {
    "retrieval": {
      // 가장 관련성 높은 Top K개 결과 반환
      "topK": 5,
      // 최소 유사도 임계값 (이 값 미만의 결과는 폐기)
      "minScore": 0.7,
      // 쿼리 재작성 활성화 (AI가 검색 키워드 최적화)
      "queryRewrite": true,
      // 하이브리드 검색 활성화 (벡터 + 키워드)
      "hybridSearch": true,
      "hybridWeight": 0.7  // 벡터 검색 가중치
    }
  }
}

8.2 검색 결과를 프롬프트에 주입

{
  "knowledgeBase": {
    "promptTemplate": {
      // 검색 결과를 시스템 프롬프트에 주입하는 템플릿
      "prefix": "다음 참고 자료를 바탕으로 사용자의 질문에 답변해 주세요. 참고 자료에 관련 내용이 없으면 솔직히 알려주세요.\n\n---\n참고 자료:\n",
      "suffix": "\n---\n\n위 참고 자료를 바탕으로 답변해 주세요:",
      // 주입할 최대 토큰 수
      "maxTokens": 4000
    }
  }
}

9. 실제 활용 시나리오

9.1 기업 내부 지식베이스

# 회사 문서를 지식베이스에 추가
/data/knowledge/company-docs/
├── 직원핸드북.pdf
├── 비용처리절차.md
├── 기술규범/
│   ├── 코드규범.md
│   ├── 배포절차.md
│   └── 보안규범.md
└── 제품문서/
    ├── 사용자가이드.pdf
    └── API문서.md

사용자가 Telegram에서 "비용 처리 절차가 어떻게 되나요?"라고 질문하면, OpenClaw가 관련 문서를 자동으로 검색하여 정확한 답변을 제공합니다.

9.2 개인 노트 어시스턴트

# Obsidian 노트 직접 연동
/home/user/notes/
├── 기술학습/
│   ├── Docker입문.md
│   ├── Kubernetes노트.md
│   └── Linux명령어사전.md
├── 독서노트/
└── 프로젝트기록/

9.3 고객 서비스 지식베이스

{
  "knowledgeBase": {
    "directories": [
      {
        "path": "/data/knowledge/faq",
        "name": "자주 묻는 질문",
        "description": "고객 자주 묻는 질문 및 표준 답변"
      },
      {
        "path": "/data/knowledge/product-manual",
        "name": "제품 매뉴얼",
        "description": "제품 기능 설명 및 사용 튜토리얼"
      }
    ]
  }
}

10. 유지보수 및 모범 사례

10.1 문서 품질이 검색 품질에 영향을 미침

• 문서 구조가 명확해야 함 (제목, 목록 등 사용)
• 대량의 중복 콘텐츠 지양
• 정기적으로 오래된 문서 정리
• Markdown 형식을 사용하면 최적의 청킹 효과 달성 가능

10.2 정기 유지보수

# 매주 인덱스 재구축 (cron)
0 3 * * 0 openclaw knowledge index --rebuild >> /var/log/openclaw-index.log 2>&1

# 인덱스 상태 점검
openclaw knowledge status

10.3 성능 최적화

지식베이스와 RAG 시스템을 구축하면 OpenClaw가 범용 AI 어시스턴트에서 전용 지식 Q&A 전문가로 업그레이드되어, 보유한 문서를 기반으로 한 다양한 질문에 정확하게 답변할 수 있게 됩니다.