OpenClaw知识库和RAG检索增强教程

前言

默认情况下，AI 模型只能基于训练数据和当前对话上下文来回答问题。但在实际场景中，你往往希望 AI 能够参考公司文档、产品手册或个人笔记来回答。RAG（Retrieval-Augmented Generation，检索增强生成）技术正是解决这个问题的关键。本文将手把手教你为 OpenClaw 搭建一套知识库系统。

一、RAG 原理简述

1.1 什么是 RAG

RAG 的工作流程如下：

用户提问
  │
  ├── ① 将问题转换为向量（Embedding）
  │
  ├── ② 在向量数据库中搜索最相关的文档片段
  │
  ├── ③ 将相关文档片段作为上下文注入提示词
  │
  └── ④ AI 模型基于上下文生成回答

1.2 RAG vs 直接上传文件

方式	优点	缺点
直接粘贴文本	简单直接	受上下文窗口限制
RAG 检索	支持海量文档	需要额外配置
微调模型	知识内化	成本高、不灵活

对于大多数团队来说，RAG 是性价比最高的方案。

二、配置知识库目录

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.1 文件格式支持列表

格式	扩展名	支持程度	说明
Markdown	.md	完全支持	推荐格式，保留结构
纯文本	.txt	完全支持	简单直接
PDF	.pdf	完全支持	自动提取文本
Word	.docx	完全支持	自动提取文本和表格
HTML	.html	支持	提取正文内容
CSV	.csv	支持	表格数据
JSON	.json	支持	结构化数据
EPUB	.epub	基本支持	电子书内容
代码文件	.py/.js/.go 等	支持	代码注释和文档

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.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 向量存储对比

存储方案	文档规模	查询速度	部署复杂度	适用场景
内置	< 1万条	快	无需额外部署	个人/小团队
ChromaDB	< 10万条	快	简单	中等规模
Qdrant	< 100万条	很快	中等	大规模/生产

五、分块策略

文档需要被切割为合适的小块（Chunk），才能被有效地索引和检索。

5.1 分块参数配置

{
  "knowledgeBase": {
    "chunking": {
      // 分块策略
      "strategy": "recursive",
      // 每个块的目标大小（字符数）
      "chunkSize": 1000,
      // 相邻块的重叠大小
      "chunkOverlap": 200,
      // 分隔符优先级（从高到低）
      "separators": ["\n## ", "\n### ", "\n\n", "\n", "。", ".", " "],
      // 保留文档元数据
      "preserveMetadata": true
    }
  }
}

5.2 分块策略说明

策略	说明	适用场景
`fixed`	固定字符数切割	无明显结构的文本
`recursive`	按分隔符递归切割	通用文档（推荐）
`markdown`	按 Markdown 标题切割	Markdown 文件
`semantic`	按语义边界切割	质量要求高的场景

5.3 分块大小选择

分块太大（> 2000字符）：
  ✗ 检索精度低，包含无关内容
  ✗ 占用更多上下文窗口

分块太小（< 200字符）：
  ✗ 缺少上下文，信息不完整
  ✗ 增加检索次数

推荐范围：500-1500 字符，重叠 100-300 字符

六、Embedding 模型配置

6.1 选择 Embedding 模型

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

6.2 各 Embedding 模型对比

模型	维度	质量	速度	费用
OpenAI text-embedding-3-large	3072	最高	快	$0.13/1M tokens
OpenAI text-embedding-3-small	1536	高	很快	$0.02/1M tokens
Ollama nomic-embed-text	768	中	中	免费（本地）
Ollama mxbai-embed-large	1024	中高	中	免费（本地）

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.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章)
#   "正式员工入职满一年后享有5天带薪年假..."
# [0.87] company-docs/HR政策.md
#   "年假申请需提前3个工作日..."

八、检索优化

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请基于以上参考资料回答：",
      // 注入的最大 Token 数
      "maxTokens": 4000
    }
  }
}

九、实际应用场景

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.1 文档质量影响检索质量

文档结构清晰（使用标题、列表等）
避免大量重复内容
定期清理过时文档
使用 Markdown 格式可获得最佳分块效果

10.2 定期维护

# 每周重建一次索引（cron）
0 3 * * 0 openclaw knowledge index --rebuild >> /var/log/openclaw-index.log 2>&1

# 检查索引健康状态
openclaw knowledge status

10.3 性能优化

优化点	方法
索引速度慢	增加 batchSize，使用更快的 Embedding 模型
检索不准确	调整 chunkSize 和 overlap，开启混合搜索
结果不相关	提高 minScore 阈值，减少 topK
内存占用大	使用外部向量存储（ChromaDB/Qdrant）

通过搭建知识库和 RAG 系统，你的 OpenClaw 将从一个通用 AI 助手升级为专属的知识问答专家，能够准确回答基于你自有文档的各种问题。