Ubuntu 22.04 安装 OpenCode 2.1 指南

目标：在一台 Ubuntu 22.04 服务器上从零安装 OpenCode（开源 AI 编程代理）2.1 稳定版，覆盖官方安装脚本、npm 包、独立二进制三种在线方案与升级、卸载全流程，并以本地 Ollama（OpenAI 兼容端点）完成首次运行验证。全部命令与输出均在 Ubuntu 22.04（x86_64）实测通过，实测日期 2026-10-23。

一、环境信息

本文所有步骤在以下环境实测，输出均为真实回显：

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• OpenCode 版本：2.1.3（npm 包 @opencode/cli 的 latest 标签，2026-10-23 实查 npm registry）
• Node.js：22.23.4（npm 方案前置）
• npm：10.9.9
• Ollama：0.40.8（用于无真实 API Key 时的本地 LLM 验证）
• 演示模型：qwen2.5:0.5b（397 MB）、qwen3:0.6b（522 MB）
• 实验账号：root

💡 说明：OpenCode 是终端 AI 编程代理，本身不依赖数据库与常驻端口（v2 会在本机拉起后台服务与本地 API，默认监听 127.0.0.1 回环地址）。安装主体只是一个约 230 MB 的可执行文件，对系统侵入性很小。

二、前置条件

1. 一台可联网的 Ubuntu 22.04 服务器（x86_64 或 arm64），具备 sudo 或 root 权限。
2. 基础工具齐备：

apt-get update && apt-get install -y curl ca-certificates git

实测回显（节选，首次执行输出较长，此处为首尾）：

Get:1 http://archive.ubuntu.com/ubuntu jammy InRelease [270 kB]
...
Setting up git (1:2.34.1-1ubuntu1.11) ...

3. 一个可用的 LLM 凭据（任选其一）：
   • OpenCode 官方免费模型组：安装后无需任何 Key，TUI 内 /models 可直接选择 Free 模型（官方文档与实测模型选择器均可见 6 个 Free 模型）；
   • 商业 API Key（Anthropic/OpenAI/Google 等）：通过 opencode auth login 或 TUI 内 /connect 录入；
   • 本地 OpenAI 兼容端点（如 Ollama）：本文第九章以 Ollama 0.40.8 做最小验证。
4. 磁盘空间：安装产物约 230 MB，预留 1 GB 以上；若用本地模型，另按模型体积预留（本文两个演示模型共约 900 MB）。

⚠️ 注意：服务器若只能经 HTTP 代理出网，curl、npm 均需显式带代理参数（如 curl -x http://192.168.1.62:7897）或设置 http_proxy/https_proxy 环境变量，否则下载会长时间无响应——这是网络受限环境安装失败的第一常见原因（见第十一章排障实录 1）。

三、版本选型说明

OpenCode 当前存在 1.x 与 2.x 两条版本线，分属不同的发行渠道，安装前必须先选定。以下均为 2026-10-23 实查官方渠道的结果：

关键差异与如何选型：

• 全新安装选 2.x（本文主线）：官方 README 与文档站均以 2.x 为主（桌面版、Web 界面、opencode serve 的 v2 API 与 Web 服务、Code Mode 等 v2 能力）。
• 1.x 安装不会被自动升级到 2.x：官方 1.19.2/1.19.0 发布说明明确"1.x 安装永远不会在常规更新中被提供 2.x 构建，升级到 OpenCode 2 是 /update 或 opencode upgrade --major 中的显式选择"，两条线并存可控。
• GitHub Releases 页当前最新发布为 v1.19.4（1.x 线），2.x 经 npm @opencode/cli 与官方更新通道分发，查询日期 2026-10-23。

💡 技术拓展：OpenCode 官方还提供 OpenCode Console（统一的模型计费控制台）与 OpenCode Go（约 $10/月的编码模型订阅），并在产品内置"Zen 免费模型组"。若不愿自管 API Key，可直接用免费模型起步；本文为通用性考虑，采用"自定义 OpenAI 兼容端点 + 本地模型"的免 Key 路径验证。

