OpenCode 安装完全指南：从一行 curl 到 v2 共享服务，附 v1 迁移！

admin@yesmiracle.net (万戈) — Sun, 04 Oct 2026 00:00:00 +0000

之前那篇《OpenCode 源码深度拆解：Effect TS 代数效应系统构建的智能编码 Agent》拆的是它的内部架构——Effect TS、四轴 LLM 路由、双 Agent 循环。文章底下问得最多的一类问题是：「所以到底怎么装？」

这篇就把它补上。我不打算复述官网的流水账，而是按我自己在一台干净机器上把它跑通的顺序来写：选哪条安装路径、v2 的「共享后台服务」到底是什么、配置写在哪个文件才会生效、怎么接上模型、以及跑第一个会话时会碰到的那些小坑。顺带说一句：如果你还在用 v1，现在是个动手迁移的时间点。

先说结论——OpenCode 现在的默认版本是 v2，命令行装的是 @opencode/cli，不是以前那个 opencode-ai。 这一点搞混了，后面所有命令都会对不上。

四条路，选一条就好

先看一张表。它是我自己会用来决策的那张，不是官网的复制。

你的情况	推荐路径	关键命令	大概耗时
刚接触，想最快跑起来	官方脚本	`curl -fsSL https://opencode.ai/v2/install \| bash`	1 分钟
Mac 用户，机器上已有一堆 brew tap	Homebrew	`brew install anomalyco/tap/opencode-v2`	2 分钟
团队用 npm 统一管全局 CLI	npm（v2 包）	`npm install -g @opencode/cli`	2 分钟
想要窗口界面 / 多端接入	桌面版 + Web / Docker	下安装包，或 `ghcr.io/anomalyco/opencode`	5 分钟

一句话原则：一台机器只留一条路径。这三条路都能往 PATH 里塞一个叫 opencode 的二进制，混装之后你排查问题时根本不知道跑的是哪一个。真要装也别同时装，装完立刻 opencode --version 确认一下。

装之前需要准备什么

两样东西就够了。

一是终端。OpenCode 的 TUI 用了真彩色，官方推荐的终端是 Ghostty、WezTerm、Alacritty、Kitty 这几个。没有也能跑，只是主题配色会退化成近似色，不影响功能。

二是模型凭证。你可以用自己已有的任意 provider 的 API Key，也可以在 TUI 里跑 /connect 走官方那套 OpenCode Console。如果只是想先试试，OpenCode Go 是个每月 $10 的订阅，专门给你开放一批主流开源编码模型，算是新人摩擦最小的一条路。

路径一：官方脚本（推荐）

一行命令：

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

这个安装脚本有几个参数值得知道，尤其是在做批量部署的时候：

# 装一个指定版本（做灰度时把机器钉在已知版本上）
curl -fsSL https://opencode.ai/v2/install | bash -s -- --version 2.0.22

# 已经手上有本地二进制，只想让它帮忙放到位
curl -fsSL https://opencode.ai/v2/install | bash -s -- --binary /path/to/opencode

# 我的 shell 配置文件由配置管理工具托管，别去改它
curl -fsSL https://opencode.ai/v2/install | bash -s -- --no-modify-path

脚本默认会帮你把 opencode 加到 PATH。如果你用 Nix、Ansible 这类工具管环境，就用 --no-modify-path 自己接管。

路径二：Homebrew

Mac 和 Linux 都能用。注意 tap 名字带 -v2：

brew install anomalyco/tap/opencode-v2

这里有个容易踩的坑：Homebrew 官方仓库里也有一个 opencode formula，但那个更新慢，追不上版本。要最新的就用 anomalyco/tap/opencode-v2 这个 tap。v1 时代的 tap 是 anomalyco/tap/opencode（不带 v2），别装错。

路径三：npm（给用 npm 管全局工具的团队）

npm install -g @opencode/cli

这个包是 v2 的。Bun 和 pnpm 需要额外放行一个脚本，否则会出现「装成功了，但真正的原生二进制没落下来」这种最气人的失败：

bun install -g --trust @opencode/cli
pnpm add -g --allow-build=@opencode/cli @opencode/cli

npm 包靠一个 postinstall 脚本去挑对应平台的原生二进制，Bun 和 pnpm 默认会拦掉生命周期脚本，所以不加参数的话命令会「成功」返回，然后 opencode 一跑就找不到文件。yarn 和 Vite+（vp install -g @opencode/cli）则不需要额外参数。Arch 用户可以直接走 AUR：paru -S opencode-beta。

