吴前锐第一次听说 Claude Code 可以接本地大模型时，我的第一反应是：这真能跑吗？Claude Code 是 Anthropic 推出的命令行编程助手，默认连接 Claude 系列模型。把本地大模型接进去，相当于让一个为 Claude 设计的 agent 工作流，和另一个开源模型配合。听起来很酷，但也很像强行跨界。真正动手跑通之后，我的感受是：跨界做不成，往往不是因为“连不上”，而是因为没想清楚接入本地大模型到底要解决什么问题。
这篇文章不打算复刻“最强教程”这种说法，只讲我理解里最关键的部分：Claude Code 接入本地大模型后，工作流到底怎么跑、参数怎么配、哪些环节最容易断、什么任务适合做。如果你想用本地模型完成全栈开发，哪怕只写一个很小的工具，这篇文章也够你少走一段弯路。
先给结论：把 Claude Code 接到本地大模型，真正价值不是省 API 费用，而是把 AI 编程从“每次对话都依赖外部服务”，变成“在可控环境里执行可复用的开发流程”。代价是模型能力下降、调试成本上升。所以正确的用法不是“本地替代云端”，而是按任务分层。
1. 先想清楚：接入本地大模型，买的不是替代，是分层能力
1.1 Claude Code 本质上是一个 agent 工作流
很多人把 Claude Code 理解成一个“命令行里的聊天机器人”，这个理解会耽误事。它不是一个问答框，而是一个能读文件、改文件、执行命令、跑测试的 agent。你给它一个目标，它会自己规划步骤，调用工具，观察结果，再决定下一步做什么。
这套机制的核心叫“工具调用”（tool calling / function calling）。模型不是直接吐出最终代码，而是先输出“我要读取哪个文件”“我要执行哪条命令”“我要修改哪一段代码”这样的结构化指令，再由 Claude Code 这个外壳去执行。真正干活的是外壳，负责思考的是模型。
理解了这一点，你就明白：把本地大模型接进 Claude Code，并不是让它去模仿 Claude 的聊天风格，而是让它接管那个“思考中枢”。工作流本身还在，但大脑换掉了。
1.2 本地大模型补上的三块拼图
为什么要费劲接本地模型？直接原因有三类，对应的价值完全不同。
第一是隐私与合规。很多公司的源码不能传到第三方服务，或者项目处在内网隔离环境里。Claude Code 接本地模型后，代码、提示词、生成结果全在本机或内网流转，不经过外部服务，这一条对不少团队来说是刚需。
第二是成本结构。云端 API 按 token 计费，长任务、大项目、频繁试错时，花费会累积。本地推理虽然也要消耗电费和硬件折旧，但成本是可预估的，不会有“某一天打开账单被吓一跳”的情况。当然，这不是说本地更便宜，而是说它的成本结构更适合高频、大量、反复实验的场景。
第三是可控性。模型权重掌握在自己手里，断网也能用，折腾坏了可以重来，还能针对自己的项目做补充。相比之下，云端模型升级、下线、限流，都不是你能控制的。
1.3 这才是主判断
接本地模型，不等于“免费获得一个 Claude”。本地大模型的代码能力和工具调用稳定性，和顶尖云端模型之间有明显差距。真正合理的用法是分层：简单、敏感、离线任务交给本地；复杂重构、长链路推理、多文件强依赖任务，仍然用云端强模型。
判断一个任务能不能本地做，不要看“项目有多大”，要看“这个任务需要多少推理深度”。把 7B 级模型用在单文件脚本和简单接口上，体验会很顺；把它用在“重构整个微服务”上，基本必翻车。这不是模型好不好用的问题，是需求匹配的问题。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 接入前必须搞懂的三个底层概念
2.1 Anthropic API 兼容层与协议转换
Claude Code 默认通过 Anthropic Messages API 和模型对话。请求里会包含 system 提示词、历史消息、工具定义等，结构比较复杂。而本地推理服务，例如常见的 Ollama、LM Studio、vLLM 等，通常默认提供 OpenAI 风格的接口。
所以让 Claude Code 连上本地模型，有两条路：
一条是本地推理服务直接提供 Anthropic 兼容端点。这类服务收到 Claude Code 发来的 /v1/messages 请求后，内部翻译成自己能理解的格式，再返回结果。另一条是在中间加一层协议转换，把 Anthropic 格式的请求翻译成 OpenAI 格式，再把模型输出翻译回去。
协议转换层虽然是个“中间件”，但它非常关键。它决定了工具定义能不能完整传递、流式响应能不能正常解析、报错信息是不是可读。选型时不要只看能不能通，还要看它是否维护活跃、是否支持 tool calling、遇到长上下文时会不会丢字段。
2.2 工具调用决定体验上限
接本地大模型后，你很快就会碰到一个现象：模型本身的代码能力看起来还可以，但 Claude Code 里的体验非常差，模型不按套路出牌，不读文件，不执行命令，只会输出一大段“建议”。
根子往往就在工具调用上。agent 工作流要求模型输出结构化的工具调用指令，比如“读取文件 package.json”“执行命令 npm test”。如果模型在结构化输出上不稳定，或者根本没有针对工具调用数据做过训练，那整个工作流就会断掉。
这也是为什么有时候 7B 级模型反而比 30B 级模型体验更好。参数大小不代表一切，训练数据里是否包含高质量的函数调用样本，同样重要。所以选模型时，一定要找带 instruction 和 tool calling 能力的版本，而不是只看它代码生成得分多高。
2.3 上下文窗口是隐形瓶颈
Claude Code 会把项目目录结构、文件内容、历史对话、工具执行结果都塞进上下文。本地模型的上下文窗口如果太小，或者虽然标称很大，但一旦用满，推理速度和显存占用都会暴涨，就会出现“越用越慢”“模型忘掉前面的要求”这类问题。
上下文超限最典型的表现，是模型开始答非所问，甚至把旧文件内容和新需求混在一起。解决方案不是猛加显存，而是让任务更聚焦。在提示词里把目标写清楚，让 Claude Code 只读必要的文件，减少无关文件进入上下文，这些动作比换大模型更有效。
3. 最简环境搭建：先让 Claude Code 连上本地模型
3.1 环境准备与模型选型
先把硬条件列清楚。Claude Code 本身通常以 npm 包方式安装，需要 Node.js 环境。本地推理需要一台有足够显存和内存的机器。下面是一个比较保守的选型参考：
| 模型规模 | 显存参考（量化后） | 更适合的场景 |
|---|---|---|
| 7B 级 Q4 量化 | 8GB 左右 | 脚本编写、简单重构、代码解释、小接口开发 |
| 14B 级 Q4 量化 | 16GB 左右 | 更复杂的单文件任务、小型工具、短链路 agent 任务 |
| 32B 级 Q4 量化 | 24GB 以上 | 较复杂任务，但要先验证工具调用稳定性 |
| 70B 级以上 | 多卡或大显存 | 探索用，普通项目性价比不高 |
首次使用本地模型时，需要先下载模型权重，这个阶段需要联网。下载完成后，推理过程可以完全在内网或离线环境进行。
选模型的建议是：先别追求参数最大，先用一个 7B 或 14B 级、带工具调用能力的模型把整条链路跑通。链路通了，再根据实际效果决定是否升级模型。否则一上来就拉一个 32B 模型，不仅下载时间长，推理慢，出了问题你都不知道是模型问题还是配置问题。
3.2 启动本地推理服务
以常见的 Ollama 为例，先启动服务，再拉取并运行模型：
bash复制ollama serve
另一个终端里执行：
bash复制ollama run qwen2.5-coder:7b
运行后，本地会有一个推理服务监听在默认地址。可以用一个简单的请求验证它是否正常：
bash复制curl http://127.0.0.1:11434/api/tags
如果返回模型列表，说明服务已经就绪。
如果推理服务跑在另一台机器上，Claude Code 的 base_url 要指向那台机器的 IP 和端口，同时检查端口是否被防火墙拦截、服务是否监听在正确的网卡上。不要一上来就在本机调试远端服务，先把 curl 调通，再接入 Claude Code。
还有一个常见情况：推理服务只提供 OpenAI 兼容接口，不接受 Anthropic 格式请求。这时候需要在本地再起一个协议转换层。社区里这类工具不少，选择时关注一点：是否支持工具调用和流式响应。如果连这两个都不支持，后面所有 agent 任务都是空中楼阁。
3.3 配置 Claude Code 指向本地端点
最直接的配置方式是用环境变量：
bash复制export ANTHROPIC_BASE_URL="http://127.0.0.1:11434"
export ANTHROPIC_AUTH_TOKEN="local-dev-token"
export ANTHROPIC_MODEL="qwen2.5-coder:7b"
claude
这里有几个点要解释。ANTHROPIC_BASE_URL 就是让 Claude Code 把请求发到本地端点；ANTHROPIC_AUTH_TOKEN 可以填一个占位 token，因为本地服务通常不校验真实密钥，但字段必须存在；ANTHROPIC_MODEL 则是告诉 Claude Code 该用本地服务里的哪个模型名。
不同版本的 Claude Code 对配置项的识别可能不同。最稳妥的办法是先跑一遍 claude --help，或者查阅当前版本的文档，确认变量名。不要照搬一个配置就以为永远适用，工具的版本迭代很快。
配好之后，启动 Claude Code，输入一句最简单的指令：
请读取当前目录下的 package.json，并解释它的 dependencies
如果能正常读到文件并给出解释，说明 Claude Code 已经和本地模型通上了。这时候再往下走，进入项目级配置。
4. 项目级配置：把参数固化到 settings.json
4.1 两种配置方式怎么分工
环境变量的特点是灵活，适合临时切换模型、临时调试。但每次开终端都要 export 一遍，很烦，而且容易写错。更稳妥的方式是把配置写进 settings.json。
Claude Code 支持用户级配置和项目级配置。用户级一般在 ~/.claude/settings.json，对所有项目生效；项目级在 .claude/settings.json，会跟着仓库走，适合团队统一。
我的建议是：用户级放通用偏好，项目级放和这个项目绑定的配置，比如本地模型地址、允许执行的命令白名单。提交代码仓库时注意，不要把真实密钥写进项目级配置。可以提交占位符，然后用环境变量注入真实值。
4.2 一个可以照着改的配置模板
下面这个示例结构，展示了常见项目级配置会长什么样：
json复制{
"env": {
"ANTHROPIC_BASE_URL": "http://127.0.0.1:11434",
"ANTHROPIC_AUTH_TOKEN": "local-dev-token",
"ANTHROPIC_MODEL": "qwen2.5-coder:7b"
},
"permissions": {
"allow": [
"Read",
"Glob",
"Edit",
"Bash(npm run *)",
"Bash(node *)"
],
"deny": [
"Bash(rm *)",
"Bash(git push *)"
]
}
}
permissions 这块很容易被忽略，但它非常重要。本地模型生成命令时，稳定性不如云端强模型，更容易出现你不希望执行的命令。用 allow 白名单明确放行哪些工具，用 deny 黑名单挡住高风险操作，能减少不少意外。
注意：不要把真实密钥写进会被提交到仓库的配置文件里。先用占位符跑通，再用环境变量注入真实值。这个习惯能避免很多泄露事故。
4.3 优先调整这四个参数
配置项很多，新手上路不需要全改。先盯住四个：
| 参数 | 作用 | 常见错误 |
|---|---|---|
| ANTHROPIC_BASE_URL | 请求发往哪个端点 | 多写了 /v1/messages 后缀，导致路径重复 |
| ANTHROPIC_MODEL | 使用哪个模型 | 模型名和本地服务里的名字不完全一致 |
| ANTHROPIC_AUTH_TOKEN | 鉴权占位 | 不填，请求直接被拒绝 |
| 最大输出 token | 限制单次回复长度 | 设太大导致本地模型超时或显存不足 |
最后一个参数尤其值得注意。Claude Code 默认允许模型输出较长内容，但本地模型如果显存不够，或者上下文已经很长，输出 token 设得太大，会出现生成到一半就卡住的情况。可以先调低，跑通了再逐步放大。
5. 跑一个全栈小任务，看链路是否完整
5.1 给一个边界清楚的任务
接入成功后，别急着让它“帮我写个全栈项目”。本地模型的 agent 能力还撑不起这种开放式需求。先跑一个边界清楚的小任务，验证整条链路是否完整。
比如这样一个任务：
在 /tmp/todo-demo 目录下，用 Node.js 自带 http 模块写一个小服务。提供 GET /api/todos 接口，返回数组；再提供一个静态 HTML 页面，用 fetch 拉取接口并展示列表。不要引入额外依赖，不要写数据库。
这个任务的好处是：只有两个文件，逻辑简单，可验证。就算模型生成得不够优雅，你也能一眼看出问题在哪里。它不考验架构能力，只考验 Claude Code 读文件、创建文件、执行命令、修改代码这条 agent 链路能不能走通。
有了明确边界，才谈得上判断模型表现。否则任务发散，本地模型大概率会给你一堆没有上下文关系的代码片段。
5.2 观察模型在链路里的真实表现
任务执行过程中，不要只盯着最终代码，要观察整个过程。
首先看它会不会主动读取目录结构。如果它直接开始凭空写代码，说明工具调用链路有问题，或者上下文里根本没有项目信息。然后看它写完代码后会不会自己执行命令验证。一个合格的 agent 工作流，应该在写完服务后启动服务、请求接口、确认返回结果。如果模型只写代码不验证，那它本质上还是在“生成文本”，不是在“干活”。
再看报错后的反应。本地模型接进来之后，最常见的现象是：第一次启动失败，然后它直接重新生成一版代码，而不是先读取报错信息，分析原因，再做小修改。这个区别决定了它能不能完成稍微复杂一点的任务。
5.3 输出检查清单
跑完之后，按这个清单检查，不要只看“代码没报错”：
- 文件是否真的存在，目录结构是否符合要求
- 服务能否启动，端口有没有被占用
- 接口返回的 JSON 是否符合预期格式
- 前端页面能不能正常拉取数据并渲染
- 生成的代码里有没有硬编码本地路径
- 有没有把端口绑定到 0.0.0.0 这种不适合默认安全的写法
- 本地模型是否误删或覆盖了你原来的文件
如果这些检查项都通过，说明 Claude Code + 本地模型的最小可用链路已经成立。接下来再逐步放大任务规模。
6. 真正常见的故障链路与排查顺序
6.1 连不上或鉴权失败
接本地模型时，大概率会碰到几类问题。第一类是“连不上”，表现为请求超时、连接拒绝。先查服务有没有启动，再查 base_url 的端口对不对。如果服务在远端，还要确认网络通不通、防火墙放没放行。
第二类是“鉴权失败”。即使本地服务不校验真实密钥，ANTHROPIC_AUTH_TOKEN 或 ANTHROPIC_API_KEY 也要填一个值。空着不填，Claude Code 可能直接拒绝发起请求。
如果请求发出去，本地服务返回 404，先检查是不是 base_url 多写了一层路径。有些配置会把 /v1/messages 也写进去，导致实际请求变成 /v1/messages/v1/messages，自然会 404。
6.2 请求通了但模型行为异常
如果请求能通，但模型表现很奇怪，问题就复杂一些。常见的现象包括：不调用工具、回复重复内容、生成乱码、答非所问。
排查顺序是：先确认模型是否支持工具调用，再看模型参数量和量化等级是不是太弱，最后检查上下文有没有被截断。不要一上来就换模型，那很容易变成反复试错。
| 现象 | 先查什么 | 可能原因 |
|---|---|---|
| 返回 401 / 403 | 鉴权字段、端点 | ANTHROPIC_AUTH_TOKEN / API_KEY 缺失或错误 |
| 连接被拒绝 | 服务状态、端口 | 本地推理服务没启动，或 base_url 写错 |
| 返回 404 | 端点路径 | base_url 多写了 /v1/messages 后缀 |
| 回复乱码或重复 | 模型能力、量化等级 | 模型过小、量化等级过低 |
| 不调用工具 | 模型是否支持 tool calling | 模型不支持工具调用，或提示词被截断 |
| 速度越来越慢 | 上下文长度、显存 | 长上下文导致 KV Cache 激增，显存不足 |
6.3 上下文截断、速度慢、卡死
第三个常见故障是“变慢”和“卡死”。这类问题最容易被误判成硬件不行，其实很多时候是上下文管理出了问题。
Claude Code 会把项目文件塞进上下文，文件越多、越大，模型处理起来越慢。如果你用的是 7B 模型，上下文一长，显存容易被打满，就会出现生成到一半卡住的情况。
遇到这种问题，先看 Claude Code 的详细日志。通常在调试模式下，能看到请求里到底传了多少 token、上下文占用情况、哪一步耗时最长。不要凭感觉猜，日志比直觉可靠。
正确排查顺序是：先看现象，再查输入和配置，再看服务日志，最后判断模型能力边界。不要一上来就换模型，那样只是在随机试错。
7. 适用边界：什么活交给本地模型，什么活别硬上
7.1 适合的场景
接入本地模型后，一定要接受一个事实：它不是万能的，但它非常适合特定范围的任务。
第一个典型场景是内网或离线开发。代码不能出内网，又想要 AI 编程助手，本地模型几乎是唯一选择。第二个场景是敏感数据相关的代码处理，比如日志脱敏脚本、数据转换工具，这些代码一旦传到外部服务，风险太高。第三个场景是高频小任务，比如写测试、解释代码、修一个函数、生成脚本。这种任务推理深度不高，本地模型完全能胜任。
还有一个非常适合的场景是学习。本地模型可以让你反复试错而不担心费用，能更直观地理解 agent 工作流到底是怎么运转的。对开发者理解 AI 编程工具的内部机制，这比花钱调云端 API 更高效。
7.2 不适合的场景
有些场景不要硬上。大型重构是第一个。需要同时理解十几个文件、梳理调用关系、保持行为不变，这种任务对上下文和推理深度的要求极高，本地模型很容易改一处崩三处。
跨多文件的复杂依赖也不适合。本地模型经常在两个文件之间建立错误的联系，或者遗漏某个关键引用。前端视觉还原同样不适合，界面细节涉及大量 trial and error，本地模型在审美和一致性上明显吃力。
依赖最新第三方 SDK 版本的任务也要慎用。本地模型的训练数据可能滞后，容易出现“用了一个已经不存在的 API”或者版本号凭空猜测。它不是懒，是真的没有见过最新资料。
7.3 判断任务是否能本地做的三个问题
我平时判断一个任务能不能交给本地模型，会问三个问题：
- 这个任务需要几步推理？
- 是否涉及多个文件之间的依赖？
- 出错之后，模型能不能从报错信息里自己恢复？
如果三个问题的答案都是“简单”，可以放心交给本地模型。只要有一个答案是“复杂”，就要认真考虑换强模型，或者把任务拆小。
这个判断标准比“看模型参数”更准。因为参数大小不完全等于体验，任务类型匹配才是决定因素。
8. 长期工作流：从一次跑通向工程化固化
8.1 单次跑通不算完
很多项目死在“demo 跑通”这一步。 Claude Code 接上本地模型后，单次任务能跑通，只能说链路没有断。距离稳定使用，还差很多工程细节。
常见的问题包括：服务重启后配置丢了吗？模型版本升级后行为变了吗？权限白名单足够安全吗？日志能追溯上一次任务到底做了什么吗？这些才是长期使用的隐性成本。如果只把它当聊天窗口用，这些都不用管；但如果要放进真实工作流，每一样都是必须补的短板。
8.2 需要补的四样东西
第一是日志。 Claude Code 的任务过程要能回溯，至少要能看到它执行了哪些命令、改过哪些文件。出问题的时候，日志能告诉你它是怎么一步步走到错误状态的。
第二是权限。权限白名单要从紧。本地模型的指令稳定性不如云端强模型，你不想看到它顺手执行一条你没有预期的命令。
第三是版本管理。AI 生成代码要纳入 Git 管理，每一次改动都要能 diff、能回滚。不要因为它来自 AI 就放松 code review 标准。
第四是验证回归。每次任务完成后，要有明确的验证方法。接口能不能跑、测试能不能过，这些要固化成脚本，而不是靠肉眼扫一遍就放行。
8.3 一个可复用的落地框架
把一个 AI 编程工具接入工作流，我习惯用五步渐进法：
第一步，选一个最小任务，跑通完整链路。目的不是产出多少代码，而是确认输入、输出、日志、权限都正常。
第二步，做质量检查和修正。这里要检查的不只是代码能否运行，还包括它是否满足需求、是否引入安全隐患、是否符合项目规范。
第三步，把配置固化成文件。将模型端点、模型名、权限白名单写进项目级配置，让整个团队用同一套规则。
第四步，补日志和权限。明确记录每次任务执行了什么，同时锁死高风险操作。
第五步，再小批量放大任务。从一个文件到一个模块，从一个接口到一组接口，每一步都确认稳定后再往前走。
这个框架不只适用于 Claude Code 加本地模型，换成其他 AI 编程工具也一样适用。
回到开头的问题：把 Claude Code 接上本地大模型，值得折腾吗？我的答案是，取决于你手里是什么任务。如果是内网环境、敏感代码、简单脚本或学习 agent 工作机制，非常值得；如果是一上来就指望 7B 模型帮你重构整个微服务，那大概率会失望。
先跑一个最小任务，把它跑通，再扩大边界。这个顺序，比换任何模型都重要。