四、方案 A：官方安装脚本在线安装（推荐）

4.1 方案说明

官方一键脚本（来源：官方仓库 README 与文档站，2026-10-23 实查）会自动识别平台架构（glibc/musl、x64/arm64），下载对应二进制并安装到用户目录，可选地修改 shell 配置写入 PATH。适合快速上手的单机部署。

4.2 执行安装

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

实测回显（完整保留）：

                                 ▄
█▀▀█ █▀▀█ █▀▀█ █▀▀▄ █▀▀▀ █▀▀█ █▀▀█ █▀▀█
█░░█ █░░█ █▀▀▀ █░░█ █░░░ █░░█ █░░█ █▀▀█
▀▀▀▀ █▀▀▀ ▀▀▀▀ ▀  ▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀


OpenCode includes free models, to start:

exec $SHELL   # Reload PATH (or open a new terminal)
cd <project>  # Open directory
opencode      # Run command

For more information visit https://opencode.ai/v2/docs

脚本默认安装到 $HOME/.opencode/bin，并自动向 shell 配置写入 PATH。实测 ~/.bashrc 尾部新增：

# opencode
export PATH=/root/.opencode/bin:$PATH

使新 PATH 生效并验证版本：

exec $SHELL
opencode --version

实测回显：

opencode v2.1.3

确认安装位置与体积：

which opencode && ls -lh /root/.opencode/bin/opencode

实测回显：

/root/.opencode/bin/opencode
-rwxr-xr-x 1 root root 230M Oct 22 21:52 /root/.opencode/bin/opencode

4.3 安装目录优先级与自定义

官方脚本按以下优先级决定安装路径（来源：官方仓库 README）：

1. $OPENCODE_INSTALL_DIR —— 自定义目录；
2. $XDG_BIN_DIR —— XDG 规范路径；
3. $HOME/bin —— 存在或可创建时；
4. $HOME/.opencode/bin —— 默认兜底。

装到系统全局路径（root 服务器常用）：

OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/v2/install | bash

不想让脚本改 shell 配置时：

curl -fsSL https://opencode.ai/v2/install | bash -s -- --no-modify-path

安装指定版本（接受带或不带 v 前缀的版本号）：

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

验证安装路径按预期生效：

which opencode && opencode --version

实测回显（自定义目录为 /usr/local/bin 的服务器上）：

/usr/local/bin/opencode
opencode v2.1.3

⚠️ 注意：脚本支持 --binary <path> 从本地二进制安装（离线服务器可将第 4.5 节下载的 tar 包解出的二进制直接以该方式安装，或手动复制到 PATH 内，效果等价）。

4.4 脚本参数速查（实测 --help 节选）

OpenCode Installer

Usage: install.sh [options]

Options:
    -h, --help              Display this help message
    -v, --version <version> Install a specific version (e.g., 0.0.0-beta-17236)
    -b, --binary <path>     Install from a local binary instead of downloading
        --no-modify-path    Don't modify shell config files (.zshrc, .bashrc, etc.)

五、方案 B：npm 包在线安装

5.1 方案说明

npm 包 @opencode/cli 是 2.x 线的官方 npm 发行渠道（包内 postinstall 脚本按平台选择原生二进制，来源：官方文档）。适合已标准化管理 Node.js 的服务器，便于纳入现有 npm 全局包运维体系。

5.2 安装 Node.js 22 LTS

Ubuntu 22.04 官方源中的 nodejs 版本过旧，直接从 nodejs.org 装 LTS 二进制包（版本号以 nodejs.org 实时目录为准，本文实装 22.23.4）：

curl -fsSL https://nodejs.org/dist/latest-v22.x/ | grep -oE 'node-v22[0-9.]*-linux-x64.tar.xz' | head -1

实测回显：

node-v22.23.4-linux-x64.tar.xz

