完全本地化 Claude Code 搭建指南

前言：Claude Code 是 Anthropic 推出的强大命令行 AI 编程工具。本教程将通过“劫持”其 API 接口的方式，将其后端替换为本地运行的开源大模型（通过 Ollama），实现一个完全免费、离线、隐私安全且具备真实工程能力的 AI 助手。

📋 目录

1. 核心优势
2. 环境与硬件准备
3. 第 1 步：部署本地模型 (Ollama)
4. 第 2 步：安装 Claude Code CLI
5. 第 3 步：核心配置 (连接桥梁)
6. 第 4 步：实战演练与工作流
7. 进阶技巧：优化上下文与性能
8. 常见问题排查 (Troubleshooting)

🌟 核心优势

• 数据隐私：所有代码、文件结构、环境变量仅在本地内存中处理，绝不上传云端。
• 零成本：无需绑定信用卡，无需支付 Toke2ns 费用。
• Agent 能力：区别于普通的聊天机器人，它能读取文件、修改代码、执行终端命令（如 ls, git, python 等）。
• 低延迟：局域网/本地回环速度，完全取决于你的显卡推理速度。

🛠 环境与硬件准备

软件要求

• 操作系统：macOS (推荐), Linux, 或 Windows (建议使用 WSL2 或 PowerShell)
• 依赖工具：curl, git

硬件建议 (决定模型选择)

🚀 第 1 步：部署本地模型 (Ollama)

Ollama 是目前最流行的本地 LLM 运行时工具。

1.1 安装 Ollama

• macOS / Linux:

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

• Windows: 直接前往 Ollama 官网下载 .exe 安装包并运行。

1.2 下载编程专用模型

Claude Code 依赖模型极强的指令遵循和工具调用能力，因此通用模型（如 Llama 3 Chat）效果不如专用编程模型（Coder 版本）。

打开终端，拉取 Qwen 2.5 Coder（目前开源界最强编程模型之一）：

# 推荐大多数用户使用 7B 版本ollama pull qwen2.5-coder:7b# 如果你是 Mac M1/M2/M3 Max 或拥有 3090/4090 显卡ollama pull qwen2.5-coder:32b

1.3 验证运行

在浏览器访问 http://localhost:11434。如果显示 Ollama is running，说明后端服务已就绪。

📦 第 2 步：安装 Claude Code CLI

这是 Anthropic 官方提供的命令行工具，我们将使用它作为前端交互界面。

2.1 执行安装脚本

macOS / Linux:

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

Windows (PowerShell 管理员模式):

irm https://claude.ai/install.ps1 | iex

2.2 验证安装

安装完成后，检查版本：

claude --version

2.3 清理旧状态 (重要)

如果你之前使用过官方 API 登录，必须先退出，否则 CLI 会优先使用缓存的官方 Token。

claude logout

🔗 第 3 步：核心配置 (连接桥梁)

我们需要通过设置环境变量，将 Claude CLI 的流量从 api.anthropic.com 劫持到 localhost:11434。

方式 A：临时运行 (仅当前终端窗口有效)

# Mac/Linuxexport ANTHROPIC_BASE_URL="http://localhost:11434"export ANTHROPIC_AUTH_TOKEN="ollama"# 任意非空字符串即可export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 # 禁用遥测# 启动claude --model qwen2.5-coder:7b

方式 B：永久配置 (推荐)

为了不用每次都输命令，我们将其写入 Shell 配置文件。

🍎 macOS / Linux (zsh 或 bash)

1. 打开配置文件：

   nano ~/.zshrc   # 如果你用 bash，则为 ~/.bashrc

2. 在文件末尾添加：

   # Claude Local Configexport ANTHROPIC_BASE_URL="http://localhost:11434"export ANTHROPIC_AUTH_TOKEN="ollama_local_key"export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

3. 保存退出 (Ctrl+O, Enter, Ctrl+X) 并刷新配置：

   source ~/.zshrc

🪟 Windows (PowerShell)

1. 打开 PowerShell 配置文件：

   notepad $PROFILE

2. 在文件中添加：

   $env:ANTHROPIC_BASE_URL = "http://localhost:11434"$env:ANTHROPIC_AUTH_TOKEN = "ollama"$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC = 1

3. 保存后重启 PowerShell。

🎮 第 4 步：实战演练与工作流

现在，你的本地 AI 程序员已经准备就绪。

4.1 启动 Agent

进入你的项目文件夹（例如 ~/my-project），运行：

claude --model qwen2.5-coder:7b

提示：如果你的模型名字很长，可以给启动命令设置别名（alias），例如 alias ai="claude --model qwen2.5-coder:7b"。

4.2 交互示例

场景 1：从零开始写代码

User: "创建一个名为 system_info.py 的脚本，读取当前系统的 CPU 和内存使用率，并打印出来。然后直接运行它。"

Claude (Local) 的行为:

1. 思考: 分析需要 psutil 库。
2. 工具调用: 执行 pip install psutil (会询问你权限)。
3. 文件操作: 写入 system_info.py。
4. 终端执行: 运行 python system_info.py。
5. 反馈: "脚本已运行，输出如下..."

场景 2：重构现有代码

User: "读取当前目录下的 main.go，给所有的函数加上详细的注释，并把错误处理逻辑优化一下。"

⚙️ 进阶技巧：优化上下文与性能

默认的 Ollama 模型上下文窗口可能较小（通常是 2048 或 4096 tokens），处理大文件时会“失忆”。我们可以自定义 Modelfile 来增加它。

1. 创建自定义模型文件

创建一个名为 Modelfile 的文件：

FROM qwen2.5-coder:7b# 将上下文窗口扩大到 16k (取决于你的显存，显存越大可以设越大)PARAMETER num_ctx 16384# 调整创造性，编码任务建议低温度PARAMETER temperature 0.1SYSTEM """你是一个高级编程助手。不仅要写代码，还要善于使用终端工具来验证你的代码。"""

2. 编译新模型

在终端运行：

ollama create my-coder -f Modelfile

3. 使用新模型启动

claude --model my-coder

🔧 常见问题排查 (Troubleshooting)

Q1: 报错 Connection refused 或 ECONNREFUSED

• 原因: Ollama 没有运行，或者端口不是 11434。
• 解决: 终端运行 ollama serve 确保服务启动。检查 ANTHROPIC_BASE_URL 是否写错。

Q2: AI 回复胡言乱语或不执行命令

• 原因: 模型太小（如 2b 参数）无法理解复杂的 Agent 工具调用协议。
• 解决: 换用更强的模型（推荐 Qwen 2.5 Coder 7B 及以上）。

Q3: 报错 context length exceeded

• 原因: 项目文件太大，超过了模型的记忆限制。
• 解决:
1. 使用 /compact 命令让 Claude 压缩历史。
2. 按照“进阶技巧”增加 num_ctx。
3. 仅让 Claude 读取必要的文件，不要一次性让它读整个仓库。

Q4: 总是提示需要 API Key

• 原因: 环境变量未生效。
• 解决: 在终端运行 echo $ANTHROPIC_BASE_URL (Mac/Linux) 或 $env:ANTHROPIC_BASE_URL (Win) 检查是否有输出。如果没有，请重新配置第 3 步。

⚠️ 免责声明：虽然本地运行极其安全，但 AI 执行终端命令（如删除文件、网络请求）仍存在风险。Claude Code 在执行高危命令前通常会要求用户按 y 确认，请务必仔细审查它要执行的命令。