Claude Code本地模型接入指南：Ollama与DeepSeek API实战配置

1. 项目概述：为什么要在Claude Code里折腾本地模型？

如果你和我一样，是个喜欢在本地“捣鼓”各种AI模型的开发者，最近肯定没少听说Claude Code。它作为一款新兴的AI编程助手，以其强大的代码理解和生成能力吸引了不少眼球。但官方默认接入的是云端模型，对于有数据隐私顾虑、追求极致响应速度，或者单纯想“白嫖”本地算力的我们来说，总感觉少了点什么。

这个项目的核心，就是打破这个限制。我们不再满足于只能调用官方的Claude模型，而是要把Claude Code变成一个“万能前端”，让它能无缝对接我们本地运行的Ollama、DeepSeek，甚至是任何兼容OpenAI API格式的模型。想象一下，在VSCode里用着Claude Code流畅的交互界面，背后调用的却是你本地显卡上跑的、完全免费的Qwen或Llama模型，那种“鱼与熊掌兼得”的感觉，才是效率工具的终极形态。

我花了几天时间，把市面上主流的几种配置方法都摸了一遍，从最直接的Ollama集成，到通过第三方工具桥接DeepSeek API，再到处理各种稀奇古怪的报错。这篇文章，就是我这趟“折腾之旅”的完整记录和避坑指南。无论你是想用闲置的显卡跑模型，还是想低成本接入强大的DeepSeek，这里都有现成的方案。

2. 核心思路与方案选型：三条主流路径的深度剖析

要把Claude Code这个“前端”和我们本地的“后端”模型连接起来，关键在于找到一个双方都能理解的“通信协议”。目前，最通用、支持最广的协议就是OpenAI API兼容接口。只要我们的本地模型服务能提供一个模仿OpenAI API格式的接口，Claude Code就能像调用ChatGPT一样调用它。

基于这个核心原理，我梳理出了三条主流且可行的技术路径，每一条都有其适用的场景和需要面对的“坑”。

2.1 方案一：Ollama +ollama-ai-provider—— 最直接的本地方案

这是目前社区里讨论最多、看似最“正统”的方案。Ollama本身就是一个优秀的本地大模型管理工具，它原生提供了一个OpenAI兼容的API接口（默认在http://localhost:11434/v1）。理论上，只要在Claude Code里把这个地址填进去，就能用了。

但实际操作中，Claude Code对API的响应格式有更严格的要求，直接连接Ollama的原生接口可能会遇到provider returned error之类的报错。因此，社区诞生了一个专门的中介项目：ollama-ai-provider。它的作用就像一个“翻译官”或“适配器”，坐在Claude Code和Ollama之间，将Ollama的API响应格式，完美转换成Claude Code期望的格式。

为什么选择这个方案？

• 纯本地，零依赖：所有计算和数据都在你的机器上完成，隐私性最高，断网也能用。
• 模型管理方便：Ollama的一键拉取、运行、管理模型非常傻瓜式。
• 社区活跃：遇到问题容易找到解决方案和讨论。

需要面对什么？

• 硬件门槛：需要一块性能足够的显卡（N卡为佳）或强大的CPU。
• 模型性能：本地模型的能力与百亿、千亿参数的云端模型仍有差距，特别是在复杂逻辑和长上下文方面。
• 配置稍复杂：需要同时运行Ollama和这个Provider服务。

2.2 方案二：LM Studio / Jan.ai —— 开箱即用的图形化方案

如果你觉得命令行让人头疼，那么LM Studio或Jan.ai这类图形化工具是你的首选。它们本质上和Ollama是同类工具，但提供了漂亮的UI界面来下载、加载和运行模型。

更重要的是，它们通常都内置了功能完善的OpenAI API兼容服务器。你只需要在软件里点击“启动本地服务器”，它就会在本地（通常是http://localhost:1234/v1）开启一个服务。这个服务的兼容性通常做得比Ollama原生API更好，与Claude Code的对接成功率非常高。

为什么选择这个方案？

• 极致简单：无需任何命令行操作，全程图形化点击。
• 兼容性更好：其API服务器为对接ChatGPT类应用做了优化，报错少。
• 适合新手：对不熟悉终端命令的开发者非常友好。

需要面对什么？

• 资源占用可能略高：由于带了UI，整体内存占用会比纯后台服务的Ollama高一点。
• 灵活性稍弱：高级配置选项可能没有Ollama + 命令行来得直接。

2.3 方案三：DeepSeek API + 第三方代理工具 —— 云端高性能平替方案

也许你的本地显卡不够强，但又想体验接近GPT-4级别的代码能力。这时，性价比极高的DeepSeek API就成了绝佳选择。但Claude Code并不能直接填写DeepSeek的API地址，因为两者的API路径和参数细节仍有差异。

