1. 项目概述
在Windows环境下搭建Claude Code与Ollama本地大模型组合,为开发者提供一个完全离线的AI编程辅助环境。这个方案特别适合需要保护代码隐私、避免云端服务延迟或限制的开发者。我最近在自己的游戏本上成功部署了这套系统,实测gpt-oss:20b模型能流畅运行,代码补全和解释功能完全不输云端服务。
2. 环境准备
2.1 Node.js环境配置
Claude Code基于Node.js运行,因此需要先配置好Node环境。这里有个关键细节容易被忽略:Node版本必须≥18,因为Claude Code使用了较新的ES模块特性。我推荐使用nvm-windows管理多版本:
bash复制nvm install 20.0.0
nvm use 20.0.0
注意:如果遇到权限问题,需要用管理员身份运行PowerShell。安装完成后执行
node -v验证版本,确保输出v20.x.x。
2.2 Claude Code安装
全局安装Claude Code包时,国内用户可能会遇到npm源的问题。建议先配置淘宝镜像:
bash复制npm config set registry https://registry.npmmirror.com
npm install -g @anthropic-ai/claude-code
安装成功的标志是控制台显示added X packages且无错误提示。我在三台不同设备上测试发现,安装时间从10秒到2分钟不等,取决于网络状况。
3. Ollama与大模型部署
3.1 Ollama安装要点
从官网下载Windows版Ollama时,建议选择自定义安装路径,避免C盘空间被大量占用。安装过程中有几个关键选项:
- 勾选"Add to PATH"(添加环境变量)
- 取消"Run Ollama on startup"(不需要开机自启)
- 保持"Enable local network access"选中(允许本地访问)
安装完成后无需手动启动服务,后续拉取模型时会自动激活后台进程。
3.2 模型选择与性能考量
根据官方文档,当前支持以下模型组合:
| 模型名称 | 参数规模 | 显存要求 | 适用场景 |
|---|---|---|---|
| glm-4.7 | 47B | 仅云端 | 企业级开发 |
| qwen-coder:30b | 30B | ≥24GB | 专业代码生成 |
| gpt-oss:20b | 20B | ≥16GB | 通用编程辅助 |
我的RTX 3070笔记本(8GB显存+32GB内存)实测:
- gpt-oss:20b运行时占用约14GB内存,响应速度在可接受范围(1-3秒/请求)
- 尝试qwen-coder:30b时出现内存不足警告,建议至少RTX 4080级别显卡尝试
拉取模型命令:
bash复制ollama pull gpt-oss:20b
实测数据:在100Mbps带宽下,20B模型下载约需30分钟(模型大小约12GB)
4. 网络与端口配置
4.1 本地防火墙设置
虽然教程提到默认端口11434,但我发现Windows Defender防火墙经常会拦截本地连接。最稳妥的方法是:
- 以管理员身份运行PowerShell
- 执行以下命令:
powershell复制New-NetFirewallRule -DisplayName "Ollama" -Direction Inbound -LocalPort 11434 -Protocol TCP -Action Allow
4.2 跨设备访问配置
如果需要从局域网其他设备访问,除了开放端口外,还需修改Ollama配置:
- 找到
C:\Users\[用户名]\.ollama\config.json - 添加:
json复制{
"host": "0.0.0.0",
"port": 11434
}
- 重启Ollama服务:
bash复制ollama serve
5. 环境变量配置实战
原教程提到的settings.json方法失效是因为新版Claude Code改用了环境变量读取方式。我推荐使用永久性环境变量设置:
powershell复制[System.Environment]::SetEnvironmentVariable('ANTHROPIC_AUTH_TOKEN', 'ollama', [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'http://localhost:11434', [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_MODEL', 'gpt-oss:20b', [System.EnvironmentVariableTarget]::User)
重要提示:修改后需要重启终端才能生效。验证方法:新开PowerShell执行
$env:ANTHROPIC_BASE_URL应显示设置的值。
6. 使用技巧与优化
6.1 终端交互模式
启动Claude Code交互界面后,我发现几个实用技巧:
- 输入
/help查看所有命令 - 使用
/model gpt-oss:20b切换模型(需提前拉取) //开头的行会被视为注释不执行- Ctrl+D退出交互模式
6.2 VSCode插件深度配置
安装官方插件后,需要在设置中手动指定本地端点:
json复制{
"claude-code.endpoint": "http://localhost:11434",
"claude-code.model": "gpt-oss:20b",
"claude-code.maxTokens": 2048
}
实测发现两个实用功能:
- 代码选中后按Ctrl+Shift+P → "Claude: Explain" 获取解释
- 在注释中写需求,按Alt+Enter自动生成代码
7. 常见问题排查
7.1 模型加载失败
错误现象:Error: model not found
解决方案:
- 确认模型已下载完成:
ollama list - 检查模型名称拼写(区分大小写)
- 尝试重新拉取:
ollama pull gpt-oss:20b
7.2 响应速度慢
优化方案:
- 在Ollama启动时添加GPU加速:
bash复制OLLAMA_DEVICE=cuda ollama run gpt-oss:20b
- 降低上下文长度:
bash复制setx OLLAMA_MAX_CONTEXT 2048
- 关闭其他占用显存的程序
7.3 内存不足处理
当出现CUDA out of memory错误时:
- 尝试更小模型:
ollama pull starcoder:7b - 启用内存交换:
bash复制setx OLLAMA_NO_MEMORY_LOCK 1
- 添加系统虚拟内存(至少32GB)
8. 性能调优实测数据
在我的ROG枪神6(i9-12900H/RTX3070/32GB)上测试:
| 操作 | 首次响应时间 | 持续响应时间 |
|---|---|---|
| 简单代码补全 | 1.2s | 0.8s |
| 复杂算法生成 | 3.5s | 2.1s |
| 代码解释(50行) | 2.8s | 1.9s |
| 跨文件上下文理解 | 4.2s | 3.5s |
优化建议:
- 对时间敏感的操作使用
//claude:fast注释触发精简模式 - 大项目中使用
/context命令预先加载关键文件 - 定期重启Ollama释放内存(建议每4小时一次)
这套本地部署方案经过两周的持续使用,稳定性完全满足日常开发需求。特别是在处理私有项目时,不必担心代码泄露风险,而且响应速度随着使用会越来越快(模型缓存机制)。对于没有高端显卡的用户,可以考虑使用qwen-coder:7b这类小模型,虽然能力稍弱但内存占用只有8GB左右