OpenClaw 集成

一键配置 index1，为 OpenClaw AI Agent 添加项目知识库搜索。

1安装方式

标准 Python 包安装，适用于大多数环境

2是否创建快捷 Skill？

创建 /reindex、/isearch、/doctor 快捷命令

3CJK 搜索支持？

安装 jieba 分词，BM25 模式下支持中日韩搜索

复制下面的脚本，粘贴到项目根目录的终端中运行：

🔌 与 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 模式下中日韩搜索需要 jieba 分词：pip install index1[chinese]
没有 jieba 时 CJK BM25 搜索可能返回 0 结果，英文搜索不受影响。
验证：index1 doctor（Check 6 显示中文支持状态）

故障排查

问题	原因	解决
工具没出现	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 并拉取模型