很多开发者第一次接触 Claude Code 时,都会被它的执行能力震撼:它能自己读工程目录、修改多个文件、执行终端命令、跑测试,甚至在失败后自己调整策略重试。但随后就会遇到一个现实的瓶颈——API 按 token 计费,一个稍微复杂的任务就可能消耗几十万 token,费用并不便宜;更麻烦的是,代码作为敏感资产要上传到云端,很多公司对此有顾虑。
这篇文章要解决的问题,就是如何把 Claude Code 的前端交互能力,和本地大模型的私密、免费、可控性结合起来。读完你会得到一个完整可用的全栈开发工作流:本地模型负责代码生成和修改,Claude Code 负责理解意图、调度工具、管理上下文。我会从模型选型、环境配置、接口对接、完整实战到问题排查全部跑一遍,不走弯路。
1. 为什么需要 Claude Code + 本地大模型
Claude Code 是 Anthropic 推出的终端编程智能体工具。它不是一个简单的代码补全插件,而是一个能主动完成开发任务的 Agent。你给它一句自然语言指令,比如“把登录接口加上验证码校验”,它会在你的项目目录里自动检索相关文件,理解现有代码结构,生成修改方案,调用文件编辑工具落地修改,然后执行测试命令进行验证。
这种工作方式在当前的大模型应用形态里,属于最接近于“真实程序员助手”的那一类。
但它有一个核心问题:默认使用 Anthropic 的云端模型。这就带来了三个实际困扰:
- 成本。重度使用场景下,API 费用累计很快。
- 数据安全。第三方 SaaS 服务对代码的合规要求比较高,很多企业不允许源代码上传到公有云。
- 网络依赖。API 服务的稳定性和可用性不完全由开发者掌控。
本地大模型正好解决了这三个问题。通过 Ollama、LM Studio 这类工具,可以在自己的电脑上运行开源模型(比如 Qwen2.5-Coder、DeepSeek-Coder 等),完全离线运行。
Claude Code 本身支持通过环境变量指定 API 地址,这就意味着——我们可以把 Claude Code 的模型后端,指向本地模型服务。这就是“Claude Code + 本地大模型”方案的原理基础。
1.1 这套方案实际能干什么
从实践看,本地模型接入 Claude Code 后,主要能完成以下工作:
- 跨文件代码重构:让模型根据指令修改多个相关文件,保持接口一致性。
- Bug 修复与调试:给出报错日志,让模型定位问题并修改代码。
- 测试用例生成:为已有模块补充单元测试。
- 代码解释与文档生成:对复杂模块生成说明文档。
- 全栈小项目生成:从一个页面到完整应用,由模型逐步生成。
相比云端模型,本地模型在复杂推理能力上确实存在差距,但在代码补全、修改、解释这类结构性任务上,开源模型已经达到了相当可用的水平。尤其是 14B 以上的模型,配合较强的量化版本,在多数日常开发任务里表现足够好。
1.2 适合哪些开发者
这套方案特别适合以下几类人:
- 有隐私诉求的开发者,不希望代码上传到外部服务器。
- 重度使用编程智能体但预算有限的个人开发者。
- 需要使用开源模型进行定制训练或微调的团队。
- 对网络环境有要求的开发场景,比如内网开发。
如果你追求的是最强代码生成能力,且预算充足、不在意数据上云,那么直接使用云端模型仍然是更优选择。这篇文章讲的是本地化方案,要先把预期管理清楚——它不是替代顶级云端模型,而是提供一个高性价比、高可控性的替代路径。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 本地大模型核心概念与模型选型
在开始配置之前,必须先理解几个关键概念。这些概念决定你后续能不能顺利跑通。
2.1 量化:让大模型在消费级硬件上运行的秘密
一个 7B 参数的大模型,以 FP16 精度存储,权重文件约 14GB。如果你的显卡只有 8GB 显存,直接加载会内存溢出。这时就需要量化。
量化是把模型权重从高精度(如 FP16)压缩到低精度(如 INT4、INT8)的过程。效果就是模型文件变小,显存占用降低,推理速度提升,代价是生成质量略有下降。
常见的量化格式包括 GGUF 格式的 Q4_K_M、Q5_K_M、Q8_0 等。其中 Q4_K_M 是性能和质量的平衡点,Q8_0 质量更好但体积更大。实践里,7B/8B 模型选择 Q8_0,14B 模型选择 Q5_K_M 或 Q4_K_M,是比较稳妥的方案。
这里容易踩的一个坑是:购买显卡或选择模型时,只看参数数量而不看显存容量。比如有人说“我要跑 32B 模型”,结果显卡只有 8GB 显存,这是跑不起来的。模型参数、量化等级、显存大小之间的关系,决定了你最终能跑多大的模型。
可以按一个简化公式估算显存占用:
显存占用约等于 = 模型参数量(B)× 量化位数(bit) / 8 × 1.2(推理开销)
举例:7B 模型用 Q8 量化:
7 × 8 / 8 × 1.2 ≈ 8.4GB
这意味着 8GB 显存跑 Q8 的 7B 模型有点紧张,但 Q4 量化只要约 4.2GB,就很充裕。
如果显存不足,就要考虑用 CPU 模式运行,但生成速度会明显下降。
2.2 模型选型思路
接入 Claude Code 的本地模型,需要具备指令跟随能力和工具调用能力。工具调用是指模型能按特定格式输出结构化内容,让 Claude Code 解析并执行下一步动作。如果模型不具备这个能力,Claude Code 就无法完成“调用工具→观察结果→再决策”的循环。
目前社区里口碑较好的选择:
| 模型 | 参数量 | 上下文支持 | 特点 |
|---|---|---|---|
| Qwen2.5-Coder-7B | 7B | 128K | 中文支持好,代码能力强 |
| Qwen2.5-Coder-14B | 14B | 128K | 综合能力明显优于 7B |
| DeepSeek-Coder-V2-Lite | 16B | 128K | 擅长代码生成 |
| Qwen2.5-14B | 14B | 128K | 通用对话能力,兼顾代码 |
从实际体验看,Qwen2.5-Coder-7B 在内存 16GB 以上的机器上可以流畅运行,适合快速尝试流程;如果追求更好的代码质量,Qwen2.5-Coder-14B 是更推荐的选择。32B 以上的模型需要 24GB 以上显存,普通开发者可以先不考虑。
一个常见误区是追求大参数模型。大模型确实更聪明,但推理速度也明显下降。Claude Code 的工作模式是多轮交互:模型要思考→调用工具→查看结果→再思考。如果每次推理要等十几秒,整体使用体验会非常差。在本地部署场景里,流畅度比绝对能力更重要。
第一次尝试的建议是:从 7B 或 8B 模型开始,跑通流程后再升级到 14B。
2.3 上下文长度的意义
模型上下文长度决定了一次对话中能容纳多少信息。Claude Code 发送给模型的内容,包含用户指令、相关代码片段、文件内容、工具执行输出的日志。在一个大型代码仓库里,一次修改任务可能涉及非常多信息。
如果上下文太小,模型会“遗忘”前面的内容,导致修改不完整。所以至少选择 32K 以上上下文窗口的模型。Qwen2.5-Coder 系列支持的 128K 上下文,在本场景下非常实用。
需要注意的是,本地推理时,上下文越长,占用的显存和计算量也越大。实际项目中,Claude Code 默认也不会一次性把整个仓库塞进去,而是自动选择相关文件,这本身就是它的核心设计之一。
3. 环境准备与硬件评估
这套方案对你的电脑配置有要求。先把环境准备好,后面才不容易出问题。
3.1 确定你的硬件水平
在安装任何软件之前,先做一次硬件评估。不同配置能跑的模型完全不同:
| 硬件级别 | 建议模型 | 说明 |
|---|---|---|
| 8GB 显存 GPU | 7B Q4 量化 | 起步配置,够用但不宽裕 |
| 12GB-16GB 显存 GPU | 7B Q8 或 14B Q4 | 比较舒适的区间 |
| 24GB 显存 GPU | 32B Q4 或 14B Q8 | 适合重度使用 |
| 纯 CPU 32GB 内存 | 7B Q4 | 能跑但速度较慢 |
用户需要检查三项配置:
- 显卡显存:决定能否用 GPU 加速和最多能跑多大的模型。
- 内存容量:模型加载时不仅占显存,也会占用部分内存做缓存。
- 磁盘空间:模型文件很大,7B 模型约 5-8GB,14B 模型约 10-16GB。
在 Windows 上可以打开任务管理器查看硬件信息,在 Linux 上可以用 free -h 查看内存,用 nvidia-smi 查看 GPU 信息。
3.2 安装 Ollama
Ollama 是目前运行本地大模型的主流工具,优点是安装简单、命令简洁、内置模型管理能力,并且提供了 OpenAI 兼容的 API 接口——这正是后续与 Claude Code 对接的关键。
访问 Ollama 官网下载对应系统的安装包。
- Windows 用户下载 exe 安装包,安装后命令行里直接使用
ollama命令。 - macOS 用户同样是下载安装包。
- Linux 用户需要执行安装脚本。
Ollama 安装完成后,可以通过一个命令下载并运行模型,以 Qwen2.5-Coder-7B 为例:
bash复制ollama pull qwen2.5-coder:7b
ollama run qwen2.5-coder:7b
第一条命令下载模型,第二条命令进入交互式对话。下载可能需要几分钟到几十分钟,取决于网络状况。
安装 Laravel,这是 PHP 最流行的框架之一,它提供了清晰的目录结构、内置的 Eloquent ORM 和 Artisan 命令行工具。
在 Ubuntu 系统上先更新包索引,然后安装 PHP 扩展和 Composer:
bash复制sudo apt update
sudo apt install php-cli php-mbstring php-xml php-zip php-mysql php-curl unzip git -y
3.3 安装 Claude Code
Claude Code 以 npm 包的形式发布。安装命令很简单:
bash复制npm install -g @anthropic-ai/claude-code
安装完成后执行 claude --version 确认安装成功。
Claude Code 默认需要登录 Anthropic 账号。但在我们这套本地化方案中,可以通过环境变量直接指向本地 API,这需要你有一个 Anthropic 的 API Key 作为基础凭证——这个过程通常只需要几秒钟。
这里提醒一下:如果你没有 Anthropic 账号,也可以跳过登录阶段,通过 config.json 配置文件来使用非官方模型服务。但这种方式依赖 Claude Code 的命令行参数和环境变量,本教程为了通用性,仍然从官方安装路径讲起。
3.4 确认组件版本
不同版本的 Claude Code 和 Ollama 在某些接口行为上可能有差异。建议安装后先确认版本:
bash复制claude --version
ollama --version
如果 Claude Code 版本过旧,可能不支持某些环境变量配置,建议及时更新。
4. Claude Code 对接本地模型
Claude Code 支持通过 ANTHROPIC_BASE_URL 环境变量,把所有 API 请求转发到自定义地址。这就是接入本地模型的核心机制。
4.1 原理介绍
Claude Code 本身的架构是:终端交互界面 → Agent 调度层 → API 客户端 → 模型服务。
默认情况下,API 客户端请求的是 Anthropic 官方地址 https://api.anthropic.com。通过修改环境变量,可以让它请求任何实现了 Anthropic API 兼容协议的服务地址。
Ollama 提供的是 OpenAI 风格的 API,和 Anthropic API 协议不同。因此我们还需要一个协议转换层。目前常用的方案有两个:
- 等模型提供 Anthropic 兼容接口:某些模型服务器已经实现了
/v1/messages接口,只要把 BASE_URL 指过去即可。 - 使用 LiteLLM 代理:LiteLLM 是一个统一的大模型网关服务,可以把 OpenAI 协议转换为 Anthropic 协议,同时接入 Ollama。
从社区实践反馈看,Ollama Library 的 Claude 支持程度一直在改进。实际上,Ollama 官方文档里已经提出了对 Anthropic API 兼容性的支持方案,但使用人数最多的还属 LiteLLM 这条路线。
考虑到这是一个保姆级教程,我建议采用 LiteLLM 方案。它在 Windows、macOS、Linux 上都能跑,而且一条命令就能启动代理服务。
4.2 设计一个最小可用的接法
下面的架构图描述了一条本地化链路:
text复制Claude Code → LiteLLM 代理 → Ollama API → 本地模型
Claude Code 把 Anthropic 格式的请求发给 LiteLLM,LiteLLM 把格式转换为 OpenAI 格式发给 Ollama,Ollama 最终调用本地模型推理,然后把结果原路返回。
4.3 安装和配置 LiteLLM
LiteLLM 需要通过 Python 安装。先确保你的机器上已经有 Python 3.10 以上版本:
bash复制python --version
然后安装 LiteLLM:
bash复制pip install litellm
安装完成后,你可以先直接测试一下能否通过 Ollama 接口调用模型:
bash复制litellm --model ollama_chat/qwen2.5-coder:7b --port 8080
这个命令会启动一个本地代理服务,监听 8080 端口,模型指向 Ollama 里的 qwen2.5-coder:7b。
但注意,Claude Code 默认请求的 API 路径是 /v1/messages。而上面的启动方式默认不保证这个路径可用,后面需要正确配置。
更稳妥的配置方式是写一个配置文件,指定接口模型映射。创建一个 config.yaml 文件:
yaml复制model_list:
- model: anthropic/claude-code-qwen
litellm_params:
model: ollama_chat/qwen2.5-coder:7b
api_base: http://localhost:11434
然后启动:
bash复制litellm --config config.yaml --port 8080
这样,LiteLLM 就在 http://localhost:8080 上提供了一个入口,并明确映射到了 Ollama 的 qwen2.5-coder 模型。
如果你的本机 Ollama 不是默认端口,需要把 api_base 改成实际地址。
4.4 配置 Claude Code 环境变量
Claude Code 通过环境变量读取 API 地址和 Key。在 Windows PowerShell 里,可以这样设置:
powershell复制$env:ANTHROPIC_BASE_URL="http://localhost:8080"
$env:ANTHROPIC_API_KEY="local-test-key"
在 macOS/Linux bash 里:
bash复制export ANTHROPIC_BASE_URL="http://localhost:8080"
export ANTHROPIC_API_KEY="local-test-key"
这里的 API Key 可以是任意非空字符串,因为本地代理不校验真实 Key。但 Claude Code 要求必须有这个变量,否则会报错。
设置完环境变量后,在项目目录里启动 Claude Code:
bash复制claude
如果一切正常,Claude Code 会启动终端交互界面。此时你发出的指令会被转发到本地模型。
这里真正容易踩坑的地方是:有些开发者配置了环境变量,但没有在新终端窗口里启动 Claude Code。环境变量只对当前终端会话生效,如果你修改了变量,必须重启终端再执行 claude。
需要注意的一个点是,Claude Code 需要你给它足够的文件读取和命令执行权限。首次启动时会要求确认权限策略,如果选择限制模式,很多工具调用会被拦截。既然是本地开发环境,可以直接选择允许权限。
5. 基于 LM Studio 的备选方案
除了 Ollama 加 LiteLLM 的组合,还有一个备选方案:LM Studio。
LM Studio 是一个带图形界面的本地模型管理工具,内置了本地 API 服务器,也支持 OpenAI 兼容接口。对不熟悉命令行的开发者来说,这个方案更直观。
5.1 安装和配置 LM Studio
从 LM Studio 官网下载安装包,安装后:
- 在应用内搜索并下载模型,比如
qwen2.5-coder-7b-instruct。 - 模型下载完成后,点击左边栏的 “Local Server” 或类似入口。
- 启动本地服务器,默认端口是
1234。
LM Studio 的本地服务同样支持 OpenAI 兼容协议。要让 Claude Code 接入它,仍需一个协议转换层,但好处是 LM Studio 自带服务,不用额外起 Ollama。
5.2 修改 LiteLLM 配置映射
如果使用 LM Studio,配置文件里模型地址需要指向 LM Studio 的 API:
yaml复制model_list:
- model: anthropic/claude-code-qwen
litellm_params:
model: openai/qwen2.5-coder-7b-instruct
api_base: http://localhost:1234/v1
这里 openai/ 前缀告诉 LiteLLM 这是一个 OpenAI 兼容接口。
两种方案各有优劣:Ollama 命令行高效、资源占用更小;LM Studio 有图形界面,适合图形化操作习惯的开发者。从纯稳定性的角度来说,Ollama 方案在自动化脚本和 CI/CD 场景里更灵活。
6. 完整实战:全栈开发一个待办事项应用
下面进入本文的高潮部分。我们用 Claude Code + 本地大模型,从零开发一个全栈待办事项应用。技术栈使用 Node.js + Express + SQLite + React,前后端分离。
这个实战的目的是展示 Claude Code 在真实项目中的完整工作流:理解需求、拆解任务、生成代码、执行命令、验证结果。
6.1 初始化项目
先创建项目目录并初始化 Node.js 环境:
bash复制mkdir claude-todo-app
cd claude-todo-app
npm init -y
此时项目里只有一个 package.json 文件。接下来打开 Claude Code:
bash复制claude
在 Claude Code 的交互界面里,输入以下指令:
text复制这是一个全栈待办事项应用项目。请完成以下工作:
1. 用 Express 创建后端 API,提供待办事项的增删改查功能,数据存储使用 SQLite。
2. 用 React 创建前端页面,展示待办列表,支持添加、完成、删除操作。
3. 后端端口固定为 3001,前端开发服务器端口为 5173(Vite 默认)。
4. 后端要配置 CORS 支持,允许前端跨域请求。
5. 项目结构要清晰,前后端代码分别放在 server 和 client 目录。
6.2 观察 Claude Code 的执行过程
提交指令后,你会看到 Claude Code 开始自主工作,大致流程是:
- 读取当前目录结构,确认项目状态。
- 调用 Bash 工具安装后端依赖(express、sqlite3、cors 等)。
- 创建
server/index.js文件,写入 Express 服务代码。 - 创建
server/database.js文件,初始化 SQLite 数据库。 - 安装前端依赖(vite、react、react-dom 等)。
- 创建
client/src/App.jsx、client/src/App.css等文件。 - 在合适的节点执行启动命令,验证服务是否正常运行。
这个过程会持续几分钟,取决于本地模型的推理速度和任务复杂度。你不需要干预每一步,但在关键节点(比如验证 API 是否启动成功)可以观察它的输出。
6.3 生成的核心代码
即使没有手动写代码,你也可以随时让 Claude Code 展示生成的代码。让它继续执行:
text复制请展示 server/index.js 的完整内容。
如果前端页面不够美观,可以要求:
text复制请为待办事项页面添加一个现代化的 CSS 样式,包括卡片布局、圆角按钮、悬停效果。
如果某个步骤需要精确控制,可以手动干预:
text复制请停止当前操作。把数据库字段从 completed 改为 finished,注意同步修改前端代码。
这种自然语言的交互方式,就是 Claude Code 的核心价值:你控制方向,它负责实现细节。
6.4 配套的启动脚本
为了让项目易于启动,可以让 Claude Code 生成一个统一的启动脚本:
bash复制#!/bin/bash
# 启动后端
cd server && node index.js &
# 启动前端
cd client && npm run dev &
在 Claude Code 中输入:
text复制请在项目根目录创建一个 start.sh,内容为:先启动后端服务,再启动前端开发服务器,两条命令都需要后台运行。
它会自动创建并赋予权限。
6.5 手动补充一个手动创建的测试文件
即使有 Agent 辅助,一个优秀的开发者仍然需要写关键测试。在项目里手动创建一个后端测试脚本,用来验证核心 API:
js复制// 文件路径:server/test-api.js
const http = require('http');
function request(method, path, data) {
return new Promise((resolve, reject) => {
const body = data ? JSON.stringify(data) : null;
const options = {
hostname: 'localhost',
port: 3001,
path,
method,
headers: body ? {
'Content-Type': 'application/json',
'Content-Length': Buffer.byteLength(body)
} : {}
};
const req = http.request(options, res => {
let chunks = '';
res.on('data', chunk => chunks += chunk);
res.on('end', () => resolve({ status: res.statusCode, body: chunks }));
});
req.on('error', reject);
if (body) req.write(body);
req.end();
});
}
(async () => {
const create = await request('POST', '/api/todos', { title: '学习 Claude Code' });
console.log('创建:', create.status, create.body);
const list = await request('GET', '/api/todos');
console.log('列表:', list.status, list.body);
const id = JSON.parse(list.body)[0]?.id;
if (id) {
const update = await request('PUT', `/api/todos/${id}`, { completed: true });
console.log('更新:', update.status, update.body);
}
})();
运行验证:
bash复制cd server
node test-api.js
7. 运行结果与验证方法
7.1 启动后端并验证 API
首先启动后端服务:
bash复制cd server
node index.js
正常输出会显示类似内容:
text复制Server running at http://localhost:3001
SQLite database connected
然后另开一个终端,验证接口是否正常:
bash复制curl http://localhost:3001/api/todos
预期输出是一个 JSON 数组,例如:
json复制[]
这说明数据库连接正常,接口可访问。如果这个接口都失败,就不要往后端排错,先回到环境配置检查。
7.2 启动前端并验证页面
启动前端:
bash复制cd client
npm run dev
浏览器访问 http://localhost:5173,应该能看到待办事项页面,能够在输入框里添加待办事项,点击复选框切换完成状态,点击删除按钮移除项目。
到这一步,说明整个全栈链路已经打通,Claude Code + 本地大模型完成了一个全栈应用的开发闭环。
7.3 如何判断 Claude Code 工作是否正常
很多用户最大的困惑是:模型在跑,但结果对不对?
可以按以下顺序快速判断:
- 执行
claude后,输入简单指令“用 node 输出 hello world”,看是否有正确输出。 - 如果连这种简单任务都做不到,说明模型接入有问题,不是功能问题。
- 在 Claude Code 里使用
/status命令,查看当前上下文和请求状态。 - 在 LiteLLM 日志窗口查看是否有请求记录。
如果在交互中没有出现任何输出,先检查 LiteLLM 代理是否正常启动。执行:
bash复制curl http://localhost:8080/v1/models
如果这个接口返回空或报错,说明代理没有正确映射到 Ollama 模型。
8. 常见问题与排查思路
本地化方案涉及组件多,每个环节都可能出问题。下面整理几个最高频的问题。
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
| Claude Code 报 404 | ANTHROPIC_BASE_URL 指向的 LiteLLM 不支持 /v1/messages 路径 | 检查 LiteLLM 启动日志 | 确认 LiteLLM 版本支持 Anthropic API 兼容路径 |
| Claude Code 报模型不存在 | Ollama 中没有该模型,或模型名称写错 | ollama list 查看已下载模型 |
使用 ollama pull 模型名 拉取对应模型 |
| 启动 claude 后无任何响应 | 环境变量未生效或模型推理太慢 | 检查终端环境变量,观察 LiteLLM 日志 | 重启终端再启动 claude,或换更小模型 |
| 生成的代码质量不理想 | 模型太小或量化太激进 | 检查模型参数和量化等级 | 升级到 14B 模型,或改用 Q8 量化 |
| 工具调用反复失败 | 模型的工具调用能力不足 | 观察 Claude Code 输出中的重复尝试 | 更换支持 tool use 的模型,或降低任务复杂度 |
| 显存不足导致崩溃 | 模型太大,显存装不下 | 运行 nvidia-smi 查看显存占用 |
换更小的量化版本,或者使用 CPU 推理 |
| 前后端跨域报错 | 后端未配置 CORS | 检查服务器响应头 | 在后端添加 cors 中间件 |
8.1 一个隐藏最深的坑:模型输出格式不稳定
这是本方案中最隐蔽的问题。Claude Code 这类 Agent 工具要求模型以严格的格式输出工具调用指令,比如 function_call 或特定的 XML 标签。如果模型在输出中多加了一个字符,或者格式不标准,Claude Code 会无法解析工具调用,导致任务中断。
解决思路是:
- 优先选择专门训练过工具调用能力的模型,如 Qwen2.5 系列。
- 如果模型能力不够,可以从提示词入手,明确告诉模型“只输出 JSON,不要包含任何解释”。
- 如果问题频繁,降低任务复杂度,拆成更细的步骤让 Claude Code 逐步执行。
从实践体验看,Qwen2.5-Coder 系列在指令跟随上的表现相对稳定,推荐优先尝试。如果用的模型一直格式错乱,果断换模型比反复调提示词更省时间。
9. 最佳实践与工程建议
在本地化方案跑通后,容错空间就大了不少——不用再担心 token 成本,可以放心尝试各种操作。但工程上的习惯仍然要养成。
9.1 用 Class 文件而不是纯 prompt 管理复杂任务
Claude Code 支持使用 CLAUDE.md 文件来定义项目的全局指令。比如在项目根目录创建一个 CLAUDE.md:
markdown复制# 项目规范
- 后端代码位于 server 目录,数据库使用 SQLite
- 前端代码位于 client 目录,使用 React + Vite
- API 路由统一前缀 /api/
- 代码使用英文命名,注释可以使用中文
- 生成代码后必须执行相关测试
每次启动 Claude Code 时,它会自动加载这个文件里的规范。这相当于给 Agent 立了规矩,能显著提高生成代码的确定性。
9.2 善用子代理模式
对于复杂任务,Claude Code + 本地模型可以按子代理的方式协作。比如先让一个会话生成项目框架,再开一个新会话补全某个模块,最后合并检查。这种做法能减少上下文过长导致的模型状态混乱。
本地模型的上下文是有限资源,会话中的历史越长,模型越容易“忘事”。实在搞不定的时候,可以用 /clear 清理上下文,重新开始。
9.3 代码评审仍不可少
Agent 生成的代码,经过 CI 和人工 review 是必须的。本地模型生成的代码在逻辑上可能存在边界漏洞,特别是在数据库事务、权限校验、文件路径处理这些安全敏感区域。
9.4 关注模型的显存和内存计算方法
随着模型迭代,新模型可能会变大。生产使用时建议留出至少 20% 的显存余量,避免后台上其他程序占用显存导致 Ollama 崩溃。
9.5 版本管理要跟上
Ollama、Claude Code、LiteLLM 都是快速迭代的工具。建议固定版本,并使用锁文件管理配置。对于团队协作,可以使用 Docker 容器封装 Ollama 和 LiteLLM,保证各成员环境一致。
9.6 数据安全边界
虽然本地化方案避免了代码上传云端,但企业项目中仍然要注意:本地模型所在机器的物理安全和访问控制,模型文件本身也可能包含训练数据的敏感信息。部署在内网时,需要注意 API 默认监听的端口权限设置,避免局域网内其他设备直接访问本地模型服务。
10. 总结与后续学习方向
到这里,Claude Code + 本地大模型的全栈开发闭环已经完整跑通了。你学会了如何评估硬件、选择模型、安装 Ollama 和 Claude Code、通过 LiteLLM 完成协议对接,也实际完成了一个前后端分离的项目开发。最关键的是,你理解了这套工作流的本质——Claude Code 不是模型,而是一个智能调度框架,模型只是它的“大脑”。把大脑换成本地开源模型,整套开发流程依然可以运转。
接下来的进阶方向有三个:
- 尝试更大参数模型:比如 32B 级别的 Qwen2.5 系列,在代码生成质量上的提升非常明显,但需要更好的硬件支撑。
- 学习模型微调:如果你有特定项目的代码风格,可以对基础模型进行 LoRA 微调,让生成结果更贴合团队规范。
- 掌握 Prompt 工程:Claude Code 中提示词的质量直接决定任务的完成度,值得花时间研究角色设定、任务拆解、约束条件的写法。
这套方案最好的地方是:它不依赖付费 API,不依赖外部网络环境,一旦配置完成,就是一个完全属于你自己的编程助手。建议把本文收藏备用,在实际配置过程中按章节对照操作。如果你用的是 16GB 内存的普通开发机,第一次跑 7B 模型也能感受到很明显的智能感;如果配置更高,不妨直接上 14B 模型,体验会更接近云端服务。祝你在本地开发这条路上一路顺利。
