LowHow 文档

中文

English

中文

English

深色模式

OpenCode 实战教程：从零搭建免费 AI 编程助手 ​

📚 分类: AI 编程工具 ⏱️ 预计耗时: 30 分钟 🎯 难度: 入门 🔧 环境要求: Windows / macOS / Linux 均可，需有 Node.js 环境

你将学到什么 ​

完成本教程后，你将能够：

  • [ ] 在本地终端成功安装并启动 OpenCode
  • [ ] 切换并使用免费的 AI 模型（如 Gemini）进行编程
  • [ ] 配置并接入顶级商业模型（如 Claude 4.5 Opus）
  • [ ] 理解 OpenCode 的核心概念和基础操作
  • [ ] 解决安装和配置过程中的常见问题

最终效果 ​

你将拥有一个运行在你电脑终端中的 AI 编程助手。你可以在项目目录下输入 opencode 命令，启动一个交互式对话界面，通过自然语言让 AI 帮你读取文件、修改代码、运行命令等。整个过程完全在你的本地环境中进行，代码安全可控。

前置准备 ​

在开始前，请确认你的环境满足以下条件：

检查项要求版本验证命令
Node.js≥ 18.0node -v
Git≥ 2.30git --version
系统内存≥ 4GB (推荐 8GB)系统信息查看

1. 安装 Node.js ​

如果你还没有 Node.js，请访问 nodejs.org 下载并安装最新的 LTS（长期支持）版本。

bash
# 验证安装
$ node -v
# 预期输出：v18.x.x 或更高版本

✅ 验证：如果终端正确输出了版本号，说明安装成功。

第 1 步：安装 OpenCode ​

🎯 目标：在你的操作系统中安装 OpenCode 的命令行工具。

📝 操作：我们使用官方推荐的 npm 包管理器进行全局安装。

bash
# 使用 npm 全局安装 OpenCode
$ npm install -g opencode-ai@latest

💡 提示：如果遇到 EACCES: permission denied 权限错误，说明你的 npm 全局安装路径需要管理员权限。在 macOS/Linux 上，你可以在命令前加 sudo：

bash
$ sudo npm install -g opencode-ai@latest

🤔 为什么要这样做？-g 参数表示全局安装，这样你就可以在终端的任何位置使用 opencode 命令了。

✅ 验证：安装完成后，验证是否成功。

bash
$ opencode --version
# 预期输出：v1.4.3 或类似版本号

⚠️ 常见错误：

  • 错误信息：opencode: command not found
  • 解决方案：这说明 opencode 的可执行文件没有被添加到系统的 PATH 环境变量中。请重新启动你的终端窗口，或者尝试手动添加 npm 的全局 bin 目录到 PATH 中（通常在 ~/.npm-global/bin 或 /usr/local/bin）。

第 2 步：启动 OpenCode 并初始化项目 ​

🎯 目标：在你的项目目录中启动 OpenCode，并让它了解项目结构。

📝 操作：

  1. 打开终端，导航到你的项目目录。如果你还没有项目，可以创建一个新的空目录作为练习。

    bash
    # 创建一个测试目录并进入
$ mkdir my-ai-project && cd my-ai-project

  2. 在项目目录中启动 OpenCode。

    bash
    $ opencode

    你会看到 OpenCode 的终端用户界面（TUI）启动，并出现一个对话窗口。

  3. 在对话窗口中，输入初始化命令 /init 并按回车。OpenCode 会分析你的项目结构，并创建一个 AGENTS.md 文件来记录项目上下文。

    bash
    # 在 OpenCode 的对话界面中输入
/init

✅ 验证：你应该会看到 OpenCode 的界面，并且可以输入命令。在你的项目目录下，会生成一个名为 AGENTS.md 的新文件。

第 3 步：使用免费模型进行首次对话 ​

🎯 目标：无需任何配置，立即使用 OpenCode 自带的免费模型进行交互。

📝 操作：

  1. 在 OpenCode 的对话界面中，输入 /models 命令查看可用的模型列表。

    bash
    /models

    系统会列出一系列模型，其中带有 Free 标签的就是你可以免费使用的模型，例如 minimax-m2.1-free。

  2. 切换到一个免费模型。

    bash
    /model minimax-m2.1-free

  3. 现在，你可以向 AI 提问了。例如，让它帮你写一个简单的 Python 函数。

    text
    请用 Python 写一个函数，用于计算斐波那契数列的第 n 项。

✅ 验证：OpenCode 会开始思考并生成代码。你应该能在界面中看到它生成的 Python 代码和解释。

💡 提示：/models 和 /model 是 OpenCode 中非常重要的内置命令。/models 用于查看所有可用模型，/model <模型名> 用于切换当前使用的模型。

第 4 步：接入免费且强大的 Google Gemini 3 Pro ​