路径四：桌面版、Web 和 Docker

OpenCode 现在不只是终端里的东西。同一个后台服务后面挂着好几种客户端，你想用哪个都行。

桌面版直接下对应平台的安装包——macOS、Windows，以及 Linux 的 .deb、.rpm、AppImage 都有。

想做 Web 访问，在装好 CLI 的机器上跑：

opencode pair

它会打印一个本地地址和一组临时用户名密码，端口是随机分的，形如 http://127.0.0.1:49374。手机、平板浏览器打开就能接上同一个服务。

Docker 走版本化标签：

docker run -it --rm ghcr.io/anomalyco/opencode:2.0.0

注意Windows 不支持用包管理器装。官方文档写得很明确：Windows 上要么下独立二进制，要么进 WSL。别去翻什么 Chocolatey、Scoop、Winget 的配方，v2 这条线没有。这是 v2 和 v1 一个明显的分歧——v1 当年是给了 choco install opencode 和 scoop install opencode 的。

v2 到底变了什么：共享后台服务

这是 v1 到 v2 最本质的一处改动，也是很多人装完发现「行为不对」的根源。

v1 基本是「每个终端一个自己」。v2 改成了 client-server：OpenCode 会为你的用户账号自动发现或启动一个共享的后台服务，所有本地客户端都连到它上面。 会话、配置、权限、工具执行，全归这个服务管。

大多数时候你不用管它，但有几个开关得记一下：

opencode --standalone        # 这个终端用私有服务，不碰共享的那份
opencode --server http://localhost:4096   # 连到指定服务
opencode service status      # 看后台服务现在什么状态
opencode service restart     # 卡住了就重启

如果你希望命令行默认别启动共享服务，可以显式关掉：

opencode service set disabled true

关掉之后 --server 仍然能连指定服务，opencode service start 也能手动把共享服务拉起来。但要注意：Web 端的 opencode pair 依赖共享服务，服务一关配对就不能用了。

如果你从 v1 升上来、发现行为怪怪的，第一步就是 opencode service status 看看是不是有个旧的后台进程在捣鬼。想彻底清干净再重装，可以先用 opencode uninstall --dry-run 预览会删什么，再用 opencode uninstall 执行；想保留配置和会话数据，加 --keep-config --keep-data。

配置：全局还是项目，哪个说了算

OpenCode 用 JSON（也吃带注释的 JSONC）配置，文件叫 opencode.json。两个位置最常用：

全局：~/.config/opencode/opencode.json——放你个人的 provider、默认模型、权限这类跨项目偏好。
项目：项目根目录下的 opencode.json——放这个项目专属的设置，可以放心提交进 Git。

它跟你直觉不太一样的一点是：这些配置文件是「合并」而不是「覆盖」的。 全局设了 autoupdate: true，项目设了 model，最后两个都生效。优先级从低到高大致是：组织下发的远程配置（.well-known/opencode）→ 全局 → OPENCODE_CONFIG 指定的自定义文件 → 项目配置 → .opencode/ 目录 → 内联配置。此外还有一组管理员强制配置（macOS 是 /Library/Application Support/opencode/，Linux 是 /etc/opencode/）优先级最高，用户改不动。

一个 provider 配置长这样，换 baseURL 就能走代理或自建端点：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": { "baseURL": "https://api.anthropic.com/v1" },
      "whitelist": ["claude-sonnet-4-20250514"]
    }
  }
}

whitelist 是只留列出的模型，blacklist 是屏蔽列出的模型，两个按顺序叠加生效。这在 provider 暴露了一堆你根本不会用的模型时很有用，/models 选择器会干净很多。

接上模型

装完还没配凭证时，OpenCode 是连不上任何模型的。两个办法：

在 TUI 里直接跑：

/connect

选一个 provider，粘贴 API Key。凭证会落到 ~/.local/share/opencode/auth.json。命令行等价的做法是：

opencode auth login          # 交互式登录
opencode auth list           # 看已经登录了哪些 provider
opencode auth logout         # 退出某个 provider

OpenCode 底层靠 Models.dev 维护的 provider 列表，官方口径是支持 75+ 家 provider，也支持本地模型（Ollama、LM Studio、llama.cpp 这些都能接）。想确认自己到底能用哪些模型、以及它们在配置里的准确名字，跑：

