如何在本地运行 Claude Code（100% 免费且完全私密）
一、概述
1. 简介
A. 是什么
本教程介绍如何在本地机器上完全运行 Claude Code，使用本地开源模型作为 AI 引擎。这种设置让 AI 能够读取文件、编辑代码和运行命令，无需将任何数据发送到云端。
B. 为什么学
- 完全离线运行，无需 API 调用
- 零成本，无订阅费用
- 数据隐私得到完全保护
- 无追踪，无监控
C. 学完能做什么
- 在本地部署 Claude Code 环境
- 使用开源模型实现 AI 编程助手功能
- 让 AI 能够编辑文件和执行终端命令
2. 前置知识
A. 必备技能
- 基本的命令行操作能力
- 了解如何安装软件包
B. 推荐知识
- 对大语言模型有基本了解
- 了解 Claude Code 的基本概念
二、环境准备
1. 系统要求
- macOS 或 Linux 系统
- Windows 系统
- 内存要求取决于选择的模型大小
2. 核心组件
- Ollama：本地 AI 模型运行引擎
- Claude Code：AI 编程助手
- 开源代码模型：如 Qwen2.5-Coder 或 Gemma
三、核心概念
1. 基本术语
- Ollama：本地大模型运行平台，支持函数调用
- Claude Code：Anthropic 官方的 AI 编程助手
- 本地模式：Claude Code 连接到本地模型而非云端 API
2. 工作原理
graph LR
A[用户输入] --> B[Claude Code]
B --> C{模型选择}
C -->|云端模式| D[Anthropic API]
C -->|本地模式| E[Ollama]
E --> F[本地开源模型]
F --> G[文件读写]
F --> H[命令执行]
G --> B
H --> B
D --> I[需要联网]
E --> J[完全离线]
四、快速上手
1. 步骤一：选择本地"大脑"（Ollama）
在运行 Claude Code 之前，需要先安装一个能够托管 AI 模型并支持工具调用或函数调用的本地引擎。Ollama 可以完成这个任务。
首先下载并安装 Ollama。安装完成后，它在 Mac 和 Windows 上都会在后台静默运行。
2. 步骤二：下载代码模型
接下来需要下载一个专注于代码的模型。有很多开源模型可以选择，具体取决于机器的性能。
推荐配置：
高性能系统：
# 拉取更大的模型
ollama run qwen2.5-coder:30b低内存机器：
# 使用较小的模型
ollama run gemma:2b
# 或
ollama run qwen2.5-coder:7b首次运行命令时，模型会下载到本地机器，因此输出可能会与后续运行有所不同。
3. 步骤三：安装 Claude Code
现在安装 Claude Code 代理本身，这将把模型转变为活跃的编程助手。
在终端中运行对应系统的安装命令：
Mac 或 Linux：
curl -fsSL https://claude.ai/install.sh | bashWindows：
irm https://claude.ai/install.ps1 | iex安装完成后，通过以下命令验证是否成功：
claude --version注意：如果之前登录过 Anthropic 账户，可能需要先登出，以便 Claude 切换到本地模式。
4. 步骤四：将 Claude 指向本地机器
这是最关键的一步。默认情况下，Claude 会尝试连接到 Anthropic 的服务器。这里需要明确将其重定向到本地 Ollama 实例。
首先，通过设置基础 URL 告诉 Claude Ollama 的运行位置：
export ANTHROPIC_BASE_URL="http://localhost:11434"接下来，Claude 仍然期望有 API 密钥，因此提供一个虚拟值：
export ANTHROPIC_AUTH_TOKEN="ollama"还可以选择退出遥测和调查：
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1五、实战演示
1. 启动 Claude
导航到任何项目文件夹，使用选定的模型启动 Claude。例如：
claude --model qwen2.5-coder:7b应该会看到本地模型出现。
2. 测试功能
启动后，尝试一个提示词。例如：
Add a hello world website将会看到 Claude 读取文件、修改代码并实时执行终端命令，完全在本地机器上运行。
无 API 调用，无云端处理，零成本。只是一个完全本地化的 AI 编程代理，直接在项目内部工作。
sequenceDiagram
participant U as 用户
participant C as Claude Code
participant O as Ollama
participant M as 本地模型
participant F as 文件系统
participant T as 终端
U->>C: 输入提示词
C->>O: 发送请求
O->>M: 模型推理
M->>O: 返回响应
O->>C: 返回结果
C->>F: 读取文件
F-->>C: 文件内容
C->>F: 写入修改
C->>T: 执行命令
T-->>C: 命令输出
C-->>U: 显示结果
六、适用场景
1. 目标用户
- 希望拥有私密、离线 AI 编程代理的开发者
- 想要 Claude Code 功能的高级用户
- 尝试本地大模型的开源爱好者
- 任何希望 AI 能够真正编辑文件和运行终端命令的人
2. 优势分析
- 完全免费：无 API 调用成本
- 隐私保护：数据不离开本地机器
- 离线工作：无需互联网连接
- 无监控：无遥测数据收集
七、常见问题
1. 模型选择
高性能机器建议使用更大的模型以获得更好的性能，低内存机器应选择较小的模型。
2. 兼容性
如果之前使用过云端版本的 Claude Code，需要确保正确设置环境变量以切换到本地模式。
3. 性能考虑
本地模型的性能取决于硬件配置，特别是内存和 CPU/GPU 资源。