OpenClaw 연동 — index1

← 돌아가기

# OpenClaw 연동

원클릭 설정으로 index1을 구성하여 OpenClaw AI Agent에 프로젝트 지식 검색을 추가합니다.

1설치 방법
표준 Python 패키지 설치, 대부분의 환경에 적합
2Skill 바로가기를 만들까요?
/reindex, /isearch, /doctor 단축 명령 생성
3CJK 검색 지원?
jieba 설치, BM25 모드에서 CJK 검색 지원

아래 스크립트를 복사하여 프로젝트 루트 터미널에서 실행하세요:

🔌 Claude Code와 설정 공유
스크립트가 생성하는 `.mcp.json`과 `.claude/CLAUDE.md`는 OpenClaw와 Claude Code 모두에서 사용할 수 있으며, 별도로 두 벌을 유지할 필요가 없습니다.
⚠️ 컨테이너 환경?
OpenClaw Docker 컨테이너 내에서 pip는 root 권한이 필요합니다: `docker exec -u root <컨테이너> pip3 install index1 --break-system-packages`
✅ 검증
OpenClaw를 재시작한 후 `docs_status로 인덱스 상태를 확인해 줘`를 입력하세요
AI가 docs_status를 호출하면 → 설정 성공
AI가 도구를 찾을 수 없다고 하면 → .mcp.json 경로가 올바른지 확인하세요
주의사항
Ollama 사용 불가 시 자동 폴백
index1은 Ollama를 사용할 수 없을 때 자동으로 BM25-only 모드로 폴백합니다:
• BM25 전문 검색은 완전히 사용 가능하며, 지연 시간은 약 60-80ms입니다
• 벡터 시맨틱 검색은 사용할 수 없습니다 (크로스 언어 검색 제한)
• 오류가 발생하지 않으며, 안내 메시지만 출력됩니다
벡터 검색이 필요한 경우: `curl -fsSL https://ollama.com/install.sh | sh && ollama pull nomic-embed-text`
SQLite 버전 호환성
index1은 FTS5 `contentless_delete`(SQLite ≥ 3.43.0 필요)를 사용하며, 낮은 버전에서는 자동으로 폴백됩니다.

환경 | SQLite | 동작
--- | --- | ---
macOS 14+ / Python 3.12+ | 3.43+ | 전체 기능
Debian Bookworm (Docker) | 3.40 | 자동 폴백
Ubuntu 22.04 | 3.37 | 자동 폴백

v0.1.0+에서 자동으로 처리됩니다. 이전 버전에서 `contentless_delete` 오류가 발생하면 업그레이드하세요.
Python 버전 요구사항
최소 Python 3.10, 3.11 이상을 권장합니다. OpenClaw 컨테이너에는 Python 3.11이 내장되어 있습니다.
CJK 검색은 jieba에 의존
BM25 모드에서 CJK 검색을 사용하려면 jieba 분사기가 필요합니다: `pip install index1[chinese]`
jieba가 없으면 CJK BM25 검색이 결과를 반환하지 않을 수 있으며, 영어 검색에는 영향이 없습니다.
검증: `index1 doctor` (Check 6에서 CJK 지원 상태 확인)
문제 해결

문제 | 원인 | 해결
--- | --- | ---
도구가 표시되지 않음 | MCP 설정 오류 | `.mcp.json` 확인
AI가 docs_search를 사용하지 않음 | 검색 규칙 미설정 | `.claude/CLAUDE.md` 확인
`command not found` | index1이 PATH에 없음 | `which index1`로 전체 경로 확인
`contentless_delete` 오류 | 버전이 너무 오래됨 | `pip install --upgrade index1`
검색 결과 없음 | 인덱싱 안 됨 | `index1 index ./src ./docs`
CJK 검색 결과 0건 | jieba 없음 | `pip install index1[chinese]`
벡터 검색 사용 불가 | Ollama 없음 | Ollama 설치 및 모델 다운로드