Open Code 文档

主题

首页文档搜索

使用 OpenCode 搭建私有 AI 编程助手实战教程 ​

📚 分类: AI 编程工具 ⏱️ 预计耗时: 20 分钟 🎯 难度: 入门 🔧 环境要求: Windows / macOS / Linux，已安装 Node.js (≥ 18.0) 和 npm

你将学到什么 ​

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

  • [ ] 在本地成功安装并运行 OpenCode 终端应用
  • [ ] 切换并使用 OpenCode 内置的免费大模型
  • [ ] 安装并配置核心插件 oh-my-opencode，提升 AI 协作能力
  • [ ] 掌握 OpenCode 的 3 个核心操作命令，开启你的 AI 编程工作流

最终效果 ​

你将拥有一个运行在你本地的、完全免费的 AI 编程终端助手。你可以在终端中直接向它提问、让它帮你写代码、解释代码，甚至规划复杂的开发任务。

前置准备 ​

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

检查项要求版本验证命令
Node.js≥ 18.0node -v
npm(随 Node.js 安装)npm -v

1. 安装 Node.js 和 npm ​

如果尚未安装，请前往 Node.js 官网 下载并安装最新的 LTS（长期支持）版本。安装完成后，打开你的终端（Terminal / CMD / PowerShell），运行以下命令验证：

bash
$ node -v
# 预期输出类似：v20.11.0

$ npm -v
# 预期输出类似：10.2.4

✅ 验证：如果看到版本号，说明 Node.js 和 npm 安装成功。

第 1 步：一键安装 OpenCode 主程序 ​

🎯 目标：在你的电脑上安装 OpenCode 命令行工具。

📝 操作： 在终端中，根据你的操作系统，选择其中一条命令执行即可。

bash
# 方式一（推荐）：使用 npm 全局安装
$ npm install -g opencode-ai

# 方式二（macOS）：使用 Homebrew 安装
$ brew install anomalyco/tap/opencode

# 方式三（Linux）：使用官方脚本安装
$ curl -fsSL https://opencode.ai/install | bash

🤔 为什么要这样做？npm install -g 会将 OpenCode 安装为全局命令，这意味着你可以在任何目录下直接使用 opencode 命令。

✅ 验证： 安装完成后，运行以下命令检查版本：

bash
$ opencode --version
# 预期输出类似：v0.x.x

💡 提示：

  • 如果下载速度很慢，可以尝试配置 npm 的国内镜像源，例如：npm config set registry https://registry.npmmirror.com，然后再执行安装命令。
  • 安装成功后，直接在终端输入 opencode 并回车，你应该能看到一个欢迎界面，这表示程序已成功启动。

第 2 步：连接并使用免费大模型 ​

🎯 目标：了解如何切换并使用 OpenCode 内置的免费模型，开始第一次对话。

📝 操作：

  1. 在终端中输入 opencode 启动程序（如果尚未启动）。

  2. 在欢迎界面或对话界面中，输入命令 /models 并回车。

    text
    # 在 OpenCode 对话界面中输入
/models

  3. 你将看到一个大模型列表。找到名称中带有 free 或 FREE 标记的模型，例如 HY3、MiniMax M2.5 等。

  4. 输入你想使用的模型名称（或序号）并回车，即可切换。

✅ 验证： 切换模型后，输入任意问题，例如 "用 Python 写一个快速排序算法"。如果模型能正常回复，说明连接成功。

🤔 为什么要这样做？ OpenCode 默认集成了多个免费模型，让你无需配置任何 API Key 就能立刻体验 AI 编程能力。/models 命令就是你的模型切换控制台。

⚠️ 常见错误： 问题：输入 /models 后没有显示免费模型。 解决：请确保你的 OpenCode 版本是最新的。可以运行 npm update -g opencode-ai 来更新。

第 3 步：安装核心插件 oh-my-opencode ​

🎯 目标：安装 OpenCode 的核心增强插件，为 AI 赋予更强大的任务规划和执行能力。

📝 操作：

  1. 退出 OpenCode：如果正在运行，按 Ctrl + C 退出。

  2. 全局安装插件包：

    bash
    $ npm install -g oh-my-opencode

  3. 执行安装脚本：

    bash
    $ npx -y oh-my-opencode install --no-tui --claude=no --gemini=no --copilot=no
    • --no-tui：跳过图形化界面，使用纯命令行安装。
    • --claude=no、--gemini=no、--copilot=no：我们暂时只启用 OpenCode，不连接其他商业 AI 服务。

  4. 配置 OpenCode 加载插件： 找到 OpenCode 的配置文件。路径通常在：

    • Windows: C:\Users\<你的用户名>\.config\opencode\opencode.json
    • macOS / Linux: ~/.config/opencode/opencode.json

    用文本编辑器打开这个文件，将其内容修改为：

    json
    {
  // 新增：告诉 OpenCode 加载 oh-my-opencode 插件
  "plugin": ["oh-my-opencode@latest"],
  "$schema": "https://opencode.ai/config.json"
}

  5. 重启 OpenCode：在终端输入 opencode 重新启动。首次启动会稍微慢一些，因为需要下载插件依赖。看到终端输出 Sisyphus 提示信息即表示加载成功。

