📘 Ollama 与 Claude Code 本地 AI 编程环境部署指南

✨ 本指南旨在帮助开发者快速、安全地在个人计算机上部署一套完整的本地 AI 编程辅助环境。您将无需依赖云端 API，即可使用 Claude Code 工具高效调用运行在本地的大型语言模型。

🚀 快速开始 | 环境检查清单

在开始前，请确认您的系统满足以下条件：

  • ✅ 操作系统：建议 macOS 或 Linux。Windows 用户需先安装 WSL2（Windows Subsystem for Linux 2），或直接使用官方提供的 “Ollama for Windows” 版本。
  • ✅ 基础工具：确保已安装 Git 和 curl（绝大多数系统已预装）。
  • ✅ Node.js：版本需大于或等于 v18.0.0（这是安装 Claude Code 的必需环境）。

🔧 第一部分：部署模型引擎 - Ollama

Ollama 是本地的模型运行与服务平台，为 Claude Code 提供“大脑”。

第1步：安装 Ollama

在终端（Terminal）中执行官方一键安装脚本：

curl -fsSL https://ollama.com/install.sh | sh

安装成功后，可通过以下命令验证服务状态：

查看 Ollama 版本
ollama --version

检查 11434 端口服务是否就绪
curl http://localhost:11434

第2步：下载与测试模型

推荐下载专为编程优化的开源模型，例如 qwen3-coder。在终端中运行：

拉取模型（下载需要一些时间，取决于网络与模型大小）
ollama pull qwen3-coder

进入交互模式，简单测试模型
ollama run qwen3-coder

💡 高级提示：您还可以通过 ollama create <自定义模型名> -f ./Modelfile 的方式导入已下载的 .gguf 等本地模型文件。

🔎 关于模型与端口的说明：自 Ollama v0.14.0 版本起，已默认原生支持与 Anthropic API 兼容的消息接口。因此，后续的 Claude Code 无需进行复杂配置即可直接连接。

⚙️ 第二部分：安装编程助手 - Claude Code

Claude Code 是连接您与本地模型的客户端工具，为编写代码提供智能辅助。

第1步：全局安装

为了提高下载速度，建议先配置 npm 镜像源（中国大陆用户适用）：

npm config set registry https://registry.npmmirror.com

接着，全局安装 Claude Code：

npm install -g @anthropic-ai/claude-code

验证安装是否成功：

claude --version

第2步：配置环境变量（最关键一步）

为了让 Claude Code 识别并连接您本地的 Ollama 服务，必须设置以下两个环境变量：

告知 Claude Code 本地服务的地址
export ANTHROPIC_BASE_URL=http://localhost:11434

设置一个虚拟 API Key（Ollama 无需真实密钥）
export ANTHROPIC_API_KEY=ollama

🚨 重要提醒：为了每次启动终端都能自动生效，请务必将上述两行命令永久添加到您的 Shell 配置文件中。

  • macOS / Linux：添加到 ~/.bashrc、~/.zshrc 或 ~/.bash_profile 文件的末尾。
  • Windows (WSL)：同样添加到 WSL 子系统内的 ~/.bashrc 文件中。
  • 添加后，执行 source ~/.bashrc 或重启终端以使配置生效。

✨ 第三部分：增强工具（可选）— OpenClaw AI 助手

如果您需要功能更丰富的 AI 助手体验（如额外的交互特性和脚本支持），可以安装 OpenClaw。

Windows （管理员权限 PowerShell）：

临时调整执行策略以允许脚本运行
Set-ExecutionPolicy Bypass -Scope Process -Force
执行安装脚本
iwr -useb https://openclaw.ai/install.ps1 | iex

macOS 或 Linux：

curl -fsSL https://openclaw.ai/install.sh | bash

更多功能详情，请访问 OpenClaw 官网。

🎯 第四部分：启动与验证

完成所有配置后，在任意终端窗口输入以下命令：

claude

若一切顺利，Claude Code 的交互界面将启动，并与您本地的 Ollama 模型成功连接。至此，您便拥有了一个高效、安全、零费用、完全离线的专业级 AI 编程助手！

🔍 第五部分：常见问题与排障指南

如果在操作过程中遇到问题，请对照下表进行排查：

问题现象可能的原因解决方案
claude 命令未找到npm 全局安装路径未正确添加到系统的 PATH 环境变量检查 Node.js 安装是否完整，或尝试重新执行 npm install -g @anthropic-ai/claude-code。
无法连接到 Ollama设置的环境变量未生效，Ollama 服务地址有误在终端中执行 source ~/.bashrc 重新加载配置，或完全重启终端。确认 Ollama 服务地址正确无误。
Ollama 服务无响应Ollama 后台服务进程未启动在终端中执行 ollama serve 来手动启动服务，并保持该终端窗口开启。
模型生成代码速度缓慢硬件（CPU/内存/GPU）资源不足尝试使用更小的模型（如 qwen3-coder:1.5b），或关闭其他占用大量资源的程序。

✅ 恭喜！您的专属本地 AI 编程环境已全部搭建完毕。现在，您可以不受网络限制，尽情探索和享受智能编码带来的生产力提升。祝您使用愉快！