如何在本地完全免费且私有地运行类 Claude Code 的 AI 编程助手

你是否曾希望拥有一个像 Claude Code 那样强大的 AI 编程助手，但又担心代码隐私、API 调用费用，或者单纯希望在没有网络的环境下也能工作？今天，我们将一步步探索如何将一个功能完整的 AI 编码代理完全部署在你自己的计算机上。整个过程无需连接互联网，不产生任何云服务费用，并且能确保你的所有代码和数据100%私密。

本文将详细介绍如何利用开源工具和模型，构建一个能够读取文件、编辑代码、执行终端命令的本地 AI 伙伴。

为何选择本地化部署 AI 编程助手？

在深入技术细节之前，让我们先明确一下这样做的核心价值。将 AI 编程助手运行在本地，主要带来三大优势：

  1. 绝对隐私：你的源代码、项目结构乃至 AI 给出的建议，全程都在你的设备上处理，没有一丝数据会被发送到外部服务器。
  2. 零成本运行：无需为昂贵的 API 调用付费，一次部署，无限次使用。唯一的“成本”是你本地计算机的运算资源。
  3. 离线可用性：无论你是在没有稳定网络的交通工具上，还是在保密要求极高的内网环境中，你的 AI 助手都能随时待命。

这套方案非常适合开发者、注重隐私的极客、开源爱好者，以及任何希望获得一个能真正理解并操作本地文件系统的 AI 协作者。

准备工作与核心工具

实现这一目标，我们需要两个核心组件：

  1. 一个能够在本机托管大型语言模型的“引擎”。
  2. 一个能够调用这个引擎、并具备文件操作和命令执行能力的“代理”程序。

在接下来的步骤中，我们将分别安装和配置它们。

图像：Ollama 应用界面示意图，展示其简洁的背景运行模式

第一步：构建本地“大脑”——安装 Ollama

Ollama 是一个强大的开源工具，它使得在本地下载、运行和管理大型语言模型变得异常简单。你可以把它想象成一个本地的“模型服务器”，它负责加载 AI 模型并与外部的应用程序（比如我们的编码代理）进行通信。

安装过程：

  1. 前往 Ollama 的官方网站下载安装程序。它支持 macOS、Windows 和 Linux 系统。
  2. 运行安装程序。安装完成后，Ollama 通常会以后台服务的形式静默运行，你可以在系统托盘或菜单栏找到它的图标。

安装好 Ollama 之后，它就像一个空置的“大脑容器”，等待着我们为其注入“智慧”。

选择合适的 AI 模型

Ollama 本身不包含模型，我们需要为其选择一个擅长编程任务的开放源代码模型。模型的选择很大程度上取决于你计算机的性能，特别是内存（RAM）的大小。

以下是一些针对不同性能设备的推荐：

设备性能 推荐模型 特点说明
高性能系统
(拥有足够内存，如 32GB+)		 qwen3-coder:30b 这是一个参数规模较大的模型，通常在代码生成、理解和调试方面表现更深入、更准确。需要较多的计算资源。
中等性能系统
(主流配置，16GB 内存左右)		 qwen2.5-coder:7b 在性能与资源消耗之间取得了良好平衡，是针对编程优化的优秀模型，对大多数开发任务来说能力已足够强大。
低资源或入门级设备
(如 8GB 内存)		 gemma:2b 参数规模小，运行速度快，对硬件要求极低。虽然能力不如大型模型，但仍能处理许多基础的代码补全和解释任务。

如何下载模型？
选择好模型后，我们通过一条简单的终端命令来将其下载到本地。打开你的终端（在 Windows 上是 PowerShell 或 CMD），输入以下命令格式：

ollama run <模型名称>

例如，如果你决定使用 qwen2.5-coder:7b 这个模型，就输入：

ollama run qwen2.5-coder:7b

当你第一次执行这条命令时，Ollama 会开始从网络下载对应的模型文件。下载进度会显示在终端中。下载完成后，它会自动进入一个交互式聊天界面，这意味着模型已经成功加载。你可以按 Ctrl+D 退出这个聊天界面，模型本身已经就绪，静待调用。

图像：终端中运行 ollama run qwen2.5-coder:7b 命令的截图

第二步：安装“手脚”——Claude Code 代理程序

现在，“大脑”已经准备就绪。接下来我们需要安装能够让这个大脑动手干活的“代理程序”。这个代理程序负责理解你的自然语言指令，将其转化为对文件的读取、修改，以及对终端的命令调用。

这个代理的安装过程同样通过终端完成。

  • 在 macOS 或 Linux 系统上，打开终端并运行：

    curl -fsSL https://claudecode.com/install.sh | bash
  • 在 Windows 系统上，请以管理员身份打开 PowerShell，然后运行：

    irm https://claudecode.com/install.ps1 | iex

这些安装脚本会自动完成必要的下载和配置。安装完成后，你可以通过以下命令验证是否成功：

claude --version

如果终端显示了版本号，恭喜你，代理程序安装成功。

一个重要提示：如果你之前在使用官方的 Anthropic Claude 服务并登录了账户，你可能需要在终端中退出登录，以确保接下来的配置能顺利切换到本地模式。

第三步：关键配置——将代理指向本地大脑

这是整个设置过程中最重要的一环。默认情况下，claude 命令会尝试连接 Anthropic 的官方云服务。我们需要通过设置环境变量，明确地告诉它：“请与你本机的 Ollama 对话。”

