香香甜甜圈1. OpenCode 到底是什么，为什么值得折腾
OpenCode 是一个开源终端 AI 编程助手。不是套壳的编辑器，也不是网页端的 ChatGPT 包装，它跑在你的终端里，跟 NeoVim、VS Code、JetBrains 系列都可以配合使用。核心定位是“帮你在真实项目里写代码、改代码、执行命令”的那个 AI 搭档，而不是简单的代码问答工具。
很多朋友把 OpenCode 和 Claude Code、Codex 混为一谈，实际上它们属于同类产品，但 OpenCode 有一个很关键的特质——模型无关。它可以接 OpenAI、Anthropic、Google Gemini、本地 Ollama，甚至任何兼容 OpenAI 接口的自部署模型。这点比 Claude Code 只能绑 Claude、Codex 跟 GitHub Copilot 绑定更灵活，对有模型切换需求的人来说特别实用。
这篇内容会覆盖 OpenCode 从零到一的完整流程：安装、模型配置、日常使用技巧、模板系统，以及我从实际项目中踩过的一些坑。适合三类人看：
- 已经在用 Cursor / Claude Code，想找个开源替代或者想多一个终端工具的开发者
- 对 AI 编程有基础了解，但没真正配置过终端 Agent 的新手
- 自己部署了模型 API，想找一个客户端把模型“用”起来的人
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 安装前的环境准备
2.1 Node.js 是前置条件
OpenCode 无论哪个版本，都要求本机有 Node.js 环境。这一点和很多人的直觉不太一样，OpenCode 底层是用 TypeScript 写的，安装包通过 npm 分发，所以 Node.js 是硬性依赖。
安装 Node.js 建议直接去官网下载 LTS 版本，不要用系统自带的 apt 源或者 yum 源里的老版本，那些版本通常很旧，装完后 OpenCode 跑起来会有各种奇奇怪怪的兼容性问题。LTS 版本目前稳定在 20.x 以上，安装完在终端确认一下：
bash复制node -v
npm -v
我遇到过不少朋友在 Windows 上装完 Node 之后，发现 npm 命令提示“不是内部或外部命令”。这个通常是因为安装时没有把 Node.js 自动加入 PATH，或者安装完成后没有重新打开终端。解决办法就是检查环境变量里有没有 Node.js 的安装目录，再重开一个终端窗口。
Zsh 用户还可以顺手配一下 npm 的全局路径，不然全局安装的包可能找不到：
bash复制npm config set prefix ~/.npm-global
echo 'export PATH=$PATH:~/.npm-global/bin' >> ~/.zshrc
source ~/.zshrc
2.2 OpenCode 的安装方式
安装 OpenCode 目前有两种主流方式，我分别说一下适用场景：
第一种是 npx 直接运行，不需要全局安装：
bash复制npx opencode
这种方式适合临时体验或者不想污染全局环境的情况。缺点是每次启动都要经历一次 npm 的解析，速度上会慢一点点。如果你只是想看看 OpenCode 长什么样，用这个方式足够了。
第二种是全局安装：
bash复制npm install -g opencode
安装完成后直接执行 opencode 就能启动。我推荐日常使用这种方式，Terminal 里启动 Agent 本来就追求快，全局安装能省掉 npx 每次解析依赖的时间。
安装完验证一下版本：
bash复制opencode --version
如果你用的是 macOS，也可以走 Homebrew 安装：
bash复制brew install sst/tap/opencode
不过 brew 版本有时候更新不及时，npm 全局安装通常是最快拿到新版本的渠道。