apt-get install -y xz-utils
curl -fL -o /tmp/node.tar.xz https://nodejs.org/dist/latest-v22.x/node-v22.23.4-linux-x64.tar.xz
tar -xJf /tmp/node.tar.xz -C /usr/local --strip-components=1
node -v && npm -v

实测回显：

v22.23.4
10.9.9

5.3 安装 OpenCode

npm install -g @opencode/cli@latest
opencode --version

实测回显：

added 1 package in 2m
opencode v2.1.3

确认安装位置：

which opencode

实测回显：

/usr/local/bin/opencode

⚠️ 注意：以非 root 用户使用 npm 全局安装遇到 EACCES 权限错误时，官方 npm 建议改用用户级前缀（npm config set prefix ~/.npm-global 并把 ~/.npm-global/bin 加入 PATH），不要用 sudo npm i -g 混用权限。本文环境为 root，未触发该问题。

5.4 其他包管理器（官方文档列法，未逐一实测）

官方文档同页列出：bun install -g --trust @opencode/cli、pnpm add -g --allow-build=@opencode/cli @opencode/cli、yarn global add @opencode/cli、Homebrew brew install anomalyco/tap/opencode-v2、Arch paru -S opencode-beta、mise use -g opencode（需 mise 2026.10.9+，旧版会装 OpenCode 1）。Windows 不提供包管理器支持（官方文档明示）。

六、方案 C：独立二进制直装

6.1 方案说明

适合不装 Node、不跑脚本的场景：从官方更新通道直接下载平台对应的压缩包，解压出一个约 230 MB 的单体可执行文件（内置 Bun 运行时），放到 PATH 即可。以下为 Linux x64 (glibc) 包实测。

6.2 下载与安装

curl -fL -o /tmp/oc-linux-x64.tar.gz 'https://opencode.ai/update/api/latest/cli/opencode/opencode-linux-x64.tar.gz'
ls -lh /tmp/oc-linux-x64.tar.gz

实测回显：

-rw-r--r-- 1 root root 110M Oct 23 06:06 /tmp/oc-linux-x64.tar.gz

解压并部署：

mkdir -p /opt/opencode
tar -xzf /tmp/oc-linux-x64.tar.gz -C /opt/opencode
ls -lh /opt/opencode/

实测回显：

total 235M
-rwxr-xr-x 1 root root 230M Jan  1  1970 opencode

写入全局 PATH 并验证：

ln -sf /opt/opencode/opencode /usr/local/bin/opencode
opencode --version

实测回显：

opencode v2.1.3

💡 说明：官方下载页还提供 linux-arm64、linux-musl（Alpine 等无 glibc 环境）与 baseline 指令集变体，以及 macOS/Windows 桌面版（dmg/exe/deb/rpm/AppImage）。musl 变体是 Alpine 服务器唯一可用的直装形态。

七、方案对比与选择建议

如何选型：可联网的常规服务器选 A 最省事；团队统一用 npm 管理 CLI 工具选 B；离线或最小化系统选 C，先在有网机器下载 tar 包再传内网。

八、安装后基础配置

8.1 全局数据与配置路径

OpenCode 的全局路径可用自带命令查看：

opencode debug paths

实测回显：

home       /root
data       /root/.local/share/opencode
cache      /root/.cache/opencode
config     /root/.config/opencode
state      /root/.local/state/opencode
tmp        /tmp/opencode
bin        /root/.cache/opencode/bin
log        /root/.local/share/opencode/log
repos      /root/.local/share/opencode/repos
db         /root/.local/share/opencode/opencode.db

要点：全局配置文件位于 ~/.config/opencode/opencode.json；会话与日志落 ~/.local/share/opencode（内含 SQLite 数据库 opencode.db）；升级相关的二进制缓存落 ~/.cache/opencode/bin。

8.2 默认模型与自定义 OpenAI 兼容端点

