Claude Code配置本地模型指南：从Ollama到DeepSeek的完整实践-Seo优化-塔城地区网站建设公司

1. 从“云端依赖”到“本地掌控”：为什么我们需要在 Claude Code 里配置本地模型？

如果你和我一样，是个重度依赖 Claude Code 来写代码、重构、调试的程序员，那你肯定经历过这种时刻：灵光一闪，想快速让 AI 帮你写个复杂的正则表达式，或者解释一段晦涩的遗留代码，结果 Claude Code 的响应突然变慢，或者干脆告诉你“服务暂时不可用”。那一刻的焦躁，就像网络游戏打到关键团战突然掉线一样。更别提，有时候你只是想处理一些公司内部的、带点敏感信息的代码片段，用云端服务心里总有点不踏实。

这就是为什么，把 Claude Code 从“云端服务消费者”变成“本地智能工作台”，成了一个越来越强烈的需求。简单说，我们想让 Claude Code 这个强大的代码编辑插件，不再只调用 Anthropic 官方的 Claude API，而是能连接我们自己在本地电脑上运行的 AI 模型，比如用 Ollama 部署的 Llama 3.2、CodeLlama，或者最近风头正劲的 DeepSeek Coder。这样一来，响应速度取决于你的电脑性能，数据隐私完全由自己掌控，而且还能根据你的编程语言偏好，专门调教一个“专属代码助手”。

听起来很美好，对吧？但实际操作起来，你会发现 Claude Code 的官方文档对此语焉不详，社区里的教程也零零散散。我花了差不多两个周末的时间，在各种报错、配置冲突和模型加载失败中反复横跳，才终于把这条路走通。今天，我就把我趟过的坑、验证过的步骤，以及那些官方不会告诉你的细节，从头到尾给你捋清楚。无论你是想用 Ollama 跑个轻量模型快速响应，还是想接入 DeepSeek 体验一下顶尖的代码生成能力，这篇指南都能让你少走至少 80% 的弯路。

2. 核心原理拆解：Claude Code 是如何与外部模型“对话”的？

在动手配置之前，我们得先搞明白 Claude Code 到底是怎么工作的。这能帮你理解后续每一个配置步骤的意义，而不是机械地复制粘贴命令，一出错就傻眼。

Claude Code 本质上是一个 VS Code 插件，它的核心功能是作为一个“中间人”（或者说客户端），接收你在编辑器里的指令（比如选中代码后右键点击“解释这段代码”），然后将这些指令打包成一个结构化的请求，发送给某个“AI服务端点”，最后把收到的响应解析并展示给你。默认情况下，这个“AI服务端点”就是 Anthropic 的官方 API 服务器。

我们要做的，就是“欺骗”或者“重定向” Claude Code，让它把请求发到我们本地自己搭建的服务端点上去。而本地服务端点，就是由 Ollama 这类工具提供的。Ollama 扮演了一个本地模型管理器和服务器的角色。你通过命令行下载、运行模型，Ollama 会在你本地启动一个服务（通常是http://localhost:11434），这个服务提供了类似 OpenAI API 格式的接口。Claude Code 只要能以正确的格式向这个地址发送请求，就能拿到本地模型的回复。

这里的关键在于“正确的格式”。Anthropic 的 API 和 OpenAI 的 API 在请求体结构上有所不同。幸运的是，Ollama 的 API 在设计上兼容了 OpenAI 的格式，这为我们提供了便利。但 Claude Code 原生是为 Anthropic API 设计的，所以我们需要一个“协议转换层”或者正确的配置，来让 Claude Code 适配本地 Ollama 的 OpenAI 兼容接口。这就是整个配置过程的核心挑战。

另一种情况是接入像 DeepSeek 这样的第三方云端模型（虽然标题也提到，但热词显示大家对本地部署 DeepSeek 也很感兴趣）。对于这类模型，它们通常也会提供 OpenAI 格式的兼容 API。此时，Claude Code 需要配置的目标地址就不是localhost，而是该模型服务商提供的 API 地址，同时还需要配置对应的 API Key。其底层逻辑与连接本地 Ollama 是一致的，都是让 Claude Code 向一个非官方的、兼容的 API 端点发送请求。

