Claude Context 的核心配置通过环境变量完成。其全局配置文件 ~/.context/.env 为跨客户端（如 Claude Code、Cursor）共享设置提供了便利，且遵循“进程环境变量 > 全局文件 > 默认值”的优先级机制。本文将依据源码详细解析从嵌入提供商 API 密钥、向量数据库连接到高级搜索模式、批量处理等关键配置项，助你快速搭建并优化语义代码搜索环境。

Claude Context 环境变量配置详解：从 API 密钥到向量数据库

要将语义代码搜索能力集成到 AI 编程助手中，正确配置 Claude Context 的环境变量是关键第一步。这些变量控制了嵌入模型的选择、向量数据库的连接以及搜索行为的高级调优。

一、配置文件与优先级机制

Claude Context 支持一个全局配置文件，路径为 ~/.context/.env。它的主要优势在于“一次配置，多处使用”，无需在每个 MCP 客户端的配置中重复填写相同的环境变量。

配置值的读取遵循严格的优先级顺序。在 env-manager.ts 文件中，EnvManager 类的 get() 方法清晰定义了这一逻辑：

// Priority: process.env > .env file > undefined
get(name: string): string | undefined {
    // First try to get from process environment variables
    if (process.env[name]) {
        return process.env[name];
    }

    // If not found in process env, try to read from .env file
    try {
        if (fs.existsSync(this.envFilePath)) {
            const content = fs.readFileSync(this.envFilePath, 'utf-8');
            const lines = content.split('\n');
            for (const line of lines) {
                const trimmedLine = line.trim();
                if (trimmedLine.startsWith(`${name}=`)) {
                    return trimmedLine.substring(name.length + 1);
                }
            }
        }
    } catch (error) {
        // Ignore file read errors
    }
    return undefined;
}

优先级由高到低如下：

进程环境变量：直接在 shell 或 MCP 客户端（如 claude mcp add -e KEY=VALUE）中设置的变量，优先级最高。
全局配置文件（~/.context/.env）：如果进程变量未设置，则读取此文件中的对应值。
默认值：如果以上两者都未找到，则使用代码中预设的默认值（如果存在）。

理解这个顺序对于调试配置冲突至关重要。当某个配置项的行为与预期不符时，应首先检查是否有更高优先级的设置覆盖了你的意图。

二、嵌入提供商环境变量对照

嵌入模型是将代码文本转换为向量的核心。Claude Context 支持 OpenAI、VoyageAI、Gemini 和 Ollama 四大提供商。config.ts 中的 createMcpConfig() 函数展示了如何读取这些变量并构建最终配置。

核心变量 EMBEDDING_PROVIDER 决定了使用哪个提供商。以下是各提供商所需的环境变量对照表：

提供商	必需的 API 密钥变量	可选配置变量	通用模型变量 `EMBEDDING_MODEL`
OpenAI	`OPENAI_API_KEY`	`OPENAI_BASE_URL` (自定义端点)	有效，例如 `text-embedding-3-large`
VoyageAI	`VOYAGEAI_API_KEY`	-	有效，例如 `voyage-code-3`
Gemini	`GEMINI_API_KEY`	`GEMINI_BASE_URL` (自定义端点)	有效，例如 `gemini-embedding-001`
Ollama	无需 API 密钥	`OLLAMA_HOST` (默认 `http://127.0.0.1:11434`)	有效，但 `OLLAMA_MODEL` 变量优先级更高

关键细节：

通用模型变量：EMBEDDING_MODEL 对所有提供商（除 Ollama 的特殊逻辑外）均生效，是设置具体模型名称的推荐方式。
Ollama 的特殊逻辑：对于 Ollama，系统会优先读取 OLLAMA_MODEL，其次才是 EMBEDDING_MODEL。这确保了在 Ollama 专用配置和通用配置共存时的向后兼容性。
默认模型：如果未设置任何模型变量，每个提供商都有默认值。例如 OpenAI 默认为 text-embedding-3-small。

三、向量数据库配置：连接 Zilliz Cloud

Claude Context 使用 Milvus 作为向量数据库来存储和检索代码向量。对于生产环境，推荐使用 Zilliz Cloud 托管服务。

关键环境变量如下：

MILVUS_TOKEN：这是强烈推荐的配置。它既是认证令牌，也用于自动解析 Milvus 服务地址。你只需从 Zilliz Cloud 控制台获取 Personal API Key 并设置此变量即可。
MILVUS_ADDRESS：此变量可选。当设置了 MILVUS_TOKEN 时，地址通常可以自动解析。如果你需要连接自部署的 Milvus 服务，或需要显式指定地址端点（如 https://your-cluster.vectordb.zillizcloud.com:19530），才需要手动设置此项。

简化配置示例（使用 Zilliz Cloud）： 通常，你只需要提供 MILVUS_TOKEN，连接便能自动建立。

四、高级配置项

这些配置项用于优化搜索效果、索引性能以及自定义文件处理规则。