这就需要用到“代理”或“反向代理”工具。我们可以在本地（或一台服务器上）运行一个轻量级的代理程序。这个程序做两件事：

1. 接收来自Claude Code的请求（Claude Code以为它在请求OpenAI）。
2. 将请求的格式稍作修改，转发给真正的DeepSeek API。
3. 将DeepSeek的响应再转换回OpenAI格式，返回给Claude Code。

你可以自己用Node.js、Python（FastAPI）写一个，也可以使用开源项目如localai或llm-gateway来配置。对于DeepSeek，由于其API格式与OpenAI高度相似，通常只需要修改API基地址和认证头即可。

为什么选择这个方案？

• 性能强大：用极低的成本获得顶级代码模型的体验。
• 无需强大硬件：依赖的是云端算力，对本地电脑几乎无要求。
• 配置灵活：此方案可推广到任何提供类似API的模型服务。

需要面对什么？

• 需要网络：必须保持互联网连接。
• 涉及费用：虽然DeepSeek便宜，但仍有token消耗成本。
• 数据隐私：代码片段会发送到第三方服务器。
• 额外配置：需要搭建和维护一个代理服务。

我的选择建议：新手或追求最简单体验，选方案二（LM Studio）。硬核玩家、注重隐私和离线，选方案一（Ollama + Provider）。追求最强编码能力且预算有限，选方案三（DeepSeek API代理）。下面，我将以最典型的方案一和方案三为例，展开详细的实操过程。

3. 实操详解：Ollama本地模型的完整配置流程

这条路我走得最多，坑也踩得最全。我们目标是搭建一个稳定的、Claude Code能直接调用的本地模型服务。

3.1 第一步：基础环境搭建与Ollama部署

首先，你需要安装Ollama。访问其官网下载安装包是最直接的方式。但对于国内用户，最大的拦路虎就是下载速度。

Ollama加速下载技巧：Ollama在拉取模型时，默认从Docker Hub等国外源下载，速度极慢。这里分享一个非常有效的“换源”方法，无需复杂配置：

1. 打开终端（Windows PowerShell, Mac/Linux Terminal）。
2. 在拉取模型前，设置环境变量（仅当前终端会话有效）：

   # 对于Mac/Linux export OLLAMA_MODELS=registry.cn-hangzhou.aliyuncs.com/ollama-china # 对于Windows PowerShell $env:OLLAMA_MODELS="registry.cn-hangzhou.aliyuncs.com/ollama-china"

3. 然后正常使用ollama pull命令，速度会有质的飞跃。例如，拉取一个常用的编码模型：

   ollama pull qwen2.5:7b-coder

   这个镜像源由国内社区维护，包含了大多数热门模型。如果遇到某个特定模型没有，可以尝试在社区寻找其他镜像源。

模型选择心得：对于代码辅助，经过我的实测，以下几款模型在7B参数级别表现较为突出，对硬件要求也相对友好（至少需要8GB以上显存）：

• qwen2.5:7b-coder：通义千问的代码专用模型，对中文代码注释理解好，通用代码生成能力强。
• codellama:7b-code：Meta出品，专为代码微调，在Python等语言上表现扎实。
• deepseek-coder:6.7b：DeepSeek的早期代码模型，逻辑推理能力不错。

如果你的显卡只有6GB显存（比如GTX 1060），可以尝试qwen2.5:1.5b-coder或phi3:mini这类更小的模型，它们能跑起来，但能力会打折扣。如果只有CPU，建议内存至少16GB，并选择qwen2.5:1.5b-coder这类小模型，响应速度会在可接受范围内。

3.2 第二步：部署ollama-ai-provider适配器

这是让Claude Code和Ollama“握手成功”的关键。ollama-ai-provider是一个简单的Node.js服务。

1. 确保你有Node.js环境（版本建议16+）。没有的话去Node.js官网下载安装。
2. 克隆或下载该项目。打开终端，找一个你喜欢的目录：

   git clone https://github.com/ggozad/ollama-ai-provider.git cd ollama-ai-provider

   （如果网络问题克隆失败，可以直接在GitHub项目页面下载ZIP包并解压）。
3. 安装依赖并启动服务：

   npm install node server.js

   如果一切顺利，你会看到服务运行在http://localhost:11435（注意端口是11435，不是Ollama的11434）。这个服务就是我们给Claude Code准备的“网关”。

重要配置解析：server.js里有一行关键配置：

const OLLAMA_API_HOST = process.env.OLLAMA_API_HOST || 'http://localhost:11434';

它默认连接本机11434端口的Ollama。如果你的Ollama服务在别的机器上，可以通过设置环境变量OLLAMA_API_HOST来改变。例如，在启动命令前加上：

OLLAMA_API_HOST=http://192.168.1.100:11434 node server.js

3.3 第三步：在Claude Code中配置本地模型

现在，我们打开VSCode，确保已安装Claude Code扩展。