理解了这一点，你就会明白，后续所有步骤都围绕着三个目标展开：1. 在本地启动一个能正确响应请求的模型服务；2. 获取或生成一个能让 Claude Code 识别并使用的“服务端点”配置；3. 在 Claude Code 中填入这个配置，完成连接。

3. 基础环境搭建：Ollama 的安装与模型拉取避坑指南

万事开头难，第一步就是安装 Ollama。这个过程本身不复杂，但网络问题往往是第一个拦路虎。

3.1 在不同操作系统上安装 Ollama

Ollama 支持 macOS、Linux 和 Windows。访问其官网下载安装包是最直接的方式。对于 macOS 和 Windows 用户，下载一个.dmg或.exe文件，像安装普通软件一样完成即可。安装后，Ollama 通常会作为后台服务运行，你可以在终端或命令提示符里使用ollama命令。

对于 Linux 用户，官网也提供了一键安装脚本：

curl -fsSL https://ollama.com/install.sh | sh

运行后，脚本会自动完成下载、安装和系统服务配置。

第一个实操心得：安装完成后，务必打开终端，输入ollama --version验证是否安装成功。同时，可以运行ollama serve来显式启动服务（尽管安装后它可能已经作为服务运行了）。你会看到服务监听在127.0.0.1:11434。保持这个终端窗口打开，或者确认服务在后台正常运行，这是后续所有步骤的基础。

3.2 解决“Ollama 下载太慢”的老大难问题

这是几乎所有国内开发者都会遇到的痛点。直接运行ollama pull llama3.2或ollama pull codellama，下载速度可能只有几十 KB/s，甚至直接超时失败。热词里“ollama下载太慢了”、“国内镜像源下载ollama”反映了普遍的困扰。

解决方案是使用国内镜像。Ollama 本身不支持直接配置镜像源，但我们可以通过修改系统环境变量来实现。具体操作如下：

对于 macOS/Linux：打开你的 shell 配置文件（如~/.bashrc,~/.zshrc），添加以下行：

export OLLAMA_HOST=0.0.0.0 # 可选，使服务在所有网络接口上可访问，方便后续调试 export OLLAMA_MODELS=/your/custom/model/path # 可选，自定义模型存储路径 # 最关键的一行：设置镜像源 export OLLAMA_ORIGINS=https://ollama-mirror.ghproxy.com

然后执行source ~/.zshrc（或~/.bashrc）使配置生效。这个ghproxy.com镜像源对于拉取托管在 GitHub 上的模型文件有显著加速效果。

对于 Windows：在“系统属性”->“高级”->“环境变量”中，新建一个用户变量或系统变量，变量名为OLLAMA_ORIGINS，变量值为https://ollama-mirror.ghproxy.com。

第二个实操心得（重要）：设置镜像源后，首次拉取模型时，建议使用ollama pull <model-name>命令在终端直接操作，而不是通过后续 Claude Code 的配置来触发拉取。这样你能在终端清晰地看到下载进度和速度。如果镜像源生效，速度应该能达到你的带宽上限。如果依然很慢，可以搜索“ollama 国内镜像”寻找其他可用的镜像地址替换。常见的模型如llama3.2:3b（一个30亿参数的轻量版）、codellama:7b、deepseek-coder:6.7b都是不错的起步选择。先成功拉取一个模型，我们才能进行下一步。

4. 配置 Claude Code 连接本地 Ollama 模型

现在，我们有了运行在localhost:11434的 Ollama 服务，并且本地已经有一个可用的模型（例如codellama:7b）。接下来就是让 Claude Code 认识它。

4.1 获取 Claude Code 的“自定义模型”配置入口

Claude Code 默认的配置界面只允许你输入 Anthropic 的 API Key。要配置自定义模型，我们需要使用它的“开发人员设置”功能。具体开启方式因版本略有不同，但通常可以通过以下步骤找到：