变量名	说明	默认值
`HYBRID_MODE`	启用混合搜索（BM25 关键词搜索 + 向量语义搜索）。设置为 `false` 则只使用向量搜索。	`true`
`EMBEDDING_BATCH_SIZE`	嵌入处理的批量大小。增大此值可以减少索引总时间，但会占用更多内存。	`100`
`CUSTOM_EXTENSIONS`	附加需要索引的文件扩展名，用逗号分隔。例如，要包含 Vue、Svelte 和 Astro 文件：`.vue,.svelte,.astro`。	无
`CUSTOM_IGNORE_PATTERNS`	附加需要忽略的文件或目录模式，用逗号分隔。遵循类似 `.gitignore` 的 glob 语法。例如：`temp/*,.backup,private/**`。	无
`CODE_CHUNKS_COLLECTION_NAME_OVERRIDE`	为 Milvus 中的集合名称提供一个可读的自定义前缀。最终集合名会变为 `code_chunks_<自定义前缀>_<路径哈希>` 或 `hybrid_code_chunks_<自定义前缀>_<路径哈希>`。路径哈希后缀得以保留，确保同一前缀下不同代码库的集合依然唯一。	无

配置生效流程：当你设置这些变量后，createMcpConfig() 函数会将它们读取并注入到 MCP 服务器的运行时配置中，从而影响代码分割策略、搜索算法和索引集合的命名。

五、配置实践：从创建到验证

步骤 1：创建全局配置文件 在你的用户主目录下创建 .context 目录和 .env 文件。

mkdir -p ~/.context
cat > ~/.context/.env << 'EOF'
# 嵌入提供商配置（以 OpenAI 为例）
EMBEDDING_PROVIDER=OpenAI
OPENAI_API_KEY=sk-your-openai-api-key
EMBEDDING_MODEL=text-embedding-3-small

# 向量数据库配置
MILVUS_TOKEN=your-zilliz-cloud-api-key

# 高级配置（可选）
HYBRID_MODE=true
EMBEDDING_BATCH_SIZE=150
CUSTOM_EXTENSIONS=.vue,.svelte
EOF

步骤 2：验证优先级

在 .env 文件中设置 EMBEDDING_MODEL=text-embedding-3-small。
在启动 MCP 服务器的 shell 命令中，临时设置一个同名变量：EMBEDDING_MODEL=text-embedding-3-large npx @zilliz/claude-context-mcp@latest。
观察服务器启动日志中 [DEBUG] 🎯 OpenAI model selection 输出的模型名。应该是 text-embedding-3-large，证明进程变量优先级更高。

步骤 3：配置嵌入提供商 根据所选提供商，确保设置正确的 API 密钥。以 VoyageAI 为例：

# 在 ~/.context/.env 或进程变量中
EMBEDDING_PROVIDER=VoyageAI
VOYAGEAI_API_KEY=pa-your-voyageai-key
EMBEDDING_MODEL=voyage-code-3

步骤 4：连接 Milvus 最简配置只需 MILVUS_TOKEN。如果使用自部署 Milvus，则需要同时设置地址：

# 使用 Zilliz Cloud（推荐）
MILVUS_TOKEN=your-token

# 或连接自部署实例
MILVUS_ADDRESS=localhost:19530
MILVUS_TOKEN= # 如果需要认证

步骤 5：应用高级配置与验证 设置高级变量后，可通过启动日志验证。例如，设置了 CODE_CHUNKS_COLLECTION_NAME_OVERRIDE=my_project 后，在 [MCP] Configuration Summary 中会看到 Collection Name Override: ✅ Configured。

首次运行索引任务（例如通过 MCP 工具 index_codebase）后，你可以在 Zilliz Cloud 控制台或 Milvus 客户端中看到新创建的、带有你自定义前缀的集合。

FAQ

Q: 设置了 MILVUS_TOKEN 后，是否还需要配置 MILVUS_ADDRESS？ A: 通常不需要。当使用 Zilliz Cloud 的 Personal API Key 时，MILVUS_TOKEN 可用于自动发现和连接对应的服务端点。只有当你需要连接非 Zilliz Cloud 的自部署 Milvus 实例时，才必须手动指定 MILVUS_ADDRESS。

Q: 为什么我为 Ollama 设置了 EMBEDDING_MODEL，但日志显示使用了另一个模型？ A: 这是 Ollama 的特殊优先级设计。系统会优先查找并使用 OLLAMA_MODEL 变量。如果该变量未设置，才会回退到 EMBEDDING_MODEL。请检查 OLLAMA_MODEL 是否被意外设置。更多关于不同提供商的配置差异，可以参考嵌入提供商对比。

Q: CUSTOM_IGNORE_PATTERNS 和项目里的 .gitignore 文件是什么关系？ A: CUSTOM_IGNORE_PATTERNS 是用于补充和覆盖 .gitignore 规则的机制。Claude Context 会默认尊重 .gitignore 的规则，忽略其中列出的文件和目录。CUSTOM_IGNORE_PATTERNS 允许你在不修改 .gitignore 的前提下，额外忽略一些特定于索引任务的文件（如测试临时文件、私有配置等）。详细的忽略规则链可以参考忽略规则详解。

Claude Context 环境变量配置详解：从 API 密钥到向量数据库 #

一、配置文件与优先级机制 #

二、嵌入提供商环境变量对照 #

三、向量数据库配置：连接 Zilliz Cloud #

四、高级配置项 #

五、配置实践：从创建到验证 #