OpenCode 保姆级部署教程：终端开源 AI 编程助手从零到一完整搭建

OpenCode 官方终端界面截图

OpenCode 是 sst 团队（后来演进为 anomalyco）出品的开源终端 AI 编程 Agent，截至本文写作时在 GitHub 上收获约 22 万 Star，是当下终端里最热门的开源编码 Agent 之一。它跑在你的终端里，读你的项目、改代码、跑命令、看报错，全程在你眼皮底下。它不是闭源 SaaS 的套壳——从 CLI 到桌面 Beta 应用全开源，模型由你自己选。

为什么值得用？第一，它的安装方式极度简单，一行 curl 脚本搞定，不需要 Node 环境也能跑。第二，它内置两个角色——build（全权开发）和 plan（只读分析），按 Tab 切换，探索陌生代码库时用 plan 模式不会误改文件。第三，它支持 npm、brew、pacman、nix、mise 几乎所有包管理器，跨 macOS / Linux / Windows。本文从零开始，把 OpenCode 在你的终端里装好、配上模型、跑通第一个任务。

一、项目介绍与适用场景

OpenCode 是一个 TUI（终端图形界面）形态的 AI 编程助手。你在项目目录敲 opencode，它进入全屏界面，你用自然语言下任务，它读文件、写代码、跑命令、看报错、迭代修复。适合：

重度终端党：不想离开 iTerm / Alacritty / VS Code 内置终端写代码。
远程服务器开发：SSH 登录的开发机，没有图形界面，需要终端里的 AI 搭档。
多模型用户：一天切好几个模型，不想被某一家绑死。
想二次开发：它开源，可接自己的模型端点、自定义 agent。

二、核心功能逐条拆解

双 Agent 角色：build（默认全权开发）和 plan（只读分析，默认拒绝改文件、跑 bash 前要确认），按 Tab 切换。
general 子代理：内部用于复杂搜索和多步任务，用 @general 在消息里调用。
多模型接入：OpenAI、Anthropic、Gemini、OpenRouter、本地 Ollama 等都能接。
桌面 Beta：除了 CLI，还有 macOS / Windows / Linux 桌面应用，从 opencode.ai/download 下载。
全平台安装：curl 一键脚本、npm、brew、pacman、paru、mise、nix 全支持。
安装目录固定：脚本安装到 $HOME/.opencode/bin，不污染系统目录。
开源可扩展：文档站 opencode.ai/v2/docs 提供配置、agent 自定义说明。

三、全套官方链接

类型	链接
GitHub 仓库	https://github.com/anomalyco/opencode（原 sst/opencode 已迁移）
官方文档	https://opencode.ai/v2/docs
桌面版下载	https://opencode.ai/download
npm 包	https://www.npmjs.com/package/@opencode/cli

四、硬件与环境前置要求

OpenCode 本体是单个二进制，资源占用极小：

操作系统：macOS（Apple Silicon / Intel）、Linux、Windows（桌面版有 .exe；CLI 通过 WSL 或 Git Bash）。
curl 脚本安装：不需要 Node，脚本自带 Node 运行时。
npm 安装：需要 Node.js 18+。
模型侧：云端 API 只需网络；本地 Ollama 则需自己 GPU。
内存 / CPU：OpenCode 本体 < 100MB，真正吃资源的是模型。

出处：官方 README「Installation」段。

五、多平台安装步骤

5.1 一行脚本安装（推荐，全平台）

官方 README 原文：

curl -fsSL https://opencode.ai/v2/install | bash

逐段解释：-fsSL 是 curl 的 silent + follow redirect；| bash 把下载到的安装脚本管道给 shell 执行。脚本会下载对应平台的预编译二进制，装到 $HOME/.opencode/bin。

官方提示：装完要确保 $HOME/.opencode/bin 在 PATH 里。验证：

opencode --version

5.2 npm 安装（已有 Node 的环境）

官方 README 原文：

npm i -g @opencode/cli@latest

等价于 bun / pnpm / yarn：

bun i -g @opencode/cli@latest
pnpm i -g @opencode/cli@latest
yarn global add @opencode/cli@latest

5.3 Homebrew（macOS / Linux）

官方 README 给了两个 tap：

brew install anomalyco/tap/opencode-v2   # 官方推荐，永远最新
brew install opencode                      # 官方 formula，更新较慢

5.4 Arch Linux

sudo pacman -S opencode          # 稳定版
paru -S opencode-beta            # AUR 最新版

5.5 mise / nix

mise use -g opencode              # 任意 OS，用 mise 管版本
nix run github:anomalyco/opencode # Nix