OpenCode 自带 models.dev 模型目录，装好后即可在 TUI 用 /connect 接入商业账号、在 /models 选择模型；对自托管网关或本地推理服务（Ollama/vLLM 等），在全局配置声明一个自定义 provider 即可。本文写入 ~/.config/opencode/opencode.json（完整字段解释见《OpenCode 2.1 配置参数详解》）：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama/qwen2.5:0.5b",
  "providers": {
    "ollama": {
      "name": "Ollama",
      "env": ["OLLAMA_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": { "baseURL": "http://127.0.0.1:11434/v1" },
      "models": {
        "qwen2.5:0.5b": { "name": "Qwen2.5 0.5B" }
      }
    }
  }
}

逐项说明：model 为 provider/model 引用格式，作为默认模型；providers.ollama 为自定义 provider 键名；env 声明凭据环境变量名（本地 Ollama 不校验值，但变量必须存在）；package 指定 OpenAI 兼容运行时；settings.baseURL 指向端点（Ollama 的 OpenAI 兼容前缀固定为 /v1）；models 键名即模型 ID。改完执行 opencode reload 或重启会话生效。

九、安装验证（含本地模型端到端）

9.1 基础验证

opencode --version && opencode --help | head -8

实测回显：

opencode v2.1.3
DESCRIPTION
  OpenCode command line interface

USAGE
  opencode <subcommand> [flags] [<directory>]

9.2 Ollama 本地模型最小验证（无真实 API Key 路径）

在服务器上安装 Ollama（以官方脚本安装 0.40.8 为例）：

curl -fsSL https://ollama.com/install.sh | sh
ollama --version

实测回显（版本）：

ollama version is 0.40.8

拉取演示模型并确认 OpenAI 兼容端点就绪：

ollama pull qwen2.5:0.5b
curl -s http://127.0.0.1:11434/v1/models

实测回显：

{"object":"list","data":[{"id":"qwen2.5:0.5b","object":"model","created":1792706205,"owned_by":"library"}]}

设置 provider 凭据变量（8.2 已配置 provider）后，用非交互模式做一次端到端验证：

export OLLAMA_API_KEY=ollama
cd /root/demo-app
opencode run "请用一句话回答：calc.py 里的 add 函数是做什么的？"

实测回显：

> build · qwen2.5:0.5b
"a函数"

⚠️ 注意：回答质量差是 0.5B 量级本地模型的固有限制，不是安装问题——链路（配置解析 → OpenAI 兼容请求 → 模型响应 → 终端输出）已全通。换用 agent 工具调用任务时，0.6B/1.5B 小模型经常把工具调用输出成 JSON 文本而不真正执行（实测确有发生），生产建议使用 7B 以上支持 function calling 的模型或商业 API。交互式 TUI 与命令详解见《OpenCode 2.1 常用 CLI 命令详解》。

验证模型已注册进 OpenCode：

opencode models | grep -x 'ollama/qwen2.5:0.5b.*'

实测回显：

ollama/qwen2.5:0.5b

十、升级与多版本管理

10.1 自升级命令

opencode upgrade --help

实测回显：

DESCRIPTION
  Upgrade OpenCode to the latest or a specific version

USAGE
  opencode upgrade [flags] [<target>]

ARGUMENTS
  target string    Version to upgrade to (with or without a leading v) (optional)

FLAGS
  --method, -m choice    Installation method to use (choices: curl, npm, pnpm, bun, yarn, vp, brew, winget)

要点：

• 升级到 2.x 同线最新版：opencode upgrade；指定版本：opencode upgrade 2.1.3；
• 跨大版本升级到 OpenCode 2 是显式动作：opencode upgrade --major（官方 1.19.0 发布说明）；
• --method 可强制按指定安装方式升级（如 npm 安装的实例被识别为 curl 时用 opencode upgrade --method npm）；
• 1.x 用户在 TUI 内可用 /update 手动安装更新或选择升级 2.x（1.19.0 起 TUI 更新不再自动安装）。

10.2 多版本并存

不同安装方式的产物落点不同，可并存：脚本版在 ~/.opencode/bin，npm 版在 npm 全局 bin，独立二进制自定位置。PATH 顺序决定默认 opencode 指向谁；opencode --version 即可确认当前生效版本。官方提示：安装 2.x 前应移除 0.1.x 及更早的历史版本（官方 README Tip）。

