Claude Code本地化：用Ollama在NUC集群搭建AI编程助手

如果手里有几台 NUC 这类迷你主机又想让 Claude Code 这样的 AI 编程助手在本地完成一部分编码任务你大概率会遇到一个现实问题Claude Code 默认走云端接口订阅限制、网络波动、数据隐私、排队超时每一项都可能影响实际使用。Yeschef 解决的就是这个问题——它把 Claude Code 发出的任务分发给局域网里的 Ollama 节点让模型推理发生在本地而不是云端。实测在 3 台 NUC 组成的局域网环境里跑出了 627 tok/s 的吞吐速度。这个数字可以作为参考但更值得关注的是这套架构本身前端工具不变后端换成自己能掌控的本地模型节点。下面我按实际搭建顺序把这套方案拆开来说。重点不是介绍某个现成工具怎么用而是帮你理解“Claude Code 派单、Ollama 干活、局域网组网”这件事里的关键链路、参数、验证方式和常见坑。1. 先搞懂 Yeschef 在整套架构里到底管什么1.1 它没有替代 Claude Code而是在前端和后端之间加了一层调度很多人第一次看到这类项目容易理解成“用 Ollama 替代 Claude”。这个理解不对。Claude Code 是编码代理工具它的价值在于理解你的命令、读代码、改文件、跑命令甚至提交内容。Ollama 是本地模型运行器它只负责加载模型、接收提示词、生成文本。真正的问题是Claude Code 默认连接的是 Anthropic 云端 API请求格式、鉴权方式、返回结构都按云端接口来。而 Ollama 自己的接口是/api/chat或者/api/generate字段完全不同。你不可能直接把ANTHROPIC_BASE_URL改成 Ollama 地址就让 Claude Code 正常工作至少中间要有人做协议转换。Yeschef 这类工具承担的正是这个转换层和调度层接收 Claude Code 发来的请求把 Anthropic Messages API 格式转换成 Ollama 能理解的格式在一组局域网节点里选择一台合适的 NUC 做推理把结果再转换成 Claude Code 能读的响应所以它更像一个任务分发器或者说一个本地网关。1.2 为什么 3 台 NUC 会比一台更有吸引力NUC 的特点是体积小、功耗低、放在家里或办公室不占地方。一台 NUC 跑 7B 或 14B 参数的量化模型日常修改代码、解释报错、写脚本是够用的。但如果同时开几个任务单台机器很快就内存吃紧、CPU 打满token/s 掉得很明显。这时候把 3 台 NUC 组成一个局域网推理集群价值就出来了。Yeschef 按一定策略把不同请求分到不同机器整体吞吐自然比单台高。627 tok/s 我理解是这个 3 节点组合在某一轮实测里的整体吞吐不代表单个请求一定比单台机器快。多机主要提升的是并发能力也就是同一时间能处理更多任务而不是某个任务本身速度翻三倍。这一点必须提前说清楚否则你会对实测数字产生误解。1.3 适不适合你看三个条件这套方案适合已经有一台或多台空闲 x86 迷你主机不想闲置重视数据隐私希望代码片段和会话内容只在内网流转对本地模型的速度和稳定性有合理预期不指望 7B 模型能媲美云端最强模型不适合没有 Linux 或命令行基础的人希望本地模型完全达到云端顶级代码模型能力的人只有一台低配置机器还非要并发跑多个大模型的人2. 动手前的硬件和网络判断比安装更重要2.1 NUC 能跑什么模型先看内存而不是“能不能装”Ollama 本身几乎能在任何 Linux 机器上装但能不能跑出可用速度关键看内存和 CPU 指令集。NUC 一般没有独显主要靠 CPU 和内存带宽做推理。如果你机器是 16GB 内存建议跑 7B 到 14B 的量化模型如果 32GB可以考虑 30B 左右的小尺寸模型。我一般会按这个参考来选内存大小推荐模型范围说明8GB3B 到 7B 量化模型适合轻量文本生成编码能力有限16GB7B 到 14B 量化模型比较平衡能处理简单代码任务32GB14B 到 30B 量化模型代码理解能力明显更好但 CPU 推理仍然慢64GB 及以上30B 以上如果有单机体验会好很多注意NUC 的内存带宽通常不如服务器平台实际 token/s 会偏低。先跑free -h看看内存再决定拉哪个模型。2.2 网络比计算更容易成为性能瓶颈这套方案叫 LAN 部署网络质量直接决定最终体验。Ollama 拉取模型、Claude Code 发请求、节点返回内容全部走局域网。如果节点之间用 Wi-Fi 连接尤其是无线网卡驱动不稳定或信号一般你会发现 token/s 波动很大甚至经常连接超时。我建议每台 NUC 优先走网线千兆局域网是底线在路由器里给 3 台机器设置固定 IP或者开启 DHCP 保留关闭接入点隔离、客户端隔离这类功能如果用的是某些 Realtek 无线网卡遇到频繁断流先更新驱动再考虑换有线这里容易踩一个坑你明明把 Ollama 监听地址改成了0.0.0.0局域网其他机器却连接失败。查到最后往往不是 Ollama 的问题而是路由器把设备隔离了或者防火墙没放行 11434 端口。2.3 软件前置Linux 系统、CPU 指令集、交换分区三台 NUC 建议统一装 Ubuntu Server 或 Debian版本不用太新LTS 版本就行。用 Docker 跑 Ollama 也可行但如果你只是为了局域网分发直接二进制安装反而更简单少一层容器网络映射。安装前检查一件事CPU 是否支持 AVX2 或 AVX512。Ollama 底层推理库对这些指令很依赖太老的 CPU 即使能跑速度也会很难看。另外建议给 NUC 开点 swap 分区。我之前遇到过拉取模型后启动推理进程直接被killed的情况查 dmesg 发现是内存不够。开 4GB 到 8GB swap 能救急但不要指望 swap 能替代内存一旦长时间用到 swap吞吐会掉到不可用的程度。3. 把 Ollama 装起来让局域网真的能访问到3.1 安装 Ollama下载慢先别急Linux 下最常见安装方式是curl -fsSL https://ollama.com/install.sh | sh如果你所在网络访问官方源很慢可以先去官网下载对应架构的二进制包拿到 U 盘或内网机器上分发。多台 NUC 之间也可以先把安装包拷到一台机器然后通过 scp 传到其他机器。Ollama 下载慢通常有两种情况一是安装脚本下载二进制慢二是拉取模型慢。前者优先用离线包后者可以配置国内可用的镜像源或者直接在局域网内提前拉好模型再共享。具体镜像地址经常变我不在这里写死建议装好后先跑一次ollama pull观察实际速度再决定用哪个源。3.2 修改监听地址让其他机器能连Ollama 默认只监听本机回环地址127.0.0.1:11434这意味着远程机器访问不到。需要把它改成0.0.0.0:11434。如果用 systemd 管理服务修改服务配置sudo systemctl edit ollama.service写入[Service] EnvironmentOLLAMA_HOST0.0.0.0:11434然后重启sudo systemctl daemon-reload sudo systemctl restart ollama如果你不用 systemd直接在终端运行OLLAMA_HOST0.0.0.0:11434 ollama serve这里最容易被忽略的是防火墙。Ubuntu 上如果有 ufw需要放行sudo ufw allow 11434/tcp3.3 拉取模型并用 curl 做一次单机验证以代码任务为主的话可以拉取 qwen2.5-coder 系列ollama pull qwen2.5-coder:14b或者先用更小的模型验证链路ollama pull qwen2.5-coder:7b拉取完之后直接在 Ollama 所在机器验证推理是否正常curl http://localhost:11434/api/generate \ -d {model: qwen2.5-coder:7b, prompt: 用 Python 写一个判断素数的函数, stream: false}能返回完整 JSON 响应说明 Ollama 本身没问题。3.4 三台 NUC 各自部署并确认互相能访问三台机器都按上面步骤装好 Ollama拉取相同模型。然后用局域网 IP 做一次跨机验证比如在 A 机器上访问 B 节点curl http://192.168.1.11:11434/api/version curl http://192.168.1.12:11434/api/version curl http://192.168.1.13:11434/api/version全部返回版本信息说明网络层通了。我建议把每台机器的 IP、模型列表、是否可访问列成一张表格方便排查节点内网 IP内存已拉取模型跨机访问NUC-1192.168.1.1016GBqwen2.5-coder:7b通NUC-2192.168.1.1116GBqwen2.5-coder:7b通NUC-3192.168.1.1232GBqwen2.5-coder:14b通这一步很关键。不要在 Claude Code 还没接好时就去调多条链路先把底层网络和 Ollama 都验证完后面排错会容易很多。4. 把 Claude Code 接到本地 Ollama关键在转换层4.1 环境变量怎么配为什么不是直接指到 OllamaClaude Code 支持通过环境变量切换 API 端点和模型名。常规思路是export ANTHROPIC_BASE_URLhttp://127.0.0.1:8080 export ANTHROPIC_MODELqwen2.5-coder:7b export ANTHROPIC_API_KEYollama这个8080不是 Ollama 的 11434而是 Yeschef 或同类适配层暴露的端口。原因我前面提过Claude Code 发的是 Anthropic Messages API 格式Ollama 原生接口不认。必须有中间层把请求转成 Ollama 的chat或generate格式同时把 Ollama 的返回包装回 Anthropic 格式。所以整个请求链是Claude Code ↓ Anthropic 格式 Yeschef 适配层协议转换 节点选择 ↓ Ollama API 格式 Ollama 节点 1/2/3 ↓ 生成结果 Yeschef 适配层 ↓ Anthropic 格式 Claude Code网上很多“Claude Code 切换到本地模型”的脚本本质就是改这几个环境变量。但如果少了协议转换层直接指向 Ollama 的 11434通常会在收到请求后立刻报 404 或 400。这不是模型问题而是接口格式不匹配。4.2 模型名映射最容易出问题如果你只在一台机器上配好模型名那没问题。但多台 NUC 并行时每台机器的模型名称必须一致。比如节点 1 拉的是qwen2.5-coder:7b节点 2 拉的是qwen2.5-coder:latestOllama 会认为它们是不同的模型 tag适配层在选节点时可能因为找不到指定模型而报错。更隐蔽的问题是Claude Code 的模型名和 Ollama 的模型 tag 不完全一致。比如 Claude Code 端配置成qwen2.5-coder-7bOllama 端实际名称是qwen2.5-coder:7b连字符和冒号不一样就可能出现类似“not a model this version of Claude Code recognizes”的报错。我的建议是在适配层统一配置一个模型映射表{ model_map: { qwen2.5-coder:7b: qwen2.5-coder:7b, local-code: qwen2.5-coder:14b }, nodes: { nuc1: http://192.168.1.10:11434, nuc2: http://192.168.1.11:11434, nuc3: http://192.168.1.12:11434 } }这只是一个示例配置真实项目可能字段不一样但思路一致把逻辑模型名和物理模型名分开调度层只认逻辑名。4.3 做一次最小测试看链路是否真实打通配置好环境变量之后不要直接让 Claude Code 去改大项目。先在 Claude Code 里发起一个简单任务例如让 Claude Code 解释一段 Python 代码让 Claude Code 写一个简单的递归函数让 Claude Code 分析当前目录里的 README 文件然后打开适配层日志观察是否收到来自 Claude Code 的请求请求被转发到了哪台 NUCOllama 是否返回了内容适配层是否把响应回传给了 Claude Code如果 Claude Code 那边一直转圈先看适配层有没有请求进来如果适配层有请求但没返回再看 Ollama 日志和模型是否加载成功如果 Ollama 返回正常但 Claude Code 报错大概率是响应格式转换时出问题比如流式输出格式不对、字段命名不一致。4.4 627 tok/s 这类数据是怎么验证出来的实测速度不是只有工具告诉你一个数字那么简单。我会用下面几个角度交叉验证单条响应耗时从输入 prompt 到完整输出结束看秒数token 吞吐用输出 token 数除以生成耗时得到 tok/s首 token 延迟用户发出请求到模型开始吐字的时间这个值影响交互感并发成功率同时发多个任务统计完成率和失败数Ollama 日志里能看到每次请求的加载和推理耗时。适配层日志里能记录转发节点、开始时间、结束时间、生成字符数。把两边时间戳对齐就能算出这段时间里的真实吞吐。627 tok/s 在 CPU 推理环境下已经不错了。但如果你看到自己机器只有 20 tok/s不要急着怀疑工具先看模型是不是太大、内存是不是被占满、是不是用了太老的 CPU、是不是所有节点都打到同一台机器上了。5. 多机调度和批量任务别一上来就把并发拉满5.1 三种常见分发策略按你的场景选多节点部署以后适配层需要决定每个请求跑在哪台机器上。常见策略有三种策略逻辑适用场景轮询按顺序轮流分给节点各节点配置接近任务轻重差不多最小负载优先分给当前任务数最少的节点节点配置差异大或任务耗时差距大按任务类型分发简单任务去小模型节点复杂任务去大模型节点有明确的模型分工如果 3 台 NUC 配置一样轮询最简单。如果有一台内存 32GB、其余 16GB我建议做最小负载让 32GB 机器承载更多 14B 任务16GB 机器只跑 7B。5.2 单任务只会落在单台机器上多机提升的是并发这是很多人误解最多的地方。3 台 NUC 并不代表一个 Claude Code 任务会被拆成三份并行计算。大多数场景下单个任务只会被分发给其中一个节点完整处理。多机的意义在于当任务 D 在进行时任务 E 可以同时跑到另一台机器上而不是排队等第一台空了。所以你可以这样理解单任务延迟取决于单台 NUC 的 CPU、内存带宽、模型大小多任务吞吐取决于节点数量、分发策略、单机稳定性和网络带宽如果你只是一个人用 Claude Code同时只开一个会话那 3 台机器的优势没那么明显。如果你有多个终端会话、多个任务队列或者将来接入自动化脚本多节点并发价值就很大。5.3 批量任务要考虑失败重试、输出命名和幂等一旦从手动单任务变成批量编码任务重点就不是模型快不快而是流程稳不稳定。建议提前想好这几件事失败重试任务超时或节点宕了能不能自动换到另一个节点重跑输出命名多节点生成的结果文件如果都写到同一个目录会不会互相覆盖幂等性同一个任务如果被重跑两次修改代码的结果是否一致不能因为重试导致重复插入逻辑日志关联任务 ID 要贯穿 Claude Code、适配层、Ollama 三层出问题时能定位到具体节点我实际跑批量任务时习惯先拿 5 条任务测一轮确认失败率低、输出一致再放大到 50 条。不要一上来就把并发开到 10节点一旦 OOM后面所有任务都会跟着失败。6. 常见问题排查从现象到根因按这个顺序查6.1 局域网里连不上 Ollama 节点现象在另一台机器执行curl http://192.168.1.11:11434/api/version超时或拒绝连接。排查顺序在 Ollama 所在机器执行curl http://localhost:11434/api/version确认服务本身正常确认OLLAMA_HOST是否设置成0.0.0.0:11434确认路由器没有开启客户端隔离确认系统和路由器防火墙放行了 11434 端口如果所有配置都正常还可以curl http://192.168.1.11:11434/api/version在 Ollama 机器上自己访问局域网 IP排除防火墙方向问题6.2 请求返回 404、400、模型名不识别这类报错很常见比如deepseek-v4-pro is not a model this version of Claude Code recognizes。原因一般有三种Claude Code 配置的模型名和 Ollama 模型 tag 不一致适配层没有正确转发到拥有该模型的节点请求格式没有转换成功Ollama 返回了错误码排查时先确认 Ollama 本地模型列表ollama list然后确认 Claude Code 环境变量里的模型名和这个输出完全一致。如果不一致要么改环境变量要么在适配层加模型映射。6.3 进程被 killed 或 Ollama 日志出现 OOM现象启动模型后没过多久进程消失或者日志里直接出现killed。排查顺序执行free -h看内存是否被占满执行dmesg | tail看内核是否报告 OOM killer检查是否同时启动了多个大模型7B 和 14B 同时加载会把内存吃光临时加 swapsudo fallocate -l 8G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile加 swap 只是应急长期使用还是要控制同时加载的模型数量。Ollama 默认会保持模型常驻内存如果任务不断切换不同模型内存会被撑爆。6.4 速度很慢token/s 上不去不要只看 CPU 核数CPU 推理时内存带宽和缓存影响更大。可以先试降低模型量化等级比如从qwen2.5-coder:14b换成qwen2.5-coder:7b确认同一时间只有一个大模型加载在内存里检查局域网是不是无线连接无线网卡信号弱会导致响应像“卡住”在适配层调整并发数把并发降下来排队反而可能更快如果所有节点都是 CPU 推理token/s 有上限是正常的。追求高速就换更强 CPU、更大内存带宽或者加一张本地推理卡不能只靠堆节点数。6.5 返回内容乱码或截断乱码最常见的原因是终端编码和流式输出拼接问题。Claude Code 和适配层之间如果没按 UTF-8 处理中文内容容易出现乱码。先确认环境变量LANG和LC_ALL设置为en_US.UTF-8或C.UTF-8。响应截断则可能是流式输出没有正确处理。适配层如果只接收完整响应而 Ollama 的流式返回某段超时就会出现“内容不完整但 Claude Code 认为已经结束”的情况。排查时看适配层日志确认每次响应是否有done字段。7. 我自己的落地建议从小规模开始别急着铺开7.1 从单机到多机的升级路径如果你现在还没搭我强烈建议按这个顺序来先在一台 NUC 上装好 Ollama拉一个小模型用 curl 验证推理正常再配好 Claude Code 的本地端点跑通一个简单代码任务确认稳定后再加入第二台 NUC配置节点列表观察请求是否轮流落到不同机器最后加入第三台做并发测试和失败重试验证这个路径看起来慢但每一步都能暴露问题。直接三台一起上一旦出问题你很难判断是网络、模型、适配层还是 Claude Code 配置的问题。7.2 本地模型不是万能的什么时候该回云端本地部署最大的优势是数据不出内网其次是可用性和成本可控。但必须承认7B 和 14B 模型在复杂代码重构、跨文件理解、精准 API 调用这些场景里能力比云端最强模型还是差一截。我的建议是轻量任务比如解释报错、生成单函数、分析代码片段走本地 Ollama复杂任务比如大规模重构、理解整个项目结构、需要最新上下文语义的任务仍然保留云端 API 通道。Yeschef 这类适配层通常可以配置两套上游按照模型名或任务类型来回切。7.3 长期使用要提前准备的三件事监控脚本定时检查每个节点的/api/version和内存占用哪个节点挂了第一时间能看到统一日志Claude Code 日志、适配层日志、Ollama 日志放到同一个目录按日期切分模型版本管理在一个固定文件里记录每个节点拉取的模型名和版本升级模型后所有节点同步更新避免“节点 1 能跑、节点 2 不能跑”的情况最后留一个我自己的判断标准这套方案真正落地时最值得盯住的不是 627 tok/s 这个数字而是输入格式、资源占用和失败重试。工具链再顺底层模型或网络不稳都会让体验瞬间打回原形。先让单条任务在本地稳稳跑通再考虑多机并发这条路最不容易翻车。