5.6 桌面版（Beta）

从 https://opencode.ai/download 下载对应包：

macOS Apple Silicon：opencode-desktop-mac-arm64.dmg
macOS Intel：opencode-desktop-mac-x64.dmg
Windows：opencode-desktop-win-x64.exe
Linux：.deb / .rpm / .AppImage

macOS 也可 brew：

brew install --cask opencode-desktop

六、配置文件全部参数解释

OpenCode 首次启动会引导你配模型。官方 README 没有给出完整 config 示例，但文档站（opencode.ai/v2/docs）有完整配置参考。常见做法：

模型选择：启动后在界面里选 provider，贴 API Key。
切 agent：按 Tab 在 build / plan 之间切换。
调起子代理：在消息里写 @general 帮我搜一下这个项目里所有调用 fetch 的地方。

官方 TIP：README 明确提醒「Remove versions older than 0.1.x before installing」——从 0.1.x 旧版升级前，先删旧版再装新版，避免二进制冲突。

七、启动、后台与日常使用

7.1 启动

cd your-project
opencode

预期：进入全屏 TUI，欢迎界面后是输入框。

7.2 后台常驻

OpenCode 是交互式 TUI，官方没有提供常驻服务模式。需要 SSH 长连接时用 tmux：

tmux new -s oc
opencode
# Ctrl+B D 脱离；tmux attach -t oc 回来

7.3 修改端口

OpenCode 作为客户端不监听端口；接本地 Ollama 时改 Ollama 的 OLLAMA_HOST，再在 OpenCode 的 provider 设置里改 Base URL。

八、功能实操教程

第 1 步：用 5.1 的脚本装好，opencode --version 确认成功。

第 2 步：cd 到一个真实项目，敲 opencode。

第 3 步：首次启动按提示选模型供应商（如 Anthropic / OpenAI / OpenRouter），贴 API Key。

第 4 步：默认在 build agent 下，输入「帮我给这个项目加一个 README badge」。它会读项目结构、提议改法、写文件。

第 5 步：按 Tab 切到 plan agent，问「这个仓库的目录结构是什么样的？」。plan 模式只读，不会改文件，适合探索陌生代码库。

第 6 步：在消息里用 @general 列出所有 TODO 注释，调起子代理做跨文件搜索。

第 7 步：接本地 Ollama（如果你想离线跑）：先 ollama serve && ollama pull qwen2.5-coder，然后在 OpenCode 模型选择里选 Ollama，Base URL 填 http://localhost:11434。

九、全套报错故障排查

报错 1： opencode: command not found 原因分析：$HOME/.opencode/bin 不在 PATH。解决方案：echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc。

报错 2： 装完后启动报版本冲突。原因分析：官方 README TIP 明确——从 0.1.x 旧版升级前没删旧版。解决方案：删 $HOME/.opencode/bin/opencode 后重新跑安装脚本。

报错 3： npm 安装报 EACCES。原因分析：npm 全局目录归 root。解决方案：用 nvm 装 Node，或 npm config set prefix ~/.npm-global。

报错 4： 选了模型后 401 / 403。原因分析：API Key 没贴对或过期。解决方案：重新进模型选择界面贴 Key；注意 Anthropic 和 OpenAI 的 Key 不能混用。

报错 5： 连本地 Ollama 报 connection refused。原因分析：Ollama 没起。解决方案：ollama serve 起服务，curl http://localhost:11434 验证。

十、升级、回滚与卸载

升级：重新跑安装脚本，或 npm i -g @opencode/cli@latest、brew upgrade。

备份建议：OpenCode 配置在 ~/.config/opencode/（含 provider、模型设置），整个目录打包。

回滚：脚本支持重装；npm 版 npm i -g @opencode/cli@具体旧版本。

卸载：删 $HOME/.opencode/bin/opencode；npm 版 npm uninstall -g @opencode/cli；brew 版 brew uninstall。

十一、商用许可与合规风险提示

OpenCode 是开源项目，核心代码可自由使用、二次开发。商用前请以仓库 LICENSE 文件为准（仓库 README 未在首页显著标注 license 徽章，发布前建议再核对一次 LICENSE 文件）。注意点：模型 API 费用按你选的供应商单独结算；把公司代码喂给第三方模型时，确认供应商的数据政策；本地 Ollama 场景则完全离线。

参考链接

GitHub 仓库：https://github.com/anomalyco/opencode
官方文档：https://opencode.ai/v2/docs
桌面版下载：https://opencode.ai/download
npm 包：https://www.npmjs.com/package/@opencode/cli