LowHow 文档

中文

English

中文

English

深色模式

OpenCode 安装与配置实战教程：部署开源AI编程工具打造自由可控编程工作流 ​

📚 分类: 开发工具 / AI编程 ⏱️ 预计耗时: 15-20 分钟 🎯 难度: 入门 🔧 环境要求: Windows / macOS / Linux，Node.js ≥ 18.0，Git

你将学到什么 ​

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

  • [ ] 在本地成功安装并启动 OpenCode 终端界面
  • [ ] 切换并使用免费大模型进行 AI 辅助编程
  • [ ] 安装并配置核心插件 oh-my-opencode，让 AI 具备多角色协同能力
  • [ ] 安装 superpowers 技能包，提升 AI 的工程化能力
  • [ ] 掌握 10 个高频使用技巧，从“看着 AI 写”进阶到“用流程管 AI”

最终效果 ​

安装完成后，你将在终端中看到一个交互式 AI 编程助手界面。你可以直接输入自然语言指令（如“帮我写一个计算器函数”），AI 会自动生成代码、分析项目结构、甚至执行自动化测试。通过插件和技能包，AI 将具备团队级协作能力，能拆解任务、规划步骤、审查代码质量。

前置准备 ​

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

检查项要求版本验证命令
Node.js≥ 18.0node -v
npm≥ 9.0npm -v
Git≥ 2.30git --version

1. 安装 Node.js（如果尚未安装） ​

如果你还没有安装 Node.js，请访问 https://nodejs.org 下载并安装当前最新稳定版（LTS）。

💡 提示：安装完成后，打开一个新终端窗口，运行 node -v 和 npm -v 确认安装成功。

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

🎯 目标：在你的电脑上安装 OpenCode 命令行工具，并验证安装成功。

📝 操作：

根据你的操作系统，选择以下任意一条命令执行：

bash
# 方式一：使用 curl（推荐，适用于 macOS / Linux）
$ curl -fsSL https://opencode.ai/install | bash

# 方式二：使用 npm（通用，适用于所有平台）
$ npm install -g opencode-ai

# 方式三：使用 bun（需要先安装 bun）
$ bun add -g opencode-ai

# 方式四：使用 Homebrew（仅适用于 macOS）
$ brew install anomalyco/tap/opencode

# 方式五：使用 paru（仅适用于 Arch Linux）
$ paru -S opencode

⚠️ 注意：如果你在国内网络环境下下载速度较慢，可以配置 npm 镜像源：

bash
$ npm config set registry https://registry.npmmirror.com
$ npm install -g opencode-ai

✅ 验证：安装完成后，运行以下命令确认安装成功：

bash
$ opencode --version
# 预期输出类似：v1.x.x（具体版本号）

💡 提示：如果遇到权限错误（如 EACCES），在命令前加 sudo（macOS/Linux）或以管理员身份运行终端（Windows）。

第 2 步：启动 OpenCode 并切换免费模型 ​

🎯 目标：首次启动 OpenCode，进入欢迎界面，并切换到一个免费大模型。

📝 操作：

  1. 在终端中直接输入 opencode 并回车：
bash
$ opencode

  1. 你会看到一个交互式终端界面。首次启动可能需要几秒钟加载。

  2. 在终端中输入以下命令查看可用模型列表：

text
/models

  1. 你会看到一系列模型名称，其中带有 free 标签的是可以免费使用的。例如：

    • HY3 (free)
    • MiniMax M2.5 (free)
    • Nemotron 3 super (free)

  2. 选择一个免费模型，输入模型名称切换即可（例如：HY3）。

🤔 为什么要这样做？ OpenCode 默认自带免费大模型，你无需额外配置 API Key 或付费，开箱即用。这对于初学者来说非常友好，降低了入门门槛。

✅ 验证：成功切换到免费模型后，你会看到终端提示当前已激活的模型名称。你可以输入一句简单的指令测试，例如：

text
帮我写一个 Python 函数，计算斐波那契数列的第 n 项

