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 在不同操作系统上安装 OllamaOllama 支持 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_HOST0.0.0.0 # 可选使服务在所有网络接口上可访问方便后续调试 export OLLAMA_MODELS/your/custom/model/path # 可选自定义模型存储路径 # 最关键的一行设置镜像源 export OLLAMA_ORIGINShttps://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 中打开命令面板CmdShiftP或CtrlShiftP。输入并选择 “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: ollamaOllama 本地服务通常不需要鉴权但这个字段是 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 服务先CtrlC停止当前服务再重新运行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 fetch1. Ollama 服务未运行。2.baseURL地址或端口错误。3. 防火墙/安全软件阻止了连接。1. 在终端运行ollama serve并确保它持续运行。2. 在浏览器或终端访问http://localhost:11434/api/tags确认能返回 JSON 格式的模型列表。3. 检查baseURL是否包含/v1。4. 暂时关闭防火墙或安全软件试试。错误信息包含Model ‘xxx’ not found1. 配置中的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% 以上的辅助编程需求。