1. 项目概述为什么我们需要在 Claude Code 中配置本地模型最近在开发者圈子里Claude Code 的热度持续攀升但很多朋友在尝鲜后都遇到了同一个瓶颈官方 API 调用有次数限制响应速度受网络影响而且对于一些涉及内部代码或敏感数据的场景直接把代码片段发到云端总让人心里不踏实。与此同时像 Ollama 这样的本地大模型部署工具越来越成熟DeepSeek 等优秀的开源模型也层出不穷。一个很自然的需求就产生了能不能让 Claude Code 这个好用的 IDE 智能助手直接调用我本地部署的模型呢这样既没有网络延迟也没有隐私顾虑还能自由选择最适合自己任务的模型。答案是肯定的而且配置过程并没有想象中那么复杂。简单来说Claude Code 支持通过配置自定义的 “后端”Backend将模型推理请求转发到你指定的本地服务上无论是 Ollama、LM Studio还是直接调用 DeepSeek 的官方 API。这相当于给 Claude Code 换了一个“大脑”而这个大脑完全可以由你自己来部署和掌控。接下来我将以一个资深全栈开发者的视角带你一步步拆解这个配置过程分享我趟过的坑和总结出的最佳实践让你也能轻松打造一个完全属于自己、高效且私密的智能编程环境。2. 核心思路与方案选型本地模型接入的几种路径在动手之前我们得先理清思路。Claude Code 本质上是一个客户端它需要向一个符合其通信协议的“模型服务端”发送请求并获取补全或对话结果。因此我们的核心工作就是搭建或指定这样一个服务端并让 Claude Code 正确连接到它。2.1 主流本地模型服务方案对比目前主流的、能与 Claude Code 配合的本地模型服务方案主要有以下三类各有优劣方案一使用 Ollama这是目前最流行、对新手最友好的方案。Ollama 是一个强大的开源框架专门用于在本地运行、管理和服务大型语言模型。它帮你处理了复杂的模型下载、环境配置和 API 服务暴露你只需要几条简单的命令。优点安装部署极其简单模型库丰富支持 Llama、Mistral、Qwen、DeepSeek 等众多系列社区活跃文档完善。缺点对硬件有一定要求尤其是内存默认从国外拉取模型可能较慢但有解决办法。适合人群绝大多数开发者尤其是希望快速上手、不想折腾底层细节的朋友。方案二使用 LM Studio这是一个带有图形界面的桌面应用程序功能比 Ollama 更强大一些除了提供本地模型服务还内置了聊天界面方便直接测试模型。优点图形化操作直观易用支持更多格式的模型文件GGUF、GPTQ等可以更细致地调整推理参数。缺点软件本身更重一些在纯命令行或服务器环境下不如 Ollama 灵活。适合人群偏好图形化操作或需要测试多种不同格式模型的用户。方案三直接调用远程/本地 API如果你已经在某台服务器上通过vLLM、TGI(Text Generation Inference) 或Ollama部署了模型服务或者想直接使用 DeepSeek 的官方云端 API虽然这不完全是“本地”也可以采用此方案。优点最灵活可以对接任何提供 OpenAI 兼容 API 的服务端。适合已有模型服务基础设施的团队。缺点需要自行确保 API 服务的稳定性和安全性配置稍复杂。适合人群有运维经验或在公司内网已有模型服务的开发者。对于绝大多数个人开发者和中小团队我强烈推荐从Ollama开始。它平衡了易用性、功能性和社区支持是我们后续演示的重点。而 DeepSeek 作为当前性能第一梯队的开源模型自然是我们想要加载的首选。2.2 Claude Code 的配置逻辑解析Claude Code 的配置核心在于其设置中的Claude Code: Backend选项。它允许你指定一个后端类型如Ollama和对应的基础 URL。当你在 IDE 中触发代码补全或对话时Claude Code 会按照 OpenAI API 的格式将请求发送到你配置的 URL例如http://localhost:11434/v1Ollama 服务接收到请求后调用指定的模型进行推理再将结果返回给 Claude Code。这里有一个关键点Ollama 提供了 OpenAI 兼容的 API 端点。这正是 Claude Code 能无缝接入的原因。你不需要修改 Claude Code 的代码只需要告诉它“别去找官方的服务器了去找我本地的这个地址。”3. 实操准备Ollama 的安装与模型拉取理论清晰后我们进入实战环节。第一步是在你的机器上安装并运行 Ollama。3.1 安装 OllamaOllama 支持 macOS、Linux 和 Windows (预览版)。以 macOS 和 Linux 为例安装通常只需一行命令# 官方安装脚本适用于 macOS 和 Linux curl -fsSL https://ollama.com/install.sh | sh安装完成后Ollama 服务会自动在后台启动。你可以通过运行ollama serve来显式启动服务或者用ollama --help查看所有命令。注意很多朋友反映从国外下载 Ollama 本体或模型时速度很慢甚至失败。这里分享两个关键技巧使用国内镜像加速下载对于模型拉取可以在运行ollama pull命令前设置环境变量OLLAMA_HOST指向国内镜像源。例如有些社区维护的镜像站速度不错但需自行寻找可靠来源。请注意务必使用可信的镜像源避免安全风险。手动下载模型文件对于完全无法连接的情况可以尝试在能访问的机器上先下载好模型文件通常是一个名为Modelfile和若干数据文件然后通过ollama create命令从本地文件创建模型。这是最彻底但稍显麻烦的方法。3.2 拉取并运行 DeepSeek 模型Ollama 官方库中已经收录了 DeepSeek 系列模型。目前推荐使用deepseek-coder系列它在代码任务上表现非常出色。选择哪个版本取决于你的硬件配置deepseek-coder:6.7b适合大多数拥有 8GB 以上显存的电脑响应速度快代码能力足够强。deepseek-coder:33b需要更大的内存建议 32GB能力更强但推理速度会慢一些。deepseek-coder:1.3b或deepseek-coder:6.7b-instruct-q4_K_M如果硬件资源非常有限可以尝试更小的量化版本带q4、q5等后缀它们通过降低精度来减少内存占用但性能会有一定损失。执行以下命令拉取并运行一个模型# 拉取模型以 6.7B 版本为例 ollama pull deepseek-coder:6.7b # 运行模型。运行后模型服务就启动了。 ollama run deepseek-coder:6.7bollama run命令会启动一个交互式聊天界面你可以在这里先简单测试一下模型是否工作正常例如问它“用 Python 写一个快速排序函数”。测试成功后可以按CtrlD退出交互界面但Ollama 服务仍在后台运行并监听 API 请求。关键检查点打开浏览器访问http://localhost:11434/api/tags。如果看到返回的 JSON 数据中包含你刚拉取的模型信息如deepseek-coder:6.7b说明 Ollama 服务及模型加载一切正常。这个地址http://localhost:11434就是我们稍后要在 Claude Code 中配置的 Backend URL 的基础部分。4. 核心配置在 Claude Code 中连接本地 OllamaOllama 服务就绪后接下来的配置在 Claude Code 中完成非常简单。4.1 打开 Claude Code 设置在 VSCode 中按下Cmd,(Mac) 或Ctrl,(Windows/Linux) 打开设置。在搜索框中输入 “Claude Code”。4.2 配置 Backend你需要找到并设置以下两个关键选项Claude Code › Backend: Type在下拉菜单中选择Ollama。这是最直接的方式Claude Code 会为你预填充一部分配置。Claude Code › Backend: Url当你选择Ollama类型后此字段通常会默认填充为http://localhost:11434/v1。请确保它确实如此。/v1这个路径至关重要这是 Ollama 提供的 OpenAI 兼容 API 的端点。如果只填http://localhost:11434Claude Code 将无法正确通信。4.3 选择模型接下来你需要告诉 Claude Code 使用 Ollama 服务中的哪个具体模型。Claude Code › Model点击输入框Claude Code 可能会尝试从你配置的 Backend URL 拉取可用的模型列表。如果拉取成功你可以直接从下拉列表中选择deepseek-coder:6.7b。如果下拉列表没有出现或者拉取失败你需要手动输入模型的名称。这个名称必须与你在 Ollama 中拉取和运行的模型名称完全一致例如deepseek-coder:6.7b。4.4 验证连接配置完成后无需重启整个 VSCode。你可以直接打开一个代码文件尝试触发代码补全例如在 Python 文件中输入一个函数名开头或者打开 Claude Code 的聊天面板发送一个问题。如何判断是否成功成功代码补全正常出现聊天回复内容来自 DeepSeek-Coder你可以问它“你是谁”它会回答自己是 DeepSeek Coder。同时观察你运行ollama run的终端或者通过ollama list查看模型运行状态应该能看到新的推理请求和资源占用。失败Claude Code 界面通常会弹出错误提示例如“无法连接到后端”、“模型未找到”等。此时就需要进入排查环节。5. 深度排查与进阶调优配置过程看似简单但实际操作中可能会遇到各种问题。下面是我总结的常见故障排查清单和进阶优化技巧。5.1 常见问题与解决方案速查表问题现象可能原因排查步骤与解决方案错误无法连接到后端1. Ollama 服务未运行。2. Backend URL 配置错误。3. 防火墙/端口阻止。1. 终端执行ollama serve确保服务启动。2. 浏览器访问http://localhost:11434看是否显示 Ollama 运行信息。访问http://localhost:11434/v1/models看是否返回模型列表。3. 确认 URL 是http://localhost:11434/v1注意http而非https以及末尾的/v1。错误模型未找到1. 模型名称拼写错误。2. 模型未成功拉取或加载。1. 终端执行ollama list核对准确的模型名称包括标签。2. 在 Claude Code 的 Model 设置中严格按ollama list显示的名称输入。3. 执行ollama run 模型名测试模型是否能独立运行。Claude Code 无响应或补全慢1. 本地硬件资源CPU/内存/显存不足。2. 模型太大硬件跑不动。3. Ollama 未使用 GPU 加速。1. 监控系统资源占用活动监视器、任务管理器等。2. 换用更小的模型如从 33B 换到 6.7B或量化版模型如q4_K_M。3. 对于 NVIDIA GPU确保安装了正确版本的 CUDAOllama 通常能自动检测并使用。可通过ollama run时的输出信息查看是否使用了 GPU。拉取模型速度极慢网络连接到 Ollama 官方仓库不畅。1.设置镜像源通过配置环境变量或修改 Ollama 服务配置使用国内镜像源加速下载需自行搜索当前可用的可靠镜像地址。2.手动下载在网络好的环境下载模型文件然后通过ollama create从本地导入。补全质量不佳1. 模型本身能力限制。2. 提示词Prompt或上下文长度设置问题。1. 尝试不同的模型。对于代码deepseek-coder通常比通用聊天模型如llama3更专业。2. 在 Claude Code 设置中可以尝试调整Temperature降低如 0.2让输出更确定和Max Tokens增加以获得更长的补全。5.2 进阶技巧性能优化与多模型管理当你基本功能跑通后下面这些技巧能显著提升使用体验1. 为 Ollama 配置 GPU 加速NVIDIA如果你的电脑有 NVIDIA 独显确保 Ollama 能利用上可以极大提升推理速度。Ollama 默认会尝试检测 CUDA。你可以通过以下命令检查ollama run deepseek-coder:6.7b观察输出日志如果看到类似“Using GPU 0 (NVIDIA GeForce ...)”的信息说明 GPU 已启用。如果没有你需要检查 CUDA 和 cuDNN 的安装。在 macOS 上Metal 后端是自动启用的。2. 管理多个模型你不可能只用一个模型。可以通过ollama list查看已下载的模型ollama pull拉取新模型ollama rm 模型名删除不再需要的模型以节省空间。在 Claude Code 中切换模型只需修改Claude Code › Model设置即可无需重启服务。3. 调整模型参数除了在 Claude Code 侧调整Temperature你还可以在创建或运行 Ollama 模型时指定更多参数。例如创建一个自定义的 ModelfileFROM deepseek-coder:6.7b # 设置较低的 temperature 以获得更确定的代码输出 PARAMETER temperature 0.1 # 设置更高的上下文窗口如果模型支持 PARAMETER num_ctx 16384然后通过ollama create my-coder -f ./Modelfile创建自定义模型在 Claude Code 中选用my-coder即可。4. 保持服务常驻与资源管理ollama run在退出交互后会保持服务但如果你关闭了终端服务可能会停止。对于 Linux/macOS可以考虑使用systemd或launchd将 Ollama 设为后台服务开机自启。另外注意模型会占用大量内存。如果长时间不用可以通过ollama stop 模型名来卸载模型释放内存下次使用时 Claude Code 的请求会自动重新加载它。6. 扩展方案配置其他模型后端虽然 Ollama 是首选但了解其他配置方式能让你应对更多场景。6.1 配置 LM StudioLM Studio 的配置逻辑与 Ollama 类似因为它也提供了 OpenAI 兼容的 API 端点。启动 LM Studio在左侧加载一个模型如 Qwen 的 GGUF 文件。点击顶部导航栏的 “Local Server” 选项卡。点击 “Start Server”。LM Studio 会在本地启动一个服务器并显示 API 地址通常是http://localhost:1234/v1。在 Claude Code 设置中将Backend: Type设置为OpenAI(或Other取决于 Claude Code 版本)然后将Backend: Url设置为 LM Studio 显示的地址如http://localhost:1234/v1。在Model设置中输入你在 LM Studio 中加载的模型名称如Qwen2.5-Coder-7B-Instruct-GGUF。6.2 配置 DeepSeek 官方 API如果你希望使用 DeepSeek 官方最新的云端模型如 DeepSeek-V3或者你在某台云服务器上部署了模型 API也可以进行配置。获取你的 API 密钥和基础 URL。对于 DeepSeek 官方URL 是https://api.deepseek.com。在 Claude Code 设置中将Backend: Type设置为OpenAI。将Backend: Url设置为https://api.deepseek.com。通常还需要配置Claude Code › Api Key字段填入你的 DeepSeek API 密钥。在Model设置中输入你想使用的模型名称如deepseek-chat。重要提示使用官方 API 意味着你的代码片段会被发送到 DeepSeek 的服务器请勿用于处理敏感、涉密或非公开的代码。6.3 关于 “Codex接入DeepSeek” 和 “CC Switch”在一些网络讨论中你可能会看到 “Codex” 或 “CC Switch” 这样的词。这里需要澄清一下Claude Code vs CodexClaude Code 是 Anthropic 公司推出的 IDE 插件。而 Codex 通常指的是 OpenAI 的 Codex 模型GPT-3 的代码版本或者是某些第三方开发的、旨在连接多种 AI 后端的工具/插件。它们是不同的东西。本文讨论的是Claude Code插件。CC Switch这可能指的是 Claude Code 内部用于切换不同后端配置的功能或社区开发的辅助工具。其核心原理与我们上面手动配置Backend和Model是一致的可能提供了一个更友好的图形界面来管理多个配置预设。但底层依赖的仍然是 Ollama、LM Studio 或 OpenAI 兼容的 API 服务。配置本地模型到 Claude Code 的过程本质上是一个“搭桥”的工作。一旦你成功搭建了这座桥你就获得了一个响应迅速、完全私密、且可高度定制的智能编程伙伴。从简单的代码补全到复杂的系统设计讨论你都可以在本地环境中放心地进行。我自己的体验是在接入本地 DeepSeek-Coder 后对于网络延迟的焦虑完全消失了在思考复杂逻辑时与模型的连续对话也变得非常流畅。如果你在配置过程中遇到了上面未覆盖的奇怪问题我的建议是首先回到原点用curl命令或浏览器直接测试你的本地模型 API 端点是否正常工作其次查看 Claude Code 的输出日志通常在 VSCode 的“输出”面板选择“Claude Code”那里往往藏着最直接的错误信息。