AI 应该会开始生成代码。

⚠️ 常见错误：

  • 如果遇到 Error: Cannot find module 等错误，说明依赖未完全安装。尝试重新运行安装命令。
  • 如果模型切换后无响应，可能是网络问题。检查你的网络连接，或尝试切换其他免费模型。

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

🎯 目标：安装官方推荐的插件 oh-my-opencode，让 AI 具备多角色协同能力（预置 LSP/AST/MCP 工具链），从“单兵作战”升级为“团队配合”。

📝 操作：

  1. 首先，在终端中安装 oh-my-opencode 插件：
bash
$ npm install -g oh-my-opencode
  1. 然后，运行安装命令进行配置：
bash
$ npx -y oh-my-opencode install --no-tui --claude=no --gemini=no --copilot=no

💡 提示：参数 --no-tui 表示不使用图形界面安装；--claude=no、--gemini=no、--copilot=no 表示跳过这些模型的配置，因为我们使用 OpenCode 自带的免费模型。

  1. 找到 OpenCode 的配置文件。配置文件路径为：

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

  2. 用文本编辑器打开这个文件，追加以下配置内容：

json
{
  "plugin": ["oh-my-opencode@latest"],
  "$schema": "https://opencode.ai/config.json"
}

⚠️ 注意：如果文件已经存在其他内容，请不要删除原有配置，只需在 plugin 数组中追加 "oh-my-opencode@latest"。如果文件不存在，则直接创建这个文件并写入上述内容。

✅ 验证：

  1. 重新启动 OpenCode（退出后再次运行 opencode）。
  2. 首次启动会稍慢（自动拉取最新依赖），耐心等待。
  3. 当终端输出类似 Sisyphus 的提示时，说明插件加载成功。
  4. 此时按 Tab 键，你应该可以看到 Plan 模式与 Build 模式之间的切换。

🤔 为什么要这样做？oh-my-opencode 插件给 AI 内置了多角色协同能力，包括规划、执行、审查等不同角色的 Agent。没有它时，AI 只能“单兵作战”；有了它，AI 能像一个小团队一样工作，先规划再执行，大幅提升代码质量和开发效率。

第 4 步：安装 Skills 技能包 ​

🎯 目标：为 AI 安装两个核心技能包——superpowers（专家级任务拆解）和 planning-with-files（标准研发流模拟），让 AI 做事更“稳”。

📝 操作：

  1. 打开浏览器，访问技能包市场：https://skills.sh/

  2. 在技能市场中，找到以下两个技能包：

    • superpowers：提供专家级任务拆解、计划编排、测试驱动流程
    • planning-with-files：模拟标准研发流程（需求→架构→排期→执行→归档）

  3. 进入技能详情页，复制安装命令。或者直接使用以下命令安装：

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

# 安装 planning-with-files 技能包
$ npx skills add https://github.com/othmanadi/planning-with-files --skill planning-with-files-zh

💡 提示：如果你希望全局安装（所有项目都能使用），可以添加 -g 参数：

bash
$ npx skills add <owner/repo> --skill '*' -g

⚠️ 注意：技能包不是越多越好。AI 当前的智能度还不足以在海量技能中精准路由。建议精选 2~3 个高频场景的技能包，效果最佳。

✅ 验证：安装完成后，重新启动 OpenCode，输入一个复杂的任务（如“帮我重构这个项目的用户认证模块”），观察 AI 是否能够先输出步骤拆解和计划，再执行代码修改。

进阶技巧：10 个高频使用技巧 ​

掌握基础安装后，以下 10 个技巧将帮助你从“看着 AI 写”进阶到“用流程管 AI”。

技巧 1：上下文与记忆管理——使用 /init 生成项目说明书 ​

在项目根目录执行 /init，AI 会自动扫描项目结构并生成 AGENTS.md 文件（务必提交 Git 版本控制）。这是 AI 理解你项目的“第一份地图”，类似 Claude Code 的 claude.md。

text
/init

技巧 2：精准控制范围——使用 @文件/目录 语法 ​

