上个月我在折腾本地 AI 编程工具的时候发现 Claude Code 这种终端型编程助手确实带感能直接在项目里读文件、改代码、跑命令。但它默认绑定 Anthropic 官方 API按 token 计费重度用下来钱包真的顶不住。身边一个同事神神秘秘地跟我说可以直接把 Claude Code 接到本地 Ollama 上跑开源模型等于“白嫖”。我当时第一反应是不信——官方客户端怎么可能随便接第三方模型结果自己花了两个周末折腾发现这条路还真能走通而且跑起来之后完全是另一个体验。只是坑也真的不少协议对不上、请求被劫持到官方、上下文一长就失忆、工具调用翻车……这篇文章把我从零到跑通的完整流程以及踩过的所有坑原原本本整理出来给想省钱又想玩 Claude Code 的人一个参考。1. 为什么要把 Claude Code 接到 Ollama动机和适用边界1.1 这套组合到底是做什么的先搞清楚一个基本概念。Claude Code 是 Anthropic 官方出的命令行 AI 编程助手它的典型用法是你打开终端给它一个任务比如“修复这个 bug”或“给这个模块补测试”它会自己读项目文件、写代码、执行命令然后循环直到任务完成。和 Cursor、Copilot 这类 IDE 插件不太一样Claude Code 更强调“代理式”工作流适合干那种多步骤的脏活累活。而 Ollama 是一个本地大模型运行工具它把 Llama、Qwen、DeepSeek 这些开源模型打包成一条命令就能跑起来的服务。装上之后你的本机就成了一个推理服务器任何程序都可以通过 HTTP 接口调用它完全免费、离线可用、数据不出本机。把这两者接起来就是让 Claude Code 这个原本只跟 Anthropic 官方云端服务对话的客户端改成跟本地 Ollama 对话。这样你不需要官网 API key不按 token 计费显卡好的话大模型在你机器里跑代码数据也不出本机。对于我在小公司做的内部工具、还有个人开源项目来说这个诱惑力非常大。1.2 核心原理协议转换与端点重定向很多人以为“接入”就是把 Claude Code 的地址改成 localhost 就行实际上没那么简单。Claude Code 使用 Anthropic 的 Messages API 格式请求和响应的 JSON 结构有一套自己的规范而 Ollama 原生提供的是 OpenAI 兼容接口路径、字段、消息格式都不一样。两边的协议不互通直接指过去是跑不起来的。所以主流的做法是在中间加一层转换代理它对外伪装成 Anthropic 的 API 服务接收 Claude Code 发来的请求然后把请求体翻译成 Ollama 能理解的 OpenAI 格式转发给 Ollama再把 Ollama 的返回结果翻译回 Anthropic 格式。Claude Code 全程以为自己在跟 Anthropic 官方服务器对话实际上背后干活的是你本地的开源模型。1.3 先泼三盆冷水适用边界在开搞之前我必须先把丑话说在前面。第一本地开源模型和 Claude 官方的大模型能力差距是客观存在的。你让一个 7B 的模型去重构一个大型代码项目它基本会乱来但如果让它写几个函数、补测试用例、做格式化还是可以胜任的。第二工具调用能力是分水岭。Claude Code 的核心依赖是工具调用它需要模型输出特定格式的 JSON 来决定“我要读哪个文件”“我要执行什么命令”。很多小模型在这一步就崩了输出的 JSON 不合法、参数名乱写、字段截断表现就是 Claude Code 界面一直在转圈或者反复重试。第三硬件门槛不是想象中那么低。本地跑模型需要足够大的内存或显存7B 模型量化后大约需要 6-8GB14B 需要 12GB 以上如果你想用 32B 级别的模型内存低于 32GB 就可以放弃了。当然如果你只是图个离线体验和隐私不在乎速度和质量那门槛可以放低一些。我把这三盆冷水放在前面是为了让后面的流程对你有实际价值——别指望本地跑个 14B 就能替代 Claude 官方最强模型但作为日常辅助、隐私敏感项目、或者学习调优练习这套组合还是很香的。2. Ollama 部署细节下载、安装、模型存储位置2.1 下载慢问题安装包和镜像源的选择Ollama 的安装包本身不大Windows 版大概几百 MB但它的官方下载地址是放在 GitHub 和境外服务器上的国内网络环境拉取时经常卡成狗。我第一次下载的时候进度条跑了半小时纹丝不动差点以为软件坏了。这里有几个实战解法。首先是安装包本身可以去国内的一些镜像站下载很多社区的网盘也有人打包好了安装包注意下载后校验一下哈希值不要从来源不明的地方乱装。其次是如果官方地址偶尔能打开但速度慢可以用浏览器开一个 VIP 通道之类的下载工具或者换个时间段再试实测凌晨时段的下载速度会好很多。还有一个小技巧安装完成后Ollama 拉取模型时也会遇到下载慢的问题因为模型默认也是从官方 registry 拉取。国内镜像方面可以通过设置OLLAMA_HOST、OLLAMA_MODELS之类的不解决下载慢真正管用的是给 Ollama 配置镜像加速或者直接用hf-mirror这类 HuggingFace 中转站下载 GGUF 格式模型后再手动导入 Ollama 的模型目录。这个我后面会提到。2.2 安装时的几个关键选项Windows 下安装很简单双击安装包一路下一步就行。但有两个细节容易被忽略。第一个是模型存储目录。Ollama 默认把模型放在 C 盘用户目录下一个 14B 模型动辄 8-10GB几个模型下来 C 盘就爆了。所以建议在安装前先设置一个环境变量OLLAMA_MODELS指定到其他盘比如 D 盘建一个D:\ollama\models目录设好之后再启动 Ollama。如果你一开始忘了设安装完了也可以改改完重启 Ollama 服务就行。实测没有遇到模型文件迁移的坑因为模型是按 digest 存储的路径变了重新 pull 一次即可。第二个是 Ollama 的监听地址。默认只监听127.0.0.1:11434这对单机使用没问题但如果后面的 Claude Code 跑在 WSL2 或者另一台机器上需要把它改成0.0.0.0:11434也就是设置环境变量OLLAMA_HOST0.0.0.0并确保防火墙放行了 11434 端口。这个坑我在后面 WSL2 章节还会展开。安装完成后在浏览器里访问http://127.0.0.1:11434如果能看到Ollama is running说明服务起来了。再用ollama list看看当前有哪些模型默认应该是空的。2.3 模型选哪个参数规模与硬件对照模型选择是决定后面体验的关键。Claude Code 本质是纯代码工具所以你要选的是代码模型。我在实测中比较了几个结论如下模型参数规模建议内存/显存工具调用稳定性代码质量qwen2.5-coder:7b7B8GB一般能写小函数qwen2.5-coder:14b14B16GB较好小任务可用qwen2.5-coder:32b32B32GB好接近可商用deepseek-coder-v2:16b16B16GB一般代码不错但工具调用弱codellama:7b7B8GB差会乱写如果你只有 8GB 内存那就只考虑 7B体验一下流程可以干正事别抱太大期望。正常建议是 14B 起步内存 16GB 以上有条件直接上 32B那是质变的级别。另外要注意内存不够时 Ollama 会走内存交换到磁盘速度慢到怀疑人生。我自己的机器是 32GB 内存最终稳定在 qwen2.5-coder:14b速度和效果比较均衡。拉取模型用这个命令ollama pull qwen2.5-coder:14b如果拉取时下载速度很慢可以检查一下 Ollama 的下载日志确认是不是卡在官方 registry 上。这种情况我可以告诉你一个实用操作去 HuggingFace 镜像站搜Qwen/Qwen2.5-Coder-14B-Instruct-GGUF下载 GGUF 文件到本地然后建一个 ModelfileFROM ./qwen2.5-coder-14b-instruct-q4_k_m.gguf再执行ollama create qwen2.5-coder:local -f Modelfile模型名后面带个:local以后就用这个名字调用。这样拉取慢的问题彻底解决还能自己控制量化等级。3. Claude Code 安装与接入 Ollama 的完整步骤3.1 安装 Claude Code 客户端Claude Code 的官方安装方式是通过 npm 全局安装前提是你的机器上已经有 Node.js版本建议 18 以上。如果没有 Node.js先去官网装一个 LTS 版本然后顺手配一下 npm 的国内源不然npm install同样可能慢到崩溃。npm config set registry https://registry.npmmirror.com npm install -g anthropic-ai/claude-code安装完成后执行claude --version能输出版本号就说明客户端装好了。如果你打算在 VSCode 的终端里用直接打开 VSCode 的集成终端运行claude命令即可不需要额外插件如果要更深度集成也可以看看社区的一些方案不过我用下来发现直接在终端里跑是最省心的。3.2 方案一LiteLLM 网关做协议转换接下来是最关键的一步让 Claude Code 能和本地 Ollama 说话。我推荐先用 LiteLLM它是一个开源的多模型网关装好之后同时提供 OpenAI 兼容端点也支持 Anthropic 格式的转换。相比自己写代理脚本LiteLLM 打包得比较完整后续还能灵活换模型。先安装 LiteLLM建议用 pipx 避免污染系统环境pipx install litellm[proxy]然后创建一个配置文件config.yamlmodel_list: - model_name: * litellm_params: model: ollama/qwen2.5-coder:14b api_base: http://127.0.0.1:11434这里model_name: *表示通配不管 Claude Code 发过来什么模型名都路由到 Ollama 的 qwen2.5-coder:14b。这是特别关键的一点因为 Claude Code 请求体里带的模型名一定是 claude 系列比如claude-3-5-sonnet之类如果你不处理映射关系网关会直接报错。启动网关litellm --config config.yaml --port 4000启动后用 curl 快速验证一下 Anthropic 端点是否可用curl http://127.0.0.1:4000/v1/messages \ -H x-api-key: local-key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-3-5-sonnet-latest, max_tokens: 100, messages: [{role: user, content: hello}] }如果返回一个带content数组的 JSON说明协议转换已经通了下面就可以配置 Claude Code 了。3.3 方案二如果没有 pipx 或者不想装笨重网关我知道有人会觉得 LiteLLM 太重毕竟它是个通用网关Python 依赖一大堆。如果你只是自己玩也可以写一个不到 50 行的迷你代理脚本。from fastapi import FastAPI, Request import httpx app FastAPI() OLLAMA_URL http://127.0.0.1:11434/v1/chat/completions MODEL_NAME qwen2.5-coder:14b app.post(/v1/messages) async def messages(request: Request): body await request.json() oai_messages [] if body.get(system): oai_messages.append({role: system, content: body[system]}) for msg in body.get(messages, []): oai_messages.append({role: msg[role], content: msg[content]}) max_tokens body.get(max_tokens, 4096) payload { model: MODEL_NAME, messages: oai_messages, max_tokens: max_tokens, stream: False, } async with httpx.AsyncClient() as client: resp await client.post(OLLAMA_URL, jsonpayload) data resp.json() text data[choices][0][message][content] usage data.get(usage, {}) return { id: msg_mini_proxy, type: message, role: assistant, model: body.get(model, local), content: [{type: text, text: text}], usage: usage, }这段脚本用 FastAPI 起一个服务监听8000端口把/v1/messages的 Anthropic 请求转成 Ollama 的 OpenAI 格式。要注意的是我在代码里把stream强制设成了 False也就是关闭流式输出Claude Code 依然能工作只是效果和速度会稍打折扣。如果你一定要流式需要对 SSE 做一次转换工程量大很多不如直接用 LiteLLM。启动方式uvicorn proxy:app --host 127.0.0.1 --port 40003.4 配置环境变量与验证请求现在万事俱备就差把 Claude Code 的脑回路从官方 API 拨到本地代理了。这一步通过环境变量完成ANTHROPIC_BASE_URLhttp://127.0.0.1:4000把请求地址指向本地代理ANTHROPIC_AUTH_TOKENlocal-test-key给一个非空的 token绕过官方的 API key 校验。在 Windows 的 PowerShell 里可以这样设置$env:ANTHROPIC_BASE_URLhttp://127.0.0.1:4000 $env:ANTHROPIC_AUTH_TOKENlocal-test-key或者在项目的.claude/settings.json里写{ env: { ANTHROPIC_BASE_URL: http://127.0.0.1:4000, ANTHROPIC_AUTH_TOKEN: local-test-key } }设置完成后在项目目录里运行claude如果一切正常你会看到它进入交互模式不会再弹出官方登录流程。在会话里输入一句“请介绍一下当前目录”如果模型确实读到了文件并输出了中文回答说明通路已经打通了。4. 踩坑实录从“连不上”到“上下文失忆”的完整排查链路4.1 坑一配了 BASE_URL 却在请求官方接口这个坑我整整折腾了一个晚上。事情是这样的环境变量配好了启动 Claude Code界面确实没弹登录我也给它发了一个任务它开始假装干活但速度极慢而且输出风格明显是官方 Claude 的特有腔调。我一看就不对劲翻日志发现它请求的端点居然是api.anthropic.com不是我的localhost:4000。查了一圈才发现Claude Code 的认证优先级是这样的如果你之前用 Claude.ai 账号登录过它会在~/.claude目录下缓存 OAuth 凭证这个凭证的优先级比ANTHROPIC_AUTH_TOKEN高。结果就是你的 BASE_URL 虽然改了但它拿着缓存的 token 去请求了官方的 token 端点绕过了本地代理。解决办法很简单先清除缓存的登录态。在 Claude Code 会话里输入/logout然后退出重进或者干脆手动删除缓存文件rm -f ~/.claude/.credentials.json删掉之后再次启动确认这次日志里请求的是127.0.0.1:4000。我建议你在/tmp/claude-code.log里搜一下api.anthropic.com如果搜到了就说明还有残留认证在作怪继续查凭证文件和环境变量优先级。4.2 坑二连接被拒绝或者一直转圈排除官方劫持之后下一个频繁出现的问题是连接被拒绝。症状是 Claude Code 界面一直转动像是思考了很久然后告诉你“connection error”或者“request failed”。这个问题的排查链路很固定先 curl 代理端口再 curl Ollama 端口逐层定位。如果curl http://127.0.0.1:4000/v1/messages都返回连接拒绝那问题在代理层没启动或者端口号不对如果代理通了但转发给 Ollama 失败就看 Ollama 的服务是否运行、端口是否是 11434。还有一次我发现 Ollama 虽然开着但被我设了OLLAMA_HOST127.0.0.1:11434而 LiteLLM 用localhost去连接在部分系统上 IPv6 解析把它带到了::1结果连不上。后来把api_base里的地址从localhost改成127.0.0.1就正常了。这类玄学问题通常就是主机名解析引起的经验就是统一用 IP 别用 localhost。4.3 坑三模型名不匹配导致的 404 或 400跑通本地代理之后我一度发现某些请求会报model not found。原因前面已经提到过Claude Code 发来的模型名是它自己固定的比如claude-3-5-sonnet-latest但 Ollama 里根本没有这个名字。如果你用 LiteLLM并且配置里model_name没有做通配或映射就会直接 400如果你用我那个迷你代理脚本由于它固定用MODEL_NAME变量所以不会出这个问题但代价是你不能通过 Claude Code 的/model命令切换后端模型。血的教训是别试图在 Claude Code 端把模型名改成qwen2.5-coder:14b因为客户端可能根本不允许自定义模型名或者它会校验这个模型名是否在官方模型列表中你会发现改完之后它依然发旧名字过去。正解就是在代理层做替换让后端永远用你指定的 Ollama 模型。4.4 坑四开源模型在工具调用上的全线翻车走过前三个坑通路已经通了但真正磨人的是工具调用的稳定性。Claude Code 是一个重度依赖工具调用的代理你让它改代码它先调用Read工具读文件再调用Edit工具改内容最后调用Bash工具跑测试。这个过程需要模型在每个步骤都输出合法的结构化参数稍有一点偏差工具就执行失败。我实测下来qwen2.5-coder:7b 在这块几乎不可用模型经常生成的 JSON 不完整、参数名和实际工具定义不匹配或者明明只改一个字符却把整个文件重写一遍。14b 稍微好一点但在多文件改动时也会出现“读了一个文件但引用了另一个文件的内容”这种幻觉。这个坑没有完美解法只能从工作习惯上规避。我给 Claude Code 的任务描述写得非常具体比如“只修改 src/utils.ts 文件里的 parseConfig 函数不要动其他文件”并且一次只让它做一件小事多轮对话后如果发现它开始乱动文件就及时中断。实测下来把任务拆小之后 14b 的可用性会明显提升。4.5 坑五上下文窗口太短与“失忆”最后一个高频坑是上下文长度。Ollama 默认给每个模型设置的上下文窗口其实相当保守很多模型默认只有 2048 或 4096 tokens。Claude Code 每次会把项目结构、命令输出、代码片段都塞进上下文里稍微大一点就超了。表现就是前期对话还挺正常聊着聊着模型突然开始“复读”你已经说过的话或者干脆答非所问感觉像失忆了。解决方法是提高 Ollama 的上下文长度。有两个办法第一个是在启动 Ollama 时设置环境变量OLLAMA_CONTEXT_LENGTH16384第二个是直接在模型层面通过 Modelfile 设置FROM qwen2.5-coder:14b PARAMETER num_ctx 16384注意上下文长度拉长之后会显著增加内存占用显存不足的话推理速度会大幅下降。我自己的 32GB 内存机器跑到 16K 上下文勉强能接受但如果你只有 16GB 内存还是老老实实保持短上下文同时把任务拆得更碎一些。4.6 坑六WSL2 与 Windows 的端口互通问题如果你和我的环境一样Windows 上装了 Ollama但 Claude Code 跑在 WSL2 里或者反过来你会遇到一个很抽象的互通问题。WSL2 的 localhost 转发机制时好时坏。Windows 访问 WSL2 内运行的 Ollama一般可以直接用localhost:11434因为 WSL2 默认开启了转发但反过来WSL2 内访问 Windows 宿主的服务经常拿不到正确端口。我当时是 Ollama 装在了 Windows 宿主WSL2 里跑 Claude Code结果 WSL2 里 curllocalhost:11434一直超时。排查办法是在 WSL2 里找到宿主的 IPcat /etc/resolv.conf | grep nameserver拿到 IP 之后把 Ollama 的监听地址改成0.0.0.0:11434同时放行 Windows 防火墙的入站端口然后把代理配置里的api_base指向那个 IP就能通了。如果不想记 IP还可以在 WSL2 的/etc/hosts里加一行映射把固定 IP 映射成一个 hostname省得每次重启 IP 变了都要改配置。另外还要提醒一句Claude Code 跑在 WSL2 里访问 Windows 文件系统/mnt/c/时文件监听和读写性能会有明显的下降尤其是大项目。如果项目本身能放 Linux 文件系统里~/目录下尽量放 Linux 侧体验会好很多。5. 实测效果与最终的配置清单5.1 不同模型在 Claude Code 里的表现跑通之后我拿手头的几个开源模型做了横向对比场景是给一个 Python 脚本补测试用例和修一个简单的正则 bug。qwen2.5-coder:7b 在这个场景下勉强能用输出的测试用例结构完整但偶发会漏掉边缘 case修 bug 时有点“头疼医脚”的倾向。14b 的表现明显上了一个台阶修正逻辑的原因分析基本正确补测试时也能模仿出项目风格。32b 由于我内存不够没测完整但从朋友机器上的体验看在小项目上的可用性已经接近一个初级工程师的水平。deepseek-coder-v2 的代码生成质量其实不差但它的工具调用输出格式经常不符合 Claude Code 的预期导致流程频繁中断需要手动介入。codellama 则完全不要碰它在结构化输出上的表现堪称灾难。5.2 我最后留下的配置折腾这么一圈我最后稳定下来的配置是Windows 宿主 Ollama qwen2.5-coder:14b LiteLLM 网关Claude Code 跑在 VSCode 的 PowerShell 终端里。配置文件很小复用方便。config.yamlmodel_list: - model_name: * litellm_params: model: ollama/qwen2.5-coder:14b api_base: http://127.0.0.1:11434.claude/settings.json{ env: { ANTHROPIC_BASE_URL: http://127.0.0.1:4000, ANTHROPIC_AUTH_TOKEN: local-test-key } }启动顺序我建议是固定的先起 Ollama再起 LiteLLM最后运行claude。如果哪个环节没启动Claude Code 的表现往往是“看似思考了很久最终报错”而不是即时反馈这一点容易让人误判提前知道能省很多排查时间。5.3 我的日常使用套路这套配置在日常工作中我主要用来做三类事情给现有代码补测试、解释陌生项目里的关键模块、批量做机械性的代码重构。这些任务对模型的创造能力要求不高但对“老老实实按指令执行”要求很高恰恰是开源代码模型比较擅长的区间。我也给自己立了几条规矩涉及数据库迁移、核心交易逻辑等高风险代码绝不交给本地模型写多文件联动的大改动会先让它出方案我确认之后再进行每轮任务结束我会主动检查 Claude Code 的 diff 和测试结果不盲目信任模型输出。说句公道话这套方案无法完全替代官方 Claude 的能力但在不花钱、数据可控的前提下确实做到了一个相当可用的编程辅助级别。最后分享一个小技巧如果你想让 Claude Code 在本地模型下表现更稳定可以在启动时加一个全局提示词让它“每次修改前先总结当前文件结构并且只修改任务涉及的代码”。这个提示对像 qwen 这类指令遵循能力偏弱的开源模型特别有效能明显减少它乱动无关代码的概率。