Claude Code

关注公众号 jb51net

关闭
AI > Claude Code >

Claude Code接入Ollama本地模型的完整指南

磊子1

引言

过去一年，Claude Code 凭借其强大的代码理解与生成能力，成为众多开发者日常编码的得力助手。但有一个现实问题始终绕不开：每一次对话都依赖 Anthropic 的云端 API。这不仅意味着稳定的网络连接、持续的 API 费用，还意味着将代码片段和业务逻辑上传到第三方服务器——对于涉及商业机密或合规要求严格的项目，这往往是不可接受的。

Ollama 作为最流行的本地大模型运行工具，让开发者可以在自己的机器上运行 Llama、Qwen、DeepSeek 等开源模型。当我们将 Claude Code 与 Ollama 结合时，一个诱人的可能性浮出水面：能否让 Claude Code 调用本地模型完成编码任务？

本文将深入探讨这一技术方案，从架构原理到实操配置，帮助你搭建一套完全离线的 AI 辅助编程环境。

读者收获：

一、Claude Code 的 Provider 架构：它不只是 Claude

很多人以为 Claude Code 只能调用 Anthropic 的 Claude 系列模型，但实际上，Claude Code 采用了灵活的 Provider 架构。

1.1 Provider 是什么？

Claude Code 底层的模型调用抽象了一层 Provider 接口，它定义了「如何与模型对话」的协议。默认情况下使用的是 anthropic Provider，指向 Anthropic 云端 API。但通过配置，我们可以接入其他兼容 OpenAI API 格式的服务。

1.2 为什么能接 Ollama？

Ollama 从 0.1.0 版本开始就提供了 OpenAI 兼容接口（/v1/chat/completions），这意味着任何支持 OpenAI API 的工具都可以无缝切换到 Ollama。Claude Code 恰好支持通过环境变量覆盖 API Base URL。

关键配置接口：

# Claude Code 通过以下环境变量对接自定义 Provider
ANTHROPIC_BASE_URL=http://localhost:11434/v1   # 指向 Ollama
ANTHROPIC_API_KEY=ollama                        # Ollama 不验证 key，但不能为空

1.3 请求流转图

下面是架构示意：

┌──────────────────┐       ┌──────────────────┐       ┌─────────────────┐
│   Claude Code    │ ────▶ │  Provider Layer  │ ────▶ │  Ollama Server  │
│   Your Terminal  │       │  (抽象模型接口)   │       │  localhost:11434 │
└──────────────────┘       └──────────────────┘       └────────┬────────┘
                                                               │
                                                     ┌─────────▼────────┐
                                                     │  Local LLM       │
                                                     │  (Qwen2.5 /      │
                                                     │   DeepSeek /     │
                                                     │   Llama 3.x)     │
                                                     └──────────────────┘

二、Ollama 环境搭建

2.1 安装与启动

macOS / Linux：

curl -fsSL https://ollama.com/install.sh | sh
ollama serve          # 启动服务（默认 11434 端口）

Windows：

从 ollama.com/download 下载安装包，安装后 Ollama 会自动作为后台服务运行。

验证服务：

curl http://localhost:11434/api/tags
# 应返回 JSON 格式的模型列表

2.2 模型选择：哪个适合代码场景？

以下模型在代码生成与理解上表现较好：

模型参数规模显存需求代码能力中文支持
Qwen2.5-Coder7B / 14B / 32B6GB / 16GB / 32GB⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
DeepSeek-Coder-V216B18GB⭐⭐⭐⭐⭐⭐⭐⭐
CodeLlama7B / 13B / 34B6GB / 12GB / 32GB⭐⭐⭐⭐⭐⭐
Llama 3.18B / 70B8GB / 40GB⭐⭐⭐⭐⭐

推荐首推 Qwen2.5-Coder:14B——它在代码理解和中文语义之间取得了最好的平衡，且在 16GB 显存的消费级 GPU 上即可流畅运行。

# 拉取推荐模型
ollama pull qwen2.5-coder:14b

# 测试推理
ollama run qwen2.5-coder:14b "用 Python 实现一个 LRU Cache，并分析时间复杂度"

也可以使用轻量化版本（适合 CPU only 或 8GB 显存）：

ollama pull qwen2.5-coder:7b

2.3 确认 OpenAI 兼容接口可用

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-coder:14b",
    "messages": [{"role": "user", "content": "1+1="}],
    "stream": false
  }'

# 应返回标准 OpenAI 格式响应

三、配置 Claude Code 接入 Ollama

3.1 基础配置

启动 Claude Code 时传入环境变量：

# 方式一：单次启动
ANTHROPIC_BASE_URL=http://localhost:11434/v1 \
ANTHROPIC_API_KEY=ollama \
claude

# 方式二：写入 shell 配置文件（推荐）
echo 'export ANTHROPIC_BASE_URL=http://localhost:11434/v1' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY=ollama' >> ~/.zshrc
source ~/.zshrc
claude

3.2 指定本地模型

默认情况下，Claude Code 会尝试调用 claude-sonnet-4-20250514 这个模型名。对接 Ollama 时，我们需要将模型名映射到本地已拉取的模型。

Claude Code 通过 ANTHROPIC_MODEL 环境变量指定模型：