🎯 目标：配置 Google Gemini 3 Pro 模型，获得更强的 AI 编程能力，且无需付费。

📝 操作：

  1. 获取 API 密钥：

    • 访问 Google AI Studio.
    • 使用你的 Google 账号登录。
    • 点击左侧菜单或页面上的 "Get API key" 按钮。
    • 点击 "Create API key" 创建一个新的 API 密钥。
    • 复制并安全保存 这个密钥。

  2. 在 OpenCode 中配置：

    • 回到 OpenCode 的对话界面。
    • 输入以下命令开始配置 Google 模型提供商：
    bash
    /connect google
    • 系统会提示你输入 API 密钥。粘贴你刚才复制的密钥，然后按回车。

  3. 切换到 Gemini 模型：

    • 配置完成后，输入以下命令切换到 Gemini 3 Pro 模型：
    bash
    /model gemini-3-pro

✅ 验证：模型名称切换为 gemini-3-pro。你可以再次提问，观察回答的质量和速度。如果配置失败，会提示 "API key not valid" 等错误信息。

⚠️ 常见错误：

  • 错误信息：API key not valid
  • 解决方案：
    1. 检查你复制的 API 密钥是否完整，没有多余的空格。
    2. 确认你的 Google AI Studio 账号已经激活，并且 API 功能没有被限制。
    3. 尝试在 Google AI Studio 中重新生成一个新的 API 密钥。

第 5 步：接入顶级模型 Claude 4.5 Opus (付费) ​

🎯 目标：配置 Anthropic 官方 API，接入当前代码能力最强的 Claude 4.5 Opus 模型。

📝 操作：

  1. 获取 API 密钥：

    • 访问 Anthropic 控制台 并注册/登录。
    • 在控制台中，点击 "API Keys" 选项卡。
    • 点击 "Create Key" 按钮创建一个新的 API 密钥。
    • 复制并安全保存 这个密钥。

  2. 在 OpenCode 中配置：

    • 在 OpenCode 的对话界面中，输入以下命令：
    bash
    /connect anthropic
    • 按照提示粘贴你的 Anthropic API 密钥。

  3. 切换到 Claude 模型：

    bash
    /model claude-4.5-opus

✅ 验证：模型名称切换为 claude-4.5-opus。现在你可以体验最强模型的能力了。

⚠️ 重要提示：

  • 这是付费模型：使用 Anthropic 官方 API 需要按量付费（输入 $15/百万 token，输出 $75/百万 token）。新用户通常会有 $5 的免费试用额度。
  • 注意封号风险：不建议使用非官方的第三方代理或 OAuth 方式接入，存在账号被封禁的风险。

进阶技巧（可选） ​

掌握基础后，你可以尝试：

  1. 使用 Oh My Opencode 插件：这是一个社区开发的强大插件，可以一键切换模型、启用“终极工作模式”等，极大提升效率。在 OpenCode 中直接输入以下指令即可让 AI 帮你安装：

    text
    Install and configure oh-my-opencode by following the instructions here:
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md

  2. 配置本地模型 (Ollama)：如果你非常注重隐私，可以安装 Ollama 并在本地运行开源模型（如 deepseek-coder）。然后在 OpenCode 中使用 /connect ollama 命令进行配置。

常见问题 (FAQ) ​

Q1: 使用 OpenCode 时，我的代码会被上传到服务器吗？A: 默认情况下，不会。OpenCode 是一个本地工具。只有当你使用云端模型（如 Gemini, Claude）时，你的代码片段才会被发送到对应的 API 提供商进行处理。如果你使用本地模型（如通过 Ollama），则完全不需要联网。

Q2: 如何更新 OpenCode 到最新版本？A: 根据你的安装方式，运行对应的命令：

  • npm 安装: npm update -g opencode-ai@latest
  • brew 安装: brew upgrade opencode
  • 一键脚本安装: 重新运行安装脚本 curl -fsSL https://opencode.ai/install | bash

Q3: 如何卸载 OpenCode？A: 同样取决于安装方式：

  • npm 安装: npm uninstall -g opencode-ai
  • brew 安装: brew uninstall opencode
  • 一键脚本安装: 手动删除 ~/.opencode 目录和 /usr/local/bin/opencode 文件。

总结 ​

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

  1. 安装与启动：学会了使用 npm 安装 OpenCode 并在项目目录中启动它。
  2. 免费模型使用：掌握了如何查看和切换到 OpenCode 自带的免费模型。
  3. 配置外部模型：学会了如何获取 API 密钥并配置 Google Gemini 和 Anthropic Claude 等外部模型。
  4. 基础操作：熟悉了 /init、/models、/model、/connect 等核心命令。

你现在已经拥有了一个强大、灵活且免费的 AI 编程助手。

© 2026 LowHow