✅ 验证： 启动后，按 Tab 键。你应该能看到切换模式的选项，例如 Plan 模式和 Build 模式。这说明插件已生效。

🤔 为什么要这样做？oh-my-opencode 就像给 AI 配备了一个“项目管理团队”。它让 AI 不再只是“单兵作战”，而是能先进行规划（Plan模式），再动手执行（Build模式），让开发过程更可控、更可靠。

第 4 步：掌握 3 个核心命令，开启高效工作流 ​

🎯 目标：学习并实践 OpenCode 的 3 个最常用的核心命令，立即提升你的使用效率。

📝 操作：

1. /init - 生成项目说明书 ​

这是你开始一个新项目时必须做的第一步。

  • 操作：进入你的项目根目录，启动 OpenCode 后，输入 /init 并回车。
  • 效果：AI 会自动扫描你的项目结构，并生成一个名为 AGENTS.md 的文件。这个文件就是 AI 理解你项目的“第一份地图”。
  • ✅ 验证：查看项目根目录，确认 AGENTS.md 文件已生成。建议将此文件提交到 Git 仓库。

2. @文件路径 - 精准控制讨论范围 ​

当你想让 AI 专注于某个特定文件时，使用 @ 符号。

  • 操作：在提问时，输入 @src/main.py 然后跟上你的问题，例如 @src/main.py 帮我分析这里的性能瓶颈。
  • 效果：AI 将只关注你指定的文件，避免“脑补”无关代码，大幅提升回答的准确性。
  • ✅ 验证：AI 的回答会明确引用 src/main.py 文件中的内容。

3. /compact - 压缩对话上下文 ​

当你的对话很长，感觉 AI 开始“答非所问”时使用。

  • 操作：在对话界面输入 /compact 并回车。
  • 效果：AI 会将当前对话的核心决策和上下文进行压缩，清理掉无关的“废话”，让对话重回正轨。
  • ✅ 验证：执行命令后，AI 会提示上下文已被压缩。你可以继续提问，感受其回答的聚焦程度。

进阶技巧（可选） ​

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

  1. 安装 Skills 技能包： 通过 npx skills add <仓库地址> --skill <技能名> -g 命令，可以为 AI 安装“专业技能”。例如，superpowers 技能包能提升 AI 的任务拆解和规划能力。

    bash
    # 示例：安装 superpowers 技能包
$ npx skills add https://github.com/obra/superpowers --skill using-superpowers -g

  2. 创建自定义 Agent： 使用 opencode agent create 命令创建专属角色，例如一个只负责代码审查的 review-agent。

常见问题 (FAQ) ​

Q1: 安装后运行 opencode 提示 command not found？A: 说明全局安装路径未添加到系统环境变量。可以尝试重新打开终端窗口，或运行 npm root -g 找到全局安装路径，并将其添加到 PATH 环境变量中。

Q2: 如何修改 OpenCode 的配置文件？A: 配置文件位于 ~/.config/opencode/opencode.json。你可以用任何文本编辑器打开它，修改 "plugin" 等字段来管理插件。

Q3: 免费模型用完了怎么办？A: OpenCode 的免费模型通常有每日使用额度。你可以通过 /models 命令切换到其他免费模型，或配置自己的 API Key（如 GPT、Claude）来使用更强大的模型。

总结 ​

恭喜你完成了本教程！🎉

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

  1. 环境搭建：成功安装了 Node.js 和 OpenCode 主程序。
  2. 模型切换：学会了使用 /models 命令选择免费 AI 模型。
  3. 插件安装：掌握了安装和配置核心插件 oh-my-opencode 的方法。
  4. 核心命令：熟练使用 /init、@文件路径、/compact 三个命令，开启了高效的 AI 编程工作流。

下一步 ​

如果你想继续深入，建议学习：

  • 📖 探索插件生态：访问 OpenCode 官方插件市场，发现更多有用的插件。
  • 📖 配置自己的 API Key：学习如何连接 GPT-4、Claude 等更强大的商业模型。

💡 练习任务：找一个你以前写过的小项目，进入项目目录，执行 /init 生成 AGENTS.md，然后尝试用 Plan 模式让 AI 为你规划一个重构方案。这是巩固知识的最佳方式。

yaml

## 相关文档

- [OpenCode 实战教程：从零搭建一个 Node.js API 服务](/docs/opencode-shi-zhan-jiao-cheng/opencode-shi-zhan-jiao-cheng-cong-ling-da-jian-yi-ge-node-js-api-fu-wu.html)

Open Code 文档社区

© 2026 Open Code. All rights reserved.