在 VS Code 中，打开命令面板（Cmd+Shift+P或Ctrl+Shift+P）。
输入并选择 “Claude Code: Open Settings”。
在打开的设置界面中，仔细寻找 “Developer Settings” 或 “Advanced Settings” 相关的选项，可能会有一个复选框如 “Enable Custom Model Endpoint” 或 “Use Custom Configuration”。
更常见且可靠的方法是，直接编辑 VS Code 的settings.json文件。打开命令面板，输入 “Preferences: Open User Settings (JSON)”。

4.2 编写核心配置代码

在你的settings.json文件中，你需要添加一个针对 Claude Code 的专属配置。以下是一个连接本地 Ollama 的codellama:7b模型的完整配置示例：

{ "claude.code.configuration": { "endpoints": [ { "name": "Ollama - CodeLlama 7B", // 在 Claude Code 界面中显示的名称 "type": "openai", // 关键！指定为 OpenAI 兼容类型 "baseURL": "http://localhost:11434/v1", // Ollama 的 OpenAI 兼容 API 地址 "apiKey": "ollama", // Ollama 不需要真正的 key，但字段必填，可填任意非空字符串 "model": "codellama:7b", // 你本地通过 `ollama pull` 下载的模型名称 "defaults": { "maxTokens": 2048, "temperature": 0.2 // 代码生成建议较低的温度，保持确定性 } } ] } }

逐项解析与避坑点：

"type": "openai"：这是最关键的一行。它告诉 Claude Code 使用 OpenAI 的 API 通信格式向目标地址发送请求。Ollama 的/v1端点正是为兼容此格式而设计。
"baseURL": "http://localhost:11434/v1"：确保 Ollama 服务正在运行且端口是11434。/v1路径不能省略。
"apiKey": "ollama"：Ollama 本地服务通常不需要鉴权，但这个字段是 Claude Code 配置结构所必需的。填ollama或sk-no-key-required等任意字符串即可。
"model": "codellama:7b"：这里的模型名必须与你在 Ollama 中拉取和使用的名称完全一致。你可以通过ollama list命令查看本地已有的模型列表。
"defaults"：这里可以设置一些默认参数。对于代码任务，较低的temperature（如 0.1-0.3）能减少随机性，生成更稳定、可预测的代码。

4.3 验证连接与切换模型

保存settings.json文件后，回到 VS Code 编辑器。你应该能看到 Claude Code 插件的 UI 界面（通常侧边栏或状态栏会有图标）中，模型选择的地方除了原来的 “Claude 3.5 Sonnet” 等，多出了一个 “Ollama - CodeLlama 7B” 的选项。

验证连接：选择这个新模型，尝试执行一个简单的操作，比如选中一行代码，右键选择 “Explain This Code”。观察 Claude Code 的输出面板。如果配置正确，你会看到请求发送的提示，然后本地模型会开始思考（你的电脑风扇可能开始转动），最终给出解释。
常见错误排查：
- 错误：Failed to fetch或Connection refused：首先确认ollama serve是否在运行。在终端执行curl http://localhost:11434/api/tags，如果返回你本地模型的列表，说明 Ollama 服务正常。
- 错误：Model not found：检查配置中的model字段是否拼写正确。务必使用ollama list显示的确切名称。
- 请求超时：本地小模型（如 7B）响应应该很快。如果超时，可能是模型首次加载需要时间，或者你的配置中maxTokens设得过高，导致生成时间过长。可以尝试先设小一点。

第三个实操心得：成功连接后，强烈建议你进行一个对比测试。用同一个代码解释或生成任务，分别让官方的 Claude 模型和你的本地 CodeLlama 执行。你会直观地感受到响应速度的差异（本地更快），以及能力上的区别（大模型通常更精准，小模型可能更快但有时会胡言乱语）。这有助于你根据不同的任务场景（快速片段生成 vs. 复杂逻辑分析）来灵活切换模型。

5. 进阶：接入 DeepSeek 及其他第三方模型 API

除了本地模型，Claude Code 也可以配置使用像 DeepSeek 这样的第三方云端模型 API。这相当于用 Claude Code 作为统一客户端，来调用不同厂商的模型服务。这里以 DeepSeek 为例。

5.1 获取 DeepSeek API 密钥与端点

访问 DeepSeek 开放平台官网，注册并登录账号。
在控制台中，通常可以找到 “API Keys” 部分，创建一个新的 API 密钥并妥善保存。
在文档中找到 API 的调用端点（Base URL）。例如，DeepSeek 的 OpenAI 兼容端点可能是https://api.deepseek.com/v1。请务必以官方最新文档为准。

5.2 配置 Claude Code 使用 DeepSeek API

配置逻辑与 Ollama 类似，区别在于baseURL、apiKey和model字段需要替换为 DeepSeek 提供的值。在settings.json的claude.code.configuration.endpoints数组中，再添加一个对象：

{ "claude.code.configuration": { "endpoints": [ // ... 之前的 Ollama 配置 ... { "name": "DeepSeek Coder", "type": "openai", // 同样是 OpenAI 兼容类型 "baseURL": "https://api.deepseek.com/v1", // 替换为 DeepSeek 的真实端点 "apiKey": "your-deepseek-api-key-here", // 替换为你申请的 API Key "model": "deepseek-coder", // 替换为 DeepSeek 提供的具体模型名，如 deepseek-coder-33b-instruct "defaults": { "maxTokens": 4096, "temperature": 0.1 } } ] } }

重要安全提示：apiKey是高度敏感信息。切勿将包含真实 API Key 的settings.json文件上传到公开的 GitHub 仓库。可以考虑使用环境变量来管理，但 Claude Code 的配置原生支持从环境变量读取吗？这需要查证。一个更安全的做法是，将apiKey的值用一个变量占位，如"apiKey": "${env:DEEPSEEK_API_KEY}"，但这需要 Claude Code 支持这种语法。如果不支持，请务必确保你的settings.json文件在本地是安全的，或者使用 VS Code 的本地配置覆盖功能。

5.3 关于本地部署 DeepSeek 模型的说明

热词中出现了 “deepseek v4 flash 本地部署”、“deepseek本地部署”。目前，像 DeepSeek-V4-Flash 这样的顶级大模型，由于其庞大的参数量（数千亿），对消费级硬件（GPU 显存）要求极高，普通用户很难在本地顺畅运行。通常的“本地部署”指的是在拥有多张高端显卡的服务器上进行。对于个人开发者，通过 Ollama 部署的deepseek-coder:6.7b这类较小参数量的代码专用模型，是更现实的本地运行选择。其配置方法与第 4 节完全一致，只需将model字段改为deepseek-coder:6.7b并在 Ollama 中提前拉取即可。

6. 性能调优与日常使用技巧

配置成功只是开始，要让本地模型在 Claude Code 中好用，还需要一些调优。

6.1 模型选择与硬件平衡

不是模型越大越好。在有限的本地硬件上，需要在模型能力和响应速度间取得平衡。

轻量级任务（代码补全、简单解释）：考虑 3B-7B 参数模型，如llama3.2:3b,codellama:7b。它们加载快，响应迅速，对内存/显存要求低（通常 8GB RAM 以上即可尝试）。
中型任务（代码重构、小型函数生成）：可以考虑 13B-34B 参数模型，如codellama:13b。这需要更强的硬件（建议 16GB+ RAM，有独立显卡更好）。
大型任务（复杂算法设计、系统架构分析）：本地运行大模型（70B+）对绝大多数个人电脑不现实。此时，更合理的方案是使用第 5 节的方法，配置 Claude Code 去调用云端的强大模型 API（如 DeepSeek），为这些重任务付费，而日常轻量任务用本地小模型处理。在 Claude Code 中快速切换不同端点配置，就能实现这种混合模式。

6.2 优化提示词与参数

本地模型的理解和生成能力可能不如顶级云端模型。通过优化提示词，可以显著提升效果。

明确上下文：在请求中，尽量提供清晰的代码上下文。Claude Code 会自动附送选中的代码或当前文件内容，这很好。
指定角色和格式：在自定义指令（如果 Claude Code 支持）或你的提问中，可以加入“你是一个资深的 Python 后端工程师，请用简洁的语言解释...”这样的角色设定，以及“请以列表形式给出修改建议”这样的输出格式要求。
调整生成参数：在配置的defaults里或每次请求时（如果 UI 支持）：
- temperature：代码生成建议用 0.1-0.3，追求稳定性；创意性任务可以调高。
- maxTokens：根据任务需要设置，避免过长导致生成慢或无关内容多。对于代码补全，512-1024 可能就够了。
- top_p(如果支持)：与 temperature 配合，控制生成多样性。

6.3 管理多个模型配置

你可以在settings.json的endpoints数组里配置多个模型。Claude Code 的 UI 应该会提供一个下拉列表让你切换。为你常用的几个模型（如一个本地快速模型、一个云端强力模型）都配置好，并根据任务场景一键切换，能极大提升效率。

第四个实操心得：关于稳定性。本地模型服务（Ollama）在长时间运行或连续处理大量请求后，有时会出现内存累积或响应变慢的情况。我的经验是，如果发现模型开始胡言乱语或响应异常变慢，可以尝试在终端重启 Ollama 服务：先Ctrl+C停止当前服务，再重新运行ollama serve。对于生产级使用，可能需要编写监控脚本或使用进程管理工具来确保服务稳定。

7. 故障排除与常见问题清单

即使按照指南操作，你也可能会遇到一些问题。这里汇总一个常见问题清单，方便你快速排查。

问题现象	可能原因	排查步骤与解决方案
Claude Code 中看不到自定义模型选项	1.`settings.json`配置语法错误。 2. Claude Code 版本过旧，不支持自定义端点。	1. 检查`settings.json`的 JSON 格式是否正确，特别是括号和逗号。 2. 确保`claude.code.configuration.endpoints`路径正确。 3. 更新 Claude Code 插件到最新版本。
选择自定义模型后，操作无响应或报错`Failed to fetch`	1. Ollama 服务未运行。 2.`baseURL`地址或端口错误。 3. 防火墙/安全软件阻止了连接。	1. 在终端运行`ollama serve`并确保它持续运行。 2. 在浏览器或终端访问`http://localhost:11434/api/tags`，确认能返回 JSON 格式的模型列表。 3. 检查`baseURL`是否包含`/v1`。 4. 暂时关闭防火墙或安全软件试试。
错误信息包含`Model ‘xxx’ not found`	1. 配置中的`model`名称拼写错误。 2. 该模型未下载到本地。	1. 运行`ollama list`核对准确的模型名。 2. 如果模型不存在，运行`ollama pull <correct-model-name>`下载。
模型响应速度极慢，或生成内容质量很差	1. 本地硬件资源（CPU/内存/显存）不足。 2. 模型参数（如`maxTokens`）设置过高。 3. 模型本身能力有限。	1. 检查任务管理器/活动监视器，看是否有资源瓶颈。尝试关闭其他占用资源的程序。 2. 降低`maxTokens`和`temperature`试试。 3. 换一个更适合代码任务或更小的模型尝试。
使用 DeepSeek 等 API 时提示鉴权失败	1. API Key 错误或已失效。 2.`baseURL`不正确。 3. 账户欠费或该模型不可用。	1. 在模型供应商的控制台重新生成并复制 API Key。 2. 仔细核对 API 文档中的端点地址。 3. 检查账户余额和模型状态。
Ollama 拉取模型始终失败或极慢	网络连接问题，特别是从国外源拉取。	1.最有效方案：按照第 3.2 节设置`OLLAMA_ORIGINS`环境变量使用国内镜像。 2. 尝试在网络状况好的时段下载。 3. 对于特别大的模型，考虑先在云服务器上下载，再传输到本地。

走通整个配置流程后，最大的体会是，这种“混合模式”的 AI 编程助手才是最高效的。日常的代码补全、简单解释、小段重构，交给本地的 7B 模型，几乎是零延迟，隐私无忧。当遇到需要深度思考、复杂设计或跨文件理解的大型任务时，再手动切换到配置好的云端 DeepSeek 或保留的官方 Claude 模型，用它们更强的能力来攻坚。Claude Code 作为一个统一的客户端，完美地串联起了这两个世界。整个过程里，最花时间的反而不是配置本身，而是根据自己硬件条件和需求，去挑选和试验哪个本地模型最适合自己。我建议从codellama:7b或deepseek-coder:6.7b开始，它们的代码能力在轻量级模型里是相当出色的，足以处理日常 70% 以上的辅助编程需求。