Claude Context 遇到问题时，排查顺序是：先查索引状态（是否 indexed）→ 再查 debug 日志（看具体报错）→ 修改配置后重连 MCP。最常见的问题是：索引进度跳到 10% 后不动（正常，阶段式进度）、0 files 0 chunks（本地快照过时，clear 重索引即可）、搜索无结果（路径不一致或忽略规则过严）。完全本地部署可以用 Ollama + 本地 Milvus，数据不出网。

Claude Context 常见问题与排查指南：索引失败、0 chunks、搜索无结果怎么办

Claude Context 的配置本身不复杂，但向量数据库和 Embedding 服务的加入让排查链路变长了。本文先解决最常见的问题，再给出系统性排查步骤。

最常见的 5 个问题

1. 进度跳到 10% 后不动

这不是 bug。 get_indexing_status 的百分比是阶段式的，不是线性的（详见 索引机制详解）。

• 0%：准备阶段
• ~5%：扫描文件列表
• 10% → 100%：真正的批量处理（切块 → 向量化 → 写入数据库）

大项目在 10% 停十几分钟是正常的。只要没报错，等就好。

2. 状态显示 0 files, 0 chunks

本地快照元数据过时了，不是数据库里真的没数据。

解决方法：

1. 对 AI 说：Clear the index
2. 再说：Index this codebase
3. 等状态变为 indexed，再查看

3. 搜索无结果

最可能的原因：

原因	检查方式
索引未完成	Check the indexing status，确认是 indexed
路径不一致	搜索时用的路径必须和索引时完全一致（绝对路径）
忽略规则过严	检查 .gitignore、CUSTOM_IGNORE_PATTERNS 是否误排了目标文件
扩展名未覆盖	确认目标文件类型在支持列表里（用 CUSTOM_EXTENSIONS 补充）

4. 索引失败（indexfailed）

最常见原因：Embedding API Key 无效或额度用完。

排查步骤：

1. 确认 API Key 有效（到 Provider 后台检查）
2. 确认账户有额度（OpenAI 需要付费账户）
3. 确认 Zilliz Cloud 集群状态正常
4. 看 debug 日志里的具体报错

5. 改了代码但搜索结果没更新

Claude Context 没有自动增量索引。修改代码后需要重新索引：

Clear the index
Index this codebase

---

系统性排查步骤

Step 1：检查索引状态

直接对 AI 说：

Check the indexing status

get_indexing_status 会返回状态、进度、错误信息。大部分问题在这一步就能定位。

Step 2：查看 Debug 日志

如果状态看不出问题：

Claude Code / Gemini CLI：

claude --debug
# 或
gemini --debug

Cursor：

1. 打开 Output 面板（⌘⇧U）
2. 下拉选择 "MCP Logs"

通用方法： 查看 Claude Context 的 MCP 服务日志，通常会输出具体的错误堆栈。

Step 3：修改配置后重连 MCP

如果发现问题和配置（API Key、环境变量）有关，修改后需要重连：

平台	重连方式
Claude Code	/mcp reconnect claude-context
Gemini CLI	/mcp refresh
Cursor / 其他 GUI	找到 MCP 服务的开关按钮重启

重连后重新测试索引和搜索。

Step 4：检查 GitHub Issues

如果前三步都没解决：

• GitHub Issues 搜索类似问题
• 看 Open 和 Closed 的 Issues，可能有 Workaround

---

完全本地部署方案

如果你的代码不能发到云端，可以用 Ollama + 本地 Milvus 实现完全本地化。

组件

组件	本地替代	说明
OpenAI Embedding	Ollama + nomic-embed-text	本地生成向量
Zilliz Cloud	本地 Milvus（Docker）	本地存储向量

配置步骤

1. 安装 Ollama 并拉取模型

ollama pull nomic-embed-text
ollama serve

2. 启动本地 Milvus

按 Milvus 官方安装指南 用 Docker Compose 启动。

3. 配置环境变量

EMBEDDING_PROVIDER=Ollama
EMBEDDING_MODEL=nomic-embed-text
OLLAMA_HOST=http://127.0.0.1:11434
MILVUS_ADDRESS=127.0.0.1:19530
MILVUS_TOKEN=your-milvus-token

MILVUS_TOKEN 如果本地 Milvus 没开认证可以留空。

---

FAQ

Q: 索引大项目很慢，怎么加速？ A: 调大 EMBEDDING_BATCH_SIZE（默认 100，可以试 512）。换更快的 Embedding Provider（VoyageAI 通常比 OpenAI 快）。确保网络通畅（云端 Provider 有延迟）。

Q: 同一个仓库在两个不同路径索引了，会冲突吗？ A: 不会冲突，但它们是两个独立索引。Claude Context 按绝对路径区分代码库，不同路径 = 不同索引。搜索时要确认路径和索引时一致。

Q: clear_index 后快照文件还在怎么办？ A: clear_index 应该同时清除向量数据库和本地快照。如果快照残留，手动删除 ~/.context/mcp-codebase-snapshot.json 中对应条目，然后重新索引。

Q: Claude Desktop 里怎么用 Claude Context？ A: 在 Claude Desktop 的 MCP 配置里加同一段 JSON 即可，配置格式和 Cursor/Windsurf 一样。Claude Desktop 本身支持 MCP 工具，索引和搜索都能正常使用。