# OpenClaw 集成指南

[OpenClaw](https://docs.openclaw.ai) 是开源 AI Agent 平台，原生支持 MCP 协议。index1 可以为 OpenClaw 提供项目知识库搜索能力。

## 安装 index1

### 方式 A：pip 安装（推荐）

```bash
pip install index1
```

> OpenClaw 容器/服务器环境可能需要 `--break-system-packages` 标志。

### 方式 B：pipx 安装（本地开发）

```bash
pipx install index1
```

### 方式 C：从源码安装

```bash
git clone https://github.com/gladego/index1.git
cd index1
pip install .
```

安装后验证：

```bash
index1 --version       # 应输出 0.1.0+
index1 status          # 查看索引状态
```

---

## 配置三步

<h3>⬛ 第 1 步：配置 MCP — 让 AI 能调用 index1</h3>
<h3>⬛ 第 2 步：添加搜索规则 — 让 AI 知道何时该调用</h3>
<h3>⬜ 第 3 步（可选）：创建 Skill — 常用操作一键触发</h3>

<h3 style="color:red">⚠️ 只做第 1 步 = 装了工具没教 AI 怎么用。第 2 步才是关键！</h3>

---

### 第 1 步：配置 MCP Server

在项目根目录创建 `.mcp.json`：

```json
{
  "mcpServers": {
    "index1": {
      "type": "stdio",
      "command": "index1",
      "args": ["serve"]
    }
  }
}
```

> 如果 `index1` 不在 PATH 中，用 `which index1` 获取完整路径填入 `command`。

重启 OpenClaw 后，5 个 `docs_*` 工具即可使用：`docs_search`、`docs_get`、`docs_status`、`docs_reindex`、`docs_config`。

### 第 2 步：添加搜索规则

在项目 **`.claude/CLAUDE.md`** 中添加：

```markdown
## 搜索策略

本项目已配置 index1 MCP Server（docs_search 等 5 个工具）。搜索代码时遵循：

1. 已知标识符（函数名/类名/文件名）→ 直接 Grep/Glob（4ms）
2. 探索性问题（"XX 怎么实现的"）→ 先 docs_search 定位方向，再 Grep 精确查找
3. 中文查英文代码 → 必须用 docs_search（Grep 不支持跨语言）
4. 高频关键词（预期匹配 > 50 行）→ 优先 docs_search（节省 90%+ 上下文）
```

**效果对比**：

```
❌ 没有规则：Grep "search" 全项目 → 881 行 → 35,895 tokens
✅ 有规则：  docs_search → 5 条摘要 → 460 tokens    节省 97%
```

### 第 3 步（可选）：创建 Skill

Skill 文件放在 `.claude/skills/` 目录，OpenClaw 和 Claude Code 共用：

```
.claude/skills/
├── reindex.md      ← /reindex 重建索引
├── isearch.md      ← /isearch 语义搜索
└── doctor.md       ← /doctor 环境诊断
```

详见 [Claude Code 集成指南 — Skill 配置](integration-claude-code.md)。

---

## 索引项目文件

```bash
# 索引源码和文档
index1 index ./src ./docs

# 查看索引状态
index1 status

# 搜索测试
index1 search "你的查询"
```

---

## 与 Claude Code 共存

OpenClaw 和 Claude Code 共用所有配置文件，无需维护两套：

```
项目根目录/
├── .mcp.json                    ← MCP 配置（共用）
├── .claude/
│   ├── CLAUDE.md                ← 搜索规则（共用）
│   └── skills/                  ← Skill（共用）
├── src/
└── docs/
```

---

## 注意事项

### 1. Ollama 不可用时自动降级

index1 在 Ollama 不可用时自动降级为 BM25-only 模式：

- BM25 全文搜索**完全可用**，延迟约 60-80ms
- 向量语义搜索不可用（跨语言搜索能力受限）
- 不会报错崩溃，只输出提示信息

如需向量搜索：

```bash
# 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取 embedding 模型（按需选择）
ollama pull nomic-embed-text           # 标准，270MB
ollama pull bge-m3                     # 中文最优，1.2GB

# 验证
index1 doctor
```

### 2. 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+ 已自动处理**：低版本 SQLite 会使用兼容的 FTS5 删除方式，无需手动干预。

旧版本（< 0.1.0）会报错 `unrecognized option: "contentless_delete"`，升级即可解决。

### 3. Python 版本

- 最低要求：Python 3.10
- 推荐：Python 3.11+
- 容器环境通常自带 Python 3.11，可直接使用

### 4. 中文搜索

BM25 模式下中文搜索依赖 jieba 分词：

```bash
# 安装中文支持
pip install index1[chinese]

# 验证
index1 doctor    # Check 6 应显示中文支持状态
```

没有 jieba 时，中文 BM25 搜索可能返回 0 结果。英文搜索不受影响。

### 5. 权限问题

OpenClaw 容器内通常以 `node` 用户运行（UID 1000），pip 安装需要 root 权限：

```bash
# 容器内安装
docker exec -u root <container> pip3 install index1 --break-system-packages

# 安装后任何用户都可使用
docker exec <container> index1 --version
```

---

## 验证集成

```
你: 用 docs_status 看一下索引状态
→ 应返回文档数和片段数

你: 搜索功能怎么实现的？
→ AI 应先调用 docs_search，而不是 Grep 全项目
```

## 故障排查

| 问题 | 原因 | 解决 |
|------|------|------|
| 工具没出现 | MCP 配置错误 | 检查 `.mcp.json` 格式和 `index1` 路径 |
| AI 不用 docs_search | 没加搜索规则 | **做第 2 步**，添加 CLAUDE.md |
| `command not found` | index1 不在 PATH | `which index1` 获取完整路径 |
| `contentless_delete` 报错 | index1 版本太旧 | `pip install --upgrade index1` |
| 搜索无结果 | 未索引 | `index1 index ./src ./docs` |
| 中文搜索 0 结果 | 无 jieba 或无 Ollama | `pip install index1[chinese]` |
| 向量搜索不可用 | 无 Ollama | 安装 Ollama 并拉取模型 |