opencode models              # 列出所有可用模型，格式 provider/model
opencode models anthropic    # 只看某一家
opencode models --refresh    # 强制刷新模型缓存

模型名必须写成 provider/model 的格式，比如 openai/gpt-4.1、opencode/kimi-k2。写错了会报 ProviderModelNotFoundError，别去怀疑网络，先检查这一条。

跑起第一个会话

找个项目目录进去，然后跑起来：

cd /path/to/your/project
opencode

第一次进项目，先让它读一遍代码库：

/init

它会在项目根目录生成一个 AGENTS.md，描述这个项目的结构和编码约定。这个文件建议提交进 Git，之后每次会话它都靠这个快速理解你的项目长什么样，省掉大量重复的上下文说明。

然后是日常用法里我认为最值得先学会的三件事：

用 Tab 键在 Build 和 Plan 两个模式之间切。Plan 模式会禁掉写文件的能力，只让模型给你实施思路——改大功能之前先在 Plan 里过一遍，比直接让它动手稳得多。@ 键可以模糊搜项目里的文件，比手打路径快。改错了就 /undo，可以连着撤好几步，/redo 是反悔回去。想给同事看这段会话，/share 生成一个链接。

不想开全屏界面的话，还有两条：

opencode run "解释一下这个仓库的入口在哪"   # 一次性出结果，适合脚本和 CI
opencode mini                              # 极简交互界面

opencode run 还有个实用技巧——常驻一个服务再挂上去，避免每次冷启动 MCP 服务器：

opencode serve                                             # 一个终端里跑无头服务
opencode run --attach http://localhost:4096 "解释下 async/await"   # 另一个终端里挂上去跑

装完之后

常用命令我列一份给自己备忘用的清单：

opencode --version              # 确认装的是哪个版本
opencode session list           # 看历史会话
opencode stats                  # 看 token 用量和花费
opencode export <sessionID>     # 导出会话 JSON
opencode uninstall --dry-run    # 卸载前先看会删什么

最后一句提醒：跑 opencode 之后如果觉得哪里不对劲，先看日志。 v2 的日志在 ~/.local/share/opencode/log/opencode.log，可以 tail -f 跟着复现。它每条日志都带 run= 和 role= 字段，用 role=server 过滤就能只看到服务侧的会话、provider、插件、权限活动。

常见问题

装完 opencode 命令找不到？ 先确认 PATH 有没有刷新（重开一个终端）。用 npm/Bun/pnpm 装的，八成是 postinstall 脚本被拦了——回到路径三，加上 --trust 或 --allow-build 重装。

提示 ProviderModelNotFoundError？ 模型名格式不对。必须是 provider/model，用 opencode models 查出准确名字再填。

报 ProviderInitError，配置像坏了？ 一般是凭证文件或配置损坏。v1 时代的处理方式是删掉 ~/.local/share/opencode 再重新 /connect。做这一步前先备份。

AI_APICallError 或者模型参数报错？ OpenCode 会按需动态下载 provider 包并缓存。这类兼容性问题清缓存通常能解决：删掉 ~/.cache/opencode，重启让它重新拉最新的 provider 包。

Linux 上复制粘贴没反应？ 缺剪贴板工具。X11 装 xclip 或 xsel，Wayland 装 wl-clipboard。OpenCode 会自动检测 Wayland 并优先用 wl-clipboard。

Windows 上能用包管理器装吗？ 不能。v2 明确不支持 Windows 包管理器，下独立二进制，或者干脆进 WSL——官方也推荐 WSL，性能和兼容性都更好。

我怎么知道自己该装 v1 还是 v2？ 新装一律 v2。还在跑 v1、依赖某个 v1 插件的话，先在隔离环境里迁，确认插件在 v2 上能跑，再换掉生产机器。

写在最后

把 OpenCode 装上本身不难，四行命令的事。真正花了点时间才想明白的是它 v2 的共享服务模型——一旦你接受「会话和权限归一个后台服务管，客户端只是连上去的壳」，很多看起来奇怪的行为就都顺了，桌面版、Web、Docker 这些客户端也才讲得通。

如果你想在装之前先搞清楚它内部那套 Effect TS 的架构是怎么回事，回去看那篇源码拆解；想横向比较它和别的编码 Agent 的设计取舍，可以顺手读这两篇：

Developer Tools on AI博士 万戈