十一、常见问题（含排障实录）

Q1：下载 opencode/Node 极慢或卡住不动？ 排障实录：受限网络下 apt-get update、curl 直连官方源会长时间停在 0%。定位：curl -I https://opencode.ai 无响应即网络出口问题。解决：统一走 HTTP 代理——export http_proxy=http://192.168.1.62:7897 https_proxy=http://192.168.1.62:7897 后重试；apt 场景写 /etc/apt/apt.conf.d/99proxy（Acquire::http::Proxy "http://192.168.1.62:7897";），npm 可 npm config set proxy 同理。实测改走代理后 apt 以 115 kB/s 完成更新，opencode 安装正常。

Q2：opencode: command not found？ 安装脚本默认装到 ~/.opencode/bin，若当前 shell 未重载 PATH 就会找不到。解决：exec $SHELL 或手动 export PATH=$HOME/.opencode/bin:$PATH；用 --no-modify-path 安装的实例必须自行把安装目录写入 PATH。

Q3：npm 全局安装报 EACCES 权限错误？ 不要 sudo npm i -g。改用用户级前缀：npm config set prefix ~/.npm-global，并把 ~/.npm-global/bin 加入 PATH 后重装；或改用方案 A/C。

Q4：无 systemd 的精简系统里能装吗？ 能。OpenCode 不依赖 systemd：v2 的后台服务由 CLI 自己管理（opencode service start/stop/status）。在无 systemd 的最小化环境中实测，脚本安装、npm 安装、opencode run 全部正常。

Q5：TUI 打开中文乱码？ 终端需 UTF-8 与等宽中文字体支持。服务器侧确认 locale 含 UTF-8，客户端终端选支持 CJK 的等宽字体即可。

Q6：升级时被提示需要选择安装方式？ opencode upgrade 无法识别安装来源时（如手动复制的二进制），用 --method 显式指定，或按第十章 10.2 的落点自行管理多版本。

十二、卸载与清理

OpenCode 自带卸载命令，先预演再执行：

opencode uninstall --dry-run

实测回显：

┌  Uninstall OpenCode
│
●  Installation method: curl
│
│  The following global files will be removed (shared by OpenCode versions and channels):
│
●    Cache: /root/.cache/opencode
│
●    Binary (manual removal): /root/.opencode/bin/opencode
│
▲  Dry run - no changes made
│
└  Done

确认无误后正式卸载（-f 跳过确认；会话数据、配置与状态按官方设计保留）：

opencode uninstall -f

彻底清理（按需选择）：

rm -rf /root/.opencode                # 脚本安装的二进制与垫片
rm -rf /root/.config/opencode         # 全局配置
rm -rf /root/.local/share/opencode    # 会话数据与日志（含 opencode.db）
rm -rf /root/.cache/opencode          # 缓存
npm uninstall -g @opencode/cli        # npm 方案的卸载
rm -f /usr/local/bin/opencode && rm -rf /opt/opencode   # 独立二进制方案

最后核对：

which opencode || echo 'opencode 已卸载'

实测回显：

opencode 已卸载

十三、参考链接

• 官方网站：https://opencode.ai/
• 官方仓库（GitHub）：https://github.com/anomalyco/opencode （原 sst/opencode）
• 官方文档（v2）：https://opencode.ai/v2/docs
• 安装文档：https://opencode.ai/v2/docs （CLI 安装一节）
• npm 包（2.x）：https://www.npmjs.com/package/@opencode/cli
• npm 包（1.x 维护线）：https://www.npmjs.com/package/opencode-ai
• GitHub Releases：https://github.com/anomalyco/opencode/releases
• 模型目录：https://models.dev/
• 本地模型（Ollama）：https://ollama.com/

站内相关：《Ubuntu 22.04 安装 OpenCode 2.1 指南》、《OpenCode 介绍与选型指南》