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 설치 및 모델 다운로드