我们需要设置两个核心的环境变量：

  1. 设置基础连接地址：告诉 Claude Code 代理，API 服务在本机的哪个端口。Ollama 默认在 http://localhost:11434 提供服务。

    export ANTHROPIC_BASE_URL="http://localhost:11434"
  2. 提供一个“通行证”：虽然本地服务不需要真正的 API 密钥，但代理程序仍需要这个参数才能启动。我们只需任意提供一个字符串即可，惯例是使用 "ollama"。

    export ANTHROPIC_AUTH_TOKEN="ollama"

额外建议（隐私强化）：你还可以设置一个变量，明确禁止代理发送任何非必要的诊断或使用数据，这确保了绝对的隐私。

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

这些设置是临时的吗？
在终端中直接使用 export 命令设置的环境变量是临时的，只对当前终端会话有效。如果你希望永久生效，需要将这三行命令添加到你的 shell 配置文件中（例如 ~/.bashrc, ~/.zshrc 或 Windows 的系统环境变量中）。

图像：在终端中设置环境变量的命令截图

第四步：实战测试——启动你的私人编程助手

所有部件都已就位，现在是见证成果的时刻。让我们启动这个完全运行在本地的 AI 编程助手，并完成一个真实的任务。

  1. 启动代理：
    首先，通过终端进入你的任何一个项目目录。然后，使用 claude 命令启动代理，并通过 --model 参数指定你想要使用的本地模型。

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

    执行后，你应该会看到终端界面发生变化，显示来自本地模型的欢迎信息，这表明连接成功。

  2. 执行第一个任务：
    现在，你可以像与一个人类助手交谈一样，向它下达指令。例如，输入：

    “创建一个简单的 ‘Hello World’ 静态网站。”

    接下来，你将看到令人惊叹的一幕：

    • Claude Code 代理会分析你当前目录的文件。
    • 它可能会生成 HTML、CSS 或 JavaScript 文件。
    • 它会执行诸如 touch index.html、echo ‘<html>...’ > index.html 或 python -m http.server 等终端命令。
    • 所有这一切，都在你的屏幕上实时发生，而背后没有任何网络请求发出。

整个过程中，你可以观察到文件的创建、内容的写入，甚至一个本地服务器的启动。这就是一个功能完备、完全私有的 AI 编程助手在工作。

图像：Claude Code 在终端中运行并与用户交互的界面截图

常见问题解答 (FAQ)

Q1: 这个本地版的“Claude Code”和官方的 Claude Code 是完全一样的吗？
A: 不完全是。官方的 Claude Code 是 Anthropic 公司开发的专有产品。我们这里实现的是利用开源工具（Ollama）和开源代码模型，组合出了一个具备类似文件操作和命令执行能力的本地 AI 编码代理。你可以将其视为一个开源替代方案，核心体验相似，但背后的“大脑”（模型）不同。

Q2: 我的电脑需要多高的配置才能运行？
A: 这主要取决于你选择的模型。像 gemma:2b 这样的小模型，在 8GB 内存的普通笔记本电脑上就能流畅运行。而 qwen3-coder:30b 这样的大模型，则需要 32GB 或更多的内存才能良好运行。建议从 qwen2.5-coder:7b 这类中等模型开始尝试。

Q3: 除了编程，这个本地助手还能做其他事情吗？
A: 它的核心能力由背后的语言模型决定。你选择的“Coder”系列模型经过代码训练，因此在编程任务上表现最强。但语言模型本身也具备通用知识问答、文本摘要、创意写作等能力。不过，其文件操作和命令执行功能是 Claude Code 代理程序赋予的，主要围绕开发工作流设计。

Q4: 每次使用都需要重新下载模型和设置环境变量吗？
A: 不需要。模型文件下载一次后就会存储在本地。环境变量如果按“永久生效”的方式配置，也只需设置一次。之后，你只需在项目文件夹中运行 claude --model <模型名> 即可启动助手。

Q5: 如果过程中出错了，如何排查？
A: 请按顺序检查以下几点：

  1. Ollama 是否在运行？ 检查系统托盘或使用 ollama serve 命令确保服务已启动。
  2. 模型是否已下载？ 尝试 ollama list 查看已下载的模型列表。
  3. 环境变量是否正确设置？ 在终端中运行 echo $ANTHROPIC_BASE_URL (Linux/Mac) 或 echo %ANTHROPIC_BASE_URL% (Windows) 来验证。
  4. 是否指定了正确的模型名？ 确保 claude --model 后的模型名与 Ollama 中的一致。

总结与展望

通过以上四个步骤，你已经成功地将一个强大的 AI 编程助手“请”到了自己的计算机中。它不再是一个需要网络连接、按使用量付费的云服务，而变成了一个真正属于你的、随时可用的离线工具。

这种本地化部署模式代表了一种重要的趋势：在享受 AI 强大能力的同时，将控制权和隐私权牢牢掌握在自己手中。无论是为了在受限网络环境下工作，还是出于对核心代码资产的安全考量，亦或是作为开发者对开源技术的一种探索，这套方案都提供了坚实可行的路径。

现在，你可以放心地让你的 AI 助手深度访问你的项目，尝试更复杂的指令，比如“重构这个模块”、“为这个函数添加测试”或“分析这个日志文件中的错误”。所有的思考和操作，都在你那台安静运行着的机器内部完成，安全、私密且自由。