1. 点击VSCode侧边栏的Claude Code图标，打开其主界面。
2. 找到设置（通常是齿轮图标或“Settings”），进入配置页面。
3. 寻找“AI Provider”或“Model Configuration”相关的选项。不同版本位置可能略有不同，核心是找到让你填写API地址的地方。
4. 将API Base URL设置为http://localhost:11435/v1。这就是我们刚刚启动的ollama-ai-provider的地址。
5. API Key可以随意填写一个非空字符串，比如ollama-local。因为本地服务通常不验证密钥，但Claude Code的输入框可能要求必填。
6. Model Name这里需要特别注意！这里填写的不是你在Ollama里看到的qwen2.5:7b-coder，而应该是gpt-3.5-turbo。这是因为ollama-ai-provider为了最大兼容性，将自己“伪装”成了OpenAI的GPT-3.5 Turbo接口。你实际使用的模型，取决于你在启动Ollama时加载的那个。你可以在启动ollama-ai-provider前，在另一个终端运行ollama run qwen2.5:7b-coder来加载指定模型。
7. 保存配置。

现在，尝试在Claude Code里问一个问题。如果终端里ollama-ai-provider和ollama run的窗口都有新的日志输出，并且Claude Code收到了回复，那么恭喜你，配置成功了！

4. 实操详解：接入DeepSeek API的代理方案

如果你想获得更强的编码能力，DeepSeek API是性价比之王。下面我们搭建一个最简单的HTTP代理来桥接。

4.1 第一步：获取DeepSeek API密钥并了解计费

1. 访问DeepSeek官网，注册并登录账号。
2. 进入控制台，在“API Keys” section创建一个新的密钥，并妥善保存。它看起来像一长串乱码字符。
3. 非常重要：查看定价文档。DeepSeek采用按Token消耗计费，价格非常低廉，但使用前务必清楚计费方式，避免意外开销。通常会有免费额度供开始使用。

4.2 第二步：使用Node.js + Express创建简易代理服务器

我们将创建一个极简的Node.js服务，它接收OpenAI格式的请求，转发给DeepSeek，并返回结果。

1. 新建一个项目目录并初始化：

   mkdir deepseek-proxy && cd deepseek-proxy npm init -y npm install express axios

2. 创建主文件server.js：

   const express = require('express'); const axios = require('axios'); const app = express(); const port = 3000; // 代理服务运行的端口 // 你的DeepSeek API密钥，从环境变量读取更安全 const DEEPSEEK_API_KEY = process.env.DEEPSEEK_API_KEY || '你的_DeepSeek_API_密钥_放在这里'; const DEEPSEEK_API_BASE = 'https://api.deepseek.com/v1'; // DeepSeek API 地址 app.use(express.json()); // 拦截Claude Code发送到 /v1/chat/completions 的请求 app.post('/v1/chat/completions', async (req, res) => { console.log('Received request from Claude Code:', JSON.stringify(req.body, null, 2)); try { // 将请求转发给DeepSeek API const response = await axios.post( `${DEEPSEEK_API_BASE}/chat/completions`, req.body, // 直接转发请求体 { headers: { 'Authorization': `Bearer ${DEEPSEEK_API_KEY}`, 'Content-Type': 'application/json', }, } ); console.log('Response from DeepSeek received.'); // 将DeepSeek的响应直接返回给Claude Code res.json(response.data); } catch (error) { console.error('Proxy error:', error.response?.data || error.message); res.status(error.response?.status || 500).json({ error: { message: `Proxy to DeepSeek failed: ${error.message}`, type: 'proxy_error', } }); } }); // 一个简单的模型列表接口，Claude Code可能会调用 app.get('/v1/models', async (req, res) => { try { const response = await axios.get(`${DEEPSEEK_API_BASE}/models`, { headers: { 'Authorization': `Bearer ${DEEPSEEK_API_KEY}` }, }); res.json(response.data); } catch (error) { // 如果获取失败，返回一个模拟的列表，确保Claude Code能识别 res.json({ object: "list", data: [ { id: "deepseek-chat", object: "model", created: 1686935000 }, { id: "deepseek-coder", object: "model", created: 1686935000 }, ] }); } }); app.listen(port, () => { console.log(`DeepSeek proxy server running at http://localhost:${port}`); console.log(`请将Claude Code的API Base URL设置为: http://localhost:${port}/v1`); });

3. 启动代理服务器：

   # 在终端中设置环境变量（更安全的方式） export DEEPSEEK_API_KEY=你的_实际_API_密钥 node server.js

   你应该看到服务器成功启动的日志。

4.3 第三步：配置Claude Code使用代理

这一步和配置Ollama类似，但更简单。

