准备工作：了解你需要什么

本教程面向零基础读者，目标是让你在本地电脑上跑通一个免费的 AI 编程助手。你需要：

• 一台电脑（Windows / macOS / Linux 均可）
• 基本的命令行操作能力（打开终端、输入命令）
• 如果使用 GPU 加速，需要 NVIDIA 显卡（可选，CPU 也能用但慢一些）

我们会用到两个工具：Ollama（一个让你在本地运行 AI 模型的软件）和 OpenCode（一个终端里的 AI 编程助手）。它们都是免费的。

第一步：安装 Ollama 并下载模型

Ollama 负责在本地运行 AI 模型。安装步骤：

1. 打开浏览器，访问 ollama.com，点击“Download”下载对应系统的安装包。
2. 运行安装程序，按提示完成安装。
3. 安装后，打开终端（Windows 用户打开命令提示符或 PowerShell），输入 ollama pull qwen2.5-coder:7b 并回车。这会下载一个 7B 参数的编程模型，适合大多数电脑。如果你的显卡显存大于 8GB，可以换成 qwen2.5-coder:14b（效果更好）。

常见坑：如果下载很慢，可以尝试更换网络或使用代理。下载完成后，输入 ollama list 确认模型已存在。

第二步：安装 OpenCode 并配置连接

OpenCode 是我们要用的 AI 编程助手。安装步骤：

1. 在终端输入以下命令（Windows 用户请用 PowerShell）：
   curl -fsSL https://opencode.ai/install | sh
2. 安装完成后，将 OpenCode 添加到系统路径：
   export PATH=$HOME/.opencode/bin:$PATH（Linux/macOS）或参考安装提示。
3. 在你想要使用 AI 助手的项目文件夹里，创建一个名为 opencode.json 的配置文件，内容如下：
   

   {
     "provider": {
       "ollama": {
         "type": "openai-compatible",
         "baseURL": "http://localhost:11434/v1"
       }
     },
     "model": "ollama/qwen2.5-coder:7b"
   }

解释：这个配置文件告诉 OpenCode 使用 Ollama 提供的本地模型。其中 baseURL 是 Ollama 的地址，model 指定了要用的模型名称。

第三步：启动并测试

现在来验证一切是否正常：

1. 确保 Ollama 正在运行：在终端输入 ollama serve 并保持窗口打开。如果 Ollama 已经在后台运行，这一步可以跳过。
2. 在项目文件夹里输入 opencode 并回车。你应该会看到一个漂亮的终端界面（TUI）。
3. 按 Tab 键切换到 Plan 模式（只读模式，适合问问题）。然后输入一个问题，比如“这个项目的主要功能是什么？”如果模型开始回答，说明配置成功！

常见坑：如果出现“Connection refused”错误，说明 Ollama 没有启动。请先运行 ollama serve。如果模型没有回答，检查 opencode.json 里的模型名称是否和 ollama pull 时用的一致。

下一步可以做什么

现在你已经成功运行了本地的 AI 编程助手！你可以：

• 在 Plan 模式下询问代码问题，比如“这个函数是做什么的？”
• 尝试切换到 Build 模式（再次按 Tab），但注意：目前 Build 模式写文件的功能有 bug（社区已知问题 #29940），建议用 Plan 模式做代码探索，实际写代码还是用云端 API 更可靠。
• 尝试下载其他模型，比如 llama3.2:3b 更轻量，适合快速问答。

恭喜你，你已经迈出了 AI 编程的第一步！