ANTHROPIC_BASE_URL=http://localhost:11434/v1 \
ANTHROPIC_API_KEY=ollama \
ANTHROPIC_MODEL=qwen2.5-coder:14b \
claude

3.3 验证是否成功

启动后输入一个简单测试：

> 用 JavaScript 写一个防抖函数，并说明其工作原理

如果模型正常响应，你就成功搭建了一套完全离线的 AI 编程助手。

3.4 踩坑实录

坑 1：流式输出兼容性 Ollama 的流式输出格式与 OpenAI 标准有细微差异。如果遇到输出卡顿，尝试关闭流式模式：

# Claude Code 暂未暴露 stream 配置，但 Ollama 0.3.0+ 已修复此问题
# 升级到最新版即可
ollama --version   # 确认 ≥ 0.3.0

坑 2：上下文窗口不足 本地模型受限于显存，上下文窗口通常较小（4K-32K tokens）。而 Claude Code 默认会发送大量上下文（包括项目文件）。可以通过限制 --max-tokens 或减少发送给模型的文件数量来规避：

# 在 Claude Code 中压缩历史对话
> /compact

坑 3：模型名不匹配报错 Claude Code 内部写死了默认模型名，如果 Ollama 没有对应模型会返回 404。确保环境变量 ANTHROPIC_MODEL 与 ollama list 中的模型名完全一致。

四、进阶配置与性能优化

4.1 量化模型：用更少显存跑更大模型

Ollama 支持多种量化级别，用更少的显存换取略微下降的推理质量：

# Q4_K_M 量化（推荐，质量损失 < 5%）
ollama pull qwen2.5-coder:14b-q4_K_M

# Q2_K 量化（极致压缩，适合 8GB 以下显存）
ollama pull qwen2.5-coder:14b-q2_K

量化级别与显存对照：

量化14B 模型大小最低显存质量保留
F16 (原始)~28GB32GB100%
Q8_0~15GB18GB~99%
Q4_K_M~8.5GB10GB~95%
Q3_K_M~6.5GB8GB~88%
Q2_K~5GB6GB~75%

4.2 多模型路由策略

一个进阶技巧：同时启动多个模型，根据不同任务类型路由到不同模型。不过 Claude Code 目前不支持动态切换模型，但可以启动两个 Claude Code 实例，分别对接不同的 Ollama 模型：

# 终端 1：轻量模型（快速问答）
ANTHROPIC_MODEL=qwen2.5-coder:7b claude

# 终端 2：重量模型（深度分析）
ANTHROPIC_MODEL=qwen2.5-coder:14b claude

4.3 并发与性能调优

Ollama 在 GPU 加速下性能最好。确认是否启用 GPU：

# 查看启动日志中是否包含 "LLAMA_COMPUTE_DEVICE=cuda" 或 "Metal"
ollama serve --verbose 2>&1 | grep -i compute

如果 CPU 推理太慢，可以尝试：

  1. 减少送入模型的上下文：用 /compact 压缩对话历史
  2. 使用更小的模型：7B 比 14B 快 2-3 倍
  3. 调整 Ollama 并发参数：
OLLAMA_NUM_PARALLEL=1      # 并行数（显存够大可调大）
OLLAMA_MAX_LOADED_MODELS=1 # 最多同时加载模型数
OLLAMA_KEEP_ALIVE=5m       # 模型卸载等待时间

五、落地场景分析

5.1 最佳适用场景

场景推荐原因
涉密项目代码审查✅ 强烈推荐数据不出本机，满足合规
离线环境开发✅ 唯一选择无需互联网
简单的代码补全/重构✅ 推荐7B 模型即可胜任
复杂架构设计⚠️ 谨慎本地模型深度有限
大型代码库理解⚠️ 需调优上下文窗口限制
长对话持续开发❌ 不推荐本地模型注意力容易漂移

5.2 与云端 Claude 的体验差异

维度云端 Claude本地 Ollama + 模型
响应速度300-800ms 首 token2-10s（取决于显存）
代码质量⭐⭐⭐⭐⭐⭐⭐⭐⭐（14B）/ ⭐⭐⭐（7B）
上下文长度200K tokens8K-32K
隐私安全数据上传完全本地
成本按量付费仅电费
中文理解⭐⭐⭐⭐⭐⭐⭐⭐⭐（Qwen）

5.3 混合架构：鱼与熊掌兼得

一个务实的方案是混合使用：

启动两个 Claude Code 实例各自接入不同的 Provider，按需选择。

六、总结

Claude Code + Ollama 的本地化方案为开发者提供了一个隐私安全、零成本、离线可用的 AI 编程替代方案。虽然本地模型在推理质量和响应速度上还无法完全比肩云端 Claude，但对于以下群体极具价值：

随着 Qwen2.5-Coder、DeepSeek 等开源模型的持续进化，本地模型与云端模型的差距正在缩小。这套方案不是替代，而是补充——它让 AI 辅助编程的覆盖场景从「有网」扩展到了「随时随地」。

本文所有配置已在 macOS 14 + Ollama 0.5.x + Qwen2.5-Coder:14b-Q4_K_M 环境下验证通过。

以上就是Claude Code接入Ollama本地模型的完整指南的详细内容，更多关于Claude Code接入Ollama的资料请关注脚本之家其它相关文章！