1. 在Claude Code设置中，找到API配置部分。
2. 将API Base URL设置为http://localhost:3000/v1（与你代理服务器启动的端口一致）。
3. 将API Key设置为任意非空字符串即可，例如deepseek-proxy。因为我们的代理服务器代码里没有验证这个Key，真正的认证是在代理服务器转发时使用我们环境变量里的DEEPSEEK_API_KEY。
4. 在Model Name中，填写DeepSeek提供的模型名称，例如deepseek-chat或deepseek-coder。你可以在DeepSeek的官方文档中找到最新的可用模型列表。
5. 保存并测试。现在，你在Claude Code中的对话，就会通过本地代理，安全地转发到DeepSeek的官方API了。

安全性强化建议：上述示例为了清晰，将代理逻辑简化了。在生产环境或个人使用中，建议：

• 永远不要将真实的API密钥硬编码在代码中。务必使用环境变量（process.env）。
• 可以考虑在代理服务器中添加简单的IP白名单或HTTP Basic认证，防止局域网内其他设备误调用。
• 对于请求和响应体，可以添加日志（脱敏后）以便调试，但注意不要记录包含敏感代码的完整消息。

5. 避坑指南与常见问题排查

在实际操作中，你几乎一定会遇到一些问题。下面是我踩过坑后总结的“排错清单”。

5.1 连接失败与超时问题

• 症状：Claude Code提示“无法连接”、“网络错误”或“超时”。
• 排查步骤：
  1. 检查服务是否运行：在终端运行curl http://localhost:端口/v1/models（将端口换成11435或3000）。如果返回JSON数据或错误信息，说明服务是活的；如果连接被拒绝，说明服务没启动。
  2. 检查端口占用：确认你指定的端口没有被其他程序占用。可以用lsof -i :端口号（Mac/Linux）或netstat -ano | findstr :端口号（Windows）查看。
  3. 检查防火墙：确保你的系统防火墙或安全软件没有阻止本地回环地址（127.0.0.1）或特定端口的通信。可以临时关闭防火墙测试。
  4. 对于Ollama方案：确保Ollama服务本身在运行（ollama serve），并且ollama-ai-provider连接到了正确的Ollama地址。

5.2 模型加载与响应格式错误

• 症状：Claude Code显示“provider returned error: ...”，或者返回一堆乱码、空白。
• 排查步骤：
  1. 查看服务端日志：这是最重要的信息源！仔细看ollama-ai-provider或你的代理服务器的终端输出，错误信息通常非常明确。
  2. 确认模型名称映射：对于Ollama方案，在Claude Code里填的模型名必须是gpt-3.5-turbo，而在运行Ollama时加载你想要的模型（如ollama run qwen2.5:7b-coder）。两者是分离的。
  3. 检查Ollama模型是否已下载：运行ollama list确认模型存在。如果不存在，用ollama pull拉取。
  4. 显存/内存不足：这是本地模型最常见的错误。查看终端日志，是否有“CUDA out of memory”或“内存不足”的提示。尝试换用更小的模型，或者关闭其他占用显存的程序。
  5. 代理方案检查：检查你的代理服务器代码是否正确处理了请求和响应格式。用Postman或curl直接测试你的代理端点，对比与直接调用DeepSeek API的差异。

5.3 性能优化与使用技巧

• Ollama模型加载慢：首次使用某个模型时，Ollama需要加载到显存，会有点慢。后续对话如果间隔时间不长，模型会保持在内存中，响应会快很多。如果你希望模型常驻，可以写一个简单的守护脚本，定期发送一个保持活跃的请求。
• Claude Code上下文管理：本地模型通常上下文窗口（Context Window）比云端模型小。注意不要在Claude Code中开启过长的对话历史，否则可能因为超出上下文限制导致模型回复质量下降或报错。可以在Claude Code设置中调整“最大对话历史长度”。
• 多模型切换：如果你安装了多个本地模型，可以通过停止当前Ollama运行进程，重新ollama run <新模型名>来切换。对于ollama-ai-provider，它始终会调用Ollama服务当前加载的活跃模型。
• 代理服务器的稳定性：自己搭建的Node.js代理服务如果崩溃，Claude Code就会失联。可以考虑使用pm2这样的进程管理工具来守护你的代理服务，实现崩溃后自动重启。

  npm install -g pm2 pm2 start server.js --name deepseek-proxy pm2 save pm2 startup # 设置开机自启（可选）

配置成功只是第一步，真正享受本地模型或低成本高性能模型带来的便利，还需要在日常使用中不断磨合。从我的体验来看，对于日常的代码补全、解释、重构和调试建议，本地7B级别的模型已经能提供相当可靠的帮助，极大地减少了上下文切换的成本。而当你需要处理非常复杂、需要深度推理的算法问题时，通过代理调用DeepSeek这类云端模型，则能让你瞬间拥有一个强大的外脑。这种“混合模式”或许才是当下最务实、最高效的AI编程助手使用策略。