终端 Agent 容易“脑补”无关代码。使用 @ 符号指定文件或目录，能大幅降低幻觉：

text
@src/service/order.go 帮我分析这里的并发隐患

技巧 3：压缩对话上下文——使用 /compact ​

长会话容易跑偏或超出 Token 限制。定期执行此命令，让上下文“瘦身”，保留核心决策链路，聚焦主线逻辑。

text
/compact

技巧 4：Plan / Build 双模工作流 ​

按 Tab 键可在 Plan 模式和 Build 模式间无缝切换。强烈建议先 Plan 后 Build：

  • 切到 Plan 模式，让 AI 输出步骤拆解、风险点与修改清单
  • 确认无误后，再切回 Build 模式执行

返工率直降 50%。

技巧 5：代码时光机——/undo 与 /redo ​

改错了不用手动 git revert。底层基于 Git 版本控制，一键撤销最后一条消息及所有文件变更。

text
/undo
/redo

技巧 6：快速开启新会话——/new ​

比重启终端快得多，适合开启全新任务分支，彻底清空历史上下文干扰。

text
/new

技巧 7：自定义 Agent 与权限隔离 ​

执行以下命令可创建专属角色（如 review-agent、test-agent）：

bash
$ opencode agent create

配合 opencode.json 的权限配置，可实现“核心分支禁止自动推送”、“安全扫描只读不写”等精细化管控。

技巧 8：非交互模式跑脚本 ​

可无缝接入 Git Hooks、CI 流水线：

bash
$ opencode -p "Review this diff and summarize risks"

实现 PR 自动审查、Commit Message 生成、自动化文档注释等工程化功能。

技巧 9：一键切模型——/connect 与 /models ​

免费模型卡顿时，终端内直接配置 API Key、切换主力模型（支持 GPT/Claude/Gemini/Kimi/Minimax 等），不中断当前会话。

text
/connect
/models

技巧 10：IDE 深度集成 ​

在 VS Code / Cursor 插件市场搜索 opencode 安装后，使用快捷键即可在分屏终端直接呼出会话：

  • Windows / Linux: Ctrl + Esc
  • macOS: Cmd + Esc

无需来回切换窗口。

常见问题 (FAQ) ​

Q1: 安装时报错 EACCES: permission denied 怎么办？A: 说明权限不足。在命令前加 sudo（macOS/Linux）或以管理员身份运行终端（Windows）。或者使用 npm 的 --global 参数配合 sudo。

Q2: 启动 OpenCode 后界面卡住或空白？A: 可能是网络问题导致无法加载资源。检查网络连接，尝试使用代理或切换镜像源。如果持续卡住，使用 Ctrl+C 退出后重试。

Q3: 切换模型后 AI 无响应？A: 可能是所选模型暂时不可用。尝试切换其他免费模型（如 HY3、MiniMax M2.5）。如果问题持续，检查网络或重启 OpenCode。

Q4: 安装了 oh-my-opencode 插件后，按 Tab 键没有反应？A: 确认配置文件 opencode.json 已正确添加 plugin 配置。重启 OpenCode 后等待几秒让插件加载。如果仍然无效，尝试重新执行安装命令。

Q5: 安装技能包时提示 npx: command not found？A: 说明 npm 未正确安装或不在环境变量中。重新安装 Node.js，或使用完整路径运行（如 C:\Program Files\nodejs\npx）。

总结 ​

恭喜你完成了本教程！🎉

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

  1. 一键安装 OpenCode：通过 npm/curl 等方式快速安装，无需复杂配置
  2. 切换免费模型：开箱即用，无需 API Key 即可体验 AI 编程
  3. 安装核心插件 oh-my-opencode：让 AI 从“单兵作战”升级为“团队配合”
  4. 安装技能包：通过 superpowers 和 planning-with-files 提升 AI 的工程化能力
  5. 掌握 10 个高频技巧：从 /init 生成项目说明书到 IDE 深度集成，全面提效

© 2026 LowHow